=== useapi.net — universal note === Generated: 2026-11-21 05:55 UTC Authentication (applies to every useapi.net API). Header: Authorization: Bearer user:- Use the COMPLETE token, including the `user:` prefix and the alphanumeric suffix. Do not truncate. Do not URL-encode. A single token authorizes every API under the user's subscription. Service-specific patterns. Identifier names (jobid / taskId / musicId / etc.), job lifecycle, response shapes, webhook semantics, and synchronous-vs-async behavior vary PER API. Use ONLY the service-specific documentation below to determine the correct request body, response shape, polling endpoint, and status values for THIS API. Do not assume conventions from another useapi.net API carry over. For cross-service context (e.g. which APIs expose the same underlying model, billing tiers, model availability matrix), see https://useapi.net/llms.txt === END universal note === useapi.net — third-party APIs for AI services that run on the accounts and plans you already have, since 2023. $15/month subscription gives full access to all APIs listed below. Subscribe: https://useapi.net/docs/subscription Support: https://discord.gg/w28uK3cnmF | https://t.me/use_api === URL: https://useapi.net/docs/account-management === Document URL: https://useapi.net/docs/account-management --- layout: default title: Account Management nav_icon: account description: "useapi.net account endpoints — check subscription and connected service accounts, set a default replyUrl webhook, query usage stats, reset your API token, and read the public daily stats." nav_order: 350 has_children: true has_toc: false permalink: /docs/account-management --- # Account Management These endpoints manage your useapi.net account itself rather than any one AI service. They work the same whichever services you use. Every endpoint except the public daily stats needs your API token, see [Setup useapi.net](/docs/start-here/setup-useapi). ### Endpoints | Endpoint | What it does | |:---|:---| | [GET account](/docs/account-management/get-account) | Returns your subscription status, how many subscriptions you have, the maximum accounts per service, and the total, active and error accounts configured for each AI service. | | [POST account](/docs/account-management/post-account) | Updates your account name and the default `replyUrl` webhook used by every API call that does not set its own. | | [GET account/stats](/docs/account-management/get-account-stats) | Returns your own generations, job ends and failed requests for one service (`bot`), by date or as the last N records, with an optional filter by service account. Data lags 5 to 15 minutes and is kept for 3 months. | | [POST account/token/reset](/docs/account-management/post-account-token-reset) | Emails a confirmation link, valid for 15 minutes, that replaces your API token with a new one. | | [GET stats/daily](/docs/account-management/get-stats-daily) | Returns the anonymized stats we publish every day for the previous UTC day, such as Google Flow captcha providers, Google Flow and PixVerse success rates by model, and Muse usage. No API token needed. | ### When to use them - Run `GET account` before adding service accounts to see how many slots your subscriptions leave, and to spot accounts in an error state. Error accounts still count toward the limit, so delete the ones you will not fix. - Set a default `replyUrl` with `POST account` once if all your jobs report to the same webhook, instead of passing `replyUrl` on every request. - Use `GET account/stats` to audit your own traffic. It breaks your requests down by service account, endpoint and HTTP status code, gives the success rate of your generations, and says for each failure whether it came from the request, the service account, the AI service or useapi.net. - Call `POST account/token/reset` as soon as you think your token was exposed. The old token stops working for almost every request right away. - Check `GET stats/daily` to compare your results with the anonymized results across all customers, for example to choose a captcha provider or a model. To add more accounts per service, buy another [subscription](/docs/subscription). === URL: https://useapi.net/docs/account-management/get-account-stats === Document URL: https://useapi.net/docs/account-management/get-account-stats --- layout: default title: GET account/stats description: "Query your useapi.net usage per service with GET account/stats: generations, job ends and failures, each row with its origin, outcome and error, plus success rate and per-account counts." parent: Account Management nav_order: 250 --- ## Query Usage Statistics January 31, 2026 (November 7, 2026) --- Returns your requests to one API, one row each, with totals and counts per account, model, endpoint and status code. Use it to see what failed, why, and on which account. - Rows show up 5 to 15 minutes after the request. - Rows are kept for 3 months. ##### What is recorded | Recorded | Not recorded | |:---------|:-------------| | Every generation you submit, whatever its outcome | Requests useapi.net answered itself without calling the AI service: validation errors, our limits, an account already marked broken, an unknown job id | | The end of every background job, see [Job ends](#job-ends) | Successful calls that are not generations: lookups, adding an account, cancelling a job | | Any other request the AI service failed or refused | Successful reads, such as polling a job | | A request that failed or crashed inside useapi.net | Reads with a wrong id, such as polling a deleted job | These rules apply since November 1, 2026. Older rows followed earlier rules and have empty `origin`, `outcome` and `error`. > **https://api.useapi.net/v2/account/stats** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters | Parameter | Required | Description | |:----------|:---------|:------------| | `bot` | **Yes** | Bot to query stats for.
Supported: `google-flow`, `dreamina`, `kling`, `runwayml`, `pixverse`, `minimax`, `mureka`, `flowmusic`, `tempolor`, `ltxstudio`, `luma`, `gemini-notebook`, `google-vids`, `muse`, `acemusic` | | `date` | No | Date in `YYYY-MM-DD` format.
Defaults to today if `limit` is not specified. | | `limit` | No | Number of records to return (max: 50000).
If specified, `date` filter is ignored and returns last N records across all dates. | | `offset` | No | Page of a large day, see [Large days](#large-days): `0`, `20000`, `40000` and so on, as `page.next_offset` gives.
Only with a day (`date`, or today), not with `limit`. | | `config` | No | Filter by one service account, written exactly as it appears in the `config` field of the rows, for example an email.
Letters, digits and `_ . @ + : % -` only, URL-encoded (`+` as `%2B`). Anything else answers `400`. | ##### Responses **200** **200 OK** Returns usage statistics for the specified bot. ```json { "bot": "google-flow", "date": "2026-02-13", "total": 2402, "summary": { "from": "2026-02-13T00:00:03.000Z", "to": "2026-02-13T23:58:38.000Z", "time_span": "23 hours 58 minutes", "by_config": { "user1@gmail.com": 670, "user2@gmail.com": 547, "user3@gmail.com": 438, "user4@gmail.com": 321, "user5@gmail.com": 306, "user6@gmail.com": 120 }, "by_code": { "200": 548, "201": 796, "400": 130, "403": 684, "429": 239, "500": 3, "503": 2 }, "by_endpoint": { "post-images": 1334, "post-videos": 1046, "post-videos-upscale": 22 }, "by_status": { "Created": 796, "OK": 548, "Forbidden": 684, "Too Many Requests": 239, "Bad Request": 130, "Internal Server Error": 3, "Service Unavailable": 2 }, "success_rate": "56.0%", "model_refusals": 0, "account_refusals": 0, "avg_msec": 17759, "by_model": { "veo-3.1-lite-low-priority": 1032, "nano-banana-pro": 702, "imagen-4": 449, "nano-banana": 181, "veo-3.1-fast": 14 }, "by_captcha_provider": { "CapSolver": 4856 }, "avg_captcha_retry": 2, "by_tier": { "PAYGATE_TIER_TWO": 1684, "PAYGATE_TIER_ONE": 612, "PAYGATE_TIER_NOT_PAID": 106 }, "by_sku": { "WS_ULTRA": 1430, "G1_TIER2": 254, "G1_TIER1": 612, "G1_FREEMIUM": 106 }, "lookup": { "tiers": { "PAYGATE_TIER_TWO": "Ultra $199", "PAYGATE_TIER_ONE": "Pro", "PAYGATE_TIER_NOT_PAID": "Free" }, "skus": { "WS_ULTRA": "Workspace Ultra", "G1_TIER2": "Ultra $199", "G1_TIER1": "Pro", "G1_FREEMIUM": "Free" } } }, "data": [ { "timestamp": "2026-02-13T10:30:00.000Z", "jobid": "20260213103000-user:123-bot:google-flow", "config": "user1@gmail.com", "endpoint": "post-images", "status": "OK", "func": "v1-google-flow-images", "code": 200, "msec": 5432, "outcome": "ok", "error": "", "origin": "submit", "model": "imagen-4", "captchaProviders": "CapSolver", "captchaRetry": 1, "tier": "PAYGATE_TIER_TWO", "sku": "WS_ULTRA", "backend": "flow", "bytes": 0, "reason": "", "sampleInterval": 1 } ] } ``` The `summary` object is left out when there are no rows. **400** **400 Bad Request** Missing or invalid parameters, for example a `config` that is not a plain account name. ```json { "error": "" } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "Unauthorized" } ``` ##### Reading a row Three fields say what a row is. They are empty on rows written before November 1, 2026. | `origin` | Why the row exists | |:---------|:-------------------| | `submit` | A generation you submitted (for `google-flow`, also a file upload) | | `finished` | The end of a background job, see [Job ends](#job-ends) | | `refused` | Another request that failed | | `read` | A `GET` that failed | | `crash` | A request that crashed inside useapi.net | | `outcome` | What happened | Typical codes | |:----------|:--------------|:--------------| | `ok` | It worked | `2xx` | | `customer` | A problem with the request or its content | `400`, `404`, `422` (content refused) | | `account` | A problem with the service account | `401`, `402`, `403`, `429`, `596` | | `vendor` | The AI service failed | `5xx` after the service was called, or a failure inside a `2xx` answer | | `ours` | useapi.net failed | a crash, or a `5xx` before the service was called | `error` is the error text, written the same way every time so you can group by it: lowercase, with URLs, emails, ids and numbers masked (numbers become `N`), at most 120 characters. It is empty on success. ##### Totals - `total`, `success_rate` and `avg_msec` count submitted work only: rows with `origin` `submit`, plus older rows. - Other failed requests (`refused`, `read`, `crash`) are in `data` and the `by_` counts, but not in those three figures. - Job ends have their own figures in `summary.jobs`, see below. - An MCP tool call shows as the REST request the tool makes. Rows with endpoint `mcp`, written until October 31, 2026, repeated those requests and are left out of `total`. On busy days the stats store keeps a sample of the rows from the busiest API tokens rather than every row. Each row's `sampleInterval` says how many it stands for. It is `1` for almost every customer and higher only for the busiest ones at peak hours. `total` and every count, rate and average in `summary` already weight each row by its `sampleInterval`, so they reflect all of your . When you count rows in `data` yourself, add up `sampleInterval` rather than counting rows. `limit` counts stored rows, so `total` can be larger than `limit`. ##### Large days A day with more than 50,000 rows comes in pages of 20,000, newest first. `total` and `summary` always cover the whole day, on every page. The answer then has a `page` object: `offset` (the first row of this page), `size` (rows in `data`), `rows` (rows in the whole day) and `next_offset`. Ask for the next page with `offset` set to `next_offset`, and stop when it is missing. A day of 50,000 rows or fewer returns everything at once, with no `page`, unless you pass an `offset` above 0. For today, rows keep arriving while you page, so a later page can repeat a few rows of the one before. Past days page exactly. On a paged `google-flow` day before September 25, 2026, `summary.model_refusals` counts only the refusals recorded on the rows themselves, so `success_rate` can read slightly lower than on a smaller day. ##### Job ends When a background job ends, a second row is written next to the submit row: - `endpoint` is the submit endpoint plus `-finished`, for example `post-videos-finished` (`video-finished` and `image-finished` for `pixverse`) - `origin` is `finished`, and `status` is the final status - `code` is `200` for a finished result, otherwise the job's error code, for example `422` for a moderated `pixverse` job - `msec` is the time from submit to end (the submit row's `msec` covers only the submit call) Job ends stay out of `total`, `success_rate`, `avg_msec` and the `by_` counts. `summary.jobs` counts them instead: `finished`, `completed` (finished results), `completion_rate` and `avg_msec` (submit to result, completed jobs only). Written for `pixverse` since October 28, 2026 and for the other APIs since November 1, 2026. PixVerse Off-Peak videos have no end row. ##### Model names `model` and `by_model` are filled for `google-flow`, `dreamina`, `kling`, `minimax`, `pixverse`, `luma`, `gemini-notebook`, `google-vids`, `muse`, `flowmusic`, `mureka` and `acemusic`. Usually it is the AI model, such as `veo-3.1-fast`. Some requests use their own names: | API | `model` | Rows | |:----|:--------|:-----| | `google-flow` | `agent` | [Agent](/docs/api-google-flow-v1/agent) turns, their end rows (`completed`, `waiting_approval` or `failed`), and agent requests that failed | | | `agent-approval` | An approval answered | | | `agent-stream` | A chat stream that failed | | | `mcp` | A crash inside the [MCP server](/docs/api-google-flow-v1/mcp) | | `gemini-notebook` | the Studio action, for example `video:cinematic` or `quiz` | Studio work. Empty on chat and sources | | `google-vids` | `video:text`, `video:image`, `video:ingredients`, `video:extend`, `video:upscale`, `video:edit`, `image`, `avatar:image`, `avatar:appearance` | What the request made. Empty on failed uploads | | `muse` | `muse-image`, `muse-video` | Generations and their end rows | | | `muse-chat` | Each chat message sent, and other chat requests that failed | | | `muse-chat-approval` | An approval Muse did not take | | | `muse-stream` | A chat stream that failed (status `failed` or `dropped`) | | | `muse-widget` | A widget the API can only pass through as `data` (status is the widget kind) | | | `muse-permissions` | A failed change to the agent's permissions | | | `muse-mcp` | A crash inside the [MCP server](/docs/api-muse-v1/mcp) | | | `sign-in` | A failed sign-in (status `refused` or `failed`), or Meta's security checkpoint on an added account (status `checkpoint`) | | | `quota` | A failed live account read | | `acemusic` | `acemusic-v1`, `acemusic-v1.1`, `ace-step-1.5-xl` | Songs and their end rows. Empty on uploads, scores, lyrics and style | | | `model=;ran=` | A song switched to another model than the one asked for, for example `model=acemusic-v1;ran=acemusic-v1.1` | | | `stems:vocals`, `stems:all` | [Stems](/docs/api-acemusic-v1/post-acemusic-music-stems) | `muse` rows also carry `tier`: the account's Muse plan, for example `HATCH_FREE` (free) or `PRODUCT_TIER_1` (Power). Empty before October 13, 2026. ##### Google Flow fields | Field | Meaning | |:------|:--------| | `captchaProviders` / `by_captcha_provider` | Captcha providers used | | `captchaRetry` / `avg_captcha_retry` | Captcha retries | | `tier` / `by_tier` | Google plan family, for example `PAYGATE_TIER_TWO`. Since May 21, 2026 | | `sku` / `by_sku` | The exact subscription, for example `WS_ULTRA`. Since May 21, 2026 | | `summary.lookup` | Plan names for the `tier` and `sku` values present, for example `WS_ULTRA` → `Workspace Ultra`. Read names from here rather than hard-coding them | | `backend` | `flow` (flow.google.com) or `labs` (the older backend). Since September 14, 2026, empty when the request failed before one was chosen | | `reason` / `by_reason` | Google's reason for refusing, for example `PUBLIC_ERROR_USER_QUOTA_REACHED`. Since September 25, 2026 | | `model_refusals` | Requests refused because the account's plan does not offer the model (`PUBLIC_ERROR_MODEL_ACCESS_DENIED`). They say something about the account, so `success_rate` leaves them out | | `account_refusals` | Requests refused because Google treats the Google account as belonging to someone under 18 (`PUBLIC_ERROR_USER_MINOR`). Google Flow refuses such an account whatever the request, so `success_rate` leaves them out too. Image uploads count from November 7, 2026 | | `bytes` | Size of an uploaded file, `0` on every other row | Rows without a plan (uploads, and rows from before May 21, 2026) count under `"(empty)"` in `by_tier` and `by_sku`. Before September 25, 2026, `model_refusals` are recovered from a sampled log, so a few older ones may still count against `success_rate`. > Invited members of an Ultra $199 family plan cannot use `veo-3.1-lite-low-priority` since September 23, 2026, and those requests count as `model_refusals`. Known `tier` and `sku` values: | Field | Enum value | Label | Plan | |---|---|---|---| | `tier` | `PAYGATE_TIER_NOT_PAID` | Free | Free tier | | `tier` | `PAYGATE_TIER_ONE` | Pro | Google AI Pro | | `tier` | `PAYGATE_TIER_TIER1P5` | Ultra $99 | Google AI Ultra $99/mo | | `tier` | `PAYGATE_TIER_TWO` | Ultra $199 | Google AI Ultra $199/mo | | `sku` | `G1_FREEMIUM` | Free | Google AI consumer Free | | `sku` | `G1_TIER1` | Pro | Google AI consumer Pro | | `sku` | `G1_TIER1P5` | Ultra $99 | Google AI consumer Ultra $99 | | `sku` | `G1_TIER2` | Ultra $199 | Google AI consumer Ultra $199 | | `sku` | `WS_FREEMIUM` | Workspace Free | Google Workspace, no AI add-on | | `sku` | `WS_ULTRA` | Workspace Ultra | Google Workspace + AI Ultra add-on | ##### Google Flow uploads Every upload that reaches Google writes a `post-assets` row (since September 19, 2026). - Uploads can be an account's busiest call. With `limit` they can push generations out of the window, so ask for a `date` without `limit` and filter `data` by `endpoint`. - `bytes` is the size sent to Google, also on refused uploads. There is no summary field: add up `bytes × sampleInterval` over the `post-assets` rows. - Uploads refused before reaching Google (bad token, file too large, every account already upload-limited) write no row. Rows with `code` `200` are the uploads Google accepted. Google limits uploads per account separately from generation. An account at the limit refuses every upload but still generates. The limit clears, so far within about two weeks. Counting `post-assets` rows per `config` shows how much of the allowance an account has used. ##### Model ```typescript // Response structure { bot: string // Bot name date?: string // Date filter applied (YYYY-MM-DD) limit?: number // Limit filter applied config?: string // Config filter applied page?: { // Only for a day of more than 50,000 rows, or an offset above 0 (see Large days) offset: number // First row of this page size: number // Rows in data rows: number // Rows in the whole day next_offset?: number // offset of the next page, missing on the last one } total: number // Generations the returned rows stand for (sum of sampleInterval over rows with origin submit or empty), on a paged day the whole day's; job ends, refused / read / crash rows and mcp rows are left out summary?: { // Aggregated statistics (omitted if no data) from: string // Earliest timestamp (ISO 8601) to: string // Latest timestamp (ISO 8601) time_span: string // Human readable duration (e.g., "2 days 5 hours") by_config: Record // Count per config/account by_code: Record // Count per HTTP status code by_endpoint: Record // Count per endpoint/verb by_status: Record // Count per job status success_rate: string // Percentage of generations with a 2xx code (e.g., "86.7%"); google-flow leaves model_refusals and account_refusals out, and reports "n/a" when every row is one avg_msec: number // Average response time of generations in ms jobs?: { // the job-end rows (endpoint -finished), every API with background jobs finished: number completed: number // finished results completion_rate: string avg_msec: number // submit to finished result, completed jobs only } // the APIs listed under Model names: by_model?: Record // Count per AI model // google-flow only: by_captcha_provider?: Record // Count per captcha provider avg_captcha_retry?: number // Average captcha retries by_reason?: Record // Count per Google refusal reason (google-flow, since 2026-09-25) model_refusals?: number // Requests refused because the account's plan lacks the model; not in success_rate (google-flow) account_refusals?: number // Requests refused because Google treats the account as under 18; not in success_rate (google-flow) by_tier?: Record // Count per Google userPaygateTier (since 2026-05-21). Pre-existing rows bucket under "(empty)". by_sku?: Record // Count per Google sku (since 2026-05-21). Pre-existing rows bucket under "(empty)". lookup?: { // Canonical enum -> human-readable label map for the tier/sku values present here. tiers: Record // e.g. { PAYGATE_TIER_TWO: "Ultra $199" }. Unknown enums map to themselves. skus: Record // e.g. { WS_ULTRA: "Workspace Ultra" }. Unknown enums map to themselves. } } data: Array<{ timestamp: string // ISO 8601 timestamp jobid: string // Job/task identifier config: string // Account/config used (channel for MJ, email/account for others) endpoint: string // API endpoint called status: string // Job status func: string // Function name code: number // HTTP status code msec: number // Duration in milliseconds origin: string // submit | finished | refused | read | crash; '' on rows written before 2026-11-01 outcome: string // ok | customer | account | vendor | ours; '' on rows written before 2026-11-01 error: string // normalised error text, URLs / emails / ids / numbers masked, <= 120 chars; '' on success and older rows // the APIs listed under Model names: model?: string // AI model used for generation // google-flow only: captchaProviders?: string // Captcha providers tried (comma-separated) captchaRetry?: number // Number of captcha retries tier?: string // Google userPaygateTier (PAYGATE_TIER_*). Empty for rows pre-2026-05-21. Resolve to a label via summary.lookup.tiers. sku?: string // Google sku (G1_*/WS_*). Empty for rows pre-2026-05-21. Resolve to a label via summary.lookup.skus. backend?: string // "flow" | "labs" — which Google backend served it. Empty for rows pre-2026-09-14. reason?: string // Google's refusal reason, e.g. "PUBLIC_ERROR_MODEL_ACCESS_DENIED". Empty on success. Before 2026-09-25 only plan refusals are filled in. bytes?: number // Size of an uploaded file. 0 on every row that is not post-assets. sampleInterval: number // How many requests this row stands for, usually 1 (see Totals) }> } ``` ##### Examples **Curl** ``` bash # Today's stats for google-flow curl -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v2/account/stats?bot=google-flow" # Specific date curl -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v2/account/stats?bot=google-flow&date=2026-01-31" # Second page of a large day (page.next_offset of the first page) curl -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v2/account/stats?bot=google-flow&date=2026-01-31&offset=20000" # Last 1000 records curl -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v2/account/stats?bot=kling&limit=1000" # Filter by config curl -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v2/account/stats?bot=runwayml&config=user@email.com" ``` **JavaScript** ``` javascript const token = 'YOUR_API_TOKEN'; const bot = 'google-flow'; const date = '2026-01-31'; const response = await fetch( `https://api.useapi.net/v2/account/stats?bot=${bot}&date=${date}`, { headers: { 'Authorization': `Bearer ${token}` } } ); const stats = await response.json(); console.log(`Total requests: ${stats.total}`); console.log('Stats:', stats.data); ``` **Python** ``` python import requests token = 'YOUR_API_TOKEN' headers = {'Authorization': f'Bearer {token}'} # Today's stats for google-flow response = requests.get( 'https://api.useapi.net/v2/account/stats', params={'bot': 'google-flow'}, headers=headers ) stats = response.json() print(f"Total requests: {stats['total']}") print('Stats:', stats['data']) ``` === URL: https://useapi.net/docs/account-management/get-account === Document URL: https://useapi.net/docs/account-management/get-account --- layout: default title: GET account description: "Retrieve your useapi.net account details and settings — including configured service accounts and the default replyUrl — via GET account in the useapi.net account-management API." parent: Account Management nav_order: 100 --- ## Retrieve useapi.net account information December 2023 (October 17, 2026) --- Use this endpoint to retrieve the list of all configured AI services accounts and current subscription status. Response fields descriptions: * `subscriptionIsActive` indicates your subscription status. * `subscriptions` is the number of purchased useapi.net subscriptions, you can buy more at [Subscription](/docs/subscription). * `maxAccountsPerAPI` is the maximum allowed number of accounts per each AI service based on your current subscriptions. A single useapi.net subscription supports up to three accounts for each AI service. If you need more accounts, you'll need to purchase additional [subscriptions](/docs/subscription). * `sub` indicates the date when subscription was renewed, in YYMMDD format. * `accounts` provides the number of `total`, `active`, and `error` accounts for each configured AI service. If you do not plan on fixing and reusing error accounts, you should delete them, as they count towards the total number of accounts and will consume subscription allocations. * `error` indicates if there are any outstanding issues with an account. * `subscriptionsNeededTotal` appears when a service has more accounts than `maxAccountsPerAPI` allows, and is the number of subscriptions you need to cover them. ### Need more accounts? Each subscription adds 3 accounts on every service: `1 sub = $15 → 2 = $25 → 3 = $35 → 4 = $45` The service where you connect the most accounts sets how many subscriptions you need. For example, 5 Google Flow accounts and 2 Kling accounts need 2 subscriptions.
Subscriptions needed1
Accounts per service3
Monthly cost$15
Use "Subscriptions needed" as the quantity at checkout, or change it later in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo). --- > **https://api.useapi.net/v2/account** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** ```json { "id": 12345, "email": "your@email.com", "created": "2023-07-25T03:02:28.676Z", "name": "Your Name", "subscriptionIsActive": true, "subscriptions": 1, "maxAccountsPerAPI": 3, "accounts": { "MiniMax API": { "total": 3, "active": 3 }, "Runway API": { "total": 1, "active": 1 }, "Google Flow API": { "total": 3, "active": 3 }, "Dreamina API": { "total": 1, "active": 1 } }, "verified": "2023-07-25T03:02:53.252Z", "sub": "250405" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model ```typescript { // TypeScript, all fields are optional id: number; email: string; created: Date; name?: string; subscriptions: number; maxAccountsPerAPI: number; accounts: Record; updated?: Date; verified?: Date; sub?: string; replyUrl?: string; subscriptionsNeededTotal?: number; subscriptionIsActive?: boolean; error?: string; } ``` ##### Examples **Curl** ``` bash curl https://api.useapi.net/v2/account \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = "https://api.useapi.net/v2/account"; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" apiUrl = "https://api.useapi.net/v2/account" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/account-management/get-stats-daily === Document URL: https://useapi.net/docs/account-management/get-stats-daily --- layout: default title: GET stats/daily description: "Browse the daily anonymized useapi.net stats — Google Flow captcha providers, Google Flow and PixVerse success rates by model, Muse best single account — via GET stats/daily, no API token needed." parent: Account Management nav_order: 400 --- ## Daily anonymized stats October 4, 2026 (October 28, 2026) --- Every day we publish anonymized stats for the previous full UTC day. They are also announced in the `#daily-stats` channel of our [Discord server](https://discord.gg/w28uK3cnmF). - [Google Flow](/docs/api-google-flow-v1) Captcha (after 00:03 UTC): each captcha provider's share of jobs, how often its token is accepted on the first try and overall, and how long it takes, for images, videos and audio. - [Google Flow](/docs/api-google-flow-v1) (after 00:18 UTC): success rate, median time and results by model, the best single account per model and Google plan, and results by Google plan, for images and videos. - [PixVerse](/docs/api-pixverse-v2) (after 00:33 UTC): by model, the share of requests PixVerse accepted, the share of jobs that ended with a finished video or image, the median time from submit to the finished file, the results, and the best single account per model, for images and videos. Completion and time start with October 28, 2026. - [Muse](/docs/api-muse-v1) (after 00:48 UTC): the most successful images, videos and chat messages a single account made, with that account's Muse plan, the success rate across all customers and the average job time for images and videos. The stats show shares, rates and times, plus the most successful requests a single anonymous account made per model (for Google Flow, per model and plan). They contain no user or account data. Rows from fewer than 3 customers, and then one more small row, are not shown (the Muse report shows every row). Reports are kept for 90 days. For the same numbers about your own requests, use [GET account/stats](/docs/account-management/get-account-stats) and, for Google Flow captchas, [GET accounts/captcha-stats](/docs/api-google-flow-v1/get-google-flow-accounts-captcha-stats). > **https://api.useapi.net/v1/stats/daily** ##### Request Headers No API token is needed. The stats are public. ##### Query Parameters - `list` optional. Set to `true` to get the available dates and report types instead of a report. - `type` optional, the report: `google-flow-captcha` (default), `google-flow`, `pixverse` or `muse`. - `date` optional, the UTC day in `YYYY-MM-DD` format. Defaults to the latest day available. ##### Responses **200** **200 OK** The report as Markdown (`Content-Type: text/markdown`). The `X-Report-Date` and `X-Report-Type` headers name the day and the report. With `list=true`, a JSON list of what is available, newest day first: ```json { "dates": ["2026-10-03", "2026-10-02"], "types": ["google-flow-captcha", "google-flow", "pixverse", "muse"] } ``` **400** **400 Bad Request** ```json { "error": "date must be YYYY-MM-DD", "code": 400 } ``` **404** **404 Not Found** There is no report of that type for that day, for example a day older than 90 days. ```json { "error": "No google-flow report for 2026-06-01", "code": 404 } ``` ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/stats/daily?list=true" curl "https://api.useapi.net/v1/stats/daily?type=google-flow-captcha&date=2026-10-03" ``` **JavaScript** ``` javascript const res = await fetch("https://api.useapi.net/v1/stats/daily?type=google-flow"); console.log(res.headers.get("X-Report-Date"), await res.text()); ``` **Python** ``` python import requests res = requests.get("https://api.useapi.net/v1/stats/daily", params={"type": "pixverse"}) print(res.headers.get("X-Report-Date"), res.text) ``` ##### View the reports
=== URL: https://useapi.net/docs/account-management/post-account-token-reset === Document URL: https://useapi.net/docs/account-management/post-account-token-reset --- layout: default title: POST account/token/reset description: "Reset your useapi.net API token via POST account/token/reset — a 15-minute email confirmation link, then a new token in place of the old one." parent: Account Management nav_order: 300 --- ## Reset your useapi.net API token October 3, 2026 --- Use this when you think your API token was exposed, or simply want a new one. The reset takes two steps, so a stolen token or a stolen website sign-in alone can never change it: 1. This endpoint emails a confirmation link to your account email. Nothing changes yet. The link is good for 15 minutes. 2. You open the link and click **Reset token** on useapi.net. A new token is issued and we email you the same link as in your welcome email, which now shows the new token. After the reset, the old token is refused for almost every request right away. For a short while it may still: - use the MiniMax image and video endpoints (start, check, cancel or delete generations), for up to 10 minutes - read the status and results of your Mureka and Google Flow jobs, including ones started with the new token, for up to 30 minutes - repeat a read-only request it just made, for up to 1 minute Everything else, including other services, adding accounts and changing settings, is refused right away. You are also signed out of the useapi.net website in every browser, with the same short windows as the old token. Sign in again at [useapi.net/login](/login). Both emails show when and from where the request was made (time, IP address, approximate location and browser or client), so you can tell whether it was you. > **https://api.useapi.net/v2/account/token/reset** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. It works for lapsed subscriptions too, so you can reset the token before you renew. ##### Responses **200** **200 OK** The confirmation link was emailed. Your token has not changed yet. If you ask again within 2 minutes you get the same answer, usually without a second email. Use the link you already have. ```json { "message": "We emailed a confirmation link to you@example.com. Your API token changes only after you open that link and confirm. The link is good for 15 minutes." } ``` **401** **401 Unauthorized** ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **502** **502 Bad Gateway** The confirmation email could not be sent. Nothing changed, try again. ```json { "error": "Could not send the confirmation email, please try again", "code": 502 } ``` ##### Model ```typescript { // TypeScript, all fields are optional message: string error: string code: number } ``` ##### Examples **Curl** ``` bash curl -H "Authorization: Bearer …" \ -X POST https://api.useapi.net/v2/account/token/reset ``` **JavaScript** ``` javascript const token = "API token"; const response = await fetch("https://api.useapi.net/v2/account/token/reset", { method: "POST", headers: { "Authorization": `Bearer ${token}` } }); const result = await response.json(); console.log("response", { response, result }); ``` **Python** ``` python import requests token = "API token" response = requests.post("https://api.useapi.net/v2/account/token/reset", headers={"Authorization": f"Bearer {token}"}) print(response, response.json()) ``` === URL: https://useapi.net/docs/account-management/post-account === Document URL: https://useapi.net/docs/account-management/post-account --- layout: default title: POST account description: "Update your useapi.net account settings, such as the default replyUrl webhook, via POST account in the useapi.net account-management API." parent: Account Management nav_order: 200 --- ## Update useapi.net account information December 2023 (April 7, 2025) --- > **https://api.useapi.net/v2/account** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "name": "User name", "replyUrl": "Default callback URL to be used for all API endpoints, API will call the provided replyUrl once job completed or failed" } ``` - `name` optional, account user name. - `replyUrl` optional, provided value will be used as default value for all API calls unless you choose to override them for individual calls. Place here your callback URL. API will call the provided `replyUrl` once job completed or failed. Maximum length 1024 characters. We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality. ##### Responses **204** **204 No Content** Account was successfully updated. Use [GET account](/docs/account-management/get-account) to retrieve updated account information. **400** **400 Bad Request** ```json { "error": "replyUrl is too long", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST https://api.useapi.net/v2/account \ -d '{"name": "…", "replyUrl": "…"}' ``` **JavaScript** ``` javascript const apiUrl = "https://api.useapi.net/v2/account"; const token = "API token"; const user = "User name"; const replyUrl = "Callback URL"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ user, replyUrl }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests apiUrl = "https://api.useapi.net/v2/account" token = "API token" user = "User name" replyUrl = "Callback URL" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } body = { "user": f"{user}", "replyUrl": f"{replyUrl}" } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/start-here/setup-acemusic === Document URL: https://useapi.net/docs/start-here/setup-acemusic --- layout: default title: Setup ACE Music description: "How to add an ACE Music (acemusic.ai) account to the useapi.net ACE Music API with its email and password, including accounts made with Google or a phone number." parent: Start Here nav_order: 215 permalink: /docs/start-here/setup-acemusic --- # Setup ACE Music November 14, 2026 ## Table of contents Approximately 3 minutes to complete setup steps. --- > This is the setup guide for [ACE Music API](/docs/api-acemusic-v1). An [ACE Music](https://acemusic.ai) account with an email and a password and a [useapi.net subscription](/docs/subscription) are required for the API to work. [ACE Music](https://acemusic.ai) is the song generator from Timedomain, the maker of [ACE Studio](https://acestudio.ai). Every request makes two songs, with vocals or instrumental, from a prompt or from your own style and lyrics, and it covers, remixes, edits and mashes up songs you made or uploaded. The Free plan comes with 20 credits a day, and ACE-Step v1.5 XL songs use no credits on any plan. See [Pricing](/docs/api-acemusic-v1#pricing). The API signs in with the account's email and password, the way you sign in at acemusic.ai, and keeps ACE Music's session from then on. It renews the session by itself and signs in again with the stored password when ACE Music ends it. The password is used only to sign in to ACE Music and is never returned by the API. Each [useapi.net subscription](/docs/subscription) lets you connect 3 ACE Music accounts, up to 100 in total. ### Create an ACE Music account We recommend a dedicated ACE Music account for the API, separate from the one you use in your browser. 1. Open [acemusic.ai](https://acemusic.ai) and click **Sign up**. 2. Enter an email you can read and a password, then sign up. ACE Music emails a 6-digit code: enter it to verify the email. 3. Skip or finish the onboarding. Nothing else needs to be set up. To use ACE Music v1 and v1.1 beyond the Free plan's 20 daily credits, or to download WAV, MIDI and MusicXML files and split stems, subscribe to Creator or Artist on the [pricing page](https://acemusic.ai/pricing/) with that account. ### The email and password the API uses The API signs in exactly the way the [Log in](https://acemusic.ai/login/) page does, so the email and password you add are the ones you type there. Sign in once in your browser to check them: 1. Enter the account's email `1`. 2. Enter its password `2`. 3. Click **Log in** `3`. If ACE Music lets you in, the same email and password will work in [Add the account](#add-the-account) below. 4. No password yet, or forgot it? Use **Forgot password?** `4` to set one by email. Signing in to acemusic.ai in your own browser does not end the API's session. ![ACE Music Log in page: 1 Email, 2 Password, 3 Log in, 4 Forgot password?](https://media.useapi.net/acemusic/2026-11-14-setup/acemusic-setup-login-email-password.jpg) ### Accounts that sign in with Google or a phone number The API needs an email and a password. An account made with Continue with Google or with a phone number has no password yet. Set one on acemusic.ai first, for example with **Forgot password?** `4` in the Log in box (screenshot above): enter the account's email, type the 6-digit code ACE Music sends, then set a new password of 8 to 20 characters with both letters and numbers. Then add the account below with that email and password. Adding such an account before it has a password answers `400` with `ACE Music refused the email or password`. ### Add the account Paste your useapi.net API token and the account's email and password, then click Go. You can also call [POST /accounts](/docs/api-acemusic-v1/post-acemusic-accounts) directly.
The API signs in, checks the session and answers `200` with the account, its plan and the credits left. Adding the same email again with a new password replaces the stored one. ### What to expect - Signing out of acemusic.ai in your own browser does not end the API's session either. - After you change or reset the password on acemusic.ai, the stored one no longer works. Add the account again with the new password. - Each account runs up to 4 requests at a time, which is ACE Music's own limit. Lower it with `maxJobs` if you share the account with your own work on acemusic.ai. ### If the account needs attention When ACE Music refuses the stored email and password, the API pauses the account, emails you once and answers `596` for it, with the reason in `error` on [GET /accounts](/docs/api-acemusic-v1/get-acemusic-accounts). Add the account again with the current password to resume. Temporary problems never pause an account: they answer `503`, and a retry works. === URL: https://useapi.net/docs/api-acemusic-v1/delete-acemusic-accounts-email === Document URL: https://useapi.net/docs/api-acemusic-v1/delete-acemusic-accounts-email --- layout: default title: DELETE accounts/`email` description: "Remove an ACE Music account from the useapi.net ACE Music API with DELETE accounts/email. The stored password and session are deleted, the songs stay on acemusic.ai." parent: ACE Music API nav_order: 130 permalink: /docs/api-acemusic-v1/delete-acemusic-accounts-email --- ## Delete an account November 14, 2026 --- Remove a connected ACE Music account from your useapi.net account. The stored password and session are deleted and the account slot is freed. Nothing is deleted on ACE Music's side: the account's songs and uploads stay in its Library, and you can connect it again at any time with [POST /accounts](/docs/api-acemusic-v1/post-acemusic-accounts). Song and image ids of a removed account stop working until it is connected again, and a job still running on it fails with `404` at its next check. > **https://api.useapi.net/v1/acemusic/accounts/`email`** - `email` is the email of a connected account, URL-encoded in the path. ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **204** **204 No Content** The account was removed. **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **404** **404 Not Found** ```json { "error": "Account example@example.com is not configured", "code": 404 } ``` ##### Examples **Curl** ``` bash curl -X DELETE "https://api.useapi.net/v1/acemusic/accounts/example%40example.com" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const email = "example@example.com"; const response = await fetch(`https://api.useapi.net/v1/acemusic/accounts/${encodeURIComponent(email)}`, { method: "DELETE", headers: { "Authorization": `Bearer ${token}` } }); console.log(response.status); ``` **Python** ``` python import requests from urllib.parse import quote token = "API token" email = "example@example.com" response = requests.delete(f"https://api.useapi.net/v1/acemusic/accounts/{quote(email, safe='')}", headers={"Authorization": f"Bearer {token}"}) print(response.status_code) ``` === URL: https://useapi.net/docs/api-acemusic-v1/delete-acemusic-music-songid === Document URL: https://useapi.net/docs/api-acemusic-v1/delete-acemusic-music-songid --- layout: default title: DELETE music/`songId` description: "Delete an ACE Music song with DELETE music/songId in the useapi.net ACE Music API: it moves to the account's trash on acemusic.ai and leaves the Library and the API." parent: ACE Music API nav_order: 320 permalink: /docs/api-acemusic-v1/delete-acemusic-music-songid --- ## Delete a song November 14, 2026 --- Delete a song from the ACE Music Library of the account that holds it. ACE Music moves it to the account's trash, where it can be restored on acemusic.ai only. Through the API it is gone: its `songId` answers `404`, and so does a job whose songs were all deleted. > **https://api.useapi.net/v1/acemusic/music/`songId`** - `songId` is URL-encoded in the path (it contains `:` and `@`). ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **204** **204 No Content** The song was moved to the account's trash. **400** **400 Bad Request** ```json { "error": "Path parameter songId (not-a-song) is not a valid songId (user:--song:so_…)", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** ```json { "error": "Song user:5678-someone@example.com-song:so_91fd58fded6b4617a47a5726 is not yours", "code": 403 } ``` **404** **404 Not Found** The song is already deleted, or its account is not connected. ```json { "error": "Deleting the song: Not found", "code": 404 } ``` ##### Examples **Curl** ``` bash SONGID="user:1234-example@example.com-song:so_3f9c2a7d81e64b05a9d2c4e7" curl -X DELETE -H "Authorization: Bearer …" \ "https://api.useapi.net/v1/acemusic/music/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$SONGID")" ``` **JavaScript** ``` javascript const token = "API token"; const songId = "user:1234-example@example.com-song:so_3f9c2a7d81e64b05a9d2c4e7"; const response = await fetch(`https://api.useapi.net/v1/acemusic/music/${encodeURIComponent(songId)}`, { method: "DELETE", headers: { "Authorization": `Bearer ${token}` } }); console.log(response.status); ``` **Python** ``` python import requests from urllib.parse import quote token = "API token" songId = "user:1234-example@example.com-song:so_3f9c2a7d81e64b05a9d2c4e7" response = requests.delete(f"https://api.useapi.net/v1/acemusic/music/{quote(songId, safe='')}", headers={"Authorization": f"Bearer {token}"}) print(response.status_code) ``` === URL: https://useapi.net/docs/api-acemusic-v1/get-acemusic-accounts-email === Document URL: https://useapi.net/docs/api-acemusic-v1/get-acemusic-accounts-email --- layout: default title: GET accounts/`email` description: "Read one ACE Music account live with GET accounts/email in the useapi.net ACE Music API: plan, billing cycle, credits left, credit costs and model text limits." parent: ACE Music API nav_order: 120 permalink: /docs/api-acemusic-v1/get-acemusic-accounts-email --- ## Retrieve an ACE Music account November 14, 2026 (November 16, 2026) --- Read one connected account together with what ACE Music reports for it right now: the plan, the billing cycle, the credits left, what each request costs in credits, and the models the account can use with their text limits. Use it to check the balance before a run on ACE Music v1 or v1.1, which cost 4 credits a request. A paused account (its stored password was refused) answers with the stored fields and its `error`, without asking ACE Music. When only ACE Music's live part fails for a moment, the stored fields come back with `liveError`. > **https://api.useapi.net/v1/acemusic/accounts/`email`** - `email` is the email of a connected account, URL-encoded in the path. ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** ```json { "email": "example@example.com", "user_id": "1216554433", "plan": "free", "maxJobs": 4, "added": "2026-11-14T19:17:18.288Z", "health": "OK", "plan_name": "Free", "cycle": "monthly", "credits": 16, "costs": { "song": 4, "stems": { "0": 5, "2": 60 }, "video_minute": 1, "continue": 1 }, "models": [ { "id": "acemusic-v1", "name": "ACE Music v1", "free": false, "limits": { "prompt": 2000, "style": 1000, "lyrics": 5000 } }, { "id": "acemusic-v1.1", "name": "ACE Music v1.1 Preview", "free": false, "limits": { "prompt": 2000, "style": 1000, "lyrics": 5000 } }, { "id": "ace-step-1.5-xl", "name": "ACE-Step v1.5 XL", "free": true, "limits": { "prompt": 2000, "style": 512, "lyrics": 2000 } } ], "online": true } ``` **400** **400 Bad Request** ```json { "error": "Path parameter email (not-an-email) is not a valid email", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **404** **404 Not Found** ```json { "error": "Account example@example.com is not configured", "code": 404 } ``` ##### Model The account as stored, with ACE Music's live plan, credits left, credit prices and models.
The account with its live plan, credits and models, field by field ```typescript { // TypeScript, all fields are optional email: string // the ACE Music account user_id: string // ACE Music's own id of the account plan: string | null // free | creator | artist, live maxJobs: number // requests the account runs at the same time, 1 to 4 added: string // ISO 8601 updated?: string // ISO 8601 error?: string // paused: ACE Music refused the stored password, add the account again health: 'OK' | 'error' // error: ACE Music refused the stored password, see error plan_name?: string | null // Free | Creator | Artist. This and the fields below are ACE Music's live // answer: left out when liveError is set cycle?: string | null // monthly or yearly billing credits?: number | null // credits left. Free plans get 20 a day, Creator 1,000 and Artist 2,500 a month costs?: { // ACE Music's credit prices, live song: number // credits a request (two songs) costs on acemusic-v1 and acemusic-v1.1, 4 stems: Record // credits a stem split with POST /music/stems costs, keyed by ACE Music's own number // for the split: "0" is mode vocals (vocal and instrumental), 5. "2" is mode all // (every stem), 60 video_minute: number // ACE Music's price for video in a prompt, not used by this API continue?: number // ACE Music's price for continuing a song (a feature of acemusic.ai), not used by this API } | null models?: { // the models ACE Music offers, live id: string // the value for `model` name: string // the model's name on acemusic.ai free: boolean // true: 0 credits limits: { // maximum characters of each text on this model prompt: number // characters allowed in prompt (the song idea in your own words) on this model style: number // characters allowed in style (genre, instruments, mood, tempo and vocals) on this model lyrics: number // characters allowed in lyrics on this model, section tags included } }[] online?: boolean // false when ACE Music reports itself offline offlineReason?: string // ACE Music's reason when online is false liveError?: string // the live part failed for a moment: only the stored fields are current } ```
##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/acemusic/accounts/example%40example.com" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const email = "example@example.com"; const response = await fetch(`https://api.useapi.net/v1/acemusic/accounts/${encodeURIComponent(email)}`, { headers: { "Authorization": `Bearer ${token}` } }); console.log(response.status, await response.json()); ``` **Python** ``` python import requests from urllib.parse import quote token = "API token" email = "example@example.com" response = requests.get(f"https://api.useapi.net/v1/acemusic/accounts/{quote(email, safe='')}", headers={"Authorization": f"Bearer {token}"}) print(response.status_code, response.json()) ``` === URL: https://useapi.net/docs/api-acemusic-v1/get-acemusic-accounts === Document URL: https://useapi.net/docs/api-acemusic-v1/get-acemusic-accounts --- layout: default title: GET accounts description: "List every ACE Music account connected to the useapi.net ACE Music API with GET accounts: plan, maxJobs and health, read from storage with no call to ACE Music." parent: ACE Music API nav_order: 110 permalink: /docs/api-acemusic-v1/get-acemusic-accounts --- ## Retrieve ACE Music accounts November 14, 2026 (November 16, 2026) --- List the ACE Music accounts connected with [POST /accounts](/docs/api-acemusic-v1/post-acemusic-accounts), keyed by email. The list is read from storage, with no call to ACE Music, so `plan` is the one last seen. For the live plan and credits left, use [GET /accounts/`email`](/docs/api-acemusic-v1/get-acemusic-accounts-email). An account whose stored password ACE Music refused shows `health: "error"` and the reason in `error`. It takes no requests until you add it again with the current password. > **https://api.useapi.net/v1/acemusic/accounts** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** ```json { "example@example.com": { "email": "example@example.com", "user_id": "1216554433", "plan": "free", "maxJobs": 4, "added": "2026-11-14T19:17:18.288Z", "health": "OK" }, "example2@example.com": { "email": "example2@example.com", "user_id": "1216558877", "plan": "artist", "maxJobs": 4, "added": "2026-11-14T19:19:22.646Z", "updated": "2026-11-14T19:45:11.926Z", "health": "OK" }, "example3@example.com": { "email": "example3@example.com", "user_id": "1216561122", "plan": "creator", "maxJobs": 2, "added": "2026-11-10T08:02:41.007Z", "error": "ACE Music refused the stored email and password. Update the password with POST /accounts to resume using this account", "health": "error" } } ``` No accounts yet: ```json {} ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` ##### Model An object keyed by account email, one entry per ACE Music account with its plan, `maxJobs` and health.
The accounts, keyed by email, field by field ```typescript { // TypeScript, all fields are optional [email: string]: { // one entry per account, keyed by its email email: string // the ACE Music account user_id: string // ACE Music's own id of the account plan: string | null // free | creator | artist, as last seen maxJobs: number // requests the account runs at the same time, 1 to 4 added: string // ISO 8601 updated?: string // ISO 8601, the last re-add or maxJobs change error?: string // ACE Music refused the stored password: add the account again health: 'OK' | 'error' // error: ACE Music refused the stored password, see error } } ```
##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/acemusic/accounts" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const response = await fetch("https://api.useapi.net/v1/acemusic/accounts", { headers: { "Authorization": `Bearer ${token}` } }); console.log(response.status, await response.json()); ``` **Python** ``` python import requests token = "API token" response = requests.get("https://api.useapi.net/v1/acemusic/accounts", headers={"Authorization": f"Bearer {token}"}) print(response.status_code, response.json()) ``` === URL: https://useapi.net/docs/api-acemusic-v1/get-acemusic-jobs-jobid === Document URL: https://useapi.net/docs/api-acemusic-v1/get-acemusic-jobs-jobid --- layout: default title: GET jobs/`jobid` description: "Poll an ACE Music song or stem-split job with GET jobs/jobid in the useapi.net ACE Music API: status, both songs with mp3 and play links, signed stem tracks, or the error." parent: ACE Music API nav_order: 810 permalink: /docs/api-acemusic-v1/get-acemusic-jobs-jobid --- ## Retrieve a job November 14, 2026 (November 16, 2026) --- Fetch a job by its `jobid`. [POST /music](/docs/api-acemusic-v1/post-acemusic-music) and [POST /music/stems](/docs/api-acemusic-v1/post-acemusic-music-stems) return one. After an async request, or a sync one that answered `202`, poll this endpoint until `status` is `completed` or `failed`. Songs take 20 seconds to about 2 minutes and a stem split about 1.5 minutes, so polling every 10 seconds is enough. A job still running 30 minutes after it started fails with `504` when it is read. ACE Music may still finish it later, and a later read then shows it `completed`. Every read asks ACE Music for the job's songs, so links are always fresh: each song's `playUrl` and the stem track links are read again. `playUrl` is a direct link to the same MP3 for players, valid until `playUrlExpires` (about an hour): some browsers (Brave) block the redirect behind `audioUrl`. Store `audioUrl`, play `playUrl`. Stem track links are valid for 24 hours from the read. After the job ends, nothing of it is kept on our side: the record is rebuilt from the songs ACE Music keeps in the account's Library. A song deleted since, with [DELETE /music/`songId`](/docs/api-acemusic-v1/delete-acemusic-music-songid) or on acemusic.ai, is listed as `{ songId, taskId, status: "deleted" }` with no links, and the job keeps its status from the song still there. A job none of whose songs ACE Music has any more answers `404`, and any job answers `410` once it is older than 7 days. Instead of polling, pass `replyUrl` (and optionally `replyRef`) with the POST: when the job completes or fails, the API sends one `POST` of this same job record, as JSON, to that URL. See [Model](#model). > **https://api.useapi.net/v1/acemusic/jobs/`jobid`** - `jobid` is URL-encoded in the path (it contains `:` and `@`), for example `j1114201530412583907m-u1234-email%3Aexample%40example.com-task%3Aso_3f9c2a7d81e64b05a9d2c4e7.so_b6e14d0c9a7f4382be51f0a3-bot%3Aacemusic`. ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** A song job (the songs are cut short here, see [POST /music](/docs/api-acemusic-v1/post-acemusic-music) for full songs): ```json { "jobid": "j1114201530412583907m-u1234-email:example@example.com-task:so_3f9c2a7d81e64b05a9d2c4e7.so_b6e14d0c9a7f4382be51f0a3-bot:acemusic", "type": "music", "status": "completed", "email": "example@example.com", "created": "2026-11-14T20:15:30.412Z", "model": "ace-step-1.5-xl", "modelUsed": "ace-step-1.5-xl", "songs": [ { "songId": "user:1234-example@example.com-song:so_3f9c2a7d81e64b05a9d2c4e7", "taskId": "so_3f9c2a7d81e64b05a9d2c4e7", "status": "succeeded", "title": "Farmers Market Sunshine", "model": "ace-step-1.5-xl", "duration": 135.02, "audioUrl": "https://acemusic.ai/data/so_3f9c2a7d81e64b05a9d2c4e7.mp3", "playUrl": "https://….r2.cloudflarestorage.com/acemusic-data-prod/users/…/audio/202611/….mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20261114T201722Z&X-Amz-Expires=3599&…", "playUrlExpires": "2026-11-14T21:17:21.000Z", "coverUrl": "https://acemusic.ai/data/so_3f9c2a7d81e64b05a9d2c4e7-cover.jpg?v=1794685678498", "kind": "original", "score": false }, { "songId": "user:1234-example@example.com-song:so_b6e14d0c9a7f4382be51f0a3", "taskId": "so_b6e14d0c9a7f4382be51f0a3", "status": "succeeded", "title": "Farmers Market Sunshine", "model": "ace-step-1.5-xl", "duration": 135.02, "audioUrl": "https://acemusic.ai/data/so_b6e14d0c9a7f4382be51f0a3.mp3", "playUrl": "https://….r2.cloudflarestorage.com/acemusic-data-prod/users/…/audio/202611/….mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20261114T201723Z&X-Amz-Expires=3599&…", "playUrlExpires": "2026-11-14T21:17:22.000Z", "coverUrl": "https://acemusic.ai/data/so_b6e14d0c9a7f4382be51f0a3-cover.jpg?v=1794685679611", "kind": "original", "score": false } ], "completed": "2026-11-14T20:16:14.205Z", "job_state": "completed", "outputs": [ { "ok": true, "url": "https://acemusic.ai/data/so_3f9c2a7d81e64b05a9d2c4e7.mp3", "url_auth": "none", "mime": "audio/mpeg", "expires_at": null, "ref": "user:1234-example@example.com-song:so_3f9c2a7d81e64b05a9d2c4e7", "thumbnail_url": "https://acemusic.ai/data/so_3f9c2a7d81e64b05a9d2c4e7-cover.jpg?v=1794685678498" }, { "ok": true, "url": "https://acemusic.ai/data/so_b6e14d0c9a7f4382be51f0a3.mp3", "url_auth": "none", "mime": "audio/mpeg", "expires_at": null, "ref": "user:1234-example@example.com-song:so_b6e14d0c9a7f4382be51f0a3", "thumbnail_url": "https://acemusic.ai/data/so_b6e14d0c9a7f4382be51f0a3-cover.jpg?v=1794685679611" } ] } ``` The same job after its second song was deleted with [DELETE /music/`songId`](/docs/api-acemusic-v1/delete-acemusic-music-songid), its song cut short the same way: ```json { "jobid": "j1114201530412583907m-u1234-email:example@example.com-task:so_3f9c2a7d81e64b05a9d2c4e7.so_b6e14d0c9a7f4382be51f0a3-bot:acemusic", "type": "music", "status": "completed", "email": "example@example.com", "created": "2026-11-14T20:15:30.412Z", "model": "ace-step-1.5-xl", "modelUsed": "ace-step-1.5-xl", "songs": [ { "songId": "user:1234-example@example.com-song:so_3f9c2a7d81e64b05a9d2c4e7", "taskId": "so_3f9c2a7d81e64b05a9d2c4e7", "status": "succeeded", "title": "Farmers Market Sunshine", "audioUrl": "https://acemusic.ai/data/so_3f9c2a7d81e64b05a9d2c4e7.mp3", "playUrl": "https://….r2.cloudflarestorage.com/acemusic-data-prod/users/…/audio/202611/….mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20261114T201722Z&X-Amz-Expires=3599&…", "playUrlExpires": "2026-11-14T21:17:21.000Z" }, { "songId": "user:1234-example@example.com-song:so_b6e14d0c9a7f4382be51f0a3", "taskId": "so_b6e14d0c9a7f4382be51f0a3", "status": "deleted" } ], "completed": "2026-11-14T20:16:14.205Z", "job_state": "completed", "outputs": [ { "ok": true, "url": "https://acemusic.ai/data/so_3f9c2a7d81e64b05a9d2c4e7.mp3", "url_auth": "none", "mime": "audio/mpeg", "expires_at": null, "ref": "user:1234-example@example.com-song:so_3f9c2a7d81e64b05a9d2c4e7", "thumbnail_url": null }, { "ok": false, "url": null, "url_auth": "none", "mime": "audio/mpeg", "expires_at": null, "ref": "user:1234-example@example.com-song:so_b6e14d0c9a7f4382be51f0a3", "thumbnail_url": null } ] } ``` A stem split, read a few minutes after it finished. Its track links are signed again on every read, so `expires` and each `expires_at` are 24 hours after the read: ```json { "jobid": "j1114203012775104298s-u1234-email:example@example.com-task:so_3f9c2a7d81e64b05a9d2c4e7.0-bot:acemusic", "type": "stems", "status": "completed", "email": "example@example.com", "created": "2026-11-14T20:30:12.775Z", "stems": { "mode": "vocals", "songId": "user:1234-example@example.com-song:so_3f9c2a7d81e64b05a9d2c4e7", "tracks": [ { "type": "vocal", "url": "https://….r2.cloudflarestorage.com/acemusic-data-prod/users/…/stem/202611/…?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=86400&…", "duration": 135.02 }, { "type": "instrumental", "url": "https://….r2.cloudflarestorage.com/acemusic-data-prod/users/…/stem/202611/…?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=86400&…", "duration": 135.02 } ], "expires": "2026-11-15T20:35:59.230Z" }, "completed": "2026-11-14T20:31:39.143Z", "job_state": "completed", "outputs": [ { "ok": true, "url": "https://….r2.cloudflarestorage.com/acemusic-data-prod/users/…/stem/202611/…?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=86400&…", "url_auth": "none", "mime": "audio/mpeg", "expires_at": "2026-11-15T20:35:59.256Z", "ref": null }, { "ok": true, "url": "https://….r2.cloudflarestorage.com/acemusic-data-prod/users/…/stem/202611/…?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=86400&…", "url_auth": "none", "mime": "audio/mpeg", "expires_at": "2026-11-15T20:35:59.256Z", "ref": null } ] } ``` A job that is still running or that failed answers `200` too: check `status`, and for a failed job `code` and `error`. **400** **400 Bad Request** ```json { "error": "Path parameter jobid (not-a-job) is not a valid ACE Music job id", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The job belongs to another useapi.net user. ```json { "error": "Not your job", "code": 403 } ``` **404** **404 Not Found** ACE Music has none of the job's songs any more (deleted and then emptied from the trash on acemusic.ai), or the job's account was removed. ```json { "error": "Job j1114201530412583907m-u1234-email:example@example.com-task:so_3f9c2a7d81e64b05a9d2c4e7.so_b6e14d0c9a7f4382be51f0a3-bot:acemusic not found: ACE Music has none of its songs", "code": 404 } ``` ```json { "error": "Account example@example.com is not configured: the job cannot be read", "code": 404 } ``` **410** **410 Gone** The job is older than 7 days. Its songs are still in the account's Library: read them with [GET /music](/docs/api-acemusic-v1/get-acemusic-music). ```json { "error": "Job has expired: jobs can be read for 7 days", "code": 410 } ``` ##### Model The job record. [POST /music](/docs/api-acemusic-v1/post-acemusic-music) and [POST /music/stems](/docs/api-acemusic-v1/post-acemusic-music-stems) return it too, and it is the body of the `replyUrl` webhook.
The job record, field by field, and the types it uses (Song, Output, ErrorInfo) ```typescript { // TypeScript, all fields are optional jobid: string // the job's id, `j…-u-email:-task:…-bot:acemusic`. It names the account and // the song or songs the job is about. Read the job with GET /jobs/{jobid} type: 'music' | 'stems' // music: POST /music. stems: POST /music/stems status: 'processing' | 'completed' | 'failed' // processing: ACE Music is making the songs or the split (every job // starts here). completed: done, a song job once at least one of its two songs succeeded. // failed: done without a result, error says why and code is the HTTP status email: string // the ACE Music account the job runs on created: string // ISO 8601 completed?: string // ISO 8601, when the job completed or failed model?: string // music: the model you asked for modelUsed?: string // music: the model that made the songs. It differs from model when the request ran on // another one: a request that must read a song (a mashup, a cover asked on acemusic-v1, a // prompt with more than one reference on ace-step-1.5-xl) runs on acemusic-v1.1, and ACE // Music can also switch a request itself songs?: (Song | DeletedSong)[] // music: the request's two songs, see Song below. A song deleted since, with // DELETE /music/{songId} or on acemusic.ai, is a DeletedSong stems?: { // on a stems job: the split mode: 'vocals' | 'all' // the split you asked for songId: string // the song that was split songStatus?: 'deleted' // the song was deleted, its stems went with it (the job failed with code 404) tracks: { // one per stem type: string // vocals: vocal, instrumental. all: vocals, `backing_vocals`, drums, bass, guitar, // keyboard, strings, synth, woodwinds, fx (the stems ACE Music found) url: string | null // signed mp3 link, valid 24 hours duration?: number // seconds }[] expires?: string // ISO 8601, when the track links stop working (read the job again for fresh ones) } error?: string // status 'failed': why code?: number // status failed: the HTTP status of the failure. 400: ACE Music could not read a // referenced song's melody (read its score with GET /music/score, then run it again). 404: // the account was removed, or a split's song was deleted. 422: ACE Music could not make // the songs or the split. 504: not finished within 30 minutes (ACE Music may still finish // it). 596: the account was signed out replyUrl?: string // the replyUrl you sent: it receives this record when the job ends replyRef?: string // the replyRef you sent, echoed back job_state: 'pending' | 'in_progress' | 'completed' | 'failed' | 'cancelled' | 'expired' | 'unknown' // where the job is, in the same words for every useapi.net API outputs: Output[] // one entry per file the job made, see Output below error_info?: ErrorInfo // only on a failed job: why, and whether to retry, see ErrorInfo below } ``` **`Song`**: each item of `songs` in the job record above. **`DeletedSong`**: an item of `songs` whose song was deleted since, with DELETE `/music/{songId}` or on acemusic.ai. ```typescript { // TypeScript songId: string // the song's id, as it was taskId: string // ACE Music's own id of the song (so_…) status: 'deleted' // deleted with DELETE /music/{songId} or on acemusic.ai } ``` **`Output`**: each item of `outputs` in the job record above. **`ErrorInfo`**: the `error_info` of a failed job above. | `status` | Meaning | |---|---| | `processing` | ACE Music is making the songs or the split. Every job starts here. | | `completed` | Done. A song job is completed when at least one of its two songs succeeded. A song that failed carries its own `error`, and a song deleted since shows `status: "deleted"`. | | `failed` | Done without a result. `error` says why and `code` is the HTTP status. | | `code` | Meaning | |---|---| | `400` | ACE Music could not read the melody of a referenced song (`ref_no_melody`), usually an ACE-Step song with no score yet. Read its score with [GET /music/score](/docs/api-acemusic-v1/get-acemusic-music-score), then run the request again. The songs show `refunded: true`: ACE Music gave the credits back. | | `404` | The account was removed with [DELETE /accounts/`email`](/docs/api-acemusic-v1/delete-acemusic-accounts-email) while the job ran, or a stem split's song was deleted (its stems went with it, `stems.songStatus` is `deleted`). | | `422` | ACE Music could not make the songs or the split, and `error` has ACE Music's reason. A failed song shows `refunded: true` when ACE Music gave its credits back. | | `504` | The job did not finish within 30 minutes. ACE Music may still finish it and has likely charged for it: read the job again later (it shows `completed` once ACE Music finished it) or look for its songs with [GET /music](/docs/api-acemusic-v1/get-acemusic-music) before you run it again. | | `596` | The account was signed out while the job ran: ACE Music refused the stored password. ACE Music may still finish the job. Update the password with [POST /accounts](/docs/api-acemusic-v1/post-acemusic-accounts), then read the job again. | The `replyUrl` webhook is one `POST` with `Content-Type: application/json` and this record as the body, sent once when the job completes or fails (a 10-second timeout, no retries, redirects are not followed). Use `replyRef` to match the callback to your own records.
##### Examples **Curl** ``` bash JOBID="j1114201530412583907m-u1234-email:example@example.com-task:so_3f9c2a7d81e64b05a9d2c4e7.so_b6e14d0c9a7f4382be51f0a3-bot:acemusic" curl -H "Authorization: Bearer …" \ "https://api.useapi.net/v1/acemusic/jobs/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$JOBID")" ``` **JavaScript** ``` javascript const token = "API token"; const jobid = "j1114201530412583907m-u1234-email:example@example.com-task:so_3f9c2a7d81e64b05a9d2c4e7.so_b6e14d0c9a7f4382be51f0a3-bot:acemusic"; const apiUrl = `https://api.useapi.net/v1/acemusic/jobs/${encodeURIComponent(jobid)}`; let job; do { await new Promise(resolve => setTimeout(resolve, 10000)); const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}` } }); job = await response.json(); console.log(job.status); } while (job.status === "processing"); console.log("job", job); ``` **Python** ``` python import requests, time, urllib.parse token = "API token" jobid = "j1114201530412583907m-u1234-email:example@example.com-task:so_3f9c2a7d81e64b05a9d2c4e7.so_b6e14d0c9a7f4382be51f0a3-bot:acemusic" apiUrl = "https://api.useapi.net/v1/acemusic/jobs/" + urllib.parse.quote(jobid, safe="") headers = {"Authorization": f"Bearer {token}"} while True: time.sleep(10) job = requests.get(apiUrl, headers=headers).json() print(job.get("status")) if job.get("status") != "processing": break print(job) ``` === URL: https://useapi.net/docs/api-acemusic-v1/get-acemusic-jobs === Document URL: https://useapi.net/docs/api-acemusic-v1/get-acemusic-jobs --- layout: default title: GET jobs description: "List the ACE Music song and stem-split jobs running now with GET jobs in the useapi.net ACE Music API: jobid, account, model and start time, to see why you got 429." parent: ACE Music API nav_order: 800 permalink: /docs/api-acemusic-v1/get-acemusic-jobs --- ## Retrieve running jobs November 14, 2026 (November 16, 2026) --- List the song and stem-split jobs that are running now on all your ACE Music accounts. A job leaves the list as soon as it ends: read finished jobs with [GET /jobs/`jobid`](/docs/api-acemusic-v1/get-acemusic-jobs-jobid) and their songs with [GET /music](/docs/api-acemusic-v1/get-acemusic-music). Each account runs up to its `maxJobs` requests at a time (default `4`). Count the jobs per `email` here to see which accounts are full when [POST /music](/docs/api-acemusic-v1/post-acemusic-music) answers `429`. > **https://api.useapi.net/v1/acemusic/jobs** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** ```json { "jobs": [ { "jobid": "j1114202212045711826m-u1234-email:example@example.com-task:so_8c1d4f7a2b9e4c06a3f5d7e1.so_e2a7b9c4d6f84a1b95c3e0d8-bot:acemusic", "type": "music", "status": "processing", "email": "example@example.com", "created": "2026-11-14T20:22:12.045Z", "model": "acemusic-v1", "modelUsed": "acemusic-v1", "replyUrl": "https://your-domain.com/webhook", "replyRef": "lofi-1", "job_state": "in_progress", "outputs": [] }, { "jobid": "j1114202301338470152s-u1234-email:example2@example.com-task:so_5a0e3c8b1d7f4e92a6c4b8d0.2-bot:acemusic", "type": "stems", "status": "processing", "email": "example2@example.com", "created": "2026-11-14T20:23:01.338Z", "stemsMode": "all", "job_state": "in_progress", "outputs": [] } ] } ``` Nothing running: ```json { "jobs": [] } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` ##### Model Your running jobs, newest first, each with the `jobid` to read with [GET /jobs/`jobid`](/docs/api-acemusic-v1/get-acemusic-jobs-jobid).
The running jobs, field by field ```typescript { // TypeScript, all fields are optional jobs: { // the running jobs of your token, newest first jobid: string // read it with GET /jobs/{jobid} type: 'music' | 'stems' // music: POST /music. stems: POST /music/stems status: 'processing' // only running jobs are listed email: string // the account the job runs on created: string // ISO 8601 model?: string // music: the model asked for modelUsed?: string // music: the model that runs stemsMode?: 'vocals' | 'all' // on a stems job: the split asked for replyUrl?: string // the replyUrl you sent replyRef?: string // the replyRef you sent job_state: 'in_progress' // where the job is, in the same words for every useapi.net API outputs: [] // no files yet: the job is running }[] } ```
##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/acemusic/jobs" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const response = await fetch("https://api.useapi.net/v1/acemusic/jobs", { headers: { "Authorization": `Bearer ${token}` } }); console.log(response.status, await response.json()); ``` **Python** ``` python import requests token = "API token" response = requests.get("https://api.useapi.net/v1/acemusic/jobs", headers={"Authorization": f"Bearer {token}"}) print(response.status_code, response.json()) ``` === URL: https://useapi.net/docs/api-acemusic-v1/get-acemusic-music-download === Document URL: https://useapi.net/docs/api-acemusic-v1/get-acemusic-music-download --- layout: default title: GET music/download description: "Download an ACE Music song with GET music/download in the useapi.net ACE Music API: the public mp3 link, a signed WAV link, or MIDI and MusicXML files on paid plans." parent: ACE Music API nav_order: 330 permalink: /docs/api-acemusic-v1/get-acemusic-music-download --- ## Download a song November 14, 2026 (November 16, 2026) --- Get a finished song as MP3, WAV, MIDI or MusicXML. | `format` | Plans | What comes back | |---|---|---| | `mp3` (default) | every plan | JSON with the song's public mp3 link, the same as its `audioUrl`, and `playUrl`, the same mp3 as a direct link for players until `playUrlExpires`. For a file uploaded with [POST /files](/docs/api-acemusic-v1/post-acemusic-files), its own audio in the format it was uploaded in, as a signed link valid for 24 hours | | `wav` | Creator, Artist | JSON with a signed link valid for 24 hours. Not for `ace-step-1.5-xl` songs, which ACE Music makes as MP3 only | | `midi` | Creator, Artist | The `.mid` file itself, `audio/midi` | | `musicxml` | Creator, Artist | The MusicXML score itself, `application/vnd.recordare.musicxml+xml` | For `mp3`, `playUrl` is a direct link to the same MP3 for players, valid until `playUrlExpires` (about an hour): some browsers (Brave) block the redirect behind `audioUrl`. Store `audioUrl`, play `playUrl`. ACE Music makes WAV, MIDI and MusicXML on the first request for a song. The API waits up to a minute for it, then answers `202`: call again a minute later. For the score as ABC notation, use [GET /music/score](/docs/api-acemusic-v1/get-acemusic-music-score). > **https://api.useapi.net/v1/acemusic/music/download?songId=`songId`&format=`format`** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `songId` is **required**, a finished song's `songId` (`user:--song:so_…`), URL-encoded. - `format` is optional. Supported values: `mp3` (default), `wav`, `midi`, `musicxml`. ##### Responses **200** **200 OK** The file's link as JSON for `mp3` and `wav`, or the file itself for `midi` and `musicxml`. With `format: mp3` (the default) on a made song: ```json { "songId": "user:1234-example@example.com-song:so_3f9c2a7d81e64b05a9d2c4e7", "format": "mp3", "url": "https://acemusic.ai/data/so_3f9c2a7d81e64b05a9d2c4e7.mp3", "playUrl": "https://….r2.cloudflarestorage.com/acemusic-data-prod/users/…/audio/202611/….mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20261114T204512Z&X-Amz-Expires=3599&…", "playUrlExpires": "2026-11-14T21:45:11.000Z", "fileName": "Farmers Market Sunshine.mp3" } ``` `wav`, and `mp3` of an uploaded file: ```json { "songId": "user:1234-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7", "format": "wav", "url": "https://….r2.cloudflarestorage.com/acemusic-data-prod/users/…/audio/202611/….wav?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=86400&…", "fileName": "Orchestral Morning.wav", "expires": "2026-11-15T20:07:29.242Z" } ``` `midi` and `musicxml` answer with the file itself, with `Content-Disposition: attachment; filename=".mid"` (or `.musicxml`). **202** **202 Accepted** ACE Music is still making the file. Call again in a minute. ```json { "songId": "user:1234-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7", "format": "midi", "status": "processing", "message": "ACE Music is still making the midi: call again in a minute" } ``` **400** **400 Bad Request** ```json { "error": "ace-step-1.5-xl songs are made lossy: no WAV (use mp3)", "code": 400 } ``` ```json { "error": "Parameter format (flac) valid values: mp3,wav,midi,musicxml", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** WAV, MIDI and MusicXML need a paid ACE Music plan, or the song belongs to another useapi.net user. ```json { "error": "Downloading the wav needs a paid ACE Music plan (the account is on free): Downloads come with a paid plan", "code": 403 } ``` **404** **404 Not Found** ```json { "error": "Song user:1234-example@example.com-song:so_3f9c2a7d81e64b05a9d2c4e7 not found (deleted on acemusic.ai?)", "code": 404 } ``` **409** **409 Conflict** The song is not finished, or it failed. ```json { "error": "Song user:1234-example@example.com-song:so_8c1d4f7a2b9e4c06a3f5d7e1 is running: nothing to download yet", "code": 409 } ``` **503** **503 Service Unavailable** ACE Music is busy, did not answer in time, could not be reached, answered with a server error, or the session is being renewed. Nothing was charged: retry after the `Retry-After` header. ```json { "error": "Downloading the wav: ACE Music did not answer within 30 s, please retry shortly", "code": 503 } ``` ##### Model A link to the song in the format you asked for, or a `202` answer while ACE Music is still making the file. <details markdown="block" class="model-details"> <summary>The download link, field by field</summary> ```typescript { // TypeScript, all fields are optional songId: string // the song you asked for format: 'mp3' | 'wav' | 'midi' | 'musicxml' // the format you asked for url?: string // mp3 of a made song: the public link, the same as audioUrl. mp3 of a file uploaded // with POST /files: its own audio, in the format it was uploaded in, as a signed link. // wav, and a midi that ACE Music redirects: a signed link. Not on 202 playUrl?: string | null // mp3 of a made song: the same mp3 as a direct link for players, valid until // playUrlExpires (about an hour). null when the link could not be read playUrlExpires?: string | null // ISO 8601, when playUrl stops working fileName?: string // the song's title with the file's extension. Not on 202 expires?: string // ISO 8601, when a signed link stops working (24 hours) status?: 'processing' // only on 202: ACE Music is still making the file message?: string // only on 202: which file is still being made, and to call again in a minute } ``` </details> ##### Examples **Curl** ``` bash SONGID="user:1234-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7" curl -H "Authorization: Bearer …" -o song.mid \ "https://api.useapi.net/v1/acemusic/music/download?format=midi&songId=$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$SONGID")" ``` **JavaScript** ``` javascript const token = "API token"; const songId = "user:1234-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7"; const params = new URLSearchParams({ songId, format: "wav" }); const response = await fetch(`https://api.useapi.net/v1/acemusic/music/download?${params}`, { headers: { "Authorization": `Bearer ${token}` } }); const result = await response.json(); console.log(response.status, result.url, result.expires); ``` **Python** ``` python import requests token = "API token" params = {"songId": "user:1234-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7", "format": "musicxml"} response = requests.get("https://api.useapi.net/v1/acemusic/music/download", headers={"Authorization": f"Bearer {token}"}, params=params) if response.status_code == 200 and "json" not in response.headers.get("content-type", ""): with open("song.musicxml", "wb") as f: f.write(response.content) else: print(response.status_code, response.json()) ``` === URL: https://useapi.net/docs/api-acemusic-v1/get-acemusic-music-score === Document URL: https://useapi.net/docs/api-acemusic-v1/get-acemusic-music-score --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> music/score description: "Read an ACE Music song's score with GET music/score in the useapi.net ACE Music API: melody, chords and sections in ABC notation, on every plan including Free." parent: ACE Music API nav_order: 410 permalink: /docs/api-acemusic-v1/get-acemusic-music-score --- ## Retrieve a song's score November 14, 2026 (November 16, 2026) --- Get the score of a finished song in [ABC notation](https://abcnotation.com): the vocal melody, an instrumental line, chords and sections, which any ABC tool turns into sheet music or MIDI. It works on every ACE Music plan, the Free plan included. ACE Music reads the score from the song on the first request and keeps it with the song. ACE Music v1.1 Preview songs come with their score already, because that model writes one before the audio. Reading the score of an ACE-Step v1.5 XL song costs 1 credit the first time, and ACE Music v1 songs cost nothing in our tests. The API waits up to a minute for the reading, then answers `202`: call again a minute later. ACE Music v1.1 follows a song's melody from its score. A cover or mashup on [POST /music](/docs/api-acemusic-v1/post-acemusic-music) reads the score of an ACE Music v1 song that has none by itself, for free. An ACE-Step song is not read automatically: when a cover or mashup of it fails with `ref_no_melody`, call this endpoint on the song first (1 credit), then send the request again. On a paid plan the same score downloads as MusicXML with [GET /music/download](/docs/api-acemusic-v1/get-acemusic-music-download) and `format=musicxml`. > **https://api.useapi.net/v1/acemusic/music/score?songId=`songId`** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `songId` is **required**, a finished song's `songId` (`user:<id>-<email>-song:so_…`), URL-encoded. ##### Responses **200** **200 OK** ```json { "songId": "user:1234-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7", "abc": "X:1\nT:\nM:4/4\nL:1/16\nQ:1/4=142\nV: Vocal clef=treble name=\"Vocal Melody\" snm=\"Vocal\"\nV: Ins clef=treble name=\"Ins Melody\" snm=\"Inst.\"\nK:G\n% intro\nV: Vocal\nz8\"G\"z8|\"G\"z16|\"G\"z16|\"G\"z16|\nV: Ins\nZ|z2GABGDGcGDBGGAG|BGGAGGBGcGGBGGAG|g3a3b2c'3b3g2|\n% verse\nV: Vocal\n\"G\"b8z2a2b2c'2|\"C\"c'8e6d2|\"G\"d16|\"G\"z8g4a4|\n…", "musicxml": "GET /music/download?songId=user%3A1234-example%40example.com-song%3Aso_4e7b2c9d0a5f4183b6d8e2c7&format=musicxml (paid plans)" } ``` **202** **202 Accepted** ACE Music is still reading the score. Call again in a minute. ```json { "songId": "user:1234-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7", "status": "processing", "message": "ACE Music is still reading the score: call again in a minute" } ``` **400** **400 Bad Request** ```json { "error": "Parameter songId is required", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **404** **404 Not Found** The song was deleted, or its account is not connected. **409** **409 Conflict** The song is not finished, or it failed. **412** **412 Precondition Failed** The account has no credit left to read an ACE-Step song's score. **422** **422 Unprocessable Entity** ```json { "error": "ACE Music could not read a score from song user:1234-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7", "code": 422 } ``` **502** **502 Bad Gateway** ACE Music may have started reading the score, and charged its credit, but its answer was lost or unexpected. Call again: a score already read costs nothing. **503** **503 Service Unavailable** ACE Music is busy, could not be reached before the score read was sent, or the session is being renewed. Nothing was charged: retry after the `Retry-After` header. **504** **504 Gateway Timeout** ACE Music did not answer within 30 seconds after the score read was sent: it may have started it and charged its credit. Call again: a score already read costs nothing. ```json { "error": "Reading the score: ACE Music did not answer within 30 s. ACE Music may already have charged for this: check GET /music before retrying", "code": 504 } ``` **596** **596 Account Error** ACE Music refused the stored email and password of the account. Add it again with the current password, see [Setup ACE Music](/docs/start-here/setup-acemusic#if-the-account-needs-attention). ##### Model The song's score in ABC notation, or a `202` answer while ACE Music is still reading it. <details markdown="block" class="model-details"> <summary>The score, field by field</summary> ```typescript { // TypeScript, all fields are optional songId: string // the song you asked for abc?: string // the score in ABC notation: header, a Vocal and an Ins voice, chords in quotes, % sections musicxml?: string // how to get the same score as MusicXML (paid plans) status?: 'processing' // only on 202: ACE Music is still reading the score message?: string // only on 202: the score is still being read, call again in a minute } ``` </details> ##### Examples **Curl** ``` bash SONGID="user:1234-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7" curl -H "Authorization: Bearer …" \ "https://api.useapi.net/v1/acemusic/music/score?songId=$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$SONGID")" ``` **JavaScript** ``` javascript const token = "API token"; const songId = "user:1234-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7"; const response = await fetch(`https://api.useapi.net/v1/acemusic/music/score?${new URLSearchParams({ songId })}`, { headers: { "Authorization": `Bearer ${token}` } }); const result = await response.json(); console.log(response.status, result.abc ?? result.message); ``` **Python** ``` python import requests token = "API token" songId = "user:1234-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7" response = requests.get("https://api.useapi.net/v1/acemusic/music/score", headers={"Authorization": f"Bearer {token}"}, params={"songId": songId}) result = response.json() print(response.status_code, result.get("abc") or result) ``` === URL: https://useapi.net/docs/api-acemusic-v1/get-acemusic-music-songid === Document URL: https://useapi.net/docs/api-acemusic-v1/get-acemusic-music-songid --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> music/`songId` description: "Read one ACE Music song live with GET music/songId in the useapi.net ACE Music API: status, style, lyrics, fresh mp3 and cover links, and its stems as signed links." parent: ACE Music API nav_order: 310 permalink: /docs/api-acemusic-v1/get-acemusic-music-songid --- ## Retrieve a song November 14, 2026 (November 16, 2026) --- Read one song from the ACE Music Library of the account that holds it: its status, title, style, lyrics, length, model, mp3 and cover links, and the stems of any [split](/docs/api-acemusic-v1/post-acemusic-music-stems) made of it, with each track as a signed link valid for 24 hours. Find `songId`s in a finished job, in [GET /music](/docs/api-acemusic-v1/get-acemusic-music) or in the answer of [POST /files](/docs/api-acemusic-v1/post-acemusic-files). The mp3 link of a generated song is public. `playUrl` is a direct link to the same MP3 for players, valid until `playUrlExpires` (about an hour): some browsers (Brave) block the redirect behind `audioUrl`. Store `audioUrl`, play `playUrl`. Each read gives a fresh one. An uploaded audio file has no public `audioUrl`: its `playUrl` is a direct link to your upload, signed for 24 hours (also from [GET /music/download](/docs/api-acemusic-v1/get-acemusic-music-download)). For WAV, MIDI or MusicXML use the same endpoint. > **https://api.useapi.net/v1/acemusic/music/`songId`** - `songId` is URL-encoded in the path (it contains `:` and `@`), for example `user%3A1234-example%40example.com-song%3Aso_3f9c2a7d81e64b05a9d2c4e7`. ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** ```json { "songId": "user:1234-example@example.com-song:so_3f9c2a7d81e64b05a9d2c4e7", "taskId": "so_3f9c2a7d81e64b05a9d2c4e7", "status": "succeeded", "title": "Farmers Market Sunshine", "model": "ace-step-1.5-xl", "style": "Upbeat indie folk, bright cheerful acoustic ukulele strumming, light hand percussion, shaker, warm upright bass, sweet breezy female vocals, sunny acoustic production.", "lyrics": "[verse 1]\nWoven tote bag swinging by my side\nMorning breeze and the sky open wide\n…", "instrumental": false, "duration": 135.02, "audioUrl": "https://acemusic.ai/data/so_3f9c2a7d81e64b05a9d2c4e7.mp3", "playUrl": "https://….r2.cloudflarestorage.com/acemusic-data-prod/users/…/audio/202611/….mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20261114T204512Z&X-Amz-Expires=3599&…", "playUrlExpires": "2026-11-14T21:45:11.000Z", "coverUrl": "https://acemusic.ai/data/so_3f9c2a7d81e64b05a9d2c4e7-cover.jpg?v=1794685678498", "pageUrl": "https://acemusic.ai/song/k4m8q2vz7xpd", "created": "2026-11-14T20:15:30.439Z", "finished": "2026-11-14T20:16:14.205Z", "kind": "original", "score": false, "stems": { "vocals": { "status": "done", "tracks": [ { "type": "vocal", "url": "https://….r2.cloudflarestorage.com/acemusic-data-prod/users/…/stem/202611/…?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=86400&…", "duration": 135.02 }, { "type": "instrumental", "url": "https://….r2.cloudflarestorage.com/acemusic-data-prod/users/…/stem/202611/…?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=86400&…", "duration": 135.02 } ] } } } ``` **400** **400 Bad Request** ```json { "error": "Path parameter songId (not-a-song) is not a valid songId (user:<id>-<email>-song:so_…)", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** ```json { "error": "Song user:5678-someone@example.com-song:so_6b2e8d4a9c1f47e3a0d5b7c2 is not yours", "code": 403 } ``` **404** **404 Not Found** The song was deleted, or its account is not connected. ```json { "error": "Song user:1234-example@example.com-song:so_3f9c2a7d81e64b05a9d2c4e7 not found (deleted on acemusic.ai?)", "code": 404 } ``` ##### Model The song, with its audio links and the signed links of the stems of any split. <details markdown="block" class="model-details"> <summary>The song, field by field, and the type it uses (<code>Split</code>)</summary> ```typescript { // TypeScript, all fields are optional songId: string // user:<id>-<email>-song:so_…, the song's id: use it as a reference, to split, download or delete taskId: string // ACE Music's own id of the song (so_…) status: 'planning' | 'scoring' | 'queued' | 'running' | 'succeeded' | 'failed' | 'interrupted' // ACE Music's progress on the song title: string | null // the song's title (ACE Music writes one for a prompt request) model: string | null // acemusic-v1, acemusic-v1.1 or ace-step-1.5-xl. null for an uploaded file style: string | null // the style the song was made with (ACE Music writes it for a prompt request) lyrics: string | null // [verse] / [chorus] tagged instrumental: boolean | null // true for a song with no vocals duration: number | null // seconds audioUrl: string | null // public mp3 link, https://acemusic.ai/data/<taskId>.mp3, once the song succeeded. // It never changes: store this one. null for an uploaded file: get its audio with // GET /music/download playUrl?: string | null // a direct link to the song's audio for players, valid until playUrlExpires: about an // hour for a made song (the same mp3 as audioUrl), 24 hours for an upload (its own audio, // in the format it was uploaded in). Some browsers (Brave) block the redirect behind // audioUrl: store audioUrl, play playUrl. For about a minute after a song is made it is // audioUrl itself (ACE Music serves the file directly then). In job records, // GET /music/{songId} and an audio upload's POST /files answer, not in GET /music. null // while the song is not finished, or when the link could not be read playUrlExpires?: string | null // ISO 8601, when playUrl stops working: read the job or the song again for a fresh one coverUrl: string | null // cover art (jpg) pageUrl: string | null // the song's page on acemusic.ai, when ACE Music made one created: string | null // ISO 8601 finished: string | null // ISO 8601 kind: 'original' | 'cover' | 'mashup' | 'edit' | 'upload' // how the song was made: original (a prompt or mode // generate), cover (mode cover, and mode remix too), mashup, edit, or upload (a file // sent with POST /files) score: boolean // true when ACE Music already has the song's score (GET /music/score) error?: { // a failed song code?: string // ACE Music's code, e.g. `ref_no_melody`, `song_not_made` message?: string // ACE Music's own words reason?: string // ACE Music's reason, when it gives one } refunded?: boolean // ACE Music gave the credits back for a failed song stems?: { // splits made with POST /music/stems. Their track links are signed (24 hours) on // GET /music/{songId}, null elsewhere vocals?: Split // mode vocals: vocal and instrumental all?: Split // mode all: every stem ACE Music found } upload?: { // an uploaded audio file (POST /files) seconds?: number // its length, counted against the account's upload minutes bpm?: number // the tempo ACE Music read transcription?: string // done once ACE Music has read its lyrics, style and melody } } ``` **`Split`**: each split in `stems` of a `Song` above (`vocals`, `all`). ```typescript { // TypeScript status?: string // ACE Music's progress on the split tracks: { // one per stem type?: string // the stem, e.g. vocals, drums, bass url: string | null // signed mp3 link (24 hours) on GET /music/{songId}, null elsewhere duration?: number // seconds }[] } ``` </details> ##### Examples **Curl** ``` bash SONGID="user:1234-example@example.com-song:so_3f9c2a7d81e64b05a9d2c4e7" curl -H "Authorization: Bearer …" \ "https://api.useapi.net/v1/acemusic/music/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$SONGID")" ``` **JavaScript** ``` javascript const token = "API token"; const songId = "user:1234-example@example.com-song:so_3f9c2a7d81e64b05a9d2c4e7"; const response = await fetch(`https://api.useapi.net/v1/acemusic/music/${encodeURIComponent(songId)}`, { headers: { "Authorization": `Bearer ${token}` } }); console.log(response.status, await response.json()); ``` **Python** ``` python import requests from urllib.parse import quote token = "API token" songId = "user:1234-example@example.com-song:so_3f9c2a7d81e64b05a9d2c4e7" response = requests.get(f"https://api.useapi.net/v1/acemusic/music/{quote(songId, safe='')}", headers={"Authorization": f"Bearer {token}"}) print(response.status_code, response.json()) ``` === URL: https://useapi.net/docs/api-acemusic-v1/get-acemusic-music === Document URL: https://useapi.net/docs/api-acemusic-v1/get-acemusic-music --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> music description: "List an account's ACE Music Library with GET music in the useapi.net ACE Music API: songs and uploads, newest first, with songId and mp3 link, paged by after." parent: ACE Music API nav_order: 300 permalink: /docs/api-acemusic-v1/get-acemusic-music --- ## Retrieve the Library November 14, 2026 (November 16, 2026) --- List the songs in an account's ACE Music Library, newest first: songs made through the API or on acemusic.ai, and audio uploaded with [POST /files](/docs/api-acemusic-v1/post-acemusic-files). Each one has a `songId` for [POST /music](/docs/api-acemusic-v1/post-acemusic-music) references, [stems](/docs/api-acemusic-v1/post-acemusic-music-stems), [downloads](/docs/api-acemusic-v1/get-acemusic-music-download) and [scores](/docs/api-acemusic-v1/get-acemusic-music-score). ACE Music keeps every song until it is deleted, so this is also where to find the songs of a job older than 7 days. Songs in this list carry `audioUrl` but no `playUrl` (it would cost one more call per song): read a song with [GET /music/`songId`](/docs/api-acemusic-v1/get-acemusic-music-songid) for its `playUrl`, the direct link for players. The list is read live from ACE Music, which leaves failed songs out of it. Page through it with `after`: each page returns `next`, the value for the following page, and `null` on the last one. > **https://api.useapi.net/v1/acemusic/music?email=`email`&limit=`limit`&after=`after`** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `email` is optional with one account, and **required** when more than one is configured: the account whose Library to list. - `limit` is optional, the number of songs per page. Range: `1` to `60`. Default: `20`. - `after` is optional, the `next` value of the previous page. ##### Responses **200** **200 OK** ```json { "email": "example@example.com", "songs": [ { "songId": "user:1234-example@example.com-song:so_7d2e9b4c1a8f4e6d93b0c5a1", "taskId": "so_7d2e9b4c1a8f4e6d93b0c5a1", "status": "succeeded", "title": "paper-boat-demo", "model": null, "style": "Gentle indie folk ballad, slow contemplative tempo. Fingerpicked acoustic guitar, warm bass and soft ambient textures, breathy female vocals.", "lyrics": "[verse]\nFold the morning into paper\nSend it down the gutter stream\nSail away, little paper boat\nCarry every quiet dream", "instrumental": false, "duration": 35, "audioUrl": null, "coverUrl": "https://acemusic.ai/data/so_7d2e9b4c1a8f4e6d93b0c5a1-cover.jpg?v=1794686793115", "pageUrl": null, "created": "2026-11-14T20:06:23.708Z", "finished": "2026-11-14T20:06:35.653Z", "kind": "upload", "score": true, "upload": { "seconds": 35, "bpm": 88, "transcription": "done" } }, { "songId": "user:1234-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7", "taskId": "so_4e7b2c9d0a5f4183b6d8e2c7", "status": "succeeded", "title": "Orchestral Morning", "model": "acemusic-v1", "style": "cinematic orchestral, soaring strings, choir, epic drums", "lyrics": "[Verse]\nMorning light on the window pane\nCoffee steam and a quiet lane\n[Chorus]\nHold on, hold on, the day is new\nEvery road leads back to you", "instrumental": false, "duration": 44.71, "audioUrl": "https://acemusic.ai/data/so_4e7b2c9d0a5f4183b6d8e2c7.mp3", "coverUrl": "https://acemusic.ai/data/so_4e7b2c9d0a5f4183b6d8e2c7-cover.jpg?v=1794686500022", "pageUrl": "https://acemusic.ai/song/p6x2d8m4f9qa", "created": "2026-11-14T20:01:32.508Z", "finished": "2026-11-14T20:02:03.716Z", "kind": "original", "score": false } ], "next": "1794686492508~so_4e7b2c9d0a5f4183b6d8e2c7~1794686492508_1431913" } ``` **400** **400 Bad Request** ```json { "error": "Parameter email is required when more than one account is configured", "code": 400 } ``` ```json { "error": "Parameter limit (61) is more than 60", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **404** **404 Not Found** ```json { "error": "Account example@example.com is not configured", "code": 404 } ``` **596** **596 Account Error** ACE Music refused the stored email and password. Add the account again with the current password. ```json { "error": "Account example@example.com: ACE Music refused the stored email and password. Update the password with POST /accounts to resume using this account", "code": 596 } ``` ##### Model One page of the account's Library, newest song first, with the cursor for the next page. <details markdown="block" class="model-details"> <summary>The Library page, field by field, and the types it uses (<code>Song</code>, <code>Split</code>)</summary> ```typescript { // TypeScript, all fields are optional email: string // the account listed songs: Song[] // newest first, see Song below next: string | null // pass as `after` for the next page, null on the last page } ``` **`Song`**: each item of `songs` above. ```typescript { // TypeScript, all fields are optional songId: string // user:<id>-<email>-song:so_…, the song's id: use it as a reference, to split, download or delete taskId: string // ACE Music's own id of the song (so_…) status: 'planning' | 'scoring' | 'queued' | 'running' | 'succeeded' | 'failed' | 'interrupted' // ACE Music's progress on the song title: string | null // the song's title (ACE Music writes one for a prompt request) model: string | null // acemusic-v1, acemusic-v1.1 or ace-step-1.5-xl. null for an uploaded file style: string | null // the style the song was made with (ACE Music writes it for a prompt request) lyrics: string | null // [verse] / [chorus] tagged instrumental: boolean | null // true for a song with no vocals duration: number | null // seconds audioUrl: string | null // public mp3 link, https://acemusic.ai/data/<taskId>.mp3, once the song succeeded. // It never changes: store this one. null for an uploaded file: get its audio with // GET /music/download playUrl?: string | null // a direct link to the song's audio for players, valid until playUrlExpires: about an // hour for a made song (the same mp3 as audioUrl), 24 hours for an upload (its own audio, // in the format it was uploaded in). Some browsers (Brave) block the redirect behind // audioUrl: store audioUrl, play playUrl. For about a minute after a song is made it is // audioUrl itself (ACE Music serves the file directly then). In job records, // GET /music/{songId} and an audio upload's POST /files answer, not in GET /music. null // while the song is not finished, or when the link could not be read playUrlExpires?: string | null // ISO 8601, when playUrl stops working: read the job or the song again for a fresh one coverUrl: string | null // cover art (jpg) pageUrl: string | null // the song's page on acemusic.ai, when ACE Music made one created: string | null // ISO 8601 finished: string | null // ISO 8601 kind: 'original' | 'cover' | 'mashup' | 'edit' | 'upload' // how the song was made: original (a prompt or mode // generate), cover (mode cover, and mode remix too), mashup, edit, or upload (a file // sent with POST /files) score: boolean // true when ACE Music already has the song's score (GET /music/score) error?: { // a failed song code?: string // ACE Music's code, e.g. `ref_no_melody`, `song_not_made` message?: string // ACE Music's own words reason?: string // ACE Music's reason, when it gives one } refunded?: boolean // ACE Music gave the credits back for a failed song stems?: { // splits made with POST /music/stems. Their track links are signed (24 hours) on // GET /music/{songId}, null elsewhere vocals?: Split // mode vocals: vocal and instrumental all?: Split // mode all: every stem ACE Music found } upload?: { // an uploaded audio file (POST /files) seconds?: number // its length, counted against the account's upload minutes bpm?: number // the tempo ACE Music read transcription?: string // done once ACE Music has read its lyrics, style and melody } } ``` **`Split`**: each split in `stems` of a `Song` above (`vocals`, `all`). ```typescript { // TypeScript status?: string // ACE Music's progress on the split tracks: { // one per stem type?: string // the stem, e.g. vocals, drums, bass url: string | null // signed mp3 link (24 hours) on GET /music/{songId}, null elsewhere duration?: number // seconds }[] } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/acemusic/music?email=example%40example.com&limit=20" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const email = "example@example.com"; let after = null; do { const params = new URLSearchParams({ email, limit: "60" }); if (after) params.set("after", after); const page = await (await fetch(`https://api.useapi.net/v1/acemusic/music?${params}`, { headers: { "Authorization": `Bearer ${token}` } })).json(); page.songs.forEach(song => console.log(song.songId, song.title, song.audioUrl)); after = page.next; } while (after); ``` **Python** ``` python import requests token = "API token" params = {"email": "example@example.com", "limit": 60} while True: page = requests.get("https://api.useapi.net/v1/acemusic/music", headers={"Authorization": f"Bearer {token}"}, params=params).json() for song in page["songs"]: print(song["songId"], song["title"], song["audioUrl"]) if not page.get("next"): break params["after"] = page["next"] ``` === URL: https://useapi.net/docs/api-acemusic-v1 === Document URL: https://useapi.net/docs/api-acemusic-v1 --- layout: default title: ACE Music API nav_logo: /assets/images/acemusic.svg seo_title: "ACE Music API: ACE Music v1, v1.1 and ACE-Step Songs, Covers and Stems" description: "Third-party ACE Music API by useapi.net, the only API for ACE Music v1 and v1.1: two songs per request, covers, mashups, stems and scores, and ACE-Step for free." nav_order: 2015 has_children: true permalink: /docs/api-acemusic-v1 --- # <img style="height:1em;vertical-align: middle;" src="/assets/images/acemusic.svg" alt=""> ACE Music API November 14, 2026 This is a [third-party](/docs/legal#affiliation--third-party-services) API for [ACE Music](https://acemusic.ai) by Timedomain. It uses your [ACE Music subscription](https://acemusic.ai/pricing/): Free, Creator $9.90 or Artist $29 a month (as of November 2026). Through a REST API and a hosted MCP server, it makes two songs per request from a prompt or from your own style and lyrics, then covers, remixes, edits, mashes up and splits them into stems. On any ACE Music plan, the Free plan included, an ACE-Step v1.5 XL song uses no credits, against the API of the third-party acestep.io, which needs its $49 a month Studio plan (about 360 songs a month, about $0.14 a song, as of November 2026). ACE Music v1 ranks #1 on [Artificial Analysis' vocal music leaderboard](https://artificialanalysis.ai/music/leaderboard/vocals), ahead of Suno v6. ## Models | Model | What it makes | Notes | |---|---|---| | ACE Music v1<br>`acemusic-v1` | [Songs](/docs/api-acemusic-v1/post-acemusic-music) from a prompt, or from your own style and lyrics, sung or instrumental | The default model. Song length from 30 seconds to 10 minutes with `duration`, WAV downloads on paid plans | | ACE Music v1.1 Preview<br>`acemusic-v1.1` | Songs that follow your songs: [covers and mashups](/docs/api-acemusic-v1/post-acemusic-music#modes) | Writes a score first, then the audio. Requests that must read a song [switch to it](/docs/api-acemusic-v1/post-acemusic-music#model-switching) | | ACE-Step v1.5 XL<br>`ace-step-1.5-xl` | Songs, [remixes, and edits](/docs/api-acemusic-v1/post-acemusic-music#modes) that rewrite part of a song | Open-source model by ACE Studio and StepFun, 0 credits. Tempo, key, meter, 10 to 240 seconds, MP3 only | | Stems | [Vocal and instrumental, or every stem](/docs/api-acemusic-v1/post-acemusic-music-stems) of a song | Drums, bass, guitar, keys, strings, synth and more, as MP3 tracks, on paid plans | | More | [Lyrics](/docs/api-acemusic-v1/post-acemusic-music-lyrics) and [style](/docs/api-acemusic-v1/post-acemusic-music-style) writers, a song's [score](/docs/api-acemusic-v1/get-acemusic-music-score), [MP3, WAV, MIDI and MusicXML](/docs/api-acemusic-v1/get-acemusic-music-download) downloads, [audio and image uploads](/docs/api-acemusic-v1/post-acemusic-files) and your [Library](/docs/api-acemusic-v1/get-acemusic-music) | Uploaded songs and images guide new ones | ## MCP server The hosted [ACE Music MCP server](/docs/api-acemusic-v1/mcp) gives the Claude app, ChatGPT, Claude Code, Cursor, VS Code and other AI assistants 15 tools for songs, covers, remixes, edits, mashups, stems, scores, lyrics and uploads, with your useapi.net API token and nothing to install. ## Pricing What one song costs on each [ACE Music plan](https://acemusic.ai/pricing/) (as of November 2026). Every request makes two songs, and ACE Music charges per request: 4 credits on ACE Music v1 and v1.1, so a song costs 2 credits, its share of the plan's credits. | Model | Free (20 cr/day) | Artist $16.58/m (2,500 cr/mo, billed yearly) | Creator $7.90/m (1,000 cr/mo, billed yearly) | Creator $9.90/m (1,000 cr/mo) | Artist $29/m (2,500 cr/mo) | |---|---|---|---|---|---| | ACE Music v1, v1.1 (a song) | $0 / 2 cr (10 songs/day) | $0.013 / 2 cr (1,250 songs/mo) | $0.016 / 2 cr (500 songs/mo) | $0.020 / 2 cr (500 songs/mo) | $0.023 / 2 cr (1,250 songs/mo) | | Stems (vocal + instrumental) | paid plans | $0.033 / 5 cr | $0.040 / 5 cr | $0.050 / 5 cr | $0.058 / 5 cr | | Stems (every stem) | paid plans | $0.40 / 60 cr | $0.47 / 60 cr | $0.59 / 60 cr | $0.70 / 60 cr | | ACE-Step score (first read) | $0 / 1 cr | $0.007 / 1 cr | $0.008 / 1 cr | $0.010 / 1 cr | $0.012 / 1 cr | | ACE-Step v1.5 XL (a song) | $0 / 0 cr | $0 / 0 cr | $0 / 0 cr | $0 / 0 cr | $0 / 0 cr | - A free ACE Music account makes songs too: ACE-Step v1.5 XL with no credits, and ACE Music v1 and v1.1 from its 20 daily credits, about 10 songs a day. WAV, MIDI and MusicXML downloads and stems need Creator or Artist. - ACE Music grants commercial use rights on Creator and Artist, and on the Free plan only for ACE-Step songs. - A request that must read a song, such as a mashup, runs on ACE Music v1.1 Preview and costs 4 credits even when you asked for ACE-Step, see [Model switching](/docs/api-acemusic-v1/post-acemusic-music#model-switching). [GET /accounts/`email`](/docs/api-acemusic-v1/get-acemusic-accounts-email) shows the credits left. ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. ## Run several ACE Music accounts Each useapi.net subscription connects 3 ACE Music accounts, up to 100 in total. One $15 subscription runs up to 12 song requests at once (3 accounts × 4 each), and every request makes two songs, so 24 songs generate in parallel, on ACE Music v1 or on ACE-Step v1.5 XL, which uses no credits. Song requests don't need `email`: each one goes to a healthy account with a free slot within its `maxJobs`, which starts at 4, ACE Music's own limit of requests running at once, and can be lowered with [POST /accounts](/docs/api-acemusic-v1/post-acemusic-accounts). A request for ACE Music v1 or v1.1 skips an account that ACE Music just reported short of credits, and moves to the next account when one refuses it. When every account is busy you get `429`, so wait and send it again. Pass `email` to run a request on a specific account. Songs, uploads and images stay on the account that made them, so a request that names them runs there. [GET /jobs](/docs/api-acemusic-v1/get-acemusic-jobs) shows the jobs running on every account and [GET /accounts/`email`](/docs/api-acemusic-v1/get-acemusic-accounts-email) its live credit balance. Every request can post its finished record to your webhook with `replyUrl`, or you poll [GET /jobs/`jobid`](/docs/api-acemusic-v1/get-acemusic-jobs-jobid) in `async` mode, so a request that takes up to two minutes needs no open connection. [How useapi.net works](/docs/how-it-works) has tips for keeping your accounts healthy. [Setup ACE Music](/docs/start-here/setup-acemusic) [LLM-friendly API spec](https://useapi.net/assets/aibot/api-acemusic-v1.txt) Feed this to your LLM to build integrations [Claude Code skill](/llm-tools) A drop-in useapi.net skill for Claude Code, and a rule for Cursor [GitHub examples](https://github.com/useapi/acemusic-api) Node.js and Python: songs from prompts and lyrics, covers, mashups, uploads, stems and downloads [Postman collection](https://www.postman.com/useapinet/useapi-net/collection/29112081-fb6c1594-534a-4d6f-9fdd-deea77bec055) (November 14, 2026) [MCP Server](/docs/api-acemusic-v1/mcp) Make songs, covers, stems and scores from Claude Code, Cursor, VS Code and other MCP clients Articles: * [How to Generate AI Songs with the ACE Music API](/docs/articles/ace-music-api-tutorial) {% include lang-switch.html mode="hub" key="ace-music-tutorial" %} * [Suno API Alternative: ACE Music, Mureka, Lyria 3.5, TemPolor and MiniMax](/docs/articles/suno-api-alternative) {% include lang-switch.html mode="hub" key="suno-api-alternative" %} * [Five AI Music APIs on the Same Six Briefs: ACE Music v1, TemPolor v4.8, MiniMax Music-3.0, Lyria 3.5 and Mureka V9.5](/docs/articles/ai-music-flagships-compared) {% include lang-switch.html mode="hub" key="ai-music-flagships" %} Videos on YouTube: * [Five AI music APIs: ACE Music v1, TemPolor v4.8, MiniMax Music-3.0, Lyria 3.5 and Mureka V9.5](https://www.youtube.com/watch?v=MSUGckk4JqU) * [Bleep Boop Bounce: a drum and bass song from one photo with ACE Music v1](https://youtube.com/shorts/z_aOmILvIng) Developer Community: * <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> * <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> * <a href="https://www.reddit.com/r/ACEMusic_AI/"><img style="height:1em;vertical-align: middle;" src="/assets/images/reddit.svg" alt=""> r/ACEMusic_AI on Reddit</a> === URL: https://useapi.net/docs/api-acemusic-v1/mcp === Document URL: https://useapi.net/docs/api-acemusic-v1/mcp --- layout: default title: MCP Server nav_icon: mcp seo_title: "ACE Music MCP Server: Songs, Covers, Stems and Scores for AI Assistants" description: "Connect Claude Code, Cursor, VS Code or any MCP client to the hosted useapi.net ACE Music MCP server: 15 tools for songs, covers, mashups, stems, scores and uploads." parent: ACE Music API nav_order: 50 permalink: /docs/api-acemusic-v1/mcp --- ## ACE Music MCP Server November 14, 2026 --- The useapi.net ACE Music MCP server lets an AI assistant such as the Claude app, ChatGPT, Claude Code, Cursor or VS Code Copilot make music with [ACE Music](https://acemusic.ai) on your own ACE Music accounts. It is a hosted [Model Context Protocol](https://modelcontextprotocol.io) server with 15 tools: make two songs from an idea or from your own style and lyrics on ACE Music v1, v1.1 or the free ACE-Step v1.5 XL, cover, remix, edit and mash up songs, split them into stems, read their score, download WAV, MIDI and MusicXML, write lyrics and styles, and upload audio and images as references. Each tool calls the [ACE Music API](/docs/api-acemusic-v1), so the same rules and limits apply. Nothing needs to be installed or hosted. **Is there an ACE Music MCP server?** Yes. useapi.net, a third-party service not affiliated with ACE Music, hosts one at `https://api.useapi.net/v1/acemusic/mcp` with 15 tools for ACE Music songs, covers, stems and scores, on your own ACE Music account, nothing to install. See [how it compares with ACE Music's own MCP server](#useapinet-vs-ace-musics-own-mcp-server). See all useapi.net MCP servers on [Model Matrix & MCP](/model-matrix#mcp-servers). ## useapi.net vs ACE Music's own MCP server ACE Music también tiene su propio servidor MCP en `https://acemusic.ai/mcp`. Crea canciones de ACE Music v1 y v1.1 a partir del estilo y la letra que escribe tu asistente. El servidor de useapi.net funciona con la misma cuenta de ACE Music y agrega todo lo demás (al 18 de noviembre de 2026): | | MCP de ACE Music de useapi.net | MCP propio de ACE Music | |---|---|---| | ACE-Step v1.5 XL, 0 créditos en todos los planes | Sí | No, solo ACE Music v1 y v1.1 | | Descarga de MP3 en el plan Free | Sí | No, toda descarga requiere un plan de pago | | Covers, remixes, ediciones y mashups | Una llamada para cada uno, a partir de tus canciones | El asistente los arma a partir de una partitura transcrita | | Stems: voz e instrumental, o cada instrumento | Sí | No | | Partituras MusicXML | Sí | No, solo MIDI | | Estilo, letra y título escritos por ACE Music a partir de una idea de una línea | Sí | No, los escribe el asistente | | Varias cuentas de ACE Music en una sola conexión | Sí | Una cuenta por conexión | | Token de API para scripts, n8n y agentes sin interfaz, además de OAuth | Sí | Solo inicio de sesión con OAuth | | Las mismas llamadas por REST, con jobs y webhooks | Sí | No | useapi.net es un servicio de terceros, sin afiliación con ACE Music. ACE Music juga punya MCP server sendiri di `https://acemusic.ai/mcp`. Server itu membuat lagu ACE Music v1 dan v1.1 dari gaya dan lirik yang ditulis asisten Anda. Server useapi.net bekerja di akun ACE Music yang sama dan menambahkan sisanya (per 18 November 2026): | | MCP ACE Music dari useapi.net | MCP milik ACE Music sendiri | |---|---|---| | ACE-Step v1.5 XL, 0 kredit di semua paket | Ya | Tidak, hanya ACE Music v1 dan v1.1 | | Download MP3 di paket Free | Ya | Tidak, setiap download butuh paket berbayar | | Cover, remix, edit, dan mashup | Masing-masing satu panggilan, dari lagu Anda | Dirangkai oleh asisten dari partitur hasil transkripsi | | Stem: vokal dan instrumental, atau setiap instrumen | Ya | Tidak | | Partitur MusicXML | Ya | Tidak, hanya MIDI | | Gaya, lirik, dan judul ditulis ACE Music dari ide satu baris | Ya | Tidak, asisten yang menulisnya | | Beberapa akun ACE Music dalam satu koneksi | Ya | Satu akun per koneksi | | Token API untuk skrip, n8n, dan agen headless, plus OAuth | Ya | Hanya login OAuth | | Panggilan yang sama lewat REST, dengan job dan webhook | Ya | Tidak | useapi.net adalah layanan pihak ketiga dan tidak berafiliasi dengan ACE Music. ACE Music も独自の MCP サーバーを `https://acemusic.ai/mcp` で提供しています。こちらは、アシスタントが書いたスタイルと歌詞から ACE Music v1 と v1.1 の曲を作ります。useapi.net のサーバーは同じ ACE Music アカウントで動き、それ以外のすべてを補います(2026年11月18日時点)。 | | useapi.net の ACE Music MCP | ACE Music 独自の MCP | |---|---|---| | ACE-Step v1.5 XL、どのプランでも0クレジット | 対応 | 非対応、ACE Music v1 と v1.1 のみ | | Free プランでの MP3 ダウンロード | 対応 | 非対応、ダウンロードにはすべて有料プランが必要 | | カバー、リミックス、編集、マッシュアップ | お手持ちの曲から、それぞれ1回の呼び出しで | 書き起こした楽譜をもとにアシスタントが組み立てる | | ステム:ボーカルとインスト、または楽器ごと | 対応 | 非対応 | | MusicXML の楽譜 | 対応 | 非対応、MIDI のみ | | 1行のアイデアから ACE Music がスタイル、歌詞、タイトルを書く | 対応 | 非対応、アシスタントが書く | | 1つの接続で複数の ACE Music アカウント | 対応 | 1接続につき1アカウント | | スクリプト、n8n、ヘッドレスエージェント向けの API トークンと OAuth | 対応 | OAuth サインインのみ | | 同じ呼び出しを REST で、ジョブと Webhook 付きで | 対応 | 非対応 | useapi.net はサードパーティのサービスで、ACE Music とは提携していません。 O ACE Music também tem o próprio servidor MCP em `https://acemusic.ai/mcp`. Ele gera músicas do ACE Music v1 e v1.1 a partir do estilo e da letra que o seu assistente escreve. O servidor da useapi.net funciona na mesma conta do ACE Music e acrescenta todo o resto (em 18 de novembro de 2026): | | MCP do ACE Music da useapi.net | MCP do próprio ACE Music | |---|---|---| | ACE-Step v1.5 XL, 0 créditos em todos os planos | Sim | Não, só ACE Music v1 e v1.1 | | Download de MP3 no plano Free | Sim | Não, todo download exige um plano pago | | Covers, remixes, edições e mashups | Uma chamada para cada, a partir das suas músicas | Montados pelo assistente a partir de uma partitura transcrita | | Stems: vocal e instrumental, ou cada instrumento | Sim | Não | | Partituras MusicXML | Sim | Não, só MIDI | | Estilo, letra e título escritos pelo ACE Music a partir de uma ideia de uma linha | Sim | Não, o assistente escreve | | Várias contas do ACE Music em uma só conexão | Sim | Uma conta por conexão | | Token de API para scripts, n8n e agentes headless, além de OAuth | Sim | Só login com OAuth | | As mesmas chamadas via REST, com jobs e webhooks | Sim | Não | A useapi.net é um serviço de terceiros, sem afiliação com o ACE Music. ACE Music มี MCP server ของตัวเองด้วยที่ `https://acemusic.ai/mcp` ซึ่งสร้างเพลง ACE Music v1 และ v1.1 จากสไตล์และเนื้อเพลงที่ผู้ช่วย AI ของคุณเขียน ส่วน server ของ useapi.net ทำงานบนบัญชี ACE Music เดียวกันและเพิ่มส่วนที่เหลือทั้งหมด (ข้อมูล ณ วันที่ 18 พฤศจิกายน 2026): | | ACE Music MCP ของ useapi.net | MCP ของ ACE Music เอง | |---|---|---| | ACE-Step v1.5 XL ใช้ 0 เครดิตในทุกแพ็กเกจ | ได้ | ไม่ได้ มีแค่ ACE Music v1 และ v1.1 | | ดาวน์โหลด MP3 ในแพ็กเกจ Free | ได้ | ไม่ได้ ทุกการดาวน์โหลดต้องใช้แพ็กเกจเสียเงิน | | คัฟเวอร์ รีมิกซ์ การแก้ไข และแมชอัป | เรียกครั้งเดียวต่ออย่าง จากเพลงของคุณ | ผู้ช่วย AI ประกอบเองจากโน้ตเพลงที่ถอดออกมา | | สเต็ม: เสียงร้องกับดนตรี หรือแยกทุกเครื่องดนตรี | ได้ | ไม่ได้ | | โน้ตเพลง MusicXML | ได้ | ไม่ได้ มีแค่ MIDI | | ACE Music เขียนสไตล์ เนื้อเพลง และชื่อเพลงจากไอเดียบรรทัดเดียว | ได้ | ไม่ได้ ผู้ช่วย AI ต้องเขียนเอง | | หลายบัญชี ACE Music ในการเชื่อมต่อเดียว | ได้ | หนึ่งบัญชีต่อการเชื่อมต่อ | | API token สำหรับสคริปต์ n8n และเอเจนต์ที่ไม่มีหน้าจอ พร้อม OAuth | ได้ | ล็อกอินด้วย OAuth เท่านั้น | | เรียกแบบเดียวกันผ่าน REST พร้อมงานและ webhook | ได้ | ไม่ได้ | useapi.net เป็นบริการของบุคคลที่สาม ไม่มีส่วนเกี่ยวข้องกับ ACE Music ACE Music cũng có MCP server riêng tại `https://acemusic.ai/mcp`. Server này tạo bài hát ACE Music v1 và v1.1 từ phong cách và lời bài hát do trợ lý của bạn viết. Server của useapi.net chạy trên cùng tài khoản ACE Music và bổ sung phần còn lại (tính đến 18 tháng 11 năm 2026): | | MCP ACE Music của useapi.net | MCP riêng của ACE Music | |---|---|---| | ACE-Step v1.5 XL, 0 credit trên mọi gói | Có | Không, chỉ ACE Music v1 và v1.1 | | Tải MP3 trên gói Free | Có | Không, mọi lượt tải đều cần gói trả phí | | Cover, remix, chỉnh sửa và mashup | Mỗi thứ một lệnh gọi, từ bài hát của bạn | Trợ lý tự ghép lại từ bản nhạc được chép ra | | Stem: giọng hát và nhạc nền, hoặc từng nhạc cụ | Có | Không | | Bản nhạc MusicXML | Có | Không, chỉ MIDI | | Phong cách, lời và tên bài do ACE Music viết từ một ý tưởng một dòng | Có | Không, trợ lý tự viết | | Nhiều tài khoản ACE Music trong một kết nối | Có | Một tài khoản cho mỗi kết nối | | API token cho script, n8n và agent chạy không giao diện, cùng với OAuth | Có | Chỉ đăng nhập OAuth | | Cùng các lệnh gọi qua REST, có job và webhook | Có | Không | useapi.net là dịch vụ của bên thứ ba, không liên kết với ACE Music. ACE Music 也在 `https://acemusic.ai/mcp` 运行自己的 MCP 服务器。它根据你的助手写好的风格和歌词生成 ACE Music v1 和 v1.1 歌曲。useapi.net 的服务器使用同一个 ACE Music 账号,并补上其余的一切(截至 2026 年 11 月 18 日): | | useapi.net ACE Music MCP | ACE Music 自己的 MCP | |---|---|---| | ACE-Step v1.5 XL,所有套餐都是 0 积分 | 支持 | 不支持,只有 ACE Music v1 和 v1.1 | | 免费套餐下载 MP3 | 支持 | 不支持,任何下载都需要付费套餐 | | 翻唱、重混、编辑和混搭 | 基于你的歌曲,各一次调用 | 由助手根据转写出的乐谱拼凑完成 | | 分轨:人声和伴奏,或每件乐器 | 支持 | 不支持 | | MusicXML 乐谱 | 支持 | 不支持,只有 MIDI | | 由 ACE Music 根据一句话的想法写出风格、歌词和标题 | 支持 | 不支持,由助手来写 | | 一个连接中使用多个 ACE Music 账号 | 支持 | 每个连接一个账号 | | 用于脚本、n8n 和无界面智能体的 API Token,另有 OAuth | 支持 | 只能 OAuth 登录 | | 通过 REST 进行同样的调用,带任务和 webhook | 支持 | 不支持 | useapi.net 是第三方服务,与 ACE Music 无关联。 ACE Music also runs its own MCP server at `https://acemusic.ai/mcp`. It makes ACE Music v1 and v1.1 songs from the style and lyrics your assistant writes. The useapi.net server works on the same ACE Music account and adds the rest (as of November 18, 2026): | | useapi.net ACE Music MCP | ACE Music's own MCP | |---|---|---| | ACE-Step v1.5 XL, 0 credits on every plan | Yes | No, ACE Music v1 and v1.1 only | | MP3 download on the Free plan | Yes | No, every download needs a paid plan | | Covers, remixes, edits and mashups | One call each, from your songs | Pieced together by the assistant from a transcribed score | | Stems: vocals and instrumental, or every instrument | Yes | No | | MusicXML scores | Yes | No, MIDI only | | Style, lyrics and title written by ACE Music from a one-line idea | Yes | No, the assistant writes them | | Several ACE Music accounts in one connection | Yes | One account per connection | | API token for scripts, n8n and headless agents, plus OAuth | Yes | OAuth sign-in only | | The same calls over REST, with jobs and webhooks | Yes | No | useapi.net is a third-party service, not affiliated with ACE Music. ## Endpoint and authorization ``` https://api.useapi.net/v1/acemusic/mcp ``` - Transport: Streamable HTTP. - Listed in the [official MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers/net.useapi%2Facemusic/versions/latest) as `net.useapi/acemusic`, so MCP clients and directories that read the registry can find it by that name. - Authorization: your useapi.net API token in the `Authorization: Bearer …` header, see [Setup useapi.net](/docs/start-here/setup-useapi). The Claude app and ChatGPT sign in with OAuth instead, see [Use it in the Claude app or ChatGPT](#use-it-in-the-claude-app-or-chatgpt). - You need at least one ACE Music account added with [Setup ACE Music](/docs/start-here/setup-acemusic). Adding and removing accounts is not available over MCP: use [POST /accounts](/docs/api-acemusic-v1/post-acemusic-accounts) or the setup page. ## Setup Replace `YOUR_API_TOKEN` with your useapi.net API token. ### Claude Code ```bash claude mcp add --transport http useapi-acemusic https://api.useapi.net/v1/acemusic/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` ### Cursor In `~/.cursor/mcp.json`: ```json { "mcpServers": { "useapi-acemusic": { "url": "https://api.useapi.net/v1/acemusic/mcp", "headers": { "Authorization": "Bearer YOUR_API_TOKEN" } } } } ``` ### VS Code In `.vscode/mcp.json`: ```json { "servers": { "useapi-acemusic": { "type": "http", "url": "https://api.useapi.net/v1/acemusic/mcp", "headers": { "Authorization": "Bearer YOUR_API_TOKEN" } } } } ``` ### Windsurf and other clients Any client that supports remote MCP servers over HTTP with custom headers works. The usual JSON shape: ```json { "mcpServers": { "useapi-acemusic": { "serverUrl": "https://api.useapi.net/v1/acemusic/mcp", "headers": { "Authorization": "Bearer YOUR_API_TOKEN" } } } } ``` Some clients name the address field `url` instead of `serverUrl`. ### Test it with curl ```bash curl -s https://api.useapi.net/v1/acemusic/mcp \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}' curl -s https://api.useapi.net/v1/acemusic/mcp \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' ``` The first call answers with the server's name `useapi-acemusic` and its instructions for the assistant, the second with the 15 tools. ## Use it in the Claude app or ChatGPT The Claude app ([claude.ai](https://claude.ai) and Claude Desktop) and [ChatGPT](https://chatgpt.com) can add this server as a custom connector. They sign in with OAuth: you give the app the URL, it opens a useapi.net page, and you paste your useapi.net API token there once. Both work on their Free plans. The API-token setups above for Claude Code, Cursor, VS Code and other clients keep working as before. ``` ``` ### Claude app 1. Open Settings → Connectors and click Add custom connector. 2. Enter a name, for example `useapi `, and the URL above, then click Add. 3. Click Connect. Claude opens the useapi.net sign-in page. 4. Paste your useapi.net API token and click Allow. Claude asks before each tool call unless you choose Always allow. The Free plan allows one custom connector. ### ChatGPT 1. Open Plugins, click Add and choose Add custom MCP server. 2. Enter a name and the URL above, and set Authentication to OAuth. 3. Tick ChatGPT's "I understand and want to continue" box, then click Create as a plugin. 4. Click Connect. ChatGPT opens the useapi.net sign-in page. 5. Paste your useapi.net API token and click Allow. ChatGPT asks you to confirm each tool call that creates or changes something. The Free plan works without developer mode (as of October 25, 2026). ### How the sign-in works - Your API token is in your welcome email, see [Setup useapi.net](/docs/start-here/setup-useapi). The useapi.net page links there too. - Each connection is for one MCP server. Connect each server you want to use on its own. - The app gets an access token that lasts 1 hour and renews it on its own. A connection you don't use for 90 days lapses, and you connect again. - [Resetting your API token](/docs/account-management/post-account-token-reset) disconnects every app connected with it. - - Results come back as public links, so they open right in the app. ## Tools Songs, uploads and jobs are named by the ids the tools return, and each id carries its account, so a cover, a split or a download runs on the account that holds the song. Tools that start something new take an optional `email` to pick the account. ### Accounts | Tool | What it does | Main parameters | |---|---|---| | `acemusic_list_accounts` | Lists your accounts with their plan, `maxJobs` and health, as stored. | | | `acemusic_get_account` | Reads one account live: plan, credits left, the models with their text limits, and credit costs. | `email` | | `acemusic_update_account` | Sets `maxJobs`, the requests an account runs at once, 1 to 4. | `email`, `maxJobs` | ### Songs | Tool | What it does | Main parameters | |---|---|---| | `acemusic_create_song` | Makes two songs from an idea, or from your own style and lyrics with a mode: generate, cover, remix, edit or mashup. | `prompt`, `images` or `style`, `lyrics`, `instrumental`, `title`, `mode`, `references`, `model`, the options, `email` | | `acemusic_get_job` | Reads a song or stem-split job, and with `wait: true` waits for it to finish. | `jobid`, `wait` | | `acemusic_list_jobs` | Lists the jobs running now on each account. | | | `acemusic_list_songs` | Lists an account's Library, newest first, page by page. | `email`, `limit`, `after` | | `acemusic_get_song` | Reads one song with fresh links and its stems. | `songId` | | `acemusic_delete_song` | Moves a song to the account's ACE Music trash. Cannot be undone through the API. | `songId` | The parameters match [POST /music](/docs/api-acemusic-v1/post-acemusic-music), including the [options](/docs/api-acemusic-v1/post-acemusic-music#options) and [model switching](/docs/api-acemusic-v1/post-acemusic-music#model-switching). ### Stems, scores and downloads | Tool | What it does | Main parameters | |---|---|---| | `acemusic_split_stems` | Splits a song into vocal and instrumental (5 credits) or every stem (60 credits), on paid plans. | `songId`, `mode` | | `acemusic_get_score` | Returns a song's score in ABC notation. | `songId` | | `acemusic_download_song` | Returns a song's mp3 link with its play link, a signed WAV link (paid plans), or the MIDI or MusicXML download address (paid plans). | `songId`, `format` | ### Writing and uploads | Tool | What it does | Main parameters | |---|---|---| | `acemusic_write_lyrics` | Writes or rewrites lyrics and a title, without making a song. | `prompt`, `style`, `lyrics`, `title`, `model`, `email` | | `acemusic_improve_style` | Improves a style description, or invents one. | `style`, `lyrics`, `model`, `email` | | `acemusic_upload_file` | Uploads audio (MP3, WAV, FLAC, OGG, M4A or AAC, up to 8 minutes) as a Library song to use as a reference, or an image (JPEG, PNG or WebP, up to 10 MB) for a prompt, from a public https URL or sent as `contentBase64`. | `url` or `contentBase64`, `mimeType`, `title`, `email` | A file sent by URL is read into memory first, up to 60 MB (25 MB when its server sends no size). Larger audio goes through [POST /files](/docs/api-acemusic-v1/post-acemusic-files) directly. The full input schema of every tool comes from `tools/list`. ## Long-running work MCP clients usually give up on a tool call after about a minute, so a tool waits up to about 50 seconds: - An ACE-Step request usually takes 20 to 50 seconds, ACE Music v1.1 Preview about 35 to 75 and ACE Music v1 about 80 to 105. If the songs aren't done in time, `acemusic_create_song` returns the `jobid`, and `acemusic_get_job` with `wait: true` picks it up. Ask the assistant to keep checking until it is done. - A stem split takes about a minute and a half, and works the same way. - `acemusic_write_lyrics`, `acemusic_improve_style`, `acemusic_get_score` and `acemusic_download_song` answer within about 55 seconds. When ACE Music is still making a score or a file, call the tool again a minute later. Clients that ask for progress notifications get one about every 10 seconds while a tool waits. Each song comes back with its `songId`, a public mp3 link to keep and a play link (`playUrl`, valid about an hour) to play now: some browsers (Brave) block the redirect behind the mp3 link. A song deleted since shows as deleted. Stem tracks and WAV files come back as signed links that work for 24 hours. MIDI and MusicXML come back as the address of [GET /music/download](/docs/api-acemusic-v1/get-acemusic-music-download), fetched with your API token in the `Authorization` header, or, in an app signed in with OAuth, as a download link that works without sign-in for 1 hour. ## Example prompts - "Make an upbeat synth-pop song about catching the last train home, with ACE-Step." - "Write lyrics about a cat who loves rainy days, then sing them as acoustic indie folk on ACE Music v1." - "Cover my last song as a slow jazz ballad." - "Mash up these two songs into one." - "Split that song into stems and give me the drums." - "Show me the score of the first song." - "How many ACE Music credits are left on my accounts?" ## Limits and notes - The tools use your ACE Music accounts and the same rules as the REST API, such as `maxJobs`. ACE Music v1 and v1.1 requests use 4 of the account's credits, ACE-Step v1.5 XL none, see [Pricing](/docs/api-acemusic-v1#pricing). - A client may send up to 20 JSON-RPC requests in one batch. - If the client sends an `MCP-Protocol-Version` header, it must be one of the supported versions: `2025-11-25`, `2025-06-18`, `2025-03-26` or `2024-11-05`. - Tool calls show in your [usage stats](/docs/account-management/get-account-stats) (`bot=acemusic`) through the REST call each tool makes, the same rows a direct API request writes. === URL: https://useapi.net/docs/api-acemusic-v1/post-acemusic-accounts === Document URL: https://useapi.net/docs/api-acemusic-v1/post-acemusic-accounts --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> accounts description: "Add an ACE Music account to the useapi.net ACE Music API with POST accounts: its email and password, checked by a live sign-in, or change its maxJobs from 1 to 4." parent: ACE Music API nav_order: 100 permalink: /docs/api-acemusic-v1/post-acemusic-accounts --- ## Configure an ACE Music account November 14, 2026 (November 16, 2026) --- Add an [ACE Music](https://acemusic.ai) account with the email and password you sign in with at acemusic.ai. See [Setup ACE Music](/docs/start-here/setup-acemusic) for how to make one, and how to set a password on an account made with Google or a phone number. The API signs in to ACE Music and reads the account before anything is saved, so a wrong email or password answers `400` and stores nothing. The password is stored to sign in again whenever ACE Music ends the session, and it is never returned. Posting an account that is already connected re-adds it: the new password replaces the stored one, and an account paused with an `error` is resumed. This endpoint does two things. To add or re-add an account, post its `email` and `password`. To change only `maxJobs` on an account that is already connected, post `email` and `maxJobs` and leave `password` out: nothing is sent to ACE Music then. Each [useapi.net subscription](/docs/subscription) lets you connect 3 ACE Music accounts, up to 100 in total. > **https://api.useapi.net/v1/acemusic/accounts** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body Add or re-add an account: ```json { "email": "example@example.com", "password": "your-acemusic-password", "maxJobs": 4 } ``` Change `maxJobs` only: ```json { "email": "example@example.com", "maxJobs": 2 } ``` - `email` is **required**, the email the ACE Music account signs in with. - `password` is **required** to add or re-add an account, the account's ACE Music password. Maximum length: `256` characters. - `maxJobs` is optional when adding, and **required** when `password` is left out. It is how many requests the account runs at the same time. Each request makes two songs or one stem split. Range: `1` to `4`. Default: `4`, ACE Music's own limit (it refuses a fifth request running at once). A re-added account keeps its value unless you send a new one. ##### Responses **200** **200 OK** The account is added or re-added. `plan_name` and `credits` come from the sign-in. ```json { "email": "example@example.com", "user_id": "1216554433", "plan": "creator", "maxJobs": 4, "added": "2026-11-14T19:17:18.288Z", "health": "OK", "plan_name": "Creator", "credits": 996 } ``` Only `maxJobs` changed: ```json { "email": "example@example.com", "user_id": "1216554433", "plan": "creator", "maxJobs": 2, "added": "2026-11-14T19:17:18.288Z", "updated": "2026-11-14T19:45:14.605Z", "health": "OK" } ``` **400** **400 Bad Request** ACE Music refused the email or password, or a parameter is invalid. ACE Music's own reason is in parentheses. ```json { "error": "ACE Music refused the email or password (Wrong email or password.). Accounts made with Google or a phone number need a password set on acemusic.ai first", "code": 400 } ``` ```json { "error": "Send password to add or re-add the account, or maxJobs to change its concurrency", "code": 400 } ``` ```json { "error": "Parameter maxJobs (5) is more than 4", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **402** **402 Payment Required** Your useapi.net subscription has expired, or it does not cover another account. Each subscription covers 3 accounts per service. **404** **404 Not Found** `maxJobs` only, for an email that is not connected. ```json { "error": "Account example@example.com is not configured: add it with email and password", "code": 404 } ``` **503** **503 Service Unavailable** ACE Music could not be reached or answered with a server error. Nothing was saved: retry in a few seconds. ##### Model The account as stored, with its plan, `maxJobs`, health and the credits left. <details markdown="block" class="model-details"> <summary>The account, field by field</summary> ```typescript { // TypeScript, all fields are optional email: string // the ACE Music account user_id: string // ACE Music's own id of the account plan: string | null // free | creator | artist maxJobs: number // 1 to 4 added: string // ISO 8601, when the account was first added updated?: string // ISO 8601, the last re-add or maxJobs change health: 'OK' | 'error' // error: ACE Music refused the stored password, see error error?: string // present when ACE Music refused the stored password, see GET /accounts plan_name?: string | null // add or re-add: the plan's name, e.g. Creator credits?: number | null // add or re-add: the credits left } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/acemusic/accounts" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "email": "example@example.com", "password": "your-acemusic-password" }' ``` **JavaScript** ``` javascript const token = "API token"; const response = await fetch("https://api.useapi.net/v1/acemusic/accounts", { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}` }, body: JSON.stringify({ email: "example@example.com", password: "your-acemusic-password" }) }); console.log(response.status, await response.json()); ``` **Python** ``` python import requests token = "API token" response = requests.post( "https://api.useapi.net/v1/acemusic/accounts", headers={"Authorization": f"Bearer {token}"}, json={"email": "example@example.com", "password": "your-acemusic-password"} ) print(response.status_code, response.json()) ``` === URL: https://useapi.net/docs/api-acemusic-v1/post-acemusic-files === Document URL: https://useapi.net/docs/api-acemusic-v1/post-acemusic-files --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> files description: "Upload audio or an image with POST files in the useapi.net ACE Music API: a song ACE Music transcribes, to cover or remix, or a picture for a prompt's images." parent: ACE Music API nav_order: 600 permalink: /docs/api-acemusic-v1/post-acemusic-files --- ## Upload audio or an image November 14, 2026 (November 16, 2026) --- Upload a file to an account's ACE Music Library, sent as the raw request body with its `Content-Type`: - Audio (MP3, WAV, FLAC, OGG, M4A or AAC, up to 100 MB and 8 minutes) becomes a song in the Library. ACE Music transcribes it, reading its lyrics, style, tempo and melody, which took about 15 to 30 seconds in our tests. The answer is that song with its `songId`, which works as a reference in [POST /music](/docs/api-acemusic-v1/post-acemusic-music): cover it, remix or edit it, mash it up, or let it guide a prompt. - An image (JPEG, PNG or WebP, up to 10 MB) returns a `mediaId` for the `images` of a prompt in [POST /music](/docs/api-acemusic-v1/post-acemusic-music). The type is read from the file's first bytes. The `Content-Type` you send only has to agree on audio or image. An uploaded file, its `songId` and its `mediaId` work only on the account it was uploaded to, so a request that uses them runs there. Uploaded audio counts against the account's upload allowance, the total length of audio it keeps: 10 minutes on Free, 30 on Creator and 60 on Artist. When it is used up the API answers `412`: delete uploads on acemusic.ai, or move up a plan. Transcribing costs no credits. The song's own audio downloads with [GET /music/download](/docs/api-acemusic-v1/get-acemusic-music-download). > **https://api.useapi.net/v1/acemusic/files?email=`email`&title=`title`** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: audio/mpeg # Or the file's own type: audio/wav, audio/flac, audio/ogg, audio/mp4, audio/aac, # image/jpeg, image/png, image/webp ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. - `Content-Type` is **required**, an `audio/…` or `image/…` type matching the file. - `Content-Length` is **required**. Most tools send it for you. ##### Query Parameters - `email` is optional, the account to upload to. Default: any healthy account. - `title` is optional, the title of an uploaded song, and its file name at ACE Music. Default: `upload-` with the date and time. Maximum length: `80` characters. ##### Request Body The file's bytes, nothing else. ##### Responses **200** **200 OK** Audio, transcribed: ```json { "songId": "user:1234-example@example.com-song:so_7d2e9b4c1a8f4e6d93b0c5a1", "taskId": "so_7d2e9b4c1a8f4e6d93b0c5a1", "status": "succeeded", "title": "paper-boat-demo", "model": null, "style": "A gentle acoustic indie-folk lullaby at a slow, peaceful tempo. Delicate fingerpicked acoustic guitar with warm ambient pads, and a tender female lead vocal close to the mic.", "lyrics": "[verse]\nFold the morning into paper\nSend it down the gutter stream\nSail away, little paper boat\nCarry every quiet dream", "instrumental": false, "duration": 35, "audioUrl": null, "playUrl": "https://example.r2.cloudflarestorage.com/…/upload.mp3?X-Amz-…", "playUrlExpires": "2026-11-16T01:27:32.000Z", "coverUrl": "https://acemusic.ai/data/so_7d2e9b4c1a8f4e6d93b0c5a1-cover.jpg?v=1794685595471", "pageUrl": null, "created": "2026-11-14T19:46:25.300Z", "finished": "2026-11-14T19:46:37.999Z", "kind": "upload", "score": true, "upload": { "seconds": 35, "bpm": 88, "transcription": "done" } } ``` An image: ```json { "mediaId": "user:1234-example@example.com-media:cx_5e8a1f3b9c2d4e7f80a6b4d2", "email": "example@example.com", "url": "https://acemusic.ai/data/cx_5e8a1f3b9c2d4e7f80a6b4d2.jpg", "mime": "image/jpeg", "kind": "image" } ``` **202** **202 Accepted** Audio that ACE Music was still transcribing after 90 seconds. The body is the song as it stands, the same shape as `200`. Read it again with [GET /music/`songId`](/docs/api-acemusic-v1/get-acemusic-music-songid). **400** **400 Bad Request** ACE Music refused the file, or the body ended early. ```json { "error": "Importing the audio: Audio can be up to 8 min long", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **404** **404 Not Found** ```json { "error": "Account example@example.com is not configured", "code": 404 } ``` **411** **411 Length Required** ```json { "error": "Content-Length is required (send the file as the raw request body)", "code": 411 } ``` **412** **412 Precondition Failed** The account's upload allowance is used up: delete uploads on acemusic.ai, or move up a plan. **413** **413 Content Too Large** ```json { "error": "The image file is 11.0 MB: the limit is 10 MB", "code": 413 } ``` **415** **415 Unsupported Media Type** ```json { "error": "Content-Type says audio but the file is an image (png)", "code": 415 } ``` ```json { "error": "Send the file as the raw request body with its Content-Type (audio/mpeg, audio/wav, audio/flac, audio/ogg, audio/mp4, audio/aac, image/jpeg, image/png or image/webp)", "code": 415 } ``` **422** **422 Unprocessable Entity** ACE Music could not read the audio. The body is the song with its `error`. **596** **596 Account Error** The account is paused, or no account is healthy. Add it again with the current password. ##### Model The uploaded file: an image, with the `mediaId` to send in `images`, or audio, as a song with its `songId`. <details markdown="block" class="model-details"> <summary>The uploaded image or song, field by field, and the type it uses (<code>Split</code>)</summary> An image: ```typescript { // TypeScript, all fields are optional mediaId: string // user:<id>-<email>-media:cx_…, the image's id: send it in the `images` of POST /music email: string // the account it was uploaded to url: string | null // ACE Music's link to the image mime: string // image/jpeg, image/png or image/webp kind: string // image } ``` Audio, the song (`kind: "upload"`): ```typescript { // TypeScript, all fields are optional songId: string // user:<id>-<email>-song:so_…, the song's id: use it as a reference, to split, download or delete taskId: string // ACE Music's own id of the song (so_…) status: 'planning' | 'scoring' | 'queued' | 'running' | 'succeeded' | 'failed' | 'interrupted' // ACE Music's progress on the song title: string | null // the song's title (ACE Music writes one for a prompt request) model: string | null // acemusic-v1, acemusic-v1.1 or ace-step-1.5-xl. null for an uploaded file style: string | null // the style the song was made with (ACE Music writes it for a prompt request) lyrics: string | null // [verse] / [chorus] tagged instrumental: boolean | null // true for a song with no vocals duration: number | null // seconds audioUrl: string | null // public mp3 link, https://acemusic.ai/data/<taskId>.mp3, once the song succeeded. // It never changes: store this one. null for an uploaded file: get its audio with // GET /music/download playUrl?: string | null // a direct link to the song's audio for players, valid until playUrlExpires: about an // hour for a made song (the same mp3 as audioUrl), 24 hours for an upload (its own audio, // in the format it was uploaded in). Some browsers (Brave) block the redirect behind // audioUrl: store audioUrl, play playUrl. For about a minute after a song is made it is // audioUrl itself (ACE Music serves the file directly then). In job records, // GET /music/{songId} and an audio upload's POST /files answer, not in GET /music. null // while the song is not finished, or when the link could not be read playUrlExpires?: string | null // ISO 8601, when playUrl stops working: read the job or the song again for a fresh one coverUrl: string | null // cover art (jpg) pageUrl: string | null // the song's page on acemusic.ai, when ACE Music made one created: string | null // ISO 8601 finished: string | null // ISO 8601 kind: 'original' | 'cover' | 'mashup' | 'edit' | 'upload' // how the song was made: original (a prompt or mode // generate), cover (mode cover, and mode remix too), mashup, edit, or upload (a file // sent with POST /files) score: boolean // true when ACE Music already has the song's score (GET /music/score) error?: { // a failed song code?: string // ACE Music's code, e.g. `ref_no_melody`, `song_not_made` message?: string // ACE Music's own words reason?: string // ACE Music's reason, when it gives one } refunded?: boolean // ACE Music gave the credits back for a failed song stems?: { // splits made with POST /music/stems. Their track links are signed (24 hours) on // GET /music/{songId}, null elsewhere vocals?: Split // mode vocals: vocal and instrumental all?: Split // mode all: every stem ACE Music found } upload?: { // an uploaded audio file (POST /files) seconds?: number // its length, counted against the account's upload minutes bpm?: number // the tempo ACE Music read transcription?: string // done once ACE Music has read its lyrics, style and melody } } ``` **`Split`**: each split in `stems` of a `Song` above (`vocals`, `all`). ```typescript { // TypeScript status?: string // ACE Music's progress on the split tracks: { // one per stem type?: string // the stem, e.g. vocals, drums, bass url: string | null // signed mp3 link (24 hours) on GET /music/{songId}, null elsewhere duration?: number // seconds }[] } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/acemusic/files?title=paper-boat-demo" \ -H "Authorization: Bearer …" \ -H "Content-Type: audio/mpeg" \ --data-binary "@demo.mp3" ``` **JavaScript** ``` javascript import { readFile } from "node:fs/promises"; const token = "API token"; const bytes = await readFile("demo.mp3"); const response = await fetch("https://api.useapi.net/v1/acemusic/files?title=paper-boat-demo", { method: "POST", headers: { "Authorization": `Bearer ${token}`, "Content-Type": "audio/mpeg" }, body: bytes }); const song = await response.json(); console.log(response.status, song.songId, song.lyrics); ``` **Python** ``` python import requests token = "API token" with open("demo.mp3", "rb") as f: response = requests.post( "https://api.useapi.net/v1/acemusic/files", headers={"Authorization": f"Bearer {token}", "Content-Type": "audio/mpeg"}, params={"title": "paper-boat-demo"}, data=f.read() ) print(response.status_code, response.json()) ``` === URL: https://useapi.net/docs/api-acemusic-v1/post-acemusic-music-lyrics === Document URL: https://useapi.net/docs/api-acemusic-v1/post-acemusic-music-lyrics --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> music/lyrics description: "Write or rewrite song lyrics and a title with POST music/lyrics in the useapi.net ACE Music API, steered by a style and your own lyrics, ready for POST music." parent: ACE Music API nav_order: 500 permalink: /docs/api-acemusic-v1/post-acemusic-music-lyrics --- ## Write lyrics November 14, 2026 (November 16, 2026) --- Have ACE Music's lyrics writer write lyrics and a title from a request, without making a song. It answers in about 5 to 40 seconds with `[verse]` / `[chorus]` tagged lyrics. Edit them if you like, then sing them with [POST /music](/docs/api-acemusic-v1/post-acemusic-music) as `lyrics` with a `style`, which [POST /music/style](/docs/api-acemusic-v1/post-acemusic-music-style) can write. Send existing `lyrics` with a request such as "make the chorus shorter" to rewrite them, and a `style` for words that fit the music. With `model` `acemusic-v1`, the writer adds section headers that say how each part is played, for ACE Music v1. Nothing is kept: call it again for another version. No credits were charged for it in our tests. > **https://api.useapi.net/v1/acemusic/music/lyrics** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "prompt": "A short song about a cat who loves rainy days", "style": "acoustic indie folk" } ``` - `prompt` is **required**, what to write: the theme, the story, the mood, or a change to the given `lyrics`. Maximum length: `2000` characters. - `style` is optional, the song's style, for lyrics that fit it. Maximum length: `1000` characters. - `lyrics` is optional, existing lyrics to rewrite or continue. Maximum length: `5000` characters. - `title` is optional, a working title. Maximum length: `80` characters. - `model` is optional. `acemusic-v1` adds section headers that say how each part is played. Other values change nothing. Supported values: `acemusic-v1`, `acemusic-v1.1`, `ace-step-1.5-xl`. - `email` is optional, the account to use. Default: any healthy account. ##### Responses **200** **200 OK** ```json { "email": "example@example.com", "title": "Rainy Day Whiskers", "lyrics": "[verse]\nCurled up on the window sill\nWatching every drop spill\nPaws tucked in against the cold\nGrey skies turning into gold\n\n[chorus]\nPatter, patter on the glass\nWatching little rivers pass\nTail twitch, half-closed eyes\nSleeping under stormy skies\n\n[verse]\nThunder rolls a gentle sound\nRaindrops drumming on the ground\nSoft purr humming in my chest\nRainy days are always best\n\n[outro]\nPatter, patter, rain falls deep\nTime to curl right back to sleep" } ``` **400** **400 Bad Request** A parameter is missing or invalid, or ACE Music's writer refused the request. ```json { "error": "Parameter prompt is required", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **422** **422 Unprocessable Entity** ```json { "error": "ACE Music wrote no lyrics for this request: rephrase it and try again", "code": 422 } ``` **596** **596 Account Error** The account named by `email` is paused, or no account is healthy. Add it again with the current password. ```json { "error": "No healthy ACE Music account configured. Check GET /accounts", "code": 596 } ``` ##### Model The lyrics ACE Music wrote, tagged by section, with a title for the song. <details markdown="block" class="model-details"> <summary>The lyrics, field by field</summary> ```typescript { // TypeScript, all fields are optional email: string // the account that wrote them title: string | null // a title for the song, null when ACE Music gave none lyrics: string // [verse] / [chorus] tagged } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/acemusic/music/lyrics" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "prompt": "A short song about a cat who loves rainy days" }' ``` **JavaScript** ``` javascript const token = "API token"; const response = await fetch("https://api.useapi.net/v1/acemusic/music/lyrics", { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}` }, body: JSON.stringify({ prompt: "A short song about a cat who loves rainy days" }) }); const { title, lyrics } = await response.json(); console.log(title, lyrics); ``` **Python** ``` python import requests token = "API token" response = requests.post( "https://api.useapi.net/v1/acemusic/music/lyrics", headers={"Authorization": f"Bearer {token}"}, json={"prompt": "A short song about a cat who loves rainy days"} ) print(response.status_code, response.json()) ``` === URL: https://useapi.net/docs/api-acemusic-v1/post-acemusic-music-stems === Document URL: https://useapi.net/docs/api-acemusic-v1/post-acemusic-music-stems --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> music/stems description: "Split an ACE Music song into stems with POST music/stems in the useapi.net ACE Music API: vocal and instrumental for 5 credits, or every stem for 60, as MP3 links." parent: ACE Music API nav_order: 400 permalink: /docs/api-acemusic-v1/post-acemusic-music-stems --- ## Split a song into stems November 14, 2026 (November 16, 2026) --- Split a finished song into stems with ACE Music's stem splitter, on the account that holds the song. Stems need a paid ACE Music plan (Creator or Artist). | `mode` | Tracks | Credits | |---|---|---| | `vocals` (default) | `vocal` and `instrumental` | 5 | | `all` | every stem ACE Music finds, such as `vocals`, `backing_vocals`, `drums`, `bass`, `guitar`, `keyboard`, `strings`, `synth`, `woodwinds` and `fx` | 60 | Each track is an MP3 behind a signed link valid for 24 hours (`expires`). Read the job again with [GET /jobs/`jobid`](/docs/api-acemusic-v1/get-acemusic-jobs-jobid), or the song with [GET /music/`songId`](/docs/api-acemusic-v1/get-acemusic-music-songid), for fresh links. A song that was already split in that mode answers at once with its tracks. ### Sync, async and webhooks - Every request runs as a job. Sync (the default): the POST waits and answers `200` with the finished job record, or with the job's error code and the record. In our tests an ACE-Step request took 20 to 95 seconds, ACE Music v1.1 Preview about 35 to 75 seconds, ACE Music v1 about 80 to 105 seconds and a stem split about 90 seconds. If the job is still running after 100 seconds, the POST answers `202` with the job as it stands: fetch the result with [GET /jobs/`jobid`](/docs/api-acemusic-v1/get-acemusic-jobs-jobid). Always check `status`: only `completed` carries the links. - Async: pass `async: true`. The POST answers `201` at once with the job in `status: "processing"`. Poll [GET /jobs/`jobid`](/docs/api-acemusic-v1/get-acemusic-jobs-jobid) or wait for the webhook. - `replyUrl` receives one `POST` of the final job record, as JSON, when the job completes or fails, for sync and async requests alike. Without `replyUrl`, the default `replyUrl` of your useapi.net account is used, see [POST account](/docs/account-management/post-account), when it passes the same checks as a request's: a public `https` URL. - A job that has not finished 30 minutes after it started fails with `504`. ACE Music may still finish it and has likely charged for it, so look for its songs with [GET /music](/docs/api-acemusic-v1/get-acemusic-music) before you run it again. - Each account runs at most `maxJobs` requests at a time (default `4`, which is ACE Music's own limit, range `1` to `4`, set with [POST /accounts](/docs/api-acemusic-v1/post-acemusic-accounts)). [GET /jobs](/docs/api-acemusic-v1/get-acemusic-jobs) shows what is running. A job can be read for 7 days. > **https://api.useapi.net/v1/acemusic/music/stems** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "songId": "user:1234-example@example.com-song:so_3f9c2a7d81e64b05a9d2c4e7", "mode": "all", "async": true, "replyUrl": "https://your-domain.com/webhook", "replyRef": "stems-1" } ``` - `songId` is **required**, a finished song's `songId` (`user:<id>-<email>-song:so_…`). The split runs on the account that holds it. - `mode` is optional. Supported values: `vocals` (default), `all`. - `async` is optional, `true` to answer `201` at once and run the split in the background. Default: `false`. - `replyUrl` is optional, a public `https` URL that receives one `POST` of the job record when the split completes or fails. Callback body has the same JSON shape as [GET /jobs/`jobid`](/docs/api-acemusic-v1/get-acemusic-jobs-jobid) response. Maximum length: `2048` characters. - `replyRef` is optional, your own reference echoed back in the job record. Maximum length: `1024` characters. ##### Responses **200** **200 OK** The split is done. ```json { "jobid": "j1114203012775104298s-u1234-email:example@example.com-task:so_3f9c2a7d81e64b05a9d2c4e7.0-bot:acemusic", "type": "stems", "status": "completed", "email": "example@example.com", "created": "2026-11-14T20:30:12.775Z", "stems": { "mode": "vocals", "songId": "user:1234-example@example.com-song:so_3f9c2a7d81e64b05a9d2c4e7", "tracks": [ { "type": "vocal", "url": "https://….r2.cloudflarestorage.com/acemusic-data-prod/users/…/stem/202611/…?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=86400&…", "duration": 135.02 }, { "type": "instrumental", "url": "https://….r2.cloudflarestorage.com/acemusic-data-prod/users/…/stem/202611/…?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=86400&…", "duration": 135.02 } ], "expires": "2026-11-15T20:31:40.508Z" }, "completed": "2026-11-14T20:31:39.143Z", "job_state": "completed", "outputs": [ { "ok": true, "url": "https://….r2.cloudflarestorage.com/acemusic-data-prod/users/…/stem/202611/…?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=86400&…", "url_auth": "none", "mime": "audio/mpeg", "expires_at": "2026-11-15T20:31:40.531Z", "ref": null }, { "ok": true, "url": "https://….r2.cloudflarestorage.com/acemusic-data-prod/users/…/stem/202611/…?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=86400&…", "url_auth": "none", "mime": "audio/mpeg", "expires_at": "2026-11-15T20:31:40.531Z", "ref": null } ] } ``` **201** **201 Created** `async: true`, the split is running. A sync request that is still running after 100 seconds answers `202` with the same body. ```json { "jobid": "j1114203348120936514s-u1234-email:example@example.com-task:so_3f9c2a7d81e64b05a9d2c4e7.2-bot:acemusic", "type": "stems", "status": "processing", "email": "example@example.com", "created": "2026-11-14T20:33:48.120Z", "stems": { "mode": "all", "songId": "user:1234-example@example.com-song:so_3f9c2a7d81e64b05a9d2c4e7", "tracks": [] }, "replyUrl": "https://your-domain.com/webhook", "replyRef": "stems-1", "job_state": "in_progress", "outputs": [] } ``` **202** **202 Accepted** Sync mode, the split was still running after 100 seconds. The body is the job as it stands, the same shape as `201`, with `status: "processing"`. Fetch the result with [GET /jobs/`jobid`](/docs/api-acemusic-v1/get-acemusic-jobs-jobid) or wait for the webhook. **400** **400 Bad Request** ```json { "error": "Parameter mode (drums) valid values: vocals,all", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The account is on the Free plan, or the song belongs to another useapi.net user. ```json { "error": "Splitting the song into stems needs a paid ACE Music plan (the account is on free): Downloads come with a paid plan", "code": 403 } ``` **412** **412 Precondition Failed** The account has too few credits for the split. `cost` is what it needs. **422** **422 Unprocessable Entity** Sync mode, ACE Music could not split the song. The body is the failed job record, with ACE Music's reason in `error`. **429** **429 Too Many Requests** The song's account is running its `maxJobs`. Retry after the `Retry-After` header (30 seconds). ```json { "error": "Account example@example.com is running 4 of 4 jobs (maxJobs). Wait for one to finish, or raise maxJobs with POST /accounts", "code": 429 } ``` **502** **502 Bad Gateway** ACE Music may have accepted the request, and charged for it, but its answer was lost, or it answered with something unexpected after accepting it. Check the song with [GET /music/`songId`](/docs/api-acemusic-v1/get-acemusic-music-songid) before you send it again: its stems may be there. **503** **503 Service Unavailable** ACE Music is busy, could not be reached before the request was sent, or the session is being renewed. Nothing was charged: retry after the `Retry-After` header. **504** **504 Gateway Timeout** ACE Music did not answer within 30 seconds after the request was sent: it may have accepted it and charged for it. Check the song with [GET /music/`songId`](/docs/api-acemusic-v1/get-acemusic-music-songid) before you send it again. ```json { "error": "Splitting the song into stems: ACE Music did not answer within 30 s. It may already have charged for this: check GET /music before retrying", "code": 504 } ``` **596** **596 Account Error** ACE Music refused the stored email and password of the song's account. Add it again with the current password. ##### Model The job record. [GET /jobs/`jobid`](/docs/api-acemusic-v1/get-acemusic-jobs-jobid) and the `replyUrl` webhook return the same shape. <details markdown="block" class="model-details"> <summary>The job record, field by field, and the types it uses (<code>Song</code>, <code>Output</code>, <code>ErrorInfo</code>)</summary> ```typescript { // TypeScript, all fields are optional jobid: string // the job's id, `j…-u<id>-email:<email>-task:…-bot:acemusic`. It names the account and // the song or songs the job is about. Read the job with GET /jobs/{jobid} type: 'music' | 'stems' // music: POST /music. stems: POST /music/stems status: 'processing' | 'completed' | 'failed' // processing: ACE Music is making the songs or the split (every job // starts here). completed: done, a song job once at least one of its two songs succeeded. // failed: done without a result, error says why and code is the HTTP status email: string // the ACE Music account the job runs on created: string // ISO 8601 completed?: string // ISO 8601, when the job completed or failed model?: string // music: the model you asked for modelUsed?: string // music: the model that made the songs. It differs from model when the request ran on // another one: a request that must read a song (a mashup, a cover asked on acemusic-v1, a // prompt with more than one reference on ace-step-1.5-xl) runs on acemusic-v1.1, and ACE // Music can also switch a request itself songs?: (Song | DeletedSong)[] // music: the request's two songs, see Song below. A song deleted since, with // DELETE /music/{songId} or on acemusic.ai, is a DeletedSong stems?: { // on a stems job: the split mode: 'vocals' | 'all' // the split you asked for songId: string // the song that was split songStatus?: 'deleted' // the song was deleted, its stems went with it (the job failed with code 404) tracks: { // one per stem type: string // vocals: vocal, instrumental. all: vocals, `backing_vocals`, drums, bass, guitar, // keyboard, strings, synth, woodwinds, fx (the stems ACE Music found) url: string | null // signed mp3 link, valid 24 hours duration?: number // seconds }[] expires?: string // ISO 8601, when the track links stop working (read the job again for fresh ones) } error?: string // status 'failed': why code?: number // status failed: the HTTP status of the failure. 400: ACE Music could not read a // referenced song's melody (read its score with GET /music/score, then run it again). 404: // the account was removed, or a split's song was deleted. 422: ACE Music could not make // the songs or the split. 504: not finished within 30 minutes (ACE Music may still finish // it). 596: the account was signed out replyUrl?: string // the replyUrl you sent: it receives this record when the job ends replyRef?: string // the replyRef you sent, echoed back job_state: 'pending' | 'in_progress' | 'completed' | 'failed' | 'cancelled' | 'expired' | 'unknown' // where the job is, in the same words for every useapi.net API outputs: Output[] // one entry per file the job made, see Output below error_info?: ErrorInfo // only on a failed job: why, and whether to retry, see ErrorInfo below } ``` **`Song`**: each item of `songs` in the job record above. **`DeletedSong`**: an item of `songs` whose song was deleted since, with DELETE `/music/{songId}` or on acemusic.ai. ```typescript { // TypeScript songId: string // the song's id, as it was taskId: string // ACE Music's own id of the song (so_…) status: 'deleted' // deleted with DELETE /music/{songId} or on acemusic.ai } ``` **`Output`**: each item of `outputs` in the job record above. **`ErrorInfo`**: the `error_info` of a failed job above. </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/acemusic/music/stems" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "songId": "user:1234-example@example.com-song:so_3f9c2a7d81e64b05a9d2c4e7", "mode": "vocals" }' ``` **JavaScript** ``` javascript const token = "API token"; const response = await fetch("https://api.useapi.net/v1/acemusic/music/stems", { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}` }, body: JSON.stringify({ songId: "user:1234-example@example.com-song:so_3f9c2a7d81e64b05a9d2c4e7", mode: "vocals" }) }); const job = await response.json(); console.log(response.status, job.status); job.stems?.tracks.forEach(track => console.log(track.type, track.url)); ``` **Python** ``` python import requests token = "API token" response = requests.post( "https://api.useapi.net/v1/acemusic/music/stems", headers={"Authorization": f"Bearer {token}"}, json={"songId": "user:1234-example@example.com-song:so_3f9c2a7d81e64b05a9d2c4e7", "mode": "vocals"} ) job = response.json() print(response.status_code, job.get("status")) for track in (job.get("stems") or {}).get("tracks", []): print(track["type"], track["url"]) ``` === URL: https://useapi.net/docs/api-acemusic-v1/post-acemusic-music-style === Document URL: https://useapi.net/docs/api-acemusic-v1/post-acemusic-music-style --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> music/style description: "Improve or invent a song style with POST music/style in the useapi.net ACE Music API: genre, instruments, vocals and production in a paragraph, ready for POST music." parent: ACE Music API nav_order: 510 permalink: /docs/api-acemusic-v1/post-acemusic-music-style --- ## Write a style November 14, 2026 (November 16, 2026) --- Turn a few words such as "indie folk" into a full style description, the genre, instruments, vocals, mix and how the song builds, or invent one when `style` is empty. Use the result as `style` in [POST /music](/docs/api-acemusic-v1/post-acemusic-music). With `model` `acemusic-v1` and your `lyrics`, it writes a production brief for those lyrics. It answers in about 5 to 15 seconds, and nothing is kept. ACE-Step v1.5 XL takes a style of up to 512 characters, so shorten a long one for that model. > **https://api.useapi.net/v1/acemusic/music/style** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "style": "indie folk" } ``` - `style` is optional, the style to improve. Leave it out to have one invented. Maximum length: `1000` characters. - `lyrics` is optional, with `model` `acemusic-v1` only: the lyrics the style is for. Maximum length: `5000` characters. - `model` is optional. `acemusic-v1` uses `lyrics`. Other values change nothing. Supported values: `acemusic-v1`, `acemusic-v1.1`, `ace-step-1.5-xl`. - `email` is optional, the account to use. Default: any healthy account. ##### Responses **200** **200 OK** ```json { "email": "example@example.com", "style": "Contemporary indie folk with an intimate, pastoral atmosphere. The arrangement centers on delicate, intricate fingerpicked steel-string acoustic guitar and warm upright bass, supported by subtle brushed snare and soft foot-stomps. Melodic cello lines and distant lap steel swells add emotional depth behind a close-mic'd, breathy lead vocal with raw, vulnerable delivery. Warm tape saturation and room ambience preserve an organic live feel. The piece opens sparsely with solo guitar, gathers momentum as lush group harmonies and gentle piano join during the choruses, and resolves to a quiet, unresolved acoustic decay." } ``` **400** **400 Bad Request** ```json { "error": "Parameter style length exceeds 1000 characters", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **596** **596 Account Error** The account named by `email` is paused, or no account is healthy. Add it again with the current password. ```json { "error": "No healthy ACE Music account configured. Check GET /accounts", "code": 596 } ``` ##### Model The style ACE Music wrote, ready for the `style` of [POST /music](/docs/api-acemusic-v1/post-acemusic-music). <details markdown="block" class="model-details"> <summary>The style, field by field</summary> ```typescript { // TypeScript, all fields are optional email: string // the account that wrote it style: string // the style, for POST /music `style` } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/acemusic/music/style" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "style": "dark techno" }' ``` **JavaScript** ``` javascript const token = "API token"; const response = await fetch("https://api.useapi.net/v1/acemusic/music/style", { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}` }, body: JSON.stringify({ style: "dark techno" }) }); console.log((await response.json()).style); ``` **Python** ``` python import requests token = "API token" response = requests.post( "https://api.useapi.net/v1/acemusic/music/style", headers={"Authorization": f"Bearer {token}"}, json={"style": "dark techno"} ) print(response.status_code, response.json()) ``` === URL: https://useapi.net/docs/api-acemusic-v1/post-acemusic-music === Document URL: https://useapi.net/docs/api-acemusic-v1/post-acemusic-music --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> music description: "Generate two songs with POST music in the useapi.net ACE Music API on ACE Music v1, v1.1 or ACE-Step: from a prompt or your lyrics, cover, remix, edit or mashup." parent: ACE Music API nav_order: 200 permalink: /docs/api-acemusic-v1/post-acemusic-music --- ## Generate songs November 14, 2026 (November 16, 2026) --- Make two songs with [ACE Music](https://acemusic.ai) in one request, with vocals or instrumental, on ACE Music v1, ACE Music v1.1 Preview or the free ACE-Step v1.5 XL. Each song comes back with a public mp3 link, cover art, its title, style and lyrics, and a `songId` you can cover, remix, edit, mash up, [split into stems](/docs/api-acemusic-v1/post-acemusic-music-stems), [download](/docs/api-acemusic-v1/get-acemusic-music-download) as WAV, MIDI or MusicXML, or read as a [score](/docs/api-acemusic-v1/get-acemusic-music-score). ### Two ways to make songs The fields you send pick the way, as on the ACE Music website: | Way | Send | What ACE Music does | |---|---|---| | Idea | `prompt`, and optionally up to 3 `references` and up to 3 `images` | Writes the style, lyrics and title from your idea, then makes the songs | | Your own texts | `style` and `lyrics` (or `instrumental: true`), with an optional `title`, `mode` and the [options](#options) | Sings your lyrics in your style, or covers, remixes, edits or mashes up songs | A request with any of `mode`, `style`, `lyrics`, `title`, `instrumental`, `referenceAudio` or an option takes the second way. Never send `prompt` together with them: the API answers `400` and names what to drop. To have ACE Music write lyrics you can still edit, use [POST /music/lyrics](/docs/api-acemusic-v1/post-acemusic-music-lyrics) and [POST /music/style](/docs/api-acemusic-v1/post-acemusic-music-style) first. ### Modes `mode` applies to the second way. A reference is a `songId`: a song made by the API, one from [GET /music](/docs/api-acemusic-v1/get-acemusic-music), or your own audio uploaded with [POST /files](/docs/api-acemusic-v1/post-acemusic-files). | `mode` | `references` | Runs on | What it does | |---|---|---|---| | `generate` (default) | none | any model | New songs from `style` (required) and your `lyrics`. No `lyrics` makes an instrumental | | `cover` | 1 song | `acemusic-v1.1`, or ACE-Step on `ace-step-1.5-xl` | The song in a new style, following its melody, chords and structure | | `remix` | 1 song | `ace-step-1.5-xl` only, the default for this mode | ACE-Step's remix: `coverStrength` keeps the original, `remixStrength` moves away from it | | `edit` | 1 song | `ace-step-1.5-xl` only, the default for this mode | Rewrites the part between `start` and `end` seconds, with new `lyrics` for that part | | `mashup` | 2 or 3 songs | `acemusic-v1.1` | One new song from several. Without `lyrics`, ACE Music combines the songs' own words | `instrumental: true` works only with `mode` `generate`. A cover, remix, edit or mashup keeps the words of the songs it is made from, so other modes answer `400` to it. ACE Music v1.1 follows a song by the melody it reads from the song's score. A cover or mashup of an ACE Music v1 song reads its score first when it has none (free for ACE Music v1 songs, a few seconds). ACE-Step songs are not read automatically: if ACE Music answers `ref_no_melody`, call [GET /music/score](/docs/api-acemusic-v1/get-acemusic-music-score) on the song first (1 credit), then try again. ### Model switching `model` is the model you ask for. As on the ACE Music website, a request that must read a song runs on ACE Music v1.1 Preview, the model that reads: a `mashup`, a `cover` asked on `acemusic-v1`, and a prompt with more than one reference on `ace-step-1.5-xl`. ACE Music can also switch a request itself, for example a prompt with a reference song on `acemusic-v1`, to keep its tune. The job reports both: `model` (asked) and `modelUsed` (ran). The credits and the text limits follow the model that runs, so a switched ACE-Step request costs 4 credits. ### Cost ACE Music charges per request when it accepts it: 4 credits on `acemusic-v1` and `acemusic-v1.1` (two songs, 2 credits a song) and nothing on `ace-step-1.5-xl`, which runs even on an account with 0 credits. An account with too few credits answers `412` with the `cost`. A song ACE Music could not make shows `refunded: true` when ACE Music gave its credits back. See [Pricing](/docs/api-acemusic-v1#pricing). ### Sync, async and webhooks - Every request runs as a job. Sync (the default): the POST waits and answers `200` with the finished job record, or with the job's error code and the record. In our tests an ACE-Step request took 20 to 95 seconds, ACE Music v1.1 Preview about 35 to 75 seconds, ACE Music v1 about 80 to 105 seconds and a stem split about 90 seconds. If the job is still running after 100 seconds, the POST answers `202` with the job as it stands: fetch the result with [GET /jobs/`jobid`](/docs/api-acemusic-v1/get-acemusic-jobs-jobid). Always check `status`: only `completed` carries the links. - Async: pass `async: true`. The POST answers `201` at once with the job in `status: "processing"`. Poll [GET /jobs/`jobid`](/docs/api-acemusic-v1/get-acemusic-jobs-jobid) or wait for the webhook. - `replyUrl` receives one `POST` of the final job record, as JSON, when the job completes or fails, for sync and async requests alike. Without `replyUrl`, the default `replyUrl` of your useapi.net account is used, see [POST account](/docs/account-management/post-account), when it passes the same checks as a request's: a public `https` URL. - A job that has not finished 30 minutes after it started fails with `504`. ACE Music may still finish it and has likely charged for it, so look for its songs with [GET /music](/docs/api-acemusic-v1/get-acemusic-music) before you run it again. - Each account runs at most `maxJobs` requests at a time (default `4`, which is ACE Music's own limit, range `1` to `4`, set with [POST /accounts](/docs/api-acemusic-v1/post-acemusic-accounts)). [GET /jobs](/docs/api-acemusic-v1/get-acemusic-jobs) shows what is running. A job can be read for 7 days. > **https://api.useapi.net/v1/acemusic/music** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body From an idea: ```json { "prompt": "A short cheerful ukulele tune about a sunny Saturday morning at the farmers market", "model": "ace-step-1.5-xl" } ``` From your own style and lyrics: ```json { "style": "synthwave, retro drum machine, warm analog pads, male vocals", "lyrics": "[Verse]\nMorning light on the window pane\nCoffee steam and a quiet lane\n[Chorus]\nHold on, hold on, the day is new\nEvery road leads back to you", "title": "Neon Morning", "model": "acemusic-v1", "duration": 120, "async": true, "replyUrl": "https://your-domain.com/webhook", "replyRef": "neon-morning-1" } ``` A cover of one of your songs: ```json { "mode": "cover", "references": ["user:1234-example@example.com-song:so_3f9c2a7d81e64b05a9d2c4e7"], "style": "acoustic folk, fingerpicked guitar, soft female vocals" } ``` Idea: - `prompt` is **required** for an idea, unless `references` or `images` are given: the song in your own words. ACE Music writes the style, lyrics and title. Maximum length: `2000` characters. - `images` is optional, up to `3` image ids from [POST /files](/docs/api-acemusic-v1/post-acemusic-files) (`user:<id>-<email>-media:cx_…`), pictures the songs are about. With `prompt` only. Your own texts: - `mode` is optional, see [Modes](#modes). Supported values: `generate` (default), `cover`, `remix`, `edit`, `mashup`. - `style` is **required** for `mode` `generate`: genre, instruments, mood, tempo and vocals. Maximum length: `1000` characters, `512` on `ace-step-1.5-xl`. - `lyrics` is optional, your lyrics with `[verse]` / `[chorus]` section tags. In `mode` `generate`, no lyrics makes an instrumental. In `edit`, the words for the part you rewrite. Maximum length: `5000` characters, `2000` on `ace-step-1.5-xl`. - `instrumental` is optional, `true` for songs with no vocals, with `mode` `generate` only. Not together with `lyrics`. - `title` is optional, the songs' title. Maximum length: `80` characters. - The [options](#options) below. Both ways: - `model` is optional, the model to ask for, see [Model switching](#model-switching). Supported values: `acemusic-v1` (default), `acemusic-v1.1`, `ace-step-1.5-xl` (the default for `remix` and `edit`). - `references` is optional, an array of `songId`s (`user:<id>-<email>-song:so_…`) from a finished job, [GET /music](/docs/api-acemusic-v1/get-acemusic-music) or [POST /files](/docs/api-acemusic-v1/post-acemusic-files). With `prompt`, up to `3` songs that guide the new ones. With a `mode`, as many as the [Modes](#modes) table says. Each id once. - `email` is optional, the account to run on. When omitted, the account that holds the `references` and `images` runs the request, or, with none, a healthy account with a free `maxJobs` slot. Every song and image of one request must be on the same account. - `async` is optional, `true` to answer `201` at once and run the job in the background. Default: `false`. - `replyUrl` is optional, a public `https` URL that receives one `POST` of the job record when the job completes or fails. It works with sync and async requests. Callback body has the same JSON shape as [GET /jobs/`jobid`](/docs/api-acemusic-v1/get-acemusic-jobs-jobid) response. Maximum length: `2048` characters. - `replyRef` is optional, your own reference echoed back in the job record. Maximum length: `1024` characters. Any other parameter returns `400 Parameter <name> not supported`. ##### Options Each option works only where the table says, checked against the model that runs. Anywhere else the API answers `400 Parameter <name> does not apply to mode <mode> on <model>`. | Option | Values | Where | |---|---|---| | `duration` | Song length in seconds: `30` to `600` on `acemusic-v1`, `10` to `240` on `ace-step-1.5-xl`. Default: the model decides | `generate` on `acemusic-v1` or `ace-step-1.5-xl` | | `negative` | Styles to avoid, up to `200` characters | `generate` on `acemusic-v1` or `ace-step-1.5-xl` | | `styleInfluence` | `0` to `100`, default `80`: how strictly your style is followed, as written when high, freely when low | `acemusic-v1`, `acemusic-v1.1` | | `audioInfluence` | `0` to `100`, default `60`: how closely the reference is followed, its chords, sections, tempo, key and sound | `acemusic-v1.1` with `references` (`cover`, `mashup`) | | `bpm` | `30` to `200` | `generate` on `ace-step-1.5-xl` | | `timeSignature` | `2/4`, `3/4`, `4/4`, `6/8` | `generate` on `ace-step-1.5-xl` | | `thinking` | `0` to `100`: ACE-Step plans the whole song first, creative when low, steady when high | `generate` on `ace-step-1.5-xl` | | `key` | `C major`, `C minor`, `C# major` … `B minor`: C, C#, D, Eb, E, F, F#, G, Ab, A, Bb and B, each `major` or `minor` | `generate`, `cover`, `remix` on `ace-step-1.5-xl` | | `coverStrength` | `0` to `100`, default `20`: how much of the original stays | `cover`, `remix` on `ace-step-1.5-xl` | | `remixStrength` | `0` to `100`, default `0`: how far it moves away from the original | `cover`, `remix` on `ace-step-1.5-xl` | | `start`, `end` | Seconds, `0` to `600`, `end` at least 1 second after `start`. Required for `edit` | `edit` | | `referenceAudio` | A `songId` whose sound guides the result | any mode on `ace-step-1.5-xl` | ##### Responses **200** **200 OK** Sync mode, the job has finished. It is `completed` when at least one of its two songs succeeded, here both: a song that failed carries its own `error`. Each `audioUrl` is a public mp3 link. `playUrl` is a direct link to the same MP3 for players, valid until `playUrlExpires` (about an hour): some browsers (Brave) block the redirect behind `audioUrl`. Store `audioUrl`, play `playUrl`. For about a minute after a song is made ACE Music serves it at `audioUrl` itself, so the answer that comes right then, as here, has `playUrl` equal to `audioUrl` with a one-minute `playUrlExpires`: read the job or the song again later for a fresh link. ```json { "jobid": "j1114201530412583907m-u1234-email:example@example.com-task:so_3f9c2a7d81e64b05a9d2c4e7.so_b6e14d0c9a7f4382be51f0a3-bot:acemusic", "type": "music", "status": "completed", "email": "example@example.com", "created": "2026-11-14T20:15:30.412Z", "model": "ace-step-1.5-xl", "modelUsed": "ace-step-1.5-xl", "songs": [ { "songId": "user:1234-example@example.com-song:so_3f9c2a7d81e64b05a9d2c4e7", "taskId": "so_3f9c2a7d81e64b05a9d2c4e7", "status": "succeeded", "title": "Farmers Market Sunshine", "model": "ace-step-1.5-xl", "style": "Upbeat indie folk, bright cheerful acoustic ukulele strumming, light hand percussion, shaker, warm upright bass, sweet breezy female vocals, sunny acoustic production.", "lyrics": "[verse 1]\nWoven tote bag swinging by my side\nMorning breeze and the sky open wide\n…\n\n[chorus]\nOh it's Saturday morning down at the square\n…", "instrumental": false, "duration": 135.02, "audioUrl": "https://acemusic.ai/data/so_3f9c2a7d81e64b05a9d2c4e7.mp3", "playUrl": "https://acemusic.ai/data/so_3f9c2a7d81e64b05a9d2c4e7.mp3", "playUrlExpires": "2026-11-14T20:17:20.318Z", "coverUrl": "https://acemusic.ai/data/so_3f9c2a7d81e64b05a9d2c4e7-cover.jpg?v=1794685678498", "pageUrl": "https://acemusic.ai/song/k4m8q2vz7xpd", "created": "2026-11-14T20:15:30.439Z", "finished": "2026-11-14T20:16:14.205Z", "kind": "original", "score": false }, { "songId": "user:1234-example@example.com-song:so_b6e14d0c9a7f4382be51f0a3", "taskId": "so_b6e14d0c9a7f4382be51f0a3", "status": "succeeded", "title": "Farmers Market Sunshine", "model": "ace-step-1.5-xl", "style": "Upbeat indie folk, bright cheerful acoustic ukulele strumming, light hand percussion, shaker, warm upright bass, sweet breezy female vocals, sunny acoustic production.", "lyrics": "[verse 1]\nWoven tote bag swinging by my side\nMorning breeze and the sky open wide\n…\n\n[chorus]\nOh it's Saturday morning down at the square\n…", "instrumental": false, "duration": 135.02, "audioUrl": "https://acemusic.ai/data/so_b6e14d0c9a7f4382be51f0a3.mp3", "playUrl": "https://acemusic.ai/data/so_b6e14d0c9a7f4382be51f0a3.mp3", "playUrlExpires": "2026-11-14T20:17:20.318Z", "coverUrl": "https://acemusic.ai/data/so_b6e14d0c9a7f4382be51f0a3-cover.jpg?v=1794685679611", "pageUrl": "https://acemusic.ai/song/w7n3c5r9t2hb", "created": "2026-11-14T20:15:30.440Z", "finished": "2026-11-14T20:16:14.205Z", "kind": "original", "score": false } ], "completed": "2026-11-14T20:16:14.205Z", "job_state": "completed", "outputs": [ { "ok": true, "url": "https://acemusic.ai/data/so_3f9c2a7d81e64b05a9d2c4e7.mp3", "url_auth": "none", "mime": "audio/mpeg", "expires_at": null, "ref": "user:1234-example@example.com-song:so_3f9c2a7d81e64b05a9d2c4e7", "thumbnail_url": "https://acemusic.ai/data/so_3f9c2a7d81e64b05a9d2c4e7-cover.jpg?v=1794685678498" }, { "ok": true, "url": "https://acemusic.ai/data/so_b6e14d0c9a7f4382be51f0a3.mp3", "url_auth": "none", "mime": "audio/mpeg", "expires_at": null, "ref": "user:1234-example@example.com-song:so_b6e14d0c9a7f4382be51f0a3", "thumbnail_url": "https://acemusic.ai/data/so_b6e14d0c9a7f4382be51f0a3-cover.jpg?v=1794685679611" } ] } ``` **201** **201 Created** `async: true`, the job is running, here an idea on `acemusic-v1`. While ACE Music writes the lyrics, the songs are `planning` and `Untitled`. Poll [GET /jobs/`jobid`](/docs/api-acemusic-v1/get-acemusic-jobs-jobid) or wait for the webhook. ```json { "jobid": "j1114202212045711826m-u1234-email:example@example.com-task:so_8c1d4f7a2b9e4c06a3f5d7e1.so_e2a7b9c4d6f84a1b95c3e0d8-bot:acemusic", "type": "music", "status": "processing", "email": "example@example.com", "created": "2026-11-14T20:22:12.045Z", "model": "acemusic-v1", "modelUsed": "acemusic-v1", "songs": [ { "songId": "user:1234-example@example.com-song:so_8c1d4f7a2b9e4c06a3f5d7e1", "taskId": "so_8c1d4f7a2b9e4c06a3f5d7e1", "status": "planning", "title": "Untitled", "model": "acemusic-v1", "style": null, "lyrics": null, "instrumental": false, "duration": null, "audioUrl": null, "playUrl": null, "playUrlExpires": null, "coverUrl": null, "pageUrl": null, "created": "2026-11-14T20:22:12.068Z", "finished": null, "kind": "original", "score": false }, { "songId": "user:1234-example@example.com-song:so_e2a7b9c4d6f84a1b95c3e0d8", "taskId": "so_e2a7b9c4d6f84a1b95c3e0d8", "status": "planning", "title": "Untitled", "model": "acemusic-v1", "style": null, "lyrics": null, "instrumental": false, "duration": null, "audioUrl": null, "playUrl": null, "playUrlExpires": null, "coverUrl": null, "pageUrl": null, "created": "2026-11-14T20:22:12.069Z", "finished": null, "kind": "original", "score": false } ], "replyUrl": "https://your-domain.com/webhook", "replyRef": "lofi-1", "job_state": "in_progress", "outputs": [ { "ok": false, "url": null, "url_auth": "none", "mime": "audio/mpeg", "expires_at": null, "ref": "user:1234-example@example.com-song:so_8c1d4f7a2b9e4c06a3f5d7e1", "thumbnail_url": null }, { "ok": false, "url": null, "url_auth": "none", "mime": "audio/mpeg", "expires_at": null, "ref": "user:1234-example@example.com-song:so_e2a7b9c4d6f84a1b95c3e0d8", "thumbnail_url": null } ] } ``` **202** **202 Accepted** Sync mode, the songs were still being made after 100 seconds. The body is the job as it stands, the same shape as `201`, with `status: "processing"`. Fetch the result with [GET /jobs/`jobid`](/docs/api-acemusic-v1/get-acemusic-jobs-jobid) or wait for the webhook. **400** **400 Bad Request** A parameter is missing or invalid, the parameters mix the two ways, or ACE Music refused the request. A few of the answers: ```json { "error": "Send prompt or lyrics, not both: drop lyrics to have ACE Music write the song from your prompt, or drop prompt to sing your own lyrics (with style)", "code": 400 } ``` ```json { "error": "mode mashup takes 2 to 3 songs in references", "code": 400 } ``` ```json { "error": "Parameter bpm does not apply to mode generate on acemusic-v1", "code": 400 } ``` ```json { "error": "Song user:1234-example2@example.com-song:so_5a0e3c8b1d7f4e92a6c4b8d0 is on account example2@example.com, not example@example.com: songs and images only work on the account that holds them", "code": 400 } ``` ```json { "error": "Please add at least one ACE Music account first: https://useapi.net/docs/api-acemusic-v1/post-acemusic-accounts", "code": 400 } ``` Sync mode, ACE Music could not read the melody of a referenced song (`ref_no_melody`), usually an ACE-Step song with no score yet. Read its score with [GET /music/score](/docs/api-acemusic-v1/get-acemusic-music-score), then send the request again. The body is the failed job record, and the credits came back (`refunded: true`): ```json { "jobid": "j1114200257596846480m-u1234-email:example@example.com-task:so_9a4f1c7e3b2d4a8c96e0b5d2.so_0c6b8e2a4f1d4b7a83e9c5f1-bot:acemusic", "type": "music", "status": "failed", "email": "example@example.com", "created": "2026-11-14T20:02:57.596Z", "model": "ace-step-1.5-xl", "modelUsed": "acemusic-v1.1", "songs": [ { "songId": "user:1234-example@example.com-song:so_9a4f1c7e3b2d4a8c96e0b5d2", "taskId": "so_9a4f1c7e3b2d4a8c96e0b5d2", "status": "failed", "title": "Untitled", "model": "acemusic-v1.1", "style": "upbeat pop mashup, bright synths", "lyrics": null, "instrumental": false, "duration": null, "audioUrl": null, "playUrl": null, "playUrlExpires": null, "coverUrl": null, "pageUrl": null, "created": "2026-11-14T20:02:57.619Z", "finished": null, "kind": "mashup", "score": false, "error": { "code": "ref_no_melody", "message": "No melody could be found in the reference" }, "refunded": true }, { "songId": "user:1234-example@example.com-song:so_0c6b8e2a4f1d4b7a83e9c5f1", "taskId": "so_0c6b8e2a4f1d4b7a83e9c5f1", "status": "failed", "title": "Untitled", "model": "acemusic-v1.1", "style": "upbeat pop mashup, bright synths", "lyrics": null, "instrumental": false, "duration": null, "audioUrl": null, "playUrl": null, "playUrlExpires": null, "coverUrl": null, "pageUrl": null, "created": "2026-11-14T20:02:57.620Z", "finished": null, "kind": "mashup", "score": false, "error": { "code": "ref_no_melody", "message": "No melody could be found in the reference" }, "refunded": true } ], "completed": "2026-11-14T20:03:46.414Z", "code": 400, "error": "ACE Music could not read the melody of the referenced song (ref_no_melody): read its score first with GET /music/score, then try again. ACE Music refunded the credits", "job_state": "failed", "outputs": [ { "ok": false, "url": null, "url_auth": "none", "mime": "audio/mpeg", "expires_at": null, "ref": "user:1234-example@example.com-song:so_9a4f1c7e3b2d4a8c96e0b5d2", "thumbnail_url": null }, { "ok": false, "url": null, "url_auth": "none", "mime": "audio/mpeg", "expires_at": null, "ref": "user:1234-example@example.com-song:so_0c6b8e2a4f1d4b7a83e9c5f1", "thumbnail_url": null } ], "error_info": { "code": "input_rejected", "message": "ACE Music could not read the melody of the referenced song (ref_no_melody): read its score first with GET /music/score, then try again. ACE Music refunded the credits", "retry": { "mode": "never", "action": "replace_input" }, "vendor_code": "ref_no_melody" } } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** A `songId` or image id belongs to another useapi.net user. ```json { "error": "Song user:5678-someone@example.com-song:so_c155273ac66b4f2fa0c0dad1 is not yours", "code": 403 } ``` **404** **404 Not Found** ```json { "error": "Account example@example.com is not configured", "code": 404 } ``` **412** **412 Precondition Failed** The account has too few credits for `acemusic-v1` or `acemusic-v1.1`. `cost` is what the request needs. Without `email`, the API first tries your other accounts. `ace-step-1.5-xl` needs no credits. ```json { "error": "Generating the songs: Not enough credits — a generation costs 4.", "code": 412, "cost": 4 } ``` **422** **422 Unprocessable Entity** Sync mode, ACE Music could not make either song. The body is the failed job record, the same shape as the `ref_no_melody` example under `400`, with `code: 422`, ACE Music's reason and code in `error` and each song's own `error`. A song shows `refunded: true` when ACE Music gave its credits back. **429** **429 Too Many Requests** The account named by `email`, or the account that holds the references, is running its `maxJobs`. Without them, every account is. ACE Music can answer `429` itself while songs of the account are still being made. Retry after the `Retry-After` header (30 seconds). ```json { "error": "Account example@example.com is running 4 of 4 jobs (maxJobs). Wait for one to finish, or raise maxJobs with POST /accounts", "code": 429 } ``` ```json { "error": "All 3 usable ACE Music accounts are running their maximum number of jobs (maxJobs), please retry shortly", "code": 429 } ``` **502** **502 Bad Gateway** ACE Music may have accepted the request, and charged for it, but its answer was lost, or it answered with something unexpected after accepting it. Check [GET /music](/docs/api-acemusic-v1/get-acemusic-music) before you send it again: the songs may be there. **503** **503 Service Unavailable** ACE Music is busy, could not be reached before the request was sent, or the session is being renewed. Nothing was charged: retry after the `Retry-After` header. When ACE Music may have accepted the request but its answer was lost, the API answers `502` (or `504` on a timeout) instead, saying it may already have charged: check [GET /music](/docs/api-acemusic-v1/get-acemusic-music) before you send it again. **504** **504 Gateway Timeout** ACE Music did not answer within 30 seconds after the request was sent: it may have accepted it and charged for it. Check [GET /music](/docs/api-acemusic-v1/get-acemusic-music) before you send it again. ```json { "error": "Generating the songs: ACE Music did not answer within 30 s. It may already have charged for this: check GET /music before retrying", "code": 504 } ``` **596** **596 Account Error** ACE Music refused the stored email and password of the account. Add it again with the current password, see [Setup ACE Music](/docs/start-here/setup-acemusic#if-the-account-needs-attention). ```json { "error": "Account example@example.com: ACE Music refused the stored email and password. Update the password with POST /accounts to resume using this account", "code": 596 } ``` ##### Model The job record. [GET /jobs/`jobid`](/docs/api-acemusic-v1/get-acemusic-jobs-jobid) and the `replyUrl` webhook return the same shape. A failed sync job answers with the HTTP status in `code` and the failed record as the body. <details markdown="block" class="model-details"> <summary>The job record, field by field, and the types it uses (<code>Song</code>, <code>Output</code>, <code>ErrorInfo</code>)</summary> ```typescript { // TypeScript, all fields are optional jobid: string // the job's id, `j…-u<id>-email:<email>-task:…-bot:acemusic`. It names the account and // the song or songs the job is about. Read the job with GET /jobs/{jobid} type: 'music' | 'stems' // music: POST /music. stems: POST /music/stems status: 'processing' | 'completed' | 'failed' // processing: ACE Music is making the songs or the split (every job // starts here). completed: done, a song job once at least one of its two songs succeeded. // failed: done without a result, error says why and code is the HTTP status email: string // the ACE Music account the job runs on created: string // ISO 8601 completed?: string // ISO 8601, when the job completed or failed model?: string // music: the model you asked for modelUsed?: string // music: the model that made the songs. It differs from model when the request ran on // another one: a request that must read a song (a mashup, a cover asked on acemusic-v1, a // prompt with more than one reference on ace-step-1.5-xl) runs on acemusic-v1.1, and ACE // Music can also switch a request itself songs?: (Song | DeletedSong)[] // music: the request's two songs, see Song below. A song deleted since, with // DELETE /music/{songId} or on acemusic.ai, is a DeletedSong stems?: { // on a stems job: the split mode: 'vocals' | 'all' // the split you asked for songId: string // the song that was split songStatus?: 'deleted' // the song was deleted, its stems went with it (the job failed with code 404) tracks: { // one per stem type: string // vocals: vocal, instrumental. all: vocals, `backing_vocals`, drums, bass, guitar, // keyboard, strings, synth, woodwinds, fx (the stems ACE Music found) url: string | null // signed mp3 link, valid 24 hours duration?: number // seconds }[] expires?: string // ISO 8601, when the track links stop working (read the job again for fresh ones) } error?: string // status 'failed': why code?: number // status failed: the HTTP status of the failure. 400: ACE Music could not read a // referenced song's melody (read its score with GET /music/score, then run it again). 404: // the account was removed, or a split's song was deleted. 422: ACE Music could not make // the songs or the split. 504: not finished within 30 minutes (ACE Music may still finish // it). 596: the account was signed out replyUrl?: string // the replyUrl you sent: it receives this record when the job ends replyRef?: string // the replyRef you sent, echoed back job_state: 'pending' | 'in_progress' | 'completed' | 'failed' | 'cancelled' | 'expired' | 'unknown' // where the job is, in the same words for every useapi.net API outputs: Output[] // one entry per file the job made, see Output below error_info?: ErrorInfo // only on a failed job: why, and whether to retry, see ErrorInfo below } ``` **`Song`**: each item of `songs` in the job record above. **`DeletedSong`**: an item of `songs` whose song was deleted since, with DELETE `/music/{songId}` or on acemusic.ai. ```typescript { // TypeScript songId: string // the song's id, as it was taskId: string // ACE Music's own id of the song (so_…) status: 'deleted' // deleted with DELETE /music/{songId} or on acemusic.ai } ``` **`Output`**: each item of `outputs` in the job record above. **`ErrorInfo`**: the `error_info` of a failed job above. </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/acemusic/music" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "prompt": "A short cheerful ukulele tune about a sunny Saturday morning at the farmers market", "model": "ace-step-1.5-xl" }' ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = "https://api.useapi.net/v1/acemusic"; const headers = { "Content-Type": "application/json", "Authorization": `Bearer ${token}` }; const response = await fetch(`${apiUrl}/music`, { method: "POST", headers, body: JSON.stringify({ style: "synthwave, retro drum machine, warm analog pads, male vocals", lyrics: "[Verse]\nMorning light on the window pane\n[Chorus]\nHold on, the day is new", model: "acemusic-v1", async: true }) }); let job = await response.json(); console.log("submitted", response.status, job.jobid); while (job.status === "processing") { await new Promise(r => setTimeout(r, 10000)); job = await (await fetch(`${apiUrl}/jobs/${encodeURIComponent(job.jobid)}`, { headers })).json(); console.log(job.status); } if (job.status === "completed") job.songs.forEach(song => console.log(song.title, 'store:', song.audioUrl, 'play:', song.playUrl)); else console.log("error", job.code, job.error); ``` **Python** ``` python import time import requests from urllib.parse import quote token = "API token" apiUrl = "https://api.useapi.net/v1/acemusic" headers = {"Content-Type": "application/json", "Authorization": f"Bearer {token}"} data = { "style": "synthwave, retro drum machine, warm analog pads, male vocals", "lyrics": "[Verse]\nMorning light on the window pane\n[Chorus]\nHold on, the day is new", "model": "acemusic-v1", "async": True } job = requests.post(f"{apiUrl}/music", headers=headers, json=data).json() print("submitted", job.get("jobid")) while job.get("status") == "processing": time.sleep(10) job = requests.get(f"{apiUrl}/jobs/{quote(job['jobid'], safe='')}", headers=headers).json() print(job.get("status")) if job.get("status") == "completed": for song in job["songs"]: print(song["title"], "store:", song["audioUrl"], "play:", song.get("playUrl")) else: print("error", job.get("code"), job.get("error")) ``` === URL: https://useapi.net/docs/start-here/setup-dreamina === Document URL: https://useapi.net/docs/start-here/setup-dreamina --- layout: default title: Setup Dreamina description: "How to set up Dreamina for the useapi.net API — connect your account and start generating via the API." parent: Start Here nav_order: 230 --- # <img src="/assets/images/dreamina-logo.png" style="height:1em;vertical-align: middle;" alt=""> Dreamina February 23, 2026 (November 16, 2026) ## Table of contents Approximately 10 minutes to complete setup steps. --- > This is the setup guide for [Dreamina API](/docs/api-dreamina-v1). An active [Dreamina](https://dreamina.capcut.com/) subscription and a [useapi.net subscription](/docs/subscription) are required for the API to work. [Dreamina](https://dreamina.capcut.com/) creates AI-generated videos and images using models from [ByteDance's Seed](https://seed.bytedance.com/) family. The API supports two regions: **US** and **CA** (Canada). Both expose `seedance-2.5`, `seedance-2.5-draft`, `seedance-2.0`, `seedance-2.0-fast`, and `seedance-2.0-mini`, the Seedance 2.0 models at the same resolutions, up to 4K. `seedance-2.5` goes up to 1080p on US and 4K on CA, and `seedance-2.5-flash` is CA only. The image models differ. `seedream-5.5`, `seedream-5.0-lite`, `seedream-4.7`, `seedream-3.1` and `nano-banana-2.1` are CA only, and `seedream-5.0-flash` is US only. See the [Cost calculator](#cost-calculator) below for per-region pricing. CA is the only region offering `happyhorse-1.1`, `wan-3.0` and the Seedance 1.0 Pro and Fast models. `seedance-1.5-pro` and `seedance-1.0-mini` are US only. ### VPN setup A VPN with a US or Canadian IP address is required to create a Dreamina account. The VPN is only needed for browser-based account creation — the API handles all requests through its own proxy infrastructure. **For US region accounts:** [Opera](https://www.opera.com/) browser has a built-in free VPN. 1. Download and install [Opera](https://www.opera.com/) if you don't have it already 2. Enable the built-in VPN by clicking the **VPN** badge in the address bar 3. Set the VPN region to **Americas** 4. Verify the VPN is active — you should see "Protected" and an Americas IP address ![](/assets/images/setup-dreamina-1.jpg) **For CA region accounts:** Opera's free VPN does not support the Canadian region. You will need a commercial VPN service that offers Canadian server locations (e.g., NordVPN, ExpressVPN, Surfshark, or similar). Set your VPN to a **Canada** server before creating the account. ### Create a Dreamina account **Use a dedicated email account for this API — do NOT use your personal email.** 1. Navigate to [https://dreamina.capcut.com/](https://dreamina.capcut.com/) with your VPN active and set to the desired region (Americas for US, Canada for CA) 2. Verify your region by checking the URL — US accounts will see `dreamina.capcut.com`, CA accounts may see a Canadian IP in the VPN indicator 3. Click **Sign in** in the bottom-left corner 4. Select **Continue with email** from the login options ![](/assets/images/setup-dreamina-2.jpg) 5. Click **Sign up** to create a new account 6. Enter your **email address** and choose a **password** 7. Click **Continue** to complete registration ![](/assets/images/setup-dreamina-3.jpg) You may need to verify your email address by entering a code sent to your inbox. ### Verify available models Before adding your account to the API, confirm that the desired Seedance models are available: 1. Navigate to [https://dreamina.capcut.com/ai-tool/generate](https://dreamina.capcut.com/ai-tool/generate) 2. Select **AI Video** from the mode selector at the bottom 3. Click the model name to open the model dropdown and verify that your desired models (e.g., Seedance 2.0 Fast, Seedance 2.0) are listed ![](/assets/images/setup-dreamina-5.jpg) If you don't see Seedance 2.0 models, your account may have been created in the wrong region. Create a new account with the correct VPN region. We recommend starting with the **Basic plan** to verify that subscription and generation work end-to-end before upgrading to the **Advanced plan**. The model dropdown is only an advertisement — Dreamina sometimes lists models that fail at execution for a given region or account. Running one successful generation on the Basic plan confirms the model actually works for your account before you commit to a larger plan. ### Verify and add account Use the form below to verify your credentials and add your Dreamina account. Select **Add Account** to complete setup, or **Verify** to test your credentials first. You should receive response `200` if successful. You can also use [POST /accounts](/docs/api-dreamina-v1/post-dreamina-accounts) directly. <script> async function apiTestAccountDreamina(addAccount) { data = { method: 'POST', headers: { 'Authorization': `Bearer ${document.getElementById('post-accounts-Dreamina-api_token').value}`, 'Content-Type': 'application/json' } }; let email = document.getElementById('post-accounts-Dreamina-email')?.value; let password = document.getElementById('post-accounts-Dreamina-password')?.value; let region = document.getElementById('post-accounts-Dreamina-region')?.value || 'CA'; const body = { email, password, region }; if (!addAccount) body.dryRun = true; data.body = JSON.stringify(body); await apiExecute('https://api.useapi.net/v1/dreamina/accounts', 'post-accounts-Dreamina', data); } </script> <form id="post-accounts-Dreamina" onsubmit="apiTestAccountDreamina(document.getElementById('post-accounts-Dreamina-action').value === 'add'); return false;" class="input-form"> <div class="input-field"> <div class="input-field-row"> <label for="post-accounts-Dreamina-api_token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="post-accounts-Dreamina-api_token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> <label for="post-accounts-Dreamina-email"><span>Dreamina email</span> <input id="post-accounts-Dreamina-email" type="text" class="input-element" required aria-required="true" placeholder="your-dreamina-email@example.com"> </label> <label for="post-accounts-Dreamina-password"><span>Dreamina password</span> <input id="post-accounts-Dreamina-password" type="text" class="input-element" required aria-required="true"> </label> <label for="post-accounts-Dreamina-region"><span>region</span> <select id="post-accounts-Dreamina-region" class="input-element"> <option value="CA">CA (Canada)</option> <option value="US">US</option> </select> </label> <label for="post-accounts-Dreamina-action"><span>action</span> <select id="post-accounts-Dreamina-action" class="input-element"> <option value="verify">Verify — test credentials only</option> <option value="add">Add Account — required to complete setup</option> </select> </label> </div> <button id="post-accounts-Dreamina-button" class="btn btn-primary fs-3" type="submit">Go</button> </div> </form> <div id="post-accounts-Dreamina-response" class="response-placeholder visible-false"></div> ### Cost calculator On Seedance 2.5 (Flash and Draft included), billed seconds are the output duration plus every input video attached, rounded down to a whole second. Every other model bills the output duration only. A Seedance 2.5 edit counts its source video twice, once as an input and once as the output. Two live CA generations on 2026-09-07 landed on the predicted figure exactly: a 21.3-second edit billed 42 seconds (756 credits) and a 35-second long video built from a 21.3-second reference billed 56 (1,680). Dollars per second on the Advanced subscription billed monthly: US $79 for 8,645 credits, Canada C$109.99 for 11,997 credits, converted at CAD/USD 0.7023 (as of November 12, 2026). | Model | US $/sec | CA $/sec | |-------|---------:|---------:| | Seedance 2.5 @480p, with a video reference | $0.128 | $0.116 | | Seedance 2.5 @480p | $0.155 | $0.142 | | Seedance 2.5 @720p | $0.338 | $0.245 | | Seedance 2.5 @1080p | $0.832 | $0.753 | | Seedance 2.5 @4K, with a video reference | — | $0.586 | | Seedance 2.5 @4K | — | $0.831 | | Seedance 2.5 long video @480p | $0.210 | $0.193 | | Seedance 2.5 long video @720p | $0.411 | $0.373 | | Seedance 2.5 long video @1080p | $0.923 | $0.837 | | Seedance 2.5 long video @4K | — | $0.914 | | Seedance 2.5 Flash @480p | — | $0.071 | | Seedance 2.5 Flash @720p | — | $0.155 | | Seedance 2.5 Draft @480p | $0.119 | $0.109 | | Seedance 2.0 @720p | $0.155 | $0.148 | | Seedance 2.0 @1080p | $0.375 | $0.367 | | Seedance 2.0 @4K | $0.896 | $0.811 | | Seedance 2.0 Fast @720p | $0.073 | $0.064 | | Seedance 2.0 Fast @1080p | $0.128 | $0.097 | | Seedance 2.0 Fast @2K | $0.155 | $0.116 | | Seedance 2.0 Fast @4K | $0.201 | $0.148 | | Seedance 2.0 Mini @720p | $0.046 | $0.045 | | Seedance 2.0 Mini @1080p | $0.101 | $0.084 | | Seedance 2.0 Mini @2K | $0.128 | $0.097 | | Seedance 2.0 Mini @4K | $0.174 | $0.129 | | Seedance 1.5 Pro @720p | $0.183 | — | | HappyHorse 1.1 @720p | — | $0.109 | | HappyHorse 1.1 @1080p | — | $0.148 | | Wan 3.0 @720p | — | $0.109 | | Wan 3.0 @1080p | — | $0.270 | Seedance 2.5 bills a reference video's duration on top of the output, so a 4-second video from a 5-second reference bills 9 seconds, at the lower with-reference rate, which applies at 480p, and at 4K on Canada accounts. Canada costs up to 28% less per second (on Seedance 2.5 at 720p, and about 25% on Seedance 2.0 Fast and Mini above 720p), because its subscription buys 153 credits per US dollar against 109 in the US, even though each video uses more credits. Canada also has Seedance 2.5 Flash, Seedance 2.5 at 4K, HappyHorse 1.1, Wan 3.0 and Seedance 1.0 Pro and Fast. Credits per image (as of November 12, 2026): | Model | Sizes | US | CA | |-------|-------|----|----| | Seedream 5.5 | 1.5K / 2K | — | 8 / 13 (launch price, normally 11 / 18) | | Seedream 5.0 Pro | 1.5K / 2K / 4K | — / 12 / 18 | 11 / 15 / 23 | | Seedream 5.0 Flash | 1.5K / 2K / 4K | 6 / 6 / 10 | — | | GPT Image 2.5 Flare and Sunburst | 1K / 2K / 4K | 8 / 11 / 13 (launch price, normally 10 / 14 / 17) | 5 / 7 / 8 (launch price, normally 13 / 18 / 22) | | Nano Banana 2.1 | 1K / 2K / 4K | — | 15 / 23 / 47 | | Nano Banana Pro | 1K / 2K / 4K | 42 / 42 / 75 | 53 / 53 / 95 | | GPT Image 2 | 1K / 2K / 4K | 21 / 38 / 48 | 27 / 48 / 61 | Yearly billing lowers the US Advanced subscription to $900 a year ($75 a month), and Canada's to C$1,299.99 a year. [Setup Dreamina](/docs/start-here/setup-dreamina#cost-calculator) has the credits behind each rate. Credits per second behind those rates, from each region's own price metadata (every row checked again on November 12, 2026): | Model | US cr/sec | CA cr/sec | |-------|----------:|----------:| | Seedance 2.5 @480p, with a video reference | 14 | 18 | | Seedance 2.5 @480p | 17 | 22 | | Seedance 2.5 @720p | 37 | 38 | | Seedance 2.5 @1080p | 91 | 117 | | Seedance 2.5 @4K, with a video reference | — | 91 | | Seedance 2.5 @4K | — | 129 | | Seedance 2.5 long video @480p | 23 | 30 | | Seedance 2.5 long video @720p | 45 | 58 | | Seedance 2.5 long video @1080p | 101 | 130 | | Seedance 2.5 long video @4K | — | 142 | | Seedance 2.5 Flash @480p | — | 11 | | Seedance 2.5 Flash @720p | — | 24 | | Seedance 2.5 Draft @480p | 13 | 17 | | Seedance 2.0 @720p | 17 | 23 | | Seedance 2.0 @1080p | 41 | 57 | | Seedance 2.0 @4K | 98 | 126 | | Seedance 2.0 Fast @720p | 8 | 10 | | Seedance 2.0 Fast @1080p | 14 | 15 | | Seedance 2.0 Fast @2K | 17 | 18 | | Seedance 2.0 Fast @4K | 22 | 23 | | Seedance 2.0 Mini @720p | 5 | 7 | | Seedance 2.0 Mini @1080p | 11 | 13 | | Seedance 2.0 Mini @2K | 14 | 15 | | Seedance 2.0 Mini @4K | 19 | 20 | | Seedance 1.5 Pro @720p | 20 | — | | HappyHorse 1.1 @720p | — | 17 | | HappyHorse 1.1 @1080p | — | 23 | | Wan 3.0 @720p | — | 17 | | Wan 3.0 @1080p | — | 42 | Rates move: on August 14, 2026 a US Seedance 2.5 video at 720p with a video reference used 27 credits a second, and it now uses 37, the same as without one. Treat the tables as a snapshot. Long video, any `duration` from 31 to 180 seconds, is priced on its own higher scale — on CA 30 credits a second at 480p against 22 for an ordinary generation without a reference, and 58 against 38 at 720p — and gets no reference discount at all. <details markdown="block"> <summary>Show the math</summary> Dollars per credit, from the Advanced subscription billed monthly: | Region | Plan | Credits/month | Per credit | Credits per USD | |--------|------|--------------:|-----------:|----------------:| | US | $79/mo | 8,645 | $0.009138 | 109.4 | | CA | C$109.99/mo = $77.24 | 11,997 | $0.006438 | 155.3 | Both were read on 2026-11-12 from Dreamina's US and Canadian price lists, with CA converted at CAD/USD 0.702266. Billed yearly, US is $900 a year ($75 a month, $0.008676 a credit) and CA is C$1,299.99 a year (about C$108.33 a month, $0.006341 a credit). First-month and first-year prices are promotional and not used here. Failed generations are not charged. </details> ### Important notes - **First generation via browser** — after setting up your account, generate at least one video using the Dreamina website (e.g., a short Seedance 2.0 Fast clip in Omni Reference mode) to ensure the service is working and to accept the Terms of Service. This is a one-time step before using the API. - **VPN not required for API usage** — the VPN is only needed for creating the Dreamina account in the browser. The API handles all requests through its own proxy infrastructure. - **Region is permanent** — use the same region for the account as the VPN used during creation. US accounts must use `region: "US"`, Canadian accounts must use `region: "CA"`. - **Session management** — the API automatically manages your Dreamina session, including refreshing expired sessions. If you see `596` errors, check [GET /accounts](/docs/api-dreamina-v1/get-dreamina-accounts) first: an account with `signedOutPauseUntil` is paused for 30 minutes after Dreamina signed it out right after a fresh sign-in, and comes back by itself. Otherwise re-add your account via [POST /accounts](/docs/api-dreamina-v1/post-dreamina-accounts). - **Avoid using the same account** simultaneously through both the API and the Dreamina website — it should work, but to play safe it's better to avoid potential session conflicts. - **Avoid logging in from other regions** — do not log in to your Dreamina account from any region other than the one used during creation, as it may change the account's default region. - **Free credits** — new Dreamina accounts receive free credits. Check your balance via [GET /accounts/`account`](/docs/api-dreamina-v1/get-dreamina-accounts-account). === URL: https://useapi.net/docs/api-dreamina-v1/delete-dreamina-accounts-account === Document URL: https://useapi.net/docs/api-dreamina-v1/delete-dreamina-accounts-account --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> accounts/`account` description: "Delete a configured Dreamina account via DELETE accounts/account in the useapi.net Dreamina API v1, removing it from configuration and cleaning up active jobs." parent: Dreamina API nav_order: 400 --- ## Delete Account Configuration February 23, 2026 (November 16, 2026) --- Delete a configured Dreamina account. This removes the account from your configuration and cleans up any executing job entries. **Warning:** This action cannot be undone. You will need to reconfigure the account using [POST /accounts](/docs/api-dreamina-v1/post-dreamina-accounts) if you want to use it again. > **https://api.useapi.net/v1/dreamina/accounts/`account`** ### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Path Parameters - `account` is **required**. ### Responses **200** **200 OK** Account deleted successfully. ```json { "account": "US:user@example.com", "deleted": true, "remaining": 0 } ``` - `remaining` - Number of other accounts still configured. **401** **401 Unauthorized** Invalid API token. ```json { "error": "Unauthorized" } ``` **404** **404 Not Found** The account is not configured. The response has no body. ### Examples **Curl** ``` bash curl -X DELETE \ -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v1/dreamina/accounts/US:user@example.com" ``` **JavaScript** ``` javascript const token = 'YOUR_API_TOKEN'; const account = 'US:user@example.com'; const response = await fetch( `https://api.useapi.net/v1/dreamina/accounts/${encodeURIComponent(account)}`, { method: 'DELETE', headers: { 'Authorization': `Bearer ${token}` } } ); const result = await response.json(); console.log('Delete result:', result); ``` **Python** ``` python import requests from urllib.parse import quote token = 'YOUR_API_TOKEN' account = 'US:user@example.com' headers = {'Authorization': f'Bearer {token}'} response = requests.delete( f'https://api.useapi.net/v1/dreamina/accounts/{quote(account, safe="")}', headers=headers ) print('Delete result:', response.json()) ``` ### Try It <script> async function apiExecuteDeleteDreaminaAccountsAccount() { const tokenElement = document.getElementById('input-token'); const accountElement = document.getElementById('input-account'); const data = { method: 'DELETE', headers: { 'Authorization': `Bearer ${tokenElement.value}` } }; await apiExecute( `https://api.useapi.net/v1/dreamina/accounts/${encodeURIComponent(accountElement.value)}`, 'input', data ); } </script> <form id="input" class="input-form" onsubmit="return false;"> <div class="input-field"> <div class="input-field-row"> <label for="input-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="input-token" type="text" class="input-element" required aria-required="true"> </label> <label for="input-account"><span>account (required)</span> <input id="input-account" type="text" class="input-element" required aria-required="true" placeholder="US:user@example.com"> </label> </div> <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteDeleteDreaminaAccountsAccount()">Go</button> </div> </form> <div id="input-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-dreamina-v1/delete-dreamina-assets-assetid === Document URL: https://useapi.net/docs/api-dreamina-v1/delete-dreamina-assets-assetid --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> assets/`assetId` description: "Delete an image or video asset from Dreamina generation history by assetId via DELETE assets/assetId in the useapi.net Dreamina API v1." parent: Dreamina API nav_order: 520 --- ## Delete Asset March 2, 2026 (November 16, 2026) --- Delete a specific asset (image or video) from generation history. The `assetId` is obtained from [GET /assets/`account`](/docs/api-dreamina-v1/get-dreamina-assets-account), completed [GET /images/`jobid`](/docs/api-dreamina-v1/get-dreamina-images-jobid), or [GET /videos/`jobid`](/docs/api-dreamina-v1/get-dreamina-videos-jobid) results. > **https://api.useapi.net/v1/dreamina/assets/`assetId`** ### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Path Parameters - `assetId` is **required**. ### Responses **200** **200 OK** Asset deleted successfully. ```json { "deleted": true, "assetId": "US:user@example.com-306191111942:7612453183683579150", "account": "US:user@example.com" } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "Unauthorized" } ``` **400** **400 Bad Request** The account is not configured. ```json { "error": "Unable to find configuration for account US:user@example.com. Please add configuration via POST /v1/dreamina/accounts", "code": 400 } ``` ### Examples **Curl** ``` bash curl -X DELETE \ -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v1/dreamina/assets/US:user@example.com-306191111942:7612453183683579150" ``` **JavaScript** ``` javascript const token = 'YOUR_API_TOKEN'; const assetId = 'US:user@example.com-306191111942:7612453183683579150'; const response = await fetch( `https://api.useapi.net/v1/dreamina/assets/${encodeURIComponent(assetId)}`, { method: 'DELETE', headers: { 'Authorization': `Bearer ${token}` } } ); const result = await response.json(); console.log('Delete result:', result); ``` **Python** ``` python import requests from urllib.parse import quote token = 'YOUR_API_TOKEN' asset_id = 'US:user@example.com-306191111942:7612453183683579150' response = requests.delete( f'https://api.useapi.net/v1/dreamina/assets/{quote(asset_id, safe="")}', headers={'Authorization': f'Bearer {token}'} ) print('Delete result:', response.json()) ``` ### Try It <script> async function apiExecuteDeleteDreaminaAssetsAssetId() { const tokenElement = document.getElementById('input-token'); const assetIdElement = document.getElementById('input-assetid'); const data = { method: 'DELETE', headers: { 'Authorization': `Bearer ${tokenElement.value}` } }; await apiExecute( `https://api.useapi.net/v1/dreamina/assets/${encodeURIComponent(assetIdElement.value)}`, 'input', data ); } </script> <form id="input" class="input-form" onsubmit="return false;"> <div class="input-field"> <div class="input-field-row"> <label for="input-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="input-token" type="text" class="input-element" required aria-required="true"> </label> <label for="input-assetid"><span>assetId (required, from <a href="/docs/api-dreamina-v1/get-dreamina-assets-account">GET /assets/account</a>)</span> <input id="input-assetid" type="text" class="input-element" required aria-required="true" placeholder="US:user@example.com-306191111942:7612453183683579150"> </label> </div> <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteDeleteDreaminaAssetsAssetId()">Go</button> </div> </form> <div id="input-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-dreamina-v1/delete-dreamina-scheduler-jobid === Document URL: https://useapi.net/docs/api-dreamina-v1/delete-dreamina-scheduler-jobid --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> scheduler/`jobid` description: "Remove a Dreamina generation job from the executing tracker via DELETE scheduler/jobid in the useapi.net Dreamina API v1 — cancels it and marks in-progress entries as failed." parent: Dreamina API nav_order: 810 --- ## Cancel Executing Job February 23, 2026 (November 16, 2026) --- Remove a job from the executing tracker and cancel it. If the job is still in `created` status, it will be marked as failed with the reason "Cancelled by user". > **https://api.useapi.net/v1/dreamina/scheduler/`jobid`** ### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Path Parameters - `jobid` is **required**. The job ID to remove from the scheduler. ### Responses **200** **200 OK** Job removed from scheduler. ```json { "jobid": "j0223140530123456789v-u12345-US:user@example.com-bot:dreamina", "removed": true } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "Unauthorized" } ``` **403** **403 Forbidden** The job belongs to a different useapi.net user. ```json { "error": "No access to account US:user@example.com", "code": 403 } ``` ### Examples **Curl** ``` bash curl -X DELETE \ -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v1/dreamina/scheduler/j0223140530123456789v-u12345-US:user@example.com-bot:dreamina" ``` **JavaScript** ``` javascript const token = 'YOUR_API_TOKEN'; const jobid = 'j0223140530123456789v-u12345-US:user@example.com-bot:dreamina'; const response = await fetch( `https://api.useapi.net/v1/dreamina/scheduler/${jobid}`, { method: 'DELETE', headers: { 'Authorization': `Bearer ${token}` } } ); const result = await response.json(); console.log('Cancel result:', result); ``` **Python** ``` python import requests token = 'YOUR_API_TOKEN' jobid = 'j0223140530123456789v-u12345-US:user@example.com-bot:dreamina' headers = {'Authorization': f'Bearer {token}'} response = requests.delete( f'https://api.useapi.net/v1/dreamina/scheduler/{jobid}', headers=headers ) print('Cancel result:', response.json()) ``` ### Try It <script> async function apiExecuteDeleteDreaminaSchedulerJobId() { const tokenElement = document.getElementById('input-token'); const jobidElement = document.getElementById('input-jobid'); const data = { method: 'DELETE', headers: { 'Authorization': `Bearer ${tokenElement.value}` } }; await apiExecute( `https://api.useapi.net/v1/dreamina/scheduler/${jobidElement.value}`, 'input', data ); } </script> <form id="input" class="input-form" onsubmit="return false;"> <div class="input-field"> <div class="input-field-row"> <label for="input-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="input-token" type="text" class="input-element" required aria-required="true"> </label> <label for="input-jobid"><span>jobid (required)</span> <input id="input-jobid" type="text" class="input-element" required aria-required="true"> </label> </div> <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteDeleteDreaminaSchedulerJobId()">Go</button> </div> </form> <div id="input-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-dreamina-v1/get-dreamina-accounts-account === Document URL: https://useapi.net/docs/api-dreamina-v1/get-dreamina-accounts-account --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts/`account` description: "Retrieve a Dreamina account's session status, available models, and credit balance via GET accounts/account in the useapi.net Dreamina API v1." parent: Dreamina API nav_order: 350 --- ## Get Account Configuration February 23, 2026 (November 16, 2026) --- Get configuration details for a specific Dreamina account, including session status, available models, and credit balance. Can also be called once a day to claim free daily credits. > **https://api.useapi.net/v1/dreamina/accounts/`account`** ### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Path Parameters - `account` is **required**. ### Responses **200** **200 OK** Account details retrieved with live data from upstream. ```json { "account": "US:user@example.com", "email": "user@example.com", "region": "US", "maxJobs": 10, "sessionExpires": "2026-04-24T12:00:00.000Z", "session": { "expires": "2026-04-24T12:00:00.000Z", "lastRefreshed": "2026-02-23T12:00:00.000Z", "daysUntilExpiry": 60 }, "models": { "video": ["seedance-2.5-draft", "seedance-2.5", "seedance-2.0-mini", "seedance-2.0-fast", "seedance-2.0", "seedance-1.5-pro", "seedance-1.0-mini"], "image": ["gpt-image-2", "gpt-image-2.5-flare", "gpt-image-2.5-sunburst", "nano-banana-pro", "seedream-5.0-pro", "seedream-5.0-flash", "seedream-4.6", "seedream-4.5", "seedream-4.1", "seedream-4.0", "seedream-3.0"] }, "credits": { "total": 24065, "vip": 12000, "gift": 10065, "purchase": 2000, "dailyClaimed": true } } ``` **Note:** The `models`, `credits`, and `session` fields are fetched live from upstream. If upstream queries fail, a summary without these fields is returned. An account in its sign-out pause also carries `signedOutPauseUntil`. When Dreamina signs an account out again right after a fresh sign-in, the account is paused for 30 minutes. While the pause runs, [GET /accounts](/docs/api-dreamina-v1/get-dreamina-accounts) shows `signedOutPauseUntil` (an ISO 8601 time) on that account, requests that name it answer `596`, and automatic account selection uses your other accounts. When every account is paused, requests answer `596`. After the pause the account is used again. If Dreamina signs it out right after a fresh sign-in again, after the pause and within 24 hours, the account is marked with an `error` and answers `596` until you re-add it with [POST /accounts](/docs/api-dreamina-v1/post-dreamina-accounts). Re-adding an account also ends its pause. A sign-in that fails for a temporary reason, not because Dreamina refused the account, answers `503` with a `Retry-After: 30` header. The account is fine: retry in about 30 seconds. **401** **401 Unauthorized** Invalid API token. ```json { "error": "Unauthorized" } ``` **404** **404 Not Found** The account is not configured. The response has no body. ### Model The account's region, `maxJobs`, session expiry, available models and credit balance, and an `error` when the account must be re-added. <details markdown="block" class="model-details"> <summary>The account's session, models and credits, field by field</summary> ```typescript { account: string // "US:user@example.com" email: string region: string // "US" maxJobs: number // 1-50 sessionExpires: string // ISO 8601 timestamp session?: { expires: string // ISO 8601 timestamp lastRefreshed: string // ISO 8601 timestamp daysUntilExpiry: number } models?: { video: string[] // Available video model names image: string[] // Available image model names } credits?: { total: number vip: number gift: number purchase: number dailyClaimed: boolean } error?: string // Error message; the account answers 596 until re-added signedOutPauseUntil?: string // ISO 8601 timestamp, only while the account's sign-out pause runs } ``` </details> ### Examples **Curl** ``` bash curl -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v1/dreamina/accounts/US:user@example.com" ``` **JavaScript** ``` javascript const token = 'YOUR_API_TOKEN'; const account = 'US:user@example.com'; const response = await fetch( `https://api.useapi.net/v1/dreamina/accounts/${encodeURIComponent(account)}`, { headers: { 'Authorization': `Bearer ${token}` } } ); const accountConfig = await response.json(); console.log('Account:', accountConfig); console.log('Credits:', accountConfig.credits); console.log('Models:', accountConfig.models); ``` **Python** ``` python import requests from urllib.parse import quote token = 'YOUR_API_TOKEN' account = 'US:user@example.com' headers = {'Authorization': f'Bearer {token}'} response = requests.get( f'https://api.useapi.net/v1/dreamina/accounts/{quote(account, safe="")}', headers=headers ) account_config = response.json() print('Account:', account_config) print('Credits:', account_config.get('credits')) print('Models:', account_config.get('models')) ``` ### Try It <script> async function apiExecuteGetDreaminaAccountsAccount() { const tokenElement = document.getElementById('input-token'); const accountElement = document.getElementById('input-account'); const data = { method: 'GET', headers: { 'Authorization': `Bearer ${tokenElement.value}` } }; await apiExecute( `https://api.useapi.net/v1/dreamina/accounts/${encodeURIComponent(accountElement.value)}`, 'input', data ); } </script> <form id="input" class="input-form" onsubmit="return false;"> <div class="input-field"> <div class="input-field-row"> <label for="input-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="input-token" type="text" class="input-element" required aria-required="true"> </label> <label for="input-account"><span>account (required)</span> <input id="input-account" type="text" class="input-element" required aria-required="true" placeholder="US:user@example.com"> </label> </div> <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteGetDreaminaAccountsAccount()">Go</button> </div> </form> <div id="input-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-dreamina-v1/get-dreamina-accounts === Document URL: https://useapi.net/docs/api-dreamina-v1/get-dreamina-accounts --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts description: "List all configured Dreamina accounts via GET accounts in the useapi.net Dreamina API v1 — quick overview without live session details." parent: Dreamina API nav_order: 300 --- ## List All Configured Accounts February 23, 2026 (November 16, 2026) --- List all configured Dreamina accounts. To get a specific account with live details use [GET /accounts/`account`](/docs/api-dreamina-v1/get-dreamina-accounts-account). > **https://api.useapi.net/v1/dreamina/accounts** ### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Responses **200** **200 OK** Returns a map of all configured accounts, keyed by account identifier. ```json { "US:user@example.com": { "account": "US:user@example.com", "email": "user@example.com", "region": "US", "maxJobs": 10, "sessionExpires": "2026-04-24T12:00:00.000Z" } } ``` If no accounts are configured, the answer is `404` with no body. An account in its sign-out pause also carries `signedOutPauseUntil`, and a marked account carries `error`: ```json { "US:user@example.com": { "account": "US:user@example.com", "email": "user@example.com", "region": "US", "maxJobs": 10, "sessionExpires": "2026-04-24T12:00:00.000Z", "signedOutPauseUntil": "2026-11-01T18:30:00.000Z" } } ``` When Dreamina signs an account out again right after a fresh sign-in, the account is paused for 30 minutes. While the pause runs, [GET /accounts](/docs/api-dreamina-v1/get-dreamina-accounts) shows `signedOutPauseUntil` (an ISO 8601 time) on that account, requests that name it answer `596`, and automatic account selection uses your other accounts. When every account is paused, requests answer `596`. After the pause the account is used again. If Dreamina signs it out right after a fresh sign-in again, after the pause and within 24 hours, the account is marked with an `error` and answers `596` until you re-add it with [POST /accounts](/docs/api-dreamina-v1/post-dreamina-accounts). Re-adding an account also ends its pause. A sign-in that fails for a temporary reason, not because Dreamina refused the account, answers `503` with a `Retry-After: 30` header. The account is fine: retry in about 30 seconds. **401** **401 Unauthorized** Invalid API token. ```json { "error": "Unauthorized" } ``` ### Model An object keyed by account identifier, such as `US:user@example.com`, each value with its region, `maxJobs` and session expiry. <details markdown="block" class="model-details"> <summary>The accounts, keyed by account id, field by field</summary> ```typescript // Map of account identifier to account summary { [account: string]: { account: string // "US:user@example.com" email: string region: string // "US" maxJobs: number sessionExpires: string // ISO 8601 timestamp error?: string // Error message if account has issues; the account answers 596 until re-added signedOutPauseUntil?: string // ISO 8601 timestamp, only while the account's sign-out pause runs } } ``` </details> ### Examples **Curl** ``` bash curl -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v1/dreamina/accounts" ``` **JavaScript** ``` javascript const token = 'YOUR_API_TOKEN'; const response = await fetch('https://api.useapi.net/v1/dreamina/accounts', { headers: { 'Authorization': `Bearer ${token}` } }); const accounts = await response.json(); console.log('Configured accounts:', accounts); ``` **Python** ``` python import requests token = 'YOUR_API_TOKEN' headers = {'Authorization': f'Bearer {token}'} response = requests.get('https://api.useapi.net/v1/dreamina/accounts', headers=headers) print('All accounts:', response.json()) ``` ### Try It <script> async function apiExecuteGetDreaminaAccounts() { const tokenElement = document.getElementById('input-token'); const data = { method: 'GET', headers: { 'Authorization': `Bearer ${tokenElement.value}` } }; await apiExecute('https://api.useapi.net/v1/dreamina/accounts', 'input', data); } </script> <form id="input" class="input-form" onsubmit="return false;"> <div class="input-field"> <div class="input-field-row"> <label for="input-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="input-token" type="text" class="input-element" required aria-required="true"> </label> </div> <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteGetDreaminaAccounts()">Go</button> </div> </form> <div id="input-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-dreamina-v1/get-dreamina-assets-account === Document URL: https://useapi.net/docs/api-dreamina-v1/get-dreamina-assets-account --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> assets/`account` description: "Retrieve Dreamina generation history for an account via GET assets/account in the useapi.net Dreamina API v1 — asset URLs, dimensions, and assetRef for images (videos return a videoUrl)." parent: Dreamina API nav_order: 510 --- ## List Generation History March 2, 2026 (November 16, 2026) --- List generation history (images and videos) for a specific account. Returns assets with their URLs, dimensions, and reusable `assetRef` values for [POST /images](/docs/api-dreamina-v1/post-dreamina-images) or as in [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos). > **https://api.useapi.net/v1/dreamina/assets/`account`** ### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Path Parameters - `account` is **required**. ### Query Parameters - `count` is optional. Number of assets to return (1-100, default: `20`). - `offset` is optional. Pagination cursor from a previous response's `nextOffset`. ### Responses **200** **200 OK** Returns generation history with asset details. ```json { "assets": [ { "assetId": "US:user@example.com-306191111942:7612453183683579150", "historyRecordId": "306191111942", "itemId": "7612453183683579150", "type": "image", "coverUrl": "https://p9-sign.douyinpic.com/...", "description": "A stunning aurora borealis over a frozen lake", "assetRef": "US:user@example.com-image:w2560:h1440:s905000-uri:tos-useast5-i-wopfjsm1ax-tx/abc123", "imageUrl": "https://p9-sign.douyinpic.com/...", "width": 2560, "height": 1440, "format": "webp", "createdAt": "2026-03-02T14:06:06.000Z" }, { "assetId": "US:user@example.com-306191137798:7612453244173880589", "historyRecordId": "306191137798", "itemId": "7612453244173880589", "type": "video", "coverUrl": "https://p9-sign.douyinpic.com/...", "description": "A cinematic drone shot", "videoUrl": "https://v16m-default.akamaized.net/...", "width": 1280, "height": 720, "createdAt": "2026-03-02T14:08:07.000Z" } ], "hasMore": true, "nextOffset": 20, "account": "US:user@example.com" } ``` - `assetRef` on image assets can be used directly as `imageRef_N` in [POST /images](/docs/api-dreamina-v1/post-dreamina-images) or as `firstFrameRef` in [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos). - `assetId` can be used with [DELETE /assets/`assetId`](/docs/api-dreamina-v1/delete-dreamina-assets-assetid) to remove an asset. - Videos do not have `assetRef` — only a `videoUrl` for download. **401** **401 Unauthorized** Invalid API token. ```json { "error": "Unauthorized" } ``` **400** **400 Bad Request** The account is not configured. ```json { "error": "Unable to find configuration for account US:user@example.com. Please add configuration via POST /v1/dreamina/accounts", "code": 400 } ``` ### Model A page of the account's generated images and videos in `assets`, each with its `assetId`, URLs and dimensions, plus `hasMore` and `nextOffset`. <details markdown="block" class="model-details"> <summary>The list of generated images and videos, field by field</summary> ```typescript { assets: Array<{ assetId: string // ID for DELETE /assets/<assetId> historyRecordId: string itemId: string type: 'image' | 'video' coverUrl?: string // Thumbnail URL description?: string // Generation prompt assetRef?: string // Reusable ref (images only) imageUrl?: string // Full image URL (images only) videoUrl?: string // Video URL (videos only) width?: number height?: number format?: string // Image format (images only) createdAt?: string // ISO 8601 timestamp }> hasMore: boolean // More pages available nextOffset: number // Pass as offset for next page account: string } ``` </details> ### Examples **Curl** ``` bash curl -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v1/dreamina/assets/US:user@example.com?count=10" ``` **JavaScript** ``` javascript const token = 'YOUR_API_TOKEN'; const account = 'US:user@example.com'; const response = await fetch( `https://api.useapi.net/v1/dreamina/assets/${encodeURIComponent(account)}?count=20`, { headers: { 'Authorization': `Bearer ${token}` } } ); const result = await response.json(); console.log(`Assets: ${result.assets.length}, hasMore: ${result.hasMore}`); result.assets.forEach(a => { console.log(` ${a.type} ${a.assetId} ${a.width}x${a.height}`); if (a.assetRef) console.log(` assetRef: ${a.assetRef}`); }); ``` **Python** ``` python import requests from urllib.parse import quote token = 'YOUR_API_TOKEN' account = 'US:user@example.com' response = requests.get( f'https://api.useapi.net/v1/dreamina/assets/{quote(account, safe="")}', headers={'Authorization': f'Bearer {token}'}, params={'count': 20} ) result = response.json() print(f"Assets: {len(result['assets'])}, hasMore: {result['hasMore']}") for a in result['assets']: print(f" {a['type']} {a['assetId']} {a.get('width')}x{a.get('height')}") ``` ### Try It <script> async function apiExecuteGetDreaminaAssetsAccount() { const tokenElement = document.getElementById('input-token'); const accountElement = document.getElementById('input-account'); const countValue = document.getElementById('input-count')?.value; const offsetValue = document.getElementById('input-offset')?.value; const params = new URLSearchParams(); if (countValue) params.set('count', countValue); if (offsetValue) params.set('offset', offsetValue); const qs = params.toString(); const data = { method: 'GET', headers: { 'Authorization': `Bearer ${tokenElement.value}` } }; await apiExecute( `https://api.useapi.net/v1/dreamina/assets/${encodeURIComponent(accountElement.value)}${qs ? '?' + qs : ''}`, 'input', data ); } </script> <form id="input" class="input-form" onsubmit="return false;"> <div class="input-field"> <div class="input-field-row"> <label for="input-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="input-token" type="text" class="input-element" required aria-required="true"> </label> <label for="input-account"><span>account (required)</span> <input id="input-account" type="text" class="input-element" required aria-required="true" placeholder="US:user@example.com"> </label> <label for="input-count"><span>count (1-100, default: 20)</span> <input id="input-count" type="number" class="input-element" min="1" max="100" placeholder="20"> </label> <label for="input-offset"><span>offset (pagination cursor)</span> <input id="input-offset" type="number" class="input-element" placeholder="0"> </label> </div> <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteGetDreaminaAssetsAccount()">Go</button> </div> </form> <div id="input-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-dreamina-v1/get-dreamina-images-jobid === Document URL: https://useapi.net/docs/api-dreamina-v1/get-dreamina-images-jobid --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> images/`jobid` description: "Poll a Dreamina image generation or upscale job for status and results by job ID via GET images/jobid in the useapi.net Dreamina API v1 — jobs retained 30 days." parent: Dreamina API nav_order: 720 --- ## Retrieve Image Job Status March 2, 2026 (November 16, 2026) --- Retrieve the status and result of an image generation or upscale job by its job ID. Use this endpoint to poll for completion after submitting an image via [POST /images](/docs/api-dreamina-v1/post-dreamina-images) or [POST /images/upscale](/docs/api-dreamina-v1/post-dreamina-images-upscale). Jobs are retained for 30 days. > **https://api.useapi.net/v1/dreamina/images/`jobid`** ### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Path Parameters - `jobid` is **required**, the unique job identifier returned from [POST /images](/docs/api-dreamina-v1/post-dreamina-images) or [POST /images/upscale](/docs/api-dreamina-v1/post-dreamina-images-upscale). ### Responses **200** **200 OK** Returns the job record with current status and details. **Processing (status: created):** ```json { "jobid": "j0302140530123456789i-u12345-US:user@example.com-bot:dreamina", "type": "image", "status": "created", "model": "seedream-4.0", "created": "2026-03-02T14:05:30.123Z", "request": { "prompt": "A stunning aurora borealis over a frozen lake", "model": "seedream-4.0", "ratio": "16:9", "resolution": "2k", "inputMode": "generate" }, "response": { "forecastCost": 0 }, "code": 200 } ``` **Completed (image generation):** ```json { "jobid": "j0302140530123456789i-u12345-US:user@example.com-bot:dreamina", "type": "image", "status": "completed", "model": "seedream-4.0", "created": "2026-03-02T14:05:30.123Z", "updated": "2026-03-02T14:06:06.789Z", "request": { "prompt": "A stunning aurora borealis over a frozen lake", "model": "seedream-4.0", "ratio": "16:9", "resolution": "2k", "inputMode": "generate" }, "response": { "images": [ { "imageUrl": "https://p9-sign.douyinpic.com/...", "imageUri": "tos-useast5-i-wopfjsm1ax-tx/abc123", "width": 2560, "height": 1440, "format": "jpeg", "assetId": "US:user@example.com-306191111942:7612453183683579150", "assetRef": "US:user@example.com-image:w2560:h1440:s905000-uri:tos-useast5-i-wopfjsm1ax-tx/abc123", "itemId": "7612453183683579150" }, { "imageUrl": "https://p9-sign.douyinpic.com/...", "imageUri": "tos-useast5-i-wopfjsm1ax-tx/def456", "width": 2560, "height": 1440, "format": "jpeg", "assetId": "US:user@example.com-306191111942:7612453183683595534", "assetRef": "US:user@example.com-image:w2560:h1440:s911000-uri:tos-useast5-i-wopfjsm1ax-tx/def456", "itemId": "7612453183683595534" } ], "forecastCost": 0, "historyRecordId": "306191111942", "finishTime": 1709391966 }, "code": 200 } ``` **Completed (upscale):** ```json { "jobid": "j0302140630123456789I-u12345-US:user@example.com-bot:dreamina", "type": "upscale", "status": "completed", "model": "seedream-4.0", "created": "2026-03-02T14:06:30.123Z", "updated": "2026-03-02T14:08:07.456Z", "request": { "jobid": "j0302140530123456789i-u12345-US:user@example.com-bot:dreamina", "imageIndex": 0, "resolution": "4k" }, "response": { "images": [ { "imageUrl": "https://p9-sign.douyinpic.com/...", "imageUri": "tos-useast5-i-wopfjsm1ax-tx/upscaled123", "width": 4096, "height": 4096, "format": "jpeg", "assetId": "US:user@example.com-306191137798:7612453244173880589", "assetRef": "US:user@example.com-image:w4096:h4096:s1482000-uri:tos-useast5-i-wopfjsm1ax-tx/upscaled123", "itemId": "7612453244173880589" } ], "forecastCost": 0, "historyRecordId": "306191137798", "finishTime": 1709392087 }, "code": 200 } ``` **Note:** The `assetRef` on each image can be used directly as `imageRef_N` in [POST /images](/docs/api-dreamina-v1/post-dreamina-images) for further generations, without needing to re-upload. **Failed:** ```json { "jobid": "j0302140530123456789i-u12345-US:user@example.com-bot:dreamina", "type": "image", "status": "failed", "model": "seedream-4.0", "created": "2026-03-02T14:05:30.123Z", "updated": "2026-03-02T14:07:15.456Z", "request": { "prompt": "A test prompt", "model": "seedream-4.0", "ratio": "16:9", "resolution": "2k", "inputMode": "generate" }, "error": "fail_code: 2050", "errorDetails": "The prompt may contain content that violates our Community Guidelines. Change it and try again.", "failMsg": "InputTextCopyright", "code": 2050 } ``` Jobs still `created` 2 hours after they were submitted are marked as failed with `"Generation timed out after 120m (…)"` (code `408`). `errorDetails` is the sentence Dreamina's website shows, and it reads the same for different filters. `failMsg` is Dreamina's own name for the failure, so you can tell them apart. Common values, all raised after submission — a job that fails this way is not charged: | `code` | `failMsg` | Meaning | Retry? | |---|---|---|---| | `` | `` | | | **401** **401 Unauthorized** Invalid API token. ```json { "error": "Unauthorized" } ``` **403** **403 Forbidden** The job belongs to a different useapi.net user. ```json { "error": "No access to account US:user@example.com", "code": 403 } ``` **404** **404 Not Found** Job not found, or it has expired (>30 days). The response has no body. ### Model The image job with its `status`: a `completed` job lists its images in `response.images`, and a `failed` one carries `error` and `code`. <details markdown="block" class="model-details"> <summary>The image job record for each status, field by field, and notes on partial results and the watermark</summary> **Completed** Image generation completed. Includes image URLs and metadata. ```typescript { jobid: string // Unique job identifier type: 'image' | 'upscale' // Job type status: 'completed' model: string // Model used created: string // ISO 8601 timestamp updated: string // ISO 8601 timestamp request: { prompt?: string model?: string ratio?: string resolution?: string inputMode?: string // Auto-detected from params imageRef_1?: string // Reference image assetRef (when provided) imageRef_2?: string imageRef_3?: string jobid?: string // Source job (upscale only) imageIndex?: number // Source image index (upscale only) replyUrl?: string replyRef?: string } response: { images: Array<{ imageUrl: string // Direct image URL (JPEG) imageUri: string // Native URI width: number // Image width in pixels height: number // Image height in pixels format: string // "jpeg" assetId: string // Asset identifier assetRef: string // Can be used as imageRef_N in POST /images itemId: string // Upstream item ID coverUrl?: string // Small preview of the image, can carry the AI badge, see Watermark }> forecastCost: number // Estimated generation time in seconds, NOT a price historyRecordId: string // Upstream history record finishTime: number // Unix timestamp of completion failedCount?: number // Only when some of the requested images failed: how many (the rest are in images) failCode?: string // Dreamina's code for those, e.g. "23001" } code: number // 200 } ``` **Failed** Image generation failed. Includes error details. ```typescript { jobid: string type: 'image' | 'upscale' status: 'failed' model: string created: string updated: string request: { prompt?: string model?: string ratio?: string resolution?: string inputMode?: string replyUrl?: string replyRef?: string } error: string // Error summary errorDetails?: string // Additional details (the sentence Dreamina's website shows) failMsg?: string // Dreamina's own name for a failure, e.g. "InputTextCopyright", "common error" code: number // Error code } ``` **Common error codes:** | Code | Meaning | |------|---------| | 408 | Generation timed out (no result after 2 hours) | | 596 | Account session expired | | 2038 | Content filtered | | 2057 | Upstream processing error | #### Some images failed Dreamina sometimes finishes a request with fewer images than asked: for example 3 of 4, with the fourth failing under its code `23001` ("common error"). The job is then `completed` with the images that were made, and `response.failedCount` and `response.failCode` say how many failed and why. Dreamina charges only the images it delivered and returns the credits of the failed ones. Sending the same request again usually gives a full set. #### Watermark Dreamina adds an "AI" badge to the top-left corner of generated images unless the account's "close watermark" setting is on. We switch that setting on when you add or re-add an account with [POST accounts](/docs/api-dreamina-v1/post-dreamina-accounts). - On a paid Dreamina plan, `imageUrl` is the clean image. On some paid accounts Dreamina keeps the badge on its preview even with the setting on. For those, `imageUrl` is the clean copy that Dreamina's own Download button saves, at no extra cost. - `coverUrl` is a small preview of the image and can still carry the badge, so use `imageUrl` for the picture you keep or show. - Dreamina doesn't allow the setting on free accounts, so their images keep the badge, in `imageUrl` too. - The URLs are signed, so editing one to remove the badge does not work. </details> ### Examples **Curl** ```bash curl "https://api.useapi.net/v1/dreamina/images/j0302140530123456789i-u12345-US:user@example.com-bot:dreamina" \ -H "Authorization: Bearer YOUR_API_TOKEN" ``` **JavaScript** ```javascript const apiToken = 'YOUR_API_TOKEN' const jobId = 'j0302140530123456789i-u12345-US:user@example.com-bot:dreamina' async function waitForImages(jobId, intervalMs = 10000) { while (true) { const response = await fetch(`https://api.useapi.net/v1/dreamina/images/${jobId}`, { headers: { 'Authorization': `Bearer ${apiToken}` } }) const job = await response.json() console.log(`Status: ${job.status}`) if (job.status === 'completed') { job.response.images.forEach((img, i) => console.log(` [${i}] ${img.width}x${img.height} ${img.format}`) ) return job } if (job.status === 'failed') throw new Error(job.error) await new Promise(resolve => setTimeout(resolve, intervalMs)) } } const job = await waitForImages(jobId) ``` **Python** ```python import requests import time api_token = 'YOUR_API_TOKEN' job_id = 'j0302140530123456789i-u12345-US:user@example.com-bot:dreamina' def wait_for_images(job_id: str, interval_sec: int = 10) -> dict: while True: job = requests.get( f'https://api.useapi.net/v1/dreamina/images/{job_id}', headers={'Authorization': f'Bearer {api_token}'} ).json() print(f"Status: {job['status']}") if job['status'] == 'completed': for i, img in enumerate(job['response']['images']): print(f" [{i}] {img['width']}x{img['height']} {img['format']}") # Download image img_response = requests.get(img['imageUrl']) with open(f'image_{i}.jpeg', 'wb') as f: f.write(img_response.content) return job if job['status'] == 'failed': raise Exception(f"Job failed: {job.get('error')}") time.sleep(interval_sec) job = wait_for_images(job_id) ``` ### Try It <script> function displayDreaminaImageMedia(response, elementId) { const mediaContainer = document.getElementById(`${elementId}-media-links`); if (!mediaContainer) return; mediaContainer.innerHTML = ''; if (response.status === 'completed' && response.response?.images) { const images = response.response.images; if (images.length > 0) { const linksHTML = images.map((img, i) => `<a href="${img.imageUrl}" target="_blank" rel="noopener noreferrer" class="media-link image">Image ${i + 1} (${img.width}x${img.height})</a>` ).join(' '); const typeLabel = response.type === 'upscale' ? 'Upscaled Image' : 'Generated Images'; mediaContainer.innerHTML = `<div class="media-links-container"><strong>${typeLabel}:</strong> ${linksHTML}</div>`; mediaContainer.style.display = 'block'; return; } } mediaContainer.style.display = 'none'; } async function apiExecuteGetDreaminaImagesJobId() { const tokenElement = document.getElementById('input-token'); const jobidElement = document.getElementById('input-jobid'); const elementId = 'input'; const data = { method: 'GET', headers: { 'Authorization': `Bearer ${tokenElement.value}` } }; const mediaLinks = document.getElementById(`${elementId}-media-links`); if (mediaLinks) mediaLinks.style.display = 'none'; const status = await apiExecute( `https://api.useapi.net/v1/dreamina/images/${jobidElement.value}`, elementId, data ); if (status === 200) { try { const content = document.getElementById(`${elementId}-response-json`); const response = JSON.parse(content.innerText); displayDreaminaImageMedia(response, elementId); } catch (e) { console.error('Failed to parse response for media display:', e); } } } </script> <form id="input" class="input-form" onsubmit="return false;"> <div class="input-field"> <div class="input-field-row"> <label for="input-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="input-token" type="text" class="input-element" required aria-required="true"> </label> <label for="input-jobid"><span>jobid (required)</span> <input id="input-jobid" type="text" class="input-element" required aria-required="true"> </label> </div> <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteGetDreaminaImagesJobId()">Go</button> </div> </form> <div id="input-media-links" style="display:none;"></div> <div id="input-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-dreamina-v1/get-dreamina-scheduler === Document URL: https://useapi.net/docs/api-dreamina-v1/get-dreamina-scheduler --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> scheduler description: "List all currently in-progress Dreamina video and image generation jobs via GET scheduler in the useapi.net Dreamina API v1, grouped by account." parent: Dreamina API nav_order: 800 --- ## List Executing Jobs February 23, 2026 (November 16, 2026) --- List all currently executing (in-progress) video and image generation jobs, grouped by account. > **https://api.useapi.net/v1/dreamina/scheduler** ### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Responses **200** **200 OK** Returns executing jobs grouped by account. ```json { "executing": { "US:user@example.com": [ { "jobid": "j0223140530123456789v-u12345-US:user@example.com-bot:dreamina", "submitId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "model": "seedance-2.0", "elapsedSeconds": 45, "replyUrl": "https://your-domain.com/webhook" } ] }, "total": 1 } ``` When no jobs are executing: ```json { "executing": {}, "total": 0 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "Unauthorized" } ``` ### Model The jobs running now, grouped by account in `executing`, each with its `jobid`, model and seconds elapsed, plus the `total`. <details markdown="block" class="model-details"> <summary>The running jobs by account, field by field</summary> ```typescript { executing: { [account: string]: Array<{ jobid: string // Job identifier submitId: string // Upstream submission ID model: string // Model used elapsedSeconds: number // Seconds since job was submitted replyUrl?: string // Webhook URL if configured }> } total: number // Total number of executing jobs } ``` </details> ### Examples **Curl** ``` bash curl -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v1/dreamina/scheduler" ``` **JavaScript** ``` javascript const token = 'YOUR_API_TOKEN'; const response = await fetch('https://api.useapi.net/v1/dreamina/scheduler', { headers: { 'Authorization': `Bearer ${token}` } }); const scheduler = await response.json(); console.log('Executing jobs:', scheduler.total); for (const [account, jobs] of Object.entries(scheduler.executing)) { console.log(` ${account}: ${jobs.length} jobs`); } ``` **Python** ``` python import requests token = 'YOUR_API_TOKEN' headers = {'Authorization': f'Bearer {token}'} response = requests.get('https://api.useapi.net/v1/dreamina/scheduler', headers=headers) scheduler = response.json() print(f"Executing jobs: {scheduler['total']}") for account, jobs in scheduler['executing'].items(): print(f" {account}: {len(jobs)} jobs") ``` ### Try It <script> async function apiExecuteGetDreaminaScheduler() { const tokenElement = document.getElementById('input-token'); const data = { method: 'GET', headers: { 'Authorization': `Bearer ${tokenElement.value}` } }; await apiExecute('https://api.useapi.net/v1/dreamina/scheduler', 'input', data); } </script> <form id="input" class="input-form" onsubmit="return false;"> <div class="input-field"> <div class="input-field-row"> <label for="input-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="input-token" type="text" class="input-element" required aria-required="true"> </label> </div> <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteGetDreaminaScheduler()">Go</button> </div> </form> <div id="input-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-dreamina-v1/get-dreamina-videos-jobid === Document URL: https://useapi.net/docs/api-dreamina-v1/get-dreamina-videos-jobid --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> videos/`jobid` description: "Poll a Dreamina video generation, upscale, or interpolation job for status and results by job ID via GET videos/jobid in the useapi.net Dreamina API v1." parent: Dreamina API nav_order: 700 --- ## Retrieve Job Status March 2, 2026 (November 16, 2026) --- Retrieve the status and result of a video generation, upscale, or interpolation job by its job ID. Use this endpoint to poll for completion after submitting a video via [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos), [POST /videos/full-quality](/docs/api-dreamina-v1/post-dreamina-videos-full-quality), [POST /videos/upscale](/docs/api-dreamina-v1/post-dreamina-videos-upscale), or [POST /videos/interpolate](/docs/api-dreamina-v1/post-dreamina-videos-interpolate). Jobs are retained for 30 days. > **https://api.useapi.net/v1/dreamina/videos/`jobid`** ### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Path Parameters - `jobid` is **required**, the unique job identifier returned from [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos), [POST /videos/full-quality](/docs/api-dreamina-v1/post-dreamina-videos-full-quality), [POST /videos/upscale](/docs/api-dreamina-v1/post-dreamina-videos-upscale), or [POST /videos/interpolate](/docs/api-dreamina-v1/post-dreamina-videos-interpolate). ### Responses **200** **200 OK** Returns the job record with current status and details. **Processing (status: created):** ```json { "jobid": "j0223140530123456789v-u12345-CA:user@example.com-bot:dreamina", "type": "video", "status": "created", "model": "seedance-2.0", "created": "2026-02-23T14:05:30.123Z", "request": { "prompt": "A serene mountain landscape at sunset", "model": "seedance-2.0", "ratio": "16:9", "duration": 5, "inputMode": "prompt" }, "response": { "forecastCost": 125 }, "code": 200 } ``` **Completed:** ```json { "jobid": "j0223140530123456789v-u12345-CA:user@example.com-bot:dreamina", "type": "video", "status": "completed", "model": "seedance-2.0", "created": "2026-02-23T14:05:30.123Z", "updated": "2026-02-23T14:07:15.456Z", "request": { "prompt": "A serene mountain landscape at sunset", "model": "seedance-2.0", "ratio": "16:9", "duration": 5, "inputMode": "prompt" }, "response": { "assetId": "CA:user@example.com-306191137798:7341234567890123456", "videoUrl": "https://v16m-default.tiktokcdn.com/...", "videoUrlBackup": "https://v16m.byteicdn.com/...", "videoUrlWatermarked": "https://v16-cc.capcut.com/...", "watermarked": false, "videoId": "7341234567890123456", "coverUrl": "https://p9-sign.douyinpic.com/...", "width": 1280, "height": 720, "durationMs": 5042, "hasAudio": false, "forecastCost": 125, "finishTime": 1708700835 }, "code": 200 } ``` **Failed:** ```json { "jobid": "j0223140530123456789v-u12345-CA:user@example.com-bot:dreamina", "type": "video", "status": "failed", "model": "seedance-2.0", "created": "2026-02-23T14:05:30.123Z", "updated": "2026-02-23T14:07:15.456Z", "request": { "prompt": "A test prompt", "model": "seedance-2.0", "ratio": "16:9", "duration": 5, "inputMode": "prompt" }, "error": "fail_code: 2043", "errorDetails": "OutputVideoRisk", "failMsg": "OutputVideoRisk", "code": 2043 } ``` Jobs still `created` 2 hours after they were submitted are marked as failed with `"Generation timed out after 120m (…)"` (code `408`). `errorDetails` is the sentence Dreamina's website shows, and it reads the same for different filters. `failMsg` is Dreamina's own name for the failure, so you can tell them apart. Common values, all raised after submission — a job that fails this way is not charged: | `code` | `failMsg` | Meaning | Retry? | |---|---|---|---| | `` | `` | | | **401** **401 Unauthorized** Invalid API token. ```json { "error": "Unauthorized" } ``` **403** **403 Forbidden** The job belongs to a different useapi.net user. ```json { "error": "No access to account US:user@example.com", "code": 403 } ``` **404** **404 Not Found** Job not found, or it has expired (>30 days). The response has no body. ### Model The video job with its `status`: a `completed` job holds the video in `response.videoUrl`, and a `failed` one carries `error` and `code`. <details markdown="block" class="model-details"> <summary>The video job record for each status, field by field, and how the watermark is handled</summary> **Completed** Video generation completed. Includes video URL and metadata. ```typescript { jobid: string // Unique job identifier type: 'video' | 'video-upscale' | 'video-interpolate' // Job type status: 'completed' model: string // Model used created: string // ISO 8601 timestamp updated: string // ISO 8601 timestamp request: { prompt?: string model: string ratio?: string duration?: number inputMode: string // "prompt" | "first_frame" | "end_frame" | "multi_frame" | "unified_edit" | "long_video" | "edit" | "full_quality" resolution?: string // "480p", "720p", "1080p", "2k" or "4k" draftJobid?: string // full_quality only: the seedance-2.5-draft job it was made from firstFrameRef?: string endFrameRef?: string editVideoRef?: string frame_1_imageRef?: string // Keyframe refs (multi_frame mode) frame_1_prompt?: string frame_1_duration?: number frame_2_imageRef?: string frame_2_prompt?: string frame_2_duration?: number replyUrl?: string replyRef?: string } response: { assetId: string // For DELETE /assets/<assetId> videoUrl: string // Direct MP4 URL — clean (non-watermarked) master when available; falls back to the watermarked variant for models that don't expose a master videoUrlBackup?: string // Alternate CDN host for the same master (use if primary fails) videoUrlBackups?: string[] // Full list of alternate master URLs when more than one is provided videoUrlWatermarked?: string // Watermarked variant, preserved as a fallback and for compliance/traceability of AI-generated content watermarked?: boolean // true when the returned videoUrl carries Dreamina's AIGC transparency badge videoId: string // Dreamina video ID coverUrl: string // Video cover/thumbnail URL width: number // Video width in pixels height: number // Video height in pixels durationMs: number // Video duration in milliseconds hasAudio: boolean // Whether video has audio forecastCost: number // Estimated generation time in seconds, NOT a price finishTime: number // Unix timestamp of completion upscaleJobid?: string // Set after POST /videos/upscale } code: number // 200 } ``` #### Watermark handling Dreamina's backend renders every generated video twice: - A **clean master** served from `v16m-default.tiktokcdn.com` / `v16m.byteicdn.com`. - A **watermarked transcode** served from `v16-cc.capcut.com` with a baked-in top-left "AI" transparency badge and (on non-premium accounts) a bottom-right Dreamina brand mark. `GET /videos/<jobid>` returns the clean master as `videoUrl` whenever the upstream response exposes one, and keeps the watermarked URL in `videoUrlWatermarked` as a fallback. The `watermarked` flag reflects which variant `videoUrl` is currently pointing at. For models that don't expose a master, `videoUrl` falls back to the watermarked variant and `watermarked` becomes `true`. The watermark is baked into the MP4 at render time — there is no URL parameter that strips it from the watermarked variant, and attempting to edit the URL invalidates its signature. All video URLs are signed and expire ~7 days after generation. Download promptly. **Failed** Video generation failed. Includes error details. ```typescript { jobid: string // Unique job identifier type: 'video' | 'video-upscale' | 'video-interpolate' status: 'failed' model: string created: string // ISO 8601 timestamp updated: string // ISO 8601 timestamp request: { prompt?: string model: string ratio?: string duration?: number inputMode: string firstFrameRef?: string endFrameRef?: string editVideoRef?: string replyUrl?: string replyRef?: string } error: string // Error summary (e.g., "fail_code: 2043") errorDetails?: string // Additional details (e.g., "OutputVideoRisk") failMsg?: string // Dreamina's own name for a failure, e.g. "OutputVideoRisk", "ParamImageRatioInvalid" code: number // Error code (e.g., 2043, 408, 596) } ``` **Common error codes:** | Code | Meaning | |------|---------| | 408 | Generation timed out (no result after 2 hours) | | 596 | Account session expired | | 2038 | Content filtered | | 2043 | Output video moderation risk | </details> ### Examples **Curl** ```bash # Get job status curl "https://api.useapi.net/v1/dreamina/videos/j0223140530123456789v-u12345-CA:user@example.com-bot:dreamina" \ -H "Authorization: Bearer YOUR_API_TOKEN" # Poll for completion (check every 10 seconds) while true; do RESULT=$(curl -s "https://api.useapi.net/v1/dreamina/videos/$JOBID" \ -H "Authorization: Bearer YOUR_API_TOKEN") STATUS=$(echo "$RESULT" | jq -r '.status') echo "Status: $STATUS" if [[ "$STATUS" == "completed" ]]; then echo "$RESULT" | jq -r '.response.videoUrl' break fi if [[ "$STATUS" == "failed" ]]; then echo "$RESULT" | jq -r '.error' break fi sleep 10 done ``` **JavaScript** ```javascript const apiToken = 'YOUR_API_TOKEN' const jobId = 'j0223140530123456789v-u12345-CA:user@example.com-bot:dreamina' async function getJobStatus(jobId) { const response = await fetch(`https://api.useapi.net/v1/dreamina/videos/${jobId}`, { headers: { 'Authorization': `Bearer ${apiToken}` } }) return await response.json() } // Poll until completion async function waitForCompletion(jobId, intervalMs = 10000) { while (true) { const job = await getJobStatus(jobId) console.log(`Status: ${job.status}`) if (job.status === 'completed') { console.log('Video URL:', job.response.videoUrl) console.log('Dimensions:', `${job.response.width}x${job.response.height}`) console.log('Duration:', `${job.response.durationMs}ms`) return job } if (job.status === 'failed') { console.error('Job failed:', job.error) throw new Error(job.error) } await new Promise(resolve => setTimeout(resolve, intervalMs)) } } const job = await waitForCompletion(jobId) ``` **Python** ```python import requests import time api_token = 'YOUR_API_TOKEN' job_id = 'j0223140530123456789v-u12345-CA:user@example.com-bot:dreamina' def get_job_status(job_id: str) -> dict: response = requests.get( f'https://api.useapi.net/v1/dreamina/videos/{job_id}', headers={'Authorization': f'Bearer {api_token}'} ) response.raise_for_status() return response.json() def wait_for_completion(job_id: str, interval_sec: int = 10) -> dict: while True: job = get_job_status(job_id) print(f"Status: {job['status']}") if job['status'] == 'completed': print(f"Video URL: {job['response']['videoUrl']}") print(f"Dimensions: {job['response']['width']}x{job['response']['height']}") # Download video video_response = requests.get(job['response']['videoUrl']) with open('output.mp4', 'wb') as f: f.write(video_response.content) print('Video saved to output.mp4') return job if job['status'] == 'failed': raise Exception(f"Job failed: {job.get('error')}") time.sleep(interval_sec) job = wait_for_completion(job_id) ``` ### Try It <script> function displayDreaminaVideoMedia(response, elementId) { const mediaContainer = document.getElementById(`${elementId}-media-links`); if (!mediaContainer) return; mediaContainer.innerHTML = ''; if (response.status === 'completed' && response.response?.videoUrl) { const r = response.response; const label = `Video (${r.width}x${r.height}, ${r.durationMs}ms)`; mediaContainer.innerHTML = `<div class="media-links-container"><strong>Generated Video:</strong> <a href="${r.videoUrl}" target="_blank" rel="noopener noreferrer" class="media-link video">${label}</a></div>`; mediaContainer.style.display = 'block'; return; } mediaContainer.style.display = 'none'; } async function apiExecuteGetDreaminaVideosJobId() { const tokenElement = document.getElementById('input-token'); const jobidElement = document.getElementById('input-jobid'); const elementId = 'input'; const data = { method: 'GET', headers: { 'Authorization': `Bearer ${tokenElement.value}` } }; const mediaLinks = document.getElementById(`${elementId}-media-links`); if (mediaLinks) mediaLinks.style.display = 'none'; const status = await apiExecute( `https://api.useapi.net/v1/dreamina/videos/${jobidElement.value}`, elementId, data ); if (status === 200) { try { const content = document.getElementById(`${elementId}-response-json`); const response = JSON.parse(content.innerText); displayDreaminaVideoMedia(response, elementId); } catch (e) { console.error('Failed to parse response for media display:', e); } } } </script> <form id="input" class="input-form" onsubmit="return false;"> <div class="input-field"> <div class="input-field-row"> <label for="input-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="input-token" type="text" class="input-element" required aria-required="true"> </label> <label for="input-jobid"><span>jobid (required)</span> <input id="input-jobid" type="text" class="input-element" required aria-required="true"> </label> </div> <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteGetDreaminaVideosJobId()">Go</button> </div> </form> <div id="input-media-links" style="display:none;"></div> <div id="input-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-dreamina-v1 === Document URL: https://useapi.net/docs/api-dreamina-v1 --- layout: default title: Dreamina API nav_logo: /assets/images/dreamina-logo.png nav_title: Dreamina API seo_title: "Dreamina API: Seedance 2.5 and 2.0 Video, Seedream, GPT Image" description: "Dreamina has no developer API: the third-party useapi.net Dreamina API runs Seedance 2.5 and 2.0 video, Seedream and GPT Image on your own Dreamina plan, no BytePlus account needed." nav_order: 2100 has_children: true permalink: /docs/api-dreamina-v1 repo: https://github.com/useapi/dreamina-api --- # <img style="height:1em;vertical-align: middle;" src="/assets/images/dreamina-logo.png" alt=""> Dreamina API February 23, 2026 (November 20, 2026) This is a [third-party](/docs/legal#affiliation--third-party-services) API for [Dreamina](https://dreamina.capcut.com/) by [ByteDance](https://www.bytedance.com/). It uses your [Dreamina subscription](https://dreamina.capcut.com/pricing/dreamina-price): Free, Basic $15, Standard $36, Advanced $79 to $320 or Ultra $520 a month in the US (as of November 2026). It makes video with ByteDance's [Seed](https://seed.bytedance.com/) models Seedance 2.5, 2.5 Flash, 2.0, 2.0 Fast and 2.0 Mini, with HappyHorse 1.1 and Wan 3.0 on Canada accounts, and images with Seedream 5.5, GPT Image 2.5 and Nano Banana Pro, through a REST API and a hosted MCP server. Seedance 2.5 here accepts real faces and makes videos up to 3 minutes long. Accounts with Dreamina's November 2026 [Unlimited](#unlimited) offer make Seedance videos at 480p or 720p and Seedream 5.5, GPT Image 2.5 and Nano Banana images at no credits. On Standard, a 5-second 720p Seedance 2.0 Fast video uses $0.37 of the plan's monthly credits, against $0.60 a video on ByteDance's own API. ## Models | Model | What it makes | Notes | |---|---|---| | Seedance 2.5<br>`seedance-2.5` | [Video](/docs/api-dreamina-v1/post-dreamina-videos) from text, a start and an end frame, or up to 50 references (30 images, 10 videos, 10 audio clips), plus [long videos and edits](/docs/api-dreamina-v1/post-dreamina-videos#what-is-new-in-seedance-25) | 4 to 30 seconds, or 31 to 180 in long video mode, 480p, 720p or 1080p, 4K on CA, accepts real faces, Unlimited at 480p and 720p | | Seedance 2.5 Flash<br>`seedance-2.5-flash` | [Video](/docs/api-dreamina-v1/post-dreamina-videos#seedance-25-flash-and-seedance-25-draft) from text, a start and an end frame, or up to 20 references (10 images, 5 videos, 5 audio clips), plus edits | 4 to 30 seconds, 480p or 720p, faster and fewer credits than Seedance 2.5, Unlimited, CA only | | Seedance 2.5 Draft<br>`seedance-2.5-draft` | A 480p draft video to test a prompt, from text, a start and an end frame, or up to 50 references, then [the same video in full quality](/docs/api-dreamina-v1/post-dreamina-videos-full-quality) | 4 to 30 seconds, 480p drafts, full quality in 1080p, or 4K on CA, Unlimited drafts | | Seedance 2.0<br>`seedance-2.0` | Video from text, a start and an end frame, or up to 12 references (9 images, 3 videos, 3 audio clips) | 4 to 15 seconds, 720p, 1080p or 4K, Unlimited at 720p | | Seedance 2.0 Fast<br>`seedance-2.0-fast` | Video from text, a start and an end frame, or up to 12 references | 4 to 15 seconds, 720p, or 1080p, 2K and 4K upscaled from 720p, Unlimited at 720p | | Seedance 2.0 Mini<br>`seedance-2.0-mini` | Video from text, a start and an end frame, or up to 12 references | 4 to 15 seconds, 720p, or 1080p, 2K and 4K upscaled from 720p, Unlimited at 720p, the cheapest Seedance 2.0 | | Seedance 1.5 Pro<br>`seedance-1.5-pro` | Video from text, or a start and an end frame | 5, 10 or 12 seconds, 720p, US only | | Seedance 1.0 Pro<br>`seedance-1.0-pro` | Video from text or a start frame | 5 or 10 seconds, 1080p, CA only | | Seedance 1.0 Mini<br>`seedance-1.0-mini` | Video from text, a start frame, or 2 to 10 keyframes with a prompt each | 5 or 10 seconds, 720p, US only | | Seedance 1.0 Fast<br>`seedance-1.0-fast` | Video from text, a start frame, or 2 to 10 keyframes | 5 or 10 seconds, 720p or 1080p, CA only | | HappyHorse 1.1<br>`happyhorse-1.1` | Video with sound from text, a start frame, or up to 9 reference images, by [Alibaba](https://www.alibabagroup.com/) | 4 to 15 seconds, 720p or 1080p, CA only | | Wan 3.0<br>`wan-3.0` | Video with sound from text, a start and an end frame, or up to 20 references (10 images, 5 videos, 5 audio clips), by Tongyi Lab | 4 to 15 seconds, 720p or 1080p, CA only | | GPT Image 2.5 Flare<br>`gpt-image-2.5-flare` | [Images](/docs/api-dreamina-v1/post-dreamina-images) from text and up to 6 reference images | 1K, 2K or 4K, [OpenAI](https://openai.com/)'s faster model for everyday images and edits, Unlimited at 1K and 2K | | GPT Image 2.5 Sunburst<br>`gpt-image-2.5-sunburst` | Images from text and up to 6 reference images | 1K, 2K or 4K, sharper details and more precise edits, Unlimited at 1K and 2K | | Nano Banana Pro<br>`nano-banana-pro` | Images from text and up to 6 reference images | 1K, 2K or 4K, Gemini 3 Pro Image, Unlimited at 1K and 2K | | Nano Banana 2.1<br>`nano-banana-2.1` | 2 images from text and up to 6 reference images | 1K, 2K or 4K, Unlimited at 1K and 2K, CA only | | GPT Image 2<br>`gpt-image-2` | Images from text and up to 6 reference images | 1K, 2K or 4K | | Seedream 5.5<br>`seedream-5.5` | 1 to 8 images from text and up to 6 reference images | 1.5K or 2K, realistic images with complex text, transparent background, Unlimited, CA only | | Seedream 5.0 Pro<br>`seedream-5.0-pro` | Up to 4 images from text and up to 6 reference images | 2K or 4K, 1.5K on CA, cinematic and text-rich images | | Seedream 5.0 Flash<br>`seedream-5.0-flash` | Up to 4 images from text and up to 6 reference images | 1.5K, 2K or 4K, US only | | Seedream 5.0 Lite<br>`seedream-5.0-lite` | Up to 4 images from text and up to 6 reference images | 2K or 4K, CA only | | Seedream 4.7<br>`seedream-4.7` | Up to 4 images from text and up to 6 reference images | 2K or 4K, CA only | | Seedream 4.6<br>`seedream-4.6` | Up to 4 images from text and up to 6 reference images | 2K or 4K, the default image model | | Seedream 4.5<br>`seedream-4.5` | Up to 4 images from text and up to 6 reference images | 2K or 4K, high quality | | Seedream 4.1<br>`seedream-4.1` | Up to 4 images from text and up to 6 reference images | 2K or 4K | | Seedream 4.0<br>`seedream-4.0` | Up to 4 images from text and up to 6 reference images | 2K or 4K, balances quality and speed | | Seedream 3.1<br>`seedream-3.1` | Up to 4 images from text | 1K or 2K, CA only | | Seedream 3.0<br>`seedream-3.0` | Up to 4 images from text and 1 reference image | 1K or 2K | | More | [Video upscale](/docs/api-dreamina-v1/post-dreamina-videos-upscale), [smoother video](/docs/api-dreamina-v1/post-dreamina-videos-interpolate) and [image upscale](/docs/api-dreamina-v1/post-dreamina-images-upscale) | Video 2x (720p to 1440p, 1080p to 4K), 30 or 60 FPS on original or upscaled videos, images to 2K, 4K or 8K | US and Canada (CA) accounts run the same resolutions on the Seedance 2.0 models, up to 4K. Seedance 2.5 goes up to 1080p on US accounts and 4K on CA. The models marked CA only need a Canada-region account and the ones marked US only a US account, and Seedream picks the aspect ratio for you when you don't set one. References are images, videos and audio you [upload](/docs/api-dreamina-v1/post-dreamina-assets-account) to the account. ## Unlimited With `unlimited` set to `true` the job uses no credits. Unlimited comes with a Dreamina plan bought or upgraded during Dreamina's November 2026 offers. Dreamina decides which of these models and resolutions an account gets and for how many days, and can end it early. | Model | Unlimited at | Per request | Accounts | |---|---|---|---| | `seedance-2.5` | 480p, 720p | 1 video, up to 30 s | US, CA | | `seedance-2.5-flash` | 480p, 720p | 1 video, up to 30 s | CA | | `seedance-2.5-draft` | 480p | 1 video, up to 30 s | US, CA | | `seedance-2.0` | 720p | 1 video, up to 15 s | US, CA | | `seedance-2.0-fast` | 720p | 1 video, up to 15 s | US, CA | | `seedance-2.0-mini` | 720p | 1 video, up to 15 s | US, CA | | `seedream-5.5` | 1.5K, 2K | up to 4 images | CA | | `gpt-image-2.5-flare`<br>`gpt-image-2.5-sunburst` | 1K, 2K | 1 image | US, CA | | `nano-banana-pro` | 1K, 2K | up to 4 images | US, CA | | `nano-banana-2.1` | 1K, 2K | up to 4 images | CA | - The plan decides which of these resolutions are Unlimited. 4K never is. - Video references and edits are included. The Seedance 2.5 models stop at 30 seconds, so long video is not. - An image request without `count` asks for the most the model allows, 4 images (1 on GPT Image 2.5). - Dreamina runs one Unlimited job at a time per account, videos and images together. | Answer | When | |---|---| | `400` | A model not in the table. On POST /videos also another resolution or a long video. | | `412` | The account has no Unlimited for this model and resolution, or it has ended. Send the request without `unlimited` to use credits. | | `429` | The account is already running an Unlimited job. Retry after it finishes. | ## MCP server The hosted [Dreamina MCP server](/docs/api-dreamina-v1/mcp) gives the Claude app, ChatGPT, Claude Code, Cursor, VS Code and other AI assistants 15 tools for Seedance videos, upscales, frame rates, draft to full quality, Seedream, GPT Image and Nano Banana images, uploads and history, with your useapi.net API token and nothing to install. It is listed in the official MCP Registry as `net.useapi/dreamina`. The [dreamina-api](https://github.com/useapi/dreamina-api) repo also adds it in one step as a [Claude Code plugin](https://github.com/useapi/dreamina-api#use-with-claude-code) or a [Gemini CLI extension](https://github.com/useapi/dreamina-api#use-with-gemini-cli). ## Pricing What one 5-second video costs on ByteDance's [BytePlus ModelArk](https://docs.byteplus.com/en/docs/ModelArk/1544106) API and on each US Dreamina subscription billed monthly (as of November 2026). Each subscription comes with a monthly number of credits, and each video uses a set number of them, so a video costs its share of the subscription. | Model | [Official API](https://docs.byteplus.com/en/docs/ModelArk/1544106) | Ultra $520/m (59,000 cr/mo) | Advanced $79/m (8,645 cr/mo) | Standard $36/m (3,885 cr/mo) | Basic $15/m (1,575 cr/mo) | |---|---|---|---|---|---| | Seedance 2.0 Mini (720p, 5 s) | $0.38 ($0.076 a second) | $0.22 / 25 cr (2,360 videos/mo) | $0.23 / 25 cr (345 videos/mo) | $0.23 / 25 cr (155 videos/mo) | $0.24 / 25 cr (63 videos/mo) | | Seedance 2.0 Fast (720p, 5 s) | $0.60 ($0.12 a second) | $0.35 / 40 cr (1,475 videos/mo) | $0.37 / 40 cr (216 videos/mo) | $0.37 / 40 cr (97 videos/mo) | $0.38 / 40 cr (39 videos/mo) | | Seedance 2.0 Mini (1080p upscaled from 720p, 5 s) | not sold (Seedance 2.0 at 1080p: $1.87) | $0.48 / 55 cr (1,072 videos/mo) | $0.50 / 55 cr (157 videos/mo) | $0.51 / 55 cr (70 videos/mo) | $0.52 / 55 cr (28 videos/mo) | | Seedance 2.0 Fast (1080p upscaled from 720p, 5 s) | not sold (Seedance 2.0 at 1080p: $1.87) | $0.62 / 70 cr (842 videos/mo) | $0.64 / 70 cr (123 videos/mo) | $0.65 / 70 cr (55 videos/mo) | $0.67 / 70 cr (22 videos/mo) | | Seedance 2.5 long video (480p, 60 s) | not sold (stops at 30 s) | $12.16 / 1,380 cr (42 videos/mo) | $12.61 / 1,380 cr (6 videos/mo) | $12.79 / 1,380 cr (2 videos/mo) | $13.14 / 1,380 cr (1 video/mo) | - A free Dreamina account works too. On Dreamina's free daily credits, which [GET accounts/`account`](/docs/api-dreamina-v1/get-dreamina-accounts-account) collects once a day, a free US account makes Seedream 4.6, 4.5, 4.1, 4.0, 3.0 and 5.0 Flash images up to 2K (as of November 2026). Seedance video needs a paid subscription, and only paid subscriptions remove Dreamina's AI badge from images. - Dreamina's paid subscriptions also include video upscaling and 60 FPS. - BytePlus runs Seedance only after you buy a prepaid [resource pack](https://docs.byteplus.com/en/docs/ModelArk/2191775), from about $30, which expires after 90 days. - Seedance 2.5 here does two things ByteDance's own API doesn't: it accepts photos of real faces and makes [long videos](/docs/api-dreamina-v1/post-dreamina-videos) of 31 to 180 seconds in one job. On a Canadian plan it also makes 4K, about $4.15 for 5 seconds on Canada's Advanced, against $4.57 on ByteDance's API (as of November 18, 2026). - Canada-region subscriptions cost Basic C$20.49, Standard C$50, Advanced from C$109.99 or Ultra C$725 a month. A 5-second Seedance 2.0 video at 1080p costs about $1.83 on Canada's Advanced and $1.87 on the US Advanced, against $1.87 on BytePlus. - Larger Advanced subscriptions give 17,600 to 35,500 credits a month for $159 to $320. Yearly billing and the price per second of every model are in the cost calculator below. <details markdown="block" class="calc-details"> <summary>Cost calculator for every model, US and Canada</summary> Dollars per second on the Advanced subscription billed monthly: US $79 for 8,645 credits, Canada C$109.99 for 11,997 credits, converted at CAD/USD 0.7023 (as of November 12, 2026). | Model | US $/sec | CA $/sec | |-------|---------:|---------:| | Seedance 2.5 @480p, with a video reference | $0.128 | $0.116 | | Seedance 2.5 @480p | $0.155 | $0.142 | | Seedance 2.5 @720p | $0.338 | $0.245 | | Seedance 2.5 @1080p | $0.832 | $0.753 | | Seedance 2.5 @4K, with a video reference | — | $0.586 | | Seedance 2.5 @4K | — | $0.831 | | Seedance 2.5 long video @480p | $0.210 | $0.193 | | Seedance 2.5 long video @720p | $0.411 | $0.373 | | Seedance 2.5 long video @1080p | $0.923 | $0.837 | | Seedance 2.5 long video @4K | — | $0.914 | | Seedance 2.5 Flash @480p | — | $0.071 | | Seedance 2.5 Flash @720p | — | $0.155 | | Seedance 2.5 Draft @480p | $0.119 | $0.109 | | Seedance 2.0 @720p | $0.155 | $0.148 | | Seedance 2.0 @1080p | $0.375 | $0.367 | | Seedance 2.0 @4K | $0.896 | $0.811 | | Seedance 2.0 Fast @720p | $0.073 | $0.064 | | Seedance 2.0 Fast @1080p | $0.128 | $0.097 | | Seedance 2.0 Fast @2K | $0.155 | $0.116 | | Seedance 2.0 Fast @4K | $0.201 | $0.148 | | Seedance 2.0 Mini @720p | $0.046 | $0.045 | | Seedance 2.0 Mini @1080p | $0.101 | $0.084 | | Seedance 2.0 Mini @2K | $0.128 | $0.097 | | Seedance 2.0 Mini @4K | $0.174 | $0.129 | | Seedance 1.5 Pro @720p | $0.183 | — | | HappyHorse 1.1 @720p | — | $0.109 | | HappyHorse 1.1 @1080p | — | $0.148 | | Wan 3.0 @720p | — | $0.109 | | Wan 3.0 @1080p | — | $0.270 | Seedance 2.5 bills a reference video's duration on top of the output, so a 4-second video from a 5-second reference bills 9 seconds, at the lower with-reference rate, which applies at 480p, and at 4K on Canada accounts. Canada costs up to 28% less per second (on Seedance 2.5 at 720p, and about 25% on Seedance 2.0 Fast and Mini above 720p), because its subscription buys 153 credits per US dollar against 109 in the US, even though each video uses more credits. Canada also has Seedance 2.5 Flash, Seedance 2.5 at 4K, HappyHorse 1.1, Wan 3.0 and Seedance 1.0 Pro and Fast. Credits per image (as of November 12, 2026): | Model | Sizes | US | CA | |-------|-------|----|----| | Seedream 5.5 | 1.5K / 2K | — | 8 / 13 (launch price, normally 11 / 18) | | Seedream 5.0 Pro | 1.5K / 2K / 4K | — / 12 / 18 | 11 / 15 / 23 | | Seedream 5.0 Flash | 1.5K / 2K / 4K | 6 / 6 / 10 | — | | GPT Image 2.5 Flare and Sunburst | 1K / 2K / 4K | 8 / 11 / 13 (launch price, normally 10 / 14 / 17) | 5 / 7 / 8 (launch price, normally 13 / 18 / 22) | | Nano Banana 2.1 | 1K / 2K / 4K | — | 15 / 23 / 47 | | Nano Banana Pro | 1K / 2K / 4K | 42 / 42 / 75 | 53 / 53 / 95 | | GPT Image 2 | 1K / 2K / 4K | 21 / 38 / 48 | 27 / 48 / 61 | Yearly billing lowers the US Advanced subscription to $900 a year ($75 a month), and Canada's to C$1,299.99 a year. [Setup Dreamina](/docs/start-here/setup-dreamina#cost-calculator) has the credits behind each rate. </details> ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. ## Run several Dreamina accounts Video and image requests don't need `account`: each job goes to one of your Dreamina accounts that has a free job slot, within the `maxJobs` limit (1 to 50, 10 by default) you set for each account with [POST accounts](/docs/api-dreamina-v1/post-dreamina-accounts). When every account is busy you get `429`, so wait and send it again. Pass `account`, such as `CA:user@example.com`, to run a job on a specific account. A job that uses an uploaded image, video or audio runs on the account that holds it, and [GET scheduler](/docs/api-dreamina-v1/get-dreamina-scheduler) lists the jobs running on each account. Every generation request can also send its result to your webhook with `replyUrl`, so you don't have to poll. Most videos take 60 to 180 seconds, while Seedance 2.5 long videos and edits took 13 to 17 minutes in our tests. [How useapi.net works](/docs/how-it-works) has tips for keeping your accounts healthy. ## Questions ### Does Dreamina have an API? Through useapi.net, yes. The useapi.net Dreamina API runs Seedance 2.5, 2.0, 2.0 Fast and 2.0 Mini, and Seedream, GPT Image 2.5 and Nano Banana Pro images over REST on your Dreamina subscription. Dreamina itself is a website with no developer API (as of November 2026). A runnable Node.js example is on GitHub at [useapi/dreamina-api](https://github.com/useapi/dreamina-api), and the [Dreamina tutorial](/docs/articles/dreamina-bash) walks through it. ### How much does the Dreamina API cost? Through useapi.net, a 5-second Seedance 2.0 Fast video at 720p costs $0.37 on Dreamina Advanced, against $0.60 on ByteDance's [BytePlus ModelArk](https://docs.byteplus.com/en/docs/ModelArk/1544106), and Seedance 2.0 Mini costs $0.23 against $0.38 (as of November 2026). BytePlus also needs a prepaid resource pack before Seedance runs. The [price table](#pricing) shows each model on each subscription, and the [Seedance pricing comparison](/docs/articles/seedance-2-api-pricing) prices every route. ### Is there a Dreamina API key? Through useapi.net, you use our [API token](/docs/start-here/setup-useapi), since Dreamina issues no API key, and connect your Dreamina account once with its email and password through [Setup Dreamina](/docs/start-here/setup-dreamina), with no BytePlus account and no prepaid pack. Both regions run Seedance 2.5 and the Seedance 2.0 models, the 2.0 models at the same resolutions, up to 4K. Pick a Canada-region account for Seedance 2.5 Flash, Seedance 2.5 at 4K, and Seedance 1.0 Pro and 1.0 Fast. ### Is there a Seedance 2.5 API that accepts real faces? Through useapi.net, yes: the Dreamina route accepts photographic portraits on Seedance 2.5 and makes long videos of 31 to 180 seconds in one job. ByteDance's own [Seedance 2.5 guide](https://docs.byteplus.com/en/docs/modelark/seedance-2-5) says it "does not support directly uploading reference images or videos containing real human faces" and makes up to 30 seconds per request (as of November 2026). Send `seedance-2.5` to [POST videos](/docs/api-dreamina-v1/post-dreamina-videos). [Setup Dreamina](/docs/start-here/setup-dreamina) [LLM-friendly API spec](https://useapi.net/assets/aibot/api-dreamina-v1.txt) Feed this to your LLM to build integrations [Claude Code skill](/llm-tools) A drop-in useapi.net skill for Claude Code, and a rule for Cursor [Postman collection](https://www.postman.com/useapinet/useapi-net/collection/29112081-347618e4-ef47-4ca4-bdee-72d321dcb4f2) (November 12, 2026) [MCP Server](/docs/api-dreamina-v1/mcp) Make Seedance videos and Seedream images from the Claude app, ChatGPT, Claude Code, Cursor and other MCP clients [GitHub examples](https://github.com/useapi/dreamina-api) Node.js and Python: Seedance video, Seedance 2.5 draft to full quality, and Dreamina image generation [Seedance 2.0 four ways](https://github.com/useapi/seedance-2-api) The same Seedance 2.0 job through Dreamina, PixVerse, Runway and MiniMax, plus a cross-vendor price dataset Articles: * [How to Draft Seedance 2.5 Videos at 480p and Finish Them in 1080p or 4K](/docs/articles/dreamina-seedance-2-5-draft) * [How to Generate AI Video with Seedance 2.5 and 2.0 via the Dreamina API](/docs/articles/dreamina-bash) * [Seedance 2.0 and 2.5 API Pricing: Every Route, Compared](/docs/articles/seedance-2-api-pricing) {% include lang-switch.html mode="hub" key="seedance-2-pricing" %} Examples: * [Seedance 2.5 — long video and video edit](/blog/260907) * [Seedance 2.5](/blog/260807) * [Seedance 2.0 Mini — omni video from three image references](/blog/260626) * [Seedance 2.0 — real-face tutorial (Runway & Dreamina)](/blog/260415) * [Seedance 2.0, Video Upscale](/blog/260402) * [17 AI Image Models: The Showdown](/blog/260309i) * [Seedream 4.5 and Seedance 2.0](/blog/260302) * [Seedance 2.0](/blog/260223) Videos on YouTube: * [Selfie Situation, Seedance 2.0](https://www.youtube.com/shorts/TYlg9cVyNy4) * [Seedance 2.0 Omni: photo, reference video and audio into one clip](https://www.youtube.com/shorts/apUc3lXrY_4) Developer Community: * <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> * <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> === URL: https://useapi.net/docs/api-dreamina-v1/mcp === Document URL: https://useapi.net/docs/api-dreamina-v1/mcp --- layout: default title: MCP Server nav_icon: mcp seo_title: "Dreamina MCP Server: Seedance 2.5 Video and Seedream Images" description: "Connect the Claude app, ChatGPT, Claude Code or any MCP client to the hosted useapi.net Dreamina MCP server: 15 tools for Seedance video, Seedream and GPT Image." parent: Dreamina API nav_order: 50 permalink: /docs/api-dreamina-v1/mcp --- ## Dreamina MCP Server November 20, 2026 --- The useapi.net Dreamina MCP server lets an AI assistant such as the Claude app, ChatGPT, Claude Code, Cursor or VS Code Copilot make videos and images with [Dreamina](https://dreamina.capcut.com) on your own Dreamina accounts. It is a hosted [Model Context Protocol](https://modelcontextprotocol.io) server with 15 tools: generate Seedance 2.5, 2.0, HappyHorse and Wan videos from text, start and end frames or omni references, upscale them, raise their frame rate, turn a Seedance 2.5 draft into a full-quality video, generate Seedream, GPT Image and Nano Banana images, upload your own images, videos and audio, and clean up your generation history. Each tool calls the [Dreamina API](/docs/api-dreamina-v1), so the same rules and limits apply. Nothing needs to be installed or hosted. **Is there a Dreamina MCP server?** Yes. useapi.net, a third-party service not affiliated with Dreamina or ByteDance, hosts one at `https://api.useapi.net/v1/dreamina/mcp` with 15 tools for Seedance video and Seedream images on your own Dreamina plan, including its Unlimited mode, nothing to install. Prefer REST? Code: [github.com/useapi/dreamina-api](https://github.com/useapi/dreamina-api) See all useapi.net MCP servers on [Model Matrix & MCP](/model-matrix#mcp-servers). ## Endpoint and authorization ``` https://api.useapi.net/v1/dreamina/mcp ``` - Transport: Streamable HTTP. - Listed in the [official MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers/net.useapi%2Fdreamina/versions/latest) as `net.useapi/dreamina`, so MCP clients and directories that read the registry can find it by that name. - Authorization: your useapi.net API token in the `Authorization: Bearer …` header, see [Setup useapi.net](/docs/start-here/setup-useapi). The Claude app and ChatGPT sign in with OAuth instead, see [Use it in the Claude app or ChatGPT](#use-it-in-the-claude-app-or-chatgpt). - You need at least one Dreamina account added with [Setup Dreamina](/docs/start-here/setup-dreamina). Adding and removing accounts is not available over MCP: use [POST /accounts](/docs/api-dreamina-v1/post-dreamina-accounts) or the setup page. ## Setup Replace `YOUR_API_TOKEN` with your useapi.net API token. ### Claude Code ```bash claude mcp add --transport http useapi-dreamina https://api.useapi.net/v1/dreamina/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` ### Cursor In `~/.cursor/mcp.json`: ```json { "mcpServers": { "useapi-dreamina": { "url": "https://api.useapi.net/v1/dreamina/mcp", "headers": { "Authorization": "Bearer YOUR_API_TOKEN" } } } } ``` ### VS Code In `.vscode/mcp.json`: ```json { "servers": { "useapi-dreamina": { "type": "http", "url": "https://api.useapi.net/v1/dreamina/mcp", "headers": { "Authorization": "Bearer YOUR_API_TOKEN" } } } } ``` ### Windsurf and other clients Any client that supports remote MCP servers over HTTP with custom headers works. The usual JSON shape: ```json { "mcpServers": { "useapi-dreamina": { "serverUrl": "https://api.useapi.net/v1/dreamina/mcp", "headers": { "Authorization": "Bearer YOUR_API_TOKEN" } } } } ``` Some clients name the address field `url` instead of `serverUrl`. ### Test it with curl ```bash curl -s https://api.useapi.net/v1/dreamina/mcp \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}' curl -s https://api.useapi.net/v1/dreamina/mcp \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' ``` The first call answers with the server's name `useapi-dreamina` and its instructions for the assistant, the second with the 15 tools. ## Use it in the Claude app or ChatGPT The Claude app ([claude.ai](https://claude.ai) and Claude Desktop) and [ChatGPT](https://chatgpt.com) can add this server as a custom connector. They sign in with OAuth: you give the app the URL, it opens a useapi.net page, and you paste your useapi.net API token there once. Both work on their Free plans. The API-token setups above for Claude Code, Cursor, VS Code and other clients keep working as before. ``` ``` ### Claude app 1. Open Settings → Connectors and click Add custom connector. 2. Enter a name, for example `useapi `, and the URL above, then click Add. 3. Click Connect. Claude opens the useapi.net sign-in page. 4. Paste your useapi.net API token and click Allow. Claude asks before each tool call unless you choose Always allow. The Free plan allows one custom connector. ### ChatGPT 1. Open Plugins, click Add and choose Add custom MCP server. 2. Enter a name and the URL above, and set Authentication to OAuth. 3. Tick ChatGPT's "I understand and want to continue" box, then click Create as a plugin. 4. Click Connect. ChatGPT opens the useapi.net sign-in page. 5. Paste your useapi.net API token and click Allow. ChatGPT asks you to confirm each tool call that creates or changes something. The Free plan works without developer mode (as of October 25, 2026). ### How the sign-in works - Your API token is in your welcome email, see [Setup useapi.net](/docs/start-here/setup-useapi). The useapi.net page links there too. - Each connection is for one MCP server. Connect each server you want to use on its own. - The app gets an access token that lasts 1 hour and renews it on its own. A connection you don't use for 90 days lapses, and you connect again. - [Resetting your API token](/docs/account-management/post-account-token-reset) disconnects every app connected with it. - - Results come back as public links, so they open right in the app. ## Tools Accounts are named by their key, the region and the email, such as `US:user@example.com`. A job with references runs on the account that holds them, and upscale, frame rate and full quality run on the source job's account. Tools that start a job take an optional `account`; without it a random account with a free slot whose region offers the model is picked. ### Accounts | Tool | What it does | Main parameters | |---|---|---| | `dreamina_list_accounts` | Lists your accounts with their region, `maxJobs` and session expiry, without calling Dreamina. | | | `dreamina_get_account` | Checks one account live: the video and image models its region and plan offer, and its credits. Called once a day, it also claims the account's free daily credits. | `account` | ### Videos | Tool | What it does | Main parameters | |---|---|---| | `dreamina_create_video` | Generates a video with Seedance 2.5, 2.5 Flash, 2.5 Draft, 2.0, 2.0 Fast, 2.0 Mini, 1.x, HappyHorse 1.1 or Wan 3.0: from text, a first and last frame, 2 to 10 keyframes, omni references cited in the prompt as `@image1`, `@video1` or `@audio1`, or a re-cut of your own video. `unlimited: true` uses Dreamina's Unlimited mode at no credits. | `prompt`, `model`, `ratio`, `duration`, `resolution`, `unlimited`, `firstFrameRef`, `endFrameRef`, `frames`, `omniImages`, `omniVideos`, `omniAudios`, `editVideoRef`, `account` | | `dreamina_get_video` | Reads a video job, and with `wait: true` waits for it to finish. A finished video comes with its `videoUrl`, cover, size, duration and `assetId`. | `jobid`, `wait` | | `dreamina_upscale_video` | Doubles a finished video's width and height, for example 1080p to 4K. Each video can be upscaled once. | `jobid` | | `dreamina_interpolate_video` | Raises a finished video's frame rate to 30 or 60 fps. | `jobid`, `fps` | | `dreamina_full_quality_video` | Turns a finished `seedance-2.5-draft` video of up to 14 days old into a 1080p video, or 4K on a CA account. | `jobid`, `resolution` | The parameters match [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos), [POST /videos/upscale](/docs/api-dreamina-v1/post-dreamina-videos-upscale), [POST /videos/interpolate](/docs/api-dreamina-v1/post-dreamina-videos-interpolate) and [POST /videos/full-quality](/docs/api-dreamina-v1/post-dreamina-videos-full-quality). The numbered references of the REST API (`omni_N_imageRef`, `frame_N_imageRef` and so on) are lists here: the first item of `omniImages` is `@image1` in the prompt, the second `@image2`. ### Images | Tool | What it does | Main parameters | |---|---|---| | `dreamina_create_image` | Generates 1 to 8 images, by model, with Seedream, GPT Image or Nano Banana, from a prompt and up to 6 reference images. The first image comes back as an image the assistant can see. | `prompt`, `model`, `ratio`, `resolution`, `count`, `background`, `imageRefs`, `imageStrength`, `unlimited`, `account` | | `dreamina_get_image` | Reads an image job, and with `wait: true` waits for it to finish. Each image comes with its URL, its `assetRef` to reuse as a reference and its `assetId`. | `jobid`, `wait` | | `dreamina_upscale_image` | Upscales one of a finished job's first 4 images to 2K, 4K or 8K. | `jobid`, `imageIndex`, `upscaleResolution` | The parameters match [POST /images](/docs/api-dreamina-v1/post-dreamina-images) and [POST /images/upscale](/docs/api-dreamina-v1/post-dreamina-images-upscale). ### Files, history and running jobs | Tool | What it does | Main parameters | |---|---|---| | `dreamina_upload_asset` | Uploads your own image (JPEG, PNG or WebP, up to 10 MB), video (MP4, MOV or WebM, up to 50 MB) or audio (MP3, WAV, M4A or AAC, up to 15 MB) from a public https URL, or sent as `contentBase64`, and returns an `assetRef` that works on that account only. Uploads cannot be deleted. | `account`, `url` or `contentBase64`, `mimeType` | | `dreamina_list_assets` | Lists an account's generation history, images and videos, newest first, with each item's `assetId`, page by page. | `account`, `count`, `offset` | | `dreamina_delete_asset` | Deletes a generated image or video from the account's Dreamina history. It cannot be undone, and no credits come back. | `assetId` | | `dreamina_list_running_jobs` | Lists the jobs running now, by account. | | | `dreamina_cancel_job` | Stops tracking a running job and frees its slot. A job not yet started is marked failed. Credits already spent are not refunded. | `jobid` | The full input schema of every tool comes from `tools/list`. ## Long-running work MCP clients usually give up on a tool call after about a minute, so a tool waits up to about 50 seconds: - A quick image can come back from `dreamina_create_image` itself. - Most videos and slower images take longer. The tool then returns the `jobid`, and `dreamina_get_video` or `dreamina_get_image` with `wait: true` picks it up. Ask the assistant to keep checking until it is done. Clients that ask for progress notifications get one about every 10 seconds while a tool waits. Videos and images come back as Dreamina's own download links, which open without sign-in. They expire, videos after about 7 days, so download them soon. ## Example prompts - "Make a 10-second Seedance 2.0 video of a paper boat drifting down a rainy street at night, 9:16." - "Upload this photo and this song, then make a 15-second Seedance 2.5 video where @image1 dances to @audio1." - "Make a Seedance 2.5 draft of this prompt, and if it looks right, render it in full quality at 1080p." - "Generate 4 Seedream images of a cozy mountain cabin in winter, then upscale the second one to 4K." - "Which video models and how many credits does my CA account have?" - "Make the last video smoother at 60 fps." - "Delete the images we made today from my Dreamina history." ## Limits and notes - The tools use your Dreamina accounts and the same rules as the REST API, such as `maxJobs` and the models of each region. Generations use the account's Dreamina credits, see [Pricing](/docs/api-dreamina-v1#pricing), and `unlimited: true` uses none on a plan that includes Unlimited, see [Unlimited](/docs/api-dreamina-v1#unlimited). A failed job is not charged. - A client may send up to 20 JSON-RPC requests in one batch. - If the client sends an `MCP-Protocol-Version` header, it must be one of the supported versions: `2025-11-25`, `2025-06-18`, `2025-03-26` or `2024-11-05`. - Tool calls show in your [usage stats](/docs/account-management/get-account-stats) (`bot=dreamina`) through the REST call each tool makes, the same rows a direct API request writes. === URL: https://useapi.net/docs/api-dreamina-v1/post-dreamina-accounts === Document URL: https://useapi.net/docs/api-dreamina-v1/post-dreamina-accounts --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> accounts description: "Configure a Dreamina account for API access via POST accounts in the useapi.net Dreamina API v1 — provide email and password to enable image and video generation." parent: Dreamina API nav_order: 200 --- ## Configure Dreamina Account February 23, 2026 (November 16, 2026) --- Configure your Dreamina account for API access using email and password credentials. See [Setup Dreamina](/docs/start-here/setup-dreamina) for details. When the account is saved, we also switch on its Dreamina "close watermark" setting, so generated images come back without the "AI" badge. Dreamina allows this on paid plans only — on a free account the images keep the badge. We also accept Dreamina's one-time "Before you continue" confirmation, which the web app shows before the first generation with a model that asks for it (currently Seedance 2.x). It is an account setting, so it covers every such model at once: "You confirm you own all necessary rights to uploaded content and will not infringe third-party rights, nor upload sensitive personal data or inappropriate content." Without it, Dreamina refuses those generations. Accounts added earlier get it on their first Seedance 2.x request. > **https://api.useapi.net/v1/dreamina/accounts** ### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Request Body ```json { "email": "user@example.com", "password": "your-password", "region": "CA", "maxJobs": 10 } ``` - `email` is **required**. Dreamina account email address. - `password` is **required**. Dreamina account password. - `region` is **required**. Region code. Supported values: `US`, `CA`. Both regions support the Seedance 2.0 and 2.5 models at the same resolutions, up to 4K. The available image models also differ by region. See [Setup Dreamina](/docs/start-here/setup-dreamina) for region-specific setup. - `maxJobs` is optional. Maximum concurrent jobs for this account (1-50, default: `10`). ### Responses **200** **200 OK** Account configured successfully. ```json { "account": "CA:user@example.com", "email": "user@example.com", "region": "CA", "maxJobs": 10, "sessionExpires": "2026-04-24T12:00:00.000Z", "session": { "expires": "2026-04-24T12:00:00.000Z", "lastRefreshed": "2026-02-23T12:00:00.000Z", "daysUntilExpiry": 60 }, "models": { "video": ["seedance-2.5-flash", "seedance-2.5-draft", "seedance-2.5", "seedance-2.0-mini", "seedance-2.0-fast", "seedance-2.0", "seedance-1.0-pro", "seedance-1.0-fast"], "image": ["gpt-image-2", "gpt-image-2.5-flare", "gpt-image-2.5-sunburst", "nano-banana-pro", "nano-banana-2.1", "seedream-5.5", "seedream-5.0-pro", "seedream-5.0-lite", "seedream-4.7", "seedream-4.6", "seedream-4.5", "seedream-4.1", "seedream-4.0", "seedream-3.1", "seedream-3.0"] }, "credits": { "total": 500, "vip": 200, "gift": 200, "purchase": 100, "dailyClaimed": false } } ``` **400** **400 Bad Request** Validation error (missing/invalid parameters). ```json { "error": "Parameter email is required" } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "Unauthorized" } ``` **402** **402 Payment Required** Your useapi.net subscription is missing or has expired, or it does not cover one more Dreamina account (each [subscription](/docs/subscription) connects 3). ```json { "error": "useapi.net ⁝ Monthly subscription 261008 expired, please renew your subscription before submitting new requests.", "code": 402 } ``` ```json { "error": "useapi.net ⁝ You have 1 subscription, you need 1 additional subscription (2 total) to support 4 accounts for the dreamina API. Upgrade at https://useapi.net/docs/subscription", "code": 402 } ``` **500** **500 Internal Server Error** Login failed (bad credentials, upstream error). ```json { "error": "Login failed: invalid credentials" } ``` ### Model The configured account with its region, `maxJobs`, session expiry, available video and image models and credit balance. <details markdown="block" class="model-details"> <summary>The configured account, field by field</summary> - `account` - Account identifier - `email` - Dreamina account email - `region` - Region code - `maxJobs` - Maximum concurrent jobs - `sessionExpires` - ISO 8601 timestamp when session expires - `session` - Session details including refresh timing - `models` - Available video and image generation models - `credits` - Credit balance breakdown ```typescript { // TypeScript, all fields are optional account: string // "CA:user@example.com" email: string region: string // "US" or "CA" maxJobs: number // 1-50 sessionExpires: string // ISO 8601 timestamp session: { expires: string // ISO 8601 timestamp lastRefreshed: string // ISO 8601 timestamp daysUntilExpiry: number } models: { video: string[] // Available video model names image: string[] // Available image model names } credits: { total: number vip: number gift: number purchase: number dailyClaimed: boolean } error?: string // Error message } ``` </details> ### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -X POST "https://api.useapi.net/v1/dreamina/accounts" \ -d '{ "email": "user@example.com", "password": "your-password", "region": "CA" }' ``` **JavaScript** ``` javascript const apiUrl = 'https://api.useapi.net/v1/dreamina/accounts'; const token = 'YOUR_API_TOKEN'; const response = await fetch(apiUrl, { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ email: 'user@example.com', password: 'your-password', region: 'CA' }) }); const result = await response.json(); console.log('Account configured:', result); ``` **Python** ``` python import requests apiUrl = 'https://api.useapi.net/v1/dreamina/accounts' token = 'YOUR_API_TOKEN' headers = { 'Content-Type': 'application/json', 'Authorization': f'Bearer {token}' } body = { 'email': 'user@example.com', 'password': 'your-password', 'region': 'CA' } response = requests.post(apiUrl, headers=headers, json=body) print(response.status_code, response.json()) ``` ### Try It <script> async function apiTestAccountDreamina() { data = { method: 'POST', headers: { 'Authorization': `Bearer ${document.getElementById('post-accounts-Dreamina-api_token').value}`, 'Content-Type': 'application/json' } }; let email = document.getElementById('post-accounts-Dreamina-email')?.value; let password = document.getElementById('post-accounts-Dreamina-password')?.value; let region = document.getElementById('post-accounts-Dreamina-region')?.value; data.body = JSON.stringify({ email, password, region }); await apiExecute(`https://api.useapi.net/v1/dreamina/accounts`, 'post-accounts-Dreamina', data); } </script> <form id="post-accounts-Dreamina" onsubmit="return false;" class="input-form"> <div class="input-field"> <div class="input-field-row"> <label for="post-accounts-Dreamina-api_token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="post-accounts-Dreamina-api_token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> <label for="post-accounts-Dreamina-email"><span>email (required)</span> <input id="post-accounts-Dreamina-email" type="text" class="input-element" required aria-required="true" placeholder="user@example.com"> </label> <label for="post-accounts-Dreamina-password"><span>password (required)</span> <input id="post-accounts-Dreamina-password" type="text" class="input-element" required aria-required="true"> </label> <label for="post-accounts-Dreamina-region"><span>region (required)</span> <select id="post-accounts-Dreamina-region" class="input-element"> <option value="CA">CA (Canada)</option> <option value="US">US</option> </select> </label> </div> <button id="post-accounts-Dreamina-button" class="btn btn-primary fs-3" type="submit" onclick="apiTestAccountDreamina()">Go</button> </div> </form> <div id="post-accounts-Dreamina-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-dreamina-v1/post-dreamina-assets-account === Document URL: https://useapi.net/docs/api-dreamina-v1/post-dreamina-assets-account --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> assets/`account` description: "Upload images, videos, or audio to Dreamina via POST assets/account in the useapi.net Dreamina API v1 for use as reference inputs in video and image generation." parent: Dreamina API nav_order: 500 --- ## Upload Assets February 23, 2026 (November 16, 2026) --- Upload images, videos, and audio files to Dreamina for use in video and image generation. **Images** (max 10 MB): | Content-Type | File Extension | | ------------ | -------------- | | image/jpeg | jpeg, jpg | | image/png | png | | image/webp | webp | **Videos** (max 50 MB, 1.8-30.2 seconds, 300-6000px): | Content-Type | File Extension | | ------------ | -------------- | | video/mp4 | mp4 | | video/quicktime | mov | | video/webm | webm | **Audio** (max 15 MB, 1.8-30.2 seconds): | Content-Type | File Extension | | ------------ | -------------- | | audio/mpeg | mp3 | | audio/mp3 | mp3 | | audio/wav | wav | | audio/mp4 | m4a | | audio/aac | aac | The returned `assetRef` is used as: - **Images:** `firstFrameRef`, `endFrameRef`, `frame_N_imageRef`, or `omni_N_imageRef` in [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos), and `imageRef_N` in [POST /images](/docs/api-dreamina-v1/post-dreamina-images). - **Videos:** `omni_N_videoRef` in [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos) Omni Reference mode, or `editVideoRef` there to re-cut the video in Edit mode. - **Audio:** `omni_N_audioRef` in [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos) Omni Reference mode. The duration and dimension limits above are the loosest any model accepts, so one upload can be reused across models. Each model applies its own tighter caps when you submit the generation — `seedance-2.5` and `seedance-2.5-draft` take 10 videos and 10 audio clips per request, `seedance-2.5-flash` takes 5 of each, the Seedance 2.0 family takes 3 of each with videos up to 15.4s and audio up to 15s. See the reference-limit table on [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos). > **https://api.useapi.net/v1/dreamina/assets/`account`** ### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: select from the table above ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. - `Content-Type` is **required**, see table above. ### Path Parameters - `account` is **required**. ### Request Body Binary image content (raw bytes). ### Responses **200** **200 OK** Asset uploaded successfully. Returns the `assetRef` for use in video and image generation. **Image response:** ```json { "assetRef": "CA:user@example.com-image:w2560:h1440:s580914-uri:tos-alisg-i-wopfjsm1ax-sg/abc123", "account": "CA:user@example.com", "width": 2560, "height": 1440, "size": 580914 } ``` **Video response:** ```json { "assetRef": "CA:user@example.com-video:w1070:h1904:s1656759:d5880-vid:v10762g50003d77lv1nog65ie0vi8oh0", "account": "CA:user@example.com", "type": "video", "width": 1070, "height": 1904, "duration": 5880, "size": 1656759 } ``` **Audio response:** ```json { "assetRef": "CA:user@example.com-audio:w480:h360:s562605:d14040-vid:v10762g50003d77l5uvog65nl4esjs2g", "account": "CA:user@example.com", "type": "audio", "duration": 14040, "size": 562605 } ``` - `assetRef` - Reference ID for use in generation endpoints. - `type` - Asset type: `image`, `video`, or `audio` (omitted for images for backward compatibility). - `width` - Width in pixels (images and videos). - `height` - Height in pixels (images and videos). - `duration` - Duration in milliseconds (videos and audio). - `size` - File size in bytes. - `account` - Account used for the upload. **assetRef formats:** - Image: `<account>-image:w<width>:h<height>:s<size>-uri:<nativeUri>` - Video: `<account>-video:w<width>:h<height>:s<size>:d<durationMs>-vid:<videoId>` - Audio: `<account>-audio:w<width>:h<height>:s<size>:d<durationMs>-vid:<videoId>` **400** **400 Bad Request** Invalid request (empty content, unsupported content type, file too large, duration out of range, or an account that is not configured). ```json { "error": "Content-Type (image/bmp) not supported. Valid values: image/jpeg, image/png, image/webp, video/mp4, video/quicktime, video/webm, audio/mpeg, audio/mp3, audio/wav, audio/x-wav, audio/mp4, audio/aac" } ``` ```json { "error": "video exceeds 50MB limit (52.1MB)" } ``` ```json { "error": "Audio duration 31.4s exceeds 30.2s limit" } ``` ```json { "error": "Unable to find configuration for account US:user@example.com. Please add configuration via POST /v1/dreamina/accounts", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "Unauthorized" } ``` **596** **596 Session Error** The account's session expired or Dreamina locked it, or the account is in its sign-out pause. Check [GET /accounts](/docs/api-dreamina-v1/get-dreamina-accounts): an account with `signedOutPauseUntil` comes back by itself after the pause, any other account needs to be re-added using [POST /accounts](/docs/api-dreamina-v1/post-dreamina-accounts) with correct credentials. ```json { "error": "Dreamina account session expired or locked. Please re-add account via POST /v1/dreamina/accounts", "code": 596 } ``` When Dreamina signs an account out again right after a fresh sign-in, the account is paused for 30 minutes. While the pause runs, [GET /accounts](/docs/api-dreamina-v1/get-dreamina-accounts) shows `signedOutPauseUntil` (an ISO 8601 time) on that account, requests that name it answer `596`, and automatic account selection uses your other accounts. When every account is paused, requests answer `596`. After the pause the account is used again. If Dreamina signs it out right after a fresh sign-in again, after the pause and within 24 hours, the account is marked with an `error` and answers `596` until you re-add it with [POST /accounts](/docs/api-dreamina-v1/post-dreamina-accounts). Re-adding an account also ends its pause. A sign-in that fails for a temporary reason, not because Dreamina refused the account, answers `503` with a `Retry-After: 30` header. The account is fine: retry in about 30 seconds. ### Model The uploaded file's `assetRef` for [POST videos](/docs/api-dreamina-v1/post-dreamina-videos) and [POST images](/docs/api-dreamina-v1/post-dreamina-images), with its size and its dimensions or duration. <details markdown="block" class="model-details"> <summary>The uploaded file, field by field</summary> ```typescript { assetRef: string // Reference ID for POST /videos and POST /images account: string // "CA:user@example.com" type?: string // "image", "video", or "audio" (omitted for images) width?: number // Width in pixels (images and videos) height?: number // Height in pixels (images and videos) duration?: number // Duration in milliseconds (videos and audio) size?: number // File size in bytes imageRef?: string // Legacy alias for assetRef (backward compatibility, images only) error?: string // Error message } ``` </details> ### Examples **Curl** ``` bash curl -X POST \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: image/jpeg" \ --data-binary @/path/to/your/image.jpeg \ "https://api.useapi.net/v1/dreamina/assets/US:user@example.com" ``` **JavaScript** ``` javascript const token = 'YOUR_API_TOKEN'; const account = 'US:user@example.com'; const apiUrl = `https://api.useapi.net/v1/dreamina/assets/${encodeURIComponent(account)}`; // Load image - Example 1: From local file (Node.js) const fsp = require('fs').promises; const blob = new Blob([await fsp.readFile('./image.jpeg')]); // Load image - Example 2: From file input element // const imageFile = document.getElementById('image-file'); // const blob = imageFile.files[0]; const response = await fetch(apiUrl, { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': blob.type || 'image/jpeg' }, body: blob }); const result = await response.json(); console.log('Upload result:', result); console.log('assetRef:', result.assetRef); ``` **Python** ``` python import requests from urllib.parse import quote token = 'YOUR_API_TOKEN' account = 'US:user@example.com' api_url = f'https://api.useapi.net/v1/dreamina/assets/{quote(account, safe="")}' with open('./image.jpeg', 'rb') as image_file: file_content = image_file.read() headers = { 'Authorization': f'Bearer {token}', 'Content-Type': 'image/jpeg' } response = requests.post(api_url, headers=headers, data=file_content) result = response.json() print('Upload result:', result) print('assetRef:', result.get('assetRef')) ``` ### Try It <script> async function apiExecutePostDreaminaAssetAccount() { const tokenElement = document.getElementById('input-token'); const accountElement = document.getElementById('input-account'); const inputFile = document.getElementById('input-file'); if (!inputFile.files[0]) { alert('Please select a file.'); return false; } const blob = inputFile.files[0]; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${tokenElement.value}`, 'Content-Type': blob.type || 'image/jpeg' }, body: blob }; await apiExecute( `https://api.useapi.net/v1/dreamina/assets/${encodeURIComponent(accountElement.value)}`, 'input', data ); } function clearInputFile() { document.getElementById('input-file').value = ''; return false; } </script> <form id="input" class="input-form" onsubmit="return false;"> <div class="input-field"> <div class="input-field-row"> <label for="input-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="input-token" type="text" class="input-element" required aria-required="true"> </label> <label for="input-account"><span>account (required)</span> <input id="input-account" type="text" class="input-element" required aria-required="true" placeholder="US:user@example.com"> </label> <label for="input-file"><span>Upload file</span> <div style="display:flex"> <button id="input-file-clear" onclick="clearInputFile()">Clear </button> <input id="input-file" type="file" class="input-element" accept="image/png,image/jpeg,image/webp,video/mp4,video/quicktime,video/webm,audio/mpeg,audio/mp3,audio/wav,audio/mp4,audio/aac"> </div> </label> </div> <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecutePostDreaminaAssetAccount()">Go</button> </div> </form> <div id="input-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-dreamina-v1/post-dreamina-images-upscale === Document URL: https://useapi.net/docs/api-dreamina-v1/post-dreamina-images-upscale --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> images/upscale description: "Upscale a Dreamina-generated image to 2K, 4K, or 8K via POST images/upscale in the useapi.net Dreamina API v1 — asynchronous; poll GET images/jobid for the result." parent: Dreamina API nav_order: 730 --- ## Upscale Image March 2, 2026 (November 16, 2026) --- Upscale a generated image to higher resolution (2K, 4K, or 8K). Requires a completed image generation job from [POST /images](/docs/api-dreamina-v1/post-dreamina-images). Upscale is asynchronous — poll [GET /images/`jobid`](/docs/api-dreamina-v1/get-dreamina-images-jobid) for the result. > **https://api.useapi.net/v1/dreamina/images/upscale** ### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Request Body ```json { "jobid": "j0302140530123456789i-u12345-US:user@example.com-bot:dreamina", "imageIndex": 0, "upscaleResolution": "4k" } ``` - `jobid` is **required**. The job ID of a completed image generation job from [POST /images](/docs/api-dreamina-v1/post-dreamina-images). - `imageIndex` is optional. Index of the image to upscale from the source job (0-3, default: `0`). A job can make up to 8 images (`count` up to 8), but only its first 4 can be upscaled. - `upscaleResolution` is optional. Target resolution (default: `4k`). Supported values: `2k`, `4k`, `8k`. - `originalImageStrength` is optional. How much of the original image to preserve (0-1, default: `0.65`). - `detailStrength` is optional. Detail enhancement level (0-1, default: `0.5`). - `replyUrl` is optional, webhook URL for job status callbacks. Callback body has the same JSON shape as [GET /images/`jobid`](/docs/api-dreamina-v1/get-dreamina-images-jobid) response. - `replyRef` is optional, custom reference string passed back in webhook callbacks. ### Responses **200** **200 OK** Upscale job created. Poll [GET /images/`jobid`](/docs/api-dreamina-v1/get-dreamina-images-jobid) for the result. ```json { "jobid": "j0302140630123456789I-u12345-US:user@example.com-bot:dreamina", "type": "upscale", "status": "created", "model": "seedream-4.0", "created": "2026-03-02T14:06:30.123Z", "request": { "jobid": "j0302140530123456789i-u12345-US:user@example.com-bot:dreamina", "imageIndex": 0, "resolution": "4k" }, "response": { "forecastCost": 0 }, "code": 200 } ``` **400** **400 Bad Request** Validation error. ```json { "error": "Parameter jobid is required" } ``` ```json { "error": "Source image job is created, must be completed" } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "Unauthorized" } ``` **404** **404 Not Found** Source image job not found. ```json { "error": "Source image job not found", "code": 404 } ``` ### Examples **Curl** ``` bash curl -X POST \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "jobid": "j0302140530123456789i-u12345-US:user@example.com-bot:dreamina", "imageIndex": 0, "upscaleResolution": "4k" }' \ "https://api.useapi.net/v1/dreamina/images/upscale" ``` **JavaScript** ``` javascript const token = 'YOUR_API_TOKEN'; const response = await fetch('https://api.useapi.net/v1/dreamina/images/upscale', { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ jobid: 'j0302140530123456789i-u12345-US:user@example.com-bot:dreamina', imageIndex: 0, upscaleResolution: '4k' }) }); const result = await response.json(); console.log('Upscale job:', result.jobid); // Poll for completion const poll = async (jobid) => { while (true) { const res = await fetch(`https://api.useapi.net/v1/dreamina/images/${jobid}`, { headers: { 'Authorization': `Bearer ${token}` } }); const job = await res.json(); if (job.status === 'completed') { console.log('Upscaled:', job.response.images[0].width, 'x', job.response.images[0].height); return job; } if (job.status === 'failed') throw new Error(job.error); await new Promise(r => setTimeout(r, 10000)); } }; await poll(result.jobid); ``` **Python** ``` python import requests import time token = 'YOUR_API_TOKEN' response = requests.post( 'https://api.useapi.net/v1/dreamina/images/upscale', headers={ 'Authorization': f'Bearer {token}', 'Content-Type': 'application/json' }, json={ 'jobid': 'j0302140530123456789i-u12345-US:user@example.com-bot:dreamina', 'imageIndex': 0, 'upscaleResolution': '4k' } ) result = response.json() print(f"Upscale job: {result['jobid']}") # Poll for completion jobid = result['jobid'] while True: job = requests.get( f'https://api.useapi.net/v1/dreamina/images/{jobid}', headers={'Authorization': f'Bearer {token}'} ).json() if job['status'] == 'completed': img = job['response']['images'][0] print(f"Upscaled: {img['width']}x{img['height']}") break if job['status'] == 'failed': raise Exception(job.get('error')) time.sleep(10) ``` ### Try It <script> async function apiExecutePostDreaminaImagesUpscale() { const tokenElement = document.getElementById('input-token'); const elementId = 'input'; const payload = {}; const inputs = document.querySelectorAll('.input-query-param'); inputs.forEach(input => { const id = input.id; const value = input.value?.trim(); if (id.startsWith('input-') && value !== '' && value !== undefined) { const key = id.replace('input-', ''); if (key === 'imageIndex' || key === 'maxJobs') { payload[key] = parseInt(value); } else if (key === 'originalImageStrength' || key === 'detailStrength') { payload[key] = parseFloat(value); } else { payload[key] = value; } } }); const data = { method: 'POST', headers: { 'Authorization': `Bearer ${tokenElement.value}`, 'Content-Type': 'application/json' }, body: JSON.stringify(payload) }; await apiExecute('https://api.useapi.net/v1/dreamina/images/upscale', elementId, data); } </script> <form id="input" class="input-form" onsubmit="return false;"> <div class="input-field"> <div class="input-field-row"> <label for="input-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="input-token" type="text" class="input-element" required aria-required="true"> </label> <label for="input-jobid"><span>jobid (required, from POST /images)</span> <input id="input-jobid" type="text" class="input-element input-query-param" required aria-required="true"> </label> <label for="input-imageIndex"><span>imageIndex (0-3, default: 0)</span> <input id="input-imageIndex" type="number" class="input-element input-query-param" min="0" max="3" placeholder="0"> </label> <label for="input-upscaleResolution"><span>upscaleResolution</span> <select id="input-upscaleResolution" class="input-element input-query-param"> <option value="">4k (default)</option> <option value="2k">2k</option> <option value="4k">4k</option> <option value="8k">8k</option> </select> </label> <label for="input-originalImageStrength"><span>originalImageStrength (0-1, default: 0.65)</span> <input id="input-originalImageStrength" type="number" class="input-element input-query-param" min="0" max="1" step="0.05" placeholder="0.65"> </label> <label for="input-detailStrength"><span>detailStrength (0-1, default: 0.5)</span> <input id="input-detailStrength" type="number" class="input-element input-query-param" min="0" max="1" step="0.1" placeholder="0.5"> </label> <label for="input-replyUrl"><span>replyUrl (webhook URL)</span> <input id="input-replyUrl" type="text" class="input-element input-query-param" placeholder="https://your-domain.com/webhook"> </label> <label for="input-replyRef"><span>replyRef (custom reference)</span> <input id="input-replyRef" type="text" class="input-element input-query-param" placeholder="my-custom-id-123"> </label> </div> <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecutePostDreaminaImagesUpscale()">Go</button> </div> </form> <div id="input-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-dreamina-v1/post-dreamina-images === Document URL: https://useapi.net/docs/api-dreamina-v1/post-dreamina-images --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> images description: "Submit a Dreamina image prompt via POST images in the useapi.net Dreamina API v1 — generates up to 4 images per job; poll GET images/jobid or use a replyUrl webhook." parent: Dreamina API nav_order: 710 --- ## Generate Images March 4, 2026 (November 18, 2026) --- Generate images using Dreamina AI models from text prompts with optional reference images. All image generation is asynchronous — this endpoint returns immediately with a job ID. Poll [GET /images/`jobid`](/docs/api-dreamina-v1/get-dreamina-images-jobid) for completion, or use `replyUrl` webhook for automatic callbacks. The Images column shows how many images a request makes, with the range `count` accepts in brackets. Generation typically completes within 15-120 seconds depending on the model and resolution. ### Models | Model | Region | Images | Resolutions | Max Refs | Prompt Required | Auto Ratio | |-------|--------|--------|-------------|----------|-----------------|------------| | `gpt-image-2.5-flare` | US, CA | 1 | 1k (default), 2k, 4k | 6 | No (imageRef_x only) | No | | `gpt-image-2.5-sunburst` | US, CA | 1 | 1k (default), 2k, 4k | 6 | No (imageRef_x only) | No | | `nano-banana-pro` | US, CA | 1 (1–4) | 1k (default), 2k, 4k | 6 | No (imageRef_x only) | No | | `nano-banana-2.1` | CA | 2 (1–4) | 1k (default), 2k, 4k | 6 | No (imageRef_x only) | No | | `gpt-image-2` | US, CA | 1 | 1k (default), 2k, 4k | 6 | No (imageRef_x only) | No | | `seedream-5.5` | CA | 4 (1–8) | 1.5k (default), 2k | 6 | No (imageRef_x only) | Yes | | `seedream-5.0-pro` | US, CA | 4 (1–4) | 1.5k (CA only), 2k (default), 4k | 6 | No (imageRef_x only) | Yes | | `seedream-5.0-flash` | US | 4 (1–4) | 1.5k, 2k (default), 4k | 6 | No (imageRef_x only) | Yes | | `seedream-5.0-lite` | CA | 4 (1–8) | 2k (default), 4k | 6 | No (imageRef_x only) | Yes | | `seedream-4.7` | CA | 4 (1–8) | 2k (default), 4k | 6 | No (imageRef_x only) | Yes | | `seedream-4.6` (default model, runs on a free account's daily credits) | US, CA | 4 (1–8) | 2k (default), 4k | 6 | No (imageRef_x only) | Yes | | `seedream-4.5` | US, CA | 4 (1–8, US 1–4) | 2k (default), 4k | 6 | No (imageRef_x only) | Yes | | `seedream-4.1` | US, CA | 4 (1–8, US 1–4) | 2k (default), 4k | 6 | No (imageRef_x only) | Yes | | `seedream-4.0` | US, CA | 4 (1–8) | 2k (default), 4k | 6 | No (imageRef_x only) | Yes | | `seedream-3.1` | CA | 4 | 1k (default), 2k | 0 (text only) | Yes | No | | `seedream-3.0` | US, CA | 4 | 1k (default), 2k (2k without imageRef_x only) | 1 | Yes | No | > **https://api.useapi.net/v1/dreamina/images** ### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Request Body ```json { "prompt": "A stunning aurora borealis over a frozen lake at midnight", "model": "seedream-4.6", "ratio": "16:9", "resolution": "2k" } ``` - `account` is optional. Specific account to use. If omitted, a random account with free capacity is picked among those whose region offers `model`. Not needed when `imageRef_N` provided — account is derived from the reference. - `prompt` is **required**, optional when model supports `imageRef_N`. Maximum 5000 characters. - `model` is optional, see [Models](#models) above. - `ratio` is optional, image aspect ratio (default: `auto` for models that support it, `1:1` otherwise). Supported values: `auto`, `1:1`, `3:4`, `16:9`, `4:3`, `9:16`, `2:3`, `3:2`, `21:9`. - `resolution` is optional, output resolution tier (default depends on model, see [Models](#models)). Supported values: `1k`, `1.5k`, `2k`, `4k`. `1.5k` is offered by `seedream-5.5`, `seedream-5.0-flash` and `seedream-5.0-pro` (CA). - `background` is optional, `auto` (default), `opaque` or `transparent`. Supported by `seedream-5.5`, `gpt-image-2`, `gpt-image-2.5-flare` and `gpt-image-2.5-sunburst`. `transparent` returns PNG images with a transparent background, the Transparent option in Dreamina's image settings. - `imageRef_1`…`imageRef_6` are optional. Reference images from [POST /assets/`account`](/docs/api-dreamina-v1/post-dreamina-assets-account) or completed image job `assetRef`. Must be contiguous, max per model see [Models](#models). - `imageStrength` is optional, reference image influence strength (0-1, default: `0.5`). - `count` is optional, the number of images to make, within the model's range in the Images column of [Models](#models). Each image is charged. - `unlimited` is optional, `true` makes the images in Dreamina's Unlimited mode, at no credits. Models, resolutions and answers: [Unlimited](#unlimited) below. - `replyUrl` is optional, webhook URL for job status callbacks. Callback body has the same JSON shape as [GET /images/`jobid`](/docs/api-dreamina-v1/get-dreamina-images-jobid) response. - `replyRef` is optional, custom reference string passed back in webhook callbacks. - `maxJobs` is optional, override max concurrent jobs for this request (1-50). ### Unlimited With `unlimited` set to `true` the job uses no credits. Unlimited comes with a Dreamina plan bought or upgraded during Dreamina's November 2026 offers. Dreamina decides which of these models and resolutions an account gets and for how many days, and can end it early. | Model | Unlimited at | Per request | Accounts | |---|---|---|---| | `seedance-2.5` | 480p, 720p | 1 video, up to 30 s | US, CA | | `seedance-2.5-flash` | 480p, 720p | 1 video, up to 30 s | CA | | `seedance-2.5-draft` | 480p | 1 video, up to 30 s | US, CA | | `seedance-2.0` | 720p | 1 video, up to 15 s | US, CA | | `seedance-2.0-fast` | 720p | 1 video, up to 15 s | US, CA | | `seedance-2.0-mini` | 720p | 1 video, up to 15 s | US, CA | | `seedream-5.5` | 1.5K, 2K | up to 4 images | CA | | `gpt-image-2.5-flare`<br>`gpt-image-2.5-sunburst` | 1K, 2K | 1 image | US, CA | | `nano-banana-pro` | 1K, 2K | up to 4 images | US, CA | | `nano-banana-2.1` | 1K, 2K | up to 4 images | CA | - The plan decides which of these resolutions are Unlimited. 4K never is. - Video references and edits are included. The Seedance 2.5 models stop at 30 seconds, so long video is not. - An image request without `count` asks for the most the model allows, 4 images (1 on GPT Image 2.5). - Dreamina runs one Unlimited job at a time per account, videos and images together. | Answer | When | |---|---| | `400` | A model not in the table. On POST /videos also another resolution or a long video. | | `412` | The account has no Unlimited for this model and resolution, or it has ended. Send the request without `unlimited` to use credits. | | `429` | The account is already running an Unlimited job. Retry after it finishes. | ### Responses **200** **200 OK** Job created successfully. Images are generating in the background. ```json { "jobid": "j0302140530123456789i-u12345-US:user@example.com-bot:dreamina", "type": "image", "status": "created", "model": "seedream-4.6", "created": "2026-03-02T14:05:30.123Z", "request": { "prompt": "A stunning aurora borealis over a frozen lake at midnight", "model": "seedream-4.6", "ratio": "16:9", "resolution": "2k", "inputMode": "generate", "replyUrl": "https://your-domain.com/webhook", "replyRef": "my-ref-123" }, "response": { "forecastCost": 0 }, "code": 200 } ``` Poll [GET /images/`jobid`](/docs/api-dreamina-v1/get-dreamina-images-jobid) for completion status, or use `replyUrl` for webhook callbacks. **400** **400 Bad Request** Validation error. ```json { "error": "Parameter model (invalid-model) valid values: seedream-5.5, seedream-5.0-pro, seedream-5.0-flash, seedream-5.0-lite, seedream-4.7, seedream-4.6, seedream-4.5, seedream-4.1, seedream-4.0, seedream-3.1, seedream-3.0, gpt-image-2, gpt-image-2.5-flare, gpt-image-2.5-sunburst, nano-banana-pro, nano-banana-2.1" } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "Unauthorized" } ``` **412** **412 Precondition Failed** The Dreamina account does not have enough credits for this job (`ret` `1006`), or `unlimited` was set and the account has no Unlimited for this model and resolution, or it has ended (`ret` `1311`). Top up the account, send the request without `unlimited`, or use another account. ```json { "error": "Account CA:user@example.com has no Unlimited generations left for seedream-5.5 at this resolution: Dreamina's Unlimited is a promotion benefit per account, model and resolution (the plan decides which, never 4K), and it also ends. Send the request without unlimited (it then uses credits), at a resolution the account's Unlimited covers, or on an account whose Unlimited is still active. Dreamina: Unlimited generations have ended. Future generations will use credits.", "code": 412, "ret": "1311", "errmsg": "Unlimited generations have ended. Future generations will use credits.", "failCode": "1311", "failStarlingMessage": "Unlimited generations have ended. Future generations will use credits.", "account": "CA:user@example.com", "model": "seedream-5.5" } ``` **429** **429 Too Many Requests** All accounts at maximum capacity. Wait for current jobs to complete or increase `maxJobs`. When you set `account`, or only one of your accounts can take the job, the message names that account instead: `Account <account> is busy executing <N> tasks`. ```json { "error": "All configured accounts are running at maximum capacity", "code": 429 } ``` ### Model The new job's `jobid` with status `created`: poll it with [GET /images/`jobid`](/docs/api-dreamina-v1/get-dreamina-images-jobid) until it completes or fails. <details markdown="block" class="model-details"> <summary>The new image job, field by field</summary> ```typescript { jobid: string // Unique job identifier type: 'image' // Job type status: 'created' // Initial status model: string // Model used created: string // ISO 8601 timestamp request: { prompt?: string model: string ratio?: string resolution?: string inputMode: string // Auto-detected from params imageRef_1?: string // Reference image assetRef (when provided) imageRef_2?: string imageRef_3?: string replyUrl?: string replyRef?: string } response: { forecastCost: number // Estimated generation time in seconds, NOT a price } code: number // HTTP status code error?: string } ``` </details> ### Examples **Curl** ``` bash # Text-to-image curl -X POST \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A stunning aurora borealis over a frozen lake", "model": "seedream-4.6", "ratio": "16:9", "resolution": "2k" }' \ "https://api.useapi.net/v1/dreamina/images" # With reference image curl -X POST \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A dreamy reinterpretation with soft pastel colors", "model": "seedream-4.1", "imageRef_1": "US:user@example.com-image:w685:h900:s86866-uri:tos-useast5-i-wopfjsm1ax-tx/abc123", "imageStrength": 0.5 }' \ "https://api.useapi.net/v1/dreamina/images" ``` **JavaScript** ``` javascript const token = 'YOUR_API_TOKEN'; const apiUrl = 'https://api.useapi.net/v1/dreamina/images'; // Text-to-image const response = await fetch(apiUrl, { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ prompt: 'A stunning aurora borealis over a frozen lake', model: 'seedream-4.6', ratio: '16:9', resolution: '2k' }) }); const result = await response.json(); console.log('Job created:', result.jobid); // Poll for completion const poll = async (jobid) => { while (true) { const res = await fetch(`https://api.useapi.net/v1/dreamina/images/${jobid}`, { headers: { 'Authorization': `Bearer ${token}` } }); const job = await res.json(); console.log('Status:', job.status); if (job.status === 'completed') { console.log('Images:', job.response.images.length); job.response.images.forEach((img, i) => console.log(` [${i}] ${img.width}x${img.height} ${img.imageUrl}`) ); return job; } if (job.status === 'failed') throw new Error(job.error); await new Promise(r => setTimeout(r, 10000)); } }; const completed = await poll(result.jobid); ``` **Python** ``` python import requests import time token = 'YOUR_API_TOKEN' api_url = 'https://api.useapi.net/v1/dreamina/images' headers = { 'Authorization': f'Bearer {token}', 'Content-Type': 'application/json' } # Text-to-image data = { 'prompt': 'A stunning aurora borealis over a frozen lake', 'model': 'seedream-4.6', 'ratio': '16:9', 'resolution': '2k' } response = requests.post(api_url, headers=headers, json=data) result = response.json() print(f"Job created: {result['jobid']}") # Poll for completion jobid = result['jobid'] while True: job = requests.get( f'https://api.useapi.net/v1/dreamina/images/{jobid}', headers={'Authorization': f'Bearer {token}'} ).json() print(f"Status: {job['status']}") if job['status'] == 'completed': for i, img in enumerate(job['response']['images']): print(f" [{i}] {img['width']}x{img['height']} {img['imageUrl']}") break if job['status'] == 'failed': raise Exception(job.get('error')) time.sleep(10) ``` ### Try It <script> async function apiExecutePostDreaminaImages() { const tokenElement = document.getElementById('input-token'); const elementId = 'input'; const payload = {}; const inputs = document.querySelectorAll('.input-query-param'); inputs.forEach(input => { const id = input.id; const value = input.value?.trim(); if (id.startsWith('input-') && value !== '' && value !== undefined) { const key = id.replace('input-', ''); if (key === 'maxJobs' || key === 'imageStrength' || key === 'count') { payload[key] = parseFloat(value); } else if (key === 'unlimited') { payload[key] = value === 'true'; } else { payload[key] = value; } } }); const data = { method: 'POST', headers: { 'Authorization': `Bearer ${tokenElement.value}`, 'Content-Type': 'application/json' }, body: JSON.stringify(payload) }; await apiExecute('https://api.useapi.net/v1/dreamina/images', elementId, data); } </script> <form id="input" class="input-form" onsubmit="return false;"> <div class="input-field"> <div class="input-field-row"> <label for="input-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="input-token" type="text" class="input-element" required aria-required="true"> </label> <label for="input-account"><span>account (optional)</span> <input id="input-account" type="text" class="input-element input-query-param" placeholder="US:user@example.com"> </label> <label for="input-prompt"><span>prompt (required for T2I)</span> <input id="input-prompt" type="text" class="input-element input-query-param" placeholder="A stunning aurora borealis over a frozen lake"> </label> <label for="input-model"><span>model</span> <select id="input-model" class="input-element input-query-param"> <option value="seedream-4.6">seedream-4.6 (default)</option> <option value="seedream-5.5">seedream-5.5 (CA only)</option> <option value="seedream-5.0-pro">seedream-5.0-pro</option> <option value="seedream-5.0-flash">seedream-5.0-flash (US only)</option> <option value="seedream-5.0-lite">seedream-5.0-lite (CA only)</option> <option value="seedream-4.7">seedream-4.7 (CA only)</option> <option value="seedream-4.5">seedream-4.5</option> <option value="seedream-4.1">seedream-4.1</option> <option value="seedream-4.0">seedream-4.0 (4K free on Advanced and Ultra until Nov 6)</option> <option value="seedream-3.1">seedream-3.1 (CA only)</option> <option value="seedream-3.0">seedream-3.0</option> <option value="gpt-image-2">gpt-image-2</option> <option value="gpt-image-2.5-flare">gpt-image-2.5-flare</option> <option value="gpt-image-2.5-sunburst">gpt-image-2.5-sunburst</option> <option value="nano-banana-pro">nano-banana-pro</option> <option value="nano-banana-2.1">nano-banana-2.1 (CA only)</option> </select> </label> <label for="input-ratio"><span>ratio</span> <select id="input-ratio" class="input-element input-query-param"> <option value="">auto</option> <option value="1:1">1:1</option> <option value="3:4">3:4</option> <option value="16:9">16:9</option> <option value="4:3">4:3</option> <option value="9:16">9:16</option> <option value="2:3">2:3</option> <option value="3:2">3:2</option> <option value="21:9">21:9</option> </select> </label> <label for="input-resolution"><span>resolution</span> <select id="input-resolution" class="input-element input-query-param"> <option value="">default</option> <option value="1k">1k</option> <option value="1.5k">1.5k (seedream-5.5, 5.0-flash, 5.0-pro on CA)</option> <option value="2k">2k</option> <option value="4k">4k</option> </select> </label> <label for="input-background"><span>background (seedream-5.5 and GPT Image only)</span> <select id="input-background" class="input-element input-query-param"> <option value="">default (auto)</option> <option value="auto">auto</option> <option value="opaque">opaque</option> <option value="transparent">transparent</option> </select> </label> <label for="input-count"><span>count (optional, images per request)</span> <input id="input-count" type="number" class="input-element input-query-param" min="1" max="8" step="1" placeholder="model default"> </label> <label for="input-unlimited"><span>unlimited (seedream-5.5, GPT Image 2.5, Nano Banana Pro and 2.1)</span> <select id="input-unlimited" class="input-element input-query-param"> <option value="">off</option> <option value="true">true</option> </select> </label> <label for="input-imageRef_1"><span>imageRef_1 (optional, from <a href="/docs/api-dreamina-v1/post-dreamina-assets-account">POST /assets/account</a>)</span> <input id="input-imageRef_1" type="text" class="input-element input-query-param" placeholder="US:user@example.com-image:w685:h900:s86866-uri:..."> </label> <label for="input-imageRef_2"><span>imageRef_2 (optional)</span> <input id="input-imageRef_2" type="text" class="input-element input-query-param" placeholder="US:user@example.com-image:w685:h900:s86866-uri:..."> </label> <label for="input-imageRef_3"><span>imageRef_3 (optional)</span> <input id="input-imageRef_3" type="text" class="input-element input-query-param" placeholder="US:user@example.com-image:w685:h900:s86866-uri:..."> </label> <label for="input-imageStrength"><span>imageStrength (0-1, default: 0.5)</span> <input id="input-imageStrength" type="number" class="input-element input-query-param" min="0" max="1" step="0.1" placeholder="0.5"> </label> <label for="input-replyUrl"><span>replyUrl (webhook URL)</span> <input id="input-replyUrl" type="text" class="input-element input-query-param" placeholder="https://your-domain.com/webhook"> </label> <label for="input-replyRef"><span>replyRef (custom reference)</span> <input id="input-replyRef" type="text" class="input-element input-query-param" placeholder="my-custom-id-123"> </label> </div> <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecutePostDreaminaImages()">Go</button> </div> </form> <div id="input-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-dreamina-v1/post-dreamina-videos-full-quality === Document URL: https://useapi.net/docs/api-dreamina-v1/post-dreamina-videos-full-quality --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/full-quality description: "Turn a finished Seedance 2.5 Draft into a 1080p or 4K video via POST videos/full-quality in the useapi.net Dreamina API v1, built from the draft you approved." parent: Dreamina API nav_order: 650 --- ## Generate in Full Quality November 12, 2026 (November 16, 2026) --- Turn a finished `seedance-2.5-draft` video into a full-quality Seedance 2.5 video, the way Dreamina's "Generate in full quality" button does. Make a cheap 480p draft with [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos) and `model: "seedance-2.5-draft"`, check it, then send its `jobid` here. Dreamina builds the full-quality video from that draft, so you get the video you approved rather than a new take on the same prompt. The video keeps the draft's prompt, references, length and aspect ratio. US accounts make 1080p, CA accounts 1080p or 4K. Dreamina keeps a draft for 14 days, so a draft older than that can no longer be used. Full quality costs the same as making the video with `seedance-2.5` at that resolution. The draft is an extra run on top of that, whether you then make 1080p or 4K, so it pays off when you would otherwise try a prompt more than once. Prices for the draft and every resolution are in the [cost calculator](/docs/start-here/setup-dreamina#cost-calculator). A draft itself can't be upscaled or interpolated. A 1080p full-quality video can be upscaled, and any full-quality video interpolated. The result is a regular video job: poll [GET /videos/`jobid`](/docs/api-dreamina-v1/get-dreamina-videos-jobid) or use `replyUrl`. A 4-second 1080p video took one to two minutes in our tests. A step-by-step walkthrough with real videos: [How to Draft Seedance 2.5 Videos at 480p and Finish Them in 1080p or 4K](/docs/articles/dreamina-seedance-2-5-draft). > **https://api.useapi.net/v1/dreamina/videos/full-quality** ### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Request Body ```json { "jobid": "j1112160030123456789v-u12345-CA:user@example.com-bot:dreamina", "resolution": "1080p" } ``` - `jobid` is **required**. The job ID of a completed `seedance-2.5-draft` job from [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos), at most 14 days old. The video is made on the same account. - `resolution` is optional, `1080p` (default) or `4k`. `4k` works on CA accounts only. - `replyUrl` is optional, webhook URL for job status callbacks. Callback body has the same JSON shape as [GET /videos/`jobid`](/docs/api-dreamina-v1/get-dreamina-videos-jobid) response. - `replyRef` is optional, custom reference string passed back in webhook callbacks. ### Responses **200** **200 OK** Job created. Poll [GET /videos/`jobid`](/docs/api-dreamina-v1/get-dreamina-videos-jobid) for the result. `request.draftJobid` is the draft it was made from. ```json { "jobid": "j1112160330123456789v-u12345-CA:user@example.com-bot:dreamina", "type": "video", "status": "created", "model": "seedance-2.5-draft", "created": "2026-11-12T16:03:06.825Z", "request": { "prompt": "A paper boat drifting down a rain-soaked street gutter", "model": "seedance-2.5-draft", "ratio": "9:16", "duration": 4, "inputMode": "full_quality", "resolution": "1080p", "draftJobid": "j1112160030123456789v-u12345-CA:user@example.com-bot:dreamina" }, "response": { "forecastCost": 209 }, "code": 200 } ``` **400** **400 Bad Request** The job is not a finished draft, the draft is older than 14 days, or the resolution is not offered on the account's region. ```json { "error": "Job j1112160030123456789v-u12345-CA:user@example.com-bot:dreamina is not a seedance-2.5-draft job. Make a draft with POST /videos and model seedance-2.5-draft first" } ``` ```json { "error": "Invalid resolution: 4k. A US draft can be made into 1080p" } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "Unauthorized" } ``` **403** **403 Forbidden** The draft belongs to another user, or the Dreamina account has no paid plan that includes Seedance 2.5. ```json { "error": "Account CA:user@example.com needs a paid Dreamina subscription for seedance-2.5-draft: Dreamina refused the job because the account has no plan that includes it (credits bought separately don't count). Subscribe at https://dreamina.capcut.com/pricing/dreamina-price, or use an account that has one. Dreamina: credit miss role" } ``` **412** **412 Precondition Failed** The Dreamina account is out of credits. ```json { "error": "Submit failed: Not enough credits left or no relevant benefits" } ``` **404** **404 Not Found** The draft job is unknown, or Dreamina no longer has the draft, for example because it was deleted from the account with [DELETE /assets/`assetId`](/docs/api-dreamina-v1/delete-dreamina-assets-assetid). ```json { "error": "Draft job not found", "code": 404 } ``` ```json { "error": "Dreamina has no draft <jobid> on account US:user@example.com any more. It may have been deleted from the account. Make a new draft", "code": 404 } ``` **502** **502 Bad Gateway** Dreamina did not answer when the draft was read. Retry in a minute. ```json { "error": "Dreamina did not return draft j1112160030123456789v-u12345-CA:user@example.com-bot:dreamina (HTTP 503). Retry in a minute" } ``` ### Examples **Curl** ``` bash curl -X POST \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "jobid": "YOUR_COMPLETED_DRAFT_JOBID", "resolution": "1080p" }' \ "https://api.useapi.net/v1/dreamina/videos/full-quality" ``` **JavaScript** ``` javascript const token = 'YOUR_API_TOKEN'; const response = await fetch('https://api.useapi.net/v1/dreamina/videos/full-quality', { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ jobid: 'YOUR_COMPLETED_DRAFT_JOBID', resolution: '1080p' }) }); const result = await response.json(); console.log('Full-quality job:', result.jobid); const poll = async (jobid) => { while (true) { const res = await fetch(`https://api.useapi.net/v1/dreamina/videos/${jobid}`, { headers: { 'Authorization': `Bearer ${token}` } }); const job = await res.json(); if (job.status === 'completed') { console.log('Video:', job.response.width, 'x', job.response.height, job.response.videoUrl); return job; } if (job.status === 'failed') throw new Error(job.error); await new Promise(r => setTimeout(r, 10000)); } }; await poll(result.jobid); ``` **Python** ``` python import requests import time token = 'YOUR_API_TOKEN' response = requests.post( 'https://api.useapi.net/v1/dreamina/videos/full-quality', headers={ 'Authorization': f'Bearer {token}', 'Content-Type': 'application/json' }, json={ 'jobid': 'YOUR_COMPLETED_DRAFT_JOBID', 'resolution': '1080p' } ) result = response.json() print(f"Full-quality job: {result['jobid']}") jobid = result['jobid'] while True: job = requests.get( f'https://api.useapi.net/v1/dreamina/videos/{jobid}', headers={'Authorization': f'Bearer {token}'} ).json() if job['status'] == 'completed': r = job['response'] print(f"Video: {r['width']}x{r['height']} {r['videoUrl']}") break if job['status'] == 'failed': raise Exception(job.get('error')) time.sleep(10) ``` ### Try It <script> async function apiExecutePostDreaminaVideosFullQuality() { const tokenElement = document.getElementById('input-token'); const elementId = 'input'; const payload = {}; const inputs = document.querySelectorAll('.input-query-param'); inputs.forEach(input => { const id = input.id; const value = input.value?.trim(); if (id.startsWith('input-') && value !== '' && value !== undefined) { const key = id.replace('input-', ''); if (key === 'maxJobs') { payload[key] = parseInt(value); } else { payload[key] = value; } } }); const data = { method: 'POST', headers: { 'Authorization': `Bearer ${tokenElement.value}`, 'Content-Type': 'application/json' }, body: JSON.stringify(payload) }; await apiExecute('https://api.useapi.net/v1/dreamina/videos/full-quality', elementId, data); } </script> <form id="input" class="input-form" onsubmit="return false;"> <div class="input-field"> <div class="input-field-row"> <label for="input-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="input-token" type="text" class="input-element" required aria-required="true"> </label> <label for="input-jobid"><span>jobid (required, a completed seedance-2.5-draft job)</span> <input id="input-jobid" type="text" class="input-element input-query-param" required aria-required="true"> </label> <label for="input-resolution"><span>resolution</span> <select id="input-resolution" class="input-element input-query-param"> <option value="">default (1080p)</option> <option value="1080p">1080p</option> <option value="4k">4k (CA only)</option> </select> </label> <label for="input-replyUrl"><span>replyUrl (webhook URL)</span> <input id="input-replyUrl" type="text" class="input-element input-query-param" placeholder="https://your-domain.com/webhook"> </label> <label for="input-replyRef"><span>replyRef (custom reference)</span> <input id="input-replyRef" type="text" class="input-element input-query-param" placeholder="my-custom-id-123"> </label> </div> <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecutePostDreaminaVideosFullQuality()">Go</button> </div> </form> <div id="input-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-dreamina-v1/post-dreamina-videos-interpolate === Document URL: https://useapi.net/docs/api-dreamina-v1/post-dreamina-videos-interpolate --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/interpolate description: "Interpolate a Dreamina video to 30 or 60 FPS via POST videos/interpolate in the useapi.net Dreamina API v1 — adds intermediate frames for smoother motion." parent: Dreamina API nav_order: 706 --- ## Interpolate Video April 2, 2026 (November 16, 2026) --- Interpolate a generated video to higher frame rate (30 or 60 FPS from the original 24 FPS). Creates smoother motion by generating intermediate frames. Requires a completed video generation or video upscale job. Each video can only be interpolated once. You can interpolate both original and upscaled videos. Interpolation is asynchronous — poll [GET /videos/`jobid`](/docs/api-dreamina-v1/get-dreamina-videos-jobid) for the result. > **https://api.useapi.net/v1/dreamina/videos/interpolate** ### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Request Body ```json { "jobid": "j0302140530123456789v-u12345-CA:user@example.com-bot:dreamina", "fps": 60 } ``` - `jobid` is **required**. The job ID of a completed video generation job from [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos) or a completed video upscale job from [POST /videos/upscale](/docs/api-dreamina-v1/post-dreamina-videos-upscale). A `seedance-2.5-draft` video is refused with `400`, because Dreamina doesn't interpolate drafts: turn it into a full-quality video with [POST /videos/full-quality](/docs/api-dreamina-v1/post-dreamina-videos-full-quality) first. - `fps` is **required**. Target frame rate. Supported values: `30`, `60`. - `replyUrl` is optional, webhook URL for job status callbacks. Callback body has the same JSON shape as [GET /videos/`jobid`](/docs/api-dreamina-v1/get-dreamina-videos-jobid) response. - `replyRef` is optional, custom reference string passed back in webhook callbacks. ### Responses **200** **200 OK** Interpolation job created. Poll [GET /videos/`jobid`](/docs/api-dreamina-v1/get-dreamina-videos-jobid) for the result. ```json { "jobid": "j0302140630123456789F-u12345-CA:user@example.com-bot:dreamina", "type": "video-interpolate", "status": "created", "model": "seedance-2.0-fast", "created": "2026-04-02T10:06:30.123Z", "request": { "jobid": "j0302140530123456789v-u12345-CA:user@example.com-bot:dreamina", "fps": 60 }, "response": { "forecastCost": 66 }, "code": 200 } ``` **400** **400 Bad Request** Validation error. ```json { "error": "Source video job is created, must be completed" } ``` ```json { "error": "Source video already interpolated: j0302140630123456789F-u12345-CA:user@example.com-bot:dreamina" } ``` ```json { "error": "Parameter fps (24) valid values: 30, 60" } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "Unauthorized" } ``` **404** **404 Not Found** Source video job not found. ```json { "error": "Source video job not found", "code": 404 } ``` ### Examples **Curl** ``` bash # Interpolate a generated video to 60 FPS curl -X POST \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "jobid": "YOUR_COMPLETED_VIDEO_JOBID", "fps": 60 }' \ "https://api.useapi.net/v1/dreamina/videos/interpolate" # Interpolate an upscaled video to 30 FPS curl -X POST \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "jobid": "YOUR_COMPLETED_UPSCALE_JOBID", "fps": 30 }' \ "https://api.useapi.net/v1/dreamina/videos/interpolate" ``` **JavaScript** ``` javascript const token = 'YOUR_API_TOKEN'; const response = await fetch('https://api.useapi.net/v1/dreamina/videos/interpolate', { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ jobid: 'YOUR_COMPLETED_VIDEO_JOBID', fps: 60 }) }); const result = await response.json(); console.log('Interpolate job:', result.jobid); // Poll for completion const poll = async (jobid) => { while (true) { const res = await fetch(`https://api.useapi.net/v1/dreamina/videos/${jobid}`, { headers: { 'Authorization': `Bearer ${token}` } }); const job = await res.json(); if (job.status === 'completed') { console.log('Video URL:', job.response.videoUrl); return job; } if (job.status === 'failed') throw new Error(job.error); await new Promise(r => setTimeout(r, 10000)); } }; await poll(result.jobid); ``` **Python** ``` python import requests import time token = 'YOUR_API_TOKEN' response = requests.post( 'https://api.useapi.net/v1/dreamina/videos/interpolate', headers={ 'Authorization': f'Bearer {token}', 'Content-Type': 'application/json' }, json={ 'jobid': 'YOUR_COMPLETED_VIDEO_JOBID', 'fps': 60 } ) result = response.json() print(f"Interpolate job: {result['jobid']}") # Poll for completion jobid = result['jobid'] while True: job = requests.get( f'https://api.useapi.net/v1/dreamina/videos/{jobid}', headers={'Authorization': f'Bearer {token}'} ).json() if job['status'] == 'completed': print(f"Video URL: {job['response']['videoUrl']}") break if job['status'] == 'failed': raise Exception(job.get('error')) time.sleep(10) ``` ### Try It <script> async function apiExecutePostDreaminaVideosInterpolate() { const tokenElement = document.getElementById('input-token'); const elementId = 'input'; const payload = {}; const inputs = document.querySelectorAll('.input-query-param'); inputs.forEach(input => { const id = input.id; const value = input.value?.trim(); if (id.startsWith('input-') && value !== '' && value !== undefined) { const key = id.replace('input-', ''); if (key === 'fps' || key === 'maxJobs') { payload[key] = parseInt(value); } else { payload[key] = value; } } }); const data = { method: 'POST', headers: { 'Authorization': `Bearer ${tokenElement.value}`, 'Content-Type': 'application/json' }, body: JSON.stringify(payload) }; await apiExecute('https://api.useapi.net/v1/dreamina/videos/interpolate', elementId, data); } </script> <form id="input" class="input-form" onsubmit="return false;"> <div class="input-field"> <div class="input-field-row"> <label for="input-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="input-token" type="text" class="input-element" required aria-required="true"> </label> <label for="input-jobid"><span>jobid (required, from POST /videos or /videos/upscale)</span> <input id="input-jobid" type="text" class="input-element input-query-param" required aria-required="true"> </label> <label for="input-fps"><span>fps (required)</span> <select id="input-fps" class="input-element input-query-param"> <option value="30">30</option> <option value="60" selected>60</option> </select> </label> <label for="input-replyUrl"><span>replyUrl (webhook URL)</span> <input id="input-replyUrl" type="text" class="input-element input-query-param" placeholder="https://your-domain.com/webhook"> </label> <label for="input-replyRef"><span>replyRef (custom reference)</span> <input id="input-replyRef" type="text" class="input-element input-query-param" placeholder="my-custom-id-123"> </label> </div> <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecutePostDreaminaVideosInterpolate()">Go</button> </div> </form> <div id="input-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-dreamina-v1/post-dreamina-videos-upscale === Document URL: https://useapi.net/docs/api-dreamina-v1/post-dreamina-videos-upscale --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/upscale description: "Apply 2x super-resolution to a Dreamina video via POST videos/upscale in the useapi.net Dreamina API v1 — doubles dimensions (720p to 1440p, 1080p to 4K)." parent: Dreamina API nav_order: 705 --- ## Upscale Video April 2, 2026 (November 16, 2026) --- Upscale a generated video to 2x resolution (super resolution). Doubles both width and height — for example, 720p (1280x720) becomes 1440p (2560x1440), and 1080p (1920x1080) becomes 4K (3840x2160). Requires a completed video generation job from [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos). Each video can only be upscaled once. Upscale is asynchronous — poll [GET /videos/`jobid`](/docs/api-dreamina-v1/get-dreamina-videos-jobid) for the result. > **https://api.useapi.net/v1/dreamina/videos/upscale** ### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Request Body ```json { "jobid": "j0302140530123456789v-u12345-CA:user@example.com-bot:dreamina" } ``` - `jobid` is **required**. The job ID of a completed video generation job from [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos). Must be a video generation job (not an upscale job) at 480p, 720p or 1080p. Upscale doubles the size, so a `2k` or `4k` source is refused with `400`. A `seedance-2.5-draft` video is refused with `400` too, because Dreamina doesn't upscale drafts: turn it into a full-quality video with [POST /videos/full-quality](/docs/api-dreamina-v1/post-dreamina-videos-full-quality) first. - `replyUrl` is optional, webhook URL for job status callbacks. Callback body has the same JSON shape as [GET /videos/`jobid`](/docs/api-dreamina-v1/get-dreamina-videos-jobid) response. - `replyRef` is optional, custom reference string passed back in webhook callbacks. ### Responses **200** **200 OK** Upscale job created. Poll [GET /videos/`jobid`](/docs/api-dreamina-v1/get-dreamina-videos-jobid) for the result. ```json { "jobid": "j0302140630123456789V-u12345-CA:user@example.com-bot:dreamina", "type": "video-upscale", "status": "created", "model": "seedance-2.0-fast", "created": "2026-04-02T00:24:24.535Z", "request": { "jobid": "j0302140530123456789v-u12345-CA:user@example.com-bot:dreamina" }, "response": { "forecastCost": 30 }, "code": 200 } ``` **400** **400 Bad Request** Validation error. ```json { "error": "Source video job is created, must be completed" } ``` ```json { "error": "Source video already upscaled: j0302140630123456789V-u12345-CA:user@example.com-bot:dreamina" } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "Unauthorized" } ``` **404** **404 Not Found** Source video job not found. ```json { "error": "Source video job not found", "code": 404 } ``` ### Examples **Curl** ``` bash curl -X POST \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "jobid": "YOUR_COMPLETED_VIDEO_JOBID" }' \ "https://api.useapi.net/v1/dreamina/videos/upscale" ``` **JavaScript** ``` javascript const token = 'YOUR_API_TOKEN'; const response = await fetch('https://api.useapi.net/v1/dreamina/videos/upscale', { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ jobid: 'YOUR_COMPLETED_VIDEO_JOBID' }) }); const result = await response.json(); console.log('Upscale job:', result.jobid); // Poll for completion const poll = async (jobid) => { while (true) { const res = await fetch(`https://api.useapi.net/v1/dreamina/videos/${jobid}`, { headers: { 'Authorization': `Bearer ${token}` } }); const job = await res.json(); if (job.status === 'completed') { console.log('Upscaled:', job.response.width, 'x', job.response.height); console.log('Video URL:', job.response.videoUrl); return job; } if (job.status === 'failed') throw new Error(job.error); await new Promise(r => setTimeout(r, 10000)); } }; await poll(result.jobid); ``` **Python** ``` python import requests import time token = 'YOUR_API_TOKEN' response = requests.post( 'https://api.useapi.net/v1/dreamina/videos/upscale', headers={ 'Authorization': f'Bearer {token}', 'Content-Type': 'application/json' }, json={ 'jobid': 'YOUR_COMPLETED_VIDEO_JOBID' } ) result = response.json() print(f"Upscale job: {result['jobid']}") # Poll for completion jobid = result['jobid'] while True: job = requests.get( f'https://api.useapi.net/v1/dreamina/videos/{jobid}', headers={'Authorization': f'Bearer {token}'} ).json() if job['status'] == 'completed': r = job['response'] print(f"Upscaled: {r['width']}x{r['height']}") print(f"Video URL: {r['videoUrl']}") break if job['status'] == 'failed': raise Exception(job.get('error')) time.sleep(10) ``` ### Try It <script> async function apiExecutePostDreaminaVideosUpscale() { const tokenElement = document.getElementById('input-token'); const elementId = 'input'; const payload = {}; const inputs = document.querySelectorAll('.input-query-param'); inputs.forEach(input => { const id = input.id; const value = input.value?.trim(); if (id.startsWith('input-') && value !== '' && value !== undefined) { const key = id.replace('input-', ''); if (key === 'maxJobs') { payload[key] = parseInt(value); } else { payload[key] = value; } } }); const data = { method: 'POST', headers: { 'Authorization': `Bearer ${tokenElement.value}`, 'Content-Type': 'application/json' }, body: JSON.stringify(payload) }; await apiExecute('https://api.useapi.net/v1/dreamina/videos/upscale', elementId, data); } </script> <form id="input" class="input-form" onsubmit="return false;"> <div class="input-field"> <div class="input-field-row"> <label for="input-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="input-token" type="text" class="input-element" required aria-required="true"> </label> <label for="input-jobid"><span>jobid (required, from POST /videos)</span> <input id="input-jobid" type="text" class="input-element input-query-param" required aria-required="true"> </label> <label for="input-replyUrl"><span>replyUrl (webhook URL)</span> <input id="input-replyUrl" type="text" class="input-element input-query-param" placeholder="https://your-domain.com/webhook"> </label> <label for="input-replyRef"><span>replyRef (custom reference)</span> <input id="input-replyRef" type="text" class="input-element input-query-param" placeholder="my-custom-id-123"> </label> </div> <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecutePostDreaminaVideosUpscale()">Go</button> </div> </form> <div id="input-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-dreamina-v1/post-dreamina-videos === Document URL: https://useapi.net/docs/api-dreamina-v1/post-dreamina-videos --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos description: "Submit a Dreamina video prompt via POST videos in the useapi.net Dreamina API v1 — Seedance models; text-to-video, image-guided, multi-frame, and Omni Reference modes." parent: Dreamina API nav_order: 600 --- ## Generate Videos February 23, 2026 (November 18, 2026) --- Generate videos using Dreamina AI models from text prompts with optional image frames. All video generation is asynchronous — this endpoint returns immediately with a job ID. Poll [GET /videos/`jobid`](/docs/api-dreamina-v1/get-dreamina-videos-jobid) for completion, or use `replyUrl` webhook for automatic callbacks. Video generation typically completes within 60-180 seconds depending on the model and duration. The `long_video` and `edit` modes on `seedance-2.5` take considerably longer — a 21-second edit measured 13 minutes and a 35-second long video 17, so use `replyUrl` rather than polling for those. ### Input Modes The input mode is automatically determined from the provided parameters: | Mode | API Value | Trigger | Description | |------|-----------|---------|-------------| | Prompt | `prompt` | No image refs | Text-to-video generation | | First Frame | `first_frame` | `firstFrameRef` provided | Video starts from uploaded image | | First/Last Frame | `end_frame` | `firstFrameRef` + `endFrameRef` | Video transitions between two images | | Multi-Frame | `multi_frame` | `frame_N_imageRef` params | 2-10 keyframe images with per-frame prompts | | Omni Reference | `unified_edit` | `omni_N_imageRef`/`omni_N_videoRef`/`omni_N_audioRef` in prompt | Interleaved text, image, video, and audio references (Seedance 2.5, 2.5 Flash, 2.5 Draft, 2.0, 2.0 Fast, 2.0 Mini, Wan 3.0; HappyHorse 1.1 images only) | | Long Video | `long_video` | `duration` above 30 | 31-180 second generation (`seedance-2.5` only) | | Edit | `edit` | `editVideoRef` provided | Re-cut an existing video (`seedance-2.5` and `seedance-2.5-flash`) | #### Aspect ratio auto-detection In `first_frame` and `end_frame` modes the aspect ratio is taken from the uploaded image, and the closest standard ratio (21:9, 16:9, 4:3, 1:1, 3:4, 9:16) is used. The `ratio` parameter cannot be supplied alongside image refs. When using `firstFrameRef` together with `endFrameRef`, both images must share the same aspect ratio. ### Model Capabilities | Model | Region | Durations | Resolution | Input Modes | |-------|--------|-----------|------------|-------------| | `seedance-2.5` | US, CA | 4-30s, or 31-180s in long video mode | 480p (default), 720p, 1080p, 4k (CA only) | Prompt, First/Last Frame, Omni Reference, Long Video, Edit | | `seedance-2.5-flash` | CA | 4-30s | 480p (default), 720p | Prompt, First/Last Frame, Omni Reference, Edit | | `seedance-2.5-draft` | US, CA | 4-30s | 480p | Prompt, First/Last Frame, Omni Reference | | `seedance-2.0` | US, CA | 4-15s | 720p, 1080p, 4k | Prompt, First/Last Frame, Omni Reference | | `seedance-2.0-fast` | US, CA | 4-15s | 720p, 1080p, 2k, 4k (above 720p, upscaled from 720p) | Prompt, First/Last Frame, Omni Reference | | `seedance-2.0-mini` | US, CA | 4-15s | 720p, 1080p, 2k, 4k (above 720p, upscaled from 720p) | Prompt, First/Last Frame, Omni Reference | | `seedance-1.5-pro` | US | 5, 10, 12s | 720p | Prompt, First/Last Frame | | `seedance-1.0-pro` | CA | 5, 10s | 1080p | Prompt, First Frame | | `seedance-1.0-mini` | US | 5, 10s | 720p | Prompt, First Frame, Multi-Frame | | `seedance-1.0-fast` | CA | 5, 10s | 720p, 1080p | Prompt, First Frame, Multi-Frame | | `happyhorse-1.1` | CA | 4-15s | 720p (default), 1080p | Prompt, First Frame, Omni Reference (images only) | | `wan-3.0` | CA | 4-15s | 720p (default), 1080p | Prompt, First/Last Frame, Omni Reference | Both regions run the same resolutions on the Seedance 2.0 models. `seedance-2.5` runs 1080p on CA since August 14, 2026 and on US since October 23, 2026, and 4k on CA only since November 12, 2026. `seedance-2.0-fast` and `seedance-2.0-mini` render at 720p, and Dreamina upscales 1080p, 2k and 4k from that 720p video (as of October 23, 2026). 480p arrived with `seedance-2.5` on August 7, 2026. `seedance-1.5-pro` is US only since November 9, 2026, when Dreamina dropped it from Canadian accounts. See [Setup Dreamina](/docs/start-here/setup-dreamina) for per-region setup and pricing. `happyhorse-1.1` (by Alibaba) and `wan-3.0` (by Tongyi Lab) run on CA accounts as of November 12, 2026. Both make 4 to 15-second videos with sound at 720p or 1080p. HappyHorse takes up to 9 reference images, and Wan up to 10 images, 5 videos and 5 audio clips. #### What is new in `seedance-2.5` * Up to **30 seconds** in one call, twice the 15-second ceiling of the 2.0 family. * Up to **50 omni references** — 30 images, 10 videos, 10 audio clips — against the 2.0 family's 12. * Defaults to `480p`, which costs roughly half of `720p`. * `1080p`, added on CA August 14, 2026 and on US October 23, 2026. * `4k` on CA accounts since November 12, 2026, including long video mode. * **Long video** — pass a `duration` of 31 to 180 and the generation switches to long video mode, six times the ordinary 30-second ceiling. Works from a plain prompt or with omni references. Priced on its own, higher, per-second rate. * **Edit** — pass `editVideoRef` and Seedance re-cuts an existing 4-30 second video instead of generating a new one, keeping its motion and framing while applying whatever the prompt asks for. Combine it with `omni_N_imageRef` references to bring new elements in. * Attaching an omni video reference makes a generation cheaper per second at `480p` on both regions and at `4k` on CA (as of November 12, 2026). `720p` has no lower rate on either region. Reference videos may be up to 30.2 seconds each and are billed on top of the output duration. #### `seedance-2.5-flash` and `seedance-2.5-draft` Two lower-cost Seedance 2.5 models, both added November 12, 2026: * `seedance-2.5-flash` runs on CA accounts. Dreamina describes it as "Great quality, faster, fewer credits": 480p or 720p, 4-30 seconds, up to 20 omni references (10 images, 5 videos, 5 audio clips), and Edit. On CA it costs 11 credits a second at 480p and 24 at 720p, with or without a reference video, against 22 and 38 for `seedance-2.5` without one. No long video mode. * `seedance-2.5-draft` runs on US and CA accounts and makes a 480p draft, so you can test a prompt before paying for a full `seedance-2.5` video. It takes the same 50 omni references as `seedance-2.5`, at 13 credits a second on US and 17 on CA. Send a finished draft to [POST /videos/full-quality](/docs/api-dreamina-v1/post-dreamina-videos-full-quality) to turn it into a 1080p video, or 4K on CA, built from the draft you approved. Prices are Dreamina's own and change often (as of November 12, 2026). #### Content on `seedance-2.5` Markedly more permissive than the 2.0 family: * **Real human faces are accepted.** A photographic portrait works directly as `omni_N_imageRef` or `firstFrameRef`, and the identity carries through the clip. The 2.0 family rejects them, so the face-grid workaround in the [Seedance 2.0 real-faces tutorial](/blog/260415) is not needed here. * **Cinematic violence renders.** Stylised action — fight scenes, impacts, blood spray — is generated rather than refused. * **Recognisable third-party content is refused**, as `fail_code 2053`. It is judged against the finished video two to four minutes into generation, not against your prompt text — so a prompt naming no person and no property can still fail if it *describes* one, such as a costumed superhero, a trademarked landmark, or a character written as an unmistakable celebrity. Failed generations are not charged. > **https://api.useapi.net/v1/dreamina/videos** ### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Request Body ```json { "prompt": "A serene mountain landscape at sunset with camera slowly panning right", "model": "seedance-2.0", "ratio": "16:9", "duration": 5 } ``` - `account` is optional. Specific account to use. Auto-inferred from image refs if provided. If omitted, a random account with free capacity is picked among those whose region offers `model` at the requested `resolution`. - `prompt` is **required** for `prompt` mode. Optional for `first_frame` and `end_frame`. Cannot be used with `multi_frame` mode (use `frame_N_prompt` instead). Maximum 20000 characters on `wan-3.0`, 15000 on `seedance-2.5`, `seedance-2.5-flash` and `seedance-2.5-draft`, 2500 on `happyhorse-1.1`, 5000 on every other model. - `model` is optional, the AI model to use (default: `seedance-2.0`). Available models depend on account region — see Model Capabilities table. - `ratio` is optional, video aspect ratio (default: `16:9`). One of `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, plus `4:5`, `5:4` and `9:21` on `happyhorse-1.1`. `wan-3.0` takes `16:9`, `4:3`, `1:1`, `3:4` and `9:16`. Cannot be specified when image refs are provided (image aspect ratio is used). - `duration` is optional, video duration in seconds (default: `5`). Valid values depend on model — see Model Capabilities table. On `seedance-2.5` any value from 31 to 180 switches the request to long video mode, which is priced separately. Cannot be used with `editVideoRef`, where the output always matches the source video. - `resolution` is optional, one of `480p`, `720p`, `1080p`, `2k` or `4k`. Each model accepts only some of these — see the Resolution column in Model Capabilities above. Defaults to `720p`, except `seedance-2.5`, `seedance-2.5-flash` and `seedance-2.5-draft`, which default to `480p`. - `unlimited` is optional, `true` makes the video in Dreamina's Unlimited mode, at no credits. Models, resolutions and answers: [Unlimited](#unlimited) below. - `firstFrameRef` is optional, `imageRef` from [POST /assets/`account`](/docs/api-dreamina-v1/post-dreamina-assets-account) for the starting frame. Triggers `first_frame` mode. - `endFrameRef` is optional, `imageRef` for the ending frame. Triggers `end_frame` mode. Requires `firstFrameRef`. - `editVideoRef` is optional, `videoRef` from [POST /assets/`account`](/docs/api-dreamina-v1/post-dreamina-assets-account) for the video to re-cut. Triggers `edit` mode, `seedance-2.5` and `seedance-2.5-flash` only. The source must be 4-30 seconds. The output inherits the source's length and aspect ratio, so `duration` and `ratio` cannot be supplied alongside it. May be combined with `omni_N_imageRef`/`omni_N_videoRef` references, mentioned in the prompt as usual. - `frame_N_imageRef` is optional (N=1-10), `imageRef` for keyframe N. Triggers `multi_frame` mode when at least 2 frames are provided. - `frame_N_prompt` is optional, per-frame prompt for multi_frame mode. Maximum 5000 characters. - `frame_N_duration` is optional, per-frame duration in seconds for multi_frame mode (1-6, default: `5`). - `replyUrl` is optional, webhook URL for job status callbacks. Receives POST requests with the job record on submission and on completion/failure. Callback body has the same JSON shape as [GET /videos/`jobid`](/docs/api-dreamina-v1/get-dreamina-videos-jobid) response. - `replyRef` is optional, custom reference string passed back in webhook callbacks. - `omni_N_imageRef`, `omni_N_videoRef` and `omni_N_audioRef` are optional `assetRef` values from [POST /assets/`account`](/docs/api-dreamina-v1/post-dreamina-assets-account), and trigger Omni Reference mode. Mention each one in the prompt as `@imageN`, `@videoN` or `@audioN` — for example `"Make @image1 dance like @video1 while @audio1 plays"`. Supported by `seedance-2.5`, `seedance-2.5-flash`, `seedance-2.5-draft`, `seedance-2.0`, `seedance-2.0-fast`, `seedance-2.0-mini`, `wan-3.0`, and `happyhorse-1.1` (images only). Per-model counts are in the reference-limit table below. - `maxJobs` is optional, override max concurrent jobs for this request (1-50). **Omni Reference constraints:** - Only supported by `seedance-2.5`, `seedance-2.5-flash`, `seedance-2.5-draft`, `seedance-2.0`, `seedance-2.0-fast`, `seedance-2.0-mini`, `wan-3.0`, and `happyhorse-1.1` (images only) - Prompt must contain `@imageN`, `@videoN`, and/or `@audioN` placeholders matching the provided `omni_N_*Ref` params - A reference that is uploaded but never mentioned in the prompt is ignored, and is not billed - The Seedance 2.0 models and `wan-3.0` need at least one image or video reference. Audio references alone are refused with `400`. The Seedance 2.5 models accept audio alone - Cannot be combined with `firstFrameRef`, `endFrameRef`, or `frame_N_imageRef` Reference limits differ by model: | Limit | `seedance-2.5`, `seedance-2.5-draft` | `seedance-2.5-flash` | Seedance 2.0 family | `wan-3.0` | `happyhorse-1.1` | |---|---|---|---|---|---| | Image references | 30 | 10 | 9 | 10 | 9 | | Video references | 10 | 5 | 3 | 5 | — | | Audio references | 10 | 5 | 3 | 5 | — | | Total materials combined | 50 | 20 | 12 | 20 | 9 | | Total video duration across all refs | 30.2s | 30.2s | 15.4s | 15s | — | | Total audio duration across all refs | 30.2s | 30.2s | 15s | 15s | — | | Individual video | 1.8-30.2s, 300-6000px | 1.8-30.2s, 300-6000px | 2-15.4s, 200-2160px | 1-15s, 240-4096px | — | | Individual audio | 1.8-30.2s | 1.8-30.2s | 2-15s | 1-15s | — | Uploads via [POST /assets/`account`](/docs/api-dreamina-v1/post-dreamina-assets-account) are accepted up to the loosest of these limits (video 1.8-30.2s, audio 1.8-30.2s, video max 50 MB, audio max 15 MB), so one asset can be reused across models. The per-model limits above are checked when you submit the generation. **Multi-frame constraints:** - Minimum 2 frames, maximum 10 frames - No gaps allowed (frame_1 through frame_N must be contiguous) - All frame images must have the same aspect ratio - Top-level `prompt` cannot be used (use `frame_N_prompt` instead) - `firstFrameRef`/`endFrameRef` cannot be combined with multi_frame - Total duration of non-last frames must equal a valid model duration ### Unlimited With `unlimited` set to `true` the job uses no credits. Unlimited comes with a Dreamina plan bought or upgraded during Dreamina's November 2026 offers. Dreamina decides which of these models and resolutions an account gets and for how many days, and can end it early. | Model | Unlimited at | Per request | Accounts | |---|---|---|---| | `seedance-2.5` | 480p, 720p | 1 video, up to 30 s | US, CA | | `seedance-2.5-flash` | 480p, 720p | 1 video, up to 30 s | CA | | `seedance-2.5-draft` | 480p | 1 video, up to 30 s | US, CA | | `seedance-2.0` | 720p | 1 video, up to 15 s | US, CA | | `seedance-2.0-fast` | 720p | 1 video, up to 15 s | US, CA | | `seedance-2.0-mini` | 720p | 1 video, up to 15 s | US, CA | | `seedream-5.5` | 1.5K, 2K | up to 4 images | CA | | `gpt-image-2.5-flare`<br>`gpt-image-2.5-sunburst` | 1K, 2K | 1 image | US, CA | | `nano-banana-pro` | 1K, 2K | up to 4 images | US, CA | | `nano-banana-2.1` | 1K, 2K | up to 4 images | CA | - The plan decides which of these resolutions are Unlimited. 4K never is. - Video references and edits are included. The Seedance 2.5 models stop at 30 seconds, so long video is not. - An image request without `count` asks for the most the model allows, 4 images (1 on GPT Image 2.5). - Dreamina runs one Unlimited job at a time per account, videos and images together. | Answer | When | |---|---| | `400` | A model not in the table. On POST /videos also another resolution or a long video. | | `412` | The account has no Unlimited for this model and resolution, or it has ended. Send the request without `unlimited` to use credits. | | `429` | The account is already running an Unlimited job. Retry after it finishes. | ### Responses **200** **200 OK** Job created successfully. Video is generating in the background. ```json { "jobid": "j0223140530123456789v-u12345-CA:user@example.com-bot:dreamina", "type": "video", "status": "created", "model": "seedance-2.0", "created": "2026-02-23T14:05:30.123Z", "request": { "prompt": "A serene mountain landscape at sunset with camera slowly panning right", "model": "seedance-2.0", "ratio": "16:9", "duration": 5, "inputMode": "prompt" }, "response": { "forecastCost": 125 }, "code": 200 } ``` Poll [GET /videos/`jobid`](/docs/api-dreamina-v1/get-dreamina-videos-jobid) for completion status, or use `replyUrl` for webhook callbacks. **400** **400 Bad Request** Validation error. ```json { "error": "Parameter model (invalid-model) valid values: seedance-2.5, seedance-2.5-flash, seedance-2.5-draft, seedance-2.0, seedance-2.0-fast, seedance-2.0-mini, seedance-1.5-pro, seedance-1.0-mini, seedance-1.0-pro, seedance-1.0-fast, happyhorse-1.1, wan-3.0" } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "Unauthorized" } ``` **402** **402 Payment Required** Your useapi.net subscription is missing or has expired. A Dreamina account that is out of credits gets `412` instead. ```json { "error": "useapi.net ⁝ Monthly subscription 261008 expired, please renew your subscription before submitting new requests.", "code": 402 } ``` **403** **403 Forbidden** One of two reasons, and `ret` says which. `ret` `5006`: the account has no Dreamina subscription that includes this model. Dreamina runs it only on a paid plan, and credits bought separately don't count. Subscribe the account, or use one that has a plan. ```json { "error": "Account US:user@example.com needs a paid Dreamina subscription for seedance-2.5: Dreamina refused the job because the account has no plan that includes it (credits bought separately don't count). Subscribe at https://dreamina.capcut.com/pricing/dreamina-price, or use an account that has one. Dreamina: credit miss role", "ret": "5006", "errmsg": "credit miss role", "account": "US:user@example.com", "model": "seedance-2.5" } ``` `ret` `4010`: Dreamina asks for its one-time "Before you continue" confirmation on this account (currently Seedance 2.x). We accept it automatically and resubmit, so you only get this response when that did not clear it. Retry once. If it persists, sign in at [dreamina.capcut.com](https://dreamina.capcut.com) with the account, start a generation with the same model, click Agree, then retry. ```json { "error": "Dreamina asks for a one-time confirmation on account US:user@example.com and our automatic confirmation did not clear it. Retry once. If it persists, sign in at https://dreamina.capcut.com with this account, start a seedance-2.0 generation, click Agree on \"Before you continue\", then retry. Dreamina: Couldn't generate. Refresh and agree to the confirmation before you continue.", "ret": "4010", "errmsg": "Couldn't generate. Refresh and agree to the confirmation before you continue.", "failCode": "4010", "account": "US:user@example.com", "model": "seedance-2.0" } ``` **412** **412 Precondition Failed** The Dreamina account does not have enough credits for this job, or no benefit that covers this model (`ret` `1006`), or `unlimited` was set and the account has no Unlimited for this model and resolution, or it has ended (`ret` `1311`). Top up the account, send the request without `unlimited`, or use another account. ```json { "error": "Submit failed: Not enough credits left or no relevant benefits", "code": 412, "ret": "1006", "errmsg": "Not enough credits left or no relevant benefits", "failCode": "1006", "account": "US:user@example.com", "model": "seedance-2.0" } ``` **429** **429 Too Many Requests** All accounts at maximum capacity. Wait for current jobs to complete or increase `maxJobs`. When you set `account`, or only one of your accounts can take the job, the message names that account instead: `Account <account> is busy executing <N> tasks`. With `unlimited`, the account may also be running another Unlimited job (`ret` `1312`, Dreamina runs one at a time per account): retry after the `Retry-After` seconds. ```json { "error": "All configured accounts are running at maximum capacity", "code": 429 } ``` **503** **503 Service Unavailable** Dreamina signed the account out and signing it in again failed for a temporary reason. The response carries a `Retry-After: 30` header. Retry in about 30 seconds. ```json { "error": "Dreamina signed this account out and signing it in again failed temporarily. Retry in about 30 seconds.", "code": 503, "retryAfterSec": 30 } ``` **596** **596 Session Error** The account's session expired or Dreamina locked it, or the account is in its sign-out pause. Check [GET /accounts](/docs/api-dreamina-v1/get-dreamina-accounts): an account with `signedOutPauseUntil` comes back by itself after the pause, any other account needs to be re-added using [POST /accounts](/docs/api-dreamina-v1/post-dreamina-accounts) with correct credentials. ```json { "error": "Dreamina account session expired or locked. Please re-add account via POST /v1/dreamina/accounts", "code": 596 } ``` When Dreamina signs an account out again right after a fresh sign-in, the account is paused for 30 minutes. While the pause runs, [GET /accounts](/docs/api-dreamina-v1/get-dreamina-accounts) shows `signedOutPauseUntil` (an ISO 8601 time) on that account, requests that name it answer `596`, and automatic account selection uses your other accounts. When every account is paused, requests answer `596`. After the pause the account is used again. If Dreamina signs it out right after a fresh sign-in again, after the pause and within 24 hours, the account is marked with an `error` and answers `596` until you re-add it with [POST /accounts](/docs/api-dreamina-v1/post-dreamina-accounts). Re-adding an account also ends its pause. A sign-in that fails for a temporary reason, not because Dreamina refused the account, answers `503` with a `Retry-After: 30` header. The account is fine: retry in about 30 seconds. ### Model The new job's `jobid` with status `created`: poll it with [GET /videos/`jobid`](/docs/api-dreamina-v1/get-dreamina-videos-jobid) until it completes or fails. <details markdown="block" class="model-details"> <summary>The new video job, field by field</summary> ```typescript { jobid: string // Unique job identifier type: 'video' // Job type status: 'created' // Initial status model: string // Model used created: string // ISO 8601 timestamp request: { prompt?: string model: string ratio?: string // "16:9", "9:16", etc. duration?: number // Seconds inputMode: string // "prompt" | "first_frame" | "end_frame" | "multi_frame" | "unified_edit" | "long_video" | "edit" resolution?: string // "480p", "720p", "1080p", "2k" or "4k" unlimited?: boolean // true when sent with unlimited firstFrameRef?: string // assetRef (image) for first frame endFrameRef?: string // assetRef (image) for end frame frame_1_imageRef?: string // Keyframe refs (multi_frame mode) frame_1_prompt?: string frame_1_duration?: number frame_2_imageRef?: string frame_2_prompt?: string frame_2_duration?: number omni_1_imageRef?: string // Omni image refs (use @image1 in prompt) omni_2_imageRef?: string omni_1_videoRef?: string // Omni video refs (use @video1 in prompt) omni_1_audioRef?: string // Omni audio refs (use @audio1 in prompt) replyUrl?: string // Webhook URL replyRef?: string // Custom reference } response: { forecastCost: number // Estimated generation time in seconds, NOT a price } code: number // HTTP status code error?: string // Error message } ``` </details> ### Examples **Curl** ``` bash # Text-to-video curl -X POST \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A serene mountain landscape at sunset", "model": "seedance-2.0", "ratio": "16:9", "duration": 5 }' \ "https://api.useapi.net/v1/dreamina/videos" # Image-to-video (first frame — ratio auto-detected from image) curl -X POST \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Camera slowly pans across the scene", "model": "seedance-2.0", "firstFrameRef": "CA:user@example.com-image:w685:h900:s86866-uri:tos-useast5-i-wopfjsm1ax-tx/abc123", "duration": 5 }' \ "https://api.useapi.net/v1/dreamina/videos" # Omni Reference (image + audio) curl -X POST \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "@image1 slowly moving forward while @audio1 plays in background", "model": "seedance-2.0", "ratio": "16:9", "duration": 4, "omni_1_imageRef": "CA:user@example.com-image:w2560:h1440:s580914-uri:tos-alisg-i-wopfjsm1ax-sg/abc123", "omni_1_audioRef": "CA:user@example.com-audio:d14040-vid:v10762g50003d77l5uvog65nl4esjs2g" }' \ "https://api.useapi.net/v1/dreamina/videos" ``` **JavaScript** ``` javascript const token = 'YOUR_API_TOKEN'; const apiUrl = 'https://api.useapi.net/v1/dreamina/videos'; // Text-to-video const response = await fetch(apiUrl, { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ prompt: 'A serene mountain landscape at sunset', model: 'seedance-2.0', ratio: '16:9', duration: 5 }) }); const result = await response.json(); console.log('Job created:', result.jobid); // Poll for completion const poll = async (jobid) => { while (true) { const res = await fetch(`https://api.useapi.net/v1/dreamina/videos/${jobid}`, { headers: { 'Authorization': `Bearer ${token}` } }); const job = await res.json(); console.log('Status:', job.status); if (job.status === 'completed') { console.log('Video URL:', job.response.videoUrl); return job; } if (job.status === 'failed') throw new Error(job.error); await new Promise(r => setTimeout(r, 10000)); } }; const completed = await poll(result.jobid); ``` **Python** ``` python import requests import time token = 'YOUR_API_TOKEN' api_url = 'https://api.useapi.net/v1/dreamina/videos' headers = { 'Authorization': f'Bearer {token}', 'Content-Type': 'application/json' } # Text-to-video data = { 'prompt': 'A serene mountain landscape at sunset', 'model': 'seedance-2.0', 'ratio': '16:9', 'duration': 5 } response = requests.post(api_url, headers=headers, json=data) result = response.json() print(f"Job created: {result['jobid']}") # Poll for completion jobid = result['jobid'] while True: job = requests.get( f'https://api.useapi.net/v1/dreamina/videos/{jobid}', headers={'Authorization': f'Bearer {token}'} ).json() print(f"Status: {job['status']}") if job['status'] == 'completed': print(f"Video URL: {job['response']['videoUrl']}") break if job['status'] == 'failed': raise Exception(job.get('error')) time.sleep(10) ``` ### Try It <script> async function apiExecutePostDreaminaVideos() { const tokenElement = document.getElementById('input-token'); const elementId = 'input'; const payload = {}; const inputs = document.querySelectorAll('.input-query-param'); inputs.forEach(input => { const id = input.id; const value = input.value?.trim(); if (id.startsWith('input-') && value !== '' && value !== undefined) { const key = id.replace('input-', ''); if (key === 'duration' || key === 'maxJobs') { payload[key] = parseInt(value); } else if (key === 'unlimited') { payload[key] = value === 'true'; } else { payload[key] = value; } } }); const data = { method: 'POST', headers: { 'Authorization': `Bearer ${tokenElement.value}`, 'Content-Type': 'application/json' }, body: JSON.stringify(payload) }; await apiExecute('https://api.useapi.net/v1/dreamina/videos', elementId, data); } </script> <form id="input" class="input-form" onsubmit="return false;"> <div class="input-field"> <div class="input-field-row"> <label for="input-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="input-token" type="text" class="input-element" required aria-required="true"> </label> <label for="input-account"><span>account (optional)</span> <input id="input-account" type="text" class="input-element input-query-param" placeholder="CA:user@example.com"> </label> <label for="input-prompt"><span>prompt (required for T2V)</span> <input id="input-prompt" type="text" class="input-element input-query-param" placeholder="A serene mountain landscape"> </label> <label for="input-model"><span>model</span> <select id="input-model" class="input-element input-query-param"> <option value="">default</option> <option value="seedance-2.5">seedance-2.5</option> <option value="seedance-2.5-flash">seedance-2.5-flash (CA only)</option> <option value="seedance-2.5-draft">seedance-2.5-draft</option> <option value="seedance-2.0">seedance-2.0</option> <option value="seedance-2.0-fast">seedance-2.0-fast</option> <option value="seedance-2.0-mini">seedance-2.0-mini</option> <option value="seedance-1.5-pro">seedance-1.5-pro</option> <option value="seedance-1.0-pro">seedance-1.0-pro (CA only)</option> <option value="seedance-1.0-mini">seedance-1.0-mini (US only)</option> <option value="seedance-1.0-fast">seedance-1.0-fast (CA only)</option> <option value="happyhorse-1.1">happyhorse-1.1 (CA only)</option> <option value="wan-3.0">wan-3.0 (CA only)</option> </select> </label> <label for="input-ratio"><span>ratio</span> <select id="input-ratio" class="input-element input-query-param"> <option value="">auto (from image or 16:9)</option> <option value="21:9">21:9</option> <option value="16:9">16:9</option> <option value="4:3">4:3</option> <option value="1:1">1:1</option> <option value="3:4">3:4</option> <option value="9:16">9:16</option> <option value="4:5">4:5 (happyhorse-1.1)</option> <option value="5:4">5:4 (happyhorse-1.1)</option> <option value="9:21">9:21 (happyhorse-1.1)</option> </select> </label> <label for="input-duration"><span>duration (seconds, up to 15 — 30 on the seedance-2.5 models, 31-180 long video on seedance-2.5)</span> <input id="input-duration" type="number" class="input-element input-query-param" min="4" max="180" placeholder="5"> </label> <label for="input-resolution"><span>resolution</span> <select id="input-resolution" class="input-element input-query-param"> <option value="">model default (480p on the seedance-2.5 models, else 720p)</option> <option value="480p">480p (seedance-2.5 models only)</option> <option value="720p">720p</option> <option value="1080p">1080p</option> <option value="2k">2k (seedance-2.0-fast, seedance-2.0-mini)</option> <option value="4k">4k (seedance-2.5 on CA, seedance-2.0, seedance-2.0-fast, seedance-2.0-mini)</option> </select> </label> <label for="input-unlimited"><span>unlimited (Seedance 2.5 models at 480p/720p, Seedance 2.0 models at 720p)</span> <select id="input-unlimited" class="input-element input-query-param"> <option value="">off</option> <option value="true">true</option> </select> </label> <label for="input-firstFrameRef"><span>firstFrameRef (optional, from <a href="/docs/api-dreamina-v1/post-dreamina-assets-account">POST /assets/account</a>)</span> <input id="input-firstFrameRef" type="text" class="input-element input-query-param" placeholder="CA:user@example.com-image:w685:h900:s86866-uri:..."> </label> <label for="input-endFrameRef"><span>endFrameRef (optional, requires firstFrameRef)</span> <input id="input-endFrameRef" type="text" class="input-element input-query-param" placeholder="CA:user@example.com-image:w685:h900:s86866-uri:..."> </label> <label for="input-editVideoRef"><span>editVideoRef (optional, edit mode, seedance-2.5 and seedance-2.5-flash)</span> <input id="input-editVideoRef" type="text" class="input-element input-query-param" placeholder="CA:user@example.com-video:w720:h1280:s7279723:d21300-vid:..."> </label> <label for="input-frame_1_imageRef"><span>frame_1_imageRef (multi-frame, seedance-1.0-mini)</span> <input id="input-frame_1_imageRef" type="text" class="input-element input-query-param" placeholder="CA:user@example.com-image:w685:h900:s86866-uri:..."> </label> <label for="input-frame_1_prompt"><span>frame_1_prompt</span> <input id="input-frame_1_prompt" type="text" class="input-element input-query-param" placeholder="A person standing in a garden"> </label> <label for="input-frame_1_duration"><span>frame_1_duration (1-6, default: 5)</span> <input id="input-frame_1_duration" type="number" class="input-element input-query-param" min="1" max="6" placeholder="5"> </label> <label for="input-frame_2_imageRef"><span>frame_2_imageRef</span> <input id="input-frame_2_imageRef" type="text" class="input-element input-query-param" placeholder="CA:user@example.com-image:w685:h900:s86866-uri:..."> </label> <label for="input-frame_2_prompt"><span>frame_2_prompt</span> <input id="input-frame_2_prompt" type="text" class="input-element input-query-param" placeholder="The person walks away slowly"> </label> <label for="input-frame_2_duration"><span>frame_2_duration (1-6, default: 5)</span> <input id="input-frame_2_duration" type="number" class="input-element input-query-param" min="1" max="6" placeholder="5"> </label> <label for="input-frame_3_imageRef"><span>frame_3_imageRef</span> <input id="input-frame_3_imageRef" type="text" class="input-element input-query-param" placeholder="CA:user@example.com-image:w685:h900:s86866-uri:..."> </label> <label for="input-frame_3_prompt"><span>frame_3_prompt</span> <input id="input-frame_3_prompt" type="text" class="input-element input-query-param" placeholder="A wide shot of the garden at sunset"> </label> <label for="input-frame_3_duration"><span>frame_3_duration (1-6, default: 5)</span> <input id="input-frame_3_duration" type="number" class="input-element input-query-param" min="1" max="6" placeholder="5"> </label> <label for="input-omni_1_imageRef"><span>omni_1_imageRef (Omni, use @image1 in prompt)</span> <input id="input-omni_1_imageRef" type="text" class="input-element input-query-param" placeholder="CA:user@example.com-image:w685:h900:s86866-uri:..."> </label> <label for="input-omni_2_imageRef"><span>omni_2_imageRef (use @image2 in prompt)</span> <input id="input-omni_2_imageRef" type="text" class="input-element input-query-param" placeholder="CA:user@example.com-image:w685:h900:s86866-uri:..."> </label> <label for="input-omni_1_videoRef"><span>omni_1_videoRef (use @video1 in prompt)</span> <input id="input-omni_1_videoRef" type="text" class="input-element input-query-param" placeholder="CA:user@example.com-video:w720:h1280:d8000-vid:..."> </label> <label for="input-omni_1_audioRef"><span>omni_1_audioRef (use @audio1 in prompt)</span> <input id="input-omni_1_audioRef" type="text" class="input-element input-query-param" placeholder="CA:user@example.com-audio:d14040-vid:..."> </label> <label for="input-replyUrl"><span>replyUrl (webhook URL)</span> <input id="input-replyUrl" type="text" class="input-element input-query-param" placeholder="https://your-domain.com/webhook"> </label> <label for="input-replyRef"><span>replyRef (custom reference)</span> <input id="input-replyRef" type="text" class="input-element input-query-param" placeholder="my-custom-id-123"> </label> </div> <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecutePostDreaminaVideos()">Go</button> </div> </form> <div id="input-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/start-here/setup-faceswap === Document URL: https://useapi.net/docs/start-here/setup-faceswap --- layout: default title: Setup InsightFaceSwap description: "How to set up InsightFaceSwap for the useapi.net API — connect your account and start generating via the API." parent: Start Here nav_order: 270 --- # <img style="height:1.8em;vertical-align: middle;" src="/assets/images/picsi.png" alt=""> Setup InsightFaceSwap ## Table of contents Approximately 3 minutes to complete setup steps. --- > This is the setup guide for [InsightFaceSwap API](/docs/api-faceswap-v1). A [Discord](https://discord.com) account and a [useapi.net subscription](/docs/subscription) are required for the API to work. ## Create Discord account You need a [Discord](https://discord.com) account to interact with [InsightFaceSwap Discord bot](https://discord.gg/Ym3X8U59ZN). Create a [new account](https://discord.com/register) if you don't have one already. Please note even if you have an existing Discord account we are **strongly** recommending creating a separate Discord account specifically designated to be used with useapi.net API. ## Create Discord server Please log in to your Discord account and create a new Discord server following [official instructions](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server-). ## Create `#api` text channel on your Discord server Once you created the Discord server you need to create a designated for API-related work text channel. You can refer to [official instructions](https://support.discord.com/hc/en-us/articles/4412085582359-Text-Channels-Text-Chat-In-Voice-Channels) to learn about Discord channels and how to manage them on your server. We suggest naming the text channel `#api` for clarity and also making that channel private. ## Join Picsi.Ai - Powered by InsightFace Discord Server Follow Picsi.Ai [instructions](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md) and join official [Picsi.Ai - Powered by InsightFace Discord Server](https://discord.gg/Ym3X8U59ZN). ## Add InsightFaceSwap bot to your Discord server Please follow [official instructions](https://discord.com/channels/1095014106576212101/1128550062683865178/1189604165006135379) to add InsightFaceSwap bot to your Discord server created earlier. ## Example of Discord server with private `#api` text channel and InsightFace bot Below you can see we created `useapi` Discord server with private `#api` text channel: ![](/assets/images/discord_faceswap_server_setup_example.png) InsightFace bot invited to the server and has access to private `#api` text channel ![](/assets/images/discord_faceswap_channel_setup_example.png) ## Test InsightFace bot Navigate to the created above `#api` text channel and execute few InsightFaceSwap bot command(s) to make sure it works. ## Make a note of your server id and channel id values Your Discord URL looks like `https://discord.com/channels/<server_id>/<chanel_id>` In the screenshot above URL is `https://discord.com/channels/1122226477161144546/1122277481822456166` where `1122226477161144546` is your Discord <u>server id</u> and `1122277481822456166` is your private `#api` <u>channel id</u>. Save both server id and channel id values, you will need those numbers for API. ## Obtain Discord token There are many tutorials describing how to obtain Discord tokens. Please refer to the following links bellow for additional guidance: - [How to Find Your Discord Token](https://discordhelp.net/discord-token) - [How To Get Your Discord Token](https://pcstrike.com/how-to-get-discord-token/) - [How to get Discord Token](https://linuxhint.com/get-discord-token/) Keep in mind that anyone with a Discord token can have **full access** to your Discord account so please keep it **safe** and **secure**. To reset your Discord token simply change your Discord password. ## Verify Discord access <script> async function verifyServer() { const discord = document.getElementById(`server-discord`)?.value; const server = document.getElementById(`server-server`)?.value; const data = { method: 'GET', headers: { 'Authorization': `${discord}`, 'Content-Type': 'application/json' } }; const url=`https://discord.com/api/v10/guilds/${server}`; await apiExecute(url, 'server', data); } async function verifyChannel() { const discord = document.getElementById(`channel-discord`)?.value; const channel = document.getElementById(`channel-channel`)?.value; const data = { method: 'GET', headers: { 'Authorization': `${discord}`, 'Content-Type': 'application/json' } }; const url=`https://discord.com/api/v10/channels/${channel}`; await apiExecute(url, 'channel', data); } </script> Once all the above steps are completed you should have the following: - Discord token - Discord server id number - Discord private `#api` channel id number This only verifies that the token, server id and channel id values are correct. To complete setup, you **MUST** proceed to [POST account/`channel`](/docs/api-faceswap-v1/post-faceswap-account-channel) and complete the configuration. ##### Server <form id="server" onsubmit="verifyServer(); return false;" class="input-form"> <div class="input-field"> <div class="input-field-row"> <label for="server-discord"><span>Discord token</span> <input id="server-discord" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> <label for="server-server"><span>Discord server id</span> <input id="server-server" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> </div> <button id="server-button" class="btn btn-primary fs-3" type="submit">Go</button> </div> </form> <div id="server-response" class="response-placeholder visible-false"></div> ##### Channel <form id="channel" onsubmit="verifyChannel(); return false;" class="input-form"> <div class="input-field"> <div class="input-field-row"> <label for="channel-discord"><span>Discord token</span> <input id="channel-discord" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> <label for="channel-channel"><span>Discord channel id</span> <input id="channel-channel" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> </div> <button id="channel-button" class="btn btn-primary fs-3" type="submit">Go</button> </div> </form> <div id="channel-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-faceswap-v1 === Document URL: https://useapi.net/docs/api-faceswap-v1 --- layout: default title: InsightFaceSwap API nav_logo: /assets/images/picsi.png nav_title: InsightFaceSwap API seo_title: "InsightFaceSwap API: Automate the Picsi.Ai Discord Bot" description: "Third-party InsightFaceSwap API by useapi.net: automate the Picsi.Ai Discord bot over REST for face swaps, HiFidelity, backgrounds and headshots, free or paid." nav_order: 9000 has_children: true permalink: /docs/api-faceswap-v1 --- # <img style="height:1.8em;vertical-align: middle;" src="/assets/images/picsi.png" alt=""> InsightFaceSwap API February 2024 (October 21, 2026) This is a [third-party](/docs/legal#affiliation--third-party-services) API for the [InsightFaceSwap Discord Bot](https://discord.gg/Ym3X8U59ZN) by [Picsi.Ai](https://www.picsi.ai/). It uses your [InsightFaceSwap subscription](https://www.patreon.com/picsi/membership) on Patreon: Free, Basic $9.99, Pro $19.99 or Ultra $34.99 a month (as of October 2026). It turns the Discord bot into a REST API that swaps faces from your photos onto target images and GIFs, makes AI headshots and changes backgrounds. Picsi.Ai sells no API of its own (as of October 2026), so your code swaps faces without opening Discord. ## Models | Model | What it makes | Notes | |---|---|---| | Saved-face swap<br>`/swapid` | [Swaps a saved face](/docs/api-faceswap-v1/post-faceswap-swapid) onto a target image | Save faces once with [POST saveid](/docs/api-faceswap-v1/post-faceswap-saveid). Join names with `+`, as in `mother+father`, to blend up to 3 saved faces into one | | One-step swap<br>`/picsi` | [Swaps the face](/docs/api-faceswap-v1/post-faceswap-picsi) from a source image onto a target image or animated GIF | No saved face needed. Free options keep the target's mouth `-m` or closed eyes `--shut` and fix chin `--ch` and hairline `--hl` | | INSwapper<br>`Apps/INSwapper` | [Swaps the active face](/docs/api-faceswap-v1/post-faceswap-inswapper) onto an image already posted in your Discord channel | Pick the active face with [POST setid](/docs/api-faceswap-v1/post-faceswap-setid), which also takes `+` blends | | Paid modes<br>`-f` `-s` `-e` `-o` `-y` `-a` `-x` | Face Texturizer, Sharpen, Expression matching, Oldify, Youngify, [ARTIFY](https://www.patreon.com/posts/picsi-ai-v2-0-97389077) and Xtreme close-ups, plus [HiFidelity Mode](https://www.patreon.com/posts/89036144) | Expression, Oldify and Youngify take an intensity from 1 to 1000 | | AI headshot<br>`/headshot` | [Portraits of your saved face](/docs/api-faceswap-v1/post-faceswap-headshot) from a text prompt | Results by webhook or [GET jobs/?jobid=](/docs/api-faceswap-v1/get-faceswap-jobid) | | Background change<br>`/changebg` | [A new AI background](/docs/api-faceswap-v1/post-faceswap-changebg) behind the person in your photo, from a text prompt | Results by webhook or polling, and running jobs can be [listed](/docs/api-faceswap-v1/get-faceswap-jobs) or [cancelled](/docs/api-faceswap-v1/get-faceswap-jobs-cancel) | | Face library<br>`/listid` `/delid` `/delall` | [Lists](/docs/api-faceswap-v1/post-faceswap-listid), [deletes one](/docs/api-faceswap-v1/del-faceswap-delid) or [deletes every](/docs/api-faceswap-v1/post-faceswap-delall) saved face | Picsi.Ai keeps a face-print, not your photo | ## Pricing What each InsightFaceSwap plan gives you on the Discord bot, from [Picsi.Ai's price list](https://www.picsi.ai/en/pricing) (as of October 2026). Each plan comes with daily credits, and each job uses some of them. | | Free $0 (10 cr a day) | Ultra $34.99/m (800 cr a day) | Pro $19.99/m (400 cr a day) | Basic $9.99/m (200 cr a day) | |---|---|---|---|---| | Image face swap | 1 cr per face (largest face only) | 1 cr per face (up to 4 faces) | 1 cr per face (up to 4 faces) | 1 cr per face (up to 4 faces) | | Animated GIF swap | paid plans | up to 50 cr (up to 150 frames) | 30 cr (up to 75 frames) | 20 cr (up to 20 frames) | | Paid modes and ARTIFY | paid plans | included | included | included | | Saved faces | 20 | 60 | 60 | 60 | | VIP queue | paid plans | included | included | included | | Lossless PNG output | not included | included | included | not included | - A free InsightFaceSwap account swaps the largest face in a static image, and each account you connect has its own daily credits. - Credits reset every day at 0:00 UTC and don't roll over. Yearly billing costs 20% less, and Picsi.Ai sells the same plans by card on [picsi.ai](https://www.picsi.ai/en/pricing). - Paid plans also allow commercial use of your results, with attribution to Picsi.Ai as its [terms](https://www.picsi.ai/en/terms) set out, and add [many more](https://discord.com/channels/1095014106576212101/1128550062683865178) bot features. ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. ## Run several InsightFaceSwap accounts Each useapi.net subscription connects 3 InsightFaceSwap Discord accounts, each with its own channel and daily credits, so free accounts add up too. Each channel runs one command at a time, which takes about 3 to 10 seconds. One-step swaps and background changes don't need `channel`: they go to a random connected channel with credits left. Other commands name the `channel` once you connect more than one account. An account out of credits answers `412`, and a busy one `429`, so wait 10 to 30 seconds and send it again. [GET account](/docs/api-faceswap-v1/get-faceswap-account) lists your connected accounts. Every command can post its result to your webhook with `replyUrl`, or you poll [GET jobs/?jobid=](/docs/api-faceswap-v1/get-faceswap-jobid). [How useapi.net works](/docs/how-it-works) has tips for keeping your accounts healthy. ## Questions ### Is there an InsightFaceSwap API? Through useapi.net, yes. The useapi.net InsightFaceSwap API sends the bot's [/swapid](/docs/api-faceswap-v1/post-faceswap-swapid), [/picsi](/docs/api-faceswap-v1/post-faceswap-picsi), [/headshot](/docs/api-faceswap-v1/post-faceswap-headshot) and [/changebg](/docs/api-faceswap-v1/post-faceswap-changebg) commands over REST and returns the results as JSON or to your webhook. Picsi.Ai sells no API, only the Discord bot, its web studio and its apps (as of October 2026), so calling InsightFaceSwap from code runs through useapi.net. ### How much does the InsightFaceSwap API cost? Through useapi.net, it runs on your InsightFaceSwap membership, and the free plan works with 10 credits a day. Basic at $9.99 a month raises that to 200 credits a day and adds GIF swaps, multi-face swaps and the paid modes (as of October 2026). The [plan table](#pricing) shows what each tier adds. ### Do I need an InsightFaceSwap API key? Through useapi.net, one [API token](/docs/start-here/setup-useapi) is all the key you need. Invite the bot to a private channel on your own Discord server, then save your Discord token, server and channel with [POST account/`channel`](/docs/api-faceswap-v1/post-faceswap-account-channel). [Setup InsightFaceSwap](/docs/start-here/setup-faceswap) walks through it in about 3 minutes, with a separate Discord account kept for the API. [Setup InsightFaceSwap](/docs/start-here/setup-faceswap) [LLM-friendly API spec](https://useapi.net/assets/aibot/api-faceswap-v1.txt) Feed this to your LLM to build integrations [Claude Code skill](/llm-tools) A drop-in useapi.net skill for Claude Code, and a rule for Cursor [Postman collection](https://www.postman.com/useapinet/useapi-net/collection/29112081-9ac29d7b-9ca5-42c9-9d86-b9e29a16df56) (January 20, 2026) [Setup multiple accounts](/docs/api-faceswap-v1/setup-multiple-faceswap-accounts) Connect several InsightFaceSwap Discord accounts and spread jobs across them Articles: * [How to Face Swap & Animate AI Images via API](/docs/articles/imagine-faceswap-animate) Official documentation links: - [Picsi.Ai Discord bot guide](https://www.picsi.ai/en/docs/discord-bot) - [Discord support channel](https://discord.com/channels/1095014106576212101/1128550062683865178) - [Patreon support channel](https://www.patreon.com/picsi/posts) - [YouTube channel](https://www.youtube.com/@PicsiAi) Developer Community: * <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> * <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> === URL: https://useapi.net/docs/api-faceswap-v1/del-faceswap-account-channel === Document URL: https://useapi.net/docs/api-faceswap-v1/del-faceswap-account-channel --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> faceswap/account/`channel` description: "Delete a configured InsightFaceSwap Discord account by channel via DEL faceswap/account/channel in the useapi.net InsightFaceSwap API v1." parent: InsightFaceSwap API nav_order: 400 --- ## Delete InsightFaceSwap account --- > **https://api.useapi.net/v1/faceswap/account/`channel`** The `channel` value should correspond to an account configured previously via a [POST](/docs/api-faceswap-v1/post-faceswap-account-channel) request. ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **204** **204 No Content** **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** ##### Model A successful delete answers `204` with no body, and an error answers with `error`, `errorDetails` and `code`. <details markdown="block" class="model-details"> <summary>The error answer, field by field</summary> ```typescript { // TypeScript, all fields are optional error: string, errorDetails: string, code: number } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X DELETE https://api.useapi.net/v1/faceswap/account/<channel> ``` **JavaScript** ``` javascript const channel = "Previously configured channel id"; const apiUrl = `https://api.useapi.net/v1/faceswap/account/${channnel}`; const token = "API token"; const data = { method: 'DELETE', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests channel = "Previously configured channel id" apiUrl = f"https://api.useapi.net/v1/faceswap/account/{channel}" token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-faceswap-v1/del-faceswap-delid === Document URL: https://useapi.net/docs/api-faceswap-v1/del-faceswap-delid --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> faceswap/delid description: "Delete a saved face ID by name via DEL faceswap/delid in the useapi.net InsightFaceSwap API v1 — wraps the /delid Discord command with optional replyUrl callback." parent: InsightFaceSwap API nav_order: 1100 --- ## InsightFaceSwap [/delid](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#delid-name) command --- Use this endpoint to submit the InsightFaceSwap [/delid](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#delid-name) command to your [InsightFaceSwap Discord channel](/docs/start-here/setup-faceswap). The result will be returned in the response body and can also be sent as a callback to an optional [`replyUrl`](#request-body). This is a blocking call, you will **not** be able to make another call to the same InsightFaceSwap Discord channel until the current call is completed. The average execution time is approximately 3 to 10 seconds. If you expect high load and need to make multiple concurrent calls, please consider setting up [multiple InsightFaceSwap accounts](/docs/api-faceswap-v1/post-faceswap-account-channel). It is **important** not to use the InsightFaceSwap account setup for API access for any purposes other than its intended use, such as executing `/delid` or any other InsightFaceSwap commands _manually_ or in conjunction with _any other_ automation tools. The useapi.net API internally tracks the usage of the InsightFaceSwap account, including the number of currently active executions. Using it for other activities may cause API to function incorrectly. > **https://api.useapi.net/v1/faceswap/delid** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "channel": "Discord channel id", "idname": "idname param", } ``` - `channel` is optional when only one [faceswap/account](/docs/api-faceswap-v1/get-faceswap-account) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `idname` is **required**, please refer to InsightFaceSwap [/delid](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#delid-name) for details. - `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used. Place here your callback URL. API will call the provided `replyUrl` once job completed or failed. Maximum length 1024 characters. We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality. - `replyRef` is optional, place here your reference id which will be stored and returned along with this job response / result. Maximum length 1024 characters. ##### Responses **200** **200 OK** Field `content` contains message generated by InsightFaceSwap. ```json { "jobid": "<jobid>", "verb": "faceswap-delid", "status": "completed", "idname": "me", "created": "2023-09-09T02:04:49.667Z", "updated": "2023-09-09T02:04:53.490Z", "discord": "<ABC…secured…xyz>", "server": "<Discord server id>", "channel": "<Discord channel id>", "replyUrl": "https://webhook.site/abc", "replyRef": "<your optional reference id>", "messageId": "<Discord message id>", "content": "idname me deleted", "timestamp": "2023-09-09T02:04:51.926000+00:00", "code": 200 } ``` **400** **400 Bad Request** ```json { "error": "Required param idname is missing or empty" "Optional param replyRef is too long" "Optional param replyUrl is too long" "Required param channel is missing or empty" "Configuration not found for channel <channel>, to create POST v1/faceswap/account/<channel>" "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **402** **402 Payment Required** ```json { "error": "Account has no subscription or subscription expired", "code": 402 } ``` **429** **429 Too Many Requests** Wait in a loop for **at least** 10..30 seconds and retry again. There are two possible cases for API response 429. 1. API query is full and can not accept new [faceswap/delid](#insightfaceswap-delid-command) requests. ```json { "error": "Unable to lock Discord after <attempts> attempts", "code": 429 } ``` 2. The API received an HTTP status 429 from the Discord API when it attempted to POST to the `/interactions` endpoint. Under normal circumstances, this should be a rare occurrence because the API is designed to strictly adhere to Discord rate limits. However, in certain scenarios, Discord may still issue a 429 response. ```json { "error": "Discord /interactions failed with HTTP status 429", "errorDetails": "{\"global\":true,\"message\":\"You are being rate limited.\",\"retry_after\":10}", "code": 429 } ``` ##### Model The finished job with its `status`, the `idname` and InsightFaceSwap's reply in `content`. <details markdown="block" class="model-details"> <summary>The <code>delid</code> job record, field by field</summary> ```typescript { // TypeScript, all fields are optional jobid: string, verb: 'faceswap-delid', status: 'completed' | 'failed', idname: string, created: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC updated: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC discord: string, // Provided for debugging purposes only, contains the first 3 and the last 3 characters of the original value server: string, channel: string, replyUrl: string, replyRef: string, messageId: string, content: string, // Contains message generated by InsightFaceSwap timestamp: string, error: string, errorDetails: string, code: number } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Authorization: Bearer …" \ -X DELETE https://api.useapi.net/v1/faceswap/delid \ -F "channel=<Discord channel id>" \ -F "idname=<idname>" ``` **JavaScript** ``` javascript const main = async () => { const apiUrl = "https://api.useapi.net/v1/faceswap/delid"; const token = "API token"; const channel = "Discord channel"; const idname = "idname"; const data = { method: 'DELETE', headers: { 'Authorization': `Bearer ${token}` } }; const formData = new FormData(); formData.append("channel", channel); formData.append("idname", idname); data.body = formData; const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", { response, result }); }; main() ``` **Python** ``` python import requests api_url = "https://api.useapi.net/v1/faceswap/delid" token = "API token" channel = "Discord channel" idname = "idname" headers = { 'Authorization': f'Bearer {token}' } files = { 'channel': (None, channel), 'idname': (None, idname) } response = requests.delete(api_url, headers=headers, files=files) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-faceswap-v1/get-faceswap-account-channel === Document URL: https://useapi.net/docs/api-faceswap-v1/get-faceswap-account-channel --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> faceswap/account/`channel` description: "Retrieve the InsightFaceSwap Discord account config for a specific channel via GET faceswap/account/channel in the useapi.net InsightFaceSwap API v1." parent: InsightFaceSwap API nav_order: 200 --- ## Retrieve InsightFaceSwap configuration for `channel` --- > **https://api.useapi.net/v1/faceswap/account/`channel`** The `channel` value should correspond to an account configured previously via a [POST](/docs/api-faceswap-v1/post-faceswap-account-channel) request. ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** ```json { "server": "Discord server id", "channel": "Discord channel id", "discord": "MTA…secured…aB1", "credits": { "timestamp": "2024-02-01T02:05:24.991000+00:00", "total": 50, "used": 18 } } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** Configuration not found. To create configuration use [faceswap/account/`channel`](/docs/api-faceswap-v1/post-faceswap-account-channel). ##### Model The channel's configuration, with the masked Discord token, server and channel, and the account's `credits` used and total. <details markdown="block" class="model-details"> <summary>The channel configuration and credits, field by field</summary> ```typescript { // TypeScript, all fields are optional discord: string, // masked: first and last 3 characters server: string, channel: string, credits: { timestamp: string, total: number, used: number } } ``` </details> ##### Examples **Curl** ``` bash curl https://api.useapi.net/v1/faceswap/account/<channel> \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const channel = "Previously configured channel id"; const apiUrl = `https://api.useapi.net/v1/faceswap/account/${channel}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" channel = "Previously configured channel id" apiUrl = f"https://api.useapi.net/v1/faceswap/account/{channel}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-faceswap-v1/get-faceswap-account === Document URL: https://useapi.net/docs/api-faceswap-v1/get-faceswap-account --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> faceswap/account description: "List all configured InsightFaceSwap Discord accounts via GET faceswap/account in the useapi.net InsightFaceSwap API v1 — supports multi-account load balancing." parent: InsightFaceSwap API nav_order: 100 --- ## Retrieve InsightFaceSwap accounts information --- Before you start using the API, you **must** [configure](/docs/start-here/setup-faceswap) at least one InsightFaceSwap Discord account. You may specify multiple InsightFaceSwap accounts, the API will automatically perform load balancing by randomly selecting an account with available credits before making calls to InsightFaceSwap Discord bot. This endpoint retrieves the complete list of configured accounts for InsightFaceSwap. > **https://api.useapi.net/v1/faceswap/account** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** ```json { "Discord channel A": { "server": "Discord server A", "channel": "Discord channel A", "discord": "MTA…secured…aB1", "credits": { "timestamp": "2024-02-01T02:05:24.991000+00:00", "total": 50, "used": 18 }, }, "Discord channel B": { "server": "Discord server B", "channel": "Discord channel B", "discord": "MTE…secured…cD2" }, "Discord channel N": { "server": "Discord server N", "channel": "Discord channel N", "discord": "MTI…secured…eF3", "credits": { "timestamp": "2024-02-01T03:17:48.159000+00:00", "total": 200, "used": 115 } } } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** Configuration not found. To create configuration use [faceswap/account/`channel`](/docs/api-faceswap-v1/post-faceswap-account-channel). ##### Model An object keyed by channel id, each value with the masked Discord token, server, channel and `credits` used and total. <details markdown="block" class="model-details"> <summary>The configurations, keyed by channel, field by field</summary> ```typescript { // TypeScript, all fields are optional [channel: string]: { discord: string, // masked: first and last 3 characters server: string, channel: string, credits: { timestamp: string, total: number, used: number } } } ``` </details> ##### Examples **Curl** ``` bash curl https://api.useapi.net/v1/faceswap/account \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = "https://api.useapi.net/v1/faceswap/account"; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" apiUrl = "https://api.useapi.net/v1/faceswap/account" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-faceswap-v1/get-faceswap-jobid === Document URL: https://useapi.net/docs/api-faceswap-v1/get-faceswap-jobid --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> faceswap/jobs/?jobid=`jobid` description: "Poll the status and results of any InsightFaceSwap job by jobid via GET faceswap/jobs in the useapi.net InsightFaceSwap API v1 — supports all job types (headshot, changebg, picsi, swapid, saveid, and more)." parent: InsightFaceSwap API nav_order: 1300 --- ## Retrieve InsightFaceSwap job status and results --- Use this endpoint to retrieve status and results of - [faceswap/headshot](/docs/api-faceswap-v1/post-faceswap-headshot) - [faceswap/changebg](/docs/api-faceswap-v1/post-faceswap-changebg) - [faceswap/picsi](/docs/api-faceswap-v1/post-faceswap-picsi) with initial jobs status returned `started` If you specified optional parameter [`replyUrl`](/docs/api-faceswap-v1/post-faceswap-headshot#request-body) you technically do not need to use this endpoint to retrieve results since API will call provided `replyUrl` once job generation completed. **Important** API periodically polls (checks) Discord every 15 to 60 seconds (depending on the load) and updates all currently executed jobs statuses and results. Polling interval is used for safety reasons, aiming to prevent any potential issues with Discord and InsightFaceSwap, such as bans or excessive requests. Jobs lifespan guaranteed to be at least 31 days, after that they will be expired and may be recycled. > **https://api.useapi.net/v1/faceswap/jobs/?jobid=`jobid`** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameter `jobid` is **required**, use value returned by - [faceswap/headshot](/docs/api-faceswap-v1/post-faceswap-headshot) - [faceswap/changebg](/docs/api-faceswap-v1/post-faceswap-changebg) - [faceswap/picsi](/docs/api-faceswap-v1/post-faceswap-picsi) with initial jobs status returned `started` ##### Responses **200** **200 OK** If field `status` value is *created*, *started* or *progress* wait in a loop for **at least** 10..30 seconds and retry again. When completed retrieve generated images or video from `attachments` array. Field `content` contains message generated by InsightFaceSwap reflecting current generation parameters and progress. Optional array `embeds` contains additional information. ```json { "jobid": "<jobid>", "verb": "faceswap-headshot", "status": "completed", "created": "2023-09-09T02:04:49.667Z", "updated": "2023-09-09T02:19:20.256Z", "prompt": "me, a mad king with an evil smile, wearing medieval royal blue attire and a crown. --no green --square", "discord": "<ABC…secured…xyz>", "server": "<Discord server id>", "channel": "<Discord channel id>", "messageId": "<Discord message id>", "content": "<@Discord user id> Picsi.Ai Headshot Job Submitted [jobid: 8a1f574fdbf79e8cd57e070476d9d5f3] [credits: 4] [prompt: 'a mad king with an evil smile, wearing medieval royal blue attire and a crown. --no green --square'] [time: <time>] [SaveID: 'me'] (796/800 credits remaining)", "timestamp": "2023-09-09T02:05:24.991000+00:00", "attachments": [ { "url": "<generated image url>", "proxy_url": "<generated proxy image url>", "width": 768, "height": 768, "content_type": "<generated image type>", "id": "<Discord attachment id>", "filename": "<generated image filename>", "size": 7204115 } ], "code": 200 } ``` **400** **400 Bad Request** ```json { "error": "Query param jobid not provided", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **402** **402 Payment Required** ```json { "error": "Account has no subscription or subscription expired", "code": 402 } ``` **404** **404 Not Found** ```json { "error": "Unable to locate job <jobid>", "code": 404 } ``` **410** **410 Gone** ```json { "error": "Job has expired", "code": 410 } ``` ##### Model The job with its `status`: while it is `created`, `started` or `progress` poll again, and once it completes the results are in `attachments`. <details markdown="block" class="model-details"> <summary>The job record, field by field</summary> ```typescript { // TypeScript, all fields are optional jobid: string, parentJobId: string, verb: 'faceswap-changebg' | 'faceswap-headshot' | 'faceswap-picsi' | 'faceswap-swapid' | 'faceswap-saveid' | 'faceswap-setid' | 'faceswap-INSwapper' | 'faceswap-listid' | 'faceswap-delall' | 'faceswap-delid' | 'faceswap-swap', status: 'created' | 'started' | 'moderated' | 'progress' | 'completed' | 'failed' | 'cancelled', created: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC updated: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC prompt: string, a_background_photo_of: string, options: string, image: { size: number, type: string }, source_image: { size: number, type: string }, target_image_gif_or_video: { size: number, type: string }, idname: string, saveid_idname: string, saveid_image: { size: number, type: string }, swapid_idname: string, swapid_image: { size: number, type: string }, targetMessageId: string, discord: string, // Provided for debugging purposes only, contains the first 3 and the last 3 characters of the original value server: string, channel: string, messageId: string, content: string, // Contains message generated by InsightFaceSwap reflecting current generation parameters and progress timestamp: string, attachments: [ { id: string, content_type: string, filename: string, url: string, proxy_url: string, size: number, width: number, height: number } ], embeds: [ { type: string, description: string, image: { url: string, proxy_url: string, width: number, height: number } } ], error: string, errorDetails: string, code: 200 } ``` </details> ##### Examples **Curl** ``` bash curl https://api.useapi.net/v1/faceswap/jobs/?jobid=… \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const jobid = "jobid returned by faceswap/changebg, faceswap/headshot or faceswap/picsi"; const apiUrl = `https://api.useapi.net/v1/faceswap/jobs/?jobid=${jobid}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" jobid = "jobid returned by faceswap/changebg, faceswap/headshot or faceswap/picsi" apiUrl = f"https://api.useapi.net/v1/faceswap/jobs/?jobid={jobid}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-faceswap-v1/get-faceswap-jobs-cancel === Document URL: https://useapi.net/docs/api-faceswap-v1/get-faceswap-jobs-cancel --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> jobs/cancel/?jobid=`jobid` description: "Cancel a running InsightFaceSwap job by jobid via GET faceswap/jobs/cancel in the useapi.net InsightFaceSwap API v1 — works for headshot, changebg, and picsi jobs." parent: InsightFaceSwap API nav_order: 2000 --- ## Cancel InsightFaceSwap job --- Cancel execution of job created by - [faceswap/headshot](/docs/api-faceswap-v1/post-faceswap-headshot) - [faceswap/changebg](/docs/api-faceswap-v1/post-faceswap-changebg) - [faceswap/picsi](/docs/api-faceswap-v1/post-faceswap-picsi) with initial jobs status returned `started` > **https://api.useapi.net/v1/faceswap/jobs/cancel/?jobid=`jobid`** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameter `jobid` is **required**, use value returned by - [faceswap/headshot](/docs/api-faceswap-v1/post-faceswap-headshot) - [faceswap/changebg](/docs/api-faceswap-v1/post-faceswap-changebg) - [faceswap/picsi](/docs/api-faceswap-v1/post-faceswap-picsi) with initial jobs status returned `started` ##### Responses **200** ```json { "jobid": "<jobid>", "status": "cancelled" } "code": 200 ``` **400** **400 Bad Request** ```json { "error": "Query param jobid not provided", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **402** **402 Payment Required** ```json { "error": "Account has no subscription or subscription expired", "code": 402 } ``` **404** **404 Not Found** ```json { "error": "Unable to locate job <jobid>", "code": 404 } ``` ##### Model The job's `jobid` and its `status`, which is `cancelled` once the cancel succeeds. <details markdown="block" class="model-details"> <summary>The cancelled job, field by field</summary> ```typescript { // TypeScript, all fields are optional jobid: string, status: 'created' | 'started' | 'moderated' | 'progress' | 'completed' | 'failed' | 'cancelled', error: string, errorDetails: string, code: number } ``` </details> ##### Examples **Curl** ``` bash curl https://api.useapi.net/v1/faceswap/jobs/cancel/?jobid=… \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const jobid = "jobid returned by faceswap/changebg, faceswap/headshot or faceswap/picsi"; const apiUrl = `https://api.useapi.net/v1/faceswap/jobs/cancel/?jobid=${jobid}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" jobid = "jobid returned by faceswap/changebg, faceswap/headshot or faceswap/picsi" apiUrl = f"https://api.useapi.net/v1/faceswap/jobs/cancel/?jobid={jobid}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-faceswap-v1/get-faceswap-jobs === Document URL: https://useapi.net/docs/api-faceswap-v1/get-faceswap-jobs --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> faceswap/jobs description: "List all currently executing InsightFaceSwap jobs via GET faceswap/jobs in the useapi.net InsightFaceSwap API v1 — returns an array of active jobids." parent: InsightFaceSwap API nav_order: 3000 --- ## Get list of currently executing InsightFaceSwap jobs --- > **https://api.useapi.net/v1/faceswap/jobs** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** ```json [ "<jobid>", "<jobid>", "<jobid>" ] ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **402** **402 Payment Required** ```json { "error": "Account has no subscription or subscription expired", "code": 402 } ``` ##### Model An array of the `jobid` values of the jobs running now. <details markdown="block" class="model-details"> <summary>The list of running InsightFaceSwap job ids</summary> ```typescript // TypeScript string[] ``` </details> ##### Examples **Curl** ``` bash curl https://api.useapi.net/v1/faceswap/jobs \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = `https://api.useapi.net/v1/faceswap/jobs`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" apiUrl = f"https://api.useapi.net/v1/faceswap/jobs" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-account-channel === Document URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-account-channel --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> faceswap/account/`channel` description: "Configure an InsightFaceSwap Discord account via POST faceswap/account/channel in the useapi.net InsightFaceSwap API v1 — required before any face-swap API calls." parent: InsightFaceSwap API nav_order: 300 --- ## Create or update InsightFaceSwap account information --- Before you start using the API, you **must** [configure](/docs/start-here/setup-faceswap) at least one InsightFaceSwap Discord account. You may specify multiple InsightFaceSwap accounts, the API will automatically perform load balancing by randomly selecting an account with available credits before making calls to InsightFaceSwap Discord bot. > **https://api.useapi.net/v1/faceswap/account/`channel`** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "discord": "Discord token", "server": "Discord server id", "channel": "Discord channel id" } ``` - `discord`, `channel` and `server` are **required**. Please see [Setup InsightFaceSwap](/docs/start-here/setup-faceswap) for details. - `channel` value specified in the request body **must match** the channel value specified in the URL path https://api.useapi.net/v1/faceswap/account/`channel`. ##### Responses **204** **204 No Content** **400** **400 Bad Request** ```json { "error": "Required param discord is missing or empty" "Required param server is missing or empty" "Required param channel is missing or empty" "Required param channel (<server>) is not valid Discord channel id" "Required param channel (<channel>) is not valid Discord channel id" "Required param channel (<channel>) not matching to /faceswap/account/<channel>" "Channel <channel> configuration has same discord value" "Channel <channel> configuration has same server value" "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model A successful save answers `204` with no body, and an error answers with `error` and `code`. <details markdown="block" class="model-details"> <summary>The channel configuration or the error answer, field by field</summary> ```typescript { // TypeScript, all fields are optional discord: string, server: string, channel: string, error: string, errorDetails: string, code: number } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST https://api.useapi.net/v1/faceswap/account/<channel> \ -d '{"discord": "…", "server": "…", "channel": …}' ``` **JavaScript** ``` javascript const channel = "Discord channel id"; const apiUrl = `https://api.useapi.net/v1/faceswap/account/${channel}`; const token = "API token"; const discord = "Discord token"; const server = "Discord server id"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ discord, server, channel }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests channel = "Discord channel id" apiUrl = f"https://api.useapi.net/v1/faceswap/account/{channel}" token = "API token" discord = "Discord token" server = "Discord server id" maxJobs = 10 headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } body = { "discord": f"{discord}", "server": f"{server}", "channel": f"{channel}" } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-changebg === Document URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-changebg --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> faceswap/changebg description: "Change a photo's background to an AI-generated scene via POST faceswap/changebg in the useapi.net InsightFaceSwap API v1 — request params and response examples." parent: InsightFaceSwap API nav_order: 470 --- ## InsightFaceSwap [/changebg](https://www.patreon.com/posts/introducing-ai-5-104943286) command --- Use this endpoint to submit the InsightFaceSwap [/changebg](https://www.patreon.com/posts/introducing-ai-5-104943286) command to your [InsightFaceSwap Discord channel](/docs/start-here/setup-faceswap). Results obtained as a callback via optional parameter [`replyUrl`](#request-body) or by querying [faceswap/jobs/?jobid=`jobid`](/docs/api-faceswap-v1/get-faceswap-jobid) endpoint. It is **important** not to use the InsightFaceSwap account setup for API access for any purposes other than its intended use, such as executing `/changebg` or any other InsightFaceSwap commands _manually_ or in conjunction with _any other_ automation tools. The useapi.net API internally tracks the usage of the InsightFaceSwap account, including the number of currently active executions. Using it for other activities may cause API to function incorrectly. > **https://api.useapi.net/v1/faceswap/changebg** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "channel": "Discord channel id", "a_background_photo_of": "Background prompt", "image": "Image File or Blob", "replyUrl": "Place your call back URL here", "replyRef": "Place your reference id here" } ``` - `channel` is optional, if omitted a randomly selected [configured](/docs/api-faceswap-v1/post-faceswap-account-channel) channel with available credits will be used. - `a_background_photo_of` is **required**, background prompt, please refer to InsightFaceSwap [/changebg](https://www.patreon.com/posts/introducing-ai-5-104943286) for details. - `image` is **required**, source image. Must be either a [File](https://developer.mozilla.org/en-US/docs/Web/API/File) or [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob) object when included in this [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData) POST request. - `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used. Place here your callback URL. API will call the provided `replyUrl` once job completed or failed. Maximum length 1024 characters. We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality. Callback body has the same JSON shape as [GET /`jobid`](/docs/api-faceswap-v1/get-faceswap-jobid) response. - `replyRef` is optional, place here your reference id which will be stored and returned along with this job response / result. Maximum length 1024 characters. ##### Responses **200** **200 OK** Use returned `jobid` to [retrieve InsightFaceSwap job status and results](/docs/api-faceswap-v1/get-faceswap-jobid) or use callback `replyUrl`. Field `content` contains message generated by InsightFaceSwap. ```json { "jobid": "<jobid>", "verb": "faceswap-changebg", "status": "started", "a_background_photo_of": "sunny beach", "image": { "size": 1699405, "type": "image/png" }, "created": "2023-09-09T02:04:49.667Z", "updated": "2023-09-09T02:04:53.490Z", "discord": "<ABC…secured…xyz>", "server": "<Discord server id>", "channel": "<Discord channel id>", "replyUrl": "https://webhook.site/abc", "replyRef": "<your optional reference id>", "messageId": "<Discord message id>", "content": "<@Discord user id> Picsi.Ai ChangeBG Job Submitted [jobid: 8a1f574fdbf79e8cd57e070476d9d5f3] [credits: 4] [prompt: 'sunny beach'] [time: <time>] [SaveID: '_'] (796/800 credits remaining)", "timestamp": "2023-09-09T02:04:51.926000+00:00", "code": 200 } ``` **400** **400 Bad Request** ```json { "error": "Required param a_background_photo_of is missing or empty" "Required param image is missing or empty" "Param image is not File or Blob" "Optional param replyRef is too long" "Optional param replyUrl is too long" "Configuration not found for channel <channel>, to create POST v1/faceswap/account/<channel>" "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **402** **402 Payment Required** ```json { "error": "Account has no subscription or subscription expired", "code": 402 } ``` **429** **429 Too Many Requests** Wait in a loop for **at least** 10..30 seconds and retry again. There are two possible cases for API response 429. 1. API query is full and can not accept new [faceswap/changebg](#insightfaceswap-changebg-command) requests. ```json { "error": "Unable to lock Discord after <attempts> attempts", "code": 429 } ``` 2. The API received an HTTP status 429 from the Discord API when it attempted to POST to the `/interactions` endpoint. Under normal circumstances, this should be a rare occurrence because the API is designed to strictly adhere to Discord rate limits. However, in certain scenarios, Discord may still issue a 429 response. ```json { "error": "Discord /interactions failed with HTTP status 429", "errorDetails": "{\"global\":true,\"message\":\"You are being rate limited.\",\"retry_after\":10}", "code": 429 } ``` ##### Model The new job's `jobid` with status `started`: poll it with [GET jobs/?jobid=`jobid`](/docs/api-faceswap-v1/get-faceswap-jobid) until it completes, or wait for the `replyUrl` callback. <details markdown="block" class="model-details"> <summary>The new <code>changebg</code> job, field by field</summary> ```typescript { // TypeScript, all fields are optional jobid: string, verb: 'faceswap-changebg', status: 'started' | 'failed', a_background_photo_of: string, image: { size: number, type: string }, created: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC updated: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC discord: string, // Provided for debugging purposes only, contains the first 3 and the last 3 characters of the original value server: string, channel: string, replyUrl: string, replyRef: string, messageId: string, content: string, // Contains message generated by InsightFaceSwap timestamp: string, error: string, errorDetails: string, code: number } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Authorization: Bearer …" \ -X POST https://api.useapi.net/v1/faceswap/changebg \ -F "channel=<Discord channel id>" \ -F 'image=@"<Path to the image>"' \ -F "a_background_photo_of=<a_background_photo_of>" ``` **JavaScript** ``` javascript const main = async () => { const apiUrl = "https://api.useapi.net/v1/faceswap/changebg"; const token = "API token"; const a_background_photo_of = "a_background_photo_of"; const channel = "Discord channel"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${token}` } }; const formData = new FormData(); formData.append("a_background_photo_of", a_background_photo_of); formData.append("channel", channel); /* // Example 1: Fetch image from URL const imageUrl = "https://upload.wikimedia.org/wikipedia/commons/7/7d/Mona_Lisa_color_restoration.jpg"; const responseImage = await fetch(imageUrl); formData.append("image", await responseImage.blob()); */ /* // Example 2: Load image from local file (Blob) const fsp = require('fs').promises; const imageFileName = "./target_photo.png"; const blob = new Blob([await fsp.readFile(imageFileName)]); formData.append("image", blob); */ /* // Example 3: Load from input file html element // <input id="target-photo-image-file" type="file"> const imageFile = document.getElementById(`target-photo-image-file`); if (imageFile.files[0]) formData.append("image", imageFile.files[0]); */ data.body = formData; const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", { response, result }); }; main() ``` **Python** ``` python import requests api_url = "https://api.useapi.net/v1/faceswap/changebg" token = "API token" a_background_photo_of = "a_background_photo_of" channel = "Discord channel" headers = { 'Authorization': f'Bearer {token}' } files = { 'a_background_photo_of': (None, a_background_photo_of), 'channel': (None, channel) } # # Example 1: Fetch image from URL # image_url = "https://upload.wikimedia.org/wikipedia/commons/7/7d/Mona_Lisa_color_restoration.jpg" # response_image = requests.get(image_url) # image_content = response_image.content # files['image'] = ('image.jpg', image_content, 'image/jpeg') # # Example 2: Load image from local file # image_file_path = "./target_photo.png" # with open(image_file_path, 'rb') as image_file: # files['image'] = ('target_photo.png', image_file.read(), 'image/png') response = requests.post(api_url, headers=headers, files=files) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-delall === Document URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-delall --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> faceswap/delall description: "Delete all saved face IDs from an InsightFaceSwap channel via DEL faceswap/delall in the useapi.net InsightFaceSwap API v1 — wraps the /delall Discord command." parent: InsightFaceSwap API nav_order: 1200 --- ## InsightFaceSwap [/delall](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#delall) command --- Use this endpoint to submit the InsightFaceSwap [/delall](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#delall) command to your [InsightFaceSwap Discord channel](/docs/start-here/setup-faceswap). The result will be returned in the response body and can also be sent as a callback to an optional [`replyUrl`](#request-body). This is a blocking call, you will **not** be able to make another call to the same InsightFaceSwap Discord channel until the current call is completed. The average execution time is approximately 3 to 10 seconds. If you expect high load and need to make multiple concurrent calls, please consider setting up [multiple InsightFaceSwap accounts](/docs/api-faceswap-v1/post-faceswap-account-channel). It is **important** not to use the InsightFaceSwap account setup for API access for any purposes other than its intended use, such as executing `/delall` or any other InsightFaceSwap commands _manually_ or in conjunction with _any other_ automation tools. The useapi.net API internally tracks the usage of the InsightFaceSwap account, including the number of currently active executions. Using it for other activities may cause API to function incorrectly. > **https://api.useapi.net/v1/faceswap/delall** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "channel": "Discord channel id" } ``` - `channel` is optional when only one [faceswap/account](/docs/api-faceswap-v1/get-faceswap-account) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used. Place here your callback URL. API will call the provided `replyUrl` once job completed or failed. Maximum length 1024 characters. We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality. Callback body has the same JSON shape as [GET /`jobid`](/docs/api-faceswap-v1/get-faceswap-jobid) response. - `replyRef` is optional, place here your reference id which will be stored and returned along with this job response / result. Maximum length 1024 characters. ##### Responses **200** **200 OK** Field `content` contains message generated by InsightFaceSwap. ```json { "jobid": "<jobid>", "verb": "faceswap-delall", "status": "completed", "created": "2023-09-09T02:04:49.667Z", "updated": "2023-09-09T02:04:53.490Z", "discord": "<ABC…secured…xyz>", "server": "<Discord server id>", "channel": "<Discord channel id>", "replyUrl": "https://webhook.site/abc", "replyRef": "<your optional reference id>", "messageId": "<Discord message id>", "content": "All idnames deleted", "timestamp": "2023-09-09T02:04:51.926000+00:00", "code": 200 } ``` **400** **400 Bad Request** ```json { "error": "Optional param replyRef is too long" "Optional param replyUrl is too long" "Required param channel is missing or empty" "Configuration not found for channel <channel>, to create POST v1/faceswap/account/<channel>" "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **402** **402 Payment Required** ```json { "error": "Account has no subscription or subscription expired", "code": 402 } ``` **429** **429 Too Many Requests** Wait in a loop for **at least** 10..30 seconds and retry again. There are two possible cases for API response 429. 1. API query is full and can not accept new [faceswap/delall](#insightfaceswap-delall-command) requests. ```json { "error": "Unable to lock Discord after <attempts> attempts", "code": 429 } ``` 2. The API received an HTTP status 429 from the Discord API when it attempted to POST to the `/interactions` endpoint. Under normal circumstances, this should be a rare occurrence because the API is designed to strictly adhere to Discord rate limits. However, in certain scenarios, Discord may still issue a 429 response. ```json { "error": "Discord /interactions failed with HTTP status 429", "errorDetails": "{\"global\":true,\"message\":\"You are being rate limited.\",\"retry_after\":10}", "code": 429 } ``` ##### Model The finished job with its `status` and InsightFaceSwap's reply in `content`. <details markdown="block" class="model-details"> <summary>The <code>delall</code> job record, field by field</summary> ```typescript { // TypeScript, all fields are optional jobid: string, verb: 'faceswap-delall', status: 'completed' | 'failed', created: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC updated: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC discord: string, // Provided for debugging purposes only, contains the first 3 and the last 3 characters of the original value server: string, channel: string, replyUrl: string, replyRef: string, messageId: string, content: string, // Contains message generated by InsightFaceSwap timestamp: string, error: string, errorDetails: string, code: number } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Authorization: Bearer …" \ -X DELETE https://api.useapi.net/v1/faceswap/delall \ -F "channel=<Discord channel id>" ``` **JavaScript** ``` javascript const main = async () => { const apiUrl = "https://api.useapi.net/v1/faceswap/delall"; const token = "API token"; const channel = "Discord channel"; const data = { method: 'DELETE', headers: { 'Authorization': `Bearer ${token}` } }; const formData = new FormData(); formData.append("channel", channel); data.body = formData; const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", { response, result }); }; main() ``` **Python** ``` python import requests api_url = "https://api.useapi.net/v1/faceswap/delall" token = "API token" channel = "Discord channel" headers = { 'Authorization': f'Bearer {token}' } files = { 'channel': (None, channel) } response = requests.delete(api_url, headers=headers, files=files) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-headshot === Document URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-headshot --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> faceswap/headshot description: "Generate AI headshot portraits via POST faceswap/headshot in the useapi.net InsightFaceSwap API v1 — results delivered by replyUrl callback or jobid polling." parent: InsightFaceSwap API nav_order: 950 --- ## InsightFaceSwap [/headshot](https://www.patreon.com/posts/introducing-ai-5-101604168) command --- Use this endpoint to submit the InsightFaceSwap [/headshot](https://www.patreon.com/posts/introducing-ai-5-101604168) command to your [InsightFaceSwap Discord channel](/docs/start-here/setup-faceswap). Results obtained as a callback via optional parameter [`replyUrl`](#request-body) or by querying [faceswap/jobs/?jobid=`jobid`](/docs/api-faceswap-v1/get-faceswap-jobid) endpoint. It is **important** not to use the InsightFaceSwap account setup for API access for any purposes other than its intended use, such as executing `/headshot` or any other InsightFaceSwap commands _manually_ or in conjunction with _any other_ automation tools. The useapi.net API internally tracks the usage of the InsightFaceSwap account, including the number of currently active executions. Using it for other activities may cause API to function incorrectly. > **https://api.useapi.net/v1/faceswap/headshot** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: multipart/form-data # Alternatively you can use application/json # Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "channel": "Discord channel id", "prompt": "Background prompt", "replyUrl": "Place your call back URL here", "replyRef": "Place your reference id here" } ``` - `channel` is optional when only one [faceswap/account](/docs/api-faceswap-v1/get-faceswap-account) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `prompt` is **required**, please refer to InsightFaceSwap [/headshot](https://www.patreon.com/posts/introducing-ai-5-101604168) for details. - `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used. Place here your callback URL. API will call the provided `replyUrl` once job completed or failed. Maximum length 1024 characters. We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality. Callback body has the same JSON shape as [GET /`jobid`](/docs/api-faceswap-v1/get-faceswap-jobid) response. - `replyRef` is optional, place here your reference id which will be stored and returned along with this job response / result. Maximum length 1024 characters. ##### Responses **200** **200 OK** Use returned `jobid` to [retrieve InsightFaceSwap job status and results](/docs/api-faceswap-v1/get-faceswap-jobid) or use callback `replyUrl`. Field `content` contains message generated by InsightFaceSwap. ```json { "jobid": "<jobid>", "verb": "faceswap-headshot", "status": "started", "prompt": "me, a mad king with an evil smile, wearing medieval royal blue attire and a crown. --no green --square", "created": "2023-09-09T02:04:49.667Z", "updated": "2023-09-09T02:04:53.490Z", "discord": "<ABC…secured…xyz>", "server": "<Discord server id>", "channel": "<Discord channel id>", "replyUrl": "https://webhook.site/abc", "replyRef": "<your optional reference id>", "messageId": "<Discord message id>", "content": "<@Discord user id> Picsi.Ai Headshot Job Submitted [jobid: 8a1f574fdbf79e8cd57e070476d9d5f3] [credits: 4] [prompt: 'a mad king with an evil smile, wearing medieval royal blue attire and a crown. --no green --square'] [time: <time>] [SaveID: 'me'] (796/800 credits remaining)", "timestamp": "2023-09-09T02:04:51.926000+00:00", "code": 200 } ``` **400** **400 Bad Request** ```json { "error": "Required param prompt is missing or empty" "Optional param replyRef is too long" "Optional param replyUrl is too long" "Configuration not found for channel <channel>, to create POST v1/faceswap/account/<channel>" "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **402** **402 Payment Required** ```json { "error": "Account has no subscription or subscription expired", "code": 402 } ``` **429** **429 Too Many Requests** Wait in a loop for **at least** 10..30 seconds and retry again. There are two possible cases for API response 429. 1. API query is full and can not accept new [faceswap/headshot](#insightfaceswap-headshot-command) requests. ```json { "error": "Unable to lock Discord after <attempts> attempts", "code": 429 } ``` 2. The API received an HTTP status 429 from the Discord API when it attempted to POST to the `/interactions` endpoint. Under normal circumstances, this should be a rare occurrence because the API is designed to strictly adhere to Discord rate limits. However, in certain scenarios, Discord may still issue a 429 response. ```json { "error": "Discord /interactions failed with HTTP status 429", "errorDetails": "{\"global\":true,\"message\":\"You are being rate limited.\",\"retry_after\":10}", "code": 429 } ``` ##### Model The new job's `jobid` with status `started`: poll it with [GET jobs/?jobid=`jobid`](/docs/api-faceswap-v1/get-faceswap-jobid) until it completes, or wait for the `replyUrl` callback. <details markdown="block" class="model-details"> <summary>The new <code>headshot</code> job, field by field</summary> ```typescript { // TypeScript, all fields are optional jobid: string, verb: 'faceswap-headshot', status: 'started' | 'failed', prompt: string, created: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC updated: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC discord: string, // Provided for debugging purposes only, contains the first 3 and the last 3 characters of the original value server: string, channel: string, replyUrl: string, replyRef: string, messageId: string, content: string, // Contains message generated by InsightFaceSwap timestamp: string, error: string, errorDetails: string, code: number } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Authorization: Bearer …" \ -X POST https://api.useapi.net/v1/faceswap/headshot \ -F "channel=<Discord channel id>" \ -F "prompt=<prompt>" ``` **JavaScript** ``` javascript const main = async () => { const apiUrl = "https://api.useapi.net/v1/faceswap/headshot"; const token = "API token"; const prompt = "prompt"; const channel = "Discord channel"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${token}` } }; const formData = new FormData(); formData.append("prompt", prompt); formData.append("channel", channel); data.body = formData; const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", { response, result }); }; main() ``` **Python** ``` python import requests api_url = "https://api.useapi.net/v1/faceswap/headshot" token = "API token" prompt = "prompt" channel = "Discord channel" headers = { 'Authorization': f'Bearer {token}' } files = { 'prompt': (None, prompt), 'channel': (None, channel) } response = requests.post(api_url, headers=headers, files=files) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-inswapper === Document URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-inswapper --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> faceswap/inswapper description: "Swap faces on a Discord-hosted image using Apps/INSwapper via POST faceswap/inswapper in the useapi.net InsightFaceSwap API v1 — blocking call with replyUrl support." parent: InsightFaceSwap API nav_order: 900 --- ## InsightFaceSwap [Apps/INSwapper](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#appsinswapper) command --- Use this endpoint to submit the InsightFaceSwap [Apps/INSwapper](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#appsinswapper) command to your [InsightFaceSwap Discord channel](/docs/start-here/setup-faceswap). The result will be returned in the response body and can also be sent as a callback to an optional [`replyUrl`](#request-body). If you already have a message in your channel with an attached image, you can use this endpoint to perform a face swap on the image contained in that message. You need `message.id` returned by [messages](https://discord.com/developers/docs/resources/channel#get-channel-messages) GET request https://discord.com/api/v10/channels/channel_id/messages ([article](/docs/articles/discord-api-part-1#finally-retrieve-imagine-commandresults)). You can also use field `messageId` returned by [Midjouney API v2](https://useapi.net/docs/api-v2/get-jobs-jobid#responses). This is a blocking call, you will **not** be able to make another call to the same InsightFaceSwap Discord channel until the current call is completed. The average execution time is approximately 3 to 10 seconds. If you expect high load and need to make multiple concurrent calls, please consider setting up [multiple InsightFaceSwap accounts](/docs/api-faceswap-v1/post-faceswap-account-channel). It is **important** not to use the InsightFaceSwap account setup for API access for any purposes other than its intended use, such as executing `/inswapper` or any other InsightFaceSwap commands _manually_ or in conjunction with _any other_ automation tools. The useapi.net API internally tracks the usage of the InsightFaceSwap account, including the number of currently active executions. Using it for other activities may cause API to function incorrectly. > **https://api.useapi.net/v1/faceswap/inswapper** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "channel": "Discord channel id", "targetMessageId": "Discord message id with attached image" } ``` - `channel` is optional when only one [faceswap/account](/docs/api-faceswap-v1/get-faceswap-account) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `targetMessageId` is **required**, Discord message id with an attached image. The message must be located in the channel specified by the channel param mentioned above. - `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used. Place here your callback URL. API will call the provided `replyUrl` once job completed or failed. Maximum length 1024 characters. We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality. Callback body has the same JSON shape as [GET /`jobid`](/docs/api-faceswap-v1/get-faceswap-jobid) response. - `replyRef` is optional, place here your reference id which will be stored and returned along with this job response / result. Maximum length 1024 characters. ##### Responses **200** **200 OK** Field `content` contains message generated by InsightFaceSwap. Attachments array contains generated image. ```json { "jobid": "<jobid>", "verb": "faceswap-inswapper", "status": "completed", "targetMessageId": "1106423469968976446", "created": "2023-09-09T02:04:49.667Z", "updated": "2023-09-09T02:04:53.490Z", "discord": "<ABC…secured…xyz>", "server": "<Discord server id>", "channel": "<Discord channel id>", "replyUrl": "https://webhook.site/abc", "replyRef": "<your optional reference id>", "messageId": "<Discord message id>", "content": "Picsi.Ai ver.2.0 [SaveID: 'me'] [<@Discord user id>] (90/200 credits used)", "attachments": [ { "url": "<generated image url>", "proxy_url": "<generated proxy image url>", "width": 2048, "height": 2048, "content_type": "<generated image type>", "id": "<Discord image id>", "filename": "<generated image name>", "size": 7204115 } ], "timestamp": "2023-09-09T02:04:51.926000+00:00", "code": 200 } ``` **400** **400 Bad Request** ```json { "error": "Required param targetMessageId is missing or empty" "Required param targetMessageId (<targetMessageId>) is not valid Discord message id" "Optional param replyUrl is too long" "Required param channel is missing or empty" "Configuration not found for channel <channel>, to create POST v1/faceswap/account/<channel>" "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **402** **402 Payment Required** ```json { "error": "Account has no subscription or subscription expired", "code": 402 } ``` **404** **404 Not Found** ```json { "error": "Unable to locate message <targetMessageId> is channel <channel>" "Unable to locate attachments for message <targetMessageId>" "code": 404 } ``` **429** **429 Too Many Requests** Wait in a loop for **at least** 10..30 seconds and retry again. There are two possible cases for API response 429. 1. API query is full and can not accept new faceswap/inswapper requests. ```json { "error": "Unable to lock Discord after <attempts> attempts", "code": 429 } ``` 2. The API received an HTTP status 429 from the Discord API when it attempted to POST to the `/interactions` endpoint. Under normal circumstances, this should be a rare occurrence because the API is designed to strictly adhere to Discord rate limits. However, in certain scenarios, Discord may still issue a 429 response. ```json { "error": "Discord /interactions failed with HTTP status 429", "errorDetails": "{\"global\":true,\"message\":\"You are being rate limited.\",\"retry_after\":10}", "code": 429 } ``` ##### Model The finished job with its `status`, InsightFaceSwap's reply in `content` and the generated image in `attachments`. <details markdown="block" class="model-details"> <summary>The INSwapper job record, field by field</summary> ```typescript { // TypeScript, all fields are optional jobid: string, verb: 'faceswap-inswapper', status: 'completed' | 'failed', targetMessageId: string, created: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC updated: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC discord: string, // Provided for debugging purposes only, contains the first 3 and the last 3 characters of the original value server: string, channel: string, replyUrl: string, replyRef: string, messageId: string, content: string, // Contains message generated by InsightFaceSwap attachments: [ { id: string, content_type: string, filename: string, url: string, proxy_url: string, size: number, width: number, height: number } ], timestamp: string, error: string, errorDetails: string, code: number } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Authorization: Bearer …" \ -X POST https://api.useapi.net/v1/faceswap/inswapper \ -F "channel=<Discord channel id>" \ -F "targetMessageId=<Discord message id>" ``` **JavaScript** ``` javascript const main = async () => { const apiUrl = "https://api.useapi.net/v1/faceswap/inswapper"; const token = "API token"; const targetMessageId = "Discord message id"; const channel = "Discord channel"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${token}` } }; const formData = new FormData(); formData.append("targetMessageId", targetMessageId); formData.append("channel", channel); data.body = formData; const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", { response, result }); }; main() ``` **Python** ``` python import requests api_url = "https://api.useapi.net/v1/faceswap/inswapper" token = "API token" targetMessageId = "Discord message id" channel = "Discord channel" headers = { 'Authorization': f'Bearer {token}' } files = { 'targetMessageId': (None, targetMessageId), 'channel': (None, channel) } response = requests.post(api_url, headers=headers, files=files) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-listid === Document URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-listid --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> faceswap/listid description: "List all saved face IDs in an InsightFaceSwap Discord channel via POST faceswap/listid in the useapi.net InsightFaceSwap API v1 — parameters and response examples." parent: InsightFaceSwap API nav_order: 500 --- ## InsightFaceSwap [/listid](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#listid) command --- Use this endpoint to submit the InsightFaceSwap [/listid](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#listid) command to your [InsightFaceSwap Discord channel](/docs/start-here/setup-faceswap). The result will be returned in the response body and can also be sent as a callback to an optional [`replyUrl`](#request-body). This is a blocking call, you will **not** be able to make another call to the same InsightFaceSwap Discord channel until the current call is completed. The average execution time is approximately 3 to 10 seconds. If you expect high load and need to make multiple concurrent calls, please consider setting up [multiple InsightFaceSwap accounts](/docs/api-faceswap-v1/post-faceswap-account-channel). It is **important** not to use the InsightFaceSwap account setup for API access for any purposes other than its intended use, such as executing `/listid` or any other InsightFaceSwap commands _manually_ or in conjunction with _any other_ automation tools. The useapi.net API internally tracks the usage of the InsightFaceSwap account, including the number of currently active executions. Using it for other activities may cause API to function incorrectly. > **https://api.useapi.net/v1/faceswap/listid** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "channel": "Discord channel id" } ``` - `channel` is optional when only one [faceswap/account](/docs/api-faceswap-v1/get-faceswap-account) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used. Place here your callback URL. API will call the provided `replyUrl` once job completed or failed. Maximum length 1024 characters. We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality. Callback body has the same JSON shape as [GET /`jobid`](/docs/api-faceswap-v1/get-faceswap-jobid) response. - `replyRef` is optional, place here your reference id which will be stored and returned along with this job response / result. Maximum length 1024 characters. ##### Responses **200** **200 OK** Field `content` contains message generated by InsightFaceSwap. ```json { "jobid": "<jobid>", "verb": "faceswap-listid", "status": "completed", "created": "2023-09-09T02:04:49.667Z", "updated": "2023-09-09T02:04:53.490Z", "discord": "<ABC…secured…xyz>", "server": "<Discord server id>", "channel": "<Discord channel id>", "replyUrl": "https://webhook.site/abc", "replyRef": "<your optional reference id>", "messageId": "<Discord message id>", "content": "{'id-list': ['ttt']}\n{'current-idname': 'ttt'}\n{'subscription': 'Free'}\n{'credits': '0/50'}", "timestamp": "2023-09-09T02:04:51.926000+00:00", "code": 200 } ``` **400** **400 Bad Request** ```json { "error": "Optional param replyRef is too long" "Optional param replyUrl is too long" "Required param channel is missing or empty" "Configuration not found for channel <channel>, to create POST v1/faceswap/account/<channel>" "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **402** **402 Payment Required** ```json { "error": "Account has no subscription or subscription expired", "code": 402 } ``` **429** **429 Too Many Requests** Wait in a loop for **at least** 10..30 seconds and retry again. There are two possible cases for API response 429. 1. API query is full and can not accept new [faceswap/listid](#insightfaceswap-listid-command) requests. ```json { "error": "Unable to lock Discord after <attempts> attempts", "code": 429 } ``` 2. The API received an HTTP status 429 from the Discord API when it attempted to POST to the `/interactions` endpoint. Under normal circumstances, this should be a rare occurrence because the API is designed to strictly adhere to Discord rate limits. However, in certain scenarios, Discord may still issue a 429 response. ```json { "error": "Discord /interactions failed with HTTP status 429", "errorDetails": "{\"global\":true,\"message\":\"You are being rate limited.\",\"retry_after\":10}", "code": 429 } ``` ##### Model The finished job with its `status` and InsightFaceSwap's reply in `content`, listing the saved idnames, the current one and the credits. <details markdown="block" class="model-details"> <summary>The <code>listid</code> job record, field by field</summary> ```typescript { // TypeScript, all fields are optional jobid: string, verb: 'faceswap-listid', status: 'completed' | 'failed', created: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC updated: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC discord: string, // Provided for debugging purposes only, contains the first 3 and the last 3 characters of the original value server: string, channel: string, replyUrl: string, replyRef: string, messageId: string, content: string, // Contains message generated by InsightFaceSwap timestamp: string, error: string, errorDetails: string, code: number } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Authorization: Bearer …" \ -X POST https://api.useapi.net/v1/faceswap/listid \ -F "channel=<Discord channel id>" ``` **JavaScript** ``` javascript const main = async () => { const apiUrl = "https://api.useapi.net/v1/faceswap/listid"; const token = "API token"; const channel = "Discord channel"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${token}` } }; const formData = new FormData(); formData.append("channel", channel); data.body = formData; const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", { response, result }); }; main() ``` **Python** ``` python import requests api_url = "https://api.useapi.net/v1/faceswap/listid" token = "API token" channel = "Discord channel" headers = { 'Authorization': f'Bearer {token}' } files = { 'channel': (None, channel) } response = requests.post(api_url, headers=headers, files=files) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-picsi === Document URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-picsi --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> faceswap/picsi description: "Generate a Picsi.Ai face morph from a source image and a target image or GIF via POST faceswap/picsi in the useapi.net InsightFaceSwap API v1 — video not currently supported." parent: InsightFaceSwap API nav_order: 450 --- ## InsightFaceSwap [/picsi](https://www.patreon.com/posts/introducing-ai-5-101604168) command February 12, 2024 (November 18, 2024) --- Use this endpoint to submit the InsightFaceSwap [/picsi](https://www.patreon.com/posts/introducing-ai-5-101604168) command to directly generate a Picsi.Ai face morph by attaching a source image and target image/gif/video. The result will be returned in the response body and can also be sent as a callback to an optional [`replyUrl`](#request-body). This is a blocking call, you will **not** be able to make another call to the same InsightFaceSwap Discord channel until the current call is completed. The average execution time is approximately 3 to 10 seconds. If you expect high load and need to make multiple concurrent calls, please consider setting up [multiple InsightFaceSwap accounts](/docs/api-faceswap-v1/post-faceswap-account-channel). It is **important** not to use the InsightFaceSwap account setup for API access for any purposes other than its intended use, such as executing `/picsi` or any other InsightFaceSwap commands _manually_ or in conjunction with _any other_ automation tools. The useapi.net API internally tracks the usage of the InsightFaceSwap account, including the number of currently active executions. Using it for other activities may cause API to function incorrectly. > **https://api.useapi.net/v1/faceswap/picsi** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "channel": "Discord channel id", "source_image": "Source image", "target_image_gif_or_video": "Target Image/GIF/Video", "options": "Optional parameters such as -f (Face Texturizer), -m (Retain Mouth) etc", "replyUrl": "Place your call back URL here", "replyRef": "Place your reference id here" } ``` - `channel` is optional, if omitted a randomly selected [configured](/docs/api-faceswap-v1/post-faceswap-account-channel) channel with available credits will be used. - `source_image` is **required**, source image. Must be either a [File](https://developer.mozilla.org/en-US/docs/Web/API/File) or [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob) object when included in this [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData) POST request. - `target_image_gif_or_video` is **required**, target image/GIF/Video. Must be either a [File](https://developer.mozilla.org/en-US/docs/Web/API/File) or [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob) object when included in this [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData) POST request. <span class="required-input-field"><b>Important</b></span> Video currently *not* supported. - `options` is optional, for parameters such as -f (Face Texturizer), -m (Retain Mouth), see [official help](https://discord.com/channels/1095014106576212101/1128550062683865178/1189615783433740349) for details. Options supported by **Free** version (this may not be a complete or current list, please refer to [official help](https://discord.com/channels/1095014106576212101/1128550062683865178/1189615783433740349)): * `-m` Keeps the mouth area of the target picture unchanged in the morphed result. * `--shut` Keeps eyes closed in your morphed results matching the closed eyes of the target face. To be used ONLY when the eyes are already closed in the target picture's face. This will NOT close eyes that are open. * `--ch` Corrects mismatches in chin and jawline between source and target faces. * `--hl` Addresses issues with bangs or low hairlines in source photos morphing incorrectly on target face. Options supported by **Paid** version (this may not be a complete or current list, please refer to [official help](https://discord.com/channels/1095014106576212101/1128550062683865178/1189615783433740349)): * `-f` Face Texturizer mode attempts to preserve intricate details of the target face like fine wrinkles, blemishes and freckles. * `-s` Sharpen option adds clarity and definition. * `-e` Expression Matching synchronizes the expressions between your source face and the target face in the morph. This includes aspects like smiles, frowns, or any other facial expressions, aiming to retain the target face's expression in the resulting morph for enhanced realism. * `-e 1...1000` Expression intensity. * `-o` or `--oldify` Transforms faces in your images to appear older, offering an intriguing look into the future. * `-o 1...1000` Oldify intensity * `-y` Youngify is a unique feature that blends adult-like features from a source face onto young or childlike target pictures. It's designed to enhance the blend between adult features and a young-looking target face, but does not transform adults into children or make faces appear younger. * `-y 1...1000` Youngify intensity * `-a` ARTIFY enriches the morphing experience by enabling your photorealistic source face to blend seamlessly with a pre-stylized artistic target image. * `-x` Xtreme specially designed for creating ultra-detailed, close-up portraits. - `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used. Place here your callback URL. API will call the provided `replyUrl` once job completed or failed. Maximum length 1024 characters. We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality. Callback body has the same JSON shape as [GET /`jobid`](/docs/api-faceswap-v1/get-faceswap-jobid) response. - `replyRef` is optional, place here your reference id which will be stored and returned along with this job response / result. Maximum length 1024 characters. ##### Responses **200** **200 OK** If field `status` returned as `started` use returned `jobid` to [retrieve InsightFaceSwap job status and results](/docs/api-faceswap-v1/get-faceswap-jobid) or use callback `replyUrl`. Field `content` contains message generated by InsightFaceSwap. Attachments array contains generated images. ```json { "jobid": "<jobid>", "verb": "faceswap-picsi", "status": "completed", "options": "-m", "source_image": { "size": 2438986, "type": "image/png" }, "target_image_gif_or_video": { "size": 1604758, "type": "image/png" }, "created": "2023-09-09T02:04:49.667Z", "updated": "2023-09-09T02:04:53.490Z", "discord": "<ABC…secured…xyz>", "server": "<Discord server id>", "channel": "<Discord channel id>", "replyUrl": "https://webhook.site/abc", "replyRef": "<your optional reference id>", "messageId": "<Discord message id>", "content": "<@Discord user id>", "attachments": [ { "url": "<generated image_1 url>", "proxy_url": "<generated proxy image_1 url>", "width": 2048, "height": 2048, "content_type": "<generated image_1 type>", "id": "<Discord image_1 id>", "filename": "<generated image_1 name>", "size": 7204115 }, { "url": "<generated image_N url>", "proxy_url": "<generated proxy image_N url>", "width": 2048, "height": 2048, "content_type": "<generated image_N type>", "id": "<Discord image id>", "filename": "<generated image_N name>", "size": 7204115 } ], "timestamp": "2023-09-09T02:04:51.926000+00:00", "code": 200 } ``` **400** **400 Bad Request** ```json { "error": "Required param source_image or target_image_gif_or_video is missing or empty" "Param source_image or target_image_gif_or_video is not File or Blob" "Optional param replyUrl or replyRef is too long" "Configuration not found for channel <channel>, to create POST v1/faceswap/account/<channel>" "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **402** **402 Payment Required** ```json { "error": "Account has no subscription or subscription expired", "code": 402 } ``` **412** **412 Insufficient credits** ```json { "error": "Not enough credits: requested 3, available 0", "code": 412 } ``` **429** **429 Too Many Requests** Wait in a loop for **at least** 10..30 seconds and retry again. There are two possible cases for API response 429. 1. API query is full and can not accept new [faceswap/picsi](#insightfaceswap-picsi-command) requests. ```json { "error": "Unable to lock Discord after <attempts> attempts", "code": 429 } ``` 1. The API received an HTTP status 429 from the Discord API when it attempted to POST to the `/interactions` endpoint. Under normal circumstances, this should be a rare occurrence because the API is designed to strictly adhere to Discord rate limits. However, in certain scenarios, Discord may still issue a 429 response. ```json { "error": "Discord /interactions failed with HTTP status 429", "errorDetails": "{\"global\":true,\"message\":\"You are being rate limited.\",\"retry_after\":10}", "code": 429 } ``` ##### Model The job with its `status`: a `completed` job holds the images in `attachments`, and a `started` one is polled with [GET jobs/?jobid=`jobid`](/docs/api-faceswap-v1/get-faceswap-jobid). <details markdown="block" class="model-details"> <summary>The <code>picsi</code> job record, field by field</summary> ```typescript { // TypeScript, all fields are optional jobid: string, verb: 'faceswap-picsi', status: 'started' | 'completed' | 'failed', options: string, source_image: { size: number, type: string }, target_image_gif_or_video: { size: number, type: string }, created: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC updated: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC discord: string, // Provided for debugging purposes only, contains the first 3 and the last 3 characters of the original value server: string, channel: string, replyUrl: string, replyRef: string, messageId: string, content: string, // Contains message generated by InsightFaceSwap attachments: [ { id: string, content_type: string, filename: string, url: string, proxy_url: string, size: number, width: number, height: number } ], timestamp: string, error: string, errorDetails: string, code: number } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Authorization: Bearer …" \ -X POST https://api.useapi.net/v1/faceswap/picsi \ -F "options=<options>" \ -F 'source_image=@"<Path to the source_image>"' \ -F 'target_image_gif_or_video=@"<Path to the target_image_gif_or_video>"' ``` **JavaScript** ``` javascript const main = async () => { const apiUrl = "https://api.useapi.net/v1/faceswap/picsi"; const token = "API token"; const options = "options"; const channel = "Discord channel"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${token}` } }; const formData = new FormData(); formData.append("options", options); formData.append("channel", channel); /* // Example 1: Fetch image from URL const imageUrl = "https://upload.wikimedia.org/wikipedia/commons/7/7d/Mona_Lisa_color_restoration.jpg"; const responseImage = await fetch(imageUrl); formData.append("source_image", await responseImage.blob()); */ /* // Example 2: Load image from local file (Blob) const fsp = require('fs').promises; const imageFileName = "./target_photo.png"; const blob = new Blob([await fsp.readFile(imageFileName)]); formData.append("target_image_gif_or_video", blob); */ /* // Example 3: Load from input file html element // <input id="target-photo-image-file" type="file"> const imageFile = document.getElementById(`target-photo-image-file`); if (imageFile.files[0]) formData.append("target_image_gif_or_video", imageFile.files[0]); */ data.body = formData; const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", { response, result }); }; main() ``` **Python** ``` python import requests api_url = "https://api.useapi.net/v1/faceswap/picsi" token = "API token" options = "options" channel = "Discord channel" headers = { 'Authorization': f'Bearer {token}' } files = { 'options': (None, options), 'channel': (None, channel) } # # Example 1: Fetch image from URL # image_url = "https://upload.wikimedia.org/wikipedia/commons/7/7d/Mona_Lisa_color_restoration.jpg" # response_image = requests.get(image_url) # image_content = response_image.content # files['source_image'] = ('image.jpg', image_content, 'image/jpeg') # # Example 2: Load image from local file # image_file_path = "./target_photo.png" # with open(image_file_path, 'rb') as image_file: # files['target_image_gif_or_video'] = ('target_photo.png', image_file.read(), 'image/png') response = requests.post(api_url, headers=headers, files=files) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-saveid === Document URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-saveid --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> faceswap/saveid description: "Upload and register a named face ID image via POST faceswap/saveid in the useapi.net InsightFaceSwap API v1 — required before swapping faces with /swapid." parent: InsightFaceSwap API nav_order: 600 --- ## InsightFaceSwap [/saveid](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#saveid-name-upload-id-image) command --- Use this endpoint to submit the InsightFaceSwap [/saveid](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#saveid-name-upload-id-image) command to your [InsightFaceSwap Discord channel](/docs/start-here/setup-faceswap). The result will be returned in the response body and can also be sent as a callback to an optional [`replyUrl`](#request-body). This is a blocking call, you will **not** be able to make another call to the same InsightFaceSwap Discord channel until the current call is completed. The average execution time is approximately 3 to 10 seconds. If you expect high load and need to make multiple concurrent calls, please consider setting up [multiple InsightFaceSwap accounts](/docs/api-faceswap-v1/post-faceswap-account-channel). It is **important** not to use the InsightFaceSwap account setup for API access for any purposes other than its intended use, such as executing `/saveid` or any other InsightFaceSwap commands _manually_ or in conjunction with _any other_ automation tools. The useapi.net API internally tracks the usage of the InsightFaceSwap account, including the number of currently active executions. Using it for other activities may cause API to function incorrectly. > **https://api.useapi.net/v1/faceswap/saveid** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "channel": "Discord channel id", "idname": "idname param", "image": "Image File or Blob" } ``` - `channel` is optional when only one [faceswap/account](/docs/api-faceswap-v1/get-faceswap-account) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `idname` is **required**, please refer to InsightFaceSwap [/saveid](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#saveid-name-upload-id-image) for details. - `image` is **required**, image to upload and register for subsequent facial replacement and editing. Must be either a [File](https://developer.mozilla.org/en-US/docs/Web/API/File) or [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob) object when included in this [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData) POST request. - `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used. Place here your callback URL. API will call the provided `replyUrl` once job completed or failed. Maximum length 1024 characters. We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality. Callback body has the same JSON shape as [GET /`jobid`](/docs/api-faceswap-v1/get-faceswap-jobid) response. - `replyRef` is optional, place here your reference id which will be stored and returned along with this job response / result. Maximum length 1024 characters. ##### Responses **200** **200 OK** Field `content` contains message generated by InsightFaceSwap. ```json { "jobid": "<jobid>", "verb": "faceswap-saveid", "status": "completed", "idname": "me", "image": { "size": 1699405, "type": "image/png" }, "created": "2023-09-09T02:04:49.667Z", "updated": "2023-09-09T02:04:53.490Z", "discord": "<ABC…secured…xyz>", "server": "<Discord server id>", "channel": "<Discord channel id>", "replyUrl": "https://webhook.site/abc", "replyRef": "<your optional reference id>", "messageId": "<Discord message id>", "content": "idname me created", "timestamp": "2023-09-09T02:04:51.926000+00:00", "code": 200 } ``` **400** **400 Bad Request** ```json { "error": "Required param idname is missing or empty" "Required param image is missing or empty" "Param image is not File or Blob" "Optional param replyRef is too long" "Optional param replyUrl is too long" "Required param channel is missing or empty" "Configuration not found for channel <channel>, to create POST v1/faceswap/account/<channel>" "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **402** **402 Payment Required** ```json { "error": "Account has no subscription or subscription expired", "code": 402 } ``` **429** **429 Too Many Requests** Wait in a loop for **at least** 10..30 seconds and retry again. There are two possible cases for API response 429. 1. API query is full and can not accept new [faceswap/saveid](#insightfaceswap-saveid-command) requests. ```json { "error": "Unable to lock Discord after <attempts> attempts", "code": 429 } ``` 2. The API received an HTTP status 429 from the Discord API when it attempted to POST to the `/interactions` endpoint. Under normal circumstances, this should be a rare occurrence because the API is designed to strictly adhere to Discord rate limits. However, in certain scenarios, Discord may still issue a 429 response. ```json { "error": "Discord /interactions failed with HTTP status 429", "errorDetails": "{\"global\":true,\"message\":\"You are being rate limited.\",\"retry_after\":10}", "code": 429 } ``` ##### Model The finished job with its `status`, the `idname` and InsightFaceSwap's reply in `content`. <details markdown="block" class="model-details"> <summary>The <code>saveid</code> job record, field by field</summary> ```typescript { // TypeScript, all fields are optional jobid: string, verb: 'faceswap-saveid', status: 'completed' | 'failed', idname: string, image: { size: number, type: string }, created: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC updated: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC discord: string, // Provided for debugging purposes only, contains the first 3 and the last 3 characters of the original value server: string, channel: string, replyUrl: string, replyRef: string, messageId: string, content: string, // Contains message generated by InsightFaceSwap timestamp: string, error: string, errorDetails: string, code: number } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Authorization: Bearer …" \ -X POST https://api.useapi.net/v1/faceswap/saveid \ -F "channel=<Discord channel id>" \ -F 'image=@"<Path to the image>"' \ -F "idname=<idname>" ``` **JavaScript** ``` javascript const main = async () => { const apiUrl = "https://api.useapi.net/v1/faceswap/saveid"; const token = "API token"; const idname = "idname"; const channel = "Discord channel"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${token}` } }; const formData = new FormData(); formData.append("idname", idname); formData.append("channel", channel); /* // Example 1: Fetch image from URL const imageUrl = "https://upload.wikimedia.org/wikipedia/commons/7/7d/Mona_Lisa_color_restoration.jpg"; const responseImage = await fetch(imageUrl); formData.append("image", await responseImage.blob()); */ /* // Example 2: Load image from local file (Blob) const fsp = require('fs').promises; const imageFileName = "./my_photo.png"; const blob = new Blob([await fsp.readFile(imageFileName)]); formData.append("image", blob); */ /* // Example 3: Load from input file html element // <input id="my-photo-image-file" type="file"> const imageFile = document.getElementById(`my-photo-image-file`); if (imageFile.files[0]) formData.append("image", imageFile.files[0]); */ data.body = formData; const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", { response, result }); }; main() ``` **Python** ``` python import requests api_url = "https://api.useapi.net/v1/faceswap/saveid" token = "API token" idname = "idname" channel = "Discord channel" headers = { 'Authorization': f'Bearer {token}' } files = { 'idname': (None, idname), 'channel': (None, channel) } # # Example 1: Fetch image from URL # image_url = "https://upload.wikimedia.org/wikipedia/commons/7/7d/Mona_Lisa_color_restoration.jpg" # response_image = requests.get(image_url) # image_content = response_image.content # files['image'] = ('image.jpg', image_content, 'image/jpeg') # # Example 2: Load image from local file # image_file_path = "./my_photo.png" # with open(image_file_path, 'rb') as image_file: # files['image'] = ('my_photo.png', image_file.read(), 'image/png') response = requests.post(api_url, headers=headers, files=files) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-setid === Document URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-setid --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> faceswap/setid description: "Set the current active face ID (idname) for the InsightFaceSwap channel via POST faceswap/setid in the useapi.net InsightFaceSwap API v1 — wraps the /setid Discord command." parent: InsightFaceSwap API nav_order: 1000 --- ## InsightFaceSwap [/setid](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#setid-nameprefer) command --- Use this endpoint to submit the InsightFaceSwap [/setid](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#setid-nameprefer) command to your [InsightFaceSwap Discord channel](/docs/start-here/setup-faceswap). The result will be returned in the response body and can also be sent as a callback to an optional [`replyUrl`](#request-body). This is a blocking call, you will **not** be able to make another call to the same InsightFaceSwap Discord channel until the current call is completed. The average execution time is approximately 3 to 10 seconds. If you expect high load and need to make multiple concurrent calls, please consider setting up [multiple InsightFaceSwap accounts](/docs/api-faceswap-v1/post-faceswap-account-channel). It is **important** not to use the InsightFaceSwap account setup for API access for any purposes other than its intended use, such as executing `/setid` or any other InsightFaceSwap commands _manually_ or in conjunction with _any other_ automation tools. The useapi.net API internally tracks the usage of the InsightFaceSwap account, including the number of currently active executions. Using it for other activities may cause API to function incorrectly. > **https://api.useapi.net/v1/faceswap/setid** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "channel": "Discord channel id", "idname": "idname param", } ``` - `channel` is optional when only one [faceswap/account](/docs/api-faceswap-v1/get-faceswap-account) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `idname` is **required**, please refer to InsightFaceSwap [/setid](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#setid-nameprefer) for details. - `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used. Place here your callback URL. API will call the provided `replyUrl` once job completed or failed. Maximum length 1024 characters. We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality. Callback body has the same JSON shape as [GET /`jobid`](/docs/api-faceswap-v1/get-faceswap-jobid) response. - `replyRef` is optional, place here your reference id which will be stored and returned along with this job response / result. Maximum length 1024 characters. ##### Responses **200** **200 OK** Field `content` contains message generated by InsightFaceSwap. ```json { "jobid": "<jobid>", "verb": "faceswap-setid", "status": "completed", "idname": "me", "created": "2023-09-09T02:04:49.667Z", "updated": "2023-09-09T02:04:53.490Z", "discord": "<ABC…secured…xyz>", "server": "<Discord server id>", "channel": "<Discord channel id>", "replyUrl": "https://webhook.site/abc", "replyRef": "<your optional reference id>", "messageId": "<Discord message id>", "content": "current idname updated", "timestamp": "2023-09-09T02:04:51.926000+00:00", "code": 200 } ``` **400** **400 Bad Request** ```json { "error": "Required param idname is missing or empty" "Optional param replyRef is too long" "Optional param replyUrl is too long" "Required param channel is missing or empty" "Configuration not found for channel <channel>, to create POST v1/faceswap/account/<channel>" "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **402** **402 Payment Required** ```json { "error": "Account has no subscription or subscription expired", "code": 402 } ``` **429** **429 Too Many Requests** Wait in a loop for **at least** 10..30 seconds and retry again. There are two possible cases for API response 429. 1. API query is full and can not accept new [faceswap/setid](#insightfaceswap-setid-command) requests. ```json { "error": "Unable to lock Discord after <attempts> attempts", "code": 429 } ``` 2. The API received an HTTP status 429 from the Discord API when it attempted to POST to the `/interactions` endpoint. Under normal circumstances, this should be a rare occurrence because the API is designed to strictly adhere to Discord rate limits. However, in certain scenarios, Discord may still issue a 429 response. ```json { "error": "Discord /interactions failed with HTTP status 429", "errorDetails": "{\"global\":true,\"message\":\"You are being rate limited.\",\"retry_after\":10}", "code": 429 } ``` ##### Model The finished job with its `status`, the `idname` and InsightFaceSwap's reply in `content`. <details markdown="block" class="model-details"> <summary>The <code>setid</code> job record, field by field</summary> ```typescript { // TypeScript, all fields are optional jobid: string, verb: 'faceswap-setid', status: 'completed' | 'failed', idname: string, created: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC updated: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC discord: string, // Provided for debugging purposes only, contains the first 3 and the last 3 characters of the original value server: string, channel: string, replyUrl: string, replyRef: string, messageId: string, content: string, // Contains message generated by InsightFaceSwap timestamp: string, error: string, errorDetails: string, code: number } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Authorization: Bearer …" \ -X POST https://api.useapi.net/v1/faceswap/setid \ -F "channel=<Discord channel id>" \ -F "idname=<idname>" ``` **JavaScript** ``` javascript const main = async () => { const apiUrl = "https://api.useapi.net/v1/faceswap/setid"; const token = "API token"; const channel = "Discord channel"; const idname = "idname"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${token}` } }; const formData = new FormData(); formData.append("channel", channel); formData.append("idname", idname); data.body = formData; const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", { response, result }); }; main() ``` **Python** ``` python import requests api_url = "https://api.useapi.net/v1/faceswap/setid" token = "API token" channel = "Discord channel" idname = "idname" headers = { 'Authorization': f'Bearer {token}' } files = { 'channel': (None, channel), 'idname': (None, idname) } response = requests.post(api_url, headers=headers, files=files) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-swapid === Document URL: https://useapi.net/docs/api-faceswap-v1/post-faceswap-swapid --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> faceswap/swapid description: "Swap a saved face ID onto a target image via POST faceswap/swapid in the useapi.net InsightFaceSwap API v1 — parameters, responses, and a live Try It console." parent: InsightFaceSwap API nav_order: 700 --- ## InsightFaceSwap [/swapid](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#swapid-names-upload-image) command February 12, 2024 (November 16, 2026) --- Use this endpoint to submit the InsightFaceSwap [/swapid](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#swapid-names-upload-image) command to your [InsightFaceSwap Discord channel](/docs/start-here/setup-faceswap). The result will be returned in the response body and can also be sent as a callback to an optional [`replyUrl`](#request-body). This is a blocking call, you will **not** be able to make another call to the same InsightFaceSwap Discord channel until the current call is completed. The average execution time is approximately 3 to 10 seconds. If you expect high load and need to make multiple concurrent calls, please consider setting up [multiple InsightFaceSwap accounts](/docs/api-faceswap-v1/post-faceswap-account-channel). It is **important** not to use the InsightFaceSwap account setup for API access for any purposes other than its intended use, such as executing `/swapid` or any other InsightFaceSwap commands _manually_ or in conjunction with _any other_ automation tools. The useapi.net API internally tracks the usage of the InsightFaceSwap account, including the number of currently active executions. Using it for other activities may cause API to function incorrectly. > **https://api.useapi.net/v1/faceswap/swapid** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "channel": "Discord channel id", "idname": "idname param", "image": "Image File or Blob" } ``` - `channel` is optional when only one [faceswap/account](/docs/api-faceswap-v1/get-faceswap-account) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `idname` is **required**, please refer to InsightFaceSwap [/swapid](https://github.com/deepinsight/insightface/blob/master/web-demos/swapping_discord/README.md#swapid-names-upload-image) for details. - `image` is **required**, target image to be uploaded for replacing the face identified by the `idname` parameter mentioned above. Must be either a [File](https://developer.mozilla.org/en-US/docs/Web/API/File) or [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob) object when included in this [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData) POST request. - `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used. Place here your callback URL. API will call the provided `replyUrl` once job completed or failed. Maximum length 1024 characters. We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality. Callback body has the same JSON shape as [GET /`jobid`](/docs/api-faceswap-v1/get-faceswap-jobid) response. - `replyRef` is optional, place here your reference id which will be stored and returned along with this job response / result. Maximum length 1024 characters. ##### Responses **200** **200 OK** Field `content` contains message generated by InsightFaceSwap. Attachments array contains generated image. ```json { "jobid": "<jobid>", "verb": "faceswap-swapid", "status": "completed", "idname": "me", "image": { "size": 1699405, "type": "image/png" }, "created": "2023-09-09T02:04:49.667Z", "updated": "2023-09-09T02:04:53.490Z", "discord": "<ABC…secured…xyz>", "server": "<Discord server id>", "channel": "<Discord channel id>", "replyUrl": "https://webhook.site/abc", "replyRef": "<your optional reference id>", "messageId": "<Discord message id>", "content": "Picsi.Ai ver.2.0 [SaveID: 'me'] [<@Discord user id>] (79/200 credits used)", "attachments": [ { "url": "<generated image url>", "proxy_url": "<generated proxy image url>", "width": 2048, "height": 2048, "content_type": "<generated image type>", "id": "<Discord image id>", "filename": "<generated image name>", "size": 7204115 } ], "timestamp": "2023-09-09T02:04:51.926000+00:00", "code": 200 } ``` **400** **400 Bad Request** ```json { "error": "Required param idname is missing or empty" "Required param image is missing or empty" "Param image is not File or Blob" "Optional param replyRef is too long" "Optional param replyUrl is too long" "Required param channel is missing or empty" "Configuration not found for channel <channel>, to create POST v1/faceswap/account/<channel>" "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **402** **402 Payment Required** ```json { "error": "Account has no subscription or subscription expired", "code": 402 } ``` **412** **412 Insufficient credits** ```json { "error": "Not enough credits: requested 3, available 0", "code": 412 } ``` **429** **429 Too Many Requests** Wait in a loop for **at least** 10..30 seconds and retry again. There are two possible cases for API response 429. 1. API query is full and can not accept new [faceswap/swapid](#insightfaceswap-swapid-command) requests. ```json { "error": "Unable to lock Discord after <attempts> attempts", "code": 429 } ``` 2. The API received an HTTP status 429 from the Discord API when it attempted to POST to the `/interactions` endpoint. Under normal circumstances, this should be a rare occurrence because the API is designed to strictly adhere to Discord rate limits. However, in certain scenarios, Discord may still issue a 429 response. ```json { "error": "Discord /interactions failed with HTTP status 429", "errorDetails": "{\"global\":true,\"message\":\"You are being rate limited.\",\"retry_after\":10}", "code": 429 } ``` ##### Model The finished job with its `status`, InsightFaceSwap's reply in `content` and the generated image in `attachments`. <details markdown="block" class="model-details"> <summary>The <code>swapid</code> job record, field by field</summary> ```typescript { // TypeScript, all fields are optional jobid: string, verb: 'faceswap-swapid', status: 'completed' | 'failed', idname: string, image: { size: number, type: string }, created: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC updated: string, // YYYY-MM-DDTHH:mm:ss.sssZ, IS0 8601, UTC discord: string, // Provided for debugging purposes only, contains the first 3 and the last 3 characters of the original value server: string, channel: string, replyUrl: string, replyRef: string, messageId: string, content: string, // Contains message generated by InsightFaceSwap attachments: [ { id: string, content_type: string, filename: string, url: string, proxy_url: string, size: number, width: number, height: number } ], timestamp: string, error: string, errorDetails: string, code: number } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Authorization: Bearer …" \ -X POST https://api.useapi.net/v1/faceswap/swapid \ -F "channel=<Discord channel id>" \ -F 'image=@"<Path to the image>"' \ -F "idname=<idname>" ``` **JavaScript** ``` javascript const main = async () => { const apiUrl = "https://api.useapi.net/v1/faceswap/swapid"; const token = "API token"; const idname = "idname"; const channel = "Discord channel"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${token}` } }; const formData = new FormData(); formData.append("idname", idname); formData.append("channel", channel); /* // Example 1: Fetch image from URL const imageUrl = "https://upload.wikimedia.org/wikipedia/commons/7/7d/Mona_Lisa_color_restoration.jpg"; const responseImage = await fetch(imageUrl); formData.append("image", await responseImage.blob()); */ /* // Example 2: Load image from local file (Blob) const fsp = require('fs').promises; const imageFileName = "./target_photo.png"; const blob = new Blob([await fsp.readFile(imageFileName)]); formData.append("image", blob); */ /* // Example 3: Load from input file html element // <input id="target-photo-image-file" type="file"> const imageFile = document.getElementById(`target-photo-image-file`); if (imageFile.files[0]) formData.append("image", imageFile.files[0]); */ data.body = formData; const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", { response, result }); }; main() ``` **Python** ``` python import requests api_url = "https://api.useapi.net/v1/faceswap/swapid" token = "API token" idname = "idname" channel = "Discord channel" headers = { 'Authorization': f'Bearer {token}' } files = { 'idname': (None, idname), 'channel': (None, channel) } # # Example 1: Fetch image from URL # image_url = "https://upload.wikimedia.org/wikipedia/commons/7/7d/Mona_Lisa_color_restoration.jpg" # response_image = requests.get(image_url) # image_content = response_image.content # files['image'] = ('image.jpg', image_content, 'image/jpeg') # # Example 2: Load image from local file # image_file_path = "./target_photo.png" # with open(image_file_path, 'rb') as image_file: # files['image'] = ('target_photo.png', image_file.read(), 'image/png') response = requests.post(api_url, headers=headers, files=files) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-faceswap-v1/setup-multiple-faceswap-accounts === Document URL: https://useapi.net/docs/api-faceswap-v1/setup-multiple-faceswap-accounts --- layout: default title: Setup multiple accounts nav_icon: users description: "Configure multiple InsightFaceSwap Discord accounts for automatic load balancing in the useapi.net InsightFaceSwap API v1 — step-by-step setup guide." parent: InsightFaceSwap API nav_order: 6000 --- ## How to use multiple InsightFaceSwap accounts Before you start using the API, you **must** [configure](/docs/start-here/setup-faceswap) at least one InsightFaceSwap Discord [faceswap/account](/docs/api-faceswap-v1/get-faceswap-account). You may specify multiple InsightFaceSwap accounts, the API will automatically perform load balancing by randomly selecting an account with available credits before making calls to InsightFaceSwap Discord bot. To take advantage of saved configurations and account load balancing, please follow these simple steps: - Gather your InsightFaceSwap account(s) information as outlined at [Setup InsightFaceSwap](/docs/start-here/setup-faceswap). - Post your configuration(s) using the [faceswap/account/`channel`](/docs/api-faceswap-v1/post-faceswap-account-channel) endpoint. To see all your currently configured InsightFaceSwap accounts, please use the [faceswap/account](/docs/api-faceswap-v1/get-faceswap-account) endpoint. Feel free to [reach out to us](/docs/support) if you have any questions or concerns. === URL: https://useapi.net/docs/start-here/setup-flowmusic === Document URL: https://useapi.net/docs/start-here/setup-flowmusic --- layout: default title: Setup Flow Music description: "How to set up FlowMusic for the useapi.net API — connect your account and start generating via the API." parent: Start Here nav_order: 250 permalink: /docs/start-here/setup-flowmusic --- # <img style="height:1em;vertical-align: middle;" src="/assets/images/google-flow-music-logo.jpg" alt=""> Setup Flow Music June 3, 2026 (November 9, 2026) ## Table of contents Approximately 5 minutes to complete setup steps. --- > This is the setup guide for [Flow Music API](/docs/api-flowmusic-v1). A [Flow Music](https://www.flowmusic.app) account (Google sign-in) and a [useapi.net subscription](/docs/subscription) are required for the API to work. If the Google account has Google AI Plus, Pro or Ultra, sign in at flowmusic.app once and allow it to see your Google One membership: the account then gets the Flow Music plan included with it (Starter on [Plus](https://support.google.com/googleone/answer/16882689), Plus on [Pro](https://support.google.com/googleone/answer/14534406), Member on [Ultra](https://support.google.com/googleone/answer/16286513)). Do that before you add the account here, or add it again afterwards, so useapi.net reads the new plan. ### Automated setup (recommended) Use our guided browser setup to configure your account automatically — no DevTools or token copying needed. Enter your API token, sign in with Google in the remote browser, and your account is ready. [Open automated setup](/assets/setup-browser/flowmusic.html) Prefer manual setup? Continue with the steps below. --- [Flow Music](https://www.flowmusic.app) is [Google Labs](https://labs.google)' AI music generator, powered by the [Lyria 3 Pro](https://deepmind.google/models/lyria/) model (formerly Producer AI, originally [Riffusion](https://www.riffusion.com)). It creates complete, fully-produced songs — vocals, melody, and arrangement — from a text prompt, and can also cover/restyle songs, adjust lyrics in place, extend or replace sections, and apply audio effects. Flow Music signs you in with your Google account and keeps the session — including a **refresh token** — in your browser. To use the API you copy that refresh token and register it with [POST /accounts](/docs/api-flowmusic-v1/post-flowmusic-accounts); useapi.net then calls Flow Music on your behalf and refreshes the token automatically. Each [useapi.net subscription](/docs/subscription) lets you connect 3 Flow Music accounts, up to 100 in total. ### Sign in to Flow Music * Navigate to [https://www.flowmusic.app](https://www.flowmusic.app) * Sign in with your Google account. We **strongly recommend** using a dedicated Google account for the API — not your personal Gmail. * Generate at least one song, and upload at least one image **and** one audio file. Doing each once in the browser dismisses Flow Music's first-use consent dialogs. ### Copy your refresh token 1. Open [https://www.flowmusic.app](https://www.flowmusic.app) <span style="color: red;">`1`</span> and make sure you're **signed out** (sign out if you're already signed in). 2. Open browser DevTools (**F12**) and select the **Network** tab <span style="color: red;">`2`</span>. 3. Click **Login** <span style="color: red;">`3`</span> and sign in with Google — this triggers a fresh token exchange. (The screenshot shows that button as **New session** because it changes to that once sign-in completes.) 4. In the Network filter box, type `sb.flowmusic.app/auth/v1/token` <span style="color: red;">`4`</span>. 5. Click the `token?grant_type=pkce` request that appears <span style="color: red;">`5`</span>. 6. Open the **Response** tab and copy the value of `refresh_token` <span style="color: red;">`6`</span>. ![](/assets/images/flowmusic-setup-1.jpg) **Important — manual setup only:** once the account is added to the API, **clear Flow Music's cookies** in your browser (or just close it and stop using Flow Music there). **Do not sign out** — signing out revokes the refresh token and disables the API account. Also don't keep browsing Flow Music there, or it will refresh the token itself and rotate it away from the API. Let the API fully manage the session from here on. The [automated setup](#automated-setup-recommended) handles all of this for you — it captures the token in a throwaway remote browser with no lingering session, so it's strongly preferred. If an account later stops working, repeat these steps and re-run [POST /accounts](/docs/api-flowmusic-v1/post-flowmusic-accounts). ### Verify and add account Paste your API token and the `refresh_token` below to register the account — you should receive a `201` (new) or `200` (updated) response. You can also call [POST /accounts](/docs/api-flowmusic-v1/post-flowmusic-accounts) directly. <script> async function apiTestSetupFlowMusic() { const data = { method: 'POST', headers: { 'Authorization': `Bearer ${document.getElementById('setup-accounts-FlowMusic-token').value}`, 'Content-Type': 'application/json' } }; let refresh_token = document.getElementById(`setup-accounts-FlowMusic-refresh_token`)?.value; data.body = JSON.stringify({ refresh_token }); await apiExecute(`https://api.useapi.net/v1/flowmusic/accounts`, 'setup-accounts-FlowMusic', data); } </script> <form id="setup-accounts-FlowMusic" onsubmit="return false;" class="input-form"> <div class="input-field"> <div class="input-field-row"> <label for="setup-accounts-FlowMusic-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="setup-accounts-FlowMusic-token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> <label for="setup-accounts-FlowMusic-refresh_token"><span>refresh_token</span> <textarea id="setup-accounts-FlowMusic-refresh_token" class="input-element" rows="3" required aria-required="true" style="resize: both;"></textarea> </label> </div> <button id="setup-accounts-FlowMusic-button" class="btn btn-primary fs-3" type="submit" onclick="apiTestSetupFlowMusic()">Go</button> </div> </form> <div id="setup-accounts-FlowMusic-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-flowmusic-v1/delete-flowmusic-accounts-email === Document URL: https://useapi.net/docs/api-flowmusic-v1/delete-flowmusic-accounts-email --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> accounts/`email` description: "Remove a configured Flow Music account by email via DELETE accounts/email in the useapi.net FlowMusic API v1 — unlinks the refresh token and frees the account slot." parent: Flow Music API nav_order: 140 permalink: /docs/api-flowmusic-v1/delete-flowmusic-accounts-email --- ## Remove an account June 3, 2026 --- Remove a configured Flow Music account from your useapi.net account. > **https://api.useapi.net/v1/flowmusic/accounts/`email`** - `email` is URL-encoded in the path. ### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Responses **204** **204 No Content** — the account was deleted. The response body is empty. **401** **401 Unauthorized** — invalid API token. **404** **404** — account not configured. ### Examples **Curl** ``` bash curl -X DELETE -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v1/flowmusic/accounts/user@email.com" ``` **Python** ``` python import requests, urllib.parse email = 'user@email.com' r = requests.delete('https://api.useapi.net/v1/flowmusic/accounts/' + urllib.parse.quote(email, safe=''), headers={'Authorization': 'Bearer YOUR_API_TOKEN'}) print(r.status_code) # 204 No Content (empty body) ``` ### Try It <script> async function apiTestDeleteAccountsEmailFlowMusic() { const data = { method: 'DELETE', headers: { 'Authorization': `Bearer ${document.getElementById('delete-accounts-email-FlowMusic-token').value}` } }; let email = document.getElementById(`delete-accounts-email-FlowMusic-email`)?.value; const url = `https://api.useapi.net/v1/flowmusic/accounts/${encodeURIComponent(email)}`; await apiExecute(url, 'delete-accounts-email-FlowMusic', data); } </script> <form id="delete-accounts-email-FlowMusic" onsubmit="return false;" class="input-form"> <div class="input-field"> <div class="input-field-row"> <label for="delete-accounts-email-FlowMusic-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="delete-accounts-email-FlowMusic-token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> <label for="delete-accounts-email-FlowMusic-email"><span>email</span> <input id="delete-accounts-email-FlowMusic-email" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> </div> <button id="delete-accounts-email-FlowMusic-button" class="btn btn-primary fs-3" type="submit" onclick="apiTestDeleteAccountsEmailFlowMusic()">Go</button> </div> </form> <div id="delete-accounts-email-FlowMusic-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-flowmusic-v1/delete-flowmusic-jobs-jobid === Document URL: https://useapi.net/docs/api-flowmusic-v1/delete-flowmusic-jobs-jobid --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> jobs/`jobid` description: "Cancel a running job and free its concurrency slot via DELETE jobs/jobid in the useapi.net FlowMusic API v1 — marks the record as failed with user_cancelled." parent: Flow Music API nav_order: 420 permalink: /docs/api-flowmusic-v1/delete-flowmusic-jobs-jobid --- ## Cancel a job June 3, 2026 (November 9, 2026) --- Cancel a running job (async, or a sync request still in progress, which then answers `409` `user_cancelled`) and free its concurrency slot. The job record is marked `failed` with error code `user_cancelled` (terminal records are simply removed from the running set). > **https://api.useapi.net/v1/flowmusic/jobs/`jobid`** - `jobid` is URL-encoded in the path. ### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Responses **204** **204 No Content** — cancelled (or slot already freed). No body. **401** **401 Unauthorized** — invalid API token. **403** **403** — the jobid does not belong to your account. **404** **404** — no job with that id. ### Model A successful cancel returns `204 No Content` with no body. Only the error responses (`403` / `404`) carry a JSON `{ error, code }`. ### Examples **Curl** ``` bash JOBID="job:56ef7890-...-bot:flowmusic" curl -X DELETE -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v1/flowmusic/jobs/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$JOBID")" ``` **Python** ``` python import requests, urllib.parse jobid = 'job:56ef7890-...-bot:flowmusic' r = requests.delete('https://api.useapi.net/v1/flowmusic/jobs/' + urllib.parse.quote(jobid, safe=''), headers={'Authorization': 'Bearer YOUR_API_TOKEN'}) print(r.status_code) # 204 ``` ### Try It <script> async function apiTestDeleteJobsJobidFlowMusic() { const data = { method: 'DELETE', headers: { 'Authorization': `Bearer ${document.getElementById('delete-jobs-jobid-FlowMusic-token').value}` } }; let jobid = document.getElementById(`delete-jobs-jobid-FlowMusic-jobid`)?.value; const url = `https://api.useapi.net/v1/flowmusic/jobs/${encodeURIComponent(jobid)}`; await apiExecute(url, 'delete-jobs-jobid-FlowMusic', data); } </script> <form id="delete-jobs-jobid-FlowMusic" onsubmit="return false;" class="input-form"> <div class="input-field"> <div class="input-field-row"> <label for="delete-jobs-jobid-FlowMusic-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="delete-jobs-jobid-FlowMusic-token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> <label for="delete-jobs-jobid-FlowMusic-jobid"><span>jobid</span> <input id="delete-jobs-jobid-FlowMusic-jobid" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> </div> <button id="delete-jobs-jobid-FlowMusic-button" class="btn btn-primary fs-3" type="submit" onclick="apiTestDeleteJobsJobidFlowMusic()">Go</button> </div> </form> <div id="delete-jobs-jobid-FlowMusic-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-flowmusic-v1/get-flowmusic-accounts-email === Document URL: https://useapi.net/docs/api-flowmusic-v1/get-flowmusic-accounts-email --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts/`email` description: "Retrieve a configured Flow Music account's details by email via GET accounts/email in the useapi.net FlowMusic API v1, including token state and concurrency settings." parent: Flow Music API nav_order: 120 permalink: /docs/api-flowmusic-v1/get-flowmusic-accounts-email --- ## Get one account June 3, 2026 (November 16, 2026) --- Get the detail for a single configured account. > **https://api.useapi.net/v1/flowmusic/accounts/`email`** - `email` is the account's email address (URL-encoded in the path). ### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Responses **200** **200 OK** ```json { "email": "user@email.com", "tier": "plus", "subscription_plan": "plus-monthly", "provider": "g1_entitlement", "user_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", "maxJobs": 12, "added": "2026-06-01T12:00:00.000Z", "refreshed_at": "2026-06-01T12:00:00.000Z", "refreshed_count": 0, "access_token": "eyJ…redacted…zmQ", "access_token_expires_at": "2026-06-01T13:00:00.000Z", "refresh_token": "l6e…redacted…z4v", "session_id": "f0e1d2c3-b4a5-4768-9a0b-1c2d3e4f5a6b", "credits_remaining": 5000, "tokens_remaining": 60000 } ``` - `tier` is the account's Flow Music plan. useapi.net re-reads it when the account's login refreshes (about hourly while the account is in use) and on every call to this endpoint. A plan you claim through Google AI, or an upgrade, raises `maxJobs` to that plan's default, unless you set `maxJobs` yourself with [POST /accounts](/docs/api-flowmusic-v1/post-flowmusic-accounts). To apply a change right away, call this endpoint once. The plan included with [Google AI Plus](https://support.google.com/googleone/answer/16882689), [Pro](https://support.google.com/googleone/answer/14534406) or [Ultra](https://support.google.com/googleone/answer/16286513) reads as `starter`, `plus` or `member`. - `credits_remaining` and `tokens_remaining` are live-pulled from Flow Music on every request, so they are always current. They are returned only for a healthy account — an account in an error state (`error` present) omits them because its balance can't be queried. **401** **401 Unauthorized** — invalid API token. **404** **404** — account not configured. ### Model The account record with its tier, `maxJobs` and redacted tokens, plus the live `credits_remaining` and `tokens_remaining` of a healthy account. <details markdown="block" class="model-details"> <summary>The account record with its live balance, field by field</summary> ```typescript { email: string tier: 'free' | 'starter' | 'plus' | 'member' | 'unknown' subscription_plan?: string // paid tiers only provider?: string // paid tiers only user_id: string // the account's user UUID maxJobs: number added: string // ISO 8601 timestamp refreshed_at: string // ISO 8601 timestamp refreshed_count: number access_token: string // redacted access_token_expires_at: string // ISO 8601 timestamp refresh_token: string // redacted session_id: string error?: string // present only when the account needs re-authentication credits_remaining?: number | null // live-pulled per request; present only for a healthy account tokens_remaining?: number | null // live-pulled per request; present only for a healthy account } ``` </details> ### Examples **Curl** ``` bash curl -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v1/flowmusic/accounts/user@email.com" ``` **Python** ``` python import requests, urllib.parse email = 'user@email.com' r = requests.get('https://api.useapi.net/v1/flowmusic/accounts/' + urllib.parse.quote(email, safe=''), headers={'Authorization': 'Bearer YOUR_API_TOKEN'}) print(r.status_code, r.json()) ``` ### Try It <script> async function apiTestGetAccountsEmailFlowMusic() { const data = { method: 'GET', headers: { 'Authorization': `Bearer ${document.getElementById('get-accounts-email-FlowMusic-token').value}` } }; let email = document.getElementById(`get-accounts-email-FlowMusic-email`)?.value; const url = `https://api.useapi.net/v1/flowmusic/accounts/${encodeURIComponent(email)}`; await apiExecute(url, 'get-accounts-email-FlowMusic', data); } </script> <form id="get-accounts-email-FlowMusic" onsubmit="return false;" class="input-form"> <div class="input-field"> <div class="input-field-row"> <label for="get-accounts-email-FlowMusic-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="get-accounts-email-FlowMusic-token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> <label for="get-accounts-email-FlowMusic-email"><span>email</span> <input id="get-accounts-email-FlowMusic-email" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> </div> <button id="get-accounts-email-FlowMusic-button" class="btn btn-primary fs-3" type="submit" onclick="apiTestGetAccountsEmailFlowMusic()">Go</button> </div> </form> <div id="get-accounts-email-FlowMusic-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-flowmusic-v1/get-flowmusic-accounts-usage === Document URL: https://useapi.net/docs/api-flowmusic-v1/get-flowmusic-accounts-usage --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts/usage description: "Retrieve credit and token usage for a Flow Music account via GET accounts/usage in the useapi.net FlowMusic API v1 — daily billing events and per-song cost summaries." parent: Flow Music API nav_order: 130 permalink: /docs/api-flowmusic-v1/get-flowmusic-accounts-usage --- ## Account usage June 3, 2026 (November 16, 2026) --- Token and credit usage for an account — raw billing events plus per-type and per-song summaries, aggregated per UTC day. > **https://api.useapi.net/v1/flowmusic/accounts/usage?email=`email`** ### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Query Parameters - `email` (required) is which configured account to report on. ### Responses **200** **200 OK** ```json { "email": "user@email.com", "events": [ { "type": "producer-usage", "amount": 60, "conversation_id": "11112222-3333-4444-8555-666677778888", "conversation_title": "Sample Song", "event_at": "2026-06-01T00:00:00", "max_created_at": "2026-06-01T18:42:55.123456Z", "_account_email": "user@email.com" } ], "summary": { "by_type_tokens": { "daily-free": 1440, "riffusion": 60, "producer-usage": 1200, "grant": 7200 }, "by_type_credits": { "daily-free": 120, "riffusion": 5, "producer-usage": 100, "grant": 600 }, "total_charged_credits": 105, "total_received_tokens": 8640, "per_conversation": [ { "conversation_id": "11112222-3333-4444-8555-666677778888", "title": "Sample Song", "email": "user@email.com", "tokens": 60, "credits": 5 } ] } } ``` - `events` lists per-day usage rows, aggregated per UTC day. Each row carries a `type`, an `amount` in tokens, the `conversation_id` / `conversation_title` it belongs to, `event_at` (start of the UTC day), and `max_created_at` (the latest actual event time in that day). - `summary.by_type_tokens` and `by_type_credits` total the amounts per event type (credits are tokens / 12). - `total_charged_credits` sums the charged types (`producer-usage`, `riffusion`). `total_received_tokens` sums grants and free allowances. - `per_conversation` breaks the spend down per song. See [Flow Music pricing](https://www.flowmusic.app/pricing?plan=yearly) for plan allowances and per-generation costs. **401** **401 Unauthorized** — invalid API token. **404** **404** — account not configured. ### Model The account's billing events, grouped by UTC day, plus totals by type and by song in tokens and credits. <details markdown="block" class="model-details"> <summary>The account's usage events and totals, field by field</summary> ```typescript { email: string events: Array<{ type: string // e.g. 'producer-usage' | 'riffusion' | 'daily-free' | 'grant' amount: number // tokens conversation_id: string | null conversation_title: string | null event_at: string // start of the UTC day this row is bucketed into max_created_at: string // latest actual event time in that day _account_email: string }> summary: { by_type_tokens: Record<string, number> by_type_credits: Record<string, number> // tokens / 12 total_charged_credits: number total_received_tokens: number per_conversation: Array<{ conversation_id: string title: string | null email: string | null tokens: number credits: number }> } } ``` </details> ### Examples **Curl** ``` bash curl -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v1/flowmusic/accounts/usage?email=user@email.com" ``` **Python** ``` python import requests r = requests.get('https://api.useapi.net/v1/flowmusic/accounts/usage', headers={'Authorization': 'Bearer YOUR_API_TOKEN'}, params={'email': 'user@email.com'}) print(r.status_code, r.json()) ``` ### Try It <script> async function apiTestGetAccountsUsageFlowMusic() { const data = { method: 'GET', headers: { 'Authorization': `Bearer ${document.getElementById('get-accounts-usage-FlowMusic-token').value}` } }; let email = document.getElementById(`get-accounts-usage-FlowMusic-email`)?.value; const qs = new URLSearchParams(); if (email) qs.set('email', email); const url = `https://api.useapi.net/v1/flowmusic/accounts/usage` + (qs.toString() ? `?${qs.toString()}` : ''); await apiExecute(url, 'get-accounts-usage-FlowMusic', data); } </script> <form id="get-accounts-usage-FlowMusic" onsubmit="return false;" class="input-form"> <div class="input-field"> <div class="input-field-row"> <label for="get-accounts-usage-FlowMusic-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="get-accounts-usage-FlowMusic-token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> <label for="get-accounts-usage-FlowMusic-email"><span>email</span> <input id="get-accounts-usage-FlowMusic-email" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> </div> <button id="get-accounts-usage-FlowMusic-button" class="btn btn-primary fs-3" type="submit" onclick="apiTestGetAccountsUsageFlowMusic()">Go</button> </div> </form> <div id="get-accounts-usage-FlowMusic-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-flowmusic-v1/get-flowmusic-accounts === Document URL: https://useapi.net/docs/api-flowmusic-v1/get-flowmusic-accounts --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts description: "List all Flow Music accounts configured under your useapi.net account via GET accounts in the useapi.net FlowMusic API v1 — email, tier, maxJobs, token state, and re-auth error flag." parent: Flow Music API nav_order: 110 permalink: /docs/api-flowmusic-v1/get-flowmusic-accounts --- ## List accounts June 3, 2026 (November 16, 2026) --- List all Flow Music accounts configured under your useapi.net account. > **https://api.useapi.net/v1/flowmusic/accounts** ### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Responses **200** **200 OK** ```json { "user@email.com": { "email": "user@email.com", "tier": "plus", "subscription_plan": "plus-monthly", "provider": "g1_entitlement", "user_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", "maxJobs": 12, "added": "2026-06-01T12:00:00.000Z", "refreshed_at": "2026-06-01T12:00:00.000Z", "refreshed_count": 0, "access_token": "eyJ…redacted…zmQ", "access_token_expires_at": "2026-06-01T13:00:00.000Z", "refresh_token": "l6e…redacted…z4v", "session_id": "f0e1d2c3-b4a5-4768-9a0b-1c2d3e4f5a6b" } } ``` - The response is an object keyed by account email (`{}` when no accounts are configured). - `tier` is the account's Flow Music plan, re-read when the account's login refreshes (about hourly while the account is in use). [GET /accounts/`email`](/docs/api-flowmusic-v1/get-flowmusic-accounts-email) re-reads it at once, and a new plan also moves `maxJobs` to that plan's default unless you set `maxJobs` yourself with [POST /accounts](/docs/api-flowmusic-v1/post-flowmusic-accounts). The plan included with [Google AI Plus](https://support.google.com/googleone/answer/16882689), [Pro](https://support.google.com/googleone/answer/14534406) or [Ultra](https://support.google.com/googleone/answer/16286513) reads as `starter`, `plus` or `member`. - `error` is present only when an account needs re-authentication (re-run [POST /accounts](/docs/api-flowmusic-v1/post-flowmusic-accounts)) — healthy accounts omit it. - Credit balances are omitted from the list — fetch them live per account via [GET /accounts/`email`](/docs/api-flowmusic-v1/get-flowmusic-accounts-email). **401** **401 Unauthorized** — invalid API token. ### Model An object keyed by account email (`{}` when none are configured). <details markdown="block" class="model-details"> <summary>Every account record, keyed by email, field by field</summary> ```typescript { [email: string]: { email: string tier: 'free' | 'starter' | 'plus' | 'member' | 'unknown' subscription_plan?: string // paid tiers only provider?: string // paid tiers only user_id: string // the account's user UUID maxJobs: number added: string // ISO 8601 timestamp refreshed_at: string // ISO 8601 timestamp refreshed_count: number access_token: string // redacted access_token_expires_at: string // ISO 8601 timestamp refresh_token: string // redacted session_id: string error?: string // present only when the account needs re-authentication } } ``` </details> ### Examples **Curl** ``` bash curl -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v1/flowmusic/accounts" ``` **Python** ``` python import requests r = requests.get('https://api.useapi.net/v1/flowmusic/accounts', headers={'Authorization': 'Bearer YOUR_API_TOKEN'}) print(r.status_code, r.json()) ``` ### Try It <script> async function apiTestGetAccountsFlowMusic() { const data = { method: 'GET', headers: { 'Authorization': `Bearer ${document.getElementById('get-accounts-FlowMusic-token').value}` } }; const url = `https://api.useapi.net/v1/flowmusic/accounts`; await apiExecute(url, 'get-accounts-FlowMusic', data); } </script> <form id="get-accounts-FlowMusic" onsubmit="return false;" class="input-form"> <div class="input-field"> <div class="input-field-row"> <label for="get-accounts-FlowMusic-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="get-accounts-FlowMusic-token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> </div> <button id="get-accounts-FlowMusic-button" class="btn btn-primary fs-3" type="submit" onclick="apiTestGetAccountsFlowMusic()">Go</button> </div> </form> <div id="get-accounts-FlowMusic-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-flowmusic-v1/get-flowmusic-jobs-jobid === Document URL: https://useapi.net/docs/api-flowmusic-v1/get-flowmusic-jobs-jobid --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> jobs/`jobid` description: "Poll an async generation by jobid via GET jobs/jobid in the useapi.net FlowMusic API v1 — returns status, clips on completion, and error details on failure." parent: Flow Music API nav_order: 410 permalink: /docs/api-flowmusic-v1/get-flowmusic-jobs-jobid --- ## Poll a job June 3, 2026 (November 16, 2026) --- Fetch one job record by its `jobid`. Use this to poll an [async](/docs/api-flowmusic-v1/post-flowmusic-music) generation, or a sync one that answered `202` because it was not finished within the sync wait (7 minutes for a song, 2 minutes for most edits), until `status` is `completed` or `failed`. A job whose result never reaches us is marked `failed` with `error.code` `timeout` when you fetch it more than 20 minutes after it started. > **https://api.useapi.net/v1/flowmusic/jobs/`jobid`** - `jobid` is URL-encoded in the path (it contains `:` and `@`). ### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Responses **200** **200 OK** ```json { "jobid": "job:56ef7890-...-bot:flowmusic", "email": "user@email.com", "request": { "prompt": "...", "mode": "async" }, "created_at": "2026-05-31T19:57:23.954Z", "completed_at": "2026-05-31T19:59:43.118Z", "duration_ms": 139164, "status": "completed", "clips": [ { "clip": "user:1234-...-clip:...", "duration_s": 173.03, "image_url": "..." } ] } ``` While still running, only `status: "pending"` and the dispatch fields are present (no `clips`). **401** **401 Unauthorized** — invalid API token. **403** **403** — the jobid does not belong to your account. **404** **404** — no job with that id (expired or never existed). ### Model The job record — the same shape returned by [POST /music](/docs/api-flowmusic-v1/post-flowmusic-music) and [POST /music/edit](/docs/api-flowmusic-v1/post-flowmusic-music-edit). `operation` is present only for edit jobs, `clips` appears once `completed`, and `error` appears when `failed`. <details markdown="block" class="model-details"> <summary>The job record, field by field</summary> ```typescript { jobid: string // job:<uuid>-user:<id>-<email>-bot:flowmusic email: string operation?: 'effect' | 'extend' | 'replace' | 'cover' | 'remix' // edit jobs only status: 'completed' | 'pending' | 'failed' created_at: string // ISO 8601 timestamp completed_at?: string // present when terminal duration_ms?: number // wall-clock generation time clips?: Array<{ // present once completed clip: string // encoded clip asset id — use with /music/download and /music/edit title: string | null duration_s: number | null lyrics: string | null seed: number | null lyrics_timing: Array<[number, number]> | null // timing markers, [start, end] seconds (vocal clips) created_at: string audio_url: string wav_url: string image_url: string | null }> error?: { // present when status is 'failed' code: string message: string } request: object // the original request body, echoed back verbatim } ``` </details> ### Examples **Curl** ``` bash JOBID="job:56ef7890-...-bot:flowmusic" curl -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v1/flowmusic/jobs/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$JOBID")" ``` **Python** ``` python import requests, urllib.parse jobid = 'job:56ef7890-...-bot:flowmusic' r = requests.get('https://api.useapi.net/v1/flowmusic/jobs/' + urllib.parse.quote(jobid, safe=''), headers={'Authorization': 'Bearer YOUR_API_TOKEN'}) print(r.status_code, r.json()) ``` ### Try It <script> function displayFlowMusicClips(response, elementId) { const container = document.getElementById(`${elementId}-media-links`); if (!container) return; container.innerHTML = ''; const clips = response.clips || []; if (clips.length === 0) { container.style.display = 'none'; return; } container.innerHTML = '<div class="media-links-container"><strong>Generated clips:</strong></div>' + clips.map((c, i) => { const title = c.title || `Clip ${i + 1}`; const cover = c.image_url ? `<a href="${c.image_url}" target="_blank" rel="noopener noreferrer" title="Open full image in a new tab"><img src="${c.image_url}" alt="cover" style="max-width:96px;border-radius:6px;vertical-align:middle;margin-right:8px;cursor:zoom-in;"></a>` : ''; const audio = c.audio_url ? `<audio src="${c.audio_url}" controls style="vertical-align:middle;"></audio>` : ''; return `<div style="margin:6px 0;">${cover}${audio}<div>${escHtml(title)}</div></div>`; }).join(''); container.style.display = 'block'; } async function apiTestGetJobsJobidFlowMusic() { const elementId = 'get-jobs-jobid-FlowMusic'; const data = { method: 'GET', headers: { 'Authorization': `Bearer ${document.getElementById('get-jobs-jobid-FlowMusic-token').value}` } }; let jobid = document.getElementById(`get-jobs-jobid-FlowMusic-jobid`)?.value; const url = `https://api.useapi.net/v1/flowmusic/jobs/${encodeURIComponent(jobid)}`; const mediaLinks = document.getElementById(`${elementId}-media-links`); if (mediaLinks) mediaLinks.style.display = 'none'; const status = await apiExecute(url, elementId, data); if (status === 200) { try { const response = JSON.parse(document.getElementById(`${elementId}-response-json`).innerText); displayFlowMusicClips(response, elementId); } catch (e) { console.error('Failed to parse response for clip display:', e); } } } </script> <form id="get-jobs-jobid-FlowMusic" onsubmit="return false;" class="input-form"> <div class="input-field"> <div class="input-field-row"> <label for="get-jobs-jobid-FlowMusic-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="get-jobs-jobid-FlowMusic-token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> <label for="get-jobs-jobid-FlowMusic-jobid"><span>jobid</span> <input id="get-jobs-jobid-FlowMusic-jobid" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> </div> <button id="get-jobs-jobid-FlowMusic-button" class="btn btn-primary fs-3" type="submit" onclick="apiTestGetJobsJobidFlowMusic()">Go</button> </div> </form> <div id="get-jobs-jobid-FlowMusic-media-links" style="display:none;"></div> <div id="get-jobs-jobid-FlowMusic-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-flowmusic-v1/get-flowmusic-jobs === Document URL: https://useapi.net/docs/api-flowmusic-v1/get-flowmusic-jobs --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> jobs description: "List all currently-running jobs (async, and sync jobs still in progress) grouped by account via GET jobs in the useapi.net FlowMusic API v1 — shows running counts and maxJobs concurrency limits." parent: Flow Music API nav_order: 400 permalink: /docs/api-flowmusic-v1/get-flowmusic-jobs --- ## List running jobs June 3, 2026 (November 16, 2026) --- List the currently-running jobs, grouped by account email: async jobs and sync requests still in progress. Useful for tracking concurrency against each account's `maxJobs` limit. > **https://api.useapi.net/v1/flowmusic/jobs** ### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Responses **200** **200 OK** ```json { "user@email.com": { "running": 1, "maxJobs": 12, "jobs": [ { "jobid": "job:56ef7890-...-bot:flowmusic", "status": "pending", "created_at": "2026-05-31T19:57:23.954Z" } ] } } ``` An empty object `{}` means nothing is running. **401** **401 Unauthorized** — invalid API token. ### Model An object keyed by account email (`{}` when nothing is running). <details markdown="block" class="model-details"> <summary>Each account's running jobs, field by field</summary> ```typescript { [email: string]: { running: number maxJobs: number jobs: Array<{ jobid: string status: 'pending' | 'completed' | 'failed' operation?: 'effect' | 'extend' | 'replace' | 'cover' | 'remix' // edit jobs only created_at: string // ISO 8601 timestamp }> } } ``` </details> ### Examples **Curl** ``` bash curl -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v1/flowmusic/jobs" ``` **Python** ``` python import requests r = requests.get('https://api.useapi.net/v1/flowmusic/jobs', headers={'Authorization': 'Bearer YOUR_API_TOKEN'}) print(r.status_code, r.json()) ``` ### Try It <script> async function apiTestGetJobsFlowMusic() { const data = { method: 'GET', headers: { 'Authorization': `Bearer ${document.getElementById('get-jobs-FlowMusic-token').value}` } }; const url = `https://api.useapi.net/v1/flowmusic/jobs`; await apiExecute(url, 'get-jobs-FlowMusic', data); } </script> <form id="get-jobs-FlowMusic" onsubmit="return false;" class="input-form"> <div class="input-field"> <div class="input-field-row"> <label for="get-jobs-FlowMusic-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="get-jobs-FlowMusic-token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> </div> <button id="get-jobs-FlowMusic-button" class="btn btn-primary fs-3" type="submit" onclick="apiTestGetJobsFlowMusic()">Go</button> </div> </form> <div id="get-jobs-FlowMusic-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-flowmusic-v1/get-flowmusic-music-download === Document URL: https://useapi.net/docs/api-flowmusic-v1/get-flowmusic-music-download --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> music/download description: "Download a generated clip as raw mp3 audio bytes via GET music/download in the useapi.net FlowMusic API v1 — pass a clip ID, receive the binary stream directly." parent: Flow Music API nav_order: 240 permalink: /docs/api-flowmusic-v1/get-flowmusic-music-download --- ## Download raw mp3 audio June 3, 2026 --- Download a generated clip as raw `mp3` audio — the response body is the audio bytes. The full-quality **m4a** and **wav** are public URLs already on every clip, so they aren't re-served here: read `audio_url` / `wav_url` from [GET /music](/docs/api-flowmusic-v1/get-flowmusic-music) (or the job record) and download those directly. > **https://api.useapi.net/v1/flowmusic/music/download** ### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Query Parameters - `id` is **required**, an encoded clip asset ID (`user:<id>-<email>-clip:<uuid>`) or a completed jobid (resolves to the job's first clip). - `format` is optional, `mp3` (the default and only value). > **Stems are separate clips.** When you separate a song's stems in Flow Music it creates one clip per track — they show up in [GET /music](/docs/api-flowmusic-v1/get-flowmusic-music) as `"<title> - drums"`, `"- bass"`, `"- vocals"`, `"- other"`. Download each one here with its own `id` (or grab its `audio_url`/`wav_url`). ### Responses **200** **200 OK** — the raw `audio/mpeg` bytes, with a `Content-Disposition` filename (`<clip>.mp3`). **400** **400** — `id` is not a valid clip ID or jobid, or `format` is unsupported. ```json { "error": "Parameter id not a valid clip ID or jobid", "code": 400 } ``` **401** **401 Unauthorized** — invalid API token. **409** **409** — a jobid was given but the job is not completed yet. **596** **596 Account Error** The account that owns the requested clip is in an error state and can't be used — re-add it via [POST /accounts](/docs/api-flowmusic-v1/post-flowmusic-accounts). The `error` field returns whatever reason was recorded for the account. ```json { "error": "Account user@email.com in error state: refresh token rejected", "code": 596 } ``` ### Model This endpoint streams raw `audio/mpeg` bytes (not JSON), with a `Content-Disposition` filename. Only the error responses (`400` / `409`) return JSON `{ error, code }`. ### Examples **Curl** ``` bash # Any clip — including a separated stem clip — downloads as mp3 by its id curl -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v1/flowmusic/music/download?id=user:1234-user@email.com-clip:12ab34cd-...&format=mp3" \ --output song.mp3 ``` **Python** ``` python import requests, urllib.parse clip = 'user:1234-user@email.com-clip:12ab34cd-...' url = 'https://api.useapi.net/v1/flowmusic/music/download?id=' + urllib.parse.quote(clip) + '&format=mp3' r = requests.get(url, headers={'Authorization': 'Bearer YOUR_API_TOKEN'}) open('song.mp3', 'wb').write(r.content) ``` ### Try It This endpoint returns raw audio bytes (not JSON), so the form below fetches the file with your token and plays it inline. <script> async function apiTestDownloadFlowMusic() { const id = document.getElementById('get-music-download-FlowMusic-id')?.value; const data = { method: 'GET', headers: { 'Authorization': `Bearer ${document.getElementById('get-music-download-FlowMusic-token').value}` } }; const url = `https://api.useapi.net/v1/flowmusic/music/download?id=${encodeURIComponent(id)}&format=mp3`; await apiExecute(url, 'get-music-download-FlowMusic', data, { expectMedia: true }); } </script> <form id="get-music-download-FlowMusic" onsubmit="return false;" class="input-form"> <div class="input-field"> <div class="input-field-row"> <label for="get-music-download-FlowMusic-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="get-music-download-FlowMusic-token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> <label for="get-music-download-FlowMusic-id"><span>id (encoded clip id or jobid)</span> <input id="get-music-download-FlowMusic-id" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> </div> <button id="get-music-download-FlowMusic-button" class="btn btn-primary fs-3" type="submit" onclick="apiTestDownloadFlowMusic()">Go</button> </div> </form> <div id="get-music-download-FlowMusic-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-flowmusic-v1/get-flowmusic-music === Document URL: https://useapi.net/docs/api-flowmusic-v1/get-flowmusic-music --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> music description: "List generated clips on a Flow Music account via GET music in the useapi.net FlowMusic API v1 — paginated, most recent first, with clip IDs, titles, lyrics, and cover image URLs." parent: Flow Music API nav_order: 230 permalink: /docs/api-flowmusic-v1/get-flowmusic-music --- ## List clips June 3, 2026 (November 16, 2026) --- List the clips generated on a Flow Music account, most recent first. Paginated by `offset`. > **https://api.useapi.net/v1/flowmusic/music** ### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Query Parameters - `email` is optional, which configured account to list. Defaults to an available account. - `limit` is optional, the page size, 1–100 (default 20). - `offset` is optional, the page offset, ≥ 0 (default 0). ### Responses **200** **200 OK** ```json { "email": "user@email.com", "clips": [ { "clip": "user:1234-user@email.com-clip:12ab34cd-...", "title": "Morning Sun", "lyrics": "[Verse 1]\n...", "duration_s": 173.03, "image_url": "https://storage.googleapis.com/..." } ], "limit": 20, "offset": 0, "next": 20 } ``` - `next` is the `offset` to request for the following page, or `null` when this was the last page. **401** **401 Unauthorized** — invalid API token. **596** **596 Account Error** The account targeted by `email` is in an error state and can't be used — re-add it via [POST /accounts](/docs/api-flowmusic-v1/post-flowmusic-accounts). The `error` field returns whatever reason was recorded for the account. ```json { "error": "Account user@email.com in error state: refresh token rejected", "code": 596 } ``` ### Model One page of the account's clips, each with its id, title, lyrics, length and image, and the `offset` of the next page in `next`. <details markdown="block" class="model-details"> <summary>One page of the account's clips, field by field</summary> ```typescript { email: string clips: Array<{ clip: string // encoded clip asset id — use with /music/download and /music/edit title: string | null lyrics: string | null duration_s: number | null image_url: string | null }> limit: number offset: number next: number | null // offset for the next page, or null when this was the last page } ``` </details> ### Examples **Curl** ``` bash curl -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v1/flowmusic/music?limit=10&offset=0" ``` **Python** ``` python import requests response = requests.get( 'https://api.useapi.net/v1/flowmusic/music', headers={'Authorization': 'Bearer YOUR_API_TOKEN'}, params={'limit': 10, 'offset': 0} ) print(response.status_code, response.json()) ``` ### Try It <script> async function apiTestGetMusicFlowMusic() { const data = { method: 'GET', headers: { 'Authorization': `Bearer ${document.getElementById('get-music-FlowMusic-token').value}` } }; let email = document.getElementById(`get-music-FlowMusic-email`)?.value; let limit = document.getElementById(`get-music-FlowMusic-limit`)?.value; let offset = document.getElementById(`get-music-FlowMusic-offset`)?.value; const qs = new URLSearchParams(); if (email) qs.set('email', email); if (limit) qs.set('limit', limit); if (offset) qs.set('offset', offset); const url = `https://api.useapi.net/v1/flowmusic/music` + (qs.toString() ? `?${qs.toString()}` : ''); await apiExecute(url, 'get-music-FlowMusic', data); } </script> <form id="get-music-FlowMusic" onsubmit="return false;" class="input-form"> <div class="input-field"> <div class="input-field-row"> <label for="get-music-FlowMusic-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="get-music-FlowMusic-token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> <label for="get-music-FlowMusic-email"><span>email (optional)</span> <input id="get-music-FlowMusic-email" type="text" class="input-element" oninput="this.size = this.value.length"> </label> <label for="get-music-FlowMusic-limit"><span>limit (optional, 1-100)</span> <input id="get-music-FlowMusic-limit" type="text" class="input-element" oninput="this.size = this.value.length"> </label> <label for="get-music-FlowMusic-offset"><span>offset (optional, >=0)</span> <input id="get-music-FlowMusic-offset" type="text" class="input-element" oninput="this.size = this.value.length"> </label> </div> <button id="get-music-FlowMusic-button" class="btn btn-primary fs-3" type="submit" onclick="apiTestGetMusicFlowMusic()">Go</button> </div> </form> <div id="get-music-FlowMusic-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-flowmusic-v1 === Document URL: https://useapi.net/docs/api-flowmusic-v1 --- layout: default title: Flow Music API nav_logo: /assets/images/google-flow-music-logo.jpg nav_title: Flow Music API seo_title: "Google Flow Music API (Lyria 3.5): Songs, Covers and Stems" description: "Third-party Google Flow Music API (FlowMusic) by useapi.net: Lyria 3.5 and Lyria 3 Pro songs with vocals, covers, remixes, extends and stems, over REST or MCP." nav_order: 2600 has_children: true permalink: /docs/api-flowmusic-v1 repo: https://github.com/useapi/flowmusic-api --- # <img style="height:1em;vertical-align: middle;" src="/assets/images/google-flow-music-logo.jpg" alt=""> Flow Music API June 3, 2026 (November 15, 2026) This is a [third-party](/docs/legal#affiliation--third-party-services) API for [Google Flow Music](https://www.flowmusic.app) (formerly Producer AI, originally [Riffusion](https://www.riffusion.com)) by [Google Labs](https://labs.google). It uses your [Flow Music subscription](https://www.flowmusic.app/pricing): Free, Starter $8, Plus $24 or Member $64 a month (as of November 2026). [Google AI Plus](https://support.google.com/googleone/answer/16882689), [Pro](https://support.google.com/googleone/answer/14534406) and [Ultra](https://support.google.com/googleone/answer/16286513) include its Starter, Plus and Member plans. Through a REST API and a hosted MCP server, it makes full songs with vocals or instrumentals on Lyria 3.5 and Lyria 3 Pro, then covers, remixes, extends and splits them into stems. ## Models | Model | What it makes | Notes | |---|---|---| | [Lyria 3.5](https://deepmind.google/models/lyria/)<br>`lyria-3.5` | [Songs](/docs/api-flowmusic-v1/post-flowmusic-music) from a prompt, sung with lyrics the model writes or your own, or instrumental | Google's current flagship, songs up to about 3 minutes, one or two songs (an A/B pair) per request | | [Lyria 3 Pro](https://deepmind.google/models/lyria/)<br>`lyria-3-pro` | Songs from a prompt, sung or instrumental | The default when `model` is left out, so older integrations sound the same, at the same credits per song | | Song edits | [Cover, remix, extend and replace](/docs/api-flowmusic-v1/post-flowmusic-music-edit) on either model | Restyle a song, re-sing it with new lyrics, add 1 to 300 seconds (songs of 5 minutes and more) or redo one section | | Effects and stems | [Audio effects and stems](/docs/api-flowmusic-v1/post-flowmusic-music-edit) from any song | Trim, fade, gain, reverb, pan and equalizer, and four stems: drums, bass, vocals and other | | Lyrics | [Verse and chorus lyrics](/docs/api-flowmusic-v1/post-flowmusic-music-lyrics) with a matching style prompt, no audio | Shape the layout with `structure`, then sing them with a song request | | More | [Generated images](/docs/api-flowmusic-v1/post-flowmusic-files-generate) and [image and audio uploads](/docs/api-flowmusic-v1/post-flowmusic-files) as style hints, your [song list](/docs/api-flowmusic-v1/get-flowmusic-music), [mp3 downloads](/docs/api-flowmusic-v1/get-flowmusic-music-download) and [credit usage](/docs/api-flowmusic-v1/get-flowmusic-accounts-usage) | Every song also comes with m4a and wav links | ## MCP server The hosted [Flow Music MCP server](/docs/api-flowmusic-v1/mcp) gives Claude Code, Cursor, VS Code and other AI assistants 18 tools for songs, lyrics, extends, section replacements, covers, lyric remixes, effects and stems, with your useapi.net API token and nothing to install. The [flowmusic-api](https://github.com/useapi/flowmusic-api) repo also adds it in one step as a [Claude Code plugin](https://github.com/useapi/flowmusic-api#use-with-claude-code) or a [Gemini CLI extension](https://github.com/useapi/flowmusic-api#use-with-gemini-cli). ## Pricing What one song costs on Google's [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) and on each [Flow Music subscription](https://www.flowmusic.app/pricing) (as of October 2026). Each subscription comes with a monthly number of credits, and each song uses 5 of them, so a song costs its share of the subscription. | Model | [Official API](https://ai.google.dev/gemini-api/docs/pricing) | Member $64/m (30,000 cr/mo) | Plus $24/m (10,000 cr/mo) | Starter $8/m (3,000 cr/mo) | |---|---|---|---|---| | Lyria 3.5 (full song) | $0.08 (per song) | $0.011 / 5 cr (6,000 songs/mo) | $0.012 / 5 cr (2,000 songs/mo) | $0.013 / 5 cr (600 songs/mo) | | Lyria 3 Pro (full song) | $0.08 (per song, Preview) | $0.011 / 5 cr (6,000 songs/mo) | $0.012 / 5 cr (2,000 songs/mo) | $0.013 / 5 cr (600 songs/mo) | | Downloads (mp3, wav, m4a and stems) | — | $0 / 0 cr (included) | $0 / 0 cr (included) | $0 / 0 cr (included) | - A free Flow Music account makes songs too, from its daily top-up credits, with both Lyria models and every download. [Google AI Plus](https://support.google.com/googleone/answer/16882689) includes Flow Music's Starter plan (3,000 credits a month, about 600 songs), [Google AI Pro](https://support.google.com/googleone/answer/14534406) its Plus plan (10,000 credits, about 2,000 songs) and [Google AI Ultra](https://support.google.com/googleone/answer/16286513) its Member plan (30,000 credits, about 6,000 songs), an allowance separate from the Google AI credits. Sign in once at flowmusic.app with that Google account and allow it to see the Google One membership. useapi.net picks the plan up by itself: it re-reads it when the account's login refreshes (about hourly while the account is in use), and [GET /accounts/`email`](/docs/api-flowmusic-v1/get-flowmusic-accounts-email) applies a change at once. - Covers, remixes, extends, section replacements, effects and stems spend credits from the same subscription. - Paid plans can also [buy extra credits](https://www.flowmusic.app/pricing) while the subscription is active, and yearly billing is 25% off. <details markdown="block" class="calc-details"> <summary>Every plan, monthly and yearly</summary> Each request returns one or two songs (an A/B pair) at 5 credits a song. Every plan also gets daily top-up credits, so even Free makes a few songs each day. Max at once is how many generations Flow Music runs at the same time on one account, which is also the default `maxJobs` for that account. | Plan | Price a month | Credits a month | Songs a month | Per song | Max at once | |---|---|---|---|---|---| | Free | $0 | daily top-ups only | — | free daily credits | 2 | | Starter, monthly | $8 | 3,000 | about 600 | $0.013 | 8 | | Plus, monthly | $24 | 10,000 | about 2,000 | $0.012 | 12 | | Member, monthly | $64 | 30,000 | about 6,000 | $0.011 | 16 | | Starter, yearly | $6 | 3,000 | about 600 | $0.010 | 8 | | Plus, yearly | $18 | 10,000 | about 2,000 | $0.009 | 12 | | Member, yearly | $48 | 30,000 | about 6,000 | $0.008 | 16 | Yearly rows show the price per month when billed yearly, 25% off. </details> #### One Google account, four APIs The same Google AI plan powers several useapi.net APIs, each from its own allowance, so one Google account connected to all of them gets the most out of the plan: - [Google Flow API](/docs/api-google-flow-v1): Veo 3.1, Omni 1.2 Flash and Omni 1.1 Flash video, Nano Banana images up to 4K, from Flow credits. - [Google Vids API](/docs/api-google-vids-v1): Omni 1.2 Flash video up to 15 seconds, 30-second [talking avatar videos](/docs/api-google-vids-v1/post-google-vids-videos-avatar) from a photo, avatars in 30 voices and [text to speech](/docs/api-google-vids-v1/post-google-vids-speech), from the Vids allowance, which does not use Flow credits. - [Gemini Notebook API (NotebookLM API)](/docs/api-gemini-notebook-v1): chat with sources, Deep Research and every Studio output, from the Gemini Notebook usage limits. - [Flow Music API](/docs/api-flowmusic-v1): full songs with Lyria in Google Flow Music, on the Flow Music plan your Google AI subscription includes (Starter on [Plus](https://support.google.com/googleone/answer/16882689), Plus on [Pro](https://support.google.com/googleone/answer/14534406), Member on [Ultra](https://support.google.com/googleone/answer/16286513)) or on Flow Music's own plans. Each API is set up on its own setup page, and one useapi.net subscription covers all of them. ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. ## Run several Flow Music accounts Each useapi.net subscription connects 3 Flow Music accounts, up to 100 in total. Song requests don't need `email`: each one goes to an account with a free slot within its `maxJobs`, which starts at the plan's own limit (2 on Free, 8 on Starter, 12 on Plus, 16 on Member, and the plan included with Google AI Plus, Pro or Ultra counts as Starter, Plus or Member) and follows the plan when it changes, or can be set from 1 to 16 with [POST accounts](/docs/api-flowmusic-v1/post-flowmusic-accounts). When every account is busy you get `429`, so wait and send it again. Pass `email` to run a song on a specific account. Edits run on the account that holds the song, and uploaded references keep a song on the account they were uploaded to. [GET /jobs](/docs/api-flowmusic-v1/get-flowmusic-jobs) shows the load on every account and [GET /accounts/`email`](/docs/api-flowmusic-v1/get-flowmusic-accounts-email) its live credit balance. Every song and edit can post its finished record to your webhook with `replyUrl`, or you poll [GET /jobs/`jobid`](/docs/api-flowmusic-v1/get-flowmusic-jobs-jobid) in `async` mode, so a song that takes 40 to 150 seconds needs no open connection. [How useapi.net works](/docs/how-it-works) has tips for keeping your accounts healthy. ## Questions ### Is there a Google Flow Music API? Through useapi.net, yes. Google offers Flow Music only as a website, with no public Flow Music API (as of October 2026), and the useapi.net Flow Music API runs it over REST on your Flow Music plan, including the one that comes with Google AI Plus, Pro or Ultra: full songs with vocals on Lyria 3.5 and Lyria 3 Pro, and edits of them. Node.js examples are on GitHub at [useapi/flowmusic-api](https://github.com/useapi/flowmusic-api). ### How much does the Flow Music API cost? Through useapi.net, a Lyria 3.5 song costs about $0.013 on Flow Music Starter at $8 a month and $0.011 on Member, against $0.08 a song on Google's [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) (as of October 2026). Billed yearly, Member brings it to about $0.008. Google AI Plus, Pro and Ultra include the Starter, Plus and Member plans, and the Free plan's daily credits work too. The [price table](#pricing) shows every plan. ### Do I need a Flow Music API key? Through useapi.net, you call Flow Music with our [API token](/docs/start-here/setup-useapi), since Google issues no Flow Music API key. You connect the Google account you use at flowmusic.app once through [Setup Flow Music](/docs/start-here/setup-flowmusic), which signs in with Google in a guided browser, with no tokens to copy. You need no Google Cloud project and no Gemini API billing. ### Is the Flow Music API the same as the Lyria 3 Gemini API? Through useapi.net, you get more than the Lyria Gemini API: the Flow Music API drives the Flow Music app with your Google account and Flow Music plan, and it edits the songs it makes, with covers, lyric remixes, extends, section replacements, effects and stems. Lyria on Google's [Gemini API](https://ai.google.dev/gemini-api/docs/music-generation) makes each song in a single pass with no editing afterwards, and has no free tier (as of October 2026). [Setup Flow Music](/docs/start-here/setup-flowmusic) [LLM-friendly API spec](https://useapi.net/assets/aibot/api-flowmusic-v1.txt) Feed this to your LLM to build integrations [Claude Code skill](/llm-tools) A drop-in useapi.net skill for Claude Code, and a rule for Cursor [Postman collection](https://www.postman.com/useapinet/useapi-net/collection/29112081-3386ba6a-1539-415b-b9cf-7ef1c9d7939d) (August 12, 2026) [MCP Server](/docs/api-flowmusic-v1/mcp) Make songs, edits and stems from Claude Code, Cursor, VS Code and other MCP clients [GitHub examples](https://github.com/useapi/flowmusic-api) Node.js: full songs with Lyria 3.5 and Lyria 3 Pro, plus the Claude Code plugin and Gemini CLI extension Articles: * [Can You Use Your Google AI Subscription Through an API? What Plus, Pro and Ultra Get You](/docs/articles/google-ai-subscription-api) {% include lang-switch.html mode="hub" key="google-ai-subscription" %} * [Suno API Alternative: ACE Music, Mureka, Lyria 3.5, TemPolor and MiniMax](/docs/articles/suno-api-alternative) {% include lang-switch.html mode="hub" key="suno-api-alternative" %} * [How to Generate AI Music with Lyria 3 Pro via the Flow Music API](/docs/articles/flowmusic-bash) * [AI Music APIs Compared: Mureka vs MiniMax vs ElevenLabs vs Lyria 3 Pro](/docs/articles/ai-music-api-comparison) * [Five AI Music APIs on the Same Six Briefs: ACE Music v1, TemPolor v4.8, MiniMax Music-3.0, Lyria 3.5 and Mureka V9.5](/docs/articles/ai-music-flagships-compared) {% include lang-switch.html mode="hub" key="ai-music-flagships" %} Examples: * [Generate songs with Google's Lyria 3.5](/blog/260812) * [Generate and edit songs with FlowMusic API](/blog/260603) Videos on YouTube: * [Five AI music APIs: ACE Music v1, TemPolor v4.8, MiniMax Music-3.0, Lyria 3.5 and Mureka V9.5](https://www.youtube.com/watch?v=MSUGckk4JqU) * [AI music APIs one generation later: MiniMax Music-3.0 vs Lyria 3.5 vs Mureka V9.5](https://www.youtube.com/watch?v=9AM5p-A9oFM) Developer Community: * <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> * <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> === URL: https://useapi.net/docs/api-flowmusic-v1/mcp === Document URL: https://useapi.net/docs/api-flowmusic-v1/mcp --- layout: default title: MCP Server nav_icon: mcp seo_title: "Flow Music MCP Server: Lyria 3.5 Songs, Covers and Stems" description: "Connect the Claude app, ChatGPT, Claude Code or any MCP client to the hosted useapi.net Flow Music MCP server: 18 tools for Lyria songs, lyrics, edits and stems." parent: Flow Music API nav_order: 50 permalink: /docs/api-flowmusic-v1/mcp --- ## Flow Music MCP Server October 16, 2026 (November 1, 2026) --- The useapi.net Flow Music MCP server lets an AI assistant such as the Claude app, ChatGPT, Claude Code, Cursor or VS Code Copilot make music with [Google Flow Music](https://www.flowmusic.app) on your own Flow Music accounts. It is a hosted [Model Context Protocol](https://modelcontextprotocol.io) server with 18 tools: generate songs with Google's Lyria models from a description, your own lyrics or lyrics the model writes, then extend them, regenerate a section, restyle them, re-sing them with new lyrics, apply audio effects or split them into stems. Each tool calls the [FlowMusic API](/docs/api-flowmusic-v1), so the same rules and limits apply. Nothing needs to be installed or hosted. **Is there a Flow Music MCP server?** Yes. useapi.net, a third-party service not affiliated with Google, hosts one at `https://api.useapi.net/v1/flowmusic/mcp` with 18 tools for Lyria songs, covers, remixes and stems, on your own Flow Music account, nothing to install. Prefer REST? Tutorial: [How to Generate AI Music with Lyria 3 Pro via the Flow Music API](/docs/articles/flowmusic-bash) · Code: [github.com/useapi/flowmusic-api](https://github.com/useapi/flowmusic-api) See all useapi.net MCP servers on [Model Matrix & MCP](/model-matrix#mcp-servers). ## Endpoint and authorization ``` https://api.useapi.net/v1/flowmusic/mcp ``` - Transport: Streamable HTTP. - Listed in the [official MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers/net.useapi%2Fflowmusic/versions/latest) as `net.useapi/flowmusic`, so MCP clients and directories that read the registry can find it by that name. - Authorization: your useapi.net API token in the `Authorization: Bearer …` header, see [Setup useapi.net](/docs/start-here/setup-useapi). The Claude app and ChatGPT sign in with OAuth instead, see [Use it in the Claude app or ChatGPT](#use-it-in-the-claude-app-or-chatgpt). - You need at least one Flow Music account added with [Setup Flow Music](/docs/start-here/setup-flowmusic). Adding and removing accounts is not available over MCP: use [POST /accounts](/docs/api-flowmusic-v1/post-flowmusic-accounts) or the setup page. ## Setup Replace `YOUR_API_TOKEN` with your useapi.net API token. ### Claude Code ```bash claude mcp add --transport http useapi-flowmusic https://api.useapi.net/v1/flowmusic/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` ### Cursor In `~/.cursor/mcp.json`: ```json { "mcpServers": { "useapi-flowmusic": { "url": "https://api.useapi.net/v1/flowmusic/mcp", "headers": { "Authorization": "Bearer YOUR_API_TOKEN" } } } } ``` ### VS Code In `.vscode/mcp.json`: ```json { "servers": { "useapi-flowmusic": { "type": "http", "url": "https://api.useapi.net/v1/flowmusic/mcp", "headers": { "Authorization": "Bearer YOUR_API_TOKEN" } } } } ``` ### Windsurf and other clients Any client that supports remote MCP servers over HTTP with custom headers works. The usual JSON shape: ```json { "mcpServers": { "useapi-flowmusic": { "serverUrl": "https://api.useapi.net/v1/flowmusic/mcp", "headers": { "Authorization": "Bearer YOUR_API_TOKEN" } } } } ``` Some clients name the address field `url` instead of `serverUrl`. ### Test it with curl ```bash curl -s https://api.useapi.net/v1/flowmusic/mcp \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}' curl -s https://api.useapi.net/v1/flowmusic/mcp \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' ``` The first call answers with the server's name `useapi-flowmusic` and its instructions for the assistant, the second with the 18 tools. ## Use it in the Claude app or ChatGPT The Claude app ([claude.ai](https://claude.ai) and Claude Desktop) and [ChatGPT](https://chatgpt.com) can add this server as a custom connector. They sign in with OAuth: you give the app the URL, it opens a useapi.net page, and you paste your useapi.net API token there once. Both work on their Free plans. The API-token setups above for Claude Code, Cursor, VS Code and other clients keep working as before. ``` ``` ### Claude app 1. Open Settings → Connectors and click Add custom connector. 2. Enter a name, for example `useapi `, and the URL above, then click Add. 3. Click Connect. Claude opens the useapi.net sign-in page. 4. Paste your useapi.net API token and click Allow. Claude asks before each tool call unless you choose Always allow. The Free plan allows one custom connector. ### ChatGPT 1. Open Plugins, click Add and choose Add custom MCP server. 2. Enter a name and the URL above, and set Authentication to OAuth. 3. Tick ChatGPT's "I understand and want to continue" box, then click Create as a plugin. 4. Click Connect. ChatGPT opens the useapi.net sign-in page. 5. Paste your useapi.net API token and click Allow. ChatGPT asks you to confirm each tool call that creates or changes something. The Free plan works without developer mode (as of October 25, 2026). ### How the sign-in works - Your API token is in your welcome email, see [Setup useapi.net](/docs/start-here/setup-useapi). The useapi.net page links there too. - Each connection is for one MCP server. Connect each server you want to use on its own. - The app gets an access token that lasts 1 hour and renews it on its own. A connection you don't use for 90 days lapses, and you connect again. - [Resetting your API token](/docs/account-management/post-account-token-reset) disconnects every app connected with it. - - Results come back as public links, so they open right in the app. ## Tools Songs, clips and uploaded files are named by the ids the tools return, and each id carries its account, so an edit runs on the account that holds the clip. Tools that start a song take an optional `email` to pick the account. ### Accounts | Tool | What it does | Main parameters | |---|---|---| | `flowmusic_list_accounts` | Lists your accounts with their plan, `maxJobs` and health. | | | `flowmusic_get_account` | Reads one account live: plan, credits and tokens left. | `email` | | `flowmusic_update_account` | Sets `maxJobs`, the songs and edits an account runs at once. | `email`, `maxJobs` | | `flowmusic_get_usage` | Returns an account's credit usage: daily billing events and the cost of each song. | `email` | ### Songs and lyrics | Tool | What it does | Main parameters | |---|---|---| | `flowmusic_create_song` | Generates a song from a description of the style, mood, instruments and vocals, with your own lyrics, lyrics the model writes, or instrumental. | `prompt`, `lyrics`, `instrumental`, `ghostwriter`, `model`, `refImage1`..`10`, `refAudio1`..`10`, `email` | | `flowmusic_write_lyrics` | Writes `[Verse]` / `[Chorus]` lyrics, a title and a sound prompt for a song concept, without making a song. | `prompt`, `structure`, `email` | | `flowmusic_list_songs` | Lists the clips on an account, most recent first. | `email`, `limit`, `offset` | | `flowmusic_get_job` | Reads a song or edit job, and with `wait: true` waits for it to finish. | `jobid`, `wait` | | `flowmusic_list_jobs` | Lists the jobs running now on each account. | | | `flowmusic_cancel_job` | Stops tracking a job and frees its slot. Flow Music may still finish the song, and its credits are spent either way. | `jobid` | The parameters match [POST /music](/docs/api-flowmusic-v1/post-flowmusic-music) and [POST /music/lyrics](/docs/api-flowmusic-v1/post-flowmusic-music-lyrics). ### Edits Each edit of [POST /music/edit](/docs/api-flowmusic-v1/post-flowmusic-music-edit) is its own tool. Every one takes the `clip` to edit and an optional `title` and `seed`. | Tool | What it does | Main parameters | |---|---|---| | `flowmusic_extend_song` | Adds music to a clip, 1 to 300 seconds (150 by default). | `instruction`, `extend_s`, `extend_from_s`, `model` | | `flowmusic_replace_section` | Regenerates one section of a clip. | `instruction`, `mask_start_s`, `mask_end_s`, `model` | | `flowmusic_cover_song` | Restyles a whole clip. | `instruction`, `strength`, `model` | | `flowmusic_remix_lyrics` | Re-sings a clip with edited lyrics, keeping its sound. | `lyrics`, `prompt`, `model` | | `flowmusic_apply_effect` | Applies one effect: Trim, Fade, Gain, Reverb, Pan or Equalizer. | `effect` and that effect's parameters | | `flowmusic_split_stems` | Splits a clip into four stem clips: drums, bass, vocals and other. | `clip` | ### Reference files | Tool | What it does | Main parameters | |---|---|---| | `flowmusic_upload_file` | Uploads a JPEG, PNG or WebP image (up to 20 MB) or an MP3, WAV or M4A song (up to 40 MB) from a public https URL, or sent as `contentBase64`, as a reference for `flowmusic_create_song`. | `url` or `contentBase64`, `mimeType`, `email`, `stripMetadata` | | `flowmusic_generate_image` | Generates an image to use as a reference, returned as an image the assistant can see. | `prompt`, `email` | References are loose hints: neither Lyria model copies an uploaded song or picture. The full input schema of every tool comes from `tools/list`. ## Long-running work MCP clients usually give up on a tool call after about a minute, so a tool waits up to about 50 seconds: - A song usually takes 30 seconds to a minute, sometimes up to two and a half. If it isn't done in time, the tool returns the `jobid`, and `flowmusic_get_job` with `wait: true` picks it up. Ask the assistant to keep checking until it is done. - A remix takes about 20 to 30 seconds and an effect under half a minute. Extend, replace and cover take about as long as a song. - `flowmusic_write_lyrics` answers in about 30 seconds and `flowmusic_split_stems` in 15 to 60 seconds. If a stem split takes longer, call it again a minute later: a clip that is already split returns its stems at once. Clients that ask for progress notifications get one about every 10 seconds while a tool waits. Each clip comes back with its id and public `m4a` and `wav` links. The `mp3` comes through [GET /music/download](/docs/api-flowmusic-v1/get-flowmusic-music-download) with the same `Authorization` header. ## Example prompts - "Write lyrics for an upbeat song about a dog named Biscuit who loves the beach, then make it as indie pop with a warm female vocal." - "Make a 2-minute lo-fi hip hop instrumental for studying, using Lyria 3.5." - "Extend my last song by 30 seconds with an outro that fades out." - "Make a slow bossa nova cover of that song." - "Re-sing the second verse with these new lyrics: …" - "Split the song into stems and give me the vocals track." - "How many Flow Music credits are left on my accounts?" ## Limits and notes - The tools use your Flow Music accounts and the same rules as the REST API, such as `maxJobs`. Songs and edits use the account's Flow Music credits, see the cost calculator on the [FlowMusic API](/docs/api-flowmusic-v1) page. - A client may send up to 20 JSON-RPC requests in one batch. - If the client sends an `MCP-Protocol-Version` header, it must be one of the supported versions: `2025-06-18`, `2025-03-26` or `2024-11-05`. - Tool calls show in your [usage stats](/docs/account-management/get-account-stats) (`bot=flowmusic`) through the REST call each tool makes, the same rows a direct API request writes. === URL: https://useapi.net/docs/api-flowmusic-v1/post-flowmusic-accounts === Document URL: https://useapi.net/docs/api-flowmusic-v1/post-flowmusic-accounts --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> accounts description: "Add or refresh a Flow Music account via POST accounts in the useapi.net FlowMusic API v1 — provide a refresh token to add access, or update maxJobs on an existing account by email." parent: Flow Music API nav_order: 100 permalink: /docs/api-flowmusic-v1/post-flowmusic-accounts --- ## Configure a Flow Music account June 3, 2026 (November 16, 2026) --- Configure a [Flow Music](https://www.flowmusic.app) account for API access using its refresh token. See [Setup Flow Music](/docs/start-here/setup-flowmusic) for how to obtain the token. Each [useapi.net subscription](/docs/subscription) lets you connect 3 Flow Music accounts, up to 100 in total. To change an account's concurrency limit later, re-POST with just `email` + `maxJobs` (no token) — see **Request Body** below. > **https://api.useapi.net/v1/flowmusic/accounts** ### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Request Body **Add or refresh an account** — provide the `refresh_token`: ```json { "refresh_token": "bdykxtrr5eaf...", "maxJobs": 12 } ``` - `refresh_token` is **required** to add or refresh, the flowmusic.app refresh token (≥10 chars). See [Setup Flow Music](/docs/start-here/setup-flowmusic). - `maxJobs` is optional, the max concurrent jobs for this account, 1–16 (defaults to the plan tier). - The plan tier is read from Flow Music each time you add or refresh the account. The Flow Music plan included with [Google AI Plus](https://support.google.com/googleone/answer/16882689), [Pro](https://support.google.com/googleone/answer/14534406) or [Ultra](https://support.google.com/googleone/answer/16286513) reads as `starter`, `plus` or `member`. If you link the Google AI subscription to Flow Music after adding the account, add it again so the tier and the default `maxJobs` follow. **Update `maxJobs` on an existing account** — provide `email` + `maxJobs`, with no `refresh_token`: ```json { "email": "user@email.com", "maxJobs": 4 } ``` - `email` is **required** for this mode — an already-configured account. - `maxJobs` is **required** here, 1–16. Only this field is updated; no token refresh happens. Send nothing else alongside `email`. ### Responses **200** **200 OK** — existing account updated. ```json { "email": "user@email.com", "tier": "plus", "subscription_plan": "plus-monthly", "provider": "g1_entitlement", "user_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", "maxJobs": 12, "added": "2026-06-01T12:00:00.000Z", "refreshed_at": "2026-06-01T12:00:00.000Z", "refreshed_count": 0, "access_token": "eyJ…redacted…zmQ", "access_token_expires_at": "2026-06-01T13:00:00.000Z", "refresh_token": "l6e…redacted…z4v", "session_id": "f0e1d2c3-b4a5-4768-9a0b-1c2d3e4f5a6b" } ``` - Credit balances are not included here — fetch them live from [GET /accounts/`email`](/docs/api-flowmusic-v1/get-flowmusic-accounts-email). **201** **201 Created** — new account configured. Same body as `200`. **400** **400** — add mode: missing/invalid `refresh_token`, or the token failed to refresh. Update mode: `maxJobs` missing or outside 1–16, or `email` sent together with `refresh_token`. ```json { "error": "maxJobs is required when updating an account by email", "code": 400 } ``` **404** **404** — update mode: no account is configured for the given `email`. ```json { "error": "Account user@email.com not found", "code": 404 } ``` **401** **401 Unauthorized** — invalid API token. ### Model `200` (updated) and `201` (created) return the same account record. <details markdown="block" class="model-details"> <summary>The account record, field by field</summary> ```typescript { email: string tier: 'free' | 'starter' | 'plus' | 'member' | 'unknown' subscription_plan?: string // paid tiers only provider?: string // paid tiers only user_id: string // the account's user UUID maxJobs: number added: string // ISO 8601 timestamp refreshed_at: string // ISO 8601 timestamp refreshed_count: number access_token: string // redacted access_token_expires_at: string // ISO 8601 timestamp refresh_token: string // redacted session_id: string error?: string // present only when the account needs re-authentication } ``` </details> ### Examples **Curl** ``` bash curl -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -X POST "https://api.useapi.net/v1/flowmusic/accounts" \ -d '{ "refresh_token": "bdykxtrr5eaf...", "maxJobs": 12 }' ``` **Python** ``` python import requests response = requests.post( 'https://api.useapi.net/v1/flowmusic/accounts', headers={'Authorization': 'Bearer YOUR_API_TOKEN'}, json={'refresh_token': 'bdykxtrr5eaf...', 'maxJobs': 12} ) print(response.status_code, response.json()) ``` ### Try It <script> async function apiTestPostAccountsFlowMusic() { const refresh_token = document.getElementById('post-accounts-FlowMusic-refresh_token')?.value; const email = document.getElementById('post-accounts-FlowMusic-email')?.value; const maxJobs = document.getElementById('post-accounts-FlowMusic-maxJobs')?.value; const payload = {}; if (refresh_token) payload.refresh_token = refresh_token; if (email) payload.email = email; if (maxJobs) payload.maxJobs = parseInt(maxJobs); const data = { method: 'POST', headers: { 'Authorization': `Bearer ${document.getElementById('post-accounts-FlowMusic-token').value}`, 'Content-Type': 'application/json' }, body: JSON.stringify(payload) }; await apiExecute(`https://api.useapi.net/v1/flowmusic/accounts`, 'post-accounts-FlowMusic', data); } </script> <form id="post-accounts-FlowMusic" onsubmit="return false;" class="input-form"> <div class="input-field"> <div class="input-field-row"> <label for="post-accounts-FlowMusic-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="post-accounts-FlowMusic-token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> <label for="post-accounts-FlowMusic-refresh_token"><span>refresh_token (add mode — see <a href="/docs/start-here/setup-flowmusic">Setup Flow Music</a>)</span> <input id="post-accounts-FlowMusic-refresh_token" type="text" class="input-element" oninput="this.size = this.value.length"> </label> <label for="post-accounts-FlowMusic-email"><span>email (update mode — existing account)</span> <input id="post-accounts-FlowMusic-email" type="text" class="input-element" placeholder="user@email.com"> </label> <label for="post-accounts-FlowMusic-maxJobs"><span>maxJobs (optional to add / required to update, 1–16)</span> <input id="post-accounts-FlowMusic-maxJobs" type="number" class="input-element" min="1" max="16" oninput="this.size = this.value.length"> </label> </div> <button id="post-accounts-FlowMusic-button" class="btn btn-primary fs-3" type="submit" onclick="apiTestPostAccountsFlowMusic()">Go</button> </div> </form> <div id="post-accounts-FlowMusic-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-flowmusic-v1/post-flowmusic-files-generate === Document URL: https://useapi.net/docs/api-flowmusic-v1/post-flowmusic-files-generate --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> files/generate description: "Generate an AI image from a prompt via POST files/generate in the useapi.net FlowMusic API v1 — returns a refImage asset ID for use as a style reference in song generation." parent: Flow Music API nav_order: 310 permalink: /docs/api-flowmusic-v1/post-flowmusic-files-generate --- ## Generate an AI image June 3, 2026 (November 16, 2026) --- Generate an AI image from a text prompt. Returns an encoded image asset ID — the same shape [POST /files](/docs/api-flowmusic-v1/post-flowmusic-files) returns for an uploaded image — that you can pass as a reference image (`refImage1…`) to [POST /music](/docs/api-flowmusic-v1/post-flowmusic-music). > **https://api.useapi.net/v1/flowmusic/files/generate** ### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Request Body ```json { "prompt": "abstract neon city skyline at night" } ``` - `email` is optional, which configured account to use. - `prompt` is **required**, the image description. 1–2,000 characters. ### Responses **200** **200 OK** ```json { "id": "user:1234-user@email.com-image:...", "url": "https://storage.googleapis.com/producer-app-public/assets/....jpg", "kind": "image", "assetType": "image", "email": "user@email.com", "width": 1024, "height": 1024, "model": "google-generative-ai" } ``` **400** **400** — missing/empty prompt. **401** **401 Unauthorized** — invalid API token. **500** **500** — Flow Music declined the request. The most common cause is a moderated or otherwise disallowed prompt: Flow Music returns a generic `Internal Server Error` (it does not say why) and we pass it through verbatim. Retry with a different prompt — if a clearly benign prompt still fails, it is likely a transient upstream error. ```json { "error": "FlowMusic image generation failed (500): \"Internal Server Error\"", "code": 500 } ``` **596** **596 Account Error** The account targeted by `email` is in an error state and can't be used — re-add it via [POST /accounts](/docs/api-flowmusic-v1/post-flowmusic-accounts). The `error` field returns whatever reason was recorded for the account. ```json { "error": "Account user@email.com in error state: refresh token rejected", "code": 596 } ``` ### Model The generated image's asset `id`, to pass as a reference image to [POST /music](/docs/api-flowmusic-v1/post-flowmusic-music), with its URL, width, height and image model. <details markdown="block" class="model-details"> <summary>The generated image, field by field</summary> ```typescript { id: string // encoded image asset id — usable as refImage1… in POST /music url: string kind: 'image' assetType: 'image' email: string width: number height: number model: string // the image model, e.g. 'google-generative-ai' } ``` </details> ### Examples **Curl** ``` bash curl -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -X POST "https://api.useapi.net/v1/flowmusic/files/generate" \ -d '{ "prompt": "abstract neon city skyline at night" }' ``` **Python** ``` python import requests response = requests.post( 'https://api.useapi.net/v1/flowmusic/files/generate', headers={'Authorization': 'Bearer YOUR_API_TOKEN'}, json={'prompt': 'abstract neon city skyline at night'} ) print(response.status_code, response.json()) ``` ### Try It <script> function displayFlowMusicImage(response, elementId) { const container = document.getElementById(`${elementId}-media-links`); if (!container) return; container.innerHTML = ''; if (!response.url) { container.style.display = 'none'; return; } const u = response.url; container.innerHTML = `<div style="margin:6px 0;"><a href="${u}" target="_blank" rel="noopener noreferrer" title="Open full image in a new tab"><img src="${u}" alt="generated image" style="max-width:256px;border-radius:6px;cursor:zoom-in;"></a></div>`; container.style.display = 'block'; } async function apiTestFilesGenerateFlowMusic() { const elementId = 'post-files-generate-FlowMusic'; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${document.getElementById('post-files-generate-FlowMusic-token').value}`, 'Content-Type': 'application/json' } }; let email = document.getElementById(`post-files-generate-FlowMusic-email`)?.value; let prompt = document.getElementById(`post-files-generate-FlowMusic-prompt`)?.value; const url = `https://api.useapi.net/v1/flowmusic/files/generate`; data.body = JSON.stringify({ ...(email ? { email } : {}), prompt }); const mediaLinks = document.getElementById(`${elementId}-media-links`); if (mediaLinks) mediaLinks.style.display = 'none'; const status = await apiExecute(url, elementId, data, { includeTimer: true }); if (status === 200) { try { const response = JSON.parse(document.getElementById(`${elementId}-response-json`).innerText); displayFlowMusicImage(response, elementId); } catch (e) { console.error('Failed to parse response for image display:', e); } } } </script> <form id="post-files-generate-FlowMusic" onsubmit="return false;" class="input-form"> <div class="input-field"> <div class="input-field-row"> <label for="post-files-generate-FlowMusic-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="post-files-generate-FlowMusic-token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> <label for="post-files-generate-FlowMusic-email"><span>email (optional)</span> <input id="post-files-generate-FlowMusic-email" type="text" class="input-element" placeholder="user@email.com"> </label> <label for="post-files-generate-FlowMusic-prompt"><span>prompt</span> <textarea id="post-files-generate-FlowMusic-prompt" class="input-element" rows="3" required aria-required="true" style="resize: both;"></textarea> </label> </div> <button id="post-files-generate-FlowMusic-button" class="btn btn-primary fs-3" type="submit" onclick="apiTestFilesGenerateFlowMusic()">Go</button> </div> </form> <div id="post-files-generate-FlowMusic-media-links" style="display:none;"></div> <div id="post-files-generate-FlowMusic-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-flowmusic-v1/post-flowmusic-files === Document URL: https://useapi.net/docs/api-flowmusic-v1/post-flowmusic-files --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> files description: "Upload a reference image or audio file via POST files in the useapi.net FlowMusic API v1 — returns an asset ID for use as refImage/refAudio in song generation." parent: Flow Music API nav_order: 300 permalink: /docs/api-flowmusic-v1/post-flowmusic-files --- ## Upload a file June 3, 2026 (November 16, 2026) --- Upload a reference image or audio file. The file is sent as the **raw request body**, with its MIME type in the `Content-Type` header (no multipart, no form fields). Returns an encoded asset ID you can pass to [POST /music](/docs/api-flowmusic-v1/post-flowmusic-music) (`refImage1…`/`refAudio1…`). > **https://api.useapi.net/v1/flowmusic/files** ### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: {file MIME type} # see supported types below ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. The request body **is** the file's raw bytes. | Content-Type | File Extension | Max size | | ------------ | -------------- | -------- | | image/jpeg | jpg | 20 MB | | image/png | png | 20 MB | | image/webp | webp | 20 MB | | audio/mpeg | mp3 | 40 MB | | audio/wav | wav | 40 MB | | audio/mp4 | m4a | 40 MB | | audio/x-m4a | m4a | 40 MB | | audio/aac | m4a | 40 MB | ### Query Parameters - `email` is optional, which configured account to use. - `stripMetadata` is optional, default `true` — strips AI-provenance / EXIF metadata from images before upload (Flow Music's edge rejects images that declare AI-generated provenance). Set `false` to keep the original bytes. ### Responses **200** **200 OK** ```json { "id": "user:1234-user@email.com-image:34cd56ef-...", "url": "https://storage.googleapis.com/...", "kind": "image", "assetType": "image", "email": "user@email.com", "metadata_stripped": true } ``` Audio uploads also include `clip_id`, `operation_id`, `is_flagged`, and `duration_s` when available. **400** **400** — unsupported Content-Type, empty body, or magic-byte mismatch (declared type ≠ actual bytes). ```json { "error": "Content-Type (application/octet-stream) not supported. Valid values: image/jpeg, image/png, ...", "code": 400 } ``` **401** **401 Unauthorized** — invalid API token. **413** **413** — file exceeds the size cap. **422** **422** — image declares AI-generated provenance metadata and `stripMetadata=false` was set. Remove the flag (default strips it) or re-save the image without metadata. **500** **500** — FlowMusic rejected the upload or hit an internal error. Image moderation (e.g. NSFW) surfaces here as a `flowmusic_error`. The `upstream` block preserves the evidence — quote `cf_ray` to support. ```json { "error": "Upload failed (HTTP 500): FlowMusic: \"Internal Server Error\"", "code": 500, "upstream": { "status": 500, "cause": "flowmusic_error", "cf_ray": "a05b815ef02cf9cc-SJC", "server": "cloudflare", "content_type": "application/json" } } ``` **596** **596 Account Error** The account targeted by `email` is in an error state and can't be used — re-add it via [POST /accounts](/docs/api-flowmusic-v1/post-flowmusic-accounts). The `error` field returns whatever reason was recorded for the account. ```json { "error": "Account user@email.com in error state: refresh token rejected", "code": 596 } ``` ### Model The uploaded file's asset `id`, to pass to [POST /music](/docs/api-flowmusic-v1/post-flowmusic-music) as a reference, with its storage URL and `kind` (image or audio). <details markdown="block" class="model-details"> <summary>The uploaded image or audio file, field by field</summary> ```typescript { id: string // encoded asset id — user:<id>-<email>-<image|audio>:<uuid> url: string // Flow Music storage URL kind: 'image' | 'audio' assetType: 'image' | 'audio' email: string metadata_stripped?: boolean // images only — whether AI-provenance metadata was stripped clip_id?: string | null // audio only operation_id?: string | null // audio only is_flagged?: boolean | null // audio only duration_s?: number | null // audio only } ``` </details> ### Examples **Curl** ``` bash curl -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: image/png" \ -X POST "https://api.useapi.net/v1/flowmusic/files" \ --data-binary "@image.png" ``` **JavaScript** ``` javascript const bytes = await (await fetch('image.png')).arrayBuffer(); const response = await fetch('https://api.useapi.net/v1/flowmusic/files', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_TOKEN', 'Content-Type': 'image/png' }, body: bytes }); console.log(await response.json()); ``` **Python** ``` python import requests data = open('image.png', 'rb').read() response = requests.post( 'https://api.useapi.net/v1/flowmusic/files', headers={'Authorization': 'Bearer YOUR_API_TOKEN', 'Content-Type': 'image/png'}, data=data ) print(response.status_code, response.json()) ``` ### Try It <script> async function apiTestFilesFlowMusic() { const responseEl = document.getElementById('post-files-FlowMusic-response'); const file = document.getElementById('post-files-FlowMusic-file')?.files?.[0]; if (!file) { responseEl.classList.remove('visible-false'); responseEl.classList.add('visible-true'); responseEl.innerHTML = '<div class="response-status http-status-bad">Choose a file first</div>'; return; } const email = document.getElementById('post-files-FlowMusic-email')?.value; const stripMetadata = document.getElementById('post-files-FlowMusic-stripMetadata')?.value; const qs = new URLSearchParams(); if (email) qs.set('email', email); if (stripMetadata) qs.set('stripMetadata', stripMetadata); const url = `https://api.useapi.net/v1/flowmusic/files` + (qs.toString() ? `?${qs.toString()}` : ''); const data = { method: 'POST', headers: { 'Authorization': `Bearer ${document.getElementById('post-files-FlowMusic-token').value}`, 'Content-Type': file.type }, body: file }; await apiExecute(url, 'post-files-FlowMusic', data); } </script> <form id="post-files-FlowMusic" onsubmit="return false;" class="input-form"> <div class="input-field"> <div class="input-field-row"> <label for="post-files-FlowMusic-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="post-files-FlowMusic-token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> <label for="post-files-FlowMusic-email"><span>email (optional)</span> <input id="post-files-FlowMusic-email" type="text" class="input-element" oninput="this.size = this.value.length"> </label> <label for="post-files-FlowMusic-stripMetadata"><span>stripMetadata (optional)</span> <select id="post-files-FlowMusic-stripMetadata" class="input-element"> <option value="">default (true)</option> <option value="false">false — keep original bytes</option> </select> </label> <label for="post-files-FlowMusic-file"><span>file (image or audio)</span> <input id="post-files-FlowMusic-file" type="file" class="input-element" accept="image/jpeg,image/png,image/webp,audio/mpeg,audio/wav,audio/mp4,audio/aac" required aria-required="true"> </label> </div> <button id="post-files-FlowMusic-button" class="btn btn-primary fs-3" type="submit" onclick="apiTestFilesFlowMusic()">Go</button> </div> </form> <div id="post-files-FlowMusic-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-flowmusic-v1/post-flowmusic-music-edit === Document URL: https://useapi.net/docs/api-flowmusic-v1/post-flowmusic-music-edit --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> music/edit description: "Edit a generated clip via POST music/edit in the useapi.net FlowMusic API v1 — cover, remix, extend, replace, apply audio effects, or separate into stems." parent: Flow Music API nav_order: 210 permalink: /docs/api-flowmusic-v1/post-flowmusic-music-edit --- ## Edit a song June 3, 2026 (November 16, 2026) --- Edit an existing clip — the `operation` field selects one of six edit kinds, each taking a `clip` (an encoded clip asset ID from a previous generation or [GET /music](/docs/api-flowmusic-v1/get-flowmusic-music)). `operation` is **required** — one of: | `operation` | What it does | Required params | Optional params | | ----------- | ------------ | --------------- | --------------- | | `effect` | Apply one audio effect | `effect` + that effect's scalar param(s) | — | | `extend` | Add new music to the end, or from a point | `instruction` | `extend_s`, `extend_from_s` | | `replace` | Regenerate a time section | `instruction`, `mask_start_s`, `mask_end_s` | — | | `cover` | Restyle the whole song (a Lyria cover) | — | `instruction`, `strength`, `model` | | `remix` | Re-sing with edited lyrics | `lyrics` | `prompt` | | `stems` | Separate into 4 stem clips (drums/bass/vocals/other) | — | — | > **https://api.useapi.net/v1/flowmusic/music/edit** ### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Request Body Every operation accepts these common fields (there is no `email` — the `clip` already identifies its account, and the edit runs there): - `clip` is **required**, the encoded clip asset ID to edit. - `seed` is optional, an integer ≥ 0 — pins the result for reproducibility. - `title` is optional, a title for the result clip. - `model` is optional, the music model used to re-render. Supported values: `lyria-3.5` and `lyria-3-pro` (default). It is sent with the operations that re-synthesise audio — `cover`, `extend`, `replace`, and `remix`. `effect` and `stems` accept it but their output is unaffected, because those are signal processing and stem separation with no music model in the loop. Omitting it keeps the behaviour that existed before the parameter was added. - `mode` is optional, `sync` (default) or `async`. In `sync` the request waits for the edit and returns `200` with the finished record (or the job's error code). Only an edit that is still not finished after 2 minutes (7 minutes for `remix`) returns `202` with the job in `status: "pending"` — fetch the result with [GET /jobs/`jobid`](/docs/api-flowmusic-v1/get-flowmusic-jobs-jobid) or wait for the `replyUrl` webhook. The edit keeps rendering on our side even if your connection drops. `async` returns `201` with a `jobid` at once. Ignored by `stems`, which is always sync. - `replyUrl` is optional, a webhook URL — the job record is POSTed to it when the edit completes or fails. Ignored by `stems`. - `replyRef` is optional, a custom reference string echoed back in the webhook. Plus the chosen operation's own fields, below. #### operation: `effect` `effect` is one of `Trim`, `Fade`, `Gain`, `Reverb`, `Pan`, `Equalizer`. Each effect reads only its own flat scalar params (sending a param for a different effect is ignored): - `Gain` — `gain_db` (−30 … 30). - `Reverb` — `mix`, `room_size` (0 … 1 each). - `Pan` — `pan` (−1 left … 1 right). - `Equalizer` — `bass_db`, `mid_db`, `treble_db` (−12 … 12 each). - `Fade` — `fade_in_s`, `fade_out_s` (≥ 0, at least one > 0). - `Trim` — `start_s`, `end_s` (`end_s` > `start_s`, ≤ duration). ```json { "operation": "effect", "clip": "user:1234-user@email.com-clip:...", "effect": "Reverb", "mix": 0.4, "room_size": 0.7 } ``` #### operation: `extend` ```json { "operation": "extend", "clip": "user:1234-...-clip:...", "instruction": "add an instrumental outro", "extend_s": 30 } ``` - `instruction` is **required**, what to add. - `extend_s` is optional, seconds to add, 1–300 (default 150). - `extend_from_s` is optional, the point to extend from (default = end of clip). #### operation: `replace` ```json { "operation": "replace", "clip": "user:1234-...-clip:...", "instruction": "softer piano in this section", "mask_start_s": 0, "mask_end_s": 8 } ``` - `instruction` is **required**, how to regenerate the section. - `mask_start_s` is **required**, the section start (seconds). - `mask_end_s` is **required**, the section end (seconds), > `mask_start_s`, ≤ duration. #### operation: `cover` Restyle the entire song. `instruction` is **optional** (a free-text style direction); `strength` is the cover-strength slider. ```json { "operation": "cover", "clip": "user:1234-...-clip:...", "instruction": "lo-fi chillhop reinterpretation", "strength": 0.7 } ``` - `instruction` is optional, a free-text style direction. - `strength` is optional, 0 … 1 (default 1). #### operation: `remix` Re-sing the song with **edited lyrics**. By default it reuses the source song's sound prompt; override with `prompt`. The edited lyrics round-trip into the result clip's `lyrics`. ```json { "operation": "remix", "clip": "user:1234-...-clip:...", "lyrics": "[Verse 1]\nNeon rain on the avenue\n[Chorus]\nWe rise again", "prompt": "dreamy synthwave, 100 bpm" } ``` - `lyrics` is **required**, the edited lyrics, `[Verse]`/`[Chorus]`-tagged. - `prompt` is optional, a sound-prompt override (defaults to the source clip's). #### operation: `stems` Separate the song into its individual tracks. Flow Music runs the split server-side and creates **4 new clips** — `drums`, `bass`, `vocals`, `other` — each a normal clip with its own id and a public `audio_url`/`wav_url`. Only `clip` is needed. ```json { "operation": "stems", "clip": "user:1234-...-clip:..." } ``` - `stems` is **synchronous** — the request blocks while the split runs, usually ~15–60 s, then returns all four stems in one reply (it ignores `mode`/`replyUrl`/`replyRef`). If the split is not done after 2 minutes, it answers `504`. The split keeps running at Flow Music, so send the same request again a little later. Re-running on an already-split clip returns its stems immediately. - Download any stem with [GET /music/download](/docs/api-flowmusic-v1/get-flowmusic-music-download) (mp3) or its `audio_url`/`wav_url`. Its response differs from the other edits — it's a flat manifest of the stem clips, not a job record: ```json { "email": "user@email.com", "operation": "stems", "source_clip": "user:1234-...-clip:...", "status": "completed", "clips": [ { "stem_type": "drums", "clip": "user:1234-...-clip:...", "title": "Song - drums", "duration_s": 173.0, "audio_url": "https://storage.googleapis.com/...1a2b3c4d.m4a", "wav_url": "https://storage.googleapis.com/...1a2b3c4d.wav", "image_url": null } ] } ``` (four entries — `drums`, `bass`, `vocals`, `other`). ### Responses Same job-record shape as [POST /music](/docs/api-flowmusic-v1/post-flowmusic-music) — `operation` echoes the requested edit kind. (`operation: stems` is the exception — it returns the flat stem manifest shown above, not a job record.) **200** **200 OK** **Sync mode** (default) — the edit is rendered and the full record is returned inline. ```json { "jobid": "job:aaaabbbb-cccc-4ddd-8eee-ffff99990000-user:1234-user@email.com-bot:flowmusic", "email": "user@email.com", "operation": "cover", "status": "completed", "created_at": "2026-06-01T18:40:42.412Z", "completed_at": "2026-06-01T18:41:37.432Z", "duration_ms": 55020, "clips": [ { "clip": "user:1234-user@email.com-clip:c3d4e5f6-a7b8-4c9d-0e1f-2a3b4c5d6e7f", "title": "Morning Sun (Cover)", "duration_s": 171.02, "lyrics": "[Verse 1]\nCity lights blur in the rain\n[Chorus]\nAnd I will wait for the morning sun", "seed": 123456, "lyrics_timing": [ [0.0, 2.4], [2.4, 5.1] ], "created_at": "2026-06-01T18:41:30.118Z", "audio_url": "https://storage.googleapis.com/...c3d4e5f6.m4a", "wav_url": "https://storage.googleapis.com/...c3d4e5f6.wav", "image_url": "https://storage.googleapis.com/...d4e5f6a7.jpg" } ], "request": { "operation": "cover", "clip": "user:1234-user@email.com-clip:...", "strength": 0.7 } } ``` **201** **201 Created** **Async mode** (`"mode": "async"`) — the edit is queued and returned immediately as `pending`. Poll [GET /jobs/`jobid`](/docs/api-flowmusic-v1/get-flowmusic-jobs-jobid) until `status` is `completed` or `failed`. ```json { "jobid": "job:aaaabbbb-cccc-4ddd-8eee-ffff99990000-user:1234-user@email.com-bot:flowmusic", "email": "user@email.com", "operation": "remix", "status": "pending", "created_at": "2026-06-01T18:40:42.412Z", "request": { "operation": "remix", "clip": "user:1234-...-clip:...", "lyrics": "[Verse 1]\n...", "mode": "async" } } ``` **202** **202 Accepted** Sync mode only, and rare. The edit was still not finished after 2 minutes (7 minutes for `remix`), so the job is returned as it stands, `pending`. It keeps rendering: poll [GET /jobs/`jobid`](/docs/api-flowmusic-v1/get-flowmusic-jobs-jobid) until `status` is `completed` or `failed`, or wait for the `replyUrl` webhook. ```json { "jobid": "job:aaaabbbb-cccc-4ddd-8eee-ffff99990000-user:1234-user@email.com-bot:flowmusic", "email": "user@email.com", "operation": "cover", "status": "pending", "created_at": "2026-06-01T18:40:42.412Z", "request": { "operation": "cover", "clip": "user:1234-user@email.com-clip:...", "strength": 0.7 } } ``` **400** **400 Bad Request** Validation error — an unknown `operation`, a missing required field for the chosen operation (e.g. `replace` without `mask_start_s`/`mask_end_s`, or `effect` without `effect`), or a `clip` that isn't a clip-type asset ID. ```json { "error": "instruction required for operation=extend", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "Unauthorized", "code": 401 } ``` **402** **402 Payment Required** The targeted Flow Music account has insufficient credits to complete the edit. Top up its credit balance (or target a funded account with `email`), then retry. ```json { "error": "recipes/create failed (402): {\"detail\":\"User has insufficient credits\"}", "code": 402 } ``` **404** **404** The `clip`'s account isn't configured under your useapi.net account, or the source clip no longer exists on Flow Music. ```json { "error": "source clip not found on FlowMusic", "code": 404 } ``` **422** **422** The edit produced no audio (e.g. a content-moderation refusal — a terminal `status: "failed"` record), or the source clip can't be edited (an uploaded clip has no `conversation_id`). ```json { "jobid": "job:aaaabbbb-cccc-4ddd-8eee-ffff99990000-user:1234-user@email.com-bot:flowmusic", "email": "user@email.com", "operation": "cover", "status": "failed", "created_at": "2026-06-01T18:40:42.412Z", "completed_at": "2026-06-01T18:41:10.512Z", "error": { "code": "moderation_reject", "message": "the model declined to generate audio for this edit" }, "request": { "operation": "cover", "clip": "user:1234-...-clip:..." } } ``` **429** **429 Too Many Requests** Passed through from Flow Music when the `clip`'s account is already running too many concurrent jobs — retry once one finishes. ```json { "error": "producer/tool-call failed (429): {\"detail\":\"Too Many Requests\"}", "code": 429 } ``` **504** **504 Gateway Timeout** `operation: stems` only: the split did not finish within 2 minutes. It keeps running at Flow Music, so send the same request again a little later, and a clip already split returns its stems at once. ```json { "error": "stem separation did not complete in time — retry shortly", "code": 504 } ``` **596** **596 Account Error** The `clip`'s account is in an error state and can't be used — re-add it via [POST /accounts](/docs/api-flowmusic-v1/post-flowmusic-accounts). ```json { "error": "Account user@email.com in error state: refresh token rejected", "code": 596 } ``` ### Model Same job-record shape as [POST /music](/docs/api-flowmusic-v1/post-flowmusic-music), plus a top-level `operation`. The `request` echoes the edit body you submitted. (`operation: stems` returns a flat manifest of the 4 stem clips instead — see [operation: stems](#operation-stems).) <details markdown="block" class="model-details"> <summary>The edit job record for each status, field by field</summary> **200 Completed** ```typescript { jobid: string // job:<uuid>-user:<id>-<email>-bot:flowmusic email: string operation: 'effect' | 'extend' | 'replace' | 'cover' | 'remix' | 'stems' status: 'completed' | 'pending' | 'failed' created_at: string // ISO 8601 timestamp completed_at?: string // present when terminal duration_ms?: number // wall-clock render time clips: Array<{ clip: string // encoded clip asset id — use with /music/download and /music/edit title: string | null duration_s: number | null lyrics: string | null // [Verse]/[Chorus]-tagged; "[Instrumental]" for instrumentals seed: number | null lyrics_timing: Array<[number, number]> | null // timing markers, [start, end] seconds (vocal clips) created_at: string // ISO 8601 timestamp audio_url: string // m4a download URL wav_url: string // wav download URL image_url: string | null // auto-generated artwork URL }> request: { // the edit body you submitted, echoed back verbatim operation: 'effect' | 'extend' | 'replace' | 'cover' | 'remix' | 'stems' clip: string model?: 'lyria-3.5' | 'lyria-3-pro' // cover/extend/replace/remix — inert on effect/stems seed?: number // common — pins the result title?: string // common mode?: 'sync' | 'async' // common replyUrl?: string // common — webhook replyRef?: string // common — webhook reference effect?: 'Trim' | 'Fade' | 'Gain' | 'Reverb' | 'Pan' | 'Equalizer' // effect gain_db?: number // effect=Gain (-30..30) mix?: number // effect=Reverb (0..1) room_size?: number // effect=Reverb (0..1) pan?: number // effect=Pan (-1..1) bass_db?: number // effect=Equalizer (-12..12) mid_db?: number // effect=Equalizer (-12..12) treble_db?: number // effect=Equalizer (-12..12) fade_in_s?: number // effect=Fade fade_out_s?: number // effect=Fade start_s?: number // effect=Trim end_s?: number // effect=Trim instruction?: string // extend / replace / cover extend_s?: number // extend (1..300) extend_from_s?: number // extend mask_start_s?: number // replace mask_end_s?: number // replace strength?: number // cover (0..1) lyrics?: string // remix prompt?: string // remix } } ``` **201 202 Pending** ```typescript { jobid: string // job:<uuid>-user:<id>-<email>-bot:flowmusic email: string operation: 'effect' | 'extend' | 'replace' | 'cover' | 'remix' | 'stems' status: 'pending' created_at: string // ISO 8601 timestamp request: { } // the edit body you submitted — same shape as the 200 (Completed) model above } ``` </details> ### Examples **Curl** ``` bash # Cover (restyle) — instruction optional curl -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -X POST "https://api.useapi.net/v1/flowmusic/music/edit" \ -d '{ "operation": "cover", "clip": "user:1234-user@email.com-clip:...", "strength": 0.7 }' ``` **JavaScript** ``` javascript const response = await fetch('https://api.useapi.net/v1/flowmusic/music/edit', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_TOKEN', 'Content-Type': 'application/json' }, body: JSON.stringify({ operation: 'remix', clip: 'user:1234-user@email.com-clip:...', lyrics: '[Verse 1]\nNeon rain on the avenue\n[Chorus]\nWe rise again' }) }); console.log(await response.json()); ``` **Python** ``` python import requests response = requests.post( 'https://api.useapi.net/v1/flowmusic/music/edit', headers={'Authorization': 'Bearer YOUR_API_TOKEN'}, json={'operation': 'effect', 'clip': 'user:1234-user@email.com-clip:...', 'effect': 'Gain', 'gain_db': 6} ) print(response.status_code, response.json()) ``` ### Try It <script> function displayFlowMusicClips(response, elementId) { const container = document.getElementById(`${elementId}-media-links`); if (!container) return; container.innerHTML = ''; const clips = response.clips || []; if (clips.length === 0) { container.style.display = 'none'; return; } container.innerHTML = '<div class="media-links-container"><strong>Result clips:</strong></div>' + clips.map((c, i) => { const title = c.stem_type ? `${c.title || ('Stem ' + (i + 1))} (${c.stem_type})` : (c.title || `Clip ${i + 1}`); const cover = c.image_url ? `<a href="${c.image_url}" target="_blank" rel="noopener noreferrer" title="Open full image in a new tab"><img src="${c.image_url}" alt="cover" style="max-width:96px;border-radius:6px;vertical-align:middle;margin-right:8px;cursor:zoom-in;"></a>` : ''; const audio = c.audio_url ? `<audio src="${c.audio_url}" controls style="vertical-align:middle;"></audio>` : ''; return `<div style="margin:6px 0;">${cover}${audio}<div>${escHtml(title)}</div></div>`; }).join(''); container.style.display = 'block'; } async function apiTestMusicEditFlowMusic() { const data = { method: 'POST', headers: { 'Authorization': `Bearer ${document.getElementById('post-music-edit-FlowMusic-token').value}`, 'Content-Type': 'application/json' } }; const v = (id) => document.getElementById(`post-music-edit-FlowMusic-${id}`)?.value?.trim(); const str = (id) => { const x = v(id); return x ? x : undefined; }; const num = (id) => { const x = v(id); return x ? parseFloat(x) : undefined; }; const seedVal = v('seed'); const body = { operation: v('operation'), clip: v('clip'), model: str('model'), seed: seedVal ? parseInt(seedVal) : undefined, title: str('title'), mode: str('mode'), replyUrl: str('replyUrl'), replyRef: str('replyRef'), effect: str('effect'), gain_db: num('gain_db'), mix: num('mix'), room_size: num('room_size'), pan: num('pan'), bass_db: num('bass_db'), mid_db: num('mid_db'), treble_db: num('treble_db'), fade_in_s: num('fade_in_s'), fade_out_s: num('fade_out_s'), start_s: num('start_s'), end_s: num('end_s'), instruction: str('instruction'), extend_s: num('extend_s'), extend_from_s: num('extend_from_s'), mask_start_s: num('mask_start_s'), mask_end_s: num('mask_end_s'), strength: num('strength'), lyrics: str('lyrics'), prompt: str('prompt') }; data.body = JSON.stringify(body); const mediaLinks = document.getElementById('post-music-edit-FlowMusic-media-links'); if (mediaLinks) mediaLinks.style.display = 'none'; const status = await apiExecute(`https://api.useapi.net/v1/flowmusic/music/edit`, 'post-music-edit-FlowMusic', data); if (status === 200) { try { const response = JSON.parse(document.getElementById('post-music-edit-FlowMusic-response-json').innerText); displayFlowMusicClips(response, 'post-music-edit-FlowMusic'); } catch (e) { console.error('clip display failed', e); } } } </script> <form id="post-music-edit-FlowMusic" onsubmit="return false;" class="input-form"> <div class="input-field"> <div class="input-field-row"> <label for="post-music-edit-FlowMusic-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="post-music-edit-FlowMusic-token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> <label for="post-music-edit-FlowMusic-operation"><span>operation (required)</span> <select id="post-music-edit-FlowMusic-operation" class="input-element" required aria-required="true"> <option value="effect">effect</option> <option value="extend">extend</option> <option value="replace">replace</option> <option value="cover">cover</option> <option value="remix">remix</option> <option value="stems">stems</option> </select> </label> <label for="post-music-edit-FlowMusic-clip"><span>clip (required, encoded clip asset id)</span> <input id="post-music-edit-FlowMusic-clip" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> <label for="post-music-edit-FlowMusic-model"><span>model (cover/extend/replace/remix)</span> <select id="post-music-edit-FlowMusic-model" class="input-element"> <option value="">lyria-3-pro (default)</option> <option value="lyria-3.5">lyria-3.5</option> </select> </label> <label for="post-music-edit-FlowMusic-seed"><span>seed (optional, integer ≥ 0)</span> <input id="post-music-edit-FlowMusic-seed" type="number" class="input-element" min="0" oninput="this.size = this.value.length"> </label> <label for="post-music-edit-FlowMusic-title"><span>title (optional, result clip title)</span> <input id="post-music-edit-FlowMusic-title" type="text" class="input-element" oninput="this.size = this.value.length"> </label> <label for="post-music-edit-FlowMusic-instruction"><span>instruction (extend/replace required, cover optional)</span> <textarea id="post-music-edit-FlowMusic-instruction" class="input-element" rows="3" style="resize: both;"></textarea> </label> <label for="post-music-edit-FlowMusic-lyrics"><span>lyrics (remix, required)</span> <textarea id="post-music-edit-FlowMusic-lyrics" class="input-element" rows="3" style="resize: both;"></textarea> </label> <label for="post-music-edit-FlowMusic-prompt"><span>prompt (remix, optional sound override)</span> <input id="post-music-edit-FlowMusic-prompt" type="text" class="input-element" oninput="this.size = this.value.length"> </label> <label for="post-music-edit-FlowMusic-effect"><span>effect (effect, required — Trim/Fade/Gain/Reverb/Pan/Equalizer)</span> <select id="post-music-edit-FlowMusic-effect" class="input-element"> <option value=""></option> <option value="Trim">Trim</option> <option value="Fade">Fade</option> <option value="Gain">Gain</option> <option value="Reverb">Reverb</option> <option value="Pan">Pan</option> <option value="Equalizer">Equalizer</option> </select> </label> <label for="post-music-edit-FlowMusic-gain_db"><span>gain_db (effect=Gain, −30…30)</span> <input id="post-music-edit-FlowMusic-gain_db" type="text" class="input-element" oninput="this.size = this.value.length"> </label> <label for="post-music-edit-FlowMusic-mix"><span>mix (effect=Reverb, 0…1)</span> <input id="post-music-edit-FlowMusic-mix" type="text" class="input-element" oninput="this.size = this.value.length"> </label> <label for="post-music-edit-FlowMusic-room_size"><span>room_size (effect=Reverb, 0…1)</span> <input id="post-music-edit-FlowMusic-room_size" type="text" class="input-element" oninput="this.size = this.value.length"> </label> <label for="post-music-edit-FlowMusic-pan"><span>pan (effect=Pan, −1…1)</span> <input id="post-music-edit-FlowMusic-pan" type="text" class="input-element" oninput="this.size = this.value.length"> </label> <label for="post-music-edit-FlowMusic-bass_db"><span>bass_db (effect=Equalizer, −12…12)</span> <input id="post-music-edit-FlowMusic-bass_db" type="text" class="input-element" oninput="this.size = this.value.length"> </label> <label for="post-music-edit-FlowMusic-mid_db"><span>mid_db (effect=Equalizer, −12…12)</span> <input id="post-music-edit-FlowMusic-mid_db" type="text" class="input-element" oninput="this.size = this.value.length"> </label> <label for="post-music-edit-FlowMusic-treble_db"><span>treble_db (effect=Equalizer, −12…12)</span> <input id="post-music-edit-FlowMusic-treble_db" type="text" class="input-element" oninput="this.size = this.value.length"> </label> <label for="post-music-edit-FlowMusic-fade_in_s"><span>fade_in_s (effect=Fade, seconds)</span> <input id="post-music-edit-FlowMusic-fade_in_s" type="text" class="input-element" oninput="this.size = this.value.length"> </label> <label for="post-music-edit-FlowMusic-fade_out_s"><span>fade_out_s (effect=Fade, seconds)</span> <input id="post-music-edit-FlowMusic-fade_out_s" type="text" class="input-element" oninput="this.size = this.value.length"> </label> <label for="post-music-edit-FlowMusic-start_s"><span>start_s (effect=Trim, seconds)</span> <input id="post-music-edit-FlowMusic-start_s" type="text" class="input-element" oninput="this.size = this.value.length"> </label> <label for="post-music-edit-FlowMusic-end_s"><span>end_s (effect=Trim, seconds)</span> <input id="post-music-edit-FlowMusic-end_s" type="text" class="input-element" oninput="this.size = this.value.length"> </label> <label for="post-music-edit-FlowMusic-extend_s"><span>extend_s (extend, seconds 1–300)</span> <input id="post-music-edit-FlowMusic-extend_s" type="text" class="input-element" oninput="this.size = this.value.length"> </label> <label for="post-music-edit-FlowMusic-extend_from_s"><span>extend_from_s (extend, seconds)</span> <input id="post-music-edit-FlowMusic-extend_from_s" type="text" class="input-element" oninput="this.size = this.value.length"> </label> <label for="post-music-edit-FlowMusic-mask_start_s"><span>mask_start_s (replace, required, seconds)</span> <input id="post-music-edit-FlowMusic-mask_start_s" type="text" class="input-element" oninput="this.size = this.value.length"> </label> <label for="post-music-edit-FlowMusic-mask_end_s"><span>mask_end_s (replace, required, seconds)</span> <input id="post-music-edit-FlowMusic-mask_end_s" type="text" class="input-element" oninput="this.size = this.value.length"> </label> <label for="post-music-edit-FlowMusic-strength"><span>strength (cover, 0…1)</span> <input id="post-music-edit-FlowMusic-strength" type="text" class="input-element" oninput="this.size = this.value.length"> </label> <label for="post-music-edit-FlowMusic-mode"><span>mode (optional — ignored by stems)</span> <select id="post-music-edit-FlowMusic-mode" class="input-element"> <option value="">sync (default)</option> <option value="async">async</option> </select> </label> <label for="post-music-edit-FlowMusic-replyUrl"><span>replyUrl (optional, webhook URL)</span> <input id="post-music-edit-FlowMusic-replyUrl" type="text" class="input-element" oninput="this.size = this.value.length"> </label> <label for="post-music-edit-FlowMusic-replyRef"><span>replyRef (optional, webhook reference)</span> <input id="post-music-edit-FlowMusic-replyRef" type="text" class="input-element" oninput="this.size = this.value.length"> </label> </div> <button id="post-music-edit-FlowMusic-button" class="btn btn-primary fs-3" type="submit" onclick="apiTestMusicEditFlowMusic()">Go</button> </div> </form> <div id="post-music-edit-FlowMusic-media-links" style="display:none;"></div> <div id="post-music-edit-FlowMusic-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-flowmusic-v1/post-flowmusic-music-lyrics === Document URL: https://useapi.net/docs/api-flowmusic-v1/post-flowmusic-music-lyrics --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> music/lyrics seo_title: "AI Lyrics Generator API: Write New Song Lyrics with Flow Music (Lyria)" description: "Write new [Verse]/[Chorus] song lyrics with AI from a prompt via POST music/lyrics in the useapi.net Flow Music API, then sing them with POST music. It writes original lyrics, not lookups of existing songs." parent: Flow Music API nav_order: 220 permalink: /docs/api-flowmusic-v1/post-flowmusic-music-lyrics --- ## Generate lyrics June 3, 2026 (November 16, 2026) --- Generate `[Verse]`/`[Chorus]`-structured lyrics from a prompt, **without** producing audio. It runs the agent, so it uses a very small amount of credit (token usage), but renders no song. > Flow Music has no dedicated lyrics-only model — this endpoint drives the song agent to write lyrics (and a matching `sound_prompt`) **without** generating audio. It reads the agent's structured `lyrics__create` result, so lyrics come back reliably even when the agent's chat reply is conversational; a `422` only happens when the agent produced no lyrics at all. For lyrics bound to an actual track, use [POST /music](/docs/api-flowmusic-v1/post-flowmusic-music) — every generated clip returns `clip.lyrics`. > **https://api.useapi.net/v1/flowmusic/music/lyrics** ### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Request Body ```json { "prompt": "a nostalgic song about a long road trip home", "structure": "Verse 1 / Chorus / Verse 2 / Chorus / Bridge / Outro" } ``` - `email` is optional, which configured account to use. - `prompt` is **required**, the song concept. 1–2,000 characters. - `structure` is optional, a free-text section scaffold to shape the layout. ≤2,000 characters. ### Responses **200** **200 OK** ```json { "email": "user@email.com", "title": "Road Home", "lyrics": "[Verse 1]\nHighway humming under the wheels\n[Chorus]\nTaking the long way home", "sound_prompt": "Indie folk, warm acoustic guitar, 80 BPM, intimate male vocal", "source": "lyrics-create", "audio_create_song_fired": false, "credits_burned": 0 } ``` **401** **401 Unauthorized** — invalid API token. **402** **402 Payment Required** The targeted Flow Music account has insufficient credits. Generating lyrics runs the agent, which draws a small amount of credit even though no audio is rendered, so this endpoint can still run an account dry. Top up its credit balance (or target a funded account with `email`), then retry. ```json { "error": "FlowMusic conversation failed (402): {\"detail\":\"User has insufficient credits\"}", "code": 402 } ``` **422** **422** — rare: the agent produced no lyrics at all (no structured result and no tagged text block). Retry, or use [POST /music](/docs/api-flowmusic-v1/post-flowmusic-music) and read `clip.lyrics`. ```json { "email": "user@email.com", "error": { "code": "no_lyrics", "message": "..." }, "agent_text": "..." } ``` **596** **596 Account Error** The account targeted by `email` is in an error state and can't be used — re-add it via [POST /accounts](/docs/api-flowmusic-v1/post-flowmusic-accounts). The `error` field returns whatever reason was recorded for the account. ```json { "error": "Account user@email.com in error state: refresh token rejected", "code": 596 } ``` ### Model The `[Verse]`/`[Chorus]`-tagged lyrics, plus a title and a matching `sound_prompt` when the agent wrote them. <details markdown="block" class="model-details"> <summary>The generated lyrics, field by field</summary> ```typescript { email: string title: string | null lyrics: string // [Verse]/[Chorus]-tagged sound_prompt: string | null // a matching style/production prompt, when the agent wrote one source: string // 'lyrics-create' (agent's structured result) | 'text-part-fallback' audio_create_song_fired: boolean // true only if the agent also kicked off a render (normally false) credits_burned: number | null // 0 when no song was rendered — the agent chat still spends a tiny amount of credit; null if a render unexpectedly fired } ``` </details> ### Examples **Curl** ``` bash curl -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -X POST "https://api.useapi.net/v1/flowmusic/music/lyrics" \ -d '{ "prompt": "a nostalgic song about a long road trip home" }' ``` **Python** ``` python import requests response = requests.post( 'https://api.useapi.net/v1/flowmusic/music/lyrics', headers={'Authorization': 'Bearer YOUR_API_TOKEN'}, json={'prompt': 'a nostalgic song about a long road trip home'} ) print(response.status_code, response.json()) ``` ### Try It <script> async function apiTestMusicLyricsFlowMusic() { const data = { method: 'POST', headers: { 'Authorization': `Bearer ${document.getElementById('post-music-lyrics-FlowMusic-token').value}`, 'Content-Type': 'application/json' } }; let email = document.getElementById(`post-music-lyrics-FlowMusic-email`)?.value; let prompt = document.getElementById(`post-music-lyrics-FlowMusic-prompt`)?.value; let structure = document.getElementById(`post-music-lyrics-FlowMusic-structure`)?.value; const url = `https://api.useapi.net/v1/flowmusic/music/lyrics`; data.body = JSON.stringify({ email: email || undefined, prompt, structure: structure || undefined, }); await apiExecute(url, 'post-music-lyrics-FlowMusic', data); } </script> <form id="post-music-lyrics-FlowMusic" onsubmit="return false;" class="input-form"> <div class="input-field"> <div class="input-field-row"> <label for="post-music-lyrics-FlowMusic-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="post-music-lyrics-FlowMusic-token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> <label for="post-music-lyrics-FlowMusic-email"><span>email (optional)</span> <input id="post-music-lyrics-FlowMusic-email" type="text" class="input-element" placeholder="user@email.com"> </label> <label for="post-music-lyrics-FlowMusic-prompt"><span>prompt</span> <textarea id="post-music-lyrics-FlowMusic-prompt" class="input-element" rows="3" required aria-required="true" style="resize: both;"></textarea> </label> <label for="post-music-lyrics-FlowMusic-structure"><span>structure (optional, section scaffold)</span> <input id="post-music-lyrics-FlowMusic-structure" type="text" class="input-element" oninput="this.size = this.value.length"> </label> </div> <button id="post-music-lyrics-FlowMusic-button" class="btn btn-primary fs-3" type="submit" onclick="apiTestMusicLyricsFlowMusic()">Go</button> </div> </form> <div id="post-music-lyrics-FlowMusic-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-flowmusic-v1/post-flowmusic-music === Document URL: https://useapi.net/docs/api-flowmusic-v1/post-flowmusic-music --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> music description: "Generate a complete song from a text prompt via POST music in the useapi.net FlowMusic API v1 — custom lyrics, instrumental mode, and A/B clip output." parent: Flow Music API nav_order: 200 permalink: /docs/api-flowmusic-v1/post-flowmusic-music --- ## Generate a song June 3, 2026 (November 16, 2026) --- Generate a complete song from a text prompt using [Lyria](https://deepmind.google/models/lyria/), on either `lyria-3.5` (the current flagship) or `lyria-3-pro` (the default, see `model` below). Whether the result is vocal or instrumental is decided by the model from your prompt — describe vocals (or pass your own `lyrics`) to get a sung track with model-written lyrics, or set `instrumental: true` to force an instrumental. Each generation returns up to two clips (an A/B pair) and consumes credits from your account balance. > **https://api.useapi.net/v1/flowmusic/music** ### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Request Body ```json { "prompt": "lo-fi hip hop, mellow piano, 80 bpm", "instrumental": false, "ghostwriter": "pro" } ``` - `email` is optional. The Flow Music account to use. See [GET /accounts](/docs/api-flowmusic-v1/get-flowmusic-accounts) for configured accounts. If not provided, the API automatically selects an account with available capacity. Specify when you want to use a specific configured account. - `prompt` is **required**, the song description — style, mood, genre, instruments, BPM, and any vocal direction. 1–10,000 characters. - `instrumental` is optional. `true` forces an instrumental (prepends an `[Instrumental]` tag). `false` (default) lets the model decide whether to sing based on your prompt. - `lyrics` is optional, your own lyrics, ideally `[Verse]`/`[Chorus]`-tagged (≤10,000 chars). Providing them forces a vocal render of those words. Omit them and the model writes lyrics only if the prompt implies vocals. - `ghostwriter` is optional, the lyrics-writer version used when the model writes the lyrics. It has no effect if you supply your own `lyrics`. Supported values: `standard`, `pro`. - `model` is optional, the music model used for the render. Supported values: `lyria-3.5` and `lyria-3-pro` (default). `lyria-3.5` is Google's current flagship, described by Flow Music as its top-performing model with more dynamic vocals and richer musicality. `lyria-3-pro` is the older model every song generated through this API used before the parameter existed, so omitting `model` keeps your existing output unchanged. - `refImage1` to `refImage10` are optional, encoded image asset IDs from [POST /files](/docs/api-flowmusic-v1/post-flowmusic-files) or [POST /files/generate](/docs/api-flowmusic-v1/post-flowmusic-files-generate). Passed to the model only as uploaded-file hints (it may loosely nudge style) — not a literal reference. - `refAudio1` to `refAudio10` are optional, encoded audio asset IDs from [POST /files](/docs/api-flowmusic-v1/post-flowmusic-files). Experimental, limited effect — neither Lyria model truly references an uploaded song. The upload is passed only as a hint and may not influence the result. - `mode` is optional, `sync` (default) or `async`. In `sync` the request waits for the song, usually ~40–150 s, and returns `200` with the finished record (or the job's error code). Only a song that is still not finished after 7 minutes returns `202` with the job in `status: "pending"` — fetch the result with [GET /jobs/`jobid`](/docs/api-flowmusic-v1/get-flowmusic-jobs-jobid) or wait for the `replyUrl` webhook. The song keeps rendering on our side even if your connection drops, and it still lands in the job record and the webhook. `async` returns `201` immediately with a `jobid`, then you poll [GET /jobs/`jobid`](/docs/api-flowmusic-v1/get-flowmusic-jobs-jobid) for the result. On platforms with short request timeouts, use `async` or `replyUrl` so you always have the `jobid`. - `replyUrl` is optional, webhook URL. When the job completes or fails the API POSTs the job record to it — the same shape as [GET /jobs/`jobid`](/docs/api-flowmusic-v1/get-flowmusic-jobs-jobid). - `replyRef` is optional, custom reference string echoed back in the webhook. > References must come from one account. A `refImage`/`refAudio` ID is tied to the account it was uploaded to, so if you pass any, they must all be from that one account — and the song is generated there. If you also pass `email`, it has to match, or the request fails with `400`. ### Responses **200** **200 OK** **Sync mode** (default, or `"mode": "sync"`) — the song is generated and the full record is returned inline. All audio lives in the `clips[]` array. ```json { "jobid": "job:aaaabbbb-cccc-4ddd-8eee-ffff99990000-user:1234-user@email.com-bot:flowmusic", "email": "user@email.com", "status": "completed", "created_at": "2026-06-01T18:40:42.412Z", "completed_at": "2026-06-01T18:42:55.123Z", "duration_ms": 132711, "clips": [ { "clip": "user:1234-user@email.com-clip:a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", "title": "Morning Sun", "duration_s": 173.04, "lyrics": "[Verse 1]\nCity lights blur in the rain\n[Chorus]\nAnd I will wait for the morning sun", "seed": null, "lyrics_timing": [ [0.0, 2.4], [2.4, 5.1] ], "created_at": "2026-06-01T18:41:04.283Z", "audio_url": "https://storage.googleapis.com/...a1b2c3d4.m4a", "wav_url": "https://storage.googleapis.com/...a1b2c3d4.wav", "image_url": "https://storage.googleapis.com/...b2c3d4e5.jpg" } ], "request": { "prompt": "lo-fi hip hop, mellow piano, 80 bpm", "instrumental": false } } ``` **201** **201 Created** **Async mode** (`"mode": "async"`) — the job is queued and returned immediately as `pending`. Poll [GET /jobs/`jobid`](/docs/api-flowmusic-v1/get-flowmusic-jobs-jobid) until `status` is `completed` or `failed`. ```json { "jobid": "job:aaaabbbb-cccc-4ddd-8eee-ffff99990000-user:1234-user@email.com-bot:flowmusic", "email": "user@email.com", "status": "pending", "created_at": "2026-06-01T18:40:42.412Z", "request": { "prompt": "upbeat funk groove, 110 bpm", "instrumental": true, "mode": "async" } } ``` **202** **202 Accepted** Sync mode only, and rare. The song was still not finished after 7 minutes, so the job is returned as it stands, `pending`. It keeps rendering: poll [GET /jobs/`jobid`](/docs/api-flowmusic-v1/get-flowmusic-jobs-jobid) until `status` is `completed` or `failed`, or wait for the `replyUrl` webhook. ```json { "jobid": "job:aaaabbbb-cccc-4ddd-8eee-ffff99990000-user:1234-user@email.com-bot:flowmusic", "email": "user@email.com", "status": "pending", "created_at": "2026-06-01T18:40:42.412Z", "request": { "prompt": "upbeat funk groove, 110 bpm", "instrumental": true } } ``` **400** **400 Bad Request** Validation error (missing/invalid parameter, or no account configured). ```json { "error": "Parameter prompt is required", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "Unauthorized", "code": 401 } ``` **402** **402 Payment Required** The targeted Flow Music account has insufficient credits to complete the generation. Top up its credit balance (or target a funded account with `email`), then retry. ```json { "error": "FlowMusic conversation failed (402): {\"detail\":\"User has insufficient credits\"}", "code": 402 } ``` **422** **422** The model produced no audio (e.g. a content-moderation refusal). A terminal job record with `status: "failed"`. ```json { "jobid": "job:aaaabbbb-cccc-4ddd-8eee-ffff99990000-user:1234-user@email.com-bot:flowmusic", "email": "user@email.com", "status": "failed", "created_at": "2026-06-01T18:40:42.412Z", "completed_at": "2026-06-01T18:41:10.512Z", "error": { "code": "moderation_reject", "message": "the model declined to generate audio for this prompt" }, "request": { "prompt": "...", "instrumental": false } } ``` **429** **429 Too Many Requests** Returned in two cases. `email` omitted and **every** configured account is already at its `maxJobs` concurrency limit (load-balancing has nowhere to place the job) — retry once a running job finishes: ```json { "error": "All 3 FlowMusic accounts are at their maxJobs concurrency limit — retry shortly", "code": 429 } ``` Or passed through from FlowMusic when a chosen account exceeds its own per-account limit (a single or `email`-targeted account running too many generations at once): ```json { "error": "FlowMusic conversation failed (429): {\"detail\":\"Too Many Requests\"}", "code": 429 } ``` **596** **596 Account Error** The account targeted by `email` is in an error state and can't be used — re-add it via [POST /accounts](/docs/api-flowmusic-v1/post-flowmusic-accounts). The `error` field returns whatever reason was recorded for the account. ```json { "error": "Account user@email.com in error state: refresh token rejected", "code": 596 } ``` ### Model The job record, either `completed` with its clips or still `pending`: poll a pending job with [GET /jobs/`jobid`](/docs/api-flowmusic-v1/get-flowmusic-jobs-jobid) until it finishes. <details markdown="block" class="model-details"> <summary>The job record for each status, field by field</summary> **200 Completed** ```typescript { jobid: string // job:<uuid>-user:<id>-<email>-bot:flowmusic email: string status: 'completed' | 'pending' | 'failed' created_at: string // ISO 8601 timestamp completed_at?: string // present when terminal duration_ms?: number // wall-clock generation time clips: Array<{ clip: string // encoded clip asset id — use with /music/download and /music/edit title: string | null duration_s: number | null lyrics: string | null // [Verse]/[Chorus]-tagged; "[Instrumental]" for instrumentals seed: number | null lyrics_timing: Array<[number, number]> | null // timing markers, [start, end] seconds (vocal clips) created_at: string // ISO 8601 timestamp audio_url: string // signed m4a download URL wav_url: string // signed wav download URL image_url: string | null // auto-generated artwork URL }> request: { // the request body you submitted, echoed back verbatim prompt: string email?: string instrumental?: boolean lyrics?: string ghostwriter?: 'standard' | 'pro' model?: 'lyria-3.5' | 'lyria-3-pro' mode?: 'sync' | 'async' replyUrl?: string replyRef?: string refImage1?: string // …up to refImage10 — encoded image asset IDs refAudio1?: string // …up to refAudio10 — encoded audio asset IDs } } ``` **201 202 Pending** ```typescript { jobid: string // job:<uuid>-user:<id>-<email>-bot:flowmusic email: string status: 'pending' created_at: string // ISO 8601 timestamp request: { // the request body you submitted, echoed back verbatim prompt: string email?: string instrumental?: boolean lyrics?: string ghostwriter?: 'standard' | 'pro' model?: 'lyria-3.5' | 'lyria-3-pro' mode?: 'sync' | 'async' replyUrl?: string replyRef?: string refImage1?: string // …up to refImage10 — encoded image asset IDs refAudio1?: string // …up to refAudio10 — encoded audio asset IDs } } ``` </details> ### Examples **Curl** ``` bash curl -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -X POST "https://api.useapi.net/v1/flowmusic/music" \ -d '{ "prompt": "lo-fi hip hop, mellow piano, 80 bpm" }' ``` **JavaScript** ``` javascript const response = await fetch('https://api.useapi.net/v1/flowmusic/music', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_TOKEN', 'Content-Type': 'application/json' }, body: JSON.stringify({ prompt: 'lo-fi hip hop, mellow piano, 80 bpm' }) }); const result = await response.json(); console.log(result.clips?.[0]?.audio_url); ``` **Python** ``` python import requests response = requests.post( 'https://api.useapi.net/v1/flowmusic/music', headers={'Authorization': 'Bearer YOUR_API_TOKEN'}, json={'prompt': 'lo-fi hip hop, mellow piano, 80 bpm'} ) print(response.status_code, response.json()) ``` ### Try It <script> function displayFlowMusicClips(response, elementId) { const container = document.getElementById(`${elementId}-media-links`); if (!container) return; container.innerHTML = ''; const clips = response.clips || []; if (clips.length === 0) { container.style.display = 'none'; return; } container.innerHTML = '<div class="media-links-container"><strong>Generated clips:</strong></div>' + clips.map((c, i) => { const title = c.title || `Clip ${i + 1}`; const cover = c.image_url ? `<a href="${c.image_url}" target="_blank" rel="noopener noreferrer" title="Open full image in a new tab"><img src="${c.image_url}" alt="cover" style="max-width:96px;border-radius:6px;vertical-align:middle;margin-right:8px;cursor:zoom-in;"></a>` : ''; const audio = c.audio_url ? `<audio src="${c.audio_url}" controls style="vertical-align:middle;"></audio>` : ''; return `<div style="margin:6px 0;">${cover}${audio}<div>${escHtml(title)}</div></div>`; }).join(''); container.style.display = 'block'; } async function apiExecutePostFlowMusicMusic() { const elementId = 'input'; const payload = {}; document.querySelectorAll('.input-query-param').forEach(input => { const value = input.value?.trim(); if (input.id.startsWith('input-') && value !== '' && value !== undefined) { const key = input.id.replace('input-', ''); if (key === 'seed') payload[key] = parseInt(value); else if (key === 'instrumental') payload[key] = value === 'true'; else payload[key] = value; } }); const data = { method: 'POST', headers: { 'Authorization': `Bearer ${document.getElementById('input-token').value}`, 'Content-Type': 'application/json' }, body: JSON.stringify(payload) }; const mediaLinks = document.getElementById(`${elementId}-media-links`); if (mediaLinks) mediaLinks.style.display = 'none'; const status = await apiExecute('https://api.useapi.net/v1/flowmusic/music', elementId, data, { includeTimer: true }); if (status === 200) { try { const response = JSON.parse(document.getElementById(`${elementId}-response-json`).innerText); displayFlowMusicClips(response, elementId); } catch (e) { console.error('Failed to parse response for clip display:', e); } } } </script> <form id="input" class="input-form" onsubmit="return false;"> <div class="input-field"> <div class="input-field-row"> <label for="input-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="input-token" type="text" class="input-element" required aria-required="true"> </label> <label for="input-prompt"><span>prompt (required)</span> <input id="input-prompt" type="text" class="input-element input-query-param" required aria-required="true" placeholder="lo-fi hip hop, mellow piano, 80 bpm"> </label> <label for="input-instrumental"><span>instrumental</span> <select id="input-instrumental" class="input-element input-query-param"> <option value="">false (default)</option> <option value="true">true (instrumental — no vocals)</option> </select> </label> <label for="input-lyrics"><span>lyrics (optional, [Verse]/[Chorus]-tagged)</span> <input id="input-lyrics" type="text" class="input-element input-query-param" placeholder="[Verse 1] ... [Chorus] ..."> </label> <label for="input-ghostwriter"><span>ghostwriter (lyrics-writer version)</span> <select id="input-ghostwriter" class="input-element input-query-param"> <option value=""></option> <option value="standard">standard</option> <option value="pro">pro</option> </select> </label> <label for="input-model"><span>model (music model)</span> <select id="input-model" class="input-element input-query-param"> <option value="">lyria-3-pro (default)</option> <option value="lyria-3.5">lyria-3.5</option> </select> </label> <label for="input-email"><span>email (optional)</span> <input id="input-email" type="text" class="input-element input-query-param" placeholder="user@email.com"> </label> <label for="input-refImage1"><span>refImage1 (optional, encoded image asset id from <a href="/docs/api-flowmusic-v1/post-flowmusic-files" target="_blank">POST /files</a>)</span> <input id="input-refImage1" type="text" class="input-element input-query-param" placeholder="user:1234-user@email.com-image:..."> </label> <label for="input-refAudio1"><span>refAudio1 (optional, encoded audio asset id from <a href="/docs/api-flowmusic-v1/post-flowmusic-files" target="_blank">POST /files</a>)</span> <input id="input-refAudio1" type="text" class="input-element input-query-param" placeholder="user:1234-user@email.com-audio:..."> </label> <label for="input-mode"><span>mode</span> <select id="input-mode" class="input-element input-query-param"> <option value="">sync (default)</option> <option value="async">async</option> </select> </label> <label for="input-replyUrl"><span>replyUrl (webhook URL)</span> <input id="input-replyUrl" type="text" class="input-element input-query-param" placeholder="https://your-domain.com/webhook"> </label> <label for="input-replyRef"><span>replyRef (custom reference)</span> <input id="input-replyRef" type="text" class="input-element input-query-param" placeholder="my-custom-id-123"> </label> </div> <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecutePostFlowMusicMusic()">Go</button> </div> </form> <div id="input-media-links" style="display:none;"></div> <div id="input-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/start-here/setup-gemini-notebook === Document URL: https://useapi.net/docs/start-here/setup-gemini-notebook --- layout: default title: Setup Gemini Notebook seo_title: Setup Gemini Notebook API (NotebookLM API) description: "How to connect a Google account to the useapi.net Gemini Notebook API (NotebookLM API) — automated browser setup or a manual cookie paste." parent: Start Here nav_order: 225 permalink: /docs/start-here/setup-gemini-notebook --- # <img style="height:0.9em;vertical-align: middle;" src="/assets/images/gemini-notebook.svg" alt=""> Setup Gemini Notebook API (NotebookLM API) September 29, 2026 (November 1, 2026) ## Table of contents Approximately 5 minutes to complete setup steps. --- > This is the setup guide for [Gemini Notebook API](/docs/api-gemini-notebook-v1). A [Google](https://accounts.google.com) account and a [useapi.net subscription](/docs/subscription) are required for the API to work. Gemini Notebook (formerly NotebookLM) works on the free Google plan, and paid Google AI plans raise its usage limits. ### Automated setup (recommended) Use our guided browser setup to connect your account automatically — no DevTools or cookie copying needed. Enter your API token, sign in with Google in the remote browser, and your account is verified and added. [Open automated setup](/assets/setup-browser/gemini-notebook.html) Prefer manual setup? Continue with the steps below. --- ### Use a dedicated Gmail account **Use a dedicated Gmail account for this API — do NOT use your personal Gmail account.** When creating a new account: 1. Enable [2-Step Verification](https://support.google.com/accounts/answer/185839) with [Microsoft Authenticator](https://www.microsoft.com/en-us/security/mobile-authenticator-app), and save the backup codes. Avoid Google Authenticator — it backs its codes up to the Google account it is signed into, which would link this dedicated account to your personal one. 2. Keep your sign-ins consistent. If you use a VPN, pick one region and stay with it rather than switching locations — an account that appears from different places in a short time is what Google treats as suspicious. The automated setup above signs in from a US browser, so it needs no VPN on your side. ### If Google asks for a phone number Occasionally Google shows a "Verify it's you" page and asks for a phone number to text a code to, even on an account that never had one. Any number that can receive SMS works. It does not have to be one already on the account. If you'd rather not use your personal number, get an inexpensive prepaid line just for this — for example a [Tello](https://tello.com) eSIM on its cheapest plan with texts (about $5/month, activated online). Tello's guide [How can I activate my Tello eSIM?](https://tello.com/help_center/how-can-i-activate-my-tello-esim) has the steps. The phone must be carrier-unlocked and support eSIM, and Tello needs you to be in the United States when you first activate the line. Install it on any phone, receive the code there, and keep the line active so you can pass future checks. Google limits how many accounts one number can verify, and it can treat accounts verified with the same number as related. Avoid online SMS-rental and "free virtual number" services. Google rejects most of them, and a rejected number can make the lock harder to clear. ### If Google asks you to scan a QR code After the password and the 2-Step Verification code, Google sometimes adds one more page, "Verify your info to continue", with a QR code. Google wants to check a phone: scan the code with the phone's camera, tap the link, follow the steps on the phone, then switch back to the computer. It shows up mostly on accounts Google treats as risky, for example when many accounts are signed in within a short time, and an authenticator app on the account does not prevent it. - To skip the phone, choose `Try another way` below the QR code and pick what Google lists: a Microsoft Authenticator code, a backup code, or a text message to a phone number (see the phone number section above). - If Google offers no other option, close the setup and try that account again later, or add a different account. - Add accounts one at a time, spread over the day, rather than many within an hour. - Have the authenticator app and the backup codes ready before you start. The setup browser closes if the sign-in isn't finished within a few minutes. ### Manual setup **Do NOT use Google Chrome.** Google's integration with Chrome interferes with cookie extraction. Use [Brave](https://brave.com/) or [Ungoogled Chromium](https://github.com/ungoogled-software/ungoogled-chromium) instead. You copy two sets of cookies from Developer Tools and paste both into the same `cookies` field: the `https://notebook.google.com` set and the `https://accounts.google.com` set. The account is refused with only one of them. #### Start a clean browser with the setup script (recommended) Our [Google Account Setup](https://github.com/useapi/google-account-setup) scripts for Windows, macOS and Linux give you a clean, single-use Google sign-in. They open Brave in a brand-new, empty profile, wait while you sign in and copy the cookies, and delete that profile the moment you close the browser. That takes care of three things: - A fresh, empty profile, with no other Google accounts, history or extensions. It runs separately from your normal Brave, which can stay open. - No device-bound sessions. Brave starts with `--disable-features=EnableBoundSessionCredentials,DeviceBoundSessions`, so the cookies also work outside your computer. - The profile is deleted when you close the browser. That sign-in can never be opened in a browser again, so only the API uses it. The scripts read nothing and send nothing — you copy the cookies by hand, exactly as in the manual steps below. Each script is short, so read it before you run it. 1. Install [Brave](https://brave.com/) (on Linux, Chromium works too). 2. Get the script for your system from the sections below: copy it into a file, or download it from [GitHub](https://github.com/useapi/google-account-setup). 3. Run it and choose from the menupick the service from the menu. 4. In the Brave window, sign in to your dedicated Google account, copy the cookies named above (the script names them too), and paste them into the form on this page. 5. When the account shows as added, close every window of that Brave (on a Mac, quit it with `Cmd+Q`). Keep the script's window open until it reports the profile was deleted, and do not sign in to the same Google account in any other browser afterwards. <details markdown="block"> <summary>Windows — install script</summary> [Download it from GitHub](https://github.com/useapi/google-account-setup/blob/main/google-account-setup-windows.cmd), or open Notepad, paste the script below, and save it as `google-account-setup-windows.cmd` (in the Save dialog set `Save as type` to `All Files` so it is not saved as `.txt`). Double-click the saved file. If Windows shows `Windows protected your PC`, click `More info` then `Run anyway`. ```bat ``` </details> <details markdown="block"> <summary>macOS — install script</summary> [Download it from GitHub](https://github.com/useapi/google-account-setup/blob/main/google-account-setup-mac.command) and run it with `bash ~/Downloads/google-account-setup-mac.command`, or open `Terminal` (Applications → Utilities), paste the script below into a file with `nano ~/google-account-setup-mac.command`, press `Ctrl+O` then `Enter` to save and `Ctrl+X` to exit, then run it with `bash ~/google-account-setup-mac.command`. ```bash ``` </details> <details markdown="block"> <summary>Linux / WSL — install script</summary> [Download it from GitHub](https://github.com/useapi/google-account-setup/blob/main/google-account-setup-linux.sh), or save the script below to `~/google-account-setup-linux.sh` (for example with `nano ~/google-account-setup-linux.sh`), then run it with `bash ~/google-account-setup-linux.sh`. On WSL this needs Windows 11 (WSLg) for the browser window — otherwise run the Windows script instead. ```bash ``` </details> #### Or start the browser by hand Chromium browsers on Windows and Mac now bind a Google sign-in to the device (Google's Device Bound Session Credentials). Cookies copied from a bound session are refused anywhere else, and the API answers ``, so the account cannot be added or stops working. The browser's own flags page does not turn this off (Google overrides it), but a command-line switch does. The [automated setup](#automated-setup-recommended) is not affected. 1. Quit Brave completely, including any instance left in the system tray (check Task Manager for `brave.exe`, on a Mac use `Cmd+Q`). A running Brave ignores the switch. 2. Start it from the Run box (`Win+R`) with this command, which opens a private window with no cookies and without device-bound sessions: ``` "C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe" --incognito --disable-features=EnableBoundSessionCredentials,DeviceBoundSessions ``` On a Mac, run the same switches from Terminal: ``` open -na "Brave Browser" --args --incognito --disable-features=EnableBoundSessionCredentials,DeviceBoundSessions ``` Ungoogled Chromium takes the same `--disable-features` switch. Keep this window open for the steps below. #### Sign in to Gemini Notebook Navigate to [https://notebook.google.com](https://notebook.google.com) and sign in with your dedicated Gmail account <span style="color: red;">`1`</span>. ![](/assets/images/gemini-notebook-setup-2.png) Enter your password, then the 2-Step Verification code <span style="color: red;">`1`</span>. Google names Google Authenticator here whichever authenticator app holds the code. **You MUST check `Don't ask again on this device`** <span style="color: red;">`2`</span> — skipping it will break the API session. ![](/assets/images/gemini-notebook-setup-3.png) Once signed in you see Gemini Notebook with your plan's badge <span style="color: red;">`1`</span> (no badge on a free account). ![](/assets/images/gemini-notebook-setup-4.png) #### Copy the `https://notebook.google.com` cookies 1. Open Developer Tools: right-click anywhere on the page and select `Inspect` (or press `F12`), then open the `Application` tab <span style="color: red;">`1`</span> 2. Under `Cookies`, select `https://notebook.google.com` <span style="color: red;">`2`</span> 3. Click in the cookie table and select all cookies (`Ctrl+A`) <span style="color: red;">`3`</span> 4. Copy them (`Ctrl+C`, or right-click and `Copy`) <span style="color: red;">`4`</span>, and paste them into the `cookies` field below. ![](/assets/images/gemini-notebook-setup-5.png) #### Copy the `https://accounts.google.com` cookies This second set holds `LSID`. Without it the account is refused with `Missing cookies: LSID`. It is in the same Developer Tools, one entry down. 1. Stay on the `Application` tab <span style="color: red;">`1`</span> 2. Under `Cookies`, select `https://accounts.google.com` <span style="color: red;">`2`</span> 3. Click in the cookie table and select all cookies (`Ctrl+A`) <span style="color: red;">`3`</span> 4. Copy them (`Ctrl+C`, or right-click and `Copy`) <span style="color: red;">`4`</span>, and paste them into the same `cookies` field below, under the first set. ![](/assets/images/gemini-notebook-setup-6.png) Before you paste, look for `__Secure-1PSIDRTS` in what you copied. If it is there, the session is device-bound and will be refused: close every Brave window and start again with the command above. Paste everything you copied, exactly as it is. The form below sends it to [POST /accounts](/docs/api-gemini-notebook-v1/post-gemini-notebook-accounts), which checks the cookies with Google before the account is added. <script> async function apiAddAccountGeminiNotebook() { data = { method: 'POST', headers: { 'Authorization': `Bearer ${document.getElementById('post-accounts-GeminiNotebook-api_token').value}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ cookies: document.getElementById('post-accounts-GeminiNotebook-cookies')?.value }) }; await apiExecute(`https://api.useapi.net/v1/gemini-notebook/accounts`, 'post-accounts-GeminiNotebook', data); } </script> <form id="post-accounts-GeminiNotebook" onsubmit="apiAddAccountGeminiNotebook(); return false;" class="input-form"> <div class="input-field"> <div class="input-field-row"> <label for="post-accounts-GeminiNotebook-api_token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="post-accounts-GeminiNotebook-api_token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> <label for="post-accounts-GeminiNotebook-cookies"><span>cookies</span> <textarea id="post-accounts-GeminiNotebook-cookies" class="input-element" rows="10" required aria-required="true" style="resize: both;"></textarea> </label> </div> <button id="post-accounts-GeminiNotebook-button" class="btn btn-primary fs-3" type="submit">Go</button> </div> </form> <div id="post-accounts-GeminiNotebook-response" class="response-placeholder visible-false"></div> A successful response is `201` for a new account or `200` for an update, with the account email, its Google plan (`tier`) and its current usage (`quota`). ### If Google signs the account out If Google ends the session of a connected account, the API detects it on the next request, re-checks it once, and then emails you right away with a link to re-add the account. Until you re-add it, the account is paused and shows the re-add message in [GET /accounts](/docs/api-gemini-notebook-v1/get-gemini-notebook-accounts). Re-adding through the [automated setup](/assets/setup-browser/gemini-notebook.html) takes about a minute. ### Usage limits Gemini Notebook meters usage per Google account in two windows — every 5 hours and weekly — as a share of the plan's compute budget. Each Audio Overview, video, quiz or report uses part of it, and Google refuses new generations once the budget runs out until the window resets. Paid Google AI plans raise the budget. The API reports the live usage of each account at [GET /accounts/`email`](/docs/api-gemini-notebook-v1/get-gemini-notebook-accounts-email). ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/api-gemini-notebook-v1/delete-gemini-notebook-accounts-email === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/delete-gemini-notebook-accounts-email --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> accounts/`email` description: "Remove a Google account from the useapi.net Gemini Notebook API via DELETE accounts/email. Its notebooks, sources and artifacts stay on the Google account." parent: Gemini Notebook API nav_order: 140 permalink: /docs/api-gemini-notebook-v1/delete-gemini-notebook-accounts-email --- ## Delete an account September 29, 2026 --- Remove a connected Google account from your useapi.net account. The stored cookies are deleted and the account slot is freed. Nothing is deleted on Google's side. The account's notebooks, sources and artifacts stay in [Gemini Notebook](https://notebook.google.com), and you can connect the account again at any time with [POST /accounts](/docs/api-gemini-notebook-v1/post-gemini-notebook-accounts). Notebook, source and artifact ids of a removed account stop working until it is connected again. > **https://api.useapi.net/v1/gemini-notebook/accounts/`email`** - `email` is the email of a connected account, URL-encoded in the path. ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **204** **204 No Content** — the account was removed. The response body is empty. **400** **400 Bad Request** — the `email` in the path is not a valid email, or no account is connected. ```json { "error": "Path parameter email (not-an-email) not a valid email", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **404** **404 Not Found** — no account is connected for this `email`. ```json { "error": "Account user@example.com not found", "code": 404 } ``` ##### Examples **Curl** ``` bash curl -X DELETE "https://api.useapi.net/v1/gemini-notebook/accounts/user%40example.com" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const apiUrl = `https://api.useapi.net/v1/gemini-notebook/accounts/${encodeURIComponent(email)}`; const response = await fetch(apiUrl, { method: "DELETE", headers: { "Authorization": `Bearer ${token}`, }, }); console.log("response", response.status); ``` **Python** ``` python import requests from urllib.parse import quote token = "API token" email = "Previously configured account email" apiUrl = f"https://api.useapi.net/v1/gemini-notebook/accounts/{quote(email, safe='')}" headers = { "Authorization" : f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers) print(response.status_code) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/delete-gemini-notebook-artifacts-artifact === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/delete-gemini-notebook-artifacts-artifact --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> artifacts/`artifact` description: "Delete a Studio artifact, or dismiss an interactive report's suggested item, via DELETE artifacts/artifact in the useapi.net Gemini Notebook API — returns 204." parent: Gemini Notebook API nav_order: 630 permalink: /docs/api-gemini-notebook-v1/delete-gemini-notebook-artifacts-artifact --- ## Delete an artifact September 29, 2026 (November 16, 2026) --- Delete a Studio artifact from its notebook, at Google. The notebook and its sources stay. Deleted artifacts cannot be recovered. Files are always streamed from the artifact in the notebook and never stored by us, so once an artifact is deleted its [GET /artifacts/download](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts-download) links answer `404`. Download anything you want to keep first. A job still running for a deleted artifact fails with error code `not_found` on its next check. To dismiss an item an interactive report suggests, delete it by its `artifact` id from the report's `embedded` list. It then leaves that list. See [GET /artifacts/`artifact`](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts-artifact#interactive-report-items). To delete a whole notebook with everything in it, use [DELETE /notebooks/`notebook`](/docs/api-gemini-notebook-v1/delete-gemini-notebook-notebooks-notebook). > **https://api.useapi.net/v1/gemini-notebook/artifacts/`artifact`** - `artifact` is URL-encoded in the path (it contains `:` and `@`). Get it from [GET /artifacts](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts) or from the `artifact` field of a [job](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid). The id names the account and the notebook, so no `email` parameter is needed. ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **204** **204 No Content** The artifact was deleted. The response has no body. **400** **400 Bad Request** The path value is not an artifact id. ```json { "error": "Path parameter artifact (…) is not a valid artifact id", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The artifact id was issued to a different API token. ```json { "error": "user:12345-user@example.com-artifact:d02c903b-…:07b94418-… does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** The account the artifact lives on is no longer configured, or Google reports the artifact or its notebook as not found. ```json { "error": "Account user@example.com of user:12345-user@example.com-artifact:d02c903b-…:07b94418-… is not configured", "code": 404 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` ##### Model A successful delete returns `204` with no body. Errors return: <details markdown="block" class="model-details"> <summary>The error answer, field by field</summary> ```typescript { // TypeScript, all fields are optional error: string code: number } ``` </details> ##### Examples **Curl** ``` bash ARTIFACT="user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:07b94418-6c28-437c-98de-06bbeabb4e0c" curl -X DELETE "https://api.useapi.net/v1/gemini-notebook/artifacts/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$ARTIFACT")" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const artifact = "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:07b94418-6c28-437c-98de-06bbeabb4e0c"; const apiUrl = `https://api.useapi.net/v1/gemini-notebook/artifacts/${encodeURIComponent(artifact)}`; const response = await fetch(apiUrl, { method: "DELETE", headers: { "Authorization": `Bearer ${token}`, }, }); console.log("response", response.status); ``` **Python** ``` python import requests, urllib.parse token = "API token" artifact = "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:07b94418-6c28-437c-98de-06bbeabb4e0c" apiUrl = "https://api.useapi.net/v1/gemini-notebook/artifacts/" + urllib.parse.quote(artifact, safe="") headers = { "Authorization" : f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers) print(response.status_code) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/delete-gemini-notebook-chat === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/delete-gemini-notebook-chat --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> chat description: "Delete a notebook's chat history via DELETE chat in the useapi.net Gemini Notebook API — the latest or a named conversation, so the next question starts fresh." parent: Gemini Notebook API nav_order: 404 permalink: /docs/api-gemini-notebook-v1/delete-gemini-notebook-chat --- ## Delete chat history September 29, 2026 (November 16, 2026) --- Delete a chat conversation, the "Delete history" action of the Gemini Notebook web app. The next [POST /chat](/docs/api-gemini-notebook-v1/post-gemini-notebook-chat) question without a `conversation` starts a new conversation. Notes saved from the chat and the notebook's sources are not touched. Without `conversation` the notebook's latest conversation is deleted, and the call answers `404` when the notebook has none. > **https://api.useapi.net/v1/gemini-notebook/chat?notebook=`notebook`&conversation=`conversation`** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `notebook` is **required**, the notebook id returned by [POST /notebooks](/docs/api-gemini-notebook-v1/post-gemini-notebook-notebooks) or [GET /notebooks](/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks). URL-encode it (it contains `:` and `@`). The id names its account, so no `email` is needed. - `conversation` is optional, a conversation id from [POST /chat](/docs/api-gemini-notebook-v1/post-gemini-notebook-chat). Default: the notebook's latest conversation. ##### Responses **204** **204 No Content** The conversation was deleted. No body. **400** **400 Bad Request** ```json { "error": "Parameter notebook is required", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The id was issued to a different API token. ```json { "error": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55 does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** Without `conversation`, the notebook has no conversation to delete. Also returned when the notebook was deleted or its account is no longer configured. ```json { "error": "The notebook has no conversation to delete", "code": 404 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` **503** **503 Service Unavailable** Google is temporarily unavailable or is challenging our network. Retry in a few minutes. A `502` means Google answered with an unexpected error. ```json { "error": "Google is temporarily unavailable (J7Gthc grpc 14), please retry", "code": 503 } ``` ##### Model A successful delete returns `204` with no body. Errors return: <details markdown="block" class="model-details"> <summary>The error answer, field by field</summary> ```typescript { // TypeScript, all fields are optional error: string code: number } ``` </details> ##### Examples **Curl** ``` bash curl -X DELETE -G "https://api.useapi.net/v1/gemini-notebook/chat" \ -H "Authorization: Bearer …" \ --data-urlencode "notebook=user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55" ``` **JavaScript** ``` javascript const token = "API token"; const notebook = "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55"; const apiUrl = `https://api.useapi.net/v1/gemini-notebook/chat?notebook=${encodeURIComponent(notebook)}`; const response = await fetch(apiUrl, { method: "DELETE", headers: { "Authorization": `Bearer ${token}`, }, }); console.log("response", response.status); ``` **Python** ``` python import requests token = "API token" notebook = "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55" apiUrl = "https://api.useapi.net/v1/gemini-notebook/chat" headers = { "Authorization" : f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers, params={"notebook": notebook, "conversation": "fd20f12d-611f-4008-9e61-94e02af005a9"}) print(response.status_code) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/delete-gemini-notebook-collections-collection === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/delete-gemini-notebook-collections-collection --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> collections/`collection` description: "Delete a notebook collection via DELETE collections/collection in the useapi.net Gemini Notebook API — the folder goes, and its notebooks stay on the account." parent: Gemini Notebook API nav_order: 276 permalink: /docs/api-gemini-notebook-v1/delete-gemini-notebook-collections-collection --- ## Delete a collection October 15, 2026 (November 16, 2026) --- Remove a collection from its account. Its notebooks are not deleted: they stay on the account, outside this collection. To delete a notebook itself use [DELETE /notebooks/`notebook`](/docs/api-gemini-notebook-v1/delete-gemini-notebook-notebooks-notebook). > **https://api.useapi.net/v1/gemini-notebook/collections/`collection`** - `collection` is **required**, the collection id from [GET /collections](/docs/api-gemini-notebook-v1/get-gemini-notebook-collections) or [POST /collections](/docs/api-gemini-notebook-v1/post-gemini-notebook-collections), URL-encoded in the path (it contains `:` and `@`). The id names its account, so no `email` is needed. ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **204** **204 No Content** The collection was deleted. No body. **400** **400 Bad Request** The path does not hold a valid collection id. ```json { "error": "Path parameter collection (user%3A12345-user%40example.com-notebook%3Ad02c903b-17f8-4241-a263-2be9e7359d55) is not a valid collection id", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The id was issued to a different API token. ```json { "error": "user:12345-user@example.com-collection:7f3b9e21-4c8a-4d6f-b2e5-1a9c0d8e6f43 does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** The account the collection names is no longer configured. ```json { "error": "Account user@example.com of user:12345-user@example.com-collection:7f3b9e21-4c8a-4d6f-b2e5-1a9c0d8e6f43 is not configured", "code": 404 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` **503** **503 Service Unavailable** Google is temporarily unavailable or is challenging our network. Retry in a few minutes. A `502` means Google answered with an unexpected error. ```json { "error": "GOOGLE_BOT_CHECK: Google is challenging our network right now, please retry in a few minutes", "code": 503 } ``` ##### Model A successful delete returns `204` with no body. Errors return: <details markdown="block" class="model-details"> <summary>The error answer, field by field</summary> ```typescript { // TypeScript, all fields are optional error: string code: number } ``` </details> ##### Examples **Curl** ``` bash COLLECTION="user:12345-user@example.com-collection:7f3b9e21-4c8a-4d6f-b2e5-1a9c0d8e6f43" curl -X DELETE "https://api.useapi.net/v1/gemini-notebook/collections/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$COLLECTION")" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const collection = "user:12345-user@example.com-collection:7f3b9e21-4c8a-4d6f-b2e5-1a9c0d8e6f43"; const apiUrl = `https://api.useapi.net/v1/gemini-notebook/collections/${encodeURIComponent(collection)}`; const response = await fetch(apiUrl, { method: "DELETE", headers: { "Authorization": `Bearer ${token}`, }, }); console.log("response", response.status); ``` **Python** ``` python import requests, urllib.parse token = "API token" collection = "user:12345-user@example.com-collection:7f3b9e21-4c8a-4d6f-b2e5-1a9c0d8e6f43" apiUrl = "https://api.useapi.net/v1/gemini-notebook/collections/" + urllib.parse.quote(collection, safe="") headers = { "Authorization" : f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers) print(response.status_code) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/delete-gemini-notebook-jobs-jobid === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/delete-gemini-notebook-jobs-jobid --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> jobs/`jobid` description: "Cancel a running Studio or research job and free its maxJobs slot via DELETE jobs/jobid in the useapi.net Gemini Notebook API — research runs are stopped at Google too." parent: Gemini Notebook API nav_order: 720 permalink: /docs/api-gemini-notebook-v1/delete-gemini-notebook-jobs-jobid --- ## Cancel a job September 29, 2026 (November 16, 2026) --- Stop tracking a running job and free the `maxJobs` slot it holds on its account (see [GET /jobs](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs)). The job record turns `failed` with error code `cancelled`, and no `replyUrl` webhook is sent for it. Cancelling a Studio artifact job does not stop Google. Once Google has started an artifact it keeps generating it, the quota it spends is spent, and the finished artifact shows up in the notebook: find it with [GET /artifacts](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts) or read it by the job's `artifact` id with [GET /artifacts/`artifact`](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts-artifact). To remove it, [delete the artifact](/docs/api-gemini-notebook-v1/delete-gemini-notebook-artifacts-artifact) once it exists. A research job from [POST /research](/docs/api-gemini-notebook-v1/post-gemini-notebook-research) is different: the run is stopped at Google too, and its record's message is `Cancelled: the research run was stopped.` If Google could not be told to stop it, the job is still cancelled and its slot freed, and the message reads `Cancelled: the slot is freed, but Google could not be told to stop the research run.` A cancelled research job cannot be imported with [POST /research/import](/docs/api-gemini-notebook-v1/post-gemini-notebook-research-import). A one-shot job (a [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts) with `urls` / `text` instead of `notebook`) cancelled before its artifact was created also deletes the notebook that was made for it, since that notebook holds nothing you asked for. Cancelling a job that already completed or failed changes nothing and also answers `204`. > **https://api.useapi.net/v1/gemini-notebook/jobs/`jobid`** - `jobid` is URL-encoded in the path (it contains `:` and `@`). ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **204** **204 No Content** The job is cancelled (or was already finished). The response has no body. [GET /jobs/`jobid`](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid) now shows, for a Studio artifact job: ```json { "jobid": "job:09112e70-e1f3-422d-a1af-955de87508e4-user:12345-user@example.com-bot:gemini_notebook", "status": "failed", "completed_at": "2026-09-28T03:23:42.561Z", "error": { "code": "cancelled", "message": "Cancelled: the slot is freed. Google may still finish the artifact in the notebook." }, "...": "..." } ``` For a research job: ```json { "jobid": "job:0645b31d-ea2b-4c26-8754-a3b7876a21d0-user:12345-user@example.com-bot:gemini_notebook", "type": "research", "status": "failed", "completed_at": "2026-09-29T04:15:42.251Z", "error": { "code": "cancelled", "message": "Cancelled: the research run was stopped." }, "...": "..." } ``` **400** **400 Bad Request** The path value is not a Gemini Notebook jobid. ```json { "error": "Path parameter jobid (…) is not a valid jobid", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** ```json { "error": "jobid does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** No such job, or its record is older than 30 days. ```json { "error": "Job job:09112e70-…-bot:gemini_notebook not found", "code": 404 } ``` ##### Model A successful cancel returns `204` with no body. The cancelled record is the [job record](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid#model) with `status: 'failed'` and `error.code: 'cancelled'`. Errors return: <details markdown="block" class="model-details"> <summary>The error answer, field by field</summary> ```typescript { // TypeScript, all fields are optional error: string code: number } ``` </details> ##### Examples **Curl** ``` bash JOBID="job:09112e70-e1f3-422d-a1af-955de87508e4-user:12345-user@example.com-bot:gemini_notebook" curl -X DELETE "https://api.useapi.net/v1/gemini-notebook/jobs/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$JOBID")" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const jobid = "job:09112e70-e1f3-422d-a1af-955de87508e4-user:12345-user@example.com-bot:gemini_notebook"; const apiUrl = `https://api.useapi.net/v1/gemini-notebook/jobs/${encodeURIComponent(jobid)}`; const response = await fetch(apiUrl, { method: "DELETE", headers: { "Authorization": `Bearer ${token}`, }, }); console.log("response", response.status); ``` **Python** ``` python import requests, urllib.parse token = "API token" jobid = "job:09112e70-e1f3-422d-a1af-955de87508e4-user:12345-user@example.com-bot:gemini_notebook" apiUrl = "https://api.useapi.net/v1/gemini-notebook/jobs/" + urllib.parse.quote(jobid, safe="") headers = { "Authorization" : f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers) print(response.status_code) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/delete-gemini-notebook-labels-label === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/delete-gemini-notebook-labels-label --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> labels/`label` description: "Delete a source label via DELETE labels/label in the useapi.net Gemini Notebook API — the label goes, and its sources stay in the notebook without it." parent: Gemini Notebook API nav_order: 496 permalink: /docs/api-gemini-notebook-v1/delete-gemini-notebook-labels-label --- ## Delete a source label September 29, 2026 (November 16, 2026) --- Remove a label from its notebook. Its sources are not deleted: they stay in the notebook, without this label. To remove a source itself use [DELETE /sources/`source`](/docs/api-gemini-notebook-v1/delete-gemini-notebook-sources-source). > **https://api.useapi.net/v1/gemini-notebook/labels/`label`** - `label` is **required**, the label id from [GET /labels](/docs/api-gemini-notebook-v1/get-gemini-notebook-labels) or [POST /labels](/docs/api-gemini-notebook-v1/post-gemini-notebook-labels), URL-encoded in the path (it contains `:` and `@`). The id names its account and notebook, so no `email` or `notebook` is needed. ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **204** **204 No Content** The label was deleted. No body. **400** **400 Bad Request** The path does not hold a valid label id. ```json { "error": "Path parameter label (user%3A12345-user%40example.com-notebook%3Ad02c903b-17f8-4241-a263-2be9e7359d55) is not a valid label id", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The id was issued to a different API token. ```json { "error": "user:12345-user@example.com-label:d02c903b-17f8-4241-a263-2be9e7359d55:5973ba2b-845e-41b5-97b2-ef855d5746ad does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** The label is no longer in the notebook, the notebook was deleted, or its account is no longer configured. ```json { "error": "Label user:12345-user@example.com-label:d02c903b-17f8-4241-a263-2be9e7359d55:5973ba2b-845e-41b5-97b2-ef855d5746ad not found", "code": 404 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` **503** **503 Service Unavailable** Google is temporarily unavailable or is challenging our network. Retry in a few minutes. A `502` means Google answered with an unexpected error. ```json { "error": "Google is temporarily unavailable (GyzE7e grpc 14), please retry", "code": 503 } ``` ##### Model A successful delete returns `204` with no body. Errors return: <details markdown="block" class="model-details"> <summary>The error answer, field by field</summary> ```typescript { // TypeScript, all fields are optional error: string code: number } ``` </details> ##### Examples **Curl** ``` bash LABEL="user:12345-user@example.com-label:d02c903b-17f8-4241-a263-2be9e7359d55:5973ba2b-845e-41b5-97b2-ef855d5746ad" curl -X DELETE "https://api.useapi.net/v1/gemini-notebook/labels/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$LABEL")" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const label = "user:12345-user@example.com-label:d02c903b-17f8-4241-a263-2be9e7359d55:5973ba2b-845e-41b5-97b2-ef855d5746ad"; const apiUrl = `https://api.useapi.net/v1/gemini-notebook/labels/${encodeURIComponent(label)}`; const response = await fetch(apiUrl, { method: "DELETE", headers: { "Authorization": `Bearer ${token}`, }, }); console.log("response", response.status); ``` **Python** ``` python import requests, urllib.parse token = "API token" label = "user:12345-user@example.com-label:d02c903b-17f8-4241-a263-2be9e7359d55:5973ba2b-845e-41b5-97b2-ef855d5746ad" apiUrl = "https://api.useapi.net/v1/gemini-notebook/labels/" + urllib.parse.quote(label, safe="") headers = { "Authorization" : f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers) print(response.status_code) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/delete-gemini-notebook-notebooks-notebook === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/delete-gemini-notebook-notebooks-notebook --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> notebooks/`notebook` description: "Delete a notebook, together with its sources and Studio artifacts, via DELETE notebooks/notebook in the useapi.net Gemini Notebook API v1. Returns 204." parent: Gemini Notebook API nav_order: 240 permalink: /docs/api-gemini-notebook-v1/delete-gemini-notebook-notebooks-notebook --- ## Delete a notebook September 29, 2026 (November 16, 2026) --- Delete a notebook from its Google account. The notebook's sources and Studio artifacts go with it, and it cannot be recovered. Download any media you want to keep first with [GET /artifacts/download](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts-download). To remove a single source instead, use [DELETE /sources/`source`](/docs/api-gemini-notebook-v1/delete-gemini-notebook-sources-source). > **https://api.useapi.net/v1/gemini-notebook/notebooks/`notebook`** - `notebook` is **required**, the notebook id returned by [POST /notebooks](/docs/api-gemini-notebook-v1/post-gemini-notebook-notebooks) or [GET /notebooks](/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks). It contains `:` and `@`, so URL-encode it in the path (`encodeURIComponent` in JavaScript). ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **204** **204 No Content** The notebook was deleted. No body. **400** **400 Bad Request** ```json { "error": "Path parameter notebook (abc) is not a valid notebook id", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The notebook id was issued to a different API token. ```json { "error": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55 does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** The notebook's account is no longer configured, or Google no longer has the notebook. ```json { "error": "Account user@example.com of user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55 is not configured", "code": 404 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` ##### Model A successful delete returns `204 No Content` with no body. Error responses carry a JSON body: <details markdown="block" class="model-details"> <summary>The error answer, field by field</summary> ```typescript { // TypeScript, all fields are optional error: string code: number // the HTTP status } ``` </details> ##### Examples **Curl** ``` bash curl -X DELETE "https://api.useapi.net/v1/gemini-notebook/notebooks/user%3A12345-user%40example.com-notebook%3Ad02c903b-17f8-4241-a263-2be9e7359d55" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const notebook = "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55"; const apiUrl = `https://api.useapi.net/v1/gemini-notebook/notebooks/${encodeURIComponent(notebook)}`; const response = await fetch(apiUrl, { method: "DELETE", headers: { "Authorization": `Bearer ${token}`, }, }); console.log("response", response.status); ``` **Python** ``` python import requests, urllib.parse token = "API token" notebook = "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55" apiUrl = "https://api.useapi.net/v1/gemini-notebook/notebooks/" + urllib.parse.quote(notebook, safe="") headers = { "Authorization" : f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers) print(response.status_code) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/delete-gemini-notebook-notes-note === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/delete-gemini-notebook-notes-note --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> notes/`note` description: "Delete a note from its notebook via DELETE notes/note in the useapi.net Gemini Notebook API — sources made from the note with POST notes/source are kept." parent: Gemini Notebook API nav_order: 450 permalink: /docs/api-gemini-notebook-v1/delete-gemini-notebook-notes-note --- ## Delete a note September 29, 2026 (November 16, 2026) --- Remove a note from its notebook on Google. A source made from the note with [POST /notes/source](/docs/api-gemini-notebook-v1/post-gemini-notebook-notes-source) is a separate copy and stays in the notebook. Remove it with [DELETE /sources/`source`](/docs/api-gemini-notebook-v1/delete-gemini-notebook-sources-source) if you no longer need it. > **https://api.useapi.net/v1/gemini-notebook/notes/`note`** - `note` is **required**, the note id, URL-encoded in the path (it contains `:` and `@`). Note ids are returned by [POST /notes](/docs/api-gemini-notebook-v1/post-gemini-notebook-notes) and [GET /notes](/docs/api-gemini-notebook-v1/get-gemini-notebook-notes). The id names its account, so no `email` is needed. ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **204** **204 No Content** The note was deleted. No body. **400** **400 Bad Request** The path does not hold a valid note id, for example it holds a source id. ```json { "error": "Path parameter note (user%3A12345-user%40example.com-source%3Ad02c903b-17f8-4241-a263-2be9e7359d55%3A10f43c6b-a0a6-46a8-b330-06a5718dffb2) is not a valid note id", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The note id was issued to a different API token. ```json { "error": "user:12345-user@example.com-note:d02c903b-17f8-4241-a263-2be9e7359d55:e5514ee8-22e5-414d-aa67-86e8476ece09 does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** The account named in the note id is no longer configured, or Google reports the notebook as not found. ```json { "error": "Account user@example.com of user:12345-user@example.com-note:d02c903b-17f8-4241-a263-2be9e7359d55:e5514ee8-22e5-414d-aa67-86e8476ece09 is not configured", "code": 404 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` **503** **503 Service Unavailable** Google is temporarily unavailable or is challenging our network. Retry in a few minutes. A `502` means Google answered with an unexpected error. ```json { "error": "Google is temporarily unavailable (AH0mwd grpc 14), please retry", "code": 503 } ``` ##### Model A successful delete returns `204` with no body. Errors return: <details markdown="block" class="model-details"> <summary>The error answer, field by field</summary> ```typescript { // TypeScript, all fields are optional error: string code: number } ``` </details> ##### Examples **Curl** ``` bash NOTE="user:12345-user@example.com-note:d02c903b-17f8-4241-a263-2be9e7359d55:e5514ee8-22e5-414d-aa67-86e8476ece09" curl -X DELETE "https://api.useapi.net/v1/gemini-notebook/notes/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$NOTE")" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const note = "user:12345-user@example.com-note:d02c903b-17f8-4241-a263-2be9e7359d55:e5514ee8-22e5-414d-aa67-86e8476ece09"; const apiUrl = `https://api.useapi.net/v1/gemini-notebook/notes/${encodeURIComponent(note)}`; const response = await fetch(apiUrl, { method: "DELETE", headers: { "Authorization": `Bearer ${token}`, }, }); console.log("response", response.status); ``` **Python** ``` python import requests, urllib.parse token = "API token" note = "user:12345-user@example.com-note:d02c903b-17f8-4241-a263-2be9e7359d55:e5514ee8-22e5-414d-aa67-86e8476ece09" apiUrl = "https://api.useapi.net/v1/gemini-notebook/notes/" + urllib.parse.quote(note, safe="") headers = { "Authorization" : f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers) print(response.status_code) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/delete-gemini-notebook-sources-source === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/delete-gemini-notebook-sources-source --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> sources/`source` description: "Remove a source from its notebook via DELETE sources/source in the useapi.net Gemini Notebook API — later chat answers and Studio artifacts stop using it." parent: Gemini Notebook API nav_order: 330 permalink: /docs/api-gemini-notebook-v1/delete-gemini-notebook-sources-source --- ## Delete a source September 29, 2026 (November 16, 2026) --- Remove a source from its notebook on Google. Chat answers and Studio artifacts created afterwards no longer use it. The rest of the notebook is not touched. To delete the whole notebook use [DELETE /notebooks/`notebook`](/docs/api-gemini-notebook-v1/delete-gemini-notebook-notebooks-notebook). > **https://api.useapi.net/v1/gemini-notebook/sources/`source`** - `source` is the source id, URL-encoded in the path (it contains `:` and `@`). Source ids are returned by [POST /sources](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources), [POST /sources/upload](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources-upload) and [GET /notebooks/`notebook`](/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks-notebook). The id names its account, so no `email` is needed. ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **204** **204 No Content** The source was deleted. No body. **400** **400 Bad Request** The path does not hold a valid source id, for example it holds a notebook id. ```json { "error": "Path parameter source (user%3A12345-user%40example.com-notebook%3Ad02c903b-17f8-4241-a263-2be9e7359d55) is not a valid source id", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The source id was issued to a different API token. ```json { "error": "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:9df5b3d2-0afd-4ea7-9c20-e42c4af17d46 does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** The account named in the source id is no longer configured, or Google reports the source or its notebook as not found. ```json { "error": "Account user@example.com of user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:9df5b3d2-0afd-4ea7-9c20-e42c4af17d46 is not configured", "code": 404 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` **503** **503 Service Unavailable** Google is temporarily unavailable or is challenging our network. Retry in a few minutes. A `502` means Google answered with an unexpected error. ```json { "error": "Google is temporarily unavailable (tGMBJ grpc 14), please retry", "code": 503 } ``` ##### Model A successful delete returns `204 No Content` with no body. Error responses carry a JSON `{ error, code }`. <details markdown="block" class="model-details"> <summary>The error answer, field by field</summary> ```typescript { // TypeScript, all fields are optional error: string code: number } ``` </details> ##### Examples **Curl** ``` bash SOURCE="user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:9df5b3d2-0afd-4ea7-9c20-e42c4af17d46" curl -X DELETE -H "Authorization: Bearer …" \ "https://api.useapi.net/v1/gemini-notebook/sources/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$SOURCE")" ``` **JavaScript** ``` javascript const token = "API token"; const source = "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:9df5b3d2-0afd-4ea7-9c20-e42c4af17d46"; const response = await fetch(`https://api.useapi.net/v1/gemini-notebook/sources/${encodeURIComponent(source)}`, { method: "DELETE", headers: { "Authorization": `Bearer ${token}` } }); console.log("response", response.status); ``` **Python** ``` python import requests, urllib.parse token = "API token" source = "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:9df5b3d2-0afd-4ea7-9c20-e42c4af17d46" response = requests.delete("https://api.useapi.net/v1/gemini-notebook/sources/" + urllib.parse.quote(source, safe=""), headers={"Authorization": f"Bearer {token}"}) print(response.status_code) # 204 ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/get-gemini-notebook-accounts-email === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/get-gemini-notebook-accounts-email --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts/`email` description: "Read one Gemini Notebook account live via GET accounts/email in the useapi.net API — Google plan, session state, 5-hour and weekly usage, and each Studio action's estimated cost." parent: Gemini Notebook API nav_order: 120 permalink: /docs/api-gemini-notebook-v1/get-gemini-notebook-accounts-email --- ## Retrieve an account September 29, 2026 (November 16, 2026) --- Get one connected account with a live read from Google: whether the session is still signed in, the account's current plan, and its usage in the 5-hour and weekly windows. Google does not count generations. Each Studio action has an estimated cost as a percentage of the 5-hour window (`estimatedCostPercent`), and Google refuses a new job once its estimate is more than the `remainingPercent` of a window. Compare the two before you start a large job such as an Audio Overview or a slide deck. See [How much one account can generate](/docs/api-gemini-notebook-v1) for the Free, Pro and Ultra estimates. A signed-out session found here is handled like on any other request. The API re-checks it once, and if it is still signed out the account is paused and you receive an email with the re-add link. The response can be up to 60 seconds old. > **https://api.useapi.net/v1/gemini-notebook/accounts/`email`** - `email` is the email of a connected account, URL-encoded in the path. ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** ```json { "email": "user@example.com", "tier": "pro", "googleTier": "TIER_PRO", "googleTierCode": 2, "maxJobs": 3, "added": "2026-09-27T22:48:12.588Z", "cookies": [ "SID", "HSID", "SSID", "APISID", "SAPISID", "LSID", "OSID", "__Secure-OSID" ], "cookiesExpireAt": "2027-11-01T22:48:08.442Z", "addedVia": "setup-browser", "limits": { "notebooks": 500, "sourcesPerNotebook": 300 }, "health": "OK", "session": "signed-in", "outputLanguage": null, "quota": { "windows": [ { "window": "5h", "resetsAt": "2026-09-28T04:25:40.000Z", "usedPercent": 63.11, "remainingPercent": 36.89 }, { "window": "weekly", "resetsAt": "2026-10-04T23:25:40.000Z", "usedPercent": 3.01, "remainingPercent": 96.99 } ], "blocked": [ "cinematic" ], "actions": [ { "action": "audio", "allowed": true, "costTier": 3, "estimatedCostPercent": 11.03 }, { "action": "video", "allowed": true, "costTier": 3, "estimatedCostPercent": 10.92 }, { "action": "cinematic", "allowed": false, "costTier": 4, "estimatedCostPercent": 77.02 }, { "action": "video_short", "allowed": true, "costTier": 3, "estimatedCostPercent": 8.73 }, { "action": "infographic", "allowed": true, "costTier": 2, "estimatedCostPercent": 2.68 }, { "action": "slides", "allowed": true, "costTier": 3, "estimatedCostPercent": 13.63 }, { "action": "report", "allowed": true, "costTier": 2, "estimatedCostPercent": 1.08 }, { "action": "quiz", "allowed": true, "costTier": 1, "estimatedCostPercent": 0.57 }, ... ] } } ``` - Here the 5-hour window has 36.89% left, so an Audio Overview (11.03%) can start, while a cinematic video (77.02%) is refused until the window resets at `resetsAt`. - `session` tells what the live read found: - `signed-in` — the account works. `tier`, `googleTier`, `googleTierCode` and `quota` are fresh from Google. - `signed-out` — Google signed the account out. It is paused, `health` holds the re-add message and you receive an email with the re-add link. - `verifying` — another request is re-checking the session right now. Retry in about a minute. - `signed-in (re-checked)` — Google briefly reported the account as signed out, and the re-check found it signed in. - `unknown (could not reach Google to re-check)`, `unavailable (bot-check)`, `unavailable (shell-error)` — Google could not be reached. The account is not paused. Retry later. - `unknown` — the session works but the usage read failed. `quotaError` holds the reason. - `outputLanguage` is Google's account-wide language for Studio artifacts, as a language code such as `es`, or `null` when it was never set. Change it with [POST /accounts](/docs/api-gemini-notebook-v1/post-gemini-notebook-accounts). It is returned only with `session: signed-in`. - `quota` is returned only with `session: signed-in`. - An account that is already paused (its `health` is the re-add message) is returned as stored, without `session` or `quota`. Re-add it with [POST /accounts](/docs/api-gemini-notebook-v1/post-gemini-notebook-accounts). **400** **400 Bad Request** — the `email` in the path is not a valid email, or no account is connected yet. ```json { "error": "Path parameter email (not-an-email) not a valid email", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **404** **404 Not Found** — no account is connected for this `email`. ```json { "error": "Account user@example.com not found", "code": 404 } ``` ##### Model The account record plus a live read from Google: the `session` state, the 5-hour and weekly usage in `quota`, and each Studio action's estimated cost. <details markdown="block" class="model-details"> <summary>The account record with its live session, plan and usage, field by field</summary> ```typescript { // TypeScript, all fields are optional email: string tier: string // Google's plan, short form: 'free' | 'pro' | 'ultra' | 'plus' | … | 'unknown' googleTier?: string | null // Google's own plan name: 'TIER_FREE' | 'TIER_PRO' | 'TIER_ULTRA' | 'TIER_PLUS' | …googleTier?: string // Google's own plan name: 'TIER_FREE' | 'TIER_PRO' | 'TIER_ULTRA' | 'TIER_PLUS' | … googleTierCode?: number | null // Google's plan code: 1 = Free, 2 = Pro, 3 = Ultra, 4 = Plus, …googleTierCode?: number // Google's plan code: 1 = Free, 2 = Pro, 3 = Ultra, 4 = Plus, … maxJobs: number added: string // ISO 8601, when the account was first connected updated?: string // ISO 8601, the last re-add or maxJobs change cookies: string[] // names of the stored cookies, never their values cookiesExpireAt: string | null // ISO 8601, the earliest expiry Google stated for the stored cookies addedVia?: 'setup-browser' // present when the account was added by the automated setup limits?: { notebooks: number | null // notebooks allowed on the plan sourcesPerNotebook: number | null // sources allowed per notebook } health: string // 'OK', 'verifying', or the reason the account must be re-added session?: string // what the live read found, see Responses outputLanguage?: string | null // Google's account-wide Studio output language, null when unset quota?: { windows: { window: '5h' | 'weekly' resetsAt: string | null // ISO 8601 usedPercent: number remainingPercent: number }[] blocked: string[] // actions Google refuses right now actions: { action: string // 'audio' | 'video' | 'cinematic' | 'video_short' | 'infographic' | 'slides' | 'report' | 'table' | 'flashcards' | 'quiz' | 'mindmap' | 'qna' | … allowed: boolean costTier: number | null estimatedCostPercent: number | null // Google's estimate, as % of the 5h window }[] } quotaError?: string // present with session 'unknown' } ``` With `session: signed-in`, `tier`, `googleTier` and `googleTierCode` come from the live read, and `googleTier` / `googleTierCode` are `null` when Google's answer carries no plan code. [POST /accounts](/docs/api-gemini-notebook-v1/post-gemini-notebook-accounts) and [GET /accounts](/docs/api-gemini-notebook-v1/get-gemini-notebook-accounts) return the stored record, which omits both fields instead of returning `null`. </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/gemini-notebook/accounts/user%40example.com" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const apiUrl = `https://api.useapi.net/v1/gemini-notebook/accounts/${encodeURIComponent(email)}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests from urllib.parse import quote token = "API token" email = "Previously configured account email" apiUrl = f"https://api.useapi.net/v1/gemini-notebook/accounts/{quote(email, safe='')}" headers = { "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/get-gemini-notebook-accounts === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/get-gemini-notebook-accounts --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts description: "List every Google account connected to the useapi.net Gemini Notebook API via GET accounts, with plan, health, running jobs and the last-known 5-hour and weekly usage." parent: Gemini Notebook API nav_order: 110 permalink: /docs/api-gemini-notebook-v1/get-gemini-notebook-accounts --- ## List accounts September 29, 2026 (November 16, 2026) --- List the Google accounts connected with [POST /accounts](/docs/api-gemini-notebook-v1/post-gemini-notebook-accounts). Each entry shows the account's plan, its `health`, how many jobs it is running against its `maxJobs`, and the last usage the API read from Google. This endpoint does not call Google. For the live plan and usage of one account use [GET /accounts/`email`](/docs/api-gemini-notebook-v1/get-gemini-notebook-accounts-email). The response can be up to 60 seconds old. > **https://api.useapi.net/v1/gemini-notebook/accounts** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** ```json { "user@example.com": { "email": "user@example.com", "tier": "pro", "googleTier": "TIER_PRO", "googleTierCode": 2, "maxJobs": 3, "added": "2026-09-27T22:48:12.588Z", "cookies": [ "SID", "HSID", "SSID", "APISID", "SAPISID", "LSID", "OSID", "__Secure-OSID" ], "cookiesExpireAt": "2027-11-01T22:48:08.442Z", "addedVia": "setup-browser", "limits": { "notebooks": 500, "sourcesPerNotebook": 300 }, "health": "OK", "runningJobs": 1, "lastKnownQuota": { "windows": [ { "window": "5h", "resetsAt": "2026-09-28T04:25:40.000Z", "usedPercent": 63.11, "remainingPercent": 36.89 }, { "window": "weekly", "resetsAt": "2026-10-04T23:25:40.000Z", "usedPercent": 3.01, "remainingPercent": 96.99 } ], "blocked": [ "cinematic" ], "at": "2026-09-28T00:09:55.412Z" } }, "user2@example.com": { "email": "user2@example.com", "tier": "free", "googleTier": "TIER_FREE", "googleTierCode": 1, "maxJobs": 2, "added": "2026-09-27T19:18:45.721Z", "updated": "2026-09-27T20:11:41.537Z", "cookies": [ "SID", "HSID", "SSID", "APISID", "SAPISID", "LSID", "OSID", "__Secure-OSID" ], "cookiesExpireAt": "2027-11-01T00:00:00.000Z", "limits": { "notebooks": 100, "sourcesPerNotebook": 50 }, "health": "Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "runningJobs": 0 } } ``` - The response is an object keyed by account email, `{}` when no account is connected. - `health` is `OK` for a working account. `verifying` means Google reported the account as signed out and the API is re-checking it, which takes about a minute. Any other value says why the account must be re-added through [POST /accounts](/docs/api-gemini-notebook-v1/post-gemini-notebook-accounts) or the [automated setup](/assets/setup-browser/gemini-notebook.html). When Google signs an account out, it is paused and you also receive an email with the re-add link. - `lastKnownQuota` is the usage the API last read from Google, at the time given in `at`. It is refreshed by every [GET /accounts/`email`](/docs/api-gemini-notebook-v1/get-gemini-notebook-accounts-email) and after every job, and it is dropped after 5 hours. One-shot requests of [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts) use it to skip accounts where Google would refuse the job. **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` ##### Model An object keyed by account email. <details markdown="block" class="model-details"> <summary>Every account record with its running jobs and last known usage, field by field</summary> ```typescript { // TypeScript, all fields are optional [email: string]: { email: string tier: string // Google's plan, short form: 'free' | 'pro' | 'ultra' | 'plus' | … | 'unknown' googleTier?: string | null // Google's own plan name: 'TIER_FREE' | 'TIER_PRO' | 'TIER_ULTRA' | 'TIER_PLUS' | …googleTier?: string // Google's own plan name: 'TIER_FREE' | 'TIER_PRO' | 'TIER_ULTRA' | 'TIER_PLUS' | … googleTierCode?: number | null // Google's plan code: 1 = Free, 2 = Pro, 3 = Ultra, 4 = Plus, …googleTierCode?: number // Google's plan code: 1 = Free, 2 = Pro, 3 = Ultra, 4 = Plus, … maxJobs: number added: string // ISO 8601, when the account was first connected updated?: string // ISO 8601, the last re-add or maxJobs change cookies: string[] // names of the stored cookies, never their values cookiesExpireAt: string | null // ISO 8601, the earliest expiry Google stated for the stored cookies addedVia?: 'setup-browser' // present when the account was added by the automated setup limits?: { notebooks: number | null // notebooks allowed on the plan sourcesPerNotebook: number | null // sources allowed per notebook } health: string // 'OK', 'verifying', or the reason the account must be re-added runningJobs: number // jobs running on this account now, out of maxJobs lastKnownQuota?: { windows: { window: '5h' | 'weekly' resetsAt: string | null // ISO 8601 usedPercent: number remainingPercent: number }[] blocked: string[] // actions Google refused at that time at: string // ISO 8601, when this usage was read } } } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/gemini-notebook/accounts" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = "https://api.useapi.net/v1/gemini-notebook/accounts"; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" apiUrl = "https://api.useapi.net/v1/gemini-notebook/accounts" headers = { "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts-artifact === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts-artifact --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> artifacts/`artifact` description: "Fetch one Studio artifact with its result via GET artifacts/artifact in the useapi.net Gemini Notebook API — download links, report text, quiz JSON or an interactive report's suggested items." parent: Gemini Notebook API nav_order: 610 permalink: /docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts-artifact --- ## Retrieve an artifact September 29, 2026 (November 16, 2026) --- Fetch one Studio artifact by its id, read live from Google. A `completed` artifact carries its full result in the same shape as the `result` of a finished [job](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid): download links for audio, video, slide decks and infographics, the text of reports, the rows of a data table, and the JSON of quizzes, flashcards and mind maps. Use it to read an artifact again after its job record has expired, to pick up an artifact created in the Gemini Notebook web app, or to check on an artifact whose job was [cancelled](/docs/api-gemini-notebook-v1/delete-gemini-notebook-jobs-jobid) or timed out (Google may still finish it). The artifact ids come from [GET /artifacts](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts) and from the `artifact` field of a job. A completed interactive report also lists its `embedded` items, see [Interactive report items](#interactive-report-items). Each item can be read here by its own id, including a suggested one, which [GET /artifacts](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts) does not list. > **https://api.useapi.net/v1/gemini-notebook/artifacts/`artifact`** - `artifact` is URL-encoded in the path (it contains `:` and `@`), for example `user%3A12345-user%40example.com-artifact%3Ad02c903b-17f8-4241-a263-2be9e7359d55%3A07b94418-6c28-437c-98de-06bbeabb4e0c`. The id names the account and the notebook, so no `email` parameter is needed. ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Result by type A `completed` artifact adds `title` plus the fields below. Any other status returns only `artifact`, `notebook`, `type`, `status`, `created` and `title`, plus `description` for a suggested item. | `type` | Fields | Files ([GET /artifacts/download](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts-download) `format`) | |---|---|---| | `` | | | Every file link points at [GET /artifacts/download](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts-download), which streams the file from Google and needs your API token in the `Authorization` header. Google's own media URLs need the account's cookies, so they are never returned. ##### Interactive report items A completed `interactive_report` lists `embedded` items in the order they appear in the report. Each item is an infographic, a slide deck, a mind map, a quiz or flashcards that Google wrote for this report, with its own `artifact` id, `type`, `title`, `description` and `status`. - A new item has `status: "suggested"`. Nothing is generated yet, and its `description` is what Google proposes to make. - [POST /artifacts/generate](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts-generate) generates it. The item keeps its id and turns `completed`, and reading it here then returns its full result. - [DELETE /artifacts/`artifact`](/docs/api-gemini-notebook-v1/delete-gemini-notebook-artifacts-artifact) dismisses it, and it leaves the `embedded` list. ##### Responses **200** **200 OK** A completed quiz (long arrays shortened with `...`): ```json { "artifact": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:07b94418-6c28-437c-98de-06bbeabb4e0c", "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "type": "quiz", "status": "completed", "created": "2026-09-27T23:26:36.000Z", "title": "Apollo Quiz", "content": { "quiz": [ { "question": "During Apollo 11's lunar landing phase, which Flight Director was at the helm in Mission Control leading Shift 2 (White Team)?", "answerOptions": [ { "text": "Gene Kranz", "rationale": "Gene Kranz served as the Flight Director for Shift 2 (White Team), which actively managed the critical lunar landing descent phase.", "isCorrect": true }, { "text": "Glynn Lunney", "rationale": "Glynn Lunney managed Shift 3 (Black Team), which oversaw lunar ascent rather than the landing phase.", "isCorrect": false }, "..." ], "hint": "..." }, "..." ], "topics": { "covered": ["Apollo 11 Mission Overview", "Spacecraft Engineering and Call Signs", "..."], "followUp": ["Project Gemini Precursor Missions", "..."] } } } ``` A completed slide deck: ```json { "artifact": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:ae28f2a1-678b-4304-9806-09648fcb77a0", "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "type": "slides", "status": "completed", "created": "2026-09-27T23:31:15.000Z", "title": "Apollo 11 Flight Plan", "files": [ { "format": "pdf", "mimeType": "application/pdf", "url": "https://api.useapi.net/v1/gemini-notebook/artifacts/download?artifact=user%3A12345-user%40example.com-artifact%3Ad02c903b-17f8-4241-a263-2be9e7359d55%3Aae28f2a1-678b-4304-9806-09648fcb77a0&format=pdf" }, { "format": "pptx", "mimeType": "application/vnd.openxmlformats-officedocument.presentationml.presentation", "url": "https://api.useapi.net/v1/gemini-notebook/artifacts/download?artifact=user%3A12345-user%40example.com-artifact%3Ad02c903b-17f8-4241-a263-2be9e7359d55%3Aae28f2a1-678b-4304-9806-09648fcb77a0&format=pptx" } ], "slides": [ { "image": "https://api.useapi.net/v1/gemini-notebook/artifacts/download?artifact=user%3A12345-user%40example.com-artifact%3Ad02c903b-17f8-4241-a263-2be9e7359d55%3Aae28f2a1-678b-4304-9806-09648fcb77a0&format=slide&index=1", "caption": "Title slide for Apollo 11: Anatomy of a Miracle, featuring an astronaut on the lunar surface.", "text": "APOLLO_11: ANATOMY OF A MIRACLE\n\nJULY 16-24, 1969 | CREWED LUNAR LANDING\n\n..." }, "..." ] } ``` A completed interactive report, with one item generated and the others still suggested (text shortened with `...`): ```json { "artifact": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:8b9af76a-ef24-4e2f-a6ff-3d69cbf44650", "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "type": "interactive_report", "status": "completed", "created": "2026-10-15T05:06:28.000Z", "title": "To the Moon and Back: The Epic Stories of Apollo 11 and Apollo 13", "text": "Imagine blasting off atop a 36-story rocket, traveling 240,000 miles through the pitch-black void of space...", "embedded": [ { "artifact": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:5ac11006-86b7-43a8-91c9-72bc5ba1164f", "type": "infographic", "title": "Apollo 11 Moon Landing Anatomy", "description": "A visual breakdown showing the three modules of the Apollo 11 spacecraft, the three crew members, and the key steps of the moon landing sequence.", "status": "completed" }, { "artifact": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:a21107d4-54ab-46bd-8207-3a29974e4f8a", "type": "flashcards", "title": "Apollo 13 Rescue Concepts", "description": "Flashcards designed for middle school students to reinforce key terms from Apollo 13, including Aquarius, Odyssey, free-return trajectory, and the 'mailbox' CO2 filter solution.", "status": "suggested" }, { "artifact": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:7b48b9a9-ceae-4290-a647-9f2fc4a7ce3a", "type": "mindmap", "title": "The Apollo Mission Ecosystem", "description": "A branching concept map connecting Mission Control teams, spacecraft software systems, ground training, and astronaut tasks.", "status": "suggested" }, { "artifact": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:e4ec67bd-4f7e-4e09-8f6d-e88e6fa53cf6", "type": "quiz", "title": "Apollo Missions Knowledge Check", "description": "A multiple-choice review quiz designed for middle-school students to test understanding of Apollo 11 and 13 crew members, spacecraft parts, and key events.", "status": "suggested" } ] } ``` A suggested item, read by its own id: ```json { "artifact": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:a21107d4-54ab-46bd-8207-3a29974e4f8a", "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "type": "flashcards", "status": "suggested", "created": "2026-10-15T05:06:54.000Z", "title": "Apollo 13 Rescue Concepts", "description": "Flashcards designed for middle school students to reinforce key terms from Apollo 13, including Aquarius, Odyssey, free-return trajectory, and the 'mailbox' CO2 filter solution." } ``` An artifact that is not `completed` yet (or `failed`) returns only `artifact`, `notebook`, `type`, `status`, `created` and `title`. **400** **400 Bad Request** The path value is not an artifact id (a notebook or source id is refused too). ```json { "error": "Path parameter artifact (…) is not a valid artifact id", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The artifact id was issued to a different API token. ```json { "error": "user:12345-user@example.com-artifact:d02c903b-…:07b94418-… does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** The artifact is no longer in the notebook (deleted here or in the web app), the notebook is gone, or its account is no longer configured. ```json { "error": "Artifact user:12345-user@example.com-artifact:d02c903b-…:07b94418-… not found", "code": 404 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` ##### Model The artifact's type, status and title, plus its result once `completed`: download links, slides, text, a table or the quiz, flashcard or mind-map JSON. <details markdown="block" class="model-details"> <summary>The artifact and its result for each type, field by field, and the types it uses (<code>QuizContent</code>, <code>FlashcardsContent</code>, <code>MindmapNode</code>)</summary> ```typescript { // TypeScript, all fields are optional artifact: string // user:<id>-<email>-artifact:<notebook uuid>:<artifact uuid> notebook: string // user:<id>-<email>-notebook:<notebook uuid> type: 'audio' | 'video' | 'report' | 'interactive_report' | 'table' | 'quiz' | 'flashcards' | 'infographic' | 'slides' | 'mindmap' status: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'suggested' created: string | null // ISO 8601 title: string description: string // an interactive report's item: what Google proposes to make // The fields below are present only when status is 'completed', and only for the types listed above duration: number // seconds, audio and video files: Array<{ format: 'm4a' | 'mp4' | 'pdf' | 'pptx' | 'png' mimeType: string url: string // GET /artifacts/download link, needs your API token width: number // infographic png only height: number // infographic png only }> slides: Array<{ // slide decks, in order image: string // GET /artifacts/download?…&format=slide&index=N (PNG) caption: string | null // Google's one-line description of the slide text: string | null // the slide's text as Google extracted it }> text: string // report (Markdown), interactive_report, infographic table: string[][] // data table, first row = column headers content: QuizContent | FlashcardsContent | MindmapNode // quiz, flashcards, mindmap embedded: Array<{ // interactive_report: its items, in reading order artifact: string // the item's own id type: string // 'infographic', 'slides', 'mindmap', 'quiz' or 'flashcards' title: string description?: string status: 'suggested' | 'pending' | 'processing' | 'completed' | 'failed' }> } type QuizContent = { quiz: Array<{ question: string answerOptions: Array<{ text: string rationale: string // why this option is right or wrong isCorrect: boolean }> hint: string }> topics: { covered: string[] followUp: string[] } } type FlashcardsContent = { flashcards: Array<{ f: string // front of the card b: string // back of the card c: number // present on some cards (Google's own marker) }> topics: { covered: string[] followUp: string[] } } type MindmapNode = { name: string children: MindmapNode[] // absent on leaf nodes } ``` `content` is the JSON Google's own interactive quiz, flashcard and mind-map views render, passed through unchanged. If Google does not return it on a read, `content` is left out, so read the artifact again. </details> ##### Examples **Curl** ``` bash ARTIFACT="user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:07b94418-6c28-437c-98de-06bbeabb4e0c" curl -H "Authorization: Bearer …" \ "https://api.useapi.net/v1/gemini-notebook/artifacts/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$ARTIFACT")" ``` **JavaScript** ``` javascript const token = "API token"; const artifact = "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:07b94418-6c28-437c-98de-06bbeabb4e0c"; const apiUrl = `https://api.useapi.net/v1/gemini-notebook/artifacts/${encodeURIComponent(artifact)}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests, urllib.parse token = "API token" artifact = "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:07b94418-6c28-437c-98de-06bbeabb4e0c" apiUrl = "https://api.useapi.net/v1/gemini-notebook/artifacts/" + urllib.parse.quote(artifact, safe="") headers = { "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts-download === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts-download --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> artifacts/download description: "Stream an artifact's file via GET artifacts/download in the useapi.net Gemini Notebook API — m4a audio, mp4 video, pdf or pptx decks, png infographics and slide images, with Range support." parent: Gemini Notebook API nav_order: 640 permalink: /docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts-download --- ## Download an artifact file September 29, 2026 (November 16, 2026) --- Download the file of a completed Studio artifact. The response body is the file itself, streamed from Google on each request and never stored by us. Google's media URLs only open with the Google account's cookies, so every file link in a finished [job](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid) `result` and in [GET /artifacts/`artifact`](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts-artifact) points here instead. Those links are ready to use: call them with your API token in the `Authorization` header. They keep working as long as the artifact stays in its notebook. Once the artifact is [deleted](/docs/api-gemini-notebook-v1/delete-gemini-notebook-artifacts-artifact) they answer `404`, and deleting its notebook takes them with it. | Artifact `type` | `format` | Content type | |---|---|---| | `audio` | `m4a` | `audio/mp4` | | `video` | `mp4` | `video/mp4` | | `slides` | `pdf` | `application/pdf` | | `slides` | `pptx` | `application/vnd.openxmlformats-officedocument.presentationml.presentation` | | `slides` | `slide` + `index` | `image/png`, one slide image | | `infographic` | `png` | `image/png` | Reports, interactive reports, data tables, quizzes, flashcards and mind maps have no file: their text, rows or JSON are in the artifact itself. > **https://api.useapi.net/v1/gemini-notebook/artifacts/download?artifact=`artifact`&format=`format`** ##### Request Headers ``` yaml Authorization: Bearer {API token} # Optional, passed through to Google Range: bytes=0-1048575 ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. - `Range` is optional. It is forwarded to Google, so a player can seek in long audio and video or a client can resume a download. A range request answers `206 Partial Content` with `Content-Range`. ##### Query Parameters - `artifact` is **required**, the artifact id from [GET /artifacts](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts) or a job. URL-encode it (it contains `:` and `@`). - `format` is **required**, which file to download. Supported values: `m4a`, `mp4`, `pdf`, `pptx`, `png`, `slide`. The artifact must have that file, see the table above. - `index` is required with `format=slide` and ignored otherwise, the 1-based slide number. Range: `1` to `500`, and at most the number of slides in the deck. - `width` is optional, with `format=png` or `format=slide` only. Google scales the image down to this width in pixels and keeps its aspect ratio. A 2048-pixel infographic is about 5 MB, and `width=1024` makes it about 1.5 MB. Range: `100` to `4096`. Default: the full size. ##### Response headers - `Content-Type`: the file's type from the table above. - `Content-Disposition`: `attachment; filename="<artifact title>.<format>"`, for a slide image `"<artifact title> slide <index>.png"`. The title keeps letters, digits, spaces, `.`, `_` and `-`, is cut to 100 characters, and falls back to `artifact` when nothing is left. [Rename](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts-artifact) the artifact to change it. - `Content-Length`, `Accept-Ranges`, `Content-Range`, `ETag`, `Last-Modified`: passed through from Google when it sends them. - `Cache-Control: private, no-store`. ##### Responses **200** **200 OK** The raw file bytes (not JSON), for example: ``` Content-Type: audio/mp4 Content-Disposition: attachment; filename="Fue suerte el descenso del Eagle.m4a" Cache-Control: private, no-store ``` **206** **206 Partial Content** The requested byte range of the file, when the request carried a `Range` header. **400** **400 Bad Request** A parameter is missing or invalid, `format=slide` came without `index`, or `width` was sent with a format other than `png` or `slide`. ```json { "error": "index (1-based slide number) is required with format slide", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The artifact id was issued to a different API token. ```json { "error": "user:12345-user@example.com-artifact:d02c903b-…:07b94418-… does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** The artifact has no file in that `format` (wrong type, not completed yet, or a slide `index` past the last slide), or the artifact is gone from its notebook. The message lists the formats the artifact does have. ```json { "error": "No m4a file on this video (status completed); available: mp4", "code": 404 } ``` ```json { "error": "Artifact user:12345-user@example.com-artifact:d02c903b-…:07b94418-… not found", "code": 404 } ``` **502** **502 Bad Gateway** Google did not serve the file (the message names where the fetch stopped). Retry shortly. ```json { "error": "Google request failed: media fetch failed at lh3.googleusercontent.com (HTTP 403, text/html)", "code": 502 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` ##### Model A successful response is the file itself (not JSON), with the headers listed above. Errors return: <details markdown="block" class="model-details"> <summary>The error answer, field by field</summary> ```typescript { // TypeScript, all fields are optional error: string code: number } ``` </details> ##### Examples **Curl** ``` bash ARTIFACT="user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:ae28f2a1-678b-4304-9806-09648fcb77a0" # The whole deck as PDF, saved under the filename from Content-Disposition curl -G -OJ "https://api.useapi.net/v1/gemini-notebook/artifacts/download" \ -H "Authorization: Bearer …" \ --data-urlencode "artifact=$ARTIFACT" \ --data-urlencode "format=pdf" # Slide 3 as PNG curl -G "https://api.useapi.net/v1/gemini-notebook/artifacts/download" \ -H "Authorization: Bearer …" \ --data-urlencode "artifact=$ARTIFACT" \ --data-urlencode "format=slide" \ --data-urlencode "index=3" \ --output slide-3.png ``` **JavaScript** ``` javascript const token = "API token"; const artifact = "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:0c2ba8dc-47dd-474f-a19c-c06896e269fd"; const apiUrl = `https://api.useapi.net/v1/gemini-notebook/artifacts/download?artifact=${encodeURIComponent(artifact)}&format=m4a`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); if (!response.ok) console.log("error", response.status, await response.json()); else { const audio = await response.arrayBuffer(); console.log("downloaded", audio.byteLength, response.headers.get("content-disposition")); } ``` **Python** ``` python import requests token = "API token" artifact = "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:0449d123-6d1e-4864-ab28-ecac88a74c53" apiUrl = "https://api.useapi.net/v1/gemini-notebook/artifacts/download" headers = { "Authorization" : f"Bearer {token}" } with requests.get(apiUrl, headers=headers, params={"artifact": artifact, "format": "mp4"}, stream=True) as response: response.raise_for_status() with open("video.mp4", "wb") as f: for chunk in response.iter_content(chunk_size=1 << 20): f.write(chunk) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> artifacts description: "List every Studio artifact in one notebook via GET artifacts in the useapi.net Gemini Notebook API — id, title, type and generation status for each audio, video, report or quiz." parent: Gemini Notebook API nav_order: 600 permalink: /docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts --- ## List artifacts September 29, 2026 (November 16, 2026) --- List the Studio artifacts of one notebook: everything created with [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts), plus anything made in the Gemini Notebook web app on the same notebook. Each row carries the artifact id, which you pass to [GET /artifacts/`artifact`](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts-artifact) for the full result (files, slides, text, table or quiz / flashcards / mind map JSON). The list is read live from Google on every call. Artifacts that are still generating appear with status `pending` or `processing`. The items an interactive report suggests are not listed while their status is `suggested`. Find them in the report's `embedded` list on [GET /artifacts/`artifact`](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts-artifact#interactive-report-items). > **https://api.useapi.net/v1/gemini-notebook/artifacts?notebook=`notebook`** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `notebook` is **required**, the notebook id returned by [POST /notebooks](/docs/api-gemini-notebook-v1/post-gemini-notebook-notebooks) or [GET /notebooks](/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks), for example `user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55`. The id names the account the notebook lives on, so no `email` parameter is needed. URL-encode it (it contains `:` and `@`). ##### Responses **200** **200 OK** An array, one row per artifact. An empty notebook returns `[]`. ```json [ { "artifact": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:0449d123-6d1e-4864-ab28-ecac88a74c53", "title": "Apollo 11: Ticking Clock", "type": "video", "status": "completed", "created": "2026-09-27T23:38:23.000Z" }, { "artifact": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:0c2ba8dc-47dd-474f-a19c-c06896e269fd", "title": "¿Fue suerte el descenso del Eagle?", "type": "audio", "status": "completed", "created": "2026-09-27T23:38:10.000Z" }, { "artifact": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:ae28f2a1-678b-4304-9806-09648fcb77a0", "title": "Apollo 11 Flight Plan", "type": "slides", "status": "completed", "created": "2026-09-27T23:31:15.000Z" }, { "artifact": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:07b94418-6c28-437c-98de-06bbeabb4e0c", "title": "Apollo Quiz", "type": "quiz", "status": "completed", "created": "2026-09-27T23:26:36.000Z" } ] ``` **400** **400 Bad Request** `notebook` is missing or is not a notebook id. ```json { "error": "Parameter notebook is not a valid notebook id", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The notebook id was issued to a different API token. ```json { "error": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55 does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** The account the notebook lives on is no longer configured, or Google no longer has the notebook. ```json { "error": "Account user@example.com of user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55 is not configured", "code": 404 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` ##### Model One row per Studio artifact of the notebook, with its id, title, type, status and creation time. <details markdown="block" class="model-details"> <summary>The notebook's artifacts, field by field</summary> ```typescript Array<{ artifact: string // user:<id>-<email>-artifact:<notebook uuid>:<artifact uuid> title: string type: 'audio' | 'video' | 'report' | 'interactive_report' | 'table' | 'quiz' | 'flashcards' | 'infographic' | 'slides' | 'mindmap' status: 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' created: string | null // ISO 8601 }> ``` A `type` or `status` Google adds later that this API does not know yet is returned as `type<N>` / `status<N>` (Google's raw code). </details> ##### Examples **Curl** ``` bash curl -G "https://api.useapi.net/v1/gemini-notebook/artifacts" \ -H "Authorization: Bearer …" \ --data-urlencode "notebook=user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55" ``` **JavaScript** ``` javascript const token = "API token"; const notebook = "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55"; const apiUrl = `https://api.useapi.net/v1/gemini-notebook/artifacts?notebook=${encodeURIComponent(notebook)}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" notebook = "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55" apiUrl = "https://api.useapi.net/v1/gemini-notebook/artifacts" headers = { "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers, params={"notebook": notebook}) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/get-gemini-notebook-chat === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/get-gemini-notebook-chat --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> chat description: "Read a notebook's chat history via GET chat in the useapi.net Gemini Notebook API — the latest or a named conversation, up to 100 turns, oldest first." parent: Gemini Notebook API nav_order: 402 permalink: /docs/api-gemini-notebook-v1/get-gemini-notebook-chat --- ## Retrieve chat history September 29, 2026 (November 16, 2026) --- Read the questions and answers of a notebook's chat, live from Google, oldest turn first. Without `conversation` you get the notebook's latest conversation, which includes chats held in the Gemini Notebook web app. Up to 100 turns are returned. Each turn has a `role` (`user` for a question, `assistant` for an answer) and its `text`. The text is what Google stores for the turn: answers come back as plain text without the Markdown and the `[1]` citation markers of the [POST /chat](/docs/api-gemini-notebook-v1/post-gemini-notebook-chat) answer, and can include the quoted passages of the sources they cite. When the notebook has no conversation yet, `conversation` is `null` and `turns` is `[]`. Save a conversation as a note with the `conversation` parameter of [POST /notes](/docs/api-gemini-notebook-v1/post-gemini-notebook-notes), or clear it with [DELETE /chat](/docs/api-gemini-notebook-v1/delete-gemini-notebook-chat). > **https://api.useapi.net/v1/gemini-notebook/chat?notebook=`notebook`&conversation=`conversation`** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `notebook` is **required**, the notebook id returned by [POST /notebooks](/docs/api-gemini-notebook-v1/post-gemini-notebook-notebooks) or [GET /notebooks](/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks). URL-encode it (it contains `:` and `@`). The id names its account, so no `email` is needed. - `conversation` is optional, a conversation id from [POST /chat](/docs/api-gemini-notebook-v1/post-gemini-notebook-chat). Default: the notebook's latest conversation. ##### Responses **200** **200 OK** Answers shortened. ```json { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "conversation": "fd20f12d-611f-4008-9e61-94e02af005a9", "turns": [ { "role": "user", "text": "What were the 1202 alarms?" }, { "role": "assistant", "text": "The 1202 program alarms during lunar descent indicated \"executive overflows,\" meaning the guidance computer was overloaded and had to postpone lower-priority tasks to maintain real-time processing..." }, { "role": "user", "text": "Who told the crew it was safe to continue?" }, { "role": "assistant", "text": "Inside Mission Control, computer engineer Jack Garman informed Guidance Officer Steve Bales that the computer alarms were non-fatal..." } ] } ``` **400** **400 Bad Request** A missing notebook id, or a `conversation` that is not a conversation id. ```json { "error": "Parameter notebook is required", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The id was issued to a different API token. ```json { "error": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55 does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** The notebook was deleted, or its account is no longer configured. ```json { "error": "Not found on account user@example.com (Google hPTbtc grpc 5)", "code": 404 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` **503** **503 Service Unavailable** Google is temporarily unavailable or is challenging our network. Retry in a few minutes. A `502` means Google answered with an unexpected error. ```json { "error": "Google is temporarily unavailable (khqZz grpc 14), please retry", "code": 503 } ``` ##### Model The notebook's conversation id and up to 100 turns, oldest first, each with its `role` and `text`. <details markdown="block" class="model-details"> <summary>The conversation and its turns, field by field</summary> ```typescript { // TypeScript, all fields are optional notebook: string conversation: string | null // null when the notebook has no conversation turns: { // oldest first, up to 100 role: 'user' | 'assistant' text: string }[] error: string // error responses only code: number // error responses only, the HTTP status } ``` </details> ##### Examples **Curl** ``` bash curl -G "https://api.useapi.net/v1/gemini-notebook/chat" \ -H "Authorization: Bearer …" \ --data-urlencode "notebook=user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55" ``` **JavaScript** ``` javascript const token = "API token"; const notebook = "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55"; const apiUrl = `https://api.useapi.net/v1/gemini-notebook/chat?notebook=${encodeURIComponent(notebook)}&conversation=fd20f12d-611f-4008-9e61-94e02af005a9`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" notebook = "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55" apiUrl = "https://api.useapi.net/v1/gemini-notebook/chat" headers = { "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers, params={"notebook": notebook}) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/get-gemini-notebook-collections === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/get-gemini-notebook-collections --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> collections description: "List notebook collections via GET collections in the useapi.net Gemini Notebook API — each folder's name, emoji and notebooks, for one account or all of them." parent: Gemini Notebook API nav_order: 270 permalink: /docs/api-gemini-notebook-v1/get-gemini-notebook-collections --- ## List collections October 15, 2026 (November 16, 2026) --- List the collections of your accounts. A collection is a folder that groups an account's notebooks on the home page of the Gemini Notebook web app. Each one has a name, an optional emoji and the ids of its notebooks. Create a collection with [POST /collections](/docs/api-gemini-notebook-v1/post-gemini-notebook-collections). Rename it or add and remove notebooks with [POST /collections/`collection`](/docs/api-gemini-notebook-v1/post-gemini-notebook-collections-collection), and remove it with [DELETE /collections/`collection`](/docs/api-gemini-notebook-v1/delete-gemini-notebook-collections-collection). > **https://api.useapi.net/v1/gemini-notebook/collections?email=`email`** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `email` is optional, the [account](/docs/api-gemini-notebook-v1/get-gemini-notebook-accounts) to list. Default: every account of this API token. An account that cannot be read at the moment is left out of that list. ##### Responses **200** **200 OK** An account without collections returns `[]`. ```json [ { "collection": "user:12345-user@example.com-collection:7f3b9e21-4c8a-4d6f-b2e5-1a9c0d8e6f43", "email": "user@example.com", "name": "Space history", "emoji": "🚀", "notebooks": [ "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55" ] }, { "collection": "user:12345-user@example.com-collection:0a6d2c58-93e1-4b7f-8c4d-e25f17b9a306", "email": "user@example.com", "name": "Drafts", "notebooks": [] } ] ``` **400** **400 Bad Request** ```json { "error": "Parameter email not a valid email", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **404** **404 Not Found** The `email` is not one of your configured accounts. ```json { "error": "Account user@example.com is not configured", "code": 404 } ``` **596** **596 Account Error** With `email` only. Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` **503** **503 Service Unavailable** With `email` only. Google is temporarily unavailable or is challenging our network. Retry in a few minutes. A `502` means Google answered with an unexpected error. ```json { "error": "GOOGLE_BOT_CHECK: Google is challenging our network right now, please retry in a few minutes", "code": 503 } ``` ##### Model An array of your accounts' collections, each with its id, account, name, optional emoji and the ids of its notebooks. <details markdown="block" class="model-details"> <summary>The list of collections and the error answer, field by field</summary> ```typescript { // TypeScript, all fields are optional collection: string // user:<id>-<email>-collection:<collection id> email: string // the account the collection belongs to name: string emoji?: string notebooks: string[] // notebook ids in this collection }[] ``` Errors return: ```typescript { error: string code: number // the HTTP status } ``` </details> ##### Examples **Curl** ``` bash curl -G "https://api.useapi.net/v1/gemini-notebook/collections" \ -H "Authorization: Bearer …" \ --data-urlencode "email=user@example.com" ``` **JavaScript** ``` javascript const token = "API token"; const email = "user@example.com"; const apiUrl = `https://api.useapi.net/v1/gemini-notebook/collections?email=${encodeURIComponent(email)}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" apiUrl = "https://api.useapi.net/v1/gemini-notebook/collections" headers = { "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers, params={"email": "user@example.com"}) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> jobs/`jobid` description: "Poll a Studio generation or research job via GET jobs/jobid in the useapi.net Gemini Notebook API — the job record with its result or error, the same body a replyUrl webhook receives." parent: Gemini Notebook API nav_order: 710 permalink: /docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid --- ## Retrieve a job September 29, 2026 (November 16, 2026) --- Fetch a job record by its `jobid`. Every Studio generation is a job: [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts), [POST /artifacts/retry](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts-retry), [POST /artifacts/revise](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts-revise) and [POST /artifacts/generate](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts-generate) all return one. So does a research run from [POST /research](/docs/api-gemini-notebook-v1/post-gemini-notebook-research). Poll this endpoint until `status` is `completed` or `failed`. The API advances every running job about every 15 seconds, so polling more often than that gains nothing. Generation takes from under a minute (flashcards, mind maps) to 10 minutes and more (video). A job still running after 40 minutes is failed with error code `timeout` and its slot is freed. Google may still finish the artifact in the notebook, and [GET /artifacts/`artifact`](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts-artifact) shows it when it does. Instead of polling, pass `replyUrl` (and optionally `replyRef`) with the POST: when the job completes or fails, the API sends one `POST` of this same job record, as JSON, to that URL. See [Model](#model). Job records are kept for 30 days. > **https://api.useapi.net/v1/gemini-notebook/jobs/`jobid`** - `jobid` is URL-encoded in the path (it contains `:` and `@`), for example `job%3A12597f9a-010c-4758-8e9a-b5cc17b0ccdb-user%3A12345-user%40example.com-bot%3Agemini_notebook`. ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** Completed (an audio overview): ```json { "jobid": "job:12597f9a-010c-4758-8e9a-b5cc17b0ccdb-user:12345-user@example.com-bot:gemini_notebook", "email": "user@example.com", "type": "audio", "status": "completed", "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "artifact": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:0c2ba8dc-47dd-474f-a19c-c06896e269fd", "created_at": "2026-09-27T23:38:15.692Z", "request": { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "type": "audio", "format": "debate", "length": "short", "language": "es", "instructions": "Focus on the risks the crew took during the landing." }, "completed_at": "2026-09-27T23:43:41.173Z", "result": { "title": "¿Fue suerte el descenso del Eagle?", "duration": 277, "files": [ { "format": "m4a", "mimeType": "audio/mp4", "url": "https://api.useapi.net/v1/gemini-notebook/artifacts/download?artifact=user%3A12345-user%40example.com-artifact%3Ad02c903b-17f8-4241-a263-2be9e7359d55%3A0c2ba8dc-47dd-474f-a19c-c06896e269fd&format=m4a" } ] } } ``` Running (a cinematic video): ```json { "jobid": "job:21ade7e0-f2c0-48a1-904d-688096a3ff29-user:12345-user@example.com-bot:gemini_notebook", "email": "user@example.com", "type": "video", "status": "processing", "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "artifact": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:7f923bb5-fb59-4ee6-ade6-9ae559a660fe", "created_at": "2026-09-28T04:32:44.630Z", "request": { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "type": "video", "format": "cinematic" } } ``` Completed (a research job, Discover sources, list shortened): ```json { "jobid": "job:526bc256-d897-493a-9ebc-7c9f35ca4428-user:12345-user@example.com-bot:gemini_notebook", "email": "user@example.com", "type": "research", "status": "completed", "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "created_at": "2026-09-29T04:10:07.338Z", "request": { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "query": "Apollo 11 lunar module guidance computer alarms", "type": "fast" }, "completed_at": "2026-09-29T04:10:23.751Z", "result": { "mode": "fast", "query": "Apollo 11 lunar module guidance computer alarms", "summary": "Navigate the technical causes, software design, and human decisions behind the famous Apollo 11 guidance computer alarms.", "sources": [ { "url": "https://www.ibiblio.org/apollo/Documents/CherryApollo11Exegesis.pdf", "title": "Exegesis of the 1201 and 1202 Alarms Which Occurred During the Mission G Lunar Landing - Ibiblio", "description": "Technical exegesis explaining the exact mechanism of 1201/1202 alarms.", "cited": true } ] } } ``` Failed (cancelled with [DELETE /jobs/`jobid`](/docs/api-gemini-notebook-v1/delete-gemini-notebook-jobs-jobid)): ```json { "jobid": "job:09112e70-e1f3-422d-a1af-955de87508e4-user:12345-user@example.com-bot:gemini_notebook", "email": "user@example.com", "type": "flashcards", "status": "failed", "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "artifact": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:064463cc-e0a3-4feb-9196-2cec98b55039", "created_at": "2026-09-28T03:23:42.051Z", "request": { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "type": "flashcards", "quantity": "fewer" }, "completed_at": "2026-09-28T03:23:42.561Z", "error": { "code": "cancelled", "message": "Cancelled: the slot is freed. Google may still finish the artifact in the notebook." } } ``` **400** **400 Bad Request** The path value is not a Gemini Notebook jobid. ```json { "error": "Path parameter jobid (…) is not a valid jobid", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** ```json { "error": "jobid does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** No such job, or its record is older than 30 days. ```json { "error": "Job job:12597f9a-…-bot:gemini_notebook not found", "code": 404 } ``` ##### Model The job record. [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts), [POST /artifacts/retry](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts-retry), [POST /artifacts/revise](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts-revise) and [POST /research](/docs/api-gemini-notebook-v1/post-gemini-notebook-research) return it too, and it is the body of the `replyUrl` webhook. <details markdown="block" class="model-details"> <summary>The job record, field by field, and what each <code>error.code</code> means</summary> ```typescript { // TypeScript, all fields are optional jobid: string // job:<uuid>-user:<id>-<email>-bot:gemini_notebook email: string // the account the job runs on type: 'audio' | 'video' | 'report' | 'interactive_report' | 'table' | 'quiz' | 'flashcards' | 'infographic' | 'slides' | 'mindmap' | 'research' status: 'pending' | 'processing' | 'completed' | 'failed' notebook: string // notebook id; for a one-shot, the notebook created for it artifact?: string // artifact id, once Google has created it (never on a research job) created_at: string // ISO 8601, when the job was accepted updated_at?: string // one-shot only: when its artifact was created completed_at?: string // ISO 8601, when the job completed or failed request: Record<string, unknown> // your request body echoed back (ids as strings), without mode, replyUrl and replyRef replyUrl?: string replyRef?: string warnings?: string[] // one-shot only: sources Google could not process and that were left out error?: { // status 'failed' code: 'quota' | 'account' | 'not_found' | 'sources' | 'generation_failed' | 'timeout' | 'google_error' | 'scheduler' | 'cancelled' message: string retryAt?: string // code 'quota', when Google names the window: ISO 8601 time it resets } result?: { // status 'completed', a Studio artifact title: string duration?: number // audio, video: seconds files?: Array<{ // audio, video, infographic, slides format: 'm4a' | 'mp4' | 'png' | 'pdf' | 'pptx' mimeType: string url: string // GET /artifacts/download link, needs your API token width?: number // infographic height?: number }> slides?: Array<{ // slides image: string // GET /artifacts/download link (format=slide&index=N) caption: string | null text: string | null }> text?: string // report (Markdown), interactive_report, infographic table?: string[][] // table: rows of cells, header row first content?: unknown // quiz, flashcards, mindmap: Google's JSON embedded?: Array<{ // interactive_report: the items it suggests, in reading order artifact: string // the item's id, for POST /artifacts/generate or DELETE /artifacts/{artifact} type: string // 'infographic', 'slides', 'mindmap', 'quiz' or 'flashcards' title: string description?: string status: string // 'suggested' until generated }> } | { // status 'completed', type 'research' (POST /research) mode: 'fast' | 'deep' query: string summary?: string // fast: Google's one-line summary of what it found report?: { // deep: the Deep Research report title: string markdown: string } noResults?: true // the run found nothing (sources is []) sources: Array<{ url: string title: string description: string | null cited: boolean // deep: the report cites it. fast: always true }> } } ``` For a Studio job, `result` has exactly the per-type shape of a completed artifact, described on [GET /artifacts/`artifact`](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts-artifact#result-by-type). Every file `url` points at [GET /artifacts/download](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts-download), which needs your API token. For a research job (`type: research`), `result` lists what the run found, described on [POST /research](/docs/api-gemini-notebook-v1/post-gemini-notebook-research#model). Add it to the notebook with [POST /research/import](/docs/api-gemini-notebook-v1/post-gemini-notebook-research-import). While a job runs, `status` keeps the value it had when the job was accepted (`pending`, or `processing` when Google had already started) and changes only when the job completes or fails. A one-shot job starts `pending` while its sources are processed, and its `artifact` appears here once Google has created it. The `202` of a sync one-shot request can already show `processing` once its artifact exists, while this endpoint keeps showing `pending` until the job completes or fails. | `error.code` | Meaning | |---|---| | `quota` | Not enough of Google's 5-hour or weekly usage window was left for this job. `retryAt` says when it resets, when Google's refusal names the window. [GET /accounts/`email`](/docs/api-gemini-notebook-v1/get-gemini-notebook-accounts-email) shows what each action needs. | | `generation_failed` | Google reported the generation as failed. [POST /artifacts/retry](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts-retry) re-runs it in place. For a research job, Google ended the run in a state the API does not recognise. | | `sources` | One-shot only: the notebook got no usable source, or its sources were still processing after 5 minutes. | | `not_found` | The artifact, research run or notebook disappeared while the job ran (deleted here or in the web app). | | `account` | Google signed the account out, and it must be re-added via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). The same code is used when the account was removed with [DELETE /accounts/`email`](/docs/api-gemini-notebook-v1/delete-gemini-notebook-accounts-email) while the job ran, with the message `Account <email> is no longer configured`. | | `timeout` | Still running after 40 minutes. Check [GET /artifacts/`artifact`](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts-artifact) later, Google may still finish it. For a research job, check the notebook in the Gemini Notebook web app. | | `cancelled` | Cancelled with [DELETE /jobs/`jobid`](/docs/api-gemini-notebook-v1/delete-gemini-notebook-jobs-jobid). A research run cancelled in the Gemini Notebook web app fails with this code too. | | `scheduler` | The job could not be scheduled on our side. Google may already have started the generation, so check [GET /artifacts](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts) before you submit it again. | | `google_error` | Any other refusal from Google. `message` has the details. | The `replyUrl` webhook is one `POST` with `Content-Type: application/json` and this record as the body, sent once when the job completes or fails (a 10-second timeout, no retries). A job cancelled with [DELETE /jobs/`jobid`](/docs/api-gemini-notebook-v1/delete-gemini-notebook-jobs-jobid) sends no webhook. Use `replyRef` to match the callback to your own records. </details> ##### Examples **Curl** ``` bash JOBID="job:12597f9a-010c-4758-8e9a-b5cc17b0ccdb-user:12345-user@example.com-bot:gemini_notebook" curl -H "Authorization: Bearer …" \ "https://api.useapi.net/v1/gemini-notebook/jobs/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$JOBID")" ``` **JavaScript** ``` javascript const token = "API token"; const jobid = "job:12597f9a-010c-4758-8e9a-b5cc17b0ccdb-user:12345-user@example.com-bot:gemini_notebook"; const apiUrl = `https://api.useapi.net/v1/gemini-notebook/jobs/${encodeURIComponent(jobid)}`; let job; do { await new Promise(resolve => setTimeout(resolve, 15000)); const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); job = await response.json(); console.log(job.status); } while (job.status === "pending" || job.status === "processing"); console.log("job", job); ``` **Python** ``` python import requests, time, urllib.parse token = "API token" jobid = "job:12597f9a-010c-4758-8e9a-b5cc17b0ccdb-user:12345-user@example.com-bot:gemini_notebook" apiUrl = "https://api.useapi.net/v1/gemini-notebook/jobs/" + urllib.parse.quote(jobid, safe="") headers = { "Authorization" : f"Bearer {token}" } while True: time.sleep(15) job = requests.get(apiUrl, headers=headers).json() print(job.get("status")) if job.get("status") not in ("pending", "processing"): break print(job) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> jobs description: "See each Gemini Notebook account's load via GET jobs in the useapi.net API — health, maxJobs, the Studio and research jobs running now and the last-known 5-hour and weekly usage." parent: Gemini Notebook API nav_order: 700 permalink: /docs/api-gemini-notebook-v1/get-gemini-notebook-jobs --- ## List running jobs September 29, 2026 (November 16, 2026) --- The load-balancing picture in one call: for every configured account, its health, its `maxJobs` limit, the Studio and research jobs running on it right now, and the last usage Google reported for it. A job is listed from the moment [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts), [POST /artifacts/retry](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts-retry), [POST /artifacts/revise](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts-revise), [POST /artifacts/generate](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts-generate) or [POST /research](/docs/api-gemini-notebook-v1/post-gemini-notebook-research) accepts it until it completes, fails or is [cancelled](/docs/api-gemini-notebook-v1/delete-gemini-notebook-jobs-jobid). Each listed job takes one of its account's `maxJobs` slots. When all slots are taken, a new job on that account is refused with `429`, and a one-shot request without `email` goes to another account that has a free slot. Poll a single job with [GET /jobs/`jobid`](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid). This endpoint reads our own records only and never calls Google, so it is cheap to poll and is never cached. > **https://api.useapi.net/v1/gemini-notebook/jobs** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** ```json { "accounts": { "user@example.com": { "health": "OK", "maxJobs": 3, "running": 1, "jobs": [ { "jobid": "job:21ade7e0-f2c0-48a1-904d-688096a3ff29-user:12345-user@example.com-bot:gemini_notebook", "type": "video", "started_at": "2026-09-28T04:32:44.630Z", "artifact": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:7f923bb5-fb59-4ee6-ade6-9ae559a660fe" } ], "quota": { "windows": [ { "window": "5h", "resetsAt": "2026-09-28T09:25:40.000Z", "usedPercent": 0, "remainingPercent": 100 }, { "window": "weekly", "resetsAt": "2026-10-04T23:25:40.000Z", "usedPercent": 3.14, "remainingPercent": 96.86 } ], "blocked": [], "at": "2026-09-28T04:32:37.575Z" } }, "another@example.com": { "health": "OK", "maxJobs": 2, "running": 0, "jobs": [] } } } ``` With no accounts configured the answer is `{ "accounts": {} }`. **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` ##### Model The `accounts` object, keyed by email: each account's health, `maxJobs`, the jobs running on it now and the last usage Google reported. <details markdown="block" class="model-details"> <summary>Each account's health, running jobs and last known usage, field by field</summary> ```typescript { // TypeScript, all fields are optional accounts: { [email: string]: { health: string // 'OK', 'verifying' (Google reported it signed out and we are re-checking it), // the account's error text (re-add it), or 'account deleted' maxJobs: number | null // concurrent-job limit set via POST /accounts; null for a deleted account running: number // jobs running on this account now jobs: Array<{ jobid: string type: 'audio' | 'video' | 'report' | 'interactive_report' | 'table' | 'quiz' | 'flashcards' | 'infographic' | 'slides' | 'mindmap' | 'research' started_at: string // ISO 8601, when the job was accepted artifact?: string // the artifact id, once Google has created it research?: 'fast' | 'deep' // research jobs (POST /research): the kind of run }> quota?: { // last usage Google reported; absent when none is known from the last 5 hours windows: Array<{ window: '5h' | 'weekly' resetsAt: string | null // ISO 8601 usedPercent: number remainingPercent: number }> blocked: string[] // Studio actions Google refuses right now, e.g. 'cinematic' at: string // ISO 8601, when this usage was read } } } } ``` An account shows `account deleted` when it was removed with [DELETE /accounts/`email`](/docs/api-gemini-notebook-v1/delete-gemini-notebook-accounts-email) while jobs were still running on it. `quota` is refreshed every time [GET /accounts/`email`](/docs/api-gemini-notebook-v1/get-gemini-notebook-accounts-email) reads live usage and after every job finishes. For live numbers, the reset times and what each Studio action costs, call [GET /accounts/`email`](/docs/api-gemini-notebook-v1/get-gemini-notebook-accounts-email). A one-shot [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts) without `email` skips an account whose last-known usage shows a window at 100% or the requested action blocked. </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/gemini-notebook/jobs" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = "https://api.useapi.net/v1/gemini-notebook/jobs"; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" apiUrl = "https://api.useapi.net/v1/gemini-notebook/jobs" headers = { "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/get-gemini-notebook-labels === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/get-gemini-notebook-labels --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> labels description: "List a notebook's source labels via GET labels in the useapi.net Gemini Notebook API — each label's name, emoji and the sources it groups." parent: Gemini Notebook API nav_order: 490 permalink: /docs/api-gemini-notebook-v1/get-gemini-notebook-labels --- ## List source labels September 29, 2026 (November 16, 2026) --- List the labels that group a notebook's sources, as the source panel of the Gemini Notebook web app shows them. Each label has a name, an optional emoji and the ids of its sources. A source can be in more than one label, and sources without a label are not listed here. Create labels with [POST /labels](/docs/api-gemini-notebook-v1/post-gemini-notebook-labels), either by letting Google label the sources by topic or by naming one yourself. Change one with [POST /labels/`label`](/docs/api-gemini-notebook-v1/post-gemini-notebook-labels-label) and remove it with [DELETE /labels/`label`](/docs/api-gemini-notebook-v1/delete-gemini-notebook-labels-label). > **https://api.useapi.net/v1/gemini-notebook/labels?notebook=`notebook`** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `notebook` is **required**, the notebook id returned by [POST /notebooks](/docs/api-gemini-notebook-v1/post-gemini-notebook-notebooks) or [GET /notebooks](/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks), for example `user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55`. The id names the account the notebook lives on, so no `email` parameter is needed. URL-encode it (it contains `:` and `@`). ##### Responses **200** **200 OK** A notebook without labels returns `"labels": []`. ```json { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "labels": [ { "label": "user:12345-user@example.com-label:d02c903b-17f8-4241-a263-2be9e7359d55:01a0466f-bd9f-48ab-a27d-5ae84181aa42", "name": "Apollo 11 Mission", "sources": [ "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:1761af94-f5aa-47f3-9539-0b4ebcd547f8", "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:2744eb7c-399a-4573-bd32-126143ba9514" ] }, { "label": "user:12345-user@example.com-label:d02c903b-17f8-4241-a263-2be9e7359d55:5973ba2b-845e-41b5-97b2-ef855d5746ad", "name": "The landing", "emoji": "🚀", "sources": [] } ] } ``` **400** **400 Bad Request** ```json { "error": "Parameter notebook is required", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The id was issued to a different API token. ```json { "error": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55 does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** The notebook was deleted, or its account is no longer configured. ```json { "error": "Not found on account user@example.com (Google I3xc3c grpc 5)", "code": 404 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` **503** **503 Service Unavailable** Google is temporarily unavailable or is challenging our network. Retry in a few minutes. A `502` means Google answered with an unexpected error. ```json { "error": "Google is temporarily unavailable (I3xc3c grpc 14), please retry", "code": 503 } ``` ##### Model The notebook's labels, each with its id, name, optional emoji and the ids of the sources it groups. <details markdown="block" class="model-details"> <summary>The notebook's source labels, field by field</summary> ```typescript { // TypeScript, all fields are optional notebook: string labels: { label: string // user:<id>-<email>-label:<notebook uuid>:<label uuid> name: string emoji?: string sources: string[] // source ids with this label }[] error: string // error responses only code: number // error responses only, the HTTP status } ``` </details> ##### Examples **Curl** ``` bash curl -G "https://api.useapi.net/v1/gemini-notebook/labels" \ -H "Authorization: Bearer …" \ --data-urlencode "notebook=user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55" ``` **JavaScript** ``` javascript const token = "API token"; const notebook = "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55"; const apiUrl = `https://api.useapi.net/v1/gemini-notebook/labels?notebook=${encodeURIComponent(notebook)}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" notebook = "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55" apiUrl = "https://api.useapi.net/v1/gemini-notebook/labels" headers = { "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers, params={"notebook": notebook}) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks-guide === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks-guide --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> notebooks/guide description: "Read a notebook's guide via GET notebooks/guide in the useapi.net Gemini Notebook API — Google's summary of all its sources, suggested reports and suggested chat questions." parent: Gemini Notebook API nav_order: 260 permalink: /docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks-guide --- ## Retrieve the notebook guide September 29, 2026 (November 16, 2026) --- Read what the Gemini Notebook web app shows at the top of a notebook, live from Google: - `summary`, Google's overview of all the notebook's sources, in Markdown. - `suggestedReports`, report topics Google proposes, each with the prompt that would write it. A prompt can be passed as `instructions` to [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts) with `type: "report"` and `format: "custom"`. - `suggestedQuestions`, questions to ask in [chat](/docs/api-gemini-notebook-v1/post-gemini-notebook-chat), each with a short title and the full prompt. They are based on the sources whose `status` is `ready`, and the list is empty when there are none. > **https://api.useapi.net/v1/gemini-notebook/notebooks/guide?notebook=`notebook`** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `notebook` is **required**, the notebook id returned by [POST /notebooks](/docs/api-gemini-notebook-v1/post-gemini-notebook-notebooks) or [GET /notebooks](/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks), for example `user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55`. The id names the account the notebook lives on, so no `email` parameter is needed. URL-encode it (it contains `:` and `@`). ##### Responses **200** **200 OK** Summary shortened. ```json { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "summary": "**Apollo 11** was the historic **American space mission** in July 1969 that successfully achieved the first **crewed lunar landing**. Propelled by a **Saturn V rocket** from the Kennedy Space Center, astronauts **Neil Armstrong**, **Buzz Aldrin**, and **Michael Collins** journeyed to the Moon...", "suggestedReports": [ { "title": "How did the Space Race rivalry influence the mission's success?", "prompt": "Create a detailed briefing document designed to address this topic: \"How did the Space Race rivalry influence the mission's success?\". Include quotes from the original sources where appropriate." }, { "title": "Tell me about the challenges during the Eagle's lunar descent.", "prompt": "Create a detailed briefing document designed to address this topic: \"Tell me about the challenges during the Eagle's lunar descent.\". Include quotes from the original sources where appropriate." } ], "suggestedQuestions": [ { "title": "Mission Timeline", "prompt": "Create a chronological narrative of the mission events from launch to safe splashdown." }, { "title": "Astronaut Perspective", "prompt": "Focus on the experience of the crew including the challenge of lunar surface operations." } ] } ``` **400** **400 Bad Request** ```json { "error": "Parameter notebook is required", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The id was issued to a different API token. ```json { "error": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55 does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** The notebook was deleted, or its account is no longer configured. ```json { "error": "Not found on account user@example.com (Google rLM1Ne grpc 5)", "code": 404 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` **503** **503 Service Unavailable** Google is temporarily unavailable or is challenging our network. Retry in a few minutes. A `502` means Google answered with an unexpected error. ```json { "error": "Google is temporarily unavailable (VfAZjd grpc 14), please retry", "code": 503 } ``` ##### Model Google's Markdown summary of the notebook's sources, plus suggested reports and questions, each with a title and its prompt. <details markdown="block" class="model-details"> <summary>The notebook guide, field by field</summary> ```typescript { // TypeScript, all fields are optional notebook: string summary: string | null // Markdown suggestedReports: { title: string prompt: string }[] suggestedQuestions: { // [] when no source is ready title: string prompt: string }[] error: string // error responses only code: number // error responses only, the HTTP status } ``` </details> ##### Examples **Curl** ``` bash curl -G "https://api.useapi.net/v1/gemini-notebook/notebooks/guide" \ -H "Authorization: Bearer …" \ --data-urlencode "notebook=user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55" ``` **JavaScript** ``` javascript const token = "API token"; const notebook = "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55"; const apiUrl = `https://api.useapi.net/v1/gemini-notebook/notebooks/guide?notebook=${encodeURIComponent(notebook)}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" notebook = "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55" apiUrl = "https://api.useapi.net/v1/gemini-notebook/notebooks/guide" headers = { "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers, params={"notebook": notebook}) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks-notebook === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks-notebook --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> notebooks/`notebook` description: "Read one notebook via GET notebooks/notebook in the useapi.net Gemini Notebook API v1 — sources with processing status and word counts, plus Studio artifacts." parent: Gemini Notebook API nav_order: 220 permalink: /docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks-notebook --- ## Retrieve a notebook September 29, 2026 (November 16, 2026) --- Read a notebook live from Google: its title, every source with its processing `status`, and every Studio artifact it holds. Sources are processed by Google after they are added. Poll this endpoint until the sources you need show `status: ready` before you [chat](/docs/api-gemini-notebook-v1/post-gemini-notebook-chat) or generate [artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts). The `artifacts` list here is the short form (id, title, type, status). Use [GET /artifacts/`artifact`](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts-artifact) for an artifact's content and download links. > **https://api.useapi.net/v1/gemini-notebook/notebooks/`notebook`** - `notebook` is **required**, the notebook id returned by [POST /notebooks](/docs/api-gemini-notebook-v1/post-gemini-notebook-notebooks) or [GET /notebooks](/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks). It contains `:` and `@`, so URL-encode it in the path (`encodeURIComponent` in JavaScript). Example: `user%3A12345-user%40example.com-notebook%3Ad02c903b-17f8-4241-a263-2be9e7359d55` ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** ```json { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "email": "user@example.com", "title": "Apollo 11", "emoji": "🚀", "created": "2026-09-27T23:24:40.000Z", "updated": "2026-09-27T23:25:32.000Z", "sources": [ { "source": "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:5a5455b1-0557-4fa4-a8a8-52f60dffa113", "title": "01-apollo11-wikipedia.pdf", "kind": "pdf", "status": "ready", "words": 21578, "mimeType": "application/pdf", "created": "2026-09-27T23:24:53.000Z" }, { "source": "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:9732772d-0111-447b-ba78-9eec2c1c2ffe", "title": "A New Look at the Apollo 11 Landing Site", "kind": "youtube", "status": "ready", "words": 13, "url": "https://www.youtube.com/watch?v=xUcYQ7slmRw", "created": "2026-09-27T23:24:43.000Z" }, { "source": "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:c1182943-b7f0-4e89-82bc-8b3614cfb78f", "title": "Apollo 11 - Wikipedia", "kind": "web", "status": "ready", "words": 25492, "url": "https://en.wikipedia.org/wiki/Apollo_11", "created": "2026-09-27T23:24:43.000Z" } ], "artifacts": [ { "artifact": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:4ae7c76c-18f5-44a1-a54c-8158327528e3", "title": "50 Seconds from Lunar Disaster", "type": "video", "status": "completed", "created": "2026-09-27T23:51:17.000Z" }, { "artifact": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:ae28f2a1-678b-4304-9806-09648fcb77a0", "title": "Apollo 11 Flight Plan", "type": "slides", "status": "completed", "created": "2026-09-27T23:31:15.000Z" } ] } ``` **400** **400 Bad Request** ```json { "error": "Path parameter notebook (abc) is not a valid notebook id", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The notebook id was issued to a different API token. ```json { "error": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55 does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** The notebook was deleted, or its account is no longer configured. ```json { "error": "Not found on account user@example.com (Google rLM1Ne grpc 5)", "code": 404 } ``` ```json { "error": "Account user@example.com of user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55 is not configured", "code": 404 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` **503** **503 Service Unavailable** Google is temporarily unavailable, retry shortly. A `502` means Google answered with an unexpected error. ```json { "error": "Google is temporarily unavailable (rLM1Ne grpc 14), please retry", "code": 503 } ``` ##### Source and artifact values Each source carries a `kind` and a `status`: | kind | Source | |---|---| | `web` | Web page URL | | `youtube` | YouTube video URL | | `text` | Pasted `text`, or an uploaded `.txt` file | | `pdf` | PDF file | | `docx` | Word document | | `pptx` | PowerPoint presentation | | `epub` | EPUB e-book | | `markdown` | Markdown file, a note converted with [POST /notes/source](/docs/api-gemini-notebook-v1/post-gemini-notebook-notes-source), or a Deep Research report added with [POST /research/import](/docs/api-gemini-notebook-v1/post-gemini-notebook-research-import) | | `csv` | CSV file | | `media` | Audio or video file (e.g. `.mp3`, `.mp4`) | | `image` | Image file (e.g. `.jpg`) | | `google_docs` | A Google Doc from Google Drive (`drive` parameter) | | `drive` | A Google Drive file that is not a Google Doc, such as a `.docx` or `.pptx` (`drive` parameter) | | `book` | An ebook from the account's Google Play Books library (`books` parameter) | A kind Google adds later is returned as `kind<N>`, with Google's own number. | status | Meaning | |---|---| | `preparing` | The file was received and is waiting to be processed. New uploads start here. | | `processing` | Google is reading the source. | | `ready` | The source can be used by chat and Studio. | | `error` | Google could not process the source. | An unrecognised status is returned as `status<N>`. Each artifact carries a `type` and a `status`: | Field | Values | |---|---| | artifact `type` | `audio`, `video`, `report`, `interactive_report`, `table`, `quiz`, `flashcards`, `infographic`, `slides`, `mindmap` | | artifact `status` | `pending`, `processing`, `completed`, `failed`, `pending_review` | An artifact type or status Google adds later is returned as `type<N>` or `status<N>`, with Google's number. ##### Model The notebook's title, emoji and dates, every source with its processing `status`, and the short form of every Studio artifact. <details markdown="block" class="model-details"> <summary>The notebook with its sources and artifacts, field by field</summary> ```typescript { // TypeScript, all fields are optional notebook: string email: string // the account the notebook lives on title: string emoji: string | null created: string | null // ISO 8601 updated: string | null // ISO 8601 sources: { source: string // user:<userId>-<email>-source:<notebookUuid>:<sourceUuid> title: string kind: string // see the table above status: string // see the table above words?: number // word count, once Google has read the source url?: string // web page or YouTube URL mimeType?: string // uploaded files driveFileId?: string // Google Drive sources: the Drive file id created?: string // ISO 8601 }[] artifacts: { artifact: string // user:<userId>-<email>-artifact:<notebookUuid>:<artifactUuid> title: string type: string // see the table above status: string // see the table above created: string | null // ISO 8601 }[] error: string // error responses only code: number // error responses only, the HTTP status } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/gemini-notebook/notebooks/user%3A12345-user%40example.com-notebook%3Ad02c903b-17f8-4241-a263-2be9e7359d55" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const notebook = "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55"; const apiUrl = `https://api.useapi.net/v1/gemini-notebook/notebooks/${encodeURIComponent(notebook)}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests, urllib.parse token = "API token" notebook = "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55" apiUrl = "https://api.useapi.net/v1/gemini-notebook/notebooks/" + urllib.parse.quote(notebook, safe="") headers = { "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> notebooks description: "List notebooks on every configured Google account, or one via ?email=, with GET notebooks in the useapi.net Gemini Notebook API v1: titles, source counts, dates." parent: Gemini Notebook API nav_order: 210 permalink: /docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks --- ## List notebooks September 29, 2026 (November 16, 2026) --- List the notebooks of your Gemini Notebook accounts, read live from Google. The response has one entry per account. Without `email`, every healthy account is listed and accounts in an error state are skipped (see [GET /accounts](/docs/api-gemini-notebook-v1/get-gemini-notebook-accounts)). An account that fails while being read returns an `error` in its entry instead of `notebooks`, and the other accounts are still listed. The list includes notebooks created in the Gemini Notebook web app, not only the ones created through the API. Use [GET /notebooks/`notebook`](/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks-notebook) for a notebook's sources and artifacts. > **https://api.useapi.net/v1/gemini-notebook/notebooks/?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `email` is optional, list only this account's notebooks. When omitted, every healthy account is listed. ##### Responses **200** **200 OK** ```json [ { "email": "user@example.com", "notebooks": [ { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "title": "Apollo 11", "emoji": "🚀", "sources": 17, "created": "2026-09-27T23:24:40.000Z", "updated": "2026-09-27T23:25:32.000Z" }, { "notebook": "user:12345-user@example.com-notebook:93e89cc9-db25-46d0-bc14-216736e6b4c2", "title": "", "emoji": null, "sources": 0, "created": "2026-09-27T22:45:33.000Z", "updated": "2026-09-27T22:45:34.000Z" } ] }, { "email": "user2@example.com", "error": "Could not reach Gemini Notebook (HTTP 500), please retry" } ] ``` **400** **400 Bad Request** ```json { "error": "Parameter limit not supported", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **404** **404 Not Found** The `email` account is not configured. ```json { "error": "Account user@example.com not found", "code": 404 } ``` ##### Model One entry per account, with its notebooks (id, title, emoji, source count and dates), or an `error` when the account could not be read. <details markdown="block" class="model-details"> <summary>The notebooks of each account, field by field</summary> ```typescript { // TypeScript, all fields are optional email: string // the account notebooks: { notebook: string // user:<userId>-<email>-notebook:<uuid>, URL-encode it when used in a path title: string // '' for an untitled notebook emoji: string | null // the notebook's emoji sources: number // number of sources in the notebook created: string | null // ISO 8601 updated: string | null // ISO 8601 }[] error: string // instead of notebooks, when this account could not be read }[] ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/gemini-notebook/notebooks/?email=user@example.com" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const apiUrl = `https://api.useapi.net/v1/gemini-notebook/notebooks/?email=${encodeURIComponent(email)}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured account email" apiUrl = "https://api.useapi.net/v1/gemini-notebook/notebooks/" headers = { "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers, params={"email": email}) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/get-gemini-notebook-notes-note === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/get-gemini-notebook-notes-note --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> notes/`note` description: "Read one notebook note via GET notes/note in the useapi.net Gemini Notebook API — its title, full text, type (note or saved_answer) and created and updated times." parent: Gemini Notebook API nav_order: 430 permalink: /docs/api-gemini-notebook-v1/get-gemini-notebook-notes-note --- ## Retrieve a note September 29, 2026 (November 16, 2026) --- Read one note by its id, live from Google. The note is the same row [GET /notes](/docs/api-gemini-notebook-v1/get-gemini-notebook-notes) lists, including chat answers saved as notes in the Gemini Notebook web app (`type: saved_answer`) and mind maps (`type: mindmap`), whose `content` is the mind map's JSON tree. > **https://api.useapi.net/v1/gemini-notebook/notes/`note`** - `note` is **required**, the note id returned by [POST /notes](/docs/api-gemini-notebook-v1/post-gemini-notebook-notes) or [GET /notes](/docs/api-gemini-notebook-v1/get-gemini-notebook-notes). It contains `:` and `@`, so URL-encode it in the path (`encodeURIComponent` in JavaScript). The id names its account, so no `email` is needed. ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** ```json { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "note": "user:12345-user@example.com-note:d02c903b-17f8-4241-a263-2be9e7359d55:e5514ee8-22e5-414d-aa67-86e8476ece09", "title": "Landing timeline", "content": "Powered descent began at 102:33 GET.", "type": "note", "created": "2026-09-29T04:08:58.000Z", "updated": "2026-09-29T04:08:58.000Z" } ``` **400** **400 Bad Request** The path does not hold a valid note id, for example it holds a source id. ```json { "error": "Path parameter note (user%3A12345-user%40example.com-source%3Ad02c903b-17f8-4241-a263-2be9e7359d55%3A10f43c6b-a0a6-46a8-b330-06a5718dffb2) is not a valid note id", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The note id was issued to a different API token. ```json { "error": "user:12345-user@example.com-note:d02c903b-17f8-4241-a263-2be9e7359d55:e5514ee8-22e5-414d-aa67-86e8476ece09 does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** The note was deleted, its notebook was deleted, or its account is no longer configured. ```json { "error": "Note user:12345-user@example.com-note:d02c903b-17f8-4241-a263-2be9e7359d55:e5514ee8-22e5-414d-aa67-86e8476ece09 not found", "code": 404 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` **503** **503 Service Unavailable** Google is temporarily unavailable, retry shortly. A `502` means Google answered with an unexpected error. ```json { "error": "Google is temporarily unavailable (cFji9 grpc 14), please retry", "code": 503 } ``` ##### Model The note's id, title, `content` and `type` (`note`, `saved_answer` or `mindmap`), with its notebook and dates. <details markdown="block" class="model-details"> <summary>The note and its content, field by field</summary> ```typescript { // TypeScript, all fields are optional notebook: string note: string // user:<id>-<email>-note:<notebook uuid>:<note uuid> title: string content: string type: string // note | saved_answer | mindmap created?: string // ISO 8601. Google moves it to the edit time when the content changes updated?: string // ISO 8601 error: string // error responses only code: number // error responses only, the HTTP status } ``` </details> ##### Examples **Curl** ``` bash NOTE="user:12345-user@example.com-note:d02c903b-17f8-4241-a263-2be9e7359d55:e5514ee8-22e5-414d-aa67-86e8476ece09" curl "https://api.useapi.net/v1/gemini-notebook/notes/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$NOTE")" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const note = "user:12345-user@example.com-note:d02c903b-17f8-4241-a263-2be9e7359d55:e5514ee8-22e5-414d-aa67-86e8476ece09"; const apiUrl = `https://api.useapi.net/v1/gemini-notebook/notes/${encodeURIComponent(note)}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests, urllib.parse token = "API token" note = "user:12345-user@example.com-note:d02c903b-17f8-4241-a263-2be9e7359d55:e5514ee8-22e5-414d-aa67-86e8476ece09" apiUrl = "https://api.useapi.net/v1/gemini-notebook/notes/" + urllib.parse.quote(note, safe="") headers = { "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/get-gemini-notebook-notes === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/get-gemini-notebook-notes --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> notes description: "List the notes of one notebook via GET notes in the useapi.net Gemini Notebook API — written notes, saved chat answers and mind maps, with title, text and timestamps." parent: Gemini Notebook API nav_order: 410 permalink: /docs/api-gemini-notebook-v1/get-gemini-notebook-notes --- ## List notes September 29, 2026 (November 16, 2026) --- List every note of one notebook, read live from Google. Notes are the notebook's own notepad: the ones written with [POST /notes](/docs/api-gemini-notebook-v1/post-gemini-notebook-notes) or in the Gemini Notebook web app, and chat answers saved to a note in the web app. Each note carries a `type`: | type | Note | |---|---| | `note` | A note written by hand or with [POST /notes](/docs/api-gemini-notebook-v1/post-gemini-notebook-notes) | | `saved_answer` | A chat answer saved as a note in the web app. Its `content` keeps the answer's citation markers such as `[1]` | | `mindmap` | A mind map made with [POST /notes/mindmap](/docs/api-gemini-notebook-v1/post-gemini-notebook-notes-mindmap) or in the web app. Its `content` is the mind map as a JSON string, a tree of `{ name, children }` nodes | A type Google adds later is returned as `type<N>`, with Google's number. > **https://api.useapi.net/v1/gemini-notebook/notes?notebook=`notebook`** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `notebook` is **required**, the notebook id returned by [POST /notebooks](/docs/api-gemini-notebook-v1/post-gemini-notebook-notebooks) or [GET /notebooks](/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks), for example `user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55`. The id names the account the notebook lives on, so no `email` parameter is needed. URL-encode it (it contains `:` and `@`). ##### Responses **200** **200 OK** A notebook without notes returns `"notes": []`. ```json { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "notes": [ { "note": "user:12345-user@example.com-note:d02c903b-17f8-4241-a263-2be9e7359d55:e5514ee8-22e5-414d-aa67-86e8476ece09", "title": "Landing timeline", "content": "Powered descent began at 102:33 GET.", "type": "note", "created": "2026-09-29T04:08:58.000Z", "updated": "2026-09-29T04:08:58.000Z" } ] } ``` **400** **400 Bad Request** ```json { "error": "Parameter notebook is required", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The notebook id was issued to a different API token. ```json { "error": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55 does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** The notebook was deleted, or its account is no longer configured. ```json { "error": "Not found on account user@example.com (Google cFji9 grpc 5)", "code": 404 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` **503** **503 Service Unavailable** Google is temporarily unavailable, retry shortly. A `502` means Google answered with an unexpected error. ```json { "error": "Google is temporarily unavailable (cFji9 grpc 14), please retry", "code": 503 } ``` ##### Model Every note of the notebook, each with its id, title, text, `type` and dates. <details markdown="block" class="model-details"> <summary>The notebook's notes, field by field</summary> ```typescript { // TypeScript, all fields are optional notebook: string notes: { note: string // user:<id>-<email>-note:<notebook uuid>:<note uuid> title: string content: string // the note's text type: string // note | saved_answer | mindmap created?: string // ISO 8601. Google moves it to the edit time when the content changes updated?: string // ISO 8601 }[] error: string // error responses only code: number // error responses only, the HTTP status } ``` </details> ##### Examples **Curl** ``` bash curl -G "https://api.useapi.net/v1/gemini-notebook/notes" \ -H "Authorization: Bearer …" \ --data-urlencode "notebook=user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55" ``` **JavaScript** ``` javascript const token = "API token"; const notebook = "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55"; const apiUrl = `https://api.useapi.net/v1/gemini-notebook/notes?notebook=${encodeURIComponent(notebook)}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" notebook = "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55" apiUrl = "https://api.useapi.net/v1/gemini-notebook/notes" headers = { "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers, params={"notebook": notebook}) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/get-gemini-notebook-sharing === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/get-gemini-notebook-sharing --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> sharing description: "Read who can open a notebook via GET sharing in the useapi.net Gemini Notebook API — people with their owner, editor or viewer role, link access and the allow-copies setting." parent: Gemini Notebook API nav_order: 470 permalink: /docs/api-gemini-notebook-v1/get-gemini-notebook-sharing --- ## Retrieve sharing September 29, 2026 (November 16, 2026) --- Read a notebook's sharing settings live from Google, as the Share dialog of the Gemini Notebook web app shows them: every person with access and their role, whether anyone with the link can open the notebook, and whether copies are allowed. Change them with [POST /sharing](/docs/api-gemini-notebook-v1/post-gemini-notebook-sharing). | Field | Values | |---|---| | person `role` | `owner` (the account the notebook lives on), `editor`, `viewer` | | `link` | `public` (anyone with the link), `restricted` (only the people listed) | | `allowCopies` | `true` (the default) or `false`. Applies to a public link. | A role Google adds later is returned as `role<N>`, with Google's number. Google's sharing read does not include the view level (full notebook or chat only). [POST /sharing](/docs/api-gemini-notebook-v1/post-gemini-notebook-sharing) sets it with `viewLevel`. > **https://api.useapi.net/v1/gemini-notebook/sharing?notebook=`notebook`** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `notebook` is **required**, the notebook id returned by [POST /notebooks](/docs/api-gemini-notebook-v1/post-gemini-notebook-notebooks) or [GET /notebooks](/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks), for example `user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55`. The id names the account the notebook lives on, so no `email` parameter is needed. URL-encode it (it contains `:` and `@`). ##### Responses **200** **200 OK** A notebook shared with one viewer, link access restricted: ```json { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "people": [ { "email": "user@example.com", "role": "owner", "name": "Jane Doe" }, { "email": "colleague@example.com", "role": "viewer", "name": "colleague" } ], "link": "restricted", "allowCopies": true } ``` **400** **400 Bad Request** ```json { "error": "Parameter notebook is required", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The notebook id was issued to a different API token. ```json { "error": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55 does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** The notebook was deleted, or its account is no longer configured. ```json { "error": "Not found on account user@example.com (Google rLM1Ne grpc 5)", "code": 404 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` **503** **503 Service Unavailable** Google is temporarily unavailable, retry shortly. A `502` means Google answered with an unexpected error. ```json { "error": "Google is temporarily unavailable (JFMDGd grpc 14), please retry", "code": 503 } ``` ##### Model The people with access and their roles, whether the `link` is `public` or `restricted`, and whether copies are allowed. <details markdown="block" class="model-details"> <summary>The notebook's sharing settings, field by field</summary> ```typescript { // TypeScript, all fields are optional notebook: string people: { email: string role: string // owner | editor | viewer name: string | null // the person's Google display name }[] link: 'public' | 'restricted' allowCopies: boolean error: string // error responses only code: number // error responses only, the HTTP status } ``` </details> ##### Examples **Curl** ``` bash curl -G "https://api.useapi.net/v1/gemini-notebook/sharing" \ -H "Authorization: Bearer …" \ --data-urlencode "notebook=user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55" ``` **JavaScript** ``` javascript const token = "API token"; const notebook = "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55"; const apiUrl = `https://api.useapi.net/v1/gemini-notebook/sharing?notebook=${encodeURIComponent(notebook)}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" notebook = "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55" apiUrl = "https://api.useapi.net/v1/gemini-notebook/sharing" headers = { "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers, params={"notebook": notebook}) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/get-gemini-notebook-sources-books === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/get-gemini-notebook-sources-books --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> sources/books description: "List the account's Google Play Books library via GET sources/books in the useapi.net Gemini Notebook API — which ebooks can be added to a notebook as sources." parent: Gemini Notebook API nav_order: 305 permalink: /docs/api-gemini-notebook-v1/get-gemini-notebook-sources-books --- ## List Play Books October 15, 2026 (November 16, 2026) --- List the ebooks in the account's [Google Play Books](https://play.google.com/store/books) library. An ebook the account owns can be added to a notebook as a source with the `books` parameter of [POST /sources](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources). Gemini Notebook then answers questions and builds Studio artifacts from the whole book, the same way it does from a PDF or a web page. Only books whose publisher allows it can be added. Those have `addable: true`. The others are listed with `addable: false` and a `reason`, and the Gemini Notebook web app shows them greyed out. On a book's Google Play page, an eligible book shows Gemini Notebook as available under Tools. Books you uploaded to Play Books yourself are not listed. Add such a file with [POST /sources/upload](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources-upload) instead. The book must be bought (or claimed, if it is free) on the Google account itself. > **https://api.useapi.net/v1/gemini-notebook/sources/books?email=`email`** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `email` is optional when the API token has a single [account](/docs/api-gemini-notebook-v1/get-gemini-notebook-accounts), and required otherwise. ##### Responses **200** **200 OK** An empty library returns `"books": []`. ```json { "email": "user@example.com", "books": [ { "book": "-OQ2q5JqOdEC", "title": "What Is Data Science?", "authors": [ "Mike Loukides" ], "cover": "https://play.google.com/books/content/images/frontcover/-OQ2q5JqOdEC", "addable": true }, { "book": "khsZEAAAQBAJ", "title": "Howards End", "authors": [ "E. M. Forster" ], "cover": "https://play.google.com/books/publisher/content/images/frontcover/khsZEAAAQBAJ", "addable": true }, { "book": "Hfn4AAAAQBAJ", "title": "The Raven (Illustrated)", "authors": [ "Edgar Allan Poe" ], "cover": "https://play.google.com/books/publisher/content/images/frontcover/Hfn4AAAAQBAJ", "addable": false, "reason": "the publisher opted out" } ] } ``` **400** **400 Bad Request** ```json { "error": "email is required: this API token has several accounts", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **404** **404 Not Found** The `email` is not one of your configured accounts. ```json { "error": "Account user@example.com is not configured", "code": 404 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` **503** **503 Service Unavailable** Google is temporarily unavailable or is challenging our network. Retry in a few minutes. A `502` means Google answered with an unexpected error. ```json { "error": "GOOGLE_BOT_CHECK: Google is challenging our network right now, please retry in a few minutes", "code": 503 } ``` ##### Model The account's Play Books ebooks, each with its id, title, authors, cover and whether it can be added as a source. <details markdown="block" class="model-details"> <summary>The account's Play Books and the error answer, field by field</summary> ```typescript { // TypeScript, all fields are optional email: string books: { book: string // the Google Play Books id, pass it in POST /sources books title: string authors: string[] cover?: string // cover image URL addable: boolean // false: Google does not allow this book as a source reason?: string // why not, when addable is false, e.g. "the publisher opted out" }[] } ``` Errors return: ```typescript { error: string code: number // the HTTP status } ``` </details> ##### Examples **Curl** ``` bash curl -G "https://api.useapi.net/v1/gemini-notebook/sources/books" \ -H "Authorization: Bearer …" \ --data-urlencode "email=user@example.com" ``` **JavaScript** ``` javascript const token = "API token"; const email = "user@example.com"; const apiUrl = `https://api.useapi.net/v1/gemini-notebook/sources/books?email=${encodeURIComponent(email)}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" apiUrl = "https://api.useapi.net/v1/gemini-notebook/sources/books" headers = { "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers, params={"email": "user@example.com"}) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/get-gemini-notebook-sources-source === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/get-gemini-notebook-sources-source --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> sources/`source` description: "Read one notebook source via GET sources/source in the useapi.net Gemini Notebook API — Google's summary and key topics, Drive sync state and, on request, the indexed text." parent: Gemini Notebook API nav_order: 325 permalink: /docs/api-gemini-notebook-v1/get-gemini-notebook-sources-source --- ## Retrieve a source September 29, 2026 (November 16, 2026) --- Read one source live from Google: the same fields [GET /notebooks/`notebook`](/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks-notebook) lists for it, plus the source guide the web app shows when you open a source (a `summary` and its key `topics`). For a Google Drive source (kind `google_docs` or `drive`) the response also says whether the notebook's copy still matches the file in Drive (`inSync`). When it does not, re-import the file with [POST /sources/sync](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources-sync). For a changed Google Doc, this check itself can start Google's re-import, so the source may already hold the new text a few seconds later. Add `content=true` to get the full text Google indexed for the source, which is what [chat](/docs/api-gemini-notebook-v1/post-gemini-notebook-chat) answers from. `summary`, `topics`, `inSync` and `content` are returned only once the source's `status` is `ready`. > **https://api.useapi.net/v1/gemini-notebook/sources/`source`?content=`content`** - `source` is **required**, the source id, URL-encoded in the path (it contains `:` and `@`). Source ids are returned by [POST /sources](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources), [POST /sources/upload](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources-upload) and [GET /notebooks/`notebook`](/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks-notebook). The id names its account, so no `email` is needed. ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `content` is optional, `true` adds the source's indexed text as `content`. Default: `false`. ##### Responses **200** **200 OK** A pasted-text source, with `content=true`: ```json { "source": "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:10f43c6b-a0a6-46a8-b330-06a5718dffb2", "title": "Why Apollo 11 almost did not land", "kind": "text", "status": "ready", "words": 90, "created": "2026-09-29T04:08:46.000Z", "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "summary": "The historic Apollo 11 mission faced **critical dangers during its final descent**, including unexpected computer malfunctions and a hazardous boulder field that forced the crew to **take manual control of the spacecraft**...", "topics": [ "Apollo 11 landing", "Computer program alarms", "Manual final approach", "Historic moonwalk", "Lunar sample collection" ], "content": "Why Apollo 11 almost did not land\n\nThe lunar module Eagle landed in the Sea of Tranquility on July 20, 1969. During the descent the guidance computer raised 1202 and 1201 program alarms..." } ``` **400** **400 Bad Request** The path does not hold a valid source id, for example it holds a notebook or note id. ```json { "error": "Path parameter source (user%3A12345-user%40example.com-notebook%3Ad02c903b-17f8-4241-a263-2be9e7359d55) is not a valid source id", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The source id was issued to a different API token. ```json { "error": "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:10f43c6b-a0a6-46a8-b330-06a5718dffb2 does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** The source is no longer in its notebook, the notebook was deleted, or the account named in the id is no longer configured. ```json { "error": "Source user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:10f43c6b-a0a6-46a8-b330-06a5718dffb2 not found", "code": 404 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` **503** **503 Service Unavailable** Google is temporarily unavailable or is challenging our network. Retry in a few minutes. A `502` means Google answered with an unexpected error. ```json { "error": "Google is temporarily unavailable (tr032e grpc 14), please retry", "code": 503 } ``` ##### Model The source with its `status`, plus Google's summary and key topics once it is `ready`, and its indexed text with `content=true`. <details markdown="block" class="model-details"> <summary>The source with its summary and topics, field by field</summary> The source fields are those of [POST /sources](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources#model). All `kind` and `status` values are listed in [Source kinds and statuses](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources#source-kinds-and-statuses). ```typescript { // TypeScript, all fields are optional source: string // user:<id>-<email>-source:<notebook uuid>:<source uuid> title: string kind: string status: string // preparing | processing | ready | error words?: number url?: string // web page or YouTube URL mimeType?: string // file sources driveFileId?: string // Google Drive sources: the Drive file id created?: string // ISO 8601 notebook: string // the notebook the source belongs to summary?: string | null // status ready: Google's summary of the source (Markdown) topics?: string[] // status ready: key topics inSync?: boolean // status ready, Drive sources only: false once the Drive file changed since it was added content?: string // status ready, with content=true: the text Google indexed error: string // error responses only code: number // error responses only, the HTTP status } ``` </details> ##### Examples **Curl** ``` bash SOURCE="user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:10f43c6b-a0a6-46a8-b330-06a5718dffb2" curl "https://api.useapi.net/v1/gemini-notebook/sources/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$SOURCE")?content=true" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const source = "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:10f43c6b-a0a6-46a8-b330-06a5718dffb2"; const apiUrl = `https://api.useapi.net/v1/gemini-notebook/sources/${encodeURIComponent(source)}?content=true`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests, urllib.parse token = "API token" source = "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:10f43c6b-a0a6-46a8-b330-06a5718dffb2" apiUrl = "https://api.useapi.net/v1/gemini-notebook/sources/" + urllib.parse.quote(source, safe="") headers = { "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers, params={"content": "true"}) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1 === Document URL: https://useapi.net/docs/api-gemini-notebook-v1 --- layout: default title: Gemini Notebook API nav_logo: /assets/images/gemini-notebook.svg nav_title: Gemini Notebook API seo_title: "Gemini Notebook API (NotebookLM API): Podcasts, Video and Slides" description: "Third-party Gemini Notebook API (NotebookLM API) by useapi.net: podcasts, Video Overviews, slides and quizzes over REST or MCP, free plan included." nav_order: 2050 has_children: true permalink: /docs/api-gemini-notebook-v1 repo: https://github.com/useapi/notebooklm-api --- # <img style="height:0.9em;vertical-align: middle;" src="/assets/images/gemini-notebook.svg" alt=""> Gemini Notebook API (NotebookLM API) September 29, 2026 (November 16, 2026) This is a [third-party](/docs/legal#affiliation--third-party-services) API for [Gemini Notebook (formerly NotebookLM)](https://notebook.google.com) by Google. It uses your [Google AI subscription](https://gemini.google/subscriptions/): Free, Plus $4.99 (or [$9.99 with 2 TB of storage](https://one.google.com/about/plans)), Pro $19.99, Ultra $99.99 or Ultra $199.99 a month (as of November 2026). This REST API and hosted MCP server turn web pages, PDFs and YouTube videos into podcasts (Audio Overviews), Video Overviews, slide decks, quizzes and cited answers, on a free Google account too. Google offers no Gemini Notebook API for regular Google accounts (as of October 2026). ## What it makes | Output | What you get | Notes | |---|---|---| | [Audio Overview](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts) (podcast) | `m4a` | Deep dive, brief, critique or debate, short to long, in any language, with your own focus instructions | | [Video Overview](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts) | `mp4` | Explainer, brief, short or cinematic (Pro and Ultra), 9 visual styles or your own style prompt | | [Slide deck](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts) | `pdf`, `pptx` and an image of each slide | Detailed or presenter, short to long, and [revise any slide](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts-revise) with a prompt | | [Infographic](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts) | `png` | Landscape, portrait or square, 11 styles, concise to detailed | | [Report](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts) and interactive report | Markdown, [exported](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts-export) to Google Docs | Briefing, study guide, blog post or your own prompt. An interactive report suggests infographics, slides, quizzes and more, each [generated](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts-generate) on its own | | [Data table](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts) | Rows of cells, [exported](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts-export) to Google Sheets | Built from your instructions | | [Quiz, flashcards and mind map](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts) | JSON | Fewer to more questions, easy to hard, and mind maps also as [notes](/docs/api-gemini-notebook-v1/post-gemini-notebook-notes-mindmap) | | [Chat](/docs/api-gemini-notebook-v1/post-gemini-notebook-chat) | Answers from your sources with numbered citations | Follow-ups and [history](/docs/api-gemini-notebook-v1/get-gemini-notebook-chat), a learning-guide or custom persona, [longer or shorter answers](/docs/api-gemini-notebook-v1/post-gemini-notebook-chat-settings) | | [Deep Research and Discover sources](/docs/api-gemini-notebook-v1/post-gemini-notebook-research) | A cited report and the web pages it read | Discover also searches your Google Drive, then [import](/docs/api-gemini-notebook-v1/post-gemini-notebook-research-import) the sources and the report | | [Sources](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources) | Web pages, YouTube videos, text, [files](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources-upload), Google Drive and [Google Play Books](/docs/api-gemini-notebook-v1/get-gemini-notebook-sources-books) ebooks | Files up to 200 MB: PDF, Word, PowerPoint, EPUB, Markdown, CSV, audio, video and images. Drive files [sync](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources-sync) when they change | | More | [Notes](/docs/api-gemini-notebook-v1/post-gemini-notebook-notes), [labels](/docs/api-gemini-notebook-v1/post-gemini-notebook-labels), source [search](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources-search), [append](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources-append) and [copy](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources-copy), [collections](/docs/api-gemini-notebook-v1/get-gemini-notebook-collections), [notebook copies](/docs/api-gemini-notebook-v1/post-gemini-notebook-notebooks-copy), the notebook [guide](/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks-guide), [sharing](/docs/api-gemini-notebook-v1/post-gemini-notebook-sharing) and [artifact copies](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts-copy) | | ## MCP server The hosted [Gemini Notebook MCP server (NotebookLM MCP server)](/docs/api-gemini-notebook-v1/mcp) gives Claude Code, Cursor, VS Code and other AI assistants 57 tools for notebooks, sources, chat, Deep Research and every Studio output, with your useapi.net API token and nothing to install. The [notebooklm-api](https://github.com/useapi/notebooklm-api) repo also adds it in one step as a [Claude Code plugin](https://github.com/useapi/notebooklm-api#use-with-claude-code) or a [Gemini CLI extension](https://github.com/useapi/notebooklm-api#use-with-gemini-cli), and has a [Dify plugin](https://marketplace.dify.ai/plugins/useapi/notebooklm_useapi) with 56 tools for Dify [workflows, chatflows](https://docs.dify.ai/en/cloud/use-dify/build/workflow-chatflow) and [agents](https://docs.dify.ai/en/cloud/use-dify/build/new-agent/overview). ## Pricing How the useapi.net Gemini Notebook API (NotebookLM API) compares with Google's own API (October 2026). Gemini Notebook has no credits and no price per item: podcasts, videos and every other result come out of your Google account's usage, which refills every 5 hours up to a weekly limit, and a bigger Google AI plan gets more. | | useapi.net Gemini Notebook API | Google's [Gemini Notebook Enterprise API](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks) | |---|:-:|:-:| | Accounts | Your own Google accounts, free or paid plans | Enterprise licenses in a Google Cloud project | | Cost | Your Google AI subscription, the free plan included | Per-user Enterprise licenses | | Chat with citations | Yes | No | | Deep Research | Yes | No | | Audio Overviews | Yes | Yes | | Video Overviews, slides, infographics, reports, quizzes, flashcards, mind maps | Yes | No | | Status | Third-party | Preview (Pre-GA) | - A free Google account makes everything except cinematic Video Overviews, which need Pro or Ultra (Plus doesn't have them either), and each free account you connect adds its own usage. - Google publishes only notebook and source limits per plan: Free 100 notebooks and 50 sources each, Plus 200 and 100, Pro 500 and 300, Ultra 500 and up to 600 ([Google's limits](https://support.google.com/notebooklm/answer/16213268)). How much a single job uses depends on its length and type. [GET /accounts/`email`](/docs/api-gemini-notebook-v1/get-gemini-notebook-accounts-email) shows each account's live usage and when it refills. - Paid plans also let you [share a notebook](/docs/api-gemini-notebook-v1/post-gemini-notebook-sharing) as chat only. #### One Google account, four APIs The same Google AI plan powers several useapi.net APIs, each from its own allowance, so one Google account connected to all of them gets the most out of the plan: - [Google Flow API](/docs/api-google-flow-v1): Veo 3.1, Omni 1.2 Flash and Omni 1.1 Flash video, Nano Banana images up to 4K, from Flow credits. - [Google Vids API](/docs/api-google-vids-v1): Omni 1.2 Flash video up to 15 seconds, 30-second [talking avatar videos](/docs/api-google-vids-v1/post-google-vids-videos-avatar) from a photo, avatars in 30 voices and [text to speech](/docs/api-google-vids-v1/post-google-vids-speech), from the Vids allowance, which does not use Flow credits. - [Gemini Notebook API (NotebookLM API)](/docs/api-gemini-notebook-v1): chat with sources, Deep Research and every Studio output, from the Gemini Notebook usage limits. - [Flow Music API](/docs/api-flowmusic-v1): full songs with Lyria in Google Flow Music, on the Flow Music plan your Google AI subscription includes (Starter on [Plus](https://support.google.com/googleone/answer/16882689), Plus on [Pro](https://support.google.com/googleone/answer/14534406), Member on [Ultra](https://support.google.com/googleone/answer/16286513)) or on Flow Music's own plans. Each API is set up on its own setup page, and one useapi.net subscription covers all of them. ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. ## Run several Gemini Notebook accounts Each useapi.net subscription connects 3 Google accounts, up to 100 in total. Studio and research jobs don't need `email`: each one goes to an account that is healthy, has a free job slot within its `maxJobs` and still has usage left for that job, so nobody has to watch Google's 5-hour and weekly budgets. A [one-shot request](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts#one-shot-requests) with `urls` or `text` creates the notebook on such an account for you. When every account is busy or out of usage you get `429`, with `retryAt` when Google names the reset time, so wait or send the job to a specific account with `email`. [GET /jobs](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs) shows the load on every account. Every job can post its finished record to your webhook with `replyUrl`, or you poll [GET /jobs/`jobid`](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid), so a 10-minute Video Overview needs no open connection. [How useapi.net works](/docs/how-it-works) has tips for keeping your accounts healthy. ## Questions ### Does Gemini Notebook (NotebookLM) have an API? Through useapi.net, yes, for regular Google accounts: the Gemini Notebook API runs on your Google AI subscription, the free one included, with chat with citations, Deep Research and every Studio output. Google's own [Gemini Notebook Enterprise API](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks) needs Enterprise licenses in a Google Cloud project and covers only notebooks, sources, sharing and Audio Overviews (as of October 2026). ### How much does the Gemini Notebook (NotebookLM) API cost? Through useapi.net, a podcast, video or answer has no price of its own: it uses the Gemini Notebook usage of your Google AI subscription. It works on a free Google account, and a paid Google AI plan raises the usage. See the [comparison](#pricing). ### Is there a Gemini Notebook (NotebookLM) API key? Through useapi.net, you call Gemini Notebook with our [API token](/docs/start-here/setup-useapi), since Google issues no Gemini Notebook API key for regular accounts. You connect your Google account once through the [automated browser setup](/docs/start-here/setup-gemini-notebook): sign in with Google, with no cookies to copy and no Google Cloud project. We keep the session signed in, and if Google ever signs it out, you get an email with a one-minute re-add link. ### Can I generate Gemini Notebook (NotebookLM) podcasts with the API? Through useapi.net, yes: podcasts (Audio Overviews) and Video Overviews too. Send links or text to [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts) and download the podcast as `.m4a`, a Video Overview as `.mp4`, slides as `.pdf` and `.pptx` or an infographic as `.png`. No code? The [n8n tutorial](/docs/articles/notebooklm-n8n-podcast) turns web pages, YouTube videos or an RSS feed into a podcast. ### Why use useapi.net instead of a free Gemini Notebook library? Through useapi.net, Gemini Notebook runs hosted. The popular free libraries [notebooklm-py](https://github.com/teng-lin/notebooklm-py) and [gemini-notebook-mcp-cli](https://github.com/jacob-bd/gemini-notebook-mcp-cli) install and run on your own machine, while here nothing runs on your computer, so jobs keep going with your laptop off. We keep your Google session signed in with no cookies to refresh, report every job by webhook and spread jobs across up to 100 Google accounts. The [Gemini Notebook API options](/docs/articles/notebooklm-api-options) article compares them side by side. [Setup Gemini Notebook (NotebookLM)](/docs/start-here/setup-gemini-notebook) [Google Account Setup](https://github.com/useapi/google-account-setup) Scripts for a clean, single-use Google sign-in (Windows, macOS, Linux) [LLM-friendly API spec](https://useapi.net/assets/aibot/api-gemini-notebook-v1.txt) Feed this to your LLM to build integrations [Claude Code skill](/llm-tools) A drop-in useapi.net skill for Claude Code, and a rule for Cursor [Postman collection](https://www.postman.com/useapinet/useapi-net/collection/29112081-40696e39-d128-417e-984b-fe1b97e7bb00) (October 15, 2026) [MCP Server](/docs/api-gemini-notebook-v1/mcp) Notebooks, chat and Studio from Claude Code, Cursor, VS Code and other MCP clients [Agent skill: notebooklm-podcast](https://github.com/useapi/notebooklm-api/tree/main/skills/notebooklm-podcast) Claude Code and Codex turn links or files into a Gemini Notebook podcast or Video Overview [GitHub examples](https://github.com/useapi/notebooklm-api) Node.js, Python and bash, a Colab notebook, n8n workflows, a Dify plugin and an agent skill [n8n template: Gemini Notebook (NotebookLM) Podcast App]({% include n8n-url.html t="notebook-podcast" %}) Turn links or an RSS feed into a podcast you play in the browser, ready to import Articles: * [Can You Use Your Google AI Subscription Through an API? What Plus, Pro and Ultra Get You](/docs/articles/google-ai-subscription-api) {% include lang-switch.html mode="hub" key="google-ai-subscription" %} * [Gemini Notebook (NotebookLM) API Options in 2026: Google Enterprise API, Free Libraries or a Hosted API](/docs/articles/notebooklm-api-options) * [How to Automate Gemini Notebook (NotebookLM) with the API: Deep Research, Chat, Audio Overviews and a Lot More](/docs/articles/gemini-notebook-bash) {% include lang-switch.html mode="hub" key="gemini-notebook" %} * [Turn a Web Page or YouTube Video into a Podcast with Gemini Notebook (NotebookLM): A Real Example](/docs/articles/notebooklm-podcast-example) * [How to Turn Web Pages, YouTube Videos and RSS Feeds into Gemini Notebook (NotebookLM) Podcasts with n8n](/docs/articles/notebooklm-n8n-podcast) Videos on YouTube: * [NotebookLM has no API. Now it does: podcasts, video, slides from one REST call](https://www.youtube.com/shorts/ISOQAabo0b0) Developer Community: * <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> * <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> === URL: https://useapi.net/docs/api-gemini-notebook-v1/mcp === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/mcp --- layout: default title: MCP Server nav_icon: mcp seo_title: "Gemini Notebook MCP Server (NotebookLM MCP): Hosted, 57 Tools" description: "Connect the Claude app, ChatGPT or Claude Code to the hosted useapi.net Gemini Notebook MCP server (NotebookLM MCP server): 57 tools for notebooks, sources and Studio." parent: Gemini Notebook API nav_order: 50 permalink: /docs/api-gemini-notebook-v1/mcp --- ## Gemini Notebook MCP Server (NotebookLM MCP Server) October 15, 2026 (November 1, 2026) --- The useapi.net Gemini Notebook MCP server lets an AI assistant such as the Claude app, ChatGPT, Claude Code, Cursor or VS Code Copilot use [Gemini Notebook](https://notebook.google.com), formerly NotebookLM, on your own Google accounts. It is a hosted [Model Context Protocol](https://modelcontextprotocol.io) server with 57 tools: create notebooks, add web pages, YouTube videos, files, Google Drive files and Google Play Books ebooks as sources, ask questions answered with citations, and generate every Studio output, from Audio Overviews and Video Overviews to slide decks, infographics, quizzes and mind maps. Each tool calls the [Gemini Notebook API](/docs/api-gemini-notebook-v1), so the same rules and limits apply. Nothing needs to be installed or hosted. **Is there a Gemini Notebook MCP server (NotebookLM MCP server)?** Yes. useapi.net, a third-party service not affiliated with Google, hosts a Gemini Notebook MCP server at `https://api.useapi.net/v1/gemini-notebook/mcp` with 57 tools for notebooks, sources, chat and every Studio output, on your own Google account, nothing to install. Prefer REST? Tutorials: [Gemini Notebook (NotebookLM) API Options in 2026](/docs/articles/notebooklm-api-options) · [How to Automate Gemini Notebook with the API](/docs/articles/gemini-notebook-bash) · Code: [github.com/useapi/notebooklm-api](https://github.com/useapi/notebooklm-api) See all useapi.net MCP servers on [Model Matrix & MCP](/model-matrix#mcp-servers). ## Endpoint and authorization ``` https://api.useapi.net/v1/gemini-notebook/mcp ``` - Transport: Streamable HTTP. - Listed in the [official MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers/net.useapi%2Fgemini-notebook/versions/latest) as `net.useapi/gemini-notebook`, so MCP clients and directories that read the registry can find it by that name. - Authorization: your useapi.net API token in the `Authorization: Bearer …` header, see [Setup useapi.net](/docs/start-here/setup-useapi). The Claude app and ChatGPT sign in with OAuth instead, see [Use it in the Claude app or ChatGPT](#use-it-in-the-claude-app-or-chatgpt). - You need at least one Google account added with [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). Adding and removing accounts is not available over MCP: use [POST /accounts](/docs/api-gemini-notebook-v1/post-gemini-notebook-accounts) or the setup page. ## Setup Replace `YOUR_API_TOKEN` with your useapi.net API token. ### Claude Code ```bash claude mcp add --transport http useapi-gemini-notebook https://api.useapi.net/v1/gemini-notebook/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` ### Cursor In `~/.cursor/mcp.json`: ```json { "mcpServers": { "useapi-gemini-notebook": { "url": "https://api.useapi.net/v1/gemini-notebook/mcp", "headers": { "Authorization": "Bearer YOUR_API_TOKEN" } } } } ``` ### VS Code In `.vscode/mcp.json`: ```json { "servers": { "useapi-gemini-notebook": { "type": "http", "url": "https://api.useapi.net/v1/gemini-notebook/mcp", "headers": { "Authorization": "Bearer YOUR_API_TOKEN" } } } } ``` ### Windsurf and other clients Any client that supports remote MCP servers over HTTP with custom headers works. The usual JSON shape: ```json { "mcpServers": { "useapi-gemini-notebook": { "serverUrl": "https://api.useapi.net/v1/gemini-notebook/mcp", "headers": { "Authorization": "Bearer YOUR_API_TOKEN" } } } } ``` Some clients name the address field `url` instead of `serverUrl`. ### Test it with curl ```bash curl -s https://api.useapi.net/v1/gemini-notebook/mcp \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}' curl -s https://api.useapi.net/v1/gemini-notebook/mcp \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' ``` The first call answers with the server's name `useapi-gemini-notebook` and its instructions for the assistant, the second with the 57 tools. ## Use it in the Claude app or ChatGPT The Claude app ([claude.ai](https://claude.ai) and Claude Desktop) and [ChatGPT](https://chatgpt.com) can add this server as a custom connector. They sign in with OAuth: you give the app the URL, it opens a useapi.net page, and you paste your useapi.net API token there once. Both work on their Free plans. The API-token setups above for Claude Code, Cursor, VS Code and other clients keep working as before. ``` ``` ### Claude app 1. Open Settings → Connectors and click Add custom connector. 2. Enter a name, for example `useapi `, and the URL above, then click Add. 3. Click Connect. Claude opens the useapi.net sign-in page. 4. Paste your useapi.net API token and click Allow. Claude asks before each tool call unless you choose Always allow. The Free plan allows one custom connector. ### ChatGPT 1. Open Plugins, click Add and choose Add custom MCP server. 2. Enter a name and the URL above, and set Authentication to OAuth. 3. Tick ChatGPT's "I understand and want to continue" box, then click Create as a plugin. 4. Click Connect. ChatGPT opens the useapi.net sign-in page. 5. Paste your useapi.net API token and click Allow. ChatGPT asks you to confirm each tool call that creates or changes something. The Free plan works without developer mode (as of October 25, 2026). ### How the sign-in works - Your API token is in your welcome email, see [Setup useapi.net](/docs/start-here/setup-useapi). The useapi.net page links there too. - Each connection is for one MCP server. Connect each server you want to use on its own. - The app gets an access token that lasts 1 hour and renews it on its own. A connection you don't use for 90 days lapses, and you connect again. - [Resetting your API token](/docs/account-management/post-account-token-reset) disconnects every app connected with it. - - Results come back as public links, so they open right in the app. ## Tools Notebooks, sources, notes and artifacts are named by the ids the tools return, and each id carries its account. Tools that work on an account take `email`, which can be left out when the API token has one account. ### Accounts | Tool | What it does | Main parameters | |---|---|---| | `notebook_list_accounts` | Lists your accounts with health, `maxJobs`, running jobs and last known usage. | | | `notebook_get_account` | Reads one account live: plan, limits, the 5-hour and weekly usage, and the estimated cost of each Studio action. | `email` | | `notebook_update_account` | Sets `maxJobs` and the output language of Studio artifacts. | `email`, `maxJobs`, `outputLanguage` | ### Notebooks and collections | Tool | What it does | Main parameters | |---|---|---| | `notebook_list_notebooks` | Lists the notebooks of one account or of all of them. | `email` | | `notebook_get_notebook` | Reads a notebook with its sources and artifacts, and whether each source is ready. | `notebook` | | `notebook_create_notebook` | Creates an empty notebook. | `email`, `title` | | `notebook_rename_notebook` | Renames a notebook. | `notebook`, `title` | | `notebook_delete_notebook` | Deletes a notebook with everything in it. | `notebook` | | `notebook_copy_notebook` | Copies a notebook with its sources. | `notebook`, `title` | | `notebook_get_guide` | Returns Google's summary of the notebook, with suggested questions and reports. | `notebook` | | `notebook_list_collections` | Lists the collections (folders of notebooks). | `email` | | `notebook_create_collection` | Creates a collection. | `name`, `emoji`, `email` | | `notebook_update_collection` | Renames a collection, or adds and removes notebooks. | `collection`, `name`, `emoji`, `addNotebooks`, `removeNotebooks` | | `notebook_delete_collection` | Deletes a collection. Its notebooks stay. | `collection` | ### Sources | Tool | What it does | Main parameters | |---|---|---| | `notebook_add_sources` | Adds web pages, YouTube videos, pasted text, Google Drive files and Google Play Books ebooks in one call. | `notebook`, `urls`, `text`, `title`, `drive`, `books` | | `notebook_upload_source` | Adds a file (PDF, Word, PowerPoint, EPUB, Markdown, text, CSV, audio, video or image) from a public https URL of up to 50 MB, or sent as `contentBase64`. | `notebook`, `url` or `contentBase64`, `name`, `mimeType` | | `notebook_get_source` | Reads a source with Google's summary and key topics, and with `content: true` its full text. | `source`, `content` | | `notebook_rename_source` | Renames a source. | `source`, `title` | | `notebook_delete_source` | Removes a source. | `source` | | `notebook_sync_source` | Re-imports a Google Drive source after its file changed. | `source` | | `notebook_search_sources` | Finds the passages that match a query, best first. | `notebook`, `query`, `sources`, `limit` | | `notebook_append_to_source` | Adds text to the end of a source. | `source`, `text`, `title` | | `notebook_copy_sources` | Copies sources to another notebook of the same account. | `sources`, `notebook` | | `notebook_list_play_books` | Lists the account's Google Play Books library and which books can be added. | `email` | ### Chat, notes, labels and sharing | Tool | What it does | Main parameters | |---|---|---| | `notebook_ask` | Asks a question answered from the sources with numbered citations. Pass `conversation` to ask a follow-up. | `notebook`, `question`, `conversation`, `sources` | | `notebook_get_chat` | Reads a conversation. | `notebook`, `conversation` | | `notebook_delete_chat` | Deletes a conversation. | `notebook`, `conversation` | | `notebook_set_chat_settings` | Sets the chat goal (default, learning guide or a custom persona) and answer length. | `notebook`, `goal`, `persona`, `length` | | `notebook_list_notes`, `notebook_get_note`, `notebook_create_note`, `notebook_update_note`, `notebook_delete_note` | Manage notes. `notebook_create_note` with `conversation` saves a whole chat as a note. | `notebook`, `note`, `title`, `content`, `conversation` | | `notebook_note_to_source` | Turns a note into a source. | `note` | | `notebook_create_mindmap_note` | Makes a mind map of the sources as a note, in one call. | `notebook`, `sources`, `language`, `instructions` | | `notebook_list_labels`, `notebook_create_labels`, `notebook_update_label`, `notebook_delete_label` | Group sources with labels, named or assigned by Google by topic (`auto`). | `notebook`, `label`, `auto`, `name`, `emoji`, `addSources`, `removeSources` | | `notebook_get_sharing`, `notebook_set_sharing` | Read and change who can open a notebook, its link, copies and view level. | `notebook`, `people`, `link`, `allowCopies`, `viewLevel` | ### Studio and research | Tool | What it does | Main parameters | |---|---|---| | `notebook_generate_artifact` | Generates an Audio Overview, Video Overview, report, interactive report, data table, quiz, flashcards, infographic, slide deck or mind map. Without `notebook` it runs one-shot from `urls` or `text`. | `type`, `notebook`, `sources`, `urls`, `text`, and the type's options: `format`, `length`, `style`, `language`, `instructions`, `quantity`, `difficulty`, `orientation`, `detail` | | `notebook_get_job` | Reads a job, and with `wait: true` waits for it to finish. | `jobid`, `wait` | | `notebook_list_jobs` | Lists each account's running jobs and last known usage. | | | `notebook_cancel_job` | Stops tracking a job and frees its slot. Google may still finish the artifact, and its usage is spent either way. | `jobid` | | `notebook_list_artifacts` | Lists a notebook's artifacts. | `notebook` | | `notebook_get_artifact` | Reads an artifact: files with download URLs, a report's text, the JSON of a quiz, flashcards, mind map or table, slide texts, and an interactive report's suggested items. | `artifact` | | `notebook_get_slide` | Returns one slide of a slide deck, or an infographic, as an image the assistant can see, for example after revising a slide. | `artifact`, `slide`, `width` | | `notebook_rename_artifact`, `notebook_delete_artifact` | Rename or delete an artifact. Deleting a suggested item dismisses it. | `artifact`, `title` | | `notebook_retry_artifact` | Generates a failed artifact again. | `artifact` | | `notebook_revise_slide` | Changes one slide of a slide deck with a prompt. | `artifact`, `slide`, `prompt` | | `notebook_generate_suggested_item` | Generates an item an interactive report suggests, as suggested or with its own options. | `artifact` and the type's options | | `notebook_export_artifact` | Exports a report to Google Docs or a table to Google Sheets and returns its URL. | `artifact`, `destination`, `title` | | `notebook_copy_artifacts` | Copies finished artifacts to another notebook. | `artifacts`, `notebook` | | `notebook_research` | Lets Google find sources: `fast` (Discover) or `deep` (Deep Research with a report), on the web or the account's Google Drive. | `notebook`, `query`, `type`, `source` | | `notebook_import_research` | Adds the sources a research job found, and the Deep Research report. | `jobid`, `urls`, `report` | The options of each Studio type are listed on [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts). The full input schema of every tool comes from `tools/list`. ## Long-running work MCP clients usually give up on a tool call after about a minute, so a tool waits up to about 50 seconds: - A quiz, flashcards or a mind map usually finishes in that time, and the tool returns the result. - An Audio Overview, a Video Overview, a slide deck or research takes longer. The tool then returns the `jobid`, and `notebook_get_job` with `wait: true` picks it up. Ask the assistant to keep checking until it is done. - `notebook_ask` answers in about 5 to 40 seconds. Clients that ask for progress notifications get one about every 10 seconds while a tool waits. Files come back as download URLs. Fetch them with the same `Authorization` header. An infographic, and the first slide of a slide deck, also come back as an image the assistant can see. ## Example prompts - "Create a notebook from these three articles and make me a 10-minute deep-dive podcast about them." - "Upload this PDF and ask the notebook which risks it lists, with citations." - "Make a quiz of 10 easy questions from my Apollo notebook, then flashcards on the same topic." - "Make a portrait infographic in sketch-note style from the notebook, and show it to me." - "Run Deep Research on solid-state batteries in my Batteries notebook and import the sources and the report." - "Make an interactive report for a 12-year-old, then generate the slide deck it suggests." - "Export the briefing report to Google Docs and give me the link." ## Limits and notes - The tools use your Google accounts and the same rules as the REST API, such as `maxJobs` for Studio and research jobs. Studio output counts against the account's Google usage, see [Usage limits](/docs/start-here/setup-gemini-notebook#usage-limits). - A client may send up to 20 JSON-RPC requests in one batch. - If the client sends an `MCP-Protocol-Version` header, it must be one of the supported versions: `2025-06-18`, `2025-03-26` or `2024-11-05`. - Tool calls show in your [usage stats](/docs/account-management/get-account-stats) (`bot=gemini-notebook`) through the REST call each tool makes, the same rows a direct API request writes. === URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-accounts === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-accounts --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> accounts description: "Connect a Google account to the useapi.net Gemini Notebook API with POST accounts — paste its cookies to add or re-add it, or send email + maxJobs or outputLanguage to update it." parent: Gemini Notebook API nav_order: 100 permalink: /docs/api-gemini-notebook-v1/post-gemini-notebook-accounts --- ## Configure a Gemini Notebook account September 29, 2026 (November 16, 2026) --- Connect a Google account to the API with the cookies of a signed-in [Gemini Notebook](https://notebook.google.com) session. The easiest way is the [automated setup](/assets/setup-browser/gemini-notebook.html), which signs in for you and calls this endpoint. See [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook) for the manual cookie copy. The API checks the cookies with Google before saving the account. The account email is read from Google, together with its plan, its notebook and source limits, and its current usage. Posting cookies for an account that is already connected re-adds it: the cookies are replaced, and `added` and `maxJobs` are kept unless you send a new `maxJobs`. Re-adding is also how an account that Google signed out is brought back. To update a connected account, post its `email` without `cookies`, with `maxJobs`, `outputLanguage` or both. `maxJobs` is stored by the API and nothing is sent to Google for it. `outputLanguage` is Google's own account-wide setting for the language Studio artifacts are written in, the same setting as in the Gemini Notebook web app, so it is sent to Google. When both are sent, `maxJobs` is saved first. Each [useapi.net subscription](/docs/subscription) lets you connect 3 Google accounts, up to 100 in total. > **https://api.useapi.net/v1/gemini-notebook/accounts** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body Add or re-add an account: ```json { "cookies": "SID\tg.a000…\t.google.com\t/\t2027-11-01T00:00:00.000Z\t…\nOSID\tg.a000…\tnotebook.google.com\t/\t…", "maxJobs": 3 } ``` - `cookies` is **required** to add or re-add an account. Copy the cookie tables from DevTools as described in [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook#manual-setup) and paste them exactly as copied. The paste must contain `SID`, `HSID`, `SSID`, `APISID`, `SAPISID`, `LSID`, `OSID` and `__Secure-OSID`. A missing cookie returns `400` naming it. The API then checks the cookies with Google, and cookies that are not signed in to Gemini Notebook return `400`. Only these eight cookies are stored, and their values are never returned by the API. - `maxJobs` is optional, the number of jobs this account may run at the same time. Range: `1` to `10`. Default: `3` for a new account, the current value on a re-add. Update a connected account: ```json { "email": "user@example.com", "maxJobs": 5, "outputLanguage": "es" } ``` - `email` is **required** in this mode, the email of a connected account. Do not send it together with `cookies`. - `maxJobs` is optional, the new concurrency limit. Range: `1` to `10`. - `outputLanguage` is optional, the language Google writes this account's Studio artifacts in, as a language code such as `en`, `es`, `pt_BR` or `zh_Hans`. It applies to the whole Google account. [GET /accounts/`email`](/docs/api-gemini-notebook-v1/get-gemini-notebook-accounts-email) shows the current value. Send `maxJobs`, `outputLanguage` or both. If `maxJobs` was saved but Google refused the language, the call answers with Google's error, and its message says that `maxJobs` was saved and `outputLanguage` was not changed. ##### Responses **200** **200 OK** — the account was already connected and has been updated. ```json { "email": "user@example.com", "tier": "pro", "googleTier": "TIER_PRO", "googleTierCode": 2, "maxJobs": 3, "added": "2026-09-27T22:48:12.588Z", "updated": "2026-09-27T23:10:05.114Z", "cookies": [ "SID", "HSID", "SSID", "APISID", "SAPISID", "LSID", "OSID", "__Secure-OSID" ], "cookiesExpireAt": "2027-11-01T22:48:08.442Z", "limits": { "notebooks": 500, "sourcesPerNotebook": 300 }, "health": "OK", "quota": { "windows": [ { "window": "5h", "resetsAt": "2026-09-28T04:25:40.000Z", "usedPercent": 63.11, "remainingPercent": 36.89 }, { "window": "weekly", "resetsAt": "2026-10-04T23:25:40.000Z", "usedPercent": 3.01, "remainingPercent": 96.99 } ], "blocked": [ "cinematic" ], "actions": [ { "action": "audio", "allowed": true, "costTier": 3, "estimatedCostPercent": 11.03 }, { "action": "cinematic", "allowed": false, "costTier": 4, "estimatedCostPercent": 77.02 }, { "action": "quiz", "allowed": true, "costTier": 1, "estimatedCostPercent": 0.57 }, ... ] } } ``` - An update (`email` + `maxJobs` / `outputLanguage`) returns the same record without `quota`. It carries `outputLanguage` when you set it: the value Google echoed back, or `null` when Google accepted it but its answer could not be read. - `quota` is also left out when Google's usage could not be read at that moment. [GET /accounts/`email`](/docs/api-gemini-notebook-v1/get-gemini-notebook-accounts-email) reads it live at any time. **201** **201 Created** — a new account was connected. Same body as `200`, without `updated`. **400** **400 Bad Request** — a required cookie is missing, the cookies are not signed in, `email` was sent with `cookies`, both `maxJobs` and `outputLanguage` are missing in update mode, or a parameter is invalid. ```json { "error": "Missing cookies: OSID, __Secure-OSID. Copy them from notebook.google.com and accounts.google.com (DevTools → Application → Cookies).", "code": 400 } ``` ```json { "error": "These cookies are not signed in to Gemini Notebook. Sign in at https://notebook.google.com and copy the cookies again.", "code": 400 } ``` ```json { "error": "Parameter outputLanguage must be a language code such as en, es, pt_BR or zh_Hans", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **402** **402 Payment Required** — the subscription has expired, or a new account needs another [subscription](/docs/subscription). ```json { "error": "useapi.net ⁝ You have 1 subscription, you need 1 additional subscription (2 total) to support 4 accounts for the gemini_notebook API. Upgrade at https://useapi.net/docs/subscription", "code": 402 } ``` **404** **404 Not Found** — update mode: no account is connected for this `email`. ```json { "error": "Account user@example.com not found", "code": 404 } ``` **502** **502 Bad Gateway** — the cookies are signed in, but Gemini Notebook did not report the account's email. Nothing was saved. Retry the same request. ```json { "error": "Signed in, but Gemini Notebook did not report the account email — please retry", "code": 502 } ``` **503** **503 Service Unavailable** — Gemini Notebook could not be reached to check the cookies. Retry in a few minutes. ```json { "error": "Gemini Notebook is not reachable right now (shell-error HTTP 500), please retry", "code": 503 } ``` ##### Model `200` and `201` return the same account record. <details markdown="block" class="model-details"> <summary>The account record, field by field</summary> ```typescript { // TypeScript, all fields are optional email: string tier: string // Google's plan, short form: 'free' | 'pro' | 'ultra' | 'plus' | … | 'unknown' googleTier?: string | null // Google's own plan name: 'TIER_FREE' | 'TIER_PRO' | 'TIER_ULTRA' | 'TIER_PLUS' | …googleTier?: string // Google's own plan name: 'TIER_FREE' | 'TIER_PRO' | 'TIER_ULTRA' | 'TIER_PLUS' | … googleTierCode?: number | null // Google's plan code: 1 = Free, 2 = Pro, 3 = Ultra, 4 = Plus, …googleTierCode?: number // Google's plan code: 1 = Free, 2 = Pro, 3 = Ultra, 4 = Plus, … maxJobs: number added: string // ISO 8601, when the account was first connected updated?: string // ISO 8601, the last re-add or maxJobs change cookies: string[] // names of the stored cookies, never their values cookiesExpireAt: string | null // ISO 8601, the earliest expiry Google stated for the stored cookies addedVia?: 'setup-browser' // present when the account was added by the automated setup limits?: { notebooks: number | null // notebooks allowed on the plan sourcesPerNotebook: number | null // sources allowed per notebook } health: string // 'OK', 'verifying', or the reason the account must be re-added outputLanguage?: string | null // update with outputLanguage only: the language Google echoed back quota?: { windows: { window: '5h' | 'weekly' resetsAt: string | null // ISO 8601 usedPercent: number remainingPercent: number }[] blocked: string[] // actions Google refuses right now actions: { action: string // 'audio' | 'video' | 'cinematic' | 'video_short' | 'infographic' | 'slides' | 'report' | 'table' | 'flashcards' | 'quiz' | 'mindmap' | … allowed: boolean costTier: number | null estimatedCostPercent: number | null // Google's estimate, as % of the 5h window }[] } } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/gemini-notebook/accounts" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "email": "user@example.com", "maxJobs": 5 }' ``` **JavaScript** ``` javascript const token = "API token"; const cookies = "Cookie tables copied from DevTools"; const apiUrl = "https://api.useapi.net/v1/gemini-notebook/accounts"; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ cookies, maxJobs: 3 }) }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" cookies = "Cookie tables copied from DevTools" apiUrl = "https://api.useapi.net/v1/gemini-notebook/accounts" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } data = { "cookies": cookies, "maxJobs": 3 } response = requests.post(apiUrl, headers=headers, json=data) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts-artifact === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts-artifact --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> artifacts/`artifact` description: "Rename a Studio artifact via POST artifacts/artifact in the useapi.net Gemini Notebook API — set a new title of up to 200 characters, also used for its download filenames." parent: Gemini Notebook API nav_order: 620 permalink: /docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts-artifact --- ## Rename an artifact September 29, 2026 (November 16, 2026) --- Give a Studio artifact a new title. The title is what the Gemini Notebook web app shows, and [GET /artifacts/download](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts-download) names the downloaded file after it. > **https://api.useapi.net/v1/gemini-notebook/artifacts/`artifact`** - `artifact` is URL-encoded in the path (it contains `:` and `@`). Get it from [GET /artifacts](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts) or from the `artifact` field of a [job](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid). ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "title": "Apollo 11 Quiz, hard" } ``` - `title` is **required**, the new title. Length: `1` to `200` characters. ##### Responses **200** **200 OK** ```json { "artifact": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:07b94418-6c28-437c-98de-06bbeabb4e0c", "title": "Apollo 11 Quiz, hard" } ``` **400** **400 Bad Request** `title` is missing, empty or longer than 200 characters, or the path value is not an artifact id. ```json { "error": "Parameter title is required", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The artifact id was issued to a different API token. ```json { "error": "user:12345-user@example.com-artifact:d02c903b-…:07b94418-… does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** The account the artifact lives on is no longer configured, or Google reports the artifact as not found. ```json { "error": "Account user@example.com of user:12345-user@example.com-artifact:d02c903b-…:07b94418-… is not configured", "code": 404 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` ##### Model The answer is the artifact's id, as you sent it, and its new `title`. <details markdown="block" class="model-details"> <summary>The renamed artifact, field by field</summary> ```typescript { // TypeScript, all fields are optional artifact: string // the artifact id, as sent title: string // the new title error: string // error responses only code: number // error responses only } ``` </details> ##### Examples **Curl** ``` bash ARTIFACT="user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:07b94418-6c28-437c-98de-06bbeabb4e0c" curl -X POST "https://api.useapi.net/v1/gemini-notebook/artifacts/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$ARTIFACT")" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{"title": "Apollo 11 Quiz, hard"}' ``` **JavaScript** ``` javascript const token = "API token"; const artifact = "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:07b94418-6c28-437c-98de-06bbeabb4e0c"; const apiUrl = `https://api.useapi.net/v1/gemini-notebook/artifacts/${encodeURIComponent(artifact)}`; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ title: "Apollo 11 Quiz, hard" }), }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests, urllib.parse token = "API token" artifact = "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:07b94418-6c28-437c-98de-06bbeabb4e0c" apiUrl = "https://api.useapi.net/v1/gemini-notebook/artifacts/" + urllib.parse.quote(artifact, safe="") headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.post(apiUrl, headers=headers, json={"title": "Apollo 11 Quiz, hard"}) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts-copy === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts-copy --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> artifacts/copy description: "Copy Studio artifacts into another notebook on the same account via POST artifacts/copy in the useapi.net Gemini Notebook API, without generating them again." parent: Gemini Notebook API nav_order: 550 permalink: /docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts-copy --- ## Copy artifacts to another notebook October 15, 2026 (November 16, 2026) --- Copy Studio artifacts from one notebook into another notebook on the same account. Nothing is generated again. Each copy gets a new `artifact` id in the target notebook, and the originals stay where they are. All `artifacts` must come from one notebook, and the target `notebook` must be a different notebook on the same account. To copy a whole notebook with its sources use [POST /notebooks/copy](/docs/api-gemini-notebook-v1/post-gemini-notebook-notebooks-copy), and to copy sources only use [POST /sources/copy](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources-copy). The response lists each copy with `status: "pending"`. A copy completes on its own, without being generated again. Read it with [GET /artifacts/`artifact`](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts-artifact) or list the target with [GET /artifacts](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts). The API does not retry this call, so after a `502`, `503` or `504` check [GET /artifacts](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts) on the target notebook before you try again. > **https://api.useapi.net/v1/gemini-notebook/artifacts/copy** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "artifacts": [ "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:3c8b3e5e-4534-4430-aeb3-db347161a1ad" ], "notebook": "user:12345-user@example.com-notebook:5b7e2a41-9c0d-4e8f-a1b3-6d2c8f0e7a95" } ``` - `artifacts` is **required**, an array of `1` to `50` artifact ids, all from the same notebook. - `notebook` is **required**, the id of the notebook to copy into. It must be on the same account as the artifacts. ##### Responses **201** **201 Created** `from` is the original's id and `artifact` is the copy's new id. ```json { "notebook": "user:12345-user@example.com-notebook:5b7e2a41-9c0d-4e8f-a1b3-6d2c8f0e7a95", "artifacts": [ { "from": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:3c8b3e5e-4534-4430-aeb3-db347161a1ad", "artifact": "user:12345-user@example.com-artifact:5b7e2a41-9c0d-4e8f-a1b3-6d2c8f0e7a95:7282c160-d72e-40b4-b30d-774d0f585d4e", "type": "report", "title": "Comprehensive Briefing Document: Apollo 11 Mission and Historical Context", "status": "pending" } ] } ``` **400** **400 Bad Request** A missing or invalid parameter, artifacts from more than one notebook, artifacts already in the target, or a target on another account. ```json { "error": "artifacts must all come from one notebook", "code": 400 } ``` ```json { "error": "the artifacts are already in this notebook", "code": 400 } ``` ```json { "error": "artifact user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:3c8b3e5e-4534-4430-aeb3-db347161a1ad is on another account than notebook user:12345-other@example.com-notebook:5b7e2a41-9c0d-4e8f-a1b3-6d2c8f0e7a95", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The notebook id belongs to a different API token. ```json { "error": "user:12345-user@example.com-notebook:5b7e2a41-9c0d-4e8f-a1b3-6d2c8f0e7a95 does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** The account the notebook names is not configured, or a notebook or artifact no longer exists at Google. ```json { "error": "Account user@example.com of user:12345-user@example.com-notebook:5b7e2a41-9c0d-4e8f-a1b3-6d2c8f0e7a95 is not configured", "code": 404 } ``` **503** **503 Service Unavailable** Google is temporarily unavailable or is challenging our network. Check [GET /artifacts](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts) on the target notebook, then retry in a few minutes. A `502` means Google answered with an unexpected error. ```json { "error": "GOOGLE_BOT_CHECK: Google is challenging our network right now, please retry in a few minutes", "code": 503 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` ##### Model The target notebook and one row per copy: the original's id, the copy's new `artifact` id, its type, title and status. <details markdown="block" class="model-details"> <summary>The copied artifacts, field by field</summary> ```typescript { // TypeScript, all fields are optional notebook: string // the target notebook artifacts: { from: string // the original artifact's id artifact: string // the copy's id in the target notebook type: 'audio' | 'video' | 'report' | 'interactive_report' | 'table' | 'quiz' | 'flashcards' | 'infographic' | 'slides' | 'mindmap' title: string status: 'pending' | 'processing' | 'completed' | 'failed' }[] error: string // error responses only code: number // error responses only, the HTTP status } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/gemini-notebook/artifacts/copy" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "artifacts": ["user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:3c8b3e5e-4534-4430-aeb3-db347161a1ad"], "notebook": "user:12345-user@example.com-notebook:5b7e2a41-9c0d-4e8f-a1b3-6d2c8f0e7a95" }' ``` **JavaScript** ``` javascript const token = "API token"; const response = await fetch("https://api.useapi.net/v1/gemini-notebook/artifacts/copy", { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}` }, body: JSON.stringify({ artifacts: ["user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:3c8b3e5e-4534-4430-aeb3-db347161a1ad"], notebook: "user:12345-user@example.com-notebook:5b7e2a41-9c0d-4e8f-a1b3-6d2c8f0e7a95" }) }); const result = await response.json(); console.log("response", response.status, result); ``` **Python** ``` python import requests token = "API token" response = requests.post( "https://api.useapi.net/v1/gemini-notebook/artifacts/copy", headers={"Content-Type": "application/json", "Authorization": f"Bearer {token}"}, json={ "artifacts": ["user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:3c8b3e5e-4534-4430-aeb3-db347161a1ad"], "notebook": "user:12345-user@example.com-notebook:5b7e2a41-9c0d-4e8f-a1b3-6d2c8f0e7a95" } ) print(response.status_code, response.json()) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts-export === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts-export --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> artifacts/export description: "Export a report to Google Docs or a data table to Google Sheets via POST artifacts/export in the useapi.net Gemini Notebook API — returns the new file's link." parent: Gemini Notebook API nav_order: 540 permalink: /docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts-export --- ## Export an artifact to Google Docs or Sheets October 15, 2026 (November 16, 2026) --- Save a finished Studio artifact as a new file in the Google Drive of the account that holds it, the Export menu of the Gemini Notebook web app. Reports become a Google Doc. Data tables become a Google Sheet. The response carries the link to the new file. | `destination` | Artifact `type` | Creates | |---|---|---| | `docs` | `report` | a Google Doc | | `sheets` | `table` | a Google Sheet | Only a `completed` artifact can be exported. The new file belongs to the Google account that holds the notebook. > **https://api.useapi.net/v1/gemini-notebook/artifacts/export** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "artifact": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:3c8b3e5e-4534-4430-aeb3-db347161a1ad", "destination": "docs", "title": "Apollo 11 briefing" } ``` - `artifact` is **required**, the artifact id from [GET /artifacts](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts) or from the `artifact` field of a job. The id names its account and notebook, so no `email` is needed. - `destination` is **required**, where to export. Supported values: `docs` (for `report`), `sheets` (for `table`). - `title` is optional, the new file's name, up to 200 characters. Default: the artifact's title. ##### Responses **201** **201 Created** A report exported to Google Docs: ```json { "artifact": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:3c8b3e5e-4534-4430-aeb3-db347161a1ad", "destination": "docs", "url": "https://docs.google.com/document/d/1AbCdEfGhIjKlMnOpQrStUvWxYz0123456789aBcDeF" } ``` A data table exported to Google Sheets: ```json { "artifact": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:a92e5eee-f9a6-4640-906f-7b79b481e555", "destination": "sheets", "url": "https://docs.google.com/spreadsheets/d/1ZyXwVuTsRqPoNmLkJiHgFeDcBa9876543210zYxWvU/edit" } ``` **400** **400 Bad Request** A missing or invalid parameter, or a destination that does not take this artifact's type. ```json { "error": "destination sheets takes table (this one is report)", "code": 400 } ``` ```json { "error": "Parameter destination (pdf) valid values: docs,sheets", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The artifact id belongs to a different API token. ```json { "error": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:3c8b3e5e-4534-4430-aeb3-db347161a1ad does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** The artifact is no longer in its notebook, or the account it names is not configured. ```json { "error": "Artifact user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:3c8b3e5e-4534-4430-aeb3-db347161a1ad not found", "code": 404 } ``` **409** **409 Conflict** The artifact has not completed. ```json { "error": "Only a completed artifact can be exported (this one is processing)", "code": 409 } ``` **502** **502 Bad Gateway** Google answered without a link to the new file. The file may exist anyway, so look in the account's Google Drive before you export again. ```json { "error": "Google answered the export without a document link: it may have been created anyway, check the account's Google Drive before retrying", "code": 502 } ``` **503** **503 Service Unavailable** Google is temporarily unavailable or is challenging our network. Retry in a few minutes. ```json { "error": "GOOGLE_BOT_CHECK: Google is challenging our network right now, please retry in a few minutes", "code": 503 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` ##### Model The exported artifact's id, the `destination` and the `url` of the new Google Doc or Sheet in the account's Drive. <details markdown="block" class="model-details"> <summary>The exported artifact and its new Google file, field by field</summary> ```typescript { // TypeScript, all fields are optional artifact: string // the exported artifact's id destination: 'docs' | 'sheets' url: string // the new Google Doc or Sheet in the account's Google Drive error: string // error responses only code: number // error responses only, the HTTP status } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/gemini-notebook/artifacts/export" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "artifact": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:3c8b3e5e-4534-4430-aeb3-db347161a1ad", "destination": "docs", "title": "Apollo 11 briefing" }' ``` **JavaScript** ``` javascript const token = "API token"; const artifact = "user:12345-user@example.com-artifact:..."; const response = await fetch("https://api.useapi.net/v1/gemini-notebook/artifacts/export", { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}` }, body: JSON.stringify({ artifact, destination: "sheets" }) }); const result = await response.json(); console.log("response", response.status, result); ``` **Python** ``` python import requests token = "API token" artifact = "user:12345-user@example.com-artifact:..." response = requests.post( "https://api.useapi.net/v1/gemini-notebook/artifacts/export", headers={"Content-Type": "application/json", "Authorization": f"Bearer {token}"}, json={"artifact": artifact, "destination": "docs", "title": "Apollo 11 briefing"} ) print(response.status_code, response.json()) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts-generate === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts-generate --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> artifacts/generate description: "Generate an interactive report's suggested infographic, slide deck, mind map, quiz or flashcards via POST artifacts/generate in the useapi.net Gemini Notebook API, as a job." parent: Gemini Notebook API nav_order: 530 permalink: /docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts-generate --- ## Generate a suggested item October 15, 2026 (November 16, 2026) --- Generate one of the items an interactive report suggests. When an [interactive report](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts) completes, its result lists `embedded` items in reading order: infographics, slide decks, mind maps, quizzes and flashcards that Google wrote for that report. Each one starts with `status: "suggested"`. It has a `title` and a `description`, and nothing has been generated yet. This is the Generate button on the item's tile in the Gemini Notebook web app. With no options, the item's `description` is the prompt and every other option uses the web app's default. `instructions` replaces the description as the prompt. The other options depend on the item's type, see [Options by type](#options-by-type). The item keeps its `artifact` id. Once the job completes, the report's `embedded` list on [GET /artifacts/`artifact`](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts-artifact) shows the item as `completed`. To drop a suggested item instead, delete it with [DELETE /artifacts/`artifact`](/docs/api-gemini-notebook-v1/delete-gemini-notebook-artifacts-artifact). Only an item whose `status` is `suggested` can be generated. Any other artifact returns `409`. The generation is a job, exactly like a new one. It counts toward the account's `maxJobs`, and Google can refuse it with `429` when its usage window is short. `mode`, `replyUrl` and `replyRef` behave as on [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts#sync-async-and-webhooks): sync waits up to 90 seconds, async returns `201` at once, and [GET /jobs/`jobid`](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid) returns the result. ### Options by type Each type accepts only the options in its row. Omitted options use the default shown. | Item `type` | Options | `language` | `instructions` | |---|---|:--:|:--:| | `infographic` | `orientation`: `landscape` *(default)*, `portrait`, `square`<br>`detail`: `concise`, `standard` *(default)*, `detailed`<br>`style`: `auto` *(default)*, `sketch_note`, `professional`, `bento_grid`, `editorial`, `instructional`, `bricks`, `clay`, `anime`, `kawaii`, `scientific` | Yes | Yes | | `slides` | `format`: `detailed` *(default)*, `presenter`<br>`length`: `short`, `default` *(default)*, `long` | Yes | Yes | | `quiz` | `quantity`: `fewer`, `standard` *(default)*, `more`<br>`difficulty`: `easy`, `medium` *(default)*, `hard` | Yes | Yes | | `flashcards` | `quantity`: `fewer`, `standard` *(default)*, `more`<br>`difficulty`: `easy`, `medium` *(default)*, `hard` | Yes | Yes | | `mindmap` | — | Yes | Yes | > **https://api.useapi.net/v1/gemini-notebook/artifacts/generate** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body With the item's own description as the prompt: ```json { "artifact": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:e4ec67bd-4f7e-4e09-8f6d-e88e6fa53cf6", "mode": "async" } ``` With options: ```json { "artifact": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:5ac11006-86b7-43a8-91c9-72bc5ba1164f", "instructions": "A visual breakdown showing the three modules of the Apollo 11 spacecraft, the three crew members, and the key steps of the moon landing sequence. Keep it simple.", "orientation": "portrait", "detail": "concise", "style": "sketch_note", "mode": "async", "replyUrl": "https://your-domain.com/webhook", "replyRef": "apollo-infographic" } ``` - `artifact` is **required**, the suggested item's id from the report's `embedded` list. The id names its account and notebook, so no `email` is needed. - `instructions` is optional, the prompt for the item, up to 10,000 characters. Default: the item's `description`. - `language` is optional, the output language as a language code such as `en`, `es`, `pt_BR` or `zh_Hans`. Default: the language the report suggested the item in. - `orientation` is optional, `infographic` only. Supported values: `landscape` (default), `portrait`, `square`. - `detail` is optional, `infographic` only. Supported values: `concise`, `standard` (default), `detailed`. - `style` is optional, `infographic` only. Supported values: `auto` (default), `sketch_note`, `professional`, `bento_grid`, `editorial`, `instructional`, `bricks`, `clay`, `anime`, `kawaii`, `scientific`. - `format` is optional, `slides` only. Supported values: `detailed` (default), `presenter`. - `length` is optional, `slides` only. Supported values: `short`, `default` (default), `long`. - `quantity` is optional, `quiz` and `flashcards` only. Supported values: `fewer`, `standard` (default), `more`. - `difficulty` is optional, `quiz` and `flashcards` only. Supported values: `easy`, `medium` (default), `hard`. - `mode` is optional, `sync` (default, waits up to 90 seconds) or `async` (returns `201` at once). - `replyUrl` is optional, a public `http(s)` URL that receives one `POST` of the job record when the job completes or fails. See [GET /jobs/`jobid`](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid#model) for the record's shape. - `replyRef` is optional, your own reference echoed back in the job record, up to 1024 characters. ##### Responses **200** **200 OK** Sync mode, finished within 90 seconds. `result` has the same shape as on [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts#what-you-get-back) for the item's type. A suggested quiz generated with no options (long arrays shortened with `...`): ```json { "jobid": "job:95680290-a009-4d0e-8a0f-56c580d47336-user:12345-user@example.com-bot:gemini_notebook", "email": "user@example.com", "type": "quiz", "status": "completed", "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "artifact": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:e4ec67bd-4f7e-4e09-8f6d-e88e6fa53cf6", "created_at": "2026-10-15T05:07:29.911Z", "request": { "artifact": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:e4ec67bd-4f7e-4e09-8f6d-e88e6fa53cf6" }, "completed_at": "2026-10-15T05:08:19.169Z", "result": { "title": "Apollo Quiz", "content": { "quiz": [ { "question": "Who served as the Command Module Pilot for Apollo 11, staying in lunar orbit while his crewmates walked on the Moon?", "answerOptions": [ { "text": "Michael Collins", "isCorrect": true, "rationale": "He piloted Columbia in lunar orbit alone while Neil Armstrong and Buzz Aldrin descended to the surface in Eagle." }, { "text": "Jim Lovell", "isCorrect": false, "rationale": "He served as the backup commander for Apollo 11 and later commanded Apollo 13, rather than flying as Apollo 11's Command Module Pilot." }, "..." ], "hint": "Think of the astronaut who remained onboard the Command Module Columbia during the surface walk." }, "..." ], "topics": { "covered": ["Apollo 11 Crew and Spacecraft", "Apollo 13 Emergency and Recovery", "..."], "followUp": ["Lunar Orbit Rendezvous Strategy", "..."] } } } } ``` The infographic from the second request body above, as [GET /jobs/`jobid`](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid) returns it once completed: ```json { "jobid": "job:c923752d-5083-4a7a-a726-f84aa06005c5-user:12345-user@example.com-bot:gemini_notebook", "email": "user@example.com", "type": "infographic", "status": "completed", "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "artifact": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:5ac11006-86b7-43a8-91c9-72bc5ba1164f", "created_at": "2026-10-15T05:08:38.373Z", "request": { "artifact": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:5ac11006-86b7-43a8-91c9-72bc5ba1164f", "instructions": "A visual breakdown showing the three modules of the Apollo 11 spacecraft, the three crew members, and the key steps of the moon landing sequence. Keep it simple.", "orientation": "portrait", "detail": "concise", "style": "sketch_note" }, "completed_at": "2026-10-15T05:10:02.328Z", "replyUrl": "https://your-domain.com/webhook", "replyRef": "apollo-infographic", "result": { "title": "Apollo 11 Moon Landing Anatomy", "files": [ { "format": "png", "mimeType": "image/png", "url": "https://api.useapi.net/v1/gemini-notebook/artifacts/download?artifact=user%3A12345-user%40example.com-artifact%3Ad02c903b-17f8-4241-a263-2be9e7359d55%3A5ac11006-86b7-43a8-91c9-72bc5ba1164f&format=png", "width": 1536, "height": 2752 } ], "text": "APOLLO 11: ANATOMY OF THE MOON LANDING\n\n\nSPACECRAFT MODULES\n\n- Command Module Columbia (crew cabin)\n- Service Module (propulsion/power)\n- Lunar Module Eagle (moon lander)\n..." } } ``` **201** **201 Created** Async mode. Poll [GET /jobs/`jobid`](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid) until `status` is `completed` or `failed`. ```json { "jobid": "job:95680290-a009-4d0e-8a0f-56c580d47336-user:12345-user@example.com-bot:gemini_notebook", "email": "user@example.com", "type": "quiz", "status": "processing", "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "artifact": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:e4ec67bd-4f7e-4e09-8f6d-e88e6fa53cf6", "created_at": "2026-10-15T05:07:29.911Z", "request": { "artifact": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:e4ec67bd-4f7e-4e09-8f6d-e88e6fa53cf6" } } ``` **202** **202 Accepted** Sync mode, still running after 90 seconds. The body is the running job record, as in the `201` tab. Poll [GET /jobs/`jobid`](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid) for the result. **400** **400 Bad Request** A missing or invalid parameter, or an option that does not fit the item's type. ```json { "error": "Parameter format does not apply to type quiz", "code": 400 } ``` ```json { "error": "Parameter orientation (tall) valid values for infographic: landscape, portrait, square", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The artifact id belongs to a different API token. ```json { "error": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:e4ec67bd-4f7e-4e09-8f6d-e88e6fa53cf6 does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** The item is no longer in its notebook (for example it was dismissed), or the account it names is not configured. ```json { "error": "Artifact user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:e4ec67bd-4f7e-4e09-8f6d-e88e6fa53cf6 not found", "code": 404 } ``` **409** **409 Conflict** The artifact is not a suggested item, or it was already generated. ```json { "error": "Only an interactive report's suggested item can be generated (this interactive_report is completed)", "code": 409 } ``` **422** **422 Unprocessable Content** Sync mode, Google reported the generation as failed. The body is the failed job record with `error.code: "generation_failed"`. Re-run it with [POST /artifacts/retry](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts-retry). **429** **429 Too Many Requests** The account already runs `maxJobs` jobs: ```json { "error": "Account user@example.com is busy: 3/3 jobs running (maxJobs)", "code": 429 } ``` Or Google refused the job because not enough of its usage window is left, before any job was created. `retryAt` is when the window resets and `window` is `5h` or `weekly`, both present only when Google's refusal names the window. See [GET /accounts/`email`](/docs/api-gemini-notebook-v1/get-gemini-notebook-accounts-email): ```json { "error": "Not enough of Google's 5h window is left on account user@example.com for this job; it resets at 2026-10-15T09:29:23.000Z. GET /accounts/user@example.com shows what each job needs", "code": 429, "retryAt": "2026-10-15T09:29:23.000Z", "window": "5h" } ``` **503** **503 Service Unavailable** A temporary condition, retry in a few minutes. ```json { "error": "Async mode is unavailable right now, use mode sync", "code": 503 } ``` The job could not be added to our job schedule. It is failed at once with `error.code: "scheduler"`. Google may already have started the generation, since only a one-shot request creates the artifact inside the job. Check [GET /artifacts](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts) before you submit it again. ```json { "error": "Unable to lock the job schedule of user 12345, please retry", "code": 503 } ``` ```json { "error": "Failed to create the job schedule (QStash HTTP 500): …", "code": 503 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` In sync mode, a job whose account is confirmed signed out while it runs answers `596` with the failed job record (`error.code: "account"`). ##### Model The job record, the same shape as [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts#model) returns. `request` echoes `artifact` and the options you sent, and `type` is the item's type. The full field list is on [GET /jobs/`jobid`](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid#model). <details markdown="block" class="model-details"> <summary>The job record, field by field</summary> ```typescript { // TypeScript, all fields are optional jobid: string // job:<uuid>-user:<id>-<email>-bot:gemini_notebook email: string // the account the job runs on type: 'audio' | 'video' | 'report' | 'interactive_report' | 'table' | 'quiz' | 'flashcards' | 'infographic' | 'slides' | 'mindmap' | 'research' status: 'pending' | 'processing' | 'completed' | 'failed' notebook: string // notebook id; for a one-shot, the notebook created for it artifact?: string // artifact id, once Google has created it (never on a research job) created_at: string // ISO 8601, when the job was accepted updated_at?: string // one-shot only: when its artifact was created completed_at?: string // ISO 8601, when the job completed or failed request: Record<string, unknown> // your request body echoed back (ids as strings), without mode, replyUrl and replyRef replyUrl?: string replyRef?: string warnings?: string[] // one-shot only: sources Google could not process and that were left out error?: { // status 'failed' code: 'quota' | 'account' | 'not_found' | 'sources' | 'generation_failed' | 'timeout' | 'google_error' | 'scheduler' | 'cancelled' message: string retryAt?: string // code 'quota', when Google names the window: ISO 8601 time it resets } result?: { // status 'completed', a Studio artifact title: string duration?: number // audio, video: seconds files?: Array<{ // audio, video, infographic, slides format: 'm4a' | 'mp4' | 'png' | 'pdf' | 'pptx' mimeType: string url: string // GET /artifacts/download link, needs your API token width?: number // infographic height?: number }> slides?: Array<{ // slides image: string // GET /artifacts/download link (format=slide&index=N) caption: string | null text: string | null }> text?: string // report (Markdown), interactive_report, infographic table?: string[][] // table: rows of cells, header row first content?: unknown // quiz, flashcards, mindmap: Google's JSON embedded?: Array<{ // interactive_report: the items it suggests, in reading order artifact: string // the item's id, for POST /artifacts/generate or DELETE /artifacts/{artifact} type: string // 'infographic', 'slides', 'mindmap', 'quiz' or 'flashcards' title: string description?: string status: string // 'suggested' until generated }> } | { // status 'completed', type 'research' (POST /research) mode: 'fast' | 'deep' query: string summary?: string // fast: Google's one-line summary of what it found report?: { // deep: the Deep Research report title: string markdown: string } noResults?: true // the run found nothing (sources is []) sources: Array<{ url: string title: string description: string | null cited: boolean // deep: the report cites it. fast: always true }> } } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/gemini-notebook/artifacts/generate" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "artifact": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:5ac11006-86b7-43a8-91c9-72bc5ba1164f", "orientation": "portrait", "style": "sketch_note", "mode": "async" }' ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = "https://api.useapi.net/v1/gemini-notebook"; const headers = { "Content-Type": "application/json", "Authorization": `Bearer ${token}` }; const report = "user:12345-user@example.com-artifact:..."; const { embedded = [] } = await (await fetch(`${apiUrl}/artifacts/${encodeURIComponent(report)}`, { headers })).json(); const item = embedded.find(x => x.status === "suggested" && x.type === "quiz"); const response = await fetch(`${apiUrl}/artifacts/generate`, { method: "POST", headers, body: JSON.stringify({ artifact: item.artifact, difficulty: "hard", mode: "async" }) }); const job = await response.json(); console.log("response", response.status, job); ``` **Python** ``` python import requests from urllib.parse import quote token = "API token" apiUrl = "https://api.useapi.net/v1/gemini-notebook" headers = {"Content-Type": "application/json", "Authorization": f"Bearer {token}"} report = "user:12345-user@example.com-artifact:..." embedded = requests.get(f"{apiUrl}/artifacts/{quote(report, safe='')}", headers=headers).json().get("embedded", []) item = next(x for x in embedded if x["status"] == "suggested" and x["type"] == "slides") response = requests.post( f"{apiUrl}/artifacts/generate", headers=headers, json={"artifact": item["artifact"], "length": "short", "mode": "async"} ) print(response.status_code, response.json()) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts-retry === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts-retry --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> artifacts/retry description: "Re-run a failed Studio artifact in place via POST artifacts/retry in the useapi.net Gemini Notebook API, tracked as a job you poll or receive by webhook." parent: Gemini Notebook API nav_order: 510 permalink: /docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts-retry --- ## Retry a failed artifact September 29, 2026 (November 16, 2026) --- Ask Google to run a failed Studio artifact again, in place in its notebook. The retry takes no generation options of its own. Use it when a job from [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts) ends with `error.code: "generation_failed"`, or when [GET /artifacts](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts) lists an artifact with `status: "failed"`. Only an artifact whose `status` is `failed` can be retried. Any other status returns `409`. The retry is a job, exactly like a new generation. It takes the artifact's own `type`, it counts toward the account's `maxJobs`, and Google can refuse it with `429` when its usage window is short. `mode`, `replyUrl` and `replyRef` behave as on [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts#sync-async-and-webhooks): sync waits up to 90 seconds, async returns `201` at once, and [GET /jobs/`jobid`](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid) returns the result. > **https://api.useapi.net/v1/gemini-notebook/artifacts/retry** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "artifact": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:0c2ba8dc-47dd-474f-a19c-c06896e269fd", "mode": "async", "replyUrl": "https://your-domain.com/webhook", "replyRef": "apollo-audio-retry" } ``` - `artifact` is **required**, the failed artifact's id, from the job's `artifact` field or from [GET /artifacts](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts). The id names its account and notebook, so no `email` is needed. - `mode` is optional, `sync` (default, waits up to 90 seconds) or `async` (returns `201` at once). - `replyUrl` is optional, a public `http(s)` URL that receives one `POST` of the job record when the job completes or fails. See [GET /jobs/`jobid`](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid#model) for the record's shape. - `replyRef` is optional, your own reference echoed back in the job record, up to 1024 characters. ##### Responses **200** **200 OK** Sync mode, finished within 90 seconds. `result` has the same shape as on [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts#what-you-get-back) for the artifact's type. ```json { "jobid": "job:6a0d2f4e-91c3-4b7a-8e25-3fd1c09b7a64-user:12345-user@example.com-bot:gemini_notebook", "email": "user@example.com", "type": "mindmap", "status": "completed", "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "artifact": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:3758acd1-12fe-45e3-badd-6b3996945b96", "created_at": "2026-09-27T23:40:02.646Z", "request": { "artifact": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:3758acd1-12fe-45e3-badd-6b3996945b96" }, "completed_at": "2026-09-27T23:40:35.803Z", "result": { "title": "Apollo Mindmap", "content": { "name": "Apollo 11 Mission", "children": [ { "name": "Background & Objectives", "children": [ { "name": "First Human Lunar Landing" }, { "name": "Kennedy's 1961 Goal" } ] }, ... ] } } } ``` **201** **201 Created** Async mode. Poll [GET /jobs/`jobid`](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid) until `status` is `completed` or `failed`. ```json { "jobid": "job:b84e1c07-2d6f-4f3a-9c51-e07a4d2b9f18-user:12345-user@example.com-bot:gemini_notebook", "email": "user@example.com", "type": "audio", "status": "pending", "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "artifact": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:0c2ba8dc-47dd-474f-a19c-c06896e269fd", "created_at": "2026-09-28T01:12:44.180Z", "request": { "artifact": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:0c2ba8dc-47dd-474f-a19c-c06896e269fd" }, "replyUrl": "https://your-domain.com/webhook", "replyRef": "apollo-audio-retry" } ``` **202** **202 Accepted** Sync mode, still running after 90 seconds. The body is the running job record, as in the `201` tab. Poll [GET /jobs/`jobid`](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid) for the result. **400** **400 Bad Request** ```json { "error": "Parameter artifact is not a valid artifact id", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The artifact id belongs to a different API token. ```json { "error": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:0c2ba8dc-47dd-474f-a19c-c06896e269fd does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** The artifact is no longer in its notebook, or the account it names is not configured. ```json { "error": "Artifact user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:0c2ba8dc-47dd-474f-a19c-c06896e269fd not found", "code": 404 } ``` **409** **409 Conflict** The artifact has not failed. ```json { "error": "Only a failed artifact can be retried (this one is completed)", "code": 409 } ``` **422** **422 Unprocessable Content** Sync mode, Google reported the generation as failed again. The body is the failed job record with `error.code: "generation_failed"`. **429** **429 Too Many Requests** The account already runs `maxJobs` jobs: ```json { "error": "Account user@example.com is busy: 3/3 jobs running (maxJobs)", "code": 429 } ``` Or Google refused the job because not enough of its usage window is left, before any job was created. `retryAt` is when the window resets and `window` is `5h` or `weekly`, both present only when Google's refusal names the window. See [GET /accounts/`email`](/docs/api-gemini-notebook-v1/get-gemini-notebook-accounts-email): ```json { "error": "Not enough of Google's 5h window is left on account user@example.com for this job; it resets at 2026-09-28T04:25:40.000Z. GET /accounts/user@example.com shows what each job needs", "code": 429, "retryAt": "2026-09-28T04:25:40.000Z", "window": "5h" } ``` **503** **503 Service Unavailable** A temporary condition, retry in a few minutes. ```json { "error": "Async mode is unavailable right now, use mode sync", "code": 503 } ``` The job could not be added to our job schedule. It is failed at once with `error.code: "scheduler"`. Google may already have started the generation, since only a one-shot request creates the artifact inside the job. Check [GET /artifacts](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts) before you submit it again. ```json { "error": "Unable to lock the job schedule of user 12345, please retry", "code": 503 } ``` ```json { "error": "Failed to create the job schedule (QStash HTTP 500): …", "code": 503 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` In sync mode, a job whose account is confirmed signed out while it runs answers `596` with the failed job record (`error.code: "account"`). ##### Model The job record, the same shape as [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts#model) returns. `request` echoes `artifact`, and `type` is the retried artifact's type. The full field list is on [GET /jobs/`jobid`](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid#model). <details markdown="block" class="model-details"> <summary>The job record, field by field</summary> ```typescript { // TypeScript, all fields are optional jobid: string // job:<uuid>-user:<id>-<email>-bot:gemini_notebook email: string // the account the job runs on type: 'audio' | 'video' | 'report' | 'interactive_report' | 'table' | 'quiz' | 'flashcards' | 'infographic' | 'slides' | 'mindmap' | 'research' status: 'pending' | 'processing' | 'completed' | 'failed' notebook: string // notebook id; for a one-shot, the notebook created for it artifact?: string // artifact id, once Google has created it (never on a research job) created_at: string // ISO 8601, when the job was accepted updated_at?: string // one-shot only: when its artifact was created completed_at?: string // ISO 8601, when the job completed or failed request: Record<string, unknown> // your request body echoed back (ids as strings), without mode, replyUrl and replyRef replyUrl?: string replyRef?: string warnings?: string[] // one-shot only: sources Google could not process and that were left out error?: { // status 'failed' code: 'quota' | 'account' | 'not_found' | 'sources' | 'generation_failed' | 'timeout' | 'google_error' | 'scheduler' | 'cancelled' message: string retryAt?: string // code 'quota', when Google names the window: ISO 8601 time it resets } result?: { // status 'completed', a Studio artifact title: string duration?: number // audio, video: seconds files?: Array<{ // audio, video, infographic, slides format: 'm4a' | 'mp4' | 'png' | 'pdf' | 'pptx' mimeType: string url: string // GET /artifacts/download link, needs your API token width?: number // infographic height?: number }> slides?: Array<{ // slides image: string // GET /artifacts/download link (format=slide&index=N) caption: string | null text: string | null }> text?: string // report (Markdown), interactive_report, infographic table?: string[][] // table: rows of cells, header row first content?: unknown // quiz, flashcards, mindmap: Google's JSON embedded?: Array<{ // interactive_report: the items it suggests, in reading order artifact: string // the item's id, for POST /artifacts/generate or DELETE /artifacts/{artifact} type: string // 'infographic', 'slides', 'mindmap', 'quiz' or 'flashcards' title: string description?: string status: string // 'suggested' until generated }> } | { // status 'completed', type 'research' (POST /research) mode: 'fast' | 'deep' query: string summary?: string // fast: Google's one-line summary of what it found report?: { // deep: the Deep Research report title: string markdown: string } noResults?: true // the run found nothing (sources is []) sources: Array<{ url: string title: string description: string | null cited: boolean // deep: the report cites it. fast: always true }> } } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/gemini-notebook/artifacts/retry" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "artifact": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:0c2ba8dc-47dd-474f-a19c-c06896e269fd", "mode": "async" }' ``` **JavaScript** ``` javascript const token = "API token"; const artifact = "user:12345-user@example.com-artifact:..."; const response = await fetch("https://api.useapi.net/v1/gemini-notebook/artifacts/retry", { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}` }, body: JSON.stringify({ artifact, mode: "async" }) }); const job = await response.json(); console.log("response", response.status, job); ``` **Python** ``` python import requests token = "API token" artifact = "user:12345-user@example.com-artifact:..." response = requests.post( "https://api.useapi.net/v1/gemini-notebook/artifacts/retry", headers={"Content-Type": "application/json", "Authorization": f"Bearer {token}"}, json={"artifact": artifact, "mode": "async"} ) print(response.status_code, response.json()) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts-revise === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts-revise --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> artifacts/revise description: "Rewrite one slide of a finished deck from a prompt via POST artifacts/revise in the useapi.net Gemini Notebook API, returned as a new revised deck." parent: Gemini Notebook API nav_order: 520 permalink: /docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts-revise --- ## Revise a slide September 29, 2026 (November 16, 2026) --- Change one slide of a completed slide deck by describing what you want, for example *"Make this slide a simple timeline graphic."* The deck must be a `slides` artifact from [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts) whose `status` is `completed`. Google produces the revised deck as a new artifact with its own id, and in our tests its title gained a ` (2)` suffix. The job's `artifact` field names the new deck, and its `result` carries the full set of files (`pdf`, `pptx`) and every slide image, exactly like a new slide deck. In our tests a revision took about 160 seconds, so in sync mode expect a `202` and keep polling. The revision is a job. It counts toward the account's `maxJobs`, and Google can refuse it with `429` when its usage window is short. `mode`, `replyUrl` and `replyRef` behave as on [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts#sync-async-and-webhooks). > **https://api.useapi.net/v1/gemini-notebook/artifacts/revise** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "artifact": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:ae28f2a1-678b-4304-9806-09648fcb77a0", "slide": 2, "prompt": "Make this slide a simple timeline graphic.", "mode": "async" } ``` - `artifact` is **required**, the id of a completed slide deck, from its job's `artifact` field or from [GET /artifacts](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts). The id names its account and notebook, so no `email` is needed. - `slide` is **required**, the slide to change, counted from `1`. It must not exceed the deck's slide count, which is the length of `result.slides` in the deck's job or in [GET /artifacts/`artifact`](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts-artifact). Range: `1` to `500`. - `prompt` is **required**, what to change on that slide, 1 to 2,000 characters. - `mode` is optional, `sync` (default, waits up to 90 seconds) or `async` (returns `201` at once). - `replyUrl` is optional, a public `http(s)` URL that receives one `POST` of the job record when the job completes or fails. See [GET /jobs/`jobid`](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid#model) for the record's shape. - `replyRef` is optional, your own reference echoed back in the job record, up to 1024 characters. ##### Responses **200** **200 OK** The completed job, as returned by sync mode or later by [GET /jobs/`jobid`](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid). `artifact` is the new, revised deck. `request.artifact` is the deck you revised. ```json { "jobid": "job:7ec0b9b1-4a8b-4f27-9dfe-5761bc2acb18-user:12345-user@example.com-bot:gemini_notebook", "email": "user@example.com", "type": "slides", "status": "completed", "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "artifact": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:7f9b45c6-ebed-4e12-8542-0f28955d9b81", "created_at": "2026-09-28T00:05:09.001Z", "request": { "artifact": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:ae28f2a1-678b-4304-9806-09648fcb77a0", "slide": 2, "prompt": "Make this slide a simple timeline graphic." }, "completed_at": "2026-09-28T00:07:52.421Z", "result": { "title": "Apollo 11 Flight Plan (2)", "files": [ { "format": "pdf", "mimeType": "application/pdf", "url": "https://api.useapi.net/v1/gemini-notebook/artifacts/download?artifact=user%3A12345-user%40example.com-artifact%3Ad02c903b-17f8-4241-a263-2be9e7359d55%3A7f9b45c6-ebed-4e12-8542-0f28955d9b81&format=pdf" }, { "format": "pptx", "mimeType": "application/vnd.openxmlformats-officedocument.presentationml.presentation", "url": "https://api.useapi.net/v1/gemini-notebook/artifacts/download?artifact=user%3A12345-user%40example.com-artifact%3Ad02c903b-17f8-4241-a263-2be9e7359d55%3A7f9b45c6-ebed-4e12-8542-0f28955d9b81&format=pptx" } ], "slides": [ { "image": "https://api.useapi.net/v1/gemini-notebook/artifacts/download?artifact=user%3A12345-user%40example.com-artifact%3Ad02c903b-17f8-4241-a263-2be9e7359d55%3A7f9b45c6-ebed-4e12-8542-0f28955d9b81&format=slide&index=1", "caption": "Title slide for Apollo 11: Anatomy of a Miracle, featuring an astronaut on the lunar surface.", "text": "APOLLO_11: ANATOMY OF A MIRACLE\n\nJULY 16-24, 1969 | CREWED LUNAR LANDING\n..." }, { "image": "https://api.useapi.net/v1/gemini-notebook/artifacts/download?artifact=user%3A12345-user%40example.com-artifact%3Ad02c903b-17f8-4241-a263-2be9e7359d55%3A7f9b45c6-ebed-4e12-8542-0f28955d9b81&format=slide&index=2", "caption": "A timeline comparing early Soviet space achievements with a US milestone under a famous JFK quote about going to the moon.", "text": "WE CHOOSE TO GO TO THE MOON IN THIS DECADE...\n\n[Horizontal timeline chart on a dark grid background tracking early space race milestones]\n..." }, ... ] } } ``` **201** **201 Created** Async mode. Poll [GET /jobs/`jobid`](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid) until `status` is `completed` or `failed`. ```json { "jobid": "job:7ec0b9b1-4a8b-4f27-9dfe-5761bc2acb18-user:12345-user@example.com-bot:gemini_notebook", "email": "user@example.com", "type": "slides", "status": "pending", "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "artifact": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:7f9b45c6-ebed-4e12-8542-0f28955d9b81", "created_at": "2026-09-28T00:05:09.001Z", "request": { "artifact": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:ae28f2a1-678b-4304-9806-09648fcb77a0", "slide": 2, "prompt": "Make this slide a simple timeline graphic." } } ``` **202** **202 Accepted** Sync mode, still running after 90 seconds. The body is the running job record, as in the `201` tab. Poll [GET /jobs/`jobid`](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid) for the result. **400** **400 Bad Request** A missing or invalid parameter, or a `slide` number beyond the deck's last slide. ```json { "error": "slide must be 1..12", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The artifact id belongs to a different API token. ```json { "error": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:ae28f2a1-678b-4304-9806-09648fcb77a0 does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** The deck is no longer in its notebook, or the account it names is not configured. ```json { "error": "Artifact user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:ae28f2a1-678b-4304-9806-09648fcb77a0 not found", "code": 404 } ``` **409** **409 Conflict** The artifact is not a slide deck, or it has not completed. ```json { "error": "Only a completed slide deck can be revised", "code": 409 } ``` **422** **422 Unprocessable Content** Sync mode, Google reported the revised deck as failed. The body is the failed job record with `error.code: "generation_failed"`. The failed deck can be re-run with [POST /artifacts/retry](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts-retry). **429** **429 Too Many Requests** The account already runs `maxJobs` jobs: ```json { "error": "Account user@example.com is busy: 3/3 jobs running (maxJobs)", "code": 429 } ``` Or Google refused the job because not enough of its usage window is left, before any job was created. `retryAt` is when the window resets and `window` is `5h` or `weekly`, both present only when Google's refusal names the window. See [GET /accounts/`email`](/docs/api-gemini-notebook-v1/get-gemini-notebook-accounts-email): ```json { "error": "Not enough of Google's 5h window is left on account user@example.com for this job; it resets at 2026-09-28T04:25:40.000Z. GET /accounts/user@example.com shows what each job needs", "code": 429, "retryAt": "2026-09-28T04:25:40.000Z", "window": "5h" } ``` **502** **502 Bad Gateway** Google accepted the revision but did not return the new deck, so there is no job to track. Look for it in [GET /artifacts](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts). ```json { "error": "Google accepted the revision but returned no artifact to track; check GET /artifacts?notebook=", "code": 502 } ``` **503** **503 Service Unavailable** A temporary condition, retry in a few minutes. ```json { "error": "Async mode is unavailable right now, use mode sync", "code": 503 } ``` The job could not be added to our job schedule. It is failed at once with `error.code: "scheduler"`. Google may already have started the generation, since only a one-shot request creates the artifact inside the job. Check [GET /artifacts](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts) before you submit it again. ```json { "error": "Unable to lock the job schedule of user 12345, please retry", "code": 503 } ``` ```json { "error": "Failed to create the job schedule (QStash HTTP 500): …", "code": 503 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` In sync mode, a job whose account is confirmed signed out while it runs answers `596` with the failed job record (`error.code: "account"`). ##### Model The job record, the same shape as [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts#model) returns for `slides`. Here `artifact` is the new, revised deck, and `request` echoes `artifact` (the deck you revised), `slide` and `prompt`. The full field list is on [GET /jobs/`jobid`](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid#model). <details markdown="block" class="model-details"> <summary>The job record, field by field</summary> ```typescript { // TypeScript, all fields are optional jobid: string // job:<uuid>-user:<id>-<email>-bot:gemini_notebook email: string // the account the job runs on type: 'audio' | 'video' | 'report' | 'interactive_report' | 'table' | 'quiz' | 'flashcards' | 'infographic' | 'slides' | 'mindmap' | 'research' status: 'pending' | 'processing' | 'completed' | 'failed' notebook: string // notebook id; for a one-shot, the notebook created for it artifact?: string // artifact id, once Google has created it (never on a research job) created_at: string // ISO 8601, when the job was accepted updated_at?: string // one-shot only: when its artifact was created completed_at?: string // ISO 8601, when the job completed or failed request: Record<string, unknown> // your request body echoed back (ids as strings), without mode, replyUrl and replyRef replyUrl?: string replyRef?: string warnings?: string[] // one-shot only: sources Google could not process and that were left out error?: { // status 'failed' code: 'quota' | 'account' | 'not_found' | 'sources' | 'generation_failed' | 'timeout' | 'google_error' | 'scheduler' | 'cancelled' message: string retryAt?: string // code 'quota', when Google names the window: ISO 8601 time it resets } result?: { // status 'completed', a Studio artifact title: string duration?: number // audio, video: seconds files?: Array<{ // audio, video, infographic, slides format: 'm4a' | 'mp4' | 'png' | 'pdf' | 'pptx' mimeType: string url: string // GET /artifacts/download link, needs your API token width?: number // infographic height?: number }> slides?: Array<{ // slides image: string // GET /artifacts/download link (format=slide&index=N) caption: string | null text: string | null }> text?: string // report (Markdown), interactive_report, infographic table?: string[][] // table: rows of cells, header row first content?: unknown // quiz, flashcards, mindmap: Google's JSON embedded?: Array<{ // interactive_report: the items it suggests, in reading order artifact: string // the item's id, for POST /artifacts/generate or DELETE /artifacts/{artifact} type: string // 'infographic', 'slides', 'mindmap', 'quiz' or 'flashcards' title: string description?: string status: string // 'suggested' until generated }> } | { // status 'completed', type 'research' (POST /research) mode: 'fast' | 'deep' query: string summary?: string // fast: Google's one-line summary of what it found report?: { // deep: the Deep Research report title: string markdown: string } noResults?: true // the run found nothing (sources is []) sources: Array<{ url: string title: string description: string | null cited: boolean // deep: the report cites it. fast: always true }> } } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/gemini-notebook/artifacts/revise" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "artifact": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:ae28f2a1-678b-4304-9806-09648fcb77a0", "slide": 2, "prompt": "Make this slide a simple timeline graphic.", "mode": "async" }' ``` **JavaScript** ``` javascript const token = "API token"; const artifact = "user:12345-user@example.com-artifact:..."; const response = await fetch("https://api.useapi.net/v1/gemini-notebook/artifacts/revise", { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}` }, body: JSON.stringify({ artifact, slide: 2, prompt: "Make this slide a simple timeline graphic.", mode: "async" }) }); const job = await response.json(); console.log("response", response.status, job); ``` **Python** ``` python import requests token = "API token" artifact = "user:12345-user@example.com-artifact:..." response = requests.post( "https://api.useapi.net/v1/gemini-notebook/artifacts/revise", headers={"Content-Type": "application/json", "Authorization": f"Bearer {token}"}, json={ "artifact": artifact, "slide": 2, "prompt": "Make this slide a simple timeline graphic.", "mode": "async" } ) print(response.status_code, response.json()) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> artifacts description: "Generate audio and video overviews, slides, reports, quizzes and mind maps via POST artifacts in the useapi.net Gemini Notebook API, from a notebook or from URLs." parent: Gemini Notebook API nav_order: 500 permalink: /docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts --- ## Generate a Studio artifact September 29, 2026 (November 16, 2026) --- Generate any Gemini Notebook Studio artifact from a notebook's sources: an audio overview, a video overview, a slide deck, a report, an interactive report, a data table, a quiz, flashcards, an infographic or a mind map. Every generation runs as a job. Poll it with [GET /jobs/`jobid`](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid), or pass `replyUrl` to receive the finished record by webhook. There are two ways to call it: - On a notebook — pass the `notebook` id from [POST /notebooks](/docs/api-gemini-notebook-v1/post-gemini-notebook-notebooks). Its sources must be added first with [POST /sources](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources) or [POST /sources/upload](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources-upload). - One-shot — pass `urls` and/or `text` instead of `notebook`. The API creates a notebook for you on one of your accounts, adds the sources, waits for them to be ready and starts the generation. See [One-shot requests](#one-shot-requests). Text results (reports, tables, quiz and flashcard JSON, mind maps) come back inside the job record. Media files (`m4a`, `mp4`, `pdf`, `pptx`, `png` and each slide image) are streamed from Google through [GET /artifacts/download](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts-download), and the job result links to it. Those links need your API token, just like every other call. A finished artifact also stays in its notebook, where [GET /artifacts](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts) lists it and [GET /artifacts/`artifact`](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts-artifact) returns it again at any time. A completed `interactive_report` also lists `embedded` items in reading order: infographics, slide decks, mind maps, quizzes and flashcards that Google suggests for the report, each with a `title`, a `description` and `status: "suggested"`. They are not generated yet. Generate one with [POST /artifacts/generate](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts-generate), or dismiss it with [DELETE /artifacts/`artifact`](/docs/api-gemini-notebook-v1/delete-gemini-notebook-artifacts-artifact). `instructions` shape the whole report, including the items it suggests. A one-shot request with `deleteNotebook: true` deletes the items along with the notebook, so they can no longer be generated. ### Options by type Each type accepts only the options in its row. Passing any other option returns `400 Parameter <name> does not apply to type <type>`, and a value outside the listed set returns `400` with the valid values. Omitted options use the default shown. | `type` | `format` | `length` | `style` | Other options | `language` | `instructions` | |---|:-:|:-:|:-:|---|:--:|:--:| | `audio` | `deep_dive` *(default)*<br>`brief`<br>`critique`<br>`debate` | `short`<br>`default` *(default)*<br>`long` | No | — | Yes | Yes | | `video` | `explainer` *(default)*<br>`brief`<br>`cinematic`<br>`short` | No | `auto` *(default)*<br>`classic`<br>`whiteboard`<br>`heritage`<br>`paper_craft`<br>`watercolor`<br>`anime`<br>`retro_print`<br>`kawaii`<br>`custom` | `stylePrompt`<br>*(with style `custom` only)* | Yes <br>*(not cinematic)* | Yes <br>*(not cinematic)* | | `report` | `briefing` *(default)*<br>`study_guide`<br>`blog_post`<br>`custom` | No | No | — | Yes | Yes <br>*(required with `custom`)* | | `interactive_report` | No | No | No | — | Yes | Yes | | `table` | No | No | No | — | Yes | Yes | | `quiz` | No | No | No | `quantity`: `fewer`, `standard` *(default)*, `more`<br>`difficulty`: `easy`, `medium` *(default)*, `hard` | No | Yes | | `flashcards` | No | No | No | `quantity`: `fewer`, `standard` *(default)*, `more`<br>`difficulty`: `easy`, `medium` *(default)*, `hard` | No | Yes | | `infographic` | No | No | `auto` *(default)*<br>`sketch_note`<br>`professional`<br>`bento_grid`<br>`editorial`<br>`instructional`<br>`bricks`<br>`clay`<br>`anime`<br>`kawaii`<br>`scientific` | `orientation`: `landscape` *(default)*, `portrait`, `square`<br>`detail`: `concise`, `standard` *(default)*, `detailed` | Yes | Yes | | `slides` | `detailed` *(default)*<br>`presenter` | `short`<br>`default` *(default)*<br>`long` | No | — | Yes | Yes | | `mindmap` | No | No | No | — | No | Yes | Video rules: - `cinematic` takes no `style`, `stylePrompt`, `instructions` or `language`. - `short` has a fixed style, so it takes no `style` or `stylePrompt`. It does take `language` and `instructions`. - `stylePrompt` is required with `style: "custom"` and rejected with any other style. ### What you get back The job's `result` carries the artifact `title` plus the fields below. The typical times were measured on a Google AI Pro account with three jobs running at once (September 2026). Google's own cost estimate, as a percentage of the 5-hour usage window, is shown for the Free, Pro and Ultra plans. Both change over time, so read the live estimates from [GET /accounts/`email`](/docs/api-gemini-notebook-v1/get-gemini-notebook-accounts-email). | `type` | `result` fields | Download formats | Typical time | Estimate, Free / Pro / Ultra | |---|---|---|---|---| | `` | | | | % *()* / % / %no separate estimate | Google refuses a job once its estimate is larger than what is left of the usage window, even before the window is full. While a job runs, Google holds its full estimate against the window, then settles to the actual cost, which is often much lower. How a refusal comes back depends on the request (see the `429` tab under [Responses](#responses)): - On a notebook, Google refuses before the job exists. The call answers `429` with `error`, `retryAt` and `window` at the top level. [POST /artifacts/retry](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts-retry) and [POST /artifacts/revise](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts-revise) answer the same way. - One-shot, the generation starts inside the job, once its sources are ready. The job fails with `error.code: "quota"` and `error.retryAt`, without `window`. In sync mode, when this happens within the 90-second wait, the call answers `429` with that failed job record. In async mode the call has already answered `201`, and [GET /jobs/`jobid`](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid) shows the failure. `retryAt` and `window` are present only when Google's refusal names the window. ### Sync, async and webhooks - `mode: "sync"` (the default) waits up to 90 seconds for the result. A job that finishes in time returns `200` with its `result`. A job still running at 90 seconds returns `202` with the job record, and you keep polling [GET /jobs/`jobid`](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid). If your connection drops during the wait, the job carries on and can still be polled. - `mode: "async"` returns `201` with the job record at once. - The API advances running jobs every ~15 seconds. A job still running after 40 minutes is failed with `error.code: "timeout"`. Google may still finish the artifact later, and it then shows up in [GET /artifacts](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts). - `replyUrl` receives one `POST` of the final job record when the job completes or fails. Each account runs at most `maxJobs` jobs at a time (default `3`, range `1` to `10`, set with [POST /accounts](/docs/api-gemini-notebook-v1/post-gemini-notebook-accounts)). [GET /jobs](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs) shows what is running on each account. [DELETE /jobs/`jobid`](/docs/api-gemini-notebook-v1/delete-gemini-notebook-jobs-jobid) frees a slot at once, although Google may still finish the artifact in the notebook. ### One-shot requests Leave out `notebook` and pass `urls` and/or `text`. The API then: 1. Picks one of your accounts that is healthy, has a free `maxJobs` slot and whose last known usage does not block this type, or uses the account named by `email`. 2. Creates a notebook titled `title` (default `useapi <type>`) and adds the sources, with YouTube links added as YouTube sources. 3. Waits up to 5 minutes for the sources to be ready, then starts the generation. Sources Google could not process are left out and listed in the job's `warnings`. The job's `notebook` field names the new notebook, so you can reuse it for more artifacts or [chat](/docs/api-gemini-notebook-v1/post-gemini-notebook-chat). Set `deleteNotebook: true` to have it deleted once the job finishes. That is allowed only for the text-only types (`report`, `interactive_report`, `table`, `quiz`, `flashcards`, `mindmap`), because media files are streamed from their notebook and would go with it. A one-shot notebook is also deleted when the job fails before Google created the artifact, since it holds nothing you can use. > **https://api.useapi.net/v1/gemini-notebook/artifacts** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body On a notebook: ```json { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "type": "audio", "format": "debate", "length": "short", "language": "es", "instructions": "Focus on the risks the crew took during the landing.", "mode": "async", "replyUrl": "https://your-domain.com/webhook", "replyRef": "apollo-debate-1" } ``` One-shot: ```json { "type": "quiz", "urls": ["https://en.wikipedia.org/wiki/Apollo_11"], "title": "Apollo 11 quiz", "quantity": "more", "difficulty": "hard", "deleteNotebook": true } ``` - `type` is **required**, the Studio artifact to generate. Supported values: `audio`, `video`, `report`, `interactive_report`, `table`, `quiz`, `flashcards`, `infographic`, `slides`, `mindmap`. - `notebook` is optional, the notebook id from [POST /notebooks](/docs/api-gemini-notebook-v1/post-gemini-notebook-notebooks) or [GET /notebooks](/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks). The id names its account, so the job runs there. Omit it for a one-shot request. - `sources` is optional, with `notebook` only. An array of `1` to `300` source ids from that notebook to generate from. Default: every source in the notebook whose `status` is `ready`. The call returns `409` if the notebook has no sources, or none are ready yet. - `urls` is optional, one-shot only. An array of `1` to `50` `http(s)` URLs. Links on `youtube.com` or `youtu.be` are added as YouTube sources, anything else as a web page. - `text` is optional, one-shot only. Pasted text added as one source, up to 500,000 characters. A one-shot request needs `urls`, `text`, or both. - `title` is optional, one-shot only. The new notebook's title, also used as the pasted text source's title. Up to 200 characters. Default: `useapi <type>` for the notebook, `Pasted text` for the text source. - `email` is optional, one-shot only. The [account](/docs/api-gemini-notebook-v1/get-gemini-notebook-accounts) to run on. When omitted, the API picks a healthy account with a free slot whose usage allows this type. - `deleteNotebook` is optional, one-shot only. `true` deletes the one-shot notebook once the job completes or fails. Only for `report`, `interactive_report`, `table`, `quiz`, `flashcards` and `mindmap`. Default: `false`. - `format` is optional, see [Options by type](#options-by-type). `audio`: `deep_dive` (default), `brief`, `critique`, `debate`. `video`: `explainer` (default), `brief`, `cinematic`, `short`. `report`: `briefing` (default), `study_guide`, `blog_post`, `custom`. The first three use Google's own preset prompts, and any `instructions` you send are added after the preset's prompt. `custom` uses your `instructions` as the whole prompt. `slides`: `detailed` (default), `presenter`. - `length` is optional. `audio`: `short`, `default` (default), `long`. `slides`: `short`, `default` (default), `long`. - `style` is optional. `video` (`explainer` and `brief` only): `auto` (default), `classic`, `whiteboard`, `heritage`, `paper_craft`, `watercolor`, `anime`, `retro_print`, `kawaii`, `custom`. `infographic`: `auto` (default), `sketch_note`, `professional`, `bento_grid`, `editorial`, `instructional`, `bricks`, `clay`, `anime`, `kawaii`, `scientific`. - `stylePrompt` is optional, `video` only. Describes your own visual style, up to 2,000 characters. Required with `style: "custom"`, and rejected otherwise. - `quantity` is optional, `quiz` and `flashcards` only. Supported values: `fewer`, `standard` (default), `more`. - `difficulty` is optional, `quiz` and `flashcards` only. Supported values: `easy`, `medium` (default), `hard`. - `orientation` is optional, `infographic` only. Supported values: `landscape` (default), `portrait`, `square`. - `detail` is optional, `infographic` only. Supported values: `concise`, `standard` (default), `detailed`. - `language` is optional, the output language as a language code such as `en`, `es`, `pt_BR` or `zh_Hans`. Accepted by `audio`, `video` (not `cinematic`), `report`, `interactive_report`, `table`, `infographic` and `slides`. Default: `en`. - `instructions` is optional, what to focus on or how to shape the result, up to 10,000 characters. Accepted by `audio`, `video` (not `cinematic`), `interactive_report`, `table`, `quiz`, `flashcards`, `infographic`, `slides` and `mindmap`. For `report` with `format: "custom"` it is the whole prompt and is required. With a preset report format it is added after the preset's own prompt. - `mode` is optional, `sync` (default) or `async`. See [Sync, async and webhooks](#sync-async-and-webhooks). - `replyUrl` is optional, a public `http(s)` URL that receives one `POST` of the job record when the job completes or fails. See [GET /jobs/`jobid`](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid#model) for the record's shape. - `replyRef` is optional, your own reference echoed back in the job record, up to 1024 characters. ##### Responses **200** **200 OK** Sync mode, finished within 90 seconds. The `result` shape depends on the type, see [What you get back](#what-you-get-back). ```json { "jobid": "job:0ff1aa90-5244-4900-9e7d-e0931ccce82e-user:12345-user@example.com-bot:gemini_notebook", "email": "user@example.com", "type": "infographic", "status": "completed", "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "artifact": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:9213e77e-9b71-4f84-8f71-1bd130138a01", "created_at": "2026-09-27T23:31:07.016Z", "request": { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "type": "infographic", "style": "sketch_note", "orientation": "portrait" }, "completed_at": "2026-09-27T23:32:42.962Z", "result": { "title": "Apollo 11 Moon Landing Infographic", "files": [ { "format": "png", "mimeType": "image/png", "url": "https://api.useapi.net/v1/gemini-notebook/artifacts/download?artifact=user%3A12345-user%40example.com-artifact%3Ad02c903b-17f8-4241-a263-2be9e7359d55%3A9213e77e-9b71-4f84-8f71-1bd130138a01&format=png", "width": 1536, "height": 2752 } ], "text": "APOLLO 11: ONE GIANT LEAP FOR MANKIND\n\n[An illustrated infographic detailing the key stages of the 1969 moon landing mission...]\n\nMISSION PARAMETERS AT A GLANCE\n\n- Spacecraft: CSM-107 Columbia / LM-5 Eagle\n..." } } ``` A one-shot quiz, with its JSON `content`: ```json { "jobid": "job:4855bb5a-6292-4419-9fb8-1d42b81e3a78-user:12345-user@example.com-bot:gemini_notebook", "email": "user@example.com", "type": "quiz", "status": "completed", "notebook": "user:12345-user@example.com-notebook:38790668-c173-4f95-9954-bb482739b582", "created_at": "2026-09-28T00:08:21.063Z", "request": { "type": "quiz", "urls": ["https://en.wikipedia.org/wiki/Apollo_11"], "title": "useapi one-shot", "deleteNotebook": true }, "updated_at": "2026-09-28T00:08:25.396Z", "artifact": "user:12345-user@example.com-artifact:38790668-c173-4f95-9954-bb482739b582:555b18c1-237c-4014-ae8f-b5b931d2bde7", "completed_at": "2026-09-28T00:09:29.141Z", "result": { "title": "Apollo Quiz", "content": { "quiz": [ { "question": "Why did President John F. Kennedy select a crewed lunar landing mission as the target for the United States in 1961...?", "answerOptions": [ { "text": "The Soviet Union had launch vehicles with higher lift capacity, so Kennedy chose a challenge requiring new rocket technology...", "rationale": "Selecting a goal beyond existing rocket capabilities ensured that the Soviet Union's existing advantage...", "isCorrect": true }, { "text": "The United States already possessed Saturn V rockets capable of deep space flight...", "rationale": "The Saturn V rocket was still in early development phases...", "isCorrect": false } ], "hint": "Consider how initial Soviet advantages in rocket payload capacity influenced American strategic goal setting." } ] } } } ``` **201** **201 Created** Async mode. The job is created and returned at once. Poll [GET /jobs/`jobid`](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid) until `status` is `completed` or `failed`. A one-shot job starts as `pending` without an `artifact`, which appears once Google has created it. ```json { "jobid": "job:12597f9a-010c-4758-8e9a-b5cc17b0ccdb-user:12345-user@example.com-bot:gemini_notebook", "email": "user@example.com", "type": "audio", "status": "processing", "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "artifact": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:0c2ba8dc-47dd-474f-a19c-c06896e269fd", "created_at": "2026-09-27T23:38:15.692Z", "request": { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "type": "audio", "format": "debate", "length": "short", "language": "es", "instructions": "Focus on the risks the crew took during the landing." }, "replyUrl": "https://your-domain.com/webhook", "replyRef": "apollo-debate-1" } ``` **202** **202 Accepted** Sync mode, still running after 90 seconds. Poll [GET /jobs/`jobid`](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid) for the result. The job record is the same as the `201` one. ```json { "jobid": "job:7e575d08-5298-4a75-bd51-03de14ff3e31-user:12345-user@example.com-bot:gemini_notebook", "email": "user@example.com", "type": "video", "status": "processing", "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "artifact": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:5da139a1-f97b-443e-9ef5-629a9e91dc37", "created_at": "2026-09-27T23:38:38.606Z", "request": { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "type": "video", "format": "brief", "style": "custom", "stylePrompt": "1960s newsreel, black and white" } } ``` **400** **400 Bad Request** A missing or invalid parameter, or an option that does not fit the type. ```json { "error": "Parameter style does not apply to type slides", "code": 400 } ``` ```json { "error": "deleteNotebook is only for report, interactive_report, table, quiz, flashcards, mindmap: a video's files are served from its notebook", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The `notebook` id belongs to a different API token, or Google does not allow this on the account's plan. ```json { "error": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55 does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** The notebook no longer exists at Google, or the account it names (or the `email` you passed) is not configured. ```json { "error": "Account user@example.com of user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55 is not configured", "code": 404 } ``` **409** **409 Conflict** The notebook has no sources, or none of them are ready yet. Check each source's `status` with [GET /notebooks/`notebook`](/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks-notebook). ```json { "error": "The notebook's sources are still processing, retry shortly", "code": 409 } ``` **422** **422 Unprocessable Content** Sync mode, the job failed within 90 seconds: Google reported the generation as failed (`generation_failed`), or no source of a one-shot request could be used (`sources`). A failed artifact can be re-run with [POST /artifacts/retry](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts-retry). ```json { "jobid": "job:3b1f6c2e-8d47-4a95-b0e2-7c9d51a4e8f3-user:12345-user@example.com-bot:gemini_notebook", "email": "user@example.com", "type": "quiz", "status": "failed", "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "artifact": "user:12345-user@example.com-artifact:d02c903b-17f8-4241-a263-2be9e7359d55:5e2a9c71-4b3d-4f08-9a6e-d18c73b2f045", "created_at": "2026-09-27T23:26:40.393Z", "request": { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "type": "quiz" }, "completed_at": "2026-09-27T23:27:25.114Z", "error": { "code": "generation_failed", "message": "Google reported the generation as failed. POST /artifacts/retry can re-run it in place" } } ``` **429** **429 Too Many Requests** Returned in four cases. The account already runs `maxJobs` jobs. Retry when one finishes, or raise `maxJobs` with [POST /accounts](/docs/api-gemini-notebook-v1/post-gemini-notebook-accounts): ```json { "error": "Account user@example.com is busy: 3/3 jobs running (maxJobs)", "code": 429 } ``` One-shot without `email`, and every account is busy, or blocked by its last known usage: ```json { "error": "All 2 accounts are at their maxJobs limit, retry shortly", "code": 429 } ``` ```json { "error": "Google's usage limit blocks audio on every available account, check GET /accounts/{email} for reset times", "code": 429 } ``` On a notebook, Google refused the job because not enough of its usage window is left. No job was created. `retryAt` is when the window resets and `window` is `5h` or `weekly`, both present only when Google's refusal names the window. [GET /accounts/`email`](/docs/api-gemini-notebook-v1/get-gemini-notebook-accounts-email) shows what is left and what each type needs: ```json { "error": "Not enough of Google's 5h window is left on account user@example.com for this job; it resets at 2026-09-28T04:25:40.000Z. GET /accounts/user@example.com shows what each job needs", "code": 429, "retryAt": "2026-09-28T04:25:40.000Z", "window": "5h" } ``` One-shot in sync mode, Google refused the generation once the job's sources were ready. The body is the failed job record, with `error.code: "quota"` and `error.retryAt` (no `window`). The one-shot notebook is deleted, since Google created no artifact in it. In async mode the call answers `201` instead, and the job fails the same way: ```json { "jobid": "job:9c4e2f1a-7b3d-4e85-a6c2-51d8f0b3e7a4-user:12345-user@example.com-bot:gemini_notebook", "email": "user@example.com", "type": "audio", "status": "failed", "notebook": "user:12345-user@example.com-notebook:6a1f3c9e-2d48-4b7a-9e05-c3f81d7a2b64", "created_at": "2026-09-28T01:12:04.518Z", "request": { "type": "audio", "urls": ["https://en.wikipedia.org/wiki/Apollo_11"] }, "completed_at": "2026-09-28T01:12:31.207Z", "error": { "code": "quota", "message": "Not enough of Google's 5h window is left on account user@example.com for this job; it resets at 2026-09-28T04:25:40.000Z. GET /accounts/user@example.com shows what each job needs", "retryAt": "2026-09-28T04:25:40.000Z" } } ``` **502** **502 Bad Gateway** Google answered with an unexpected error, or could not be reached. In sync mode a job that failed for such a reason also returns `502` with the failed job record. ```json { "error": "Could not reach Gemini Notebook (HTTP 500), please retry", "code": 502 } ``` **503** **503 Service Unavailable** A temporary condition, retry in a few minutes. ```json { "error": "GOOGLE_BOT_CHECK: Google is challenging our network right now, please retry in a few minutes", "code": 503 } ``` ```json { "error": "Async mode is unavailable right now, use mode sync", "code": 503 } ``` The job could not be added to our job schedule. It is failed at once with `error.code: "scheduler"`. Google may already have started the generation, since only a one-shot request creates the artifact inside the job. Check [GET /artifacts](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts) before you submit it again. ```json { "error": "Unable to lock the job schedule of user 12345, please retry", "code": 503 } ``` ```json { "error": "Failed to create the job schedule (QStash HTTP 500): …", "code": 503 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` In sync mode, a job whose account is confirmed signed out while it runs answers `596` with the failed job record (`error.code: "account"`). A one-shot request without `email` returns `596` when none of your accounts is healthy: ```json { "error": "No healthy Gemini Notebook accounts available. Check GET /accounts", "code": 596 } ``` ##### Model The job record. [GET /jobs/`jobid`](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid) and the `replyUrl` webhook return the same shape. <details markdown="block" class="model-details"> <summary>The job record, field by field</summary> In sync mode a failed job answers with an HTTP status that matches `error.code`: `quota` → `429`, `account` → `596`, `not_found` → `404`, `sources` and `generation_failed` → `422`, `cancelled` → `409`, `timeout` → `504`, anything else → `502`. ```typescript { // TypeScript, all fields are optional jobid: string // job:<uuid>-user:<id>-<email>-bot:gemini_notebook email: string // the account the job runs on type: 'audio' | 'video' | 'report' | 'interactive_report' | 'table' | 'quiz' | 'flashcards' | 'infographic' | 'slides' | 'mindmap' | 'research' status: 'pending' | 'processing' | 'completed' | 'failed' notebook: string // notebook id; for a one-shot, the notebook created for it artifact?: string // artifact id, once Google has created it (never on a research job) created_at: string // ISO 8601, when the job was accepted updated_at?: string // one-shot only: when its artifact was created completed_at?: string // ISO 8601, when the job completed or failed request: Record<string, unknown> // your request body echoed back (ids as strings), without mode, replyUrl and replyRef replyUrl?: string replyRef?: string warnings?: string[] // one-shot only: sources Google could not process and that were left out error?: { // status 'failed' code: 'quota' | 'account' | 'not_found' | 'sources' | 'generation_failed' | 'timeout' | 'google_error' | 'scheduler' | 'cancelled' message: string retryAt?: string // code 'quota', when Google names the window: ISO 8601 time it resets } result?: { // status 'completed', a Studio artifact title: string duration?: number // audio, video: seconds files?: Array<{ // audio, video, infographic, slides format: 'm4a' | 'mp4' | 'png' | 'pdf' | 'pptx' mimeType: string url: string // GET /artifacts/download link, needs your API token width?: number // infographic height?: number }> slides?: Array<{ // slides image: string // GET /artifacts/download link (format=slide&index=N) caption: string | null text: string | null }> text?: string // report (Markdown), interactive_report, infographic table?: string[][] // table: rows of cells, header row first content?: unknown // quiz, flashcards, mindmap: Google's JSON embedded?: Array<{ // interactive_report: the items it suggests, in reading order artifact: string // the item's id, for POST /artifacts/generate or DELETE /artifacts/{artifact} type: string // 'infographic', 'slides', 'mindmap', 'quiz' or 'flashcards' title: string description?: string status: string // 'suggested' until generated }> } | { // status 'completed', type 'research' (POST /research) mode: 'fast' | 'deep' query: string summary?: string // fast: Google's one-line summary of what it found report?: { // deep: the Deep Research report title: string markdown: string } noResults?: true // the run found nothing (sources is []) sources: Array<{ url: string title: string description: string | null cited: boolean // deep: the report cites it. fast: always true }> } } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/gemini-notebook/artifacts" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "type": "slides", "format": "presenter", "length": "short", "mode": "async" }' ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = "https://api.useapi.net/v1/gemini-notebook"; const headers = { "Content-Type": "application/json", "Authorization": `Bearer ${token}` }; const response = await fetch(`${apiUrl}/artifacts`, { method: "POST", headers, body: JSON.stringify({ type: "audio", urls: ["https://en.wikipedia.org/wiki/Apollo_11"], format: "brief", mode: "async" }) }); let job = await response.json(); console.log("submitted", response.status, job); while (job.status === "pending" || job.status === "processing") { await new Promise(r => setTimeout(r, 15000)); job = await (await fetch(`${apiUrl}/jobs/${encodeURIComponent(job.jobid)}`, { headers })).json(); console.log(job.status); } console.log("result", job.result ?? job.error); ``` **Python** ``` python import time import requests from urllib.parse import quote token = "API token" apiUrl = "https://api.useapi.net/v1/gemini-notebook" headers = {"Content-Type": "application/json", "Authorization": f"Bearer {token}"} data = { "type": "audio", "urls": ["https://en.wikipedia.org/wiki/Apollo_11"], "format": "brief", "mode": "async" } response = requests.post(f"{apiUrl}/artifacts", headers=headers, json=data) job = response.json() print("submitted", response.status_code, job) while job.get("status") in ("pending", "processing"): time.sleep(15) job = requests.get(f"{apiUrl}/jobs/{quote(job['jobid'], safe='')}", headers=headers).json() print(job["status"]) print("result", job.get("result") or job.get("error")) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-chat-settings === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-chat-settings --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> chat/settings description: "Configure a notebook's chat via POST chat/settings in the useapi.net Gemini Notebook API — a default, learning-guide or custom persona goal and a default, longer or shorter answer length." parent: Gemini Notebook API nav_order: 406 permalink: /docs/api-gemini-notebook-v1/post-gemini-notebook-chat-settings --- ## Configure chat September 29, 2026 (November 16, 2026) --- Set how a notebook's chat answers, the "Configure chat" dialog of the Gemini Notebook web app. The setting belongs to the notebook, so it applies to every later [POST /chat](/docs/api-gemini-notebook-v1/post-gemini-notebook-chat) question on it, and to chats in the web app. - `goal` is the conversational style: `default`, `learning_guide`, or `custom` with your own `persona` prompt. Sending `persona` alone sets the goal to `custom`. - `length` is the answer length: `default`, `longer` or `shorter`. Google saves the goal and the length together, so whichever you leave out is set back to `default`. The response shows both values as saved. > **https://api.useapi.net/v1/gemini-notebook/chat/settings** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "persona": "You are a NASA flight controller. Answer in two sentences." } ``` - `notebook` is **required**, the notebook id. The id names its account, so no `email` is needed. - `goal` is optional, the conversational goal. Supported values: `default`, `learning_guide`, `custom`. Default: `custom` when `persona` is sent, otherwise `default`. - `persona` is optional, the custom goal's prompt: the role, tone or rules the chat should follow. Required with `goal: "custom"` and rejected with any other goal. Length: `1` to `10,000` characters. - `length` is optional, the answer length. Supported values: `default`, `longer`, `shorter`. Default: `default`. Provide `goal`, `persona`, `length` or any combination. ##### Responses **200** **200 OK** The settings as saved. ```json { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "goal": "custom", "persona": "You are a NASA flight controller. Answer in two sentences.", "length": "default" } ``` ```json { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "goal": "learning_guide", "length": "shorter" } ``` **400** **400 Bad Request** A missing or invalid parameter, nothing to change, or `persona` that does not match the goal. ```json { "error": "persona is required with goal custom, and only then", "code": 400 } ``` ```json { "error": "Provide goal, persona and/or length", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The id was issued to a different API token. ```json { "error": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55 does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** The notebook was deleted, or its account is no longer configured. ```json { "error": "Not found on account user@example.com (Google s0tc2d grpc 5)", "code": 404 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` **503** **503 Service Unavailable** Google is temporarily unavailable or is challenging our network. Retry in a few minutes. A `502` means Google answered with an unexpected error. ```json { "error": "Google is temporarily unavailable (s0tc2d grpc 14), please retry", "code": 503 } ``` ##### Model The chat settings as Google saved them: the `goal`, the `persona` of a custom goal and the answer `length`. <details markdown="block" class="model-details"> <summary>The saved chat settings, field by field</summary> ```typescript { // TypeScript, all fields are optional notebook: string goal: 'default' | 'learning_guide' | 'custom' persona?: string // goal custom only length: 'default' | 'longer' | 'shorter' error: string // error responses only code: number // error responses only, the HTTP status } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/gemini-notebook/chat/settings" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "goal": "learning_guide", "length": "shorter" }' ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = "https://api.useapi.net/v1/gemini-notebook/chat/settings"; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ notebook: "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", persona: "You are a NASA flight controller. Answer in two sentences." }) }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" apiUrl = "https://api.useapi.net/v1/gemini-notebook/chat/settings" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } data = { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "goal": "default", "length": "default" } response = requests.post(apiUrl, headers=headers, json=data) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-chat === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-chat --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> chat description: "Ask a question grounded in a notebook's sources via POST chat in the useapi.net Gemini Notebook API v1 — Markdown answer, cited source ids, follow-ups." parent: Gemini Notebook API nav_order: 400 permalink: /docs/api-gemini-notebook-v1/post-gemini-notebook-chat --- ## Chat with a notebook September 29, 2026 (November 16, 2026) --- Ask Gemini Notebook a question about a notebook's sources and get an answer grounded in them. The answer is Markdown with inline citation markers such as `[1]`, `[1, 2]` or `[9-12]`. Each marker number matches an entry in `citations`, which carries the quoted passage and the id of the source it came from. The call waits for the full answer and returns it in one response, which typically takes 15 to 30 seconds. It does not create a job. By default the question is answered from every source of the notebook whose `status` is `ready`. Sources still being processed are left out, so after adding sources with [POST /sources](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources) or [POST /sources/upload](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources-upload), check [GET /notebooks/`notebook`](/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks-notebook) until they are ready. Pass `sources` to limit the answer to specific sources. To ask a follow-up, send the `conversation` id from the previous answer. The earlier turns of that conversation are read from Google and sent along with the new question, so the answer can refer back to them. [GET /chat](/docs/api-gemini-notebook-v1/get-gemini-notebook-chat) reads a conversation back, [DELETE /chat](/docs/api-gemini-notebook-v1/delete-gemini-notebook-chat) clears it, and [POST /chat/settings](/docs/api-gemini-notebook-v1/post-gemini-notebook-chat-settings) sets the notebook's answer style and length. Google counts each question against the account's usage limits as its `qna` action. Its cost is small, and [GET /accounts/`email`](/docs/api-gemini-notebook-v1/get-gemini-notebook-accounts-email) shows the current estimate. > **https://api.useapi.net/v1/gemini-notebook/chat** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "question": "What went wrong during Eagle's descent, and how did the crew handle it?" } ``` - `notebook` is **required**, the notebook id returned by [POST /notebooks](/docs/api-gemini-notebook-v1/post-gemini-notebook-notebooks) or [GET /notebooks](/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks). The question runs on the account the notebook belongs to. - `question` is **required**, the question to ask. From 1 to 10,000 characters. - `conversation` is optional, the `conversation` id returned by an earlier answer in this notebook. Pass it to ask a follow-up in the same conversation. Omit it to start a new one. - `sources` is optional, an array of 1 to 300 source ids from this notebook (see [GET /notebooks/`notebook`](/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks-notebook)). Only these sources are used for the answer. When omitted, every `ready` source is used. ##### Responses **200** **200 OK** ```json { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "answer": "During *Eagle*'s lunar descent, several critical issues arose in rapid succession:\n\n1. **Overshooting the Target Site**:\n *Eagle* passed surface landmarks two to three seconds early, indicating it was traveling too fast [1, 2]. ...\n\n2. **1201 and 1202 Guidance Computer Alarms**:\n About five minutes into the descent burn, the computer issued unexpected **1201 and 1202 program alarms** [3, 4]. ...", "conversation": "30569582-8aa8-4c2d-a442-4e5d2b4185f0", "citations": [ { "number": 1, "source": "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:5a5455b1-0557-4fa4-a8a8-52f60dffa113", "text": "At 12:52:00 UTC on July 20, Aldrin and Armstrong entered Eagle, and began the final preparations for lunar descent.[8] At 17:44:00 Eagle separated from Columbia.[13] ...", "relevance": 0.9786729857819905 }, { "number": 2, "source": "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:c1182943-b7f0-4e89-82bc-8b3614cfb78f", "text": "Lunar descentColumbia in lunar orbit, photographed from EagleAt 12:52:00 UTC on July 20, Aldrin and Armstrong entered Eagle, and began the final preparations for lunar descent. [8] ...", "relevance": 0.9549763033175356 } ], "ms": 26755 } ``` **400** **400 Bad Request** A parameter is missing or invalid, or a `sources` id belongs to a different notebook. ```json { "error": "Parameter question is required", "code": 400 } ``` ```json { "error": "source user:12345-user@example.com-source:93e89cc9-db25-46d0-bc14-216736e6b4c2:5a5455b1-0557-4fa4-a8a8-52f60dffa113 is not in notebook user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The notebook id was issued to a different API token. ```json { "error": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55 does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** The notebook was deleted, or its account is no longer configured. ```json { "error": "Not found on account user@example.com (Google rLM1Ne grpc 5)", "code": 404 } ``` **409** **409 Conflict** `sources` was omitted and no source of the notebook is `ready` yet. Add sources, or wait until they finish processing. ```json { "error": "The notebook has no ready sources to answer from", "code": 409 } ``` **429** **429 Too Many Requests** Google refused the question with a quota error. The API answers every Google quota refusal with this `429` and the same generic message, which was written for Studio jobs. Do not read it as the account being out of chat usage. In our tests chat kept working with the 5-hour window fully used. When Google's refusal names the window, `retryAt` (when it resets) and `window` (`5h` or `weekly`) are added. Check [GET /accounts/`email`](/docs/api-gemini-notebook-v1/get-gemini-notebook-accounts-email) for the account's live usage. ```json { "error": "Not enough of Google's 5h window is left on account user@example.com for this job; it resets at 2026-09-28T03:40:48.000Z. GET /accounts/user@example.com shows what each job needs", "code": 429, "retryAt": "2026-09-28T03:40:48.000Z", "window": "5h" } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` **503** **503 Service Unavailable** Google is temporarily unavailable or is challenging our network. Retry in a few minutes. A `502` means Google answered with an unexpected error. ```json { "error": "GOOGLE_BOT_CHECK: Google is challenging our network right now, please retry in a few minutes", "code": 503 } ``` Google also sometimes answers with no answer text. The API asks once more, and answers `503` when the second try is empty too. A single one of these is safe to retry. If chat on one account keeps coming back empty, Google is most likely limiting chat on that account, usually after many fast or parallel chats. Retrying straight away keeps the limit going. Instead: - Wait before chatting on that account again, from a few minutes to a couple of hours. - Send chats to one account one at a time, and give each request a client timeout of at least 120 seconds, so the answer isn't abandoned while Google is still writing it. - Don't re-add the account: it is still signed in, and other endpoints keep working. ```json { "error": "chat failed: Google returned no answer, please retry", "code": 503 } ``` **504** **504 Gateway Timeout** Google did not answer within 120 seconds, or the connection to Google dropped. Asking the question again is safe. ```json { "error": "chat failed: no answer within 120 s. Google may still complete it: check before retrying anything that creates", "code": 504 } ``` ##### Model The answer in Markdown with citation markers, the `citations` they point to, and the `conversation` id for a follow-up question. <details markdown="block" class="model-details"> <summary>The answer and its citations, field by field</summary> ```typescript { // TypeScript, all fields are optional notebook: string answer: string // Markdown, with inline citation markers like [1], [1, 2] or [9-12] conversation: string | null // pass it back as `conversation` to ask a follow-up citations: { number: number // 1-based, matches the markers in answer source: string | null // the cited source id: user:<userId>-<email>-source:<notebookUuid>:<sourceUuid> text: string // the cited passage from the source relevance: number | null // Google's relevance score, 0 to 1 }[] ms: number // how long Google took to answer, in milliseconds error: string // error responses only code: number // error responses only, the HTTP status retryAt: string // 429 only, when Google names the window: ISO 8601 time it resets window: string // 429 only, when Google names the window: '5h' or 'weekly' } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/gemini-notebook/chat" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "question": "How much fuel was left when they landed?", "conversation": "30569582-8aa8-4c2d-a442-4e5d2b4185f0" }' ``` **JavaScript** ``` javascript const token = "API token"; const notebook = "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55"; const apiUrl = "https://api.useapi.net/v1/gemini-notebook/chat"; const ask = async (question, conversation) => { const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ notebook, question, conversation }) }); return response.json(); }; const first = await ask("What went wrong during Eagle's descent, and how did the crew handle it?"); console.log(first.answer, first.citations); const followUp = await ask("How much fuel was left when they landed?", first.conversation); console.log(followUp.answer); ``` **Python** ``` python import requests token = "API token" notebook = "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55" apiUrl = "https://api.useapi.net/v1/gemini-notebook/chat" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } first = requests.post(apiUrl, headers=headers, json={ "notebook": notebook, "question": "What went wrong during Eagle's descent, and how did the crew handle it?" }).json() print(first["answer"]) follow_up = requests.post(apiUrl, headers=headers, json={ "notebook": notebook, "question": "How much fuel was left when they landed?", "conversation": first["conversation"] }).json() print(follow_up["answer"]) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-collections-collection === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-collections-collection --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> collections/`collection` description: "Edit a notebook collection via POST collections/collection in the useapi.net Gemini Notebook API — rename it, change its emoji, and add or remove notebooks in one request." parent: Gemini Notebook API nav_order: 274 permalink: /docs/api-gemini-notebook-v1/post-gemini-notebook-collections-collection --- ## Update a collection October 15, 2026 (November 16, 2026) --- Rename a collection, change its emoji, or add notebooks to it and remove notebooks from it, in one request. A rename keeps the collection's current emoji unless you send a new one. The collection id does not change. Removing a notebook from a collection does not delete the notebook. Google takes one change per call, so the API sends them one after another: the name and emoji first, then each notebook to add, then each notebook to remove. If Google refuses a change after some went through, the call answers with Google's error, and its message says how many changes were applied (for example `(the first 2 of 3 changes were applied; GET /collections shows the collection now)`). Check [GET /collections](/docs/api-gemini-notebook-v1/get-gemini-notebook-collections) before you send the rest again. The response is the collection as stored after all changes. > **https://api.useapi.net/v1/gemini-notebook/collections/`collection`** - `collection` is **required**, the collection id from [GET /collections](/docs/api-gemini-notebook-v1/get-gemini-notebook-collections) or [POST /collections](/docs/api-gemini-notebook-v1/post-gemini-notebook-collections), URL-encoded in the path (it contains `:` and `@`). The id names its account, so no `email` is needed. ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "name": "Space history", "emoji": "🚀", "addNotebooks": [ "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55" ] } ``` - `name` is optional, the new name. Length: `1` to `100` characters. - `emoji` is optional, the new emoji. Length: `1` to `16` characters. - `addNotebooks` is optional, an array of `1` to `100` notebook ids of the collection's account to add to the collection. - `removeNotebooks` is optional, an array of `1` to `100` notebook ids to remove from the collection. The notebooks themselves stay. Provide `name`, `emoji`, `addNotebooks`, `removeNotebooks` or any combination. ##### Responses **200** **200 OK** The collection after the change. ```json { "collection": "user:12345-user@example.com-collection:7f3b9e21-4c8a-4d6f-b2e5-1a9c0d8e6f43", "email": "user@example.com", "name": "Space history", "emoji": "🚀", "notebooks": [ "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55" ] } ``` **400** **400 Bad Request** A malformed parameter, nothing to change, or a notebook on another account. ```json { "error": "Provide name, emoji, addNotebooks and/or removeNotebooks", "code": 400 } ``` ```json { "error": "notebook user:12345-other@example.com-notebook:5b7e2a41-9c0d-4e8f-a1b3-6d2c8f0e7a95 is on another account than collection user:12345-user@example.com-collection:7f3b9e21-4c8a-4d6f-b2e5-1a9c0d8e6f43", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The id was issued to a different API token. ```json { "error": "user:12345-user@example.com-collection:7f3b9e21-4c8a-4d6f-b2e5-1a9c0d8e6f43 does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** The collection no longer exists, or its account is no longer configured. ```json { "error": "Collection user:12345-user@example.com-collection:7f3b9e21-4c8a-4d6f-b2e5-1a9c0d8e6f43 not found", "code": 404 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` **503** **503 Service Unavailable** Google is temporarily unavailable or is challenging our network. Check [GET /collections](/docs/api-gemini-notebook-v1/get-gemini-notebook-collections), then retry in a few minutes. A `502` means Google answered with an unexpected error. ```json { "error": "GOOGLE_BOT_CHECK: Google is challenging our network right now, please retry in a few minutes", "code": 503 } ``` ##### Model The collection as stored after all changes: its id, account, name, emoji and the ids of its notebooks. <details markdown="block" class="model-details"> <summary>The updated collection, field by field</summary> ```typescript { // TypeScript, all fields are optional collection: string // user:<id>-<email>-collection:<collection id> email: string name: string emoji?: string notebooks: string[] // notebook ids in this collection error: string // error responses only code: number // error responses only, the HTTP status } ``` </details> ##### Examples **Curl** ``` bash COLLECTION="user:12345-user@example.com-collection:7f3b9e21-4c8a-4d6f-b2e5-1a9c0d8e6f43" curl -X POST "https://api.useapi.net/v1/gemini-notebook/collections/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$COLLECTION")" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "name": "Space history", "addNotebooks": ["user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55"] }' ``` **JavaScript** ``` javascript const token = "API token"; const collection = "user:12345-user@example.com-collection:7f3b9e21-4c8a-4d6f-b2e5-1a9c0d8e6f43"; const apiUrl = `https://api.useapi.net/v1/gemini-notebook/collections/${encodeURIComponent(collection)}`; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ removeNotebooks: ["user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55"] }) }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests, urllib.parse token = "API token" collection = "user:12345-user@example.com-collection:7f3b9e21-4c8a-4d6f-b2e5-1a9c0d8e6f43" apiUrl = "https://api.useapi.net/v1/gemini-notebook/collections/" + urllib.parse.quote(collection, safe="") headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } data = { "emoji": "🌕" } response = requests.post(apiUrl, headers=headers, json=data) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-collections === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-collections --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> collections description: "Create a notebook collection via POST collections in the useapi.net Gemini Notebook API — a named folder, with an optional emoji, on one of your accounts." parent: Gemini Notebook API nav_order: 272 permalink: /docs/api-gemini-notebook-v1/post-gemini-notebook-collections --- ## Create a collection October 15, 2026 (November 16, 2026) --- Create an empty collection, a folder that groups an account's notebooks in the Gemini Notebook web app. Add notebooks to it with [POST /collections/`collection`](/docs/api-gemini-notebook-v1/post-gemini-notebook-collections-collection), and list collections with [GET /collections](/docs/api-gemini-notebook-v1/get-gemini-notebook-collections). A collection belongs to one account. Pass `email` when your API token has more than one account. If Google creates the collection but does not accept its emoji, the call still answers `201`, without `emoji` and with a `warning` that says why. > **https://api.useapi.net/v1/gemini-notebook/collections** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "email": "user@example.com", "name": "Space history", "emoji": "🚀" } ``` - `email` is optional, the [account](/docs/api-gemini-notebook-v1/get-gemini-notebook-accounts) to create the collection on. Required when your API token has more than one account. - `name` is **required**, the collection's name. Length: `1` to `100` characters. - `emoji` is optional, an emoji shown before the name. Length: `1` to `16` characters. ##### Responses **201** **201 Created** ```json { "collection": "user:12345-user@example.com-collection:7f3b9e21-4c8a-4d6f-b2e5-1a9c0d8e6f43", "email": "user@example.com", "name": "Space history", "emoji": "🚀", "notebooks": [] } ``` **400** **400 Bad Request** A missing or invalid parameter, or no `email` while the API token has several accounts. ```json { "error": "email is required: this API token has several accounts", "code": 400 } ``` ```json { "error": "Parameter name is required", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **404** **404 Not Found** The `email` is not one of your configured accounts. ```json { "error": "Account user@example.com is not configured", "code": 404 } ``` **502** **502 Bad Gateway** Google accepted the collection but did not list it yet. Check [GET /collections](/docs/api-gemini-notebook-v1/get-gemini-notebook-collections) before you create it again. ```json { "error": "Google accepted the collection but does not list it yet: check GET /collections before creating it again", "code": 502 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` **503** **503 Service Unavailable** Google is temporarily unavailable or is challenging our network. Check [GET /collections](/docs/api-gemini-notebook-v1/get-gemini-notebook-collections), then retry in a few minutes. ```json { "error": "GOOGLE_BOT_CHECK: Google is challenging our network right now, please retry in a few minutes", "code": 503 } ``` ##### Model The new collection's id, account, name and emoji, with an empty `notebooks` list and a `warning` if its emoji was not set. <details markdown="block" class="model-details"> <summary>The new collection, field by field</summary> ```typescript { // TypeScript, all fields are optional collection: string // user:<id>-<email>-collection:<collection id> email: string name: string emoji?: string notebooks: string[] // notebook ids, [] for a new collection warning?: string // the collection was created, but its emoji was not set error: string // error responses only code: number // error responses only, the HTTP status } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/gemini-notebook/collections" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "email": "user@example.com", "name": "Space history", "emoji": "🚀" }' ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = "https://api.useapi.net/v1/gemini-notebook/collections"; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ email: "user@example.com", name: "Space history" }) }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" apiUrl = "https://api.useapi.net/v1/gemini-notebook/collections" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } data = { "email": "user@example.com", "name": "Space history", "emoji": "🚀" } response = requests.post(apiUrl, headers=headers, json=data) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-labels-label === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-labels-label --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> labels/`label` description: "Edit a source label via POST labels/label in the useapi.net Gemini Notebook API — rename it, change its emoji, and add or remove sources in one request." parent: Gemini Notebook API nav_order: 494 permalink: /docs/api-gemini-notebook-v1/post-gemini-notebook-labels-label --- ## Update a source label September 29, 2026 (November 16, 2026) --- Rename a label, change its emoji, or add sources to it and remove sources from it, in one request. A rename keeps the label's current emoji unless you send a new one. The label id does not change. Google takes one change per call, so the API sends them one after another: the name and emoji first, then each source to add, then each source to remove. If Google refuses a change after some went through, the call answers with Google's error, and its message says how many changes were applied (for example `(the first 2 of 3 changes were applied; GET /labels shows the label now)`). Check [GET /labels](/docs/api-gemini-notebook-v1/get-gemini-notebook-labels) before you send the rest again. The response is the label as stored after all changes. > **https://api.useapi.net/v1/gemini-notebook/labels/`label`** - `label` is **required**, the label id from [GET /labels](/docs/api-gemini-notebook-v1/get-gemini-notebook-labels) or [POST /labels](/docs/api-gemini-notebook-v1/post-gemini-notebook-labels), URL-encoded in the path (it contains `:` and `@`). The id names its account and notebook, so no `email` or `notebook` is needed. ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "name": "The landing", "addSources": [ "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:1761af94-f5aa-47f3-9539-0b4ebcd547f8" ] } ``` - `name` is optional, the new name. Length: `1` to `100` characters. - `emoji` is optional, the new emoji. Length: `1` to `16` characters. - `addSources` is optional, an array of `1` to `300` source ids of the label's notebook to add to the label. - `removeSources` is optional, an array of `1` to `300` source ids to remove from the label. The sources stay in the notebook. Provide `name`, `emoji`, `addSources`, `removeSources` or any combination. ##### Responses **200** **200 OK** The label after the change. ```json { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "label": "user:12345-user@example.com-label:d02c903b-17f8-4241-a263-2be9e7359d55:5973ba2b-845e-41b5-97b2-ef855d5746ad", "name": "The landing", "emoji": "🚀", "sources": [ "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:1761af94-f5aa-47f3-9539-0b4ebcd547f8" ] } ``` **400** **400 Bad Request** A malformed parameter, nothing to change, or a source from another notebook. ```json { "error": "Provide name, emoji, addSources and/or removeSources", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The id was issued to a different API token. ```json { "error": "user:12345-user@example.com-label:d02c903b-17f8-4241-a263-2be9e7359d55:5973ba2b-845e-41b5-97b2-ef855d5746ad does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** The label is no longer in the notebook, the notebook was deleted, or its account is no longer configured. ```json { "error": "Label user:12345-user@example.com-label:d02c903b-17f8-4241-a263-2be9e7359d55:5973ba2b-845e-41b5-97b2-ef855d5746ad not found", "code": 404 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` **503** **503 Service Unavailable** Google is temporarily unavailable or is challenging our network. Retry in a few minutes. A `502` means Google answered with an unexpected error. ```json { "error": "Google is temporarily unavailable (le8sX grpc 14), please retry", "code": 503 } ``` ##### Model The label as stored after all changes: its id, name, emoji and the ids of the sources it holds. <details markdown="block" class="model-details"> <summary>The updated label, field by field</summary> ```typescript { // TypeScript, all fields are optional notebook: string label: string // user:<id>-<email>-label:<notebook uuid>:<label uuid> name: string emoji?: string sources: string[] // source ids with this label error: string // error responses only code: number // error responses only, the HTTP status } ``` </details> ##### Examples **Curl** ``` bash LABEL="user:12345-user@example.com-label:d02c903b-17f8-4241-a263-2be9e7359d55:5973ba2b-845e-41b5-97b2-ef855d5746ad" curl -X POST "https://api.useapi.net/v1/gemini-notebook/labels/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$LABEL")" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "name": "The landing", "addSources": ["user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:1761af94-f5aa-47f3-9539-0b4ebcd547f8"] }' ``` **JavaScript** ``` javascript const token = "API token"; const label = "user:12345-user@example.com-label:d02c903b-17f8-4241-a263-2be9e7359d55:5973ba2b-845e-41b5-97b2-ef855d5746ad"; const apiUrl = `https://api.useapi.net/v1/gemini-notebook/labels/${encodeURIComponent(label)}`; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ removeSources: ["user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:1761af94-f5aa-47f3-9539-0b4ebcd547f8"] }) }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests, urllib.parse token = "API token" label = "user:12345-user@example.com-label:d02c903b-17f8-4241-a263-2be9e7359d55:5973ba2b-845e-41b5-97b2-ef855d5746ad" apiUrl = "https://api.useapi.net/v1/gemini-notebook/labels/" + urllib.parse.quote(label, safe="") headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } data = { "emoji": "🌕" } response = requests.post(apiUrl, headers=headers, json=data) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-labels === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-labels --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> labels description: "Create source labels via POST labels in the useapi.net Gemini Notebook API — let Google auto-label every source by topic, only the unlabeled ones, or add a named label." parent: Gemini Notebook API nav_order: 492 permalink: /docs/api-gemini-notebook-v1/post-gemini-notebook-labels --- ## Create source labels September 29, 2026 (November 16, 2026) --- Create labels for a notebook's sources in one of two ways: - `auto` lets Google group the sources by topic, the "Auto-label your sources" action of the Gemini Notebook web app. `auto: "all"` labels every source and replaces all existing labels, so every label gets a new id. `auto: "unlabeled"` labels only the sources that have no label yet and keeps the existing labels as they are. - `name` (with an optional `emoji`) adds one empty label of your own. Add sources to it with [POST /labels/`label`](/docs/api-gemini-notebook-v1/post-gemini-notebook-labels-label). The response is the notebook's whole label set after the change, in the shape of [GET /labels](/docs/api-gemini-notebook-v1/get-gemini-notebook-labels). The API does not retry this call, so after a `502`, `503` or `504` check [GET /labels](/docs/api-gemini-notebook-v1/get-gemini-notebook-labels) before you try again. > **https://api.useapi.net/v1/gemini-notebook/labels** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "auto": "all" } ``` ```json { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "name": "The landing", "emoji": "🚀" } ``` - `notebook` is **required**, the notebook id. The id names its account, so no `email` is needed. - `auto` is optional, let Google label the sources by topic. Supported values: `all` (every source, replacing all labels), `unlabeled` (only sources without a label). - `name` is optional, the name of a new label of your own. Length: `1` to `100` characters. - `emoji` is optional, with `name` only, an emoji shown before the label's name. Length: `1` to `16` characters. Provide either `auto` or `name`, not both. ##### Responses **201** **201 Created** The notebook's labels after the change. ```json { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "labels": [ { "label": "user:12345-user@example.com-label:d02c903b-17f8-4241-a263-2be9e7359d55:01a0466f-bd9f-48ab-a27d-5ae84181aa42", "name": "Apollo 11 Mission", "sources": [ "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:1761af94-f5aa-47f3-9539-0b4ebcd547f8", "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:2744eb7c-399a-4573-bd32-126143ba9514" ] }, { "label": "user:12345-user@example.com-label:d02c903b-17f8-4241-a263-2be9e7359d55:5973ba2b-845e-41b5-97b2-ef855d5746ad", "name": "The landing", "emoji": "🚀", "sources": [] } ] } ``` **400** **400 Bad Request** A missing or invalid parameter, both `auto` and `name`, or `emoji` with `auto`. ```json { "error": "Provide auto (all | unlabeled), or name for a label of your own", "code": 400 } ``` ```json { "error": "emoji applies to a named label", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The id was issued to a different API token. ```json { "error": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55 does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** The notebook was deleted, or its account is no longer configured. ```json { "error": "Not found on account user@example.com (Google agX4Bc grpc 5)", "code": 404 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` **503** **503 Service Unavailable** Google is temporarily unavailable or is challenging our network. Retry in a few minutes. A `502` means Google answered with an unexpected error. ```json { "error": "Google is temporarily unavailable (agX4Bc grpc 14), please retry", "code": 503 } ``` ##### Model The notebook's whole label set after the change, each label with its id, name, emoji and source ids. <details markdown="block" class="model-details"> <summary>The notebook's whole label set, field by field</summary> ```typescript { // TypeScript, all fields are optional notebook: string labels: { label: string // user:<id>-<email>-label:<notebook uuid>:<label uuid> name: string emoji?: string sources: string[] // source ids with this label }[] error: string // error responses only code: number // error responses only, the HTTP status } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/gemini-notebook/labels" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "auto": "unlabeled" }' ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = "https://api.useapi.net/v1/gemini-notebook/labels"; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ notebook: "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", auto: "all" }) }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" apiUrl = "https://api.useapi.net/v1/gemini-notebook/labels" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } data = { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "name": "The landing", "emoji": "🚀" } response = requests.post(apiUrl, headers=headers, json=data) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-notebooks-copy === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-notebooks-copy --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> notebooks/copy description: "Duplicate a notebook via POST notebooks/copy in the useapi.net Gemini Notebook API — a new notebook on the same account with its sources and Studio artifacts." parent: Gemini Notebook API nav_order: 250 permalink: /docs/api-gemini-notebook-v1/post-gemini-notebook-notebooks-copy --- ## Copy a notebook September 29, 2026 (November 16, 2026) --- Make a copy of a notebook on the same Google account, with its sources and Studio artifacts. Everything in the copy gets new ids, and the original is not changed. The copy is titled `<original title> (copy)` unless you pass `title`. Read its sources and artifacts with [GET /notebooks/`notebook`](/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks-notebook). The copy holds every source and artifact of the original. Google's answer does not list them, so the response has no count. The API does not retry a copy, so a lost answer never becomes a second copy. After a `502`, `503` or `504`, check [GET /notebooks](/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks) before you try again. > **https://api.useapi.net/v1/gemini-notebook/notebooks/copy** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "title": "Apollo 11 (copy)" } ``` - `notebook` is **required**, the id of the notebook to copy, from [POST /notebooks](/docs/api-gemini-notebook-v1/post-gemini-notebook-notebooks) or [GET /notebooks](/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks). The copy is made on the same account. - `title` is optional, the title of the copy. Default: the original title followed by ` (copy)`. Length: `1` to `200` characters. ##### Responses **201** **201 Created** The new notebook. ```json { "notebook": "user:12345-user@example.com-notebook:651bdd96-3d98-4661-83b8-d5634051934c", "email": "user@example.com", "title": "Apollo 11 (copy)", "copiedFrom": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "created": "2026-09-29T20:22:11.000Z" } ``` **400** **400 Bad Request** A missing or malformed parameter. ```json { "error": "Parameter notebook is required", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The id was issued to a different API token. ```json { "error": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55 does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** The notebook was deleted, or its account is no longer configured. ```json { "error": "Not found on account user@example.com (Google rLM1Ne grpc 5)", "code": 404 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` **503** **503 Service Unavailable** Google is temporarily unavailable or is challenging our network. Retry in a few minutes. A `502` means Google answered with an unexpected error. ```json { "error": "Google is temporarily unavailable (te3DCe grpc 14), please retry", "code": 503 } ``` ##### Model The copy's new `notebook` id, its account and title, the original's id in `copiedFrom`, and when it was created. <details markdown="block" class="model-details"> <summary>The notebook copy, field by field</summary> ```typescript { // TypeScript, all fields are optional notebook: string // the new notebook's id email: string // the account, the same as the original's title: string copiedFrom: string // the original notebook's id created: string | null // ISO 8601 error: string // error responses only code: number // error responses only, the HTTP status } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/gemini-notebook/notebooks/copy" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55" }' ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = "https://api.useapi.net/v1/gemini-notebook/notebooks/copy"; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ notebook: "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", title: "Apollo 11 (copy)" }) }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" apiUrl = "https://api.useapi.net/v1/gemini-notebook/notebooks/copy" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } data = { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "title": "Apollo 11 (copy)" } response = requests.post(apiUrl, headers=headers, json=data) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-notebooks-notebook === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-notebooks-notebook --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> notebooks/`notebook` description: "Rename a notebook with POST notebooks/notebook in the useapi.net Gemini Notebook API v1 by sending a new title of up to 200 characters." parent: Gemini Notebook API nav_order: 230 permalink: /docs/api-gemini-notebook-v1/post-gemini-notebook-notebooks-notebook --- ## Rename a notebook September 29, 2026 (November 16, 2026) --- Change the title of a notebook. The notebook keeps its id, sources and artifacts. > **https://api.useapi.net/v1/gemini-notebook/notebooks/`notebook`** - `notebook` is **required**, the notebook id returned by [POST /notebooks](/docs/api-gemini-notebook-v1/post-gemini-notebook-notebooks) or [GET /notebooks](/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks). It contains `:` and `@`, so URL-encode it in the path (`encodeURIComponent` in JavaScript). ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "title": "Apollo 11 landing" } ``` - `title` is **required**, the new notebook title. From 1 to 200 characters. ##### Responses **200** **200 OK** ```json { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "title": "Apollo 11 landing" } ``` **400** **400 Bad Request** ```json { "error": "Parameter title is required", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The notebook id was issued to a different API token. ```json { "error": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55 does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** The notebook's account is no longer configured, or Google no longer has the notebook. ```json { "error": "Account user@example.com of user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55 is not configured", "code": 404 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` ##### Model The answer is the notebook's id and its new `title`. <details markdown="block" class="model-details"> <summary>The renamed notebook, field by field</summary> ```typescript { // TypeScript, all fields are optional notebook: string title: string // the new title error: string // error responses only code: number // error responses only, the HTTP status } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/gemini-notebook/notebooks/user%3A12345-user%40example.com-notebook%3Ad02c903b-17f8-4241-a263-2be9e7359d55" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "title": "Apollo 11 landing" }' ``` **JavaScript** ``` javascript const token = "API token"; const notebook = "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55"; const apiUrl = `https://api.useapi.net/v1/gemini-notebook/notebooks/${encodeURIComponent(notebook)}`; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ title: "Apollo 11 landing" }) }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests, urllib.parse token = "API token" notebook = "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55" apiUrl = "https://api.useapi.net/v1/gemini-notebook/notebooks/" + urllib.parse.quote(notebook, safe="") headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.post(apiUrl, headers=headers, json={"title": "Apollo 11 landing"}) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-notebooks === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-notebooks --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> notebooks description: "Create an empty notebook via POST notebooks in the useapi.net Gemini Notebook API v1, with an optional title, on a chosen account or the least busy one." parent: Gemini Notebook API nav_order: 200 permalink: /docs/api-gemini-notebook-v1/post-gemini-notebook-notebooks --- ## Create a notebook September 29, 2026 (November 16, 2026) --- Create a new, empty notebook. A notebook holds the sources that [chat](/docs/api-gemini-notebook-v1/post-gemini-notebook-chat) answers from and that Studio [artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts) are generated from. Add sources next with [POST /sources](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources) (web pages, YouTube videos, pasted text, Google Drive files) or [POST /sources/upload](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources-upload) (files). The returned `notebook` id names the account it lives on, so every later call on the notebook, its sources and its artifacts goes to that account automatically. This is the only notebook endpoint that picks an account. When `email` is omitted, the notebook goes to a healthy account with the fewest running jobs (chosen at random among equally busy ones). Google caps the number of notebooks per account and the sources per notebook by plan — 100 notebooks and 50 sources on the free plan, 500 notebooks and 300 sources on Google AI Pro. [GET /accounts/`email`](/docs/api-gemini-notebook-v1/get-gemini-notebook-accounts-email) shows the limits of each account. > **https://api.useapi.net/v1/gemini-notebook/notebooks** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "email": "user@example.com", "title": "Apollo 11" } ``` - `email` is optional, the account to create the notebook on, see [GET /accounts](/docs/api-gemini-notebook-v1/get-gemini-notebook-accounts). When omitted, the least busy healthy account is used. - `title` is optional, the notebook title. Up to 200 characters. When omitted, the notebook is created untitled. ##### Responses **201** **201 Created** ```json { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "email": "user@example.com", "title": "Apollo 11" } ``` **400** **400 Bad Request** ```json { "error": "Parameter title length exceeds 200 characters", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **404** **404 Not Found** The `email` account is not configured. ```json { "error": "Account user@example.com not found", "code": 404 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` Without `email`, `596` also means no healthy account is left: ```json { "error": "No healthy Gemini Notebook accounts available. Check GET /accounts", "code": 596 } ``` **503** **503 Service Unavailable** Google is temporarily unavailable or is challenging our network. Retry in a few minutes. A `502` means Google answered with an unexpected error. ```json { "error": "GOOGLE_BOT_CHECK: Google is challenging our network right now, please retry in a few minutes", "code": 503 } ``` ##### Model The new notebook's id, the account it lives on and its title, which is empty when you sent none. <details markdown="block" class="model-details"> <summary>The new notebook, field by field</summary> ```typescript { // TypeScript, all fields are optional notebook: string // user:<userId>-<email>-notebook:<uuid>, URL-encode it when used in a path email: string // the account the notebook lives on title: string // '' when no title was given error: string // error responses only code: number // error responses only, the HTTP status } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/gemini-notebook/notebooks" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "title": "Apollo 11" }' ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = "https://api.useapi.net/v1/gemini-notebook/notebooks"; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ title: "Apollo 11" }) }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" apiUrl = "https://api.useapi.net/v1/gemini-notebook/notebooks" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } body = { "title": "Apollo 11" } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-notes-mindmap === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-notes-mindmap --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> notes/mindmap description: "Create a mind map note via POST notes/mindmap in the useapi.net Gemini Notebook API — one call returns the JSON tree of the notebook's sources and saves it as a note." parent: Gemini Notebook API nav_order: 465 permalink: /docs/api-gemini-notebook-v1/post-gemini-notebook-notes-mindmap --- ## Create a mind map note September 29, 2026 (November 16, 2026) --- Generate a mind map of a notebook's sources in a single call and save it as a note, the older note-based mind map of Gemini Notebook. The answer carries the new note and the mind map as a JSON `tree` of `{ name, children }` nodes. The note is titled after the tree's root, has `type: mindmap`, and its `content` is the same tree as a JSON string. This is not a job: the call waits for Google and answers when the mind map is ready. It took about 9 seconds in our tests. For Studio's interactive mind map, run as a job and listed with the notebook's artifacts, use [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts) with `type: "mindmap"`. The mind map is built from the sources whose `status` is `ready`, or from the `sources` you pass. A notebook with no ready source returns `409`. > **https://api.useapi.net/v1/gemini-notebook/notes/mindmap** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "instructions": "Focus on the landing", "language": "en" } ``` - `notebook` is **required**, the notebook id. The id names its account, so no `email` is needed. - `sources` is optional, an array of `1` to `300` source ids from that notebook to build the mind map from. Default: every source whose `status` is `ready`. - `language` is optional, the language of the mind map, as a language code such as `en`, `es`, `pt_BR` or `zh_Hans`. Default: `en`. - `instructions` is optional, what to focus on. Maximum length: `10,000` characters. ##### Responses **201** **201 Created** The new note and its tree (tree and `content` shortened). ```json { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "note": "user:12345-user@example.com-note:d02c903b-17f8-4241-a263-2be9e7359d55:e99087c9-a2a5-41b4-ad89-067047045e3a", "title": "Apollo 11 Mission", "content": "{\n \"name\": \"Apollo 11 Mission\",\n \"children\": [\n {\n \"name\": \"Background & Goals\",\n ...", "type": "mindmap", "created": "2026-09-29T20:20:42.000Z", "updated": "2026-09-29T20:20:42.000Z", "tree": { "name": "Apollo 11 Mission", "children": [ { "name": "Background & Goals", "children": [ { "name": "Cold War Space Race" }, { "name": "JFK Moon Challenge (1961)" } ] }, { "name": "Personnel", "children": [ { "name": "Prime Crew", "children": [ { "name": "Neil Armstrong (Commander)" }, { "name": "Michael Collins (CMP)" }, { "name": "Buzz Aldrin (LMP)" } ] } ] } ] } } ``` **400** **400 Bad Request** A missing or malformed parameter, or a source from another notebook. ```json { "error": "Parameter language must be a language code such as en, es, pt_BR or zh_Hans", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The id was issued to a different API token. ```json { "error": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55 does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** The notebook was deleted, or its account is no longer configured. ```json { "error": "Not found on account user@example.com (Google rLM1Ne grpc 5)", "code": 404 } ``` **409** **409 Conflict** The notebook has no ready sources. Check each source's `status` with [GET /notebooks/`notebook`](/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks-notebook). ```json { "error": "The notebook has no ready sources", "code": 409 } ``` **502** **502 Bad Gateway** Google answered without a mind map, or with an unexpected error. The API does not retry the call, so after a `502` or `504` check [GET /notes](/docs/api-gemini-notebook-v1/get-gemini-notebook-notes) before you try again. ```json { "error": "Google request failed: mind map generation returned no tree", "code": 502 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` **503** **503 Service Unavailable** Google is temporarily unavailable or is challenging our network. Retry in a few minutes. A `502` means Google answered with an unexpected error. ```json { "error": "Google is temporarily unavailable (yyryJe grpc 14), please retry", "code": 503 } ``` ##### Model The note, as in [GET /notes/`note`](/docs/api-gemini-notebook-v1/get-gemini-notebook-notes-note#model), plus `tree`. <details markdown="block" class="model-details"> <summary>The mind map note, field by field, and the types it uses (<code>MindMapNode</code>)</summary> ```typescript { // TypeScript, all fields are optional notebook: string note: string // user:<id>-<email>-note:<notebook uuid>:<note uuid> title: string // the tree's root name content: string // the tree as a JSON string type: 'mindmap' created?: string // ISO 8601 updated?: string // ISO 8601 tree: MindMapNode error: string // error responses only code: number // error responses only, the HTTP status } type MindMapNode = { name: string children?: MindMapNode[] } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/gemini-notebook/notes/mindmap" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55" }' ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = "https://api.useapi.net/v1/gemini-notebook/notes/mindmap"; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ notebook: "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", instructions: "Focus on the landing" }) }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" apiUrl = "https://api.useapi.net/v1/gemini-notebook/notes/mindmap" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } data = { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "language": "es" } response = requests.post(apiUrl, headers=headers, json=data) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-notes-note === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-notes-note --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> notes/`note` description: "Edit a notebook note via POST notes/note in the useapi.net Gemini Notebook API — change its title, its text or both, and whatever you leave out stays as it was." parent: Gemini Notebook API nav_order: 440 permalink: /docs/api-gemini-notebook-v1/post-gemini-notebook-notes-note --- ## Update a note September 29, 2026 (November 16, 2026) --- Change a note's title, its text, or both. Google always saves the title and the text together, so the API fills in the current value of whichever field you leave out. The note id does not change. > **https://api.useapi.net/v1/gemini-notebook/notes/`note`** - `note` is **required**, the note id, URL-encoded in the path (it contains `:` and `@`). Note ids are returned by [POST /notes](/docs/api-gemini-notebook-v1/post-gemini-notebook-notes) and [GET /notes](/docs/api-gemini-notebook-v1/get-gemini-notebook-notes). The id names its account, so no `email` is needed. ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "title": "Eagle landing timeline", "content": "Powered descent began at 102:33 GET. Landing at 102:45 GET." } ``` - `title` is optional, the new title. When omitted, the title stays as it was. Length: `1` to `200` characters. - `content` is optional, the new text. It replaces the whole text of the note. When omitted, the text stays as it was. Length: `1` to `500,000` characters. Provide `title`, `content` or both. ##### Responses **200** **200 OK** The updated note. ```json { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "note": "user:12345-user@example.com-note:d02c903b-17f8-4241-a263-2be9e7359d55:e5514ee8-22e5-414d-aa67-86e8476ece09", "title": "Eagle landing timeline", "content": "Powered descent began at 102:33 GET. Landing at 102:45 GET.", "type": "note", "created": "2026-09-29T04:09:02.000Z", "updated": "2026-09-29T04:09:02.000Z" } ``` **400** **400 Bad Request** A malformed note id, an empty or too long parameter, or nothing to change. ```json { "error": "Provide title and/or content", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The note id was issued to a different API token. ```json { "error": "user:12345-user@example.com-note:d02c903b-17f8-4241-a263-2be9e7359d55:e5514ee8-22e5-414d-aa67-86e8476ece09 does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** The note was deleted, its notebook was deleted, or its account is no longer configured. ```json { "error": "Note user:12345-user@example.com-note:d02c903b-17f8-4241-a263-2be9e7359d55:e5514ee8-22e5-414d-aa67-86e8476ece09 not found", "code": 404 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` **503** **503 Service Unavailable** Google is temporarily unavailable or is challenging our network. Retry in a few minutes. A `502` means Google answered with an unexpected error. ```json { "error": "Google is temporarily unavailable (cYAfTb grpc 14), please retry", "code": 503 } ``` ##### Model The note, as in [GET /notes/`note`](/docs/api-gemini-notebook-v1/get-gemini-notebook-notes-note#model). <details markdown="block" class="model-details"> <summary>The updated note, field by field</summary> ```typescript { // TypeScript, all fields are optional notebook: string note: string // user:<id>-<email>-note:<notebook uuid>:<note uuid> title: string content: string type: string // note | saved_answer | mindmap created?: string // ISO 8601. Google moves it to the edit time when the content changes updated?: string // ISO 8601 error: string // error responses only code: number // error responses only, the HTTP status } ``` </details> ##### Examples **Curl** ``` bash NOTE="user:12345-user@example.com-note:d02c903b-17f8-4241-a263-2be9e7359d55:e5514ee8-22e5-414d-aa67-86e8476ece09" curl -X POST "https://api.useapi.net/v1/gemini-notebook/notes/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$NOTE")" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "title": "Eagle landing timeline" }' ``` **JavaScript** ``` javascript const token = "API token"; const note = "user:12345-user@example.com-note:d02c903b-17f8-4241-a263-2be9e7359d55:e5514ee8-22e5-414d-aa67-86e8476ece09"; const apiUrl = `https://api.useapi.net/v1/gemini-notebook/notes/${encodeURIComponent(note)}`; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ content: "Powered descent began at 102:33 GET. Landing at 102:45 GET." }) }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests, urllib.parse token = "API token" note = "user:12345-user@example.com-note:d02c903b-17f8-4241-a263-2be9e7359d55:e5514ee8-22e5-414d-aa67-86e8476ece09" apiUrl = "https://api.useapi.net/v1/gemini-notebook/notes/" + urllib.parse.quote(note, safe="") headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } data = { "title": "Eagle landing timeline", "content": "Powered descent began at 102:33 GET. Landing at 102:45 GET." } response = requests.post(apiUrl, headers=headers, json=data) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-notes-source === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-notes-source --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> notes/source description: "Turn a note into a notebook source via POST notes/source in the useapi.net Gemini Notebook API — its title and text become a Markdown source that chat and Studio can use." parent: Gemini Notebook API nav_order: 460 permalink: /docs/api-gemini-notebook-v1/post-gemini-notebook-notes-source --- ## Convert a note to a source September 29, 2026 (November 16, 2026) --- Copy a note into its notebook as a source, the "Convert to source" action of the Gemini Notebook web app. Notes are not read by [chat](/docs/api-gemini-notebook-v1/post-gemini-notebook-chat) or [Studio artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts). The source made from one is. The new source is a Markdown source (kind `markdown`) titled after the note. Its text is the note's title as a `### ` heading, followed by the note's text. A saved chat answer (`type: saved_answer`) loses its citation markers such as `[1]` or `[1, 3]` on the way, as in the web app. The note itself is kept. The source is a separate copy, so later edits to the note do not reach it, and deleting the note does not remove it. > **https://api.useapi.net/v1/gemini-notebook/notes/source** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "note": "user:12345-user@example.com-note:d02c903b-17f8-4241-a263-2be9e7359d55:e5514ee8-22e5-414d-aa67-86e8476ece09" } ``` - `note` is **required**, the note id returned by [POST /notes](/docs/api-gemini-notebook-v1/post-gemini-notebook-notes) or [GET /notes](/docs/api-gemini-notebook-v1/get-gemini-notebook-notes). The id names its account and notebook, so no `email` or `notebook` is needed. ##### Responses **201** **201 Created** The new source. ```json { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "source": "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:7f6f776d-2cb6-43e3-842d-bd37b5ba8f74", "title": "Eagle landing timeline", "kind": "markdown", "status": "ready", "words": 12, "created": "2026-09-29T04:09:07.000Z" } ``` **400** **400 Bad Request** A missing or malformed `note`. ```json { "error": "Parameter note is required", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The note id was issued to a different API token. ```json { "error": "user:12345-user@example.com-note:d02c903b-17f8-4241-a263-2be9e7359d55:e5514ee8-22e5-414d-aa67-86e8476ece09 does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** The note was deleted, its notebook was deleted, or its account is no longer configured. ```json { "error": "Note user:12345-user@example.com-note:d02c903b-17f8-4241-a263-2be9e7359d55:e5514ee8-22e5-414d-aa67-86e8476ece09 not found", "code": 404 } ``` **502** **502 Bad Gateway** Google accepted the note but did not return the new source, or answered with an unexpected error. Check the notebook with [GET /notebooks/`notebook`](/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks-notebook) before you retry, since the source may have been added. ```json { "error": "Google accepted the note but returned no source; check GET /notebooks/{notebook}", "code": 502 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` **503** **503 Service Unavailable** Google is temporarily unavailable or is challenging our network. Retry in a few minutes. ```json { "error": "Google is temporarily unavailable (izAoDd grpc 14), please retry", "code": 503 } ``` ##### Model The source object, as in [POST /sources](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources#model), plus its `notebook`. <details markdown="block" class="model-details"> <summary>The new source made from the note, field by field</summary> ```typescript { // TypeScript, all fields are optional notebook: string source: string // user:<id>-<email>-source:<notebook uuid>:<source uuid> title: string // the note's title kind: string // markdown status: string // preparing | processing | ready | error words?: number created?: string // ISO 8601 error: string // error responses only code: number // error responses only, the HTTP status } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/gemini-notebook/notes/source" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "note": "user:12345-user@example.com-note:d02c903b-17f8-4241-a263-2be9e7359d55:e5514ee8-22e5-414d-aa67-86e8476ece09" }' ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = "https://api.useapi.net/v1/gemini-notebook/notes/source"; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ note: "user:12345-user@example.com-note:d02c903b-17f8-4241-a263-2be9e7359d55:e5514ee8-22e5-414d-aa67-86e8476ece09" }) }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" apiUrl = "https://api.useapi.net/v1/gemini-notebook/notes/source" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } data = { "note": "user:12345-user@example.com-note:d02c903b-17f8-4241-a263-2be9e7359d55:e5514ee8-22e5-414d-aa67-86e8476ece09" } response = requests.post(apiUrl, headers=headers, json=data) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-notes === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-notes --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> notes description: "Write a note into a notebook via POST notes in the useapi.net Gemini Notebook API — your own text, or a whole chat conversation saved as Q&A turns." parent: Gemini Notebook API nav_order: 420 permalink: /docs/api-gemini-notebook-v1/post-gemini-notebook-notes --- ## Create a note September 29, 2026 (November 16, 2026) --- Add a note to a notebook, the same as writing one in the notes panel of the Gemini Notebook web app. A note is not a source: chat and Studio do not read it until you turn it into one with [POST /notes/source](/docs/api-gemini-notebook-v1/post-gemini-notebook-notes-source). Instead of writing the text yourself, you can save a whole chat conversation as one note: pass its `conversation` id from [POST /chat](/docs/api-gemini-notebook-v1/post-gemini-notebook-chat) or [GET /chat](/docs/api-gemini-notebook-v1/get-gemini-notebook-chat). The note is titled `Chat History` unless you pass `title`, and its text lists the turns oldest first, each question as `**Q:** …` and each answer as `**A:** …`, separated by blank lines. Up to the last 100 turns are included. List a notebook's notes with [GET /notes](/docs/api-gemini-notebook-v1/get-gemini-notebook-notes), and change one with [POST /notes/`note`](/docs/api-gemini-notebook-v1/post-gemini-notebook-notes-note). > **https://api.useapi.net/v1/gemini-notebook/notes** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "title": "Landing timeline", "content": "Powered descent began at 102:33 GET." } ``` - `notebook` is **required**, the notebook id returned by [POST /notebooks](/docs/api-gemini-notebook-v1/post-gemini-notebook-notebooks) or [GET /notebooks](/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks). The id names its account, so no `email` is needed. - `content` is optional, the note's text. Length: `1` to `500,000` characters. - `conversation` is optional, the id of a chat conversation of this notebook, from [POST /chat](/docs/api-gemini-notebook-v1/post-gemini-notebook-chat) or [GET /chat](/docs/api-gemini-notebook-v1/get-gemini-notebook-chat). The whole conversation is saved as the note's text. - `title` is optional, the note's title. Default: `New Note`, or `Chat History` with `conversation`. Length: `1` to `200` characters. Provide either `content` or `conversation`, not both. ##### Responses **201** **201 Created** ```json { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "note": "user:12345-user@example.com-note:d02c903b-17f8-4241-a263-2be9e7359d55:e5514ee8-22e5-414d-aa67-86e8476ece09", "title": "Landing timeline", "content": "Powered descent began at 102:33 GET.", "type": "note", "created": "2026-09-29T04:08:58.000Z", "updated": "2026-09-29T04:08:58.000Z" } ``` Saved from a conversation (`"conversation": "fd20f12d-611f-4008-9e61-94e02af005a9"`, answer shortened): ```json { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "note": "user:12345-user@example.com-note:d02c903b-17f8-4241-a263-2be9e7359d55:463766a0-92ce-4182-9cae-2649d1d7231d", "title": "Chat History", "content": "**Q:** What were the 1202 alarms?\n\n**A:** The 1202 program alarms during lunar descent indicated \"executive overflows,\" meaning the guidance computer was overloaded...\n\n**Q:** Who told the crew it was safe to continue?\n\n**A:** ...", "type": "note", "created": "2026-09-29T20:20:33.000Z", "updated": "2026-09-29T20:20:33.000Z" } ``` **400** **400 Bad Request** A missing, empty or malformed parameter. ```json { "error": "Provide content, or conversation to save a chat conversation as a note", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The notebook id was issued to a different API token. ```json { "error": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55 does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** The notebook was deleted, its account is no longer configured, or the `conversation` has no turns in this notebook (`Conversation <id> has no turns in this notebook`). ```json { "error": "Account user@example.com of user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55 is not configured", "code": 404 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` **503** **503 Service Unavailable** Google is temporarily unavailable or is challenging our network. Retry in a few minutes. A `502` means Google answered with an unexpected error. ```json { "error": "Google is temporarily unavailable (CYK0Xb grpc 14), please retry", "code": 503 } ``` ##### Model The note, as [GET /notes](/docs/api-gemini-notebook-v1/get-gemini-notebook-notes#model) lists it, plus its `notebook`. <details markdown="block" class="model-details"> <summary>The new note and its notebook, field by field</summary> ```typescript { // TypeScript, all fields are optional notebook: string note: string // user:<id>-<email>-note:<notebook uuid>:<note uuid> title: string content: string type: string // note created?: string // ISO 8601. Google moves it to the edit time when the content changes updated?: string // ISO 8601 error: string // error responses only code: number // error responses only, the HTTP status } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/gemini-notebook/notes" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "title": "Landing timeline", "content": "Powered descent began at 102:33 GET." }' ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = "https://api.useapi.net/v1/gemini-notebook/notes"; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ notebook: "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", title: "Landing timeline", content: "Powered descent began at 102:33 GET." }) }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" apiUrl = "https://api.useapi.net/v1/gemini-notebook/notes" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } data = { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "title": "Landing timeline", "content": "Powered descent began at 102:33 GET." } response = requests.post(apiUrl, headers=headers, json=data) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-research-import === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-research-import --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> research/import description: "Add what a research job found to its notebook via POST research/import in the useapi.net Gemini Notebook API — all cited sources, a chosen subset, or the Deep Research report." parent: Gemini Notebook API nav_order: 660 permalink: /docs/api-gemini-notebook-v1/post-gemini-notebook-research-import --- ## Import research results September 29, 2026 (November 16, 2026) --- Add the results of a completed [POST /research](/docs/api-gemini-notebook-v1/post-gemini-notebook-research) job to the notebook it ran on, the Import button of the Gemini Notebook web app. Web pages are added as web sources (Google may type a PDF link as `pdf`), YouTube links as YouTube sources, Google Drive results (`source: "drive"`) as Drive sources (a Google Doc as `google_docs`, which you can keep in sync with [POST /sources/sync](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources-sync), other files as `drive`), and a Deep Research report as a Markdown source titled after the report. A Drive result whose `mimeType` is `null` cannot be imported: the API answers `400` before Google is called. Leave its URL out of `urls` and add the file with [POST /sources](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources) and `drive: [{ fileId, mimeType, name }]`. What gets imported: - Without `urls`, the same as the web app's Import: the report (Deep Research only) plus every source the result marks `cited`. For Discover sources (`fast`) that is every source. Send `report: false` to leave the report out. - With `urls`, only those sources. Each URL must appear in the job's `result.sources`, cited or not. The report is added only with `report: true`. `urls: []` with `report: true` imports only the report. Google fetches every URL before it answers, so an import usually answers within one to two minutes (55 seconds to 2 minutes in our tests). If Google takes longer, the API answers `504` after about two minutes, and the import usually still completes. A URL Google cannot fetch is left out of the response. It may still show up in the notebook with `status: error`, see [GET /notebooks/`notebook`](/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks-notebook). After a `504` or a timeout on your side, check the notebook with [GET /notebooks/`notebook`](/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks-notebook) before you retry. The import may still have completed, and a retry would add every source a second time. > **https://api.useapi.net/v1/gemini-notebook/research/import** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "jobid": "job:526bc256-d897-493a-9ebc-7c9f35ca4428-user:12345-user@example.com-bot:gemini_notebook", "urls": [ "https://www.nasa.gov/wp-content/uploads/static/history//alsj/a11/a11.1201-pa.html", "https://www.ibiblio.org/apollo/Documents/CherryApollo11Exegesis.pdf" ] } ``` - `jobid` is **required**, the id of a completed research job from [POST /research](/docs/api-gemini-notebook-v1/post-gemini-notebook-research). The sources are added to that job's notebook, on its account. - `urls` is optional, an array of up to `500` URLs taken from the job's `result.sources`. `[]` imports no sources. Default: every source with `cited: true`. - `report` is optional, `true` or `false`, whether to import the Deep Research report as a source. Default: `true` without `urls`, `false` with `urls`. ##### Responses **201** **201 Created** The sources added, one entry each. ```json { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "sources": [ { "source": "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:7eb13573-3089-45cd-a0c2-072e7550f58e", "title": "Apollo 11 Lunar Surface Journal: Program Alarms - NASA", "kind": "web", "status": "ready", "words": 1118, "url": "https://www.nasa.gov/wp-content/uploads/static/history//alsj/a11/a11.1201-pa.html", "created": "2026-09-29T04:20:12.000Z" }, { "source": "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:45d05ce9-bb96-4195-87f4-dae61a37da23", "title": "Exegesis of the 1201 and 1202 Alarms Which Occurred During the Mission G Lunar Landing - Ibiblio", "kind": "pdf", "status": "ready", "words": 3739, "url": "https://www.ibiblio.org/apollo/Documents/CherryApollo11Exegesis.pdf", "created": "2026-09-29T04:20:12.000Z" } ] } ``` A Deep Research report alone (`"urls": [], "report": true`): ```json { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "sources": [ { "source": "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:3e0b77a3-88cb-43e2-8fd3-2cb956c6c6b3", "title": "Systemic Stress and Cascading Anomalies: An Engineering Analysis of the Apollo 11 Lunar Landing Near-Abort", "kind": "markdown", "status": "ready", "words": 2985, "created": "2026-09-29T04:15:32.000Z" } ] } ``` **400** **400 Bad Request** A malformed parameter, a URL that is not in the result, nothing to import, a Drive file of an unknown type, or a job that is not a research job. ```json { "error": "Not in this research result: https://example.com/not-there", "code": 400 } ``` ```json { "error": "Nothing to import: pick urls and/or report", "code": 400 } ``` The same `400` answers a research job that found nothing (`result.noResults: true`). ```json { "error": "Parameter jobid is not a valid jobid", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** ```json { "error": "jobid does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** No such job (job records are kept for 30 days), its account is no longer configured, or Google no longer has the notebook. ```json { "error": "Job job:526bc256-…-bot:gemini_notebook not found", "code": 404 } ``` **409** **409 Conflict** The job is still running, or it failed or was cancelled. Only a completed research job can be imported. ```json { "error": "Job job:0645b31d-ea2b-4c26-8754-a3b7876a21d0-user:12345-user@example.com-bot:gemini_notebook is failed; only a completed research job can be imported", "code": 409 } ``` **504** **504 Gateway Timeout** Google did not answer within about two minutes, or the connection dropped. The import usually still completes. Check the notebook before you retry, since a retry would add every source a second time. ```json { "error": "Google did not answer the import (timeout or dropped connection). It may still have completed: check GET /notebooks/user%3A12345-user%40example.com-notebook%3Ad02c903b-17f8-4241-a263-2be9e7359d55 before retrying", "code": 504 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` **503** **503 Service Unavailable** Google is temporarily unavailable or is challenging our network. Retry in a few minutes. A `502` means Google answered with an unexpected error. ```json { "error": "Google is temporarily unavailable (LBwxtb grpc 14), please retry", "code": 503 } ``` ##### Model The sources added, in the shape of [POST /sources](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources#model). <details markdown="block" class="model-details"> <summary>The sources added to the notebook, field by field</summary> ```typescript { // TypeScript, all fields are optional notebook: string // the research job's notebook sources: { source: string // user:<id>-<email>-source:<notebook uuid>:<source uuid> title: string kind: string // web, pdf, youtube, drive, google_docs, markdown (the report), see Source kinds status: string // preparing | processing | ready | error words?: number url?: string // web page or YouTube URL driveFileId?: string // Google Drive sources: the Drive file id created?: string // ISO 8601 }[] error: string // error responses only code: number // error responses only, the HTTP status } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/gemini-notebook/research/import" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "jobid": "job:139f798f-b450-45c3-9dfa-57cd9e8e8581-user:12345-user@example.com-bot:gemini_notebook" }' ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = "https://api.useapi.net/v1/gemini-notebook/research/import"; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ jobid: "job:139f798f-b450-45c3-9dfa-57cd9e8e8581-user:12345-user@example.com-bot:gemini_notebook", urls: [], report: true }) }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" apiUrl = "https://api.useapi.net/v1/gemini-notebook/research/import" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } data = { "jobid": "job:526bc256-d897-493a-9ebc-7c9f35ca4428-user:12345-user@example.com-bot:gemini_notebook", "urls": ["https://www.ibiblio.org/apollo/Documents/CherryApollo11Exegesis.pdf"] } response = requests.post(apiUrl, headers=headers, json=data) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-research === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-research --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> research description: "Find new sources on the web via POST research in the useapi.net Gemini Notebook API — Discover sources in about 15 seconds or a Deep Research report in minutes, run as a job." parent: Gemini Notebook API nav_order: 650 permalink: /docs/api-gemini-notebook-v1/post-gemini-notebook-research --- ## Research sources September 29, 2026 (November 16, 2026) --- Let Google search the web for a notebook, the "Discover sources" and "Deep Research" features of the Gemini Notebook web app. Pass a `query` and a `type`: - `fast` (the default) is Discover sources. It returns web sources with a title and a one-line description of each, plus a one-line `summary` of what it found. In our tests it returned 10 sources in about 15 seconds. - `deep` is Deep Research. Google researches the question at length and writes a report in Markdown, with the web sources it read. Each source says whether the report cites it (`cited`). It took 3.3 to 4.2 minutes in our tests (September 2026). Discover sources can also search the account's own Google Drive instead of the web: send `source: "drive"` with `type: "fast"`. Deep Research searches the web only. A Drive result links to the file, carries its `driveFileId`, and its `mimeType` for the file types seen so far (a Google Doc and a Word `.docx` in our tests, September 2026). Google leaves out Drive files that are already sources of the notebook, so a Drive search on a notebook that holds every matching file finds nothing. A run that finds nothing completes normally, with `result.sources: []` and `result.noResults: true`. There is nothing to import from it. A research run finds sources but does not add them. The notebook is unchanged until you pick what to keep and add it with [POST /research/import](/docs/api-gemini-notebook-v1/post-gemini-notebook-research-import): any of the sources, and for Deep Research the report itself as a Markdown source. Every research run is a job, like a [Studio artifact](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts). Poll it with [GET /jobs/`jobid`](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid), or pass `replyUrl` to receive the finished record by webhook. [DELETE /jobs/`jobid`](/docs/api-gemini-notebook-v1/delete-gemini-notebook-jobs-jobid) stops a run at Google. A research job holds one of the account's `maxJobs` slots while it runs, see [GET /jobs](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs). Deep Research spends Google's usage window, like a Studio job. [GET /accounts/`email`](/docs/api-gemini-notebook-v1/get-gemini-notebook-accounts-email) lists Google's cost estimates for research under the actions `deep_research` and `fast_research`. ### Sync, async and webhooks - `mode: "sync"` (the default) waits up to 90 seconds for the result. A run that finishes in time returns `200` with its `result`, which is the usual outcome for `fast`. A run still going at 90 seconds returns `202` with the job record, the usual outcome for `deep`, and you keep polling [GET /jobs/`jobid`](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid). If your connection drops during the wait, the job carries on and can still be polled. - `mode: "async"` returns `201` with the job record at once. - The API checks running jobs every ~15 seconds. A research job still running after 40 minutes is failed with `error.code: "timeout"`. - `replyUrl` receives one `POST` of the final job record when the job completes or fails. > **https://api.useapi.net/v1/gemini-notebook/research** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "query": "Why did the Apollo 11 landing nearly abort?", "type": "deep", "mode": "async", "replyUrl": "https://your-domain.com/webhook", "replyRef": "deep-1" } ``` - `notebook` is **required**, the notebook id returned by [POST /notebooks](/docs/api-gemini-notebook-v1/post-gemini-notebook-notebooks) or [GET /notebooks](/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks). The id names its account, so the job runs there. - `query` is **required**, what to research. Length: `1` to `2,000` characters. - `type` is optional, the kind of research. Supported values: `fast` (Discover sources, default), `deep` (Deep Research). - `source` is optional, where to search. Supported values: `web` (default), `drive` (the account's Google Drive, `type: "fast"` only). `drive` with `type: "deep"` returns `400`. - `mode` is optional, `sync` (default) or `async`. See [Sync, async and webhooks](#sync-async-and-webhooks). - `replyUrl` is optional, a public `http(s)` URL that receives one `POST` of the job record when the job completes or fails. See [GET /jobs/`jobid`](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid#model) for the record's shape. - `replyRef` is optional, your own reference echoed back in the job record, up to 1024 characters. ##### Responses **200** **200 OK** Sync mode, finished within 90 seconds (Discover sources, list shortened): ```json { "jobid": "job:526bc256-d897-493a-9ebc-7c9f35ca4428-user:12345-user@example.com-bot:gemini_notebook", "email": "user@example.com", "type": "research", "status": "completed", "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "created_at": "2026-09-29T04:10:07.338Z", "request": { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "query": "Apollo 11 lunar module guidance computer alarms", "type": "fast" }, "completed_at": "2026-09-29T04:10:23.751Z", "result": { "mode": "fast", "query": "Apollo 11 lunar module guidance computer alarms", "summary": "Navigate the technical causes, software design, and human decisions behind the famous Apollo 11 guidance computer alarms.", "sources": [ { "url": "https://www.ibiblio.org/apollo/Documents/CherryApollo11Exegesis.pdf", "title": "Exegesis of the 1201 and 1202 Alarms Which Occurred During the Mission G Lunar Landing - Ibiblio", "description": "Technical exegesis explaining the exact mechanism of 1201/1202 alarms.", "cited": true }, { "url": "https://www.nasa.gov/wp-content/uploads/static/apollo50th/pdf/A11_MissionReport.pdf", "title": "APOLLO 11 MISSION REPORT NOVEMBER 1969 - NASA", "description": "Official NASA report detailing the onboard timeline and initial findings.", "cited": true }, { "url": "https://science.nasa.gov/people/margaret-hamilton/", "title": "Margaret Hamilton - NASA Science", "description": "Overview of Margaret Hamilton's software engineering innovations for Apollo.", "cited": true } ] } } ``` A completed Deep Research job, from [GET /jobs/`jobid`](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid) or the webhook (report and list shortened): ```json { "jobid": "job:139f798f-b450-45c3-9dfa-57cd9e8e8581-user:12345-user@example.com-bot:gemini_notebook", "email": "user@example.com", "type": "research", "status": "completed", "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "created_at": "2026-09-29T04:11:57.062Z", "request": { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "query": "Why did the Apollo 11 landing nearly abort?", "type": "deep" }, "replyUrl": "https://your-domain.com/webhook", "replyRef": "deep-1", "completed_at": "2026-09-29T04:15:17.664Z", "result": { "mode": "deep", "query": "Why did the Apollo 11 landing nearly abort?", "report": { "title": "Systemic Stress and Cascading Anomalies: An Engineering Analysis of the Apollo 11 Lunar Landing Near-Abort", "markdown": "# Systemic Stress and Cascading Anomalies: An Engineering Analysis of the Apollo 11 Lunar Landing Near-Abort\n\nThe Apollo 11 lunar landing on July 20, 1969, represents a monumental achievement in aerospace engineering, yet the final powered descent of the Lunar Module (*Eagle*, LM-5) brought the mission to the threshold of an abort call [cite: 1, 2]..." }, "sources": [ { "url": "https://space.stackexchange.com/questions/37368/what-were-the-problems-on-the-apollo-11-lunar-module", "title": "What were the problems on the Apollo 11 lunar module?", "description": "Comprehensive breakdown of computer alarms and low fuel issues.", "cited": true }, { "url": "https://www.discovermagazine.com/apollo-11s-1202-alarm-explained-185", "title": "Apollo 11's \"1202 Alarm\" Explained - Discover Magazine", "description": "Detailed explanation of the 1202 alarms and computer overload.", "cited": true }, { "url": "https://space.stackexchange.com/questions/49244/why-didnt-nasa-simulate-the-conditions-leading-to-the-1202-alarm-during-apollo", "title": "Why didn't NASA simulate the conditions leading to the 1202 alarm during Apollo 11?", "description": null, "cited": false } ] } } ``` **201** **201 Created** Async mode. The job is created and returned at once. Poll [GET /jobs/`jobid`](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid) until `status` is `completed` or `failed`. ```json { "jobid": "job:139f798f-b450-45c3-9dfa-57cd9e8e8581-user:12345-user@example.com-bot:gemini_notebook", "email": "user@example.com", "type": "research", "status": "processing", "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "created_at": "2026-09-29T04:11:57.062Z", "request": { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "query": "Why did the Apollo 11 landing nearly abort?", "type": "deep" }, "replyUrl": "https://your-domain.com/webhook", "replyRef": "deep-1" } ``` **202** **202 Accepted** Sync mode, still running after 90 seconds. Poll [GET /jobs/`jobid`](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid) for the result. The job record is the same as the `201` one. **400** **400 Bad Request** A missing or invalid parameter. ```json { "error": "Parameter type (slow) valid values: fast,deep", "code": 400 } ``` ```json { "error": "Parameter query is required", "code": 400 } ``` ```json { "error": "Deep Research searches the web only; use type fast with source drive", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The `notebook` id belongs to a different API token, or Google does not allow this on the account's plan. ```json { "error": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55 does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** The notebook no longer exists at Google, or the account it names is not configured. In sync mode, a run that disappeared from the notebook while it ran also answers `404` with the failed job record (`error.code: "not_found"`). ```json { "error": "Account user@example.com of user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55 is not configured", "code": 404 } ``` **409** **409 Conflict** Sync mode, the run was cancelled within the 90-second wait, with [DELETE /jobs/`jobid`](/docs/api-gemini-notebook-v1/delete-gemini-notebook-jobs-jobid) or in the Gemini Notebook web app. The body is the failed job record with `error.code: "cancelled"`. **422** **422 Unprocessable Content** Sync mode, Google ended the run within 90 seconds in a state the API does not recognise. The body is the failed job record with `error.code: "generation_failed"`. **429** **429 Too Many Requests** The account already runs `maxJobs` jobs. Retry when one finishes, or raise `maxJobs` with [POST /accounts](/docs/api-gemini-notebook-v1/post-gemini-notebook-accounts): ```json { "error": "Account user@example.com is busy: 2/2 jobs running (maxJobs)", "code": 429 } ``` Google refused the run because not enough of its usage window is left. No job was created. `retryAt` and `window` are present when Google's refusal names the window: ```json { "error": "Not enough of Google's 5h window is left on account user@example.com for this job; it resets at 2026-09-29T07:40:48.000Z. GET /accounts/user@example.com shows what each job needs", "code": 429, "retryAt": "2026-09-29T07:40:48.000Z", "window": "5h" } ``` **503** **503 Service Unavailable** A temporary condition, retry in a few minutes. A `502` means Google answered with an unexpected error. ```json { "error": "Async mode is unavailable right now, use mode sync", "code": 503 } ``` The job could not be added to our job schedule. It is failed at once with `error.code: "scheduler"`. Google had already started the run by then, and it is not stopped. ```json { "error": "Unable to lock the job schedule of user 12345, please retry", "code": 503 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` ##### Model The job record. [GET /jobs/`jobid`](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid) and the `replyUrl` webhook return the same shape. A research job has `type: "research"` and no `artifact`. The `type` you sent (`fast` or `deep`) is echoed in `request.type` and in `result.mode`. <details markdown="block" class="model-details"> <summary>The research job record, field by field</summary> In sync mode a failed job answers with an HTTP status that matches `error.code`: `quota` → `429`, `account` → `596`, `not_found` → `404`, `generation_failed` → `422`, `cancelled` → `409`, `timeout` → `504`, anything else → `502`. ```typescript { // TypeScript, all fields are optional jobid: string // job:<uuid>-user:<id>-<email>-bot:gemini_notebook email: string // the account the job runs on type: 'research' status: 'processing' | 'completed' | 'failed' notebook: string created_at: string // ISO 8601 completed_at?: string // ISO 8601, when the job completed or failed request: { // your request body echoed back, without mode, replyUrl and replyRef notebook: string query: string type?: 'fast' | 'deep' source?: 'web' | 'drive' } replyUrl?: string replyRef?: string error?: { // status 'failed' code: 'quota' | 'account' | 'not_found' | 'generation_failed' | 'timeout' | 'google_error' | 'scheduler' | 'cancelled' message: string retryAt?: string } result?: { // status 'completed' mode: 'fast' | 'deep' query: string summary?: string // fast: Google's one-line summary of what it found report?: { // deep: the Deep Research report title: string markdown: string } noResults?: true // the run found nothing (sources is []) sources: { // [] when the run found nothing url: string title: string description: string | null cited: boolean // deep: the report cites it. fast: always true driveFileId?: string // source drive: the Drive file id mimeType?: string | null // source drive: the file's type, null when Google's type code is not one we know yet }[] } } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/gemini-notebook/research" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "query": "Apollo 11 lunar module guidance computer alarms" }' ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = "https://api.useapi.net/v1/gemini-notebook"; const headers = { "Content-Type": "application/json", "Authorization": `Bearer ${token}` }; const response = await fetch(`${apiUrl}/research`, { method: "POST", headers, body: JSON.stringify({ notebook: "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", query: "Why did the Apollo 11 landing nearly abort?", type: "deep", mode: "async" }) }); let job = await response.json(); console.log("submitted", response.status, job); while (job.status === "pending" || job.status === "processing") { await new Promise(r => setTimeout(r, 15000)); job = await (await fetch(`${apiUrl}/jobs/${encodeURIComponent(job.jobid)}`, { headers })).json(); console.log(job.status); } console.log("result", job.result ?? job.error); ``` **Python** ``` python import time import requests from urllib.parse import quote token = "API token" apiUrl = "https://api.useapi.net/v1/gemini-notebook" headers = {"Content-Type": "application/json", "Authorization": f"Bearer {token}"} data = { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "query": "Why did the Apollo 11 landing nearly abort?", "type": "deep", "mode": "async" } response = requests.post(f"{apiUrl}/research", headers=headers, json=data) job = response.json() print("submitted", response.status_code, job) while job.get("status") in ("pending", "processing"): time.sleep(15) job = requests.get(f"{apiUrl}/jobs/{quote(job['jobid'], safe='')}", headers=headers).json() print(job["status"]) print("result", job.get("result") or job.get("error")) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-sharing === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-sharing --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> sharing description: "Share a notebook via POST sharing in the useapi.net Gemini Notebook API — add or remove viewers and editors, open or restrict the link, allow copies and set the view level." parent: Gemini Notebook API nav_order: 480 permalink: /docs/api-gemini-notebook-v1/post-gemini-notebook-sharing --- ## Share a notebook September 29, 2026 (November 16, 2026) --- Change who can open a notebook, the same as saving the Share dialog of the Gemini Notebook web app. One call can combine all four changes: - `people` adds a person as a `viewer` or `editor`, changes their role, or removes them (`remove`). - `link` opens the notebook to anyone with the link (`public`) or limits it to the people listed (`restricted`). - `allowCopies` sets whether people who open the public link may copy the notebook. It applies to a public link only, so it cannot be sent with `link: "restricted"`. Switching the link to `restricted` resets it to allowed, as the web app does. - `viewLevel` sets what viewers of the shared notebook get: the full notebook (`full`) or its chat only (`chat`). Google allows it on paid plans only: an account with no Google AI plan answers `403` for both values. An account that shares a paid Google One family plan counts as paid here, even when [GET /accounts](/docs/api-gemini-notebook-v1/get-gemini-notebook-accounts) shows its `tier` as `free`. The owner (the account the notebook lives on) cannot be changed. Listing the owner in `people` returns `400`. By default Google emails every person you add or change, like the "Notify people" box in the web app. Send `notify: false` to skip the email. The response is the notebook's sharing after the change, in the shape of [GET /sharing](/docs/api-gemini-notebook-v1/get-gemini-notebook-sharing). Google's sharing read does not include the view level, so `viewLevel` is in the response only when you set it, echoing the value you sent. > **https://api.useapi.net/v1/gemini-notebook/sharing** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "people": [ { "email": "colleague@example.com", "role": "editor" } ], "link": "public", "allowCopies": false, "notify": false } ``` - `notebook` is **required**, the notebook id returned by [POST /notebooks](/docs/api-gemini-notebook-v1/post-gemini-notebook-notebooks) or [GET /notebooks](/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks). The id names its account, so no `email` is needed. - `people` is optional, an array of `1` to `50` `{ email, role }` objects. `role` supported values: `viewer`, `editor`, `remove`. - `link` is optional, the link access. Supported values: `public`, `restricted`. - `allowCopies` is optional, `true` or `false`, whether people with the public link may copy the notebook. Not accepted together with `link: "restricted"`. - `notify` is optional, `false` skips Google's share email to the people in `people`. Default: `true`. - `viewLevel` is optional, what viewers of the shared notebook can open. Paid Google plans only. Supported values: `full` (the whole notebook), `chat` (chat only). Provide `people`, `link`, `allowCopies`, `viewLevel` or any combination. ##### Responses **200** **200 OK** The sharing after the change. ```json { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "people": [ { "email": "user@example.com", "role": "owner", "name": "Jane Doe" }, { "email": "colleague@example.com", "role": "editor", "name": "colleague" } ], "link": "public", "allowCopies": false } ``` **400** **400 Bad Request** A missing or malformed parameter, nothing to change, `allowCopies` with a restricted link, or a change to the owner. With nothing to change the message is `Provide people, link, allowCopies and/or viewLevel`. ```json { "error": "user@example.com owns this notebook; its role cannot change", "code": 400 } ``` ```json { "error": "allowCopies applies to a public link only", "code": 400 } ``` ```json { "error": "Parameter people role of colleague@example.com must be one of editor, viewer, remove", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The notebook id was issued to a different API token, or Google does not allow the change on the account's plan. `viewLevel` (either value) is refused on an account with no Google AI plan. ```json { "error": "Not allowed on account user@example.com's plan (Google s0tc2d grpc 7)", "code": 403 } ``` ```json { "error": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55 does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** The notebook was deleted, or its account is no longer configured. ```json { "error": "Account user@example.com of user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55 is not configured", "code": 404 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` **503** **503 Service Unavailable** Google is temporarily unavailable or is challenging our network. Retry in a few minutes. A `502` means Google answered with an unexpected error. ```json { "error": "Google is temporarily unavailable (QDyure grpc 14), please retry", "code": 503 } ``` ##### Model The sharing, as in [GET /sharing](/docs/api-gemini-notebook-v1/get-gemini-notebook-sharing#model). <details markdown="block" class="model-details"> <summary>The notebook's sharing settings, field by field</summary> ```typescript { // TypeScript, all fields are optional notebook: string people: { email: string role: string // owner | editor | viewer name: string | null // the person's Google display name }[] link: 'public' | 'restricted' allowCopies: boolean viewLevel?: 'full' | 'chat' // only when set in this call, echoing the request error: string // error responses only code: number // error responses only, the HTTP status } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/gemini-notebook/sharing" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "people": [{ "email": "colleague@example.com", "role": "viewer" }] }' ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = "https://api.useapi.net/v1/gemini-notebook/sharing"; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ notebook: "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", link: "restricted", people: [{ email: "colleague@example.com", role: "remove" }] }) }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" apiUrl = "https://api.useapi.net/v1/gemini-notebook/sharing" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } data = { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "link": "public", "allowCopies": False } response = requests.post(apiUrl, headers=headers, json=data) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-sources-append === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-sources-append --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> sources/append description: "Add text to the end of an existing source via POST sources/append in the useapi.net Gemini Notebook API — the source keeps its id, and its word count grows." parent: Gemini Notebook API nav_order: 334 permalink: /docs/api-gemini-notebook-v1/post-gemini-notebook-sources-append --- ## Append text to a source October 15, 2026 (November 16, 2026) --- Add text to the end of a source that is already in a notebook. The source keeps its id, so anything that refers to it stays valid. Use it to grow a running log or a pasted-text source instead of adding a new source each time. It works on pasted-text sources and on web page sources. `title` is an optional heading for the added text. It does not appear in the source's text, which [GET /sources/`source`](/docs/api-gemini-notebook-v1/get-gemini-notebook-sources-source) returns with `content=true`. The response is the source after the change, with its updated `words`. > **https://api.useapi.net/v1/gemini-notebook/sources/append** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "source": "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:9197c51a-6c06-4ce4-8193-892d437bc8f5", "title": "Day 2", "text": "Mission log, day 2. The crew photographed the lunar terminator." } ``` - `source` is **required**, the source id from [GET /notebooks/`notebook`](/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks-notebook) or [POST /sources](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources). The id names its account and notebook, so no `email` or `notebook` is needed. - `text` is **required**, the text to add, up to 500,000 characters. - `title` is optional, a heading for the added text, up to 200 characters. ##### Responses **200** **200 OK** The source after the change. ```json { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "source": "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:9197c51a-6c06-4ce4-8193-892d437bc8f5", "title": "Mission log", "kind": "text", "status": "ready", "words": 38, "created": "2026-10-15T05:04:48.000Z" } ``` A web page source: ```json { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "source": "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:1761af94-f5aa-47f3-9539-0b4ebcd547f8", "title": "Apollo 11 - Wikipedia", "kind": "web", "status": "ready", "words": 25588, "url": "https://en.wikipedia.org/wiki/Apollo_11", "created": "2026-10-15T05:04:37.000Z" } ``` **400** **400 Bad Request** A missing or invalid parameter. ```json { "error": "Parameter text is required", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The id was issued to a different API token. ```json { "error": "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:9197c51a-6c06-4ce4-8193-892d437bc8f5 does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** The source is no longer in the notebook, the notebook was deleted, or its account is no longer configured. ```json { "error": "Source user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:9197c51a-6c06-4ce4-8193-892d437bc8f5 not found", "code": 404 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` **503** **503 Service Unavailable** Google is temporarily unavailable or is challenging our network. Check the source with [GET /sources/`source`](/docs/api-gemini-notebook-v1/get-gemini-notebook-sources-source), then retry in a few minutes. A `502` means Google answered with an unexpected error. ```json { "error": "GOOGLE_BOT_CHECK: Google is challenging our network right now, please retry in a few minutes", "code": 503 } ``` ##### Model The source with the text added: the same id, its current `status` and the new word count in `words`. <details markdown="block" class="model-details"> <summary>The source after the added text, field by field</summary> ```typescript { // TypeScript, all fields are optional notebook: string source: string // user:<id>-<email>-source:<notebook uuid>:<source uuid>, unchanged title: string kind: string // see POST /sources, "Source kinds and statuses" status: 'preparing' | 'processing' | 'ready' | 'error' words?: number // word count, including the added text url?: string // web and YouTube sources mimeType?: string driveFileId?: string created?: string // ISO 8601 error: string // error responses only code: number // error responses only, the HTTP status } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/gemini-notebook/sources/append" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "source": "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:9197c51a-6c06-4ce4-8193-892d437bc8f5", "title": "Day 2", "text": "Mission log, day 2. The crew photographed the lunar terminator." }' ``` **JavaScript** ``` javascript const token = "API token"; const response = await fetch("https://api.useapi.net/v1/gemini-notebook/sources/append", { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}` }, body: JSON.stringify({ source: "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:9197c51a-6c06-4ce4-8193-892d437bc8f5", text: "Mission log, day 3. The crew prepared for lunar orbit insertion." }) }); const result = await response.json(); console.log("response", response.status, result); ``` **Python** ``` python import requests token = "API token" response = requests.post( "https://api.useapi.net/v1/gemini-notebook/sources/append", headers={"Content-Type": "application/json", "Authorization": f"Bearer {token}"}, json={ "source": "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:9197c51a-6c06-4ce4-8193-892d437bc8f5", "title": "Day 2", "text": "Mission log, day 2. The crew photographed the lunar terminator." } ) print(response.status_code, response.json()) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-sources-copy === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-sources-copy --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> sources/copy description: "Copy sources into another notebook on the same account via POST sources/copy in the useapi.net Gemini Notebook API — new source ids, nothing fetched or uploaded again." parent: Gemini Notebook API nav_order: 336 permalink: /docs/api-gemini-notebook-v1/post-gemini-notebook-sources-copy --- ## Copy sources to another notebook October 15, 2026 (November 16, 2026) --- Copy sources from one notebook into another notebook on the same account. Nothing is fetched or uploaded again. Each copy gets a new `source` id in the target notebook, and the originals stay where they are. All `sources` must come from one notebook, and the target `notebook` must be a different notebook on the same account. To copy a whole notebook use [POST /notebooks/copy](/docs/api-gemini-notebook-v1/post-gemini-notebook-notebooks-copy), and to copy Studio artifacts use [POST /artifacts/copy](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts-copy). The copies start with `status: "processing"` and turn `ready` on their own. Check them with [GET /notebooks/`notebook`](/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks-notebook) on the target. The API does not retry this call, so after a `502`, `503` or `504` check [GET /notebooks/`notebook`](/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks-notebook) on the target before you try again. > **https://api.useapi.net/v1/gemini-notebook/sources/copy** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "sources": [ "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:1761af94-f5aa-47f3-9539-0b4ebcd547f8", "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:2744eb7c-399a-4573-bd32-126143ba9514" ], "notebook": "user:12345-user@example.com-notebook:5b7e2a41-9c0d-4e8f-a1b3-6d2c8f0e7a95" } ``` - `sources` is **required**, an array of `1` to `300` source ids, all from the same notebook. - `notebook` is **required**, the id of the notebook to copy into. It must be on the same account as the sources. ##### Responses **201** **201 Created** `from` is the original's id and `source` is the copy's new id. ```json { "notebook": "user:12345-user@example.com-notebook:5b7e2a41-9c0d-4e8f-a1b3-6d2c8f0e7a95", "sources": [ { "from": "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:2744eb7c-399a-4573-bd32-126143ba9514", "source": "user:12345-user@example.com-source:5b7e2a41-9c0d-4e8f-a1b3-6d2c8f0e7a95:61bea6fc-1c65-4fd8-b733-a5be55ecf37d", "title": "Apollo 13 - Wikipedia", "kind": "web", "status": "processing" }, { "from": "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:1761af94-f5aa-47f3-9539-0b4ebcd547f8", "source": "user:12345-user@example.com-source:5b7e2a41-9c0d-4e8f-a1b3-6d2c8f0e7a95:b3cffe4a-130b-42eb-b6d0-1edf33675051", "title": "Apollo 11 - Wikipedia", "kind": "web", "status": "processing" } ] } ``` **400** **400 Bad Request** A missing or invalid parameter, sources from more than one notebook, sources already in the target, or a target on another account. ```json { "error": "sources must all come from one notebook", "code": 400 } ``` ```json { "error": "the sources are already in this notebook", "code": 400 } ``` ```json { "error": "source user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:1761af94-f5aa-47f3-9539-0b4ebcd547f8 is on another account than notebook user:12345-other@example.com-notebook:5b7e2a41-9c0d-4e8f-a1b3-6d2c8f0e7a95", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The notebook id belongs to a different API token. ```json { "error": "user:12345-user@example.com-notebook:5b7e2a41-9c0d-4e8f-a1b3-6d2c8f0e7a95 does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** The account the notebook names is not configured, or a notebook or source no longer exists at Google. ```json { "error": "Account user@example.com of user:12345-user@example.com-notebook:5b7e2a41-9c0d-4e8f-a1b3-6d2c8f0e7a95 is not configured", "code": 404 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` **503** **503 Service Unavailable** Google is temporarily unavailable or is challenging our network. Check the target notebook, then retry in a few minutes. A `502` means Google answered with an unexpected error. ```json { "error": "GOOGLE_BOT_CHECK: Google is challenging our network right now, please retry in a few minutes", "code": 503 } ``` ##### Model The target notebook and one row per copy: the original's id, the copy's new `source` id, its title, kind and status. <details markdown="block" class="model-details"> <summary>The copied sources, field by field</summary> ```typescript { // TypeScript, all fields are optional notebook: string // the target notebook sources: { from: string // the original source's id source: string // the copy's id in the target notebook title: string kind: string // see POST /sources, "Source kinds and statuses" status: 'preparing' | 'processing' | 'ready' | 'error' words?: number url?: string // web and YouTube sources mimeType?: string driveFileId?: string created?: string // ISO 8601 }[] error: string // error responses only code: number // error responses only, the HTTP status } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/gemini-notebook/sources/copy" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "sources": ["user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:1761af94-f5aa-47f3-9539-0b4ebcd547f8"], "notebook": "user:12345-user@example.com-notebook:5b7e2a41-9c0d-4e8f-a1b3-6d2c8f0e7a95" }' ``` **JavaScript** ``` javascript const token = "API token"; const response = await fetch("https://api.useapi.net/v1/gemini-notebook/sources/copy", { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}` }, body: JSON.stringify({ sources: [ "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:1761af94-f5aa-47f3-9539-0b4ebcd547f8", "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:2744eb7c-399a-4573-bd32-126143ba9514" ], notebook: "user:12345-user@example.com-notebook:5b7e2a41-9c0d-4e8f-a1b3-6d2c8f0e7a95" }) }); const result = await response.json(); console.log("response", response.status, result); ``` **Python** ``` python import requests token = "API token" response = requests.post( "https://api.useapi.net/v1/gemini-notebook/sources/copy", headers={"Content-Type": "application/json", "Authorization": f"Bearer {token}"}, json={ "sources": ["user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:1761af94-f5aa-47f3-9539-0b4ebcd547f8"], "notebook": "user:12345-user@example.com-notebook:5b7e2a41-9c0d-4e8f-a1b3-6d2c8f0e7a95" } ) print(response.status_code, response.json()) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-sources-search === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-sources-search --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> sources/search description: "Search a notebook's sources via POST sources/search in the useapi.net Gemini Notebook API — the best-matching passages with their source ids and character offsets." parent: Gemini Notebook API nav_order: 332 permalink: /docs/api-gemini-notebook-v1/post-gemini-notebook-sources-search --- ## Search sources October 15, 2026 (November 16, 2026) --- Find the passages of a notebook's sources that best match a query. The results are the passages themselves, best match first, each with the id of its source and its place in that source's text. Google writes no answer, and the search does not count as a chat question. To get a written answer with citations use [POST /chat](/docs/api-gemini-notebook-v1/post-gemini-notebook-chat). `start` and `end` are character offsets in the source's text, which [GET /sources/`source`](/docs/api-gemini-notebook-v1/get-gemini-notebook-sources-source) returns with `content=true`. A query that matches nothing returns `"results": []`. > **https://api.useapi.net/v1/gemini-notebook/sources/search** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "query": "oxygen tank explosion", "limit": 5 } ``` - `notebook` is **required**, the notebook id. The id names its account, so no `email` is needed. - `query` is **required**, what to look for, up to 2,000 characters. - `sources` is optional, an array of `1` to `300` source ids of this notebook to search in. Default: every source in the notebook. - `limit` is optional, the most passages to return. Range: `1` to `100`. Default: `20`. ##### Responses **200** **200 OK** Best match first (passages shortened with `...`): ```json { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "results": [ { "source": "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:2744eb7c-399a-4573-bd32-126143ba9514", "text": "April 11, 1970, 22:32:08 UTC\nUndocking date\nApril 17, 1970, 16:43:00 UTC\n...**Apollo 13** (April 11– 17, 1970) was the seventh crewed mission in the [Apollo space program](https://en.wikipedia.org/wiki/Apollo_program) and would have been the third [Moon landing](https://en.wikipedia.org/wiki/Moon_landing). ...the landing was aborted after an oxygen tank in the [service module](https://en.wikipedia.org/wiki/Apollo_command_and_service_module#Service_module_(SM)) (SM) exploded two days into the mission...\n", "start": 14276, "end": 15189 }, { "source": "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:2744eb7c-399a-4573-bd32-126143ba9514", "text": "A routine stir of an oxygen tank ignited damaged wire insulation inside it, causing an explosion that vented the contents of both of the SM's oxygen tanks to space. ...With the lunar landing canceled, mission controllers worked to bring the crew home alive.\n", "start": 15189, "end": 15729 }, "..." ] } ``` **400** **400 Bad Request** A missing or invalid parameter, or a source from another notebook. ```json { "error": "Parameter query is required", "code": 400 } ``` ```json { "error": "source user:12345-user@example.com-source:5b7e2a41-9c0d-4e8f-a1b3-6d2c8f0e7a95:b3cffe4a-130b-42eb-b6d0-1edf33675051 is not in notebook user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The id was issued to a different API token. ```json { "error": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55 does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** The account the notebook names is not configured, or the notebook was deleted. ```json { "error": "Account user@example.com of user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55 is not configured", "code": 404 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` **503** **503 Service Unavailable** Google is temporarily unavailable or is challenging our network. Retry in a few minutes. A `502` means Google answered with an unexpected error. ```json { "error": "GOOGLE_BOT_CHECK: Google is challenging our network right now, please retry in a few minutes", "code": 503 } ``` ##### Model The matching passages, best match first, each with its source id and its character offsets in that source's text. <details markdown="block" class="model-details"> <summary>The matching passages, field by field</summary> ```typescript { // TypeScript, all fields are optional notebook: string results: { // best match first source: string // user:<id>-<email>-source:<notebook uuid>:<source uuid> text: string // the matching passage start?: number // character offset in the source's text where the passage starts end?: number // character offset where it ends }[] error: string // error responses only code: number // error responses only, the HTTP status } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/gemini-notebook/sources/search" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "query": "oxygen tank explosion", "limit": 5 }' ``` **JavaScript** ``` javascript const token = "API token"; const response = await fetch("https://api.useapi.net/v1/gemini-notebook/sources/search", { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}` }, body: JSON.stringify({ notebook: "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", query: "oxygen tank", sources: ["user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:2744eb7c-399a-4573-bd32-126143ba9514"] }) }); const result = await response.json(); console.log("response", response.status, result); ``` **Python** ``` python import requests token = "API token" response = requests.post( "https://api.useapi.net/v1/gemini-notebook/sources/search", headers={"Content-Type": "application/json", "Authorization": f"Bearer {token}"}, json={ "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "query": "oxygen tank explosion", "limit": 5 } ) for r in response.json().get("results", []): print(r["source"], r.get("start"), r["text"][:100]) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-sources-source === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-sources-source --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> sources/`source` description: "Rename a notebook source via POST sources/source in the useapi.net Gemini Notebook API — sets a new title of up to 200 characters and returns the updated source." parent: Gemini Notebook API nav_order: 320 permalink: /docs/api-gemini-notebook-v1/post-gemini-notebook-sources-source --- ## Rename a source September 29, 2026 (November 16, 2026) --- Change the title of a source added via [POST /sources](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources) or [POST /sources/upload](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources-upload). The title is what chat citations and the notebook's source list show. The source id does not change. > **https://api.useapi.net/v1/gemini-notebook/sources/`source`** - `source` is the source id, URL-encoded in the path (it contains `:` and `@`). Source ids are returned by [POST /sources](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources), [POST /sources/upload](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources-upload) and [GET /notebooks/`notebook`](/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks-notebook). The id names its account, so no `email` is needed. ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "title": "Apollo 11 timeline" } ``` - `title` is **required**, the new title. Length: `1` to `200` characters. ##### Responses **200** **200 OK** The renamed source. When Google does not echo the source back, the response carries only `source` and `title`. ```json { "source": "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:9df5b3d2-0afd-4ea7-9c20-e42c4af17d46", "title": "Apollo 11 timeline", "kind": "text", "status": "ready", "words": 57, "mimeType": "text/plain", "created": "2026-09-27T23:25:04.000Z" } ``` **400** **400 Bad Request** A malformed source id, or a missing or too long `title`. ```json { "error": "Parameter title is required", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The source id was issued to a different API token. ```json { "error": "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:9df5b3d2-0afd-4ea7-9c20-e42c4af17d46 does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** The account named in the source id is no longer configured, or Google reports the source or its notebook as not found. ```json { "error": "Account user@example.com of user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:9df5b3d2-0afd-4ea7-9c20-e42c4af17d46 is not configured", "code": 404 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` **503** **503 Service Unavailable** Google is temporarily unavailable or is challenging our network. Retry in a few minutes. A `502` means Google answered with an unexpected error. ```json { "error": "Google is temporarily unavailable (b7Wfje grpc 14), please retry", "code": 503 } ``` ##### Model The source object, as in [POST /sources](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources#model). All `kind` and `status` values are listed in [Source kinds and statuses](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources#source-kinds-and-statuses). <details markdown="block" class="model-details"> <summary>The renamed source, field by field</summary> ```typescript { // TypeScript, all fields are optional source: string // user:<id>-<email>-source:<notebook uuid>:<source uuid> title: string // the new title kind: string status: string // preparing | processing | ready | error words?: number url?: string // web page or YouTube URL mimeType?: string // file sources driveFileId?: string // Google Drive sources: the Drive file id created?: string // ISO 8601 } ``` </details> ##### Examples **Curl** ``` bash SOURCE="user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:9df5b3d2-0afd-4ea7-9c20-e42c4af17d46" curl -X POST "https://api.useapi.net/v1/gemini-notebook/sources/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$SOURCE")" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "title": "Apollo 11 timeline" }' ``` **JavaScript** ``` javascript const token = "API token"; const source = "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:9df5b3d2-0afd-4ea7-9c20-e42c4af17d46"; const apiUrl = `https://api.useapi.net/v1/gemini-notebook/sources/${encodeURIComponent(source)}`; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ title: "Apollo 11 timeline" }) }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests, urllib.parse token = "API token" source = "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:9df5b3d2-0afd-4ea7-9c20-e42c4af17d46" apiUrl = "https://api.useapi.net/v1/gemini-notebook/sources/" + urllib.parse.quote(source, safe="") headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.post(apiUrl, headers=headers, json={"title": "Apollo 11 timeline"}) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-sources-sync === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-sources-sync --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> sources/sync description: "Re-import a Google Drive source via POST sources/sync in the useapi.net Gemini Notebook API when its Doc or file changed in Drive — returns the source and synced true or false." parent: Gemini Notebook API nav_order: 327 permalink: /docs/api-gemini-notebook-v1/post-gemini-notebook-sources-sync --- ## Sync a Google Drive source September 29, 2026 (November 16, 2026) --- A source added from Google Drive with the `drive` parameter of [POST /sources](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources) is a copy of the file as it was then. When the Google Doc or Drive file changes later, the notebook keeps the old text until the source is synced, just like the sync button in the Gemini Notebook web app. This endpoint checks whether the Drive file changed since it was added. If it did, Google re-imports it and the response carries the refreshed source with `synced: true`. If it did not, nothing is re-imported and the response carries the source unchanged with `synced: false`. [GET /sources/`source`](/docs/api-gemini-notebook-v1/get-gemini-notebook-sources-source) shows the same check as `inSync`. For a Google Doc, Google starts the re-import as soon as it notices the change, including during that check. In our tests (September 2026) a Doc that GET /sources/`source` reported as `inSync: false` was already refreshed a few seconds later, and a sync right after answered `synced: false` with the new text already in the source. Read `words` or `content` to see what the notebook holds. Only Google Drive sources can be synced (kind `google_docs` or `drive`). Any other source returns `400`. A re-import usually answers within one to two minutes, because Google reads the file again before it answers. If Google takes longer, the API answers `504` after about two minutes, and the sync usually still completes. After a `504` or a timeout on your side, check the source with [GET /sources/`source`](/docs/api-gemini-notebook-v1/get-gemini-notebook-sources-source) before you retry. > **https://api.useapi.net/v1/gemini-notebook/sources/sync** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "source": "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:6b1e0f2a-93c4-4d7e-a1f5-2c8e9b7d4a31" } ``` - `source` is **required**, the id of a Google Drive source. The id names its account, so no `email` is needed. ##### Responses **200** **200 OK** The source, with `synced: true` when it was re-imported, or `synced: false` when the Drive file had not changed. ```json { "source": "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:6b1e0f2a-93c4-4d7e-a1f5-2c8e9b7d4a31", "title": "Apollo 11 landing notes", "kind": "google_docs", "status": "ready", "words": 10, "driveFileId": "1Qx7Lm2VtR8pKc4NwE9bYs3HfJ6uGdA0zT5iOv1eWnXk", "created": "2026-09-28T02:52:41.000Z", "synced": true } ``` **400** **400 Bad Request** A missing or malformed `source`, or a source that did not come from Google Drive. ```json { "error": "Only a Google Drive source can be synced (this one is text)", "code": 400 } ``` ```json { "error": "Parameter source is not a valid source id", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The source id was issued to a different API token. ```json { "error": "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:6b1e0f2a-93c4-4d7e-a1f5-2c8e9b7d4a31 does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** The source is no longer in its notebook, the notebook was deleted, or the account named in the id is no longer configured. ```json { "error": "Source user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:6b1e0f2a-93c4-4d7e-a1f5-2c8e9b7d4a31 not found", "code": 404 } ``` **504** **504 Gateway Timeout** Google did not answer the re-import within about two minutes, or the connection dropped. The sync usually still completes, so check the source with [GET /sources/`source`](/docs/api-gemini-notebook-v1/get-gemini-notebook-sources-source) before you retry. ```json { "error": "Google did not answer the sync (timeout or dropped connection). It may still have completed: check GET /sources/user%3A12345-user%40example.com-source%3Ad02c903b-17f8-4241-a263-2be9e7359d55%3A6b1e0f2a-93c4-4d7e-a1f5-2c8e9b7d4a31 before retrying", "code": 504 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` **503** **503 Service Unavailable** Google is temporarily unavailable or is challenging our network. Retry in a few minutes. A `502` means Google answered with an unexpected error. ```json { "error": "Google is temporarily unavailable (FLmJqe grpc 14), please retry", "code": 503 } ``` ##### Model The source object, as in [POST /sources](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources#model), plus `synced`. <details markdown="block" class="model-details"> <summary>The synced source, field by field</summary> ```typescript { // TypeScript, all fields are optional source: string // user:<id>-<email>-source:<notebook uuid>:<source uuid> title: string kind: string // google_docs | drive status: string // preparing | processing | ready | error words?: number mimeType?: string driveFileId?: string // the Drive file id created?: string // ISO 8601 synced: boolean // true = re-imported, false = the Drive file had not changed error: string // error responses only code: number // error responses only, the HTTP status } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/gemini-notebook/sources/sync" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "source": "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:6b1e0f2a-93c4-4d7e-a1f5-2c8e9b7d4a31" }' ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = "https://api.useapi.net/v1/gemini-notebook/sources/sync"; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ source: "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:6b1e0f2a-93c4-4d7e-a1f5-2c8e9b7d4a31" }) }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" apiUrl = "https://api.useapi.net/v1/gemini-notebook/sources/sync" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } data = { "source": "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:6b1e0f2a-93c4-4d7e-a1f5-2c8e9b7d4a31" } response = requests.post(apiUrl, headers=headers, json=data) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-sources-upload === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-sources-upload --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> sources/upload description: "Upload a file as a notebook source via POST sources/upload in the useapi.net Gemini Notebook API — the raw file as the request body: PDF, Word, PowerPoint, EPUB, audio, video, images." parent: Gemini Notebook API nav_order: 310 permalink: /docs/api-gemini-notebook-v1/post-gemini-notebook-sources-upload --- ## Upload a file source September 29, 2026 (November 16, 2026) --- Upload a file to a notebook as a new source. The file is sent as the raw request body with its MIME type in the `Content-Type` header (no multipart, no JSON). The notebook and the file name go in the query string. The source starts with `status` `preparing`. Google then processes it (`processing`) until it is `ready`. Poll [GET /notebooks/`notebook`](/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks-notebook) to see when it is ready. In our tests every file type below was ready within 5 minutes. Chat and Studio use only `ready` sources. To add web pages, YouTube videos, pasted text or Google Drive files use [POST /sources](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources). > **https://api.useapi.net/v1/gemini-notebook/sources/upload?notebook=`notebook`&name=`name`** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: {file MIME type} # see the table below Content-Length: {file size in bytes} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. - `Content-Length` is **required**. curl, `fetch` and `requests` set it for you when the body is a file or a buffer. A chunked upload without it returns `411`. - `Content-Type` is the file's MIME type. It is used to pick the file extension when `name` is omitted. The request body is the file's raw bytes. The API refuses files larger than `200 MB` (209,715,200 bytes) with `413`. Uploads over `100 MB` are untested, and Cloudflare's request-size limit may refuse them before they reach the API. File types tested with this endpoint: | File | Content-Type | Source `kind` | |---|---|---| | `.pdf` | `application/pdf` | `pdf` | | `.docx` | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` | `docx` | | `.pptx` | `application/vnd.openxmlformats-officedocument.presentationml.presentation` | `pptx` | | `.epub` | `application/epub+zip` | `epub` | | `.md` | `text/markdown` | `markdown` | | `.txt` | `text/plain` | `text` | | `.csv` | `text/csv` | `csv` | | `.mp3` | `audio/mpeg` | `media` | | `.mp4` | `video/mp4` | `media` | | `.jpg` | `image/jpeg` | `image` | All `kind` and `status` values are listed in [Source kinds and statuses](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources#source-kinds-and-statuses). ##### Query Parameters - `notebook` is **required**, the notebook id returned by [POST /notebooks](/docs/api-gemini-notebook-v1/post-gemini-notebook-notebooks) or [GET /notebooks](/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks). URL-encode it (it contains `:` and `@`). The id names its account, so no `email` is needed. - `name` is optional, the file name with its extension, e.g. `apollo11-overview.docx`. Google uses it as the source title and types the file by its extension. URL-encode it. Maximum length: `200` characters. When omitted, the name is `upload.<ext>` with the extension taken from `Content-Type`. That works for every Content-Type in the table above plus `audio/mp4` (`.m4a`), `audio/wav`, `image/png` and `image/webp`. Any other Content-Type without `name` returns `400`. Rename the source later with [POST /sources/`source`](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources-source). ##### Responses **201** **201 Created** The file was uploaded and Google is preparing it. ```json { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "source": "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:5a5455b1-0557-4fa4-a8a8-52f60dffa113", "title": "01-apollo11-wikipedia.pdf", "status": "preparing" } ``` Once ready, [GET /notebooks/`notebook`](/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks-notebook) lists it like this: ```json { "source": "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:5a5455b1-0557-4fa4-a8a8-52f60dffa113", "title": "01-apollo11-wikipedia.pdf", "kind": "pdf", "status": "ready", "words": 21578, "mimeType": "application/pdf", "created": "2026-09-27T23:24:53.000Z" } ``` **400** **400 Bad Request** A missing or malformed `notebook`, an empty body, or no `name` with a Content-Type we do not recognise. ```json { "error": "Pass ?name=<file name with extension> (or a Content-Type we recognise)", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The notebook id was issued to a different API token. ```json { "error": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55 does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** The account named in the notebook id is no longer configured, or Google no longer has the notebook. ```json { "error": "Account user@example.com of user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55 is not configured", "code": 404 } ``` **411** **411 Length Required** ```json { "error": "Send the file as the request body with a Content-Length header", "code": 411 } ``` **413** **413 Content Too Large** The file is larger than the API's `200 MB` limit. An upload over `100 MB` is untested and may be refused by Cloudflare before it reaches the API. ```json { "error": "File is 262144000 bytes, the limit is 209715200", "code": 413 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` **502** **502 Bad Gateway** Google refused the upload. An upload is sent to Google once and is never retried by the API, so send it again. A failed upload may leave an unfinished source in the notebook — remove it with [DELETE /sources/`source`](/docs/api-gemini-notebook-v1/delete-gemini-notebook-sources-source). A `503` means Google is temporarily unavailable, retry in a few minutes. ```json { "error": "Google request failed: upload failed: HTTP 400", "code": 502 } ``` ##### Model The new source's id and the file name Google stored, with `status` `preparing`: poll [GET /notebooks/`notebook`](/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks-notebook) until it is `ready`. <details markdown="block" class="model-details"> <summary>The new file source, field by field</summary> ```typescript { // TypeScript, all fields are optional notebook: string // user:<id>-<email>-notebook:<uuid> source: string // user:<id>-<email>-source:<notebook uuid>:<source uuid> title: string // the file name Google stored status: 'preparing' // poll GET /notebooks/{notebook} until the source is ready } ``` </details> ##### Examples **Curl** ``` bash NOTEBOOK="user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55" curl -X POST "https://api.useapi.net/v1/gemini-notebook/sources/upload?notebook=$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$NOTEBOOK")&name=apollo11-wikipedia.pdf" \ -H "Authorization: Bearer …" \ -H "Content-Type: application/pdf" \ --data-binary "@apollo11-wikipedia.pdf" ``` **JavaScript** ``` javascript import { readFile } from 'node:fs/promises'; const token = "API token"; const notebook = "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55"; const name = "apollo11-wikipedia.pdf"; const qs = new URLSearchParams({ notebook, name }); const response = await fetch(`https://api.useapi.net/v1/gemini-notebook/sources/upload?${qs}`, { method: "POST", headers: { "Authorization": `Bearer ${token}`, "Content-Type": "application/pdf" }, body: await readFile(name) }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" notebook = "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55" name = "apollo11-wikipedia.pdf" with open(name, "rb") as f: response = requests.post( "https://api.useapi.net/v1/gemini-notebook/sources/upload", params={"notebook": notebook, "name": name}, headers={"Authorization": f"Bearer {token}", "Content-Type": "application/pdf"}, data=f.read() ) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-sources === Document URL: https://useapi.net/docs/api-gemini-notebook-v1/post-gemini-notebook-sources --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> sources description: "Add web pages, YouTube videos, pasted text, Google Drive files and Google Play Books ebooks to a notebook via POST sources in the useapi.net Gemini Notebook API." parent: Gemini Notebook API nav_order: 300 permalink: /docs/api-gemini-notebook-v1/post-gemini-notebook-sources --- ## Add sources September 29, 2026 (November 16, 2026) --- Add sources to a notebook: web pages, YouTube videos, pasted text, files from Google Drive and ebooks from the account's Google Play Books library, in one call. Sources are what [chat](/docs/api-gemini-notebook-v1/post-gemini-notebook-chat) answers from and what [Studio artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts) are generated from. To add a file (PDF, Word, PowerPoint, EPUB, Markdown, text, CSV, audio, video or an image) use [POST /sources/upload](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources-upload). Create the notebook first with [POST /notebooks](/docs/api-gemini-notebook-v1/post-gemini-notebook-notebooks). Google processes every new source before it can be used. The response carries each source's current `status`, and [GET /notebooks/`notebook`](/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks-notebook) shows it later. Chat and Studio use only sources whose `status` is `ready`. How many sources a notebook can hold depends on the account's Google plan. [GET /accounts/`email`](/docs/api-gemini-notebook-v1/get-gemini-notebook-accounts-email) shows it as `limits.sourcesPerNotebook`. > **https://api.useapi.net/v1/gemini-notebook/sources** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "urls": [ "https://en.wikipedia.org/wiki/Apollo_11", "https://www.nasa.gov/mission/apollo-11/", "https://www.youtube.com/watch?v=xUcYQ7slmRw" ], "text": "Three minutes before landing, Eagle's computer raised a 1202 alarm...", "title": "Why Apollo 11 almost did not land" } ``` - `notebook` is **required**, the notebook id returned by [POST /notebooks](/docs/api-gemini-notebook-v1/post-gemini-notebook-notebooks) or [GET /notebooks](/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks). The id names its account, so no `email` is needed. - `urls` is optional, an array of `1` to `50` `http(s)` URLs. A URL on `youtube.com` (any subdomain) or `youtu.be` is added as a YouTube source, any other URL as a web page. Google reads a YouTube video from its captions. A video with no captions at all, which happens with some official music videos, ends with `status: "error"` and its URL as the title, and Google gives no reason (September 2026). Upload the audio or video file with [POST /sources/upload](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources-upload) instead, and Google transcribes it. With `multipart/form-data`, `urls` carries a single URL. - `text` is optional, pasted text added as one text source. Maximum length: `500,000` characters. - `title` is optional, the title of the `text` source. Sending `title` without `text` returns `400`. Default: `Pasted text`. Maximum length: `200` characters. - `drive` is optional, an array of `1` to `50` Google Drive files, each `{ fileId, mimeType, name }`. All three fields are required. `fileId` is the Drive file id, `mimeType` its MIME type, and `name` (up to `200` characters) becomes the source's title. A Google Doc has the MIME type `application/vnd.google-apps.document` and is added as kind `google_docs`. A `.docx` or `.pptx` from Drive is added as kind `drive`. Send the file's exact MIME type: in our tests a Google Doc sent with the `.docx` type was added as a plain `drive` file that cannot sync, and a generic type such as `application/octet-stream` left the source stuck in `preparing`. The account must be able to open the file in its Google Drive, otherwise the API answers `409`. `drive` needs a JSON body. Example: `[{ "fileId": "1Qx7Lm2VtR8pKc4NwE9bYs3HfJ6uGdA0zT5iOv1eWnXk", "mimeType": "application/vnd.google-apps.document", "name": "Apollo 11 landing notes" }]` - `books` is optional, an array of `1` to `20` Google Play Books ids from [GET /sources/books](/docs/api-gemini-notebook-v1/get-gemini-notebook-sources-books). Each book is added as one source of kind `book` holding the whole ebook. The account must own the book, and its publisher must allow it (`addable: true`). A book that is not in the account's library returns `404`, and a book Google does not allow returns `422`. In both cases nothing is added. Example: `["-OQ2q5JqOdEC"]` Provide `urls`, `text`, `drive`, `books` or any combination. Books are added after the other sources. If a book fails after other sources were added, the error message lists what was already added. A Drive source is a copy of the file as it was when added. [GET /sources/`source`](/docs/api-gemini-notebook-v1/get-gemini-notebook-sources-source) shows whether it still matches the file (`inSync`), and [POST /sources/sync](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources-sync) re-imports it after a change. ##### Source kinds and statuses Every source object carries a `kind` (what Google made of it) and a `status`. The same values appear on sources added via [POST /sources/upload](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources-upload) and listed by [GET /notebooks/`notebook`](/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks-notebook). | kind | Source | |---|---| | `web` | Web page URL | | `youtube` | YouTube video URL | | `text` | Pasted `text`, or an uploaded `.txt` file | | `pdf` | PDF file | | `docx` | Word document | | `pptx` | PowerPoint presentation | | `epub` | EPUB e-book | | `markdown` | Markdown file, a note converted with [POST /notes/source](/docs/api-gemini-notebook-v1/post-gemini-notebook-notes-source), or a Deep Research report added with [POST /research/import](/docs/api-gemini-notebook-v1/post-gemini-notebook-research-import) | | `csv` | CSV file | | `media` | Audio or video file (e.g. `.mp3`, `.mp4`) | | `image` | Image file (e.g. `.jpg`) | | `google_docs` | A Google Doc from Google Drive (`drive` parameter) | | `drive` | A Google Drive file that is not a Google Doc, such as a `.docx` or `.pptx` (`drive` parameter) | | `book` | An ebook from the account's Google Play Books library (`books` parameter) | A kind Google adds later is returned as `kind<N>`, with Google's own number. | status | Meaning | |---|---| | `preparing` | The file was received and is waiting to be processed. New uploads start here. | | `processing` | Google is reading the source. | | `ready` | The source can be used by chat and Studio. | | `error` | Google could not process the source. | An unrecognised status is returned as `status<N>`. ##### Responses **201** **201 Created** One entry per source added. ```json { "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "sources": [ { "source": "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:c1182943-b7f0-4e89-82bc-8b3614cfb78f", "title": "Apollo 11 - Wikipedia", "kind": "web", "status": "ready", "words": 25492, "url": "https://en.wikipedia.org/wiki/Apollo_11", "created": "2026-09-27T23:24:43.000Z" }, { "source": "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:f8e48390-9349-485d-b816-38649a28aa5d", "title": "Apollo 11 - NASA", "kind": "web", "status": "ready", "words": 2639, "url": "https://www.nasa.gov/mission/apollo-11/", "created": "2026-09-27T23:24:43.000Z" }, { "source": "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:9732772d-0111-447b-ba78-9eec2c1c2ffe", "title": "A New Look at the Apollo 11 Landing Site", "kind": "youtube", "status": "ready", "words": 13, "url": "https://www.youtube.com/watch?v=xUcYQ7slmRw", "created": "2026-09-27T23:24:43.000Z" }, { "source": "user:12345-user@example.com-source:d02c903b-17f8-4241-a263-2be9e7359d55:bd69e802-65bf-4ee7-9088-d9ee5724204c", "title": "Why Apollo 11 almost did not land", "kind": "text", "status": "ready", "words": 90, "created": "2026-09-27T23:24:43.000Z" } ] } ``` **400** **400 Bad Request** A missing or malformed parameter, nothing to add, or `title` without `text`. ```json { "error": "Provide urls, text, drive and/or books", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The notebook id was issued to a different API token. ```json { "error": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55 does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** The account named in the notebook id is no longer configured, Google no longer has the notebook, or a `books` id is not in the account's Google Play Books library. ```json { "error": "Account user@example.com of user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55 is not configured", "code": 404 } ``` **409** **409 Conflict** A `drive` file the account cannot open: it is not in the account's Google Drive and not shared with it. ```json { "error": "Google refused the request in the item's current state (izAoDd grpc 9)", "code": 409 } ``` **422** **422 Unprocessable Content** A `books` id Google does not allow as a source. [GET /sources/books](/docs/api-gemini-notebook-v1/get-gemini-notebook-sources-books) lists it with `addable: false`. ```json { "error": "Google does not allow these books as sources: Hfn4AAAAQBAJ \"The Raven (Illustrated)\" (the publisher opted out)", "code": 422 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook", "code": 596 } ``` **503** **503 Service Unavailable** Google is temporarily unavailable or is challenging our network. Retry in a few minutes. A `502` means Google answered with an unexpected error. ```json { "error": "Google is temporarily unavailable (izAoDd grpc 14), please retry", "code": 503 } ``` ##### Model The notebook id and each new source with its id, title, `kind` and current `status`. <details markdown="block" class="model-details"> <summary>The notebook's new sources, field by field</summary> ```typescript { // TypeScript, all fields are optional notebook: string // user:<id>-<email>-notebook:<uuid> sources: { source: string // user:<id>-<email>-source:<notebook uuid>:<source uuid> title: string kind: string // see Source kinds above status: string // preparing | processing | ready | error words?: number // word count, once Google has read the source url?: string // web page or YouTube URL mimeType?: string // file sources driveFileId?: string // Google Drive sources: the Drive file id created?: string // ISO 8601 }[] } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/gemini-notebook/sources" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "notebook": "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55", "urls": ["https://en.wikipedia.org/wiki/Apollo_11", "https://www.youtube.com/watch?v=xUcYQ7slmRw"], "text": "Three minutes before landing, Eagle'\''s computer raised a 1202 alarm...", "title": "Why Apollo 11 almost did not land" }' ``` **JavaScript** ``` javascript const token = "API token"; const notebook = "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55"; const apiUrl = "https://api.useapi.net/v1/gemini-notebook/sources"; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ notebook, urls: ["https://en.wikipedia.org/wiki/Apollo_11", "https://www.youtube.com/watch?v=xUcYQ7slmRw"], text: "Three minutes before landing, Eagle's computer raised a 1202 alarm...", title: "Why Apollo 11 almost did not land" }) }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" notebook = "user:12345-user@example.com-notebook:d02c903b-17f8-4241-a263-2be9e7359d55" apiUrl = "https://api.useapi.net/v1/gemini-notebook/sources" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } data = { "notebook": notebook, "urls": ["https://en.wikipedia.org/wiki/Apollo_11", "https://www.youtube.com/watch?v=xUcYQ7slmRw"], "text": "Three minutes before landing, Eagle's computer raised a 1202 alarm...", "title": "Why Apollo 11 almost did not land" } response = requests.post(apiUrl, headers=headers, json=data) print(response, response.json()) ``` === URL: https://useapi.net/docs/start-here/setup-google-flow === Document URL: https://useapi.net/docs/start-here/setup-google-flow --- layout: default title: Setup Google Flow description: "How to set up Google Flow for the useapi.net API — connect your account and start generating via the API." parent: Start Here nav_order: 205 --- # <img src="/assets/images/google-flow.svg" style="height:1em;vertical-align: middle;" alt=""> Google Flow November 17, 2025 (November 6, 2026) ## Table of contents Approximately 5 minutes to complete setup steps. --- > This is the setup guide for [Google Flow API](/docs/api-google-flow-v1). An active [Google](https://accounts.google.com) account and a [useapi.net subscription](/docs/subscription) are required for the API to work. ### Automated setup (recommended) Use our guided browser setup to configure your account automatically — no DevTools or cookie copying needed. Enter your API token, log in with Google in the remote browser, and your account is ready. [Open automated setup](/assets/setup-browser/google-flow.html) Prefer manual setup? Continue with the steps below. --- [Google Flow](https://flow.google.com) makes videos with sound using [Veo 3.1](https://aistudio.google.com/models/veo-3) and Omni Flash ([Omni 1.2](https://cloud.google.com/blog/products/ai-machine-learning/gemini-omni-1-2-flash-generally-available) and [Omni 1.1](https://deepmind.google/models/model-cards/gemini-omni-flash/)), and images using [Nano Banana Pro](https://deepmind.google/models/gemini-image/pro/), Nano Banana 2.1 and [Nano Banana 2 Lite](https://deepmind.google/models/gemini-image/flash-lite/) ([all models](/docs/api-google-flow-v1#models)). ### Use a dedicated Gmail account **Use a dedicated Gmail account for this API — do NOT use your personal Gmail account.** When creating a new account: 1. Enable [2-Step Verification](https://support.google.com/accounts/answer/185839) with [Microsoft Authenticator](https://www.microsoft.com/en-us/security/mobile-authenticator-app), and save the backup codes. Avoid Google Authenticator — it backs its codes up to the Google account it is signed into, which would link this dedicated account to your personal one. 2. Keep your sign-ins consistent. If you use a VPN, pick one region and stay with it rather than switching locations — an account that appears from different places in a short time is what Google treats as suspicious. The automated setup above signs in from a US browser, so it needs no VPN on your side. ### If Google asks for a phone number Occasionally Google shows a "Verify it's you" page and asks for a phone number to text a code to, even on an account that never had one. Any number that can receive SMS works. It does not have to be one already on the account. If you'd rather not use your personal number, get an inexpensive prepaid line just for this — for example a [Tello](https://tello.com) eSIM on its cheapest plan with texts (about $5/month, activated online). Tello's guide [How can I activate my Tello eSIM?](https://tello.com/help_center/how-can-i-activate-my-tello-esim) has the steps. The phone must be carrier-unlocked and support eSIM, and Tello needs you to be in the United States when you first activate the line. Install it on any phone, receive the code there, and keep the line active so you can pass future checks. Google limits how many accounts one number can verify, and it can treat accounts verified with the same number as related. Avoid online SMS-rental and "free virtual number" services. Google rejects most of them, and a rejected number can make the lock harder to clear. ### If Google asks you to scan a QR code After the password and the 2-Step Verification code, Google sometimes adds one more page, "Verify your info to continue", with a QR code. Google wants to check a phone: scan the code with the phone's camera, tap the link, follow the steps on the phone, then switch back to the computer. It shows up mostly on accounts Google treats as risky, for example when many accounts are signed in within a short time, and an authenticator app on the account does not prevent it. - To skip the phone, choose `Try another way` below the QR code and pick what Google lists: a Microsoft Authenticator code, a backup code, or a text message to a phone number (see the phone number section above). - If Google offers no other option, close the setup and try that account again later, or add a different account. - Add accounts one at a time, spread over the day, rather than many within an hour. - Have the authenticator app and the backup codes ready before you start. The setup browser closes if the sign-in isn't finished within a few minutes. ### Manual setup **Do NOT use Google Chrome.** Google's integration with Chrome interferes with cookie extraction. Use [Brave](https://brave.com/) or [Ungoogled Chromium](https://github.com/ungoogled-software/ungoogled-chromium) instead. You sign in to Google Flow, then copy the `https://accounts.google.com` cookies from Developer Tools and paste them into the `cookies` field below. #### Start a clean browser with the setup script (recommended) Our [Google Account Setup](https://github.com/useapi/google-account-setup) scripts for Windows, macOS and Linux give you a clean, single-use Google sign-in. They open Brave in a brand-new, empty profile, wait while you sign in and copy the cookies, and delete that profile the moment you close the browser. That takes care of three things: - A fresh, empty profile, with no other Google accounts, history or extensions. It runs separately from your normal Brave, which can stay open. - No device-bound sessions. Brave starts with `--disable-features=EnableBoundSessionCredentials,DeviceBoundSessions`, so the cookies also work outside your computer. - The profile is deleted when you close the browser. That sign-in can never be opened in a browser again, so only the API uses it. The scripts read nothing and send nothing — you copy the cookies by hand, exactly as in the manual steps below. Each script is short, so read it before you run it. 1. Install [Brave](https://brave.com/) (on Linux, Chromium works too). 2. Get the script for your system from the sections below: copy it into a file, or download it from [GitHub](https://github.com/useapi/google-account-setup). 3. Run it and choose from the menupick the service from the menu. 4. In the Brave window, sign in to your dedicated Google account, copy the cookies named above (the script names them too), and paste them into the form on this page. 5. When the account shows as added, close every window of that Brave (on a Mac, quit it with `Cmd+Q`). Keep the script's window open until it reports the profile was deleted, and do not sign in to the same Google account in any other browser afterwards. <details markdown="block"> <summary>Windows — install script</summary> [Download it from GitHub](https://github.com/useapi/google-account-setup/blob/main/google-account-setup-windows.cmd), or open Notepad, paste the script below, and save it as `google-account-setup-windows.cmd` (in the Save dialog set `Save as type` to `All Files` so it is not saved as `.txt`). Double-click the saved file. If Windows shows `Windows protected your PC`, click `More info` then `Run anyway`. ```bat ``` </details> <details markdown="block"> <summary>macOS — install script</summary> [Download it from GitHub](https://github.com/useapi/google-account-setup/blob/main/google-account-setup-mac.command) and run it with `bash ~/Downloads/google-account-setup-mac.command`, or open `Terminal` (Applications → Utilities), paste the script below into a file with `nano ~/google-account-setup-mac.command`, press `Ctrl+O` then `Enter` to save and `Ctrl+X` to exit, then run it with `bash ~/google-account-setup-mac.command`. ```bash ``` </details> <details markdown="block"> <summary>Linux / WSL — install script</summary> [Download it from GitHub](https://github.com/useapi/google-account-setup/blob/main/google-account-setup-linux.sh), or save the script below to `~/google-account-setup-linux.sh` (for example with `nano ~/google-account-setup-linux.sh`), then run it with `bash ~/google-account-setup-linux.sh`. On WSL this needs Windows 11 (WSLg) for the browser window — otherwise run the Windows script instead. ```bash ``` </details> #### Or start the browser by hand Chromium browsers on Windows and Mac now bind a Google sign-in to the device (Google's Device Bound Session Credentials). Cookies copied from a bound session are refused anywhere else, and the API answers ``, so the account cannot be added or stops working. The browser's own flags page does not turn this off (Google overrides it), but a command-line switch does. The [automated setup](#automated-setup-recommended) is not affected. 1. Quit Brave completely, including any instance left in the system tray (check Task Manager for `brave.exe`, on a Mac use `Cmd+Q`). A running Brave ignores the switch. 2. Start it from the Run box (`Win+R`) with this command, which opens a private window with no cookies and without device-bound sessions: ``` "C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe" --incognito --disable-features=EnableBoundSessionCredentials,DeviceBoundSessions ``` On a Mac, run the same switches from Terminal: ``` open -na "Brave Browser" --args --incognito --disable-features=EnableBoundSessionCredentials,DeviceBoundSessions ``` Ungoogled Chromium takes the same `--disable-features` switch. Keep this window open for the steps below. #### Sign in to Google Flow Navigate to [https://flow.google.com](https://flow.google.com) and click `Create with Google Flow` <span style="color: red;">`1`</span>. ![](/assets/images/google-flow-setup-1.png) Sign in with your dedicated Gmail account <span style="color: red;">`1`</span>. ![](/assets/images/google-flow-setup-2.png) Enter your password, then the 2-Step Verification code <span style="color: red;">`1`</span>. Google names Google Authenticator here whichever authenticator app holds the code. **You MUST check `Don't ask again on this device`** <span style="color: red;">`2`</span> — skipping it will break the API session. ![](/assets/images/google-flow-setup-3.png) Once signed in you see Google Flow. Click `New project` <span style="color: red;">`1`</span> to open a project, and keep it open for the next step. ![](/assets/images/google-flow-setup-4.png) #### Copy the `https://accounts.google.com` cookies 1. Open Developer Tools: right-click anywhere on the page and select `Inspect` (or press `F12`), then open the `Application` tab <span style="color: red;">`1`</span> 2. Under `Cookies`, select `https://accounts.google.com` <span style="color: red;">`2`</span> 3. Click in the cookie table and select all cookies (`Ctrl+A`) <span style="color: red;">`3`</span> 4. Copy them (`Ctrl+C`, or right-click and `Copy`) <span style="color: red;">`4`</span>, and paste them into the `cookies` field below ![](/assets/images/google-flow-setup-5.png) Before you paste, look for `__Secure-1PSIDRTS` in what you copied. If it is there, the session is device-bound and will be refused: close every Brave window and start again with the command above. ### Verify and add account Use the form below to verify your cookies and add your Google Flow account. Select **Add Account** to complete setup, or **Verify** to test your cookies first. You should receive response `200` if successful. You can also use [POST /accounts](/docs/api-google-flow-v1/post-google-flow-accounts) directly. Right after adding the account, close the private Brave window. Do NOT sign out of Google first — signing out ends the session the API now uses. **The API now manages this Google account session.** Do NOT access this Google account via AI Studio or Google Flow directly (browser or any other means). Using the same account through both the API and direct access will break the session and require you to redo this entire setup. <script> async function apiTestAccountGoogleFlow(addAccount) { data = { method: 'POST', headers: { 'Authorization': `Bearer ${document.getElementById('post-accounts-GoogleFlow-api_token').value}`, 'Content-Type': 'application/json' } }; let cookies = document.getElementById(`post-accounts-GoogleFlow-cookies`)?.value; const body = { cookies }; if (!addAccount) body.dryRun = true; data.body = JSON.stringify(body); await apiExecute(`https://api.useapi.net/v1/google-flow/accounts`, 'post-accounts-GoogleFlow', data); } </script> <form id="post-accounts-GoogleFlow" onsubmit="apiTestAccountGoogleFlow(document.getElementById('post-accounts-GoogleFlow-action').value === 'add'); return false;" class="input-form"> <div class="input-field"> <div class="input-field-row"> <label for="post-accounts-GoogleFlow-api_token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="post-accounts-GoogleFlow-api_token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> <label for="post-accounts-GoogleFlow-cookies"><span>cookies</span> <textarea id="post-accounts-GoogleFlow-cookies" class="input-element" rows="10" required aria-required="true" style="resize: both;"></textarea> </label> <label for="post-accounts-GoogleFlow-action"><span>action</span> <select id="post-accounts-GoogleFlow-action" class="input-element"> <option value="verify">Verify — test cookies only</option> <option value="add">Add Account — required to complete setup</option> </select> </label> </div> <button id="post-accounts-GoogleFlow-button" class="btn btn-primary fs-3" type="submit">Go</button> </div> </form> <div id="post-accounts-GoogleFlow-response" class="response-placeholder visible-false"></div> ### Configure Captcha Providers Image and video generation requires reCAPTCHA v3 Enterprise solving. **Users receive 300 free captcha credits** when adding their first Google Flow account. These credits are used automatically, so you can start generating images and videos right away without configuring any provider. Check your remaining credits via [GET /accounts/captcha-providers](/docs/api-google-flow-v1/get-google-flow-accounts-captcha-providers). After free credits are exhausted, you must configure at least one provider's API key before using [POST /images](/docs/api-google-flow-v1/post-google-flow-images), [POST /images/upscale](/docs/api-google-flow-v1/post-google-flow-images-upscale), or [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos). **Supported Providers:** | Provider | Cost per 1K | Avg Solve Time | Reports Back | Website | |----------|-------------|----------------|:------------:|---------| | AntiCaptcha | ~$2.00 | ~8-12s | [Yes](https://anti-captcha.com/apidoc/methods/reportCorrectRecaptcha) | [anti-captcha.com](https://anti-captcha.com/) | | CapSolver | ~$3.00 | ~8-12s | [Yes](https://docs.capsolver.com/en/api/) | [capsolver.com](https://www.capsolver.com/) — use promo code `useapi` for 8% discount | | EzCaptcha | ~$2.50 | ~2-5s | No | [ez-captcha.com](https://www.ez-captcha.com/) | | YesCaptcha | varies | ~8-12s | No | [yescaptcha.com](https://yescaptcha.com/) | | CapMonster | ~$1.50 | ~10-30s | [Incorrect only](https://docs.capmonster.cloud/docs/api/bad-tokens/) | [capmonster.cloud](https://capmonster.cloud/) | | SolveCaptcha | ~$0.80 | ~30-60s Slow | [Yes](https://solvecaptcha.com/captcha-solver-api) | [solvecaptcha.com](https://solvecaptcha.com/) | | 2Captcha | ~$2.99 | ~30-60s Slow | [Yes](https://2captcha.com/api-docs/report-correct) | [2captcha.com](https://2captcha.com/) | SolveCaptcha and 2Captcha typically take 30-60 seconds per solve versus ~2-12 seconds for the others. They work well as low-cost fallbacks but can increase request latency as primary providers. EzCaptcha solves in real time, in about 2–5 seconds, so a token Google rejects costs little time before the next provider takes over. Reports Back — providers that support solve-result reporting receive correct/incorrect feedback after each use, which improves token quality over time. If you have two or more captcha providers, most requests use the one Google is accepting best right now, with your second-best provider as a backup on the third try. `captchaOrder` only picks which providers to use and how many tries to make, not the order. We recommend adding at least two providers, for example AntiCaptcha and CapSolver, and ideally EzCaptcha too, so fewer captchas are rejected and you pay for fewer of them. How it works: [Provider order](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers#provider-order). **Setup Steps:** 1. Create an account with one or more providers above 2. Purchase credits and obtain your API key from the provider's dashboard 3. Configure your API key(s) using [POST /accounts/captcha-providers](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers) **Tips:** - Configure more than one provider. The API tries the best of them first and falls back to the next on a rejection, as described in [Provider order](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers#provider-order). - [GET /accounts/captcha-stats](/docs/api-google-flow-v1/get-google-flow-accounts-captcha-stats) shows how each provider is doing right now and which one the API currently puts first. - Each image/video generation attempt requires one captcha solve (~$0.80-$3.00 per 1,000 generations) ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/api-google-flow-v1/agent-demo === Document URL: https://useapi.net/docs/api-google-flow-v1/agent-demo --- layout: default title: Agent Live Demo nav_icon: play description: "Open the Google Flow Agent demo app: chat with Flow's agent live, see its images and videos inline, attach media, approve spending, browse the Library and set default models." parent: Google Flow API nav_order: 54 permalink: /docs/api-google-flow-v1/agent-demo --- ## Google Flow Agent Live Demo October 16, 2026 A complete Google Flow Agent chat client in plain HTML, CSS and JavaScript, running full screen on its own page and on phones. Paste your API token, press Connect and pick a Google Flow account. Chat with the agent as its answer streams in, see the images and videos it makes right in the conversation, attach your own media, approve what it wants to spend, and change its settings. Your token stays in the browser and goes only to api.useapi.net. <a href="/demos/google-flow/" class="btn btn-primary fs-5">Open the Google Flow agent demo</a> [Get the source on GitHub](https://github.com/useapi/google-flow-api/tree/main/demo): the same five small files, with no framework, no build step and no dependencies, and a README that maps every feature to its API call. The [Agent overview](/docs/api-google-flow-v1/agent) covers the API itself. Prefer an AI assistant? The hosted [Google Flow MCP server](/docs/api-google-flow-v1/mcp) gives Claude Code, Cursor and VS Code the same chat as 12 tools. ### Screenshots Taken on the live demo with a real account, with Nano Banana 2.1 for images and Veo 3.1 Lite for video. <img src="/assets/images/google-flow-agent-demo-1-new-chat.png" alt="New chat in the Google Flow Agent demo: a greeting, three starter cards and the message box" style="max-width:100%" loading="lazy"> *1. A new chat greets you and offers three starter cards.* <img src="/assets/images/google-flow-agent-demo-2-chat-results.webp" alt="A finished turn in the Google Flow Agent demo: three moodboard options as image tiles and the images inline under the agent's answer, the Steps toggle and the media panel" style="max-width:100%" loading="lazy"> *2. The agent's images appear inline, with Download and Use in next message. Its tool calls sit in the collapsed Steps toggle.* <img src="/assets/images/google-flow-agent-demo-3-approval.webp" alt="The Google Flow agent asks to spend 10 credits for one video, with Approve, Always approve and Reject" style="max-width:100%" loading="lazy"> *3. Before it spends credits, the agent asks for approval.* <img src="/assets/images/google-flow-agent-demo-4-full-size.webp" alt="Full-size view of a generated image with Use in next message and Download" style="max-width:100%" loading="lazy"> *4. Click a result to see it full size.* <img src="/assets/images/google-flow-agent-demo-5-attach.webp" alt="The Attach menu open, with a voice, a character and an earlier image attached above the message" style="max-width:100%" loading="lazy"> *5. Attach uploads, earlier images and videos, characters and voices, each with its @-mention.* <img src="/assets/images/google-flow-agent-demo-6-settings.png" alt="Agent settings in the demo: approval mode, instructions, and default models with their credits" style="max-width:100%" loading="lazy"> *6. Agent settings: approval, instructions, and the default image and video models.* <img src="/assets/images/google-flow-agent-demo-7-phone-dark.webp" alt="The Google Flow Agent demo on a phone in the dark theme, showing the chat with its images" style="width:300px;max-width:100%" loading="lazy"> *7. On a phone, in the dark theme.* ### What it does - Connect lists your Google Flow accounts with [GET /accounts](/docs/api-google-flow-v1/get-google-flow-accounts). A new chat greets you by your Google first name, read once per account from [GET /accounts/`email`](/docs/api-google-flow-v1/get-google-flow-accounts-email), and offers 3 starter cards picked at random from Flow's own 14, such as Brainstorm with me and Develop a storyboard. Clicking a card sends its label as your first message. - Chat streams the agent's answer live with [GET /agent/chats/`chatId`/stream](/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId-stream) and resumes with `Last-Event-ID` after a drop. It starts chats with [POST /agent/chats](/docs/api-google-flow-v1/post-google-flow-agent-chats), sends the next message with [POST /agent/chats/`chatId`/messages](/docs/api-google-flow-v1/post-google-flow-agent-chats-chatId-messages), lists chats with [GET /agent/chats](/docs/api-google-flow-v1/get-google-flow-agent-chats), opens one with [GET /agent/chats/`chatId`](/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId), renames it with [PATCH /agent/chats/`chatId`](/docs/api-google-flow-v1/patch-google-flow-agent-chats-chatId) and deletes it with [DELETE /agent/chats/`chatId`](/docs/api-google-flow-v1/delete-google-flow-agent-chats-chatId). The agent's thinking and tool calls sit in a collapsed Steps toggle, and the options it offers become buttons that send your choice. - Every image and video the agent makes shows inline, with its status while a video is queued. Click one to open it full size. Download saves it, and Use in next message attaches it to what you write next. An expired link is renewed with [GET /assets/`referenceId`](/docs/api-google-flow-v1/get-google-flow-assets-mediagenerationid). - The Attach menu uploads images from disk with [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email), and picks earlier images and videos with [GET /assets/media/`email`](/docs/api-google-flow-v1/get-google-flow-assets-media-email), characters with [GET /characters](/docs/api-google-flow-v1/get-google-flow-characters) and voices with [GET /voices](/docs/api-google-flow-v1/get-google-flow-voices). You can also drop or paste images. Each attachment gets its `@referenceImage_1` style name to `@`-mention in your message. - When the agent asks before it spends credits, a card shows the cost with Approve, Always approve and Reject, sent with [POST /agent/chats/`chatId`/approval](/docs/api-google-flow-v1/post-google-flow-agent-chats-chatId-approval). - The Library shows the account's images and videos project by project, the main project or the agent's own, with previews, upload, download and delete with [DELETE /assets/`email`](/docs/api-google-flow-v1/delete-google-flow-assets-email). - Agent settings reads and saves the approval mode, up to 3 instructions and the default image and video models with [GET](/docs/api-google-flow-v1/get-google-flow-agent-settings) and [PUT /agent/settings](/docs/api-google-flow-v1/put-google-flow-agent-settings). The model lists come from the models the account's Google plan has, with what its cheapest generation costs. === URL: https://useapi.net/docs/api-google-flow-v1/agent === Document URL: https://useapi.net/docs/api-google-flow-v1/agent --- layout: default title: Agent Overview nav_icon: bot seo_title: "Google Flow Agent API: Chat with Flow's Agent Through REST" description: "Chat with Google Flow Agent through the useapi.net Google Flow API: send messages with images, videos, voices and characters, approve spending, stream replies and collect media." parent: Google Flow API nav_order: 52 --- ## Google Flow Agent API October 16, 2026 (November 16, 2026) --- Google offers [Flow Agent](https://support.google.com/labs/answer/17093911) only inside the Flow web app, with no public API (as of November 2026). The useapi.net Google Flow Agent API is a third-party REST API that lets your code chat with Google Flow Agent, the creative assistant built into [Google Flow](https://flow.google.com), on your own Google account: send messages with images, videos, voices and characters, stream its replies, approve what it wants to spend, and collect the images and videos it makes. Chatting costs no credits, and works on every Google AI plan, including a free account. To see it working first, open the [live demo](/demos/google-flow/), a complete chat client on top of this API. The [Live Demo](/docs/api-google-flow-v1/agent-demo) page maps each of its features to the API call behind it, and its source is on GitHub in [google-flow-api/demo](https://github.com/useapi/google-flow-api/tree/main/demo). Prefer an AI assistant? The hosted [Google Flow MCP server](/docs/api-google-flow-v1/mcp) gives Claude Code, Cursor and VS Code the same chat as 12 tools. Tutorial: [How to Chat with Google Flow Agent via the Google Flow API](/docs/articles/google-flow-agent-chat), one real chat step by step with curl, from the brief to the approval, the media and a rejected revision. {% include lang-switch.html mode="hub" key="google-flow-agent-chat" %} The agent runs on Google's side and keeps the whole conversation there. You can come back to a chat hours or days later and it still has the full context. Chats you start through the API show up in the Flow web app, and chats started in the web app show up in the API when they are in the same project. The agent plans, writes, generates and edits images and videos, extends videos, describes media you attach, and organizes the project's media into collections when you ask it to. It picks its own tools and models, guided by the project's [instructions and defaults](#project-instructions-and-defaults). ### How a chat works 1. Start a chat with [POST /agent/chats](/docs/api-google-flow-v1/post-google-flow-agent-chats). It answers `202` with a `chatId` once Google has accepted the turn. 2. Follow the agent live with [GET /agent/chats/`chatId`/stream](/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId-stream), or read the chat at any time with [GET /agent/chats/`chatId`](/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId), or get each turn posted to your `replyUrl` when it ends. 3. When the agent wants to spend credits, it stops and asks. Answer within about 4 minutes with [POST /agent/chats/`chatId`/approval](/docs/api-google-flow-v1/post-google-flow-agent-chats-chatId-approval), and the same turn goes on. 4. Send the next message with [POST /agent/chats/`chatId`/messages](/docs/api-google-flow-v1/post-google-flow-agent-chats-chatId-messages). 5. Collect the media. Images are ready when the turn ends. Videos usually finish a minute or two later: the stream sends a `media` event for each one, and GET shows its status and link. A turn is one message from you and everything the agent does in reply. A chat runs one turn at a time. ### Endpoints | Endpoint | What it does | |---|---| | [POST /agent/chats](/docs/api-google-flow-v1/post-google-flow-agent-chats) | Start a chat with a message and optional references | | [POST /agent/chats/`chatId`/messages](/docs/api-google-flow-v1/post-google-flow-agent-chats-chatId-messages) | Send the next message | | [POST /agent/chats/`chatId`/approval](/docs/api-google-flow-v1/post-google-flow-agent-chats-chatId-approval) | Approve or reject the agent's request to spend credits | | [GET /agent/chats/`chatId`/stream](/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId-stream) | Follow the chat live over Server-Sent Events, resumable | | [GET /agent/chats/`chatId`](/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId) | Read the chat: every turn, the agent's messages, media with links, and its state | | [GET /agent/chats](/docs/api-google-flow-v1/get-google-flow-agent-chats) | List an account's chats, including ones started in the Flow web app | | [PATCH /agent/chats/`chatId`](/docs/api-google-flow-v1/patch-google-flow-agent-chats-chatId) | Rename a chat | | [DELETE /agent/chats/`chatId`](/docs/api-google-flow-v1/delete-google-flow-agent-chats-chatId) | Delete a chat's history (the media stay) | | [GET /agent/settings](/docs/api-google-flow-v1/get-google-flow-agent-settings) | Read the project's approval mode, instructions and default models, and the models the account's plan has with their credits | | [PUT /agent/settings](/docs/api-google-flow-v1/put-google-flow-agent-settings) | Change them | All routes are under `https://api.useapi.net/v1/google-flow/agent`. They use your existing [Google Flow accounts](/docs/api-google-flow-v1/post-google-flow-accounts) and [captcha providers](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers), with nothing new to set up. ### Credits and approvals Chatting with the agent costs no Flow credits. The images and videos it generates cost the usual Flow price, the same as [POST /images](/docs/api-google-flow-v1/post-google-flow-images) and [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos). Each project has an approval mode: - `ask` (the default): before it spends credits, the agent stops and shows the cost, for example `cost: 10` for one 8-second Veo 3.1 Lite video. The chat's status is `waiting_approval` until you answer with `approve`, `always` or `reject`, and the turn goes on. Since Google changed Flow Agent on November 10, 2026, it takes an answer only while the turn that asked is still open, and it closes an unanswered request about 5 minutes after asking. Answer within about 4 minutes, or send the message again after it expires. - `auto`: the agent spends without asking. Answering an approval with `always`, or setting `approval: "auto"` with [PUT /agent/settings](/docs/api-google-flow-v1/put-google-flow-agent-settings), switches the project to it. Choose it if you don't want to answer requests at all. Each turn uses one captcha, the same as a generation request. The agent works on every Google AI plan, including a free account. What it can generate follows the account's plan, the same as [POST /images](/docs/api-google-flow-v1/post-google-flow-images) and [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos). ### References and @-mentions Attach images, a video, voices and characters to any message with the same parameters and `@`-mention syntax as [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos): up to 7 `referenceImage_N`, 1 `referenceVideo_1`, 5 `referenceAudio_N` and 7 `character_N`. See [POST /agent/chats](/docs/api-google-flow-v1/post-google-flow-agent-chats#request-body) for the details. Everything the agent makes comes back with a `referenceId`. Use it in [POST /images](/docs/api-google-flow-v1/post-google-flow-images), [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) and in your next agent message. ### Project, instructions and defaults Every chat lives in a Flow project. Unless you pass `projectId`, the API uses a dedicated project per account, created on the account's first chat and named like `My Agents Work Fri, Oct 16`. Keeping agent chats there keeps them apart from your other Flow media. Pass `projectId` (from [GET /assets/projects/`email`](/docs/api-google-flow-v1/get-google-flow-assets-projects-email)) to chat in another project. Each project has its own agent settings, read with [GET /agent/settings](/docs/api-google-flow-v1/get-google-flow-agent-settings) and changed with [PUT /agent/settings](/docs/api-google-flow-v1/put-google-flow-agent-settings): - the approval mode, `ask` or `auto` - up to 3 standing instructions the agent follows in every chat of the project, each with optional reference images - the default image model, aspect ratio and number of images - the default video model, aspect ratio and number of videos The agent uses the defaults whenever a message does not say otherwise. [GET /agent/settings](/docs/api-google-flow-v1/get-google-flow-agent-settings) also lists the image and video models the account's Google plan has, with what its cheapest generation costs, and the defaults are picked from that list. ### Limits - One turn at a time per chat. Sending while a turn runs answers `409`. - At most 3 running turns per account. The next one answers `429` with `Retry-After`. - Google limits how many agent messages an account can send per day and does not publish the number. When an account reaches it, the API answers `429` for that account until midnight UTC. Use another account until then. - A turn can run for up to 10 minutes, Google's own limit. ### Media links Media links in `url` point to Google and expire about 6 hours after they are issued. Read the chat again with [GET /agent/chats/`chatId`](/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId) for fresh links, or get a fresh link for one item from [GET /assets/`mediaGenerationId`](/docs/api-google-flow-v1/get-google-flow-assets-mediagenerationid) with its `referenceId`. ### Errors | Code | When | |---|---| | `400` | A parameter is missing or invalid, an `@`-mention has no matching parameter, or a reference belongs to another account. | | `401` | Invalid API token. | | `403` | The `chatId` belongs to another useapi.net user, or Google refused the turn for this Google account (`reason` `GOOGLE_ERROR`), for example because it treats the account as under 18. Retrying will not help. | | `404` | The chat was deleted or does not exist, the `projectId` is not a project of the account, or the account is not added. | | `409` | A turn is already running in the chat, a new message was sent while an approval waits, or nothing is waiting for approval (an approval more than about 4 minutes old has expired). Rename and delete also answer `409` while a turn runs. | | `429` | The account already runs 3 agent turns, or it reached Google's daily limit on agent messages. | | `502` | Google answered with an error or without a readable reply (`reason` `GOOGLE_ERROR` or `UNREADABLE_ANSWER`). The turn may have run: read the chat before you retry. | | `503` | Google refused every captcha for the turn (`reason` `CAPTCHA_FAILED`), your captcha provider failed, or Google Flow could not be reached. Nothing ran and nothing was charged. Retry. | | `504` | Google has not confirmed the turn yet, and it may still start. Read the chat before you send it again. | | `596` | The account's Google session is no longer valid. Add the account again with [POST /accounts](/docs/api-google-flow-v1/post-google-flow-accounts). | #### Turn errors After the `202`, a turn can still fail. The stream's `turn` event, `lastError` on [GET /agent/chats/`chatId`](/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId) and the `replyUrl` body carry its error as `{ code, message, httpStatus }`: | `code` | `httpStatus` | What happened | What to do | |---|---|---|---| | `INTERRUPTED` | `502` or `500` | The connection to Google broke during the turn. What the agent made so far is in the chat. | Read the chat before you send the message again. | | `GOOGLE_ERROR` | Google's status | Google ended the turn with an error. What the agent made so far is in the chat. A `403` means Google refused the turn before it ran, for example because it treats the Google account as under 18 (`PUBLIC_ERROR_USER_MINOR`). The `error` says why. | Read the chat before you retry. After a `403`, use another account. | | `UNREADABLE_ANSWER` | `502` | Google answered without a readable reply and may already have run the turn. | Read the chat before you retry. | | `TIMEOUT` | `504` | The turn ran past Google's 10-minute limit. What the agent made is in the chat. | Send a follow-up such as `continue`. | | `CAPTCHA_FAILED` | `503` | Google refused every captcha for the turn. Nothing ran and nothing was charged. | Send the message again. | | `AGENT_QUOTA` | `429` | The account reached Google's daily limit on agent messages. | Use another account, or wait until the next day (midnight UTC). | | `NOT_STARTED` | `503` or `500` | The turn was never sent to Google, so nothing ran and nothing was charged. The request that sent it answered with this status instead of `202`, and no `replyUrl` call follows. A `500` means agent turns are not set up on our server. | Send the message again. After a `500`, contact support@useapi.net. | A failed turn may already have started images or videos. They are listed in the chat with their own status, and generated media cost the usual Flow credits. Except after `CAPTCHA_FAILED` or `NOT_STARTED`, read the chat before you resend a failed turn. ### Usage stats Agent requests show in [GET account/stats](/docs/account-management/get-account-stats) with `bot=google-flow`. Each turn you send has a row with model `agent` (endpoint `post-chats` or `post-messages`) and a second row when it ends (endpoint `post-chats-finished` or `post-messages-finished`, status `completed`, `waiting_approval` or `failed`). An answered approval writes a row with model `agent-approval` (endpoint `post-approval`), and the turn it answered ends with its own second row. A stream shows, with model `agent-stream`, only when it fails. Other agent requests, such as reading or renaming a chat, show only when Google or useapi.net failed them. === URL: https://useapi.net/docs/api-google-flow-v1/delete-google-flow-accounts-email === Document URL: https://useapi.net/docs/api-google-flow-v1/delete-google-flow-accounts-email --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> accounts/`email` description: "Remove a Google Flow account from your configuration via DELETE accounts/email in the useapi.net Google Flow API v1, cancelling any scheduled refresh operations." parent: Google Flow API nav_order: 400 --- ## Delete Account Configuration November 17, 2025 (November 16, 2026) --- Delete a configured Google Flow account. This removes the account from your configuration and cancels any scheduled refresh operations. **Warning:** This action cannot be undone. You will need to reconfigure the account using [POST /accounts](/docs/api-google-flow-v1/post-google-flow-accounts) if you want to use it again. > **https://api.useapi.net/v1/google-flow/accounts/`email`** ### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Path Parameters - `email` is **required**. The email address of the Google Flow account to delete (URL-encoded if necessary). ### Responses **200** **200 OK** Account deleted successfully. ```json { "message": "Google Flow account john@gmail.com deleted" } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **404** **404 Not Found** Account not found or not configured. ```json { "error": "Google Flow account john@gmail.com not found", "code": 404 } ``` ### Model A message confirming that the account was deleted. <details markdown="block" class="model-details"> <summary>The confirmation, field by field</summary> ```typescript { message: string // the confirmation: Google Flow account <email> deleted } ``` </details> ### Examples **Curl** ``` bash curl -X DELETE \ -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v1/google-flow/accounts/john%40gmail.com" ``` **JavaScript** ``` javascript const token = 'YOUR_API_TOKEN'; const email = 'john@gmail.com'; const response = await fetch( `https://api.useapi.net/v1/google-flow/accounts/${encodeURIComponent(email)}`, { method: 'DELETE', headers: { 'Authorization': `Bearer ${token}` } } ); const result = await response.json(); console.log('Delete result:', result); ``` **Python** ``` python import requests from urllib.parse import quote token = 'YOUR_API_TOKEN' email = 'john@gmail.com' headers = {'Authorization': f'Bearer {token}'} response = requests.delete( f'https://api.useapi.net/v1/google-flow/accounts/{quote(email)}', headers=headers ) print('Delete result:', response.json()) ``` ### Try It <script> async function apiExecuteDeleteGoogleFlowAccountsEmail() { const tokenElement = document.getElementById('input-token'); const emailElement = document.getElementById('input-email'); const data = { method: 'DELETE', headers: { 'Authorization': `Bearer ${tokenElement.value}` } }; await apiExecute( `https://api.useapi.net/v1/google-flow/accounts/${encodeURIComponent(emailElement.value)}`, 'input', data ); } </script> <form id="input" class="input-form" onsubmit="return false;"> <div class="input-field"> <div class="input-field-row"> <label for="input-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="input-token" type="text" class="input-element" required aria-required="true"> </label> <label for="input-email"><span>email (required)</span> <input id="input-email" type="text" class="input-element" required aria-required="true" placeholder="john@gmail.com"> </label> </div> <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteDeleteGoogleFlowAccountsEmail()">Go</button> </div> </form> <div id="input-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-google-flow-v1/delete-google-flow-agent-chats-chatId === Document URL: https://useapi.net/docs/api-google-flow-v1/delete-google-flow-agent-chats-chatId --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> agent/chats/`chatId` description: "Delete a Google Flow Agent chat via DELETE agent/chats/chatId in the useapi.net Google Flow API: the conversation is removed, the images and videos it made stay in the project." parent: Google Flow API nav_order: 1480 --- ## Delete an agent chat October 16, 2026 (November 16, 2026) --- Delete a chat's conversation from Google. It disappears from [GET /agent/chats](/docs/api-google-flow-v1/get-google-flow-agent-chats) and the Flow web app, and its `chatId` stops working. The images and videos the agent made stay in the project. Delete them with [DELETE /assets/`email`](/docs/api-google-flow-v1/delete-google-flow-assets-email) if you want them gone too. A chat cannot be deleted while a turn runs in it. > **https://api.useapi.net/v1/google-flow/agent/chats/`chatId`** - `chatId` is **required**, URL-encoded in the path (it contains `:` and `@`), from [POST /agent/chats](/docs/api-google-flow-v1/post-google-flow-agent-chats) or [GET /agent/chats](/docs/api-google-flow-v1/get-google-flow-agent-chats). ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **204** **204 No Content** The chat was deleted. The response has no body. **400** **400 Bad Request** The path value is not a `chatId`. ```json { "error": "Path parameter chatId (not-a-chat-id) is not a chat id from POST /agent/chats or GET /agent/chats", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The `chatId` belongs to another useapi.net user. ```json { "error": "This chat belongs to another user", "code": 403 } ``` **404** **404 Not Found** The chat was already deleted, or its account is not added. ```json { "error": "Chat not found: it was deleted or never existed", "code": 404 } ``` **409** **409 Conflict** A turn is running in this chat. Delete it after the turn ends. ```json { "error": "A turn is running in this chat. Wait for it to finish", "code": 409 } ``` **503** **503 Service Unavailable** Google Flow could not be reached, and nothing happened. Retry shortly. ```json { "error": "Google Flow is not reachable right now and could not delete the chat. Retry", "code": 503 } ``` **596** **596 Session Error** Google rejected the account's session, and the API is re-verifying the account on its own: retry in about a minute. If Google signed the account out, the account keeps answering `596` and you get a reconnect email: add it again by following [Setup Google Flow](/docs/start-here/setup-google-flow). ```json { "error": "Google Flow account john@gmail.com Google rejected this account session (HTTP 401). We are automatically re-verifying it — please retry in about a minute. If the account was signed out, you will receive a reconnect email.", "code": 596 } ``` ##### Examples **Curl** ``` bash CHATID="c-u12345-email:john@gmail.com-project:f166200a-...-chat:2586b4d7-...-bot:google-flow" curl -X DELETE -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v1/google-flow/agent/chats/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$CHATID")" ``` **JavaScript** ``` javascript const token = 'YOUR_API_TOKEN' const chatId = 'chatId from POST /agent/chats' const response = await fetch(`https://api.useapi.net/v1/google-flow/agent/chats/${encodeURIComponent(chatId)}`, { method: 'DELETE', headers: { 'Authorization': `Bearer ${token}` } }) console.log(response.status) ``` **Python** ``` python import requests from urllib.parse import quote token = 'YOUR_API_TOKEN' chatId = 'chatId from POST /agent/chats' r = requests.delete( f'https://api.useapi.net/v1/google-flow/agent/chats/{quote(chatId, safe="")}', headers={'Authorization': f'Bearer {token}'}, ) print(r.status_code) ``` === URL: https://useapi.net/docs/api-google-flow-v1/delete-google-flow-assets-email === Document URL: https://useapi.net/docs/api-google-flow-v1/delete-google-flow-assets-email --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> assets/`email` description: "Permanently delete uploaded or generated media from a Google Flow account by mediaGenerationId, up to 100 per call, via DELETE assets/email in the useapi.net Google Flow API v1." parent: Google Flow API nav_order: 540 --- ## Delete Account Media September 1, 2026 (November 16, 2026) --- Permanently delete media from a Google Flow account, addressed by `mediaGenerationId`, up to 100 per call. **Warning:** this cannot be undone. The media is removed from the Google account itself, not from a useapi.net cache — there is no restore, and useapi.net keeps no copy to fall back on. Download anything you want to keep with [GET /assets/`mediaGenerationId`](/docs/api-google-flow-v1/get-google-flow-assets-mediagenerationid) *before* deleting it. The usual reason to reach for this is accumulated uploads. Images and videos you send with [POST /assets](/docs/api-google-flow-v1/post-google-flow-assets-email) stay on the account indefinitely, and nothing else removes them. List them with [GET /assets/media/`email`](/docs/api-google-flow-v1/get-google-flow-assets-media-email), which marks each entry with `likelyUpload`. ### Explicit ids only There is no wildcard, no "delete everything older than", and no project-wide purge. Every id you send has to have come from a listing you already read. This is deliberate. The action is irreversible on somebody's real Google account, and the blast radius of a filter that matches more than you meant is the whole account. ### Ids are validated before anything is deleted The whole batch is checked first — format, ownership, account and type — and a single bad id fails the entire call with nothing deleted. You never end up guessing which half of a batch went through. Ownership is enforced from the id itself: a `mediaGenerationId` encodes the useapi.net user it belongs to, so an id from another user is rejected with `403` before Google is contacted at all. > **https://api.useapi.net/v1/google-flow/assets/`email`** ### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Path Parameters - `email` is **required**, URL-encoded. The Google Flow account to delete from. Every id in the body must belong to this account — a mismatch is rejected with `400` rather than silently deleting from somewhere else. ### Request Body ``` json { "mediaGenerationIds": [ "user:12345-email:6a6f...-image:0115f3c1-...", "user:12345-email:6a6f...-video:a1d95d21-..." ], "projectId": "3a18acb1-2c6e-478b-bcec-2df19cb8edab" } ``` - `mediaGenerationIds` is **required**. A non-empty array of 1 to 100 ids, each of type `image` or `video`. Take them from [GET /assets/media/`email`](/docs/api-google-flow-v1/get-google-flow-assets-media-email), or from the `media[]` of any generation response. - `projectId` is optional and defaults to the project this account currently writes to. You rarely need it: media is resolved by its own id, so an asset listed under one project is deleted correctly whichever project you name. Set it only when the account has no project on file, where omitting it returns `400`. ### Responses **200** **200 OK** Google accepted the batch. ```json { "deleted": 2, "projectId": "3a18acb1-2c6e-478b-bcec-2df19cb8edab", "email": "john@gmail.com" } ``` `deleted` is how many ids the accepted batch carried, which is always the number you sent. It is not a count of records that turned out to exist — deleting an id that is already gone succeeds rather than failing. To confirm what an account now holds, re-read [GET /assets/media/`email`](/docs/api-google-flow-v1/get-google-flow-assets-media-email). **400** **400 Bad Request** Nothing is deleted for any of these. Fix the request and send it again. The body was missing or not valid JSON. ```json { "error": "Body must be JSON", "code": 400 } ``` `mediaGenerationIds` was absent, empty, or not an array. ```json { "error": "Body field mediaGenerationIds must be a non-empty array", "code": 400 } ``` An entry is not a string, or is an empty one. ```json { "error": "Body field mediaGenerationIds must contain non-empty strings", "code": 400 } ``` More than 100 ids in one call. Split the work into batches. ```json { "error": "Body field mediaGenerationIds accepts at most 100 ids, got 137", "code": 400 } ``` An entry could not be parsed as a `mediaGenerationId`. ```json { "error": "Invalid mediaGenerationId format: not-a-valid-ref-id", "code": 400 } ``` An id belongs to a different Google Flow account than the one in the path. Send it in a separate call naming that account. ```json { "error": "mediaGenerationId belongs to jane@gmail.com, not john@gmail.com", "code": 400 } ``` An id is a character or voice reference. Those have their own endpoints — [DELETE /characters/`ref`](/docs/api-google-flow-v1/delete-google-flow-characters-ref) and [DELETE /voices/`ref`](/docs/api-google-flow-v1/delete-google-flow-voices-ref). ```json { "error": "mediaGenerationId type must be 'image' or 'video', got 'character'", "code": 400 } ``` No `projectId` was given and the account has no project on file. ```json { "error": "Body field projectId is required (this account has no project on file)", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** One of the ids belongs to a different useapi.net user than the one identified by the `Authorization` token. Nothing is deleted, and Google is never contacted. ```json { "error": "Unauthorized access to user:99999 detected in mediaGenerationId", "code": 403 } ``` **404** **404 Not Found** The account named in the path is not configured for this token. List what is configured with [GET /accounts](/docs/api-google-flow-v1/get-google-flow-accounts). ```json { "error": "Google Flow account john@gmail.com not found", "code": 404 } ``` **596** **596 Session Error** Google rejected the account's session, and the API is re-verifying the account on its own: retry in about a minute. If Google signed the account out, the account keeps answering `596` and you get a reconnect email: add it again by following [Setup Google Flow](/docs/start-here/setup-google-flow). ```json { "error": "Google Flow account john@gmail.com Google rejected this account session (HTTP 401). We are automatically re-verifying it — please retry in about a minute. If the account was signed out, you will receive a reconnect email.", "code": 596 } ``` ### Model How many media ids the delete carried, with the project and the account it ran on. <details markdown="block" class="model-details"> <summary>The deletion result, field by field</summary> ```typescript { deleted: number // How many ids the accepted batch carried projectId: string // The project named in the request, or the account's current one email: string // Echo of the path parameter error?: string // Present only on error responses } ``` </details> ### Examples **Curl** ``` bash TOKEN='YOUR_API_TOKEN' EMAIL='john@gmail.com' ENCODED=$(printf %s "$EMAIL" | jq -sRr @uri) # Delete two specific assets curl --location --request DELETE \ "https://api.useapi.net/v1/google-flow/assets/$ENCODED" \ --header "Authorization: Bearer $TOKEN" \ --header 'Content-Type: application/json' \ --data '{ "mediaGenerationIds": [ "user:12345-email:6a6f...-image:0115f3c1-...", "user:12345-email:6a6f...-video:a1d95d21-..." ] }' # Or clear out uploads older than a cut-off, 100 at a time. # Read the listing first, eyeball it, and only then delete. CUTOFF='2026-01-01' curl -s -H "Authorization: Bearer $TOKEN" \ "https://api.useapi.net/v1/google-flow/assets/media/$ENCODED" \ | jq --arg cutoff "$CUTOFF" '[.media[] | select(.likelyUpload and .createTime != null and .createTime < $cutoff) | .mediaGenerationId]' > /tmp/stale.json echo "$(jq length /tmp/stale.json) uploads older than $CUTOFF" jq -c 'range(0; length; 100) as $i | .[$i:$i+100]' /tmp/stale.json | while read -r BATCH; do jq -n --argjson ids "$BATCH" '{mediaGenerationIds: $ids}' \ | curl -s --location --request DELETE \ "https://api.useapi.net/v1/google-flow/assets/$ENCODED" \ --header "Authorization: Bearer $TOKEN" \ --header 'Content-Type: application/json' \ --data @- echo done ``` **JavaScript** ``` javascript const token = 'YOUR_API_TOKEN'; const email = 'john@gmail.com'; const encoded = encodeURIComponent(email); const headers = { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' }; const listResp = await fetch( `https://api.useapi.net/v1/google-flow/assets/media/${encoded}`, { headers: { 'Authorization': `Bearer ${token}` } }); const { media } = await listResp.json(); const cutoff = '2026-01-01'; const stale = media .filter(m => m.likelyUpload && m.createTime && m.createTime < cutoff) .map(m => m.mediaGenerationId); console.log(`${stale.length} uploads older than ${cutoff}`); let removed = 0; for (let i = 0; i < stale.length; i += 100) { const batch = stale.slice(i, i + 100); const resp = await fetch( `https://api.useapi.net/v1/google-flow/assets/${encoded}`, { method: 'DELETE', headers, body: JSON.stringify({ mediaGenerationIds: batch }) }); if (!resp.ok) throw new Error(`${resp.status} ${await resp.text()}`); removed += (await resp.json()).deleted; } console.log(`Deleted ${removed}`); ``` **Python** ``` python import requests from urllib.parse import quote token = 'YOUR_API_TOKEN' email = 'john@gmail.com' encoded = quote(email, safe='') base = 'https://api.useapi.net/v1/google-flow' headers = {'Authorization': f'Bearer {token}'} listing = requests.get(f'{base}/assets/media/{encoded}', headers=headers) listing.raise_for_status() cutoff = '2026-01-01' stale = [m['mediaGenerationId'] for m in listing.json()['media'] if m['likelyUpload'] and m.get('createTime') and m['createTime'] < cutoff] print(f'{len(stale)} uploads older than {cutoff}') removed = 0 for i in range(0, len(stale), 100): resp = requests.delete(f'{base}/assets/{encoded}', headers=headers, json={'mediaGenerationIds': stale[i:i + 100]}) resp.raise_for_status() removed += resp.json()['deleted'] print(f'Deleted {removed}') ``` ### Try It <script> async function apiExecuteDeleteGoogleFlowAssetsEmail() { const tokenElement = document.getElementById('input-token'); const emailElement = document.getElementById('input-email'); const idsElement = document.getElementById('input-mediaGenerationIds'); const projectIdElement = document.getElementById('input-projectId'); const elementId = 'input'; const mediaGenerationIds = idsElement.value .split('\n') .map(line => line.trim()) .filter(line => line.length); const body = { mediaGenerationIds }; if (projectIdElement.value) body.projectId = projectIdElement.value; const data = { method: 'DELETE', headers: { 'Authorization': `Bearer ${tokenElement.value}`, 'Content-Type': 'application/json' }, body: JSON.stringify(body) }; const url = `https://api.useapi.net/v1/google-flow/assets/${encodeURIComponent(emailElement.value)}`; await apiExecute(url, elementId, data); } </script> <form id="input" class="input-form" onsubmit="return false;"> <div class="input-field"> <div class="input-field-row"> <label for="input-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="input-token" type="text" class="input-element" required aria-required="true"> </label> <label for="input-email"><span>email (Google Flow account)</span> <input id="input-email" type="text" class="input-element" placeholder="john@gmail.com" required aria-required="true"> </label> <label for="input-mediaGenerationIds"><span>mediaGenerationIds (one per line, max 100 — deletion is permanent)</span> <textarea id="input-mediaGenerationIds" rows="4" class="input-element" placeholder="user:12345-email:6a6f...-image:0115f3c1-..." required aria-required="true"></textarea> </label> <label for="input-projectId"><span>projectId (optional, defaults to the current project)</span> <input id="input-projectId" type="text" class="input-element" placeholder="3a18acb1-2c6e-478b-bcec-2df19cb8edab"> </label> </div> <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteDeleteGoogleFlowAssetsEmail()">Go</button> </div> </form> <div id="input-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-google-flow-v1/delete-google-flow-characters-ref === Document URL: https://useapi.net/docs/api-google-flow-v1/delete-google-flow-characters-ref --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> characters/`ref` description: "Delete a reusable Google Flow character by ref via DELETE characters/ref in the useapi.net Google Flow API v1 — attached voices are not affected." parent: Google Flow API nav_order: 1230 --- ## Delete Character June 5, 2026 (November 16, 2026) --- Delete a character. The attached voice (if any) is not deleted — voices have their own lifecycle. > **https://api.useapi.net/v1/google-flow/characters/`ref`** ### Path Parameters - `ref` is **required**, the `character` value from [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters) (URL-encoded). ### Request Headers ``` yaml Authorization: Bearer {API token} ``` ### Responses **200** **200 OK** ```json { "deleted": true, "entityId": "f470f1b5-...", "character": "user:12345-email:6a6f...-character:f470f1b5-...-imgs:2-voice:d990a2f9-..." } ``` **400** **400 Bad Request** ```json { "error": "Parameter character has incorrect format", "code": 400 } ``` **403** **403 Forbidden** ```json { "error": "Unauthorized access to user:12345 detected in character reference", "code": 403 } ``` **404** **404 Not Found** ```json { "error": "Character not found: f470f1b5-...", "code": 404 } ``` ### Model Confirms the delete, with Google's id of the character and the reference-id you passed. <details markdown="block" class="model-details"> <summary>The deletion result, field by field</summary> ```typescript { deleted: true // always true entityId: string // Google's id of the deleted character character: string // echoes the reference-id passed in } ``` </details> ### Examples **Curl** ``` bash REF="user:12345-email:6a6f...-character:f470f1b5-...-imgs:2" REF_ENC=$(printf '%s' "$REF" | jq -sRr @uri) curl -X DELETE \ -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v1/google-flow/characters/$REF_ENC" ``` **JavaScript** ``` javascript const ref = 'user:12345-email:6a6f...-character:f470f1b5-...-imgs:2' const r = await fetch( `https://api.useapi.net/v1/google-flow/characters/${encodeURIComponent(ref)}`, { method: 'DELETE', headers: { 'Authorization': `Bearer ${token}` } } ) const { deleted } = await r.json() console.log('deleted:', deleted) ``` **Python** ``` python import requests, urllib.parse ref = 'user:12345-email:6a6f...-character:f470f1b5-...-imgs:2' r = requests.delete( f'https://api.useapi.net/v1/google-flow/characters/{urllib.parse.quote(ref, safe="")}', headers={'Authorization': f'Bearer {token}'}, ) print('deleted:', r.json().get('deleted')) ``` ### Try It <form id="input" class="input-form" onsubmit="return false;"> <div class="input-field"> <div class="input-field-row"> <label for="input-token"><span>API Token</span> <input id="input-token" type="text" class="input-element" required aria-required="true"> </label> <label for="input-ref"><span>ref (the <code>character</code> value from <a href="/docs/api-google-flow-v1/post-google-flow-characters">POST /characters</a>)</span> <input id="input-ref" type="text" class="input-element" required aria-required="true" placeholder="user:12345-email:...-character:...-imgs:N"> </label> </div> <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteDeleteGoogleFlowCharacter()">Go</button> </div> </form> <div id="input-response" class="response-placeholder visible-false"></div> <script> async function apiExecuteDeleteGoogleFlowCharacter() { const tokenElement = document.getElementById('input-token'); const elementId = 'input'; const ref = document.getElementById('input-ref').value?.trim(); if (!ref) return; const url = `https://api.useapi.net/v1/google-flow/characters/${encodeURIComponent(ref)}`; const data = { method: 'DELETE', headers: { 'Authorization': `Bearer ${tokenElement.value}` } }; await apiExecute(url, elementId, data, { includeTimer: true }); } </script> === URL: https://useapi.net/docs/api-google-flow-v1/delete-google-flow-voices-ref === Document URL: https://useapi.net/docs/api-google-flow-v1/delete-google-flow-voices-ref --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> voices/`ref` description: "Delete a custom user voice via DELETE voices/ref in the useapi.net Google Flow API v1; system presets are immutable, and affected characters surface an orphan-voice flag." parent: Google Flow API nav_order: 1130 --- ## Delete Custom Voice June 5, 2026 (November 16, 2026) --- Delete a **user voice** by its reference-id. System voice presets are immutable — attempting to delete one returns `400`. When a voice is deleted, any **characters** that referenced it become *orphan-voice* — their [GET /characters/`ref`](/docs/api-google-flow-v1/get-google-flow-characters-ref) response surfaces `voice: { workflowId, deleted: true }` so callers can tell "had a voice, it's gone" vs "never had a voice." > **https://api.useapi.net/v1/google-flow/voices/`ref`** ### Path Parameters - `ref` is **required**, the user voice reference-id returned by [POST /voices](/docs/api-google-flow-v1/post-google-flow-voices) (URL-encoded). System voice names are rejected with `400`. ### Request Headers ``` yaml Authorization: Bearer {API token} ``` ### Responses **200** **200 OK** ```json { "deleted": true, "workflowId": "d990a2f9-...", "voice": "user:12345-email:6a6f...-voice:d990a2f9-...-mid:d55b6d59-..." } ``` **400** **400 Bad Request** Attempted to delete a system voice (immutable), or the path segment isn't a valid voice ref. ```json { "error": "Built-in voices cannot be deleted.", "code": 400 } ``` **403** **403 Forbidden** The reference belongs to a different user. ```json { "error": "Unauthorized access to user:12345 detected in voice reference", "code": 403 } ``` **404** **404 Not Found** The voice already doesn't exist on the account. ```json { "error": "Voice not found: d990a2f9-...", "code": 404 } ``` ### Model Confirms the delete, with the voice's Google Flow workflow and the reference-id you passed. <details markdown="block" class="model-details"> <summary>The deletion result, field by field</summary> ```typescript { deleted: true // always true workflowId: string // Google Flow workflow of the deleted voice voice: string // echoes the reference-id passed in } ``` </details> ### Examples **Curl** ``` bash REF="user:12345-email:6a6f...-voice:d990a2f9-...-mid:d55b6d59-..." REF_ENC=$(printf '%s' "$REF" | jq -sRr @uri) curl -X DELETE \ -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v1/google-flow/voices/$REF_ENC" ``` **JavaScript** ``` javascript const ref = 'user:12345-email:6a6f...-voice:d990a2f9-...-mid:d55b6d59-...' const r = await fetch( `https://api.useapi.net/v1/google-flow/voices/${encodeURIComponent(ref)}`, { method: 'DELETE', headers: { 'Authorization': `Bearer ${token}` } } ) const { deleted } = await r.json() console.log('deleted:', deleted) ``` **Python** ``` python import requests, urllib.parse ref = 'user:12345-email:6a6f...-voice:d990a2f9-...-mid:d55b6d59-...' r = requests.delete( f'https://api.useapi.net/v1/google-flow/voices/{urllib.parse.quote(ref, safe="")}', headers={'Authorization': f'Bearer {token}'}, ) print('deleted:', r.json().get('deleted')) ``` ### Try It <form id="input" class="input-form" onsubmit="return false;"> <div class="input-field"> <div class="input-field-row"> <label for="input-token"><span>API Token</span> <input id="input-token" type="text" class="input-element" required aria-required="true"> </label> <label for="input-ref"><span>ref (user voice reference-id from <a href="/docs/api-google-flow-v1/post-google-flow-voices">POST /voices</a>)</span> <input id="input-ref" type="text" class="input-element" required aria-required="true" placeholder="user:12345-email:...-voice:...-mid:..."> </label> </div> <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteDeleteGoogleFlowVoice()">Go</button> </div> </form> <div id="input-response" class="response-placeholder visible-false"></div> <script> async function apiExecuteDeleteGoogleFlowVoice() { const tokenElement = document.getElementById('input-token'); const elementId = 'input'; const ref = document.getElementById('input-ref').value?.trim(); if (!ref) return; const url = `https://api.useapi.net/v1/google-flow/voices/${encodeURIComponent(ref)}`; const data = { method: 'DELETE', headers: { 'Authorization': `Bearer ${tokenElement.value}` } }; await apiExecute(url, elementId, data, { includeTimer: true }); } </script> === URL: https://useapi.net/docs/api-google-flow-v1/get-google-flow-accounts-captcha-providers === Document URL: https://useapi.net/docs/api-google-flow-v1/get-google-flow-accounts-captcha-providers --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts/captcha-providers description: "Check your captcha provider keys via GET accounts/captcha-providers in the useapi.net Google Flow API v1: masked keys plus each key's status and remaining balance." parent: Google Flow API nav_order: 420 --- ## Get Captcha Providers December 23, 2025 (November 16, 2026) --- Retrieve configured captcha provider API keys (masked for security), with each key's status and remaining balance. > **https://api.useapi.net/v1/google-flow/accounts/captcha-providers** ### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Responses **200** **200 OK** Returns masked keys for all configured providers. **With providers configured:** ```json { "CapSolver": "abc12…", "AntiCaptcha": "def34…", "balances": { "CapSolver": { "status": "ok", "balance": 68.87, "checkedAt": "2026-10-03T22:11:17.173Z" }, "AntiCaptcha": { "status": "empty", "balance": 0, "checkedAt": "2026-10-03T22:11:17.173Z" } } } ``` `balances` shows, for each key you added, whether it works and how much money is left on it. We ask each provider directly and keep its answer for 15 minutes, so a balance can be up to 15 minutes old. When the provider did not answer (`unavailable`), we keep that for 2 minutes only and then ask again. `checkedAt` says when we asked. Saving keys with POST asks again when the kept answer is more than 60 seconds old, so you can see right away whether a key you just added or topped up works. | `status` | Meaning | |---|---| | `ok` | The key works and has money on it. | | `empty` | The key has no money left. We skip it until it is topped up. | | `invalid` | The provider does not accept this key. Check it in your provider account. | | `unavailable` | The provider did not answer. We ask again after 2 minutes. | `balance` is the amount the provider reports, in its own unit: US dollars for most providers, points for YesCaptcha. It is left out when the key is `invalid` or the provider is `unavailable`. `error` is the provider's message, only for `invalid` and `unavailable`. **No providers configured (shows free credits if available):** ```json { "freeCaptchaCredits": 300 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` ### Model Each configured captcha provider with its key masked, the balance of each key, and your free captcha credits when no key is set. <details markdown="block" class="model-details"> <summary>The captcha providers and their balances, field by field</summary> ```typescript { // TypeScript, all fields are optional CapSolver?: string // the key's first 5 characters and …, omitted if not configured AntiCaptcha?: string // the key's first 5 characters and …, omitted if not configured YesCaptcha?: string // the key's first 5 characters and …, omitted if not configured CapMonster?: string // the key's first 5 characters and …, omitted if not configured SolveCaptcha?: string // the key's first 5 characters and …, omitted if not configured '2Captcha'?: string // the key's first 5 characters and …, omitted if not configured EzCaptcha?: string // the key's first 5 characters and …, omitted if not configured freeCaptchaCredits?: number // Remaining free credits (only shown when no providers configured) balances?: Record<string, { // Per configured key, see below. Omitted when no keys are configured status: 'ok' | 'empty' | 'invalid' | 'unavailable' // ok: the key has funds; empty: balance under $0.01, skipped for generations; invalid: the provider refuses the key; unavailable: the provider could not be asked balance?: number // As the provider reports it (US dollars for most, points for YesCaptcha) error?: string // Provider's message, for invalid and unavailable only checkedAt: string // ISO 8601 timestamp, when we asked the provider. The answer is kept for 15 minutes, 2 minutes when the provider was unavailable }> } ``` **Note:** `freeCaptchaCredits` is only included in the response when: - No captcha providers are configured, AND - The user has remaining free credits (> 0) </details> ### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v1/google-flow/accounts/captcha-providers" ``` **JavaScript** ``` javascript const apiUrl = 'https://api.useapi.net/v1/google-flow/accounts/captcha-providers'; const token = 'YOUR_API_TOKEN'; const response = await fetch(apiUrl, { headers: { 'Authorization': `Bearer ${token}` } }); const result = await response.json(); console.log('Configured providers:', result); ``` **Python** ``` python import requests apiUrl = 'https://api.useapi.net/v1/google-flow/accounts/captcha-providers' token = 'YOUR_API_TOKEN' headers = { 'Authorization': f'Bearer {token}' } response = requests.get(apiUrl, headers=headers) print(response.status_code, response.json()) ``` ### Try It <script> async function apiTestCaptchaProvidersGet() { const data = { method: 'GET', headers: { 'Authorization': `Bearer ${document.getElementById('get-captcha-providers-api_token').value}` } }; await apiExecute('https://api.useapi.net/v1/google-flow/accounts/captcha-providers', 'get-captcha-providers', data); } </script> <form id="get-captcha-providers" onsubmit="return false;" class="input-form"> <div class="input-field"> <div class="input-field-row"> <label for="get-captcha-providers-api_token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="get-captcha-providers-api_token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> </div> <button id="get-captcha-providers-button" class="btn btn-primary fs-3" type="submit" onclick="apiTestCaptchaProvidersGet()">Go</button> </div> </form> <div id="get-captcha-providers-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-google-flow-v1/get-google-flow-accounts-captcha-stats === Document URL: https://useapi.net/docs/api-google-flow-v1/get-google-flow-accounts-captcha-stats --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts/captcha-stats description: "Query captcha solve rates by provider via GET accounts/captcha-stats in the useapi.net Google Flow API v1; anonymized=true returns cross-account benchmarks." parent: Google Flow API nav_order: 425 --- ## Get Captcha Statistics February 4, 2026 (November 16, 2026) --- Query captcha solving statistics for your account. Returns detailed information about captcha token requests and their success/failure rates. Compare success rates across all configured providers to help decide which one works best for your use case. Every response also carries `provider_ranking`, the live order the API uses to pick captcha providers automatically (see [Automatic provider order](#automatic-provider-order-provider_ranking)), and `summary.by_provider_and_type` splits each provider's results by image, video, audio and upload. Use `anonymized=true` to get aggregated scores across all users and all captcha providers. This mode returns a summary only (no individual data rows) based on the last 10000 records across all accounts, giving you a broader picture of provider performance. **Note:** - Data latency is at least 5 minutes, but should not exceed 15 minutes. - Data is retained for 3 months. - Results are cached for 5 minutes. > **https://api.useapi.net/v1/google-flow/accounts/captcha-stats** ### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Query Parameters | Parameter | Required | Description | |:----------|:---------|:------------| | `date` | No | Date in `YYYY-MM-DD` format.<br>Defaults to today if `limit` is not specified.<br>A day with more than 50,000 records comes back in pages of 20,000 (see `page` and `offset`). `total` and `summary` still cover the whole day on every page. | | `limit` | No | Number of records to return (max: 50000).<br>If specified, `date` filter is ignored and returns last N records across all dates. | | `offset` | No | Only for a day with more than 50,000 records: where the page starts. Use `page.next_offset` from the previous page. Default `0`.<br>Today's date keeps growing while you page through it, so a record can show up on two pages. A past day pages exactly. | | `provider` | No | Filter by captcha provider.<br>Supported: `CapSolver`, `AntiCaptcha`, `YesCaptcha`, `CapMonster`, `SolveCaptcha`, `2Captcha`, `EzCaptcha`, `UserProvided` | | `anonymized` | No | Set to `true` to return aggregated scores across all users and all captcha providers.<br>Returns summary only (no individual data rows).<br>Uses last 10000 records across all accounts, ignores `date`/`limit`/`provider` filters. | ### Responses **200** **200 OK** Returns captcha statistics for the specified filters. An illustrative answer for `date=2026-10-01`, with made-up numbers that add up the way the API counts them (`data` cut short to its newest row): ```json { "date": "2026-10-01", "total": 44, "summary": { "from": "2026-10-01T00:05:23.000Z", "to": "2026-10-01T23:58:47.000Z", "time_span": "23 hours 53 minutes", "sample_size_by_provider": { "AntiCaptcha": 10, "CapSolver": 24, "EzCaptcha": 8 }, "success_rate_by_provider": { "AntiCaptcha": 80.00, "CapSolver": 70.83, "EzCaptcha": 62.50 }, "sample_size_by_tier": { "PAYGATE_TIER_TWO": 25, "PAYGATE_TIER_ONE": 17 }, "success_rate_by_tier": { "PAYGATE_TIER_TWO": 92.00, "PAYGATE_TIER_ONE": 41.18 }, "sample_size_by_sku": { "WS_ULTRA": 14, "G1_TIER2": 11, "G1_TIER1": 17 }, "success_rate_by_sku": { "WS_ULTRA": 92.86, "G1_TIER2": 90.91, "G1_TIER1": 41.18 }, "by_status_code_images": { "200": 76.92, "403": 3.85, "429:PUBLIC_ERROR_UNUSUAL_ACTIVITY_TOO_MUCH_TRAFFIC": 7.69, "429:PUBLIC_ERROR_PER_MODEL_DAILY_QUOTA_REACHED": 3.85, "429:PUBLIC_ERROR_USER_REQUESTS_THROTTLED": 3.85, "503": 3.85 }, "by_status_code_videos": { "200": 70.00, "403": 10.00, "429:PUBLIC_ERROR_USER_QUOTA_REACHED": 10.00, "503": 10.00 }, "avg_captcha_ms": 8500, "avg_api_ms": 1200, "avg_attempt": 1.2, "by_provider_and_type": { "AntiCaptcha": { "image": { "samples": 6, "success_rate": 83.33, "first_attempt_samples": 5, "first_attempt_success_rate": 80.00 }, "video": { "samples": 4, "success_rate": 75.00, "first_attempt_samples": 3, "first_attempt_success_rate": 66.67 } }, "CapSolver": { "image": { "samples": 16, "success_rate": 75.00, "first_attempt_samples": 12, "first_attempt_success_rate": 75.00 }, "video": { "samples": 8, "success_rate": 62.50, "first_attempt_samples": 6, "first_attempt_success_rate": 66.67 } }, "EzCaptcha": { "image": { "samples": 8, "success_rate": 62.50, "first_attempt_samples": 8, "first_attempt_success_rate": 62.50 } } }, "lookup": { "tiers": { "PAYGATE_TIER_TWO": "Ultra $199", "PAYGATE_TIER_ONE": "Pro" }, "skus": { "WS_ULTRA": "Workspace Ultra", "G1_TIER2": "Ultra $199", "G1_TIER1": "Pro" } }, "by_account": { "john.smith@gmail.com": { "samples": 17, "success_rate": 41.18, "first_attempt_samples": 10, "first_attempt_success_rate": 20.00 }, "john@gmail.com": { "samples": 14, "success_rate": 92.86, "first_attempt_samples": 13, "first_attempt_success_rate": 92.31 }, "jane@gmail.com": { "samples": 11, "success_rate": 90.91, "first_attempt_samples": 11, "first_attempt_success_rate": 90.91 } } }, "provider_ranking": { "mode": "on", "order": ["AntiCaptcha", "EzCaptcha", "CapSolver", "YesCaptcha", "SolveCaptcha", "2Captcha", "CapMonster"], "leader": "AntiCaptcha", "leaderSince": "2026-10-02T03:15:30.000Z", "computedAt": "2026-10-02T18:40:00.000Z", "providers": { "AntiCaptcha": { "firstAttemptSuccessRate": 84.00, "samples": 100, "status": "leader" }, "EzCaptcha": { "firstAttemptSuccessRate": 71.00, "samples": 100, "status": "ranked" }, "CapSolver": { "firstAttemptSuccessRate": 43.00, "samples": 100, "status": "ranked" }, "YesCaptcha": { "firstAttemptSuccessRate": 78.05, "samples": 41, "status": "collecting" }, "SolveCaptcha": { "firstAttemptSuccessRate": 6.06, "samples": 33, "status": "hopeless" }, "2Captcha": { "firstAttemptSuccessRate": 2.17, "samples": 46, "status": "hopeless" }, "CapMonster": { "status": "collecting" } }, "rules": { "window": "newest 5-minute slots until 100 samples, up to 2 h", "minSamples": 100, "marginPoints": 10, "leaderConfirmMinutes": 5, "explorePercent": 5, "exploreCollectingPercent": 30, "exploreHopelessPercent": 2 }, "hopelessUntil": { "SolveCaptcha": "2026-10-02T20:31:00.000Z", "2Captcha": "2026-10-02T20:12:00.000Z" } }, "data": [ { "timestamp": "2026-10-01T23:58:47.000Z", "jobId": "j1001235831204917365v-u12345-email:john@gmail.com-bot:google-flow", "provider": "AntiCaptcha", "taskId": "582036417", "route": "post-videos", "statusText": "OK", "pageAction": "VIDEO_GENERATION", "error": "", "reason": "", "tier": "PAYGATE_TIER_TWO", "sku": "WS_ULTRA", "statusCode": 200, "captchaDurationMs": 8500, "apiDurationMs": 1200, "attemptNumber": 1, "sampleInterval": 1 } ] } ``` The `summary` object provides aggregated statistics (omitted if no data). On busy days the stats store keeps a sample of the rows from the busiest API tokens rather than every row. Each row's `sampleInterval` says how many it stands for. It is `1` for almost every customer and higher only for the busiest ones at peak hours. `total` and every count, rate and average in `summary` already weight each row by its `sampleInterval`, so they reflect all of your . When you count rows in `data` yourself, add up `sampleInterval` rather than counting rows. `limit` counts stored rows, so `total` can be larger than `limit`. #### Understanding the 429 buckets Google returns `HTTP 429 RESOURCE_EXHAUSTED` in at least four known distinct situations. The `by_status_code_images` / `by_status_code_videos` summary splits 429s by their reason code so you can tell them apart — each needs a different strategy. | Bucket key | What it means | Customer strategy | |---|---|---| | `429:PUBLIC_ERROR_UNUSUAL_ACTIVITY_TOO_MUCH_TRAFFIC` | Google rejected the captcha on every try (we already retried with fresh ones, up to `captchaRetry`, default 5). Usually the Google account is distrusted, sometimes the provider is doing badly. Counts as a captcha failure in `success_rate_by_provider`. | Find out whether it's a few accounts or all of them — see [When Google rejects captchas](#when-google-rejects-captchas). Rest or replace distrusted accounts. If all accounts drop together, configure a second provider via [POST /accounts/captcha-providers](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers). | | `429:PUBLIC_ERROR_USER_REQUESTS_THROTTLED` | Google is throttling this account. The captcha token was fine. Sending fewer parallel requests usually helps, but the limit is not purely a concurrency cap — Google can hold it on an account for far longer. **Does NOT count as a captcha failure.** | Reduce parallel generations per account. With `email` omitted, the load balancer quarantines this account for ~30 min and routes around it. Treat `Retry-After` as a minimum wait rather than the moment it clears. | | `429:PUBLIC_ERROR_PER_MODEL_DAILY_QUOTA_REACHED` | This account hit Google's per-model daily quota. **Does NOT count as a captcha failure.** | Switch to a different model — only this model is capped, other models on the account still work, and it resets at UTC midnight. With `email` omitted, the load balancer quarantines just this account+model and routes around it. | | `429:PUBLIC_ERROR_USER_QUOTA_REACHED` | This account hit its overall Google Flow quota cap — separate from per-model limits, blocks **all** models on this account. **Does NOT count as a captcha failure.** | Add more Google Flow accounts via [POST /accounts](/docs/api-google-flow-v1/post-google-flow-accounts) so the load spreads. With `email` omitted, the load balancer quarantines this account for ~30 min and routes around it — though Google's underlying quota can take 1–2 hours to actually reset. | The bottom three reasons automatically quarantine the account — `USER_REQUESTS_THROTTLED` and `USER_QUOTA_REACHED` for ~30 min, `PER_MODEL_DAILY_QUOTA_REACHED` until UTC midnight — and the load balancer routes around them when `email` is omitted (see [GET /jobs › Load Balancing Algorithm](/docs/api-google-flow-v1/get-google-flow-jobs#load-balancing-algorithm)). `UNUSUAL_ACTIVITY_TOO_MUCH_TRAFFIC` is per-request and does not quarantine. Per-reason scope and cooldown: [429 reference](/docs/api-google-flow-v1/post-google-flow-videos#responses). #### How `success_rate_by_provider` is calculated This is the **end-to-end captcha effectiveness** per provider — measured against Google's reCAPTCHA Enterprise evaluation, not just whether the token was syntactically accepted. Use it to compare providers and decide which to prefer, drop, or rebalance. A row counts as a **captcha failure** when: - HTTP `403` — token was rejected outright (`PERMISSION_DENIED`), except reasons `PUBLIC_ERROR_MODEL_ACCESS_DENIED` and `PUBLIC_ERROR_USER_MINOR` - HTTP `429` with reason `PUBLIC_ERROR_UNUSUAL_ACTIVITY_TOO_MUCH_TRAFFIC` — Google's response literally says `"reCAPTCHA evaluation failed"`. The token was valid but Google did not trust it enough. That depends on the Google account as much as on the provider — see [When Google rejects captchas](#when-google-rejects-captchas). The other 429 reasons (`PER_MODEL_DAILY_QUOTA_REACHED`, `USER_REQUESTS_THROTTLED`, `USER_QUOTA_REACHED`) are NOT counted as captcha failures because they are account-level limits independent of token quality. HTTP `503` is also excluded (Google-side outage, unrelated to the provider). A `403` with reason `PUBLIC_ERROR_MODEL_ACCESS_DENIED` is NOT a captcha failure either. Google sends it after the token passed, when the account's plan does not offer the requested model — since 2026-09-23 that includes `veo-3.1-lite-low-priority` on invited members of an Ultra $199 family plan. In `by_status_code_images` / `by_status_code_videos` it has its own bucket, `403:PUBLIC_ERROR_MODEL_ACCESS_DENIED`, so it does not read as a rejected token. Nor is a `403` with reason `PUBLIC_ERROR_USER_MINOR`. Google sends it whatever the token when it treats the Google account as belonging to someone under 18, and Google Flow is not available to such accounts. It has its own bucket too, `403:PUBLIC_ERROR_USER_MINOR`. Use another Google account, or have this one's age verified with Google. If one provider has a noticeably lower `success_rate_by_provider` than the others over the same period, its captchas are scoring poorly with reCAPTCHA Enterprise. The API already moves that provider down your order for you (see `provider_ranking`). To stop using it, leave it out of `captchaOrder` or remove its key. Topping up its balance can also help, since some providers give higher-balance accounts better proxies. Compare providers on the first-attempt figures in `by_provider_and_type`, and check the sample sizes before drawing conclusions. #### When Google rejects captchas Nothing was created when this happens. Google checks the captcha before it starts generating, so no Google credits were used and you can resubmit straight away. Your captcha provider still bills each solve. The usual cause is the Google account, not the captcha provider. Google gives each account its own trust level. On a trusted account it accepts about 9 in 10 captchas, on a distrusted one about 3 in 10, whichever provider solved them. Most customers have a few distrusted accounts among many good ones. To see which accounts are affected, use [GET /accounts/captcha-stats](/docs/api-google-flow-v1/get-google-flow-accounts-captcha-stats). Its `summary.by_account` shows, for each of your Google accounts, how many captchas were tried and what share Google accepted. [GET account/stats](/docs/account-management/get-account-stats) with `bot=google-flow` also shows how many requests each account finished with each response code. - If one or a few accounts are far below the others, the API already sends them less work: when you leave out `email`, each captcha Google rejected on an account in the last 15 minutes lowers its chance of being picked, for generations and for image uploads. They still get some work, so an account that recovers gets its full share back. If you pin requests with `email`, move them to your other accounts yourself. Replace an account that stays low for more than a day or two. - If all your accounts drop at the same time, it's the captcha provider. Configure at least two providers with [POST /accounts/captcha-providers](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers), and the API will start with whichever one Google accepts best. A higher `captchaRetry` gets more requests through on a distrusted account, but every extra try is another paid solve. #### How `by_status_code_images` / `by_status_code_videos` are aggregated The status distribution shows **customer-facing final outcomes per `jobId`**, not per attempt. A request that internally retried 5 times before succeeding contributes a single `"200"` to the bucket, not five entries. This makes the distribution a true outcome map. A `429:<reason>` bucket therefore counts only requests where our internal retry budget was exhausted before resolving the condition. #### Image vs video: `by_provider_and_type` A provider can do well on images and badly on video. For example, over the 72 hours to October 2, 2026, Google accepted CapSolver's first try 46% of the time for images but only 26% for video. EzCaptcha did about the same on both. `by_provider_and_type` shows each provider's results separately for `image`, `video`, `audio` (voices) and `upload` (image upload): - `samples` and `success_rate` count all tries. - `first_attempt_samples` and `first_attempt_success_rate` count first tries only. Use these to compare providers. Retries fail more often no matter which provider solves them, because Google has already rejected one captcha for that request. Counting them would make a provider look worse than it is. A number based on only a few tries means little. In the Try It charts below, bars based on fewer than 100 tries are faded, every label shows how many tries (`n`) it is based on, and the busiest providers come first. #### Automatic provider order: `provider_ranking` If you have two or more captcha providers, most requests use the one Google is accepting best right now, with your second-best provider as a backup on the third try. `captchaOrder` only picks which providers to use and how many tries to make, not the order. We recommend adding at least two providers, for example AntiCaptcha and CapSolver, and ideally EzCaptcha too, so fewer captchas are rejected and you pay for fewer of them. How it works: [Provider order](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers#provider-order). `provider_ranking` shows the current order. It is based on all customers' requests, not just yours, so you get it even when you have no data of your own. - `order`: the providers, best first. `leader` is the one in first place, and `leaderSince` is since when. - `providers.<name>.firstAttemptSuccessRate`: the provider's score. Out of its last `samples` first tries, the percentage Google accepted. - `status`: `leader` (first place), `ranked`, `collecting` (fewer than 100 recent tries, not ranked yet) or `hopeless` (doing very badly, almost never tried first). `hopelessUntil` shows until when a provider stays `hopeless`. - `rules`: the exact numbers the ranking uses. - `mode`: `on` normally. `off` means the fixed default order is used, and no other fields are returned. #### Understanding `tier` and `sku` Every row carries the Google `userPaygateTier` (`tier`) and `sku` strings captured at submission time. These come straight from Google's `/credits` response — the same wire-format strings, no translation. Aggregate breakdowns in `summary` (`sample_size_by_tier`, `success_rate_by_tier`, `sample_size_by_sku`, `success_rate_by_sku`) let you compare captcha effectiveness across plan levels, which is useful when one plan tier is being scored more aggressively by Google's reCAPTCHA Enterprise than another. `summary.lookup.tiers` and `summary.lookup.skus` are the **canonical human-readable mapping** — resolve enum values through these maps rather than hard-coding strings on your side. They cover only the enums present in this response; unknown values map to themselves so you can still see them. Current known values: | Field | Enum value | Label | Plan | |---|---|---|---| | `tier` | `PAYGATE_TIER_NOT_PAID` | Free | Free tier | | `tier` | `PAYGATE_TIER_ZERO` | Plus | Google AI Plus | | `tier` | `PAYGATE_TIER_ONE` | Pro | Google AI Pro | | `tier` | `PAYGATE_TIER_TIER1P5` | Ultra $99 | Google AI Ultra $99/mo | | `tier` | `PAYGATE_TIER_TWO` | Ultra $199 | Google AI Ultra $199/mo | | `sku` | `G1_FREEMIUM` | Free | Google AI consumer Free | | `sku` | `G1_TIER0` | Plus | Google AI consumer Plus | | `sku` | `G1_TIER1` | Pro | Google AI consumer Pro | | `sku` | `G1_TIER1P5` | Ultra $99 | Google AI consumer Ultra $99 | | `sku` | `G1_TIER2` | Ultra $199 | Google AI consumer Ultra $199 | | `sku` | `WS_FREEMIUM` | Workspace Free | Google Workspace, no AI add-on | | `sku` | `WS_ULTRA` | Workspace Ultra | Google Workspace + AI Ultra add-on | Rows written before 2026-05-21 lack `tier` and `sku` (the columns didn't exist yet) — they're bucketed under `"(empty)"` in the per-tier and per-sku aggregates. **400** **400 Bad Request** Missing or invalid parameters. ```json { "error": "Invalid date format. Use YYYY-MM-DD", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` ### Model Captcha attempts for the filters you set: the total, a summary per provider, plan tier and plan, and the rows themselves. <details markdown="block" class="model-details"> <summary>The captcha statistics, field by field</summary> ```typescript // Response structure { date?: string // Date filter applied (YYYY-MM-DD) limit?: number // Limit filter applied provider?: string // Provider filter applied total: number // Captcha attempts the rows stand for (sum of sampleInterval). A paged day: the whole day page?: { // Only for a day with more than 50,000 records, sent in pages of 20,000 offset: number // Where this page starts size: number // Records in this page (data.length) rows: number // Records in the whole day next_offset?: number // Pass as `offset` for the next page; absent on the last page } summary?: { // Aggregated statistics (omitted if no data) from: string // Earliest timestamp (ISO 8601) to: string // Latest timestamp (ISO 8601) time_span: string // Human readable duration (e.g., "2 days 5 hours") sample_size_by_provider: Record<string, number> // Attempts per provider across ALL attempts (excludes 503) success_rate_by_provider: Record<string, number> // Captcha success rate % per provider. Failures: 403 (token rejected) AND 429:PUBLIC_ERROR_UNUSUAL_ACTIVITY_TOO_MUCH_TRAFFIC (token scored too low by reCAPTCHA Enterprise). Other 429 reasons are NOT counted. (excludes 503) sample_size_by_tier: Record<string, number> // Attempts per Google userPaygateTier across ALL attempts (excludes 503). Pre-2026-05-21 rows lack tier and bucket under "(empty)" success_rate_by_tier: Record<string, number> // Captcha success rate % per tier (same failure definition as success_rate_by_provider) sample_size_by_sku: Record<string, number> // Attempts per Google sku across ALL attempts (excludes 503). Pre-2026-05-21 rows lack sku and bucket under "(empty)" success_rate_by_sku: Record<string, number> // Captcha success rate % per sku (same failure definition as success_rate_by_provider) by_account?: Record<string, { // Your Google accounts, by email: captcha results on each. Not in anonymized responses samples: number // attempts on this account (excludes 503) success_rate: number // % accepted, same failure definition as success_rate_by_provider first_attempt_samples: number // attempt 1 only first_attempt_success_rate?: number // % accepted on attempt 1, omitted when first_attempt_samples is 0 }> by_status_code_images: Record<string, number> // % per customer-facing final-attempt outcome for IMAGE. 429s split by reason — e.g. "429:PUBLIC_ERROR_UNUSUAL_ACTIVITY_TOO_MUCH_TRAFFIC" by_status_code_videos: Record<string, number> // Same as by_status_code_images but for VIDEO avg_captcha_ms: number // Average captcha solve time in ms avg_api_ms: number // Average API call time in ms avg_attempt: number // Average attempt number by_provider_and_type: Record<string, Record<string, { // provider → image | video | audio | upload samples: number // attempts (excludes 503) success_rate: number // % accepted, same failure definition as success_rate_by_provider first_attempt_samples: number // attempt 1 only — the fair comparison between providers first_attempt_success_rate?: number // omitted when first_attempt_samples is 0 }>> lookup: { // Canonical enum → human-readable label map for tier/sku enum values present in this response. Resolve enums through this map rather than hard-coding strings. tiers: Record<string, string> // e.g. { PAYGATE_TIER_TWO: "Ultra $199", PAYGATE_TIER_NOT_PAID: "Free" }. Unknown enums map to themselves. skus: Record<string, string> // e.g. { WS_ULTRA: "Workspace Ultra", G1_TIER1: "Pro" }. Unknown enums map to themselves. } } provider_ranking?: { // Live automatic provider order, all customers' first attempts (omitted if it can't be read) mode: 'on' | 'shadow' | 'off' // on: requests follow this order. shadow: the ranking is computed and shown, but requests keep the fixed default order (a few start with another provider, so every provider keeps being measured). off: the fixed default order is used and only this field is present order: string[] // Ranking, best first leader: string // order[0] leaderSince?: string // When the leader took first place (ISO 8601) computedAt: string // When this ranking was computed (ISO 8601) providers: Record<string, { // provider name → its first-attempt rate and role, in ranking order firstAttemptSuccessRate?: number // % of first-attempt tokens Google accepted (omitted with no samples) samples?: number // first attempts behind the rate status: 'leader' | 'ranked' | 'collecting' | 'hopeless' // leader: order[0]; ranked: has 100+ first attempts; collecting: fewer than 100 so far; hopeless: far below the best provider }> rules: Record<string, number | string> // the numbers the ranking runs on: window (which recent tries it counts), minSamples (first tries a provider needs to be ranked), marginPoints (percentage points a provider must beat another by to move above it), leaderConfirmMinutes (how long it must beat the leader by that margin to take first place), and the percentage of requests that start with another provider so every provider keeps being measured: explorePercent, exploreCollectingPercent (while some of your providers are still collecting) and exploreHopelessPercent (for a hopeless one) hopelessUntil?: Record<string, string> // provider → until when it stays hopeless (ISO 8601) } data: Array<{ // the captcha attempt records, newest first; empty in anonymized responses timestamp: string // ISO 8601 timestamp jobId: string // Job identifier provider: string // Captcha provider used (`CapSolver`, `AntiCaptcha`, `YesCaptcha`, `CapMonster`, // `SolveCaptcha`, `2Captcha`, `EzCaptcha`, `UserProvided`) taskId: string // Provider's task ID route: string // the endpoint the captcha was solved for, named by method and path: post-videos is POST /videos, post-images-upscale is POST /images/upscale statusText: string // HTTP status text (OK, Forbidden, NetworkError) pageAction: string // reCAPTCHA action (VIDEO_GENERATION, IMAGE_GENERATION) error: string // Error message (empty on success) reason: string // Google ErrorInfo.reason — e.g. PUBLIC_ERROR_UNUSUAL_ACTIVITY_TOO_MUCH_TRAFFIC (empty for non-Google errors or successful submits) tier: string // Google userPaygateTier — PAYGATE_TIER_NOT_PAID / PAYGATE_TIER_ZERO / PAYGATE_TIER_ONE / PAYGATE_TIER_TIER1P5 / PAYGATE_TIER_TWO. Empty for rows pre-2026-05-21. Resolve to a label via summary.lookup.tiers. sku: string // Google sku — G1_FREEMIUM / G1_TIER0 / G1_TIER1 / G1_TIER1P5 / G1_TIER2 / WS_FREEMIUM / WS_ULTRA. Empty for rows pre-2026-05-21. Resolve to a label via summary.lookup.skus. statusCode: number // HTTP status code (200, 403, 429, 0 for network errors) captchaDurationMs: number // Captcha solve duration in ms apiDurationMs: number // API call duration in ms attemptNumber: number // Attempt number (1 = first try, 2+ = retry) sampleInterval: number // How many captcha attempts this row stands for: 1 for almost every customer, higher only for the busiest ones at peak hours, when a sample of their rows is kept. Add these up, rather than counting rows, to count attempts }> } ``` </details> ### Examples **Curl** ``` bash # Today's stats curl -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v1/google-flow/accounts/captcha-stats" # Specific date curl -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v1/google-flow/accounts/captcha-stats?date=2026-02-01" # A day with more than 50,000 records: the next page (page.next_offset from the previous answer) curl -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v1/google-flow/accounts/captcha-stats?date=2026-11-08&offset=20000" # Last 1000 records curl -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v1/google-flow/accounts/captcha-stats?limit=1000" # Filter by provider curl -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v1/google-flow/accounts/captcha-stats?provider=AntiCaptcha" # Aggregated scores across all users and providers (summary only) curl -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v1/google-flow/accounts/captcha-stats?anonymized=true" ``` **JavaScript** ``` javascript const apiUrl = 'https://api.useapi.net/v1/google-flow/accounts/captcha-stats'; const token = 'YOUR_API_TOKEN'; const response = await fetch(apiUrl, { headers: { 'Authorization': `Bearer ${token}` } }); const stats = await response.json(); console.log(`Total captcha attempts: ${stats.total}`); console.log(`Success rates:`, stats.summary?.success_rate_by_provider); console.log('Data:', stats.data); ``` **Python** ``` python import requests apiUrl = 'https://api.useapi.net/v1/google-flow/accounts/captcha-stats' token = 'YOUR_API_TOKEN' headers = { 'Authorization': f'Bearer {token}' } # Today's stats response = requests.get(apiUrl, headers=headers) stats = response.json() print(f"Total captcha attempts: {stats['total']}") print(f"Success rates: {stats.get('summary', {}).get('success_rate_by_provider')}") # Filter by provider response = requests.get( apiUrl, params={'provider': 'AntiCaptcha'}, headers=headers ) ``` ### Try It <script src="/assets/js/captcha-stats-visualizer.js"></script> <script> async function apiExecuteInput() { const data = { method: 'GET', headers: { 'Authorization': `Bearer ${document.getElementById('input-token').value}` } }; const inputs = document.querySelectorAll('.input-query-param'); const params = new URLSearchParams(); inputs.forEach(input => { const id = input.id; const value = input.value?.trim(); if (id.startsWith('input-') && value !== '' && value !== undefined) { const key = id.replace('input-', ''); params.append(key, value); } }); const url = 'https://api.useapi.net/v1/google-flow/accounts/captcha-stats' + (params.toString() ? '?' + params.toString() : ''); const vizContainer = document.getElementById('input-stats-viz'); if (vizContainer) { vizContainer.innerHTML = ''; vizContainer.style.display = 'none'; } const status = await apiExecute(url, 'input', data); if (status === 200) { try { const jsonText = document.getElementById('input-response-json').textContent; const result = JSON.parse(jsonText); if (result && result.data && Array.isArray(result.data)) { await displayCaptchaStatsResult(result, 'input-stats-viz'); } } catch (e) { } } } </script> <form id="input" class="input-form" onsubmit="return false;"> <div class="input-field"> <div class="input-field-row"> <label for="input-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="input-token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> <label for="input-date"><span>date (YYYY-MM-DD)</span> <input id="input-date" type="text" class="input-element input-query-param" oninput="this.size = this.value.length"> </label> <label for="input-offset"><span>offset (a large day, page.next_offset)</span> <input id="input-offset" type="text" class="input-element input-query-param" oninput="this.size = this.value.length"> </label> <label for="input-limit"><span>limit (max 50000)</span> <input id="input-limit" type="text" class="input-element input-query-param" oninput="this.size = this.value.length"> </label> <label for="input-provider"><span>provider</span> <select id="input-provider" class="input-element input-query-param"> <option value="">All providers</option> <option value="CapSolver">CapSolver</option> <option value="AntiCaptcha">AntiCaptcha</option> <option value="YesCaptcha">YesCaptcha</option> <option value="CapMonster">CapMonster</option> <option value="SolveCaptcha">SolveCaptcha</option> <option value="2Captcha">2Captcha</option> <option value="EzCaptcha">EzCaptcha</option> <option value="UserProvided">UserProvided</option> </select> </label> <label for="input-anonymized"><span>anonymized</span> <select id="input-anonymized" class="input-element input-query-param"> <option value="">No</option> <option value="true">All users, all providers (last 10K, summary only)</option> </select> </label> </div> <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteInput()">Go</button> </div> </form> <div id="input-stats-viz" style="display:none;"></div> <div id="input-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-google-flow-v1/get-google-flow-accounts-email === Document URL: https://useapi.net/docs/api-google-flow-v1/get-google-flow-accounts-email --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts/`email` description: "Retrieve health, credits, and available video models for a specific Google Flow account via GET accounts/email in the useapi.net Google Flow API v1." parent: Google Flow API nav_order: 350 --- ## Get Account Configuration November 17, 2025 (November 16, 2026) --- Get configuration details for a specific Google Flow account, including health status, credits information, and available video models. > **https://api.useapi.net/v1/google-flow/accounts/`email`** ### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Path Parameters - `email` is **required**. The email address of the Google Flow account to query (URL-encoded if necessary). ### Responses **200** **200 OK** Account configuration found and returned with health status. ```json { "accountCookies": [ { "name": "HSID", "value": "AYQab…redacted…xY12z", "domain": ".google.com", "path": "/", "expires": "2027-11-26T16:03:52.000Z", "httpOnly": true, "secure": false, "sameSite": "Lax" } ], "flowCookies": [ { "name": "OSID", "value": "g.a00…redacted…Hj076", "domain": "flow.google.com", "path": "/", "expires": "2027-11-26T16:04:09.000Z", "httpOnly": false, "secure": true, "sameSite": "Lax" } ], "created": "2025-11-10T12:00:00.000Z", "updated": "2026-10-22T16:04:11.512Z", "project": { "projectId": "3b1c0e9d-7a6f-4592-8d38-7f9e1b4c6a5d", "projectTitle": "Nov 11 - 02:56" }, "nextRefresh": { "messageId": "msg_2…redacted…Fq9Wd", "scheduledFor": "2026-10-24T16:11:37.000Z" }, "backend": "flow", "health": "OK", "credits": { "credits": 1250, "userPaygateTier": "PAYGATE_TIER_TWO", "sku": "G1_TIER2", "serviceTier": "SERVICE_TIER_ADVANCED", "topUpCredits": 250, "subscriptionCredits": 1000 }, "models": { "videoModels": [ { "key": "veo_3_1_t2v", "displayName": "Veo 3.1 - Quality", "supportedAspectRatios": ["VIDEO_ASPECT_RATIO_LANDSCAPE"], "capabilities": ["VIDEO_MODEL_CAPABILITY_AUDIO", "VIDEO_MODEL_CAPABILITY_TEXT"], "videoLengthSeconds": 8, "videoGenerationTimeSeconds": 240, "creditCost": 100, "framesPerSecond": 24, "paygateTier": "PAYGATE_TIER_TWO", "accessType": "MODEL_ACCESS_TYPE_GENERAL", "resolution": "720p", "modelAccessInfo": {}, "modelMetadata": { "veoModelName": "Beta Audio" } }, { "key": "veo_3_1_t2v_lite_low_priority", "displayName": "Veo 3.1 - Lite [Lower Priority]", "supportedAspectRatios": ["VIDEO_ASPECT_RATIO_LANDSCAPE", "VIDEO_ASPECT_RATIO_PORTRAIT"], "capabilities": ["VIDEO_MODEL_CAPABILITY_AUDIO", "VIDEO_MODEL_CAPABILITY_TEXT"], "videoLengthSeconds": 8, "videoGenerationTimeSeconds": 110, "creditCost": 0, "framesPerSecond": 24, "paygateTier": "PAYGATE_TIER_TWO", "accessType": "MODEL_ACCESS_TYPE_GENERAL", "resolution": "720p", "modelAccessInfo": {}, "modelMetadata": { "veoModelName": "Beta Audio" } } ] } } ``` **Note:** Secret values come back masked: every cookie `value`, `sessionData.access_token` and `nextRefresh.messageId` show their first and last five characters around `…redacted…` (a value of ten characters or fewer shows as `…redacted…` alone). `accountCookies` lists every Google account cookie the account was added with (`HSID`, `LSID`, `SID`, `SSID`, `APISID`, `SAPISID`), shortened here to one, and `flowCookies` holds the flow.google.com sign-in cookie (`OSID`), which the API replaces every 2 to 3 days. The `credits` and `models` fields are only included when `health` is `"OK"`. **Captcha provider recommendations.** When fewer than two captcha providers are configured on the account, the response also includes a top-level `recommendations` array. Single-provider users have no failover when Google's reCAPTCHA Enterprise scores a token low — adding a second provider lets the worker rotate on failure. A second provider does not help when Google distrusts the account itself — see [When Google rejects captchas](/docs/api-google-flow-v1/get-google-flow-accounts-captcha-stats#when-google-rejects-captchas). Example: ```json { "health": "OK", "credits": {...}, "models": {...}, "recommendations": [ "Only one captcha provider configured. Adding a second provider gives the worker a fallback when Google scores a token low — significantly reduces 429 TOO_MUCH_TRAFFIC and 403 captcha errors. Configure via POST /accounts/captcha-providers." ] } ``` The field is **omitted** when you already have two or more providers configured. Configure additional providers via [POST /accounts/captcha-providers](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers). Omni 1.1 Flash models are listed for Plus, Pro and Ultra accounts alongside the Veo ones. Google labels this family "Omni 1.1 Flash" in the Flow interface, and `displayName` carries that label verbatim, so it tracks Google's version renames — the [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) `model` value stays `omni-flash` regardless. Every Omni key appears twice, once per `resolution`: the `_360p` variant costs about half its 720p twin. Omni 1.2 Flash (`omni-flash-1.2`, `displayName` "Omni 1.2 Flash", keys `macaron_cookie_*`) is listed for every plan: each length from 3 to 15 seconds (3 to 10 with a start and an end frame), the edit, and the extend lengths from 3 to 10 seconds, each at 720p and 360p, with the `creditCost` of a clip of that length. A free account lists lengths up to 10 seconds and no extend. Google is giving the model to accounts over several days from November 5, 2026, and the list shows the Omni 1.2 Flash models only once the account has them. **Free models on Ultra:** For accounts with Google AI Ultra subscription ([PAYGATE_TIER_TWO](https://one.google.com/ai)), video models with `creditCost: 0` are free to generate. These are the lower-priority variants — keys ending in `_low_priority` (e.g. `veo_3_1_t2v_lite_low_priority`). Keys ending in `_ultra` are discounted but not free — they typically cost 10 credits per generation. For an Ultra $199 account on flow.google.com, this list is checked against the account's own model list. Since 2026-09-23 Google no longer offers the `_low_priority` keys to invited members of a family plan — only the family manager's account keeps them — so a member account is listed without them. An account whose model list could not be read gets the plan's full list. **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **404** **404 Not Found** Account not found or not configured. ```json { "error": "Google Flow account email@example.com not found", "code": 404 } ``` ### Model The account as stored, with its masked cookies, projects, health, credits, models and next automatic refresh. <details markdown="block" class="model-details"> <summary>The account, field by field</summary> - `backend` - `flow` when the account runs on the flow.google.com cookies. `labs` marks an account added before 2026-09-12 without the `APISID` and `SAPISID` cookies, which stopped working on 2026-10-21. Every request for it answers `596`: add it again with the [automated setup](https://useapi.net/assets/setup-browser/google-flow) - `health` - `OK` when the account is ready, otherwise the reason it is not and what to do - `projectEntity` and `projectAgent` - The projects that hold the account's characters and voices, and its agent chats. Each appears once the account first uses it - `recommendations` - Captcha setup advice, see the note in the `200` tab An account first added before 2026-10-21 can also show `sessionCookies` and `sessionData` left from the old Google Labs sign-in. The API no longer uses them. ```typescript { backend: 'flow' | 'labs' // flow: the account signs in with its `flow.google.com` cookies. labs: an account added // before 2026-09-12 that stopped working on 2026-10-21, add it again created: string // ISO 8601 timestamp, first add updated?: string // ISO 8601 timestamp, most recent add, absent on an account last added before 2026-09-16 accountCookies: Array<{ // the Google sign-in cookies kept for the account: HSID, LSID, SID, SSID, APISID and SAPISID name: string // cookie name value: string // Masked domain: string // cookie domain path: string // cookie path expires: string | number // ISO 8601 timestamp, Unix seconds, or -1 for a session cookie httpOnly: boolean // the cookie's HttpOnly flag secure: boolean // the cookie's Secure flag sameSite: 'Lax' | 'Strict' | 'None' // the cookie's SameSite setting }> flowCookies?: Array<{ // Same structure, one OSID cookie for flow.google.com, absent on a 'labs' account name: string // cookie name value: string // Masked domain: string // cookie domain path: string // cookie path expires: string | number // ISO 8601 timestamp, Unix seconds, or -1 for a session cookie httpOnly: boolean // the cookie's HttpOnly flag secure: boolean // the cookie's Secure flag sameSite: 'Lax' | 'Strict' | 'None' // the cookie's SameSite setting }> sessionCookies?: Array<{ // Same structure, the cookies of the old Google Labs sign-in, on an account first added before 2026-10-21, no longer used name: string // cookie name value: string // Masked domain: string // cookie domain path: string // cookie path expires: string | number // ISO 8601 timestamp, Unix seconds, or -1 for a session cookie httpOnly: boolean // the cookie's HttpOnly flag secure: boolean // the cookie's Secure flag sameSite: 'Lax' | 'Strict' | 'None' // the cookie's SameSite setting }> sessionData?: { // the old Google Labs sign-in, on an account first added before 2026-10-21, no longer used user: { // the Google account of that sign-in name: string // its display name email: string // its email image: string // its profile picture URL } expires: string // ISO 8601 timestamp, when that sign-in expired access_token: string // Masked } project: { // the account's Google Flow project, where generations go projectId: string // Google Flow project id projectTitle: string // project title, set when the project was created } projectEntity?: { // the project that holds the account's characters and custom voices, created by the first POST /characters or POST /voices projectId: string // Google Flow project id projectTitle: string // project title, set when the project was created } projectAgent?: { // the account's agent project, where agent chats run, created by the first POST /agent/chats projectId: string // Google Flow project id projectTitle: string // project title, set when the project was created } nextRefresh?: { // the next automatic session refresh, absent once a refresh stopped on an error messageId: string // Masked scheduledFor: string // ISO 8601 timestamp, every 2 to 3 days } setupSession?: string // the automated setup session that last added the account, present only when it was added that way health: string // "OK", otherwise the reason the account does not work and what to do error?: string // the error that stopped the account, the same text as health credits?: { // Only present when health is "OK" credits: number // Google Flow AI credits left on the account userPaygateTier: string // the account's Google plan: PAYGATE_TIER_NOT_PAID (Free), PAYGATE_TIER_ZERO (Plus), PAYGATE_TIER_ONE (Pro), PAYGATE_TIER_TIER1P5 (Ultra $99), PAYGATE_TIER_TWO (Ultra $199), or PAYGATE_TIER_UNKNOWN_<n> for a plan Google added that this API has not named yet sku: string // Google's plan code: G1_FREEMIUM, G1_TIER0, G1_TIER1, G1_TIER1P5, G1_TIER2 or SKU_UNKNOWN_<n> serviceTier?: string // SERVICE_TIER_ENTRY, SERVICE_TIER_INTERMEDIATE, SERVICE_TIER_ADVANCED or SERVICE_TIER_UNKNOWN_<n> topUpCredits?: number // the part of credits bought as top-ups, when Google reports it subscriptionCredits?: number // the part of credits that comes with the plan, when Google reports it } models?: { // Only present when health is "OK" videoModels: Array<{ // video models the account's Google plan can use, one per model key key: string // Google's own key for the model displayName: string // the model's name in the Google Flow web app: Veo 3.1 - Fast, Veo 3.1 - Quality, Veo 3.1 - Lite, Veo 3.1 - Lite [Lower Priority], Omni 1.1 Flash, Omni 1.2 Flash, Omni - Upsampler 360p, Veo 3.1 - Upsampler 1080P or Veo 3.1 - Upsampler 4K supportedAspectRatios: string[] // VIDEO_ASPECT_RATIO_LANDSCAPE and/or VIDEO_ASPECT_RATIO_PORTRAIT capabilities: string[] // e.g., ["VIDEO_MODEL_CAPABILITY_TEXT", "VIDEO_MODEL_CAPABILITY_AUDIO"] videoLengthSeconds: number // video length in seconds videoGenerationTimeSeconds: number // Google's estimate of the generation time in seconds creditCost: number // Credits charged per generation. 0 for the Ultra `_low_priority` keys and for the 720p and 1080p upsamplers on paid plans framesPerSecond: number // always 24 resolution: string // 360p or 720p, the generation output resolution. On an upsampler key it is the input resolution that key accepts paygateTier: string // the lowest plan that sees this model: PAYGATE_TIER_NOT_PAID, PAYGATE_TIER_ZERO, PAYGATE_TIER_ONE or PAYGATE_TIER_TWO accessType: string // always "MODEL_ACCESS_TYPE_GENERAL" modelAccessInfo: object // always {} modelMetadata: object // { veoModelName: "Beta Audio" } on Veo models, {} on the others }> } recommendations?: string[] // captcha setup advice, only when fewer than two captcha providers are configured } ``` </details> ### Examples **Curl** ``` bash curl -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v1/google-flow/accounts/john%40gmail.com" ``` **JavaScript** ``` javascript const token = 'YOUR_API_TOKEN'; const email = 'john@gmail.com'; const response = await fetch( `https://api.useapi.net/v1/google-flow/accounts/${encodeURIComponent(email)}`, { headers: { 'Authorization': `Bearer ${token}` } } ); const accountConfig = await response.json(); console.log('Account config:', accountConfig); console.log('Health:', accountConfig.health); console.log('Credits:', accountConfig.credits); ``` **Python** ``` python import requests from urllib.parse import quote token = 'YOUR_API_TOKEN' email = 'john@gmail.com' headers = {'Authorization': f'Bearer {token}'} response = requests.get( f'https://api.useapi.net/v1/google-flow/accounts/{quote(email)}', headers=headers ) account_config = response.json() print('Account config:', account_config) print('Health:', account_config.get('health')) print('Credits:', account_config.get('credits')) ``` ### Try It <script> async function apiExecuteGetGoogleFlowAccountsEmail() { const tokenElement = document.getElementById('input-token'); const emailElement = document.getElementById('input-email'); const data = { method: 'GET', headers: { 'Authorization': `Bearer ${tokenElement.value}` } }; await apiExecute( `https://api.useapi.net/v1/google-flow/accounts/${encodeURIComponent(emailElement.value)}`, 'input', data ); } </script> <form id="input" class="input-form" onsubmit="return false;"> <div class="input-field"> <div class="input-field-row"> <label for="input-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="input-token" type="text" class="input-element" required aria-required="true"> </label> <label for="input-email"><span>email (required)</span> <input id="input-email" type="text" class="input-element" required aria-required="true" placeholder="john@gmail.com"> </label> </div> <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteGetGoogleFlowAccountsEmail()">Go</button> </div> </form> <div id="input-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-google-flow-v1/get-google-flow-accounts === Document URL: https://useapi.net/docs/api-google-flow-v1/get-google-flow-accounts --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts description: "List all Google Flow accounts configured on your useapi.net subscription via GET accounts in the useapi.net Google Flow API v1." parent: Google Flow API nav_order: 300 --- ## List All Configured Accounts November 17, 2025 (November 16, 2026) --- List all configured Google Flow accounts. To get a specific account use [GET /accounts/`email`](/docs/api-google-flow-v1/get-google-flow-accounts-email). > **https://api.useapi.net/v1/google-flow/accounts** ### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Responses **200** **200 OK** Returns a map of all configured accounts, keyed by email address. ```json { "jane.doe@gmail.com": { "health": "OK", "backend": "flow", "created": "2025-11-09T22:02:04.802Z", "updated": "2026-10-22T16:04:11.512Z", "project": { "projectId": "a7e08e13-a6ea-4945-9841-cb4147e4f024", "projectTitle": "Nov 11 - 02:56" }, "nextRefresh": { "scheduledFor": "2026-10-23T16:11:37.000Z" } }, "john.smith@gmail.com": { "health": "Google shut down the old Google Labs sign-in on 2026-10-21. This account was added without the APISID and SAPISID cookies that the Google Flow sign-in needs, so it no longer works and cannot be refreshed. Add it again with the automated setup at https://useapi.net/assets/setup-browser/google-flow, which captures every cookie needed (guide: https://useapi.net/docs/start-here/setup-google-flow).", "backend": "labs", "created": "2025-11-10T02:56:58.864Z", "project": { "projectId": "47050a10-06f4-4469-8ab0-6d294c703508", "projectTitle": "Nov 11 - 02:56" } } } ``` If no accounts are configured, returns an empty object `{}`. **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` ### Model An object keyed by account email, each with the account's health, backend, project and next automatic refresh. <details markdown="block" class="model-details"> <summary>The accounts, keyed by email, field by field</summary> - `health` - `OK` when the account is ready, otherwise the reason it is not and what to do - `backend` - `flow` when the account runs on the flow.google.com cookies. `labs` marks an account added before 2026-09-12 without the `APISID` and `SAPISID` cookies, which stopped working on 2026-10-21. Every request for it answers `596`: add it again with the [automated setup](https://useapi.net/assets/setup-browser/google-flow) - `nextRefresh` - When the next automatic refresh runs, every 2 to 3 days An account first added before 2026-10-21 can also show `sessionData` left from the old Google Labs sign-in. The API no longer uses it. ```typescript // Map of email to account summary { [email: string]: { health: string // "OK", otherwise the reason the account does not work and what to do backend: 'flow' | 'labs' // flow: the account signs in with its `flow.google.com` cookies. labs: an account added // before 2026-09-12 that stopped working on 2026-10-21, add it again error?: string // the error that stopped the account, the same text as health created?: string // ISO 8601 timestamp, first add updated?: string // ISO 8601 timestamp, most recent add, absent on an account last added before 2026-09-16 sessionData?: { // left from the old Google Labs sign-in on an account first added before 2026-10-21, no longer used expires: string // ISO 8601 timestamp, when that old sign-in expired } project?: { // the account's Google Flow project, where generations go projectId: string // Google Flow project id projectTitle: string // project title, set when the project was created } nextRefresh?: { // the next automatic session refresh, absent once a refresh stopped on an error scheduledFor: string // ISO 8601 timestamp } } } ``` </details> ### Examples **Curl** ``` bash curl -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v1/google-flow/accounts" ``` **JavaScript** ``` javascript const token = 'YOUR_API_TOKEN'; const response = await fetch('https://api.useapi.net/v1/google-flow/accounts', { headers: { 'Authorization': `Bearer ${token}` } }); const accounts = await response.json(); console.log('Configured accounts:', accounts); ``` **Python** ``` python import requests token = 'YOUR_API_TOKEN' headers = {'Authorization': f'Bearer {token}'} response = requests.get('https://api.useapi.net/v1/google-flow/accounts', headers=headers) print('All accounts:', response.json()) ``` ### Try It <script> async function apiExecuteGetGoogleFlowAccounts() { const tokenElement = document.getElementById('input-token'); const data = { method: 'GET', headers: { 'Authorization': `Bearer ${tokenElement.value}` } }; await apiExecute('https://api.useapi.net/v1/google-flow/accounts', 'input', data); } </script> <form id="input" class="input-form" onsubmit="return false;"> <div class="input-field"> <div class="input-field-row"> <label for="input-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="input-token" type="text" class="input-element" required aria-required="true"> </label> </div> <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteGetGoogleFlowAccounts()">Go</button> </div> </form> <div id="input-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId-stream === Document URL: https://useapi.net/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId-stream --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> agent/chats/`chatId`/stream description: "Follow a Google Flow Agent chat live via GET agent/chats/chatId/stream in the useapi.net Google Flow API: Server-Sent Events for messages, approvals, turn ends and media, resumable." parent: Google Flow API nav_order: 1440 --- ## Stream an agent chat October 16, 2026 (November 16, 2026) --- Follow a chat live as [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) (SSE): the agent's messages as each one completes, its requests to spend credits, the end of each turn, and every image and video it makes, including videos that finish after the turn. One stream covers the whole chat, across every turn, until it closes. Start a chat with [POST /agent/chats](/docs/api-google-flow-v1/post-google-flow-agent-chats) and send more with [POST /agent/chats/`chatId`/messages](/docs/api-google-flow-v1/post-google-flow-agent-chats-chatId-messages). Read the stream with `fetch()` or any HTTP client that can send the `Authorization` header. The browser's `EventSource` cannot send it. - Each event has an `event:` line with its name and a `data:` line with one JSON object. Most events also have an `id:` line. - A new stream first sends a `chat` event, then replays the chat's history from Google (the agent's messages and approval requests of every turn, and the media of the last two turns), then a `replayed` event. Everything after `replayed` is live. - The stream does not repeat your own messages. They are in [GET /agent/chats/`chatId`](/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId). - To resume after a disconnect, reconnect with the last `id` you received, in the `Last-Event-ID` header or as `?after=`. The stream skips what you already have and goes on live. After a `media` event id it replays that turn from its start, so de-duplicate messages by `id`. - A `keepalive` event comes every 15 seconds. When nothing happens for 10 minutes and no video is still being made, an `idle` event comes and the stream closes. One connection lasts at most 60 minutes, then a `reconnect` event comes and the stream closes. Reconnect with `Last-Event-ID` when you want live updates again. - A turn keeps running when you close the stream. Nothing is lost: reconnect, or read the chat with GET. A stream that fails shows in your [usage stats](/docs/account-management/get-account-stats) (`bot=google-flow`) as model `agent-stream`, status `failed`. Streams that open and run normally do not appear there. > **https://api.useapi.net/v1/google-flow/agent/chats/`chatId`/stream?after=`after`** - `chatId` is **required**, URL-encoded in the path (it contains `:` and `@`), from [POST /agent/chats](/docs/api-google-flow-v1/post-google-flow-agent-chats) or [GET /agent/chats](/docs/api-google-flow-v1/get-google-flow-agent-chats). ##### Request Headers ``` yaml Authorization: Bearer {API token} Last-Event-ID: 1:847ad05d-6709-45a0-b75d-b15ea1f5efba # optional, resume after this id ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. - `Last-Event-ID` is optional, the last `id` you received. The stream sends what came after it. ##### Query Parameters - `after` is optional, the same as `Last-Event-ID`, for clients that cannot set headers. The header wins when both are sent. ##### Events | Event | `id` | Data | Meaning | |---|---|---|---| | `chat` | | `chatId`, `title`, `status`, `turns` | The stream is open. Always first. `status` is the chat's state, see [GET /agent/chats/`chatId`](/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId#chat-status). | | `message` | `<turn>:<messageId>` | `id`, `turn`, `items` | One complete message of the agent: its text, thinking, tool calls and tool results. See [Agent items](/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId#agent-items). | | `approval` | `<turn>:approval` | `turn`, `cost`, `images`, `videos` | The agent asks before it spends `cost` Flow credits on `images` images and `videos` videos. Answer within about 4 minutes with [POST /agent/chats/`chatId`/approval](/docs/api-google-flow-v1/post-google-flow-agent-chats-chatId-approval). | | `turn` | `<turn>:wait`, `<turn>:end` | `turn`, `status`, `error` | `<turn>:wait`: the turn waits for your answer (`waiting_approval`) and goes on once you answer, in the same turn. `<turn>:end`: the turn ended while the stream was open, `completed` (also after a request Google closed unanswered), `waiting_approval` or `failed` with an `error`, see [Turn errors](/docs/api-google-flow-v1/agent#turn-errors). | | `media` | `<turn>:m:<mediaId>` | the media object | An image or video the agent made, or a change of its status: `queued`, then `completed` with its `url`, or `failed`. See [Media](/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId#media). | | `replayed` | | `turns` | The history replay is done. Everything after it is live. | | `keepalive` | | `at` | Sent every 15 seconds. | | `idle` | | `message` | Nothing happened for 10 minutes. The stream closes. | | `reconnect` | | `message` | The connection reached 60 minutes. The stream closes: reconnect with `Last-Event-ID`. | | `error` | | `code`, `message` | The stream failed. Reconnect with `Last-Event-ID`. | ##### Responses **200** **200 OK** — `Content-Type: text/event-stream`. A chat that asked for a video, approved it, and waited for it (some messages and fields left out, text shortened): ``` event: chat data: {"chatId":"c-u12345-email:john@gmail.com-project:f166200a-ea22-461a-bc68-47ff6d3ee500-chat:2a0f1973-d554-4fbc-aa6b-0c372edf182e-bot:google-flow","status":"running","turns":0} event: replayed data: {"turns":0} id: 1:30387708-2905-484e-888c-967812b9f5d4 event: message data: {"id":"1:30387708-2905-484e-888c-967812b9f5d4","turn":1,"items":[{"kind":"text","text":"I'm going to generate a video of a paper boat floating on a calm pond using Veo 3.1 - Lite with a duration of 8 seconds."},{"kind":"thinking","text":"**Validating Initial Specs**\n\nI'm starting by ensuring \"Veo 3.1 - Lite\" is a valid model…"}]} id: 1:9be1460c-3fb8-4ff1-8f53-3fbce90435ed event: message data: {"id":"1:9be1460c-3fb8-4ff1-8f53-3fbce90435ed","turn":1,"items":[{"kind":"tool_call","tool":"ask_for_permission","args":{"text":"This will generate 1 video, costing 10 credits. Do you want to proceed?","total_cost":10,"num_images":0,"num_videos":1}}]} id: 1:approval event: approval data: {"turn":1,"cost":10,"images":0,"videos":1} id: 1:wait event: turn data: {"turn":1,"status":"waiting_approval"} id: 1:b3f9cea0-19f1-4fbb-a207-f3a9cc8c58f9 event: message data: {"id":"1:b3f9cea0-19f1-4fbb-a207-f3a9cc8c58f9","turn":1,"items":[{"kind":"tool_result","tool":"generate_video","result":{"media_id":"97aa051d-419f-40fd-a200-f5593d997822","workflow_id":"dce57a4a-481e-4b3f-a84f-0a7f20e0b41c","status":"queued","model_key":"veo_3_1_t2v_lite","display_name":"Veo 3.1 - Lite","prompt":"A paper boat floating on a calm pond"}}]} id: 1:m:97aa051d-419f-40fd-a200-f5593d997822 event: media data: {"turn":1,"referenceId":"user:12345-email:6a6f...-video:97aa051d-419f-40fd-a200-f5593d997822","mediaId":"97aa051d-419f-40fd-a200-f5593d997822","type":"video","status":"queued","tool":"generate_video","model":"veo_3_1_t2v_lite","displayName":"Veo 3.1 - Lite"} id: 1:847ad05d-6709-45a0-b75d-b15ea1f5efba event: message data: {"id":"1:847ad05d-6709-45a0-b75d-b15ea1f5efba","turn":1,"items":[{"kind":"text","text":"Your video of a paper boat on a calm pond has been scheduled. Feel free to check back in a few minutes!","ui":[…]}]} id: 1:end event: turn data: {"turn":1,"status":"completed"} event: keepalive data: {"at":"2026-10-16T22:04:00.064Z"} id: 1:m:97aa051d-419f-40fd-a200-f5593d997822 event: media data: {"turn":1,"referenceId":"user:12345-email:6a6f...-video:97aa051d-419f-40fd-a200-f5593d997822","mediaId":"97aa051d-419f-40fd-a200-f5593d997822","type":"video","status":"completed","tool":"generate_video","model":"veo_3_1_t2v_lite","displayName":"Veo 3.1 - Lite","url":"https://flow-content.google/video/97aa051d-419f-40fd-a200-f5593d997822?Expires=...&KeyName=labs-flow-prod-cdn-key&Signature=...","durationSec":8} ``` The `approve` was sent from another window while this stream was open, within about 4 minutes of the request (Google takes an answer only while the turn that asked is still open). Turn 1 then went on: it sent a second `turn` event when it ended. **400** **400 Bad Request** The path value is not a `chatId`. ```json { "error": "Path parameter chatId (not-a-chat-id) is not a chat id from POST /agent/chats or GET /agent/chats", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The `chatId` belongs to another useapi.net user. ```json { "error": "This chat belongs to another user", "code": 403 } ``` **404** **404 Not Found** The chat was deleted, or its account is not added. ```json { "error": "Chat not found: it was deleted or never existed", "code": 404 } ``` **503** **503 Service Unavailable** Google Flow could not be reached, and nothing happened. Retry shortly. ```json { "error": "Google Flow is not reachable right now and could not read the chat. Retry", "code": 503 } ``` **596** **596 Session Error** The account's Google session is no longer valid. Delete the account with [DELETE /accounts/`email`](/docs/api-google-flow-v1/delete-google-flow-accounts-email) and add it again by following [Setup Google Flow](/docs/start-here/setup-google-flow). ##### Model The `data:` JSON of each event: <details markdown="block" class="model-details"> <summary>Each stream event, field by field</summary> ```typescript // event: chat { chatId: string, // the chat's id title?: string, // Google's title for the chat, once it has one status: 'running' | 'waiting_approval' | 'failed' | 'idle', // as GET /agent/chats/{chatId} reports it turns: number // turns in the chat so far } // event: message, id <turn>:<messageId> { id: string // <turn>:<messageId>, the same as the event's id turn: number // the turn the message belongs to items: ( // what the agent did in this message, in order: a reply (text), its reasoning (thinking), // a tool call (tool_call), what a tool returned (tool_result) or an error Google reported (error) | { kind: 'text', // a reply text: string, // the readable text choices?: { // options the agent offers, such as a tile for each image or video it made label: string, // the option's text value?: string, // the option's value mediaId?: string, // the image or video the option shows description?: string // the option's description }[], ui?: unknown // the agent's raw reply layout as Google sends it } | { kind: 'thinking', // the agent's reasoning text: string // as Google shows it } | { kind: 'tool_call', // a tool the agent called tool: string, // e.g. `generate_image`, `generate_video` or `ask_for_permission` (the approval request) args: Record<string, unknown> // what the agent passed to the tool } | { kind: 'tool_result', // what a tool returned tool: string, // the tool's name result: Record<string, unknown> // a generation result carries `media_id`, status and `display_name` } | { kind: 'error', // an error Google reported in the turn code: unknown // Google's error code } )[] } // event: approval, id <turn>:approval { turn: number // the turn that asks cost?: number // Google Flow credits it will spend images?: number // images it will make videos?: number // videos it will make } // event: turn, id <turn>:wait (waiting for your answer) or <turn>:end { turn: number // the turn status: 'completed' | 'waiting_approval' | 'failed' // waiting_approval: the turn waits for your answer. completed or failed: it ended error?: { // only on a failed turn: why it failed code: string // INTERRUPTED (the connection to Google broke), GOOGLE_ERROR (Google ended or refused the turn), // UNREADABLE_ANSWER (no readable reply), TIMEOUT (past Google's 10-minute limit), CAPTCHA_FAILED // (Google refused every captcha, nothing ran), AGENT_QUOTA (Google's daily agent limit) or // NOT_STARTED (the turn was never sent to Google, nothing ran) message: string // what went wrong httpStatus?: number // the HTTP status of the failure } } // event: media, id <turn>:m:<mediaId> { turn: number // the turn that made it referenceId: string // the id to reuse as a reference in POST /images, POST /videos or your next message mediaId: string // Google's media id type: 'image' | 'video' // image or video status: 'queued' | 'completed' | 'failed' | 'error' | string // queued or running: being made. completed: ready. // failed: Google could not make it. error: the tool refused it tool: string // the tool that made it, e.g. `generate_image` workflowId?: string // Google's workflow id that holds the media model?: string // Google's own key for the model that ran displayName?: string // the model name the Google Flow web app shows, e.g. Veo 3.1 - Lite url?: string // completed only, expires after about 6 hours durationSec?: number // a finished video's length in seconds, when Google reports it (not on images) error?: string // Google's error code (error) or error message (failed) failureReasons?: string[] // Google's failure reasons, failed videos only } // event: replayed { turns: number // turns in the chat when the replay ended } // event: keepalive { at: string // ISO 8601 timestamp, when it was sent } // event: idle, reconnect { message: string // why the stream closes and how to go on } // event: error { code: number // 503 message: string // what went wrong, reconnect with Last-Event-ID } ``` Errors before the stream opens return JSON, as in the response tabs above. </details> ##### Examples **Curl** ``` bash CHATID="c-u12345-email:john@gmail.com-project:f166200a-...-chat:2a0f1973-...-bot:google-flow" curl -N -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v1/google-flow/agent/chats/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$CHATID")/stream" ``` The `-N` flag turns off buffering, so events print as they arrive. **JavaScript** ``` javascript const token = 'YOUR_API_TOKEN' const chatId = 'chatId from POST /agent/chats' let lastEventId = '' const response = await fetch(`https://api.useapi.net/v1/google-flow/agent/chats/${encodeURIComponent(chatId)}/stream`, { headers: { 'Authorization': `Bearer ${token}`, ...(lastEventId && { 'Last-Event-ID': lastEventId }) } }) const reader = response.body.getReader() const decoder = new TextDecoder() let buffer = '' for (;;) { const { done, value } = await reader.read() if (done) break buffer += decoder.decode(value, { stream: true }) const blocks = buffer.split('\n\n') buffer = blocks.pop() for (const block of blocks) { const field = name => block.split('\n').find(line => line.startsWith(`${name}:`))?.slice(name.length + 1).trim() const event = field('event') const data = JSON.parse(field('data') ?? 'null') if (field('id')) lastEventId = field('id') if (event === 'message') for (const item of data.items) if (item.kind === 'text' && item.text) console.log('agent:', item.text) if (event === 'approval') console.log(`the agent asks to spend ${data.cost} credits`) if (event === 'media' && data.status === 'completed') console.log(data.type, data.url) if (event === 'turn') console.log(`turn ${data.turn} ${data.status}`) } } ``` **Python** ``` python import json, requests from urllib.parse import quote token = 'YOUR_API_TOKEN' chatId = 'chatId from POST /agent/chats' url = f'https://api.useapi.net/v1/google-flow/agent/chats/{quote(chatId, safe="")}/stream' event, last_event_id = None, None with requests.get(url, headers={'Authorization': f'Bearer {token}'}, stream=True) as r: for line in r.iter_lines(decode_unicode=True): if line.startswith('id:'): last_event_id = line[3:].strip() elif line.startswith('event:'): event = line[6:].strip() elif line.startswith('data:'): data = json.loads(line[5:]) if event == 'message': for item in data['items']: if item['kind'] == 'text' and item['text']: print('agent:', item['text']) elif event == 'approval': print(f"the agent asks to spend {data.get('cost')} credits") elif event == 'media' and data['status'] == 'completed': print(data['type'], data['url']) elif event == 'turn': print(f"turn {data['turn']} {data['status']}") ``` === URL: https://useapi.net/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId === Document URL: https://useapi.net/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> agent/chats/`chatId` description: "Read a Google Flow Agent chat via GET agent/chats/chatId in the useapi.net Google Flow API: every turn, the agent's messages, media with status and fresh links, and the chat's state." parent: Google Flow API nav_order: 1450 --- ## Read an agent chat October 16, 2026 (November 16, 2026) --- Read a whole chat from Google: each turn with your message, everything the agent did in reply, the images and videos it made with their status and links, and where the chat stands now. Use it to show a chat, to check on a turn after a `504` or a `502`, to see whether a video has finished, or to get fresh media links. To follow a chat live, use [GET /agent/chats/`chatId`/stream](/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId-stream). Media links point to Google and expire about 6 hours after they are issued. Each read brings the newest 50 media items up to date and gives finished ones a fresh link. Pass `media=false` for a faster read that leaves media as the agent reported them, without links. > **https://api.useapi.net/v1/google-flow/agent/chats/`chatId`?media=`media`** - `chatId` is **required**, URL-encoded in the path (it contains `:` and `@`), from [POST /agent/chats](/docs/api-google-flow-v1/post-google-flow-agent-chats) or [GET /agent/chats](/docs/api-google-flow-v1/get-google-flow-agent-chats). ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `media` is optional. Set `false` to skip the media status and link refresh. Default: `true`. ##### Responses **200** **200 OK** A chat where the agent asked before making a video, the request was approved, and the video finished (`ui` and some items left out): ```json { "chatId": "c-u12345-email:john@gmail.com-project:f166200a-ea22-461a-bc68-47ff6d3ee500-chat:2a0f1973-d554-4fbc-aa6b-0c372edf182e-bot:google-flow", "email": "john@gmail.com", "projectId": "f166200a-ea22-461a-bc68-47ff6d3ee500", "created": "2026-10-16T22:03:14.000Z", "updated": "2026-10-16T22:03:52.410Z", "status": "idle", "pendingApproval": null, "lastError": null, "turns": [ { "turn": 1, "message": { "text": "Make one 8 second video with Veo 3.1 - Lite of a paper boat floating on a calm pond.", "references": [] }, "agent": [ { "kind": "text", "text": "I'm going to generate a video of a paper boat floating on a calm pond using Veo 3.1 - Lite with a duration of 8 seconds." }, { "kind": "tool_call", "tool": "ask_for_permission", "args": { "text": "This will generate 1 video, costing 10 credits. Do you want to proceed?", "total_cost": 10, "num_images": 0, "num_videos": 1 } }, { "kind": "tool_result", "tool": "generate_video", "result": { "media_id": "97aa051d-419f-40fd-a200-f5593d997822", "workflow_id": "dce57a4a-481e-4b3f-a84f-0a7f20e0b41c", "status": "queued", "model_key": "veo_3_1_t2v_lite", "display_name": "Veo 3.1 - Lite", "prompt": "A paper boat floating on a calm pond" } }, { "kind": "text", "text": "Your video of a paper boat on a calm pond has been scheduled. Feel free to check back in a few minutes!" } ], "media": [ { "referenceId": "user:12345-email:6a6f...-video:97aa051d-419f-40fd-a200-f5593d997822", "mediaId": "97aa051d-419f-40fd-a200-f5593d997822", "type": "video", "status": "completed", "tool": "generate_video", "workflowId": "dce57a4a-481e-4b3f-a84f-0a7f20e0b41c", "model": "veo_3_1_t2v_lite", "displayName": "Veo 3.1 - Lite", "url": "https://flow-content.google/video/97aa051d-419f-40fd-a200-f5593d997822?Expires=...&KeyName=labs-flow-prod-cdn-key&Signature=...", "durationSec": 8 } ] } ] } ``` A chat waiting for an approval (`ui` left out): ```json { "chatId": "c-u12345-email:john@gmail.com-project:f166200a-ea22-461a-bc68-47ff6d3ee500-chat:7f172583-43db-4907-92fa-a8cba64e7cd3-bot:google-flow", "email": "john@gmail.com", "projectId": "f166200a-ea22-461a-bc68-47ff6d3ee500", "title": "Green Ball Rolling Motion", "created": "2026-11-11T02:31:33.950Z", "updated": "2026-11-11T02:31:52.412Z", "status": "waiting_approval", "pendingApproval": { "turn": 1, "cost": 4, "images": 0, "videos": 1 }, "lastError": null, "turns": [ { "turn": 1, "message": { "text": "Generate one 4 second video of a green ball rolling. Cheapest video model.", "references": [] }, "agent": [ { "kind": "text", "text": "I'll generate one 4-second video of a green ball rolling using Omni 1.1 Flash at 360p resolution." }, { "kind": "tool_call", "tool": "ask_for_permission", "args": { "text": "This will generate 1 video, costing 4 credits. Do you want to proceed?", "total_cost": 4, "num_images": 0, "num_videos": 1 } } ], "media": [] } ] } ``` **400** **400 Bad Request** The path value is not a `chatId`. ```json { "error": "Path parameter chatId (not-a-chat-id) is not a chat id from POST /agent/chats or GET /agent/chats", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The `chatId` belongs to another useapi.net user. ```json { "error": "This chat belongs to another user", "code": 403 } ``` **404** **404 Not Found** The chat was deleted, or its account is not added. ```json { "error": "Chat not found: it was deleted or never existed", "code": 404 } ``` **503** **503 Service Unavailable** Google Flow could not be reached, and nothing happened. Retry shortly. ```json { "error": "Google Flow is not reachable right now and could not read the chat. Retry", "code": 503 } ``` **596** **596 Session Error** The account's Google session is no longer valid. Delete the account with [DELETE /accounts/`email`](/docs/api-google-flow-v1/delete-google-flow-accounts-email) and add it again by following [Setup Google Flow](/docs/start-here/setup-google-flow). ##### Chat status | `status` | Meaning | |---|---| | `running` | A turn is running. Sending a message answers `409` until it ends. | | `waiting_approval` | The agent asks before it spends credits, see `pendingApproval`. Answer with [POST /agent/chats/`chatId`/approval](/docs/api-google-flow-v1/post-google-flow-agent-chats-chatId-approval), or send a new message to move on. | | `failed` | The last turn failed, see `lastError`. Send the next message when you are ready. | | `idle` | Nothing is running. Send the next message at any time. | `lastError` is kept for about 15 minutes after the turn ends. After that the chat reads `idle`, and the history shows what the cut-short turn made. Its `code` is one of the [turn errors](/docs/api-google-flow-v1/agent#turn-errors). ##### Agent items Each turn's `agent` array lists what the agent did, in order: | `kind` | Fields | Meaning | |---|---|---| | `text` | `text`, `choices`, `ui` | A reply. `text` is the readable text. `choices` are options the agent offers, such as a tile for each image or video it made, with a `label`, `value`, `description` and the `mediaId` of the image or video the option shows. To pick one, send its text as your next message. `ui` is the agent's raw reply layout as Google sends it, for apps that want to draw it the way the Flow web app does. | | `thinking` | `text` | The agent's reasoning, as Google shows it. | | `tool_call` | `tool`, `args` | A tool the agent called, for example `generate_image`, `generate_video` or `ask_for_permission` (the approval request). | | `tool_result` | `tool`, `result` | What the tool returned. A generation result carries `media_id`, `status` and `display_name`, and on a refusal `status` `error` with Google's `error_code`. | | `error` | `code` | An error Google reported inside the turn. | The tool names and their `args` and `result` come from Google unchanged, so new ones can appear at any time. ##### Media Each turn's `media` array lists the images and videos the agent made in that turn: - `referenceId` is the id to reuse: pass it as `referenceImage_N` or `referenceVideo_1` to [POST /images](/docs/api-google-flow-v1/post-google-flow-images), [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) or your next agent message. - `status` is `queued` while a video is being made, `completed` when it is ready, and `failed` when Google could not make it, with `error` and `failureReasons`. An item the agent's tool refused right away has status `error` with Google's code in `error`. - `url` is the link to the file, on `completed` items only. It expires about 6 hours after it was issued. Images are ready when the turn ends. Videos usually finish a minute or two later. ##### Model The chat with its status, the spend approval it waits for, the last error and every turn. <details markdown="block" class="model-details"> <summary>The chat and its turns, field by field</summary> ```typescript { // TypeScript, all fields are optional chatId: string // the chat's id, it carries the account, the project and Google's chat id email: string // the account the chat runs on projectId: string // the Google Flow project the chat is in title?: string // Google titles each chat, usually soon after its first turn created: string // ISO 8601 timestamp, from Google updated: string // ISO 8601 timestamp of the chat's last activity, from Google status: 'running' | 'waiting_approval' | 'failed' | 'idle' // running: a turn is in progress. waiting_approval: the // agent waits for your spend approval. failed: the last turn ended with an error, see // lastError. idle: nothing is in progress pendingApproval: { // the spend approval the chat waits for, null when there is none turn: number // the turn that asks cost?: number // Google Flow credits images?: number // images it will make videos?: number // videos it will make } | null lastError: { // why the last turn failed, null otherwise; kept for about 15 minutes after the turn ended turn: number // the turn that failed code: string // INTERRUPTED (the connection to Google broke), GOOGLE_ERROR (Google ended or refused the // turn), UNREADABLE_ANSWER (no readable reply), TIMEOUT (past Google's 10-minute limit), // CAPTCHA_FAILED (Google refused every captcha, nothing ran), AGENT_QUOTA (Google's daily // agent limit) or NOT_STARTED (the turn was never sent to Google, nothing ran) message: string // what went wrong httpStatus?: number // the HTTP status of the failure at: string // ISO 8601 timestamp, when the turn ended } | null turns: { // every turn of the chat, oldest first turn: number // turn number, from 1 message: { // your message text: string // @-mentions read as @Image I, @Character I or the voice name references: { // the media, voices and characters your message used type: 'media' | 'voice' | 'character', // what it is id: string // Google's id of that media, voice or character }[] } agent: ( // what the agent did in reply, in order | { kind: 'text', // a reply text: string, // the readable text choices?: { // options the agent offers, such as a tile for each image or video it made label: string, // the option's text value?: string, // the option's value mediaId?: string, // the image or video the option shows description?: string // the option's description }[], ui?: unknown // the agent's raw reply layout as Google sends it } | { kind: 'thinking', // the agent's reasoning text: string // as Google shows it } | { kind: 'tool_call', // a tool the agent called tool: string, // e.g. `generate_image`, `generate_video` or `ask_for_permission` (the approval request) args: Record<string, unknown> // what the agent passed to the tool } | { kind: 'tool_result', // what a tool returned tool: string, // the tool's name result: Record<string, unknown> // a generation result carries `media_id`, status and `display_name` } | { kind: 'error', // an error Google reported in the turn code: unknown // Google's error code } )[] media: { // the images and videos this turn made referenceId: string // the id to reuse as a reference in POST /images, POST /videos or your next message mediaId: string // Google's media id type: 'image' | 'video' // image or video status: 'queued' | 'completed' | 'failed' | 'error' | string // queued or running: being made. completed: ready. // failed: Google could not make it. error: the tool refused it tool: string // the tool that made it, e.g. `generate_image` workflowId?: string // Google's workflow id that holds the media model?: string // Google's own key for the model that ran displayName?: string // the model name the Google Flow web app shows, e.g. Veo 3.1 - Lite url?: string // completed only, expires after about 6 hours durationSec?: number // a finished video's length in seconds, when Google reports it (not on images) error?: string // Google's error code (error) or error message (failed) failureReasons?: string[] // Google's failure reasons, failed videos only }[] }[] } ``` </details> ##### Examples **Curl** ``` bash CHATID="c-u12345-email:john@gmail.com-project:f166200a-...-chat:2a0f1973-...-bot:google-flow" curl -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v1/google-flow/agent/chats/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$CHATID")" ``` **JavaScript** ``` javascript const token = 'YOUR_API_TOKEN' const chatId = 'chatId from POST /agent/chats' const response = await fetch(`https://api.useapi.net/v1/google-flow/agent/chats/${encodeURIComponent(chatId)}`, { headers: { 'Authorization': `Bearer ${token}` } }) const chat = await response.json() console.log(chat.status) for (const turn of chat.turns) for (const m of turn.media) console.log(turn.turn, m.type, m.status, m.url ?? '') ``` **Python** ``` python import requests from urllib.parse import quote token = 'YOUR_API_TOKEN' chatId = 'chatId from POST /agent/chats' r = requests.get( f'https://api.useapi.net/v1/google-flow/agent/chats/{quote(chatId, safe="")}', headers={'Authorization': f'Bearer {token}'}, ) chat = r.json() print(chat['status']) for turn in chat['turns']: for m in turn['media']: print(turn['turn'], m['type'], m['status'], m.get('url', '')) ``` === URL: https://useapi.net/docs/api-google-flow-v1/get-google-flow-agent-chats === Document URL: https://useapi.net/docs/api-google-flow-v1/get-google-flow-agent-chats --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> agent/chats description: "List a Google Flow account's agent chats via GET agent/chats in the useapi.net Google Flow API, including chats started in the Flow web app, newest first." parent: Google Flow API nav_order: 1460 --- ## List agent chats October 16, 2026 (November 16, 2026) --- List the agent chats of one Google Flow account in one project, newest activity first. The list comes from Google, so it includes chats started in the Flow web app in the same project, and it is how you find a `chatId` you lost. Without `projectId`, the list covers the account's own agent project, the one [POST /agent/chats](/docs/api-google-flow-v1/post-google-flow-agent-chats) uses by default. An account that has never chatted through the API has none yet, and the list is empty. > **https://api.useapi.net/v1/google-flow/agent/chats?email=`email`&projectId=`projectId`** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `email` is **required**, the Google Flow account, see [GET /accounts](/docs/api-google-flow-v1/get-google-flow-accounts). - `projectId` is optional, a Flow project of the account, from [GET /assets/projects/`email`](/docs/api-google-flow-v1/get-google-flow-assets-projects-email). Default: the account's agent project. ##### Responses **200** **200 OK** ```json { "chats": [ { "chatId": "c-u12345-email:john@gmail.com-project:f166200a-ea22-461a-bc68-47ff6d3ee500-chat:41fbc779-b18f-468a-ac02-f31a3bde30b0-bot:google-flow", "email": "john@gmail.com", "title": "Creative Asset Component Overview", "created": "2026-10-16T21:48:53.000Z", "updated": "2026-10-16T21:49:19.646Z", "running": false }, { "chatId": "c-u12345-email:john@gmail.com-project:f166200a-ea22-461a-bc68-47ff6d3ee500-chat:77bd5e0b-2a34-4ee0-ad13-de366e41622c-bot:google-flow", "email": "john@gmail.com", "title": "Flow Creative Capabilities Overview", "created": "2026-10-16T21:47:07.000Z", "updated": "2026-10-16T21:47:39.280Z", "running": false } ] } ``` **400** **400 Bad Request** ```json { "error": "Parameter email is required", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **404** **404 Not Found** The account is not added, or `projectId` is not a project of the account. ```json { "error": "Google Flow account john@gmail.com not found", "code": 404 } ``` When `projectId` is not a project of the account: ```json { "error": "Project not found", "code": 404 } ``` **503** **503 Service Unavailable** Google Flow could not be reached, and nothing happened. Retry shortly. ```json { "error": "Google Flow is not reachable right now and could not list the chats. Retry", "code": 503 } ``` **596** **596 Session Error** The account's Google session is no longer valid. Delete the account with [DELETE /accounts/`email`](/docs/api-google-flow-v1/delete-google-flow-accounts-email) and add it again by following [Setup Google Flow](/docs/start-here/setup-google-flow). ##### Model The account's agent chats, newest activity first, each with its `chatId`, title and whether a turn is running. <details markdown="block" class="model-details"> <summary>The list of chats, field by field</summary> ```typescript { // TypeScript, all fields are optional chats: { // the chats, newest activity first chatId: string // the chat's id for the other agent chat calls email: string // the account the chat runs on title?: string // Google's title for the chat created?: string // ISO 8601 timestamp, from Google updated?: string // last activity running: boolean // a turn is running now }[] } ``` </details> ##### Examples **Curl** ``` bash curl -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v1/google-flow/agent/chats?email=john%40gmail.com" ``` **JavaScript** ``` javascript const token = 'YOUR_API_TOKEN' const response = await fetch(`https://api.useapi.net/v1/google-flow/agent/chats?email=${encodeURIComponent('john@gmail.com')}`, { headers: { 'Authorization': `Bearer ${token}` } }) const { chats } = await response.json() chats.forEach(c => console.log(c.updated, c.title, c.chatId)) ``` **Python** ``` python import requests token = 'YOUR_API_TOKEN' r = requests.get( 'https://api.useapi.net/v1/google-flow/agent/chats', headers={'Authorization': f'Bearer {token}'}, params={'email': 'john@gmail.com'}, ) for c in r.json()['chats']: print(c.get('updated'), c.get('title'), c['chatId']) ``` === URL: https://useapi.net/docs/api-google-flow-v1/get-google-flow-agent-settings === Document URL: https://useapi.net/docs/api-google-flow-v1/get-google-flow-agent-settings --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> agent/settings description: "Read a Flow project's agent settings via GET agent/settings in the useapi.net Google Flow API: approval, instructions, default models and the plan's models with credits." parent: Google Flow API nav_order: 1490 --- ## Read agent settings October 16, 2026 (November 16, 2026) --- Read the agent settings of a Flow project: whether the agent asks before it spends credits, the standing instructions it follows in every chat of the project, and the default image and video models it uses. These are the same settings as the agent panel in the Flow web app. Change them with [PUT /agent/settings](/docs/api-google-flow-v1/put-google-flow-agent-settings). Without `projectId`, this reads the account's own agent project, the one [POST /agent/chats](/docs/api-google-flow-v1/post-google-flow-agent-chats) uses by default. An account that has no agent project yet answers `projectId: null` and the defaults. The response also lists `models`, the image and video models the account's Google plan has, each with what its cheapest generation (the shortest length at the lowest resolution) costs on that plan in `credits` (`0` is free). Pick the default models for [PUT /agent/settings](/docs/api-google-flow-v1/put-google-flow-agent-settings) from this list. When the account's plan is not known, every model is listed without `credits`. `models` is `null` when Google's model list could not be read. The list is read from Google at most once an hour per account. > **https://api.useapi.net/v1/google-flow/agent/settings?email=`email`&projectId=`projectId`** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `email` is **required**, the Google Flow account, see [GET /accounts](/docs/api-google-flow-v1/get-google-flow-accounts). - `projectId` is optional, a Flow project of the account, from [GET /assets/projects/`email`](/docs/api-google-flow-v1/get-google-flow-assets-projects-email). Default: the account's agent project. ##### Responses **200** **200 OK** ```json { "projectId": "f166200a-ea22-461a-bc68-47ff6d3ee500", "approval": "ask", "instructions": [ { "id": "2157F442-D2DB-4C22-BC53-E4B14FA4D667", "text": "Keep every answer short. Prefer free image models.", "enabled": true, "references": [] }, { "id": "C4B70536-E836-431B-B86B-0E3816CCE6B9", "text": "A switched-off instruction.", "enabled": false, "references": [] } ], "imageDefaults": { "model": "nano-banana-2", "aspectRatio": "16:9", "count": 1 }, "videoDefaults": { "model": "veo-3.1-fast", "aspectRatio": "16:9", "count": 1 }, "models": { "image": [ { "model": "nano-banana-pro", "label": "Nano Banana Pro", "credits": 0 }, { "model": "nano-banana-2-lite", "label": "Nano Banana 2 Lite", "credits": 0 }, { "model": "nano-banana-2", "label": "Nano Banana 2.1", "credits": 0 } ], "video": [ { "model": "omni-flash-1.2", "label": "Omni 1.2 Flash", "credits": 3 }, { "model": "omni-flash", "label": "Omni 1.1 Flash", "credits": 4 }, { "model": "veo-3.1-lite", "label": "Veo 3.1 - Lite", "credits": 10 }, { "model": "veo-3.1-fast", "label": "Veo 3.1 - Fast", "credits": 20 }, { "model": "veo-3.1-quality", "label": "Veo 3.1 - Quality", "credits": 100 } ] } } ``` Ultra plans also list `{ "model": "veo-3.1-lite-low-priority", "label": "Veo 3.1 - Lite [Lower Priority]" }` with its credits. An account Google has given Omni 1.2 Flash (rolling out from November 5, 2026) also lists `{ "model": "omni-flash-1.2", "label": "Omni 1.2 Flash" }` with its credits. A project whose settings were never changed: ```json { "projectId": "f166200a-ea22-461a-bc68-47ff6d3ee500", "approval": "ask", "instructions": [], "imageDefaults": null, "videoDefaults": null, "models": { "image": [ { "model": "nano-banana-pro", "label": "Nano Banana Pro", "credits": 0 }, { "model": "nano-banana-2-lite", "label": "Nano Banana 2 Lite", "credits": 0 }, { "model": "nano-banana-2", "label": "Nano Banana 2.1", "credits": 0 } ], "video": [ { "model": "omni-flash-1.2", "label": "Omni 1.2 Flash", "credits": 3 }, { "model": "omni-flash", "label": "Omni 1.1 Flash", "credits": 4 }, { "model": "veo-3.1-lite", "label": "Veo 3.1 - Lite", "credits": 10 }, { "model": "veo-3.1-fast", "label": "Veo 3.1 - Fast", "credits": 20 }, { "model": "veo-3.1-quality", "label": "Veo 3.1 - Quality", "credits": 100 } ] } } ``` **400** **400 Bad Request** ```json { "error": "Parameter email is required", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **404** **404 Not Found** The account is not added, or `projectId` is not a project of the account. ```json { "error": "Google Flow account john@gmail.com not found", "code": 404 } ``` When `projectId` is not a project of the account: ```json { "error": "Project not found", "code": 404 } ``` **503** **503 Service Unavailable** Google Flow could not be reached, and nothing happened. Retry shortly. ```json { "error": "Google Flow is not reachable right now and could not read the agent settings. Retry", "code": 503 } ``` **596** **596 Session Error** The account's Google session is no longer valid. Delete the account with [DELETE /accounts/`email`](/docs/api-google-flow-v1/delete-google-flow-accounts-email) and add it again by following [Setup Google Flow](/docs/start-here/setup-google-flow). ##### Model The agent settings of the account's project: the approval mode, the instructions, the image and video defaults and the models. <details markdown="block" class="model-details"> <summary>The agent settings, field by field</summary> ```typescript { // TypeScript, all fields are optional projectId: string | null // null: the account has no agent project yet approval: 'ask' | 'auto' // ask: the agent asks before it spends credits instructions: { // up to 3 id: string // the instruction's id title?: string // its title, when it has one text: string // what the agent is told enabled: boolean // true: the agent follows it in every chat of the project references: string[] // media ids of the instruction's reference images }[] imageDefaults: { model: string // the model's name as models.image lists it aspectRatio: string // 16:9, 9:16, 1:1, 4:3 or 3:4 count: number // images per request, 1 to 4 } | null // null: never set videoDefaults: { // the video model, aspect ratio and count the agent uses by default, null: never set model: string // the model's name as models.video lists it aspectRatio: string // 16:9 or 9:16 count: number // videos per request, 1 to 4 } | null models: { // the models the account's Google plan has, null: Google's model list could not be read image: { // image models model: string // the name to use in imageDefaults label: string // the name the Google Flow web app shows credits?: number // lowest cost of one generation on the account's plan, 0 is free, absent when the plan is not known }[] video: { // video models model: string // the name to use in videoDefaults label: string // the name the Google Flow web app shows credits?: number // lowest cost of one generation on the account's plan, 0 is free, absent when the plan is not known }[] } | null } ``` </details> ##### Examples **Curl** ``` bash curl -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v1/google-flow/agent/settings?email=john%40gmail.com" ``` **JavaScript** ``` javascript const token = 'YOUR_API_TOKEN' const response = await fetch(`https://api.useapi.net/v1/google-flow/agent/settings?email=${encodeURIComponent('john@gmail.com')}`, { headers: { 'Authorization': `Bearer ${token}` } }) console.log(await response.json()) ``` **Python** ``` python import requests token = 'YOUR_API_TOKEN' r = requests.get( 'https://api.useapi.net/v1/google-flow/agent/settings', headers={'Authorization': f'Bearer {token}'}, params={'email': 'john@gmail.com'}, ) print(r.json()) ``` === URL: https://useapi.net/docs/api-google-flow-v1/get-google-flow-assets-media-email === Document URL: https://useapi.net/docs/api-google-flow-v1/get-google-flow-assets-media-email --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> assets/media/`email` description: "Read the media held in one Google Flow project — ids, types, dates and which entries are uploads — via GET assets/media/email in the useapi.net Google Flow API v1." parent: Google Flow API nav_order: 530 --- ## List Project Media September 1, 2026 (November 16, 2026) --- List the media held in one project on a Google Flow account. Every entry comes back with a `mediaGenerationId` you can pass straight to [DELETE /assets/`email`](/docs/api-google-flow-v1/delete-google-flow-assets-email) or [GET /assets/`mediaGenerationId`](/docs/api-google-flow-v1/get-google-flow-assets-mediagenerationid). This is the endpoint that shows you your uploads. Files you send with [POST /assets](/docs/api-google-flow-v1/post-google-flow-assets-email) stay on the Google account after the generation that used them is finished, and nothing removes them on its own — they simply accumulate. `likelyUploads` counts them, and `likelyUpload` marks each one. Find a project id with [GET /assets/projects/`email`](/docs/api-google-flow-v1/get-google-flow-assets-projects-email), or omit `projectId` to read the project this account currently writes to. ### What is listed Two collections are merged into one `media` array: the project's own timeline, and media attached to the project from elsewhere. The second is where uploads normally sit, and it is usually much the larger of the two — on a real account the project's own timeline held 8 entries against 292 attached ones, every one of them an upload, some more than nine months old. Both are listed together because both are stored on the account, both count toward it, and both can be deleted the same way. ### Uploads vs generated media `likelyUpload` reflects how Google itself recorded the media — as something you uploaded, or as something Flow generated. It is not inferred from the presence of a prompt or any other heuristic. It is `likelyUpload` rather than `isUpload` for one reason: an entry Google records as neither stays `false`. Those show up as `mediaType: "OTHER"` and are left out of the `likelyUploads` count rather than being offered up for deletion on a guess. ### Very large projects One call returns at most 25,000 entries. When a project holds more, the response carries `truncated: true`. The project's own timeline comes first, so the attached uploads show up once the timeline holds fewer than 25,000 entries. There is no cursor. Google sends the whole project on every call, in no particular order, so a later page would cost as much as reading everything. To work through a large project, delete the entries you no longer need with [DELETE /assets/`email`](/docs/api-google-flow-v1/delete-google-flow-assets-email) and call again — the next call returns entries the previous one did not. A call that keeps getting back entries you want to keep will keep returning them. A project of tens of thousands of entries is also slow to read: expect 20 seconds to over a minute per call. The fastest way out is to start the account on a fresh project: 1. In Google Flow, delete the project whose id is `project.projectId` in [GET /accounts/`email`](/docs/api-google-flow-v1/get-google-flow-accounts-email). 2. Add the account again with [POST /accounts](/docs/api-google-flow-v1/post-google-flow-accounts). The API sees the project is gone and creates a new, empty one for the account. Everything in the deleted project is gone for good. Characters and voices are kept: they live in a separate project. > **https://api.useapi.net/v1/google-flow/assets/media/`email`?projectId=** ### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Path Parameters - `email` is **required**, URL-encoded. The Google Flow account holding the project. ### Query Parameters - `projectId` is optional. Defaults to the project this account currently writes to. Pass a `projectId` from [GET /assets/projects/`email`](/docs/api-google-flow-v1/get-google-flow-assets-projects-email) to read any other project on the account. It is required when the account has no project on file, in which case the call returns `400` without it. One call returns up to 25,000 entries. See [Very large projects](#very-large-projects) when a project holds more. ### Responses **200** **200 OK** ```json { "email": "john@gmail.com", "projectId": "3a18acb1-2c6e-478b-bcec-2df19cb8edab", "count": 591, "likelyUploads": 388, "media": [ { "mediaGenerationId": "user:12345-email:6a6f...-image:0115f3c1-...redacted...", "mediaType": "IMAGE", "createTime": "2026-06-14T00:03:47.401463Z", "likelyUpload": true }, { "mediaGenerationId": "user:12345-email:6a6f...-video:a1d95d21-...redacted...", "mediaType": "VIDEO", "createTime": "2026-07-26T21:07:56.856451Z", "likelyUpload": false } ] } ``` An empty project returns `200` with an empty array, not `404`. ```json { "email": "john@gmail.com", "projectId": "3a18acb1-2c6e-478b-bcec-2df19cb8edab", "count": 0, "likelyUploads": 0, "media": [] } ``` **400** **400 Bad Request** No `projectId` was given and the account has no project on file. Pass one explicitly — [GET /assets/projects/`email`](/docs/api-google-flow-v1/get-google-flow-assets-projects-email) lists every project the account holds media in. ```json { "error": "Parameter projectId is required (this account has no project on file)", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **404** **404 Not Found** The account named in the path is not configured for this token. List what is configured with [GET /accounts](/docs/api-google-flow-v1/get-google-flow-accounts). ```json { "error": "Google Flow account john@gmail.com not found", "code": 404 } ``` Google has no project with this `projectId` on the account. Google's own answer is passed through as an `error` object, which is why this one does not read like the error above. Check the value against [GET /assets/projects/`email`](/docs/api-google-flow-v1/get-google-flow-assets-projects-email). ```json { "error": { "code": 404, "message": "flow.google.com Zzl0ze failed", "status": "NOT_FOUND", "details": [] } } ``` **596** **596 Session Error** Google rejected the account's session, and the API is re-verifying the account on its own: retry in about a minute. If Google signed the account out, the account keeps answering `596` and you get a reconnect email: add it again by following [Setup Google Flow](/docs/start-here/setup-google-flow). ```json { "error": "Google Flow account john@gmail.com Google rejected this account session (HTTP 401). We are automatically re-verifying it — please retry in about a minute. If the account was signed out, you will receive a reconnect email.", "code": 596 } ``` ### Model Every media item of the project, up to 25,000, each with its `mediaGenerationId`, plus the counts. <details markdown="block" class="model-details"> <summary>The project's media, field by field</summary> ```typescript { email: string // Echo of the path parameter projectId: string // The project read, whether passed or defaulted count: number // Length of media[] likelyUploads: number // How many entries have likelyUpload: true truncated?: true // Present when the project holds more than the 25,000 entries returned media: [{ // every media in the project, up to 25,000 mediaGenerationId: string // the media's id: send it in mediaGenerationIds of DELETE /assets/{email} to delete an image or video, or to GET /assets/{mediaGenerationId} to download it mediaType: 'IMAGE' | 'VIDEO' | 'OTHER' // from Google's record; OTHER when it is neither createTime?: string // ISO 8601, absent on records Google returns without one likelyUpload: boolean // True when Google recorded this as an upload }] } ``` </details> ### Examples **Curl** ``` bash TOKEN='YOUR_API_TOKEN' EMAIL='john@gmail.com' ENCODED=$(printf %s "$EMAIL" | jq -sRr @uri) # The account's current project RESP=$(curl -s -H "Authorization: Bearer $TOKEN" \ "https://api.useapi.net/v1/google-flow/assets/media/$ENCODED") jq '{projectId, count, likelyUploads}' <<<"$RESP" # A specific project, listing the uploads oldest first PROJECT_ID='6db64a76-90a9-4ecd-99f0-cc524ec2b2af' curl -s -H "Authorization: Bearer $TOKEN" \ "https://api.useapi.net/v1/google-flow/assets/media/$ENCODED?projectId=$PROJECT_ID" \ | jq '[.media[] | select(.likelyUpload)] | sort_by(.createTime) | .[] | "\(.createTime) \(.mediaType) \(.mediaGenerationId)"' -r ``` **JavaScript** ``` javascript const token = 'YOUR_API_TOKEN'; const email = 'john@gmail.com'; const params = new URLSearchParams(); // Omit projectId to read the account's current project // params.set('projectId', '6db64a76-90a9-4ecd-99f0-cc524ec2b2af'); const url = `https://api.useapi.net/v1/google-flow/assets/media/${encodeURIComponent(email)}` + (params.toString() ? `?${params}` : ''); const resp = await fetch(url, { headers: { 'Authorization': `Bearer ${token}` } }); if (!resp.ok) throw new Error(`${resp.status} ${await resp.text()}`); const { projectId, count, likelyUploads, media } = await resp.json(); console.log(`${projectId}: ${count} media, ${likelyUploads} uploads`); const uploads = media .filter(m => m.likelyUpload) .sort((a, b) => (a.createTime ?? '').localeCompare(b.createTime ?? '')); for (const m of uploads.slice(0, 10)) console.log(`${m.createTime} ${m.mediaType} ${m.mediaGenerationId}`); ``` **Python** ``` python import requests from urllib.parse import quote token = 'YOUR_API_TOKEN' email = 'john@gmail.com' url = f'https://api.useapi.net/v1/google-flow/assets/media/{quote(email, safe="")}' # Omit projectId to read the account's current project params = {} # params['projectId'] = '6db64a76-90a9-4ecd-99f0-cc524ec2b2af' resp = requests.get(url, headers={'Authorization': f'Bearer {token}'}, params=params) resp.raise_for_status() data = resp.json() print(f"{data['projectId']}: {data['count']} media, {data['likelyUploads']} uploads") uploads = sorted((m for m in data['media'] if m['likelyUpload']), key=lambda m: m.get('createTime') or '') for m in uploads[:10]: print(f"{m.get('createTime')} {m['mediaType']} {m['mediaGenerationId']}") ``` ### Try It <script> async function apiExecuteGetGoogleFlowAssetsMediaEmail() { const tokenElement = document.getElementById('input-token'); const emailElement = document.getElementById('input-email'); const elementId = 'input'; const data = { method: 'GET', headers: { 'Authorization': `Bearer ${tokenElement.value}` } }; const params = new URLSearchParams(); document.querySelectorAll(`#${elementId} .input-query-param`).forEach(element => { if (element.value) params.append(element.id.replace('input-', ''), element.value); }); const query = params.toString(); const url = `https://api.useapi.net/v1/google-flow/assets/media/${encodeURIComponent(emailElement.value)}${query ? '?' + query : ''}`; await apiExecute(url, elementId, data); } </script> <form id="input" class="input-form" onsubmit="return false;"> <div class="input-field"> <div class="input-field-row"> <label for="input-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="input-token" type="text" class="input-element" required aria-required="true"> </label> <label for="input-email"><span>email (Google Flow account)</span> <input id="input-email" type="text" class="input-element" placeholder="john@gmail.com" required aria-required="true"> </label> <label for="input-projectId"><span>projectId (optional, defaults to the current project)</span> <input id="input-projectId" type="text" class="input-element input-query-param" placeholder="3a18acb1-2c6e-478b-bcec-2df19cb8edab"> </label> </div> <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteGetGoogleFlowAssetsMediaEmail()">Go</button> </div> </form> <div id="input-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-google-flow-v1/get-google-flow-assets-mediagenerationid === Document URL: https://useapi.net/docs/api-google-flow-v1/get-google-flow-assets-mediagenerationid --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> assets/`mediaGenerationId` description: "Resolve a signed download URL for a Google Flow image or video, or stream the video bytes directly with ?raw=true, via GET assets/mediaGenerationId in the useapi.net Google Flow API v1." parent: Google Flow API nav_order: 510 --- ## Get Asset Download URL June 15, 2026 (November 16, 2026) --- Resolve a signed download URL for an image or video, or download the video bytes through us with `?raw=true`. Pass any `mediaGenerationId` of type `image` or `video`. It does not matter how you obtained it — an uploaded asset and a generated one behave identically here. The endpoints that hand you one are: - [POST /assets](/docs/api-google-flow-v1/post-google-flow-assets-email) — an image or video you uploaded - [POST /images](/docs/api-google-flow-v1/post-google-flow-images) — a generated image - [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) — a generated video - [POST /videos/upscale](/docs/api-google-flow-v1/post-google-flow-videos-upscale) — an upscaled video - [POST /videos/extend](/docs/api-google-flow-v1/post-google-flow-videos-extend) — an extended video - [GET /jobs/`jobId`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid) — any of the above, read back from a stored job In each case it is the `mediaGenerationId` string itself, URL-encoded into the path. On [POST /assets](/docs/api-google-flow-v1/post-google-flow-assets-email) that is the nested `mediaGenerationId.mediaGenerationId` value, and on generation responses it sits on each entry of `media[]`. The endpoint has two response shapes, selected by the `raw` query parameter. | Request | Response | Content-Type | |---|---|---| | `GET /assets/{mediaGenerationId}` | JSON carrying a signed URL you fetch yourself | `application/json` | | `GET /assets/{mediaGenerationId}?raw=true` | the media bytes, streamed through useapi.net | `video/mp4` | Use the default JSON form. The signed URL points straight at Google's CDN and stays valid for ~6 hours, so you download the file directly from Google. Reach for `?raw=true` only when the JSON form cannot produce a URL. That is uncommon — Google issues those signed URLs from an endpoint that limits how often it will answer a given network address, and once in a while it withholds them for a few minutes to a few hours before clearing on its own. The raw form reads the media over a different route that the limit does not touch, which makes it a dependable fallback — at the cost of moving the whole file through us on every call. It is **video only**. ### What this endpoint accepts A video works with both forms. Ask without `raw` for a signed URL, or with `?raw=true` for the bytes. An image works with the signed URL only. Adding `?raw=true` to an image returns `400`. You do not need it for images: whenever an image URL is missing, [POST /images](/docs/api-google-flow-v1/post-google-flow-images) puts the image itself in the response instead, base64-encoded in `encodedImage`. A character or voice reference is not served here at all and returns `400` either way. Those have their own endpoints — [GET /characters/`ref`](/docs/api-google-flow-v1/get-google-flow-characters-ref) and [GET /voices/`ref`](/docs/api-google-flow-v1/get-google-flow-voices-ref). > **https://api.useapi.net/v1/google-flow/assets/`mediaGenerationId`** ### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Path Parameters - `mediaGenerationId` is **required**, URL-encoded. Any `image` or `video` reference is accepted — see [what this endpoint accepts](#what-this-endpoint-accepts) above for the full list of endpoints that return one, and where the value sits in each response. ### Query Parameters - `raw` is optional. Accepted values are `true` and `1`. Any other value is rejected with `400`. Omit it to receive JSON with a signed URL, which is the recommended form. When `raw` is set, the response body is the media file itself rather than JSON: ``` yaml Content-Type: video/mp4 Content-Disposition: attachment; filename="<mediaId>.mp4" ``` The bytes are streamed as they arrive, so the response carries no `Content-Length` and cannot be resumed part-way. Save the body to a file or pipe it onward. A video generated at 8 seconds and 720p is roughly 6-7 MB. ### Responses **200** **200 OK** Without `raw`, the body is JSON carrying the signed URL. ```json { "url": "https://flow-content.google/image/ff9aa5cc-...?Expires=1785115591&KeyName=labs-flow-prod-cdn-key&Signature=...", "mediaGenerationId": "user:12345-email:6a6f...-image:ff9aa5cc-...redacted..." } ``` With `?raw=true`, the body is the video file itself and there is no JSON at all. ``` yaml Content-Type: video/mp4 Content-Disposition: attachment; filename="a1d95d21-...redacted....mp4" <binary MP4 data> ``` **400** **400 Bad Request** The path parameter could not be parsed as a valid `mediaGenerationId`, or it is a character/voice reference type (only `image` and `video` are accepted on this endpoint — use [GET /characters/`ref`](/docs/api-google-flow-v1/get-google-flow-characters-ref) or [GET /voices/`ref`](/docs/api-google-flow-v1/get-google-flow-voices-ref) for those). ```json { "error": "Invalid mediaGenerationId format: not-a-valid-ref-id", "code": 400 } ``` `raw` was given a value other than `true` or `1`. ```json { "error": "Parameter raw must be 'true' or '1', got 'yes'", "code": 400 } ``` `?raw=true` was used with an image. Request it without `raw` to get the image's signed URL. ```json { "error": "mediaGenerationId type must be 'video', got 'image'", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The `mediaGenerationId` belongs to a different useapi.net user than the one identified by the `Authorization` token. Each `mediaGenerationId` encodes its owning user id; requests across users are rejected before any Google call is made. ```json { "error": "Unauthorized access to user:99999 detected in mediaGenerationId", "code": 403 } ``` **404** **404 Not Found** The owning Google Flow account (decoded from the `mediaGenerationId`) is not configured for this token. ```json { "error": "Google Flow account john@gmail.com not found", "code": 404 } ``` Google holds no media under this id. Both forms of this endpoint return the same thing here, so retrying without `raw` will not help and neither will retrying later — check the `mediaGenerationId` itself. ```json { "error": "Media a1d95d21-...redacted... not found", "code": 404 } ``` **502** **502 Bad Gateway** Google answered in a way we do not recognize — neither a usable download link nor one of the known conditions above. This one is worth reporting to support@useapi.net, because unlike the 404 and 503 cases it is not something you can resolve from your side. ```json { "error": "Failed to resolve URL for media ff9aa5cc-...redacted...", "code": 502 } ``` **503** **503 Service Unavailable** The media exists but is not downloadable yet. Both of the cases below are temporary and clear on their own, and both carry a `Retry-After` header telling you how long to wait — read it rather than hard-coding a delay. Google is still processing the media. A freshly uploaded or just-generated asset spends a few seconds in this state, and `?raw=true` is affected for the same window. ``` yaml Retry-After: 10 ``` ```json { "error": "Media a1d95d21-...redacted... is not ready yet, retry in 10s", "code": 503 } ``` Google is rate-limiting the requests we make to fetch signed URLs, which it does by network address rather than by account. This affects the default form only — [`?raw=true`](#query-parameters) reads the media over a different Google route and keeps working. See [Missing media URLs](/docs/api-google-flow-v1/post-google-flow-videos#missing-media-urls) for the full picture. ``` yaml Retry-After: 60 ``` ```json { "error": "Media a1d95d21-...redacted... download URL is temporarily unavailable, retry in 60s", "code": 503 } ``` **596** **596 Session Error** Google rejected the account's session, and the API is re-verifying the account on its own: retry in about a minute. If Google signed the account out, the account keeps answering `596` and you get a reconnect email: add it again by following [Setup Google Flow](/docs/start-here/setup-google-flow). ```json { "error": "Google Flow account john@gmail.com Google rejected this account session (HTTP 401). We are automatically re-verifying it — please retry in about a minute. If the account was signed out, you will receive a reconnect email.", "code": 596 } ``` ### Model A signed download link for the media, valid for about 6 hours. <details markdown="block" class="model-details"> <summary>The download link, field by field</summary> Without `raw`: ```typescript { url: string // Signed CDN download URL, valid for ~6 hours mediaGenerationId: string // Echo of the request path parameter } ``` With `?raw=true` there is no model — a successful response is the raw MP4 body. Errors still return the JSON error shape above. </details> ### Examples **Curl** ``` bash # Step 1: read back an asset uploaded earlier MEDIA_GEN_ID='user:12345-email:6a6f...-image:ff9aa5cc-...' ENCODED=$(printf %s "$MEDIA_GEN_ID" | jq -sRr @uri) RESP=$(curl -s \ -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v1/google-flow/assets/$ENCODED") # Step 2: fetch the signed URL directly to read the bytes URL=$(echo "$RESP" | jq -r .url) curl -L -o restored.png "$URL" # Fallback when no URL came back: stream the bytes through useapi.net. # ?raw=true accepts video mediaGenerationIds only. # -f makes curl fail on an error status instead of writing the JSON error to the file. VIDEO_GEN_ID='user:12345-email:6a6f...-video:a1d95d21-...' curl -f -s \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -o restored.mp4 \ "https://api.useapi.net/v1/google-flow/assets/$(printf %s "$VIDEO_GEN_ID" | jq -sRr @uri)?raw=true" ``` **JavaScript** ``` javascript const token = 'YOUR_API_TOKEN'; const mediaGenerationId = 'user:12345-email:6a6f...-video:a1d95d21-...'; const apiUrl = `https://api.useapi.net/v1/google-flow/assets/${encodeURIComponent(mediaGenerationId)}`; const resp = await fetch(apiUrl, { headers: { 'Authorization': `Bearer ${token}` } }); const { url } = await resp.json(); let bytes; if (url) { // Preferred: download straight from Google const dl = await fetch(url); bytes = new Uint8Array(await dl.arrayBuffer()); } else { // No URL available right now — stream the video through useapi.net instead (video only) const dl = await fetch(`${apiUrl}?raw=true`, { headers: { 'Authorization': `Bearer ${token}` } }); if (!dl.ok) throw new Error(`raw download failed: ${dl.status}`); bytes = new Uint8Array(await dl.arrayBuffer()); } console.log(`Downloaded ${bytes.length} bytes`); ``` **Python** ``` python import requests from urllib.parse import quote token = 'YOUR_API_TOKEN' media_generation_id = 'user:12345-email:6a6f...-video:a1d95d21-...' api_url = f'https://api.useapi.net/v1/google-flow/assets/{quote(media_generation_id, safe="")}' resp = requests.get(api_url, headers={'Authorization': f'Bearer {token}'}) url = resp.json().get('url') if url: # Preferred: fetch Google's CDN directly dl = requests.get(url) data = dl.content else: # No URL available right now — stream the video through useapi.net instead (video only) dl = requests.get(api_url, params={'raw': 'true'}, headers={'Authorization': f'Bearer {token}'}, stream=True) dl.raise_for_status() data = dl.content with open('restored.mp4', 'wb') as f: f.write(data) print(f'Downloaded {len(data)} bytes') ``` ### Try It <script> function displayGoogleFlowAssetMedia(response, mediaGenerationId, elementId) { const mediaContainer = document.getElementById(`${elementId}-media-links`); if (!mediaContainer || !response?.url) return; const isVideo = /-video:/.test(mediaGenerationId); const isImage = /-image:/.test(mediaGenerationId); const url = response.url; if (isImage) { mediaContainer.innerHTML = `<div class="media-links-container"><strong>Retrieved Image:</strong> <a href="${url}" target="_blank" rel="noopener noreferrer" class="media-link image">Open in new tab</a><br><img src="${url}" alt="Retrieved asset" style="max-width:100%;max-height:480px;margin-top:0.5em;border:1px solid #ddd;border-radius:4px;"></div>`; mediaContainer.style.display = 'block'; return; } if (isVideo) { mediaContainer.innerHTML = `<div class="media-links-container"><strong>Retrieved Video:</strong> <a href="${url}" target="_blank" rel="noopener noreferrer" class="media-link video">Open in new tab</a><br><video src="${url}" controls style="max-width:100%;max-height:480px;margin-top:0.5em;border:1px solid #ddd;border-radius:4px;"></video></div>`; mediaContainer.style.display = 'block'; return; } mediaContainer.style.display = 'none'; } async function apiExecuteGetGoogleFlowAssetsMediaGenerationId() { const tokenElement = document.getElementById('input-token'); const mediaGenerationIdElement = document.getElementById('input-mediagenerationid'); const rawElement = document.getElementById('input-raw'); const elementId = 'input'; const raw = rawElement && rawElement.value === 'true'; const data = { method: 'GET', headers: { 'Authorization': `Bearer ${tokenElement.value}` } }; const mediaLinks = document.getElementById(`${elementId}-media-links`); if (mediaLinks) mediaLinks.style.display = 'none'; const url = `https://api.useapi.net/v1/google-flow/assets/${encodeURIComponent(mediaGenerationIdElement.value)}${raw ? '?raw=true' : ''}`; const status = await apiExecute(url, elementId, data, { expectMedia: raw }); if (raw) return; if (status === 200) { try { const content = document.getElementById(`${elementId}-response-json`); const response = JSON.parse(content.innerText); displayGoogleFlowAssetMedia(response, mediaGenerationIdElement.value, elementId); } catch (e) { console.error('Failed to parse response for media display:', e); } } } </script> <form id="input" class="input-form" onsubmit="return false;"> <div class="input-field"> <div class="input-field-row"> <label for="input-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="input-token" type="text" class="input-element" required aria-required="true"> </label> <label for="input-mediagenerationid"><span>mediaGenerationId</span> <input id="input-mediagenerationid" type="text" class="input-element" placeholder="user:12345-email:6a6f...-image:ff9aa5cc-..." required aria-required="true"> </label> <label for="input-raw" style="display:block;margin-bottom:10px;"><span>raw (video only)</span> <select id="input-raw" class="input-element"> <option value="">false — return the signed URL as JSON</option> <option value="true">true — download the video bytes</option> </select> </label> </div> <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteGetGoogleFlowAssetsMediaGenerationId()">Go</button> </div> </form> <div id="input-media-links" style="display:none;"></div> <div id="input-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-google-flow-v1/get-google-flow-assets-projects-email === Document URL: https://useapi.net/docs/api-google-flow-v1/get-google-flow-assets-projects-email --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> assets/projects/`email` description: "List every project holding media on a Google Flow account, with per-project counts, types and date ranges, via GET assets/projects/email in the useapi.net Google Flow API v1." parent: Google Flow API nav_order: 520 --- ## List Account Projects September 1, 2026 (November 16, 2026) --- List every project that holds media on one Google Flow account, with a media count, a type breakdown and a date range for each. A Google Flow account accumulates projects over time, and only one of them is the project your useapi.net configuration currently writes to. The others stay in the account, keep their media, and count against whatever storage the account is subject to — but nothing in the API surfaces them, so they are easy to forget. This endpoint finds them. Use it as the first step of a cleanup: list the projects here, then read one project's contents with [GET /assets/media/`email`](/docs/api-google-flow-v1/get-google-flow-assets-media-email), then remove what you no longer want with [DELETE /assets/`email`](/docs/api-google-flow-v1/delete-google-flow-assets-email). ### What the counts include The counts here come from your account's generation history, so they cover generated images and videos only. Uploaded assets are not in that history and are not counted — read those from [GET /assets/media/`email`](/docs/api-google-flow-v1/get-google-flow-assets-media-email), which reports them as `likelyUploads`. That distinction matters if you are chasing a storage problem: an account can look modest here and still hold hundreds of uploads. > **https://api.useapi.net/v1/google-flow/assets/projects/`email`?cursor=** ### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Path Parameters - `email` is **required**, URL-encoded. The Google Flow account to scan. Unlike [POST /assets](/docs/api-google-flow-v1/post-google-flow-assets-email), the account is never chosen for you — listing "whichever account the load balancer picked" would not answer any question you could act on. ### Query Parameters - `cursor` is optional. Pass the `cursor` from a previous truncated response to continue scanning from where it stopped. Omit it to start at the newest media. ### Pagination One call walks up to 50 pages of 20 media (1,000 media), and stops early if the scan reaches 45 seconds. Either way the response sets `truncated: true` and carries a `cursor`. A `stoppedOn: "timeBudget"` alongside it tells you the clock ended the scan rather than the page cap. Keep calling with the returned `cursor` until `truncated` is `false`. A full walk takes a handful of calls — an account holding 4,776 media finished in five. Also stop if a call returns `scanned: 0`, which ends the walk on the histories where Google's last page comes back empty. **Each response counts only the media that call scanned.** The `projects` array is built from scratch per request, so continuing with a cursor gives you the counts for the next chunk of history — not a running total. Merge the pages yourself by summing `total` and `byType` per `projectId` and keeping the outermost `oldest` / `newest`. The [examples](#examples) below do this. ### Responses **200** **200 OK** Projects are sorted by `total`, largest first. ```json { "email": "john@gmail.com", "projects": [ { "projectId": "6db64a76-90a9-4ecd-99f0-cc524ec2b2af", "isCurrent": false, "total": 616, "byType": { "IMAGE": 616 }, "oldest": "2026-04-26T06:37:30.645104Z", "newest": "2026-05-02T07:38:19.981602Z" }, { "projectId": "3a18acb1-2c6e-478b-bcec-2df19cb8edab", "isCurrent": true, "total": 144, "byType": { "IMAGE": 142, "VIDEO": 2 }, "oldest": "2026-05-21T20:49:27.272324Z", "newest": "2026-07-26T21:07:56.856451Z" } ], "scanned": 760, "truncated": true, "cursor": "flow.WyJjaEVLRDRJQkRB...redacted", "stoppedOn": "timeBudget" } ``` A complete scan omits both `cursor` and `stoppedOn`. A project Google would not let us read is listed in `skippedProjects` instead of being counted. ```json { "email": "john@gmail.com", "projects": [ { "projectId": "54a1808e-fc68-466d-a163-dc0993fb84df", "isCurrent": true, "total": 40, "byType": { "IMAGE": 40 }, "oldest": "2026-03-17T00:08:43.372665Z", "newest": "2026-04-02T02:12:46.103452Z" } ], "scanned": 40, "truncated": false } ``` **400** **400 Bad Request** The `cursor` is not one this endpoint returned. ```json { "error": "Parameter cursor is not a cursor returned by this endpoint", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **404** **404 Not Found** The account named in the path is not configured for this token. List what is configured with [GET /accounts](/docs/api-google-flow-v1/get-google-flow-accounts). ```json { "error": "Google Flow account john@gmail.com not found", "code": 404 } ``` **503** **503 Service Unavailable** The call stopped before it counted any media, for example because a project could not be read or the time ran out. The answer carries a `Retry-After` header and the `cursor` to continue from. Call again with it. ```json { "error": "Nothing was counted: no project was read; the call stopped because project 6db64a76-90a9-4ecd-99f0-cc524ec2b2af could not be read (FLOW_NO_RPC_ANSWER). Call again with cursor to continue", "code": 503, "cursor": "flow.WyJjaEVLRDRJQkRB...redacted" } ``` **596** **596 Session Error** Google rejected the account's session, and the API is re-verifying the account on its own: retry in about a minute. If Google signed the account out, the account keeps answering `596` and you get a reconnect email: add it again by following [Setup Google Flow](/docs/start-here/setup-google-flow). ```json { "error": "Google Flow account john@gmail.com Google rejected this account session (HTTP 401). We are automatically re-verifying it — please retry in about a minute. If the account was signed out, you will receive a reconnect email.", "code": 596 } ``` ### Model The account's projects that hold media, most media first, each with its media counts per type. <details markdown="block" class="model-details"> <summary>The list of projects, field by field</summary> ```typescript { email: string // Echo of the path parameter projects: [{ // projects with generated media counted in this call, most media first projectId: string // Google's project UUID isCurrent: boolean // True for the project this account currently writes to total: number // Media counted for this project in THIS response byType: { // Counts per media type, e.g. { IMAGE: 142, VIDEO: 2 } [type: string]: number } oldest?: string // Earliest createTime seen in this response (ISO 8601) newest?: string // Latest createTime seen in this response (ISO 8601) }] scanned: number // Generated media counted by this call (the sum of the projects' totals) truncated: boolean // True when projects remain unread cursor?: string // Present only when truncated — pass back to continue stoppedOn?: 'timeBudget' // Present only when the time budget ended the scan skippedProjects?: [{ // projects that could not be read, so were not counted. Present only when there are any projectId: string // Google's project UUID reason: string // why it could not be read, e.g. Google's error reason }] } ``` Only generated images and videos are counted. Uploads are not, and a project holding none of them is left out. </details> ### Examples **Curl** ``` bash TOKEN='YOUR_API_TOKEN' EMAIL='john@gmail.com' ENCODED=$(printf %s "$EMAIL" | jq -sRr @uri) BASE="https://api.useapi.net/v1/google-flow/assets/projects/$ENCODED" # Walk every page, then merge the per-page counts into one total per project CURSOR='' echo '[]' > /tmp/pages.json while : ; do URL="$BASE" [ -n "$CURSOR" ] && URL="$BASE?cursor=$(printf %s "$CURSOR" | jq -sRr @uri)" RESP=$(curl -s -H "Authorization: Bearer $TOKEN" "$URL") jq --argjson p "$(jq -c .projects <<<"$RESP")" '. + $p' /tmp/pages.json > /tmp/pages.tmp \ && mv /tmp/pages.tmp /tmp/pages.json [ "$(jq -r .truncated <<<"$RESP")" = 'true' ] || break [ "$(jq -r .scanned <<<"$RESP")" = '0' ] && break CURSOR=$(jq -r .cursor <<<"$RESP") echo "scanned so far, continuing..." done jq 'group_by(.projectId) | map({ projectId: .[0].projectId, isCurrent: .[0].isCurrent, total: map(.total) | add, oldest: map(.oldest) | min, newest: map(.newest) | max }) | sort_by(-.total)' /tmp/pages.json ``` **JavaScript** ``` javascript const token = 'YOUR_API_TOKEN'; const email = 'john@gmail.com'; const base = `https://api.useapi.net/v1/google-flow/assets/projects/${encodeURIComponent(email)}`; const merged = new Map(); let cursor; let scanned = 0; do { const url = cursor ? `${base}?${new URLSearchParams({ cursor })}` : base; const resp = await fetch(url, { headers: { 'Authorization': `Bearer ${token}` } }); if (!resp.ok) throw new Error(`${resp.status} ${await resp.text()}`); const page = await resp.json(); scanned += page.scanned; for (const p of page.projects) { const acc = merged.get(p.projectId) ?? { ...p, total: 0, byType: {} }; acc.total += p.total; for (const [type, n] of Object.entries(p.byType)) acc.byType[type] = (acc.byType[type] ?? 0) + n; if (p.oldest && (!acc.oldest || p.oldest < acc.oldest)) acc.oldest = p.oldest; if (p.newest && (!acc.newest || p.newest > acc.newest)) acc.newest = p.newest; merged.set(p.projectId, acc); } cursor = page.scanned ? page.cursor : undefined; } while (cursor); const projects = [...merged.values()].sort((a, b) => b.total - a.total); console.log(`${scanned} media across ${projects.length} projects`); for (const p of projects) console.log(`${p.total.toString().padStart(5)} ${p.projectId}${p.isCurrent ? ' (current)' : ''}`); ``` **Python** ``` python import requests from urllib.parse import quote token = 'YOUR_API_TOKEN' email = 'john@gmail.com' base = f'https://api.useapi.net/v1/google-flow/assets/projects/{quote(email, safe="")}' headers = {'Authorization': f'Bearer {token}'} merged, cursor, scanned = {}, None, 0 while True: resp = requests.get(base, headers=headers, params={'cursor': cursor} if cursor else None) resp.raise_for_status() page = resp.json() scanned += page['scanned'] for p in page['projects']: acc = merged.setdefault(p['projectId'], {**p, 'total': 0, 'byType': {}}) acc['total'] += p['total'] for media_type, n in p['byType'].items(): acc['byType'][media_type] = acc['byType'].get(media_type, 0) + n if p.get('oldest'): acc['oldest'] = min(acc.get('oldest') or p['oldest'], p['oldest']) if p.get('newest'): acc['newest'] = max(acc.get('newest') or p['newest'], p['newest']) cursor = page.get('cursor') if page['scanned'] else None if not cursor: break projects = sorted(merged.values(), key=lambda p: -p['total']) print(f'{scanned} media across {len(projects)} projects') for p in projects: print(f"{p['total']:>5} {p['projectId']}{' (current)' if p['isCurrent'] else ''}") ``` ### Try It <script> async function apiExecuteGetGoogleFlowAssetsProjectsEmail() { const tokenElement = document.getElementById('input-token'); const emailElement = document.getElementById('input-email'); const elementId = 'input'; const data = { method: 'GET', headers: { 'Authorization': `Bearer ${tokenElement.value}` } }; const params = new URLSearchParams(); document.querySelectorAll(`#${elementId} .input-query-param`).forEach(element => { if (element.value) params.append(element.id.replace('input-', ''), element.value); }); const query = params.toString(); const url = `https://api.useapi.net/v1/google-flow/assets/projects/${encodeURIComponent(emailElement.value)}${query ? '?' + query : ''}`; await apiExecute(url, elementId, data); } </script> <form id="input" class="input-form" onsubmit="return false;"> <div class="input-field"> <div class="input-field-row"> <label for="input-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="input-token" type="text" class="input-element" required aria-required="true"> </label> <label for="input-email"><span>email (Google Flow account)</span> <input id="input-email" type="text" class="input-element" placeholder="john@gmail.com" required aria-required="true"> </label> <label for="input-cursor"><span>cursor (optional, continue a truncated scan)</span> <input id="input-cursor" type="text" class="input-element input-query-param" placeholder="leave empty to start from the newest media"> </label> </div> <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteGetGoogleFlowAssetsProjectsEmail()">Go</button> </div> </form> <div id="input-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-google-flow-v1/get-google-flow-characters-ref === Document URL: https://useapi.net/docs/api-google-flow-v1/get-google-flow-characters-ref --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> characters/`ref` description: "Resolve a single Google Flow character by ref with signed image previews and voice audio URL via GET characters/ref in the useapi.net Google Flow API v1." parent: Google Flow API nav_order: 1220 --- ## Get Single Character (with previewUrls + audioUrl) June 5, 2026 (November 16, 2026) --- Resolve a single character by reference-id with all media URLs included: - `imageReferences[].previewUrl` — signed image preview for each attached image - `thumbnailUrl` — signed thumbnail of the auto-composited character avatar - `voice.audioUrl` — signed playback URL when a live voice is attached All URLs are valid for ~6 hours. > **https://api.useapi.net/v1/google-flow/characters/`ref`** ### Path Parameters - `ref` is **required**, the character reference-id returned by [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters) or [GET /characters](/docs/api-google-flow-v1/get-google-flow-characters) (URL-encoded). ### Request Headers ``` yaml Authorization: Bearer {API token} ``` ### Responses **200** **200 OK** ```json { "character": "user:12345-email:6a6f...-character:f470f1b5-...-imgs:2-voice:d990a2f9-...", "entityId": "f470f1b5-...", "displayName": "Carol", "personalityNotes": "A curious traveler with a sharp wit", "imageReferences": [ { "workflowId": "wf-a...", "mediaId": "media-a...", "previewUrl": "https://flow-content.google/image/media-a...?Expires=...&Signature=..." }, { "workflowId": "wf-b...", "mediaId": "media-b...", "previewUrl": "https://flow-content.google/image/media-b...?Expires=...&Signature=..." } ], "voice": { "source": "user", "voice": "user:12345-email:6a6f...-voice:d990a2f9-...-mid:d55b6d59-...", "workflowId": "d990a2f9-...", "mediaId": "d55b6d59-...", "displayName": "Cheerful Narrator", "baseVoice": "Achernar", "dialog": "Hello, this is a test voice.", "voicePerformance": "Cheerful, energetic delivery", "audioUrl": "https://flow-content.google/audio/d55b6d59-...?Expires=...&Signature=..." }, "thumbnailMediaId": "thumb-a...", "thumbnailUrl": "https://flow-content.google/image/thumb-a...?Expires=...&Signature=...", "createTime": "2026-06-05T18:14:07.706641Z", "updateTime": "2026-06-05T18:14:16.004078Z" } ``` For a **system voice** attached at create time (e.g. `voice: "Umbriel"` on POST /characters), the `voice` block reports `{ "source": "system", "voice": "Umbriel", "displayName": "Umbriel" }` — no `workflowId`, no `audioUrl`. Preview the audio sample from `https://www.gstatic.com/aitestkitchen/voices/samples/{Name}.wav`. For an **orphan voice** (the attached user voice has been deleted), the `voice` block degrades to `{ "workflowId": "...", "mediaId": "...", "deleted": true }` — no `audioUrl`. `workflowId` comes from the `-voice:` part of the reference you sent, so a reference without it leaves `workflowId` out. A voice attached by its workflow (not its media) reports `{ "workflowId": "...", "deleted": true }`. The image URLs are unaffected. **400** **400 Bad Request** ```json { "error": "Parameter character has incorrect format", "code": 400 } ``` **403** **403 Forbidden** ```json { "error": "Unauthorized access to user:12345 detected in character reference", "code": 403 } ``` **404** **404 Not Found** ```json { "error": "Character not found: f470f1b5-...", "code": 404 } ``` ### Model The character with its reference-id, its images with signed preview links, its thumbnail and its voice. <details markdown="block" class="model-details"> <summary>The character, field by field</summary> ```typescript { character: string // reference-id used in character_1..10 on POST /videos, character_1..7 on POST /images entityId: string // Google's id of the character displayName: string // the character's name ('Untitled Character' when it has none) personalityNotes?: string // notes about the character, when set imageReferences: Array<{ // the character's image slots workflowId?: string // the image's Google Flow workflow; absent on an empty slot mediaId?: string // populated when the image media is resolvable previewUrl?: string // signed image preview URL (~6h TTL) }> thumbnailMediaId?: string // media id of the character's thumbnail image thumbnailUrl?: string // signed thumbnail URL (~6h TTL) createTime: string // ISO 8601 timestamp (empty when Google gives none) updateTime: string // ISO 8601 timestamp of the last change (empty when Google gives none) voice?: // omitted if no voice was ever attached. One of three shapes: a custom voice (source user), // a system voice preset (source system, no workflow or media), or a custom voice that was // attached and then deleted (deleted: true, no source) | { source: 'user' // a custom voice (POST /voices) voice: string // dual-id reference-id workflowId: string // Google Flow workflow of the voice mediaId: string // media id of the voice's audio displayName?: string // the voice's name baseVoice?: string // the system preset the voice is built on dialog?: string // the text the voice speaks in its sample voicePerformance?: string // the delivery style audioUrl?: string // signed playback URL (~6h TTL) } | { source: 'system' // a system voice preset voice: string // canonical Title-case preset name (e.g. 'Umbriel') displayName: string // same as `voice` } | { workflowId?: string // the deleted voice's workflow id, when known mediaId?: string // the deleted voice's media id, when the voice was attached by media id deleted: true // always true: the voice was attached, then deleted } } ``` </details> ### Examples **Curl** ``` bash REF="user:12345-email:6a6f...-character:f470f1b5-...-imgs:2" REF_ENC=$(printf '%s' "$REF" | jq -sRr @uri) curl -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v1/google-flow/characters/$REF_ENC" ``` **JavaScript** ``` javascript const ref = 'user:12345-email:6a6f...-character:f470f1b5-...-imgs:2' const r = await fetch( `https://api.useapi.net/v1/google-flow/characters/${encodeURIComponent(ref)}`, { headers: { 'Authorization': `Bearer ${token}` } } ) const c = await r.json() c.imageReferences.forEach((img, i) => console.log(`img ${i}:`, img.previewUrl)) console.log('voice audio:', c.voice?.audioUrl) ``` **Python** ``` python import requests, urllib.parse ref = 'user:12345-email:6a6f...-character:f470f1b5-...-imgs:2' r = requests.get( f'https://api.useapi.net/v1/google-flow/characters/{urllib.parse.quote(ref, safe="")}', headers={'Authorization': f'Bearer {token}'}, ) c = r.json() for i, img in enumerate(c['imageReferences']): print(f"img {i}:", img.get('previewUrl')) print('voice audio:', (c.get('voice') or {}).get('audioUrl')) ``` ### Try It <form id="input" class="input-form" onsubmit="return false;"> <div class="input-field"> <div class="input-field-row"> <label for="input-token"><span>API Token</span> <input id="input-token" type="text" class="input-element" required aria-required="true"> </label> <label for="input-ref"><span>ref (character reference-id from <a href="/docs/api-google-flow-v1/post-google-flow-characters">POST /characters</a>)</span> <input id="input-ref" type="text" class="input-element" required aria-required="true" placeholder="user:12345-email:...-character:...-imgs:N"> </label> </div> <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteGetGoogleFlowCharacterByRef()">Go</button> </div> </form> <div id="input-previews" style="display:none;margin-top:12px"></div> <div id="input-response" class="response-placeholder visible-false"></div> <script> async function apiExecuteGetGoogleFlowCharacterByRef() { const tokenElement = document.getElementById('input-token'); const elementId = 'input'; const ref = document.getElementById('input-ref').value?.trim(); if (!ref) return; const url = `https://api.useapi.net/v1/google-flow/characters/${encodeURIComponent(ref)}`; const data = { method: 'GET', headers: { 'Authorization': `Bearer ${tokenElement.value}` } }; const previews = document.getElementById('input-previews'); previews.style.display = 'none'; previews.innerHTML = ''; const status = await apiExecute(url, elementId, data, { includeTimer: true }); if (status === 200) { try { const content = document.getElementById(`${elementId}-response-json`); const c = JSON.parse(content.innerText); const parts = []; if (c.thumbnailUrl) { parts.push(`<div><strong>Thumbnail:</strong><br><img src="${c.thumbnailUrl}" style="max-height:180px;border-radius:6px"></div>`); } const imgs = (c.imageReferences || []).filter(i => i.previewUrl); if (imgs.length) { parts.push('<div><strong>Image references:</strong><br>' + imgs.map(i => `<img src="${i.previewUrl}" style="max-height:180px;border-radius:6px;margin-right:6px">`).join('') + '</div>'); } const audio = c.voice?.audioUrl; if (audio) { parts.push(`<div><strong>Voice (${escHtml(c.voice.displayName || 'attached')}):</strong><br><audio src="${audio}" class="audio-player" controls></audio></div>`); } if (parts.length) { previews.innerHTML = parts.join('<br>'); previews.style.display = 'block'; } } catch (e) {}; } } </script> === URL: https://useapi.net/docs/api-google-flow-v1/get-google-flow-characters === Document URL: https://useapi.net/docs/api-google-flow-v1/get-google-flow-characters --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> characters description: "List all reusable characters on a Google Flow account via GET characters in the useapi.net Google Flow API v1; media URLs are excluded — use GET characters/ref for signed previews." parent: Google Flow API nav_order: 1210 --- ## List Characters June 5, 2026 (November 16, 2026) --- List all **characters** on an account. This endpoint is intentionally **fast** — it does NOT resolve image preview URLs or voice audio URLs. If you need previews, call [GET /characters/`ref`](/docs/api-google-flow-v1/get-google-flow-characters-ref) for the single character you want to display. The voice block on each character distinguishes three states: - **Live voice** — full voice metadata block (`workflowId`, `mediaId`, `displayName`, `baseVoice`, `dialog`, `voicePerformance`) but no `audioUrl` (use the singleton endpoint). - **Orphan voice** — `{ "mediaId": "...", "deleted": true }`. The character was created with a voice that's since been deleted via [DELETE /voices/`ref`](/docs/api-google-flow-v1/delete-google-flow-voices-ref). A character whose voice was attached by its workflow instead reports `{ "workflowId": "...", "deleted": true }`. - **No voice** — the `voice` field is omitted entirely. > **https://api.useapi.net/v1/google-flow/characters** ### Request Headers ``` yaml Authorization: Bearer {API token} ``` ### Query Parameters - `email` — **required.** Account whose characters to list. ### Responses **200** **200 OK** ```json { "characters": [ { "character": "user:12345-email:6a6f...-character:f470f1b5-...-imgs:2-voice:d990a2f9-...", "entityId": "f470f1b5-...", "displayName": "Carol", "personalityNotes": "A curious traveler with a sharp wit", "imageReferences": [ { "workflowId": "wf-a..." }, { "workflowId": "wf-b..." } ], "voice": { "source": "user", "voice": "user:12345-email:6a6f...-voice:d990a2f9-...-mid:d55b6d59-...", "workflowId": "d990a2f9-...", "mediaId": "d55b6d59-...", "displayName": "Cheerful Narrator", "baseVoice": "Achernar", "dialog": "Hello, this is a test voice.", "voicePerformance": "Cheerful, energetic delivery" }, "thumbnailMediaId": "thumb-a...", "createTime": "2026-06-05T18:14:07.706641Z", "updateTime": "2026-06-05T18:14:16.004078Z" }, { "character": "user:12345-email:6a6f...-character:60831b31-...-imgs:1-voice:umbriel", "entityId": "60831b31-...", "displayName": "Frank", "imageReferences": [{ "workflowId": "wf-d..." }], "voice": { "source": "system", "voice": "Umbriel", "displayName": "Umbriel" }, "thumbnailMediaId": "thumb-d...", "createTime": "2026-06-05T22:42:18.901333Z", "updateTime": "2026-06-05T22:42:24.882179Z" }, { "character": "user:12345-email:6a6f...-character:8a4b0541-...-imgs:1", "entityId": "8a4b0541-...", "displayName": "Eve", "imageReferences": [{ "workflowId": "wf-c..." }], "voice": { "mediaId": "5b1c0e7a-...", "deleted": true }, "thumbnailMediaId": "thumb-c...", "createTime": "2026-06-05T18:15:37.734955Z", "updateTime": "2026-06-05T18:15:41.167097Z" } ] } ``` If no characters have been created yet, `characters` is just an empty array — no error. **400** **400 Bad Request** ```json { "error": "Parameter email is required", "code": 400 } ``` **404** **404 Not Found** ```json { "error": "Google Flow account john@gmail.com not found", "code": 404 } ``` ### Model Every character of the account, each with its reference-id, name, images and voice. <details markdown="block" class="model-details"> <summary>The list of characters, field by field</summary> ```typescript { characters: Array<{ // every character of the account character: string // reference-id used in character_1..10 on POST /videos, character_1..7 on POST /images entityId: string // Google's id of the character displayName: string // the character's name ('Untitled Character' when it has none) personalityNotes?: string // notes about the character, when set imageReferences: Array<{ // the character's image slots workflowId?: string // the image's Google Flow workflow; absent on an empty slot }> thumbnailMediaId?: string // media id of the character's thumbnail image createTime: string // ISO 8601 timestamp (empty when Google gives none) updateTime: string // ISO 8601 timestamp of the last change (empty when Google gives none) voice?: // omitted if no voice was ever attached. One of three shapes: a custom voice (source user), // a system voice preset (source system), or a custom voice that was attached and then // deleted (deleted: true, no source) | { source: 'user' // a custom voice (POST /voices) voice: string // dual-id reference-id workflowId: string // Google Flow workflow of the voice mediaId: string // media id of the voice's audio displayName?: string // the voice's name baseVoice?: string // the system preset the voice is built on dialog?: string // the text the voice speaks in its sample voicePerformance?: string // the delivery style } | { source: 'system' // a system voice preset voice: string // Title-case preset name (e.g. 'Umbriel') displayName: string // same as `voice` } | { mediaId?: string // the deleted voice's media id, when the voice was attached by media id workflowId?: string // the deleted voice's workflow id, when the voice was attached by workflow deleted: true // always true: the voice was attached, then deleted } }> } ``` </details> ### Examples **Curl** ``` bash curl -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v1/google-flow/characters?email=john@gmail.com" ``` **JavaScript** ``` javascript const r = await fetch( `https://api.useapi.net/v1/google-flow/characters?email=${email}`, { headers: { 'Authorization': `Bearer ${token}` } } ) const { characters } = await r.json() console.log(characters.map(c => c.displayName)) ``` **Python** ``` python import requests r = requests.get( 'https://api.useapi.net/v1/google-flow/characters', headers={'Authorization': f'Bearer {token}'}, params={'email': 'john@gmail.com'}, ) for c in r.json()['characters']: print(c['displayName'], '→', c['character']) ``` ### Try It <form id="input" class="input-form" onsubmit="return false;"> <div class="input-field"> <div class="input-field-row"> <label for="input-token"><span>API Token</span> <input id="input-token" type="text" class="input-element" required aria-required="true"> </label> <label for="input-email"><span>email (required)</span> <input id="input-email" type="text" class="input-element input-query-param" required aria-required="true" placeholder="john@gmail.com"> </label> </div> <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteGetGoogleFlowCharacters()">Go</button> </div> </form> <div id="input-response" class="response-placeholder visible-false"></div> <script> async function apiExecuteGetGoogleFlowCharacters() { const tokenElement = document.getElementById('input-token'); const elementId = 'input'; const email = document.getElementById('input-email').value?.trim(); if (!email) return; const url = `https://api.useapi.net/v1/google-flow/characters?email=${encodeURIComponent(email)}`; const data = { method: 'GET', headers: { 'Authorization': `Bearer ${tokenElement.value}` } }; await apiExecute(url, elementId, data, { includeTimer: true }); } </script> === URL: https://useapi.net/docs/api-google-flow-v1/get-google-flow-jobs-jobid === Document URL: https://useapi.net/docs/api-google-flow-v1/get-google-flow-jobs-jobid --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> jobs/`jobid` description: "Poll status and retrieve results of a Google Flow generation job by ID via GET jobs/jobid in the useapi.net Google Flow API v1." parent: Google Flow API nav_order: 1310 --- ## Retrieve Job Status November 17, 2025 (November 16, 2026) --- Retrieve the status and details of a specific image or video generation job by its job ID. This endpoint is particularly useful when using [async mode](/docs/api-google-flow-v1/post-google-flow-videos) for video generation, or when tracking job progress via webhooks using the `replyUrl` parameter. To get load balancing statistics across all jobs, use [GET /jobs](/docs/api-google-flow-v1/get-google-flow-jobs). A job stays `created` while the request that submitted it is still solving the captcha. If that request ends early — most often because the client closed the connection before the API answered — the job can no longer progress, and after 30 minutes it is reported as `failed` with an explanation. Submit it again, and give `POST` requests several minutes before timing out, since captcha retries can take that long. > **https://api.useapi.net/v1/google-flow/jobs/`jobId`** ### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Path Parameters - `jobId` is **required**, the unique job identifier returned from [POST /images](/docs/api-google-flow-v1/post-google-flow-images) or [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos). ### Responses **200** **200 OK** Returns the job record with current status and details. **Video job (completed):** ```json { "jobid": "j1111190012345482913v-u12345-email:john@gmail.com-bot:google-flow", "type": "video", "status": "completed", "created": "2026-11-11T19:00:12.345Z", "updated": "2026-11-11T19:01:44.806Z", "request": { "email": "john@gmail.com", "prompt": "A serene mountain landscape at sunset with camera slowly panning right", "model": "veo-3.1-fast", "aspectRatio": "landscape", "count": 1, "async": true, "replyUrl": "https://your-domain.com/webhook" }, "response": { "operations": [], "media": [ { "name": "a1d95d21-75d2-482d-a354-14ef8802ce66", "projectId": "9f63078c-...redacted...", "workflowId": "fa986834-...redacted...", "mediaMetadata": { "createTime": "2026-11-11T19:01:04.498540Z", "mediaTitle": "A serene mountain landscape at sunset with camera slowly panning right", "mediaBlobSize": "3816736", "mediaStatus": { "mediaGenerationStatus": "MEDIA_GENERATION_STATUS_SUCCESSFUL" }, "visibility": "PRIVATE", "requestData": { "videoGenerationRequestData": { "backend": "flow", "statusEnum": 3, "aspectEnum": 2, "videoModelControlInput": { "videoModelName": "veo_3_1_t2v_fast", "videoGenerationMode": "VIDEO_GENERATION_MODE_TEXT_TO_VIDEO", "videoAspectRatio": "VIDEO_ASPECT_RATIO_LANDSCAPE", "videoResolution": "VIDEO_RESOLUTION_720P" } }, "promptInputs": [ { "structuredPrompt": { "parts": [ { "text": "A serene mountain landscape at sunset with camera slowly panning right" } ] } } ] } }, "video": { "generatedVideo": { "seed": 818896, "prompt": "A serene mountain landscape at sunset with camera slowly panning right", "model": "veo_3_1_t2v_fast", "baseImageMediaGenerationId": "", "isLooped": false, "aspectRatio": "VIDEO_ASPECT_RATIO_LANDSCAPE" }, "dimensions": { "length": "8s" }, "operation": { "name": "a1d95d21-75d2-482d-a354-14ef8802ce66" } }, "mediaGenerationId": "user:12345-email:6a6f...-video:a1d95d21-75d2-482d-a354-14ef8802ce66", "videoUrl": "https://flow-content.google/video/a1d95d21-75d2-482d-a354-14ef8802ce66?Expires=...", "thumbnailUrl": "https://flow-content.google/image/a1d95d21-75d2-482d-a354-14ef8802ce66?Expires=..." } ], "remainingCredits": 14845, "captcha": { "service": "CapSolver", "taskId": "b0bf7514-...redacted...", "durationMs": 3159, "attempts": [ { "service": "CapSolver", "success": true, "durationMs": 3159, "taskId": "b0bf7514-...redacted...", "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/156.0.0.0 Safari/537.36", "secChUa": "" } ] } } } ``` **Image job (completed):** ```json { "jobid": "j1108065148191735260i-u12345-email:jane@gmail.com-bot:google-flow", "type": "image", "status": "completed", "created": "2026-11-08T06:51:48.191Z", "updated": "2026-11-08T06:52:24.683Z", "request": { "email": "jane@gmail.com", "prompt": "A serene mountain landscape at sunset with vibrant colors", "model": "nano-banana-2", "aspectRatio": "16:9", "count": 1, "replyUrl": "https://your-domain.com/webhook", "replyRef": "custom-reference-123" }, "response": { "media": [ { "name": "ee2a8a64-d534-46fd-b834-e778a7f54d93", "workflowId": "b0b8b280-...redacted...", "image": { "generatedImage": { "seed": 515151, "mediaGenerationId": "user:12345-email:616e...-image:ee2a8a64-d534-46fd-b834-e778a7f54d93", "mediaVisibility": "", "prompt": "A serene mountain landscape at sunset with vibrant colors", "modelNameType": "BELUGA", "workflowId": "b0b8b280-...redacted...", "fifeUrl": "https://flow-content.google/image/ee2a8a64-d534-46fd-b834-e778a7f54d93?Expires=...&KeyName=labs-flow-prod-cdn-key&Signature=...", "aspectRatio": "IMAGE_ASPECT_RATIO_LANDSCAPE", "requestData": { "promptInputs": [ { "textInput": "A serene mountain landscape at sunset with vibrant colors" } ], "imageGenerationRequestData": { "backend": "flow", "referencesApplied": { "media": [], "entities": [] }, "aspectEnum": 3, "modelEnum": 36 } } }, "dimensions": { "width": 1376, "height": 768 } } } ], "captcha": { "service": "EzCaptcha", "taskId": "bded30b6...redacted...", "durationMs": 2702, "attempts": [ { "service": "SolveCaptcha", "success": false, "durationMs": 194, "error": "SolveCaptcha submit failed: ERROR_ZERO_BALANCE" }, { "service": "EzCaptcha", "success": true, "durationMs": 2502, "taskId": "bded30b6...redacted...", "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/156.0.0.0 Safari/537.36", "secChUa": "\"Not:A-Brand\";v=\"8\", \"Chromium\";v=\"156\", \"Google Chrome\";v=\"156\"" } ] } } } ``` **Job failed:** ```json { "jobid": "j1111130012345906417i-u12345-email:jane@gmail.com-bot:google-flow", "type": "image", "status": "failed", "created": "2026-11-11T13:00:12.345Z", "updated": "2026-11-11T13:00:45.678Z", "request": { "email": "jane@gmail.com", "prompt": "Generate an image", "model": "nano-banana-2" }, "error": "API error: 500", "code": 500, "response": { "error": { "code": 500, "message": "flow.google.com ogiZ0b failed", "status": "INTERNAL", "details": [] }, "captcha": { "service": "CapSolver", "taskId": "e1710fcf-...redacted...", "durationMs": 4064, "attempts": [ { "service": "CapSolver", "success": true, "durationMs": 4064, "taskId": "e1710fcf-...redacted..." } ] } } } ``` **400** **400 Bad Request** Invalid job ID format, or the job belongs to a different user. ```json { "error": "Invalid job ID format", "code": 400 } ``` ```json { "error": "Access denied - job belongs to different user", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **404** **404 Not Found** Job not found in database. ```json { "error": "Job not found", "code": 404 } ``` **410** **410 Gone** Job has expired (jobs are retained for 7 days). ```json { "error": "Job has expired", "code": 410 } ``` ### Model A job record has one of three shapes: a video job (POST [/videos](/docs/api-google-flow-v1/post-google-flow-videos), [/videos/upscale](/docs/api-google-flow-v1/post-google-flow-videos-upscale) and [/videos/extend](/docs/api-google-flow-v1/post-google-flow-videos-extend)), an image job ([POST /images](/docs/api-google-flow-v1/post-google-flow-images)) or a concatenation job ([POST /videos/concatenate](/docs/api-google-flow-v1/post-google-flow-videos-concatenate)). The `request` holds what you sent after validation, so each reference id you sent comes back as a `Reference` object, and every parameter you sent is kept, captcha settings included. <details markdown="block" class="model-details"> <summary>The job record for each job type, field by field, and the types it uses (<code>VideoRequest</code>, <code>UpscaleRequest</code>, <code>ExtendRequest</code>, <code>Reference</code>, <code>Captcha</code>, <code>GoogleError</code>)</summary> **Video Job** Video generation, upscale and extend jobs. ```typescript { jobid: string // Unique job identifier type: 'video' // Job type status: 'created' | 'started' | 'completed' | 'failed' // created: not yet sent to Google; started: Google is generating created: string // ISO 8601 creation timestamp updated?: string // ISO 8601 last update timestamp model?: string // The model that ran, only when it differs from the one asked for: a model Google // retired is routed to its replacement (from December 5, 2026) request: VideoRequest | UpscaleRequest | ExtendRequest // the request as you sent it, after validation, in the shape of the endpoint you // called: VideoRequest for POST /videos, UpscaleRequest for POST /videos/upscale, // ExtendRequest for POST /videos/extend response?: { // set once Google has answered (absent while the job is created) operations?: Array<{ // empty for videos and extensions. One item per video for an upscale operation: { // the upscale operation name: string // the media id metadata?: { // filled when the upscale is done '@type': string // Google's media record type name name: string // the media id video: { // the upscaled video seed: number // the seed Google used model: string // Google's own key for the upscale model aspectRatio: string // VIDEO_ASPECT_RATIO_LANDSCAPE | VIDEO_ASPECT_RATIO_PORTRAIT isLooped: boolean // always false prompt?: string // the prompt, when Google gave one upsampleResolution?: string // e.g. VIDEO_UPSAMPLE_RESOLUTION_1080P fifeUrl?: string // Signed video download URL, same as videoUrl servingBaseUri?: string // Signed thumbnail URL (the video URL when there is none) mediaGenerationId: string // Encoded reference ID of the upscaled video mediaVisibility?: string // "PRIVATE" } } } sceneId: string // always empty status: string // MEDIA_GENERATION_STATUS_PENDING until the upscale ends, then as the media item's mediaGenerationId?: string // Encoded reference ID of the upscaled video, once done }> media?: Array<{ // one item per video asked for (count) name: string // Media identifier (raw UUID) projectId: string // the Google Flow project the video is in workflowId?: string // the Google Flow workflow of the video workflowStepId?: string // the workflow step, when Google reports one mediaMetadata: { // Google's record of the video createTime?: string // ISO 8601 timestamp mediaTitle?: string // the prompt (absent on an upscale) mediaBlobSize?: string // the video's size in bytes, once done mediaStatus: { // generation status mediaGenerationStatus: string // MEDIA_GENERATION_STATUS_PENDING | MEDIA_GENERATION_STATUS_ACTIVE | // MEDIA_GENERATION_STATUS_SUCCESSFUL | MEDIA_GENERATION_STATUS_FAILED | // MEDIA_GENERATION_STATUS_UNKNOWN error?: { // why generation failed code: number // Google's error code (0 when it gave none) message: string // Google's reason, e.g. "PUBLIC_ERROR_IP_INPUT_IMAGE" } failureReasons?: string[] // Google's classifier labels, e.g. ["IP_PROHIBITED"] } visibility?: string // "PRIVATE" requestData: { // what Google recorded about the request videoGenerationRequestData: { // Google's generation settings backend: 'flow' // the request went through `flow.google.com` statusEnum: number | null // Google's raw status value aspectEnum: number | null // Google's raw aspect value videoModelControlInput?: { // the model settings Google ran videoModelName?: string // Google's own key for the model that ran videoGenerationMode?: string // e.g. VIDEO_GENERATION_MODE_TEXT_TO_VIDEO videoAspectRatio?: string // VIDEO_ASPECT_RATIO_LANDSCAPE | VIDEO_ASPECT_RATIO_PORTRAIT videoResolution?: string // e.g. VIDEO_RESOLUTION_720P } } promptInputs?: Array<object> // the prompt as Google received it, @-mentions included clientPlatform?: string // "CLIENT_PLATFORM_WEB" } } video: { // the video generatedVideo?: { // present once Google has generated the video seed: number // the seed Google used prompt: string // the prompt as Google ran it model: string // Google's own key for the model that ran baseImageMediaGenerationId?: string // empty string isLooped: boolean // always false aspectRatio: string // VIDEO_ASPECT_RATIO_LANDSCAPE | VIDEO_ASPECT_RATIO_PORTRAIT // (empty when Google did not say) upsampleMetadata?: { // on an upscaled video videoUpsampleResolution: string // VIDEO_UPSAMPLE_RESOLUTION_1080P | VIDEO_UPSAMPLE_RESOLUTION_720P } } dimensions?: { // present when Google reports the duration length: string // duration string (e.g. "8s") } operation: { // the generation operation name: string // the media id (same as name) } } mediaGenerationId?: string // Encoded reference ID for use in subsequent API calls, set when the job ends videoUrl?: string // Signed video download URL (MP4, valid ~6h) thumbnailUrl?: string // Signed thumbnail download URL (JPEG, valid ~6h) }> remainingCredits?: number // Google Flow credits left on the account, as Google reported them failureReasons?: string[] // Why every video failed, e.g. ["PUBLIC_ERROR_IP_INPUT_IMAGE", "IP_PROHIBITED"]. // Only on jobs where all videos failed, and only when Google gave a reason captcha?: Captcha // the captcha solve of this job captchaAttemptsCount?: number // how many captcha attempts the submit made. From the submit: present while the job is // started, and kept when the job fails before Google's result arrives (as are the next three) captchaProviders?: string // the providers of those attempts, in order, comma-separated (e.g. CapSolver,AntiCaptcha) tier?: string // the account's Google Flow plan tier at submit (e.g. PAYGATE_TIER_TWO) sku?: string // the account's Google plan code at submit (e.g. G1_TIER2) error?: string | GoogleError // on a failed job, one of two: a string, what went wrong in the API's own words, // or GoogleError, Google's error as Google returned it } error?: string // Error message (if failed) code?: number // HTTP status code (if failed) } ``` **`VideoRequest`**: the `request` of a [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) job. ```typescript { email: string // the account that ran the job (picked for you when not given) prompt: string // your prompt model?: 'veo-3.1-quality' | 'veo-3.1-fast' | 'veo-3.1-lite' | 'veo-3.1-lite-low-priority' | 'omni-flash' | 'omni-flash-1.2' // the model you asked for aspectRatio?: 'landscape' | 'portrait' // as requested duration?: number // seconds, as requested resolution?: '360p' | '720p' // as requested count?: number // 1-4 startImage?: Reference // first frame endImage?: Reference // last frame referenceImage_1?: Reference // reference image (referenceImage_1 to referenceImage_10, as many as you sent) referenceImage_2?: Reference // reference image referenceImage_3?: Reference // reference image referenceImage_4?: Reference // reference image referenceImage_5?: Reference // reference image referenceImage_6?: Reference // reference image referenceImage_7?: Reference // reference image referenceImage_8?: Reference // reference image referenceImage_9?: Reference // reference image referenceImage_10?: Reference // reference image character_1?: Reference // character (character_1 to character_10, as many as you sent) character_2?: Reference // character character_3?: Reference // character character_4?: Reference // character character_5?: Reference // character character_6?: Reference // character character_7?: Reference // character character_8?: Reference // character character_9?: Reference // character character_10?: Reference // character referenceAudio_1?: string // a built-in voice name (lowercase) or your voice's reference id, as sent referenceAudio_2?: string // voice, as referenceAudio_1 referenceAudio_3?: string // voice, as referenceAudio_1 referenceAudio_4?: string // voice, as referenceAudio_1 referenceAudio_5?: string // voice, as referenceAudio_1 referenceVideo_1?: Reference // the video to edit startFrameIndex_1?: number // edit window start frame, as requested endFrameIndex_1?: number // edit window end frame, as requested captchaToken?: string // your own captcha token, as sent captchaRetry?: number // as requested captchaOrder?: string[] // the captcha providers you named, in your order async?: boolean // Fire-and-forget mode replyUrl?: string // Webhook URL for callbacks replyRef?: string // Custom reference for callbacks } ``` **`UpscaleRequest`**: the `request` of a [POST /videos/upscale](/docs/api-google-flow-v1/post-google-flow-videos-upscale) job. ```typescript { email: string // the account of the source video mediaGenerationId: Reference // the video to upscale resolution?: '720p' | '1080p' | '4K' // as requested captchaToken?: string // your own captcha token, as sent captchaRetry?: number // as requested captchaOrder?: string[] // the captcha providers you named, in your order async?: boolean // Fire-and-forget mode replyUrl?: string // Webhook URL for callbacks replyRef?: string // Custom reference for callbacks } ``` **`ExtendRequest`**: the `request` of a [POST /videos/extend](/docs/api-google-flow-v1/post-google-flow-videos-extend) job. ```typescript { email: string // the account of the source video prompt: string // your prompt mediaGenerationId: Reference // the video to extend model?: 'omni-flash-1.2' | 'veo-3.1-quality' | 'veo-3.1-fast' | 'veo-3.1-lite' | 'veo-3.1-lite-low-priority' // the model you asked for duration?: number // seconds to add, as requested resolution?: '360p' | '720p' // as requested referenceImage_1?: Reference // reference image referenceImage_2?: Reference // reference image referenceImage_3?: Reference // reference image character_1?: Reference // character character_2?: Reference // character character_3?: Reference // character referenceAudio_1?: string // a built-in voice name (lowercase) or your voice's reference id, as sent referenceAudio_2?: string // voice, as referenceAudio_1 referenceAudio_3?: string // voice, as referenceAudio_1 count?: number // 1-4 captchaToken?: string // your own captcha token, as sent captchaRetry?: number // as requested captchaOrder?: string[] // the captcha providers you named, in your order async?: boolean // Fire-and-forget mode replyUrl?: string // Webhook URL for callbacks replyRef?: string // Custom reference for callbacks } ``` **Image Job** Image generation job structure. An image job is `created` until Google answers, then `completed` or `failed`. ```typescript { jobid: string // Unique job identifier type: 'image' // Job type status: 'created' | 'completed' | 'failed' // created: not yet answered by Google created: string // ISO 8601 creation timestamp updated?: string // ISO 8601 last update timestamp request: { // the request as you sent it, after validation email: string // the account that ran the job (picked for you when not given) prompt: string // your prompt model?: 'nano-banana-2-lite' | 'nano-banana-2' | 'nano-banana-pro' | 'imagen-4' | 'nano-banana' // as requested ('imagen-4' and 'nano-banana' are deprecated aliases) aspectRatio?: '16:9' | '4:3' | '1:1' | '3:4' | '9:16' | 'auto' | 'landscape' | 'portrait' // as requested ('landscape' and 'portrait' are legacy values) count?: number // 1-4 seed?: number // as requested thinkingLevel?: 'low' | 'medium' | 'high' // as requested reference_1?: Reference // reference image (reference_1 to reference_10, as many as you sent) reference_2?: Reference // reference image reference_3?: Reference // reference image reference_4?: Reference // reference image reference_5?: Reference // reference image reference_6?: Reference // reference image reference_7?: Reference // reference image reference_8?: Reference // reference image reference_9?: Reference // reference image reference_10?: Reference // reference image character_1?: Reference // character (character_1 to character_7, as many as you sent) character_2?: Reference // character character_3?: Reference // character character_4?: Reference // character character_5?: Reference // character character_6?: Reference // character character_7?: Reference // character captchaToken?: string // your own captcha token, as sent captchaRetry?: number // as requested captchaOrder?: string[] // the captcha providers you named, in your order replyUrl?: string // Webhook URL for callbacks replyRef?: string // Custom reference for callbacks } response?: { // the result, set once Google has answered media?: Array<{ // one item per image generated name: string // media id (raw UUID) workflowId: string // the Google Flow workflow of the image image: { // the image generatedImage: { // Google's record of the generated image seed: number // the seed Google used mediaGenerationId: string // reference id for later calls (upscale, references) mediaVisibility: string // always empty prompt: string // the prompt as Google ran it modelNameType: string // Google's model name, e.g. "BELUGA" (nano-banana-2) workflowId: string // the Google Flow workflow of the image (same as above) fifeUrl: string // Signed image URL (valid ~6h). Empty when Google gave none aspectRatio: string // e.g. IMAGE_ASPECT_RATIO_LANDSCAPE requestData: { // what Google recorded about the request promptInputs: Array<{ // the prompt textInput: string // your prompt }> imageGenerationRequestData: { // Google's generation settings backend: 'flow' // the request went through `flow.google.com` referencesApplied: { // the references Google used media: string[] // media ids of the reference images entities: string[] // entity ids of the characters } aspectEnum: number | null // Google's raw aspect value modelEnum: number | null // Google's raw model value } } } dimensions?: { // the image size, when Google reports it width: number // pixels height: number // pixels } } }> captcha?: Captcha // the captcha solve of this job error?: string | GoogleError // on a failed job, one of two: a string, what went wrong in the API's own words, // or GoogleError, Google's error as Google returned it } error?: string // Error message (if failed) code?: number // HTTP status code (if failed) } ``` **Concatenation Job** Concatenation jobs. [POST /videos/concatenate](/docs/api-google-flow-v1/post-google-flow-videos-concatenate) answers with the video itself. Its job record keeps only the outcome. ```typescript { jobid: string // Unique job identifier type: 'video' // Job type status: 'created' | 'started' | 'completed' | 'failed' // started: Google is joining the videos created: string // ISO 8601 creation timestamp updated?: string // ISO 8601 last update timestamp request: { // the request as you sent it, after validation email: string // the account of the videos media: Array<{ // the videos, in order mediaGenerationId: Reference // the video trimStart?: number // seconds trimmed from the start, as requested trimEnd?: number // seconds trimmed from the end, as requested }> } response?: { // set once Google has answered operationName?: string // Google's job name, while the job is started status?: string // MEDIA_GENERATION_STATUS_SUCCESSFUL, once completed inputsCount?: number // how many videos were joined, once completed hasEncodedVideo?: boolean // true once completed (the video itself was in the POST answer) encodedVideoLength?: number // length of that base64 video, once completed head?: Array<unknown> // Google's raw answer, when Google failed the concatenation backend?: 'flow' // the request went through `flow.google.com` error?: string | GoogleError // on a failed job, one of two: a string, what went wrong in the API's own words, // or GoogleError, Google's error as Google returned it } error?: string // Error message (if failed) code?: number // HTTP status code (if failed) } ``` A reference id you sent, decoded: **`Reference`**: each image, character or video reference in a job's `request` above, decoded. ```typescript { referenceId: string // the reference id as you sent it user: number // your useapi.net user number email: string // the account the media belongs to type: 'image' | 'video' | 'character' | 'voice' // what it points to id: string // Google's id: the media id, or the character's entity id meta?: { // characters only imgs: number // how many images the character has voiceWorkflowId?: string // the workflow of the character's voice, when it has one } } ``` The captcha solve of a job: **`Captcha`**: the `captcha` in a job's `response` above. ```typescript { service?: string // the provider whose token was used: `CapSolver`, `AntiCaptcha`, `YesCaptcha`, // `CapMonster`, `SolveCaptcha`, `2Captcha`, `EzCaptcha` or `UserProvided`. Only when a // token was found taskId?: string // the provider's task id of the token used durationMs?: number // ms from the first attempt to the token. Only when a token was found error?: string // why no captcha could be solved. Only when the captcha failed attempts: Array<{ // every provider tried, in order service: string // the provider success: boolean // true when the provider returned a token durationMs?: number // how long this attempt took, ms taskId?: string // the provider's task id error?: string // why the provider failed userAgent?: string // the browser the provider solved in secChUa?: string // that browser's Sec-CH-UA header cost?: string // the provider's price for this solve (AntiCaptcha, CapMonster, 2Captcha) ip?: string // the address the provider reports createTime?: number // the provider's task start, Unix seconds endTime?: number // the provider's task end, Unix seconds solveCount?: number // the provider's own counter request?: string // SolveCaptcha's raw answer }> } ``` Google's error, as Google returned it: **`GoogleError`**: the `error` in a job's `response` above, when it is Google's own error. ```typescript { code: number // HTTP status, e.g. 429 message: string // what failed, e.g. "flow.google.com ogiZ0b failed" status: string // e.g. RESOURCE_EXHAUSTED details?: Array<object> // Google's reasons, a list of error details } ``` </details> ### Missing media URLs Media URL fields are optional and can be absent even when generation succeeded. When `videoUrl`, `thumbnailUrl`, `fifeUrl`, `servingBaseUri`, `previewUrl` or `audioUrl` is missing, the media itself is fine — only the download link could not be produced at that moment. This is rare. Across the seven days of request logs we keep, it happened on one day only — twice, for about four hours and about forty minutes — and not at all on the other six. Google issues those links from an endpoint that limits how often it will answer a given network address, so it is Google limiting our outbound calls rather than useapi.net limiting you, and nothing you do triggers it. While it lasts it affects every account generating at that moment, then clears on its own. Your generation still completed and was charged as usual. On a media item that generated successfully — `mediaStatus.mediaGenerationStatus` is `MEDIA_GENERATION_STATUS_SUCCESSFUL` — a missing URL means "not yet", not "failed", so read the field before using it and treat its absence as a retry condition. A media item that failed generation never carries a URL, and retrying will not produce one. ``` javascript const url = media.videoUrl; if (!url) { // Not an error — the link is not available yet. See the options below. } ``` #### How to get the link Which route to use depends on whether you can wait. If you are already polling the job, do nothing special. Completed video jobs re-resolve missing URLs automatically on [GET /jobs/`jobId`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid), and the recovered link is saved, so a later poll returns it with no extra work on your side. This applies to video jobs created within the last 24 hours. Once the job is completed and a URL is still missing, leave at least a minute between polls — a job re-resolves at most once a minute, and the block clears only once traffic stops, so a tight retry loop lengthens the wait rather than shortening it. If you hold a `mediaGenerationId` but no longer have the job, ask for that one media again with [GET /assets/`mediaGenerationId`](/docs/api-google-flow-v1/get-google-flow-assets-mediagenerationid). That endpoint says which case you are in rather than leaving you to guess. A `503` with a `Retry-After` header means the link is coming and tells you how long to wait, so wait that long and ask again. A `404` means Google has no such media, and no amount of retrying will change it. If you cannot wait, download the video through us with [GET /assets/`mediaGenerationId``?raw=true`](/docs/api-google-flow-v1/get-google-flow-assets-mediagenerationid). It reads the media over a different Google route that the block does not touch, so it works immediately and keeps working while the other two return nothing. It is **video only**. Prefer the two link-based routes when you can. They hand you a link and you download straight from Google. The raw form moves the whole file through useapi.net on every call, which makes it a way out of a stuck download rather than your normal download path. Characters and voices resolve their URLs as they are read, so simply requesting [GET /characters/`ref`](/docs/api-google-flow-v1/get-google-flow-characters-ref) or [GET /voices/`ref`](/docs/api-google-flow-v1/get-google-flow-voices-ref) again is enough. Wait a minute before retrying — a response that came back without its URL is held briefly, so an immediate repeat returns the same one. None of this applies to images. Whenever an image URL is missing, [POST /images](/docs/api-google-flow-v1/post-google-flow-images) puts the image itself in the response instead, base64-encoded in `encodedImage` — so you already have the picture and there is nothing to retry. ### Examples **Curl** ```bash # Get job status curl "https://api.useapi.net/v1/google-flow/jobs/j1111190012345482913v-u12345-email:john@gmail.com-bot:google-flow" \ -H "Authorization: Bearer {API token}" # Poll for completion (check every 5 seconds) while true; do STATUS=$(curl -s "https://api.useapi.net/v1/google-flow/jobs/j1111190012345482913v-u12345-email:john@gmail.com-bot:google-flow" \ -H "Authorization: Bearer {API token}" | jq -r '.status') echo "Status: $STATUS" if [[ "$STATUS" == "completed" || "$STATUS" == "failed" ]]; then break fi sleep 5 done ``` **JavaScript** ```javascript const apiToken = 'your-api-token' const jobId = 'j1111190012345482913v-u12345-email:john@gmail.com-bot:google-flow' // Get job status async function getJobStatus(jobId) { const response = await fetch(`https://api.useapi.net/v1/google-flow/jobs/${jobId}`, { headers: { 'Authorization': `Bearer ${apiToken}` } }) if (!response.ok) { throw new Error(`HTTP ${response.status}: ${await response.text()}`) } return await response.json() } // Poll until completion async function waitForCompletion(jobId, intervalMs = 5000) { while (true) { const job = await getJobStatus(jobId) console.log(`Status: ${job.status}`) if (job.status === 'completed') { console.log('Job completed!', job.response) return job } if (job.status === 'failed') { console.error('Job failed:', job.error) throw new Error(job.error) } await new Promise(resolve => setTimeout(resolve, intervalMs)) } } // Usage const job = await waitForCompletion(jobId) ``` **Python** ```python import requests import time api_token = 'your-api-token' job_id = 'j1111190012345482913v-u12345-email:john@gmail.com-bot:google-flow' # Get job status def get_job_status(job_id: str) -> dict: response = requests.get( f'https://api.useapi.net/v1/google-flow/jobs/{job_id}', headers={'Authorization': f'Bearer {api_token}'} ) response.raise_for_status() return response.json() # Poll until completion def wait_for_completion(job_id: str, interval_sec: int = 5) -> dict: while True: job = get_job_status(job_id) print(f"Status: {job['status']}") if job['status'] == 'completed': print("Job completed!", job['response']) return job if job['status'] == 'failed': raise Exception(f"Job failed: {job.get('error')}") time.sleep(interval_sec) # Usage job = wait_for_completion(job_id) # Access video URLs (for video jobs) if job['type'] == 'video': for item in job['response']['media']: if 'videoUrl' in item: print(f"Video URL: {item['videoUrl']}") # Access image URLs (for image jobs) if job['type'] == 'image': for media in job['response']['media']: if 'image' in media and 'generatedImage' in media['image']: print(f"Image URL: {media['image']['generatedImage']['fifeUrl']}") ``` ### Try It <script> function displayGoogleFlowJobMedia(response, elementId) { const mediaContainer = document.getElementById(`${elementId}-media-links`); if (!mediaContainer) return; mediaContainer.innerHTML = ''; if (response.type === 'video' && response.response?.media) { const videos = []; response.response.media.forEach((item, index) => { if (item.videoUrl) { const seed = item.video?.generatedVideo?.seed; videos.push({ videoUrl: item.videoUrl, thumbUrl: item.thumbnailUrl, seed: seed, label: `Video ${videos.length + 1}${seed ? ` (seed: ${seed})` : ''}` }); } }); if (videos.length > 0) { const linksHTML = videos.map(vid => `<a href="${vid.videoUrl}" target="_blank" rel="noopener noreferrer" class="media-link video">${vid.label}</a>` ).join(' '); mediaContainer.innerHTML = `<div class="media-links-container"><strong>Generated Videos:</strong> ${linksHTML}</div>`; mediaContainer.style.display = 'block'; return; } } if (response.type === 'image' && response.response?.media) { const images = []; response.response.media.forEach((item, index) => { if (item.image?.generatedImage) { const img = item.image.generatedImage; images.push({ url: img.fifeUrl, seed: img.seed, label: `Image ${index + 1}${img.seed ? ` (seed: ${img.seed})` : ''}` }); } }); if (images.length > 0) { const linksHTML = images.map(img => `<a href="${img.url}" target="_blank" rel="noopener noreferrer" class="media-link image">${img.label}</a>` ).join(' '); mediaContainer.innerHTML = `<div class="media-links-container"><strong>Generated Images:</strong> ${linksHTML}</div>`; mediaContainer.style.display = 'block'; return; } } mediaContainer.style.display = 'none'; } async function apiExecuteGetGoogleFlowJobsJobId() { const tokenElement = document.getElementById('input-token'); const jobIdElement = document.getElementById('input-jobid'); const elementId = 'input'; const data = { method: 'GET', headers: { 'Authorization': `Bearer ${tokenElement.value}` } }; const mediaLinks = document.getElementById(`${elementId}-media-links`); if (mediaLinks) mediaLinks.style.display = 'none'; const status = await apiExecute( `https://api.useapi.net/v1/google-flow/jobs/${jobIdElement.value}`, elementId, data ); if (status === 200) { try { const content = document.getElementById(`${elementId}-response-json`); const response = JSON.parse(content.innerText); displayGoogleFlowJobMedia(response, elementId); } catch (e) { console.error('Failed to parse response for media display:', e); } } } </script> <form id="input" class="input-form" onsubmit="return false;"> <div class="input-field"> <div class="input-field-row"> <label for="input-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="input-token" type="text" class="input-element" required aria-required="true"> </label> <label for="input-jobid"><span>jobId (required)</span> <input id="input-jobid" type="text" class="input-element" required aria-required="true"> </label> </div> <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteGetGoogleFlowJobsJobId()">Go</button> </div> </form> <div id="input-media-links" style="display:none;"></div> <div id="input-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-google-flow-v1/get-google-flow-jobs === Document URL: https://useapi.net/docs/api-google-flow-v1/get-google-flow-jobs --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> jobs description: "Get real-time load-balancing statistics and job distribution across all Google Flow accounts via GET jobs in the useapi.net Google Flow API v1." parent: Google Flow API nav_order: 1300 --- ## Get Load Balancing Statistics November 17, 2025 (November 16, 2026) --- Get load balancing statistics across all configured Google Flow accounts. This endpoint provides real-time visibility into job distribution, account health, and performance metrics for both image and video generation. To retrieve a specific job, use [GET /jobs/`jobId`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid). > **https://api.useapi.net/v1/google-flow/jobs/?options=`options`** ### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Query Parameters - `options` is optional, controls the level of detail in the response (default: `summary`). Supported values: - `summary`: Returns aggregated stats per account (executing, completed, failed, rate limited counts) - `executing`: Adds details of currently executing jobs with elapsed time - `history`: Includes top 10 most recent completed jobs from the last 15 minutes ### Load Balancing Algorithm When you have multiple Google Flow accounts configured and don't specify an `email` parameter in [POST /images](/docs/api-google-flow-v1/post-google-flow-images), [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos), or [POST /assets](/docs/api-google-flow-v1/post-google-flow-assets-email), the API automatically selects the best account in two steps: a quarantine pre-filter, then a scoring algorithm over the survivors. #### Step 1 — Quarantine pre-filter Accounts that recently hit a known recoverable Google quota or throttle are excluded from scoring entirely until their quarantine expires. This avoids retrying an account that we already know cannot succeed, and pushes load to the remaining healthy accounts. Quarantines are recorded automatically when a generation request returns `429` with one of these reasons: | 429 reason | What gets pulled from rotation | Cooldown | |------------|--------------------------------|----------| | `PUBLIC_ERROR_`<br>`USER_REQUESTS_THROTTLED` | All models on the account — or uploads only, when POST /assets triggered it | ~30 min. From POST /assets, treat it as a minimum — it can persist | | `PUBLIC_ERROR_`<br>`USER_QUOTA_REACHED` | All models on the account | ~30 min | | `PUBLIC_ERROR_`<br>`PER_MODEL_DAILY_QUOTA_REACHED` | Only that model, on that account | Next UTC midnight | The fourth 429 variant, `UNUSUAL_ACTIVITY_TOO_MUCH_TRAFFIC`, means Google rejected the captcha and does not quarantine. Instead, every captcha Google rejected on an account in the last 15 minutes raises that account's score, so an account Google distrusts gets a smaller share of the work but is never cut off — see [When Google rejects captchas](/docs/api-google-flow-v1/get-google-flow-accounts-captcha-stats#when-google-rejects-captchas). Full meanings and caller-side handling are in the [429 reference](/docs/api-google-flow-v1/post-google-flow-videos#responses). Two `403`s also quarantine. `PUBLIC_ERROR_MODEL_ACCESS_DENIED` means Google refused that model on that account, so only that model on that account is pulled from rotation, for 1 hour. The next request after that re-tests the account. Since 2026-09-23 Google no longer offers `veo-3.1-lite-low-priority` to invited members of an Ultra $199 family plan, and this keeps those accounts out of the rotation for that model while they still serve every other model. `PUBLIC_ERROR_USER_MINOR` means Google treats the Google account as belonging to someone under 18 and refuses it for everything, so the whole account is pulled from rotation for 1 hour, uploads included, and then re-tested. Quarantine is idempotent: repeated refusals for the same `(account, reason, model)` tuple preserve the original `firstSeen` timestamp. Only the entry's TTL is refreshed if needed. If every account is quarantined for the requested model, the API returns `429` with `error: "no_eligible_account"` and a `Retry-After` header indicating the earliest cooldown. See the 429 response details on the image/video endpoints: [POST /images](/docs/api-google-flow-v1/post-google-flow-images#responses) / [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos#responses). Single-account exception. If you have exactly one valid Google Flow account configured, the quarantine pre-filter is skipped — your request always goes through to Google. Quarantine has no defensive value when there's no other account to fail over to, and blocking your only account would force you to wait when Google's quota may have already cleared. The quarantine entry is still recorded for telemetry, but doesn't block requests. Your call may still come back `429` from Google directly (with `retryAfter`/`Retry-After` set), in which case you should honor the suggested cooldown before retrying. Explicit `email` bypasses the filter. If you specify an `email` parameter (in the URL path or the request body), the load balancer is skipped entirely — your request goes to that account even if it's quarantined. Every `429` (including the `no_eligible_account` short-circuit) carries an HTTP `Retry-After: <seconds>` header and a body `retryAfter: <ISO timestamp>` field. The per-reason cooldown values are in the [429 reference](/docs/api-google-flow-v1/post-google-flow-videos#responses). The two `403`s that quarantine, `MODEL_ACCESS_DENIED` and `USER_MINOR`, use 1 hour. #### Step 2 — Scoring Among the accounts that survive Step 1, the API picks the one with the lowest score: Formula: `score = executing + completed + (failed × 10) + (rateLimited × 20)` Lower scores are better. The account with the lowest score receives the next job. Components: - `executing`: Number of jobs currently running on this account Weight: 1× (each executing job adds 1 point) Purpose: Distribute load evenly across accounts - `completed`: Number of jobs successfully completed in the last 15 minutes Weight: 1× (each completion adds 1 point) Purpose: Spread traffic across the pool over time — without this term, a "winning" account whose completions don't add to its score keeps being picked while idle accounts at score 0 wait their turn; with it, the winner self-limits within the rolling 15-minute window so other healthy accounts get a fair share - `failed`: Number of failed jobs (non-429 4xx/5xx responses) in last 15 minutes Weight: 10× (each failure adds 10 points) Purpose: Heavily penalize unreliable accounts - `rateLimited`: Number of 429 rate limit responses in last 15 minutes Weight: 20× (each rate limit adds 20 points) Purpose: Most heavily penalize rate-limited accounts to avoid hitting limits Example scores: - Idle account: `0 executing + 0 completed + 0 failed + 0 rateLimited = 0` (best) - 2 jobs running: `2 executing + 0 completed + 0 failed + 0 rateLimited = 2` - 5 recent completions: `0 executing + 5 completed + 0 failed + 0 rateLimited = 5` - 1 recent failure: `0 executing + 0 completed + 1 failed + 0 rateLimited = 10` - 1 rate limit hit: `0 executing + 0 completed + 0 failed + 1 rateLimited = 20` - Rate limited account: `0 executing + 0 completed + 0 failed + 2 rateLimited = 40` (worst) When multiple accounts have the same score, one is selected randomly. Job statistics older than 15 minutes are automatically removed from load balancing calculations. ### Responses **200** **200 OK** Returns load balancing statistics categorized by job type. With `options=summary` (default): ```json { "emails": [ "john@gmail.com", "jane@gmail.com" ], "videos": { "summary": { "john@gmail.com": { "executing": 2, "completed": 15, "failed": 0, "rateLimited": 0, "avgResponseTime": 125340.50, "score": 17 }, "jane@gmail.com": { "executing": 0, "completed": 8, "failed": 1, "rateLimited": 0, "avgResponseTime": 98234.75, "score": 18 } } }, "images": { "summary": { "john@gmail.com": { "executing": 1, "completed": 42, "failed": 0, "rateLimited": 0, "avgResponseTime": 12456.30, "score": 43 }, "jane@gmail.com": { "executing": 0, "completed": 38, "failed": 0, "rateLimited": 1, "avgResponseTime": 15234.80, "score": 58 } } }, "combined": { "summary": { "john@gmail.com": { "executing": 3, "completed": 57, "failed": 0, "rateLimited": 0, "avgResponseTime": 32145.60, "score": 60 }, "jane@gmail.com": { "executing": 0, "completed": 46, "failed": 1, "rateLimited": 1, "avgResponseTime": 42367.25, "score": 76 } } } } ``` With `options=executing`: Adds `executing` object with currently running jobs and their elapsed time in `MM:SS` format: ```json { "emails": [ "john@gmail.com", "jane@gmail.com" ], "videos": { "summary": { "..." }, "executing": { "j1117160034567304152v-u12345-email:john@gmail.com-bot:google-flow": { "email": "john@gmail.com", "timestamp": 1731859234567, "elapsed": "1:23" }, "j1117155812567721846v-u12345-email:john@gmail.com-bot:google-flow-http:200": { "email": "john@gmail.com", "timestamp": 1731859092567, "elapsed": "3:45" } } }, "images": { "summary": { "..." }, "executing": { "j1117160142567158390i-u12345-email:john@gmail.com-bot:google-flow": { "email": "john@gmail.com", "timestamp": 1731859302567, "elapsed": "0:15" } } }, "combined": { "summary": { "..." } } } ``` With `options=history`: Adds both `executing` and `history` objects with top 10 most recent completed jobs from last 15 minutes: ```json { "emails": [ "john@gmail.com", "jane@gmail.com" ], "videos": { "summary": { "..." }, "executing": { "..." }, "history": { "j1117154203456620917v-u12345-email:john@gmail.com-bot:google-flow": { "email": "john@gmail.com", "timestamp": 1731858123456, "httpStatus": 200, "responseTime": 125340 }, "j1117154354567843105v-u12345-email:jane@gmail.com-bot:google-flow": { "email": "jane@gmail.com", "timestamp": 1731858234567, "httpStatus": 500, "responseTime": 98234 } } }, "images": { "summary": { "..." }, "executing": { "..." }, "history": { "..." } }, "combined": { "summary": { "..." } } } ``` **400** **400 Bad Request** Invalid `options` parameter value. ```json { "error": "Invalid options parameter. Use: summary, executing, or history", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` ### Model Load statistics per account for video and image jobs, with the list of healthy accounts. <details markdown="block" class="model-details"> <summary>The load statistics, field by field</summary> ```typescript { emails: string[] // List of all configured healthy account emails videos: { // video jobs summary: { // stats per account, keyed by account email [email: string]: { executing: number // Currently running jobs completed: number // Successfully completed (2xx) in last 15min failed: number // Failed (4xx/5xx except 429) in last 15min rateLimited: number // Rate limited (429) in last 15min avgResponseTime: number // Average response time in milliseconds score: number // Load balancing score (lower is better) } } executing?: { // Only with options=executing or history [jobId: string]: { email: string // Account email timestamp: number // Unix timestamp (milliseconds) elapsed: string // Elapsed time in MM:SS format } } history?: { // Only with options=history [jobId: string]: { email: string // Account email timestamp: number // Unix timestamp (milliseconds) httpStatus: number // HTTP status code (200, 429, 500, etc.) responseTime?: number // Response time in milliseconds, when it was recorded } } } images: { // image jobs summary: { // stats per account, keyed by account email [email: string]: { executing: number // Currently running jobs completed: number // Successfully completed (2xx) in last 15min failed: number // Failed (4xx/5xx except 429) in last 15min rateLimited: number // Rate limited (429) in last 15min avgResponseTime: number // Average response time in milliseconds score: number // Load balancing score (lower is better) } } executing?: { // Only with options=executing or history [jobId: string]: { email: string // Account email timestamp: number // Unix timestamp (milliseconds) elapsed: string // Elapsed time in MM:SS format } } history?: { // Only with options=history [jobId: string]: { email: string // Account email timestamp: number // Unix timestamp (milliseconds) httpStatus: number // HTTP status code (200, 429, 500, etc.) responseTime?: number // Response time in milliseconds, when it was recorded } } } combined: { // video and image jobs added together summary: { // stats per account, keyed by account email [email: string]: { executing: number // Currently running jobs completed: number // Successfully completed (2xx) in last 15min failed: number // Failed (4xx/5xx except 429) in last 15min rateLimited: number // Rate limited (429) in last 15min avgResponseTime: number // Average response time in milliseconds score: number // Load balancing score (lower is better) } } } } ``` </details> ### Examples **Curl** ```bash # Get summary stats (default) curl "https://api.useapi.net/v1/google-flow/jobs" \ -H "Authorization: Bearer {API token}" # Get executing jobs with elapsed time curl "https://api.useapi.net/v1/google-flow/jobs/?options=executing" \ -H "Authorization: Bearer {API token}" # Get full history (last 15 minutes) curl "https://api.useapi.net/v1/google-flow/jobs/?options=history" \ -H "Authorization: Bearer {API token}" ``` **JavaScript** ```javascript const apiToken = 'your-api-token' // Get summary stats (default) const response = await fetch('https://api.useapi.net/v1/google-flow/jobs', { headers: { 'Authorization': `Bearer ${apiToken}` } }) const stats = await response.json() // Check which account has lowest score for images const imagesSummary = stats.images.summary const bestAccount = Object.entries(imagesSummary) .sort(([, a], [, b]) => a.score - b.score)[0] console.log('Best account for images:', bestAccount[0], 'score:', bestAccount[1].score) // Get executing jobs const execResponse = await fetch('https://api.useapi.net/v1/google-flow/jobs/?options=executing', { headers: { 'Authorization': `Bearer ${apiToken}` } }) const execStats = await execResponse.json() console.log('Currently executing videos:', Object.keys(execStats.videos.executing || {}).length) ``` **Python** ```python import requests api_token = 'your-api-token' headers = {'Authorization': f'Bearer {api_token}'} # Get summary stats (default) response = requests.get( 'https://api.useapi.net/v1/google-flow/jobs', headers=headers ) stats = response.json() # Check which account has lowest score for videos videos_summary = stats['videos']['summary'] best_account = min(videos_summary.items(), key=lambda x: x[1]['score']) print(f"Best account for videos: {best_account[0]}, score: {best_account[1]['score']}") # Get full history history_response = requests.get( 'https://api.useapi.net/v1/google-flow/jobs/?options=history', headers=headers ) history_stats = history_response.json() print(f"Image job history entries: {len(history_stats['images'].get('history', {}))}") ``` ### Try It <script> async function apiExecuteGetGoogleFlowJobs() { const tokenElement = document.getElementById('input-token'); const optionsElement = document.getElementById('input-options'); const url = new URL('https://api.useapi.net/v1/google-flow/jobs/'); if (optionsElement.value) { url.searchParams.append('options', optionsElement.value); } const data = { method: 'GET', headers: { 'Authorization': `Bearer ${tokenElement.value}` } }; await apiExecute(url.toString(), 'input', data); } </script> <form id="input" class="input-form" onsubmit="return false;"> <div class="input-field"> <div class="input-field-row"> <label for="input-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="input-token" type="text" class="input-element" required aria-required="true"> </label> <label for="input-options"><span>options (optional)</span> <select id="input-options" class="input-element"> <option value="summary">summary (default)</option> <option value="executing">executing</option> <option value="history">history</option> </select> </label> </div> <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteGetGoogleFlowJobs()">Go</button> </div> </form> <div id="input-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-google-flow-v1/get-google-flow-voices-ref === Document URL: https://useapi.net/docs/api-google-flow-v1/get-google-flow-voices-ref --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> voices/`ref` description: "Resolve a voice by ref to a playback URL via GET voices/ref in the useapi.net Google Flow API v1 — user voices return a fresh signed audioUrl valid for ~6 hours." parent: Google Flow API nav_order: 1120 --- ## Get Single Voice (with audioUrl) June 5, 2026 (November 16, 2026) --- Resolve a single voice by reference-id and return a fresh playback URL. - System voice (e.g. `Achernar`) — short-circuits to the static `sampleUrl` on `gstatic.com`. No upstream call. Instant. - User voice (encoded reference-id from [POST /voices](/docs/api-google-flow-v1/post-google-flow-voices)) — resolves a fresh signed `audioUrl` via Google's media-redirect endpoint. The URL is valid for ~6 hours. > **https://api.useapi.net/v1/google-flow/voices/`ref`** ### Path Parameters - `ref` is **required**, the voice to fetch. Either a system voice name (e.g. `Achernar`, case-insensitive) or a user voice reference-id returned by [POST /voices](/docs/api-google-flow-v1/post-google-flow-voices) (URL-encoded). ### Request Headers ``` yaml Authorization: Bearer {API token} ``` ### Responses **200** **200 OK** The voice: a user voice for a voice reference-id, as here, or a system voice for a system voice name. ```json { "voice": "user:12345-email:6a6f...-voice:d990a2f9-...-mid:d55b6d59-...", "source": "user", "displayName": "Cheerful Narrator", "workflowId": "d990a2f9-...", "mediaId": "d55b6d59-...", "baseVoice": "Achernar", "dialog": "Hello, this is a test voice.", "voicePerformance": "Cheerful, energetic delivery", "createTime": "2026-06-05T18:25:32.847291Z", "audioUrl": "https://flow-content.google/audio/d55b6d59-...?Expires=...&KeyName=labs-flow-prod-cdn-key&Signature=..." } ``` **200** **200 OK** A system voice, for a system voice name such as `Achernar`. ```json { "voice": "Achernar", "source": "system", "displayName": "Achernar", "sampleUrl": "https://www.gstatic.com/aitestkitchen/voices/samples/Achernar.wav" } ``` **400** **400 Bad Request** The path segment is neither a known system voice name nor a recognized user voice reference-id. ```json { "error": "Parameter voiceRef is neither a system voice name nor a recognized user voice reference-id", "code": 400 } ``` **403** **403 Forbidden** The reference belongs to a different user. ```json { "error": "Unauthorized access to user:12345 detected in voice reference", "code": 403 } ``` **404** **404 Not Found** The voice doesn't exist (deleted or never created). ```json { "error": "Voice not found: d990a2f9-...", "code": 404 } ``` ### Model The voice: a system preset with its sample link, or one of your own voices with its audio link. <details markdown="block" class="model-details"> <summary>The system voice or custom voice, field by field</summary> ```typescript // System voice { voice: string // base preset name (e.g. "Achernar") source: 'system' // a system voice preset displayName: string // same as voice sampleUrl: string // a static Google link } // User voice { voice: string // reference-id for subsequent calls source: 'user' // a custom voice (POST /voices) displayName: string // the voice's name ('Untitled Voice' when it has none) workflowId: string // Google Flow workflow of the voice mediaId: string // media id of the voice's audio baseVoice?: string // system preset the user voice derives from, when Google reports it dialog?: string // the text the voice speaks in its sample voicePerformance?: string // the delivery style createTime?: string // ISO 8601 timestamp audioUrl?: string // signed playback URL (~6h TTL); occasionally absent on transient resolution failure } ``` </details> ### Examples **Curl** ``` bash # System voice curl -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v1/google-flow/voices/Achernar" # User voice — URL-encode the reference! REF="user:12345-email:6a6f...-voice:d990a2f9-...-mid:d55b6d59-..." REF_ENC=$(printf '%s' "$REF" | jq -sRr @uri) curl -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v1/google-flow/voices/$REF_ENC" ``` **JavaScript** ``` javascript const ref = 'user:12345-email:6a6f...-voice:d990a2f9-...-mid:d55b6d59-...' const r = await fetch( `https://api.useapi.net/v1/google-flow/voices/${encodeURIComponent(ref)}`, { headers: { 'Authorization': `Bearer ${token}` } } ) const v = await r.json() console.log('audio:', v.audioUrl || v.sampleUrl) ``` **Python** ``` python import requests, urllib.parse ref = 'user:12345-email:6a6f...-voice:d990a2f9-...-mid:d55b6d59-...' r = requests.get( f'https://api.useapi.net/v1/google-flow/voices/{urllib.parse.quote(ref, safe="")}', headers={'Authorization': f'Bearer {token}'}, ) v = r.json() print('audio:', v.get('audioUrl') or v.get('sampleUrl')) ``` ### Try It <form id="input" class="input-form" onsubmit="return false;"> <div class="input-field"> <div class="input-field-row"> <label for="input-token"><span>API Token</span> <input id="input-token" type="text" class="input-element" required aria-required="true"> </label> <label for="input-ref"><span>ref (system voice name OR user voice reference-id from <a href="/docs/api-google-flow-v1/post-google-flow-voices">POST /voices</a>)</span> <input id="input-ref" type="text" class="input-element" required aria-required="true" placeholder="Achernar or user:12345-email:...-voice:...-mid:..."> </label> </div> <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteGetGoogleFlowVoiceByRef()">Go</button> </div> </form> <div id="input-audio-preview" style="display:none;margin-top:8px"><strong>Preview:</strong><br><audio id="input-audio" class="audio-player" controls></audio></div> <div id="input-response" class="response-placeholder visible-false"></div> <script> async function apiExecuteGetGoogleFlowVoiceByRef() { const tokenElement = document.getElementById('input-token'); const elementId = 'input'; const ref = document.getElementById('input-ref').value?.trim(); if (!ref) return; const url = `https://api.useapi.net/v1/google-flow/voices/${encodeURIComponent(ref)}`; const data = { method: 'GET', headers: { 'Authorization': `Bearer ${tokenElement.value}` } }; const audioPreview = document.getElementById('input-audio-preview'); audioPreview.style.display = 'none'; const status = await apiExecute(url, elementId, data, { includeTimer: true }); if (status === 200) { try { const content = document.getElementById(`${elementId}-response-json`); const v = JSON.parse(content.innerText); const src = v.audioUrl || v.sampleUrl; if (src) { const audio = document.getElementById('input-audio'); audio.src = src; audioPreview.style.display = 'block'; } } catch (e) {}; } } </script> === URL: https://useapi.net/docs/api-google-flow-v1/get-google-flow-voices === Document URL: https://useapi.net/docs/api-google-flow-v1/get-google-flow-voices --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> voices description: "List system voice presets and custom user voices for a Google Flow account via GET voices in the useapi.net Google Flow API v1 — a fast index without playback URLs." parent: Google Flow API nav_order: 1110 --- ## List Voices June 5, 2026 (November 16, 2026) --- List both **system** voices (the 30 built-in TTS presets) and **user** voices (custom voices created via [POST /voices](/docs/api-google-flow-v1/post-google-flow-voices)) for an account. This endpoint is intentionally **fast** — it does NOT resolve playback URLs for user voices. If you need an `audioUrl` to play a specific user voice, call [GET /voices/`ref`](/docs/api-google-flow-v1/get-google-flow-voices-ref) for the single voice you want to play. System voices have a static `sampleUrl` on the response (gstatic.com asset, never expires). > **https://api.useapi.net/v1/google-flow/voices** ### Request Headers ``` yaml Authorization: Bearer {API token} ``` ### Query Parameters - `email` — **required.** Account whose voices to list. - `source` — optional filter. One of `system`, `user`. Omit to get both. ### Responses **200** **200 OK** ```json { "voices": [ { "voice": "Achernar", "source": "system", "displayName": "Achernar", "sampleUrl": "https://www.gstatic.com/aitestkitchen/voices/samples/Achernar.wav" }, { "voice": "user:12345-email:6a6f...-voice:d990a2f9-...-mid:d55b6d59-...", "source": "user", "displayName": "Cheerful Narrator", "workflowId": "d990a2f9-...", "mediaId": "d55b6d59-...", "baseVoice": "Achernar", "dialog": "Hello, this is a test voice.", "voicePerformance": "Cheerful, energetic delivery", "createTime": "2026-06-05T18:25:32.847291Z" } ] } ``` Notes: - `system` voices ship with a static `sampleUrl` (always playable, no expiration). - `user` voices do **not** include `audioUrl` here. Hit [GET /voices/`ref`](/docs/api-google-flow-v1/get-google-flow-voices-ref) to get a fresh signed `audioUrl` for the one you want to play. - If no user voices have been created yet, the `user` section is just empty — no error. **400** **400 Bad Request** ```json { "error": "Parameter email is required", "code": 400 } ``` **404** **404 Not Found** ```json { "error": "Google Flow account john@gmail.com not found", "code": 404 } ``` ### Model The 30 system voice presets first, then the account's own voices, each with its reference-id and name. <details markdown="block" class="model-details"> <summary>The list of voices, field by field</summary> ```typescript { voices: Array< // the 30 system voice presets (source system) first, then the account's own voices made // with POST /voices (source user). The source query parameter keeps one kind. The list // has no audioUrl: GET /voices/{ref} returns it for a user voice | { voice: string // base preset name (e.g. "Achernar") source: 'system' // a system voice preset displayName: string // same as voice sampleUrl: string // a static Google link that does not expire } | { voice: string // reference-id for subsequent calls source: 'user' // a custom voice (POST /voices) displayName: string // the voice's name ('Untitled Voice' when it has none) workflowId: string // Google Flow workflow of the voice mediaId: string // media id of the voice's audio baseVoice?: string // system preset the user voice derives from, when Google reports it dialog?: string // the text the voice speaks in its sample voicePerformance?: string // the delivery style createTime?: string // ISO 8601 timestamp } > } ``` </details> ### Examples **Curl** ``` bash # All voices curl -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v1/google-flow/voices?email=john@gmail.com" # Only user voices curl -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v1/google-flow/voices?email=john@gmail.com&source=user" ``` **JavaScript** ``` javascript const r = await fetch( `https://api.useapi.net/v1/google-flow/voices?email=${email}&source=user`, { headers: { 'Authorization': `Bearer ${token}` } } ) const { voices } = await r.json() console.log(voices.map(v => v.displayName)) ``` **Python** ``` python import requests r = requests.get( 'https://api.useapi.net/v1/google-flow/voices', headers={'Authorization': f'Bearer {token}'}, params={'email': 'john@gmail.com', 'source': 'user'}, ) for v in r.json()['voices']: print(v['displayName'], '→', v['voice']) ``` ### Try It <form id="input" class="input-form" onsubmit="return false;"> <div class="input-field"> <div class="input-field-row"> <label for="input-token"><span>API Token</span> <input id="input-token" type="text" class="input-element" required aria-required="true"> </label> <label for="input-email"><span>email (required)</span> <input id="input-email" type="text" class="input-element input-query-param" required aria-required="true" placeholder="john@gmail.com"> </label> <label for="input-source"><span>source (optional)</span> <select id="input-source" class="input-element input-query-param"> <option value="">(both)</option> <option value="system">system</option> <option value="user">user</option> </select> </label> </div> <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecuteGetGoogleFlowVoices()">Go</button> </div> </form> <div id="input-response" class="response-placeholder visible-false"></div> <script> async function apiExecuteGetGoogleFlowVoices() { const tokenElement = document.getElementById('input-token'); const elementId = 'input'; const params = new URLSearchParams(); document.querySelectorAll('.input-query-param').forEach(input => { const id = input.id; const value = input.value?.trim(); if (id.startsWith('input-') && value) params.set(id.replace('input-', ''), value); }); const url = `https://api.useapi.net/v1/google-flow/voices?${params.toString()}`; const data = { method: 'GET', headers: { 'Authorization': `Bearer ${tokenElement.value}` } }; await apiExecute(url, elementId, data, { includeTimer: true }); } </script> === URL: https://useapi.net/docs/api-google-flow-v1 === Document URL: https://useapi.net/docs/api-google-flow-v1 --- layout: default title: Google Flow API seo_title: "Google Flow API (No API Key): Veo 3.1, Omni Flash, Nano Banana" nav_logo: /assets/images/google-flow.svg nav_divider_before: true nav_title: Google Flow API description: "Third-party Google Flow API: Omni 1.2 Flash, Omni 1.1 Flash and Veo 3.1 video and Nano Banana images with a Google Flow website subscription. No Gemini API key." nav_order: 2000 has_children: true permalink: /docs/api-google-flow-v1 repo: https://github.com/useapi/google-flow-api --- # <img style="height:1em;vertical-align: middle;" src="/assets/images/google-flow.svg" alt=""> Google Flow API November 17, 2025 (November 20, 2026) This is a [third-party](/docs/legal#affiliation--third-party-services) API for [Google Flow](https://flow.google.com) by [Google Labs](https://labs.google). It uses your [Google AI subscription](https://gemini.google/subscriptions/): Free, Plus $4.99 (or [$9.99 with 2 TB of storage](https://one.google.com/about/plans)), Pro $19.99, Ultra $99.99 or Ultra $199.99 a month (as of November 2026). Through a REST API and a hosted MCP server, it makes videos with Omni 1.2 Flash, Omni 1.1 Flash and Veo 3.1 and images with Nano Banana Pro, 2.1 and 2 Lite, and lets you chat with Google Flow Agent. You don't need a Google Cloud account or a Google API key, which Google's own Veo API requires. An 8-second Veo 3.1 Fast video costs $0.08 on Ultra $199.99, against $0.80 on Google's own Veo API. ## Models | Model | What it makes | Notes | |---|---|---| | [Omni 1.2 Flash](https://cloud.google.com/blog/products/ai-machine-learning/gemini-omni-1-2-flash-generally-available)<br>`omni-flash-1.2` | Video with sound from text, a start and an end frame, up to 10 reference images, up to 5 [voices](/docs/api-google-flow-v1/get-google-flow-voices), [characters](/docs/api-google-flow-v1/get-google-flow-characters), and edits of an existing video | 3 to 15 seconds (up to 10 on a free plan), 360p or 720p, 1 to 4 per request, [extend](/docs/api-google-flow-v1/post-google-flow-videos-extend) by 3 to 10 seconds at a time, [upscale](/docs/api-google-flow-v1/post-google-flow-videos-upscale) to 1080p, or 4K on Ultra | | [Omni 1.1 Flash](https://deepmind.google/models/model-cards/gemini-omni-flash/)<br>`omni-flash` | Video with sound from text, a start and an end frame, up to 7 reference images, up to 5 [voices](/docs/api-google-flow-v1/get-google-flow-voices), [characters](/docs/api-google-flow-v1/get-google-flow-characters), and edits of an existing video | 4, 6, 8 or 10 seconds on paid plans, 360p or 720p, 1 to 4 per request, [extend](/docs/api-google-flow-v1/post-google-flow-videos-extend) with Omni 1.2, [upscale](/docs/api-google-flow-v1/post-google-flow-videos-upscale) to 1080p, or 4K on Ultra Retiring 2026-12-05, then runs as `omni-flash-1.2` | | [Veo 3.1](https://aistudio.google.com/models/veo-3) Fast, Quality and Lite<br>`veo-3.1-fast`, `veo-3.1-quality`, `veo-3.1-lite` | [Video](/docs/api-google-flow-v1/post-google-flow-videos) from text, from a start and an end frame, or from up to 3 reference images and a voice | 8 seconds with sound on every plan, 4 or 6 seconds on Ultra only, 1 to 4 per request, [extend](/docs/api-google-flow-v1/post-google-flow-videos-extend) with Omni 1.2, [upscale](/docs/api-google-flow-v1/post-google-flow-videos-upscale) to 1080p, or 4K on Ultra Fast and Quality retire on 2026-12-05 and then run as Lite and as `omni-flash-1.2` | | [Nano Banana 2 Lite](https://deepmind.google/models/gemini-image/flash-lite/) (Gemini 3.1 Flash-Lite Image), Nano Banana 2.1 and [Nano Banana Pro](https://deepmind.google/models/gemini-image/pro/) (Gemini 3 Pro Image)<br>`nano-banana-2-lite`, `nano-banana-2`, `nano-banana-pro` | [Images](/docs/api-google-flow-v1/post-google-flow-images) from text and up to 10 reference images | 2 Lite is the default, 1 to 4 per request in about 10 to 20 seconds, Nano Banana 2.1 with a low, medium or high thinking level, [upscale](/docs/api-google-flow-v1/post-google-flow-images-upscale) to 2K, or 4K on Ultra | | More | [Join videos](/docs/api-google-flow-v1/post-google-flow-videos-concatenate), [GIFs](/docs/api-google-flow-v1/post-google-flow-videos-gif), your own [voices](/docs/api-google-flow-v1/post-google-flow-voices) and [characters](/docs/api-google-flow-v1/post-google-flow-characters) | Join 2 to 10 clips, joins and GIFs need no captcha, voices build on 30 presets, characters hold 1 or 2 images and a voice | ## Agent Chat with Google Flow Agent, Flow's built-in creative assistant, through the [Agent API](/docs/api-google-flow-v1/agent): send it images, videos, voices and characters, follow its replies live, approve what it wants to spend and collect the images and videos it makes. Chatting costs no credits, and what it makes costs the usual Flow price. The [live demo](/demos/google-flow/) is a complete chat client built on it, with the [API call behind each feature](/docs/api-google-flow-v1/agent-demo). ## MCP server The hosted [Google Flow MCP server](/docs/api-google-flow-v1/mcp) gives Claude Code, Cursor, VS Code and other AI assistants 12 tools to chat with Google Flow Agent, approve what it spends, manage chats and settings, list your characters, voices, images and videos, and upload images, with your useapi.net API token and nothing to install. The [google-flow-api](https://github.com/useapi/google-flow-api) repo also adds it in one step as a [Claude Code plugin](https://github.com/useapi/google-flow-api#use-with-claude-code) or a [Gemini CLI extension](https://github.com/useapi/google-flow-api#use-with-gemini-cli). ## Pricing What one video or image costs on the official Google API and on each Google AI subscription. Official prices are from the [Gemini API](https://ai.google.dev/gemini-api/docs/pricing), Google Cloud's [Agent Platform](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing) for Veo (priced per second, "per count" there), and [Google Cloud](https://cloud.google.com/blog/products/ai-machine-learning/gemini-omni-1-2-flash-generally-available) for Omni 1.2 Flash. Each subscription comes with a monthly number of Flow credits, and each video or image uses a set number of them, so each one costs its share of the subscription. | 模型 | [官方 API](https://ai.google.dev/gemini-api/docs/pricing) | Ultra $199.99/月 (每月 25,000 积分) | Ultra $99.99/月 (每月 10,000 积分) | Pro $19.99/月 (每月 1,000 积分) | Plus $4.99/月 (每月 200 积分) | |---|---|---|---|---|---| | Veo 3.1 Fast (720p,8 秒) | $0.80 (每秒 $0.10) | $0.08 / 10 积分 (每月 2,500 条) | $0.10 / 10 积分 (每月 1,000 条) | $0.40 / 20 积分 (每月 50 条) | $0.50 / 20 积分 (每月 10 条) | | Veo 3.1 Quality (720p,8 秒) | $3.20 (每秒 $0.40) | $0.80 / 100 积分 (每月 250 条) | $1.00 / 100 积分 (每月 100 条) | $2.00 / 100 积分 (每月 10 条) | $2.50 / 100 积分 (每月 2 条) | | Veo 3.1 Lite (720p,8 秒) | $0.40 (每秒 $0.05) | $0.04 / 5 积分 (每月 5,000 条) | $0.05 / 5 积分 (每月 2,000 条) | $0.20 / 10 积分 (每月 100 条) | $0.25 / 10 积分 (每月 20 条) | | Veo 3.1 Lite (低优先级,720p,8 秒) | — | $0 / 0 积分 (每天约 1,000 条或更多) | — | — | — | | 视频放大 (360p 至 720p) | — | $0 / 0 积分 (已包含) | $0 / 0 积分 (已包含) | $0 / 0 积分 (已包含) | $0 / 0 积分 (已包含) | | 视频放大 (1080p) | — | $0 / 0 积分 (已包含) | $0 / 0 积分 (已包含) | $0 / 0 积分 (已包含) | $0 / 0 积分 (已包含) | | 视频放大 (4K) | — | $0.40 / 50 积分 (每月 500 条) | $0.50 / 50 积分 (每月 200 条) | — | — | | Omni 1.2 Flash (720p,15 秒) | $1.04 (每秒约 $0.07) | $0.48 / 60 积分 (每月 416 条) | $0.60 / 60 积分 (每月 166 条) | $1.20 / 60 积分 (每月 16 条) | $1.50 / 60 积分 (每月 3 条) | | Omni 1.2 Flash (360p,15 秒) | $0.35 (每秒 $0.023) | $0.16 / 20 积分 (每月 1,250 条) | $0.20 / 20 积分 (每月 500 条) | $0.40 / 20 积分 (每月 50 条) | $0.50 / 20 积分 (每月 10 条) | | Omni 1.1 Flash (720p,10 秒) | $1.01 (每秒 $0.10) | $0.12 / 15 积分 (每月 1,666 条) | $0.15 / 15 积分 (每月 666 条) | $0.30 / 15 积分 (每月 66 条) | $0.37 / 15 积分 (每月 13 条) | | Omni 1.1 Flash (360p,10 秒) | — | $0.06 / 7 积分 (每月 3,571 条) | $0.07 / 7 积分 (每月 1,428 条) | $0.14 / 7 积分 (每月 142 条) | $0.17 / 7 积分 (每月 28 条) | | Nano Banana Pro | $0.134 (每张) | $0 / 0 积分 (每天最多约 500 张) | $0 / 0 积分 (已包含) | $0 / 0 积分 (已包含) | $0 / 0 积分 (已包含) | | Nano Banana 2.1 | $0.034 (每张) | $0 / 0 积分 (每天最多约 500 张) | $0 / 0 积分 (已包含) | $0 / 0 积分 (已包含) | $0 / 0 积分 (已包含) | | Nano Banana 2 Lite | $0.034 (每张) | $0 / 0 积分 (每天最多约 500 张) | $0 / 0 积分 (已包含) | $0 / 0 积分 (已包含) | $0 / 0 积分 (已包含) | | Model | [Official API](https://ai.google.dev/gemini-api/docs/pricing) | Ultra $199.99/m (25,000 cr/mo) | Ultra $99.99/m (10,000 cr/mo) | Pro $19.99/m (1,000 cr/mo) | Plus $4.99/m (200 cr/mo) | |---|---|---|---|---|---| | Veo 3.1 Fast (720p, 8s) | $0.80 ($0.10/s) | $0.08 / 10 cr (2,500 videos/mo) | $0.10 / 10 cr (1,000 videos/mo) | $0.40 / 20 cr (50 videos/mo) | $0.50 / 20 cr (10 videos/mo) | | Veo 3.1 Quality (720p, 8s) | $3.20 ($0.40/s) | $0.80 / 100 cr (250 videos/mo) | $1.00 / 100 cr (100 videos/mo) | $2.00 / 100 cr (10 videos/mo) | $2.50 / 100 cr (2 videos/mo) | | Veo 3.1 Lite (720p, 8s) | $0.40 ($0.05/s) | $0.04 / 5 cr (5,000 videos/mo) | $0.05 / 5 cr (2,000 videos/mo) | $0.20 / 10 cr (100 videos/mo) | $0.25 / 10 cr (20 videos/mo) | | Veo 3.1 Lite (low priority, 8s) | — | $0 / 0 cr (1,000+ a day) | — | — | — | | Video upscale (360p to 720p) | — | $0 / 0 cr (included) | $0 / 0 cr (included) | $0 / 0 cr (included) | $0 / 0 cr (included) | | Video upscale (1080p) | — | $0 / 0 cr (included) | $0 / 0 cr (included) | $0 / 0 cr (included) | $0 / 0 cr (included) | | Video upscale (4K) | — | $0.40 / 50 cr (500 videos/mo) | $0.50 / 50 cr (200 videos/mo) | — | — | | Omni 1.2 Flash (720p, 15s) | $1.04 ($0.07/s) | $0.48 / 60 cr (416 videos/mo) | $0.60 / 60 cr (166 videos/mo) | $1.20 / 60 cr (16 videos/mo) | $1.50 / 60 cr (3 videos/mo) | | Omni 1.2 Flash (360p, 15s) | $0.35 ($0.023/s) | $0.16 / 20 cr (1,250 videos/mo) | $0.20 / 20 cr (500 videos/mo) | $0.40 / 20 cr (50 videos/mo) | $0.50 / 20 cr (10 videos/mo) | | Omni 1.1 Flash (720p, 10s) | $1.01 ($0.10/s) | $0.12 / 15 cr (1,666 videos/mo) | $0.15 / 15 cr (666 videos/mo) | $0.30 / 15 cr (66 videos/mo) | $0.37 / 15 cr (13 videos/mo) | | Omni 1.1 Flash (360p, 10s) | — | $0.06 / 7 cr (3,571 videos/mo) | $0.07 / 7 cr (1,428 videos/mo) | $0.14 / 7 cr (142 videos/mo) | $0.17 / 7 cr (28 videos/mo) | | Nano Banana Pro | $0.134 (per image) | $0 / 0 cr (~500 a day) | $0 / 0 cr (included) | $0 / 0 cr (included) | $0 / 0 cr (included) | | Nano Banana 2.1 | $0.034 (per image) | $0 / 0 cr (~500 a day) | $0 / 0 cr (included) | $0 / 0 cr (included) | $0 / 0 cr (included) | | Nano Banana 2 Lite | $0.034 (per image) | $0 / 0 cr (~500 a day) | $0 / 0 cr (included) | $0 / 0 cr (included) | $0 / 0 cr (included) | - A free Google account gets [50 Flow credits a day](https://support.google.com/flow/answer/16526234), enough for 2 Veo 3.1 Fast or 5 Lite videos, or Omni 1.2 Flash videos of up to 10 seconds (8 seconds at 360p is 8 credits), and images cost nothing. Omni 1.2 Flash longer than 10 seconds, extending with Omni 1.2, Omni 1.1 Flash and video upscaling need a paid subscription. During Google's peak hours, roughly 2 PM to 5 PM UTC, a free account may not be able to make videos, while images still work (Google's Flow help, checked November 16, 2026). - Veo 3.1 Lite at lower priority runs only for the owner of an Ultra $199.99 plan, not for the family members the owner invites. - Each video and image needs a captcha, which the API solves for you. Your first account gets 300 free, then your own [captcha provider](/docs/start-here/setup-google-flow#configure-captcha-providers) costs about $0.80 to $3.00 per 1,000. - The per-day counts in the free cells (Veo 3.1 Lite at lower priority and the Nano Banana images) are averages from our busiest real accounts, not guarantees: Google sets those limits and does not publish them. Plan prices are Google's US prices. - The [Veo 3.1 API pricing](/docs/articles/veo-3-1-api-pricing) article compares every Veo price with a real run. #### One Google account, four APIs The same Google AI plan powers several useapi.net APIs, each from its own allowance, so one Google account connected to all of them gets the most out of the plan: - [Google Flow API](/docs/api-google-flow-v1): Veo 3.1, Omni 1.2 Flash and Omni 1.1 Flash video, Nano Banana images up to 4K, from Flow credits. - [Google Vids API](/docs/api-google-vids-v1): Omni 1.2 Flash video up to 15 seconds, 30-second [talking avatar videos](/docs/api-google-vids-v1/post-google-vids-videos-avatar) from a photo, avatars in 30 voices and [text to speech](/docs/api-google-vids-v1/post-google-vids-speech), from the Vids allowance, which does not use Flow credits. - [Gemini Notebook API (NotebookLM API)](/docs/api-gemini-notebook-v1): chat with sources, Deep Research and every Studio output, from the Gemini Notebook usage limits. - [Flow Music API](/docs/api-flowmusic-v1): full songs with Lyria in Google Flow Music, on the Flow Music plan your Google AI subscription includes (Starter on [Plus](https://support.google.com/googleone/answer/16882689), Plus on [Pro](https://support.google.com/googleone/answer/14534406), Member on [Ultra](https://support.google.com/googleone/answer/16286513)) or on Flow Music's own plans. Each API is set up on its own setup page, and one useapi.net subscription covers all of them. ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. ## Run several Google Flow accounts You can connect up to 50 Google Flow accounts. Video and image requests don't need `email`: each job goes to your healthiest account, and an account Google is limiting sits out until its wait is over ([how accounts are picked](/docs/api-google-flow-v1/get-google-flow-jobs#load-balancing-algorithm)). When no account can take the job you get `429`, so wait and send it again. Pass `email` to run a job on a specific account. A job that uses an uploaded image, a reference or a character runs on the account that holds it. Video and image requests can also send each status change to your webhook, so you don't have to hold the connection open while a video takes its usual 60 to 180 seconds ([callbacks](/docs/api-google-flow-v1/post-google-flow-videos#async--callbacks)). Result links stay valid for about 6 hours, and [GET assets](/docs/api-google-flow-v1/get-google-flow-assets-mediagenerationid) gives a fresh one later. [How useapi.net works](/docs/how-it-works) has tips for keeping your accounts healthy. ## Questions ### Does Google Flow have an API? Through useapi.net, yes. Google offers [Flow](https://flow.google.com) only as a website, with no public API (as of November 2026). The useapi.net Google Flow API runs every Flow model over REST on your Google AI subscription, and also chats with [Google Flow Agent](/docs/api-google-flow-v1/agent), which Google offers only inside the Flow website. ### How do I get a Google Flow API key? Through useapi.net, you call Flow with our [API token](/docs/start-here/setup-useapi), since Google doesn't issue a Flow API key. You connect your Google account once through the [automated browser setup](/docs/start-here/setup-google-flow): sign in with Google, with no cookies to copy, and it's done in about a minute. ### How much does the Google Flow API cost? Through useapi.net on Google AI Ultra $199.99, Google Flow video costs a fraction of Google's own APIs: an 8-second 720p Omni 1.2 Flash video is $0.19, against $0.56 on [Google's own API](https://cloud.google.com/blog/products/ai-machine-learning/gemini-omni-1-2-flash-generally-available), and an 8-second Veo 3.1 Fast video is $0.08, against $0.80 on Google's [Agent Platform](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing) (as of November 2026). The [price table](#pricing) shows every model on every subscription. ### Is there a free Google Flow API? Through useapi.net, yes: a free Google account makes Nano Banana images, Veo 3.1 Fast and Lite videos and Omni 1.2 Flash videos of up to 10 seconds on its daily Flow credits, while Google's own APIs charge for every image and every second of video (as of November 2026). Upscaling an image to 2K is free on every account too. The [price table](#pricing) shows what each paid subscription adds. ### Is there a Google Flow SDK? Through useapi.net, you need no SDK: the API is plain REST that works from any language, and Google publishes no Flow SDK, since Flow has no public API. Runnable Node.js and Python examples, two n8n templates and an [agent skill](https://github.com/useapi/google-flow-api/tree/main/skills/omni-flash-video) for Claude Code and Codex are on GitHub at [useapi/google-flow-api](https://github.com/useapi/google-flow-api), and the [Veo 3.1 tutorial](/docs/articles/google-flow-bash) makes a first video from the command line. [Setup Google Flow](/docs/start-here/setup-google-flow) [Google Account Setup](https://github.com/useapi/google-account-setup) Scripts for a clean, single-use Google sign-in (Windows, macOS, Linux) [LLM-friendly API spec](https://useapi.net/assets/aibot/api-google-flow-v1.txt) Feed this to your LLM to build integrations [Claude Code skill](/llm-tools) A drop-in useapi.net skill for Claude Code, and a rule for Cursor [Postman collection](https://www.postman.com/useapinet/useapi-net/collection/29112081-db5b420d-b5a6-4710-91b2-82980b4cddd5) (November 6, 2026) [MCP Server](/docs/api-google-flow-v1/mcp) Chat with Google Flow Agent from Claude Code, Cursor, VS Code and other MCP clients [Agent Overview](/docs/api-google-flow-v1/agent) Chat with Google Flow Agent through the API, its replies streamed live [Agent Live Demo](/docs/api-google-flow-v1/agent-demo) Try it in your browser. [Source code on GitHub](https://github.com/useapi/google-flow-api/tree/main/demo) [Agent skill: omni-flash-video](https://github.com/useapi/google-flow-api/tree/main/skills/omni-flash-video) Claude Code and Codex make Omni Flash (1.2 and 1.1) or Veo 3.1 videos for you [GitHub examples](https://github.com/useapi/google-flow-api) Node.js and Python: Veo 3.1 and Omni Flash (1.2 and 1.1) video, extend, Nano Banana images, n8n templates, an agent skill for Claude Code and Codex [n8n template]({% include n8n-url.html t="flow-veo-nano" %}) Batch-generate Veo 3.1 videos and Nano Banana Pro images from a Google Sheet, ready to import [n8n template: UGC Ad Factory]({% include n8n-url.html t="flow-ugc" %}) Make UGC video ads with Omni 1.1 Flash from a form, pick or re-roll every step Articles: * [Can You Use Your Google AI Subscription Through an API? What Plus, Pro and Ultra Get You](/docs/articles/google-ai-subscription-api) {% include lang-switch.html mode="hub" key="google-ai-subscription" %} * [Gemini Omni 1.2 Flash in Google Flow and Google Vids: 15-second videos, extend, edit and price per video](/docs/articles/gemini-omni-1-2-flash-api) {% include lang-switch.html mode="hub" key="gemini-omni-1-2-flash" %} * [Chat with Google Flow Agent via curl: stream replies, approve spending, collect the media](/docs/articles/google-flow-agent-chat) {% include lang-switch.html mode="hub" key="google-flow-agent-chat" %} * [Google Flow Errors Explained: Upscaling Failed, PUBLIC_ERROR_UNUSUAL_ACTIVITY and Unsafe Generation](/docs/articles/google-flow-errors) * [Make a UGC product video: sheets, a character, one still, three Omni 1.1 Flash clips](/docs/articles/google-flow-ugc-product-video) {% include lang-switch.html mode="hub" key="ugc-product-video" %} * [Make UGC video ads in n8n: a no-code form with a pick or re-roll page at every step](/docs/articles/google-flow-n8n-ugc-ads) * [Sora 2 API Alternatives Compared, With Code: Seedance 2.5, Omni Flash, MiniMax H3, Kling v3](/docs/articles/sora-2-api-alternatives) * [Nano Banana 2 Lite vs 2.1 vs Pro: Image Models Compared](/docs/articles/google-flow-nano-banana-compare) {% include lang-switch.html mode="hub" key="nano-banana-compare" %} * [Generate images (Nano Banana / Pro) via curl](/docs/articles/google-flow-images-bash) {% include lang-switch.html mode="hub" key="google-flow-images" %} * [Veo 3.1 API Pricing: Official Google Veo API vs Google Flow API](/docs/articles/veo-3-1-api-pricing) * [How to Use the Veo 3.1 API: Generate Video with curl via the Google Flow API](/docs/articles/google-flow-bash) {% include lang-switch.html mode="hub" key="google-flow" %} * [Generate Omni Flash (1.2 and 1.1) audio-native video and extend it via curl](/docs/articles/omni-flash-bash) {% include lang-switch.html mode="hub" key="omni-flash" %} Examples: * [Nano Banana 2.1 thinking level: low, medium and high compared](/blog/261107) * [Omni 1.2 Flash: 15-second videos and extend with voices](/blog/261106) * [Extend Omni 1.1 Flash videos: UGC talking head](/blog/260902) * [Omni 1.1 Flash: 360p tier, first + last frames, new upscaler](/blog/260826) * [`@`-mentions](/blog/260609) * [Reusable Voices & Characters](/blog/260605) * [Omni 1.1 Flash + V2V edit](/blog/260520) * [Veo 3.1 Lite & Voice Narration](/blog/260403) * [17 AI Image Models: The Showdown](/blog/260309i) * [Video Extend and Concatenate](/blog/260129) * [Video Upscale and GIF](/blog/260120) * [Nano Banana Pro with 5 references](/blog/251201) * [Nano Banana Pro](/blog/251120) * [Initial release](/blog/251117) Videos on YouTube: * [UGC video ads in n8n with the Google Flow API](https://www.youtube.com/shorts/1vPpoNdWHJw) * [A UGC product video with the Google Flow API](https://www.youtube.com/shorts/wbUROtDIfGA) * [Sober When Dead: reusable voices and characters](https://www.youtube.com/watch?v=D1RM-tGZ6lw) * [Veo 3.1 extend and concatenate](https://www.youtube.com/shorts/PWWH2aOJG3A) Developer Community: * <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> * <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> === URL: https://useapi.net/docs/api-google-flow-v1/mcp === Document URL: https://useapi.net/docs/api-google-flow-v1/mcp --- layout: default title: MCP Server nav_icon: mcp seo_title: "Google Flow MCP Server: Chat with Google Flow Agent in Claude Code" description: "Connect the Claude app, ChatGPT, Claude Code or any MCP client to the hosted useapi.net Google Flow MCP server: 12 tools to chat with Google Flow Agent." parent: Google Flow API nav_order: 50 permalink: /docs/api-google-flow-v1/mcp --- ## Google Flow MCP Server October 16, 2026 (November 10, 2026) --- The useapi.net Google Flow MCP server lets an AI assistant such as the Claude app, ChatGPT, Claude Code, Cursor or VS Code Copilot work with Google Flow Agent, the creative assistant built into [Google Flow](https://flow.google.com), on your own Google accounts. It is a hosted [Model Context Protocol](https://modelcontextprotocol.io) server with 12 tools: chat with the agent, attach images, a video, voices and characters, answer its requests to spend credits, read, list, rename and delete chats, set the project's approval mode, instructions and default models, list the account's characters, voices, images and videos, and upload your own images. Each tool calls the [Agent API](/docs/api-google-flow-v1/agent) or another Google Flow API endpoint, so the same rules and limits apply. Nothing needs to be installed or hosted. **Is there a Google Flow MCP server?** Yes. useapi.net, a third-party service not affiliated with Google, hosts one at `https://api.useapi.net/v1/google-flow/mcp` with 12 tools to chat with Google Flow Agent, on your own Google account, nothing to install. Prefer REST? Guide: [Google Flow Agent API](/docs/api-google-flow-v1/agent) · Demo: [Agent Live Demo](/docs/api-google-flow-v1/agent-demo) · Code: [github.com/useapi/google-flow-api/demo](https://github.com/useapi/google-flow-api/tree/main/demo) See all useapi.net MCP servers on [Model Matrix & MCP](/model-matrix#mcp-servers). ## Endpoint and authorization ``` https://api.useapi.net/v1/google-flow/mcp ``` - Transport: Streamable HTTP. - Listed in the [official MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers/net.useapi%2Fgoogle-flow/versions/latest) as `net.useapi/google-flow`, so MCP clients and directories that read the registry can find it by that name. - Authorization: your useapi.net API token in the `Authorization: Bearer …` header, see [Setup useapi.net](/docs/start-here/setup-useapi). The Claude app and ChatGPT sign in with OAuth instead, see [Use it in the Claude app or ChatGPT](#use-it-in-the-claude-app-or-chatgpt). - You need at least one Google account added with [Setup Google Flow](/docs/start-here/setup-google-flow), and a [captcha provider](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers) once your free captcha credits run out. Adding and removing accounts is not available over MCP: use [POST /accounts](/docs/api-google-flow-v1/post-google-flow-accounts) or the setup page. ## Setup Replace `YOUR_API_TOKEN` with your useapi.net API token. ### Claude Code ```bash claude mcp add --transport http useapi-google-flow https://api.useapi.net/v1/google-flow/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` ### Cursor In `~/.cursor/mcp.json`: ```json { "mcpServers": { "useapi-google-flow": { "url": "https://api.useapi.net/v1/google-flow/mcp", "headers": { "Authorization": "Bearer YOUR_API_TOKEN" } } } } ``` ### VS Code In `.vscode/mcp.json`: ```json { "servers": { "useapi-google-flow": { "type": "http", "url": "https://api.useapi.net/v1/google-flow/mcp", "headers": { "Authorization": "Bearer YOUR_API_TOKEN" } } } } ``` ### Windsurf and other clients Any client that supports remote MCP servers over HTTP with custom headers works. The usual JSON shape: ```json { "mcpServers": { "useapi-google-flow": { "serverUrl": "https://api.useapi.net/v1/google-flow/mcp", "headers": { "Authorization": "Bearer YOUR_API_TOKEN" } } } } ``` Some clients name the address field `url` instead of `serverUrl`. ### Test it with curl ```bash curl -s https://api.useapi.net/v1/google-flow/mcp \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}' curl -s https://api.useapi.net/v1/google-flow/mcp \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' ``` The first call answers with the server's name `useapi-google-flow` and its instructions for the assistant, the second with the 12 tools. ## Use it in the Claude app or ChatGPT The Claude app ([claude.ai](https://claude.ai) and Claude Desktop) and [ChatGPT](https://chatgpt.com) can add this server as a custom connector. They sign in with OAuth: you give the app the URL, it opens a useapi.net page, and you paste your useapi.net API token there once. Both work on their Free plans. The API-token setups above for Claude Code, Cursor, VS Code and other clients keep working as before. ``` ``` ### Claude app 1. Open Settings → Connectors and click Add custom connector. 2. Enter a name, for example `useapi `, and the URL above, then click Add. 3. Click Connect. Claude opens the useapi.net sign-in page. 4. Paste your useapi.net API token and click Allow. Claude asks before each tool call unless you choose Always allow. The Free plan allows one custom connector. ### ChatGPT 1. Open Plugins, click Add and choose Add custom MCP server. 2. Enter a name and the URL above, and set Authentication to OAuth. 3. Tick ChatGPT's "I understand and want to continue" box, then click Create as a plugin. 4. Click Connect. ChatGPT opens the useapi.net sign-in page. 5. Paste your useapi.net API token and click Allow. ChatGPT asks you to confirm each tool call that creates or changes something. The Free plan works without developer mode (as of October 25, 2026). ### How the sign-in works - Your API token is in your welcome email, see [Setup useapi.net](/docs/start-here/setup-useapi). The useapi.net page links there too. - Each connection is for one MCP server. Connect each server you want to use on its own. - The app gets an access token that lasts 1 hour and renews it on its own. A connection you don't use for 90 days lapses, and you connect again. - [Resetting your API token](/docs/account-management/post-account-token-reset) disconnects every app connected with it. - - Results come back as public links, so they open right in the app. ## Tools Chats are named by their `chatId`, which carries its account and project, so a follow-up always runs where the chat lives. The tools that work on an account (`flow_agent_list_chats`, `flow_agent_get_settings`, `flow_agent_update_settings`, `flow_list_characters`, `flow_list_voices`, `flow_list_assets`, `flow_upload_image`) take an optional `email`, which can be left out when the API token has one Google Flow account. ### Chat | Tool | What it does | Main parameters | |---|---|---| | `flow_agent_chat` | Sends a message to the agent and returns its answer: the chat's `chatId`, the turn's `status` (`completed`, `waiting_approval`, `failed` or `running`), the agent's text, its tool calls, the media it made with `referenceId` and link, and a pending request to spend credits. Without `chatId` it starts a new chat, on `email`, on the references' account, or on an account the API picks. Name references in the message as `@referenceImage_1`, `@referenceVideo_1`, `@referenceAudio_1` or `@character_1`. Find them with the tools under [Your characters, voices and media](#your-characters-voices-and-media). They must belong to the chat's account. | `message`, `chatId`, `email`, `projectId`, `referenceImage_1`..`7`, `referenceVideo_1`, `referenceAudio_1`..`5`, `character_1`..`7` | | `flow_agent_get_chat` | Reads a chat: its status, pending request, last error and latest turns with media status and links. With `wait: true` it follows the running turn and returns the rest, after the `lastEventId` of an earlier result. | `chatId`, `wait`, `after`, `media`, `limit` | | `flow_agent_answer_approval` | Answers the agent's request to spend credits with `approve`, `always` (approve and switch the project to `auto`) or `reject`, within about 4 minutes of the request, then follows the same turn like `flow_agent_chat`. | `chatId`, `decision`, `wait` | | `flow_agent_list_chats` | Lists the account's agent chats with title, dates and whether a turn is running, including chats started in the Flow web app in the same project. | `email`, `projectId` | | `flow_agent_rename_chat` | Renames a chat, also in the Flow web app. | `chatId`, `title` | | `flow_agent_delete_chat` | Deletes a chat's history. The images and videos it made stay in the project. | `chatId` | The parameters match [POST /agent/chats](/docs/api-google-flow-v1/post-google-flow-agent-chats), [POST /agent/chats/`chatId`/messages](/docs/api-google-flow-v1/post-google-flow-agent-chats-chatId-messages), [POST /agent/chats/`chatId`/approval](/docs/api-google-flow-v1/post-google-flow-agent-chats-chatId-approval) and [GET /agent/chats/`chatId`](/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId). ### Settings | Tool | What it does | Main parameters | |---|---|---| | `flow_agent_get_settings` | Reads the project's approval mode (`ask` or `auto`), its instructions and the default image and video model, aspect ratio and count, and lists the image and video models the account's Google plan has with what its cheapest generation costs. | `email`, `projectId` | | `flow_agent_update_settings` | Changes them. `instructions` replaces the whole list of up to 3. A default `model` is any model `flow_agent_get_settings` lists for the account. | `email`, `projectId`, `approval`, `instructions`, `imageDefaults`, `videoDefaults` | The parameters match [PUT /agent/settings](/docs/api-google-flow-v1/put-google-flow-agent-settings). ### Your characters, voices and media | Tool | What it does | Main parameters | |---|---|---| | `flow_list_characters` | Lists the characters saved on the account with their name, voice and `character` id, to pass as `character_N`. | `email` | | `flow_list_voices` | Lists the 30 built-in voices by name and the account's own voices with their ids, to pass as `referenceAudio_N`. | `email`, `source` | | `flow_list_assets` | Lists a project's images and videos, newest first, with a `referenceId` for `referenceImage_N` or `referenceVideo_1` and whether each is an upload. Without `projectId` it lists the account's main project. Every project includes the account's uploads. Pass the agent project's id from `flow_agent_get_settings` to see what the agent made. Returns 50 by default, up to 200 per call. | `email`, `projectId`, `type`, `uploadsOnly`, `limit` | | `flow_upload_image` | Uploads your own JPEG, PNG or WebP image from a public https URL, or sent as `contentBase64`, up to 20 MB, and returns its `referenceId` for `referenceImage_N`. Upload it to the account you chat on. Uploads stay on the Google account until deleted. | `url` or `contentBase64`, `mimeType`, `email` | The parameters match [GET /characters](/docs/api-google-flow-v1/get-google-flow-characters), [GET /voices](/docs/api-google-flow-v1/get-google-flow-voices), [GET /assets/media/`email`](/docs/api-google-flow-v1/get-google-flow-assets-media-email) and [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email). The full input schema of every tool comes from `tools/list`. ## Long-running work MCP clients usually give up on a tool call after about a minute, so a tool waits up to about 50 seconds: - Sending waits for Google to accept the turn, usually 3 to 40 seconds. If Google has not confirmed it within 55 seconds, the tool says so and tells the assistant to check the chat before sending again. - The tool then follows the agent for the rest of the time. A short answer, an image or a request to spend credits usually comes back in that time. - A turn that is still working returns `status: "running"` and a `lastEventId`. `flow_agent_get_chat` with `wait: true` and `after` set to that `lastEventId` returns the rest. Ask the assistant to keep checking until it is done. - Videos finish a minute or two after the turn. `flow_agent_get_chat` without `wait` shows their status and link. Clients that ask for progress notifications get one about every 10 seconds while a tool waits. Media links are Google's and expire about 6 hours after they are issued. Read the chat again for fresh ones. A media item's `referenceId` can go into a later message as `referenceImage_N` or `referenceVideo_1`. ## Approvals and credits Chatting with the agent costs no Flow credits. The images and videos it makes cost the usual Flow price. In the `ask` approval mode the agent stops before it spends credits and says what it costs, and the tool result tells the assistant to ask you before it answers with `flow_agent_answer_approval`. Answer within about 4 minutes: since Google changed Flow Agent on November 10, 2026, a request expires after that, and the message has to be sent again. `always`, or `approval: "auto"` with `flow_agent_update_settings`, lets the agent spend without asking in every chat of the project. ## Example prompts - "Upload https://example.com/photo.jpg to my Flow account and ask the agent to describe it." - "Ask the Flow agent for three ideas for a 30-second coffee ad, then make the first one as a storyboard of four images." - "Make an 8-second Veo 3.1 Lite video of a paper boat floating on a calm pond. Show me the cost before you approve it." - "Send my character and this product image to the Flow agent and ask for a short video of her holding it, in the Aoede voice." - "Is the video from my last Flow chat ready? Give me the link." - "List my Flow agent chats and delete the ones about the lighthouse." - "Set the Flow agent to use Nano Banana Pro at 9:16 by default, and add an instruction to keep every answer short." ## Limits and notes - The tools use your Google accounts and the same rules as the REST API: one turn at a time per chat, at most 3 running turns per account, and Google's daily limit on agent messages. See [Limits](/docs/api-google-flow-v1/agent#limits). - Each turn uses one captcha, the same as a generation request. - References in a chat must belong to the chat's account. Upload images with `flow_upload_image` to that account. - `flow_list_assets` returns up to 200 items per call, and a large project can take 20 seconds or more to read. A new upload may take a moment to appear in the list. - A client may send up to 20 JSON-RPC requests in one batch. - If the client sends an `MCP-Protocol-Version` header, it must be one of the supported versions: `2025-06-18`, `2025-03-26` or `2024-11-05`. - Tool calls show in your [usage stats](/docs/account-management/get-account-stats) (`bot=google-flow`) through the REST call each tool makes, the same rows a direct API request writes. === URL: https://useapi.net/docs/api-google-flow-v1/patch-google-flow-agent-chats-chatId === Document URL: https://useapi.net/docs/api-google-flow-v1/patch-google-flow-agent-chats-chatId --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-put">PATCH</code> agent/chats/`chatId` description: "Rename a Google Flow Agent chat via PATCH agent/chats/chatId in the useapi.net Google Flow API: a new title of up to 200 characters, shown in the Flow web app too." parent: Google Flow API nav_order: 1470 --- ## Rename an agent chat October 16, 2026 (November 16, 2026) --- Give a chat a new title. Google titles each chat on its own, and the new title replaces it in [GET /agent/chats](/docs/api-google-flow-v1/get-google-flow-agent-chats) and in the Flow web app. A chat cannot be renamed while a turn runs in it. > **https://api.useapi.net/v1/google-flow/agent/chats/`chatId`** - `chatId` is **required**, URL-encoded in the path (it contains `:` and `@`), from [POST /agent/chats](/docs/api-google-flow-v1/post-google-flow-agent-chats) or [GET /agent/chats](/docs/api-google-flow-v1/get-google-flow-agent-chats). ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "title": "Lighthouse campaign" } ``` - `title` is **required**, the new title. Maximum length: `200` characters. ##### Responses **200** **200 OK** ```json { "chatId": "c-u12345-email:john@gmail.com-project:f166200a-ea22-461a-bc68-47ff6d3ee500-chat:2586b4d7-6652-40f8-8ba4-b0e812e7de10-bot:google-flow", "title": "Lighthouse campaign" } ``` **400** **400 Bad Request** `title` is missing or too long, or the path value is not a `chatId`. ```json { "error": "Parameter title is required", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The `chatId` belongs to another useapi.net user. ```json { "error": "This chat belongs to another user", "code": 403 } ``` **404** **404 Not Found** The chat was deleted, or its account is not added. ```json { "error": "Chat not found: it was deleted or never existed", "code": 404 } ``` **409** **409 Conflict** A turn is running in this chat. Rename it after the turn ends. ```json { "error": "A turn is running in this chat. Wait for it to finish", "code": 409 } ``` **503** **503 Service Unavailable** Google Flow could not be reached, and nothing happened. Retry shortly. ```json { "error": "Google Flow is not reachable right now and could not rename the chat. Retry", "code": 503 } ``` **596** **596 Session Error** Google rejected the account's session, and the API is re-verifying the account on its own: retry in about a minute. If Google signed the account out, the account keeps answering `596` and you get a reconnect email: add it again by following [Setup Google Flow](/docs/start-here/setup-google-flow). ```json { "error": "Google Flow account john@gmail.com Google rejected this account session (HTTP 401). We are automatically re-verifying it — please retry in about a minute. If the account was signed out, you will receive a reconnect email.", "code": 596 } ``` ##### Model The chat's id and its new title, as Google stored it. <details markdown="block" class="model-details"> <summary>The renamed chat, field by field</summary> ```typescript { // TypeScript, all fields are optional chatId: string // the chat's id title: string // the new title as Google stored it error?: string // errors only code?: number // errors only } ``` </details> ##### Examples **Curl** ``` bash CHATID="c-u12345-email:john@gmail.com-project:f166200a-...-chat:2586b4d7-...-bot:google-flow" curl -X PATCH "https://api.useapi.net/v1/google-flow/agent/chats/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$CHATID")" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -d '{ "title": "Lighthouse campaign" }' ``` **JavaScript** ``` javascript const token = 'YOUR_API_TOKEN' const chatId = 'chatId from POST /agent/chats' const response = await fetch(`https://api.useapi.net/v1/google-flow/agent/chats/${encodeURIComponent(chatId)}`, { method: 'PATCH', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${token}` }, body: JSON.stringify({ title: 'Lighthouse campaign' }) }) console.log(response.status, await response.json()) ``` **Python** ``` python import requests from urllib.parse import quote token = 'YOUR_API_TOKEN' chatId = 'chatId from POST /agent/chats' r = requests.patch( f'https://api.useapi.net/v1/google-flow/agent/chats/{quote(chatId, safe="")}', headers={'Authorization': f'Bearer {token}'}, json={'title': 'Lighthouse campaign'}, ) print(r.status_code, r.json()) ``` === URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers === Document URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> accounts/captcha-providers description: "Set captcha provider API keys for reCAPTCHA solving via POST accounts/captcha-providers in the useapi.net Google Flow API v1 — needed for image and video generation." parent: Google Flow API nav_order: 410 --- ## Configure Captcha Providers December 23, 2025 (November 16, 2026) --- Configure captcha provider API keys for image and video generation. Google Flow requires reCAPTCHA v3 Enterprise tokens for API calls - these third-party services solve the captcha automatically. **Supported Providers:** | Provider | Cost per 1K | Avg Solve Time | Reports Back | Website | |----------|-------------|----------------|:------------:|---------| | AntiCaptcha | ~$2.00 | ~8-12s | [Yes](https://anti-captcha.com/apidoc/methods/reportCorrectRecaptcha) | [anti-captcha.com](https://anti-captcha.com/) | | CapSolver | ~$3.00 | ~8-12s | [Yes](https://docs.capsolver.com/en/api/) | [capsolver.com](https://www.capsolver.com/) — use promo code `useapi` for 8% discount | | EzCaptcha | ~$2.50 | ~2-5s | No | [ez-captcha.com](https://www.ez-captcha.com/) | | YesCaptcha | varies | ~8-12s | No | [yescaptcha.com](https://yescaptcha.com/) | | CapMonster | ~$1.50 | ~10-30s | [Incorrect only](https://docs.capmonster.cloud/docs/api/bad-tokens/) | [capmonster.cloud](https://capmonster.cloud/) | | SolveCaptcha | ~$0.80 | ~30-60s Slow | [Yes](https://solvecaptcha.com/captcha-solver-api) | [solvecaptcha.com](https://solvecaptcha.com/) | | 2Captcha | ~$2.99 | ~30-60s Slow | [Yes](https://2captcha.com/api-docs/report-correct) | [2captcha.com](https://2captcha.com/) | SolveCaptcha and 2Captcha typically take 30-60 seconds per solve versus ~2-12 seconds for the others. They work well as low-cost fallbacks but can increase request latency as primary providers. EzCaptcha solves in real time, in about 2–5 seconds, so a token Google rejects costs little time before the next provider takes over. Reports Back — providers that support solve-result reporting receive correct/incorrect feedback after each use, which improves token quality over time. Use [GET /accounts/captcha-stats?anonymized=true](/docs/api-google-flow-v1/get-google-flow-accounts-captcha-stats) to compare success rates across providers. Configure multiple providers for redundancy - the API will automatically retry with different providers if one fails or returns a rejected token. ### Captcha Parameters These parameters are available on all endpoints that require captcha: [POST /images](/docs/api-google-flow-v1/post-google-flow-images), [POST /images/upscale](/docs/api-google-flow-v1/post-google-flow-images-upscale), [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos), [POST /videos/upscale](/docs/api-google-flow-v1/post-google-flow-videos-upscale), [POST /videos/extend](/docs/api-google-flow-v1/post-google-flow-videos-extend), [POST /voices](/docs/api-google-flow-v1/post-google-flow-voices). - `captchaToken` — a user-provided reCAPTCHA v3 Enterprise token. When provided, the API uses this token directly instead of solving captcha through a provider. Single attempt, no retry. Must be a valid token string (minimum 20 characters). - `captchaRetry` — how many tries to make (1-10, default 5). Which provider makes each try: [Provider order](#provider-order). - `captchaOrder` — which providers to use and how many tries, as a comma-separated list. `"AntiCaptcha,AntiCaptcha,CapSolver"` means: use AntiCaptcha and CapSolver, up to 3 tries. Only the providers in the list are used. The order you write them in doesn't matter — the API decides it (see [Provider order](#provider-order)). To use one provider only, list only that one, e.g. `"CapSolver,CapSolver,CapSolver"`. Up to 10 entries, and each provider needs a key. **Note:** `captchaToken`, `captchaRetry`, and `captchaOrder` are mutually exclusive - only one can be specified per request. #### Provider order Every image, video or voice you generate needs a captcha solved first. One of your captcha providers solves it, and Google accepts or rejects it. If Google rejects it, we try again with a fresh captcha. 1. We use all the providers you added keys for, or only the ones in `captchaOrder` if you send it. A provider whose key has no money left or is invalid is skipped for 15 minutes. 2. We make 5 tries by default. `captchaRetry` sets a different number, and with `captchaOrder` the number of entries is used. 3. The tries go to the provider Google is accepting best right now, except the third, which goes to your second-best provider as a backup: best, best, second, best, best. With more than 5 tries the same pattern repeats. 4. If Google rejects the captcha, the next try follows that pattern. If a provider can't solve the captcha at all, it is left out and your other providers take its tries. Any other error from Google ends the request. If you have only one provider, every try uses that provider. We recommend adding at least two providers, for example AntiCaptcha and CapSolver, and ideally EzCaptcha too. Then every request starts with whichever provider is working best at the moment, fewer captchas get rejected, and you pay for fewer of them. ##### How we decide which provider is best For each provider we look at its recent first tries (at least 100 of them, from the last 2 hours at most) and count how many Google accepted. 84 accepted out of 100 means a score of 84%. Tries from all customers count, so the score shows how the provider is doing right now. A captcha the provider failed to solve counts as rejected. - A provider needs at least 100 recent tries before it can move up past another provider. A provider that has hardly been tried yet goes behind the others. - The order only changes when one provider is clearly better than another, not on small ups and downs. A provider takes first place only after it has been clearly better than the current first for 5 minutes in a row. - About 1 request in 20 starts with one of your other providers, or up to 3 in 10 while that provider has too few recent tries, so we notice when it gets better. Only the first try of that request is affected. - A provider that is doing very badly is almost never tried first. When a provider gets worse, your requests move to a better one, usually within 10 minutes. You don't need to change anything. Before we have any data, the order is CapSolver, AntiCaptcha, YesCaptcha, CapMonster, SolveCaptcha, 2Captcha, EzCaptcha. ##### Example You have keys for CapSolver, AntiCaptcha and EzCaptcha. Right now AntiCaptcha scores 84%, EzCaptcha 71% and CapSolver 43%. | Request | Tries, in order | |---|---| | no captcha parameters | AntiCaptcha, AntiCaptcha, EzCaptcha, AntiCaptcha, AntiCaptcha | | `captchaRetry: 2` | AntiCaptcha, AntiCaptcha | | `captchaOrder: "CapSolver,EzCaptcha,CapSolver"` | EzCaptcha, EzCaptcha, CapSolver | | `captchaOrder: "CapSolver,CapSolver"` | CapSolver, CapSolver | The request stops as soon as Google accepts a captcha, so most requests need only one try. You can see the current ranking in [GET /accounts/captcha-stats](/docs/api-google-flow-v1/get-google-flow-accounts-captcha-stats#automatic-provider-order-provider_ranking) (`provider_ranking`). Every response shows which provider was used for each try, in `captcha.attempts`. > **Fewer captcha failures** > - Add several providers. The API ranks them by how often Google accepts each one and gives most tries to the best of them. > - Keep `captchaRetry` at the default 5. With 1 or 2 tries, a request fails as soon as one or two captchas are rejected. > - If one Google account keeps failing, Google has flagged it. Leave out `email` so the API picks another account, or rest that account for a while. > - [GET /accounts/captcha-stats](/docs/api-google-flow-v1/get-google-flow-accounts-captcha-stats) shows which accounts and providers fail. > **https://api.useapi.net/v1/google-flow/accounts/captcha-providers** ### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Request Body ```json { "CapSolver": "<your CapSolver API key>", "AntiCaptcha": "<your AntiCaptcha API key>", "YesCaptcha": "<your YesCaptcha API key>", "SolveCaptcha": "<your SolveCaptcha API key>", "2Captcha": "<your 2Captcha API key>", "EzCaptcha": "<your EzCaptcha API key>" } ``` - `CapSolver` is optional. API key from [capsolver.com](https://www.capsolver.com/). - `AntiCaptcha` is optional. API key from [anti-captcha.com](https://anti-captcha.com/). - `YesCaptcha` is optional. API key from [yescaptcha.com](https://yescaptcha.com/). - `SolveCaptcha` is optional. API key from [solvecaptcha.com](https://solvecaptcha.com/). - `2Captcha` is optional. API key from [2captcha.com](https://2captcha.com/). - `EzCaptcha` is optional. API key from [ez-captcha.com](https://www.ez-captcha.com/). **Notes:** - All fields are optional - only include providers you want to configure - Set a field to empty string `""` to remove that provider - Users receive 300 free captcha credits when adding their first Google Flow account. They are used automatically when you have not added any provider keys, and are solved with our own AntiCaptcha, CapSolver and EzCaptcha keys, best provider first. - Once free credits are exhausted, at least one provider must be configured to use [POST /images](/docs/api-google-flow-v1/post-google-flow-images), [POST /images/upscale](/docs/api-google-flow-v1/post-google-flow-images-upscale), or [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) ### Responses **200** **200 OK** Captcha providers configured successfully. Returns masked keys for all configured providers. **With providers configured:** ```json { "CapSolver": "abc12…", "AntiCaptcha": "def34…", "balances": { "CapSolver": { "status": "ok", "balance": 68.87, "checkedAt": "2026-10-03T22:11:17.173Z" }, "AntiCaptcha": { "status": "empty", "balance": 0, "checkedAt": "2026-10-03T22:11:17.173Z" } } } ``` `balances` shows, for each key you added, whether it works and how much money is left on it. We ask each provider directly and keep its answer for 15 minutes, so a balance can be up to 15 minutes old. When the provider did not answer (`unavailable`), we keep that for 2 minutes only and then ask again. `checkedAt` says when we asked. Saving keys with POST asks again when the kept answer is more than 60 seconds old, so you can see right away whether a key you just added or topped up works. | `status` | Meaning | |---|---| | `ok` | The key works and has money on it. | | `empty` | The key has no money left. We skip it until it is topped up. | | `invalid` | The provider does not accept this key. Check it in your provider account. | | `unavailable` | The provider did not answer. We ask again after 2 minutes. | `balance` is the amount the provider reports, in its own unit: US dollars for most providers, points for YesCaptcha. It is left out when the key is `invalid` or the provider is `unavailable`. `error` is the provider's message, only for `invalid` and `unavailable`. **All providers removed (shows free credits if available):** ```json { "freeCaptchaCredits": 300 } ``` **400** **400 Bad Request** Invalid provider name specified. ```json { "error": "Invalid captcha provider(s): InvalidProvider. Valid providers: CapSolver, AntiCaptcha, YesCaptcha, CapMonster, SolveCaptcha, 2Captcha, EzCaptcha", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` ### Model The captcha providers now configured, each key masked, with the balance of each key. <details markdown="block" class="model-details"> <summary>The captcha providers and their balances, field by field</summary> ```typescript { // TypeScript, all fields are optional CapSolver?: string // the key's first 5 characters and …, omitted if not configured AntiCaptcha?: string // the key's first 5 characters and …, omitted if not configured YesCaptcha?: string // the key's first 5 characters and …, omitted if not configured CapMonster?: string // the key's first 5 characters and …, omitted if not configured SolveCaptcha?: string // the key's first 5 characters and …, omitted if not configured '2Captcha'?: string // the key's first 5 characters and …, omitted if not configured EzCaptcha?: string // the key's first 5 characters and …, omitted if not configured freeCaptchaCredits?: number // Remaining free credits (only shown when no providers configured) balances?: Record<string, { // Per configured key, see below. Omitted when no keys are configured status: 'ok' | 'empty' | 'invalid' | 'unavailable' // ok: the key has funds; empty: balance under $0.01, skipped for generations; invalid: the provider refuses the key; unavailable: the provider could not be asked balance?: number // As the provider reports it (US dollars for most, points for YesCaptcha) error?: string // Provider's message, for invalid and unavailable only checkedAt: string // ISO 8601 timestamp, when we asked the provider. The answer is kept for 15 minutes, 2 minutes when the provider was unavailable. This call asks again when that answer is more than a minute old }> } ``` **Note:** `freeCaptchaCredits` is only included in the response when: - No captcha providers are configured (all removed), AND - The user has remaining free credits (> 0) </details> ### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -X POST "https://api.useapi.net/v1/google-flow/accounts/captcha-providers" \ -d '{ "AntiCaptcha": "<your AntiCaptcha API key>", "CapSolver": "<your CapSolver API key>" }' ``` **JavaScript** ``` javascript const apiUrl = 'https://api.useapi.net/v1/google-flow/accounts/captcha-providers'; const token = 'YOUR_API_TOKEN'; const response = await fetch(apiUrl, { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ AntiCaptcha: '<your AntiCaptcha API key>', CapSolver: '<your CapSolver API key>' }) }); const result = await response.json(); console.log('Captcha providers configured:', result); ``` **Python** ``` python import requests apiUrl = 'https://api.useapi.net/v1/google-flow/accounts/captcha-providers' token = 'YOUR_API_TOKEN' headers = { 'Content-Type': 'application/json', 'Authorization': f'Bearer {token}' } body = { 'AntiCaptcha': '<your AntiCaptcha API key>', 'CapSolver': '<your CapSolver API key>' } response = requests.post(apiUrl, headers=headers, json=body) print(response.status_code, response.json()) ``` ### Try It <script> async function apiTestCaptchaProvidersPost() { const body = {}; const antiCaptchaClear = document.getElementById('post-captcha-providers-AntiCaptcha-clear')?.checked; const ezCaptchaClear = document.getElementById('post-captcha-providers-EzCaptcha-clear')?.checked; const capSolverClear = document.getElementById('post-captcha-providers-CapSolver-clear')?.checked; const yesCaptchaClear = document.getElementById('post-captcha-providers-YesCaptcha-clear')?.checked; const solveCaptchaClear = document.getElementById('post-captcha-providers-SolveCaptcha-clear')?.checked; const twoCaptchaClear = document.getElementById('post-captcha-providers-2Captcha-clear')?.checked; const antiCaptcha = document.getElementById('post-captcha-providers-AntiCaptcha')?.value; const ezCaptcha = document.getElementById('post-captcha-providers-EzCaptcha')?.value; const capSolver = document.getElementById('post-captcha-providers-CapSolver')?.value; const yesCaptcha = document.getElementById('post-captcha-providers-YesCaptcha')?.value; const solveCaptcha = document.getElementById('post-captcha-providers-SolveCaptcha')?.value; const twoCaptcha = document.getElementById('post-captcha-providers-2Captcha')?.value; if (antiCaptchaClear) body.AntiCaptcha = ''; else if (antiCaptcha !== undefined && antiCaptcha !== '') body.AntiCaptcha = antiCaptcha; if (ezCaptchaClear) body.EzCaptcha = ''; else if (ezCaptcha !== undefined && ezCaptcha !== '') body.EzCaptcha = ezCaptcha; if (capSolverClear) body.CapSolver = ''; else if (capSolver !== undefined && capSolver !== '') body.CapSolver = capSolver; if (yesCaptchaClear) body.YesCaptcha = ''; else if (yesCaptcha !== undefined && yesCaptcha !== '') body.YesCaptcha = yesCaptcha; if (solveCaptchaClear) body.SolveCaptcha = ''; else if (solveCaptcha !== undefined && solveCaptcha !== '') body.SolveCaptcha = solveCaptcha; if (twoCaptchaClear) body['2Captcha'] = ''; else if (twoCaptcha !== undefined && twoCaptcha !== '') body['2Captcha'] = twoCaptcha; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${document.getElementById('post-captcha-providers-api_token').value}`, 'Content-Type': 'application/json' }, body: JSON.stringify(body) }; await apiExecute('https://api.useapi.net/v1/google-flow/accounts/captcha-providers', 'post-captcha-providers', data); } </script> <form id="post-captcha-providers" onsubmit="return false;" class="input-form"> <div class="input-field"> <div class="input-field-row"> <label for="post-captcha-providers-api_token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="post-captcha-providers-api_token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> <label for="post-captcha-providers-AntiCaptcha"><span>AntiCaptcha (optional) <input id="post-captcha-providers-AntiCaptcha-clear" type="checkbox" onchange="if(this.checked) document.getElementById('post-captcha-providers-AntiCaptcha').value=''"> Clear</span> <input id="post-captcha-providers-AntiCaptcha" type="text" class="input-element" oninput="this.size = this.value.length"> </label> <label for="post-captcha-providers-EzCaptcha"><span>EzCaptcha (optional) <input id="post-captcha-providers-EzCaptcha-clear" type="checkbox" onchange="if(this.checked) document.getElementById('post-captcha-providers-EzCaptcha').value=''"> Clear</span> <input id="post-captcha-providers-EzCaptcha" type="text" class="input-element" oninput="this.size = this.value.length"> </label> <label for="post-captcha-providers-CapSolver"><span>CapSolver (optional) <input id="post-captcha-providers-CapSolver-clear" type="checkbox" onchange="if(this.checked) document.getElementById('post-captcha-providers-CapSolver').value=''"> Clear</span> <input id="post-captcha-providers-CapSolver" type="text" class="input-element" oninput="this.size = this.value.length"> </label> <label for="post-captcha-providers-YesCaptcha"><span>YesCaptcha (optional) <input id="post-captcha-providers-YesCaptcha-clear" type="checkbox" onchange="if(this.checked) document.getElementById('post-captcha-providers-YesCaptcha').value=''"> Clear</span> <input id="post-captcha-providers-YesCaptcha" type="text" class="input-element" oninput="this.size = this.value.length"> </label> <label for="post-captcha-providers-SolveCaptcha"><span>SolveCaptcha (optional) <input id="post-captcha-providers-SolveCaptcha-clear" type="checkbox" onchange="if(this.checked) document.getElementById('post-captcha-providers-SolveCaptcha').value=''"> Clear</span> <input id="post-captcha-providers-SolveCaptcha" type="text" class="input-element" oninput="this.size = this.value.length"> </label> <label for="post-captcha-providers-2Captcha"><span>2Captcha (optional) <input id="post-captcha-providers-2Captcha-clear" type="checkbox" onchange="if(this.checked) document.getElementById('post-captcha-providers-2Captcha').value=''"> Clear</span> <input id="post-captcha-providers-2Captcha" type="text" class="input-element" oninput="this.size = this.value.length"> </label> </div> <button id="post-captcha-providers-button" class="btn btn-primary fs-3" type="submit" onclick="apiTestCaptchaProvidersPost()">Go</button> </div> </form> <div id="post-captcha-providers-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-accounts === Document URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-accounts --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> accounts description: "Register a Google Flow account from session cookies via POST accounts in the useapi.net Google Flow API v1 — 3 accounts per subscription, 50 maximum." parent: Google Flow API nav_order: 200 --- ## Configure Google Flow Account November 17, 2025 (November 16, 2026) --- Configure your Google Flow account for API access using cookies from your authenticated Google account. The API signs in to [Google Flow](https://flow.google.com) with them and keeps that sign-in fresh by itself, every 2 to 3 days. Each [useapi.net subscription](/docs/subscription) covers 3 Google Flow accounts, up to a hard limit of 50. > **https://api.useapi.net/v1/google-flow/accounts** ### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Request Body ```json { "cookies": "Name\tValue\tDomain\tPath\tExpires\t..." } ``` - `cookies` is **required**. Cookies copied from Chrome DevTools in table format: copy all the cookies of accounts.google.com, which include `HSID`, `LSID`, `SID`, `SSID`, `APISID` and `SAPISID`. See [Setup Google Flow](/docs/start-here/setup-google-flow) for detailed instructions on how to obtain these cookies, or use the [automated setup](https://useapi.net/assets/setup-browser/google-flow), which signs in to Google in a browser and adds the account for you. ### Responses **201** **201 Created** New account configuration created successfully. ```json { "accountCookies": [ { "name": "HSID", "value": "AYQab…redacted…xY12z", "domain": ".google.com", "path": "/", "expires": "2027-11-26T16:03:52.000Z", "httpOnly": true, "secure": false, "sameSite": "Lax" }, { "name": "LSID", "value": "o.myg…redacted…Kq7Lw", "domain": "accounts.google.com", "path": "/", "expires": "2027-11-26T16:03:52.000Z", "httpOnly": true, "secure": true, "sameSite": "Lax" }, { "name": "SID", "value": "g.a00…redacted…Zp076", "domain": ".google.com", "path": "/", "expires": "2027-11-26T16:03:52.000Z", "httpOnly": false, "secure": false, "sameSite": "Lax" }, { "name": "SSID", "value": "A1b2C…redacted…9dE3f", "domain": ".google.com", "path": "/", "expires": "2027-11-26T16:03:52.000Z", "httpOnly": true, "secure": true, "sameSite": "Lax" }, { "name": "APISID", "value": "Rt5uV…redacted…Lw8Qa", "domain": ".google.com", "path": "/", "expires": "2027-11-26T16:03:52.000Z", "httpOnly": false, "secure": false, "sameSite": "Lax" }, { "name": "SAPISID", "value": "Zx3cV…redacted…pQ1sD", "domain": ".google.com", "path": "/", "expires": "2027-11-26T16:03:52.000Z", "httpOnly": false, "secure": true, "sameSite": "Lax" } ], "flowCookies": [ { "name": "OSID", "value": "g.a00…redacted…Hj076", "domain": "flow.google.com", "path": "/", "expires": "2027-11-26T16:04:09.000Z", "httpOnly": false, "secure": true, "sameSite": "Lax" } ], "created": "2026-10-22T16:04:11.512Z", "updated": "2026-10-22T16:04:11.512Z", "project": { "projectId": "3b1c0e9d-7a6f-4592-8d38-7f9e1b4c6a5d", "projectTitle": "Oct 22 - 16:04" }, "nextRefresh": { "messageId": "msg_2…redacted…Fq9Wd", "scheduledFor": "2026-10-23T16:11:37.000Z" }, "backend": "flow", "email": "jane.doe@gmail.com" } ``` **200** **200 OK** Existing account configuration updated successfully. The fields are the same as in the `201` response: `created` keeps the date of the first add and `updated` is the date of this one. `accountCookies` holds the same six cookies as in the `201` example, shortened here to one. ```json { "accountCookies": [ { "name": "HSID", "value": "AYQab…redacted…xY12z", "domain": ".google.com", "path": "/", "expires": "2027-11-26T16:03:52.000Z", "httpOnly": true, "secure": false, "sameSite": "Lax" } ], "flowCookies": [ { "name": "OSID", "value": "g.a00…redacted…Hj076", "domain": "flow.google.com", "path": "/", "expires": "2027-11-26T16:04:09.000Z", "httpOnly": false, "secure": true, "sameSite": "Lax" } ], "created": "2025-11-10T12:00:00.000Z", "updated": "2026-10-22T16:04:11.512Z", "project": { "projectId": "3b1c0e9d-7a6f-4592-8d38-7f9e1b4c6a5d", "projectTitle": "Nov 11 - 02:56" }, "nextRefresh": { "messageId": "msg_2…redacted…Fq9Wd", "scheduledFor": "2026-10-23T16:11:37.000Z" }, "backend": "flow", "email": "jane.doe@gmail.com" } ``` **400** **400 Bad Request** The cookies are missing one that the Google Flow sign-in needs, or Google would not sign them in to Google Flow. ```json { "error": "Missing required cookies: APISID, SAPISID. Add the account again: guided browser setup, or ALL cookies from accounts.google.com. See https://useapi.net/docs/start-here/setup-google-flow", "code": 400 } ``` ```json { "error": "These cookies are not signed in to Google Flow. Google treats these cookies as signed out: the account was signed out, or the cookies are from an older session. Sign in again and copy fresh cookies right away, or use the automated setup at https://useapi.net/assets/setup-browser/google-flow. Setup guide: https://useapi.net/docs/start-here/setup-google-flow", "code": 400 } ``` When Google will not sign the cookies in, the message names the reason and what to do: the account is signed out, Google wants a password or 2-step check first, the account has a notice to accept, a Google Workspace administrator blocked Google Flow, or the cookies were copied from a browser that ties the session to its device. **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **402** **402 Payment Required** Subscription expired or insufficient credits. ```json { "error": "useapi.net ⁝ Your account has no subscription, please subscribe to our services before submitting requests", "code": 402 } ``` ### Model The account as stored, with its masked cookies, its projects and its next automatic refresh. <details markdown="block" class="model-details"> <summary>The account, field by field</summary> - `email` - The email address of the Google account, used as `email` in every other endpoint - `backend` - `flow` for every account added now: it holds the flow.google.com cookies the API signs in with. `labs` marks an account added before 2026-09-12 without the `APISID` and `SAPISID` cookies, which stopped working on 2026-10-21. Every request for it answers `596`: add it again with the [automated setup](https://useapi.net/assets/setup-browser/google-flow) - `created` - ISO 8601 timestamp when the account was first configured, kept unchanged when you add the same account again - `updated` - ISO 8601 timestamp of the most recent add, so you can tell when the account last got fresh cookies (the automatic refresh does not change it) - `accountCookies` - The Google account cookies kept from your `cookies`, with each value masked to its first and last five characters - `flowCookies` - The flow.google.com sign-in cookie (`OSID`) the API uses for every Google Flow request, masked the same way - `project` - Google Flow project for this account, created on the first add and kept when you add the account again — unless that project was deleted in Google Flow, in which case a new one is created - `nextRefresh` - When the next automatic refresh runs. The API refreshes the account every 2 to 3 days: it signs in to Google Flow again with the account cookies and replaces the `OSID` cookie - `projectEntity` and `projectAgent` - The projects that hold the account's characters and voices, and its agent chats, kept when you add the account again Secret values come back masked: every cookie `value`, `sessionData.access_token` and `nextRefresh.messageId` show their first and last five characters around `…redacted…` (a value of ten characters or fewer shows as `…redacted…` alone). ```typescript { email: string // Google account email backend: 'flow' | 'labs' // flow: the account signs in with its `flow.google.com` cookies. labs: an account added // before 2026-09-12 that stopped working on 2026-10-21, add it again created: string // ISO 8601 timestamp, first add updated: string // ISO 8601 timestamp, this add accountCookies: Array<{ // the Google sign-in cookies kept for the account: HSID, LSID, SID, SSID, APISID and SAPISID name: string // cookie name value: string // Masked domain: string // cookie domain path: string // cookie path expires: string | number // ISO 8601 timestamp, Unix seconds, or -1 for a session cookie httpOnly: boolean // the cookie's HttpOnly flag secure: boolean // the cookie's Secure flag sameSite: 'Lax' | 'Strict' | 'None' // the cookie's SameSite setting }> flowCookies: Array<{ // Same structure, one OSID cookie for flow.google.com name: string // cookie name value: string // Masked domain: string // cookie domain path: string // cookie path expires: string | number // ISO 8601 timestamp, Unix seconds, or -1 for a session cookie httpOnly: boolean // the cookie's HttpOnly flag secure: boolean // the cookie's Secure flag sameSite: 'Lax' | 'Strict' | 'None' // the cookie's SameSite setting }> sessionCookies?: Array<{ // Same structure, kept from the old Google Labs sign-in when an account first added before 2026-10-21 is added again, no longer used name: string // cookie name value: string // Masked domain: string // cookie domain path: string // cookie path expires: string | number // ISO 8601 timestamp, Unix seconds, or -1 for a session cookie httpOnly: boolean // the cookie's HttpOnly flag secure: boolean // the cookie's Secure flag sameSite: 'Lax' | 'Strict' | 'None' // the cookie's SameSite setting }> sessionData?: { // kept from the old Google Labs sign-in when an account first added before 2026-10-21 is added again, no longer used user: { // the Google account of that sign-in name: string // its display name email: string // its email image: string // its profile picture URL } expires: string // ISO 8601 timestamp, when that sign-in expired access_token: string // Masked } project: { // the account's Google Flow project, where generations go; adding the account again keeps it while Google still has it projectId: string // Google Flow project id projectTitle: string // project title, set when the project was created } projectEntity?: { // kept when the account is added again: the project that holds its characters and custom voices projectId: string // Google Flow project id projectTitle: string // project title, set when the project was created } projectAgent?: { // kept when the account is added again: the project where its agent chats run projectId: string // Google Flow project id projectTitle: string // project title, set when the project was created } nextRefresh: { // the next automatic session refresh, normally 2 to 3 days out messageId: string // Masked scheduledFor: string // ISO 8601 timestamp } setupSession?: string // the automated setup session that added the account, only when it was added that way } ``` </details> ### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -X POST "https://api.useapi.net/v1/google-flow/accounts" \ -d '{ "cookies": "HSID\tAYQ...\t.google.com\t/\t2027-11-10...\nSSID\tAbc...\t.google.com\t/\t2027-11-10..." }' ``` **JavaScript** ``` javascript const apiUrl = 'https://api.useapi.net/v1/google-flow/accounts'; const token = 'YOUR_API_TOKEN'; const cookies = `HSID\tAYQ...\t.google.com\t/\t2027-11-10... SSID\tAbc...\t.google.com\t/\t2027-11-10...`; const response = await fetch(apiUrl, { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ cookies: cookies }) }); const result = await response.json(); console.log('Account configured:', result); ``` **Python** ``` python import requests apiUrl = 'https://api.useapi.net/v1/google-flow/accounts' token = 'YOUR_API_TOKEN' cookies = """HSID\tAYQ...\t.google.com\t/\t2027-11-10... SSID\tAbc...\t.google.com\t/\t2027-11-10...""" headers = { 'Content-Type': 'application/json', 'Authorization': f'Bearer {token}' } body = { 'cookies': cookies } response = requests.post(apiUrl, headers=headers, json=body) print(response.status_code, response.json()) ``` ### Try It See [Setup Google Flow](/docs/start-here/setup-google-flow) page. <script> async function apiTestAccountGoogleFlow() { data = { method: 'POST', headers: { 'Authorization': `Bearer ${document.getElementById('post-accounts-GoogleFlow-api_token').value}`, 'Content-Type': 'application/json' } }; let cookies = document.getElementById(`post-accounts-GoogleFlow-cookies`)?.value; data.body = JSON.stringify({ cookies }); await apiExecute(`https://api.useapi.net/v1/google-flow/accounts`, 'post-accounts-GoogleFlow', data); } </script> <form id="post-accounts-GoogleFlow" onsubmit="return false;" class="input-form"> <div class="input-field"> <div class="input-field-row"> <label for="post-accounts-GoogleFlow-api_token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="post-accounts-GoogleFlow-api_token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> <label for="post-accounts-GoogleFlow-cookies"><span>cookies</span> <textarea id="post-accounts-GoogleFlow-cookies" class="input-element" rows="10" required aria-required="true" style="resize: both;"></textarea> </label> </div> <button id="post-accounts-GoogleFlow-button" class="btn btn-primary fs-3" type="submit" onclick="apiTestAccountGoogleFlow()">Go</button> </div> </form> <div id="post-accounts-GoogleFlow-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-agent-chats-chatId-approval === Document URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-agent-chats-chatId-approval --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> agent/chats/`chatId`/approval description: "Approve or reject Google Flow Agent's request to spend credits via POST agent/chats/chatId/approval in the useapi.net Google Flow API: approve, always or reject." parent: Google Flow API nav_order: 1430 --- ## Answer an approval October 16, 2026 (November 16, 2026) --- In the `ask` approval mode, the agent stops before it spends credits and asks for permission, showing what it wants to make and what it costs. The chat's `status` is then `waiting_approval`, the stream sends an `approval` event, and [GET /agent/chats/`chatId`](/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId) shows `pendingApproval`: ```json { "turn": 1, "cost": 10, "images": 0, "videos": 1 } ``` `cost` is in Flow credits. Answer with this request. The turn that asked goes on: the agent generates (or not) and replies in the same turn, and you follow it on the stream as before. Answer within about 4 minutes of the request. Since Google changed Flow Agent on November 10, 2026, it accepts an answer only while the turn that asked is still open, and it closes an unanswered request about 5 minutes after asking (the agent then says the request timed out). After that Google closes the request: the agent replies that it timed out, the turn ends, an answer gets `409`, and you send the message again to get a new request. If you don't want to answer requests at all, set the project to the `auto` approval mode with [PUT /agent/settings](/docs/api-google-flow-v1/put-google-flow-agent-settings) `approval: "auto"`, and the agent spends without asking. - `approve` lets the agent go ahead this time. - `always` lets it go ahead, and switches the project to the `auto` approval mode, so the agent no longer asks in any chat of the project. Switch back with [PUT /agent/settings](/docs/api-google-flow-v1/put-google-flow-agent-settings) `approval: "ask"`. - `reject` declines. The agent replies without generating. While a request waits, a new message with [POST /agent/chats/`chatId`/messages](/docs/api-google-flow-v1/post-google-flow-agent-chats-chatId-messages) gets `409`: answer the request first, with `reject` to decline it. A waiting turn counts toward the 3 agent turns an account can run at once. The request answers `202` as soon as Google has accepted the turn. That usually takes a few seconds to about 40 seconds and can take up to about 100 seconds, so set your HTTP client's timeout to about 150 seconds. The turn then keeps running on Google's side whether or not you are connected. Follow it live with [GET /agent/chats/`chatId`/stream](/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId-stream), read it with [GET /agent/chats/`chatId`](/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId), or get it posted to your `replyUrl` when it ends. A `504` means Google has not confirmed the turn yet, and it may still start. Read the chat with [GET /agent/chats/`chatId`](/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId) before you send it again. Each turn uses one captcha, solved by the API with your [captcha providers](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers) or the free captcha credits of your first account. > **https://api.useapi.net/v1/google-flow/agent/chats/`chatId`/approval** - `chatId` is **required**, URL-encoded in the path, from [POST /agent/chats](/docs/api-google-flow-v1/post-google-flow-agent-chats) or [GET /agent/chats](/docs/api-google-flow-v1/get-google-flow-agent-chats). ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "decision": "approve" } ``` - `decision` is **required**. Supported values: `approve`, `always`, `reject`. - `replyUrl`, `replyRef`, `captchaToken`, `captchaRetry` and `captchaOrder` are accepted and not used. The turn goes on, so its callback goes to the `replyUrl` of the message that started it, and the answer needs no captcha. ##### Responses **202** **202 Accepted** Google took the answer, and the agent goes on with the turn that asked. ```json { "chatId": "c-u12345-email:john@gmail.com-project:f166200a-ea22-461a-bc68-47ff6d3ee500-chat:2a0f1973-d554-4fbc-aa6b-0c372edf182e-bot:google-flow", "email": "john@gmail.com", "turn": 1, "status": "running" } ``` **400** **400 Bad Request** `decision` is missing or not one of the supported values, or the path value is not a `chatId`. ```json { "error": "Parameter decision is required", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The `chatId` belongs to another useapi.net user. ```json { "error": "This chat belongs to another user", "code": 403 } ``` **404** **404 Not Found** The chat was deleted, or its account is not added. ```json { "error": "Chat not found: it was deleted or never existed", "code": 404 } ``` **409** **409 Conflict** Nothing in this chat is waiting for approval, a turn is still running, or the request is more than about 4 minutes old and Google no longer takes an answer. Send the message again for a new request, or switch the project to `approval: "auto"`. ```json { "error": "Nothing in this chat is waiting for approval", "code": 409 } ``` ```json { "error": "This approval can no longer be given: since Google changed the Flow agent on 2026-11-10 it accepts an answer only while the turn that asked for it is still open, and closes the request about 4 minutes after asking. Send the message again for a new ask, or set approval to auto (PUT /agent/settings with \"approval\": \"auto\") so turns never wait", "code": 409 } ``` **429** **429 Too Many Requests** `429` has two causes. When the API picked the account itself (no `email`), retry or pass another account's `email`. The account already runs 3 agent turns, the most the API runs at once per account. Wait for one to finish, or use another account. The answer carries a `Retry-After` header (seconds) and a `retryAfter` time in the body. ```json { "error": "Account john@gmail.com already runs 3 agent turns (our limit per account). Wait for one to finish or use another account", "code": 429, "retryAfter": "2026-10-16T22:26:47.819Z" } ``` The account reached Google's daily limit on agent messages. Google does not publish the limit. The message Google refused answers with `reason` `AGENT_QUOTA`, and after that the API answers at once until midnight UTC, with `Retry-After` and `retryAfter` set to that time. Use another account until then. ```json { "error": "Google's daily Flow agent limit is reached for john@gmail.com. Try again after 2026-10-17T00:00:00.000Z or use another account", "code": 429, "retryAfter": "2026-10-17T00:00:00.000Z" } ``` **502** **502 Bad Gateway** Google did not take the answer. Read the chat with [GET /agent/chats/`chatId`](/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId): if it still waits for approval, answer again, otherwise send the message again. **503** **503 Service Unavailable** Google Flow could not be reached to read the chat. Nothing was sent. Retry shortly. ```json { "error": "Google Flow is not reachable right now and could not read the chat. Retry", "code": 503 } ``` **596** **596 Session Error** The account's Google session is no longer valid. Delete the account with [DELETE /accounts/`email`](/docs/api-google-flow-v1/delete-google-flow-accounts-email) and add it again by following [Setup Google Flow](/docs/start-here/setup-google-flow). ##### Model The chat, its account and the turn that asked, which goes on as `running`. <details markdown="block" class="model-details"> <summary>The approval answer, field by field</summary> ```typescript { // TypeScript, all fields are optional chatId: string // the chat's id email: string // the account the chat runs on turn: number // the turn that asked, which goes on status: 'running' // the turn goes on, after a reject too error?: string // errors only code?: number // errors only retryAfter?: string // 429 only } ``` </details> ##### Examples **Curl** ``` bash CHATID="c-u12345-email:john@gmail.com-project:f166200a-...-chat:2a0f1973-...-bot:google-flow" curl -X POST "https://api.useapi.net/v1/google-flow/agent/chats/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$CHATID")/approval" \ --max-time 150 \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -d '{ "decision": "approve" }' ``` **JavaScript** ``` javascript const token = 'YOUR_API_TOKEN' const chatId = 'chatId from POST /agent/chats' const response = await fetch(`https://api.useapi.net/v1/google-flow/agent/chats/${encodeURIComponent(chatId)}/approval`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${token}` }, body: JSON.stringify({ decision: 'approve' }), signal: AbortSignal.timeout(150_000) }) console.log(response.status, await response.json()) ``` **Python** ``` python import requests from urllib.parse import quote token = 'YOUR_API_TOKEN' chatId = 'chatId from POST /agent/chats' r = requests.post( f'https://api.useapi.net/v1/google-flow/agent/chats/{quote(chatId, safe="")}/approval', headers={'Authorization': f'Bearer {token}'}, json={'decision': 'approve'}, timeout=150, ) print(r.status_code, r.json()) ``` === URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-agent-chats-chatId-messages === Document URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-agent-chats-chatId-messages --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> agent/chats/`chatId`/messages description: "Send the next message in a Google Flow Agent chat via POST agent/chats/chatId/messages in the useapi.net Google Flow API, with optional references and @-mentions." parent: Google Flow API nav_order: 1420 --- ## Send a message October 16, 2026 (November 16, 2026) --- Send the next message in a chat started with [POST /agent/chats](/docs/api-google-flow-v1/post-google-flow-agent-chats). Google keeps the whole conversation, so the agent has full context even days later. The chat runs on its own account and project, so this request takes no `email` or `projectId`. A chat runs one turn at a time. Sending while a turn runs answers `409`. While the agent waits for an approval, a new message also answers `409`: answer the request with [POST /agent/chats/`chatId`/approval](/docs/api-google-flow-v1/post-google-flow-agent-chats-chatId-approval) first (`reject` declines it). A request expires about 4 minutes after it was made, and a new message works again then. To answer one of the agent's choices, send the text of the choice as the message, as the Flow web app does. The request answers `202` as soon as Google has accepted the turn. That usually takes a few seconds to about 40 seconds and can take up to about 100 seconds, so set your HTTP client's timeout to about 150 seconds. The turn then keeps running on Google's side whether or not you are connected. Follow it live with [GET /agent/chats/`chatId`/stream](/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId-stream), read it with [GET /agent/chats/`chatId`](/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId), or get it posted to your `replyUrl` when it ends. A `504` means Google has not confirmed the turn yet, and it may still start. Read the chat with [GET /agent/chats/`chatId`](/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId) before you send it again. Each turn uses one captcha, solved by the API with your [captcha providers](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers) or the free captcha credits of your first account. > **https://api.useapi.net/v1/google-flow/agent/chats/`chatId`/messages** - `chatId` is **required**, URL-encoded in the path (it contains `:` and `@`), from [POST /agent/chats](/docs/api-google-flow-v1/post-google-flow-agent-chats) or [GET /agent/chats](/docs/api-google-flow-v1/get-google-flow-agent-chats). ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "message": "Now animate @referenceImage_1: the light slowly sweeps across the sea.", "referenceImage_1": "user:12345-email:6a6f...-image:9afe71af-38ba-46de-9da3-8f962fae3953" } ``` - `message` is **required**, what you say to the agent. Maximum length: `20000` characters. - `referenceImage_1` to `referenceImage_7` are optional, images to attach: an id from [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email), an image made by [POST /images](/docs/api-google-flow-v1/post-google-flow-images), or the `referenceId` of an image the agent made. - `referenceVideo_1` is optional, a video to attach: an uploaded video from [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email), a video made by [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos), or the `referenceId` of a video the agent made. - `referenceAudio_1` to `referenceAudio_5` are optional, voices to attach. Each one is a built-in voice name such as `Aoede` or `Achernar` (case-insensitive, the 30 names listed on [POST /voices](/docs/api-google-flow-v1/post-google-flow-voices)), or a custom voice from [POST /voices](/docs/api-google-flow-v1/post-google-flow-voices) or [GET /voices](/docs/api-google-flow-v1/get-google-flow-voices). - `character_1` to `character_7` are optional, characters from [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters) or [GET /characters](/docs/api-google-flow-v1/get-google-flow-characters). All references must belong to the account the chat runs on. They can come from any project of that account. Point at a reference inside the message with an `@`-mention, the same syntax as [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos): `@referenceImage_1`, `@referenceVideo_1`, `@referenceAudio_1`, `@character_1`. Each `@`-mention needs its matching parameter. A mentioned reference appears inside the sentence, the way a chip does in the Flow web app. A reference you pass without mentioning it is attached to the message as well. ```json { "message": "Make @character_1 walk into @referenceImage_1 and say hello in the @referenceAudio_1 voice", "character_1": "user:12345-email:6a6f...-character:860b2818-...-imgs:2", "referenceImage_1": "user:12345-email:6a6f...-image:6bb4a078-...", "referenceAudio_1": "Aoede" } ``` - `replyUrl` is optional, a public `https` URL that receives one `POST` with the turn's result when it ends. When omitted, the `replyUrl` of your [useapi.net account](/docs/account-management/post-account) is used, if you set one. The body is described on [POST /agent/chats](/docs/api-google-flow-v1/post-google-flow-agent-chats#callback). - `replyRef` is optional, your own reference sent back in the callback body. Maximum length: `1024` characters. - `captchaToken`, `captchaRetry`, `captchaOrder` are optional, the same captcha parameters as every Flow generation request. See [Captcha Parameters](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers#captcha-parameters). ##### Responses **202** **202 Accepted** Google accepted the turn and the agent is working on it. ```json { "chatId": "c-u12345-email:john@gmail.com-project:f166200a-ea22-461a-bc68-47ff6d3ee500-chat:2a0f1973-d554-4fbc-aa6b-0c372edf182e-bot:google-flow", "email": "john@gmail.com", "turn": 2, "status": "running" } ``` **400** **400 Bad Request** A parameter is missing or invalid, the path value is not a `chatId`, an `@`-mention has no matching parameter, or a reference belongs to another account. ```json { "error": "Parameter message is required", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The `chatId` belongs to another useapi.net user. ```json { "error": "This chat belongs to another user", "code": 403 } ``` **404** **404 Not Found** The chat was deleted, or its account is not added. ```json { "error": "Chat not found: it was deleted or never existed", "code": 404 } ``` **409** **409 Conflict** A turn is already running in this chat. Wait for its `turn` event on the stream, or for the chat's `status` to leave `running`. ```json { "error": "A turn is already running in this chat. Wait for it to finish", "code": 409 } ``` **429** **429 Too Many Requests** `429` has two causes. When the API picked the account itself (no `email`), retry or pass another account's `email`. The account already runs 3 agent turns, the most the API runs at once per account. Wait for one to finish, or use another account. The answer carries a `Retry-After` header (seconds) and a `retryAfter` time in the body. ```json { "error": "Account john@gmail.com already runs 3 agent turns (our limit per account). Wait for one to finish or use another account", "code": 429, "retryAfter": "2026-10-16T22:26:47.819Z" } ``` The account reached Google's daily limit on agent messages. Google does not publish the limit. The message Google refused answers with `reason` `AGENT_QUOTA`, and after that the API answers at once until midnight UTC, with `Retry-After` and `retryAfter` set to that time. Use another account until then. ```json { "error": "Google's daily Flow agent limit is reached for john@gmail.com. Try again after 2026-10-17T00:00:00.000Z or use another account", "code": 429, "retryAfter": "2026-10-17T00:00:00.000Z" } ``` **502** **502 Bad Gateway** Google answered with an error or without a readable reply (`reason` `GOOGLE_ERROR` or `UNREADABLE_ANSWER`). The turn may have run. Read the chat with [GET /agent/chats/`chatId`](/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId) before you send it again. ```json { "error": "Google answered without a readable reply and may already have run this turn. Check GET /agent/chats/{chatId} before retrying", "code": 502, "reason": "UNREADABLE_ANSWER", "chatId": "c-u12345-email:john@gmail.com-project:f166200a-ea22-461a-bc68-47ff6d3ee500-chat:2a0f1973-d554-4fbc-aa6b-0c372edf182e-bot:google-flow" } ``` **503** **503 Service Unavailable** Nothing ran and nothing was charged. Google refused every captcha for the turn (`reason` `CAPTCHA_FAILED`), so send the message again. When `error` starts with `Captcha service failed:`, the problem is your captcha provider: check its key and balance. When `error` says Google Flow is not reachable, retry shortly. ```json { "error": "Google refused every captcha token for this turn. Nothing ran and nothing was charged. Retry", "code": 503, "reason": "CAPTCHA_FAILED", "chatId": "c-u12345-email:john@gmail.com-project:f166200a-ea22-461a-bc68-47ff6d3ee500-chat:2a0f1973-d554-4fbc-aa6b-0c372edf182e-bot:google-flow" } ``` ```json { "error": "Google Flow is not reachable right now and could not read the chat. Retry", "code": 503 } ``` **504** **504 Gateway Timeout** Google has not confirmed the turn yet, and it may still start. Read the chat with [GET /agent/chats/`chatId`](/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId) before you send it again. ```json { "error": "Google has not confirmed the turn yet; it may still start. Read GET /agent/chats/{chatId} before sending it again", "code": 504, "chatId": "c-u12345-email:john@gmail.com-project:f166200a-ea22-461a-bc68-47ff6d3ee500-chat:2a0f1973-d554-4fbc-aa6b-0c372edf182e-bot:google-flow", "turn": 2 } ``` **596** **596 Session Error** The account's Google session is no longer valid. Delete the account with [DELETE /accounts/`email`](/docs/api-google-flow-v1/delete-google-flow-accounts-email) and add it again by following [Setup Google Flow](/docs/start-here/setup-google-flow). ##### Model The chat, its account and the new turn's number and status, almost always `running`. <details markdown="block" class="model-details"> <summary>The new turn, field by field</summary> ```typescript { // TypeScript, all fields are optional chatId: string // the chat's id email: string // the account the chat runs on turn: number // this turn's number status: 'running' | 'completed' | 'waiting_approval' | 'failed' // almost always running error?: string // errors only code?: number // errors only reason?: string // CAPTCHA_FAILED | UNREADABLE_ANSWER | GOOGLE_ERROR | AGENT_QUOTA, on errors after the request reached Google retryAfter?: string // 429 only } ``` </details> ##### Examples **Curl** ``` bash CHATID="c-u12345-email:john@gmail.com-project:f166200a-...-chat:2a0f1973-...-bot:google-flow" curl -X POST "https://api.useapi.net/v1/google-flow/agent/chats/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$CHATID")/messages" \ --max-time 150 \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -d '{ "message": "Make it night time, with stars." }' ``` **JavaScript** ``` javascript const token = 'YOUR_API_TOKEN' const chatId = 'chatId from POST /agent/chats' const response = await fetch(`https://api.useapi.net/v1/google-flow/agent/chats/${encodeURIComponent(chatId)}/messages`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${token}` }, body: JSON.stringify({ message: 'Make it night time, with stars.' }), signal: AbortSignal.timeout(150_000) }) console.log(response.status, await response.json()) ``` **Python** ``` python import requests from urllib.parse import quote token = 'YOUR_API_TOKEN' chatId = 'chatId from POST /agent/chats' r = requests.post( f'https://api.useapi.net/v1/google-flow/agent/chats/{quote(chatId, safe="")}/messages', headers={'Authorization': f'Bearer {token}'}, json={'message': 'Make it night time, with stars.'}, timeout=150, ) print(r.status_code, r.json()) ``` === URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-agent-chats === Document URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-agent-chats --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> agent/chats description: "Start a chat with Google Flow Agent via POST agent/chats in the useapi.net Google Flow API: a message with images, a video, voices and characters, answered 202 with a chatId." parent: Google Flow API nav_order: 1410 --- ## Start an agent chat October 16, 2026 (November 16, 2026) --- Start a chat with Google Flow Agent and send its first message. The answer is a `chatId` for every later call. See the [Agent Overview](/docs/api-google-flow-v1/agent) for how chats, approvals and credits work. The request answers `202` as soon as Google has accepted the turn. That usually takes a few seconds to about 40 seconds and can take up to about 100 seconds, so set your HTTP client's timeout to about 150 seconds. The turn then keeps running on Google's side whether or not you are connected. Follow it live with [GET /agent/chats/`chatId`/stream](/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId-stream), read it with [GET /agent/chats/`chatId`](/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId), or get it posted to your `replyUrl` when it ends. A `504` means Google has not confirmed the turn yet, and it may still start. Read the chat with [GET /agent/chats/`chatId`](/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId) before you send it again. Each turn uses one captcha, solved by the API with your [captcha providers](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers) or the free captcha credits of your first account. > **https://api.useapi.net/v1/google-flow/agent/chats** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "message": "Make one 8 second video with Veo 3.1 - Lite of a paper boat floating on a calm pond.", "email": "john@gmail.com", "replyUrl": "https://example.com/flow-agent-hook", "replyRef": "my-ref-42" } ``` - `message` is **required**, what you say to the agent. Maximum length: `20000` characters. - `email` is optional, the Google Flow account to chat on. When omitted, the account the references belong to is used, or without references the API picks one of your accounts the same way it does for [POST /images](/docs/api-google-flow-v1/post-google-flow-images). - `projectId` is optional, the Flow project the chat lives in, from [GET /assets/projects/`email`](/docs/api-google-flow-v1/get-google-flow-assets-projects-email). Default: the account's own agent project, created on its first chat and named like `My Agents Work Fri, Oct 16`. - `referenceImage_1` to `referenceImage_7` are optional, images to attach: an id from [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email), an image made by [POST /images](/docs/api-google-flow-v1/post-google-flow-images), or the `referenceId` of an image the agent made. - `referenceVideo_1` is optional, a video to attach: an uploaded video from [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email), a video made by [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos), or the `referenceId` of a video the agent made. - `referenceAudio_1` to `referenceAudio_5` are optional, voices to attach. Each one is a built-in voice name such as `Aoede` or `Achernar` (case-insensitive, the 30 names listed on [POST /voices](/docs/api-google-flow-v1/post-google-flow-voices)), or a custom voice from [POST /voices](/docs/api-google-flow-v1/post-google-flow-voices) or [GET /voices](/docs/api-google-flow-v1/get-google-flow-voices). - `character_1` to `character_7` are optional, characters from [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters) or [GET /characters](/docs/api-google-flow-v1/get-google-flow-characters). All references must belong to the account the chat runs on. They can come from any project of that account. Point at a reference inside the message with an `@`-mention, the same syntax as [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos): `@referenceImage_1`, `@referenceVideo_1`, `@referenceAudio_1`, `@character_1`. Each `@`-mention needs its matching parameter. A mentioned reference appears inside the sentence, the way a chip does in the Flow web app. A reference you pass without mentioning it is attached to the message as well. ```json { "message": "Make @character_1 walk into @referenceImage_1 and say hello in the @referenceAudio_1 voice", "character_1": "user:12345-email:6a6f...-character:860b2818-...-imgs:2", "referenceImage_1": "user:12345-email:6a6f...-image:6bb4a078-...", "referenceAudio_1": "Aoede" } ``` - `replyUrl` is optional, a public `https` URL that receives one `POST` with the turn's result when it ends. When omitted, the `replyUrl` of your [useapi.net account](/docs/account-management/post-account) is used, if you set one. See [Callback](#callback). - `replyRef` is optional, your own reference sent back in the callback body. Maximum length: `1024` characters. - `captchaToken`, `captchaRetry`, `captchaOrder` are optional, the same captcha parameters as every Flow generation request. See [Captcha Parameters](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers#captcha-parameters). ##### Responses **202** **202 Accepted** Google accepted the turn and the agent is working on it. Follow it with [GET /agent/chats/`chatId`/stream](/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId-stream). ```json { "chatId": "c-u12345-email:john@gmail.com-project:f166200a-ea22-461a-bc68-47ff6d3ee500-chat:2a0f1973-d554-4fbc-aa6b-0c372edf182e-bot:google-flow", "email": "john@gmail.com", "turn": 1, "status": "running" } ``` **400** **400 Bad Request** A parameter is missing or invalid, an `@`-mention has no matching parameter, or a reference belongs to another account. ```json { "error": "message mentions @referenceImage_1 but referenceImage_1 was not given", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** Google refused this Google account the chat's first turn (`reason` `GOOGLE_ERROR`), for example because it treats the account as under 18, or refused to create the chat at all. Nothing ran. Retrying will not help: use another account. ```json { "error": "Google refused this request because it treats the Google account as belonging to someone under 18 (PUBLIC_ERROR_USER_MINOR). Google Flow is not available to such accounts, so retrying will not help. Use another Google account, or have this account's age verified with Google first.", "code": 403, "reason": "GOOGLE_ERROR" } ``` When Google refuses to create the chat itself, `error` names Google's reason when Google gives one: ```json { "error": "Google refused to create the chat", "code": 403 } ``` **404** **404 Not Found** The account named by `email` is not added, or `projectId` is not a project of the account. ```json { "error": "Google Flow account john@gmail.com not found", "code": 404 } ``` When `projectId` is not a project of the account: ```json { "error": "Project not found", "code": 404 } ``` **429** **429 Too Many Requests** `429` has two causes. When the API picked the account itself (no `email`), retry or pass another account's `email`. The account already runs 3 agent turns, the most the API runs at once per account. Wait for one to finish, or use another account. The answer carries a `Retry-After` header (seconds) and a `retryAfter` time in the body. ```json { "error": "Account john@gmail.com already runs 3 agent turns (our limit per account). Wait for one to finish or use another account", "code": 429, "retryAfter": "2026-10-16T22:26:47.819Z" } ``` The account reached Google's daily limit on agent messages. Google does not publish the limit. The message Google refused answers with `reason` `AGENT_QUOTA`, and after that the API answers at once until midnight UTC, with `Retry-After` and `retryAfter` set to that time. Use another account until then. ```json { "error": "Google's daily Flow agent limit is reached for john@gmail.com. Try again after 2026-10-17T00:00:00.000Z or use another account", "code": 429, "retryAfter": "2026-10-17T00:00:00.000Z" } ``` **502** **502 Bad Gateway** Google answered with an error or without a readable reply (`reason` `GOOGLE_ERROR` or `UNREADABLE_ANSWER`). The turn may have run. Look at [GET /agent/chats](/docs/api-google-flow-v1/get-google-flow-agent-chats) before you send it again. ```json { "error": "Google answered without a readable reply and may already have run this turn. Check GET /agent/chats/{chatId} before retrying", "code": 502, "reason": "UNREADABLE_ANSWER" } ``` **503** **503 Service Unavailable** Nothing ran and nothing was charged. Google refused every captcha for the turn (`reason` `CAPTCHA_FAILED`), so send the message again. When `error` starts with `Captcha service failed:`, the problem is your captcha provider: check its key and balance. When `error` says Google Flow is not reachable, retry shortly. ```json { "error": "Google refused every captcha token for this turn. Nothing ran and nothing was charged. Retry", "code": 503, "reason": "CAPTCHA_FAILED" } ``` ```json { "error": "Google Flow is not reachable right now and could not create the chat. Retry", "code": 503 } ``` **504** **504 Gateway Timeout** Google has not confirmed the turn yet, and it may still start. Read the chat with [GET /agent/chats/`chatId`](/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId) before you send it again. ```json { "error": "Google has not confirmed the turn yet; it may still start. Read GET /agent/chats/{chatId} before sending it again", "code": 504, "chatId": "c-u12345-email:john@gmail.com-project:f166200a-ea22-461a-bc68-47ff6d3ee500-chat:8bcfbc1d-6c51-409c-8a2e-1870cbbe6e76-bot:google-flow", "turn": 1 } ``` **596** **596 Session Error** The account's Google session is no longer valid. Delete the account with [DELETE /accounts/`email`](/docs/api-google-flow-v1/delete-google-flow-accounts-email) and add it again by following [Setup Google Flow](/docs/start-here/setup-google-flow). ```json { "error": "Google Flow account john@gmail.com Session expired on 2026-10-16T20:00:00.000Z", "code": 596 } ``` ##### Model The new chat's `chatId`, its account and the first turn's status, almost always `running`. <details markdown="block" class="model-details"> <summary>The new chat, field by field</summary> ```typescript { // TypeScript, all fields are optional chatId: string // c-u<user>-email:<email>-project:<projectId>-chat:<id>-bot:google-flow email: string // the account the chat runs on turn: number // 1 for a new chat status: 'running' | 'completed' | 'waiting_approval' | 'failed' // almost always running error?: string // errors only code?: number // errors only reason?: string // CAPTCHA_FAILED | UNREADABLE_ANSWER | GOOGLE_ERROR | AGENT_QUOTA, on errors after the request reached Google retryAfter?: string // 429 only } ``` </details> ##### Callback When the turn ends, the API sends one `POST` with a JSON body to `replyUrl`. Videos usually finish a minute or two after the turn, so they arrive with `status` `queued`. Get their links from [GET /agent/chats/`chatId`](/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId) or the stream's `media` events. ```json { "chatId": "c-u12345-email:john@gmail.com-project:f166200a-ea22-461a-bc68-47ff6d3ee500-chat:2a0f1973-d554-4fbc-aa6b-0c372edf182e-bot:google-flow", "email": "john@gmail.com", "turn": 2, "status": "completed", "replyRef": "my-ref-42", "messages": [ { "id": "2:b3f9cea0-19f1-4fbb-a207-f3a9cc8c58f9", "turn": 2, "items": [ { "kind": "tool_result", "tool": "generate_video_from_text", "result": { "status": "queued", "media_id": "97aa051d-419f-40fd-a200-f5593d997822", "display_name": "Paper boat floating on pond" } } ] }, { "id": "2:847ad05d-6709-45a0-b75d-b15ea1f5efba", "turn": 2, "items": [ { "kind": "text", "text": "Your video of a paper boat on a calm pond has been scheduled. Feel free to check back in a few minutes!" } ] } ], "media": [ { "referenceId": "user:12345-email:6a6f...-video:97aa051d-419f-40fd-a200-f5593d997822", "mediaId": "97aa051d-419f-40fd-a200-f5593d997822", "type": "video", "status": "queued", "tool": "generate_video_from_text", "model": "veo_3_1_t2v_lite", "displayName": "Paper boat floating on pond" } ] } ``` - `status` is `completed`, `waiting_approval` (the agent asks before it spends credits, see `pendingApproval`) or `failed` (see `error`). - `messages` are the agent's messages of this turn, the same objects as the stream's `message` events. - `media` lists what the turn made, the same objects as the stream's `media` events. - `pendingApproval` is there only while the agent waits for an approval: `{ turn, cost, images, videos, total }`. - `error` is there only on a failed turn: `{ code, message, httpStatus }`, see [Turn errors](/docs/api-google-flow-v1/agent#turn-errors). - `replyRef` is your own `replyRef`, when you sent one. ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/google-flow/agent/chats" \ --max-time 150 \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -d '{ "message": "Make one image of a lighthouse at sunset in a watercolor style.", "email": "john@gmail.com" }' ``` **JavaScript** ``` javascript const token = 'YOUR_API_TOKEN' const response = await fetch('https://api.useapi.net/v1/google-flow/agent/chats', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${token}` }, body: JSON.stringify({ message: 'Make one image of a lighthouse at sunset in a watercolor style.', email: 'john@gmail.com' }), signal: AbortSignal.timeout(150_000) }) const result = await response.json() console.log(response.status, result.chatId) ``` **Python** ``` python import requests token = 'YOUR_API_TOKEN' r = requests.post( 'https://api.useapi.net/v1/google-flow/agent/chats', headers={'Authorization': f'Bearer {token}'}, json={ 'message': 'Make one image of a lighthouse at sunset in a watercolor style.', 'email': 'john@gmail.com', }, timeout=150, ) print(r.status_code, r.json().get('chatId')) ``` === URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-assets-email === Document URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-assets-email --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> assets/`email` description: "Upload image or video assets to a Google Flow account via POST assets/email in the useapi.net Google Flow API v1 — PNG/JPEG/WebP up to 20 MB, MP4 up to 100 MB." parent: Google Flow API nav_order: 500 --- ## Upload Assets November 17, 2025 (November 16, 2026) --- Upload assets to Google Flow. Supports image and video uploads: | Content-Type | File Extension | Max size | | ------------ | -------------- | -------- | | image/png | png | 20 MB | | image/jpeg | jpeg | 20 MB | | image/webp | webp | 20 MB | | video/mp4 | mp4 | 100 MB | [POST raw content using Make.com and similar nocode tools.](/docs/questions-and-answers#how-post-raw-content-to-runwaymlassets-and-minimaxfiles-using-makecom-and-similar-nocode-tools) Uploads stay on the Google account after the generation that used them finishes, and nothing removes them on its own. Over a long-running integration they add up. To see what an account is holding, use [GET /assets/media/`email`](/docs/api-google-flow-v1/get-google-flow-assets-media-email) — it marks uploads with `likelyUpload` — and clear them with [DELETE /assets/`email`](/docs/api-google-flow-v1/delete-google-flow-assets-email). > **https://api.useapi.net/v1/google-flow/assets/`email`** ### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: select from the table above ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. - `Content-Type` is **required**, see table above. ### Path Parameters - `email` is optional. The email address of the Google Flow account to use (URL-encoded if necessary). When only one [account](/docs/api-google-flow-v1/get-google-flow-accounts) is configured, the API will automatically use that account. With multiple [accounts](/docs/api-google-flow-v1/get-google-flow-accounts) configured, omitting the email parameter triggers automatic [load balancing](/docs/api-google-flow-v1/get-google-flow-jobs#load-balancing-algorithm) based on **image generation** job statistics to select the healthiest account. **Note:** The endpoint can be called as either `POST /assets` (no email) or `POST /assets/:email` (explicit email). ### Request Body Binary file contents (raw bytes). Set `Content-Type` to match the file: - `image/png`, `image/jpeg`, `image/webp` for image uploads - `video/mp4` for video uploads (used as `referenceVideo_1` in an Omni V2V edit with `omni-flash-1.2` or `omni-flash`, or as the source of [POST /videos/extend](/docs/api-google-flow-v1/post-google-flow-videos-extend)) The image and video paths return slightly different response shapes — see the 200 response below. ### Responses **200** **200 OK** Upload successful. The response shape differs between image and video uploads — see both below. #### Image upload response Returned when `Content-Type` is `image/png`, `image/jpeg`, or `image/webp`. ```json { "media": { "name": "ff9aa5cc-...redacted...", "projectId": "5c37e988-...redacted...", "workflowId": "69603881-...redacted...", "workflowStepId": "", "mediaMetadata": { "createTime": "2026-02-27T16:34:25.128454Z", "requestData": { "clientPlatform": "CLIENT_PLATFORM_WEB" }, "visibility": "PRIVATE" }, "image": { "userUploadedImage": { "aspectRatio": "IMAGE_ASPECT_RATIO_UNSPECIFIED" }, "dimensions": { "width": 1024, "height": 1024 } } }, "workflow": { "name": "69603881-...redacted...", "metadata": { "displayName": "upload.webp", "createTime": "2026-02-27T16:34:25.128454Z", "primaryMediaId": "ff9aa5cc-...redacted..." }, "projectId": "5c37e988-...redacted..." }, "mediaGenerationId": { "mediaGenerationId": "user:12345-email:6a6f...-image:ff9aa5cc-...redacted..." }, "width": 1024, "height": 1024, "email": "john@gmail.com" } ``` | Field | Description | |-------|-------------| | `media` | Full media object from Google Flow API with upload details and dimensions | | `media.image.dimensions` | Image dimensions as reported by Google (`width` and `height`) | | `workflow` | Workflow metadata including display name and project ID | | `mediaGenerationId.mediaGenerationId` | Reference ID for use in subsequent API calls. Format: `user:{userid}-email:{hex_encoded_email}-image:{internal_media_id}`. Pass this to [GET /assets/`mediaGenerationId`](/docs/api-google-flow-v1/get-google-flow-assets-mediagenerationid) to read back the original bytes via a signed URL. | | `width` | Image width in pixels | | `height` | Image height in pixels | | `email` | Account email that was used for the upload (useful when email was omitted and auto-selected via load balancing) | #### Video upload response Returned when `Content-Type` is `video/mp4`. Use the returned `mediaGenerationId` as `referenceVideo_1` on [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) with `model: "omni-flash-1.2"` or `model: "omni-flash"` to drive V2V edit, or as the `mediaGenerationId` of [POST /videos/extend](/docs/api-google-flow-v1/post-google-flow-videos-extend). ```json { "media": { "name": "07c542b0-...redacted...", "projectId": "5c37e988-...redacted...", "workflowId": "290a1f7a-...redacted...", "mediaMetadata": { "createTime": "2026-05-20T23:04:23.089821Z", "requestData": { "clientPlatform": "CLIENT_PLATFORM_WEB" }, "mediaStatus": { "mediaGenerationStatus": "MEDIA_GENERATION_STATUS_PENDING" }, "visibility": "PRIVATE" }, "video": { "dimensions": { "width": 1280, "height": 720, "length": "11.940s" }, "videoOffset": { "startOffset": "0s", "endOffset": "11.940s" }, "userUploadedVideo": { "encodedVideo": "" } } }, "mediaGenerationId": { "mediaGenerationId": "user:12345-email:6a6f...-video:07c542b0-...redacted..." }, "durationSeconds": 11.94, "width": 1280, "height": 720, "email": "john@gmail.com" } ``` | Field | Description | |-------|-------------| | `media` | Full media object from Google Flow API with upload details and dimensions (mirrors the image response shape, with a `video{}` sub-object instead of `image{}`) | | `media.video.dimensions` | Video dimensions as reported by Google (`width`, `height`, `length`) | | `mediaGenerationId.mediaGenerationId` | Reference ID for use as `referenceVideo_1` on [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos). Format: `user:{userid}-email:{hex_encoded_email}-video:{internal_media_id}`. Also accepted by [GET /assets/`mediaGenerationId`](/docs/api-google-flow-v1/get-google-flow-assets-mediagenerationid) to read back the original bytes via a signed URL. | | `durationSeconds` | Video duration in seconds. Use this to pre-compute `endFrameIndex_1` for V2V edit: `min(round(durationSeconds × 24), 240)` | | `width` | Video width in pixels | | `height` | Video height in pixels | | `email` | Account email that was used for the upload | **400** **400 Bad Request** Invalid request (empty content, unsupported content type, file too large, or content policy violation). **General error:** ```json { "error": "File size (25165824) is over 20971520 bytes", "code": 400 } ``` **Content policy error:** ```json { "error": { "code": 400, "message": "Request contains an invalid argument.", "status": "INVALID_ARGUMENT", "details": [ { "@type": "type.googleapis.com/google.rpc.ErrorInfo", "reason": "PUBLIC_ERROR_TRUMP_FACE_DETECTED" } ] } } ``` **Image refused earlier:** when Google refuses the same image (the exact same file) 10 times with no reason, on at least 2 of your accounts, the API stops sending it to Google for 24 hours after the last refusal and answers right away. Google gives no reason for these refusals: either it does not accept the content, or it cannot read the file. Skip the image, or change it and upload the new version. A refusal that names a reason, like the one above, is never counted. ```json { "error": { "code": 400, "message": "Google refused this exact image 10 times on 3 accounts since 2026-10-18T23:18:30.986Z, so it is not sent to Google again before 2026-10-19T23:18:49.314Z. Google gives no reason: either it does not accept the content, or it cannot read the file. Skip this image, or change it (re-export it, crop or edit it) and upload the new version.", "status": "INVALID_ARGUMENT", "details": [] } } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** Google refused the upload because it treats the Google account as belonging to someone under 18 (`PUBLIC_ERROR_USER_MINOR`). Google Flow is not available to such accounts, so retrying will not help. Use another Google account, or have this one's age verified with Google first. Image uploads need no captcha, so this answer costs no captcha. With `email` omitted, the load balancer sets the account aside for 1 hour for uploads and generation, then tries it again. ```json { "error": "Google refused this request because it treats the Google account john@gmail.com as belonging to someone under 18 (PUBLIC_ERROR_USER_MINOR). Google Flow is not available to such accounts, so retrying will not help. Use another Google account, or have this account's age verified with Google first.", "code": 403 } ``` **404** **404 Not Found** Account not found or not configured. ```json { "error": "Google Flow account john@gmail.com not found", "code": 404 } ``` **429** **429 Too Many Requests** A `429` means Google is rate-limiting the account that handled your upload. Most image-upload 429s carry no reason code. The body is `{"error":{"code":429,"message":"flow.google.com maseQ failed","status":"RESOURCE_EXHAUSTED","details":[]}}`, with `details` empty and nothing to read a reason from — the `message` inside that `error` object names the upload call that failed, and is not the top-level `message` described below. That form is handled as `USER_REQUESTS_THROTTLED` all the same, so everything below applies to it unchanged: the same cooldown, the same `Retry-After`, the same upload-only quarantine, and the same top-level `message` and `retryAfter` fields added alongside Google's `error` object. Some accounts instead carry one of two reasons: | Reason | Meaning | Cooldown | |--------|---------|----------| | `PUBLIC_ERROR_`<br>`USER_QUOTA_REACHED` | The account's overall Flow quota cap | ~30 min | | `PUBLIC_ERROR_`<br>`USER_REQUESTS_THROTTLED` | Google is throttling uploads for this account | ~30 min minimum, can persist | Google meters uploads separately from generation, so `USER_REQUESTS_THROTTLED` on this endpoint does not mean the account is out of action. The same account can keep serving [POST /images](/docs/api-google-flow-v1/post-google-flow-images) and [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) normally while every upload is refused. They also survive separately. An account that has stopped accepting uploads keeps every image already uploaded to it, and those `mediaGenerationId` values stay usable as `reference_N` on that account indefinitely. An account in that state is still worth generating on — it simply cannot take new source material. The limit does clear. Accounts that reached it have uploaded again within about two weeks, and we can't yet tell whether it resets on a timer or when the account's monthly subscription renews. Such an account is worth resting rather than replacing. Counting `post-assets` per account in [GET /v2/account/stats](/docs/account-management/get-account-stats) shows how much of its upload allowance has been spent. The response carries a `Retry-After` header. Treat it as a minimum wait rather than an estimate of when the limit clears — it is a fixed cooldown, not a per-account prediction, and an upload throttle can sit on an account for hours or days. On `USER_REQUESTS_THROTTLED` the body also carries a `message` field spelling this out, and normally a `retryAfter` timestamp mirroring the header. If you passed `email`, that account is the one being limited — upload to a different account rather than retrying the same one. If you omitted `email` and have more than one account, the load balancer automatically routes around limited accounts, so you only see a `429` (`error: "no_eligible_account"`) once every account is limited — see [GET /jobs › Load Balancing Algorithm](/docs/api-google-flow-v1/get-google-flow-jobs#load-balancing-algorithm). An upload throttle only removes the account from upload routing, so generation requests still reach it. A video upload is the exception to everything above. It fails earlier, in Google's upload-init step, and returns a plain `{"error": "Video upload init failed: HTTP 429"}` with no reason code, no `Retry-After` and no `message`, and it does not quarantine the account. On that `no_eligible_account` response, each `skipReasons[].model` reports what the account was quarantined for. Uploads carry no model, so entries armed by this endpoint report `upload` — a routing scope, not a model you can request. On this endpoint the only other value is `*` (account-wide). On the generation endpoints it is a real model name or `*`. **503** **503 Service Unavailable** Google's upload service is temporarily unavailable. The error is forwarded with a `Retry-After` header — wait a few seconds and retry. This endpoint uses no captcha provider, so the `Captcha service failed` 503 does not apply here. ```json { "error": { "code": 503, "message": "Service temporarily unavailable.", "status": "UNAVAILABLE" } } ``` **596** **596 Session Error** Google rejected the account's session, and the API is re-verifying the account on its own: retry in about a minute. If Google signed the account out, the account keeps answering `596` and you get a reconnect email: add it again by following [Setup Google Flow](/docs/start-here/setup-google-flow). ```json { "error": "Google Flow account john@gmail.com Google rejected this account session (HTTP 401). We are automatically re-verifying it — please retry in about a minute. If the account was signed out, you will receive a reconnect email.", "code": 596 } ``` ### Model The uploaded image or video, with Google's record of it and the `mediaGenerationId` to use as a reference. <details markdown="block" class="model-details"> <summary>The uploaded image or video, field by field</summary> #### Image upload response ```typescript { media: { // Full media object from Google Flow API name: string // Media UUID projectId: string // the Google Flow project the upload is in workflowId: string // the Google Flow workflow of the upload workflowStepId: string // Google's workflow step id (empty when Google gives none) mediaMetadata: { // Google's record of the upload createTime?: string // ISO 8601 timestamp requestData?: { // how the upload was made, when Google names the platform clientPlatform: string // e.g. "CLIENT_PLATFORM_WEB" } visibility?: string // "PRIVATE" } image: { // the uploaded image userUploadedImage: { // marks the media as an upload aspectRatio: string // Google's aspect name, e.g. IMAGE_ASPECT_RATIO_LANDSCAPE or IMAGE_ASPECT_RATIO_PORTRAIT. IMAGE_ASPECT_RATIO_UNSPECIFIED when Google gives none } dimensions?: { // the image size Google read from the file width: number // pixels height: number // pixels } } } workflow?: { // Workflow metadata name: string // Workflow UUID metadata?: { // the workflow's details displayName?: string // Original filename createTime?: string // ISO 8601 primaryMediaId?: string // Same as media.name } projectId?: string // the Google Flow project of the workflow } mediaGenerationId: { // the reference id, wrapped in an object mediaGenerationId: string // Reference ID: user:{userid}-email:{hex_encoded_email}-image:{internal_media_id} } width?: number // Image width in pixels (absent when neither Google nor the file gives it) height?: number // Image height in pixels email: string // Account email used for upload } ``` #### Video upload response Returned when `Content-Type: video/mp4`. ```typescript { media: { // Google's record of the upload, as Google returned it (video{} instead of image{}) name: string // Media UUID projectId: string // the Google Flow project the upload is in workflowId: string // the Google Flow workflow of the upload workflowStepId?: string // Google's workflow step id, when Google gives one mediaMetadata: { // Google's record of the upload createTime: string // ISO 8601 timestamp requestData: { // how the upload was made clientPlatform: string // e.g. "CLIENT_PLATFORM_WEB" } mediaStatus: { // Google's processing status mediaGenerationStatus: string // e.g. "MEDIA_GENERATION_STATUS_PENDING" right after the upload } visibility: string // "PRIVATE" } video: { // the uploaded video dimensions: { // size and duration, as Google reports them width: number // pixels, as Google reports them (may differ from the file's) height: number // pixels, as Google reports them length: string // duration, e.g. "11.940s" } videoOffset?: { // the clip window, set to the whole clip. Present when the duration is known startOffset: string // "0s" endOffset: string // the clip's duration, e.g. "11.940s" } userUploadedVideo: { // marks the media as an upload encodedVideo: string // always empty: Google returns no bytes here } } } mediaGenerationId: { // the reference id, wrapped in an object mediaGenerationId: string // Reference ID: user:{userid}-email:{hex_encoded_email}-video:{internal_media_id} // — use as referenceVideo_1 on POST /videos with model omni-flash-1.2 or omni-flash, or as the source of POST /videos/extend } durationSeconds?: number // Video duration in seconds width?: number // Video width in pixels (from upload finalize response) height?: number // Video height in pixels email: string // Account email used for upload } ``` </details> ### Examples **Curl** ``` bash # Option 1: Without email (auto-selection/load balancing) curl -X POST \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: image/jpeg" \ --data-binary @/path/to/your/image.jpeg \ "https://api.useapi.net/v1/google-flow/assets" # Option 2: With specific email curl -X POST \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: image/jpeg" \ --data-binary @/path/to/your/image.jpeg \ "https://api.useapi.net/v1/google-flow/assets/john%40gmail.com" ``` **JavaScript** ``` javascript const token = 'YOUR_API_TOKEN'; // Option 1: Without email (auto-selection/load balancing) const apiUrl = 'https://api.useapi.net/v1/google-flow/assets'; // Option 2: With specific email // const email = 'john@gmail.com'; // const apiUrl = `https://api.useapi.net/v1/google-flow/assets/${encodeURIComponent(email)}`; // Load image - Example 1: Fetch from URL const imageUrl = "https://upload.wikimedia.org/wikipedia/commons/7/7d/Mona_Lisa_color_restoration.jpg"; const responseImage = await fetch(imageUrl); const blob = await responseImage.blob(); // Load image - Example 2: From local file (Node.js) // const fsp = require('fs').promises; // const imageFileName = "./cat.png"; // const blob = new Blob([await fsp.readFile(imageFileName)]); // Load image - Example 3: From file input element // // <input id="image-file" type="file"> // const imageFile = document.getElementById('image-file'); // const blob = imageFile.files[0]; const response = await fetch(apiUrl, { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': blob.type || 'image/jpeg' }, body: blob }); const result = await response.json(); console.log('Upload result:', result); console.log('Reference ID:', result.mediaGenerationId.mediaGenerationId); console.log('Account used:', result.email); ``` **Python** ``` python import requests from urllib.parse import quote token = 'YOUR_API_TOKEN' # Option 1: Without email (auto-selection/load balancing) api_url = 'https://api.useapi.net/v1/google-flow/assets' # Option 2: With specific email # email = 'john@gmail.com' # api_url = f'https://api.useapi.net/v1/google-flow/assets/{quote(email)}' # Load image - Example 1: Fetch from URL # image_url = "https://upload.wikimedia.org/wikipedia/commons/7/7d/Mona_Lisa_color_restoration.jpg" # response_image = requests.get(image_url) # file_content = response_image.content # Load image - Example 2: From local file # image_file_path = "./image.jpg" # with open(image_file_path, 'rb') as image_file: # file_content = image_file.read() headers = { 'Authorization': f'Bearer {token}', 'Content-Type': 'image/jpeg' } response = requests.post( api_url, headers=headers, data=file_content ) result = response.json() print('Upload result:', result) print('Reference ID:', result.get('mediaGenerationId', {}).get('mediaGenerationId')) print('Account used:', result.get('email')) ``` ### Try It <script> async function apiExecutePostGoogleFlowAssetEmail() { const tokenElement = document.getElementById('input-token'); const emailElement = document.getElementById('input-email'); const inputFile = document.getElementById('input-file'); if (!inputFile.files[0]) { alert('Please select a file.'); return false; } const blob = inputFile.files[0]; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${tokenElement.value}`, 'Content-Type': blob.type || 'image/jpeg' }, body: blob }; await apiExecute( `https://api.useapi.net/v1/google-flow/assets/${encodeURIComponent(emailElement.value)}`, 'input', data ); } function clearInputFile() { document.getElementById('input-file').value = ''; return false; } </script> <form id="input" class="input-form" onsubmit="return false;"> <div class="input-field"> <div class="input-field-row"> <label for="input-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="input-token" type="text" class="input-element" required aria-required="true"> </label> <label for="input-email"><span>email (optional)</span> <input id="input-email" type="text" class="input-element" placeholder="john@gmail.com"> </label> <label for="input-file"><span>Upload file</span> <div style="display:flex"> <button id="input-file-clear" onclick="clearInputFile()">Clear </button> <input id="input-file" type="file" class="input-element" accept="image/png,image/jpeg,image/webp"> </div> </label> </div> <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecutePostGoogleFlowAssetEmail()">Go</button> </div> </form> <div id="input-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-characters === Document URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-characters --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> characters description: "Bundle reference images and an optional voice into a named character via POST characters in the useapi.net Google Flow API v1 for reuse across Veo and Gemini generations." parent: Google Flow API nav_order: 1200 --- ## Create Character June 5, 2026 (November 16, 2026) --- Create a **character** — a reusable Google Flow entity that bundles 1–2 reference images plus an optional attached voice. Characters can be referenced from [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) and [POST /images](/docs/api-google-flow-v1/post-google-flow-images) via `character_1..7` to keep the same identity across generations. ### What can use a character? Per Google Flow's model rules: | Model | Character support | Image budget | Voice budget | |---|:-:|---|---| | Veo 3.1 Quality<br>`veo-3.1-quality` | No | n/a | n/a | | Veo 3.1 Fast<br>`veo-3.1-fast` | Yes (Ingredients mode, 8 s duration only) | 3 total (character images + raw image refs) | 1 voice | | Veo 3.1 Lite<br>`veo-3.1-lite` | Yes (Ingredients mode, 8 s duration only) | 3 total (character images + raw image refs) | 1 voice | | Veo 3.1 Lite Lower Priority<br>`veo-3.1-lite-low-priority` | Yes (Ingredients mode, 8 s duration only) | 3 total (character images + raw image refs) | 1 voice | | Omni 1.2 Flash<br>`omni-flash-1.2` | Yes (Ingredients mode, all durations, and [extend](/docs/api-google-flow-v1/post-google-flow-videos-extend)) | 10 total (character images + raw image refs), 3 on extend | 5 voices, 3 on extend | | Omni 1.1 Flash<br>`omni-flash` | Yes (Ingredients mode, all durations) | 7 total (character images + raw image refs) | 5 voices | Example: `character_1` with 2 images + `character_2` with 2 images + 3 `referenceImage_*` = 7 effective image refs — accepted on `omni-flash`, rejected on `veo-3.1-fast` (cap 3). > **https://api.useapi.net/v1/google-flow/characters** ### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` ### Request Body ```json { "displayName": "Carol", "personalityNotes": "A curious traveler with a sharp wit", "imageReference_1": "user:12345-email:6a6f...-image:abc123...", "imageReference_2": "user:12345-email:6a6f...-image:def456...", "voice": "user:12345-email:6a6f...-voice:d990a2f9-...-mid:d55b6d59-..." } ``` - `displayName` is **required**, user-facing name. Range: 1-200 chars. - `imageReference_1` is **required**, an image `mediaGenerationId` — either uploaded via [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email) or generated via [POST /images](/docs/api-google-flow-v1/post-google-flow-images). At least one image is required. - `imageReference_2` is optional, second image reference (max two per character). - `personalityNotes` is optional, short description shown alongside the character. Range: 0-2000 chars. - `voice` is optional. Either a system voice preset name (e.g. `Umbriel`, case-insensitive — one of the 30 presets) or a user voice from [POST /voices](/docs/api-google-flow-v1/post-google-flow-voices) (use the `voice` field from its response). ### Responses **200** **200 OK** ```json { "entityId": "f470f1b5-...", "character": "user:12345-email:6a6f...-character:f470f1b5-...-imgs:2-voice:d990a2f9-...", "displayName": "Carol", "personalityNotes": "A curious traveler with a sharp wit", "imageReferences": [ { "mediaId": "abc123..." }, { "mediaId": "def456..." } ], "voice": "user:12345-email:6a6f...-voice:d990a2f9-...-mid:d55b6d59-..." } ``` Use the `character` field as the value for `character_1`..`character_10` on [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) (slots `_8`..`_10` on `omni-flash-1.2` only) and `character_1`..`character_7` on [POST /images](/docs/api-google-flow-v1/post-google-flow-images). **400** **400 Bad Request** Validation error. ```json { "error": "Parameter displayName is required", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** An image or voice reference belongs to another useapi.net user, so no character was created. Use images and voices made or uploaded with your own API token. ```json { "error": "Unauthorized access to user:99999 detected in image reference user:99999-email:6a6f...-image:abc123...", "code": 403 } ``` When the voice belongs to another user: ```json { "error": "Unauthorized access to user:99999 detected in voice reference", "code": 403 } ``` **404** **404 Not Found** ```json { "error": "Google Flow account john@gmail.com not found", "code": 404 } ``` ### Model The new character, with the reference-id to send as `character_1` and up, and the images and voice you attached. <details markdown="block" class="model-details"> <summary>The new character, field by field</summary> ```typescript { entityId: string // Google's id of the character character: string // reference-id used in character_1..10 on POST /videos, character_1..7 on POST /images displayName: string // the name you sent personalityNotes?: string // the notes you sent; omitted when none imageReferences: Array<{ // the images you attached (imageReference_1, imageReference_2) mediaId: string // the image reference-id you sent }> voice?: string // echoed when a voice was attached: the voice's reference-id for a custom voice // (user:N-email:...-voice:...-mid:...), or the Title-case preset name for a system // voice (e.g. Umbriel) } ``` </details> ### Examples **Curl** ``` bash curl -X POST \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "displayName": "Carol", "imageReference_1": "user:12345-email:6a6f...-image:abc123...", "imageReference_2": "user:12345-email:6a6f...-image:def456..." }' \ "https://api.useapi.net/v1/google-flow/characters" ``` **JavaScript** ``` javascript const r = await fetch('https://api.useapi.net/v1/google-flow/characters', { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ displayName: 'Carol', imageReference_1: imgA, imageReference_2: imgB, }) }) const result = await r.json() console.log('character ref:', result.character) ``` **Python** ``` python import requests r = requests.post( 'https://api.useapi.net/v1/google-flow/characters', headers={'Authorization': f'Bearer {token}'}, json={ 'displayName': 'Carol', 'imageReference_1': img_a, 'imageReference_2': img_b, }, ) print('character ref:', r.json()['character']) ``` ### Try It <form id="input" class="input-form" onsubmit="return false;"> <div class="input-field"> <div class="input-field-row"> <label for="input-token"><span>API Token</span> <input id="input-token" type="text" class="input-element" required aria-required="true"> </label> <label for="input-displayName"><span>displayName (required, 1–200 chars)</span> <input id="input-displayName" type="text" class="input-element input-query-param" required aria-required="true" maxlength="200" placeholder="Carol"> </label> <label for="input-personalityNotes"><span>personalityNotes (optional, ≤ 2000 chars)</span> <input id="input-personalityNotes" type="text" class="input-element input-query-param" maxlength="2000" placeholder="A curious traveler with a sharp wit"> </label> <label for="input-imageReference_1"><span>imageReference_1 (required — from <a href="/docs/api-google-flow-v1/post-google-flow-assets-email">POST /assets/email</a> or <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a>)</span> <input id="input-imageReference_1" type="text" class="input-element input-query-param" required aria-required="true" placeholder="user:123-email:...-image:..."> </label> <label for="input-imageReference_2"><span>imageReference_2 (optional)</span> <input id="input-imageReference_2" type="text" class="input-element input-query-param" placeholder="user:123-email:...-image:..."> </label> <label for="input-voice"><span>voice (optional — system voice OR user voice; select to preview)</span> <div> <select id="input-voice" class="input-element input-query-param" onchange="gfOnVoicePicked('input-voice','input-voice-audio','input-voice-meta','input-token')"></select> <button type="button" class="btn btn-secondary" style="margin-left:6px" onclick="gfRefreshUserVoices('input-voice','input-token','input-imageReference_1')">Refresh user voices</button> <audio id="input-voice-audio" class="audio-player" style="display:none;margin-top:4px" controls></audio> <div id="input-voice-meta" style="display:none;font-size:0.9em;color:#666;margin-top:2px"></div> </div> </label> </div> <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecutePostGoogleFlowCharacters()">Go</button> </div> </form> <div id="input-response" class="response-placeholder visible-false"></div> <script src="/assets/js/google-flow-voices.js"></script> <script> gfPopulateVoiceSelect('input-voice'); async function apiExecutePostGoogleFlowCharacters() { const tokenElement = document.getElementById('input-token'); const elementId = 'input'; const payload = {}; document.querySelectorAll('.input-query-param').forEach(input => { const id = input.id; const value = input.value?.trim(); if (id.startsWith('input-') && value !== '') payload[id.replace('input-', '')] = value; }); const data = { method: 'POST', headers: { 'Authorization': `Bearer ${tokenElement.value}`, 'Content-Type': 'application/json' }, body: JSON.stringify(payload), }; await apiExecute('https://api.useapi.net/v1/google-flow/characters', elementId, data, { includeTimer: true }); } </script> === URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-images-upscale === Document URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-images-upscale --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> images/upscale seo_title: "Google Flow Image Upscale API: 2K and 4K" description: "Upscale a Nano Banana 2 Lite, Nano Banana 2.1 or Nano Banana Pro image to 2K or 4K via POST /images/upscale in the useapi.net Google Flow API v1." parent: Google Flow API nav_order: 650 --- ## Upscale Images January 2, 2026 (November 18, 2026) --- Upscale a previously generated image to 2K or 4K resolution. This endpoint uses Google Flow's native image upscaling capabilities. Seeing "Upscaling failed" in Flow? [Why Google Flow upscales fail and how to fix it](/docs/articles/google-flow-errors#upscaling-failed). **Important:** - `2k` works on every plan, including free accounts. - `4k` requires a [Google AI Ultra](https://one.google.com/ai) subscription. Every other plan, free, Plus and Pro alike, is limited to `2k` and a `4k` request answers `400` with `4k upscaling is not available for this account`. The request is refused before a reCAPTCHA token is solved, so it costs you nothing — raising `captchaRetry` will not change the outcome. - Both resolutions are free of Google Flow credits. > **https://api.useapi.net/v1/google-flow/images/upscale** ### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Request Body ```json { "mediaGenerationId": "user:12345-email:6a6f...-image:CAMaJDMx...", "resolution": "2k" } ``` - `mediaGenerationId` is **required**. The `mediaGenerationId` from a previously generated image via [POST /images](/docs/api-google-flow-v1/post-google-flow-images). - `resolution` is optional. Target resolution for upscaling (default: `2k`). Supported values: `2k`, `4k`. - `captchaToken`, `captchaRetry`, `captchaOrder` are optional, mutually exclusive captcha parameters. See [Captcha Parameters](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers#captcha-parameters) for details. ### Responses **200** **200 OK** Image upscaled successfully. Returns base64-encoded image data. ```json { "encodedImage": "/9j/4AAQSkZJRgABAQAAAQ...base64 encoded image data...", "media": { "name": "3c9d5e7a-...redacted...", "projectId": "9f63078c-...redacted...", "workflowId": "b0b8b280-...redacted...", "workflowStepId": "CAI", "mediaMetadata": { "createTime": "2026-11-15T22:35:07.248288Z", "mediaBlobSize": "3215872", "visibility": "PRIVATE" } }, "captcha": { "service": "AntiCaptcha", "taskId": "618254930", "durationMs": 3500, "attempts": [ { "service": "AntiCaptcha", "taskId": "618254930", "durationMs": 3500, "success": true } ] } } ``` **400** **400 Bad Request** Invalid request (missing or invalid mediaGenerationId), or `4k` on an account without Google AI Ultra. ```json { "error": "4k upscaling is not available for this account", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** Google rejected the captcha on every try. We retry with a fresh captcha as many times as you allow (`captchaRetry`, default 5, or the providers in `captchaOrder`) and return this `403` only when all of them were rejected. The top-level `error` starts with `captcha_quality:`, for example `"captcha_quality: PUBLIC_ERROR_UNUSUAL_ACTIVITY after 5 attempts. Google refused all 5 captcha tokens for user@example.com, so nothing was generated and no Google Flow credits were used (5 captcha solves were spent). Google is flagging this account's requests as unusual activity. If it keeps happening, use another account, or leave out email so the API picks one. See GET /accounts/captcha-stats summary.by_account"`. A `429` with `PUBLIC_ERROR_UNUSUAL_ACTIVITY_TOO_MUCH_TRAFFIC` reads the same way. Two `403`s are not a captcha problem, and we answer them after one try instead of retrying. `PUBLIC_ERROR_MODEL_ACCESS_DENIED` in the response means Google refused the model on that account, so raising `captchaRetry` or adding providers will not help. Check that the account's plan includes the model. Since 2026-09-23 Google no longer offers `veo-3.1-lite-low-priority` to invited members of an Ultra $199 family plan — only the family manager's account keeps it. `PUBLIC_ERROR_USER_MINOR` means Google treats the Google account as belonging to someone under 18, and Google Flow is not available to such accounts. The `error` says so in plain words. No captcha or retry changes it: use another Google account, or have this one's age verified with Google first. With `email` omitted, the load balancer sets such an account aside for 1 hour, then tries it again. Nothing was created when this happens. Google checks the captcha before it starts generating, so no Google credits were used and you can resubmit straight away. Your captcha provider still bills each solve. The usual cause is the Google account, not the captcha provider. Google gives each account its own trust level. On a trusted account it accepts about 9 in 10 captchas, on a distrusted one about 3 in 10, whichever provider solved them. Most customers have a few distrusted accounts among many good ones. To see which accounts are affected, use [GET /accounts/captcha-stats](/docs/api-google-flow-v1/get-google-flow-accounts-captcha-stats). Its `summary.by_account` shows, for each of your Google accounts, how many captchas were tried and what share Google accepted. [GET account/stats](/docs/account-management/get-account-stats) with `bot=google-flow` also shows how many requests each account finished with each response code. - If one or a few accounts are far below the others, the API already sends them less work: when you leave out `email`, each captcha Google rejected on an account in the last 15 minutes lowers its chance of being picked, for generations and for image uploads. They still get some work, so an account that recovers gets its full share back. If you pin requests with `email`, move them to your other accounts yourself. Replace an account that stays low for more than a day or two. - If all your accounts drop at the same time, it's the captcha provider. Configure at least two providers with [POST /accounts/captcha-providers](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers), and the API will start with whichever one Google accepts best. A higher `captchaRetry` gets more requests through on a distrusted account, but every extra try is another paid solve. **404** **404 Not Found** Account not found or image not found. ```json { "error": "Google Flow account john@gmail.com not found", "code": 404 } ``` **429** **429 Too Many Requests** Google returns several `RESOURCE_EXHAUSTED` 429 variants. Check the `reason` field and respond accordingly: | Reason | Meaning | Scope | What to do | Cooldown | |--------|---------|-------|------------|----------| | `PUBLIC_ERROR_`<br>`USER_REQUESTS_THROTTLED` | Google is throttling the account (the token was fine). Uploads and generation are metered separately | All models on the account — or uploads only, when POST /assets triggered it | Run fewer parallel requests, or switch accounts. From POST /assets, retrying the same one rarely clears it | ~30 min. From POST /assets, treat it as a minimum — it can persist | | `PUBLIC_ERROR_`<br>`USER_QUOTA_REACHED` | Account's overall Flow quota cap | All models on the account | Add accounts, or omit `email` to load-balance | ~30 min | | `PUBLIC_ERROR_`<br>`PER_MODEL_DAILY_QUOTA_REACHED` | Per-model daily quota | Only that model, on that account | Switch model, or wait | Next UTC midnight | | `PUBLIC_ERROR_`<br>`UNUSUAL_ACTIVITY_TOO_MUCH_TRAFFIC` | Google rejected the captcha on every try (we already retried). Usually a distrusted Google account, sometimes the provider | Per request | Check which accounts are affected in [captcha-stats](/docs/api-google-flow-v1/get-google-flow-accounts-captcha-stats#when-google-rejects-captchas). Rest or replace those accounts. Add a second provider if all accounts drop together | 60s | Every `429` returns the cooldown two ways — an HTTP `Retry-After: <seconds>` header and a body `retryAfter: <ISO timestamp>` field. Honor it before retrying. When `email` is omitted, the first three reasons quarantine the account and the load balancer routes around it. If every account is quarantined for the model you get `429` with `error: "no_eligible_account"`. Routing details: [GET /jobs › Load Balancing Algorithm](/docs/api-google-flow-v1/get-google-flow-jobs#load-balancing-algorithm). Captcha-quality failures prefix the top-level `error` with `captcha_quality:` (e.g. `"captcha_quality: PUBLIC_ERROR_UNUSUAL_ACTIVITY_TOO_MUCH_TRAFFIC after 3 attempts"`) so you can detect them without parsing the nested body. **503** **503 Service Unavailable** `503` has two distinct causes — check the response body to tell them apart. A transient Google-side outage. Wait 5-10 seconds and retry. ```json { "error": { "code": 503, "message": "Service temporarily unavailable.", "status": "UNAVAILABLE" } } ``` A captcha-provider failure — the top-level `error` is prefixed `Captcha service failed:`. The problem is your captcha provider (check its API key and balance), not Google. Don't retry until the provider is back. ```json { "error": "Captcha service failed: ERROR_ZERO_BALANCE", "code": 503 } ``` Google can also fail an upscale with its own server error and no reason, most often on 4K upscales sent in large batches. Nothing was made and no Google Flow credits were used. Retry later, or upscale to 2K. ```json { "error": "Google could not upscale this image right now (its server error, HTTP 500, gave no reason): nothing was made and no Google Flow credits were used. Retry later, or upscale to 2K", "code": 503 } ``` ### Model The upscaled image as Base64 JPEG data, Google's record of it and the captcha used. <details markdown="block" class="model-details"> <summary>The upscaled image, field by field, and the type it uses (<code>FlowCaptcha</code>)</summary> - `encodedImage` - Base64-encoded upscaled image data (JPEG format) - `media` - Google's record of the upscaled image (left out when it could not be read) - `captcha` - Captcha metadata for debugging/research - `captcha.service` - Provider that returned the successful token - `captcha.taskId` - Task ID from the captcha service - `captcha.durationMs` - Total time for all captcha attempts - `captcha.attempts` - Array of all captcha attempts (including failures) ```typescript { encodedImage: string // Base64-encoded image (decode and save as .jpg) media?: { // Google's record of the upscaled image (left out when it could not be read) name: string // Google's media id of the upscaled image projectId: string // the Google Flow project the image is in workflowId?: string // the Google Flow workflow (project item) that holds the image workflowStepId?: string // the workflow step mediaMetadata: { // Google's record of the file createTime?: string // ISO 8601 time Google created the upscale mediaBlobSize?: string // the file's size in bytes, as a string visibility?: string // "PRIVATE" } } captcha: FlowCaptcha // the captcha solved for this request (described below) } ``` When the request fails: ```typescript { error: string // what went wrong, e.g. "PUBLIC_ERROR_USER_QUOTA_REACHED (HTTP 429)" code: number // the HTTP status retryAfter?: string // ISO 8601 time to retry after, on a 429 (the Retry-After header carries the same in seconds) response?: { // Google's answer, when Google or the captcha refused the request error?: { // Google's error code: number // HTTP status Google answered message: string // the error message, e.g. "flow.google.com SPrCad failed" status: string // Google's status name, e.g. "RESOURCE_EXHAUSTED" details: Array<{ // Google's error details '@type': string // the type name of the detail reason: string // Google's reason code, e.g. "PUBLIC_ERROR_USER_QUOTA_REACHED" }> } captcha: FlowCaptcha // the captcha tried or used } } ``` The type used above: **`FlowCaptcha`**: the `captcha` in the answer above. ```typescript { service?: string // the provider whose token Google accepted: `CapSolver`, `AntiCaptcha`, // `YesCaptcha`, `CapMonster`, `SolveCaptcha`, `2Captcha`, `EzCaptcha` or // `UserProvided`. Always on a success answer taskId?: string // that provider's task id (none for `UserProvided`) durationMs?: number // ms from the first solve to the token used. Always on a success answer error?: string // why no captcha token could be had, on a failed request attempts: Array<{ // every solve tried, in order, failed ones included service: string // the provider asked taskId?: string // that provider's task id durationMs: number // how long this solve took, in ms success: boolean // true when the provider returned a token (Google may still have refused it) error?: string // why the solve failed userAgent?: string // the browser user agent the provider solved with, when it reports one secChUa?: string // the Sec-CH-UA value the provider solved with, when it reports one (may be empty) cost?: string // the provider's price for this solve, as the provider reports it ip?: string // the IP address the provider reports for this solve createTime?: number // Unix time the provider started the solve, as it reports it endTime?: number // Unix time the provider finished the solve, as it reports it solveCount?: number // the provider's own solve counter for this task }> } ``` </details> ### Examples **Curl** ``` bash # First generate an image curl -X POST \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"prompt": "A beautiful sunset over mountains"}' \ "https://api.useapi.net/v1/google-flow/images" > generate.json # Extract mediaGenerationId from the response MEDIA_ID=$(jq -r '.media[0].image.generatedImage.mediaGenerationId' generate.json) # Upscale the image to 2K curl -X POST \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d "{\"mediaGenerationId\": \"$MEDIA_ID\", \"resolution\": \"2k\"}" \ "https://api.useapi.net/v1/google-flow/images/upscale" > upscale.json # Decode base64 and save as image jq -r '.encodedImage' upscale.json | base64 -d > upscaled_image.jpg ``` **JavaScript** ``` javascript const token = 'YOUR_API_TOKEN'; // First generate an image const generateResponse = await fetch('https://api.useapi.net/v1/google-flow/images', { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ prompt: 'A beautiful sunset over mountains' }) }); const generated = await generateResponse.json(); const mediaGenerationId = generated.media[0].image.generatedImage.mediaGenerationId; // Upscale the image const upscaleResponse = await fetch('https://api.useapi.net/v1/google-flow/images/upscale', { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ mediaGenerationId, resolution: '2k' }) }); const upscaled = await upscaleResponse.json(); // Decode base64 and save const buffer = Buffer.from(upscaled.encodedImage, 'base64'); require('fs').writeFileSync('upscaled_image.jpg', buffer); console.log('Upscaled image saved!'); ``` **Python** ``` python import requests import base64 token = 'YOUR_API_TOKEN' headers = { 'Authorization': f'Bearer {token}', 'Content-Type': 'application/json' } # First generate an image generate_response = requests.post( 'https://api.useapi.net/v1/google-flow/images', headers=headers, json={'prompt': 'A beautiful sunset over mountains'} ) generated = generate_response.json() media_generation_id = generated['media'][0]['image']['generatedImage']['mediaGenerationId'] # Upscale the image upscale_response = requests.post( 'https://api.useapi.net/v1/google-flow/images/upscale', headers=headers, json={ 'mediaGenerationId': media_generation_id, 'resolution': '2k' } ) upscaled = upscale_response.json() # Decode base64 and save image_data = base64.b64decode(upscaled['encodedImage']) with open('upscaled_image.jpg', 'wb') as f: f.write(image_data) print('Upscaled image saved!') ``` ### Try It <script> function displayUpscaledImage(response, elementId) { const mediaContainer = document.getElementById(`${elementId}-media-links`); if (!mediaContainer) return; mediaContainer.innerHTML = ''; if (!response.encodedImage) { mediaContainer.style.display = 'none'; return; } const dataUrl = `data:image/jpeg;base64,${response.encodedImage}`; const downloadLink = document.createElement('a'); downloadLink.href = dataUrl; downloadLink.download = 'upscaled_image.jpg'; downloadLink.className = 'media-link image'; downloadLink.textContent = 'Download Upscaled Image'; const container = document.createElement('div'); container.className = 'media-links-container'; container.innerHTML = '<strong>Upscaled Image:</strong> '; container.appendChild(downloadLink); const imgPreview = document.createElement('img'); imgPreview.src = dataUrl; imgPreview.style.cssText = 'max-width:100%;margin-top:10px;display:block;border:1px solid #ccc;'; imgPreview.alt = 'Upscaled image preview'; mediaContainer.appendChild(container); mediaContainer.appendChild(imgPreview); mediaContainer.style.display = 'block'; } async function apiExecutePostGoogleFlowImagesUpscale() { const tokenElement = document.getElementById('input-token'); const elementId = 'input'; const payload = {}; const inputs = document.querySelectorAll('.input-query-param'); inputs.forEach(input => { const id = input.id; const value = input.value?.trim(); if (id.startsWith('input-') && value !== '' && value !== undefined) { const key = id.replace('input-', ''); if (key === 'captchaRetry') { payload[key] = parseInt(value); } else { payload[key] = value; } } }); const data = { method: 'POST', headers: { 'Authorization': `Bearer ${tokenElement.value}`, 'Content-Type': 'application/json' }, body: JSON.stringify(payload) }; const mediaLinks = document.getElementById(`${elementId}-media-links`); if (mediaLinks) mediaLinks.style.display = 'none'; const status = await apiExecute('https://api.useapi.net/v1/google-flow/images/upscale', elementId, data, { includeTimer: true }); if (status === 200) { try { const content = document.getElementById(`${elementId}-response-json`); const response = JSON.parse(content.innerText); displayUpscaledImage(response, elementId); } catch (e) { console.error('Failed to parse response for image display:', e); } } } </script> <form id="input" class="input-form" onsubmit="return false;"> <div class="input-field"> <div class="input-field-row"> <label for="input-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="input-token" type="text" class="input-element" required aria-required="true"> </label> <label for="input-mediaGenerationId"><span>mediaGenerationId (required, from <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a>)</span> <input id="input-mediaGenerationId" type="text" class="input-element input-query-param" required aria-required="true" placeholder="user:123-email:...-image:..."> </label> <label for="input-resolution"><span>resolution</span> <select id="input-resolution" class="input-element input-query-param"> <option value="2k">2k (default)</option> <option value="4k">4k</option> </select> </label> <label for="input-captchaToken"><span>captchaToken (optional, your own reCAPTCHA token)</span> <input id="input-captchaToken" type="text" class="input-element input-query-param" placeholder="reCAPTCHA v3 Enterprise token"> </label> <label for="input-captchaRetry"><span>captchaRetry (1-10, optional)</span> <input id="input-captchaRetry" type="number" class="input-element input-query-param" min="1" max="10" placeholder="5"> </label> <label for="input-captchaOrder"><span>captchaOrder (optional)</span> <input id="input-captchaOrder" type="text" class="input-element input-query-param" placeholder="CapSolver,AntiCaptcha"> </label> </div> <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecutePostGoogleFlowImagesUpscale()">Go</button> </div> </form> <div id="input-media-links" style="display:none;"></div> <div id="input-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-images === Document URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-images --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> images description: "Generate AI images from text prompts or reference images via POST images in the useapi.net Google Flow API v1 using Nano Banana 2 Lite, Nano Banana 2.1, or Nano Banana Pro." parent: Google Flow API nav_order: 600 --- ## Generate Images November 17, 2025 (November 16, 2026) --- Generate images using AI models [Nano Banana 2 Lite / Gemini 3.1 Flash-Lite Image](https://deepmind.google/models/gemini-image/flash-lite/) (Google Flow's default since July 2026), Nano Banana 2.1, and [Nano Banana Pro / Gemini 3 Pro Image](https://deepmind.google/models/gemini-image/pro/) from text prompts with optional reference images. Use any [Google AI](https://one.google.com/ai) subscription or even free account for image generations. This endpoint features dynamic concurrency management, allowing anywhere from 3 to 20 parallel generations depending on real-time capacity. Image generation typically completes within 10-20 seconds. ### Model Capabilities | Parameter | [Nano Banana 2 Lite](https://deepmind.google/models/gemini-image/flash-lite/)<br/>`nano-banana-2-lite` (default) | Nano Banana 2.1<br/>`nano-banana-2` | [Nano Banana Pro](https://deepmind.google/models/gemini-image/pro/)<br/>`nano-banana-pro` | |-----------|:---:|:---:|:---:| | T2I (text-to-image) | Yes | Yes | Yes | | I2I (reference images) | Yes (max 10) | Yes (max 10) | Yes (max 10) | | Aspect ratios | 16:9, 4:3, 1:1, 3:4, 9:16, auto<sup>†</sup> | 16:9, 4:3, 1:1, 3:4, 9:16, auto<sup>†</sup> | 16:9, 4:3, 1:1, 3:4, 9:16, auto<sup>†</sup> | | Default aspect ratio | 16:9 (T2I & I2I) | 16:9 (T2I) / auto (I2I) | 16:9 (T2I) / auto (I2I) | | `count` | Yes (1-4) | Yes (1-4) | Yes (1-4) | | `seed` | Yes | Yes | Yes | | `thinkingLevel` | No | Yes (low, medium, high) | No | | Subscription | all | all | all | <sup>†</sup> `auto` is only valid in image-to-image mode (at least one `reference_*` provided) — the backend derives the aspect ratio from the first reference image. With multiple references the derived orientation is not guaranteed — individual images in the same batch may come back with different orientations, so pass an explicit ratio when you need a consistent output shape. The `nano-banana-2` model generates with Nano Banana 2.1. Deprecated aliases, still accepted: `nano-banana` maps to `nano-banana-2`, and `imagen-4` maps to `nano-banana-2-lite` (Google removed Imagen from Flow in July 2026). ### Content Moderation If your generation is moderated, retrying with the same prompt often succeeds on subsequent attempts — moderation decisions can vary between requests. Alternatively, switching between `nano-banana-2-lite`, `nano-banana-2`, and `nano-banana-pro` models may help, as each has different content-moderation behavior. > **https://api.useapi.net/v1/google-flow/images** ### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Request Body ```json { "prompt": "A serene mountain landscape at sunset with vibrant colors", "model": "nano-banana-2-lite", "aspectRatio": "16:9", "count": 4, "seed": 123456 } ``` - `email` is optional. The email address of the Google Flow account to use. When only one [account](/docs/api-google-flow-v1/get-google-flow-accounts) is configured, the API will automatically use that account. With multiple [accounts](/docs/api-google-flow-v1/get-google-flow-accounts) configured, omitting the email parameter triggers automatic [load balancing](/docs/api-google-flow-v1/get-google-flow-jobs#load-balancing-algorithm) based on **image generation** job statistics to select the healthiest account. If reference images (`reference_1` to `_10`) are provided, the `email` parameter can be omitted—the API will automatically use the same account where the images were uploaded. - `prompt` is **required**, text description for image generation. - `model` is optional, the AI model to use for image generation (default: `nano-banana-2-lite`). Supported values: `nano-banana-2-lite`, `nano-banana-2`, `nano-banana-pro`. Deprecated aliases are still accepted: `nano-banana` maps to `nano-banana-2`, and `imagen-4` maps to `nano-banana-2-lite` (Google removed Imagen from Flow in July 2026). - `aspectRatio` is optional, output image aspect ratio. Supported values: `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `auto`. Legacy aliases `landscape` (→ `16:9`) and `portrait` (→ `9:16`) are still accepted. `auto` is only valid **when at least one `reference_*` is provided** — the backend derives the aspect ratio from the first reference image. With 2+ references the derived orientation can vary between images in the same batch, so prefer an explicit ratio for consistent output. Default: - text-to-image (no references): `16:9` - `nano-banana-2-lite` image-to-image: `16:9` - `nano-banana-2` / `nano-banana-pro` image-to-image: `auto` - `count` is optional, number of image variations to generate (1-4, default: `4`). - `seed` is optional, random seed for reproducible results (integer ≥ 0). - `thinkingLevel` is optional, how long Nano Banana 2.1 reasons before it draws, the same as Flow's Thinking level switch (`nano-banana-2` only). Supported values: `low`, `medium`, `high` (default: `high`). Higher levels follow complex prompts more closely, such as exact text, counts, times on a clock or labelled diagrams, and take longer. In Flow, one image took about 11 s on `low`, 14 s on `medium` and 21 s on `high`. Use `low` for quick drafts. `low` and `medium` need a paid Google AI plan, because Flow offers a free account `high` only, so a free account answers `400` for them before any captcha is used. Any other model answers `400` when `thinkingLevel` is set. - `reference_1` to `reference_10` are optional, use `mediaGenerationId` from [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email) for reference images. All models support up to 10 references. - `character_1` to `character_7` are optional, character reference-ids from [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters). Characters mix freely with `reference_*` — they share the same per-model image-ref budget on Google's side (per-character image counts roll into the total). - `replyUrl` is optional, webhook URL for job status callbacks. Receives POST requests with job status updates (`created`, `completed`, `failed`). The JSON payload shape matches [GET /jobs/`jobId`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid) response. Callbacks timeout after 5 seconds. - `replyRef` is optional, custom reference string passed back in webhook callbacks. Useful for tracking jobs on your end. - `captchaToken`, `captchaRetry`, `captchaOrder` are optional, mutually exclusive captcha parameters. See [Captcha Parameters](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers#captcha-parameters) for details. When `model` is not specified the API uses `nano-banana-2-lite` — it handles both text-to-image and reference-to-image, so the right variant is picked automatically from the presence of `reference_*` / `character_*` parameters. #### Inline `@`-mention markers (optional) You can place `@`-markers inside `prompt` that resolve to the body parameters you supply. Markers are **case-insensitive** and **opt-in** — a prompt with no markers behaves exactly like before. Supported markers: | Marker | Resolves to | |---|---| | `@character_1..7` | matching `character_N` body param | | `@reference_1..10` | matching `reference_N` body param | **Rules:** - Each marker MUST have a matching body slot supplied. Otherwise the API returns **400** with `'character_N' was not provided in the request body`. - A slot referenced inline still goes into the upstream reference array — markers are positional/grounding info, not a replacement for the body params. - Same slot may be inlined multiple times; the upstream reference array de-duplicates by id. - Body params supplied but NOT inlined still flow to the upstream reference array (unchanged behavior). - Unknown strings like `@gmail.com` or `@anyword_1` (no `_<digit>` after a recognized slot name) pass through as literal prompt text. **Example:** ```json { "model": "nano-banana-pro", "prompt": "@character_1 standing next to @reference_1, golden hour light", "character_1": "user:123-email:...-character:...-imgs:1", "reference_1": "user:123-email:...-image:..." } ``` ### Responses **200** **200 OK** Images generated successfully. Returns job ID and media array with generated image data. ```json { "jobId": "j1117123545678193846i-u12345-email:john@gmail.com-bot:google-flow", "media": [ { "name": "…redacted…", "workflowId": "…redacted…", "image": { "generatedImage": { "seed": 123456, "mediaGenerationId": "user:12345…redacted…", "mediaVisibility": "", "prompt": "A serene mountain landscape at sunset with vibrant colors", "modelNameType": "HARBOR_SEAL", "workflowId": "…redacted…", "fifeUrl": "https://flow-content.google/image/…redacted…?Expires=…&KeyName=labs-flow-prod-cdn-key&Signature=…", "aspectRatio": "IMAGE_ASPECT_RATIO_LANDSCAPE", "requestData": { "promptInputs": [ { "textInput": "A serene mountain landscape at sunset with vibrant colors" } ], "imageGenerationRequestData": { "backend": "flow", "referencesApplied": { "media": [], "entities": [] }, "aspectEnum": 3, "modelEnum": 31 } } }, "dimensions": { "width": 1376, "height": 768 } } } ], "captcha": { "service": "AntiCaptcha", "taskId": "540913782", "durationMs": 3500, "attempts": [ { "service": "AntiCaptcha", "taskId": "540913782", "durationMs": 3500, "success": true } ] } } ``` **400** **400 Bad Request** Invalid request (validation error, reference count exceeded, email mismatch, or content policy violation). **General error:** ```json { "error": "Parameter prompt is required", "code": 400 } ``` **Content policy error:** ```json { "jobId": "j1117123545678193846i-u12345-email:john@gmail.com-bot:google-flow", "error": "PUBLIC_ERROR_UNSAFE_GENERATION (HTTP 400)", "code": 400, "response": { "error": { "code": 400, "message": "flow.google.com ogiZ0b failed", "status": "INVALID_ARGUMENT", "details": [ { "@type": "type.googleapis.com/google.rpc.ErrorInfo", "reason": "PUBLIC_ERROR_UNSAFE_GENERATION" } ] }, "captcha": { "service": "CapSolver", "taskId": "14af1dbb-885c-4e25-8121-7a79489dfd0e", "durationMs": 3500, "attempts": [ { "service": "CapSolver", "success": true, "durationMs": 3500, "taskId": "14af1dbb-885c-4e25-8121-7a79489dfd0e" } ] } } } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **402** **402 Payment Required** Subscription expired or insufficient credits. ```json { "error": "useapi.net ⁝ Your account has no subscription, please subscribe to our services before submitting requests", "code": 402 } ``` **403** **403 Forbidden** Google rejected the captcha on every try. We retry with a fresh captcha as many times as you allow (`captchaRetry`, default 5, or the providers in `captchaOrder`) and return this `403` only when all of them were rejected. The top-level `error` starts with `captcha_quality:`, for example `"captcha_quality: PUBLIC_ERROR_UNUSUAL_ACTIVITY after 5 attempts. Google refused all 5 captcha tokens for user@example.com, so nothing was generated and no Google Flow credits were used (5 captcha solves were spent). Google is flagging this account's requests as unusual activity. If it keeps happening, use another account, or leave out email so the API picks one. See GET /accounts/captcha-stats summary.by_account"`. A `429` with `PUBLIC_ERROR_UNUSUAL_ACTIVITY_TOO_MUCH_TRAFFIC` reads the same way. Two `403`s are not a captcha problem, and we answer them after one try instead of retrying. `PUBLIC_ERROR_MODEL_ACCESS_DENIED` in the response means Google refused the model on that account, so raising `captchaRetry` or adding providers will not help. Check that the account's plan includes the model. Since 2026-09-23 Google no longer offers `veo-3.1-lite-low-priority` to invited members of an Ultra $199 family plan — only the family manager's account keeps it. `PUBLIC_ERROR_USER_MINOR` means Google treats the Google account as belonging to someone under 18, and Google Flow is not available to such accounts. The `error` says so in plain words. No captcha or retry changes it: use another Google account, or have this one's age verified with Google first. With `email` omitted, the load balancer sets such an account aside for 1 hour, then tries it again. Nothing was created when this happens. Google checks the captcha before it starts generating, so no Google credits were used and you can resubmit straight away. Your captcha provider still bills each solve. The usual cause is the Google account, not the captcha provider. Google gives each account its own trust level. On a trusted account it accepts about 9 in 10 captchas, on a distrusted one about 3 in 10, whichever provider solved them. Most customers have a few distrusted accounts among many good ones. To see which accounts are affected, use [GET /accounts/captcha-stats](/docs/api-google-flow-v1/get-google-flow-accounts-captcha-stats). Its `summary.by_account` shows, for each of your Google accounts, how many captchas were tried and what share Google accepted. [GET account/stats](/docs/account-management/get-account-stats) with `bot=google-flow` also shows how many requests each account finished with each response code. - If one or a few accounts are far below the others, the API already sends them less work: when you leave out `email`, each captcha Google rejected on an account in the last 15 minutes lowers its chance of being picked, for generations and for image uploads. They still get some work, so an account that recovers gets its full share back. If you pin requests with `email`, move them to your other accounts yourself. Replace an account that stays low for more than a day or two. - If all your accounts drop at the same time, it's the captcha provider. Configure at least two providers with [POST /accounts/captcha-providers](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers), and the API will start with whichever one Google accepts best. A higher `captchaRetry` gets more requests through on a distrusted account, but every extra try is another paid solve. **404** **404 Not Found** Account not found or not configured. ```json { "error": "Google Flow account john@gmail.com not found", "code": 404 } ``` **429** **429 Too Many Requests** Google returns several `RESOURCE_EXHAUSTED` 429 variants. Check the `reason` field and respond accordingly: | Reason | Meaning | Scope | What to do | Cooldown | |--------|---------|-------|------------|----------| | `PUBLIC_ERROR_`<br>`USER_REQUESTS_THROTTLED` | Google is throttling the account (the token was fine). Uploads and generation are metered separately | All models on the account — or uploads only, when POST /assets triggered it | Run fewer parallel requests, or switch accounts. From POST /assets, retrying the same one rarely clears it | ~30 min. From POST /assets, treat it as a minimum — it can persist | | `PUBLIC_ERROR_`<br>`USER_QUOTA_REACHED` | Account's overall Flow quota cap | All models on the account | Add accounts, or omit `email` to load-balance | ~30 min | | `PUBLIC_ERROR_`<br>`PER_MODEL_DAILY_QUOTA_REACHED` | Per-model daily quota | Only that model, on that account | Switch model, or wait | Next UTC midnight | | `PUBLIC_ERROR_`<br>`UNUSUAL_ACTIVITY_TOO_MUCH_TRAFFIC` | Google rejected the captcha on every try (we already retried). Usually a distrusted Google account, sometimes the provider | Per request | Check which accounts are affected in [captcha-stats](/docs/api-google-flow-v1/get-google-flow-accounts-captcha-stats#when-google-rejects-captchas). Rest or replace those accounts. Add a second provider if all accounts drop together | 60s | Every `429` returns the cooldown two ways — an HTTP `Retry-After: <seconds>` header and a body `retryAfter: <ISO timestamp>` field. Honor it before retrying. When `email` is omitted, the first three reasons quarantine the account and the load balancer routes around it. If every account is quarantined for the model you get `429` with `error: "no_eligible_account"`. Routing details: [GET /jobs › Load Balancing Algorithm](/docs/api-google-flow-v1/get-google-flow-jobs#load-balancing-algorithm). Captcha-quality failures prefix the top-level `error` with `captcha_quality:` (e.g. `"captcha_quality: PUBLIC_ERROR_UNUSUAL_ACTIVITY_TOO_MUCH_TRAFFIC after 3 attempts"`) so you can detect them without parsing the nested body. **500** **500 Internal Server Error** One or more generated images were moderated by Google's content policy. Try one of the following: - Switch to a different model — `nano-banana-2-lite`, `nano-banana-2`, and `nano-banana-pro` each have different content-moderation behavior - Modify your prompt or remove/change reference images - Retry the same request (moderation decisions can vary between attempts) ```json { "jobId": "j1117123545678193846i-u12345-email:john@gmail.com-bot:google-flow", "error": "API error: 500", "code": 500, "response": { "error": { "code": 500, "message": "flow.google.com ogiZ0b failed", "status": "INTERNAL", "details": [] }, "captcha": { "service": "CapSolver", "taskId": "14af1dbb-885c-4e25-8121-7a79489dfd0e", "durationMs": 3500, "attempts": [ { "service": "CapSolver", "success": true, "durationMs": 3500, "taskId": "14af1dbb-885c-4e25-8121-7a79489dfd0e" } ] } } } ``` **503** **503 Service Unavailable** `503` has two distinct causes — check the response body to tell them apart. A transient Google-side outage. Wait 5-10 seconds and retry. ```json { "error": { "code": 503, "message": "Service temporarily unavailable.", "status": "UNAVAILABLE" } } ``` A captcha-provider failure — the top-level `error` is prefixed `Captcha service failed:`. The problem is your captcha provider (check its API key and balance), not Google. Don't retry until the provider is back. ```json { "error": "Captcha service failed: ERROR_ZERO_BALANCE", "code": 503 } ``` **596** **596 Session Error** Google rejected the account's session, and the API is re-verifying the account on its own: retry in about a minute. If Google signed the account out, the account keeps answering `596` and you get a reconnect email: add it again by following [Setup Google Flow](/docs/start-here/setup-google-flow). ```json { "error": "Google Flow account john@gmail.com Google rejected this account session (HTTP 401). We are automatically re-verifying it — please retry in about a minute. If the account was signed out, you will receive a reconnect email.", "code": 596 } ``` ### Model The images made, each with a signed link and its `mediaGenerationId`, and the captcha used. <details markdown="block" class="model-details"> <summary>The images, field by field, and the type it uses (<code>FlowCaptcha</code>)</summary> - `jobId` - Unique job identifier (for use with [GET /jobs/`jobId`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid)) - `media` - Array of generated images (1-4 images based on `count`) - `media[].image.generatedImage` - Generated image data object - `generatedImage.fifeUrl` - Direct signed URL to access the generated image (valid for ~6 hours). An empty string when Google's answer had no URL, see [below](#if-fifeurl-is-missing) - `generatedImage.seed` - Seed used for this generation (for reproducibility) - `generatedImage.mediaGenerationId` - mediaGenerationId for use in subsequent API calls - `generatedImage.prompt` - The prompt used for generation - `generatedImage.modelNameType` - Model variant used (`HARBOR_SEAL`, `GEM_PIX_2`, `BELUGA`, `NARWHAL`). `BELUGA` is Nano Banana 2.1. - `generatedImage.aspectRatio` - Generated image aspect ratio (`IMAGE_ASPECT_RATIO_LANDSCAPE`, `IMAGE_ASPECT_RATIO_LANDSCAPE_FOUR_THREE`, `IMAGE_ASPECT_RATIO_SQUARE`, `IMAGE_ASPECT_RATIO_PORTRAIT_THREE_FOUR`, `IMAGE_ASPECT_RATIO_PORTRAIT`, or `IMAGE_ASPECT_RATIO_UNSPECIFIED` for `auto`) - `generatedImage.mediaVisibility` - Always an empty string (Google Flow does not report it for images) - `generatedImage.workflowId` - Unique workflow identifier - `generatedImage.requestData` - What the image was made from: the prompt, and the references Google applied - `media[].image.dimensions` - The image's width and height in pixels - `media[].name` - Internal identifier for the media item - `media[].workflowId` - Unique workflow identifier for this generation - `captcha` - Captcha metadata for debugging/research - `captcha.service` - Provider that returned the successful token - `captcha.taskId` - Task ID from the captcha service - `captcha.durationMs` - Total time for all captcha attempts - `captcha.attempts` - Array of all captcha attempts (including failures) ```typescript { jobId: string // Job identifier media: Array<{ // the images made, up to count name: string // Internal media identifier workflowId: string // Unique workflow ID (an empty string when Google reports none) image: { // the generated image generatedImage: { // the image file and how it was made seed: number // the seed Google used mediaGenerationId: string // Format: user:{userid}-email:{hex}-image:{id} mediaVisibility: '' // always an empty string prompt: string // the prompt as Google ran it modelNameType: string // HARBOR_SEAL, GEM_PIX_2, BELUGA or NARWHAL workflowId: string // same as media[].workflowId fifeUrl: string // Direct signed URL to the generated image, valid ~6 hours. An empty string when Google's answer had none aspectRatio: string // IMAGE_ASPECT_RATIO_LANDSCAPE, IMAGE_ASPECT_RATIO_LANDSCAPE_FOUR_THREE, IMAGE_ASPECT_RATIO_SQUARE, IMAGE_ASPECT_RATIO_PORTRAIT_THREE_FOUR, IMAGE_ASPECT_RATIO_PORTRAIT or IMAGE_ASPECT_RATIO_UNSPECIFIED (auto) requestData: { // what the image was made from promptInputs: Array<{ // the prompt sent to Google textInput: string // the prompt text }> imageGenerationRequestData: { // what Google applied backend: 'flow' // the image was made on `flow.google.com` referencesApplied: { // the references Google echoed back as applied media: string[] // Google's media ids of the reference images applied entities: string[] // the entity ids of the characters applied } aspectEnum: number | null // Google's raw aspect number (3 landscape, 1 square, 2 portrait, 4 3:4, 5 4:3, 0 auto) modelEnum: number | null // Google's raw model number (25 GEM_PIX_2, 29 NARWHAL, 31 HARBOR_SEAL, 36-39 BELUGA) } } } dimensions?: { // the image's size, when Google reports it width: number // width in pixels height: number // height in pixels } } }> captcha: FlowCaptcha // the captcha solved for this request (described below) } ``` When the request fails: ```typescript { jobId?: string // the job id, when the request got as far as Google error: string // what went wrong, e.g. "PUBLIC_ERROR_UNSAFE_GENERATION (HTTP 400)" or "No images generated" code?: number // the HTTP status (left out on "No images generated", a 500) retryAfter?: string // ISO 8601 time to retry after, on a 429 (the Retry-After header carries the same in seconds) response?: { // Google's answer, when Google or the captcha refused the request error?: { // Google's error code: number // HTTP status Google answered message: string // the error message, e.g. "flow.google.com ogiZ0b failed" status: string // Google's status name, e.g. "RESOURCE_EXHAUSTED" details: Array<{ // Google's error details '@type': string // the type name of the detail reason: string // Google's reason code, e.g. "PUBLIC_ERROR_USER_QUOTA_REACHED" }> } captcha: FlowCaptcha // the captcha tried or used } captcha?: FlowCaptcha // on "No images generated" only: the captcha used message?: string // on the load-balancer 429 only (error no_eligible_account: every account is quarantined for this model): the explanation skipReasons?: Array<{ // on the load-balancer 429 only: why each account was left out email: string // the account left out reason: string // Google reason that triggered the quarantine (a 429 reason, or the MODEL_ACCESS_DENIED or USER_MINOR 403) model: string // Quarantined model, or "*" for account-wide }> } ``` The type used above: **`FlowCaptcha`**: the `captcha` in the answer above. ```typescript { service?: string // the provider whose token Google accepted: `CapSolver`, `AntiCaptcha`, // `YesCaptcha`, `CapMonster`, `SolveCaptcha`, `2Captcha`, `EzCaptcha` or // `UserProvided`. Always on a success answer taskId?: string // that provider's task id (none for `UserProvided`) durationMs?: number // ms from the first solve to the token used. Always on a success answer error?: string // why no captcha token could be had, on a failed request attempts: Array<{ // every solve tried, in order, failed ones included service: string // the provider asked taskId?: string // that provider's task id durationMs: number // how long this solve took, in ms success: boolean // true when the provider returned a token (Google may still have refused it) error?: string // why the solve failed userAgent?: string // the browser user agent the provider solved with, when it reports one secChUa?: string // the Sec-CH-UA value the provider solved with, when it reports one (may be empty) cost?: string // the provider's price for this solve, as the provider reports it ip?: string // the IP address the provider reports for this solve createTime?: number // Unix time the provider started the solve, as it reports it endTime?: number // Unix time the provider finished the solve, as it reports it solveCount?: number // the provider's own solve counter for this task }> } ``` </details> ### If `fifeUrl` is missing Once in a while Google's generation response comes back without a URL for an image, and `fifeUrl` is then an empty string. The image itself is unaffected and no credits are lost. Ask for its URL with [GET /assets/`mediaGenerationId`](/docs/api-google-flow-v1/get-google-flow-assets-mediagenerationid), which answers `{ url, mediaGenerationId }`. Every example below already does this, in all three languages. ### Examples **Curl** ``` bash curl -X POST \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A serene mountain landscape at sunset with vibrant colors", "model": "nano-banana-2-lite", "aspectRatio": "16:9", "count": 4, "seed": 123456 }' \ "https://api.useapi.net/v1/google-flow/images" > response.json # Download each image. fifeUrl is normally set; when it is empty, ask # GET /assets/{mediaGenerationId} for the image's URL. for i in 0 1; do IMG=$(jq -r ".media[$i].image.generatedImage" response.json) URL=$(echo "$IMG" | jq -r '.fifeUrl // empty') if [ -z "$URL" ]; then ID=$(echo "$IMG" | jq -r '.mediaGenerationId | @uri') URL=$(curl -s -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v1/google-flow/assets/$ID" | jq -r '.url') fi curl -o "image_$((i+1)).jpg" "$URL" done # Continue for remaining images... ``` **JavaScript** ``` javascript const token = 'YOUR_API_TOKEN'; const apiUrl = 'https://api.useapi.net/v1/google-flow/images'; const response = await fetch(apiUrl, { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ prompt: 'A serene mountain landscape at sunset with vibrant colors', model: 'nano-banana-2-lite', aspectRatio: '16:9', count: 4, seed: 123456 }) }); const result = await response.json(); console.log('Generated images:', result.media.length); // Download and save images for (const [index, item] of result.media.entries()) { const img = item.image.generatedImage; console.log(`Image ${index + 1} seed:`, img.seed); console.log(`mediaGenerationId:`, img.mediaGenerationId); // fifeUrl is normally set. When it is empty, ask GET /assets/{mediaGenerationId} // for the image's URL. const imageUrl = img.fifeUrl || (await (await fetch( `https://api.useapi.net/v1/google-flow/assets/${encodeURIComponent(img.mediaGenerationId)}`, { headers: { 'Authorization': `Bearer ${token}` } })).json()).url; const imageBlob = await (await fetch(imageUrl)).blob(); // In Node.js with fs: // const buffer = Buffer.from(await imageBlob.arrayBuffer()); // require('fs').writeFileSync(`generated_image_${index + 1}.jpg`, buffer); // In browser: create download link or display in <img> element // const url = URL.createObjectURL(imageBlob); // document.querySelector('img').src = url; } ``` **Python** ``` python import requests from urllib.parse import quote token = 'YOUR_API_TOKEN' api_url = 'https://api.useapi.net/v1/google-flow/images' headers = { 'Authorization': f'Bearer {token}', 'Content-Type': 'application/json' } data = { 'prompt': 'A serene mountain landscape at sunset with vibrant colors', 'model': 'nano-banana-2-lite', 'aspectRatio': '16:9', 'count': 4, 'seed': 123456 } response = requests.post(api_url, headers=headers, json=data) result = response.json() print(f"Generated {len(result['media'])} images") # Download and save images for index, item in enumerate(result['media']): img = item['image']['generatedImage'] print(f"Image {index + 1} seed:", img['seed']) print(f"mediaGenerationId:", img['mediaGenerationId']) # fifeUrl is normally set. When it is empty, ask GET /assets/{mediaGenerationId} # for the image's URL. image_url = img.get('fifeUrl') or requests.get( 'https://api.useapi.net/v1/google-flow/assets/' + quote(img['mediaGenerationId'], safe=''), headers={'Authorization': f'Bearer {token}'}).json()['url'] image_response = requests.get(image_url) with open(f'generated_image_{index + 1}.jpg', 'wb') as f: f.write(image_response.content) ``` ### Try It <script> function displayGoogleFlowImages(response, elementId) { const mediaContainer = document.getElementById(`${elementId}-media-links`); if (!mediaContainer) return; mediaContainer.innerHTML = ''; if (!response.media || response.media.length === 0) { mediaContainer.style.display = 'none'; return; } const images = []; response.media.forEach((item, index) => { if (item.image?.generatedImage) { const img = item.image.generatedImage; images.push({ url: img.fifeUrl, seed: img.seed, label: `Image ${index + 1}${img.seed ? ` (seed: ${img.seed})` : ''}` }); } }); if (images.length > 0) { const linksHTML = images.map(img => `<a href="${img.url}" target="_blank" rel="noopener noreferrer" class="media-link image">${img.label}</a>` ).join(' '); mediaContainer.innerHTML = `<div class="media-links-container"><strong>Generated Images:</strong> ${linksHTML}</div>`; mediaContainer.style.display = 'block'; } else { mediaContainer.style.display = 'none'; } } async function apiExecutePostGoogleFlowImages() { const tokenElement = document.getElementById('input-token'); const elementId = 'input'; const payload = {}; const inputs = document.querySelectorAll('.input-query-param'); inputs.forEach(input => { const id = input.id; const value = input.value?.trim(); if (id.startsWith('input-') && value !== '' && value !== undefined) { const key = id.replace('input-', ''); if (key === 'seed' || key === 'count' || key === 'captchaRetry') { payload[key] = parseInt(value); } else { payload[key] = value; } } }); const data = { method: 'POST', headers: { 'Authorization': `Bearer ${tokenElement.value}`, 'Content-Type': 'application/json' }, body: JSON.stringify(payload) }; const mediaLinks = document.getElementById(`${elementId}-media-links`); if (mediaLinks) mediaLinks.style.display = 'none'; const status = await apiExecute('https://api.useapi.net/v1/google-flow/images', elementId, data, { includeTimer: true }); if (status === 200) { try { const content = document.getElementById(`${elementId}-response-json`); const response = JSON.parse(content.innerText); displayGoogleFlowImages(response, elementId); } catch (e) { console.error('Failed to parse response for image display:', e); } } } </script> <form id="input" class="input-form" onsubmit="return false;"> <div class="input-field"> <div class="input-field-row"> <label for="input-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="input-token" type="text" class="input-element" required aria-required="true"> </label> <label for="input-email"><span>email (optional)</span> <input id="input-email" type="text" class="input-element input-query-param" placeholder="john@gmail.com"> </label> <label for="input-prompt"><span>prompt (required)</span> <input id="input-prompt" type="text" class="input-element input-query-param" required aria-required="true" placeholder="A serene mountain landscape"> </label> <label for="input-model"><span>model</span> <select id="input-model" class="input-element input-query-param"> <option value="nano-banana-2-lite">nano-banana-2-lite (default)</option> <option value="nano-banana-2">nano-banana-2 (Nano Banana 2.1)</option> <option value="nano-banana-pro">nano-banana-pro</option> </select> </label> <label for="input-aspectRatio"><span>aspectRatio</span> <select id="input-aspectRatio" class="input-element input-query-param"> <option value="">(default — auto for nano-banana-2/pro image-to-image, otherwise 16:9)</option> <option value="16:9">16:9</option> <option value="4:3">4:3</option> <option value="1:1">1:1</option> <option value="3:4">3:4</option> <option value="9:16">9:16</option> <option value="auto">auto (image-to-image only)</option> </select> </label> <label for="input-count"><span>count</span> <input id="input-count" type="number" class="input-element input-query-param" min="1" max="4" placeholder="4"> </label> <label for="input-seed"><span>seed</span> <input id="input-seed" type="number" class="input-element input-query-param" min="0" placeholder="(random)"> </label> <label for="input-thinkingLevel"><span>thinkingLevel (nano-banana-2 only)</span> <select id="input-thinkingLevel" class="input-element input-query-param"> <option value="">(default — high)</option> <option value="low">low</option> <option value="medium">medium</option> <option value="high">high</option> </select> </label> <label for="input-reference_1"><span>reference_1 (optional, from <a href="/docs/api-google-flow-v1/post-google-flow-assets-email">POST /assets/email</a>)</span> <input id="input-reference_1" type="text" class="input-element input-query-param" placeholder="user:123-email:..."> </label> <label for="input-reference_2"><span>reference_2</span> <input id="input-reference_2" type="text" class="input-element input-query-param" placeholder="user:123-email:..."> </label> <label for="input-reference_3"><span>reference_3</span> <input id="input-reference_3" type="text" class="input-element input-query-param" placeholder="user:123-email:..."> </label> <label for="input-reference_4"><span>reference_4</span> <input id="input-reference_4" type="text" class="input-element input-query-param" placeholder="user:123-email:..."> </label> <label for="input-reference_5"><span>reference_5</span> <input id="input-reference_5" type="text" class="input-element input-query-param" placeholder="user:123-email:..."> </label> <label for="input-reference_6"><span>reference_6</span> <input id="input-reference_6" type="text" class="input-element input-query-param" placeholder="user:123-email:..."> </label> <label for="input-reference_7"><span>reference_7</span> <input id="input-reference_7" type="text" class="input-element input-query-param" placeholder="user:123-email:..."> </label> <label for="input-reference_8"><span>reference_8</span> <input id="input-reference_8" type="text" class="input-element input-query-param" placeholder="user:123-email:..."> </label> <label for="input-reference_9"><span>reference_9</span> <input id="input-reference_9" type="text" class="input-element input-query-param" placeholder="user:123-email:..."> </label> <label for="input-reference_10"><span>reference_10</span> <input id="input-reference_10" type="text" class="input-element input-query-param" placeholder="user:123-email:..."> </label> <label for="input-character_1"><span>character_1 (optional, ref from <a href="/docs/api-google-flow-v1/post-google-flow-characters">POST /characters</a>)</span> <input id="input-character_1" type="text" class="input-element input-query-param" placeholder="user:123-email:...-character:...-imgs:N"> </label> <label for="input-character_2"><span>character_2</span> <input id="input-character_2" type="text" class="input-element input-query-param" placeholder="user:123-email:...-character:...-imgs:N"> </label> <label for="input-character_3"><span>character_3</span> <input id="input-character_3" type="text" class="input-element input-query-param" placeholder="user:123-email:...-character:...-imgs:N"> </label> <label for="input-character_4"><span>character_4</span> <input id="input-character_4" type="text" class="input-element input-query-param" placeholder="user:123-email:...-character:...-imgs:N"> </label> <label for="input-character_5"><span>character_5</span> <input id="input-character_5" type="text" class="input-element input-query-param" placeholder="user:123-email:...-character:...-imgs:N"> </label> <label for="input-character_6"><span>character_6</span> <input id="input-character_6" type="text" class="input-element input-query-param" placeholder="user:123-email:...-character:...-imgs:N"> </label> <label for="input-character_7"><span>character_7</span> <input id="input-character_7" type="text" class="input-element input-query-param" placeholder="user:123-email:...-character:...-imgs:N"> </label> <label for="input-replyUrl"><span>replyUrl (webhook URL)</span> <input id="input-replyUrl" type="text" class="input-element input-query-param" placeholder="https://your-domain.com/webhook"> </label> <label for="input-replyRef"><span>replyRef (custom reference)</span> <input id="input-replyRef" type="text" class="input-element input-query-param" placeholder="my-custom-id-123"> </label> <label for="input-captchaToken"><span>captchaToken (optional, your own reCAPTCHA token)</span> <input id="input-captchaToken" type="text" class="input-element input-query-param" placeholder="reCAPTCHA v3 Enterprise token"> </label> <label for="input-captchaRetry"><span>captchaRetry (1-10, optional)</span> <input id="input-captchaRetry" type="number" class="input-element input-query-param" min="1" max="10" placeholder="5"> </label> <label for="input-captchaOrder"><span>captchaOrder (optional)</span> <input id="input-captchaOrder" type="text" class="input-element input-query-param" placeholder="CapSolver,AntiCaptcha"> </label> </div> <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecutePostGoogleFlowImages()">Go</button> </div> </form> <div id="input-media-links" style="display:none;"></div> <div id="input-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos-concatenate === Document URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos-concatenate --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/concatenate description: "Merge up to 10 Google Flow videos into one clip via POST videos/concatenate in the useapi.net Google Flow API v1 — no captcha required, with optional per-clip trim." parent: Google Flow API nav_order: 740 --- ## Concatenate Videos January 29, 2026 (November 16, 2026) --- Concatenate multiple previously generated videos into a single video. This is a synchronous operation that returns base64-encoded video data. - Combines 2-10 videos into a single video file. - Each clip contributes its full recorded length: 8 seconds for a standard Veo clip, 4 or 6 seconds for the short Veo durations, up to 10 seconds for an Omni 1.1 Flash clip, up to 15 seconds for an Omni 1.2 Flash clip, and just under 40 seconds for an Omni 1.2 Flash extension. Earlier versions cut every clip at 8 seconds, which silently dropped the last 2 seconds of each 10-second Omni clip. - All videos must have the same aspect ratio (all landscape or all portrait). - No captcha required - this endpoint doesn't require reCAPTCHA solving. - Joining videos costs no Google Flow credits: the account's credit balance read the same before and after a concatenation (measured September 18, 2026). - Optional trimming allows removing frames from the start/end of each video for smoother transitions. - Returns large base64-encoded video data (~7MB per input video). - Concatenation typically completes within 15-25 seconds, occasionally up to about a minute when Google's first export fails and has to be restarted. - Google's export sometimes fails outright. When it does, this endpoint answers `408` in well under a minute rather than waiting out the full timeout, and retrying the same request is free — it costs no credits. > **https://api.useapi.net/v1/google-flow/videos/concatenate** ### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Request Body ```json { "media": [ { "mediaGenerationId": "user:12345-email:6a6f...-video:CAMaJDMx..." }, { "mediaGenerationId": "user:12345-email:6a6f...-video:CAMaJDMy...", "trimStart": 0.5 }, { "mediaGenerationId": "user:12345-email:6a6f...-video:CAMaJDMz...", "trimEnd": 1 } ] } ``` - `media` is **required**. Array of 2-10 video references to concatenate. Each item contains: - `mediaGenerationId` is **required**. The `mediaGenerationId` from a previously generated or extended video. - `trimStart` is optional. Seconds to trim from the start of this video (0-60, default: 0). When joining a Veo extension to its source, use `trimStart: 1` to remove the ~1 second overlap. An Omni 1.2 Flash extension already holds its source, so it needs no join. - `trimEnd` is optional. Seconds to trim from the end of this video (0-60, default: 0). - `trimStart` plus `trimEnd` must be less than the clip's own length, otherwise the request returns `400`. - Clips from [POST /videos/upscale](/docs/api-google-flow-v1/post-google-flow-videos-upscale) can be joined too, and the output keeps their resolution. Google records no length on an upscaled clip, so its length is taken from the clip it was upscaled from. **Notes:** - All videos must belong to the same Google Flow account (same email). - All videos must have the same aspect ratio. - Videos are concatenated in the order provided. - Omni 1.1 Flash edits chained from one source all re-render the same time window, so joining them repeats the source motion with each edit applied. See the [video reference notes](/docs/api-google-flow-v1/post-google-flow-videos#video-reference-omni-11-flash-v2v-edit) on POST /videos. ### Responses **200** **200 OK** Videos concatenated successfully. Returns job ID and base64-encoded video data. ```json { "jobId": "j1115124012345270981v-u12345-email:john@gmail.com-bot:google-flow", "status": "MEDIA_GENERATION_STATUS_SUCCESSFUL", "inputsCount": 3, "encodedVideo": "AAAAIGZ0eXBpc29t...~21MB base64...", "backend": "flow" } ``` **400** **400 Bad Request** Invalid request. ```json { "error": "Parameter media must have at least 2 videos", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **402** **402 Payment Required** Your useapi.net subscription is missing or has expired, so nothing was sent to Google. [Subscribe or renew it](/docs/subscription), then send the request again. ```json { "error": "useapi.net ⁝ Your account has no subscription, please subscribe to our services before submitting requests", "code": 402 } ``` When the subscription has expired: ```json { "error": "useapi.net ⁝ Monthly subscription 261008 expired, please renew your subscription before submitting new requests.", "code": 402 } ``` **404** **404 Not Found** Account not found or video not found. ```json { "error": "Google Flow account john@gmail.com not found", "code": 404 } ``` **408** **408 Request Timeout** Concatenation polling timeout (after 3 minutes). ```json { "error": "Polling timeout", "code": 408 } ``` **503** **503 Service Unavailable** Google Flow could not be reached for this request, so nothing was made. Retry shortly. If Google signed the account out, the API re-verifies it on its own and the account answers `596` meanwhile. ```json { "error": { "code": 503, "message": "flow.google.com unavailable for this request — retry", "status": "UNAVAILABLE", "details": [] } } ``` **596** **596 Session Error** Google rejected the account's session, and the API is re-verifying the account on its own: retry in about a minute. If Google signed the account out, the account keeps answering `596` and you get a reconnect email: add it again by following [Setup Google Flow](/docs/start-here/setup-google-flow). ```json { "error": "Google Flow account john@gmail.com Google rejected this account session (HTTP 401). We are automatically re-verifying it — please retry in about a minute. If the account was signed out, you will receive a reconnect email.", "code": 596 } ``` ### Model The joined video as Base64 MP4 data, with the job id and the number of input videos. <details markdown="block" class="model-details"> <summary>The joined video, field by field</summary> ```typescript { jobId: string // the job id status: 'MEDIA_GENERATION_STATUS_SUCCESSFUL' // always this value on a 200 inputsCount: number // number of input videos encodedVideo: string // Base64-encoded MP4 (~7MB per input, decode and save as .mp4) backend: 'flow' // the video was joined on `flow.google.com` } ``` When the request fails: ```typescript { jobId?: string // the job id, when the job had been created error: string | { // what went wrong, e.g. "Concatenation failed" or "Polling timeout", or Google's error object when the request failed before the job was created code: number // HTTP status Google answered, e.g. 503 message: string // the error message status: string // Google's status name, e.g. "UNAVAILABLE" details: Array<{ // Google's error details '@type': string // the type name of the detail reason: string // Google's reason code }> } code?: number // the HTTP status, with our own text response?: { // what Google answered, when the job had been created error?: string | { // Google's error when Google refused the request, or our own text (a polling timeout) code: number // HTTP status Google answered message: string // the error message status: string // Google's status name, e.g. "INTERNAL" details: Array<{ // Google's error details '@type': string // the type name of the detail reason: string // Google's reason code }> } head?: unknown[] // Google's raw status record of a failed export ("Concatenation failed") backend?: 'flow' // with head: the video was joined on `flow.google.com` } } ``` </details> ### Examples **Curl** ``` bash # Generate first video curl -X POST \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"prompt": "A serene mountain landscape at sunrise"}' \ "https://api.useapi.net/v1/google-flow/videos" > video1.json # Generate second video (or extend the first) curl -X POST \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"prompt": "The sun rises higher, birds fly across the sky"}' \ "https://api.useapi.net/v1/google-flow/videos" > video2.json # Extract mediaGenerationIds VIDEO1_ID=$(jq -r '.media[0].mediaGenerationId' video1.json) VIDEO2_ID=$(jq -r '.media[0].mediaGenerationId' video2.json) # Concatenate videos curl -X POST \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d "{\"media\": [{\"mediaGenerationId\": \"$VIDEO1_ID\"}, {\"mediaGenerationId\": \"$VIDEO2_ID\", \"trimStart\": 0.5}]}" \ "https://api.useapi.net/v1/google-flow/videos/concatenate" > concat.json # Decode base64 and save as MP4 jq -r '.encodedVideo' concat.json | base64 -d > concatenated_video.mp4 ``` **JavaScript** ``` javascript const token = 'YOUR_API_TOKEN'; // Assume you have two video mediaGenerationIds const videoId1 = 'user:12345-email:6a6f...-video:CAMaJDMx...'; const videoId2 = 'user:12345-email:6a6f...-video:CAMaJDMy...'; // Concatenate videos const concatResponse = await fetch('https://api.useapi.net/v1/google-flow/videos/concatenate', { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ media: [ { mediaGenerationId: videoId1 }, { mediaGenerationId: videoId2, trimStart: 0.5 } // Trim 0.5s from start for smooth transition ] }) }); const result = await concatResponse.json(); // Decode base64 and save (Node.js) const buffer = Buffer.from(result.encodedVideo, 'base64'); require('fs').writeFileSync('concatenated_video.mp4', buffer); console.log('Concatenated video saved!'); // Or use in browser as data URL for preview const dataUrl = `data:video/mp4;base64,${result.encodedVideo}`; document.getElementById('video-player').src = dataUrl; ``` **Python** ``` python import requests import base64 token = 'YOUR_API_TOKEN' headers = { 'Authorization': f'Bearer {token}', 'Content-Type': 'application/json' } # Assume you have two video mediaGenerationIds video_id_1 = 'user:12345-email:6a6f...-video:CAMaJDMx...' video_id_2 = 'user:12345-email:6a6f...-video:CAMaJDMy...' # Concatenate videos concat_response = requests.post( 'https://api.useapi.net/v1/google-flow/videos/concatenate', headers=headers, json={ 'media': [ {'mediaGenerationId': video_id_1}, {'mediaGenerationId': video_id_2, 'trimStart': 0.5} # Trim 0.5s for smooth transition ] } ) result = concat_response.json() # Decode base64 and save video_data = base64.b64decode(result['encodedVideo']) with open('concatenated_video.mp4', 'wb') as f: f.write(video_data) print(f'Concatenated video saved! ({len(video_data)} bytes)') ``` ### Try It <script> function displayConcatenatedVideo(response, elementId) { const mediaContainer = document.getElementById(`${elementId}-media-links`); if (!mediaContainer) return; mediaContainer.innerHTML = ''; if (!response.encodedVideo) { mediaContainer.style.display = 'none'; return; } const dataUrl = `data:video/mp4;base64,${response.encodedVideo}`; const downloadLink = document.createElement('a'); downloadLink.href = dataUrl; downloadLink.download = 'concatenated_video.mp4'; downloadLink.className = 'media-link video'; downloadLink.textContent = 'Download Concatenated Video'; const container = document.createElement('div'); container.className = 'media-links-container'; container.innerHTML = '<strong>Concatenated Video:</strong> '; container.appendChild(downloadLink); mediaContainer.appendChild(container); mediaContainer.style.display = 'block'; } async function apiExecutePostGoogleFlowVideosConcatenate() { const tokenElement = document.getElementById('input-token'); const elementId = 'input'; const media = []; for (let i = 1; i <= 5; i++) { const idInput = document.getElementById(`input-mediaGenerationId-${i}`); const trimStartInput = document.getElementById(`input-trimStart-${i}`); const trimEndInput = document.getElementById(`input-trimEnd-${i}`); if (idInput && idInput.value?.trim()) { const item = { mediaGenerationId: idInput.value.trim() }; if (trimStartInput && trimStartInput.value) { item.trimStart = parseFloat(trimStartInput.value); } if (trimEndInput && trimEndInput.value) { item.trimEnd = parseFloat(trimEndInput.value); } media.push(item); } } const payload = { media }; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${tokenElement.value}`, 'Content-Type': 'application/json' }, body: JSON.stringify(payload) }; const mediaLinks = document.getElementById(`${elementId}-media-links`); if (mediaLinks) mediaLinks.style.display = 'none'; const status = await apiExecute('https://api.useapi.net/v1/google-flow/videos/concatenate', elementId, data, { includeTimer: true }); if (status === 200) { try { const content = document.getElementById(`${elementId}-response-json`); const response = JSON.parse(content.innerText); displayConcatenatedVideo(response, elementId); if (response.encodedVideo) { const trimmed = { ...response, encodedVideo: response.encodedVideo.slice(0, 50) + '...' }; content.innerText = JSON.stringify(trimmed, null, 2); } } catch (e) { console.error('Failed to parse response for video display:', e); } } } </script> <form id="input" class="input-form" onsubmit="return false;"> <div class="input-field"> <div class="input-field-row"> <label for="input-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="input-token" type="text" class="input-element" required aria-required="true"> </label> <label for="input-mediaGenerationId-1"><span>Video 1 mediaGenerationId (required)</span> <input id="input-mediaGenerationId-1" type="text" class="input-element" required aria-required="true" placeholder="user:123-email:...-video:..."> </label> <div style="display: flex; gap: 10px;"> <label for="input-trimStart-1" style="flex:1;"><span>trimStart (seconds)</span> <input id="input-trimStart-1" type="number" class="input-element" min="0" max="60" step="0.1" placeholder="0"> </label> <label for="input-trimEnd-1" style="flex:1;"><span>trimEnd (seconds)</span> <input id="input-trimEnd-1" type="number" class="input-element" min="0" max="60" step="0.1" placeholder="0"> </label> </div> <label for="input-mediaGenerationId-2"><span>Video 2 mediaGenerationId (required)</span> <input id="input-mediaGenerationId-2" type="text" class="input-element" required aria-required="true" placeholder="user:123-email:...-video:..."> </label> <div style="display: flex; gap: 10px;"> <label for="input-trimStart-2" style="flex:1;"><span>trimStart (seconds)</span> <input id="input-trimStart-2" type="number" class="input-element" min="0" max="60" step="0.1" placeholder="0"> </label> <label for="input-trimEnd-2" style="flex:1;"><span>trimEnd (seconds)</span> <input id="input-trimEnd-2" type="number" class="input-element" min="0" max="60" step="0.1" placeholder="0"> </label> </div> <label for="input-mediaGenerationId-3"><span>Video 3 mediaGenerationId (optional)</span> <input id="input-mediaGenerationId-3" type="text" class="input-element" placeholder="user:123-email:...-video:..."> </label> <div style="display: flex; gap: 10px;"> <label for="input-trimStart-3" style="flex:1;"><span>trimStart (seconds)</span> <input id="input-trimStart-3" type="number" class="input-element" min="0" max="60" step="0.1" placeholder="0"> </label> <label for="input-trimEnd-3" style="flex:1;"><span>trimEnd (seconds)</span> <input id="input-trimEnd-3" type="number" class="input-element" min="0" max="60" step="0.1" placeholder="0"> </label> </div> <label for="input-mediaGenerationId-4"><span>Video 4 mediaGenerationId (optional)</span> <input id="input-mediaGenerationId-4" type="text" class="input-element" placeholder="user:123-email:...-video:..."> </label> <div style="display: flex; gap: 10px;"> <label for="input-trimStart-4" style="flex:1;"><span>trimStart (seconds)</span> <input id="input-trimStart-4" type="number" class="input-element" min="0" max="60" step="0.1" placeholder="0"> </label> <label for="input-trimEnd-4" style="flex:1;"><span>trimEnd (seconds)</span> <input id="input-trimEnd-4" type="number" class="input-element" min="0" max="60" step="0.1" placeholder="0"> </label> </div> <label for="input-mediaGenerationId-5"><span>Video 5 mediaGenerationId (optional)</span> <input id="input-mediaGenerationId-5" type="text" class="input-element" placeholder="user:123-email:...-video:..."> </label> <div style="display: flex; gap: 10px;"> <label for="input-trimStart-5" style="flex:1;"><span>trimStart (seconds)</span> <input id="input-trimStart-5" type="number" class="input-element" min="0" max="60" step="0.1" placeholder="0"> </label> <label for="input-trimEnd-5" style="flex:1;"><span>trimEnd (seconds)</span> <input id="input-trimEnd-5" type="number" class="input-element" min="0" max="60" step="0.1" placeholder="0"> </label> </div> </div> <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecutePostGoogleFlowVideosConcatenate()">Go</button> </div> </form> <div id="input-media-links" style="display:none;"></div> <div id="input-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos-extend === Document URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos-extend --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/extend description: "Extend a Google Flow video by 3 to 10 seconds at a time with Omni 1.2 Flash via POST videos/extend in the useapi.net Google Flow API v1 — one continuous clip with image, character and voice references." parent: Google Flow API nav_order: 730 --- ## Extend Videos January 29, 2026 (November 20, 2026) --- Extend a video with a new prompt: Omni 1.2 Flash continues the clip by 3 to 10 seconds and returns one clip that holds the whole source plus the new seconds. Extend the result again to keep going. - Extending requires a paid [Google AI](https://one.google.com/ai) plan (Plus, Pro or Ultra) with remaining credits. A free Google account gets `400`: Google Flow doesn't extend videos on the free plan. - Omni 1.2 Flash extends any video shorter than 30 seconds: one generated with any model (Veo included), uploaded, or already extended. A video of 30 seconds or more gets `400`, so the longest result is just under 40 seconds. - The extension keeps the source's aspect ratio (landscape or portrait). Its resolution is the source's own unless you set `resolution`. - It costs the same as an Omni 1.2 Flash generation of the added length, on every plan: at 720p 3 credits a second (10 s = 30), at 360p 1 credit a second (3 s = 3). - Images, characters and voices can steer the extension, including a voice for new dialogue (see [Request Body](#request-body)). - Google is giving Omni 1.2 Flash to accounts over several days from November 5, 2026. On an account that doesn't have it yet the request returns `400`. Google removed the Veo models from Flow's Extend on November 18, 2026. A request with a Veo `model` (`veo-3.1-fast`, `veo-3.1-quality`, `veo-3.1-lite` or `veo-3.1-lite-low-priority`) returns `400` right away and nothing is charged. Leave `model` out, or set it to `omni-flash-1.2`. > **https://api.useapi.net/v1/google-flow/videos/extend** ### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Request Body ```json { "mediaGenerationId": "user:12345-email:6a6f...-video:CAMaJDMx...", "prompt": "The magician runs after the glowing card through the rain, calling out @referenceAudio_1: \"Come back here! You are the ace of hearts!\"", "duration": 10, "referenceAudio_1": "Charon" } ``` - `mediaGenerationId` is **required**. The `mediaGenerationId` of a video: one from [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) (any model), from this endpoint, or uploaded via [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email). The video must be shorter than 30 seconds. The extension runs on the account that holds it. - `prompt` is **required**. What happens next. It can name the references inline with `@referenceImage_1..3`, `@character_1..3` and `@referenceAudio_1..3`, the same [inline markers](/docs/api-google-flow-v1/post-google-flow-videos#inline--mention-markers-optional) as POST /videos. - `model` is optional (default: `omni-flash-1.2`), the only model that extends. A Veo model (`veo-3.1-fast`, `veo-3.1-quality`, `veo-3.1-lite`, `veo-3.1-lite-low-priority`) returns `400`: Google no longer extends with them. - `duration` is optional, the seconds to add: any whole number from `3` to `10` (default: `8`). - `resolution` is optional, `360p` or `720p` (default: the source's resolution). 360p costs a third of 720p. - `referenceImage_1` to `referenceImage_3` are optional, mediaGenerationId of images from [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email) on the same account. - `character_1` to `character_3` are optional, characters from [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters). Each character's images count toward the same limit of 3 images. - `referenceAudio_1` to `referenceAudio_3` are optional, voices for new dialogue: a system voice name (one of the 30 presets listed on [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos#voice-narration)) or a user voice from [POST /voices](/docs/api-google-flow-v1/post-google-flow-voices). - `count` is optional. Number of variations to generate (1-4, default: 1). Each variation is a separate video: a full clip of the source plus its own extension. - `returnSilentVideos` is optional (default: `false`). When Google's audio filter rejects the sound generated with the extension, `false` fails the video with `PUBLIC_ERROR_AUDIO_FILTERED` and Google charges nothing for it, and `true` returns it without sound, charged like any other video. Details in [Videos that failed on their sound](/docs/api-google-flow-v1/post-google-flow-videos#videos-that-failed-on-their-sound). - `async` is optional, enables fire-and-forget mode (default: `false`). When `true`, returns immediately with `201 Created` and job metadata. Poll [GET /jobs/`jobId`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid) for completion status. - `replyUrl` is optional, webhook URL for job status callbacks. Receives POST requests with job status updates (`created`, `started`, `completed`, `failed`). The JSON payload shape matches [GET /jobs/`jobId`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid) response. - `replyRef` is optional, custom reference string passed back in webhook callbacks. - `captchaToken`, `captchaRetry`, `captchaOrder` are optional, mutually exclusive captcha parameters. See [Captcha Parameters](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers#captcha-parameters) for details. ### Responses **200** **200 OK** Video extended successfully. All video data is in the `media[]` array. With `omni-flash-1.2` each item is one clip of the source plus the extension: in this example a 10 s clip extended by 10 s, so `length` is `20s`. ```json { "jobId": "j1115123456789539281v-u12345-email:john@gmail.com-bot:google-flow", "media": [ { "name": "a1d95d21-75d2-482d-a354-14ef8802ce66", "projectId": "9f63078c-...redacted...", "workflowId": "fa986834-...redacted...", "workflowStepId": "CAE", "mediaMetadata": { "createTime": "2026-11-06T02:13:29.851988Z", "mediaTitle": "The magician runs after the glowing card through the rain, calling out VoiceI: \"Come back here! You are the ace of hearts!\"", "mediaBlobSize": "10618058", "mediaStatus": { "mediaGenerationStatus": "MEDIA_GENERATION_STATUS_SUCCESSFUL" }, "visibility": "PRIVATE", "requestData": { "videoGenerationRequestData": { "backend": "flow", "statusEnum": 3, "aspectEnum": 2, "videoModelControlInput": { "videoModelName": "models/omni_1p5_pro_flow", "videoGenerationMode": "VIDEO_GENERATION_MODE_VIDEO_EXTENSION", "videoAspectRatio": "VIDEO_ASPECT_RATIO_LANDSCAPE", "videoResolution": "VIDEO_RESOLUTION_720P" } }, "promptInputs": [ { "structuredPrompt": { "parts": [ { "text": "The magician runs after the glowing card through the rain, calling out " }, { "reference": { "audio": { "mediaId": "5b0e2c1d-...redacted...", "handle": "VoiceI" } } }, { "text": ": \"Come back here! You are the ace of hearts!\"" } ] } } ], "clientPlatform": "CLIENT_PLATFORM_WEB" } }, "video": { "generatedVideo": { "seed": 267051, "prompt": "The magician runs after the glowing card through the rain, calling out audio_0.wav : \"Come back here! You are the ace of hearts!\"", "model": "macaron_cookie_extend_10s", "baseImageMediaGenerationId": "", "isLooped": false, "aspectRatio": "VIDEO_ASPECT_RATIO_LANDSCAPE" }, "dimensions": { "length": "20s" }, "operation": { "name": "a1d95d21-...redacted..." } }, "mediaGenerationId": "user:12345-email:6a6f...-video:a1d95d21-...redacted...", "videoUrl": "https://flow-content.google/video/a1d95d21-...redacted...?Expires=...", "thumbnailUrl": "https://flow-content.google/image/a1d95d21-...redacted...?Expires=..." } ], "operations": [], "remainingCredits": 847, "captcha": { "service": "AntiCaptcha", "taskId": "931846120", "durationMs": 15243, "attempts": [ { "service": "AntiCaptcha", "success": true, "durationMs": 15243, "cost": "0.00200", "ip": "203.0.113.24", "createTime": 1794787642, "endTime": 1794787657, "solveCount": 0, "taskId": "931846120", "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/153.0.0.0 Safari/537.36" } ] } } ``` **201** **201 Created** Job created in async mode (`async: true`). Video extension is processing in the background. Use [GET /jobs/`jobId`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid) to poll for completion status. ```json { "jobid": "j1115123456789539281v-u12345-email:john@gmail.com-bot:google-flow", "type": "video", "status": "created", "created": "2026-11-15T12:34:56.789Z", "request": { "prompt": "The camera rises above the mountains as the sun sets behind them", "mediaGenerationId": { "user": 12345, "email": "john@gmail.com", "type": "video", "id": "a1d95d21-75d2-482d-a354-14ef8802ce66", "referenceId": "user:12345-email:6a6f...-video:a1d95d21-75d2-482d-a354-14ef8802ce66" }, "async": true, "email": "john@gmail.com" }, "response": { "operations": [], "media": [ { "name": "d83b61f0-...redacted...", "projectId": "9f63078c-...redacted...", "workflowId": "fa986834-...redacted...", "workflowStepId": "CAI", "mediaMetadata": { "createTime": "2026-11-15T12:35:01.053004Z", "mediaTitle": "The camera rises above the mountains as the sun sets behind them", "mediaStatus": { "mediaGenerationStatus": "MEDIA_GENERATION_STATUS_PENDING" }, "visibility": "PRIVATE", "requestData": { "videoGenerationRequestData": { "backend": "flow", "statusEnum": 6, "aspectEnum": 2, "videoModelControlInput": { "videoModelName": "models/omni_1p5_pro_flow", "videoGenerationMode": "VIDEO_GENERATION_MODE_VIDEO_EXTENSION", "videoAspectRatio": "VIDEO_ASPECT_RATIO_LANDSCAPE", "videoResolution": "VIDEO_RESOLUTION_720P" } }, "promptInputs": [ { "structuredPrompt": { "parts": [{ "text": "The camera rises above the mountains as the sun sets behind them" }] } } ], "clientPlatform": "CLIENT_PLATFORM_WEB" } }, "video": { "generatedVideo": { "seed": 267051, "prompt": "The camera rises above the mountains as the sun sets behind them", "model": "macaron_cookie_extend_8s", "baseImageMediaGenerationId": "", "isLooped": false, "aspectRatio": "VIDEO_ASPECT_RATIO_LANDSCAPE" }, "dimensions": { "length": "16s" }, "operation": { "name": "d83b61f0-...redacted..." } } } ], "captcha": { "service": "CapSolver", "taskId": "14af1dbb-885c-4e25-8121-7a79489dfd0e", "durationMs": 5357, "attempts": [ { "service": "CapSolver", "success": true, "durationMs": 5357, "taskId": "14af1dbb-885c-4e25-8121-7a79489dfd0e" } ] }, "captchaAttemptsCount": 1, "captchaProviders": "CapSolver", "tier": "PAYGATE_TIER_TWO", "sku": "G1_TIER2", "remainingCredits": 847 } } ``` **400** **400 Bad Request** Invalid request. ```json { "error": "Parameter prompt is required", "code": 400 } ``` A Veo `model`, which Google no longer extends with: ```json { "error": "Google Flow no longer extends videos with Veo models: Google removed Veo video extension on 2026-11-18. Extend with model 'omni-flash-1.2' (the default), available on paid Google Flow plans (Plus, Pro or Ultra).", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **402** **402 Payment Required** Your useapi.net subscription is missing or has expired, so nothing was sent to Google. [Subscribe or renew it](/docs/subscription), then send the request again. ```json { "error": "useapi.net ⁝ Your account has no subscription, please subscribe to our services before submitting requests", "code": 402 } ``` When the subscription has expired: ```json { "error": "useapi.net ⁝ Monthly subscription 261008 expired, please renew your subscription before submitting new requests.", "code": 402 } ``` **403** **403 Forbidden** Google rejected the captcha on every try. We retry with a fresh captcha as many times as you allow (`captchaRetry`, default 5, or the providers in `captchaOrder`) and return this `403` only when all of them were rejected. The top-level `error` starts with `captcha_quality:`, for example `"captcha_quality: PUBLIC_ERROR_UNUSUAL_ACTIVITY after 5 attempts. Google refused all 5 captcha tokens for user@example.com, so nothing was generated and no Google Flow credits were used (5 captcha solves were spent). Google is flagging this account's requests as unusual activity. If it keeps happening, use another account, or leave out email so the API picks one. See GET /accounts/captcha-stats summary.by_account"`. A `429` with `PUBLIC_ERROR_UNUSUAL_ACTIVITY_TOO_MUCH_TRAFFIC` reads the same way. Two `403`s are not a captcha problem, and we answer them after one try instead of retrying. `PUBLIC_ERROR_MODEL_ACCESS_DENIED` in the response means Google refused the model on that account, so raising `captchaRetry` or adding providers will not help. Check that the account's plan includes the model. Since 2026-09-23 Google no longer offers `veo-3.1-lite-low-priority` to invited members of an Ultra $199 family plan — only the family manager's account keeps it. `PUBLIC_ERROR_USER_MINOR` means Google treats the Google account as belonging to someone under 18, and Google Flow is not available to such accounts. The `error` says so in plain words. No captcha or retry changes it: use another Google account, or have this one's age verified with Google first. With `email` omitted, the load balancer sets such an account aside for 1 hour, then tries it again. Nothing was created when this happens. Google checks the captcha before it starts generating, so no Google credits were used and you can resubmit straight away. Your captcha provider still bills each solve. The usual cause is the Google account, not the captcha provider. Google gives each account its own trust level. On a trusted account it accepts about 9 in 10 captchas, on a distrusted one about 3 in 10, whichever provider solved them. Most customers have a few distrusted accounts among many good ones. To see which accounts are affected, use [GET /accounts/captcha-stats](/docs/api-google-flow-v1/get-google-flow-accounts-captcha-stats). Its `summary.by_account` shows, for each of your Google accounts, how many captchas were tried and what share Google accepted. [GET account/stats](/docs/account-management/get-account-stats) with `bot=google-flow` also shows how many requests each account finished with each response code. - If one or a few accounts are far below the others, the API already sends them less work: when you leave out `email`, each captcha Google rejected on an account in the last 15 minutes lowers its chance of being picked, for generations and for image uploads. They still get some work, so an account that recovers gets its full share back. If you pin requests with `email`, move them to your other accounts yourself. Replace an account that stays low for more than a day or two. - If all your accounts drop at the same time, it's the captcha provider. Configure at least two providers with [POST /accounts/captcha-providers](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers), and the API will start with whichever one Google accepts best. A higher `captchaRetry` gets more requests through on a distrusted account, but every extra try is another paid solve. **404** **404 Not Found** Account not found or video not found. ```json { "error": "Google Flow account john@gmail.com not found", "code": 404 } ``` **408** **408 Request Timeout** Video extension polling timeout (after 10 minutes). ```json { "error": "Polling timeout", "code": 408 } ``` **429** **429 Too Many Requests** Google returns several `RESOURCE_EXHAUSTED` 429 variants. Check the `reason` field and respond accordingly: | Reason | Meaning | Scope | What to do | Cooldown | |--------|---------|-------|------------|----------| | `PUBLIC_ERROR_`<br>`USER_REQUESTS_THROTTLED` | Google is throttling the account (the token was fine). Uploads and generation are metered separately | All models on the account — or uploads only, when POST /assets triggered it | Run fewer parallel requests, or switch accounts. From POST /assets, retrying the same one rarely clears it | ~30 min. From POST /assets, treat it as a minimum — it can persist | | `PUBLIC_ERROR_`<br>`USER_QUOTA_REACHED` | Account's overall Flow quota cap | All models on the account | Add accounts, or omit `email` to load-balance | ~30 min | | `PUBLIC_ERROR_`<br>`PER_MODEL_DAILY_QUOTA_REACHED` | Per-model daily quota | Only that model, on that account | Switch model, or wait | Next UTC midnight | | `PUBLIC_ERROR_`<br>`UNUSUAL_ACTIVITY_TOO_MUCH_TRAFFIC` | Google rejected the captcha on every try (we already retried). Usually a distrusted Google account, sometimes the provider | Per request | Check which accounts are affected in [captcha-stats](/docs/api-google-flow-v1/get-google-flow-accounts-captcha-stats#when-google-rejects-captchas). Rest or replace those accounts. Add a second provider if all accounts drop together | 60s | Every `429` returns the cooldown two ways — an HTTP `Retry-After: <seconds>` header and a body `retryAfter: <ISO timestamp>` field. Honor it before retrying. When `email` is omitted, the first three reasons quarantine the account and the load balancer routes around it. If every account is quarantined for the model you get `429` with `error: "no_eligible_account"`. Routing details: [GET /jobs › Load Balancing Algorithm](/docs/api-google-flow-v1/get-google-flow-jobs#load-balancing-algorithm). Captcha-quality failures prefix the top-level `error` with `captcha_quality:` (e.g. `"captcha_quality: PUBLIC_ERROR_UNUSUAL_ACTIVITY_TOO_MUCH_TRAFFIC after 3 attempts"`) so you can detect them without parsing the nested body. **503** **503 Service Unavailable** `503` has two distinct causes — check the response body to tell them apart. A transient Google-side outage. Wait 5-10 seconds and retry. ```json { "error": { "code": 503, "message": "Service temporarily unavailable.", "status": "UNAVAILABLE" } } ``` A captcha-provider failure — the top-level `error` is prefixed `Captcha service failed:`. The problem is your captcha provider (check its API key and balance), not Google. Don't retry until the provider is back. ```json { "error": "Captcha service failed: ERROR_ZERO_BALANCE", "code": 503 } ``` **596** **596 Session Error** Google rejected the account's session, and the API is re-verifying the account on its own: retry in about a minute. If Google signed the account out, the account keeps answering `596` and you get a reconnect email: add it again by following [Setup Google Flow](/docs/start-here/setup-google-flow). ```json { "error": "Google Flow account john@gmail.com Google rejected this account session (HTTP 401). We are automatically re-verifying it — please retry in about a minute. If the account was signed out, you will receive a reconnect email.", "code": 596 } ``` ### Model One tab per answer: the extended videos (`200`, sync), the job record (`201`, async) and a failed job. <details markdown="block" class="model-details"> <summary>The answer for each status, field by field, and the types it uses (<code>FlowVideoMedia</code>, <code>FlowCaptcha</code>, <code>FlowReference</code>)</summary> **200 OK (Sync)** Video extension completed. Returns extended video data with signed URLs. `FlowVideoMedia` and `FlowCaptcha` are described below the tabs. ```typescript { jobId: string // the job id, for GET /jobs/{jobid} operations: [] // always empty on this endpoint: read media[] media: FlowVideoMedia[] // one item per video. With omni-flash-1.2 each is one clip of the source plus the extension remainingCredits?: number // the account's Google Flow credits left, as Google last reported them captcha: FlowCaptcha // the captcha solved for this request } ``` **201 Created (Async)** Job created and processing in background. Structure matches [GET /jobs/`jobId`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid) response. References you sent come back decoded, as `FlowReference` objects (described below the tabs). ```typescript { jobid: string // the job id, for GET /jobs/{jobid} type: 'video' // the job type status: 'created' // the job status created: string // ISO 8601 time the job was created request: { // the request as you sent it, after validation email: string // the account the job runs on, the one that owns the source video prompt: string // the extension prompt mediaGenerationId: FlowReference // the source video model?: string // "omni-flash-1.2", when you set it duration?: number // the seconds to add, 3-10, omni-flash-1.2 resolution?: string // 360p or 720p, omni-flash-1.2 referenceImage_1?: FlowReference // a reference image, omni-flash-1.2 referenceImage_2?: FlowReference // a reference image, omni-flash-1.2 referenceImage_3?: FlowReference // a reference image, omni-flash-1.2 character_1?: FlowReference // a character, omni-flash-1.2 character_2?: FlowReference // a character, omni-flash-1.2 character_3?: FlowReference // a character, omni-flash-1.2 referenceAudio_1?: string // a voice: a built-in voice name (lowercase) or your voice reference referenceAudio_2?: string // a voice: a built-in voice name (lowercase) or your voice reference referenceAudio_3?: string // a voice: a built-in voice name (lowercase) or your voice reference count?: number // how many videos you asked for returnSilentVideos?: boolean // true: a video whose sound Google's filter rejects comes back silent captchaToken?: string // the captcha token you sent captchaRetry?: number // the captcha retries you asked for captchaOrder?: string[] // the captcha providers you listed, in order async: true // answer at once, the job runs in the background replyUrl?: string // your callback URL replyRef?: string // your reference, sent back in callbacks } response: { // Google's answer so far operations: [] // always empty on this endpoint: read media[] media: FlowVideoMedia[] // one item per video, still being made (no mediaGenerationId or URLs yet) captcha: FlowCaptcha // the captcha solved for this request captchaAttemptsCount: number // how many captcha solves were tried, one per entry of captcha.attempts captchaProviders: string // the providers tried, comma-separated, in the order tried tier: string // the account's Google plan tier when the job started, as Google reports it, e.g. "PAYGATE_TIER_TWO" sku: string // the account's Google plan code when the job started, e.g. "G1_TIER2" remainingCredits?: number // the account's Google Flow credits left, as Google reported them at submit } } ``` **Error** Error response structure (applies to both sync and async modes). ```typescript { jobId?: string // the job id, when the job had been created error: string // what went wrong, e.g. "All operations failed" or "PUBLIC_ERROR_UNSAFE_GENERATION (HTTP 400)" code?: number // the HTTP status retryAfter?: string // ISO 8601 time to retry after, on a 429 (the Retry-After header carries the same in seconds) response?: { // what the job held when it failed failureReasons?: string[] // why every video failed: Google's terminal codes and classifier labels, de-duplicated. // Present only when all videos failed AND Google gave a reason. See // "Why a generation failed" on the POST /videos page operations?: [] // always empty, kept for older clients media?: FlowVideoMedia[] // every video of the job, when none was made: each carries its own reason in mediaMetadata.mediaStatus remainingCredits?: number // the account's Google Flow credits left, as Google last reported them error?: string | { // Google's error when Google refused the request, or our own text (e.g. a polling timeout) code: number // HTTP status Google answered message: string // the error message, e.g. "flow.google.com fZytfe failed" status: string // Google's status name, e.g. "RESOURCE_EXHAUSTED" details: Array<{ // Google's error details '@type': string // the type name of the detail reason: string // Google's reason code, e.g. "PUBLIC_ERROR_USER_QUOTA_REACHED" }> } captcha?: FlowCaptcha // the captcha tried or used captchaAttemptsCount?: number // how many captcha solves were tried, when the job failed before its first poll captchaProviders?: string // the providers tried, comma-separated, when the job failed before its first poll tier?: string // the account's Google plan tier, when the job failed before its first poll sku?: string // the account's Google plan code, when the job failed before its first poll } } ``` The types the tabs refer to: **`FlowVideoMedia`**: each item of `media` in the tabs above. ```typescript { name: string // Google's media id of the video projectId: string // the Google Flow project the video is in workflowId?: string // the Google Flow workflow (project item) that holds the video workflowStepId?: string // the workflow step, e.g. "CAE" (left out when Google's record has none) mediaMetadata: { // Google's record of the video createTime?: string // ISO 8601 time Google created the video mediaTitle?: string // the prompt, as Google Flow titles the video (an upscale has none) mediaBlobSize?: string // the MP4's size in bytes, as a string, once the video is done mediaStatus: { // whether the video was made mediaGenerationStatus: string // MEDIA_GENERATION_STATUS_PENDING | MEDIA_GENERATION_STATUS_ACTIVE | // MEDIA_GENERATION_STATUS_SUCCESSFUL | MEDIA_GENERATION_STATUS_FAILED | // MEDIA_GENERATION_STATUS_UNKNOWN error?: { // why the video failed code: number // Google's error code message: string // Google's reason, e.g. "PUBLIC_ERROR_IP_INPUT_IMAGE" } failureReasons?: string[] // Google's classifier labels for a failed video, e.g. "IP_PROHIBITED" } visibility?: string // "PRIVATE" (left out on a failed video) requestData: { // what the video was made from, as Google echoes it videoGenerationRequestData: { // the generation settings backend: 'flow' // the video was made on `flow.google.com` statusEnum: number | null // Google's raw status number: 6 queued, 1 and 2 running, 3 done, 4, 5 and 7 failed aspectEnum: number | null // Google's raw aspect number: 2 landscape, 1 portrait videoModelControlInput?: { // the model settings Google ran videoModelName?: string // Google's own key for the model that ran videoGenerationMode?: string // VIDEO_GENERATION_MODE_TEXT_TO_VIDEO | VIDEO_GENERATION_MODE_REFERENCE_TO_VIDEO | // VIDEO_GENERATION_MODE_VIDEO_EXTENSION (left out for the other modes) videoAspectRatio?: string // VIDEO_ASPECT_RATIO_LANDSCAPE | VIDEO_ASPECT_RATIO_PORTRAIT videoResolution?: string // VIDEO_RESOLUTION_360P | VIDEO_RESOLUTION_720P | VIDEO_RESOLUTION_1080P | // VIDEO_RESOLUTION_4K } } promptInputs?: Array<{ // the prompt as Google received it (an upscale has none) structuredPrompt: { // the prompt in parts parts: Array<{ // a run of text, or an @-mention text?: string // a run of prompt text reference?: object // an @-mention: { media: { mediaId, handle } }, { audio: { mediaId, handle } } or { entity: { entityId, handle } } }> } }> clientPlatform?: string // "CLIENT_PLATFORM_WEB" } } video: { // the video's details generatedVideo?: { // how Google made it (left out until Google reports it) seed: number // the seed Google used (0 when it reports none) prompt: string // the prompt as Google ran it (Veo rewrites it), an empty string on an upscale model: string // Google's own key for the model that ran baseImageMediaGenerationId?: string // an empty string on every video so far isLooped: false // always false aspectRatio: string // VIDEO_ASPECT_RATIO_LANDSCAPE | VIDEO_ASPECT_RATIO_PORTRAIT // (an empty string when Google reports none) upsampleMetadata?: { // on an upscaled video videoUpsampleResolution: string // VIDEO_UPSAMPLE_RESOLUTION_720P | VIDEO_UPSAMPLE_RESOLUTION_1080P // (left out for 4K) } } dimensions?: { // the clip's measurements (an upscaled clip has none) length: string // the clip's length, e.g. "8s" } operation: { // the generation operation name: string // the same as name } } mediaGenerationId?: string // the id to pass to the other endpoints (upscale, extend, GIF, concatenate, assets), on every finished answer, left out of the 201 answer videoUrl?: string // signed MP4 download URL, valid about 6 hours, once the video is done thumbnailUrl?: string // signed JPEG thumbnail URL, valid about 6 hours } ``` **`FlowCaptcha`**: the `captcha` in the tabs above. ```typescript { service?: string // the provider whose token Google accepted: `CapSolver`, `AntiCaptcha`, // `YesCaptcha`, `CapMonster`, `SolveCaptcha`, `2Captcha`, `EzCaptcha` or // `UserProvided`. Always on a success answer taskId?: string // that provider's task id (none for `UserProvided`) durationMs?: number // ms from the first solve to the token used. Always on a success answer error?: string // why no captcha token could be had, on a failed request attempts: Array<{ // every solve tried, in order, failed ones included service: string // the provider asked taskId?: string // that provider's task id durationMs: number // how long this solve took, in ms success: boolean // true when the provider returned a token (Google may still have refused it) error?: string // why the solve failed userAgent?: string // the browser user agent the provider solved with, when it reports one secChUa?: string // the Sec-CH-UA value the provider solved with, when it reports one (may be empty) cost?: string // the provider's price for this solve, as the provider reports it ip?: string // the IP address the provider reports for this solve createTime?: number // Unix time the provider started the solve, as it reports it endTime?: number // Unix time the provider finished the solve, as it reports it solveCount?: number // the provider's own solve counter for this task }> } ``` **`FlowReference`**: the source video and each reference image or character in `request` above. ```typescript { user: number // your useapi.net user id, read from the reference email: string // the Google account the media belongs to, read from the reference type: 'image' | 'video' | 'character' // what the reference points to id: string // Google's media id (image or video), or the character's entity id referenceId: string // the reference you sent meta?: { // characters only imgs: number // how many images the character holds (they count toward the model's image limit) voiceWorkflowId?: string // the voice attached to the character, when it has one } } ``` </details> ### Missing media URLs Media URL fields are optional and can be absent even when generation succeeded. When `videoUrl`, `thumbnailUrl`, `fifeUrl`, `servingBaseUri`, `previewUrl` or `audioUrl` is missing, the media itself is fine — only the download link could not be produced at that moment. This is rare. Across the seven days of request logs we keep, it happened on one day only — twice, for about four hours and about forty minutes — and not at all on the other six. Google issues those links from an endpoint that limits how often it will answer a given network address, so it is Google limiting our outbound calls rather than useapi.net limiting you, and nothing you do triggers it. While it lasts it affects every account generating at that moment, then clears on its own. Your generation still completed and was charged as usual. On a media item that generated successfully — `mediaStatus.mediaGenerationStatus` is `MEDIA_GENERATION_STATUS_SUCCESSFUL` — a missing URL means "not yet", not "failed", so read the field before using it and treat its absence as a retry condition. A media item that failed generation never carries a URL, and retrying will not produce one. ``` javascript const url = media.videoUrl; if (!url) { // Not an error — the link is not available yet. See the options below. } ``` #### How to get the link Which route to use depends on whether you can wait. If you are already polling the job, do nothing special. Completed video jobs re-resolve missing URLs automatically on [GET /jobs/`jobId`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid), and the recovered link is saved, so a later poll returns it with no extra work on your side. This applies to video jobs created within the last 24 hours. Once the job is completed and a URL is still missing, leave at least a minute between polls — a job re-resolves at most once a minute, and the block clears only once traffic stops, so a tight retry loop lengthens the wait rather than shortening it. If you hold a `mediaGenerationId` but no longer have the job, ask for that one media again with [GET /assets/`mediaGenerationId`](/docs/api-google-flow-v1/get-google-flow-assets-mediagenerationid). That endpoint says which case you are in rather than leaving you to guess. A `503` with a `Retry-After` header means the link is coming and tells you how long to wait, so wait that long and ask again. A `404` means Google has no such media, and no amount of retrying will change it. If you cannot wait, download the video through us with [GET /assets/`mediaGenerationId``?raw=true`](/docs/api-google-flow-v1/get-google-flow-assets-mediagenerationid). It reads the media over a different Google route that the block does not touch, so it works immediately and keeps working while the other two return nothing. It is **video only**. Prefer the two link-based routes when you can. They hand you a link and you download straight from Google. The raw form moves the whole file through useapi.net on every call, which makes it a way out of a stuck download rather than your normal download path. Characters and voices resolve their URLs as they are read, so simply requesting [GET /characters/`ref`](/docs/api-google-flow-v1/get-google-flow-characters-ref) or [GET /voices/`ref`](/docs/api-google-flow-v1/get-google-flow-voices-ref) again is enough. Wait a minute before retrying — a response that came back without its URL is held briefly, so an immediate repeat returns the same one. None of this applies to images. Whenever an image URL is missing, [POST /images](/docs/api-google-flow-v1/post-google-flow-images) puts the image itself in the response instead, base64-encoded in `encodedImage` — so you already have the picture and there is nothing to retry. ### Examples **Curl** ``` bash # First generate a video curl -X POST \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"prompt": "A serene mountain landscape at sunset"}' \ "https://api.useapi.net/v1/google-flow/videos" > generate.json # Extract mediaGenerationId from the response MEDIA_ID=$(jq -r '.media[0].mediaGenerationId' generate.json) # Extend the video curl -X POST \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d "{\"mediaGenerationId\": \"$MEDIA_ID\", \"prompt\": \"The camera rises above the mountains as the sun sets behind them\"}" \ "https://api.useapi.net/v1/google-flow/videos/extend" > extend.json # Extract extended video URL and download VIDEO_URL=$(jq -r '.media[0].videoUrl' extend.json) curl "$VIDEO_URL" --output extended_video.mp4 ``` **JavaScript** ``` javascript const token = 'YOUR_API_TOKEN'; // First generate a video const generateResponse = await fetch('https://api.useapi.net/v1/google-flow/videos', { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ prompt: 'A serene mountain landscape at sunset' }) }); const generated = await generateResponse.json(); // Prefer media[] over deprecated operations[] const mediaGenerationId = generated.media[0].mediaGenerationId; // Extend the video const extendResponse = await fetch('https://api.useapi.net/v1/google-flow/videos/extend', { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ mediaGenerationId, prompt: 'The camera rises above the mountains as the sun sets behind them' }) }); const extended = await extendResponse.json(); // Prefer media[] over deprecated operations[] const videoUrl = extended.media[0].videoUrl; // Download extended video (Node.js) const videoResponse = await fetch(videoUrl); const videoBuffer = await videoResponse.arrayBuffer(); require('fs').writeFileSync('extended_video.mp4', Buffer.from(videoBuffer)); console.log('Extended video saved!'); ``` **Python** ``` python import requests token = 'YOUR_API_TOKEN' headers = { 'Authorization': f'Bearer {token}', 'Content-Type': 'application/json' } # First generate a video generate_response = requests.post( 'https://api.useapi.net/v1/google-flow/videos', headers=headers, json={'prompt': 'A serene mountain landscape at sunset'} ) generated = generate_response.json() # Prefer media[] over deprecated operations[] media_generation_id = generated['media'][0]['mediaGenerationId'] # Extend the video extend_response = requests.post( 'https://api.useapi.net/v1/google-flow/videos/extend', headers=headers, json={ 'mediaGenerationId': media_generation_id, 'prompt': 'The camera rises above the mountains as the sun sets behind them' } ) extended = extend_response.json() # Prefer media[] over deprecated operations[] video_url = extended['media'][0]['videoUrl'] # Download extended video video_response = requests.get(video_url) with open('extended_video.mp4', 'wb') as f: f.write(video_response.content) print('Extended video saved!') ``` ### Try It <script> function displayExtendedVideo(response, elementId) { const mediaContainer = document.getElementById(`${elementId}-media-links`); if (!mediaContainer) return; mediaContainer.innerHTML = ''; const mediaItems = response.media || []; const operations = response.operations || []; if (mediaItems.length === 0 && operations.length === 0) { mediaContainer.style.display = 'none'; return; } const videos = []; if (mediaItems.length > 0) { mediaItems.forEach((item, index) => { videos.push({ videoUrl: item.videoUrl, label: `Extended Video` }); }); } else { operations.forEach((op, index) => { if (op.operation?.metadata?.video) { const video = op.operation.metadata.video; videos.push({ videoUrl: video.fifeUrl, label: `Extended Video` }); } }); } if (videos.length > 0) { const linksHTML = videos.map(vid => { return `<a href="${vid.videoUrl}" target="_blank" rel="noopener noreferrer" class="media-link video">${vid.label}</a>`; }).join(' '); mediaContainer.innerHTML = `<div class="media-links-container"><strong>Extended Video:</strong> ${linksHTML}</div>`; mediaContainer.style.display = 'block'; } else { mediaContainer.style.display = 'none'; } } async function apiExecutePostGoogleFlowVideosExtend() { const tokenElement = document.getElementById('input-token'); const elementId = 'input'; const payload = {}; const inputs = document.querySelectorAll('.input-query-param'); inputs.forEach(input => { const id = input.id; const value = input.value?.trim(); if (id.startsWith('input-') && value !== '' && value !== undefined) { const key = id.replace('input-', ''); if (key === 'captchaRetry' || key === 'count' || key === 'duration') { payload[key] = parseInt(value); } else if (key === 'async' || key === 'returnSilentVideos') { payload[key] = value === 'true'; } else { payload[key] = value; } } }); const data = { method: 'POST', headers: { 'Authorization': `Bearer ${tokenElement.value}`, 'Content-Type': 'application/json' }, body: JSON.stringify(payload) }; const mediaLinks = document.getElementById(`${elementId}-media-links`); if (mediaLinks) mediaLinks.style.display = 'none'; const status = await apiExecute('https://api.useapi.net/v1/google-flow/videos/extend', elementId, data, { includeTimer: true }); if (status === 200) { try { const content = document.getElementById(`${elementId}-response-json`); const response = JSON.parse(content.innerText); displayExtendedVideo(response, elementId); } catch (e) { console.error('Failed to parse response for video display:', e); } } } </script> <form id="input" class="input-form" onsubmit="return false;"> <div class="input-field"> <div class="input-field-row"> <label for="input-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="input-token" type="text" class="input-element" required aria-required="true"> </label> <label for="input-mediaGenerationId"><span>mediaGenerationId (required, from <a href="/docs/api-google-flow-v1/post-google-flow-videos">POST /videos</a> or <a href="/docs/api-google-flow-v1/post-google-flow-videos-extend">POST /videos/extend</a>)</span> <input id="input-mediaGenerationId" type="text" class="input-element input-query-param" required aria-required="true" placeholder="user:123-email:...-video:..."> </label> <label for="input-prompt"><span>prompt (required)</span> <input id="input-prompt" type="text" class="input-element input-query-param" required aria-required="true" placeholder="What happens next..."> </label> <label for="input-model"><span>model</span> <select id="input-model" class="input-element input-query-param"> <option value="">omni-flash-1.2 (default, one clip: source + 3-10 s)</option> </select> </label> <label for="input-duration"><span>duration (omni-flash-1.2 only, seconds to add: 3-10, default 8)</span> <input id="input-duration" type="number" class="input-element input-query-param" min="3" max="10" placeholder="8"> </label> <label for="input-resolution"><span>resolution (omni-flash-1.2 only, default: the source's)</span> <select id="input-resolution" class="input-element input-query-param"> <option value="">source resolution (default)</option> <option value="360p">360p</option> <option value="720p">720p</option> </select> </label> <label for="input-referenceImage_1"><span>referenceImage_1 (omni-flash-1.2 only)</span> <input id="input-referenceImage_1" type="text" class="input-element input-query-param" placeholder="user:123-email:...-image:..."> </label> <label for="input-referenceImage_2"><span>referenceImage_2 (omni-flash-1.2 only)</span> <input id="input-referenceImage_2" type="text" class="input-element input-query-param" placeholder="user:123-email:...-image:..."> </label> <label for="input-referenceImage_3"><span>referenceImage_3 (omni-flash-1.2 only)</span> <input id="input-referenceImage_3" type="text" class="input-element input-query-param" placeholder="user:123-email:...-image:..."> </label> <label for="input-character_1"><span>character_1 (omni-flash-1.2 only)</span> <input id="input-character_1" type="text" class="input-element input-query-param" placeholder="user:123-email:...-character:...-imgs:N"> </label> <label for="input-referenceAudio_1"><span>referenceAudio_1 (omni-flash-1.2 only, system voice name or user voice)</span> <input id="input-referenceAudio_1" type="text" class="input-element input-query-param" placeholder="Charon"> </label> <label for="input-referenceAudio_2"><span>referenceAudio_2 (omni-flash-1.2 only)</span> <input id="input-referenceAudio_2" type="text" class="input-element input-query-param" placeholder="Aoede"> </label> <label for="input-count"><span>count (1-4, default: 1)</span> <input id="input-count" type="number" class="input-element input-query-param" min="1" max="4" placeholder="1"> </label> <label for="input-returnSilentVideos"><span>returnSilentVideos (true: a video whose sound Google's audio filter rejects comes back silent, charged, instead of failing)</span> <select id="input-returnSilentVideos" class="input-element input-query-param"> <option value="">false (default)</option> <option value="true">true</option> </select> </label> <label for="input-async"><span>async (fire-and-forget mode)</span> <select id="input-async" class="input-element input-query-param"> <option value="false">false (default)</option> <option value="true">true</option> </select> </label> <label for="input-replyUrl"><span>replyUrl (webhook URL)</span> <input id="input-replyUrl" type="text" class="input-element input-query-param" placeholder="https://your-domain.com/webhook"> </label> <label for="input-replyRef"><span>replyRef (custom reference)</span> <input id="input-replyRef" type="text" class="input-element input-query-param" placeholder="my-custom-id-123"> </label> <label for="input-captchaToken"><span>captchaToken (optional, your own reCAPTCHA token)</span> <input id="input-captchaToken" type="text" class="input-element input-query-param" placeholder="reCAPTCHA v3 Enterprise token"> </label> <label for="input-captchaRetry"><span>captchaRetry (1-10, optional)</span> <input id="input-captchaRetry" type="number" class="input-element input-query-param" min="1" max="10" placeholder="5"> </label> <label for="input-captchaOrder"><span>captchaOrder (optional)</span> <input id="input-captchaOrder" type="text" class="input-element input-query-param" placeholder="CapSolver,AntiCaptcha"> </label> </div> <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecutePostGoogleFlowVideosExtend()">Go</button> </div> </form> <div id="input-media-links" style="display:none;"></div> <div id="input-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos-gif === Document URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos-gif --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/gif description: "Generate an animated GIF from a Google Flow video via POST videos/gif in the useapi.net Google Flow API v1 — synchronous, no captcha required." parent: Google Flow API nav_order: 720 --- ## Generate Video GIF January 20, 2026 (November 16, 2026) --- Generate an animated GIF preview from a previously generated video. This is a synchronous operation that returns base64-encoded GIF data. - No captcha required - this endpoint doesn't require reCAPTCHA solving. - GIF generation can take up to 90 seconds. > **https://api.useapi.net/v1/google-flow/videos/gif** ### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Request Body ```json { "mediaGenerationId": "user:12345-email:6a6f...-video:CAMaJDMx..." } ``` - `mediaGenerationId` is **required**. The `mediaGenerationId` from a previously generated video via [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos). ### Responses **200** **200 OK** GIF generated successfully. Returns base64-encoded GIF data. ```json { "encodedGif": "R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7...base64 encoded GIF data...", "backend": "flow" } ``` **400** **400 Bad Request** Invalid request (missing or invalid mediaGenerationId). ```json { "error": "Parameter mediaGenerationId is required", "code": 400 } ``` An image's `mediaGenerationId` instead of a video's: ```json { "error": "Parameter mediaGenerationId type must be 'video', got 'image'", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **402** **402 Payment Required** Your useapi.net subscription is missing or has expired, so nothing was sent to Google. [Subscribe or renew it](/docs/subscription), then send the request again. ```json { "error": "useapi.net ⁝ Your account has no subscription, please subscribe to our services before submitting requests", "code": 402 } ``` When the subscription has expired: ```json { "error": "useapi.net ⁝ Monthly subscription 261008 expired, please renew your subscription before submitting new requests.", "code": 402 } ``` **403** **403 Forbidden** Google refused to make the GIF (`PERMISSION_DENIED`), so no GIF was made. Google's answer is passed on as it came, with Google's reason in `details` when it gives one. ```json { "error": { "code": 403, "message": "flow.google.com QZasKb failed", "status": "PERMISSION_DENIED", "details": [] } } ``` **404** **404 Not Found** Account not found or video not found. ```json { "error": "Google Flow account john@gmail.com not found", "code": 404 } ``` **429** **429 Too Many Requests** Google is limiting requests from this account (`RESOURCE_EXHAUSTED`), so no GIF was made. Wait before you retry. Google's answer is passed on as it came, with Google's reason in `details` when it gives one. ```json { "error": { "code": 429, "message": "flow.google.com QZasKb failed", "status": "RESOURCE_EXHAUSTED", "details": [] } } ``` **503** **503 Service Unavailable** Google Flow could not be reached for this request, so nothing was made. Retry shortly. If Google signed the account out, the API re-verifies it on its own and the account answers `596` meanwhile. ```json { "error": { "code": 503, "message": "flow.google.com unavailable for this request — retry", "status": "UNAVAILABLE", "details": [] } } ``` **596** **596 Session Error** Google rejected the account's session, and the API is re-verifying the account on its own: retry in about a minute. If Google signed the account out, the account keeps answering `596` and you get a reconnect email: add it again by following [Setup Google Flow](/docs/start-here/setup-google-flow). ```json { "error": "Google Flow account john@gmail.com Google rejected this account session (HTTP 401). We are automatically re-verifying it — please retry in about a minute. If the account was signed out, you will receive a reconnect email.", "code": 596 } ``` ### Model The GIF as Base64 data, or an error object when the request fails. <details markdown="block" class="model-details"> <summary>The GIF and the error answer, field by field</summary> ```typescript { encodedGif: string // Base64-encoded GIF data (decode and save as .gif) backend: 'flow' // the GIF was made on `flow.google.com` } ``` When the request fails, the answer is either our own `{ error, code }` or Google's error object as Google answered it: ```typescript { error: string | { // what went wrong: our own text, or Google's error object when Google refused the request code: number // HTTP status Google answered, e.g. 404 message: string // the error message status: string // Google's status name details: Array<{ // Google's error details '@type': string // the type name of the detail reason: string // Google's reason code }> } code?: number // the HTTP status, with our own text } ``` </details> ### Examples **Curl** ``` bash # First generate a video curl -X POST \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"prompt": "A serene mountain landscape at sunset"}' \ "https://api.useapi.net/v1/google-flow/videos" > generate.json # Extract mediaGenerationId from the response MEDIA_ID=$(jq -r '.media[0].mediaGenerationId' generate.json) # Generate GIF preview curl -X POST \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d "{\"mediaGenerationId\": \"$MEDIA_ID\"}" \ "https://api.useapi.net/v1/google-flow/videos/gif" > gif.json # Decode base64 and save as GIF jq -r '.encodedGif' gif.json | base64 -d > video_preview.gif ``` **JavaScript** ``` javascript const token = 'YOUR_API_TOKEN'; // First generate a video const generateResponse = await fetch('https://api.useapi.net/v1/google-flow/videos', { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ prompt: 'A serene mountain landscape at sunset' }) }); const generated = await generateResponse.json(); const mediaGenerationId = generated.media[0].mediaGenerationId; // Generate GIF preview const gifResponse = await fetch('https://api.useapi.net/v1/google-flow/videos/gif', { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ mediaGenerationId }) }); const gifResult = await gifResponse.json(); // Decode base64 and save (Node.js) const buffer = Buffer.from(gifResult.encodedGif, 'base64'); require('fs').writeFileSync('video_preview.gif', buffer); console.log('GIF preview saved!'); // Or use in browser as data URL const dataUrl = `data:image/gif;base64,${gifResult.encodedGif}`; document.getElementById('preview').src = dataUrl; ``` **Python** ``` python import requests import base64 token = 'YOUR_API_TOKEN' headers = { 'Authorization': f'Bearer {token}', 'Content-Type': 'application/json' } # First generate a video generate_response = requests.post( 'https://api.useapi.net/v1/google-flow/videos', headers=headers, json={'prompt': 'A serene mountain landscape at sunset'} ) generated = generate_response.json() media_generation_id = generated['operations'][0]['mediaGenerationId'] # Generate GIF preview gif_response = requests.post( 'https://api.useapi.net/v1/google-flow/videos/gif', headers=headers, json={'mediaGenerationId': media_generation_id} ) gif_result = gif_response.json() # Decode base64 and save gif_data = base64.b64decode(gif_result['encodedGif']) with open('video_preview.gif', 'wb') as f: f.write(gif_data) print('GIF preview saved!') ``` ### Try It <script> function displayVideoGif(response, elementId) { const mediaContainer = document.getElementById(`${elementId}-media-links`); if (!mediaContainer) return; mediaContainer.innerHTML = ''; if (!response.encodedGif) { mediaContainer.style.display = 'none'; return; } const dataUrl = `data:image/gif;base64,${response.encodedGif}`; const downloadLink = document.createElement('a'); downloadLink.href = dataUrl; downloadLink.download = 'video_preview.gif'; downloadLink.className = 'media-link image'; downloadLink.textContent = 'Download GIF'; const container = document.createElement('div'); container.className = 'media-links-container'; container.innerHTML = '<strong>Video GIF Preview:</strong> '; container.appendChild(downloadLink); const imgPreview = document.createElement('img'); imgPreview.src = dataUrl; imgPreview.style.cssText = 'max-width:100%;margin-top:10px;display:block;border:1px solid #ccc;'; imgPreview.alt = 'GIF preview'; mediaContainer.appendChild(container); mediaContainer.appendChild(imgPreview); mediaContainer.style.display = 'block'; } async function apiExecutePostGoogleFlowVideosGif() { const tokenElement = document.getElementById('input-token'); const elementId = 'input'; const payload = {}; const inputs = document.querySelectorAll('.input-query-param'); inputs.forEach(input => { const id = input.id; const value = input.value?.trim(); if (id.startsWith('input-') && value !== '' && value !== undefined) { const key = id.replace('input-', ''); payload[key] = value; } }); const data = { method: 'POST', headers: { 'Authorization': `Bearer ${tokenElement.value}`, 'Content-Type': 'application/json' }, body: JSON.stringify(payload) }; const mediaLinks = document.getElementById(`${elementId}-media-links`); if (mediaLinks) mediaLinks.style.display = 'none'; const status = await apiExecute('https://api.useapi.net/v1/google-flow/videos/gif', elementId, data, { includeTimer: true }); if (status === 200) { try { const content = document.getElementById(`${elementId}-response-json`); const response = JSON.parse(content.innerText); displayVideoGif(response, elementId); } catch (e) { console.error('Failed to parse response for GIF display:', e); } } } </script> <form id="input" class="input-form" onsubmit="return false;"> <div class="input-field"> <div class="input-field-row"> <label for="input-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="input-token" type="text" class="input-element" required aria-required="true"> </label> <label for="input-mediaGenerationId"><span>mediaGenerationId (required, from <a href="/docs/api-google-flow-v1/post-google-flow-videos">POST /videos</a>)</span> <input id="input-mediaGenerationId" type="text" class="input-element input-query-param" required aria-required="true" placeholder="user:123-email:...-video:..."> </label> </div> <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecutePostGoogleFlowVideosGif()">Go</button> </div> </form> <div id="input-media-links" style="display:none;"></div> <div id="input-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos-upscale === Document URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos-upscale --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/upscale seo_title: "Google Flow Video Upscale API: 720p, 1080p and 4K" description: "Upscale a Google Flow video to 720p, 1080p or 4K via POST /videos/upscale in the useapi.net Google Flow API — 720p promotes a 360p Omni clip, 4K needs Ultra." parent: Google Flow API nav_order: 710 --- ## Upscale Videos January 20, 2026 (November 16, 2026) --- Upscale a previously generated video to 720p, 1080p or 4K resolution. Seeing "Upscaling failed" in Flow? [Why Google Flow upscales fail and how to fix it](/docs/articles/google-flow-errors#upscaling-failed). - Video upscaling requires a paid [Google AI](https://one.google.com/ai) subscription. Free accounts cannot upscale at any resolution. - `4K` requires a [Google AI Ultra](https://one.google.com/ai) subscription. Other paid accounts can use `720p` and `1080p`. - A resolution your account's plan does not include answers `400` with `4K upscaling is not available for this account` (or `720p` / `1080p` on a free account). The request is refused before a reCAPTCHA token is solved, so it costs you nothing, and retrying will not change the outcome. - `720p` and `1080p` upscaling are free for a video of up to 10 seconds, then 1 credit for each second above 10 (a 15-second video costs 5). `4K` costs 50 credits up to 10 seconds, then 5 more for each second above 10 (75 for 15 seconds). - Google upscales videos of up to 15 seconds. A longer video, such as one made longer with [POST /videos/extend](/docs/api-google-flow-v1/post-google-flow-videos-extend), answers `400` before any captcha is solved. - `720p` is for promoting a 360p Omni clip ([Omni 1.2 Flash or Omni 1.1 Flash](/docs/api-google-flow-v1/post-google-flow-videos#model-capabilities)), generated with `resolution: 360p`. For a video of up to 10 seconds, generating at 360p and upscaling afterwards costs a third of generating at 720p directly on Omni 1.2 Flash, and about half on Omni 1.1 Flash. - Video upscaling typically completes within 30-60 seconds, with 4K taking a few minutes. - Upscaling the same video twice returns a cached result (no additional credits consumed). Use the video URL from the first upscale response. > **https://api.useapi.net/v1/google-flow/videos/upscale** ### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Request Body ```json { "mediaGenerationId": "user:12345-email:6a6f...-video:CAMaJDMx...", "resolution": "1080p" } ``` - `mediaGenerationId` is **required**. The `mediaGenerationId` from a previously generated video via [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos). - `resolution` is optional. Target resolution for upscaling (default: `1080p`). Supported values: `720p`, `1080p`, `4K`. Use `720p` on a 360p Omni clip. A 360p clip can also go straight to `1080p`. - `async` is optional, enables fire-and-forget mode (default: `false`). When `true`, returns immediately with `201 Created` and job metadata. Poll [GET /jobs/`jobId`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid) for completion status. - `replyUrl` is optional, webhook URL for job status callbacks. Receives POST requests with job status updates (`created`, `started`, `completed`, `failed`). The JSON payload shape matches [GET /jobs/`jobId`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid) response. - `replyRef` is optional, custom reference string passed back in webhook callbacks. - `captchaToken`, `captchaRetry`, `captchaOrder` are optional, mutually exclusive captcha parameters. See [Captcha Parameters](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers#captcha-parameters) for details. ### Responses **200** **200 OK** Video upscaled successfully. Both `operations[]` (older shape, with `fifeUrl`) and `media[]` (current, with `videoUrl`) are populated. ```json { "jobId": "j1115123456789617024v-u12345-email:john@gmail.com-bot:google-flow", "operations": [ { "operation": { "name": "2fefd089-...redacted...", "metadata": { "@type": "type.googleapis.com/google.internal.labs.aisandbox.v1.Media", "name": "2fefd089-...redacted...", "video": { "seed": 0, "model": "veo_3_1_upsampler_1080p", "aspectRatio": "VIDEO_ASPECT_RATIO_LANDSCAPE", "isLooped": false, "upsampleResolution": "VIDEO_UPSAMPLE_RESOLUTION_1080P", "fifeUrl": "https://flow-content.google/video/2fefd089-...redacted...?Expires=...", "servingBaseUri": "https://flow-content.google/image/2fefd089-...redacted...?Expires=...", "mediaGenerationId": "user:12345-email:6a6f...-video:2fefd089-...redacted...", "mediaVisibility": "PRIVATE" } } }, "sceneId": "", "status": "MEDIA_GENERATION_STATUS_SUCCESSFUL", "mediaGenerationId": "user:12345-email:6a6f...-video:2fefd089-...redacted..." } ], "media": [ { "name": "2fefd089-...redacted...", "projectId": "9f63078c-...redacted...", "workflowId": "66612805-...redacted...", "workflowStepId": "CAI", "mediaMetadata": { "createTime": "2026-11-15T23:31:41.145235Z", "mediaBlobSize": "14417920", "mediaStatus": { "mediaGenerationStatus": "MEDIA_GENERATION_STATUS_SUCCESSFUL" }, "visibility": "PRIVATE", "requestData": { "videoGenerationRequestData": { "backend": "flow", "statusEnum": 3, "aspectEnum": 2, "videoModelControlInput": { "videoModelName": "veo_3_1_upsampler_1080p", "videoAspectRatio": "VIDEO_ASPECT_RATIO_LANDSCAPE", "videoResolution": "VIDEO_RESOLUTION_1080P" } }, "clientPlatform": "CLIENT_PLATFORM_WEB" } }, "video": { "generatedVideo": { "seed": 0, "prompt": "", "model": "veo_3_1_upsampler_1080p", "baseImageMediaGenerationId": "", "isLooped": false, "aspectRatio": "VIDEO_ASPECT_RATIO_LANDSCAPE", "upsampleMetadata": { "videoUpsampleResolution": "VIDEO_UPSAMPLE_RESOLUTION_1080P" } }, "operation": { "name": "2fefd089-...redacted..." } }, "videoUrl": "https://flow-content.google/video/2fefd089-...redacted...?Expires=...", "thumbnailUrl": "https://flow-content.google/image/2fefd089-...redacted...?Expires=...", "mediaGenerationId": "user:12345-email:6a6f...-video:2fefd089-...redacted..." } ], "remainingCredits": 18760, "captcha": { "service": "CapSolver", "taskId": "14af1dbb-885c-4e25-8121-7a79489dfd0e", "durationMs": 3500, "attempts": [ { "service": "CapSolver", "success": true, "durationMs": 3500, "taskId": "14af1dbb-885c-4e25-8121-7a79489dfd0e" } ] } } ``` **201** **201 Created** Job created in async mode (`async: true`). Video upscaling is processing in the background. Use [GET /jobs/`jobId`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid) to poll for completion status. ```json { "jobid": "j1115123456789617024v-u12345-email:john@gmail.com-bot:google-flow", "type": "video", "status": "created", "created": "2026-11-15T12:34:56.789Z", "request": { "mediaGenerationId": { "user": 12345, "email": "john@gmail.com", "type": "video", "id": "a1d95d21-75d2-482d-a354-14ef8802ce66", "referenceId": "user:12345-email:6a6f...-video:a1d95d21-75d2-482d-a354-14ef8802ce66" }, "resolution": "1080p", "async": true, "email": "john@gmail.com" }, "response": { "media": [ { "name": "2fefd089-...redacted...", "projectId": "9f63078c-...redacted...", "workflowId": "66612805-...redacted...", "workflowStepId": "CAI", "mediaMetadata": { "createTime": "2026-11-15T23:31:41.145235Z", "mediaStatus": { "mediaGenerationStatus": "MEDIA_GENERATION_STATUS_PENDING" }, "visibility": "PRIVATE", "requestData": { "videoGenerationRequestData": { "backend": "flow", "statusEnum": 1, "aspectEnum": 2, "videoModelControlInput": { "videoModelName": "veo_3_1_upsampler_1080p", "videoAspectRatio": "VIDEO_ASPECT_RATIO_LANDSCAPE", "videoResolution": "VIDEO_RESOLUTION_1080P" } }, "clientPlatform": "CLIENT_PLATFORM_WEB" } }, "video": { "generatedVideo": { "seed": 0, "prompt": "", "model": "veo_3_1_upsampler_1080p", "baseImageMediaGenerationId": "", "isLooped": false, "aspectRatio": "VIDEO_ASPECT_RATIO_LANDSCAPE", "upsampleMetadata": { "videoUpsampleResolution": "VIDEO_UPSAMPLE_RESOLUTION_1080P" } }, "operation": { "name": "2fefd089-...redacted..." } } } ], "operations": [ { "operation": { "name": "2fefd089-...redacted..." }, "sceneId": "", "status": "MEDIA_GENERATION_STATUS_PENDING" } ], "captcha": { "service": "CapSolver", "taskId": "14af1dbb-885c-4e25-8121-7a79489dfd0e", "durationMs": 5357, "attempts": [ { "service": "CapSolver", "success": true, "durationMs": 5357, "taskId": "14af1dbb-885c-4e25-8121-7a79489dfd0e" } ] }, "captchaAttemptsCount": 1, "captchaProviders": "CapSolver", "tier": "PAYGATE_TIER_TWO", "sku": "G1_TIER2", "remainingCredits": 18760 } } ``` **400** **400 Bad Request** Invalid request, or a resolution your account's plan does not include (`4K` needs Google AI Ultra). ```json { "error": "4K upscaling is not available for this account", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **402** **402 Payment Required** Your useapi.net subscription is missing or has expired, so nothing was sent to Google. [Subscribe or renew it](/docs/subscription), then send the request again. ```json { "error": "useapi.net ⁝ Your account has no subscription, please subscribe to our services before submitting requests", "code": 402 } ``` When the subscription has expired: ```json { "error": "useapi.net ⁝ Monthly subscription 261008 expired, please renew your subscription before submitting new requests.", "code": 402 } ``` **403** **403 Forbidden** Google rejected the captcha on every try. We retry with a fresh captcha as many times as you allow (`captchaRetry`, default 5, or the providers in `captchaOrder`) and return this `403` only when all of them were rejected. The top-level `error` starts with `captcha_quality:`, for example `"captcha_quality: PUBLIC_ERROR_UNUSUAL_ACTIVITY after 5 attempts. Google refused all 5 captcha tokens for user@example.com, so nothing was generated and no Google Flow credits were used (5 captcha solves were spent). Google is flagging this account's requests as unusual activity. If it keeps happening, use another account, or leave out email so the API picks one. See GET /accounts/captcha-stats summary.by_account"`. A `429` with `PUBLIC_ERROR_UNUSUAL_ACTIVITY_TOO_MUCH_TRAFFIC` reads the same way. Two `403`s are not a captcha problem, and we answer them after one try instead of retrying. `PUBLIC_ERROR_MODEL_ACCESS_DENIED` in the response means Google refused the model on that account, so raising `captchaRetry` or adding providers will not help. Check that the account's plan includes the model. Since 2026-09-23 Google no longer offers `veo-3.1-lite-low-priority` to invited members of an Ultra $199 family plan — only the family manager's account keeps it. `PUBLIC_ERROR_USER_MINOR` means Google treats the Google account as belonging to someone under 18, and Google Flow is not available to such accounts. The `error` says so in plain words. No captcha or retry changes it: use another Google account, or have this one's age verified with Google first. With `email` omitted, the load balancer sets such an account aside for 1 hour, then tries it again. Nothing was created when this happens. Google checks the captcha before it starts generating, so no Google credits were used and you can resubmit straight away. Your captcha provider still bills each solve. The usual cause is the Google account, not the captcha provider. Google gives each account its own trust level. On a trusted account it accepts about 9 in 10 captchas, on a distrusted one about 3 in 10, whichever provider solved them. Most customers have a few distrusted accounts among many good ones. To see which accounts are affected, use [GET /accounts/captcha-stats](/docs/api-google-flow-v1/get-google-flow-accounts-captcha-stats). Its `summary.by_account` shows, for each of your Google accounts, how many captchas were tried and what share Google accepted. [GET account/stats](/docs/account-management/get-account-stats) with `bot=google-flow` also shows how many requests each account finished with each response code. - If one or a few accounts are far below the others, the API already sends them less work: when you leave out `email`, each captcha Google rejected on an account in the last 15 minutes lowers its chance of being picked, for generations and for image uploads. They still get some work, so an account that recovers gets its full share back. If you pin requests with `email`, move them to your other accounts yourself. Replace an account that stays low for more than a day or two. - If all your accounts drop at the same time, it's the captcha provider. Configure at least two providers with [POST /accounts/captcha-providers](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers), and the API will start with whichever one Google accepts best. A higher `captchaRetry` gets more requests through on a distrusted account, but every extra try is another paid solve. **404** **404 Not Found** Account not found or video not found. ```json { "error": "Google Flow account john@gmail.com not found", "code": 404 } ``` **408** **408 Request Timeout** Video upscaling polling timeout (after 10 minutes). ```json { "error": "Polling timeout", "code": 408 } ``` **429** **429 Too Many Requests** Google returns several `RESOURCE_EXHAUSTED` 429 variants. Check the `reason` field and respond accordingly: | Reason | Meaning | Scope | What to do | Cooldown | |--------|---------|-------|------------|----------| | `PUBLIC_ERROR_`<br>`USER_REQUESTS_THROTTLED` | Google is throttling the account (the token was fine). Uploads and generation are metered separately | All models on the account — or uploads only, when POST /assets triggered it | Run fewer parallel requests, or switch accounts. From POST /assets, retrying the same one rarely clears it | ~30 min. From POST /assets, treat it as a minimum — it can persist | | `PUBLIC_ERROR_`<br>`USER_QUOTA_REACHED` | Account's overall Flow quota cap | All models on the account | Add accounts, or omit `email` to load-balance | ~30 min | | `PUBLIC_ERROR_`<br>`PER_MODEL_DAILY_QUOTA_REACHED` | Per-model daily quota | Only that model, on that account | Switch model, or wait | Next UTC midnight | | `PUBLIC_ERROR_`<br>`UNUSUAL_ACTIVITY_TOO_MUCH_TRAFFIC` | Google rejected the captcha on every try (we already retried). Usually a distrusted Google account, sometimes the provider | Per request | Check which accounts are affected in [captcha-stats](/docs/api-google-flow-v1/get-google-flow-accounts-captcha-stats#when-google-rejects-captchas). Rest or replace those accounts. Add a second provider if all accounts drop together | 60s | Every `429` returns the cooldown two ways — an HTTP `Retry-After: <seconds>` header and a body `retryAfter: <ISO timestamp>` field. Honor it before retrying. When `email` is omitted, the first three reasons quarantine the account and the load balancer routes around it. If every account is quarantined for the model you get `429` with `error: "no_eligible_account"`. Routing details: [GET /jobs › Load Balancing Algorithm](/docs/api-google-flow-v1/get-google-flow-jobs#load-balancing-algorithm). Captcha-quality failures prefix the top-level `error` with `captcha_quality:` (e.g. `"captcha_quality: PUBLIC_ERROR_UNUSUAL_ACTIVITY_TOO_MUCH_TRAFFIC after 3 attempts"`) so you can detect them without parsing the nested body. **503** **503 Service Unavailable** `503` has two distinct causes — check the response body to tell them apart. A transient Google-side outage. Wait 5-10 seconds and retry. ```json { "error": { "code": 503, "message": "Service temporarily unavailable.", "status": "UNAVAILABLE" } } ``` A captcha-provider failure — the top-level `error` is prefixed `Captcha service failed:`. The problem is your captcha provider (check its API key and balance), not Google. Don't retry until the provider is back. ```json { "error": "Captcha service failed: ERROR_ZERO_BALANCE", "code": 503 } ``` **596** **596 Session Error** Google rejected the account's session, and the API is re-verifying the account on its own: retry in about a minute. If Google signed the account out, the account keeps answering `596` and you get a reconnect email: add it again by following [Setup Google Flow](/docs/start-here/setup-google-flow). ```json { "error": "Google Flow account john@gmail.com Google rejected this account session (HTTP 401). We are automatically re-verifying it — please retry in about a minute. If the account was signed out, you will receive a reconnect email.", "code": 596 } ``` ### Model One tab per answer: the upscaled video (`200`, sync), the job record (`201`, async) and a failed job. <details markdown="block" class="model-details"> <summary>The answer for each status, field by field, and the types it uses (<code>FlowVideoMedia</code>, <code>FlowCaptcha</code>, <code>FlowReference</code>)</summary> **200 OK (Sync)** Video upscaling completed. Returns the upscaled video with signed URLs, in `media[]` and, for older clients, in `operations[]`. `FlowVideoMedia` and `FlowCaptcha` are described below the tabs. ```typescript { jobId: string // the job id, for GET /jobs/{jobid} operations: Array<{ // older shape, kept for clients that read fifeUrl: one per media[] item operation: { // the upscale operation name: string // the same as media[].name metadata?: { // the upscaled video, copied from media[] (left out when Google reports no video details) '@type': string // always the same type name, Google's media record name: string // the same as media[].name video: { // the upscaled video seed: number // the seed Google reports (0 on an upscale) model: string // Google's own key for the upscale model aspectRatio: string // VIDEO_ASPECT_RATIO_LANDSCAPE | VIDEO_ASPECT_RATIO_PORTRAIT isLooped: false // always false prompt?: string // left out on an upscale (it has no prompt) upsampleResolution?: string // VIDEO_UPSAMPLE_RESOLUTION_720P | VIDEO_UPSAMPLE_RESOLUTION_1080P // (left out for 4K) fifeUrl?: string // signed MP4 download URL, as media[].videoUrl servingBaseUri?: string // signed thumbnail URL, as media[].thumbnailUrl (the video URL when there is none) mediaGenerationId: string // the upscaled video's id, as media[].mediaGenerationId mediaVisibility?: string // "PRIVATE", as media[].mediaMetadata.visibility } } } sceneId: '' // always an empty string status: string // MEDIA_GENERATION_STATUS_SUCCESSFUL | MEDIA_GENERATION_STATUS_FAILED, as media[] mediaGenerationId: string // the upscaled video's id, as media[].mediaGenerationId }> media: FlowVideoMedia[] // the upscaled video remainingCredits?: number // the account's Google Flow credits left, as Google last reported them captcha: FlowCaptcha // the captcha solved for this request } ``` **201 Created (Async)** Job created and processing in background. Structure matches [GET /jobs/`jobId`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid) response. The video you sent comes back decoded, as a `FlowReference` object (described below the tabs). ```typescript { jobid: string // the job id, for GET /jobs/{jobid} type: 'video' // the job type status: 'created' // the job status created: string // ISO 8601 time the job was created request: { // the request as you sent it, after validation mediaGenerationId: FlowReference // the video to upscale resolution?: string // 720p, 1080p or 4K captchaToken?: string // the captcha token you sent captchaRetry?: number // the captcha retries you asked for captchaOrder?: string[] // the captcha providers you listed, in order async: true // answer at once, the job runs in the background replyUrl?: string // your callback URL replyRef?: string // your reference, sent back in callbacks email: string // the account the job runs on, the one that owns the video } response: { // Google's answer so far media: FlowVideoMedia[] // the upscale, still being made (no mediaGenerationId or URLs yet) operations: Array<{ // older shape: one per media[] item operation: { // the upscale operation name: string // the same as media[].name } sceneId: '' // always an empty string status: string // MEDIA_GENERATION_STATUS_PENDING at this point }> captcha: FlowCaptcha // the captcha solved for this request captchaAttemptsCount: number // how many captcha solves were tried, one per entry of captcha.attempts captchaProviders: string // the providers tried, comma-separated, in the order tried tier: string // the account's Google plan tier when the job started, as Google reports it, e.g. "PAYGATE_TIER_TWO" sku: string // the account's Google plan code when the job started, e.g. "G1_TIER2" remainingCredits?: number // the account's Google Flow credits left, as Google reported them at submit } } ``` **Error** Error response structure (applies to both sync and async modes). ```typescript { jobId?: string // the job id, when the job had been created error: string | { // what went wrong, e.g. "All operations failed", or Google's own error object when Google // could not read the source video (answered before a job exists, so with no jobId or code) code: number // HTTP status Google answered, e.g. 404 message: string // the error message status: string // Google's status name details: Array<{ // Google's error details '@type': string // the type name of the detail reason: string // Google's reason code }> } code?: number // the HTTP status retryAfter?: string // ISO 8601 time to retry after, on a 429 (the Retry-After header carries the same in seconds) response?: { // what the job held when it failed failureReasons?: string[] // why every video failed: Google's terminal codes and classifier labels, de-duplicated. // Present only when all videos failed AND Google gave a reason. See // "Why a generation failed" on the POST /videos page operations?: object[] // the older operations[] shape of the 200 answer, one per media[] item media?: FlowVideoMedia[] // every video of the job, when none was made: each carries its own reason in mediaMetadata.mediaStatus remainingCredits?: number // the account's Google Flow credits left, as Google last reported them error?: string | { // Google's error when Google refused the request, or our own text (e.g. a polling timeout) code: number // HTTP status Google answered message: string // the error message, e.g. "flow.google.com p0UkFb failed" status: string // Google's status name, e.g. "RESOURCE_EXHAUSTED" details: Array<{ // Google's error details '@type': string // the type name of the detail reason: string // Google's reason code, e.g. "PUBLIC_ERROR_USER_QUOTA_REACHED" }> } captcha?: FlowCaptcha // the captcha tried or used captchaAttemptsCount?: number // how many captcha solves were tried, when the job failed before its first poll captchaProviders?: string // the providers tried, comma-separated, when the job failed before its first poll tier?: string // the account's Google plan tier, when the job failed before its first poll sku?: string // the account's Google plan code, when the job failed before its first poll } } ``` The types the tabs refer to: **`FlowVideoMedia`**: each item of `media` in the tabs above. ```typescript { name: string // Google's media id of the video projectId: string // the Google Flow project the video is in workflowId?: string // the Google Flow workflow (project item) that holds the video workflowStepId?: string // the workflow step, e.g. "CAE" (left out when Google's record has none) mediaMetadata: { // Google's record of the video createTime?: string // ISO 8601 time Google created the video mediaTitle?: string // the prompt, as Google Flow titles the video (an upscale has none) mediaBlobSize?: string // the MP4's size in bytes, as a string, once the video is done mediaStatus: { // whether the video was made mediaGenerationStatus: string // MEDIA_GENERATION_STATUS_PENDING | MEDIA_GENERATION_STATUS_ACTIVE | // MEDIA_GENERATION_STATUS_SUCCESSFUL | MEDIA_GENERATION_STATUS_FAILED | // MEDIA_GENERATION_STATUS_UNKNOWN error?: { // why the video failed code: number // Google's error code message: string // Google's reason, e.g. "PUBLIC_ERROR_IP_INPUT_IMAGE" } failureReasons?: string[] // Google's classifier labels for a failed video, e.g. "IP_PROHIBITED" } visibility?: string // "PRIVATE" (left out on a failed video) requestData: { // what the video was made from, as Google echoes it videoGenerationRequestData: { // the generation settings backend: 'flow' // the video was made on `flow.google.com` statusEnum: number | null // Google's raw status number: 6 queued, 1 and 2 running, 3 done, 4, 5 and 7 failed aspectEnum: number | null // Google's raw aspect number: 2 landscape, 1 portrait videoModelControlInput?: { // the model settings Google ran videoModelName?: string // Google's own key for the model that ran videoGenerationMode?: string // VIDEO_GENERATION_MODE_TEXT_TO_VIDEO | VIDEO_GENERATION_MODE_REFERENCE_TO_VIDEO | // VIDEO_GENERATION_MODE_VIDEO_EXTENSION (left out for the other modes) videoAspectRatio?: string // VIDEO_ASPECT_RATIO_LANDSCAPE | VIDEO_ASPECT_RATIO_PORTRAIT videoResolution?: string // VIDEO_RESOLUTION_360P | VIDEO_RESOLUTION_720P | VIDEO_RESOLUTION_1080P | // VIDEO_RESOLUTION_4K } } promptInputs?: Array<{ // the prompt as Google received it (an upscale has none) structuredPrompt: { // the prompt in parts parts: Array<{ // a run of text, or an @-mention text?: string // a run of prompt text reference?: object // an @-mention: { media: { mediaId, handle } }, { audio: { mediaId, handle } } or { entity: { entityId, handle } } }> } }> clientPlatform?: string // "CLIENT_PLATFORM_WEB" } } video: { // the video's details generatedVideo?: { // how Google made it (left out until Google reports it) seed: number // the seed Google used (0 when it reports none) prompt: string // the prompt as Google ran it (Veo rewrites it), an empty string on an upscale model: string // Google's own key for the model that ran baseImageMediaGenerationId?: string // an empty string on every video so far isLooped: false // always false aspectRatio: string // VIDEO_ASPECT_RATIO_LANDSCAPE | VIDEO_ASPECT_RATIO_PORTRAIT // (an empty string when Google reports none) upsampleMetadata?: { // on an upscaled video videoUpsampleResolution: string // VIDEO_UPSAMPLE_RESOLUTION_720P | VIDEO_UPSAMPLE_RESOLUTION_1080P // (left out for 4K) } } dimensions?: { // the clip's measurements (an upscaled clip has none) length: string // the clip's length, e.g. "8s" } operation: { // the generation operation name: string // the same as name } } mediaGenerationId?: string // the id to pass to the other endpoints (upscale, extend, GIF, concatenate, assets), on every finished answer, left out of the 201 answer videoUrl?: string // signed MP4 download URL, valid about 6 hours, once the video is done thumbnailUrl?: string // signed JPEG thumbnail URL, valid about 6 hours } ``` **`FlowCaptcha`**: the `captcha` in the tabs above. ```typescript { service?: string // the provider whose token Google accepted: `CapSolver`, `AntiCaptcha`, // `YesCaptcha`, `CapMonster`, `SolveCaptcha`, `2Captcha`, `EzCaptcha` or // `UserProvided`. Always on a success answer taskId?: string // that provider's task id (none for `UserProvided`) durationMs?: number // ms from the first solve to the token used. Always on a success answer error?: string // why no captcha token could be had, on a failed request attempts: Array<{ // every solve tried, in order, failed ones included service: string // the provider asked taskId?: string // that provider's task id durationMs: number // how long this solve took, in ms success: boolean // true when the provider returned a token (Google may still have refused it) error?: string // why the solve failed userAgent?: string // the browser user agent the provider solved with, when it reports one secChUa?: string // the Sec-CH-UA value the provider solved with, when it reports one (may be empty) cost?: string // the provider's price for this solve, as the provider reports it ip?: string // the IP address the provider reports for this solve createTime?: number // Unix time the provider started the solve, as it reports it endTime?: number // Unix time the provider finished the solve, as it reports it solveCount?: number // the provider's own solve counter for this task }> } ``` **`FlowReference`**: the video to upscale, `mediaGenerationId` in `request` above. ```typescript { user: number // your useapi.net user id, read from the reference email: string // the Google account the media belongs to, read from the reference type: 'image' | 'video' | 'character' // what the reference points to id: string // Google's media id (image or video), or the character's entity id referenceId: string // the reference you sent meta?: { // characters only imgs: number // how many images the character holds (they count toward the model's image limit) voiceWorkflowId?: string // the voice attached to the character, when it has one } } ``` </details> ### Missing media URLs Media URL fields are optional and can be absent even when generation succeeded. When `videoUrl`, `thumbnailUrl`, `fifeUrl`, `servingBaseUri`, `previewUrl` or `audioUrl` is missing, the media itself is fine — only the download link could not be produced at that moment. This is rare. Across the seven days of request logs we keep, it happened on one day only — twice, for about four hours and about forty minutes — and not at all on the other six. Google issues those links from an endpoint that limits how often it will answer a given network address, so it is Google limiting our outbound calls rather than useapi.net limiting you, and nothing you do triggers it. While it lasts it affects every account generating at that moment, then clears on its own. Your generation still completed and was charged as usual. On a media item that generated successfully — `mediaStatus.mediaGenerationStatus` is `MEDIA_GENERATION_STATUS_SUCCESSFUL` — a missing URL means "not yet", not "failed", so read the field before using it and treat its absence as a retry condition. A media item that failed generation never carries a URL, and retrying will not produce one. ``` javascript const url = media.videoUrl; if (!url) { // Not an error — the link is not available yet. See the options below. } ``` #### How to get the link Which route to use depends on whether you can wait. If you are already polling the job, do nothing special. Completed video jobs re-resolve missing URLs automatically on [GET /jobs/`jobId`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid), and the recovered link is saved, so a later poll returns it with no extra work on your side. This applies to video jobs created within the last 24 hours. Once the job is completed and a URL is still missing, leave at least a minute between polls — a job re-resolves at most once a minute, and the block clears only once traffic stops, so a tight retry loop lengthens the wait rather than shortening it. If you hold a `mediaGenerationId` but no longer have the job, ask for that one media again with [GET /assets/`mediaGenerationId`](/docs/api-google-flow-v1/get-google-flow-assets-mediagenerationid). That endpoint says which case you are in rather than leaving you to guess. A `503` with a `Retry-After` header means the link is coming and tells you how long to wait, so wait that long and ask again. A `404` means Google has no such media, and no amount of retrying will change it. If you cannot wait, download the video through us with [GET /assets/`mediaGenerationId``?raw=true`](/docs/api-google-flow-v1/get-google-flow-assets-mediagenerationid). It reads the media over a different Google route that the block does not touch, so it works immediately and keeps working while the other two return nothing. It is **video only**. Prefer the two link-based routes when you can. They hand you a link and you download straight from Google. The raw form moves the whole file through useapi.net on every call, which makes it a way out of a stuck download rather than your normal download path. Characters and voices resolve their URLs as they are read, so simply requesting [GET /characters/`ref`](/docs/api-google-flow-v1/get-google-flow-characters-ref) or [GET /voices/`ref`](/docs/api-google-flow-v1/get-google-flow-voices-ref) again is enough. Wait a minute before retrying — a response that came back without its URL is held briefly, so an immediate repeat returns the same one. None of this applies to images. Whenever an image URL is missing, [POST /images](/docs/api-google-flow-v1/post-google-flow-images) puts the image itself in the response instead, base64-encoded in `encodedImage` — so you already have the picture and there is nothing to retry. ### Examples **Curl** ``` bash # First generate a video curl -X POST \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"prompt": "A serene mountain landscape at sunset"}' \ "https://api.useapi.net/v1/google-flow/videos" > generate.json # Extract mediaGenerationId from the response MEDIA_ID=$(jq -r '.media[0].mediaGenerationId' generate.json) # Upscale the video to 1080p curl -X POST \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d "{\"mediaGenerationId\": \"$MEDIA_ID\", \"resolution\": \"1080p\"}" \ "https://api.useapi.net/v1/google-flow/videos/upscale" > upscale.json # Extract upscaled video URL and download VIDEO_URL=$(jq -r '.media[0].videoUrl' upscale.json) curl "$VIDEO_URL" --output upscaled_video.mp4 ``` **JavaScript** ``` javascript const token = 'YOUR_API_TOKEN'; // First generate a video const generateResponse = await fetch('https://api.useapi.net/v1/google-flow/videos', { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ prompt: 'A serene mountain landscape at sunset' }) }); const generated = await generateResponse.json(); // Prefer media[] over deprecated operations[] const mediaGenerationId = generated.media[0].mediaGenerationId; // Upscale the video const upscaleResponse = await fetch('https://api.useapi.net/v1/google-flow/videos/upscale', { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ mediaGenerationId, resolution: '1080p' }) }); const upscaled = await upscaleResponse.json(); // Prefer media[] over deprecated operations[] const videoUrl = upscaled.media[0].videoUrl; // Download upscaled video (Node.js) const videoResponse = await fetch(videoUrl); const videoBuffer = await videoResponse.arrayBuffer(); require('fs').writeFileSync('upscaled_video.mp4', Buffer.from(videoBuffer)); console.log('Upscaled video saved!'); ``` **Python** ``` python import requests token = 'YOUR_API_TOKEN' headers = { 'Authorization': f'Bearer {token}', 'Content-Type': 'application/json' } # First generate a video generate_response = requests.post( 'https://api.useapi.net/v1/google-flow/videos', headers=headers, json={'prompt': 'A serene mountain landscape at sunset'} ) generated = generate_response.json() # Prefer media[] over deprecated operations[] media_generation_id = generated['media'][0]['mediaGenerationId'] # Upscale the video upscale_response = requests.post( 'https://api.useapi.net/v1/google-flow/videos/upscale', headers=headers, json={ 'mediaGenerationId': media_generation_id, 'resolution': '1080p' } ) upscaled = upscale_response.json() # Prefer media[] over deprecated operations[] video_url = upscaled['media'][0]['videoUrl'] # Download upscaled video video_response = requests.get(video_url) with open('upscaled_video.mp4', 'wb') as f: f.write(video_response.content) print('Upscaled video saved!') ``` ### Try It <script> function displayUpscaledVideo(response, elementId) { const mediaContainer = document.getElementById(`${elementId}-media-links`); if (!mediaContainer) return; mediaContainer.innerHTML = ''; const mediaItems = response.media || []; const operations = response.operations || []; if (mediaItems.length === 0 && operations.length === 0) { mediaContainer.style.display = 'none'; return; } const videos = []; if (mediaItems.length > 0) { mediaItems.forEach((item, index) => { videos.push({ videoUrl: item.videoUrl, label: `Upscaled Video` }); }); } else { operations.forEach((op, index) => { if (op.rawBytes) { const dataUrl = `data:video/mp4;base64,${op.rawBytes}`; videos.push({ videoUrl: dataUrl, label: `Download Upscaled Video (rawBytes)`, isRawBytes: true }); } else if (op.operation?.metadata?.video) { const video = op.operation.metadata.video; videos.push({ videoUrl: video.fifeUrl, label: `Upscaled Video` }); } }); } if (videos.length > 0) { const linksHTML = videos.map(vid => { if (vid.isRawBytes) { return `<a href="${vid.videoUrl}" download="upscaled_video.mp4" class="media-link video">${vid.label}</a>`; } return `<a href="${vid.videoUrl}" target="_blank" rel="noopener noreferrer" class="media-link video">${vid.label}</a>`; }).join(' '); mediaContainer.innerHTML = `<div class="media-links-container"><strong>Upscaled Video:</strong> ${linksHTML}</div>`; mediaContainer.style.display = 'block'; } else { mediaContainer.style.display = 'none'; } } async function apiExecutePostGoogleFlowVideosUpscale() { const tokenElement = document.getElementById('input-token'); const elementId = 'input'; const payload = {}; const inputs = document.querySelectorAll('.input-query-param'); inputs.forEach(input => { const id = input.id; const value = input.value?.trim(); if (id.startsWith('input-') && value !== '' && value !== undefined) { const key = id.replace('input-', ''); if (key === 'captchaRetry') { payload[key] = parseInt(value); } else if (key === 'async') { payload[key] = value === 'true'; } else { payload[key] = value; } } }); const data = { method: 'POST', headers: { 'Authorization': `Bearer ${tokenElement.value}`, 'Content-Type': 'application/json' }, body: JSON.stringify(payload) }; const mediaLinks = document.getElementById(`${elementId}-media-links`); if (mediaLinks) mediaLinks.style.display = 'none'; const status = await apiExecute('https://api.useapi.net/v1/google-flow/videos/upscale', elementId, data, { includeTimer: true }); if (status === 200) { try { const content = document.getElementById(`${elementId}-response-json`); const response = JSON.parse(content.innerText); displayUpscaledVideo(response, elementId); } catch (e) { console.error('Failed to parse response for video display:', e); } } } </script> <form id="input" class="input-form" onsubmit="return false;"> <div class="input-field"> <div class="input-field-row"> <label for="input-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="input-token" type="text" class="input-element" required aria-required="true"> </label> <label for="input-mediaGenerationId"><span>mediaGenerationId (required, from <a href="/docs/api-google-flow-v1/post-google-flow-videos">POST /videos</a>)</span> <input id="input-mediaGenerationId" type="text" class="input-element input-query-param" required aria-required="true" placeholder="user:123-email:...-video:..."> </label> <label for="input-resolution"><span>resolution</span> <select id="input-resolution" class="input-element input-query-param"> <option value="720p">720p (from a 360p Omni clip)</option> <option value="1080p" selected>1080p (default)</option> <option value="4K">4K (Ultra only)</option> </select> </label> <label for="input-async"><span>async (fire-and-forget mode)</span> <select id="input-async" class="input-element input-query-param"> <option value="false">false (default)</option> <option value="true">true</option> </select> </label> <label for="input-replyUrl"><span>replyUrl (webhook URL)</span> <input id="input-replyUrl" type="text" class="input-element input-query-param" placeholder="https://your-domain.com/webhook"> </label> <label for="input-replyRef"><span>replyRef (custom reference)</span> <input id="input-replyRef" type="text" class="input-element input-query-param" placeholder="my-custom-id-123"> </label> <label for="input-captchaToken"><span>captchaToken (optional, your own reCAPTCHA token)</span> <input id="input-captchaToken" type="text" class="input-element input-query-param" placeholder="reCAPTCHA v3 Enterprise token"> </label> <label for="input-captchaRetry"><span>captchaRetry (1-10, optional)</span> <input id="input-captchaRetry" type="number" class="input-element input-query-param" min="1" max="10" placeholder="5"> </label> <label for="input-captchaOrder"><span>captchaOrder (optional)</span> <input id="input-captchaOrder" type="text" class="input-element input-query-param" placeholder="CapSolver,AntiCaptcha"> </label> </div> <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecutePostGoogleFlowVideosUpscale()">Go</button> </div> </form> <div id="input-media-links" style="display:none;"></div> <div id="input-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos === Document URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos description: "Generate Omni 1.2 Flash, Omni 1.1 Flash or Veo 3.1 AI videos via POST videos in the useapi.net Google Flow API v1 — 3 to 15 second clips, text-to-video, image-to-video, V2V edit, and voice narration." parent: Google Flow API nav_order: 700 --- ## Generate Videos November 17, 2025 (November 20, 2026) --- Generate videos using Google Flow AI models ([Omni 1.2 Flash](https://cloud.google.com/blog/products/ai-machine-learning/gemini-omni-1-2-flash-generally-available), [Omni 1.1 Flash](https://deepmind.google/models/model-cards/gemini-omni-flash/), [Veo 3.1 Quality](https://deepmind.google/technologies/veo/), [Veo 3.1 Fast](https://deepmind.google/technologies/veo/), [Veo 3.1 Lite](https://deepmind.google/technologies/veo/), [Veo 3.1 Lite Lower Priority](https://deepmind.google/technologies/veo/)) from text prompts with optional start/end frames, reference images, reference video (Omni V2V edit), and voice narration. Videos are returned as signed URLs ready for download. Omni 1.2 Flash (`omni-flash-1.2`) makes clips of any whole number of seconds from 3 to 15, at 360p or 720p, and is the model [POST /videos/extend](/docs/api-google-flow-v1/post-google-flow-videos-extend) extends with. Google released it on November 5, 2026. Google is giving Omni 1.2 Flash to accounts over several days from November 5, 2026. Until an account has it, a request for `omni-flash-1.2` on that account returns `400` straight away, before any captcha is solved. When the load balancer picks the account (no `email`), accounts that don't have the model yet are skipped. This endpoint features dynamic concurrency management. Video generation typically completes within 60-180 seconds depending on the model and mode. The endpoint automatically polls for completion and returns the final result. `Veo 3.1 Lite Lower Priority` is available only to [Google AI Ultra $199](https://one.google.com/ai) subscribers — no credit cost but lower generation priority. The cheaper Ultra $99 plan does not include it. Since 2026-09-23 Google no longer offers it to invited members of an Ultra $199 family plan — only the family manager's account keeps it. A member account still shows its Ultra credits, but the model is missing from its model list at [flow.google.com](https://flow.google.com). The API checks that model list, so a request for this model on a member account returns `400` straight away, before any captcha is solved. When the load balancer picks the account (no `email`, and no input image, reference, voice or character that ties the request to one account), member accounts are skipped for this model automatically. If Google still refuses the model on an account, the request returns `403` with `PUBLIC_ERROR_MODEL_ACCESS_DENIED` and the account is skipped for this model for an hour — see [Load Balancing Algorithm](/docs/api-google-flow-v1/get-google-flow-jobs#load-balancing-algorithm). ### Model Capabilities Two model families: [Veo 3.1](https://deepmind.google/technologies/veo/) (four variants) and Omni Flash (two versions, [Omni 1.2 Flash](https://cloud.google.com/blog/products/ai-machine-learning/gemini-omni-1-2-flash-generally-available) and [Omni 1.1 Flash](https://deepmind.google/models/model-cards/gemini-omni-flash/)). The `omni-flash` model value is Omni 1.1 Flash, the label the Flow interface has used since Google's August 26, 2026 update. `omni-flash-1.2` is Omni 1.2 Flash, a separate model with its own lengths and prices. The current label of each is shown as `displayName` on [GET /accounts/`email`](/docs/api-google-flow-v1/get-google-flow-accounts-email). #### Models *Veo figures: [Google Flow — Credits and pricing](https://support.google.com/flow/answer/16526234). Omni figures measured against the live API.* Omni 1.2 Flash is priced per second, the same on every plan: the first 10 seconds at the base rate and every second past 10 at twice that. An edit costs the same as a generation of the edited length. | Model | Generation type(s) | Credits per generation | |-------|---------------------|------------------------| | Veo 3.1 - Lite<br>`veo-3.1-lite` | 4s, 6s, 8s videos | **Non-Ultra:** 10<br>**Ultra:** 5 | | Veo 3.1 - Lite Lower Priority<br>`veo-3.1-lite-low-priority` | 4s, 6s, 8s videos | **Ultra $199 only:** 0 *(lower priority)* | | Veo 3.1 - Fast *(default until 2026-12-05)*<br>`veo-3.1-fast`<br>*retiring 2026-12-05, then runs as `veo-3.1-lite`* | 4s, 6s, 8s videos | **Non-Ultra:** 20<br>**Ultra:** 10 | | Veo 3.1 - Quality<br>`veo-3.1-quality`<br>*retiring 2026-12-05, then runs as `omni-flash-1.2` at 720p* | 4s, 6s, 8s videos | 100 | | Omni 1.2 Flash<br>`omni-flash-1.2` | 3s to 15s videos at 720p<br>Edit, Extend | **Every plan** *(Free: up to 10s, no extend)*:<br>3 per second up to 10s, 6 per second above<br>**3s:** 9 · **8s:** 24 · **10s:** 30 · **15s:** 60 | | Omni 1.2 Flash<br>`omni-flash-1.2` + `resolution: 360p` | 3s to 15s videos at 360p<br>Edit, Extend | **Every plan** *(Free: up to 10s, no extend)*:<br>1 per second up to 10s, 2 per second above<br>**3s:** 3 · **8s:** 8 · **10s:** 10 · **15s:** 20 | | Omni 1.1 Flash<br>`omni-flash`<br>*retiring 2026-12-05, then runs as `omni-flash-1.2`* | 4s, 6s, 8s, 10s videos at 720p<br>*(does not include edits to uploaded & generated videos)* | **Plus / Pro / Ultra:**<br>**4s:** 7<br>**6s:** 10<br>**8s:** 12<br>**10s:** 15 | | Omni 1.1 Flash<br>`omni-flash` + `resolution: 360p`<br>*retiring 2026-12-05* | 4s, 6s, 8s, 10s videos at 360p | **Plus / Pro / Ultra:**<br>**4s:** 4<br>**6s:** 5<br>**8s:** 6<br>**10s:** 7 | | Omni 1.1 Flash<br>`omni-flash` + `referenceVideo_1`<br>*retiring 2026-12-05* | Edit uploaded & generated videos of all lengths | **Plus / Pro / Ultra:** 20 at 720p, 10 at 360p | Requests for a retiring model keep working after December 5, 2026: from that day a request without `model` runs as `veo-3.1-lite`, the new default, and `omni-flash` at 720p costs about twice the credits (at 360p about the same). The job then shows the model that ran in `model`. #### Aspect ratio (`aspectRatio`) | Model | Supported values | |-------|------------------| | All Veo variants | **`landscape`** *(default)*, `portrait` | | `omni-flash-1.2`, `omni-flash` | **`landscape`** *(default)*, `portrait` | #### Duration (`duration`, sec) | Mode / Model | Supported | |--------------|-----------| | Veo T2V / I2V / I2V-FL | `4`, `6`, **`8`** *(default)* — `4`/`6` are Ultra-only | | Veo R2V | **`8`** only | | `omni-flash-1.2` T2V / R2V / I2V | any whole number from `3` to `15`, **`8`** *(default)* — `11` to `15` on paid plans only | | `omni-flash-1.2` I2V-FL | any whole number from `3` to `10`, **`8`** *(default)* | | `omni-flash-1.2` V2V edit | not accepted — output matches input trim window *(max 15 s, set via `endFrameIndex_1`, max 10 s on a free plan)* | | `omni-flash` T2V / R2V / I2V / I2V-FL | `4`, `6`, **`8`** *(default)*, `10` | | `omni-flash` V2V edit | not accepted — output matches input trim window *(max 10 s, set via `endFrameIndex_1`)* | #### References | Reference | Parameter(s) | Veo (all variants) | `omni-flash-1.2`, `omni-flash` | |-----------|--------------|:-:|:-:| | Start frame *(I2V)* | `startImage` | Yes | Yes *(the frame only — no `referenceImage_*`, no `character_*`, no `referenceAudio_*`)* | | Start + end frames *(I2V-FL)* | `startImage` + `endImage` | Yes | Yes *(frames only — no `referenceImage_*`, no `character_*`, no `referenceAudio_*`)* | | Image refs *(R2V / Ingredients)* | `referenceImage_1..10` | up to **3** *(slots `_1..3`)*; not on `veo-3.1-quality` | up to **10** on `omni-flash-1.2`, **7** on `omni-flash` *(R2V)* / up to **5** *(V2V edit)* | | Characters *(R2V / Ingredients)* | `character_1..10` *(from [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters))* | **3 total** with `referenceImage_*` — Veo fast/lite/lite-low-priority **only**, **8 s** only, **not** on `veo-3.1-quality` | **10 total** with `referenceImage_*` on `omni-flash-1.2`, **7** on `omni-flash` (R2V) | | Voice narration | `referenceAudio_1..5` *([POST /voices](/docs/api-google-flow-v1/post-google-flow-voices) refs OR system voice names)* | **1** *(slot `_1`, requires an image ref or character, R2V only)*; not on `veo-3.1-quality` | up to **5** *(R2V, requires an image ref or character)* / up to **3** *(V2V edit)* | | Source video *(V2V edit)* | `referenceVideo_1` *(+ optional `startFrameIndex_1` / `endFrameIndex_1`)* | — | Yes *(uploaded MP4, trim on a 24 fps virtual timeline, max 360 frames = 15 s on `omni-flash-1.2`, 240 frames = 10 s on `omni-flash`)* | ### Content Moderation If your generation is moderated, retrying with the same prompt often succeeds on subsequent attempts — moderation decisions can vary between requests. Modifying the prompt, removing reference images, or swapping models can also help, as each has different content-moderation behavior. One case does not improve on retry. `IP_PROHIBITED` means Google's intellectual-property classifier flagged an input image as containing copyrighted, branded or recognizable content, and since the image is unchanged a retry gets flagged again. Replace the reference image instead — original photos of non-famous subjects pass where celebrity photos, film stills, product shots and copyrighted characters do not. Despite how it reads, the "IP" here is intellectual property and has nothing to do with network addresses. ### Why a generation failed When every operation in a job fails, the top-level `error` reads `All operations failed` for all of them. The reason is in `response.failureReasons`, a de-duplicated list of everything Google said about the failed media. Two kinds of string arrive in it, and a job can carry either or both. Terminal codes name what went wrong, and the ones seen most are `PUBLIC_ERROR_UNSAFE_GENERATION`, `PUBLIC_ERROR_PROMINENT_PEOPLE_FILTER_FAILED`, `PUBLIC_ERROR_AUDIO_FILTERED`, `PUBLIC_ERROR_MINOR`, `PUBLIC_ERROR_SEXUAL`, `PUBLIC_ERROR_DANGER_FILTER`, `PUBLIC_ERROR_IP_INPUT_IMAGE` and, on V2V edits, `PUBLIC_ERROR_SPEECH_EDIT`. Classifier labels name which filter fired, such as `IP_PROHIBITED`. The list is Google's, not ours, so treat it as open-ended and match on substrings rather than on an exhaustive set. `PUBLIC_ERROR_SPEECH_EDIT` comes only from V2V edits (`referenceVideo_1`), and it is the most common named reason there: about a quarter of failed edits carry it. Google refuses the edit because of the speech in the clip and gives no detail beyond the code. The name points at an edit that changes what someone in the video says, so try a prompt that leaves the dialogue as it is, or a source clip without speech. The field is absent when Google returned no reason at all, which is common enough to code for — around half of V2V edit failures arrive with nothing attached. An absent `failureReasons` is not an error in itself, and those jobs are usually worth one retry. A job that failed before any operation started — a rejected request, a moderated prompt — never reaches this path. Those return the Google error verbatim instead, as shown in the [400 responses](#responses) above. #### Videos that failed on their sound `PUBLIC_ERROR_AUDIO_FILTERED`, with the label `AUDIO_GENERATION_FILTERED`, means the picture was fine but Google's audio filter rejected the sound generated with it. Every model makes sound along with the video, even for a prompt with no dialogue (ambient noise, music, effects), and Google checks that sound separately from the picture. When the filter rejects it, Google fails the whole video by default and charges no credits for it. It is the most common failure on `veo-3.1-lite` and the second most common on `veo-3.1-lite-low-priority`: about 1 in 5 `veo-3.1-lite` videos and 1 in 12 `veo-3.1-lite-low-priority` videos fail this way, about 1 in 25 on `veo-3.1-fast`, and fewer than 1 in 100 on the Omni models. What you can do: * If the video can do without its sound (b-roll, backgrounds, clips you put music or a voice-over on later), send `returnSilentVideos: true`. Such a video then comes back without sound instead of failing, and Google charges its credits like any other video. This is the "Return silent videos" setting in Google Flow's own settings, applied per request. * If you need the sound, send the request again: each attempt generates new sound, so the filter judges it anew. * An Omni model (`omni-flash-1.2`, `omni-flash`) hardly ever fails this way. > **https://api.useapi.net/v1/google-flow/videos** ### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ### Request Body ```json { "prompt": "A serene mountain landscape at sunset with camera slowly panning right", "model": "veo-3.1-fast", "aspectRatio": "landscape", "duration": 8, "count": 2 } ``` Parameters are grouped below. For per-model limits and modes see [Model Capabilities](#model-capabilities) above. #### Core - `prompt` is **required**, text description for video generation. - `model` is optional, the AI model to use for video generation (default: `veo-3.1-fast`, and `veo-3.1-lite` from December 5, 2026, when Google retires Veo 3.1 Fast). Supported values: `omni-flash-1.2`, `omni-flash`, `veo-3.1-quality`, `veo-3.1-fast`, `veo-3.1-lite`, `veo-3.1-lite-low-priority`. See [Model Capabilities](#model-capabilities). - `aspectRatio` is optional, output video aspect ratio (default: `landscape`). Supported values: `landscape`, `portrait`, for every model. - `duration` is optional, output video length in seconds (default: `8`). `omni-flash-1.2` takes any whole number from `3` to `15` (`3` to `10` with `startImage` + `endImage`, and up to `10` on a free Google plan). `omni-flash` takes `4`, `6`, `8`, `10`. Veo takes `4`, `6`, `8`. See [Model Capabilities](#model-capabilities). Not accepted by a V2V edit (output length matches the input trim window). - `resolution` is optional, output resolution (default: `720p`). Supported values: `360p`, `720p`. Omni models only — Veo publishes no 360p variant, so `360p` on a Veo model is rejected rather than silently generating 720p at full price. On `omni-flash-1.2` a 360p generation costs a third of the same request at 720p, on `omni-flash` roughly half. A 360p clip can be promoted afterwards with [POST /videos/upscale](/docs/api-google-flow-v1/post-google-flow-videos-upscale). - `count` is optional, number of video variations to generate (1-4, default: `1`). #### Account selection - `email` is optional, the Google Flow account to use. When only one [account](/docs/api-google-flow-v1/get-google-flow-accounts) is configured, the API will automatically use that account. With multiple [accounts](/docs/api-google-flow-v1/get-google-flow-accounts) configured, omitting the email parameter triggers automatic [load balancing](/docs/api-google-flow-v1/get-google-flow-jobs#load-balancing-algorithm) based on **video generation** job statistics to select the healthiest account. If `startImage`, `endImage`, `referenceImage_*`, or `referenceVideo_1` are provided, the `email` parameter can be omitted — the API will automatically use the same account where the references were uploaded. #### Image references - `startImage` is optional, mediaGenerationId from [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email) for I2V mode (video starts with this frame). Supported on Veo and both Omni models, all of which also accept `endImage`. - `endImage` is optional, mediaGenerationId from [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email) for I2V-FL mode (video ends with this frame, requires `startImage`). End-frame-only is not supported. On the Omni models the two frames are the only accepted input, so `referenceImage_*`, `character_*` and `referenceAudio_*` are rejected alongside them. - `referenceImage_1` to `referenceImage_10` are optional, mediaGenerationId from [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email) for R2V mode. Slots `_1`..`_3` work on Veo (max 3, not `veo-3.1-quality`) and both Omni models, slots `_4`..`_7` on the Omni models only, slots `_8`..`_10` on `omni-flash-1.2` only. Cannot be combined with `startImage`/`endImage`. #### Characters - `character_1` to `character_10` are optional, character reference-ids from [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters). Triggers R2V (Ingredients) mode just like `referenceImage_*` does. Each character's image count rolls into the model's image-ref budget (see [Model Capabilities › References](#references)): - **Veo 3.1 Fast / Lite / Lite Lower Priority** (`veo-3.1-fast`, `veo-3.1-lite`, `veo-3.1-lite-low-priority`) — characters supported in 8 s only; `referenceImages.length + Σ(character.imgs) ≤ 3`. - **Omni 1.2 Flash and Omni 1.1 Flash** (`omni-flash-1.2`, `omni-flash`) — characters supported in all durations. `referenceImages.length + Σ(character.imgs) ≤ 10` on `omni-flash-1.2`, `≤ 7` on `omni-flash`. - **Veo 3.1 Quality** (`veo-3.1-quality`) — characters NOT supported (no Ingredients mode). #### Voice narration - `referenceAudio_1` to `referenceAudio_5` are optional. Each slot accepts either a system voice name (case-insensitive, one of the 30 presets) or a user voice from [POST /voices](/docs/api-google-flow-v1/post-google-flow-voices). Per-model limits are in the [References table](#references) above. System voice presets (30 names): ```json [ "Achird", "Achernar", "Algieba", "Algenib", "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" ] ``` System voice samples: <code>https://www.gstatic.com/aitestkitchen/voices/samples/{Name}.wav</code> To list user (custom) voices on an account: [GET /voices?email=...&source=user](/docs/api-google-flow-v1/get-google-flow-voices). To preview a single voice (system or user): [GET /voices/`ref`](/docs/api-google-flow-v1/get-google-flow-voices-ref). #### Silent videos - `returnSilentVideos` is optional (default: `false`). Every model generates sound with the video, and Google checks that sound with its own audio filter. When the filter rejects it, `false` fails the video with `PUBLIC_ERROR_AUDIO_FILTERED` and Google charges nothing for it. `true` returns the video without sound, charged like any other video. It is the same as "Return silent videos" in Google Flow's settings, applied to this request only, whatever the account's own setting says. See [Videos that failed on their sound](#videos-that-failed-on-their-sound). #### Video reference (Omni V2V edit) - `referenceVideo_1` is optional (Omni models only), mediaGenerationId of a video uploaded via [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email), or of a video this API generated or edited earlier. Switches the request into V2V edit mode. Cannot be combined with `startImage`/`endImage`. - `startFrameIndex_1` is optional (Omni V2V only, paired with `referenceVideo_1`), trim start on a 24 fps virtual timeline. Range: 0-359 on `omni-flash-1.2`, 0-239 on `omni-flash`. Default: `0`. - `endFrameIndex_1` is optional (Omni V2V only, paired with `referenceVideo_1`), trim end on a 24 fps virtual timeline. Range: 1-360 on `omni-flash-1.2` (360 = 15 s), 1-240 on `omni-flash` (240 = 10 s). Default: the end of the clip, or the model's maximum for longer clips. Must be greater than `startFrameIndex_1`. On a free Google plan an `omni-flash-1.2` edit covers at most 10 s (240 frames). An edit works on a slice of the input video, and `startFrameIndex_1` / `endFrameIndex_1` pick that slice. Google counts 24 frames per second, so frame 24 is one second in, frame 120 is five seconds in, and frame 240 is ten seconds in. The output is that slice re-rendered with your edit, so it is exactly as long as the slice. There is no duration parameter on an edit. On `omni-flash-1.2` an edit costs the same as a generation of the slice's length (a 3 s slice at 360p costs 3 credits). The table shows `omni-flash`. On `omni-flash-1.2` the same rules hold with a 15 s (360 frame) maximum, so a 13 s clip is edited whole. | Input clip | You send | Slice used | Output | |---|---|---|---| | 10 s | nothing | frames 0 to 240 | 10 s | | 10 s | `endFrameIndex_1: 120` | frames 0 to 120 | 5 s | | 13 s | nothing | frames 0 to 240 | 10 s, the last 3 s of the input are not used | | 8 s | nothing | frames 0 to 192 | 8 s | An edit does not add time to a video. The motion follows the source closely: in our tests the edit reproduced the source's first and last frames almost exactly, and a prompt asking it to begin elsewhere was ignored. Feeding the output back in as the next `referenceVideo_1` with a new line to say gives you a new take of the same seconds, with the voice and the gestures carried over from the source. To make a clip longer, use [POST /videos/extend](/docs/api-google-flow-v1/post-google-flow-videos-extend), which adds up to 10 seconds at a time with Omni 1.2 Flash and returns one continuous clip. Chaining edits is the other way to get a longer piece out of an Omni clip, and the joins can be made invisible with one precaution at the start. Because every edit opens and closes on the same frames as its source, the only thing that shows at a join is the difference between the source's own first and last frame. Remove it at the seed: generate a still of the presenter at rest with [POST /images](/docs/api-google-flow-v1/post-google-flow-images), make the first clip with that still as both `startImage` and `endImage`, and every edit chained from it opens and closes on that same frame. Join the run with [POST /videos/concatenate](/docs/api-google-flow-v1/post-google-flow-videos-concatenate) and the cuts land still-to-still. The quiet beat that pins each clip to the still also shows at a join as a hold, about half a second before the presenter speaks and a third of a second of settling after, so trim it there: roughly `trimEnd: 0.375` on every clip but the last and `trimStart: 0.458` on every clip but the first leaves two frames of rest across each cut. Measured on a 4-second talking head, the joins were then indistinguishable from the motion inside the clips and the longest hold was an eighth of a second. **Google's V2V moderation is non-deterministic.** The exact same body can land on a content-safety reject (`IDENTIFIABLE_PERSON_SAFETY`, `CHILD_SAFETY`, etc.) on one attempt and a clean success on the next. A simple resubmit usually clears it — no input changes needed. #### Inline `@`-mention markers (optional) You can place `@`-markers inside `prompt` that resolve to the body parameters you supply. Markers are **case-insensitive** and **opt-in** — a prompt with no markers behaves exactly like before. Supported markers (one per body slot): | Marker | Resolves to | |---|---| | `@character_1..10` | matching `character_N` body param | | `@referenceImage_1..10` | matching `referenceImage_N` body param | | `@referenceAudio_1..5` | matching `referenceAudio_N` body param | | `@referenceVideo_*` | **NOT supported inline** — pass `referenceVideo_1` as a body field. The API returns **400** if it appears in `prompt`. | **Rules:** - Each marker MUST have a matching body slot supplied. Otherwise the API returns **400** with `'character_N' was not provided in the request body`. - A slot referenced inline still goes into the upstream reference array — markers are positional/grounding info, not a replacement for the body params. - Same slot may be inlined multiple times in one prompt; the upstream reference array de-duplicates by id. - Body params supplied but NOT inlined still flow to the upstream reference array (unchanged behavior). - Unknown strings like `@gmail.com` or `@anyword_1` (no `_<digit>` after a recognized slot name) pass through as literal prompt text. **Example:** ```json { "model": "omni-flash", "prompt": "@character_1 sitting on @referenceImage_1, @character_2 standing beside, @referenceImage_2 visible in the background, smooth camera dolly", "character_1": "user:123-email:...-character:...-imgs:1", "character_2": "user:123-email:...-character:...-imgs:1", "referenceImage_1": "user:123-email:...-image:...", "referenceImage_2": "user:123-email:...-image:..." } ``` #### Async & callbacks - `async` is optional, enables fire-and-forget mode (default: `false`). When `true`, returns immediately with `201 Created` and job metadata. Poll [GET /jobs/`jobId`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid) for completion status. Useful for avoiding long request timeouts since video generation takes 60-180 seconds. - `replyUrl` is optional, webhook URL for job status callbacks. Receives POST requests with job status updates (`created`, `started`, `completed`, `failed`). The JSON payload shape matches [GET /jobs/`jobId`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid) response. - `replyRef` is optional, custom reference string passed back in webhook callbacks. Useful for tracking jobs on your end. #### Captcha - `captchaToken`, `captchaRetry`, `captchaOrder` are optional, mutually exclusive captcha parameters. See [Captcha Parameters](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers#captcha-parameters) for details. ### Responses **200** **200 OK** Videos generated successfully. All video data is in the `media[]` array. ```json { "jobId": "j1117123456789304152v-u12345-email:john@gmail.com-bot:google-flow", "operations": [], "media": [ { "name": "a1d95d21-75d2-482d-a354-14ef8802ce66", "projectId": "9f63078c-...redacted...", "workflowId": "fa986834-...redacted...", "workflowStepId": "CAE", "mediaMetadata": { "createTime": "2026-11-15T23:14:02.931677Z", "mediaTitle": "A serene mountain landscape at sunset with camera slowly panning right", "mediaBlobSize": "6895556", "mediaStatus": { "mediaGenerationStatus": "MEDIA_GENERATION_STATUS_SUCCESSFUL" }, "visibility": "PRIVATE", "requestData": { "videoGenerationRequestData": { "backend": "flow", "statusEnum": 3, "aspectEnum": 2, "videoModelControlInput": { "videoModelName": "veo_3_1_t2v_fast", "videoGenerationMode": "VIDEO_GENERATION_MODE_TEXT_TO_VIDEO", "videoAspectRatio": "VIDEO_ASPECT_RATIO_LANDSCAPE", "videoResolution": "VIDEO_RESOLUTION_720P" } }, "promptInputs": [ { "structuredPrompt": { "parts": [ { "text": "A serene mountain landscape at sunset with camera slowly panning right" } ] } } ], "clientPlatform": "CLIENT_PLATFORM_WEB" } }, "video": { "generatedVideo": { "seed": 123456, "prompt": "A serene mountain landscape at sunset with camera slowly panning right", "model": "veo_3_1_t2v_fast", "baseImageMediaGenerationId": "", "isLooped": false, "aspectRatio": "VIDEO_ASPECT_RATIO_LANDSCAPE" }, "dimensions": { "length": "8s" }, "operation": { "name": "a1d95d21-75d2-482d-a354-14ef8802ce66" } }, "videoUrl": "https://flow-content.google/video/a1d95d21-...redacted...?Expires=...", "thumbnailUrl": "https://flow-content.google/image/a1d95d21-...redacted...?Expires=...", "mediaGenerationId": "user:12345-email:6a6f...-video:a1d95d21-75d2-482d-a354-14ef8802ce66" } ], "remainingCredits": 18760, "captcha": { "service": "AntiCaptcha", "taskId": "931846120", "durationMs": 15243, "attempts": [ { "service": "AntiCaptcha", "success": true, "durationMs": 15243, "cost": "0.00200", "ip": "203.0.113.24", "createTime": 1794787642, "endTime": 1794787657, "solveCount": 0, "taskId": "931846120", "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/153.0.0.0 Safari/537.36" } ] } } ``` **201** **201 Created** Job created in async mode (`async: true`). Video generation is processing in the background. Use [GET /jobs/`jobId`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid) to poll for completion status. ```json { "jobid": "j1117123456789304152v-u12345-email:john@gmail.com-bot:google-flow", "type": "video", "status": "created", "created": "2025-11-17T12:34:56.789Z", "request": { "email": "john@gmail.com", "prompt": "A serene mountain landscape at sunset with camera slowly panning right", "model": "veo-3.1-fast", "aspectRatio": "landscape", "duration": 8, "count": 2, "async": true, "replyUrl": "https://your-domain.com/webhook", "replyRef": "custom-reference-123" }, "response": { "operations": [], "media": [ { "name": "1450903d-...redacted...-9c86f0", "projectId": "9f63078c-...redacted...", "workflowId": "b3e1c0de-...redacted...", "workflowStepId": "CAE", "mediaMetadata": { "createTime": "2025-11-17T12:34:58.102934Z", "mediaTitle": "A serene mountain landscape at sunset with camera slowly panning right", "mediaStatus": { "mediaGenerationStatus": "MEDIA_GENERATION_STATUS_PENDING" }, "visibility": "PRIVATE", "requestData": { "videoGenerationRequestData": { "backend": "flow", "statusEnum": 6, "aspectEnum": 2, "videoModelControlInput": { "videoModelName": "veo_3_1_t2v_fast", "videoGenerationMode": "VIDEO_GENERATION_MODE_TEXT_TO_VIDEO", "videoAspectRatio": "VIDEO_ASPECT_RATIO_LANDSCAPE", "videoResolution": "VIDEO_RESOLUTION_720P" } }, "promptInputs": [ { "structuredPrompt": { "parts": [{ "text": "A serene mountain landscape at sunset with camera slowly panning right" }] } } ], "clientPlatform": "CLIENT_PLATFORM_WEB" } }, "video": { "generatedVideo": { "seed": 527083, "prompt": "A serene mountain landscape at sunset with camera slowly panning right", "model": "veo_3_1_t2v_fast", "baseImageMediaGenerationId": "", "isLooped": false, "aspectRatio": "VIDEO_ASPECT_RATIO_LANDSCAPE" }, "dimensions": { "length": "8s" }, "operation": { "name": "1450903d-...redacted...-9c86f0" } } }, { "name": "f2eec9bd-...redacted...-e16f7a", "projectId": "9f63078c-...redacted...", "workflowId": "c47a90b1-...redacted...", "workflowStepId": "CAE", "mediaMetadata": { "createTime": "2025-11-17T12:34:58.102934Z", "mediaTitle": "A serene mountain landscape at sunset with camera slowly panning right", "mediaStatus": { "mediaGenerationStatus": "MEDIA_GENERATION_STATUS_PENDING" }, "visibility": "PRIVATE", "requestData": { "videoGenerationRequestData": { "backend": "flow", "statusEnum": 6, "aspectEnum": 2, "videoModelControlInput": { "videoModelName": "veo_3_1_t2v_fast", "videoGenerationMode": "VIDEO_GENERATION_MODE_TEXT_TO_VIDEO", "videoAspectRatio": "VIDEO_ASPECT_RATIO_LANDSCAPE", "videoResolution": "VIDEO_RESOLUTION_720P" } }, "promptInputs": [ { "structuredPrompt": { "parts": [{ "text": "A serene mountain landscape at sunset with camera slowly panning right" }] } } ], "clientPlatform": "CLIENT_PLATFORM_WEB" } }, "video": { "generatedVideo": { "seed": 81946, "prompt": "A serene mountain landscape at sunset with camera slowly panning right", "model": "veo_3_1_t2v_fast", "baseImageMediaGenerationId": "", "isLooped": false, "aspectRatio": "VIDEO_ASPECT_RATIO_LANDSCAPE" }, "dimensions": { "length": "8s" }, "operation": { "name": "f2eec9bd-...redacted...-e16f7a" } } } ], "captcha": { "service": "CapSolver", "taskId": "14af1dbb-885c-4e25-8121-7a79489dfd0e", "durationMs": 5357, "attempts": [ { "service": "CapSolver", "success": true, "durationMs": 5357, "taskId": "14af1dbb-885c-4e25-8121-7a79489dfd0e", "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/153.0.0.0 Safari/537.36", "secChUa": "\"Google Chrome\";v=\"153\", \"Not_A Brand\";v=\"8\", \"Chromium\";v=\"153\"" } ] }, "captchaAttemptsCount": 1, "captchaProviders": "CapSolver", "tier": "PAYGATE_TIER_TWO", "sku": "G1_TIER2", "remainingCredits": 24235 } } ``` **400** **400 Bad Request** Invalid request (validation error, mode conflict, email mismatch, or content policy violation). **Validation error:** ```json { "error": "Model 'veo-3.1-quality' does not support R2V mode (MULTI_REFERENCE_NO_STYLE)", "code": 400 } ``` **Model not offered on this account** (`veo-3.1-lite-low-priority` on an invited member of an Ultra $199 family plan, answered before any captcha is solved): ```json { "error": "Google no longer offers veo-3.1-lite-low-priority on this account (user@gmail.com). Since 2026-09-23 invited members of a Google AI Ultra $199 family plan do not have it — only the family manager's account keeps it. Use an account that still lists it at flow.google.com, or another model.", "code": 400 } ``` **Content policy error:** ```json { "jobId": "j1117123456789304152v-u12345-email:john@gmail.com-bot:google-flow", "error": "PUBLIC_ERROR_UNSAFE_GENERATION (HTTP 400)", "code": 400, "response": { "error": { "code": 400, "message": "flow.google.com YhhmEf failed", "status": "INVALID_ARGUMENT", "details": [ { "@type": "type.googleapis.com/google.rpc.ErrorInfo", "reason": "PUBLIC_ERROR_UNSAFE_GENERATION" } ] }, "captcha": { "service": "CapSolver", "taskId": "14af1dbb-885c-4e25-8121-7a79489dfd0e", "durationMs": 5357, "attempts": [ { "service": "CapSolver", "success": true, "durationMs": 5357, "taskId": "14af1dbb-885c-4e25-8121-7a79489dfd0e" } ] } } } ``` **All operations failed (during polling):** The top-level `error` is always the same sentence, so the reason is in `response.failureReasons` — see [Why a generation failed](#why-a-generation-failed) above. Each video in `response.media` also carries its own reason (shortened here to the fields that matter). ```json { "jobId": "j1117123456789304152v-u12345-email:john@gmail.com-bot:google-flow", "error": "All operations failed", "code": 400, "response": { "operations": [], "media": [ { "name": "a629a9...redacted", "projectId": "9f63078c-...redacted...", "mediaMetadata": { "mediaStatus": { "mediaGenerationStatus": "MEDIA_GENERATION_STATUS_FAILED", "error": { "code": 3, "message": "PUBLIC_ERROR_MINOR" } }, "requestData": { "videoGenerationRequestData": { "backend": "flow", "statusEnum": 4, "aspectEnum": 2 } } }, "video": { "operation": { "name": "a629a9...redacted" } }, "mediaGenerationId": "user:12345-email:6a6f...-video:a629a9...redacted" } ], "remainingCredits": 18760, "failureReasons": [ "PUBLIC_ERROR_MINOR" ], "captcha": { "service": "CapSolver", "taskId": "14af1dbb-885c-4e25-8121-7a79489dfd0e", "durationMs": 5357, "attempts": [ { "service": "CapSolver", "success": true, "durationMs": 5357, "taskId": "14af1dbb-885c-4e25-8121-7a79489dfd0e" } ] } } } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **402** **402 Payment Required** Subscription expired or insufficient credits. ```json { "error": "useapi.net ⁝ Your account has no subscription, please subscribe to our services before submitting requests", "code": 402 } ``` **403** **403 Forbidden** Google rejected the captcha on every try. We retry with a fresh captcha as many times as you allow (`captchaRetry`, default 5, or the providers in `captchaOrder`) and return this `403` only when all of them were rejected. The top-level `error` starts with `captcha_quality:`, for example `"captcha_quality: PUBLIC_ERROR_UNUSUAL_ACTIVITY after 5 attempts. Google refused all 5 captcha tokens for user@example.com, so nothing was generated and no Google Flow credits were used (5 captcha solves were spent). Google is flagging this account's requests as unusual activity. If it keeps happening, use another account, or leave out email so the API picks one. See GET /accounts/captcha-stats summary.by_account"`. A `429` with `PUBLIC_ERROR_UNUSUAL_ACTIVITY_TOO_MUCH_TRAFFIC` reads the same way. Two `403`s are not a captcha problem, and we answer them after one try instead of retrying. `PUBLIC_ERROR_MODEL_ACCESS_DENIED` in the response means Google refused the model on that account, so raising `captchaRetry` or adding providers will not help. Check that the account's plan includes the model. Since 2026-09-23 Google no longer offers `veo-3.1-lite-low-priority` to invited members of an Ultra $199 family plan — only the family manager's account keeps it. `PUBLIC_ERROR_USER_MINOR` means Google treats the Google account as belonging to someone under 18, and Google Flow is not available to such accounts. The `error` says so in plain words. No captcha or retry changes it: use another Google account, or have this one's age verified with Google first. With `email` omitted, the load balancer sets such an account aside for 1 hour, then tries it again. Nothing was created when this happens. Google checks the captcha before it starts generating, so no Google credits were used and you can resubmit straight away. Your captcha provider still bills each solve. The usual cause is the Google account, not the captcha provider. Google gives each account its own trust level. On a trusted account it accepts about 9 in 10 captchas, on a distrusted one about 3 in 10, whichever provider solved them. Most customers have a few distrusted accounts among many good ones. To see which accounts are affected, use [GET /accounts/captcha-stats](/docs/api-google-flow-v1/get-google-flow-accounts-captcha-stats). Its `summary.by_account` shows, for each of your Google accounts, how many captchas were tried and what share Google accepted. [GET account/stats](/docs/account-management/get-account-stats) with `bot=google-flow` also shows how many requests each account finished with each response code. - If one or a few accounts are far below the others, the API already sends them less work: when you leave out `email`, each captcha Google rejected on an account in the last 15 minutes lowers its chance of being picked, for generations and for image uploads. They still get some work, so an account that recovers gets its full share back. If you pin requests with `email`, move them to your other accounts yourself. Replace an account that stays low for more than a day or two. - If all your accounts drop at the same time, it's the captcha provider. Configure at least two providers with [POST /accounts/captcha-providers](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers), and the API will start with whichever one Google accepts best. A higher `captchaRetry` gets more requests through on a distrusted account, but every extra try is another paid solve. **404** **404 Not Found** Account not found or not configured. ```json { "error": "Google Flow account john@gmail.com not found", "code": 404 } ``` **408** **408 Request Timeout** Video generation polling timeout (after 10 minutes). ```json { "error": "Video generation polling timeout after 120 attempts (600s)", "code": 408 } ``` **429** **429 Too Many Requests** Google returns several `RESOURCE_EXHAUSTED` 429 variants. Check the `reason` field and respond accordingly: | Reason | Meaning | Scope | What to do | Cooldown | |--------|---------|-------|------------|----------| | `PUBLIC_ERROR_`<br>`USER_REQUESTS_THROTTLED` | Google is throttling the account (the token was fine). Uploads and generation are metered separately | All models on the account — or uploads only, when POST /assets triggered it | Run fewer parallel requests, or switch accounts. From POST /assets, retrying the same one rarely clears it | ~30 min. From POST /assets, treat it as a minimum — it can persist | | `PUBLIC_ERROR_`<br>`USER_QUOTA_REACHED` | Account's overall Flow quota cap | All models on the account | Add accounts, or omit `email` to load-balance | ~30 min | | `PUBLIC_ERROR_`<br>`PER_MODEL_DAILY_QUOTA_REACHED` | Per-model daily quota | Only that model, on that account | Switch model, or wait | Next UTC midnight | | `PUBLIC_ERROR_`<br>`UNUSUAL_ACTIVITY_TOO_MUCH_TRAFFIC` | Google rejected the captcha on every try (we already retried). Usually a distrusted Google account, sometimes the provider | Per request | Check which accounts are affected in [captcha-stats](/docs/api-google-flow-v1/get-google-flow-accounts-captcha-stats#when-google-rejects-captchas). Rest or replace those accounts. Add a second provider if all accounts drop together | 60s | Every `429` returns the cooldown two ways — an HTTP `Retry-After: <seconds>` header and a body `retryAfter: <ISO timestamp>` field. Honor it before retrying. When `email` is omitted, the first three reasons quarantine the account and the load balancer routes around it. If every account is quarantined for the model you get `429` with `error: "no_eligible_account"`. Routing details: [GET /jobs › Load Balancing Algorithm](/docs/api-google-flow-v1/get-google-flow-jobs#load-balancing-algorithm). Captcha-quality failures prefix the top-level `error` with `captcha_quality:` (e.g. `"captcha_quality: PUBLIC_ERROR_UNUSUAL_ACTIVITY_TOO_MUCH_TRAFFIC after 3 attempts"`) so you can detect them without parsing the nested body. **503** **503 Service Unavailable** `503` has two distinct causes — check the response body to tell them apart. A transient Google-side outage. Wait 5-10 seconds and retry. ```json { "error": { "code": 503, "message": "Service temporarily unavailable.", "status": "UNAVAILABLE" } } ``` A captcha-provider failure — the top-level `error` is prefixed `Captcha service failed:`. The problem is your captcha provider (check its API key and balance), not Google. Don't retry until the provider is back. ```json { "error": "Captcha service failed: ERROR_ZERO_BALANCE", "code": 503 } ``` **596** **596 Session Error** Google rejected the account's session, and the API is re-verifying the account on its own: retry in about a minute. If Google signed the account out, the account keeps answering `596` and you get a reconnect email: add it again by following [Setup Google Flow](/docs/start-here/setup-google-flow). ```json { "error": "Google Flow account john@gmail.com Google rejected this account session (HTTP 401). We are automatically re-verifying it — please retry in about a minute. If the account was signed out, you will receive a reconnect email.", "code": 596 } ``` ### Model One tab per answer: the finished videos (`200`, sync), the job record (`201`, async) and a failed job. <details markdown="block" class="model-details"> <summary>The answer for each status, field by field, and the types it uses (<code>FlowVideoMedia</code>, <code>FlowCaptcha</code>, <code>FlowReference</code>)</summary> **200 OK (Sync)** Video generation completed. Returns full video data with signed URLs. `FlowVideoMedia` and `FlowCaptcha` are described below the tabs. ```typescript { jobId: string // the job id, for GET /jobs/{jobid} operations: [] // always empty, kept for older clients: read media[] media: FlowVideoMedia[] // one item per video remainingCredits?: number // the account's Google Flow credits left, as Google last reported them captcha: FlowCaptcha // the captcha solved for this request } ``` **201 Created (Async)** Job created and processing in background. Structure matches [GET /jobs/`jobId`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid) response. References you sent come back decoded, as `FlowReference` objects (described below the tabs). ```typescript { jobid: string // the job id, for GET /jobs/{jobid} type: 'video' // the job type status: 'created' // the job status created: string // ISO 8601 time the job was created request: { // the request as you sent it, after validation email: string // the account the job runs on (the one you named, or the one the API picked) prompt: string // the prompt model?: string // the model you asked for aspectRatio?: string // the aspect ratio you asked for duration?: number // the length you asked for, in seconds resolution?: string // the resolution you asked for count?: number // how many videos you asked for startImage?: FlowReference // the first-frame image endImage?: FlowReference // the last-frame image referenceImage_1?: FlowReference // a reference image referenceImage_2?: FlowReference // a reference image referenceImage_3?: FlowReference // a reference image referenceImage_4?: FlowReference // a reference image referenceImage_5?: FlowReference // a reference image referenceImage_6?: FlowReference // a reference image referenceImage_7?: FlowReference // a reference image referenceImage_8?: FlowReference // a reference image referenceImage_9?: FlowReference // a reference image referenceImage_10?: FlowReference // a reference image character_1?: FlowReference // a character character_2?: FlowReference // a character character_3?: FlowReference // a character character_4?: FlowReference // a character character_5?: FlowReference // a character character_6?: FlowReference // a character character_7?: FlowReference // a character character_8?: FlowReference // a character character_9?: FlowReference // a character character_10?: FlowReference // a character referenceAudio_1?: string // a voice: a built-in voice name (lowercase) or your voice reference referenceAudio_2?: string // a voice: a built-in voice name (lowercase) or your voice reference referenceAudio_3?: string // a voice: a built-in voice name (lowercase) or your voice reference referenceAudio_4?: string // a voice: a built-in voice name (lowercase) or your voice reference referenceAudio_5?: string // a voice: a built-in voice name (lowercase) or your voice reference referenceVideo_1?: FlowReference // the video to edit startFrameIndex_1?: number // the first frame of the video to edit endFrameIndex_1?: number // the last frame of the video to edit returnSilentVideos?: boolean // true: a video whose sound Google's filter rejects comes back silent captchaToken?: string // the captcha token you sent captchaRetry?: number // the captcha retries you asked for captchaOrder?: string[] // the captcha providers you listed, in order async: true // answer at once, the job runs in the background replyUrl?: string // your callback URL replyRef?: string // your reference, sent back in callbacks } model?: string // the model that ran, only when it is not the one you asked for (a retired model, routed to its replacement) response: { // Google's answer so far operations: [] // always empty, kept for older clients: read media[] media: FlowVideoMedia[] // one item per video, still being made (no mediaGenerationId or URLs yet) captcha: FlowCaptcha // the captcha solved for this request captchaAttemptsCount: number // how many captcha solves were tried, one per entry of captcha.attempts captchaProviders: string // the providers tried, comma-separated, in the order tried tier: string // the account's Google plan tier when the job started, as Google reports it, e.g. "PAYGATE_TIER_TWO" sku: string // the account's Google plan code when the job started, e.g. "G1_TIER2" remainingCredits?: number // the account's Google Flow credits left, as Google reported them at submit } } ``` **Error** Error response structure (applies to both sync and async modes). ```typescript { jobId?: string // the job id, when the job had been created error: string // what went wrong, e.g. "All operations failed" or "PUBLIC_ERROR_UNSAFE_GENERATION (HTTP 400)" code?: number // the HTTP status retryAfter?: string // ISO 8601 time to retry after, on a 429 (the Retry-After header carries the same in seconds) response?: { // what the job held when it failed failureReasons?: string[] // why every video failed: Google's terminal codes and classifier labels, de-duplicated, // e.g. PUBLIC_ERROR_IP_INPUT_IMAGE or IP_PROHIBITED. Present only when all videos // failed and Google gave a reason operations?: [] // always empty, kept for older clients media?: FlowVideoMedia[] // every video of the job, when none was made: each carries its own reason in mediaMetadata.mediaStatus remainingCredits?: number // the account's Google Flow credits left, as Google last reported them error?: string | { // Google's error when Google refused the request, or our own text (e.g. a polling timeout) code: number // HTTP status Google answered message: string // the error message, e.g. "flow.google.com YhhmEf failed" status: string // Google's status name, e.g. "RESOURCE_EXHAUSTED" details: Array<{ // Google's error details '@type': string // the type name of the detail reason: string // Google's reason code, e.g. "PUBLIC_ERROR_USER_QUOTA_REACHED" }> } captcha?: FlowCaptcha // the captcha tried or used captchaAttemptsCount?: number // how many captcha solves were tried, when the job failed before its first poll captchaProviders?: string // the providers tried, comma-separated, when the job failed before its first poll tier?: string // the account's Google plan tier, when the job failed before its first poll sku?: string // the account's Google plan code, when the job failed before its first poll } message?: string // on the load-balancer 429 only (error no_eligible_account: every account is quarantined for this model): the explanation skipReasons?: Array<{ // on the load-balancer 429 only: why each account was left out email: string // the account left out reason: string // Google reason that triggered the quarantine (a 429 reason, or the MODEL_ACCESS_DENIED or USER_MINOR 403) model: string // Quarantined model, or "*" for account-wide }> } ``` The types the tabs refer to: **`FlowVideoMedia`**: each item of `media` in the tabs above. ```typescript { name: string // Google's media id of the video projectId: string // the Google Flow project the video is in workflowId?: string // the Google Flow workflow (project item) that holds the video workflowStepId?: string // the workflow step, e.g. "CAE" (left out when Google's record has none) mediaMetadata: { // Google's record of the video createTime?: string // ISO 8601 time Google created the video mediaTitle?: string // the prompt, as Google Flow titles the video (an upscale has none) mediaBlobSize?: string // the MP4's size in bytes, as a string, once the video is done mediaStatus: { // whether the video was made mediaGenerationStatus: string // MEDIA_GENERATION_STATUS_PENDING | MEDIA_GENERATION_STATUS_ACTIVE | // MEDIA_GENERATION_STATUS_SUCCESSFUL | MEDIA_GENERATION_STATUS_FAILED | // MEDIA_GENERATION_STATUS_UNKNOWN error?: { // why the video failed code: number // Google's error code message: string // Google's reason, e.g. "PUBLIC_ERROR_IP_INPUT_IMAGE" } failureReasons?: string[] // Google's classifier labels for a failed video, e.g. "IP_PROHIBITED" } visibility?: string // "PRIVATE" (left out on a failed video) requestData: { // what the video was made from, as Google echoes it videoGenerationRequestData: { // the generation settings backend: 'flow' // the video was made on `flow.google.com` statusEnum: number | null // Google's raw status number: 6 queued, 1 and 2 running, 3 done, 4, 5 and 7 failed aspectEnum: number | null // Google's raw aspect number: 2 landscape, 1 portrait videoModelControlInput?: { // the model settings Google ran videoModelName?: string // Google's own key for the model that ran videoGenerationMode?: string // VIDEO_GENERATION_MODE_TEXT_TO_VIDEO | VIDEO_GENERATION_MODE_REFERENCE_TO_VIDEO | // VIDEO_GENERATION_MODE_VIDEO_EXTENSION (left out for the other modes) videoAspectRatio?: string // VIDEO_ASPECT_RATIO_LANDSCAPE | VIDEO_ASPECT_RATIO_PORTRAIT videoResolution?: string // VIDEO_RESOLUTION_360P | VIDEO_RESOLUTION_720P | VIDEO_RESOLUTION_1080P | // VIDEO_RESOLUTION_4K } } promptInputs?: Array<{ // the prompt as Google received it (an upscale has none) structuredPrompt: { // the prompt in parts parts: Array<{ // a run of text, or an @-mention text?: string // a run of prompt text reference?: object // an @-mention: { media: { mediaId, handle } }, { audio: { mediaId, handle } } or { entity: { entityId, handle } } }> } }> clientPlatform?: string // "CLIENT_PLATFORM_WEB" } } video: { // the video's details generatedVideo?: { // how Google made it (left out until Google reports it) seed: number // the seed Google used (0 when it reports none) prompt: string // the prompt as Google ran it (Veo rewrites it), an empty string on an upscale model: string // Google's own key for the model that ran baseImageMediaGenerationId?: string // an empty string on every video so far isLooped: false // always false aspectRatio: string // VIDEO_ASPECT_RATIO_LANDSCAPE | VIDEO_ASPECT_RATIO_PORTRAIT // (an empty string when Google reports none) upsampleMetadata?: { // on an upscaled video videoUpsampleResolution: string // VIDEO_UPSAMPLE_RESOLUTION_720P | VIDEO_UPSAMPLE_RESOLUTION_1080P // (left out for 4K) } } dimensions?: { // the clip's measurements (an upscaled clip has none) length: string // the clip's length, e.g. "8s" } operation: { // the generation operation name: string // the same as name } } mediaGenerationId?: string // the id to pass to the other endpoints (upscale, extend, GIF, concatenate, assets), on every finished answer, left out of the 201 answer videoUrl?: string // signed MP4 download URL, valid about 6 hours, once the video is done thumbnailUrl?: string // signed JPEG thumbnail URL, valid about 6 hours } ``` **`FlowCaptcha`**: the `captcha` in the tabs above. ```typescript { service?: string // the provider whose token Google accepted: `CapSolver`, `AntiCaptcha`, // `YesCaptcha`, `CapMonster`, `SolveCaptcha`, `2Captcha`, `EzCaptcha` or // `UserProvided`. Always on a success answer taskId?: string // that provider's task id (none for `UserProvided`) durationMs?: number // ms from the first solve to the token used. Always on a success answer error?: string // why no captcha token could be had, on a failed request attempts: Array<{ // every solve tried, in order, failed ones included service: string // the provider asked taskId?: string // that provider's task id durationMs: number // how long this solve took, in ms success: boolean // true when the provider returned a token (Google may still have refused it) error?: string // why the solve failed userAgent?: string // the browser user agent the provider solved with, when it reports one secChUa?: string // the Sec-CH-UA value the provider solved with, when it reports one (may be empty) cost?: string // the provider's price for this solve, as the provider reports it ip?: string // the IP address the provider reports for this solve createTime?: number // Unix time the provider started the solve, as it reports it endTime?: number // Unix time the provider finished the solve, as it reports it solveCount?: number // the provider's own solve counter for this task }> } ``` **`FlowReference`**: each image, character or video reference in `request` above. ```typescript { user: number // your useapi.net user id, read from the reference email: string // the Google account the media belongs to, read from the reference type: 'image' | 'video' | 'character' // what the reference points to id: string // Google's media id (image or video), or the character's entity id referenceId: string // the reference you sent meta?: { // characters only imgs: number // how many images the character holds (they count toward the model's image limit) voiceWorkflowId?: string // the voice attached to the character, when it has one } } ``` </details> ### Missing media URLs Media URL fields are optional and can be absent even when generation succeeded. When `videoUrl`, `thumbnailUrl`, `fifeUrl`, `servingBaseUri`, `previewUrl` or `audioUrl` is missing, the media itself is fine — only the download link could not be produced at that moment. This is rare. Across the seven days of request logs we keep, it happened on one day only — twice, for about four hours and about forty minutes — and not at all on the other six. Google issues those links from an endpoint that limits how often it will answer a given network address, so it is Google limiting our outbound calls rather than useapi.net limiting you, and nothing you do triggers it. While it lasts it affects every account generating at that moment, then clears on its own. Your generation still completed and was charged as usual. On a media item that generated successfully — `mediaStatus.mediaGenerationStatus` is `MEDIA_GENERATION_STATUS_SUCCESSFUL` — a missing URL means "not yet", not "failed", so read the field before using it and treat its absence as a retry condition. A media item that failed generation never carries a URL, and retrying will not produce one. ``` javascript const url = media.videoUrl; if (!url) { // Not an error — the link is not available yet. See the options below. } ``` #### How to get the link Which route to use depends on whether you can wait. If you are already polling the job, do nothing special. Completed video jobs re-resolve missing URLs automatically on [GET /jobs/`jobId`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid), and the recovered link is saved, so a later poll returns it with no extra work on your side. This applies to video jobs created within the last 24 hours. Once the job is completed and a URL is still missing, leave at least a minute between polls — a job re-resolves at most once a minute, and the block clears only once traffic stops, so a tight retry loop lengthens the wait rather than shortening it. If you hold a `mediaGenerationId` but no longer have the job, ask for that one media again with [GET /assets/`mediaGenerationId`](/docs/api-google-flow-v1/get-google-flow-assets-mediagenerationid). That endpoint says which case you are in rather than leaving you to guess. A `503` with a `Retry-After` header means the link is coming and tells you how long to wait, so wait that long and ask again. A `404` means Google has no such media, and no amount of retrying will change it. If you cannot wait, download the video through us with [GET /assets/`mediaGenerationId``?raw=true`](/docs/api-google-flow-v1/get-google-flow-assets-mediagenerationid). It reads the media over a different Google route that the block does not touch, so it works immediately and keeps working while the other two return nothing. It is **video only**. Prefer the two link-based routes when you can. They hand you a link and you download straight from Google. The raw form moves the whole file through useapi.net on every call, which makes it a way out of a stuck download rather than your normal download path. Characters and voices resolve their URLs as they are read, so simply requesting [GET /characters/`ref`](/docs/api-google-flow-v1/get-google-flow-characters-ref) or [GET /voices/`ref`](/docs/api-google-flow-v1/get-google-flow-voices-ref) again is enough. Wait a minute before retrying — a response that came back without its URL is held briefly, so an immediate repeat returns the same one. None of this applies to images. Whenever an image URL is missing, [POST /images](/docs/api-google-flow-v1/post-google-flow-images) puts the image itself in the response instead, base64-encoded in `encodedImage` — so you already have the picture and there is nothing to retry. ### Examples **Curl** ``` bash curl -X POST \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A serene mountain landscape at sunset with camera slowly panning right", "model": "veo-3.1-fast", "aspectRatio": "landscape", "duration": 8, "count": 2 }' \ "https://api.useapi.net/v1/google-flow/videos" > response.json # Extract video URLs using jq cat response.json | jq -r '.media[0].videoUrl' cat response.json | jq -r '.media[1].videoUrl' # Download videos using curl curl "$(cat response.json | jq -r '.media[0].videoUrl')" --output video_1.mp4 curl "$(cat response.json | jq -r '.media[1].videoUrl')" --output video_2.mp4 ``` **JavaScript** ``` javascript const token = 'YOUR_API_TOKEN'; const apiUrl = 'https://api.useapi.net/v1/google-flow/videos'; const response = await fetch(apiUrl, { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ prompt: 'A serene mountain landscape at sunset with camera slowly panning right', model: 'veo-3.1-fast', aspectRatio: 'landscape', duration: 8, count: 2 }) }); const result = await response.json(); console.log('Generated videos:', result.media.length); // Download videos for (const [index, item] of result.media.entries()) { console.log(`Video ${index + 1} seed:`, item.video?.generatedVideo?.seed); console.log(`mediaGenerationId:`, item.mediaGenerationId); console.log(`Video URL:`, item.videoUrl); // Download video (Node.js) const videoResponse = await fetch(item.videoUrl); const videoBuffer = await videoResponse.arrayBuffer(); const fs = require('fs'); fs.writeFileSync(`generated_video_${index + 1}.mp4`, Buffer.from(videoBuffer)); } ``` **Python** ``` python import requests token = 'YOUR_API_TOKEN' api_url = 'https://api.useapi.net/v1/google-flow/videos' headers = { 'Authorization': f'Bearer {token}', 'Content-Type': 'application/json' } data = { 'prompt': 'A serene mountain landscape at sunset with camera slowly panning right', 'model': 'veo-3.1-fast', 'aspectRatio': 'landscape', 'duration': 8, 'count': 2 } response = requests.post(api_url, headers=headers, json=data) result = response.json() print(f"Generated {len(result['media'])} videos") # Download videos for index, item in enumerate(result['media']): video = item.get('video', {}).get('generatedVideo', {}) print(f"Video {index + 1} seed:", video.get('seed')) print(f"mediaGenerationId:", item.get('mediaGenerationId')) # Download video video_response = requests.get(item['videoUrl']) with open(f'generated_video_{index + 1}.mp4', 'wb') as f: f.write(video_response.content) ``` ### Try It <script src="/assets/js/google-flow-voices.js"></script> <script> document.addEventListener('DOMContentLoaded', function () { gfPopulateVoiceSelect('input-referenceAudio_1'); }); function displayGoogleFlowVideos(response, elementId) { const mediaContainer = document.getElementById(`${elementId}-media-links`); if (!mediaContainer) return; mediaContainer.innerHTML = ''; const mediaItems = response.media || []; if (mediaItems.length === 0) { mediaContainer.style.display = 'none'; return; } const videos = []; mediaItems.forEach((item, index) => { if (!item.videoUrl) return; const seed = item.video?.generatedVideo?.seed; videos.push({ videoUrl: item.videoUrl, seed: seed, label: `Video ${videos.length + 1}${seed ? ` (seed: ${seed})` : ''}` }); }); if (videos.length > 0) { const linksHTML = videos.map(vid => `<a href="${vid.videoUrl}" target="_blank" rel="noopener noreferrer" class="media-link video">${vid.label}</a>` ).join(' '); mediaContainer.innerHTML = `<div class="media-links-container"><strong>Generated Videos:</strong> ${linksHTML}</div>`; mediaContainer.style.display = 'block'; } else { mediaContainer.style.display = 'none'; } } async function apiExecutePostGoogleFlowVideos() { const tokenElement = document.getElementById('input-token'); const elementId = 'input'; const payload = {}; const inputs = document.querySelectorAll('.input-query-param'); inputs.forEach(input => { const id = input.id; const value = input.value?.trim(); if (id.startsWith('input-') && value !== '' && value !== undefined) { const key = id.replace('input-', ''); if (key === 'count' || key === 'captchaRetry' || key === 'startFrameIndex_1' || key === 'endFrameIndex_1') { payload[key] = parseInt(value); } else if (key === 'async' || key === 'returnSilentVideos') { payload[key] = value === 'true'; } else { payload[key] = value; } } }); const data = { method: 'POST', headers: { 'Authorization': `Bearer ${tokenElement.value}`, 'Content-Type': 'application/json' }, body: JSON.stringify(payload) }; const mediaLinks = document.getElementById(`${elementId}-media-links`); if (mediaLinks) mediaLinks.style.display = 'none'; const status = await apiExecute('https://api.useapi.net/v1/google-flow/videos', elementId, data, { includeTimer: true }); if (status === 200) { try { const content = document.getElementById(`${elementId}-response-json`); const response = JSON.parse(content.innerText); displayGoogleFlowVideos(response, elementId); } catch (e) { console.error('Failed to parse response for video display:', e); } } } </script> <form id="input" class="input-form" onsubmit="return false;"> <div class="input-field"> <div class="input-field-row"> <label for="input-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="input-token" type="text" class="input-element" required aria-required="true"> </label> <label for="input-email"><span>email (optional)</span> <input id="input-email" type="text" class="input-element input-query-param" placeholder="john@gmail.com"> </label> <label for="input-prompt"><span>prompt (required)</span> <input id="input-prompt" type="text" class="input-element input-query-param" required aria-required="true" placeholder="A serene mountain landscape"> </label> <label for="input-model"><span>model</span> <select id="input-model" class="input-element input-query-param"> <option value="veo-3.1-fast">veo-3.1-fast (default)</option> <option value="veo-3.1-quality">veo-3.1-quality</option> <option value="veo-3.1-lite">veo-3.1-lite (faster, lower cost)</option> <option value="veo-3.1-lite-low-priority">veo-3.1-lite-low-priority (Ultra $199 only, no credits, lower priority)</option> <option value="omni-flash-1.2">omni-flash-1.2 (Omni 1.2 Flash, 3-15 s, every plan, free up to 10 s)</option> <option value="omni-flash">omni-flash (Omni 1.1 Flash, Plus/Pro/Ultra, 4/6/8/10 s)</option> </select> </label> <label for="input-aspectRatio"><span>aspectRatio</span> <select id="input-aspectRatio" class="input-element input-query-param"> <option value="landscape" selected>landscape (default)</option> <option value="portrait">portrait</option> </select> </label> <label for="input-duration"><span>duration (sec — omni-flash-1.2: 3-15 · omni-flash: 4/6/8/10 · Veo: 4/6 Ultra-only, 8 default)</span> <select id="input-duration" class="input-element input-query-param"> <option value="3">3 (omni-flash-1.2)</option> <option value="4">4</option> <option value="5">5 (omni-flash-1.2)</option> <option value="6">6</option> <option value="7">7 (omni-flash-1.2)</option> <option value="8" selected>8 (default)</option> <option value="9">9 (omni-flash-1.2)</option> <option value="10">10 (omni models)</option> <option value="11">11 (omni-flash-1.2, paid plans)</option> <option value="12">12 (omni-flash-1.2, paid plans)</option> <option value="13">13 (omni-flash-1.2, paid plans)</option> <option value="14">14 (omni-flash-1.2, paid plans)</option> <option value="15">15 (omni-flash-1.2, paid plans)</option> </select> </label> <label for="input-resolution"><span>resolution (omni models only — 360p costs a third on omni-flash-1.2, about half on omni-flash)</span> <select id="input-resolution" class="input-element input-query-param"> <option value="">720p (default)</option> <option value="360p">360p (omni models only)</option> <option value="720p">720p</option> </select> </label> <label for="input-count"><span>count</span> <input id="input-count" type="number" class="input-element input-query-param" min="1" max="4" placeholder="1"> </label> <label for="input-startImage"><span>startImage (optional, from <a href="/docs/api-google-flow-v1/post-google-flow-assets-email">POST /assets/email</a>)</span> <input id="input-startImage" type="text" class="input-element input-query-param" placeholder="user:123-email:..."> </label> <label for="input-endImage"><span>endImage (optional, requires startImage)</span> <input id="input-endImage" type="text" class="input-element input-query-param" placeholder="user:123-email:..."> </label> <label for="input-referenceImage_1"><span>referenceImage_1 (optional, R2V mode)</span> <input id="input-referenceImage_1" type="text" class="input-element input-query-param" placeholder="user:123-email:..."> </label> <label for="input-referenceImage_2"><span>referenceImage_2</span> <input id="input-referenceImage_2" type="text" class="input-element input-query-param" placeholder="user:123-email:..."> </label> <label for="input-referenceImage_3"><span>referenceImage_3</span> <input id="input-referenceImage_3" type="text" class="input-element input-query-param" placeholder="user:123-email:..."> </label> <label for="input-referenceImage_4"><span>referenceImage_4 (omni models only)</span> <input id="input-referenceImage_4" type="text" class="input-element input-query-param" placeholder="user:123-email:..."> </label> <label for="input-referenceImage_5"><span>referenceImage_5 (omni models only)</span> <input id="input-referenceImage_5" type="text" class="input-element input-query-param" placeholder="user:123-email:..."> </label> <label for="input-referenceImage_6"><span>referenceImage_6 (omni models only)</span> <input id="input-referenceImage_6" type="text" class="input-element input-query-param" placeholder="user:123-email:..."> </label> <label for="input-referenceImage_7"><span>referenceImage_7 (omni models only)</span> <input id="input-referenceImage_7" type="text" class="input-element input-query-param" placeholder="user:123-email:..."> </label> <label for="input-referenceImage_8"><span>referenceImage_8 (omni-flash-1.2 only)</span> <input id="input-referenceImage_8" type="text" class="input-element input-query-param" placeholder="user:123-email:..."> </label> <label for="input-referenceImage_9"><span>referenceImage_9 (omni-flash-1.2 only)</span> <input id="input-referenceImage_9" type="text" class="input-element input-query-param" placeholder="user:123-email:..."> </label> <label for="input-referenceImage_10"><span>referenceImage_10 (omni-flash-1.2 only)</span> <input id="input-referenceImage_10" type="text" class="input-element input-query-param" placeholder="user:123-email:..."> </label> <label for="input-character_1"><span>character_1 (optional, ref from <a href="/docs/api-google-flow-v1/post-google-flow-characters">POST /characters</a>)</span> <input id="input-character_1" type="text" class="input-element input-query-param" placeholder="user:123-email:...-character:...-imgs:N"> </label> <label for="input-character_2"><span>character_2</span> <input id="input-character_2" type="text" class="input-element input-query-param" placeholder="user:123-email:...-character:...-imgs:N"> </label> <label for="input-character_3"><span>character_3</span> <input id="input-character_3" type="text" class="input-element input-query-param" placeholder="user:123-email:...-character:...-imgs:N"> </label> <label for="input-character_4"><span>character_4 (omni models only)</span> <input id="input-character_4" type="text" class="input-element input-query-param" placeholder="user:123-email:...-character:...-imgs:N"> </label> <label for="input-character_5"><span>character_5 (omni models only)</span> <input id="input-character_5" type="text" class="input-element input-query-param" placeholder="user:123-email:...-character:...-imgs:N"> </label> <label for="input-character_6"><span>character_6 (omni models only)</span> <input id="input-character_6" type="text" class="input-element input-query-param" placeholder="user:123-email:...-character:...-imgs:N"> </label> <label for="input-character_7"><span>character_7 (omni models only)</span> <input id="input-character_7" type="text" class="input-element input-query-param" placeholder="user:123-email:...-character:...-imgs:N"> </label> <label for="input-character_8"><span>character_8 (omni-flash-1.2 only)</span> <input id="input-character_8" type="text" class="input-element input-query-param" placeholder="user:123-email:...-character:...-imgs:N"> </label> <label for="input-character_9"><span>character_9 (omni-flash-1.2 only)</span> <input id="input-character_9" type="text" class="input-element input-query-param" placeholder="user:123-email:...-character:...-imgs:N"> </label> <label for="input-character_10"><span>character_10 (omni-flash-1.2 only)</span> <input id="input-character_10" type="text" class="input-element input-query-param" placeholder="user:123-email:...-character:...-imgs:N"> </label> <label for="input-referenceVideo_1"><span>referenceVideo_1 (omni V2V edit, MP4 mediaGenerationId from <a href="/docs/api-google-flow-v1/post-google-flow-assets-email">POST /assets/email</a>)</span> <input id="input-referenceVideo_1" type="text" class="input-element input-query-param" placeholder="user:123-email:...-video:..."> </label> <label for="input-startFrameIndex_1"><span>startFrameIndex_1 (omni V2V only, 24 fps timeline: 0-359 on omni-flash-1.2, 0-239 on omni-flash)</span> <input id="input-startFrameIndex_1" type="number" class="input-element input-query-param" min="0" max="359" placeholder="0"> </label> <label for="input-endFrameIndex_1"><span>endFrameIndex_1 (omni V2V only: 1-360 on omni-flash-1.2 = 15 s, 1-240 on omni-flash = 10 s)</span> <input id="input-endFrameIndex_1" type="number" class="input-element input-query-param" min="1" max="360" placeholder="(auto from clip duration)"> </label> <label for="input-referenceAudio_1"><span>referenceAudio_1 (optional — system voice OR user voice; select to preview)</span> <div> <select id="input-referenceAudio_1" class="input-element input-query-param" onchange="gfOnVoicePicked('input-referenceAudio_1','input-referenceAudio_1-audio','input-referenceAudio_1-meta','input-token')"></select> <button type="button" class="btn btn-secondary" style="margin-left:6px" onclick="gfRefreshUserVoices('input-referenceAudio_1','input-token','input-email')">Refresh user voices</button> <audio id="input-referenceAudio_1-audio" class="audio-player" style="display:none;margin-top:4px" controls></audio> <div id="input-referenceAudio_1-meta" style="display:none;font-size:0.9em;color:#666;margin-top:2px"></div> </div> </label> <label for="input-referenceAudio_2"><span>referenceAudio_2 (omni models only)</span> <input id="input-referenceAudio_2" type="text" class="input-element input-query-param" placeholder="e.g. Aoede"> </label> <label for="input-referenceAudio_3"><span>referenceAudio_3 (omni models only)</span> <input id="input-referenceAudio_3" type="text" class="input-element input-query-param" placeholder="e.g. Kore"> </label> <label for="input-referenceAudio_4"><span>referenceAudio_4 (omni models only)</span> <input id="input-referenceAudio_4" type="text" class="input-element input-query-param" placeholder="e.g. Puck"> </label> <label for="input-referenceAudio_5"><span>referenceAudio_5 (omni models only)</span> <input id="input-referenceAudio_5" type="text" class="input-element input-query-param" placeholder="e.g. Zephyr"> </label> <label for="input-returnSilentVideos"><span>returnSilentVideos (true: a video whose sound Google's audio filter rejects comes back silent, charged, instead of failing)</span> <select id="input-returnSilentVideos" class="input-element input-query-param"> <option value="">false (default)</option> <option value="true">true</option> </select> </label> <label for="input-captchaToken"><span>captchaToken (optional, your own reCAPTCHA token)</span> <input id="input-captchaToken" type="text" class="input-element input-query-param" placeholder="reCAPTCHA v3 Enterprise token"> </label> <label for="input-captchaRetry"><span>captchaRetry (1-10, optional)</span> <input id="input-captchaRetry" type="number" class="input-element input-query-param" min="1" max="10" placeholder="5"> </label> <label for="input-captchaOrder"><span>captchaOrder (optional)</span> <input id="input-captchaOrder" type="text" class="input-element input-query-param" placeholder="CapSolver,AntiCaptcha"> </label> <label for="input-async"><span>async (fire-and-forget mode, see <a href="/docs/api-google-flow-v1/get-google-flow-jobs-jobid">GET /jobs/jobId</a>)</span> <select id="input-async" class="input-element input-query-param"> <option value="false">false (default)</option> <option value="true">true</option> </select> </label> <label for="input-replyUrl"><span>replyUrl (webhook URL)</span> <input id="input-replyUrl" type="text" class="input-element input-query-param" placeholder="https://your-domain.com/webhook"> </label> <label for="input-replyRef"><span>replyRef (custom reference)</span> <input id="input-replyRef" type="text" class="input-element input-query-param" placeholder="my-custom-id-123"> </label> </div> <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecutePostGoogleFlowVideos()">Go</button> </div> </form> <div id="input-media-links" style="display:none;"></div> <div id="input-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-voices === Document URL: https://useapi.net/docs/api-google-flow-v1/post-google-flow-voices --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> voices description: "Create a custom voice built on a system TTS preset via POST voices in the useapi.net Google Flow API v1 — reuse it in video narration or attach it to a character." parent: Google Flow API nav_order: 1100 --- ## Create Custom Voice June 5, 2026 (November 16, 2026) --- Create a **custom voice** (also called a *user voice*) on a Google Flow account. A custom voice is a saved Text-to-Speech (TTS) clip built on top of one of the **30 system voice presets** (`Achernar`, `Achird`, `Algenib`, …) with your own `dialog` text and `voicePerformance` description. Once created, the voice can be: - Used in [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) via `referenceAudio_1..5` - Attached to a [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters) at create time (`voice` body param) - Played back via [GET /voices/`ref`](/docs/api-google-flow-v1/get-google-flow-voices-ref) (returns a fresh signed `audioUrl`) **Captcha:** required. See [Captcha Parameters](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers#captcha-parameters). > **https://api.useapi.net/v1/google-flow/voices** ### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` ### Request Body ```json { "email": "john@gmail.com", "voice": "Achernar", "dialog": "Hello, this is a test voice.", "voicePerformance": "Cheerful, energetic delivery", "displayName": "Cheerful Narrator" } ``` - `email` is **required**, the Google Flow account to create the voice on. - `voice` is **required**, one of the 30 system voice presets. The custom voice inherits the timbre of this base voice. Case-sensitive. Valid 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 ``` - `displayName` is **required**, user-facing label for the voice. Range: 1-200 chars. Shown in [GET /voices](/docs/api-google-flow-v1/get-google-flow-voices) and used to distinguish multiple voices in your list. - `dialog` is **required**, the text the voice will say. Range: 1-120 chars. Used as the audio preview sample. - `voicePerformance` is **required**, short description of delivery style (e.g. "Cheerful, energetic delivery", "Deep, brooding villain tone"). Range: 1-120 chars. - `captchaToken`, `captchaRetry`, `captchaOrder` are optional, mutually exclusive captcha parameters. See [Captcha Parameters](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers#captcha-parameters) for details. ### Responses **200** **200 OK** Voice created. ```json { "voice": "user:12345-email:6a6f...-voice:d990a2f9-...-mid:d55b6d59-...", "source": "user", "workflowId": "d990a2f9-...", "mediaId": "d55b6d59-...", "displayName": "Cheerful Narrator", "baseVoice": "Achernar", "dialog": "Hello, this is a test voice.", "voicePerformance": "Cheerful, energetic delivery", "audioUrl": "https://flow-content.google/audio/d55b6d59-...?Expires=...&KeyName=labs-flow-prod-cdn-key&Signature=..." } ``` Use the `voice` field as the value for `referenceAudio_1`..`referenceAudio_5` on [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos), or as the `voice` body param when creating a character via [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters). It's also the path segment for [GET /voices/`ref`](/docs/api-google-flow-v1/get-google-flow-voices-ref) and [DELETE /voices/`ref`](/docs/api-google-flow-v1/delete-google-flow-voices-ref). **400** **400 Bad Request** Validation error (missing required field, invalid voice name, dialog/voicePerformance > 120 chars, etc). ```json { "error": "Parameter voice is required (must be one of Achernar,Achird,Algenib,…)", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** Google rejected the captcha on every try. We retry with a fresh captcha as many times as you allow (`captchaRetry`, default 5, or the providers in `captchaOrder`) and return this `403` only when all of them were rejected. The top-level `error` starts with `captcha_quality:`, for example `"captcha_quality: PUBLIC_ERROR_UNUSUAL_ACTIVITY after 5 attempts. Google refused all 5 captcha tokens for user@example.com, so nothing was generated and no Google Flow credits were used (5 captcha solves were spent). Google is flagging this account's requests as unusual activity. If it keeps happening, use another account, or leave out email so the API picks one. See GET /accounts/captcha-stats summary.by_account"`. A `429` with `PUBLIC_ERROR_UNUSUAL_ACTIVITY_TOO_MUCH_TRAFFIC` reads the same way. Two `403`s are not a captcha problem, and we answer them after one try instead of retrying. `PUBLIC_ERROR_MODEL_ACCESS_DENIED` in the response means Google refused the model on that account, so raising `captchaRetry` or adding providers will not help. Check that the account's plan includes the model. Since 2026-09-23 Google no longer offers `veo-3.1-lite-low-priority` to invited members of an Ultra $199 family plan — only the family manager's account keeps it. `PUBLIC_ERROR_USER_MINOR` means Google treats the Google account as belonging to someone under 18, and Google Flow is not available to such accounts. The `error` says so in plain words. No captcha or retry changes it: use another Google account, or have this one's age verified with Google first. With `email` omitted, the load balancer sets such an account aside for 1 hour, then tries it again. Nothing was created when this happens. Google checks the captcha before it starts generating, so no Google credits were used and you can resubmit straight away. Your captcha provider still bills each solve. The usual cause is the Google account, not the captcha provider. Google gives each account its own trust level. On a trusted account it accepts about 9 in 10 captchas, on a distrusted one about 3 in 10, whichever provider solved them. Most customers have a few distrusted accounts among many good ones. To see which accounts are affected, use [GET /accounts/captcha-stats](/docs/api-google-flow-v1/get-google-flow-accounts-captcha-stats). Its `summary.by_account` shows, for each of your Google accounts, how many captchas were tried and what share Google accepted. [GET account/stats](/docs/account-management/get-account-stats) with `bot=google-flow` also shows how many requests each account finished with each response code. - If one or a few accounts are far below the others, the API already sends them less work: when you leave out `email`, each captcha Google rejected on an account in the last 15 minutes lowers its chance of being picked, for generations and for image uploads. They still get some work, so an account that recovers gets its full share back. If you pin requests with `email`, move them to your other accounts yourself. Replace an account that stays low for more than a day or two. - If all your accounts drop at the same time, it's the captcha provider. Configure at least two providers with [POST /accounts/captcha-providers](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers), and the API will start with whichever one Google accepts best. A higher `captchaRetry` gets more requests through on a distrusted account, but every extra try is another paid solve. **404** **404 Not Found** Account not configured. ```json { "error": "Google Flow account john@gmail.com not found", "code": 404 } ``` **429** **429 Too Many Requests** Google returns several `RESOURCE_EXHAUSTED` 429 variants. Check the `reason` field and respond accordingly: | Reason | Meaning | Scope | What to do | Cooldown | |--------|---------|-------|------------|----------| | `PUBLIC_ERROR_`<br>`USER_REQUESTS_THROTTLED` | Google is throttling the account (the token was fine). Uploads and generation are metered separately | All models on the account — or uploads only, when POST /assets triggered it | Run fewer parallel requests, or switch accounts. From POST /assets, retrying the same one rarely clears it | ~30 min. From POST /assets, treat it as a minimum — it can persist | | `PUBLIC_ERROR_`<br>`USER_QUOTA_REACHED` | Account's overall Flow quota cap | All models on the account | Add accounts, or omit `email` to load-balance | ~30 min | | `PUBLIC_ERROR_`<br>`PER_MODEL_DAILY_QUOTA_REACHED` | Per-model daily quota | Only that model, on that account | Switch model, or wait | Next UTC midnight | | `PUBLIC_ERROR_`<br>`UNUSUAL_ACTIVITY_TOO_MUCH_TRAFFIC` | Google rejected the captcha on every try (we already retried). Usually a distrusted Google account, sometimes the provider | Per request | Check which accounts are affected in [captcha-stats](/docs/api-google-flow-v1/get-google-flow-accounts-captcha-stats#when-google-rejects-captchas). Rest or replace those accounts. Add a second provider if all accounts drop together | 60s | Every `429` returns the cooldown two ways — an HTTP `Retry-After: <seconds>` header and a body `retryAfter: <ISO timestamp>` field. Honor it before retrying. When `email` is omitted, the first three reasons quarantine the account and the load balancer routes around it. If every account is quarantined for the model you get `429` with `error: "no_eligible_account"`. Routing details: [GET /jobs › Load Balancing Algorithm](/docs/api-google-flow-v1/get-google-flow-jobs#load-balancing-algorithm). Captcha-quality failures prefix the top-level `error` with `captcha_quality:` (e.g. `"captcha_quality: PUBLIC_ERROR_UNUSUAL_ACTIVITY_TOO_MUCH_TRAFFIC after 3 attempts"`) so you can detect them without parsing the nested body. **503** **503 Service Unavailable** `503` has two distinct causes — check the response body to tell them apart. A transient Google-side outage. Wait 5-10 seconds and retry. ```json { "error": { "code": 503, "message": "Service temporarily unavailable.", "status": "UNAVAILABLE" } } ``` A captcha-provider failure — the top-level `error` is prefixed `Captcha service failed:`. The problem is your captcha provider (check its API key and balance), not Google. Don't retry until the provider is back. ```json { "error": "Captcha service failed: ERROR_ZERO_BALANCE", "code": 503 } ``` ### Model The new custom voice with its reference-id, its base voice, the text spoken in its sample and its audio link. <details markdown="block" class="model-details"> <summary>The new voice, field by field</summary> ```typescript { voice: string // reference-id used in subsequent calls source: 'user' // always 'user' (a custom voice) workflowId: string // Google Flow workflow of the voice mediaId: string // media id of the voice's audio displayName: string // the name you sent baseVoice: string // one of the 30 system voice presets dialog: string // the text you sent, spoken in the sample voicePerformance: string // the delivery style you sent audioUrl?: string // signed playback URL (~6h TTL); occasionally absent on transient resolution failure } ``` </details> ### Examples **Curl** ``` bash curl -X POST \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "john@gmail.com", "voice": "Achernar", "dialog": "Welcome to the demo.", "voicePerformance": "Cheerful, energetic delivery", "displayName": "Cheerful Narrator" }' \ "https://api.useapi.net/v1/google-flow/voices" ``` **JavaScript** ``` javascript const response = await fetch('https://api.useapi.net/v1/google-flow/voices', { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ email: 'john@gmail.com', voice: 'Achernar', dialog: 'Welcome to the demo.', voicePerformance: 'Cheerful, energetic delivery', displayName: 'Cheerful Narrator' }) }) const result = await response.json() console.log('voice ref:', result.voice) ``` **Python** ``` python import requests r = requests.post( 'https://api.useapi.net/v1/google-flow/voices', headers={'Authorization': f'Bearer {token}'}, json={ 'email': 'john@gmail.com', 'voice': 'Achernar', 'dialog': 'Welcome to the demo.', 'voicePerformance': 'Cheerful, energetic delivery', 'displayName': 'Cheerful Narrator', }, ) print('voice ref:', r.json()['voice']) ``` ### Try It <form id="input" class="input-form" onsubmit="return false;"> <div class="input-field"> <div class="input-field-row"> <label for="input-token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="input-token" type="text" class="input-element" required aria-required="true"> </label> <label for="input-email"><span>email (required)</span> <input id="input-email" type="text" class="input-element input-query-param" required aria-required="true" placeholder="john@gmail.com"> </label> <label for="input-voice"><span>voice (required — base voice preset; select to preview)</span> <div> <select id="input-voice" class="input-element input-query-param" required aria-required="true" onchange="gfPreviewSystemVoice(this.value)"> <option value="">(select)</option> <option value="Achernar">Achernar</option><option value="Achird">Achird</option> <option value="Algenib">Algenib</option><option value="Algieba">Algieba</option> <option value="Alnilam">Alnilam</option><option value="Aoede">Aoede</option> <option value="Autonoe">Autonoe</option><option value="Callirrhoe">Callirrhoe</option> <option value="Charon">Charon</option><option value="Despina">Despina</option> <option value="Enceladus">Enceladus</option><option value="Erinome">Erinome</option> <option value="Fenrir">Fenrir</option><option value="Gacrux">Gacrux</option> <option value="Iapetus">Iapetus</option><option value="Kore">Kore</option> <option value="Laomedeia">Laomedeia</option><option value="Leda">Leda</option> <option value="Orus">Orus</option><option value="Puck">Puck</option> <option value="Pulcherrima">Pulcherrima</option><option value="Rasalgethi">Rasalgethi</option> <option value="Sadachbia">Sadachbia</option><option value="Sadaltager">Sadaltager</option> <option value="Schedar">Schedar</option><option value="Sulafat">Sulafat</option> <option value="Umbriel">Umbriel</option><option value="Vindemiatrix">Vindemiatrix</option> <option value="Zephyr">Zephyr</option><option value="Zubenelgenubi">Zubenelgenubi</option> </select> <audio id="input-voice-audio" class="audio-player" style="display:none;margin-top:4px" controls></audio> </div> </label> <label for="input-displayName"><span>displayName (required, 1–200 chars)</span> <input id="input-displayName" type="text" class="input-element input-query-param" required aria-required="true" maxlength="200" placeholder="Cheerful Narrator"> </label> <label for="input-dialog"><span>dialog (required, 1–120 chars)</span> <input id="input-dialog" type="text" class="input-element input-query-param" required aria-required="true" maxlength="120" placeholder="Welcome to the demo."> </label> <label for="input-voicePerformance"><span>voicePerformance (required, 1–120 chars)</span> <input id="input-voicePerformance" type="text" class="input-element input-query-param" required aria-required="true" maxlength="120" placeholder="Cheerful, energetic delivery"> </label> <label for="input-captchaToken"><span>captchaToken (optional)</span> <input id="input-captchaToken" type="text" class="input-element input-query-param" placeholder="reCAPTCHA v3 Enterprise token"> </label> <label for="input-captchaRetry"><span>captchaRetry (1-10, optional)</span> <input id="input-captchaRetry" type="number" class="input-element input-query-param" min="1" max="10" placeholder="5"> </label> <label for="input-captchaOrder"><span>captchaOrder (optional)</span> <input id="input-captchaOrder" type="text" class="input-element input-query-param" placeholder="CapSolver,AntiCaptcha"> </label> </div> <button id="input-button" class="btn btn-primary fs-3" type="submit" onclick="apiExecutePostGoogleFlowVoices()">Go</button> </div> </form> <div id="input-generated-preview" style="display:none;margin-top:8px"><strong>Generated voice:</strong><br><audio id="input-generated-audio" class="audio-player" controls></audio></div> <div id="input-response" class="response-placeholder visible-false"></div> <script src="/assets/js/google-flow-voices.js"></script> <script> async function apiExecutePostGoogleFlowVoices() { const tokenElement = document.getElementById('input-token'); const elementId = 'input'; const payload = {}; document.querySelectorAll('.input-query-param').forEach(input => { const id = input.id; const value = input.value?.trim(); if (id.startsWith('input-') && value !== '' && value !== undefined) { const key = id.replace('input-', ''); if (key === 'captchaRetry') payload[key] = parseInt(value); else payload[key] = value; } }); const data = { method: 'POST', headers: { 'Authorization': `Bearer ${tokenElement.value}`, 'Content-Type': 'application/json' }, body: JSON.stringify(payload), }; const previewBox = document.getElementById('input-generated-preview'); previewBox.style.display = 'none'; const status = await apiExecute('https://api.useapi.net/v1/google-flow/voices', elementId, data, { includeTimer: true }); if (status === 200) { try { const content = document.getElementById(`${elementId}-response-json`); const v = JSON.parse(content.innerText); if (v && v.audioUrl) { const audio = document.getElementById('input-generated-audio'); audio.src = v.audioUrl; previewBox.style.display = 'block'; audio.play().catch(() => {}); } } catch (e) {} } } </script> === URL: https://useapi.net/docs/api-google-flow-v1/put-google-flow-agent-settings === Document URL: https://useapi.net/docs/api-google-flow-v1/put-google-flow-agent-settings --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-put">PUT</code> agent/settings description: "Change a Flow project's agent settings via PUT agent/settings in the useapi.net Google Flow API: ask or auto approval, up to 3 instructions, default models from the account's plan." parent: Google Flow API nav_order: 1495 --- ## Change agent settings October 16, 2026 (November 16, 2026) --- Change the agent settings of a Flow project. They apply to every chat in the project, including chats in the Flow web app. Send only what you want to change: the fields you leave out keep their values. The response is the project's settings after the change, the same as [GET /agent/settings](/docs/api-google-flow-v1/get-google-flow-agent-settings). Without `projectId`, this changes the account's own agent project, the one [POST /agent/chats](/docs/api-google-flow-v1/post-google-flow-agent-chats) uses by default. It is created if the account has none yet. > **https://api.useapi.net/v1/google-flow/agent/settings** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "email": "john@gmail.com", "approval": "ask", "instructions": [ { "text": "Keep every answer short. Prefer free image models." }, { "title": "Brand look", "text": "Use the colors of the attached logo.", "references": ["user:12345-email:6a6f...-image:6bb4a078-..."] } ], "imageDefaults": { "model": "nano-banana-2", "aspectRatio": "16:9", "count": 1 }, "videoDefaults": { "model": "veo-3.1-fast", "aspectRatio": "16:9", "count": 1 } } ``` - `email` is **required**, the Google Flow account, see [GET /accounts](/docs/api-google-flow-v1/get-google-flow-accounts). - `projectId` is optional, a Flow project of the account, from [GET /assets/projects/`email`](/docs/api-google-flow-v1/get-google-flow-assets-projects-email). Default: the account's agent project. - `approval` is optional, whether the agent asks before it spends credits. Supported values: `ask` (the agent stops and shows the cost, see [POST /agent/chats/`chatId`/approval](/docs/api-google-flow-v1/post-google-flow-agent-chats-chatId-approval)), `auto` (the agent spends without asking). - `instructions` is optional, the project's standing instructions, which the agent follows in every chat of the project. The array replaces all of the project's instructions, so send the full list each time. An empty array removes them all. Up to 3 instructions, each an object with: - `text`, **required**, 1 to 5000 characters. - `title`, optional, up to 200 characters. - `enabled`, optional, `false` keeps the instruction without the agent following it. Default: `true`. - `references`, optional, an array of images of the same account for the agent to use with this instruction: ids from [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email), images made by [POST /images](/docs/api-google-flow-v1/post-google-flow-images), or the `referenceId` of an image the agent made. - `id`, optional, the `id` of an existing instruction from [GET /agent/settings](/docs/api-google-flow-v1/get-google-flow-agent-settings), to keep it. A new id is given otherwise. - `imageDefaults` is optional, what the agent uses for images when a message does not say otherwise, an object with: - `model`, **required**, a model the account's Google plan has, as `models.image` in [GET /agent/settings](/docs/api-google-flow-v1/get-google-flow-agent-settings) lists it with its credits. Supported values: `nano-banana-pro`, `nano-banana-2` (Nano Banana 2.1), `nano-banana-2-lite`, and any other model `models.image` lists for the account. - `aspectRatio`, **required**. Supported values: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`. - `count`, optional, images per request. Range: `1` to `4`. Default: `1`. - `videoDefaults` is optional, what the agent uses for videos when a message does not say otherwise, an object with: - `model`, **required**, a model the account's Google plan has, as `models.video` in [GET /agent/settings](/docs/api-google-flow-v1/get-google-flow-agent-settings) lists it with its credits. Supported values: `omni-flash-1.2` (accounts Google has given Omni 1.2 Flash), `omni-flash`, `veo-3.1-lite`, `veo-3.1-fast`, `veo-3.1-quality`, `veo-3.1-lite-low-priority` (Ultra plans only), and any other model `models.video` lists for the account. - `aspectRatio`, **required**. Supported values: `16:9`, `9:16`. - `count`, optional, videos per request. Range: `1` to `4`. Default: `1`. Send at least one of `approval`, `instructions`, `imageDefaults` or `videoDefaults`. A model that Google adds to Flow before this API names it shows in `models` under Google's own name, and that name works as `model` too. A model the account's plan does not have answers `400` with the models it does have. ##### Responses **200** **200 OK** The project's settings after the change, with the account's `models` as in [GET /agent/settings](/docs/api-google-flow-v1/get-google-flow-agent-settings). ```json { "projectId": "f166200a-ea22-461a-bc68-47ff6d3ee500", "approval": "ask", "instructions": [ { "id": "2157F442-D2DB-4C22-BC53-E4B14FA4D667", "text": "Keep every answer short. Prefer free image models.", "enabled": true, "references": [] }, { "id": "C4B70536-E836-431B-B86B-0E3816CCE6B9", "text": "A switched-off instruction.", "enabled": false, "references": [] } ], "imageDefaults": { "model": "nano-banana-2", "aspectRatio": "16:9", "count": 1 }, "videoDefaults": { "model": "veo-3.1-fast", "aspectRatio": "16:9", "count": 1 }, "models": { "image": [ { "model": "nano-banana-pro", "label": "Nano Banana Pro", "credits": 0 }, { "model": "nano-banana-2-lite", "label": "Nano Banana 2 Lite", "credits": 0 }, { "model": "nano-banana-2", "label": "Nano Banana 2.1", "credits": 0 } ], "video": [ { "model": "omni-flash", "label": "Omni 1.1 Flash", "credits": 4 }, { "model": "veo-3.1-lite", "label": "Veo 3.1 - Lite", "credits": 10 }, { "model": "veo-3.1-fast", "label": "Veo 3.1 - Fast", "credits": 20 }, { "model": "veo-3.1-quality", "label": "Veo 3.1 - Quality", "credits": 100 } ] } } ``` **400** **400 Bad Request** A parameter is missing or invalid, a reference belongs to another account, a default model is not on the account's Google plan, or nothing to change was sent. ```json { "error": "Nothing to change: give approval, instructions, imageDefaults or videoDefaults", "code": 400 } ``` When the account's plan does not have the model: ```json { "error": "Model veo-3.1-lite-low-priority is not available on this account's Google plan. Available: omni-flash, veo-3.1-lite, veo-3.1-fast, veo-3.1-quality", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **404** **404 Not Found** The account is not added, or `projectId` is not a project of the account. ```json { "error": "Google Flow account john@gmail.com not found", "code": 404 } ``` When `projectId` is not a project of the account: ```json { "error": "Project not found", "code": 404 } ``` **503** **503 Service Unavailable** Google Flow could not be reached, and nothing happened. Retry shortly. ```json { "error": "Google Flow is not reachable right now and could not save the agent settings. Retry", "code": 503 } ``` **596** **596 Session Error** The account's Google session is no longer valid. Delete the account with [DELETE /accounts/`email`](/docs/api-google-flow-v1/delete-google-flow-accounts-email) and add it again by following [Setup Google Flow](/docs/start-here/setup-google-flow). ##### Model The same as [GET /agent/settings](/docs/api-google-flow-v1/get-google-flow-agent-settings#model): the project's settings after the change. <details markdown="block" class="model-details"> <summary>The agent settings, field by field</summary> ```typescript { // TypeScript, all fields are optional projectId: string // the project the settings belong to, the account's agent project unless you sent projectId (created when the account had none) approval: 'ask' | 'auto' // ask: the agent asks before it spends credits instructions: { // up to 3 id: string // the instruction's id title?: string // its title, when it has one text: string // what the agent is told enabled: boolean // true: the agent follows it in every chat of the project references: string[] // media ids of the instruction's reference images }[] imageDefaults: { model: string // the model's name as models.image lists it aspectRatio: string // 16:9, 9:16, 1:1, 4:3 or 3:4 count: number // images per request, 1 to 4 } | null // null: never set videoDefaults: { // the video model, aspect ratio and count the agent uses by default, null: never set model: string // the model's name as models.video lists it aspectRatio: string // 16:9 or 9:16 count: number // videos per request, 1 to 4 } | null models: { // the models the account's Google plan has, null: Google's model list could not be read image: { // image models model: string // the name to use in imageDefaults label: string // the name the Google Flow web app shows credits?: number // lowest cost of one generation on the account's plan, 0 is free, absent when the plan is not known }[] video: { // video models model: string // the name to use in videoDefaults label: string // the name the Google Flow web app shows credits?: number // lowest cost of one generation on the account's plan, 0 is free, absent when the plan is not known }[] } | null } ``` </details> ##### Examples **Curl** ``` bash curl -X PUT "https://api.useapi.net/v1/google-flow/agent/settings" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -d '{ "email": "john@gmail.com", "approval": "ask", "imageDefaults": { "model": "nano-banana-2", "aspectRatio": "16:9", "count": 1 } }' ``` **JavaScript** ``` javascript const token = 'YOUR_API_TOKEN' const response = await fetch('https://api.useapi.net/v1/google-flow/agent/settings', { method: 'PUT', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${token}` }, body: JSON.stringify({ email: 'john@gmail.com', approval: 'ask', imageDefaults: { model: 'nano-banana-2', aspectRatio: '16:9', count: 1 } }) }) console.log(response.status, await response.json()) ``` **Python** ``` python import requests token = 'YOUR_API_TOKEN' r = requests.put( 'https://api.useapi.net/v1/google-flow/agent/settings', headers={'Authorization': f'Bearer {token}'}, json={ 'email': 'john@gmail.com', 'approval': 'ask', 'imageDefaults': {'model': 'nano-banana-2', 'aspectRatio': '16:9', 'count': 1}, }, ) print(r.status_code, r.json()) ``` === URL: https://useapi.net/docs/start-here/setup-google-vids === Document URL: https://useapi.net/docs/start-here/setup-google-vids --- layout: default title: Setup Google Vids description: "How to connect a Google AI Plus, Pro or Ultra account to the useapi.net Google Vids API — automated browser setup, the setup script, or a docs.google.com cookie paste." parent: Start Here nav_order: 220 permalink: /docs/start-here/setup-google-vids --- # Setup Google Vids October 7, 2026 (November 4, 2026) ## Table of contents Approximately 5 minutes to complete setup steps. --- > This is the setup guide for [Google Vids API](/docs/api-google-vids-v1). A [Google](https://accounts.google.com) account on a paid Google AI plan and a [useapi.net subscription](/docs/subscription) are required for the API to work. Free Google accounts get no Vids video or images. They can still be added, and make avatars, speech and talking avatar videos. **After you add the account, never open that Google account in a browser again.** Google Vids needs a session cookie that a browser renews about every 10 minutes. If any browser uses the same Google sign-in, it renews that cookie and the copy the API holds stops working within minutes. Google Vids is stricter about this than [Google Flow](/docs/start-here/setup-google-flow) and [Gemini Notebook](/docs/start-here/setup-gemini-notebook). The automated setup and the setup script below both sign in once, in a browser that is closed and deleted afterwards, so only the API uses that session. ### Which Google plan you need Google Vids generates video with Gemini Omni and meters it by plan, as seconds of video and a number of images a month. A free Google account gets 0 seconds of video and 0 images. It can still be added, and makes avatars, [speech](/docs/api-google-vids-v1/post-google-vids-speech) and [talking avatar videos](/docs/api-google-vids-v1/post-google-vids-videos-avatar) within their own monthly counts. For Omni videos and images, use an account on [Google AI Plus, Pro or Ultra](https://gemini.google/subscriptions/) (Plus gets 60 seconds of video a month). - On Google AI Ultra $199 (Google calls it Ultra 20x) the account gets 10,000 seconds of video and 1,000 images a month. - Video seconds are shared by everyone on a Google family plan, and images are counted per account. Adding more family members' accounts adds images but no video seconds. - Allowances reset on the 1st of each month. Google's figures for every plan are on its [Gemini in Google Vids](https://support.google.com/docs/answer/15609411) help page and the [Google Vids API](/docs/api-google-vids-v1) overview. Google Vids does not use [Google Flow](/docs/api-google-flow-v1) credits, so the same Google AI plan gives you both allowances. ### Turn on smart features Gemini in Google Vids works only when the account has Google Workspace smart features turned on. They are off by default in some countries. When they are off, videos and images fail with `403` and the message "has Google Workspace smart features turned off". Turn them on before you add the account: 1. Sign in to the account at [Gmail](https://mail.google.com). 2. Open Settings (the gear) → **See all settings** → **General** → **Google Workspace smart features** → **Manage Workspace smart feature settings**. 3. Turn on **Smart features in Google Workspace** and **Smart features in other Google products**, then save. If the account is already added, add it again after the change: opening it in a browser ends the session the API holds. ### Automated setup (recommended) Use our guided browser setup to connect your account automatically — no DevTools or cookie copying needed. Enter your API token, sign in with Google in the remote browser, and your account is verified and added. The remote browser is closed right after, so that sign-in is never opened again. [Open automated setup](/assets/setup-browser/google-vids.html) Prefer manual setup? Continue with the steps below. --- ### Use a dedicated Gmail account **Use a dedicated Gmail account for this API — do NOT use your personal Gmail account.** When creating a new account: 1. Enable [2-Step Verification](https://support.google.com/accounts/answer/185839) with [Microsoft Authenticator](https://www.microsoft.com/en-us/security/mobile-authenticator-app), and save the backup codes. Avoid Google Authenticator — it backs its codes up to the Google account it is signed into, which would link this dedicated account to your personal one. 2. Keep your sign-ins consistent. If you use a VPN, pick one region and stay with it rather than switching locations — an account that appears from different places in a short time is what Google treats as suspicious. The automated setup above signs in from a US browser, so it needs no VPN on your side. ### If Google asks for a phone number Occasionally Google shows a "Verify it's you" page and asks for a phone number to text a code to, even on an account that never had one. Any number that can receive SMS works. It does not have to be one already on the account. If you'd rather not use your personal number, get an inexpensive prepaid line just for this — for example a [Tello](https://tello.com) eSIM on its cheapest plan with texts (about $5/month, activated online). Tello's guide [How can I activate my Tello eSIM?](https://tello.com/help_center/how-can-i-activate-my-tello-esim) has the steps. The phone must be carrier-unlocked and support eSIM, and Tello needs you to be in the United States when you first activate the line. Install it on any phone, receive the code there, and keep the line active so you can pass future checks. Google limits how many accounts one number can verify, and it can treat accounts verified with the same number as related. Avoid online SMS-rental and "free virtual number" services. Google rejects most of them, and a rejected number can make the lock harder to clear. ### If Google asks you to scan a QR code After the password and the 2-Step Verification code, Google sometimes adds one more page, "Verify your info to continue", with a QR code. Google wants to check a phone: scan the code with the phone's camera, tap the link, follow the steps on the phone, then switch back to the computer. It shows up mostly on accounts Google treats as risky, for example when many accounts are signed in within a short time, and an authenticator app on the account does not prevent it. - To skip the phone, choose `Try another way` below the QR code and pick what Google lists: a Microsoft Authenticator code, a backup code, or a text message to a phone number (see the phone number section above). - If Google offers no other option, close the setup and try that account again later, or add a different account. - Add accounts one at a time, spread over the day, rather than many within an hour. - Have the authenticator app and the backup codes ready before you start. The setup browser closes if the sign-in isn't finished within a few minutes. ### Manual setup **Do NOT use Google Chrome.** Google's integration with Chrome interferes with cookie extraction. Use [Brave](https://brave.com/) or [Ungoogled Chromium](https://github.com/ungoogled-software/ungoogled-chromium) instead. You sign in to Google Vids, then copy the `https://docs.google.com` cookies from Developer Tools and paste them into the `cookies` field below. That one set holds every cookie the API needs: `SID`, `HSID`, `SSID`, `APISID`, `SAPISID`, `__Secure-1PSIDTS` and the `docs.google.com` `OSID`. #### Start a clean browser with the setup script (recommended) Our [Google Account Setup](https://github.com/useapi/google-account-setup) scripts for Windows, macOS and Linux give you a clean, single-use Google sign-in. They open Brave in a brand-new, empty profile, wait while you sign in and copy the cookies, and delete that profile the moment you close the browser. That takes care of three things: - A fresh, empty profile, with no other Google accounts, history or extensions. It runs separately from your normal Brave, which can stay open. - No device-bound sessions. Brave starts with `--disable-features=EnableBoundSessionCredentials,DeviceBoundSessions`, so the cookies also work outside your computer. - The profile is deleted when you close the browser. That sign-in can never be opened in a browser again, so only the API uses it. The scripts read nothing and send nothing — you copy the cookies by hand, exactly as in the manual steps below. Each script is short, so read it before you run it. 1. Install [Brave](https://brave.com/) (on Linux, Chromium works too). 2. Get the script for your system from the sections below: copy it into a file, or download it from [GitHub](https://github.com/useapi/google-account-setup). 3. Run it and choose from the menupick the service from the menu. 4. In the Brave window, sign in to your dedicated Google account, copy the cookies named above (the script names them too), and paste them into the form on this page. 5. When the account shows as added, close every window of that Brave (on a Mac, quit it with `Cmd+Q`). Keep the script's window open until it reports the profile was deleted, and do not sign in to the same Google account in any other browser afterwards. <details markdown="block"> <summary>Windows — install script</summary> [Download it from GitHub](https://github.com/useapi/google-account-setup/blob/main/google-account-setup-windows.cmd), or open Notepad, paste the script below, and save it as `google-account-setup-windows.cmd` (in the Save dialog set `Save as type` to `All Files` so it is not saved as `.txt`). Double-click the saved file. If Windows shows `Windows protected your PC`, click `More info` then `Run anyway`. ```bat ``` </details> <details markdown="block"> <summary>macOS — install script</summary> [Download it from GitHub](https://github.com/useapi/google-account-setup/blob/main/google-account-setup-mac.command) and run it with `bash ~/Downloads/google-account-setup-mac.command`, or open `Terminal` (Applications → Utilities), paste the script below into a file with `nano ~/google-account-setup-mac.command`, press `Ctrl+O` then `Enter` to save and `Ctrl+X` to exit, then run it with `bash ~/google-account-setup-mac.command`. ```bash ``` </details> <details markdown="block"> <summary>Linux / WSL — install script</summary> [Download it from GitHub](https://github.com/useapi/google-account-setup/blob/main/google-account-setup-linux.sh), or save the script below to `~/google-account-setup-linux.sh` (for example with `nano ~/google-account-setup-linux.sh`), then run it with `bash ~/google-account-setup-linux.sh`. On WSL this needs Windows 11 (WSLg) for the browser window — otherwise run the Windows script instead. ```bash ``` </details> #### Or start the browser by hand Chromium browsers on Windows and Mac now bind a Google sign-in to the device (Google's Device Bound Session Credentials). Cookies copied from a bound session are refused anywhere else, and the API answers ``, so the account cannot be added or stops working. The browser's own flags page does not turn this off (Google overrides it), but a command-line switch does. The [automated setup](#automated-setup-recommended) is not affected. 1. Quit Brave completely, including any instance left in the system tray (check Task Manager for `brave.exe`, on a Mac use `Cmd+Q`). A running Brave ignores the switch. 2. Start it from the Run box (`Win+R`) with this command, which opens a private window with no cookies and without device-bound sessions: ``` "C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe" --incognito --disable-features=EnableBoundSessionCredentials,DeviceBoundSessions ``` On a Mac, run the same switches from Terminal: ``` open -na "Brave Browser" --args --incognito --disable-features=EnableBoundSessionCredentials,DeviceBoundSessions ``` Ungoogled Chromium takes the same `--disable-features` switch. Keep this window open for the steps below. #### Sign in to Google Vids Navigate to [https://docs.google.com/videos](https://docs.google.com/videos) and sign in with your dedicated Gmail account. ![](/assets/images/google-vids-setup-1.jpg) Enter your password, then the 2-Step Verification code. Google names Google Authenticator here whichever authenticator app holds the code. **You MUST check `Don't ask again on this device`** — skipping it will break the API session. ![](/assets/images/google-vids-setup-2.jpg) #### Copy the `https://docs.google.com` cookies Once signed in you see the Google Vids home page. 1. Open Developer Tools: right-click anywhere on the page and select `Inspect` (or press `F12`), then open the `Application` tab 2. Under `Cookies`, select `https://docs.google.com` 3. Click in the cookie table and select all cookies (`Ctrl+A`) 4. Copy them (`Ctrl+C`, or right-click and `Copy`), and paste them into the `cookies` field below ![](/assets/images/google-vids-setup-3.jpg) Before you paste, look for `__Secure-1PSIDRTS` in what you copied. If it is there, the session is device-bound and will be refused: close every Brave window and start again with the command above. ### Add the account Paste everything you copied, exactly as it is. The form below sends it to [POST /accounts](/docs/api-google-vids-v1/post-google-vids-accounts), which checks the cookies with Google and reads the account's monthly allowance before the account is added. <script> async function apiAddAccountGoogleVids() { data = { method: 'POST', headers: { 'Authorization': `Bearer ${document.getElementById('post-accounts-GoogleVids-api_token').value}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ cookies: document.getElementById('post-accounts-GoogleVids-cookies')?.value }) }; await apiExecute(`https://api.useapi.net/v1/google-vids/accounts`, 'post-accounts-GoogleVids', data); } </script> <form id="post-accounts-GoogleVids" onsubmit="apiAddAccountGoogleVids(); return false;" class="input-form"> <div class="input-field"> <div class="input-field-row"> <label for="post-accounts-GoogleVids-api_token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="post-accounts-GoogleVids-api_token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> <label for="post-accounts-GoogleVids-cookies"><span>cookies</span> <textarea id="post-accounts-GoogleVids-cookies" class="input-element" rows="10" required aria-required="true" style="resize: both;"></textarea> </label> </div> <button id="post-accounts-GoogleVids-button" class="btn btn-primary fs-3" type="submit">Go</button> </div> </form> <div id="post-accounts-GoogleVids-response" class="response-placeholder visible-false"></div> A successful response is `201` for a new account or `200` for an update, with the account email, its monthly limits and how much of each is left (`quota`). Right after the account is added, close every window of that browser. Do NOT sign out of Google first — signing out ends the session the API now uses. From now on, use this Google account only through the API: do not open it in Google Vids, Gmail or any other Google page, in any browser. ### If Google signs the account out If Google ends the session of a connected account, the API detects it on the next request, re-checks it once, and then emails you right away with a link to re-add the account. Until you re-add it, the account is paused and shows the re-add message in [GET /accounts](/docs/api-google-vids-v1/get-google-vids-accounts). The most common cause is opening the same Google account in a browser. Re-add it with the [automated setup](/assets/setup-browser/google-vids.html) or the setup script, which take about a minute and leave no browser session behind. ### Usage limits Google Vids meters each plan by the month: video in seconds and images by count. A clip uses its length in seconds, whether 720p or 1080p, and an extend uses only the seconds it adds. A request Google refuses uses nothing. Once an allowance runs out Google refuses new generations until it resets on the 1st of the month. The API reports the live limits of each account at [GET /accounts/`email`](/docs/api-google-vids-v1/get-google-vids-accounts-email). === URL: https://useapi.net/docs/api-google-vids-v1/delete-google-vids-accounts-email === Document URL: https://useapi.net/docs/api-google-vids-v1/delete-google-vids-accounts-email --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> accounts/`email` description: "Remove a Google account from the useapi.net Google Vids API via DELETE accounts/email. Its Vids document and saved avatars stay on the Google account." parent: Google Vids API nav_order: 140 permalink: /docs/api-google-vids-v1/delete-google-vids-accounts-email --- ## Delete an account October 7, 2026 (November 16, 2026) --- Remove a connected Google account from your useapi.net account. The stored cookies are deleted and the account slot is freed. Nothing is deleted on Google's side. The account's Vids document and the avatars saved in it stay on the Google account, and you can connect the account again at any time with [POST /accounts](/docs/api-google-vids-v1/post-google-vids-accounts). Media, asset and avatar ids of a removed account stop working until it is connected again, and an async job still queued for it fails with `404`. > **https://api.useapi.net/v1/google-vids/accounts/`email`** - `email` is the email of a connected account, URL-encoded in the path. ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **204** **204 No Content** — the account was removed. The response body is empty. **400** **400 Bad Request** — the `email` in the path is not a valid email, or no account is connected. ```json { "error": "Path parameter email (not-an-email) not a valid email", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **404** **404 Not Found** — no account is connected for this `email`. ```json { "error": "Account user@example.com not found", "code": 404 } ``` ##### Model `204` has no body. Errors return: <details markdown="block" class="model-details"> <summary>The error answer, field by field</summary> ```typescript { // TypeScript, all fields are optional error: string code: number } ``` </details> ##### Examples **Curl** ``` bash curl -X DELETE "https://api.useapi.net/v1/google-vids/accounts/user%40example.com" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const apiUrl = `https://api.useapi.net/v1/google-vids/accounts/${encodeURIComponent(email)}`; const response = await fetch(apiUrl, { method: "DELETE", headers: { "Authorization": `Bearer ${token}`, }, }); console.log("response", response.status); ``` **Python** ``` python import requests from urllib.parse import quote token = "API token" email = "Previously configured account email" apiUrl = f"https://api.useapi.net/v1/google-vids/accounts/{quote(email, safe='')}" headers = { "Authorization" : f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers) print(response.status_code) ``` === URL: https://useapi.net/docs/api-google-vids-v1/delete-google-vids-avatars-avatarId === Document URL: https://useapi.net/docs/api-google-vids-v1/delete-google-vids-avatars-avatarId --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> avatars/`avatarId` description: "Delete an avatar from its account's Vids document via DELETE avatars/avatarId in the useapi.net Google Vids API. Clips already made with it are not affected." parent: Google Vids API nav_order: 620 permalink: /docs/api-google-vids-v1/delete-google-vids-avatars-avatarId --- ## Delete an avatar October 7, 2026 (November 16, 2026) --- Remove an avatar from the account's Vids document. This works for avatars made with [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) and for those made in the Google Vids web app, as listed by [GET /avatars](/docs/api-google-vids-v1/get-google-vids-avatars). Clips already made with the avatar are not affected. Apart from the one Vids document it creates when you add the account, avatars are the only thing the API saves on a Google account. Generated videos, images and uploads live in Google's temporary storage and need no deleting, see [How long files last](/docs/api-google-vids-v1/get-google-vids-media-mediaId#how-long-files-last). > **https://api.useapi.net/v1/google-vids/avatars/`avatarId`** - `avatarId` is the avatar's id, URL-encoded in the path (it contains `:` and `@`). It names its account, so no `email` is needed. ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **204** **204 No Content** — the avatar was deleted. The response body is empty. **400** **400 Bad Request** — the path value is not an `avatarId`. ```json { "error": "Path parameter avatarId (…) is not a valid avatar id", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** — the `avatarId` was issued to a different API token. ```json { "error": "avatar id does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** — the avatar is already gone from the Vids document, or its account is not connected. ```json { "error": "Avatar not found in the Vids document", "code": 404 } ``` **502** **502 Bad Gateway** — Google did not remove the avatar. Retry. ```json { "error": "Google did not remove the avatar, please retry", "code": 502 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Google Vids](/docs/start-here/setup-google-vids). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-google-vids", "code": 596 } ``` ##### Model `204` has no body. Errors return: <details markdown="block" class="model-details"> <summary>The error answer, field by field</summary> ```typescript { // TypeScript, all fields are optional error: string code: number } ``` </details> ##### Examples **Curl** ``` bash AVATARID="user:12345-user@example.com-avatar:eyJnIjoiaDMy…" curl -X DELETE -H "Authorization: Bearer …" \ "https://api.useapi.net/v1/google-vids/avatars/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$AVATARID")" ``` **JavaScript** ``` javascript const token = "API token"; const avatarId = "avatarId from GET /avatars"; const apiUrl = `https://api.useapi.net/v1/google-vids/avatars/${encodeURIComponent(avatarId)}`; const response = await fetch(apiUrl, { method: "DELETE", headers: { "Authorization": `Bearer ${token}`, }, }); console.log("response", response.status); ``` **Python** ``` python import requests from urllib.parse import quote token = "API token" avatarId = "avatarId from GET /avatars" apiUrl = "https://api.useapi.net/v1/google-vids/avatars/" + quote(avatarId, safe="") headers = { "Authorization" : f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers) print(response.status_code) ``` === URL: https://useapi.net/docs/api-google-vids-v1/get-google-vids-accounts-email === Document URL: https://useapi.net/docs/api-google-vids-v1/get-google-vids-accounts-email --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts/`email` description: "Check one Google Vids account live via GET accounts/email in the useapi.net API: whether Google still signs it in, and the video seconds, images, speech and avatar videos left." parent: Google Vids API nav_order: 120 permalink: /docs/api-google-vids-v1/get-google-vids-accounts-email --- ## Retrieve an account October 7, 2026 (November 16, 2026) --- Get one connected account with a live read from Google: whether the session is still signed in, and how much of each monthly allowance is left. The read uses the stored cookies exactly as a generation does. The answer is kept for about a minute, so a repeat call within a minute returns the same answer without asking Google again. The video counter is in seconds, the image counter in images, `speech` in Gemini uses (one per [POST /speech](/docs/api-google-vids-v1/post-google-vids-speech) and one for the speech of each talking avatar video) and `avatarVideo` in AI avatar videos ([POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar)). On a Google family plan the video seconds are shared by every family member, so two accounts of one family show the same `video.left`. See [Plans and monthly allowances](/docs/api-google-vids-v1#plans-and-monthly-allowances). A signed-out session found here is handled like on any other request. The API re-checks it once, and if it is still signed out the account is paused and you receive an email with the re-add link. > **https://api.useapi.net/v1/google-vids/accounts/`email`** - `email` is the email of a connected account, URL-encoded in the path. ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** ```json { "email": "user@example.com", "maxJobs": 3, "added": "2026-10-07T02:21:08.626Z", "updated": "2026-10-07T05:47:38.929Z", "cookies": [ "SID", "HSID", "SSID", "APISID", "SAPISID", "__Secure-1PSIDTS", "OSID" ], "cookiesExpireAt": "2027-04-05T02:18:00.438Z", "vidsDocId": "1N48K72jE4hpv4A3XPH3rf0EVTpMCERAwf4uDmQPc6v4", "limits": { "video": 10000, "image": 1000, "music": 300, "speech": 50, "avatarVideo": 10 }, "health": "OK", "session": "signed-in", "quota": { "video": { "limit": 10000, "left": 9652, "resetAt": "2026-11-01T07:00:00.000Z" }, "image": { "limit": 1000, "left": 947, "resetAt": "2026-11-01T07:00:00.000Z" }, "music": { "limit": 300, "left": 298, "resetAt": "2026-11-01T07:00:00.000Z" }, "speech": { "limit": 50, "left": 37, "resetAt": "2026-11-01T07:00:00.000Z" }, "avatarVideo": { "limit": 10, "left": 8, "resetAt": "2026-11-01T07:00:00.000Z" } } } ``` - `session` tells what the live read found: - `signed-in` — the account works, and `quota` is fresh from Google. If the plan's limits changed (for example the account moved from free to a Google AI plan), `limits` is updated, and new jobs use it right away. An account added before November 4, 2026 gets its `speech` and `avatarVideo` limits here on its first call. - `signed-out` — Google signed the account out. It is paused, `health` holds the re-add message and you receive an email with the re-add link. - `verifying` — another request is re-checking the session right now. Retry in about a minute. - `unknown (could not reach Google to re-check)` and `unavailable (…)` — Google could not be reached, or its Vids page did not answer normally. The account is not paused. Retry later. - `unknown` — the session works but the allowance read failed. `quotaError` holds the reason. - `quota` is returned only with `session: signed-in`. A counter Google did not answer is `null`. `resetAt` is the 1st of next month, 00:00 Pacific time. - `exhaustedUntil` is present while the account sits out video, image, speech or avatar video jobs because Google reported that allowance used up (see [GET /accounts](/docs/api-google-vids-v1/get-google-vids-accounts)). When the live read shows allowance left for that kind of job, for example after a plan upgrade, this call removes it and the account takes those jobs again right away. To check again after a plan change, wait a minute between calls. - An account that is already paused (its `health` is the re-add message, or `verifying`) is returned as stored, without `session` or `quota`. Re-add a paused account with [POST /accounts](/docs/api-google-vids-v1/post-google-vids-accounts). **400** **400 Bad Request** — the `email` in the path is not a valid email, or no account is connected yet. ```json { "error": "Path parameter email (not-an-email) not a valid email", "code": 400 } ``` ```json { "error": "Please configure at least one account at https://useapi.net/docs/api-google-vids-v1/post-google-vids-accounts", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **404** **404 Not Found** — no account is connected for this `email`. ```json { "error": "Account user@example.com not found", "code": 404 } ``` ##### Model The stored account record plus a live read: the `session` state and what is left of each monthly allowance in `quota`. <details markdown="block" class="model-details"> <summary>The account record with its live session and allowances, field by field</summary> ```typescript { // TypeScript, all fields are optional email: string maxJobs: number // jobs this account may run at the same time added: string // ISO 8601, when the account was first connected updated?: string // ISO 8601, the last re-add or maxJobs change cookies: string[] // names of the stored cookies, never their values cookiesExpireAt?: string | null // ISO 8601, the earliest expiry date in the pasted cookies vidsDocId: string // the Google Vids document the API created on the account limits: { // monthly limits, read from Google on add and kept current by GET /accounts/{email} video: number | null // seconds of video image: number | null // images music: number | null // songs (not used by this API) speech?: number | null // Gemini uses: POST /speech, and the speech of each talking avatar video avatarVideo?: number | null // AI avatar videos (POST /videos/avatar) } avatarsOnly?: true // 0 video and 0 images (e.g. a free Google account): no clips or images, only avatars, speech and avatar videos health: string // 'OK', 'verifying', or the reason the account must be re-added exhaustedUntil?: { // job types this account sits out, only while in force (a re-add clears it) video?: string // ISO 8601, Google's reset time for the used-up video seconds image?: string // ISO 8601, Google's reset time for the used-up images speech?: string // ISO 8601, Google's reset time for the used-up Gemini uses avatarVideo?: string // ISO 8601, Google's reset time for the used-up AI avatar videos } addedVia?: 'setup-browser' // present when the account was added by the automated setup session?: string // what the live read found, see Responses quota?: { // session 'signed-in' only, null when a counter did not answer video: { limit: number, left: number, resetAt: string } | null // seconds of video image: { limit: number, left: number, resetAt: string } | null // images music: { limit: number, left: number, resetAt: string } | null // songs (not used by this API) speech: { limit: number, left: number, resetAt: string } | null // Gemini uses: POST /speech and the speech of each avatar video avatarVideo: { limit: number, left: number, resetAt: string } | null // AI avatar videos (POST /videos/avatar) } quotaError?: string // present with session 'unknown' } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/google-vids/accounts/user%40example.com" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const apiUrl = `https://api.useapi.net/v1/google-vids/accounts/${encodeURIComponent(email)}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests from urllib.parse import quote token = "API token" email = "Previously configured account email" apiUrl = f"https://api.useapi.net/v1/google-vids/accounts/{quote(email, safe='')}" headers = { "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-google-vids-v1/get-google-vids-accounts === Document URL: https://useapi.net/docs/api-google-vids-v1/get-google-vids-accounts --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts description: "List the Google accounts connected to the useapi.net Google Vids API via GET accounts, with each account's health, maxJobs and monthly video, image, speech and avatar video limits." parent: Google Vids API nav_order: 110 permalink: /docs/api-google-vids-v1/get-google-vids-accounts --- ## Retrieve all accounts October 7, 2026 (November 16, 2026) --- List the Google accounts connected with [POST /accounts](/docs/api-google-vids-v1/post-google-vids-accounts). Each entry shows the account's `health`, its `maxJobs`, the monthly limits Google reported when it was added (an account added before November 4, 2026 shows its `speech` and `avatarVideo` limits after its next [GET /accounts/`email`](/docs/api-google-vids-v1/get-google-vids-accounts-email)), and `exhaustedUntil` while the account sits out a kind of job because its allowance is used up. This endpoint does not call Google. For the live session and what is left of each allowance use [GET /accounts/`email`](/docs/api-google-vids-v1/get-google-vids-accounts-email). [GET /jobs](/docs/api-google-vids-v1/get-google-vids-jobs) shows how many jobs each account is running. > **https://api.useapi.net/v1/google-vids/accounts** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** ```json { "user@example.com": { "email": "user@example.com", "maxJobs": 3, "added": "2026-10-07T02:21:08.626Z", "updated": "2026-10-07T05:47:38.929Z", "cookies": [ "SID", "HSID", "SSID", "APISID", "SAPISID", "__Secure-1PSIDTS", "OSID" ], "cookiesExpireAt": "2027-04-05T02:18:00.438Z", "vidsDocId": "1N48K72jE4hpv4A3XPH3rf0EVTpMCERAwf4uDmQPc6v4", "limits": { "video": 10000, "image": 1000, "music": 300, "speech": 50, "avatarVideo": 10 }, "health": "OK", "exhaustedUntil": { "video": "2026-11-01T07:00:00.000Z" } }, "another@example.com": { "email": "another@example.com", "maxJobs": 3, "added": "2026-10-07T01:07:47.890Z", "cookies": [ "SID", "HSID", "SSID", "APISID", "SAPISID", "__Secure-1PSIDTS", "OSID" ], "cookiesExpireAt": "2027-04-05T01:05:12.204Z", "vidsDocId": "1zeizDjTAw4DyXjNZKPkHuAhHJt87J6COR_Hc4L3gKJw", "limits": { "video": 10000, "image": 1000, "music": 300, "speech": 50, "avatarVideo": 10 }, "health": "Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-google-vids" } } ``` - The response is an object keyed by account email, or `{}` when no account is connected. - `health` is `OK`, `verifying` while the API re-checks an account Google reported as signed out, or the reason the account must be re-added. A paused account takes no new jobs until you re-add it with [POST /accounts](/docs/api-google-vids-v1/post-google-vids-accounts). - `exhaustedUntil` appears when Google refused a job because the account's monthly video seconds (`video`), images (`image`), Gemini uses (`speech`) or AI avatar videos (`avatarVideo`) were used up. Until that time, Google's reset time, the account gets no jobs of that kind: jobs without `email` go to your other accounts, and a request that must run on this account gets `429` with `retryAt`. It is shown only while in force. [GET /accounts/`email`](/docs/api-google-vids-v1/get-google-vids-accounts-email) removes it early when Google shows allowance left again, for example after a plan upgrade, and a re-add with [POST /accounts](/docs/api-google-vids-v1/post-google-vids-accounts) clears it. Uploads and avatars are never held back by it. **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` ##### Model An object keyed by account email, each with its `health`, `maxJobs`, monthly `limits` and any `exhaustedUntil` reset times. <details markdown="block" class="model-details"> <summary>Every account record, keyed by email, field by field</summary> ```typescript { // TypeScript, all fields are optional [email: string]: { email: string maxJobs: number // jobs this account may run at the same time added: string // ISO 8601, when the account was first connected updated?: string // ISO 8601, the last re-add or maxJobs change cookies: string[] // names of the stored cookies, never their values cookiesExpireAt?: string | null // ISO 8601, the earliest expiry date in the pasted cookies vidsDocId: string // the Google Vids document the API created on the account limits: { // monthly limits, read from Google on add and kept current by GET /accounts/{email} video: number | null // seconds of video image: number | null // images music: number | null // songs (not used by this API) speech?: number | null // Gemini uses: POST /speech, and the speech of each talking avatar video avatarVideo?: number | null // AI avatar videos (POST /videos/avatar) } avatarsOnly?: true // 0 video and 0 images (e.g. a free Google account): no clips or images, only avatars, speech and avatar videos health: string // 'OK', 'verifying', or the reason the account must be re-added exhaustedUntil?: { // job types this account sits out, only while in force (a re-add clears it) video?: string // ISO 8601, Google's reset time for the used-up video seconds image?: string // ISO 8601, Google's reset time for the used-up images speech?: string // ISO 8601, Google's reset time for the used-up Gemini uses avatarVideo?: string // ISO 8601, Google's reset time for the used-up AI avatar videos } addedVia?: 'setup-browser' // present when the account was added by the automated setup } } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/google-vids/accounts" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = "https://api.useapi.net/v1/google-vids/accounts"; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" apiUrl = "https://api.useapi.net/v1/google-vids/accounts" headers = { "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-google-vids-v1/get-google-vids-avatars === Document URL: https://useapi.net/docs/api-google-vids-v1/get-google-vids-avatars --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> avatars description: "List the avatars on your Google Vids accounts via GET avatars in the useapi.net API, including ones made in the Vids web app, with avatarId and voice." parent: Google Vids API nav_order: 610 permalink: /docs/api-google-vids-v1/get-google-vids-avatars --- ## List avatars October 7, 2026 (November 16, 2026) --- List the avatars saved in your accounts' Vids documents, each with an `avatarId` ready to pass as `avatar` to [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar) (a talking-head video of a script), as `avatar_1`..`avatar_3` to [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos), or as `avatar` to [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) to make a changed copy. The list is read live from Google, so it includes avatars made in the Google Vids web app on that document as well as those made with [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars). An avatar made in the web app with one of Google's older narrator voices is listed with `voice: null` and a `note`. It cannot be used in a video through the API, but it can be the start of a new avatar with another voice: pass its `avatarId` as `avatar` to POST /avatars. Make a new avatar with [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) instead. Each avatar comes with `previewMediaId`, its picture, which downloads with [GET /media/`mediaId`](/docs/api-google-vids-v1/get-google-vids-media-mediaId). A fresh one is made on every call, so download it soon after listing. It is for download only: to start a new avatar from this one, pass its `avatarId` as `avatar` to POST /avatars. Without `email`, every healthy account is read. An account that could not be read is listed under `errors`, and the others are still returned. > **https://api.useapi.net/v1/google-vids/avatars?email=`email`** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `email` is optional, read one account only. URL-encode it. ##### Responses **200** **200 OK** ```json { "avatars": [ { "avatarId": "user:12345-user@example.com-avatar:eyJnIjoiaDMy…", "name": "Ruby", "voice": "Kaci", "voiceId": "Autonoe", "voiceStyle": "Bright", "voicePreview": "https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Autonoe.wav", "previewMediaId": "user:12345-user@example.com-image:eyJ1IjoiaHR0cHM6Ly9kb2NzLmdvb2dsZS5jb20v…", "email": "user@example.com" }, { "avatarId": "user:12345-user@example.com-avatar:eyJnIjoiaDMy…", "name": "Marco", "voice": "Holt", "voiceId": "Charon", "voiceStyle": "Informative", "voicePreview": "https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Charon.wav", "previewMediaId": "user:12345-user@example.com-image:eyJ1IjoiaHR0cHM6Ly9kb2NzLmdvb2dsZS5jb20v…", "email": "user@example.com" } ] } ``` - `avatars` is `[]` when no account has an avatar. **400** **400 Bad Request** — `email` is not a valid email, or no account is connected yet. ```json { "error": "Please configure at least one account at https://useapi.net/docs/api-google-vids-v1/post-google-vids-accounts", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **404** **404 Not Found** — the account named by `email` is not connected. ```json { "error": "Account user@example.com is not configured", "code": 404 } ``` ##### Model Your accounts' avatars, each with its `avatarId`, name, voice, preview picture and account, plus `errors` for accounts that could not be read. <details markdown="block" class="model-details"> <summary>The list of avatars, field by field</summary> ```typescript { // TypeScript, all fields are optional avatars: { avatarId: string // pass it as avatar_1..avatar_3 to POST /videos name: string voice: string | null // the Vids voice name, null for an older narrator voice voiceId?: string // Google's voice id voiceStyle?: string // Google's label for the voice voicePreview?: string // a public English sample of the voice (WAV) previewMediaId?: string // the avatar's picture: download it with GET /media/{mediaId} note?: string // voice null: why the avatar cannot be used in a video email: string // the account the avatar is saved on }[] errors?: { // accounts that could not be read email: string error: string }[] } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/google-vids/avatars?email=user%40example.com" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = "https://api.useapi.net/v1/google-vids/avatars"; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" apiUrl = "https://api.useapi.net/v1/google-vids/avatars" headers = { "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-google-vids-v1/get-google-vids-jobs-jobid === Document URL: https://useapi.net/docs/api-google-vids-v1/get-google-vids-jobs-jobid --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> jobs/`jobid` description: "Poll a Google Vids video, image, speech or talking avatar job via GET jobs/jobid in the useapi.net API: its status, the finished mediaId and quota, or the error code." parent: Google Vids API nav_order: 820 permalink: /docs/api-google-vids-v1/get-google-vids-jobs-jobid --- ## Retrieve a job October 7, 2026 (November 16, 2026) --- Fetch a job record by its `jobid`. Every generation is a job: [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos), [POST /videos/extend](/docs/api-google-vids-v1/post-google-vids-videos-extend), [POST /videos/upscale](/docs/api-google-vids-v1/post-google-vids-videos-upscale), [POST /videos/edit](/docs/api-google-vids-v1/post-google-vids-videos-edit), [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar), [POST /images](/docs/api-google-vids-v1/post-google-vids-images) and [POST /speech](/docs/api-google-vids-v1/post-google-vids-speech) all return one. After an async request, poll this endpoint until `status` is `completed` or `failed`. A video takes 20 seconds to about 2 minutes (an extend or an edit takes the longest), a talking avatar video 1 to 2.5 minutes, an image about 10 seconds and speech a few, so polling every 10 seconds is enough. A job may run for up to 15 minutes, and a sync POST that answered `202` hands you a job that is still running. A job still not finished about 16 minutes after it was created is failed with `504` when it is read. Instead of polling, pass `replyUrl` (and optionally `replyRef`) with the POST: when the job completes or fails, the API sends one `POST` of this same job record, as JSON, to that URL. See [Model](#model). Job records are kept for 7 days. After that the job answers `410`. > **https://api.useapi.net/v1/google-vids/jobs/`jobid`** - `jobid` is URL-encoded in the path (it contains `:` and `@`), for example `j1007155127045518215v-u12345-email%3Auser%40example.com-bot%3Agoogle-vids`. ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** Completed (an async text-to-video job): ```json { "jobid": "j1007155127045518215v-u12345-email:user@example.com-bot:google-vids", "type": "video", "mode": "text", "email": "user@example.com", "status": "completed", "created": "2026-10-07T06:29:01.204Z", "request": { "prompt": "A hot air balloon rising over a misty valley at sunrise", "duration": 3, "async": true }, "updated": "2026-10-07T06:29:27.207Z", "completed": "2026-10-07T06:29:27.207Z", "result": { "mediaId": "user:12345-user@example.com-video:eyJ1IjoiaHR0…", "width": 1280, "height": 720, "duration": 3, "resolution": "720p", "aspectRatio": "landscape", "model": "/flix/generate_videos_omni_t2v_psq/v1", "quota": { "video": { "limit": 10000, "left": 9615, "resetAt": "2026-11-01T07:00:00.000Z" } }, "elapsedMs": 24611 } } ``` Running: ```json { "jobid": "j1007155127045518215v-u12345-email:user@example.com-bot:google-vids", "type": "video", "mode": "text", "email": "user@example.com", "status": "processing", "created": "2026-10-07T06:29:01.204Z", "request": { "prompt": "A hot air balloon rising over a misty valley at sunrise", "duration": 3, "async": true }, "updated": "2026-10-07T06:29:02.461Z" } ``` Failed (Google refused an edit of an uploaded video): ```json { "jobid": "j1007123831345945676v-u12345-email:user@example.com-bot:google-vids", "type": "video", "mode": "edit", "email": "user@example.com", "status": "failed", "created": "2026-10-07T06:36:31.478Z", "request": { "video": "user:12345-user@example.com-asset:…", "duration": 4, "prompt": "Make the sky stormy and dark" }, "updated": "2026-10-07T06:36:41.176Z", "completed": "2026-10-07T06:36:41.176Z", "error": { "code": 422, "message": "Google refused this request (\"That request looks like it goes against our terms. Try asking something else.\"). Change the prompt or the inputs and try again." } } ``` **400** **400 Bad Request** The path value is not a Google Vids `jobid`. ```json { "error": "Path parameter jobid (…) is not a valid job id", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** ```json { "error": "This job does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** No such job. ```json { "error": "Job not found", "code": 404 } ``` **410** **410 Gone** The job has expired: job records are kept for 7 days. ```json { "error": "Job has expired", "code": 410 } ``` ##### Model The job record. [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos), [POST /videos/extend](/docs/api-google-vids-v1/post-google-vids-videos-extend), [POST /videos/upscale](/docs/api-google-vids-v1/post-google-vids-videos-upscale), [POST /videos/edit](/docs/api-google-vids-v1/post-google-vids-videos-edit), [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar), [POST /images](/docs/api-google-vids-v1/post-google-vids-images) and [POST /speech](/docs/api-google-vids-v1/post-google-vids-speech) return it too, and it is the body of the `replyUrl` webhook. <details markdown="block" class="model-details"> <summary>The job record, field by field, and what each <code>status</code> and <code>error.code</code> means</summary> ```typescript { // TypeScript, all fields are optional jobid: string // j<time><random><v|i|s|a>-u<id>-email:<email>-bot:google-vids type: 'video' | 'image' | 'speech' | 'avatarVideo' mode?: 'text' | 'image' | 'ingredients' | 'extend' | 'upscale' | 'edit' // video jobs only email: string // the account the job runs on status: 'processing' | 'completed' | 'failed' created: string // ISO 8601, when the job was accepted updated?: string // ISO 8601, the last status change completed?: string // ISO 8601, when the job completed or failed request: Record<string, unknown> // your request body as sent (ids as strings) replyUrl?: string replyRef?: string error?: { // status 'failed' code: number // 400 | 403 | 404 | 422 | 429 | 500 | 502 | 503 | 504 | 596, see GET /jobs/{jobid} message: string retryAt?: string // code 429: ISO 8601, when to try again quota?: { // code 429 for allowance: Google's counter for this kind of job when it refused it limit: number // monthly limit (seconds of video, images, Gemini uses or AI avatar videos) left: number // what was left, 0 when used up resetAt: string // ISO 8601, when the allowance resets } } result?: { // status 'completed' mediaId: string // download it with GET /media/{mediaId}. A video: extend / upscale / edit it. An image: use it as startImage, referenceImage_N or avatar image. Speech: a WAV width?: number // video and image height?: number // video and image duration?: number // video: length of the whole clip in whole seconds. Speech: length of the audio in seconds resolution?: '720p' | '1080p' // video aspectRatio?: 'landscape' | 'portrait' // video speechDuration?: number // avatarVideo: length of the spoken script in seconds model: string | null // Google's backend path, e.g. /flix/generate_videos_omni_t2v_psq/v1 quota?: { // what the account has left after this job (absent when Google sends no counter) video?: { limit: number, left: number, resetAt: string } // seconds, video jobs image?: { limit: number, left: number, resetAt: string } // images, image jobs speech?: { limit: number, left: number, resetAt: string } // Gemini uses, speech jobs; absent when Google sends no counter for the account's plan avatarVideo?: { limit: number, left: number, resetAt: string } // AI avatar videos, avatarVideo jobs } elapsedMs: number // how long Google took } } ``` | `status` | Meaning | |---|---| | `processing` | Google is generating. Every job starts here. | | `completed` | Done. `result.mediaId` downloads the file with [GET /media/`mediaId`](/docs/api-google-vids-v1/get-google-vids-media-mediaId). | | `failed` | Done without a file. `error` says why. | A job sent without `email` and without input ids can change `email` while it runs: when Google refuses it because that account's allowance is used up or its smart features are off, it moves to another of your accounts, never to one whose allowance for that kind of job is used up. | `error.code` | Meaning | |---|---| | `400` | Google rejected the request as invalid, and `message` has Google's reason. Or the script of a talking avatar video runs over 30 seconds when spoken. | | `403` | The account's Google plan has no Vids allowance for this kind of job (a monthly limit of 0), for example no AI avatar videos, or the account has [Google Workspace smart features](/docs/start-here/setup-google-vids#turn-on-smart-features) turned off. | | `404` | The account was removed with [DELETE /accounts/`email`](/docs/api-google-vids-v1/delete-google-vids-accounts-email) before the async job ran. | | `422` | Google refused the prompt or the inputs ("That request looks like it goes against our terms"). Nothing was charged. Change the prompt or the inputs. In our tests every edit of an uploaded video ended here. For a talking avatar video, `422` can also mean Google's safety check refused the finished video: Google still counts that one against the account's AI avatar videos. | | `429` | The account's monthly allowance is used up or too low for this job: `retryAt` is the reset time and `quota` shows what was left (`limit`, `left`, `resetAt`). A used-up account then gets no jobs of that kind until that time, see [GET /accounts](/docs/api-google-vids-v1/get-google-vids-accounts). Or Google is limiting the account for a short while, and `retryAt` is about a minute away. | | `500` | An unexpected error on our side. | | `502` | Google answered, but without a file the API could read, or with an unexpected error (for a talking avatar video: Google could not make it, and `message` has Google's reason). Google may have made and charged the file, so running it again is not free: report the jobid to support. | | `503` | Google answered with a server error or could not be reached, or the async job could not be queued. Retry. | | `504` | Google did not answer within 5 minutes, Google did not finish a talking avatar video within the job's time, or Google's answer never reached us within 15 minutes. In the last two cases Google may have made and counted or charged the file, but it cannot be retrieved. | | `596` | Google reported the account as signed out. While we re-check it, retry in about a minute. If it stays signed out, re-add it via [Setup Google Vids](/docs/start-here/setup-google-vids). | A sync POST whose job fails answers with the HTTP status in `error.code` and the failed job record as the body. The `replyUrl` webhook is one `POST` with `Content-Type: application/json` and this record as the body, sent once when the job completes or fails (a 10-second timeout, no retries, redirects are not followed). Use `replyRef` to match the callback to your own records. </details> ##### Examples **Curl** ``` bash JOBID="j1007155127045518215v-u12345-email:user@example.com-bot:google-vids" curl -H "Authorization: Bearer …" \ "https://api.useapi.net/v1/google-vids/jobs/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$JOBID")" ``` **JavaScript** ``` javascript const token = "API token"; const jobid = "j1007155127045518215v-u12345-email:user@example.com-bot:google-vids"; const apiUrl = `https://api.useapi.net/v1/google-vids/jobs/${encodeURIComponent(jobid)}`; let job; do { await new Promise(resolve => setTimeout(resolve, 10000)); const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); job = await response.json(); console.log(job.status); } while (job.status === "processing"); console.log("job", job); ``` **Python** ``` python import requests, time, urllib.parse token = "API token" jobid = "j1007155127045518215v-u12345-email:user@example.com-bot:google-vids" apiUrl = "https://api.useapi.net/v1/google-vids/jobs/" + urllib.parse.quote(jobid, safe="") headers = { "Authorization" : f"Bearer {token}" } while True: time.sleep(10) job = requests.get(apiUrl, headers=headers).json() print(job.get("status")) if job.get("status") != "processing": break print(job) ``` === URL: https://useapi.net/docs/api-google-vids-v1/get-google-vids-jobs === Document URL: https://useapi.net/docs/api-google-vids-v1/get-google-vids-jobs --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> jobs description: "See what each Google Vids account is generating via GET jobs in the useapi.net API: the jobs running now and each account's count against maxJobs." parent: Google Vids API nav_order: 810 permalink: /docs/api-google-vids-v1/get-google-vids-jobs --- ## List running jobs October 7, 2026 (November 16, 2026) --- List the jobs running right now and, for every connected account, how many of its `maxJobs` slots they take. A job is listed from the moment [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos), [POST /videos/extend](/docs/api-google-vids-v1/post-google-vids-videos-extend), [POST /videos/upscale](/docs/api-google-vids-v1/post-google-vids-videos-upscale), [POST /videos/edit](/docs/api-google-vids-v1/post-google-vids-videos-edit), [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar), [POST /images](/docs/api-google-vids-v1/post-google-vids-images) or [POST /speech](/docs/api-google-vids-v1/post-google-vids-speech) accepts it until it completes or fails. Each listed job takes one of its account's slots. When all slots of an account are taken, a new job on it is refused with `429`, and a job without `email` goes to another account that has a free slot. Uploads and avatars take no slot. Poll a single job with [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid). This endpoint reads our own records only and never calls Google, so it is cheap to poll. > **https://api.useapi.net/v1/google-vids/jobs** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** ```json { "running": [ { "jobid": "j1007155127045518215v-u12345-email:user@example.com-bot:google-vids", "email": "user@example.com", "created": "2026-10-07T06:29:01.204Z", "type": "video", "mode": "text" } ], "accounts": { "user@example.com": { "running": 1, "maxJobs": 3 }, "another@example.com": { "running": 0, "maxJobs": 3 } } } ``` **400** **400 Bad Request** — no account is connected yet. ```json { "error": "Please configure at least one account at https://useapi.net/docs/api-google-vids-v1/post-google-vids-accounts", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` ##### Model Each running job with its id, account and type, and for each account how many jobs it runs out of its `maxJobs`. <details markdown="block" class="model-details"> <summary>The running jobs and each account's slots, field by field</summary> ```typescript { // TypeScript, all fields are optional running: { jobid: string email: string // the account the job runs on created: string // ISO 8601, when the job was accepted type: 'video' | 'image' | 'speech' | 'avatarVideo' mode?: 'text' | 'image' | 'ingredients' | 'extend' | 'upscale' | 'edit' // video jobs only }[] accounts: { [email: string]: { running: number // jobs running on this account now maxJobs: number // its limit, set with POST /accounts } } } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/google-vids/jobs" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = "https://api.useapi.net/v1/google-vids/jobs"; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" apiUrl = "https://api.useapi.net/v1/google-vids/jobs" headers = { "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-google-vids-v1/get-google-vids-media-mediaId === Document URL: https://useapi.net/docs/api-google-vids-v1/get-google-vids-media-mediaId --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> media/`mediaId` description: "Download a generated Google Vids video (MP4), image (JPEG) or speech (WAV) via GET media/mediaId in the useapi.net API, streamed from Google with Range support." parent: Google Vids API nav_order: 800 permalink: /docs/api-google-vids-v1/get-google-vids-media-mediaId --- ## Download a video, image or speech October 7, 2026 (November 16, 2026) --- Download a finished video, image or speech. The response body is the file itself, streamed from Google on each request and never stored by us. Google's file links open only with the Google account's cookies, so a finished job returns a `mediaId` instead, and this endpoint fetches the file with the account that made it. Pass the `result.mediaId` of any job from [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos), [POST /videos/extend](/docs/api-google-vids-v1/post-google-vids-videos-extend), [POST /videos/upscale](/docs/api-google-vids-v1/post-google-vids-videos-upscale), [POST /videos/edit](/docs/api-google-vids-v1/post-google-vids-videos-edit), [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar), [POST /images](/docs/api-google-vids-v1/post-google-vids-images) or [POST /speech](/docs/api-google-vids-v1/post-google-vids-speech), or the `previewMediaId` of a generated [avatar](/docs/api-google-vids-v1/post-google-vids-avatars). ### How long files last Generated videos, generated images and uploaded files live in Google's temporary storage. They are never saved to the account's Vids document, Google Drive or a gallery, so nothing piles up on the account and there is nothing to delete. Download the files you want to keep soon after they are made with [GET /media/`mediaId`](/docs/api-google-vids-v1/get-google-vids-media-mediaId): images stay available for a few hours and videos for 24 hours. After that the download answers `404`. Upload an input with [POST /assets](/docs/api-google-vids-v1/post-google-vids-assets) shortly before the job that uses it. Avatars are the exception. They are saved in the account's Vids document, together with any avatars made in the Google Vids web app, until you delete them with [DELETE /avatars/`avatarId`](/docs/api-google-vids-v1/delete-google-vids-avatars-avatarId). > **https://api.useapi.net/v1/google-vids/media/`mediaId`** - `mediaId` is a video, image or audio (speech) `mediaId`, URL-encoded in the path (it contains `:` and `@`). An `assetId` cannot be downloaded. ##### Request Headers ``` yaml Authorization: Bearer {API token} # Optional, passed through to Google Range: bytes=0-1048575 ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. - `Range` is optional. It is forwarded to Google, so a player can seek in a video or a client can resume a download. A range request answers `206 Partial Content` with `Content-Range`. ##### Response headers - `Content-Type`: `video/mp4` for a video, `image/jpeg` for an image, `audio/wav` for speech. - `Content-Disposition`: `inline; filename="video.mp4"`, `inline; filename="image.jpg"` or `inline; filename="speech.wav"`. - `Content-Length`, `Content-Range`, `Accept-Ranges`: passed through from Google when it sends them. ##### Responses **200** **200 OK** The raw file bytes (not JSON), for example: ``` Content-Type: video/mp4 Content-Length: 718046 Content-Disposition: inline; filename="video.mp4" ``` **206** **206 Partial Content** The requested byte range of the file, when the request carried a `Range` header. **400** **400 Bad Request** The path value is not a video, image or audio `mediaId`. ```json { "error": "Path parameter mediaId (…) is not a valid video / image / audio id", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The `mediaId` was issued to a different API token. ```json { "error": "video id does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** The file has expired at Google (images last a few hours, videos 24 hours), or the account that made it is not connected. ```json { "error": "This file has expired at Google (HTTP 403). Generated files are temporary: download them soon after they are made", "code": 404 } ``` ```json { "error": "Account user@example.com (from the video id) is not configured", "code": 404 } ``` **502** **502 Bad Gateway** Google did not serve the file, or answered with a page instead of the file. Retry shortly. ```json { "error": "Google answered HTTP 500 for this file", "code": 502 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Google Vids](/docs/start-here/setup-google-vids). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-google-vids", "code": 596 } ``` ##### Model A successful response is the file itself (not JSON), with the headers listed above. Errors return: <details markdown="block" class="model-details"> <summary>The error answer, field by field</summary> ```typescript { // TypeScript, all fields are optional error: string code: number } ``` </details> ##### Examples **Curl** ``` bash MEDIAID="user:12345-user@example.com-video:eyJ1IjoiaHR0…" curl -H "Authorization: Bearer …" \ "https://api.useapi.net/v1/google-vids/media/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$MEDIAID")" \ --output video.mp4 ``` **JavaScript** ``` javascript const token = "API token"; const mediaId = "mediaId from a finished job"; const apiUrl = `https://api.useapi.net/v1/google-vids/media/${encodeURIComponent(mediaId)}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); if (!response.ok) console.log("error", response.status, await response.json()); else { const file = await response.arrayBuffer(); console.log("downloaded", file.byteLength, response.headers.get("content-type")); } ``` **Python** ``` python import requests from urllib.parse import quote token = "API token" mediaId = "mediaId from a finished job" apiUrl = "https://api.useapi.net/v1/google-vids/media/" + quote(mediaId, safe="") headers = { "Authorization" : f"Bearer {token}" } with requests.get(apiUrl, headers=headers, stream=True) as response: response.raise_for_status() with open("video.mp4", "wb") as f: for chunk in response.iter_content(chunk_size=1 << 20): f.write(chunk) ``` === URL: https://useapi.net/docs/api-google-vids-v1/get-google-vids-voices === Document URL: https://useapi.net/docs/api-google-vids-v1/get-google-vids-voices --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> voices description: "List the 30 Gemini voices for Google Vids avatars via GET voices in the useapi.net API, with Google's style labels and samples in 18 languages, no token." parent: Google Vids API nav_order: 700 permalink: /docs/api-google-vids-v1/get-google-vids-voices --- ## List voices October 7, 2026 (November 16, 2026) --- List the 30 voices an [avatar](/docs/api-google-vids-v1/post-google-vids-avatars) or [speech](/docs/api-google-vids-v1/post-google-vids-speech) can use, in the order the Vids editor shows them. Each voice has its Vids name, Google's voice id and Google's one-word style label, plus links to Google's own pregenerated sample of the voice in 18 languages. Pass either the `name` or the `voice` id as `voice` to [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) or [POST /speech](/docs/api-google-vids-v1/post-google-vids-speech). Voices are free. To hear a voice read your own script, use POST /speech. This endpoint is public: it needs no API token and no connected account, and any web page may call it. The list is fixed, so the response is cached for 24 hours. | `name` | `voice` | `style` | English sample | |---|---|---|---| | `Nyla` | `Achernar` | Soft | <audio controls preload="none" src="https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Achernar.wav" style="height: 32px; width: 240px;"></audio> | | `Holt` | `Charon` | Informative | <audio controls preload="none" src="https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Charon.wav" style="height: 32px; width: 240px;"></audio> | | `Knox` | `Algieba` | Smooth | <audio controls preload="none" src="https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Algieba.wav" style="height: 32px; width: 240px;"></audio> | | `Tyra` | `Erinome` | Clear | <audio controls preload="none" src="https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Erinome.wav" style="height: 32px; width: 240px;"></audio> | | `Paz` | `Enceladus` | Breathy | <audio controls preload="none" src="https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Enceladus.wav" style="height: 32px; width: 240px;"></audio> | | `Umi` | `Sadaltager` | Knowledgeable | <audio controls preload="none" src="https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Sadaltager.wav" style="height: 32px; width: 240px;"></audio> | | `Jett` | `Algenib` | Gravelly | <audio controls preload="none" src="https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Algenib.wav" style="height: 32px; width: 240px;"></audio> | | `Elio` | `Achird` | Friendly | <audio controls preload="none" src="https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Achird.wav" style="height: 32px; width: 240px;"></audio> | | `Lani` | `Callirrhoe` | Easy-going | <audio controls preload="none" src="https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Callirrhoe.wav" style="height: 32px; width: 240px;"></audio> | | `Zeno` | `Alnilam` | Firm | <audio controls preload="none" src="https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Alnilam.wav" style="height: 32px; width: 240px;"></audio> | | `Kaci` | `Autonoe` | Bright | <audio controls preload="none" src="https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Autonoe.wav" style="height: 32px; width: 240px;"></audio> | | `Tova` | `Aoede` | Breezy | <audio controls preload="none" src="https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Aoede.wav" style="height: 32px; width: 240px;"></audio> | | `Lora` | `Despina` | Smooth | <audio controls preload="none" src="https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Despina.wav" style="height: 32px; width: 240px;"></audio> | | `Fola` | `Sulafat` | Warm | <audio controls preload="none" src="https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Sulafat.wav" style="height: 32px; width: 240px;"></audio> | | `Yori` | `Zubenelgenubi` | Casual | <audio controls preload="none" src="https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Zubenelgenubi.wav" style="height: 32px; width: 240px;"></audio> | | `Iro` | `Rasalgethi` | Informative | <audio controls preload="none" src="https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Rasalgethi.wav" style="height: 32px; width: 240px;"></audio> | | `Fira` | `Leda` | Youthful | <audio controls preload="none" src="https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Leda.wav" style="height: 32px; width: 240px;"></audio> | | `Nyx` | `Iapetus` | Clear | <audio controls preload="none" src="https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Iapetus.wav" style="height: 32px; width: 240px;"></audio> | | `Neo` | `Puck` | Upbeat | <audio controls preload="none" src="https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Puck.wav" style="height: 32px; width: 240px;"></audio> | | `Baya` | `Umbriel` | Easy-going | <audio controls preload="none" src="https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Umbriel.wav" style="height: 32px; width: 240px;"></audio> | | `Peli` | `Laomedeia` | Upbeat | <audio controls preload="none" src="https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Laomedeia.wav" style="height: 32px; width: 240px;"></audio> | | `Jacy` | `Schedar` | Even | <audio controls preload="none" src="https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Schedar.wav" style="height: 32px; width: 240px;"></audio> | | `Cale` | `Orus` | Firm | <audio controls preload="none" src="https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Orus.wav" style="height: 32px; width: 240px;"></audio> | | `Orla` | `Vindemiatrix` | Gentle | <audio controls preload="none" src="https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Vindemiatrix.wav" style="height: 32px; width: 240px;"></audio> | | `Dori` | `Sadachbia` | Lively | <audio controls preload="none" src="https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Sadachbia.wav" style="height: 32px; width: 240px;"></audio> | | `Sani` | `Zephyr` | Bright | <audio controls preload="none" src="https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Zephyr.wav" style="height: 32px; width: 240px;"></audio> | | `Kero` | `Fenrir` | Excitable | <audio controls preload="none" src="https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Fenrir.wav" style="height: 32px; width: 240px;"></audio> | | `Saro` | `Gacrux` | Mature | <audio controls preload="none" src="https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Gacrux.wav" style="height: 32px; width: 240px;"></audio> | | `Lito` | `Kore` | Firm | <audio controls preload="none" src="https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Kore.wav" style="height: 32px; width: 240px;"></audio> | | `Vira` | `Pulcherrima` | Forward | <audio controls preload="none" src="https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Pulcherrima.wav" style="height: 32px; width: 240px;"></audio> | Sample languages: `en`, `es`, `fr`, `de`, `it`, `ja`, `ko`, `pt`, `nl`, `hi`, `id`, `ar`, `ru`, `tr`, `vi`, `th`, `pl`, `uk`. > **https://api.useapi.net/v1/google-vids/voices** ##### Request Headers None. No `Authorization` header is needed. ##### Responses **200** **200 OK** The list, shortened to its first voice and three of its sample languages: ```json { "voices": [ { "name": "Nyla", "voice": "Achernar", "style": "Soft", "preview": "https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Achernar.wav", "previews": { "en": "https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Achernar.wav", "es": "https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/es/Achernar.wav", "fr": "https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/fr/Achernar.wav", ... } }, ... ], "languages": [ "en", "es", "fr", ... ] } ``` **404** **404 Not Found** — a path below `/voices`, which does not exist. ```json { "error": "Unknown path /v1/google-vids/voices/Nyla", "code": 404 } ``` ##### Model The voices, each with its Vids name, Google's voice id, its style label and links to its WAV samples, plus the sample languages. <details markdown="block" class="model-details"> <summary>The list of voices, field by field</summary> ```typescript { // TypeScript, all fields are optional voices: { name: string // the Vids name, e.g. 'Holt' voice: string // Google's voice id, e.g. 'Charon' style: string // Google's one-word label for the voice, e.g. 'Informative' preview: string // the English sample (WAV) previews: { [language: string]: string // the sample in each language of `languages` (WAV) } }[] languages: string[] // the sample languages } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/google-vids/voices" ``` **JavaScript** ``` javascript const response = await fetch("https://api.useapi.net/v1/google-vids/voices"); const { voices } = await response.json(); console.table(voices.map(({ name, voice, style }) => ({ name, voice, style }))); ``` **Python** ``` python import requests voices = requests.get("https://api.useapi.net/v1/google-vids/voices").json()["voices"] for v in voices: print(v["name"], v["voice"], v["style"]) ``` === URL: https://useapi.net/docs/api-google-vids-v1 === Document URL: https://useapi.net/docs/api-google-vids-v1 --- layout: default title: Google Vids API nav_logo: /assets/images/google-vids.svg nav_title: Google Vids API seo_title: "Google Vids API: Gemini Omni Video and Voiced AI Avatars" description: "Third-party Google Vids API by useapi.net: Gemini Omni 1.2 Flash video up to 15 s, extend, upscale, edit, talking avatars and speech on your Google AI subscription, REST or MCP." nav_order: 2025 has_children: true permalink: /docs/api-google-vids-v1 repo: https://github.com/useapi/google-vids-api --- # <img style="height:1em;vertical-align: middle;" src="/assets/images/google-vids.svg" alt=""> Google Vids API October 7, 2026 (November 16, 2026) This is a [third-party](/docs/legal#affiliation--third-party-services) API for [Google Vids](https://docs.google.com/videos) by Google. It uses your [Google AI subscription](https://gemini.google/subscriptions/): Free, Plus $4.99 (or [$9.99 with 2 TB of storage](https://one.google.com/about/plans)), Pro $19.99, Ultra $99.99 or Ultra $199.99 a month (as of November 2026). Through a REST API and a hosted MCP server, it makes Gemini Omni 1.2 Flash videos of up to 15 seconds with sound at 720p or 1080p, extends, upscales and edits them, and makes images, speech and talking avatars with [30 voices](/docs/api-google-vids-v1/get-google-vids-voices). Google publishes no Google Vids API, and Vids asks for no captcha and has its own monthly Omni allowance, separate from Google Flow credits. ## Models | Model | What it makes | Notes | |---|---|---| | [Gemini Omni 1.2 Flash](https://workspaceupdates.googleblog.com/2026/11/gemini-omni-12-flash-now-in-vids-with-15second-generations-and-improved-quality.html) | [Video](/docs/api-google-vids-v1/post-google-vids-videos) with sound and speech from text, a start image, or up to 3 references that mix your images and avatars | 3 to 15 seconds, 720p or 1080p, landscape or portrait, [extend](/docs/api-google-vids-v1/post-google-vids-videos-extend) by up to 10 seconds at a time, on clips of up to 24 seconds, to about 34 seconds, [upscale](/docs/api-google-vids-v1/post-google-vids-videos-upscale) to 1080p, [edit](/docs/api-google-vids-v1/post-google-vids-videos-edit) up to 15 seconds by prompt | | Avatars | [Avatars](/docs/api-google-vids-v1/post-google-vids-avatars): a picture and one of 30 [voices](/docs/api-google-vids-v1/get-google-vids-voices) | From a description, your own photo, a Vids image or another avatar, changed in words or with a logo, up to 3 in one Omni video for a dialogue, kept until you [delete](/docs/api-google-vids-v1/delete-google-vids-avatars-avatarId) them | | Talking avatar video | [A talking head](/docs/api-google-vids-v1/post-google-vids-videos-avatar) that reads your script in the avatar's voice | Up to 30 seconds, 720p landscape, with sound | | Gemini voices | [Speech](/docs/api-google-vids-v1/post-google-vids-speech) from a script | WAV in 30 voices, scripts up to 2,500 characters, audio tags like `[whisper]` | | Vids images | [Images](/docs/api-google-vids-v1/post-google-vids-images) from text | About 1 megapixel, 16:9, 1:1 or 9:16, in 7 styles, for references and avatar pictures | | More | [Uploads](/docs/api-google-vids-v1/post-google-vids-assets) of JPEG, PNG, WebP or MP4 up to 50 MB, [downloads](/docs/api-google-vids-v1/get-google-vids-media-mediaId), and [avatars made in the Vids web app](/docs/api-google-vids-v1/get-google-vids-avatars) | | Google added Omni to Vids in September 2026 and moved it to Omni 1.2 Flash, with clips of up to 15 seconds, on November 5, 2026. The Vids web app calls it just "Omni". Make a single clip at 1080p directly, for the same seconds as 720p. For a clip you will extend or edit, work at 720p and [upscale](/docs/api-google-vids-v1/post-google-vids-videos-upscale) once at the end: a 1080p clip is an upscaled 720p one, and each extend at 1080p processes the whole clip again and over-sharpens faces ([see the comparison](/blog/261106v#720p-or-1080p-what-a-1080p-extend-does)). Vids images are basic, with no reference images and no larger size. For better images use the [Google Flow API](/docs/api-google-flow-v1/post-google-flow-images): Nano Banana with reference images, at up to 4K. Every video carries Google's invisible SynthID watermark and a visible Gemini ✦ in a corner, and the API returns Google's file unchanged. The free [watermark remover](https://github.com/useapi/google-vids-api/tree/main/watermark-remover) in our GitHub examples takes the visible ✦ off clips as generated and their upscales ([details](/docs/api-google-vids-v1/post-google-vids-videos#watermark)). ## MCP server The hosted [Google Vids MCP server](/docs/api-google-vids-v1/mcp) gives Claude Code, Cursor, VS Code and other AI assistants 18 tools for videos, extends, upscales, edits, images, uploads, avatars, talking avatar videos and speech, with your useapi.net API token and nothing to install. It is listed in the official MCP Registry as `net.useapi/google-vids`, and the [google-vids-api](https://github.com/useapi/google-vids-api) repo also adds it in one step as a [Claude Code plugin](https://github.com/useapi/google-vids-api#use-with-claude-code) or a [Gemini CLI extension](https://github.com/useapi/google-vids-api#use-with-gemini-cli). ## Pricing What one video costs on Google's [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) and on each Google AI subscription (as of November 2026). Vids has no credits: each subscription comes with seconds of video, a number of images and a number of AI avatar videos a month, listed on Google's [Gemini in Google Vids](https://support.google.com/docs/answer/15609411) page, so a video costs its share of the subscription. On a subscription a 1080p video uses the same seconds as a 720p one, while Google's API charges 50% more for it. | Model | [Official API](https://ai.google.dev/gemini-api/docs/pricing) | Ultra $199.99/m (10,000 s/mo) | Ultra $99.99/m (2,500 s/mo) | Pro $19.99/m (500 s/mo) | Plus $4.99/m (60 s/mo) | |---|---|---|---|---|---| | Omni 1.2 Flash (720p, 15 s) | $1.04 ($0.07/s) | $0.30 / 15 s (666 videos/mo) | $0.60 / 15 s (166 videos/mo) | $0.60 / 15 s (33 videos/mo) | $1.25 / 15 s (4 videos/mo) | | Omni 1.2 Flash (1080p, 15 s) | $1.56 ($0.104/s) | $0.30 / 15 s (666 videos/mo) | $0.60 / 15 s (166 videos/mo) | $0.60 / 15 s (33 videos/mo) | $1.25 / 15 s (4 videos/mo) | | Omni 1.2 Flash (720p, 10 s) | $0.70 ($0.07/s) | $0.20 / 10 s (1,000 videos/mo) | $0.40 / 10 s (250 videos/mo) | $0.40 / 10 s (50 videos/mo) | $0.83 / 10 s (6 videos/mo) | | Vids image | no API | $0 / 0 s (1,000 images/mo) | $0 / 0 s (300 images/mo) | $0 / 0 s (30 images/mo) | $0 / 0 s (≤50 images/mo) | | Avatar | no API | $0 / 0 s (1 image) | $0 / 0 s (1 image) | $0 / 0 s (1 image) | $0 / 0 s (1 image) | | Talking avatar (video, up to 30 s) | no API | $0 / 0 s (1 avatar video) | $0 / 0 s (1 avatar video) | $0 / 0 s (1 avatar video) | $0 / 0 s (1 avatar video) | | Speech | no API | $0 / 0 s (unlimited) | $0 / 0 s (unlimited) | $0 / 0 s (unlimited) | $0 / 0 s (1 of 50 credits) | - A free Google account makes avatars at no cost, and in our tests (November 2026) it had 10 AI avatar videos and 50 Gemini uses (speech) a month, but no video seconds or images in Vids, so Omni videos and images skip it. - A video uses its length in seconds, at the same rate for 720p and 1080p, and references or avatars add nothing. An [extend](/docs/api-google-vids-v1/post-google-vids-videos-extend) uses only the seconds it adds, an [upscale](/docs/api-google-vids-v1/post-google-vids-videos-upscale) uses the clip's seconds again, and an [edit](/docs/api-google-vids-v1/post-google-vids-videos-edit) uses at most the seconds it edits (in our tests a 15-second edit used 10). A request Google refuses uses nothing. - Video seconds are shared by everyone on a Google family plan, while images are counted per account. Allowances reset on the 1st of the month at 00:00 Pacific time. - A [talking avatar video](/docs/api-google-vids-v1/post-google-vids-videos-avatar) uses 1 of the account's AI avatar videos and 1 Gemini use for its speech, and no video seconds. Google counts it even when its safety check refuses the finished video. [Speech](/docs/api-google-vids-v1/post-google-vids-speech) uses 1 Gemini use. - Google lists AI voice-over as unlimited on Google AI Pro and Ultra, and as 1 credit per voice-over on a free account and on Plus, out of 50 credits a month shared with other Vids actions ([Google's limits](https://support.google.com/docs/answer/15609411)). The API follows the `speech` counter Google reports for each account: in our tests (November 2026) an account in an Ultra $199.99 family plan, not the plan owner, had 50 a month. [GET /accounts/`email`](/docs/api-google-vids-v1/get-google-vids-accounts-email) shows it. - [GET /accounts/`email`](/docs/api-google-vids-v1/get-google-vids-accounts-email) shows what each account has left. When an allowance runs out, the job fails with `429` and the reset time, and the account takes no more jobs of that kind until then. - The seconds and images per plan are Google's figures, and our tests on Ultra $199.99 match them. Plan prices are Google's US prices. Vids seconds are separate from [Google Flow API](/docs/api-google-flow-v1) credits, so one Google account connected to both makes Omni videos in each, on top of each other. #### One Google account, four APIs The same Google AI plan powers several useapi.net APIs, each from its own allowance, so one Google account connected to all of them gets the most out of the plan: - [Google Flow API](/docs/api-google-flow-v1): Veo 3.1, Omni 1.2 Flash and Omni 1.1 Flash video, Nano Banana images up to 4K, from Flow credits. - [Google Vids API](/docs/api-google-vids-v1): Omni 1.2 Flash video up to 15 seconds, 30-second [talking avatar videos](/docs/api-google-vids-v1/post-google-vids-videos-avatar) from a photo, avatars in 30 voices and [text to speech](/docs/api-google-vids-v1/post-google-vids-speech), from the Vids allowance, which does not use Flow credits. - [Gemini Notebook API (NotebookLM API)](/docs/api-gemini-notebook-v1): chat with sources, Deep Research and every Studio output, from the Gemini Notebook usage limits. - [Flow Music API](/docs/api-flowmusic-v1): full songs with Lyria in Google Flow Music, on the Flow Music plan your Google AI subscription includes (Starter on [Plus](https://support.google.com/googleone/answer/16882689), Plus on [Pro](https://support.google.com/googleone/answer/14534406), Member on [Ultra](https://support.google.com/googleone/answer/16286513)) or on Flow Music's own plans. Each API is set up on its own setup page, and one useapi.net subscription covers all of them. ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. ## Run several Google Vids accounts Each useapi.net subscription connects 3 Google accounts, up to 100 in total. Video and image requests don't need `email`: each job goes to an account that is healthy, has a free slot within its `maxJobs` (1 to 10, default 3) and has allowance left for that kind of job. A job Google refuses because the account's allowance is used up moves to another account with allowance left and runs there. When every account is busy you get `429`, so wait and send it again. When every account has used up its allowance, the `429` comes at once with `retryAt`, the earliest reset time. Pass `email` to pin a job to one account. A job that uses an upload, an avatar or an earlier clip runs on the account that holds it. Accounts of one family plan share their video seconds, so adding them runs more jobs at once and adds images, but no seconds. Every job can post its finished record to your webhook with `replyUrl`, or you poll [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid), so a video, which takes from about 20 seconds to over 2 minutes for an extend or an edit, needs no open connection. [GET /jobs](/docs/api-google-vids-v1/get-google-vids-jobs) shows what each account is running. Download results soon: videos stay available for 24 hours and images for a few hours ([how long files last](/docs/api-google-vids-v1/get-google-vids-media-mediaId#how-long-files-last)). [How useapi.net works](/docs/how-it-works) has tips for keeping your accounts healthy. ## Questions ### Does Google Vids have an API? Through useapi.net, yes. Google has published no Google Vids API (as of October 2026), and the useapi.net Google Vids API makes Gemini Omni 1.2 Flash videos of up to 15 seconds, images and talking avatars in Vids over REST, on your Google AI subscription. The [MCP server](/docs/api-google-vids-v1/mcp) gives the same tools to Claude Code, Cursor and other AI assistants, with nothing to install. ### How much does the Google Vids API cost? Through useapi.net, a 10-second Omni 1.2 Flash video uses about $0.20 of Google AI Ultra $199.99, against about $0.70 at 720p on Google's [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) (as of November 2026). On the same plan a 15-second 1080p video uses about $0.30, against $1.56 on the Gemini API. Images and avatars use no video seconds. The [price table](#pricing) shows every plan. ### Is there a Google Vids API key? Through useapi.net, one [API token](/docs/start-here/setup-useapi) is the only key you need. Connect your Google account once with the [automated setup](/docs/start-here/setup-google-vids): you sign in with Google in a remote browser, with no cookies to copy, no Google Cloud project, no Gemini API key and no captcha provider. If Google ever signs the account out, you get an email with a link to re-add it. ### Can the Google Vids API make talking AI avatars? Through useapi.net, yes, while Google offers Vids avatars only in its web app: [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) pairs a person's picture, drawn or from your own photo, with one of 30 Gemini voices. The avatar reads a script of up to 30 seconds as a [talking-head video](/docs/api-google-vids-v1/post-google-vids-videos-avatar), or up to 3 avatars speak the lines you write in a [video](/docs/api-google-vids-v1/post-google-vids-videos) prompt. The [AI influencer tutorial](/docs/articles/google-vids-influencer-avatars) builds a clip step by step. [Setup Google Vids](/docs/start-here/setup-google-vids) [Google Account Setup](https://github.com/useapi/google-account-setup) Scripts for a clean, single-use Google sign-in (Windows, macOS, Linux) [LLM-friendly API spec](https://useapi.net/assets/aibot/api-google-vids-v1.txt) Feed this to your LLM to build integrations [Claude Code skill](/llm-tools) A drop-in useapi.net skill for Claude Code, and a rule for Cursor [Postman collection](https://www.postman.com/useapinet/useapi-net/collection/29112081-9ef3d017-d44c-4f43-a4cb-7351b9b265df) (November 6, 2026) [MCP Server](/docs/api-google-vids-v1/mcp) Make Vids clips, images, talking avatars and speech from Claude Code, Cursor, VS Code and other MCP clients [Agent skill: google-vids-video](https://github.com/useapi/google-vids-api/tree/main/skills/google-vids-video) Claude Code and Codex make Omni 1.2 Flash clips and talking avatars for you: `npx skills add useapi/google-vids-api --skill google-vids-video` [GitHub examples](https://github.com/useapi/google-vids-api) Node.js and Python: voiced-avatar influencer clips, an n8n workflow, an agent skill for Claude Code and Codex, and a remover for the visible Gemini ✦ [n8n template: Talking Avatar App]({% include n8n-url.html t="vids-avatar" %}) Describe or pick a presenter, choose a voice, write the lines and get a talking avatar video of up to about 34 s, ready to import Articles: * [Can You Use Your Google AI Subscription Through an API? What Plus, Pro and Ultra Get You](/docs/articles/google-ai-subscription-api) {% include lang-switch.html mode="hub" key="google-ai-subscription" %} * [Gemini Omni 1.2 Flash in Google Flow and Google Vids: 15-second videos, extend, edit and price per video](/docs/articles/gemini-omni-1-2-flash-api) {% include lang-switch.html mode="hub" key="gemini-omni-1-2-flash" %} * [How to Make AI Influencer Videos with Avatars via the Google Vids API](/docs/articles/google-vids-influencer-avatars) {% include lang-switch.html mode="hub" key="google-vids" %} Examples: * [Omni 1.2 Flash: 15-second videos, a 10-second extension and a 15-second edit](/blog/261106v) * [30-second talking avatars from a photo, and text to speech](/blog/261104) Videos on YouTube: * [Gemini Omni 1.2 Flash in Google Vids: 15 seconds from one prompt, extended to 25](https://www.youtube.com/watch?v=eJ3js18XCBM) * [Two AI influencers launch a sneaker: Google Vids avatars and Gemini Omni 1.1 Flash](https://www.youtube.com/watch?v=ofCtt7xRBCk) Developer Community: * <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> * <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> === URL: https://useapi.net/docs/api-google-vids-v1/mcp === Document URL: https://useapi.net/docs/api-google-vids-v1/mcp --- layout: default title: MCP Server nav_icon: mcp seo_title: "Google Vids MCP Server: Gemini Omni Video and Voiced Avatars" description: "Connect the Claude app, ChatGPT, Claude Code or any MCP client to the hosted useapi.net Google Vids MCP server: 18 tools for Omni video, talking avatars and speech." parent: Google Vids API nav_order: 50 permalink: /docs/api-google-vids-v1/mcp --- ## Google Vids MCP Server October 16, 2026 (November 6, 2026) --- The useapi.net Google Vids MCP server lets an AI assistant such as the Claude app, ChatGPT, Claude Code, Cursor or VS Code Copilot make videos with [Google Vids](https://docs.google.com/videos) on your own Google accounts. It is a hosted [Model Context Protocol](https://modelcontextprotocol.io) server with 18 tools: generate Gemini Omni 1.2 Flash clips of up to 15 seconds with sound and speech from text, a start image or up to 3 references, extend, upscale and edit them, make images, upload your own pictures, create voiced avatars from a description, a photo or another avatar, make an avatar read a script as a talking-head video, and turn a script into speech. Each tool calls the [Google Vids API](/docs/api-google-vids-v1), so the same rules and limits apply. Nothing needs to be installed or hosted. **Is there a Google Vids MCP server?** Yes. useapi.net, a third-party service not affiliated with Google, hosts one at `https://api.useapi.net/v1/google-vids/mcp` with 18 tools for Gemini Omni 1.2 Flash video, images, talking avatars and speech, on your own Google AI Pro or Ultra plan, nothing to install. Prefer REST? Tutorial: [How to Make AI Influencer Videos with Avatars via the Google Vids API](/docs/articles/google-vids-influencer-avatars) · Code: [github.com/useapi/google-vids-api](https://github.com/useapi/google-vids-api) See all useapi.net MCP servers on [Model Matrix & MCP](/model-matrix#mcp-servers). ## Endpoint and authorization ``` https://api.useapi.net/v1/google-vids/mcp ``` - Transport: Streamable HTTP. - Listed in the [official MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers/net.useapi%2Fgoogle-vids/versions/latest) as `net.useapi/google-vids`, so MCP clients and directories that read the registry can find it by that name. - Authorization: your useapi.net API token in the `Authorization: Bearer …` header, see [Setup useapi.net](/docs/start-here/setup-useapi). The Claude app and ChatGPT sign in with OAuth instead, see [Use it in the Claude app or ChatGPT](#use-it-in-the-claude-app-or-chatgpt). - You need at least one Google account added with [Setup Google Vids](/docs/start-here/setup-google-vids). Adding and removing accounts is not available over MCP: use [POST /accounts](/docs/api-google-vids-v1/post-google-vids-accounts) or the setup page. ## Setup Replace `YOUR_API_TOKEN` with your useapi.net API token. ### Claude Code ```bash claude mcp add --transport http useapi-google-vids https://api.useapi.net/v1/google-vids/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` ### Cursor In `~/.cursor/mcp.json`: ```json { "mcpServers": { "useapi-google-vids": { "url": "https://api.useapi.net/v1/google-vids/mcp", "headers": { "Authorization": "Bearer YOUR_API_TOKEN" } } } } ``` ### VS Code In `.vscode/mcp.json`: ```json { "servers": { "useapi-google-vids": { "type": "http", "url": "https://api.useapi.net/v1/google-vids/mcp", "headers": { "Authorization": "Bearer YOUR_API_TOKEN" } } } } ``` ### Windsurf and other clients Any client that supports remote MCP servers over HTTP with custom headers works. The usual JSON shape: ```json { "mcpServers": { "useapi-google-vids": { "serverUrl": "https://api.useapi.net/v1/google-vids/mcp", "headers": { "Authorization": "Bearer YOUR_API_TOKEN" } } } } ``` Some clients name the address field `url` instead of `serverUrl`. ### Test it with curl ```bash curl -s https://api.useapi.net/v1/google-vids/mcp \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}' curl -s https://api.useapi.net/v1/google-vids/mcp \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' ``` The first call answers with the server's name `useapi-google-vids` and its instructions for the assistant, the second with the 18 tools. ## Use it in the Claude app or ChatGPT The Claude app ([claude.ai](https://claude.ai) and Claude Desktop) and [ChatGPT](https://chatgpt.com) can add this server as a custom connector. They sign in with OAuth: you give the app the URL, it opens a useapi.net page, and you paste your useapi.net API token there once. Both work on their Free plans. The API-token setups above for Claude Code, Cursor, VS Code and other clients keep working as before. ``` ``` ### Claude app 1. Open Settings → Connectors and click Add custom connector. 2. Enter a name, for example `useapi `, and the URL above, then click Add. 3. Click Connect. Claude opens the useapi.net sign-in page. 4. Paste your useapi.net API token and click Allow. Claude asks before each tool call unless you choose Always allow. The Free plan allows one custom connector. ### ChatGPT 1. Open Plugins, click Add and choose Add custom MCP server. 2. Enter a name and the URL above, and set Authentication to OAuth. 3. Tick ChatGPT's "I understand and want to continue" box, then click Create as a plugin. 4. Click Connect. ChatGPT opens the useapi.net sign-in page. 5. Paste your useapi.net API token and click Allow. ChatGPT asks you to confirm each tool call that creates or changes something. The Free plan works without developer mode (as of October 25, 2026). ### How the sign-in works - Your API token is in your welcome email, see [Setup useapi.net](/docs/start-here/setup-useapi). The useapi.net page links there too. - Each connection is for one MCP server. Connect each server you want to use on its own. - The app gets an access token that lasts 1 hour and renews it on its own. A connection you don't use for 90 days lapses, and you connect again. - [Resetting your API token](/docs/account-management/post-account-token-reset) disconnects every app connected with it. - - Results come back as public links, so they open right in the app. ## Tools Clips, images, uploads and avatars are named by the ids the tools return, and each id carries its account, so a follow-up runs on the account that holds its inputs. Tools that start a job take an optional `email` to pick the account. ### Accounts | Tool | What it does | Main parameters | |---|---|---| | `vids_list_accounts` | Lists your accounts with health, `maxJobs` and the plan's monthly limits. | | | `vids_get_account` | Checks one account live: signed in or not, and what is left of this month's video seconds, images, AI avatar videos (`avatarVideo`) and Gemini uses (`speech`). | `email` | | `vids_update_account` | Sets `maxJobs`, the jobs an account runs at once. | `email`, `maxJobs` | ### Videos and images | Tool | What it does | Main parameters | |---|---|---| | `vids_create_video` | Generates a 3 to 15 second clip with sound and speech from text, from a start image, or from up to 3 references (images and avatars, named in the prompt as `@referenceImage_1` or `@avatar_1`). | `prompt`, `duration`, `aspectRatio`, `resolution`, `startImage`, `referenceImage_1`..`3`, `avatar_1`..`3`, `email` | | `vids_extend_video` | Adds 3 to 10 seconds per call to a clip of up to 24 seconds and returns the whole clip, so about 34 seconds at most. | `mediaId`, `prompt`, `duration` | | `vids_upscale_video` | Turns a `720p` clip of up to 20 seconds into `1080p`. | `mediaId` | | `vids_edit_video` | Changes up to 15 seconds of a clip by prompt: colours, objects, style. | `video`, `prompt`, `duration` | | `vids_create_image` | Generates one JPEG in one of 7 styles, returned as an image the assistant can see. | `prompt`, `aspectRatio`, `style`, `email` | | `vids_create_avatar_video` | Makes an avatar read a script in its own voice: a 1280×720 talking-head video as long as the speech, up to 30 seconds (script up to 400 characters, audio tags like `[whisper]` allowed). Uses 1 AI avatar video of the account, also when Google's safety check refuses the finished clip. Takes 1 to 2.5 minutes, so it usually returns the `jobid`. | `avatar`, `script` | | `vids_create_speech` | Turns a script of up to 2,500 characters into a WAV in one of the 30 voices, to hear a voice before a talking avatar video or to use the audio elsewhere. Uses 1 Gemini use of the account. | `script`, `voice`, `email` | | `vids_get_job` | Reads a video, image, speech or talking avatar video job, and with `wait: true` waits for it to finish. | `jobid`, `wait` | | `vids_list_jobs` | Lists the jobs running now and each account's running count against `maxJobs`. | | The parameters match [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos), [POST /videos/extend](/docs/api-google-vids-v1/post-google-vids-videos-extend), [POST /videos/upscale](/docs/api-google-vids-v1/post-google-vids-videos-upscale), [POST /videos/edit](/docs/api-google-vids-v1/post-google-vids-videos-edit), [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar), [POST /images](/docs/api-google-vids-v1/post-google-vids-images) and [POST /speech](/docs/api-google-vids-v1/post-google-vids-speech). ### Files, avatars and voices | Tool | What it does | Main parameters | |---|---|---| | `vids_upload_asset` | Uploads your own JPEG, PNG or WebP image from a public https URL of up to 50 MB, or sent as `contentBase64`, and returns an `assetId` for `startImage` or `referenceImage_N`, or for a person's photo or a logo in `vids_create_avatar`. Upload with the `email` of the account you will use it on. | `url` or `contentBase64`, `mimeType`, `email` | | `vids_get_media` | Checks a video, image or speech `mediaId` and returns its download URL. An image also comes back as an image the assistant can see. | `mediaId` | | `vids_list_voices` | Lists the 30 Gemini voices with their style and preview audio. | | | `vids_list_avatars` | Lists the avatars saved on your accounts, including ones made in the Google Vids web app. | `email` | | `vids_create_avatar` | Makes a new voiced avatar from exactly one start: a description (`appearance`), a person's photo from `vids_upload_asset` or an image from `vids_create_image` (`image`), or an existing avatar (`avatar`). `refine` and `logo` then change the picture. Each picture Google makes counts 1 image where the plan has an image allowance, and costs nothing on a plan without one. Google refuses photos of prominent people. The new picture comes back as an image. | `name`, `voice`, `appearance`, `outfit`, `shot`, `expression`, `details`, `image`, `avatar`, `refine`, `logo`, `email` | | `vids_delete_avatar` | Deletes an avatar. | `avatarId` | The full input schema of every tool comes from `tools/list`. ## Long-running work MCP clients usually give up on a tool call after about a minute, so a tool waits up to about 50 seconds: - An image usually finishes in about 10 seconds, and the tool returns it. - A `720p` clip often finishes in that time. A `1080p` clip, an extend, an upscale or an edit takes longer. The tool then returns the `jobid`, and `vids_get_job` with `wait: true` picks it up. Ask the assistant to keep checking until it is done. - `vids_create_avatar` answers in about 10 to 60 seconds, the longest when a photo or description is also refined. - `vids_create_speech` usually finishes in a few seconds. - `vids_create_avatar_video` takes 1 to 2.5 minutes, so it returns the `jobid`: `vids_get_job` with `wait: true` picks it up. Clients that ask for progress notifications get one about every 10 seconds while a tool waits. Clips come back as a `mediaId` with a download URL. Fetch it with the same `Authorization` header, and download soon, since Google keeps the files only for a while, see [How long files last](/docs/api-google-vids-v1/get-google-vids-media-mediaId#how-long-files-last). ## Example prompts - "Make a 10-second 1080p clip of a fox running through a snowy forest at dawn." - "Make a photo of a red bicycle in a Lisbon street, then turn it into a clip where someone rides it away." - "Create an avatar of a cheerful chef in her fifties with the Neo voice, then make a portrait clip where she says: 'Today we bake bread.'" - "Upload this photo of me, make it an avatar in a navy blazer with the Holt voice, and have it read this 20-second product intro." - "Read this script in the Kaci voice so I can hear it before I make the avatar video." - "Upload this product photo and make a clip of my avatar holding it and talking about it." - "Extend the last clip by 8 seconds with the camera pulling back, then upscale it to 1080p." - "How many video seconds are left on my Vids accounts this month?" ## Limits and notes - The tools use your Google accounts and the same rules as the REST API, such as `maxJobs`. Video seconds, images, AI avatar videos and Gemini uses (speech) count against the account's monthly Vids allowance, see [Plans and monthly allowances](/docs/api-google-vids-v1#plans-and-monthly-allowances). - A client may send up to 20 JSON-RPC requests in one batch. - If the client sends an `MCP-Protocol-Version` header, it must be one of the supported versions: `2025-06-18`, `2025-03-26` or `2024-11-05`. - Tool calls show in your [usage stats](/docs/account-management/get-account-stats) (`bot=google-vids`) through the REST call each tool makes, the same rows a direct API request writes. === URL: https://useapi.net/docs/api-google-vids-v1/post-google-vids-accounts === Document URL: https://useapi.net/docs/api-google-vids-v1/post-google-vids-accounts --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> accounts description: "Connect a Google AI account to the useapi.net Google Vids API with POST accounts by pasting its docs.google.com cookies, or update its maxJobs by email." parent: Google Vids API nav_order: 100 permalink: /docs/api-google-vids-v1/post-google-vids-accounts --- ## Configure a Google Vids account October 7, 2026 (November 20, 2026) --- Connect a Google account to the API with the cookies of a signed-in [Google Vids](https://docs.google.com/videos) session. The easiest way is the [automated setup](/assets/setup-browser/google-vids.html), which signs in for you and calls this endpoint. See [Setup Google Vids](/docs/start-here/setup-google-vids) for the setup script and the manual cookie copy. The API checks the cookies with Google before saving the account. The account email is read from Google, together with the account's monthly limits and how much of each is left. A free Google account has no Vids video or images (0 seconds of video and 0 images a month). It is accepted and marked `avatarsOnly`: it can make avatars, speech and talking avatar videos, but no clips or images. For clips and images, use an account on a paid [Google AI plan](https://one.google.com/ai). The first time an account is added, the API creates one Google Vids document on it (`vidsDocId`). Every generation names that document, and it is where [avatars](/docs/api-google-vids-v1/post-google-vids-avatars) are saved. Generated videos and images are not stored in it. In Google Drive it is named `Vids avatars` (accounts added before November 20, 2026 keep the name Google gave it, such as `Untitled video`). Moving that document to the Google Drive trash does no harm: it keeps working, avatars included. If it is deleted for good, the API creates a new, empty document the next time it needs one and carries on, so the account does not need to be re-added. Avatars saved in the deleted document are gone with it. Posting cookies for an account that is already connected re-adds it: the cookies are replaced, and `added`, `maxJobs` and the Vids document are kept unless you send a new `maxJobs`. Re-adding is also how an account that Google signed out is brought back, and it clears `exhaustedUntil`, so the account takes video and image jobs again. After the account is added, do not open that Google account in a browser again. Google Vids needs the `__Secure-1PSIDTS` cookie on every call, and a browser using the same sign-in renews it, which ends the copy the API holds within minutes. This endpoint does two things. To add or re-add an account, post its `cookies`. To change only `maxJobs` on an account that is already connected, post `email` and `maxJobs` and leave `cookies` out: nothing is sent to Google then. Each [useapi.net subscription](/docs/subscription) lets you connect 3 Google accounts, up to 100 in total. > **https://api.useapi.net/v1/google-vids/accounts** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body Add or re-add an account: ```json { "cookies": "SID\tg.a000…\t.google.com\t/\t2027-11-01T00:00:00.000Z\t…\nOSID\tg.a000…\tdocs.google.com\t/\t…", "maxJobs": 3 } ``` - `cookies` is **required** to add or re-add an account. Copy the cookie table of `https://docs.google.com` from DevTools as described in [Setup Google Vids](/docs/start-here/setup-google-vids#manual-setup) and paste it exactly as copied. The paste must contain `SID`, `HSID`, `SSID`, `APISID`, `SAPISID` and `__Secure-1PSIDTS` for `.google.com`, plus `OSID` for `docs.google.com`. A missing cookie returns `400` naming it. Cookies that are not signed in to Google Vids, or that Google refuses for generation, return `400`. Only these seven cookies are stored, and their values are never returned by the API. - `maxJobs` is optional, the number of jobs this account may run at the same time. Range: `1` to `10`. Default: `3` for a new account, the current value on a re-add. Update a connected account: ```json { "email": "user@example.com", "maxJobs": 5 } ``` - `email` is **required** in this mode, the email of a connected account. Do not send it together with `cookies`. - `maxJobs` is **required** in this mode, the new concurrency limit. Range: `1` to `10`. ##### Responses **200** **200 OK** — the account was already connected and has been re-added. ```json { "email": "user@example.com", "maxJobs": 3, "added": "2026-10-06T22:51:03.032Z", "updated": "2026-10-07T01:03:28.469Z", "cookies": [ "SID", "HSID", "SSID", "APISID", "SAPISID", "__Secure-1PSIDTS", "OSID" ], "cookiesExpireAt": "2027-04-05T02:18:00.438Z", "vidsDocId": "13uYNqnKSfoLaWj1GYxZ3Wqe_06hY5k5i0S1_jPCXn2Y", "limits": { "video": 10000, "image": 1000, "music": 300, "speech": 50, "avatarVideo": 10 }, "health": "OK", "quota": { "video": { "limit": 10000, "left": 9936, "resetAt": "2026-11-01T07:00:00.000Z" }, "image": { "limit": 1000, "left": 990, "resetAt": "2026-11-01T07:00:00.000Z" }, "music": { "limit": 300, "left": 298, "resetAt": "2026-11-01T07:00:00.000Z" }, "speech": { "limit": 50, "left": 50, "resetAt": "2026-11-01T07:00:00.000Z" }, "avatarVideo": { "limit": 10, "left": 10, "resetAt": "2026-11-01T07:00:00.000Z" } } } ``` - `limits` are the account's monthly limits: seconds of video, images, songs (music is not used by this API), Gemini uses (`speech`, for [POST /speech](/docs/api-google-vids-v1/post-google-vids-speech) and the speech of each talking avatar video) and AI avatar videos (`avatarVideo`, for [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar)). Jobs without `email` go only to accounts whose limit for that kind of job is above 0. After you change the account's plan, call [GET /accounts/`email`](/docs/api-google-vids-v1/get-google-vids-accounts-email) or add the account again, so the new limits are used. - `avatarsOnly: true` marks an account with 0 video seconds and 0 images, such as a free Google account. It makes no clips or images, but it can make avatars with [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) when you name it with `email`, and speech and talking avatar videos as far as its `speech` and `avatarVideo` limits allow. - `quota` is what the account has left right now. A counter Google did not answer is `null`. [GET /accounts/`email`](/docs/api-google-vids-v1/get-google-vids-accounts-email) reads it live at any time. - An update (`email` + `maxJobs`) returns the same record without `quota`. **201** **201 Created** — a new account was connected. Same body as `200`, without `updated`. **400** **400 Bad Request** — a required cookie is missing, the cookies are not signed in, the account's plan has no Vids allowance, `email` was sent with `cookies`, or a parameter is invalid. ```json { "error": "Missing cookies: __Secure-1PSIDTS. Copy them from docs.google.com/videos (DevTools → Application → Cookies).", "code": 400 } ``` ```json { "error": "These cookies are not signed in to Google Vids (HTTP 302 → sign-in). Sign in at https://docs.google.com/videos and copy the cookies again.", "code": 400 } ``` ```json { "error": "Google refused these cookies for Vids generation (401). Copy them again from docs.google.com/videos.", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **402** **402 Payment Required** — the subscription has expired, or a new account needs another [subscription](/docs/subscription). ```json { "error": "useapi.net ⁝ You have 1 subscription, you need 1 additional subscription (2 total) to support 4 accounts for the google_vids API. Upgrade at https://useapi.net/docs/subscription", "code": 402 } ``` **404** **404 Not Found** — update mode: no account is connected for this `email`. ```json { "error": "Account user@example.com not found", "code": 404 } ``` **502** **502 Bad Gateway** — the cookies are signed in, but Google's Vids page did not give the API what it needs, or the Vids document could not be created. Nothing was saved. Retry the same request. ```json { "error": "Could not create the Vids document for this account — please retry", "code": 502 } ``` ##### Model `200` and `201` return the same account record. <details markdown="block" class="model-details"> <summary>The account record, field by field</summary> ```typescript { // TypeScript, all fields are optional email: string maxJobs: number // jobs this account may run at the same time added: string // ISO 8601, when the account was first connected updated?: string // ISO 8601, the last re-add or maxJobs change cookies: string[] // names of the stored cookies, never their values cookiesExpireAt?: string | null // ISO 8601, the earliest expiry date in the pasted cookies vidsDocId: string // the Google Vids document the API created on the account limits: { // monthly limits, read from Google on add and kept current by GET /accounts/{email} video: number | null // seconds of video image: number | null // images music: number | null // songs (not used by this API) speech?: number | null // Gemini uses: POST /speech, and the speech of each talking avatar video avatarVideo?: number | null // AI avatar videos (POST /videos/avatar) } avatarsOnly?: true // 0 video and 0 images (e.g. a free Google account): no clips or images, only avatars, speech and avatar videos health: string // 'OK', 'verifying', or the reason the account must be re-added exhaustedUntil?: { // job types this account sits out, only while in force (a re-add clears it) video?: string // ISO 8601, Google's reset time for the used-up video seconds image?: string // ISO 8601, Google's reset time for the used-up images speech?: string // ISO 8601, Google's reset time for the used-up Gemini uses avatarVideo?: string // ISO 8601, Google's reset time for the used-up AI avatar videos } addedVia?: 'setup-browser' // present when the account was added by the automated setup quota?: { // add and re-add only: what is left right now, null when a counter did not answer video: { limit: number, left: number, resetAt: string } | null // seconds of video image: { limit: number, left: number, resetAt: string } | null // images music: { limit: number, left: number, resetAt: string } | null // songs (not used by this API) speech: { limit: number, left: number, resetAt: string } | null // Gemini uses: POST /speech and the speech of each avatar video avatarVideo: { limit: number, left: number, resetAt: string } | null // AI avatar videos (POST /videos/avatar) } } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/google-vids/accounts" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "email": "user@example.com", "maxJobs": 5 }' ``` **JavaScript** ``` javascript const token = "API token"; const cookies = "Cookie table of https://docs.google.com copied from DevTools"; const apiUrl = "https://api.useapi.net/v1/google-vids/accounts"; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ cookies, maxJobs: 3 }) }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" cookies = "Cookie table of https://docs.google.com copied from DevTools" apiUrl = "https://api.useapi.net/v1/google-vids/accounts" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } data = { "cookies": cookies, "maxJobs": 3 } response = requests.post(apiUrl, headers=headers, json=data) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-google-vids-v1/post-google-vids-assets === Document URL: https://useapi.net/docs/api-google-vids-v1/post-google-vids-assets --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> assets description: "Upload a JPEG, PNG, WebP or MP4 of up to 50 MB via POST assets in the useapi.net Google Vids API: an assetId for a start image, reference, avatar photo or logo." parent: Google Vids API nav_order: 400 permalink: /docs/api-google-vids-v1/post-google-vids-assets --- ## Upload an asset October 7, 2026 (November 16, 2026) --- Upload an image or a video to one of your accounts and get an `assetId` for it. The file is sent as the raw request body with its MIME type in the `Content-Type` header (no multipart, no JSON). Where an `assetId` goes: - An image is a `startImage` or a `referenceImage_1`..`referenceImage_3` of [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos). An image made with [POST /images](/docs/api-google-vids-v1/post-google-vids-images) needs no upload: pass its `mediaId` there directly. - Uploaded videos cannot be edited: Google refuses every edit of an uploaded video. To edit a clip, pass the `mediaId` of a clip made with this API to [POST /videos/edit](/docs/api-google-vids-v1/post-google-vids-videos-edit). - An image is also a person's photo to start an avatar from (`image`), or a logo to place on an avatar's clothes (`logo`), in [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars). The `assetId` names the account the file was uploaded to, and only jobs on that account can use it. To use several uploads in one video or avatar, upload them all to the same account with `email`. An upload takes no `maxJobs` slot, uses no allowance, and works even on an account whose allowance is used up for the month. Uploads are temporary like every Vids file, so upload an input shortly before the job that uses it. See [How long files last](/docs/api-google-vids-v1/get-google-vids-media-mediaId#how-long-files-last). > **https://api.useapi.net/v1/google-vids/assets?email=`email`** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: image/jpeg # image/jpeg, image/png, image/webp or video/mp4 ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. - `Content-Type` is **required**, the file's MIME type. Supported values: `image/jpeg`, `image/png`, `image/webp`, `video/mp4`. The request body is the file's raw bytes, from 1 byte to `50 MB`. ##### Query Parameters - `email` is optional, the account to upload to, used as given whatever its plan (a free account included, for an avatar photo or logo). When omitted, a healthy account with a video allowance is picked at random, preferring one whose video seconds are not used up this month. URL-encode it. ##### Responses **200** **200 OK** ```json { "assetId": "user:12345-user@example.com-asset:AYGXpjjhK1XnT8IYzCoB9dCO4XxlyHvHv54IZep9pWDRq7fNu8bo7WF-qhIC6OzxYEVNrPLOm1e5x9BrxROKgHRUCIeFWQ_r1tRbzBHTMGfER_jmittzbVWQfvZjzrU2Qv4CyCZtaeJMoqfkPWgZMA5QmCoS8zRLIeapAuj5lYbhjWQgIfRrmdA", "email": "user@example.com", "type": "image/jpeg", "bytes": 113184 } ``` **400** **400 Bad Request** — an unsupported `Content-Type`, an empty body, or a file over 50 MB. ```json { "error": "Content-Type must be one of image/jpeg, image/png, image/webp, video/mp4 (raw file bytes in the body)", "code": 400 } ``` ```json { "error": "File must be 1 byte to 50 MB", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **404** **404 Not Found** — the account named by `email` is not connected. ```json { "error": "Account user@example.com is not configured", "code": 404 } ``` **503** **503 Service Unavailable** — Google did not accept the upload. Retry shortly. ```json { "error": "Google error: Upload failed (HTTP 500)", "code": 503 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Google Vids](/docs/start-here/setup-google-vids). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-google-vids", "code": 596 } ``` ##### Model The new `assetId`, the account the file was uploaded to, its `Content-Type` and its size in bytes. <details markdown="block" class="model-details"> <summary>The uploaded file, field by field</summary> ```typescript { // TypeScript, all fields are optional assetId: string // user:<id>-<email>-asset:<Google upload id>, pass it as startImage, referenceImage_N or video, or as image or logo of POST /avatars email: string // the account the file was uploaded to type: string // the Content-Type you sent bytes: number // the file size error?: string // errors only code?: number // errors only } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/google-vids/assets?email=user%40example.com" \ -H "Authorization: Bearer …" \ -H "Content-Type: image/jpeg" \ --data-binary @dog.jpg ``` **JavaScript** ``` javascript import fs from "fs"; const token = "API token"; const email = "Previously configured account email"; const apiUrl = `https://api.useapi.net/v1/google-vids/assets?email=${encodeURIComponent(email)}`; const response = await fetch(apiUrl, { method: "POST", headers: { "Authorization": `Bearer ${token}`, "Content-Type": "image/jpeg", }, body: fs.readFileSync("dog.jpg") }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured account email" apiUrl = "https://api.useapi.net/v1/google-vids/assets" headers = { "Authorization" : f"Bearer {token}", "Content-Type": "image/jpeg" } with open("dog.jpg", "rb") as f: response = requests.post(apiUrl, headers=headers, params={"email": email}, data=f.read()) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-google-vids-v1/post-google-vids-avatars === Document URL: https://useapi.net/docs/api-google-vids-v1/post-google-vids-avatars --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> avatars description: "Create a voiced avatar via POST avatars in the useapi.net Google Vids API from a description, a photo or another avatar, refined in words or with a logo." parent: Google Vids API nav_order: 600 permalink: /docs/api-google-vids-v1/post-google-vids-avatars --- ## Create an avatar October 7, 2026 (November 16, 2026) --- An avatar is a picture of a person plus a fixed voice. It can: - Read a script as a talking-head video of up to 30 seconds, with [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar). - Act in a scene: pass its `avatarId` as `avatar_1`..`avatar_3` to [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos), and the clip shows that person speaking the lines you write in the prompt, in the avatar's voice. One clip can hold several avatars, for a dialogue. The picture starts from exactly one of three inputs: | Start | Body parameter | What Google does | |---|---|---| | A description | `appearance`, plus optional `outfit`, `shot`, `expression` and `details` | Draws the person. | | A photo or an image | `image`: the `assetId` of a person's photo uploaded with [POST /assets](/docs/api-google-vids-v1/post-google-vids-assets), or the `mediaId` of an image made with [POST /images](/docs/api-google-vids-v1/post-google-vids-images) | A photo is reframed into a 16:9 avatar picture: one person, centred, facing the camera with a smile, keeping their face, clothes and accessories. A photo with no visible face comes back unchanged. An image `mediaId` is used as is. | | Another avatar | `avatar`: an `avatarId` from [GET /avatars](/docs/api-google-vids-v1/get-google-vids-avatars) or an earlier POST /avatars | Uses that avatar's picture, for example to give the same person another name or voice. | Two optional changes then apply to the picture, whatever it started from: - `refine` is a change in words: other clothes, a new background, a hairstyle, glasses. - `logo` is an image placed on the clothes like a small pin or patch, on the left chest unless you say where in `refine`. Without `refine` or `logo`, an image `mediaId` or an `avatar` start keeps its picture unchanged. Every call makes a new avatar. The avatar you started from stays as it was. All inputs of one request (`image`, `avatar`, `logo`) must live on the same account, and the new avatar is saved there. Google checks every picture. It refuses photos of prominent people and of minors, and content against its terms, with `422`. The voice is one of the 30 voices listed by [GET /voices](/docs/api-google-vids-v1/get-google-vids-voices), named by its Vids name (`Holt`) or its Google voice id (`Charon`). To hear a voice with your own words first, use [POST /speech](/docs/api-google-vids-v1/post-google-vids-speech). The avatar is saved in the account's Vids document, where [GET /avatars](/docs/api-google-vids-v1/get-google-vids-avatars) lists it and [DELETE /avatars/`avatarId`](/docs/api-google-vids-v1/delete-google-vids-avatars-avatarId) removes it. It can be used only by videos on that account. ### Cost - Each picture Google makes uses 1 image of the account's monthly Vids images: a drawing from a description, a photo reframed, and a change with `refine` and/or `logo` (both together are one change). So a start plus a change uses 2 images. An avatar copied unchanged from `avatar`, or an image `mediaId` used as is, makes no new picture and uses nothing. - On an account with no image allowance, such as a free Google account, avatar pictures still work and cost nothing. Name that account with `email`. Its avatars can talk with [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar) when its plan has AI avatar videos, and their pictures (`previewMediaId`) download like any image. - Voices are free. - A video with an avatar costs its seconds like any other clip, and the avatar takes one of its 3 reference slots. A talking avatar video uses the account's AI avatar videos, see [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar). Creating an avatar takes about 15 to 20 seconds from a description, about 10 to 15 seconds from a photo, and a few seconds from an image `mediaId` or an avatar used as is. A `refine` or a `logo` adds about 15 to 25 seconds, so a start plus a change takes about 30 to 45 seconds. The call answers when the avatar is saved and takes no `maxJobs` slot. > **https://api.useapi.net/v1/google-vids/avatars** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body From a description: ```json { "name": "Marco", "voice": "Holt", "appearance": "a middle-aged man with a short grey beard", "outfit": "navy blazer over a white shirt", "shot": "upper-body", "expression": "a calm, friendly smile", "details": "warm studio lighting", "email": "user@example.com" } ``` From a photo uploaded with [POST /assets](/docs/api-google-vids-v1/post-google-vids-assets), with a change and a logo: ```json { "name": "Dana", "voice": "Kaci", "image": "user:12345-user@example.com-asset:AYGXpjhQ2Lw8…", "refine": "a dark green hoodie, a plain light grey studio background", "logo": "user:12345-user@example.com-asset:AYGXpjgN7cRt…" } ``` From an existing avatar, with a new voice and glasses: ```json { "name": "Marco with glasses", "voice": "Zeno", "avatar": "user:12345-user@example.com-avatar:eyJnIjoiaDMy…", "refine": "round tortoiseshell glasses" } ``` - `name` is **required**, the new avatar's name. It is a label only and plays no part in a video prompt. Length: `1` to `40` characters. - `voice` is **required**, a voice `name` or `voice` id from [GET /voices](/docs/api-google-vids-v1/get-google-vids-voices), case-insensitive. - `appearance`, `image` and `avatar` are the start of the picture. Send exactly one of them. - `appearance` is the person to draw, for example their age, hair and features. Length: `1` to `500` characters. - `outfit`, `shot`, `expression` and `details` describe the drawn picture further. They apply only with `appearance` and are ignored otherwise: to change a photo or an avatar, use `refine`. - `outfit` is what the person wears. Maximum length: `300` characters. - `shot` is the framing. Supported values: `close-up` (head and shoulders), `upper-body` (from the waist up), `full-body` (head to feet). Default: `close-up`. - `expression` is the facial expression. When omitted, Google is asked for a smile with teeth. Maximum length: `200` characters. - `details` is anything else about the picture. Maximum length: `1000` characters. - `image` is the `assetId` of a person's photo uploaded with [POST /assets](/docs/api-google-vids-v1/post-google-vids-assets) (JPEG, PNG or WebP), or the `mediaId` of an image made with [POST /images](/docs/api-google-vids-v1/post-google-vids-images). The `previewMediaId` returned by POST /avatars is an image `mediaId` and works here too. The `previewMediaId` listed by [GET /avatars](/docs/api-google-vids-v1/get-google-vids-avatars) does not: pass that avatar's `avatarId` as `avatar` instead. - `avatar` is an `avatarId` from [GET /avatars](/docs/api-google-vids-v1/get-google-vids-avatars) or POST /avatars, to start from its picture. - `refine` is optional, a change to the picture in words, for example clothes, background, hairstyle or glasses. Length: `1` to `1000` characters. - `logo` is optional, an image to place on the clothes: an `assetId` from [POST /assets](/docs/api-google-vids-v1/post-google-vids-assets) or an image `mediaId` from [POST /images](/docs/api-google-vids-v1/post-google-vids-images). Say where it goes in `refine`, for example `"the logo on the cap"`. - `email` is optional, the account to save the avatar on. With `image`, `avatar` or `logo` it defaults to the account they live on and must match it. With `appearance` alone, a healthy account with an image allowance is picked when it is omitted, preferring one whose images are not used up this month. Name any other account, a free one included, with `email`. ##### Responses **201** **201 Created** From a description: ```json { "avatarId": "user:12345-user@example.com-avatar:eyJnIjoiaDMy…", "name": "Marco", "voice": "Holt", "voiceId": "Charon", "voiceStyle": "Informative", "voicePreview": "https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Charon.wav", "email": "user@example.com", "source": "generated", "previewMediaId": "user:12345-user@example.com-image:eyJ1IjoiaHR0…", "look": { "appearance": "a middle-aged man with a short grey beard", "outfit": "navy blazer over a white shirt", "shot": "upper-body", "expression": "a calm, friendly smile", "details": "warm studio lighting" } } ``` From a photo, with `refine` and `logo`. `previewMediaId` is the new picture: ```json { "avatarId": "user:12345-user@example.com-avatar:eyJnIjoiaDU4…", "name": "Dana", "voice": "Kaci", "voiceId": "Autonoe", "voiceStyle": "Bright", "voicePreview": "https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Autonoe.wav", "email": "user@example.com", "source": "photo", "previewMediaId": "user:12345-user@example.com-image:eyJ1IjoiaHR0…", "refine": "a dark green hoodie, a plain light grey studio background", "logo": "user:12345-user@example.com-asset:AYGXpjgN7cRt…" } ``` From an existing avatar with no change (a copy with another name or voice), there is no new picture, so no `previewMediaId`: ```json { "avatarId": "user:12345-user@example.com-avatar:eyJnIjoiaDMw…", "name": "Marco, firm voice", "voice": "Zeno", "voiceId": "Alnilam", "voiceStyle": "Firm", "voicePreview": "https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Alnilam.wav", "email": "user@example.com", "source": "avatar" } ``` **400** **400 Bad Request** — an unknown voice, none or more than one of `appearance`, `image` and `avatar`, inputs from different accounts, an image Google no longer serves, or an invalid parameter. ```json { "error": "Unknown voice Bob. GET /voices lists them (name or voice id)", "code": 400 } ``` ```json { "error": "Give one of appearance (a description of the person to draw), image (a photo uploaded with POST /assets, or an image mediaId from POST /images) or avatar (an avatarId to start from)", "code": 400 } ``` ```json { "error": "Give only one of appearance, image and avatar", "code": 400 } ``` ```json { "error": "user:12345-another@example.com-asset:AYGXpjgN7cRt… lives on another@example.com, not user@example.com: every input of one avatar must come from the same account", "code": 400 } ``` ```json { "error": "logo: Google answered HTTP 404 for this image (it may have expired). Generate it again or upload it with POST /assets", "code": 400 } ``` ```json { "error": "Parameter name is required", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** — an `image`, `avatar` or `logo` id was issued to a different API token. ```json { "error": "image id does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** — the account named by `email` or by an input id is not connected. ```json { "error": "Account user@example.com is not configured", "code": 404 } ``` **422** **422 Unprocessable Content** — Google refused the picture: a prominent person, a minor, or content against its terms. Nothing is saved. Try another photo or other words. ```json { "error": "Google refused the image: \"The image you provided contains a prominent person, which isn't allowed by our content policies. Try another image.\"", "code": 422 } ``` ```json { "error": "Google refused the image: \"The image you provided contains a minor, which isn't allowed by our content policies. Try another image.\"", "code": 422 } ``` ```json { "error": "Google refused this request (\"That request looks like it goes against our terms. Try asking something else.\")", "code": 422 } ``` **429** **429 Too Many Requests** — Google's own short-term limit on avatar pictures for this account. Retry later, or use another account. ```json { "error": "Google says this account has hit its limit for generating avatar pictures in Vids. Retry later or use another account", "code": 429 } ``` **502** **502 Bad Gateway** — Google did not save the avatar, or answered without a picture. Retry. ```json { "error": "Google did not keep the avatar in the Vids document, please retry", "code": 502 } ``` **503** **503 Service Unavailable** — Google's avatar picture service is failing for now (Google's own editor shows "Something went wrong. Try again."). Nothing was charged. Retry in a few minutes. ```json { "error": "Google's avatar picture service failed (\"Something went wrong. Try again.\", INTERNAL_SERVER_ERROR). Nothing was charged. Retry in a few minutes", "code": 503 } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Google Vids](/docs/start-here/setup-google-vids). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-google-vids", "code": 596 } ``` ##### Model The new avatar's `avatarId`, name, voice and account, the `previewMediaId` of its new picture, and what it was made from. <details markdown="block" class="model-details"> <summary>The new avatar, field by field</summary> ```typescript { // TypeScript, all fields are optional avatarId: string // user:<id>-<email>-avatar:…, for POST /videos/avatar, avatar_1..avatar_3 of POST /videos, or avatar here name: string voice: string // the Vids voice name, e.g. 'Holt' voiceId: string // Google's voice id, e.g. 'Charon' voiceStyle: string // Google's label for the voice, e.g. 'Informative' voicePreview: string // a public English sample of the voice (WAV) email: string // the account the avatar is saved on source: 'generated' | 'photo' | 'image' | 'avatar' // appearance, an uploaded photo, an image mediaId, an avatarId previewMediaId?: string // the new picture (1280x720), download it with GET /media/{mediaId}. Absent when the picture was reused unchanged look?: { // with appearance: the description you sent appearance: string outfit?: string shot: 'close-up' | 'upper-body' | 'full-body' expression?: string details?: string } refine?: string // the change you sent logo?: string // the logo id you sent error?: string // errors only code?: number // errors only } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/google-vids/avatars" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "name": "Marco", "voice": "Holt", "appearance": "a middle-aged man with a short grey beard", "outfit": "navy blazer over a white shirt", "shot": "upper-body" }' # From a photo: upload it to the account first, then pass its assetId as image curl -X POST "https://api.useapi.net/v1/google-vids/assets?email=user%40example.com" \ -H "Content-Type: image/jpeg" \ -H "Authorization: Bearer …" \ --data-binary @dana.jpg curl -X POST "https://api.useapi.net/v1/google-vids/avatars" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "name": "Dana", "voice": "Kaci", "image": "user:12345-user@example.com-asset:AYGXpjhQ2Lw8…", "refine": "a dark green hoodie" }' ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = "https://api.useapi.net/v1/google-vids"; const headers = { "Content-Type": "application/json", "Authorization": `Bearer ${token}` }; const avatar = await (await fetch(`${apiUrl}/avatars`, { method: "POST", headers, body: JSON.stringify({ name: "Marco", voice: "Holt", appearance: "a middle-aged man with a short grey beard", shot: "upper-body" }) })).json(); console.log("avatar", avatar); const job = await (await fetch(`${apiUrl}/videos/avatar`, { method: "POST", headers, body: JSON.stringify({ avatar: avatar.avatarId, script: "Hi, I'm Marco. Welcome to our channel." }) })).json(); console.log("talking video", job.result ?? job.error ?? job); ``` **Python** ``` python import requests token = "API token" apiUrl = "https://api.useapi.net/v1/google-vids" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } data = { "name": "Marco", "voice": "Holt", "appearance": "a middle-aged man with a short grey beard", "shot": "upper-body" } avatar = requests.post(f"{apiUrl}/avatars", headers=headers, json=data).json() print(avatar) ``` === URL: https://useapi.net/docs/api-google-vids-v1/post-google-vids-images === Document URL: https://useapi.net/docs/api-google-vids-v1/post-google-vids-images --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> images description: "Generate a JPEG via POST images in the useapi.net Google Vids API: 16:9, 1:1 or 9:16 at about 1 megapixel in 7 styles, for references and avatars." parent: Google Vids API nav_order: 300 permalink: /docs/api-google-vids-v1/post-google-vids-images --- ## Generate an image October 7, 2026 (November 16, 2026) --- Generate one image from a prompt with the image generator of [Google Vids](https://docs.google.com/videos). Each call returns one JPEG in a fixed size: | `aspectRatio` | Size | |---|---| | `16:9` *(default)* | 1376×768 | | `1:1` | 1024×1024 | | `9:16` | 768×1376 | Vids image generation is basic: one prompt in, one small image out (about 1 megapixel in every style, no larger size or upscale), and it takes no reference images. It works well for quick video references, avatar pictures and storyboards. For anything better, use the [Google Flow API](/docs/api-google-flow-v1/post-google-flow-images): Nano Banana with reference images, at up to 4K. How to use the result: - As an avatar picture: pass its `mediaId` as `image` to [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars). - As a `startImage` or `referenceImage_N` of [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos): pass its `mediaId`. Images carry no visible watermark. ### Cost Each image uses 1 of the account's monthly Vids images, which are counted per account even on a family plan. A request Google refuses uses nothing. See [Plans and monthly allowances](/docs/api-google-vids-v1#plans-and-monthly-allowances). ### Sync, async and webhooks An image normally takes about 10 seconds, and now and then Google takes much longer (in our tests 3 of about 70 images took over 2 minutes). A sync request then answers `202` with the job still running, so nothing is lost: fetch the result with [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid). - Every generation runs as a job on our side, with up to 5 minutes for Google's answer, so a slow answer is never lost. - Sync (the default): the POST waits for the job and answers `200` with the finished job record, or the job's error code. A video usually takes 20 seconds to about 2 minutes (an extend or an edit takes the longest), a talking avatar video 1 to 2.5 minutes, an image about 10 and speech a few. If the job is still running after about 100 seconds, the POST answers `202` with the job as it stands: fetch the result with [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid). Always check `status`: only `completed` has a `result`. - Async: pass `async: true`. The POST answers `202` at once with the job in `status: "processing"`. Poll [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid) or wait for the webhook. - `replyUrl` receives one `POST` of the final job record, as JSON, when the job completes or fails, for sync and async requests alike. It does not make a request async. - Each account runs at most `maxJobs` jobs at a time (default `3`, range `1` to `10`, set with [POST /accounts](/docs/api-google-vids-v1/post-google-vids-accounts)). [GET /jobs](/docs/api-google-vids-v1/get-google-vids-jobs) shows what is running. Job records are kept for 7 days. > **https://api.useapi.net/v1/google-vids/images** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "prompt": "A red vintage bicycle leaning on a sunny brick wall", "aspectRatio": "16:9", "style": "photography", "async": true, "replyUrl": "https://your-domain.com/webhook", "replyRef": "bicycle-1" } ``` - `prompt` is **required**, what the image shows. Maximum length: `5000` characters. - `aspectRatio` is optional. Supported values: `1:1`, `16:9` (default), `9:16`. - `style` is optional, one of the style presets of the Vids image panel. Supported values: `none`, `photography`, `sketch`, `background`, `watercolor`, `vector-art`, `cyberpunk`. Default: `none`. - `email` is optional, the account to run on. When omitted, a healthy account with a free `maxJobs` slot and images left this month is used. - `async` is optional, `true` to answer `202` at once and run the job in the background. Default: `false`. - `replyUrl` is optional, a public `http(s)` URL that receives one `POST` of the job record when the job completes or fails. It works with sync and async requests. Callback body has the same JSON shape as [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid) response. Maximum length: `1024` characters. - `replyRef` is optional, your own reference echoed back in the job record. Maximum length: `1024` characters. ##### Responses **200** **200 OK** — sync mode, the image is ready. ```json { "jobid": "j1007173527443903528i-u12345-email:user@example.com-bot:google-vids", "type": "image", "email": "user@example.com", "status": "completed", "created": "2026-10-07T06:20:21.951Z", "request": { "prompt": "A red vintage bicycle leaning on a sunny brick wall", "style": "photography" }, "updated": "2026-10-07T06:20:32.213Z", "completed": "2026-10-07T06:20:32.213Z", "result": { "mediaId": "user:12345-user@example.com-image:eyJ1IjoiaHR0…", "width": 1376, "height": 768, "model": "/flix/edit_image/v1", "quota": { "image": { "limit": 1000, "left": 945, "resetAt": "2026-11-01T07:00:00.000Z" } }, "elapsedMs": 10204 } } ``` **202** **202 Accepted** — the job is running: with `async: true` at once, in sync mode after about 100 seconds of waiting. Fetch the result with [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid) (or wait for the webhook). ```json { "jobid": "j1007113643796947340i-u12345-email:user@example.com-bot:google-vids", "type": "image", "email": "user@example.com", "status": "processing", "created": "2026-10-07T06:29:29.018Z", "request": { "prompt": "A cup of coffee with latte art, top view", "async": true } } ``` **400** **400 Bad Request** — a parameter is missing or invalid, or Google rejected the request. ```json { "error": "Parameter style (oil-painting) valid values: none,photography,sketch,background,watercolor,vector-art,cyberpunk", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** — the account's Google plan has no Vids image allowance, or the account has [Google Workspace smart features](/docs/start-here/setup-google-vids#turn-on-smart-features) turned off. The body is the failed job record with `error.code: 403`. **404** **404 Not Found** — the account named by `email` is not connected. ```json { "error": "Account user@example.com is not configured", "code": 404 } ``` **422** **422 Unprocessable Content** — Google refused the prompt. Nothing was charged. The body is the failed job record, see [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos). **429** **429 Too Many Requests** — the account is running `maxJobs` jobs, every account is busy, the month's images are used up, or Google is limiting the account for a minute. ```json { "error": "All 2 healthy accounts are running their maximum number of jobs (maxJobs), please retry shortly", "code": 429 } ``` Once Google refuses a job because the account's monthly allowance is used up, the API keeps Google's reset time on the account (`exhaustedUntil` in [GET /accounts](/docs/api-google-vids-v1/get-google-vids-accounts)) and gives it no jobs until then. A request that must run on that account is answered at once with `429`, with no job created and no call to Google. `retryAt` is when to try again. If the account's plan changed, [GET /accounts/`email`](/docs/api-google-vids-v1/get-google-vids-accounts-email) reads its allowance again and lets it take jobs right away. ```json { "error": "Account user@example.com has used up this month's Google Vids allowance. It resets at 2026-11-01T07:00:00.000Z. If its plan changed, call GET /accounts/user@example.com to refresh it", "code": 429, "retryAt": "2026-11-01T07:00:00.000Z" } ``` When nothing ties the request to one account, the job goes to an account with allowance left. When every healthy account has used up its allowance, `retryAt` is the earliest reset time: ```json { "error": "All 3 healthy Google Vids accounts have used up this month's allowance. The first one resets at 2026-11-01T07:00:00.000Z. If a plan changed, call GET /accounts/{email} to refresh it", "code": 429, "retryAt": "2026-11-01T07:00:00.000Z" } ``` A job that Google itself refuses for its allowance (the first refusal, or a job that needs more than the account has left) fails with `error.code` `429`, `error.retryAt` set to the reset time, and `error.quota` with what was left (`limit`, `left`, `resetAt`). An account with some allowance left still takes smaller jobs. **504** **504 Gateway Timeout** — Google did not answer within 5 minutes: run it again. ```json { "jobid": "j1007194433973510548i-u12345-email:user@example.com-bot:google-vids", "type": "image", "email": "user@example.com", "status": "failed", "created": "2026-10-07T05:49:12.411Z", "request": { "prompt": "A red ceramic coffee mug on a plain background" }, "updated": "2026-10-07T05:54:13.469Z", "completed": "2026-10-07T05:54:13.469Z", "error": { "code": 504, "message": "Google did not answer in time (no answer from Google within the proxy's 300 s). Run it again" } } ``` **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Google Vids](/docs/start-here/setup-google-vids). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-google-vids", "code": 596 } ``` Without `email`, the same code means no connected account is healthy and has an image allowance: ```json { "error": "No healthy Google Vids account with an image allowance configured. Check GET /accounts", "code": 596 } ``` ##### Model The job record, `type: "image"`. [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid) and the `replyUrl` webhook return the same shape. An image result has no `duration`, `resolution` or `aspectRatio`. <details markdown="block" class="model-details"> <summary>The image job record, field by field</summary> ```typescript { // TypeScript, all fields are optional jobid: string // j<time><random><v|i|s|a>-u<id>-email:<email>-bot:google-vids type: 'video' | 'image' | 'speech' | 'avatarVideo' mode?: 'text' | 'image' | 'ingredients' | 'extend' | 'upscale' | 'edit' // video jobs only email: string // the account the job runs on status: 'processing' | 'completed' | 'failed' created: string // ISO 8601, when the job was accepted updated?: string // ISO 8601, the last status change completed?: string // ISO 8601, when the job completed or failed request: Record<string, unknown> // your request body as sent (ids as strings) replyUrl?: string replyRef?: string error?: { // status 'failed' code: number // 400 | 403 | 404 | 422 | 429 | 500 | 502 | 503 | 504 | 596, see GET /jobs/{jobid} message: string retryAt?: string // code 429: ISO 8601, when to try again quota?: { // code 429 for allowance: Google's counter for this kind of job when it refused it limit: number // monthly limit (seconds of video, images, Gemini uses or AI avatar videos) left: number // what was left, 0 when used up resetAt: string // ISO 8601, when the allowance resets } } result?: { // status 'completed' mediaId: string // download it with GET /media/{mediaId}. A video: extend / upscale / edit it. An image: use it as startImage, referenceImage_N or avatar image. Speech: a WAV width?: number // video and image height?: number // video and image duration?: number // video: length of the whole clip in whole seconds. Speech: length of the audio in seconds resolution?: '720p' | '1080p' // video aspectRatio?: 'landscape' | 'portrait' // video speechDuration?: number // avatarVideo: length of the spoken script in seconds model: string | null // Google's backend path, e.g. /flix/generate_videos_omni_t2v_psq/v1 quota?: { // what the account has left after this job (absent when Google sends no counter) video?: { limit: number, left: number, resetAt: string } // seconds, video jobs image?: { limit: number, left: number, resetAt: string } // images, image jobs speech?: { limit: number, left: number, resetAt: string } // Gemini uses, speech jobs; absent when Google sends no counter for the account's plan avatarVideo?: { limit: number, left: number, resetAt: string } // AI avatar videos, avatarVideo jobs } elapsedMs: number // how long Google took } } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/google-vids/images" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "prompt": "A small lighthouse on a rocky island at dusk", "aspectRatio": "9:16", "style": "watercolor" }' ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = "https://api.useapi.net/v1/google-vids"; const headers = { "Content-Type": "application/json", "Authorization": `Bearer ${token}` }; const response = await fetch(`${apiUrl}/images`, { method: "POST", headers, body: JSON.stringify({ prompt: "A small lighthouse on a rocky island at dusk", aspectRatio: "9:16", style: "watercolor" }) }); const job = await response.json(); if (job.status === "completed") { const image = await fetch(`${apiUrl}/media/${encodeURIComponent(job.result.mediaId)}`, { headers }); console.log("image bytes", (await image.arrayBuffer()).byteLength); } else console.log("response", response.status, job); ``` **Python** ``` python import requests from urllib.parse import quote token = "API token" apiUrl = "https://api.useapi.net/v1/google-vids" headers = {"Content-Type": "application/json", "Authorization": f"Bearer {token}"} data = {"prompt": "A small lighthouse on a rocky island at dusk", "aspectRatio": "9:16", "style": "watercolor"} job = requests.post(f"{apiUrl}/images", headers=headers, json=data).json() if job.get("status") == "completed": image = requests.get(f"{apiUrl}/media/{quote(job['result']['mediaId'], safe='')}", headers=headers) with open("image.jpg", "wb") as f: f.write(image.content) else: print(job) ``` === URL: https://useapi.net/docs/api-google-vids-v1/post-google-vids-speech === Document URL: https://useapi.net/docs/api-google-vids-v1/post-google-vids-speech --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> speech description: "Turn a script of up to 2,500 characters into a WAV in one of 30 Gemini voices via POST speech in the useapi.net Google Vids API, with audio tags like [whisper]." parent: Google Vids API nav_order: 310 permalink: /docs/api-google-vids-v1/post-google-vids-speech --- ## Turn a script into speech November 4, 2026 (November 16, 2026) --- Turn a script into speech with the Gemini voices of [Google Vids](https://docs.google.com/videos). Each call returns one WAV file (24 kHz, mono) of the script read in one of the 30 voices listed by [GET /voices](/docs/api-google-vids-v1/get-google-vids-voices). Use it to hear how a voice reads your script before you make a [talking avatar video](/docs/api-google-vids-v1/post-google-vids-videos-avatar), or to use the audio anywhere else. Audio tags in square brackets, such as `[whisper]`, `[short pause]` or `[sarcasm]`, are performed, not read aloud: ``` Welcome back. [short pause] Today I have a secret for you. [whisper] Nobody else knows it yet. ``` Download the result with [GET /media/`mediaId`](/docs/api-google-vids-v1/get-google-vids-media-mediaId). Like every Vids file it is temporary, so download it soon, see [How long files last](/docs/api-google-vids-v1/get-google-vids-media-mediaId#how-long-files-last). ### Cost Each script uses 1 of the account's monthly Gemini uses, shown as `speech` in [GET /accounts/`email`](/docs/api-google-vids-v1/get-google-vids-accounts-email). Google lists AI voice-over as unlimited on Google AI Pro and Ultra and as 1 of 50 monthly credits on a free account and on Plus ([Google's limits](https://support.google.com/docs/answer/15609411)), while the API follows the counter Google reports for the account: in our tests (November 2026) an account in an Ultra $199.99 family plan, not the plan owner, had 50 a month. ### Sync, async and webhooks Speech usually takes a few seconds, so the default sync request answers with the finished job. - Every generation runs as a job on our side, with up to 5 minutes for Google's answer, so a slow answer is never lost. - Sync (the default): the POST waits for the job and answers `200` with the finished job record, or the job's error code. A video usually takes 20 seconds to about 2 minutes (an extend or an edit takes the longest), a talking avatar video 1 to 2.5 minutes, an image about 10 and speech a few. If the job is still running after about 100 seconds, the POST answers `202` with the job as it stands: fetch the result with [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid). Always check `status`: only `completed` has a `result`. - Async: pass `async: true`. The POST answers `202` at once with the job in `status: "processing"`. Poll [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid) or wait for the webhook. - `replyUrl` receives one `POST` of the final job record, as JSON, when the job completes or fails, for sync and async requests alike. It does not make a request async. - Each account runs at most `maxJobs` jobs at a time (default `3`, range `1` to `10`, set with [POST /accounts](/docs/api-google-vids-v1/post-google-vids-accounts)). [GET /jobs](/docs/api-google-vids-v1/get-google-vids-jobs) shows what is running. Job records are kept for 7 days. > **https://api.useapi.net/v1/google-vids/speech** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "script": "Welcome back. [short pause] Today I have a secret for you. [whisper] Nobody else knows it yet.", "voice": "Kaci", "async": false, "replyUrl": "https://your-domain.com/webhook", "replyRef": "intro-voice-1" } ``` - `script` is **required**, the text to speak. Audio tags in square brackets are performed, not read. Length: `1` to `2500` characters. - `voice` is **required**, a voice `name` or `voice` id from [GET /voices](/docs/api-google-vids-v1/get-google-vids-voices), case-insensitive. - `email` is optional, the account to run on. When omitted, a healthy account with a free `maxJobs` slot and speech left this month is used. - `async` is optional, `true` to answer `202` at once and run the job in the background. Default: `false`. - `replyUrl` is optional, a public `http(s)` URL that receives one `POST` of the job record when the job completes or fails. It works with sync and async requests. Callback body has the same JSON shape as [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid) response. Maximum length: `1024` characters. - `replyRef` is optional, your own reference echoed back in the job record. Maximum length: `1024` characters. ##### Responses **200** **200 OK** — sync mode, the speech is ready. ```json { "jobid": "j1104183512448203617s-u12345-email:user@example.com-bot:google-vids", "type": "speech", "email": "user@example.com", "status": "completed", "created": "2026-11-04T18:35:12.448Z", "request": { "script": "Welcome back. [short pause] Today I have a secret for you. [whisper] Nobody else knows it yet.", "voice": "Kaci" }, "updated": "2026-11-04T18:35:16.330Z", "completed": "2026-11-04T18:35:16.330Z", "result": { "mediaId": "user:12345-user@example.com-audio:eyJ1IjoiaHR0…", "duration": 6.12, "model": "/flix/generate_text_to_speech/v1", "quota": { "speech": { "limit": 50, "left": 33, "resetAt": "2026-12-01T08:00:00.000Z" } }, "elapsedMs": 3882 } } ``` **202** **202 Accepted** — the job is running: with `async: true` at once, in sync mode after about 100 seconds of waiting. Fetch the result with [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid) (or wait for the webhook). ```json { "jobid": "j1104183702117390245s-u12345-email:user@example.com-bot:google-vids", "type": "speech", "email": "user@example.com", "status": "processing", "created": "2026-11-04T18:37:02.117Z", "request": { "script": "Thanks for watching, see you next week.", "voice": "Holt", "async": true } } ``` **400** **400 Bad Request** — a parameter is missing or invalid, or the voice is unknown. ```json { "error": "Unknown voice Bob. GET /voices lists them (name or voice id)", "code": 400 } ``` ```json { "error": "Parameter script is required", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** — the account's Google plan has no speech allowance, or the account has [Google Workspace smart features](/docs/start-here/setup-google-vids#turn-on-smart-features) turned off. The body is the failed job record with `error.code: 403`. **404** **404 Not Found** — the account named by `email` is not connected. ```json { "error": "Account user@example.com is not configured", "code": 404 } ``` **422** **422 Unprocessable Content** — Google refused the script. Nothing was charged. The body is the failed job record: ```json { "error": { "code": 422, "message": "Google refused this request (\"That request looks like it goes against our terms. Try asking something else.\"). Change the prompt or the inputs and try again." } } ``` The body is the failed job record, shortened here to its `error`. **429** **429 Too Many Requests** — the account is running `maxJobs` jobs, every account is busy, the month's speech is used up, or Google is limiting the account for a while. When Google's speech service itself is failing, it also answers this way: retry in a few minutes. ```json { "error": "All 2 healthy accounts are running their maximum number of jobs (maxJobs), please retry shortly", "code": 429 } ``` Once Google refuses a job because the account's monthly allowance is used up, the API keeps Google's reset time on the account (`exhaustedUntil` in [GET /accounts](/docs/api-google-vids-v1/get-google-vids-accounts)) and gives it no jobs until then. A request that must run on that account is answered at once with `429`, with no job created and no call to Google. `retryAt` is when to try again. If the account's plan changed, [GET /accounts/`email`](/docs/api-google-vids-v1/get-google-vids-accounts-email) reads its allowance again and lets it take jobs right away. ```json { "error": "Account user@example.com has used up this month's Google Vids allowance. It resets at 2026-11-01T07:00:00.000Z. If its plan changed, call GET /accounts/user@example.com to refresh it", "code": 429, "retryAt": "2026-11-01T07:00:00.000Z" } ``` When nothing ties the request to one account, the job goes to an account with allowance left. When every healthy account has used up its allowance, `retryAt` is the earliest reset time: ```json { "error": "All 3 healthy Google Vids accounts have used up this month's allowance. The first one resets at 2026-11-01T07:00:00.000Z. If a plan changed, call GET /accounts/{email} to refresh it", "code": 429, "retryAt": "2026-11-01T07:00:00.000Z" } ``` A job that Google itself refuses for its allowance (the first refusal, or a job that needs more than the account has left) fails with `error.code` `429`, `error.retryAt` set to the reset time, and `error.quota` with what was left (`limit`, `left`, `resetAt`). An account with some allowance left still takes smaller jobs. **503** **503 Service Unavailable** — Google answered with a server error, or the async job could not be queued. Retry shortly. The body is the failed job record. **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Google Vids](/docs/start-here/setup-google-vids). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-google-vids", "code": 596 } ``` Without `email`, the same code means no connected account is healthy and has a speech allowance: ```json { "error": "No healthy Google Vids account with a speech (Gemini) allowance configured. Check GET /accounts", "code": 596 } ``` ##### Model The job record, `type: "speech"`. [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid) and the `replyUrl` webhook return the same shape. A speech result has a `duration` in seconds and no `width`, `height`, `resolution` or `aspectRatio`. <details markdown="block" class="model-details"> <summary>The speech job record, field by field</summary> ```typescript { // TypeScript, all fields are optional jobid: string // j<time><random><v|i|s|a>-u<id>-email:<email>-bot:google-vids type: 'video' | 'image' | 'speech' | 'avatarVideo' mode?: 'text' | 'image' | 'ingredients' | 'extend' | 'upscale' | 'edit' // video jobs only email: string // the account the job runs on status: 'processing' | 'completed' | 'failed' created: string // ISO 8601, when the job was accepted updated?: string // ISO 8601, the last status change completed?: string // ISO 8601, when the job completed or failed request: Record<string, unknown> // your request body as sent (ids as strings) replyUrl?: string replyRef?: string error?: { // status 'failed' code: number // 400 | 403 | 404 | 422 | 429 | 500 | 502 | 503 | 504 | 596, see GET /jobs/{jobid} message: string retryAt?: string // code 429: ISO 8601, when to try again quota?: { // code 429 for allowance: Google's counter for this kind of job when it refused it limit: number // monthly limit (seconds of video, images, Gemini uses or AI avatar videos) left: number // what was left, 0 when used up resetAt: string // ISO 8601, when the allowance resets } } result?: { // status 'completed' mediaId: string // download it with GET /media/{mediaId}. A video: extend / upscale / edit it. An image: use it as startImage, referenceImage_N or avatar image. Speech: a WAV width?: number // video and image height?: number // video and image duration?: number // video: length of the whole clip in whole seconds. Speech: length of the audio in seconds resolution?: '720p' | '1080p' // video aspectRatio?: 'landscape' | 'portrait' // video speechDuration?: number // avatarVideo: length of the spoken script in seconds model: string | null // Google's backend path, e.g. /flix/generate_videos_omni_t2v_psq/v1 quota?: { // what the account has left after this job (absent when Google sends no counter) video?: { limit: number, left: number, resetAt: string } // seconds, video jobs image?: { limit: number, left: number, resetAt: string } // images, image jobs speech?: { limit: number, left: number, resetAt: string } // Gemini uses, speech jobs; absent when Google sends no counter for the account's plan avatarVideo?: { limit: number, left: number, resetAt: string } // AI avatar videos, avatarVideo jobs } elapsedMs: number // how long Google took } } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/google-vids/speech" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "script": "Welcome back. [short pause] Today I have a secret for you. [whisper] Nobody else knows it yet.", "voice": "Kaci" }' ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = "https://api.useapi.net/v1/google-vids"; const headers = { "Content-Type": "application/json", "Authorization": `Bearer ${token}` }; const response = await fetch(`${apiUrl}/speech`, { method: "POST", headers, body: JSON.stringify({ script: "Welcome back. [short pause] Today I have a secret for you.", voice: "Kaci" }) }); const job = await response.json(); if (job.status === "completed") { const audio = await fetch(`${apiUrl}/media/${encodeURIComponent(job.result.mediaId)}`, { headers }); console.log("wav bytes", (await audio.arrayBuffer()).byteLength, "seconds", job.result.duration); } else console.log("response", response.status, job); ``` **Python** ``` python import requests from urllib.parse import quote token = "API token" apiUrl = "https://api.useapi.net/v1/google-vids" headers = {"Content-Type": "application/json", "Authorization": f"Bearer {token}"} data = {"script": "Welcome back. [short pause] Today I have a secret for you.", "voice": "Kaci"} job = requests.post(f"{apiUrl}/speech", headers=headers, json=data).json() if job.get("status") == "completed": audio = requests.get(f"{apiUrl}/media/{quote(job['result']['mediaId'], safe='')}", headers=headers) with open("speech.wav", "wb") as f: f.write(audio.content) else: print(job) ``` === URL: https://useapi.net/docs/api-google-vids-v1/post-google-vids-videos-avatar === Document URL: https://useapi.net/docs/api-google-vids-v1/post-google-vids-videos-avatar --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/avatar description: "Make an avatar read your script in its own voice via POST videos/avatar in the useapi.net Google Vids API: a 720p talking-head MP4 of up to 30 seconds." parent: Google Vids API nav_order: 240 permalink: /docs/api-google-vids-v1/post-google-vids-videos-avatar --- ## Make an avatar talk November 4, 2026 (November 16, 2026) --- Make a talking-head video of one [avatar](/docs/api-google-vids-v1/post-google-vids-avatars): the avatar faces the camera and says your script word for word, in its own voice, with matching lip movement. The video is an MP4 with sound, 1280×720 (landscape only, Google offers no portrait), and as long as the spoken script, up to 30 seconds. How it differs from an avatar in [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos): | | [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar) | [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) with `avatar_1` | |---|---|---| | What you get | A talking head reading your script | A scene with action, where the avatar is a character | | Length | The length of the speech, up to 30 seconds | 3 to 15 seconds | | What the avatar says | Exactly your `script` | The lines you write in the prompt | | Format | 720p landscape | 720p or 1080p, landscape or portrait | | Allowance | 1 AI avatar video (and 1 Gemini use for the speech) | The clip's seconds of video | Audio tags in square brackets, such as `[whisper]`, `[short pause]` or `[sarcasm]`, are performed, not read aloud. To hear how the avatar's voice reads a script before you spend an avatar video, try it with [POST /speech](/docs/api-google-vids-v1/post-google-vids-speech) in the same voice. The video runs on the account that holds the avatar. Its result is a video `mediaId`, which downloads with [GET /media/`mediaId`](/docs/api-google-vids-v1/get-google-vids-media-mediaId) and can be passed to [POST /videos/extend](/docs/api-google-vids-v1/post-google-vids-videos-extend), [POST /videos/upscale](/docs/api-google-vids-v1/post-google-vids-videos-upscale) and [POST /videos/edit](/docs/api-google-vids-v1/post-google-vids-videos-edit) like any other clip. ### Cost - Each video uses 1 AI avatar video from the account's monthly allowance, shown as `avatarVideo` in [GET /accounts/`email`](/docs/api-google-vids-v1/get-google-vids-accounts-email). It does not use the account's video seconds. - The speech is made first and uses 1 of the account's monthly Gemini uses (`speech`), like [POST /speech](/docs/api-google-vids-v1/post-google-vids-speech). - Google checks the video while making it: for safety, and for a picture that looks like a prominent person. This check is stricter than the one for avatar pictures, so an avatar made from a photo of someone who is not famous can still be refused here. When Google refuses, the job fails with `422` and Google still counts the video against the allowance. A script Google refuses before the video starts costs nothing. - A script that runs over 30 seconds when spoken fails with `400` before the video starts. The speech use is spent. ### Sync, async and webhooks Google takes about 1 to 2.5 minutes to make a talking avatar video. A sync request waits about 100 seconds and then answers `202` with the job still running, so plan to fetch the result with [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid) or a `replyUrl` webhook, or pass `async: true`. - Every generation runs as a job on our side, with up to 5 minutes for Google's answer, so a slow answer is never lost. - Sync (the default): the POST waits for the job and answers `200` with the finished job record, or the job's error code. A video usually takes 20 seconds to about 2 minutes (an extend or an edit takes the longest), a talking avatar video 1 to 2.5 minutes, an image about 10 and speech a few. If the job is still running after about 100 seconds, the POST answers `202` with the job as it stands: fetch the result with [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid). Always check `status`: only `completed` has a `result`. - Async: pass `async: true`. The POST answers `202` at once with the job in `status: "processing"`. Poll [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid) or wait for the webhook. - `replyUrl` receives one `POST` of the final job record, as JSON, when the job completes or fails, for sync and async requests alike. It does not make a request async. - Each account runs at most `maxJobs` jobs at a time (default `3`, range `1` to `10`, set with [POST /accounts](/docs/api-google-vids-v1/post-google-vids-accounts)). [GET /jobs](/docs/api-google-vids-v1/get-google-vids-jobs) shows what is running. Job records are kept for 7 days. > **https://api.useapi.net/v1/google-vids/videos/avatar** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "avatar": "user:12345-user@example.com-avatar:eyJnIjoiaDMy…", "script": "Hi there! Thanks for joining us today. Let me show you what we built this week.", "async": true, "replyUrl": "https://your-domain.com/webhook", "replyRef": "weekly-update-1" } ``` - `avatar` is **required**, an `avatarId` from [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) or [GET /avatars](/docs/api-google-vids-v1/get-google-vids-avatars). The video runs on that avatar's account. - `script` is **required**, what the avatar says, written as it should be spoken. Audio tags in square brackets are performed, not read. Spoken, it must fit in 30 seconds: depending on the voice that is about 250 to 400 characters, and `[slow pace]` or pauses make it longer (370 characters with `[slow pace]` ran 33 seconds in a calm voice). Length: `1` to `400` characters. - `async` is optional, `true` to answer `202` at once and run the job in the background. Default: `false`. - `replyUrl` is optional, a public `http(s)` URL that receives one `POST` of the job record when the job completes or fails. It works with sync and async requests. Callback body has the same JSON shape as [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid) response. Maximum length: `1024` characters. - `replyRef` is optional, your own reference echoed back in the job record. Maximum length: `1024` characters. Any other parameter returns `400 Parameter <name> not supported`. ##### Responses **200** **200 OK** — the video is ready. In sync mode this is rare, since most videos take longer than the sync wait. [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid) returns the same record. ```json { "jobid": "j1104215335919482713a-u12345-email:user@example.com-bot:google-vids", "type": "avatarVideo", "email": "user@example.com", "status": "completed", "created": "2026-11-04T21:53:35.919Z", "request": { "avatar": "user:12345-user@example.com-avatar:eyJnIjoiaDMy…", "script": "Hi there! Thanks for joining us today. Let me show you what we built this week.", "async": true }, "updated": "2026-11-04T21:54:34.055Z", "completed": "2026-11-04T21:54:34.055Z", "result": { "mediaId": "user:12345-user@example.com-video:eyJ1IjoiaHR0…", "width": 1280, "height": 720, "duration": 4, "resolution": "720p", "aspectRatio": "landscape", "model": "/flix/generate_avatar_video/v2_conditional", "speechDuration": 4.28, "quota": { "avatarVideo": { "limit": 10, "left": 9, "resetAt": "2026-12-01T08:00:00.000Z" } }, "elapsedMs": 58136 } } ``` **202** **202 Accepted** — the job is running: with `async: true` at once, in sync mode after about 100 seconds of waiting. Fetch the result with [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid) (or wait for the webhook). ```json { "jobid": "j1104215335919482713a-u12345-email:user@example.com-bot:google-vids", "type": "avatarVideo", "email": "user@example.com", "status": "processing", "created": "2026-11-04T21:53:35.919Z", "request": { "avatar": "user:12345-user@example.com-avatar:eyJnIjoiaDMy…", "script": "Hi there! Thanks for joining us today. Let me show you what we built this week.", "async": true } } ``` **400** **400 Bad Request** — a parameter is missing or invalid, the avatar uses an older voice, the avatar's account has no AI avatar videos on its plan (a monthly limit of 0), or the spoken script is longer than 30 seconds (the failed job record). ```json { "error": "Parameter script length exceeds 400 characters", "code": 400 } ``` An avatar made in the Vids web app with one of Google's older narrator voices cannot talk through the API. Make a new avatar with [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars), for example from this one with `avatar`. ```json { "error": "This avatar uses an older Vids narrator voice that the API cannot send. Make a new avatar with POST /avatars", "code": 400 } ``` A script that runs past 30 seconds when spoken: ```json { "error": { "code": 400, "message": "The script runs 34.2 seconds when spoken in this voice. An avatar video takes up to 30 seconds of speech (Google's limit): shorten the script" } } ``` The body is the failed job record, shortened here to its `error`. **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** — the `avatarId` was issued to a different API token, Google answered that the account's plan has no AI avatar videos, or the account has [Google Workspace smart features](/docs/start-here/setup-google-vids#turn-on-smart-features) turned off (the failed job record, `error.code: 403`). ```json { "error": "avatar id does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** — the account that holds the avatar is not connected. ```json { "error": "Account user@example.com (from the avatar id) is not configured", "code": 404 } ``` **422** **422 Unprocessable Content** — Google refused the script, or refused the video while making it (its safety check, or an avatar picture that looks like a prominent person). A refused script costs nothing. A refused video still counts against the account's AI avatar videos. Change the script or use another avatar and try again. ```json { "error": { "code": 422, "message": "Google's safety check refused the finished avatar video (FINISH_REASON_GENERATED_VIDEO_SAFETY). Google still counts it against the account's monthly AI avatar allowance. Change the script or the avatar and try again" } } ``` An avatar picture Google takes for a prominent person: ```json { "error": { "code": 422, "message": "Google refused to animate this avatar: its picture looks like a prominent person (FINISH_REASON_INPUT_IMAGE_CELEBRITY). Google still counts it against the account's monthly AI avatar allowance. Use an avatar of someone else" } } ``` The body is the failed job record, shortened here to its `error`. **429** **429 Too Many Requests** — the account is running `maxJobs` jobs, its AI avatar videos or Gemini uses for this month are used up, or Google is limiting the account for a while. ```json { "error": "Account user@example.com is running 3 of 3 jobs (maxJobs). Wait for one to finish, or raise maxJobs with POST /accounts", "code": 429 } ``` Once Google refuses a job because the account's monthly allowance is used up, the API keeps Google's reset time on the account (`exhaustedUntil` in [GET /accounts](/docs/api-google-vids-v1/get-google-vids-accounts)) and gives it no jobs until then. A request that must run on that account is answered at once with `429`, with no job created and no call to Google. `retryAt` is when to try again. If the account's plan changed, [GET /accounts/`email`](/docs/api-google-vids-v1/get-google-vids-accounts-email) reads its allowance again and lets it take jobs right away. ```json { "error": "Account user@example.com has used up this month's Google Vids allowance. It resets at 2026-11-01T07:00:00.000Z. If its plan changed, call GET /accounts/user@example.com to refresh it", "code": 429, "retryAt": "2026-11-01T07:00:00.000Z" } ``` When nothing ties the request to one account, the job goes to an account with allowance left. When every healthy account has used up its allowance, `retryAt` is the earliest reset time: ```json { "error": "All 3 healthy Google Vids accounts have used up this month's allowance. The first one resets at 2026-11-01T07:00:00.000Z. If a plan changed, call GET /accounts/{email} to refresh it", "code": 429, "retryAt": "2026-11-01T07:00:00.000Z" } ``` A job that Google itself refuses for its allowance (the first refusal, or a job that needs more than the account has left) fails with `error.code` `429`, `error.retryAt` set to the reset time, and `error.quota` with what was left (`limit`, `left`, `resetAt`). An account with some allowance left still takes smaller jobs. **502** **502 Bad Gateway** — Google could not make the video and gave another reason, or answered in a way the API could not read. The body is the failed job record, and `error.message` has Google's reason. **503** **503 Service Unavailable** — Google answered with a server error or could not be reached, or the async job could not be queued. Retry shortly. The body is the failed job record. **504** **504 Gateway Timeout** — Google did not finish the video within the job's time budget. It may still count against the account's AI avatar videos: run it again. ```json { "error": { "code": 504, "message": "Google did not finish the avatar video within the job's time budget. It may still count against the account's AI avatar allowance: run it again" } } ``` The body is the failed job record, shortened here to its `error`. **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Google Vids](/docs/start-here/setup-google-vids). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-google-vids", "code": 596 } ``` ##### Model The job record, `type: "avatarVideo"`. [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid) and the `replyUrl` webhook return the same shape. The result's `duration` is the video's length in whole seconds and `speechDuration` the exact length of the spoken script. The codes are listed on [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid#model). <details markdown="block" class="model-details"> <summary>The avatar video job record, field by field</summary> ```typescript { // TypeScript, all fields are optional jobid: string // j<time><random><v|i|s|a>-u<id>-email:<email>-bot:google-vids type: 'video' | 'image' | 'speech' | 'avatarVideo' mode?: 'text' | 'image' | 'ingredients' | 'extend' | 'upscale' | 'edit' // video jobs only email: string // the account the job runs on status: 'processing' | 'completed' | 'failed' created: string // ISO 8601, when the job was accepted updated?: string // ISO 8601, the last status change completed?: string // ISO 8601, when the job completed or failed request: Record<string, unknown> // your request body as sent (ids as strings) replyUrl?: string replyRef?: string error?: { // status 'failed' code: number // 400 | 403 | 404 | 422 | 429 | 500 | 502 | 503 | 504 | 596, see GET /jobs/{jobid} message: string retryAt?: string // code 429: ISO 8601, when to try again quota?: { // code 429 for allowance: Google's counter for this kind of job when it refused it limit: number // monthly limit (seconds of video, images, Gemini uses or AI avatar videos) left: number // what was left, 0 when used up resetAt: string // ISO 8601, when the allowance resets } } result?: { // status 'completed' mediaId: string // download it with GET /media/{mediaId}. A video: extend / upscale / edit it. An image: use it as startImage, referenceImage_N or avatar image. Speech: a WAV width?: number // video and image height?: number // video and image duration?: number // video: length of the whole clip in whole seconds. Speech: length of the audio in seconds resolution?: '720p' | '1080p' // video aspectRatio?: 'landscape' | 'portrait' // video speechDuration?: number // avatarVideo: length of the spoken script in seconds model: string | null // Google's backend path, e.g. /flix/generate_videos_omni_t2v_psq/v1 quota?: { // what the account has left after this job (absent when Google sends no counter) video?: { limit: number, left: number, resetAt: string } // seconds, video jobs image?: { limit: number, left: number, resetAt: string } // images, image jobs speech?: { limit: number, left: number, resetAt: string } // Gemini uses, speech jobs; absent when Google sends no counter for the account's plan avatarVideo?: { limit: number, left: number, resetAt: string } // AI avatar videos, avatarVideo jobs } elapsedMs: number // how long Google took } } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/google-vids/videos/avatar" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "avatar": "user:12345-user@example.com-avatar:eyJnIjoiaDMy…", "script": "Hi there! Thanks for joining us today. Let me show you what we built this week.", "async": true }' ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = "https://api.useapi.net/v1/google-vids"; const headers = { "Content-Type": "application/json", "Authorization": `Bearer ${token}` }; const response = await fetch(`${apiUrl}/videos/avatar`, { method: "POST", headers, body: JSON.stringify({ avatar: "user:12345-user@example.com-avatar:eyJnIjoiaDMy…", script: "Hi there! Thanks for joining us today. Let me show you what we built this week.", async: true }) }); let job = await response.json(); console.log("submitted", response.status, job); while (job.status === "processing") { await new Promise(r => setTimeout(r, 15000)); job = await (await fetch(`${apiUrl}/jobs/${encodeURIComponent(job.jobid)}`, { headers })).json(); console.log(job.status); } if (job.status === "completed") { const video = await fetch(`${apiUrl}/media/${encodeURIComponent(job.result.mediaId)}`, { headers }); console.log("video bytes", (await video.arrayBuffer()).byteLength); } else console.log("error", job.error); ``` **Python** ``` python import time import requests from urllib.parse import quote token = "API token" apiUrl = "https://api.useapi.net/v1/google-vids" headers = {"Content-Type": "application/json", "Authorization": f"Bearer {token}"} data = { "avatar": "user:12345-user@example.com-avatar:eyJnIjoiaDMy…", "script": "Hi there! Thanks for joining us today. Let me show you what we built this week.", "async": True } job = requests.post(f"{apiUrl}/videos/avatar", headers=headers, json=data).json() print("submitted", job) while job.get("status") == "processing": time.sleep(15) job = requests.get(f"{apiUrl}/jobs/{quote(job['jobid'], safe='')}", headers=headers).json() print(job["status"]) if job.get("status") == "completed": video = requests.get(f"{apiUrl}/media/{quote(job['result']['mediaId'], safe='')}", headers=headers) with open("avatar.mp4", "wb") as f: f.write(video.content) else: print("error", job.get("error")) ``` === URL: https://useapi.net/docs/api-google-vids-v1/post-google-vids-videos-edit === Document URL: https://useapi.net/docs/api-google-vids-v1/post-google-vids-videos-edit --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/edit description: "Edit up to 15 seconds of a generated Gemini Omni 1.2 Flash clip by prompt via POST videos/edit in the useapi.net Google Vids API: recolour, add objects or restyle." parent: Google Vids API nav_order: 230 permalink: /docs/api-google-vids-v1/post-google-vids-videos-edit --- ## Edit a video October 7, 2026 (November 16, 2026) --- Change a clip with a prompt, for example "Make the paper boat bright yellow". The result is a new clip with a new `mediaId`, and the job runs on the account that holds the source. Edit works on clips Google made: pass a video `mediaId` from [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos), [POST /videos/extend](/docs/api-google-vids-v1/post-google-vids-videos-extend) or [POST /videos/upscale](/docs/api-google-vids-v1/post-google-vids-videos-upscale). In our tests 7 of 7 edits of generated clips worked, including a colour change, an added object, a restyle, an extended 8-second clip and a `1080p` portrait clip. An edit works on up to 15 seconds of a clip and returns those seconds. In our tests a 15-second clip came back whole, every frame edited, in about 140 seconds, longer than the 100 seconds a sync request waits, so run long edits with `async: true`. On a longer clip it edits the first 15 seconds: a 25-second clip came back as its first 15 seconds, edited. So edit clips of 15 seconds or less. An edit of a `1080p` clip probably goes through the same extra `1080p` pass as an extend (we tested extends): see [720p or 1080p](#720p-or-1080p). The result carries Google's visible Gemini ✦ (see [Watermark](/docs/api-google-vids-v1/post-google-vids-videos#watermark)). Our [watermark remover](https://github.com/useapi/google-vids-api/tree/main/watermark-remover) does not work on edited clips: the model repaints the source's star into the picture, so a faint diamond stays even after the new stamp is removed. The API also accepts an uploaded video, an `assetId` from [POST /assets](/docs/api-google-vids-v1/post-google-vids-assets), but Google refuses those at once with `422`. That happened to every upload we tried, even a clip this API had generated and we uploaded again. A refusal uses nothing. ### 720p or 1080p A `1080p` video is a `720p` draft that Google upscales, and it takes about twice as long to make. An extend at `1080p` processes the whole clip again, the seconds you already had included, and each pass sharpens faces and small details further, until they look plastic ([see the comparison](/blog/261106v#720p-or-1080p-what-a-1080p-extend-does)). At `720p` an extend leaves the earlier seconds as they were. So give a clip one `1080p` pass, at the end: - Make and extend your clips at `720p`, and edit at `720p` too. - Finish a clip of up to 20 seconds with one [upscale](/docs/api-google-vids-v1/post-google-vids-videos-upscale) to `1080p`. - For a clip of 21 to 34 seconds, which upscale doesn't take, set `resolution: "1080p"` on the last extend only. - A single clip you won't extend or edit can be made at `1080p` from the start: it uses the same seconds as `720p`. ### Cost An edit uses at most the seconds it edits from the account's monthly Vids video allowance: in our tests a 15-second edit used 10 seconds. A request Google refuses uses nothing. ### Sync, async and webhooks - Every generation runs as a job on our side, with up to 5 minutes for Google's answer, so a slow answer is never lost. - Sync (the default): the POST waits for the job and answers `200` with the finished job record, or the job's error code. A video usually takes 20 seconds to about 2 minutes (an extend or an edit takes the longest), a talking avatar video 1 to 2.5 minutes, an image about 10 and speech a few. If the job is still running after about 100 seconds, the POST answers `202` with the job as it stands: fetch the result with [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid). Always check `status`: only `completed` has a `result`. - Async: pass `async: true`. The POST answers `202` at once with the job in `status: "processing"`. Poll [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid) or wait for the webhook. - `replyUrl` receives one `POST` of the final job record, as JSON, when the job completes or fails, for sync and async requests alike. It does not make a request async. - Each account runs at most `maxJobs` jobs at a time (default `3`, range `1` to `10`, set with [POST /accounts](/docs/api-google-vids-v1/post-google-vids-accounts)). [GET /jobs](/docs/api-google-vids-v1/get-google-vids-jobs) shows what is running. Job records are kept for 7 days. > **https://api.useapi.net/v1/google-vids/videos/edit** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "video": "user:12345-user@example.com-video:eyJ1IjoiaHR0…", "prompt": "Make the paper boat bright yellow", "async": true, "replyUrl": "https://your-domain.com/webhook", "replyRef": "boat-yellow" } ``` - `video` is **required**, the video `mediaId` of the clip to edit, from a finished job's `result`. An `assetId` of an uploaded MP4 is accepted, but Google refuses it. - `prompt` is **required**, the change to make. Maximum length: `5000` characters. - `duration` is optional for a `mediaId`, where it defaults to the clip's length up to 15 seconds and may not be longer than the clip, and **required** for an `assetId`, where it is the uploaded video's length in seconds. Range: `3` to `15`. - `aspectRatio` is optional. Supported values: `landscape`, `portrait`. Default: the source clip's (`landscape` for an `assetId`). - `resolution` is optional. Supported values: `720p`, `1080p`. Default: the source clip's (`720p` for an `assetId`). - `async` is optional, `true` to answer `202` at once and run the job in the background. Default: `false`. - `replyUrl` is optional, a public `http(s)` URL that receives one `POST` of the job record when the job completes or fails. It works with sync and async requests. Callback body has the same JSON shape as [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid) response. Maximum length: `1024` characters. - `replyRef` is optional, your own reference echoed back in the job record. Maximum length: `1024` characters. ##### Responses **200** **200 OK** — sync mode, a 3-second clip edited, charged 3 seconds. ```json { "jobid": "j1007134950991174444v-u12345-email:user@example.com-bot:google-vids", "type": "video", "mode": "edit", "email": "user@example.com", "status": "completed", "created": "2026-10-07T06:28:21.680Z", "request": { "video": "user:12345-user@example.com-video:eyJ1IjoiaHR0…", "prompt": "Make the paper boat bright yellow" }, "updated": "2026-10-07T06:28:59.896Z", "completed": "2026-10-07T06:28:59.896Z", "result": { "mediaId": "user:12345-user@example.com-video:eyJ1IjoiaHR0…", "width": 1280, "height": 720, "duration": 3, "resolution": "720p", "aspectRatio": "landscape", "model": "/flix/generate_videos_omni_edit_psq/v1", "quota": { "video": { "limit": 10000, "left": 9621, "resetAt": "2026-11-01T07:00:00.000Z" } }, "elapsedMs": 38167 } } ``` **202** **202 Accepted** — the job is running: with `async: true` at once, in sync mode after about 100 seconds of waiting. Fetch the result with [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid) (or wait for the webhook). **400** **400 Bad Request** — a parameter is missing or invalid, or `duration` is longer than the clip. ```json { "error": "duration (the uploaded video's length in seconds, 3–15) is required when video is an asset id", "code": 400 } ``` ```json { "error": "Parameter video is not a valid video / asset id", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** — the `video` id was issued to a different API token, or the account has [Google Workspace smart features](/docs/start-here/setup-google-vids#turn-on-smart-features) turned off. ```json { "error": "video id does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** — the account that holds the source is no longer connected. ```json { "error": "Account user@example.com (from the video id) is not configured", "code": 404 } ``` **422** **422 Unprocessable Content** — Google refused the edit. Every uploaded video gets this answer. Nothing was charged. ```json { "jobid": "j1007123831345945676v-u12345-email:user@example.com-bot:google-vids", "type": "video", "mode": "edit", "email": "user@example.com", "status": "failed", "created": "2026-10-07T06:36:31.478Z", "request": { "video": "user:12345-user@example.com-asset:AYGXpjh2dWHI…", "duration": 4, "prompt": "Make the sky stormy and dark" }, "updated": "2026-10-07T06:36:41.176Z", "completed": "2026-10-07T06:36:41.176Z", "error": { "code": 422, "message": "Google refused this request (\"That request looks like it goes against our terms. Try asking something else.\"). Change the prompt or the inputs and try again." } } ``` **429** **429 Too Many Requests** — the account is running `maxJobs` jobs, the month's video allowance is used up, or Google is limiting the account for a minute. ```json { "error": "Account user@example.com is running 3 of 3 jobs (maxJobs). Wait for one to finish, or raise maxJobs with POST /accounts", "code": 429 } ``` Once Google refuses a job because the account's monthly allowance is used up, the API keeps Google's reset time on the account (`exhaustedUntil` in [GET /accounts](/docs/api-google-vids-v1/get-google-vids-accounts)) and gives it no jobs until then. A request that must run on that account is answered at once with `429`, with no job created and no call to Google. `retryAt` is when to try again. If the account's plan changed, [GET /accounts/`email`](/docs/api-google-vids-v1/get-google-vids-accounts-email) reads its allowance again and lets it take jobs right away. ```json { "error": "Account user@example.com has used up this month's Google Vids allowance. It resets at 2026-11-01T07:00:00.000Z. If its plan changed, call GET /accounts/user@example.com to refresh it", "code": 429, "retryAt": "2026-11-01T07:00:00.000Z" } ``` When nothing ties the request to one account, the job goes to an account with allowance left. When every healthy account has used up its allowance, `retryAt` is the earliest reset time: ```json { "error": "All 3 healthy Google Vids accounts have used up this month's allowance. The first one resets at 2026-11-01T07:00:00.000Z. If a plan changed, call GET /accounts/{email} to refresh it", "code": 429, "retryAt": "2026-11-01T07:00:00.000Z" } ``` A job that Google itself refuses for its allowance (the first refusal, or a job that needs more than the account has left) fails with `error.code` `429`, `error.retryAt` set to the reset time, and `error.quota` with what was left (`limit`, `left`, `resetAt`). An account with some allowance left still takes smaller jobs. **504** **504 Gateway Timeout** — Google did not answer within 5 minutes: run it again. **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Google Vids](/docs/start-here/setup-google-vids). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-google-vids", "code": 596 } ``` ##### Model The job record, `mode: "edit"`. [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid) and the `replyUrl` webhook return the same shape. <details markdown="block" class="model-details"> <summary>The video job record, field by field</summary> ```typescript { // TypeScript, all fields are optional jobid: string // j<time><random><v|i|s|a>-u<id>-email:<email>-bot:google-vids type: 'video' | 'image' | 'speech' | 'avatarVideo' mode?: 'text' | 'image' | 'ingredients' | 'extend' | 'upscale' | 'edit' // video jobs only email: string // the account the job runs on status: 'processing' | 'completed' | 'failed' created: string // ISO 8601, when the job was accepted updated?: string // ISO 8601, the last status change completed?: string // ISO 8601, when the job completed or failed request: Record<string, unknown> // your request body as sent (ids as strings) replyUrl?: string replyRef?: string error?: { // status 'failed' code: number // 400 | 403 | 404 | 422 | 429 | 500 | 502 | 503 | 504 | 596, see GET /jobs/{jobid} message: string retryAt?: string // code 429: ISO 8601, when to try again quota?: { // code 429 for allowance: Google's counter for this kind of job when it refused it limit: number // monthly limit (seconds of video, images, Gemini uses or AI avatar videos) left: number // what was left, 0 when used up resetAt: string // ISO 8601, when the allowance resets } } result?: { // status 'completed' mediaId: string // download it with GET /media/{mediaId}. A video: extend / upscale / edit it. An image: use it as startImage, referenceImage_N or avatar image. Speech: a WAV width?: number // video and image height?: number // video and image duration?: number // video: length of the whole clip in whole seconds. Speech: length of the audio in seconds resolution?: '720p' | '1080p' // video aspectRatio?: 'landscape' | 'portrait' // video speechDuration?: number // avatarVideo: length of the spoken script in seconds model: string | null // Google's backend path, e.g. /flix/generate_videos_omni_t2v_psq/v1 quota?: { // what the account has left after this job (absent when Google sends no counter) video?: { limit: number, left: number, resetAt: string } // seconds, video jobs image?: { limit: number, left: number, resetAt: string } // images, image jobs speech?: { limit: number, left: number, resetAt: string } // Gemini uses, speech jobs; absent when Google sends no counter for the account's plan avatarVideo?: { limit: number, left: number, resetAt: string } // AI avatar videos, avatarVideo jobs } elapsedMs: number // how long Google took } } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/google-vids/videos/edit" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "video": "user:12345-user@example.com-video:eyJ1IjoiaHR0…", "prompt": "Make the paper boat bright yellow" }' ``` **JavaScript** ``` javascript const token = "API token"; const video = "mediaId of a clip made by this API"; const apiUrl = "https://api.useapi.net/v1/google-vids/videos/edit"; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ video, prompt: "Make the paper boat bright yellow" }) }); const job = await response.json(); console.log("response", response.status, job.result ?? job.error ?? job); ``` **Python** ``` python import requests token = "API token" video = "mediaId of a clip made by this API" apiUrl = "https://api.useapi.net/v1/google-vids/videos/edit" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } data = { "video": video, "prompt": "Make the paper boat bright yellow" } response = requests.post(apiUrl, headers=headers, json=data) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-google-vids-v1/post-google-vids-videos-extend === Document URL: https://useapi.net/docs/api-google-vids-v1/post-google-vids-videos-extend --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/extend description: "Extend a Gemini Omni 1.2 Flash clip by 3 to 10 seconds per call via POST videos/extend in the useapi.net Google Vids API, on clips of up to 24 s (about 34 s at most), in portrait or 1080p if you like." parent: Google Vids API nav_order: 210 permalink: /docs/api-google-vids-v1/post-google-vids-videos-extend --- ## Extend a video October 7, 2026 (November 16, 2026) --- Continue a clip made by this API with 3 to 10 more seconds of Gemini Omni 1.2 Flash video. The `prompt` describes what happens in the new seconds. The result is the whole clip, the source followed by its continuation, with a new `mediaId`. A 3-second clip extended by 3 seconds comes back as one 6-second clip. The source is a video `mediaId` from [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos), an earlier extend, [POST /videos/upscale](/docs/api-google-vids-v1/post-google-vids-videos-upscale) or [POST /videos/edit](/docs/api-google-vids-v1/post-google-vids-videos-edit). The job runs on the account that made it. One clip can be extended several times, each extend branching into its own new clip. An extend may change the shape of the clip. With `aspectRatio` and `resolution` left out, the result keeps the source's. Set them to turn a landscape clip into a portrait one, or a `720p` clip into `1080p`, and the whole returned clip has the new shape. Extending a `1080p` clip works, but each extend processes the whole clip again and over-sharpens the seconds you already had. Work at `720p` and go to `1080p` once, at the end: A `1080p` video is a `720p` draft that Google upscales, and it takes about twice as long to make. An extend at `1080p` processes the whole clip again, the seconds you already had included, and each pass sharpens faces and small details further, until they look plastic ([see the comparison](/blog/261106v#720p-or-1080p-what-a-1080p-extend-does)). At `720p` an extend leaves the earlier seconds as they were. So give a clip one `1080p` pass, at the end: - Make and extend your clips at `720p`, and edit at `720p` too. - Finish a clip of up to 20 seconds with one [upscale](/docs/api-google-vids-v1/post-google-vids-videos-upscale) to `1080p`. - For a clip of 21 to 34 seconds, which upscale doesn't take, set `resolution: "1080p"` on the last extend only. - A single clip you won't extend or edit can be made at `1080p` from the start: it uses the same seconds as `720p`. [Google Flow](/docs/api-google-flow-v1/post-google-flow-videos-extend) extends with Omni 1.2 as well, also by up to 10 seconds per call. The result carries Google's visible Gemini ✦ (see [Watermark](/docs/api-google-vids-v1/post-google-vids-videos#watermark)). Our [watermark remover](https://github.com/useapi/google-vids-api/tree/main/watermark-remover) does not work on extended clips: the model repaints the source's star into the picture, so a faint diamond stays even after the new stamp is removed. ### How long a clip can get Omni 1.2 Flash extends clips of up to 24 seconds, and each step returns the whole clip. In our tests 15 → 20, 15 → 25, 20 → 30, 23 → 28 and 24 → 27 seconds worked, while a 25-second and a 30-second source failed in Google with an internal error and used nothing. So the API refuses a source longer than 24 seconds with `400`, and the longest clip is about 34 seconds (24 + 10). In our tests an extend took about 90 to 127 seconds, more than the 100 seconds a sync request waits, so run extends with `async: true`. ### Cost An extend uses only the seconds it adds, its `duration`, from the account's monthly Vids video allowance, whatever the length of the source. A request Google refuses uses nothing. ### Sync, async and webhooks - Every generation runs as a job on our side, with up to 5 minutes for Google's answer, so a slow answer is never lost. - Sync (the default): the POST waits for the job and answers `200` with the finished job record, or the job's error code. A video usually takes 20 seconds to about 2 minutes (an extend or an edit takes the longest), a talking avatar video 1 to 2.5 minutes, an image about 10 and speech a few. If the job is still running after about 100 seconds, the POST answers `202` with the job as it stands: fetch the result with [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid). Always check `status`: only `completed` has a `result`. - Async: pass `async: true`. The POST answers `202` at once with the job in `status: "processing"`. Poll [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid) or wait for the webhook. - `replyUrl` receives one `POST` of the final job record, as JSON, when the job completes or fails, for sync and async requests alike. It does not make a request async. - Each account runs at most `maxJobs` jobs at a time (default `3`, range `1` to `10`, set with [POST /accounts](/docs/api-google-vids-v1/post-google-vids-accounts)). [GET /jobs](/docs/api-google-vids-v1/get-google-vids-jobs) shows what is running. Job records are kept for 7 days. > **https://api.useapi.net/v1/google-vids/videos/extend** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "mediaId": "user:12345-user@example.com-video:eyJ1IjoiaHR0…", "prompt": "Camera tilts up to the rainy sky", "duration": 3, "aspectRatio": "portrait", "resolution": "1080p", "async": true, "replyUrl": "https://your-domain.com/webhook", "replyRef": "boat-extend-1" } ``` - `mediaId` is **required**, the video `mediaId` of the clip to extend, from a finished job's `result`. The clip may be up to `24` seconds long. - `prompt` is **required**, what happens in the added seconds. Maximum length: `5000` characters. - `duration` is optional, the number of seconds to add. Range: `3` to `10`. Default: `8`. An extend adds up to 10 seconds per call, while a new clip can be 15. Google accepts a longer extend but adds only 10 seconds and charges the full length asked, so the API refuses a `duration` above 10. Extend again to make the clip longer. - `aspectRatio` is optional, the shape of the returned clip. Supported values: `landscape`, `portrait`. Default: the source clip's. - `resolution` is optional, the resolution of the returned clip. Supported values: `720p`, `1080p`. Default: the source clip's. - `async` is optional, `true` to answer `202` at once and run the job in the background. Default: `false`. - `replyUrl` is optional, a public `http(s)` URL that receives one `POST` of the job record when the job completes or fails. It works with sync and async requests. Callback body has the same JSON shape as [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid) response. Maximum length: `1024` characters. - `replyRef` is optional, your own reference echoed back in the job record. Maximum length: `1024` characters. ##### Responses **200** **200 OK** — sync mode. Here a 3-second landscape `720p` clip was extended by 3 seconds into a 6-second portrait `1080p` clip, charged 3 seconds. ```json { "jobid": "j1007132808631117470v-u12345-email:user@example.com-bot:google-vids", "type": "video", "mode": "extend", "email": "user@example.com", "status": "completed", "created": "2026-10-07T06:26:11.800Z", "request": { "mediaId": "user:12345-user@example.com-video:eyJ1IjoiaHR0…", "prompt": "Camera tilts up to the rainy sky", "duration": 3, "aspectRatio": "portrait", "resolution": "1080p" }, "updated": "2026-10-07T06:27:52.191Z", "completed": "2026-10-07T06:27:52.191Z", "result": { "mediaId": "user:12345-user@example.com-video:eyJ1IjoiaHR0…", "width": 1080, "height": 1920, "duration": 6, "resolution": "1080p", "aspectRatio": "portrait", "model": "/flix/generate_videos_omni_extend_psq/v1", "quota": { "video": { "limit": 10000, "left": 9627, "resetAt": "2026-11-01T07:00:00.000Z" } }, "elapsedMs": 100336 } } ``` **202** **202 Accepted** — the job is running: with `async: true` at once, in sync mode after about 100 seconds of waiting. Fetch the result with [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid) (or wait for the webhook). **400** **400 Bad Request** — a parameter is missing or invalid, or Google rejected the request. ```json { "error": "Parameter mediaId is not a valid video id", "code": 400 } ``` ```json { "error": "Parameter duration (15) is more than 10: an extend adds up to 10 seconds per call. Google takes a longer request but adds only 10 seconds and counts the seconds asked for. Extend again to make the clip longer", "code": 400 } ``` ```json { "error": "This clip is 25 seconds long. Google Vids extends clips of up to 24 seconds, so the longest clip is about 34 seconds", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** — the `mediaId` was issued to a different API token, or the account has [Google Workspace smart features](/docs/start-here/setup-google-vids#turn-on-smart-features) turned off. ```json { "error": "video id does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** — the account that made the clip is no longer connected. ```json { "error": "Account user@example.com (from the video id) is not configured", "code": 404 } ``` **422** **422 Unprocessable Content** — Google refused the prompt or the clip. Nothing was charged. The body is the failed job record, see [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos). **429** **429 Too Many Requests** — the account is running `maxJobs` jobs, the month's video allowance is used up, or Google is limiting the account for a minute. ```json { "error": "Account user@example.com is running 3 of 3 jobs (maxJobs). Wait for one to finish, or raise maxJobs with POST /accounts", "code": 429 } ``` Once Google refuses a job because the account's monthly allowance is used up, the API keeps Google's reset time on the account (`exhaustedUntil` in [GET /accounts](/docs/api-google-vids-v1/get-google-vids-accounts)) and gives it no jobs until then. A request that must run on that account is answered at once with `429`, with no job created and no call to Google. `retryAt` is when to try again. If the account's plan changed, [GET /accounts/`email`](/docs/api-google-vids-v1/get-google-vids-accounts-email) reads its allowance again and lets it take jobs right away. ```json { "error": "Account user@example.com has used up this month's Google Vids allowance. It resets at 2026-11-01T07:00:00.000Z. If its plan changed, call GET /accounts/user@example.com to refresh it", "code": 429, "retryAt": "2026-11-01T07:00:00.000Z" } ``` When nothing ties the request to one account, the job goes to an account with allowance left. When every healthy account has used up its allowance, `retryAt` is the earliest reset time: ```json { "error": "All 3 healthy Google Vids accounts have used up this month's allowance. The first one resets at 2026-11-01T07:00:00.000Z. If a plan changed, call GET /accounts/{email} to refresh it", "code": 429, "retryAt": "2026-11-01T07:00:00.000Z" } ``` A job that Google itself refuses for its allowance (the first refusal, or a job that needs more than the account has left) fails with `error.code` `429`, `error.retryAt` set to the reset time, and `error.quota` with what was left (`limit`, `left`, `resetAt`). An account with some allowance left still takes smaller jobs. **503** **503 Service Unavailable** — Google answered with a server error. We saw this once when extending a 40-second clip. Retry, or extend a shorter clip. ```json { "error": { "code": 503, "message": "Google error: Internal error encountered." } } ``` The body is the failed job record, shortened here to its `error`. **504** **504 Gateway Timeout** — Google did not answer within 5 minutes: run it again. ```json { "error": { "code": 504, "message": "Google did not answer in time (no answer from Google within the proxy's 300 s). Run it again" } } ``` The body is the failed job record, shortened here to its `error`. **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Google Vids](/docs/start-here/setup-google-vids). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-google-vids", "code": 596 } ``` ##### Model The job record, `mode: "extend"`. [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid) and the `replyUrl` webhook return the same shape. `result.duration` is the length of the whole returned clip. <details markdown="block" class="model-details"> <summary>The video job record, field by field</summary> ```typescript { // TypeScript, all fields are optional jobid: string // j<time><random><v|i|s|a>-u<id>-email:<email>-bot:google-vids type: 'video' | 'image' | 'speech' | 'avatarVideo' mode?: 'text' | 'image' | 'ingredients' | 'extend' | 'upscale' | 'edit' // video jobs only email: string // the account the job runs on status: 'processing' | 'completed' | 'failed' created: string // ISO 8601, when the job was accepted updated?: string // ISO 8601, the last status change completed?: string // ISO 8601, when the job completed or failed request: Record<string, unknown> // your request body as sent (ids as strings) replyUrl?: string replyRef?: string error?: { // status 'failed' code: number // 400 | 403 | 404 | 422 | 429 | 500 | 502 | 503 | 504 | 596, see GET /jobs/{jobid} message: string retryAt?: string // code 429: ISO 8601, when to try again quota?: { // code 429 for allowance: Google's counter for this kind of job when it refused it limit: number // monthly limit (seconds of video, images, Gemini uses or AI avatar videos) left: number // what was left, 0 when used up resetAt: string // ISO 8601, when the allowance resets } } result?: { // status 'completed' mediaId: string // download it with GET /media/{mediaId}. A video: extend / upscale / edit it. An image: use it as startImage, referenceImage_N or avatar image. Speech: a WAV width?: number // video and image height?: number // video and image duration?: number // video: length of the whole clip in whole seconds. Speech: length of the audio in seconds resolution?: '720p' | '1080p' // video aspectRatio?: 'landscape' | 'portrait' // video speechDuration?: number // avatarVideo: length of the spoken script in seconds model: string | null // Google's backend path, e.g. /flix/generate_videos_omni_t2v_psq/v1 quota?: { // what the account has left after this job (absent when Google sends no counter) video?: { limit: number, left: number, resetAt: string } // seconds, video jobs image?: { limit: number, left: number, resetAt: string } // images, image jobs speech?: { limit: number, left: number, resetAt: string } // Gemini uses, speech jobs; absent when Google sends no counter for the account's plan avatarVideo?: { limit: number, left: number, resetAt: string } // AI avatar videos, avatarVideo jobs } elapsedMs: number // how long Google took } } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/google-vids/videos/extend" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "mediaId": "user:12345-user@example.com-video:eyJ1IjoiaHR0…", "prompt": "The paper boat spins and sails into a puddle", "duration": 10, "async": true }' ``` **JavaScript** ``` javascript const token = "API token"; const mediaId = "mediaId of a clip made by this API"; const apiUrl = "https://api.useapi.net/v1/google-vids"; const headers = { "Content-Type": "application/json", "Authorization": `Bearer ${token}` }; const response = await fetch(`${apiUrl}/videos/extend`, { method: "POST", headers, body: JSON.stringify({ mediaId, prompt: "The paper boat spins and sails into a puddle", duration: 10, async: true }) }); let job = await response.json(); while (job.status === "processing") { await new Promise(r => setTimeout(r, 10000)); job = await (await fetch(`${apiUrl}/jobs/${encodeURIComponent(job.jobid)}`, { headers })).json(); } console.log("job", job.result ?? job.error); ``` **Python** ``` python import time import requests from urllib.parse import quote token = "API token" mediaId = "mediaId of a clip made by this API" apiUrl = "https://api.useapi.net/v1/google-vids" headers = {"Content-Type": "application/json", "Authorization": f"Bearer {token}"} data = {"mediaId": mediaId, "prompt": "The paper boat spins and sails into a puddle", "duration": 10, "async": True} job = requests.post(f"{apiUrl}/videos/extend", headers=headers, json=data).json() while job.get("status") == "processing": time.sleep(10) job = requests.get(f"{apiUrl}/jobs/{quote(job['jobid'], safe='')}", headers=headers).json() print(job.get("result") or job.get("error")) ``` === URL: https://useapi.net/docs/api-google-vids-v1/post-google-vids-videos-upscale === Document URL: https://useapi.net/docs/api-google-vids-v1/post-google-vids-videos-upscale --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/upscale description: "Upscale a 720p Gemini Omni clip to 1080p via POST videos/upscale in the useapi.net Google Vids API. It is charged the clip's seconds a second time." parent: Google Vids API nav_order: 220 permalink: /docs/api-google-vids-v1/post-google-vids-videos-upscale --- ## Upscale a video to 1080p October 7, 2026 (November 16, 2026) --- Turn a `720p` clip made by this API into `1080p`: 1280×720 becomes 1920×1080 and 720×1280 becomes 1080×1920. The clip keeps its length and aspect ratio, and the result has a new `mediaId`. The job runs on the account that made the clip. The source is a video `mediaId` from [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos), [POST /videos/extend](/docs/api-google-vids-v1/post-google-vids-videos-extend) or [POST /videos/edit](/docs/api-google-vids-v1/post-google-vids-videos-edit). A clip that is already `1080p` is refused with `400`. To take the visible Gemini ✦ off the result (see [Watermark](/docs/api-google-vids-v1/post-google-vids-videos#watermark)), use our [watermark remover](https://github.com/useapi/google-vids-api/tree/main/watermark-remover). It works when the source is a clip as made by [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos), not when the source was extended or edited. ### Cost An upscale uses the clip's full length in seconds again from the account's monthly Vids video allowance: upscaling an 8-second clip uses 8 seconds. Upscale works on clips of up to 20 seconds, the same limit as the Vids editor. A 20-second clip came back fine. Our 30-second clip came back with its frames out of order, three times out of three, so the API refuses clips longer than 20 seconds with `400` before anything is charged. For a longer `1080p` clip, make and extend it at `1080p`. Upscale once, at the end: if the finished clip is 20 seconds or less, make, extend and edit it at `720p`, then upscale it. Google's own [Gemini API](https://aistudio.google.com/docs/omni) has no upscale of an existing video: it makes `1080p` and 4K only as the output of a generation or an edit (as of November 2026). In Vids, a clip you know you want at `1080p` is best made at `1080p` with [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos), which uses the same seconds as `720p`. Use this endpoint for a `720p` clip you already have. A `1080p` video is a `720p` draft that Google upscales, and it takes about twice as long to make. An extend at `1080p` processes the whole clip again, the seconds you already had included, and each pass sharpens faces and small details further, until they look plastic ([see the comparison](/blog/261106v#720p-or-1080p-what-a-1080p-extend-does)). At `720p` an extend leaves the earlier seconds as they were. So give a clip one `1080p` pass, at the end: - Make and extend your clips at `720p`, and edit at `720p` too. - Finish a clip of up to 20 seconds with one [upscale](/docs/api-google-vids-v1/post-google-vids-videos-upscale) to `1080p`. - For a clip of 21 to 34 seconds, which upscale doesn't take, set `resolution: "1080p"` on the last extend only. - A single clip you won't extend or edit can be made at `1080p` from the start: it uses the same seconds as `720p`. ### Sync, async and webhooks - Every generation runs as a job on our side, with up to 5 minutes for Google's answer, so a slow answer is never lost. - Sync (the default): the POST waits for the job and answers `200` with the finished job record, or the job's error code. A video usually takes 20 seconds to about 2 minutes (an extend or an edit takes the longest), a talking avatar video 1 to 2.5 minutes, an image about 10 and speech a few. If the job is still running after about 100 seconds, the POST answers `202` with the job as it stands: fetch the result with [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid). Always check `status`: only `completed` has a `result`. - Async: pass `async: true`. The POST answers `202` at once with the job in `status: "processing"`. Poll [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid) or wait for the webhook. - `replyUrl` receives one `POST` of the final job record, as JSON, when the job completes or fails, for sync and async requests alike. It does not make a request async. - Each account runs at most `maxJobs` jobs at a time (default `3`, range `1` to `10`, set with [POST /accounts](/docs/api-google-vids-v1/post-google-vids-accounts)). [GET /jobs](/docs/api-google-vids-v1/get-google-vids-jobs) shows what is running. Job records are kept for 7 days. > **https://api.useapi.net/v1/google-vids/videos/upscale** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "mediaId": "user:12345-user@example.com-video:eyJ1IjoiaHR0…", "async": true, "replyUrl": "https://your-domain.com/webhook", "replyRef": "boat-1080p" } ``` - `mediaId` is **required**, the video `mediaId` of a `720p` clip of up to 20 seconds, from a finished job's `result`. - `async` is optional, `true` to answer `202` at once and run the job in the background. Default: `false`. - `replyUrl` is optional, a public `http(s)` URL that receives one `POST` of the job record when the job completes or fails. It works with sync and async requests. Callback body has the same JSON shape as [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid) response. Maximum length: `1024` characters. - `replyRef` is optional, your own reference echoed back in the job record. Maximum length: `1024` characters. ##### Responses **200** **200 OK** — sync mode, a 3-second `720p` clip upscaled to `1080p`, charged 3 seconds. ```json { "jobid": "j1007101456724115154v-u12345-email:user@example.com-bot:google-vids", "type": "video", "mode": "upscale", "email": "user@example.com", "status": "completed", "created": "2026-10-07T06:27:55.554Z", "request": { "mediaId": "user:12345-user@example.com-video:eyJ1IjoiaHR0…" }, "updated": "2026-10-07T06:28:19.945Z", "completed": "2026-10-07T06:28:19.945Z", "result": { "mediaId": "user:12345-user@example.com-video:eyJ1IjoiaHR0…", "width": 1920, "height": 1080, "duration": 3, "resolution": "1080p", "aspectRatio": "landscape", "model": "/flix/upsample_video/v1", "quota": { "video": { "limit": 10000, "left": 9624, "resetAt": "2026-11-01T07:00:00.000Z" } }, "elapsedMs": 24339 } } ``` **202** **202 Accepted** — the job is running: with `async: true` at once, in sync mode after about 100 seconds of waiting. Fetch the result with [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid) (or wait for the webhook). **400** **400 Bad Request** — `mediaId` is missing or invalid, the clip is already `1080p`, or it is longer than 20 seconds. ```json { "error": "This clip is already 1080p", "code": 400 } ``` ```json { "error": "Parameter mediaId is required", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** — the `mediaId` was issued to a different API token, or the account has [Google Workspace smart features](/docs/start-here/setup-google-vids#turn-on-smart-features) turned off. ```json { "error": "video id does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** — the account that made the clip is no longer connected. ```json { "error": "Account user@example.com (from the video id) is not configured", "code": 404 } ``` **429** **429 Too Many Requests** — the account is running `maxJobs` jobs, the month's video allowance is used up, or Google is limiting the account for a minute. ```json { "error": "Account user@example.com is running 3 of 3 jobs (maxJobs). Wait for one to finish, or raise maxJobs with POST /accounts", "code": 429 } ``` Once Google refuses a job because the account's monthly allowance is used up, the API keeps Google's reset time on the account (`exhaustedUntil` in [GET /accounts](/docs/api-google-vids-v1/get-google-vids-accounts)) and gives it no jobs until then. A request that must run on that account is answered at once with `429`, with no job created and no call to Google. `retryAt` is when to try again. If the account's plan changed, [GET /accounts/`email`](/docs/api-google-vids-v1/get-google-vids-accounts-email) reads its allowance again and lets it take jobs right away. ```json { "error": "Account user@example.com has used up this month's Google Vids allowance. It resets at 2026-11-01T07:00:00.000Z. If its plan changed, call GET /accounts/user@example.com to refresh it", "code": 429, "retryAt": "2026-11-01T07:00:00.000Z" } ``` When nothing ties the request to one account, the job goes to an account with allowance left. When every healthy account has used up its allowance, `retryAt` is the earliest reset time: ```json { "error": "All 3 healthy Google Vids accounts have used up this month's allowance. The first one resets at 2026-11-01T07:00:00.000Z. If a plan changed, call GET /accounts/{email} to refresh it", "code": 429, "retryAt": "2026-11-01T07:00:00.000Z" } ``` A job that Google itself refuses for its allowance (the first refusal, or a job that needs more than the account has left) fails with `error.code` `429`, `error.retryAt` set to the reset time, and `error.quota` with what was left (`limit`, `left`, `resetAt`). An account with some allowance left still takes smaller jobs. **504** **504 Gateway Timeout** — Google did not answer within 5 minutes: run it again. **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Google Vids](/docs/start-here/setup-google-vids). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-google-vids", "code": 596 } ``` ##### Model The job record, `mode: "upscale"`. [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid) and the `replyUrl` webhook return the same shape. <details markdown="block" class="model-details"> <summary>The video job record, field by field</summary> ```typescript { // TypeScript, all fields are optional jobid: string // j<time><random><v|i|s|a>-u<id>-email:<email>-bot:google-vids type: 'video' | 'image' | 'speech' | 'avatarVideo' mode?: 'text' | 'image' | 'ingredients' | 'extend' | 'upscale' | 'edit' // video jobs only email: string // the account the job runs on status: 'processing' | 'completed' | 'failed' created: string // ISO 8601, when the job was accepted updated?: string // ISO 8601, the last status change completed?: string // ISO 8601, when the job completed or failed request: Record<string, unknown> // your request body as sent (ids as strings) replyUrl?: string replyRef?: string error?: { // status 'failed' code: number // 400 | 403 | 404 | 422 | 429 | 500 | 502 | 503 | 504 | 596, see GET /jobs/{jobid} message: string retryAt?: string // code 429: ISO 8601, when to try again quota?: { // code 429 for allowance: Google's counter for this kind of job when it refused it limit: number // monthly limit (seconds of video, images, Gemini uses or AI avatar videos) left: number // what was left, 0 when used up resetAt: string // ISO 8601, when the allowance resets } } result?: { // status 'completed' mediaId: string // download it with GET /media/{mediaId}. A video: extend / upscale / edit it. An image: use it as startImage, referenceImage_N or avatar image. Speech: a WAV width?: number // video and image height?: number // video and image duration?: number // video: length of the whole clip in whole seconds. Speech: length of the audio in seconds resolution?: '720p' | '1080p' // video aspectRatio?: 'landscape' | 'portrait' // video speechDuration?: number // avatarVideo: length of the spoken script in seconds model: string | null // Google's backend path, e.g. /flix/generate_videos_omni_t2v_psq/v1 quota?: { // what the account has left after this job (absent when Google sends no counter) video?: { limit: number, left: number, resetAt: string } // seconds, video jobs image?: { limit: number, left: number, resetAt: string } // images, image jobs speech?: { limit: number, left: number, resetAt: string } // Gemini uses, speech jobs; absent when Google sends no counter for the account's plan avatarVideo?: { limit: number, left: number, resetAt: string } // AI avatar videos, avatarVideo jobs } elapsedMs: number // how long Google took } } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/google-vids/videos/upscale" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "mediaId": "user:12345-user@example.com-video:eyJ1IjoiaHR0…" }' ``` **JavaScript** ``` javascript const token = "API token"; const mediaId = "mediaId of a 720p clip made by this API"; const apiUrl = "https://api.useapi.net/v1/google-vids/videos/upscale"; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ mediaId }) }); const job = await response.json(); console.log("response", response.status, job.result ?? job.error ?? job); ``` **Python** ``` python import requests token = "API token" mediaId = "mediaId of a 720p clip made by this API" apiUrl = "https://api.useapi.net/v1/google-vids/videos/upscale" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.post(apiUrl, headers=headers, json={"mediaId": mediaId}) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-google-vids-v1/post-google-vids-videos === Document URL: https://useapi.net/docs/api-google-vids-v1/post-google-vids-videos --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos description: "Generate 3 to 15 second Gemini Omni 1.2 Flash video via POST videos in the useapi.net Google Vids API from text, a start image or up to 3 image and avatar references." parent: Google Vids API nav_order: 200 permalink: /docs/api-google-vids-v1/post-google-vids-videos --- ## Generate a video October 7, 2026 (November 16, 2026) --- Generate a video clip with Gemini Omni 1.2 Flash in [Google Vids](https://docs.google.com/videos), which the Vids web app shows as "Omni". Clips are 3 to 15 seconds long, at `720p` or `1080p`, landscape or portrait, and come with sound. Characters speak the lines you write in the prompt, and an [avatar](/docs/api-google-vids-v1/post-google-vids-avatars) speaks them in its own voice. For a talking head that reads a script of up to 30 seconds word for word, use [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar) instead. A clip can start from one of three inputs: | `mode` in the job | Inputs | What Google does | |---|---|---| | `text` | `prompt` only | Text to video. | | `image` | `startImage` | The clip opens on that image. | | `ingredients` | `referenceImage_1`..`referenceImage_3` and/or `avatar_1`..`avatar_3` | Up to 3 references in all, images and avatars together. The clip shows the people, objects and places they picture. | `startImage` cannot be combined with references. An image is either an `assetId` from [POST /assets](/docs/api-google-vids-v1/post-google-vids-assets) or the `mediaId` of an image made with [POST /images](/docs/api-google-vids-v1/post-google-vids-images), which the API fetches from Google and uploads for you on that image's account. The job record echoes the id you sent. Avatars come from [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) or [GET /avatars](/docs/api-google-vids-v1/get-google-vids-avatars). All inputs of one request must live on the same account, and the job runs there. The finished clip's `mediaId` downloads it with [GET /media/`mediaId`](/docs/api-google-vids-v1/get-google-vids-media-mediaId) and continues it with [POST /videos/extend](/docs/api-google-vids-v1/post-google-vids-videos-extend), [POST /videos/upscale](/docs/api-google-vids-v1/post-google-vids-videos-upscale) and [POST /videos/edit](/docs/api-google-vids-v1/post-google-vids-videos-edit). ### Cost A clip uses its `duration` in seconds of the account's monthly Vids video allowance, at the same rate for `720p` and `1080p`. An avatar or a reference adds nothing. A request Google refuses uses nothing. See [Plans and monthly allowances](/docs/api-google-vids-v1#plans-and-monthly-allowances). ### Watermark Google states that every Omni clip made in Vids carries an invisible SynthID watermark in its frames. Every MP4 we downloaded also has a visible Gemini ✦ sparkle in the bottom-right corner. Gemini's [media watermark setting](https://support.google.com/gemini/answer/17405358) does not reach Vids: with it switched off, new Vids clips still had the sparkle. The API returns Google's file unchanged. Images have no visible mark. To take the sparkle off a downloaded clip, use the [watermark remover](https://github.com/useapi/google-vids-api/tree/main/watermark-remover) in our GitHub examples: it reverses the blend in all four Vids formats and leaves SynthID untouched. It works on clips as generated and on their upscales, not on extended or edited clips, where the model repaints the star into the picture. ### 720p or 1080p A `1080p` video is a `720p` draft that Google upscales, and it takes about twice as long to make. An extend at `1080p` processes the whole clip again, the seconds you already had included, and each pass sharpens faces and small details further, until they look plastic ([see the comparison](/blog/261106v#720p-or-1080p-what-a-1080p-extend-does)). At `720p` an extend leaves the earlier seconds as they were. So give a clip one `1080p` pass, at the end: - Make and extend your clips at `720p`, and edit at `720p` too. - Finish a clip of up to 20 seconds with one [upscale](/docs/api-google-vids-v1/post-google-vids-videos-upscale) to `1080p`. - For a clip of 21 to 34 seconds, which upscale doesn't take, set `resolution: "1080p"` on the last extend only. - A single clip you won't extend or edit can be made at `1080p` from the start: it uses the same seconds as `720p`. ### Sync, async and webhooks - Every generation runs as a job on our side, with up to 5 minutes for Google's answer, so a slow answer is never lost. - Sync (the default): the POST waits for the job and answers `200` with the finished job record, or the job's error code. A video usually takes 20 seconds to about 2 minutes (an extend or an edit takes the longest), a talking avatar video 1 to 2.5 minutes, an image about 10 and speech a few. If the job is still running after about 100 seconds, the POST answers `202` with the job as it stands: fetch the result with [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid). Always check `status`: only `completed` has a `result`. - Async: pass `async: true`. The POST answers `202` at once with the job in `status: "processing"`. Poll [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid) or wait for the webhook. - `replyUrl` receives one `POST` of the final job record, as JSON, when the job completes or fails, for sync and async requests alike. It does not make a request async. - Each account runs at most `maxJobs` jobs at a time (default `3`, range `1` to `10`, set with [POST /accounts](/docs/api-google-vids-v1/post-google-vids-accounts)). [GET /jobs](/docs/api-google-vids-v1/get-google-vids-jobs) shows what is running. Job records are kept for 7 days. ### Prompt markers You can place `@`-markers inside `prompt` that stand for the reference parameters you send, as in [Google Flow](/docs/api-google-flow-v1/post-google-flow-videos). Markers are case-insensitive and optional. | Marker | Stands for | |---|---| | `@referenceImage_1`..`@referenceImage_3` | the matching `referenceImage_N` body parameter | | `@avatar_1`..`@avatar_3` | the matching `avatar_N` body parameter | Rules: - Each marker needs its body parameter. Otherwise the API returns `400` with `'avatar_2' was not provided in the request body`. - A reference that the prompt does not mention is still used. Google sees it ahead of the prompt text. - The same marker may appear several times in one prompt. - An avatar's name plays no part in the prompt. Two avatars may share a name and still appear in one clip, told apart by `@avatar_1` and `@avatar_2`. - Other strings, such as `@gmail.com` or `@image_1`, stay plain prompt text. Example, two avatars and a reference image: ```json { "prompt": "@avatar_1 and @avatar_2 sit at @referenceImage_1. @avatar_2 says: \"This coffee is perfect.\" @avatar_1 nods and says: \"Told you.\"", "avatar_1": "user:12345-user@example.com-avatar:eyJnIjoiaDMy…", "avatar_2": "user:12345-user@example.com-avatar:eyJnIjoiaDMy…", "referenceImage_1": "user:12345-user@example.com-asset:AYGXpjgATU91…", "duration": 6 } ``` > **https://api.useapi.net/v1/google-vids/videos** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "prompt": "@referenceImage_1 rides in the passenger seat of @referenceImage_2 driving along @referenceImage_3", "referenceImage_1": "user:12345-user@example.com-asset:AYGXpjjhK1Xn…", "referenceImage_2": "user:12345-user@example.com-asset:AYGXpjjOxEMQ…", "referenceImage_3": "user:12345-user@example.com-asset:AYGXpjgP9eeS…", "duration": 4, "aspectRatio": "landscape", "resolution": "720p", "async": true, "replyUrl": "https://your-domain.com/webhook", "replyRef": "car-ride-1" } ``` - `prompt` is **required**, what happens in the clip, including any spoken lines. It may carry `@`-markers, see [Prompt markers](#prompt-markers). Maximum length: `5000` characters. - `duration` is optional, the clip length in seconds. Range: `3` to `15`. Default: `8`. In our tests a 15-second `720p` clip took about 60 seconds. - `aspectRatio` is optional. Supported values: `landscape` (16:9), `portrait` (9:16). Default: `landscape`. - `resolution` is optional. Supported values: `720p` (1280×720 or 720×1280), `1080p` (1920×1080 or 1080×1920). Default: `720p` (recommended). Both cost the same. A `1080p` clip takes about twice as long to generate. If you plan to extend or edit the clip, stay at `720p`: see [720p or 1080p](#720p-or-1080p). - `startImage` is optional, an `assetId` from [POST /assets](/docs/api-google-vids-v1/post-google-vids-assets) or an image `mediaId` from [POST /images](/docs/api-google-vids-v1/post-google-vids-images). The clip opens on this image. Not accepted together with `referenceImage_N` or `avatar_N`. - `referenceImage_1`, `referenceImage_2`, `referenceImage_3` are optional, the people, objects or places to show, each an `assetId` from [POST /assets](/docs/api-google-vids-v1/post-google-vids-assets) or an image `mediaId` from [POST /images](/docs/api-google-vids-v1/post-google-vids-images). - `avatar_1`, `avatar_2`, `avatar_3` are optional, `avatarId`s from [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) or [GET /avatars](/docs/api-google-vids-v1/get-google-vids-avatars). An avatar keeps its look and speaks in its own voice. References and avatars together: at most `3`. - `email` is optional, the account to run on. When omitted, the account that holds the inputs is used, or, for a text-only clip, a healthy account with a free `maxJobs` slot and video seconds left this month. - `async` is optional, `true` to answer `202` at once and run the job in the background. Default: `false`. - `replyUrl` is optional, a public `http(s)` URL that receives one `POST` of the job record when the job completes or fails. It works with sync and async requests. Callback body has the same JSON shape as [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid) response. Maximum length: `1024` characters. - `replyRef` is optional, your own reference echoed back in the job record. Maximum length: `1024` characters. Any other parameter returns `400 Parameter <name> not supported`. ##### Responses **200** **200 OK** — sync mode, the clip is ready. ```json { "jobid": "j1007112632830970253v-u12345-email:user@example.com-bot:google-vids", "type": "video", "mode": "ingredients", "email": "user@example.com", "status": "completed", "created": "2026-10-07T06:24:34.765Z", "request": { "prompt": "@referenceImage_1 rides in the passenger seat of @referenceImage_2 driving along @referenceImage_3", "referenceImage_1": "user:12345-user@example.com-asset:AYGXpjjhK1Xn…", "referenceImage_2": "user:12345-user@example.com-asset:AYGXpjjOxEMQ…", "referenceImage_3": "user:12345-user@example.com-asset:AYGXpjgP9eeS…", "duration": 4 }, "updated": "2026-10-07T06:25:01.482Z", "completed": "2026-10-07T06:25:01.482Z", "result": { "mediaId": "user:12345-user@example.com-video:eyJ1IjoiaHR0…", "width": 1280, "height": 720, "duration": 4, "resolution": "720p", "aspectRatio": "landscape", "model": "/flix/generate_videos_omni_r2v_psq/v1", "quota": { "video": { "limit": 10000, "left": 9636, "resetAt": "2026-11-01T07:00:00.000Z" } }, "elapsedMs": 26664 } } ``` **202** **202 Accepted** — the job is running: with `async: true` at once, in sync mode after about 100 seconds of waiting. Fetch the result with [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid) (or wait for the webhook). ```json { "jobid": "j1007154417508260291v-u12345-email:user@example.com-bot:google-vids", "type": "video", "mode": "text", "email": "user@example.com", "status": "processing", "created": "2026-10-07T06:31:32.041Z", "request": { "prompt": "A snail crawling over a mossy log, macro", "duration": 3, "replyUrl": "https://your-domain.com/webhook", "replyRef": "snail-1" }, "replyUrl": "https://your-domain.com/webhook", "replyRef": "snail-1" } ``` **400** **400 Bad Request** — a parameter is missing or invalid, inputs are combined in a way Vids does not take, or Google rejected the request. A failed sync job answers with its job record, other cases with: ```json { "error": "'referenceImage_2' was not provided in the request body", "code": 400 } ``` ```json { "error": "Use either startImage or referenceImage_1..3 / avatar_1..3, not both", "code": 400 } ``` ```json { "error": "Up to 3 references in all: referenceImage_1..3 and avatar_1..3 together", "code": 400 } ``` ```json { "error": "user:12345-another@example.com-asset:AYGXpjjhK1Xn… lives on another@example.com, not user@example.com: every input of one job must come from the same account", "code": 400 } ``` ```json { "error": "Parameter duration (16) is more than 15", "code": 400 } ``` An image `mediaId` that Google no longer serves: ```json { "error": "referenceImage_1: Google answered HTTP 404 for this image (it may have expired). Generate it again or upload it with POST /assets", "code": 400 } ``` An avatar made in the Vids web app with one of Google's older narrator voices cannot be used here. Make a new avatar with [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars). ```json { "error": "avatar_1 uses an older Vids narrator voice that the API cannot send. Make a new avatar with POST /avatars", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** — an input id was issued to a different API token, the account's Google plan has no Vids video allowance, or the account has [Google Workspace smart features](/docs/start-here/setup-google-vids#turn-on-smart-features) turned off (the failed job record, `error.code: 403`). ```json { "error": "image id does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** — the account named by `email` or by an input id is not connected. ```json { "error": "Account user@example.com is not configured", "code": 404 } ``` **422** **422 Unprocessable Content** — Google refused the prompt or the inputs. Nothing was charged. Change the prompt or the inputs and try again. ```json { "jobid": "j1007123831345945676v-u12345-email:user@example.com-bot:google-vids", "type": "video", "mode": "text", "email": "user@example.com", "status": "failed", "created": "2026-10-07T06:36:31.478Z", "request": { "prompt": "…", "duration": 4 }, "updated": "2026-10-07T06:36:41.176Z", "completed": "2026-10-07T06:36:41.176Z", "error": { "code": 422, "message": "Google refused this request (\"That request looks like it goes against our terms. Try asking something else.\"). Change the prompt or the inputs and try again." } } ``` **429** **429 Too Many Requests** — the account is running `maxJobs` jobs, every account is busy, the month's video allowance is used up, or Google is limiting the account for a minute. ```json { "error": "Account user@example.com is running 3 of 3 jobs (maxJobs). Wait for one to finish, or raise maxJobs with POST /accounts", "code": 429 } ``` Once Google refuses a job because the account's monthly allowance is used up, the API keeps Google's reset time on the account (`exhaustedUntil` in [GET /accounts](/docs/api-google-vids-v1/get-google-vids-accounts)) and gives it no jobs until then. A request that must run on that account is answered at once with `429`, with no job created and no call to Google. `retryAt` is when to try again. If the account's plan changed, [GET /accounts/`email`](/docs/api-google-vids-v1/get-google-vids-accounts-email) reads its allowance again and lets it take jobs right away. ```json { "error": "Account user@example.com has used up this month's Google Vids allowance. It resets at 2026-11-01T07:00:00.000Z. If its plan changed, call GET /accounts/user@example.com to refresh it", "code": 429, "retryAt": "2026-11-01T07:00:00.000Z" } ``` When nothing ties the request to one account, the job goes to an account with allowance left. When every healthy account has used up its allowance, `retryAt` is the earliest reset time: ```json { "error": "All 3 healthy Google Vids accounts have used up this month's allowance. The first one resets at 2026-11-01T07:00:00.000Z. If a plan changed, call GET /accounts/{email} to refresh it", "code": 429, "retryAt": "2026-11-01T07:00:00.000Z" } ``` A job that Google itself refuses for its allowance (the first refusal, or a job that needs more than the account has left) fails with `error.code` `429`, `error.retryAt` set to the reset time, and `error.quota` with what was left (`limit`, `left`, `resetAt`). An account with some allowance left still takes smaller jobs. For example, a job that needed more seconds than the account had left: ```json { "jobid": "j1007174201068993706v-u12345-email:user@example.com-bot:google-vids", "type": "video", "mode": "text", "email": "user@example.com", "status": "failed", "created": "2026-10-07T06:32:10.218Z", "request": { "prompt": "A spinning top on a wooden table", "duration": 10 }, "updated": "2026-10-07T06:32:11.624Z", "completed": "2026-10-07T06:32:11.624Z", "error": { "code": 429, "message": "Account user@example.com has 6 of 10000 left this month in Google Vids, not enough for this request. It resets at 2026-11-01T07:00:00.000Z", "retryAt": "2026-11-01T07:00:00.000Z", "quota": { "limit": 10000, "left": 6, "resetAt": "2026-11-01T07:00:00.000Z" } } } ``` **503** **503 Service Unavailable** — Google answered with a server error, or the async job could not be queued. Retry shortly. ```json { "error": { "code": 503, "message": "Google error: Internal error encountered." } } ``` The body is the failed job record, shortened here to its `error`. **504** **504 Gateway Timeout** — Google did not answer within 5 minutes: run it again. ```json { "error": { "code": 504, "message": "Google did not answer in time (no answer from Google within the proxy's 300 s). Run it again" } } ``` The body is the failed job record, shortened here to its `error`. **596** **596 Account Error** Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via [Setup Google Vids](/docs/start-here/setup-google-vids). ```json { "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.", "code": 596 } ``` ```json { "error": "Account user@example.com: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-google-vids", "code": 596 } ``` Without `email`, the same code means no connected account is healthy and has a video allowance: ```json { "error": "No healthy Google Vids account with a video allowance configured. Check GET /accounts", "code": 596 } ``` ##### Model The job record. [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid) and the `replyUrl` webhook return the same shape. In sync mode a failed job answers with the HTTP status in its `error.code`. The codes are listed on [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid#model). <details markdown="block" class="model-details"> <summary>The video job record, field by field</summary> ```typescript { // TypeScript, all fields are optional jobid: string // j<time><random><v|i|s|a>-u<id>-email:<email>-bot:google-vids type: 'video' | 'image' | 'speech' | 'avatarVideo' mode?: 'text' | 'image' | 'ingredients' | 'extend' | 'upscale' | 'edit' // video jobs only email: string // the account the job runs on status: 'processing' | 'completed' | 'failed' created: string // ISO 8601, when the job was accepted updated?: string // ISO 8601, the last status change completed?: string // ISO 8601, when the job completed or failed request: Record<string, unknown> // your request body as sent (ids as strings) replyUrl?: string replyRef?: string error?: { // status 'failed' code: number // 400 | 403 | 404 | 422 | 429 | 500 | 502 | 503 | 504 | 596, see GET /jobs/{jobid} message: string retryAt?: string // code 429: ISO 8601, when to try again quota?: { // code 429 for allowance: Google's counter for this kind of job when it refused it limit: number // monthly limit (seconds of video, images, Gemini uses or AI avatar videos) left: number // what was left, 0 when used up resetAt: string // ISO 8601, when the allowance resets } } result?: { // status 'completed' mediaId: string // download it with GET /media/{mediaId}. A video: extend / upscale / edit it. An image: use it as startImage, referenceImage_N or avatar image. Speech: a WAV width?: number // video and image height?: number // video and image duration?: number // video: length of the whole clip in whole seconds. Speech: length of the audio in seconds resolution?: '720p' | '1080p' // video aspectRatio?: 'landscape' | 'portrait' // video speechDuration?: number // avatarVideo: length of the spoken script in seconds model: string | null // Google's backend path, e.g. /flix/generate_videos_omni_t2v_psq/v1 quota?: { // what the account has left after this job (absent when Google sends no counter) video?: { limit: number, left: number, resetAt: string } // seconds, video jobs image?: { limit: number, left: number, resetAt: string } // images, image jobs speech?: { limit: number, left: number, resetAt: string } // Gemini uses, speech jobs; absent when Google sends no counter for the account's plan avatarVideo?: { limit: number, left: number, resetAt: string } // AI avatar videos, avatarVideo jobs } elapsedMs: number // how long Google took } } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/google-vids/videos" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "prompt": "A paper boat drifting down a rain gutter, close up", "duration": 6, "resolution": "1080p", "async": true }' ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = "https://api.useapi.net/v1/google-vids"; const headers = { "Content-Type": "application/json", "Authorization": `Bearer ${token}` }; const response = await fetch(`${apiUrl}/videos`, { method: "POST", headers, body: JSON.stringify({ prompt: "A paper boat drifting down a rain gutter, close up", duration: 6, resolution: "1080p", async: true }) }); let job = await response.json(); console.log("submitted", response.status, job); while (job.status === "processing") { await new Promise(r => setTimeout(r, 10000)); job = await (await fetch(`${apiUrl}/jobs/${encodeURIComponent(job.jobid)}`, { headers })).json(); console.log(job.status); } if (job.status === "completed") { const video = await fetch(`${apiUrl}/media/${encodeURIComponent(job.result.mediaId)}`, { headers }); console.log("video bytes", (await video.arrayBuffer()).byteLength); } else console.log("error", job.error); ``` **Python** ``` python import time import requests from urllib.parse import quote token = "API token" apiUrl = "https://api.useapi.net/v1/google-vids" headers = {"Content-Type": "application/json", "Authorization": f"Bearer {token}"} data = { "prompt": "A paper boat drifting down a rain gutter, close up", "duration": 6, "resolution": "1080p", "async": True } response = requests.post(f"{apiUrl}/videos", headers=headers, json=data) job = response.json() print("submitted", response.status_code, job) while job.get("status") == "processing": time.sleep(10) job = requests.get(f"{apiUrl}/jobs/{quote(job['jobid'], safe='')}", headers=headers).json() print(job["status"]) if job.get("status") == "completed": video = requests.get(f"{apiUrl}/media/{quote(job['result']['mediaId'], safe='')}", headers=headers) with open("video.mp4", "wb") as f: f.write(video.content) else: print("error", job.get("error")) ``` === URL: https://useapi.net/docs/start-here/setup-kling === Document URL: https://useapi.net/docs/start-here/setup-kling --- layout: default title: Setup Kling description: "How to connect a Kling account to the useapi.net API — automated setup in a remote browser, email and password, or a connect tool for accounts that hit the Kling login slider." parent: Start Here nav_order: 235 --- # <img style="height:1em;vertical-align: middle;" src="/assets/images/kling.svg" alt=""> Setup Kling April 18, 2025 (November 14, 2026) ## Table of contents Approximately 2 minutes to complete setup steps. --- > This is the setup guide for [Kling API](/docs/api-kling-v1). An active [Kling AI](https://kling.ai/app/) subscription and a [useapi.net subscription](/docs/subscription) are required for the API to work. ### Automated setup (recommended) Use our guided browser setup to add your account automatically. Enter your API token, sign in with your Kling email and password in the remote browser, and your account is ready. The remote browser runs in the US next to our Kling servers, which avoids the `Unable to login (100110016: Your action is too frequent)` refusal some accounts get with a password login. [Open automated setup](/assets/setup-browser/kling.html) Prefer manual setup? Continue with the steps below. --- ## Create Kling AI account Navigate to [https://kling.ai/app/](https://kling.ai/app) and sign up with an email account. Our API does not support Gmail or Apple accounts. We strongly recommend creating a separate Kling AI account designated for API work. ![](/assets/images/kling_setup_1.png) ![](/assets/images/kling_setup_2.png) ![](/assets/images/kling_setup_3.png) ![](/assets/images/kling_setup_4.png) ## Add your account Most Kling accounts connect with just an email and password. Enter them below and choose **Add Account** (or **Verify** to test the credentials first). A `200` response means success. You can also call [POST /accounts](/docs/api-kling-v1/post-kling-accounts) directly. <script> async function apiTestAccountKling(addAccount) { data = { method: 'POST', headers: { 'Authorization': `Bearer ${document.getElementById('post-accounts-Kling-api_token').value}`, 'Content-Type': 'application/json' } }; let email = document.getElementById(`post-accounts-Kling-email`)?.value; let password = document.getElementById(`post-accounts-Kling-password`)?.value; email = email && email.length ? email : undefined; password = password && password.length ? password : undefined; const body = { password, email, maxJobs: 10 }; if (!addAccount) body.dryRun = true; data.body = JSON.stringify(body); await apiExecute(`https://api.useapi.net/v1/kling/accounts`, 'post-accounts-Kling', data); } </script> <form id="post-accounts-Kling" onsubmit="apiTestAccountKling(document.getElementById('post-accounts-Kling-action').value === 'add'); return false;" class="input-form"> <div class="input-field"> <div class="input-field-row"> <label for="post-accounts-Kling-api_token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="post-accounts-Kling-api_token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> <label for="post-accounts-Kling-email"><span>email </span> <input id="post-accounts-Kling-email" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> <label for="post-accounts-Kling-password"><span>password</span> <input id="post-accounts-Kling-password" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> <label for="post-accounts-Kling-action"><span>action</span> <select id="post-accounts-Kling-action" class="input-element"> <option value="verify">Verify — test credentials only</option> <option value="add">Add Account — required to complete setup</option> </select> </label> </div> <button id="post-accounts-Kling-button" class="btn btn-primary fs-3" type="submit">Go</button> </div> </form> <div id="post-accounts-Kling-response" class="response-placeholder visible-false"></div> ## Seeing a login slider captcha? Some Kling accounts are asked to solve a security slider at login. Kling decides this from the account's own risk history, so a brand-new or heavily-used account may get it while others never do. Our server cannot solve that slider, so for those accounts the **Add Account** step above returns: ```json { "error": "Unable to login (400002)" } ``` Kling can also refuse a password login outright with `Unable to login (100110016: Your action is too frequent)`. In both cases use the [automated setup](#automated-setup-recommended) above, where you solve the slider yourself in a browser that runs next to our servers. If you never see the slider when you sign in to Kling yourself, you do not need any of this — email and password is all it takes. You can also connect the account from your own browser, where the slider appears and you solve it once. Our connect tool guides you through it: you sign in to Kling a single time, it captures your signed-in session — a durable `passToken` plus your `did` and `userId` — and adds the account with those values. From then on the API refreshes the session with the `passToken` (valid about 21 days and rotated on each use), so no slider and no password login are needed while the `passToken` is valid. [Open the Kling connect tool](/assets/setup-browser/kling-connect.html) The tool shows the exact steps — copy a short code, paste it into Kling's browser Console, sign in and solve the slider, then paste your useapi.net API token and click **Add account**. ### Prefer to grab the values by hand? You can also read the three values yourself and pass them to [POST /accounts](/docs/api-kling-v1/post-kling-accounts). After you have signed in to Kling and solved the slider, open Developer Tools on [kling.ai/app](https://kling.ai/app) <span style="color: red;">`1`</span>, switch to the `Application` tab <span style="color: red;">`2`</span>, then under `Cookies` select `https://kling.ai` <span style="color: red;">`3`</span>. Copy the value of these three cookies: * `did` — a device id * `passToken` — the durable session token (about 21 days, rotated on each use) * `userId` — your numeric account id ![](/assets/images/kling_connect_1.jpg) Send all three together on [POST /accounts](/docs/api-kling-v1/post-kling-accounts), alongside your `email`, `password`, and `maxJobs`. Provide them only for an account that hits the slider — leave them out and the normal email and password login is used. Once an account is connected, you do not need the three values again. To update it later, for example to change `maxJobs`, post just `email`, `password` and `maxJobs`. The account keeps its `passToken` session, and the API cannot verify the password of a connected account, so it is stored as given — make sure it is correct. If the `passToken` stops working (for example after the account sits unused for about 21 days), the API falls back to a password login, which hits the slider. Connect the account again with the tool above to get a fresh `passToken`. Paste the three values into the form below with your email and password, then choose **Add Account** (or **Verify** to test first). A `200` response means success. <script> async function apiConnectAccountKling(addAccount) { data = { method: 'POST', headers: { 'Authorization': `Bearer ${document.getElementById('connect-accounts-Kling-api_token').value}`, 'Content-Type': 'application/json' } }; const g = (id) => { const v = document.getElementById(id)?.value?.trim(); return v && v.length ? v : undefined; }; const body = { email: g('connect-accounts-Kling-email'), password: g('connect-accounts-Kling-password'), maxJobs: 10, passToken: g('connect-accounts-Kling-passToken'), did: g('connect-accounts-Kling-did'), userId: g('connect-accounts-Kling-userId') }; if (!addAccount) body.dryRun = true; data.body = JSON.stringify(body); await apiExecute(`https://api.useapi.net/v1/kling/accounts`, 'connect-accounts-Kling', data); } </script> <form id="connect-accounts-Kling" onsubmit="apiConnectAccountKling(document.getElementById('connect-accounts-Kling-action').value === 'add'); return false;" class="input-form"> <div class="input-field"> <div class="input-field-row"> <label for="connect-accounts-Kling-api_token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="connect-accounts-Kling-api_token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> <label for="connect-accounts-Kling-email"><span>email</span> <input id="connect-accounts-Kling-email" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> <label for="connect-accounts-Kling-password"><span>password</span> <input id="connect-accounts-Kling-password" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> <label for="connect-accounts-Kling-passToken"><span>passToken</span> <textarea id="connect-accounts-Kling-passToken" class="input-element" rows="3" required aria-required="true" style="resize: both;"></textarea> </label> <label for="connect-accounts-Kling-did"><span>did</span> <input id="connect-accounts-Kling-did" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> <label for="connect-accounts-Kling-userId"><span>userId</span> <input id="connect-accounts-Kling-userId" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> <label for="connect-accounts-Kling-action"><span>action</span> <select id="connect-accounts-Kling-action" class="input-element"> <option value="verify">Verify — test credentials only</option> <option value="add">Add Account — required to complete setup</option> </select> </label> </div> <button id="connect-accounts-Kling-button" class="btn btn-primary fs-3" type="submit">Go</button> </div> </form> <div id="connect-accounts-Kling-response" class="response-placeholder visible-false"></div> > `passToken`, `did`, and `userId` are your live Kling session — keep them private and treat them like a password. The connect tool holds them in your browser and only sends them to useapi.net when you click **Add account**. === URL: https://useapi.net/docs/api-kling-v1 === Document URL: https://useapi.net/docs/api-kling-v1 --- layout: default title: Kling API nav_logo: /assets/images/kling.svg nav_title: Kling API seo_title: "Kling API: Kling 4.0, 3.0, O3 and Lip-Sync Video" description: "Third-party Kling API by useapi.net: Kling 4.0, 4.0 Flash, 3.0 and O3 video, avatars, motion control and lip-sync on your Kling AI subscription, over REST or MCP." nav_order: 2300 has_children: true permalink: /docs/api-kling-v1 repo: https://github.com/useapi/kling-api --- # <img style="height:1em;vertical-align: middle;" src="/assets/images/kling.svg" alt=""> Kling API April 18, 2025 (November 19, 2026) This is a [third-party](/docs/legal#affiliation--third-party-services) API for [Kling AI](https://kling.ai/app) by [Kuaishou Technology](https://www.kuaishou.com/en). It uses your [Kling AI subscription](https://kling.ai/app/membership/membership-plan): Free, Standard $8.80, Pro $32.56, Premier from $80.96 or Ultra+ $544.99 a month, with up to 21% off the first month (as of November 2026). It makes video with Kling 4.0, 4.0 Flash, 3.0 and Omni, plus images, talking avatars, lip-sync and motion control, through a REST API and a hosted MCP server. Kling 4.0 runs through this API too, at $0.76 for a 5-second 1080p video on Premier, against $1.15 on [Kling's own developer API](https://kling.ai/dev/pricing). On Premier, a 5-second 1080p Kling 3.0 video with sound uses $0.61 of the plan's monthly credits, against $0.84 a video on Kling's own API. ## Models | Model | What it makes | Notes | |---|---|---| | Kling 4.0<br>`kling-v4-0` | Video from [text](/docs/api-kling-v1/post-kling-videos-text2video), or from [a start image, an end image and keyframes between them](/docs/api-kling-v1/post-kling-videos-image2video-frames) | 3 to 30 seconds with stereo sound, multi-shot, 720p, or 1080p and 4K with optional HDR on paid subscriptions, 21:9 widescreen, up to 10 images per video | | Kling 4.0 Flash<br>`kling-v4-0-flash` | Video from [text](/docs/api-kling-v1/post-kling-videos-text2video) or from [a start image](/docs/api-kling-v1/post-kling-videos-image2video-frames) | A lower-cost Kling 4.0: 3 to 20 seconds with sound at 720p, 21:9 widescreen | | Kling 3.0<br>`kling-v3-0` | Video from text or images, and [images](/docs/api-kling-v1/post-kling-images-omni) | 3 to 15 seconds, multi-shot, sound, video and images up to 4K, 1 to 9 images per request | | Kling 3.0 Turbo<br>`kling-v3-0-turbo` | Video from text or images | A faster Kling 3.0, with sound | | Kling Image 4.0<br>`omni_version`: `v4` | [Images](/docs/api-kling-v1/post-kling-images-omni) from text and up to 10 reference images and elements | 2K, 4K and 8K, Series Mode of 2 to 10 images, [style, tone and font presets](/docs/api-kling-v1/get-kling-images-presets), and long product detail pages and web page designs | | Omni (O1, 3.0 / O3, 4.0 and 4.0 Flash)<br>`omni_version`: `o1`, `v3`, `v4`, `v4-flash` | [Video](/docs/api-kling-v1/post-kling-videos-omni) and [images](/docs/api-kling-v1/post-kling-images-omni) from reference images, saved [elements](/docs/api-kling-v1/get-kling-elements), reference videos and [voices](/docs/api-kling-v1/get-kling-videos-voices) | Omni 4.0 takes up to 10 images, 7 elements, 5 reference videos (30 seconds in total) and 3 voices, your own included, and costs the same as Kling 4.0. With a reference video it costs 20% more when the clip is at least as long as the videos, and more for a shorter clip. Omni 4.0 Flash takes the same references except voices, at 720p up to 20 seconds | | Kling 2.6, 2.5, 2.1 Master, 1.6 and 1.5 | Video from text or images | 5 or 10 seconds, Kling 2.6 with native sound | | KOLORS 3.0 and 2.1 | [Images](/docs/api-kling-v1/post-kling-images-kolors) from text and reference images | 1 to 9 images per request, and 2.1 adds face, subject and style references, or [up to 4 subjects with a scene and a style](/docs/api-kling-v1/post-kling-images-kolors-elements) | | Avatar 2.0 | [Talking avatar videos](/docs/api-kling-v1/post-kling-avatars-video) from an image | Lip-synced to your audio or to text-to-speech | | Lip-sync | Makes the person in a [video](/docs/api-kling-v1/post-kling-videos-lipsync) speak an audio file | Videos up to 60 seconds | | Motion control | Moves a character image like the person in a [reference video](/docs/api-kling-v1/post-kling-videos-motion-create) | Kling 3.0 and 2.6, from a 3 to 30 second reference video, with its sound kept if you like | | Image enhance | [Sharper images](/docs/api-kling-v1/post-kling-images-enhance) with restored detail | 2K or 4K from any image, and [upscale](/docs/api-kling-v1/post-kling-images-upscale) for images Kling made | | Speech | [Text-to-speech](/docs/api-kling-v1/post-kling-tts-create) | Up to 5 minutes | | More | [Effects](/docs/api-kling-v1/post-kling-videos-image2video-effects), [extend](/docs/api-kling-v1/post-kling-videos-extend), [add sound](/docs/api-kling-v1/post-kling-videos-add-sound), [virtual try-on](/docs/api-kling-v1/post-kling-images-virtual-try-on) and [face detection](/docs/api-kling-v1/post-kling-images-recognize-faces) | | ## MCP server The hosted [Kling MCP server](/docs/api-kling-v1/mcp) gives Claude Code, Cursor, VS Code and other AI assistants 46 tools for Kling video, images, avatars, lip-sync, elements and voices, with your useapi.net API token and nothing to install. The [kling-api](https://github.com/useapi/kling-api) repo also adds it in one step as a [Claude Code plugin](https://github.com/useapi/kling-api#use-with-claude-code) or a [Gemini CLI extension](https://github.com/useapi/kling-api#use-with-gemini-cli). ## Pricing What one video costs on [Kling's developer API](https://kling.ai/dev/pricing) and on each Kling AI subscription (as of October 2026). Each subscription comes with a monthly number of credits, and each video uses a set number of them, so a video costs its share of the subscription. | Model | [Official API](https://kling.ai/dev/pricing) | Premier $80.96/m (8,000 cr/mo) | Pro $32.56/m (3,000 cr/mo) | Standard $8.80/m (660 cr/mo) | |---|---|---|---|---| | Kling 4.0 (720p, 5 s) | $0.77 ($0.154 a second) | $0.51 / 50 cr (160 videos/mo) | $0.54 / 50 cr (60 videos/mo) | $0.67 / 50 cr (13 videos/mo) | | Kling 4.0 (1080p, 5 s) | $1.15 ($0.231 a second) | $0.76 / 75 cr (106 videos/mo) | $0.81 / 75 cr (40 videos/mo) | $1.00 / 75 cr (8 videos/mo) | | Kling 4.0 (4K, 5 s) | $2.69 ($0.538 a second) | $1.77 / 175 cr (45 videos/mo) | $1.90 / 175 cr (17 videos/mo) | $2.33 / 175 cr (3 videos/mo) | | Kling 4.0 Flash (720p, 5 s) | $0.46 ($0.092 a second) | $0.30 / 30 cr (266 videos/mo) | $0.33 / 30 cr (100 videos/mo) | $0.40 / 30 cr (22 videos/mo) | | Kling 3.0 (1080p with sound, 5 s) | $0.84 ($0.168 a second) | $0.61 / 60 cr (133 videos/mo) | $0.65 / 60 cr (50 videos/mo) | $0.80 / 60 cr (11 videos/mo) | | Omni O1 (5 s) | — | $0.30 / 30 cr (266 videos/mo) | $0.33 / 30 cr (100 videos/mo) | $0.40 / 30 cr (22 videos/mo) | | Motion control (Kling 3.0, 5 s) | $0.63 ($0.126 a second) | $0.46 / 45 cr (177 videos/mo) | $0.49 / 45 cr (66 videos/mo) | $0.60 / 45 cr (14 videos/mo) | | Avatar 2.0 (5 s) | $0.28 ($0.056 a second) | $0.20 / 20 cr (400 videos/mo) | $0.22 / 20 cr (150 videos/mo) | $0.27 / 20 cr (33 videos/mo) | | Lip-sync (5 s) | — | $0.05 / 5 cr (1,600 videos/mo) | $0.05 / 5 cr (600 videos/mo) | $0.07 / 5 cr (132 videos/mo) | | Kling Image 4.0 (2K) | $0.06 (16 units) | $0.04 / 4 cr (2,000 images/mo) | $0.04 / 4 cr (750 images/mo) | $0.05 / 4 cr (165 images/mo) | | Kling Image 4.0 (8K) | $0.15 (40 units) | $0.10 / 10 cr (800 images/mo) | $0.11 / 10 cr (300 images/mo) | $0.13 / 10 cr (66 images/mo) | | Kling 3.0 image (2K) | — | $0.02 / 2 cr (4,000 images/mo) | $0.02 / 2 cr (1,500 images/mo) | $0.03 / 2 cr (330 images/mo) | | [Text-to-speech](/docs/api-kling-v1/post-kling-tts-create) (up to 5 minutes) | — | $0 / 0 cr (free on every plan) | $0 / 0 cr (free on every plan) | $0 / 0 cr (free on every plan) | | [Face detection](/docs/api-kling-v1/post-kling-images-recognize-faces) | — | $0 / 0 cr (free on every plan) | $0 / 0 cr (free on every plan) | $0 / 0 cr (free on every plan) | - Text-to-speech and face detection cost 0 credits on every Kling AI subscription, including the free one. - On a paid Kling AI subscription you also get downloads [without the Kling watermark](/docs/api-kling-v1/get-kling-assets-download), [2 to 4 Omni videos per request](/docs/api-kling-v1/post-kling-videos-omni), [4K Kling 3.0 and 4.0 video](/docs/api-kling-v1/post-kling-videos-text2video) and [4K and 8K images](/docs/api-kling-v1/post-kling-images-omni). - Omni O1, motion control and Avatar 2.0 are shown at standard quality. - Kling's developer API sells video packs from $700 for 5,000 units, valid 180 days, separately from the Kling AI subscriptions, and Kling 4.0 and 4.0 Flash in their own packs from $500 for 3,250 units (as of November 5, 2026). Kling Image 4.0 has its own image packs there, from $300 for 78,216 units, and each reference image or element costs extra (as of November 19, 2026). The Official API column uses the smallest of each. - Larger Premier and Ultra+ subscriptions, yearly billing and [credit top-ups](https://kling.ai/app/membership/spirit-unit) are in the calculator below. <details markdown="block" class="calc-details"> <summary>Cost calculator for every model and subscription</summary> <div class="calc"> <div class="calc-head"><label for="planSelect" class="calc-label">Kling AI subscription</label><span class="calc-sep" aria-hidden="true">·</span><a class="calc-link" href="https://kling.ai/app/membership/membership-plan">current prices and offers</a></div> <select id="planSelect" class="calc-select"> <optgroup label="Monthly"> <option value="std_monthly">Standard · $8.80/mo · 660 credits · $0.0133/credit</option> <option value="pro_monthly" selected>Pro · $32.56/mo · 3,000 credits · $0.0109/credit</option> <option value="premier_monthly">Premier 8K · $80.96/mo · 8,000 credits · $0.0101/credit</option> <option value="premier18_monthly">Premier 18K · $181.99/mo · 18,000 credits · $0.0101/credit</option> <option value="premier28_monthly">Premier 28K · $283.99/mo · 28,000 credits · $0.0101/credit</option> <option value="premier38_monthly">Premier 38K · $376.99/mo · 38,000 credits · $0.0099/credit</option> <option value="ultraplus_monthly">Ultra+ · $544.99/mo · 57,000 credits · $0.0096/credit</option> </optgroup> <optgroup label="First month offer"> <option value="std_first">Standard first month · $6.99 · 660 credits · $0.0106/credit</option> <option value="pro_first">Pro first month · $25.99 · 3,000 credits · $0.0087/credit</option> <option value="premier_first">Premier 8K first month · $64.99 · 8,000 credits · $0.0081/credit</option> <option value="premier18_first">Premier 18K first month · $144.99 · 18,000 credits · $0.0081/credit</option> <option value="premier28_first">Premier 28K first month · $225.99 · 28,000 credits · $0.0081/credit</option> <option value="premier38_first">Premier 38K first month · $299.99 · 38,000 credits · $0.0079/credit</option> <option value="ultraplus_first">Ultra+ first month · $432.99 · 57,000 credits · $0.0076/credit</option> </optgroup> <optgroup label="Yearly"> <option value="std_yearly">Standard yearly · $79.20/yr · 7,920 credits · $0.0100/credit</option> <option value="pro_yearly">Pro yearly · $293.04/yr · 36,000 credits · $0.0081/credit</option> <option value="premier_yearly">Premier 8K yearly · $728.64/yr · 96,000 credits · $0.0076/credit</option> <option value="premier18_yearly">Premier 18K yearly · $1,639.99/yr · 216,000 credits · $0.0076/credit</option> <option value="premier28_yearly">Premier 28K yearly · $2,550.99/yr · 336,000 credits · $0.0076/credit</option> <option value="premier38_yearly">Premier 38K yearly · $3,389.99/yr · 456,000 credits · $0.0074/credit</option> <option value="ultraplus_yearly">Ultra+ yearly · $4,902.99/yr · 684,000 credits · $0.0072/credit</option> </optgroup> <optgroup label="First year offer"> </optgroup> <optgroup label="Credit packs"> <option value="credits">Credits card · $200 · 16,000 credits · valid 2 years · $0.0125/credit</option> </optgroup> <optgroup label="No longer sold"> <option value="ultra_monthly">Ultra · $159.99/mo · 26,000 credits · $0.0062/credit</option> <option value="ultra_yearly">Ultra yearly · $1,430/yr · 312,000 credits · $0.0046/credit</option> </optgroup> <option value="custom">Custom cost and credits…</option> </select> <div id="customInputs" class="calc-custom" style="display: none;"> <div> <label for="customCost" class="calc-label">Cost ($)</label> <input type="number" id="customCost" min="0" step="0.01" value="159.99"> </div> <div> <label for="customCredits" class="calc-label">Credits</label> <input type="number" id="customCredits" min="1" step="1" value="26000"> </div> </div> </div> <div> <table class="calc-plan"> <thead> <tr> <th>Subscription</th> <th>Cost</th> <th>Credits</th> <th>Per credit</th> </tr> </thead> <tbody> <tr id="planDetails"> <td id="planName">Pro monthly</td> <td id="planCost">$32.56/mo</td> <td id="planCredits">3,000</td> <td id="creditCost">$0.0109</td> </tr> </tbody> </table> </div> <h4>Price per video or image</h4> <div> <table class="calc-gen"> <thead> <tr> <th>Kling Model</th> <th>Credits</th> <th>Cost</th> </tr> </thead> <tbody id="generationTableBody"> <tr> <td>2.6 Pro Native Audio 1080p 10sec</td> <td>100</td> <td class="gen-price">$1.09</td> </tr> <tr> <td>2.6 Pro Native Audio 1080p 5sec</td> <td>50</td> <td class="gen-price">$0.54</td> </tr> <tr> <td>2.6 Pro 1080p 10sec</td> <td>50</td> <td class="gen-price">$0.54</td> </tr> <tr> <td>2.6 Pro 1080p 5sec</td> <td>25</td> <td class="gen-price">$0.27</td> </tr> <tr> <td>2.6 Std 720p 10sec</td> <td>30</td> <td class="gen-price">$0.33</td> </tr> <tr> <td>2.6 Std 720p 5sec</td> <td>15</td> <td class="gen-price">$0.16</td> </tr> <tr> <td>2.5 Pro 1080p 10sec</td> <td>50</td> <td class="gen-price">$0.54</td> </tr> <tr> <td>2.5 Pro 1080p 5sec</td> <td>25</td> <td class="gen-price">$0.27</td> </tr> <tr> <td>2.1 Pro 1080p 10sec</td> <td>70</td> <td class="gen-price">$0.76</td> </tr> <tr> <td>2.1 Pro 1080p 5sec</td> <td>35</td> <td class="gen-price">$0.38</td> </tr> <tr> <td>2.1 Std 720p 10sec</td> <td>40</td> <td class="gen-price">$0.43</td> </tr> <tr> <td>2.1 Std 720p 5sec</td> <td>20</td> <td class="gen-price">$0.22</td> </tr> <tr> <td>2.x Master 1080p 10sec</td> <td>200</td> <td class="gen-price">$2.17</td> </tr> <tr> <td>2.x Master 1080p 5sec</td> <td>100</td> <td class="gen-price">$1.09</td> </tr> <tr> <td>1.6 Pro 1080p 10sec</td> <td>70</td> <td class="gen-price">$0.76</td> </tr> <tr> <td>1.6 Pro 1080p 5sec</td> <td>35</td> <td class="gen-price">$0.38</td> </tr> <tr> <td>1.6 Std 720p 10sec</td> <td>40</td> <td class="gen-price">$0.43</td> </tr> <tr> <td>1.6 Std 720p 5sec</td> <td>20</td> <td class="gen-price">$0.22</td> </tr> <tr> <td>v3 Motion Pro (per sec)</td> <td>12</td> <td class="gen-price">$0.13</td> </tr> <tr> <td>v3 Motion Std (per sec)</td> <td>9</td> <td class="gen-price">$0.10</td> </tr> <tr> <td>2.6 Motion Std 720p 10sec</td> <td>70</td> <td class="gen-price">$0.76</td> </tr> <tr> <td>2.6 Motion Std 720p 5sec</td> <td>35</td> <td class="gen-price">$0.38</td> </tr> <tr> <td>2.6 Motion Pro 1080p 10sec</td> <td>100</td> <td class="gen-price">$1.09</td> </tr> <tr> <td>2.6 Motion Pro 1080p 5sec</td> <td>50</td> <td class="gen-price">$0.54</td> </tr> <tr> <td>Video Extend</td> <td>20</td> <td class="gen-price">$0.22</td> </tr> <tr> <td>Video Add Sound</td> <td>2.5</td> <td class="gen-price">$0.03</td> </tr> <tr> <td>Effects Std</td> <td>20</td> <td class="gen-price">$0.22</td> </tr> <tr> <td>Effects Pro</td> <td>35</td> <td class="gen-price">$0.38</td> </tr> <tr> <td>LipSync 5sec</td> <td>5</td> <td class="gen-price">$0.05</td> </tr> <tr> <td>LipSync 10sec</td> <td>10</td> <td class="gen-price">$0.11</td> </tr> <tr> <td>Avatar 2.0 Pro (per sec)</td> <td>8</td> <td class="gen-price">$0.09</td> </tr> <tr> <td>Avatar 2.0 Std (per sec)</td> <td>4</td> <td class="gen-price">$0.04</td> </tr> <tr> <td>Virtual Try-On</td> <td>5</td> <td class="gen-price">$0.05</td> </tr> <tr> <td>KOLORS 1.5/2.0/2.1 Image</td> <td>1</td> <td class="gen-price">$0.01</td> </tr> <tr> <td>O1 Image 1k</td> <td>1</td> <td class="gen-price">$0.01</td> </tr> <tr> <td>O1 Image 2k</td> <td>1</td> <td class="gen-price">$0.01</td> </tr> <tr> <td>O1 Video Pro 10sec</td> <td>80</td> <td class="gen-price">$0.87</td> </tr> <tr> <td>O1 Video Pro 5sec</td> <td>40</td> <td class="gen-price">$0.43</td> </tr> <tr> <td>O1 Video Std 10sec</td> <td>60</td> <td class="gen-price">$0.65</td> </tr> <tr> <td>O1 Video Std 5sec</td> <td>30</td> <td class="gen-price">$0.33</td> </tr> <tr> <td>v4 Video 4K (per sec)</td> <td>35</td> <td class="gen-price">$0.38</td> </tr> <tr> <td>v4 Video 4K HDR (per sec)</td> <td>40</td> <td class="gen-price">$0.43</td> </tr> <tr> <td>v4 Video Pro (per sec)</td> <td>15</td> <td class="gen-price">$0.15</td> </tr> <tr> <td>v4 Video Pro HDR (per sec)</td> <td>18</td> <td class="gen-price">$0.20</td> </tr> <tr> <td>v4 Video Std (per sec)</td> <td>10</td> <td class="gen-price">$0.10</td> </tr> <tr> <td>v4 Omni 4K with reference video (per sec)</td> <td>42</td> <td class="gen-price">$0.46</td> </tr> <tr> <td>v4 Omni 4K HDR with reference video (per sec)</td> <td>47</td> <td class="gen-price">$0.51</td> </tr> <tr> <td>v4 Omni Pro with reference video (per sec)</td> <td>18</td> <td class="gen-price">$0.20</td> </tr> <tr> <td>v4 Omni Pro HDR with reference video (per sec)</td> <td>21</td> <td class="gen-price">$0.23</td> </tr> <tr> <td>v4 Omni Std with reference video (per sec)</td> <td>12</td> <td class="gen-price">$0.13</td> </tr> <tr> <td>v4 Flash Video Std (per sec)</td> <td>6</td> <td class="gen-price">$0.07</td> </tr> <tr> <td>v4 Flash Omni with reference video (per sec)</td> <td>8</td> <td class="gen-price">$0.09</td> </tr> <tr> <td>v3 Video 4k (per sec)</td> <td>30</td> <td class="gen-price">$0.33</td> </tr> <tr> <td>v3 Video Pro (per sec)</td> <td>12</td> <td class="gen-price">$0.13</td> </tr> <tr> <td>v3 Video Std (per sec)</td> <td>9</td> <td class="gen-price">$0.10</td> </tr> <tr> <td>v3 Video Pro audio-off (per sec)</td> <td>8</td> <td class="gen-price">$0.09</td> </tr> <tr> <td>v3 Video Std audio-off (per sec)</td> <td>6</td> <td class="gen-price">$0.07</td> </tr> <tr> <td>Omni 3.0 Pro (per sec)</td> <td>12</td> <td class="gen-price">$0.13</td> </tr> <tr> <td>Omni 3.0 Std (per sec)</td> <td>9</td> <td class="gen-price">$0.10</td> </tr> <tr> <td>Omni 3.0 Pro audio-off (per sec)</td> <td>8</td> <td class="gen-price">$0.09</td> </tr> <tr> <td>Omni 3.0 Std audio-off (per sec)</td> <td>6</td> <td class="gen-price">$0.07</td> </tr> <tr> <td>v3 Turbo Video Pro (per sec)</td> <td>10</td> <td class="gen-price">$0.11</td> </tr> <tr> <td>v3 Turbo Video Std (per sec)</td> <td>8</td> <td class="gen-price">$0.09</td> </tr> <tr> <td>v3 Image 1k</td> <td>1</td> <td class="gen-price">$0.01</td> </tr> <tr> <td>v3 Image 2k</td> <td>2</td> <td class="gen-price">$0.02</td> </tr> <tr> <td>v3 Image 4k (VIP)</td> <td>4</td> <td class="gen-price">$0.04</td> </tr> <tr> <td>v4 Image 2k</td> <td>4</td> <td class="gen-price">$0.04</td> </tr> <tr> <td>v4 Image 4k (VIP)</td> <td>6</td> <td class="gen-price">$0.07</td> </tr> <tr> <td>v4 Image 8k (VIP)</td> <td>10</td> <td class="gen-price">$0.11</td> </tr> <tr> <td>v4 Product Detail 1k short</td> <td>15</td> <td class="gen-price">$0.16</td> </tr> <tr> <td>v4 Product Detail 1k medium</td> <td>30</td> <td class="gen-price">$0.33</td> </tr> <tr> <td>v4 Product Detail 1k long</td> <td>50</td> <td class="gen-price">$0.54</td> </tr> <tr> <td>v4 Product Detail 2k short</td> <td>18</td> <td class="gen-price">$0.20</td> </tr> <tr> <td>v4 Product Detail 2k medium</td> <td>35</td> <td class="gen-price">$0.38</td> </tr> <tr> <td>v4 Product Detail 2k long</td> <td>55</td> <td class="gen-price">$0.60</td> </tr> <tr> <td>v4 Web Design 1k</td> <td>35</td> <td class="gen-price">$0.38</td> </tr> <tr> <td>v4 Web Design 2k</td> <td>38</td> <td class="gen-price">$0.41</td> </tr> <tr> <td>KOLORS v3.0 Image</td> <td>1</td> <td class="gen-price">$0.01</td> </tr> <tr> <td>Image Enhance 2K</td> <td>1</td> <td class="gen-price">$0.01</td> </tr> <tr> <td>Image Enhance 4K</td> <td>2</td> <td class="gen-price">$0.02</td> </tr> </tbody> </table> </div> </details> <script> (function() { const klingCalculatorData = { plans: { std_monthly: { name: "Standard monthly", cost: 8.80, credits: 660, period: "/mo" }, pro_monthly: { name: "Pro monthly", cost: 32.56, credits: 3000, period: "/mo" }, premier_monthly: { name: "Premier 8K monthly", cost: 80.96, credits: 8000, period: "/mo" }, premier18_monthly: { name: "Premier 18K monthly", cost: 181.99, credits: 18000, period: "/mo" }, premier28_monthly: { name: "Premier 28K monthly", cost: 283.99, credits: 28000, period: "/mo" }, premier38_monthly: { name: "Premier 38K monthly", cost: 376.99, credits: 38000, period: "/mo" }, ultraplus_monthly: { name: "Ultra+ monthly", cost: 544.99, credits: 57000, period: "/mo" }, std_first: { name: "Standard first month", cost: 6.99, credits: 660 }, pro_first: { name: "Pro first month", cost: 25.99, credits: 3000 }, premier_first: { name: "Premier 8K first month", cost: 64.99, credits: 8000 }, premier18_first: { name: "Premier 18K first month", cost: 144.99, credits: 18000 }, premier28_first: { name: "Premier 28K first month", cost: 225.99, credits: 28000 }, premier38_first: { name: "Premier 38K first month", cost: 299.99, credits: 38000 }, ultraplus_first: { name: "Ultra+ first month", cost: 432.99, credits: 57000 }, std_yearly: { name: "Standard yearly (660 credits a month)", cost: 79.20, credits: 7920, period: "/yr" }, pro_yearly: { name: "Pro yearly (3,000 credits a month)", cost: 293.04, credits: 36000, period: "/yr" }, premier_yearly: { name: "Premier 8K yearly (8,000 credits a month)", cost: 728.64, credits: 96000, period: "/yr" }, premier18_yearly: { name: "Premier 18K yearly (18,000 credits a month)", cost: 1639.99, credits: 216000, period: "/yr" }, premier28_yearly: { name: "Premier 28K yearly (28,000 credits a month)", cost: 2550.99, credits: 336000, period: "/yr" }, premier38_yearly: { name: "Premier 38K yearly (38,000 credits a month)", cost: 3389.99, credits: 456000, period: "/yr" }, ultraplus_yearly: { name: "Ultra+ yearly (57,000 credits a month)", cost: 4902.99, credits: 684000, period: "/yr" }, credits: { name: "Credits card (valid 2 years)", cost: 200, credits: 16000 }, ultra_monthly: { name: "Ultra monthly (no longer sold)", cost: 159.99, credits: 26000, period: "/mo" }, ultra_yearly: { name: "Ultra yearly (26,000 credits a month, no longer sold)", cost: 1430, credits: 312000, period: "/yr" }, custom: { name: "Custom plan", cost: 159.99, credits: 26000 } }, generations: [ { name: "2.6 Pro Native Audio 1080p 10sec", credits: 100 }, { name: "2.6 Pro Native Audio 1080p 5sec", credits: 50 }, { name: "2.6 Pro 1080p 10sec", credits: 50 }, { name: "2.6 Pro 1080p 5sec", credits: 25 }, { name: "2.6 Std 720p 10sec", credits: 30 }, { name: "2.6 Std 720p 5sec", credits: 15 }, { name: "2.5 Pro 1080p 10sec", credits: 50 }, { name: "2.5 Pro 1080p 5sec", credits: 25 }, { name: "2.1 Pro 1080p 10sec", credits: 70 }, { name: "2.1 Pro 1080p 5sec", credits: 35 }, { name: "2.1 Std 720p 10sec", credits: 40 }, { name: "2.1 Std 720p 5sec", credits: 20 }, { name: "2.x Master 1080p 10sec", credits: 200 }, { name: "2.x Master 1080p 5sec", credits: 100 }, { name: "1.6 Pro 1080p 10sec", credits: 70 }, { name: "1.6 Pro 1080p 5sec", credits: 35 }, { name: "1.6 Std 720p 10sec", credits: 40 }, { name: "1.6 Std 720p 5sec", credits: 20 }, { name: "v3 Motion Pro (per sec)", credits: 12 }, { name: "v3 Motion Std (per sec)", credits: 9 }, { name: "2.6 Motion Std 720p 10sec", credits: 70 }, { name: "2.6 Motion Std 720p 5sec", credits: 35 }, { name: "2.6 Motion Pro 1080p 10sec", credits: 100 }, { name: "2.6 Motion Pro 1080p 5sec", credits: 50 }, { name: "Video Extend", credits: 20 }, { name: "Video Add Sound", credits: 2.5 }, { name: "Effects Std", credits: 20 }, { name: "Effects Pro", credits: 35 }, { name: "LipSync 5sec", credits: 5 }, { name: "LipSync 10sec", credits: 10 }, { name: "Avatar 2.0 Pro (per sec)", credits: 8 }, { name: "Avatar 2.0 Std (per sec)", credits: 4 }, { name: "Virtual Try-On", credits: 5 }, { name: "KOLORS 1.5/2.0/2.1 Image", credits: 1 }, { name: "O1 Image 1k", credits: 1 }, { name: "O1 Image 2k", credits: 1 }, { name: "O1 Video Pro 10sec", credits: 80 }, { name: "O1 Video Pro 5sec", credits: 40 }, { name: "O1 Video Std 10sec", credits: 60 }, { name: "O1 Video Std 5sec", credits: 30 }, { name: "v4 Video 4K (per sec)", credits: 35 }, { name: "v4 Video 4K HDR (per sec)", credits: 40 }, { name: "v4 Video Pro (per sec)", credits: 15 }, { name: "v4 Video Pro HDR (per sec)", credits: 18 }, { name: "v4 Video Std (per sec)", credits: 10 }, { name: "v4 Omni 4K with reference video (per sec)", credits: 42 }, { name: "v4 Omni 4K HDR with reference video (per sec)", credits: 47 }, { name: "v4 Omni Pro with reference video (per sec)", credits: 18 }, { name: "v4 Omni Pro HDR with reference video (per sec)", credits: 21 }, { name: "v4 Omni Std with reference video (per sec)", credits: 12 }, { name: "v4 Flash Video Std (per sec)", credits: 6 }, { name: "v4 Flash Omni with reference video (per sec)", credits: 8 }, { name: "v3 Video 4k (per sec)", credits: 30 }, { name: "v3 Video Pro (per sec)", credits: 12 }, { name: "v3 Video Std (per sec)", credits: 9 }, { name: "v3 Video Pro audio-off (per sec)", credits: 8 }, { name: "v3 Video Std audio-off (per sec)", credits: 6 }, { name: "Omni 3.0 Pro (per sec)", credits: 12 }, { name: "Omni 3.0 Std (per sec)", credits: 9 }, { name: "Omni 3.0 Pro audio-off (per sec)", credits: 8 }, { name: "Omni 3.0 Std audio-off (per sec)", credits: 6 }, { name: "v3 Turbo Video Pro (per sec)", credits: 10 }, { name: "v3 Turbo Video Std (per sec)", credits: 8 }, { name: "v3 Image 1k", credits: 1 }, { name: "v3 Image 2k", credits: 2 }, { name: "v3 Image 4k (VIP)", credits: 4 }, { name: "v4 Image 2k", credits: 4 }, { name: "v4 Image 4k (VIP)", credits: 6 }, { name: "v4 Image 8k (VIP)", credits: 10 }, { name: "v4 Product Detail 1k short", credits: 15 }, { name: "v4 Product Detail 1k medium", credits: 30 }, { name: "v4 Product Detail 1k long", credits: 50 }, { name: "v4 Product Detail 2k short", credits: 18 }, { name: "v4 Product Detail 2k medium", credits: 35 }, { name: "v4 Product Detail 2k long", credits: 55 }, { name: "v4 Web Design 1k", credits: 35 }, { name: "v4 Web Design 2k", credits: 38 }, { name: "KOLORS v3.0 Image", credits: 1 }, { name: "Image Enhance 2K", credits: 1 }, { name: "Image Enhance 4K", credits: 2 } ] }; if (document.readyState === 'loading') { document.addEventListener('DOMContentLoaded', setupCalculator); } else { setupCalculator(); } function setupCalculator() { const planSelect = document.getElementById('planSelect'); const customInputs = document.getElementById('customInputs'); const customCost = document.getElementById('customCost'); const customCredits = document.getElementById('customCredits'); const planName = document.getElementById('planName'); const planCost = document.getElementById('planCost'); const planCredits = document.getElementById('planCredits'); const creditCost = document.getElementById('creditCost'); const genPrices = document.querySelectorAll('.gen-price'); if (!planSelect || !customInputs || !customCost || !customCredits || !planName || !planCost || !planCredits || !creditCost) { return; } function money(n) { return '$' + (Number.isInteger(n) ? n.toLocaleString('en-US') : n.toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 })); } function updatePrices() { let selectedPlan; if (planSelect.value === 'custom') { customInputs.style.display = 'flex'; const cost = parseFloat(customCost.value) || 0; const credits = parseInt(customCredits.value) || 1; klingCalculatorData.plans.custom.cost = cost; klingCalculatorData.plans.custom.credits = credits; selectedPlan = klingCalculatorData.plans.custom; } else { customInputs.style.display = 'none'; selectedPlan = klingCalculatorData.plans[planSelect.value]; } planName.textContent = selectedPlan.name; planCost.textContent = money(selectedPlan.cost) + (selectedPlan.period || ''); planCredits.textContent = selectedPlan.credits.toLocaleString('en-US'); const creditCostValue = selectedPlan.cost / selectedPlan.credits; creditCost.textContent = '$' + creditCostValue.toFixed(4); klingCalculatorData.generations.forEach((gen, index) => { if (index < genPrices.length) { const price = (gen.credits * creditCostValue).toFixed(2); genPrices[index].textContent = '$' + price; } }); } planSelect.addEventListener('change', updatePrices); customCost.addEventListener('input', updatePrices); customCredits.addEventListener('input', updatePrices); updatePrices(); } })(); </script> ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. ## Run several Kling accounts Video and image requests don't need `email`: each job goes to one of your accounts that has a free job slot, within the `maxJobs` limit (1 to 50) you set for each account with [POST accounts](/docs/api-kling-v1/post-kling-accounts). When every account is busy you get `429`, so wait and send it again. Pass `email` to run a job on a specific account, and to read that account's tasks, assets and voices ([GET tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) explains how to find which account ran a job). A ready-made [n8n Google Sheet queue](https://github.com/useapi/kling-api/tree/main/n8n) spreads Kling 4.0 jobs across your accounts this way. Every generation request can also send its progress and result to your webhook ([what it sends](/docs/api-kling-v1/get-kling-tasks-task_id#model)), so you don't have to poll while a video takes a few minutes. [How useapi.net works](/docs/how-it-works) has tips for keeping your accounts healthy. ## Questions ### Is there a Kling 4.0 API? Through useapi.net, yes, on your Kling AI subscription: $0.152 a second at 1080p on Kling Premier, in [text-to-video](/docs/api-kling-v1/post-kling-videos-text2video), [image-to-video with keyframes](/docs/api-kling-v1/post-kling-videos-image2video-frames) and [Omni](/docs/api-kling-v1/post-kling-videos-omni). Kling's own [developer API](https://kling.ai/dev/pricing) charges $0.231 a second at 1080p, in prepaid packs from $500 (as of October 28, 2026). Step by step: [the Kling 4.0 tutorial](/docs/articles/kling-4-api). ### How much does the Kling API cost? Through useapi.net, a 5-second Kling 3.0 video at 1080p with sound costs $0.65 on Kling's Pro subscription, against about $0.84 on Kling's developer API, which also needs a prepaid video pack from $700 (as of October 2026). The [price table](#pricing) shows each model on each subscription. ### Do I need a Kling API key? Through useapi.net, you use our [API token](/docs/start-here/setup-useapi), not a Kling developer key, and connect your Kling account once through [Setup Kling](/docs/start-here/setup-kling). A free account runs text-to-speech and face detection; Kling gives its free plan no monthly credits (Kling's own wording), so videos need credits from a paid subscription. Kling's developer API needs a separate developer account and its own key instead. ### Is there a Kling motion control API? Through useapi.net, yes, on Kling 3.0 and 2.6 with your Kling AI subscription: [POST videos/motion-create](/docs/api-kling-v1/post-kling-videos-motion-create) moves a character image like the person in a reference video. A 5-second Kling 3.0 motion control video costs $0.49 on Kling's Pro subscription (as of October 2026), and the [motion control example](/blog/260306) shows the results. [Setup Kling](/docs/start-here/setup-kling) [LLM-friendly API spec](https://useapi.net/assets/aibot/api-kling-v1.txt) Feed this to your LLM to build integrations [Claude Code skill](/llm-tools) A drop-in useapi.net skill for Claude Code, and a rule for Cursor [Postman collection](https://www.postman.com/useapinet/useapi-net/collection/29112081-d26e35d5-af3a-44a7-9810-3aeb6351c169) (November 5, 2026) [MCP Server](/docs/api-kling-v1/mcp) Kling video, images, avatars and lip-sync from Claude Code, Cursor, VS Code and other MCP clients [GitHub examples](https://github.com/useapi/kling-api) Kling 4.0, text-to-video, multi-image Omni, motion control, lip-sync and images [n8n Google Sheet queue](https://github.com/useapi/kling-api/tree/main/n8n) Kling 4.0 videos from a Google Sheet, spread across your Kling accounts Articles: * [How to Generate Kling Image 4.0 Images via the Kling API](/docs/articles/kling-image-4-api) * [Kling 4.0 API Pricing: Every Route, Compared](/docs/articles/kling-4-api-pricing) * [How to Generate Kling 4.0 Video via the Kling API](/docs/articles/kling-4-api) * [How to Generate AI Video with Kling v3 via the Kling API](/docs/articles/kling-bash) * [Sora 2 API Alternatives Compared, With Code: Seedance 2.5, Omni Flash, MiniMax H3, Kling v3](/docs/articles/sora-2-api-alternatives) * [How to Generate Multi-Reference & Multi-Shot Video with Kling Omni via the Kling API](/docs/articles/kling-omni-bash) * [Kling Lip-Sync Avatars, Motion Control & Image Generation via the Kling API](/docs/articles/kling-features-bash) Examples: * [Kling 3.0 Turbo](/blog/260617) * [17 AI Image Models: The Showdown](/blog/260309i) * [Kling Motion Control v3.0](/blog/260306) * [Kling Multi-Shot](/blog/260216) * [Kling API v3](/blog/260209) * [Kling API Elements, Avatars 2.0 and Video O1 (Omni)](/blog/260112) * [Kling API Motion Control v2.6](/blog/260106) * [Kling API Image O1 (Omni)](/blog/251210) * [Kling API v2.6 with Native Audio](/blog/251204) * [Kling API Create Video using First and Last Frames](/blog/251127) * [Kling API Motion Control Samples](/blog/251007) * [Kling API Text/Image-to-Video v2.5 Samples](/blog/250923) * [Kling API Text/Image-to-Video v1.5, v1.6 and v2.0 Samples](/blog/250418) * [Kling API Text-to-Image KOLORS Samples](/blog/250424) * [Kling API KOLORS Elements Sample](/blog/250718) * [Kling API Video To Sound](/blog/250808) Videos on YouTube: * [Mission: Kitchen Impossible, Kling v3 multi-shot](https://www.youtube.com/watch?v=Ti8oHAvg7Cw) * [Kling Video O1](https://www.youtube.com/watch?v=rUcVpqwcNVY) * [Kling Avatar 2.0](https://www.youtube.com/shorts/nKw61pdzFmw) * [Smooth Criminal, Kling Motion 3.0](https://www.youtube.com/shorts/VztjBYqqQ1A) Developer Community: * <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> * <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> === URL: https://useapi.net/docs/api-kling-v1/del-kling-accounts-email === Document URL: https://useapi.net/docs/api-kling-v1/del-kling-accounts-email --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> accounts/`email` description: "Remove a specific Kling account from your useapi.net configuration by email via DELETE accounts/email in the Kling API v1." parent: Kling API nav_order: 130 --- ## Delete Kling API account configuration for `email` April 18, 2025 --- This endpoint removes a specific Kling account from your configuration. > **https://api.useapi.net/v1/kling/accounts/`email`** The `email` value should correspond to an account configured previously via a [POST /accounts](/docs/api-kling-v1/post-kling-accounts) request. ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **204** **204 No Content** Account successfully deleted. **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** Account configuration not found. ##### Examples **Curl** ``` bash curl -X DELETE https://api.useapi.net/v1/kling/accounts/<email> \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const apiUrl = `https://api.useapi.net/v1/kling/accounts/${email}`; const response = await fetch(apiUrl, { method: "DELETE", headers: { "Authorization": `Bearer ${token}`, }, }); console.log("response", {status: response.status, statusText: response.statusText}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured account email" apiUrl = f"https://api.useapi.net/v1/kling/accounts/{email}" headers = { "Authorization" : f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers) print(response.status_code, response.reason) ``` === URL: https://useapi.net/docs/api-kling-v1/del-kling-assets-uploaded === Document URL: https://useapi.net/docs/api-kling-v1/del-kling-assets-uploaded --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> assets/uploaded description: "Delete one or more uploaded assets from your Kling account via DELETE assets/uploaded in the useapi.net Kling API v1 — deleted assets cannot be recovered." parent: Kling API nav_order: 202 --- ## Delete uploaded Kling assets May 6, 2026 (November 16, 2026) --- This endpoint deletes one or more assets that you previously uploaded to your Kling account via [POST /assets](/docs/api-kling-v1/post-kling-assets). Deleted assets cannot be recovered. To delete generated assets (outputs), use [DELETE /tasks/`task_id`](/docs/api-kling-v1/del-kling-tasks-task_id) instead. > **https://api.useapi.net/v1/kling/assets/uploaded/?email=`email`&id=`id`** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `email` is **required** — the previously configured account email (see [POST /accounts](/docs/api-kling-v1/post-kling-accounts)). - `id` is **required** — the uploaded asset ID, or a comma-separated list of up to 10 numeric IDs. Asset IDs are returned by [GET /assets/uploaded](/docs/api-kling-v1/get-kling-assets-uploaded) in the `id` field of each item in `uploadAssetsList`. ##### Responses **200** **200 OK** ```json { "deleted": 1, "ids": ["869218167527833688"] } ``` The response indicates how many assets were deleted and their IDs. **400** **400 Bad Request** ```json { "error": "Parameter id (...) must be a numeric string or a comma-separated list of up to 10 numeric strings" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model A successful delete answers with the number of uploaded assets deleted and their ids. <details markdown="block" class="model-details"> <summary>The deleted uploads, field by field</summary> ```typescript { // TypeScript, all fields are optional deleted: number // Number of uploaded assets deleted ids: string[] // Array of deleted asset IDs } ``` </details> ##### Examples **Curl** ``` bash curl -X DELETE "https://api.useapi.net/v1/kling/assets/uploaded/?email=user@example.com&id=869218167527833688" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const id = "869218167527833688"; // single id, or "id1,id2,id3" up to 10 const apiUrl = `https://api.useapi.net/v1/kling/assets/uploaded/?email=${email}&id=${id}`; const response = await fetch(apiUrl, { method: "DELETE", headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured account email" id = "869218167527833688" # single id, or "id1,id2,id3" up to 10 apiUrl = f"https://api.useapi.net/v1/kling/assets/uploaded/?email={email}&id={id}" headers = { "Authorization" : f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-kling-v1/del-kling-avatars-avatarId === Document URL: https://useapi.net/docs/api-kling-v1/del-kling-avatars-avatarId --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> avatars/<code>avatarId</code> description: "Delete a personal Kling avatar by ID via DELETE avatars/avatarId in the useapi.net Kling API v1 — system template avatars cannot be deleted." parent: Kling API nav_order: 465 --- ## Delete avatar January 12, 2026 (November 16, 2026) --- This endpoint deletes a specific avatar by its ID. Use [GET /avatars](/docs/api-kling-v1/get-kling-avatars) to list your avatars and get their IDs. Note: You can only delete personal avatars created via [POST /avatars](/docs/api-kling-v1/post-kling-avatars). System template avatars cannot be deleted. > **https://api.useapi.net/v1/kling/avatars/`avatarId`?...** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Path Parameters - `avatarId` is **required**, the avatar ID to delete. ##### Query Parameters - `email` is optional with one [account](/docs/api-kling-v1/get-kling-accounts). With more than one, pass the `email` of the account that created the avatar: without it, the request goes to one of your accounts (`429` while every account is at its `maxJobs`) and may not find the avatar. ##### Responses **200** **200 OK** ```json { "deleted": null } ``` A `null` value indicates successful deletion. **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** ```json { "error": "<error message>" } ``` ##### Model A successful delete answers with `deleted` set to `null`. <details markdown="block" class="model-details"> <summary>The delete result, field by field</summary> ```typescript { // TypeScript deleted: null // null indicates success } ``` </details> ##### Examples **Curl** ``` bash curl -X DELETE "https://api.useapi.net/v1/kling/avatars/123456789012?email=user@example.com" \ -H "Authorization: Bearer ..." ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const avatarId = "123456789012"; const apiUrl = `https://api.useapi.net/v1/kling/avatars/${avatarId}?email=${email}`; const response = await fetch(apiUrl, { method: "DELETE", headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured account email" avatarId = "123456789012" apiUrl = f"https://api.useapi.net/v1/kling/avatars/{avatarId}?email={email}" headers = { "Authorization" : f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-kling-v1/del-kling-elements-elementId === Document URL: https://useapi.net/docs/api-kling-v1/del-kling-elements-elementId --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> elements/<code>elementId</code> description: "Delete a saved character or object element by ID via DELETE elements/elementId in the useapi.net Kling API v1." parent: Kling API nav_order: 428 --- ## Delete element January 12, 2026 (November 16, 2026) --- This endpoint deletes a specific element by its ID. Use [GET /elements](/docs/api-kling-v1/get-kling-elements) to list your elements and get their IDs. > **https://api.useapi.net/v1/kling/elements/`elementId`?...** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Path Parameters - `elementId` is **required**, the element ID to delete. ##### Query Parameters - `email` is optional with one [account](/docs/api-kling-v1/get-kling-accounts). With more than one, pass the `email` of the account that created the element: without it, the request goes to one of your accounts (`429` while every account is at its `maxJobs`) and may not find the element. ##### Responses **200** **200 OK** ```json { "deleted": 1 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** ```json { "error": "<error message>" } ``` ##### Model A successful delete answers with a numeric `deleted` field, for example `1`. <details markdown="block" class="model-details"> <summary>The delete result, field by field</summary> ```typescript { // TypeScript deleted: number } ``` </details> ##### Examples **Curl** ``` bash curl -X DELETE "https://api.useapi.net/v1/kling/elements/u_123456789012345?email=user@example.com" \ -H "Authorization: Bearer ..." ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const elementId = "u_123456789012345"; const apiUrl = `https://api.useapi.net/v1/kling/elements/${elementId}?email=${email}`; const response = await fetch(apiUrl, { method: "DELETE", headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured account email" elementId = "u_123456789012345" apiUrl = f"https://api.useapi.net/v1/kling/elements/{elementId}?email={email}" headers = { "Authorization" : f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-kling-v1/del-kling-scheduler-task_id === Document URL: https://useapi.net/docs/api-kling-v1/del-kling-scheduler-task_id --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> scheduler/`task_id` description: "Cancel API tracking for a running task via DELETE scheduler/task_id in the useapi.net Kling API v1 — Kling still executes it, but the API stops monitoring progress." parent: Kling API nav_order: 520 --- ## Cancel a running task April 18, 2025 --- This endpoint cancels a running API task from being tracked by the scheduler. The task will still be executed by Kling, but the API will no longer track its progress. > **https://api.useapi.net/v1/kling/scheduler/`task_id`** The `task_id` value should be a numeric identifier of the task you want to cancel. You can get task IDs from [GET /scheduler](/docs/api-kling-v1/get-kling-scheduler). ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **204** **204 No Content** Task was successfully canceled. **400** **400 Bad Request** ```json { "error": "Error ..." } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** ```json { "error": "Unable to locate running task_id 123456789" } ``` ##### Examples **Curl** ``` bash curl -X DELETE "https://api.useapi.net/v1/kling/scheduler/123456789" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const taskId = "123456789"; const apiUrl = `https://api.useapi.net/v1/kling/scheduler/${taskId}`; const response = await fetch(apiUrl, { method: "DELETE", headers: { "Authorization": `Bearer ${token}`, }, }); console.log("response", {status: response.status, statusText: response.statusText}); ``` **Python** ``` python import requests token = "API token" task_id = "123456789" apiUrl = f"https://api.useapi.net/v1/kling/scheduler/{task_id}" headers = { "Authorization" : f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers) print(response.status_code, response.reason) ``` === URL: https://useapi.net/docs/api-kling-v1/del-kling-tasks-task_id === Document URL: https://useapi.net/docs/api-kling-v1/del-kling-tasks-task_id --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> tasks/`task_id` description: "Permanently delete a Kling task and all its associated output works by task ID via DELETE tasks/task_id in the useapi.net Kling API v1." parent: Kling API nav_order: 307 --- ## Delete Kling Task October 7, 2025 (November 16, 2026) --- This endpoint deletes a specific task and all its associated works (outputs) by task ID. Deleted tasks and works cannot be recovered. If the task has multiple works (e.g., multiple variations), all of them will be deleted. > **https://api.useapi.net/v1/kling/tasks/`task_id`?…** The `task_id` value should be a numeric identifier of the task you want to delete. ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `email` is optional when only one [account](/docs/api-kling-v1/get-kling-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. ##### Responses **200** **200 OK** ```json { "deleted": 1, "workIds": [987654321] } ``` The response indicates how many works were deleted and their IDs. **400** **400 Bad Request** ```json { "error": "Invalid task_id parameter" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** Task was not found or has no associated works. ```json { "error": "No works found for task 123456789" } ``` ##### Model A successful delete answers with how many of the task's works (outputs) were deleted and their `workIds`. <details markdown="block" class="model-details"> <summary>The deleted works, field by field</summary> ```typescript { // TypeScript, all fields are optional deleted: number // Number of works deleted workIds: number[] // Array of deleted work IDs } ``` </details> ##### Examples **Curl** ``` bash curl -X DELETE "https://api.useapi.net/v1/kling/tasks/123456789?email=user@example.com" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const taskId = "123456789"; const apiUrl = `https://api.useapi.net/v1/kling/tasks/${taskId}?email=${email}`; const response = await fetch(apiUrl, { method: "DELETE", headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured account email" task_id = "123456789" apiUrl = f"https://api.useapi.net/v1/kling/tasks/{task_id}?email={email}" headers = { "Authorization" : f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-kling-v1/del-kling-videos-voices === Document URL: https://useapi.net/docs/api-kling-v1/del-kling-videos-voices --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> videos/voices description: "Delete a Kling 4.0 voice you saved, by its numeric voiceId, via DELETE videos/voices in the useapi.net Kling API v1." parent: Kling API nav_order: 329 --- ## Delete a Saved Kling 4.0 Voice October 15, 2026 (November 16, 2026) --- This endpoint deletes a voice you saved with [POST /videos/voices](/docs/api-kling-v1/post-kling-videos-voices) or on kling.ai. Only saved voices (`source: USER`) can be deleted. Find the voice `id` with [GET /videos/voices](/docs/api-kling-v1/get-kling-videos-voices). > **https://api.useapi.net/v1/kling/videos/voices?voiceId=`voiceId`&email=`email`** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `voiceId` is **required**, the numeric `id` of a saved voice from [GET /videos/voices](/docs/api-kling-v1/get-kling-videos-voices). - `email` is optional when only one [account](/docs/api-kling-v1/get-kling-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. Use the account that saved the voice. ##### Responses **200** **200 OK** ```json { "deleted": true } ``` **400** **400 Bad Request** The `voiceId` is not a numeric voice id. ```json { "error": "Parameter voiceId (my-voice) has incorrect format" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** Kling did not delete the voice, for example because it is not a voice saved to this account. ```json { "error": "Voice 301234567890 was not deleted" } ``` ##### Model A successful delete answers with `deleted: true`, and a failed one with an `error` message. <details markdown="block" class="model-details"> <summary>The delete result, field by field</summary> ```typescript { // TypeScript, all fields are optional deleted: boolean error: string } ``` </details> ##### Examples **Curl** ``` bash curl -X DELETE "https://api.useapi.net/v1/kling/videos/voices?voiceId=301234567890&email=user@example.com" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const voiceId = "301234567890"; const apiUrl = `https://api.useapi.net/v1/kling/videos/voices?voiceId=${voiceId}&email=${encodeURIComponent(email)}`; const response = await fetch(apiUrl, { method: "DELETE", headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured account email" voiceId = "301234567890" apiUrl = "https://api.useapi.net/v1/kling/videos/voices" headers = { "Authorization" : f"Bearer {token}" } params = { "voiceId": voiceId, "email": email } response = requests.delete(apiUrl, headers=headers, params=params) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-kling-v1/get-kling-accounts-email === Document URL: https://useapi.net/docs/api-kling-v1/get-kling-accounts-email --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts/`email` description: "Retrieve configuration and credit balance for a specific Kling account by email via GET accounts/email in the useapi.net Kling API v1." parent: Kling API nav_order: 120 --- ## Retrieve Kling API account configuration and balance for `email` April 18, 2025 (November 16, 2026) --- This endpoint retrieves the configuration and balance information for a specific Kling account. > **https://api.useapi.net/v1/kling/accounts/`email`** The `email` value should correspond to an account configured previously via a [POST /accounts](/docs/api-kling-v1/post-kling-accounts) request. ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** ```json { "email": "user@example.com", "authMode": "password", "session": { "userId": 12345, "ExpireTime": 123456789, "ExpireTimeUTC": "2025-01-01T12:13:14.000Z" }, "maxJobs": 5, "password": "…secured…", "balance": { "points": [ { "orderId": "123456789", "type": "plan", "amount": 66000, "balance": 56000, "startTime": 123456789, "endTime": 123456789 } ], "tickets": [], "nextApplyTime": 123456789, "total": 56000 } } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** Account configuration not found. To create configuration use [POST /accounts](/docs/api-kling-v1/post-kling-accounts). ##### Model The account's settings, its Kling session with its expiry time, and its balance, with the total in `balance.total`. <details markdown="block" class="model-details"> <summary>The account's settings, session and balance, field by field</summary> ```typescript { // TypeScript, all fields are optional email: string authMode: "password" | "passToken" session: { userId: number ExpireTime: number ExpireTimeUTC: string } maxJobs: number password: string balance: { points: Array<{ orderId: string type: string amount: number balance: number startTime: number endTime: number }> tickets: Array<any> nextApplyTime: number total: number } } ``` </details> ##### Examples **Curl** ``` bash curl https://api.useapi.net/v1/kling/accounts/<email> \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const apiUrl = `https://api.useapi.net/v1/kling/accounts/${email}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured account email" apiUrl = f"https://api.useapi.net/v1/kling/accounts/{email}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-kling-v1/get-kling-accounts === Document URL: https://useapi.net/docs/api-kling-v1/get-kling-accounts --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts description: "List every Kling account connected to useapi.net, with its maxJobs and session, via GET accounts in the Kling API v1. Generation jobs are spread across these accounts." parent: Kling API nav_order: 100 --- ## Retrieve Kling API accounts configuration April 18, 2025 (November 16, 2026) --- You can connect several Kling accounts. Generation requests (video, image, avatar video and the other task-based endpoints) sent without `email` go to one of your healthy accounts that has a free job slot, picked at random, and each account runs at most its own `maxJobs` jobs at once. If every account is busy, the response is `429`. Pass `email` to pin a job to one account. Task, asset and voice calls, such as [GET tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id), [GET assets](/docs/api-kling-v1/get-kling-assets) and [GET videos/voices](/docs/api-kling-v1/get-kling-videos-voices), need `email` when you have more than one account. Element and avatar calls without `email` go to one of your accounts and may not find an item saved on another. Each endpoint page says which kind it is. See [Run several Kling accounts](/docs/api-kling-v1#run-several-kling-accounts). This endpoint retrieves the complete list of configured API accounts for Kling. > **https://api.useapi.net/v1/kling/accounts** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** ```json { "<email #1>": { "email": "<email #1>", "authMode": "password", "session": { "userId": 12345, "ExpireTime": 123456789, "ExpireTimeUTC": "2025-01-01T12:13:14.000Z" }, "maxJobs": 8, "password": "…secured…", "addedVia": "password", "created": "2026-11-14T23:04:11.000Z", "lastAdded": "2026-11-14T23:04:11.000Z" }, "<email #2>": { "email": "<email #2>", "authMode": "passToken", "session": { "userId": 67890, "ExpireTime": 123456789, "ExpireTimeUTC": "2025-01-01T12:13:14.000Z" }, "maxJobs": 3, "password": "…secured…", "addedVia": "setup-browser", "created": "2026-11-14T22:10:45.000Z", "lastAdded": "2026-11-14T22:10:45.000Z" } } ``` `authMode` is `password` for accounts added with email + password, or `passToken` for accounts added through the automated setup or connected from the browser (see [Setup Kling](/docs/start-here/setup-kling)). The `passToken`, `did`, and password values are never returned. `addedVia` says how the account was added: `setup-browser` (the automated setup), `connect` (the connect tool or `passToken`, `did` and `userId` sent to [POST /accounts](/docs/api-kling-v1/post-kling-accounts)) or `password` (email and password). `created` is when the account was first added and `lastAdded` when it was last added or updated. Accounts added before November 14, 2026 have no `addedVia` or `created`. **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** Configuration not found. To create configuration use [POST /accounts](/docs/api-kling-v1/post-kling-accounts). ##### Model An object keyed by account email, each value holding that account's settings, session and `maxJobs`. <details markdown="block" class="model-details"> <summary>Every account's settings, keyed by email, field by field</summary> ```typescript { // TypeScript, all fields are optional [email: string]: { email: string authMode: "password" | "passToken" session: { userId: number ExpireTime: number ExpireTimeUTC: string } maxJobs: number password: string addedVia: "setup-browser" | "connect" | "password" created: string lastAdded: string error: string } } ``` </details> ##### Examples **Curl** ``` bash curl https://api.useapi.net/v1/kling/accounts \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = "https://api.useapi.net/v1/kling/accounts"; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" apiUrl = "https://api.useapi.net/v1/kling/accounts" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-kling-v1/get-kling-assets-download === Document URL: https://useapi.net/docs/api-kling-v1/get-kling-assets-download --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> assets/download description: "Download watermark-free assets from a paid Kling account by work ID via GET assets/download in the useapi.net Kling API v1." parent: Kling API nav_order: 205 --- ## Download Kling assets without watermarks April 18, 2025 (November 16, 2026) --- This endpoint allows you to download assets from your *paid* Kling account without watermarks by providing the work IDs. > **https://api.useapi.net/v1/kling/assets/download?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `email` is optional when only one [account](/docs/api-kling-v1/get-kling-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `workIds` is **required**, specify the IDs of works to download. Can be a single numeric string or a comma-separated list of numeric strings (e.g., "123456789" or "123456789,987654321"). These IDs can be obtained from the `workId` field in the `works` array returned by the [GET /assets](/docs/api-kling-v1/get-kling-assets), [GET /tasks](/docs/api-kling-v1/get-kling-tasks) or [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) endpoint. - `fileTypes` is optional, comma-separated file types to download (e.g., "MP4" or "MP4,MOV"). Supported file types: `MP4`, `MOV`, `MP3`, `WAV`, `PNG`. A video downloads as `MP4` or `MOV`, an image as `PNG`. If omitted, the first type the work has is used: `MP4` for a video, `PNG` for an image, `MP3` for audio. A type the work does not have answers `400`. **Note:** A single `workId` with a single file type returns a link to the file itself, ready at once. Several `workIds` or several file types return a link to a `.zip`. ##### Responses **200** **200 OK** ```json { "cdnUrl": "https://v15-kling.klingai.com/klingai-stream-sgp/kling/download/MzI0MTU5…?x-kcdn-pid=112372", "status": "success", "fileName": "kling_20261017_Text_to_Video_A_golden_r_1499_0.mp4", "streaming": false, "fileSize": null } ``` **400** **400 Bad Request** ```json { "error": "Invalid parameters" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model The `cdnUrl` of the file without watermarks, or of a .zip for several works or file types, with its file name. <details markdown="block" class="model-details"> <summary>The download link, field by field</summary> ```typescript { // TypeScript cdnUrl: string // URL of the file, or of a .zip for several workIds or file types status: string // "success" when successful fileName: string // e.g. kling_20261017_Text_to_Video_..._0.mp4, or download_result.zip streaming: boolean fileSize: number | null } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/kling/assets/download?email=user@example.com&workIds=123456789,987654321" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const workIds = "123456789,987654321"; const apiUrl = `https://api.useapi.net/v1/kling/assets/download?email=${email}&workIds=${workIds}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured account email" workIds = "123456789,987654321" apiUrl = f"https://api.useapi.net/v1/kling/assets/download?email={email}&workIds={workIds}" headers = { "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-kling-v1/get-kling-assets-uploaded === Document URL: https://useapi.net/docs/api-kling-v1/get-kling-assets-uploaded --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> assets/uploaded description: "List assets you uploaded to your Kling account (distinct from generated outputs) via GET assets/uploaded in the useapi.net Kling API v1." parent: Kling API nav_order: 201 --- ## Retrieve uploaded Kling assets August 8, 2025 (November 16, 2026) --- This endpoint retrieves assets that you have uploaded to your Kling account, as opposed to generated assets. > **https://api.useapi.net/v1/kling/assets/uploaded/?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `email` is optional when only one [account](/docs/api-kling-v1/get-kling-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `pageNum` is optional, specify the page number to retrieve. Default `1`. - `pageSize` is optional, specify the number of items per page. Default `20`. - `contentType` is optional, type of content to retrieve. Supported values: `video`, `image`, or `audio`. - `fileName` is optional, filter by file name (keyword search). - `sort` is optional, sort direction by upload time. Supported values: `asc`, `desc`. Default `desc`. ##### Responses **200** **200 OK** ```json { "uploadAssetsList": [ { "id": "1234567890", "name": "abcdef12345.mp4", "userId": 12345, "contentType": "video", "resource": { "resource": "https://v15-kling.klingai.com/….mp4", "height": 1080, "width": 720, "duration": 9040, "resourceKey": "" }, "cover": { "resource": "https://v15-kling.klingai.com/…", "height": 1080, "width": 720, "duration": 0, "resourceKey": "" }, "createTime": 1754630473303, "updateTime": 1754630473303, "favored": false, "extraInfo": "{}", "entrance": "" }, { "id": "1234567890", "name": "abcdef12345.mp4", "userId": 12345, "contentType": "image", "resource": { "resource": "https://v15-kling.klingai.com/…", "height": 1080, "width": 720, "duration": 0, "resourceKey": "" }, "cover": { "resource": "", "height": 1, "width": 1, "duration": 0, "resourceKey": "" }, "createTime": 1754627757354, "updateTime": 1754627757354, "favored": false, "extraInfo": "{}", "entrance": "" } ] } ``` **400** **400 Bad Request** ```json { "error": "Invalid parameters" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model Your uploaded videos, images and audio in `uploadAssetsList`, each with its `id`, URL, size in pixels and duration. <details markdown="block" class="model-details"> <summary>The list of uploaded assets, field by field</summary> ```typescript { // TypeScript, all fields are optional uploadAssetsList: { id: string // Unique asset identifier name: string // Generated unique filename userId: number // User ID who uploaded the asset contentType: string // "video", "image", or "audio" resource: { resource: string // URL of the uploaded asset height: number // Height in pixels width: number // Width in pixels duration: number // Duration in milliseconds (0 for images) resourceKey: string // Resource key (usually empty) } cover: { resource: string // URL of cover image (empty for images) height: number // Cover height (1 for images without cover) width: number // Cover width (1 for images without cover) duration: number // Cover duration (always 0) resourceKey: string // Cover resource key (usually empty) } createTime: number // Upload timestamp updateTime: number // Last update timestamp favored: boolean // Whether asset is favorited extraInfo: string // Extra information as JSON string entrance: string // Entry point (usually empty) }[] } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/kling/assets/uploaded/?contentType=image" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = `https://api.useapi.net/v1/kling/assets/uploaded/?contentType=image`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" apiUrl = f"https://api.useapi.net/v1/kling/assets/uploaded/?contentType=image" headers = { "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-kling-v1/get-kling-assets === Document URL: https://useapi.net/docs/api-kling-v1/get-kling-assets --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> assets description: "List generated assets (videos, images) from your Kling account via GET assets in the useapi.net Kling API v1 — pagination and filtering supported." parent: Kling API nav_order: 200 --- ## Retrieve Kling assets April 18, 2025 (November 16, 2026) --- This endpoint retrieves generated assets from your Kling account. > **https://api.useapi.net/v1/kling/assets/?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `email` is optional when only one [account](/docs/api-kling-v1/get-kling-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `pageNum` is optional, specify the page number to retrieve. Default `1`. - `pageSize` is optional, specify the number of items per page. Default `40`. - `contentType` is optional, type of content to retrieve. Supported values: `video`, `image`, or `audio`. - `sort` is optional, sort direction by creation time. Supported values: `asc`, `desc`. Default `desc`. ##### Responses **200** **200 OK** ```json { "limitations": [ { "type": "mmu_txt2img_aiweb", "remaining": 10000, "limit": 10000 }, { "type": "m2v_txt2video_hq", "remaining": 10000, "limit": 10000 }, { "type": "m2v_img2video_hq", "remaining": 10000, "limit": 10000 } ], "history": [ { "works": [ { "workId": 123456789, "workItemId": 0, "taskId": 123456789, "userId": 12345, "type": "m2v_img2video_hq", "status": 99, "contentType": "video", "resource": { "resource": "https://s21-kling.klingai.com/....mp4", "height": 1268, "width": 724, "duration": 5041, "resourceKey": "" }, "cover": { "resource": "https://s21-kling.klingai.com/....jpg", "height": 1268, "width": 724, "duration": 0, "resourceKey": "" }, "starNum": 0, "cloneCount": 0, "reportNum": 0, "createTime": 1744858514515, "taskInfo": { "type": "m2v_img2video_hq", "inputs": [ { "name": "input", "inputType": "URL", "token": null, "blobStorage": null, "url": "https://s21-kling.klingai.com/....jpg", "cover": null, "fromWorkId": null, "fromUploadId": null } ], "arguments": [ { "name": "prompt", "value": "A person dancing" }, { "name": "negative_prompt", "value": "" }, { "name": "duration", "value": "5" }, { "name": "kling_version", "value": "2.0" } ], "extraArgs": {}, "callbackPayloads": [], "scene": "NORMAL_CREATION" }, "selfAttitude": "unknown", "selfComment": { "rate": 0, "tags": [], "content": "", "prompts": [] }, "favored": false, "starred": false, "publishStatus": "unpublished", "deleted": false, "publishTime": 0, "submitTime": 1744858514515, "lipSyncStatus": 99, "downloadInfo": { "fileTypes": [ { "type": "MP4", "watermark": true } ] }, "allowPublish": true } ], "task": { "id": 123456789, "userId": 12345, "type": "m2v_img2video_hq", "scene": "NORMAL_CREATION", "status": 99, "taskInfo": { "type": "m2v_img2video_hq", "inputs": [ { "name": "input", "inputType": "URL", "token": null, "blobStorage": null, "url": "https://s21-kling.klingai.com/....jpg", "cover": null, "fromWorkId": null, "fromUploadId": null } ], "arguments": [ { "name": "prompt", "value": "A person dancing" }, { "name": "negative_prompt", "value": "" }, { "name": "duration", "value": "5" }, { "name": "kling_version", "value": "2.0" } ], "extraArgs": {}, "callbackPayloads": [], "scene": "NORMAL_CREATION" }, "favored": false, "deleted": false, "viewed": true, "createTime": 1744858514499, "updateTime": 1744858823172, "viewTime": 1744916388016 }, "etaTime": 0, "etaTimeOverSla": false, "queuingEtaTime": 0, "originEtaTime": 0, "originQueuingEtaTime": 0, "currentTimestamp": 1744955215247 } ], "userPoints": { "points": [ { "orderId": "123456789", "type": "plan", "amount": 300000, "balance": 190500, "startTime": 1744081611119, "endTime": 1746760011119 } ], "total": 190500 }, "userTickets": { "ticket": [ { "orderId": "123456789", "type": "priority", "packageType": "reward", "amount": 1, "balance": 1, "startTime": 1744046060883, "endTime": 1746724460883 }, { "orderId": "123456789", "type": "extend", "packageType": "reward", "amount": 2, "balance": 2, "startTime": 1744046060883, "endTime": 1746724460883 }, { "orderId": "123456789", "type": "hq_5s", "packageType": "reward", "amount": 3, "balance": 3, "startTime": 1744046060883, "endTime": 1746724460883 } ] } } ``` **400** **400 Bad Request** ```json { "error": "Invalid parameters" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model Your generated videos and images (works), grouped by task in `history`, with the account's limits and balance. <details markdown="block" class="model-details"> <summary>The generated works by task, with limits and balance, field by field</summary> To download assets without watermarks, use the [GET /assets/download](/docs/api-kling-v1/get-kling-assets-download) endpoint with the workId values found in the `works` array of the response. ```typescript { // TypeScript, all fields are optional limitations: { type: string remaining: number limit: number }[] history: { works: { workId: number workItemId: number taskId: number userId: number type: string status: number contentType: string resource: { resource: string height: number width: number duration: number resourceKey: string } cover: { resource: string height: number width: number duration: number resourceKey: string } starNum: number cloneCount: number reportNum: number createTime: number taskInfo: { type: string inputs: { name: string inputType: string token: string | null blobStorage: string | null url: string cover: string | null fromWorkId: number | null fromUploadId: number | null }[] arguments: { name: string value: string }[] extraArgs: Record<string, any> callbackPayloads: any[] scene: string } selfAttitude: string selfComment: { rate: number tags: any[] content: string prompts: any[] } favored: boolean starred: boolean publishStatus: string deleted: boolean publishTime: number submitTime: number lipSyncStatus: number downloadInfo: { fileTypes: { type: string watermark: boolean }[] } allowPublish: boolean }[] task: { id: number userId: number type: string scene: string status: number taskInfo: { type: string inputs: { name: string inputType: string token: string | null blobStorage: string | null url: string cover: string | null fromWorkId: number | null fromUploadId: number | null }[] arguments: { name: string value: string }[] extraArgs: Record<string, any> callbackPayloads: any[] scene: string } favored: boolean deleted: boolean viewed: boolean createTime: number updateTime: number viewTime: number } etaTime: number etaTimeOverSla: boolean queuingEtaTime: number originEtaTime: number originQueuingEtaTime: number currentTimestamp: number }[] userPoints: { points: { orderId: string type: string amount: number balance: number startTime: number endTime: number }[] total: number } userTickets: { ticket: { orderId: string type: string packageType: string amount: number balance: number startTime: number endTime: number }[] } } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/kling/assets/?email=user@example.com" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const apiUrl = `https://api.useapi.net/v1/kling/assets/?email=${email}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured account email" apiUrl = f"https://api.useapi.net/v1/kling/assets/?email={email}" headers = { "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-kling-v1/get-kling-avatars === Document URL: https://useapi.net/docs/api-kling-v1/get-kling-avatars --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> avatars description: "List personal or system-template Kling avatars available for lip-sync video generation via GET avatars in the useapi.net Kling API v1." parent: Kling API nav_order: 450 --- ## List avatars January 12, 2026 (November 16, 2026) --- This endpoint retrieves a list of avatars. You can list either your personal saved avatars or browse system-provided templates. Avatars are digital characters that can be animated with lip-sync using [POST /avatars/video](/docs/api-kling-v1/post-kling-avatars-video). > **https://api.useapi.net/v1/kling/avatars/?...** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `email` is optional. Without it, one of your [accounts](/docs/api-kling-v1/get-kling-accounts) is used (`429` while every account is at its `maxJobs`). Personal avatars belong to the account that saved them, so pass `email` to list a specific account's avatars. - `type` is optional, the type of avatars to list. Supported values: `personal` (default), `templates`. - `personal`: Your saved avatars created via [POST /avatars](/docs/api-kling-v1/post-kling-avatars) - `templates`: System-provided avatar templates ##### Responses **200** **200 OK** **Personal avatars response (type=personal):** ```json [ { "id": "123456789012", "nickname": "My Fashion Avatar", "prompt": "Elegant woman in professional attire", "scene": "advertising_marketing", "imageResources": [ { "url": "https://s21-kling.klingai.com/ai-platform/.../avatar.jpg", "sourceFrom": 2 } ], "ttsSpeaker": "speaker_id_123", "ttsSpeed": "1", "ttsEmotionKey": "neutral", "createTime": 1736640000000, "updateTime": 1736640000000 } ] ``` **Templates response (type=templates):** ```json [ { "id": "12345", "name": "Business Woman", "imageResources": [ { "url": "https://s21-kling.klingai.com/ai-platform/.../template.jpg" } ], "prompt": "Professional businesswoman in formal attire" } ] ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model A list of avatars, each with its `id`, name, prompt, image URLs and text-to-speech settings. <details markdown="block" class="model-details"> <summary>The list of avatars, field by field</summary> ```typescript Array<{ id: string nickname?: string name?: string prompt: string scene?: string imageResources: { url: string sourceFrom?: number }[] ttsSpeaker?: string ttsSpeed?: string ttsEmotionKey?: string createTime?: number updateTime?: number }> ``` </details> ##### Avatar ID Format - **Personal avatars** have long IDs (more than 8 digits), e.g., `123456789012` - **Template avatars** have short IDs (8 digits or fewer), e.g., `12345` This distinction is used internally when generating avatar videos. ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/kling/avatars/?email=user@example.com&type=personal" \ -H "Accept: application/json" \ -H "Authorization: Bearer ..." ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const apiUrl = `https://api.useapi.net/v1/kling/avatars/?email=${email}&type=personal`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured account email" apiUrl = f"https://api.useapi.net/v1/kling/avatars/?email={email}&type=personal" headers = { "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-kling-v1/get-kling-elements-elementId === Document URL: https://useapi.net/docs/api-kling-v1/get-kling-elements-elementId --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> elements/<code>elementId</code> description: "Retrieve details for a saved character or object element by ID via GET elements/elementId in the useapi.net Kling API v1." parent: Kling API nav_order: 424 --- ## Retrieve element by ID January 12, 2026 (November 16, 2026) --- This endpoint retrieves details for a specific element by its ID. Use [GET /elements](/docs/api-kling-v1/get-kling-elements) to list all your elements and get their IDs. > **https://api.useapi.net/v1/kling/elements/`elementId`?...** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Path Parameters - `elementId` is **required**, the element ID to retrieve. ##### Query Parameters - `email` is optional with one [account](/docs/api-kling-v1/get-kling-accounts). With more than one, pass the `email` of the account that created the element: without it, the request goes to one of your accounts (`429` while every account is at its `maxJobs`) and may not find the element. ##### Responses **200** **200 OK** ```json { "id": "u_123456789012345", "name": "FashionLady ABC12", "userId": 12345678, "type": "IMAGE", "description": "Elegant woman in red dress", "cover": { "resource": "https://s21-kling.klingai.com/ai-platform/.../cover.jpg", "width": 768, "height": 1365, "resourceKey": "cover", "cover": true, "slotKey": "" }, "resources": [ { "resource": ".../cover.jpg", "resourceKey": "cover", "cover": true, "slotKey": "" }, { "resource": ".../side.png", "resourceKey": "secondary", "cover": false, "slotKey": "side" }, { "resource": ".../back.png", "resourceKey": "secondary", "cover": false, "slotKey": "back" }, { "resource": ".../top.png", "resourceKey": "secondary", "cover": false, "slotKey": "topView" } ], "tagList": [], "favored": false, "official": false, "createTime": 1736640000000, "updateTime": 1736640000000 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** ```json { "error": "<error message>" } ``` ##### Model One element with its `type`, name, description, cover, resources, tags and assigned voice. <details markdown="block" class="model-details"> <summary>The element and its resources, field by field</summary> ```typescript { // TypeScript, all fields are optional id: string name: string userId: number type: 'IMAGE' | 'VIDEO' description: string cover: { resource: string width: number height: number resourceKey: 'cover' | 'secondary' | 'video' cover: boolean slotKey: string } resources: { resource: string width: number height: number resourceKey: 'cover' | 'secondary' | 'video' cover: boolean slotKey: string voice: { id: number name: string official: boolean resource: object } }[] tagList: object[] voice: { id: number name: string official: boolean resource: object } currentVersion: number createTime: number updateTime: number favored: boolean official: boolean } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/kling/elements/u_123456789012345?email=user@example.com" \ -H "Accept: application/json" \ -H "Authorization: Bearer ..." ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const elementId = "u_123456789012345"; const apiUrl = `https://api.useapi.net/v1/kling/elements/${elementId}?email=${email}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured account email" elementId = "u_123456789012345" apiUrl = f"https://api.useapi.net/v1/kling/elements/{elementId}?email={email}" headers = { "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-kling-v1/get-kling-elements-tags === Document URL: https://useapi.net/docs/api-kling-v1/get-kling-elements-tags --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> elements/tags description: "Retrieve available category tags for organizing and filtering elements via GET elements/tags in the useapi.net Kling API v1." parent: Kling API nav_order: 420 --- ## Retrieve available element tags January 12, 2026 (November 16, 2026) --- This endpoint retrieves available element category tags. Tags are used to categorize elements when creating them via [POST /elements](/docs/api-kling-v1/post-kling-elements) and for filtering when listing elements via [GET /elements](/docs/api-kling-v1/get-kling-elements). > **https://api.useapi.net/v1/kling/elements/tags/?...** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `email` is optional. Without it, one of your [accounts](/docs/api-kling-v1/get-kling-accounts) is used to read the list (`429` while every account is at its `maxJobs`). ##### Responses **200** **200 OK** ```json { "tagList": [ { "id": "o_102", "tagKey": "character", "name": "Characters", "official": true, "type": "element" }, { "id": "o_103", "tagKey": "animal", "name": "Animals", "official": true, "type": "element" }, { "id": "o_104", "tagKey": "prop", "name": "Items", "official": true, "type": "element" }, { "id": "o_105", "tagKey": "costume", "name": "Costumes", "official": true, "type": "element" }, { "id": "o_106", "tagKey": "scene", "name": "Scenes", "official": true, "type": "element" }, { "id": "o_107", "tagKey": "effect", "name": "Effects", "official": true, "type": "element" }, { "id": "o_108", "tagKey": "others", "name": "Others", "official": true, "type": "element" } ] } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model A list of element category tags in `tagList`, each with its `id`, `tagKey` and name. <details markdown="block" class="model-details"> <summary>The list of element tags, field by field</summary> ```typescript { // TypeScript, all fields are optional tagList: { id: string tagKey: string name: string official: boolean type: string }[] } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/kling/elements/tags/?email=user@example.com" \ -H "Accept: application/json" \ -H "Authorization: Bearer ..." ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const apiUrl = `https://api.useapi.net/v1/kling/elements/tags/?email=${email}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured account email" apiUrl = f"https://api.useapi.net/v1/kling/elements/tags/?email={email}" headers = { "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-kling-v1/get-kling-elements-voices === Document URL: https://useapi.net/docs/api-kling-v1/get-kling-elements-voices --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> elements/voices description: "List official voices assignable to character-tagged elements via GET elements/voices in the useapi.net Kling API v1." parent: Kling API nav_order: 422 --- ## Retrieve available element voices February 9, 2026 (November 16, 2026) --- This endpoint retrieves available official voices for elements. Voices can be assigned to elements when creating them via [POST /elements](/docs/api-kling-v1/post-kling-elements). Only elements with the `character` tag support voice assignment. > **https://api.useapi.net/v1/kling/elements/voices/?...** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `email` is optional. Without it, one of your [accounts](/docs/api-kling-v1/get-kling-accounts) is used to read the list (`429` while every account is at its `maxJobs`). ##### Responses **200** **200 OK** ```json { "voices": [ { "id": 1, "name": "Vivid Girl" }, { "id": 2, "name": "Gentle Lady" }, { "id": 3, "name": "Charming Uncle" } ] } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model A list of Kling's official voices for elements, each with its `id` and `name`. <details markdown="block" class="model-details"> <summary>The list of element voices, field by field</summary> ```typescript { // TypeScript, all fields are optional voices: { id: number name: string }[] } ``` Use the `id` or `name` value in the `voice` parameter when creating VIDEO elements via [POST /elements](/docs/api-kling-v1/post-kling-elements). </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/kling/elements/voices/?email=user@example.com" \ -H "Accept: application/json" \ -H "Authorization: Bearer ..." ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const apiUrl = `https://api.useapi.net/v1/kling/elements/voices/?email=${email}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured account email" apiUrl = f"https://api.useapi.net/v1/kling/elements/voices/?email={email}" headers = { "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-kling-v1/get-kling-elements === Document URL: https://useapi.net/docs/api-kling-v1/get-kling-elements --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> elements description: "List saved character and object elements reusable across Omni image and video generations via GET elements in the useapi.net Kling API v1." parent: Kling API nav_order: 422 --- ## List elements January 12, 2026 (November 16, 2026) --- This endpoint retrieves a list of your custom elements. Elements are saved character/object references that can be reused across multiple generations in [POST /images/omni](/docs/api-kling-v1/post-kling-images-omni) and [POST /videos/omni](/docs/api-kling-v1/post-kling-videos-omni) using the `@element_N` syntax. > **https://api.useapi.net/v1/kling/elements/?...** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `email` is optional. Without it, one of your [accounts](/docs/api-kling-v1/get-kling-accounts) is used (`429` while every account is at its `maxJobs`). Elements belong to the account that created them, so pass `email` to list a specific account's elements. - `pageNum` is optional, the page number to retrieve. Default: `1`. Must be `1` or greater. - `pageSize` is optional, the number of elements per page. Range: `1` to `100`. Default: `50`. - `tag` is optional, filter elements by tag. Use [GET /elements/tags](/docs/api-kling-v1/get-kling-elements-tags) to get available tags. - `official` is optional, filter to show only official/system elements. Default: `false`. - `favored` is optional, filter to show only favored elements. Default: `false`. - `sortDirection` is optional, sort order for results. Supported values: `ASC`, `DESC` (default). ##### Responses **200** **200 OK** ```json { "elementsList": [ { "id": "u_123456789012345", "name": "FashionLady ABC12", "userId": 12345678, "type": "IMAGE", "description": "Elegant woman in red dress", "cover": { "resource": "https://s21-kling.klingai.com/ai-platform/.../cover.jpg", "width": 768, "height": 1365, "resourceKey": "cover", "cover": true, "slotKey": "" }, "resources": [ { "resource": ".../cover.jpg", "resourceKey": "cover", "cover": true, "slotKey": "" }, { "resource": ".../side.png", "resourceKey": "secondary", "slotKey": "side" } ], "tagList": [], "favored": false, "official": false, "createTime": 1736640000000, "updateTime": 1736640000000 } ], "pageNum": 1, "pageSize": 50, "total": 3 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model One page of your elements in `elementsList`, with `pageNum`, `pageSize` and the `total` count. <details markdown="block" class="model-details"> <summary>The page of elements, field by field</summary> ```typescript { // TypeScript, all fields are optional elementsList: { id: string name: string userId: number type: 'IMAGE' | 'VIDEO' description: string cover: { resource: string width: number height: number resourceKey: 'cover' | 'secondary' | 'video' cover: boolean slotKey: string } resources: { resource: string width: number height: number resourceKey: 'cover' | 'secondary' | 'video' cover: boolean slotKey: string voice: { id: number name: string official: boolean resource: object } }[] tagList: object[] voice: { id: number name: string official: boolean resource: object } currentVersion: number createTime: number updateTime: number favored: boolean official: boolean }[] pageNum: number pageSize: number total: number } ``` </details> ##### Usage in Omni Endpoints Once you have element IDs, you can reference them in [POST /images/omni](/docs/api-kling-v1/post-kling-images-omni) and [POST /videos/omni](/docs/api-kling-v1/post-kling-videos-omni): ```json { "prompt": "Character @element_1 walking through a beautiful garden", "element_1": "u_123456789012345" } ``` ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/kling/elements/?email=user@example.com&pageSize=10" \ -H "Accept: application/json" \ -H "Authorization: Bearer ..." ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const apiUrl = `https://api.useapi.net/v1/kling/elements/?email=${email}&pageSize=10`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured account email" apiUrl = f"https://api.useapi.net/v1/kling/elements/?email={email}&pageSize=10" headers = { "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-kling-v1/get-kling-images-presets === Document URL: https://useapi.net/docs/api-kling-v1/get-kling-images-presets --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> images/presets description: "List the Kling Image 4.0 presets via GET images/presets in the useapi.net Kling API v1 — the styles, tones and fonts a v4 prompt names as @style:, @tone: and @font:." parent: Kling API nav_order: 311 --- ## Get Kling Image 4.0 Presets November 19, 2026 --- This endpoint lists the styles, tones and fonts of Kling Image 4.0. Name one in a [POST images/omni](/docs/api-kling-v1/post-kling-images-omni#presets-v4) prompt with `omni_version: v4`: - `@style:<id>` sets the look of the image, for example `@style:3d_cartoon_pro`. - `@tone:<id>` applies a color and lighting preset, for example `@tone:Nostalgic_Wuxia`. - `@font:<id>` sets the lettering of the quoted text that follows it, for example `@font:elegant_brush_hand "Jade Dragon"`. The lists are Kling's own and the same for every account. They are kept for an hour, so a new preset from Kling shows up within an hour. > **https://api.useapi.net/v1/kling/images/presets?...** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `email` is optional. The lists are the same for every account, so any of your [accounts](/docs/api-kling-v1/get-kling-accounts) can fetch them. ##### Responses **200** **200 OK** ```json { "styles": [ { "id": "3d_cartoon_with_exaggerated_perspective_pro", "name": "3D Cartoon with Exaggerated Perspective", "group": "3D Style", "text_to_image": true, "image_to_image": true, "sample": "https://s15-kling.klingai.com/kimg/.../sample.png" }, { "id": "ink_wash_painting_pro", "name": "Ink Wash Painting", "group": "2D Style", "text_to_image": true, "image_to_image": false, "sample": "https://s15-kling.klingai.com/kimg/.../sample.png" } ], "tones": [ { "id": "Nostalgic_Wuxia", "name": "Nostalgic Wuxia", "group": "Director Styles", "sample": "https://s15-kling.klingai.com/kimg/.../sample.png" }, { "id": "Morandi_Palette", "name": "Morandi Palette", "group": "Advanced Color", "sample": "https://s15-kling.klingai.com/kimg/.../sample.png" } ], "fonts": [ { "id": "modern_rounded_sans", "name": "Modern Rounded Sans", "languages": ["en"], "styles": ["standard"], "sample": "https://s15-kling.klingai.com/kimg/.../sample.png" } ], "updated": "2026-11-19T18:00:00.000Z" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model The styles, tones and fonts of Kling Image 4.0, each with the `id` to name in a prompt and a sample image. - `sample` is an image that shows the preset. - `text_to_image` and `image_to_image` say where Kling offers a style: for images from text, for restyling a reference image, or both. - `languages` of a font are the scripts it covers: `en`, `ja`, `ko`, `zh-Hans`, `zh-Hant`. <details markdown="block" class="model-details"> <summary>The presets, field by field</summary> ```typescript { // TypeScript, all fields are optional styles: Array<{ id: string // Use as @style:<id> in a v4 prompt name: string // e.g. "3D Cartoon with Exaggerated Perspective" group: string // 3D Style, 2D Style, Material Craft or Photography Style text_to_image: boolean // Offered for images from text image_to_image: boolean // Offered for restyling a reference image sample: string // Sample image }> tones: Array<{ id: string // Use as @tone:<id> in a v4 prompt name: string // e.g. "Nostalgic Wuxia" group: string // Director Styles, Camera Simulation, Classic Styles, Advanced Color or Visual Lighting sample: string // Sample image }> fonts: Array<{ id: string // Use as @font:<id> before the quoted text in a v4 prompt name: string // e.g. "Modern Rounded Sans" languages: string[] // en, ja, ko, zh-Hans, zh-Hant styles: string[] // e.g. standard, handwriting, cute, retro, pixel, modern, classical sample: string // Sample image }> updated: string // When the lists were fetched from Kling (ISO 8601) } ``` </details> ##### Examples **Curl** ``` bash curl -X GET "https://api.useapi.net/v1/kling/images/presets" \ -H "Authorization: Bearer ..." ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = "https://api.useapi.net/v1/kling/images/presets"; const response = await fetch(apiUrl, { method: "GET", headers: { "Authorization": `Bearer ${token}`, } }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" apiUrl = "https://api.useapi.net/v1/kling/images/presets" headers = { "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-kling-v1/get-kling-scheduler-available === Document URL: https://useapi.net/docs/api-kling-v1/get-kling-scheduler-available --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> scheduler/available description: "Retrieve available generation capacity and running task counts via GET scheduler/available in the useapi.net Kling API v1." parent: Kling API nav_order: 510 --- ## Retrieve available capacity April 18, 2025 (November 16, 2026) --- This endpoint retrieves information about available capacity and currently running API tasks. > **https://api.useapi.net/v1/kling/scheduler/available** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** ```json { "executing": [ { "id": 123456789, "email": "user1@example.com", "started": "2025-04-18T12:34:56.789Z", "elapsed": "03:45", "replyUrl": "https://example.com/webhook", "replyRef": "reference-id" } ], "available": [ { "email": "user1@example.com", "maxJobs": 5, "executing": 1, "available": 4 }, { "email": "user2@example.com", "maxJobs": 3, "executing": 0, "available": 3 } ] } ``` **400** **400 Bad Request** ```json { "error": "Error ..." } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model The tasks running now, and for each account its `maxJobs`, running jobs and free job slots. <details markdown="block" class="model-details"> <summary>Running tasks and free job slots per account, field by field</summary> ```typescript { // TypeScript, all fields are optional executing: { id: number // Task ID email: string // Account email started: string // ISO timestamp of when the task started elapsed: string // Elapsed time in MM:SS format replyUrl: string // Webhook URL to notify when the task completes replyRef: string // Reference ID for the webhook }[] available: { email: string // Kling account email maxJobs: number // Maximum number of concurrent jobs configured executing: number // Number of jobs currently executing available: number // Number of available job slots }[] } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/kling/scheduler/available" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = "https://api.useapi.net/v1/kling/scheduler/available"; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" apiUrl = "https://api.useapi.net/v1/kling/scheduler/available" headers = { "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-kling-v1/get-kling-scheduler === Document URL: https://useapi.net/docs/api-kling-v1/get-kling-scheduler --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> scheduler description: "Check which API tasks are currently running via GET scheduler in the useapi.net Kling API v1 — useful for monitoring active Kling generation jobs." parent: Kling API nav_order: 500 --- ## Retrieve running tasks April 18, 2025 (November 16, 2026) --- This endpoint retrieves information about currently running API tasks. > **https://api.useapi.net/v1/kling/scheduler** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** ```json [ { "id": 123456789, "email": "user@example.com", "started": "2025-04-18T12:34:56.789Z", "elapsed": "03:45", "replyUrl": "https://example.com/webhook", "replyRef": "reference-id" }, { "id": 987654321, "email": "user@example.com", "started": "2025-04-18T12:45:67.890Z", "elapsed": "02:34", "replyUrl": "https://example.com/webhook", "replyRef": "reference-id-2" } ] ``` **400** **400 Bad Request** ```json { "error": "Error ..." } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model A list of the tasks running now, each with its task id, account email, start time and elapsed time. <details markdown="block" class="model-details"> <summary>The list of running tasks, field by field</summary> ```typescript { // TypeScript, all fields are optional id: number // Task ID email: string // Account email started: string // ISO timestamp of when the task started elapsed: string // Elapsed time in MM:SS format replyUrl: string // Webhook URL to notify when the task completes replyRef: string // Reference ID for the webhook }[] ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/kling/scheduler" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = "https://api.useapi.net/v1/kling/scheduler"; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" apiUrl = "https://api.useapi.net/v1/kling/scheduler" headers = { "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-kling-v1/get-kling-tasks-task_id === Document URL: https://useapi.net/docs/api-kling-v1/get-kling-tasks-task_id --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> tasks/`task_id` description: "Poll the status and output of a specific Kling task by task ID via GET tasks/task_id in the useapi.net Kling API v1 — response schema and status values documented." parent: Kling API nav_order: 305 --- ## Retrieve specific Kling task April 18, 2025 (November 19, 2026) --- This endpoint retrieves information about a specific task by its ID. > **https://api.useapi.net/v1/kling/tasks/`task_id`?…** The `task_id` value should be a numeric identifier of the task you want to retrieve. ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `email` is optional when only one [account](/docs/api-kling-v1/get-kling-accounts) is configured. However, if you have multiple accounts configured, this parameter becomes required. Use the account that ran the task. A job sent without `email` runs on one of your accounts: the create call's `task.userId` is that account's `session.userId` in [GET accounts](/docs/api-kling-v1/get-kling-accounts), and [GET scheduler](/docs/api-kling-v1/get-kling-scheduler) lists each running task with its account's `email`. ##### Responses **200** **200 OK** ```json { "status": 99, "status_name": "succeed", "status_final": true, "etaTime": 0, "etaTimeOverSla": false, "queuingEtaTime": 0, "originEtaTime": 0, "originQueuingEtaTime": 0, "message": "success", "task": { "id": 123456789, "userId": 12345, "type": "m2v_img2video_hq", "scene": "NORMAL_CREATION", "status": 99, "status_name": "succeed", "status_final": true, "taskInfo": { "type": "m2v_img2video_hq", "inputs": [ { "name": "input", "inputType": "URL", "token": null, "blobStorage": null, "url": "https://s21-kling.klingai.com/....jpg", "cover": null, "fromWorkId": null } ], "arguments": [ { "name": "prompt", "value": "A person dancing" }, { "name": "negative_prompt", "value": "" }, { "name": "duration", "value": "5" }, { "name": "kling_version", "value": "2.0" } ], "extraArgs": {}, "callbackPayloads": [], "scene": "NORMAL_CREATION" }, "favored": false, "deleted": false, "viewed": true, "createTime": 1744858514499, "updateTime": 1744858823172, "viewTime": 1744916388016 }, "works": [ { "workId": 123456789, "workItemId": 0, "taskId": 123456789, "userId": 12345, "type": "m2v_img2video_hq", "status": 99, "status_name": "succeed", "status_final": true, "contentType": "video", "resource": { "resource": "https://s21-kling.klingai.com/....mp4", "height": 1268, "width": 724, "duration": 5041, "resourceKey": "" }, "cover": { "resource": "https://s21-kling.klingai.com/....jpg", "height": 1268, "width": 724, "duration": 0, "resourceKey": "" }, "starNum": 0, "cloneCount": 0, "reportNum": 0, "createTime": 1744858514515, "taskInfo": { "type": "m2v_img2video_hq", "inputs": [ { "name": "input", "inputType": "URL", "token": null, "blobStorage": null, "url": "https://s21-kling.klingai.com/....jpg", "cover": null, "fromWorkId": null, "fromUploadId": null } ], "arguments": [ { "name": "prompt", "value": "A person dancing" }, { "name": "negative_prompt", "value": "" }, { "name": "duration", "value": "5" }, { "name": "kling_version", "value": "2.0" } ], "extraArgs": {}, "callbackPayloads": [], "scene": "NORMAL_CREATION" }, "selfAttitude": "unknown", "selfComment": { "rate": 0, "tags": [], "content": "", "prompts": [] }, "favored": false, "starred": false, "publishStatus": "unpublished", "deleted": false, "publishTime": 0, "submitTime": 1744858514515, "lipSyncStatus": 99, "downloadInfo": { "fileTypes": [ { "type": "MP4", "watermark": true } ] }, "allowPublish": true } ], "currentTimestamp": 1744955215247 } ``` **400** **400 Bad Request** ```json { "error": "Invalid task_id parameter" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** Task was either deleted or failed due to moderation, or your account did not have enough credits. Check your KLING account balance [GET accounts/`email`](/docs/api-kling-v1/get-kling-accounts-email) ```json { "error": "Sorry, the requested resource was not found (VALID.ResourceNotFound)", "message": "Not Found" } ``` **429** **429 Too Many Requests** Kling limits how often one account may call it and answered "Service busy" (`BASE.RateExceed`). Poll less often, a task every 10 seconds or slower is plenty, and retry after the `Retry-After` seconds (10). ```json { "error": "Kling account user@example.com is calling Kling too often: request frequency exceeded, please try again later. Poll less often (a task every 10 seconds or slower is plenty, a job takes minutes) and retry after the Retry-After seconds (BASE.RateExceed)", "message": "Service busy (BASE.RateExceed)" } ``` ##### Model The task's status (`status_name`, `status_final`), its time estimate and its outputs in `works`, each with a `workId`. <details markdown="block" class="model-details"> <summary>Known <code>status</code> values and the task record, field by field</summary> List of known `status` values: | status | status_name | status_final | Notes | |--------|-------------|---------------|------------------------------------------------| | 5 | submitted | false | | | 6 | failed | true | Change the input prompt and try again | | 7 | failed | true | The input prompt contains sensitive words | | 9 | failed | true | Change the input prompt and try again | | 10 | processing | false | | | 50 | failed | true | Change the input prompt and try again | | 53 | failed | true | Your account does not support this feature | | 54 | failed | true | The queue for the free plan is busy now | | 58 | failed | true | The queue for your plan is busy now. Wait until running tasks are completed and retry, or upgrade your plan. | | 99 | succeed | true | | Calculate estimated time left in milliseconds as `etaTime - currentTimestamp`. When the task is complete, `etaTime` will be `0`. To download assets without watermarks, use the [GET /assets/download](/docs/api-kling-v1/get-kling-assets-download) endpoint with the workId values found in the `works` array of the response. ```typescript { // TypeScript, all fields are optional status: number status_name: string status_final: boolean etaTime: number etaTimeOverSla: boolean queuingEtaTime: number originEtaTime: number originQueuingEtaTime: number message: string task: { id: number userId: number type: string scene: string status: number status_name: string status_final: boolean taskInfo: { type: string inputs: { name: string inputType: string token: string | null blobStorage: string | null url: string cover: string | null fromWorkId: number | null }[] arguments: { name: string value: string }[] extraArgs: Record<string, any> callbackPayloads: any[] scene: string } favored: boolean deleted: boolean viewed: boolean createTime: number updateTime: number viewTime: number } works: { workId: number workItemId: number taskId: number userId: number type: string status: number status_name: string status_final: boolean contentType: string resource: { resource: string height: number width: number duration: number resourceKey: string } cover: { resource: string height: number width: number duration: number resourceKey: string } starNum: number cloneCount: number reportNum: number createTime: number taskInfo: { type: string inputs: { name: string inputType: string token: string | null blobStorage: string | null url: string cover: string | null fromWorkId: number | null fromUploadId: number | null }[] arguments: { name: string value: string }[] extraArgs: Record<string, any> callbackPayloads: any[] scene: string } selfAttitude: string selfComment: { rate: number tags: any[] content: string prompts: any[] } favored: boolean starred: boolean publishStatus: string deleted: boolean publishTime: number submitTime: number lipSyncStatus: number downloadInfo: { fileTypes: { type: string watermark: boolean }[] } allowPublish: boolean }[] currentTimestamp: number } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/kling/tasks/123456789?email=user@example.com" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const taskId = "123456789"; const apiUrl = `https://api.useapi.net/v1/kling/tasks/${taskId}?email=${email}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured account email" task_id = "123456789" apiUrl = f"https://api.useapi.net/v1/kling/tasks/{task_id}?email={email}" headers = { "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-kling-v1/get-kling-tasks === Document URL: https://useapi.net/docs/api-kling-v1/get-kling-tasks --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> tasks description: "List Kling tasks (images, videos, and other generations) from your account via GET tasks in the useapi.net Kling API v1, with pagination and type filtering." parent: Kling API nav_order: 300 --- ## Retrieve Kling tasks April 18, 2025 (November 16, 2026) --- This endpoint retrieves a list of tasks from your Kling account. > **https://api.useapi.net/v1/kling/tasks/?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `email` is optional when only one [account](/docs/api-kling-v1/get-kling-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `contentType` is optional, filter tasks by content type. Supported values: `video`, `image`, or `audio`. - `pageSize` is optional, specify the number of tasks to return. - `createdBefore` is optional, timestamp (in milliseconds) to get tasks created before this time. Cannot be used with `createdAfter`. - `createdAfter` is optional, timestamp (in milliseconds) to get tasks created after this time. Cannot be used with `createdBefore`. ##### Responses **200** **200 OK** ```json { "history": [ { "works": [ { "workId": 123456789, "workItemId": 0, "taskId": 123456789, "userId": 12345, "type": "m2v_img2video_hq", "status": 99, "status_name": "succeed", "status_final": true "contentType": "video", "resource": { "resource": "https://s21-kling.klingai.com/....mp4", "height": 1268, "width": 724, "duration": 5041, "resourceKey": "" }, "cover": { "resource": "https://s21-kling.klingai.com/....jpg", "height": 1268, "width": 724, "duration": 0, "resourceKey": "" }, "starNum": 0, "cloneCount": 0, "reportNum": 0, "createTime": 1744858514515, "taskInfo": { "type": "m2v_img2video_hq", "inputs": [ { "name": "input", "inputType": "URL", "token": null, "blobStorage": null, "url": "https://s21-kling.klingai.com/....jpg", "cover": null, "fromWorkId": null, "fromUploadId": null } ], "arguments": [ { "name": "prompt", "value": "A person dancing" }, { "name": "negative_prompt", "value": "" }, { "name": "duration", "value": "5" }, { "name": "kling_version", "value": "2.0" } ], "extraArgs": {}, "callbackPayloads": [], "scene": "NORMAL_CREATION" }, "selfAttitude": "unknown", "selfComment": { "rate": 0, "tags": [], "content": "", "prompts": [] }, "favored": false, "starred": false, "publishStatus": "unpublished", "deleted": false, "publishTime": 0, "submitTime": 1744858514515, "lipSyncStatus": 99, "downloadInfo": { "fileTypes": [ { "type": "MP4", "watermark": true } ] }, "allowPublish": true } ], "task": { "id": 123456789, "userId": 12345, "type": "m2v_img2video_hq", "scene": "NORMAL_CREATION", "status": 99, "status_name": "succeed", "status_final": true "taskInfo": { "type": "m2v_img2video_hq", "inputs": [ { "name": "input", "inputType": "URL", "token": null, "blobStorage": null, "url": "https://s21-kling.klingai.com/....jpg", "cover": null, "fromWorkId": null, "fromUploadId": null } ], "arguments": [ { "name": "prompt", "value": "A person dancing" }, { "name": "negative_prompt", "value": "" }, { "name": "duration", "value": "5" }, { "name": "kling_version", "value": "2.0" } ], "extraArgs": {}, "callbackPayloads": [], "scene": "NORMAL_CREATION" }, "favored": false, "deleted": false, "viewed": true, "createTime": 1744858514499, "updateTime": 1744858823172, "viewTime": 1744916388016 }, "etaTime": 0, "etaTimeOverSla": false, "queuingEtaTime": 0, "originEtaTime": 0, "originQueuingEtaTime": 0, "currentTimestamp": 1744955215247 } ], "userPoints": { "total": 190500 }, "userTickets": { "ticket": [ { "orderId": "123456789", "type": "priority", "packageType": "reward", "amount": 1, "balance": 1, "startTime": 1744046060883, "endTime": 1746724460883 } ] } } ``` **400** **400 Bad Request** ```json { "error": "createdAfter and createdBefore cannot be used together" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model Your tasks in `history`, each with its status and its outputs in `works`, plus the account's balance. <details markdown="block" class="model-details"> <summary>Known <code>status</code> values and the list of tasks, field by field</summary> List of known `status` values: | status | status_name | status_final | Notes | |--------|-------------|---------------|------------------------------------------------| | 5 | submitted | false | | | 6 | failed | true | Change the input prompt and try again | | 7 | failed | true | The input prompt contains sensitive words | | 9 | failed | true | Change the input prompt and try again | | 10 | processing | false | | | 50 | failed | true | Change the input prompt and try again | | 53 | failed | true | Your account does not support this feature | | 54 | failed | true | The queue for the free plan is busy now | | 58 | failed | true | The queue for your plan is busy now. Wait until running tasks are completed and retry, or upgrade your plan. | | 99 | succeed | true | | To download assets without watermarks, use the [GET /assets/download](/docs/api-kling-v1/get-kling-assets-download) endpoint with the workId values found in the `works` array of the response. ```typescript { // TypeScript, all fields are optional history: { works: { workId: number workItemId: number taskId: number userId: number type: string status: number status_name: string status_final: boolean contentType: string resource: { resource: string height: number width: number duration: number resourceKey: string } cover: { resource: string height: number width: number duration: number resourceKey: string } starNum: number cloneCount: number reportNum: number createTime: number taskInfo: { type: string inputs: { name: string inputType: string token: string | null blobStorage: string | null url: string cover: string | null fromWorkId: number | null fromUploadId: number | null }[] arguments: { name: string value: string }[] extraArgs: Record<string, any> callbackPayloads: any[] scene: string } selfAttitude: string selfComment: { rate: number tags: any[] content: string prompts: any[] } favored: boolean starred: boolean publishStatus: string deleted: boolean publishTime: number submitTime: number lipSyncStatus: number downloadInfo: { fileTypes: { type: string watermark: boolean }[] } allowPublish: boolean }[] task: { id: number userId: number type: string scene: string status: number status_name: string status_final: boolean taskInfo: { type: string inputs: { name: string inputType: string token: string | null blobStorage: string | null url: string cover: string | null fromWorkId: number | null fromUploadId: number | null }[] arguments: { name: string value: string }[] extraArgs: Record<string, any> callbackPayloads: any[] scene: string } favored: boolean deleted: boolean viewed: boolean createTime: number updateTime: number viewTime: number } etaTime: number etaTimeOverSla: boolean queuingEtaTime: number originEtaTime: number originQueuingEtaTime: number currentTimestamp: number }[] userPoints: { total: number } userTickets: { ticket: { orderId: string type: string packageType: string amount: number balance: number startTime: number endTime: number }[] } } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/kling/tasks/?email=user@example.com" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const apiUrl = `https://api.useapi.net/v1/kling/tasks/?email=${email}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured account email" apiUrl = f"https://api.useapi.net/v1/kling/tasks/?email={email}" headers = { "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-kling-v1/get-kling-tts-voices === Document URL: https://useapi.net/docs/api-kling-v1/get-kling-tts-voices --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> tts/voices description: "List available Kling text-to-speech voices for use with POST tts/create via GET tts/voices in the useapi.net Kling API v1." parent: Kling API nav_order: 470 --- ## Retrieve available TTS voices April 18, 2025 (November 16, 2026) --- This endpoint retrieves a list of available text-to-speech voices from Kling. > **https://api.useapi.net/v1/kling/tts/voices?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `email` is optional. Without it, one of your [accounts](/docs/api-kling-v1/get-kling-accounts) is used to read the list (`429` while every account is at its `maxJobs`). ##### Responses **200** **200 OK** ```json { "ttsList": [ { "name": "Voice Name 1", "speakerId": "voice_id_1", "exampleUrl": "https://s21-kling.klingai.com/....mp3", "new": false, "emotions": [ { "name": "Happy", "key": "happy", "enable": true }, { "name": "Sad", "key": "sad", "enable": true } ] }, { "name": "Voice Name 2", "speakerId": "voice_id_2", "exampleUrl": "https://s21-kling.klingai.com/....mp3", "new": true, "emotions": [] } ], "lastSpeakerId": "voice_id_1", "typeList": ["en", "zh"] } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model A list of Kling's text-to-speech voices in `ttsList`, each with its `speakerId`, `exampleUrl` and emotions. <details markdown="block" class="model-details"> <summary>The list of text-to-speech voices, field by field</summary> ```typescript { // TypeScript, all fields are optional ttsList: { name: string speakerId: string exampleUrl: string new: boolean emotions: { name: string key: string enable: boolean }[] }[] lastSpeakerId: string typeList: string[] } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/kling/tts/voices?email=user@example.com" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const apiUrl = `https://api.useapi.net/v1/kling/tts/voices?email=${email}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured account email" apiUrl = f"https://api.useapi.net/v1/kling/tts/voices?email={email}" headers = { "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-kling-v1/get-kling-videos-effects === Document URL: https://useapi.net/docs/api-kling-v1/get-kling-videos-effects --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> videos/effects description: "List available special video effects for use with POST videos/image2video-effects via GET videos/effects in the useapi.net Kling API v1." parent: Kling API nav_order: 320 --- ## Get Available Video Effects April 18, 2025 (November 16, 2026) --- This endpoint retrieves a list of available special effects that can be applied to videos when using the [POST /videos/image2video-effects](/docs/api-kling-v1/post-kling-videos-image2video-effects) endpoint. > **https://api.useapi.net/v1/kling/videos/effects/?...** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `email` is optional. Without it, one of your [accounts](/docs/api-kling-v1/get-kling-accounts) is used to read the list (`429` while every account is at its `maxJobs`). ##### Responses **200** **200 OK** ```json [ { "name": "rocket", "caption": "RocketRocket", "hot": true, "minimalKrnVersion": 20250416, "supportedModelMode": ["std", "pro"], "compositedSchema": { "preprocess": { "taskType": "", "taskVersion": "", "defaultPrompt": "", "requireInputs": [ { "inputType": "URL", "contentType": "IMAGE", "optional": false, "contentName": "image" } ] }, "process": { "taskType": "m2v_img2video_se_hq", "taskVersion": "1.6", "defaultPrompt": "emits dazzling white smoke and orange Mach rings from the bottom, and it begins to rise into the air...", "requireInputs": [ { "inputType": "URL", "contentType": "IMAGE", "optional": false, "contentName": "image" } ] } }, "videoUrl": "https://v21-kling.klingai.com/bs2/upload-ylab-stunt-sgp/kling/ai_se/火箭升空-原-海-视频.gif", "coverUrl": "https://s21-kling.klingai.com/bs2/upload-ylab-stunt-sgp/kling/ai_se/火箭升空-原-海-封面.jpg", "webVideoUrl": "https://v21-kling.klingai.com/bs2/upload-ylab-stunt-sgp/kling/ai_se/火箭升空-原-海-视频.mp4", "effectSupported": true, "promptSupported": true }, { "name": "spinoff", "caption": "DizzyDizzy", "hot": false, "minimalKrnVersion": 400, "supportedModelMode": ["pro"], "videoUrl": "https://v21-kling.klingai.com/bs2/upload-ylab-stunt-sgp/kling/ai_se/魔力转圈圈-视频.gif", "coverUrl": "https://s21-kling.klingai.com/bs2/upload-ylab-stunt-sgp/kling/ai_se/魔力转圈圈-封面.png", "webVideoUrl": "https://v21-kling.klingai.com/bs2/upload-ylab-stunt-sgp/kling/ai_se/魔力转圈圈-视频-compress.mp4", "effectSupported": false, "promptSupported": false } ] ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` The response contains an array of available effects that can be used with the [POST /videos/image2video-effects](/docs/api-kling-v1/post-kling-videos-image2video-effects) endpoint. Each effect now includes additional flags: - `effectSupported`: Indicates if the effect is supported by the current endpoint (false means it requires image preprocessing) - `promptSupported`: Indicates if the effect accepts custom prompts (false means it uses only default prompts) ##### Model An array of video effects for [POST /videos/image2video-effects](/docs/api-kling-v1/post-kling-videos-image2video-effects), each with its `name` and preview video and cover URLs. <details markdown="block" class="model-details"> <summary>Each video effect, field by field</summary> ```typescript { // TypeScript, all fields are optional name: string // Effect name identifier (used in requests) caption: string // Display name for the effect hot: boolean // Whether this is a featured effect minimalKrnVersion?: number // Minimum kernel version required supportedModelMode?: string[] // Supported model modes ("std", "pro") effectSupported?: boolean // Whether effect is supported (false = requires preprocessing) promptSupported?: boolean // Whether effect accepts custom prompts compositedSchema?: { // Legacy schema information preprocess?: { taskType: string taskVersion: string defaultPrompt: string requireInputs: Array<{ inputType: string contentType: string optional: boolean contentName: string }> } process?: { taskType: string taskVersion: string defaultPrompt: string requireInputs: Array<{ inputType: string contentType: string optional: boolean contentName: string }> } } videoUrl: string // Preview video URL for the effect coverUrl: string // Cover image URL for the effect webVideoUrl: string // Web-optimized preview video URL } ``` </details> ##### Usage Notes - **effectSupported**: Only effects with `effectSupported: true` can be used with the [POST /videos/image2video-effects](/docs/api-kling-v1/post-kling-videos-image2video-effects) endpoint - **promptSupported**: Effects with `promptSupported: true` accept custom prompts; others use built-in defaults - **supportedModelMode**: Check which quality modes (std/pro) are available for each effect - Use the effect's `name` value when making requests to the [POST /videos/image2video-effects](/docs/api-kling-v1/post-kling-videos-image2video-effects) endpoint ##### Examples **Curl** ``` bash curl -X GET "https://api.useapi.net/v1/kling/videos/effects?email=user@example.com" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const apiUrl = "https://api.useapi.net/v1/kling/videos/effects"; const response = await fetch(`${apiUrl}?email=${email}`, { method: "GET", headers: { "Authorization": `Bearer ${token}`, } }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured account email" apiUrl = "https://api.useapi.net/v1/kling/videos/effects" headers = { "Authorization" : f"Bearer {token}" } params = { "email": email } response = requests.get(apiUrl, headers=headers, params=params) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-kling-v1/get-kling-videos-motions === Document URL: https://useapi.net/docs/api-kling-v1/get-kling-videos-motions --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> videos/motions description: "List official motion videos to use as the motionUrl parameter in POST videos/motion-create via GET videos/motions in the useapi.net Kling API v1." parent: Kling API nav_order: 325 --- ## Get Available Motions October 7, 2025 (November 16, 2026) --- This endpoint retrieves a list of available motion assets. Official motion videos can be used as `motionUrl` in [POST /videos/motion-create](/docs/api-kling-v1/post-kling-videos-motion-create). Uses Kling v2.6 modality asset API. > **https://api.useapi.net/v1/kling/videos/motions?...** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `email` is optional. Without it, one of your [accounts](/docs/api-kling-v1/get-kling-accounts) is used to read the list (`429` while every account is at its `maxJobs`). With `mine=true`, pass `email` to list that account's own motion videos. - `mine` is optional, boolean value. When `true`, retrieves user's own motion assets. When `false` or omitted, retrieves official Kling motion templates. **Notes:** - Use the `url` field as `motionUrl` when making requests to motion-create - Official motions are pre-processed motion videos provided by Kling - User motions are videos previously uploaded via [POST /assets](/docs/api-kling-v1/post-kling-assets) - use `resourceUrl` from upload response ##### Responses **200** **200 OK** ```json [ { "assetId": "motion_12345", "assetType": "MOTION", "url": "https://v15-kling.klingai.com/bs2/upload-ylab-stunt-sgp/.../motion.mp4", "coverUrl": "https://s15-kling.klingai.com/.../cover.jpg", "duration": 5760, "width": 720, "height": 1280, "hasAudio": true, "createTime": 1767669665000 } ] ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model A list of motion videos, each with its `assetId` and the `url` to pass as `motionUrl` to [POST /videos/motion-create](/docs/api-kling-v1/post-kling-videos-motion-create). <details markdown="block" class="model-details"> <summary>The list of motions, field by field</summary> ```typescript Array<{ // TypeScript, all fields are optional assetId: string // Unique asset identifier assetType: string // "MOTION" url: string // URL to the motion video - use as motionUrl in motion-create coverUrl?: string // URL to the cover/thumbnail image duration?: number // Duration in milliseconds width?: number // Video width in pixels height?: number // Video height in pixels hasAudio?: boolean // Whether the motion has audio createTime?: number // Creation timestamp }> ``` </details> ##### Examples **Curl** ``` bash # Get official motions curl -X GET "https://api.useapi.net/v1/kling/videos/motions?email=user@example.com" \ -H "Authorization: Bearer ..." # Get user motions curl -X GET "https://api.useapi.net/v1/kling/videos/motions?email=user@example.com&mine=true" \ -H "Authorization: Bearer ..." ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const mine = false; // false for official, true for user const apiUrl = "https://api.useapi.net/v1/kling/videos/motions"; const response = await fetch(`${apiUrl}?email=${email}&mine=${mine}`, { method: "GET", headers: { "Authorization": `Bearer ${token}`, } }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured account email" apiUrl = "https://api.useapi.net/v1/kling/videos/motions" headers = { "Authorization" : f"Bearer {token}" } params = { "email": email, "mine": False # False for official, True for user } response = requests.get(apiUrl, headers=headers, params=params) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-kling-v1/get-kling-videos-voices === Document URL: https://useapi.net/docs/api-kling-v1/get-kling-videos-voices --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> videos/voices description: "List your Kling 4.0 voices, saved and official, via GET videos/voices in the useapi.net Kling API v1 to use as voice_1 to voice_3 in Omni v4 videos." parent: Kling API nav_order: 327 --- ## Get Kling 4.0 Voices October 15, 2026 (November 16, 2026) --- This endpoint lists the Kling 4.0 voices available to your account: your saved voices first, then Kling's official voices. Use a voice `id` or `name` as `voice_1`, `voice_2` or `voice_3` in [POST /videos/omni](/docs/api-kling-v1/post-kling-videos-omni#voices-v4-only) with `omni_version: v4`. Save your own voice from a 4.5 to 30 second audio clip with [POST /videos/voices](/docs/api-kling-v1/post-kling-videos-voices). Voices you saved on kling.ai show up here too. A saved voice belongs to one Kling account, so use the same `email` here and in [POST /videos/omni](/docs/api-kling-v1/post-kling-videos-omni). Delete a saved voice with [DELETE /videos/voices](/docs/api-kling-v1/del-kling-videos-voices). Some voices have samples shorter than 3 seconds, which Kling does not accept — [POST /videos/omni](/docs/api-kling-v1/post-kling-videos-omni#responses) with such a voice returns a 400 error. > **https://api.useapi.net/v1/kling/videos/voices?...** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `email` is optional when only one [account](/docs/api-kling-v1/get-kling-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. **Notes:** - Saved voices have `source: USER` and Kling's official voices have `source: TTS_OFFICIAL` - `audioUrl` is the voice sample, so you can listen to a voice before you use it - `duration` is the length of a saved voice in milliseconds ##### Responses **200** **200 OK** ```json { "voices": [ { "id": "301234567890", "name": "My voice", "source": "USER", "audioUrl": "https://v15-kling.klingai.com/.../voice.quality.wav", "coverUrl": "https://s15-kling.klingai.com/kimg/.../cover.png", "duration": 8300 }, { "id": "English_captivating_female1", "name": "Emma", "source": "TTS_OFFICIAL", "audioUrl": "https://v15-kling.klingai.com/bs2/upload-ylab-stunt-sgp/kling/tts/emma.mp3?x-kcdn-pid=112372", "coverUrl": "https://s15-kling.klingai.com/kimg/.../cover.png", "emotions": [ { "name": "Neutral", "key": "neutral", "enable": true }, { "name": "Happy", "key": "happy", "enable": true }, { "name": "Angry", "key": "angry", "enable": true }, { "name": "Sad", "key": "sad", "enable": true }, { "name": "Fearful", "key": "fearful", "enable": true }, { "name": "Disgusted", "key": "disgusted", "enable": true }, { "name": "Surprised", "key": "surprised", "enable": true } ] }, { "id": "English_CalmWoman", "name": "Diana", "source": "TTS_OFFICIAL", "audioUrl": "https://v15-kling.klingai.com/bs2/upload-ylab-stunt-sgp/kling/tts/diana.mp3?x-kcdn-pid=112372", "coverUrl": "https://s15-kling.klingai.com/kimg/.../cover.png", "emotions": [ { "name": "Neutral", "key": "neutral", "enable": true }, { "name": "Happy", "key": "happy", "enable": true }, { "name": "Angry", "key": "angry", "enable": true }, { "name": "Sad", "key": "sad", "enable": true }, { "name": "Fearful", "key": "fearful", "enable": true }, { "name": "Disgusted", "key": "disgusted", "enable": true }, { "name": "Surprised", "key": "surprised", "enable": true } ] } ] } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model A list of Kling 4.0 voices, your saved voices (`source: USER`) first, each with its `id`, name and sample. <details markdown="block" class="model-details"> <summary>The list of Kling 4.0 voices, field by field</summary> ```typescript { // TypeScript, all fields are optional voices: Array<{ id: string // Use as voice_1 … voice_3 in POST /videos/omni (or use name) name: string // Voice name, e.g. "Emma" source: 'USER' | 'TTS_OFFICIAL' // USER = your saved voice, TTS_OFFICIAL = Kling's official voice audioUrl: string // Voice sample coverUrl?: string // Cover image emotions?: Array<{ name: string key: string enable: boolean }> duration?: number // Saved (USER) voices: length in milliseconds }> } ``` </details> ##### Examples **Curl** ``` bash curl -X GET "https://api.useapi.net/v1/kling/videos/voices?email=user@example.com" \ -H "Authorization: Bearer ..." ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const apiUrl = "https://api.useapi.net/v1/kling/videos/voices"; const response = await fetch(`${apiUrl}?email=${email}`, { method: "GET", headers: { "Authorization": `Bearer ${token}`, } }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured account email" apiUrl = "https://api.useapi.net/v1/kling/videos/voices" headers = { "Authorization" : f"Bearer {token}" } params = { "email": email } response = requests.get(apiUrl, headers=headers, params=params) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-kling-v1/mcp === Document URL: https://useapi.net/docs/api-kling-v1/mcp --- layout: default title: MCP Server nav_icon: mcp seo_title: "Kling MCP Server: Kling 4.0 Video, Avatars and Lip-Sync, Hosted" description: "Connect the Claude app, ChatGPT, Claude Code or any MCP client to the hosted useapi.net Kling MCP server: 46 tools for Kling 4.0 video, Kling Image 4.0, v3 and Omni, avatars and lip-sync." parent: Kling API nav_order: 50 permalink: /docs/api-kling-v1/mcp --- ## Kling MCP Server October 16, 2026 (November 19, 2026) --- The useapi.net Kling MCP server lets an AI assistant such as the Claude app, ChatGPT, Claude Code, Cursor or VS Code Copilot use [Kling AI](https://kling.ai/app) on your own Kling accounts. It is a hosted [Model Context Protocol](https://modelcontextprotocol.io) server with 46 tools: generate video from text, images, keyframes or references with Kling 4.0, 4.0 Flash, v3 and Omni, make talking avatars and motion-control videos, lip-sync, add sound and extend clips, generate images with Kling Image 4.0 (up to 8K, product pages and web designs) and enhance them, and manage elements, voices, avatars and uploads. Each tool calls the [Kling API](/docs/api-kling-v1), so the same rules and limits apply. Nothing needs to be installed or hosted. **Is there a Kling MCP server?** Yes. useapi.net, a third-party service not affiliated with Kuaishou, hosts one at `https://api.useapi.net/v1/kling/mcp` with 46 tools for Kling 4.0, 4.0 Flash, v3 and Omni video, Kling Image 4.0, avatars and lip-sync, on your own Kling account, nothing to install. Prefer REST? Tutorial: [How to Generate AI Video with Kling v3 via the Kling API](/docs/articles/kling-bash) · Code: [github.com/useapi/kling-api](https://github.com/useapi/kling-api) See all useapi.net MCP servers on [Model Matrix & MCP](/model-matrix#mcp-servers). ## Endpoint and authorization ``` https://api.useapi.net/v1/kling/mcp ``` - Transport: Streamable HTTP. - Listed in the [official MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers/net.useapi%2Fkling/versions/latest) as `net.useapi/kling`, so MCP clients and directories that read the registry can find it by that name. - Authorization: your useapi.net API token in the `Authorization: Bearer …` header, see [Setup useapi.net](/docs/start-here/setup-useapi). The Claude app and ChatGPT sign in with OAuth instead, see [Use it in the Claude app or ChatGPT](#use-it-in-the-claude-app-or-chatgpt). - You need at least one Kling account added with [Setup Kling](/docs/start-here/setup-kling). Adding and removing accounts is not available over MCP: use [POST /accounts](/docs/api-kling-v1/post-kling-accounts) or the setup page. ## Setup Replace `YOUR_API_TOKEN` with your useapi.net API token. ### Claude Code ```bash claude mcp add --transport http useapi-kling https://api.useapi.net/v1/kling/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` ### Cursor In `~/.cursor/mcp.json`: ```json { "mcpServers": { "useapi-kling": { "url": "https://api.useapi.net/v1/kling/mcp", "headers": { "Authorization": "Bearer YOUR_API_TOKEN" } } } } ``` ### VS Code In `.vscode/mcp.json`: ```json { "servers": { "useapi-kling": { "type": "http", "url": "https://api.useapi.net/v1/kling/mcp", "headers": { "Authorization": "Bearer YOUR_API_TOKEN" } } } } ``` ### Windsurf and other clients Any client that supports remote MCP servers over HTTP with custom headers works. The usual JSON shape: ```json { "mcpServers": { "useapi-kling": { "serverUrl": "https://api.useapi.net/v1/kling/mcp", "headers": { "Authorization": "Bearer YOUR_API_TOKEN" } } } } ``` Some clients name the address field `url` instead of `serverUrl`. ### Test it with curl ```bash curl -s https://api.useapi.net/v1/kling/mcp \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}' curl -s https://api.useapi.net/v1/kling/mcp \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' ``` The first call answers with the server's name `useapi-kling` and its instructions for the assistant, the second with the 46 tools. ## Use it in the Claude app or ChatGPT The Claude app ([claude.ai](https://claude.ai) and Claude Desktop) and [ChatGPT](https://chatgpt.com) can add this server as a custom connector. They sign in with OAuth: you give the app the URL, it opens a useapi.net page, and you paste your useapi.net API token there once. Both work on their Free plans. The API-token setups above for Claude Code, Cursor, VS Code and other clients keep working as before. ``` ``` ### Claude app 1. Open Settings → Connectors and click Add custom connector. 2. Enter a name, for example `useapi `, and the URL above, then click Add. 3. Click Connect. Claude opens the useapi.net sign-in page. 4. Paste your useapi.net API token and click Allow. Claude asks before each tool call unless you choose Always allow. The Free plan allows one custom connector. ### ChatGPT 1. Open Plugins, click Add and choose Add custom MCP server. 2. Enter a name and the URL above, and set Authentication to OAuth. 3. Tick ChatGPT's "I understand and want to continue" box, then click Create as a plugin. 4. Click Connect. ChatGPT opens the useapi.net sign-in page. 5. Paste your useapi.net API token and click Allow. ChatGPT asks you to confirm each tool call that creates or changes something. The Free plan works without developer mode (as of October 25, 2026). ### How the sign-in works - Your API token is in your welcome email, see [Setup useapi.net](/docs/start-here/setup-useapi). The useapi.net page links there too. - Each connection is for one MCP server. Connect each server you want to use on its own. - The app gets an access token that lasts 1 hour and renews it on its own. A connection you don't use for 90 days lapses, and you connect again. - [Resetting your API token](/docs/account-management/post-account-token-reset) disconnects every app connected with it. - - Results come back as public links, so they open right in the app. ## Tools Generations run as tasks on one Kling account. When you don't name the account with `email`, the tool picks the one with the most free job slots and every answer says which account it used. Uploaded files, elements, voices, avatars and task ids belong to one account, so pass the same `email` when you use them. ### Videos | Tool | What it does | Main parameters | |---|---|---| | `kling_text_to_video` | Generates a video from a prompt with any text-to-video model, including `kling-v4-0` and `kling-v4-0-flash`, or from custom multi-shot prompts on `kling-v3-0` and `kling-v4-0`. | `prompt`, `model_name`, `mode`, `hdr`, `duration`, `aspect_ratio`, `enable_audio`, `shot_N_prompt` | | `kling_image_to_video` | Animates a start image, optionally to an end image, with Kling 4.0 keyframes in between or `kling-v3-0` elements. `kling-v4-0-flash` takes the start image only. | `image`, `image_tail`, `keyframe_1`..`9`, `element_1`..`3`, `prompt`, `model_name`, `mode`, `hdr`, `duration` | | `kling_omni_video` | Kling Omni (`o1`, `v3`, `v4` or `v4-flash`): a video from a prompt with images, elements, reference videos and voices named in it as `@image_1`, `@element_1`, `@video_1`, `@voice_1`. | `prompt`, `omni_version`, `image_N`, `element_N`, `video_N`, `voice_N`, `duration`, `mode`, `hdr` | | `kling_motion_control` | Makes the person in an image perform the movement of a motion video. | `imageUrl`, `motionUrl`, `model_name`, `mode` | | `kling_avatar_video` | A talking-head video from an avatar or a portrait, speaking an audio file or text. | `avatarId` or `imageUrl`, `audioUrl` or `text` + `speakerId`, `mode` | | `kling_lipsync` | Makes the face in a video speak an audio track. | `video`, `audio` | | `kling_add_sound` | Generates sound effects and ambience for a video. | `video` | | `kling_extend_video` | Continues a finished video by about 5 seconds. It works on `kling-v1-6` videos. | `task_id`, `prompt` | | `kling_effect_video` | Turns an image into a video with one of Kling's effects. | `effect`, `image`, `mode` | | `kling_elements_video` | A video combining images and elements. | `prompt`, `image_0`..`3`, `element_1`..`3`, `model_name` | The parameters match [POST /videos/text2video](/docs/api-kling-v1/post-kling-videos-text2video), [POST /videos/image2video-frames](/docs/api-kling-v1/post-kling-videos-image2video-frames), [POST /videos/omni](/docs/api-kling-v1/post-kling-videos-omni) and the other video endpoints. ### Images | Tool | What it does | Main parameters | |---|---|---| | `kling_omni_image` | Kling Image 4.0 (`v4`, up to 8K, Series Mode, style, tone and font presets, product detail pages and web designs) and Omni `v3` / `o1` images with up to 10 reference images and elements. | `prompt`, `omni_version`, `resolution`, `skill`, `length`, `story_mode`, `image_N`, `element_N`, `imageCount` | | `kling_list_image_presets` | Lists the Kling Image 4.0 styles, tones and fonts to name in a `kling_omni_image` v4 prompt. | `kind` | | `kling_kolors_image` | Kolors images, with reference images on v3 or subject, face and restyle references on older versions. | `prompt`, `version`, `imageCount`, `aspect_ratio`, `image_N` | | `kling_kolors_elements_image` | Combines up to 4 subjects with a scene and a style image. | `prompt`, `subjectImage1`..`4`, `sceneImage`, `styleImage` | | `kling_virtual_try_on` | Dresses a person in clothes from images. | `humanImage`, `dressInput` or `upperInput` / `lowerInput` | | `kling_upscale_image` | Upscales an image from a finished Kling image task. | `task_id`, `workId` | | `kling_enhance_image` | Improves and restores the detail of any image, to 2k or 4k. | `image`, `resolution` | | `kling_recognize_faces` | Finds the faces in an image. | `imageReference` | ### Tasks and files | Tool | What it does | Main parameters | |---|---|---| | `kling_get_task` | Reads a task and its results, and with `wait: true` waits for it to finish. | `task_id`, `email`, `wait` | | `kling_list_tasks` | Lists an account's recent tasks with their results. | `email`, `contentType`, `pageSize` | | `kling_list_works` | Lists an account's finished results only (videos, images, audio), with paging. | `email`, `contentType`, `pageNum`, `sort` | | `kling_list_running` | Lists the tasks still running and each account's free job slots. | | | `kling_stop_tracking` | Stops tracking a stuck task and frees its slot. The task keeps running at Kling. | `task_id` | | `kling_delete_task` | Deletes every result of a finished task. | `task_id`, `email` | | `kling_upload_asset` | Uploads an image, video or audio file from a public https URL or as `contentBase64`, and returns the Kling URL to use as an input. | `url` or `contentBase64`, `mimeType`, `email` | | `kling_list_uploads`, `kling_delete_uploads` | List and delete your uploaded files. | `email`, `contentType`, `ids` | | `kling_get_download_url` | Returns a result's file without the Kling watermark (paid Kling plans): MP4 or MOV for a video, PNG for an image. | `workId`, `fileType` | ### Elements, voices, avatars and accounts | Tool | What it does | Main parameters | |---|---|---| | `kling_list_elements`, `kling_get_element`, `kling_create_element`, `kling_delete_element` | Manage reusable elements: characters, props and scenes made from an image or a video. | `name`, `coverImage` or `video`, `tag`, `voice` | | `kling_list_element_tags`, `kling_list_element_voices` | List the tags and the voices an element can have. | `email` | | `kling_list_voices`, `kling_save_voice`, `kling_delete_voice` | List, save and delete Kling 4.0 voices for `kling_omni_video` v4. | `audioUrl`, `name`, `voiceId` | | `kling_list_tts_voices`, `kling_text_to_speech` | List the text-to-speech voices and read text aloud. | `speakerId`, `text`, `speed`, `emotion` | | `kling_list_avatars`, `kling_create_avatar`, `kling_delete_avatar` | List, create and delete avatars for `kling_avatar_video`. | `imageUrl`, `nickname`, `ttsSpeaker` | | `kling_list_effects`, `kling_list_motions` | List the video effects and the ready-made motion videos. | `email`, `mine` | | `kling_list_accounts`, `kling_get_account` | List your Kling accounts and read one account's credit balance. | `email` | The full input schema of every tool comes from `tools/list`. ## Long-running work MCP clients usually give up on a tool call after about a minute, so a tool waits up to about 50 seconds: - An image usually finishes in that time, and the tool returns it as an image the assistant can see. - A video takes a few minutes. The tool returns the `task_id` and `email`, and `kling_get_task` with both and `wait: true` picks it up. Ask the assistant to keep checking until it is done. The tool reads the task when Kling's own estimate says it may be ready. Clients that ask for progress notifications get one about every 10 seconds while a tool waits. Results come back as Kling CDN links, which may carry a watermark. A finished video also comes back with its cover as an image. ## Example prompts - "Make a 5-second video of a golden retriever running on a beach at sunset, the cheapest way." - "Upload this photo and animate it: she smiles and turns her head slowly." - "Make a 10-second Kling 4.0 video from these three images as keyframes." - "Create an element of this character, then use it in an Omni video walking through a market." - "Make a talking avatar from this portrait that says: 'Welcome to our store.'" - "How many Kling credits are left on my accounts?" ## Limits and notes - The tools use your Kling accounts and the same rules as the REST API, such as `maxJobs`. Everything uses the account's Kling credits, and prices differ a lot by model and mode, see the cost calculator on the [Kling API](/docs/api-kling-v1) page. - A client may send up to 20 JSON-RPC requests in one batch. - If the client sends an `MCP-Protocol-Version` header, it must be one of the supported versions: `2025-06-18`, `2025-03-26` or `2024-11-05`. - Tool calls show in your [usage stats](/docs/account-management/get-account-stats) (`bot=kling`) through the REST call each tool makes, the same rows a direct API request writes. === URL: https://useapi.net/docs/api-kling-v1/post-kling-accounts === Document URL: https://useapi.net/docs/api-kling-v1/post-kling-accounts --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> accounts description: "Add or update a Kling account via POST accounts in the useapi.net Kling API v1 — logs in to verify email and password, or connects slider accounts with a passToken." parent: Kling API nav_order: 110 --- ## Create/update Kling API account April 18, 2025 (November 16, 2026) --- This endpoint adds or updates a Kling account in your configuration. For an account added with email and password, the API logs in to verify your credentials. For an account connected with `passToken` (see below), the API refreshes the session with the `passToken` instead. Kling usually asks these accounts to solve the slider on a password login, so their password cannot be checked and is stored as given. The easiest way to add an account is the [automated setup](/docs/start-here/setup-kling#automated-setup-recommended): you sign in to Kling in our remote browser and the account is added for you, with no call to this endpoint. Use it when this endpoint answers `Unable to login (400002)` or `Unable to login (100110016: Your action is too frequent)`. > **https://api.useapi.net/v1/kling/accounts** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "email": "user@example.com", "password": "your-password", "maxJobs": 50 } ``` - `email` and `password` are **required**. Please see [Setup Kling](/docs/start-here/setup-kling) for details. - `maxJobs` is **required**, specify maximum number of concurrent jobs (`1`-`50`) - `passToken`, `did`, and `userId` are **optional** — supply all three together, or none. Provide them only when the account hits the Kling login slider captcha (which our server cannot solve, so plain `email` + `password` returns `Unable to login (400002)`). The three values are your signed-in Kling session captured from your own browser, where you solved the slider. When present, the account is stored in `passToken` mode and refreshes captcha-free using the `passToken`, with no password login while the `passToken` is valid. The connect tool captures them for you — see [Setup Kling](/docs/start-here/setup-kling). To update a connected account later, for example to change `maxJobs`, post `email`, `password` and `maxJobs` alone. The account stays in `passToken` mode and refreshes with its stored `passToken`. The password is stored as given without being verified, so make sure it is correct. If the stored `passToken` no longer works, the API tries a password login instead, which usually fails with `Unable to login (400002)`. Reconnect the account with a fresh `passToken`, `did` and `userId`. ##### Responses **201** **201 Created** ```json { "email": "user@example.com", "authMode": "password", "session": { "userId": 12345, "ExpireTime": 123456789, "ExpireTimeUTC": "2025-01-01T12:13:14.000Z" }, "maxJobs": 50, "password": "…secured…", "addedVia": "password", "created": "2026-11-14T22:10:45.000Z", "lastAdded": "2026-11-14T22:10:45.000Z" } ``` `authMode` is `password` for accounts added with email + password, or `passToken` for accounts connected with `passToken` + `did` + `userId`. A connected account keeps `passToken` mode when you update it later without those three values. `addedVia`, `created` and `lastAdded` are described on [GET /accounts](/docs/api-kling-v1/get-kling-accounts). **400** **400 Bad Request** ```json { "error": "Account does not exist or password is incorrect (100110004)" } ``` Kling refused the login. `Unable to login (400002)` means Kling asks this account to solve a slider, and `Unable to login (100110016: Your action is too frequent)` means Kling's risk control blocked the login. Add these accounts with the [automated setup](/docs/start-here/setup-kling#automated-setup-recommended). **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **402** **402 Payment Required** ```json { "error": "Subscription required", "code": 402 } ``` ##### Model The account as saved, with its sign-in mode (`authMode`), Kling session and `maxJobs`. <details markdown="block" class="model-details"> <summary>The saved account's settings, field by field</summary> ```typescript { // TypeScript, all fields are optional email: string authMode: "password" | "passToken" session: { userId: number ExpireTime: number ExpireTimeUTC: string } maxJobs: number password: string addedVia: "setup-browser" | "connect" | "password" created: string lastAdded: string error: string } ``` </details> ##### Examples **Curl** ``` bash curl -X POST https://api.useapi.net/v1/kling/accounts \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{"email": "user@example.com", "password": "your-password", "maxJobs": 50}' ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = "https://api.useapi.net/v1/kling/accounts"; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ email: "user@example.com", password: "your-password", maxJobs: 50 }) }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" apiUrl = "https://api.useapi.net/v1/kling/accounts" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } data = { "email": "user@example.com", "password": "your-password", "maxJobs": 50 } response = requests.post(apiUrl, headers=headers, json=data) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-kling-v1/post-kling-assets === Document URL: https://useapi.net/docs/api-kling-v1/post-kling-assets --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> assets description: "Upload images or other files to your Kling account for use in image and video generation via POST assets in the useapi.net Kling API v1." parent: Kling API nav_order: 210 --- ## Upload asset to Kling April 18, 2025 (November 16, 2026) --- This endpoint uploads an asset to your Kling account for later use in image and video generation. > **https://api.useapi.net/v1/kling/assets/?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: select from the table below ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. - `Content-Type` is **required**, select from the table below: | Content-Type | File Extension | Max Size | Notes | | ------------------- | -------------- | -------- | ----- | | image/png | png | 10MB | Minimum dimensions of 300px | | image/jpeg | jpg/jpeg | 10MB | Minimum dimensions of 300px | | video/mp4 | mp4 | 150MB | 720p/1080p resolution, 10s max | | video/quicktime | mov | 150MB | 720p/1080p resolution, 10s max | | audio/wav | wav | 30MB | 30 seconds max | | audio/wave | wav | 30MB | 30 seconds max | | audio/mpeg | mp3 | 30MB | 30 seconds max | | audio/mp4 | m4a | 30MB | 30 seconds max | | audio/flac | flac | 30MB | 30 seconds max | | audio/aac | aac | 30MB | 30 seconds max | | audio/ogg | ogg | 30MB | 30 seconds max | ##### Query Parameters - `email` is optional when only one [account](/docs/api-kling-v1/get-kling-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. ##### Responses **200** **200 OK** ```json { "status": 3, "url": "https://s21-kling.klingai.com/....jpg", "message": "", "fileName": "abc123def456789.jpg" } ``` **400** **400 Bad Request** ```json { "error": "Content-Type {content-type} is not supported. Valid values: image/png,image/jpeg,video/mp4,video/quicktime,audio/wav,audio/wave,audio/mpeg,audio/mp4,audio/flac,audio/aac,audio/ogg" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **500** **500 Internal Server Error** Kling uses a `500` response to indicate moderation and other issues with the input. It may be hard to separate actual 500 errors from moderation errors, so use the `error` field text and your best judgement to tell them apart, since the `message` field most often has very generic and perhaps misleading text. ```json { "error": "The content you uploaded appears to violate the community guidelines. (CM_EXT.POther)", "message": "Service busy (CM_EXT.POther)" } ``` You can retrieve uploaded asset details via [GET assets/uploaded/?fileName=`fileName`](/docs/api-kling-v1/get-kling-assets-uploaded). ##### Model The uploaded file's URL: `url` for an image or audio file, `resourceUrl` and a cover for a video. <details markdown="block" class="model-details"> <summary>The uploaded file, field by field</summary> ```typescript { // TypeScript, all fields are optional status: number // 3 = success for image, 1 = success for video url: string // URL of the uploaded asset for image/audio message: string // Status message or error error: string fileName?: string // Generated unique filename resourceUrl?: string // URL of the processed file (video) coverUrl?: string // URL of the cover image (video) cover?: { resource: string // URL of the cover height: number // Height in pixels width: number // Width in pixels duration: number // Duration in milliseconds (for video) resourceKey: string // Resource key } } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/kling/assets/?email=user@example.com" \ -H "Authorization: Bearer …" \ -H "Content-Type: image/jpeg" \ --data-binary @/path/to/your/image.jpg ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const apiUrl = `https://api.useapi.net/v1/kling/assets/?email=${email}`; let blob; /* // Example 1: Fetch image from URL const imageUrl = "https://example.com/image.jpg"; const responseImage = await fetch(imageUrl); blob = await responseImage.blob(); */ /* // Example 2: Load image from local file (Node.js) const fsp = require('fs').promises; const imageFileName = "./image.jpg"; blob = new Blob([await fsp.readFile(imageFileName)]); */ /* // Example 3: Load from input file html element // <input id="image-file" type="file"> const imageFile = document.getElementById(`image-file`); if (imageFile.files[0]) blob = imageFile.files[0]; */ const response = await fetch(apiUrl, { method: "POST", headers: { "Authorization": `Bearer ${token}`, "Content-Type": "image/jpeg" }, body: blob }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured account email" apiUrl = f"https://api.useapi.net/v1/kling/assets/?email={email}" headers = { 'Authorization': f'Bearer {token}', 'Content-Type': 'image/jpeg' } # Example: Load image from local file image_file_path = "./image.jpg" with open(image_file_path, 'rb') as image_file: file_content = image_file.read() response = requests.post(apiUrl, headers=headers, data=file_content) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-kling-v1/post-kling-avatars-video === Document URL: https://useapi.net/docs/api-kling-v1/post-kling-avatars-video --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> avatars/video description: "Generate a lip-sync avatar video where a Kling avatar speaks an audio file or TTS text via POST avatars/video in the useapi.net Kling API v1." parent: Kling API nav_order: 460 --- ## Generate avatar video January 12, 2026 (November 16, 2026) --- This endpoint generates a lip-sync video from an avatar image and audio. The avatar speaks with realistic lip movements synchronized to the provided audio or generated text-to-speech. You can use either: - A saved avatar from [POST /avatars](/docs/api-kling-v1/post-kling-avatars) or system templates - A direct image URL For audio, you can provide either: - A pre-recorded audio file URL (upload via [POST /assets](/docs/api-kling-v1/post-kling-assets)) - Text that will be converted to speech using TTS > **https://api.useapi.net/v1/kling/avatars/video** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "email": "user@example.com", "avatarId": "123456789012", "text": "Hello, welcome to our product demo!", "speakerId": "speaker_id_123" } ``` - `email` is optional. Leave it out and the job goes to one of your [accounts](/docs/api-kling-v1/get-kling-accounts) that has a free job slot, picked at random. Each account runs at most its `maxJobs` jobs at once, and [GET scheduler/available](/docs/api-kling-v1/get-kling-scheduler-available) shows the free slots. If no account has a free slot, the response is `429`. Pass `email` to run the job on that account (`429` if it is busy). Uploaded files, elements, voices, avatars and earlier tasks belong to one account, so pass the `email` of the account they came from. With more than one account, reading the task with [GET tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) needs its account's `email`. The response's `task.userId` is that account's `session.userId` in [GET accounts](/docs/api-kling-v1/get-kling-accounts), and [GET scheduler](/docs/api-kling-v1/get-kling-scheduler) lists each running task with its `email`. ###### Avatar Source (one required) Provide either `avatarId` or `imageUrl`, not both: - `avatarId` is the ID of a saved avatar. Use [GET /avatars](/docs/api-kling-v1/get-kling-avatars) to list your personal avatars or browse system templates. When using an avatar, its saved `prompt` and TTS settings are used as defaults. - `imageUrl` is a direct URL to an avatar image. You can upload images using [POST /assets](/docs/api-kling-v1/post-kling-assets) and use the returned URL here. ###### Audio Source (one required) Provide either `audioUrl` or `text`, not both: - `audioUrl` is a URL to a pre-recorded audio file. You can upload audio using [POST /assets](/docs/api-kling-v1/post-kling-assets) and use the returned URL here. - `text` is the text to be converted to speech. Maximum length: 5000 characters. Requires `speakerId` to be provided. ###### TTS Options (when using text) These options apply when providing `text` for text-to-speech: - `speakerId` is **required** when using `text`. Use [GET /tts/voices](/docs/api-kling-v1/get-kling-tts-voices) to get available speaker IDs. If using an `avatarId`, the avatar's saved `ttsSpeaker` is used as default. - `speed` is optional, speech speed. Range: `0.8` to `2.0`. Default: `1`. If using an `avatarId`, the avatar's saved `ttsSpeed` is used as default. - `emotion` is optional, speech emotion. Supported values: `neutral` (default), `happy`, `angry`, `sad`, `fearful`, `disgusted`, `surprised`. Not all emotions are available for all speakers. Check [GET /tts/voices](/docs/api-kling-v1/get-kling-tts-voices) for each speaker's supported emotions. If using an `avatarId`, the avatar's saved `ttsEmotionKey` is used as default. ###### Video Options - `prompt` is optional, description of the avatar's behavior/appearance. Maximum length: 2000 characters. If using an `avatarId`, the avatar's saved `prompt` is used as default. Default: "Natural speaking". - `mode` is optional, the video generation mode. Supported values: `std` (default), `pro`. `4k` is accepted for older integrations: it runs as `std` and the response lists that in `warnings`. ###### Scheduler Parameters - `maxJobs` is optional, range from `1` to `50`. Specifies the maximum number of concurrent jobs. - `replyUrl` is optional, a callback URL to receive generation progress and result. See [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id#model) for response model. - `replyRef` is optional, a reference identifier for the callback. ##### Responses **200** **200 OK** ```json { "task": { "id": 123456789, "userId": 12345, "type": "m2v_img2digital", "scene": "NORMAL_CREATION", "status": 5, "status_name": "submitted", "status_final": false, "taskInfo": { "type": "m2v_img2digital", "inputs": [ { "name": "image", "inputType": "URL", "url": "https://s21-kling.klingai.com/ai-platform/.../avatar.jpg" }, { "name": "audio", "inputType": "URL", "url": "https://s21-kling.klingai.com/ai-platform/.../audio.mp3" } ], "arguments": [ { "name": "prompt", "value": "Natural speaking" }, { "name": "upload_method", "value": "MY_AVATAR" }, { "name": "duration", "value": "5.234" }, { "name": "model_mode", "value": "std" } ] }, "createTime": 1736640000000, "updateTime": 1736640000000 }, "status": 5, "status_name": "submitted", "status_final": false } ``` When the request asks for `mode: 4k`, the video is generated in `std` and the response adds `"warnings": ["mode 4k is not available for avatar videos; it runs as std"]`. The field is left out when there is nothing to report. **400** **400 Bad Request** The parameters are invalid. When Kling refuses the submitted parameters, `error` carries Kling's own message. ```json { "error": "<error message>" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** ```json { "error": "<error message>" } ``` **412** **412 Precondition Failed** The Kling account named in `error` is out of credits, and Kling did not create a task. Add credits or upgrade the plan of that account on [kling.ai](https://kling.ai), or send the job to another account with `email`. `message` keeps Kling's own text. ```json { "error": "Kling account user@example.com is out of credits: Credit are insufficient, you can upgrade your membership or purchase credit. (TASK.PointNotEnough)", "message": "积分消费失败 (TASK.PointNotEnough)" } ``` ##### Model The new task, with its `task.id` and `status_name`: poll it with [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) until `status_final` is `true`. <details markdown="block" class="model-details"> <summary>The task record, field by field</summary> ```typescript { // TypeScript, all fields are optional task: { id: number userId: number type: string scene: string status: number status_name: 'submitted' | 'failed' | 'processing' | 'succeed' status_final: boolean taskInfo: { type: string inputs: { name: string, inputType: string, url: string }[] arguments: { name: string, value: string }[] } createTime: number updateTime: number } works: object[] status: number status_name: string status_final: boolean message: string warnings: string[] // only when a value of the request was run differently (mode 4k as std) } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/kling/avatars/video" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ..." \ -d '{ "email": "user@example.com", "avatarId": "123456789012", "text": "Welcome to our demo!", "speakerId": "speaker_id_123" }' ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const apiUrl = "https://api.useapi.net/v1/kling/avatars/video"; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ email: email, avatarId: "123456789012", text: "Welcome to our demo!", speakerId: "speaker_id_123" }) }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured account email" apiUrl = "https://api.useapi.net/v1/kling/avatars/video" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } data = { "email": email, "avatarId": "123456789012", "text": "Welcome to our demo!", "speakerId": "speaker_id_123" } response = requests.post(apiUrl, headers=headers, json=data) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-kling-v1/post-kling-avatars === Document URL: https://useapi.net/docs/api-kling-v1/post-kling-avatars --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> avatars description: "Create a Kling avatar (digital character) from an image via POST avatars in the useapi.net Kling API v1 — AI auto-fills most fields including TTS voice settings." parent: Kling API nav_order: 455 --- ## Create avatar January 12, 2026 (November 16, 2026) --- This endpoint creates a new avatar from an image. Avatars are digital characters that can be animated with lip-sync using [POST /avatars/video](/docs/api-kling-v1/post-kling-avatars-video). Most fields are optional and will be automatically populated using AI if not provided. The AI analyzes your image to suggest an appropriate nickname, description, scene, and TTS settings. > **https://api.useapi.net/v1/kling/avatars** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "email": "user@example.com", "imageUrl": "https://s21-kling.klingai.com/ai-platform/xxx/xxx.jpg" } ``` - `email` is optional. Leave it out and the job goes to one of your [accounts](/docs/api-kling-v1/get-kling-accounts) that has a free job slot, picked at random. Each account runs at most its `maxJobs` jobs at once, and [GET scheduler/available](/docs/api-kling-v1/get-kling-scheduler-available) shows the free slots. If no account has a free slot, the response is `429`. Pass `email` to run the job on that account (`429` if it is busy). Uploaded files, elements, voices, avatars and earlier tasks belong to one account, so pass the `email` of the account they came from. - `imageUrl` is **required**, the URL of the avatar image. You can upload images using [POST /assets](/docs/api-kling-v1/post-kling-assets) and use the returned URL here. ###### Optional Parameters (AI Auto-Populated) The following fields will be automatically filled by AI if not provided: - `nickname` is optional, display name for the avatar. Maximum length: 30 characters. - `prompt` is optional, description/prompt for the avatar. Maximum length: 2000 characters. Used as the default prompt when generating avatar videos. - `scene` is optional, the avatar's use case category. Supported values: `all`, `social_media`, `entertainment`, `advertising_marketing` (default), `business`, `education`, `virtual_idol`. - `ttsSpeaker` is optional, the TTS speaker ID for voice. Use [GET /tts/voices](/docs/api-kling-v1/get-kling-tts-voices) to get available speaker IDs. AI will recommend an appropriate voice if not provided. - `ttsSpeed` is optional, speech speed. Range: `0.8` to `2.0`. Default: `1`. - `ttsEmotionKey` is optional, speech emotion. Supported values: `neutral` (default), `happy`, `angry`, `sad`, `fearful`, `disgusted`, `surprised`. Note: Not all emotions are available for all speakers. Check [GET /tts/voices](/docs/api-kling-v1/get-kling-tts-voices) for each speaker's supported emotions. ##### Responses **200** **200 OK** ```json { "id": "300137233318846", "status": "SUCCESS" } ``` Use [GET /avatars](/docs/api-kling-v1/get-kling-avatars) to retrieve the full avatar details after creation. **400** **400 Bad Request** ```json { "error": "<error message>" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model The new avatar's `id` and a `status` of `SUCCESS` or `FAILED`. <details markdown="block" class="model-details"> <summary>The new avatar's id and status, field by field</summary> ```typescript { // TypeScript id: string status: 'SUCCESS' | 'FAILED' } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/kling/avatars" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ..." \ -d '{ "email": "user@example.com", "imageUrl": "https://s21-kling.klingai.com/ai-platform/xxx/xxx.jpg" }' ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const apiUrl = "https://api.useapi.net/v1/kling/avatars"; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ email: email, imageUrl: "https://s21-kling.klingai.com/ai-platform/xxx/xxx.jpg" }) }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured account email" apiUrl = "https://api.useapi.net/v1/kling/avatars" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } data = { "email": email, "imageUrl": "https://s21-kling.klingai.com/ai-platform/xxx/xxx.jpg" } response = requests.post(apiUrl, headers=headers, json=data) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-kling-v1/post-kling-elements === Document URL: https://useapi.net/docs/api-kling-v1/post-kling-elements --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> elements description: "Create reusable IMAGE or VIDEO elements from images or clips via POST elements in the useapi.net Kling API v1 — IMAGE elements work in O1, v3 and v4 Omni, VIDEO elements in v3 and v4 Omni." parent: Kling API nav_order: 426 --- ## Create element January 12, 2026 (November 16, 2026) --- This endpoint creates one or more elements from a cover image or video. Elements are saved character/object references that can be reused across multiple generations in [POST /images/omni](/docs/api-kling-v1/post-kling-images-omni) and [POST /videos/omni](/docs/api-kling-v1/post-kling-videos-omni) using the `@element_N` syntax. There are two element types: - **IMAGE** elements: Created from a `coverImage`, with optional multi-angle views - **VIDEO** elements: Created from a `video` URL (mp4, minimum 3 seconds, auto-trimmed to 8s), with optional voice assignment. VIDEO elements can be used in v3 and v4 video generation via [POST /videos/omni](/docs/api-kling-v1/post-kling-videos-omni). | Feature | IMAGE | VIDEO | |---------|:-----:|:-----:| | Input | `coverImage` | `video` (mp4, min 3s, auto-trimmed to 8s) | | `voice` support | Yes (character tag only) | Yes (character tag only) | | Auto voice extraction | No | Yes (character tag, 5-60s video) | | Custom voice from URL | Yes (mp4, 5-60s) | Yes (mp4, 5-60s) | | `extraImage1/2/3` | Yes | No | | `generateViews` | Yes | No | | Used in O1 omni | Yes | No | | Used in v3 and v4 omni | Yes | Yes | The `generateViews` option (IMAGE only) uses AI to create multiple variations of your element with different angles, which can produce up to 3 separate elements from a single image. You can review the results and delete ones you don't like using [DELETE /elements/`elementId`](/docs/api-kling-v1/del-kling-elements-elementId). Kling prices `generateViews` at 5 credits each time. While the account has free element uses left from Kling, it pays nothing: the Kling Pro account we checked had 3 free uses in October and November 2026. > **https://api.useapi.net/v1/kling/elements** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "email": "user@example.com", "name": "MyCharacter", "coverImage": "https://s21-kling.klingai.com/ai-platform/xxx/xxx.jpg", "tag": "character" } ``` - `email` is optional. Leave it out and the job goes to one of your [accounts](/docs/api-kling-v1/get-kling-accounts) that has a free job slot, picked at random. Each account runs at most its `maxJobs` jobs at once, and [GET scheduler/available](/docs/api-kling-v1/get-kling-scheduler-available) shows the free slots. If no account has a free slot, the response is `429`. Pass `email` to run the job on that account (`429` if it is busy). Uploaded files, elements, voices, avatars and earlier tasks belong to one account, so pass the `email` of the account they came from. - `name` is **required**, the base name for the element. Maximum length: 15 characters. A 5-character random suffix is automatically appended (e.g., "MyChar" becomes "MyChar ABC12"). - `coverImage` is required for IMAGE elements, the URL of the primary image. You can upload images using [POST /assets](/docs/api-kling-v1/post-kling-assets) and use the returned URL here. Cannot be used together with `video`. - `video` is required for VIDEO elements, the URL of a video (mp4 format, minimum 3 seconds). You can upload videos using [POST /assets](/docs/api-kling-v1/post-kling-assets) and use the returned URL here. The video is preprocessed to extract a cover frame and normalized video. Videos longer than 8 seconds are automatically trimmed. Minimum 700px shortest edge. Cannot be used together with `coverImage`. - `voice` is optional (`character` tag required), the voice to assign to the element. Accepts an official voice name/ID from [GET /elements/voices](/docs/api-kling-v1/get-kling-elements-voices), or a video URL (mp4, 5-60 seconds) to extract a custom voice from. For VIDEO elements without an explicit voice, voice extraction is automatically attempted from the video (requires 5-60 seconds with audio; silently skipped if video is too short). Voice is only supported for elements with the `character` tag. - `description` is optional, a text description of the element. Maximum length: 100 characters. If not provided, a description is automatically generated from the image using AI. - `tag` is optional, the category tag for the element. Use [GET /elements/tags](/docs/api-kling-v1/get-kling-elements-tags) to get available tags. Accepts either `id` or `tagKey` (e.g., "1" or "character"). If not provided, the tag is automatically detected from the image using AI. ###### Secondary Images (IMAGE only) You can optionally provide additional angle/view images: - `extraImage1` is optional, URL of first additional view. - `extraImage2` is optional, URL of second additional view. - `extraImage3` is optional, URL of third additional view. Maximum 3 secondary images allowed. Cannot be used together with `generateViews` or `video`. ###### Auto-Generate Views (IMAGE only) - `generateViews` is optional, set to `true` to have AI generate 3 multi-angle variations. When enabled, the system generates different views of your element automatically. This can create **up to 3 separate elements**, one for each variation group. Cannot be used together with `extraImage1/2/3` or `video`. This call can take up to 60 seconds to complete since generation takes time. ##### Responses **200** **200 OK** **Standard response (without generateViews):** ```json { "elements": [ { "id": "u_123456789012345", "name": "MyCharacter ABC12", "userId": 12345678, "description": "AI-generated description of the character", "cover": { "resource": "https://s21-kling.klingai.com/ai-platform/.../cover.jpg", "width": 768, "height": 1365, "resourceKey": "cover", "cover": true, "slotKey": "" }, "resources": [ { "resource": "https://s21-kling.klingai.com/ai-platform/.../cover.jpg", "width": 768, "height": 1365, "resourceKey": "cover", "cover": true, "slotKey": "" } ], "tagList": [], "createTime": 1736640000000, "updateTime": 1736640000000, "favored": false, "official": false } ], "count": 1 } ``` **Response with generateViews (creates up to 3 separate elements, each with 4 views):** ```json { "elements": [ { "id": "u_123456789012345", "name": "MyCharacter ABC12", "userId": 12345678, "description": "AI-generated description", "cover": { "resource": "https://s21-kling.klingai.com/ai-platform/.../cover.jpg", "resourceKey": "cover", "cover": true, "slotKey": "" }, "resources": [ { "resource": ".../cover.jpg", "resourceKey": "cover", "cover": true, "slotKey": "" }, { "resource": ".../side.png", "resourceKey": "secondary", "cover": false, "slotKey": "side" }, { "resource": ".../back.png", "resourceKey": "secondary", "cover": false, "slotKey": "back" }, { "resource": ".../top.png", "resourceKey": "secondary", "cover": false, "slotKey": "topView" } ], "tagList": [] }, { "id": "u_234567890123456", "name": "MyCharacter DEF34", "description": "AI-generated description", "resources": [ { "resource": ".../cover.jpg", "resourceKey": "cover", "cover": true, "slotKey": "" }, { "resource": ".../side.png", "resourceKey": "secondary", "cover": false, "slotKey": "side" }, { "resource": ".../back.png", "resourceKey": "secondary", "cover": false, "slotKey": "back" }, { "resource": ".../top.png", "resourceKey": "secondary", "cover": false, "slotKey": "topView" } ], "tagList": [] } ], "count": 2 } ``` **400** **400 Bad Request** ```json { "error": "<error message>" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model The created elements, each with its `id`, type, cover and resources, and their `count`. <details markdown="block" class="model-details"> <summary>The created elements, field by field</summary> ```typescript { // TypeScript, all fields are optional elements: { id: string name: string userId: number type: 'IMAGE' | 'VIDEO' description: string cover: { resource: string width: number height: number resourceKey: 'cover' | 'secondary' | 'video' cover: boolean slotKey: string } resources: { resource: string width: number height: number resourceKey: 'cover' | 'secondary' | 'video' cover: boolean slotKey: string voice: { id: number name: string official: boolean resource: object } }[] tagList: object[] voice: { id: number name: string official: boolean resource: object } currentVersion: number createTime: number updateTime: number favored: boolean official: boolean }[] count: number } ``` </details> ##### Usage After Creation Once created, you can use element IDs in [POST /images/omni](/docs/api-kling-v1/post-kling-images-omni), [POST /videos/omni](/docs/api-kling-v1/post-kling-videos-omni), and [POST /videos/motion-create](/docs/api-kling-v1/post-kling-videos-motion-create): ```json { "prompt": "Character @element_1 walking through a beautiful garden", "element_1": "u_123456789012345" } ``` ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/kling/elements" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ..." \ -d '{ "email": "user@example.com", "name": "FashionLady", "coverImage": "https://s21-kling.klingai.com/ai-platform/xxx/xxx.jpg", "tag": "character" }' ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const apiUrl = "https://api.useapi.net/v1/kling/elements"; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ email: email, name: "FashionLady", coverImage: "https://s21-kling.klingai.com/ai-platform/xxx/xxx.jpg", tag: "character" }) }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured account email" apiUrl = "https://api.useapi.net/v1/kling/elements" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } data = { "email": email, "name": "FashionLady", "coverImage": "https://s21-kling.klingai.com/ai-platform/xxx/xxx.jpg", "tag": "character" } response = requests.post(apiUrl, headers=headers, json=data) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-kling-v1/post-kling-images-enhance === Document URL: https://useapi.net/docs/api-kling-v1/post-kling-images-enhance --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> images/enhance description: "Enhance image quality and restore details at 2k or 4k with Kling's Image Enhancing via POST images/enhance in the useapi.net Kling API v1, from any image URL." parent: Kling API nav_order: 317 --- ## Enhance Images October 15, 2026 (November 16, 2026) --- This endpoint runs Kling's Image Enhancing, which enhances the quality of an image and restores its details. It takes any image URL, for example one uploaded via [POST /assets](/docs/api-kling-v1/post-kling-assets). [POST /images/upscale](/docs/api-kling-v1/post-kling-images-upscale) works only on an image Kling generated, identified by its `task_id` and `workId`. This endpoint takes any image URL instead. Enhancing costs 1 Kling credit at `2k` and 2 credits at `4k`. The output size depends on the input image. For example, an 800×1200 image came back as 1664×2496 with `2k`, and a 768×1344 image came back as 1536×2704 with `4k`. > **https://api.useapi.net/v1/kling/images/enhance** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "email": "user@example.com", "image": "https://s21-kling.klingai.com/ai-platform/xxx/xxx.jpg", "resolution": "2k" } ``` - `email` is optional. Leave it out and the job goes to one of your [accounts](/docs/api-kling-v1/get-kling-accounts) that has a free job slot, picked at random. Each account runs at most its `maxJobs` jobs at once, and [GET scheduler/available](/docs/api-kling-v1/get-kling-scheduler-available) shows the free slots. If no account has a free slot, the response is `429`. Pass `email` to run the job on that account (`429` if it is busy). Uploaded files, elements, voices, avatars and earlier tasks belong to one account, so pass the `email` of the account they came from. With more than one account, reading the task with [GET tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) needs its account's `email`. The response's `task.userId` is that account's `session.userId` in [GET accounts](/docs/api-kling-v1/get-kling-accounts), and [GET scheduler](/docs/api-kling-v1/get-kling-scheduler) lists each running task with its `email`. - `image` is **required**, the URL of the image to enhance. You can upload an image via [POST /assets](/docs/api-kling-v1/post-kling-assets) and use the returned URL. - `resolution` is optional. Supported values: `2k` (1 credit), `4k` (2 credits). Default: `2k`. - `maxJobs` is optional, range from `1` to `50`. Specifies the maximum number of concurrent jobs. - `replyUrl` is optional, a callback URL to receive generation progress and result. See [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id#model) for response model. - `replyRef` is optional, a reference identifier for the callback. ##### Responses **200** **200 OK** ```json { "task": { "id": 123456789, "userId": 12345, "type": "mmu_image_refiner", "scene": "NORMAL_CREATION", "status": 5, "status_name": "submitted", "status_final": false, "taskInfo": { "type": "mmu_image_refiner", "inputs": [ { "name": "input", "inputType": "URL", "token": null, "blobStorage": null, "url": "https://s21-kling.klingai.com/ai-platform/xxx/xxx.jpg", "cover": null, "fromWorkId": null } ], "arguments": [ { "name": "biz", "value": "klingai" }, { "name": "imageCount", "value": "1" }, { "name": "source", "value": "TOOLBOX" }, { "name": "img_resolution", "value": "2k" } ], "extraArgs": {}, "callbackPayloads": [], "scene": "NORMAL_CREATION" }, "favored": false, "deleted": false, "viewed": false, "createTime": 1760558400000, "updateTime": 1760558400000 }, "works": [], "status": 5, "status_name": "submitted", "status_final": false, "message": "", "userPoints": { "points": [], "total": 0 }, "userTickets": { "ticket": [] }, "editProject": null } ``` **400** **400 Bad Request** The parameters are invalid. When Kling refuses the submitted parameters, `error` carries Kling's own message. ```json { "error": "Parameter resolution (8k) valid values: 2k,4k" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **412** **412 Precondition Failed** The Kling account named in `error` is out of credits, and Kling did not create a task. Add credits or upgrade the plan of that account on [kling.ai](https://kling.ai), or send the job to another account with `email`. `message` keeps Kling's own text. ```json { "error": "Kling account user@example.com is out of credits: Credit are insufficient, you can upgrade your membership or purchase credit. (TASK.PointNotEnough)", "message": "积分消费失败 (TASK.PointNotEnough)" } ``` **500** **500 Internal Server Error** Kling uses a `500` response to indicate moderation and other issues with the input. It may be hard to separate actual 500 errors from moderation errors, so use the `error` field text and your best judgement to tell them apart, since the `message` field most often has very generic and perhaps misleading text. ```json { "error": "The content you uploaded appears to violate the community guidelines. (CM_EXT.POther)", "message": "Service busy (CM_EXT.POther)" } ``` When successful, the response includes a task ID which can be used to check the status using [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id). The enhanced image is in the `works` array once the task succeeds. ##### Model The new task, with its `task.id` and `status_name`: poll it with [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) until `status_final` is `true`. <details markdown="block" class="model-details"> <summary>The task record, field by field</summary> ```typescript { // TypeScript, all fields are optional task: { id: number userId: number type: string scene: string status: number status_name: 'submitted' | 'failed' | 'processing' | 'succeed' status_final: boolean taskInfo: { type: string inputs: Array<{ name: string inputType: string token: string | null blobStorage: any | null url: string cover: string | null fromWorkId: number | null }> arguments: Array<{ name: string value: string }> extraArgs: Record<string, any> callbackPayloads: any[] scene: string } favored: boolean deleted: boolean viewed: boolean createTime: number updateTime: number viewTime: number } works: Array<any> status: number status_name: 'submitted' | 'failed' | 'processing' | 'succeed' status_final: boolean message: string error: string userPoints: { points: Array<{ orderId: string type: string amount: number balance: number startTime: number endTime: number }> total: number } userTickets: { ticket: Array<{ orderId: string type: string packageType: string amount: number balance: number startTime: number endTime: number }> } editProject: any | null } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/kling/images/enhance" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "email": "user@example.com", "image": "https://s21-kling.klingai.com/ai-platform/xxx/xxx.jpg", "resolution": "4k" }' ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const apiUrl = "https://api.useapi.net/v1/kling/images/enhance"; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ email: email, image: "https://s21-kling.klingai.com/ai-platform/xxx/xxx.jpg", resolution: "4k" }) }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured account email" apiUrl = "https://api.useapi.net/v1/kling/images/enhance" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } data = { "email": email, "image": "https://s21-kling.klingai.com/ai-platform/xxx/xxx.jpg", "resolution": "4k" } response = requests.post(apiUrl, headers=headers, json=data) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-kling-v1/post-kling-images-kolors-elements === Document URL: https://useapi.net/docs/api-kling-v1/post-kling-images-kolors-elements --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> images/kolors-elements description: "Generate KOLORS v2.1 images from up to 4 subject images plus optional scene and style references via POST images/kolors-elements in the useapi.net Kling API v1." parent: Kling API nav_order: 313 --- ## Generate Images with KOLORS Elements July 18, 2025 (November 16, 2026) --- This endpoint generates images using Kling's KOLORS v2.1 with multiple image elements (up to 4 subject images, plus optional scene and style images) that will appear as elements in the generated image. This allows for more complex compositions with multiple reference images. > **https://api.useapi.net/v1/kling/images/kolors-elements** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "email": "user@example.com", "prompt": "A digital art gallery with modern paintings and sculptures on display", "subjectImage1": "https://example.com/painting1.jpg", "subjectImage2": "https://example.com/sculpture1.jpg", "subjectImage3": "https://example.com/painting2.jpg", "subjectImage4": "https://example.com/decoration.jpg", "sceneImage": "https://example.com/gallery-background.jpg", "styleImage": "https://example.com/art-style.jpg", "aspect_ratio": "16:9", "imageCount": 1, "replyUrl": "https://your-callback-url.com/webhook", "replyRef": "your-reference-id" } ``` - `email` is optional. Leave it out and the job goes to one of your [accounts](/docs/api-kling-v1/get-kling-accounts) that has a free job slot, picked at random. Each account runs at most its `maxJobs` jobs at once, and [GET scheduler/available](/docs/api-kling-v1/get-kling-scheduler-available) shows the free slots. If no account has a free slot, the response is `429`. Pass `email` to run the job on that account (`429` if it is busy). Uploaded files, elements, voices, avatars and earlier tasks belong to one account, so pass the `email` of the account they came from. With more than one account, reading the task with [GET tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) needs its account's `email`. The response's `task.userId` is that account's `session.userId` in [GET accounts](/docs/api-kling-v1/get-kling-accounts), and [GET scheduler](/docs/api-kling-v1/get-kling-scheduler) lists each running task with its `email`. - `prompt` is optional, the text description of the image to generate. Maximum length: 2500 characters. - `subjectImage1`, `subjectImage2`, `subjectImage3` and `subjectImage4` are optional URLs to subject images that will appear as elements in the generated image. Images can be uploaded using [POST /assets](/docs/api-kling-v1/post-kling-assets) and the returned URLs can be used here. - `sceneImage` is optional, URL to a scene/background image. Image can be uploaded using [POST /assets](/docs/api-kling-v1/post-kling-assets) and the returned URLs can be used here. - `styleImage` is optional, URL to a style reference image. Image can be uploaded using [POST /assets](/docs/api-kling-v1/post-kling-assets) and the returned URLs can be used here. - `aspect_ratio` is optional, the aspect ratio of the generated image. Supported values: `1:1`, `16:9` (default), `4:3`, `3:2`, `2:3`, `3:4`, `9:16`, `21:9`. - `imageCount` is optional, the number of images to generate. Range: `1` to `9`. Default: `1`. - `maxJobs` is optional, range from `1` to `50`. Specifies the maximum number of concurrent jobs. - `replyUrl` is optional, a callback URL to receive generation progress and result. See [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id#model) for response model. - `replyRef` is optional, a reference identifier for the callback. **Note:** At least two images must be provided (any combination of subjectImage1-4, sceneImage, or styleImage). ##### Responses **200** **200 OK** ```json { "task": { "id": 123456789, "userId": 12345, "type": "mmu_multi_img2img_aiweb", "scene": "NORMAL_CREATION", "status": 5, "status_name": "submitted", "status_final": false, "taskInfo": { "type": "mmu_multi_img2img_aiweb", "inputs": [ { "name": "subject_image_0", "inputType": "URL", "token": null, "blobStorage": null, "url": "https://example.com/painting1.jpg", "cover": null, "fromWorkId": null }, { "name": "raw_subject_image_0", "inputType": "URL", "token": null, "blobStorage": null, "url": "https://example.com/painting1.jpg", "cover": null, "fromWorkId": null }, { "name": "subject_image_1", "inputType": "URL", "token": null, "blobStorage": null, "url": "https://example.com/sculpture1.jpg", "cover": null, "fromWorkId": null }, { "name": "scene_image", "inputType": "URL", "token": null, "blobStorage": null, "url": "https://example.com/gallery-background.jpg", "cover": null, "fromWorkId": null } ], "arguments": [ { "name": "prompt", "value": "A digital art gallery with modern paintings and sculptures on display" }, { "name": "aspect_ratio", "value": "16:9" }, { "name": "imageCount", "value": "1" }, { "name": "kolors_version", "value": "2.1" }, { "name": "img_resolution", "value": "1k" }, { "name": "style", "value": "默认" }, { "name": "imageList", "value": "[{\"top\":0,\"left\":0,\"width\":1,\"height\":1},{\"top\":0,\"left\":0,\"width\":1,\"height\":1}]" }, { "name": "biz", "value": "klingai" } ], "extraArgs": {}, "callbackPayloads": [], "scene": "NORMAL_CREATION" }, "favored": false, "deleted": false, "viewed": false, "createTime": 1745376611075, "updateTime": 1745376611075 }, "works": [], "status": 5, "status_name": "submitted", "status_final": false, "message": "", "limitation": { "type": "mmu_multi_img2img_aiweb", "remaining": 10000, "limit": 10000 }, "userPoints": { "points": [], "total": 0 }, "userTickets": { "ticket": [] }, "editProject": null } ``` **400** **400 Bad Request** The parameters are invalid. When Kling refuses the submitted parameters, `error` carries Kling's own message. ```json { "error": "At least two images must be provided" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** Kling was unable to locate one of the referenced assets. Make sure to use [POST /assets](/docs/api-kling-v1/post-kling-assets) to upload assets. ```json { "error": "Sorry, the requested resource was not found (VALID.ResourceNotFound)", "message": "Not Found" } ``` **412** **412 Precondition Failed** The Kling account named in `error` is out of credits, and Kling did not create a task. Add credits or upgrade the plan of that account on [kling.ai](https://kling.ai), or send the job to another account with `email`. `message` keeps Kling's own text. ```json { "error": "Kling account user@example.com is out of credits: Credit are insufficient, you can upgrade your membership or purchase credit. (TASK.PointNotEnough)", "message": "积分消费失败 (TASK.PointNotEnough)" } ``` **500** **500 Internal Server Error** Kling uses a `500` response to indicate moderation and other issues with the input. It may be hard to separate actual 500 errors from moderation errors, so use the `error` field text and your best judgement to tell them apart, since the `message` field most often has very generic and perhaps misleading text. ```json { "error": "The content you uploaded appears to violate the community guidelines. (CM_EXT.POther)", "message": "Service busy (CM_EXT.POther)" } ``` When successful, the response includes a task ID which can be used to check the status using [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id). ##### Model The new task, with its `task.id` and `status_name`: poll it with [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) until `status_final` is `true`. <details markdown="block" class="model-details"> <summary>The task record, field by field</summary> ```typescript { // TypeScript, all fields are optional task: { id: number userId: number type: string scene: string status: number status_name: 'submitted' | 'failed' | 'processing' | 'succeed' status_final: boolean taskInfo: { type: string inputs: Array<{ name: string inputType: string token: string | null blobStorage: any | null url: string cover: string | null fromWorkId: number | null }> arguments: Array<{ name: string value: string }> extraArgs: Record<string, any> callbackPayloads: any[] scene: string } favored: boolean deleted: boolean viewed: boolean createTime: number updateTime: number viewTime: number } works: Array<any> status: number status_name: 'submitted' | 'failed' | 'processing' | 'succeed' status_final: boolean message: string error: string limitation: { type: string remaining: number limit: number } userPoints: { points: Array<{ orderId: string type: string amount: number balance: number startTime: number endTime: number }> total: number } userTickets: { ticket: Array<{ orderId: string type: string packageType: string amount: number balance: number startTime: number endTime: number }> } editProject: any | null } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/kling/images/kolors-elements" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "email": "user@example.com", "prompt": "A digital art gallery with modern paintings and sculptures on display", "subjectImage1": "https://example.com/painting1.jpg", "subjectImage2": "https://example.com/sculpture1.jpg", "sceneImage": "https://example.com/gallery-background.jpg" }' ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const apiUrl = "https://api.useapi.net/v1/kling/images/kolors-elements"; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ email: email, prompt: "A digital art gallery with modern paintings and sculptures on display", subjectImage1: "https://example.com/painting1.jpg", subjectImage2: "https://example.com/sculpture1.jpg", sceneImage: "https://example.com/gallery-background.jpg" }) }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured account email" apiUrl = "https://api.useapi.net/v1/kling/images/kolors-elements" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } data = { "email": email, "prompt": "A digital art gallery with modern paintings and sculptures on display", "subjectImage1": "https://example.com/painting1.jpg", "subjectImage2": "https://example.com/sculpture1.jpg", "sceneImage": "https://example.com/gallery-background.jpg" } response = requests.post(apiUrl, headers=headers, json=data) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-kling-v1/post-kling-images-kolors === Document URL: https://useapi.net/docs/api-kling-v1/post-kling-images-kolors --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> images/kolors description: "Generate images with KOLORS v3.0 (up to 10 reference images) or v2.1 (face, subject, restyle workflows) via POST images/kolors in the useapi.net Kling API v1." parent: Kling API nav_order: 312 --- ## Generate Images with KOLORS April 24, 2025 (November 16, 2026) --- This endpoint generates images using Kling's KOLORS. It supports KOLORS v3.0 for text-to-image with reference images, and KOLORS v2.1 for text-to-image with face, subject, and restyle reference workflows. **Note:** KOLORS v2.0, v1.6 and v1.5 have been retired by Kling from the website. Their features (restyle, face, subject) are now available under v2.1. The legacy versions are still accepted for backwards compatibility and, since February 9, 2026, run as v2.1. ##### Model Support Matrix | Feature | v3.0 | v2.1 | |---------|:----:|:----:| | Text-to-image | Yes | Yes | | Reference images (`image_1`-`image_10`) | Yes (up to 10) | No | | Face reference (`reference: face`) | No | Yes | | Subject reference (`reference: subject`) | No | Yes | | Restyle (`reference: restyle`) | No | Yes | | `resolution` | `1k`, `2k` (default) | `1k`, `2k` (default, text-to-image only) | | `aspect_ratio` default | `16:9` | `16:9` | | `imageCount` default | `2` | `1` | | `aspect_ratio: auto` | Yes (with images only) | No | > **https://api.useapi.net/v1/kling/images/kolors** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "email": "user@example.com", "prompt": "A woman @image_1 dancing elegantly in a ballroom", "version": "kling-v3-0", "resolution": "2k", "aspect_ratio": "3:4", "imageCount": 2, "image_1": "https://s21-kling.klingai.com/ai-platform/xxx/xxx.jpg" } ``` - `email` is optional. Leave it out and the job goes to one of your [accounts](/docs/api-kling-v1/get-kling-accounts) that has a free job slot, picked at random. Each account runs at most its `maxJobs` jobs at once, and [GET scheduler/available](/docs/api-kling-v1/get-kling-scheduler-available) shows the free slots. If no account has a free slot, the response is `429`. Pass `email` to run the job on that account (`429` if it is busy). Uploaded files, elements, voices, avatars and earlier tasks belong to one account, so pass the `email` of the account they came from. With more than one account, reading the task with [GET tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) needs its account's `email`. The response's `task.userId` is that account's `session.userId` in [GET accounts](/docs/api-kling-v1/get-kling-accounts), and [GET scheduler](/docs/api-kling-v1/get-kling-scheduler) lists each running task with its `email`. - `prompt` is **required**, the text description of the image to generate. Maximum length: 2500 characters. For v3, use `@image_1`, `@image_2`, etc. to reference images in your prompt. - `version` is optional, the KOLORS model version to use. Supported values: `kling-v3-0` (default), `kling-v2-1`. Legacy (retired): `kling-v1-5`, `kling-v1-6`, `kling-v2-0` — still accepted for backwards compatibility and run as `kling-v2-1`. - `resolution` is optional, the resolution of the generated image. Supported values: `1k`, `2k` (default). Only available for v3.0 and v2.1 text-to-image (`reference: none`). Not supported by subject/face/restyle. ###### v3 Parameters - `image_1` through `image_10` are optional (v3 only), URLs of reference images. You can upload images using [POST /assets](/docs/api-kling-v1/post-kling-assets). Reference in prompt using `@image_1`, `@image_2`, etc. **Note:** v3 does not support `reference`, `imageReference`, `faceStrength`, `subjectStrength`, or `faceNo` parameters. ###### v3 Aspect Ratios When using `version: kling-v3-0`, the supported aspect ratios are: `9:16`, `2:3`, `3:4`, `1:1`, `4:3`, `3:2`, `16:9` (default), `21:9`, `auto` (with images only). ###### v2.1 Reference Parameters - `reference` is optional, the type of reference to use (v2.1). Supported values: - `none` (default) — text-to-image - `subject` — subject similarity reference - `face` — face similarity reference - `restyle` — style transfer from reference image - `imageReference` is required if `reference` is not `none`, the URL of the reference image. You can upload images using [POST /assets](/docs/api-kling-v1/post-kling-assets) and use the returned URL here. - `aspect_ratio` is optional, the aspect ratio of the generated image. Not supported by `restyle` reference type. Supported values: `1:1`, `16:9` (default), `4:3`, `3:2`, `2:3`, `3:4`, `9:16`, `21:9`. - `imageCount` is optional, the number of images to generate. Range: `1` to `9`. Default: `1` (v3 default: `2`). - `faceStrength` is optional, the strength of face similarity for both `face` and `subject` reference types. Range: `1` to `100`. Default: `65`. - `subjectStrength` is optional, the strength of subject similarity for `subject` reference type. Range: `1` to `100`. Default: `50`. - `faceNo` is optional, the index of the face to use in multi-face images for `face` reference type. Default: `1`. You can use [POST /images/recognize-faces](/docs/api-kling-v1/post-kling-images-recognize-faces) to detect faces in an image. ###### Scheduler Parameters - `maxJobs` is optional, range from `1` to `50`. Specifies the maximum number of concurrent jobs. - `replyUrl` is optional, a callback URL to receive generation progress and result. See [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id#model) for response model. - `replyRef` is optional, a reference identifier for the callback. ##### Responses **200** **200 OK** ```json { "task": { "id": 123456789, "userId": 12345, "type": "mmu_img2img_aiweb", "scene": "NORMAL_CREATION", "status": 5, "status_name": "submitted", "status_final": false, "taskInfo": { "type": "mmu_img2img_aiweb", "inputs": [ { "name": "input", "inputType": "URL", "token": null, "blobStorage": null, "url": "https://example.com/face.jpg", "cover": null, "fromWorkId": null }, { "name": "feature", "inputType": "URL", "token": null, "blobStorage": null, "url": "https://s21-kling.klingai.com/....jpg", "cover": null, "fromWorkId": null } ], "arguments": [ { "name": "prompt", "value": "Portrait of a woman with blue eyes, detailed, photorealistic" }, { "name": "aspect_ratio", "value": "16:9" }, { "name": "imageCount", "value": "1" }, { "name": "kolors_version", "value": "2.1" }, { "name": "fidelity", "value": "0.65" }, { "name": "style", "value": "默认" }, { "name": "faceBound", "value": "{\"x\":120,\"y\":80,\"width\":200,\"height\":240}" }, { "name": "referenceType", "value": "mmu_img2img_aiweb_v15_character" }, { "name": "biz", "value": "klingai" } ], "extraArgs": {}, "callbackPayloads": [ { "name": "face_count", "value": "1" }, { "name": "referenceImageWidth", "value": "724" }, { "name": "referenceImageHeight", "value": "1268" } ], "scene": "NORMAL_CREATION" }, "favored": false, "deleted": false, "viewed": false, "createTime": 1745376611075, "updateTime": 1745376611075 }, "works": [], "status": 5, "status_name": "submitted", "status_final": false, "message": "", "limitation": { "type": "mmu_img2img_aiweb", "remaining": 10000, "limit": 10000 }, "userPoints": { "points": [], "total": 0 }, "userTickets": { "ticket": [] }, "editProject": null } ``` **400** **400 Bad Request** The parameters are invalid. When Kling refuses the submitted parameters, `error` carries Kling's own message. ```json { "error": "reference \"face\" does not support subjectStrength" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** Kling was unable to locate one of the referenced assets. Make sure to use [POST /assets](/docs/api-kling-v1/post-kling-assets) to upload assets. ```json { "error": "Sorry, the requested resource was not found (VALID.ResourceNotFound)", "message": "Not Found" } ``` **412** **412 Precondition Failed** The Kling account named in `error` is out of credits, and Kling did not create a task. Add credits or upgrade the plan of that account on [kling.ai](https://kling.ai), or send the job to another account with `email`. `message` keeps Kling's own text. ```json { "error": "Kling account user@example.com is out of credits: Credit are insufficient, you can upgrade your membership or purchase credit. (TASK.PointNotEnough)", "message": "积分消费失败 (TASK.PointNotEnough)" } ``` **500** **500 Internal Server Error** Kling uses a `500` response to indicate moderation and other issues with the input. It may be hard to separate actual 500 errors from moderation errors, so use the `error` field text and your best judgement to tell them apart, since the `message` field most often has very generic and perhaps misleading text. ```json { "error": "The content you uploaded appears to violate the community guidelines. (CM_EXT.POther)", "message": "Service busy (CM_EXT.POther)" } ``` When successful, the response includes a task ID which can be used to check the status using [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id). ##### Model The new task, with its `task.id` and `status_name`: poll it with [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) until `status_final` is `true`. <details markdown="block" class="model-details"> <summary>The task record, field by field</summary> ```typescript { // TypeScript, all fields are optional task: { id: number userId: number type: string scene: string status: number status_name: 'submitted' | 'failed' | 'processing' | 'succeed' status_final: boolean taskInfo: { type: string inputs: Array<{ name: string inputType: string token: string | null blobStorage: any | null url: string cover: string | null fromWorkId: number | null }> arguments: Array<{ name: string value: string }> extraArgs: Record<string, any> callbackPayloads: any[] scene: string } favored: boolean deleted: boolean viewed: boolean createTime: number updateTime: number viewTime: number } works: Array<any> status: number status_name: 'submitted' | 'failed' | 'processing' | 'succeed' status_final: boolean message: string error: string limitation: { type: string remaining: number limit: number } userPoints: { points: Array<{ orderId: string type: string amount: number balance: number startTime: number endTime: number }> total: number } userTickets: { ticket: Array<{ orderId: string type: string packageType: string amount: number balance: number startTime: number endTime: number }> } editProject: any | null } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/kling/images/kolors" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "email": "user@example.com", "prompt": "Portrait of a woman with blue eyes, detailed, photorealistic", "reference": "face", "imageReference": "https://example.com/face.jpg", "faceStrength": 65, "faceNo": 1 }' ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const apiUrl = "https://api.useapi.net/v1/kling/images/kolors"; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ email: email, prompt: "Portrait of a woman with blue eyes, detailed, photorealistic", reference: "face", imageReference: "https://example.com/face.jpg", faceStrength: 65, faceNo: 1 }) }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured account email" apiUrl = "https://api.useapi.net/v1/kling/images/kolors" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } data = { "email": email, "prompt": "Portrait of a woman with blue eyes, detailed, photorealistic", "reference": "face", "imageReference": "https://example.com/face.jpg", "faceStrength": 65, "faceNo": 1 } response = requests.post(apiUrl, headers=headers, json=data) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-kling-v1/post-kling-images-omni === Document URL: https://useapi.net/docs/api-kling-v1/post-kling-images-omni --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> images/omni description: "Generate images with Kling Image 4.0 via POST images/omni in the useapi.net Kling API v1 — 8K, Series Mode, product pages, web designs and prompt presets, plus Omni 3.0 and O1." parent: Kling API nav_order: 310 --- ## Generate Images with Omni December 10, 2025 (November 19, 2026) --- This endpoint generates images with Kling Image 4.0 (`v4`), Omni 3.0 (`v3`) and Omni O1 (`o1`), from a prompt and up to 10 reference images and saved elements named in it. Kling Image 4.0 adds 8K images, Series Mode from the prompt alone, style, tone and font presets in the prompt, and two design skills that each make one long page image: a product detail page from a product photo, and a web page design. ##### Version Comparison | Feature | v4 (Kling Image 4.0) | v3 | O1 | |---------|:--:|:--:|:--:| | Resolution | `2k`, `4k` (VIP), `8k` (VIP) | `1k`, `2k`, `4k` (VIP) | `1k`, `2k` | | Default `resolution` | `2k` | `1k` | `1k` | | Default `aspect_ratio` | `auto` | `auto` | `16:9` | | `auto` aspect ratio | Yes | Yes | No | | `story_mode` (Series Mode) | Yes 2 to 10 images, with or without references | Yes with a reference | No | | Style, tone and font presets | Yes | No | No | | `skill`: product detail page, web design | Yes | No | No | | Credits per image | 4 at 2K, 6 at 4K, 10 at 8K | 1 at 1K, 2 at 2K, 4 at 4K | 1 | Prices for every plan are in the [Kling price calculator](/docs/api-kling-v1#pricing). > **https://api.useapi.net/v1/kling/images/omni** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "email": "user@example.com", "prompt": "@tone:Morandi_Palette A woman @image_1 dancing elegantly in a ballroom", "omni_version": "v4", "resolution": "4k", "aspect_ratio": "16:9", "imageCount": 2, "image_1": "https://s21-kling.klingai.com/ai-platform/xxx/xxx.jpg" } ``` - `email` is optional. Leave it out and the job goes to one of your [accounts](/docs/api-kling-v1/get-kling-accounts) that has a free job slot, picked at random. Each account runs at most its `maxJobs` jobs at once, and [GET scheduler/available](/docs/api-kling-v1/get-kling-scheduler-available) shows the free slots. If no account has a free slot, the response is `429`. Pass `email` to run the job on that account (`429` if it is busy). Uploaded files, elements, voices, avatars and earlier tasks belong to one account, so pass the `email` of the account they came from. With more than one account, reading the task with [GET tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) needs its account's `email`. The response's `task.userId` is that account's `session.userId` in [GET accounts](/docs/api-kling-v1/get-kling-accounts), and [GET scheduler](/docs/api-kling-v1/get-kling-scheduler) lists each running task with its `email`. - `prompt` is **required**, the text description of the image to generate. Maximum length: 1700 characters. Use `@image_1`, `@image_2`, etc. to reference images in your prompt. Use `@element_1`, `@element_2`, etc. (or `@object_1`, etc.) to reference saved elements. With `v4` the prompt can also name [presets](#presets-v4): `@style:<id>`, `@tone:<id>` and `@font:<id>`. Put text that should appear in the image in quotation marks. - `omni_version` is optional, the Omni model version to use. Supported values: `o1`, `v3` (default), `v4` (Kling Image 4.0). - `resolution` is optional, the resolution of the generated image. `v4`: `2k` (default), `4k` (**VIP required**), `8k` (**VIP required**). With a `skill`: `1k` or `2k` (default). `v3`: `1k` (default), `2k`, `4k` (**VIP required**). `o1`: `1k` (default), `2k`. - `aspect_ratio` is optional, the aspect ratio of the generated image. Supported values: `auto` (v4 and v3), `16:9` (default for O1), `9:16`, `1:1`, `4:3`, `3:4`, `3:2`, `2:3`, `21:9`. v4 and v3 default to `auto`. `auto` is NOT available for O1. Not used with a `skill`. - `imageCount` is optional, the number of images to generate. Range: `1` to `10`. Default: `1`. Up to `9`, and up to `10` only in a `v4` Series Mode: with `v4` and `story_mode` it is `2` to `10`, or leave it out and Kling decides how many images the series needs (each image is charged). - `story_mode` is optional, enables Series Mode for coherent multi-image generation (v4 and v3). A Series Mode generates a coherent set of images, like the panels of a story, rather than independent images. `v3` requires at least one reference image or element. `v4` also makes a series from the prompt alone. Default: `false`. - `skill` is optional, a Kling Image 4.0 design skill (`v4` only). It makes one long page image instead of `imageCount` images. Supported values: `product_detail`, `web_design`. - `product_detail` makes a product detail page from your product photo in `image_1`, which is **required**. - `web_design` makes a web page design. `image_1` is optional, a style reference for the page. Kling writes the page's text in Chinese unless the prompt names the language, so end the prompt with, for example, "All text on the page in English." With a `skill`, `resolution` is `1k` or `2k` (default) and `imageCount` is `1`. `aspect_ratio`, `story_mode`, `unlimited`, `image_2` to `image_10`, elements and presets are not used. - `length` is optional, the length of the product detail page (`skill` `product_detail` only). Supported values: `short` (2 to 5 sections), `medium` (default, 6 to 10 sections), `long` (11 to 18 sections). - `unlimited` is optional, enables unlimited generation mode for eligible Pro and above accounts (subscribed prior December 15, 2025). Default: `false`. ###### Reference Images - `image_1` through `image_10` are optional, URLs of reference images. You can upload images using [POST /assets](/docs/api-kling-v1/post-kling-assets). Reference in prompt using `@image_1`, `@image_2`, etc. ###### Saved Elements - `element_1` through `element_10` are optional, IDs of saved elements. Create elements using [POST /elements](/docs/api-kling-v1/post-kling-elements). Reference in prompt using `@element_1` or `@object_1`, etc. **Note:** Images and elements share the same pool of 10 slots. Combined total cannot exceed 10. ###### Prompt Reference Syntax | Input Type | Prompt Syntax | Example | |------------|---------------|---------| | Images | `@image_1`, `@image_2`, ... | `"A woman @image_1 in a ballroom"` | | Elements | `@element_1` or `@object_1`, ... | `"Character @element_1 sitting..."` | | Style preset (v4) | `@style:<id>` | `"@style:3d_cartoon_pro a fox on a skateboard"` | | Tone preset (v4) | `@tone:<id>` | `"@tone:Nostalgic_Wuxia a swordsman in the rain"` | | Font preset (v4) | `@font:<id>` before the quoted text | `"a cafe sign that reads @font:elegant_brush_hand \"Jade Dragon\""` | ###### Presets (v4) Kling Image 4.0 has three kinds of presets you can name in the prompt. [GET images/presets](/docs/api-kling-v1/get-kling-images-presets) lists the current ones with their ids and sample images. - A style (`@style:<id>`) sets the look of the image: 3D, 2D, material craft or photography styles. It is sent to Kling as the style's name, the same as writing that name in the prompt. - A tone (`@tone:<id>`) applies one of Kling's color and lighting presets: director styles, camera simulation, classic styles, advanced color and visual lighting. - A font (`@font:<id>`) sets the lettering of the quoted text that follows it. Fonts come in English, Japanese, Korean and Chinese. An unknown id is refused with `400`, before anything is sent to Kling. ###### Scheduler Parameters - `maxJobs` is optional, range from `1` to `50`. Specifies the maximum number of concurrent jobs. - `replyUrl` is optional, a callback URL to receive generation progress and result. See [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id#model) for response model. - `replyRef` is optional, a reference identifier for the callback. ##### Responses **200** **200 OK** ```json { "task": { "id": 123456789, "userId": 12345, "type": "mmu_omni_image", "scene": "NORMAL_CREATION", "status": 5, "status_name": "submitted", "status_final": false, "taskInfo": { "type": "mmu_omni_image", "inputs": [ { "name": "image_1", "inputType": "URL", "token": null, "blobStorage": null, "url": "https://s21-kling.klingai.com/ai-platform/xxx/xxx.jpg", "cover": null, "fromWorkId": null } ], "arguments": [ { "name": "prompt", "value": "A woman Image1 dancing elegantly in a ballroom" }, { "name": "rich_prompt", "value": "A woman <<<image_1>>> dancing elegantly in a ballroom" }, { "name": "kolors_version", "value": "3.0-omni" }, { "name": "img_resolution", "value": "2k" }, { "name": "aspect_ratio", "value": "16:9" }, { "name": "imageCount", "value": "1" } ], "extraArgs": {}, "callbackPayloads": [], "scene": "NORMAL_CREATION" }, "favored": false, "deleted": false, "viewed": false, "createTime": 1733836800000, "updateTime": 1733836800000 }, "works": [], "status": 5, "status_name": "submitted", "status_final": false, "message": "", "limitation": { "type": "mmu_omni_image", "remaining": 10000, "limit": 10000 }, "userPoints": { "points": [], "total": 0 }, "userTickets": { "ticket": [] }, "editProject": null } ``` **400** **400 Bad Request** The parameters are invalid. When Kling refuses the submitted parameters, `error` carries Kling's own message. ```json { "error": "<error message>" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** ```json { "error": "<error message>" } ``` **412** **412 Precondition Failed** The Kling account named in `error` is out of credits, and Kling did not create a task. Add credits or upgrade the plan of that account on [kling.ai](https://kling.ai), or send the job to another account with `email`. `message` keeps Kling's own text. ```json { "error": "Kling account user@example.com is out of credits: Credit are insufficient, you can upgrade your membership or purchase credit. (TASK.PointNotEnough)", "message": "积分消费失败 (TASK.PointNotEnough)" } ``` **500** **500 Internal Server Error** Kling uses a `500` response to indicate moderation and other issues with the input. It may be hard to separate actual 500 errors from moderation errors, so use the `error` field text and your best judgement to tell them apart, since the `message` field most often has very generic and perhaps misleading text. ```json { "error": "The content you uploaded appears to violate the community guidelines. (CM_EXT.POther)", "message": "Service busy (CM_EXT.POther)" } ``` When successful, the response includes a task ID which can be used to check the status using [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id). A `skill` task has `task.type` `design_ecommerce_detail` (product detail page) or `design_web_design` (web design) and makes one tall image, for example 2048 x 13084 pixels for a 2K web design. ##### Model The new task, with its `task.id` and `status_name`: poll it with [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) until `status_final` is `true`. <details markdown="block" class="model-details"> <summary>The task record, field by field</summary> ```typescript { // TypeScript, all fields are optional task: { id: number userId: number type: string scene: string status: number status_name: 'submitted' | 'failed' | 'processing' | 'succeed' status_final: boolean taskInfo: { type: string inputs: Array<{ name: string inputType: string token: string | null blobStorage: any | null url: string cover: string | null fromWorkId: number | null }> arguments: Array<{ name: string value: string }> extraArgs: Record<string, any> callbackPayloads: any[] scene: string } favored: boolean deleted: boolean viewed: boolean createTime: number updateTime: number viewTime: number } works: Array<any> status: number status_name: 'submitted' | 'failed' | 'processing' | 'succeed' status_final: boolean message: string error: string limitation: { type: string remaining: number limit: number } userPoints: { points: Array<{ orderId: string type: string amount: number balance: number startTime: number endTime: number }> total: number } userTickets: { ticket: Array<{ orderId: string type: string packageType: string amount: number balance: number startTime: number endTime: number }> } editProject: any | null } ``` </details> ##### Examples **Curl** ``` bash # Using reference image curl -X POST "https://api.useapi.net/v1/kling/images/omni" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ..." \ -d '{ "email": "user@example.com", "prompt": "A woman @image_1 dancing elegantly in a ballroom", "resolution": "2k", "aspect_ratio": "16:9", "image_1": "https://s21-kling.klingai.com/ai-platform/xxx/xxx.jpg" }' # Using story_mode (Series Mode) for coherent multi-image generation curl -X POST "https://api.useapi.net/v1/kling/images/omni" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ..." \ -d '{ "email": "user@example.com", "prompt": "A series of @image_1 in different seasons", "resolution": "2k", "aspect_ratio": "16:9", "imageCount": 3, "story_mode": true, "image_1": "https://s21-kling.klingai.com/ai-platform/xxx/xxx.jpg" }' # Using saved element curl -X POST "https://api.useapi.net/v1/kling/images/omni" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ..." \ -d '{ "email": "user@example.com", "prompt": "Character @element_1 in a garden setting", "resolution": "2k", "aspect_ratio": "16:9", "element_1": "u_123456789012345" }' # Kling Image 4.0 at 8K curl -X POST "https://api.useapi.net/v1/kling/images/omni" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ..." \ -d '{ "prompt": "Macro photo of a dew-covered spider web at sunrise, every droplet catching the light", "omni_version": "v4", "resolution": "8k", "aspect_ratio": "16:9" }' # Kling Image 4.0 Series Mode from the prompt alone, Kling decides how many images curl -X POST "https://api.useapi.net/v1/kling/images/omni" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ..." \ -d '{ "prompt": "A four-panel story: a paper boat sails down a rainy city gutter, reaches a river and finally the sea", "omni_version": "v4", "story_mode": true }' # Kling Image 4.0 with a tone preset and a font preset (ids from GET images/presets) curl -X POST "https://api.useapi.net/v1/kling/images/omni" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ..." \ -d '{ "prompt": "@tone:Morandi_Palette A small tea house at dusk with a wooden sign that reads @font:elegant_brush_hand \"Jade Dragon\"", "omni_version": "v4" }' # Kling Image 4.0 skill: a long product detail page from a product photo curl -X POST "https://api.useapi.net/v1/kling/images/omni" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ..." \ -d '{ "prompt": "Insulated steel water bottle: keeps drinks cold 24 hours, leak-proof lid, fits car cup holders", "omni_version": "v4", "skill": "product_detail", "length": "short", "image_1": "https://s21-kling.klingai.com/ai-platform/xxx/xxx.jpg" }' # Kling Image 4.0 skill: a web page design curl -X POST "https://api.useapi.net/v1/kling/images/omni" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ..." \ -d '{ "prompt": "Landing page for a small-batch coffee roaster: warm browns, serif headlines, a subscription offer", "omni_version": "v4", "skill": "web_design" }' ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const apiUrl = "https://api.useapi.net/v1/kling/images/omni"; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ email: email, prompt: "@tone:Morandi_Palette Character @element_1 in a garden setting", omni_version: "v4", resolution: "4k", aspect_ratio: "16:9", element_1: "u_123456789012345" }) }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured account email" apiUrl = "https://api.useapi.net/v1/kling/images/omni" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } data = { "email": email, "prompt": "@tone:Morandi_Palette Character @element_1 in a garden setting", "omni_version": "v4", "resolution": "4k", "aspect_ratio": "16:9", "element_1": "u_123456789012345" } response = requests.post(apiUrl, headers=headers, json=data) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-kling-v1/post-kling-images-recognize-faces === Document URL: https://useapi.net/docs/api-kling-v1/post-kling-images-recognize-faces --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> images/recognize-faces description: "Detect faces in an image and return their positions and features for free via POST images/recognize-faces in the useapi.net Kling API v1." parent: Kling API nav_order: 314 --- ## Detect Faces in Images April 24, 2025 (November 16, 2026) --- This endpoint detects faces in the provided image and returns face information, including positions and features. This is useful for identifying facial features prior to using them with [POST /images/kolors](/docs/api-kling-v1/post-kling-images-kolors) with the `face` reference type. You can execute an unlimited number of face detections for **free**. This feature is available for all Kling subscription plans, including the free one. > **https://api.useapi.net/v1/kling/images/recognize-faces** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "email": "user@example.com", "imageReference": "https://example.com/image.jpg" } ``` - `email` is optional. Leave it out and the job goes to one of your [accounts](/docs/api-kling-v1/get-kling-accounts) that has a free job slot, picked at random. Each account runs at most its `maxJobs` jobs at once, and [GET scheduler/available](/docs/api-kling-v1/get-kling-scheduler-available) shows the free slots. If no account has a free slot, the response is `429`. Pass `email` to run the job on that account (`429` if it is busy). Uploaded files, elements, voices, avatars and earlier tasks belong to one account, so pass the `email` of the account they came from. - `imageReference` is **required**, the URL of the image to analyze. You can upload images using [POST /assets](/docs/api-kling-v1/post-kling-assets) and use the returned URL here. ##### Responses **200** **200 OK** ```json { "status": 0, "message": "", "faceItems": [ { "name": "face_0", "resources": [ { "name": "face", "type": "image", "url": "https://s21-kling.klingai.com/...face_0.jpg", "marginTop": 0, "countInRow": 1 }, { "name": "face_feature", "type": "image", "url": "https://s21-kling.klingai.com/...face_feature_0.jpg", "marginTop": 0, "countInRow": 1 } ], "arguments": [ { "name": "face_bound", "value": "{\"x\":120,\"y\":80,\"width\":200,\"height\":240}" } ] } ], "mediaInfo": { "type": "image", "duration": 0, "width": 724, "height": 1268 } } ``` **400** **400 Bad Request** ```json { "error": "Parameter imageReference is required" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **500** **500 Internal Server Error** Kling uses a `500` response to indicate moderation and other issues with the input. It may be hard to separate actual 500 errors from moderation errors, so use the `error` field text and your best judgement to tell them apart, since the `message` field most often has very generic and perhaps misleading text. ```json { "error": "The content you uploaded appears to violate the community guidelines. (CM_EXT.POther)", "message": "Service busy (CM_EXT.POther)" } ``` If the response contains `faceItems`, it means faces were detected in the image. Each face is listed with its position and features. The response will include: - `status`: 0 indicates success - `faceItems`: An array of detected faces, each with: - `resources`: Face images and feature information - `arguments`: Contains face bounding box coordinates - `mediaInfo`: Information about the original image ##### Model Each face found in the image, with its face image URLs and bounds, plus the image's width and height. <details markdown="block" class="model-details"> <summary>The detected faces, field by field</summary> ```typescript { // TypeScript, all fields are optional status: number // 0 for success message: string // Empty string on success, error message otherwise error: string faceItems?: { name: string // Face identifier (e.g., "face_0") resources: { name: string // Resource type identifier (e.g., "face", "face_feature") type: string // Resource type (typically "image") url: string // URL to the resource marginTop: number // Display margin countInRow: number // Display count in row }[] arguments: { name: string // Argument name (e.g., "face_bound") value: string // JSON string with facial bounds coordinates }[] }[] mediaInfo: { type: string // Media type (typically "image") duration: number // Duration for video (0 for image) width: number // Image width in pixels height: number // Image height in pixels } } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/kling/images/recognize-faces" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "email": "user@example.com", "imageReference": "https://example.com/image.jpg" }' ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const apiUrl = "https://api.useapi.net/v1/kling/images/recognize-faces"; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ email: email, imageReference: "https://example.com/image.jpg" }) }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured account email" apiUrl = "https://api.useapi.net/v1/kling/images/recognize-faces" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } data = { "email": email, "imageReference": "https://example.com/image.jpg" } response = requests.post(apiUrl, headers=headers, json=data) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-kling-v1/post-kling-images-upscale === Document URL: https://useapi.net/docs/api-kling-v1/post-kling-images-upscale --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> images/upscale description: "Upscale a previously generated Kling image to higher resolution by task ID and work ID via POST images/upscale in the useapi.net Kling API v1." parent: Kling API nav_order: 316 --- ## Upscale Images April 24, 2025 (November 16, 2026) --- This endpoint upscales previously generated images to higher resolution. It takes a task ID and work ID from a completed task, and creates a new upscaled version of the specified image. To improve the quality of any image by its URL, including one Kling did not generate, use [POST /images/enhance](/docs/api-kling-v1/post-kling-images-enhance). > **https://api.useapi.net/v1/kling/images/upscale** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "email": "user@example.com", "task_id": "123456789", "workId": "987654321" } ``` - `email` is optional. Leave it out and the job goes to one of your [accounts](/docs/api-kling-v1/get-kling-accounts) that has a free job slot, picked at random. Each account runs at most its `maxJobs` jobs at once, and [GET scheduler/available](/docs/api-kling-v1/get-kling-scheduler-available) shows the free slots. If no account has a free slot, the response is `429`. Pass `email` to run the job on that account (`429` if it is busy). Uploaded files, elements, voices, avatars and earlier tasks belong to one account, so pass the `email` of the account they came from. With more than one account, reading the task with [GET tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) needs its account's `email`. The response's `task.userId` is that account's `session.userId` in [GET accounts](/docs/api-kling-v1/get-kling-accounts), and [GET scheduler](/docs/api-kling-v1/get-kling-scheduler) lists each running task with its `email`. - `task_id` is **required**, the ID of a completed task that generated the image. Must be in the `succeed` status, which can be checked using [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id). - `workId` is **required**, the ID of the specific image from the task to upscale. Can be found in the `works` array of the [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) response. - `maxJobs` is optional, range from `1` to `50`. Specifies the maximum number of concurrent jobs. - `replyUrl` is optional, a callback URL to receive generation progress and result. See [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id#model) for response model. - `replyRef` is optional, a reference identifier for the callback. ##### Responses **200** **200 OK** ```json { "task": { "id": 123456789, "userId": 12345, "type": "mmu_image_upscale_aiweb", "scene": "NORMAL_CREATION", "status": 5, "status_name": "submitted", "status_final": false, "taskInfo": { "type": "mmu_image_upscale_aiweb", "inputs": [ { "name": "input", "inputType": "URL", "token": null, "blobStorage": null, "url": "https://s21-kling.klingai.com/....jpg", "cover": null, "fromWorkId": 987654321 } ], "arguments": [ { "name": "biz", "value": "klingai" }, { "name": "__initialType", "value": "mmu_img2img_aiweb" }, { "name": "__initialPrompt", "value": "Portrait of a woman with blue eyes" } ], "extraArgs": {}, "callbackPayloads": [], "scene": "NORMAL_CREATION" }, "favored": false, "deleted": false, "viewed": false, "createTime": 1745376611075, "updateTime": 1745376611075 }, "works": [], "status": 5, "status_name": "submitted", "status_final": false, "message": "", "limitation": { "type": "mmu_image_upscale_aiweb", "remaining": 10000, "limit": 10000 }, "userPoints": { "points": [], "total": 0 }, "userTickets": { "ticket": [] }, "editProject": null } ``` **400** **400 Bad Request** The parameters are invalid. When Kling refuses the submitted parameters, `error` carries Kling's own message. ```json { "error": "Task 123456789 is not completed" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **412** **412 Precondition Failed** The Kling account named in `error` is out of credits, and Kling did not create a task. Add credits or upgrade the plan of that account on [kling.ai](https://kling.ai), or send the job to another account with `email`. `message` keeps Kling's own text. ```json { "error": "Kling account user@example.com is out of credits: Credit are insufficient, you can upgrade your membership or purchase credit. (TASK.PointNotEnough)", "message": "积分消费失败 (TASK.PointNotEnough)" } ``` **500** **500 Internal Server Error** Kling uses a `500` response to indicate moderation and other issues with the input. It may be hard to separate actual 500 errors from moderation errors, so use the `error` field text and your best judgement to tell them apart, since the `message` field most often has very generic and perhaps misleading text. ```json { "error": "The content you uploaded appears to violate the community guidelines. (CM_EXT.POther)", "message": "Service busy (CM_EXT.POther)" } ``` When successful, the response includes a task ID which can be used to check the status using [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id). ##### Model The new task, with its `task.id` and `status_name`: poll it with [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) until `status_final` is `true`. <details markdown="block" class="model-details"> <summary>The task record, field by field</summary> ```typescript { // TypeScript, all fields are optional task: { id: number userId: number type: string scene: string status: number status_name: 'submitted' | 'failed' | 'processing' | 'succeed' status_final: boolean taskInfo: { type: string inputs: Array<{ name: string inputType: string token: string | null blobStorage: any | null url: string cover: string | null fromWorkId: number | null }> arguments: Array<{ name: string value: string }> extraArgs: Record<string, any> callbackPayloads: any[] scene: string } favored: boolean deleted: boolean viewed: boolean createTime: number updateTime: number viewTime: number } works: Array<any> status: number status_name: 'submitted' | 'failed' | 'processing' | 'succeed' status_final: boolean message: string error: string limitation: { type: string remaining: number limit: number } userPoints: { points: Array<{ orderId: string type: string amount: number balance: number startTime: number endTime: number }> total: number } userTickets: { ticket: Array<{ orderId: string type: string packageType: string amount: number balance: number startTime: number endTime: number }> } editProject: any | null } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/kling/images/upscale" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "email": "user@example.com", "task_id": "123456789", "workId": "987654321" }' ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const apiUrl = "https://api.useapi.net/v1/kling/images/upscale"; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ email: email, task_id: "123456789", workId: "987654321" }) }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured account email" apiUrl = "https://api.useapi.net/v1/kling/images/upscale" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } data = { "email": email, "task_id": "123456789", "workId": "987654321" } response = requests.post(apiUrl, headers=headers, json=data) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-kling-v1/post-kling-images-virtual-try-on === Document URL: https://useapi.net/docs/api-kling-v1/post-kling-images-virtual-try-on --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> images/virtual-try-on description: "Create virtual clothing try-on images from a person photo and garment references via POST images/virtual-try-on in the useapi.net Kling API v1." parent: Kling API nav_order: 310 --- ## Virtual Try-On April 18, 2025 (November 16, 2026) --- This endpoint allows you to create virtual try-on images with Kling AI by providing a human image and clothing items. > **https://api.useapi.net/v1/kling/images/virtual-try-on** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "email": "user@example.com", "humanImage": "https://example.com/person.jpg", "dressInput": "https://example.com/dress.jpg", "imageCount": 2, "replyUrl": "https://your-callback-url.com/webhook", "replyRef": "your-reference-id" } ``` - `email` is optional. Leave it out and the job goes to one of your [accounts](/docs/api-kling-v1/get-kling-accounts) that has a free job slot, picked at random. Each account runs at most its `maxJobs` jobs at once, and [GET scheduler/available](/docs/api-kling-v1/get-kling-scheduler-available) shows the free slots. If no account has a free slot, the response is `429`. Pass `email` to run the job on that account (`429` if it is busy). Uploaded files, elements, voices, avatars and earlier tasks belong to one account, so pass the `email` of the account they came from. With more than one account, reading the task with [GET tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) needs its account's `email`. The response's `task.userId` is that account's `session.userId` in [GET accounts](/docs/api-kling-v1/get-kling-accounts), and [GET scheduler](/docs/api-kling-v1/get-kling-scheduler) lists each running task with its `email`. - `humanImage` is **required**, URL to a real photo of a person. Kling refuses AI-generated illustrations and images without a person. Must be a valid http/https URL. Images can be uploaded using [POST /assets](/docs/api-kling-v1/post-kling-assets) and the returned URLs can be used here. - `dressInput` URL to a full-dress image to try on. Incompatible with upperInput and lowerInput. Images can be uploaded using [POST /assets](/docs/api-kling-v1/post-kling-assets). - `upperInput` URL to an upper garment image. Incompatible with dressInput. Images can be uploaded using [POST /assets](/docs/api-kling-v1/post-kling-assets). - `lowerInput` URL to a lower garment image. Incompatible with dressInput. Images can be uploaded using [POST /assets](/docs/api-kling-v1/post-kling-assets). - `imageCount` is optional, range from `1` to `4`. Default is `1`. - `maxJobs` is optional, range from `1` to `50`. Specifies the maximum number of concurrent jobs. - `replyUrl` is optional, a callback URL to receive generation progress and result. See [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id#model) for response model. - `replyRef` is optional, a reference identifier for the callback. **Note:** You must provide at least one of: `dressInput`, `upperInput`, or `lowerInput`. ##### Responses **200** **200 OK** ```json { "task": { "id": 123456789, "userId": 12345, "type": "mmu_img2img_aitryon", "scene": "NORMAL_CREATION", "status": 5, "status_name": "submitted", "status_final": false, "taskInfo": { "type": "mmu_img2img_aitryon", "inputs": [ { "name": "humanImage", "inputType": "URL", "token": null, "blobStorage": null, "url": "https://example.com/person.jpg", "cover": null, "fromWorkId": null }, { "name": "dressInput", "inputType": "URL", "token": null, "blobStorage": null, "url": "https://example.com/dress.jpg", "cover": null, "fromWorkId": null } ], "arguments": [ { "name": "personType", "value": "Female" }, { "name": "imageCount", "value": "2" } ], "extraArgs": {}, "callbackPayloads": [], "scene": "NORMAL_CREATION" }, "favored": false, "deleted": false, "viewed": false, "createTime": 1745376611075, "updateTime": 1745376611075 }, "works": [], "status": 5, "status_name": "submitted", "status_final": false, "message": "", "limitation": { "type": "mmu_img2img_aitryon", "remaining": 10000, "limit": 10000 }, "userPoints": { "points": [], "total": 0 }, "userTickets": { "ticket": [] }, "editProject": null } ``` **400** **400 Bad Request** The parameters are invalid, or Kling refused one of the images. When Kling refuses the submitted parameters, `error` carries Kling's own message. ```json { "error": "At least one of dressInput, upperInput or lowerInput must be provided" } ``` ```json { "error": "Kling refused humanImage (https://s15-kling.klingai.com/kimg/…). Use a real photo of a person (BASE.BadRequest)." } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** Kling was unable to locate one of the referenced assets. Make sure to use [POST /assets](/docs/api-kling-v1/post-kling-assets) to upload assets. ```json { "error": "Sorry, the requested resource was not found (VALID.ResourceNotFound)", "message": "Not Found" } ``` **412** **412 Precondition Failed** The Kling account named in `error` is out of credits, and Kling did not create a task. Add credits or upgrade the plan of that account on [kling.ai](https://kling.ai), or send the job to another account with `email`. `message` keeps Kling's own text. ```json { "error": "Kling account user@example.com is out of credits: Credit are insufficient, you can upgrade your membership or purchase credit. (TASK.PointNotEnough)", "message": "积分消费失败 (TASK.PointNotEnough)" } ``` **500** **500 Internal Server Error** Kling uses a `500` response to indicate moderation and other issues with the input. It may be hard to separate actual 500 errors from moderation errors, so use the `error` field text and your best judgement to tell them apart, since the `message` field most often has very generic and perhaps misleading text. ```json { "error": "The content you uploaded appears to violate the community guidelines. (CM_EXT.POther)", "message": "Service busy (CM_EXT.POther)" } ``` When successful, the response includes a task ID which can be used to check the status using [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id). ##### Model The new task, with its `task.id` and `status_name`: poll it with [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) until `status_final` is `true`. <details markdown="block" class="model-details"> <summary>The task record, field by field</summary> ```typescript { // TypeScript, all fields are optional task: { id: number userId: number type: string scene: string status: number status_name: 'submitted' | 'failed' | 'processing' | 'succeed' status_final: boolean taskInfo: { type: string inputs: Array<{ name: string inputType: string token: string | null blobStorage: any | null url: string cover: string | null fromWorkId: number | null }> arguments: Array<{ name: string value: string }> extraArgs: Record<string, any> callbackPayloads: any[] scene: string } favored: boolean deleted: boolean viewed: boolean createTime: number updateTime: number viewTime: number } works: Array<any> status: number status_name: 'submitted' | 'failed' | 'processing' | 'succeed' status_final: boolean message: string error: string limitation: { type: string remaining: number limit: number } userPoints: { points: Array<{ orderId: string type: string amount: number balance: number startTime: number endTime: number }> total: number } userTickets: { ticket: Array<{ orderId: string type: string packageType: string amount: number balance: number startTime: number endTime: number }> } editProject: any | null } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/kling/images/virtual-try-on" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "email": "user@example.com", "humanImage": "https://example.com/person.jpg", "dressInput": "https://example.com/dress.jpg", "imageCount": 2 }' ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const apiUrl = "https://api.useapi.net/v1/kling/images/virtual-try-on"; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ email: email, humanImage: "https://example.com/person.jpg", dressInput: "https://example.com/dress.jpg", imageCount: 2 }) }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured account email" apiUrl = "https://api.useapi.net/v1/kling/images/virtual-try-on" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } data = { "email": email, "humanImage": "https://example.com/person.jpg", "dressInput": "https://example.com/dress.jpg", "imageCount": 2 } response = requests.post(apiUrl, headers=headers, json=data) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-kling-v1/post-kling-tts-create === Document URL: https://useapi.net/docs/api-kling-v1/post-kling-tts-create --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> tts/create description: "Generate up to 5 minutes of speech from text for free via POST tts/create in the useapi.net Kling API v1 — unlimited TTS on all Kling subscription plans." parent: Kling API nav_order: 475 --- ## Generate speech from text April 18, 2025 (November 16, 2026) --- This endpoint generates speech up to **5 minutes** long from text using Kling's text-to-speech technology. You can execute an unlimited number of TTS generations for **free**. This feature is available for all Kling subscription plans, including the free one. > **https://api.useapi.net/v1/kling/tts/create** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "email": "user@example.com", "speakerId": "speakerId", "text": "Text to be converted to speech", "speed": 1.0, "emotion": "happy" } ``` - `email` is optional. Leave it out and the job goes to one of your [accounts](/docs/api-kling-v1/get-kling-accounts) that has a free job slot, picked at random. Each account runs at most its `maxJobs` jobs at once, and [GET scheduler/available](/docs/api-kling-v1/get-kling-scheduler-available) shows the free slots. If no account has a free slot, the response is `429`. Pass `email` to run the job on that account (`429` if it is busy). Uploaded files, elements, voices, avatars and earlier tasks belong to one account, so pass the `email` of the account they came from. - `speakerId` is **required**, a valid speakerId from [GET /tts/voices](/docs/api-kling-v1/get-kling-tts-voices). - `text` is **required**, the text to be converted to speech. - `speed` is optional, range from `0.8` to `2.0`. Default is `1.0`. - `emotion` is optional, must be one of the supported emotion keys for the selected voice. ##### Responses **200** **200 OK** ```json { "resource": "https://s21-kling.klingai.com/....mp3", "status": 99, "duration": 195621, "status_name": "succeed", "status_final": true } ``` **400** **400 Bad Request** ```json { "error": "<error message>" } ``` Kling refused the text under its content rules. `error` carries Kling's own message: ```json { "error": "The description contains content that violates our guidelines. Please revise it and try again. If you have any questions, please contact customer support. (CM_EXT.Other)", "message": "The description contains content that violates our guidelines. Please revise it and try again. If you have any questions, please contact customer support. (CM_EXT.Other)" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **500** **500 Internal Server Error** Kling uses a `500` response to indicate moderation and other issues with the input. It may be hard to separate actual 500 errors from moderation errors, so use the `error` field text and your best judgement to tell them apart, since the `message` field most often has very generic and perhaps misleading text. ```json { "error": "The content you uploaded appears to violate the community guidelines. (CM_EXT.POther)", "message": "Service busy (CM_EXT.POther)" } ``` Field `resource` will contain URL with generated mp3 audio file. ##### Model The finished speech: the URL of the MP3 file in `resource`, with its `duration` and final status. <details markdown="block" class="model-details"> <summary>The generated speech, field by field</summary> ```typescript { // TypeScript, all fields are optional resource: string // URL to the generated MP3 audio file status: number // Status code, e.g., 99 for succeed duration: number // Duration, seconds status_name: 'submitted' | 'failed' | 'processing' | 'succeed' // Status name status_final: boolean // Whether this is the final status message: string error: string } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/kling/tts/create" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{"email":"user@example.com","speakerId":"speakerId","text":"Hello, world!"}' ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const apiUrl = "https://api.useapi.net/v1/kling/tts/create"; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ email: email, speakerId: "speakerId", text: "Hello, world!" }) }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured account email" apiUrl = "https://api.useapi.net/v1/kling/tts/create" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } data = { "email": email, "speakerId": "speakerId", "text": "Hello, world!" } response = requests.post(apiUrl, headers=headers, json=data) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-kling-v1/post-kling-videos-add-sound === Document URL: https://useapi.net/docs/api-kling-v1/post-kling-videos-add-sound --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/add-sound description: "Add AI-generated sound to an existing Kling video (3–20 seconds long) via POST videos/add-sound in the useapi.net Kling API v1." parent: Kling API nav_order: 385 --- ## Add sound to Kling video August 8, 2025 (November 16, 2026) --- This endpoint generates sound for an existing video using Kling's AI audio generation capabilities. Video can't be shorter than 3 seconds or longer than 20 seconds. > **https://api.useapi.net/v1/kling/videos/add-sound** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ``` json { "video": "https://s21-kling.klingai.com/....mp4", "replyUrl": "https://my.domain.com/webhook-endpoint-kling", "replyRef": "my-id-1234" } ``` - `email` is optional. Leave it out and the job goes to one of your [accounts](/docs/api-kling-v1/get-kling-accounts) that has a free job slot, picked at random. Each account runs at most its `maxJobs` jobs at once, and [GET scheduler/available](/docs/api-kling-v1/get-kling-scheduler-available) shows the free slots. If no account has a free slot, the response is `429`. Pass `email` to run the job on that account (`429` if it is busy). Uploaded files, elements, voices, avatars and earlier tasks belong to one account, so pass the `email` of the account they came from. With more than one account, reading the task with [GET tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) needs its account's `email`. The response's `task.userId` is that account's `session.userId` in [GET accounts](/docs/api-kling-v1/get-kling-accounts), and [GET scheduler](/docs/api-kling-v1/get-kling-scheduler) lists each running task with its `email`. - `video` is **required**, the URL of the video to add sound to. Video can be uploaded using [POST /assets](/docs/api-kling-v1/post-kling-assets) and the returned URL can be used here. Video can't be shorter than 3 seconds or longer than 20 seconds. - `cropVideoOriginalSound` is optional, whether to preserve the original video's sound. Default `false` (original sound will be replaced). - `maxJobs` is optional, the maximum number of concurrent Kling jobs. - `replyUrl` is optional, a URL to receive webhooks when the video is completed. Callback body has the same JSON shape as [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) response. - `replyRef` is optional, include a custom reference to identify the job. Passed as-is to the `replyUrl` webhook. ##### Responses **200** **200 OK** ```json { "task": { "id": 1234567890, "userId": 12345, "type": "kwave_video2audio", "scene": "NORMAL_CREATION", "status": 5, "taskInfo": { "type": "kwave_video2audio", "inputs": [ { "name": "video", "inputType": "URL", "token": null, "blobStorage": null, "url": "https://v15-kling.klingai.com/…", "cover": null, "fromWorkId": null, "fromUploadId": null } ], "arguments": [ { "name": "biz", "value": "klingai" }, { "name": "imageCount", "value": "1" }, { "name": "duration", "value": "20" } ], "extraArgs": {}, "callbackPayloads": [ { "name": "video2audio_payloads", "resources": [ { "name": "originalVideoUrl", "type": "VIDEO", "url": "https://v15-kling.klingai.com/…" } ], "arguments": [ { "name": "cropVideoOriginalSound", "value": "false" } ] } ], "scene": "NORMAL_CREATION" }, "favored": false, "deleted": false, "viewed": false, "createTime": 1754630611379, "updateTime": 1754630611379, "viewTime": 0, "status_name": "submitted", "status_final": false }, "works": [], "status": 5, "message": "", "limitation": null, "userPoints": { "points": [ { "orderId": "1234567890", "type": "reward", "amount": 26600, "balance": 3150, "startTime": 1754406534079, "endTime": 1757084934079 } ], "total": 113390 }, "userTickets": { "ticket": [ { "orderId": "1234456789", "type": "priority", "packageType": "reward", "amount": 1, "balance": 1, "startTime": 1754406534079, "endTime": 1757084934079 } ] }, "editProject": null, "status_name": "submitted", "status_final": false } ``` **400** **400 Bad Request** The parameters are invalid. When Kling refuses the submitted parameters, `error` carries Kling's own message. ```json { "error": "Invalid video URL format" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** Kling was unable to locate one of the referenced assets. Make sure to use [POST /assets](/docs/api-kling-v1/post-kling-assets) to upload assets. ```json { "error": "Sorry, the requested resource was not found (VALID.ResourceNotFound)", "message": "Not Found" } ``` **412** **412 Precondition Failed** The Kling account named in `error` is out of credits, and Kling did not create a task. Add credits or upgrade the plan of that account on [kling.ai](https://kling.ai), or send the job to another account with `email`. `message` keeps Kling's own text. ```json { "error": "Kling account user@example.com is out of credits: Credit are insufficient, you can upgrade your membership or purchase credit. (TASK.PointNotEnough)", "message": "积分消费失败 (TASK.PointNotEnough)" } ``` **500** **500 Internal Server Error** Kling uses a `500` response to indicate moderation and other issues with the input. It may be hard to separate actual 500 errors from moderation errors, so use the `error` field text and your best judgement to tell them apart, since the `message` field most often has very generic and perhaps misleading text. ```json { "error": "The content you uploaded appears to violate the community guidelines. (CM_EXT.POther)", "message": "Service busy (CM_EXT.POther)" } ``` When successful, the response includes a task ID which can be used to check the status using [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id). ##### Model The new task, with its `task.id` and `status_name`: poll it with [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) until `status_final` is `true`. <details markdown="block" class="model-details"> <summary>The task record, field by field</summary> ```typescript { // TypeScript, all fields are optional task: { id: number // Unique task identifier userId: number // User ID type: string // Task type: "kwave_video2audio" scene: string // Scene type: "NORMAL_CREATION" status: number // Task status taskInfo: { type: string // Task type inputs: { name: string // Input name: "video" inputType: string // Input type: "URL" token: string | null blobStorage: string | null url: string // Video URL cover: string | null fromWorkId: number | null fromUploadId: number | null }[] arguments: { name: string // Argument name value: string // Argument value }[] extraArgs: Record<string, any> callbackPayloads: { name: string // "video2audio_payloads" resources: { name: string // "originalVideoUrl" type: string // "VIDEO" url: string // Original video URL marginTop?: number countInRow?: number mode?: string }[] arguments: { name: string // Parameter name value: string // Parameter value }[] }[] scene: string // Scene type } favored: boolean deleted: boolean viewed: boolean createTime: number // Creation timestamp updateTime: number // Update timestamp viewTime: number // View timestamp status_name: string // Status name: "submitted" status_final: boolean // Whether status is final } works: any[] // Work items (empty initially) status: number // Overall status message: string // Status message error: string limitation: any | null // Rate limiting info userPoints: { points: { orderId: string // Order ID type: string // Point type amount: number // Point amount balance: number // Remaining balance startTime: number // Start timestamp endTime: number // End timestamp }[] total: number // Total points } userTickets: { ticket: { orderId: string // Order ID type: string // Ticket type packageType: string // Package type amount: number // Ticket amount balance: number // Remaining balance startTime: number // Start timestamp endTime: number // End timestamp }[] } editProject: any | null // Edit project info status_name: string // Status name status_final: boolean // Whether status is final } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/kling/videos/add-sound" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "email": "user@domain.com", "video": "https://s21-kling.klingai.com/....mp4", "replyUrl": "https://my.domain.com/webhook-endpoint-kling" }' ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const requestData = { email, video: "https://s21-kling.klingai.com/....mp4", replyUrl: "https://my.domain.com/webhook-endpoint-kling" }; const response = await fetch("https://api.useapi.net/v1/kling/videos/add-sound", { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify(requestData) }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured account email" request_data = { "email": email, "video": "https://s21-kling.klingai.com/....mp4", "replyUrl": "https://my.domain.com/webhook-endpoint-kling" } headers = { "Content-Type": "application/json", "Authorization": f"Bearer {token}" } response = requests.post("https://api.useapi.net/v1/kling/videos/add-sound", headers=headers, json=request_data) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-kling-v1/post-kling-videos-extend === Document URL: https://useapi.net/docs/api-kling-v1/post-kling-videos-extend --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/extend description: "Extend a previously generated Kling video, continuing its animation from where it left off, via POST videos/extend in the useapi.net Kling API v1." parent: Kling API nav_order: 370 --- ## Extend an Existing Video April 18, 2025 (November 16, 2026) --- This endpoint extends a previously generated video, continuing the animation from where it left off. > **https://api.useapi.net/v1/kling/videos/extend** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "email": "user@example.com", "task_id": "12345678", "prompt": "Continue with the mountain landscape, now showing a sunset", "negative_prompt": "people, low quality, distorted", "cfg_scale": 0.5, "replyUrl": "https://your-callback-url.com/webhook", "replyRef": "your-reference-id" } ``` - `email` is optional. Leave it out and the job goes to one of your [accounts](/docs/api-kling-v1/get-kling-accounts) that has a free job slot, picked at random. Each account runs at most its `maxJobs` jobs at once, and [GET scheduler/available](/docs/api-kling-v1/get-kling-scheduler-available) shows the free slots. If no account has a free slot, the response is `429`. Pass `email` to run the job on that account (`429` if it is busy). Uploaded files, elements, voices, avatars and earlier tasks belong to one account, so pass the `email` of the account they came from. With more than one account, reading the task with [GET tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) needs its account's `email`. The response's `task.userId` is that account's `session.userId` in [GET accounts](/docs/api-kling-v1/get-kling-accounts), and [GET scheduler](/docs/api-kling-v1/get-kling-scheduler) lists each running task with its `email`. - `task_id` is **required**, the ID of a completed video generation task to extend. You can get a list of your tasks from [GET /tasks](/docs/api-kling-v1/get-kling-tasks). - `prompt` is optional, text description to guide the extended video generation. Maximum length: 2500 characters. - `negative_prompt` is optional, what not to include in the generated video. Maximum length: 2500 characters. - `cfg_scale` is optional, guidance scale for video extension. Range: `0` to `1`. Default: `0.5`. - `enable_audio` is optional, add sound effects. Supported values: `false` (default) or `true`. - `maxJobs` is optional, range from `1` to `50`. Specifies the maximum number of concurrent jobs. - `replyUrl` is optional, a callback URL to receive generation progress and result. See [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id#model) for response model. - `replyRef` is optional, a reference identifier for the callback. **Note:** The task specified by `task_id` must be in the `succeed` status for the extension to work. ##### Responses **200** **200 OK** ```json { "task": { "id": 123456789, "userId": 12345, "type": "m2v_extend_video", "scene": "NORMAL_CREATION", "status": 5, "status_name": "submitted", "status_final": false, "taskInfo": { "type": "m2v_extend_video", "inputs": [ { "name": "input", "inputType": "URL", "token": null, "blobStorage": null, "url": "https://s21-kling.klingai.com/video12345.mp4", "cover": null, "fromWorkId": 12345678 } ], "arguments": [ { "name": "prompt", "value": "Continue with the mountain landscape, now showing a sunset" }, { "name": "negative_prompt", "value": "people, low quality, distorted" }, { "name": "cfg", "value": "0.5" }, { "name": "__initialType", "value": "m2v_txt2video_hq" }, { "name": "__initialPrompt", "value": "A majestic mountain landscape with snow-capped peaks and flowing rivers" }, { "name": "kling_version", "value": "1.6" } ], "extraArgs": {}, "callbackPayloads": [], "scene": "NORMAL_CREATION" }, "favored": false, "deleted": false, "viewed": false, "createTime": 1745376611075, "updateTime": 1745376611075 }, "works": [], "status": 5, "status_name": "submitted", "status_final": false, "message": "", "limitation": { "type": "m2v_extend_video", "remaining": 10000, "limit": 10000 }, "userPoints": { "points": [], "total": 0 }, "userTickets": { "ticket": [] }, "editProject": null } ``` **400** **400 Bad Request** The parameters are invalid. When Kling refuses the submitted parameters, `error` carries Kling's own message. ```json { "error": "Task is not completed" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **412** **412 Precondition Failed** The Kling account named in `error` is out of credits, and Kling did not create a task. Add credits or upgrade the plan of that account on [kling.ai](https://kling.ai), or send the job to another account with `email`. `message` keeps Kling's own text. ```json { "error": "Kling account user@example.com is out of credits: Credit are insufficient, you can upgrade your membership or purchase credit. (TASK.PointNotEnough)", "message": "积分消费失败 (TASK.PointNotEnough)" } ``` **500** **500 Internal Server Error** Kling uses a `500` response to indicate moderation and other issues with the input. It may be hard to separate actual 500 errors from moderation errors, so use the `error` field text and your best judgement to tell them apart, since the `message` field most often has very generic and perhaps misleading text. ```json { "error": "The content you uploaded appears to violate the community guidelines. (CM_EXT.POther)", "message": "Service busy (CM_EXT.POther)" } ``` When successful, the response includes a task ID which can be used to check the status using [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id). ##### Model The new task, with its `task.id` and `status_name`: poll it with [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) until `status_final` is `true`. <details markdown="block" class="model-details"> <summary>The task record, field by field</summary> ```typescript { // TypeScript, all fields are optional task: { id: number userId: number type: string scene: string status: number status_name: 'submitted' | 'failed' | 'processing' | 'succeed' status_final: boolean taskInfo: { type: string inputs: Array<{ name: string inputType: string token: string | null blobStorage: any | null url: string cover: string | null fromWorkId: number | null }> arguments: Array<{ name: string value: string }> extraArgs: Record<string, any> callbackPayloads: any[] scene: string } favored: boolean deleted: boolean viewed: boolean createTime: number updateTime: number viewTime: number } works: Array<any> status: number status_name: 'submitted' | 'failed' | 'processing' | 'succeed' status_final: boolean message: string error: string limitation: { type: string remaining: number limit: number } userPoints: { points: Array<{ orderId: string type: string amount: number balance: number startTime: number endTime: number }> total: number } userTickets: { ticket: Array<{ orderId: string type: string packageType: string amount: number balance: number startTime: number endTime: number }> } editProject: any | null } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/kling/videos/extend" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "email": "user@example.com", "task_id": "12345678", "prompt": "Continue with the mountain landscape, now showing a sunset", "negative_prompt": "people, low quality, distorted" }' ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const apiUrl = "https://api.useapi.net/v1/kling/videos/extend"; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ email: email, task_id: "12345678", prompt: "Continue with the mountain landscape, now showing a sunset", negative_prompt: "people, low quality, distorted" }) }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured account email" apiUrl = "https://api.useapi.net/v1/kling/videos/extend" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } data = { "email": email, "task_id": "12345678", "prompt": "Continue with the mountain landscape, now showing a sunset", "negative_prompt": "people, low quality, distorted" } response = requests.post(apiUrl, headers=headers, json=data) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-kling-v1/post-kling-videos-image2video-effects === Document URL: https://useapi.net/docs/api-kling-v1/post-kling-videos-image2video-effects --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/image2video-effects description: "Animate an image using a special effect preset via POST videos/image2video-effects in the useapi.net Kling API v1 — browse available effects with GET videos/effects." parent: Kling API nav_order: 360 --- ## Create Video From Image with Effects April 18, 2025 (November 18, 2026) --- This endpoint generates a video from an image using special effects. > **https://api.useapi.net/v1/kling/videos/image2video-effects** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "email": "user@example.com", "effect": "rocket", "image": "https://example.com/image.jpg", "prompt": "A detailed description for the effect", "mode": "std", "replyUrl": "https://your-callback-url.com/webhook", "replyRef": "your-reference-id" } ``` - `email` is optional. Leave it out and the job goes to one of your [accounts](/docs/api-kling-v1/get-kling-accounts) that has a free job slot, picked at random. Each account runs at most its `maxJobs` jobs at once, and [GET scheduler/available](/docs/api-kling-v1/get-kling-scheduler-available) shows the free slots. If no account has a free slot, the response is `429`. Pass `email` to run the job on that account (`429` if it is busy). Uploaded files, elements, voices, avatars and earlier tasks belong to one account, so pass the `email` of the account they came from. With more than one account, reading the task with [GET tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) needs its account's `email`. The response's `task.userId` is that account's `session.userId` in [GET accounts](/docs/api-kling-v1/get-kling-accounts), and [GET scheduler](/docs/api-kling-v1/get-kling-scheduler) lists each running task with its `email`. - `effect` is **required**, the name of the effect to apply. Get available effects from [GET /videos/effects](/docs/api-kling-v1/get-kling-videos-effects). - `image` is **required**, URL to the image to animate. Image can be uploaded using [POST /assets](/docs/api-kling-v1/post-kling-assets) and the returned URLs can be used here. - `prompt` is optional, text description to guide the effect. Some effects support custom prompts while others use default prompts. Maximum length: 2500 characters. - `mode` is optional, generation quality mode. Accepted values: `std` (standard), `pro` (professional). Defaults to `std`. Not all effects support all modes - check the effect details from [GET /videos/effects](/docs/api-kling-v1/get-kling-videos-effects). - `maxJobs` is optional, range from `1` to `50`. Specifies the maximum number of concurrent jobs. - `replyUrl` is optional, a callback URL to receive generation progress and result. See [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id#model) for response model. - `replyRef` is optional, a reference identifier for the callback. **Notes:** - Different effects have different capabilities. Check the response from [GET /videos/effects](/docs/api-kling-v1/get-kling-videos-effects) to see if an effect supports custom prompts and which modes are available. - Effects marked as `effectSupported: false` require image preprocessing and are not yet supported. - Effects with `promptSupported: true` accept custom prompts, while others use built-in default prompts. - The `mode` parameter allows selection between standard and professional quality where supported. ##### Responses **200** **200 OK** ```json { "task": { "id": 123456789, "userId": 12345, "type": "m2v_img2video_se_hq", "scene": "NORMAL_CREATION", "status": 5, "status_name": "submitted", "status_final": false, "taskInfo": { "type": "m2v_img2video_se_hq", "inputs": [ { "name": "input", "inputType": "URL", "token": null, "blobStorage": null, "url": "https://example.com/image.jpg", "cover": null, "fromWorkId": null, "fromUploadId": null } ], "arguments": [ { "name": "special_effect", "value": "expansion" }, { "name": "prompt", "value": "A detailed description for the effect" }, { "name": "kling_version", "value": "1.6" }, { "name": "model_mode", "value": "std" }, { "name": "seStepName", "value": "seSubmit" }, { "name": "biz", "value": "klingai" } ], "extraArgs": {}, "callbackPayloads": [], "scene": "NORMAL_CREATION" }, "favored": false, "deleted": false, "viewed": false, "createTime": 1753424884354, "updateTime": 1753424884354, "viewTime": 0 }, "works": [], "status": 5, "status_name": "submitted", "status_final": false, "message": "", "limitation": null, "userPoints": { "points": [ { "orderId": "…", "type": "recharge", "amount": 66000, "balance": 25540, "startTime": 1752894669788, "endTime": 1815966669788 } ], "total": 25540 }, "userTickets": { "ticket": [ { "orderId": "…", "type": "priority", "packageType": "reward", "amount": 1, "balance": 1, "startTime": 1751329144926, "endTime": 1754007544926 } ] }, "editProject": null } ``` **400** **400 Bad Request** The parameters are invalid. When Kling refuses the submitted parameters, `error` carries Kling's own message. ```json { "error": "Effect rocket not found. Supported effects: cartoon,cyberpunk,spinoff" } ``` An effect Kling has retired answers `400` too. Choose another one from [GET videos/effects](https://useapi.net/docs/api-kling-v1/get-kling-videos-effects). ```json { "error": "Kling no longer offers this effect (This effect is no longer available.). Choose another one from GET /videos/effects (SE.SeCanNotUse)", "message": "Service busy (SE.SeCanNotUse)" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** Kling was unable to locate one of the referenced assets. Make sure to use [POST /assets](/docs/api-kling-v1/post-kling-assets) to upload assets. ```json { "error": "Sorry, the requested resource was not found (VALID.ResourceNotFound)", "message": "Not Found" } ``` **412** **412 Precondition Failed** The Kling account named in `error` is out of credits, and Kling did not create a task. Add credits or upgrade the plan of that account on [kling.ai](https://kling.ai), or send the job to another account with `email`. `message` keeps Kling's own text. ```json { "error": "Kling account user@example.com is out of credits: Credit are insufficient, you can upgrade your membership or purchase credit. (TASK.PointNotEnough)", "message": "积分消费失败 (TASK.PointNotEnough)" } ``` **500** **500 Internal Server Error** Kling uses a `500` response to indicate moderation and other issues with the input. It may be hard to separate actual 500 errors from moderation errors, so use the `error` field text and your best judgement to tell them apart, since the `message` field most often has very generic and perhaps misleading text. ```json { "error": "The content you uploaded appears to violate the community guidelines. (CM_EXT.POther)", "message": "Service busy (CM_EXT.POther)" } ``` When successful, the response includes a task ID which can be used to check the status using [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id). ##### Model The new task, with its `task.id` and `status_name`: poll it with [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) until `status_final` is `true`. <details markdown="block" class="model-details"> <summary>The task record, field by field</summary> ```typescript { // TypeScript, all fields are optional task: { id: number userId: number type: string scene: string status: number status_name: 'submitted' | 'failed' | 'processing' | 'succeed' status_final: boolean taskInfo: { type: string inputs: Array<{ name: string inputType: string token: string | null blobStorage: any | null url: string cover: string | null fromWorkId: number | null }> arguments: Array<{ name: string value: string }> extraArgs: Record<string, any> callbackPayloads: any[] scene: string } favored: boolean deleted: boolean viewed: boolean createTime: number updateTime: number viewTime: number } works: Array<any> status: number status_name: 'submitted' | 'failed' | 'processing' | 'succeed' status_final: boolean message: string error: string limitation: { type: string remaining: number limit: number } userPoints: { points: Array<{ orderId: string type: string amount: number balance: number startTime: number endTime: number }> total: number } userTickets: { ticket: Array<{ orderId: string type: string packageType: string amount: number balance: number startTime: number endTime: number }> } editProject: any | null } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/kling/videos/image2video-effects" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "email": "user@example.com", "effect": "rocket", "image": "https://example.com/image.jpg" }' ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const apiUrl = "https://api.useapi.net/v1/kling/videos/image2video-effects"; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ email: email, effect: "rocket", image: "https://example.com/image.jpg" }) }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured account email" apiUrl = "https://api.useapi.net/v1/kling/videos/image2video-effects" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } data = { "email": email, "effect": "rocket", "image": "https://example.com/image.jpg" } response = requests.post(apiUrl, headers=headers, json=data) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-kling-v1/post-kling-videos-image2video-elements === Document URL: https://useapi.net/docs/api-kling-v1/post-kling-videos-image2video-elements --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/image2video-elements description: "Create a Kling video from image or element references via POST videos/image2video-elements in the useapi.net Kling API v1 — v3.0 supports up to 3 combined refs, v1.6 up to 4 images." parent: Kling API nav_order: 350 --- ## Create Video From Multiple Images April 18, 2025 (November 16, 2026) --- This endpoint generates a video from multiple images (up to 4) that will appear as elements in the video. Model `3.0` additionally supports saved [elements](/docs/api-kling-v1/get-kling-elements) via `element_1`-`element_3` parameters, with a combined maximum of 3 images/elements. ##### Model Support Matrix | Feature | v3.0 | v1.6 | |---------|:----:|:----:| | Image inputs (`image_0`-`image_3`) | Yes | Yes | | Element inputs (`element_1`-`element_3`) | Yes | No | | Max combined inputs | 3 | 4 | | Duration | 3-15s | 5/10s | | Audio | Always on | Optional | | aspect_ratio | No (from image) | Yes | > **https://api.useapi.net/v1/kling/videos/image2video-elements** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "email": "user@example.com", "prompt": "A museum gallery with artwork on display", "image_0": "https://example.com/image1.jpg", "image_1": "https://example.com/image2.jpg", "image_2": "https://example.com/image3.jpg", "image_3": "https://example.com/image4.jpg", "negative_prompt": "low quality, blurry, distorted", "duration": "5", "aspect_ratio": "16:9", "model_name": "kling-v1-6", "mode": "std", "replyUrl": "https://your-callback-url.com/webhook", "replyRef": "your-reference-id" } ``` - `email` is optional. Leave it out and the job goes to one of your [accounts](/docs/api-kling-v1/get-kling-accounts) that has a free job slot, picked at random. Each account runs at most its `maxJobs` jobs at once, and [GET scheduler/available](/docs/api-kling-v1/get-kling-scheduler-available) shows the free slots. If no account has a free slot, the response is `429`. Pass `email` to run the job on that account (`429` if it is busy). Uploaded files, elements, voices, avatars and earlier tasks belong to one account, so pass the `email` of the account they came from. With more than one account, reading the task with [GET tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) needs its account's `email`. The response's `task.userId` is that account's `session.userId` in [GET accounts](/docs/api-kling-v1/get-kling-accounts), and [GET scheduler](/docs/api-kling-v1/get-kling-scheduler) lists each running task with its `email`. - `prompt` is **required**, text description of the video to generate. Maximum length: 2500 characters. - `image_0` to `image_3` are URLs to images that will appear in the video. At least one image or element must be provided. Images can be uploaded using [POST /assets](/docs/api-kling-v1/post-kling-assets) and the returned URLs can be used here. - `element_1` to `element_3` are optional, IDs of saved [elements](/docs/api-kling-v1/get-kling-elements). Model `3.0` only. Model `1.6` ignores them next to an image and the response lists that in `warnings`. Without an image it returns `400`. Create elements using [POST /elements](/docs/api-kling-v1/post-kling-elements). Combined total of images + elements cannot exceed 3 for model `3.0`. - `negative_prompt` is optional, what not to include in the generated video. Maximum length: 2500 characters. Model `3.0` ignores it and the response lists that in `warnings`. - `duration` is optional, length of the video in seconds. Model `3.0`: `3` to `15` seconds (default `5`). Model `1.6`: `5` (default) or `10`. - `aspect_ratio` is optional, the video aspect ratio. Supported values: `16:9` (default), `9:16`, `1:1`. Model `3.0` ignores it (the aspect ratio comes from the input image) and the response lists that in `warnings`. - `model_name` is optional, the AI model version to use. Supported values: `kling-v3-0`, `kling-v1-6` (default). - `mode` is optional, quality level. Supported values: `std` (standard, default), `pro` (higher quality, slower generation), or `4k` (4K resolution, model `3.0` only). Model `1.6` runs `4k` as `pro` and the response lists that in `warnings`. - `enable_audio` is optional, add sound effects. Supported values: `false` or `true`. The default depends on the model: `true` on model `3.0`, `false` on every other model that accepts it. Model `3.0` defaults to audio enabled; set `enable_audio: false` to disable. - `maxJobs` is optional, range from `1` to `50`. Specifies the maximum number of concurrent jobs. - `replyUrl` is optional, a callback URL to receive generation progress and result. See [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id#model) for response model. - `replyRef` is optional, a reference identifier for the callback. **Note:** At least one image or element must be provided. For model `1.6`, at least one of `image_0`-`image_3` is required. For model `3.0`, elements (`element_1`-`element_3`) alone are also sufficient. ##### Responses **200** **200 OK** ```json { "task": { "id": 123456789, "userId": 12345, "type": "m2v_img2video_hq", "scene": "NORMAL_CREATION", "status": 5, "status_name": "submitted", "status_final": false, "taskInfo": { "type": "m2v_img2video_hq", "inputs": [ { "name": "ref_img_0", "inputType": "URL", "token": null, "blobStorage": null, "url": "https://example.com/image1.jpg", "cover": null, "fromWorkId": null }, { "name": "raw_ref_img_0", "inputType": "URL", "token": null, "blobStorage": null, "url": "https://example.com/image1.jpg", "cover": null, "fromWorkId": null }, { "name": "ref_img_1", "inputType": "URL", "token": null, "blobStorage": null, "url": "https://example.com/image2.jpg", "cover": null, "fromWorkId": null }, { "name": "raw_ref_img_1", "inputType": "URL", "token": null, "blobStorage": null, "url": "https://example.com/image2.jpg", "cover": null, "fromWorkId": null } ], "arguments": [ { "name": "prompt", "value": "A museum gallery with artwork on display" }, { "name": "negative_prompt", "value": "low quality, blurry, distorted" }, { "name": "duration", "value": "5" }, { "name": "aspect_ratio", "value": "16:9" }, { "name": "kling_version", "value": "1.6" }, { "name": "imageList", "value": "[{\"top\":0,\"left\":0,\"width\":1,\"height\":1},{\"top\":0,\"left\":0,\"width\":1,\"height\":1}]" } ], "extraArgs": {}, "callbackPayloads": [], "scene": "NORMAL_CREATION" }, "favored": false, "deleted": false, "viewed": false, "createTime": 1745376611075, "updateTime": 1745376611075 }, "works": [], "status": 5, "status_name": "submitted", "status_final": false, "message": "", "limitation": { "type": "m2v_img2video_hq", "remaining": 10000, "limit": 10000 }, "userPoints": { "points": [], "total": 0 }, "userTickets": { "ticket": [] }, "editProject": null } ``` When the model cannot honor a value of the request, the job still runs the way it always has and the response adds a `warnings` array that says what was used instead, for example `"warnings": ["aspect_ratio is ignored by kling-v3-0 (the aspect ratio comes from the input image)"]`. The field is left out when there is nothing to report. **400** **400 Bad Request** The parameters are invalid. When Kling refuses the submitted parameters, `error` carries Kling's own message. ```json { "error": "At least one image (image_0, image_1, image_2 or image_3) is required" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** Kling was unable to locate one of the referenced assets. Make sure to use [POST /assets](/docs/api-kling-v1/post-kling-assets) to upload assets. ```json { "error": "Sorry, the requested resource was not found (VALID.ResourceNotFound)", "message": "Not Found" } ``` **412** **412 Precondition Failed** The Kling account named in `error` is out of credits, and Kling did not create a task. Add credits or upgrade the plan of that account on [kling.ai](https://kling.ai), or send the job to another account with `email`. `message` keeps Kling's own text. ```json { "error": "Kling account user@example.com is out of credits: Credit are insufficient, you can upgrade your membership or purchase credit. (TASK.PointNotEnough)", "message": "积分消费失败 (TASK.PointNotEnough)" } ``` **500** **500 Internal Server Error** Kling uses a `500` response to indicate moderation and other issues with the input. It may be hard to separate actual 500 errors from moderation errors, so use the `error` field text and your best judgement to tell them apart, since the `message` field most often has very generic and perhaps misleading text. ```json { "error": "The content you uploaded appears to violate the community guidelines. (CM_EXT.POther)", "message": "Service busy (CM_EXT.POther)" } ``` When successful, the response includes a task ID which can be used to check the status using [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id). ##### Model The new task, with its `task.id` and `status_name`: poll it with [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) until `status_final` is `true`. <details markdown="block" class="model-details"> <summary>The task record, field by field</summary> ```typescript { // TypeScript, all fields are optional task: { id: number userId: number type: string scene: string status: number status_name: 'submitted' | 'failed' | 'processing' | 'succeed' status_final: boolean taskInfo: { type: string inputs: Array<{ name: string inputType: string token: string | null blobStorage: any | null url: string cover: string | null fromWorkId: number | null }> arguments: Array<{ name: string value: string }> extraArgs: Record<string, any> callbackPayloads: any[] scene: string } favored: boolean deleted: boolean viewed: boolean createTime: number updateTime: number viewTime: number } works: Array<any> status: number status_name: 'submitted' | 'failed' | 'processing' | 'succeed' status_final: boolean message: string error: string limitation: { type: string remaining: number limit: number } userPoints: { points: Array<{ orderId: string type: string amount: number balance: number startTime: number endTime: number }> total: number } userTickets: { ticket: Array<{ orderId: string type: string packageType: string amount: number balance: number startTime: number endTime: number }> } editProject: any | null warnings: string[] // only when a value of the request was run differently or ignored, e.g. mode 4k as pro } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/kling/videos/image2video-elements" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "email": "user@example.com", "prompt": "A museum gallery with artwork on display", "image_0": "https://example.com/image1.jpg", "image_1": "https://example.com/image2.jpg", "negative_prompt": "low quality, blurry, distorted" }' ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const apiUrl = "https://api.useapi.net/v1/kling/videos/image2video-elements"; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ email: email, prompt: "A museum gallery with artwork on display", image_0: "https://example.com/image1.jpg", image_1: "https://example.com/image2.jpg", negative_prompt: "low quality, blurry, distorted" }) }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured account email" apiUrl = "https://api.useapi.net/v1/kling/videos/image2video-elements" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } data = { "email": email, "prompt": "A museum gallery with artwork on display", "image_0": "https://example.com/image1.jpg", "image_1": "https://example.com/image2.jpg", "negative_prompt": "low quality, blurry, distorted" } response = requests.post(apiUrl, headers=headers, json=data) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-kling-v1/post-kling-videos-image2video-frames === Document URL: https://useapi.net/docs/api-kling-v1/post-kling-videos-image2video-frames --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/image2video-frames description: "Generate a Kling video from start, end and keyframe images via POST videos/image2video-frames in the useapi.net Kling API v1 — Kling 4.0 with up to 9 keyframes in up to 4K, 4.0 Flash from a start frame, v3.0 with elements, v2.6 and older." parent: Kling API nav_order: 340 --- ## Create Video From Image Frames April 18, 2025 (November 19, 2026) --- This endpoint generates a video from one or two images (start and end frames). Kling 4.0 also takes keyframes between them, up to 10 images in total, and the duration sets how many images you can use. | Model | Start<br>Frame | End<br>Frame | Keyframes | Elements | Audio | Multi-<br>shot | |-------|:--:|:--:|:--:|:--:|:--:|:--:| | kling-v4-0 | Yes <br>Required | Yes | Yes <br>Up to 9 | No | Yes <br>always on | Yes <br>always on | | kling-v4-0-flash | Yes <br>Required | No | No | No | Yes <br>always on | No <br>no custom shots | | kling-v3-0 | Yes <br>Required | Yes | No | Yes <br>Up to 3 | Yes <br>default on | Yes | | kling-v3-0-turbo | Yes <br>Required | No | No | No | Yes <br>always on | No | | kling-v2-6 | Yes <br>Required | Yes | No | No | Yes <br>Native<br>(Pro) | No | | kling-v2-5 | Yes <br>Required | Yes | No | No | Yes <br>SFX | No | | kling-v2-1 | Yes <br>Required | Yes | No | No | Yes <br>SFX | No | | kling-v2-1-master | Yes <br>Required | No | No | No | Yes <br>SFX | No | | kling-v1-6 | Yes | Yes | No | No | Yes <br>SFX | No | | kling-v1-5 | Yes | Yes | No | No | Yes <br>SFX | No | - **Duration**: `kling-v4-0` supports 3–30s, `kling-v4-0-flash` 3–20s, `kling-v3-0` / `kling-v3-0-turbo` support 3–15s, and all other models support 5s or 10s. - **SFX** = Sound Effects. - **Native** = Native Audio (model `2.6`, `pro` mode, start frame only). Kling 4.0 generates 720p (`std`), 1080p (`pro`) and 4K (`4k`) video, and HDR video at 1080p or 4K with `hdr: true`. Kling offers 1080p and 4K to paid Kling subscribers only. It costs 10 credits a second at 720p, 15 at 1080p and 35 at 4K. HDR adds 3 credits a second at 1080p and 5 at 4K, and Kling charges subscribers nothing extra for HDR until November 30, 2026 (see the [cost calculator](/docs/api-kling-v1#pricing)). Kling 4.0 Flash (`kling-v4-0-flash`) generates 720p (`std`) video only, 3 to 20 seconds, from the start frame (`image`) alone, at a lower [price](/docs/api-kling-v1#pricing) than 4.0. To use [elements](/docs/api-kling-v1/post-kling-elements) with Kling 4.0, use [POST videos/omni](/docs/api-kling-v1/post-kling-videos-omni) with `omni_version` `v4` or `v4-flash`. If your Kling account can't use Kling 4.0 or 4.0 Flash yet, the request returns a [`403`](#responses) error. > **https://api.useapi.net/v1/kling/videos/image2video-frames** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "email": "user@example.com", "image": "https://example.com/start-image.jpg", "keyframe_1": "https://example.com/keyframe-1.jpg", "image_tail": "https://example.com/end-image.jpg", "prompt": "A futuristic city with flying cars and tall buildings", "duration": "10", "model_name": "kling-v4-0", "mode": "pro", "replyUrl": "https://your-callback-url.com/webhook", "replyRef": "your-reference-id" } ``` - `email` is optional. Leave it out and the job goes to one of your [accounts](/docs/api-kling-v1/get-kling-accounts) that has a free job slot, picked at random. Each account runs at most its `maxJobs` jobs at once, and [GET scheduler/available](/docs/api-kling-v1/get-kling-scheduler-available) shows the free slots. If no account has a free slot, the response is `429`. Pass `email` to run the job on that account (`429` if it is busy). Uploaded files, elements, voices, avatars and earlier tasks belong to one account, so pass the `email` of the account they came from. With more than one account, reading the task with [GET tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) needs its account's `email`. The response's `task.userId` is that account's `session.userId` in [GET accounts](/docs/api-kling-v1/get-kling-accounts), and [GET scheduler](/docs/api-kling-v1/get-kling-scheduler) lists each running task with its `email`. - `image` is required if `image_tail` is not provided. URL to the start frame image. Required for models `2.x`, `3.0`, `4.0` and `4.0 Flash`. Image can be uploaded using [POST /assets](/docs/api-kling-v1/post-kling-assets) and the returned URLs can be used here. - `image_tail` is required if `image` is not provided. URL to the end frame image. Models `2.1 Master`, `3.0 Turbo` and `4.0 Flash` do not support this parameter. Image can be uploaded using [POST /assets](/docs/api-kling-v1/post-kling-assets) and the returned URLs can be used here. - `keyframe_1` through `keyframe_9` are optional, URLs to keyframe images placed between the start frame (`image`) and the end frame (`image_tail`), in order. Supported by `kling-v4-0` only (not `kling-v4-0-flash`). They require `image` and must be consecutive, starting from `keyframe_1`. A video takes up to 10 images in total, so you can add up to 8 keyframes together with `image_tail`, or up to 9 without it. The total number of images (`image`, `keyframe_N` and `image_tail`) can be at most the `duration` in seconds plus one, and at most 10: | `duration` | Max images in total | |---|---| | `3` | 4 | | `4` | 5 | | `5` (default) | 6 | | `6` | 7 | | `7` | 8 | | `8` | 9 | | `9` to `30` | 10 | When you leave out `duration` and send more than 6 images, the duration becomes the number of images minus one, so 7 images make a 6-second video. Images can be uploaded using [POST /assets](/docs/api-kling-v1/post-kling-assets) and the returned URLs can be used here. - `element_1`, `element_2`, `element_3` are optional, references to saved [elements](/docs/api-kling-v1/post-kling-elements) (e.g. `u_309377170505500`) used to guide the generation alongside the start/end frames. Up to 3 combined. Supported by model `3.0` only. For elements with Kling 4.0, use [POST videos/omni](/docs/api-kling-v1/post-kling-videos-omni) with `omni_version` `v4`. - `prompt` is optional, text description to guide the video generation. Maximum length: 8000 characters for models `4.0` and `4.0 Flash`, and 2500 characters for every other model. Cannot be used together with multi-shot parameters (`shot_N_prompt`/`shot_N_duration`). - `negative_prompt` is optional, what not to include in the generated video. Models `2.5`, `2.6`, `3.0`, `4.0` and `4.0 Flash` do not support this parameter. Maximum length: 2500 characters. - `cfg_scale` is optional, guidance scale for image-to-video generation. Models `2.x`, `3.0`, `4.0` and `4.0 Flash` do not support this parameter. Range: `0` to `1`. Default: `0.5`. - `duration` is optional, length of the video in seconds. Cannot be used together with multi-shot parameters (`shot_N_prompt`/`shot_N_duration`). Model `4.0`: `3` to `30` seconds (default `5`). Model `4.0 Flash`: `3` to `20` seconds (default `5`). Models `3.0` and `3.0 Turbo`: `3` to `15` seconds (default `5`). Other models: `5` (default) or `10`. - `model_name` is optional, the AI model version to use. Supported values: `kling-v4-0`, `kling-v4-0-flash`, `kling-v3-0`, `kling-v3-0-turbo`, `kling-v2-6`, `kling-v2-5`, `kling-v2-1` (default), `kling-v2-1-master`, `kling-v1-6`, `kling-v1-5`. Models `3.0`, `3.0 Turbo`, `4.0` and `4.0 Flash` do not support `aspect_ratio` (derived from input image). Model `3.0` enables audio by default, set `enable_audio: false` to disable it. Model `3.0 Turbo` (`kling-v3-0-turbo`) is a faster 3.0 variant: start frame only (no `image_tail`), `std`/`pro` modes (no `4k`), audio always on (`enable_audio` not supported), and no `element_N` references or multi-shot. Model `4.0` (`kling-v4-0`) always generates stereo audio and takes 3 to 30 seconds. It takes keyframes but no `element_N` references. Model `4.0 Flash` (`kling-v4-0-flash`) generates 720p only (`std`), always generates audio and takes 3 to 20 seconds. It takes the start frame (`image`) only: no `image_tail`, `keyframe_N`, `element_N` or multi-shot parameters. - `mode` is optional, quality level. Model `2.1 Master` only supports `pro` mode. Supported values: `std` (standard, default), `pro` (higher quality, slower generation), or `4k` (4K resolution, models `3.0` and `4.0`). Model `2.6` supports `std` and `pro`, but `pro` is required when `enable_audio` is `true`. Model `3.0` adds support for `4k`. Model `3.0 Turbo` supports `std` and `pro` only. Model `4.0` supports `std` (720p), `pro` (1080p) and `4k`. Kling offers 1080p and 4K to paid Kling subscribers only. Model `4.0 Flash` supports `std` (720p) only. Models `1.5`, `1.6` and `2.1` have no `4k`: `mode: 4k` runs as `pro` and the response lists that in `warnings`. With `image_tail` (End Frame), models `1.5`, `1.6`, `2.1`, `2.5` and `2.6` always run in `pro` (Kling has no `std` end-frame task). Leave `mode` out or set `pro`. Any other `mode` runs as `pro` and the response lists that in `warnings`. - `hdr` is optional, generate HDR video (model `4.0` only). Supported values: `false` (default) or `true`. Needs `mode` `pro` (1080p) or `4k`, because Kling makes no HDR video at 720p. `hdr: true` with `mode` `std` (the default), or `hdr` with another model, returns [`400`](#responses). HDR adds 3 credits a second at 1080p and 5 at 4K. Kling charges subscribers nothing extra for HDR until November 30, 2026. The task's own link is a 1080p standard-range preview: download the 4K or HDR file with [GET /assets/download](/docs/api-kling-v1/get-kling-assets-download) (4K: 3840×2160 H.264; HDR: 10-bit HEVC in HLG). - `enable_audio` is optional, add audio to the generated video. Supported values: `false` or `true`. The default depends on the model: `true` on model `3.0`, `false` on every other model that accepts it. Model `3.0` defaults to audio enabled (including `4k`); set `enable_audio: false` to disable. Models `3.0 Turbo`, `4.0` and `4.0 Flash` always generate audio and do not accept this parameter. Model `2.6`: Native Audio (AI-generated audio synced with video), requires `mode: pro`, not available with End Frame. Other models: Sound Effects (basic audio generation). - `multi_shot` is optional, let the model cut the video into several shots on its own (models `3.0` and `4.0`). Supported values: `false` (default) or `true`. You write one ordinary `prompt` and Kling decides where the cuts fall — use `shot_1_prompt` below instead when you want to direct each shot yourself. Ignored when `shot_1_prompt` is present — directing the shots yourself already turns multi-shot on. Model `4.0` always lets the model use several shots, so it accepts only `multi_shot: true`. Models `3.0` and `4.0` accept this parameter. Every other model, including `3.0 Turbo` and `4.0 Flash`, rejects it outright — even `multi_shot: false`. - `shot_1_prompt` through `shot_6_prompt` are optional, per-shot text prompts for multi-shot storytelling (models `3.0` and `4.0`). Maximum length: 2500 characters per shot. Minimum 2 shots required. Cannot be used together with `prompt` or `duration`. - `shot_1_duration` through `shot_6_duration` are optional, per-shot duration in seconds. Each shot must have both prompt and duration. Total duration must be 3-15 seconds. Shots must be sequential with no gaps (e.g. `shot_1` + `shot_2`, not `shot_1` + `shot_3`). - `maxJobs` is optional, range from `1` to `50`. Specifies the maximum number of concurrent jobs. - `replyUrl` is optional, a callback URL to receive generation progress and result. See [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id#model) for response model. - `replyRef` is optional, a reference identifier for the callback. **Notes:** - At least one of `image` or `image_tail` must be provided. - With `image_tail` on models `1.x` and `2.x` the video is always generated in `pro` (Kling runs the end frame in `pro` only). Another `mode` runs as `pro` and the response lists that in `warnings`. - Element references (`element_1`-`element_3`) require model `3.0`. - Keyframes (`keyframe_1`-`keyframe_9`) require `kling-v4-0` (not `kling-v4-0-flash`). The total number of images can be at most the `duration` plus one (4 to 10). - Model `3.0 Turbo` supports the start frame only — no end frame (`image_tail`), `element_N` references, or multi-shot. - Model `4.0 Flash` supports the start frame only — no end frame (`image_tail`), keyframes, `element_N` references, or multi-shot. ##### Responses **200** **200 OK** ```json { "task": { "id": 123456789, "userId": 12345, "type": "m2v_img2video_hq", "scene": "NORMAL_CREATION", "status": 5, "status_name": "submitted", "status_final": false, "taskInfo": { "type": "m2v_img2video_hq", "inputs": [ { "name": "input", "inputType": "URL", "token": null, "blobStorage": null, "url": "https://example.com/start-image.jpg", "cover": null, "fromWorkId": null }, { "name": "tail_image", "inputType": "URL", "token": null, "blobStorage": null, "url": "https://example.com/end-image.jpg", "cover": null, "fromWorkId": null } ], "arguments": [ { "name": "prompt", "value": "A futuristic city with flying cars and tall buildings" }, { "name": "negative_prompt", "value": "people, low quality, distorted" }, { "name": "duration", "value": "5" }, { "name": "kling_version", "value": "2.1" }, { "name": "tail_image_enabled", "value": "true" } ], "extraArgs": {}, "callbackPayloads": [], "scene": "NORMAL_CREATION" }, "favored": false, "deleted": false, "viewed": false, "createTime": 1745376611075, "updateTime": 1745376611075 }, "works": [], "status": 5, "status_name": "submitted", "status_final": false, "message": "", "limitation": { "type": "m2v_img2video_hq", "remaining": 10000, "limit": 10000 }, "userPoints": { "points": [], "total": 0 }, "userTickets": { "ticket": [] }, "editProject": null } ``` When the model cannot honor a value of the request, the job still runs the way it always has and the response adds a `warnings` array that says what was used instead, for example `"warnings": ["an end frame (image_tail) needs pro on kling-v2-1; mode std runs as pro"]`. The field is left out when there is nothing to report. **400** **400 Bad Request** The parameters are invalid. When Kling refuses the submitted parameters, `error` carries Kling's own message. ```json { "error": "image or image_tail is required" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **403** **403 Forbidden** Your Kling account can't use the requested model yet, for example Kling 4.0 or 4.0 Flash. ```json { "error": "This Kling account does not have access to the requested model or feature (AUTH.VPrivilegeEscalation)", "message": "Service busy (AUTH.VPrivilegeEscalation)" } ``` **404** **404 Not Found** Kling was unable to locate one of the referenced assets. Make sure to use [POST /assets](/docs/api-kling-v1/post-kling-assets) to upload assets. ```json { "error": "Sorry, the requested resource was not found (VALID.ResourceNotFound)", "message": "Not Found" } ``` **412** **412 Precondition Failed** The Kling account named in `error` is out of credits, and Kling did not create a task. Add credits or upgrade the plan of that account on [kling.ai](https://kling.ai), or send the job to another account with `email`. `message` keeps Kling's own text. ```json { "error": "Kling account user@example.com is out of credits: Credit are insufficient, you can upgrade your membership or purchase credit. (TASK.PointNotEnough)", "message": "积分消费失败 (TASK.PointNotEnough)" } ``` **500** **500 Internal Server Error** Kling uses a `500` response to indicate moderation and other issues with the input. It may be hard to separate actual 500 errors from moderation errors, so use the `error` field text and your best judgement to tell them apart, since the `message` field most often has very generic and perhaps misleading text. ```json { "error": "The content you uploaded appears to violate the community guidelines. (CM_EXT.POther)", "message": "Service busy (CM_EXT.POther)" } ``` When successful, the response includes a task ID which can be used to check the status using [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id). ##### Model The new task, with its `task.id` and `status_name`: poll it with [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) until `status_final` is `true`. <details markdown="block" class="model-details"> <summary>The task record, field by field</summary> ```typescript { // TypeScript, all fields are optional task: { id: number userId: number type: string scene: string status: number status_name: 'submitted' | 'failed' | 'processing' | 'succeed' status_final: boolean taskInfo: { type: string inputs: Array<{ name: string inputType: string token: string | null blobStorage: any | null url: string cover: string | null fromWorkId: number | null }> arguments: Array<{ name: string value: string }> extraArgs: Record<string, any> callbackPayloads: any[] scene: string } favored: boolean deleted: boolean viewed: boolean createTime: number updateTime: number viewTime: number } works: Array<any> status: number status_name: 'submitted' | 'failed' | 'processing' | 'succeed' status_final: boolean message: string error: string limitation: { type: string remaining: number limit: number } userPoints: { points: Array<{ orderId: string type: string amount: number balance: number startTime: number endTime: number }> total: number } userTickets: { ticket: Array<{ orderId: string type: string packageType: string amount: number balance: number startTime: number endTime: number }> } editProject: any | null warnings: string[] // only when a value of the request was run differently, e.g. mode 4k as pro } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/kling/videos/image2video-frames" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "email": "user@example.com", "image": "https://example.com/start-image.jpg", "image_tail": "https://example.com/end-image.jpg", "prompt": "A futuristic city with flying cars and tall buildings", "negative_prompt": "people, low quality, distorted" }' ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const apiUrl = "https://api.useapi.net/v1/kling/videos/image2video-frames"; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ email: email, image: "https://example.com/start-image.jpg", image_tail: "https://example.com/end-image.jpg", prompt: "A futuristic city with flying cars and tall buildings", negative_prompt: "people, low quality, distorted" }) }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured account email" apiUrl = "https://api.useapi.net/v1/kling/videos/image2video-frames" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } data = { "email": email, "image": "https://example.com/start-image.jpg", "image_tail": "https://example.com/end-image.jpg", "prompt": "A futuristic city with flying cars and tall buildings", "negative_prompt": "people, low quality, distorted" } response = requests.post(apiUrl, headers=headers, json=data) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-kling-v1/post-kling-videos-lipsync === Document URL: https://useapi.net/docs/api-kling-v1/post-kling-videos-lipsync --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/lipsync description: "Sync character lips to an audio file in a Kling video (max 60 seconds) via POST videos/lipsync in the useapi.net Kling API v1." parent: Kling API nav_order: 380 --- ## Apply Lip Sync to Video April 18, 2025 (November 16, 2026) --- This endpoint applies lip sync to a video using an audio file, making the character in the video appear to speak the audio. Video cannot be longer than 60 seconds. We suggest using PixVerse Lip Sync [POST pixverse/videos/lipsync](/docs/api-pixverse-v2/post-pixverse-videos-lipsync) for longer videos. PixVerse can lip sync videos over 60 seconds long and has much more relaxed requirements for character face visibility. > **https://api.useapi.net/v1/kling/videos/lipsync** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "email": "user@example.com", "video": "https://example.com/video.mp4", "audio": "https://example.com/audio.mp3", "replyUrl": "https://your-callback-url.com/webhook", "replyRef": "your-reference-id" } ``` - `email` is optional. Leave it out and the job goes to one of your [accounts](/docs/api-kling-v1/get-kling-accounts) that has a free job slot, picked at random. Each account runs at most its `maxJobs` jobs at once, and [GET scheduler/available](/docs/api-kling-v1/get-kling-scheduler-available) shows the free slots. If no account has a free slot, the response is `429`. Pass `email` to run the job on that account (`429` if it is busy). Uploaded files, elements, voices, avatars and earlier tasks belong to one account, so pass the `email` of the account they came from. With more than one account, reading the task with [GET tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) needs its account's `email`. The response's `task.userId` is that account's `session.userId` in [GET accounts](/docs/api-kling-v1/get-kling-accounts), and [GET scheduler](/docs/api-kling-v1/get-kling-scheduler) lists each running task with its `email`. - `video` is **required**, URL to the video that contains a face to sync with. Video cannot be longer than 60 seconds. Video can be uploaded using [POST /assets](/docs/api-kling-v1/post-kling-assets) and the returned URL can be used here. - `audio` is **required**, URL to the audio file containing speech. Audio can be uploaded using [POST /assets](/docs/api-kling-v1/post-kling-assets) and the returned URL can be used here. - `maxJobs` is optional, range from `1` to `50`. Specifies the maximum number of concurrent jobs. - `replyUrl` is optional, a callback URL to receive generation progress and result. See [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id#model) for response model. - `replyRef` is optional, a reference identifier for the callback. **Notes:** - The video should contain a clear frontal view of a face with lip movements. - Supported audio formats include MP3, WAV, and other common audio formats. - If the audio is shorter than the video, the excess video will be muted. If it's longer, the excess audio will be discarded. ##### Responses **200** **200 OK** ```json { "task": { "id": 123456789, "userId": 12345, "type": "m2v_video_lip_sync", "scene": "NORMAL_CREATION", "status": 5, "status_name": "submitted", "status_final": false, "taskInfo": { "type": "m2v_video_lip_sync", "inputs": [ { "name": "video", "inputType": "URL", "token": null, "blobStorage": null, "url": "https://example.com/video.mp4", "cover": null, "fromWorkId": null }, { "name": "audio", "inputType": "URL", "token": null, "blobStorage": null, "url": "https://example.com/audio.mp3", "cover": null, "fromWorkId": null } ], "arguments": [ { "name": "__filename", "value": "audio.mp3" }, { "name": "__isLocalAudio", "value": "true" }, { "name": "biz", "value": "klingai" } ], "extraArgs": {}, "callbackPayloads": [], "scene": "NORMAL_CREATION" }, "favored": false, "deleted": false, "viewed": false, "createTime": 1745376611075, "updateTime": 1745376611075 }, "works": [], "status": 5, "status_name": "submitted", "status_final": false, "message": "", "limitation": { "type": "m2v_video_lip_sync", "remaining": 10000, "limit": 10000 }, "userPoints": { "points": [], "total": 0 }, "userTickets": { "ticket": [] }, "editProject": null } ``` **400** **400 Bad Request** The parameters are invalid. When Kling refuses the submitted parameters, `error` carries Kling's own message. ```json { "error": "Parameter video is required" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** Kling was unable to locate one of the referenced assets. Make sure to use [POST /assets](/docs/api-kling-v1/post-kling-assets) to upload assets. ```json { "error": "Sorry, the requested resource was not found (VALID.ResourceNotFound)", "message": "Not Found" } ``` **412** **412 Precondition Failed** The Kling account named in `error` is out of credits, and Kling did not create a task. Add credits or upgrade the plan of that account on [kling.ai](https://kling.ai), or send the job to another account with `email`. `message` keeps Kling's own text. ```json { "error": "Kling account user@example.com is out of credits: Credit are insufficient, you can upgrade your membership or purchase credit. (TASK.PointNotEnough)", "message": "积分消费失败 (TASK.PointNotEnough)" } ``` **500** **500 Internal Server Error** Kling uses a `500` response to indicate moderation and other issues with the input. It may be hard to separate actual 500 errors from moderation errors, so use the `error` field text and your best judgement to tell them apart, since the `message` field most often has very generic and perhaps misleading text. ```json { "error": "The content you uploaded appears to violate the community guidelines. (CM_EXT.POther)", "message": "Service busy (CM_EXT.POther)" } ``` When successful, the response includes a task ID which can be used to check the status using [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id). ##### Model The new task, with its `task.id` and `status_name`: poll it with [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) until `status_final` is `true`. <details markdown="block" class="model-details"> <summary>The task record, field by field</summary> ```typescript { // TypeScript, all fields are optional task: { id: number userId: number type: string scene: string status: number status_name: 'submitted' | 'failed' | 'processing' | 'succeed' status_final: boolean taskInfo: { type: string inputs: Array<{ name: string inputType: string token: string | null blobStorage: any | null url: string cover: string | null fromWorkId: number | null }> arguments: Array<{ name: string value: string }> extraArgs: Record<string, any> callbackPayloads: any[] scene: string } favored: boolean deleted: boolean viewed: boolean createTime: number updateTime: number viewTime: number } works: Array<any> status: number status_name: 'submitted' | 'failed' | 'processing' | 'succeed' status_final: boolean message: string error: string limitation: { type: string remaining: number limit: number } userPoints: { points: Array<{ orderId: string type: string amount: number balance: number startTime: number endTime: number }> total: number } userTickets: { ticket: Array<{ orderId: string type: string packageType: string amount: number balance: number startTime: number endTime: number }> } editProject: any | null } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/kling/videos/lipsync" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "email": "user@example.com", "video": "https://example.com/video.mp4", "audio": "https://example.com/audio.mp3" }' ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const apiUrl = "https://api.useapi.net/v1/kling/videos/lipsync"; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ email: email, video: "https://example.com/video.mp4", audio: "https://example.com/audio.mp3" }) }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured account email" apiUrl = "https://api.useapi.net/v1/kling/videos/lipsync" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } data = { "email": email, "video": "https://example.com/video.mp4", "audio": "https://example.com/audio.mp3" } response = requests.post(apiUrl, headers=headers, json=data) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-kling-v1/post-kling-videos-motion-create === Document URL: https://useapi.net/docs/api-kling-v1/post-kling-videos-motion-create --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/motion-create description: "Transfer motion from a reference video onto a static image via POST videos/motion-create in the useapi.net Kling API v1 — Kling v3.0 and v2.6 motion control models." parent: Kling API nav_order: 390 --- ## Create Video from Motion and Image October 7, 2025 (November 16, 2026) --- This endpoint applies motion from a reference video to a static image, creating an animated video where the character in the image performs the motion. Supports Kling v3.0 (default) and v2.6 motion control models. Optionally attach an element for improved character consistency. > **https://api.useapi.net/v1/kling/videos/motion-create** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "email": "user@example.com", "model_name": "kling-v3-0", "imageUrl": "https://example.com/person.jpg", "motionUrl": "https://example.com/dance-video.mp4", "prompt": "Person dancing energetically", "keepAudio": true, "motionDirection": "motion_direction", "mode": "std", "element_1": "u_123456789012345", "replyUrl": "https://your-callback-url.com/webhook", "replyRef": "your-reference-id" } ``` - `email` is optional. Leave it out and the job goes to one of your [accounts](/docs/api-kling-v1/get-kling-accounts) that has a free job slot, picked at random. Each account runs at most its `maxJobs` jobs at once, and [GET scheduler/available](/docs/api-kling-v1/get-kling-scheduler-available) shows the free slots. If no account has a free slot, the response is `429`. Pass `email` to run the job on that account (`429` if it is busy). Uploaded files, elements, voices, avatars and earlier tasks belong to one account, so pass the `email` of the account they came from. With more than one account, reading the task with [GET tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) needs its account's `email`. The response's `task.userId` is that account's `session.userId` in [GET accounts](/docs/api-kling-v1/get-kling-accounts), and [GET scheduler](/docs/api-kling-v1/get-kling-scheduler) lists each running task with its `email`. - `model_name` is optional, must be `kling-v3-0` or `kling-v2-6`. Selects the motion control model version. v3.0 provides upgraded motion capture with high facial consistency. Default: `kling-v3-0` - `imageUrl` is **required**, URL to the image containing the person. The person's body and pose should be clearly visible. Must be uploaded via [POST /assets](/docs/api-kling-v1/post-kling-assets) first - use the `url` field from the response. - `motionUrl` is **required**, URL to the motion reference video (3-30 seconds). The video provides the motion that will be applied to the person in the image. Use [GET /videos/motions](/docs/api-kling-v1/get-kling-videos-motions) to retrieve official Kling motions or your previously uploaded motions. To upload a new motion video, use [POST /assets](/docs/api-kling-v1/post-kling-assets) - use the `resourceUrl` field from the response. - `prompt` is optional, string up to 2500 characters. Text description to guide the video generation. - `keepAudio` is optional, boolean. When `true`, preserves the original audio from the motion video. Default: `false` - `motionDirection` is optional, must be `motion_direction` or `image_direction`. - `motion_direction` (default): The generated video follows the motion from the reference video - `image_direction`: The generated video follows the pose/direction from the source image - `mode` is optional, must be `std` or `pro`. Generation quality mode. Pro mode provides higher quality but costs more. Default: `std` - `element_1` is optional, a saved element ID (e.g., `u_123456789012345`) for improved character consistency. Only supported with `kling-v3-0`. Create elements using [POST /elements](/docs/api-kling-v1/post-kling-elements). The element's cover image is included in the generation inputs. - `maxJobs` is optional, range from `1` to `50`. Specifies the maximum number of concurrent jobs. - `replyUrl` is optional, a callback URL to receive generation progress and result. See [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id#model) for response model. - `replyRef` is optional, a reference identifier for the callback. **Notes:** - The image must contain at least one clearly visible person with detectable pose - The endpoint validates the image before processing - returns error if no character detected - Video duration is automatically detected from the motion video ##### Responses **200** **200 OK** ```json { "task": { "id": 299640525521807, "userId": 23555898, "type": "m2v_motion_control", "scene": "NORMAL_CREATION", "status": 5, "status_name": "submitted", "status_final": false, "taskInfo": { "type": "m2v_motion_control", "inputs": [ { "name": "video", "inputType": "URL", "url": "https://example.com/dance-video.mp4", "cover": "" }, { "name": "image", "inputType": "URL", "url": "https://example.com/person.jpg" } ], "arguments": [ { "name": "biz", "value": "klingai" }, { "name": "prompt", "value": "Person dancing energetically" }, { "name": "duration", "value": 5.76 }, { "name": "imageCount", "value": 1 }, { "name": "kling_version", "value": "3.0" }, { "name": "keep_original_sound", "value": false }, { "name": "motion_direction", "value": "motion_direction" }, { "name": "model_mode", "value": "std" } ], "callbackPayloads": [ { "name": "motionFrom", "value": "LOCAL" } ] }, "createTime": 1767669665000, "updateTime": 1767669665000 }, "works": [], "status": 5, "status_name": "submitted", "status_final": false, "message": "" } ``` **400** **400 Bad Request** The parameters are invalid. When Kling refuses the submitted parameters, `error` carries Kling's own message. Image validation failed - no detectable character in image: ```json { "status": 1, "message": "MOTION.PIC_NOT_MATCHED" } ``` Missing required parameter: ```json { "error": "Parameter imageUrl is required" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **412** **412 Precondition Failed** The Kling account named in `error` is out of credits, and Kling did not create a task. Add credits or upgrade the plan of that account on [kling.ai](https://kling.ai), or send the job to another account with `email`. `message` keeps Kling's own text. ```json { "error": "Kling account user@example.com is out of credits: Credit are insufficient, you can upgrade your membership or purchase credit. (TASK.PointNotEnough)", "message": "积分消费失败 (TASK.PointNotEnough)" } ``` **500** **500 Internal Server Error** Kling uses a `500` response to indicate moderation and other issues with the input. ```json { "error": "The content you uploaded appears to violate the community guidelines. (CM_EXT.POther)", "message": "Service busy (CM_EXT.POther)" } ``` When successful, the response includes a task ID which can be used to check the status using [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id). ##### Model The new task, with its `task.id` and `status_name`: poll it with [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) until `status_final` is `true`. <details markdown="block" class="model-details"> <summary>The task record, field by field</summary> ```typescript { // TypeScript, all fields are optional task: { id: number userId: number type: string // "m2v_motion_control" scene: string status: number status_name: 'submitted' | 'failed' | 'processing' | 'succeed' status_final: boolean taskInfo: { type: string inputs: Array<{ name: string inputType: string url: string cover?: string }> arguments: Array<{ name: string value: string | number | boolean }> callbackPayloads: Array<{ name: string value: string }> } createTime: number updateTime: number } works: Array<any> status: number status_name: 'submitted' | 'failed' | 'processing' | 'succeed' status_final: boolean message: string error?: { type: string detail: string } } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/kling/videos/motion-create" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ..." \ -d '{ "email": "user@example.com", "model_name": "kling-v3-0", "imageUrl": "https://s15-kling.klingai.com/.../person.jpg", "motionUrl": "https://v15-kling.klingai.com/.../dance.mp4", "prompt": "Person dancing energetically", "keepAudio": true, "mode": "std", "element_1": "u_123456789012345" }' ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const apiUrl = "https://api.useapi.net/v1/kling/videos/motion-create"; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ email: email, model_name: "kling-v3-0", imageUrl: "https://s15-kling.klingai.com/.../person.jpg", motionUrl: "https://v15-kling.klingai.com/.../dance.mp4", prompt: "Person dancing energetically", keepAudio: true, mode: "std", element_1: "u_123456789012345" }) }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured account email" apiUrl = "https://api.useapi.net/v1/kling/videos/motion-create" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } data = { "email": email, "model_name": "kling-v3-0", "imageUrl": "https://s15-kling.klingai.com/.../person.jpg", "motionUrl": "https://v15-kling.klingai.com/.../dance.mp4", "prompt": "Person dancing energetically", "keepAudio": True, "mode": "std", "element_1": "u_123456789012345" } response = requests.post(apiUrl, headers=headers, json=data) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-kling-v1/post-kling-videos-omni === Document URL: https://useapi.net/docs/api-kling-v1/post-kling-videos-omni --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/omni description: "Generate Kling Omni videos (O1, v3, Kling 4.0 or 4.0 Flash) via POST videos/omni in the useapi.net Kling API v1 — image, element, video and voice references, frames and video transform." parent: Kling API nav_order: 330 --- ## Generate Videos with Omni December 11, 2025 (November 19, 2026) --- This endpoint generates videos using Kling's Omni model (`O1` and `v3`), Kling 4.0 (`v4`) and Kling 4.0 Flash (`v4-flash`). It supports multiple workflows for different use cases: - **Default workflow**: Text-to-video with optional image/element references - **Frames workflow**: Generate video between start and end frame images - **Video Reference workflow**: Use reference videos to guide generation style (up to 5 with `v4` and `v4-flash`) - **Video Transform workflow**: Transform/modify a reference video ##### Version Comparison | Feature | v4 | v4-flash | v3 | O1 | |---------|:--:|:--:|:--:|:--:| | Duration | 3-30s | 3-20s | 3-15s | 3-10s | | Mode | `std` (720p), `pro` (1080p), `4k` | `std` (720p) | `std`, `pro`, `4k` | `std`, `pro` | | HDR (`hdr`) | Yes `pro` or `4k` | No | No | No | | Multi-shot | No | No | Yes | No | | Native Audio | Yes Always on, stereo | Yes Always on | Yes `enable_audio` (default on, no video) | No | | Aspect Ratio | `16:9` (default), `9:16`, `1:1`, `21:9`, `auto` | `16:9` (default), `9:16`, `1:1`, `21:9`, `auto` | `16:9` (default), `9:16`, `1:1` | `16:9` (default), `9:16`, `1:1` | | Aspect Ratio `auto` | Yes | Yes | Frames workflow only | Frames workflow only | | Workflows | Default, Video Reference | Default, Video Reference | All | All | | Max `image_N` | 10 | 10 | 7 | 7 | | Max `element_N` | 7 | 7 | 7 | 7 | | Reference videos | Up to 5, 3-30s each, 30s in total | Up to 5, 3-20s each, 20s in total | 1, 3-15s | 1, 3-10s | | Voices (`voice_N`) | Up to 3 | No | No | No | | Prompt length | 8000 | 8000 | 1700 | 1700 | | VIDEO elements | Yes | Yes | Yes | No (IMAGE only) | Omni 4.0 costs the same as Kling 4.0 on [POST /videos/text2video](/docs/api-kling-v1/post-kling-videos-text2video), 10 credits a second at 720p (`std`), 15 at 1080p (`pro`) and 35 in 4K (`mode: 4k`). With a reference video (`video_1` to `video_5`) or a VIDEO element, Kling also counts the reference video's length. When the clip is at least as long as the reference videos, which it is by default, Omni 4.0 costs 12 credits a second at 720p, 18 at 1080p and 42 in 4K, and Omni 4.0 Flash 8. A clip shorter than its reference videos costs more: Kling bills the videos' seconds plus the clip's, at 6 credits a second at 720p, 9 at 1080p, 21 in 4K and 4 on Flash. For example, an 8-second reference video and a 5-second 1080p clip cost 117 credits (see the [cost calculator](/docs/api-kling-v1)). With `hdr: true` it makes HDR video at 1080p or 4K. HDR adds 3 credits a second at 1080p and 5 at 4K, and Kling charges subscribers nothing extra for HDR until November 30, 2026. Kling offers 1080p and 4K to paid Kling subscribers only. Omni 4.0 Flash (`v4-flash`) costs the same as Kling 4.0 Flash and generates 720p (`std`) video only, 3 to 20 seconds, without voices. If your Kling account can't use Kling 4.0 or 4.0 Flash yet, the request returns a [`403`](#responses) error. > **https://api.useapi.net/v1/kling/videos/omni** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "email": "user@example.com", "prompt": "A woman @image_1 dancing elegantly in a ballroom", "duration": "5", "aspect_ratio": "16:9", "count": 1, "image_1": "https://s21-kling.klingai.com/ai-platform/xxx/xxx.jpg" } ``` - `email` is optional. Leave it out and the job goes to one of your [accounts](/docs/api-kling-v1/get-kling-accounts) that has a free job slot, picked at random. Each account runs at most its `maxJobs` jobs at once, and [GET scheduler/available](/docs/api-kling-v1/get-kling-scheduler-available) shows the free slots. If no account has a free slot, the response is `429`. Pass `email` to run the job on that account (`429` if it is busy). Uploaded files, elements, voices, avatars and earlier tasks belong to one account, so pass the `email` of the account they came from. With more than one account, reading the task with [GET tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) needs its account's `email`. The response's `task.userId` is that account's `session.userId` in [GET accounts](/docs/api-kling-v1/get-kling-accounts), and [GET scheduler](/docs/api-kling-v1/get-kling-scheduler) lists each running task with its `email`. - `prompt` is **required** (unless using multi-shot), the text description of the video to generate. Maximum length: 8000 characters for `v4` and `v4-flash`, and 1700 characters for `o1` and `v3`. Cannot be used together with multi-shot parameters (`shot_N_prompt`/`shot_N_duration`). Use `@image_1`, `@image_2`, etc. to reference images in your prompt. Use `@element_1`, `@element_2`, etc. (or `@object_1`, etc.) to reference saved elements. Use `@video_1` to reference a video in your prompt (`@video_1` through `@video_5` with `v4` and `v4-flash`). Use `@voice_1`, `@voice_2` and `@voice_3` to reference voices with `v4`. - `omni_version` is optional, the Omni model version to use. Supported values: `o1`, `v3` (default), `v4`, `v4-flash`. Version `v4` uses Kling 4.0. It supports the default and video reference workflows, takes IMAGE and VIDEO elements, up to 5 reference videos and up to 3 voices, always generates stereo audio, and does not take `frame_start`/`frame_end`, `video_mode: transform` or multi-shot. For start, end and keyframe images with Kling 4.0, use [POST /videos/image2video-frames](/docs/api-kling-v1/post-kling-videos-image2video-frames) with `model_name: kling-v4-0`. Version `v4-flash` uses Kling 4.0 Flash. It works like `v4` with the same images, elements and up to 5 reference videos, but generates 720p (`std`) only, takes 3 to 20 seconds, accepts reference videos of 3-20 seconds each and 20 seconds in total, and takes no voices (`voice_N`). It always generates audio. For a start image with Kling 4.0 Flash, use [POST /videos/image2video-frames](/docs/api-kling-v1/post-kling-videos-image2video-frames) with `model_name: kling-v4-0-flash`. - `mode` is optional, the generation mode. Supported values: `std` (default), `pro`, or `4k` (4K resolution, `omni_version` `v3` and `v4`). Version `v4` supports `std` (720p), `pro` (1080p) and `4k`. Kling offers 1080p and 4K to paid Kling subscribers only. Version `v4-flash` supports `std` (720p) only. - `hdr` is optional, generate HDR video (`omni_version` `v4` only). Supported values: `false` (default) or `true`. Needs `mode` `pro` (1080p) or `4k`, because Kling makes no HDR video at 720p. `hdr: true` with `mode` `std` (the default), or `hdr` with another `omni_version`, returns [`400`](#responses). HDR adds 3 credits a second at 1080p and 5 at 4K. Kling charges subscribers nothing extra for HDR until November 30, 2026. The task's own link is a 1080p standard-range preview: download the 4K or HDR file with [GET /assets/download](/docs/api-kling-v1/get-kling-assets-download) (4K: 3840×2160 H.264; HDR: 10-bit HEVC in HLG). - `enable_audio` is optional, whether to generate native audio (a soundtrack) for the video. Default: `true`. Applies to `omni_version: v3` without a reference video. Set to `false` for a silent video, which uses the lower audio-off price tier. Not valid together with `video_1` (use `keep_audio` for video workflows), with `omni_version: o1`, or with `v4` and `v4-flash`, which always generate audio. ###### Workflow Selection The workflow is automatically determined based on which inputs you provide: | Inputs Provided | Workflow | |-----------------|----------| | `frame_start` (with optional `frame_end`) | Frames | | `video_1` with `video_mode=transform` | Video Transform | | `video_1` with `video_mode=reference` (default) | Video Reference | | Images/elements only, or text-only | Default | ###### Default Workflow (Images/Elements) Use images and/or saved elements as references in your prompt. - `image_1` through `image_7` are optional, URLs of reference images. You can upload images using [POST /assets](/docs/api-kling-v1/post-kling-assets). Reference in prompt using `@image_1`, `@image_2`, etc. - `image_8` through `image_10` are optional, more reference images for `v4` and `v4-flash` only. - `element_1` through `element_7` are optional, IDs of saved elements. Create elements using [POST /elements](/docs/api-kling-v1/post-kling-elements). Reference in prompt using `@element_1` or `@object_1`, etc. **Note:** For `o1` and `v3`, images and elements share the same pool of 7 slots. Combined total cannot exceed 7. For `v4` and `v4-flash`, you can use up to 10 images and up to 7 elements, with up to 15 references in total, counting `image_N`, `element_N`, `video_N` and `voice_N`. ###### Frames Workflow Generate video that transitions between a start frame and optional end frame. - `frame_start` is required for frames workflow, URL of the start frame image. Internally mapped to `image_1`. - `frame_end` is optional, URL of the end frame image. Internally mapped to `image_2`. Cannot be used without `frame_start`. **Restrictions:** When using frames workflow, `image_N`, `element_N`, and `video_1` are not allowed. Versions `v4` and `v4-flash` do not support the frames workflow. ###### Video Reference/Transform Workflow Use reference videos to guide generation or transform a video directly. - `video_1` is optional, URL of a reference video. You can upload videos using [POST /assets](/docs/api-kling-v1/post-kling-assets). Reference in prompt using `@video_1`. Video must be 3-10 seconds long (O1), 3-15 seconds (v3), 3-30 seconds (`v4`), or 3-20 seconds (`v4-flash`). - `video_2` through `video_5` are optional, more reference videos for `v4` and `v4-flash` only. Use them in order starting from `video_1`, and reference them in the prompt as `@video_2` through `@video_5`. Each video must be 3-30 seconds long (3-20 with `v4-flash`), and all reference videos together at most 30 seconds (20 with `v4-flash`). You can use up to 5 videos and VIDEO elements together, with at most 3 VIDEO elements. Versions `o1` and `v3` take `video_1` only. - `video_mode` is optional, how to use the video reference. Supported values: `reference` (default), `transform`. - `reference`: Video guides the style/motion of generated content - `transform`: Video is directly transformed/modified (not supported by `v4` or `v4-flash`) - `keep_audio` is optional, whether to keep the soundtrack of `video_1`. Default: `false`. Only applies when `video_1` is provided. With `v4` and `v4-flash`, `video_1` must have sound. **Note:** When using `video_1` with `o1` or `v3`, you can still include up to 4 images/elements (combined). Versions `v4` and `v4-flash` keep their usual limits. ###### Voices (v4 only) With `v4`, people in the video can speak in a voice you choose. - `voice_1`, `voice_2` and `voice_3` are optional, voices for `omni_version: v4`. Each takes a voice `id` or `name` from [GET /videos/voices](/docs/api-kling-v1/get-kling-videos-voices). To use your own voice, save it first with [POST /videos/voices](/docs/api-kling-v1/post-kling-videos-voices) and pass the same `email` here, because a saved voice belongs to that Kling account. Use them in order starting from `voice_1`, and reference them in the prompt as `@voice_1`, `@voice_2` and `@voice_3`, for example `A woman says "Good morning" in the voice of @voice_1`. Versions `o1`, `v3` and `v4-flash` return a `400` error for `voice_N`. Some voices have samples shorter than 3 seconds, which Kling does not accept — the request returns a [`400`](#responses) error. ###### Duration Support Matrix Duration availability depends on the workflow, inputs, and version: | Scenario | O1 Durations | v3 Durations | v4 Durations | v4-flash Durations | Notes | |----------|-------------|--------------|:-:|:-:|-------| | Text-only (no inputs) | `5`, `10` | `3`-`15` | `3`-`30` | `3`-`20` | O1 restricted | | Single start frame only | `5`, `10` | `3`-`15` | No | No | O1 restricted | | Images/elements provided | `3`-`10` | `3`-`15` | `3`-`30` | `3`-`20` | Full range | | Both frames (start + end) | `3`-`10` | `3`-`15` | No | No | Full range | | With reference videos | Locked to video length | Locked to video length | `3`-`30` | `3`-`20` | O1 and v3 cannot be changed, v4 and v4-flash default to the total length of the reference videos | - `duration` is optional, the duration in seconds. Default: `5`. Cannot be used together with multi-shot parameters (`shot_N_prompt`/`shot_N_duration`). **VIP required** for durations `7`-`10` (O1) or `7`-`15` (v3). Version `v4` takes `3` to `30` seconds, `v4-flash` `3` to `20` seconds. With `video_1` and `o1` or `v3`, the duration is the video's length and cannot be changed. With reference videos and `v4`, you can set `3` to `30` seconds. The default is the total length of the reference videos in whole seconds, from `3` to `30`. With `v4-flash` you can set `3` to `20` seconds, and the default is that total length, up to `20`. ###### Aspect Ratio Support Matrix | Workflow | Allowed Values | Default | |----------|---------------|---------| | Default (text/images/elements) | `16:9`, `9:16`, `1:1`, `21:9` and `auto` (`v4` and `v4-flash` only) | `16:9` | | Frames workflow | `auto` only | `auto` | | Video Reference/Transform | `16:9`, `9:16`, `1:1`, `21:9` and `auto` (`v4` and `v4-flash` only) | `16:9` | - `aspect_ratio` is optional. When using `frame_start`, aspect ratio is always `auto` (derived from input). With `o1` and `v3`, `auto` is NOT allowed for other workflows. ###### Input Limits Matrix | Workflow | Max Images | Max Elements | Max Combined | Max Video | Max Voices | |----------|------------|--------------|--------------|-----------|------------| | Default | 7 | 7 | 7 | 0 | 0 | | Frames | 0 | 0 | 0 | 0 | 0 | | Video Reference | 4 | 4 | 4 | 1 | 0 | | Video Transform | 4 | 4 | 4 | 1 | 0 | | `v4`, Default or Video Reference | 10 | 7 | 15 (`video_N` and `voice_N` included) | 5 (VIDEO elements included, at most 3 of them) | 3 | | `v4-flash`, Default or Video Reference | 10 | 7 | 15 (`video_N` included) | 5 (VIDEO elements included, at most 3 of them) | 0 | ###### Multi-shot (v3 only) Split a video into multiple shots, each with its own prompt and duration. Useful for storytelling with scene transitions. Either hand the whole job to the model with `multi_shot`, or direct each shot yourself with `shot_1_prompt` and friends. - `multi_shot` is optional, let the model cut the video into several shots on its own. Supported values: `false` (default) or `true`. You write one ordinary `prompt` and Kling decides where the cuts fall. Ignored when `shot_1_prompt` is present — directing the shots yourself already turns multi-shot on. - `shot_1_prompt` through `shot_6_prompt` are optional, per-shot text prompts. Maximum length: 2500 characters per shot. Minimum 2 shots required. Cannot be used together with `prompt` or `duration`. Use `@image_1`, `@element_1`, etc. references within shot prompts. - `shot_1_duration` through `shot_6_duration` are optional, per-shot duration in seconds. Each shot must have both prompt and duration. Total duration must be 3-15 seconds. Shots must be sequential with no gaps (e.g. `shot_1` + `shot_2`, not `shot_1` + `shot_3`). ###### Other Parameters - `count` is optional, the number of videos to generate. Range: `1` to `4`. Default: `1`. **VIP required** for counts `2`-`4`. - `maxJobs` is optional, range from `1` to `50`. Specifies the maximum number of concurrent jobs. - `replyUrl` is optional, a callback URL to receive generation progress and result. See [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id#model) for response model. - `replyRef` is optional, a reference identifier for the callback. ##### Prompt Reference Syntax Reference your inputs in the prompt using these patterns: | Input Type | Prompt Syntax | Example | |------------|---------------|---------| | Images | `@image_1`, `@image_2`, ... | `"A woman @image_1 dancing..."` | | Elements | `@element_1` or `@object_1`, ... | `"Character @element_1 walks..."` | | Frames | `@image_1`, `@image_2` | `"Scene transitions from @image_1 to @image_2"` | | Video | `@video_1` (`@video_1` through `@video_5` with `v4` and `v4-flash`) | `"Scene like @video_1 but in winter"` | | Voices (`v4`) | `@voice_1`, `@voice_2`, `@voice_3` | `'A woman says "Good morning" in the voice of @voice_1'` | ##### Responses **200** **200 OK** ```json { "task": { "id": 123456789, "userId": 12345, "type": "m2v_omni_video", "scene": "NORMAL_CREATION", "status": 5, "status_name": "submitted", "status_final": false, "taskInfo": { "type": "m2v_omni_video", "inputs": [ { "name": "image_1", "inputType": "URL", "token": null, "blobStorage": null, "url": "https://s21-kling.klingai.com/ai-platform/xxx/xxx.jpg", "cover": null, "fromWorkId": null } ], "arguments": [ { "name": "prompt", "value": "A woman Image1 dancing elegantly in a ballroom" }, { "name": "rich_prompt", "value": "A woman <<<image_1>>> dancing elegantly in a ballroom" }, { "name": "kling_version", "value": "o1" }, { "name": "model_mode", "value": "pro" }, { "name": "duration", "value": "5" }, { "name": "aspect_ratio", "value": "16:9" }, { "name": "imageCount", "value": "1" } ], "extraArgs": {}, "callbackPayloads": [], "scene": "NORMAL_CREATION" }, "favored": false, "deleted": false, "viewed": false, "createTime": 1733836800000, "updateTime": 1733836800000 }, "works": [], "status": 5, "status_name": "submitted", "status_final": false, "message": "", "limitation": { "type": "m2v_omni_video", "remaining": 10000, "limit": 10000 }, "userPoints": { "points": [], "total": 0 }, "userTickets": { "ticket": [] }, "editProject": null } ``` **400** **400 Bad Request** The parameters are invalid. When Kling refuses the submitted parameters, `error` carries Kling's own message, for example for a voice whose sample is too short. ```json { "error": "v40 audio duration must be between 3.0 and 30.1 seconds: audio_1 (TASK.InvalidArguments)" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **403** **403 Forbidden** Your Kling account can't use the requested model yet, for example Kling 4.0 or 4.0 Flash. ```json { "error": "This Kling account does not have access to the requested model or feature (AUTH.VPrivilegeEscalation)", "message": "Service busy (AUTH.VPrivilegeEscalation)" } ``` **404** **404 Not Found** ```json { "error": "<error message>" } ``` **412** **412 Precondition Failed** The Kling account named in `error` is out of credits, and Kling did not create a task. Add credits or upgrade the plan of that account on [kling.ai](https://kling.ai), or send the job to another account with `email`. `message` keeps Kling's own text. ```json { "error": "Kling account user@example.com is out of credits: Credit are insufficient, you can upgrade your membership or purchase credit. (TASK.PointNotEnough)", "message": "积分消费失败 (TASK.PointNotEnough)" } ``` **500** **500 Internal Server Error** Kling uses a `500` response to indicate moderation and other issues with the input. It may be hard to separate actual 500 errors from moderation errors, so use the `error` field text and your best judgement to tell them apart, since the `message` field most often has very generic and perhaps misleading text. ```json { "error": "The content you uploaded appears to violate the community guidelines. (CM_EXT.POther)", "message": "Service busy (CM_EXT.POther)" } ``` When successful, the response includes a task ID which can be used to check the status using [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id). ##### Model The new task, with its `task.id` and `status_name`: poll it with [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) until `status_final` is `true`. <details markdown="block" class="model-details"> <summary>The task record, field by field</summary> ```typescript { // TypeScript, all fields are optional task: { id: number userId: number type: string scene: string status: number status_name: 'submitted' | 'failed' | 'processing' | 'succeed' status_final: boolean taskInfo: { type: string inputs: Array<{ name: string inputType: string token: string | null blobStorage: any | null url: string cover: string | null fromWorkId: number | null }> arguments: Array<{ name: string value: string }> extraArgs: Record<string, any> callbackPayloads: any[] scene: string } favored: boolean deleted: boolean viewed: boolean createTime: number updateTime: number viewTime: number } works: Array<any> status: number status_name: 'submitted' | 'failed' | 'processing' | 'succeed' status_final: boolean message: string error: string limitation: { type: string remaining: number limit: number } userPoints: { points: Array<{ orderId: string type: string amount: number balance: number startTime: number endTime: number }> total: number } userTickets: { ticket: Array<{ orderId: string type: string packageType: string amount: number balance: number startTime: number endTime: number }> } editProject: any | null } ``` </details> ##### Examples **Curl** ``` bash # Default workflow with image curl -X POST "https://api.useapi.net/v1/kling/videos/omni" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ..." \ -d '{ "email": "user@example.com", "prompt": "A woman @image_1 dancing elegantly in a ballroom", "duration": "5", "aspect_ratio": "16:9", "image_1": "https://s21-kling.klingai.com/ai-platform/xxx/xxx.jpg" }' # Kling 4.0 with images, 21:9 curl -X POST "https://api.useapi.net/v1/kling/videos/omni" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ..." \ -d '{ "email": "user@example.com", "omni_version": "v4", "prompt": "The woman @image_1 walks into the cafe @image_2 and orders a coffee", "duration": "12", "aspect_ratio": "21:9", "image_1": "https://s21-kling.klingai.com/ai-platform/xxx/woman.jpg", "image_2": "https://s21-kling.klingai.com/ai-platform/xxx/cafe.jpg" }' # Kling 4.0 with a voice and two reference videos curl -X POST "https://api.useapi.net/v1/kling/videos/omni" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ..." \ -d '{ "email": "user@example.com", "omni_version": "v4", "prompt": "The dancer from @video_1 performs the moves from @video_2, then says \"Good morning\" in the voice of @voice_1", "duration": "10", "video_1": "https://s21-kling.klingai.com/ai-platform/xxx/dancer.mp4", "video_2": "https://s21-kling.klingai.com/ai-platform/xxx/moves.mp4", "voice_1": "Emma" }' # Kling 4.0 Flash with a reference video (720p, 3-20 s, no voices) curl -X POST "https://api.useapi.net/v1/kling/videos/omni" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ..." \ -d '{ "email": "user@example.com", "omni_version": "v4-flash", "prompt": "The dancer from @video_1 dances on a rooftop at sunset", "duration": "5", "video_1": "https://s21-kling.klingai.com/ai-platform/xxx/dancer.mp4" }' # Using saved element curl -X POST "https://api.useapi.net/v1/kling/videos/omni" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ..." \ -d '{ "email": "user@example.com", "prompt": "Character @element_1 walking through a garden", "duration": "5", "element_1": "u_123456789012345" }' # Frames workflow curl -X POST "https://api.useapi.net/v1/kling/videos/omni" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ..." \ -d '{ "email": "user@example.com", "prompt": "Smooth transition from @image_1 to @image_2", "duration": "5", "frame_start": "https://s21-kling.klingai.com/ai-platform/xxx/start.jpg", "frame_end": "https://s21-kling.klingai.com/ai-platform/xxx/end.jpg" }' # Video reference workflow curl -X POST "https://api.useapi.net/v1/kling/videos/omni" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ..." \ -d '{ "email": "user@example.com", "prompt": "Scene like @video_1 but in a winter setting", "video_1": "https://s21-kling.klingai.com/ai-platform/xxx/reference.mp4", "video_mode": "reference" }' ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const apiUrl = "https://api.useapi.net/v1/kling/videos/omni"; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ email: email, prompt: "Character @element_1 dancing elegantly", duration: "5", aspect_ratio: "16:9", element_1: "u_123456789012345" }) }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured account email" apiUrl = "https://api.useapi.net/v1/kling/videos/omni" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } data = { "email": email, "prompt": "Character @element_1 walking through garden", "duration": "5", "aspect_ratio": "16:9", "element_1": "u_123456789012345" } response = requests.post(apiUrl, headers=headers, json=data) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-kling-v1/post-kling-videos-text2video === Document URL: https://useapi.net/docs/api-kling-v1/post-kling-videos-text2video --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/text2video description: "Submit a text prompt to generate a Kling video via POST videos/text2video in the useapi.net Kling API v1 — Kling 4.0 (3-30s, 21:9, 1080p or 4K, HDR), 4.0 Flash (3-20s, 720p), v3.0, v3.0 Turbo, v2.6 native audio, and earlier models." parent: Kling API nav_order: 330 --- ## Create Video From Text April 18, 2025 (November 19, 2026) --- This endpoint generates a video based on a text prompt. ##### Model Support Matrix | Feature | v4.0 | v4.0 Flash | v3.0 | v3.0 Turbo | v2.6 | v2.5<br>v2.1 Master | v1.6<br>v1.5 | |---------|:----:|:----------:|:----:|:----------:|:----:|:------------------:|:----:| | Duration | 3-30s | 3-20s | 3-15s | 3-15s | 5/10s | 5/10s | 5/10s | | Aspect ratio `21:9` | Yes | Yes | No | No | No | No | No | | Mode `std`<br>720p | Yes | Yes | Yes | Yes | Yes | No | Yes | | Mode `pro`<br>1080p | Yes <br>Paid Kling plan | No | Yes | Yes | Yes | Yes | Yes | | Mode `4k`<br>4K | Yes <br>Paid Kling plan | No | Yes | No | No | No | No | | HDR<br>`hdr` | Yes <br>`pro` or `4k` | No | No | No | No | No | No | | Audio | Yes <br>Always on, stereo | Yes <br>Always on | Yes <br>Default on | Yes <br>Always on | Yes <br>Native Audio<br>(Pro) | Yes <br>Sound Effects | Yes <br>Sound Effects | | Multi-shot | Yes <br>Always on | No <br>No custom shots | Yes | No | No | No | No | | Prompt length | 8000 | 8000 | 2500 | 2500 | 2500 | 2500 | 2500 | | cfg_scale | No | No | No | No | No | No | Yes | Kling 4.0 generates 720p (`std`), 1080p (`pro`) and 4K (`4k`) video, and HDR video at 1080p or 4K with `hdr: true`. Kling offers 1080p and 4K to paid Kling subscribers only. It costs 10 credits a second at 720p, 15 at 1080p and 35 at 4K. HDR adds 3 credits a second at 1080p and 5 at 4K, and Kling charges subscribers nothing extra for HDR until November 30, 2026 (see the [cost calculator](/docs/api-kling-v1#pricing)). Kling 4.0 Flash (`kling-v4-0-flash`) generates 720p (`std`) video only, 3 to 20 seconds, at a lower [price](/docs/api-kling-v1#pricing) than 4.0. If your Kling account can't use Kling 4.0 or 4.0 Flash yet, the request returns a [`403`](#responses) error. > **https://api.useapi.net/v1/kling/videos/text2video** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "email": "user@example.com", "prompt": "A majestic mountain landscape with snow-capped peaks and flowing rivers", "negative_prompt": "people, buildings, text, low quality", "duration": "10", "model_name": "kling-v2-1-master", "aspect_ratio": "16:9", "replyUrl": "https://your-callback-url.com/webhook", "replyRef": "your-reference-id" } ``` - `email` is optional. Leave it out and the job goes to one of your [accounts](/docs/api-kling-v1/get-kling-accounts) that has a free job slot, picked at random. Each account runs at most its `maxJobs` jobs at once, and [GET scheduler/available](/docs/api-kling-v1/get-kling-scheduler-available) shows the free slots. If no account has a free slot, the response is `429`. Pass `email` to run the job on that account (`429` if it is busy). Uploaded files, elements, voices, avatars and earlier tasks belong to one account, so pass the `email` of the account they came from. With more than one account, reading the task with [GET tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) needs its account's `email`. The response's `task.userId` is that account's `session.userId` in [GET accounts](/docs/api-kling-v1/get-kling-accounts), and [GET scheduler](/docs/api-kling-v1/get-kling-scheduler) lists each running task with its `email`. - `prompt` is **required** (unless using multi-shot), the text description of the video to generate. Maximum length: 8000 characters for models `4.0` and `4.0 Flash`, and 2500 characters for every other model. Cannot be used together with multi-shot parameters (`shot_N_prompt`/`shot_N_duration`). - `negative_prompt` is optional, what not to include in the generated video. Models `2.5`, `2.6`, `3.0`, `4.0` and `4.0 Flash` do not support this parameter. Maximum length: 2500 characters. - `cfg_scale` is optional, guidance scale for text-to-video generation. Models `2.x`, `3.0`, `4.0` and `4.0 Flash` do not support this parameter. Range: `0` to `1`. Default: `0.5`. - `duration` is optional, length of the video in seconds. Cannot be used together with multi-shot parameters (`shot_N_prompt`/`shot_N_duration`). Supported values depend on `model_name`: | Model | Supported Durations | |-------|-------------------| | kling-v4-0 | `3` to `30`, default `5` | | kling-v4-0-flash | `3` to `20`, default `5` | | kling-v3-0, kling-v3-0-turbo | `3`, `4`, `5` (default), `6`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `15` | | kling-v2-6, v2-5, v2-1-master, v1-6, v1-5 | `5` (default), `10` | - `model_name` is optional, the AI model version to use. Supported values: `kling-v4-0`, `kling-v4-0-flash`, `kling-v3-0`, `kling-v3-0-turbo`, `kling-v2-6`, `kling-v2-5`, `kling-v2-1-master`, `kling-v1-6` (default), `kling-v1-5`. Model `3.0 Turbo` (`kling-v3-0-turbo`) is a faster 3.0 variant: `std`/`pro` modes (no `4k`), audio always on (`enable_audio` not supported), and no multi-shot. Model `4.0` (`kling-v4-0`) always generates stereo audio and takes 3 to 30 seconds. Model `4.0 Flash` (`kling-v4-0-flash`) generates 720p only (`std`), always generates audio, takes 3 to 20 seconds and does not accept multi-shot parameters. - `aspect_ratio` is optional, the video aspect ratio. Supported values: `16:9` (default), `9:16`, `1:1`, and `21:9` (models `4.0` and `4.0 Flash` only). - `mode` is optional, quality level. Models `2.1 Master` and `2.5` only support `pro` mode. Supported values: `std` (standard, default), `pro` (higher quality, slower generation), or `4k` (4K resolution, models `3.0` and `4.0`). Model `2.6` supports `std` and `pro`, but `pro` is required when `enable_audio` is `true`. Model `3.0` adds support for `4k`. Model `3.0 Turbo` supports `std` and `pro` only. Model `4.0` supports `std` (720p), `pro` (1080p) and `4k`. Kling offers 1080p and 4K to paid Kling subscribers only. Model `4.0 Flash` supports `std` (720p) only. Models `1.5` and `1.6` have no `4k`: `mode: 4k` runs as `pro` and the response lists that in `warnings`. - `hdr` is optional, generate HDR video (model `4.0` only). Supported values: `false` (default) or `true`. Needs `mode` `pro` (1080p) or `4k`, because Kling makes no HDR video at 720p. `hdr: true` with `mode` `std` (the default), or `hdr` with another model, returns [`400`](#responses). HDR adds 3 credits a second at 1080p and 5 at 4K. Kling charges subscribers nothing extra for HDR until November 30, 2026. The task's own link is a 1080p standard-range preview: download the 4K or HDR file with [GET /assets/download](/docs/api-kling-v1/get-kling-assets-download) (4K: 3840×2160 H.264; HDR: 10-bit HEVC in HLG). - `enable_audio` is optional, add sound effects (Native Audio for models `2.6` and `3.0`). Supported values: `false` or `true`. The default depends on the model: `true` on model `3.0`, `false` on every other model that accepts it. Model `2.6` with `enable_audio: true` requires `mode: pro`. Model `3.0` defaults to audio enabled; set `enable_audio: false` to disable. Models `3.0 Turbo`, `4.0` and `4.0 Flash` always generate audio and do not accept this parameter. - `multi_shot` is optional, let the model cut the video into several shots on its own (models `3.0` and `4.0`). Supported values: `false` (default) or `true`. You write one ordinary `prompt` and Kling decides where the cuts fall — use `shot_1_prompt` below instead when you want to direct each shot yourself. Ignored when `shot_1_prompt` is present — directing the shots yourself already turns multi-shot on. Model `4.0` always lets the model use several shots, so it accepts only `multi_shot: true`. Models `3.0` and `4.0` accept this parameter. Every other model, including `3.0 Turbo` and `4.0 Flash`, rejects it outright — even `multi_shot: false`. - `shot_1_prompt` through `shot_6_prompt` are optional, per-shot text prompts for multi-shot storytelling (models `3.0` and `4.0`). Maximum length: 2500 characters per shot. Minimum 2 shots required. Cannot be used together with `prompt` or `duration`. - `shot_1_duration` through `shot_6_duration` are optional, per-shot duration in seconds. Each shot must have both prompt and duration. Total duration must be 3-15 seconds. Shots must be sequential with no gaps (e.g. `shot_1` + `shot_2`, not `shot_1` + `shot_3`). - `maxJobs` is optional, range from `1` to `50`. Specifies the maximum number of concurrent jobs. - `replyUrl` is optional, a callback URL to receive generation progress and result. See [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id#model) for response model. - `replyRef` is optional, a reference identifier for the callback. ##### Responses **200** **200 OK** ```json { "task": { "id": 123456789, "userId": 12345, "type": "m2v_txt2video_hq", "scene": "NORMAL_CREATION", "status": 5, "status_name": "submitted", "status_final": false, "taskInfo": { "type": "m2v_txt2video_hq", "inputs": [], "arguments": [ { "name": "prompt", "value": "A majestic mountain landscape with snow-capped peaks and flowing rivers" }, { "name": "negative_prompt", "value": "people, buildings, text, low quality" }, { "name": "cfg", "value": "0.5" }, { "name": "duration", "value": "5" }, { "name": "kling_version", "value": "1.6" }, { "name": "aspect_ratio", "value": "16:9" } ], "extraArgs": {}, "callbackPayloads": [], "scene": "NORMAL_CREATION" }, "favored": false, "deleted": false, "viewed": false, "createTime": 1745376611075, "updateTime": 1745376611075 }, "works": [], "status": 5, "status_name": "submitted", "status_final": false, "message": "", "limitation": { "type": "m2v_txt2video_hq", "remaining": 10000, "limit": 10000 }, "userPoints": { "points": [], "total": 0 }, "userTickets": { "ticket": [] }, "editProject": null } ``` When the model cannot honor a value of the request, the job still runs the way it always has and the response adds a `warnings` array that says what was used instead, for example `"warnings": ["mode 4k is not available on kling-v1-6; it runs as pro"]`. The field is left out when there is nothing to report. **400** **400 Bad Request** The parameters are invalid. When Kling refuses the submitted parameters, `error` carries Kling's own message. ```json { "error": "Parameter prompt is required" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **403** **403 Forbidden** Your Kling account can't use the requested model yet, for example Kling 4.0 or 4.0 Flash. ```json { "error": "This Kling account does not have access to the requested model or feature (AUTH.VPrivilegeEscalation)", "message": "Service busy (AUTH.VPrivilegeEscalation)" } ``` **412** **412 Precondition Failed** The Kling account named in `error` is out of credits, and Kling did not create a task. Add credits or upgrade the plan of that account on [kling.ai](https://kling.ai), or send the job to another account with `email`. `message` keeps Kling's own text. ```json { "error": "Kling account user@example.com is out of credits: Credit are insufficient, you can upgrade your membership or purchase credit. (TASK.PointNotEnough)", "message": "积分消费失败 (TASK.PointNotEnough)" } ``` **500** **500 Internal Server Error** Kling uses a `500` response to indicate moderation and other issues with the input. It may be hard to separate actual 500 errors from moderation errors, so use the `error` field text and your best judgement to tell them apart, since the `message` field most often has very generic and perhaps misleading text. ```json { "error": "The content you uploaded appears to violate the community guidelines. (CM_EXT.POther)", "message": "Service busy (CM_EXT.POther)" } ``` When successful, the response includes a task ID which can be used to check the status using [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id). ##### Model The new task, with its `task.id` and `status_name`: poll it with [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) until `status_final` is `true`. <details markdown="block" class="model-details"> <summary>The task record, field by field</summary> ```typescript { // TypeScript, all fields are optional task: { id: number userId: number type: string scene: string status: number status_name: 'submitted' | 'failed' | 'processing' | 'succeed' status_final: boolean taskInfo: { type: string inputs: Array<{ name: string inputType: string token: string | null blobStorage: any | null url: string cover: string | null fromWorkId: number | null }> arguments: Array<{ name: string value: string }> extraArgs: Record<string, any> callbackPayloads: any[] scene: string } favored: boolean deleted: boolean viewed: boolean createTime: number updateTime: number viewTime: number } works: Array<any> status: number status_name: 'submitted' | 'failed' | 'processing' | 'succeed' status_final: boolean message: string error: string limitation: { type: string remaining: number limit: number } userPoints: { points: Array<{ orderId: string type: string amount: number balance: number startTime: number endTime: number }> total: number } userTickets: { ticket: Array<{ orderId: string type: string packageType: string amount: number balance: number startTime: number endTime: number }> } editProject: any | null warnings: string[] // only when a value of the request was run differently, e.g. mode 4k as pro } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/kling/videos/text2video" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "email": "user@example.com", "prompt": "A majestic mountain landscape with snow-capped peaks and flowing rivers", "negative_prompt": "people, buildings, text, low quality", "model_name": "kling-v1-6", "aspect_ratio": "16:9", "mode": "pro" }' ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const apiUrl = "https://api.useapi.net/v1/kling/videos/text2video"; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ email: email, prompt: "A majestic mountain landscape with snow-capped peaks and flowing rivers", negative_prompt: "people, buildings, text, low quality", model_name: "kling-v1-6", aspect_ratio: "16:9", mode: "pro" }) }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured account email" apiUrl = "https://api.useapi.net/v1/kling/videos/text2video" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } data = { "email": email, "prompt": "A majestic mountain landscape with snow-capped peaks and flowing rivers", "negative_prompt": "people, buildings, text, low quality", "model_name": "kling-v1-6", "aspect_ratio": "16:9", "mode": "pro" } response = requests.post(apiUrl, headers=headers, json=data) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-kling-v1/post-kling-videos-voices === Document URL: https://useapi.net/docs/api-kling-v1/post-kling-videos-voices --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/voices description: "Save your own Kling 4.0 voice from a 4.5–30 second audio clip via POST videos/voices in the useapi.net Kling API v1, then use it as voice_1 in Omni v4 videos." parent: Kling API nav_order: 328 --- ## Save a Kling 4.0 Voice October 15, 2026 (November 16, 2026) --- This endpoint saves your own Kling 4.0 voice from an audio clip. Kling cleans up the clip and saves it to your Kling account as a voice with `source: USER`. Use the returned `id` (or the `name`) as `voice_1`, `voice_2` or `voice_3` in [POST /videos/omni](/docs/api-kling-v1/post-kling-videos-omni#voices-v4-only) with `omni_version: v4`. A saved voice belongs to the Kling account that saved it, so pass the same `email` to [POST /videos/omni](/docs/api-kling-v1/post-kling-videos-omni). Saved voices are listed first by [GET /videos/voices](/docs/api-kling-v1/get-kling-videos-voices), and you can remove one with [DELETE /videos/voices](/docs/api-kling-v1/del-kling-videos-voices). > **https://api.useapi.net/v1/kling/videos/voices** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "email": "user@example.com", "audioUrl": "https://example.com/my-voice.mp3", "name": "My voice" } ``` - `email` is optional when only one [account](/docs/api-kling-v1/get-kling-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `audioUrl` is **required**, a URL of an audio file 4.5 to 30 seconds long. Supported formats: `mp3`, `wav`, `m4a`, `flac`, `aac`, `ogg`. - `name` is **required**, the voice name. Maximum length: 30 characters. ##### Responses **200** **200 OK** ```json { "email": "user@example.com", "id": "301234567890", "name": "My voice", "source": "USER", "audioUrl": "https://v15-kling.klingai.com/.../voice.quality.wav", "coverUrl": "https://s15-kling.klingai.com/kimg/.../cover.png", "duration": 8300 } ``` **400** **400 Bad Request** The clip is shorter than 4.5 seconds or longer than 30 seconds, `audioUrl` can't be fetched, or it is not an audio file. ```json { "error": "audioUrl duration 2.8s must be between 4.5 and 30 seconds" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model The saved voice with its `id`, name, account `email` and cleaned-up sample in `audioUrl`. <details markdown="block" class="model-details"> <summary>The saved voice, field by field</summary> ```typescript { // TypeScript, all fields are optional email: string // Kling account the voice was saved to id: string // Use as voice_1 … voice_3 in POST /videos/omni (or use name) name: string source: 'USER' // Your saved voice audioUrl: string // The cleaned-up voice sample (.wav) coverUrl: string // Cover image duration: number // Voice length in milliseconds } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/kling/videos/voices" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "email": "user@example.com", "audioUrl": "https://example.com/my-voice.mp3", "name": "My voice" }' ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const apiUrl = "https://api.useapi.net/v1/kling/videos/voices"; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ email: email, audioUrl: "https://example.com/my-voice.mp3", name: "My voice" }) }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured account email" apiUrl = "https://api.useapi.net/v1/kling/videos/voices" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } data = { "email": email, "audioUrl": "https://example.com/my-voice.mp3", "name": "My voice" } response = requests.post(apiUrl, headers=headers, json=data) print(response, response.json()) ``` === URL: https://useapi.net/docs/start-here/setup-minimax === Document URL: https://useapi.net/docs/start-here/setup-minimax --- layout: default title: Setup MiniMax description: "How to set up MiniMax (Hailuo) for the useapi.net API — connect your account and start generating via the API." parent: Start Here nav_order: 255 --- # <img style="height:1.5em;vertical-align: middle;" src="/assets/images/minimax.png" alt=""> Setup MiniMax | Hailuo AI September 25, 2024 (November 24, 2025) ## Table of contents Approximately 5 minutes to complete setup steps. --- > This is the setup guide for [MiniMax API](/docs/api-minimax-v1). A [Hailuo AI](https://hailuoai.video) account and a [useapi.net subscription](/docs/subscription) are required for the API to work. ### Connect your account (recommended) Link your Hailuo account right in your own browser — a quick copy-and-paste, with no software to install and no remote setup. It runs entirely on your own machine and never touches your Google login. [Open the connect page](/assets/setup-browser/minimax.html) Prefer to do it by hand? Continue with the manual steps below. --- ## Setup <b>hailuoai.video</b> account You need a [hailuoai.video](https://hailuoai.video) account to to use MiniMax API. Sign-in with your Google account at [hailuoai.video](https://hailuoai.video). You can create as many accounts as you need. Our API uses automated load balancing and will select an account with available capacity. ### Step 1 • Navigate to hailuoai.video Open Chromium-compatible browser (e.g. [Google Chrome](https://www.google.com/chrome/), [Microsoft Edge](https://www.microsoft.com/en-us/edge) or [Opera](https://www.opera.com/)) and navigate to [https://hailuoai.video](https://hailuoai.video). Once the page is fully loaded, ensure that you're logged in with your Google account <span style="color: red;">`1`</span>. Open [Developer Tools](https://developer.chrome.com/docs/devtools) by right-clicking on the page and selecting "Inspect Element" <span style="color: red;">`2`</span>. Finally refresh page <span style="color: red;">`3`</span>. ![](/assets/images/minimax_video_setup_1.png) ### Step 2 • Locate `url` Select Developer Tools » Network <span style="color: red;">`1`</span>: * On the left side many click on `Assets` submenu <span style="color: red;">`2`</span>. * Type `/cursor` in the filter box <span style="color: red;">`3`</span> and hit Enter. * Make sure that `All` or `Fetch/XHR` is selected <span style="color: red;">`4`</span>. * You should see a http call(s) entry as shown below <span style="color: red;">`5`</span>, click on that entry. * Select "Headers" tab <span style="color: red;">`6`</span>. * Locate General » Request URL <span style="color: red;">`7`</span> as shown below and copy its value. This is your `url`. [EXPAND](/assets/images/minimax_video_setup_2.png){:target="_blank"} ![](/assets/images/minimax_video_setup_2.png) As an example below the `url` is ``` https://hailuoai.video/v3/api/multimodal/video/my/cursor?type=next¤tID=0&limit=30&scene=mine&filterType=2&device_platform=web&app_id=3001&version_code=22202&biz_id=0&lang=en&uuid=8a2d8b5d-ac0d-4bb5-8028-3177fa64f861&device_id=301350748241866752&os_name=Windows&browser_name=opera&device_memory=8&cpu_core_num=12&browser_language=en-US&browser_platform=Win32&screen_width=1920&screen_height=1080&unix=1728704107000 ``` ### Step 3 • Locate `token` value Locate Request Headers » Token <span style="color: red;">`7`</span> as shown below and copy it's value. This is your `token`. [EXPAND](/assets/images/minimax_video_setup_3.png){:target="_blank"} ![](/assets/images/minimax_video_setup_3.png) As an example below the `token` is ``` eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MzIxNTk4MjksInVzZXIiOnsiaWQiOiIzMDEzNDg0MDk1ODE4MzgzMzYiLCJuYW1lIjoidXNlIGFwaSIsImF2YXRhciI6Imh0dHBzOi8vbGgzLmdvb2dsZXVzZXJjb250ZW50LmNvbS9hL0FDZzhvY0lLNEJaMmpfSlIxcTh3TkFKU2RlZzlwVHZlTDJTSVhFRjg4TkU4MV85VlowbFBRQT1zOTYtYyIsImRldmljZUlEIjoiIn19.1-zGnbUfENnVdjDGDBuaZ4Sf7rTelfqUKk5XNj7liE4 ``` If you are curious, you can use [jwt.io](https://jwt.io) to decode the token and see its content. ## Verify and add account Use the form below to verify your credentials and add your MiniMax account. Select **Add Account** to complete setup, or **Verify** to test your credentials first. You should receive response `200` if successful. You can also use [POST /accounts](/docs/api-minimax-v1/post-minimax-accounts-account) directly. <script> async function apiTestAccountMiniMax(addAccount) { data = { method: 'POST', headers: { 'Authorization': `Bearer ${document.getElementById('post-accounts-MiniMax-api_token').value}`, 'Content-Type': 'application/json' } }; let url = document.getElementById(`post-accounts-MiniMax-url`)?.value; let token = document.getElementById(`post-accounts-MiniMax-token`)?.value; url = url && url.length ? url : undefined; token = token && token.length ? token : undefined; const body = { token, url, maxJobs: 3 }; if (!addAccount) body.dryRun = true; data.body = JSON.stringify(body); await apiExecute(`https://api.useapi.net/v1/minimax/accounts`, 'post-accounts-MiniMax', data); } </script> <form id="post-accounts-MiniMax" onsubmit="apiTestAccountMiniMax(document.getElementById('post-accounts-MiniMax-action').value === 'add'); return false;" class="input-form"> <div class="input-field"> <div class="input-field-row"> <label for="post-accounts-MiniMax-api_token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="post-accounts-MiniMax-api_token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> <label for="post-accounts-MiniMax-url"><span>url </span> <input id="post-accounts-MiniMax-url" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> <label for="post-accounts-MiniMax-token"><span>token</span> <input id="post-accounts-MiniMax-token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> <label for="post-accounts-MiniMax-action"><span>action</span> <select id="post-accounts-MiniMax-action" class="input-element"> <option value="verify">Verify — test credentials only</option> <option value="add">Add Account — required to complete setup</option> </select> </label> </div> <button id="post-accounts-MiniMax-button" class="btn btn-primary fs-3" type="submit">Go</button> </div> </form> <div id="post-accounts-MiniMax-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-minimax-v1 === Document URL: https://useapi.net/docs/api-minimax-v1 --- layout: default title: MiniMax API nav_logo: /assets/images/minimax.png nav_title: MiniMax API seo_title: "Hailuo API (MiniMax): Hailuo 3.0 Video, Speech and Music" description: "Generate Hailuo 3.0 video, Speech-2.8 text-to-speech and Music-3.0 songs with a Hailuo AI website subscription through the third-party useapi.net REST API." nav_order: 3000 has_children: true permalink: /docs/api-minimax-v1 repo: https://github.com/useapi/minimax-api --- # <img style="height:1.5em;vertical-align: middle;" src="/assets/images/minimax.png" alt=""> MiniMax API September 25, 2024 (November 20, 2026) This is a [third-party](/docs/legal#affiliation--third-party-services) API for [Hailuo AI](https://hailuoai.video) by [MiniMax](https://minimaxi.com). It uses your [Hailuo AI subscription](https://hailuoai.video/subscribe): Free, Standard $10.50, Pro $38, Master $89 or Max $216 a month (as of October 2026). It makes [video with Hailuo 3.0, Veo 3.1 and Seedance 2.0, and images with MiniMax H3 Image, Midjourney V7, Nano Banana Pro and GPT Image 2](#models), through a REST API and a hosted MCP server. On Max, a 5-second 768p Hailuo 3.0 video uses $0.28 of the plan's monthly credits, against $0.40 a video on MiniMax's own API. Songs with Music 3.0 and speech with Speech 2.8 use a separate [MiniMax Audio subscription](https://www.minimax.io/audio/subscribe): Free, Starter $5, Creator $15, Standard $30 or Pro $99 a month. MiniMax's own [developer platform](https://platform.minimax.io/docs/pricing/overview) sells none of the Veo, Seedance, Midjourney, Nano Banana, GPT Image or Seedream models, and its music API has been closed to new users since August 20, 2026. ## Models | Model | What it makes | Notes | |---|---|---| | [Hailuo 3.0](https://hailuoai.video) (MiniMax H3)<br>`Hailuo-3.0` | [Video](/docs/api-minimax-v1/post-minimax-videos-create) from text, a start and an end frame, or up to 9 reference images, 3 videos and 3 audio clips | 4 to 15 seconds at 768p or 2K, sound on every video, aspect ratios from 21:9 to 9:16 | | [Hailuo 2.3](https://hailuoai.video/ai-video-landing/ai-video-generator-hailuo-2-3) and 2.3 Fast<br>`T2V-2.3`, `I2V-2.3`, `I2V-2.3-Fast` | Video from text or an image | 768p for 6 or 10 seconds, 1080p for 6 | | [Hailuo 02](https://www.minimax.io/news/minimax-hailuo-02)<br>`02` | Video from text or an image, with an end frame | 512p or 768p for 6 or 10 seconds, 1080p for 6 | | Hailuo 01<br>`T2V-01`, `I2V-01`, `I2V-01-live`, `I2V-01-Director`, `T2V-01-Director`, `S2V-01` | Video from text, an image or a [saved character](/docs/api-minimax-v1/get-minimax-videos-characters) | 720p, 6 seconds, live-photo effect, Director models follow camera moves | | [Seedance 2.0](https://seed.bytedance.com/), 2.0 Fast and 2.0 Mini<br>`Seedance-2.0`, `Seedance-2.0-Fast`, `Seedance-2.0-Mini` | Video from text, a start and an end frame, or up to 9 reference images, 3 videos and 3 audio clips | 4 to 15 seconds at 480p or 720p, plus 1080p and 4K on 2.0, aspect ratios from 21:9 to 9:16 | | [Veo 3.1](https://deepmind.google/models/veo/) and 3.1 Fast<br>`Veo-3.1`, `Veo-3.1-Fast`, `Veo-3.1-S2V`, `Veo-3.1-S2V-Fast` | Video from text or an image with an end frame, or from up to 14 subject reference images | 8 seconds at 720p, 1080p or 4K with sound, 16:9 or 9:16 | | [MiniMax H3 Image](https://hailuoai.video/create/image-generation) and H3 Image Highspeed<br>`h3-image`, `h3-image-highspeed` | [Images](/docs/api-minimax-v1/post-minimax-images-create) from text and up to 16 reference images, with `@Image1` mentions in the prompt | MiniMax's own image model, 1K, 2K or 4K, Highspeed renders the same quality faster | | [Midjourney V7 and Niji 7](https://www.midjourney.com/)<br>`midjourney-v7`, `midjourney-niji7` | Images from text and up to 14 reference images | 4 images per request | | [Nano Banana Pro](https://blog.google/technology/ai/nano-banana-pro/) and Nano Banana 2<br>`nano-banana-pro`, `nano-banana-2` | Images from text and up to 14 reference images | Up to 4K, 1 to 4 per request, with less content moderation than Google Flow, so photos of minors or famous people can be edited | | [GPT Image 2 and 1.5](https://openai.com/index/introducing-4o-image-generation/)<br>`gpt-image-2`, `gpt-image-1.5` | Images from text and reference images | GPT Image 2 up to 4K with 16 references, 1.5 with 3, low, medium or high quality | | [Seedream 5.0 and 4.5](https://seed.bytedance.com/en/seedream4_5)<br>`seedream-5.0`, `seedream-4.5` | Images from text and up to 14 reference images | 5.0 at 2K or 3K, 4.5 at 2K or 4K | | image-01<br>`image-01` | Images from text and a character reference | MiniMax's own image model, HD | | [Music 3.0](https://www.minimax.io/audio/music) and 2.6<br>`music-3.0`, `music-2.6` | [Songs](/docs/api-minimax-v1/post-minimax-music-create) with vocals or instrumental, from your lyrics or lyrics the model writes, and [covers](/docs/api-minimax-v1/post-minimax-music-reference) of a track you upload that keep its melody and structure | 1 to 3 songs per request, 256 kbps stereo MP3, streamed while it renders | | [Speech 2.8](https://www.minimax.io/audio/text-to-speech), 2.6, 2.5, 02 and 01, each HD and Turbo<br>`speech-2.8-hd`, `speech-2.8-turbo` | [Text-to-speech](/docs/api-minimax-v1/post-minimax-speech-create) in [more than 600 voices](/docs/api-minimax-v1/get-minimax-speech-voices) across 40 languages, and [voice cloning](/docs/api-minimax-v1/post-minimax-speech-clone-voice) from a sample | Emotion, breath and pause markup, word timings for captions, streamed over a [WebSocket](/docs/api-minimax-v1/wss-minimax-speech-wss) or [one call for an MP3](/docs/api-minimax-v1/post-minimax-speech-create-mp3) | | More | [Uploads](/docs/api-minimax-v1/post-minimax-files) up to 5 GB as references, [cancel a video](/docs/api-minimax-v1/post-minimax-videos-cancel), and [GET features](/docs/api-minimax-v1/get-minimax-features) for credits left and each model's cost | | Sora 2 is no longer available: OpenAI shut it down on September 24, 2026. ## Agent The [MiniMax Agent API](/docs/api-minimax-v1/post-minimax-agent) takes one prompt and picks from the models you allow: video with Hailuo 2.3, 02 and Veo 3.1, images with Midjourney V7 and Niji 7, Nano Banana 2 and Pro, Seedream 4.5 and 5.0, [Kontext](https://bfl.ai/models/flux-kontext), [Qwen](https://github.com/QwenLM/Qwen-Image) and Kolors, and audio with [Speech 2.5](https://minimax-ai.chat/models/minimax-speech-25/) and [Music 2.0](https://www.minimax.io/news/minimax-music-20). It runs in sync or async mode, and [GET agent/`jobId`](/docs/api-minimax-v1/get-minimax-agent-jobId) returns the result. [Agent video templates](/docs/api-minimax-v1/post-minimax-videos-agent-create) turn a few inputs into a finished video from a [template](/docs/api-minimax-v1/get-minimax-videos-agent-templates), with live progress while it renders. ## MCP server The hosted [MiniMax MCP server](/docs/api-minimax-v1/mcp) gives the Claude app, ChatGPT, Claude Code, Cursor, VS Code and other AI assistants 38 tools for Hailuo, Veo and Seedance videos, template videos, images, the MiniMax agent, songs and covers, speech, voice cloning, uploads and running jobs, with your useapi.net API token and nothing to install. It is listed in the official MCP Registry as `net.useapi/minimax`. The [minimax-api](https://github.com/useapi/minimax-api) repo also adds it in one step as a [Claude Code plugin](https://github.com/useapi/minimax-api#use-with-claude-code) or a [Gemini CLI extension](https://github.com/useapi/minimax-api#use-with-gemini-cli). ## Pricing What one video, image, song or speech clip costs on MiniMax's [developer platform](https://platform.minimax.io/docs/pricing/overview) and on each subscription (as of October 2026). Each subscription comes with a monthly number of credits, and each video or image uses a set number of them, so each one costs its share of the subscription. Video and images use your Hailuo AI subscription: | Model | [Official API](https://platform.minimax.io/docs/pricing/overview) | Max $216/m (27,000 cr/mo) | Master $89/m (10,500 cr/mo) | Pro $38/m (4,500 cr/mo) | Standard $10.50/m (1,000 cr/mo) | |---|---|---|---|---|---| | Hailuo 3.0 (768p, 5 s) | $0.40 ($0.08 a second) | $0.28 / 35 cr (771 videos/mo) | $0.30 / 35 cr (300 videos/mo) | $0.30 / 35 cr (128 videos/mo) | $0.37 / 35 cr (28 videos/mo) | | Hailuo 3.0 (2K, 5 s) | $0.65 ($0.13 a second) | $0.48 / 60 cr (450 videos/mo) | $0.51 / 60 cr (175 videos/mo) | $0.51 / 60 cr (75 videos/mo) | $0.63 / 60 cr (16 videos/mo) | | Hailuo 2.3 (768p, 6 s) | $0.28 (a video) | unlimited (Hailuo's listing) | $0.21 / 25 cr (420 videos/mo) | $0.21 / 25 cr (180 videos/mo) | $0.26 / 25 cr (40 videos/mo) | | Hailuo 2.3 Fast (768p, 6 s) | $0.19 (a video) | unlimited (Hailuo's listing) | $0.13 / 15 cr (700 videos/mo) | $0.13 / 15 cr (300 videos/mo) | $0.16 / 15 cr (66 videos/mo) | | Hailuo 02 (768p, 6 s) | $0.28 (a video) | unlimited (Hailuo's listing) | $0.21 / 25 cr (420 videos/mo) | $0.21 / 25 cr (180 videos/mo) | $0.26 / 25 cr (40 videos/mo) | | Hailuo 01 (720p, 6 s) | not sold | unlimited (Hailuo's listing) | $0.21 / 25 cr (420 videos/mo) | $0.21 / 25 cr (180 videos/mo) | $0.26 / 25 cr (40 videos/mo) | | Seedance 2.0 (1080p, 5 s) | not sold | $2.00 / 250 cr (108 videos/mo) | $2.12 / 250 cr (42 videos/mo) | $2.11 / 250 cr (18 videos/mo) | $2.63 / 250 cr (4 videos/mo) | | Seedance 2.0 Fast (720p, 5 s) | not sold | $0.68 / 85 cr (317 videos/mo) | $0.72 / 85 cr (123 videos/mo) | $0.72 / 85 cr (52 videos/mo) | $0.89 / 85 cr (11 videos/mo) | | Seedance 2.0 Mini (720p, 5 s) | not sold | $0.44 / 55 cr (490 videos/mo) | $0.47 / 55 cr (190 videos/mo) | $0.46 / 55 cr (81 videos/mo) | $0.58 / 55 cr (18 videos/mo) | | Veo 3.1 (720p, 8 s) | not sold | $0.96 / 120 cr (225 videos/mo) | $1.02 / 120 cr (87 videos/mo) | $1.01 / 120 cr (37 videos/mo) | $1.26 / 120 cr (8 videos/mo) | | Veo 3.1 Fast (720p, 8 s) | not sold | $0.48 / 60 cr (450 videos/mo) | $0.51 / 60 cr (175 videos/mo) | $0.51 / 60 cr (75 videos/mo) | $0.63 / 60 cr (16 videos/mo) | | MiniMax H3 Image (4K) | $0.069 (an image) | $0.048 / 6 cr (4,500 images/mo) | $0.051 / 6 cr (1,750 images/mo) | $0.051 / 6 cr (750 images/mo) | $0.063 / 6 cr (166 images/mo) | | H3 Image Highspeed (4K) | $0.130 (an image) | $0.096 / 12 cr (2,250 images/mo) | $0.102 / 12 cr (875 images/mo) | $0.101 / 12 cr (375 images/mo) | $0.126 / 12 cr (83 images/mo) | | Nano Banana Pro (2K) | not sold | $0.05 / 6 cr (4,500 images/mo) | $0.05 / 6 cr (1,750 images/mo) | $0.05 / 6 cr (750 images/mo) | $0.06 / 6 cr (166 images/mo) | | Nano Banana 2 (1K) | not sold | $0.03 / 4 cr (6,750 images/mo) | $0.03 / 4 cr (2,625 images/mo) | $0.03 / 4 cr (1,125 images/mo) | $0.04 / 4 cr (250 images/mo) | | GPT Image 2 (medium, 1K) | not sold | $0.06 / 8 cr (3,375 images/mo) | $0.07 / 8 cr (1,312 images/mo) | $0.07 / 8 cr (562 images/mo) | $0.08 / 8 cr (125 images/mo) | | GPT Image 1.5 (medium) | not sold | $0.06 / 8 cr (3,375 images/mo) | $0.07 / 8 cr (1,312 images/mo) | $0.07 / 8 cr (562 images/mo) | $0.08 / 8 cr (125 images/mo) | | Midjourney V7 | not sold | $0.02 / 3 cr (9,000 images/mo) | $0.03 / 3 cr (3,500 images/mo) | $0.03 / 3 cr (1,500 images/mo) | $0.03 / 3 cr (333 images/mo) | | Midjourney Niji 7 | not sold | $0.02 / 3 cr (9,000 images/mo) | $0.03 / 3 cr (3,500 images/mo) | $0.03 / 3 cr (1,500 images/mo) | $0.03 / 3 cr (333 images/mo) | | Seedream 5.0 | not sold | $0.03 / 4 cr (6,750 images/mo) | $0.03 / 4 cr (2,625 images/mo) | $0.03 / 4 cr (1,125 images/mo) | $0.04 / 4 cr (250 images/mo) | | Seedream 4.5 | not sold | $0.03 / 4 cr (6,750 images/mo) | $0.03 / 4 cr (2,625 images/mo) | $0.03 / 4 cr (1,125 images/mo) | $0.04 / 4 cr (250 images/mo) | Songs and speech use your MiniMax Audio subscription, a separate credit balance, so a video plan doesn't pay for songs and an audio plan doesn't pay for video: | Model | [Official API](https://platform.minimax.io/docs/pricing/overview) | Pro $99/m (3M cr/mo) | Standard $30/m (750K cr/mo) | Creator $15/m (330K cr/mo) | Starter $5/m (100K cr/mo) | |---|---|---|---|---|---| | Music 3.0 (a song) | closed to new users ($0.15 a song for existing users) | $0.010 / 300 cr (10,000 songs/mo) | $0.012 / 300 cr (2,500 songs/mo) | $0.014 / 300 cr (1,100 songs/mo) | $0.015 / 300 cr (333 songs/mo) | | Music 2.6 (a song) | closed to new users ($0.15 a song for existing users) | $0.010 / 300 cr (10,000 songs/mo) | $0.012 / 300 cr (2,500 songs/mo) | $0.014 / 300 cr (1,100 songs/mo) | $0.015 / 300 cr (333 songs/mo) | | Speech 2.8 HD (1,000 characters) | $0.10 ($100 a million) | $0.033 / 1,000 cr (3M characters/mo) | $0.04 / 1,000 cr (750K characters/mo) | $0.045 / 1,000 cr (330K characters/mo) | $0.05 / 1,000 cr (100K characters/mo) | | Speech 2.8 Turbo (1,000 characters) | $0.06 ($60 a million) | $0.020 / 600 cr (5M characters/mo) | $0.024 / 600 cr (1.25M characters/mo) | $0.027 / 600 cr (550K characters/mo) | $0.03 / 600 cr (166K characters/mo) | | Voice cloning | $1.50 (a voice) | $0 / 0 cr (250 voice slots) | $0 / 0 cr (50 voice slots) | $0 / 0 cr (30 voice slots) | $0 / 0 cr (10 voice slots) | - A free Hailuo AI account gets one-time trial credits for Hailuo models only. A free MiniMax Audio account gets 10,000 credits a month, about 33 songs, and 3 voice slots. - Billed yearly, Hailuo AI costs $8.40, $30.40, $71.20 or $184 a month and MiniMax Audio $4.50, $13, $25 or $80 a month, for the same monthly credits. - On Max, Hailuo lists Hailuo 2.3, 02 and 01 videos as unlimited. Its yearly Pro, Master and Max plans also list unlimited Nano Banana Pro, Nano Banana 2, Seedream and GPT Image 1.5 images, at a top resolution that depends on the plan. - Standard runs Hailuo 2.3 and 02 at 6 seconds and Veo 3.1 at 720p. Pro and up add 10-second Hailuo videos and 1080p Veo 3.1, priced in the calculator below. - A song costs 300 credits whatever the model, its length or vocals, while MiniMax's pay-as-you-go API added $0.01 when the model wrote the lyrics. Uploading a track to [cover](/docs/api-minimax-v1/post-minimax-music-reference) costs no credits. - Speech 2.6, 2.5, 02 and 01 cost the same as 2.8 in each variant. Emotion tags are free, and sound and pause markup is billed as ordinary text. - A cloned voice takes a voice slot, which [POST speech/delete-voice](/docs/api-minimax-v1/post-minimax-speech-delete-voice) frees and [GET speech/equity](/docs/api-minimax-v1/get-minimax-speech-equity) counts. <details markdown="block" class="calc-details"> <summary>Cost calculator for every video and image model</summary> Actual costs may change, see [hailuoai.video](https://hailuoai.video/subscribe) for current pricing. The "$ at Master" column prices each video or image on the [$89/m Master](https://hailuoai.video/subscribe) plan ($0.00848/credit). Max has the lowest monthly cost per credit at $0.00800, and yearly billing takes 20% off Standard, Pro and Master and about 15% off Max. Paid plans apply Seedance 2.0 at half credits, already reflected below. Seedance 2.0 and Hailuo 3.0 bill per second, and a video reference is charged on its own length on top of the generated video, at the same rate on Hailuo 3.0 and a lower one on Seedance 2.0. Image and audio references carry no per-second charge. The calculator below takes a video reference length so you can see the full cost. | Plan | Monthly | Credits/mo | $/credit | |:-----|:-----:|:-----:|:-----:| | Standard | $10.50 | 1,000 | $0.01050 | | Pro | $38 | 4,500 | $0.00844 | | Master | $89 | 10,500 | $0.00848 | | Max | $216 | 27,000 | $0.00800 | Billed yearly instead, for the same monthly credits: | Plan | Yearly | Per month | $/credit | |:-----|:-----:|:-----:|:-----:| | Standard | $100.80 | $8.40 | $0.00840 | | Pro | $364.80 | $30.40 | $0.00676 | | Master | $854.40 | $71.20 | $0.00678 | | Max | $2,208 | $184 | $0.00681 | Images, priced per image, see [images/create](/docs/api-minimax-v1/post-minimax-images-create) for details: | Model | Credits | $ at Master | |:------|:-------:|:-----------:| | image-01 | 1 | $0.008 | | h3-image (1K/2K / 4K) | 3 / 6 | $0.020 / $0.041 | | h3-image-highspeed (1K/2K / 4K) | 5 / 12 | $0.034 / $0.081 | | midjourney-v7, midjourney-niji7 | 3 | $0.025 | | seedream-4.5, seedream-5.0 | 4 | $0.034 | | nano-banana-2 (512P/1K) | 4 | $0.034 | | nano-banana-2 (2K) | 5 | $0.042 | | nano-banana-2 (4K) | 8 | $0.068 | | nano-banana-pro (1K/2K) | 6 | $0.051 | | nano-banana-pro (4K) | 10 | $0.085 | | gpt-image-1.5 (Low/Medium/High) | 4 / 8 / 15 | $0.034 / $0.068 / $0.127 | | gpt-image-2 quality `low` (1K/2K/4K) | 2 / 5 / 10 | $0.017 / $0.042 / $0.085 | | gpt-image-2 quality `medium` (1K/2K/4K) | 8 / 20 / 40 | $0.068 / $0.170 / $0.339 | | gpt-image-2 quality `high` (1K/2K/4K) | 30 / 80 / 160 | $0.254 / $0.678 / $1.356 | Videos, see [videos/create](/docs/api-minimax-v1/post-minimax-videos-create) for details. Billed per second, so multiply by your `duration` (4–15). A video reference is charged on its own length as well, at the rate in the "Video ref/sec" column. | Model | Resolution | Credits/sec | Video ref/sec | $ at Master, per sec | |:------|:-----------|:-----------:|:-------------:|:--------------------:| | Hailuo-3.0 | 768p | 7 | 7 | $0.059 | | Hailuo-3.0 | 2K | 12 | 12 | $0.102 | | Seedance-2.0 | 480p | 10 | 6 | $0.085 | | Seedance-2.0 | 720p | 21 | 14 | $0.178 | | Seedance-2.0 | 1080p | 50 | 30 | $0.424 | | Seedance-2.0 | 4K | 100 | 60 | $0.848 | | Seedance-2.0-Fast | 480p | 8 | 4 | $0.068 | | Seedance-2.0-Fast | 720p | 17 | 11 | $0.144 | | Seedance-2.0-Mini | 480p | 5 | 3 | $0.042 | | Seedance-2.0-Mini | 720p | 11 | 7 | $0.093 | Billed per video, at a fixed price per option. | Model | Option | Credits | $ at Master | |:------|:-------|:-------:|:-----------:| | Hailuo 01 (all models) | — | 25 | $0.212 | | Hailuo 02, T2V-2.3, I2V-2.3 | 768p / 1080p | 25–80 | $0.212–$0.678 | | I2V-2.3-Fast | 768p / 1080p | 15–50 | $0.127–$0.424 | | Veo-3.1, Veo-3.1-S2V | 720p / 1080p / 4K | 120 / 120 / 180 | $1.017 / $1.017 / $1.526 | | Veo-3.1-Fast, Veo-3.1-S2V-Fast | 720p / 1080p / 4K | 60 / 60 / 90 | $0.509 / $0.509 / $0.763 | Pick a plan and a model for the cost of one video or image: <div class="calc" markdown="0"> <div class="calc-head"><label for="mmPlan" class="calc-label">Hailuo AI subscription</label><span class="calc-sep" aria-hidden="true">·</span><a class="calc-link" href="https://hailuoai.video/subscribe">current prices and offers</a></div> <select id="mmPlan" class="calc-select"> <optgroup label="Monthly"> <option value="0.0105000">Standard · $10.50/mo · 1,000 credits · $0.0105/credit</option> <option value="0.0084444">Pro · $38/mo · 4,500 credits · $0.0084/credit</option> <option value="0.0084762" selected>Master · $89/mo · 10,500 credits · $0.0085/credit</option> <option value="0.0080000">Max · $216/mo · 27,000 credits · $0.0080/credit</option> </optgroup> <optgroup label="Yearly, price per month"> <option value="0.0067556">Pro yearly · $30.40/mo · 4,500 credits · $0.0068/credit</option> <option value="0.0067810">Master yearly · $71.20/mo · 10,500 credits · $0.0068/credit</option> </optgroup> </select> <div class="calc-fields"> <div><label class="calc-label" for="mmKind">Type</label><select id="mmKind" class="calc-select"><option value="video">Video</option><option value="image">Image</option></select></div> <div><label class="calc-label" for="mmModel">Model</label><select id="mmModel" class="calc-select"></select></div> <div id="mmOptR"><label class="calc-label" for="mmOpt">Option</label><select id="mmOpt" class="calc-select"></select></div> <div id="mmDurR"><label class="calc-label" for="mmDur">Duration (s)</label><select id="mmDur" class="calc-select"></select></div> <div id="mmVrefR"><label class="calc-label" for="mmVref">Video ref (s)</label><select id="mmVref" class="calc-select"></select></div> </div> <table class="calc-plan calc-result"> <thead><tr><th>Cost on the selected subscription</th></tr></thead> <tbody><tr><td id="mmOut">—</td></tr></tbody> </table> </div> <script> (function(){ var M={ video:{ 'Hailuo-3.0':{sd:{'768p':[7,7],'2K (1440)':[12,12]}}, '02':{opt:{'512p · 6s':12,'512p · 10s':25,'768p · 6s':25,'768p · 10s':50,'1080p · 6s':80}}, 'T2V-2.3':{opt:{'768p · 6s':25,'768p · 10s':50,'1080p · 6s':80}}, 'I2V-2.3':{opt:{'768p · 6s':25,'768p · 10s':50,'1080p · 6s':80}}, 'I2V-2.3-Fast':{opt:{'768p · 6s':15,'768p · 10s':30,'1080p · 6s':50}}, 'T2V-01':{flat:25},'I2V-01':{flat:25},'I2V-01-live':{flat:25},'I2V-01-Director':{flat:25},'T2V-01-Director':{flat:25},'S2V-01':{flat:25}, 'Seedance-2.0':{sd:{'480p':[10,6],'720p':[21,14],'1080p':[50,30],'4K':[100,60]}}, 'Seedance-2.0-Fast':{sd:{'480p':[8,4],'720p':[17,11]}}, 'Seedance-2.0-Mini':{sd:{'480p':[5,3],'720p':[11,7]}}, 'Veo-3.1':{opt:{'720p · 8s':120,'1080p · 8s':120,'4K · 8s':180}}, 'Veo-3.1-Fast':{opt:{'720p · 8s':60,'1080p · 8s':60,'4K · 8s':90}}, 'Veo-3.1-S2V':{opt:{'720p · 8s':120,'1080p · 8s':120,'4K · 8s':180}}, 'Veo-3.1-S2V-Fast':{opt:{'720p · 8s':60,'1080p · 8s':60,'4K · 8s':90}} }, image:{ 'image-01':{flat:1},'h3-image':{opt:{'1K/2K':3,'4K':6}},'h3-image-highspeed':{opt:{'1K/2K':5,'4K':12}},'midjourney-v7':{flat:3},'midjourney-niji7':{flat:3},'seedream-4.5':{flat:4},'seedream-5.0':{flat:4}, 'nano-banana-2':{opt:{'512P/1K':4,'2K':5,'4K':8}}, 'nano-banana-pro':{opt:{'1K/2K':6,'4K':10}}, 'gpt-image-1.5':{opt:{'Low':4,'Medium':8,'High':15}}, 'gpt-image-2':{opt:{'low · 1K':2,'low · 2K':5,'low · 4K':10,'medium · 1K':8,'medium · 2K':20,'medium · 4K':40,'high · 1K':30,'high · 2K':80,'high · 4K':160}} } }; function g(id){return document.getElementById(id);} var plan=g('mmPlan'),kind=g('mmKind'),model=g('mmModel'),optR=g('mmOptR'),opt=g('mmOpt'),durR=g('mmDurR'),dur=g('mmDur'),vrefR=g('mmVrefR'),vref=g('mmVref'),out=g('mmOut'); function fill(sel,arr){sel.innerHTML='';for(var i=0;i<arr.length;i++){var o=document.createElement('option');o.value=arr[i];o.textContent=arr[i];sel.appendChild(o);}} function models(){fill(model,Object.keys(M[kind.value]));inputs();} function inputs(){ var m=M[kind.value][model.value]||{}; if(m.sd){optR.style.display='';durR.style.display='';vrefR.style.display='';fill(opt,Object.keys(m.sd));var d=[];for(var i=4;i<=15;i++)d.push(String(i));fill(dur,d);dur.value='5';var v=[];for(var j=0;j<=15;j++)v.push(String(j));fill(vref,v);vref.value='0';} else if(m.opt){optR.style.display='';durR.style.display='none';vrefR.style.display='none';fill(opt,Object.keys(m.opt));} else{optR.style.display='none';durR.style.display='none';vrefR.style.display='none';} calc(); } function calc(){ var m=M[kind.value][model.value]||{},cr=0,d=''; if(m.sd){var r=m.sd[opt.value]||[0,0],rt=r[0],vr=r[1],s=+dur.value,vs=+vref.value;cr=rt*s+vr*vs;d=rt+' cr/sec × '+s+'s'+(vs?' + '+vr+' cr/sec × '+vs+'s video ref':'');} else if(m.opt){cr=m.opt[opt.value];d='per '+kind.value;} else{cr=m.flat||0;d='per '+kind.value;} var pc=+plan.value,usd=cr*pc; out.innerHTML='<b>'+cr+' credits</b> ≈ <b>$'+usd.toFixed(usd<1?3:2)+'</b> <span class="sub">'+d+', at $'+pc.toFixed(5)+'/credit</span>'; } plan.onchange=calc;kind.onchange=models;model.onchange=inputs;opt.onchange=calc;dur.onchange=calc;vref.onchange=calc; models(); })(); </script> Estimate only — it does not include any discounts or promotional pricing. Plan rates are the published prices as of October 21, 2026. </details> ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. ## Run several MiniMax accounts Video and song requests don't need `account`. A video goes to a random account with a free slot within the `maxJobs` (1 to 10) you set with [POST accounts](/docs/api-minimax-v1/post-minimax-accounts-account), and a song to the account with the fewest songs running. Image and speech requests take `account` once you connect more than one. When every account is busy you get `429`, so wait and send it again. Hailuo AI renders one video at a time on Free and Standard and two on Pro, Master and Max, and MiniMax Audio one song at a time per account. [GET scheduler/available](/docs/api-minimax-v1/get-minimax-scheduler-available) shows the free slots on each account. Video, image, song and speech requests can also send the finished result to your webhook with `replyUrl`, so you don't have to poll while a video renders. [How useapi.net works](/docs/how-it-works) has tips for keeping your accounts healthy. ## Questions ### Is there a MiniMax Hailuo API? Through useapi.net, yes: Hailuo 3.0 runs on your Hailuo AI subscription for $0.059 a second at 768p on Pro or Master, against $0.08 on MiniMax's [developer platform](https://platform.minimax.io/docs/pricing/overview) (as of October 2026). The same account makes Veo 3.1 and Seedance 2.0 video and Midjourney V7, Nano Banana Pro and GPT Image 2 images, none of which MiniMax's developer platform sells. ### How much does the MiniMax API cost? Through useapi.net, Hailuo 3.0 at 2K costs about $0.081 a second on Hailuo AI Master or Max billed yearly ($71.20 or $184 a month), against $0.13 on MiniMax's developer platform (as of October 2026). The [price tables](#pricing) show what one video, image, song or speech clip costs on each subscription, and the calculator below them prices every model. ### Do I need a MiniMax API key? Through useapi.net, no MiniMax platform key and no pay-as-you-go balance: you use our [API token](/docs/start-here/setup-useapi) and connect your Hailuo AI website subscription through [Setup MiniMax](/docs/start-here/setup-minimax), which links it right in your browser, with no software to install. Node.js examples are on GitHub at [useapi/minimax-api](https://github.com/useapi/minimax-api). ### Is there a MiniMax text-to-speech API? Through useapi.net, yes: speech-2.8-hd costs $33 per million characters on MiniMax Audio Pro ($99 a month), against $100 pay as you go on MiniMax's developer platform, and cloning a voice costs no credits, against $1.50 a voice there (as of October 2026). [GET speech/voices](/docs/api-minimax-v1/get-minimax-speech-voices) lists more than 600 voices in 40 languages. See the [text-to-speech tutorial](/docs/articles/minimax-speech-bash). ### Is there a MiniMax music API? Through useapi.net, yes, while MiniMax's paid music and lyrics APIs have been closed to new users since August 20, 2026. [POST music/create](/docs/api-minimax-v1/post-minimax-music-create) makes full songs with vocals or instrumentals on Music 3.0 and 2.6 for about a cent a song on MiniMax Audio Pro, against $0.15 for the official API's existing users. Upload a track as a [reference](/docs/api-minimax-v1/post-minimax-music-reference) and the model covers it in a new genre. [Setup MiniMax](/docs/start-here/setup-minimax) [LLM-friendly API spec](https://useapi.net/assets/aibot/api-minimax-v1.txt) Feed this to your LLM to build integrations [Claude Code skill](/llm-tools) A drop-in useapi.net skill for Claude Code, and a rule for Cursor [Postman collection](https://www.postman.com/useapinet/useapi-net/collection/29112081-ded91f3a-ca96-4842-ad7b-6b1244fed442) (November 10, 2026) [MCP Server](/docs/api-minimax-v1/mcp) Make Hailuo videos, images, songs and speech from the Claude app, ChatGPT, Claude Code, Cursor and other MCP clients [GitHub examples](https://github.com/useapi/minimax-api) Hailuo video and Speech text-to-speech Articles: * [How to Generate Images with the MiniMax H3 Image API](/docs/articles/minimax-h3-image-api) * [How to Generate Hailuo 02 and 2.3 Video with curl: MiniMax Tutorial](/docs/articles/minimax-bash) * [How to Generate Text-to-Speech (TTS) Audio with the MiniMax (Hailuo) API](/docs/articles/minimax-speech-bash) * [Sora 2 API Alternatives Compared, With Code: Seedance 2.5, Omni Flash, MiniMax H3, Kling v3](/docs/articles/sora-2-api-alternatives) * [Seedance 2.0 and 2.5 API Pricing: Every Route, Compared](/docs/articles/seedance-2-api-pricing) {% include lang-switch.html mode="hub" key="seedance-2-pricing" %} * [Suno API Alternative: ACE Music, Mureka, Lyria 3.5, TemPolor and MiniMax](/docs/articles/suno-api-alternative) {% include lang-switch.html mode="hub" key="suno-api-alternative" %} * [Five AI Music APIs on the Same Six Briefs: ACE Music v1, TemPolor v4.8, MiniMax Music-3.0, Lyria 3.5 and Mureka V9.5](/docs/articles/ai-music-flagships-compared) {% include lang-switch.html mode="hub" key="ai-music-flagships" %} * [AI Music APIs Compared: Mureka vs MiniMax vs ElevenLabs vs Lyria 3 Pro](/docs/articles/ai-music-api-comparison) Examples: * [MiniMax: Cover a Track You Upload](/blog/260821) * [MiniMax: Music Generation, Three Ways](/blog/260817) * [MiniMax H3 vs Seedance 2.0: 2K with native audio, head to head](/blog/260730) * [Midjourney V7: prompts, image references, and pricing](/blog/260629) * [Seedance 2.0: Standard vs Fast vs Mini, omni references](/blog/260626b) * [17 AI Image Models: The Showdown](/blog/260309i) * [Nano Banana 2](/blog/260227) * [MiniMax Sora 2 & Midjourney V7](/blog/260224) * [MiniMax Sora 2, Veo 3.1](/blog/260102) * [MiniMax Agent: Nano Banana 2/Pro, Speech 2.5, Music 2.0 and more...](/blog/251124) * [MiniMax 2.3](/blog/251030) * [MiniMax 02 End Frame](/blog/250830) * [Hailuo 02 at 512p](/blog/250804m) * [Groundbreaking Video Agents](/blog/250630) * [MiniMax Images](/blog/250508) * [I2V-01-Director camera moves](/blog/250224m) Videos on YouTube: * [Pennywise the Clown, MiniMax T2V 2.3](https://www.youtube.com/watch?v=iIF5wY8Kweg) * [The Cat Exorcist](https://www.youtube.com/watch?v=4W4FE4FU2EM) * [Five AI music APIs: ACE Music v1, TemPolor v4.8, MiniMax Music-3.0, Lyria 3.5 and Mureka V9.5](https://www.youtube.com/watch?v=MSUGckk4JqU) * [AI music APIs compared: Mureka vs MiniMax vs ElevenLabs vs Lyria 3 Pro](https://www.youtube.com/watch?v=9-tVK4SYuR4) Developer Community: * <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> * <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> === URL: https://useapi.net/docs/api-minimax-v1/del-minimax-accounts-account === Document URL: https://useapi.net/docs/api-minimax-v1/del-minimax-accounts-account --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> accounts/`account` description: "Delete a previously configured MiniMax account by name via DEL accounts/account in the useapi.net MiniMax API v1." parent: MiniMax API nav_order: 400 --- ## Delete MiniMax API account September 25, 2024 (November 16, 2026) --- > **https://api.useapi.net/v1/minimax/accounts/`account`** The `account` value should correspond to an account configured previously via a [POST /accounts](/docs/api-minimax-v1/post-minimax-accounts-account) request. ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **204** **204 No Content** **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** ##### Model A successful delete answers `204` with no body, and an error answers with its `error` message and `code`. <details markdown="block" class="model-details"> <summary>The error answer, field by field</summary> ```typescript { // TypeScript, all fields are optional error: string, errorDetails: string, code: number } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X DELETE https://api.useapi.net/v1/minimax/accounts/<account> ``` **JavaScript** ``` javascript const account = "Previously configured account"; const apiUrl = `https://api.useapi.net/v1/minimax/accounts/${channnel}`; const token = "API token"; const data = { method: 'DELETE', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests account = "Previously configured account" apiUrl = f"https://api.useapi.net/v1/minimax/accounts/{account}" token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-minimax-v1/del-minimax-files-fileID === Document URL: https://useapi.net/docs/api-minimax-v1/del-minimax-files-fileID --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> files/`fileID` description: "Delete an uploaded file by fileID via DEL files/fileID in the useapi.net MiniMax API v1 — always succeeds, even if the file is already gone." parent: MiniMax API nav_order: 3500 --- ## Delete file December 23, 2024 --- Use this endpoint to delete file uploaded by * [POST files](/docs/api-minimax-v1/post-minimax-files) This endpoint will return a response `200` if you're trying to delete a file that does not exist or has already been deleted. It is safe to say it always succeeds. > **https://api.useapi.net/v1/minimax/files/`fileID`** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Path parameter - `fileID` is **required**. Specify the fileID you want to delete. ##### Responses **200** **200 OK** **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Examples **Curl** ``` bash curl -X DELETE "https://api.useapi.net/v1/minimax/files/fileID" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const fileID = "fileID to delete"; const apiUrl = `https://api.useapi.net/v1/minimax/files/${fileID}`; const response = await fetch(apiUrl, { method: 'DELETE', headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" fileID = "fileID to delete" apiUrl = f"https://api.useapi.net/v1/minimax/files/{fileID}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-minimax-v1/del-minimax-images-imageId === Document URL: https://useapi.net/docs/api-minimax-v1/del-minimax-images-imageId --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> images/`imageId` description: "Soft-delete a generated image by imageId via DEL images/imageId in the useapi.net MiniMax API v1 — hides it from GET images but keeps it retrievable by ID." parent: MiniMax API nav_order: 1400 --- ## Delete image March 17, 2025 --- Use this endpoint to delete image generated by * [POST images/create](/docs/api-minimax-v1/post-minimax-images-create) This endpoint will return a response `200` if you're trying to delete a image that does not exist or has already been deleted. It is safe to say it always succeeds. Images are soft-deleted. While the image will no longer appear in [GET images](/docs/api-minimax-v1/get-minimax-images), you can still retrieve it via [GET images/`imageId`](/docs/api-minimax-v1/get-minimax-images-imageId). > **https://api.useapi.net/v1/minimax/images/`imageId`** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Path parameter - `imageId` is **required**. Specify the imageId you want to delete. ##### Responses **200** **200 OK** **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Examples **Curl** ``` bash curl -X DELETE "https://api.useapi.net/v1/minimax/images/<imageId>" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const imageId = "imageId to delete"; const apiUrl = `https://api.useapi.net/v1/minimax/images/${imageId}`; const response = await fetch(apiUrl, { method: 'DELETE', headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" imageId = "imageId to delete" apiUrl = f"https://api.useapi.net/v1/minimax/images/{imageId}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-minimax-v1/del-minimax-music-musicId === Document URL: https://useapi.net/docs/api-minimax-v1/del-minimax-music-musicId --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> music/`musicId` description: "Remove a generated song from the MiniMax account via DELETE music/musicId in the useapi.net MiniMax API v1 — takes the musicId returned by POST music/create." parent: MiniMax API nav_order: 3100 --- ## Delete Music August 17, 2026 (November 16, 2026) --- Deletes a song from the MiniMax account it was generated on. The track disappears from [GET music](/docs/api-minimax-v1/get-minimax-music) and its `audio_url` stops resolving, so download anything you want to keep first. > **https://api.useapi.net/v1/minimax/music/{musicId}** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `musicId` is **required**, the value returned by [POST music/create](/docs/api-minimax-v1/post-minimax-music-create). Path parameter, for example `user:12345-minimax:123456789012345678-music:987654321098765`. **Notes:** - The account is taken from the `musicId` itself, so no `account` parameter is needed. - A song that is still rendering **cannot** be deleted — the call returns `409`. Wait until [GET music/musicId](/docs/api-minimax-v1/get-minimax-music-musicId) reports `statusFinal` as `true`, then delete. The generation is unaffected by the rejected attempt. ##### Responses **200** **200 OK** ```json { "musicId": "user:12345-minimax:123456789012345678-music:987654321098765", "deleted": true } ``` **400** **400 Bad Request** ```json { "error": "Path parameter musicId (bogus) has incorrect format", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **409** **409 Conflict** ```json { "error": "This song is still generating and cannot be deleted yet. Wait for statusFinal, then delete.", "code": 409 } ``` **596** **596 Account Error** ```json { "error": "Your minimax account has pending error. Please address this issue at https://useapi.net/docs/api-minimax-v1/post-minimax-accounts-account before making any new API calls.", "code": 596 } ``` A `musicId` belonging to a different useapi.net user is rejected with `400 Path parameter musicId (…) unauthorized access to user:NNNNN detected`. ##### Model A successful delete answers with the deleted song's `musicId` and `deleted: true`. <details markdown="block" class="model-details"> <summary>The delete answer, field by field</summary> ```typescript { // TypeScript, all fields are optional musicId: string, // The song that was deleted deleted: boolean } ``` </details> ##### Examples **Curl** ```bash curl -X DELETE "https://api.useapi.net/v1/minimax/music/user:12345-minimax:123456789012345678-music:987654321098765" \ -H "Authorization: Bearer …" ``` **JavaScript** ```javascript const musicId = "user:12345-minimax:123456789012345678-music:987654321098765"; const response = await fetch(`https://api.useapi.net/v1/minimax/music/${musicId}`, { method: "DELETE", headers: { "Authorization": "Bearer …" } }); console.log(await response.json()); ``` **Python** ```python import requests music_id = "user:12345-minimax:123456789012345678-music:987654321098765" response = requests.delete( f"https://api.useapi.net/v1/minimax/music/{music_id}", headers={"Authorization": "Bearer …"} ) print(response.json()) ``` === URL: https://useapi.net/docs/api-minimax-v1/del-minimax-scheduler-videoId === Document URL: https://useapi.net/docs/api-minimax-v1/del-minimax-scheduler-videoId --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> scheduler/`id` description: "Remove a video, image, music or speech generation from scheduler tracking via DEL scheduler/id in the useapi.net MiniMax API v1 without cancelling the underlying job." parent: MiniMax API nav_order: 3800 --- ## Remove video, image, music or speech generation from being tracked by the scheduler September 25, 2024 (November 16, 2026) --- API tracks the running generations of images and videos. This is done to maintain a list of currently executed video generations and to send webhook messages via optionally provided `replyUrl` parameters. If you want to remove image or video generation from being tracked by the scheduler, use this endpoint. > **https://api.useapi.net/v1/minimax/scheduler/`id`** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Path parameter - `id` is **required**. Specify videoId, imageId, musicId or audioId you want to stop tracking. **Notes:** - Stopping tracking does not cancel the work at MiniMax. A video or song carries on and can still be found through its own GET endpoint. - Speech is the exception worth knowing about. An `audioId` is issued by useapi.net rather than MiniMax, so once it stops being tracked there is nothing left to resolve it — [GET speech/`audioId`](/docs/api-minimax-v1/get-minimax-speech_audio_id) reports it as `failed` from that point on. The recording itself still completes and appears in [GET speech](/docs/api-minimax-v1/get-minimax-speech). ##### Responses **204** **204 No Content** **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** ```json { "error": "Unable to locate running <id>" } ``` ##### Model A successful removal answers `204` with no body, and an error answers with its `error` message and `code`. <details markdown="block" class="model-details"> <summary>The error answer, field by field</summary> ```typescript { // TypeScript, all fields are optional error: string code: number } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X DELETE "https://api.useapi.net/v1/minimax/scheduler/<id>" ``` **JavaScript** ``` javascript const videoId = "videoId to cancel"; const apiUrl = `https://api.useapi.net/v1/minimax/scheduler/${videoId}`; const token = "API token"; const data = { method: 'DELETE', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests videoId = "videoId to cancel" apiUrl = f"https://api.useapi.net/v1/minimax/scheduler/{videoId}" token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-minimax-v1/del-minimax-speech-audio_id === Document URL: https://useapi.net/docs/api-minimax-v1/del-minimax-speech-audio_id --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> speech/`audio_id` description: "Delete a speech recording from a MiniMax account via DELETE speech/audioId in the useapi.net MiniMax API v1, removing it from the account history for good." parent: MiniMax API nav_order: 1901 --- ## Delete text-to-speech audio clip December 27, 2024 (August 24, 2026) --- This endpoint will delete audio clip generated by * [POST speech/create](/docs/api-minimax-v1/post-minimax-speech-create) * [POST speech/create-mp3](/docs/api-minimax-v1/post-minimax-speech-create-mp3) This endpoint returns `200` for an audio clip that does not exist or has already been deleted. The one case that does not succeed is a generation still in flight — see the notes below. > **https://api.useapi.net/v1/minimax/speech/`audio_id`** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Path parameter - `audio_id` is **required**. Specify the audio_id you want to delete. **Notes:** - Accepts an `audioId` returned by [POST speech/create](/docs/api-minimax-v1/post-minimax-speech-create) as well as any `audio_id` listed by [GET speech](/docs/api-minimax-v1/get-minimax-speech). - A generation that is still running cannot be deleted, because there is nothing stored yet. Cancel it with [DELETE scheduler/`id`](/docs/api-minimax-v1/del-minimax-scheduler-videoId) instead, passing the same `audioId`. - Deleting is permanent. The recording leaves the MiniMax account and stops appearing in [GET speech](/docs/api-minimax-v1/get-minimax-speech). ##### Responses **200** **200 OK** **400** **400 Bad Request** A generation that is still running has nothing stored to delete yet: ```json { "error": "Generation is still running. Cancel it with DELETE /v1/minimax/scheduler/user:12345-minimax:123456789012345678-audio:178737039436895391" } ``` And one that never produced a recording: ```json { "error": "Nothing was generated for this audioId, so there is nothing to delete" } ``` Anything else: ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **596** **596 Account Error** ```json { "error": "Your minimax account has pending error. Please address this issue at https://useapi.net/docs/api-minimax-v1/post-minimax-accounts-account before making any new API calls.", "code": 596 } ``` ##### Examples **Curl** ``` bash curl -X DELETE "https://api.useapi.net/v1/minimax/speech/<audio_id>" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const audio_id = "audio_id to delete"; const apiUrl = `https://api.useapi.net/v1/minimax/speech/${audio_id}`; const response = await fetch(apiUrl, { method: 'DELETE', headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" audio_id = "audio_id to delete" apiUrl = f"https://api.useapi.net/v1/minimax/speech/{audio_id}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-minimax-v1/del-minimax-videos-videoId === Document URL: https://useapi.net/docs/api-minimax-v1/del-minimax-videos-videoId --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> videos/`videoId` description: "Delete a generated video by videoId via DEL videos/videoId in the useapi.net MiniMax API v1 — always returns 200, even if already deleted." parent: MiniMax API nav_order: 1000 --- ## Delete video December 23, 2024 --- Use this endpoint to delete video generated by * [videos/create](/docs/api-minimax-v1/post-minimax-videos-create) This endpoint will return a response `200` if you're trying to delete a video that does not exist or has already been deleted. It is safe to say it always succeeds. > **https://api.useapi.net/v1/minimax/videos/`videoId`** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Path parameter - `videoId` is **required**. Specify the videoId you want to delete. ##### Responses **200** **200 OK** **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Examples **Curl** ``` bash curl -X DELETE "https://api.useapi.net/v1/minimax/videos/videoId" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const videoId = "videoId to delete"; const apiUrl = `https://api.useapi.net/v1/minimax/videos/${videoId}`; const response = await fetch(apiUrl, { method: 'DELETE', headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" videoId = "videoId to delete" apiUrl = f"https://api.useapi.net/v1/minimax/videos/{videoId}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-minimax-v1/get-minimax-accounts-account === Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-accounts-account --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts/`account` description: "Retrieve the configuration for a single MiniMax account by name via GET accounts/account in the useapi.net MiniMax API v1." parent: MiniMax API nav_order: 200 --- ## Retrieve MiniMax API account configuration for `account` September 25, 2024 (November 16, 2026) --- > **https://api.useapi.net/v1/minimax/accounts/`account`** The `account` value should correspond to an account configured previously via a [POST /accounts](/docs/api-minimax-v1/post-minimax-accounts-account) request. ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** ```json { "account": "123456", "jwt": { "token": "abc…secured…xyz", "user": { "deviceID": "123456789", "id": "123456", "isAnonymous": true, "name": "<name>", "avatar": "<url>" }, "exp": 1734858598.864, "iat": 1732266598.864, "host": "hailuoai.video", "searchParams": "device_platform=web&app_id=3001&version_code=22201&uuid=b5df53d1-4c0d-4c77-8422-87e3f3b1a1d6&device_id=123456789&os_name=Windows&browser_name=chrome&device_memory=8&cpu_core_num=4&browser_language=en-US&browser_platform=Win32&screen_width=1920&screen_height=1080&unix=1732266598000", "iat_Issued": "2024-01-01T00:00:00.000Z", "exp_Expire": "2024-12-01T00:00:00.000Z" }, "maxJobs": 1, "supportVideo": true, "supportChat": true, "supportAudio": true } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** Configuration not found. To create configuration use [POST /accounts](/docs/api-minimax-v1/post-minimax-accounts-account). ##### Model The account's configuration, with its token details, `maxJobs` and which of video, chat, audio and music it supports. <details markdown="block" class="model-details"> <summary>The account's configuration, field by field</summary> ```typescript { // TypeScript, all fields are optional account: string jwt: { token: string user: { deviceID: string id: string isAnonymous: boolean name: string avatar: string }, exp: number iat: number host: string searchParams: string iat_Issued: string exp_Expire: string } maxJobs: number supportVideo: boolean supportChat: boolean supportAudio: boolean supportMusic: boolean } ``` </details> ##### Examples **Curl** ``` bash curl https://api.useapi.net/v1/minimax/accounts/<account> \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const account = "Previously configured account"; const apiUrl = `https://api.useapi.net/v1/minimax/accounts/${account}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" account = "Previously configured account" apiUrl = f"https://api.useapi.net/v1/minimax/accounts/{account}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-minimax-v1/get-minimax-accounts === Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-accounts --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts description: "List all configured MiniMax API accounts via GET accounts in the useapi.net MiniMax API v1 — used for load-balanced multi-account setups." parent: MiniMax API nav_order: 100 --- ## Retrieve MiniMax API accounts configuration September 25, 2024 (November 16, 2026) --- For your convenience, you can specify your MiniMax configuration values under your MiniMax account. If you specify multiple MiniMax accounts, the API will automatically perform load balancing by randomly selecting an account with available capacity before making calls to MiniMax. This endpoint retrieves the complete list of configured API accounts for MiniMax. > **https://api.useapi.net/v1/minimax/accounts** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** ```json { "123456": { "account": "123456", "jwt": { "token": "abc…secured…xyz", "user": { "deviceID": "123456789", "id": "123456", "isAnonymous": true, "name": "<name>", "avatar": "<url>" }, "exp": 1734858598.864, "iat": 1732266598.864, "host": "hailuoai.video", "searchParams": "device_platform=web&app_id=3001&version_code=22201&uuid=b5df53d1-4c0d-4c77-8422-87e3f3b1a1d6&device_id=123456789&os_name=Windows&browser_name=chrome&device_memory=8&cpu_core_num=4&browser_language=en-US&browser_platform=Win32&screen_width=1920&screen_height=1080&unix=1732266598000", "iat_Issued": "2024-01-01T00:00:00.000Z", "exp_Expire": "2024-12-01T00:00:00.000Z" }, "maxJobs": 1, "supportVideo": true, "supportChat": true, "supportAudio": true }, "78910": { "account": "78910", "jwt": { "token": "edf…secured…lmn", "user": { "deviceID": "987654321", "id": "78910", "isAnonymous": true, "name": "<name>", "avatar": "<url>" }, "host": "hailuoai.com", "exp": 1744858598.864, "iat": 1742266598.864, "searchParams": "device_platform=web&app_id=3001&version_code=22201&uuid=92f1a65c-3e9e-4a37-8bd7-8615a6cf60ee&device_id=987654321&os_name=Windows&browser_name=firefox&device_memory=16&cpu_core_num=8&browser_language=en-US&browser_platform=Win64&screen_width=2560&screen_height=1440&unix=1742266598000", "iat_Issued": "2025-01-01T00:00:00.000Z", "exp_Expire": "2025-12-01T00:00:00.000Z" }, "maxJobs": 1, "supportVideo": true, "supportChat": true, "supportAudio": true } } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** Configuration not found. To create configuration use [POST /accounts](/docs/api-minimax-v1/post-minimax-accounts-account). ##### Model An object keyed by account, each holding that account's configuration as [GET /accounts/`account`](/docs/api-minimax-v1/get-minimax-accounts-account) returns it. <details markdown="block" class="model-details"> <summary>The configuration of each account, field by field</summary> ```typescript { // TypeScript, all fields are optional [account: string]: { account: string jwt: { token: string user: { deviceID: string id: string isAnonymous: boolean name: string avatar: string }, exp: number iat: number host: string searchParams: string iat_Issued: string exp_Expire: string } maxJobs: number supportVideo: boolean supportChat: boolean supportAudio: boolean supportMusic: boolean } } ``` </details> ##### Examples **Curl** ``` bash curl https://api.useapi.net/v1/minimax/accounts \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = "https://api.useapi.net/v1/minimax/accounts"; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" apiUrl = "https://api.useapi.net/v1/minimax/accounts" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-minimax-v1/get-minimax-agent-jobId === Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-agent-jobId --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> agent/`jobId` description: "Poll the status and results of an async AI Agent job by jobId via GET agent/jobId in the useapi.net MiniMax API v1 — jobs are retained for 31 days." parent: MiniMax API nav_order: 2100 --- ## Retrieve Agent Job Status and Results November 24, 2025 (November 16, 2026) --- Retrieve the status and results of an agent job. Jobs are stored for 31 days after creation. Use this endpoint to check the progress of asynchronous agent jobs created with [POST agent](/docs/api-minimax-v1/post-minimax-agent) using `async: true`. > **https://api.useapi.net/v1/minimax/agent/`jobId`** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Path Parameters - `jobId` is **required**. The job ID to query. ##### Responses **200** **200 OK** Job found and returned successfully. **Started Job:** ```json { "jobId": "p123456789-u12345-a67890-bot:minimax", "status": "started", "created": "2025-11-23T12:34:56.789Z", "request": { "prompt": "Generate a video of a cat playing piano", "models": ["hailuo-2.3"], "async": true } } ``` **Completed Job:** ```json { "jobId": "p123456789-u12345-a67890-bot:minimax", "status": "completed", "created": "2025-11-23T12:34:56.789Z", "request": { "prompt": "Generate a video of a cat playing piano", "models": ["hailuo-2.3", "nano-banana-2"] }, "response": { "projectID": "123456789", "sectionID": "987654321", "chatID": "456789123", "msg_content": "I've generated a video of a cat playing piano and an image variation.", "timestamp": 1732366496789, "elapsedTime": "02:15", "attachments": [ { "attachmentID": "att_123456789", "type": 1, "status": 3, "file": { "fileName": "cat_piano_video.mp4", "fileUrl": "https://cdn.hailuoai.video/...mp4", "type": "video/mp4", "extra": { "width": "1280", "height": "720", "duration": "5.0", "fps": "24", "no_watermark_url": "https://cdn.hailuoai.video/.../no_watermark.mp4", "watermark_url": "https://cdn.hailuoai.video/.../watermark.mp4", "thumbnail_url": "https://cdn.hailuoai.video/.../thumb.jpg" } } }, { "attachmentID": "att_987654321", "type": 2, "status": 3, "file": { "fileName": "cat_piano_image.png", "fileUrl": "https://cdn.hailuoai.video/...png", "type": "image/png", "extra": { "model_name": "banana_2", "model_aspect_ratio": "16:9", "model_resolution": "1K" } } } ] } } ``` **Failed Job:** ```json { "jobId": "p123456789-u12345-a67890-bot:minimax", "status": "failed", "created": "2025-11-23T12:34:56.789Z", "request": { "prompt": "Generate a video", "models": ["hailuo-2.3"] }, "error": { "message": "Timeout waiting for assistant response", "status": 504 } } ``` **400** **400 Bad Request** Invalid job ID format or access denied. ```json { "error": "Error …", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** Job not found or expired after 31 days. ```json { "error": "Job not found or expired after 31 days", "code": 404 } ``` ##### Model The agent job record, with its `status`, the original request, and once completed the agent's reply and generated files. <details markdown="block" class="model-details"> <summary>The agent job record, field by field</summary> **Downloading Generated Files:** - `file.fileUrl` - Primary download URL (may have watermark) - `file.extra.no_watermark_url` - URL without watermark (when available) - `file.extra.watermark_url` - URL with watermark - `node.agentFile.noWatermarkUrl` - Alternative watermark-free URL - `node.agentFile.url` - Alternative file URL ```typescript { // Job metadata jobId: string // Unique job identifier status: 'started' | 'completed' | 'failed' // Job status created: string // ISO 8601 timestamp code?: number // HTTP status code (optional) // Original request request: { prompt: string // User's prompt file?: Array<{ // File metadata (actual files not included) name: string size: number type: string }> models: string[] // Model IDs used async?: boolean // Async mode flag replyUrl?: string // Callback URL replyRef?: string // User's reference ID } // Agent response (only present when status is 'completed') response?: { projectID: string // MiniMax project ID sectionID: string // MiniMax section ID chatID: string // MiniMax chat ID msg_content: string // Agent's response message timestamp: number // Response timestamp (milliseconds since epoch) elapsedTime: string // Elapsed time (mm:ss format) attachments?: Array<{ // Generated files attachmentID: string // Attachment identifier type: number // Attachment type (numeric) status: number // Attachment status (3 = completed) file: { fileName: string // File name fileUrl: string // CDN URL to download file extra?: { // Additional file metadata // Video-specific fields height?: string // Video height in pixels width?: string // Video width in pixels duration?: string // Duration in seconds fps?: string // Frames per second frames?: string // Total frame count no_watermark_url?: string // CDN URL without watermark watermark_url?: string // CDN URL with watermark thumbnail_url?: string // Thumbnail image URL url?: string // Alternative URL path?: string // File path task_id?: string // Generation task ID vendor?: string // Video generation vendor subtitle_path?: string // Subtitle file path // Image-specific fields (nano-banana-2 model) model_aspect_ratio?: string // e.g. "9:16", "16:9" model_name?: string // e.g. "banana_2" model_resolution?: string // e.g. "1K", "2K" // Audio/TTS-specific fields format?: string // e.g. "mp3" type?: string // e.g. "audio" model_speech_count?: string // Character count for TTS } posterUrl?: string // Poster/thumbnail URL type?: string // File MIME type referenceType?: number // Reference type } text?: string // Associated text content extra?: Record<string, any> // Additional metadata node?: { // Node/timeline information nodeID: string // Unique node identifier xStart: number // X position start yStart: number // Y position start width: number // Node width height: number // Node height layer: number // Layer index nodeType: number // Node type identifier agentFile?: { // Generated file details id: string // File ID name: string // File name url: string // File URL coverInfo?: { // Cover image info coverURL: string // Cover image URL } noWatermarkUrl?: string // URL without watermark duration?: number // Duration in seconds relativePath?: string // Relative file path thumbnailUrl?: string // Thumbnail URL } status: number // Node status playWidth: number // Playback width playHeight: number // Playback height logoType: number // Logo type identifier } }> } // Error information (only present when status is 'failed') error?: string | { // Error can be a string or object message: string // Error description status: number // HTTP status code details?: any // Additional error details } } ``` </details> ##### Examples **Curl** ``` bash curl -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v1/minimax/agent/p123456789-u12345-a67890-bot:minimax" ``` **JavaScript** ``` javascript const token = "YOUR_API_TOKEN"; const jobId = "p123456789-u12345-a67890-bot:minimax"; const apiUrl = `https://api.useapi.net/v1/minimax/agent/${jobId}`; const response = await fetch(apiUrl, { headers: { 'Authorization': `Bearer ${token}` } }); const job = await response.json(); console.log('Job status:', job.status); if (job.status === 'completed' && job.response?.attachments) { job.response.attachments.forEach(att => { console.log(`${att.file.fileName}: ${att.file.fileUrl}`); }); } else if (job.status === 'failed') { console.error('Job failed:', job.error); } ``` **Python** ``` python import requests token = "YOUR_API_TOKEN" job_id = "p123456789-u12345-a67890-bot:minimax" api_url = f"https://api.useapi.net/v1/minimax/agent/{job_id}" response = requests.get( api_url, headers={'Authorization': f'Bearer {token}'} ) job = response.json() print(f"Job status: {job['status']}") if job['status'] == 'completed' and job.get('response', {}).get('attachments'): for att in job['response']['attachments']: print(f"{att['file']['fileName']}: {att['file']['fileUrl']}") elif job['status'] == 'failed': print(f"Job failed: {job['error']}") ``` === URL: https://useapi.net/docs/api-minimax-v1/get-minimax-agent-jobs === Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-agent-jobs --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> agent/jobs description: "List all currently running AI Agent jobs via GET agent/jobs in the useapi.net MiniMax API v1 — only in-progress jobs; completed ones require GET agent/jobId." parent: MiniMax API nav_order: 2200 --- ## List Running Agent Jobs November 24, 2025 (November 16, 2026) --- List all currently running agent jobs for your account. This endpoint returns jobs that are still being processed (status: `started`). Completed and failed jobs are not included in this list but can be retrieved using [GET agent/`jobId`](/docs/api-minimax-v1/get-minimax-agent-jobId) if you have the job ID. > **https://api.useapi.net/v1/minimax/agent/jobs** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** List of running jobs returned successfully. Returns jobs grouped by account with execution statistics. ```json { "accounts": ["67890", "54321"], "summary": { "67890": { "executing": 2 }, "54321": { "executing": 1 } }, "executing": { "67890": [ { "jobId": "p123456789-u12345-a67890-bot:minimax", "elapsed": "02:15" }, { "jobId": "p987654321-u12345-a67890-bot:minimax", "elapsed": "01:30" } ], "54321": [ { "jobId": "p456789123-u12345-a54321-bot:minimax", "elapsed": "00:45" } ] } } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "Unauthorized" } ``` ##### Model Your configured accounts, how many agent jobs each is running, and each running job's `jobId` and elapsed time. <details markdown="block" class="model-details"> <summary>The list of running agent jobs, field by field</summary> ```typescript { accounts: string[] // List of account IDs with configured access summary: Record<string, { executing: number // Number of currently executing jobs for this account }> executing: Record<string, Array<{ // Jobs grouped by account jobId: string // Job identifier elapsed: string // Elapsed time since job started (mm:ss format) }>> } ``` </details> ##### Examples **Curl** ``` bash curl -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://api.useapi.net/v1/minimax/agent/jobs" ``` **JavaScript** ``` javascript const token = "YOUR_API_TOKEN"; const apiUrl = "https://api.useapi.net/v1/minimax/agent/jobs"; const response = await fetch(apiUrl, { headers: { 'Authorization': `Bearer ${token}` } }); const result = await response.json(); console.log(`${result.accounts.length} account(s) configured`); for (const account of result.accounts) { const summary = result.summary[account]; if (summary) { console.log(`Account ${account}: ${summary.executing} job(s) executing`); } const jobs = result.executing[account] || []; jobs.forEach(job => { console.log(` ${job.jobId} (${job.elapsed})`); }); } ``` **Python** ``` python import requests token = "YOUR_API_TOKEN" api_url = "https://api.useapi.net/v1/minimax/agent/jobs" response = requests.get( api_url, headers={'Authorization': f'Bearer {token}'} ) result = response.json() print(f"{len(result['accounts'])} account(s) configured") for account in result['accounts']: summary = result['summary'].get(account) if summary: print(f"Account {account}: {summary['executing']} job(s) executing") jobs = result['executing'].get(account, []) for job in jobs: print(f" {job['jobId']} ({job['elapsed']})") ``` === URL: https://useapi.net/docs/api-minimax-v1/get-minimax-features === Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-features --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> features description: "Retrieve account credits, available models, per-model credit costs, and queue lengths for your hailuoai.video and minimax.io/audio accounts via GET features in the useapi.net MiniMax API v1." parent: MiniMax API nav_order: 450 --- ## Retrieve your hailuoai.video and minimax.io/audio accounts information October 14, 2024 (November 16, 2026) --- Retrieve your [hailuoai.video](https://hailuoai.video) and [www.minimax.io/audio](https://www.minimax.io/audio) accounts information, see [Setup MiniMax](/docs/start-here/setup-minimax) for details. This endpoint provides detailed information about available credits and features supported by your account, such as the list of models, credits required for different models, maximum size of jobs query, and so on. > **https://api.useapi.net/v1/minimax/features/?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `account` is optional when only one [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. ##### Responses **200** **200 OK** ```json { "privilegeType": 0, "totalCredits": 100, "expireText": "100 points will expire within 24 hours", "videoCost": 30, "queueLength": 3, "memberText": "Subscribe", "memberHoverText": "", "expireTime": 0, "isNewUser": false, "questionText": "", "trialExpireTime": 0, "trialText": 0, "memberName": "Free", "newUserVersion": 0, "creditExpireText": [ { "credit": 100, "endTime": 1748735999999 } ], "modelControl": [ { "modelId": "image-01", "videoCost": 1, "isMember": false, "freeCount": 0, "durations": [], "resolutions": [], "modes": [], "videoCosts": [] }, { "modelId": "23000", "videoCost": 30, "isMember": false, "freeCount": 0, "durations": [], "resolutions": [], "modes": [], "videoCosts": [] }, { "modelId": "23010", "videoCost": 30, "isMember": false, "freeCount": 0, "durations": [], "resolutions": [], "modes": [], "videoCosts": [] }, { "modelId": "23001", "videoCost": 30, "isMember": false, "freeCount": 0, "durations": [], "resolutions": [], "modes": [], "videoCosts": [] }, { "modelId": "23011", "videoCost": 30, "isMember": false, "freeCount": 0, "durations": [], "resolutions": [], "modes": [], "videoCosts": [] }, { "modelId": "23102", "videoCost": 30, "isMember": false, "freeCount": 0, "durations": [], "resolutions": [], "modes": [], "videoCosts": [] }, { "modelId": "23021", "videoCost": 45, "isMember": false, "freeCount": 0, "durations": [], "resolutions": [], "modes": [], "videoCosts": [] } ], "supportModes": [], "imageQueueLength": 5, "totalCreditsStr": "100", "isPaidSubscription": false, "canManagePlan": true, "audio": { "total_credit": 100, "sub_credits": [ { "credit_type": 3, "end_time": 1748735999999, "credit": 100, "text": "", "record": [ { "credit": 100, "endTime": 1748735999999 } ], "coin_type": 0 } ], "base_resp": {} } } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model The account's credits, plan and per-model settings and costs, plus its minimax.io/audio credits. <details markdown="block" class="model-details"> <summary>The account's credits, plan and model settings, field by field</summary> ```typescript { // TypeScript, all fields are optional privilegeType: number totalCredits: number expireText: string videoCost: number queueLength: number memberText: string memberHoverText: string expireTime: number isNewUser: boolean questionText: string trialExpireTime: number trialText: number memberName: string newUserVersion: number creditExpireText: { credit: number endTime: number }[] modelControl: { modelId: string videoCost: number isMember: boolean freeCount: number durations: any[] resolutions: any[] modes: any[] videoCosts: any[] }[] supportModes: any[] imageQueueLength: number totalCreditsStr: string isPaidSubscription: boolean canManagePlan: boolean audio: { total_credit: number sub_credits: { credit_type: number end_time: number credit: number text: string record: { credit: number endTime: number }[] coin_type: number }[] } } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/minimax/features/?account=account" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const account = "Previously configured account"; const apiUrl = `https://api.useapi.net/v1/minimax/features/?account=${account}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" account = "Previously configured account" apiUrl = f"https://api.useapi.net/v1/minimax/features/?account={account}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-minimax-v1/get-minimax-files === Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-files --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> files description: "List images previously used in video generation via GET files in the useapi.net MiniMax API v1 — this endpoint appears retired as of March 2025 and currently returns no data." parent: MiniMax API nav_order: 3400 --- ## Retrieve the list of images you have uploaded October 14, 2024 (November 16, 2026) --- Use [hailuoai.video](https://hailuoai.video) account to retrieve list of uploaded images, see [Setup MiniMax](/docs/start-here/setup-minimax) for details. This endpoint will return a list of all the images you've used previously to generate videos. Only images that were actually used for generation will be shown. **NOTE**: As of March 2025, this endpoint appears to be retired both on [hailuoai.video](https://hailuoai.video) website and internally, as it is not used by any website API calls nor does it return any data. We decided to keep it just in case it is revived. > **https://api.useapi.net/v1/minimax/files/?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `account` is optional when only one [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `limit` is optional, specify the number of files to return. Default 10. ##### Responses **200** **200 OK** ```json [ { "file_id": "user:user_id-minimax:account-file:file_id_#1", "file_name": "<file name>", "file_type": "jpeg", "cdn_url": "<file ulr>", "oss_path": "<file path with name>", "file_scene": 10, "file_status": 1 }, { "file_id": "user:user_id-minimax:account-file:file_id_#n", "file_name": "<file name>", "file_type": "png", "cdn_url": "<file ulr>", "oss_path": "<file path with name>", "file_scene": 10, "file_status": 1 } ] ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model A list of the images you have uploaded, each with its `file_id`, name, type and CDN URL. <details markdown="block" class="model-details"> <summary>The list of uploaded images, field by field</summary> ```typescript { // TypeScript, all fields are optional file_id: string file_name: string file_type: string cdn_url: string oss_path: string file_scene: number file_status: number }[] ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/minimax/files/?account=account" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const account = "Previously configured account"; const apiUrl = `https://api.useapi.net/v1/minimax/files/?account=${account}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" account = "Previously configured account" apiUrl = f"https://api.useapi.net/v1/minimax/files/?account={account}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-minimax-v1/get-minimax-images-imageId === Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-images-imageId --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> images/`imageId` description: "Retrieve the status and results of an image generation by imageId via GET images/imageId in the useapi.net MiniMax API v1." parent: MiniMax API nav_order: 1300 --- ## Retrieve image March 17, 2025 (November 16, 2026) --- Use this endpoint to retrieve status and results of * [POST images/create](/docs/api-minimax-v1/post-minimax-images-create) > **https://api.useapi.net/v1/minimax/images/`imageId`** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Path parameter - `imageId` is **required**. Specify the imageId you want to retrieve. ##### Responses **200** **200 OK** ```json { "id": "<image_id>", "desc": "...prompt...", "coverURL": "https://cdn.hailuoai.video/...png?x-oss-process=image/resize,w_1080/format,webp", "videoURL": "https://cdn.hailuoai.video/....png", "status": 2, "canRetry": false, "width": 0, "height": 0, "originFiles": [], "canAppeal": false, "downloadURL": "https://cdn.hailuoai.video/....png", "hasVoice": false, "modelID": "image-01", "useOriginPrompt": false, "isBookmarked": false, "disableGenerateSimilar": false, "createTime": 1742173334234, "postStatus": 0, "userID": 923847293472394000, "createType": 4, "promptImgURL": "", "extra": { "cameraMotions": [], "promptStruct": "" }, "isVisitor": false, "videoURLs": { "feedURL": "", "downloadURLWithWatermark": "https://cdn.hailuoai.video/....png" }, "priority": 0, "generatorType": 1, "isInFolder": false, "batchID": "357846312387492374", "aspectRatio": "9:16", "fileID": "user:<user>-minimax:<account>-file:<file_id>", "tags": [ { "type": "normal", "tagIcon": "", "tagText": "image-01" }, { "type": "normal", "tagIcon": "", "tagText": "Enable Optimization" }, { "type": "normal", "tagIcon": "", "tagText": "Image to video" } ], "duration": 0, "resolution": 0, "humanCheckStatus": 0, "userIDStr": "<account>", "statusLabel": "completed", "statusFinal": true, "imageId": "user:<user>-minimax:<account>-image:<image_id>" } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** ```json { "error": "Not found.", "code": 404 } ``` ##### Model The image record, with its numeric `status`, `statusFinal`, progress while it runs, and its size and download URLs. <details markdown="block" class="model-details"> <summary>The image record and its <code>status</code> values, field by field</summary> Known `status` values: * **0** pending * **1** processing * **2** completed * **3** failed * **5** moderated * **7** moderated * **11** queued * **12** processing * **14** moderated Optional fields `message` and `percent` will contain generation progress information. ```typescript { // TypeScript, all fields are optional id: string desc: string coverURL: string videoURL: string status: number message: string // Contains the message shown to the user while the image is being processed percent: number // Contains 0-100 percent while the image is being processed canRetry: boolean width: number height: number originFiles: any[] canAppeal: boolean downloadURL: string hasVoice: boolean modelID: string useOriginPrompt: boolean isBookmarked: boolean disableGenerateSimilar: boolean createTime: number postStatus: number userID: number createType: number promptImgURL: string extra: { cameraMotions: any[] promptStruct: string } isVisitor: boolean videoURLs: { feedURL: string downloadURLWithWatermark: string } priority: number generatorType: number isInFolder: boolean batchID: string aspectRatio: string fileID: string tags: { type: string tagIcon: string tagText: string }[] duration: number resolution: number humanCheckStatus: number userIDStr: string statusLabel: string statusFinal: boolean imageId: string } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/minimax/images/<imageId>" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const imageId = "imageId to retrieve"; const apiUrl = `https://api.useapi.net/v1/minimax/images/${imageId}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" imageId = "imageId to retrieve" apiUrl = f"https://api.useapi.net/v1/minimax/images/{imageId}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-minimax-v1/get-minimax-images === Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-images --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> images description: "List all images you have generated via GET images in the useapi.net MiniMax API v1, with pagination and optional account filter." parent: MiniMax API nav_order: 1200 --- ## Retrieve the list of images you have generated March 17, 2025 (November 16, 2026) --- Use [hailuoai.video](https://hailuoai.video) account to retrieve list of generated images, see [Setup MiniMax](/docs/start-here/setup-minimax) for details. Returned image `fileID` value can be used as a parameter for [POST videos/create](/docs/api-minimax-v1/post-minimax-videos-create). > **https://api.useapi.net/v1/minimax/images/?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `account` is optional when only one [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `limit` is optional, specify the number of images to return. Default 30. - `lastImageId` is optional, specify the image id from where to start. ##### Responses **200** **200 OK** ```json { "images": [ { "id": "<image_id>", "desc": "...prompt...", "coverURL": "https://cdn.hailuoai.video/...png?x-oss-process=image/resize,w_1080/format,webp", "videoURL": "https://cdn.hailuoai.video/....png", "status": 2, "canRetry": false, "width": 0, "height": 0, "originFiles": [], "canAppeal": false, "downloadURL": "https://cdn.hailuoai.video/....png", "hasVoice": false, "modelID": "image-01", "useOriginPrompt": false, "isBookmarked": false, "disableGenerateSimilar": false, "createTime": 1742173334234, "postStatus": 0, "userID": 923847293472394000, "createType": 4, "promptImgURL": "", "extra": { "cameraMotions": [], "promptStruct": "" }, "isVisitor": false, "videoURLs": { "feedURL": "", "downloadURLWithWatermark": "https://cdn.hailuoai.video/....png" }, "priority": 0, "generatorType": 1, "isInFolder": false, "batchID": "357846312387492374", "aspectRatio": "9:16", "fileID": "user:<user>-minimax:<account>-file:<file_id>", "tags": [ { "type": "normal", "tagIcon": "", "tagText": "image-01" }, { "type": "normal", "tagIcon": "", "tagText": "Enable Optimization" }, { "type": "normal", "tagIcon": "", "tagText": "Image to video" } ], "duration": 0, "resolution": 0, "humanCheckStatus": 0, "userIDStr": "<account>", "statusLabel": "completed", "statusFinal": true, "imageId": "user:<user>-minimax:<account>-image:<image_id>" } ], "hasPre": false, "hasNext": true, "processing": false, "total": 4135 } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model Your generated images, each with its `imageId`, numeric `status` and `fileID`, plus `hasNext` to tell whether more pages follow. <details markdown="block" class="model-details"> <summary>The list of images and their <code>status</code> values, field by field</summary> Known `status` values: * **0** pending * **1** processing * **2** completed * **3** failed * **5** moderated * **7** moderated * **11** queued * **12** processing * **14** moderated ```typescript { images: { id: string desc: string coverURL: string videoURL: string status: number canRetry: boolean width: number height: number originFiles: any[] canAppeal: boolean downloadURL: string hasVoice: boolean modelID: string useOriginPrompt: boolean isBookmarked: boolean disableGenerateSimilar: boolean createTime: number postStatus: number userID: number createType: number promptImgURL: string extra: { cameraMotions: any[] promptStruct: string } isVisitor: boolean videoURLs: { feedURL: string downloadURLWithWatermark: string } priority: number generatorType: number isInFolder: boolean batchID: string aspectRatio: string fileID: string tags: { type: string tagIcon: string tagText: string }[] duration: number resolution: number humanCheckStatus: number userIDStr: string statusLabel: string statusFinal: boolean imageId: string }[] hasPre: boolean hasNext: boolean processing: boolean total: number } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/minimax/images/?account=<account>" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const account = "Previously configured account"; const apiUrl = `https://api.useapi.net/v1/minimax/images/?account=${account}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" account = "Previously configured account" apiUrl = f"https://api.useapi.net/v1/minimax/images/?account={account}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-minimax-v1/get-minimax-music-musicId === Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-music-musicId --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> music/`musicId` description: "Poll a single MiniMax song by musicId via GET music/musicId in the useapi.net MiniMax API v1 — returns status, duration, lyrics, and the MP3 download URL once rendering completes." parent: MiniMax API nav_order: 3000 --- ## Retrieve Music September 25, 2024 (November 16, 2026) --- Retrieve a single song created with [POST music/create](/docs/api-minimax-v1/post-minimax-music-create). Poll this endpoint until `statusFinal` is `true`, at which point `audio_url` holds the MP3 and `duration` is set. It also returns reference tracks uploaded with [POST music/reference](/docs/api-minimax-v1/post-minimax-music-reference), which need no polling — they arrive `completed`. `typeLabel` tells the two apart. Supplying a `replyUrl` on the original create call avoids polling altogether — we POST this same object to your URL as soon as the track finishes. > **https://api.useapi.net/v1/minimax/music/{musicId}** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `musicId` is **required**, the value returned by [POST music/create](/docs/api-minimax-v1/post-minimax-music-create). Path parameter, for example `user:12345-minimax:123456789012345678-music:987654321098765`. **Notes:** - Poll every 15 to 20 seconds. Generation time varies with the model, the length of the song, and how busy MiniMax is. - When `quantity` was greater than `1`, each `musicId` finishes independently — poll each one. ##### Status values | status | statusLabel | statusFinal | Notes | |:------:|-------------|:-----------:|-------| | 0 | `pending` | false | Queued, not started | | 1 | `processing` | false | Rendering — `audio_url` empty, `duration` 0 | | 2 | `completed` | true | `audio_url` and `duration` are set | | 3 | `failed` | true | MiniMax accepted the request but could not render it — `audio_url` stays empty and `duration` stays 0 | | 4 | `moderated` | true | Rejected by content moderation | ##### Responses **200** **200 OK** ```json { "musicId": "user:12345-minimax:123456789012345678-music:987654321098765", "title": "Lisbon Rain", "idea": "warm nylon guitar, slow bossa nova, about a rainy afternoon in Lisbon", "lyrics": "[Verse]\nThe tram climbs up the hill\n[Chorus]\nAnd the rain keeps falling still", "audio_url": "https://cdn.hailuoai.video/moss/prod/2026-08-16-02/moss-audio/user_music/1700000000000000000-987654321098765.mp3", "cover_url": "https://cdn.hailuoai.video/moss/staging/2025-06-22-16/music_cover/1700000000000000001-other_43.png", "model": "music-3.0", "status": 2, "statusLabel": "completed", "statusFinal": true, "typeLabel": "song", "instrumental": false, "duration": 138472, "create_time": 1786849532637, "update_time": 1786849671000, "is_favorite": false, "author_info": { "user_name": "Your Name", "avatar": "https://cdn.hailuoai.video/moss/prod/2026-03-02-06/user/user_avatar/1700000000000000003-avatar_123456789012345678" }, "tag_list": [ { "tag_name": "warm nylon guitar, slow bossa nova, about a rainy afternoon in Lisbon", "tag_type": 1 } ] } ``` **400** **400 Bad Request** ```json { "error": "Path parameter musicId (bogus) has incorrect format", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** ```json { "error": "Music user:12345-minimax:123456789012345678-music:987654321098765 not found. Possibly moderated prompt." } ``` **596** **596 Account Error** ```json { "error": "Your minimax account has pending error. Please address this issue at https://useapi.net/docs/api-minimax-v1/post-minimax-accounts-account before making any new API calls.", "code": 596 } ``` ##### Model The song record, with its `status`, `statusFinal`, lyrics and, once complete, the MP3 in `audio_url`. <details markdown="block" class="model-details"> <summary>The song record, field by field</summary> ```typescript { // TypeScript, all fields are optional musicId: string, title: string, idea: string, // The prompt used to generate this track lyrics: string, // Yours, or written by the model audio_url: string, // MP3, 256 kbps 44.1 kHz stereo. Empty until complete cover_url: string, model: string, // music-3.0 | music-2.6 status: number, // See the status table above statusLabel: string, statusFinal: boolean, typeLabel: string, // song | reference — see GET music referenceMusicId: string, // Present only on a cover: the track it follows instrumental: boolean, duration: number, // Milliseconds, 0 until complete create_time: number, update_time: number, is_favorite: boolean, author_info: { user_name: string, avatar: string }, tag_list: [{ tag_name: string, tag_type: number }] } ``` </details> ##### Examples **Curl** ```bash curl "https://api.useapi.net/v1/minimax/music/user:12345-minimax:123456789012345678-music:987654321098765" \ -H "Authorization: Bearer …" ``` **JavaScript** ```javascript const musicId = "user:12345-minimax:123456789012345678-music:987654321098765"; while (true) { const response = await fetch(`https://api.useapi.net/v1/minimax/music/${musicId}`, { headers: { "Authorization": "Bearer …" } }); const track = await response.json(); if (track.statusFinal) { console.log(track.status === 2 ? track.audio_url : track.statusLabel); break; } await new Promise(resolve => setTimeout(resolve, 20000)); } ``` **Python** ```python import requests, time music_id = "user:12345-minimax:123456789012345678-music:987654321098765" while True: response = requests.get( f"https://api.useapi.net/v1/minimax/music/{music_id}", headers={"Authorization": "Bearer …"} ) track = response.json() if track["statusFinal"]: print(track["audio_url"] if track["status"] == 2 else track["statusLabel"]) break time.sleep(20) ``` === URL: https://useapi.net/docs/api-minimax-v1/get-minimax-music === Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-music --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> music description: "List the songs and reference tracks on a MiniMax account via GET music in the useapi.net MiniMax API v1 — newest first, filtered by type, with pagination by lastMusicId and a favourites filter." parent: MiniMax API nav_order: 3200 --- ## Retrieve the list of your music September 25, 2024 (November 16, 2026) --- Lists the songs on a configured MiniMax account, newest first. Tracks still rendering appear here too, with `statusLabel` set to `processing` and an empty `audio_url`. This list reflects the MiniMax account itself, so it also includes songs created directly on [minimax.io](https://www.minimax.io/audio/music) rather than through this API. The account holds two kinds of record and `type` chooses between them. Generated songs are returned by default. Reference tracks — the clips uploaded with [POST music/reference](/docs/api-minimax-v1/post-minimax-music-reference) to make covers from — are held back unless you ask for them, so adding references to an account never changes what an existing integration sees. > **https://api.useapi.net/v1/minimax/music/?account={account}&limit={limit}&lastMusicId={lastMusicId}&favorite={favorite}&type={type}** Note the trailing slash after `music` — without it the request does not reach this endpoint. ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `account` is optional when only one account is configured. If you have several MiniMax accounts configured, this parameter becomes **required**. - `limit` is optional, the number of songs to return. Default: `30`. Maximum: `100`. - `lastMusicId` is optional, the `musicId` to start from. Results continue from the song *after* it, which is how you page through a long history. The cursor is looked up across the most recent 1000 songs. A `musicId` older than that returns `400` rather than silently restarting from the newest song. - `favorite` is optional, return only songs marked as favourites on the MiniMax account. Default: `false`. - `type` is optional, which kind of record to return. Default: `song`. | Value | Returns | |---|---| | `song` | Generated songs, covers included. The default. | | `reference` | Reference tracks uploaded with [POST music/reference](/docs/api-minimax-v1/post-minimax-music-reference) | | `all` | Both, interleaved by date | Every row carries `typeLabel` saying which it is. A cover is a song, not a reference — you recognise it by `referenceMusicId` being set. ##### Responses **200** **200 OK** ```json [ { "musicId": "user:12345-minimax:123456789012345678-music:987654321098766", "title": "Lisbon Rain", "idea": "warm nylon guitar, slow bossa nova, about a rainy afternoon in Lisbon", "lyrics": "[Verse]\nThe tram climbs up the hill\n[Chorus]\nAnd the rain keeps falling still", "audio_url": "https://cdn.hailuoai.video/moss/prod/2026-08-16-02/moss-audio/user_music/1700000000000000000-987654321098766.mp3", "cover_url": "https://cdn.hailuoai.video/moss/staging/2025-06-22-16/music_cover/1700000000000000002-other_45.png", "model": "music-3.0", "status": 2, "statusLabel": "completed", "statusFinal": true, "typeLabel": "song", "instrumental": false, "duration": 138472, "update_time": 1786827844513, "is_favorite": false, "hasWav": false, "tag_list": [ { "tag_name": "warm nylon guitar, slow bossa nova, about a rainy afternoon in Lisbon", "tag_type": 1 } ] } ] ``` **400** **400 Bad Request** ```json { "error": "Please use parameter account to specify account", "code": 400 } ``` A `lastMusicId` older than the retrievable window: ```json { "error": "lastMusicId user:12345-minimax:123456789012345678-music:987654321098765 was not found in the most recent 1000 songs", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **596** **596 Account Error** ```json { "error": "Your minimax account has pending error. Please address this issue at https://useapi.net/docs/api-minimax-v1/post-minimax-accounts-account before making any new API calls.", "code": 596 } ``` An account with no songs returns an empty array. ##### Model An array of the account's songs, newest first, each with its `musicId`, `status`, lyrics and `audio_url`. <details markdown="block" class="model-details"> <summary>The list of songs, field by field</summary> ```typescript [{ // TypeScript, all fields are optional musicId: string, // Use with GET music/musicId title: string, idea: string, lyrics: string, audio_url: string, // Empty while still rendering cover_url: string, model: string, // music-3.0 | music-2.6 status: number, // See GET music/musicId for the status table statusLabel: string, statusFinal: boolean, typeLabel: string, // song | reference referenceMusicId: string, // Present only on a cover: the track it follows instrumental: boolean, duration: number, // Milliseconds update_time: number, is_favorite: boolean, hasWav: boolean, tag_list: [{ tag_name: string, tag_type: number }] }] ``` </details> ##### Examples **Curl** ```bash curl "https://api.useapi.net/v1/minimax/music/?limit=10" \ -H "Authorization: Bearer …" ``` **JavaScript** ```javascript const response = await fetch("https://api.useapi.net/v1/minimax/music/?limit=10", { headers: { "Authorization": "Bearer …" } }); const tracks = await response.json(); for (const track of tracks) console.log(track.title, track.statusLabel, track.audio_url); ``` **Python** ```python import requests response = requests.get( "https://api.useapi.net/v1/minimax/music/", headers={"Authorization": "Bearer …"}, params={"limit": 10} ) for track in response.json(): print(track["title"], track["statusLabel"], track["audio_url"]) ``` === URL: https://useapi.net/docs/api-minimax-v1/get-minimax-scheduler-available === Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-scheduler-available --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> scheduler/available description: "Check running video jobs and per-account slot availability via GET scheduler/available in the useapi.net MiniMax API v1 before submitting new generations." parent: MiniMax API nav_order: 3700 --- ## Retrieve the list of videos currently running via the API along with the available account capacity October 15, 2024 (November 16, 2026) --- This endpoint retrieves the list of images and videos currently running via the API along with the available account capacity. If you want to get all videos currently being executed including you manually initiated from hailuoai.com website use [GET /videos](/docs/api-minimax-v1/get-minimax-videos). If you want to get all images currently being executed including you manually initiated from hailuoai.com website use [GET /images](/docs/api-minimax-v1/get-minimax-images). Please refer to code provided in the [Hailuo video tutorial](/docs/articles/minimax-bash) to see how this endpoint can be used in conjunction with [POST /files](/docs/api-minimax-v1/post-minimax-files) and [POST videos/create](/docs/api-minimax-v1/post-minimax-videos-create). **NOTE**: The available capacity (array `available`) includes only videos, the API does not include currently executing image generations in that capacity. > **https://api.useapi.net/v1/minimax/scheduler/available** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** ```json { "executing": [ { "videoId": "user:user_id-minimax:account-video:id1", "started": "2024-09-25T01:55:16.128Z", "elapsed": "03:57", "replyUrl": "<optional callback URL>", "replyRef": "<optional reference>" }, { "videoId": "user:user_id-minimax:account-image:inN", "started": "2024-09-25T01:58:18.555Z", "elapsed": "00:35", "replyUrl": "<optional callback URL>", "replyRef": "<optional reference>" }, { "musicId": "user:user_id-minimax:account-music:idN", "started": "2026-08-17T02:11:04.312Z", "elapsed": "01:12" }, { "audioId": "user:user_id-minimax:account-audio:idN", "started": "2026-08-24T02:11:04.312Z", "elapsed": "00:08" } ], "available": [ { "account": "<account_1>", "maxJobs": 5, "executing": 0, "available": 5, "executingMusic": 0 }, { "account": "<account_2>", "maxJobs": 5, "executing": 3, "available": 2, "executingMusic": 1 }, { "account": "<account_N>", "maxJobs": 3, "executing": 2, "available": 1, "executingMusic": 0 } ] } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model The jobs running through the API, and for each account its `maxJobs`, running count and `available` capacity. <details markdown="block" class="model-details"> <summary>The running jobs and each account's free capacity, field by field</summary> ```typescript { // TypeScript, all fields are optional executing: { videoId: string imageId: string musicId: string audioId: string started: string elapsed: string replyUrl: string replyRef: string }[] available: { account: string maxJobs: number executing: number available: number executingMusic: number // music generations in flight; music has no local ceiling executingAudio: number // speech generations in flight, same reasoning }[] error: string code: number } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/minimax/scheduler/available" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = `https://api.useapi.net/v1/minimax/scheduler/available`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" apiUrl = f"https://api.useapi.net/v1/minimax/scheduler/available" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-minimax-v1/get-minimax-scheduler === Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-scheduler --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> scheduler description: "Retrieve all video, image, music and speech generations currently running via the API via GET scheduler in the useapi.net MiniMax API v1 — API-initiated jobs only." parent: MiniMax API nav_order: 3600 --- ## Retrieve the list of images, videos, music and speech currently being executed by the API September 25, 2024 (November 16, 2026) --- This endpoint retrieves the list of images and videos currently being executed by the API. If you want to get all videos currently being executed including you manually initiated from hailuoai.com website use [GET /videos](/docs/api-minimax-v1/get-minimax-videos). If you want to get all images currently being executed including you manually initiated from hailuoai.com website use [GET /images](/docs/api-minimax-v1/get-minimax-images). > **https://api.useapi.net/v1/minimax/scheduler/** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** ```json [ { "videoId": "user:user_id-minimax:account-video:id1", "started": "2024-09-25T01:55:16.128Z", "elapsed": "03:57", "replyUrl": "<optional callback URL>", "replyRef": "<optional reference>" }, { "videoId": "user:user_id-minimax:account-image:inN", "started": "2024-09-25T01:58:18.555Z", "elapsed": "00:35", "replyUrl": "<optional callback URL>", "replyRef": "<optional reference>" }, { "musicId": "user:user_id-minimax:account-music:idN", "started": "2026-08-17T02:11:04.312Z", "elapsed": "01:12", "replyUrl": "<optional callback URL>", "replyRef": "<optional reference>" }, { "audioId": "user:user_id-minimax:account-audio:idN", "started": "2026-08-24T02:11:04.312Z", "elapsed": "00:08", "replyUrl": "<optional callback URL>", "replyRef": "<optional reference>" } ] ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model An array of the jobs the API is running now, each with its id, start time and elapsed time. <details markdown="block" class="model-details"> <summary>The list of running jobs, field by field</summary> ```typescript { // TypeScript, all fields are optional videoId: string imageId: string musicId: string audioId: string started: number elapsed: string replyUrl: string replyRef: string }[] ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/minimax/scheduler/" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = `https://api.useapi.net/v1/minimax/scheduler/`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" apiUrl = f"https://api.useapi.net/v1/minimax/scheduler/" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-minimax-v1/get-minimax-speech-config === Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-speech-config --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> speech/config description: "Fetch the speech emotion list and voice tag vocabularies via GET speech/config in the useapi.net MiniMax API v1, everything needed to build your own voice picker." parent: MiniMax API nav_order: 1899 --- ## Retrieve audio configuration parameters December 23, 2024 (November 16, 2026) --- Returns the vocabularies speech generation accepts — the emotion names, the voice tags used for filtering, and the languages available for `language_boost`. > **https://api.useapi.net/v1/minimax/speech/config/?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `account` is optional when only one [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. ##### Responses **200** **200 OK** ```json { "t2a_emotion": [ { "label": "Happy", "value": "happy" }, { "label": "...", "value": "..." } ], "voice_tag_accent": [ { "language": "English", "tag_name": "EN-US (General)" }, { "language": "...", "tag_name": "..." } ], "voice_tag_age": [ { "tag_name": "Young" }, { "tag_name": "..." } ], "voice_tag_gender": [ { "tag_name": "Male" }, { "tag_name": "..." } ], "voice_tag_language": [ { "tag_name": "English" }, { "tag_name": "..." } ] } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **596** **596 Account Error** ```json { "error": "Your minimax account has pending error. Please address this issue at https://useapi.net/docs/api-minimax-v1/post-minimax-accounts-account before making any new API calls.", "code": 596 } ``` ##### Model The emotion names and the accent, age, gender and language voice tags that speech generation accepts. <details markdown="block" class="model-details"> <summary>The speech emotions and voice tags, field by field</summary> ```typescript { // TypeScript, all fields are optional t2a_emotion: { label: string value: string }[] voice_tag_accent: { language: string tag_name: string }[] voice_tag_age: { tag_name: string }[] voice_tag_gender: { tag_name: string }[] voice_tag_language: { tag_name: string }[] } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/minimax/speech/config/?account=account" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const account = "Previously configured account"; const apiUrl = `https://api.useapi.net/v1/minimax/speech/config/?account=${account}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" account = "Previously configured account" apiUrl = f"https://api.useapi.net/v1/minimax/speech/config/?account={account}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-minimax-v1/get-minimax-speech-equity === Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-speech-equity --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> speech/equity description: "Check how many voice cloning slots an account has used and how many it holds via GET speech/equity in the useapi.net MiniMax API v1, before spending twenty seconds on a clone that cannot be saved." parent: MiniMax API nav_order: 1900 --- ## Voice Cloning Quota August 24, 2026 (November 16, 2026) --- Returns how many cloned voice slots the MiniMax account holds and how many are in use. Worth calling before [POST speech/clone-voice](/docs/api-minimax-v1/post-minimax-speech-clone-voice), which spends around twenty seconds building a voice. Without this the only signal that an account is out of slots arrives after that work is done. > **https://api.useapi.net/v1/minimax/speech/equity?account={account}** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `account` is optional when only one account is configured. If you have several MiniMax accounts configured, this parameter becomes **required**. ##### Responses **200** **200 OK** ```json { "used": 3, "total": 3, "voice_clone_preview_free_quota": "inf", "srt_download": false, "base_resp": {} } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **596** **596 Account Error** ```json { "error": "Your minimax account has pending error. Please address this issue at https://useapi.net/docs/api-minimax-v1/post-minimax-accounts-account before making any new API calls.", "code": 596 } ``` ##### Model How many cloned voice slots the account has (`total`) and how many are in use (`used`). <details markdown="block" class="model-details"> <summary>The account's voice cloning quota, field by field</summary> ```typescript { // TypeScript, all fields are optional used: number, // Cloned voices currently stored total: number, // Slots the plan grants voice_clone_preview_free_quota: string, // Free clone previews left, "inf" when unlimited srt_download: boolean // Whether the plan includes SRT download on minimax.io } ``` - `used` is allowed to exceed `total`. An account observed with three slots reported four in use, so treat these figures as advisory rather than as a hard gate — the authoritative refusal is the error returned by [POST speech/clone-voice](/docs/api-minimax-v1/post-minimax-speech-clone-voice) itself. - Slots are freed by [POST speech/delete-voice](/docs/api-minimax-v1/post-minimax-speech-delete-voice). - `srt_download` reflects whether the MiniMax plan includes subtitle downloads on their own site. It does not gate this API — word timings come back on [POST speech/create-mp3](/docs/api-minimax-v1/post-minimax-speech-create-mp3) and the streaming `done` event whatever it says, see [Word timings](/docs/api-minimax-v1/post-minimax-speech-create#word-timings). </details> ##### Examples **Curl** ```bash curl "https://api.useapi.net/v1/minimax/speech/equity?account=123456789012345678" \ -H "Authorization: Bearer …" ``` **JavaScript** ```javascript const response = await fetch("https://api.useapi.net/v1/minimax/speech/equity?account=123456789012345678", { headers: { "Authorization": "Bearer …" } }); const { used, total } = await response.json(); console.log(`${used} of ${total} voice slots in use`); ``` **Python** ```python import requests response = requests.get( "https://api.useapi.net/v1/minimax/speech/equity", headers={"Authorization": "Bearer …"}, params={"account": "123456789012345678"} ) equity = response.json() print(equity["used"], "of", equity["total"], "voice slots in use") ``` === URL: https://useapi.net/docs/api-minimax-v1/get-minimax-speech-voices === Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-speech-voices --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> speech/voices description: "Browse MiniMax speech voices via GET speech/voices in the useapi.net MiniMax API v1 — system and cloned voices, filtered by language, gender, age and accent tags." parent: MiniMax API nav_order: 1898 --- ## Retrieve the list of system and cloned audio voices December 23, 2024 (November 16, 2026) --- Lists the voices the account can generate with — MiniMax's built-in catalogue, or the ones you have cloned yourself. 600+ pre-built voices, tagged for filtering with `tag_list`: * Languages: 40, from English, Chinese (Mandarin and Cantonese), Japanese and Korean through to Thai, Hindi, Tamil and Afrikaans * Emotions: happy, sad, angry, fearful, disgusted, surprised, neutral, fluent * Accents: `EN-US (General)`, `EN-Australian`, `EN-British`, `EN-Indian`, `CN-Northern`, `CN-Southern` * Ages: `Child`, `Young`, `Middle-aged`, `Elderly` * Genders: `Male`, `Female` `tag_list` matches these strings exactly, including case. A tag it does not recognise is ignored rather than rejected, so a typo silently *widens* the result instead of narrowing it — `Female,Middle-Aged` returns the same 310 voices as `Female` alone, spanning every age. Check the count when you add a filter. [GET speech/config](/docs/api-minimax-v1/get-minimax-speech-config) returns the tags the picker UI offers, updated as MiniMax adds to them. Voices carry others besides — `Documentary`, `Calm` and `Adult` all match voices without appearing there. > **https://api.useapi.net/v1/minimax/speech/voices/?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `account` is optional when only one [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `tag_list` is optional. Specify a comma-separated list of tags using those returned by [GET speech/config](/docs/api-minimax-v1/get-minimax-speech-config) to narrow down the returned results. Example: `Italian,Female` - `page` and `page_size` are optional. Use them to retrieve the next page of data when the returned `has_more` field is `true`. Default `page_size` is 500. - `is_system` is optional. Set to `false` if you want to retrieve a list of custom voices cloned via [POST speech/clone-voice](/docs/api-minimax-v1/post-minimax-speech-clone-voice). The entire list of custom voices will be returned at once, the `page` and `page_size` parameters will not be used. Default is `true` (return system voices). ##### Responses **200** **200 OK** `GET` [https://api.useapi.net/v1/minimax/speech/voices/?tag_list=Italian,Female](https://api.useapi.net/v1/minimax/speech/voices/?tag_list=Italian,Female) ```json { "voice_list": [ { "voice_id": "209544421245048", "parent_voice_id": "0", "voice_name": "Diligent Leader", "tag_list": [ "Italian", "Female", "Adult", "Calm", "Standard" ], "file_id": "", "cover_url": "https://cdn.hailuoai.video/moss/staging/2024-11-21-14/moss-audio/voice_cover//1732171514479796864-207331589841022.png?x-oss-process=image/resize,p_50/format,webp", "create_time": 1732711650948, "update_time": 1732711650948, "collected": false, "voice_status": 2, "sample_audio": "https://cdn.hailuoai.video/moss/staging/2024-11-25-20/moss-audio/voice_sample_audio/1732537441602153587-official_sample_audio/4_it05.mp3", "uniq_id": "Italian_DiligentLeader", "group_id": "0" } ], "total": 1, "has_more": false } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **596** **596 Account Error** ```json { "error": "Your minimax account has pending error. Please address this issue at https://useapi.net/docs/api-minimax-v1/post-minimax-accounts-account before making any new API calls.", "code": 596 } ``` ##### Model A list of voices, each with its `voice_id`, name, tags and sample audio, plus `total` and `has_more` for paging. <details markdown="block" class="model-details"> <summary>The list of voices, field by field</summary> ```typescript { // TypeScript, all fields are optional voice_list: { voice_id: string parent_voice_id: string voice_name: string tag_list: string[] file_id: string cover_url: string create_time: number update_time: number collected: boolean voice_status: number sample_audio: string uniq_id: string group_id: string }[] total: number has_more: boolean } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/minimax/speech/voices/?account=account" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const account = "Previously configured account"; const apiUrl = `https://api.useapi.net/v1/minimax/speech/voices/?account=${account}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" account = "Previously configured account" apiUrl = f"https://api.useapi.net/v1/minimax/speech/voices/?account={account}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-minimax-v1/get-minimax-speech === Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-speech --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> speech description: "List every speech recording on a MiniMax account via GET speech in the useapi.net MiniMax API v1 — newest first, with audio URLs, voice names and subtitle availability." parent: MiniMax API nav_order: 1896 --- ## Retrieve the list of text-to-speech audio clips you have generated December 23, 2024 (November 16, 2026) --- This endpoint will return audio clips generated by * [POST speech/create](/docs/api-minimax-v1/post-minimax-speech-create) * [POST speech/create-mp3](/docs/api-minimax-v1/post-minimax-speech-create-mp3) > **https://api.useapi.net/v1/minimax/speech/?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `account` is optional when only one [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `page` and `page_size` are optional. Use them to retrieve the next page of data when the returned `has_more` field is `true`. Default `page_size` is 100. ##### Responses **200** **200 OK** ```json { "audio_list": [ { "audio_id": "user:user_id-minimax:account_id-audio:audio_id", "audio_review": 0, "user_id": "123456789012345678", "audio_title": "<Audio title>", "audio_url": "https://cdn.hailuoai.video/...mp3", "update_time": 1122334455780 }, { "audio_id": "user:user_id-minimax:account_id-audio:audio_id", "audio_review": 0, "user_id": "123456789012345678", "audio_title": "Audio title", "audio_url": "https://cdn.hailuoai.video/...mp3", "update_time": 1122334455779 } ], "total": 2025, "has_more": true } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **596** **596 Account Error** ```json { "error": "Your minimax account has pending error. Please address this issue at https://useapi.net/docs/api-minimax-v1/post-minimax-accounts-account before making any new API calls.", "code": 596 } ``` ##### Model A list of your speech clips, each with its `audio_id`, text, voice name and `audio_url`, plus `total` and `has_more`. <details markdown="block" class="model-details"> <summary>The list of speech clips, field by field</summary> ```typescript { // TypeScript, all fields are optional audio_list: { audio_id: string audio_review: number user_id: string // The MiniMax account id audio_title: string audio_url: string update_time: number text: string voice_name: string status: number async: number has_srt: boolean // Word timings are available for this recording has_wav: boolean // A WAV rendition exists alongside the MP3 }[] total: number has_more: boolean } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/minimax/speech/?account=account" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const account = "Previously configured account"; const apiUrl = `https://api.useapi.net/v1/minimax/speech/?account=${account}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" account = "Previously configured account" apiUrl = f"https://api.useapi.net/v1/minimax/speech/?account={account}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-minimax-v1/get-minimax-speech_audio_id === Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-speech_audio_id --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> speech/`audio_id` description: "Poll or retrieve one speech recording via GET speech/audioId in the useapi.net MiniMax API v1 — pending and failed states, credit cost, model, voice and applied effects." parent: MiniMax API nav_order: 1897 --- ## Retrieve text-to-speech audio clip December 23, 2024 (November 16, 2026) --- This endpoint will return audio clip generated by * [POST speech/create](/docs/api-minimax-v1/post-minimax-speech-create) * [POST speech/create-mp3](/docs/api-minimax-v1/post-minimax-speech-create-mp3) > **https://api.useapi.net/v1/minimax/speech/`audio_id`** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Path parameter - `audio_id` is **required**. Specify audio clip you want to retrieve. **Notes:** - Accepts an `audioId` returned by [POST speech/create](/docs/api-minimax-v1/post-minimax-speech-create) as well as any `audio_id` listed by [GET speech](/docs/api-minimax-v1/get-minimax-speech). - While a generation from [POST speech/create](/docs/api-minimax-v1/post-minimax-speech-create) is still running, the response is `{"statusLabel": "pending", "statusFinal": false}` with no `audio_url`. Poll until `statusFinal` is `true`, or supply a `replyUrl` and let the callback tell you. - A generation that never completed reports `statusLabel: "failed"` with `code` and `error` describing why. Cancelling one with [DELETE scheduler/`id`](/docs/api-minimax-v1/del-minimax-scheduler-videoId) puts it in the same state. - An `audioId` issued by [POST speech/create](/docs/api-minimax-v1/post-minimax-speech-create) resolves for 7 days. After that use [GET speech](/docs/api-minimax-v1/get-minimax-speech) to find the recording, which stays on the account. ##### Responses **200** **200 OK** ```json { "audio_id": "user:user_id-minimax:account_id-audio:audio_id", "audio_review": 0, "voice_info": { "voice_id": "209533299589184", "parent_voice_id": "0", "voice_name": "Calm Woman", "tag_list": [ "English", "Female", "Adult", "Audiobook", "US (General)" ], "file_id": "", "cover_url": "https://cdn.hailuoai.video/...png", "create_time": 1122334455667, "update_time": 1122334455668, "collected": false, "voice_status": 2, "sample_audio": "https://cdn.hailuoai.video/...mp3", "uniq_id": "English_CalmWoman", "group_id": "0" }, "text": "<Text>", "audio_url": "https://cdn.hailuoai.video/...mp3", "audio_title": "<Title>", "create_time": 1122334455667, "emotion": "Auto", "language_boost": "Auto", "speed": 1, "pitch": 0, "update_time": 0, "effects": { "deepen_lighten": 0, "stronger_softer": 0, "nasal_crisp": 0, "spacious_echo": true, "lofi_telephone": false, "robotic": false, "auditorium_echo": false }, "statusLabel": "completed", "statusFinal": true } ``` While the generation is still running: ```json { "audioId": "user:12345-minimax:123456789012345678-audio:178737039436895391", "status": 0, "statusLabel": "pending", "statusFinal": false } ``` And when it failed, or was still unfinished after the 10-minute tracking window: ```json { "audioId": "user:12345-minimax:123456789012345678-audio:178737039436895391", "status": 3, "statusLabel": "failed", "statusFinal": true, "code": 400, "error": "More than 10 minutes have passed, the task has expired." } ``` Poll on `statusFinal` rather than `status` — `statusLabel` and `statusFinal` are added by useapi.net, because every MiniMax history row reports `status` `0` whether or not it finished. **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** Returned with an empty body when MiniMax no longer holds the recording, for example once it has been deleted. **596** **596 Account Error** ```json { "error": "Your minimax account has pending error. Please address this issue at https://useapi.net/docs/api-minimax-v1/post-minimax-accounts-account before making any new API calls.", "code": 596 } ``` ##### Model The speech clip record: its text, voice, settings, `statusFinal` and, once complete, the audio in `audio_url`. <details markdown="block" class="model-details"> <summary>The speech clip record, field by field</summary> ```typescript { // TypeScript, all fields are optional audio_id: string audio_review: number voice_info: { voice_id: string parent_voice_id: string voice_name: string tag_list: string[] file_id: string cover_url: string create_time: number update_time: number collected: boolean voice_status: number sample_audio: string uniq_id: string group_id: string } text: string audio_url: string audio_title: string create_time: number emotion: string language_boost: string speed: number pitch: number volume: number update_time: number model: string // The speech model used cost_credit: number // Credits this generation cost is_first: boolean status: number statusLabel: string // completed once audio_url is set, otherwise processing statusFinal: boolean async: number has_srt: boolean has_wav: boolean effects: { deepen_lighten: number stronger_softer: number nasal_crisp: number spacious_echo: boolean lofi_telephone: boolean robotic: boolean auditorium_echo: boolean } } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/minimax/speech/audio_id" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const audio_id = "audio_id to retrieve"; const apiUrl = `https://api.useapi.net/v1/minimax/speech/${audio_id}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" audio_id = "audio_id to retrieve" apiUrl = f"https://api.useapi.net/v1/minimax/speech/{audio_id}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-minimax-v1/get-minimax-videos-agent-templates === Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-videos-agent-templates --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> videos/agent-templates description: "List available agent video templates via GET videos/agent-templates in the useapi.net MiniMax API v1 for use with POST videos/agent-create." parent: MiniMax API nav_order: 701 --- ## Retrieve available agent video templates June 30, 2025 (November 16, 2026) --- Use [hailuoai.video](https://hailuoai.video) account to retrieve available agent video templates, see [Setup MiniMax](/docs/start-here/setup-minimax) for details. Templates can be used with [POST videos/agent-create](/docs/api-minimax-v1/post-minimax-videos-agent-create) to generate videos. > **https://api.useapi.net/v1/minimax/videos/agent-templates/?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `account` is optional when only one [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `templateId` is optional, specify a template ID to get detailed information for a specific template including input requirements. - `limit` is optional, specify the number of templates to return. Default 30. - `lastId` is optional, specify the template id from where to start pagination. ##### Responses **200** **200 OK** **Template List Response** (when `templateId` is not provided): ```json { "videoList": [ { "id": "1122334455667788", "createTime": 1702953600000, "videoAsset": { "id": "video_asset_id", "desc": "Template description", "coverURL": "https://example.com/cover.jpg", "videoURL": "https://example.com/video.mp4", "status": 2, "width": 1280, "height": 720, "duration": 10, "resolution": 1, "title": "Template Title", "agentTemplateID": "1122334455667788", "agentTemplateName": "Template Name", "downloadURL": "https://example.com/download.mp4", "hasVoice": true, "modelID": "model_123", "useOriginPrompt": false, "isBookmarked": false, "disableGenerateSimilar": false, "postStatus": 1, "userID": 123456, "createType": 1, "promptImgURL": "https://example.com/prompt.jpg", "aspectRatio": "16:9", "tags": [ { "type": "style", "tagIcon": "https://example.com/icon.png", "tagText": "Cinematic" } ], "humanCheckStatus": 1, "userIDStr": "123456" }, "like": { "likes": 42, "likeStatus": 0 }, "author": { "userID": "user123", "name": "Author Name", "avatar": "https://example.com/avatar.jpg" }, "cardType": 1, "tabID": "template" } ], "hasPre": false, "hasNext": true } ``` **Template Details Response** (when `templateId` is provided): ```json { "id": "1122334455667788", "createTime": 1702953600000, "videoAsset": { "id": "video_asset_id", "desc": "Template description", "coverURL": "https://example.com/cover.jpg", "videoURL": "https://example.com/video.mp4", "status": 2, "width": 1280, "height": 720, "duration": 10, "resolution": 1, "title": "Template Title", "agentTemplateID": "1122334455667788", "agentTemplateName": "Template Name" }, "like": { "likes": 42, "likeStatus": 0 }, "author": { "userID": "user123", "name": "Author Name", "avatar": "https://example.com/avatar.jpg" }, "cardType": 1, "tabID": "template", "credits": 100, "requirePrompt": true, "requireImage": true, "prompt": "Template prompt", "inputs": [ { "name": "text_input", "type": "text", }, { "name": "image_input", "type": "image", } ] } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** ```json { "error": "The video or template you are trying to use does not exist or has been deleted." } ``` ##### Model The list of agent video templates, or, when `templateId` is given, one template's details with its credits and required inputs. <details markdown="block" class="model-details"> <summary>The template list and a single template's details, field by field</summary> ```typescript { // TypeScript, template list response videoList: { id: string createTime: number videoAsset: { id: string desc: string coverURL: string videoURL: string status: number width: number height: number duration: number resolution: number title: string agentTemplateID: string agentTemplateName: string downloadURL?: string hasVoice?: boolean modelID?: string useOriginPrompt?: boolean isBookmarked?: boolean disableGenerateSimilar?: boolean postStatus?: number userID?: number createType?: number promptImgURL?: string aspectRatio?: string tags?: { type: string tagIcon: string tagText: string }[] humanCheckStatus?: number userIDStr?: string } like: { likes: number likeStatus: number } author: { userID: string name: string avatar: string } cardType: number tabID: string }[] hasPre: boolean hasNext: boolean } { // TypeScript, template details response (when templateId provided) id: string createTime: number videoAsset: {} // Same structure as above like: {} // Same structure as above author: {} // Same structure as above cardType: number tabID: string credits: number requirePrompt: boolean requireImage: boolean prompt: string inputs: { name: string type: "text" | "image" }[] } ``` </details> ##### Examples **Curl** ``` bash # Get list of templates curl "https://api.useapi.net/v1/minimax/videos/agent-templates/?account=account&limit=10" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" # Get specific template details curl "https://api.useapi.net/v1/minimax/videos/agent-templates/?templateId=1122334455667788" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript // Get list of templates const token = "API token"; const account = "Previously configured account"; const apiUrl = `https://api.useapi.net/v1/minimax/videos/agent-templates/?account=${account}&limit=10`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("Templates:", {response, result}); // Get specific template details const templateId = "1122334455667788"; const detailUrl = `https://api.useapi.net/v1/minimax/videos/agent-templates/?templateId=${templateId}`; const detailResponse = await fetch(detailUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const templateDetails = await detailResponse.json(); console.log("Template details:", {detailResponse, templateDetails}); ``` **Python** ``` python import requests # Get list of templates token = "API token" account = "Previously configured account" apiUrl = f"https://api.useapi.net/v1/minimax/videos/agent-templates/?account={account}&limit=10" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print("Templates:", response, response.json()) # Get specific template details template_id = "1122334455667788" detail_url = f"https://api.useapi.net/v1/minimax/videos/agent-templates/?templateId={template_id}" detail_response = requests.get(detail_url, headers=headers) print("Template details:", detail_response, detail_response.json()) ``` === URL: https://useapi.net/docs/api-minimax-v1/get-minimax-videos-characters === Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-videos-characters --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> videos/characters description: "List your saved Subject Reference characters via GET videos/characters in the useapi.net MiniMax API v1 — the same roster shown in the Hailuo 'My Characters' panel." parent: MiniMax API nav_order: 800 --- ## Retrieve the list of characters January 9, 2025 (November 16, 2026) --- Use [hailuoai.video](https://hailuoai.video) account to retrieve list of generated videos, see [Setup MiniMax](/docs/start-here/setup-minimax) for details. This endpoint returns a list of previously created characters, the same list you see when navigating to Subject Reference » Add Reference Character » My Characters. > **https://api.useapi.net/v1/minimax/videos/characters/?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `account` is optional when only one [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `page` is optional, specify the page number. Default 1. - `pageSize` is optional, specify number of items to return. Default 50. ##### Responses **200** **200 OK** Field `cdnUrl` contains a link to the originally uploaded file. Field `promptImgUrl` contains a link to the detected character face from the file mentioned above. ```json [ { "characterID": "1234567890", "characterType": 1, "file": { "fileID": "user:user_id-minimax:account-file:file_id", "cdnUrl": "https://cdn.hailuoai.video/...jpeg", "promptImgUrl": "https://cdn.hailuoai.video/..." } } ] ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model An array of your characters, each with its `characterID` and the uploaded file's id and image links. <details markdown="block" class="model-details"> <summary>The list of characters, field by field</summary> ```typescript { // TypeScript, all fields are optional characterID: string characterType: number file: { fileID: string cdnUrl: string promptImgUrl: string } }[] ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/minimax/videos/characters/?account=account" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const account = "Previously configured account"; const apiUrl = `https://api.useapi.net/v1/minimax/videos/characters/?account=${account}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" account = "Previously configured account" apiUrl = f"https://api.useapi.net/v1/minimax/videos/characters/?account={account}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-minimax-v1/get-minimax-videos-videoId === Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-videos-videoId --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> videos/`videoId` description: "Poll the status and retrieve results of a video generation by videoId via GET videos/videoId in the useapi.net MiniMax API v1." parent: MiniMax API nav_order: 600 --- ## Retrieve video September 25, 2024 (November 16, 2026) --- Use this endpoint to retrieve status and results of * [videos/create](/docs/api-minimax-v1/post-minimax-videos-create) > **https://api.useapi.net/v1/minimax/videos/`videoId`** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Path parameter - `videoId` is **required**. Specify the videoId you want to retrieve. ##### Responses **200** **200 OK** ```json { "id": "id", "desc": "<prompt>", "coverURL": "<cover url>", "videoURL": "<generated video with watermark url>", "downloadURL": "<generated video without watermark (paid accounts) url>", "status": 2, "statusLabel": "completed", "statusFinal": true, "percent": 100, "width": 1300, "height": 760, "originFiles": [ { "id": "user:user_id-minimax:account-file:file_id", "url": "<file url>", "type": "png" } ], "canAppeal": false, "canRetry": false, "videoId": "user:user_id-minimax:account-video:id" } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** This most often means that the video was moderated and removed after it was generated. ```json { "error": "Not found.", "code": 404 } ``` ##### Model The video record, with its numeric `status`, `statusFinal`, progress while it runs, and its video and download URLs. <details markdown="block" class="model-details"> <summary>The video record and its <code>status</code> values, field by field</summary> Known `status` values: * **0** pending * **1** processing * **2** completed * **3** failed * **5** moderated * **7** moderated * **11** queued * **12** processing * **14** moderated * **16** moderated (input reference rejected, e.g. Seedance "Face Detected") Optional fields `message` and `percent` will contain generation progress information. ```typescript { // TypeScript, all fields are optional id: string desc: string coverURL: string videoURL: string downloadURL: string status: number statusLabel: string statusFinal: boolean message: string // Contains the message shown to the user while the video is being processed percent: number // Contains 0-100 percent while the video is being processed width: number height: number originFiles: { id: string url: string type: string }[] canAppeal: boolean canRetry: boolean videoId: string } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/minimax/videos/videoId" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const videoId = "videoId to retrieve"; const apiUrl = `https://api.useapi.net/v1/minimax/videos/${videoId}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" videoId = "videoId to retrieve" apiUrl = f"https://api.useapi.net/v1/minimax/videos/{videoId}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-minimax-v1/get-minimax-videos === Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-videos --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> videos description: "List all videos you have generated via GET videos in the useapi.net MiniMax API v1 — paginated with limit and lastVideoId cursor parameters." parent: MiniMax API nav_order: 700 --- ## Retrieve the list of videos you have generated September 25, 2024 (November 16, 2026) --- Use [hailuoai.video](https://hailuoai.video) account to retrieve list of generated videos, see [Setup MiniMax](/docs/start-here/setup-minimax) for details. > **https://api.useapi.net/v1/minimax/videos/?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `account` is optional when only one [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `limit` is optional, specify the number of videos to return. Default 30. - `lastVideoId` is optional, specify the video id from where to start. ##### Responses **200** **200 OK** ```json [ { "id": "video_id_#1", "desc": "", "coverURL": "", "videoURL": "", "status": 1, "statusLabel": "processing", "statusFinal": false, "message": "<Message from chairman Xi>", "width": 0, "height": 0, "originFiles": [], "canAppeal": false, "canRetry": false, "videoId": "user:user_id-minimax:account-video:video_id_#1" }, { "id": "video_id_#2", "desc": "<prompt>", "coverURL": "<cover url>", "videoURL": "<generated video with watermark url>", "downloadURL": "<generated video without watermark (paid accounts) url>", "status": 2, "statusLabel": "completed", "statusFinal": true, "width": 1300, "height": 760, "originFiles": [ { "id": "user:user_id-minimax:account-file:file_id", "url": "<file url>", "type": "png" } ], "canAppeal": false, "canRetry": false, "videoId": "user:user_id-minimax:account-video:video_id_#2" } ] ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model An array of your generated videos, each with its `videoId`, numeric `status`, `statusFinal` and video and download URLs. <details markdown="block" class="model-details"> <summary>The list of videos and their <code>status</code> values, field by field</summary> Known `status` values: * **0** pending * **1** processing * **2** completed * **3** failed * **5** moderated * **7** moderated * **11** queued * **12** processing * **14** moderated ```typescript { // TypeScript, all fields are optional id: string desc: string coverURL: string videoURL: string downloadURL: string status: number statusLabel: string statusFinal: boolean message: string, width: number height: number originFiles: { id: string url: string type: string }[] canAppeal: boolean canRetry: boolean videoId: string }[] ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/minimax/videos/?account=account" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const account = "Previously configured account"; const apiUrl = `https://api.useapi.net/v1/minimax/videos/?account=${account}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" account = "Previously configured account" apiUrl = f"https://api.useapi.net/v1/minimax/videos/?account={account}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-minimax-v1/mcp === Document URL: https://useapi.net/docs/api-minimax-v1/mcp --- layout: default title: MCP Server nav_icon: mcp seo_title: "MiniMax MCP Server: Hailuo 3.0 Video, Images, Music and Speech" description: "Connect the Claude app, ChatGPT, Claude Code or any MCP client to the hosted useapi.net MiniMax MCP server: 38 tools for Hailuo video, images, music and speech." parent: MiniMax API nav_order: 50 permalink: /docs/api-minimax-v1/mcp --- ## MiniMax MCP Server November 20, 2026 --- The useapi.net MiniMax MCP server lets an AI assistant such as the Claude app, ChatGPT, Claude Code, Cursor or VS Code Copilot make videos, images, songs and speech with [Hailuo AI](https://hailuoai.video) and [MiniMax Audio](https://www.minimax.io/audio) on your own MiniMax accounts. It is a hosted [Model Context Protocol](https://modelcontextprotocol.io) server with 38 tools: generate Hailuo, Veo 3.1 and Seedance 2.0 videos from text, frames or omni references, or from a Hailuo AI video template, generate MiniMax H3 Image, Nano Banana, GPT Image, Seedream and Midjourney images, hand a task to the MiniMax agent, make songs and covers, turn text into speech in built-in or cloned voices, upload your own files and clean up your history. Each tool calls the [MiniMax API](/docs/api-minimax-v1), so the same rules and limits apply. Nothing needs to be installed or hosted. **Is there a MiniMax MCP server?** Yes. useapi.net, a third-party service not affiliated with MiniMax, hosts one at `https://api.useapi.net/v1/minimax/mcp` with 38 tools for Hailuo video, images, music and speech on your own Hailuo AI and MiniMax Audio subscriptions, nothing to install. MiniMax's own MCP server has 8 tools, needs a developer API key at pay-as-you-go prices and has no tools for songs, covers, Veo, Seedance, templates or the agent ([comparison](#useapinet-vs-minimaxs-own-mcp-server)). Prefer REST? Code: [github.com/useapi/minimax-api](https://github.com/useapi/minimax-api) See all useapi.net MCP servers on [Model Matrix & MCP](/model-matrix#mcp-servers). ## useapi.net vs MiniMax's own MCP server MiniMax also publishes its own [MiniMax-MCP](https://github.com/MiniMax-AI/MiniMax-MCP) server with 8 tools for speech, voices, Hailuo video and MiniMax images. You install and run it yourself with a MiniMax developer API key, billed at [developer platform prices](/docs/api-minimax-v1#pricing). The useapi.net server is hosted and works on your Hailuo AI and MiniMax Audio subscriptions (as of November 20, 2026): | | useapi.net MiniMax MCP | MiniMax's own MCP | |---|---|---| | Nothing to install, connects in the Claude app and ChatGPT | Yes | No, you run it with `uvx` or host it yourself | | Billed on your Hailuo AI and MiniMax Audio subscriptions | Yes | No, a developer API key at pay-as-you-go prices | | Songs, and covers of a reference track | Yes | No | | Veo 3.1 and Seedance 2.0 videos besides Hailuo | Yes | No, Hailuo only | | Nano Banana, GPT Image, Seedream and Midjourney images besides MiniMax H3 | Yes | No, MiniMax H3 Image and image-01 only | | Hailuo AI video templates and the MiniMax agent | Yes | No | | List and delete your videos, images, songs, speech and uploads | Yes | No | | Several MiniMax accounts in one connection | Yes | One API key per server | useapi.net is a third-party service, not affiliated with MiniMax. ## Endpoint and authorization ``` https://api.useapi.net/v1/minimax/mcp ``` - Transport: Streamable HTTP. - Listed in the [official MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers/net.useapi%2Fminimax/versions/latest) as `net.useapi/minimax`, so MCP clients and directories that read the registry can find it by that name. - Authorization: your useapi.net API token in the `Authorization: Bearer …` header, see [Setup useapi.net](/docs/start-here/setup-useapi). The Claude app and ChatGPT sign in with OAuth instead, see [Use it in the Claude app or ChatGPT](#use-it-in-the-claude-app-or-chatgpt). - You need at least one MiniMax account added with [Setup MiniMax](/docs/start-here/setup-minimax). Adding and removing accounts is not available over MCP: use [POST accounts](/docs/api-minimax-v1/post-minimax-accounts-account) or the setup page. ## Setup Replace `YOUR_API_TOKEN` with your useapi.net API token. ### Claude Code ```bash claude mcp add --transport http useapi-minimax https://api.useapi.net/v1/minimax/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` ### Cursor In `~/.cursor/mcp.json`: ```json { "mcpServers": { "useapi-minimax": { "url": "https://api.useapi.net/v1/minimax/mcp", "headers": { "Authorization": "Bearer YOUR_API_TOKEN" } } } } ``` ### VS Code In `.vscode/mcp.json`: ```json { "servers": { "useapi-minimax": { "type": "http", "url": "https://api.useapi.net/v1/minimax/mcp", "headers": { "Authorization": "Bearer YOUR_API_TOKEN" } } } } ``` ### Windsurf and other clients Any client that supports remote MCP servers over HTTP with custom headers works. The usual JSON shape: ```json { "mcpServers": { "useapi-minimax": { "serverUrl": "https://api.useapi.net/v1/minimax/mcp", "headers": { "Authorization": "Bearer YOUR_API_TOKEN" } } } } ``` Some clients name the address field `url` instead of `serverUrl`. ### Test it with curl ```bash curl -s https://api.useapi.net/v1/minimax/mcp \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}' curl -s https://api.useapi.net/v1/minimax/mcp \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' ``` The first call answers with the server's name `useapi-minimax` and its instructions for the assistant, the second with the 38 tools. ## Use it in the Claude app or ChatGPT The Claude app ([claude.ai](https://claude.ai) and Claude Desktop) and [ChatGPT](https://chatgpt.com) can add this server as a custom connector. They sign in with OAuth: you give the app the URL, it opens a useapi.net page, and you paste your useapi.net API token there once. Both work on their Free plans. The API-token setups above for Claude Code, Cursor, VS Code and other clients keep working as before. ``` ``` ### Claude app 1. Open Settings → Connectors and click Add custom connector. 2. Enter a name, for example `useapi `, and the URL above, then click Add. 3. Click Connect. Claude opens the useapi.net sign-in page. 4. Paste your useapi.net API token and click Allow. Claude asks before each tool call unless you choose Always allow. The Free plan allows one custom connector. ### ChatGPT 1. Open Plugins, click Add and choose Add custom MCP server. 2. Enter a name and the URL above, and set Authentication to OAuth. 3. Tick ChatGPT's "I understand and want to continue" box, then click Create as a plugin. 4. Click Connect. ChatGPT opens the useapi.net sign-in page. 5. Paste your useapi.net API token and click Allow. ChatGPT asks you to confirm each tool call that creates or changes something. The Free plan works without developer mode (as of October 25, 2026). ### How the sign-in works - Your API token is in your welcome email, see [Setup useapi.net](/docs/start-here/setup-useapi). The useapi.net page links there too. - Each connection is for one MCP server. Connect each server you want to use on its own. - The app gets an access token that lasts 1 hour and renews it on its own. A connection you don't use for 90 days lapses, and you connect again. - [Resetting your API token](/docs/account-management/post-account-token-reset) disconnects every app connected with it. - - Results come back as public links, so they open right in the app. ## Tools Accounts are named by their account id, as `minimax_list_accounts` shows it. Every id a tool returns (`videoId`, `imageId`, `fileID`, `musicId`, `audioId`, `voice_id`) names its account, so a tool that works on one runs on that account. Without `account`, a video goes to one of your accounts with a free slot and a song to the account with the fewest songs running. Images, speech, the agent, uploads and the tools that read one account's lists need `account` only when more than one account is added. Every create tool also takes `wait`, and a webhook with `replyUrl` and `replyRef`. ### Accounts and credits | Tool | What it does | Main parameters | |---|---|---| | `minimax_list_accounts` | Lists your accounts as stored: account id, host, `maxJobs`, the features each one supports (video, audio, music, agent), session expiry and any stored account error, without calling MiniMax. | | | `minimax_get_account` | One account's stored settings: host, `maxJobs`, supported features, session times and the stored error if MiniMax put it on hold, without calling MiniMax. | `account` | | `minimax_get_features` | Reads an account live from MiniMax: its video and image credits, plan and per-model settings, plus the separate MiniMax Audio credits for music and speech. | `account` | The parameters match [GET accounts](/docs/api-minimax-v1/get-minimax-accounts), [GET accounts/account](/docs/api-minimax-v1/get-minimax-accounts-account) and [GET features](/docs/api-minimax-v1/get-minimax-features). ### Uploads, files and characters | Tool | What it does | Main parameters | |---|---|---| | `minimax_upload_file` | Uploads your own image (PNG, JPEG or WebP), audio (MP3 or WAV) or MP4 video, up to 50 MB, from a public https URL or sent as `contentBase64`, as a reference for videos, images and template videos. Returns a `fileID` that works on that account only, and its `ossPath`. | `url` or `contentBase64`, `mimeType`, `account` | | `minimax_list_files` | Lists the files uploaded to one account, here, through the REST API or in the MiniMax web app, with each `file_id`, name, type, CDN URL and `oss_path`. | `account`, `limit` | | `minimax_delete_file` | Deletes one uploaded file. Generations that already used it are not affected. It cannot be undone. | `fileID` | | `minimax_list_characters` | Lists the characters saved on one Hailuo AI account, with each character image's `fileID` for `minimax_create_video` (such as the S2V-01 subject) or `minimax_create_template_video`, page by page. | `account`, `page`, `pageSize` | The parameters match [POST files](/docs/api-minimax-v1/post-minimax-files), [GET files](/docs/api-minimax-v1/get-minimax-files), [DEL files/fileID](/docs/api-minimax-v1/del-minimax-files-fileID) and [GET videos/characters](/docs/api-minimax-v1/get-minimax-videos-characters). Files larger than 50 MB, up to 5 GB, go to POST files directly. ### Videos | Tool | What it does | Main parameters | |---|---|---| | `minimax_create_video` | Generates a video with Hailuo 3.0, 2.3, 02 or 01, Veo 3.1 or Seedance 2.0: from text, a first frame, an end frame, subject images on the S2V models, or omni references cited in the prompt as `@Image1`, `@Video1` or `@Audio1` on Seedance and Hailuo 3.0. Hailuo 02, Hailuo 2.3 and Veo set size and length with `options`, Seedance and Hailuo 3.0 with `resolution` and `duration`. | `prompt`, `model`, `options`, `resolution`, `duration`, `aspectRatio`, `fileID`, `end_frame_fileID`, `fileID2` to `fileID14`, `videoFileID1` to `videoFileID3`, `audioFileID1` to `audioFileID3`, `account`, `maxJobs` | | `minimax_get_video` | Reads one video, and with `wait: true` waits for it to finish. A finished video comes with its `videoURL`, a `downloadURL` without watermark on paid accounts, its cover, width and height. A 404 usually means the video was moderated and removed. | `videoId`, `wait` | | `minimax_list_videos` | Lists one account's videos on Hailuo AI, including running ones and those made in the web app, page by page. | `account`, `limit`, `lastVideoId` | | `minimax_cancel_video` | Asks MiniMax to cancel a video that is still generating. `minimax_get_video` then shows its final status. It cannot be undone. | `videoId` | | `minimax_delete_video` | Deletes one video from its account's Hailuo AI history. It cannot be undone. | `videoId` | The parameters match [POST videos/create](/docs/api-minimax-v1/post-minimax-videos-create), [GET videos/videoId](/docs/api-minimax-v1/get-minimax-videos-videoId), [GET videos](/docs/api-minimax-v1/get-minimax-videos), [POST videos/cancel](/docs/api-minimax-v1/post-minimax-videos-cancel) and [DEL videos/videoId](/docs/api-minimax-v1/del-minimax-videos-videoId), with the same names for the numbered references. Durations, resolutions and ratios of each model are on POST videos/create. ### Images | Tool | What it does | Main parameters | |---|---|---| | `minimax_create_image` | Generates 1 to 4 images with MiniMax H3 Image, image-01, Nano Banana, GPT Image, Seedream or Midjourney (always 4), from a prompt and up to 16 reference images cited as `@Image1` on the models that support it, or a character image on image-01. The first image comes back as an image the assistant can see. | `prompt`, `model`, `aspectRatio`, `resolution`, `quality`, `quantity`, `referenceFileId1` to `referenceFileId16`, `characterFileId`, `account` | | `minimax_get_image` | Reads one image, and with `wait: true` waits for it to finish. A finished image comes with its URL, a `downloadURL` without watermark on paid accounts, its size and a `fileID` to reuse as a reference, and as an image block. | `imageId`, `wait` | | `minimax_list_images` | Lists one account's images on Hailuo AI, including running ones and those made in the web app, page by page. Deleted images are not listed. | `account`, `limit`, `lastImageId` | | `minimax_delete_image` | Deletes one image from its account's Hailuo AI history. It leaves the list, but `minimax_get_image` can still read it. It cannot be undone. | `imageId` | The parameters match [POST images/create](/docs/api-minimax-v1/post-minimax-images-create), [GET images/imageId](/docs/api-minimax-v1/get-minimax-images-imageId), [GET images](/docs/api-minimax-v1/get-minimax-images) and [DEL images/imageId](/docs/api-minimax-v1/del-minimax-images-imageId). ### Template videos and the agent | Tool | What it does | Main parameters | |---|---|---| | `minimax_list_agent_templates` | Lists the Hailuo AI video templates with each one's id, title and preview, page by page. With `templateId`, one template's credits and the prompt or image it requires. | `templateId`, `limit`, `lastId`, `account` | | `minimax_create_template_video` | Generates a video from a template, with the prompt or image the template requires. It returns a `videoId` for `minimax_get_video`. | `templateId`, `prompt`, `fileID`, `ossPath`, `account`, `maxJobs` | | `minimax_run_agent` | Gives the Hailuo AI agent a task in plain words and the models it may use, such as Hailuo 2.3, Veo 3.1, Nano Banana 2 or Midjourney V7, with up to 3 reference files by public URL. The agent picks among them and returns the files it made. | `prompt`, `models`, `fileUrls`, `account` | | `minimax_get_agent_job` | Reads one agent job, and with `wait: true` waits for it to finish. A finished job comes with each file the agent made. Jobs are kept 31 days. | `jobId`, `wait` | | `minimax_list_agent_jobs` | Lists the agent jobs running now, by account, and the accounts that can run the agent. | | The parameters match [GET videos/agent-templates](/docs/api-minimax-v1/get-minimax-videos-agent-templates), [POST videos/agent-create](/docs/api-minimax-v1/post-minimax-videos-agent-create), [POST agent](/docs/api-minimax-v1/post-minimax-agent), [GET agent/jobId](/docs/api-minimax-v1/get-minimax-agent-jobId) and [GET agent/jobs](/docs/api-minimax-v1/get-minimax-agent-jobs). ### Music | Tool | What it does | Main parameters | |---|---|---| | `minimax_create_music` | Generates 1 to 3 songs with MiniMax Music 3.0 or 2.6 from a style prompt, your own lyrics or a reference track (a cover). Without lyrics the model writes them, and `instrumental: true` makes a song without vocals. | `prompt`, `lyrics`, `title`, `model`, `quantity`, `instrumental`, `referenceMusicId`, `account` | | `minimax_upload_music_reference` | Uploads an MP3 or WAV of up to 50 MB as a reference track for covers. Returns its `musicId`, ready at once, and the lyrics MiniMax transcribed from it. A reference stays on the account for any number of covers, and uploading it costs no credits. | `url` or `contentBase64`, `mimeType`, `name`, `account` | | `minimax_get_music` | Reads one song or reference, and with `wait: true` waits for a song to finish. A finished song comes with its MP3 `audio_url`, duration, title, lyrics and model. | `musicId`, `wait` | | `minimax_list_music` | Lists one account's songs, references or both, including songs made on minimax.io and tracks still rendering, page by page. | `account`, `type`, `limit`, `lastMusicId`, `favorite` | | `minimax_delete_music` | Deletes one song or reference track. Its `audio_url` stops working, so download it first. A song still rendering cannot be deleted. It cannot be undone. | `musicId` | The parameters match [POST music/create](/docs/api-minimax-v1/post-minimax-music-create), [POST music/reference](/docs/api-minimax-v1/post-minimax-music-reference), [GET music/musicId](/docs/api-minimax-v1/get-minimax-music-musicId), [GET music](/docs/api-minimax-v1/get-minimax-music) and [DELETE music/musicId](/docs/api-minimax-v1/del-minimax-music-musicId). ### Speech and voices | Tool | What it does | Main parameters | |---|---|---| | `minimax_create_speech` | Turns text into speech with MiniMax Speech 2.8 HD (the default) or another Speech 2.8, 2.6, 2.5, 02 or 01 model, HD or Turbo, up to 5,000 characters on HD models and 10,000 on Turbo, in a built-in or cloned voice, with speed, volume, pitch, emotion and voice effects. | `text`, `voice_id`, `model`, `speed`, `vol`, `pitch`, `emotion`, `language_boost`, `account` | | `minimax_get_speech` | Reads one recording, and with `wait: true` waits for it to finish. A finished one comes with its MP3 `audio_url`, text, model, voice, settings and the credits MiniMax charged. An `audioId` from `minimax_create_speech` resolves for 7 days. | `audio_id`, `wait` | | `minimax_list_speech` | Lists one account's recordings, made here or on minimax.io, page by page. | `account`, `page`, `page_size` | | `minimax_delete_speech` | Deletes one recording. One still generating cannot be deleted. It cannot be undone. | `audio_id` | | `minimax_list_voices` | Lists MiniMax's built-in voices, filtered by tags and page by page, or your cloned voices, each with its `voice_id` and a sample. | `account`, `is_system`, `tag_list`, `page`, `page_size` | | `minimax_get_speech_config` | Lists the values speech accepts on an account: the emotions, and the voice tags by language, gender, age and accent. | `account` | | `minimax_get_voice_quota` | Shows how many cloned voice slots an account has, how many are in use and the free clone previews left. | `account` | | `minimax_upload_voice_sample` | Uploads one MP3 or WAV sample of 10 to 60 seconds of speech, up to 50 MB, for voice cloning. Returns a `fileID` for `minimax_clone_voice`. | `url` or `contentBase64`, `mimeType`, `account` | | `minimax_clone_voice` | Builds a new voice from 1 to 10 samples of the same account and returns its `voice_id` and a sample. It takes a cloned voice slot. | `files`, `voice_name`, `language_tag`, `need_noise_reduction` | | `minimax_delete_voice` | Deletes one cloned voice and frees its slot. It cannot be undone. | `voice_id` | The parameters match [POST speech/create](/docs/api-minimax-v1/post-minimax-speech-create), [GET speech/audio_id](/docs/api-minimax-v1/get-minimax-speech_audio_id), [GET speech](/docs/api-minimax-v1/get-minimax-speech), [DEL speech/audio_id](/docs/api-minimax-v1/del-minimax-speech-audio_id), [GET speech/voices](/docs/api-minimax-v1/get-minimax-speech-voices), [GET speech/config](/docs/api-minimax-v1/get-minimax-speech-config), [GET speech/equity](/docs/api-minimax-v1/get-minimax-speech-equity), [POST speech/upload-sample](/docs/api-minimax-v1/post-minimax-speech-upload-sample), [POST speech/clone-voice](/docs/api-minimax-v1/post-minimax-speech-clone-voice) and [POST speech/delete-voice](/docs/api-minimax-v1/post-minimax-speech-delete-voice). Speech streamed over a [WebSocket](/docs/api-minimax-v1/wss-minimax-speech-wss) or as [server-sent events](/docs/api-minimax-v1/post-minimax-speech-create-stream) stays on the REST API. ### Running jobs | Tool | What it does | Main parameters | |---|---|---| | `minimax_list_running_jobs` | Lists the videos, images, music and speech the API is tracking now, and the accounts with a free video slot (`maxJobs`, running and free). | | | `minimax_stop_tracking` | Stops tracking a running video, image, music or speech job and frees its slot on the account. It does not cancel the work at MiniMax: use `minimax_cancel_video` for that. It cannot be undone. | `id` | The parameters match [GET scheduler](/docs/api-minimax-v1/get-minimax-scheduler), [GET scheduler/available](/docs/api-minimax-v1/get-minimax-scheduler-available) and [DEL scheduler/id](/docs/api-minimax-v1/del-minimax-scheduler-videoId). The full input schema of every tool comes from `tools/list`. ## Long-running work MCP clients usually give up on a tool call after about a minute, so a tool waits up to about 50 seconds: - A quick result can come back from the create tool itself. - Otherwise the tool returns the id, and the matching get tool (`minimax_get_video`, `minimax_get_image`, `minimax_get_agent_job`, `minimax_get_music` or `minimax_get_speech`) with `wait: true` picks it up. Ask the assistant to keep checking until it is done. - `wait: false` on a create tool returns the id at once. Clients that ask for progress notifications get one about every 10 seconds while a tool waits. Videos, images, songs and speech come back as MiniMax CDN links. ## Example prompts - "Make a 6-second Hailuo 2.3 video at 768p of a paper boat drifting down a rainy street at night." - "Upload this photo and make a 10-second Hailuo 3.0 video in 2K where @Image1 walks along a beach at sunset." - "Generate Midjourney V7 images of a cozy mountain cabin in winter." - "Show me a few Hailuo video templates, then make one with my photo." - "Write an upbeat synth-pop song about a summer road trip with Music 3.0." - "Upload this MP3 and make a cover of it that keeps its lyrics." - "Clone my voice from these two recordings, then read this paragraph with it." - "How many video and audio credits are left on my MiniMax account?" ## Limits and notes - The tools use your MiniMax accounts and the same rules as the REST API, such as `maxJobs` and one song at a time per account, songs started on minimax.io included. Videos and images use the account's Hailuo AI credits, songs and speech the separate MiniMax Audio credits, see [Pricing](/docs/api-minimax-v1#pricing), and `minimax_get_features` shows both. - A 412 means the account lacks the credits for that job. A 429 means your accounts are busy or MiniMax's own queue is full: check `minimax_list_running_jobs` and retry later. A 596 means MiniMax put the account on hold. - A client may send up to 20 JSON-RPC requests in one batch. - If the client sends an `MCP-Protocol-Version` header, it must be one of the supported versions: `2025-11-25`, `2025-06-18`, `2025-03-26` or `2024-11-05`. === URL: https://useapi.net/docs/api-minimax-v1/post-minimax-accounts-account === Document URL: https://useapi.net/docs/api-minimax-v1/post-minimax-accounts-account --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> accounts description: "Create or update a MiniMax account configuration via POST accounts in the useapi.net MiniMax API v1 to enable multi-account load balancing." parent: MiniMax API nav_order: 300 --- ## Create or update MiniMax API account configuration September 25, 2024 (November 16, 2026) --- See [Setup MiniMax](/docs/start-here/setup-minimax) for details. For your convenience, you can specify your MiniMax configuration values under your account. If you specify multiple MiniMax accounts, the API will automatically perform load balancing by randomly selecting an account with available capacity before making calls to MiniMax. > **https://api.useapi.net/v1/minimax/accounts** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "url": "MiniMax url", "token": "MiniMax token", "maxJobs": 1-10, } ``` - `url` and `token` are **required**. Please see [Setup MiniMax](/docs/start-here/setup-minimax) for details. - `maxJobs` is **required**. Currently, it should be between 1 and 10. It applies to video and image generations. Music concurrency is not configurable here — MiniMax enforces its own limit and the API surfaces it, see [POST music/create](/docs/api-minimax-v1/post-minimax-music-create). For **video** accounts, please set this number according to your [subscription](https://hailuoai.video/subscribe) plan. We recommend setting it to **2** (3 maximum) for Free, and **3** (4 maximum) for Standard and Unlimited plans. Although you can set it to higher values (3 for Free and 5 for Standard and Unlimited respectively), it won't make any difference since only one video can be processed at a time for Free accounts, and no more than two for Standard and Unlimited accounts. It's helpful to have a spare empty slot for cases where the MiniMax website is too busy and responds with `502` or `504` while still accepting jobs into the internal queue. ##### Responses **201** **201 Created** ```json { "account": "123456", "jwt": { "token": "abc…secured…xyz", "user": { "deviceID": "123456789", "id": "123456", "isAnonymous": true, "name": "<name>", "avatar": "<url>" }, "exp": 1734858598.864, "iat": 1732266598.864, "host": "hailuoai.video", "searchParams": "device_platform=web&app_id=3001&version_code=22201&uuid=b5df53d1-4c0d-4c77-8422-87e3f3b1a1d6&device_id=123456789&os_name=Windows&browser_name=chrome&device_memory=8&cpu_core_num=4&browser_language=en-US&browser_platform=Win32&screen_width=1920&screen_height=1080&unix=1732266598000", "iat_Issued": "2024-01-01T00:00:00.000Z", "exp_Expire": "2024-12-01T00:00:00.000Z" }, "maxJobs": 1, "supportVideo": true, "supportChat": true, "supportAudio": true } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "Wrong username/password combination.", "This account has been suspended." "code": 401 } ``` ##### Model The saved configuration, in the same shape as [GET /accounts/`account`](/docs/api-minimax-v1/get-minimax-accounts-account): token details, `maxJobs` and supported features. <details markdown="block" class="model-details"> <summary>The saved account configuration, field by field</summary> ```typescript { // TypeScript, all fields are optional account: string jwt: { token: string user: { deviceID: string id: string isAnonymous: boolean name: string avatar: string }, exp: number iat: number host: string searchParams: string iat_Issued: string exp_Expire: string } maxJobs: number supportMusic: boolean supportVideo: boolean supportAudio: boolean supportChat: boolean } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST https://api.useapi.net/v1/minimax/accounts \ -d '{"url": "…", "token": "…", "maxJobs": …}' ``` **JavaScript** ``` javascript const url = "MiniMax url"; const token = "MiniMax token"; const apiUrl = `https://api.useapi.net/v1/minimax/accounts`; const api_token = "API token"; const maxJobs = 1; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${api_token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ url, token, maxJobs }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests url = "MiniMax url" token = "MiniMax token" apiUrl = f"https://api.useapi.net/v1/minimax/accounts" api_token = "API token" maxJobs = 1 headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {api_token}" } body = { "url": f"{url}", "token": f"{token}", "maxJobs": maxJobs } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-minimax-v1/post-minimax-agent === Document URL: https://useapi.net/docs/api-minimax-v1/post-minimax-agent --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> agent description: "Run the MiniMax AI Agent via POST agent in the useapi.net MiniMax API v1 to generate video, images, or audio using multiple models in sync or async mode." parent: MiniMax API nav_order: 2000 --- ## Execute AI Agent with Multi-Model Support November 24, 2025 (November 16, 2026) --- Execute MiniMax AI Agent with support for multiple AI models including video generation ([Hailuo 2.3](https://hailuoai.video/ai-video-landing/ai-video-generator-hailuo-2-3), [02](https://www.minimax.io/news/minimax-hailuo-02), [Veo 3.1](https://deepmind.google/models/veo/) including S2V subject reference), image generation ([Midjourney V7/NiJi 7](https://www.midjourney.com/), [Nano Banana 2/Pro](https://blog.google/technology/ai/nano-banana-pro/), [Seedream 4.5/5.0](https://seed.bytedance.com/en/seedream4_5), [Kontext](https://bfl.ai/models/flux-kontext), [Qwen](https://github.com/QwenLM/Qwen-Image), Kolors), and audio synthesis ([Speech 2.5](https://minimax-ai.chat/models/minimax-speech-25/), [Music 2.0](https://www.minimax.io/news/minimax-music-20)). The agent API can operate in synchronous or asynchronous mode. Be very specific in your prompt about the type of content you want to generate. Explicitly state "generate a video", "generate an image", or "generate a song based on my lyrics" to ensure the agent uses the correct model from your provided list. You can also specify aspect ratio and resolution directly in your prompt, e.g., "create 1:1 4K image of a sunset" or "generate 16:9 video of waves". Without clear instructions, the agent may choose a different model or generate unexpected content type (e.g., generating a video when you wanted an image). To verify which model was actually used along with the resolution and aspect ratio, check the `file.extra` fields in the response (see [Model](#model) section for `model_name`, `model_aspect_ratio`, `model_resolution` fields). This endpoint features dynamic capacity limits. If you receive a `429` response, wait for at least one job to complete (or wait ~30 seconds) and try again. Use [GET agent/jobs](/docs/api-minimax-v1/get-minimax-agent-jobs) to monitor running jobs. Execution Times: - Simple one-step tasks: 20-60 seconds - Medium complexity tasks: 60 seconds to 2 minutes - Multi-step complex tasks with multiple models: 5+ minutes - Jobs expire after 15 minutes Use [hailuoai.video](https://hailuoai.video) account to execute agent tasks, see [Setup MiniMax](/docs/start-here/setup-minimax) for details. **Note:** Model `nano-banana-2` Nano Banana 2/Pro has less content moderation compared to Google Flow and is capable of editing photos of minors or famous people. Use responsibly and in compliance with applicable laws and regulations. > **https://api.useapi.net/v1/minimax/agent** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body Below is a [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData) `multipart/form-data` example using Postman notation: | Key | Type | Value (example) | | --------- | ---- | --------------------------------- | | account | Text | Optional MiniMax API account | | prompt | Text | Generate a video of a cat playing | | models | Text | hailuo-2.3,nano-banana-2 | | file | File | «Reference.jpg» | | file | File | «Style.png» | | async | Text | false | | replyUrl | Text | https://webhook.site/your-id | | replyRef | Text | my-task-123 | - `account` is optional when only one [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `prompt` is **required**, describe your request to the AI agent. - `models` is **required**, comma-separated list of AI models to use. Supported models: **Video Models - Hailuo:** - `hailuo-2.3` - Hailuo 2.3 (highest quality) - `hailuo-2.3-fast` - Hailuo 2.3-Fast (faster generation) - `hailuo-02` - Hailuo 02 **Video Models - Veo:** - `veo-3.1` - Veo 3.1 (Google DeepMind) - `veo-3.1-fast` - Veo 3.1 Fast - `veo-3.1-s2v` - Veo 3.1 S2V (subject reference) - `veo-3.1-s2v-fast` - Veo 3.1 S2V Fast Sora 2 is no longer available: OpenAI shut it down on September 24, 2026. **Image Models - MiniMax:** - `nano-banana-2` - Nano Banana 2/Pro - `nano-banana` - Nano Banana - `seedream` - Seedream 4.5 **Image Models - Third Party:** - `midjourney-v7` - Midjourney V7 - `midjourney-niji7` - Midjourney NiJi 7 - `seedream-5.0` - Seedream 5.0 (ByteDance) - `kontext` - Kontext (Flux) - `qwen` - Qwen Image (Alibaba) - `kolors` - Kolors (Kuaishou) **Audio Models - TTS:** - `speech-2.5-hd-preview` - Speech 2.5 HD Preview - `speech-2.5-turbo-preview` - Speech 2.5 Turbo Preview **Audio Models - Music:** - `minimax-music-2.0` - MiniMax Music 2.0 Example: `"hailuo-2.3,nano-banana-2"` will use both Hailuo 2.3 video and Nano Banana 2/Pro image models. - `file` is optional, attach reference files for the agent to process. You can upload multiple files. - `async` is optional. When set to `true`, the API returns immediately with a job ID and processes the request in the background. Default: `false` (synchronous). - `replyUrl` is optional. Callback URL for job completion notifications. API will call the provided `replyUrl` once the agent task is completed or failed. The callback payload format matches the response [Model](/docs/api-minimax-v1/get-minimax-agent-jobId#model) shown below. Maximum length 1024 characters. We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality. - `replyRef` is optional, place here your reference id which will be stored and returned along with this agent response/result. Maximum length 1024 characters. ##### Responses **200** **200 OK** Agent task completed successfully (synchronous mode). ```json { "jobId": "p123456789-u12345-a67890-bot:minimax", "status": "completed", "created": "2025-11-24T12:34:56.789Z", "request": { "account": "67890", "prompt": "Generate a video of a cat playing piano", "models": [ "hailuo-2.3", "nano-banana-2" ], "replyUrl": "https://webhook.site/your-webhook-id", "replyRef": "my-task-123" }, "response": { "projectID": "123456789", "sectionID": "987654321", "chatID": "456789123", "msg_content": "I've generated a video of a cat playing piano and an image variation.", "timestamp": 1732366496789, "elapsedTime": "02:15", "attachments": [ { "attachmentID": "att_123456789", "type": 1, "status": 3, "file": { "fileName": "cat_piano_video.mp4", "fileUrl": "https://cdn.hailuoai.video/...mp4", "type": "video/mp4", "extra": { "width": "1280", "height": "720", "duration": "5.0", "fps": "24", "no_watermark_url": "https://cdn.hailuoai.video/.../no_watermark.mp4", "watermark_url": "https://cdn.hailuoai.video/.../watermark.mp4", "thumbnail_url": "https://cdn.hailuoai.video/.../thumb.jpg" } } }, { "attachmentID": "att_987654321", "type": 2, "status": 3, "file": { "fileName": "cat_piano_image.png", "fileUrl": "https://cdn.hailuoai.video/...png", "type": "image/png", "extra": { "model_name": "banana_2", "model_aspect_ratio": "16:9", "model_resolution": "1K" } } } ] } } ``` **201** **201 Created** Agent task created and processing in background (asynchronous mode with `async: true`). Use the returned `jobId` to check status via [GET agent/`jobId`](/docs/api-minimax-v1/get-minimax-agent-jobId). ```json { "jobId": "p987654321-u12345-a67890-bot:minimax", "status": "started", "created": "2025-11-24T12:30:00.000Z", "request": { "account": "67890", "prompt": "Generate a video of a cat playing piano", "models": [ "hailuo-2.3" ], "async": true, "replyUrl": "https://webhook.site/your-webhook-id", "replyRef": "my-task-456" }, "response": { "projectID": "987654321", "sectionID": "123456789", "chatID": "456789012" } } ``` **400** **400 Bad Request** Invalid request parameters. ```json { "error": "Error …", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **422** **422 Unprocessable Content** Moderated content or invalid file. ```json { "error": "Your prompt contains content that violates our policies" } ``` **429** **429 Too Many Requests** Dynamic capacity limit reached. Wait for at least one job to complete (or wait ~30 seconds) and try again. ```json { "error": "Agent generation failed" } ``` **500** **500 Internal Server Error** Agent execution failed. ```json { "jobId": "p123456789-u12345-a67890-bot:minimax", "status": "failed", "created": "2025-11-23T12:34:56.789Z", "request": { "prompt": "Generate a video", "models": ["hailuo-2.3"] }, "error": { "message": "Agent connection error", "status": 500 } } ``` **504** **504 Gateway Timeout** Agent task timed out after 15 minutes. ```json { "jobId": "p123456789-u12345-a67890-bot:minimax", "status": "failed", "created": "2025-11-23T12:34:56.789Z", "request": { "prompt": "Generate a video", "models": ["hailuo-2.3"] }, "error": { "message": "Timeout waiting for assistant response", "status": 504 } } ``` **596** **596 Pending mod message** Your hailuoai.video account has been placed on hold, which may last a few hours. It may be a good idea to pause operations until then. You can reach out to the Discord [support channel](https://discord.com/channels/1280370508373950534/1297778596236103762) or send an email requesting your account to be unlocked. Based on the information we have gathered, this seems to be a temporary ban that will automatically unlock in just a few hours. ```json { "error": "Unusual account activities detected. Please contact customer support at contact@hailuoai.com" } ``` ##### Model The agent job record, with its `jobId` and `status`, and once completed the agent's reply and generated files. <details markdown="block" class="model-details"> <summary>The agent job record, field by field</summary> - `response.attachments[].file.fileUrl` - primary download URL (may have watermark) - `response.attachments[].file.extra.no_watermark_url` - URL without watermark (when available) - `response.attachments[].file.extra.watermark_url` - URL with watermark - `response.attachments[].node.agentFile.noWatermarkUrl` - alternative watermark-free URL - `response.attachments[].node.agentFile.url` - alternative file URL ```typescript { // Job metadata jobId: string // Unique job identifier status: 'started' | 'completed' | 'failed' // Job status created: string // ISO 8601 timestamp code?: number // HTTP status code (optional) // Original request request: { prompt: string // User's prompt file?: Array<{ // File metadata (actual files not included) name: string size: number type: string }> models: string[] // Model IDs used async?: boolean // Async mode flag replyUrl?: string // Callback URL replyRef?: string // User's reference ID } // Agent response (only present on completion) response?: { projectID: string // MiniMax project ID sectionID: string // MiniMax section ID chatID: string // MiniMax chat ID msg_content: string // Agent's response message timestamp: number // Response timestamp (milliseconds since epoch) elapsedTime: string // Elapsed time (mm:ss format) attachments?: Array<{ // Generated files attachmentID: string // Attachment identifier type: number // Attachment type (numeric) status: number // Attachment status (3 = completed) file: { fileName: string // File name fileUrl: string // CDN URL to download file extra?: { // Additional file metadata // Video-specific fields height?: string // Video height in pixels width?: string // Video width in pixels duration?: string // Duration in seconds fps?: string // Frames per second frames?: string // Total frame count no_watermark_url?: string // CDN URL without watermark watermark_url?: string // CDN URL with watermark thumbnail_url?: string // Thumbnail image URL url?: string // Alternative URL path?: string // File path task_id?: string // Generation task ID vendor?: string // Video generation vendor subtitle_path?: string // Subtitle file path // Image-specific fields (nano-banana-2 model) model_aspect_ratio?: string // e.g. "9:16", "16:9" model_name?: string // e.g. "banana_2" model_resolution?: string // e.g. "1K", "2K" // Audio/TTS-specific fields format?: string // e.g. "mp3" type?: string // e.g. "audio" model_speech_count?: string // Character count for TTS } posterUrl?: string // Poster/thumbnail URL type?: string // File MIME type referenceType?: number // Reference type } text?: string // Associated text content extra?: Record<string, any> // Additional metadata node?: { // Node/timeline information nodeID: string // Unique node identifier xStart: number // X position start yStart: number // Y position start width: number // Node width height: number // Node height layer: number // Layer index nodeType: number // Node type identifier agentFile?: { // Generated file details id: string // File ID name: string // File name url: string // File URL coverInfo?: { // Cover image info coverURL: string // Cover image URL } noWatermarkUrl?: string // URL without watermark duration?: number // Duration in seconds relativePath?: string // Relative file path thumbnailUrl?: string // Thumbnail URL } status: number // Node status playWidth: number // Playback width playHeight: number // Playback height logoType: number // Logo type identifier } }> } // Error information (only present on failure) error?: string | { // Error can be a string or object message: string // Error description status: number // HTTP status code details?: any // Additional error details } } ``` </details> ##### Examples **Curl** ``` bash # Synchronous request curl -H "Authorization: Bearer YOUR_API_TOKEN" \ -F "prompt=Generate a video of a cat playing piano" \ -F "models=hailuo-2.3,nano-banana-2" \ "https://api.useapi.net/v1/minimax/agent" # Asynchronous request curl -H "Authorization: Bearer YOUR_API_TOKEN" \ -F "prompt=Generate a video of a cat playing piano" \ -F "models=hailuo-2.3" \ -F "async=true" \ -F "replyUrl=https://webhook.site/your-webhook-id" \ "https://api.useapi.net/v1/minimax/agent" # With file upload curl -H "Authorization: Bearer YOUR_API_TOKEN" \ -F "prompt=Generate a video using this reference" \ -F "models=hailuo-2.3" \ -F "file=@/path/to/reference.jpg" \ "https://api.useapi.net/v1/minimax/agent" ``` **JavaScript** ``` javascript const token = "YOUR_API_TOKEN"; const apiUrl = "https://api.useapi.net/v1/minimax/agent"; // Synchronous request const formData = new FormData(); formData.append('prompt', 'Generate a video of a cat playing piano'); formData.append('models', 'hailuo-2.3,nano-banana-2'); const response = await fetch(apiUrl, { method: 'POST', headers: { 'Authorization': `Bearer ${token}` }, body: formData }); const result = await response.json(); console.log("Job completed:", result); if (result.response?.attachments) { result.response.attachments.forEach(att => { console.log(`${att.file.fileName}: ${att.file.fileUrl}`); }); } // Asynchronous request const asyncFormData = new FormData(); asyncFormData.append('prompt', 'Generate a video of a cat playing piano'); asyncFormData.append('models', 'hailuo-2.3'); asyncFormData.append('async', 'true'); asyncFormData.append('replyUrl', 'https://webhook.site/your-webhook-id'); const asyncResponse = await fetch(apiUrl, { method: 'POST', headers: { 'Authorization': `Bearer ${token}` }, body: asyncFormData }); const asyncResult = await asyncResponse.json(); console.log("Job ID:", asyncResult.jobId); ``` **Python** ``` python import requests token = "YOUR_API_TOKEN" api_url = "https://api.useapi.net/v1/minimax/agent" headers = { "Authorization": f"Bearer {token}" } # Synchronous request data = { "prompt": "Generate a video of a cat playing piano", "models": "hailuo-2.3,nano-banana-2" } response = requests.post(api_url, headers=headers, data=data) result = response.json() print("Job completed:", result) if result.get('response', {}).get('attachments'): for att in result['response']['attachments']: print(f"{att['file']['fileName']}: {att['file']['fileUrl']}") # Asynchronous request async_data = { "prompt": "Generate a video of a cat playing piano", "models": "hailuo-2.3", "async": "true", "replyUrl": "https://webhook.site/your-webhook-id" } async_response = requests.post(api_url, headers=headers, data=async_data) async_result = async_response.json() print("Job ID:", async_result['jobId']) ``` === URL: https://useapi.net/docs/api-minimax-v1/post-minimax-files === Document URL: https://useapi.net/docs/api-minimax-v1/post-minimax-files --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> files description: "Upload images, audio, or video up to 5 GB via POST files in the useapi.net MiniMax API v1 for use as reference inputs in videos/create and images/create." parent: MiniMax API nav_order: 3300 --- ## Upload image, audio, or video file October 15, 2024 (November 16, 2026) --- Use [hailuoai.video](https://hailuoai.video) account to upload image, see [Setup MiniMax](/docs/start-here/setup-minimax) for details. Upload media (images, audio, video) up to 5GB in size that you want to use as references in [POST videos/create](/docs/api-minimax-v1/post-minimax-videos-create) or [POST images/create](/docs/api-minimax-v1/post-minimax-images-create). Supported formats: - **Images** (`.png`, `.jpeg`, `.webp`) — first frame, end frame, character/subject reference, omni image reference. `.webp` uploads via `Content-Type: image/jpeg`. - **Audio** (`.mp3`, `.wav`) — Seedance omni audio references (`audioFileID1`…`audioFileID3`, resolved as `@Audio1`…`@Audio3`). - **Video** (`.mp4`) — Seedance omni video references (`videoFileID1`…`videoFileID3`, resolved as `@Video1`…`@Video3`). Please **be patient**, on average, it takes about 1 minute per GB to upload. [POST raw content using Make.com and similar nocode tools.](/docs/questions-and-answers#how-post-raw-content-to-runwaymlassets-and-minimaxfiles-using-makecom-and-similar-nocode-tools) > **https://api.useapi.net/v1/minimax/files/?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: select from the table below ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. - `Content-Type` is **required**, select from the table below: | Content-Type | File Extension | Used for | | ------------ | -------------- | -------- | | image/png | png | Image references (all video/image models) | | image/jpeg | jpeg | Image references; also `.webp` (uploaded as jpeg) | | audio/mpeg | mp3 | Seedance omni audio reference (`audioFileID*`) | | audio/wav | wav | Seedance omni audio reference (`audioFileID*`) | | video/mp4 | mp4 | Seedance omni video reference (`videoFileID*`) | ##### Query Parameters - `account` is optional when only one [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. ##### Responses **200** **200 OK** ```json { "ossPath": "<file url>", "fileID": "user:user_id-minimax:account-file:file_id" } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model The uploaded file's `fileID`, to use as a reference in [POST videos/create](/docs/api-minimax-v1/post-minimax-videos-create), and its `ossPath`. <details markdown="block" class="model-details"> <summary>The uploaded file, field by field</summary> ```typescript { // TypeScript, all fields are optional ossPath: string fileID: string error: string code: number } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/minimax/files/?account=account" \ -H "Authorization: Bearer …" \ -H "Content-Type: image/jpeg" \ --data-binary /path/to/your/image.jpeg ``` **JavaScript** ``` javascript const token = "API token"; const account = "Previously configured video account"; const apiUrl = `https://api.useapi.net/v1/minimax/files/?account=${account}`; let blob; /* // Example 1: Fetch image from URL const imageUrl = "https://upload.wikimedia.org/wikipedia/commons/7/7d/Mona_Lisa_color_restoration.jpg"; const responseImage = await fetch(imageUrl); blob = await responseImage.blob(); */ /* // Example 2: Load image from local file (Blob) const fsp = require('fs').promises; const imageFileName = "./cat.png"; blob = new Blob([await fsp.readFile(imageFileName)]); */ /* // Example 3: Load from input file html element // <input id="image-file" type="file"> const imageFile = document.getElementById(`image-file`); if (imageFile.files[0]) blob = imageFile.files[0]); */ const response = await fetch(apiUrl, { method: "POST" headers: { "Authorization": `Bearer ${token}`, }, body: blob }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" account = "Previously configured video account" apiUrl = f"https://api.useapi.net/v1/minimax/files/?account={account}" headers = { 'Authorization': f'Bearer {token}', 'Content-Type': 'image/jpeg' } # # Example 1: Fetch image from URL # image_url = "https://upload.wikimedia.org/wikipedia/commons/7/7d/Mona_Lisa_color_restoration.jpg" # response_image = requests.get(image_url) # file_content = response_image.content # # Example 2: Load image from local file # image_file_path = "./image.jpg" # with open(image_file_path, 'rb') as image_file: # file_content = image_file.read() response = requests.post(api_url, headers=headers, data=file_content) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-minimax-v1/post-minimax-images-create === Document URL: https://useapi.net/docs/api-minimax-v1/post-minimax-images-create --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> images/create description: "Create AI images via POST images/create in the useapi.net MiniMax API v1 — 11 models including MiniMax H3 Image, Midjourney V7, GPT Image 2, Nano Banana Pro and Seedream 5.0." parent: MiniMax API nav_order: 1100 --- ## Create an image using a text prompt ## Table of contents March 17, 2025 (November 16, 2026) --- Use [hailuoai.video](https://hailuoai.video) account to retrieve list of generated images, see [Setup MiniMax](/docs/start-here/setup-minimax) for details. ##### Model Comparison Matrix | Model | Resolutions | Aspect Ratios | Ref Images | @-mention | |:------|:------------|:--------------|:-----------|:---------:| | image-01 | HD | 16:9 (default), 4:3, 1:1, 3:4, 9:16, 21:9 | 1 via `characterFileId` | — | | h3-image | 1K, 2K, 4K | auto (default), 21:9, 16:9, 5:4, 4:3, 3:2, 1:1, 2:3, 3:4, 4:5, 9:16 | 1-16 via `referenceFileId1`…`16` | Yes | | h3-image-highspeed | 1K, 2K, 4K | auto (default), 21:9, 16:9, 5:4, 4:3, 3:2, 1:1, 2:3, 3:4, 4:5, 9:16 | 1-16 via `referenceFileId1`…`16` | Yes | | nano-banana-2 | 512P, 1K, 2K, 4K | auto (default), 16:9, 5:4, 4:3, 3:2, 1:1, 2:3, 3:4, 4:5, 9:16, 21:9 | 1-14 via `referenceFileId1`…`14` | Yes | | nano-banana-pro | 1K, 2K, 4K | auto (default), 16:9, 5:4, 4:3, 3:2, 1:1, 2:3, 3:4, 4:5, 9:16, 21:9 | 1-14 via `referenceFileId1`…`14` | Yes | | gpt-image-1.5 | Low, Medium, High | auto (default), 1:1, 3:2, 2:3 | 1-3 via `referenceFileId1`…`3` | — | | gpt-image-2 | 1K, 2K, 4K | 16:9 (default), 21:9, 5:4, 4:3, 3:2, 1:1, 2:3, 3:4, 4:5, 9:16 | 1-16 via `referenceFileId1`…`16` | Yes | | seedream-4.5 | 2K, 4K | auto (default), 16:9, 5:4, 4:3, 3:2, 1:1, 2:3, 3:4, 4:5, 9:16, 21:9 | 1-14 via `referenceFileId1`…`14` | Yes | | seedream-5.0 | 2K, 3K | auto (default), 21:9, 16:9, 5:4, 4:3, 3:2, 1:1, 2:3, 3:4, 4:5, 9:16 | 1-14 via `referenceFileId1`…`14` | Yes | | midjourney-v7 | n/a | auto (default), 21:9, 16:9, 5:4, 4:3, 3:2, 1:1, 2:3, 3:4, 4:5, 9:16 | 1-14 via `referenceFileId1`…`14` | — | | midjourney-niji7 | n/a | auto (default), 21:9, 16:9, 5:4, 4:3, 3:2, 1:1, 2:3, 3:4, 4:5, 9:16 | 1-14 via `referenceFileId1`…`14` | — | Models with **@-mention** support let you reference uploaded images by slot inside the `prompt` (e.g. `"@Image1 with bokeh background"`). The token is `@Image<N>` where `<N>` is the slot from `referenceFileId<N>`. Case-insensitive: `@IMAGE1`, `@image1`, `@ImAgE001` all canonicalize to `@Image1`. Unsupported models reject prompts containing `@Image<N>` tokens. <details markdown="block"> <summary><b>Credits estimator</b></summary> Credits are charged per image. Actual costs may change, see [hailuoai.video](https://hailuoai.video) for current pricing. | Model | Resolution | Credits per image | Quantity | |:------|:-----------|:-----------------:|:---------| | image-01 | HD | 1 | 1-4 | | h3-image | 1K, 2K | 3 | 1-4 | | h3-image | 4K | 6 | 1-4 | | h3-image-highspeed | 1K, 2K | 5 | 1-4 | | h3-image-highspeed | 4K | 12 | 1-4 | | nano-banana-2 | 512P, 1K | 4 | 1-4 | | nano-banana-2 | 2K | 5 | 1-4 | | nano-banana-2 | 4K | 8 | 1-4 | | nano-banana-pro | 1K, 2K | 6 | 1-4 | | nano-banana-pro | 4K | 10 | 1-4 | | gpt-image-1.5 | Low | 4 | 1-4 | | gpt-image-1.5 | Medium | 8 | 1-4 | | gpt-image-1.5 | High | 15 | 1-4 | | gpt-image-2 (quality `low`) | 1K | 2 | 1-4 | | gpt-image-2 (quality `low`) | 2K | 5 | 1-4 | | gpt-image-2 (quality `low`) | 4K | 10 | 1-4 | | gpt-image-2 (quality `medium`) | 1K | 8 | 1-4 | | gpt-image-2 (quality `medium`) | 2K | 20 | 1-4 | | gpt-image-2 (quality `medium`) | 4K | 40 | 1-4 | | gpt-image-2 (quality `high`) | 1K | 30 | 1-4 | | gpt-image-2 (quality `high`) | 2K | 80 | 1-4 | | gpt-image-2 (quality `high`) | 4K | 160 | 1-4 | | seedream-4.5 | 2K, 4K | 4 | 1-4 | | seedream-5.0 | 2K, 3K | 4 | 1-4 | | midjourney-v7 | n/a | 3 | 4 (fixed) | | midjourney-niji7 | n/a | 3 | 4 (fixed) | </details> To retrieve generated image(s), use: * [GET images/`imageId`](/docs/api-minimax-v1/get-minimax-images-imageId) * [GET images](/docs/api-minimax-v1/get-minimax-images) > **https://api.useapi.net/v1/minimax/images/create** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "account": "Optional MiniMax API account", "prompt": "Required text prompt", "promptOptimization": true, "model": "nano-banana-pro", "aspectRatio": "16:9", "resolution": "2K", "referenceFileId1": "user:…-minimax:…-file:…", "referenceFileId2": "user:…-minimax:…-file:…", "quantity": 2, "replyUrl": "Place your call back URL here", "replyRef": "Place your reference id here" } ``` ##### Parameters - `account` is optional when only one [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `prompt` is **required**, describe your image. Maximum length depends on the model — 2,000 characters for `image-01`, `gpt-image-1.5`, `seedream-4.5`, and `seedream-5.0`, 5,000 for `midjourney-v7` and `midjourney-niji7`, and 7,500 for `h3-image`, `h3-image-highspeed`, `gpt-image-2`, `nano-banana-2`, and `nano-banana-pro`. **@-mention syntax** (supported by `h3-image`, `h3-image-highspeed`, `gpt-image-2`, `nano-banana-pro`, `nano-banana-2`, `seedream-4.5`, `seedream-5.0`): use `@Image1`…`@Image16` in the prompt to reference uploaded images by slot — `@Image1` binds to `referenceFileId1`, `@Image2` to `referenceFileId2`, etc. Tokens are case-insensitive (`@IMAGE1`, `@image1`, `@ImAgE001` all canonicalize to `@Image1`). Models without @-mention support (`image-01`, `gpt-image-1.5`, `midjourney-v7`, `midjourney-niji7`) reject prompts containing `@Image<N>` tokens with a 400. - `promptOptimization` is optional. Supported values: `true` (default), `false`. - `model` is optional. Supported values: * `image-01` (default) - Character-focused image generation with HD resolution. Supports character reference via `characterFileId`. * `h3-image` - MiniMax H3 Image (1K/2K/4K), MiniMax's own image generation and editing model, with up to 16 reference images via `referenceFileId1`…`16` (with @-mention support). * `h3-image-highspeed` - MiniMax H3 Image Highspeed, the same image quality generated faster (1K/2K/4K), with up to 16 reference images (with @-mention support). * `nano-banana-2` - Image generation (512P/1K/2K/4K) with up to 14 reference images. Lower cost flash variant. * `nano-banana-pro` - High-resolution image generation (1K/2K/4K) with up to 14 reference images. * `gpt-image-1.5` - High-resolution image generation (Low/Medium/High) with up to 3 reference images and limited aspect ratios. * `gpt-image-2` - GPT Image 2 (1K/2K/4K, `quality` = low/medium/high) with 10 aspect ratios and up to 16 reference images via `referenceFileId1`…`16` (with @-mention support). * `seedream-4.5` - High-resolution image generation (2K/4K) with up to 14 reference images. * `seedream-5.0` - High-resolution image generation (2K/3K) with up to 14 reference images. * `midjourney-v7` - Midjourney V7 image generation. Always generates 4 images per request (ignores `quantity`). Up to 14 reference images. * `midjourney-niji7` - Midjourney NiJi 7 anime-focused image generation. Always generates 4 images per request (ignores `quantity`). Up to 14 reference images. - `resolution` is optional, model-specific. * `image-01`: Only `HD` supported (default). * `h3-image`, `h3-image-highspeed`: `1K` (default), `2K`, `4K`. * `nano-banana-2`: `512P` (default), `1K`, `2K`, `4K`. * `nano-banana-pro`: `1K` (default), `2K`, `4K`. * `gpt-image-1.5`: `Low` (default), `Medium`, `High`. * `gpt-image-2`: `1K` (default), `2K`, `4K`. * `seedream-4.5`: `2K` (default), `4K`. * `seedream-5.0`: `2K` (default), `3K`. * `midjourney-v7`: Not applicable (no resolution parameter). * `midjourney-niji7`: Not applicable (no resolution parameter). - `aspectRatio` is optional, model-specific. * `image-01`: `16:9` (default), `4:3`, `1:1`, `3:4`, `9:16`, `21:9`. * `h3-image`, `h3-image-highspeed`: `auto` (default), `21:9`, `16:9`, `5:4`, `4:3`, `3:2`, `1:1`, `2:3`, `3:4`, `4:5`, `9:16`. * `nano-banana-2`: `auto` (default), `16:9`, `5:4`, `4:3`, `3:2`, `1:1`, `2:3`, `3:4`, `4:5`, `9:16`, `21:9`. * `nano-banana-pro`: `auto` (default), `16:9`, `5:4`, `4:3`, `3:2`, `1:1`, `2:3`, `3:4`, `4:5`, `9:16`, `21:9`. * `gpt-image-1.5`: `auto` (default), `1:1`, `3:2`, `2:3`. * `gpt-image-2`: `16:9` (default), `21:9`, `5:4`, `4:3`, `3:2`, `1:1`, `2:3`, `3:4`, `4:5`, `9:16`. (No `auto` — model doesn't accept it.) * `seedream-4.5`: `auto` (default), `16:9`, `5:4`, `4:3`, `3:2`, `1:1`, `2:3`, `3:4`, `4:5`, `9:16`, `21:9`. * `seedream-5.0`: `auto` (default), `21:9`, `16:9`, `5:4`, `4:3`, `3:2`, `1:1`, `2:3`, `3:4`, `4:5`, `9:16`. * `midjourney-v7`: `auto` (default), `21:9`, `16:9`, `5:4`, `4:3`, `3:2`, `1:1`, `2:3`, `3:4`, `4:5`, `9:16`. * `midjourney-niji7`: `auto` (default), `21:9`, `16:9`, `5:4`, `4:3`, `3:2`, `1:1`, `2:3`, `3:4`, `4:5`, `9:16`. - `quality` is optional, **only for `gpt-image-2`**. Supported values: `low` (default), `medium`, `high`. Credit cost varies by quality × resolution — see the credits estimator above. Other models reject the `quality` parameter with a 400. - `characterFileId` is optional, **only for `image-01`**: * fileID of the character image uploaded via [POST /files](/docs/api-minimax-v1/post-minimax-files). Upload a clear front-facing photo for best result. Avoid side angles and obstructions. * Cannot be used with other models (use `referenceFileId1`…`16` instead). - `referenceFileId1` … `referenceFileId16` are optional, **for all models except `image-01`**: * fileID(s) of reference images uploaded via [POST /files](/docs/api-minimax-v1/post-minimax-files). * `h3-image`, `h3-image-highspeed`, `gpt-image-2`: Supports 1-16 reference images (`referenceFileId1`…`16`). Supports @-mention syntax in prompt. * `nano-banana-2`, `nano-banana-pro`, `seedream-4.5`, `seedream-5.0`: Supports 1-14 reference images. Supports @-mention syntax in prompt. * `midjourney-v7`, `midjourney-niji7`: Supports 1-14 reference images. Does **not** support @-mention syntax — `@ImageN` tokens in prompt return 400. * `gpt-image-1.5`: Supports 1-3 reference images (`referenceFileId1`…`3` only). Does **not** support @-mention syntax. * `image-01`: Use `characterFileId` instead. * Slots must be **contiguous starting at 1** — sending `referenceFileId3` without `referenceFileId1`/`2` returns 400. * All reference files must belong to the same account. - `quantity` is optional. Supported range: 1…4, default 1. **Note:** `midjourney-v7` and `midjourney-niji7` always generate exactly 4 images per request. The `quantity` parameter is ignored for these models. - `replyUrl` is optional. Callback URL for job completion notifications. API will call the provided `replyUrl` once MiniMax image completed or failed. Maximum length 1024 characters. We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality. Callback body has the same JSON shape as [GET /images/`imageId`](/docs/api-minimax-v1/get-minimax-images-imageId) response. - `replyRef` is optional, place here your reference id which will be stored and returned along with this MiniMax image response/result. Maximum length 1024 characters. ##### Responses **200** **200 OK** Use returned in array `imageIds` values to retrieve image status and results using [GET images/`imageId`](/docs/api-minimax-v1/get-minimax-images-imageId). Check `videoURL` and/or `downloadURL` (paid account, no watermarks) for generated image with the `status` **2** (Completed). If you specify the optional parameter [`replyUrl`](/docs/api-minimax-v1/post-minimax-images-create#request-body) the API will call the provided `replyUrl` with image progress updates until the image is complete or fails. ```json { "id": "<image_id_1>", "task": { "batchID": "<batch_id>", "videoIDs": [ "<image_id_1>", "<image_id_2>", "<image_id_3>", "<image_id_4>" ] }, "isFirstGenerate": false, "imageIds": [ "user:<user>-minimax:<account>-image:<image_id_1>", "user:<user>-minimax:<account>-image:<image_id_2>", "user:<user>-minimax:<account>-image:<image_id_3>", "user:<user>-minimax:<account>-image:<image_id_4>" ], "replyUrl": "https://webhook.site/…", "replyRef": "2025-03-11T17:23:05.795Z", "code": 200 } ``` **400** **400 Bad Request** ```json { "error": "<Error message>" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized" } ``` **412** **412 Insufficient credits** Insufficient credits. Please recharge to get more credits or try again next day. ```json { "error": "Insufficient credits. Please recharge to get more credits or try again next day." } ``` **422** **422 Unprocessable Content** Moderated message. ```json { "error": "Your prompt is too short, please provide more details" } ``` **429** **429 Too Many Requests** Wait in a loop for **at least** 10..30 seconds and retry again. ```json { "error": "There are currently multiple tasks in the queue, and only <number> can be generated at once" } ``` **596** **596 Pending mod message** Your hailuoai.video account has been placed on hold, which may last a few hours. It may be a good idea to pause operations until then. You can reach out to the Discord [support channel](https://discord.com/channels/1280370508373950534/1297778596236103762) or send an email requesting your account to be unlocked. Based on the information we have gathered, this seems to be a temporary ban that will automatically unlock in just a few hours. ```json { "error": "Unusual account activities detected. Please contact customer support at contact@hailuoai.com" } ``` ##### Model The new task, with its `imageIds`: poll each with [GET images/`imageId`](/docs/api-minimax-v1/get-minimax-images-imageId) until it completes. <details markdown="block" class="model-details"> <summary>The new image task, field by field</summary> ```typescript { // TypeScript, all fields are optional id: string task: { batchID: string videoIDs: string[] } isFirstGenerate: boolean imageIds: string[] replyUrl: string replyRef: string code: number } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST "https://api.useapi.net/v1/minimax/images/create" \ -d '{"prompt": "…"}' ``` **JavaScript** ``` javascript const prompt = "text prompt"; const apiUrl = `https://api.useapi.net/v1/minimax/images/create`; const token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ prompt }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests prompt = "text prompt" apiUrl = f"https://api.useapi.net/v1/minimax/images/create" token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } body = { "prompt": f"{prompt}" } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-minimax-v1/post-minimax-music-create === Document URL: https://useapi.net/docs/api-minimax-v1/post-minimax-music-create --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> music/create description: "Generate a song from a prompt, optional lyrics, or a reference track via POST music/create in the useapi.net MiniMax API v1 — Music-3.0 and Music-2.6, covers, instrumental mode, and an SSE stream you can play while it renders." parent: MiniMax API nav_order: 2900 --- ## Create Music August 17, 2026 (November 18, 2026) --- This endpoint generates a song from a style prompt and, optionally, your own lyrics. It is powered by [MiniMax Music](https://www.minimax.io/audio/music) — [Music-3.0](https://www.minimax.io/audio/music) is the default, and Music-2.6 remains available. It also makes covers. Pass `referenceMusicId` and the new song is built in the character of an existing track — see [Covers](#covers). There are two ways to collect the result, and the response status tells you which one you got. | Mode | `stream` | Response | Body | |---|:---:|:---:|---| | Async (default) | `false` | `201` | JSON with a `musicId` you poll or receive by webhook | | Streaming | `true` | `200` | `text/event-stream` carrying the audio as it renders | Streaming lets a player start well before the song is finished — see [Streaming](#streaming). Everything under [Request Body](#request-body) applies to both modes. Configure a MiniMax account at [POST accounts/account](/docs/api-minimax-v1/post-minimax-accounts-account) before calling this endpoint. ##### Model Comparison: Music | Feature | Music-3.0 | Music-2.6 | |---------|:---------:|:---------:| | Default | Yes | No | | `prompt` max length | 2000 | 2000 | | `lyrics` max length | 3500 | 3500 | | `title` max length | 40 | 40 | | Instrumental | Yes | Yes | | Covers (`referenceMusicId`) | Yes | Yes | | Tracks per call | 1-3 | 1-3 | | Output | MP3 256 kbps<br>44.1 kHz stereo | MP3 256 kbps<br>44.1 kHz stereo | > **https://api.useapi.net/v1/minimax/music/create** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "account": "123456789012345678", "prompt": "warm nylon guitar, slow bossa nova, gentle brushes, about a rainy afternoon in Lisbon", "lyrics": "[Verse]\nThe tram climbs up the hill\n[Chorus]\nAnd the rain keeps falling still", "title": "Lisbon Rain", "model": "music-3.0", "quantity": 1, "instrumental": false, "referenceMusicId": "user:12345-minimax:123456789012345678-music:987654321098766", "stream": false, "replyUrl": "https://webhook.site/abc", "replyRef": "your-reference-id" } ``` - `account` is optional, if not specified API will select the [account](/docs/api-minimax-v1/get-minimax-accounts) with the fewest music generations already running. - `prompt` is optional, the musical style **and** the subject of the song. Max length `2000`. This one field does two jobs. Describe genre, mood, tempo, instruments and vocal type, and — if you want the lyrics to be about something in particular — say so in the same sentence. A prompt of `melancholic slow piano ballad, female vocals, sparse arrangement` yields lyrics about the mood itself, while the same prompt followed by `, about a lighthouse keeper who lost his dog` yields lyrics about exactly that. - `lyrics` is optional, your own lyrics. Max length `3500`, where each letter and punctuation mark counts as one character. Leave it out and the model writes the lyrics for you from `prompt`, returning them in the response. MiniMax may refuse to write lyrics from a `prompt` alone, and the call then returns `422`: add `lyrics`, set `instrumental` to `true`, or rephrase the `prompt`. Longer lyrics produce longer songs — this is the only way to influence duration, as there is no duration parameter. Structure the words with tags on their own line: `[Intro]`, `[Verse]`, `[Pre-Chorus]`, `[Chorus]`, `[Hook]`, `[Drop]`, `[Bridge]`, `[Solo]`, `[Build-up]`, `[Instrumental]`, `[Breakdown]`, `[Break]`, `[Interlude]`, `[Outro]`. The model may also use tags outside this list in lyrics it writes itself. For wordless vocals, spell the syllables out — `ah, ah, ah` or `la, la, la`. - `title` is optional, the song name. Max length `40`. - `model` is optional. Default: `music-3.0`. Supported values: `music-3.0`, `music-2.6`. - `quantity` is optional, how many tracks to generate from this one call. Default: `1`. Supported values: `1`, `2`, `3`. Each track gets its own `musicId` and finishes independently — they do not complete together. - `instrumental` is optional, generate music with no vocals. Default: `false`. Leaving `lyrics` empty is **not** enough to get an instrumental — without this flag the model writes its own words and sings them. Cannot be combined with `lyrics` or `referenceMusicId`. - `referenceMusicId` is optional, the `musicId` of a track the new song should follow. Turns the call into a cover — see [Covers](#covers). Accepts anything on the same account: a file you uploaded with [POST music/reference](/docs/api-minimax-v1/post-minimax-music-reference), or a song this API generated earlier. - `stream` is optional, return the audio as a Server-Sent Events stream instead of a JSON response. Default: `false`. The streaming response is `200` with `Content-Type: text/event-stream`, not the `201` documented below. See [Streaming](#streaming). - `replyUrl` is optional, we will send a POST request to this URL when generation completes. Maximum length 1024 characters. Callback body has the same JSON shape as [GET music/`musicId`](/docs/api-minimax-v1/get-minimax-music-musicId#model) response, plus `replyRef`, `replyUrl` and `code`. If a track is still unfinished 15 minutes after it was submitted we stop tracking it and POST `{"code": 400, "error": "More than 15 minutes have passed, the task has expired."}` to the same URL. - `replyRef` is optional, your own reference string, echoed back on the `replyUrl` callback. Maximum length 1024 characters. **Notes:** - Supply `prompt`, `lyrics`, `referenceMusicId`, or a combination. A call with none of them returns `400`. - You cannot request a length. The model decides how long each song is, and the only way to influence it is the amount of `lyrics` you supply — more words generally means a longer song. This is true of covers too: the reference's own length has no bearing on the result. - When `quantity` is greater than `1` the tracks are independent songs, not variations of one length. Each gets its own duration, and they finish at different times. - Generation usually takes a few minutes, varying with the length of the song and how busy MiniMax is. Use `replyUrl` or [GET music/musicId](/docs/api-minimax-v1/get-minimax-music-musicId) rather than assuming a fixed wait. - One generation per account at a time. MiniMax enforces this, so it counts songs you start on [minimax.io](https://www.minimax.io/audio/music) as well as those started here, and a second request returns `429` until the first finishes. - Music is billed separately from video and images, at 300 credits a song. A new account has a small allowance to try it; beyond that, music needs a MiniMax audio subscription — covering music and speech — bought from [MiniMax](https://www.minimax.io/audio/music) directly. Without one the call returns `412 Insufficient credits`, however much video credit the account holds. ##### Responses **201** **201 Created** Returned when `stream` is `false` (the default). With `stream` set to `true` the response is `200` and an event stream instead — see [Streaming](#streaming). ```json [ { "musicId": "user:12345-minimax:123456789012345678-music:987654321098765", "title": "Lisbon Rain", "idea": "warm nylon guitar, slow bossa nova, gentle brushes, about a rainy afternoon in Lisbon", "lyrics": "[Verse]\nThe tram climbs up the hill\n[Chorus]\nAnd the rain keeps falling still", "audio_url": "", "cover_url": "https://cdn.hailuoai.video/moss/staging/2025-06-22-16/music_cover/1700000000000000001-other_43.png", "model": "music-3.0", "status": 1, "statusLabel": "processing", "statusFinal": false, "instrumental": false, "duration": 0, "create_time": 1786849532637, "update_time": 0, "is_favorite": false, "hasWav": false, "tag_list": [ { "tag_name": "warm nylon guitar, slow bossa nova, gentle brushes, about a rainy afternoon in Lisbon", "tag_type": 1 } ] } ] ``` **400** **400 Bad Request** ```json { "error": "Please provide prompt, lyrics, or both", "code": 400 } ``` `lyrics` cannot be combined with `instrumental`: ```json { "error": "Parameter lyrics cannot be combined with instrumental", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **412** **412 Precondition Failed** ```json { "error": "Insufficient credits. Please recharge to get more credits or try again next day." } ``` **422** **422 Unprocessable Content** ```json { "error": "Prompt or lyrics were rejected by content moderation", "code": 422 } ``` MiniMax refused to make a song from the prompt alone: ```json { "error": "MiniMax could not make a song from this prompt (2600021). Add lyrics, set instrumental: true, or rephrase the prompt.", "code": 422 } ``` **429** **429 Too Many Requests** ```json { "error": "This account already has a music generation running. Retry once it completes.", "code": 429 } ``` MiniMax allows one music generation per account at a time and reports this itself, so the limit is theirs rather than ours — it applies to songs you start on [minimax.io](https://www.minimax.io/audio/music) too, not only through this API. Wait for the running track to reach `statusFinal`, or use a different `account`. **504** **504 Gateway Timeout** ```json { "error": "No response from minimax music service", "code": 504 } ``` The same status covers the other socket-level failures — `Unable to open music WebSocket (HTTP nnn)`, `Music WebSocket failed before the generation was accepted`, and `Music WebSocket closed before the generation was accepted`. All mean the request never reached MiniMax; retry it. **596** **596 Account Error** ```json { "error": "Your minimax account has pending error. Please address this issue at https://useapi.net/docs/api-minimax-v1/post-minimax-accounts-account before making any new API calls." } ``` ##### Model The new song record, with the `musicId` to poll with [GET music/`musicId`](/docs/api-minimax-v1/get-minimax-music-musicId) until `statusFinal` is `true`. <details markdown="block" class="model-details"> <summary>The song record, field by field</summary> ```typescript { // TypeScript, all fields are optional musicId: string, // Use with GET music/musicId title: string, idea: string, // Echo of the prompt you supplied lyrics: string, // Yours, or written by the model when you leave it empty audio_url: string, // Empty until the track completes cover_url: string, // Cover art, assigned immediately model: string, // music-3.0 | music-2.6 status: number, // See the status table on GET music/musicId statusLabel: string, statusFinal: boolean, typeLabel: string, // "song" here — see GET music referenceMusicId: string, // Present only on a cover: the track it follows instrumental: boolean, duration: number, // Milliseconds, 0 until complete create_time: number, update_time: number, is_favorite: boolean, hasWav: boolean, tag_list: [{ tag_name: string, tag_type: number }] } ``` </details> ##### Covers A cover takes its cues from an existing track. Set `referenceMusicId` and the model reads the reference's character out of the audio itself. How much of the reference survives depends on how much else you supply. A detailed `prompt` competes with it — the model generates from the brief instead. Given a reference and nothing else, it derives everything from the audio, down to the subject of the lyrics it writes. The reference can be either of: - a file you uploaded with [POST music/reference](/docs/api-minimax-v1/post-minimax-music-reference) - a song this API generated earlier — pass its `musicId` directly, no upload needed Both live on the same account, and the account is taken from the `referenceMusicId` itself, so `account` is redundant on a cover. ```bash curl "https://api.useapi.net/v1/minimax/music/create" \ -H "Authorization: Bearer …" \ -H "Content-Type: application/json" \ -d '{ "referenceMusicId": "user:12345-minimax:123456789012345678-music:987654321098766", "prompt": "italo disco, driving synth bass, bright arpeggios", "title": "Last Train Italo" }' ``` What `lyrics` does on a cover is worth knowing: | `lyrics` | Result | |---|---| | Omitted | The model writes its own words, drawn from what it hears in the reference | | Supplied | The cover sings your words, and their volume sets the length | | The reference's own `lyrics` | The cover keeps the original words and lands close to the reference's length — [POST music/reference](/docs/api-minimax-v1/post-minimax-music-reference) returns them, transcribed from the audio | **Notes:** - For the closest result, supply the reference's own `lyrics` and no `prompt`. A full style brief pulls the song away from the reference. - `instrumental` cannot be combined with `referenceMusicId` and returns `400`. MiniMax accepts the pair and then fails the track, so it is rejected here rather than costing you the credits. - A cover costs the same 300 credits as any other song. - The response carries `referenceMusicId` back, so a track's origin is visible in [GET music](/docs/api-minimax-v1/get-minimax-music) and [GET music/musicId](/docs/api-minimax-v1/get-minimax-music-musicId) long after the call. - Only make covers of material you have the rights to use. ##### Streaming Set `stream` to `true` and the response is `200` with `Content-Type: text/event-stream`, instead of the `201` JSON documented in [Responses](#responses). The audio arrives in chunks as MiniMax renders it, so a player can begin well before the song is finished. The response carries an `X-Music-Id` header with the `musicId` — comma-separated when `quantity` is greater than `1` — so you can identify or poll the track even if you stop reading the stream. ###### Events | Event | Description | When Sent | |---|---|---| | `progress` | The track record, same shape as the [Model](#model) above | Whenever MiniMax reports a state change | | `audio` | `{ "musicId": "...", "chunk": "<base64>" }` — a slice of the MP3 | As each chunk is rendered | | `done` | Array of the finished track records, with `audio_url` and `duration` set | Once **every** track is complete | | `error` | `{ "error": "...", "code": 422 }` | Moderation rejected the prompt or lyrics, or MiniMax failed mid-generation — `code` carries the mapped HTTP status (`422`, `412`, `429`, `500`) | | `: keepalive` | An SSE comment, not an event | Every 10 seconds | ###### When the stream ends without `done` Two cases end the stream with neither `done` nor `error`, so do not block on `done` forever. The upstream connection can drop, which closes the SSE stream where it stands; and there is a hard 10 minute cap on any single stream. In both cases the generation itself keeps going — poll [GET music/musicId](/docs/api-minimax-v1/get-minimax-music-musicId) with the `musicId` from the `X-Music-Id` header to collect the finished track. ###### Knowing when it is finished Wait for the `done` event. It is the only signal that means the job succeeded, and it fires once every track in the call is complete. For a single track a `progress` event with `statusFinal: true` means the same thing. Audio stops arriving before the song is finished — do not read that as completion. After the last chunk MiniMax spends up to a minute finalising the file, and only then are `audio_url` and `duration` filled in. A client that stops at the last chunk reports the song as ready while still holding `duration: 0` and an empty `audio_url`. That gap works in your favour for playback: you have the whole song in hand before `done` arrives, so you can start playing straight away and use `done` only to confirm success and pick up the final metadata. ###### Playing while it generates Concatenate the base64 `chunk` values in arrival order, per `musicId`. The result is a plain MP3, playable as soon as you have the first chunk. The stream is silent for the first 20 to 50 seconds while MiniMax renders the opening. Nothing is wrong — the `: keepalive` comments are there to stop proxies closing what looks like an idle connection, and your client should not time out during this. Show the user a "generating" state until the first `audio` event. After that, playback will not stutter. Audio arrives faster than it plays, so the buffer only ever grows — by the time the first 7 seconds have played you already hold 30 or more, and the full song lands well before playback reaches the end. You do not need to pre-buffer or throttle. Chunk sizes are uneven — anywhere from a few kilobytes to a couple of megabytes — so append whatever arrives rather than expecting a steady feed. ###### Streaming example ```javascript const response = await fetch("https://api.useapi.net/v1/minimax/music/create", { method: "POST", headers: { "Authorization": "Bearer …", "Content-Type": "application/json" }, body: JSON.stringify({ prompt: "gentle fingerpicked acoustic guitar, warm and short", instrumental: true, stream: true }) }); console.log("musicId:", response.headers.get("X-Music-Id")); const reader = response.body.getReader(); const decoder = new TextDecoder(); const chunks = []; let buffer = ""; while (true) { const { done, value } = await reader.read(); if (done) break; buffer += decoder.decode(value, { stream: true }); const parts = buffer.split("\n\n"); buffer = parts.pop(); for (const part of parts) { const event = /^event: (.+)$/m.exec(part)?.[1]; const data = /^data: (.+)$/m.exec(part)?.[1]; if (!event || !data) continue; const payload = JSON.parse(data); if (event === "audio") chunks.push(Uint8Array.from(atob(payload.chunk), c => c.charCodeAt(0))); else if (event === "progress") console.log("status:", payload.statusLabel); else if (event === "done") console.log("finished:", payload[0].duration, "ms"); else if (event === "error") console.error(payload.error); } } const audio = new Blob(chunks, { type: "audio/mpeg" }); document.querySelector("audio").src = URL.createObjectURL(audio); ``` ###### Playing it live with MediaSource The example above collects every chunk and plays the result at the end. To play *while* the song is still being generated, push each chunk into a [MediaSource](https://developer.mozilla.org/en-US/docs/Web/API/MediaSource) `SourceBuffer` instead. Two details make or break this. Chunks must be appended **one at a time** — `appendBuffer` throws if the buffer is still updating — so queue them and append on `updateend`. And call `endOfStream()` when the stream finishes, otherwise the element never learns the track has ended. ```html <audio id="player" controls></audio> ``` ```javascript const player = document.getElementById("player"); const mediaSource = new MediaSource(); player.src = URL.createObjectURL(mediaSource); const queue = []; let sourceBuffer = null; let finished = false; const pump = () => { if (!sourceBuffer || sourceBuffer.updating || queue.length === 0) { if (finished && sourceBuffer && !sourceBuffer.updating && queue.length === 0 && mediaSource.readyState === "open") mediaSource.endOfStream(); return; } sourceBuffer.appendBuffer(queue.shift()); }; mediaSource.addEventListener("sourceopen", async () => { sourceBuffer = mediaSource.addSourceBuffer("audio/mpeg"); sourceBuffer.addEventListener("updateend", pump); const response = await fetch("https://api.useapi.net/v1/minimax/music/create", { method: "POST", headers: { "Authorization": "Bearer …", "Content-Type": "application/json" }, body: JSON.stringify({ prompt: "gentle fingerpicked acoustic guitar, warm and short", instrumental: true, stream: true }) }); const reader = response.body.getReader(); const decoder = new TextDecoder(); let buffer = ""; while (true) { const { done, value } = await reader.read(); if (done) break; buffer += decoder.decode(value, { stream: true }); const parts = buffer.split("\n\n"); buffer = parts.pop(); for (const part of parts) { const event = /^event: (.+)$/m.exec(part)?.[1]; const data = /^data: (.+)$/m.exec(part)?.[1]; if (!event || !data) continue; const payload = JSON.parse(data); if (event === "audio") { queue.push(Uint8Array.from(atob(payload.chunk), c => c.charCodeAt(0))); pump(); if (player.paused) player.play(); } else if (event === "done") { finished = true; pump(); } else if (event === "error") { console.error(payload.error); finished = true; pump(); } } } }); ``` Playback starts as soon as the first chunk lands and runs to the end without stalling, because the stream stays ahead of the playhead. Browser support. `MediaSource` with `audio/mpeg` works in Chrome, Edge, and Firefox. Safari's MSE support does not cover MP3, so check `MediaSource.isTypeSupported("audio/mpeg")` and fall back to the collect-then-play approach shown earlier. ##### Examples **Curl** ```bash curl -X POST "https://api.useapi.net/v1/minimax/music/create" \ -H "Authorization: Bearer …" \ -H "Content-Type: application/json" \ -d '{ "prompt": "warm nylon guitar, slow bossa nova, about a rainy afternoon in Lisbon", "title": "Lisbon Rain", "quantity": 1 }' ``` **JavaScript** ```javascript const response = await fetch("https://api.useapi.net/v1/minimax/music/create", { method: "POST", headers: { "Authorization": "Bearer …", "Content-Type": "application/json" }, body: JSON.stringify({ prompt: "warm nylon guitar, slow bossa nova, about a rainy afternoon in Lisbon", title: "Lisbon Rain", quantity: 1 }) }); const tracks = await response.json(); console.log(tracks.map(track => track.musicId)); ``` **Python** ```python import requests response = requests.post( "https://api.useapi.net/v1/minimax/music/create", headers={ "Authorization": "Bearer …", "Content-Type": "application/json" }, json={ "prompt": "warm nylon guitar, slow bossa nova, about a rainy afternoon in Lisbon", "title": "Lisbon Rain", "quantity": 1 } ) for track in response.json(): print(track["musicId"]) ``` === URL: https://useapi.net/docs/api-minimax-v1/post-minimax-music-reference === Document URL: https://useapi.net/docs/api-minimax-v1/post-minimax-music-reference --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> music/reference description: "Upload an MP3 or WAV as a reference track via POST music/reference in the useapi.net MiniMax API v1 — returns a reusable musicId that POST music/create turns into a cover." parent: MiniMax API nav_order: 2950 --- ## Upload Reference Music August 21, 2026 (November 16, 2026) --- Uploads an audio file and registers it on the MiniMax account as a reference track. The response carries a `musicId` you pass to [POST music/create](/docs/api-minimax-v1/post-minimax-music-create) as `referenceMusicId`, which produces a **cover** — a new song built in the character of the reference. Upload once and reuse. A reference is a permanent record on the account, so the same `musicId` can back any number of covers — there is no need to re-send the file per song. MiniMax transcribes the lyrics from the audio during upload and returns them, which is how you get the original words if you want the cover to keep them. > **https://api.useapi.net/v1/minimax/music/reference?account={account}&name={name}** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: audio/mpeg ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. - `Content-Type` is **required** and must match the file you are sending. Supported values: `audio/mpeg`, `audio/mp3`, `audio/wav`, `audio/wave`, `audio/x-wav`. ##### Request Body The raw bytes of the audio file — not JSON, and not `multipart/form-data`. ##### Query Parameters - `account` is optional when only one account is configured. If you have several MiniMax accounts configured, this parameter becomes **required**. - `name` is optional, the title the reference is stored under. Max length `40`. Defaults to a timestamp. **Notes:** - Both MP3 and WAV are accepted. MiniMax re-encodes whatever you send to MP3 and serves it back from its own CDN, so the `audio_url` in the response is a re-hosted copy rather than your original file. - There is no length limit worth planning around. A 20-second excerpt and a full 3-minute song both upload and both work as references. - The reference does not set the cover's length — `lyrics` does, exactly as it does for an ordinary song. To get a cover close to the reference's length, pass the reference's own `lyrics` back in. - How strongly the reference comes through varies, and a detailed `prompt` competes with it. Omit `prompt` entirely and the model takes its cues from the audio alone. - Uploading does not generate anything and costs no credits. Only [POST music/create](/docs/api-minimax-v1/post-minimax-music-create) does. - References appear in [GET music](/docs/api-minimax-v1/get-minimax-music) under `type=reference`, and are hidden from the default `type=song` listing. - You do not have to upload at all to make a cover. Any song already on the account works as a reference — pass its `musicId` straight to `referenceMusicId`. - Only upload audio you have the rights to use. ##### Responses **201** **201 Created** The reference is ready immediately — `statusLabel` is already `completed` and `audio_url` already points at the stored copy. ```json { "musicId": "user:12345-minimax:123456789012345678-music:987654321098766", "title": "Last Train 20s", "idea": "", "lyrics": "[Chorus]\nin my ear.\n\n[Verse]", "audio_url": "https://cdn.hailuoai.video/moss/prod/2026-08-21-09/moss-audio/user_music/1700000000000000000-987654321098766.mp3", "cover_url": "https://cdn.hailuoai.video/moss/staging/2025-06-22-16/music_cover/1700000000000000002-other_44.png", "model": "", "status": 2, "statusLabel": "completed", "statusFinal": true, "typeLabel": "reference", "instrumental": false, "duration": 20036, "create_time": 1787276488868, "update_time": 1787276488868, "is_favorite": false, "tag_list": [] } ``` **400** **400 Bad Request** An unsupported `Content-Type`: ```json { "error": "Content-Type (image/png) not supported. Valid values: audio/mpeg,audio/mp3,audio/wav,audio/wave,audio/x-wav", "code": 400 } ``` An empty body: ```json { "error": "Content is empty", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **596** **596 Account Error** ```json { "error": "Your minimax account has pending error. Please address this issue at https://useapi.net/docs/api-minimax-v1/post-minimax-accounts-account before making any new API calls.", "code": 596 } ``` ##### Model The reference track, already complete, with its transcribed lyrics and the `musicId` to pass to [POST music/create](/docs/api-minimax-v1/post-minimax-music-create) as `referenceMusicId`. <details markdown="block" class="model-details"> <summary>The reference track record, field by field</summary> ```typescript { // TypeScript, all fields are optional musicId: string, // Pass to POST music/create as referenceMusicId title: string, // The name you supplied idea: string, // Always empty on a reference lyrics: string, // Transcribed from the audio by MiniMax audio_url: string, // MiniMax's re-hosted copy of your file cover_url: string, // Cover art, assigned automatically model: string, // Always empty on a reference status: number, // 2 — a reference is complete on arrival statusLabel: string, statusFinal: boolean, typeLabel: string, // Always "reference" here instrumental: boolean, duration: number, // Milliseconds create_time: number, update_time: number, is_favorite: boolean, tag_list: [{ tag_name: string, tag_type: number }] } ``` </details> ##### Examples **Curl** ```bash curl "https://api.useapi.net/v1/minimax/music/reference?name=Last%20Train%2020s" \ -H "Authorization: Bearer …" \ -H "Content-Type: audio/mpeg" \ --data-binary "@reference.mp3" ``` **JavaScript** ```javascript import { readFile } from "node:fs/promises"; const file = await readFile("reference.mp3"); const response = await fetch("https://api.useapi.net/v1/minimax/music/reference?name=Last Train 20s", { method: "POST", headers: { "Authorization": "Bearer …", "Content-Type": "audio/mpeg" }, body: file }); const reference = await response.json(); console.log(reference.musicId, reference.duration, reference.lyrics); ``` **Python** ```python import requests with open("reference.mp3", "rb") as file: response = requests.post( "https://api.useapi.net/v1/minimax/music/reference", headers={ "Authorization": "Bearer …", "Content-Type": "audio/mpeg" }, params={"name": "Last Train 20s"}, data=file.read() ) reference = response.json() print(reference["musicId"], reference["duration"]) print(reference["lyrics"]) ``` Then turn it into a cover: ```bash curl "https://api.useapi.net/v1/minimax/music/create" \ -H "Authorization: Bearer …" \ -H "Content-Type: application/json" \ -d '{ "referenceMusicId": "user:12345-minimax:123456789012345678-music:987654321098766", "prompt": "italo disco, driving synth bass, bright arpeggios", "title": "Last Train Italo" }' ``` === URL: https://useapi.net/docs/api-minimax-v1/post-minimax-speech-clone-voice === Document URL: https://useapi.net/docs/api-minimax-v1/post-minimax-speech-clone-voice --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> speech/clone-voice description: "Clone a voice from uploaded samples via POST speech/clone-voice in the useapi.net MiniMax API v1, then narrate with it by passing the returned voice id to any speech call." parent: MiniMax API nav_order: 1892 --- ## Clone a voice using uploaded audio samples December 27, 2024 (November 16, 2026) --- Builds a new voice from audio samples uploaded with [POST speech/upload-sample](/docs/api-minimax-v1/post-minimax-speech-upload-sample). The voice it returns can be passed as `voice_id` to any of the speech endpoints. Cloned voices occupy a slot, and how many an account gets depends on its MiniMax plan. [GET speech/equity](/docs/api-minimax-v1/get-minimax-speech-equity) reports `used` and `total`, and [POST speech/delete-voice](/docs/api-minimax-v1/post-minimax-speech-delete-voice) frees one. Treat the count as advisory rather than as a gate — MiniMax lets `used` exceed `total`, and the authoritative refusal is error `2600010` on the clone itself. If you need more slots than a plan allows, configure another [www.minimax.io/audio](https://www.minimax.io/audio) account. Please be patient, voice cloning can take up to 60 seconds. This endpoint can only support one or two parallel tasks maximum, so organize internal queuing if you need to clone many voices in bulk. > **https://api.useapi.net/v1/minimax/speech/clone-voice** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "files": "user:user_id-minimax:account-file:file_id1,user:user_id-minimax:account-file:file_id2", "voice_name": "Doctor Who", "language_tag": "English" } ``` - `voice_name` is **required**. Maximum length: 30 characters. - `language_tag` is **required**. Use tag_name from array `voice_tag_language` of [GET speech/config](/docs/api-minimax-v1/get-minimax-speech-config). - `files` is **required**. Provide up to 10 comma-separated `fileID` values of audio samples uploaded via [POST speech/upload-sample](/docs/api-minimax-v1/post-minimax-speech-upload-sample). Each audio sample should be between 10 to 60 seconds long. - `need_noise_reduction` is optional. Supported values: `true` (default), `false`. ##### Responses **200** **200 OK** ```json { "voice_id": "user:user_id-minimax:account_id-voice:voice_id", "parent_voice_id": "0", "voice_name": "Doctor Who", "tag_list": [ "English" ], "file_id": "1234567890", "cover_url": "https://cdn.hailuoai.video/...png", "create_time": 1122334455667, "update_time": 1122334455667, "collected": false, "voice_status": 2, "sample_audio": "https://cdn.hailuoai.video/...mp3", "uniq_id": "<uniq_id>", "group_id": "<group_id>" } ``` **400** **400 Bad Request** ```json { "error": "<Error message>" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized" } ``` **596** **596 Account Error** ```json { "error": "Your minimax account has pending error. Please address this issue at https://useapi.net/docs/api-minimax-v1/post-minimax-accounts-account before making any new API calls.", "code": 596 } ``` ##### Model The new cloned voice, with the `voice_id` to pass to the speech endpoints, its name and tags. <details markdown="block" class="model-details"> <summary>The new cloned voice, field by field</summary> ```typescript { // TypeScript, all fields are optional voice_id: string parent_voice_id: string voice_name: string tag_list: string[] file_id: string cover_url: string create_time: number update_time: number collected: boolean voice_status: number sample_audio: string uniq_id: string group_id: string } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST https://api.useapi.net/v1/minimax/speech/clone-voice \ -d '{"voice_name": "…", "language_tag": "…", "files": …}' ``` **JavaScript** ``` javascript const voice_name = "Voice Name"; const language_tag = "Voice Language"; const files = "fileID1,fileID2"; const apiUrl = `https://api.useapi.net/v1/minimax/speech/clone-voice`; const api_token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${api_token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ voice_name, language_tag, files }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests voice_name = "Voice Name" language_tag = "Voice Language" files = "fileID1,fileID2" apiUrl = f"https://api.useapi.net/v1/minimax/speech/clone-voice" api_token = "API token" maxJobs = 1 headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {api_token}" } body = { "voice_name": f"{voice_name}", "language_tag": f"{language_tag}", "files": files } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-minimax-v1/post-minimax-speech-create-mp3 === Document URL: https://useapi.net/docs/api-minimax-v1/post-minimax-speech-create-mp3 --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> speech/create-mp3 description: "Generate speech and get the MP3 back in a single call via POST speech/create-mp3 in the useapi.net MiniMax API v1 — up to 3,000 characters, ten voice models, word timings." parent: MiniMax API nav_order: 1860 --- ## Create text-to-speech audio December 23, 2024 (November 16, 2026) --- This endpoint creates an mp3 audio from the provided text and returns it in one call. For longer text use [POST speech/create](/docs/api-minimax-v1/post-minimax-speech-create), which takes 5,000 characters, or 10,000 on a `turbo` model. 600+ pre-built voices provided by [GET speech/voices](/docs/api-minimax-v1/get-minimax-speech-voices), tagged for filtering with `tag_list`: * Languages: 40, from English, Chinese (Mandarin and Cantonese), Japanese and Korean through to Thai, Hindi, Tamil and Afrikaans * Emotions: happy, sad, angry, fearful, disgusted, surprised, neutral, fluent * Accents: `EN-US (General)`, `EN-Australian`, `EN-British`, `EN-Indian`, `CN-Northern`, `CN-Southern` * Ages: `Child`, `Young`, `Middle-aged`, `Elderly` * Genders: `Male`, `Female` `tag_list` matches these strings exactly, including case. A tag it does not recognise is ignored rather than rejected, so a typo silently *widens* the result instead of narrowing it — `Female,Middle-Aged` returns the same 310 voices as `Female` alone, spanning every age. Check the count when you add a filter. [GET speech/config](/docs/api-minimax-v1/get-minimax-speech-config) returns the tags the picker UI offers, updated as MiniMax adds to them. Voices carry others besides — `Documentary`, `Calm` and `Adult` all match voices without appearing there. > **https://api.useapi.net/v1/minimax/speech/create-mp3** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "account": "Optional MiniMax www.minimax.io/audio API account", "text": "Required text", "voice_id": "Required voice id" } ``` - `account` is optional when only one [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `text` is **required**, the words to speak. Maximum `3000` characters whatever the model allows, which is around four minutes of speech. Supports [inline markup](/docs/api-minimax-v1/post-minimax-speech-create#text-markup) for emotion, sounds and pauses — for example `<#0.5#>` inserts a half-second pause. - `voice_id` is **required**. Use [GET speech/voices](/docs/api-minimax-v1/get-minimax-speech-voices) to get list of all available voices. - `model` is optional. Default: `speech-2.8-hd`. See [Model Comparison](#model-comparison-speech) below for the ten models, their character ceilings and their credit ratios. - `language_boost` is optional. Use tag_name from array `voice_tag_language` of [GET speech/config](/docs/api-minimax-v1/get-minimax-speech-config). Default value `Auto`. - `emotion` is optional. Use value from array `t2a_emotion` of [GET speech/config](/docs/api-minimax-v1/get-minimax-speech-config). Default value `Auto`. - `vol` is optional. Default 1. - `speed` is optional. Valid range: 0.5…2, default 1. - `pitch` is optional. Valid range: -12…12, default 0. - `deepen_lighten` is optional. Valid range: -100…100, default 0. - `stronger_softer` is optional. Valid range: -100…100, default 0. - `nasal_crisp` is optional. Valid range: -100…100, default 0. - `spacious_echo` is optional. Supported values: `true`, `false` (default). - `lofi_telephone` is optional. Supported values: `true`, `false` (default). - `robotic` is optional. Supported values: `true`, `false` (default). - `auditorium_echo` is optional. Supported values: `true`, `false` (default). ##### Model Comparison: Speech | Model | Max characters | Credits per character | Status | |---|---|---|---| | `speech-2.8-hd` | 5,000 | 1 | Current, and the default | | `speech-2.8-turbo` | 10,000 | 0.6 | Current | | `speech-2.6-hd` | 5,000 | 1 | Previous generation | | `speech-2.6-turbo` | 10,000 | 0.6 | Previous generation | | `speech-2.5-hd-preview` | 5,000 | 1 | Superseded by 2.6 | | `speech-2.5-turbo-preview` | 10,000 | 0.6 | Superseded by 2.6 | | `speech-02-hd` | 5,000 | 1 | Legacy | | `speech-02-turbo` | 10,000 | 0.6 | Legacy | | `speech-01-hd` | 5,000 | 1 | Legacy | | `speech-01-turbo` | 10,000 | 0.6 | Legacy | Use `speech-2.8-hd` unless you have a reason not to. The older models stay selectable because they are still live at MiniMax, and because regenerating audio to match something made earlier needs the model that made it — not because they are worth picking for new work. Within a generation, `hd` and `turbo` are the same model tuned differently. `turbo` costs 40% less per character and accepts twice the text in a single call. It is not measurably faster — on identical 990-character text the two came out level — so pick `turbo` for the cheaper rate and the higher ceiling, and `hd` when voice quality matters most. Sending more than a model accepts returns `400` before anything is generated, so an oversized request never costs credits. The message names the model and its limit — `Parameter text length (5001) exceeds 5000 characters for model speech-2.8-hd` — except at the absolute 10,000 ceiling, which is checked first and reports the limit without the model. On this endpoint the per-model ceiling never comes into play — `text` is capped at 3,000 characters whichever model you pick, because the connection is held open for the whole generation and 3,000 characters is about as long as a caller should be asked to wait. The ceilings above apply to [POST speech/create](/docs/api-minimax-v1/post-minimax-speech-create). ##### Responses **200** **200 OK** Use returned `audio_url` to download generated mp3 audio file. Use returned `audio_id` to retrieve full details using [GET speech/`audio_id`](/docs/api-minimax-v1/get-minimax-speech_audio_id). ```json { "audio_id": "user:user_id-minimax:account_id-audio:audio_id", "audio_length": 0, "audio_sample_rate": 0, "audio_size": 0, "bitrate": 0, "word_count": 0, "invisible_character_ratio": 0, "usage_characters": 22, "input_sensitive": false, "trace_id": "<trace id>", "chunks": 2, "subtitles": [ { "text": "Phase one verification", "time_begin": 0, "time_end": 2245.2, "text_begin": 0, "text_end": 22, "timestamped_words": [] } ], "audio_review": 0, "user_id": "123456789012345678", "audio_title": "<autogenerated title>", "audio_url": "https://cdn.hailuoai.video/...mp3", "update_time": 123456789, "text": "Phase one verification", "voice_name": "Deep Storyteller", "status": 0, "async": 0, "has_srt": true, "has_wav": true } ``` Only `usage_characters` is populated on the size fields — `audio_length`, `audio_sample_rate`, `audio_size` and `bitrate` all come back `0`, which is what MiniMax sends. **400** **400 Bad Request** ```json { "error": "<Error message>" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized" } ``` **412** **412 Precondition Failed** The account cannot pay for the generation. MiniMax reports this two different ways, and both mean the same thing — check the speech balance with [GET features](/docs/api-minimax-v1/get-minimax-features), where `audio.total_credit` is the MiniMax audio wallet the API bills against. ```json { "error": "Insufficient credits. Please recharge to get more credits or try again next day." } ``` ```json { "error": "MiniMax rejected the generation — the account is out of speech credits. Confirm with GET /features (audio.total_credit) and top up at https://www.minimax.io/audio/subscribe." } ``` **429** **429 Too Many Requests** The account already has its maximum number of speech generations in flight. The running generations are unaffected — retry once one finishes. The ceiling depends on the MiniMax plan. A free account allows three. ```json { "error": "This account already has the maximum number of speech generations running. Retry once one completes.", "code": 429 } ``` **504** **504 Gateway Timeout** The generation did not finish inside the 90 second ceiling this endpoint waits: ```json { "error": "minimax did not finish within 90 seconds. Use POST /v1/minimax/speech/create for text this long.", "code": 504 } ``` Or it finished but had not appeared in the account history in time: ```json { "error": "Audio was generated but did not appear in history in time. Call GET /v1/minimax/speech/ to retrieve it.", "code": 504 } ``` **596** **596 Account Error** ```json { "error": "Your minimax account has pending error. Please address this issue at https://useapi.net/docs/api-minimax-v1/post-minimax-accounts-account before making any new API calls.", "code": 596 } ``` ##### Model The finished speech clip, with its `audio_id`, the MP3 in `audio_url`, and per-phrase timings in `subtitles`. <details markdown="block" class="model-details"> <summary>The finished speech clip, field by field</summary> ```typescript { // TypeScript, all fields are optional audio_id: string audio_length: number audio_sample_rate: number audio_size: number bitrate: number word_count: number invisible_character_ratio: number usage_characters: number input_sensitive: boolean trace_id: string chunks: number // Non-heartbeat frames received, 2 for a short generation subtitles: { // Per-phrase timings, milliseconds text: string time_begin: number time_end: number text_begin: number text_end: number timestamped_words: [] }[] audio_review: number user_id: string // The MiniMax account id audio_title: string audio_url: string update_time: number text: string voice_name: string status: number async: number has_srt: boolean // Word timings are available for this recording has_wav: boolean // A WAV rendition exists alongside the MP3 } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST "https://api.useapi.net/v1/minimax/speech/create-mp3" \ -d '{"text": "…", "voice_id": "…"}' ``` **JavaScript** ``` javascript const text = "text"; const voice_id = "voice_id"; const apiUrl = `https://api.useapi.net/v1/minimax/speech/create-mp3`; const token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ text, voice_id }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests text = "text" voice_id = "voice_id" apiUrl = f"https://api.useapi.net/v1/minimax/speech/create-mp3" token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } body = { "text": f"{text}", "voice_id": f"{voice_id}" } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-minimax-v1/post-minimax-speech-create === Document URL: https://useapi.net/docs/api-minimax-v1/post-minimax-speech-create --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> speech/create description: "Generate speech from text via POST speech/create in the useapi.net MiniMax API v1 — ten models, emotion and pause markup, word timings, a replyUrl callback or an SSE stream." parent: MiniMax API nav_order: 1850 --- ## Create Speech August 24, 2026 (November 16, 2026) --- Converts text to speech and returns an `audioId` immediately. Generation continues at MiniMax, and you either wait for the [replyUrl](#request-body) callback or poll [GET speech/`audioId`](/docs/api-minimax-v1/get-minimax-speech_audio_id). Use it for anything longer than a sentence or two. [POST speech/create-mp3](/docs/api-minimax-v1/post-minimax-speech-create-mp3) holds the connection open until the audio is finished, so it stops at `3,000` characters. This one takes `5,000`, or `10,000` on a `turbo` model — roughly a quarter of an hour of speech. ##### Model Comparison: Speech | Model | Max characters | Credits per character | Status | |---|---|---|---| | `speech-2.8-hd` | 5,000 | 1 | Current, and the default | | `speech-2.8-turbo` | 10,000 | 0.6 | Current | | `speech-2.6-hd` | 5,000 | 1 | Previous generation | | `speech-2.6-turbo` | 10,000 | 0.6 | Previous generation | | `speech-2.5-hd-preview` | 5,000 | 1 | Superseded by 2.6 | | `speech-2.5-turbo-preview` | 10,000 | 0.6 | Superseded by 2.6 | | `speech-02-hd` | 5,000 | 1 | Legacy | | `speech-02-turbo` | 10,000 | 0.6 | Legacy | | `speech-01-hd` | 5,000 | 1 | Legacy | | `speech-01-turbo` | 10,000 | 0.6 | Legacy | Use `speech-2.8-hd` unless you have a reason not to. The older models stay selectable because they are still live at MiniMax, and because regenerating audio to match something made earlier needs the model that made it — not because they are worth picking for new work. Within a generation, `hd` and `turbo` are the same model tuned differently. `turbo` costs 40% less per character and accepts twice the text in a single call. It is not measurably faster — on identical 990-character text the two came out level — so pick `turbo` for the cheaper rate and the higher ceiling, and `hd` when voice quality matters most. Sending more than a model accepts returns `400` before anything is generated, so an oversized request never costs credits. The message names the model and its limit — `Parameter text length (5001) exceeds 5000 characters for model speech-2.8-hd` — except at the absolute 10,000 ceiling, which is checked first and reports the limit without the model. 600+ pre-built voices provided by [GET speech/voices](/docs/api-minimax-v1/get-minimax-speech-voices), tagged for filtering with `tag_list`: * Languages: 40, from English, Chinese (Mandarin and Cantonese), Japanese and Korean through to Thai, Hindi, Tamil and Afrikaans * Emotions: happy, sad, angry, fearful, disgusted, surprised, neutral, fluent * Accents: `EN-US (General)`, `EN-Australian`, `EN-British`, `EN-Indian`, `CN-Northern`, `CN-Southern` * Ages: `Child`, `Young`, `Middle-aged`, `Elderly` * Genders: `Male`, `Female` `tag_list` matches these strings exactly, including case. A tag it does not recognise is ignored rather than rejected, so a typo silently *widens* the result instead of narrowing it — `Female,Middle-Aged` returns the same 310 voices as `Female` alone, spanning every age. Check the count when you add a filter. [GET speech/config](/docs/api-minimax-v1/get-minimax-speech-config) returns the tags the picker UI offers, updated as MiniMax adds to them. Voices carry others besides — `Documentary`, `Calm` and `Adult` all match voices without appearing there. > **https://api.useapi.net/v1/minimax/speech/create** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "account": "123456789012345678", "text": "Good morning. Here is the weather for the week ahead.", "voice_id": "380426458095854", "model": "speech-2.8-hd", "speed": 1, "vol": 1, "pitch": 0, "emotion": "happy", "language_boost": "English", "stream": false, "replyUrl": "https://webhook.site/abc", "replyRef": "your-reference-id" } ``` - `account` is optional when only one account is configured. If you have several MiniMax accounts configured, this parameter becomes **required**. - `text` is **required**, the words to speak. Max length depends on the model — `5000` for `hd`, `10000` for `turbo`. Supports [inline markup](#text-markup) for emotion, sounds and pauses. - `voice_id` is **required**, from [GET speech/voices](/docs/api-minimax-v1/get-minimax-speech-voices). Accepts a MiniMax voice id or the `voiceId` of a voice you cloned with [POST speech/clone-voice](/docs/api-minimax-v1/post-minimax-speech-clone-voice). - `model` is optional. Default: `speech-2.8-hd`. See [Model Comparison](#model-comparison-speech) for the full list. - `speed` is optional, playback rate. Default: `1`. Range `0.5` to `2`. - `vol` is optional, volume. Default: `1`. Minimum `1`. - `pitch` is optional. Default: `0`. Range `-12` to `12`. - `emotion` is optional. Default: `Auto`. Use a value from the `t2a_emotion` array of [GET speech/config](/docs/api-minimax-v1/get-minimax-speech-config), or leave it out and mark up the text instead. - `language_boost` is optional, biases pronunciation toward one language. Default: `Auto`. - `deepen_lighten`, `stronger_softer`, `nasal_crisp` are optional voice effects. Default: `0`. Range `-100` to `100`. - `spacious_echo`, `lofi_telephone`, `robotic`, `auditorium_echo` are optional effect switches. Default: `false`. - `stream` is optional, return the audio as Server-Sent Events instead of a JSON response. Default: `false`. The streaming response is `200` with `Content-Type: text/event-stream`, not the `201` documented below. See [Streaming](#streaming). - `replyUrl` is optional, we will send a POST request to this URL when generation completes. Maximum length 1024 characters. Callback body has the same JSON shape as one row of [GET speech](/docs/api-minimax-v1/get-minimax-speech#model), minus `audio_id`, plus `audioId`, `replyRef`, `replyUrl`, `code`, `statusLabel` and `statusFinal`. It is built from the account history, so it is the lighter list shape — `voice_info`, `model`, `cost_credit` and `effects` are only on [GET speech/`audioId`](/docs/api-minimax-v1/get-minimax-speech_audio_id#model). If a generation is still unfinished 10 minutes after it was submitted we stop tracking it and POST `{"code": 400, "error": "More than 10 minutes have passed, the task has expired."}` to the same URL. - `replyRef` is optional, your own reference string, echoed back on the `replyUrl` callback. Maximum length 1024 characters. **Notes:** - Store the `audioId`. MiniMax assigns no identifier at submit time, so it is the only handle on the generation. It resolves for 7 days. - Speech is billed per character, 1 credit on an `hd` model and 0.6 on a `turbo` one, rounded up. [GET speech/`audioId`](/docs/api-minimax-v1/get-minimax-speech_audio_id) reports what was charged as `cost_credit`. [POST speech/create-mp3](/docs/api-minimax-v1/post-minimax-speech-create-mp3) reports `usage_characters` instead, the character count before the ratio. - Generation time scales with the length of the text, from a few seconds up to about 80 seconds at the 10,000-character ceiling. Use `replyUrl` or poll rather than assuming a fixed wait. - Speech bills against the MiniMax audio subscription, the same one music uses. Without it the call returns `412`, however much video credit the account holds. ##### Responses **201** **201 Created** ```json { "audioId": "user:12345-minimax:123456789012345678-audio:178737039436895391", "replyRef": "your-reference-id", "replyUrl": "https://webhook.site/abc", "status": 0, "statusLabel": "pending", "statusFinal": false } ``` **400** **400 Bad Request** Text longer than the chosen model accepts: ```json { "error": "Parameter text length (6000) exceeds 5000 characters for model speech-2.8-hd", "code": 400 } ``` An unknown `voice_id`: ```json { "error": "Incorrect voice_id (2600006)" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **412** **412 Precondition Failed** The account cannot pay for the generation. MiniMax reports this two different ways, and both mean the same thing — check the speech balance with [GET features](/docs/api-minimax-v1/get-minimax-features), where `audio.total_credit` is the MiniMax audio wallet the API bills against. ```json { "error": "Insufficient credits. Please recharge to get more credits or try again next day." } ``` ```json { "error": "MiniMax rejected the generation — the account is out of speech credits. Confirm with GET /features (audio.total_credit) and top up at https://www.minimax.io/audio/subscribe." } ``` **429** **429 Too Many Requests** The account already has its maximum number of speech generations in flight. The running generations are unaffected — retry once one finishes. The ceiling depends on the MiniMax plan. A free account allows three. ```json { "error": "This account already has the maximum number of speech generations running. Retry once one completes.", "code": 429 } ``` **504** **504 Gateway Timeout** MiniMax accepted the connection but sent nothing back within 30 seconds. ```json { "error": "minimax did not respond within 30 seconds", "code": 504 } ``` **596** **596 Account Error** ```json { "error": "Your minimax account has pending error. Please address this issue at https://useapi.net/docs/api-minimax-v1/post-minimax-accounts-account before making any new API calls.", "code": 596 } ``` ##### Model The new speech job, pending, with the `audioId` to poll with [GET speech/`audioId`](/docs/api-minimax-v1/get-minimax-speech_audio_id) until `statusFinal` is `true`. <details markdown="block" class="model-details"> <summary>The new speech job, field by field</summary> ```typescript { // TypeScript, all fields are optional audioId: string, // Pass to GET speech/audioId replyRef: string, replyUrl: string, status: number, // 0 while pending statusLabel: string, // pending statusFinal: boolean // false until the generation completes } ``` </details> ##### Text markup Three kinds of markup can be embedded directly in `text`, and they can be combined. Only emotion tags are excluded from billing — sound and pause markup counts toward the character total like any other text. | Markup | Example | Values | |---|---|---| | Emotion | `{happy}Great news!{/happy}` | `happy`, `sad`, `angry`, `fearful`, `disgusted`, `surprised`, `neutral`, `fluent`. Max 15 spans per request | | Sound | `That's wonderful (chuckle)` | `laughs`, `chuckle`, `coughs`, `clear-throat`, `groans`, `breath`, `pant`, `inhale`, `exhale`, `gasps`, `sniffs`, `sighs`, `snorts`, `burps`, `lip-smacking`, `humming`, `hissing`, `emm`, `sneezes` | | Pause | `Wait for it <#0.5#> there!` | Seconds, from `0.01` to `99.99` | ```json { "text": "{happy}The results are in{/happy} (chuckle) <#0.5#> and we did it." } ``` ##### Word timings Word timings come back as a `subtitles` array with millisecond boundaries per phrase, which is what captions or a karaoke-style display need. They reach you on two paths only: the SSE `done` event, and [POST speech/create-mp3](/docs/api-minimax-v1/post-minimax-speech-create-mp3). MiniMax does not store them, so neither [GET speech/`audioId`](/docs/api-minimax-v1/get-minimax-speech_audio_id) nor the `replyUrl` callback can return them — those report `has_srt` to tell you timings existed, but not the timings themselves. If you need captions for text over 3,000 characters, use `stream` and keep the `done` payload. ```json "subtitles": [ { "text": "The results are in", "time_begin": 0, "time_end": 1211.9, "text_begin": 0, "text_end": 18, "timestamped_words": [] } ] ``` Use `time_begin` and `time_end`. The `text_begin` and `text_end` fields are reported by MiniMax but do not reliably index into either the full text or the phrase, so they are passed through rather than interpreted. ##### Streaming Set `stream` to `true` and the response is `200` with `Content-Type: text/event-stream`, instead of the `201` JSON documented in [Responses](#responses). The response carries an `X-Audio-Id` header with the `audioId`. Streaming trades the callback for a shorter wait — the first audio arrives about four seconds in, rather than after the whole generation. The MP3 arrives in pieces that have to be joined, so buffer them as they come. ###### Events | Event | Description | When Sent | |---|---|---| | `audio` | `{ "audioId": "...", "format": "mp3" \| "wav", "complete": false, "chunk": "<base64>" }` | As each piece is rendered | | `done` | `{ "audioId": "...", "subtitles": [...], "usage_characters": 112 }` | When the generation finishes | | `error` | `{ "error": "...", "code": 412 }` | MiniMax rejected the generation, the connection closed before any audio arrived (`502`), or the 5 minute cap fired (`504`) — `code` carries the HTTP status | | `: keepalive` | An SSE comment, not an event | Every 10 seconds | ###### Handling the `audio` events Two different things arrive on this event, and `format` tells them apart. `format: "mp3"` events are **chunks**, and `complete` is `false`. Append them in arrival order and the result is a plain MP3. Short text sends a single chunk, but a 10,000-character generation sends around 40 of them over a minute or two, so treat it as a stream rather than assuming one. `format: "wav"` with `complete: true` is the same speech again as a whole WAV file, delivered after the MP3 chunks. It is roughly four times the size and is not part of the MP3 — do not append it. It arrives reliably on short text, and on very long generations the stream may end after the MP3 chunks without it. The simplest correct client keeps the MP3 chunks, ignores the WAV, and assembles once the stream ends — using `done` for the subtitles when it arrives, rather than as the trigger to assemble. ###### How the stream ends Every stream terminates with exactly one of `done` or `error`, so you never have to treat a closed connection as ambiguous. - `done` — the audio is finished. On a long generation MiniMax stops after the last MP3 chunk and drops the connection without sending its final frame, so `done` arrives with no `subtitles`. Read those from [GET speech/`audioId`](/docs/api-minimax-v1/get-minimax-speech_audio_id), which is also where to confirm the recording if you need certainty. - `error` with `502` — the connection closed before any audio arrived. - `error` with `504` — the generation ran past the 5 minute cap. None of these lose the recording. A streamed generation is registered with the scheduler exactly like the default mode, so it still reconciles, `replyUrl` still fires, and the `audioId` from the `X-Audio-Id` header still resolves through [GET speech/`audioId`](/docs/api-minimax-v1/get-minimax-speech_audio_id). Hanging up mid-stream is safe for the same reason. ##### Examples **Curl** ```bash curl "https://api.useapi.net/v1/minimax/speech/create" \ -H "Authorization: Bearer …" \ -H "Content-Type: application/json" \ -d '{ "text": "Good morning. Here is the weather for the week ahead.", "voice_id": "380426458095854", "model": "speech-2.8-turbo", "replyUrl": "https://webhook.site/abc" }' ``` **JavaScript** ```javascript const response = await fetch("https://api.useapi.net/v1/minimax/speech/create", { method: "POST", headers: { "Authorization": "Bearer …", "Content-Type": "application/json" }, body: JSON.stringify({ text: "Good morning. Here is the weather for the week ahead.", voice_id: "380426458095854", model: "speech-2.8-turbo", replyUrl: "https://webhook.site/abc" }) }); const { audioId } = await response.json(); console.log(audioId); ``` **Python** ```python import requests response = requests.post( "https://api.useapi.net/v1/minimax/speech/create", headers={ "Authorization": "Bearer …", "Content-Type": "application/json" }, json={ "text": "Good morning. Here is the weather for the week ahead.", "voice_id": "380426458095854", "model": "speech-2.8-turbo", "replyUrl": "https://webhook.site/abc" } ) print(response.json()["audioId"]) ``` ###### Streaming example Set `stream` and the response is an event stream rather than JSON. Two pieces: read the events, then play the chunks. Both are folded up — open what you need. <details markdown="block"> <summary>Read the stream — collect the MP3 chunks and the subtitles</summary> ```javascript const response = await fetch("https://api.useapi.net/v1/minimax/speech/create", { method: "POST", headers: { "Authorization": "Bearer …", "Content-Type": "application/json" }, body: JSON.stringify({ text: "Good morning. Here is the weather for the week ahead.", voice_id: "380426458095854", stream: true }) }); const audioId = response.headers.get("X-Audio-Id"); const reader = response.body.getReader(); const decoder = new TextDecoder(); let buffer = ""; const chunks = []; let subtitles = null; while (true) { const { done, value } = await reader.read(); if (done) break; buffer += decoder.decode(value, { stream: true }); const parts = buffer.split("\n\n"); buffer = parts.pop(); for (const part of parts) { const event = part.match(/^event: (.+)$/m)?.[1]; const data = part.match(/^data: (.+)$/m)?.[1]; if (!event || !data) continue; const payload = JSON.parse(data); if (event === "audio" && payload.format === "mp3") chunks.push(Uint8Array.from(atob(payload.chunk), c => c.charCodeAt(0))); if (event === "done") subtitles = payload.subtitles; if (event === "error") console.error(payload.error); } } const mp3 = new Blob(chunks, { type: "audio/mpeg" }); console.log(audioId, mp3.size, subtitles); ``` </details> That collects the whole recording and plays it at the end. To hear it while it is still rendering, feed each chunk to a `MediaSource` — it splices MP3 frames correctly, which decoding chunks individually does not: <details markdown="block"> <summary>Progressive player — play the stream as it arrives</summary> ```javascript const audio = document.querySelector("audio"); const mediaSource = new MediaSource(); audio.src = URL.createObjectURL(mediaSource); const ready = new Promise(resolve => mediaSource.addEventListener("sourceopen", resolve, { once: true })); await ready; const sourceBuffer = mediaSource.addSourceBuffer("audio/mpeg"); const pending = []; const flush = () => { if (sourceBuffer.updating || !pending.length) return; sourceBuffer.appendBuffer(pending.shift()); }; sourceBuffer.addEventListener("updateend", flush); /* inside the event loop above, instead of collecting into `chunks` */ if (event === "audio" && payload.format === "mp3") { pending.push(Uint8Array.from(atob(payload.chunk), c => c.charCodeAt(0))); flush(); if (audio.paused) audio.play().catch(() => {}); } /* once the stream ends, after the queue has drained */ if (event === "done") { const close = () => (pending.length || sourceBuffer.updating) ? setTimeout(close, 50) : mediaSource.endOfStream(); close(); } ``` Two things worth knowing. **Append, do not decode.** Only the first chunk carries an MP3 header and the rest are bare frames, so decoding them individually and splicing the results produces gaps and overlaps — `MediaSource` handles the frame boundaries for you. And **`appendBuffer` is asynchronous**: appending again while `updating` is true throws, hence the queue and the `updateend` handler. Check `MediaSource.isTypeSupported("audio/mpeg")` first and fall back to assembling a `Blob` at the end, as in the example above. </details> === URL: https://useapi.net/docs/api-minimax-v1/post-minimax-speech-delete-voice === Document URL: https://useapi.net/docs/api-minimax-v1/post-minimax-speech-delete-voice --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> speech/delete-voice description: "Delete a cloned voice via POST speech/delete-voice in the useapi.net MiniMax API v1, freeing one of the account's limited voice cloning slots." parent: MiniMax API nav_order: 1894 --- ## Delete cloned voice December 27, 2024 (August 24, 2026) --- This endpoint deletes a voice cloned via [POST speech/clone-voice](/docs/api-minimax-v1/post-minimax-speech-clone-voice). This endpoint returns `200` for a cloned voice that does not exist or has already been deleted. An error from MiniMax is passed through, so check the status rather than assuming it always succeeds. > **https://api.useapi.net/v1/minimax/speech/delete-voice** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "voice_id": "user:1234-minimax:1234567890123456789-voice:abcdef" } ``` - `voice_id` is **required**, use value of field voice_id returned by [POST speech/clone-voice](/docs/api-minimax-v1/post-minimax-speech-clone-voice) or [GET speech/voices/?is_system=false](/docs/api-minimax-v1/get-minimax-speech-voices) This endpoint takes no `account` parameter. Cloned voice ids are returned in a wrapped form that already names the account, so it is read from `voice_id` — including when several accounts are configured. Sending `account` returns `400 Parameter account not supported`. ##### Responses **200** **200 OK** **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "Wrong username/password combination.", "This account has been suspended." "code": 401 } ``` **596** **596 Account Error** ```json { "error": "Your minimax account has pending error. Please address this issue at https://useapi.net/docs/api-minimax-v1/post-minimax-accounts-account before making any new API calls.", "code": 596 } ``` ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST https://api.useapi.net/v1/minimax/speech/delete-voice \ -d '{"voice_id": "…"}' ``` **JavaScript** ``` javascript const voice_id = "voice id"; const apiUrl = `https://api.useapi.net/v1/minimax/speech/delete-voice`; const api_token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${api_token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ voice_id }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests voice_id = "voice id" apiUrl = f"https://api.useapi.net/v1/minimax/speech/delete-voice" api_token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {api_token}" } body = { "voice_id": f"{voice_id}" } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-minimax-v1/post-minimax-speech-upload-sample === Document URL: https://useapi.net/docs/api-minimax-v1/post-minimax-speech-upload-sample --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> speech/upload-sample description: "Upload an MP3 or WAV sample for voice cloning via POST speech/upload-sample in the useapi.net MiniMax API v1, returning the file id POST speech/clone-voice consumes." parent: MiniMax API nav_order: 1890 --- ## Upload audio samples for voice cloning December 27, 2024 (November 16, 2026) --- Upload `.mp3` and `.wav` audio samples that you want to use for your voice cloning via [POST speech/clone-voice](/docs/api-minimax-v1/post-minimax-speech-clone-voice). Each audio sample should be between 10 to 60 seconds long. [POST raw content using Make.com and similar nocode tools.](/docs/questions-and-answers#how-post-raw-content-to-runwaymlassets-and-minimaxfiles-using-makecom-and-similar-nocode-tools) > **https://api.useapi.net/v1/minimax/speech/upload-sample/?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: select from the table below ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. - `Content-Type` is **required**, select from the table below: | Content-Type | File Extension | | ------------ | -------------- | | audio/mpeg | mp3 | | audio/wav | wav | | audio/wave | wav | ##### Query Parameters - `account` is optional when only one [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. ##### Responses **200** **200 OK** ```json { "ossPath": "<file url>", "fileID": "user:user_id-minimax:account-file:file_id" } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **596** **596 Account Error** ```json { "error": "Your minimax account has pending error. Please address this issue at https://useapi.net/docs/api-minimax-v1/post-minimax-accounts-account before making any new API calls.", "code": 596 } ``` ##### Model The uploaded sample's `fileID`, to pass in `files` to [POST speech/clone-voice](/docs/api-minimax-v1/post-minimax-speech-clone-voice), and its `ossPath`. <details markdown="block" class="model-details"> <summary>The uploaded sample, field by field</summary> ```typescript { // TypeScript, all fields are optional ossPath: string fileID: string error: string code: number } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/minimax/speech/upload-sample/?account=account" \ -H "Authorization: Bearer …" \ -H "Content-Type: audio/mpeg" \ --data-binary /path/to/your/voice-sample.mp3 ``` **JavaScript** ``` javascript const token = "API token"; const account = "Previously configured account"; const apiUrl = `https://api.useapi.net/v1/minimax/speech/upload-sample/?account=${account}`; let blob; /* // Example 1: Fetch audio from URL const audioUrl = "https://upload.wikimedia.org/wikipedia/commons/voice-sample.mp3"; const responseAudio = await fetch(audioUrl); blob = await responseAudio.blob(); */ /* // Example 2: Load audio from local file (Blob) const fsp = require('fs').promises; const audioFileName = "./voice-sample.mp3"; blob = new Blob([await fsp.readFile(audioFileName)]); */ /* // Example 3: Load from input file html element // <input id="audio-file" type="file"> const audioFile = document.getElementById(`audio-file`); if (audioFile.files[0]) blob = audioFile.files[0]); */ const response = await fetch(apiUrl, { method: "POST" headers: { "Authorization": `Bearer ${token}`, }, body: blob }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" account = "Previously configured account" apiUrl = f"https://api.useapi.net/v1/minimax/speech/upload-sample/?account={account}" headers = { 'Authorization': f'Bearer {token}', 'Content-Type': 'audio/mpeg' } # # Example 1: Fetch audio from URL # audio_url = "https://upload.wikimedia.org/wikipedia/commons/voice-sample.mp3" # response_audio = requests.get(audio_url) # file_content = response_audio.content # # Example 2: Load audio from local file # audio_file_path = "./voice-sample.mp3" # with open(audio_file_path, 'rb') as audio_file: # file_content = audio_file.read() response = requests.post(api_url, headers=headers, data=file_content) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-minimax-v1/post-minimax-videos-agent-create === Document URL: https://useapi.net/docs/api-minimax-v1/post-minimax-videos-agent-create --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/agent-create description: "Create videos from predefined agent templates with real-time server-sent event (SSE) streaming via POST videos/agent-create in the useapi.net MiniMax API v1." parent: MiniMax API nav_order: 501 --- ## Create a video using an agent template ## Table of contents June 30, 2025 (November 16, 2026) --- Create videos using MiniMax agent templates with predefined prompts and input requirements. On average, it takes 2 to 7 minutes for the agent to complete generation. The longer the duration of the result video, the longer it will take to generate. Videos longer than 15 seconds on average can take up to 15 minutes to generate. **Note:** This endpoint returns a **real-time streaming response** (`Content-Type: multipart/form-data`) that provides live progress updates during video generation. Use [hailuoai.video](https://hailuoai.video) account to generate videos, see [Setup MiniMax](/docs/start-here/setup-minimax) for details. To browse available templates use [GET videos/agent-templates](/docs/api-minimax-v1/get-minimax-videos-agent-templates). > **https://api.useapi.net/v1/minimax/videos/agent-create** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` ##### Response Headers ``` yaml Content-Type: text/event-stream Cache-Control: no-cache Connection: keep-alive ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "account": "Optional MiniMax API account", "templateId": "Required template ID", "prompt": "Optional text prompt", "fileID": "user:user_id-minimax:account-file:file_id", "ossPath": "Required OSS path when using fileID", "replyUrl": "Place your call back URL here", "replyRef": "Place your reference id here", "maxJobs": 1 } ``` - `account` is optional, if not specified API will randomly select account from available [accounts](/docs/api-minimax-v1/get-minimax-accounts). - `templateId` is **required**, the ID of the agent template to use. Get available templates from [GET videos/agent-templates](/docs/api-minimax-v1/get-minimax-videos-agent-templates). - `prompt` is optional, text input for templates that require text prompts. Check template requirements using [GET videos/agent-templates/?templateId=`templateId`](/docs/api-minimax-v1/get-minimax-videos-agent-templates) with the specific `templateId`. - `fileID` is optional, required for templates that need image inputs: * fileID of image uploaded via [POST /files](/docs/api-minimax-v1/post-minimax-files) * fileID of previously uploaded image retrieved via [GET /files](/docs/api-minimax-v1/get-minimax-files) * fileID of previously uploaded character retrieved via [GET videos/characters](/docs/api-minimax-v1/get-minimax-videos-characters) * fileID of image generated via [POST images/create](/docs/api-minimax-v1/post-minimax-images-create). - `ossPath` is **required** when using `fileID`, the OSS path / url for the uploaded file. Cannot be provided without `fileID`. - `replyUrl` is optional. Callback URL for job completion notifications. API will call the provided `replyUrl` once MiniMax video completed or failed. Maximum length 1024 characters. Callback body has the same JSON shape as [GET /videos/`videoId`](/docs/api-minimax-v1/get-minimax-videos-videoId) response. - `replyRef` is optional, place here your reference id which will be stored and returned along with this MiniMax video response / result. Maximum length 1024 characters. - `maxJobs` is optional, if not specified value from [accounts/account](/docs/api-minimax-v1/get-minimax-accounts-account) will be used. Valid range: 1…10. ##### Responses **200** **200 OK** Returns a **streaming response** (`Content-Type: text/event-stream`) with real-time progress updates. The stream contains multiple data events showing the video generation process from start to finish. See [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events) to learn more about events format. ```bash data: {"status":"created","videoId":"user:1234-minimax:1234567-video:7654321","projectID":"…","chatID":"…","message":{"msgContent":"Futuristic sports car","msgType":1},"code":200,"timestamp":1755800001000} data: {"status":"connected","videoId":"user:1234-minimax:1234567-video:7654321","projectID":"…","chatID":"…","code":200,"timestamp":1755800002000} data: {"status":"heartbeat","timestamp":1755800012000} data: {"status":"progress","type":1,"message":{"msgContent":"Generating image...","msgType":2},"timestamp":1755800015000} data: {"status":"progress","type":2,"message":{"attachmentInfo":{"attachments":[{"file":{"fileName":"processing"},"status":2}]}},"timestamp":1755800017000} data: {"status":"progress","type":2,"message":{"attachmentInfo":{"attachments":[{"file":{"fileName":"car.png","fileUrl":"https://cdn.hailuoai.video/moss/prod/.../car.png"},"status":3}]}},"timestamp":1755800025000} data: {"status":"progress","type":1,"message":{"msgContent":"Generating video...","msgType":2},"timestamp":1755800026000} data: {"status":"progress","type":2,"message":{"attachmentInfo":{"type":3,"attachments":[{"file":{"fileName":"processing"},"status":2}]}},"timestamp":1755800028000} data: {"status":"progress","type":2,"message":{"attachmentInfo":{"type":3,"attachments":[{"file":{"fileName":"final_video.mp4","fileUrl":"https://cdn.hailuoai.video/moss/prod/.../final.mp4"},"status":3}]}},"timestamp":1755800055000} data: {"status":"progress","type":3,"isFinished":true,"recTemplateList":[{"id":"template_vlog_1","name":"Vlog Interview"},{"id":"template_tf_2","name":"Transformers"}],"timestamp":1755800056000} data: {"status":"finished","videoId":"user:1234-minimax:1234567-video:7654321","projectID":"…","chatID":"…","message":{"msgContent":"Futuristic sports car","msgType":1},"code":200,"timestamp":1755800057000} ``` Use the `videoId` from the stream event with `"status":"finished"` or `"status":"created"` to retrieve video status and results using [GET /videos/`videoId`](/docs/api-minimax-v1/get-minimax-videos-videoId). **400** **400 Bad Request** ```json { "error": "<Error message>" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized" } ``` **404** **404 Not Found** ```json { "error": "The video or template you are trying to use does not exist or has been deleted." } ``` ##### Model `Content-Type: text/event-stream` A stream of server-sent progress events, where the `created` or `finished` event carries the `videoId` to read with [GET /videos/`videoId`](/docs/api-minimax-v1/get-minimax-videos-videoId). <details markdown="block" class="model-details"> <summary>Each stream event, field by field</summary> See [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events) to learn more about events format. ```bash data:<JSON Data> data:<JSON Data> … ``` ###### JSON Data Model ```typescript { // TypeScript, all fields are optional status?: 'created' | 'connected' | 'heartbeat' | 'progress' | 'finished' // Event status videoId?: string // Use GET /videos/<videoId> to retrieve results timestamp?: number // Event timestamp in milliseconds projectID?: string // Project identifier sectionID?: string // Section identifier within the project chatID?: string // Chat session identifier code?: number // Response code, e.g., 200 type?: 1 | 2 | 3 // Progress type. 1: Text/Tool, 2: Attachment, 3: Recommendations needUserInput?: boolean // Flag indicating if user input is required isFinished?: boolean // Flag indicating if the entire process is complete errCode?: number // Error code, 0 for success errMsg?: string // Error message string /** The main message payload, can be null during certain events */ message?: { msgId: string // Unique message ID parentMsgId?: string // ID of the parent message msgType?: 1 | 2 // Message type. 1: User, 2: System isQuota?: boolean // Quota usage flag timestamp?: number // Message creation timestamp msgContent?: string // Text content of the message files?: { // User-uploaded files fileName: string fileUrl: string posterUrl: string type: string extra: Record<string, never> }[] toolCall?: { // System tool call details toolName: string toolCallStatus: 1 | 2 // Tool status. 1: Started, 2: Finished toolCallArgs: string // Tool arguments as a JSON string } attachmentInfo?: { // Generated media attachments attachmentInfoID: string type?: 1 | 2 | 3 // Attachment type. 1: Image, 2: Video, 3: Final Composite attachments: { attachmentID: string type?: number file: { fileName: string fileUrl: string posterUrl: string type: string extra?: { height?: string width?: string url?: string path?: string no_watermark_url?: string watermark_url?: string duration?: string fps?: string frames?: string // A JSON string of frame URLs task_id?: string vendor?: string } | Record<string, never> } text?: string status?: 2 | 3 // Generation status. 2: Processing, 3: Complete extra?: Record<string, never> subAttachments?: [] }[] createTime?: number attachmentInfoUrl?: string extra?: Record<string, never> status?: number } } | null } ``` </details> ##### Examples **JavaScript** <details markdown="block"> <summary>Expand <code class="language-plaintext highlighter-rouge"><b>JavaScript Streaming Example</b></code></summary> ``` javascript const templateId = "1122334455667788"; const prompt = "text prompt"; const token = "API token"; const response = await fetch('https://api.useapi.net/v1/minimax/videos/agent-create', { method: 'POST', headers: { 'Authorization': `Bearer ${token}` }, body: new FormData([['templateId', templateId], ['prompt', prompt]]) }); if (!response.ok) { const errorText = await response.text(); throw new Error(`HTTP ${response.status}: ${errorText}`); } let videoId = null; const reader = response.body.getReader(); const decoder = new TextDecoder("utf-8"); let buffer = ""; while (true) { const { done, value } = await reader.read(); if (done) break; buffer += decoder.decode(value, { stream: true }); const lines = buffer.split("\n"); buffer = lines.pop(); for (const line of lines) { if (line.startsWith("data:")) { try { const json = JSON.parse(line.slice(5).trim()); console.log("Stream event:", json); if (json.videoId && !videoId) { videoId = json.videoId; console.log("Video ID:", videoId); } if (json.status === 'finished') { console.log("Generation completed!"); break; } } catch (e) { console.error("Failed to parse JSON:", e); } } } } console.log("Final video ID:", videoId); ``` </details> **Python** <details markdown="block"> <summary>Expand <code class="language-plaintext highlighter-rouge"><b>Python Streaming Example</b></code></summary> ``` python import requests import json template_id = "1122334455667788" prompt = "text prompt" token = "API token" data = { 'templateId': template_id, 'prompt': prompt } response = requests.post( 'https://api.useapi.net/v1/minimax/videos/agent-create', headers={'Authorization': f'Bearer {token}'}, data=data, stream=True ) if not response.ok: print(f"HTTP Error {response.status_code}: {response.text}") exit(1) video_id = None for line in response.iter_lines(decode_unicode=True): if line and line.startswith("data:"): try: json_data = json.loads(line[5:].strip()) print("Stream event:", json_data) if json_data.get("videoId") and not video_id: video_id = json_data["videoId"] print(f"Video ID: {video_id}") if json_data.get("status") == "finished": print("Generation completed!") break except json.JSONDecodeError as e: print(f"Failed to parse JSON: {e}") print(f"Final video ID: {video_id}") ``` </details> **Curl** ``` bash curl -H "Accept: text/event-stream" \ -H "Authorization: Bearer …" \ -X POST "https://api.useapi.net/v1/minimax/videos/agent-create" \ -d "templateId=1122334455667788" \ -d "prompt=text prompt" \ --no-buffer ``` === URL: https://useapi.net/docs/api-minimax-v1/post-minimax-videos-cancel === Document URL: https://useapi.net/docs/api-minimax-v1/post-minimax-videos-cancel --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/cancel description: "Cancel an in-progress video generation by videoId via POST videos/cancel in the useapi.net MiniMax API v1." parent: MiniMax API nav_order: 900 --- ## Cancel the currently generated video ## Table of contents January 9, 2025 --- Attempt to cancel a currently generated video created via [POST videos/create](/docs/api-minimax-v1/post-minimax-videos-create). > **https://api.useapi.net/v1/minimax/videos/cancel** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "videoId": "user:user_id-minimax:account-file:video_id", } ``` - `videoId` is **required**. Specify the videoId you want to cancel. ##### Responses **200** **200 OK** **400** **400 Bad Request** ```json { "error": "<Error message>" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized" } ``` ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST "https://api.useapi.net/v1/minimax/videos/cancel" \ -d '{"videoId": "…"}' ``` **JavaScript** ``` javascript const videoId = "videoId you want to cancel"; const apiUrl = `https://api.useapi.net/v1/minimax/videos/cancel`; const token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ videoId }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests videoId = "videoId you want to cancel" apiUrl = f"https://api.useapi.net/v1/minimax/videos/cancel" token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } body = { "videoId": f"{videoId}" } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-minimax-v1/post-minimax-videos-create === Document URL: https://useapi.net/docs/api-minimax-v1/post-minimax-videos-create --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/create description: "Generate AI video from text or image via POST videos/create in the useapi.net MiniMax API v1 — 18 models including Hailuo 3.0 at 768p/2K with native audio, Hailuo 02/2.3, Veo 3.1, and Seedance 2.0." parent: MiniMax API nav_order: 500 --- ## Create a video using a text and image prompt ## Table of contents September 25, 2024 (November 16, 2026) --- Use [hailuoai.video](https://hailuoai.video) account to generate videos, see [Setup MiniMax](/docs/start-here/setup-minimax) for details. To upload prompt image use [POST /files](/docs/api-minimax-v1/post-minimax-files). ##### Model Comparison Matrix Sora 2 is no longer available: OpenAI shut it down on September 24, 2026. ###### Hailuo 01 — Legacy models, 720p 6sec, no `options` | Model | Type | Notes | |:------|:-----|:------| | T2V-01 | Text-to-Video | Default for text prompts | | I2V-01 | Image-to-Video | Default for image prompts | | I2V-01-live | Image-to-Video | Live photo effect | | I2V-01-Director | Image-to-Video | Camera movement control | | T2V-01-Director | Text-to-Video | Camera movement control | | S2V-01 | Subject Reference | Character/subject consistency | ###### Hailuo 02/2.3 — Resolution and duration `options` | Model | Type | Options | End Frame | |:------|:-----|:--------|:----------| | 02 | Text/Image-to-Video | 512p-6/10sec, 768p-6/10sec, 1080p-6sec | Yes (768p/1080p) | | T2V-2.3 | Text-to-Video | 768p-6/10sec, 1080p-6sec | No | | I2V-2.3 | Image-to-Video | 768p-6/10sec, 1080p-6sec | No | | I2V-2.3-Fast | Image-to-Video | 768p-6/10sec, 1080p-6sec | No | ###### Veo 3.1 — `aspectRatio` (16:9, 9:16), higher resolution `options` | Model | Type | Options | End Frame | Notes | |:------|:-----|:--------|:----------|:------| | Veo-3.1 | Text/Image-to-Video | veo-720p/1080p/4k-8sec | Yes | Google DeepMind, native audio | | Veo-3.1-Fast | Text/Image-to-Video | veo-720p/1080p/4k-8sec | Yes | Faster generation | | Veo-3.1-S2V | Subject Reference | veo-720p/1080p/4k-8sec | No | Up to 14 ref images | | Veo-3.1-S2V-Fast | Subject Reference | veo-720p/1080p/4k-8sec | No | Up to 14 ref images, faster | ###### Seedance 2.0 — Independent `resolution` + `duration`, `aspectRatio` (7 ratios incl. Auto), omni multi-modal references | Model | Type | Resolutions | Duration | Aspect Ratios | Notes | |:------|:-----|:-----------:|:--------:|:--------------|:------| | Seedance-2.0 | Text/Image-to-Video | 480, 720, 1080, 4K | 4–15 sec | Auto, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 | ByteDance, omni reference + start/end frames, only tier with 4K | | Seedance-2.0-Fast | Text/Image-to-Video | 480, 720 | 4–15 sec | Same as above | Faster, lower cost | | Seedance-2.0-Mini | Text/Image-to-Video | 480, 720 | 4–15 sec | Same as above | Cheapest tier | Seedance models do not use `options`. Set `resolution` and `duration` directly. `end_frame_fileID` is mutually exclusive with omni references (`fileID2`…`fileID9`, `videoFileID*`, `audioFileID*`). ###### Hailuo 3.0 — 768p and 2K output, native stereo audio on every generation, omni multi-modal references | Model | Type | Resolution | Duration | Aspect Ratios | Notes | |:------|:-----|:----------:|:--------:|:--------------|:------| | Hailuo-3.0 | Text/Image-to-Video | 768, 1440 (2K) | 4–15 sec | Auto, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 | MiniMax H3, omni reference + start/end frames, native audio | Hailuo 3.0 takes the same shape as Seedance 2.0 — set `resolution` and `duration` directly, no `options`. Output is 24 fps and every generation includes native stereo audio. Pixel dimensions follow the chosen `aspectRatio`, so a 2K clip is larger at 16:9 than at 21:9. A few rules are specific to this model: - `resolution` accepts `1440` (2K, the default) and `768`. 768p costs 7 credits per second against 12 for 2K. - `prompt` is required on every request, including image-to-video. - Omni references are capped at 12 files in total — up to 9 images, 3 videos, and 3 audio clips, so the three buckets cannot all be filled at once. - An audio reference must be accompanied by at least one image or video reference. - Each reference file is capped at 30 MB for images, 50 MB for video, and 15 MB for audio. - `end_frame_fileID` works without `fileID`, so you can supply an end frame alone. - With no `aspectRatio`, text-to-video defaults to 16:9 and any request carrying references defaults to `Auto` (match the input). <details markdown="block"> <summary><b>Credits estimator</b></summary> Credits are charged per video. Actual costs may change, see [hailuoai.video](https://hailuoai.video) for current pricing. | Model | Option | Credits | |:------|:-------|:-------:| | T2V-01, I2V-01, I2V-01-live, S2V-01, T2V-01-Director, I2V-01-Director | - | 25 | | 02, T2V-2.3, I2V-2.3 | 768p-6sec | 25 | | 02, T2V-2.3, I2V-2.3 | 768p-10sec | 50 | | 02, T2V-2.3, I2V-2.3 | 1080p-6sec | 80 | | 02 | 512p-6sec | 12 | | 02 | 512p-10sec | 25 | | I2V-2.3-Fast | 768p-6sec | 15 | | I2V-2.3-Fast | 768p-10sec | 30 | | I2V-2.3-Fast | 1080p-6sec | 50 | | Veo-3.1, Veo-3.1-S2V | veo-720p-8sec | 120 | | Veo-3.1, Veo-3.1-S2V | veo-1080p-8sec | 120 | | Veo-3.1, Veo-3.1-S2V | veo-4k-8sec | 180 | | Veo-3.1-Fast, Veo-3.1-S2V-Fast | veo-720p-8sec | 60 | | Veo-3.1-Fast, Veo-3.1-S2V-Fast | veo-1080p-8sec | 60 | | Veo-3.1-Fast, Veo-3.1-S2V-Fast | veo-4k-8sec | 90 | Seedance 2.0 and Hailuo 3.0 are billed per second rather than per clip. Multiply the output rate by your chosen `duration` (4–15) for the base cost. | Model | Resolution | Credits/sec | 4-sec clip | Credits/sec of video reference | |:------|:----------:|:-----------:|:----------:|:------------------------------:| | Seedance-2.0 | 480p | 10 | 40 | 6 | | Seedance-2.0 | 720p | 21 | 84 | 14 | | Seedance-2.0 | 1080p | 50 | 200 | 30 | | Seedance-2.0 | 4K | 100 | 400 | 60 | | Seedance-2.0-Fast | 480p | 8 | 32 | 4 | | Seedance-2.0-Fast | 720p | 17 | 68 | 11 | | Seedance-2.0-Mini | 480p | 5 | 20 | 3 | | Seedance-2.0-Mini | 720p | 11 | 44 | 7 | | Hailuo-3.0 | 768p | 7 | 28 | 7 | | Hailuo-3.0 | 2K (1440) | 12 | 48 | 12 | A video reference is billed on its own length, on top of the generated clip. A 4-second Hailuo-3.0 clip costs 48 credits on its own, and about 168 credits when it carries a 10-second video reference (4 × 12 for the output plus 10 × 12 for the reference). Image and audio references do not add a per-second charge. </details> > **https://api.useapi.net/v1/minimax/videos/create** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "account": "1234567890", "model": "Seedance-2.0-Fast", "fileID": "user:1234-minimax:1234567890-file:1234567890", "prompt": "Cinematic shot of @Image1 walking through a neon-lit alley at night, rain reflections on wet pavement, slow tracking", "resolution": "720", "duration": 5, "aspectRatio": "16:9", "replyUrl": "https://webhook.site/abc", "replyRef": "shot-042" } ``` - `account` is optional, if not specified API will randomly select account from available [accounts](/docs/api-minimax-v1/get-minimax-accounts). - `prompt` is optional, describe your shot. Maximum length 2,000 characters (7,500 for Seedance models, 7,000 for `Hailuo-3.0`). `Hailuo-3.0` requires a prompt on every request, including image-to-video. How to prompt [tutorial](https://ageofllms.com/ai-howto-prompts/ai-fun/hailuo-minimax-tutorial). **Omni `@`-mentions** (Seedance 2.0 and `Hailuo-3.0`)**.** When omni references are uploaded, you can refer to them in the prompt using `@Image1`…`@Image9`, `@Video1`…`@Video3`, `@Audio1`…`@Audio3` (case-insensitive — `@image1`, `@IMAGE1`, `@Image01` all resolve to the same slot). Unresolved tokens (e.g. `@Image5` when only 2 images are provided) return a 400 error. If no omni references are uploaded, `@`-tokens pass through as literal text. **Seedance omni audio.** To make a referenced voice audible in the output, spell out the spoken line and state it is heard, for example *She speaks out loud, clearly saying "your line" in the voice from @Audio1, audible throughout*. A bare `@Audio1` mention (no explicit "says … audible" wording) often returns a silent track, even though the request is accepted. - `promptOptimization` is optional. Supported values: `true`, `false`. Default: `false` (no optimization). - `fileID` — image/character reference. Upload via [POST /files](/docs/api-minimax-v1/post-minimax-files), retrieve via [GET /files](/docs/api-minimax-v1/get-minimax-files), [GET videos/characters](/docs/api-minimax-v1/get-minimax-videos-characters), or use fileID from [POST images/create](/docs/api-minimax-v1/post-minimax-images-create). | `model` | `fileID` | `end_frame_fileID` | `fileID2`…`fileID14` | `aspectRatio` | |:------|:---------|:-------------------|:---------------------|:--------------| | `T2V-01`, `T2V-01-Director`, `T2V-2.3` | Not supported | - | - | - | | `I2V-01`, `I2V-01-live`, `I2V-01-Director` | Required | - | - | - | | `S2V-01` | Required | - | - | - | | `02` | Optional | Yes (768p/1080p only) | - | - | | `I2V-2.3`, `I2V-2.3-Fast` | Required | - | - | - | | `Veo-3.1`, `Veo-3.1-Fast` | Optional | Yes | - | `16:9`, `9:16` | | `Veo-3.1-S2V`, `Veo-3.1-S2V-Fast` | Required | - | Up to 14 total | `16:9`, `9:16` | | `Seedance-2.0`, `Seedance-2.0-Fast`, `Seedance-2.0-Mini`, `Hailuo-3.0` | Optional | Yes (mutually exclusive with `fileID2`…`fileID9` and omni `videoFileID*`/`audioFileID*`) | Up to 9 (`fileID`…`fileID9`, resolved as `@Image1`…`@Image9`) | 7 ratios (see below) | - `end_frame_fileID` is optional. The `end_frame_fileID` and `fileID` cannot be the same, reupload the end frame via [POST /files](/docs/api-minimax-v1/post-minimax-files) if needed. - `fileID2` … `fileID14` are optional. **For S2V models** (`Veo-3.1-S2V`, `Veo-3.1-S2V-Fast`) — additional subject/character reference images, up to 14 total. **For Seedance models and `Hailuo-3.0`** — additional omni image references `@Image2`…`@Image9` (up to 9 total, `fileID10`…`fileID14` rejected). `Hailuo-3.0` additionally caps all references combined at 12 files. Requires `fileID` first. Slots must be filled consecutively (no gaps). All files must belong to the same account. - `videoFileID1` … `videoFileID3` are optional, **for Seedance models and `Hailuo-3.0`**. Omni video references resolved as `@Video1`…`@Video3` in the prompt. Upload mp4 via [POST /files](/docs/api-minimax-v1/post-minimax-files). Each video reference must be 2–15 seconds, and all video references together cannot exceed 15 seconds. Slots must be filled consecutively (no gaps). Mutually exclusive with `end_frame_fileID`. A video reference that shows a recognizable real human face is rejected by Seedance's content filter — the job ends with status `moderated` ("Face Detected"). Blur the face, or use footage without a clear face. A real face in an **image** reference (`fileID`) is allowed — the restriction applies to video material only. - `audioFileID1` … `audioFileID3` are optional, **for Seedance models and `Hailuo-3.0`**. Omni audio references resolved as `@Audio1`…`@Audio3` in the prompt. Upload mp3 or wav via [POST /files](/docs/api-minimax-v1/post-minimax-files). Each audio reference must be 2–15 seconds, and all audio references together cannot exceed 15 seconds — video and audio are totalled separately, 15 seconds each. Slots must be filled consecutively (no gaps). Mutually exclusive with `end_frame_fileID`. On `Hailuo-3.0` an audio reference must be accompanied by at least one image or video reference. To hear the voice in the output, prompt it explicitly (see `prompt` above). - `resolution` is optional, **for Seedance models and `Hailuo-3.0`**. Supported values: `480`, `720`, `1080` (Seedance-2.0 only), `4K` (Seedance-2.0 only), `768` and `1440` (`Hailuo-3.0` only). `Seedance-2.0-Fast` and `Seedance-2.0-Mini` support `480` and `720` only. Default: `720` for Seedance, `1440` for `Hailuo-3.0`. - `duration` is optional, **for Seedance models and `Hailuo-3.0`**. Integer seconds in range 4–15. Default: `5`. - `aspectRatio` is optional. Supported by: - `Veo-3.1`, `Veo-3.1-Fast`, `Veo-3.1-S2V`, `Veo-3.1-S2V-Fast` — values: `16:9` (default), `9:16`. - `Seedance-2.0`, `Seedance-2.0-Fast`, `Seedance-2.0-Mini` — values: `Auto` (default), `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`. - `model` is optional. Supported values: **Hailuo 01** — 720p, 6 sec * `T2V-01` (default) text-to-video * `I2V-01` (default) image-to-video * `I2V-01-live` image-to-video, live photo effect * `S2V-01` subject reference, character/subject consistency * `T2V-01-Director` text-to-video, camera movement control via `[<movement>]` in prompt (instructions) * `I2V-01-Director` image-to-video, camera movement control via `[<movement>]` in prompt (instructions) **Hailuo 02/2.3** — resolution and duration `options` * `02` text/image-to-video, native 1080p * `T2V-2.3` text-to-video * `I2V-2.3` image-to-video * `I2V-2.3-Fast` image-to-video, faster generation **Veo 3.1** — `aspectRatio` support, higher resolution `options` * `Veo-3.1` Google DeepMind Veo 3.1, text/image-to-video with native audio, 720p/1080p/4K * `Veo-3.1-Fast` Veo 3.1 Fast, text/image-to-video, 720p/1080p/4K * `Veo-3.1-S2V` Veo 3.1 Subject Reference, up to 14 reference images via `fileID`…`fileID14`, 720p/1080p/4K * `Veo-3.1-S2V-Fast` Veo 3.1 Subject Reference Fast, up to 14 reference images, 720p/1080p/4K **Seedance 2.0** — independent `resolution` + `duration`, omni multi-modal references, 7 aspect ratios * `Seedance-2.0` ByteDance Seedance 2.0, text/image-to-video, 480p/720p/1080p/4K, 4–15 sec * `Seedance-2.0-Fast` Seedance 2.0 Fast, text/image-to-video, 480p/720p, 4–15 sec, lower cost * `Seedance-2.0-Mini` Seedance 2.0 Mini, text/image-to-video, 480p/720p, 4–15 sec, cheapest tier - `options` is optional. Sets resolution and duration. Hailuo 01 and Seedance models do not support `options` (Seedance uses `resolution` and `duration` directly). | `model` | `options` | `end_frame` | |:------|:-------------------|:-----------| | `02` | `512p-6sec`, `512p-10sec` (I2V only), `768p-6sec`, `768p-10sec`, `1080p-6sec` | Yes (768p/1080p only) | | `T2V-2.3` | `768p-6sec`, `768p-10sec`, `1080p-6sec` | No | | `I2V-2.3` | `768p-6sec`, `768p-10sec`, `1080p-6sec` | No | | `I2V-2.3-Fast` | `768p-6sec`, `768p-10sec`, `1080p-6sec` | No | | `Veo-3.1` | `veo-720p-8sec`, `veo-1080p-8sec`, `veo-4k-8sec` | Yes | | `Veo-3.1-Fast` | `veo-720p-8sec`, `veo-1080p-8sec`, `veo-4k-8sec` | Yes | | `Veo-3.1-S2V` | `veo-720p-8sec`, `veo-1080p-8sec`, `veo-4k-8sec` | No | | `Veo-3.1-S2V-Fast` | `veo-720p-8sec`, `veo-1080p-8sec`, `veo-4k-8sec` | No | - `replyUrl` is optional. Callback URL for job completion notifications. API will call the provided `replyUrl` once MiniMax video completed or failed. Maximum length 1024 characters. We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality. Callback body has the same JSON shape as [GET /videos/`videoId`](/docs/api-minimax-v1/get-minimax-videos-videoId) response. - `replyRef` is optional, place here your reference id which will be stored and returned along with this MiniMax video response / result. Maximum length 1024 characters. - `maxJobs` is optional, if not specified value from [accounts/account](/docs/api-minimax-v1/get-minimax-accounts-account) will be used. Valid range: 1…10. Please set this number according to your [subscription](https://hailuoai.video/subscribe) plan. We recommend setting it to **2** (3 maximum) for Free, and **3** (4 maximum) for Standard and Unlimited plans. Although you can set it to higher values (3 for Free and 5 for Standard and Unlimited respectively), it won't make any difference since only one video can be processed at a time for Free accounts, and no more than two for Standard and Unlimited accounts. It's helpful to have a spare empty slot for cases where the MiniMax website is too busy and responds with `502` or `504` while still accepting jobs into the internal queue. ##### Responses **200** **200 OK** Use returned `videoId` to retrieve video status and results using [GET /videos/`videoId`](/docs/api-minimax-v1/get-minimax-videos-videoId). Check `videoURL` and/or `downloadURL` (paid account, no watermarks) for generated video with the `status` **2** (Completed). If you specify the optional parameter [`replyUrl`](/docs/api-minimax-v1/post-minimax-videos-create#request-body) the API will call the provided `replyUrl` with video progress updates until the video is complete or fails. ```json { "id": "1122334455667798899", "task": { "batchID": "998877665544332211", "videoIDs": [ "1122334455667798899" ] }, "videoId": "user:1234-minimax:987654321-video:998877665544332211", "replyUrl": "https://webhook.site/abc", "replyRef": "<your optional reference id>" } ``` **400** **400 Bad Request** ```json { "error": "<Error message>" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized" } ``` **412** **412 Insufficient credits** Insufficient credits. Please recharge to get more credits or try again next day. ```json { "error": "Insufficient credits. Please recharge to get more credits or try again next day." } ``` **422** **422 Unprocessable Content** Moderated message. ```json { "error": "Your prompt is too short, please provide more details" } ``` **429** **429 Too Many Requests** Wait in a loop for **at least** 10..30 seconds and retry again. There are two possible cases for API response 429: 1. API query is full and can not accept new videos/create requests. Size of query defined by [`maxJobs` optional parameter](#request-body). ```json { "error": "Account <MiniMax account> is busy executing <Account maxJobs> videos", "runningVideos": { "<MiniMax account>": [ { "account": "<MiniMax account>", "id": "id1", "scheduledVideo": "<scheduled video id1>", "videoId": "user:user_id-minimax:account-video:id1", "started": "2024-09-25T01:55:16.128Z", "replyUrl": "<optional callback URL>", "replyRef": "<optional reference>" }, { "account": "<MiniMax account>", "id": "idN", "scheduledVideo": "<scheduled video idN>", "videoId": "user:user_id-minimax:account-video:idN", "started": "2024-09-25T01:55:16.128Z", "replyUrl": "<optional callback URL>", "replyRef": "<optional reference>" } ] } } ``` 2. The API received an HTTP response status 429 from MiniMax. Please refer to your [subscription](https://hailuoai.video/subscribe) plan for the maximum allowed tasks in the queue. ```json { "error": "YOU CAN QUEUE 3 JOBS AT ONCE" } ``` **596** **596 Pending mod message** Your hailuoai.video account has been placed on hold, which may last a few hours. It may be a good idea to pause operations until then. You can reach out to the Discord [support channel](https://discord.com/channels/1280370508373950534/1297778596236103762) or send an email requesting your account to be unlocked. Based on the information we have gathered, this seems to be a temporary ban that will automatically unlock in just a few hours. ```json { "error": "Unusual account activities detected. Please contact customer support at contact@hailuoai.com" } ``` ##### Model The new video task, with the `videoId` to poll with [GET /videos/`videoId`](/docs/api-minimax-v1/get-minimax-videos-videoId) until it completes. <details markdown="block" class="model-details"> <summary>The new video task, field by field</summary> ```typescript { // TypeScript, all fields are optional videoId: string id: string task: { batchID: string videoIDs: string[] } runningVideos: { [account: string]: { account: string id: string scheduledVideo: string videoId: string started: string replyUrl: string replyRef: string }[] } replyUrl: string replyRef: string error: string } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST "https://api.useapi.net/v1/minimax/videos/create" \ -d '{"prompt": "…"}' ``` **JavaScript** ``` javascript const prompt = "text prompt"; const apiUrl = `https://api.useapi.net/v1/minimax/videos/create`; const token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ prompt }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests prompt = "text prompt" apiUrl = f"https://api.useapi.net/v1/minimax/videos/create" token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } body = { "prompt": f"{prompt}" } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/start-here/setup-mureka === Document URL: https://useapi.net/docs/start-here/setup-mureka --- layout: default title: Setup Mureka description: "How to connect a Mureka account to the useapi.net API — the recommended email + password method (the API re-logs in for you), or copying your session token + refresh token from the browser." parent: Start Here nav_order: 245 --- # <img style="height:1.2em;vertical-align: middle;" src="/assets/images/mureka.webp" alt=""> Setup Mureka December 2, 2024 (August 14, 2026) ## Table of contents Approximately 5 minutes to complete setup steps. --- > This is the setup guide for [Mureka API](/docs/api-mureka-v1). A [Mureka AI](https://www.mureka.ai) account and a [useapi.net subscription](/docs/subscription) are required for the API to work. [Mureka AI](https://www.mureka.ai) is a music generation service from Chinese tech giant Kunlun Tech featuring its proprietary Mureka music models (V9.5, V9, O2) and positioned to compete with [Suno](https://www.suno.com) and [Udio](https://www.udio.com). It creates unique songs based on user-provided lyrics or description (AI-generated lyrics), selected musical styles, and references to specific vocals and songs. We *strongly recommend* using a **separate Mureka account dedicated to API use**, kept out of your everyday browsing. ## Two ways to connect — and which to pick There are two ways to link a Mureka account. They differ in one thing that matters a lot over time: **what happens when Mureka ends the session.** | | **Email + password** — *recommended* | **Session token** | |---|---|---| | **What you give the API** | A dedicated Mureka account's **email + password** | Mureka's **session tokens** (`token` + `refresh_token`), copied from your browser | | **When the session is revoked** | The API **logs back in automatically** with your password | You must **re-connect the account by hand** | | **Ongoing maintenance** | **None — reconnects automatically** | Periodic re-linking (Google-based sessions get revoked every few days) | | **Best for** | Everyone setting up a new API account | An existing account you can't recreate with email + password | **Bottom line:** if you're setting up fresh, use **Method 1 (email + password)** — it's the only option that keeps working on its own. Use **Method 2 (session token)** only when you must keep an existing Google / Facebook / Discord / Apple account. --- ## Method 1 — Email + password (recommended) The API stores your Mureka password, so whenever Mureka ends the session it simply signs back in — your account never goes dark and never needs re-linking. This is the durable, zero-maintenance path. Mureka hides the email sign-up option by default, so use our guided page — it switches the email form on in your own browser, walks you through creating the account, and links it to useapi.net: [Open email + password setup](/assets/setup-browser/mureka-login-email) In short: 1. Open the guided page and copy its one-line snippet. 2. On [www.mureka.ai](https://www.mureka.ai), open the browser console and paste it — the **Email** / **Password** fields appear in the Sign in box. 3. Register with **an email you control** + **a password you choose** (Mureka emails a verification link — click it and set that password). 4. Back on the guided page, enter that email + password + your useapi.net API token → **Add account**. Already have an email + password Mureka account? Link it here (or call [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts) with `{ "email", "password" }`): <script> async function apiAddAccountMurekaEmail() { data = { method: 'POST', headers: { 'Authorization': `Bearer ${document.getElementById('post-accounts-Mureka-email-api_token').value}`, 'Content-Type': 'application/json' } }; const email = document.getElementById('post-accounts-Mureka-email-email')?.value?.trim(); const password = document.getElementById('post-accounts-Mureka-email-password')?.value; data.body = JSON.stringify({ email, password }); await apiExecute(`https://api.useapi.net/v1/mureka/accounts`, 'post-accounts-Mureka-email', data); } </script> <form id="post-accounts-Mureka-email" onsubmit="apiAddAccountMurekaEmail(); return false;" class="input-form"> <div class="input-field"> <div class="input-field-row"> <label for="post-accounts-Mureka-email-api_token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="post-accounts-Mureka-email-api_token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> <label for="post-accounts-Mureka-email-email"><span>email (your dedicated Mureka account email)</span> <input id="post-accounts-Mureka-email-email" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> <label for="post-accounts-Mureka-email-password" style="display:block; margin-bottom:10px;"><span>password (the password you set for that Mureka account)</span> <input id="post-accounts-Mureka-email-password" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> </div> <button id="post-accounts-Mureka-email-button" class="btn btn-primary fs-3" type="submit">Add account</button> </div> </form> <div id="post-accounts-Mureka-email-response" class="response-placeholder visible-false"></div> > The API stores your password so it can re-login on your behalf. It's sent only to useapi.net over HTTPS and is never returned (the response shows a masked value). The account will show `"authMode": "email"`. --- ## Method 2 — Session token (alternative) This captures Mureka's own session tokens — the `access_token` and `refresh_token` it returns when you sign in. The API auto-refreshes them for you, but **when the session is fully revoked or expires you'll need to re-connect the account by hand** (this is the case that Method 1 avoids). Sign in with **Google** — the provider we have tested end-to-end; Facebook, Discord, and Apple should work the same way since the values you copy are Mureka's own tokens, not the provider's. ### Automated capture Use our guided connect tool — copy a short snippet, sign in to Mureka, and your session is captured and your account added automatically, right in your own browser. No manual token copying. [Open automated session-token setup](/assets/setup-browser/mureka-connect.html) Prefer to do it by hand? Continue with the manual steps below. ### Open Mureka * Navigate to [https://www.mureka.ai](https://www.mureka.ai) <span style="color: red;">`1`</span>. **Sign out of this Mureka account everywhere first** — in this browser and any other browser or device. You need a fresh sign-in for the tokens to appear, and if the same account stays signed in elsewhere, Mureka invalidates the captured refresh token. * Open your browser's Developer Tools (press `F12`, or `Control+Shift+I` on Windows, `Command+Option+I` on Mac) and keep it open. ![](/assets/images/mureka_setup_1.jpg) ### Sign in to Mureka * Click `Try free now` <span style="color: red;">`2`</span> (shown in the image above). * In the `Sign in to Mureka` popup, click `Continue with Google` and complete the sign-in. ![](/assets/images/mureka_setup_2.jpg) ### Copy your token and refresh token In Developer Tools: 1. Click the `Network` tab <span style="color: red;">`1`</span> and type `/login` in the filter box <span style="color: red;">`2`</span>. 2. Click the `login` request in the list <span style="color: red;">`3`</span>. 3. Open the `Response` tab <span style="color: red;">`4`</span>. 4. Under `data` → `session_token`, copy the `access_token` value <span style="color: red;">`5`</span> — this is your `token`. 5. Copy the `refresh_token` value <span style="color: red;">`6`</span>. ![](/assets/images/mureka_setup_3.jpg) Both are long `eyJ…` strings (roughly 350–390 characters). Copy each value in full, without the surrounding quotes. ### Add account Paste your `token` (the `access_token`) and `refresh_token` below and click **Add account**. A `200` response means success. You can also call [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts) directly. > When you **Add account**, the API immediately performs one refresh — this confirms the tokens work and takes the session over from your browser, so the API holds its own token pair. It takes about ten seconds, which is expected. Once added, the API auto-refreshes the session with the refresh token, with no browser involved. You can close the Mureka tab. The account will show `"authMode": "token"`. > **Keep this Mureka account dedicated to the API and signed out everywhere else.** Signing into the same account in a browser again starts a second session, which invalidates the API's refresh token and breaks auto-refresh. If you want to use Mureka in a browser, use a different account — or switch to **Method 1**, which is immune to this. <script> async function apiTestAccountMureka() { data = { method: 'POST', headers: { 'Authorization': `Bearer ${document.getElementById('post-accounts-Mureka-api_token').value}`, 'Content-Type': 'application/json' } }; const token = document.getElementById('post-accounts-Mureka-token')?.value?.trim(); const refresh_token = document.getElementById('post-accounts-Mureka-refresh_token')?.value?.trim(); data.body = JSON.stringify({ token, refresh_token }); await apiExecute(`https://api.useapi.net/v1/mureka/accounts`, 'post-accounts-Mureka', data); } </script> <form id="post-accounts-Mureka" onsubmit="apiTestAccountMureka(); return false;" class="input-form"> <div class="input-field"> <div class="input-field-row"> <label for="post-accounts-Mureka-api_token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="post-accounts-Mureka-api_token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> <label for="post-accounts-Mureka-token"><span>token (access_token from the Mureka.ai login response)</span> <textarea id="post-accounts-Mureka-token" class="input-element" rows="3" required aria-required="true" style="resize: both;"></textarea> </label> <label for="post-accounts-Mureka-refresh_token"><span>refresh_token (refresh_token from the Mureka.ai login response)</span> <textarea id="post-accounts-Mureka-refresh_token" class="input-element" rows="3" required aria-required="true" style="resize: both;"></textarea> </label> </div> <button id="post-accounts-Mureka-button" class="btn btn-primary fs-3" type="submit">Add account</button> </div> </form> <div id="post-accounts-Mureka-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-mureka-v1 === Document URL: https://useapi.net/docs/api-mureka-v1 --- layout: default title: Mureka API nav_logo: /assets/images/mureka.webp nav_title: Mureka API seo_title: "Mureka API Pricing and Docs: Your Own Voice, Stems, Sheet Music" description: "Third-party Mureka AI API by useapi.net: V9.5 songs in your own voice, remixes, stems and sheet music on your Mureka subscription, over REST or MCP." nav_order: 2500 has_children: true permalink: /docs/api-mureka-v1 repo: https://github.com/useapi/mureka-api --- # <img style="height:1.2em;vertical-align: middle;" src="/assets/images/mureka.webp" alt=""> Mureka API December 2, 2024 (November 15, 2026) This is a [third-party](/docs/legal#affiliation--third-party-services) API for [Mureka AI](https://www.mureka.ai) by Kunlun Tech. It uses your [Mureka subscription](https://www.mureka.ai/subscribe): Free, Pro $10 or Premier $30 a month (as of October 2026). Through a REST API and a hosted MCP server, it makes songs with Mureka V9.5, V9, V8, O2, V7.6 and V7.5-all, an alternative to [Suno](https://www.suno.com) and [Udio](https://www.udio.com), sung in your own voice if you like, plus remixes, stems with MIDI, sheet music and speech. Everything runs on your subscription's monthly Mureka Gold, with no Mureka developer account and no prepaid developer balance. On Premier, a Mureka V9.5 song uses $0.018 of the plan's monthly Gold, against $0.15 a song on Mureka's own API. ## Models | Model | What it makes | Notes | |---|---|---| | Mureka V9.5<br>`V9.5` | Songs [from your lyrics](/docs/api-mureka-v1/post-mureka-music-create-advanced), [from a prompt](/docs/api-mureka-v1/post-mureka-music-create) and [instrumentals](/docs/api-mureka-v1/post-mureka-music-create-instrumental) | The default. Up to 5 minutes, two songs per request in about 45 seconds, styled by a [reference track](/docs/api-mureka-v1/post-mureka-files), a [melody](/docs/api-mureka-v1/post-mureka-files-motif) or a voice | | Mureka V9<br>`V9` | Songs from your lyrics or a prompt, and instrumentals | Reference tracks, melodies, voices and remix, the same as V9.5 | | Mureka V8<br>`V8` | Songs from your lyrics or a prompt, and instrumentals | Reference tracks, melodies, voices and remix | | Mureka O2<br>`O2` | Songs from your lyrics or a prompt, and instrumentals | Mureka's all-in-one model, with reference tracks and voices | | Mureka V7.6<br>`V7.6` | Songs from your lyrics or a prompt, and instrumentals | Finer prompt control. The retired `V7`, `O1` and `V6` ids run on V7.6, and `V5.5` too for instrumentals | | Mureka V7.5-all<br>`V7.5-all` | Songs from your lyrics or a prompt, and instrumentals | The model a free Mureka account makes songs with. The older `V7.5` id runs on it | | Your own voice | Songs sung by [a voice you upload](/docs/api-mureka-v1/post-mureka-files-vocal) or by a reusable [character](/docs/api-mureka-v1/post-mureka-music-characters) | A character comes from about 30 seconds of singing or from a song you made, public or [private](/docs/api-mureka-v1/post-mureka-music-characters-publish) | | Edit, extend and remix | [Re-sing one section](/docs/api-mureka-v1/post-mureka-music-edit) with new lyrics, [extend](/docs/api-mureka-v1/post-mureka-music-extend) a song, or [remix](/docs/api-mureka-v1/post-mureka-music-remix) it in a new style | An edit keeps the rest of the track, a remix keeps or replaces the lyrics, instrumentals remix too | | Stems | [Up to 12 instrument and vocal tracks with MIDI](/docs/api-mureka-v1/post-mureka-music-stems), or vocals and instrumental | [Download](/docs/api-mureka-v1/post-mureka-music-stems-download) WAV, MP3, MIDI or a session for Ableton Live, Logic Pro, Pro Tools or Cubase | | Sheet music | [MusicXML, staff and numbered-notation PDFs](/docs/api-mureka-v1/post-mureka-music-score) from a song, a YouTube link or an uploaded file | 10 seconds to 10 minutes of audio, ready in about 5 to 15 seconds | | Speech | [Text-to-speech](/docs/api-mureka-v1/post-mureka-speech) with Mureka's voices or [your cloned voice](/docs/api-mureka-v1/post-mureka-speech-voice) | Conversations between several voices, and no limit on speech jobs at once. Voice cloning needs Mureka Premier | | More | [Lyrics](/docs/api-mureka-v1/post-mureka-music-lyrics-generate), [lyrics videos](/docs/api-mureka-v1/post-mureka-music-video-generate), [YouTube soundtracks](/docs/api-mureka-v1/get-mureka-files-youtube) for reference tracks, and the [song license and stems package](/docs/api-mureka-v1/post-mureka-music-download) | Lyrics videos for songs on V9, V8, O2, V7.6 and V7.5-all | ## MCP server The hosted [Mureka MCP server](/docs/api-mureka-v1/mcp) gives Claude Code, Cursor, VS Code and other AI assistants 40 tools for songs, characters, edits, remixes, stems, sheet music and speech, with your useapi.net API token and nothing to install. The [mureka-api](https://github.com/useapi/mureka-api) repo also adds it in one step as a [Claude Code plugin](https://github.com/useapi/mureka-api#use-with-claude-code) or a [Gemini CLI extension](https://github.com/useapi/mureka-api#use-with-gemini-cli). ## Pricing What one song costs on [Mureka's developer API](https://platform.mureka.ai/pricing) and on each Mureka subscription (as of October 2026). Each subscription comes with a monthly amount of Mureka Gold, and each song uses a set number of it, so a song costs its share of the subscription: a Gold is worth 0.2 cents on Pro and 0.15 cents on Premier. | Model | [Official API](https://platform.mureka.ai/pricing) | Premier $30/m (20,000 Gold/mo) | Pro $10/m (5,000 Gold/mo) | |---|---|---|---| | Mureka V9.5 (song) | $0.15 ($0.50 from a prompt) | $0.018 / 12 Gold (1,666 songs/mo) | $0.024 / 12 Gold (416 songs/mo) | | Mureka V9 (song) | $0.045 ($0.30 from a prompt) | $0.018 / 12 Gold (1,666 songs/mo) | $0.024 / 12 Gold (416 songs/mo) | | Mureka V8 (song) | $0.045 ($0.30 from a prompt) | $0.018 / 12 Gold (1,666 songs/mo) | $0.024 / 12 Gold (416 songs/mo) | | Mureka O2 (song) | $0.045 ($0.30 from a prompt) | $0.03 / 20 Gold (1,000 songs/mo) | $0.04 / 20 Gold (250 songs/mo) | | Mureka V7.6 (song) | $0.03 ($0.30 from a prompt) | $0.015 / 10 Gold (2,000 songs/mo) | $0.02 / 10 Gold (500 songs/mo) | | Mureka V7.5-all (song) | not sold | $0.015 / 10 Gold (2,000 songs/mo) | $0.02 / 10 Gold (500 songs/mo) | | Section edit | $0.10 (on V8) | $0.03 / 20 Gold (1,000 edits/mo) | $0.04 / 20 Gold (250 edits/mo) | | Remix (V9.5, V9 or V8) | $0.20 (on V8) | $0.018 / 12 Gold (1,666 songs/mo) | $0.024 / 12 Gold (416 songs/mo) | | 12 stems with MIDI | $0.70 (per song) | $0.15 / 100 Gold (200 songs/mo) | Premier only | | Vocals and instrumental | $0.20 (per song) | $0.03 / 20 Gold (1,000 songs/mo) | Premier only | | Sheet music (MusicXML and PDF) | $0.20 (per song) | $0.015 / 10 Gold (2,000 songs/mo) | $0.02 / 10 Gold (500 songs/mo) | | Speech | $0.082 ($4.90 an hour) | $0.03 / 20 Gold (1,000 min/mo) | $0.04 / 20 Gold (250 min/mo) | | Stem downloads (MIDI and DAW sessions) | — | $0 / 0 Gold (included) | Premier only | | Your own voice (as the singer) | $5 (per voice) | $0 / 0 Gold (included) | Premier only | | Lyrics | $0.009 (per lyric) | $0 / 0 Gold (included) | $0 / 0 Gold (included) | - A free Mureka account makes 4 songs a day on Mureka V7.5-all, 2 at a time. The other models need Pro or Premier. - Each song request makes two songs, so it uses twice the Gold shown. Mureka's plans page counts 10 Gold a song (500 songs on Pro, 2,000 on Premier), and the table uses each model's own Gold price. - Songs and speech share one Gold allowance. - Singing in your own voice needs Premier. Characters, reusable singers made from your own voice, cost no Gold to create but need a paid plan, and songs made with them cost the same as any song. - Premier also downloads instrumentals and the basic stems package for free. - Mureka's developer API needs a prepaid balance from $1,000, valid 12 months, that runs 5 requests at once, while each Mureka account here runs up to 10 generations (20 songs) at once. - Pro and Premier can buy more Gold: $18 for 4,000, $28 for 8,000 and $48 for 16,000. Billed yearly, Pro is $96 and Premier $288 a year. ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. ## Run several Mureka accounts Each useapi.net subscription connects 3 Mureka accounts, and each account runs up to 10 generations (20 songs) at once. With more than one account connected, pass `account` to choose where a new song, upload or speech job runs. Edits, remixes, extends, stems and scores need no `account`, since the `song_id` names the account that holds the song. When all 10 of an account's generation slots are full you get `429`, so wait a few seconds and send it again, or send it to another account. Speech has no such limit. Song and speech requests can also run in the background with `async` and send their result to your webhook with `replyUrl`, so you don't have to hold the connection open for the 30 to 90 seconds a song takes. [GET /jobs](/docs/api-mureka-v1/get-mureka-jobs) shows what each account is running. An account connected with its email and password [logs back in on its own](/docs/api-mureka-v1/post-mureka-accounts) when Mureka ends the session. [How useapi.net works](/docs/how-it-works) has tips for keeping your accounts healthy. ## Questions ### Is there a Mureka API? Through useapi.net, the Mureka AI API runs on your Mureka website subscription, the free plan included, and covers what mureka.ai does: songs on Mureka V9.5, V9, V8, O2, V7.6 and V7.5-all, your own voice as the singer, section edits, remixes, stems with MIDI, sheet music and speech. Mureka's own [developer API](https://platform.mureka.ai/pricing) starts with a separate $1,000 prepaid balance instead (as of October 2026). ### How much does the Mureka API cost? Through useapi.net, a Mureka V9.5 song costs 1.8 to 2.4 cents on a Mureka Premier or Pro subscription, against 15 cents from your lyrics or 50 cents from a prompt on Mureka's developer API. V9 and V8 songs cost the same, against 4.5 cents, and speech costs 3 to 4 cents a minute, against 8.2 cents (as of October 2026). The [price table](#pricing) shows every model and tool. ### Is there a Mureka API key? Through useapi.net you need no Mureka platform key: you call the API with a useapi.net [API token](/docs/start-here/setup-useapi) and connect your Mureka account once through [Setup Mureka](/docs/start-here/setup-mureka). Connected with its email and password, the account logs back in on its own whenever Mureka ends the session. Node.js and Python examples are on GitHub at [useapi/mureka-api](https://github.com/useapi/mureka-api). ### Can the Mureka API sing in my own voice? Through useapi.net, your own voice sings at no extra cost per voice on a Mureka Premier subscription, against $5 per voice on Mureka's developer API (as of October 2026). Upload a voice with [POST /files/vocal](/docs/api-mureka-v1/post-mureka-files-vocal) or turn it into a reusable character with [POST /music/characters](/docs/api-mureka-v1/post-mureka-music-characters), then pass it to [POST /music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced) with your lyrics and a style. The song costs the same as any other. ### Can the Mureka API turn a song into sheet music? Through useapi.net, a song becomes sheet music for 1.5 to 2 cents, against 20 cents on Mureka's developer API (as of October 2026). [POST /music/score](/docs/api-mureka-v1/post-mureka-music-score) turns a Mureka song, a YouTube link or an uploaded audio file into a zip with MusicXML, a staff PDF and a numbered-notation PDF. The [sheet music tutorial](/docs/articles/mureka-sheet-music) shows the output. [Setup Mureka](/docs/start-here/setup-mureka) [LLM-friendly API spec](https://useapi.net/assets/aibot/api-mureka-v1.txt) Feed this to your LLM to build integrations [Claude Code skill](/llm-tools) A drop-in useapi.net skill for Claude Code, and a rule for Cursor [Postman collection](https://www.postman.com/useapinet/useapi-net/collection/29112081-6ca3c497-835e-44bc-a2be-978be82b69cc) (October 16, 2026) [MCP Server](/docs/api-mureka-v1/mcp) Make songs, characters, remixes, stems, sheet music and speech from Claude Code, Cursor, VS Code and other MCP clients [GitHub examples](https://github.com/useapi/mureka-api) Node.js and Python: songs from a prompt or your lyrics, instrumentals, sheet music and your own voice Articles: * [Suno API Alternative: ACE Music, Mureka, Lyria 3.5, TemPolor and MiniMax](/docs/articles/suno-api-alternative) {% include lang-switch.html mode="hub" key="suno-api-alternative" %} * [How to Turn a Song or YouTube Link into Sheet Music with the Mureka API](/docs/articles/mureka-sheet-music) * [Mureka API Music Samples](/docs/articles/mureka-music-samples) * [How to Generate AI Music with the Mureka API](/docs/articles/mureka-bash) * [AI Music APIs Compared: Mureka vs MiniMax vs ElevenLabs vs Lyria 3 Pro](/docs/articles/ai-music-api-comparison) * [Five AI Music APIs on the Same Six Briefs: ACE Music v1, TemPolor v4.8, MiniMax Music-3.0, Lyria 3.5 and Mureka V9.5](/docs/articles/ai-music-flagships-compared) {% include lang-switch.html mode="hub" key="ai-music-flagships" %} * [How to Create AI Music Videos via API (Music, Video and Lip-Sync)](/docs/articles/create-music-videos-via-api) Examples: * [Mureka characters, remix and sheet music](/blog/261016) * [Mureka section editing](/blog/260905) * [Mureka V9.5](/blog/260814) * [Mureka V9](/blog/260404) * [Mureka V8](/blog/260127m) * [Mureka async jobs](/blog/260121) * [Mureka O2 & V7.6](/blog/251128) * [Mureka song parody with a reference track](/blog/250925) * [Mureka TTS/Speech](/blog/250818) * [Mureka custom vocals](/blog/250115) * [Mureka reference tracks and melodies](/blog/241213) Videos on YouTube: * [Five AI music APIs: ACE Music v1, TemPolor v4.8, MiniMax Music-3.0, Lyria 3.5 and Mureka V9.5](https://www.youtube.com/watch?v=MSUGckk4JqU) * [Music and voice cloning with Mureka](https://www.youtube.com/shorts/mZDCfVmyEoc) * [Developers, they don’t care about bugs! (Mureka)](https://www.youtube.com/watch?v=i0wMct6GzIs) Developer Community: * <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> * <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> === URL: https://useapi.net/docs/api-mureka-v1/del-mureka-accounts-account === Document URL: https://useapi.net/docs/api-mureka-v1/del-mureka-accounts-account --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> accounts/`account` description: "Remove a previously configured Mureka API account by name via DELETE accounts/account in the useapi.net Mureka API v1." parent: Mureka API nav_order: 400 --- ## Delete Mureka API account December 2, 2024 (November 16, 2026) --- > **https://api.useapi.net/v1/mureka/accounts/`account`** The `account` value should correspond to an account configured previously via a [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts) request. ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **204** **204 No Content** **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** ##### Model A successful delete answers `204` with no body, and an error answers with its `error` message and `code`. <details markdown="block" class="model-details"> <summary>The error answer, field by field</summary> ```typescript { // TypeScript, all fields are optional error: string, errorDetails: string, code: number } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X DELETE https://api.useapi.net/v1/mureka/accounts/<account> ``` **JavaScript** ``` javascript const account = "Previously configured account"; const apiUrl = `https://api.useapi.net/v1/mureka/accounts/${channnel}`; const token = "API token"; const data = { method: 'DELETE', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests account = "Previously configured account" apiUrl = f"https://api.useapi.net/v1/mureka/accounts/{account}" token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-mureka-v1/del-mureka-files-vocal === Document URL: https://useapi.net/docs/api-mureka-v1/del-mureka-files-vocal --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> files/vocal description: "Delete a previously uploaded vocal mp3 sample by ID via DELETE files/vocal in the useapi.net Mureka API v1 — parameters and response codes." parent: Mureka API nav_order: 2000 --- ## Delete vocal January 15, 2025 --- Delete vocal which was uploaded using [POST files/vocal](/docs/api-mureka-v1/post-mureka-files-vocal). > **https://api.useapi.net/v1/mureka/files/vocal/?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `id` is **required**, to see full list of uploaded vocals use [GET music/vocals/?mine=true](/docs/api-mureka-v1/get-mureka-music-vocals). ##### Responses **200** **200 OK** **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **596** **596 Account Error** Returned when the account has an error state preventing API calls. ```json { "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required", "code": "REFRESH_FAILED" } ``` Possible error codes: - `ACCOUNT_ERROR` - Account has a blocking error - `REFRESH_FAILED` - Automatic token refresh failed - `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly - `SESSION_EXPIRED` - Session expired and no auto-refresh available - `COOKIE_EXPIRED` - Google cookie has expired To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts). ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X DELETE https://api.useapi.net/v1/mureka/files/vocal/?account=<accound>&id=<id> ``` **JavaScript** ``` javascript const account = 123456789; const id = 98765432; const apiUrl = `https://api.useapi.net/v1/mureka/files/vocal/?account=${account}&id=${id}`; const token = "API token"; const data = { method: 'DELETE', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests account = 123456789 id = 98765432 apiUrl = f"https://api.useapi.net/v1/mureka/files/vocal/?account={account}&id={id}" token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-mureka-v1/del-mureka-files === Document URL: https://useapi.net/docs/api-mureka-v1/del-mureka-files --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> files description: "Delete a reference track from your Mureka collection by file ID via DELETE files in the useapi.net Mureka API v1 — parameters and response codes." parent: Mureka API nav_order: 1850 --- ## Delete track December 13, 2024 --- Delete track which was uploaded using [POST /files](/docs/api-mureka-v1/post-mureka-files). > **https://api.useapi.net/v1/mureka/files/?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `id` is **required**, to see full list of uploaded tracks use [GET /files](/docs/api-mureka-v1/get-mureka-files). ##### Responses **200** **200 OK** **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **596** **596 Account Error** Returned when the account has an error state preventing API calls. ```json { "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required", "code": "REFRESH_FAILED" } ``` Possible error codes: - `ACCOUNT_ERROR` - Account has a blocking error - `REFRESH_FAILED` - Automatic token refresh failed - `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly - `SESSION_EXPIRED` - Session expired and no auto-refresh available - `COOKIE_EXPIRED` - Google cookie has expired To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts). ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X DELETE https://api.useapi.net/v1/mureka/files/?account=<accound>&id=<id> ``` **JavaScript** ``` javascript const account = 123456789; const id = 98765432; const apiUrl = `https://api.useapi.net/v1/mureka/files/?account=${account}&id=${id}`; const token = "API token"; const data = { method: 'DELETE', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests account = 123456789 id = 98765432 apiUrl = f"https://api.useapi.net/v1/mureka/files/?account={account}&id={id}" token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-mureka-v1/del-mureka-music-characters === Document URL: https://useapi.net/docs/api-mureka-v1/del-mureka-music-characters --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> music/characters description: "Delete a Mureka character by its character_id via DELETE music/characters in the useapi.net Mureka API v1; songs already made with it are kept." parent: Mureka API nav_order: 2030 --- ## Delete a character October 16, 2026 --- Delete a character created with [POST /music/characters](/docs/api-mureka-v1/post-mureka-music-characters) or on [mureka.ai](https://www.mureka.ai). Songs you already made with it are kept. The voice you uploaded with [POST /files/vocal](/docs/api-mureka-v1/post-mureka-files-vocal) is kept too. > **https://api.useapi.net/v1/mureka/music/characters/?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) is configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `character_id` is **required**, the `id` from [GET /music/characters](/docs/api-mureka-v1/get-mureka-music-characters). ##### Responses **200** **200 OK** ```json {} ``` **400** **400 Bad Request** ```json { "error": "Parameter character_id is required", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Wrong username/password combination.", "code": 401 } ``` **596** **596 Account Error** Returned when the account has an error state preventing API calls. ```json { "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required", "code": "REFRESH_FAILED" } ``` Possible error codes: - `ACCOUNT_ERROR` - Account has a blocking error - `REFRESH_FAILED` - Automatic token refresh failed - `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly - `SESSION_EXPIRED` - Session expired and no auto-refresh available - `COOKIE_EXPIRED` - Google cookie has expired To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts). ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Authorization: Bearer …" \ -X DELETE "https://api.useapi.net/v1/mureka/music/characters/?account=<account>&character_id=<character_id>" ``` **JavaScript** ``` javascript const account = "12345678901234"; const character_id = 166751507709953; const apiUrl = `https://api.useapi.net/v1/mureka/music/characters/?account=${account}&character_id=${character_id}`; const token = "API token"; const data = { method: 'DELETE', headers: { 'Authorization': `Bearer ${token}` } }; const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests account = "12345678901234" character_id = 166751507709953 apiUrl = f"https://api.useapi.net/v1/mureka/music/characters/?account={account}&character_id={character_id}" token = "API token" headers = { "Authorization" : f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-mureka-v1/del-mureka-music-song_id === Document URL: https://useapi.net/docs/api-mureka-v1/del-mureka-music-song_id --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> music/`song_id` description: "Permanently delete a generated song by song_id via DELETE music/song_id in the useapi.net Mureka API v1 — accepts a song_id from GET music, create, create-advanced, or create-instrumental." parent: Mureka API nav_order: 1500 --- ## Delete song December 2, 2024 (November 16, 2026) --- > **https://api.useapi.net/v1/mureka/music/`song_id`** The `song_id` value returned by one of the following endpoints: * [GET /music](/docs/api-mureka-v1/get-mureka-music) * [POST /music/create](/docs/api-mureka-v1/post-mureka-music-create) * [POST /music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced) * [POST /music/create-instrumental](/docs/api-mureka-v1/post-mureka-music-create-instrumental) ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** ```json {} ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **596** **596 Account Error** Returned when the account has an error state preventing API calls. ```json { "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required", "code": "REFRESH_FAILED" } ``` Possible error codes: - `ACCOUNT_ERROR` - Account has a blocking error - `REFRESH_FAILED` - Automatic token refresh failed - `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly - `SESSION_EXPIRED` - Session expired and no auto-refresh available - `COOKIE_EXPIRED` - Google cookie has expired To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts). ##### Model A successful delete answers `200` with an empty JSON object. <details markdown="block" class="model-details"> <summary>The delete answer, an empty object</summary> ```typescript {} ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X DELETE https://api.useapi.net/v1/mureka/accounts/<song_id> ``` **JavaScript** ``` javascript const song_id = 123456789; const apiUrl = `https://api.useapi.net/v1/mureka/accounts/${song_id}`; const token = "API token"; const data = { method: 'DELETE', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests song_id = 123456789 apiUrl = f"https://api.useapi.net/v1/mureka/accounts/{song_id}" token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-mureka-v1/del-mureka-speech-voice === Document URL: https://useapi.net/docs/api-mureka-v1/del-mureka-speech-voice --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> speech/voice description: "Permanently delete a custom cloned voice from your Mureka account via DELETE speech/voice in the useapi.net Mureka API v1." parent: Mureka API nav_order: 2400 --- ## Delete speech voice August 18, 2025 --- This endpoint permanently deletes a custom cloned voice from your Mureka account. Once deleted, the voice cannot be recovered and can no longer be used for speech generation. Use this to clean up unwanted voice clones or manage your voice library. > **https://api.useapi.net/v1/mureka/speech/voice?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `voice_id` is **required**. The ID of the voice to delete. Get voice IDs from [GET /speech/voices](/docs/api-mureka-v1/get-mureka-speech-voices). ##### Responses **200** **200 OK** ```json {} ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **596** **596 Account Error** Returned when the account has an error state preventing API calls. ```json { "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required", "code": "REFRESH_FAILED" } ``` Possible error codes: - `ACCOUNT_ERROR` - Account has a blocking error - `REFRESH_FAILED` - Automatic token refresh failed - `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly - `SESSION_EXPIRED` - Session expired and no auto-refresh available - `COOKIE_EXPIRED` - Google cookie has expired To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts). ##### Examples **Curl** ``` bash curl -X DELETE "https://api.useapi.net/v1/mureka/speech/voice?voice_id=12345678901234" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const voiceId = "Voice ID to delete"; const apiUrl = `https://api.useapi.net/v1/mureka/speech/voice?voice_id=${voiceId}`; const response = await fetch(apiUrl, { method: "DELETE", headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" voice_id = "Voice ID to delete" apiUrl = f"https://api.useapi.net/v1/mureka/speech/voice?voice_id={voice_id}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-mureka-v1/del-mureka-speech === Document URL: https://useapi.net/docs/api-mureka-v1/del-mureka-speech --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> speech description: "Permanently delete a speech recording from your Mureka account via DELETE speech in the useapi.net Mureka API v1 — audio file and metadata cannot be recovered." parent: Mureka API nav_order: 2170 --- ## Delete speech August 18, 2025 --- This endpoint permanently deletes a specific speech recording from your Mureka account. Once deleted, the speech audio file and metadata cannot be recovered. Use this to clean up unwanted recordings or manage storage in your account. > **https://api.useapi.net/v1/mureka/speech/?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `id` is **required**. The ID of the speech to delete. Get speech IDs from [GET /speech](/docs/api-mureka-v1/get-mureka-speech). ##### Responses **200** **200 OK** ```json {} ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **596** **596 Account Error** Returned when the account has an error state preventing API calls. ```json { "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required", "code": "REFRESH_FAILED" } ``` Possible error codes: - `ACCOUNT_ERROR` - Account has a blocking error - `REFRESH_FAILED` - Automatic token refresh failed - `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly - `SESSION_EXPIRED` - Session expired and no auto-refresh available - `COOKIE_EXPIRED` - Google cookie has expired To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts). ##### Examples **Curl** ``` bash curl -X DELETE "https://api.useapi.net/v1/mureka/speech/?id=23456789012345" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const speechId = "Speech ID to delete"; const apiUrl = `https://api.useapi.net/v1/mureka/speech/?id=${speechId}`; const response = await fetch(apiUrl, { method: "DELETE", headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" speech_id = "Speech ID to delete" apiUrl = f"https://api.useapi.net/v1/mureka/speech/?id={speech_id}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-mureka-v1/get-mureka-accounts-account === Document URL: https://useapi.net/docs/api-mureka-v1/get-mureka-accounts-account --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts/`account` description: "Retrieve the configuration for a specific Mureka API account by name via GET accounts/account in the useapi.net Mureka API v1." parent: Mureka API nav_order: 200 --- ## Retrieve Mureka API account configuration for `account` December 2, 2024 (November 16, 2026) --- [Setup Mureka](/docs/start-here/setup-mureka) > **https://api.useapi.net/v1/mureka/accounts/`account`** The `account` value should correspond to an account configured previously via a [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts) request. ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** Secret values (token, refresh_token, password) are masked. `authMode` shows how the account authenticates — here `email` (email + password): ```json { "account": "150670177140737", "token": "eyJ…secured…", "refresh_token": "eyJ…secured…", "password": "…secured…", "authMode": "email", "token_expires": 1787197734000, "refresh_expires": 1789789733000, "updated": 1784605734942, "email": "you@example.com", "hasAutoRefresh": true, "tokenIssuedDaysAgo": 0, "updatedUTC": "2026-07-21T03:48:54.000Z", "tokenExpiresUTC": "2026-08-20T03:48:54.000Z", "refreshExpiresUTC": "2026-09-19T03:48:53.000Z" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** Configuration not found. To create configuration use [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts). ##### Model The account's configuration, with masked secrets, how it signs in (`authMode`), token expiry dates and `error` when it needs re-linking. <details markdown="block" class="model-details"> <summary>The account's configuration, field by field</summary> ```typescript { // TypeScript, all fields are optional account: string token: string // masked refresh_token?: string // masked — present on email and token accounts password?: string // masked — present only on email (email + password) accounts authMode?: "email" | "token" // "email" = email + password (the API re-logs in automatically when the session ends); "token" = session/refresh-token only (re-link on expiry); absent = legacy Google cookie / direct token token_expires?: number // access-token expiry, epoch ms (~30 days out) refresh_expires?: number // refresh-token expiry, epoch ms (~60 days out) updated: number updatedUTC: string tokenExpiresUTC?: string refreshExpiresUTC?: string tokenIssuedDaysAgo: number hasAutoRefresh: boolean email?: string sessionCookie?: { // legacy Google __Secure-3PSID accounts only name: string value: string domain: string path: string expires: string httpOnly: boolean secure: boolean sameSite: string added?: string } error?: string // present when the account needs re-linking } ``` </details> ##### Examples **Curl** ``` bash curl https://api.useapi.net/v1/mureka/accounts/<account> \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const account = "Previously configured account"; const apiUrl = `https://api.useapi.net/v1/mureka/accounts/${account}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" account = "Previously configured account" apiUrl = f"https://api.useapi.net/v1/mureka/accounts/{account}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-mureka-v1/get-mureka-accounts === Document URL: https://useapi.net/docs/api-mureka-v1/get-mureka-accounts --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts description: "List all configured Mureka API accounts via GET accounts in the useapi.net Mureka API v1 — complete account configuration with credentials and status." parent: Mureka API nav_order: 100 --- ## Retrieve Mureka API accounts configuration December 2, 2024 (November 16, 2026) --- This endpoint retrieves the complete list of configured API accounts for Mureka. [Setup Mureka](/docs/start-here/setup-mureka) > **https://api.useapi.net/v1/mureka/accounts** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** Secret values (token, refresh_token, password, cookie) are masked. `authMode` shows how each account authenticates: `email` (email + password), `token` (session/refresh-token), or absent (legacy Google cookie / direct token). ```json { "150670177140737": { "account": "150670177140737", "token": "eyJ…secured…", "refresh_token": "eyJ…secured…", "password": "…secured…", "authMode": "email", "token_expires": 1787197734000, "refresh_expires": 1789789733000, "updated": 1784605734942, "email": "you@example.com", "hasAutoRefresh": true, "tokenIssuedDaysAgo": 0, "updatedUTC": "2026-07-21T03:48:54.000Z", "tokenExpiresUTC": "2026-08-20T03:48:54.000Z", "refreshExpiresUTC": "2026-09-19T03:48:53.000Z" }, "42423380213761": { "account": "42423380213761", "token": "eyJ…secured…", "refresh_token": "eyJ…secured…", "authMode": "token", "token_expires": 1787114588000, "refresh_expires": 1789706570000, "updated": 1784522588916, "email": "user@gmail.com", "hasAutoRefresh": true, "tokenIssuedDaysAgo": 1, "updatedUTC": "2026-07-20T04:43:08.000Z", "tokenExpiresUTC": "2026-08-19T04:43:08.000Z", "refreshExpiresUTC": "2026-09-18T04:42:50.000Z" }, "987654321": { "account": "987654321", "token": "def…secured…uvw", "updated": 1724514995, "updatedUTC": "2024-10-24T15:56:35.000Z", "tokenIssuedDaysAgo": 1, "hasAutoRefresh": false, "email": "legacy@gmail.com", "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required" } } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** Configuration not found. To create configuration use [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts). ##### Model An object keyed by account, each holding that account's configuration as [GET /accounts/`account`](/docs/api-mureka-v1/get-mureka-accounts-account) returns it. <details markdown="block" class="model-details"> <summary>The configuration of each account, field by field</summary> ```typescript { // TypeScript, all fields are optional [account: string]: { account: string token: string // masked refresh_token?: string // masked — present on email and token accounts password?: string // masked — present only on email (email + password) accounts authMode?: "email" | "token" // "email" = email + password (the API re-logs in automatically when the session ends); "token" = session/refresh-token only (re-link on expiry); absent = legacy Google cookie / direct token token_expires?: number // access-token expiry, epoch ms (~30 days out) refresh_expires?: number // refresh-token expiry, epoch ms (~60 days out) updated: number updatedUTC: string tokenExpiresUTC?: string refreshExpiresUTC?: string tokenIssuedDaysAgo: number hasAutoRefresh: boolean email?: string sessionCookie?: { // legacy Google __Secure-3PSID accounts only name: string value: string domain: string path: string expires: string httpOnly: boolean secure: boolean sameSite: string added?: string } error?: string // present when the account needs re-linking } } ``` </details> ##### Examples **Curl** ``` bash curl https://api.useapi.net/v1/mureka/accounts \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = "https://api.useapi.net/v1/mureka/accounts"; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" apiUrl = "https://api.useapi.net/v1/mureka/accounts" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-mureka-v1/get-mureka-files-youtube === Document URL: https://useapi.net/docs/api-mureka-v1/get-mureka-files-youtube --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> files/youtube description: "Retrieve a downloadable link to a YouTube video's soundtrack via GET files/youtube in the useapi.net Mureka API v1." parent: Mureka API nav_order: 1700 --- ## Retrieve soundtrack from YouTube url December 13, 2024 (November 16, 2026) --- This endpoint will return a link to the YouTube video soundtrack. You can download it, adjust if needed, and upload it to your track collection using [POST /files](/docs/api-mureka-v1/post-mureka-files). > **https://api.useapi.net/v1/mureka/files/youtube/?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `url` is **required**. Provide the YouTube url link for which you want to retrieve the soundtrack. ##### Responses **200** **200 OK** ```json { "name": "<YouTube video name>", "cos_url": "https://...mp3", "duration": 21000 } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **596** **596 Account Error** Returned when the account has an error state preventing API calls. ```json { "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required", "code": "REFRESH_FAILED" } ``` Possible error codes: - `ACCOUNT_ERROR` - Account has a blocking error - `REFRESH_FAILED` - Automatic token refresh failed - `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly - `SESSION_EXPIRED` - Session expired and no auto-refresh available - `COOKIE_EXPIRED` - Google cookie has expired To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts). ##### Model The soundtrack's name, its download link in `cos_url` and its duration. <details markdown="block" class="model-details"> <summary>The YouTube soundtrack link, field by field</summary> ```typescript { // TypeScript, all fields are optional name: string cos_url: string duration: number } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/mureka/files/youtube/?account=account&url=<url>" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const account = "Previously configured account"; const url = "YouTube video url"; const apiUrl = `https://api.useapi.net/v1/mureka/files/youtube/?account=${account}&url=${url}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" account = "Previously configured account" url = "YouTube video url" apiUrl = f"https://api.useapi.net/v1/mureka/files/youtube/?account={account}&url={url}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-mureka-v1/get-mureka-files === Document URL: https://useapi.net/docs/api-mureka-v1/get-mureka-files --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> files description: "List all reference tracks you have uploaded via GET files in the useapi.net Mureka API v1 — returns IDs for use as ref_id in advanced music generation." parent: Mureka API nav_order: 1600 --- ## Retrieve your reference tracks December 13, 2024 (November 16, 2026) --- Retrieve full list of track uploaded using [POST /files](/docs/api-mureka-v1/post-mureka-files). Keep in mind that all uploaded files will be visible to all users of Mureka.ai website. Use `id` value to reference a track when using the parameter `ref_id` of [POST /music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced). > **https://api.useapi.net/v1/mureka/files/?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `last_id` is optional. Use it to retrieve the next page of data. To do so, set its value to the `last_id` returned in the previous response when the `more` field in that response is `true`. ##### Responses **200** **200 OK** ```json { "list": [ { "id": 1122334455, "url": "https://<song download url>.mp3", "duration_milliseconds": 30000, "mood": "relaxed", "title": "<song title>", "genre": "afrobeat", "username": "<user name>" }, { "id": 66778899, "url": "https://<song download url>.mp3", "duration_milliseconds": 30000, "mood": "restless", "title": "<song title>", "genre": "rock", "username": "<user name>" } ], "last_id": 77665544332211, "more": true } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **596** **596 Account Error** Returned when the account has an error state preventing API calls. ```json { "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required", "code": "REFRESH_FAILED" } ``` Possible error codes: - `ACCOUNT_ERROR` - Account has a blocking error - `REFRESH_FAILED` - Automatic token refresh failed - `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly - `SESSION_EXPIRED` - Session expired and no auto-refresh available - `COOKIE_EXPIRED` - Google cookie has expired To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts). ##### Model A page of your uploaded reference tracks, each with the `id` to pass as `ref_id`, plus `last_id` and `more` for the next page. <details markdown="block" class="model-details"> <summary>The list of reference tracks, field by field</summary> ```typescript { // TypeScript, all fields are optional list: { id: number url: string duration_milliseconds: number mood: string title: string genre: string username: string }[] last_id: number more: boolean } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/mureka/files/?account=account" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const account = "Previously configured account"; const apiUrl = `https://api.useapi.net/v1/mureka/files/?account=${account}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" account = "Previously configured account" apiUrl = f"https://api.useapi.net/v1/mureka/files/?account={account}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-mureka-v1/get-mureka-jobs-jobid === Document URL: https://useapi.net/docs/api-mureka-v1/get-mureka-jobs-jobid --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> jobs/`jobid` description: "Poll the status and results of a music or speech generation job by job ID via GET jobs/jobid in the useapi.net Mureka API v1 — essential for async mode." parent: Mureka API nav_order: 2460 --- ## Retrieve Job Status January 21, 2026 (November 16, 2026) --- Retrieve the status and details of a specific music or speech generation job by its job ID. This endpoint is particularly useful when using `async` mode for music or speech generation, or when tracking job progress via webhooks using the `replyUrl` parameter. Job IDs are returned from: * [POST /music/create](/docs/api-mureka-v1/post-mureka-music-create) * [POST /music/create-instrumental](/docs/api-mureka-v1/post-mureka-music-create-instrumental) * [POST /music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced) * [POST /music/extend](/docs/api-mureka-v1/post-mureka-music-extend) * [POST /music/edit](/docs/api-mureka-v1/post-mureka-music-edit) * [POST /music/remix](/docs/api-mureka-v1/post-mureka-music-remix) * [POST /music/stems](/docs/api-mureka-v1/post-mureka-music-stems) * [POST /speech](/docs/api-mureka-v1/post-mureka-speech) Jobs are retained for 7 days after creation. Jobs older than 7 days will return a 404 error. While a [POST /music/stems](/docs/api-mureka-v1/post-mureka-music-stems) job is still `created`, each call checks the extraction with Mureka, so the job turns `completed` as soon as the stems are ready. To get a summary of all running jobs, use [GET /jobs](/docs/api-mureka-v1/get-mureka-jobs). > **https://api.useapi.net/v1/mureka/jobs/`jobid`** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Path Parameters - `jobid` is **required**, the unique job identifier. ##### Responses **200** **200 OK** Returns the job record with current status and details. **Music job (completed):** ```json { "jobid": "j0121061432017475905m-u777-a12345678901234-bot:mureka", "verb": "music/create", "jobType": "music", "status": "completed", "created": "2026-01-20T12:34:56.789Z", "updated": "2026-01-20T12:35:42.123Z", "request": { "account": "12345678901234", "prompt": "Upbeat electronic dance track", "model": "V7.6", "async": true, "replyUrl": "https://your-domain.com/webhook", "replyRef": "my-custom-ref-123" }, "response": { "feed_id": 11223344, "state": 3, "songs": [ { "song_id": "user:777-mureka:123456789-song:33445566", "title": "Upbeat Dance", "version": "1", "duration_milliseconds": 234567, "mp3_url": "https://...mp3", "cover": "https://...png" }, { "song_id": "user:777-mureka:123456789-song:33445567", "title": "Upbeat Dance", "version": "2", "duration_milliseconds": 234890, "mp3_url": "https://...mp3", "cover": "https://...png" } ] } } ``` **Speech job (completed):** ```json { "jobid": "j0121061456745673364t-u777-a12345678901234-bot:mureka", "verb": "speech", "jobType": "tts", "status": "completed", "created": "2026-01-20T12:40:00.000Z", "updated": "2026-01-20T12:40:25.000Z", "request": { "account": "12345678901234", "text": "Hello, this is a test speech.", "voice_id": 12345, "async": true }, "response": { "title": "Hello, this is a test speech.", "mp3_url": "https://...mp3", "duration_milliseconds": 5000, "state": 3 } } ``` **Job still processing:** ```json { "jobid": "j0121061432017475905m-u777-a12345678901234-bot:mureka", "verb": "music/create", "jobType": "music", "status": "created", "created": "2026-01-20T12:34:56.789Z", "request": { "account": "12345678901234", "prompt": "Upbeat electronic dance track", "async": true } } ``` **Job failed:** ```json { "jobid": "j0121061432017475905m-u777-a12345678901234-bot:mureka", "verb": "music/create", "jobType": "music", "status": "failed", "created": "2026-01-20T12:34:56.789Z", "updated": "2026-01-20T12:35:10.000Z", "request": { "account": "12345678901234", "prompt": "Test prompt", "async": true }, "error": "Content policy violation", "code": 400 } ``` **400** **400 Bad Request** Invalid job ID format. ```json { "error": "Invalid job ID: Missing required component" } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "Unauthorized", "code": 401 } ``` **403** **403 Forbidden** Job belongs to a different user. ```json { "error": "Unauthorized access to job" } ``` **404** **404 Not Found** Job not found or has expired (jobs are retained for 7 days). ```json { "error": "Job not found" } ``` ##### Model The job record, with its `status`, the original request and, once completed, the result: songs, stems or speech. <details markdown="block" class="model-details"> <summary>The job record for music, stems and speech jobs, field by field</summary> **Music Job** Music generation job structure. ```typescript { jobid: string // Unique job identifier verb: 'music/create' | 'music/create-instrumental' | 'music/create-advanced' | 'music/regenerate' | 'music/extend' | 'music/edit' | 'music/remix' jobType: 'music' // Job type status: 'created' | 'completed' | 'failed' created: string // ISO 8601 creation timestamp updated?: string // ISO 8601 last update timestamp request: { account?: string // Mureka account ID prompt?: string // Text prompt (for create endpoints) title?: string // Song title lyrics?: string // Lyrics (for create-advanced, extend) song_id?: string // Source song ID (for extend, edit, remix) start_milliseconds?: number // Start position (for edit) model?: string // AI model used instrumental_model?: string // Instrumental model (for create-instrumental) ref_id?: string // Reference track ID vocal_id?: string // Vocal library ID motif_id?: string // Motif ID mood?: string // Mood tag genre?: string // Genre tag vocal_gender?: string // Vocal gender (male, female) async?: boolean // Fire-and-forget mode replyUrl?: string // Webhook URL for callbacks replyRef?: string // Custom reference for callbacks } response?: { // Present when completed feed_id: number state: number songs: Array<{ song_id: string title: string version: string duration_milliseconds: number generate_at: number genres: string[] moods: string[] mp3_url: string share_key: string cover: string share_link: string }> } error?: string // Error message (if failed) errorDetails?: string // Additional error details code?: number // HTTP status code (if failed) } ``` **Stems Job** Stems extraction job structure, see [POST /music/stems](/docs/api-mureka-v1/post-mureka-music-stems). ```typescript { jobid: string // Unique job identifier verb: 'music/stems' // Job verb jobType: 'music' // Job type status: 'created' | 'completed' | 'failed' created: string // ISO 8601 creation timestamp updated?: string // ISO 8601 last update timestamp request: { account: string // Mureka account ID song_id: number // Source song ID all_stems: boolean // true = all detected stems, false = vocals + instrumental async?: boolean // Fire-and-forget mode replyUrl?: string // Webhook URL for callbacks replyRef?: string // Custom reference for callbacks } response?: { stems_id: string // Pass to POST /music/stems-download song_id: string all_stems?: boolean bpm?: number status: 'processing' | 'completed' generate_state?: number // Mureka's own state: 3 while extracting, 1 when done stems?: Array<{ // Present when completed stem_name: string wav: string | null mp3: string | null }> } error?: string // Error message (if failed) code?: number // HTTP status code (if failed) } ``` **Speech Job** Speech generation job structure. ```typescript { jobid: string // Unique job identifier verb: 'speech' // Job verb jobType: 'tts' // Job type status: 'created' | 'completed' | 'failed' created: string // ISO 8601 creation timestamp updated?: string // ISO 8601 last update timestamp request: { account?: string // Mureka account ID title?: string // Speech title text?: string // Text to convert to speech voice_id?: number // Voice ID conversation?: Array<{voice_id: number, text: string}> // Multi-speaker conversation async?: boolean // Fire-and-forget mode replyUrl?: string // Webhook URL for callbacks replyRef?: string // Custom reference for callbacks } response?: { // Present when completed title: string preview: string cover: string mp3_url: string id: number duration_milliseconds: number audio_quality: number state: number } error?: string // Error message (if failed) errorDetails?: string // Additional error details code?: number // HTTP status code (if failed) } ``` </details> ##### Examples **Curl** ```bash # Get job status curl "https://api.useapi.net/v1/mureka/jobs/j0121061432017475905m-u777-a12345678901234-bot:mureka" \ -H "Authorization: Bearer {API token}" # Poll for completion (check every 5 seconds) while true; do STATUS=$(curl -s "https://api.useapi.net/v1/mureka/jobs/j0121061432017475905m-u777-a12345678901234-bot:mureka" \ -H "Authorization: Bearer {API token}" | jq -r '.status') echo "Status: $STATUS" if [[ "$STATUS" == "completed" || "$STATUS" == "failed" ]]; then break fi sleep 5 done ``` **JavaScript** ```javascript const token = "API token"; const jobid = "j0121061432017475905m-u777-a12345678901234-bot:mureka"; // Get job status async function getJobStatus(jobid) { const response = await fetch(`https://api.useapi.net/v1/mureka/jobs/${jobid}`, { headers: { "Authorization": `Bearer ${token}` } }); if (!response.ok) { throw new Error(`HTTP ${response.status}: ${await response.text()}`); } return await response.json(); } // Poll until completion async function waitForCompletion(jobid, intervalMs = 5000) { while (true) { const job = await getJobStatus(jobid); console.log(`Status: ${job.status}`); if (job.status === "completed") { console.log("Job completed!", job.response); return job; } if (job.status === "failed") { console.error("Job failed:", job.error); throw new Error(job.error); } await new Promise(resolve => setTimeout(resolve, intervalMs)); } } // Usage const job = await waitForCompletion(jobid); // Access song URLs (for music jobs) if (job.jobType === "music" && job.response?.songs) { job.response.songs.forEach((song, i) => { console.log(`Song ${i + 1}: ${song.mp3_url}`); }); } // Access audio URL (for speech jobs) if (job.jobType === "tts" && job.response?.mp3_url) { console.log(`Speech audio: ${job.response.mp3_url}`); } ``` **Python** ```python import requests import time token = "API token" jobid = "j0121061432017475905m-u777-a12345678901234-bot:mureka" # Get job status def get_job_status(jobid: str) -> dict: response = requests.get( f"https://api.useapi.net/v1/mureka/jobs/{jobid}", headers={"Authorization": f"Bearer {token}"} ) response.raise_for_status() return response.json() # Poll until completion def wait_for_completion(jobid: str, interval_sec: int = 5) -> dict: while True: job = get_job_status(jobid) print(f"Status: {job['status']}") if job["status"] == "completed": print("Job completed!", job["response"]) return job if job["status"] == "failed": raise Exception(f"Job failed: {job.get('error')}") time.sleep(interval_sec) # Usage job = wait_for_completion(jobid) # Access song URLs (for music jobs) if job["jobType"] == "music" and job.get("response", {}).get("songs"): for i, song in enumerate(job["response"]["songs"]): print(f"Song {i + 1}: {song['mp3_url']}") # Access audio URL (for speech jobs) if job["jobType"] == "tts" and job.get("response", {}).get("mp3_url"): print(f"Speech audio: {job['response']['mp3_url']}") ``` === URL: https://useapi.net/docs/api-mureka-v1/get-mureka-jobs === Document URL: https://useapi.net/docs/api-mureka-v1/get-mureka-jobs --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> jobs description: "List all currently running music and speech generation jobs across your Mureka accounts via GET jobs in the useapi.net Mureka API v1." parent: Mureka API nav_order: 2450 --- ## List Running Jobs January 21, 2026 (November 16, 2026) --- Retrieve a summary of all currently running jobs for your user account. This endpoint is useful for monitoring active music and speech generation jobs across all your configured Mureka accounts. Jobs are retained for 7 days after creation. Running jobs are tracked separately and show real-time elapsed time. > **https://api.useapi.net/v1/mureka/jobs** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** Returns summary of running jobs grouped by account. ```json { "total": 3, "music": 2, "tts": 1, "accounts": { "12345678901234": { "total": 3, "music": 2, "tts": 1, "jobs": [ { "jobid": "j0121061456745673364t-u777-a12345678901234-bot:mureka", "verb": "speech", "elapsed": "00:00" }, { "jobid": "j0121061432017475905m-u777-a12345678901234-bot:mureka", "verb": "music/create", "elapsed": "00:24" }, { "jobid": "j0121061447693272611m-u777-a12345678901234-bot:mureka", "verb": "music/create-advanced", "elapsed": "00:09" } ] } }, "availableAccounts": [ "98765432109876", "12345678901234" ] } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model Counts of your running music and speech jobs, in total and per account, with each job's `jobid`, `verb` and elapsed time. <details markdown="block" class="model-details"> <summary>The running jobs by account, field by field</summary> ```typescript { total: number // Total number of running jobs music: number // Number of music generation jobs tts: number // Number of speech (TTS) jobs accounts: { [accountId: string]: { total: number // Jobs for this account music: number // Music jobs for this account tts: number // TTS jobs for this account jobs: Array<{ jobid: string // Unique job identifier verb: 'music/create' | 'music/create-instrumental' | 'music/create-advanced' | 'music/regenerate' | 'music/extend' | 'music/edit' | 'music/remix' | 'music/stems' | 'speech' elapsed: string // Human-readable elapsed time (e.g., "45s", "1m 23s") }> } } availableAccounts: string[] // List of configured account IDs } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/mureka/jobs" \ -H "Authorization: Bearer {API token}" ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = "https://api.useapi.net/v1/mureka/jobs"; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}` } }); const result = await response.json(); console.log("Running jobs:", result.total); console.log("Music jobs:", result.music); console.log("TTS jobs:", result.tts); // Check jobs per account for (const [accountId, data] of Object.entries(result.accounts)) { console.log(`Account ${accountId}: ${data.total} jobs`); data.jobs.forEach(job => { console.log(` - ${job.jobid} (${job.verb}) running for ${job.elapsed}`); }); } ``` **Python** ``` python import requests token = "API token" api_url = "https://api.useapi.net/v1/mureka/jobs" headers = { "Authorization": f"Bearer {token}" } response = requests.get(api_url, headers=headers) result = response.json() print(f"Running jobs: {result['total']}") print(f"Music jobs: {result['music']}") print(f"TTS jobs: {result['tts']}") # Check jobs per account for account_id, data in result['accounts'].items(): print(f"Account {account_id}: {data['total']} jobs") for job in data['jobs']: print(f" - {job['jobid']} ({job['verb']}) running for {job['elapsed']}") ``` === URL: https://useapi.net/docs/api-mureka-v1/get-mureka-music-characters === Document URL: https://useapi.net/docs/api-mureka-v1/get-mureka-music-characters --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> music/characters description: "List the Mureka characters (reusable singers) on an account, newest first, via GET music/characters in the useapi.net Mureka API v1." parent: Mureka API nav_order: 950 --- ## List characters October 16, 2026 (November 16, 2026) --- > **https://api.useapi.net/v1/mureka/music/characters/?…** List the characters you created with [POST /music/characters](/docs/api-mureka-v1/post-mureka-music-characters) or on [mureka.ai](https://www.mureka.ai), newest first, 20 per page. Pass a character's `id` as `character_id` to [POST /music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced). ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) is configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `last_id` is optional, the `last_id` value of the previous page, to get the next page. ##### Responses **200** **200 OK** `list` is empty when the account has no characters. A private character has no `is_published` field. ```json { "list": [ { "id": 166751507709953, "name": "Scarlett", "bio": "A clear, articulate mid-range female voice.", "tags": [ "Female", "Powerful" ], "avatar": "https://static-cos.mureka.ai/cos-prod/mureka/static/img/<id>.jpg", "is_published": true, "user_id": 12345678901234, "published_at": 1792191715, "created_at": 1792191715, "user": { "id": "12345678901234", "user_id": 12345678901234, "stage_name": "user@example.com", "profile_image": "https://static-cos.mureka.ai/cos-prod/res/image/portrait/2b_default.png" }, "asset_id": 166751507578881, "showcase_edit_range": {}, "song_description": "An intimate mid-tempo acoustic pop song with soft piano and a clear female lead vocal." } ], "last_id": 166751507709953 } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Wrong username/password combination.", "code": 401 } ``` **596** **596 Account Error** Returned when the account has an error state preventing API calls. ```json { "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required", "code": "REFRESH_FAILED" } ``` Possible error codes: - `ACCOUNT_ERROR` - Account has a blocking error - `REFRESH_FAILED` - Automatic token refresh failed - `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly - `SESSION_EXPIRED` - Session expired and no auto-refresh available - `COOKIE_EXPIRED` - Google cookie has expired To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts). ##### Model A page of your characters, newest first, each with the `id` to pass as `character_id`, plus `last_id` for the next page. <details markdown="block" class="model-details"> <summary>The list of characters, field by field</summary> ```typescript { list: { id: number // character_id for POST /music/create-advanced name: string bio?: string tags?: string[] avatar?: string is_published?: boolean // left out when the character is private published_at?: number // Unix seconds created_at?: number // Unix seconds song_use_count?: number // songs made with this character vocal_showcase?: string // preview audio, for characters made on mureka.ai song_description?: string user_id?: number user?: object asset_id?: number showcase_edit_range?: object }[] last_id?: number // pass as last_id for the next page } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Authorization: Bearer …" \ "https://api.useapi.net/v1/mureka/music/characters/?account=<account>" ``` **JavaScript** ``` javascript const account = "12345678901234"; const apiUrl = `https://api.useapi.net/v1/mureka/music/characters/?account=${account}`; const token = "API token"; const data = { method: 'GET', headers: { 'Authorization': `Bearer ${token}` } }; const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests account = "12345678901234" apiUrl = f"https://api.useapi.net/v1/mureka/music/characters/?account={account}" token = "API token" headers = { "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-mureka-v1/get-mureka-music-moods-and-genres === Document URL: https://useapi.net/docs/api-mureka-v1/get-mureka-music-moods-and-genres --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> music/moods-and-genres description: "Retrieve all supported genres, moods, and vocals for Mureka music creation via GET music/moods-and-genres in the useapi.net Mureka API v1." parent: Mureka API nav_order: 800 --- ## Retrieve a list of supported Genres, Moods and Vocals December 2, 2024 (November 16, 2026) --- > **https://api.useapi.net/v1/mureka/music/moods-and-genres/?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. ##### Responses **200** **200 OK** ```json { "genres": [ { "tag": "pop", "cover": "cos-prod/res/image/Pop@4x.png" }, { "tag": "<genre 2>", "cover": "<cover image 1>" }, { "tag": "<genre NN>", "cover": "<cover image NN>" } ], "moods": [ { "tag": "relaxed" }, { "tag": "<mood 2>" }, { "tag": "<mood NN>" } ], "vocals": [ { "tag": "female vocal" }, { "tag": "male vocal" } ] } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **596** **596 Account Error** Returned when the account has an error state preventing API calls. ```json { "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required", "code": "REFRESH_FAILED" } ``` Possible error codes: - `ACCOUNT_ERROR` - Account has a blocking error - `REFRESH_FAILED` - Automatic token refresh failed - `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly - `SESSION_EXPIRED` - Session expired and no auto-refresh available - `COOKIE_EXPIRED` - Google cookie has expired To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts). ##### Model The genre, mood and vocal tags Mureka supports, each as a `tag` string. <details markdown="block" class="model-details"> <summary>The genre, mood and vocal tags, field by field</summary> ```typescript { // TypeScript, all fields are optional genres: { tag: string, cover?: string }[] moods: { tag: string }[] vocals: { tag: string }[] } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/mureka/music/moods-and-genres/?account=account" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const account = "Previously configured account"; const apiUrl = `https://api.useapi.net/v1/mureka/music/moods-and-genres/?account=${account}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" account = "Previously configured account" apiUrl = f"https://api.useapi.net/v1/mureka/music/moods-and-genres/?account={account}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-mureka-v1/get-mureka-music-refs === Document URL: https://useapi.net/docs/api-mureka-v1/get-mureka-music-refs --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> music/refs description: "Browse Mureka's built-in reference songs filterable by mood and genre via GET music/refs in the useapi.net Mureka API v1." parent: Mureka API nav_order: 1000 --- ## Retrieve a list of reference songs December 2, 2024 (November 16, 2026) --- > **https://api.useapi.net/v1/mureka/music/refs/?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `mood` is optional. Filter songs by mood, to retrieve list supported moods use [GET music/moods-and-genres](/docs/api-mureka-v1/get-mureka-music-moods-and-genres). - `genre` is optional. Filter songs by genre, to retrieve list supported genres use [GET music/moods-and-genres](/docs/api-mureka-v1/get-mureka-music-moods-and-genres). - `last_id` is optional. Use it to retrieve the next page of data. To do so, set its value to the `last_id` returned in the previous response when the `more` field in that response is `true`. ##### Responses **200** **200 OK** ```json { "list": [ { "id": 1122334455, "url": "https://<song download url>.mp3", "duration_milliseconds": 30000, "mood": "relaxed", "title": "<song title>", "genre": "afrobeat", "username": "<user name>" }, { "id": 66778899, "url": "https://<song download url>.mp3", "duration_milliseconds": 30000, "mood": "restless", "title": "<song title>", "genre": "rock", "username": "<user name>" } ], "last_id": 77665544332211, "more": true } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **596** **596 Account Error** Returned when the account has an error state preventing API calls. ```json { "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required", "code": "REFRESH_FAILED" } ``` Possible error codes: - `ACCOUNT_ERROR` - Account has a blocking error - `REFRESH_FAILED` - Automatic token refresh failed - `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly - `SESSION_EXPIRED` - Session expired and no auto-refresh available - `COOKIE_EXPIRED` - Google cookie has expired To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts). ##### Model A page of reference songs, each with its `id`, audio `url`, mood and genre, plus `last_id` and `more` for the next page. <details markdown="block" class="model-details"> <summary>The list of reference songs, field by field</summary> ```typescript { // TypeScript, all fields are optional list: { id: number url: string duration_milliseconds: number mood: string title: string genre: string username: string }[] last_id: number more: boolean } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/mureka/music/refs/?account=account" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const account = "Previously configured account"; const apiUrl = `https://api.useapi.net/v1/mureka/music/refs/?account=${account}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" account = "Previously configured account" apiUrl = f"https://api.useapi.net/v1/mureka/music/refs/?account={account}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-mureka-v1/get-mureka-music-song_id === Document URL: https://useapi.net/docs/api-mureka-v1/get-mureka-music-song_id --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> music/`song_id` description: "Retrieve lyrics, audio URLs, and metadata for a specific generated song via GET music/song_id in the useapi.net Mureka API v1." parent: Mureka API nav_order: 700 --- ## Retrieve generated song lyrics and other details December 2, 2024 (November 16, 2026) --- > **https://api.useapi.net/v1/mureka/music/`song_id`** The `song_id` value returned by one of the following endpoints: * [GET /music](/docs/api-mureka-v1/get-mureka-music) * [POST /music/create](/docs/api-mureka-v1/post-mureka-music-create) * [POST /music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced) * [POST /music/create-instrumental](/docs/api-mureka-v1/post-mureka-music-create-instrumental) ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** ```json { "song": { "song_id": "user:777-mureka:987654321-song:123456789", "title": "<song title>", "version": "1", "duration_milliseconds": 1234567, "generate_at": 123456789, "genres": [ "rock", "metal" ], "moods": [ "majestic", "romantic", "mysterious" ], "mp3_url": "https://<download link>.mp3", "share_key": "<share key>", "machine_audit_state": 1, "credit_type": 1, "cover": "https://<cover image>.png", "lyrics": [ { "rows": [ { "start": 1, "end": 100, "text": "lyrics here" }, { "start": 200, "end": 300, "text": "lyrics continues" } ] } ], "video": {}, "share_link": "https://<share link>" }, "user": { "id": "987654321", "user_id": 987654321, "stage_name": "<stage name>", "profile_image": "https://<profile image>.png" }, "feed_id": 998877665544332211, "conn_id": "…", "state": 3, "generation_method": 1, "model": "O1" } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** ```json { "error": "The song has been deleted" } ``` **596** **596 Account Error** Returned when the account has an error state preventing API calls. ```json { "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required", "code": "REFRESH_FAILED" } ``` Possible error codes: - `ACCOUNT_ERROR` - Account has a blocking error - `REFRESH_FAILED` - Automatic token refresh failed - `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly - `SESSION_EXPIRED` - Session expired and no auto-refresh available - `COOKIE_EXPIRED` - Google cookie has expired To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts). ##### Model The song with its `mp3_url`, cover and lyrics, plus the `user` profile and the `model` used. <details markdown="block" class="model-details"> <summary>The song record with its lyrics, field by field</summary> ```typescript { // TypeScript, all fields are optional song: { song_id: number title: string version: string duration_milliseconds: number generate_at: number genres: string[] moods: string[] mp3_url: string share_key: string share_link: string machine_audit_state: number credit_type: number cover: string lyrics: { seg_type: number user_input_tag: string start?: number end?: number rows?: { start?: number end?: number text: string }[] }[] video?: { video_url: string video_cover_url: string video_id: number } } user: { id: string user_id: number stage_name: string profile_image: string } feed_id: number conn_id: string state: number generation_method: number model: string } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/mureka/music/song_id" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const song_id = "song_id"; const apiUrl = `https://api.useapi.net/v1/mureka/music/${song_id}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" song_id = "song_id" apiUrl = f"https://api.useapi.net/v1/mureka/music/{song_id}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-mureka-v1/get-mureka-music-vocals === Document URL: https://useapi.net/docs/api-mureka-v1/get-mureka-music-vocals --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> music/vocals description: "List available vocal samples — including your custom-uploaded vocals — via GET music/vocals in the useapi.net Mureka API v1." parent: Mureka API nav_order: 900 --- ## Retrieve a list of vocal samples including the ones you uploaded December 2, 2024 (November 16, 2026) --- > **https://api.useapi.net/v1/mureka/music/vocals/?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `last_id` is optional. Use it to retrieve the next page of data. To do so, set its value to the `last_id` returned in the previous response when the `more` field in that response is `true`. - `mine` is optional. Set to `true` to retrieve list of vocals uploaded via [POST files/vocal](/docs/api-mureka-v1/post-mureka-files-vocal). Supported values: `true`, `false` (default). ##### Responses **200** **200 OK** ```json { "list": [ { "id": 47235584950273, "url": "https://...mp3", "duration_milliseconds": 40731, "gender": 2, "title": "James", "created_at": 1735202082, "username": "Star_Boy", "background_url": "https://...jpg" }, { "id": 48696156946433, "url": "https://...mp3", "duration_milliseconds": 49059, "gender": 2, "title": "Bella", "created_at": 1735898537, "username": "ZenZephyr", "background_url": "https://...jpeg" } ], "last_id": 1726311196088, "more": true } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **596** **596 Account Error** Returned when the account has an error state preventing API calls. ```json { "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required", "code": "REFRESH_FAILED" } ``` Possible error codes: - `ACCOUNT_ERROR` - Account has a blocking error - `REFRESH_FAILED` - Automatic token refresh failed - `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly - `SESSION_EXPIRED` - Session expired and no auto-refresh available - `COOKIE_EXPIRED` - Google cookie has expired To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts). ##### Model A page of vocal samples, each with its `id`, audio `url`, title and gender, plus `last_id` and `more` for the next page. <details markdown="block" class="model-details"> <summary>The list of vocal samples, field by field</summary> ```typescript { // TypeScript, all fields are optional list: { id: number url: string duration_milliseconds: number gender: number title: string created_at: number username: string background_url: string }[] last_id: number more: boolean } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/mureka/music/vocals/?account=account" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const account = "Previously configured account"; const apiUrl = `https://api.useapi.net/v1/mureka/music/vocals/?account=${account}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" account = "Previously configured account" apiUrl = f"https://api.useapi.net/v1/mureka/music/vocals/?account={account}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-mureka-v1/get-mureka-music === Document URL: https://useapi.net/docs/api-mureka-v1/get-mureka-music --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> music description: "Retrieve your generated Mureka music library via GET music in the useapi.net Mureka API v1 — paginated list of songs with audio URLs and metadata." parent: Mureka API nav_order: 600 --- ## Retrieve generated music December 2, 2024 (November 16, 2026) --- > **https://api.useapi.net/v1/mureka/music/?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `last_id` is optional. Use it to retrieve the next page of data. To do so, set its value to the `last_id` returned in the previous response when the `more` field in that response is `true`. - `expand` is optiona. Set it to `true` if you want to retrieve complete song details. Supported values: `true`, `false` (default). ##### Responses **200** **200 OK** ```json { "list": [ { "feed_id": 111222333, "state": 3, "songs": [ { "song_id": "user:777-mureka:123456789-song:111122222", "title": "<song title>", "version": "1", "duration_milliseconds": 123456, "generate_at": 123456789, "genres": [ "rock", "metal" ], "moods": [ "majestic", "romantic", "mysterious" ], "mp3_url": "https://<download link>.mp3", "share_key": "<share key>", "machine_audit_state": 1, "credit_type": 1, "cover": "https://<cover image>.png", "share_link": "https://<share link>" }, { "song_id": "user:777-mureka:123456789-song:33334444", "title": "<song title>", "version": "1", "duration_milliseconds": 223456, "generate_at": 223456789, "genres": [ "rock", "metal" ], "moods": [ "quirky", "relaxed", "mysterious" ], "mp3_url": "https://<download link>.mp3", "share_key": "<share key>", "machine_audit_state": 1, "credit_type": 1, "cover": "https://<cover image>.png", "share_link": "https://<share link>" } ], "conn_id": "…", "is_accelerated": true, "generation_method": 1, "model": "V6" }, { "feed_id": 444555666, "state": 3, "songs": [ { "song_id": "user:777-mureka:123456789-song:55556666", "title": "<song title>", "version": "1", "duration_milliseconds": 123456, "generate_at": 123456789, "genres": [ "latin", "world-music" ], "moods": [ "calm", "romantic", "happy" ], "mp3_url": "https://<download link>.mp3", "share_key": "<share key>", "machine_audit_state": 1, "credit_type": 1, "cover": "https://<cover image>.png", "share_link": "https://<share link>" }, { "song_id": "user:777-mureka:123456789-song:77778888", "title": "<song title>", "version": "1", "duration_milliseconds": 223456, "generate_at": 223456789, "genres": [ "pop", "indie" ], "moods": [ "majestic", "inspired", "quirky" ], "mp3_url": "https://<download link>.mp3", "share_key": "<share key>", "machine_audit_state": 1, "credit_type": 1, "cover": "https://<cover image>.png", "share_link": "https://<share link>" } ], "conn_id": "…", "is_accelerated": true, "generation_method": 1, "model": "O1" } ], "last_id": 123456789, "more": true, "total": 9623 } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **596** **596 Account Error** Returned when the account has an error state preventing API calls. ```json { "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required", "code": "REFRESH_FAILED" } ``` Possible error codes: - `ACCOUNT_ERROR` - Account has a blocking error - `REFRESH_FAILED` - Automatic token refresh failed - `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly - `SESSION_EXPIRED` - Session expired and no auto-refresh available - `COOKIE_EXPIRED` - Google cookie has expired To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts). ##### Model Your generated songs, grouped as they were created, each with its `song_id`, MP3 link and cover, plus `last_id` for paging. <details markdown="block" class="model-details"> <summary>The list of generated songs, field by field</summary> ```typescript { // TypeScript, all fields are optional list: { feed_id: number state: number songs: { song_id: number title: string version: string duration_milliseconds: number generate_at: number genres: string[] moods: string[] mp3_url: string share_key: string share_link: string machine_audit_state: number wave_list: number[] credit_type: number cover: string is_played?: boolean is_liked?: boolean video?: { video_url: string video_cover_url: string video_id: number } }[] is_accelerated: boolean conn_id: string generation_method: number model: string }[] last_id: number total: number } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/mureka/music/?account=account" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const account = "Previously configured account"; const apiUrl = `https://api.useapi.net/v1/mureka/music/?account=${account}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" account = "Previously configured account" apiUrl = f"https://api.useapi.net/v1/mureka/music/?account={account}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-mureka-v1/get-mureka-profile === Document URL: https://useapi.net/docs/api-mureka-v1/get-mureka-profile --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> profile description: "Retrieve your mureka.ai account information and remaining credit balance via GET profile in the useapi.net Mureka API v1." parent: Mureka API nav_order: 450 --- ## Retrieve your [mureka.ai](https://www.mureka.ai) account information and remaining credits December 2, 2024 (November 16, 2026) --- > **https://api.useapi.net/v1/mureka/profile/?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. ##### Responses **200** **200 OK** ```json { "user": { "id": "987654321", "user_id": 987654321, "stage_name": "useapi.net", "profile_image": "https://static-cos.mureka.ai/cos-prod/image/default.png", "is_vip": true, "vip_level": 2, "created_on": 1756353867, "sid": 123456789, "last_active_time": 1771038894, "country_code": "US", "register_ip": "192.168.0.1", "vip_end": 1771632412, "vip_name": "Monthly Pro", "vip_level_name": "basic", "vip_period_name": "month", "created_on_UTC": "2025-08-28T04:04:27.000Z", "vip_end_UTC": "2026-02-21T00:06:52.000Z" }, "country_code": "US", "credits": 500, "feed_list_count": 574, "credits_silver": 4, "free_download_mp3_models": [ "V8" ], "models": { "official_models": [ { "display_name": "V9.5", "model": "mureka-9.5", "description": "Natural songwriting, authentic performances, fuller sound.", "generation_amount": 1, "required_credits": 12, "supported_control_types": [ "refer", "prompt", "soundtrack", "motif", "vocal", "instrumental", "remix" ], "show_free_to_use": true, "app_display_name": "V9.5", "min_tier": "basic", "free_trial_window_days": 7 }, { "display_name": "V9", "model": "mureka-9", "description": "Advanced prompt control, studio-grade sound", "generation_amount": 1, "required_credits": 12, "supported_control_types": [ "refer", "prompt", "soundtrack", "motif", "vocal", "instrumental", "remix" ], "show_free_to_use": true, "app_display_name": "V9", "min_tier": "basic" }, { "display_name": "V8", "model": "mureka-8.0.1", "description": "Publish-ready music, emotional vocals, memorable melodies.", "generation_amount": 1, "required_credits": 12, "supported_control_types": [ "refer", "prompt", "soundtrack", "motif", "vocal", "instrumental", "remix" ], "show_free_to_use": true, "app_display_name": "V8", "min_tier": "basic" }, { "display_name": "O2", "model": "mureka-o2", "description": "All-in-one smart music model, professional results.", "generation_amount": 1, "required_credits": 20, "supported_control_types": [ "refer", "prompt", "soundtrack", "instrumental", "vocal" ], "show_free_to_use": true, "app_display_name": "O2", "min_tier": "basic" }, { "display_name": "V7.6", "model": "mureka-7.6", "description": "Pro music creation, finer prompt control.", "generation_amount": 1, "required_credits": 10, "supported_control_types": [ "refer", "prompt", "soundtrack", "motif", "vocal", "instrumental" ], "show_free_to_use": true, "app_display_name": "V7.6", "min_tier": "basic" }, { "display_name": "V7.5-all", "model": "mureka-7.5all", "description": "Easy music creation, clear vocal, quick mixing, entry-level.", "generation_amount": 1, "required_credits": 10, "supported_control_types": [ "refer", "prompt", "soundtrack", "motif", "vocal", "instrumental" ], "show_free_to_use": true, "app_display_name": "V7.5-all" } ], "default_model": { "display_name": "V9.5", "model": "mureka-9.5", "description": "Natural songwriting, authentic performances, fuller sound.", "generation_amount": 1, "required_credits": 12, "supported_control_types": [ "refer", "prompt", "soundtrack", "motif", "vocal", "instrumental", "remix" ], "show_free_to_use": true, "app_display_name": "V9.5", "min_tier": "basic", "free_trial_window_days": 7 } } } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **596** **596 Account Error** Returned when the account has an error state preventing API calls. ```json { "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required", "code": "REFRESH_FAILED" } ``` Possible error codes: - `ACCOUNT_ERROR` - Account has a blocking error - `REFRESH_FAILED` - Automatic token refresh failed - `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly - `SESSION_EXPIRED` - Session expired and no auto-refresh available - `COOKIE_EXPIRED` - Google cookie has expired To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts). ##### Model Your mureka.ai profile and plan, the remaining `credits`, and the models you can use with their credit costs. <details markdown="block" class="model-details"> <summary>The account's profile, plan and credits, field by field</summary> ```typescript { // TypeScript, all fields are optional user: { id: string user_id: number stage_name: string profile_image: string is_vip: boolean vip_level: number created_on: number sid: number register_ip: string vip_start: number vip_end: number vip_name: string vip_level_name: string vip_period_name: string } credits: number credits_silver?: number feed_list_count: number free_download_mp3_models?: string[] models?: { official_models: { display_name: string model: string description?: string generation_amount?: number required_credits: number supported_control_types: string[] show_free_to_use?: boolean app_display_name?: string min_tier?: string }[] default_model: { display_name: string model: string description?: string generation_amount?: number required_credits: number supported_control_types: string[] show_free_to_use?: boolean app_display_name?: string min_tier?: string } } } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/mureka/profile/?account=account" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const account = "Previously configured account"; const apiUrl = `https://api.useapi.net/v1/mureka/profile/?account=${account}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" account = "Previously configured account" apiUrl = f"https://api.useapi.net/v1/mureka/profile/?account={account}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-mureka-v1/get-mureka-speech-voices === Document URL: https://useapi.net/docs/api-mureka-v1/get-mureka-speech-voices --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> speech/voices description: "List TTS voices — Mureka's built-in voices, or your cloned ones with cloned=true — via GET speech/voices in the useapi.net Mureka API v1, with preview audio and pagination." parent: Mureka API nav_order: 2200 --- ## Retrieve speech voices August 18, 2025 (November 16, 2026) --- This endpoint lists the voices for speech generation: Mureka's built-in voices by default, or with `cloned=true` your custom cloned voices created via [POST /speech/voice](/docs/api-mureka-v1/post-mureka-speech-voice). One call returns one of the two lists. Use pagination with the `last_id` parameter and `more` field to browse through all available voices. Voices include preview audio for testing before use. > **https://api.useapi.net/v1/mureka/speech/voices/?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `last_id` is optional. Use it to retrieve the next page of data. Set its value to the `last_id` returned in the previous response. - `cloned` is optional. Set to `true` for your cloned voices. Omitted or `false` lists Mureka's built-in voices. Supported values: `true`, `false`. ##### Responses **200** **200 OK** ```json { "list": [ { "id": 12345678901234, "user_id": 23456789012345, "title": "Sarah", "cover": "https://static-cos.mureka.ai/cos-prod/res/cover/….png", "mp3_url": "https://static-cos.mureka.ai/cos-prod/tts-v2/….mp3", "language": "en", "created_at": 1755483687, "description": "Professional female voice", "duration_milliseconds": 12520, "source_type": 2, "machine_audit_state": 1 }, { "id": 34567890123456, "user_id": 23456789012345, "title": "Michael", "cover": "https://static-cos.mureka.ai/cos-prod/res/cover/….png", "mp3_url": "https://static-cos.mureka.ai/cos-prod/tts-v2/….mp3", "language": "en", "created_at": 1755483619, "description": "Deep male narrator", "duration_milliseconds": 13680, "source_type": 2, "machine_audit_state": 1 } ], "last_id": 1755483619964 } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **596** **596 Account Error** Returned when the account has an error state preventing API calls. ```json { "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required", "code": "REFRESH_FAILED" } ``` Possible error codes: - `ACCOUNT_ERROR` - Account has a blocking error - `REFRESH_FAILED` - Automatic token refresh failed - `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly - `SESSION_EXPIRED` - Session expired and no auto-refresh available - `COOKIE_EXPIRED` - Google cookie has expired To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts). ##### Model A page of built-in or cloned voices, each with its `id`, language and preview MP3, plus `last_id` and `more` for paging. <details markdown="block" class="model-details"> <summary>The list of speech voices, field by field</summary> ```typescript { // TypeScript, all fields are optional list: { id: number user_id: number title: string cover: string mp3_url: string language: string created_at: number description: string duration_milliseconds: number source_type?: number machine_audit_state: number }[] last_id: number more?: boolean } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/mureka/speech/voices/?cloned=true" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = "https://api.useapi.net/v1/mureka/speech/voices/?cloned=true"; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" apiUrl = "https://api.useapi.net/v1/mureka/speech/voices/?cloned=true" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-mureka-v1/get-mureka-speech === Document URL: https://useapi.net/docs/api-mureka-v1/get-mureka-speech --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> speech description: "Retrieve your Mureka speech generation history with audio URLs and metadata via GET speech in the useapi.net Mureka API v1 — paginated using last_id." parent: Mureka API nav_order: 2100 --- ## Retrieve generated speech August 18, 2025 (November 16, 2026) --- This endpoint retrieves a list of previously generated speech recordings from your Mureka account. Use pagination with the `last_id` parameter to browse through all your speech history. The `more` field indicates whether additional pages are available. Each response includes the generated audio URLs, titles, and metadata for easy playback and management. > **https://api.useapi.net/v1/mureka/speech/?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `last_id` is optional. Use it to retrieve the next page of data. Set its value to the `last_id` returned in the previous response. ##### Responses **200** **200 OK** ```json { "list": [ { "title": "Morning Conversation", "preview": "Good morning! How are you doing today? I hope you're having a wonderful start to your day.", "cover": "https://static-cos.mureka.ai/cos-prod/res/cover/….png", "mp3_url": "https://static-cos.mureka.ai/cos-prod/tts-v2/….mp3", "id": 23456789012345, "duration_milliseconds": 8500, "audio_quality": 2, "state": 3 }, { "title": "Evening Reflection", "preview": "As the day comes to an end, let's take a moment to reflect on all the good things that happened.", "cover": "https://static-cos.mureka.ai/cos-prod/res/cover/….png", "mp3_url": "https://static-cos.mureka.ai/cos-prod/tts-v2/….mp3", "id": 34567890123456, "duration_milliseconds": 12300, "audio_quality": 2, "state": 3 } ], "last_id": 1755483687, "more": true } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **596** **596 Account Error** Returned when the account has an error state preventing API calls. ```json { "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required", "code": "REFRESH_FAILED" } ``` Possible error codes: - `ACCOUNT_ERROR` - Account has a blocking error - `REFRESH_FAILED` - Automatic token refresh failed - `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly - `SESSION_EXPIRED` - Session expired and no auto-refresh available - `COOKIE_EXPIRED` - Google cookie has expired To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts). ##### Model A page of your speech recordings, each with its `id`, title and `mp3_url`, plus `last_id` and `more` for the next page. <details markdown="block" class="model-details"> <summary>The list of speech recordings, field by field</summary> ```typescript { // TypeScript, all fields are optional list: { title: string preview: string cover: string mp3_url: string id: number duration_milliseconds: number audio_quality: number state: number }[] last_id: number more?: boolean } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/mureka/speech/" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = "https://api.useapi.net/v1/mureka/speech/"; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" apiUrl = "https://api.useapi.net/v1/mureka/speech/" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-mureka-v1/mcp === Document URL: https://useapi.net/docs/api-mureka-v1/mcp --- layout: default title: MCP Server nav_icon: mcp seo_title: "Mureka MCP Server: Songs, Characters, Stems and Sheet Music" description: "Connect the Claude app, ChatGPT, Claude Code or any MCP client to the hosted useapi.net Mureka MCP server: 40 tools for songs, characters, remix, stems and speech." parent: Mureka API nav_order: 50 permalink: /docs/api-mureka-v1/mcp --- ## Mureka MCP Server October 16, 2026 (November 1, 2026) --- The useapi.net Mureka MCP server lets an AI assistant such as the Claude app, ChatGPT, Claude Code, Cursor or VS Code Copilot make music and speech with [Mureka](https://www.mureka.ai) on your own Mureka accounts. It is a hosted [Model Context Protocol](https://modelcontextprotocol.io) server with nothing to install: point your client at the URL below and add your useapi.net API token. It covers the whole [Mureka API](/docs/api-mureka-v1): songs from a prompt or your lyrics, your own voice as a reusable singer, edits and remixes, stems with MIDI and DAW sessions, sheet music, and speech with cloned voices. Every tool calls the same REST API, so accounts, limits and errors behave exactly as documented there. **Is there a Mureka MCP server?** useapi.net hosts a third-party Mureka MCP server at `https://api.useapi.net/v1/mureka/mcp` with 40 tools for songs, characters, remixes, stems, sheet music and speech, and it runs on your Mureka web plan, nothing to install. Prefer REST? Tutorial: [How to Generate AI Music with the Mureka API](/docs/articles/mureka-bash) · Code: [github.com/useapi/mureka-api](https://github.com/useapi/mureka-api) See all useapi.net MCP servers on [Model Matrix & MCP](/model-matrix#mcp-servers). ## Endpoint and authorization ``` https://api.useapi.net/v1/mureka/mcp ``` - Transport: Streamable HTTP. - Listed in the [official MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers/net.useapi%2Fmureka/versions/latest) as `net.useapi/mureka`, so MCP clients and directories that read the registry can find it by that name. - Authorization: your useapi.net API token in the `Authorization: Bearer …` header, see [Setup useapi.net](/docs/start-here/setup-useapi). The Claude app and ChatGPT sign in with OAuth instead, see [Use it in the Claude app or ChatGPT](#use-it-in-the-claude-app-or-chatgpt). - You need at least one Mureka account added with [Setup Mureka](/docs/start-here/setup-mureka). Adding and removing accounts is not available over MCP: use [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts). ## Setup Replace `YOUR_API_TOKEN` with your useapi.net API token. ### Claude Code ```bash claude mcp add --transport http useapi-mureka https://api.useapi.net/v1/mureka/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` ### Cursor In `~/.cursor/mcp.json`: ```json { "mcpServers": { "useapi-mureka": { "url": "https://api.useapi.net/v1/mureka/mcp", "headers": { "Authorization": "Bearer YOUR_API_TOKEN" } } } } ``` ### VS Code In `.vscode/mcp.json`: ```json { "servers": { "useapi-mureka": { "type": "http", "url": "https://api.useapi.net/v1/mureka/mcp", "headers": { "Authorization": "Bearer YOUR_API_TOKEN" } } } } ``` ### Windsurf and other clients Any client that supports remote MCP servers over HTTP with custom headers works. The usual JSON shape: ```json { "mcpServers": { "useapi-mureka": { "serverUrl": "https://api.useapi.net/v1/mureka/mcp", "headers": { "Authorization": "Bearer YOUR_API_TOKEN" } } } } ``` Some clients name the address field `url` instead of `serverUrl`. ### Test it with curl ```bash curl -s https://api.useapi.net/v1/mureka/mcp \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}' curl -s https://api.useapi.net/v1/mureka/mcp \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' ``` The first call answers with the server's name `useapi-mureka` and its instructions for the assistant, the second with the 40 tools. ## Use it in the Claude app or ChatGPT The Claude app ([claude.ai](https://claude.ai) and Claude Desktop) and [ChatGPT](https://chatgpt.com) can add this server as a custom connector. They sign in with OAuth: you give the app the URL, it opens a useapi.net page, and you paste your useapi.net API token there once. Both work on their Free plans. The API-token setups above for Claude Code, Cursor, VS Code and other clients keep working as before. ``` ``` ### Claude app 1. Open Settings → Connectors and click Add custom connector. 2. Enter a name, for example `useapi `, and the URL above, then click Add. 3. Click Connect. Claude opens the useapi.net sign-in page. 4. Paste your useapi.net API token and click Allow. Claude asks before each tool call unless you choose Always allow. The Free plan allows one custom connector. ### ChatGPT 1. Open Plugins, click Add and choose Add custom MCP server. 2. Enter a name and the URL above, and set Authentication to OAuth. 3. Tick ChatGPT's "I understand and want to continue" box, then click Create as a plugin. 4. Click Connect. ChatGPT opens the useapi.net sign-in page. 5. Paste your useapi.net API token and click Allow. ChatGPT asks you to confirm each tool call that creates or changes something. The Free plan works without developer mode (as of October 25, 2026). ### How the sign-in works - Your API token is in your welcome email, see [Setup useapi.net](/docs/start-here/setup-useapi). The useapi.net page links there too. - Each connection is for one MCP server. Connect each server you want to use on its own. - The app gets an access token that lasts 1 hour and renews it on its own. A connection you don't use for 90 days lapses, and you connect again. - [Resetting your API token](/docs/account-management/post-account-token-reset) disconnects every app connected with it. - - Results come back as public links, so they open right in the app. ## Tools Songs carry their account in the `song_id`, so an edit, remix, stem extraction or score runs on the account that holds the song. Other tools take an optional `account`, required only when you have several accounts. ### Accounts | Tool | What it does | Main parameters | |---|---|---| | `mureka_list_accounts` | Lists your Mureka accounts with their sign-in mode and health. | | | `mureka_get_account` | Reads one account: sign-in mode, session expiry and any error. | `account` | | `mureka_get_profile` | Returns the account's Mureka plan and Gold balance. | `account` | ### Songs | Tool | What it does | Main parameters | |---|---|---| | `mureka_create_song` | Makes two songs from a description; Mureka writes the lyrics. | `prompt`, `model` | | `mureka_create_song_with_lyrics` | Makes two songs from your lyrics, with a style and optionally a voice, a character, a reference track or a melody. | `lyrics`, `desc`, `vocal_id`, `character_id`, `ref_id`, `motif_id`, `title`, `vocal_gender`, `model` | | `mureka_create_instrumental` | Makes two instrumentals from a prompt or a reference track. | `prompt` or `ref_id`, `title`, `model` | | `mureka_write_lyrics` | Writes lyrics from an idea, without making a song. | `prompt` | The parameters match [POST /music/create](/docs/api-mureka-v1/post-mureka-music-create), [POST /music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced) and [POST /music/create-instrumental](/docs/api-mureka-v1/post-mureka-music-create-instrumental). ### Edits and remix | Tool | What it does | Main parameters | |---|---|---| | `mureka_extend_song` | Continues a song from its end with new lyrics. | `song_id`, `lyrics` | | `mureka_edit_section` | Re-sings one range of a song with new lyrics and keeps the rest. Returns one song. | `song_id`, `start_milliseconds`, `end_milliseconds`, `lyrics`, `keep_melody` | | `mureka_remix_song` | Re-records a song, with vocals or instrumental, in a new style. | `song_id`, `desc`, `lyrics`, `title`, `model` | ### Library | Tool | What it does | Main parameters | |---|---|---| | `mureka_list_songs` | Lists the songs on an account, newest first. | `account`, `last_id` | | `mureka_get_song` | Reads one song with its lyrics, style and mp3 link. | `song_id` | | `mureka_delete_song` | Deletes a song. | `song_id` | | `mureka_download_song` | Returns the basic stems package or the license certificate of a song. | `song_id`, `type` | | `mureka_create_video` | Makes a lyrics video (mp4) for a song. Mureka does not make it for V9.5 songs; songs made on V9, V8, O2, V7.6 or V7.5-all work. | `song_id` | ### Stems and sheet music | Tool | What it does | Main parameters | |---|---|---| | `mureka_extract_stems` | Splits a song into up to 12 stems plus MIDI (100 Gold), or vocals and instrumental (20 Gold). | `song_id`, `all_stems` | | `mureka_download_stems` | From a finished extraction: one stem with its MIDI, ZIPs of everything, or a session for Ableton Live, Logic Pro, Pro Tools or Cubase. | `stems_id`, `stem_name`, `daw` | | `mureka_get_sheet_music` | Transcribes a song, a YouTube link or an uploaded MP3 into MusicXML and PDF sheet music. 10 Gold. | `song_id` or `url`, `title` | ### Characters | Tool | What it does | Main parameters | |---|---|---| | `mureka_create_character` | Turns a voice from `mureka_upload_vocal`, or one of your songs, into a reusable singer. Free. | `name`, `vocal_id` or `song_id`, `bio`, `tags`, `desc`, `private` | | `mureka_list_characters` | Lists your characters. | `account`, `last_id` | | `mureka_set_character_private` | Hides a character from mureka.ai or publishes it. | `character_id`, `private` | | `mureka_delete_character` | Deletes a character. Songs made with it are kept. | `character_id` | ### Voices, references and uploads | Tool | What it does | Main parameters | |---|---|---| | `mureka_list_styles` | Lists the genre and mood tags Mureka understands. | `account` | | `mureka_list_vocals` | Lists Mureka's singing voices, or with `mine: true` the ones you uploaded. | `mine`, `last_id` | | `mureka_list_references` | Lists Mureka's 30-second reference tracks by mood or genre. | `mood`, `genre`, `last_id` | | `mureka_list_files` | Lists the reference tracks you uploaded. | `last_id` | | `mureka_import_youtube` | Fetches the audio of a YouTube link into Mureka storage. | `url` | | `mureka_upload_reference` | Uploads an MP3 as a reference track. | `url` or `contentBase64`, `title`, `mood`, `genre` | | `mureka_upload_motif` | Uploads an MP3 melody idea. | `url` or `contentBase64` | | `mureka_upload_vocal` | Uploads an MP3 of a singing voice, about 30 seconds of clear vocals. | `url` or `contentBase64`, `title` | | `mureka_delete_file` | Deletes an uploaded reference track. | `id` | | `mureka_delete_vocal` | Deletes an uploaded voice. | `id` | Uploads take MP3 files up to 40 MB, from a public https URL or sent as `contentBase64`. ### Speech | Tool | What it does | Main parameters | |---|---|---| | `mureka_create_speech` | Text to speech with one voice, or a conversation between several voices. | `text` + `voice_id`, or `conversation`, `title` | | `mureka_list_speech` | Lists the speech made on an account. | `last_id` | | `mureka_delete_speech` | Deletes a speech item. | `id` | | `mureka_list_voices` | Lists Mureka's speech voices, or with `cloned: true` the ones you cloned. | `cloned`, `last_id` | | `mureka_clone_voice` | Clones a speaking voice from an MP3 sample. | `url` or `contentBase64`, `title`, `desc`, `lang` | | `mureka_delete_voice` | Deletes a cloned voice. | `voice_id` | ### Jobs | Tool | What it does | Main parameters | |---|---|---| | `mureka_get_job` | Reads a song, edit, remix, stems or speech job, and with `wait: true` waits for it to finish. | `jobid`, `wait` | | `mureka_list_jobs` | Lists the jobs running now on each account. | | The full input schema of every tool comes from `tools/list`. ## Long-running work MCP clients usually give up on a tool call after about a minute, so a tool waits up to about 50 seconds: - A song, edit or remix usually takes 45 to 90 seconds. If it isn't done in time, the tool returns the `jobid`, and `mureka_get_job` with `wait: true` picks it up. Ask the assistant to keep checking until it is done. - A stem extraction takes about a minute, and speech 20 to 90 seconds, the same way. - Sheet music answers in 5 to 20 seconds, plus up to 15 seconds to fetch a YouTube link. Clients that ask for progress notifications get one about every 10 seconds while a tool waits. Each song comes back with its `song_id` and a public `mp3` link. ## Example prompts - "Write lyrics for a song about a lighthouse keeper, then make it as a slow folk ballad on V9.5." - "Upload this voice clip as a singer called Nova, keep it private, and have her sing my lyrics as synthwave." - "Remix my last song as drum and bass." - "Split that song into vocals and instrumental and give me a Logic Pro session." - "Turn this YouTube video into sheet music." - "Read this paragraph aloud with a warm British voice." - "How much Mureka Gold is left on my account?" ## Limits and notes - The tools use your Mureka accounts and the same rules as the REST API. Most actions use the account's Mureka Gold: see the pricing on the [Mureka API](/docs/api-mureka-v1) page. - A client may send up to 20 JSON-RPC requests in one batch. - If the client sends an `MCP-Protocol-Version` header, it must be one of the supported versions: `2025-06-18`, `2025-03-26` or `2024-11-05`. - Tool calls show in your [usage stats](/docs/account-management/get-account-stats) (`bot=mureka`) through the REST call each tool makes, the same rows a direct API request writes. === URL: https://useapi.net/docs/api-mureka-v1/post-mureka-accounts === Document URL: https://useapi.net/docs/api-mureka-v1/post-mureka-accounts --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> accounts description: "Configure a Mureka account for the useapi.net Mureka API v1 — the recommended email + password method (the API re-logs in for you), or a session token + refresh token — via POST accounts." parent: Mureka API nav_order: 299 --- ## Configure Mureka API account January 19, 2026 (November 16, 2026) --- Configure a Mureka account for API access. There are **two ways to connect**, differing in what happens when Mureka ends the session: - **Email + password** *(recommended).* Give the API a dedicated Mureka account's `email` + `password`. When the session is revoked, the API **logs back in automatically** — the account never needs manual re-linking. - **Session token.** Give the API the `token` (`access_token`) + `refresh_token` copied from your browser after signing in. The API auto-refreshes them, but once fully revoked or expired the account must be **re-linked by hand**. See [Setup Mureka](/docs/start-here/setup-mureka) for step-by-step instructions on both. > **https://api.useapi.net/v1/mureka/accounts** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body Send **one** of the two bodies below. **Option 1 — email + password** *(recommended)* ```json { "email": "you@example.com", "password": "your-mureka-password" } ``` - `email` — the dedicated Mureka account's email address. - `password` — that account's password. It's stored so the API can re-login on your behalf whenever Mureka ends the session, and is **never returned** (masked in every response). Create the account through the guided [Connect Mureka with email + password](/assets/setup-browser/mureka-login-email) page. Accounts added this way report **`"authMode": "email"`**. **Option 2 — token + refresh_token** ```json { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...secured...E7jlw8", "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...secured...hNvmuU" } ``` - `token` — **required** for this option. The `access_token` from the [Mureka.ai login response](/docs/start-here/setup-mureka) (a JWT starting with `eyJ…`, ~390 characters). - `refresh_token` — *optional but recommended*. The `refresh_token` from the same login response (a JWT starting with `eyJ…`, ~350 characters). With it, the API keeps your session alive automatically and the account reports **`"authMode": "token"`**. Without it, the account works for about 30 days (until the token expires) and then must be re-added — no auto-refresh, and no `authMode` in the response. > When you add an account, the API validates it once — an email + password login (Option 1), or a token refresh (Option 2). This confirms the credentials work, takes the session over from your browser, and stores the API's own token pair. It adds a few seconds to the request. If it fails, the account is **not** saved and the error explains why. ##### Responses **200** **200 OK** Account configured successfully with browserless auto-refresh enabled. Secret values (token, refresh_token, password) are masked in the response. Option 1 (email + password) → `authMode: "email"`: ```json { "123456789012345": { "account": "123456789012345", "token": "eyJ…secured…", "refresh_token": "eyJ…secured…", "password": "…secured…", "authMode": "email", "token_expires": 1786579200000, "refresh_expires": 1789171200000, "updated": 1783987200000, "email": "you@example.com", "hasAutoRefresh": true, "tokenIssuedDaysAgo": 0, "updatedUTC": "2026-07-14T00:00:00.000Z", "tokenExpiresUTC": "2026-08-13T00:00:00.000Z", "refreshExpiresUTC": "2026-09-12T00:00:00.000Z" } } ``` Option 2 (token + refresh_token) → `authMode: "token"` (identical shape, no `password`). **400** **400 Bad Request** Option 1 — the email or password was rejected (finish Mureka's email verification first if you just set the password): ```json { "error": "Mureka login failed: incorrect email or password (9022)", "code": 400 } ``` Option 2 — the captured refresh token was rejected — re-capture a fresh one (and if the account is signed in on another browser or device, sign out there first): ```json { "error": "Could not establish a refreshable Mureka session: Mureka refresh failed (code=2, msg=invalid refresh token). Re-capture a fresh session and try again — if this Mureka account is signed in on another browser or device, sign out of it there first.", "code": 400 } ``` **429** **429 Too Many Requests** The onboarding login/refresh was rate-limited by Mureka. Wait ~20 seconds and try again. ```json { "error": "Could not log in to Mureka right now — Mureka login rate-limited (9008) — retry shortly. Wait ~20 seconds and try again.", "code": 429 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model The saved account, keyed by its id, with masked secrets, how it signs in (`authMode`) and its token expiry dates. <details markdown="block" class="model-details"> <summary>The saved account configuration, field by field</summary> ```typescript { // TypeScript, all fields are optional [account: string]: { account: string token: string // masked refresh_token: string // masked password?: string // masked — present only for email + password (authMode "email") accounts authMode: "email" | "token" // "email" = email + password (the API re-logs in automatically); "token" = session/refresh-token only (re-link on expiry) token_expires: number // access-token expiry, epoch ms (~30 days out) refresh_expires: number // refresh-token expiry, epoch ms (~60 days out) updated: number email?: string hasAutoRefresh: boolean tokenIssuedDaysAgo: number updatedUTC: string tokenExpiresUTC: string refreshExpiresUTC: string } error: string code: number } ``` </details> ##### Examples Examples use the recommended **email + password** body. For the session-token method, replace the body with `{ "token": "eyJ…", "refresh_token": "eyJ…" }`. **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST https://api.useapi.net/v1/mureka/accounts \ -d '{"email": "you@example.com", "password": "your-mureka-password"}' ``` **JavaScript** ``` javascript const apiUrl = 'https://api.useapi.net/v1/mureka/accounts'; const api_token = "API token"; const email = "you@example.com"; const password = "your-mureka-password"; const response = await fetch(apiUrl, { method: 'POST', headers: { 'Authorization': `Bearer ${api_token}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ email, password }) }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests apiUrl = "https://api.useapi.net/v1/mureka/accounts" api_token = "API token" email = "you@example.com" password = "your-mureka-password" headers = { "Content-Type": "application/json", "Authorization": f"Bearer {api_token}" } body = { "email": email, "password": password } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-mureka-v1/post-mureka-files-motif === Document URL: https://useapi.net/docs/api-mureka-v1/post-mureka-files-motif --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> files/motif description: "Upload an mp3 melody (motif) file up to 5 GB via POST files/motif in the useapi.net Mureka API v1 — reference it as motif_id in advanced music creation." parent: Mureka API nav_order: 1900 --- ## Upload mp3 melody (motif) track December 13, 2024 (November 16, 2026) --- Upload mp3 audio file up to 5GB in size. Use `id` value to reference uploaded melody when using the parameter `motif_id` of [POST /music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced). Uploaded file will not be visible for other users of the Mureka.ai [POST raw content using Make.com and similar nocode tools.](/docs/questions-and-answers#how-post-raw-content-to-runwaymlassets-and-minimaxfiles-using-makecom-and-similar-nocode-tools) > **https://api.useapi.net/v1/mureka/files/motif/?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: audio/mpeg ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. - `Content-Type` is **required**, only `audio/mpeg ` supported. ##### Query Parameters - `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. ##### Responses **200** **200 OK** The response contains an `id` that you can use to reference the uploaded melody when using the parameter `motif_id` of [POST /music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced). ```json { "id": "user:777-mureka:987654321-file:123456789", "url": "https://<song download url>.mp3", "duration_milliseconds": 50000 } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **422** **422 Unprocessable Content** Mureka refused the uploaded file for copyright infringement (Mureka code 6388). Upload a different file. ```json { "error": "Mureka refused this content for copyright infringement (6388). Use a different file or input." } ``` **596** **596 Account Error** Returned when the account has an error state preventing API calls. ```json { "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required", "code": "REFRESH_FAILED" } ``` Possible error codes: - `ACCOUNT_ERROR` - Account has a blocking error - `REFRESH_FAILED` - Automatic token refresh failed - `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly - `SESSION_EXPIRED` - Session expired and no auto-refresh available - `COOKIE_EXPIRED` - Google cookie has expired To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts). ##### Model The uploaded melody's `id`, to pass as `motif_id` to [POST /music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced), with its URL and length. <details markdown="block" class="model-details"> <summary>The uploaded melody, field by field</summary> ```typescript { // TypeScript, all fields are optional id: string url: string duration_milliseconds: number } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/mureka/files/motif/?account=<account>" \ -H "Authorization: Bearer …" \ -H "Content-Type: audio/mpeg" \ --data-binary /path/to/your/audio.mp3 ``` **JavaScript** ``` javascript const token = "API token"; const account = "Previously configured account account"; const apiUrl = `https://api.useapi.net/v1/mureka/files/motif/?account=${account}`; let blob; /* // Example 1: Fetch audio from URL const url = "https://upload.wikimedia.org/wikipedia/commons/7/7d/sound.mp3"; const response = await fetch(url); blob = await responseImage.blob(); */ /* // Example 2: Load audio from local file (Blob) const fsp = require('fs').promises; const fileName = "./music.mp3"; blob = new Blob([await fsp.readFile(fileName)]); */ /* // Example 3: Load from input file html element // <input id="music-file" type="file"> const musicFile = document.getElementById(`music-file`); if (musicFile.files[0]) blob = musicFile.files[0]); */ const response = await fetch(apiUrl, { method: "POST" headers: { "Authorization": `Bearer ${token}`, }, body: blob }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" account = "Previously configured account account" apiUrl = f"https://api.useapi.net/v1/mureka/files/motif/?account={account}" headers = { 'Authorization': f'Bearer {token}', 'Content-Type': 'audio/mpeg' } # # Example 1: Fetch audio from URL # url = "https://upload.wikimedia.org/wikipedia/commons/7/7d/audio.mp3" # response_audio = requests.get(url) # file_content = response_audio.content # # Example 2: Load audio from local file # audio_file_path = "./audio.mp3" # with open(audio_file_path, 'rb') as audio_file: # file_content = audio_file.read() response = requests.post(api_url, headers=headers, data=file_content) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-mureka-v1/post-mureka-files-vocal === Document URL: https://useapi.net/docs/api-mureka-v1/post-mureka-files-vocal --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> files/vocal description: "Upload a custom mp3 vocal sample up to 5 GB via POST files/vocal in the useapi.net Mureka API v1 — reference it as vocal_id in advanced music creation." parent: Mureka API nav_order: 1950 --- ## Upload mp3 vocal January 15, 2025 (November 16, 2026) --- Upload mp3 audio file up to 5GB in size. Use `id` value to reference uploaded vocal when using the parameter `vocal_id` of [POST /music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced). Uploaded file will not be visible for other users of the Mureka.ai [POST raw content using Make.com and similar nocode tools.](/docs/questions-and-answers#how-post-raw-content-to-runwaymlassets-and-minimaxfiles-using-makecom-and-similar-nocode-tools) > **https://api.useapi.net/v1/mureka/files/vocal/?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: audio/mpeg ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. - `Content-Type` is **required**, only `audio/mpeg ` supported. ##### Query Parameters - `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `title` is **required**. Provide name for your vocal. ##### Responses **200** **200 OK** The response contains an `id` that you can use to reference the uploaded melody when using the parameter `vocal_id` of [POST /music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced). ```json { "id": 1234567890, "title": "vocal name", "url": "https://<vocal download url>.mp3", "duration_milliseconds": 50000 } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **422** **422 Unprocessable Content** Mureka refused the uploaded file for copyright infringement (Mureka code 6388). Upload a different file. ```json { "error": "Mureka refused this content for copyright infringement (6388). Use a different file or input." } ``` **596** **596 Account Error** Returned when the account has an error state preventing API calls. ```json { "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required", "code": "REFRESH_FAILED" } ``` Possible error codes: - `ACCOUNT_ERROR` - Account has a blocking error - `REFRESH_FAILED` - Automatic token refresh failed - `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly - `SESSION_EXPIRED` - Session expired and no auto-refresh available - `COOKIE_EXPIRED` - Google cookie has expired To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts). ##### Model The uploaded vocal's `id`, to pass as `vocal_id` to [POST /music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced), with its title, URL and length. <details markdown="block" class="model-details"> <summary>The uploaded vocal, field by field</summary> ```typescript { // TypeScript, all fields are optional id: number title: string url: string duration_milliseconds: number } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/mureka/files/vocal/?account=<account>" \ -H "Authorization: Bearer …" \ -H "Content-Type: audio/mpeg" \ --data-binary /path/to/your/audio.mp3 ``` **JavaScript** ``` javascript const token = "API token"; const account = "Previously configured account account"; const apiUrl = `https://api.useapi.net/v1/mureka/files/vocal/?account=${account}`; let blob; /* // Example 1: Fetch audio from URL const url = "https://upload.wikimedia.org/wikipedia/commons/7/7d/sound.mp3"; const response = await fetch(url); blob = await responseImage.blob(); */ /* // Example 2: Load audio from local file (Blob) const fsp = require('fs').promises; const fileName = "./music.mp3"; blob = new Blob([await fsp.readFile(fileName)]); */ /* // Example 3: Load from input file html element // <input id="music-file" type="file"> const musicFile = document.getElementById(`music-file`); if (musicFile.files[0]) blob = musicFile.files[0]); */ const response = await fetch(apiUrl, { method: "POST" headers: { "Authorization": `Bearer ${token}`, }, body: blob }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" account = "Previously configured account account" apiUrl = f"https://api.useapi.net/v1/mureka/files/vocal/?account={account}" headers = { 'Authorization': f'Bearer {token}', 'Content-Type': 'audio/mpeg' } # # Example 1: Fetch audio from URL # url = "https://upload.wikimedia.org/wikipedia/commons/7/7d/audio.mp3" # response_audio = requests.get(url) # file_content = response_audio.content # # Example 2: Load audio from local file # audio_file_path = "./audio.mp3" # with open(audio_file_path, 'rb') as audio_file: # file_content = audio_file.read() response = requests.post(api_url, headers=headers, data=file_content) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-mureka-v1/post-mureka-files === Document URL: https://useapi.net/docs/api-mureka-v1/post-mureka-files --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> files description: "Upload an mp3 audio track to your Mureka reference collection via POST files in the useapi.net Mureka API v1 — uploaded tracks are visible to all Mureka users." parent: Mureka API nav_order: 1800 --- ## Upload mp3 audio track to your music collection December 13, 2024 (November 16, 2026) --- Upload mp3 audio file up to 5GB in size. Files uploaded using this endpoint will be visible to all users of Mureka.ai website. To retrieve a full list of all your uploaded tracks use [GET /files](/docs/api-mureka-v1/get-mureka-files). [POST raw content using Make.com and similar nocode tools.](/docs/questions-and-answers#how-post-raw-content-to-runwaymlassets-and-minimaxfiles-using-makecom-and-similar-nocode-tools) > **https://api.useapi.net/v1/mureka/files/?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: audio/mpeg ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. - `Content-Type` is **required**, only `audio/mpeg ` supported. ##### Query Parameters - `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `title` is **required**. - `genre` is **required**. Provide the genre of your track. See supported values using [GET /music/moods-and-genres](/docs/api-mureka-v1/get-mureka-music-moods-and-genres). - `mood` is **required**. Provide the mood of your track. See supported values using [GET /music/moods-and-genres](/docs/api-mureka-v1/get-mureka-music-moods-and-genres). - `url` is optional. Provide the original YouTube url if applicable. ##### Responses **200** **200 OK** The response contains an `id` that you can use to reference the uploaded audio file when using the parameter `ref_id` of [POST /music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced). ```json { "id": 1122334455, "url": "https://<song download url>.mp3", "duration_milliseconds": 30000, "mood": "relaxed", "title": "<song title>", "genre": "afrobeat" } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **422** **422 Unprocessable Content** Mureka refused the uploaded file for copyright infringement (Mureka code 6388). Upload a different file. ```json { "error": "Mureka refused this content for copyright infringement (6388). Use a different file or input." } ``` **596** **596 Account Error** Returned when the account has an error state preventing API calls. ```json { "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required", "code": "REFRESH_FAILED" } ``` Possible error codes: - `ACCOUNT_ERROR` - Account has a blocking error - `REFRESH_FAILED` - Automatic token refresh failed - `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly - `SESSION_EXPIRED` - Session expired and no auto-refresh available - `COOKIE_EXPIRED` - Google cookie has expired To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts). ##### Model The uploaded track, with its `id`, URL, length, title, mood and genre. <details markdown="block" class="model-details"> <summary>The uploaded track, field by field</summary> ```typescript { // TypeScript, all fields are optional id: number url: string duration_milliseconds: number mood: string title: string genre: string } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/mureka/files/?account=<account>&title=<title>&genre=<genre>&mood=<mood>" \ -H "Authorization: Bearer …" \ -H "Content-Type: audio/mpeg" \ --data-binary /path/to/your/audio.mp3 ``` **JavaScript** ``` javascript const token = "API token"; const account = "Previously configured account account"; const title = "song title"; const mood = "song mood"; const genre = "song genre"; const apiUrl = `https://api.useapi.net/v1/mureka/files/?account=${account}&title=${title}&genre=${genre}&mood=${mood}`; let blob; /* // Example 1: Fetch audio from URL const url = "https://upload.wikimedia.org/wikipedia/commons/7/7d/sound.mp3"; const response = await fetch(url); blob = await responseImage.blob(); */ /* // Example 2: Load audio from local file (Blob) const fsp = require('fs').promises; const fileName = "./music.mp3"; blob = new Blob([await fsp.readFile(fileName)]); */ /* // Example 3: Load from input file html element // <input id="music-file" type="file"> const musicFile = document.getElementById(`music-file`); if (musicFile.files[0]) blob = musicFile.files[0]); */ const response = await fetch(apiUrl, { method: "POST" headers: { "Authorization": `Bearer ${token}`, }, body: blob }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" account = "Previously configured account account" title = "song title" mood = "song mood" genre = "song genre" apiUrl = f"https://api.useapi.net/v1/mureka/files/?account={account}&title={title}&genre={genre}&mood={mood}" headers = { 'Authorization': f'Bearer {token}', 'Content-Type': 'audio/mpeg' } # # Example 1: Fetch audio from URL # url = "https://upload.wikimedia.org/wikipedia/commons/7/7d/audio.mp3" # response_audio = requests.get(url) # file_content = response_audio.content # # Example 2: Load audio from local file # audio_file_path = "./audio.mp3" # with open(audio_file_path, 'rb') as audio_file: # file_content = audio_file.read() response = requests.post(api_url, headers=headers, data=file_content) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-mureka-v1/post-mureka-music-characters-publish === Document URL: https://useapi.net/docs/api-mureka-v1/post-mureka-music-characters-publish --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> music/characters-publish description: "Make a Mureka character private or publish it on mureka.ai again via POST music/characters-publish in the useapi.net Mureka API v1." parent: Mureka API nav_order: 2020 --- ## Publish or hide a character October 16, 2026 --- > **https://api.useapi.net/v1/mureka/music/characters-publish** Make a character private, so only you can see it, or publish it on [mureka.ai](https://www.mureka.ai) again. A private character works the same in [POST /music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced). New characters from [POST /music/characters](/docs/api-mureka-v1/post-mureka-music-characters) are public unless created with `private: true`. ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "account": "12345678901234", "character_id": 166751507709953, "private": true } ``` - `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) is configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `character_id` is **required**, the `id` from [GET /music/characters](/docs/api-mureka-v1/get-mureka-music-characters). - `private` is optional (default: `false`). `true` makes the character private. `false` publishes it on mureka.ai. ##### Responses **200** **200 OK** ```json { "character_id": 166751507709953, "private": true } ``` **400** **400 Bad Request** ```json { "error": "Parameter character_id is required", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Wrong username/password combination.", "code": 401 } ``` **596** **596 Account Error** Returned when the account has an error state preventing API calls. ```json { "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required", "code": "REFRESH_FAILED" } ``` Possible error codes: - `ACCOUNT_ERROR` - Account has a blocking error - `REFRESH_FAILED` - Automatic token refresh failed - `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly - `SESSION_EXPIRED` - Session expired and no auto-refresh available - `COOKIE_EXPIRED` - Google cookie has expired To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts). ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST https://api.useapi.net/v1/mureka/music/characters-publish \ -d '{"account": "…", "character_id": …, "private": true}' ``` **JavaScript** ``` javascript const account = "12345678901234"; const character_id = 166751507709953; const apiUrl = `https://api.useapi.net/v1/mureka/music/characters-publish`; const api_token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${api_token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ account, character_id, private: true }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests apiUrl = f"https://api.useapi.net/v1/mureka/music/characters-publish" api_token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {api_token}" } body = { "account": "12345678901234", "character_id": 166751507709953, "private": True } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-mureka-v1/post-mureka-music-characters === Document URL: https://useapi.net/docs/api-mureka-v1/post-mureka-music-characters --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> music/characters description: "Create a reusable Mureka singer from your own voice clip or an existing song via POST music/characters in the useapi.net Mureka API v1, then sing any lyrics in any style with it." parent: Mureka API nav_order: 2010 --- ## Create a character October 16, 2026 (November 16, 2026) --- > **https://api.useapi.net/v1/mureka/music/characters** Create a character, the same as Create Character on [mureka.ai](https://www.mureka.ai). A character is a reusable singer: a voice plus a default song description. Pass its `id` as `character_id` to [POST /music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced), together with your `lyrics` and a `desc` style, and the song is sung in that voice. Build a character from either: - your own voice clip, uploaded with [POST /files/vocal](/docs/api-mureka-v1/post-mureka-files-vocal) (about 30 seconds of clear singing works best), or - a song you generated, by its `song_id`. Creating a character costs no Gold and takes under a second. The character is ready to use right away. It needs a paid Mureka plan. On a Free account the call returns `403 low vip level (6335)`. Characters are public on mureka.ai unless you create them with `private: true`. You can change that later with [POST /music/characters-publish](/docs/api-mureka-v1/post-mureka-music-characters-publish). List your characters with [GET /music/characters](/docs/api-mureka-v1/get-mureka-music-characters) and delete them with [DELETE /music/characters](/docs/api-mureka-v1/del-mureka-music-characters). You can also use a voice without creating a character: [POST /music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced) accepts `vocal_id` together with `desc`. ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "account": "12345678901234", "vocal_id": 166746659094530, "name": "Scarlett", "bio": "A clear, articulate mid-range female voice.", "tags": ["Female", "Powerful"], "desc": "An intimate mid-tempo acoustic pop song with soft piano and a clear female lead vocal." } ``` - `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) is configured or when `song_id` is provided. However, if you have multiple accounts configured and `song_id` is not provided, this parameter becomes **required**. - `vocal_id` is optional, the `id` returned by [POST /files/vocal](/docs/api-mureka-v1/post-mureka-files-vocal). - `song_id` is optional, a song you generated, as returned by [GET /music](/docs/api-mureka-v1/get-mureka-music) or any create endpoint. The song's own account creates the character. Specify `vocal_id` or `song_id`, but not both. - `name` is **required**. Maximum length: 50 characters. - `bio` is optional, a short description of the voice. Maximum length: 1000 characters. - `tags` is optional, an array of strings or one comma-separated string, up to 10 tags. mureka.ai offers `Female`, `Male`, `Warm`, `Airy`, `Bright`, `Smoky`, `Soft`, `Powerful`, `Smooth`, `Whispery`. - `desc` is optional, the character's default song description, which mureka.ai shows with the character. Maximum length: 1000 characters. - `private` is optional (default: `false`). `true` keeps the character visible only to you. Otherwise it is published on mureka.ai. ##### Responses **200** **200 OK** Use `id` as `character_id`. A private character has no `is_published` field. ```json { "id": 166751507709953, "name": "Scarlett", "bio": "A clear, articulate mid-range female voice.", "tags": [ "Female", "Powerful" ], "avatar": "https://static-cos.mureka.ai/cos-prod/mureka/static/img/<id>.jpg", "is_published": true, "user_id": 12345678901234, "published_at": 1792191715, "created_at": 1792191715, "asset_id": 166751507578881, "showcase_edit_range": {}, "song_description": "An intimate mid-tempo acoustic pop song with soft piano and a clear female lead vocal." } ``` **400** **400 Bad Request** ```json { "error": "Please specify vocal_id or song_id but not both", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Wrong username/password combination.", "code": 401 } ``` **403** **403 Forbidden** The account's Mureka plan does not include characters. Free accounts always get this (tested November 2026). Pro accounts may get it too: Mureka rolls characters out to Pro gradually, and a Pro account outside that rollout gets the same answer. ```json { "error": "low vip level (6335)" } ``` **596** **596 Account Error** Returned when the account has an error state preventing API calls. ```json { "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required", "code": "REFRESH_FAILED" } ``` Possible error codes: - `ACCOUNT_ERROR` - Account has a blocking error - `REFRESH_FAILED` - Automatic token refresh failed - `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly - `SESSION_EXPIRED` - Session expired and no auto-refresh available - `COOKIE_EXPIRED` - Google cookie has expired To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts). ##### Model The new character, with the `id` to pass as `character_id` to [POST /music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced), its name and tags. <details markdown="block" class="model-details"> <summary>The new character, field by field</summary> ```typescript { id: number // character_id for POST /music/create-advanced name: string bio?: string tags?: string[] avatar?: string is_published?: boolean // left out when the character is private published_at?: number // Unix seconds created_at?: number // Unix seconds user_id?: number asset_id?: number showcase_edit_range?: object song_description?: string // the desc you sent } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST https://api.useapi.net/v1/mureka/music/characters \ -d '{"account": "…", "vocal_id": …, "name": "Scarlett", "tags": ["Female", "Powerful"]}' ``` **JavaScript** ``` javascript const account = "12345678901234"; const vocal_id = 166746659094530; const apiUrl = `https://api.useapi.net/v1/mureka/music/characters`; const api_token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${api_token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ account, vocal_id, name: 'Scarlett', tags: ['Female', 'Powerful'] }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests account = "12345678901234" vocal_id = 166746659094530 apiUrl = f"https://api.useapi.net/v1/mureka/music/characters" api_token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {api_token}" } body = { "account": account, "vocal_id": vocal_id, "name": "Scarlett", "tags": ["Female", "Powerful"] } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-mureka-v1/post-mureka-music-create-advanced === Document URL: https://useapi.net/docs/api-mureka-v1/post-mureka-music-create-advanced --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> music/create-advanced description: "Generate a song with custom lyrics, vocals, and reference style via POST music/create-advanced in the useapi.net Mureka API v1." parent: Mureka API nav_order: 1200 --- ## Create a song using custom lyrics, styles, vocals and reference song December 2, 2024 (November 16, 2026) --- Mureka supports up to **10 parallel generations** per account in **near real-time** fashion, with an average generation time of 45 seconds (each generation produces two songs). Generated songs can be up to 5 minutes long depending on your lyrics. > **https://api.useapi.net/v1/mureka/music/create-advanced** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "account": "Optional Mureka API account", "lyrics": "Required song lyrics", "title": "Optional song title", } ``` - `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) is configured or if the `motif_id` parameter is provided. However, if you have multiple accounts configured and the `motif_id` parameter is not provided, this parameter becomes **required**. - `lyrics` is **required**. Lyrics for the song. Maximum length: 5000 characters. - `title` is optional. Song title. Maximum length: 50 characters. - `desc` is optional. To guide song generation, provide a comma-separated list of genres, moods, and desired vocals. See supported values using [GET /music/moods-and-genres](/docs/api-mureka-v1/get-mureka-music-moods-and-genres). Combine it with `vocal_id` or `character_id` to have that voice sing your lyrics in this style, and with `ref_id` to blend a reference track's sound with this style. This parameter is not compatible with `motif_id`. Example: `pop, electronic, happy, female vocal`" Maximum length: 1000 characters. - `vocal_id` is optional. Specify the desired vocal. See supported vocals using [GET /music/vocals](/docs/api-mureka-v1/get-mureka-music-vocals). Upload your own voice with [POST /files/vocal](/docs/api-mureka-v1/post-mureka-files-vocal) and use the returned `id`. Can be combined with `desc` and `ref_id`. - `character_id` is optional, a reusable singer created with [POST /music/characters](/docs/api-mureka-v1/post-mureka-music-characters). See your characters using [GET /music/characters](/docs/api-mureka-v1/get-mureka-music-characters). The song is sung in the character's voice, in the style you give in `desc`. Can be combined with `desc` and `ref_id`, not with `vocal_id`, because the character already has its voice. - `ref_id` is optional. Create songs inspired by a reference track. See available tracks using [GET /music/refs](/docs/api-mureka-v1/get-mureka-music-refs). You can upload your own track using [POST /files](/docs/api-mureka-v1/post-mureka-files). To see a list of tracks you have already uploaded, use [GET /files](/docs/api-mureka-v1/get-mureka-files). - `motif_id` is optional. Create songs inspired by a melody idea to kickstart your song. Upload the melody using [POST /files/motif](/docs/api-mureka-v1/post-mureka-files-motif) and use the returned `id` value. This parameter is not compatible with parameters `ref_id`, `vocal_id`, `character_id` or `desc`. - `model` is optional. Supported values: `V9.5` (default), `V9`, `V8`, `O2`, `V7.6`, `V7.5-all`. The older `V7.5` id still works and runs on `V7.5-all`. Note: `V7`, `O1`, and `V6` are retired models that now redirect to `V7.6`. When `model` is omitted, the API uses the model Mureka reports as the default for your Mureka account — `models.default_model` in [GET /profile](/docs/api-mureka-v1/get-mureka-profile) — falling back to `V9.5`. Mureka tags every model except `V7.5-all` with `min_tier: basic`, meaning an active paid Mureka plan is required. Without one, those models return `403 low vip level (6335)` and only `V7.5-all` generates. `models.default_model` is what Mureka promotes rather than what your account may use, so a plan-less account can be shown `V9.5` as its default and still be refused it. - `vocal_gender` is optional. Specify desired vocal gender. Supported values: `female`, `male`. - `async` is optional, enables fire-and-forget mode (default: `false`). When `true`, returns immediately with `201 Created` and job metadata. Poll [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) for completion status. Useful for avoiding long request timeouts since music generation takes 30-90 seconds. - `replyUrl` is optional, webhook URL for job status callbacks. Receives a POST request when the job ends as `completed` or `failed`. The JSON payload shape matches [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) response. - `replyRef` is optional, custom reference string passed back in webhook callbacks. Useful for tracking jobs on your end. ##### Responses **200** **200 OK** ```json { "jobid": "j0121061432017475905m-u777-a12345678901234-bot:mureka", "feed_id": 11223344, "state": 3, "songs": [ { "song_id": "user:777-mureka:123456789-song:33445566", "title": "<title>", "version": "1", "duration_milliseconds": 234567, "generate_at": 12345677, "genres": [ "electronic", "indie" ], "moods": [ "quirky", "angry", "restless" ], "mp3_url": "https://<download link>.mp3", "share_key": "<share key>", "recall": true, "machine_audit_state": 4, "credit_type": 1, "cover": "https://<cover image>.png", "share_link": "https://<share link>" }, { "song_id": "user:777-mureka:123456789-song:33445566", "title": "<title>", "version": "2", "duration_milliseconds": 1234567, "generate_at": 12345667, "genres": [ "electronic", "world-music" ], "moods": [ "dark", "quirky", "energetic" ], "mp3_url": "https://<download link>.mp3", "share_key": "<share key>", "machine_audit_state": 1, "credit_type": 1, "cover": "https://<cover image>.png", "share_link": "https://<share link>" } ] } ``` **201** **201 Created** Job created in async mode (`async: true`). Music generation is processing in the background. Use [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) to poll for completion status. ```json { "jobid": "j0121061432017475905m-u777-a12345678901234-bot:mureka", "verb": "music/create-advanced", "jobType": "music", "status": "created", "created": "2026-01-20T12:34:56.789Z", "request": { "account": "12345678901234", "lyrics": "Your song lyrics here", "title": "My Song", "model": "V7.6", "async": true, "replyUrl": "https://your-domain.com/webhook", "replyRef": "my-custom-ref-123" } } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Wrong username/password combination.", "code": 401 } ``` **429** **429 Too Many Requests** * Rate limit exceeded. Endpoint called too frequently. Wait at least 3 seconds before making another call. ```json { "code": 9008, "msg": "Too frequently, please try again later." } ``` * Concurrent job limit exceeded. All job slots are taken (typically 10 concurrent generations per account). Wait at least 5 seconds before retrying. ```json { "error": "Generate multiple task exceed limit. (6323)" } ``` **596** **596 Account Error** Returned when the account has an error state preventing API calls. ```json { "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required", "code": "REFRESH_FAILED" } ``` Possible error codes: - `ACCOUNT_ERROR` - Account has a blocking error - `REFRESH_FAILED` - Automatic token refresh failed - `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly - `SESSION_EXPIRED` - Session expired and no auto-refresh available - `COOKIE_EXPIRED` - Google cookie has expired To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts). ##### Model Sync mode answers with the finished songs and their MP3 links, and async mode with the new job to poll with [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid). <details markdown="block" class="model-details"> <summary>The answer for each status (sync songs, async job, error), field by field</summary> **200 OK (Sync)** Music generation completed. Returns full song data with MP3 URLs. ```typescript { jobid: string // Job identifier (for later lookup) feed_id: number state: number songs?: { song_id: string title: string version: string duration_milliseconds: number generate_at: number genres: string[] moods: string[] mp3_url: string share_key: string machine_audit_state: number credit_type: number cover: string share_link: string }[] error?: string code?: number msg?: string } ``` **201 Created (Async)** Job created and processing in background. Structure matches [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) response. ```typescript { jobid: string // Job identifier verb: 'music/create-advanced' // Job verb jobType: 'music' // Job type status: 'created' // Job status created: string // ISO 8601 timestamp request: { account?: string lyrics: string title?: string desc?: string vocal_id?: string character_id?: number ref_id?: string motif_id?: string model?: string vocal_gender?: string async: true replyUrl?: string replyRef?: string } } ``` **Error** Error response structure (applies to both sync and async modes). ```typescript { jobid?: string // Present for job-related errors error: string // Error summary message code?: number // HTTP status code or error code msg?: string // Additional error message } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST https://api.useapi.net/v1/mureka/music/create-advanced \ -d '{"account": "…", "lyrics": "…"}' ``` **JavaScript** ``` javascript const account = "Mureka account"; const lyrics = "<Your song lyrics here>"; const apiUrl = `https://api.useapi.net/v1/mureka/music/create-advanced`; const api_token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${api_token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ account, lyrics }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests account = "Mureka account" lyrics = "<Your song lyrics here>" apiUrl = f"https://api.useapi.net/v1/mureka/music/create-advanced" api_token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {api_token}" } body = { "account": f"{account}", "lyrics": f"{lyrics}" } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-mureka-v1/post-mureka-music-create-instrumental === Document URL: https://useapi.net/docs/api-mureka-v1/post-mureka-music-create-instrumental --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> music/create-instrumental description: "Generate lyrics-free Mureka instrumental tracks from a text prompt via POST music/create-instrumental in the useapi.net Mureka API v1." parent: Mureka API nav_order: 1210 --- ## Create instrumental music March 31, 2025 (November 16, 2026) --- Mureka supports up to **10 parallel generations** per account in **near real-time** fashion, with an average generation time of 45 seconds (each generation produces two songs). Generated songs can be up to 5 minutes long depending on your prompt. > **https://api.useapi.net/v1/mureka/music/create-instrumental** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "account": "Optional Mureka API account", "prompt": "Ambient electronic with soft pads, great for nature walks and peaceful moments." } ``` - `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) is configured or if the `motif_id` parameter is provided. However, if you have multiple accounts configured and the `motif_id` parameter is not provided, this parameter becomes **required**. - `prompt` is optional. Describe your instrumental music. Maximum length: 1000 characters. - `title` is optional. Song title. Maximum length: 50 characters. - `ref_id` is optional. Create music inspired by a reference track. See available tracks using [GET /music/refs](/docs/api-mureka-v1/get-mureka-music-refs). You can upload your own track using [POST /files](/docs/api-mureka-v1/post-mureka-files). To see a list of tracks you have already uploaded, use [GET /files](/docs/api-mureka-v1/get-mureka-files). - `model` is optional. Supported values: `V9.5` (default), `V9`, `V8`, `O2`, `V7.6`, `V7.5-all`. The older `V7.5` id still works and runs on `V7.5-all`. Note: `V7`, `O1`, `V6`, and `V5.5` are retired models that now redirect to `V7.6`. When `model` is omitted, the API uses the model Mureka reports as the default for your Mureka account — `models.default_model` in [GET /profile](/docs/api-mureka-v1/get-mureka-profile) — falling back to `V9.5`. Mureka tags every model except `V7.5-all` with `min_tier: basic`, meaning an active paid Mureka plan is required. Without one, those models return `403 low vip level (6335)` and only `V7.5-all` generates. `models.default_model` is what Mureka promotes rather than what your account may use, so a plan-less account can be shown `V9.5` as its default and still be refused it. - `async` is optional, enables fire-and-forget mode (default: `false`). When `true`, returns immediately with `201 Created` and job metadata. Poll [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) for completion status. Useful for avoiding long request timeouts since music generation takes 30-90 seconds. - `replyUrl` is optional, webhook URL for job status callbacks. Receives a POST request when the job ends as `completed` or `failed`. The JSON payload shape matches [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) response. - `replyRef` is optional, custom reference string passed back in webhook callbacks. Useful for tracking jobs on your end. ##### Responses **200** **200 OK** ```json { "jobid": "j0121061432017475905m-u777-a12345678901234-bot:mureka", "feed_id": 11223344, "state": 3, "songs": [ { "song_id": "user:777-mureka:123456789-song:33445566", "title": "<title>", "version": "1", "duration_milliseconds": 234567, "generate_at": 12345677, "genres": [ "electronic", "indie" ], "moods": [ "quirky", "angry", "restless" ], "mp3_url": "https://<download link>.mp3", "share_key": "<share key>", "recall": true, "machine_audit_state": 4, "credit_type": 1, "cover": "https://<cover image>.png", "share_link": "https://<share link>" }, { "song_id": "user:777-mureka:123456789-song:33445566", "title": "<title>", "version": "2", "duration_milliseconds": 1234567, "generate_at": 12345667, "genres": [ "electronic", "world-music" ], "moods": [ "dark", "quirky", "energetic" ], "mp3_url": "https://<download link>.mp3", "share_key": "<share key>", "machine_audit_state": 1, "credit_type": 1, "cover": "https://<cover image>.png", "share_link": "https://<share link>" } ] } ``` **201** **201 Created** Job created in async mode (`async: true`). Music generation is processing in the background. Use [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) to poll for completion status. ```json { "jobid": "j0121061432017475905m-u777-a12345678901234-bot:mureka", "verb": "music/create-instrumental", "jobType": "music", "status": "created", "created": "2026-01-20T12:34:56.789Z", "request": { "account": "12345678901234", "prompt": "Ambient electronic with soft pads", "model": "V7.6", "async": true, "replyUrl": "https://your-domain.com/webhook", "replyRef": "my-custom-ref-123" } } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Wrong username/password combination.", "code": 401 } ``` **429** **429 Too Many Requests** * Rate limit exceeded. Endpoint called too frequently. Wait at least 3 seconds before making another call. ```json { "code": 9008, "msg": "Too frequently, please try again later." } ``` * Concurrent job limit exceeded. All job slots are taken (typically 10 concurrent generations per account). Wait at least 5 seconds before retrying. ```json { "error": "Generate multiple task exceed limit. (6323)" } ``` **596** **596 Account Error** Returned when the account has an error state preventing API calls. ```json { "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required", "code": "REFRESH_FAILED" } ``` Possible error codes: - `ACCOUNT_ERROR` - Account has a blocking error - `REFRESH_FAILED` - Automatic token refresh failed - `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly - `SESSION_EXPIRED` - Session expired and no auto-refresh available - `COOKIE_EXPIRED` - Google cookie has expired To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts). ##### Model Sync mode answers with the finished songs and their MP3 links, and async mode with the new job to poll with [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid). <details markdown="block" class="model-details"> <summary>The answer for each status (sync songs, async job, error), field by field</summary> **200 OK (Sync)** Music generation completed. Returns full song data with MP3 URLs. ```typescript { jobid: string // Job identifier (for later lookup) feed_id: number state: number songs?: { song_id: string title: string version: string duration_milliseconds: number generate_at: number genres: string[] moods: string[] mp3_url: string share_key: string machine_audit_state: number credit_type: number cover: string share_link: string }[] error?: string code?: number msg?: string } ``` **201 Created (Async)** Job created and processing in background. Structure matches [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) response. ```typescript { jobid: string // Job identifier verb: 'music/create-instrumental' // Job verb jobType: 'music' // Job type status: 'created' // Job status created: string // ISO 8601 timestamp request: { account?: string prompt?: string title?: string ref_id?: string model?: string async: true replyUrl?: string replyRef?: string } } ``` **Error** Error response structure (applies to both sync and async modes). ```typescript { jobid?: string // Present for job-related errors error: string // Error summary message code?: number // HTTP status code or error code msg?: string // Additional error message rawData?: string // Raw error data (if available) } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST https://api.useapi.net/v1/mureka/music/create-instrumental \ -d '{"account": "…", "prompt": "…"}' ``` **JavaScript** ``` javascript const account = "Mureka account"; const prompt = "<Your music prompt here>"; const apiUrl = `https://api.useapi.net/v1/mureka/music/create-instrumental`; const api_token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${api_token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ account, prompt }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests account = "Mureka account" prompt = "<Your music prompt here>" apiUrl = f"https://api.useapi.net/v1/mureka/music/create-instrumental" api_token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {api_token}" } body = { "account": f"{account}", "prompt": f"{prompt}" } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-mureka-v1/post-mureka-music-create === Document URL: https://useapi.net/docs/api-mureka-v1/post-mureka-music-create --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> music/create description: "Generate a Mureka song with AI-written lyrics from your text prompt via POST music/create in the useapi.net Mureka API v1 — parameters and response examples." parent: Mureka API nav_order: 1100 --- ## Create a song using AI-generated lyrics based on your prompt December 2, 2024 (November 16, 2026) --- Mureka supports up to **10 parallel generations** per account in **near real-time** fashion, with an average generation time of 45 seconds (each generation produces two songs). Generated songs can be up to 5 minutes long depending on your lyrics. > **https://api.useapi.net/v1/mureka/music/create** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "account": "Optional Mureka API account", "prompt": "Optional text prompt" } ``` - `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) configured. However, if you have multiple music configured, this parameter becomes **required**. - `prompt` is optional. Use it to guide AI to generate desired lyrics. If omitted AI will generate some random lyrics. Maximum length: 3000 characters. - `model` is optional. Supported values: `V9.5` (default), `V9`, `V8`, `O2`, `V7.6`, `V7.5-all`. Older aliases are still accepted: `V7.5` maps to `V7.5-all`, while `V7`, `O1`, and `V6` redirect to `V7.6`. When `model` is omitted, the API uses the model Mureka reports as the default for your Mureka account — `models.default_model` in [GET /profile](/docs/api-mureka-v1/get-mureka-profile) — falling back to `V9.5`. Mureka tags every model except `V7.5-all` with `min_tier: basic`, meaning an active paid Mureka plan is required. Without one, those models return `403 low vip level (6335)` and only `V7.5-all` generates. `models.default_model` is what Mureka promotes rather than what your account may use, so a plan-less account can be shown `V9.5` as its default and still be refused it. - `async` is optional, enables fire-and-forget mode (default: `false`). When `true`, returns immediately with `201 Created` and job metadata. Poll [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) for completion status. Useful for avoiding long request timeouts since music generation takes 30-90 seconds. - `replyUrl` is optional, webhook URL for job status callbacks. Receives a POST request when the job ends as `completed` or `failed`. The JSON payload shape matches [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) response. - `replyRef` is optional, custom reference string passed back in webhook callbacks. Useful for tracking jobs on your end. ##### Responses **200** **200 OK** ```json { "jobid": "j0121061432017475905m-u777-a12345678901234-bot:mureka", "feed_id": 11223344, "state": 3, "songs": [ { "song_id": "user:777-mureka:123456789-song:33445566", "title": "<title>", "version": "1", "duration_milliseconds": 234567, "generate_at": 12345677, "genres": [ "electronic", "indie" ], "moods": [ "quirky", "angry", "restless" ], "mp3_url": "https://<download link>.mp3", "share_key": "<share key>", "recall": true, "machine_audit_state": 4, "credit_type": 1, "cover": "https://<cover image>.png", "share_link": "https://<share link>" }, { "song_id": "user:777-mureka:123456789-song:33445566", "title": "<title>", "version": "2", "duration_milliseconds": 1234567, "generate_at": 12345667, "genres": [ "electronic", "world-music" ], "moods": [ "dark", "quirky", "energetic" ], "mp3_url": "https://<download link>.mp3", "share_key": "<share key>", "machine_audit_state": 1, "credit_type": 1, "cover": "https://<cover image>.png", "share_link": "https://<share link>" } ] } ``` **201** **201 Created** Job created in async mode (`async: true`). Music generation is processing in the background. Use [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) to poll for completion status. ```json { "jobid": "j0121061432017475905m-u777-a12345678901234-bot:mureka", "verb": "music/create", "jobType": "music", "status": "created", "created": "2026-01-20T12:34:56.789Z", "request": { "account": "12345678901234", "prompt": "Silly song about Santa", "model": "V7.6", "async": true, "replyUrl": "https://your-domain.com/webhook", "replyRef": "my-custom-ref-123" } } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Wrong username/password combination.", "code": 401 } ``` **429** **429 Too Many Requests** * Rate limit exceeded. Endpoint called too frequently. Wait at least 3 seconds before making another call. ```json { "code": 9008, "msg": "Too frequently, please try again later." } ``` * Concurrent job limit exceeded. All job slots are taken (typically 10 concurrent generations per account). Wait at least 5 seconds before retrying. ```json { "error": "Generate multiple task exceed limit. (6323)" } ``` **596** **596 Account Error** Returned when the account has an error state preventing API calls. ```json { "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required", "code": "REFRESH_FAILED" } ``` Possible error codes: - `ACCOUNT_ERROR` - Account has a blocking error - `REFRESH_FAILED` - Automatic token refresh failed - `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly - `SESSION_EXPIRED` - Session expired and no auto-refresh available - `COOKIE_EXPIRED` - Google cookie has expired To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts). ##### Model Sync mode answers with the finished songs and their MP3 links, and async mode with the new job to poll with [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid). <details markdown="block" class="model-details"> <summary>The answer for each status (sync songs, async job, error), field by field</summary> **200 OK (Sync)** Music generation completed. Returns full song data with MP3 URLs. ```typescript { jobid: string // Job identifier (for later lookup) feed_id: number state: number songs?: { song_id: string title: string version: string duration_milliseconds: number generate_at: number genres: string[] moods: string[] mp3_url: string share_key: string machine_audit_state: number credit_type: number cover: string share_link: string }[] error?: string code?: number msg?: string } ``` **201 Created (Async)** Job created and processing in background. Structure matches [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) response. ```typescript { jobid: string // Job identifier verb: 'music/create' // Job verb jobType: 'music' // Job type status: 'created' // Job status created: string // ISO 8601 timestamp request: { account?: string prompt?: string model?: string async: true replyUrl?: string replyRef?: string } } ``` **Error** Error response structure (applies to both sync and async modes). ```typescript { jobid?: string // Present for job-related errors error: string // Error summary message code?: number // HTTP status code or error code msg?: string // Additional error message rawData?: string // Raw error data (if available) } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST https://api.useapi.net/v1/mureka/music/create \ -d '{"account": "…", "prompt": "…"}' ``` **JavaScript** ``` javascript const account = "Mureka account"; const prompt = "Silly song about Santa"; const apiUrl = `https://api.useapi.net/v1/mureka/music/create`; const api_token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${api_token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ account, prompt }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests account = "Mureka account" prompt = "Silly song about Santa" apiUrl = f"https://api.useapi.net/v1/mureka/music/create" api_token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {api_token}" } body = { "account": f"{account}", "prompt": f"{prompt}" } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-mureka-v1/post-mureka-music-download === Document URL: https://useapi.net/docs/api-mureka-v1/post-mureka-music-download --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> music/download description: "Download the stems or license ZIP for a generated Mureka song via POST music/download in the useapi.net Mureka API v1 — specify 'stem' or 'license' as the type." parent: Mureka API nav_order: 1220 --- ## Download the song license and stems March 31, 2025 (November 16, 2026) --- > **https://api.useapi.net/v1/mureka/music/download** The `stem` type returns the basic stems package and needs Mureka's [Premier plan](https://www.mureka.ai/subscribe). On Free or Pro it returns `403 low vip level (6335)`. To separate a song into up to 12 instrument and vocal tracks with MIDI, use [POST /music/stems](/docs/api-mureka-v1/post-mureka-music-stems) and [POST /music/stems-download](/docs/api-mureka-v1/post-mureka-music-stems-download). ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "song_id": 123456789, "type": "stem" } ``` - `song_id` is **required**. The `song_id` value returned by one of the following endpoints: * [GET /music](/docs/api-mureka-v1/get-mureka-music) * [POST /music/create](/docs/api-mureka-v1/post-mureka-music-create) * [POST /music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced) * [POST /music/create-instrumental](/docs/api-mureka-v1/post-mureka-music-create-instrumental) * [POST /music/download](/docs/api-mureka-v1/post-mureka-music-download) * [POST /music/edit](/docs/api-mureka-v1/post-mureka-music-edit) - `type` is **required**. Supported values: `stem`, `license` ##### Responses **200** **200 OK** ```json { "oss_key": "https://static-cos.mureka.ai/…zip", "paid_state": 1 } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Wrong username/password combination.", "code": 401 } ``` **596** **596 Account Error** Returned when the account has an error state preventing API calls. ```json { "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required", "code": "REFRESH_FAILED" } ``` Possible error codes: - `ACCOUNT_ERROR` - Account has a blocking error - `REFRESH_FAILED` - Automatic token refresh failed - `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly - `SESSION_EXPIRED` - Session expired and no auto-refresh available - `COOKIE_EXPIRED` - Google cookie has expired To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts). ##### Model The link to the stems package or license file in `oss_key`, plus `paid_state`. <details markdown="block" class="model-details"> <summary>The download link, field by field</summary> ```typescript { // TypeScript, all fields are optional oss_key: string paid_state: number } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST https://api.useapi.net/v1/mureka/music/download \ -d '{"song_id": …, "type": "stem"}' ``` **JavaScript** ``` javascript const song_id = 123456789; const type = "stem"; const apiUrl = `https://api.useapi.net/v1/mureka/music/download`; const api_token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${api_token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ song_id, type }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests song_id = 123456789 type = "stem" apiUrl = f"https://api.useapi.net/v1/mureka/music/download" api_token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {api_token}" } body = { "song_id": song_id, "type": f"{type}" } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-mureka-v1/post-mureka-music-edit === Document URL: https://useapi.net/docs/api-mureka-v1/post-mureka-music-edit --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> music/edit description: "Rewrite one section of an existing Mureka song via POST music/edit in the useapi.net Mureka API v1 — pick a millisecond range, supply new lyrics, and optionally keep the original melody." parent: Mureka API nav_order: 1260 --- ## Edit song section September 5, 2026 (November 16, 2026) --- > **https://api.useapi.net/v1/mureka/music/edit** Re-render one bounded section of a song you already generated. You choose the section by time range, hand Mureka the lyrics that section should sing, and get back a complete song with only that stretch replaced. Editing keeps the rest of the track untouched. To re-record a whole song in a new style, use [POST /music/remix](/docs/api-mureka-v1/post-mureka-music-remix). There is no `model` parameter. The edit inherits whatever rendered the source song, and the edited song comes back reporting no model of its own. Sending one is rejected with `400 Parameter model not supported`. An active paid Mureka plan is required. Without one every call returns `403 low vip level (6335)`. An edit costs 20 credits and returns one song. Credits come off when the request is accepted, not when the song finishes. ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "song_id": "user:777-mureka:123456789-song:33445566", "start_milliseconds": 41560, "end_milliseconds": 87080, "lyrics": "Golden temples hum a tune\nIncense swirling, afternoon\nThis line is new\nEvery heartbeat sings this room", "keep_melody": true } ``` - `song_id` is **required**. The `song_id` value returned by one of the following endpoints: * [GET /music](/docs/api-mureka-v1/get-mureka-music) * [GET /music/`song_id`](/docs/api-mureka-v1/get-mureka-music-song_id) * [POST /music/create](/docs/api-mureka-v1/post-mureka-music-create) * [POST /music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced) * [POST /music/create-instrumental](/docs/api-mureka-v1/post-mureka-music-create-instrumental) * [POST /music/extend](/docs/api-mureka-v1/post-mureka-music-extend) * [POST /music/edit](/docs/api-mureka-v1/post-mureka-music-edit) - `start_milliseconds` is optional, where the edited section begins (default: `0`). - `end_milliseconds` is optional, where the edited section ends (default: the song's `duration_milliseconds`, so omitting both bounds rewrites the whole song). A value past the end of the song is clamped to its duration. Pick the range off [GET /music/`song_id`](/docs/api-mureka-v1/get-mureka-music-song_id), where each sung line carries its own `start` and `end` in milliseconds. Mureka treats your range as a hint and may widen it to a musical boundary, so the finished song can cover more than you asked for — `regenerate_from` and `regenerate_to` on the returned song report the range it actually used. - `lyrics` is optional, up to 3000 characters — the lyrics for the selected range only, not for the whole song. One line per sung line, without the `[Verse]` / `[Chorus]` section tags. Omit it to keep the words you already have: the API fills in the song's own lines from that range, so you can re-roll a section's performance without rewriting it. Only lines falling *entirely* inside the range are picked up, and they come through verbatim, including any bracketed production cue the song stores as a lyric line. A range that cuts a line in half drops that line, leaving Mureka fewer lyrics than the audio it spans — pin the bounds to a line's own `start` and `end` when you want an exact match. - `title` is optional, up to 58 characters (default: the source song's title). - `keep_melody` is optional (default: `true`). Leave it on to hold the existing melody and rewrite only what is sung over it, which keeps the section at its original length and leaves the rest of the track where it was. Set it to `false` and Mureka writes a new melody for the section, which is then re-timed to fit the new line. That moves everything after it and changes the song's total duration — in one measured run the same four lines came back six seconds shorter, pulling the closing section earlier and trimming a 2:55 track to 2:49. Check `duration_milliseconds` on the returned song rather than assuming it matches the source. - `async` is optional, enables fire-and-forget mode (default: `false`). When `true`, returns immediately with `201 Created` and job metadata. Poll [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) for completion status. Useful for avoiding long request timeouts since music generation takes 30-90 seconds. - `replyUrl` is optional, webhook URL for job status callbacks. Receives a POST request when the job ends as `completed` or `failed`. The JSON payload shape matches [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) response. - `replyRef` is optional, custom reference string passed back in webhook callbacks. Useful for tracking jobs on your end. ##### Responses **200** **200 OK** ```json { "jobid": "j0121061432017475905m-u777-a12345678901234-bot:mureka", "feed_id": 11223344, "state": 3, "songs": [ { "song_id": "user:777-mureka:123456789-song:33445566", "title": "<title>", "is_regenerate": true, "regenerate_from": 41560, "regenerate_to": 91013, "duration_milliseconds": 202843, "generate_at": 12345677, "genres": [ "r&b", "pop" ], "moods": [ "warm", "relaxed" ], "mp3_url": "https://<download link>.mp3", "share_key": "<share key>", "machine_audit_state": 1, "credit_type": 1, "cover": "https://<cover image>.png", "share_link": "https://<share link>" } ] } ``` **201** **201 Created** Job created in async mode (`async: true`). The edit is processing in the background. Use [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) to poll for completion status. ```json { "jobid": "j0121061432017475905m-u777-a12345678901234-bot:mureka", "verb": "music/edit", "jobType": "music", "status": "created", "created": "2026-09-05T12:34:56.789Z", "request": { "account": "12345678901234", "song_id": 33445566, "start_milliseconds": 41560, "end_milliseconds": 87080, "keep_melody": true, "async": true, "replyUrl": "https://your-domain.com/webhook", "replyRef": "my-custom-ref-123" } } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` Returned when the range is unusable — `end_milliseconds` at or before `start_milliseconds`, `start_milliseconds` past the end of the song, or a range that contains no sung lines while `lyrics` was omitted. **401** **401 Unauthorized** ```json { "error": "Wrong username/password combination.", "code": 401 } ``` **403** **403 Forbidden** Editing an existing song is a paid Mureka feature. Subscribe at [mureka.ai/subscribe](https://www.mureka.ai/subscribe) and retry. ```json { "error": "low vip level (6335)" } ``` **429** **429 Too Many Requests** * Rate limit exceeded. Endpoint called too frequently. Wait at least 3 seconds before making another call. ```json { "code": 9008, "msg": "Too frequently, please try again later." } ``` * Concurrent job limit exceeded. All job slots are taken (typically 10 concurrent generations per account). Wait at least 5 seconds before retrying. ```json { "error": "Generate multiple task exceed limit. (6323)" } ``` **596** **596 Account Error** Returned when the account has an error state preventing API calls. ```json { "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required", "code": "REFRESH_FAILED" } ``` Possible error codes: - `ACCOUNT_ERROR` - Account has a blocking error - `REFRESH_FAILED` - Automatic token refresh failed - `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly - `SESSION_EXPIRED` - Session expired and no auto-refresh available - `COOKIE_EXPIRED` - Google cookie has expired To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts). ##### Model Sync mode answers with the edited song and its MP3 link, and async mode with the new job to poll with [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid). <details markdown="block" class="model-details"> <summary>The answer for each status (sync song, async job, error), field by field</summary> **200 OK (Sync)** Edit completed. Returns the full song data with MP3 URLs. ```typescript { jobid: string // Job identifier (for later lookup) feed_id: number state: number songs?: { song_id: string title: string is_regenerate: boolean regenerate_from: number // Start of the range Mureka actually re-rendered regenerate_to: number // End of the range Mureka actually re-rendered duration_milliseconds: number generate_at: number genres: string[] moods: string[] mp3_url: string share_key: string machine_audit_state: number credit_type: number cover: string share_link: string }[] error?: string code?: number msg?: string } ``` **201 Created (Async)** Job created and processing in background. Structure matches [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) response. ```typescript { jobid: string // Job identifier verb: 'music/edit' // Job verb jobType: 'music' // Job type status: 'created' // Job status created: string // ISO 8601 timestamp request: { account?: string song_id: number // Decoded Mureka id, not the user:…-song:… form start_milliseconds?: number end_milliseconds?: number lyrics?: string title?: string keep_melody?: boolean async: true replyUrl?: string replyRef?: string } } ``` **Error** Error response structure (applies to both sync and async modes). ```typescript { jobid?: string // Present for job-related errors error: string // Error summary message code?: number // HTTP status code or error code msg?: string // Additional error message rawData?: string // Raw error data (if available) } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST https://api.useapi.net/v1/mureka/music/edit \ -d '{"song_id": "…", "start_milliseconds": 41560, "end_milliseconds": 87080, "lyrics": "…"}' ``` **JavaScript** ``` javascript const song_id = "user:777-mureka:123456789-song:33445566"; const start_milliseconds = 41560; const end_milliseconds = 87080; const lyrics = "Golden temples hum a tune\nIncense swirling, afternoon"; const apiUrl = `https://api.useapi.net/v1/mureka/music/edit`; const api_token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${api_token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ song_id, start_milliseconds, end_milliseconds, lyrics }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests song_id = "user:777-mureka:123456789-song:33445566" start_milliseconds = 41560 end_milliseconds = 87080 lyrics = "Golden temples hum a tune\nIncense swirling, afternoon" apiUrl = f"https://api.useapi.net/v1/mureka/music/edit" api_token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {api_token}" } body = { "song_id": song_id, "start_milliseconds": start_milliseconds, "end_milliseconds": end_milliseconds, "lyrics": lyrics } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-mureka-v1/post-mureka-music-extend === Document URL: https://useapi.net/docs/api-mureka-v1/post-mureka-music-extend --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> music/extend description: "Extend an existing Mureka song with new lyrics via POST music/extend in the useapi.net Mureka API v1 — supports async mode and webhook callbacks." parent: Mureka API nav_order: 1230 --- ## Extend song December 13, 2024 (November 16, 2026) --- > **https://api.useapi.net/v1/mureka/music/extend** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "song_id": 123456789, "lyrics": "required lyrics to extend your original song" } ``` - `song_id` is **required**. The `song_id` value returned by one of the following endpoints: * [GET /music](/docs/api-mureka-v1/get-mureka-music) * [POST /music/create](/docs/api-mureka-v1/post-mureka-music-create) * [POST /music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced) * [POST /music/create-instrumental](/docs/api-mureka-v1/post-mureka-music-create-instrumental) * [POST /music/extend](/docs/api-mureka-v1/post-mureka-music-extend) * [POST /music/edit](/docs/api-mureka-v1/post-mureka-music-edit) - `lyrics` is **required**. Lyrics for the song extension. Maximum length: 3000 characters. - `async` is optional, enables fire-and-forget mode (default: `false`). When `true`, returns immediately with `201 Created` and job metadata. Poll [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) for completion status. Useful for avoiding long request timeouts since music generation takes 30-90 seconds. - `replyUrl` is optional, webhook URL for job status callbacks. Receives a POST request when the job ends as `completed` or `failed`. The JSON payload shape matches [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) response. - `replyRef` is optional, custom reference string passed back in webhook callbacks. Useful for tracking jobs on your end. ##### Responses **200** **200 OK** ```json { "jobid": "j0121061432017475905m-u777-a12345678901234-bot:mureka", "feed_id": 11223344, "state": 3, "songs": [ { "song_id": "user:777-mureka:123456789-song:33445566", "title": "<title>", "version": "1...1", "is_regenerate": true, "regenerate_from": 123456, "duration_milliseconds": 234567, "generate_at": 12345677, "genres": [ "electronic", "indie" ], "moods": [ "quirky", "angry", "restless" ], "mp3_url": "https://<download link>.mp3", "share_key": "<share key>", "recall": true, "machine_audit_state": 1, "credit_type": 1, "cover": "https://<cover image>.png", "share_link": "https://<share link>" }, { "song_id": "user:777-mureka:123456789-song:33445566", "title": "<title>", "version": "1...2", "is_regenerate": true, "regenerate_from": 123456, "duration_milliseconds": 1234567, "generate_at": 12345667, "genres": [ "electronic", "world-music" ], "moods": [ "dark", "quirky", "energetic" ], "mp3_url": "https://<download link>.mp3", "share_key": "<share key>", "machine_audit_state": 1, "credit_type": 1, "cover": "https://<cover image>.png", "share_link": "https://<share link>" } ] } ``` **201** **201 Created** Job created in async mode (`async: true`). Music extension is processing in the background. Use [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) to poll for completion status. ```json { "jobid": "j0121061432017475905m-u777-a12345678901234-bot:mureka", "verb": "music/extend", "jobType": "music", "status": "created", "created": "2026-01-20T12:34:56.789Z", "request": { "account": "12345678901234", "song_id": "user:777-mureka:123456789-song:33445566", "lyrics": "New verse lyrics here", "async": true, "replyUrl": "https://your-domain.com/webhook", "replyRef": "my-custom-ref-123" } } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Wrong username/password combination.", "code": 401 } ``` **429** **429 Too Many Requests** * Rate limit exceeded. Endpoint called too frequently. Wait at least 3 seconds before making another call. ```json { "code": 9008, "msg": "Too frequently, please try again later." } ``` * Concurrent job limit exceeded. All job slots are taken (typically 10 concurrent generations per account). Wait at least 5 seconds before retrying. ```json { "error": "Generate multiple task exceed limit. (6323)" } ``` **596** **596 Account Error** Returned when the account has an error state preventing API calls. ```json { "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required", "code": "REFRESH_FAILED" } ``` Possible error codes: - `ACCOUNT_ERROR` - Account has a blocking error - `REFRESH_FAILED` - Automatic token refresh failed - `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly - `SESSION_EXPIRED` - Session expired and no auto-refresh available - `COOKIE_EXPIRED` - Google cookie has expired To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts). ##### Model Sync mode answers with the extended songs and their MP3 links, and async mode with the new job to poll with [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid). <details markdown="block" class="model-details"> <summary>The answer for each status (sync songs, async job, error), field by field</summary> **200 OK (Sync)** Music extension completed. Returns full song data with MP3 URLs. ```typescript { jobid: string // Job identifier (for later lookup) feed_id: number state: number songs?: { song_id: string title: string version: string is_regenerate: boolean regenerate_from: number duration_milliseconds: number generate_at: number genres: string[] moods: string[] mp3_url: string share_key: string machine_audit_state: number credit_type: number cover: string share_link: string }[] error?: string code?: number msg?: string } ``` **201 Created (Async)** Job created and processing in background. Structure matches [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) response. ```typescript { jobid: string // Job identifier verb: 'music/extend' // Job verb jobType: 'music' // Job type status: 'created' // Job status created: string // ISO 8601 timestamp request: { account?: string song_id: string lyrics: string async: true replyUrl?: string replyRef?: string } } ``` **Error** Error response structure (applies to both sync and async modes). ```typescript { jobid?: string // Present for job-related errors error: string // Error summary message code?: number // HTTP status code or error code msg?: string // Additional error message rawData?: string // Raw error data (if available) } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST https://api.useapi.net/v1/mureka/music/extend \ -d '{"song_id": …, "lyrics": "…"}' ``` **JavaScript** ``` javascript const song_id = 123456789; const lyrics = "place your lyrics here"; const apiUrl = `https://api.useapi.net/v1/mureka/music/extend`; const api_token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${api_token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ song_id, lyrics }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests song_id = 123456789 lyrics = "place your lyrics here" apiUrl = f"https://api.useapi.net/v1/mureka/music/extend" api_token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {api_token}" } body = { "song_id": song_id, "lyrics": f"{lyrics}" } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-mureka-v1/post-mureka-music-lyrics-generate === Document URL: https://useapi.net/docs/api-mureka-v1/post-mureka-music-lyrics-generate --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> music/lyrics-generate seo_title: "AI Lyrics Generator API: Write New Song Lyrics with Mureka, Free" description: "Write new AI song lyrics from a prompt via POST music/lyrics-generate in the useapi.net Mureka API, free of charge, then sing them with POST music/create-advanced. It writes original lyrics, not lookups of existing songs." parent: Mureka API nav_order: 1300 --- ## Create an AI-generated lyrics based on your prompt December 2, 2024 (November 16, 2026) --- > **https://api.useapi.net/v1/mureka/music/lyrics-generate** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "account": "Optional Mureka API account", "prompt": "Optional text prompt" } ``` - `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) configured. However, if you have multiple music configured, this parameter becomes **required**. - `prompt` is optional. Use it to guide AI to generate desired lyrics. If omitted AI will generate some random lyrics. ##### Responses **200** **200 OK** ```json { "lyrics": "<lyrics generated by AI based on your optional prompt>" } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Wrong username/password combination.", "code": 401 } ``` **429** **429 Too Many Requests** Rate limit exceeded. Endpoint called too frequently. Wait at least 1 second before making another call. ```json { "code": 9008, "msg": "Too frequently, please try again later." } ``` **596** **596 Account Error** Returned when the account has an error state preventing API calls. ```json { "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required", "code": "REFRESH_FAILED" } ``` Possible error codes: - `ACCOUNT_ERROR` - Account has a blocking error - `REFRESH_FAILED` - Automatic token refresh failed - `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly - `SESSION_EXPIRED` - Session expired and no auto-refresh available - `COOKIE_EXPIRED` - Google cookie has expired To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts). ##### Model The generated lyrics as one `lyrics` string, or `error`, `code` and `msg` when it fails. <details markdown="block" class="model-details"> <summary>The generated lyrics, field by field</summary> ```typescript { // TypeScript, all fields are optional lyrics: string error?: string code?: number msg?: string } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST https://api.useapi.net/v1/mureka/music/lyrics-generate \ -d '{"account": "…", "prompt": "…"}' ``` **JavaScript** ``` javascript const account = "Mureka account"; const prompt = "Silly song about Santa"; const apiUrl = `https://api.useapi.net/v1/mureka/music/lyrics-generate`; const api_token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${api_token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ account, prompt }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests account = "Mureka account" prompt = "Silly song about Santa" apiUrl = f"https://api.useapi.net/v1/mureka/music/lyrics-generate" api_token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {api_token}" } body = { "account": f"{account}", "prompt": f"{prompt}" } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-mureka-v1/post-mureka-music-remix === Document URL: https://useapi.net/docs/api-mureka-v1/post-mureka-music-remix --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> music/remix description: "Re-record one of your Mureka songs in a new style, keeping its lyrics and voice, via POST music/remix in the useapi.net Mureka API v1; sync, async or webhook." parent: Mureka API nav_order: 1262 --- ## Remix a song in a new style October 16, 2026 (November 16, 2026) --- > **https://api.useapi.net/v1/mureka/music/remix** Re-record one of your songs in a new style, the same as Remix on [mureka.ai](https://www.mureka.ai). Mureka uses the original recording as the reference and keeps its lyrics, and the new songs follow the style you give in `desc`. You can also replace the lyrics or the title. Like any song generation, a remix produces two songs and costs the same Mureka Gold as [POST /music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced) (24 Gold on V9.5 in our tests). It takes 30 to 60 seconds. Instrumental songs remix too, and the result stays instrumental. For an instrumental song only `desc`, `title` and `model` apply. ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "song_id": "user:777-mureka:12345678901234-song:33445566", "desc": "D&B, hip-hop" } ``` - `song_id` is **required**, the song to remix. The `song_id` value returned by one of the following endpoints: * [GET /music](/docs/api-mureka-v1/get-mureka-music) * [GET /music/`song_id`](/docs/api-mureka-v1/get-mureka-music-song_id) * [POST /music/create](/docs/api-mureka-v1/post-mureka-music-create) * [POST /music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced) * [POST /music/extend](/docs/api-mureka-v1/post-mureka-music-extend) * [POST /music/edit](/docs/api-mureka-v1/post-mureka-music-edit) * [POST /music/remix](/docs/api-mureka-v1/post-mureka-music-remix) The song's own account runs the remix, so there is no `account` parameter. - `desc` is optional, the new style: a comma-separated list of genres, moods and instruments. See supported values using [GET /music/moods-and-genres](/docs/api-mureka-v1/get-mureka-music-moods-and-genres). When left out, the original song's style is used. Maximum length: 1000 characters. - `lyrics` is optional, new lyrics. When left out, the original lyrics are used. Can not be used with an instrumental song. Maximum length: 5000 characters. - `title` is optional. When left out, a song with vocals keeps the original title plus `(Remix)`, and Mureka names an instrumental remix itself. Maximum length: 50 characters. - `vocal_gender` is optional. Supported values: `female`, `male`. Can not be used with an instrumental song. - `model` is optional. Supported values: `V9.5`, `V9`, `V8`. When left out, the account's default model is used if it supports remix, otherwise `V9.5`. - `async` is optional, enables fire-and-forget mode (default: `false`). When `true`, returns immediately with `201 Created` and job metadata. Poll [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) for completion status. - `replyUrl` is optional, webhook URL for job status callbacks. Receives a POST request when the job ends as `completed` or `failed`. The JSON payload shape matches [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) response. - `replyRef` is optional, custom reference string passed back in webhook callbacks. Useful for tracking jobs on your end. ##### Responses **200** **200 OK** Real response, one of the two songs shown, ids shortened. ```json { "jobid": "j1016230256133236021m-u777-a12345678901234-bot:mureka", "feed_id": 166751633473537, "state": 3, "songs": [ { "song_id": "user:777-mureka:12345678901234-song:166751644024833", "title": "Scarlett character song(Remix)", "duration_milliseconds": 87230, "generate_at": 1792191775, "genres": [ "electronic" ], "moods": [ "energetic" ], "description": "D&B, hip-hop", "mp3_url": "https://static-cos.mureka.ai/cos-prod/song/audio/20261016/<id>.mp3", "share_key": "<share key>", "machine_audit_state": 1, "credit_type": 1, "cover": "https://static-cos.mureka.ai/cos-prod/skm/image/20261016/<id>.jpeg", "control_types": [ 1, 3, 5, 11 ], "generate_state": 3, "generation_method": 1, "allow_remix": true, "share_link": "https://www.mureka.ai/song-detail?share_key=<share key>&is_from_share=1" } ] } ``` **201** **201 Created** Job created in async mode (`async: true`). The remix is processing in the background. Use [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) to poll for completion status. ```json { "jobid": "j1016230256133236021m-u777-a12345678901234-bot:mureka", "verb": "music/remix", "jobType": "music", "status": "created", "created": "2026-10-16T23:02:56.133Z", "request": { "song_id": 166751520227330, "desc": "D&B, hip-hop", "async": true, "account": "12345678901234" } } ``` **400** **400 Bad Request** ```json { "error": "Song 33445566 is instrumental, parameters lyrics and vocal_gender can not be used", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Wrong username/password combination.", "code": 401 } ``` **412** **412 Precondition Failed** The account does not have enough Mureka Gold (a remix costs the same as a song). ```json { "error": "User balance is not enough to operate (6310)", "code": 412 } ``` **596** **596 Account Error** Returned when the account has an error state preventing API calls. ```json { "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required", "code": "REFRESH_FAILED" } ``` Possible error codes: - `ACCOUNT_ERROR` - Account has a blocking error - `REFRESH_FAILED` - Automatic token refresh failed - `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly - `SESSION_EXPIRED` - Session expired and no auto-refresh available - `COOKIE_EXPIRED` - Google cookie has expired To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts). ##### Model Sync mode answers with the remixed songs and their MP3 links, and async mode with the new job to poll with [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid). <details markdown="block" class="model-details"> <summary>The answer for each status (sync songs, async job), field by field</summary> **200** Same structure as [POST /music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced). ```typescript { jobid: string feed_id: number state: number songs: { song_id: string title: string duration_milliseconds: number generate_at: number genres: string[] moods: string[] description?: string // the style used mp3_url: string share_key: string share_link: string cover: string control_types?: number[] machine_audit_state: number credit_type: number }[] } ``` **201** ```typescript { jobid: string verb: 'music/remix' jobType: 'music' status: 'created' created: string // ISO 8601 timestamp request: { song_id: number // Decoded Mureka id, not the user:…-song:… form desc?: string lyrics?: string title?: string vocal_gender?: string model?: string account: string async?: boolean replyUrl?: string replyRef?: string } } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST https://api.useapi.net/v1/mureka/music/remix \ -d '{"song_id": "…", "desc": "D&B, hip-hop"}' ``` **JavaScript** ``` javascript const song_id = "user:777-mureka:12345678901234-song:33445566"; const desc = "D&B, hip-hop"; const apiUrl = `https://api.useapi.net/v1/mureka/music/remix`; const api_token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${api_token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ song_id, desc }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests apiUrl = f"https://api.useapi.net/v1/mureka/music/remix" api_token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {api_token}" } body = { "song_id": "user:777-mureka:12345678901234-song:33445566", "desc": "D&B, hip-hop" } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-mureka-v1/post-mureka-music-score === Document URL: https://useapi.net/docs/api-mureka-v1/post-mureka-music-score --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> music/score description: "Turn a Mureka song, a YouTube link or an uploaded audio file into sheet music (MusicXML, staff and numbered-notation PDF) via POST music/score in the useapi.net Mureka API v1." parent: Mureka API nav_order: 1226 --- ## Turn a song into sheet music October 16, 2026 (November 16, 2026) --- > **https://api.useapi.net/v1/mureka/music/score** Transcribe the main melody and chords of a song into sheet music, the same as the Score tool on [mureka.ai](https://www.mureka.ai). You get a link to a `.zip` with three files: - `<title>_staff.musicxml`, to open in MuseScore, Sibelius, Finale, Dorico and other notation software - `<title>_staff.pdf`, staff notation - `<title>_numbered_notation.pdf`, numbered (jianpu) notation The source can be one of your Mureka songs, a YouTube link, or an audio file you uploaded with [POST /files](/docs/api-mureka-v1/post-mureka-files) or [POST /files/vocal](/docs/api-mureka-v1/post-mureka-files-vocal). The audio must be 10 seconds to 10 minutes long. A score costs 10 Mureka Gold. Scoring the same YouTube link again returned the earlier zip, with its original file names, and was not charged in our tests. The call waits for the result, which takes about 5 to 15 seconds, plus up to 15 seconds to fetch a YouTube link. Mureka recommends a solo song with clear vocals, a steady tempo and a consistent rhythm. Songs with tempo changes or frequent rhythm changes are not supported well. Tutorial: [How to Turn a Song or YouTube Link into Sheet Music with the Mureka API](/docs/articles/mureka-sheet-music), one real score step by step with curl, the zip's three files and how to open the MusicXML in MuseScore. ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "song_id": "user:777-mureka:12345678901234-song:33445566" } ``` ```json { "account": "12345678901234", "url": "https://www.youtube.com/watch?v=f_YMI6Rc9Ok" } ``` - `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) is configured or when `song_id` is provided. However, if you have multiple accounts configured and `song_id` is not provided, this parameter becomes **required**. - `song_id` is optional, one of your songs. The `song_id` value returned by one of the following endpoints: * [GET /music](/docs/api-mureka-v1/get-mureka-music) * [GET /music/`song_id`](/docs/api-mureka-v1/get-mureka-music-song_id) * [POST /music/create](/docs/api-mureka-v1/post-mureka-music-create) * [POST /music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced) * [POST /music/extend](/docs/api-mureka-v1/post-mureka-music-extend) * [POST /music/edit](/docs/api-mureka-v1/post-mureka-music-edit) * [POST /music/remix](/docs/api-mureka-v1/post-mureka-music-remix) - `url` is optional, either a YouTube link or the `url` of a file uploaded with [POST /files](/docs/api-mureka-v1/post-mureka-files) or [POST /files/vocal](/docs/api-mureka-v1/post-mureka-files-vocal) (a `https://static-cos.mureka.ai/…` link). Maximum length: 2048 characters. Specify `song_id` or `url`, but not both. - `title` is optional, the name used for the files in the zip when the source is a `url`. It defaults to the YouTube video title. A `song_id` source always uses the song's own title. Maximum length: 100 characters. ##### Responses **200** **200 OK** ```json { "title": "Hold My Hand", "url": "https://static-cos.mureka.ai/cos-prod/skm/music-staff/20261016/<id>.zip" } ``` **400** **400 Bad Request** ```json { "error": "Please specify song_id or url but not both", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Wrong username/password combination.", "code": 401 } ``` **412** **412 Precondition Failed** The account does not have enough Mureka Gold (10 Gold per score). ```json { "error": "User balance is not enough to operate (6310)", "code": 412 } ``` **596** **596 Account Error** Returned when the account has an error state preventing API calls. ```json { "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required", "code": "REFRESH_FAILED" } ``` Possible error codes: - `ACCOUNT_ERROR` - Account has a blocking error - `REFRESH_FAILED` - Automatic token refresh failed - `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly - `SESSION_EXPIRED` - Session expired and no auto-refresh available - `COOKIE_EXPIRED` - Google cookie has expired To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts). ##### Model The link to a `.zip` of the sheet music, as MusicXML and two PDFs, plus the `title` used for its file names. <details markdown="block" class="model-details"> <summary>The sheet music download, field by field</summary> ```typescript { title: string // file name used inside the zip url: string // .zip with MusicXML, staff PDF and numbered-notation PDF } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST https://api.useapi.net/v1/mureka/music/score \ -d '{"song_id": "…"}' ``` **JavaScript** ``` javascript const song_id = "user:777-mureka:12345678901234-song:33445566"; const apiUrl = `https://api.useapi.net/v1/mureka/music/score`; const api_token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${api_token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ song_id }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests apiUrl = f"https://api.useapi.net/v1/mureka/music/score" api_token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {api_token}" } body = { "song_id": "user:777-mureka:12345678901234-song:33445566" } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-mureka-v1/post-mureka-music-stems-download === Document URL: https://useapi.net/docs/api-mureka-v1/post-mureka-music-stems-download --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> music/stems-download description: "Get WAV, MIDI, ZIP or DAW session links (Ableton, Logic, Pro Tools, Cubase) for extracted stems via POST music/stems-download in the useapi.net Mureka API v1." parent: Mureka API nav_order: 1224 --- ## Download extracted stems October 9, 2026 (November 16, 2026) --- > **https://api.useapi.net/v1/mureka/music/stems-download** Get download links for the stems of a finished [POST /music/stems](/docs/api-mureka-v1/post-mureka-music-stems) extraction. Stems come from POST /music/stems, which needs Mureka's [Premier plan](https://www.mureka.ai/subscribe). Downloads are free. What you get depends on the parameters you send: | Parameters | Returns | |---|---| | `stems_id` only | `audio_zip` with every stem as audio, and `midi_zip` with every MIDI track | | `stems_id` + `stem_name` | One stem: its `wav` and its `midi` | | `stems_id` + `daw` | `url` of a session for Ableton Live, Logic Pro, Pro Tools or Cubase | The `.wav` and `.mp3` links of each stem are already in the [POST /music/stems](/docs/api-mureka-v1/post-mureka-music-stems) job response, so you only need this endpoint for MIDI, the ZIP archives or a DAW session. ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "stems_id": "user:777-mureka:12345678901234-song:33445566-stems:55667788", "stem_name": "drums" } ``` - `stems_id` is **required**, the `response.stems_id` value returned by [POST /music/stems](/docs/api-mureka-v1/post-mureka-music-stems) or [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid). The extraction must be `completed`, otherwise the call returns `409`. - `stem_name` is optional, one stem from the `stems` list of the extraction, such as `vocal`, `drums`, `bass` or `other`. Returns that stem's `wav` and `midi` links. `midi` is `null` when Mureka has no MIDI for that stem (seen once for `other`, FX on mureka.ai, on some songs). A name the extraction does not have returns `400`, with the available names in the error message. - `daw` is optional, builds a session you open directly in your DAW. Supported values: `ableton`, `logic`, `protools`, `cubase`. `ableton`, `logic` and `protools` return a `.zip`, `cubase` returns a `.dawproject` file. `logic` and `protools` return the same file. `stem_name` and `daw` can not be used together. ##### Responses **200** **200 OK** With `stems_id` only: ```json { "stems_id": "user:777-mureka:12345678901234-song:33445566-stems:55667788", "audio_zip": "https://static-cos.mureka.ai/<stems>.zip", "midi_zip": "https://static-cos.mureka.ai/<midi>.zip" } ``` With `stem_name`: ```json { "stems_id": "user:777-mureka:12345678901234-song:33445566-stems:55667788", "stem_name": "drums", "wav": "https://static-cos.mureka.ai/<drums>.wav", "midi": "https://static-cos.mureka.ai/<drums-midi>" } ``` With `daw`: ```json { "stems_id": "user:777-mureka:12345678901234-song:33445566-stems:55667788", "daw": "ableton", "url": "https://static-cos.mureka.ai/<session>.zip" } ``` **400** **400 Bad Request** Returned for a malformed `stems_id`, for `stem_name` and `daw` sent together, or for a `stem_name` the extraction does not have. ```json { "error": "Parameter stem_name (piano) not found, this extraction has vocal, drums, bass, other", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Wrong username/password combination.", "code": 401 } ``` **409** **409 Conflict** The extraction is still running. Poll [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) until it is `completed`, then retry. ```json { "error": "Stems extraction is not completed yet (generate_state 3), poll GET /jobs/{jobid}", "code": 409 } ``` **503** **503 Service Unavailable** Mureka builds a DAW session on request. If it is still not ready after a few retries, the call returns `503`. Retry shortly. ```json { "error": "DAW session ableton is not ready yet (state <n>), please retry shortly", "code": 503 } ``` **596** **596 Account Error** Returned when the account has an error state preventing API calls. ```json { "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required", "code": "REFRESH_FAILED" } ``` Possible error codes: - `ACCOUNT_ERROR` - Account has a blocking error - `REFRESH_FAILED` - Automatic token refresh failed - `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly - `SESSION_EXPIRED` - Session expired and no auto-refresh available - `COOKIE_EXPIRED` - Google cookie has expired To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts). ##### Model Download links that depend on what you send: both ZIP archives, one stem's WAV and MIDI, or a DAW session. <details markdown="block" class="model-details"> <summary>The stem download links, field by field</summary> ```typescript { // TypeScript, all fields are optional stems_id: string // stems_id only audio_zip: string | null midi_zip: string | null // stem_name stem_name: string wav: string | null midi: string | null // null for a stem without MIDI // daw daw: 'ableton' | 'logic' | 'protools' | 'cubase' url: string // .zip, or .dawproject for cubase } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST https://api.useapi.net/v1/mureka/music/stems-download \ -d '{"stems_id": "…", "stem_name": "drums"}' ``` **JavaScript** ``` javascript const stems_id = "user:777-mureka:12345678901234-song:33445566-stems:55667788"; const stem_name = "drums"; const apiUrl = `https://api.useapi.net/v1/mureka/music/stems-download`; const api_token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${api_token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ stems_id, stem_name }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests stems_id = "user:777-mureka:12345678901234-song:33445566-stems:55667788" stem_name = "drums" apiUrl = f"https://api.useapi.net/v1/mureka/music/stems-download" api_token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {api_token}" } body = { "stems_id": stems_id, "stem_name": stem_name } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-mureka-v1/post-mureka-music-stems === Document URL: https://useapi.net/docs/api-mureka-v1/post-mureka-music-stems --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> music/stems description: "Separate a Mureka song into up to 12 instrument and vocal stems plus MIDI via POST music/stems in the useapi.net Mureka API v1, or into just vocals and instrumental." parent: Mureka API nav_order: 1222 --- ## Extract stems from a song October 9, 2026 (November 16, 2026) --- > **https://api.useapi.net/v1/mureka/music/stems** Split a song you generated into separate tracks, the same as Extract Stems on [mureka.ai](https://www.mureka.ai). Needs Mureka's [Premier plan](https://www.mureka.ai/subscribe). On Free or Pro every call returns `403 low vip level (6335)`. There are two modes: | `all_stems` | What you get | Cost | |---|---|---| | `true` (default) | All detected stems — up to 12 separate instrument and vocal tracks, plus MIDI | 100 Mureka Gold | | `false` | Vocals + Instrumental | 20 Mureka Gold | Each stem comes back as a `.wav` and an `.mp3` link. Extraction takes about a minute for a 3-minute song (40 to 70 seconds in our tests). Every call starts a new extraction and is charged again, even for a song you already extracted. Keep the `stems_id` of a finished extraction and use it with [POST /music/stems-download](/docs/api-mureka-v1/post-mureka-music-stems-download) instead of extracting the same song twice. Once the job is `completed`, pass its `stems_id` to [POST /music/stems-download](/docs/api-mureka-v1/post-mureka-music-stems-download) for a single stem with its MIDI, ZIP archives of all stems and all MIDI, or a ready-made session for Ableton Live, Logic Pro, Pro Tools or Cubase. Those downloads are free. [POST /music/download](/docs/api-mureka-v1/post-mureka-music-download) with `type` `stem` still returns the basic stems package of a song, with no extraction job. ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "song_id": "user:777-mureka:12345678901234-song:33445566", "all_stems": true } ``` - `song_id` is **required**. The `song_id` value returned by one of the following endpoints: * [GET /music](/docs/api-mureka-v1/get-mureka-music) * [GET /music/`song_id`](/docs/api-mureka-v1/get-mureka-music-song_id) * [POST /music/create](/docs/api-mureka-v1/post-mureka-music-create) * [POST /music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced) * [POST /music/create-instrumental](/docs/api-mureka-v1/post-mureka-music-create-instrumental) * [POST /music/extend](/docs/api-mureka-v1/post-mureka-music-extend) * [POST /music/edit](/docs/api-mureka-v1/post-mureka-music-edit) The song's own account runs the extraction, so there is no `account` parameter. - `all_stems` is optional (default: `true`). `true` extracts all detected stems, up to 12 tracks plus MIDI, for 100 Mureka Gold. The stems Mureka finds depend on the song. Names seen so far are `bass`, `brass_and_winds`, `drums`, `guitar`, `other` (shown as FX on mureka.ai), `piano` (Keyboard on mureka.ai), `strings`, `synth` and `vocal`. `false` extracts Vocals + Instrumental only, for 20 Mureka Gold. It returns two stems, `instrumental` and `vocal`, and both have MIDI. - `async` is optional, enables fire-and-forget mode (default: `false`). When `true`, returns immediately with `201 Created` and job metadata. Poll [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) for completion status. Without `async` the call waits for the extraction to finish and returns `200` with the `completed` job. If the extraction is still running after about 4 minutes, it returns `201` with the job still `created` — keep polling [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) until it completes. A failed extraction returns the `failed` job, with its `code` as the HTTP status. A job still extracting after 10 minutes is marked `failed`. - `replyUrl` is optional, webhook URL for job status callbacks. Receives a POST request when the job ends as `completed` or `failed`. The JSON payload shape matches [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) response. If no callback arrives within about 5 minutes, poll [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) — an extraction that runs that long is finished by the poll, not by a callback. - `replyRef` is optional, custom reference string passed back in webhook callbacks. Useful for tracking jobs on your end. ##### Responses **200** **200 OK** Extraction completed. Each stem has a `.wav` and an `.mp3` link. Real response, ids shortened (a 3:15 song, 9 stems, 67 seconds). ```json { "jobid": "j1010023903143042515m-u777-a12345678901234-bot:mureka", "verb": "music/stems", "jobType": "music", "status": "completed", "created": "2026-10-10T02:39:03.143Z", "request": { "song_id": 33445566, "all_stems": true, "account": "12345678901234" }, "response": { "stems_id": "user:777-mureka:12345678901234-song:33445566-stems:55667788", "song_id": "user:777-mureka:12345678901234-song:33445566", "all_stems": true, "bpm": 120, "status": "completed", "generate_state": 1, "stems": [ { "stem_name": "bass", "wav": "https://static-cos.mureka.ai/cos-prod/song/audio/20261010/<id>/bass.wav", "mp3": "https://static-cos.mureka.ai/cos-prod/song/audio/20261010/<id>/<id>.mp3" }, { "stem_name": "brass_and_winds", "wav": "https://static-cos.mureka.ai/cos-prod/song/audio/20261010/<id>/brass_and_winds.wav", "mp3": "https://static-cos.mureka.ai/cos-prod/song/audio/20261010/<id>/<id>.mp3" }, { "stem_name": "drums", "wav": "https://static-cos.mureka.ai/cos-prod/song/audio/20261010/<id>/drums.wav", "mp3": "https://static-cos.mureka.ai/cos-prod/song/audio/20261010/<id>/<id>.mp3" }, { "stem_name": "guitar", "wav": "https://static-cos.mureka.ai/cos-prod/song/audio/20261010/<id>/guitar.wav", "mp3": "https://static-cos.mureka.ai/cos-prod/song/audio/20261010/<id>/<id>.mp3" }, { "stem_name": "other", "wav": "https://static-cos.mureka.ai/cos-prod/song/audio/20261010/<id>/other.wav", "mp3": "https://static-cos.mureka.ai/cos-prod/song/audio/20261010/<id>/<id>.mp3" }, { "stem_name": "piano", "wav": "https://static-cos.mureka.ai/cos-prod/song/audio/20261010/<id>/piano.wav", "mp3": "https://static-cos.mureka.ai/cos-prod/song/audio/20261010/<id>/<id>.mp3" }, { "stem_name": "strings", "wav": "https://static-cos.mureka.ai/cos-prod/song/audio/20261010/<id>/strings.wav", "mp3": "https://static-cos.mureka.ai/cos-prod/song/audio/20261010/<id>/<id>.mp3" }, { "stem_name": "synth", "wav": "https://static-cos.mureka.ai/cos-prod/song/audio/20261010/<id>/synth.wav", "mp3": "https://static-cos.mureka.ai/cos-prod/song/audio/20261010/<id>/<id>.mp3" }, { "stem_name": "vocal", "wav": "https://static-cos.mureka.ai/cos-prod/song/audio/20261010/<id>/vocal.wav", "mp3": "https://static-cos.mureka.ai/cos-prod/song/audio/20261010/<id>/<id>.mp3" } ] }, "updated": "2026-10-10T02:40:09.871Z" } ``` **201** **201 Created** Job created in async mode (`async: true`), or a sync call that was still extracting after about 4 minutes. The extraction is processing in the background. Use [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) to poll for completion status. ```json { "jobid": "j1009123456789475905m-u777-a12345678901234-bot:mureka", "verb": "music/stems", "jobType": "music", "status": "created", "created": "2026-10-09T12:34:56.789Z", "request": { "song_id": 33445566, "all_stems": true, "async": true, "replyUrl": "https://your-domain.com/webhook", "replyRef": "my-custom-ref-123", "account": "12345678901234" }, "response": { "stems_id": "user:777-mureka:12345678901234-song:33445566-stems:55667788", "song_id": "user:777-mureka:12345678901234-song:33445566", "all_stems": true, "status": "processing", "generate_state": 3 } } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Wrong username/password combination.", "code": 401 } ``` **412** **412 Precondition Failed** The account does not have enough Mureka Gold for the extraction (100 for all stems, 20 for Vocals + Instrumental). ```json { "error": "User balance is not enough to operate (6310)", "code": 412 } ``` **596** **596 Account Error** Returned when the account has an error state preventing API calls. ```json { "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required", "code": "REFRESH_FAILED" } ``` Possible error codes: - `ACCOUNT_ERROR` - Account has a blocking error - `REFRESH_FAILED` - Automatic token refresh failed - `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly - `SESSION_EXPIRED` - Session expired and no auto-refresh available - `COOKIE_EXPIRED` - Google cookie has expired To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts). ##### Model The stems job record, with the `stems_id` for [POST /music/stems-download](/docs/api-mureka-v1/post-mureka-music-stems-download) and, once completed, each stem's WAV and MP3 links. <details markdown="block" class="model-details"> <summary>The answer for each status (job record, error), field by field</summary> **200 / 201** Both sync and async calls return the job record. Structure matches [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) response. ```typescript { jobid: string // Job identifier verb: 'music/stems' // Job verb jobType: 'music' // Job type status: 'created' | 'completed' | 'failed' created: string // ISO 8601 timestamp updated?: string // ISO 8601 timestamp, once the job ends request: { song_id: number // Decoded Mureka id, not the user:…-song:… form all_stems: boolean account: string async?: boolean replyUrl?: string replyRef?: string } response?: { stems_id: string // Pass to POST /music/stems-download song_id: string all_stems?: boolean bpm?: number status: 'processing' | 'completed' generate_state?: number // Mureka's own state: 3 while extracting, 1 when done stems?: { // Present when completed stem_name: string // e.g. vocal, drums, bass, other wav: string | null mp3: string | null }[] } error?: string // Present when failed code?: number // Present when failed } ``` **Error** Error response structure (applies to both sync and async modes). ```typescript { jobid?: string // Present for job-related errors error: string // Error summary message code?: number // HTTP status code or error code msg?: string // Additional error message } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST https://api.useapi.net/v1/mureka/music/stems \ -d '{"song_id": "…", "all_stems": true}' ``` **JavaScript** ``` javascript const song_id = "user:777-mureka:12345678901234-song:33445566"; const all_stems = true; const apiUrl = `https://api.useapi.net/v1/mureka/music/stems`; const api_token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${api_token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ song_id, all_stems }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests song_id = "user:777-mureka:12345678901234-song:33445566" all_stems = True apiUrl = f"https://api.useapi.net/v1/mureka/music/stems" api_token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {api_token}" } body = { "song_id": song_id, "all_stems": all_stems } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-mureka-v1/post-mureka-music-video-generate === Document URL: https://useapi.net/docs/api-mureka-v1/post-mureka-music-video-generate --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> music/video-generate description: "Generate an AI music video for a Mureka song via POST music/video-generate in the useapi.net Mureka API v1 — returns video_url, cover image, and video_id." parent: Mureka API nav_order: 1400 --- ## Create an AI-generated video for your song December 2, 2024 (November 16, 2026) --- > **https://api.useapi.net/v1/mureka/music/video-generate** Make a lyrics video (mp4) for a song. Mureka makes these for songs on V9, V8, O2, V7.6 and V7.5-all, and for edited songs. A V9.5 song returns `400`, because Mureka does not make lyrics videos for V9.5 songs. ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "song_id": 123456789 } ``` - `song_id` is **required**. The `song_id` value returned by one of the following endpoints: * [GET /music](/docs/api-mureka-v1/get-mureka-music) * [POST /music/create](/docs/api-mureka-v1/post-mureka-music-create) * [POST /music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced) ##### Responses **200** **200 OK** ```json { "video_url": "https://<download link>.mp4", "video_cover_url": "https://<cover image>.png", "video_id": 112233445566 } ``` **400** **400 Bad Request** ```json { "error": "Mureka can not make a lyrics video for a V9.5 song. It works for songs made on V9, V8, O2, V7.6 or V7.5-all", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Wrong username/password combination.", "code": 401 } ``` **429** **429 Too Many Requests** * Rate limit exceeded. Endpoint called too frequently. Wait at least 3 seconds before making another call. ```json { "code": 9008, "msg": "Too frequently, please try again later." } ``` * Concurrent job limit exceeded. All job slots are taken (typically 10 concurrent generations per account). Wait at least 5 seconds before retrying. ```json { "error": "Generate multiple task exceed limit. (6323)" } ``` **596** **596 Account Error** Returned when the account has an error state preventing API calls. ```json { "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required", "code": "REFRESH_FAILED" } ``` Possible error codes: - `ACCOUNT_ERROR` - Account has a blocking error - `REFRESH_FAILED` - Automatic token refresh failed - `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly - `SESSION_EXPIRED` - Session expired and no auto-refresh available - `COOKIE_EXPIRED` - Google cookie has expired To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts). ##### Model The lyrics video's MP4 link in `video_url`, its cover image and `video_id`. <details markdown="block" class="model-details"> <summary>The lyrics video, field by field</summary> ```typescript { // TypeScript, all fields are optional video_url: string video_cover_url: string video_id: number error?: string code?: number msg?: string } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST https://api.useapi.net/v1/mureka/music/video-generate \ -d '{"song_id": …}' ``` **JavaScript** ``` javascript const song_id = 123456789; const apiUrl = `https://api.useapi.net/v1/mureka/music/video-generate`; const api_token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${api_token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ song_id }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests song_id = 123456789 apiUrl = f"https://api.useapi.net/v1/mureka/music/video-generate" api_token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {api_token}" } body = { "song_id": song_id } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-mureka-v1/post-mureka-speech-voice === Document URL: https://useapi.net/docs/api-mureka-v1/post-mureka-speech-voice --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> speech/voice description: "Clone a custom voice from an MP3 audio sample (10-60 s) via POST speech/voice in the useapi.net Mureka API v1 — use the resulting voice ID for TTS generation." parent: Mureka API nav_order: 2300 --- ## Clone voice for speech August 18, 2025 (November 16, 2026) --- This endpoint creates a custom voice clone by uploading an audio sample. The cloned voice can then be used for speech generation via [POST /speech](/docs/api-mureka-v1/post-mureka-speech). Upload clear, high-quality audio MP3 samples (10-60 seconds) for best results. Voice cloning typically takes 60-90 seconds to process. Voice cloning needs Mureka's [Premier plan](https://www.mureka.ai/subscribe). On Free or Pro the call returns `403 low vip level (6335)`. > **https://api.useapi.net/v1/mureka/speech/voice?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: audio/mpeg ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `title` is **required**. Voice title. Length: 1-50 characters. - `desc` is **required**. Voice description. Length: 1-500 characters. - `lang` is **required**. Language code for the voice. Supported values: `en` (English), `zh-Hans` (Simplified Chinese), `zh-Hant` (Traditional Chinese), `ja` (Japanese), `ko` (Korean), `es` (Spanish), `pt` (Portuguese), `de` (German), `fr` (French), `it` (Italian), `ru` (Russian). ##### Request Body Binary audio file content. Supported format: MP3 only (`audio/mpeg` content type). Recommended: 10-60 seconds of clear speech for optimal cloning quality. ##### Responses **200** **200 OK** ```json { "id": 12345678901234, "user_id": 23456789012345, "title": "Custom Voice", "cover": "https://static-cos.mureka.ai/cos-prod/res/cover/….png", "mp3_url": "https://static-cos.mureka.ai/cos-prod/tts-v2/….mp3", "language": "en", "created_at": 1755483687, "description": "Custom cloned voice description", "duration_milliseconds": 12520, "machine_audit_state": 1 } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **596** **596 Account Error** Returned when the account has an error state preventing API calls. ```json { "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required", "code": "REFRESH_FAILED" } ``` Possible error codes: - `ACCOUNT_ERROR` - Account has a blocking error - `REFRESH_FAILED` - Automatic token refresh failed - `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly - `SESSION_EXPIRED` - Session expired and no auto-refresh available - `COOKIE_EXPIRED` - Google cookie has expired To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts). ##### Model The cloned voice, with its `id`, title, language and preview MP3, ready for [POST /speech](/docs/api-mureka-v1/post-mureka-speech). <details markdown="block" class="model-details"> <summary>The cloned voice, field by field</summary> ```typescript { // TypeScript, all fields are optional id: number user_id: number title: string cover: string mp3_url: string language: string created_at: number description: string duration_milliseconds: number machine_audit_state: number } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/mureka/speech/voice?title=CustomVoice&desc=MyVoiceDescription&lang=en" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" \ -H "Content-Type: audio/mpeg" \ --data-binary @voice_sample.mp3 ``` **JavaScript** ``` javascript const token = "API token"; const title = "Custom Voice"; const desc = "My voice description"; const lang = "en"; const fileInput = document.querySelector('input[type="file"]'); const file = fileInput.files[0]; const apiUrl = `https://api.useapi.net/v1/mureka/speech/voice?title=${title}&desc=${desc}&lang=${lang}`; const response = await fetch(apiUrl, { method: "POST", headers: { "Authorization": `Bearer ${token}`, "Content-Type": file.type, }, body: file, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" title = "Custom Voice" desc = "My voice description" lang = "en" apiUrl = f"https://api.useapi.net/v1/mureka/speech/voice?title={title}&desc={desc}&lang={lang}" headers = { "Authorization" : f"Bearer {token}", "Content-Type": "audio/mpeg" } with open('voice_sample.mp3', 'rb') as audio_file: response = requests.post(apiUrl, headers=headers, data=audio_file.read()) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-mureka-v1/post-mureka-speech === Document URL: https://useapi.net/docs/api-mureka-v1/post-mureka-speech --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> speech description: "Generate Mureka TTS audio from text via POST speech in the useapi.net Mureka API v1 — supports preset and cloned voices, plus multi-speaker conversation mode." parent: Mureka API nav_order: 2150 --- ## Generate speech August 18, 2025 (November 16, 2026) --- This endpoint generates high-quality speech from text using Mureka's advanced text-to-speech technology. You can use either predefined voices or custom cloned voices created via [POST /speech/voice](/docs/api-mureka-v1/post-mureka-speech-voice). For multi-speaker conversations, use the `conversation` parameter with different voice IDs. Speech generation typically takes 20-90 seconds depending on text length. Unlike music generation endpoints, this endpoint has no rate limits or concurrent generation restrictions, allowing unlimited parallel speech generations per account. > **https://api.useapi.net/v1/mureka/speech** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body - `account` is optional when only one [account](/docs/api-mureka-v1/get-mureka-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `title` is optional string. Maximum length is 500 characters. - `text` is required string when not using `conversation`. Must be used together with `voice_id`. Maximum text length is 5000 characters. - `voice_id` is required number when not using `conversation`. Must be used together with `text`. Get available voice IDs from [GET /speech/voices](/docs/api-mureka-v1/get-mureka-speech-voices). To create a cloned voice, first use [POST /speech/voice](/docs/api-mureka-v1/post-mureka-speech-voice) to upload an audio sample and clone the voice. - `conversation` is optional JSON string. Alternative to `text` and `voice_id`. Must be a JSON string array of objects with `voice_id` (number) and `text` (string) fields. Cannot be used together with `text` and `voice_id`. Total text length across all conversation items cannot exceed 5000 characters. Example `conversation` JSON: ```json [ {"voice_id": 12345, "text": "Hello, welcome to our service!"}, {"voice_id": 67890, "text": "Thank you for choosing us today."}, {"voice_id": 12345, "text": "Is there anything I can help you with?"} ] ``` - `async` is optional, enables fire-and-forget mode (default: `false`). When `true`, returns immediately with `201 Created` and job metadata. Poll [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) for completion status. Useful for avoiding long request timeouts since speech generation takes 20-90 seconds. - `replyUrl` is optional, webhook URL for job status callbacks. Receives a POST request when the job ends as `completed` or `failed`. The JSON payload shape matches [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) response. - `replyRef` is optional, custom reference string passed back in webhook callbacks. Useful for tracking jobs on your end. ##### Responses **200** **200 OK** ```json { "jobid": "j0121061456745673364t-u777-a12345678901234-bot:mureka", "title": "Sample Speech Title", "preview": "This is a preview of the generated speech content that demonstrates the text-to-speech capabilities.", "cover": "https://static-cos.mureka.ai/cos-prod/res/cover/….png", "mp3_url": "https://static-cos.mureka.ai/cos-prod/tts-v2/….mp3", "id": 12345678901234, "duration_milliseconds": 15000, "audio_quality": 2, "state": 3 } ``` **201** **201 Created** Job created in async mode (`async: true`). Speech generation is processing in the background. Use [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) to poll for completion status. ```json { "jobid": "j0121061456745673364t-u777-a12345678901234-bot:mureka", "verb": "speech", "jobType": "tts", "status": "created", "created": "2026-01-20T12:34:56.789Z", "request": { "account": "12345678901234", "text": "Hello, this is a sample text for speech generation.", "voice_id": 67890, "async": true, "replyUrl": "https://your-domain.com/webhook", "replyRef": "my-custom-ref-123" } } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **596** **596 Account Error** Returned when the account has an error state preventing API calls. ```json { "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required", "code": "REFRESH_FAILED" } ``` Possible error codes: - `ACCOUNT_ERROR` - Account has a blocking error - `REFRESH_FAILED` - Automatic token refresh failed - `REFRESH_IN_PROGRESS` - Token refresh already in progress, retry shortly - `SESSION_EXPIRED` - Session expired and no auto-refresh available - `COOKIE_EXPIRED` - Google cookie has expired To resolve, update your account configuration via [POST /accounts](/docs/api-mureka-v1/post-mureka-accounts). ##### Model Sync mode answers with the finished speech and its MP3 link, and async mode with the new job to poll with [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid). <details markdown="block" class="model-details"> <summary>The answer for each status (sync speech, async job, error), field by field</summary> **200 OK (Sync)** Speech generation completed. Returns full audio data with MP3 URL. ```typescript { jobid: string // Job identifier (for later lookup) title: string preview: string cover: string mp3_url: string id: number duration_milliseconds: number audio_quality: number state: number } ``` **201 Created (Async)** Job created and processing in background. Structure matches [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) response. ```typescript { jobid: string // Job identifier verb: 'speech' // Job verb jobType: 'tts' // Job type status: 'created' // Job status created: string // ISO 8601 timestamp request: { account?: string title?: string text?: string voice_id?: number conversation?: string async: true replyUrl?: string replyRef?: string } } ``` **Error** Error response structure (applies to both sync and async modes). ```typescript { jobid?: string // Present for job-related errors error: string // Error summary message code?: number // HTTP status code or error code rawData?: string // Raw error data (if available) } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/mureka/speech" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" \ -H "Content-Type: application/json" \ -d '{ "text": "Hello, this is a sample text for speech generation.", "voice_id": 67890 }' ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = "https://api.useapi.net/v1/mureka/speech"; const response = await fetch(apiUrl, { method: "POST", headers: { "Authorization": `Bearer ${token}`, "Content-Type": "application/json", }, body: JSON.stringify({ text: "Hello, this is a sample text for speech generation.", voice_id: 67890 }), }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" apiUrl = "https://api.useapi.net/v1/mureka/speech" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } data = { "text": "Hello, this is a sample text for speech generation.", "voice_id": 67890 } response = requests.post(apiUrl, headers=headers, json=data) print(response, response.json()) ``` === URL: https://useapi.net/docs/start-here/setup-muse === Document URL: https://useapi.net/docs/start-here/setup-muse --- layout: default title: Setup Muse description: "How to add a Meta Muse (muse.ai) account to the useapi.net Muse API with its email and password, what the login-code email means, and Meta's security check." parent: Start Here nav_order: 210 permalink: /docs/start-here/setup-muse --- # Setup Muse October 12, 2026 (October 30, 2026) ## Table of contents Approximately 5 minutes to complete setup steps. --- > This is the setup guide for [Muse API](/docs/api-muse-v1). A [Muse](https://muse.ai) account and a [useapi.net subscription](/docs/subscription) are required for the API to work. Add a Muse account with its email and password. The API signs in once and keeps the account signed in from then on. ### Before you start - Muse is available in the US, Canada, [Japan](https://about.fb.com/ja/news/2026/10/muse-personal-ai-agent-launches-in-japan/) and [Singapore](https://about.fb.com/news/2026/10/muse-is-now-available-in-singapore-the-worlds-first-personal-ai-agent-built-for-everyone/) (as of October 30, 2026), so create the account in one of them. Once it is added, you can call the API from anywhere. - Finish Muse's onboarding at [muse.ai](https://muse.ai), including Meta's age check, and create one image there. - The account must have email + password sign-in, because the API signs in with the email and password. A Meta account that signs in only with an emailed code has no password yet: create one in [Meta Accounts Center](https://accountscenter.meta.com/password_and_security/) (Password and security), then add the account here. Without a password the add is refused with `400`. - Use the account only for the API, with no other automation tools on it. Opening it at muse.ai in a browser is fine, but only from the US, Canada, Japan or Singapore (the regions Muse officially supports), or through a VPN in one of them: Meta can switch off video for an account it sees used from elsewhere. ![The Muse sign-in page at muse.ai](/assets/images/muse-setup-1.png) ### Add the account <script> async function apiAddAccountMuse() { data = { method: 'POST', headers: { 'Authorization': `Bearer ${document.getElementById('post-accounts-Muse-api_token').value}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ email: document.getElementById('post-accounts-Muse-email')?.value?.trim(), password: document.getElementById('post-accounts-Muse-password')?.value, maxJobs: document.getElementById('post-accounts-Muse-maxJobs')?.value ? Number(document.getElementById('post-accounts-Muse-maxJobs').value) : undefined }) }; await apiExecute(`https://api.useapi.net/v1/muse/accounts`, 'post-accounts-Muse', data); } </script> <form id="post-accounts-Muse" onsubmit="apiAddAccountMuse(); return false;" class="input-form"> <div class="input-field"> <div class="input-field-row"> <label for="post-accounts-Muse-api_token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="post-accounts-Muse-api_token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> <label for="post-accounts-Muse-email"><span>email (the Muse account)</span> <input id="post-accounts-Muse-email" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> <label for="post-accounts-Muse-password"><span>password</span> <input id="post-accounts-Muse-password" type="password" class="input-element" required aria-required="true" autocomplete="off"> </label> <label for="post-accounts-Muse-maxJobs"><span>maxJobs (optional, 1 to 50, default 10: jobs the account runs at the same time)</span> <input id="post-accounts-Muse-maxJobs" type="number" min="1" max="50" step="1" class="input-element"> </label> </div> <button id="post-accounts-Muse-button" class="btn btn-primary fs-3" type="submit">Go</button> </div> </form> <div id="post-accounts-Muse-response" class="response-placeholder visible-false"></div> A new account answers `201`, a re-added one `200`, with `health: "OK"`, `sessionExpiresAt` and `quota`. Each account runs 10 jobs at a time unless you set `maxJobs` (1 to 50) above. Accounts added earlier keep their stored value until you change it. To change it later, post the email with a new `maxJobs` and no password to [POST /accounts](/docs/api-muse-v1/post-muse-accounts). ### What to expect - The API renews the session itself: before the 30-day session expires, and whenever Muse asks for a new sign-in. You never re-add the account for that. - Muse emails the account a login code on each sign-in. Nothing needs to be done with it. - Re-adding the account with the same password reuses its live session, so it does not sign in again. - [Chat](/docs/api-muse-v1/post-muse-chats) can act on the apps connected to the Muse account, such as email or calendar. With Muse's default setting, some actions, like sending an email, happen without asking. To make Muse ask before each one, set `connectors` to `always_ask` with [POST /accounts/`email`/permissions](/docs/api-muse-v1/post-muse-accounts-email-permissions). Connect only the apps you want the API to use. ### If the account needs attention The API pauses an account it cannot use, emails you once, and answers `596` with the reason, also shown in `health` on [GET /accounts](/docs/api-muse-v1/get-muse-accounts): - Meta asks for a security check, usually after a sign-in from a new place. Sign in at [muse.ai](https://muse.ai) in a browser, complete the check, then add the account again with the same email and password. - Muse refused to sign in when the session was renewed, usually because the password changed. Add the account again with the current password. Temporary problems never pause an account. They answer `503`, and a retry works. ### Usage limits Muse meters each account weekly. [GET /accounts/`email`](/docs/api-muse-v1/get-muse-accounts-email) returns the plan and usage in `quota`: `tier`, `percentUsed`, `resetsAt` and `quotaStatus`. | Plan | Price | Weekly allowance | |---|---|---| | Free | $0 | not published | | Power | $20/month | 500 million Muse tokens | | Maximum | $100/month | 3 billion Muse tokens | Source: Meta, [About Muse subscriptions](https://www.meta.com/help/subscriptions/1021145227643680/), October 2026. Availability can differ by region. - On the free plan, a video used 2 to 3 percent of the weekly allowance in our tests and an image 0 to 1 percent. Meta does not publish per-job token costs. - The allowance resets at `resetsAt`. Once it is used up, new jobs go to your other accounts, and a job pinned to the account answers `412`. - Tokens bought or granted on top of the plan show on muse.ai as Additional tokens and never expire. The API keeps sending jobs to an account that has top-up left after its weekly allowance is used up. `topupLabel` gives the top-up as muse.ai words it, for example `0% used (1B tokens left)`. `topupBalance` (left) and `topupTotal` (bought) are Muse's own counters, not token counts: an account with 1B tokens left reads `40000000`. - Muse also limits the videos an account makes over the last 24 hours, apart from the weekly allowance. When it says the limit is reached, video jobs skip the account for an hour. See [Video limit](/docs/api-muse-v1/post-muse-jobs-video#video-limit). === URL: https://useapi.net/docs/api-muse-v1/chat-streaming-guide === Document URL: https://useapi.net/docs/api-muse-v1/chat-streaming-guide --- layout: default title: Chat Streaming Guide nav_icon: activity description: "Chat with the Muse agent over Server-Sent Events in the useapi.net Muse API: start a chat, read the stream with fetch(), send mid-answer, resume with Last-Event-ID." parent: Muse API nav_order: 10 permalink: /docs/api-muse-v1/chat-streaming-guide --- ## Chat Streaming Guide October 12, 2026 (November 20, 2026) --- This guide shows how to hold a two-way chat with [Muse](https://muse.ai), Meta's AI agent, through the useapi.net Muse API: send messages, read the answer live over [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) (SSE), and pick up again after a disconnect. To see it working first, open the [Live Demo](/docs/api-muse-v1/demo). A chat reaches the whole Muse agent: it talks, researches the web, writes and runs code, uses the apps connected to the Muse account, and makes images and videos. Each chat is a normal Muse chat, so it also shows in the muse.ai app. ## How a chat works 1. Start the chat with [POST /chats](/docs/api-muse-v1/post-muse-chats). It answers `201` with a `chatId`. 2. Open [GET /chats/`chatId`/stream](/docs/api-muse-v1/get-muse-chats-chatId-stream). The answer arrives as events: the agent's text in pieces, what it is doing, the files it makes, and `turn.done` when the answer ends. 3. Send the next message with [POST /chats/`chatId`/messages](/docs/api-muse-v1/post-muse-chats-chatId-messages). Sending does not need an open stream: the stream only lets you watch the reply live. Without one, read the reply with [GET /chats/`chatId`](/docs/api-muse-v1/get-muse-chats-chatId), or open the stream later and it is replayed. You can also send while Muse is still answering: it takes the new message into the answer it is working on. 4. Stop an answer with [POST /chats/`chatId`/cancel](/docs/api-muse-v1/post-muse-chats-chatId-cancel). One stream follows the whole chat, across every answer, so keep it open for as long as the conversation goes on. Past chats are listed by [GET /chats](/docs/api-muse-v1/get-muse-chats) and read as JSON with [GET /chats/`chatId`](/docs/api-muse-v1/get-muse-chats-chatId). ## Reading the stream The stream needs the `Authorization` header. The browser's `EventSource` cannot send it, so read the stream with `fetch()`, or with any HTTP client that can read a response as it arrives. The response is `text/event-stream`. Events are separated by a blank line. Each one has a `data:` line with one JSON object, and some also have an `id:` line: ``` data: {"event":"initialized","chatId":"c-u12345-email:example@gmail.com-chat:272b73f4-6fcb-42c2-9ec7-75cc0c020940-bot:muse","email":"example@gmail.com","after":0} data: {"event":"status","status":"running"} id: 1263 data: {"event":"message","messageId":"389bfe1b-d8a0-47ed-9b11-d9269a8ed656","text":"Write a 300-word story about the sea.","files":[]} data: {"event":"activity","text":"is responding"} data: {"event":"text","messageId":"assistant-msg-c736fee5-9539-4ac0-8d59-30afb00a10d1","text":"The tide came in"} data: {"event":"text","messageId":"assistant-msg-c736fee5-9539-4ac0-8d59-30afb00a10d1","text":" like an"} id: 1265 data: {"event":"message.done","messageId":"assistant-msg-c736fee5-9539-4ac0-8d59-30afb00a10d1"} data: {"event":"status","status":"completed"} data: {"event":"turn.done","status":"completed","files":[]} ``` ## Events | Event | Meaning | When | |---|---|---| | `initialized` | The stream is open. | Always first. | | `replayed` | The replay of earlier events is done: everything after it is live. | Once, after the replay. | | `message` | A message you sent, with its media files as asset ids and other files as workspace paths. | When Muse receives it, also mid-answer. | | `activity` | What the agent is doing, for example `Generating image`. | During an answer. | | `text` | A piece of the agent's message, or with `full: true` the whole message. | As the agent writes. | | `message.done` | The agent's message with this `messageId` is complete. | At the end of each agent message. | | `widget` | An interactive card in the agent's message: quick-reply choices (`options`), a chart or table (`html`, shown only in a sandboxed iframe), a web app the agent built (`space_build_completed`, with its `assetId`), a link to open on Muse's own site, for example to connect Google Calendar (`internal_link_action_card`, with its `url`), or another kind (`data`, show its `fallbackText`). See [Answer a widget](/docs/api-muse-v1/post-muse-chats-chatId-widgets-widgetId). | With the agent's message. | | `file` | A file the agent made or showed, as an `assetId`: an image, video or audio file, or a document. | As soon as the file is ready. | | `reaction` | The reactions on a message changed, for example the agent reacted with 👍. | When a reaction is added or removed. | | `browser` | The agent's web browser: its status, the open page, who has control, and whether it can be watched live. See the [Live Browser Guide](/docs/api-muse-v1/live-browser-guide). | When the agent opens a browser, and each time it changes. | | `status` | The chat's state from Muse, for example `running` or `completed`. | When it changes. | | `approval` | The agent asks for permission before an action. The answer pauses until you reply. | When Muse asks. | | `approval.resolved` | A permission request ended: approved, denied or timed out. | Once per request. | | `turn.done` | The answer ended, `completed` or `interrupted`, with all its files. | At the end of each answer. | | `error` | The connection to Muse broke. The stream closes. | On a failure. | | `keepalive` | Nothing to report. | Every 15 seconds. | | `idle` | Nothing happened for 10 minutes. The stream closes. | After 10 quiet minutes. | | `reconnect` | The connection reached its 60-minute limit. The stream closes. | After 60 minutes. | ### Event model ```typescript type StreamEvent = // TypeScript | { event: 'initialized', chatId: string, email: string, after: number } | { event: 'replayed', lastEventId: number } // once: the replay is done, everything after is live | { event: 'message', messageId: string, text: string, files: string[] } // your message: media as asset ids, other files as workspace paths | { event: 'activity', text: string } // e.g. "is working", "Generating image" | { event: 'text', messageId: string, text: string, full?: true } // full: the whole text, replaces earlier pieces | { event: 'message.done', messageId: string } | { event: 'widget', messageId?: string, widgetId: string, // an interactive card in the agent's message kind: string, text: string | null, fallbackText: string | null, // show fallbackText for a kind you can't render options?: string[], // kind option: quick replies, answer with POST /chats/{chatId}/widgets/{widgetId} html?: string, // kind html: a card to show only in a sandboxed iframe name?: string, summary?: string, status?: string, // kind space_build_completed: a web app the agent built assetId?: string | null, // and its asset id (GET /assets/{assetId}) title?: string, subtitle?: string, linkType?: string, // kind internal_link_action_card: something to do on Muse's site, url?: string | null, connectorId?: string, imageUrl?: string, // opened by the account's owner signed in to Muse data?: Record<string, unknown> } // any other kind: Muse's widget data as it is | { event: 'file', messageId?: string, assetId: string, type: 'image' | 'video' | 'audio', mime: string, bytes: number, origin: 'generated' | 'made', // made: by the agent's own tools. Once per answer: a later answer may send the same file again podcastId?: string } // audio of a podcast: the podcast's asset id (its cover: GET /assets/{podcastId}?part=cover) | { event: 'file', messageId?: string, assetId: string, // a document the agent showed (md, csv, pdf, pptx…) type: 'document', mime: string, bytes: number, origin: string } | { event: 'browser' } & Browser // the agent's browser changed, see Browser below | { event: 'reaction', messageId: string, reactions: string[] } // the message's reactions now, e.g. ["👍"] | { event: 'status', status: string } // e.g. running, pending_user_confirmation (this chat waits for its own approval), user_confirmed / user_denied (after your answer), completed | { event: 'approval' // the agent asks for permission approvalId: string title: string | null // e.g. "Share info with deb.nodesource.com" question: string | null // e.g. "Allow Muse to share information with deb.nodesource.com?" details: { label: string, value: string }[] // e.g. Host, Grants, Method options: { decision: string, label: string }[] // e.g. allow_once "Allow once", deny "Deny" expires: string | null // ISO 8601, unanswered requests time out then } | { event: 'approval.resolved', approvalId: string, // once, when one of this chat's requests ends status: string, decision: string | null } // e.g. approved / allow_once, denied / deny, timed_out | { event: 'turn.done', status: 'completed' | 'interrupted', files: { assetId: string, type: 'image' | 'video' | 'audio', mime: string, bytes: number }[] } | { event: 'error', code: number, message: string } // reconnect with Last-Event-ID | { event: 'keepalive' } // every 15 seconds | { event: 'idle', message: string } // 10 quiet minutes, the stream closes | { event: 'reconnect', message: string } // 60 minutes reached, the stream closes ``` ```typescript type Browser = { // TypeScript: the agent's browser in a chat taskId: string // the browser's id in this chat, for /chats/{chatId}/browser/{taskId} status: string | null // e.g. Queued, Running, Completed, User controlled displayState: string | null // e.g. starting, working, completed, paused stepTitle: string | null // what the agent is doing, e.g. "Opening example page" steps: number | null // how many steps the agent took site: string | null // e.g. example.com url: string | null // the open page tabTitle: string | null // the open page's title controlOwner: string | null // agent or user previewAvailable: boolean // true: the browser is open and can be watched with a viewer link parkedExpiresAt: string | null // ISO 8601: the browser stays open until then after the agent's answer ended: boolean // true: the browser is closed for good updated: string | null // ISO 8601 } ``` ### Text The agent's text arrives in pieces. Join the pieces with the same `messageId` in order. An answer can hold several agent messages, each with its own `messageId`. A `text` event with `full: true` holds the whole text of a message. Show it in place of any pieces you have for that `messageId`. It comes when the stream replays a finished message, for example after a reconnect. A link the agent presents on its own, such as a share link it created, also arrives this way: as an agent message whose text is the link, a `text` event with `full: true` followed by `message.done`. ### Files Each file the agent makes arrives as a `file` event with an `assetId`, its `type`, `mime` and `bytes`, once per answer. Besides images, videos and audio, `type` can be `document`, for a document the agent showed, such as Markdown, CSV or a presentation. Audio of a podcast episode also has a `podcastId`: [GET /assets/`podcastId`](/docs/api-muse-v1/get-muse-assets-assetId) `?part=cover` gives its cover. A web app the agent built arrives as a `widget` of `kind` `space_build_completed` with its `assetId`. When the agent shows the same file again in a later answer, for example after rewriting it in place, the `file` event comes again under that answer. If you keep a list of files, de-duplicate it by `assetId`. Download it with [GET /assets/`assetId`](/docs/api-muse-v1/get-muse-assets-assetId), or pass it in `files` of the next message or as an input of a [job](/docs/api-muse-v1/post-muse-jobs-image). `turn.done` lists every image, video and audio file of the answer again. Your own files go in with `files` on [POST /chats](/docs/api-muse-v1/post-muse-chats#request-body) and the next messages: media as asset ids from [POST /assets](/docs/api-muse-v1/post-muse-assets), and documents, data or code as workspace paths from [POST /files](/docs/api-muse-v1/post-muse-files). For example, write `workspace/your_files/report.pdf`, then send `"files": ["workspace/your_files/report.pdf"]` with the message `Summarize file_1`. ### Reactions The agent reacts to messages too, for example with 👍 to yours. A `reaction` event names the `messageId` and its whole set of `reactions` now, so replace what you show for that message. React yourself with [POST /chats/`chatId`/messages/`messageId`/reactions](/docs/api-muse-v1/post-muse-chats-chatId-messages-messageId-reactions). ### The agent's browser When the agent works in its own web browser, a `browser` event comes with the browser's `taskId`, and again each time the browser changes. Keep the latest event per `taskId`. While `previewAvailable` is `true`, you can watch the browser live or take control of it, see the [Live Browser Guide](/docs/api-muse-v1/live-browser-guide). ### Approvals Before some actions, for example sending information to a website while it runs code, the agent asks for your permission: 1. The stream shows a `status` event `pending_user_confirmation` and an `approval` event with the request's `approvalId`, `title`, `question`, `details`, `options` and `expires`. The answer is paused, and no `turn.done` comes while the request waits. `pending_user_confirmation` always means this chat waits for one of its own requests, never another chat's. 2. Send one of the `options` decisions to [POST /chats/`chatId`/approvals/`approvalId`](/docs/api-muse-v1/post-muse-chats-chatId-approvals-approvalId): `allow_once` for this one request, `allow_always` to allow the site from now on for the whole Muse account, or `deny`. 3. The stream shows `approval.resolved` with the result, and a `status` event such as `user_confirmed` or `user_denied`. The answer goes on. After `deny` the agent continues without the action. A request that is not answered by `expires` ends as timed out. Open requests are also listed in `pendingApprovals` of [GET /chats/`chatId`](/docs/api-muse-v1/get-muse-chats-chatId), and the stream sends them again after a reconnect: key them by `approvalId`. ## Resuming after a disconnect Keep the last `id` you received. An `id` appears only on events that close a complete part of the chat, so everything up to it has arrived. To resume, open the stream again with that value in the `Last-Event-ID` header, or as `?after=`. The stream replays what you missed, then goes on live: your messages, each finished agent message as one `text` event with `full: true`, and its files. A fresh stream (no `Last-Event-ID`) replays the newest 1000 chat events. Older messages are in [GET /chats/`chatId`](/docs/api-muse-v1/get-muse-chats-chatId) with `before`. A `replayed` event marks where the replay ends and live events begin: its `lastEventId` is the last id sent so far, or the one you resumed from. A stream opened after an answer ended replays that answer and then a `status` event such as `completed`, without a `turn.done`. Reconnect with `Last-Event-ID` after `error` and after any network error. After `idle` (10 quiet minutes) or `reconnect` (60 minutes), reconnect with `Last-Event-ID` if you still want live updates, for example while the chat is on screen, or else when you next need it. Either way the stream resumes exactly where it left off, with no history reload. ## Limits - Each account can have about 50 streams open at the same time. More answer `429`. The count is approximate: a connection you close is noticed within about a minute, so a quick burst of reconnects can briefly count more streams than are really open. Keep one stream per chat. [GET /chats/streams](/docs/api-muse-v1/get-muse-chats-streams) shows the count. Close streams you no longer read. - A stream that fails shows in your [usage stats](/docs/account-management/get-account-stats) (`bot=muse`) as model `muse-stream`, with status `failed` or `dropped`. Streams that open and run normally do not appear there. To spot a reconnect loop, watch the count on [GET /chats/streams](/docs/api-muse-v1/get-muse-chats-streams). - Chat does not use the account's `maxJobs`, which limits jobs only. - Chat uses the account's weekly [Muse allowance](/docs/start-here/setup-muse#usage-limits), like jobs do. ## Examples Each example starts a chat, prints the answer as it streams, and reconnects with `Last-Event-ID` when the connection drops. **JavaScript** ``` javascript const token = "API token"; const api = "https://api.useapi.net/v1/muse"; const start = await fetch(`${api}/chats`, { method: "POST", headers: { "Authorization": `Bearer ${token}`, "Content-Type": "application/json" }, body: JSON.stringify({ message: "Write a short poem about the sea, then make one image for it." }), }); const { chatId } = await start.json(); let lastId = 0; const texts = new Map(); // messageId → text so far // Reads the stream until the answer ends ("done"), or the stream closes ("again") const follow = async () => { const response = await fetch(`${api}/chats/${encodeURIComponent(chatId)}/stream`, { headers: { "Authorization": `Bearer ${token}`, "Last-Event-ID": String(lastId) }, }); if (!response.ok) throw new Error(`${response.status} ${await response.text()}`); const reader = response.body.getReader(); const decoder = new TextDecoder(); let buffer = ""; for (;;) { const { done, value } = await reader.read(); if (done) return "again"; buffer += decoder.decode(value, { stream: true }); const blocks = buffer.split("\n\n"); buffer = blocks.pop(); for (const block of blocks) { const lines = block.split("\n"); const id = lines.find(l => l.startsWith("id:")); const data = lines.find(l => l.startsWith("data:")); if (id) lastId = Number(id.slice(3)); if (!data) continue; const e = JSON.parse(data.slice(5)); switch (e.event) { case "text": texts.set(e.messageId, e.full ? e.text : (texts.get(e.messageId) ?? "") + e.text); if (!e.full) process.stdout.write(e.text); break; case "message.done": console.log(); break; case "file": console.log("file:", e.type, e.assetId); break; case "turn.done": console.log("answer done:", e.status, e.files.length, "file(s)"); await reader.cancel(); return "done"; case "idle": return "done"; case "error": case "reconnect": return "again"; } } } }; for (;;) { const result = await follow().catch(err => (console.log("dropped:", err.message), "again")); if (result === "done") break; await new Promise(r => setTimeout(r, 2000)); } ``` **Python** ``` python import json, time, requests from urllib.parse import quote token = "API token" api = "https://api.useapi.net/v1/muse" start = requests.post(f"{api}/chats", headers={"Authorization": f"Bearer {token}"}, json={"message": "Write a short poem about the sea, then make one image for it."}) chat_id = start.json()["chatId"] last_id = 0 def follow(): """Reads the stream until the answer ends ("done"), or the stream closes ("again").""" global last_id url = f"{api}/chats/{quote(chat_id, safe='')}/stream" headers = {"Authorization": f"Bearer {token}", "Last-Event-ID": str(last_id)} with requests.get(url, headers=headers, stream=True, timeout=(10, 60)) as response: response.raise_for_status() for line in response.iter_lines(decode_unicode=True): if line.startswith("id:"): last_id = int(line[3:]) continue if not line.startswith("data:"): continue e = json.loads(line[5:]) kind = e["event"] if kind == "text": print(e["text"], end="" if not e.get("full") else "\n", flush=True) elif kind == "message.done": print() elif kind == "file": print("file:", e["type"], e["assetId"]) elif kind == "turn.done": print("answer done:", e["status"], len(e["files"]), "file(s)") return "done" elif kind == "idle": return "done" elif kind in ("error", "reconnect"): return "again" return "again" while True: try: if follow() == "done": break except requests.RequestException as err: print("dropped:", err) time.sleep(2) ``` **Curl** ``` bash CHATID="c-u12345-email:example@gmail.com-chat:272b73f4-6fcb-42c2-9ec7-75cc0c020940-bot:muse" curl -N -H "Authorization: Bearer …" \ -H "Last-Event-ID: 1265" \ "https://api.useapi.net/v1/muse/chats/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$CHATID")/stream" ``` The `-N` flag turns off buffering, so events print as they arrive. Call [POST /chats/`chatId`/messages](/docs/api-muse-v1/post-muse-chats-chatId-messages) from anywhere in your code, with or without a stream open. When a stream is open, the new message arrives on it as a `message` event, followed by the answer. ## Chat or jobs? Use [POST /jobs/image](/docs/api-muse-v1/post-muse-jobs-image) and [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video) when you want one image or one video per call, with a job record, sync or async answers and `replyUrl` webhooks. Use chat when you want a conversation, the agent's own words as it works, follow-up edits in the same context, or anything beyond images and videos. Both use the same asset ids, so files move freely between them. === URL: https://useapi.net/docs/api-muse-v1/delete-muse-accounts-email-permissions-permissionId === Document URL: https://useapi.net/docs/api-muse-v1/delete-muse-accounts-email-permissions-permissionId --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> accounts/`email`/permissions/`permissionId` description: "Remove one Muse agent permission rule via DELETE accounts/email/permissions/permissionId in the useapi.net Muse API. Without it, the account default applies again." parent: Muse API nav_order: 125 permalink: /docs/api-muse-v1/delete-muse-accounts-email-permissions-permissionId --- ## Delete a permission rule October 12, 2026 (November 16, 2026) --- Remove one standing rule of the Muse agent. Without the rule, the account's default setting applies again, see [GET /accounts/`email`/permissions](/docs/api-muse-v1/get-muse-accounts-email-permissions). Rules are created when an approval is answered with `allow_always`, so this is how you take an "Always allow this site" back. > **https://api.useapi.net/v1/muse/accounts/`email`/permissions/`permissionId`** - `email` is the email of an added account, URL-encoded in the path. - `permissionId` is the rule's `permissionId` from [GET /accounts/`email`/permissions](/docs/api-muse-v1/get-muse-accounts-email-permissions), URL-encoded in the path (it contains `:`). ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** ```json { "email": "example@gmail.com", "permissionId": "network_rule:hitl_domain_allow_nodesource_com_afdc93c7", "deleted": true } ``` **401** **401 Unauthorized** — Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **404** **404 Not Found** — the rule is not there (already removed), or the account named by `email` is not added. ```json { "error": "Permission not found", "code": 404 } ``` **502** **502 Bad Gateway** — Muse did not change the rule. Retry. **503** **503 Service Unavailable** — Muse could not be read right now. Retry shortly. ```json { "error": "Muse could not be read right now (…), please retry", "code": 503 } ``` **596** **596 Account Error** The account needs your attention, and it is paused until you add it again. You receive an email when this happens. There are three causes. Meta asks for a security check on the account. Sign in once at [muse.ai](https://muse.ai) in a browser, complete the check, then add the account again with [POST /accounts](/docs/api-muse-v1/post-muse-accounts) using the same email and password. The API keeps using its session, so no new sign-in is needed. ```json { "error": "Account example@gmail.com: Meta asks for a security check on account example@gmail.com (\"This account must complete a security checkpoint on the web\"). Sign in once at https://muse.ai in a browser, complete the check, then add the account again with POST /accounts", "code": 596 } ``` Or Muse refused to sign the account in again when its session needed renewing, most often because the password was changed. Add the account again with the current password. ```json { "error": "Account example@gmail.com: Muse refused to sign in account example@gmail.com (…). Update its password with POST /accounts, or sign in at https://muse.ai to clear the block, then re-add it", "code": 596 } ``` Or Muse disabled the account's computer and refuses to start it again. Sign in at [muse.ai](https://muse.ai) in a browser to see why, and ask Muse support to restore it with the form Muse shows there. Add the account again only after Muse has restored it. ```json { "error": "Account example@gmail.com: Muse has disabled the computer of account example@gmail.com (\"VM wake unavailable\"). Sign in at https://muse.ai in a browser to see why and contact Muse support there, then add the account again with POST /accounts", "code": 596 } ``` ##### Model A successful delete answers with the account `email`, the `permissionId` and `deleted: true`. <details markdown="block" class="model-details"> <summary>The removed rule, field by field</summary> ```typescript { // TypeScript, all fields are optional email: string permissionId: string deleted: true error?: string // errors only code?: number // errors only } ``` </details> ##### Examples **Curl** ``` bash EMAIL="example@gmail.com" curl -X DELETE -H "Authorization: Bearer …" \ "https://api.useapi.net/v1/muse/accounts/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$EMAIL")/permissions/network_rule%3Ahitl_domain_allow_nodesource_com_afdc93c7" ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously added account email"; const permissionId = "permissionId from GET /accounts/{email}/permissions"; const apiUrl = `https://api.useapi.net/v1/muse/accounts/${encodeURIComponent(email)}/permissions/${encodeURIComponent(permissionId)}`; const response = await fetch(apiUrl, { method: "DELETE", headers: { "Authorization": `Bearer ${token}`, } }); console.log("response", response.status, await response.json()); ``` **Python** ``` python import requests from urllib.parse import quote token = "API token" email = "Previously added account email" permissionId = "permissionId from GET /accounts/{email}/permissions" apiUrl = f"https://api.useapi.net/v1/muse/accounts/{quote(email, safe='')}/permissions/{quote(permissionId, safe='')}" headers = { "Authorization" : f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-muse-v1/delete-muse-accounts-email === Document URL: https://useapi.net/docs/api-muse-v1/delete-muse-accounts-email --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> accounts/`email` description: "Remove a Muse account from the useapi.net Muse API via DELETE accounts/email. Its stored password and session are deleted, while its muse.ai files and chats stay." parent: Muse API nav_order: 140 permalink: /docs/api-muse-v1/delete-muse-accounts-email --- ## Delete a Muse account October 12, 2026 (November 16, 2026) --- Remove an added Muse account from your useapi.net account. The stored password and session are deleted and the account slot is freed. Nothing is deleted on Muse's side. The account's files and chats stay in its Muse workspace, and you can add the account again at any time with [POST /accounts](/docs/api-muse-v1/post-muse-accounts). Its asset ids, and the chat history of its jobs, stop working until it is added again. Job records stay readable with [GET /jobs/`jobid`](/docs/api-muse-v1/get-muse-jobs-jobid). > **https://api.useapi.net/v1/muse/accounts/`email`** - `email` is the email of an added account, URL-encoded in the path. ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **204** **204 No Content** — the account was removed. The response body is empty. **400** **400 Bad Request** — the `email` in the path is not a valid email, or no account is added at all. ```json { "error": "Path parameter email (not-an-email) not a valid email", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **404** **404 Not Found** — no account is added for this `email`. ```json { "error": "Account example@gmail.com not found", "code": 404 } ``` ##### Model `204` has no body. Errors return: <details markdown="block" class="model-details"> <summary>The error answer, field by field</summary> ```typescript { // TypeScript, all fields are optional error: string code: number } ``` </details> ##### Examples **Curl** ``` bash curl -X DELETE "https://api.useapi.net/v1/muse/accounts/example%40gmail.com" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously added account email"; const apiUrl = `https://api.useapi.net/v1/muse/accounts/${encodeURIComponent(email)}`; const response = await fetch(apiUrl, { method: "DELETE", headers: { "Authorization": `Bearer ${token}`, }, }); console.log("response", response.status); ``` **Python** ``` python import requests from urllib.parse import quote token = "API token" email = "Previously added account email" apiUrl = f"https://api.useapi.net/v1/muse/accounts/{quote(email, safe='')}" headers = { "Authorization" : f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers) print(response.status_code) ``` === URL: https://useapi.net/docs/api-muse-v1/delete-muse-assets-assetId-share === Document URL: https://useapi.net/docs/api-muse-v1/delete-muse-assets-assetId-share --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> assets/`assetId`/share description: "Stop sharing a published Muse web app via DELETE assets/assetId/share in the useapi.net Muse API. The public link stops working, and the app stays." parent: Muse API nav_order: 336 permalink: /docs/api-muse-v1/delete-muse-assets-assetId-share --- ## Stop sharing a web app October 12, 2026 (November 16, 2026) --- Stop sharing a web app published with [POST /assets/`assetId`/share](/docs/api-muse-v1/post-muse-assets-assetId-share). Its public link stops working, and `shareUrl` in [GET /assets](/docs/api-muse-v1/get-muse-assets) becomes `null`. The app itself stays in the Library. Publish it again at any time. > **https://api.useapi.net/v1/muse/assets/`assetId`/share** - `assetId` is the URL-encoded `assetId` of a web app, an asset of `type` `web`. ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** ```json { "assetId": "user:12345-email:6578616d706c6540676d61696c2e636f6d-web:space~hello-demo", "shareUrl": null } ``` **400** **400 Bad Request** — the path value is not a Muse `assetId`, or the asset is not a web app. ```json { "error": "Only web apps (assets of type web) can be shared", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** — the `assetId` was issued to a different API token. ```json { "error": "This asset id does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** — the web app is not there or is not shared, or the account that holds it is not added. ```json { "error": "Asset not found, or not shared", "code": 404 } ``` **502** **502 Bad Gateway** — Muse did not stop sharing. Retry shortly. ```json { "error": "Muse did not stop sharing (HTTP 500: …), please retry", "code": 502 } ``` **503** **503 Service Unavailable** — Muse could not be reached. Retry shortly. ```json { "error": "Could not connect to the Muse workspace of account example@gmail.com (…), please retry shortly", "code": 503 } ``` **504** **504 Gateway Timeout** — Muse did not answer in time. Check `shareUrl` in [GET /assets](/docs/api-muse-v1/get-muse-assets) `?type=web`, then retry. ```json { "error": "Muse did not answer (…): check shareUrl in GET /assets?type=web, then retry", "code": 504 } ``` **596** **596 Account Error** The account needs your attention, and it is paused until you add it again. You receive an email when this happens. There are three causes. Meta asks for a security check on the account. Sign in once at [muse.ai](https://muse.ai) in a browser, complete the check, then add the account again with [POST /accounts](/docs/api-muse-v1/post-muse-accounts) using the same email and password. The API keeps using its session, so no new sign-in is needed. ```json { "error": "Account example@gmail.com: Meta asks for a security check on account example@gmail.com (\"This account must complete a security checkpoint on the web\"). Sign in once at https://muse.ai in a browser, complete the check, then add the account again with POST /accounts", "code": 596 } ``` Or Muse refused to sign the account in again when its session needed renewing, most often because the password was changed. Add the account again with the current password. ```json { "error": "Account example@gmail.com: Muse refused to sign in account example@gmail.com (…). Update its password with POST /accounts, or sign in at https://muse.ai to clear the block, then re-add it", "code": 596 } ``` Or Muse disabled the account's computer and refuses to start it again. Sign in at [muse.ai](https://muse.ai) in a browser to see why, and ask Muse support to restore it with the form Muse shows there. Add the account again only after Muse has restored it. ```json { "error": "Account example@gmail.com: Muse has disabled the computer of account example@gmail.com (\"VM wake unavailable\"). Sign in at https://muse.ai in a browser to see why and contact Muse support there, then add the account again with POST /accounts", "code": 596 } ``` ##### Model The web app's `assetId` with `shareUrl` set to `null`, since its public link no longer works. <details markdown="block" class="model-details"> <summary>The web app's sharing state, field by field</summary> ```typescript { // TypeScript, all fields are optional assetId: string shareUrl: string | null // the public link, null after stopping sharing error?: string // errors only code?: number // errors only } ``` </details> ##### Examples **Curl** ``` bash ASSETID="user:12345-email:6578616d706c6540676d61696c2e636f6d-web:space~hello-demo" curl -X DELETE -H "Authorization: Bearer …" \ "https://api.useapi.net/v1/muse/assets/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$ASSETID")/share" ``` **JavaScript** ``` javascript const token = "API token"; const assetId = "assetId of a web app from GET /assets?type=web"; const apiUrl = `https://api.useapi.net/v1/muse/assets/${encodeURIComponent(assetId)}/share`; const response = await fetch(apiUrl, { method: "DELETE", headers: { "Authorization": `Bearer ${token}`, }, }); console.log("response", response.status, await response.json()); ``` **Python** ``` python import requests from urllib.parse import quote token = "API token" assetId = "assetId of a web app from GET /assets?type=web" apiUrl = "https://api.useapi.net/v1/muse/assets/" + quote(assetId, safe="") + "/share" headers = { "Authorization" : f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-muse-v1/delete-muse-assets-assetId === Document URL: https://useapi.net/docs/api-muse-v1/delete-muse-assets-assetId --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> assets/`assetId` description: "Delete any Muse Library item via DELETE assets/assetId in the useapi.net Muse API: a media file, a document, a web app or a podcast. An item already gone answers 404." parent: Muse API nav_order: 330 permalink: /docs/api-muse-v1/delete-muse-assets-assetId --- ## Delete an asset October 12, 2026 (November 16, 2026) --- Delete an item from the Library of the account that holds it: an upload, a file Muse generated or the agent made, a document, a web app the agent built, or a podcast episode with its cover. Find asset ids with [GET /assets](/docs/api-muse-v1/get-muse-assets). The item is gone from the muse.ai app too, and its `assetId` stops working in downloads, jobs and chats. > **https://api.useapi.net/v1/muse/assets/`assetId`** - `assetId` is URL-encoded in the path (it contains `:`), from [GET /assets](/docs/api-muse-v1/get-muse-assets). ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** ```json { "assetId": "user:12345-email:6578616d706c6540676d61696c2e636f6d-image:1e562575130e2f0117ff824ed55876343fcb9f8ed6513f35f121d79958a78afc.png", "deleted": true } ``` **400** **400 Bad Request** — the path value is not a Muse `assetId`. ```json { "error": "Path parameter assetId (…) is not a valid Muse asset id (from GET /assets, POST /assets or a job result)", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** — the `assetId` was issued to a different API token. ```json { "error": "This asset id does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** — the item is not there (already deleted), or the account that holds it is not added. ```json { "error": "Asset not found", "code": 404 } ``` **503** **503 Service Unavailable** — Muse could not be reached. Retry shortly. ```json { "error": "Could not connect to the Muse workspace of account example@gmail.com (…), please retry shortly", "code": 503 } ``` **596** **596 Account Error** The account needs your attention, and it is paused until you add it again. You receive an email when this happens. There are three causes. Meta asks for a security check on the account. Sign in once at [muse.ai](https://muse.ai) in a browser, complete the check, then add the account again with [POST /accounts](/docs/api-muse-v1/post-muse-accounts) using the same email and password. The API keeps using its session, so no new sign-in is needed. ```json { "error": "Account example@gmail.com: Meta asks for a security check on account example@gmail.com (\"This account must complete a security checkpoint on the web\"). Sign in once at https://muse.ai in a browser, complete the check, then add the account again with POST /accounts", "code": 596 } ``` Or Muse refused to sign the account in again when its session needed renewing, most often because the password was changed. Add the account again with the current password. ```json { "error": "Account example@gmail.com: Muse refused to sign in account example@gmail.com (…). Update its password with POST /accounts, or sign in at https://muse.ai to clear the block, then re-add it", "code": 596 } ``` Or Muse disabled the account's computer and refuses to start it again. Sign in at [muse.ai](https://muse.ai) in a browser to see why, and ask Muse support to restore it with the form Muse shows there. Add the account again only after Muse has restored it. ```json { "error": "Account example@gmail.com: Muse has disabled the computer of account example@gmail.com (\"VM wake unavailable\"). Sign in at https://muse.ai in a browser to see why and contact Muse support there, then add the account again with POST /accounts", "code": 596 } ``` ##### Model A successful delete answers with the asset's `assetId` and `deleted: true`. <details markdown="block" class="model-details"> <summary>The deleted asset, field by field</summary> ```typescript { // TypeScript, all fields are optional assetId: string deleted: true error?: string // errors only code?: number // errors only } ``` </details> ##### Examples **Curl** ``` bash ASSETID="user:12345-email:6578616d706c6540676d61696c2e636f6d-image:1e562575130e2f0117ff824ed55876343fcb9f8ed6513f35f121d79958a78afc.png" curl -X DELETE -H "Authorization: Bearer …" \ "https://api.useapi.net/v1/muse/assets/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$ASSETID")" ``` **JavaScript** ``` javascript const token = "API token"; const assetId = "assetId from GET /assets"; const apiUrl = `https://api.useapi.net/v1/muse/assets/${encodeURIComponent(assetId)}`; const response = await fetch(apiUrl, { method: "DELETE", headers: { "Authorization": `Bearer ${token}`, }, }); console.log("response", response.status, await response.json()); ``` **Python** ``` python import requests from urllib.parse import quote token = "API token" assetId = "assetId from GET /assets" apiUrl = "https://api.useapi.net/v1/muse/assets/" + quote(assetId, safe="") headers = { "Authorization" : f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-muse-v1/delete-muse-chats-chatId-browser-taskId-viewer === Document URL: https://useapi.net/docs/api-muse-v1/delete-muse-chats-chatId-browser-taskId-viewer --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> chats/`chatId`/browser/`taskId`/viewer description: "Revoke every live view of the agent's browser via DELETE chats/chatId/browser/taskId/viewer in the useapi.net Muse API: open sessions end, unused links stop working." parent: Muse API nav_order: 474 permalink: /docs/api-muse-v1/delete-muse-chats-chatId-browser-taskId-viewer --- ## Revoke live views of the browser October 14, 2026 (November 16, 2026) --- End every live view of the agent's browser. Open viewer sessions end within about 15 seconds, and links that were not opened yet stop working. A link you create after this works as usual. The browser itself stays open: [stop it](/docs/api-muse-v1/post-muse-chats-chatId-browser-taskId-stop) to close it. If you had control in a viewer that ends this way, control goes back to the agent. Use it when you gave a viewer link to someone and want to take it back, or to free the account's one viewer for another browser. See the [Live Browser Guide](/docs/api-muse-v1/live-browser-guide) for the whole flow. > **https://api.useapi.net/v1/muse/chats/`chatId`/browser/`taskId`/viewer** - `chatId` is URL-encoded in the path (it contains `:` and `@`). - `taskId` is the `taskId` of the chat's `browser` event. ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** ```json { "chatId": "c-u12345-email:example@gmail.com-chat:8e0bf21e-a3b5-4a1e-a05a-65d160469bfb-bot:muse", "taskId": "423bc12e-db16-4921-8670-08b5f3f5a5d6", "revoked": true } ``` **400** **400 Bad Request** — the path holds no valid `chatId` or `taskId`. ```json { "error": "Path parameter taskId (not-a-task) is not a valid browser task id", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** — the `chatId` was issued to a different API token. ```json { "error": "This chat id does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** — the chat or the browser was not found, or the account that holds the chat is not added. ```json { "error": "Browser task not found in this chat", "code": 404 } ``` **409** **409 Conflict** — the browser is closed. Its viewers ended with it. ```json { "error": "This browser is already closed", "code": 409 } ``` **503** **503 Service Unavailable** — Muse could not be reached. Retry shortly. ```json { "error": "Could not connect to the Muse workspace of account example@gmail.com (…), please retry shortly", "code": 503 } ``` **596** **596 Account Error** The account needs your attention, and it is paused until you add it again. You receive an email when this happens. There are three causes. Meta asks for a security check on the account. Sign in once at [muse.ai](https://muse.ai) in a browser, complete the check, then add the account again with [POST /accounts](/docs/api-muse-v1/post-muse-accounts) using the same email and password. The API keeps using its session, so no new sign-in is needed. ```json { "error": "Account example@gmail.com: Meta asks for a security check on account example@gmail.com (\"This account must complete a security checkpoint on the web\"). Sign in once at https://muse.ai in a browser, complete the check, then add the account again with POST /accounts", "code": 596 } ``` Or Muse refused to sign the account in again when its session needed renewing, most often because the password was changed. Add the account again with the current password. ```json { "error": "Account example@gmail.com: Muse refused to sign in account example@gmail.com (…). Update its password with POST /accounts, or sign in at https://muse.ai to clear the block, then re-add it", "code": 596 } ``` Or Muse disabled the account's computer and refuses to start it again. Sign in at [muse.ai](https://muse.ai) in a browser to see why, and ask Muse support to restore it with the form Muse shows there. Add the account again only after Muse has restored it. ```json { "error": "Account example@gmail.com: Muse has disabled the computer of account example@gmail.com (\"VM wake unavailable\"). Sign in at https://muse.ai in a browser to see why and contact Muse support there, then add the account again with POST /accounts", "code": 596 } ``` ##### Model The answer names the chat and the browser (`chatId`, `taskId`) with `revoked: true`. <details markdown="block" class="model-details"> <summary>The revoke result, field by field</summary> ```typescript { // TypeScript, all fields are optional chatId: string taskId: string revoked: true error?: string // errors only code?: number // errors only } ``` </details> ##### Examples **Curl** ``` bash CHATID="c-u12345-email:example@gmail.com-chat:8e0bf21e-a3b5-4a1e-a05a-65d160469bfb-bot:muse" TASKID="423bc12e-db16-4921-8670-08b5f3f5a5d6" curl -X DELETE -H "Authorization: Bearer …" \ "https://api.useapi.net/v1/muse/chats/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$CHATID")/browser/$TASKID/viewer" ``` **JavaScript** ``` javascript const token = "API token"; const chatId = "chatId from POST /chats"; const taskId = "taskId from the stream's browser event"; const apiUrl = `https://api.useapi.net/v1/muse/chats/${encodeURIComponent(chatId)}/browser/${encodeURIComponent(taskId)}/viewer`; const response = await fetch(apiUrl, { method: "DELETE", headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", response.status, result); ``` **Python** ``` python import requests from urllib.parse import quote token = "API token" chatId = "chatId from POST /chats" taskId = "taskId from the stream's browser event" apiUrl = f"https://api.useapi.net/v1/muse/chats/{quote(chatId, safe='')}/browser/{quote(taskId, safe='')}/viewer" headers = { "Authorization" : f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-muse-v1/delete-muse-chats-chatId === Document URL: https://useapi.net/docs/api-muse-v1/delete-muse-chats-chatId --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> chats/`chatId` description: "Delete a Muse chat via DELETE chats/chatId in the useapi.net Muse API. The chat is removed on Muse, and the files it made stay in the account's workspace." parent: Muse API nav_order: 460 permalink: /docs/api-muse-v1/delete-muse-chats-chatId --- ## Delete a chat October 12, 2026 (November 16, 2026) --- Delete a chat on Muse. It disappears from the muse.ai app and from [GET /chats](/docs/api-muse-v1/get-muse-chats). The account's main chat cannot be deleted and answers `409`. A job's chat can be deleted too, and its job record stays readable with [GET /jobs/`jobid`](/docs/api-muse-v1/get-muse-jobs-jobid). The files the chat made stay in the account's workspace: list them with [GET /assets](/docs/api-muse-v1/get-muse-assets), and remove one with [DELETE /assets/`assetId`](/docs/api-muse-v1/delete-muse-assets-assetId). If the agent opened a browser in the chat, [stop it](/docs/api-muse-v1/post-muse-chats-chatId-browser-taskId-stop) first: a browser of a deleted chat can no longer be reached, and it can keep one of the account's two browsers busy. > **https://api.useapi.net/v1/muse/chats/`chatId`** - `chatId` is URL-encoded in the path (it contains `:` and `@`). ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** ```json { "chatId": "c-u12345-email:example@gmail.com-chat:272b73f4-6fcb-42c2-9ec7-75cc0c020940-bot:muse", "deleted": true } ``` **400** **400 Bad Request** — the path value is not a Muse `chatId`. ```json { "error": "Path parameter chatId (not-a-chat-id) is not a valid Muse chat id", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** — the `chatId` was issued to a different API token. ```json { "error": "This chat id does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** — the chat is already deleted, or the account that holds it is not added. ```json { "error": "Chat not found", "code": 404 } ``` **409** **409 Conflict** — this is the account's main chat, which Muse never deletes. ```json { "error": "This is the account's main chat, which Muse never deletes", "code": 409 } ``` **503** **503 Service Unavailable** — Muse could not be reached. Retry shortly. ```json { "error": "Could not connect to the Muse workspace of account example@gmail.com (…), please retry shortly", "code": 503 } ``` **596** **596 Account Error** The account needs your attention, and it is paused until you add it again. You receive an email when this happens. There are three causes. Meta asks for a security check on the account. Sign in once at [muse.ai](https://muse.ai) in a browser, complete the check, then add the account again with [POST /accounts](/docs/api-muse-v1/post-muse-accounts) using the same email and password. The API keeps using its session, so no new sign-in is needed. ```json { "error": "Account example@gmail.com: Meta asks for a security check on account example@gmail.com (\"This account must complete a security checkpoint on the web\"). Sign in once at https://muse.ai in a browser, complete the check, then add the account again with POST /accounts", "code": 596 } ``` Or Muse refused to sign the account in again when its session needed renewing, most often because the password was changed. Add the account again with the current password. ```json { "error": "Account example@gmail.com: Muse refused to sign in account example@gmail.com (…). Update its password with POST /accounts, or sign in at https://muse.ai to clear the block, then re-add it", "code": 596 } ``` Or Muse disabled the account's computer and refuses to start it again. Sign in at [muse.ai](https://muse.ai) in a browser to see why, and ask Muse support to restore it with the form Muse shows there. Add the account again only after Muse has restored it. ```json { "error": "Account example@gmail.com: Muse has disabled the computer of account example@gmail.com (\"VM wake unavailable\"). Sign in at https://muse.ai in a browser to see why and contact Muse support there, then add the account again with POST /accounts", "code": 596 } ``` ##### Model A successful delete answers with the chat's `chatId` and `deleted: true`. <details markdown="block" class="model-details"> <summary>The deleted chat, field by field</summary> ```typescript { // TypeScript, all fields are optional chatId: string deleted: true error?: string // errors only code?: number // errors only } ``` </details> ##### Examples **Curl** ``` bash CHATID="c-u12345-email:example@gmail.com-chat:272b73f4-6fcb-42c2-9ec7-75cc0c020940-bot:muse" curl -X DELETE -H "Authorization: Bearer …" \ "https://api.useapi.net/v1/muse/chats/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$CHATID")" ``` **JavaScript** ``` javascript const token = "API token"; const chatId = "chatId from POST /chats or GET /chats"; const apiUrl = `https://api.useapi.net/v1/muse/chats/${encodeURIComponent(chatId)}`; const response = await fetch(apiUrl, { method: "DELETE", headers: { "Authorization": `Bearer ${token}`, }, }); console.log("response", response.status, await response.json()); ``` **Python** ``` python import requests from urllib.parse import quote token = "API token" chatId = "chatId from POST /chats or GET /chats" apiUrl = f"https://api.useapi.net/v1/muse/chats/{quote(chatId, safe='')}" headers = { "Authorization" : f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-muse-v1/delete-muse-files === Document URL: https://useapi.net/docs/api-muse-v1/delete-muse-files --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> files description: "Delete a file from a Muse account's workspace via DELETE files in the useapi.net Muse API. Files only, not folders. A file already gone answers 404." parent: Muse API nav_order: 344 permalink: /docs/api-muse-v1/delete-muse-files --- ## Delete a workspace file October 12, 2026 (November 16, 2026) --- Delete one file from the Muse workspace of an account. Folders cannot be deleted: delete the files in them. Files and assets are two views of the same workspace. [Assets](/docs/api-muse-v1/get-muse-assets) are the images, videos and audio files, each with an `assetId` for jobs and chats. `/files` covers the whole workspace, including the code, documents and data the agent writes. A media file listed here also carries its `assetId`. Deleting a media file also removes its asset. Paths always start with `workspace/`, for example `workspace/your_files/report.pdf`. > **https://api.useapi.net/v1/muse/files?email=`email`&path=`path`** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `email` is optional when the API token has one Muse account, and **required** when it has more. URL-encode it. - `path` is **required**, the file's path in the workspace. ##### Responses **200** **200 OK** ```json { "email": "example@gmail.com", "path": "workspace/your_files/report.pdf", "deleted": true } ``` **400** **400 Bad Request** — `path` is a folder, or not a path in the workspace. ```json { "error": "Deleting folders is not supported: delete the files in it", "code": 400 } ``` **401** **401 Unauthorized** — Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **404** **404 Not Found** — the path is not in the workspace, or the account named by `email` is not added. ```json { "error": "File not found", "code": 404 } ``` **503** **503 Service Unavailable** — Muse could not be reached. Retry shortly. ```json { "error": "Muse could not do it right now (…), please retry", "code": 503 } ``` **596** **596 Account Error** The account needs your attention, and it is paused until you add it again. You receive an email when this happens. There are three causes. Meta asks for a security check on the account. Sign in once at [muse.ai](https://muse.ai) in a browser, complete the check, then add the account again with [POST /accounts](/docs/api-muse-v1/post-muse-accounts) using the same email and password. The API keeps using its session, so no new sign-in is needed. ```json { "error": "Account example@gmail.com: Meta asks for a security check on account example@gmail.com (\"This account must complete a security checkpoint on the web\"). Sign in once at https://muse.ai in a browser, complete the check, then add the account again with POST /accounts", "code": 596 } ``` Or Muse refused to sign the account in again when its session needed renewing, most often because the password was changed. Add the account again with the current password. ```json { "error": "Account example@gmail.com: Muse refused to sign in account example@gmail.com (…). Update its password with POST /accounts, or sign in at https://muse.ai to clear the block, then re-add it", "code": 596 } ``` Or Muse disabled the account's computer and refuses to start it again. Sign in at [muse.ai](https://muse.ai) in a browser to see why, and ask Muse support to restore it with the form Muse shows there. Add the account again only after Muse has restored it. ```json { "error": "Account example@gmail.com: Muse has disabled the computer of account example@gmail.com (\"VM wake unavailable\"). Sign in at https://muse.ai in a browser to see why and contact Muse support there, then add the account again with POST /accounts", "code": 596 } ``` ##### Model A successful delete answers with the account `email`, the file's `path` and `deleted: true`. <details markdown="block" class="model-details"> <summary>The deleted file, field by field</summary> ```typescript { // TypeScript, all fields are optional email: string path: string deleted: true error?: string // errors only code?: number // errors only } ``` </details> ##### Examples **Curl** ``` bash curl -X DELETE -H "Authorization: Bearer …" \ "https://api.useapi.net/v1/muse/files?email=example%40gmail.com&path=workspace%2Fyour_files%2Freport.pdf" ``` **JavaScript** ``` javascript const token = "API token"; const params = new URLSearchParams({ email: "example@gmail.com", path: "workspace/your_files/report.pdf" }); const response = await fetch(`https://api.useapi.net/v1/muse/files?${params}`, { method: "DELETE", headers: { "Authorization": `Bearer ${token}`, } }); console.log("response", response.status, await response.json()); ``` **Python** ``` python import requests token = "API token" apiUrl = "https://api.useapi.net/v1/muse/files" headers = { "Authorization" : f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers, params={"email": "example@gmail.com", "path": "workspace/your_files/report.pdf"}) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-muse-v1/demo === Document URL: https://useapi.net/docs/api-muse-v1/demo --- layout: default title: Live Demo nav_icon: play description: "Open the Muse API demo app: chat with Meta's Muse agent live, watch its browser, answer approvals, browse the Library and workspace, and edit permissions, on desktop or phone." parent: Muse API nav_order: 5 permalink: /docs/api-muse-v1/demo --- ## Muse API Live Demo October 12, 2026 (October 14, 2026) A complete Muse client in one HTML file, running full screen on its own page and on phones. Paste your API token, press Connect and pick a Muse account. Chat with the Muse agent as its answer streams in, watch its web browser live, answer its permission requests, browse the account's Library and every file on the account, and change what the agent may do without asking. Your token stays in the browser and goes only to api.useapi.net. <a href="/demos/muse/" class="btn btn-primary fs-5">Open the Muse demo</a> [Get the source on GitHub](https://github.com/useapi/muse-api/tree/main/demo): the same `index.html`, with no framework, no build step and no dependencies, and a README that maps every feature to its API call. ### What it does - Chat streams Muse's answers live with [GET /chats/`chatId`/stream](/docs/api-muse-v1/get-muse-chats-chatId-stream) and resumes with `Last-Event-ID` after a drop. It starts chats with [POST /chats](/docs/api-muse-v1/post-muse-chats), sends messages with [POST /chats/`chatId`/messages](/docs/api-muse-v1/post-muse-chats-chatId-messages), stops with [POST /chats/`chatId`/cancel](/docs/api-muse-v1/post-muse-chats-chatId-cancel), and lists, opens and deletes chats with [GET /chats](/docs/api-muse-v1/get-muse-chats), [GET /chats/`chatId`](/docs/api-muse-v1/get-muse-chats-chatId) and [DELETE /chats/`chatId`](/docs/api-muse-v1/delete-muse-chats-chatId). The [Chat Streaming Guide](/docs/api-muse-v1/chat-streaming-guide) explains the stream step by step. - Reactions the agent adds to messages show under them, from the stream's `reaction` events and `reactions` in [GET /chats/`chatId`](/docs/api-muse-v1/get-muse-chats-chatId). Podcasts the agent makes play in the chat with their cover. - A browser card shows each web browser the agent opens, with its status and open page. Watch live opens a live view in a new tab with [POST /chats/`chatId`/browser/`taskId`/viewer](/docs/api-muse-v1/post-muse-chats-chatId-browser-taskId-viewer), where you can take control. Give back returns control to the agent with [POST /chats/`chatId`/browser/`taskId`/release](/docs/api-muse-v1/post-muse-chats-chatId-browser-taskId-release), Stop closes the browser with [POST /chats/`chatId`/browser/`taskId`/stop](/docs/api-muse-v1/post-muse-chats-chatId-browser-taskId-stop), and Refresh reads it with [GET /chats/`chatId`/browser/`taskId`](/docs/api-muse-v1/get-muse-chats-chatId-browser-taskId). The [Live Browser Guide](/docs/api-muse-v1/live-browser-guide) explains the flow. - Approval cards answer the agent's permission requests with [POST /chats/`chatId`/approvals/`approvalId`](/docs/api-muse-v1/post-muse-chats-chatId-approvals-approvalId), and quick-reply buttons answer with [POST /chats/`chatId`/widgets/`widgetId`](/docs/api-muse-v1/post-muse-chats-chatId-widgets-widgetId). - The Library view lists the account's whole Library with [GET /assets](/docs/api-muse-v1/get-muse-assets), filtered by type: images, videos and audio, documents, web apps and podcasts. It uploads with [POST /assets](/docs/api-muse-v1/post-muse-assets), and previews, downloads and deletes with [GET /assets/`assetId`](/docs/api-muse-v1/get-muse-assets-assetId) and [DELETE /assets/`assetId`](/docs/api-muse-v1/delete-muse-assets-assetId). Documents also download as PDF. A web app opens with Open app, and Share publishes it on a public link with [POST /assets/`assetId`/share](/docs/api-muse-v1/post-muse-assets-assetId-share), with Copy link and Stop sharing ([DELETE /assets/`assetId`/share](/docs/api-muse-v1/delete-muse-assets-assetId-share)). Podcasts play with their cover. - The Workspace view browses every file in the account's Muse workspace with [GET /files](/docs/api-muse-v1/get-muse-files), previews and downloads with [GET /files/content](/docs/api-muse-v1/get-muse-files-content), searches with [GET /files/search](/docs/api-muse-v1/get-muse-files-search), uploads with [POST /files](/docs/api-muse-v1/post-muse-files) and deletes with [DELETE /files](/docs/api-muse-v1/delete-muse-files). Any file can be attached to the next message. - Permissions shows and changes the agent's defaults and rules with [GET](/docs/api-muse-v1/get-muse-accounts-email-permissions) and [POST /accounts/`email`/permissions](/docs/api-muse-v1/post-muse-accounts-email-permissions), [changes](/docs/api-muse-v1/post-muse-accounts-email-permissions-permissionId) or [removes](/docs/api-muse-v1/delete-muse-accounts-email-permissions-permissionId) a rule, and lists waiting and answered requests with [GET /accounts/`email`/approvals](/docs/api-muse-v1/get-muse-accounts-email-approvals). === URL: https://useapi.net/docs/api-muse-v1/get-muse-accounts-email-approvals === Document URL: https://useapi.net/docs/api-muse-v1/get-muse-accounts-email-approvals --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts/`email`/approvals description: "List the Muse agent's permission requests via GET accounts/email/approvals in the useapi.net Muse API: pending ones from every chat, plus recent decisions." parent: Muse API nav_order: 121 permalink: /docs/api-muse-v1/get-muse-accounts-email-approvals --- ## List approvals October 12, 2026 (November 16, 2026) --- List the agent's permission requests on one Muse account, across all of its chats. Each Muse account is one agent, and before some actions it asks for permission: for example to send information to a website while it runs code, or to act in a connected app. - `pending` holds the requests that wait for an answer. Each names the `chatId` that asked. Answer one with [POST /chats/`chatId`/approvals/`approvalId`](/docs/api-muse-v1/post-muse-chats-chatId-approvals-approvalId) and one of its `options`. - `decided` holds requests that already ended, newest first: approved, denied or timed out. While a request waits, that chat's answer is paused. A request that is not answered by its `expires` time ends as timed out. The chat stream shows the same requests as `approval` events, see [GET /chats/`chatId`/stream](/docs/api-muse-v1/get-muse-chats-chatId-stream). > **https://api.useapi.net/v1/muse/accounts/`email`/approvals?status=`status`&limit=`limit`** - `email` is the email of an added account, URL-encoded in the path. ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `status` is optional, `pending` for the waiting requests only, or `all` for `pending` and `decided`. Default: `all`. - `limit` is optional, how many decided requests to read. Range: `1` to `100`. Default: `50`. ##### Responses **200** **200 OK** ```json { "email": "example@gmail.com", "pending": [ { "approvalId": "b996c81a-fbf4-4645-bc62-4a3cb75d3cbb", "chatId": "c-u12345-email:example@gmail.com-chat:24b7e718-bb5a-4ff3-81d9-d90b108f084c-bot:muse", "status": "pending", "decision": null, "title": "Share info with deb.nodesource.com", "question": "Allow Muse to share information with deb.nodesource.com?", "details": [ { "label": "Host", "value": "deb.nodesource.com" }, { "label": "Grants", "value": "nodesource.com and all subdomains" }, { "label": "Method", "value": "CONNECT" }, { "label": "Path", "value": "deb.nodesource.com:443" }, { "label": "Policy", "value": "tool.exec" } ], "options": [ { "decision": "allow_once", "label": "Allow once" }, { "decision": "allow_always", "label": "Always allow this site" }, { "decision": "deny", "label": "Deny" } ], "requested": "2026-10-13T01:26:15.483Z", "decided": null, "expires": "2026-10-13T01:36:15.483Z" } ], "decided": [ { "approvalId": "c5728845-81a7-4c50-902a-84a7dacff6fd", "chatId": "c-u12345-email:example@gmail.com-chat:8d69a599-7aa9-46e2-bfcb-78e156f9a138-bot:muse", "status": "approved", "decision": "allow_always", "title": "Share info with deb.nodesource.com", "question": "Allow Muse to share information with deb.nodesource.com?", "details": [ { "label": "Host", "value": "deb.nodesource.com" }, { "label": "Grants", "value": "nodesource.com and all subdomains" }, { "label": "Method", "value": "CONNECT" }, { "label": "Path", "value": "deb.nodesource.com:443" }, { "label": "Policy", "value": "tool.exec" } ], "requested": "2026-10-13T01:26:15.483Z", "decided": "2026-10-13T01:26:21.339Z", "expires": "2026-10-13T01:36:15.483Z" } ] } ``` With `status=pending` the response has no `decided`. **400** **400 Bad Request** — a parameter is invalid. ```json { "error": "Parameter status (done) valid values: pending,all", "code": 400 } ``` **401** **401 Unauthorized** — Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **404** **404 Not Found** — the account named by `email` is not added. ```json { "error": "Account example@gmail.com is not configured", "code": 404 } ``` **503** **503 Service Unavailable** — Muse could not be read right now. Retry shortly. ```json { "error": "Muse could not be read right now (…), please retry", "code": 503 } ``` **596** **596 Account Error** The account needs your attention, and it is paused until you add it again. You receive an email when this happens. There are three causes. Meta asks for a security check on the account. Sign in once at [muse.ai](https://muse.ai) in a browser, complete the check, then add the account again with [POST /accounts](/docs/api-muse-v1/post-muse-accounts) using the same email and password. The API keeps using its session, so no new sign-in is needed. ```json { "error": "Account example@gmail.com: Meta asks for a security check on account example@gmail.com (\"This account must complete a security checkpoint on the web\"). Sign in once at https://muse.ai in a browser, complete the check, then add the account again with POST /accounts", "code": 596 } ``` Or Muse refused to sign the account in again when its session needed renewing, most often because the password was changed. Add the account again with the current password. ```json { "error": "Account example@gmail.com: Muse refused to sign in account example@gmail.com (…). Update its password with POST /accounts, or sign in at https://muse.ai to clear the block, then re-add it", "code": 596 } ``` Or Muse disabled the account's computer and refuses to start it again. Sign in at [muse.ai](https://muse.ai) in a browser to see why, and ask Muse support to restore it with the form Muse shows there. Add the account again only after Muse has restored it. ```json { "error": "Account example@gmail.com: Muse has disabled the computer of account example@gmail.com (\"VM wake unavailable\"). Sign in at https://muse.ai in a browser to see why and contact Muse support there, then add the account again with POST /accounts", "code": 596 } ``` ##### Model The agent's permission requests on the account: `pending` ones that wait for an answer and `decided` ones, newest first. <details markdown="block" class="model-details"> <summary>The account's pending and decided approvals, field by field, and the type it uses (<code>Approval</code>)</summary> ```typescript { // TypeScript, all fields are optional email: string pending: Approval[] // waiting for an answer decided?: Approval[] // ended, newest first (not with status=pending) error?: string // errors only code?: number // errors only } type Approval = { approvalId: string chatId: string | null // the chat that asked: answer with POST /chats/{chatId}/approvals/{approvalId} status: string // pending, approved, denied, or how it ended, e.g. timed out decision: string | null // e.g. allow_once, allow_always, deny title: string | null // e.g. "Share info with deb.nodesource.com" question: string | null details: { label: string, value: string }[] options?: { decision: string, label: string }[] // pending only: the answers you can give requested: string | null // ISO 8601 decided: string | null // ISO 8601 expires: string | null // ISO 8601, an unanswered request times out then } ``` </details> ##### Examples **Curl** ``` bash EMAIL="example@gmail.com" curl -H "Authorization: Bearer …" \ "https://api.useapi.net/v1/muse/accounts/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$EMAIL")/approvals?status=pending" ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously added account email"; const apiUrl = `https://api.useapi.net/v1/muse/accounts/${encodeURIComponent(email)}/approvals?status=pending`; const response = await fetch(apiUrl, { method: "GET", headers: { "Authorization": `Bearer ${token}`, } }); console.log("response", response.status, await response.json()); ``` **Python** ``` python import requests from urllib.parse import quote token = "API token" email = "Previously added account email" apiUrl = f"https://api.useapi.net/v1/muse/accounts/{quote(email, safe='')}/approvals" headers = { "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers, params={"status": "pending"}) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-muse-v1/get-muse-accounts-email-permissions === Document URL: https://useapi.net/docs/api-muse-v1/get-muse-accounts-email-permissions --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts/`email`/permissions description: "Read what the Muse agent may do without asking via GET accounts/email/permissions in the useapi.net Muse API: default settings and the standing allow or deny rules." parent: Muse API nav_order: 122 permalink: /docs/api-muse-v1/get-muse-accounts-email-permissions --- ## List permissions October 12, 2026 (November 16, 2026) --- Read what the Muse agent on this account may do without asking: the two default settings, and the standing rules for single websites and app actions. - `web` covers the websites the agent reaches, for example while it runs code. - `connectors` covers actions in the apps connected to the Muse account, such as email or calendar. Each one is `auto_allow` or `always_ask`: - `auto_allow` is Muse's "Ask for some actions", the default. Muse may act without asking, for example send an email from a connected Gmail. - `always_ask` is Muse's "Always ask". Muse asks before each such action, and the question comes to the chat as an [approval](/docs/api-muse-v1/post-muse-chats-chatId-approvals-approvalId). Change the defaults with [POST /accounts/`email`/permissions](/docs/api-muse-v1/post-muse-accounts-email-permissions). A rule allows or denies one website or app action, whatever the default says. A rule is created when you answer an approval with `allow_always`, or when you allow something for good in the muse.ai app. Change a rule with [POST /accounts/`email`/permissions/`permissionId`](/docs/api-muse-v1/post-muse-accounts-email-permissions-permissionId), or remove it with [DELETE /accounts/`email`/permissions/`permissionId`](/docs/api-muse-v1/delete-muse-accounts-email-permissions-permissionId). > **https://api.useapi.net/v1/muse/accounts/`email`/permissions** - `email` is the email of an added account, URL-encoded in the path. ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** ```json { "email": "example@gmail.com", "defaults": { "web": "auto_allow", "connectors": "auto_allow" }, "rules": [ { "permissionId": "network_rule:hitl_domain_allow_nodesource_com_afdc93c7", "type": "web", "mode": "allow", "modes": ["allow", "ask", "deny"], "title": "nodesource.com", "target": "nodesource.com:80,443", "note": null, "lifetime": "durable", "revocable": true, "created": null }, { "permissionId": "transient_connector:connector-context-write:708c1f254e09d74cffc023608a684291b6a72eaef90880502d28a1ab33381840", "type": "connector", "mode": "allow", "modes": ["allow", "ask", "deny"], "title": "Download files in Browser", "target": "browser:page.download", "note": "For Heartbeat · Scheduled task", "lifetime": "durable", "revocable": true, "created": "2026-10-05T05:12:39.495Z" } ] } ``` **401** **401 Unauthorized** — Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **404** **404 Not Found** — the account named by `email` is not added. ```json { "error": "Account example@gmail.com is not configured", "code": 404 } ``` **503** **503 Service Unavailable** — Muse could not be read right now. Retry shortly. ```json { "error": "Muse could not be read right now (…), please retry", "code": 503 } ``` **596** **596 Account Error** The account needs your attention, and it is paused until you add it again. You receive an email when this happens. There are three causes. Meta asks for a security check on the account. Sign in once at [muse.ai](https://muse.ai) in a browser, complete the check, then add the account again with [POST /accounts](/docs/api-muse-v1/post-muse-accounts) using the same email and password. The API keeps using its session, so no new sign-in is needed. ```json { "error": "Account example@gmail.com: Meta asks for a security check on account example@gmail.com (\"This account must complete a security checkpoint on the web\"). Sign in once at https://muse.ai in a browser, complete the check, then add the account again with POST /accounts", "code": 596 } ``` Or Muse refused to sign the account in again when its session needed renewing, most often because the password was changed. Add the account again with the current password. ```json { "error": "Account example@gmail.com: Muse refused to sign in account example@gmail.com (…). Update its password with POST /accounts, or sign in at https://muse.ai to clear the block, then re-add it", "code": 596 } ``` Or Muse disabled the account's computer and refuses to start it again. Sign in at [muse.ai](https://muse.ai) in a browser to see why, and ask Muse support to restore it with the form Muse shows there. Add the account again only after Muse has restored it. ```json { "error": "Account example@gmail.com: Muse has disabled the computer of account example@gmail.com (\"VM wake unavailable\"). Sign in at https://muse.ai in a browser to see why and contact Muse support there, then add the account again with POST /accounts", "code": 596 } ``` ##### Model The account's two default settings, `web` and `connectors`, and its standing rules, each with a `permissionId` to change or delete it. <details markdown="block" class="model-details"> <summary>The account's default settings and rules, field by field, and the type it uses (<code>Rule</code>)</summary> ```typescript { // TypeScript, all fields are optional email: string defaults: { web: 'auto_allow' | 'always_ask' | null connectors: 'auto_allow' | 'always_ask' | null } rules: Rule[] error?: string // errors only code?: number // errors only } type Rule = { permissionId: string // use it in POST / DELETE /accounts/{email}/permissions/{permissionId} type: 'web' | 'connector' // web: a website the agent may reach; connector: an action in a connected app mode: string | null // allow or deny modes: string[] // the modes this rule can take: allow, ask, deny title: string | null // e.g. "nodesource.com", "Download files in Browser" target: string | null // e.g. "nodesource.com:80,443", "browser:page.download" note: string | null lifetime: string | null // e.g. durable revocable: boolean created: string | null // ISO 8601 } ``` </details> ##### Examples **Curl** ``` bash EMAIL="example@gmail.com" curl -H "Authorization: Bearer …" \ "https://api.useapi.net/v1/muse/accounts/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$EMAIL")/permissions" ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously added account email"; const apiUrl = `https://api.useapi.net/v1/muse/accounts/${encodeURIComponent(email)}/permissions`; const response = await fetch(apiUrl, { method: "GET", headers: { "Authorization": `Bearer ${token}`, } }); console.log("response", response.status, await response.json()); ``` **Python** ``` python import requests from urllib.parse import quote token = "API token" email = "Previously added account email" apiUrl = f"https://api.useapi.net/v1/muse/accounts/{quote(email, safe='')}/permissions" headers = { "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-muse-v1/get-muse-accounts-email === Document URL: https://useapi.net/docs/api-muse-v1/get-muse-accounts-email --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts/`email` description: "Read one Muse account live via GET accounts/email in the useapi.net Muse API: its plan tier, the percent of the weekly allowance used and the reset time." parent: Muse API nav_order: 120 permalink: /docs/api-muse-v1/get-muse-accounts-email --- ## Retrieve a Muse account October 12, 2026 (November 16, 2026) --- Get one added account with a live read from Muse: its plan and how much of the weekly allowance it has used. The read uses the stored session, as a job does, and every call goes to Muse. The result is also saved, so [GET /accounts](/docs/api-muse-v1/get-muse-accounts) and the choice of account for new jobs use it. Muse meters each account weekly. [GET /accounts/`email`](/docs/api-muse-v1/get-muse-accounts-email) returns the plan and usage in `quota`: `tier`, `percentUsed`, `resetsAt` and `quotaStatus`. | Plan | Price | Weekly allowance | |---|---|---| | Free | $0 | not published | | Power | $20/month | 500 million Muse tokens | | Maximum | $100/month | 3 billion Muse tokens | Source: Meta, [About Muse subscriptions](https://www.meta.com/help/subscriptions/1021145227643680/), October 2026. Availability can differ by region. - On the free plan, a video used 2 to 3 percent of the weekly allowance in our tests and an image 0 to 1 percent. Meta does not publish per-job token costs. - The allowance resets at `resetsAt`. Once it is used up, new jobs go to your other accounts, and a job pinned to the account answers `412`. - Tokens bought or granted on top of the plan show on muse.ai as Additional tokens and never expire. The API keeps sending jobs to an account that has top-up left after its weekly allowance is used up. `topupLabel` gives the top-up as muse.ai words it, for example `0% used (1B tokens left)`. `topupBalance` (left) and `topupTotal` (bought) are Muse's own counters, not token counts: an account with 1B tokens left reads `40000000`. - Muse also limits the videos an account makes over the last 24 hours, apart from the weekly allowance. When it says the limit is reached, video jobs skip the account for an hour. See [Video limit](/docs/api-muse-v1/post-muse-jobs-video#video-limit). If Muse no longer accepts the session, the API signs the account in again once, the same as on any other request, and then reads it. A paused account (one whose `health` is not `OK`) is returned as stored, without a call to Muse. > **https://api.useapi.net/v1/muse/accounts/`email`** - `email` is the email of an added account, URL-encoded in the path. ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** ```json { "email": "example@gmail.com", "maxJobs": 3, "added": "2026-10-12T00:34:19.139Z", "updated": "2026-10-12T01:29:14.234Z", "sessionExpiresAt": "2026-11-11T00:34:18.820Z", "quota": { "tier": "HATCH_FREE", "percentUsed": 3, "resetsAt": "2026-10-19T01:13:18.000Z", "quotaStatus": "SUFFICIENT", "topupBalance": 0, "topupTotal": 0, "topupLabel": null, "readAt": "2026-10-12T01:29:14.794Z" }, "health": "OK", "session": "signed-in" } ``` - `session` is `signed-in` after a live read. It is `checkpoint` when Meta asks for a security check on the account (the account is paused from then on and `health` says what to do), and `unknown` when Muse did not answer the read: `quotaError` then says why and `quota` is the last saved one. - A paused account is returned as stored, without `session`. - `videoLimitUntil` is shown only while the account sits out video jobs after Muse said it reached its [video limit](/docs/api-muse-v1/post-muse-jobs-video#video-limit) for the last 24 hours. This read does not clear it: video jobs try the account again after that time, or right away once you add it again with [POST /accounts](/docs/api-muse-v1/post-muse-accounts). - `videoRegionBlocked` is shown when Muse said video is not available for the account in its country or region. Video jobs skip the account until you add it again with [POST /accounts](/docs/api-muse-v1/post-muse-accounts). See [Generate a video](/docs/api-muse-v1/post-muse-jobs-video#video-limit). **400** **400 Bad Request** — the `email` in the path is not a valid email. ```json { "error": "Path parameter email (not-an-email) not a valid email", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **404** **404 Not Found** — no account is added for this `email`. ```json { "error": "Account example@gmail.com not found", "code": 404 } ``` **503** **503 Service Unavailable** — Muse did not accept the session and signing in again could not finish right now. Retry in a few minutes. ```json { "error": "Muse refused account example@gmail.com's new session, please retry in a few minutes", "code": 503 } ``` **596** **596 Account Error** The account needs your attention, and it is paused until you add it again. You receive an email when this happens. There are three causes. Meta asks for a security check on the account. Sign in once at [muse.ai](https://muse.ai) in a browser, complete the check, then add the account again with [POST /accounts](/docs/api-muse-v1/post-muse-accounts) using the same email and password. The API keeps using its session, so no new sign-in is needed. ```json { "error": "Account example@gmail.com: Meta asks for a security check on account example@gmail.com (\"This account must complete a security checkpoint on the web\"). Sign in once at https://muse.ai in a browser, complete the check, then add the account again with POST /accounts", "code": 596 } ``` Or Muse refused to sign the account in again when its session needed renewing, most often because the password was changed. Add the account again with the current password. ```json { "error": "Account example@gmail.com: Muse refused to sign in account example@gmail.com (…). Update its password with POST /accounts, or sign in at https://muse.ai to clear the block, then re-add it", "code": 596 } ``` Or Muse disabled the account's computer and refuses to start it again. Sign in at [muse.ai](https://muse.ai) in a browser to see why, and ask Muse support to restore it with the form Muse shows there. Add the account again only after Muse has restored it. ```json { "error": "Account example@gmail.com: Muse has disabled the computer of account example@gmail.com (\"VM wake unavailable\"). Sign in at https://muse.ai in a browser to see why and contact Muse support there, then add the account again with POST /accounts", "code": 596 } ``` ##### Model One account's record: its `health`, `maxJobs`, session expiry, and its Muse plan and weekly usage in `quota`. <details markdown="block" class="model-details"> <summary>The account record and session state, field by field</summary> ```typescript { // TypeScript, all fields are optional email: string maxJobs: number // jobs this account may run at the same time added: string // ISO 8601, when the account was first added updated?: string // ISO 8601, the last re-add or maxJobs change sessionExpiresAt: string // ISO 8601, when the Muse session expires (30 days, renewed by the API) quota?: { // the account's Muse plan and weekly usage, as last read tier: string | null // Muse plan, e.g. HATCH_FREE percentUsed: number | null // share of the weekly allowance used, in whole percent resetsAt: string | null // ISO 8601, when the weekly allowance resets quotaStatus: string | null // SUFFICIENT while jobs may run topupBalance: number | null // top-up left, in Muse's own unit, not tokens topupTotal: number | null // top-up bought, in the same unit topupLabel: string | null // the top-up as muse.ai shows it, e.g. '0% used (1B tokens left)' readAt: string // ISO 8601, when this was read from Muse } health: string // 'OK', or why the account needs attention (596) videoLimitUntil?: string // ISO 8601, only while Muse's video limit for the last 24 hours holds the // account: video jobs skip it until then. A re-add clears it videoRegionBlocked?: string // ISO 8601, when Muse said video is not available for this account in its // country or region: video jobs skip it. A re-add clears it session?: 'signed-in' | 'checkpoint' | 'unknown' quotaError?: string // session 'unknown': why Muse did not answer the read error?: string // errors only code?: number // errors only } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/muse/accounts/example%40gmail.com" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously added account email"; const apiUrl = `https://api.useapi.net/v1/muse/accounts/${encodeURIComponent(email)}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests from urllib.parse import quote token = "API token" email = "Previously added account email" apiUrl = f"https://api.useapi.net/v1/muse/accounts/{quote(email, safe='')}" headers = { "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-muse-v1/get-muse-accounts === Document URL: https://useapi.net/docs/api-muse-v1/get-muse-accounts --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts description: "List every Muse account added to the useapi.net Muse API with GET accounts: health, maxJobs, session expiry and the weekly usage as last read, without calling Muse." parent: Muse API nav_order: 110 permalink: /docs/api-muse-v1/get-muse-accounts --- ## List Muse accounts October 12, 2026 (November 16, 2026) --- List the Muse accounts added with [POST /accounts](/docs/api-muse-v1/post-muse-accounts). Each entry shows the account's `health`, its `maxJobs`, when its session expires, and its plan and weekly usage as last read. This endpoint does not call Muse. For the live plan and usage use [GET /accounts/`email`](/docs/api-muse-v1/get-muse-accounts-email). [GET /jobs](/docs/api-muse-v1/get-muse-jobs) shows how many jobs each account is running. > **https://api.useapi.net/v1/muse/accounts** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** ```json { "example@gmail.com": { "email": "example@gmail.com", "maxJobs": 3, "added": "2026-10-12T00:34:19.139Z", "updated": "2026-10-12T01:29:14.234Z", "sessionExpiresAt": "2026-11-11T00:34:18.820Z", "quota": { "tier": "HATCH_FREE", "percentUsed": 0, "resetsAt": "2026-10-19T01:13:05.000Z", "quotaStatus": "SUFFICIENT", "topupBalance": 0, "topupTotal": 0, "topupLabel": null, "readAt": "2026-10-12T01:13:05.614Z" }, "health": "OK" } } ``` - The response is an object keyed by account email, or `{}` when no account is added. - `health` is `OK`, or the reason the account needs attention. Such an account is paused: it takes no new jobs until you add it again with [POST /accounts](/docs/api-muse-v1/post-muse-accounts). See [Setup Muse](/docs/start-here/setup-muse#if-the-account-needs-attention). - `quota` is updated when the account is added, on every [GET /accounts/`email`](/docs/api-muse-v1/get-muse-accounts-email), and when Muse refuses a job. - `videoLimitUntil` is shown only while the account sits out video jobs after Muse said it reached its [video limit](/docs/api-muse-v1/post-muse-jobs-video#video-limit) for the last 24 hours. Video jobs try it again after that time. Adding the account again with [POST /accounts](/docs/api-muse-v1/post-muse-accounts) clears it. - `videoRegionBlocked` is shown when Muse said video is not available for the account in its country or region. Video jobs skip the account until you add it again with [POST /accounts](/docs/api-muse-v1/post-muse-accounts). See [Generate a video](/docs/api-muse-v1/post-muse-jobs-video#video-limit). **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` ##### Model An object keyed by account email, each with its `health`, `maxJobs`, session expiry and last-read plan and usage. <details markdown="block" class="model-details"> <summary>Every account's record, keyed by email, field by field</summary> ```typescript { // TypeScript, all fields are optional [email: string]: { email: string maxJobs: number // jobs this account may run at the same time added: string // ISO 8601, when the account was first added updated?: string // ISO 8601, the last re-add or maxJobs change sessionExpiresAt: string // ISO 8601, when the Muse session expires (30 days, renewed by the API) quota?: { // the account's Muse plan and weekly usage, as last read tier: string | null // Muse plan, e.g. HATCH_FREE percentUsed: number | null // share of the weekly allowance used, in whole percent resetsAt: string | null // ISO 8601, when the weekly allowance resets quotaStatus: string | null // SUFFICIENT while jobs may run topupBalance: number | null // top-up left, in Muse's own unit, not tokens topupTotal: number | null // top-up bought, in the same unit topupLabel: string | null // the top-up as muse.ai shows it, e.g. '0% used (1B tokens left)' readAt: string // ISO 8601, when this was read from Muse } health: string // 'OK', or why the account needs attention (596) videoLimitUntil?: string // ISO 8601, only while Muse's video limit for the last 24 hours holds the // account: video jobs skip it until then. A re-add clears it videoRegionBlocked?: string // ISO 8601, when Muse said video is not available for this account in its // country or region: video jobs skip it. A re-add clears it } } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/muse/accounts" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = "https://api.useapi.net/v1/muse/accounts"; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" apiUrl = "https://api.useapi.net/v1/muse/accounts" headers = { "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-muse-v1/get-muse-assets-assetId === Document URL: https://useapi.net/docs/api-muse-v1/get-muse-assets-assetId --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> assets/`assetId` description: "Download any Muse Library item via GET assets/assetId in the useapi.net Muse API: images, videos, audio, documents (also as PDF), web apps as HTML, podcasts as MP3." parent: Muse API nav_order: 310 permalink: /docs/api-muse-v1/get-muse-assets-assetId --- ## Download an asset October 12, 2026 (November 16, 2026) --- Download a Library item by its `assetId`: an image, video or audio file from a finished job's `result.assets[]`, a chat's `file` event, an upload with [POST /assets](/docs/api-muse-v1/post-muse-assets), or any item of the account's Library in [GET /assets](/docs/api-muse-v1/get-muse-assets). The response body is the file itself, streamed from the Muse workspace of the account that holds it on each request. No copy is kept at useapi.net. What you get depends on the item's type: - `image`, `video`, `audio`: the file. - `document`: the file as the agent wrote it, for example `.md`, `.csv`, `.pdf` or `.pptx`. With `format=pdf`, an `md`, `txt` or `html` document comes as a PDF that Muse makes, which takes about 10 seconds. A PDF downloads as it is. - `web`: the web app as one HTML file, with its scripts and styles inside, named after the app. - `podcast`: the episode as MP3. With `part=cover`, the episode's cover image. Items stay in the account's Library until you delete them with [DELETE /assets/`assetId`](/docs/api-muse-v1/delete-muse-assets-assetId) or in the muse.ai app. An item that is no longer there answers `404`. > **https://api.useapi.net/v1/muse/assets/`assetId`?part=`part`&format=`format`** - `assetId` is URL-encoded in the path (it contains `:`), for example `user%3A12345-email%3A6578616d706c6540676d61696c2e636f6d-image%3Ad62d3099…jpg`. ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `part` is optional, for podcasts only. Supported values: `cover` (the episode's cover image). - `format` is optional, for `md`, `txt` and `html` documents only. Supported values: `pdf`. ##### Response headers - `Content-Type`: the file's type, for example `image/webp` for a generated image, `video/mp4` for a video, `text/markdown` for a Markdown document or `text/html` for a web app. - `Content-Disposition`: the file name. Images (except SVG), videos and audio come `inline`, every other file as an `attachment`. - `Content-Length`: when Muse sends the size. ##### Responses **200** **200 OK** The raw file bytes (not JSON), for example: ``` Content-Type: video/mp4 Content-Length: 3753558 Content-Disposition: inline; filename="media-generation-restored-portrait-animation-0-4322afa2-10d0-47b0-acc6-675a129aa78e.mp4" ``` **400** **400 Bad Request** The path value is not a Muse `assetId`, or `part` or `format` does not fit the item. ```json { "error": "Path parameter assetId (…) is not a valid Muse asset id (from GET /assets, POST /assets or a job result)", "code": 400 } ``` ```json { "error": "format=pdf is for documents of type md, txt, html, htm, pdf (a pdf downloads as is)", "code": 400 } ``` ```json { "error": "part=cover is for podcast assets only", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** The `assetId` was issued to a different API token. ```json { "error": "This asset id does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** The file is no longer in the account's Muse workspace, or the account that holds it is not added. ```json { "error": "This file is no longer in the Muse workspace of account example@gmail.com", "code": 404 } ``` ```json { "error": "This podcast has no cover", "code": 404 } ``` ```json { "error": "Account example@gmail.com (from the asset id) is not configured", "code": 404 } ``` **422** **422 Unprocessable Content** Muse could not convert the document to PDF. ```json { "error": "Muse could not convert this file (HTTP 400)", "code": 422 } ``` **502** **502 Bad Gateway** Muse did not send the file. Retry shortly. ```json { "error": "Muse did not send the file (…), please retry", "code": 502 } ``` **503** **503 Service Unavailable** Muse could not be reached. Retry shortly. ```json { "error": "Could not connect to the Muse workspace of account example@gmail.com (…), please retry shortly", "code": 503 } ``` **596** **596 Account Error** The account needs your attention, and it is paused until you add it again. You receive an email when this happens. There are three causes. Meta asks for a security check on the account. Sign in once at [muse.ai](https://muse.ai) in a browser, complete the check, then add the account again with [POST /accounts](/docs/api-muse-v1/post-muse-accounts) using the same email and password. The API keeps using its session, so no new sign-in is needed. ```json { "error": "Account example@gmail.com: Meta asks for a security check on account example@gmail.com (\"This account must complete a security checkpoint on the web\"). Sign in once at https://muse.ai in a browser, complete the check, then add the account again with POST /accounts", "code": 596 } ``` Or Muse refused to sign the account in again when its session needed renewing, most often because the password was changed. Add the account again with the current password. ```json { "error": "Account example@gmail.com: Muse refused to sign in account example@gmail.com (…). Update its password with POST /accounts, or sign in at https://muse.ai to clear the block, then re-add it", "code": 596 } ``` Or Muse disabled the account's computer and refuses to start it again. Sign in at [muse.ai](https://muse.ai) in a browser to see why, and ask Muse support to restore it with the form Muse shows there. Add the account again only after Muse has restored it. ```json { "error": "Account example@gmail.com: Muse has disabled the computer of account example@gmail.com (\"VM wake unavailable\"). Sign in at https://muse.ai in a browser to see why and contact Muse support there, then add the account again with POST /accounts", "code": 596 } ``` ##### Model A successful response is the file itself (not JSON), with the headers listed above. Errors return: <details markdown="block" class="model-details"> <summary>The error answer, field by field</summary> ```typescript { // TypeScript, all fields are optional error: string code: number } ``` </details> ##### Examples **Curl** ``` bash ASSETID="user:12345-email:6578616d706c6540676d61696c2e636f6d-video:media-generation-restored-portrait-animation-0-4322afa2-10d0-47b0-acc6-675a129aa78e.mp4" curl -H "Authorization: Bearer …" \ "https://api.useapi.net/v1/muse/assets/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$ASSETID")" \ --output video.mp4 ``` **JavaScript** ``` javascript const token = "API token"; const assetId = "assetId from a finished job, POST /assets or GET /assets"; const apiUrl = `https://api.useapi.net/v1/muse/assets/${encodeURIComponent(assetId)}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); if (!response.ok) console.log("error", response.status, await response.json()); else { const file = await response.arrayBuffer(); console.log("downloaded", file.byteLength, response.headers.get("content-type")); } ``` **Python** ``` python import requests from urllib.parse import quote token = "API token" assetId = "assetId from a finished job or POST /assets" apiUrl = "https://api.useapi.net/v1/muse/assets/" + quote(assetId, safe="") headers = { "Authorization" : f"Bearer {token}" } with requests.get(apiUrl, headers=headers, stream=True) as response: response.raise_for_status() with open("video.mp4", "wb") as f: for chunk in response.iter_content(chunk_size=1 << 20): f.write(chunk) ``` === URL: https://useapi.net/docs/api-muse-v1/get-muse-assets === Document URL: https://useapi.net/docs/api-muse-v1/get-muse-assets --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> assets description: "List a Muse account's whole Library via GET assets in the useapi.net Muse API: media, documents, web apps and podcasts as asset ids, newest first, filtered by type." parent: Muse API nav_order: 320 permalink: /docs/api-muse-v1/get-muse-assets --- ## List assets October 12, 2026 (November 16, 2026) --- List a Muse account's whole Library as asset ids, newest first, as the Library in the muse.ai app shows it. Each item has a `type`: - `image`, `video`, `audio`: media files, uploaded, generated by Muse or made by the agent. They work as inputs of a [job](/docs/api-muse-v1/post-muse-jobs-image) or a [chat](/docs/api-muse-v1/post-muse-chats). - `document`: a document the agent wrote or you added, such as Markdown, CSV, PDF or a presentation. It works in a chat's `files`, and an `md`, `txt` or `html` document also downloads as PDF. - `web`: a web app the agent built. It downloads as one HTML file, and can be published on a public link with [POST /assets/`assetId`/share](/docs/api-muse-v1/post-muse-assets-assetId-share). `shareUrl` is its public link while it is shared. - `podcast`: a podcast episode the agent made. It downloads as MP3, and its cover with `part=cover`. Each item downloads with [GET /assets/`assetId`](/docs/api-muse-v1/get-muse-assets-assetId) and can be removed with [DELETE /assets/`assetId`](/docs/api-muse-v1/delete-muse-assets-assetId). Muse may add other kinds to the Library later. They are listed with their own `type`, and with `assetId` `null` when the API cannot download them yet. Every item also carries Muse's own names for it, useful to match it to a workspace file or a reference in a chat, and to recognise a kind the API does not map yet: - `museRef` is Muse's own reference: `file:<workspace path>` for a media file or a document (the same path [GET /files](/docs/api-muse-v1/get-muse-files) shows), `space:<slug>` for a web app, `podcast:<slug>` for a podcast. - `museType` is Muse's own type name: `image`, `video` or `audio` for media, and for example `document`, `web` or `podcast` for the other kinds. `origin` tells where a media file came from: - `uploaded`: files you sent with [POST /assets](/docs/api-muse-v1/post-muse-assets). - `generated`: images and videos Muse generated, in a job, a chat or the muse.ai app. - `made`: files the agent made with its own tools, for example an edited video or a song. Read the next page with the `cursor` of the response, until `cursor` is `null`. New items go to the top of the list, so an item can show up again on the next page when items were added in between. `partial: true` means the list is not complete: a part of the Library could not be read right now, or the account has more than 500 media files and only the newest 500 are listed. > **https://api.useapi.net/v1/muse/assets?email=`email`&type=`type`&origin=`origin`&limit=`limit`&cursor=`cursor`** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `email` is optional when the API token has one Muse account, and **required** when it has more. URL-encode it. - `type` is optional, only items of this type. Supported values: `image`, `video`, `audio`, `document`, `web`, `podcast`, or any other `type` the list shows. - `origin` is optional, only media files of this origin. Supported values: `uploaded`, `generated`, `made`. - `limit` is optional, the most items per page. Range: `1` to `100`. Default: `50`. - `cursor` is optional, the `cursor` from the previous page, to read the next one. ##### Responses **200** **200 OK** ```json { "email": "example@gmail.com", "assets": [ { "assetId": "user:12345-email:6578616d706c6540676d61696c2e636f6d-image:media-generation-create-one-small-image-of-a-re-0-1b5617eb-685d-445f-a289-fdc9a792f696.webp", "type": "image", "origin": "generated", "mime": "image/webp", "bytes": 186402, "created": "2026-10-14T23:19:48.892Z", "name": "media-generation-create-one-small-image-of-a-re-0-1b5617eb-685d-445f-a289-fdc9a792f696.webp", "updated": "2026-10-14T23:19:48.892Z", "museType": "image", "museRef": "file:workspace/imagine_media/media-generation-create-one-small-image-of-a-re-0-1b5617eb-685d-445f-a289-fdc9a792f696.webp" }, { "assetId": "user:12345-email:6578616d706c6540676d61696c2e636f6d-podcast:podcast~why-dogs-wag-their-tails-2026-10-14", "type": "podcast", "format": "mp3", "name": "Why Dogs Wag Their Tails", "duration": 22, "created": "2026-10-14T21:58:35.735354+00:00", "updated": "2026-10-14T21:58:35.735354+00:00", "museType": "podcast", "museRef": "podcast:why-dogs-wag-their-tails-2026-10-14" }, { "assetId": "user:12345-email:6578616d706c6540676d61696c2e636f6d-web:space~hello-demo", "type": "web", "format": "html", "name": "Hello Demo", "created": "2026-10-14T21:55:06.000Z", "updated": "2026-10-14T21:56:07.000Z", "lastOpened": "2026-10-15T00:14:03.238Z", "museType": "web", "museRef": "space:hello-demo", "shareUrl": "https://muse.ai/s/hello-demo-k3v9q2m7xw4pzrt" }, { "assetId": "user:12345-email:6578616d706c6540676d61696c2e636f6d-document:ws~your_files~cat-facts.md", "type": "document", "format": "md", "name": "cat-facts.md", "created": null, "updated": "2026-10-14T21:54:45.663Z", "lastOpened": "2026-10-15T00:14:04.306Z", "museType": "document", "museRef": "file:workspace/your_files/cat-facts.md" } ], "cursor": "4" } ``` **400** **400 Bad Request** — a parameter is invalid, or the token has more than one Muse account and `email` is missing. ```json { "error": "Parameter origin (other) valid values: uploaded,generated,made", "code": 400 } ``` ```json { "error": "Pass email: this token has 3 Muse accounts", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **404** **404 Not Found** — the account named by `email` is not added. ```json { "error": "Account example@gmail.com is not configured", "code": 404 } ``` **503** **503 Service Unavailable** — Muse could not be reached. Retry shortly. ```json { "error": "Could not connect to the Muse workspace of account example@gmail.com (…), please retry shortly", "code": 503 } ``` **596** **596 Account Error** The account needs your attention, and it is paused until you add it again. You receive an email when this happens. There are three causes. Meta asks for a security check on the account. Sign in once at [muse.ai](https://muse.ai) in a browser, complete the check, then add the account again with [POST /accounts](/docs/api-muse-v1/post-muse-accounts) using the same email and password. The API keeps using its session, so no new sign-in is needed. ```json { "error": "Account example@gmail.com: Meta asks for a security check on account example@gmail.com (\"This account must complete a security checkpoint on the web\"). Sign in once at https://muse.ai in a browser, complete the check, then add the account again with POST /accounts", "code": 596 } ``` Or Muse refused to sign the account in again when its session needed renewing, most often because the password was changed. Add the account again with the current password. ```json { "error": "Account example@gmail.com: Muse refused to sign in account example@gmail.com (…). Update its password with POST /accounts, or sign in at https://muse.ai to clear the block, then re-add it", "code": 596 } ``` Or Muse disabled the account's computer and refuses to start it again. Sign in at [muse.ai](https://muse.ai) in a browser to see why, and ask Muse support to restore it with the form Muse shows there. Add the account again only after Muse has restored it. ```json { "error": "Account example@gmail.com: Muse has disabled the computer of account example@gmail.com (\"VM wake unavailable\"). Sign in at https://muse.ai in a browser to see why and contact Muse support there, then add the account again with POST /accounts", "code": 596 } ``` ##### Model One page of the account's Library, newest first, each item with its `assetId` and `type`, and a `cursor` for the next page. <details markdown="block" class="model-details"> <summary>The page of Library items, field by field</summary> ```typescript { // TypeScript, all fields are optional email: string assets: { assetId: string | null // download with GET /assets/{assetId}; null for a kind the API cannot download yet type: string // image, video, audio, document, web, podcast, or another kind Muse lists name: string | null // the file name, or the title of a web app or podcast created: string | null // ISO 8601 updated: string | null // ISO 8601, the list is sorted by it, newest first museType: string | null // Muse's own type name, e.g. image, video, audio, document, web, podcast museRef: string | null // Muse's own reference: file:<workspace path> (media, documents), space:<slug> or podcast:<slug> // media (image, video, audio) origin?: 'uploaded' | 'generated' | 'made' mime?: string | null // e.g. image/webp, video/mp4, audio/mpeg bytes?: number | null // document, web, podcast format?: string | null // e.g. md, csv, pdf, pptx for documents, html for web apps, mp3 for podcasts lastOpened?: string | null // ISO 8601, documents and web apps status?: string | null // web apps: the build status shareUrl?: string | null // web apps: the public link, null when not shared duration?: number | null // podcasts: seconds }[] cursor: string | null // pass it as cursor for the next page, null on the last page partial?: true // a part of the Library could not be read: the list is not complete error?: string // errors only code?: number // errors only } ``` </details> ##### Examples **Curl** ``` bash curl -H "Authorization: Bearer …" \ "https://api.useapi.net/v1/muse/assets?email=example%40gmail.com&type=video&limit=10" ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously added account email"; const all = []; let cursor = null; do { const params = new URLSearchParams({ email, origin: "generated", limit: "100" }); if (cursor) params.set("cursor", cursor); const response = await fetch(`https://api.useapi.net/v1/muse/assets?${params}`, { headers: { "Authorization": `Bearer ${token}` }, }); const page = await response.json(); all.push(...page.assets); cursor = page.cursor; } while (cursor); console.log(all.length, "generated files"); ``` **Python** ``` python import requests token = "API token" email = "Previously added account email" apiUrl = "https://api.useapi.net/v1/muse/assets" headers = { "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers, params={"email": email, "type": "video", "limit": 10}) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-muse-v1/get-muse-chats-chatId-browser-taskId === Document URL: https://useapi.net/docs/api-muse-v1/get-muse-chats-chatId-browser-taskId --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> chats/`chatId`/browser/`taskId` description: "Read the agent's browser in a chat via GET chats/chatId/browser/taskId in the useapi.net Muse API: the open page, who has control, and whether it can be watched live." parent: Muse API nav_order: 470 permalink: /docs/api-muse-v1/get-muse-chats-chatId-browser-taskId --- ## Read the agent's browser October 14, 2026 (November 16, 2026) --- The Muse agent can open a web browser on its own computer during a chat, for example to read a page, fill in a form or show you a site. Each browser arrives on the chat's [stream](/docs/api-muse-v1/get-muse-chats-chatId-stream) as a `browser` event with its `taskId`, and is listed in `browsers` of [GET /chats/`chatId`](/docs/api-muse-v1/get-muse-chats-chatId). This endpoint reads one browser now: the open page, who has control, whether it is on screen in a viewer, and the size of its display. While `previewAvailable` is `true`, you can watch the browser or take control of it with a [viewer link](/docs/api-muse-v1/post-muse-chats-chatId-browser-taskId-viewer). The [Live Browser Guide](/docs/api-muse-v1/live-browser-guide) walks through the whole flow. > **https://api.useapi.net/v1/muse/chats/`chatId`/browser/`taskId`** - `chatId` is URL-encoded in the path (it contains `:` and `@`). - `taskId` is the `taskId` of the chat's `browser` event. ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** ```json { "chatId": "c-u12345-email:example@gmail.com-chat:8e0bf21e-a3b5-4a1e-a05a-65d160469bfb-bot:muse", "email": "example@gmail.com", "taskId": "423bc12e-db16-4921-8670-08b5f3f5a5d6", "status": "Completed", "displayState": "completed", "stepTitle": "Open example.com in browser", "steps": 1, "site": "example.com", "url": "https://example.com/", "tabTitle": "Example Domain", "controlOwner": "agent", "previewAvailable": true, "parkedExpiresAt": "2026-10-15T01:06:42.438Z", "ended": false, "updated": "2026-10-14T23:06:42.438Z", "controlExpiresAt": null, "presented": false, "display": { "width": 1920, "height": 1080 } } ``` A browser that was closed answers with its last state, `ended: true` and `previewAvailable: false`. **400** **400 Bad Request** — the path holds no valid `chatId` or `taskId`. ```json { "error": "Path parameter taskId (not-a-task) is not a valid browser task id", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** — the `chatId` was issued to a different API token. ```json { "error": "This chat id does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** — the chat was deleted, the browser is not part of this chat's newest 1000 events, or the account that holds the chat is not added. ```json { "error": "Browser task not found in this chat", "code": 404 } ``` ```json { "error": "Chat not found", "code": 404 } ``` **502** **502 Bad Gateway** — Muse did not answer with the browser's state. Retry shortly. ```json { "error": "Muse refused to read the browser task (HTTP 500)", "code": 502 } ``` **503** **503 Service Unavailable** — Muse could not be reached. Retry shortly. ```json { "error": "Could not connect to the Muse workspace of account example@gmail.com (…), please retry shortly", "code": 503 } ``` **596** **596 Account Error** The account needs your attention, and it is paused until you add it again. You receive an email when this happens. There are three causes. Meta asks for a security check on the account. Sign in once at [muse.ai](https://muse.ai) in a browser, complete the check, then add the account again with [POST /accounts](/docs/api-muse-v1/post-muse-accounts) using the same email and password. The API keeps using its session, so no new sign-in is needed. ```json { "error": "Account example@gmail.com: Meta asks for a security check on account example@gmail.com (\"This account must complete a security checkpoint on the web\"). Sign in once at https://muse.ai in a browser, complete the check, then add the account again with POST /accounts", "code": 596 } ``` Or Muse refused to sign the account in again when its session needed renewing, most often because the password was changed. Add the account again with the current password. ```json { "error": "Account example@gmail.com: Muse refused to sign in account example@gmail.com (…). Update its password with POST /accounts, or sign in at https://muse.ai to clear the block, then re-add it", "code": 596 } ``` Or Muse disabled the account's computer and refuses to start it again. Sign in at [muse.ai](https://muse.ai) in a browser to see why, and ask Muse support to restore it with the form Muse shows there. Add the account again only after Muse has restored it. ```json { "error": "Account example@gmail.com: Muse has disabled the computer of account example@gmail.com (\"VM wake unavailable\"). Sign in at https://muse.ai in a browser to see why and contact Muse support there, then add the account again with POST /accounts", "code": 596 } ``` ##### Model The browser now: its open page, who has control, whether a viewer shows it, and the size of its display. <details markdown="block" class="model-details"> <summary>The browser's state, field by field, and the type it uses (<code>Browser</code>)</summary> The browser's fields, as in the stream's `browser` event: ```typescript type Browser = { // TypeScript: the agent's browser in a chat taskId: string // the browser's id in this chat, for /chats/{chatId}/browser/{taskId} status: string | null // e.g. Queued, Running, Completed, User controlled displayState: string | null // e.g. starting, working, completed, paused stepTitle: string | null // what the agent is doing, e.g. "Opening example page" steps: number | null // how many steps the agent took site: string | null // e.g. example.com url: string | null // the open page tabTitle: string | null // the open page's title controlOwner: string | null // agent or user previewAvailable: boolean // true: the browser is open and can be watched with a viewer link parkedExpiresAt: string | null // ISO 8601: the browser stays open until then after the agent's answer ended: boolean // true: the browser is closed for good updated: string | null // ISO 8601 } ``` This endpoint adds: ```typescript { // TypeScript, all fields are optional chatId: string email: string // the account the chat is on controlExpiresAt: string | null // ISO 8601: while you have control, when it returns to the agent unless a viewer keeps it presented: boolean // true: a viewer shows this browser now display: { // the size of the browser's display width: number | null height: number | null } error?: string // errors only code?: number // errors only } ``` </details> ##### Examples **Curl** ``` bash CHATID="c-u12345-email:example@gmail.com-chat:8e0bf21e-a3b5-4a1e-a05a-65d160469bfb-bot:muse" TASKID="423bc12e-db16-4921-8670-08b5f3f5a5d6" curl -H "Authorization: Bearer …" \ "https://api.useapi.net/v1/muse/chats/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$CHATID")/browser/$TASKID" ``` **JavaScript** ``` javascript const token = "API token"; const chatId = "chatId from POST /chats"; const taskId = "taskId from the stream's browser event"; const apiUrl = `https://api.useapi.net/v1/muse/chats/${encodeURIComponent(chatId)}/browser/${encodeURIComponent(taskId)}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", response.status, result); ``` **Python** ``` python import requests from urllib.parse import quote token = "API token" chatId = "chatId from POST /chats" taskId = "taskId from the stream's browser event" apiUrl = f"https://api.useapi.net/v1/muse/chats/{quote(chatId, safe='')}/browser/{quote(taskId, safe='')}" headers = { "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-muse-v1/get-muse-chats-chatId-stream === Document URL: https://useapi.net/docs/api-muse-v1/get-muse-chats-chatId-stream --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> chats/`chatId`/stream description: "Follow a Muse chat live via GET chats/chatId/stream in the useapi.net Muse API: Server-Sent Events with text, files, reactions and the agent's browser, resumable." parent: Muse API nav_order: 410 permalink: /docs/api-muse-v1/get-muse-chats-chatId-stream --- ## Stream a chat October 12, 2026 (November 20, 2026) --- Follow a chat live as [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) (SSE): your messages, the agent's text as it is written, the files it makes, its reactions, the web browser it works in, and the end of each answer. One stream covers the whole chat, across every answer, until you close it. Start a chat with [POST /chats](/docs/api-muse-v1/post-muse-chats) and send more with [POST /chats/`chatId`/messages](/docs/api-muse-v1/post-muse-chats-chatId-messages). The [Chat Streaming Guide](/docs/api-muse-v1/chat-streaming-guide) has the full event reference and complete readers in JavaScript and Python. Read the stream with `fetch()` or any HTTP client that can send the `Authorization` header. The browser's `EventSource` cannot send it. - Each event is a `data:` line with one JSON object. Its `event` field names the event, see [Events](#events). - Some events also carry an `id:` line. An `id` appears only when everything up to it is complete. - To resume after a disconnect, reconnect with the last `id` you received, in the `Last-Event-ID` header or as `?after=`. After `idle` (10 quiet minutes) or `reconnect` (60 minutes, or Muse closed a quiet connection), reconnect the same way if you still want live updates, for example while the chat is on screen, or else when you next need it. Either way the stream resumes exactly where it left off: messages you missed are replayed, with no history reload, and then it goes on live. - A fresh stream (no `Last-Event-ID`) replays the newest 1000 chat events. Older messages are in [GET /chats/`chatId`](/docs/api-muse-v1/get-muse-chats-chatId) with `before`. - A `keepalive` event comes every 15 seconds. When nothing happens for 10 minutes, an `idle` event comes and the stream closes. One connection lasts at most 60 minutes: a `reconnect` event comes, and the stream closes. A `reconnect` also comes when Muse closed a quiet connection before that: the stream stays open while Muse is quiet, and you reconnect the same way. - Each account can have about 50 streams open at the same time. More answer `429`. The count is approximate: a connection you close is noticed within about a minute, so a quick burst of reconnects can briefly count more streams than are really open. Keep one stream per chat. [GET /chats/streams](/docs/api-muse-v1/get-muse-chats-streams) shows the count. A stream that fails shows in your [usage stats](/docs/account-management/get-account-stats) (`bot=muse`) as model `muse-stream`, with status `failed` or `dropped`. Streams that open and run normally do not appear there. To spot a reconnect loop, watch the count on [GET /chats/streams](/docs/api-muse-v1/get-muse-chats-streams). > **https://api.useapi.net/v1/muse/chats/`chatId`/stream?after=`after`** - `chatId` is URL-encoded in the path (it contains `:` and `@`), from [POST /chats](/docs/api-muse-v1/post-muse-chats) or [GET /chats](/docs/api-muse-v1/get-muse-chats). ##### Request Headers ``` yaml Authorization: Bearer {API token} Last-Event-ID: 1266 # optional, resume after this id ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. - `Last-Event-ID` is optional, the last `id` you received. The stream sends what came after it. ##### Query Parameters - `after` is optional, the same as `Last-Event-ID`, for clients that cannot set headers. The header wins when both are sent. Default: `0`, the newest 1000 chat events, then live. ##### Events | Event | Fields | Meaning | |---|---|---| | `initialized` | `chatId`, `email`, `after` | The stream is open. Always first. | | `replayed` | `lastEventId` | Sent once, after the replay of earlier events: everything after it is live. `lastEventId` is the last event id sent so far, or the `after` you resumed from. You can ignore it. | | `message` | `messageId`, `text`, `files` | A message you sent, with its media files as asset ids and other files as workspace paths. Also a message sent while Muse was answering. | | `activity` | `text` | What the agent is doing, for example `is working`, `Generating image`. | | `text` | `messageId`, `text`, `full` | A piece of the agent's message. Join the pieces with the same `messageId`. With `full: true` the event holds the whole message text and replaces any earlier pieces of that message. A link the agent presents on its own, such as a share link, arrives as a message whose whole text is the link (`full: true`). | | `message.done` | `messageId` | The agent's message is complete. | | `widget` | `messageId`, `widgetId`, `kind`, `text`, `fallbackText`, `options`, `html`, `name`, `summary`, `status`, `assetId`, `title`, `subtitle`, `linkType`, `url`, `connectorId`, `imageUrl`, `data` | An interactive card in the agent's message: quick-reply `options`, an `html` card to show only in a sandboxed iframe, a web app the agent built (`kind` `space_build_completed`, with its `name`, `summary`, `status` and `assetId`), a link card (`kind` `internal_link_action_card`, with its `title`, `subtitle`, `linkType`, `url`, `connectorId` and `imageUrl`), or other `data`. A link card asks for something only Muse's own site can do, such as connecting Google Calendar: the account's owner opens its `url` signed in to Muse as that account, then continues the chat. Show `fallbackText` for a kind you can't render. See [Answer a widget](/docs/api-muse-v1/post-muse-chats-chatId-widgets-widgetId). A widget can also come on its own, with no text in its message. | | `file` | `messageId`, `assetId`, `type`, `mime`, `bytes`, `origin`, `podcastId` | A file the agent made or showed: an image, video or audio file, or a `document` such as Markdown, CSV or a presentation. `origin` is `generated` for an image or video Muse generated, `made` for a file the agent made with its own tools, such as an edited video. Audio of a podcast episode also has `podcastId`, the podcast's asset id, which gives its cover with `?part=cover`. A file comes once per answer, and again under a later answer that shows the same file: de-duplicate by `assetId` if you keep a file list. Download it with [GET /assets/`assetId`](/docs/api-muse-v1/get-muse-assets-assetId). | | `reaction` | `messageId`, `reactions` | The reactions on a message changed, for example the agent reacted with 👍 to your message. `reactions` is the message's whole set now. React yourself with [POST /chats/`chatId`/messages/`messageId`/reactions](/docs/api-muse-v1/post-muse-chats-chatId-messages-messageId-reactions). | | `browser` | `taskId`, `status`, `displayState`, `stepTitle`, `steps`, `site`, `url`, `tabTitle`, `controlOwner`, `previewAvailable`, `parkedExpiresAt`, `ended`, `updated` | The agent opened a web browser, or its browser changed. Each event holds the browser's whole state: keep the latest per `taskId`. While `previewAvailable` is `true`, watch it or take control with a [viewer link](/docs/api-muse-v1/post-muse-chats-chatId-browser-taskId-viewer). A resumed stream sends each browser's latest state again. See the [Live Browser Guide](/docs/api-muse-v1/live-browser-guide). | | `status` | `status` | The chat's state from Muse, for example `running`, `pending_user_confirmation`, `user_confirmed` or `user_denied`, `completed`, `interrupted`. `pending_user_confirmation` means this chat waits for an answer to one of its own `approval` requests, and `user_confirmed` or `user_denied` follows your answer. A chat never shows waiting for another chat's request. | | `approval` | `approvalId`, `title`, `question`, `details`, `options`, `expires` | The agent asks for permission before an action. The answer pauses (`status` `pending_user_confirmation`) until you answer with [POST /chats/`chatId`/approvals/`approvalId`](/docs/api-muse-v1/post-muse-chats-chatId-approvals-approvalId), or the request expires. | | `approval.resolved` | `approvalId`, `status`, `decision` | One of this chat's requests ended: `approved`, `denied` or timed out. Sent once per request. | | `turn.done` | `status`, `files` | The answer ended: `completed` or `interrupted` (cancelled). `files` lists every image, video and audio file of this answer. | | `error` | `code`, `message` | The connection to Muse broke. Reconnect with `Last-Event-ID`. | | `keepalive` | | Sent every 15 seconds. | | `idle` | `message` | Nothing happened for 10 minutes. The stream closes. | | `reconnect` | `message` | The connection reached 60 minutes, or Muse closed a quiet connection ("Muse closed the quiet connection. Reconnect with Last-Event-ID to continue"). The stream closes: reconnect with `Last-Event-ID`. | ##### Responses **200** **200 OK** — `Content-Type: text/event-stream`. A chat that asked for an image (text pieces shortened): ``` data: {"event":"initialized","chatId":"c-u12345-email:example@gmail.com-chat:272b73f4-6fcb-42c2-9ec7-75cc0c020940-bot:muse","email":"example@gmail.com","after":0} data: {"event":"status","status":"running"} id: 1270 data: {"event":"message","messageId":"3a1a5487-51a4-42a6-9ae1-b7c6b3ea247f","text":"Create one small image of a red apple on a white table.","files":[]} data: {"event":"activity","text":"Generating image"} data: {"event":"text","messageId":"assistant-msg-92cffe58-3184-44c6-a1ee-cb620081f72a","text":"Here it is."} data: {"event":"file","messageId":"51657274-51ff-4669-9e98-6786d03f206e","assetId":"user:12345-email:6578616d706c6540676d61696c2e636f6d-image:media-generation-create-one-small-image-of-a-re-0-1b5617eb-685d-445f-a289-fdc9a792f696.webp","type":"image","mime":"image/webp","bytes":186402,"origin":"generated"} id: 1272 data: {"event":"message.done","messageId":"assistant-msg-92cffe58-3184-44c6-a1ee-cb620081f72a"} data: {"event":"status","status":"completed"} data: {"event":"turn.done","status":"completed","files":[{"assetId":"user:12345-email:6578616d706c6540676d61696c2e636f6d-image:media-generation-create-one-small-image-of-a-re-0-1b5617eb-685d-445f-a289-fdc9a792f696.webp","type":"image","mime":"image/webp","bytes":186402}]} data: {"event":"keepalive"} ``` **400** **400 Bad Request** — the path value is not a Muse `chatId`, or `after` is not a number. ```json { "error": "Path parameter chatId (not-a-chat-id) is not a valid Muse chat id", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** — the `chatId` was issued to a different API token. ```json { "error": "This chat id does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** — the chat was deleted, or the account that holds it is not added. ```json { "error": "Chat not found", "code": 404 } ``` **429** **429 Too Many Requests** — the account has about 50 streams open. Close the ones you no longer read, and keep one stream per chat. The response carries `Retry-After: 60`. ```json { "error": "Account example@gmail.com has about 50 open chat streams. Close some (a closed connection is noticed within about a minute), or keep one stream per chat", "code": 429 } ``` **503** **503 Service Unavailable** — Muse could not be reached. Retry shortly. ```json { "error": "Could not connect to the Muse workspace of account example@gmail.com (…), please retry shortly", "code": 503 } ``` **596** **596 Account Error** The account needs your attention, and it is paused until you add it again. You receive an email when this happens. There are three causes. Meta asks for a security check on the account. Sign in once at [muse.ai](https://muse.ai) in a browser, complete the check, then add the account again with [POST /accounts](/docs/api-muse-v1/post-muse-accounts) using the same email and password. The API keeps using its session, so no new sign-in is needed. ```json { "error": "Account example@gmail.com: Meta asks for a security check on account example@gmail.com (\"This account must complete a security checkpoint on the web\"). Sign in once at https://muse.ai in a browser, complete the check, then add the account again with POST /accounts", "code": 596 } ``` Or Muse refused to sign the account in again when its session needed renewing, most often because the password was changed. Add the account again with the current password. ```json { "error": "Account example@gmail.com: Muse refused to sign in account example@gmail.com (…). Update its password with POST /accounts, or sign in at https://muse.ai to clear the block, then re-add it", "code": 596 } ``` Or Muse disabled the account's computer and refuses to start it again. Sign in at [muse.ai](https://muse.ai) in a browser to see why, and ask Muse support to restore it with the form Muse shows there. Add the account again only after Muse has restored it. ```json { "error": "Account example@gmail.com: Muse has disabled the computer of account example@gmail.com (\"VM wake unavailable\"). Sign in at https://muse.ai in a browser to see why and contact Muse support there, then add the account again with POST /accounts", "code": 596 } ``` ##### Model Each `data:` line is one JSON event whose `event` field names it, such as `text`, `file`, `browser` or `turn.done`. <details markdown="block" class="model-details"> <summary>Each stream event, field by field, and the types it uses (<code>StreamEvent</code>, <code>Browser</code>)</summary> Each `data:` line holds one of these objects: ```typescript type StreamEvent = // TypeScript | { event: 'initialized', chatId: string, email: string, after: number } | { event: 'replayed', lastEventId: number } // once: the replay is done, everything after is live | { event: 'message', messageId: string, text: string, files: string[] } // your message: media as asset ids, other files as workspace paths | { event: 'activity', text: string } // e.g. "is working", "Generating image" | { event: 'text', messageId: string, text: string, full?: true } // full: the whole text, replaces earlier pieces | { event: 'message.done', messageId: string } | { event: 'widget', messageId?: string, widgetId: string, // an interactive card in the agent's message kind: string, text: string | null, fallbackText: string | null, // show fallbackText for a kind you can't render options?: string[], // kind option: quick replies, answer with POST /chats/{chatId}/widgets/{widgetId} html?: string, // kind html: a card to show only in a sandboxed iframe name?: string, summary?: string, status?: string, // kind space_build_completed: a web app the agent built assetId?: string | null, // and its asset id (GET /assets/{assetId}) title?: string, subtitle?: string, linkType?: string, // kind internal_link_action_card: something to do on Muse's site, url?: string | null, connectorId?: string, imageUrl?: string, // opened by the account's owner signed in to Muse data?: Record<string, unknown> } // any other kind: Muse's widget data as it is | { event: 'file', messageId?: string, assetId: string, type: 'image' | 'video' | 'audio', mime: string, bytes: number, origin: 'generated' | 'made', // made: by the agent's own tools. Once per answer: a later answer may send the same file again podcastId?: string } // audio of a podcast: the podcast's asset id (its cover: GET /assets/{podcastId}?part=cover) | { event: 'file', messageId?: string, assetId: string, // a document the agent showed (md, csv, pdf, pptx…) type: 'document', mime: string, bytes: number, origin: string } | { event: 'browser' } & Browser // the agent's browser changed, see Browser below | { event: 'reaction', messageId: string, reactions: string[] } // the message's reactions now, e.g. ["👍"] | { event: 'status', status: string } // e.g. running, pending_user_confirmation (this chat waits for its own approval), user_confirmed / user_denied (after your answer), completed | { event: 'approval' // the agent asks for permission approvalId: string title: string | null // e.g. "Share info with deb.nodesource.com" question: string | null // e.g. "Allow Muse to share information with deb.nodesource.com?" details: { label: string, value: string }[] // e.g. Host, Grants, Method options: { decision: string, label: string }[] // e.g. allow_once "Allow once", deny "Deny" expires: string | null // ISO 8601, unanswered requests time out then } | { event: 'approval.resolved', approvalId: string, // once, when one of this chat's requests ends status: string, decision: string | null } // e.g. approved / allow_once, denied / deny, timed_out | { event: 'turn.done', status: 'completed' | 'interrupted', files: { assetId: string, type: 'image' | 'video' | 'audio', mime: string, bytes: number }[] } | { event: 'error', code: number, message: string } // reconnect with Last-Event-ID | { event: 'keepalive' } // every 15 seconds | { event: 'idle', message: string } // 10 quiet minutes, the stream closes | { event: 'reconnect', message: string } // 60 minutes reached, the stream closes ``` ```typescript type Browser = { // TypeScript: the agent's browser in a chat taskId: string // the browser's id in this chat, for /chats/{chatId}/browser/{taskId} status: string | null // e.g. Queued, Running, Completed, User controlled displayState: string | null // e.g. starting, working, completed, paused stepTitle: string | null // what the agent is doing, e.g. "Opening example page" steps: number | null // how many steps the agent took site: string | null // e.g. example.com url: string | null // the open page tabTitle: string | null // the open page's title controlOwner: string | null // agent or user previewAvailable: boolean // true: the browser is open and can be watched with a viewer link parkedExpiresAt: string | null // ISO 8601: the browser stays open until then after the agent's answer ended: boolean // true: the browser is closed for good updated: string | null // ISO 8601 } ``` Errors before the stream opens return `{ error, code }` as JSON. </details> ##### Examples **Curl** ``` bash CHATID="c-u12345-email:example@gmail.com-chat:272b73f4-6fcb-42c2-9ec7-75cc0c020940-bot:muse" curl -N -H "Authorization: Bearer …" \ "https://api.useapi.net/v1/muse/chats/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$CHATID")/stream" ``` The `-N` flag turns off buffering, so events print as they arrive. **JavaScript** ``` javascript const token = "API token"; const chatId = "chatId from POST /chats"; const response = await fetch(`https://api.useapi.net/v1/muse/chats/${encodeURIComponent(chatId)}/stream`, { headers: { "Authorization": `Bearer ${token}` }, }); const reader = response.body.getReader(); const decoder = new TextDecoder(); let buffer = ""; for (;;) { const { done, value } = await reader.read(); if (done) break; buffer += decoder.decode(value, { stream: true }); const blocks = buffer.split("\n\n"); buffer = blocks.pop(); for (const block of blocks) { const data = block.split("\n").find(line => line.startsWith("data:")); if (!data) continue; const e = JSON.parse(data.slice(5)); if (e.event === "text") process.stdout.write(e.text); if (e.event === "file") console.log("\nfile", e.assetId); if (e.event === "turn.done") console.log("\nanswer done:", e.status); } } ``` **Python** ``` python import json, requests from urllib.parse import quote token = "API token" chatId = "chatId from POST /chats" apiUrl = f"https://api.useapi.net/v1/muse/chats/{quote(chatId, safe='')}/stream" headers = {"Authorization": f"Bearer {token}"} with requests.get(apiUrl, headers=headers, stream=True) as response: for line in response.iter_lines(decode_unicode=True): if not line or not line.startswith("data:"): continue e = json.loads(line[5:]) if e["event"] == "text": print(e["text"], end="", flush=True) elif e["event"] == "file": print("\nfile", e["assetId"]) elif e["event"] == "turn.done": print("\nanswer done:", e["status"]) ``` === URL: https://useapi.net/docs/api-muse-v1/get-muse-chats-chatId === Document URL: https://useapi.net/docs/api-muse-v1/get-muse-chats-chatId --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> chats/`chatId` description: "Read a Muse chat as JSON via GET chats/chatId in the useapi.net Muse API: messages with files, widgets and reactions, the agent's browsers, paged with before." parent: Muse API nav_order: 450 permalink: /docs/api-muse-v1/get-muse-chats-chatId --- ## Read a chat October 12, 2026 (November 20, 2026) --- Read a chat as JSON: its title and status, its messages in order, yours and the agent's, with their files as asset ids and their reactions, and the browsers the agent opened. Use it to show a past chat, or to catch up without a stream. For the live answer, use [GET /chats/`chatId`/stream](/docs/api-muse-v1/get-muse-chats-chatId-stream). A response holds the latest part of the chat, in order from oldest to newest. When `hasMore` is `true`, pass the `before` value of the response as `before` to read the older messages. > **https://api.useapi.net/v1/muse/chats/`chatId`?limit=`limit`&before=`before`** - `chatId` is URL-encoded in the path (it contains `:` and `@`), from [POST /chats](/docs/api-muse-v1/post-muse-chats) or [GET /chats](/docs/api-muse-v1/get-muse-chats). ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `limit` is optional, how many chat events to read, counting each message and each file. Range: `1` to `1000`. Default: `1000`. - `before` is optional, the `before` value from the previous response, to read older messages. ##### Responses **200** **200 OK** (long texts shortened) ```json { "chatId": "c-u12345-email:example@gmail.com-chat:272b73f4-6fcb-42c2-9ec7-75cc0c020940-bot:muse", "title": "Write a sea story", "snippet": "Create one small image of a red apple on a white table.", "status": "completed", "created": "2026-10-12T23:19:01.000Z", "updated": "2026-10-12T23:19:50.000Z", "email": "example@gmail.com", "messages": [ { "messageId": "389bfe1b-d8a0-47ed-9b11-d9269a8ed656", "role": "user", "text": "Write a 300-word story about the sea. Text only, no files.", "files": [] }, { "messageId": "assistant-msg-c736fee5-9539-4ac0-8d59-30afb00a10d1", "role": "assistant", "text": "The tide came in like an apology.\n\nMara had been counting gulls from the breakwater since morning…", "files": [] }, { "messageId": "3a1a5487-51a4-42a6-9ae1-b7c6b3ea247f", "role": "user", "text": "Create one small image of a red apple on a white table.", "files": [], "reactions": ["👍"] }, { "messageId": "assistant-msg-92cffe58-3184-44c6-a1ee-cb620081f72a", "role": "assistant", "text": "Here it is.", "files": [] }, { "messageId": "51657274-51ff-4669-9e98-6786d03f206e", "role": "assistant", "text": "", "files": [ { "assetId": "user:12345-email:6578616d706c6540676d61696c2e636f6d-image:media-generation-create-one-small-image-of-a-re-0-1b5617eb-685d-445f-a289-fdc9a792f696.webp", "type": "image", "mime": "image/webp", "bytes": 186402, "origin": "generated" } ] } ], "browsers": [], "pendingApprovals": [], "hasMore": false, "before": 1263 } ``` - A user message lists its media files as asset ids, and other files as their workspace path. An agent message lists its files as objects with `assetId`, `type`, `mime`, `bytes` and `origin`. - The agent may send a file as a message of its own, with empty `text`. A link it presents on its own, such as a share link it created, is an agent message whose `text` is the link. - An agent message can carry `widgets`, interactive cards such as quick-reply choices or an HTML chart, in the same shape as the stream's `widget` event. See [POST /chats/`chatId`/widgets/`widgetId`](/docs/api-muse-v1/post-muse-chats-chatId-widgets-widgetId). - A message can carry `reactions`, the emoji on it from you and the agent, as the stream's `reaction` event. React with [POST /chats/`chatId`/messages/`messageId`/reactions](/docs/api-muse-v1/post-muse-chats-chatId-messages-messageId-reactions). - An agent message lists the documents it showed as files of `type` `document`, and a podcast episode as an `audio` file with a `podcastId`. - `browsers` lists the web browsers the agent opened in this part of the chat, each in its latest state, as the stream's `browser` event, plus `afterMessageId`: the message the browser came after, to show it at the right place. See the [Live Browser Guide](/docs/api-muse-v1/live-browser-guide). - `pendingApprovals` lists the agent's permission requests in this chat that wait for an answer, in the same shape as the stream's `approval` event without `event`. Answer one with [POST /chats/`chatId`/approvals/`approvalId`](/docs/api-muse-v1/post-muse-chats-chatId-approvals-approvalId). **400** **400 Bad Request** — the path value is not a Muse `chatId`, or a parameter is invalid. ```json { "error": "Path parameter chatId (not-a-chat-id) is not a valid Muse chat id", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** — the `chatId` was issued to a different API token. ```json { "error": "This chat id does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** — the chat was deleted, or the account that holds it is not added. ```json { "error": "Chat not found", "code": 404 } ``` **503** **503 Service Unavailable** — Muse could not be reached. Retry shortly. ```json { "error": "Could not connect to the Muse workspace of account example@gmail.com (…), please retry shortly", "code": 503 } ``` **596** **596 Account Error** The account needs your attention, and it is paused until you add it again. You receive an email when this happens. There are three causes. Meta asks for a security check on the account. Sign in once at [muse.ai](https://muse.ai) in a browser, complete the check, then add the account again with [POST /accounts](/docs/api-muse-v1/post-muse-accounts) using the same email and password. The API keeps using its session, so no new sign-in is needed. ```json { "error": "Account example@gmail.com: Meta asks for a security check on account example@gmail.com (\"This account must complete a security checkpoint on the web\"). Sign in once at https://muse.ai in a browser, complete the check, then add the account again with POST /accounts", "code": 596 } ``` Or Muse refused to sign the account in again when its session needed renewing, most often because the password was changed. Add the account again with the current password. ```json { "error": "Account example@gmail.com: Muse refused to sign in account example@gmail.com (…). Update its password with POST /accounts, or sign in at https://muse.ai to clear the block, then re-add it", "code": 596 } ``` Or Muse disabled the account's computer and refuses to start it again. Sign in at [muse.ai](https://muse.ai) in a browser to see why, and ask Muse support to restore it with the form Muse shows there. Add the account again only after Muse has restored it. ```json { "error": "Account example@gmail.com: Muse has disabled the computer of account example@gmail.com (\"VM wake unavailable\"). Sign in at https://muse.ai in a browser to see why and contact Muse support there, then add the account again with POST /accounts", "code": 596 } ``` ##### Model The chat's title and status, its latest messages in order with their files, reactions and widgets, its browsers and pending approvals. <details markdown="block" class="model-details"> <summary>The chat with its messages, browsers and approvals, field by field, and the type it uses (<code>Browser</code>)</summary> ```typescript { // TypeScript, all fields are optional chatId: string title: string | null snippet: string | null // the start of the latest message status: string | null // e.g. running, completed, interrupted created: string | null // ISO 8601 updated: string | null // ISO 8601 pinned?: true archived?: true email: string // the account the chat is on messages: { messageId: string role: 'user' | 'assistant' text: string files: (string | { // user: asset ids, or workspace paths of other files; assistant: the files it made assetId: string // download it with GET /assets/{assetId} type: 'image' | 'video' | 'audio' | 'document' mime: string bytes: number origin: string // generated or made, as the stream's file event podcastId?: string // audio of a podcast: the podcast's asset id })[] reactions?: string[] // e.g. ["👍"], as the stream's reaction event widgets?: { // assistant: interactive cards in the message, as the stream's widget event widgetId: string // answer kind option with POST /chats/{chatId}/widgets/{widgetId} kind: string // option, html, or another kind text: string | null fallbackText: string | null // show it for a kind you can't render options?: string[] // kind option: the quick replies html?: string // kind html: show only in a sandboxed iframe (sandbox="allow-scripts") name?: string // kind space_build_completed: a web app the agent built, with summary, status summary?: string status?: string assetId?: string | null // kind space_build_completed: the web app's asset id title?: string // kind internal_link_action_card: something to do on Muse's own site, subtitle?: string // e.g. title "Google Calendar", subtitle "Connector", linkType "connector" linkType?: string url?: string | null // kind internal_link_action_card: open it signed in to Muse as this account connectorId?: string // e.g. google_calendar, for a connector imageUrl?: string // Muse's icon for it data?: Record<string, unknown> // any other kind: Muse's widget data as it is }[] }[] browsers: (Browser & { // the agent's browsers in this page of the chat, see Browser below afterMessageId?: string // the last message before the browser first appeared })[] pendingApprovals: { // permission requests waiting for an answer, see POST /chats/{chatId}/approvals/{approvalId} approvalId: string title: string | null question: string | null details: { label: string, value: string }[] options: { decision: string, label: string }[] // e.g. allow_once, allow_always, deny expires: string | null // ISO 8601 }[] hasMore: boolean // older messages exist before?: number // pass as before to read the older messages error?: string // errors only code?: number // errors only } ``` ```typescript type Browser = { // TypeScript: the agent's browser in a chat taskId: string // the browser's id in this chat, for /chats/{chatId}/browser/{taskId} status: string | null // e.g. Queued, Running, Completed, User controlled displayState: string | null // e.g. starting, working, completed, paused stepTitle: string | null // what the agent is doing, e.g. "Opening example page" steps: number | null // how many steps the agent took site: string | null // e.g. example.com url: string | null // the open page tabTitle: string | null // the open page's title controlOwner: string | null // agent or user previewAvailable: boolean // true: the browser is open and can be watched with a viewer link parkedExpiresAt: string | null // ISO 8601: the browser stays open until then after the agent's answer ended: boolean // true: the browser is closed for good updated: string | null // ISO 8601 } ``` </details> ##### Examples **Curl** ``` bash CHATID="c-u12345-email:example@gmail.com-chat:272b73f4-6fcb-42c2-9ec7-75cc0c020940-bot:muse" curl -H "Authorization: Bearer …" \ "https://api.useapi.net/v1/muse/chats/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$CHATID")" ``` **JavaScript** ``` javascript const token = "API token"; const chatId = "chatId from POST /chats or GET /chats"; const apiUrl = `https://api.useapi.net/v1/muse/chats/${encodeURIComponent(chatId)}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const chat = await response.json(); for (const m of chat.messages ?? []) console.log(`${m.role}: ${m.text}`, m.files); ``` **Python** ``` python import requests from urllib.parse import quote token = "API token" chatId = "chatId from POST /chats or GET /chats" apiUrl = f"https://api.useapi.net/v1/muse/chats/{quote(chatId, safe='')}" headers = { "Authorization" : f"Bearer {token}" } chat = requests.get(apiUrl, headers=headers).json() for m in chat.get("messages", []): print(f"{m['role']}: {m['text']}", m["files"]) ``` === URL: https://useapi.net/docs/api-muse-v1/get-muse-chats-streams === Document URL: https://useapi.net/docs/api-muse-v1/get-muse-chats-streams --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> chats/streams description: "See the open chat streams of a Muse account via GET chats/streams in the useapi.net Muse API: an approximate count against the limit of about 50, per chat." parent: Muse API nav_order: 415 permalink: /docs/api-muse-v1/get-muse-chats-streams --- ## List open streams October 12, 2026 (November 16, 2026) --- List the chat streams open on a Muse account, see [GET /chats/`chatId`/stream](/docs/api-muse-v1/get-muse-chats-chatId-stream). Each account can have about 50 streams open at the same time. The count is approximate. A connection you close is noticed within about a minute, so right after a quick burst of reconnects the list can show more streams than are really open. Keep one stream per chat. A stream that fails also shows in your [usage stats](/docs/account-management/get-account-stats) (`bot=muse`) as model `muse-stream`, with status `failed` or `dropped`. Streams that open normally do not appear there, so this list is the place to spot a reconnect loop. > **https://api.useapi.net/v1/muse/chats/streams?email=`email`** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `email` is optional when the API token has one Muse account, and **required** when it has more. URL-encode it. ##### Responses **200** **200 OK** ```json { "email": "example@gmail.com", "count": 2, "limit": 50, "approximate": true, "streams": [ { "chatId": "c-u12345-email:example@gmail.com-chat:30db952d-8996-4e58-b679-cd469ce6d711-bot:muse", "opened": "2026-10-13T03:16:03.120Z", "seen": "2026-10-13T03:21:03.402Z" }, { "chatId": "c-u12345-email:example@gmail.com-chat:272b73f4-6fcb-42c2-9ec7-75cc0c020940-bot:muse", "opened": "2026-10-13T03:18:41.877Z", "seen": "2026-10-13T03:18:41.877Z" } ] } ``` **400** **400 Bad Request** — the token has more than one Muse account and `email` is missing. ```json { "error": "Pass email: this token has 3 Muse accounts", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **404** **404 Not Found** — the account named by `email` is not added. ```json { "error": "Account example@gmail.com is not configured", "code": 404 } ``` ##### Model The approximate count of chat streams open on the account, its limit, and each stream's `chatId` and times. <details markdown="block" class="model-details"> <summary>The account's open streams, field by field</summary> ```typescript { // TypeScript, all fields are optional email: string count: number // open streams, approximate limit: number // about how many streams the account can have open approximate: true streams: { chatId: string // the chat the stream follows opened: string // ISO 8601, when it opened seen: string // ISO 8601, when the connection last reported in (about every 5 minutes while open) }[] error?: string // errors only code?: number // errors only } ``` </details> ##### Examples **Curl** ``` bash curl -H "Authorization: Bearer …" \ "https://api.useapi.net/v1/muse/chats/streams?email=example%40gmail.com" ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously added account email"; const apiUrl = `https://api.useapi.net/v1/muse/chats/streams?email=${encodeURIComponent(email)}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); console.log("response", response.status, await response.json()); ``` **Python** ``` python import requests token = "API token" email = "Previously added account email" apiUrl = "https://api.useapi.net/v1/muse/chats/streams" headers = { "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers, params={"email": email}) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-muse-v1/get-muse-chats === Document URL: https://useapi.net/docs/api-muse-v1/get-muse-chats --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> chats description: "List the chats of a Muse account via GET chats in the useapi.net Muse API: title, snippet, status and dates, newest first, paged with a cursor, job chats included." parent: Muse API nav_order: 440 permalink: /docs/api-muse-v1/get-muse-chats --- ## List chats October 12, 2026 (November 16, 2026) --- List the chats of a Muse account, newest first. The list holds every chat on the account: the ones you start with [POST /chats](/docs/api-muse-v1/post-muse-chats), the ones made in the muse.ai app, and the ones the [jobs](/docs/api-muse-v1/post-muse-jobs-image) create, because every job is a Muse chat too. Any listed `chatId` works with the other chat endpoints. > **https://api.useapi.net/v1/muse/chats?email=`email`&limit=`limit`&cursor=`cursor`** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `email` is optional when the API token has one Muse account, and **required** when it has more. URL-encode it. - `limit` is optional, the number of chats per page. Range: `1` to `100`. Default: `50`. - `cursor` is optional, the `cursor` from the previous page, to read the next one. ##### Responses **200** **200 OK** ```json { "email": "example@gmail.com", "chats": [ { "chatId": "c-u12345-email:example@gmail.com-chat:272b73f4-6fcb-42c2-9ec7-75cc0c020940-bot:muse", "title": "Write a sea story", "snippet": "Write a 600-word essay about lighthouses. Text only.", "status": "interrupted", "created": "2026-10-12T23:19:01.000Z", "updated": "2026-10-12T23:19:53.000Z" }, { "chatId": "c-u12345-email:example@gmail.com-chat:3b945e81-6112-4035-a14a-f1c8ac47c9ec-bot:muse", "title": "Animate image to video", "snippet": "Here's your video.", "status": "completed", "created": "2026-10-12T23:09:50.000Z", "updated": "2026-10-12T23:11:02.000Z" } ], "cursor": "v3:0:0:-:1791846958:1791846950:3b945e81-6112-4035-a14a-f1c8ac47c9ec" } ``` `cursor` is `null` on the last page. **400** **400 Bad Request** — the token has more than one Muse account and `email` is missing, or a parameter is invalid. ```json { "error": "Pass email: this token has 3 Muse accounts", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **404** **404 Not Found** — the account named by `email` is not added. ```json { "error": "Account example@gmail.com is not configured", "code": 404 } ``` **503** **503 Service Unavailable** — Muse could not be reached. Retry shortly. ```json { "error": "Could not connect to the Muse workspace of account example@gmail.com (…), please retry shortly", "code": 503 } ``` **596** **596 Account Error** The account needs your attention, and it is paused until you add it again. You receive an email when this happens. There are three causes. Meta asks for a security check on the account. Sign in once at [muse.ai](https://muse.ai) in a browser, complete the check, then add the account again with [POST /accounts](/docs/api-muse-v1/post-muse-accounts) using the same email and password. The API keeps using its session, so no new sign-in is needed. ```json { "error": "Account example@gmail.com: Meta asks for a security check on account example@gmail.com (\"This account must complete a security checkpoint on the web\"). Sign in once at https://muse.ai in a browser, complete the check, then add the account again with POST /accounts", "code": 596 } ``` Or Muse refused to sign the account in again when its session needed renewing, most often because the password was changed. Add the account again with the current password. ```json { "error": "Account example@gmail.com: Muse refused to sign in account example@gmail.com (…). Update its password with POST /accounts, or sign in at https://muse.ai to clear the block, then re-add it", "code": 596 } ``` Or Muse disabled the account's computer and refuses to start it again. Sign in at [muse.ai](https://muse.ai) in a browser to see why, and ask Muse support to restore it with the form Muse shows there. Add the account again only after Muse has restored it. ```json { "error": "Account example@gmail.com: Muse has disabled the computer of account example@gmail.com (\"VM wake unavailable\"). Sign in at https://muse.ai in a browser to see why and contact Muse support there, then add the account again with POST /accounts", "code": 596 } ``` ##### Model One page of the account's chats, newest first, each with its `chatId`, title and status, and a `cursor` for the next page. <details markdown="block" class="model-details"> <summary>The page of chats, field by field</summary> ```typescript { // TypeScript, all fields are optional email: string chats: { chatId: string // c-u<id>-email:<email>-chat:<Muse chat id>-bot:muse title: string | null // the title Muse gave the chat snippet: string | null // the start of the latest message status: string | null // e.g. running, completed, interrupted created: string | null // ISO 8601 updated: string | null // ISO 8601 pinned?: true // pinned in the muse.ai app archived?: true // archived in the muse.ai app }[] cursor: string | null // pass it as cursor for the next page, null on the last page error?: string // errors only code?: number // errors only } ``` </details> ##### Examples **Curl** ``` bash curl -H "Authorization: Bearer …" \ "https://api.useapi.net/v1/muse/chats?email=example%40gmail.com&limit=10" ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously added account email"; const apiUrl = `https://api.useapi.net/v1/muse/chats?email=${encodeURIComponent(email)}&limit=10`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", response.status, result); ``` **Python** ``` python import requests token = "API token" email = "Previously added account email" apiUrl = "https://api.useapi.net/v1/muse/chats" headers = { "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers, params={"email": email, "limit": 10}) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-muse-v1/get-muse-files-content === Document URL: https://useapi.net/docs/api-muse-v1/get-muse-files-content --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> files/content description: "Download any file from a Muse account's workspace via GET files/content in the useapi.net Muse API: code, PDFs, CSV, text or media, streamed as is." parent: Muse API nav_order: 341 permalink: /docs/api-muse-v1/get-muse-files-content --- ## Download a workspace file October 12, 2026 (November 16, 2026) --- Download any file from the Muse workspace of an account: code, documents, data or media, for example a report or a script the agent wrote. The response body is the file itself, streamed from the workspace, with its `Content-Type`. Files and assets are two views of the same workspace. [Assets](/docs/api-muse-v1/get-muse-assets) are the images, videos and audio files, each with an `assetId` for jobs and chats. `/files` covers the whole workspace, including the code, documents and data the agent writes. A media file listed here also carries its `assetId`. Paths always start with `workspace/`, for example `workspace/your_files/report.pdf`. Find a path with [GET /files](/docs/api-muse-v1/get-muse-files) or [GET /files/search](/docs/api-muse-v1/get-muse-files-search). > **https://api.useapi.net/v1/muse/files/content?email=`email`&path=`path`** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `email` is optional when the API token has one Muse account, and **required** when it has more. URL-encode it. - `path` is **required**, the file's path in the workspace. ##### Responses **200** **200 OK** — the raw file bytes (not JSON), for example: ``` Content-Type: text/plain; charset=utf-8 Content-Length: 769 ``` **400** **400 Bad Request** — `path` is a folder, or not a path in the workspace. ```json { "error": "Path is a folder: list it with GET /files", "code": 400 } ``` **401** **401 Unauthorized** — Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **404** **404 Not Found** — the path is not in the workspace, or the account named by `email` is not added. ```json { "error": "File not found", "code": 404 } ``` **503** **503 Service Unavailable** — Muse could not be reached. Retry shortly. ```json { "error": "Muse could not do it right now (…), please retry", "code": 503 } ``` **596** **596 Account Error** The account needs your attention, and it is paused until you add it again. You receive an email when this happens. There are three causes. Meta asks for a security check on the account. Sign in once at [muse.ai](https://muse.ai) in a browser, complete the check, then add the account again with [POST /accounts](/docs/api-muse-v1/post-muse-accounts) using the same email and password. The API keeps using its session, so no new sign-in is needed. ```json { "error": "Account example@gmail.com: Meta asks for a security check on account example@gmail.com (\"This account must complete a security checkpoint on the web\"). Sign in once at https://muse.ai in a browser, complete the check, then add the account again with POST /accounts", "code": 596 } ``` Or Muse refused to sign the account in again when its session needed renewing, most often because the password was changed. Add the account again with the current password. ```json { "error": "Account example@gmail.com: Muse refused to sign in account example@gmail.com (…). Update its password with POST /accounts, or sign in at https://muse.ai to clear the block, then re-add it", "code": 596 } ``` Or Muse disabled the account's computer and refuses to start it again. Sign in at [muse.ai](https://muse.ai) in a browser to see why, and ask Muse support to restore it with the form Muse shows there. Add the account again only after Muse has restored it. ```json { "error": "Account example@gmail.com: Muse has disabled the computer of account example@gmail.com (\"VM wake unavailable\"). Sign in at https://muse.ai in a browser to see why and contact Muse support there, then add the account again with POST /accounts", "code": 596 } ``` ##### Model A successful response is the file itself (not JSON). Errors return: <details markdown="block" class="model-details"> <summary>The error answer, field by field</summary> ```typescript { // TypeScript, all fields are optional error: string code: number } ``` </details> ##### Examples **Curl** ``` bash curl -H "Authorization: Bearer …" \ "https://api.useapi.net/v1/muse/files/content?email=example%40gmail.com&path=workspace%2Fyour_files%2Fsunkissed-lyrics.txt" \ --output sunkissed-lyrics.txt ``` **JavaScript** ``` javascript const token = "API token"; const params = new URLSearchParams({ email: "example@gmail.com", path: "workspace/your_files/sunkissed-lyrics.txt" }); const response = await fetch(`https://api.useapi.net/v1/muse/files/content?${params}`, { method: "GET", headers: { "Authorization": `Bearer ${token}`, } }); const file = await response.arrayBuffer(); console.log("downloaded", response.status, file.byteLength, response.headers.get("content-type")); ``` **Python** ``` python import requests token = "API token" apiUrl = "https://api.useapi.net/v1/muse/files/content" headers = { "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers, params={"email": "example@gmail.com", "path": "workspace/your_files/sunkissed-lyrics.txt"}) with open("lyrics.txt", "wb") as f: f.write(response.content) print(response, len(response.content)) ``` === URL: https://useapi.net/docs/api-muse-v1/get-muse-files-search === Document URL: https://useapi.net/docs/api-muse-v1/get-muse-files-search --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> files/search description: "Find files in a Muse account's workspace via GET files/search in the useapi.net Muse API: by part of the name and/or by extension, under any folder, paged." parent: Muse API nav_order: 342 permalink: /docs/api-muse-v1/get-muse-files-search --- ## Search workspace files October 12, 2026 (November 16, 2026) --- Find files in the Muse workspace of an account by part of their name, by extension, or both, in a folder and its subfolders. Results come in pages: read on with `offset` while `hasMore` is `true`. Files and assets are two views of the same workspace. [Assets](/docs/api-muse-v1/get-muse-assets) are the images, videos and audio files, each with an `assetId` for jobs and chats. `/files` covers the whole workspace, including the code, documents and data the agent writes. A media file listed here also carries its `assetId`. Paths always start with `workspace/`, for example `workspace/your_files/report.pdf`. > **https://api.useapi.net/v1/muse/files/search?email=`email`&path=`path`&name=`name`&extensions=`extensions`&limit=`limit`&offset=`offset`** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `email` is optional when the API token has one Muse account, and **required** when it has more. URL-encode it. - `path` is optional, the folder to search in, including its subfolders. Default: `workspace`. - `name` is optional, a part of the file name, for example `report`. - `extensions` is optional, a comma-separated list of file extensions, for example `pdf,csv`. - `limit` is optional, the most files per page. Range: `1` to `200`. Default: `50`. - `offset` is optional, how many matches to skip, for the next page. Default: `0`. Send at least one of `name` and `extensions`. ##### Responses **200** **200 OK** ```json { "email": "example@gmail.com", "path": "workspace", "entries": [ { "name": "sunkissed-lyrics.txt", "path": "workspace/your_files/sunkissed-lyrics.txt", "type": "file", "bytes": 769, "modified": "2026-10-05T05:02:00.385Z", "assetId": null } ], "total": 1, "hasMore": false } ``` **400** **400 Bad Request** — neither `name` nor `extensions` was sent, or a parameter is invalid. ```json { "error": "Pass name and/or extensions (e.g. extensions=pdf,csv)", "code": 400 } ``` **401** **401 Unauthorized** — Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **404** **404 Not Found** — the account named by `email` is not added. ```json { "error": "Account example@gmail.com is not configured", "code": 404 } ``` **503** **503 Service Unavailable** — Muse could not be reached. Retry shortly. ```json { "error": "Muse could not do it right now (…), please retry", "code": 503 } ``` **596** **596 Account Error** The account needs your attention, and it is paused until you add it again. You receive an email when this happens. There are three causes. Meta asks for a security check on the account. Sign in once at [muse.ai](https://muse.ai) in a browser, complete the check, then add the account again with [POST /accounts](/docs/api-muse-v1/post-muse-accounts) using the same email and password. The API keeps using its session, so no new sign-in is needed. ```json { "error": "Account example@gmail.com: Meta asks for a security check on account example@gmail.com (\"This account must complete a security checkpoint on the web\"). Sign in once at https://muse.ai in a browser, complete the check, then add the account again with POST /accounts", "code": 596 } ``` Or Muse refused to sign the account in again when its session needed renewing, most often because the password was changed. Add the account again with the current password. ```json { "error": "Account example@gmail.com: Muse refused to sign in account example@gmail.com (…). Update its password with POST /accounts, or sign in at https://muse.ai to clear the block, then re-add it", "code": 596 } ``` Or Muse disabled the account's computer and refuses to start it again. Sign in at [muse.ai](https://muse.ai) in a browser to see why, and ask Muse support to restore it with the form Muse shows there. Add the account again only after Muse has restored it. ```json { "error": "Account example@gmail.com: Muse has disabled the computer of account example@gmail.com (\"VM wake unavailable\"). Sign in at https://muse.ai in a browser to see why and contact Muse support there, then add the account again with POST /accounts", "code": 596 } ``` ##### Model One page of matching files and folders, each with its `path`, size and date, plus the `total` count and `hasMore`. <details markdown="block" class="model-details"> <summary>The page of matching files, field by field</summary> ```typescript { // TypeScript, all fields are optional email: string path: string // the folder searched entries: { name: string path: string // workspace/… type: 'file' | 'directory' bytes: number | null modified: string | null // ISO 8601 assetId?: string | null // files only: the asset id of an image, video or audio file, else null }[] total: number | null // all matches hasMore: boolean // more matches after this page: pass offset error?: string // errors only code?: number // errors only } ``` </details> ##### Examples **Curl** ``` bash curl -H "Authorization: Bearer …" \ "https://api.useapi.net/v1/muse/files/search?email=example%40gmail.com&extensions=pdf,csv&limit=20" ``` **JavaScript** ``` javascript const token = "API token"; const params = new URLSearchParams({ email: "example@gmail.com", name: "lyrics" }); const response = await fetch(`https://api.useapi.net/v1/muse/files/search?${params}`, { method: "GET", headers: { "Authorization": `Bearer ${token}`, } }); console.log("response", response.status, await response.json()); ``` **Python** ``` python import requests token = "API token" apiUrl = "https://api.useapi.net/v1/muse/files/search" headers = { "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers, params={"email": "example@gmail.com", "extensions": "pdf,csv", "limit": 20}) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-muse-v1/get-muse-files === Document URL: https://useapi.net/docs/api-muse-v1/get-muse-files --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> files description: "List a folder of a Muse account's workspace via GET files in the useapi.net Muse API: files and folders with size, date, and asset ids for media." parent: Muse API nav_order: 340 permalink: /docs/api-muse-v1/get-muse-files --- ## List workspace files October 12, 2026 (November 16, 2026) --- List a folder in the Muse workspace of an account: the files and folders in it, with their size and date. Given the path of a file, it answers that file's entry. Files and assets are two views of the same workspace. [Assets](/docs/api-muse-v1/get-muse-assets) are the images, videos and audio files, each with an `assetId` for jobs and chats. `/files` covers the whole workspace, including the code, documents and data the agent writes. A media file listed here also carries its `assetId`. Paths always start with `workspace/`, for example `workspace/your_files/report.pdf`. Read a file with [GET /files/content](/docs/api-muse-v1/get-muse-files-content), find files with [GET /files/search](/docs/api-muse-v1/get-muse-files-search), write one with [POST /files](/docs/api-muse-v1/post-muse-files), and remove one with [DELETE /files](/docs/api-muse-v1/delete-muse-files). > **https://api.useapi.net/v1/muse/files?email=`email`&path=`path`** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `email` is optional when the API token has one Muse account, and **required** when it has more. URL-encode it. - `path` is optional, a folder or a file in the workspace. Default: `workspace`. ##### Responses **200** **200 OK** — a folder: ```json { "email": "example@gmail.com", "path": "workspace/your_files", "entries": [ { "name": "balalaika_etude.mp3", "path": "workspace/your_files/balalaika_etude.mp3", "type": "file", "bytes": 2321598, "modified": "2026-10-05T05:07:37.404Z", "assetId": "user:12345-email:6578616d706c6540676d61696c2e636f6d-audio:ws~your_files~balalaika_etude.mp3" }, { "name": "sunkissed-lyrics.txt", "path": "workspace/your_files/sunkissed-lyrics.txt", "type": "file", "bytes": 769, "modified": "2026-10-05T05:02:00.385Z", "assetId": null } ] } ``` The top folder, `workspace`: ```json { "email": "example@gmail.com", "path": "workspace", "entries": [ { "name": "code", "path": "workspace/code", "type": "directory", "bytes": null, "modified": "2026-10-13T01:28:06.219Z" }, { "name": "your_files", "path": "workspace/your_files", "type": "directory", "bytes": null, "modified": "2026-10-13T01:54:06.788Z" } ] } ``` A file path answers that file's entry: ```json { "email": "example@gmail.com", "name": "sunkissed-lyrics.txt", "path": "workspace/your_files/sunkissed-lyrics.txt", "type": "file", "bytes": 769, "modified": "2026-10-05T05:02:00.385Z", "assetId": null } ``` **400** **400 Bad Request** — `path` is not a path in the workspace, or the token has more than one Muse account and `email` is missing. ```json { "error": "Parameter path must be a path in the workspace, e.g. workspace/your_files/notes.txt", "code": 400 } ``` **401** **401 Unauthorized** — Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **404** **404 Not Found** — the path is not in the workspace, or the account named by `email` is not added. ```json { "error": "Path not found", "code": 404 } ``` **503** **503 Service Unavailable** — Muse could not be reached. Retry shortly. ```json { "error": "Muse could not do it right now (…), please retry", "code": 503 } ``` **596** **596 Account Error** The account needs your attention, and it is paused until you add it again. You receive an email when this happens. There are three causes. Meta asks for a security check on the account. Sign in once at [muse.ai](https://muse.ai) in a browser, complete the check, then add the account again with [POST /accounts](/docs/api-muse-v1/post-muse-accounts) using the same email and password. The API keeps using its session, so no new sign-in is needed. ```json { "error": "Account example@gmail.com: Meta asks for a security check on account example@gmail.com (\"This account must complete a security checkpoint on the web\"). Sign in once at https://muse.ai in a browser, complete the check, then add the account again with POST /accounts", "code": 596 } ``` Or Muse refused to sign the account in again when its session needed renewing, most often because the password was changed. Add the account again with the current password. ```json { "error": "Account example@gmail.com: Muse refused to sign in account example@gmail.com (…). Update its password with POST /accounts, or sign in at https://muse.ai to clear the block, then re-add it", "code": 596 } ``` Or Muse disabled the account's computer and refuses to start it again. Sign in at [muse.ai](https://muse.ai) in a browser to see why, and ask Muse support to restore it with the form Muse shows there. Add the account again only after Muse has restored it. ```json { "error": "Account example@gmail.com: Muse has disabled the computer of account example@gmail.com (\"VM wake unavailable\"). Sign in at https://muse.ai in a browser to see why and contact Muse support there, then add the account again with POST /accounts", "code": 596 } ``` ##### Model The files and folders in the listed folder, each with its `path`, size and date, or the entry of one file. <details markdown="block" class="model-details"> <summary>The folder listing, field by field</summary> ```typescript { // TypeScript, all fields are optional email: string path: string // the folder listed entries: { name: string path: string // workspace/… type: 'file' | 'directory' bytes: number | null modified: string | null // ISO 8601 assetId?: string | null // files only: the asset id of an image, video or audio file, else null }[] error?: string // errors only code?: number // errors only } ``` For a file path, the response is `email` plus that file's entry fields. </details> ##### Examples **Curl** ``` bash curl -H "Authorization: Bearer …" \ "https://api.useapi.net/v1/muse/files?email=example%40gmail.com&path=workspace%2Fyour_files" ``` **JavaScript** ``` javascript const token = "API token"; const params = new URLSearchParams({ email: "example@gmail.com", path: "workspace/your_files" }); const response = await fetch(`https://api.useapi.net/v1/muse/files?${params}`, { method: "GET", headers: { "Authorization": `Bearer ${token}`, } }); console.log("response", response.status, await response.json()); ``` **Python** ``` python import requests token = "API token" apiUrl = "https://api.useapi.net/v1/muse/files" headers = { "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers, params={"email": "example@gmail.com", "path": "workspace/your_files"}) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-muse-v1/get-muse-jobs-jobid === Document URL: https://useapi.net/docs/api-muse-v1/get-muse-jobs-jobid --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> jobs/`jobid` description: "Poll a Muse image or video job via GET jobs/jobid in the useapi.net Muse API: status, generated asset ids, the agent's reply, error codes, chat on request." parent: Muse API nav_order: 510 permalink: /docs/api-muse-v1/get-muse-jobs-jobid --- ## Retrieve a job October 12, 2026 (November 16, 2026) --- Fetch a job record by its `jobid`. [POST /jobs/image](/docs/api-muse-v1/post-muse-jobs-image) and [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video) both return one. After an async request, poll this endpoint until `status` is `completed` or `failed`. An image takes 20 to 60 seconds and a video 60 to 140, so polling every 10 seconds is enough. Our side follows each job for up to 10 minutes. If a job is still running well past its usual time, reading it also checks the job's Muse chat again, so a finished result is not lost. A job that has no result 15 minutes after it was created is failed with `504`. Instead of polling, pass `replyUrl` (and optionally `replyRef`) with the POST: when the job completes or fails, the API sends one `POST` of this same job record, as JSON, to that URL. See [Model](#model). Job records are kept for 7 days. After that the job answers `410`. > **https://api.useapi.net/v1/muse/jobs/`jobid`?history=`history`** - `jobid` is URL-encoded in the path (it contains `:` and `@`), for example `j1012014112831908109v-u12345-email%3Aexample%40gmail.com-task%3A3e8bc834-f243-4172-8f6e-9fc28e1a107c-bot%3Amuse`. ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `history` is optional, `true` to add `history`: the job's turn read live from its Muse chat (your message, the agent's replies and the files it showed), for troubleshooting. It opens a connection to Muse, so it is slower than a plain poll. Use it to see what the agent said, or, after a `504`, whether it made the file after all. Links into the Muse workspace and token-like fields are left out. The shape of `history` is Muse's own and can change. When the chat cannot be read, `historyError` says why. Default: `false`. ##### Responses **200** **200 OK** Completed (an old portrait, restored by an earlier job, brought to life): ```json { "jobid": "j1012014112831908109v-u12345-email:example@gmail.com-task:3e8bc834-f243-4172-8f6e-9fc28e1a107c-bot:muse", "type": "video", "email": "example@gmail.com", "status": "completed", "created": "2026-10-12T01:41:12.831Z", "request": { "prompt": "Animate image_1 into a video with the same portrait frame: the young woman slowly lifts her eyes to the camera, her smile widens, she gently touches the rose on her shoulder and says softly: \"It has been a hundred years... and you still remember me.\" A light breeze moves a few strands of her hair, soft window light, the camera stays still with a very slow push-in. Keep her face exactly as in image_1.", "image_1": "user:12345-email:6578616d706c6540676d61696c2e636f6d-image:media-generation-restored-portrait-0-69c7e16d-eb86-4932-b940-8d688f2b95dc.webp", "async": true }, "chatId": "3e8bc834-f243-4172-8f6e-9fc28e1a107c", "messageId": "1df531ad-e133-4725-b706-986ab4d19714", "updated": "2026-10-12T01:42:21.321Z", "completed": "2026-10-12T01:42:21.321Z", "result": { "assets": [ { "assetId": "user:12345-email:6578616d706c6540676d61696c2e636f6d-video:media-generation-restored-portrait-animation-0-4322afa2-10d0-47b0-acc6-675a129aa78e.mp4", "type": "video", "mime": "video/mp4", "bytes": 3753558, "origin": "generated" } ], "text": "Here it is." } } ``` Running: ```json { "jobid": "j1012014112831908109v-u12345-email:example@gmail.com-task:3e8bc834-f243-4172-8f6e-9fc28e1a107c-bot:muse", "type": "video", "email": "example@gmail.com", "status": "started", "created": "2026-10-12T01:41:12.831Z", "request": { "prompt": "Animate image_1 into a video with the same portrait frame: …", "image_1": "user:12345-email:6578616d706c6540676d61696c2e636f6d-image:media-generation-restored-portrait-0-69c7e16d-eb86-4932-b940-8d688f2b95dc.webp", "async": true }, "chatId": "3e8bc834-f243-4172-8f6e-9fc28e1a107c" } ``` Failed (Muse could not make the video this time and said why, so it can simply run again): ```json { "jobid": "j1012014437650921837v-u12345-email:example@gmail.com-task:3c0c6fd6-a99f-4d7f-bfd5-91e6af964242-bot:muse", "type": "video", "email": "example@gmail.com", "status": "failed", "created": "2026-10-12T01:44:37.650Z", "request": { "prompt": "Animate image_1 into a cinematic video in exactly 16:9 aspect ratio (landscape): she rides the vintage motorcycle along the shoreline, the front wheel slices through the shallow waves and sends spray flying, …", "image_1": "user:12345-email:6578616d706c6540676d61696c2e636f6d-image:media-generation-beach-shoreline-motorcycle-rid-0-99c2e513-813a-4707-9f5b-f7e68780b072.webp", "async": true }, "chatId": "3c0c6fd6-a99f-4d7f-bfd5-91e6af964242", "messageId": "f8ac44d6-9b29-455a-8fb7-df4a20c2b82a", "updated": "2026-10-12T01:45:14.352Z", "completed": "2026-10-12T01:45:14.352Z", "error": { "code": 503, "message": "Muse failed to make it this time, nothing was made: I tried to kick off your shoreline ride video and the video worker glitched out before it rendered anything, so no clip was made. I can't retry it in this same go.\n\nSay the word and I'll run it again from image_1 in 16:9.. Please retry" } } ``` Failed (the account reached Muse's [video limit](/docs/api-muse-v1/post-muse-jobs-video#video-limit) for the last 24 hours). This job named `email`, so it could only run on that account: `error.retryAt` is when video jobs try the account again. A job that could go to any account has no `retryAt`, and its message says to run it again now, on your other accounts. ```json { "jobid": "j1023131200123456789v-u12345-email:example@gmail.com-task:5b7e2c9a-0d41-4f3e-9a6b-2c8d1e7f4a10-bot:muse", "type": "video", "email": "example@gmail.com", "status": "failed", "created": "2026-10-23T13:12:00.123Z", "request": { "prompt": "A paper boat drifts down a rain-soaked city street at night, neon reflections in the water, slow tracking shot, 16:9.", "email": "example@gmail.com", "async": true }, "chatId": "5b7e2c9a-0d41-4f3e-9a6b-2c8d1e7f4a10", "messageId": "9c3f61d2-7a84-4b0e-b5e1-0f2d6a9c8e47", "updated": "2026-10-23T13:12:41.002Z", "completed": "2026-10-23T13:12:41.002Z", "error": { "code": 429, "message": "Account example@gmail.com reached Muse's video limit for the last 24 hours, nothing was made (Muse said: Your video limit for the last 24 hours has been reached. Please try again later.). Video jobs try this account again after 2026-10-23T14:12:41.001Z", "retryAt": "2026-10-23T14:12:41.001Z" } } ``` With `?history=true`, the same record plus `history`, abridged here (an image job): ```json { "jobid": "j1012011314385546947i-u12345-email:example@gmail.com-task:43d100f9-1dff-4b00-a223-453b45b8d3e3-bot:muse", "status": "completed", "…": "…", "history": [ { "event_name": "message.user", "role": "user", "display_text": "Create one image: a young woman in a red summer dress on a beach at golden hour, full body, vertical 9:16 photo\n\nMake it directly. Do not ask me questions, do not upscale, crop or edit the result afterwards. If you make no file, begin your reply with exactly one of these labels, …", "…": "…" }, { "event_name": "message.assistant", "role": "assistant", "display_text": "Done.", "…": "…" }, { "event_name": "delta.presentation", "role": "assistant", "display_text": "Red summer dress at golden hour", "…": "…" } ] } ``` The first event shows the message the API sent: your prompt after `Create one image:` (or `Create one video:`), with the line that asks Muse to make the file directly. With inputs, a list naming each input's file in the workspace comes first. **400** **400 Bad Request** The path value is not a Muse `jobid`, or a query parameter is not supported. ```json { "error": "Path parameter jobid (…) is not a valid Muse job id", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** ```json { "error": "This job does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** No such job. ```json { "error": "Job not found", "code": 404 } ``` **410** **410 Gone** The job is older than 7 days: job records are kept for 7 days. ```json { "error": "Job has expired", "code": 410 } ``` ##### Model The job record. [POST /jobs/image](/docs/api-muse-v1/post-muse-jobs-image) and [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video) return it too, and it is the body of the `replyUrl` webhook. <details markdown="block" class="model-details"> <summary>The job record and its <code>status</code> values, field by field</summary> ```typescript { // TypeScript, all fields are optional jobid: string // j<nonce><i|v>-u<id>-email:<email>-task:<chat id>-bot:muse type: 'image' | 'video' email: string // the Muse account the job runs on status: 'started' | 'completed' | 'failed' created: string // ISO 8601, when the job was accepted updated?: string // ISO 8601, the last change completed?: string // ISO 8601, when the job completed or failed request: Record<string, unknown> // your request body as sent chatId: string // the Muse chat this job created (also inside the jobid) messageId?: string // Muse's id of the job's message in that chat, once it was sent replyUrl?: string replyRef?: string error?: { // status 'failed' code: number // see the error codes on GET /jobs/{jobid} message: string // when Muse refused, its own words retryAt?: string // ISO 8601, code 429 for Muse's video limit on a job that could only run on this account: // video jobs try the account again after this time } result?: { // status 'completed' assets: { // the files the job made, the finished one first: usually one, two when the agent finishes // Muse's file with its own tools (e.g. lays your audio_1 onto the generated clip) assetId: string // download it with GET /assets/{assetId}, or pass it as image_N / video_N of the next job type: 'image' | 'video' | 'audio' mime: string // e.g. image/webp, video/mp4 bytes: number origin: 'generated' | 'made' // generated by Muse, or made by the agent with its own tools (an edit) }[] text: string | null // the agent's last message, e.g. "Here's your image." } history?: unknown[] // GET /jobs/{jobid}?history=true only: the job's chat turn as Muse sent it historyError?: string // GET /jobs/{jobid}?history=true only: why the chat could not be read } ``` | `status` | Meaning | |---|---| | `started` | Muse is working on it. Every job starts here. | | `completed` | Done. Each file in `result.assets[]` downloads with [GET /assets/`assetId`](/docs/api-muse-v1/get-muse-assets-assetId) and can be the input of the next job. | | `failed` | Done without a file. `error` says why. | </details> ### Error codes | `error.code` | Meaning | |---|---| | `403` | Muse refused to make it, for example on content grounds, and `message` has the agent's own words. This includes a hold the agent keeps in the account's memory for a kind of request. Running the same prompt again will not help: change the prompt or the inputs. `403` is also the answer on a video job when Meta has switched off video for the account in its country or region: video jobs then skip that account, and image jobs still work (see [Video limit](/docs/api-muse-v1/post-muse-jobs-video#video-limit)). `403` is also the answer when Muse asked for permission before going on: a job cannot answer that, a [chat](/docs/api-muse-v1/post-muse-chats) can. | | `404` | The account was removed with [DELETE /accounts/`email`](/docs/api-muse-v1/delete-muse-accounts-email) before the job's result could be read. | | `409` | Nothing was made: Muse said the account already made this request, or already has it queued, and would not do it again. `message` has Muse's own words. The account's Muse computer keeps what it made across chats, so the same prompt on the same account gets the same answer. Change the prompt, or run the job on another account. | | `412` | The account's weekly Muse allowance is used up. `message` says when it resets. See [GET /accounts/`email`](/docs/api-muse-v1/get-muse-accounts-email). | | `429` | Nothing was made, for one of three reasons. Muse is limiting requests on the account right now: retry in about a minute. Or Muse said another usage limit stopped the job, and `message` has its own words: retry later, or run the job on another account. Or, on a video job, Muse said the account reached its video limit for the last 24 hours, and `message` has Muse's own words. Video jobs then skip that account for an hour. Without `retryAt`, run the job again now and it goes to your other accounts. With `retryAt` the job could only run on that account (it named `email`, or its inputs live there), and the account takes video jobs again after that time. | | `500` | An unexpected error on our side. | | `502` | Muse made a file the API cannot return (an unusual file name), or did not accept the message. A made file is in the job's chat ([GET /jobs/`jobid`?history=true](/docs/api-muse-v1/get-muse-jobs-jobid)), and running the job again uses the allowance again. Report the jobid to support. | | `503` | Nothing was made. Either the job never reached Muse (Muse could not be reached, the job could not be started, or it was interrupted before it was sent), or Muse failed to make it this time and said so, for example `the video worker glitched out before it rendered anything`. Run it again: in our tests the same prompt then worked. A video limit is not a `503`: it is answered with `429`, and a refusal to repeat a request with `409`. When Muse ends its answer with a promise such as `Back in a minute`, the job keeps waiting up to 5 more minutes for the file before it fails. | | `504` | Muse did not finish in time (a job is followed for up to 10 minutes and failed 15 minutes after it started), or the connection to Muse dropped after the job was sent. The job may still have completed in the account's Muse chat: check [GET /jobs/`jobid`?history=true](/docs/api-muse-v1/get-muse-jobs-jobid) before running it again. | | `596` | The account needs attention: Meta asks for a security check, or Muse refused to sign it in again. See [Setup Muse](/docs/start-here/setup-muse#if-the-account-needs-attention). | A sync POST whose job fails answers with the HTTP status in `error.code` and the failed job record as the body. The `replyUrl` webhook is one `POST` with `Content-Type: application/json` and this record as the body, sent once when the job completes or fails (a 10-second timeout, no retries, redirects are not followed). Use `replyRef` to match the callback to your own records. ##### Examples **Curl** ``` bash JOBID="j1012014112831908109v-u12345-email:example@gmail.com-task:3e8bc834-f243-4172-8f6e-9fc28e1a107c-bot:muse" curl -H "Authorization: Bearer …" \ "https://api.useapi.net/v1/muse/jobs/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$JOBID")" ``` **JavaScript** ``` javascript const token = "API token"; const jobid = "j1012014112831908109v-u12345-email:example@gmail.com-task:3e8bc834-f243-4172-8f6e-9fc28e1a107c-bot:muse"; const apiUrl = `https://api.useapi.net/v1/muse/jobs/${encodeURIComponent(jobid)}`; let job; do { await new Promise(resolve => setTimeout(resolve, 10000)); const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); job = await response.json(); console.log(job.status); } while (job.status === "started"); console.log("job", job); ``` **Python** ``` python import requests, time, urllib.parse token = "API token" jobid = "j1012014112831908109v-u12345-email:example@gmail.com-task:3e8bc834-f243-4172-8f6e-9fc28e1a107c-bot:muse" apiUrl = "https://api.useapi.net/v1/muse/jobs/" + urllib.parse.quote(jobid, safe="") headers = { "Authorization" : f"Bearer {token}" } while True: time.sleep(10) job = requests.get(apiUrl, headers=headers).json() print(job.get("status")) if job.get("status") != "started": break print(job) ``` === URL: https://useapi.net/docs/api-muse-v1/get-muse-jobs === Document URL: https://useapi.net/docs/api-muse-v1/get-muse-jobs --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> jobs description: "See what your Muse accounts are making via GET jobs in the useapi.net Muse API: the image and video jobs running now and each account's count against maxJobs." parent: Muse API nav_order: 500 permalink: /docs/api-muse-v1/get-muse-jobs --- ## List running jobs October 12, 2026 (November 16, 2026) --- List the jobs running right now and, for every added account, how many of its `maxJobs` slots they take. A job is listed from the moment [POST /jobs/image](/docs/api-muse-v1/post-muse-jobs-image) or [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video) accepts it until it completes or fails. Each listed job takes one of its account's slots. When all slots of an account are taken, a new job on it is refused with `429`, and a job without `email` or inputs goes to another account that has a free slot. [Chats](/docs/api-muse-v1/post-muse-chats) take no slot. Open chat streams are listed by [GET /chats/streams](/docs/api-muse-v1/get-muse-chats-streams). Uploads take no slot. Fetch a single job with [GET /jobs/`jobid`](/docs/api-muse-v1/get-muse-jobs-jobid). This endpoint reads our own records only and never calls Muse, so it is cheap to poll. > **https://api.useapi.net/v1/muse/jobs** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** ```json { "running": [ { "jobid": "j1012012359487240036i-u12345-email:example@gmail.com-task:bcaa91f0-24e0-4b7e-8d2c-6624bf9562e0-bot:muse", "email": "example@gmail.com", "created": "2026-10-12T01:23:59.487Z", "type": "image" } ], "accounts": { "example@gmail.com": { "running": 1, "maxJobs": 10 } } } ``` **400** **400 Bad Request** No Muse account is added yet. ```json { "error": "Please configure at least one account at https://useapi.net/docs/api-muse-v1/post-muse-accounts", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` ##### Model The jobs running now, each with its `jobid`, account and type, and for each account how many of its `maxJobs` slots are taken. <details markdown="block" class="model-details"> <summary>Running jobs and slots per account, field by field</summary> ```typescript { // TypeScript, all fields are optional running: { jobid: string email: string // the account the job runs on created: string // ISO 8601, when the job was accepted type: 'image' | 'video' }[] accounts: { [email: string]: { running: number // jobs running on this account now maxJobs: number // its limit, set with POST /accounts } } } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/muse/jobs" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = "https://api.useapi.net/v1/muse/jobs"; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" apiUrl = "https://api.useapi.net/v1/muse/jobs" headers = { "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-muse-v1 === Document URL: https://useapi.net/docs/api-muse-v1 --- layout: default title: Muse API nav_logo: /assets/images/muse.svg nav_title: Muse API seo_title: "Muse API for Meta Muse AI: Video, Images and Agent Chat" description: "Muse API by useapi.net, third-party: 10-second Meta Muse videos with sound, images and Muse agent chat over REST or MCP, on your Muse plan, free plan included." nav_order: 2010 has_children: true permalink: /docs/api-muse-v1 repo: https://github.com/useapi/muse-api --- # <img style="height:1em;vertical-align: middle;" src="/assets/images/muse.svg" alt=""> Muse API October 12, 2026 (October 30, 2026) This is a [third-party](/docs/legal#affiliation--third-party-services) API for [Muse](https://muse.ai) by [Meta](https://about.meta.com). It uses your [Muse subscription](https://www.meta.com/help/subscriptions/1021145227643680/): Free, Power $20 or Maximum $100 a month (as of October 2026). Through a REST API and a hosted MCP server, it makes images and 10-second videos with sound and spoken dialogue, and lets you chat with the Muse agent and watch or take over its web browser. Meta sells no Muse video API: its own [Model API](https://dev.meta.ai/docs/models) has no video model and no API for the Muse agent (as of October 2026). ## What it makes | Output | What you get | Notes | |---|---|---| | [Image](/docs/api-muse-v1/post-muse-jobs-image) | WebP, about 2 to 2.5 megapixels | From text or up to 9 of your images: combine photos, change an outfit, restore and colorize an old photo | | [Video](/docs/api-muse-v1/post-muse-jobs-video) | MP4, about 10 seconds at 720p, with sound | From text, a photo or another video, with up to 9 images, 3 videos and 3 audio files. Quoted lines are spoken, so a photo talks, and a person in a clip can be swapped for someone else | | [Chat](/docs/api-muse-v1/post-muse-chats) | Text, files and cards, streamed live | Research, code, connected apps, documents, web apps and podcasts, with your images, videos, audio and workspace files attached | | [Library](/docs/api-muse-v1/get-muse-assets) | Every file on the account | [Uploads](/docs/api-muse-v1/post-muse-assets) up to 50 MB, made media, documents (also as PDF), podcasts as MP3, and web apps you can [publish on a public link](/docs/api-muse-v1/post-muse-assets-assetId-share) | | [Workspace files](/docs/api-muse-v1/get-muse-files) | Any file on the agent's computer | [Search](/docs/api-muse-v1/get-muse-files-search), [download](/docs/api-muse-v1/get-muse-files-content), [write](/docs/api-muse-v1/post-muse-files) and [delete](/docs/api-muse-v1/delete-muse-files) the code, documents and data the agent writes | Muse picks its own model, so there is no model, resolution or duration setting: you ask for the aspect ratio and the spoken lines in the prompt, and Muse follows any common ratio. Every file Muse makes is an [asset id](/docs/api-muse-v1/get-muse-assets-assetId) that the next job takes as an input, so edits chain with no downloads or re-uploads. In our tests an image took 20 to 60 seconds and a video 60 to 140. ## Agent Chat with Muse, Meta's personal AI agent, through [POST /chats](/docs/api-muse-v1/post-muse-chats): its answers stream live and pick up again after a dropped connection, and you can send the next message mid-answer, [stop](/docs/api-muse-v1/post-muse-chats-chatId-cancel) it, and [list, read or delete](/docs/api-muse-v1/get-muse-chats) chats. When it opens a website, [watch its browser live](/docs/api-muse-v1/live-browser-guide) and take control with mouse and keyboard. Answer its [permission requests](/docs/api-muse-v1/post-muse-chats-chatId-approvals-approvalId) and [quick-reply cards](/docs/api-muse-v1/post-muse-chats-chatId-widgets-widgetId), set [what it may do without asking](/docs/api-muse-v1/get-muse-accounts-email-permissions), or [reset](/docs/api-muse-v1/post-muse-accounts-email-reset) a stuck account to a fresh agent computer. The [live demo](/docs/api-muse-v1/demo) is a complete chat client built on it, and we keep adding more of what Muse can do. ## MCP server The hosted [Muse MCP server](/docs/api-muse-v1/mcp) gives Claude Code, Cursor, VS Code and other AI assistants 37 tools for Muse images, videos, chat, the agent's browser and the Library, with your useapi.net API token and nothing to install. The [muse-api](https://github.com/useapi/muse-api) repo also adds it in one step as a [Claude Code plugin](https://github.com/useapi/muse-api#use-with-claude-code) or a [Gemini CLI extension](https://github.com/useapi/muse-api#use-with-gemini-cli). ## Pricing How the useapi.net Muse API compares with Meta's own API (October 2026). Muse has no credits and no price per image or video: each job uses part of your Muse account's weekly allowance, and a paid Muse plan gets a bigger one. | | useapi.net Muse API | Meta's [Model API](https://dev.meta.ai/docs/pricing-rate-limits) | |---|:-:|:-:| | Cost | Your Muse subscription, the free plan included | $0.01 per image | | Images | Yes | Yes | | 10-second videos with sound and speech | Yes | No | | Chat with the Muse agent at muse.ai | Yes | No | | The agent's live web browser, Library and files | Yes | No | - A free Muse account makes images, videos and chats, and each account you connect has its own weekly allowance. - Meta publishes each plan's weekly allowance in Muse tokens: 500 million on Power and 3 billion on Maximum, while the free plan's limit isn't published ([About Muse subscriptions](https://www.meta.com/help/subscriptions/1021145227643680/)). Meta publishes no token cost per image or video. In our tests on the free plan, a video used 2 to 3 percent of the week and an image 0 to 1 percent. - [GET /accounts/`email`](/docs/api-muse-v1/get-muse-accounts-email) shows each account's plan, the share of the week used and when it resets. ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. ## Run several Muse accounts Each useapi.net subscription adds 3 Muse accounts. Image and video jobs don't need `email`: a job goes to the account that holds its inputs, or to a healthy account with allowance left and a free slot within its `maxJobs` (1 to 50, default 10). An account whose weekly allowance is used up sits out until it resets, and a job sent to it with `email` answers `412`. An account that reached Muse's [video limit](/docs/api-muse-v1/post-muse-jobs-video#video-limit) for the last 24 hours sits out video jobs for an hour. When every account is busy you get `429`, so wait and send it again. [GET /jobs](/docs/api-muse-v1/get-muse-jobs) shows what each account is running, and chats take no job slot. Every job can post its finished record to your webhook with `replyUrl`, or you poll [GET /jobs/`jobid`](/docs/api-muse-v1/get-muse-jobs-jobid), so a video needs no open connection. [How useapi.net works](/docs/how-it-works) has tips for keeping your accounts healthy. ## Questions ### Is there a Meta Muse API? Through useapi.net, yes, for video, images and the Muse agent: the useapi.net Muse API makes 10-second [videos](/docs/api-muse-v1/post-muse-jobs-video) with sound and spoken dialogue, [images](/docs/api-muse-v1/post-muse-jobs-image) and live [chat](/docs/api-muse-v1/post-muse-chats) with the agent, on your Muse subscription. Meta's official [Model API](https://dev.meta.ai/docs/pricing-rate-limits) sells the Muse Image model at $0.01 per image, but as of October 2026 it has no video generation and no API for the Muse agent at muse.ai, where the videos are made. ### How much does the Muse API cost? Through useapi.net, an image or a video has no price of its own: it uses the weekly allowance of your Muse subscription, and the free plan works. A paid Muse plan raises the weekly allowance, as the [comparison](#pricing) shows. ### Is there a Muse API key? Through useapi.net, one [API token](/docs/start-here/setup-useapi) is all the key you need, for the REST API and the [MCP server](/docs/api-muse-v1/mcp) alike. Add your [muse.ai](https://muse.ai) email and password once with [Setup Muse](/docs/start-here/setup-muse), and we keep the account signed in, with no cookies to copy. Create the account in the US, Canada, Japan or Singapore, where Muse is available (as of October 2026), and finish its onboarding at muse.ai. After that you can call the API from anywhere. [Setup Muse](/docs/start-here/setup-muse) [LLM-friendly API spec](https://useapi.net/assets/aibot/api-muse-v1.txt) Feed this to your LLM to build integrations [Claude Code skill](/llm-tools) A drop-in useapi.net skill for Claude Code, and a rule for Cursor [Postman collection](https://www.postman.com/useapinet/useapi-net/collection/29112081-8619be70-7909-4fca-a03a-3b89e455c044) (October 14, 2026) [MCP Server](/docs/api-muse-v1/mcp) Muse images, videos, chat and the agent's browser from Claude Code, Cursor, VS Code and other MCP clients [Chat Streaming Guide](/docs/api-muse-v1/chat-streaming-guide) Chat with the Muse agent, its answers streamed live over SSE [Live Browser Guide](/docs/api-muse-v1/live-browser-guide) Watch the agent's web browser live and take control of it [Live Demo](/docs/api-muse-v1/demo) Try it in your browser. [Source code on GitHub](https://github.com/useapi/muse-api/tree/main/demo) [Agent skill: muse-video](https://github.com/useapi/muse-api/tree/main/skills/muse-video) Claude Code and Codex make Muse images and videos for you: `npx skills add useapi/muse-api --skill muse-video` [GitHub examples](https://github.com/useapi/muse-api) Node.js and Python: combine photos, restore old photos, make a photo talk, swap a person in a video and make a narrated 30-second Short, plus the live chat demo, n8n workflows and an agent skill [n8n template: Old Photo to Talking Video]({% include n8n-url.html t="muse-photo" %}) Restore an old photo, then make the person in it speak your line, with pick-or-redo pages and an optional Google Sheet batch mode, ready to import [n8n template: Narrated Faceless Shorts]({% include n8n-url.html t="muse-shorts" %}) Type a topic: Muse writes a short script and makes one narrated 9:16 scene per part, joined into one Short and saved to Google Drive Articles: * [Is There a Meta Muse Video API? Official API, Free Tools and a Hosted API (2026)](/docs/articles/meta-muse-video-api) * [How to Generate AI Videos and Images with the Meta Muse API](/docs/articles/muse-images-videos) {% include lang-switch.html mode="hub" key="muse" %} Videos on YouTube: * [Meta Muse API demo: images, talking photos, video with sound, chat and MCP](https://www.youtube.com/watch?v=OMUGbfRIO5E) * [A narrated 30-second Short made only with Meta Muse API calls](https://www.youtube.com/shorts/1e8f7dHTkzs) * [3 photos in, 1 talking video out](https://www.youtube.com/shorts/v_7mREyFSWk) * [The Great Pyramid was once bright white: a Short made by the Narrated Faceless Shorts n8n template](https://www.youtube.com/shorts/D-Nk0x9aJMo) * [Why honey never spoils: a Short the same template voiced with Muse text to speech](https://www.youtube.com/shorts/bYLsJIqerSM) Developer Community: * <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> * <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> === URL: https://useapi.net/docs/api-muse-v1/live-browser-guide === Document URL: https://useapi.net/docs/api-muse-v1/live-browser-guide --- layout: default title: Live Browser Guide nav_icon: browser description: "Watch the Muse agent's own web browser live and take control of it through the useapi.net Muse API: the browser event, a single-use viewer link, give back, stop." parent: Muse API nav_order: 12 permalink: /docs/api-muse-v1/live-browser-guide --- ## Live Browser Guide October 14, 2026 --- The Muse agent has a web browser on its own computer. In a chat it can open a site, read it, click through it and fill in forms. Through the useapi.net Muse API you can watch that browser live, take control of it with your mouse and keyboard, for example to sign in to a site for the agent, and then give it back. This guide walks through the flow end to end. The [Live Demo](/docs/api-muse-v1/demo) shows it working: a browser card in the chat with a Watch live button. ## How it works 1. Ask the agent for something that needs a browser, for example `Open https://example.com in your browser and keep it open`, with [POST /chats](/docs/api-muse-v1/post-muse-chats) or [POST /chats/`chatId`/messages](/docs/api-muse-v1/post-muse-chats-chatId-messages). 2. The chat's [stream](/docs/api-muse-v1/get-muse-chats-chatId-stream) sends a `browser` event with the browser's `taskId`, and another one each time the browser changes: its status, the open page, who has control. [GET /chats/`chatId`](/docs/api-muse-v1/get-muse-chats-chatId) lists the chat's browsers in `browsers`. 3. When `previewAvailable` is `true`, create a viewer link with [POST /chats/`chatId`/browser/`taskId`/viewer](/docs/api-muse-v1/post-muse-chats-chatId-browser-taskId-viewer). Use `mode` `control` to allow taking control. 4. Open the link in a web browser, or give it to your user. The page shows the agent's browser live. With a `control` link, Take control lets you click and type in it. 5. Give control back with Release control on the page, by closing the viewer, or with [POST /chats/`chatId`/browser/`taskId`/release](/docs/api-muse-v1/post-muse-chats-chatId-browser-taskId-release). The agent carries on. 6. When the browser is no longer needed, close it with [POST /chats/`chatId`/browser/`taskId`/stop](/docs/api-muse-v1/post-muse-chats-chatId-browser-taskId-stop). ## The browser event A `browser` event looks like this: ```json { "event": "browser", "taskId": "423bc12e-db16-4921-8670-08b5f3f5a5d6", "status": "Completed", "displayState": "completed", "stepTitle": "Open example.com in browser", "steps": 1, "site": "example.com", "url": "https://example.com/", "tabTitle": "Example Domain", "controlOwner": "agent", "previewAvailable": true, "parkedExpiresAt": "2026-10-15T01:06:42.438Z", "ended": false, "updated": "2026-10-14T23:06:42.438Z" } ``` A browser starts as `Queued`, then `Running`, and is `Completed` when the agent's step is done. After the agent's answer the browser stays open until `parkedExpiresAt`, and can be watched until then. `ended: true` means it is closed for good. Keep the latest event per `taskId`: each one holds the browser's whole state. A stream that resumes with `Last-Event-ID` sends the latest state of each browser again. ```typescript type Browser = { // TypeScript: the agent's browser in a chat taskId: string // the browser's id in this chat, for /chats/{chatId}/browser/{taskId} status: string | null // e.g. Queued, Running, Completed, User controlled displayState: string | null // e.g. starting, working, completed, paused stepTitle: string | null // what the agent is doing, e.g. "Opening example page" steps: number | null // how many steps the agent took site: string | null // e.g. example.com url: string | null // the open page tabTitle: string | null // the open page's title controlOwner: string | null // agent or user previewAvailable: boolean // true: the browser is open and can be watched with a viewer link parkedExpiresAt: string | null // ISO 8601: the browser stays open until then after the agent's answer ended: boolean // true: the browser is closed for good updated: string | null // ISO 8601 } ``` In [GET /chats/`chatId`](/docs/api-muse-v1/get-muse-chats-chatId), each item of `browsers` also has `afterMessageId`, the message the browser came after, so you can show it at the right place in the conversation. ## Watching and taking control [POST /chats/`chatId`/browser/`taskId`/viewer](/docs/api-muse-v1/post-muse-chats-chatId-browser-taskId-viewer) answers with a `url` such as `https://api.useapi.net/v1/muse/viewer#t=…`. Good to know: - The link works once, and must be opened within `ttl` seconds, 60 by default. Anyone who has the link can open it, so share it only with the person who should see the browser. - The account has one browser display, so one viewer at a time per account. Two browsers can run at once, and only one of them can be controlled at a time. - A viewer session lasts up to 30 minutes. Then create a new link. - With a `control` link, Take control hands you the mouse and keyboard. Control stays with you while the viewer is open, and goes back to the agent when you release it or close the viewer. - The page reconnects by itself when the connection drops, and the browser's display follows the size of the page. - Picture quality can be changed on the page: Low, Balanced, High or Max. - Copying and pasting inside the browser works. Copy and paste between your computer and the browser is not supported. - To take a link back, [revoke the viewers](/docs/api-muse-v1/delete-muse-chats-chatId-browser-taskId-viewer). Open sessions end within about 15 seconds. - If Muse can no longer show a browser, the viewer says so and the browser is stopped. Ask the agent to open the page again. To show the hosted page in an `<iframe>` in your app, or to build your own client over the viewer's WebSocket (RFB 3.8 plus a JSON control channel, with resume after a drop), see [Advanced: your own viewer client](/docs/api-muse-v1/post-muse-chats-chatId-browser-taskId-viewer#advanced-your-own-viewer-client). ## Two browsers per account A Muse account runs at most 2 browsers at a time. A third one waits with status `Queued` until one of them closes. Stop a browser when you are done with it, and always before you delete its chat: a browser of a deleted chat can no longer be reached. If the account's browsers stay `Queued` and stopping does not help, [reset the account](/docs/api-muse-v1/post-muse-accounts-email-reset), which deletes everything on it. ## Example This JavaScript reads a chat's stream and prints a viewer link as soon as the agent's browser can be watched. Read the stream as shown in the [Chat Streaming Guide](/docs/api-muse-v1/chat-streaming-guide). ```javascript const token = "API token"; const api = "https://api.useapi.net/v1/muse"; const headers = { "Authorization": `Bearer ${token}`, "Content-Type": "application/json" }; const started = await fetch(`${api}/chats`, { method: "POST", headers, body: JSON.stringify({ message: "Open https://example.com in your browser and keep it open." }), }).then(r => r.json()); const chat = encodeURIComponent(started.chatId); const viewers = new Set(); const response = await fetch(`${api}/chats/${chat}/stream`, { headers }); const reader = response.body.pipeThrough(new TextDecoderStream()).getReader(); let buffer = ""; for (;;) { const { value, done } = await reader.read(); if (done) break; buffer += value; const parts = buffer.split("\n\n"); buffer = parts.pop(); for (const part of parts) { const line = part.split("\n").find(l => l.startsWith("data: ")); if (!line) continue; const e = JSON.parse(line.slice(6)); if (e.event === "browser" && e.previewAvailable && !e.ended && !viewers.has(e.taskId)) { viewers.add(e.taskId); const viewer = await fetch(`${api}/chats/${chat}/browser/${e.taskId}/viewer`, { method: "POST", headers, body: JSON.stringify({ mode: "control" }), }).then(r => r.json()); console.log("Open before", viewer.expiresAt, viewer.url); } if (e.event === "turn.done") console.log("answer done:", e.status); } } ``` The same steps with curl: ```bash CHAT="c-u12345-email%3Aexample%40gmail.com-chat%3A8e0bf21e-a3b5-4a1e-a05a-65d160469bfb-bot%3Amuse" TASK="423bc12e-db16-4921-8670-08b5f3f5a5d6" curl -H "Authorization: Bearer …" "https://api.useapi.net/v1/muse/chats/$CHAT/browser/$TASK" curl -X POST -H "Authorization: Bearer …" -H "Content-Type: application/json" \ -d '{"mode": "control"}' "https://api.useapi.net/v1/muse/chats/$CHAT/browser/$TASK/viewer" curl -X POST -H "Authorization: Bearer …" "https://api.useapi.net/v1/muse/chats/$CHAT/browser/$TASK/release" curl -X POST -H "Authorization: Bearer …" "https://api.useapi.net/v1/muse/chats/$CHAT/browser/$TASK/stop" ``` ## Endpoints | Endpoint | What it does | |---|---| | [GET /chats/`chatId`/browser/`taskId`](/docs/api-muse-v1/get-muse-chats-chatId-browser-taskId) | The browser's state now, who has control, and whether a viewer shows it. | | [POST /chats/`chatId`/browser/`taskId`/viewer](/docs/api-muse-v1/post-muse-chats-chatId-browser-taskId-viewer) | A single-use live view link, to watch or take control. | | [DELETE /chats/`chatId`/browser/`taskId`/viewer](/docs/api-muse-v1/delete-muse-chats-chatId-browser-taskId-viewer) | Ends every live view of the browser. | | [POST /chats/`chatId`/browser/`taskId`/release](/docs/api-muse-v1/post-muse-chats-chatId-browser-taskId-release) | Gives control back to the agent. | | [POST /chats/`chatId`/browser/`taskId`/stop](/docs/api-muse-v1/post-muse-chats-chatId-browser-taskId-stop) | Closes the browser for good. | The [MCP server](/docs/api-muse-v1/mcp) has the same actions as tools, so an AI assistant can hand you a live view link. === URL: https://useapi.net/docs/api-muse-v1/mcp === Document URL: https://useapi.net/docs/api-muse-v1/mcp --- layout: default title: MCP Server nav_icon: mcp seo_title: "Muse MCP Server: Meta Muse Video, Images and Chat, Hosted" description: "Connect the Claude app, ChatGPT, Claude Code or any MCP client to the hosted useapi.net Muse MCP server: 37 tools for Muse images, videos, chat and the agent's browser." parent: Muse API nav_order: 15 permalink: /docs/api-muse-v1/mcp --- ## Muse MCP Server October 13, 2026 (November 1, 2026) --- The useapi.net Muse MCP server lets an AI assistant such as the Claude app, ChatGPT, Claude Code, Cursor or VS Code Copilot use [Muse](https://muse.ai), Meta's AI agent, on your own Muse account. It is a hosted [Model Context Protocol](https://modelcontextprotocol.io) server with 37 tools: generate images and videos, chat with the Muse agent, answer its permission requests, open a live view of its web browser, manage the account's Library and files, and reset the account. Each tool calls the [Muse API](/docs/api-muse-v1), so the same rules, limits and allowance apply. Nothing needs to be installed or hosted. **Is there a Muse MCP server?** Yes. useapi.net, a third-party service not affiliated with Meta, hosts one at `https://api.useapi.net/v1/muse/mcp` with 37 tools for Muse images, videos, chat, the agent's browser and the Library, on your own Muse account, nothing to install. Prefer REST? Tutorial: [How to Generate AI Videos and Images with the Meta Muse API](/docs/articles/muse-images-videos) · Code: [github.com/useapi/muse-api](https://github.com/useapi/muse-api) See all useapi.net MCP servers on [Model Matrix & MCP](/model-matrix#mcp-servers). ## Endpoint and authorization ``` https://api.useapi.net/v1/muse/mcp ``` - Transport: Streamable HTTP. - Listed in the [official MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers/net.useapi%2Fmuse/versions/latest) as `net.useapi/muse`, so MCP clients and directories that read the registry can find it by that name. - Authorization: your useapi.net API token in the `Authorization: Bearer …` header, see [Setup useapi.net](/docs/start-here/setup-useapi). The Claude app and ChatGPT sign in with OAuth instead, see [Use it in the Claude app or ChatGPT](#use-it-in-the-claude-app-or-chatgpt). - You need at least one Muse account added with [Setup Muse](/docs/start-here/setup-muse). Adding and removing accounts is not available over MCP: use [POST /accounts](/docs/api-muse-v1/post-muse-accounts) or the Setup Muse page. ## Setup Replace `YOUR_API_TOKEN` with your useapi.net API token. ### Claude Code ```bash claude mcp add --transport http useapi-muse https://api.useapi.net/v1/muse/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` ### Cursor In `~/.cursor/mcp.json`: ```json { "mcpServers": { "useapi-muse": { "url": "https://api.useapi.net/v1/muse/mcp", "headers": { "Authorization": "Bearer YOUR_API_TOKEN" } } } } ``` ### VS Code In `.vscode/mcp.json`: ```json { "servers": { "useapi-muse": { "type": "http", "url": "https://api.useapi.net/v1/muse/mcp", "headers": { "Authorization": "Bearer YOUR_API_TOKEN" } } } } ``` ### Windsurf and other clients Any client that supports remote MCP servers over HTTP with custom headers works. The usual JSON shape: ```json { "mcpServers": { "useapi-muse": { "serverUrl": "https://api.useapi.net/v1/muse/mcp", "headers": { "Authorization": "Bearer YOUR_API_TOKEN" } } } } ``` Some clients name the address field `url` instead of `serverUrl`. ### Test it with curl ```bash curl -s https://api.useapi.net/v1/muse/mcp \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}' curl -s https://api.useapi.net/v1/muse/mcp \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' ``` The first call answers with the server's name `useapi-muse` and its instructions for the assistant, the second with the 37 tools. ## Use it in the Claude app or ChatGPT The Claude app ([claude.ai](https://claude.ai) and Claude Desktop) and [ChatGPT](https://chatgpt.com) can add this server as a custom connector. They sign in with OAuth: you give the app the URL, it opens a useapi.net page, and you paste your useapi.net API token there once. Both work on their Free plans. The API-token setups above for Claude Code, Cursor, VS Code and other clients keep working as before. ``` ``` ### Claude app 1. Open Settings → Connectors and click Add custom connector. 2. Enter a name, for example `useapi `, and the URL above, then click Add. 3. Click Connect. Claude opens the useapi.net sign-in page. 4. Paste your useapi.net API token and click Allow. Claude asks before each tool call unless you choose Always allow. The Free plan allows one custom connector. ### ChatGPT 1. Open Plugins, click Add and choose Add custom MCP server. 2. Enter a name and the URL above, and set Authentication to OAuth. 3. Tick ChatGPT's "I understand and want to continue" box, then click Create as a plugin. 4. Click Connect. ChatGPT opens the useapi.net sign-in page. 5. Paste your useapi.net API token and click Allow. ChatGPT asks you to confirm each tool call that creates or changes something. The Free plan works without developer mode (as of October 25, 2026). ### How the sign-in works - Your API token is in your welcome email, see [Setup useapi.net](/docs/start-here/setup-useapi). The useapi.net page links there too. - Each connection is for one MCP server. Connect each server you want to use on its own. - The app gets an access token that lasts 1 hour and renews it on its own. A connection you don't use for 90 days lapses, and you connect again. - [Resetting your API token](/docs/account-management/post-account-token-reset) disconnects every app connected with it. - - Results come back as public links, so they open right in the app. ## Tools Most tools take an optional `email`, the Muse account to use. It can be left out when the API token has one Muse account. ### Accounts and permissions | Tool | What it does | Main parameters | |---|---|---| | `muse_list_accounts` | Lists your Muse accounts with health, `maxJobs`, weekly usage and top-up tokens, as last read. | | | `muse_get_account` | Reads one account with its live weekly usage and top-up tokens. | `email` | | `muse_update_account` | Sets `maxJobs`, the image and video jobs an account runs at once. It doesn't sign in. | `email`, `maxJobs` | | `muse_reset_account` | Resets the account to a fresh agent computer, deleting everything on it. In two steps: without `confirm` it only returns the warning to show you, and it resets only when called again with `confirm` set to the account email you typed. | `email`, `confirm` | | `muse_list_approvals` | Lists the agent's permission requests across all chats, pending and decided. | `email`, `status`, `limit` | | `muse_get_permissions` | Reads whether the agent asks before acting on websites and connected apps, and the standing rules. | `email` | | `muse_set_permission_defaults` | Sets `web` and `connectors` to `auto_allow` or `always_ask`. | `email`, `web`, `connectors` | | `muse_set_permission_rule` | Changes one rule to `allow`, `ask` or `deny`. | `permissionId`, `mode` | | `muse_delete_permission_rule` | Removes one rule. | `permissionId` | ### Images and videos | Tool | What it does | Main parameters | |---|---|---| | `muse_generate_image` | Makes one image from a prompt, optionally from up to 9 input images. | `prompt`, `image_1`..`image_9`, `email` | | `muse_generate_video` | Makes one video of about 10 seconds with sound, from a prompt and optional input images, videos and audio. | `prompt`, `image_1`..`image_9`, `video_1`..`video_3`, `audio_1`..`audio_3` | | `muse_get_job` | Reads a job, and with `wait: true` waits for it to finish. | `jobid`, `wait`, `history` | | `muse_list_jobs` | Lists the jobs running now. | | The job tools also take `replyRef`, your own reference echoed back in the job record. ### Chat | Tool | What it does | Main parameters | |---|---|---| | `muse_chat` | Sends a message to the Muse agent and returns its answer: text, files, widgets and permission requests. Without `chatId` it starts a new chat. | `message`, `chatId`, `files`, `email` | | `muse_get_chat` | Reads a chat. With `wait: true` it follows the running answer and returns the rest. | `chatId`, `wait`, `after`, `limit`, `before` | | `muse_list_chats` | Lists the account's chats, newest first. | `email`, `limit`, `cursor` | | `muse_delete_chat` | Deletes a chat. Its files stay. | `chatId` | | `muse_cancel_chat` | Stops the answer Muse is working on. | `chatId` | | `muse_list_streams` | Lists the chat streams open on an account against its limit. | `email` | | `muse_answer_approval` | Answers a permission request with `allow_once`, `allow_always` or `deny`, then follows the chat and returns the answer together with the agent's continuation. | `chatId`, `approvalId`, `decision`, `wait` | | `muse_answer_widget` | Answers a quick-reply widget with an option index or your own text, then follows the reply. | `chatId`, `widgetId`, `option` or `text`, `wait` | ### The agent's browser | Tool | What it does | Main parameters | |---|---|---| | `muse_get_browser` | Reads a browser the agent opened in a chat: status, page, who has control, and whether it can be watched. | `chatId`, `taskId` | | `muse_open_browser_viewer` | Returns a single-use link to a live view of the browser, to watch it or take control. | `chatId`, `taskId`, `mode`, `ttl`, `quality`, `compression` | | `muse_revoke_browser_viewers` | Ends every live view of the browser. | `chatId`, `taskId` | | `muse_release_browser` | Gives control of the browser back to the agent. | `chatId`, `taskId` | | `muse_stop_browser` | Closes the browser. | `chatId`, `taskId` | See the [Live Browser Guide](/docs/api-muse-v1/live-browser-guide). ### Library | Tool | What it does | Main parameters | |---|---|---| | `muse_list_assets` | Lists the account's whole Library, newest first: images, videos and audio, documents, web apps (with `shareUrl` when published) and podcasts. Says when the list may be incomplete. | `email`, `type`, `origin`, `limit`, `cursor` | | `muse_upload_asset` | Uploads an image, video or audio file from a public https URL, up to 50 MB. | `url`, `email` | | `muse_get_asset` | Returns an image of up to about 1 MB as an image, a text document or web app of up to 256 KB as text, or else the file's type, size and download URL. `part=cover` gives a podcast's cover, `format=pdf` a document as PDF. | `assetId`, `part`, `format` | | `muse_delete_asset` | Deletes a Library item: a media file, a document, a web app or a podcast. | `assetId` | | `muse_share_web_app` | Publishes a web app on a public link. Muse reviews it first and can refuse, listing the issues it found. | `assetId` | | `muse_unshare_web_app` | Stops sharing a web app. The app stays in the Library. | `assetId` | ### Workspace files | Tool | What it does | Main parameters | |---|---|---| | `muse_list_files` | Lists a folder of the account's workspace, or one file. | `email`, `path` | | `muse_search_files` | Finds files by part of the name and/or extension. | `name`, `extensions`, `path`, `limit`, `offset` | | `muse_read_file` | Returns a text file of up to about 200 KB as text, or an image of up to about 1 MB as an image. | `path` | | `muse_write_file` | Writes a file into the workspace, as text or base64, for the agent to use in a chat. | `path`, `content` or `contentBase64`, `contentType` | | `muse_delete_file` | Deletes a file. | `path` | The full input schema of every tool comes from `tools/list`. ## Long-running work MCP clients usually give up on a tool call after about a minute, so a tool waits up to about 50 seconds: - An image or a short answer usually finishes in that time, and the tool returns the result. - A video usually takes longer. `muse_generate_video` then returns the `jobid`, and `muse_get_job` with `wait: true` picks it up. - A chat answer that is still running returns its `chatId` with `status: "running"` and a `lastEventId`. `muse_get_chat` with `wait: true` and `after` set to that `lastEventId` returns the rest. Clients that ask for progress notifications get one about every 10 seconds while a tool waits. Results show up to two small images as previews, and every file comes with its `assetId` and download URL. When a chat answer returns `status: "waiting_for_approval"`, the agent waits for your permission: the assistant should ask you, then answer with `muse_answer_approval`. `muse_reset_account` never resets on its first call. It returns a warning for the assistant to show you, and resets only when you type the account email and the assistant calls it again with that email as `confirm`. If the reset call errors or times out, it may still have run: check the account before calling it again. ## Example prompts - "Make a 10-second video of a corgi surfing at sunset, in exactly 9:16 aspect ratio." - "Make an image of a vintage motorcycle on wet cobblestones at night, then animate it into a video." - "Ask Muse to research the top 5 electric cars of 2026, write a comparison table as a CSV, and give me the files." - "Upload this photo from its URL and restore and colorize it." - "List my Muse chats and continue the newest one: ask for a shorter version." - "Ask Muse to open example.com in its browser, then give me a live view link so I can take control." - "List the web apps in my Muse Library and publish the newest one." ## Limits and notes - The tools use your Muse account, its weekly [Muse allowance](/docs/start-here/setup-muse#usage-limits), and the same rules as the REST API, such as `maxJobs` for jobs. - Before some actions, such as reaching a website or acting in a connected app, the agent asks for permission. See [GET /accounts/`email`/permissions](/docs/api-muse-v1/get-muse-accounts-email-permissions) to change when it asks. - A client may send up to 20 JSON-RPC requests in one batch. - If the client sends an `MCP-Protocol-Version` header, it must be one of the supported versions: `2025-06-18`, `2025-03-26` or `2024-11-05`. - Tool calls show in your [usage stats](/docs/account-management/get-account-stats) (`bot=muse`) through the REST call each tool makes, the same rows a direct API request writes. === URL: https://useapi.net/docs/api-muse-v1/post-muse-accounts-email-permissions-permissionId === Document URL: https://useapi.net/docs/api-muse-v1/post-muse-accounts-email-permissions-permissionId --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> accounts/`email`/permissions/`permissionId` description: "Change one Muse agent permission rule via POST accounts/email/permissions/permissionId in the useapi.net Muse API: allow, deny, or ask, which removes it." parent: Muse API nav_order: 124 permalink: /docs/api-muse-v1/post-muse-accounts-email-permissions-permissionId --- ## Change a permission rule October 12, 2026 (November 16, 2026) --- Change one standing rule of the Muse agent: allow or deny one website or app action. Find rules with [GET /accounts/`email`/permissions](/docs/api-muse-v1/get-muse-accounts-email-permissions). A rule is created when an approval is answered with `allow_always`. - `allow`: the agent goes ahead without asking. - `deny`: the agent may not do it. - `ask`: removes the rule, because asking is the default. The response then has `removed: true`. > **https://api.useapi.net/v1/muse/accounts/`email`/permissions/`permissionId`** - `email` is the email of an added account, URL-encoded in the path. - `permissionId` is the rule's `permissionId` from [GET /accounts/`email`/permissions](/docs/api-muse-v1/get-muse-accounts-email-permissions), URL-encoded in the path (it contains `:`). ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "mode": "deny" } ``` - `mode` is **required**, one of the rule's `modes`. Supported values: `allow`, `ask`, `deny`. ##### Responses **200** **200 OK** — the rule as it is now. With `mode: "ask"` the rule is gone and the response has `removed: true` instead of `rule`. ```json { "email": "example@gmail.com", "permissionId": "network_rule:hitl_domain_allow_nodesource_com_afdc93c7", "mode": "deny", "rule": { "permissionId": "network_rule:hitl_domain_allow_nodesource_com_afdc93c7", "type": "web", "mode": "deny", "modes": ["allow", "ask", "deny"], "title": "nodesource.com", "target": "nodesource.com:80,443", "note": null, "lifetime": "durable", "revocable": true, "created": null } } ``` ```json { "email": "example@gmail.com", "permissionId": "network_rule:hitl_domain_allow_nodesource_com_afdc93c7", "mode": "ask", "removed": true } ``` **400** **400 Bad Request** — `mode` is missing or is not one of the rule's `modes`. ```json { "error": "Parameter mode (sometimes) valid values: allow,ask,deny", "code": 400 } ``` **401** **401 Unauthorized** — Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **404** **404 Not Found** — the account named by `email` is not added, or it has no rule with this `permissionId`. ```json { "error": "Permission not found", "code": 404 } ``` **502** **502 Bad Gateway** — Muse did not change the rule. Retry. **503** **503 Service Unavailable** — Muse could not be read right now. Retry shortly. ```json { "error": "Muse could not be read right now (…), please retry", "code": 503 } ``` **596** **596 Account Error** The account needs your attention, and it is paused until you add it again. You receive an email when this happens. There are three causes. Meta asks for a security check on the account. Sign in once at [muse.ai](https://muse.ai) in a browser, complete the check, then add the account again with [POST /accounts](/docs/api-muse-v1/post-muse-accounts) using the same email and password. The API keeps using its session, so no new sign-in is needed. ```json { "error": "Account example@gmail.com: Meta asks for a security check on account example@gmail.com (\"This account must complete a security checkpoint on the web\"). Sign in once at https://muse.ai in a browser, complete the check, then add the account again with POST /accounts", "code": 596 } ``` Or Muse refused to sign the account in again when its session needed renewing, most often because the password was changed. Add the account again with the current password. ```json { "error": "Account example@gmail.com: Muse refused to sign in account example@gmail.com (…). Update its password with POST /accounts, or sign in at https://muse.ai to clear the block, then re-add it", "code": 596 } ``` Or Muse disabled the account's computer and refuses to start it again. Sign in at [muse.ai](https://muse.ai) in a browser to see why, and ask Muse support to restore it with the form Muse shows there. Add the account again only after Muse has restored it. ```json { "error": "Account example@gmail.com: Muse has disabled the computer of account example@gmail.com (\"VM wake unavailable\"). Sign in at https://muse.ai in a browser to see why and contact Muse support there, then add the account again with POST /accounts", "code": 596 } ``` ##### Model The rule as it is now after `allow` or `deny`, or `removed: true` after `ask`. <details markdown="block" class="model-details"> <summary>The changed rule, field by field</summary> ```typescript { // TypeScript, all fields are optional email: string permissionId: string mode: string // the mode you sent rule?: Rule // allow / deny: the rule as it is now, see GET /accounts/{email}/permissions removed?: true // ask: the rule is gone error?: string // errors only code?: number // errors only } ``` </details> ##### Examples **Curl** ``` bash EMAIL="example@gmail.com" curl -X POST -H "Authorization: Bearer …" \ -H "Content-Type: application/json" \ -d '{"mode": "deny"}' \ "https://api.useapi.net/v1/muse/accounts/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$EMAIL")/permissions/network_rule%3Ahitl_domain_allow_nodesource_com_afdc93c7" ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously added account email"; const permissionId = "permissionId from GET /accounts/{email}/permissions"; const apiUrl = `https://api.useapi.net/v1/muse/accounts/${encodeURIComponent(email)}/permissions/${encodeURIComponent(permissionId)}`; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ mode: "deny" }) }); console.log("response", response.status, await response.json()); ``` **Python** ``` python import requests from urllib.parse import quote token = "API token" email = "Previously added account email" permissionId = "permissionId from GET /accounts/{email}/permissions" apiUrl = f"https://api.useapi.net/v1/muse/accounts/{quote(email, safe='')}/permissions/{quote(permissionId, safe='')}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.post(apiUrl, headers=headers, json={"mode": "deny"}) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-muse-v1/post-muse-accounts-email-permissions === Document URL: https://useapi.net/docs/api-muse-v1/post-muse-accounts-email-permissions --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> accounts/`email`/permissions description: "Set whether the Muse agent asks first via POST accounts/email/permissions in the useapi.net Muse API: auto_allow or always_ask for websites and connected apps." parent: Muse API nav_order: 123 permalink: /docs/api-muse-v1/post-muse-accounts-email-permissions --- ## Change permission defaults October 12, 2026 (November 16, 2026) --- Set whether the Muse agent on this account asks before it acts. This is the same setting as in the muse.ai app. - `web` covers the websites the agent reaches, for example while it runs code. - `connectors` covers actions in the apps connected to the Muse account, such as email or calendar. Each one is `auto_allow` or `always_ask`: - `auto_allow` is Muse's "Ask for some actions", the default. Muse may act without asking, for example send an email from a connected Gmail. - `always_ask` is Muse's "Always ask". Muse asks before each such action, and the question comes to the chat as an [approval](/docs/api-muse-v1/post-muse-chats-chatId-approvals-approvalId). Send one or both. Rules for single websites and app actions stay as they are, see [GET /accounts/`email`/permissions](/docs/api-muse-v1/get-muse-accounts-email-permissions). > **https://api.useapi.net/v1/muse/accounts/`email`/permissions** - `email` is the email of an added account, URL-encoded in the path. ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "web": "always_ask", "connectors": "always_ask" } ``` - `web` is optional, the setting for websites. Supported values: `auto_allow`, `always_ask`. - `connectors` is optional, the setting for connected apps. Supported values: `auto_allow`, `always_ask`. Send at least one of them. ##### Responses **200** **200 OK** — the settings as they are now. ```json { "email": "example@gmail.com", "defaults": { "web": "always_ask", "connectors": "always_ask" } } ``` **400** **400 Bad Request** — neither `web` nor `connectors` was sent, or a value is not supported. ```json { "error": "Pass web and/or connectors (auto_allow or always_ask)", "code": 400 } ``` **401** **401 Unauthorized** — Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **404** **404 Not Found** — the account named by `email` is not added. ```json { "error": "Account example@gmail.com is not configured", "code": 404 } ``` **503** **503 Service Unavailable** — Muse could not be read right now. Retry shortly. ```json { "error": "Muse could not be read right now (…), please retry", "code": 503 } ``` **596** **596 Account Error** The account needs your attention, and it is paused until you add it again. You receive an email when this happens. There are three causes. Meta asks for a security check on the account. Sign in once at [muse.ai](https://muse.ai) in a browser, complete the check, then add the account again with [POST /accounts](/docs/api-muse-v1/post-muse-accounts) using the same email and password. The API keeps using its session, so no new sign-in is needed. ```json { "error": "Account example@gmail.com: Meta asks for a security check on account example@gmail.com (\"This account must complete a security checkpoint on the web\"). Sign in once at https://muse.ai in a browser, complete the check, then add the account again with POST /accounts", "code": 596 } ``` Or Muse refused to sign the account in again when its session needed renewing, most often because the password was changed. Add the account again with the current password. ```json { "error": "Account example@gmail.com: Muse refused to sign in account example@gmail.com (…). Update its password with POST /accounts, or sign in at https://muse.ai to clear the block, then re-add it", "code": 596 } ``` Or Muse disabled the account's computer and refuses to start it again. Sign in at [muse.ai](https://muse.ai) in a browser to see why, and ask Muse support to restore it with the form Muse shows there. Add the account again only after Muse has restored it. ```json { "error": "Account example@gmail.com: Muse has disabled the computer of account example@gmail.com (\"VM wake unavailable\"). Sign in at https://muse.ai in a browser to see why and contact Muse support there, then add the account again with POST /accounts", "code": 596 } ``` ##### Model The account's two default settings, `web` and `connectors`, as they are after the change. <details markdown="block" class="model-details"> <summary>The account's default settings, field by field</summary> ```typescript { // TypeScript, all fields are optional email: string defaults: { web: 'auto_allow' | 'always_ask' | null connectors: 'auto_allow' | 'always_ask' | null } error?: string // errors only code?: number // errors only } ``` </details> ##### Examples **Curl** ``` bash EMAIL="example@gmail.com" curl -X POST -H "Authorization: Bearer …" \ -H "Content-Type: application/json" \ -d '{"connectors": "always_ask"}' \ "https://api.useapi.net/v1/muse/accounts/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$EMAIL")/permissions" ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously added account email"; const apiUrl = `https://api.useapi.net/v1/muse/accounts/${encodeURIComponent(email)}/permissions`; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ connectors: "always_ask" }) }); console.log("response", response.status, await response.json()); ``` **Python** ``` python import requests from urllib.parse import quote token = "API token" email = "Previously added account email" apiUrl = f"https://api.useapi.net/v1/muse/accounts/{quote(email, safe='')}/permissions" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.post(apiUrl, headers=headers, json={"connectors": "always_ask"}) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-muse-v1/post-muse-accounts-email-reset === Document URL: https://useapi.net/docs/api-muse-v1/post-muse-accounts-email-reset --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> accounts/`email`/reset description: "Reset a Muse account to a fresh agent computer via POST accounts/email/reset in the useapi.net Muse API. Permanently deletes every chat, file and memory on it." parent: Muse API nav_order: 130 permalink: /docs/api-muse-v1/post-muse-accounts-email-reset --- ## Reset a Muse account October 14, 2026 (November 16, 2026) --- Reset the account's Muse computer, as Reset in the muse.ai app's data settings does. The account gets a fresh agent computer, and everything on the old one is deleted for good: every chat, file, document, web app and podcast, the agent's memory and its name, and any open browser. This cannot be undone. Use it when the account's computer is stuck, for example when every new browser stays `Queued` and stopping browsers does not help. The account stays added, with its sign-in, and the new agent starts with a short onboarding message of its own. - Send the account email again as `confirm`, so a reset never happens by mistake. - Every chat id, job id and asset id of the account answers `404` after the reset. - Do not repeat the call after a `202` or a timeout: the reset has run, and a repeat would reset the new computer too. Check the account with [GET /accounts/`email`](/docs/api-muse-v1/get-muse-accounts-email) or [GET /chats](/docs/api-muse-v1/get-muse-chats) instead. > **https://api.useapi.net/v1/muse/accounts/`email`/reset** - `email` is the email of an added account, URL-encoded in the path. ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "confirm": "example@gmail.com" } ``` - `confirm` is **required**, the account email, the same as in the path. ##### Responses **200** **200 OK** — the account was reset, and its new computer is ready. ```json { "email": "example@gmail.com", "reset": true, "ready": true } ``` **202** **202 Accepted** — the account was reset, and its new computer is still starting. Requests on the account may answer `503` for about a minute. Do not reset again. ```json { "email": "example@gmail.com", "reset": true, "ready": false, "message": "Muse reset the account; its new computer is not ready yet. Requests may answer 503 for a minute" } ``` **400** **400 Bad Request** — `confirm` is missing or is not the account email. Nothing was reset. ```json { "error": "confirm must be the account email (example@gmail.com): a reset permanently deletes every chat, file, artifact and memory of this Muse account", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **404** **404 Not Found** — the account named by `email` is not added. ```json { "error": "Account example@gmail.com not found", "code": 404 } ``` **409** **409 Conflict** — jobs or chat answers are running on the account, or a reset of it is already running. Nothing was reset. Retry when they finish. ```json { "error": "Account example@gmail.com has 1 running job(s) or chat answer(s). Reset it when they finish", "code": 409 } ``` ```json { "error": "A reset of account example@gmail.com is already running", "code": 409 } ``` **502** **502 Bad Gateway** — Muse refused the reset. Nothing was reset. ```json { "error": "Muse refused the reset of account example@gmail.com (…)", "code": 502 } ``` **503** **503 Service Unavailable** — Muse could not be reached. Nothing was reset. Retry shortly. ```json { "error": "Could not find the Muse computer of account example@gmail.com, please retry shortly", "code": 503 } ``` **596** **596 Account Error** The account needs your attention, and it is paused until you add it again. You receive an email when this happens. There are three causes. Meta asks for a security check on the account. Sign in once at [muse.ai](https://muse.ai) in a browser, complete the check, then add the account again with [POST /accounts](/docs/api-muse-v1/post-muse-accounts) using the same email and password. The API keeps using its session, so no new sign-in is needed. ```json { "error": "Account example@gmail.com: Meta asks for a security check on account example@gmail.com (\"This account must complete a security checkpoint on the web\"). Sign in once at https://muse.ai in a browser, complete the check, then add the account again with POST /accounts", "code": 596 } ``` Or Muse refused to sign the account in again when its session needed renewing, most often because the password was changed. Add the account again with the current password. ```json { "error": "Account example@gmail.com: Muse refused to sign in account example@gmail.com (…). Update its password with POST /accounts, or sign in at https://muse.ai to clear the block, then re-add it", "code": 596 } ``` Or Muse disabled the account's computer and refuses to start it again. Sign in at [muse.ai](https://muse.ai) in a browser to see why, and ask Muse support to restore it with the form Muse shows there. Add the account again only after Muse has restored it. ```json { "error": "Account example@gmail.com: Muse has disabled the computer of account example@gmail.com (\"VM wake unavailable\"). Sign in at https://muse.ai in a browser to see why and contact Muse support there, then add the account again with POST /accounts", "code": 596 } ``` ##### Model The answer confirms the reset, with `ready` set to `false` and status `202` while the new computer is still starting. <details markdown="block" class="model-details"> <summary>The reset result, field by field</summary> ```typescript { // TypeScript, all fields are optional email: string reset: true ready: boolean // false: the new computer is still starting (202) message?: string // 202 only error?: string // errors only code?: number // errors only } ``` </details> ##### Examples **Curl** ``` bash EMAIL="example@gmail.com" curl -X POST -H "Authorization: Bearer …" \ -H "Content-Type: application/json" \ -d "{\"confirm\": \"$EMAIL\"}" \ "https://api.useapi.net/v1/muse/accounts/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$EMAIL")/reset" ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously added account email"; const apiUrl = `https://api.useapi.net/v1/muse/accounts/${encodeURIComponent(email)}/reset`; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ confirm: email }) }); console.log("response", response.status, await response.json()); ``` **Python** ``` python import requests from urllib.parse import quote token = "API token" email = "Previously added account email" apiUrl = f"https://api.useapi.net/v1/muse/accounts/{quote(email, safe='')}/reset" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.post(apiUrl, headers=headers, json={"confirm": email}) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-muse-v1/post-muse-accounts === Document URL: https://useapi.net/docs/api-muse-v1/post-muse-accounts --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> accounts description: "Add a Muse account to the useapi.net Muse API with POST accounts: its email and password, signed in once and renewed by us, or change its maxJobs from 1 to 50." parent: Muse API nav_order: 100 permalink: /docs/api-muse-v1/post-muse-accounts --- ## Add or update a Muse account October 12, 2026 (November 16, 2026) --- Add a [Muse](https://muse.ai) account with its email and password. The account must have email + password sign-in: if it signs in only with an emailed code, create a password in [Meta Accounts Center](https://accountscenter.meta.com/password_and_security/) first. See [Setup Muse](/docs/start-here/setup-muse) for what the account needs and what to expect. Once added, the account is managed by the API: it signs in once, keeps the account signed in, and renews the 30-day Muse session itself, a day before it expires or whenever Muse stops accepting it, using the stored password. You never re-add the account for that. Each sign-in makes Muse email the account a login code, which needs no action. After the sign-in the API reads the account's Muse plan and weekly usage (`quota`). If Meta asks for a security check on the account, the account is saved but paused, and the answer is `596`: sign in once at [muse.ai](https://muse.ai) in a browser, complete the check, then post the same email and password again. Posting an account that is already added re-adds it. With the same password and a session Muse still accepts, the API keeps that session and signs in nothing new. `added`, `maxJobs` and the session are kept unless you send a new `maxJobs` or a new password. A re-add also lets an account that sits out video jobs after Muse's [video limit](/docs/api-muse-v1/post-muse-jobs-video#video-limit) take them again right away. This endpoint does two things. To add or re-add an account, post `email` and `password`. To change only `maxJobs` on an account that is already added, post `email` and `maxJobs` without `password`: nothing is sent to Muse then. Each [useapi.net subscription](/docs/subscription) lets you add 3 Muse accounts. > **https://api.useapi.net/v1/muse/accounts** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body Add or re-add an account: ```json { "email": "example@gmail.com", "password": "your Muse password", "maxJobs": 2 } ``` - `email` is **required**, the email of the Muse account. - `password` is **required** to add or re-add an account, the account's Muse password. Maximum length: `256` characters. A wrong password returns `400`. So does an account without a password (one that signs in only with an emailed code): create a password in [Meta Accounts Center](https://accountscenter.meta.com/password_and_security/) first. - `maxJobs` is optional, the number of jobs this account may run at the same time. Range: `1` to `50`. Default: `10` for a new account, the current value on a re-add. Accounts added before the default changed keep their stored value until you update it. Update an added account: ```json { "email": "example@gmail.com", "maxJobs": 3 } ``` - `email` is **required**, the email of an added account. - `maxJobs` is **required** in this mode, the new limit. Range: `1` to `50`. ##### Responses **200** **200 OK** — the account was already added and has been re-added or updated. ```json { "email": "example@gmail.com", "maxJobs": 3, "added": "2026-10-12T00:34:19.139Z", "updated": "2026-10-12T01:13:03.745Z", "sessionExpiresAt": "2026-11-11T00:34:18.820Z", "quota": { "tier": "HATCH_FREE", "percentUsed": 0, "resetsAt": "2026-10-19T01:13:03.000Z", "quotaStatus": "SUFFICIENT", "topupBalance": 0, "topupTotal": 0, "topupLabel": null, "readAt": "2026-10-12T01:13:03.745Z" }, "health": "OK" } ``` - `sessionExpiresAt` is when the current Muse session ends. The API renews it before then. - `quota` is the account's Muse plan and weekly usage, as read now. It is left out when Muse did not answer the read. [GET /accounts/`email`](/docs/api-muse-v1/get-muse-accounts-email) reads it live at any time. - An update (`email` + `maxJobs`) returns the same record with `quota` as last read. **201** **201 Created** — a new account was added. Same body as `200`, without `updated`. ```json { "email": "example@gmail.com", "maxJobs": 2, "added": "2026-10-12T00:34:19.139Z", "sessionExpiresAt": "2026-11-11T00:34:18.820Z", "health": "OK" } ``` **400** **400 Bad Request** — Muse refused the sign-in (a wrong email or password, or an account without a password), `password` and `maxJobs` are both missing, or a parameter is invalid. ```json { "error": "Meta account example@gmail.com has no password: it signs in with an emailed code only. Create a password in Meta Accounts Center (https://accountscenter.meta.com/password_and_security/), then add the account again", "code": 400 } ``` ```json { "error": "Parameter maxJobs (99) is more than 50", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **402** **402 Payment Required** — the subscription has expired, or a new account needs another [subscription](/docs/subscription). ```json { "error": "useapi.net ⁝ You have 1 subscription, you need 1 additional subscription (2 total) to support 4 accounts for the muse API. Upgrade at https://useapi.net/docs/subscription", "code": 402 } ``` **404** **404 Not Found** — update mode: no account is added for this `email`. ```json { "error": "Account example@gmail.com not found. Add it with email and password", "code": 404 } ``` **503** **503 Service Unavailable** — Muse could not be reached or the sign-in could not finish right now. Nothing was saved. Retry shortly. ```json { "error": "Could not reach Muse (gateway: /api/session returned no vm_id), please retry shortly", "code": 503 } ``` **596** **596 Account Error** Meta asks for a security check on the account. The account is saved with its session but paused. Sign in once at [muse.ai](https://muse.ai) in a browser, complete the check, then post the same email and password again: the API then uses the session it already has. ```json { "error": "Account example@gmail.com: Meta asks for a security check on account example@gmail.com (\"This account must complete a security checkpoint on the web\"). Sign in once at https://muse.ai in a browser, complete the check, then add the account again with POST /accounts", "code": 596 } ``` ##### Model `200` and `201` return the same account record. The password and the session are never returned. <details markdown="block" class="model-details"> <summary>The account record, field by field</summary> ```typescript { // TypeScript, all fields are optional email: string maxJobs: number // jobs this account may run at the same time added: string // ISO 8601, when the account was first added updated?: string // ISO 8601, the last re-add or maxJobs change sessionExpiresAt: string // ISO 8601, when the Muse session expires (30 days, renewed by the API) quota?: { // the account's Muse plan and weekly usage, as last read tier: string | null // Muse plan, e.g. HATCH_FREE percentUsed: number | null // share of the weekly allowance used, in whole percent resetsAt: string | null // ISO 8601, when the weekly allowance resets quotaStatus: string | null // SUFFICIENT while jobs may run topupBalance: number | null // top-up left, in Muse's own unit, not tokens topupTotal: number | null // top-up bought, in the same unit topupLabel: string | null // the top-up as muse.ai shows it, e.g. '0% used (1B tokens left)' readAt: string // ISO 8601, when this was read from Muse } health: string // 'OK', or why the account needs attention (596) videoLimitUntil?: string // ISO 8601, only while Muse's video limit for the last 24 hours holds the // account: video jobs skip it until then. A re-add clears it videoRegionBlocked?: string // ISO 8601, when Muse said video is not available for this account in its // country or region: video jobs skip it. A re-add clears it error?: string // errors only code?: number // errors only } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/muse/accounts" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "email": "example@gmail.com", "password": "…", "maxJobs": 2 }' ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = "https://api.useapi.net/v1/muse/accounts"; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ email: "Muse account email", password: "Muse account password", maxJobs: 2 }) }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" apiUrl = "https://api.useapi.net/v1/muse/accounts" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } data = { "email": "Muse account email", "password": "Muse account password", "maxJobs": 2 } response = requests.post(apiUrl, headers=headers, json=data) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-muse-v1/post-muse-assets-assetId-share === Document URL: https://useapi.net/docs/api-muse-v1/post-muse-assets-assetId-share --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> assets/`assetId`/share description: "Publish a web app the Muse agent built on a public link via POST assets/assetId/share in the useapi.net Muse API. Muse reviews the app first and can refuse it." parent: Muse API nav_order: 335 permalink: /docs/api-muse-v1/post-muse-assets-assetId-share --- ## Publish a web app October 12, 2026 (November 16, 2026) --- Publish a web app the agent built on a public link. Anyone with the link can open the app, signed in to Muse or not. The app opens inside Muse's own page. Find web apps with [GET /assets](/docs/api-muse-v1/get-muse-assets) `?type=web`, or in a chat's web-app widget (`kind` `space_build_completed`). Muse reviews the app before it goes out, which takes about 15 seconds, and can refuse it: the `422` response says why, with the issues it found in `errorDetails`. Publishing again republishes the current version of the app, under the same link. The link shows as `shareUrl` in [GET /assets](/docs/api-muse-v1/get-muse-assets). Stop sharing with [DELETE /assets/`assetId`/share](/docs/api-muse-v1/delete-muse-assets-assetId-share). > **https://api.useapi.net/v1/muse/assets/`assetId`/share** - `assetId` is the URL-encoded `assetId` of a web app, an asset of `type` `web`. ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** ```json { "assetId": "user:12345-email:6578616d706c6540676d61696c2e636f6d-web:space~hello-demo", "shareUrl": "https://muse.ai/s/hello-demo-k3v9q2m7xw4pzrt" } ``` **400** **400 Bad Request** — the path value is not a Muse `assetId`, or the asset is not a web app. ```json { "error": "Only web apps (assets of type web) can be shared", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** — the `assetId` was issued to a different API token. ```json { "error": "This asset id does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** — the web app is not there (deleted), or the account that holds it is not added. ```json { "error": "Asset not found", "code": 404 } ``` **422** **422 Unprocessable Content** — Muse reviewed the app and refused to publish it. `errorDetails` lists the issues it found. Ask the agent to fix them, then publish again. When Muse asks for an extra confirmation instead, publish the app once from the muse.ai app. ```json { "error": "Muse refused to publish this app: …", "errorDetails": "Issues found:\n- …", "code": 422 } ``` **502** **502 Bad Gateway** — Muse did not publish the app. Retry shortly. ```json { "error": "Muse did not publish the app (HTTP 500: …), please retry", "code": 502 } ``` **503** **503 Service Unavailable** — Muse could not be reached. Retry shortly. ```json { "error": "Could not connect to the Muse workspace of account example@gmail.com (…), please retry shortly", "code": 503 } ``` **504** **504 Gateway Timeout** — Muse did not answer in time. The app may still be publishing: check `shareUrl` in [GET /assets](/docs/api-muse-v1/get-muse-assets) `?type=web` shortly. ```json { "error": "Muse did not answer (…); the app may still be publishing: check shareUrl in GET /assets?type=web shortly", "code": 504 } ``` **596** **596 Account Error** The account needs your attention, and it is paused until you add it again. You receive an email when this happens. There are three causes. Meta asks for a security check on the account. Sign in once at [muse.ai](https://muse.ai) in a browser, complete the check, then add the account again with [POST /accounts](/docs/api-muse-v1/post-muse-accounts) using the same email and password. The API keeps using its session, so no new sign-in is needed. ```json { "error": "Account example@gmail.com: Meta asks for a security check on account example@gmail.com (\"This account must complete a security checkpoint on the web\"). Sign in once at https://muse.ai in a browser, complete the check, then add the account again with POST /accounts", "code": 596 } ``` Or Muse refused to sign the account in again when its session needed renewing, most often because the password was changed. Add the account again with the current password. ```json { "error": "Account example@gmail.com: Muse refused to sign in account example@gmail.com (…). Update its password with POST /accounts, or sign in at https://muse.ai to clear the block, then re-add it", "code": 596 } ``` Or Muse disabled the account's computer and refuses to start it again. Sign in at [muse.ai](https://muse.ai) in a browser to see why, and ask Muse support to restore it with the form Muse shows there. Add the account again only after Muse has restored it. ```json { "error": "Account example@gmail.com: Muse has disabled the computer of account example@gmail.com (\"VM wake unavailable\"). Sign in at https://muse.ai in a browser to see why and contact Muse support there, then add the account again with POST /accounts", "code": 596 } ``` ##### Model The web app's `assetId` and the public link to it in `shareUrl`. <details markdown="block" class="model-details"> <summary>The web app's public link, field by field</summary> ```typescript { // TypeScript, all fields are optional assetId: string shareUrl: string | null // the public link, null after stopping sharing error?: string // errors only code?: number // errors only } ``` </details> ##### Examples **Curl** ``` bash ASSETID="user:12345-email:6578616d706c6540676d61696c2e636f6d-web:space~hello-demo" curl -X POST -H "Authorization: Bearer …" \ "https://api.useapi.net/v1/muse/assets/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$ASSETID")/share" ``` **JavaScript** ``` javascript const token = "API token"; const assetId = "assetId of a web app from GET /assets?type=web"; const apiUrl = `https://api.useapi.net/v1/muse/assets/${encodeURIComponent(assetId)}/share`; const response = await fetch(apiUrl, { method: "POST", headers: { "Authorization": `Bearer ${token}`, }, }); console.log("response", response.status, await response.json()); ``` **Python** ``` python import requests from urllib.parse import quote token = "API token" assetId = "assetId of a web app from GET /assets?type=web" apiUrl = "https://api.useapi.net/v1/muse/assets/" + quote(assetId, safe="") + "/share" headers = { "Authorization" : f"Bearer {token}" } response = requests.post(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-muse-v1/post-muse-assets === Document URL: https://useapi.net/docs/api-muse-v1/post-muse-assets --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> assets description: "Upload an image, video or audio file of up to 50 MB via POST assets in the useapi.net Muse API, as raw bytes or from a public URL, and get back its assetId." parent: Muse API nav_order: 300 permalink: /docs/api-muse-v1/post-muse-assets --- ## Upload an asset October 12, 2026 (November 16, 2026) --- Upload an image, a video or an audio file to one of your Muse accounts and get an `assetId` for it. Send the file as the raw request body with its MIME type in the `Content-Type` header (no multipart), or send JSON with the file's `url` and the API fetches it. The file is written into the Muse workspace of the account, where the muse.ai app keeps its files too. Nothing is stored at useapi.net. Pass the `assetId` as `image_N`, `video_N` or `audio_N` to [POST /jobs/image](/docs/api-muse-v1/post-muse-jobs-image) or [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video). A file Muse made needs no upload: its `assetId` from the job's `result.assets[]` works the same way. The `assetId` names your API token, the account and the file, and only jobs and chats on that account can use it. To use several uploads in one job, upload them all to the same account with `email`. The same file uploaded to the same account again gets the same `assetId` and is not written twice. An upload takes no `maxJobs` slot and uses no Muse allowance. > **https://api.useapi.net/v1/muse/assets?email=`email`** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: image/jpeg # the file's MIME type, see the list below Content-Length: 316641 # most HTTP clients set it for you ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. - `Content-Type` is **required**, the file's MIME type. Supported values: `image/jpeg`, `image/png`, `image/webp`, `video/mp4`, `video/quicktime`, `video/webm`, `audio/mpeg`, `audio/wav`, `audio/x-wav`, `audio/mp4`, `audio/x-m4a`, `audio/ogg`. - `Content-Length` is **required**, the file size in bytes. A request without it answers `411`. The request body is the file's raw bytes, from 1 byte to `52,428,800` bytes (50 MB). Muse takes a file in 1 MB pieces, so an upload runs at about 1 MB per second: a 50 MB file takes about a minute. ##### Upload from a URL Instead of the file, send `Content-Type: application/json` and a JSON body with the file's address. The API downloads the file and uploads it as above. ```json { "url": "https://your-domain.com/photos/rider.jpg" } ``` - `url` is **required** in this form, a public `https` URL of the file. Maximum length: `2048` characters. - The URL must answer with one of the supported `Content-Type` values listed above, and the file must be at most 50 MB. ##### Query Parameters - `email` is optional, the account to upload to. When omitted, a healthy account with allowance left is picked at random. URL-encode it. ##### Responses **200** **200 OK** ```json { "assetId": "user:12345-email:6578616d706c6540676d61696c2e636f6d-image:d62d3099acbf50a46bc2155a0d18e79dc371ecdc6e4d28a072aa5bbd070bcfd3.jpg", "email": "example@gmail.com", "type": "image", "mime": "image/jpeg", "bytes": 316641 } ``` **400** **400 Bad Request** — an unsupported `Content-Type`, an empty body, a `url` that could not be downloaded or is not a supported file, or no Muse account added yet. ```json { "error": "Content-Type must be one of image/jpeg, image/png, image/webp, video/mp4, video/quicktime, video/webm, audio/mpeg, audio/wav, audio/x-wav, audio/mp4, audio/x-m4a, audio/ogg (raw file bytes in the body), or send JSON {\"url\": \"https://…\"}", "code": 400 } ``` ```json { "error": "The url's file type text/html is not supported: image/jpeg, image/png, image/webp, video/mp4, video/quicktime, video/webm, audio/mpeg, audio/wav, audio/x-wav, audio/mp4, audio/x-m4a, audio/ogg", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **404** **404 Not Found** — the account named by `email` is not added. ```json { "error": "Account example@gmail.com is not configured", "code": 404 } ``` **411** **411 Length Required** — the request has no `Content-Length` header, for example a streamed (chunked) body. ```json { "error": "Content-Length is required (send the file as the raw request body)", "code": 411 } ``` **412** **412 Precondition Failed** — the account's weekly Muse allowance is used up (or every account's, without `email`). ```json { "error": "All 2 healthy accounts have used up their Muse allowance. GET /accounts/{email} re-reads it", "code": 412 } ``` **413** **413 Content Too Large** — the file is larger than 52,428,800 bytes (50 MB). ```json { "error": "File must be at most 52428800 bytes", "code": 413 } ``` **502** **502 Bad Gateway** — Muse did not store the file. Retry. ```json { "error": "Muse did not store the file (…), please retry", "code": 502 } ``` **503** **503 Service Unavailable** — Muse could not be reached, or the same file is being uploaded to the account by another request. Retry shortly. ```json { "error": "Could not connect to the Muse workspace of account example@gmail.com (…), please retry shortly", "code": 503 } ``` **596** **596 Account Error** The account needs your attention, and it is paused until you add it again. You receive an email when this happens. There are three causes. Meta asks for a security check on the account. Sign in once at [muse.ai](https://muse.ai) in a browser, complete the check, then add the account again with [POST /accounts](/docs/api-muse-v1/post-muse-accounts) using the same email and password. The API keeps using its session, so no new sign-in is needed. ```json { "error": "Account example@gmail.com: Meta asks for a security check on account example@gmail.com (\"This account must complete a security checkpoint on the web\"). Sign in once at https://muse.ai in a browser, complete the check, then add the account again with POST /accounts", "code": 596 } ``` Or Muse refused to sign the account in again when its session needed renewing, most often because the password was changed. Add the account again with the current password. ```json { "error": "Account example@gmail.com: Muse refused to sign in account example@gmail.com (…). Update its password with POST /accounts, or sign in at https://muse.ai to clear the block, then re-add it", "code": 596 } ``` Or Muse disabled the account's computer and refuses to start it again. Sign in at [muse.ai](https://muse.ai) in a browser to see why, and ask Muse support to restore it with the form Muse shows there. Add the account again only after Muse has restored it. ```json { "error": "Account example@gmail.com: Muse has disabled the computer of account example@gmail.com (\"VM wake unavailable\"). Sign in at https://muse.ai in a browser to see why and contact Muse support there, then add the account again with POST /accounts", "code": 596 } ``` ##### Model The new `assetId` with the account it was uploaded to, the file's type, MIME type and size. <details markdown="block" class="model-details"> <summary>The uploaded file, field by field</summary> ```typescript { // TypeScript, all fields are optional assetId: string // user:<id>-email:<hex of the email>-<image|video|audio>:<sha256>.<ext> email: string // the account the file was uploaded to type: 'image' | 'video' | 'audio' mime: string // the file's Content-Type bytes: number // the file size error?: string // errors only code?: number // errors only } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/muse/assets?email=example%40gmail.com" \ -H "Authorization: Bearer …" \ -H "Content-Type: image/jpeg" \ --data-binary @rider.jpg ``` **Curl (url)** ``` bash curl -X POST "https://api.useapi.net/v1/muse/assets?email=example%40gmail.com" \ -H "Authorization: Bearer …" \ -H "Content-Type: application/json" \ -d '{"url": "https://your-domain.com/photos/rider.jpg"}' ``` **JavaScript** ``` javascript import fs from "fs"; const token = "API token"; const email = "Previously added account email"; const apiUrl = `https://api.useapi.net/v1/muse/assets?email=${encodeURIComponent(email)}`; const response = await fetch(apiUrl, { method: "POST", headers: { "Authorization": `Bearer ${token}`, "Content-Type": "image/jpeg", }, body: fs.readFileSync("rider.jpg") }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously added account email" apiUrl = "https://api.useapi.net/v1/muse/assets" headers = { "Authorization" : f"Bearer {token}", "Content-Type": "image/jpeg" } with open("rider.jpg", "rb") as f: response = requests.post(apiUrl, headers=headers, params={"email": email}, data=f.read()) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-muse-v1/post-muse-chats-chatId-approvals-approvalId === Document URL: https://useapi.net/docs/api-muse-v1/post-muse-chats-chatId-approvals-approvalId --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> chats/`chatId`/approvals/`approvalId` description: "Answer the Muse agent's permission request via POST chats/chatId/approvals/approvalId in the useapi.net Muse API: allow once, always allow the site, or deny." parent: Muse API nav_order: 435 permalink: /docs/api-muse-v1/post-muse-chats-chatId-approvals-approvalId --- ## Answer an approval October 12, 2026 (November 16, 2026) --- Before some actions, for example sending information to a website while it runs code, the Muse agent asks for your permission. The question arrives on [GET /chats/`chatId`/stream](/docs/api-muse-v1/get-muse-chats-chatId-stream) as an `approval` event, and [GET /chats/`chatId`](/docs/api-muse-v1/get-muse-chats-chatId) lists the open ones in `pendingApprovals`. This endpoint gives your answer. While a request waits, the answer is paused: the stream shows a `status` event `pending_user_confirmation`, and no `turn.done` comes. After your answer, the stream shows `approval.resolved`, and the agent goes on. - `allow_once` allows this one request. - `allow_always` allows the site from now on, for the whole Muse account. It is Muse's own "Always allow this site" and stays in place. - `deny` refuses the request. The agent goes on without it. A request that is not answered by its `expires` time ends as timed out. > **https://api.useapi.net/v1/muse/chats/`chatId`/approvals/`approvalId`** - `chatId` is URL-encoded in the path (it contains `:` and `@`). - `approvalId` is the `approvalId` of the `approval` event. ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "decision": "allow_once" } ``` - `decision` is **required**, one of the `decision` values in the request's `options`, usually `allow_once`, `allow_always` or `deny`. An `approval` event looks like this: ```json { "event": "approval", "approvalId": "87c8850c-5c3e-49be-b4d8-981d7fe31952", "title": "Share info with deb.nodesource.com", "question": "Allow Muse to share information with deb.nodesource.com?", "details": [ { "label": "Host", "value": "deb.nodesource.com" }, { "label": "Grants", "value": "nodesource.com and all subdomains" }, { "label": "Method", "value": "CONNECT" }, { "label": "Path", "value": "deb.nodesource.com:443" }, { "label": "Policy", "value": "tool.exec" } ], "options": [ { "decision": "allow_once", "label": "Allow once" }, { "decision": "allow_always", "label": "Always allow this site" }, { "decision": "deny", "label": "Deny" } ], "expires": "2026-10-13T00:42:04.519Z" } ``` ##### Responses **200** **200 OK** — Muse took the answer. `status` is `approved` or `denied`, or `decided` when Muse does not say. ```json { "chatId": "c-u12345-email:example@gmail.com-chat:e72e976b-1e33-4406-b8ae-e2980040e9f9-bot:muse", "approvalId": "87c8850c-5c3e-49be-b4d8-981d7fe31952", "decision": "allow_once", "status": "approved" } ``` **400** **400 Bad Request** — `decision` is missing or is not one of the request's options, or a path value is invalid. ```json { "error": "decision must be one of allow_once, allow_always, deny", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** — the `chatId` was issued to a different API token. ```json { "error": "This chat id does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** — this chat has no request with this `approvalId`, or the account that holds the chat is not added. ```json { "error": "Approval not found for this chat", "code": 404 } ``` **409** **409 Conflict** — the request is no longer waiting: it was already answered, or it timed out. ```json { "error": "This approval is no longer waiting (status approved, decision allow_once)", "code": 409 } ``` **502** **502 Bad Gateway** — Muse did not take the answer. Retry while the request is still waiting. **503** **503 Service Unavailable** — Muse could not be reached. Retry shortly. **596** **596 Account Error** The account needs your attention, and it is paused until you add it again. You receive an email when this happens. There are three causes. Meta asks for a security check on the account. Sign in once at [muse.ai](https://muse.ai) in a browser, complete the check, then add the account again with [POST /accounts](/docs/api-muse-v1/post-muse-accounts) using the same email and password. The API keeps using its session, so no new sign-in is needed. ```json { "error": "Account example@gmail.com: Meta asks for a security check on account example@gmail.com (\"This account must complete a security checkpoint on the web\"). Sign in once at https://muse.ai in a browser, complete the check, then add the account again with POST /accounts", "code": 596 } ``` Or Muse refused to sign the account in again when its session needed renewing, most often because the password was changed. Add the account again with the current password. ```json { "error": "Account example@gmail.com: Muse refused to sign in account example@gmail.com (…). Update its password with POST /accounts, or sign in at https://muse.ai to clear the block, then re-add it", "code": 596 } ``` Or Muse disabled the account's computer and refuses to start it again. Sign in at [muse.ai](https://muse.ai) in a browser to see why, and ask Muse support to restore it with the form Muse shows there. Add the account again only after Muse has restored it. ```json { "error": "Account example@gmail.com: Muse has disabled the computer of account example@gmail.com (\"VM wake unavailable\"). Sign in at https://muse.ai in a browser to see why and contact Muse support there, then add the account again with POST /accounts", "code": 596 } ``` ##### Model The decision you sent and the approval's `status`: approved, denied, or decided when Muse does not say. <details markdown="block" class="model-details"> <summary>The answered approval, field by field</summary> ```typescript { // TypeScript, all fields are optional chatId: string approvalId: string decision: string // the decision you sent status: string // approved or denied, or decided when Muse does not say error?: string // errors only code?: number // errors only } ``` </details> ##### Examples **Curl** ``` bash CHATID="c-u12345-email:example@gmail.com-chat:e72e976b-1e33-4406-b8ae-e2980040e9f9-bot:muse" APPROVALID="87c8850c-5c3e-49be-b4d8-981d7fe31952" curl -X POST "https://api.useapi.net/v1/muse/chats/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$CHATID")/approvals/$APPROVALID" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{"decision": "allow_once"}' ``` **JavaScript** ``` javascript const token = "API token"; const chatId = "chatId from POST /chats"; const approvalId = "approvalId from the approval event"; const apiUrl = `https://api.useapi.net/v1/muse/chats/${encodeURIComponent(chatId)}/approvals/${encodeURIComponent(approvalId)}`; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ decision: "allow_once" }) }); console.log("response", response.status, await response.json()); ``` **Python** ``` python import requests from urllib.parse import quote token = "API token" chatId = "chatId from POST /chats" approvalId = "approvalId from the approval event" apiUrl = f"https://api.useapi.net/v1/muse/chats/{quote(chatId, safe='')}/approvals/{quote(approvalId, safe='')}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.post(apiUrl, headers=headers, json={"decision": "allow_once"}) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-muse-v1/post-muse-chats-chatId-browser-taskId-release === Document URL: https://useapi.net/docs/api-muse-v1/post-muse-chats-chatId-browser-taskId-release --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> chats/`chatId`/browser/`taskId`/release description: "Give the agent's browser back to Muse via POST chats/chatId/browser/taskId/release in the useapi.net Muse API, after you took control of it in a live viewer." parent: Muse API nav_order: 471 permalink: /docs/api-muse-v1/post-muse-chats-chatId-browser-taskId-release --- ## Give the browser back October 14, 2026 (November 16, 2026) --- Give control of the agent's browser back to the agent, like the Done button in the muse.ai app. Use it after you took control of the browser in a [viewer](/docs/api-muse-v1/post-muse-chats-chatId-browser-taskId-viewer), when the viewer is no longer open to give it back itself. The viewer page has its own Release control button, and control also returns to the agent when the viewer closes. The call answers `200` with `controlOwner: "agent"` also when the agent already has control, so it is safe to repeat. See the [Live Browser Guide](/docs/api-muse-v1/live-browser-guide) for the whole flow. > **https://api.useapi.net/v1/muse/chats/`chatId`/browser/`taskId`/release** - `chatId` is URL-encoded in the path (it contains `:` and `@`). - `taskId` is the `taskId` of the chat's `browser` event. ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** ```json { "chatId": "c-u12345-email:example@gmail.com-chat:8e0bf21e-a3b5-4a1e-a05a-65d160469bfb-bot:muse", "taskId": "423bc12e-db16-4921-8670-08b5f3f5a5d6", "released": true, "controlOwner": "agent" } ``` **400** **400 Bad Request** — the path holds no valid `chatId` or `taskId`. ```json { "error": "Path parameter taskId (not-a-task) is not a valid browser task id", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** — the `chatId` was issued to a different API token. ```json { "error": "This chat id does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** — the chat or the browser was not found, or the account that holds the chat is not added. ```json { "error": "Browser task not found in this chat", "code": 404 } ``` **409** **409 Conflict** — the browser is closed, or Muse refused the release. ```json { "error": "This browser is already closed", "code": 409 } ``` **502** **502 Bad Gateway** — Muse did not take the release. Retry shortly. ```json { "error": "Muse refused the release (HTTP 500)", "code": 502 } ``` **503** **503 Service Unavailable** — Muse could not be reached. Retry shortly. ```json { "error": "Could not connect to the Muse workspace of account example@gmail.com (…), please retry shortly", "code": 503 } ``` **596** **596 Account Error** The account needs your attention, and it is paused until you add it again. You receive an email when this happens. There are three causes. Meta asks for a security check on the account. Sign in once at [muse.ai](https://muse.ai) in a browser, complete the check, then add the account again with [POST /accounts](/docs/api-muse-v1/post-muse-accounts) using the same email and password. The API keeps using its session, so no new sign-in is needed. ```json { "error": "Account example@gmail.com: Meta asks for a security check on account example@gmail.com (\"This account must complete a security checkpoint on the web\"). Sign in once at https://muse.ai in a browser, complete the check, then add the account again with POST /accounts", "code": 596 } ``` Or Muse refused to sign the account in again when its session needed renewing, most often because the password was changed. Add the account again with the current password. ```json { "error": "Account example@gmail.com: Muse refused to sign in account example@gmail.com (…). Update its password with POST /accounts, or sign in at https://muse.ai to clear the block, then re-add it", "code": 596 } ``` Or Muse disabled the account's computer and refuses to start it again. Sign in at [muse.ai](https://muse.ai) in a browser to see why, and ask Muse support to restore it with the form Muse shows there. Add the account again only after Muse has restored it. ```json { "error": "Account example@gmail.com: Muse has disabled the computer of account example@gmail.com (\"VM wake unavailable\"). Sign in at https://muse.ai in a browser to see why and contact Muse support there, then add the account again with POST /accounts", "code": 596 } ``` ##### Model The answer names the chat and the browser with `released: true` and `controlOwner` set to `agent`. <details markdown="block" class="model-details"> <summary>The released browser, field by field</summary> ```typescript { // TypeScript, all fields are optional chatId: string taskId: string released: true controlOwner: string // agent error?: string // errors only code?: number // errors only } ``` </details> ##### Examples **Curl** ``` bash CHATID="c-u12345-email:example@gmail.com-chat:8e0bf21e-a3b5-4a1e-a05a-65d160469bfb-bot:muse" TASKID="423bc12e-db16-4921-8670-08b5f3f5a5d6" curl -X POST -H "Authorization: Bearer …" \ "https://api.useapi.net/v1/muse/chats/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$CHATID")/browser/$TASKID/release" ``` **JavaScript** ``` javascript const token = "API token"; const chatId = "chatId from POST /chats"; const taskId = "taskId from the stream's browser event"; const apiUrl = `https://api.useapi.net/v1/muse/chats/${encodeURIComponent(chatId)}/browser/${encodeURIComponent(taskId)}/release`; const response = await fetch(apiUrl, { method: "POST", headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", response.status, result); ``` **Python** ``` python import requests from urllib.parse import quote token = "API token" chatId = "chatId from POST /chats" taskId = "taskId from the stream's browser event" apiUrl = f"https://api.useapi.net/v1/muse/chats/{quote(chatId, safe='')}/browser/{quote(taskId, safe='')}/release" headers = { "Authorization" : f"Bearer {token}" } response = requests.post(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-muse-v1/post-muse-chats-chatId-browser-taskId-stop === Document URL: https://useapi.net/docs/api-muse-v1/post-muse-chats-chatId-browser-taskId-stop --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> chats/`chatId`/browser/`taskId`/stop description: "Close the agent's browser for good via POST chats/chatId/browser/taskId/stop in the useapi.net Muse API, freeing one of the account's two browsers." parent: Muse API nav_order: 472 permalink: /docs/api-muse-v1/post-muse-chats-chatId-browser-taskId-stop --- ## Stop the agent's browser October 14, 2026 (November 16, 2026) --- Close a browser the agent opened, for good, like closing it in the muse.ai app. Open viewers end, and the stream's `browser` event then shows `ended: true`. The chat stays. A Muse account runs at most 2 browsers at a time, and a new one waits with status `Queued` while both are busy. Stop a browser you no longer need, and always before you [delete its chat](/docs/api-muse-v1/delete-muse-chats-chatId): a browser of a deleted chat can no longer be reached. See the [Live Browser Guide](/docs/api-muse-v1/live-browser-guide) for the whole flow. > **https://api.useapi.net/v1/muse/chats/`chatId`/browser/`taskId`/stop** - `chatId` is URL-encoded in the path (it contains `:` and `@`). - `taskId` is the `taskId` of the chat's `browser` event. ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** ```json { "chatId": "c-u12345-email:example@gmail.com-chat:8e0bf21e-a3b5-4a1e-a05a-65d160469bfb-bot:muse", "taskId": "423bc12e-db16-4921-8670-08b5f3f5a5d6", "stopped": true } ``` **400** **400 Bad Request** — the path holds no valid `chatId` or `taskId`. ```json { "error": "Path parameter taskId (not-a-task) is not a valid browser task id", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** — the `chatId` was issued to a different API token. ```json { "error": "This chat id does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** — the chat or the browser was not found, or the account that holds the chat is not added. ```json { "error": "Browser task not found in this chat", "code": 404 } ``` **409** **409 Conflict** — the browser is already closed, or Muse refused to close it. ```json { "error": "This browser is already closed", "code": 409 } ``` **502** **502 Bad Gateway** — Muse did not close the browser. Retry shortly. ```json { "error": "Muse refused the stop (HTTP 500)", "code": 502 } ``` **503** **503 Service Unavailable** — Muse could not be reached. Retry shortly. ```json { "error": "Could not connect to the Muse workspace of account example@gmail.com (…), please retry shortly", "code": 503 } ``` **596** **596 Account Error** The account needs your attention, and it is paused until you add it again. You receive an email when this happens. There are three causes. Meta asks for a security check on the account. Sign in once at [muse.ai](https://muse.ai) in a browser, complete the check, then add the account again with [POST /accounts](/docs/api-muse-v1/post-muse-accounts) using the same email and password. The API keeps using its session, so no new sign-in is needed. ```json { "error": "Account example@gmail.com: Meta asks for a security check on account example@gmail.com (\"This account must complete a security checkpoint on the web\"). Sign in once at https://muse.ai in a browser, complete the check, then add the account again with POST /accounts", "code": 596 } ``` Or Muse refused to sign the account in again when its session needed renewing, most often because the password was changed. Add the account again with the current password. ```json { "error": "Account example@gmail.com: Muse refused to sign in account example@gmail.com (…). Update its password with POST /accounts, or sign in at https://muse.ai to clear the block, then re-add it", "code": 596 } ``` Or Muse disabled the account's computer and refuses to start it again. Sign in at [muse.ai](https://muse.ai) in a browser to see why, and ask Muse support to restore it with the form Muse shows there. Add the account again only after Muse has restored it. ```json { "error": "Account example@gmail.com: Muse has disabled the computer of account example@gmail.com (\"VM wake unavailable\"). Sign in at https://muse.ai in a browser to see why and contact Muse support there, then add the account again with POST /accounts", "code": 596 } ``` ##### Model The answer names the chat and the browser (`chatId`, `taskId`) with `stopped: true`. <details markdown="block" class="model-details"> <summary>The stopped browser, field by field</summary> ```typescript { // TypeScript, all fields are optional chatId: string taskId: string stopped: true error?: string // errors only code?: number // errors only } ``` </details> ##### Examples **Curl** ``` bash CHATID="c-u12345-email:example@gmail.com-chat:8e0bf21e-a3b5-4a1e-a05a-65d160469bfb-bot:muse" TASKID="423bc12e-db16-4921-8670-08b5f3f5a5d6" curl -X POST -H "Authorization: Bearer …" \ "https://api.useapi.net/v1/muse/chats/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$CHATID")/browser/$TASKID/stop" ``` **JavaScript** ``` javascript const token = "API token"; const chatId = "chatId from POST /chats"; const taskId = "taskId from the stream's browser event"; const apiUrl = `https://api.useapi.net/v1/muse/chats/${encodeURIComponent(chatId)}/browser/${encodeURIComponent(taskId)}/stop`; const response = await fetch(apiUrl, { method: "POST", headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", response.status, result); ``` **Python** ``` python import requests from urllib.parse import quote token = "API token" chatId = "chatId from POST /chats" taskId = "taskId from the stream's browser event" apiUrl = f"https://api.useapi.net/v1/muse/chats/{quote(chatId, safe='')}/browser/{quote(taskId, safe='')}/stop" headers = { "Authorization" : f"Bearer {token}" } response = requests.post(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-muse-v1/post-muse-chats-chatId-browser-taskId-viewer === Document URL: https://useapi.net/docs/api-muse-v1/post-muse-chats-chatId-browser-taskId-viewer --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> chats/`chatId`/browser/`taskId`/viewer description: "Create a single-use live view link of the agent's browser via POST chats/chatId/browser/taskId/viewer in the useapi.net Muse API: watch it, or take control with mouse and keyboard." parent: Muse API nav_order: 473 permalink: /docs/api-muse-v1/post-muse-chats-chatId-browser-taskId-viewer --- ## Open a live view of the browser October 14, 2026 (November 16, 2026) --- Create a link to a live view of the agent's browser. Open it in any web browser, or give it to your user: the page shows the agent's browser as it works. With `mode` `control`, the page can also take control of the browser, so you can click and type in it yourself, for example to sign in to a site, then give it back to the agent. The [Live Browser Guide](/docs/api-muse-v1/live-browser-guide) walks through the whole flow. - The link works once, and it must be opened within `ttl` seconds. The secret part of the link is after `#`, so it is never sent to a server when the page loads. - One viewer at a time per Muse account, because the account has one browser display. Close the open viewer, or [revoke it](/docs/api-muse-v1/delete-muse-chats-chatId-browser-taskId-viewer), before you open another. - A viewer session lasts up to 30 minutes. Then create a new link to go on watching. - The browser must be open: `previewAvailable` is `true` in its `browser` event or in [GET /chats/`chatId`/browser/`taskId`](/docs/api-muse-v1/get-muse-chats-chatId-browser-taskId). The viewer page has these controls: - Take control and Release control, with a `control` link. While you have control, your clicks and keys go to the browser. Control stays with you while the viewer is open, and goes back to the agent when you release it or close the viewer. - Picture quality: Low, Balanced, High or Max. A change applies at once. - Close viewer, which ends the session. The browser's display follows the size of the viewer window. When the connection drops, the page reconnects by itself. Copying and pasting inside the browser works. Copy and paste between your computer and the browser is not supported. If Muse can no longer show a browser, the viewer says so and the browser is stopped, which frees it for the account. Ask the agent to open the page again. > **https://api.useapi.net/v1/muse/chats/`chatId`/browser/`taskId`/viewer** - `chatId` is URL-encoded in the path (it contains `:` and `@`). - `taskId` is the `taskId` of the chat's `browser` event. ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "mode": "control", "ttl": 120 } ``` - `mode` is optional, what the link allows. Supported values: `view` (watch only), `control` (watch and take control). Default: `view`. - `ttl` is optional, how many seconds the link can be opened in. It is not the length of the session. Range: `15` to `300`. Default: `60`. - `quality` is optional, the picture quality the viewer starts with, from `0` (smallest) to `9` (sharpest). The viewer can change it. Range: `0` to `9`. Default: `6`. - `compression` is optional, how hard the picture is compressed, from `0` to `9`. Higher uses less bandwidth and more time. Range: `0` to `9`. Default: `1`. - `width` and `height` are optional, the display size for a client that does not send its own. The hosted viewer page always sends the size of its window. Range: `width` `320` to `1920`, `height` `240` to `1080`. Default: `1280` × `720`. ##### Responses **200** **200 OK** — open `url` before `expiresAt`. ```json { "chatId": "c-u12345-email:example@gmail.com-chat:8e0bf21e-a3b5-4a1e-a05a-65d160469bfb-bot:muse", "taskId": "423bc12e-db16-4921-8670-08b5f3f5a5d6", "url": "https://api.useapi.net/v1/muse/viewer#t=Qm9w4kTz0gXc1yR8vN2sLpE7aHfJ3uWdK6iYbM5oZtA", "expiresAt": "2026-10-14T23:09:10.512Z", "mode": "control", "viewerId": "5f1c0a9e7b24", "quality": 6, "compression": 1 } ``` **400** **400 Bad Request** — a parameter is invalid, or the path holds no valid `chatId` or `taskId`. ```json { "error": "mode must be view or control, not edit", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** — the `chatId` was issued to a different API token. ```json { "error": "This chat id does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** — the chat or the browser was not found, or the account that holds the chat is not added. ```json { "error": "Browser task not found in this chat", "code": 404 } ``` **409** **409 Conflict** — the browser is closed. ```json { "error": "This browser is already closed", "code": 409 } ``` **503** **503 Service Unavailable** — Muse could not be reached. Retry shortly. ```json { "error": "Could not connect to the Muse workspace of account example@gmail.com (…), please retry shortly", "code": 503 } ``` **596** **596 Account Error** The account needs your attention, and it is paused until you add it again. You receive an email when this happens. There are three causes. Meta asks for a security check on the account. Sign in once at [muse.ai](https://muse.ai) in a browser, complete the check, then add the account again with [POST /accounts](/docs/api-muse-v1/post-muse-accounts) using the same email and password. The API keeps using its session, so no new sign-in is needed. ```json { "error": "Account example@gmail.com: Meta asks for a security check on account example@gmail.com (\"This account must complete a security checkpoint on the web\"). Sign in once at https://muse.ai in a browser, complete the check, then add the account again with POST /accounts", "code": 596 } ``` Or Muse refused to sign the account in again when its session needed renewing, most often because the password was changed. Add the account again with the current password. ```json { "error": "Account example@gmail.com: Muse refused to sign in account example@gmail.com (…). Update its password with POST /accounts, or sign in at https://muse.ai to clear the block, then re-add it", "code": 596 } ``` Or Muse disabled the account's computer and refuses to start it again. Sign in at [muse.ai](https://muse.ai) in a browser to see why, and ask Muse support to restore it with the form Muse shows there. Add the account again only after Muse has restored it. ```json { "error": "Account example@gmail.com: Muse has disabled the computer of account example@gmail.com (\"VM wake unavailable\"). Sign in at https://muse.ai in a browser to see why and contact Muse support there, then add the account again with POST /accounts", "code": 596 } ``` When the link is opened, the viewer page shows why it cannot start, for example: - The link was already opened, has expired or was revoked. Create a new one. - The browser already has a viewer open, or the account has a viewer open on its other browser. Close that viewer or revoke it. A viewer that was closed abruptly frees its place within about 90 seconds. ##### Model A viewer `url` that works once and must be opened before `expiresAt`, with its `mode` and starting picture settings. <details markdown="block" class="model-details"> <summary>The viewer link, field by field</summary> ```typescript { // TypeScript, all fields are optional chatId: string taskId: string url: string // the viewer page, works once expiresAt: string // ISO 8601: open the link before this time mode: 'view' | 'control' viewerId: string // the viewer's id quality: number // the starting picture quality, 0 to 9 compression: number // the starting compression, 0 to 9 error?: string // errors only code?: number // errors only } ``` </details> ##### Advanced: your own viewer client The hosted page is the easy way. This section has what you need to embed it, or to build your own client. ###### The hosted page - `GET https://api.useapi.net/v1/muse/viewer` returns the viewer page. It needs no API token: the ticket is the part of `url` after `#t=`, in the URL fragment, which browsers never send to a server. - The page loads its [noVNC](https://github.com/novnc/noVNC) 1.4 client from the same origin, `https://api.useapi.net/v1/muse/viewer/novnc.js`, and uses no third-party CDN. - It opens a WebSocket to the same address, with its screen size as `?w=&h=` so the browser is shown pixel for pixel. - Open `url` in a new tab or window, or show it in an `<iframe>` in your own app. The page sends no header that forbids framing. - The quality selector maps to `quality` and `compression`: Low `2`/`9`, Balanced `6`/`1`, High `8`/`1`, Max `9`/`1`. A change applies to the next frames, without reconnecting. ###### The link - The ticket works once: opening the WebSocket uses it up. A second open of the same link is refused. - It must be opened within `ttl` seconds. - [DELETE …/viewer](/docs/api-muse-v1/delete-muse-chats-chatId-browser-taskId-viewer) revokes it, and ends sessions already open. - One viewer per browser, and one per account, because the account has one display. ###### Connecting ``` wss://api.useapi.net/v1/muse/viewer?w=1280&h=720 Sec-WebSocket-Protocol: useapi-viewer, t.<ticket> ``` - In a browser: `new WebSocket('wss://api.useapi.net/v1/muse/viewer?w=1280&h=720', ['useapi-viewer', 't.' + ticket])`. The server answers with the subprotocol `useapi-viewer`. - `w` and `h` are optional, your screen area in pixels. Without them, the link's `width` and `height` are used. Sizes are kept within `320` to `1920` by `240` to `1080`. - Binary frames carry RFB 3.8 (the VNC protocol) both ways, without a password: the browser's screen from the server, your mouse and keyboard from you. Set `binaryType = 'arraybuffer'`. Any RFB client library can read them. - Text frames are JSON objects with an `op` field: the control channel. ###### Text frames you send | `op` | Fields | What it does | |---|---|---| | `takeover` | | Take control. A `control` link only: a `view` link answers with an `error`. | | `release` | | Give control back to the agent. | | `resize` | `w`, `h` | Your screen area changed. The browser's display follows it, and the screen stream then restarts with a `reconnect`. | | `ack` | `bytes` | The total binary bytes you received so far. The hosted page sends it every 256 KB. A client that sends acks and falls more than 16 MB behind is disconnected. A client that never sends one is not measured. | | `ping` | | Keeps a quiet connection open. Send one about every 25 seconds. | | `close` | | End the session. Control goes back to the agent. | ###### Text frames you receive | `op` | Fields | Meaning | |---|---|---| | `attached` | `mode`, `width`, `height`, `quality`, `compression`, `controlOwner`, `controlExpiresAt` | The session started. `controlOwner` is `user` when you have control, else `agent`. | | `state` | `controlOwner`, `controlExpiresAt` | Control changed hands. | | `error` | `message` | Something went wrong, or a request was refused. A close often follows. | | `revoked` | | The link was revoked. The session ends. | | `reconnect` | `ticket` | The screen stream restarts, for example after a resize. Close this socket and connect again at once with this `ticket`. | | `resume` | `ticket` | Keep it. If the connection drops unexpectedly, connect again with this `ticket` to go on in the same session. It works once. | | `ping` | | Sent about every 25 seconds. Ignore it. | ###### Session rules - A `view` link never sends input: the server drops your mouse and keyboard events. With a `control` link, input reaches the browser only while you have control. - Control is kept alive while the session is open, and handed back to the agent when the session ends. - A session lasts up to 30 minutes, counted from the first connection, across every resume. - After an unexpected drop, reconnect with the `resume` ticket within about 5 seconds to keep control. Later, the ticket still continues the session, but control is back with the agent. The hosted page reconnects by itself after about a second. - Do not resume after a close you or the server made on purpose (`1000`), or after a refusal (`4000` and up). ###### Close codes | Code | Meaning | |---|---| | `1000` | A normal end: you closed the session, the link was revoked, the 30-minute limit, the browser closed, or a `reconnect`. | | `1003` | The server could not read what the client sent. | | `1011` | An error or a drop, for example the connection to Muse. Resume with the `resume` ticket. | | `4000` + HTTP status | The link could not open a session: `4410` already used, expired or revoked, `4409` this browser already has a viewer, `4429` the account has a viewer open on another browser, `4404` the account is not added. | A refusal, and most ends with an error, come after an `{"op": "error"}` frame with the reason. A missing or malformed ticket is refused with HTTP `401` before the connection opens. ##### Examples **Curl** ``` bash CHATID="c-u12345-email:example@gmail.com-chat:8e0bf21e-a3b5-4a1e-a05a-65d160469bfb-bot:muse" TASKID="423bc12e-db16-4921-8670-08b5f3f5a5d6" curl -X POST "https://api.useapi.net/v1/muse/chats/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$CHATID")/browser/$TASKID/viewer" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{"mode": "control"}' ``` **JavaScript** ``` javascript const token = "API token"; const chatId = "chatId from POST /chats"; const taskId = "taskId from the stream's browser event"; const apiUrl = `https://api.useapi.net/v1/muse/chats/${encodeURIComponent(chatId)}/browser/${encodeURIComponent(taskId)}/viewer`; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ mode: "control" }) }); const result = await response.json(); console.log("response", response.status, result); if (response.ok) window.open(result.url, "_blank"); ``` **Python** ``` python import requests from urllib.parse import quote token = "API token" chatId = "chatId from POST /chats" taskId = "taskId from the stream's browser event" apiUrl = f"https://api.useapi.net/v1/muse/chats/{quote(chatId, safe='')}/browser/{quote(taskId, safe='')}/viewer" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.post(apiUrl, headers=headers, json={"mode": "control"}) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-muse-v1/post-muse-chats-chatId-cancel === Document URL: https://useapi.net/docs/api-muse-v1/post-muse-chats-chatId-cancel --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> chats/`chatId`/cancel description: "Stop the Muse agent mid-answer via POST chats/chatId/cancel in the useapi.net Muse API. The answer ends as interrupted, and the chat stays." parent: Muse API nav_order: 430 permalink: /docs/api-muse-v1/post-muse-chats-chatId-cancel --- ## Cancel an answer October 12, 2026 (November 16, 2026) --- Stop the answer Muse is working on in a chat, like the stop button in the muse.ai app. The stream shows `turn.done` with `status: "interrupted"`. The chat stays: send the next message with [POST /chats/`chatId`/messages](/docs/api-muse-v1/post-muse-chats-chatId-messages). > **https://api.useapi.net/v1/muse/chats/`chatId`/cancel** - `chatId` is URL-encoded in the path (it contains `:` and `@`). ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** — `cancelled` is `true` when Muse confirmed the stop. ```json { "chatId": "c-u12345-email:example@gmail.com-chat:272b73f4-6fcb-42c2-9ec7-75cc0c020940-bot:muse", "cancelled": true } ``` `cancelled` is `false` when no answer was running. **400** **400 Bad Request** — the path value is not a Muse `chatId`. ```json { "error": "Path parameter chatId (not-a-chat-id) is not a valid Muse chat id", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** — the `chatId` was issued to a different API token. ```json { "error": "This chat id does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** — Muse has no such chat, or the account that holds the chat is not added. ```json { "error": "Chat not found", "code": 404 } ``` ```json { "error": "Account example@gmail.com (from the chat id) is not configured", "code": 404 } ``` **503** **503 Service Unavailable** — Muse could not be reached. Retry shortly. ```json { "error": "Could not connect to the Muse workspace of account example@gmail.com (…), please retry shortly", "code": 503 } ``` **596** **596 Account Error** The account needs your attention, and it is paused until you add it again. You receive an email when this happens. There are three causes. Meta asks for a security check on the account. Sign in once at [muse.ai](https://muse.ai) in a browser, complete the check, then add the account again with [POST /accounts](/docs/api-muse-v1/post-muse-accounts) using the same email and password. The API keeps using its session, so no new sign-in is needed. ```json { "error": "Account example@gmail.com: Meta asks for a security check on account example@gmail.com (\"This account must complete a security checkpoint on the web\"). Sign in once at https://muse.ai in a browser, complete the check, then add the account again with POST /accounts", "code": 596 } ``` Or Muse refused to sign the account in again when its session needed renewing, most often because the password was changed. Add the account again with the current password. ```json { "error": "Account example@gmail.com: Muse refused to sign in account example@gmail.com (…). Update its password with POST /accounts, or sign in at https://muse.ai to clear the block, then re-add it", "code": 596 } ``` Or Muse disabled the account's computer and refuses to start it again. Sign in at [muse.ai](https://muse.ai) in a browser to see why, and ask Muse support to restore it with the form Muse shows there. Add the account again only after Muse has restored it. ```json { "error": "Account example@gmail.com: Muse has disabled the computer of account example@gmail.com (\"VM wake unavailable\"). Sign in at https://muse.ai in a browser to see why and contact Muse support there, then add the account again with POST /accounts", "code": 596 } ``` ##### Model The answer's `cancelled` is `true` when Muse stopped a running answer, and `false` when none was running. <details markdown="block" class="model-details"> <summary>The cancel result, field by field</summary> ```typescript { // TypeScript, all fields are optional chatId: string cancelled: boolean // true when Muse confirmed the stop, false when no answer was running error?: string // errors only code?: number // errors only } ``` </details> ##### Examples **Curl** ``` bash CHATID="c-u12345-email:example@gmail.com-chat:272b73f4-6fcb-42c2-9ec7-75cc0c020940-bot:muse" curl -X POST -H "Authorization: Bearer …" \ "https://api.useapi.net/v1/muse/chats/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$CHATID")/cancel" ``` **JavaScript** ``` javascript const token = "API token"; const chatId = "chatId from POST /chats"; const apiUrl = `https://api.useapi.net/v1/muse/chats/${encodeURIComponent(chatId)}/cancel`; const response = await fetch(apiUrl, { method: "POST", headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", response.status, result); ``` **Python** ``` python import requests from urllib.parse import quote token = "API token" chatId = "chatId from POST /chats" apiUrl = f"https://api.useapi.net/v1/muse/chats/{quote(chatId, safe='')}/cancel" headers = { "Authorization" : f"Bearer {token}" } response = requests.post(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-muse-v1/post-muse-chats-chatId-messages-messageId-reactions === Document URL: https://useapi.net/docs/api-muse-v1/post-muse-chats-chatId-messages-messageId-reactions --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> chats/`chatId`/messages/`messageId`/reactions description: "React to a Muse chat message with an emoji via POST chats/chatId/messages/messageId/reactions in the useapi.net Muse API. Sending the same emoji again removes it." parent: Muse API nav_order: 425 permalink: /docs/api-muse-v1/post-muse-chats-chatId-messages-messageId-reactions --- ## React to a message October 14, 2026 (November 16, 2026) --- Add an emoji reaction to a message in a chat, yours or the agent's, as in the muse.ai app. Sending the same emoji again removes it. The response lists the message's reactions after the change. The agent reacts too, for example with 👍 to a message of yours. Reactions arrive on the [stream](/docs/api-muse-v1/get-muse-chats-chatId-stream) as `reaction` events with the message's whole set of reactions, and [GET /chats/`chatId`](/docs/api-muse-v1/get-muse-chats-chatId) lists them in each message's `reactions`. > **https://api.useapi.net/v1/muse/chats/`chatId`/messages/`messageId`/reactions** - `chatId` is URL-encoded in the path (it contains `:` and `@`). - `messageId` is the `messageId` of a message in the chat, from the stream or [GET /chats/`chatId`](/docs/api-muse-v1/get-muse-chats-chatId). ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "emoji": "👍" } ``` - `emoji` is **required**, one emoji, for example 👍, ❤️, 😂, 😮, 😢, 🙏 or 🫶. Sending an emoji the message already has from you removes it. Maximum length: 32 characters. ##### Responses **200** **200 OK** — the message's reactions after the change. ```json { "chatId": "c-u12345-email:example@gmail.com-chat:8e0bf21e-a3b5-4a1e-a05a-65d160469bfb-bot:muse", "messageId": "assistant-msg-bfc09d8d-5071-6d9b-dac3-dd35bdeaa602", "reactions": ["👍"] } ``` **400** **400 Bad Request** — `emoji` is missing, a path value is invalid, or Muse did not accept the emoji. ```json { "error": "Muse did not take the reaction (HTTP 400)", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** — the `chatId` was issued to a different API token. ```json { "error": "This chat id does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** — Muse has no such message, or the account that holds the chat is not added. ```json { "error": "Muse did not take the reaction (HTTP 404)", "code": 404 } ``` **502** **502 Bad Gateway** — Muse did not take the reaction. Retry shortly. ```json { "error": "Muse did not take the reaction (HTTP 500)", "code": 502 } ``` **503** **503 Service Unavailable** — Muse could not be reached. Retry shortly. ```json { "error": "Could not connect to the Muse workspace of account example@gmail.com (…), please retry shortly", "code": 503 } ``` **596** **596 Account Error** The account needs your attention, and it is paused until you add it again. You receive an email when this happens. There are three causes. Meta asks for a security check on the account. Sign in once at [muse.ai](https://muse.ai) in a browser, complete the check, then add the account again with [POST /accounts](/docs/api-muse-v1/post-muse-accounts) using the same email and password. The API keeps using its session, so no new sign-in is needed. ```json { "error": "Account example@gmail.com: Meta asks for a security check on account example@gmail.com (\"This account must complete a security checkpoint on the web\"). Sign in once at https://muse.ai in a browser, complete the check, then add the account again with POST /accounts", "code": 596 } ``` Or Muse refused to sign the account in again when its session needed renewing, most often because the password was changed. Add the account again with the current password. ```json { "error": "Account example@gmail.com: Muse refused to sign in account example@gmail.com (…). Update its password with POST /accounts, or sign in at https://muse.ai to clear the block, then re-add it", "code": 596 } ``` Or Muse disabled the account's computer and refuses to start it again. Sign in at [muse.ai](https://muse.ai) in a browser to see why, and ask Muse support to restore it with the form Muse shows there. Add the account again only after Muse has restored it. ```json { "error": "Account example@gmail.com: Muse has disabled the computer of account example@gmail.com (\"VM wake unavailable\"). Sign in at https://muse.ai in a browser to see why and contact Muse support there, then add the account again with POST /accounts", "code": 596 } ``` ##### Model The message's whole set of reactions after your change, in `reactions`. <details markdown="block" class="model-details"> <summary>The message's reactions, field by field</summary> ```typescript { // TypeScript, all fields are optional chatId: string messageId: string reactions: string[] // the message's reactions after the change, e.g. ["👍"] error?: string // errors only code?: number // errors only } ``` </details> ##### Examples **Curl** ``` bash CHATID="c-u12345-email:example@gmail.com-chat:8e0bf21e-a3b5-4a1e-a05a-65d160469bfb-bot:muse" MESSAGEID="assistant-msg-bfc09d8d-5071-6d9b-dac3-dd35bdeaa602" curl -X POST "https://api.useapi.net/v1/muse/chats/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$CHATID")/messages/$MESSAGEID/reactions" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{"emoji": "👍"}' ``` **JavaScript** ``` javascript const token = "API token"; const chatId = "chatId from POST /chats"; const messageId = "messageId from the stream or GET /chats/{chatId}"; const apiUrl = `https://api.useapi.net/v1/muse/chats/${encodeURIComponent(chatId)}/messages/${encodeURIComponent(messageId)}/reactions`; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ emoji: "👍" }) }); console.log("response", response.status, await response.json()); ``` **Python** ``` python import requests from urllib.parse import quote token = "API token" chatId = "chatId from POST /chats" messageId = "messageId from the stream or GET /chats/{chatId}" apiUrl = f"https://api.useapi.net/v1/muse/chats/{quote(chatId, safe='')}/messages/{quote(messageId, safe='')}/reactions" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.post(apiUrl, headers=headers, json={"emoji": "👍"}) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-muse-v1/post-muse-chats-chatId-messages === Document URL: https://useapi.net/docs/api-muse-v1/post-muse-chats-chatId-messages --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> chats/`chatId`/messages description: "Send the next message in a Muse chat via POST chats/chatId/messages in the useapi.net Muse API, at any time, even while the agent is still answering." parent: Muse API nav_order: 420 permalink: /docs/api-muse-v1/post-muse-chats-chatId-messages --- ## Send a message October 12, 2026 (November 16, 2026) --- Send a message into a chat started with [POST /chats](/docs/api-muse-v1/post-muse-chats), or into any chat from [GET /chats](/docs/api-muse-v1/get-muse-chats). No stream needs to be open. Watch the reply live with [GET /chats/`chatId`/stream](/docs/api-muse-v1/get-muse-chats-chatId-stream), or read it afterwards with [GET /chats/`chatId`](/docs/api-muse-v1/get-muse-chats-chatId). You can send at any time, also while Muse is still answering. Muse then takes the new message into the answer it is working on, the way it does in the muse.ai app. A message to a chat that is not answering starts a new answer. Chat does not use the account's `maxJobs`. > **https://api.useapi.net/v1/muse/chats/`chatId`/messages** - `chatId` is URL-encoded in the path (it contains `:` and `@`). ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "message": "Also add one sentence about the moon.", "files": [] } ``` - `message` is **required**, what you say to Muse. Maximum length: `5000` characters. - `files` is optional, an array of asset ids (up to 9 images, 3 videos and 3 audio files) and workspace paths or document asset ids of other files (up to 10, for example `workspace/your_files/report.pdf`), named `image_1`, `video_1`, `audio_1`, `file_1`… in the order you list them. They must be on the chat's account. See [POST /chats](/docs/api-muse-v1/post-muse-chats#request-body). ##### Responses **202** **202 Accepted** — the message was sent. It shows on the stream as a `message` event with this `messageId`. ```json { "chatId": "c-u12345-email:example@gmail.com-chat:272b73f4-6fcb-42c2-9ec7-75cc0c020940-bot:muse", "email": "example@gmail.com", "messageId": "962c0d79-61d7-4aaa-8f4a-8b3194146c79" } ``` **400** **400 Bad Request** — a parameter is missing or invalid, the path value is not a Muse `chatId`, or a file is on another account. ```json { "error": "Path parameter chatId (not-a-chat-id) is not a valid Muse chat id", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** — the `chatId` or a file's asset id was issued to a different API token. ```json { "error": "This chat id does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** — the account that holds the chat is not added. ```json { "error": "Account example@gmail.com (from the chat id) is not configured", "code": 404 } ``` **412** **412 Precondition Failed** — the account's weekly Muse allowance is used up. **429** **429 Too Many Requests** — Muse is limiting requests on the account. Retry in about a minute. ```json { "error": "Muse is limiting requests on account example@gmail.com right now. Retry in about a minute", "code": 429 } ``` **502** **502 Bad Gateway** — Muse did not accept the message. Retry. **503** **503 Service Unavailable** — Muse could not be reached, and nothing was sent. Retry shortly. ```json { "error": "Could not read the chat on Muse, nothing was sent. Please retry", "code": 503 } ``` **504** **504 Gateway Timeout** — the connection to Muse dropped while the message was being sent. It may have arrived: check [GET /chats/`chatId`](/docs/api-muse-v1/get-muse-chats-chatId) before you send it again. ```json { "error": "The connection to Muse dropped while sending (…). The message may have arrived: check GET /chats/{chatId} before sending it again", "code": 504 } ``` **596** **596 Account Error** The account needs your attention, and it is paused until you add it again. You receive an email when this happens. There are three causes. Meta asks for a security check on the account. Sign in once at [muse.ai](https://muse.ai) in a browser, complete the check, then add the account again with [POST /accounts](/docs/api-muse-v1/post-muse-accounts) using the same email and password. The API keeps using its session, so no new sign-in is needed. ```json { "error": "Account example@gmail.com: Meta asks for a security check on account example@gmail.com (\"This account must complete a security checkpoint on the web\"). Sign in once at https://muse.ai in a browser, complete the check, then add the account again with POST /accounts", "code": 596 } ``` Or Muse refused to sign the account in again when its session needed renewing, most often because the password was changed. Add the account again with the current password. ```json { "error": "Account example@gmail.com: Muse refused to sign in account example@gmail.com (…). Update its password with POST /accounts, or sign in at https://muse.ai to clear the block, then re-add it", "code": 596 } ``` Or Muse disabled the account's computer and refuses to start it again. Sign in at [muse.ai](https://muse.ai) in a browser to see why, and ask Muse support to restore it with the form Muse shows there. Add the account again only after Muse has restored it. ```json { "error": "Account example@gmail.com: Muse has disabled the computer of account example@gmail.com (\"VM wake unavailable\"). Sign in at https://muse.ai in a browser to see why and contact Muse support there, then add the account again with POST /accounts", "code": 596 } ``` ##### Model The chat and account the message went to, and Muse's `messageId` for your message. <details markdown="block" class="model-details"> <summary>The sent message, field by field</summary> ```typescript { // TypeScript, all fields are optional chatId: string email: string // the account the chat runs on messageId: string | null // Muse's id of your message, as the stream's `message` event shows it error?: string // errors only code?: number // errors only } ``` </details> ##### Examples **Curl** ``` bash CHATID="c-u12345-email:example@gmail.com-chat:272b73f4-6fcb-42c2-9ec7-75cc0c020940-bot:muse" curl -X POST "https://api.useapi.net/v1/muse/chats/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$CHATID")/messages" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{"message": "Also add one sentence about the moon."}' ``` **JavaScript** ``` javascript const token = "API token"; const chatId = "chatId from POST /chats"; const apiUrl = `https://api.useapi.net/v1/muse/chats/${encodeURIComponent(chatId)}/messages`; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ message: "Also add one sentence about the moon." }) }); const result = await response.json(); console.log("response", response.status, result); ``` **Python** ``` python import requests from urllib.parse import quote token = "API token" chatId = "chatId from POST /chats" apiUrl = f"https://api.useapi.net/v1/muse/chats/{quote(chatId, safe='')}/messages" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.post(apiUrl, headers=headers, json={"message": "Also add one sentence about the moon."}) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-muse-v1/post-muse-chats-chatId-widgets-widgetId === Document URL: https://useapi.net/docs/api-muse-v1/post-muse-chats-chatId-widgets-widgetId --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> chats/`chatId`/widgets/`widgetId` description: "Answer a quick-reply card from the Muse agent via POST chats/chatId/widgets/widgetId in the useapi.net Muse API: pick an option by index or reply with text." parent: Muse API nav_order: 436 permalink: /docs/api-muse-v1/post-muse-chats-chatId-widgets-widgetId --- ## Answer a widget October 12, 2026 (November 20, 2026) --- The Muse agent sometimes puts an interactive card, a widget, into its message, for example a few quick-reply choices or a chart. The stream sends each one as a `widget` event, see [GET /chats/`chatId`/stream](/docs/api-muse-v1/get-muse-chats-chatId-stream), and [GET /chats/`chatId`](/docs/api-muse-v1/get-muse-chats-chatId) lists them in `messages[].widgets`. | `kind` | Fields | How to show it | |---|---|---| | `option` | `options` | Quick-reply choices. Show one button per option, and answer with [POST /chats/`chatId`/widgets/`widgetId`](/docs/api-muse-v1/post-muse-chats-chatId-widgets-widgetId). | | `html` | `html` | A card the agent wrote, such as a chart or a table. It may contain scripts. Show it only inside a sandboxed iframe, `sandbox="allow-scripts"`, never with `allow-same-origin`. Show `fallbackText` when you don't render it. | | `space_build_completed` | `name`, `summary`, `status`, `assetId` | A web app the agent built. `fallbackText` is its name. Download it as one HTML file with [GET /assets/`assetId`](/docs/api-muse-v1/get-muse-assets-assetId), or publish it on a public link with [POST /assets/`assetId`/share](/docs/api-muse-v1/post-muse-assets-assetId-share). `assetId` is `null` when the app has no id the API can name. | | `internal_link_action_card` | `title`, `subtitle`, `linkType`, `url`, `connectorId`, `imageUrl` | A link to something only Muse's own site can do, for example connecting Google Calendar (`title` `Google Calendar`, `subtitle` `Connector`, `linkType` `connector`, `connectorId` `google_calendar`). Show it as a button: the account's owner opens `url` signed in to Muse as that account, then continues the chat. The API cannot do this step. | | any other | `data` | Muse's widget data as it is. Other kinds may appear: show `fallbackText` when you can't render one. | An `html` card uses these CSS variables for its colors, so define them in the iframe's page to match your design: `--hatch-widget-text`, `--hatch-widget-muted`, `--hatch-widget-accent`, `--hatch-widget-surface`, `--hatch-widget-surface-muted`, `--hatch-widget-border`. For example, pass the card as `srcdoc`: ```html <iframe sandbox="allow-scripts" srcdoc="<style>:root { --hatch-widget-text: #1f2328; --hatch-widget-muted: #656d76; --hatch-widget-accent: #0969da; --hatch-widget-surface: #ffffff; --hatch-widget-surface-muted: #f6f8fa; --hatch-widget-border: #d0d7de }</style> …the widget's html…"></iframe> ``` A widget can also arrive on its own, for example an `html` card the agent presents by itself: its `messageId` carries no text (in GET /chats/`chatId`, an agent message with empty `text` and that widget), and its `widgetId` is not of the `widget-…` form. Only `option` widgets inside a message can be answered through the API. Answering sends the chosen option's text as your next message, the same as tapping it in the muse.ai app. The reply streams as usual, like for any message, see [POST /chats/`chatId`/messages](/docs/api-muse-v1/post-muse-chats-chatId-messages). An `option` widget event looks like this: ```json { "event": "widget", "messageId": "assistant-msg-2ed3bb21-13fe-4759-a8a6-2a8361247e61", "widgetId": "widget-f8a4ee04-d3bb-4cc3-b9d5-108a39ba58c4", "kind": "option", "text": "Set up GitHub repo sync / I'll just attach files in chat", "fallbackText": "- Set up GitHub repo sync\n- I'll just attach files in chat", "options": [ "Set up GitHub repo sync", "I'll just attach files in chat" ] } ``` An `html` widget event looks like this (the `html` is shortened): ```json { "event": "widget", "messageId": "assistant-msg-b54a2c1e-7d3f-4e8a-9b6c-0f1e2d3c4b5a", "widgetId": "widget-c29f94b9-647b-45c0-8183-c3bf1c83f502", "kind": "html", "text": null, "fallbackText": "Bar chart of today's top news topics by coverage intensity", "html": "<div style=\"padding:16px;color:var(--hatch-widget-text)\">…</div>" } ``` > **https://api.useapi.net/v1/muse/chats/`chatId`/widgets/`widgetId`** - `chatId` is URL-encoded in the path (it contains `:` and `@`). - `widgetId` is the `widgetId` of the widget. ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "option": 1 } ``` Send exactly one of these: - `option` is the index of the chosen entry in the widget's `options`, starting at `0`. - `text` is your own reply instead of one of the options. Maximum length: `5000` characters. ##### Responses **202** **202 Accepted** — the answer was sent as your message. It shows on the stream as a `message` event with this `messageId`. ```json { "chatId": "c-u12345-email:example@gmail.com-chat:a1e7ec87-b9ba-41ba-8c99-c9da82cb63d1-bot:muse", "email": "example@gmail.com", "messageId": "f20f589c-1c71-46b4-8bb9-8b6a753d23e3" } ``` **400** **400 Bad Request** — neither or both of `option` and `text` were sent, `option` is not one of the widget's options, or the widget's kind cannot be answered. ```json { "error": "option must be 0 to 1", "code": 400 } ``` ```json { "error": "Pass either option (the index of one of the widget options) or text", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** — the `chatId` was issued to a different API token. ```json { "error": "This chat id does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** — the widget is not in this chat, or the account that holds the chat is not added. ```json { "error": "Widget not found in this chat", "code": 404 } ``` **429** **429 Too Many Requests** — Muse is limiting requests on the account. Retry in about a minute. **502** **502 Bad Gateway** — Muse did not accept the answer. Retry. ```json { "error": "Muse did not accept the message (HTTP 400). Please retry", "code": 502 } ``` **503** **503 Service Unavailable** — Muse could not be reached, and nothing was sent. Retry shortly. **504** **504 Gateway Timeout** — the connection to Muse dropped while the answer was being sent. It may have arrived: check [GET /chats/`chatId`](/docs/api-muse-v1/get-muse-chats-chatId) before you send it again. **596** **596 Account Error** The account needs your attention, and it is paused until you add it again. You receive an email when this happens. There are three causes. Meta asks for a security check on the account. Sign in once at [muse.ai](https://muse.ai) in a browser, complete the check, then add the account again with [POST /accounts](/docs/api-muse-v1/post-muse-accounts) using the same email and password. The API keeps using its session, so no new sign-in is needed. ```json { "error": "Account example@gmail.com: Meta asks for a security check on account example@gmail.com (\"This account must complete a security checkpoint on the web\"). Sign in once at https://muse.ai in a browser, complete the check, then add the account again with POST /accounts", "code": 596 } ``` Or Muse refused to sign the account in again when its session needed renewing, most often because the password was changed. Add the account again with the current password. ```json { "error": "Account example@gmail.com: Muse refused to sign in account example@gmail.com (…). Update its password with POST /accounts, or sign in at https://muse.ai to clear the block, then re-add it", "code": 596 } ``` Or Muse disabled the account's computer and refuses to start it again. Sign in at [muse.ai](https://muse.ai) in a browser to see why, and ask Muse support to restore it with the form Muse shows there. Add the account again only after Muse has restored it. ```json { "error": "Account example@gmail.com: Muse has disabled the computer of account example@gmail.com (\"VM wake unavailable\"). Sign in at https://muse.ai in a browser to see why and contact Muse support there, then add the account again with POST /accounts", "code": 596 } ``` ##### Model The chat and account your answer went to, and Muse's `messageId` for it. <details markdown="block" class="model-details"> <summary>The sent answer, field by field</summary> ```typescript { // TypeScript, all fields are optional chatId: string email: string // the account the chat runs on messageId: string | null // Muse's id of your answer, as the stream's `message` event shows it error?: string // errors only code?: number // errors only } ``` </details> ##### Examples **Curl** ``` bash CHATID="c-u12345-email:example@gmail.com-chat:a1e7ec87-b9ba-41ba-8c99-c9da82cb63d1-bot:muse" WIDGETID="widget-f8a4ee04-d3bb-4cc3-b9d5-108a39ba58c4" curl -X POST "https://api.useapi.net/v1/muse/chats/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$CHATID")/widgets/$WIDGETID" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{"option": 1}' ``` **JavaScript** ``` javascript const token = "API token"; const chatId = "chatId from POST /chats"; const widgetId = "widgetId from the widget event"; const apiUrl = `https://api.useapi.net/v1/muse/chats/${encodeURIComponent(chatId)}/widgets/${encodeURIComponent(widgetId)}`; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ option: 1 }) }); console.log("response", response.status, await response.json()); ``` **Python** ``` python import requests from urllib.parse import quote token = "API token" chatId = "chatId from POST /chats" widgetId = "widgetId from the widget event" apiUrl = f"https://api.useapi.net/v1/muse/chats/{quote(chatId, safe='')}/widgets/{quote(widgetId, safe='')}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.post(apiUrl, headers=headers, json={"option": 1}) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-muse-v1/post-muse-chats === Document URL: https://useapi.net/docs/api-muse-v1/post-muse-chats --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> chats description: "Start a two-way chat with the Muse agent via POST chats in the useapi.net Muse API: a message up to 5000 characters plus optional files, answered live over SSE." parent: Muse API nav_order: 400 permalink: /docs/api-muse-v1/post-muse-chats --- ## Start a chat October 12, 2026 (November 16, 2026) --- Start a chat with [Muse](https://muse.ai), Meta's AI agent, and get a `chatId` for it. The answer streams live from [GET /chats/`chatId`/stream](/docs/api-muse-v1/get-muse-chats-chatId-stream), and you can send more messages at any time with [POST /chats/`chatId`/messages](/docs/api-muse-v1/post-muse-chats-chatId-messages), even while Muse is still answering. The [Chat Streaming Guide](/docs/api-muse-v1/chat-streaming-guide) walks through the whole flow, and the [Live Demo](/docs/api-muse-v1/demo) runs it in your browser. A chat reaches the whole Muse agent, not only images and videos. It can talk, research the web, write and run code, and use the apps connected to the Muse account, the same as a chat in the muse.ai app. The chat is a normal Muse chat: it shows in the muse.ai app too. Files go in and come out as the same asset ids the [jobs](/docs/api-muse-v1/post-muse-jobs-image) use. Pass your files in `files`, as asset ids from [POST /assets](/docs/api-muse-v1/post-muse-assets) or from an earlier job or chat, as asset ids of documents in the account's Library, or as workspace paths of documents and data written with [POST /files](/docs/api-muse-v1/post-muse-files). Every file Muse makes arrives as a `file` event on the stream, and downloads with [GET /assets/`assetId`](/docs/api-muse-v1/get-muse-assets-assetId). Chat does not use the account's `maxJobs`, which limits jobs only. Chat uses the account's weekly [Muse allowance](/docs/start-here/setup-muse#usage-limits), like jobs do. > **https://api.useapi.net/v1/muse/chats** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "message": "Write a 300-word story about the sea, then make one image for it.", "files": [ "user:12345-email:6578616d706c6540676d61696c2e636f6d-image:3e788737ea18422b9809aeb06a453c072e15f1b3fb219d7a4fd7e8fffd733d4f.jpg" ], "email": "example@gmail.com" } ``` - `message` is **required**, what you say to Muse. Maximum length: `5000` characters. - `files` is optional, an array of: - asset ids from [POST /assets](/docs/api-muse-v1/post-muse-assets), [GET /assets](/docs/api-muse-v1/get-muse-assets), a job's `result.assets[]` or a chat's `file` event, up to 9 images, 3 videos and 3 audio files. - workspace paths of any other file, such as a PDF, a spreadsheet or code, from [POST /files](/docs/api-muse-v1/post-muse-files) or [GET /files](/docs/api-muse-v1/get-muse-files), for example `workspace/your_files/report.pdf`, or the asset ids of documents from [GET /assets](/docs/api-muse-v1/get-muse-assets) or a chat's `file` event. Up to 10 of these together. A document's asset id works like its workspace path. Muse sees them as `image_1`, `image_2`… `video_1`… `audio_1`… `file_1`, `file_2`… in the order you list them, so the message can name them, for example `put the person from image_1 into image_2` or `summarize file_1`. All files must be on the same Muse account, and the chat runs on that account. When you send only workspace paths or document asset ids and the API token has more than one Muse account, `email` is **required**, so the chat runs on the account that holds them. - `email` is optional, the account to chat on. When omitted, the account that holds the files is used, or without files a healthy account with allowance left. ##### Responses **201** **201 Created** — the message was sent and Muse is answering. Open [GET /chats/`chatId`/stream](/docs/api-muse-v1/get-muse-chats-chatId-stream) to read the answer. ```json { "chatId": "c-u12345-email:example@gmail.com-chat:272b73f4-6fcb-42c2-9ec7-75cc0c020940-bot:muse", "email": "example@gmail.com", "messageId": "389bfe1b-d8a0-47ed-9b11-d9269a8ed656" } ``` **400** **400 Bad Request** — a parameter is missing or invalid, the files are on different accounts, or no Muse account is added yet. ```json { "error": "Parameter message is required", "code": 400 } ``` ```json { "error": "Please configure at least one account at https://useapi.net/docs/api-muse-v1/post-muse-accounts", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** — a file's asset id belongs to another API token. ```json { "error": "This asset id does not belong to this API token", "code": 403 } ``` **404** **404 Not Found** — the account named by `email`, or the account a file lives on, is not added. ```json { "error": "Account example@gmail.com is not configured", "code": 404 } ``` **412** **412 Precondition Failed** — the account's weekly Muse allowance is used up (or every account's, without `email`). ```json { "error": "All 2 healthy accounts have used up their Muse allowance. GET /accounts/{email} re-reads it", "code": 412 } ``` **429** **429 Too Many Requests** — Muse is limiting requests on the account. Retry in about a minute. ```json { "error": "Muse is limiting requests on account example@gmail.com right now. Retry in about a minute", "code": 429 } ``` **502** **502 Bad Gateway** — Muse did not accept the message. Retry. ```json { "error": "Muse did not accept the message (HTTP 400). Please retry", "code": 502 } ``` **503** **503 Service Unavailable** — Muse could not be reached, and nothing was sent. Retry shortly. ```json { "error": "Muse did not accept the message (HTTP 500). Please retry", "code": 503 } ``` **504** **504 Gateway Timeout** — the connection to Muse dropped while the message was being sent. It may have arrived: look at [GET /chats](/docs/api-muse-v1/get-muse-chats) before you send it again. ```json { "error": "The connection to Muse dropped while sending (…). The message may have arrived: check GET /chats/{chatId} before sending it again", "code": 504 } ``` **596** **596 Account Error** The account needs your attention, and it is paused until you add it again. You receive an email when this happens. There are three causes. Meta asks for a security check on the account. Sign in once at [muse.ai](https://muse.ai) in a browser, complete the check, then add the account again with [POST /accounts](/docs/api-muse-v1/post-muse-accounts) using the same email and password. The API keeps using its session, so no new sign-in is needed. ```json { "error": "Account example@gmail.com: Meta asks for a security check on account example@gmail.com (\"This account must complete a security checkpoint on the web\"). Sign in once at https://muse.ai in a browser, complete the check, then add the account again with POST /accounts", "code": 596 } ``` Or Muse refused to sign the account in again when its session needed renewing, most often because the password was changed. Add the account again with the current password. ```json { "error": "Account example@gmail.com: Muse refused to sign in account example@gmail.com (…). Update its password with POST /accounts, or sign in at https://muse.ai to clear the block, then re-add it", "code": 596 } ``` Or Muse disabled the account's computer and refuses to start it again. Sign in at [muse.ai](https://muse.ai) in a browser to see why, and ask Muse support to restore it with the form Muse shows there. Add the account again only after Muse has restored it. ```json { "error": "Account example@gmail.com: Muse has disabled the computer of account example@gmail.com (\"VM wake unavailable\"). Sign in at https://muse.ai in a browser to see why and contact Muse support there, then add the account again with POST /accounts", "code": 596 } ``` ##### Model The new chat's `chatId`, the account it runs on, and Muse's `messageId` for your message. <details markdown="block" class="model-details"> <summary>The started chat, field by field</summary> ```typescript { // TypeScript, all fields are optional chatId: string // c-u<id>-email:<email>-chat:<Muse chat id>-bot:muse email: string // the account the chat runs on messageId: string | null // Muse's id of your message, as the stream's `message` event shows it error?: string // errors only code?: number // errors only } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/muse/chats" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "message": "Write a 300-word story about the sea, then make one image for it." }' ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = "https://api.useapi.net/v1/muse/chats"; const response = await fetch(apiUrl, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ message: "Write a 300-word story about the sea, then make one image for it." }) }); const result = await response.json(); console.log("response", response.status, result); /* next: read the answer from GET /chats/{chatId}/stream, see the Chat Streaming Guide */ ``` **Python** ``` python import requests token = "API token" apiUrl = "https://api.useapi.net/v1/muse/chats" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } data = {"message": "Write a 300-word story about the sea, then make one image for it."} response = requests.post(apiUrl, headers=headers, json=data) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-muse-v1/post-muse-files === Document URL: https://useapi.net/docs/api-muse-v1/post-muse-files --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> files description: "Write any file into a Muse account's workspace via POST files in the useapi.net Muse API: raw body up to 50 MB at the path you choose, ready for chat." parent: Muse API nav_order: 343 permalink: /docs/api-muse-v1/post-muse-files --- ## Write a workspace file October 12, 2026 (November 16, 2026) --- Write a file of any type into the Muse workspace of an account, at the path you choose: a PDF, a spreadsheet, code, text or media. A file already at that path is replaced. Send the file as the raw request body. To have the agent work on it, pass its path in `files` of [POST /chats](/docs/api-muse-v1/post-muse-chats) or [POST /chats/`chatId`/messages](/docs/api-muse-v1/post-muse-chats-chatId-messages), for example upload `workspace/your_files/report.pdf` and send `"files": ["workspace/your_files/report.pdf"]` with "Summarize file_1". Files and assets are two views of the same workspace. [Assets](/docs/api-muse-v1/get-muse-assets) are the images, videos and audio files, each with an `assetId` for jobs and chats. `/files` covers the whole workspace, including the code, documents and data the agent writes. A media file listed here also carries its `assetId`. For an image, video or audio file you want to use in jobs, [POST /assets](/docs/api-muse-v1/post-muse-assets) is the simpler choice. Paths always start with `workspace/`. Write into your own folders, for example `workspace/your_files/…`. Media for jobs and chats goes in with [POST /assets](/docs/api-muse-v1/post-muse-assets). > **https://api.useapi.net/v1/muse/files?email=`email`&path=`path`** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/pdf # the file's MIME type Content-Length: 52 # most HTTP clients set it for you ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. - `Content-Type` is optional, the file's MIME type. - `Content-Length` is **required**, the file size in bytes. The request body is the file's raw bytes, from 1 byte to `52,428,800` bytes (50 MB). ##### Query Parameters - `email` is optional when the API token has one Muse account, and **required** when it has more. URL-encode it. - `path` is **required**, where to write the file, for example `workspace/your_files/report.pdf`. A file already there is replaced. ##### Responses **200** **200 OK** — the written file. ```json { "email": "example@gmail.com", "name": "report.pdf", "path": "workspace/your_files/report.pdf", "type": "file", "bytes": 52, "modified": "2026-10-13T01:54:06.788Z", "assetId": null } ``` **400** **400 Bad Request** — `path` is a folder or not a path in the workspace, or the body is empty. ```json { "error": "Path is a folder: give the file path, e.g. workspace/your_files/notes.pdf", "code": 400 } ``` **401** **401 Unauthorized** — Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **404** **404 Not Found** — the account named by `email` is not added. ```json { "error": "Account example@gmail.com is not configured", "code": 404 } ``` **411** **411 Length Required** — the request has no `Content-Length` header, for example a streamed (chunked) body. ```json { "error": "Content-Length is required (send the file as the raw request body)", "code": 411 } ``` **413** **413 Content Too Large** — the file is larger than 52,428,800 bytes (50 MB). ```json { "error": "File must be at most 52428800 bytes", "code": 413 } ``` **409** **409 Conflict** — another request is writing the same file right now. Retry shortly. ```json { "error": "This file is being written by another request, please retry shortly", "code": 409 } ``` **503** **503 Service Unavailable** — Muse could not be reached. Retry shortly. ```json { "error": "Muse could not do it right now (…), please retry", "code": 503 } ``` **596** **596 Account Error** The account needs your attention, and it is paused until you add it again. You receive an email when this happens. There are three causes. Meta asks for a security check on the account. Sign in once at [muse.ai](https://muse.ai) in a browser, complete the check, then add the account again with [POST /accounts](/docs/api-muse-v1/post-muse-accounts) using the same email and password. The API keeps using its session, so no new sign-in is needed. ```json { "error": "Account example@gmail.com: Meta asks for a security check on account example@gmail.com (\"This account must complete a security checkpoint on the web\"). Sign in once at https://muse.ai in a browser, complete the check, then add the account again with POST /accounts", "code": 596 } ``` Or Muse refused to sign the account in again when its session needed renewing, most often because the password was changed. Add the account again with the current password. ```json { "error": "Account example@gmail.com: Muse refused to sign in account example@gmail.com (…). Update its password with POST /accounts, or sign in at https://muse.ai to clear the block, then re-add it", "code": 596 } ``` Or Muse disabled the account's computer and refuses to start it again. Sign in at [muse.ai](https://muse.ai) in a browser to see why, and ask Muse support to restore it with the form Muse shows there. Add the account again only after Muse has restored it. ```json { "error": "Account example@gmail.com: Muse has disabled the computer of account example@gmail.com (\"VM wake unavailable\"). Sign in at https://muse.ai in a browser to see why and contact Muse support there, then add the account again with POST /accounts", "code": 596 } ``` ##### Model The written file's entry: its `path`, size and date, and for an image, video or audio file its `assetId`. <details markdown="block" class="model-details"> <summary>The written file, field by field</summary> ```typescript { // TypeScript, all fields are optional email: string name: string path: string // workspace/… type: 'file' | 'directory' bytes: number | null modified: string | null // ISO 8601 assetId?: string | null // files only: the asset id of an image, video or audio file, else null error?: string // errors only code?: number // errors only } ``` </details> ##### Examples **Curl** ``` bash curl -X POST -H "Authorization: Bearer …" \ -H "Content-Type: application/pdf" \ --data-binary @report.pdf \ "https://api.useapi.net/v1/muse/files?email=example%40gmail.com&path=workspace%2Fyour_files%2Freport.pdf" ``` **JavaScript** ``` javascript import fs from "fs"; const token = "API token"; const params = new URLSearchParams({ email: "example@gmail.com", path: "workspace/your_files/report.pdf" }); const response = await fetch(`https://api.useapi.net/v1/muse/files?${params}`, { method: "POST", headers: { "Content-Type": "application/pdf", "Authorization": `Bearer ${token}`, }, body: fs.readFileSync("report.pdf") }); console.log("response", response.status, await response.json()); ``` **Python** ``` python import requests token = "API token" apiUrl = "https://api.useapi.net/v1/muse/files" headers = { "Content-Type": "application/pdf", "Authorization" : f"Bearer {token}" } response = requests.post(apiUrl, headers=headers, params={"email": "example@gmail.com", "path": "workspace/your_files/report.pdf"}, data=open("report.pdf", "rb").read()) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-muse-v1/post-muse-jobs-image === Document URL: https://useapi.net/docs/api-muse-v1/post-muse-jobs-image --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> jobs/image description: "Generate an image via POST jobs/image in the useapi.net Muse API: text to image or image to image from up to 9 inputs, aspect ratio set by prompt, WebP back." parent: Muse API nav_order: 200 permalink: /docs/api-muse-v1/post-muse-jobs-image --- ## Generate an image October 12, 2026 (November 16, 2026) --- Ask [Muse](https://muse.ai) for one image. Describe it in `prompt`, and optionally pass up to 9 input images as `image_1`..`image_9`. With inputs, Muse can combine them into one scene, edit an image, or restore and colorize an old photograph. The finished job lists the image in `result.assets[]` as an `assetId`. Download it with [GET /assets/`assetId`](/docs/api-muse-v1/get-muse-assets-assetId), or pass it as `image_N` to the next image job or to [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video) to animate it. `result.text` is the agent's last message. ### Prompt, aspect ratio and size Muse is an agent, not a fixed generator. There are no model, aspect ratio, resolution or duration parameters: describe the video in the prompt. - Aspect ratio: ask for it explicitly, best as `in exactly <ratio> aspect ratio`. Image to video keeps the start image's shape unless the prompt asks for another ratio. - Length: every video is about 10 seconds. - Sound: every video has audio. Dialogue written in quotes in the prompt is spoken. - Resolution: about 720p, MP4 (H.264, 24 fps). Asking for 1080p or 4K did not add detail when we tested it (October 2026), though Muse may change this. | Asked for | Video | |---|---| | `16:9` | 1280×720 or 1248×704 | | `9:16` | 720×1280 or 704×1248 | | `3:4` | 832×1104 | Muse is an agent, not a fixed generator. There are no model, aspect ratio or resolution parameters: describe the image in the prompt. - Aspect ratio: ask for it explicitly, best as `in exactly <ratio> aspect ratio`. Muse follows any common ratio. - Size: about 2 to 2.5 megapixels, WebP. | Asked for | Image | |---|---| | `1:1` | 1600×1600 | | `16:9` / `9:16` | 2048×1152 / 1152×2048 | | `3:2` / `2:3` | 1920×1280 / 1280×1920 | | `4:3` / `3:4` | 1792×1344 / 1344×1792 | | `5:4` / `4:5` | 1760×1408 / 1408×1760 | | `21:9` | 2352×1008 | ### Inputs | Parameter | Takes | Count | |---|---|---| | `image_1` .. `image_9` | an image asset id | up to 9 | | `video_1` .. `video_3` | a video asset id | up to 3 | | `audio_1` .. `audio_3` | an audio asset id | up to 3 | | Parameter | Takes | Count | |---|---|---| | `image_1` .. `image_9` | an image asset id | up to 9 | - An asset id comes from [POST /assets](/docs/api-muse-v1/post-muse-assets) (your own file) or from `result.assets[]` of an earlier job (a file Muse made). A generated file needs no download and no upload to be used again. - Each parameter takes an asset of its own type. An image asset in a `video_N` parameter answers `400`. - All inputs of one job must live on the same Muse account, and the job runs on that account. If you also send `email`, it must be that account. - Name the inputs in the prompt, for example `the person from image_2 wearing the jacket from image_1`. The API tells Muse which file each name stands for. A prompt that names an input you did not send answers `400`. ### Sync, async and webhooks - Every generation runs as a job on our side, which follows it for up to 10 minutes. In our tests an image took 20 to 60 seconds and a video 60 to 140 seconds. A job that is still running 15 minutes after it started is reported as failed with `504`. - Sync (the default): the POST waits for the job and answers `200` with the finished job record, or with the job's error code and the failed job record. If the job is still running after about 100 seconds, the POST answers `202` with the job as it stands (`status: "started"`): fetch the result with [GET /jobs/`jobid`](/docs/api-muse-v1/get-muse-jobs-jobid). Always check `status`: only `completed` has a `result`. - Async: pass `async: true`. The POST answers `201` at once with the job in `status: "started"`. Poll [GET /jobs/`jobid`](/docs/api-muse-v1/get-muse-jobs-jobid) or wait for the webhook. - `replyUrl` receives one `POST` of the final job record, as JSON, when the job completes or fails, for sync and async requests alike. It does not make a request async. Without `replyUrl`, the account-level `replyUrl` set with [POST /account](/docs/account-management/post-account) is used. Rarely, for example when a job is interrupted on our side, a job ends without a call to `replyUrl`: if you have not heard back within 15 minutes, read the job with [GET /jobs/`jobid`](/docs/api-muse-v1/get-muse-jobs-jobid), which always has the final status. - Each Muse account runs at most `maxJobs` jobs at a time (default `10`, range `1` to `50`, set with [POST /accounts](/docs/api-muse-v1/post-muse-accounts)). [GET /jobs](/docs/api-muse-v1/get-muse-jobs) shows what is running. Job records are kept for 7 days. An image uses a small part of the account's weekly allowance: 0 to 1 percent on the free plan in our tests. See [Weekly allowance](/docs/start-here/setup-muse#usage-limits). > **https://api.useapi.net/v1/muse/jobs/image** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "prompt": "Restore the old photograph image_1 as a high-quality modern photo: remove the scratches, dust, stains, fading and grain, and colorize it naturally. Keep the exact same person, expression, pose, framing and crop, and the same portrait aspect ratio as image_1: do not crop, extend or reframe it.", "image_1": "user:12345-email:6578616d706c6540676d61696c2e636f6d-image:3e788737ea18422b9809aeb06a453c072e15f1b3fb219d7a4fd7e8fffd733d4f.jpg", "async": true, "replyUrl": "https://your-domain.com/webhook", "replyRef": "restore-1" } ``` - `prompt` is **required**, what to make. Name the inputs as `image_1`, `image_2`… and say the aspect ratio here. Maximum length: `5000` characters. - `image_1` .. `image_9` are optional, input images as asset ids from [POST /assets](/docs/api-muse-v1/post-muse-assets) or from an earlier job's `result.assets[]`. See [Inputs](#inputs). - `email` is optional, the account to run on. When omitted, the account that holds the inputs is used, or without inputs a healthy account with allowance left and a free `maxJobs` slot. - `async` is optional, `true` to answer `201` at once and run the job in the background. Default: `false`. - `replyUrl` is optional, a public `https` URL that receives one `POST` of the job record when the job completes or fails. It works with sync and async requests. Callback body has the same JSON shape as [GET /jobs/`jobid`](/docs/api-muse-v1/get-muse-jobs-jobid) response. Maximum length: `1024` characters. - `replyRef` is optional, your own reference echoed back in the job record. Maximum length: `1024` characters. ##### Responses **200** **200 OK** — sync mode, the image is ready. This one changed the dress in an image made by an earlier job, 34 seconds after the request. ```json { "jobid": "j1012012322765813065i-u12345-email:example@gmail.com-task:a59c458f-efb4-4244-8ab7-f0d0c2744ea5-bot:muse", "type": "image", "email": "example@gmail.com", "status": "completed", "created": "2026-10-12T01:23:22.765Z", "request": { "prompt": "Change the dress of the woman in image_1 to a blue denim dress; keep everything else the same.", "image_1": "user:12345-email:6578616d706c6540676d61696c2e636f6d-image:media-generation-a-young-woman-in-a-red-summer-0-df6bcf46-d28c-4c0e-bffe-3b348d39cd0c.webp" }, "chatId": "a59c458f-efb4-4244-8ab7-f0d0c2744ea5", "messageId": "dff54c7e-65d1-46ec-85d2-3c538bcbb0ca", "updated": "2026-10-12T01:23:56.496Z", "completed": "2026-10-12T01:23:56.496Z", "result": { "assets": [ { "assetId": "user:12345-email:6578616d706c6540676d61696c2e636f6d-image:media-generation-change-the-dress-of-the-woman-0-0eec3b94-f75b-4eb5-a6cb-7c680546429e.webp", "type": "image", "mime": "image/webp", "bytes": 487120, "origin": "generated" } ], "text": "Done — blue denim dress, everything else untouched." } } ``` **201** **201 Created** — `async: true`: the job is running. Fetch the result with [GET /jobs/`jobid`](/docs/api-muse-v1/get-muse-jobs-jobid), or wait for the webhook. ```json { "jobid": "j1012012359487240036i-u12345-email:example@gmail.com-task:bcaa91f0-24e0-4b7e-8d2c-6624bf9562e0-bot:muse", "type": "image", "email": "example@gmail.com", "status": "started", "created": "2026-10-12T01:23:59.487Z", "request": { "prompt": "a red fox sitting in fresh snow, close-up photo", "async": true, "replyUrl": "https://your-domain.com/webhook", "replyRef": "fox-1" }, "chatId": "bcaa91f0-24e0-4b7e-8d2c-6624bf9562e0", "replyUrl": "https://your-domain.com/webhook", "replyRef": "fox-1" } ``` **202** **202 Accepted** — sync mode, the job was still running after about 100 seconds. The body is the job record with `status: "started"`, as in `201`. The job keeps running: fetch it with [GET /jobs/`jobid`](/docs/api-muse-v1/get-muse-jobs-jobid). **400** **400 Bad Request** — a parameter is missing or invalid, an input is not an image asset, the inputs live on different accounts, or the prompt names an input that was not sent. ```json { "error": "The prompt names image_2, but 'image_2' was not provided in the request body", "code": 400 } ``` ```json { "error": "Parameter model not supported", "code": 400 } ``` ```json { "error": "Please configure at least one account at https://useapi.net/docs/api-muse-v1/post-muse-accounts", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** — an input asset id belongs to another API token: ```json { "error": "This asset id does not belong to this API token", "code": 403 } ``` Or, in sync mode, Muse refused to make the image: the body is the failed job record, and `error.message` has the agent's own words. Change the prompt or the inputs. See [error codes](/docs/api-muse-v1/get-muse-jobs-jobid#error-codes). **404** **404 Not Found** — the account named by `email`, or the account an input lives on, is not added. ```json { "error": "Account example@gmail.com is not configured", "code": 404 } ``` **409** **409 Conflict** — in sync mode, Muse would not make the image because it says the account already made this request or already has it queued. The body is the failed job record, and `error.message` has Muse's own words. Change the prompt, or run it on another account. See [error codes](/docs/api-muse-v1/get-muse-jobs-jobid#error-codes). **412** **412 Precondition Failed** — the account's weekly Muse allowance is used up (or every account's, without `email`). It counts again after the reset time in the message. In sync mode a job that Muse turned down for this reason answers `412` with the failed job record. ```json { "error": "All 2 healthy accounts have used up their Muse allowance. GET /accounts/{email} re-reads it", "code": 412 } ``` **429** **429 Too Many Requests** — the account is running `maxJobs` jobs, or every account is. The response carries `Retry-After: 30`. In sync mode `429` can also be a job that Muse turned down because it was limiting the account: retry in about a minute. ```json { "error": "All 1 accounts are running their maximum number of jobs (maxJobs), please retry shortly", "code": 429 } ``` **502** **502 Bad Gateway** — sync mode, Muse made the image but the API cannot return it, for example because of an unusual file name. The body is the failed job record and `error.message` says why. The image is in the job's chat, see [GET /jobs/`jobid`?history=true](/docs/api-muse-v1/get-muse-jobs-jobid). Running the job again uses the allowance again. **503** **503 Service Unavailable** — nothing was made: the job could not be started, Muse could not be reached, or Muse failed to make the image this time and said so. The body is the failed job record. Run it again. **504** **504 Gateway Timeout** — sync mode, Muse did not finish in time or the connection dropped after the job was sent. The body is the failed job record. Muse may still have made the image: check [GET /jobs/`jobid`?history=true](/docs/api-muse-v1/get-muse-jobs-jobid) before running it again. **596** **596 Account Error** The account needs your attention, and it is paused until you add it again. You receive an email when this happens. There are three causes. Meta asks for a security check on the account. Sign in once at [muse.ai](https://muse.ai) in a browser, complete the check, then add the account again with [POST /accounts](/docs/api-muse-v1/post-muse-accounts) using the same email and password. The API keeps using its session, so no new sign-in is needed. ```json { "error": "Account example@gmail.com: Meta asks for a security check on account example@gmail.com (\"This account must complete a security checkpoint on the web\"). Sign in once at https://muse.ai in a browser, complete the check, then add the account again with POST /accounts", "code": 596 } ``` Or Muse refused to sign the account in again when its session needed renewing, most often because the password was changed. Add the account again with the current password. ```json { "error": "Account example@gmail.com: Muse refused to sign in account example@gmail.com (…). Update its password with POST /accounts, or sign in at https://muse.ai to clear the block, then re-add it", "code": 596 } ``` Or Muse disabled the account's computer and refuses to start it again. Sign in at [muse.ai](https://muse.ai) in a browser to see why, and ask Muse support to restore it with the form Muse shows there. Add the account again only after Muse has restored it. ```json { "error": "Account example@gmail.com: Muse has disabled the computer of account example@gmail.com (\"VM wake unavailable\"). Sign in at https://muse.ai in a browser to see why and contact Muse support there, then add the account again with POST /accounts", "code": 596 } ``` Without `email` and without inputs, the same code means no added account is healthy: ```json { "error": "No healthy Muse account configured. Check GET /accounts", "code": 596 } ``` ##### Model The job record, `type: "image"`. [GET /jobs/`jobid`](/docs/api-muse-v1/get-muse-jobs-jobid) and the `replyUrl` webhook return the same shape. Errors before a job is created return `{ error, code }`. <details markdown="block" class="model-details"> <summary>The job record, field by field</summary> ```typescript { // TypeScript, all fields are optional jobid: string // j<nonce><i|v>-u<id>-email:<email>-task:<chat id>-bot:muse type: 'image' | 'video' email: string // the Muse account the job runs on status: 'started' | 'completed' | 'failed' created: string // ISO 8601, when the job was accepted updated?: string // ISO 8601, the last change completed?: string // ISO 8601, when the job completed or failed request: Record<string, unknown> // your request body as sent chatId: string // the Muse chat this job created (also inside the jobid) messageId?: string // Muse's id of the job's message in that chat, once it was sent replyUrl?: string replyRef?: string error?: { // status 'failed' code: number // see the error codes on GET /jobs/{jobid} message: string // when Muse refused, its own words retryAt?: string // ISO 8601, code 429 for Muse's video limit on a job that could only run on this account: // video jobs try the account again after this time } result?: { // status 'completed' assets: { // the files the job made, the finished one first: usually one, two when the agent finishes // Muse's file with its own tools (e.g. lays your audio_1 onto the generated clip) assetId: string // download it with GET /assets/{assetId}, or pass it as image_N / video_N of the next job type: 'image' | 'video' | 'audio' mime: string // e.g. image/webp, video/mp4 bytes: number origin: 'generated' | 'made' // generated by Muse, or made by the agent with its own tools (an edit) }[] text: string | null // the agent's last message, e.g. "Here's your image." } history?: unknown[] // GET /jobs/{jobid}?history=true only: the job's chat turn as Muse sent it historyError?: string // GET /jobs/{jobid}?history=true only: why the chat could not be read } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/muse/jobs/image" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "prompt": "In exactly 16:9 aspect ratio (landscape), a cinematic photo of a vintage 1920s black BMW motorcycle parked on wet cobblestones at night in San Francisco, the Golden Gate Bridge glowing through fog in the distance" }' ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = "https://api.useapi.net/v1/muse"; const headers = { "Content-Type": "application/json", "Authorization": `Bearer ${token}` }; const response = await fetch(`${apiUrl}/jobs/image`, { method: "POST", headers, body: JSON.stringify({ prompt: "In exactly 9:16 aspect ratio, a full-body portrait photo of a woman biker in a black leather jacket in a rain-soaked neon alley" }) }); const job = await response.json(); if (job.status === "completed") { const { assetId } = job.result.assets[0]; const image = await fetch(`${apiUrl}/assets/${encodeURIComponent(assetId)}`, { headers }); console.log("image bytes", (await image.arrayBuffer()).byteLength, job.result.text); } else console.log("response", response.status, job); ``` **Python** ``` python import requests from urllib.parse import quote token = "API token" apiUrl = "https://api.useapi.net/v1/muse" headers = {"Content-Type": "application/json", "Authorization": f"Bearer {token}"} data = {"prompt": "In exactly 9:16 aspect ratio, a full-body portrait photo of a woman biker in a black leather jacket in a rain-soaked neon alley"} job = requests.post(f"{apiUrl}/jobs/image", headers=headers, json=data).json() if job.get("status") == "completed": asset_id = job["result"]["assets"][0]["assetId"] image = requests.get(f"{apiUrl}/assets/{quote(asset_id, safe='')}", headers=headers) with open("image.webp", "wb") as f: f.write(image.content) else: print(job) ``` === URL: https://useapi.net/docs/api-muse-v1/post-muse-jobs-video === Document URL: https://useapi.net/docs/api-muse-v1/post-muse-jobs-video --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> jobs/video seo_title: "Meta Muse Video API: POST jobs/video, 10-Second Clips with Sound" description: "Generate a 10-second Meta Muse video with sound via POST jobs/video in the useapi.net Muse API: text, image or video to video, talking photos, up to 15 inputs." parent: Muse API nav_order: 210 permalink: /docs/api-muse-v1/post-muse-jobs-video --- ## Generate a video October 12, 2026 (November 16, 2026) --- Ask [Muse](https://muse.ai) for one video of about 10 seconds with sound. Describe it in `prompt`, and optionally pass input files: up to 9 images as `image_1`..`image_9`, 3 videos as `video_1`..`video_3` and 3 audio files as `audio_1`..`audio_3`. - Text to video: no inputs. - Image to video: animate `image_1`, an uploaded image or one Muse made. Write a line in quotes and the person in the photo speaks it, a talking photo. - Video to video: edit `video_1`, for example replace a person in it with someone from `image_1`. The finished job lists the video in `result.assets[]` as an `assetId`. When the agent finishes Muse's clip with its own tools, for example lays your `audio_1` onto it, both files are listed and the finished one is first. Download it with [GET /assets/`assetId`](/docs/api-muse-v1/get-muse-assets-assetId), or pass it as `video_N` to the next video job. `result.text` is the agent's last message. ### Prompt, aspect ratio and length Muse is an agent, not a fixed generator. There are no model, aspect ratio, resolution or duration parameters: describe the video in the prompt. - Aspect ratio: ask for it explicitly, best as `in exactly <ratio> aspect ratio`. Image to video keeps the start image's shape unless the prompt asks for another ratio. - Length: every video is about 10 seconds. - Sound: every video has audio. Dialogue written in quotes in the prompt is spoken. - Resolution: about 720p, MP4 (H.264, 24 fps). Asking for 1080p or 4K did not add detail when we tested it (October 2026), though Muse may change this. | Asked for | Video | |---|---| | `16:9` | 1280×720 or 1248×704 | | `9:16` | 720×1280 or 704×1248 | | `3:4` | 832×1104 | Muse is an agent, not a fixed generator. There are no model, aspect ratio or resolution parameters: describe the image in the prompt. - Aspect ratio: ask for it explicitly, best as `in exactly <ratio> aspect ratio`. Muse follows any common ratio. - Size: about 2 to 2.5 megapixels, WebP. | Asked for | Image | |---|---| | `1:1` | 1600×1600 | | `16:9` / `9:16` | 2048×1152 / 1152×2048 | | `3:2` / `2:3` | 1920×1280 / 1280×1920 | | `4:3` / `3:4` | 1792×1344 / 1344×1792 | | `5:4` / `4:5` | 1760×1408 / 1408×1760 | | `21:9` | 2352×1008 | ### Inputs | Parameter | Takes | Count | |---|---|---| | `image_1` .. `image_9` | an image asset id | up to 9 | | `video_1` .. `video_3` | a video asset id | up to 3 | | `audio_1` .. `audio_3` | an audio asset id | up to 3 | | Parameter | Takes | Count | |---|---|---| | `image_1` .. `image_9` | an image asset id | up to 9 | - An asset id comes from [POST /assets](/docs/api-muse-v1/post-muse-assets) (your own file) or from `result.assets[]` of an earlier job (a file Muse made). A generated file needs no download and no upload to be used again. - Each parameter takes an asset of its own type. An image asset in a `video_N` parameter answers `400`. - All inputs of one job must live on the same Muse account, and the job runs on that account. If you also send `email`, it must be that account. - Name the inputs in the prompt, for example `the person from image_2 wearing the jacket from image_1`. The API tells Muse which file each name stands for. A prompt that names an input you did not send answers `400`. Our tests used image and video inputs. Muse decides how to use an audio file from what the prompt says about it. ### Sync, async and webhooks - Every generation runs as a job on our side, which follows it for up to 10 minutes. In our tests an image took 20 to 60 seconds and a video 60 to 140 seconds. A job that is still running 15 minutes after it started is reported as failed with `504`. - Sync (the default): the POST waits for the job and answers `200` with the finished job record, or with the job's error code and the failed job record. If the job is still running after about 100 seconds, the POST answers `202` with the job as it stands (`status: "started"`): fetch the result with [GET /jobs/`jobid`](/docs/api-muse-v1/get-muse-jobs-jobid). Always check `status`: only `completed` has a `result`. - Async: pass `async: true`. The POST answers `201` at once with the job in `status: "started"`. Poll [GET /jobs/`jobid`](/docs/api-muse-v1/get-muse-jobs-jobid) or wait for the webhook. - `replyUrl` receives one `POST` of the final job record, as JSON, when the job completes or fails, for sync and async requests alike. It does not make a request async. Without `replyUrl`, the account-level `replyUrl` set with [POST /account](/docs/account-management/post-account) is used. Rarely, for example when a job is interrupted on our side, a job ends without a call to `replyUrl`: if you have not heard back within 15 minutes, read the job with [GET /jobs/`jobid`](/docs/api-muse-v1/get-muse-jobs-jobid), which always has the final status. - Each Muse account runs at most `maxJobs` jobs at a time (default `10`, range `1` to `50`, set with [POST /accounts](/docs/api-muse-v1/post-muse-accounts)). [GET /jobs](/docs/api-muse-v1/get-muse-jobs) shows what is running. Job records are kept for 7 days. A video took 60 to 140 seconds in our tests, so a sync request answers `202` for the slower ones. Swapping a person in a video took the longest. Send videos with `async: true` when you would rather poll or use the webhook. A video uses 2 to 3 percent of the weekly allowance on the free plan. See [Weekly allowance](/docs/start-here/setup-muse#usage-limits). ### Video limit Besides the weekly allowance, Muse limits the videos an account makes over the last 24 hours. When Muse answers a job that the account reached this limit, nothing is made and the job fails with `429`, with Muse's own words in `error.message`. Muse gives no reset time, so video jobs then skip that account for one hour, and after the hour one job tries it again. - A job that could go to any account fails without `retryAt`: run it again right away and it goes to your other accounts. - A job that can only run on that account, because it names `email` or its inputs live there, fails with `error.retryAt`, the time video jobs try the account again. Until then a new job for that account is answered `429` at once with `retryAt`, without creating a job. So is any video job when every account has reached the limit. - [GET /accounts](/docs/api-muse-v1/get-muse-accounts) shows `videoLimitUntil` while it applies. Adding the account again with [POST /accounts](/docs/api-muse-v1/post-muse-accounts) clears it. - Image jobs, chats and uploads are not affected. Meta can also switch off video for an account in its country or region, for example when the account is used from outside the [regions Muse supports](/docs/start-here/setup-muse). Muse then answers that video is not available for the account in its country or region, and says it is lasting. That job fails with `403`, and from then on video jobs skip the account: a video job that names it is answered `403` at once, without creating a job. [GET /accounts](/docs/api-muse-v1/get-muse-accounts) shows `videoRegionBlocked`. Image jobs still work. Once video works for the account again at muse.ai, adding it again with [POST /accounts](/docs/api-muse-v1/post-muse-accounts) clears it. > **https://api.useapi.net/v1/muse/jobs/video** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "prompt": "Edit video_1: replace the rider with the woman from image_1 (her face, pink hair in two buns, colorful makeup and tattoos), and keep everything else the same: the motorcycle, the beach, the waves and spray, the Golden Gate Bridge, the light, the camera move and the timing. Instead of the original line she shouts: \"Catch me if you can, San Francisco!\" Keep the 16:9 frame and the same length.", "video_1": "user:12345-email:6578616d706c6540676d61696c2e636f6d-video:media-generation-shoreline-motorcycle-ride-16x9-0-acd2974b-63e0-4539-8279-3a9384f4ccb0.mp4", "image_1": "user:12345-email:6578616d706c6540676d61696c2e636f6d-image:fb07d74a0e9144e4ae5bb3f6f2d1045abbf209e20693b9cb4833d932e2b3ffd7.jpg", "async": true, "replyUrl": "https://your-domain.com/webhook", "replyRef": "rider-swap-1" } ``` - `prompt` is **required**, what to make. Name the inputs as `image_1`, `video_1`, `audio_1`… and say the aspect ratio and the spoken lines here. Maximum length: `5000` characters. - `image_1` .. `image_9` are optional, input images as asset ids from [POST /assets](/docs/api-muse-v1/post-muse-assets) or from an earlier job's `result.assets[]`. See [Inputs](#inputs). - `video_1` .. `video_3` are optional, input videos as asset ids. - `audio_1` .. `audio_3` are optional, input audio files as asset ids. - `email` is optional, the account to run on. When omitted, the account that holds the inputs is used, or without inputs a healthy account with allowance left, a free `maxJobs` slot and no [video limit](#video-limit) in effect. - `async` is optional, `true` to answer `201` at once and run the job in the background. Default: `false`. - `replyUrl` is optional, a public `https` URL that receives one `POST` of the job record when the job completes or fails. It works with sync and async requests. Callback body has the same JSON shape as [GET /jobs/`jobid`](/docs/api-muse-v1/get-muse-jobs-jobid) response. Maximum length: `1024` characters. - `replyRef` is optional, your own reference echoed back in the job record. Maximum length: `1024` characters. ##### Responses **200** **200 OK** — sync mode, the video is ready. This one animated an uploaded image, 83 seconds after the request. ```json { "jobid": "j1012012156286615380v-u12345-email:example@gmail.com-task:20842037-a004-4dba-b640-225a8197385b-bot:muse", "type": "video", "email": "example@gmail.com", "status": "completed", "created": "2026-10-12T01:21:56.286Z", "request": { "prompt": "Animate image_1: she turns toward the camera and smiles, the wind moves her dress. Keep the vertical 9:16 frame.", "image_1": "user:12345-email:6578616d706c6540676d61696c2e636f6d-image:558c51be411f66026e9ca195d9330e5582d5e5807e455926ad29d6cfbe02e302.webp" }, "chatId": "20842037-a004-4dba-b640-225a8197385b", "messageId": "28d4035a-7eec-4720-95a9-84a8dd1e9f2b", "updated": "2026-10-12T01:23:18.960Z", "completed": "2026-10-12T01:23:18.960Z", "result": { "assets": [ { "assetId": "user:12345-email:6578616d706c6540676d61696c2e636f6d-video:media-generation-create-one-video-animate-image-0-def1ac18-8024-4a8b-9bce-a2700d683f45.mp4", "type": "video", "mime": "video/mp4", "bytes": 5066535, "origin": "generated" } ], "text": "Done — here's your clip, vertical 9:16, 10 seconds." } } ``` **201** **201 Created** — `async: true`: the job is running. Fetch the result with [GET /jobs/`jobid`](/docs/api-muse-v1/get-muse-jobs-jobid), or wait for the webhook. ```json { "jobid": "j1012014112831908109v-u12345-email:example@gmail.com-task:3e8bc834-f243-4172-8f6e-9fc28e1a107c-bot:muse", "type": "video", "email": "example@gmail.com", "status": "started", "created": "2026-10-12T01:41:12.831Z", "request": { "prompt": "Animate image_1 into a video with the same portrait frame: the young woman slowly lifts her eyes to the camera, her smile widens, she gently touches the rose on her shoulder and says softly: \"It has been a hundred years... and you still remember me.\" Keep her face exactly as in image_1.", "image_1": "user:12345-email:6578616d706c6540676d61696c2e636f6d-image:media-generation-restored-portrait-0-69c7e16d-eb86-4932-b940-8d688f2b95dc.webp", "async": true }, "chatId": "3e8bc834-f243-4172-8f6e-9fc28e1a107c" } ``` **202** **202 Accepted** — sync mode, the job was still running after about 100 seconds. The body is the job record with `status: "started"`, as in `201`. The job keeps running: fetch it with [GET /jobs/`jobid`](/docs/api-muse-v1/get-muse-jobs-jobid). **400** **400 Bad Request** — a parameter is missing or invalid, an input is not of its parameter's type, the inputs live on different accounts, or the prompt names an input that was not sent. ```json { "error": "The prompt names image_2, but 'image_2' was not provided in the request body", "code": 400 } ``` ```json { "error": "Parameter image_1 must be a image asset, this one is a video", "code": 400 } ``` ```json { "error": "Please configure at least one account at https://useapi.net/docs/api-muse-v1/post-muse-accounts", "code": 400 } ``` **401** **401 Unauthorized** Invalid API token. ```json { "error": "useapi.net ⁝ Unauthorized", "code": 401 } ``` **403** **403 Forbidden** — an input asset id belongs to another API token: ```json { "error": "This asset id does not belong to this API token", "code": 403 } ``` Or Meta has switched off video for the account in its country or region (see [Video limit](#video-limit)), and the job names that account (with `email`, or with inputs that live on it), or every account has video switched off: ```json { "error": "Meta has switched off video for account example@gmail.com in its country or region (Muse said so on 2026-11-12T22:47:51.012Z), so video jobs cannot run on it. Image jobs still work. Once video works for the account again at muse.ai, add it again with POST /accounts", "code": 403 } ``` Or, in sync mode, Muse refused to make the video: the body is the failed job record, and `error.message` has the agent's own words. Change the prompt or the inputs. See [error codes](/docs/api-muse-v1/get-muse-jobs-jobid#error-codes). **404** **404 Not Found** — the account named by `email`, or the account an input lives on, is not added. ```json { "error": "Account example@gmail.com is not configured", "code": 404 } ``` **409** **409 Conflict** — in sync mode, Muse would not make the video because it says the account already made this request or already has it queued. The body is the failed job record, and `error.message` has Muse's own words. Change the prompt, or run it on another account. See [error codes](/docs/api-muse-v1/get-muse-jobs-jobid#error-codes). **412** **412 Precondition Failed** — the account's weekly Muse allowance is used up (or every account's, without `email`). It counts again after the reset time in the message. In sync mode a job that Muse turned down for this reason answers `412` with the failed job record. ```json { "error": "All 2 healthy accounts have used up their Muse allowance. GET /accounts/{email} re-reads it", "code": 412 } ``` **429** **429 Too Many Requests** — one of three causes. The account is running `maxJobs` jobs, or every account is. The response carries `Retry-After: 30`. ```json { "error": "All 1 accounts are running their maximum number of jobs (maxJobs), please retry shortly", "code": 429 } ``` The account reached Muse's [video limit](#video-limit) for the last 24 hours: the one named by `email` or holding the inputs, or every account when the job could go to any. No job is created and nothing is sent to Muse. `retryAt`, and the `Retry-After` header in seconds, say when video jobs try the account again. ```json { "error": "Account example@gmail.com reached Muse's video limit for the last 24 hours. Video jobs try it again after 2026-10-23T14:12:00.000Z", "code": 429, "retryAt": "2026-10-23T14:12:00.000Z" } ``` ```json { "error": "All 3 accounts reached Muse's video limit for the last 24 hours. Video jobs try the first one again after 2026-10-23T14:12:00.000Z", "code": 429, "retryAt": "2026-10-23T14:12:00.000Z" } ``` In sync mode the body can also be a failed job record, without a `Retry-After` header: Muse was limiting requests on the account (retry in about a minute), or Muse answered the job that the account reached its video limit. See [error codes](/docs/api-muse-v1/get-muse-jobs-jobid#error-codes). **502** **502 Bad Gateway** — sync mode, Muse made the video but the API cannot return it, for example because of an unusual file name. The body is the failed job record and `error.message` says why. The video is in the job's chat, see [GET /jobs/`jobid`?history=true](/docs/api-muse-v1/get-muse-jobs-jobid). Running the job again uses the allowance again. **503** **503 Service Unavailable** — nothing was made: the job could not be started, Muse could not be reached, or Muse failed to make the video this time and said so. The body is the failed job record. Run it again. When Muse says the account reached its video limit, the answer is `429`, not `503`. **504** **504 Gateway Timeout** — sync mode, Muse did not finish in time or the connection dropped after the job was sent. The body is the failed job record. Muse may still have made the video: check [GET /jobs/`jobid`?history=true](/docs/api-muse-v1/get-muse-jobs-jobid) before running it again. **596** **596 Account Error** The account needs your attention, and it is paused until you add it again. You receive an email when this happens. There are three causes. Meta asks for a security check on the account. Sign in once at [muse.ai](https://muse.ai) in a browser, complete the check, then add the account again with [POST /accounts](/docs/api-muse-v1/post-muse-accounts) using the same email and password. The API keeps using its session, so no new sign-in is needed. ```json { "error": "Account example@gmail.com: Meta asks for a security check on account example@gmail.com (\"This account must complete a security checkpoint on the web\"). Sign in once at https://muse.ai in a browser, complete the check, then add the account again with POST /accounts", "code": 596 } ``` Or Muse refused to sign the account in again when its session needed renewing, most often because the password was changed. Add the account again with the current password. ```json { "error": "Account example@gmail.com: Muse refused to sign in account example@gmail.com (…). Update its password with POST /accounts, or sign in at https://muse.ai to clear the block, then re-add it", "code": 596 } ``` Or Muse disabled the account's computer and refuses to start it again. Sign in at [muse.ai](https://muse.ai) in a browser to see why, and ask Muse support to restore it with the form Muse shows there. Add the account again only after Muse has restored it. ```json { "error": "Account example@gmail.com: Muse has disabled the computer of account example@gmail.com (\"VM wake unavailable\"). Sign in at https://muse.ai in a browser to see why and contact Muse support there, then add the account again with POST /accounts", "code": 596 } ``` Without `email` and without inputs, the same code means no added account is healthy: ```json { "error": "No healthy Muse account configured. Check GET /accounts", "code": 596 } ``` ##### Model The job record, `type: "video"`. [GET /jobs/`jobid`](/docs/api-muse-v1/get-muse-jobs-jobid) and the `replyUrl` webhook return the same shape. Errors before a job is created return `{ error, code }`. <details markdown="block" class="model-details"> <summary>The job record, field by field</summary> ```typescript { // TypeScript, all fields are optional jobid: string // j<nonce><i|v>-u<id>-email:<email>-task:<chat id>-bot:muse type: 'image' | 'video' email: string // the Muse account the job runs on status: 'started' | 'completed' | 'failed' created: string // ISO 8601, when the job was accepted updated?: string // ISO 8601, the last change completed?: string // ISO 8601, when the job completed or failed request: Record<string, unknown> // your request body as sent chatId: string // the Muse chat this job created (also inside the jobid) messageId?: string // Muse's id of the job's message in that chat, once it was sent replyUrl?: string replyRef?: string error?: { // status 'failed' code: number // see the error codes on GET /jobs/{jobid} message: string // when Muse refused, its own words retryAt?: string // ISO 8601, code 429 for Muse's video limit on a job that could only run on this account: // video jobs try the account again after this time } result?: { // status 'completed' assets: { // the files the job made, the finished one first: usually one, two when the agent finishes // Muse's file with its own tools (e.g. lays your audio_1 onto the generated clip) assetId: string // download it with GET /assets/{assetId}, or pass it as image_N / video_N of the next job type: 'image' | 'video' | 'audio' mime: string // e.g. image/webp, video/mp4 bytes: number origin: 'generated' | 'made' // generated by Muse, or made by the agent with its own tools (an edit) }[] text: string | null // the agent's last message, e.g. "Here's your image." } history?: unknown[] // GET /jobs/{jobid}?history=true only: the job's chat turn as Muse sent it historyError?: string // GET /jobs/{jobid}?history=true only: why the chat could not be read } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/muse/jobs/video" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "prompt": "Cinematic 16:9 landscape video, about 10 seconds: an old mechanic in a dusty 1920s garage polishes the chrome headlamp of a vintage black motorcycle, then looks up at the camera and says warmly: \"They don'\''t build them like this anymore.\" Warm tungsten light, slow push-in.", "async": true }' ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = "https://api.useapi.net/v1/muse"; const headers = { "Content-Type": "application/json", "Authorization": `Bearer ${token}` }; const image_1 = "assetId of an image, from POST /assets or an earlier job"; const response = await fetch(`${apiUrl}/jobs/video`, { method: "POST", headers, body: JSON.stringify({ image_1, async: true, prompt: "Animate image_1: she turns to the camera and says: \"Best seat in San Francisco.\" Keep her face exactly as in image_1." }) }); let job = await response.json(); while (job.status === "started") { await new Promise(resolve => setTimeout(resolve, 10000)); job = await (await fetch(`${apiUrl}/jobs/${encodeURIComponent(job.jobid)}`, { headers })).json(); } if (job.status === "completed") { const { assetId } = job.result.assets[0]; const video = await fetch(`${apiUrl}/assets/${encodeURIComponent(assetId)}`, { headers }); console.log("video bytes", (await video.arrayBuffer()).byteLength, job.result.text); } else console.log("job", job); ``` **Python** ``` python import requests, time from urllib.parse import quote token = "API token" apiUrl = "https://api.useapi.net/v1/muse" headers = {"Content-Type": "application/json", "Authorization": f"Bearer {token}"} image_1 = "assetId of an image, from POST /assets or an earlier job" data = {"image_1": image_1, "async": True, "prompt": "Animate image_1: she turns to the camera and says: \"Best seat in San Francisco.\" Keep her face exactly as in image_1."} job = requests.post(f"{apiUrl}/jobs/video", headers=headers, json=data).json() while job.get("status") == "started": time.sleep(10) job = requests.get(f"{apiUrl}/jobs/{quote(job['jobid'], safe='')}", headers=headers).json() if job.get("status") == "completed": asset_id = job["result"]["assets"][0]["assetId"] video = requests.get(f"{apiUrl}/assets/{quote(asset_id, safe='')}", headers=headers) with open("video.mp4", "wb") as f: f.write(video.content) else: print(job) ``` === URL: https://useapi.net/docs/start-here/setup-pixverse === Document URL: https://useapi.net/docs/start-here/setup-pixverse --- layout: default title: Setup PixVerse description: "How to set up PixVerse for the useapi.net API — connect your account and start generating via the API." parent: Start Here nav_order: 240 --- # <img style="height:1.3em;vertical-align: bottom;" src="/assets/images/pixverse.png" alt=""> Setup PixVerse December 6, 2024 ## Table of contents Approximately 2 minutes to complete setup steps. --- > This is the setup guide for [PixVerse API](/docs/api-pixverse-v2). An active [PixVerse.ai](https://pixverse.ai) account and a [useapi.net subscription](/docs/subscription) are required for the API to work. ## Create PixVerse.ai account Navigate to [PixVerse.ai](https://PixVerse.ai) and sign up with an email account. Our API does not support Gmail, Apple, or Discord accounts. We strongly recommend creating a separate PixVerse.ai account designated for API work. ![](/assets/images/pixverse_setup-v2-web.png) ## Configure PixVerse.ai API account Now that you have a working PixVerse.ai account, configure it for API access using [POST /accounts/`email`](/docs/api-pixverse-v2/post-pixverse-accounts-email). You will need your `email` and `password`. You should receive response `200` if successful. ## `OPTIONAL` Configure PixVerse API to use the current PixVerse.ai session The PixVerse.ai website enforces a single active session for a given account. When the API is running, it will terminate your web session. If you want to use the website and run the API simultaneously, you will need to perform the following steps in the **exact** order: * [POST /accounts/`email`](/docs/api-pixverse-v2/post-pixverse-accounts-email) using your `email` and `password`. * Navigate to [PixVerse.ai](https://PixVerse.ai), **logout** from your account, and **login** again. * Using the screenshot below, locate the session `token`. <details markdown="block"> <summary><b>Screenshot</b></summary> <img src="/assets/images/pixverse_setup_v2-token.png"> </details> * [POST /accounts/`email`](/docs/api-pixverse-v2/post-pixverse-accounts-email) using your `email`, `password` and the obtained `token`. * Keep the website open. Now, your API and your browser will share the session token, allowing you to use both. Keep in mind that the API will eventually try to refresh the token, so the approach described above is only effective for a limited time. We strongly recommend not using the API account for any manual generation to avoid any interference with the API. === URL: https://useapi.net/docs/api-pixverse-v2 === Document URL: https://useapi.net/docs/api-pixverse-v2 --- layout: default title: PixVerse API nav_logo: /assets/images/pixverse.png nav_title: PixVerse API seo_title: "PixVerse API: V6, Seedance 2.5 and Kling 4.0 on Ultra, Premium, Pro" description: "Third-party PixVerse API by useapi.net: PixVerse V6, Seedance 2.5, Kling 4.0 and O3, Veo 3.1 and MiniMax H3 video, plus Nano Banana Pro and GPT Image 2.5 images, on your PixVerse subscription." nav_order: 2400 has_children: true permalink: /docs/api-pixverse-v2 repo: https://github.com/useapi/pixverse-api --- # <img style="height:1.3em;vertical-align: bottom;" src="/assets/images/pixverse.png" alt=""> PixVerse API December 6, 2024 (November 20, 2026) This is a [third-party](/docs/legal#affiliation--third-party-services) API for [PixVerse](https://pixverse.ai) by AIsphere. It uses your [PixVerse subscription](https://app.pixverse.ai/subscribe): Free (Basic), Standard $10, Pro $30, Premium $60, Ultra $199 or Team Ultra $199 a seat a month (as of November 2026). It makes video with PixVerse V6 and C1, with Off-Peak mode and more than 900 effects, plus images, music, [music videos](/docs/api-pixverse-v2/post-pixverse-music-video-create), speech, upscaling and [Seedance 2.5, Kling 4.0 and O3, Veo 3.1 Fast, MiniMax H3 and more](#models), through a REST API and a hosted MCP server. PixVerse's own developer API bills separate credits that a PixVerse subscription can't pay for, and it has no Off-Peak mode. On Premium, a 5-second 1080p PixVerse V6 video with sound uses $0.40 of the plan's monthly credits, or $0.20 in Off-Peak mode, against $0.51 a video on PixVerse's own API. ## Models | Model | What it makes | Notes | |---|---|---| | PixVerse V6<br>`v6` | Video from [text or an image](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) or from [a first and a last frame](/docs/api-pixverse-v2/post-pixverse-videos-create-frames-v4), and it [extends](/docs/api-pixverse-v2/post-pixverse-videos-extend-v4) videos | 1 to 15 seconds, 360p to 1080p, sound, multi-shot, Off-Peak and preview mode | | [PixVerse C1](https://pixverse.ai)<br>`pixverse-c1` | Video from text, an image, two frames or [up to 7 reference images](/docs/api-pixverse-v2/post-pixverse-videos-create-fusion) | 1 to 15 seconds, 360p to 1080p, sound, Off-Peak and preview mode | | PixVerse V5.6, V5.5, V5 and V5 Fast<br>`v5.6`, `v5.5`, `v5`, `v5-fast` | Video from text, an image or two frames, and V5.6 and V5 also from reference images | 1 to 10 seconds, 1080p up to 8 seconds, sound on V5.6 and V5.5 | | [Seedance 2.5](https://seed.bytedance.com/seedance)<br>`seedance-2.5` | Video from text, an image, two frames or references | 4 to 30 seconds, 480p to 4K, sound, up to 30 images, 10 videos and 10 audio clips, 50 in total | | Seedance 2.5 Flash and Draft<br>`seedance-2.5-flash`, `seedance-2.5-draft` | Video from text, an image, two frames or references, and a draft [finished in 1080p or 4K](/docs/api-pixverse-v2/post-pixverse-videos-create-final) | 4 to 30 seconds with sound. Flash: 480p or 720p, up to 10 images, 5 videos and 5 audio clips. Draft: a 480p preview, kept 14 days | | Seedance 2.0, 2.0 Fast and 2.0 Mini<br>`seedance-2.0`, `seedance-2.0-fast`, `seedance-2.0-mini` | Video from text, an image, two frames or references | 4 to 15 seconds, 480p or 720p, 2.0 also 1080p and 4K, up to 9 images, 3 videos and 3 audio clips | | [Kling 4.0, O3 and 3.0](https://www.klingai.com)<br>`kling-4.0`, `kling-o3`, `kling-v3` | Video from text, an image or two frames, and 4.0 and O3 also from references | 4.0: 3 to 30 seconds, 720p or 1080p, sound, up to 10 images and 5 videos. O3 and 3.0: 3 to 15 seconds, Standard, Pro or 4K tier, sound on request, O3 up to 7 images | | [Veo 3.1](https://deepmind.google/technologies/veo) Lite, Standard and Fast<br>`veo-3.1-lite`, `veo-3.1-standard`, `veo-3.1-fast` | Video from text, an image or two frames | 4, 6 or 8 seconds, 720p or 1080p, 4K and sound on Standard and Fast | | [MiniMax H3 and H3 Max](https://www.minimax.io) (Hailuo 3.0)<br>`minimax-h3`, `minimax-h3-max` | Video from text, an image, two frames or up to 9 reference images | 5 to 15 seconds with sound, 768p or 2K on H3, 480p to 1080p on H3 Max | | [Gemini Omni Flash](https://deepmind.google/technologies/gemini/)<br>`gemini-omni-flash` | Video from text, an image, or up to 5 images and 3 reference videos | 3 to 10 seconds, 720p, sound | | [Wan 3.0](https://wan.video)<br>`wan-3.0` | Video from text, an image, two frames or references | 2 to 30 seconds, 480p to 1080p, sound on request, up to 10 images, 5 videos and 5 audio clips | | [Grok Imagine and Grok Imagine 1.5](https://x.ai/grok)<br>`grok-imagine`, `grok-imagine-1.5` | Video from text or an image (1.5 from an image only), and Grok Imagine extends videos | 1 to 15 seconds, 480p or 720p | | HappyHorse 1.0<br>`happyhorse-1.0` | Video from text or an image | 3 to 15 seconds, 720p or 1080p, sound | | [FLUX 3](https://bfl.ai)<br>`flux-3.0` | Video from text or an image | 5 to 20 seconds, 720p or 1080p, sound on request | | Motion control | Moves the person or animal in a character image like the subject of a [reference video](/docs/api-pixverse-v2/post-pixverse-videos-motion-control) | No prompt needed, Off-Peak works | | [Nano Banana](https://deepmind.google/technologies/gemini/flash/) Pro, 2.1, 2, 2 Lite and Nano Banana<br>`nano-banana-pro`, `nano-banana-2.1`, `nano-banana-2`, `nano-banana-2-lite`, `nano-banana` | [Images](/docs/api-pixverse-v2/post-pixverse-images-create) from text and up to 14 reference images | 1 to 4 per request, up to 4K, and 2.1 adds ratios up to 8:1 | | [Seedream](https://seed.bytedance.com/en/seedream) 5.0 Pro, 5.0 Lite, 4.5 and 4.0<br>`seedream-5.0-pro`, `seedream-5.0-lite`, `seedream-4.5`, `seedream-4.0` | Images from text and up to 10 reference images | 1 to 4 per request, up to 4K, 5.0 Pro up to 1440p | | [GPT Image](https://openai.com/) 2.5 Flare, 2.5 Sunburst and 2.0<br>`gpt-image-2.5-flare`, `gpt-image-2.5-sunburst`, `gpt-image-2.0` | Images from text and reference images, up to 16 on 2.5 and 9 on 2.0 | 1 to 4 per request, up to 4K, five detail levels on 2.5 | | [Qwen Image](https://github.com/QwenLM/Qwen2.5-VL), Kling O3 and Kling 3.0 images<br>`qwen-image`, `kling-o3`, `kling-3.0` | Images from text and reference images | Qwen Image in about 3 seconds, Kling O3 up to 4K | | Upscale: PixVerse Upscale and [Topaz](https://www.topazlabs.com) Proteus, Starlight Fast, Starlight Precise and Gigapixel<br>`pixverse-upscale`, `topaz-proteus`, `topaz-starlight-fast`, `topaz-starlight-precise`, `topaz-gigapixel` | [Videos](/docs/api-pixverse-v2/post-pixverse-videos-upscale) and [images](/docs/api-pixverse-v2/post-pixverse-images-upscale) at 1080p, 2K or 4K | Your own uploads too, videos up to 3 minutes, with a free price quote first | | Music: [MiniMax](https://www.minimax.io) Music 2.6, [ElevenLabs](https://elevenlabs.io) Music v1 and [Lyria 3 Pro](https://deepmind.google/technologies/lyria)<br>`music-2.6`, `music-v1`, `lyria-3-pro-preview` | [Songs and instrumentals](/docs/api-pixverse-v2/post-pixverse-music-create) from a prompt | Your own lyrics or lyrics the model writes, and Lyria 3 Pro takes up to 10 reference images | | Music videos | A full [music video](/docs/api-pixverse-v2/post-pixverse-music-video-create) from your song and a character photo | Performance with lip-sync, expressive or storytelling, lyric captions, up to 6 minutes, 720p or 1080p | | Speech: MiniMax Speech 2.8 HD and Turbo, ElevenLabs Multilingual v2, v3 and Turbo v2.5<br>`speech-2.8-hd`, `speech-2.8-turbo`, `eleven-multilingual-v2`, `eleven-v3`, `eleven-turbo-v2.5` | [Text-to-speech](/docs/api-pixverse-v2/post-pixverse-speech-create) | More than 300 voices, 30 to 40 languages per model, emotion control, audio tags on v3 | | Effects | Video from [more than 900 effect templates](/docs/api-pixverse-v2/get-pixverse-videos-effects) and your images | 1 to 5 images per template | | More | [Transition](/docs/api-pixverse-v2/post-pixverse-videos-create-frames-v4) from a first to a last frame, [multi-frame transitions](/docs/api-pixverse-v2/post-pixverse-videos-create-transition) through up to 7 frames, [modify](/docs/api-pixverse-v2/post-pixverse-videos-modify) a video with a prompt, [extend](/docs/api-pixverse-v2/post-pixverse-videos-extend-v4) and [lip-sync](/docs/api-pixverse-v2/post-pixverse-videos-lipsync) to audio or text-to-speech | Multi-frame on V5, modify on V5.5, lip-sync on V5 with audio up to 60 seconds | [Model capabilities](/docs/api-pixverse-v2/model-capabilities) lists each model's durations, resolutions, aspect ratios and references. Sora 2 is no longer available: OpenAI shut it down on September 24, 2026. ## MCP server The hosted [PixVerse MCP server](/docs/api-pixverse-v2/mcp) gives the Claude app, ChatGPT, Claude Code, Cursor, VS Code and other AI assistants 38 tools for videos, effects, images, music, music videos, speech, upscales, uploads and running jobs, with your useapi.net API token and nothing to install. It is listed in the official MCP Registry as `net.useapi/pixverse`. The [pixverse-api](https://github.com/useapi/pixverse-api) repo also adds it in one step as a [Claude Code plugin](https://github.com/useapi/pixverse-api#use-with-claude-code) or a [Gemini CLI extension](https://github.com/useapi/pixverse-api#use-with-gemini-cli). ## Pricing What one video or image costs on [PixVerse's developer API](https://docs.platform.pixverse.ai/pixverse-api-pricing-2394995m0) and on each PixVerse subscription (as of November 2026). Each subscription comes with a monthly number of credits, and each video or image uses a set number of them, so it costs its share of the subscription. | Model | [Official API](https://docs.platform.pixverse.ai/pixverse-api-pricing-2394995m0) | Ultra $199/m (30,000 cr/mo) | Premium $60/m (15,000 cr/mo) | Pro $30/m (6,000 cr/mo) | |---|---|---|---|---| | PixVerse V6 (720p with sound, 5 s) | $0.27 ($0.053 a second) | $0.33 / 50 cr (600 videos/mo) | $0.20 / 50 cr (300 videos/mo) | $0.25 / 50 cr (120 videos/mo) | | PixVerse V6 (1080p with sound, 5 s) | $0.51 ($0.102 a second) | $0.66 / 100 cr (300 videos/mo) | $0.40 / 100 cr (150 videos/mo) | $0.50 / 100 cr (60 videos/mo) | | PixVerse V6 Off-Peak (1080p with sound, 5 s) | no Off-Peak | $0 / 0 cr (free, no monthly cap) | $0.20 / 50 cr (300 videos/mo) | $0.35 / 70 cr (85 videos/mo) | | PixVerse C1 (1080p with sound, 5 s) | $0.53 ($0.107 a second) | $0.66 / 100 cr (300 videos/mo) | $0.40 / 100 cr (150 videos/mo) | $0.50 / 100 cr (60 videos/mo) | | Seedance 2.5 (1080p, 5 s) | not sold | $3.10 / 468 cr (64 videos/mo) | $3.40 / 850 cr (17 videos/mo) | $4.25 / 850 cr (7 videos/mo) | | Seedance 2.0 (1080p, 5 s) | not sold | $1.49 / 225 cr (133 videos/mo) | $1.80 / 450 cr (33 videos/mo) | $2.25 / 450 cr (13 videos/mo) | | Kling 4.0 (1080p with sound, 5 s) | not sold | $0.50 / 75 cr (400 videos/mo) | $1.50 / 375 cr (40 videos/mo) | $1.88 / 375 cr (16 videos/mo) | | Kling O3 (Pro tier, 5 s) | not sold | $0.70 / 105 cr (285 videos/mo) | $0.70 / 175 cr (85 videos/mo) | $0.88 / 175 cr (34 videos/mo) | | Veo 3.1 Fast (1080p with sound, 8 s) | not sold | $1.27 / 192 cr (156 videos/mo) | $1.92 / 480 cr (31 videos/mo) | $2.40 / 480 cr (12 videos/mo) | | MiniMax H3 (768p with sound, 5 s) | not sold | $0 / 0 cr (free) | $0 / 0 cr (free) | $0.75 / 150 cr (40 videos/mo) | | Music video (720p, 1 minute of song) | $4.00 ($0.067 a second) | $3.98 / 600 cr (50 min of song/mo) | $2.40 / 600 cr (25 min of song/mo) | $3.00 / 600 cr (10 min of song/mo) | | Nano Banana Pro (1080p image) | not sold | $0 / 0 cr (free in Relax Mode) | $0.20 / 50 cr (300 images/mo) | $0.25 / 50 cr (120 images/mo) | | Nano Banana 2 (1080p image) | not sold | $0 / 0 cr (free in Relax Mode) | $0 / 0 cr (free in Relax Mode) | $0.13 / 25 cr (240 images/mo) | | GPT Image 2.5 Flare (1080p image, medium detail) | not sold | $0 / 0 cr (free in Relax Mode) | $0.02 / 5 cr (3,000 images/mo) | $0.03 / 5 cr (1,200 images/mo) | | Nano Banana 2 Lite (1080p image) | not sold | $0 / 0 cr (free in Relax Mode) | $0 / 0 cr (free in Relax Mode) | $0 / 0 cr (free in Relax Mode) | | Qwen Image (720p or 1080p image) | not sold | $0 / 0 cr (free in Relax Mode) | $0 / 0 cr (free in Relax Mode) | $0 / 0 cr (free in Relax Mode) | The third-party video prices above include PixVerse's discount for each model on each plan, which applies unless the request sends `relax_mode: false`. The discounts are PixVerse promotions that change without notice. With `relax_mode: false` these videos cost the full price: | Model | Ultra $199/m (relax_mode: false, full price) | Premium $60/m (relax_mode: false, full price) | |---|---|---| | Seedance 2.5 (1080p, 5 s) | $5.64 / 850 cr (35 videos/mo) | same as above | | Seedance 2.0 (1080p, 5 s) | $2.99 / 450 cr (66 videos/mo) | same as above | | Kling 4.0 (1080p with sound, 5 s) | $2.49 / 375 cr (80 videos/mo) | same as above | | Kling O3 (Pro tier, 5 s) | $1.16 / 175 cr (171 videos/mo) | same as above | | Veo 3.1 Fast (1080p with sound, 8 s) | $3.18 / 480 cr (62 videos/mo) | same as above | | MiniMax H3 (768p with sound, 5 s) | $1.00 / 150 cr (200 videos/mo) | $0.60 / 150 cr (100 videos/mo) | Every discount, by plan and model, is listed under [`relax_mode`](/docs/api-pixverse-v2/post-pixverse-videos-create-v4#parameters). Pro has none on these models. - A free Basic account gets 60 credits to start and 30 a day, for the PixVerse models up to 540p, and paid plans get 60 a day on top of their monthly credits. Standard ($10 a month, 1,200 credits) goes up to 720p and adds Nano Banana 2.1 and the GPT Image 2.5 pair. Every third-party video model needs Pro or higher. - Relax Mode images cost 0 credits: Qwen Image and Nano Banana 2 Lite on Pro, plus Nano Banana, Nano Banana 2, Nano Banana 2.1 and Seedream 4.0 on Premium, and all 15 image models on Ultra. Past a few hundred images per model a day, PixVerse moves the account to a [slow queue](#free-images-relax-mode). - Off-Peak mode takes 30% off on Pro and 50% on Premium and is free on Ultra, for the PixVerse models, with results usually within 24 hours. Preview mode takes 20% off on every paid plan. PixVerse's developer API has neither. - Kling 4.0 costs 50 credits a second at 720p and 75 at 1080p, with 80% off on Ultra. - With its discounts, Ultra is the cheapest plan for most third-party video. Premium stays cheaper on the models Ultra takes only 20% off. Premium also makes MiniMax H3 and Wan 3.0 free and takes 30% off Seedance 2.0 Fast and Mini, and Pro takes 10% off those two. - Billed yearly, the same credits cost 20% less on Standard, Pro and Premium and 25% less on Ultra ($149 a month). Team Ultra costs $199 a seat, with Ultra's credits and discounts, 12 concurrent generations and a shared workspace. - [Music videos](/docs/api-pixverse-v2/post-pixverse-music-video-create) cost 10 credits a second of song at 720p and 15 at 1080p, or 20 and 40 in storytelling mode (PixVerse's developer API has no storytelling mode). The first one on every account is free, at any length and in 1080p, even on a free Basic plan. - Upscale, music, music videos, speech and every other model and quality are in the calculator below. <details markdown="block" class="calc-details"> <summary>Cost calculator for every model and subscription</summary> <div class="calc" id="interactive-calculator" markdown="0"> <div class="calc-head"><label for="cc-plan" class="calc-label">PixVerse subscription</label><span class="calc-sep" aria-hidden="true">·</span><a class="calc-link" href="https://app.pixverse.ai/subscribe">current prices and offers</a></div> <select id="cc-plan" class="calc-select"> <optgroup label="Monthly"> <option value="ultra-m" data-plan="ultra" data-rate="0.0066333">Ultra · $199/mo · 30,000 credits · $0.0066/credit · free Off-Peak</option> <option value="premium-m" data-plan="premium" data-rate="0.004" selected>Premium · $60/mo · 15,000 credits · $0.0040/credit</option> <option value="pro-m" data-plan="pro" data-rate="0.005">Pro · $30/mo · 6,000 credits · $0.0050/credit</option> </optgroup> <optgroup label="Yearly, price per month"> <option value="ultra-y" data-plan="ultra" data-rate="0.0049667">Ultra yearly · $149/mo · 30,000 credits · $0.0050/credit · free Off-Peak</option> <option value="premium-y" data-plan="premium" data-rate="0.0032">Premium yearly · $48/mo · 15,000 credits · $0.0032/credit</option> <option value="pro-y" data-plan="pro" data-rate="0.004">Pro yearly · $24/mo · 6,000 credits · $0.0040/credit</option> </optgroup> </select> <div class="calc-fields"> <div> <label for="cc-kind" class="calc-label">Type</label> <select id="cc-kind" class="calc-select"> <option value="video">Video</option> <option value="image">Image</option> <option value="music">Music</option> <option value="musicvideo">Music video</option> <option value="speech">Speech</option> </select> </div> <div> <label for="cc-model" class="calc-label">Model</label> <select id="cc-model" class="calc-select"></select> </div> <div id="cc-quality-row"> <label for="cc-quality" class="calc-label">Quality</label> <select id="cc-quality" class="calc-select"></select> </div> <div id="cc-duration-row"> <label for="cc-duration" class="calc-label">Duration (s)</label> <select id="cc-duration" class="calc-select"></select> </div> <div id="cc-chars-row" style="display:none;"> <label for="cc-chars" class="calc-label">Characters</label> <input id="cc-chars" type="number" min="1" value="1000"> </div> </div> <div class="calc-flags" id="cc-flags"></div> <table class="calc-plan calc-result"> <thead><tr><th>Cost on the selected subscription</th></tr></thead> <tbody><tr><td id="cc-result">—</td></tr></tbody> </table> </div> <script> (function(){ var PV={'360p':1,'540p':1.5,'720p':2,'1080p':4}; var VIDEO={ 'v6':{base:4,qm:PV,audio:1.25,multishot:1,dur:[1,15]}, 'v5.6':{base:4,qm:PV,audio:1.25,dur:[1,10]}, 'v5.5':{base:4,qm:PV,audio:1.25,dur:[1,10]}, 'v5':{base:4,qm:PV,autoSound:1,autoSpeech:4,dur:[1,10],v5Legacy:true}, 'v5-fast':{base:3,qm:PV,autoSound:1,autoSpeech:4,dur:[1,10],v5Legacy:true}, 'pixverse-c1':{base:4,qm:PV,audio:1.25,dur:[1,15]}, 'seedance-2.5':{flatByQuality:{'480p':{base:35},'720p':{base:75},'1080p':{base:170},'2160p':{base:286}},refVideo:{'480p':21,'720p':45,'1080p':102,'2160p':176},dur:[4,30]}, 'seedance-2.5-flash':{flatByQuality:{'480p':{base:21},'720p':{base:48}},refVideo:{'480p':13,'720p':29},dur:[4,30]}, 'seedance-2.5-draft':{flatByQuality:{'480p':{base:35}},refVideo:{'480p':21},dur:[4,30]}, 'seedance-2.5-draft final':{flatByQuality:{'1080p':{base:170},'2160p':{base:286}},dur:[4,30],relaxAs:'seedance-2.5'}, 'seedance-2.0':{flatByQuality:{'480p':{base:20},'720p':{base:45},'1080p':{base:90},'2160p':{base:200}},dur:[4,15]}, 'seedance-2.0-fast':{flatByQuality:{'480p':{base:15},'720p':{base:30}},dur:[4,15]}, 'seedance-2.0-mini':{flatByQuality:{'480p':{base:8},'720p':{base:18}},dur:[4,15]}, 'minimax-h3':{flatByQuality:{'768p':{base:30},'1440p':{base:45}},dur:[5,15],fusionImageSurcharge:{over:5,each:10}}, 'minimax-h3-max':{flatByQuality:{'480p':{base:15},'768p':{base:30},'1080p':{base:60}},dur:[5,15],fusionImageSurcharge:{over:2,each:20}}, 'kling-4.0':{flatByQuality:{'720p':{base:50},'1080p':{base:75}},refVideo:{'720p':30,'1080p':45},refVideoMinMult:2,dur:[3,30]}, 'kling-v3':{flatByQuality:{'720p':{base:20,label:'Std'},'1080p':{base:25,label:'Pro'},'2160p':{base:120,label:'4K',audio:1}},audio:1.4,dur:[3,15]}, 'kling-o3':{flatByQuality:{'720p':{base:25,label:'Std'},'1080p':{base:35,label:'Pro'},'2160p':{base:120,label:'4K',audio:1}},audio:1.4,dur:[3,15]}, 'grok-imagine':{base:10,qm:{'480p':1,'720p':1.5},dur:[1,15]}, 'grok-imagine-1.5':{base:20,qm:{'480p':1,'720p':2},dur:[1,15]}, 'gemini-omni-flash':{base:40,qm:{'720p':1},dur:[3,10]}, 'veo-3.1-lite':{base:15,qm:{'720p':1,'1080p':2},durEnum:[4,6,8],durByQuality:{'1080p':[8]}}, 'veo-3.1-fast':{base:30,qm:{'720p':1,'1080p':1,'2160p':3},audio:2,audioForced:true,durEnum:[4,6,8],durByQuality:{'1080p':[8]}}, 'veo-3.1-standard':{base:80,qm:{'720p':1,'1080p':1,'2160p':3},audio:2,audioForced:true,durEnum:[4,6,8],durByQuality:{'1080p':[8]}}, 'happyhorse-1.0':{base:30,qm:{'720p':1,'1080p':2},dur:[3,15]}, 'flux-3.0':{base:55,qm:{'720p':1,'1080p':1.7},dur:[5,20]}, 'wan-3.0':{flatByQuality:{'480p':{base:15},'720p':{base:30},'1080p':{base:60}},dur:[2,30]} }; var IMAGE={ 'qwen-image':{'720p':5,'1080p':10}, 'nano-banana':{'1080p':15}, 'nano-banana-2':{'512p':16,'1080p':25,'1440p':40,'2160p':60}, 'nano-banana-2.1':{'1080p':10,'1440p':25,'2160p':35}, 'nano-banana-2-lite':{'1080p':6}, 'nano-banana-pro':{'1080p':50,'1440p':50,'2160p':90}, 'seedream-4.0':{'1080p':10,'1440p':10,'2160p':10}, 'seedream-4.5':{'1440p':10,'2160p':10}, 'seedream-5.0-pro':{'1080p':15,'1440p':30}, 'seedream-5.0-lite':{'1440p':12,'1800p':15,'2160p':18}, 'kling-3.0':{'1080p':10,'1440p':10}, 'kling-o3':{'1080p':10,'1440p':10,'2160p':20}, 'gpt-image-2.0':{'1080p':15,'1440p':30,'2160p':45}, 'gpt-image-2.5-flare':{'1080p':5,'1440p':6,'2160p':10}, 'gpt-image-2.5-sunburst':{'1080p':5,'1440p':6,'2160p':10} }; var IMAGE_DETAIL_MULT={'gpt-image-2.0':{'low':1,'medium':2,'high':4}}; var G25={'1080p':{'low':5,'medium':5,'high':15,'xhigh':20,'max':50}, '1440p':{'low':6,'medium':6,'high':20,'xhigh':35,'max':80}, '2160p':{'low':7,'medium':10,'high':35,'xhigh':65,'max':145}}; var IMAGE_DETAIL_ABS={'gpt-image-2.5-flare':G25,'gpt-image-2.5-sunburst':G25}; var IMAGE_REF_SURCHARGE={'gpt-image-2.5-flare':{each:5,max:16},'gpt-image-2.5-sunburst':{each:5,max:16}}; var EXT_PROMO={pro:{},premium:{},ultra:{}}; var PROMO_ONLY_AT={}; var RELAX_PROMO={ pro:{'seedance-2.0-fast':0.9,'seedance-2.0-mini':0.9}, premium:{'minimax-h3':0,'wan-3.0':0,'seedance-2.0-fast':0.7,'seedance-2.0-mini':0.7}, ultra:{'minimax-h3':0,'wan-3.0':0,'seedance-2.0-fast':0.1,'seedance-2.0-mini':0.1,'kling-4.0':0.2,'gemini-omni-flash':0.3,'veo-3.1-lite':0.4,'veo-3.1-standard':0.4,'veo-3.1-fast':0.4,'flux-3.0':0.5,'seedance-2.0':0.5,'seedance-2.5':0.55,'minimax-h3-max':0.55,'kling-o3':0.6,'grok-imagine-1.5':0.6,'happyhorse-1.0':0.6,'kling-v3':0.8,'grok-imagine':0.8,'seedance-2.5-flash':0.8,'seedance-2.5-draft':0.8} }; var FREE_IMAGES={ pro:{'qwen-image':1,'nano-banana-2-lite':1}, premium:{'qwen-image':1,'nano-banana-2-lite':1,'nano-banana':1,'nano-banana-2':1,'nano-banana-2.1':1,'seedream-4.0':1}, ultra:{'qwen-image':1,'nano-banana-2-lite':1,'nano-banana':1,'nano-banana-2':1,'nano-banana-pro':1,'seedream-4.0':1,'seedream-4.5':1,'seedream-5.0-pro':1,'seedream-5.0-lite':1,'kling-3.0':1,'kling-o3':1,'gpt-image-2.0':1,'gpt-image-2.5-flare':1,'gpt-image-2.5-sunburst':1,'nano-banana-2.1':1} }; var MUSIC={'music-2.6':40,'music-v1':150,'lyria-3-pro-preview':20}; var MV={'performance':{'720p':10,'1080p':15},'expressive':{'720p':10,'1080p':15},'storytelling':{'720p':20,'1080p':40}}; var MV_DUR=[10,15,20,30,45,60,90,120,150,180,240,300,360]; var SPEECH={'speech-2.8-hd':50,'speech-2.8-turbo':100,'eleven-multilingual-v2':50,'eleven-v3':50,'eleven-turbo-v2.5':100}; var $=function(id){return document.getElementById(id);}; function planOpt(){return plan.options[plan.selectedIndex];} function planRate(){return +planOpt().getAttribute('data-rate');} var kSel=$('cc-kind'),mSel=$('cc-model'),qSel=$('cc-quality'),qRow=$('cc-quality-row'),dInp=$('cc-duration'),dRow=$('cc-duration-row'),flags=$('cc-flags'),charsRow=$('cc-chars-row'),charsInp=$('cc-chars'),plan=$('cc-plan'),out=$('cc-result'); function clear(el){while(el.firstChild)el.removeChild(el.firstChild);} function chk(id){var e=$(id);return e?e.checked:false;} function renderModels(){ var k=kSel.value; clear(mSel); var keys=Object.keys(k==='music'?MUSIC:k==='speech'?SPEECH:k==='image'?IMAGE:k==='musicvideo'?MV:VIDEO); keys.forEach(function(k){var o=document.createElement('option');o.value=k;o.textContent=k;mSel.appendChild(o);}); mSel.value=keys[0]; } function renderQualities(){ var k=kSel.value; if(k==='music'||k==='speech'){qRow.style.display='none';clear(qSel);return;} qRow.style.display=''; if(k==='musicvideo'){clear(qSel);Object.keys(MV[mSel.value]).forEach(function(q){var o=document.createElement('option');o.value=q;o.textContent=q;qSel.appendChild(o);});return;} var isImg=k==='image'; var src=isImg?IMAGE[mSel.value]:VIDEO[mSel.value]; clear(qSel); var qs=isImg?Object.keys(src):(src.qm?Object.keys(src.qm):Object.keys(src.flatByQuality)); qs.forEach(function(q){ var o=document.createElement('option');o.value=q; o.textContent=(!isImg&&src.flatByQuality&&src.flatByQuality[q].label)?(q+' ('+src.flatByQuality[q].label+')'):q; qSel.appendChild(o); }); } function renderDurationAndFlags(){ var k=kSel.value; var prevRelax=$('cc-relax')?$('cc-relax').value:''; charsRow.style.display=(k==='speech')?'':'none'; if(k==='music'||k==='speech'){dRow.style.display='none';clear(flags);return;} if(k==='musicvideo'){ var prevD=+dInp.value,prevF=chk('cc-mvfree'); dRow.style.display='';clear(dInp);clear(flags); MV_DUR.forEach(function(v){var o=document.createElement('option');o.value=v;o.textContent=v+' ('+Math.floor(v/60)+':'+('0'+v%60).slice(-2)+')';dInp.appendChild(o);}); dInp.value=MV_DUR.indexOf(prevD)>=0?prevD:60; var fw=document.createElement('label');fw.style.fontWeight='400';fw.style.minWidth='auto'; var fc=document.createElement('input');fc.type='checkbox';fc.id='cc-mvfree';fc.checked=prevF;fc.addEventListener('change',compute); fw.appendChild(fc);fw.appendChild(document.createTextNode(' first music video on the account (free, any length, 1080p too)')); flags.appendChild(fw); return; } var isImg=k==='image'; dRow.style.display=isImg?'none':''; clear(flags); if(isImg){ var abs=IMAGE_DETAIL_ABS[mSel.value]; var dm=abs?abs[qSel.value]:IMAGE_DETAIL_MULT[mSel.value]; if(dm){ var w=document.createElement('label');w.style.fontWeight='400';w.style.minWidth='auto'; w.appendChild(document.createTextNode('detail_level: ')); var sel=document.createElement('select');sel.id='cc-detail'; Object.keys(dm).forEach(function(d){ var o=document.createElement('option');o.value=d;o.textContent=d;sel.appendChild(o); }); sel.value='medium'; sel.addEventListener('change',compute); w.appendChild(sel);flags.appendChild(w); } var rs=IMAGE_REF_SURCHARGE[mSel.value]; if(rs){ var iw2=document.createElement('label');iw2.style.fontWeight='400';iw2.style.minWidth='auto'; iw2.appendChild(document.createTextNode('reference images (+'+rs.each+' credits each): ')); var ii2=document.createElement('input');ii2.type='number';ii2.id='cc-imgrefs';ii2.min='0';ii2.max=String(rs.max);ii2.step='1';ii2.value='0';ii2.style.width='4.5em'; ii2.addEventListener('change',compute);ii2.addEventListener('input',compute); iw2.appendChild(ii2);flags.appendChild(iw2); } return; } var m=VIDEO[mSel.value]; clear(dInp); var values=[]; if(m.durByQuality&&m.durByQuality[qSel.value]){values=m.durByQuality[qSel.value].slice();} else if(m.durEnum){values=m.durEnum.slice();} else{for(var i=m.dur[0];i<=m.dur[1];i++)values.push(i);} values.forEach(function(v){var o=document.createElement('option');o.value=v;o.textContent=v;dInp.appendChild(o);}); dInp.value=values[0]; function add(id,label,checked){ var w=document.createElement('label');w.style.fontWeight='400';w.style.minWidth='auto'; var cb=document.createElement('input');cb.type='checkbox';cb.id=id;cb.checked=checked; cb.addEventListener('change',compute); w.appendChild(cb);w.appendChild(document.createTextNode(' '+label)); flags.appendChild(w); } if(m.audio&&!m.audioForced&&!m.v5Legacy)add('cc-audio','audio',true); if(m.audioForced){var n=document.createElement('span');n.textContent='audio: always on';n.style.color='#888';flags.appendChild(n);} if(m.v5Legacy){add('cc-autosound','auto_sound',false);add('cc-autospeech','auto_speech',false);} if(m.qm===PV){ add('cc-offpeak','off_peak_mode (PixVerse native models)',false); add('cc-preview','preview_mode (PixVerse native models, 20% off)',false); }else if(!m.v5Legacy){ var xw=document.createElement('label');xw.style.fontWeight='400';xw.style.minWidth='auto'; xw.appendChild(document.createTextNode('relax_mode: ')); var xs=document.createElement('select');xs.id='cc-relax'; [['','left out (default, discounted)'],['true','true (same price, Relax Mode)'],['false','false (full price)']].forEach(function(p){var o=document.createElement('option');o.value=p[0];o.textContent=p[1];xs.appendChild(o);}); xs.value=prevRelax; xs.addEventListener('change',compute); xw.appendChild(xs);flags.appendChild(xw); var xn=document.createElement('span');xn.id='cc-relax-note';xn.style.color='#888';flags.appendChild(xn); } if(m.fusionImageSurcharge){ var iw=document.createElement('label');iw.style.fontWeight='400';iw.style.minWidth='auto'; iw.appendChild(document.createTextNode('fusion reference images (0 = none): ')); var ii=document.createElement('input');ii.type='number';ii.id='cc-refimg';ii.min='0';ii.max='9';ii.step='1';ii.value='0';ii.style.width='4.5em'; ii.addEventListener('change',compute);ii.addEventListener('input',compute); iw.appendChild(ii);flags.appendChild(iw); } if(m.refVideo){ var rw=document.createElement('label');rw.style.fontWeight='400';rw.style.minWidth='auto'; rw.appendChild(document.createTextNode('fusion reference video, total seconds (0 = none): ')); var ri=document.createElement('input');ri.type='number';ri.id='cc-refvid';ri.min='0';ri.max='30';ri.step='1';ri.value='0';ri.style.width='4.5em'; ri.addEventListener('change',compute);ri.addEventListener('input',compute); rw.appendChild(ri);flags.appendChild(rw); } } function compute(){ if(kSel.value==='musicvideo'){ var rate=(MV[mSel.value]||{})[qSel.value]||0; var secs=+dInp.value||60; var vc=chk('cc-mvfree')?0:rate*secs; var vd=vc*planRate(); clear(out); var vb=document.createElement('b');vb.textContent='$'+vd.toFixed(3);out.appendChild(vb); out.appendChild(document.createTextNode(' · ')); var vs=document.createElement('span');vs.textContent=vc+' credits ('+rate+' credits/s x '+secs+' s of song)';vs.style.color='#555';out.appendChild(vs); return; } if(kSel.value==='music'){ var mc=MUSIC[mSel.value]||0; var md=mc*planRate(); clear(out); var mb=document.createElement('b');mb.textContent='$'+md.toFixed(3);out.appendChild(mb); out.appendChild(document.createTextNode(' · ')); var ms=document.createElement('span');ms.textContent=mc+' credits / track';ms.style.color='#555';out.appendChild(ms); return; } if(kSel.value==='speech'){ var n=SPEECH[mSel.value]||50; var chars=Math.max(1,+charsInp.value||0); var scr=Math.ceil(chars/n); var sd=scr*planRate(); clear(out); var sb=document.createElement('b');sb.textContent='$'+sd.toFixed(3);out.appendChild(sb); out.appendChild(document.createTextNode(' · ')); var ss=document.createElement('span');ss.textContent=scr+' credits / '+chars+' chars';ss.style.color='#555';out.appendChild(ss); return; } var isImg=kSel.value==='image'; var credits=0; var planKey=planOpt().getAttribute('data-plan'); if(isImg){ var basePrice=(IMAGE[mSel.value]||{})[qSel.value]||0; var dl=$('cc-detail')?$('cc-detail').value:'medium'; var abs=IMAGE_DETAIL_ABS[mSel.value]; if(abs){ basePrice=(abs[qSel.value]||{})[dl]||basePrice; }else{ var dm=IMAGE_DETAIL_MULT[mSel.value]; if(dm)basePrice*=dm[dl]||1; } var rs=IMAGE_REF_SURCHARGE[mSel.value]; if(rs){ var nr=$('cc-imgrefs')?Math.max(0,+$('cc-imgrefs').value||0):0; basePrice+=nr*rs.each; } credits=(FREE_IMAGES[planKey]||{})[mSel.value]?0:basePrice; }else{ var m=VIDEO[mSel.value],q=qSel.value,dur=+dInp.value||1; var base,qMult=1; if(m.flatByQuality){base=m.flatByQuality[q].base;} else{base=m.base;qMult=m.qm[q]||1;} var cost=base*qMult*dur; var rv=$('cc-refvid')?Math.max(0,+$('cc-refvid').value||0):0; if(m.refVideo&&rv>0){cost=(m.refVideo[q]||base*qMult)*Math.max(dur+rv,(m.refVideoMinMult||0)*dur);} if(m.fusionImageSurcharge){ var ni=$('cc-refimg')?Math.max(0,+$('cc-refimg').value||0):0; if(ni>m.fusionImageSurcharge.over)cost+=(ni-m.fusionImageSurcharge.over)*m.fusionImageSurcharge.each; } if(m.v5Legacy){ var add=0; if(chk('cc-autosound'))add+=1; if(chk('cc-autospeech'))add+=4; cost=(base*qMult+add)*dur; }else{ var aMult=m.audio; if(m.flatByQuality&&m.flatByQuality[q]&&m.flatByQuality[q].audio!==undefined)aMult=m.flatByQuality[q].audio; if(aMult){var audioOn=m.audioForced||chk('cc-audio');if(audioOn)cost*=aMult;} } var isNative=m.qm===PV; if(isNative){ if(chk('cc-preview'))cost*=0.8; if(chk('cc-offpeak'))cost*=(planKey==='ultra'?0:planKey==='pro'?0.7:0.5); }else{ var sp=(EXT_PROMO[planKey]||{})[mSel.value]; var pOnly=PROMO_ONLY_AT[mSel.value]; if(pOnly&&q!==pOnly)sp=0; var rp=(RELAX_PROMO[planKey]||{})[m.relaxAs||mSel.value]; var rm=$('cc-relax')?$('cc-relax').value:''; var useRelax=rp!==undefined&&rm!=='false'; cost*=sp?sp:(useRelax?rp:1); var xn2=$('cc-relax-note'); if(xn2){ var pn=planKey==='ultra'?'Ultra':planKey==='premium'?'Premium':'Pro'; var off=rp===0?'free':(rp!==undefined?Math.round((1-rp)*100)+'% off':''); xn2.textContent=rp===undefined?(pn+': no PixVerse discount on this model, full price'):(rm==='false'?pn+': full price with relax_mode false (by default '+off+')':pn+': '+off+' unless relax_mode is false'); } } credits=Math.ceil(cost); } var dollars=credits*planRate(); clear(out); var b1=document.createElement('b');b1.textContent='$'+dollars.toFixed(3);out.appendChild(b1); out.appendChild(document.createTextNode(' · ')); var b2=document.createElement('span');b2.textContent=credits+' credits';b2.style.color='#555';out.appendChild(b2); } kSel.addEventListener('change',function(){renderModels();renderQualities();renderDurationAndFlags();compute();}); mSel.addEventListener('change',function(){renderQualities();renderDurationAndFlags();compute();}); qSel.addEventListener('change',function(){renderDurationAndFlags();compute();}); dInp.addEventListener('change',compute); dInp.addEventListener('input',compute); charsInp.addEventListener('change',compute); charsInp.addEventListener('input',compute); plan.addEventListener('change',compute); renderModels();renderQualities();renderDurationAndFlags();compute(); })(); </script> #### Plans | Plan | Monthly | Yearly | Credits/mo | $/credit monthly | $/credit yearly | |:-----|:-----:|:-----:|:-----:|:-----:|:-----:| | Ultra | $199 | $1,788 | 30,000 | $0.00663 | $0.00497 | | Premium | $60 | $576 | 15,000 | $0.00400 | $0.00320 | | Pro | $30 | $288 | 6,000 | $0.00500 | $0.00400 | | Standard | $10 | $96 | 1,200 | $0.00833 | $0.00667 | The calculator carries Ultra, Premium and Pro, monthly and yearly. Team Ultra is priced like Ultra per seat and shares its credits, discounts and free image list, so select Ultra for it. Free (Basic) and Standard run only the PixVerse models, and a third-party model returns 412 on them, so Standard isn't in the calculator. Ultra's higher $/credit rate means a single PixVerse-model video costs more on Ultra than on Premium, unless you use more than Premium's monthly credits. The calculator applies every plan rule automatically. #### Third-party model discounts PixVerse discounts third-party video one model at a time, on each plan. The discount applies unless the request sends `relax_mode: false` on [POST videos/create](/docs/api-pixverse-v2/post-pixverse-videos-create-v4), create-frames, create-fusion or [create-final](/docs/api-pixverse-v2/post-pixverse-videos-create-final), which pays the full price, so the calculator applies it by default. `relax_mode: true` costs the same, and PixVerse records the video as made in its Relax Mode. | Models | Ultra | Premium | Pro | |:-----|:-----:|:-----:|:-----:| | `minimax-h3`, `wan-3.0` | free | free | — | | `seedance-2.0-fast`, `seedance-2.0-mini` | 90% off | 30% off | 10% off | | `kling-4.0` | 80% off | — | — | | `gemini-omni-flash` | 70% off | — | — | | `veo-3.1-lite`, `veo-3.1-standard`, `veo-3.1-fast` | 60% off | — | — | | `seedance-2.0`, `flux-3.0` | 50% off | — | — | | `seedance-2.5`, `minimax-h3-max` | 45% off | — | — | | `kling-o3`, `grok-imagine-1.5`, `happyhorse-1.0` | 40% off | — | — | | `kling-v3`, `grok-imagine`, `seedance-2.5-flash`, `seedance-2.5-draft` | 20% off | — | — | These are the discounts as of November 15, 2026. PixVerse raised most of them, and moved Ultra from 25,000 to 30,000 credits a month, between November 9 and 15, 2026. Until then Ultra's list read 40% off most models, and Premium's only the 30% off Seedance 2.0 Fast and Mini. PixVerse adds and removes these promotions without notice, so treat the calculator as current as of its last sync rather than contractual. #### Cost per second, in dollars Discounts are quoted as percentages off a credit rate, which makes plans hard to compare. This is the same thing in money: the per-second cost of one video at the plan's monthly $/credit, with each plan's discount (the default), and on Ultra also at the full price that `relax_mode: false` pays. Multiply by your duration. | Model | Quality | Credits/sec | Ultra | Premium | Pro | Ultra, `relax_mode: false` | |:-----|:-----:|:-----:|:-----:|:-----:|:-----:|:-----:| | `seedance-2.5` | 480p | 35 | $0.128 | $0.140 | $0.175 | $0.232 | | `seedance-2.5` | 720p | 75 | $0.274 | $0.300 | $0.375 | $0.498 | | `seedance-2.5` | 1080p | 170 | $0.620 | $0.680 | $0.850 | $1.128 | | `seedance-2.5` | 2160p | 286 | $1.043 | $1.144 | $1.430 | $1.897 | | `seedance-2.5-flash` | 480p | 21 | $0.111 | $0.084 | $0.105 | $0.139 | | `seedance-2.5-flash` | 720p | 48 | $0.255 | $0.192 | $0.240 | $0.318 | | `seedance-2.5-draft` | 480p | 35 | $0.186 | $0.140 | $0.175 | $0.232 | | `seedance-2.0` | 480p | 20 | $0.066 | $0.080 | $0.100 | $0.133 | | `seedance-2.0` | 720p | 45 | $0.149 | $0.180 | $0.225 | $0.299 | | `seedance-2.0` | 1080p | 90 | $0.299 | $0.360 | $0.450 | $0.597 | | `seedance-2.0` | 2160p | 200 | $0.663 | $0.800 | $1.000 | $1.327 | | `seedance-2.0-fast` | 480p | 15 | $0.010 | $0.042 | $0.068 | $0.100 | | `seedance-2.0-fast` | 720p | 30 | $0.020 | $0.084 | $0.135 | $0.199 | | `seedance-2.0-mini` | 480p | 8 | $0.005 | $0.022 | $0.036 | $0.053 | | `seedance-2.0-mini` | 720p | 18 | $0.012 | $0.050 | $0.081 | $0.119 | | `minimax-h3` | 768p | 30 | $0.000 | $0.000 | $0.150 | $0.199 | | `minimax-h3` | 1440p *(2K)* | 45 | $0.000 | $0.000 | $0.225 | $0.299 | | `minimax-h3-max` | 480p | 15 | $0.055 | $0.060 | $0.075 | $0.100 | | `minimax-h3-max` | 768p | 30 | $0.109 | $0.120 | $0.150 | $0.199 | | `minimax-h3-max` | 1080p | 60 | $0.219 | $0.240 | $0.300 | $0.398 | | `wan-3.0` | 480p | 15 | $0.000 | $0.000 | $0.075 | $0.100 | | `wan-3.0` | 720p | 30 | $0.000 | $0.000 | $0.150 | $0.199 | | `wan-3.0` | 1080p | 60 | $0.000 | $0.000 | $0.300 | $0.398 | | `flux-3.0` | 720p | 55 | $0.182 | $0.220 | $0.275 | $0.365 | | `flux-3.0` | 1080p | 93.5 | $0.310 | $0.374 | $0.468 | $0.620 | | `kling-4.0` | 720p | 50 | $0.066 | $0.200 | $0.250 | $0.332 | | `kling-4.0` | 1080p | 75 | $0.100 | $0.300 | $0.375 | $0.498 | | `kling-v3` | 720p *(Std)* | 20 | $0.106 | $0.080 | $0.100 | $0.133 | | `kling-v3` | 1080p *(Pro)* | 25 | $0.133 | $0.100 | $0.125 | $0.166 | | `kling-v3` | 2160p *(4K)* | 120 | $0.637 | $0.480 | $0.600 | $0.796 | | `kling-o3` | 720p *(Std)* | 25 | $0.100 | $0.100 | $0.125 | $0.166 | | `kling-o3` | 1080p *(Pro)* | 35 | $0.139 | $0.140 | $0.175 | $0.232 | | `kling-o3` | 2160p *(4K)* | 120 | $0.478 | $0.480 | $0.600 | $0.796 | | `grok-imagine` | 480p | 10 | $0.053 | $0.040 | $0.050 | $0.066 | | `grok-imagine` | 720p | 15 | $0.080 | $0.060 | $0.075 | $0.100 | | `grok-imagine-1.5` | 480p | 20 | $0.080 | $0.080 | $0.100 | $0.133 | | `grok-imagine-1.5` | 720p | 40 | $0.159 | $0.160 | $0.200 | $0.265 | | `gemini-omni-flash` | 720p | 40 | $0.080 | $0.160 | $0.200 | $0.265 | | `veo-3.1-lite` | 720p | 15 | $0.040 | $0.060 | $0.075 | $0.100 | | `veo-3.1-lite` | 1080p | 30 | $0.080 | $0.120 | $0.150 | $0.199 | | `veo-3.1-fast` | 720p | 60 | $0.159 | $0.240 | $0.300 | $0.398 | | `veo-3.1-fast` | 1080p | 60 | $0.159 | $0.240 | $0.300 | $0.398 | | `veo-3.1-fast` | 2160p | 180 | $0.478 | $0.720 | $0.900 | $1.194 | | `veo-3.1-standard` | 720p | 160 | $0.425 | $0.640 | $0.800 | $1.061 | | `veo-3.1-standard` | 1080p | 160 | $0.425 | $0.640 | $0.800 | $1.061 | | `veo-3.1-standard` | 2160p | 480 | $1.274 | $1.920 | $2.400 | $3.184 | | `happyhorse-1.0` | 720p | 30 | $0.119 | $0.120 | $0.150 | $0.199 | | `happyhorse-1.0` | 1080p | 60 | $0.239 | $0.240 | $0.300 | $0.398 | With each plan's discount applied by default, Ultra is the cheapest plan on 40 of the 48 rows. It makes `minimax-h3` and `wan-3.0` free (so does Premium), and it beats Premium on every model it takes 40% or more off, though only by a fraction of a cent on `kling-o3`, `grok-imagine-1.5` and `happyhorse-1.0`. Premium, at $0.00400 a credit against $0.00500 on Pro and $0.00663 on Ultra at the full price, stays the cheapest on the other eight rows, `seedance-2.5-flash`, `seedance-2.5-draft`, `kling-v3` and `grok-imagine`, where Ultra's 20% off leaves $0.00531 a credit, above both Premium and Pro. With `relax_mode: false` every plan pays the full price, and Ultra's last column is then the most expensive on every row. Notes on the figures above: - Credits/sec is the list rate before any plan discount. - Rates are for monthly billing. Yearly billing is 20 to 25% cheaper per credit, so scale accordingly: Pro $0.00400, Premium $0.00320, Ultra $0.00497. - A [Seedance 2.5 draft](/docs/api-pixverse-v2/post-pixverse-videos-create-final) bills the `seedance-2.5-draft` row, and its final bills the `seedance-2.5` row at 1080p or 2160p, on the same duration. The calculator lists the final as `seedance-2.5-draft final`. - `kling-o3` and `kling-v3` add 40% when `audio` is enabled, at 720p and 1080p only. The 4K tier carries no audio surcharge. - `veo-3.1-standard` and `veo-3.1-fast` generate audio on every call and cannot disable it, so their surcharge is already included above. - `veo-3.1-lite`, `veo-3.1-standard` and `veo-3.1-fast` accept a `duration` of 4, 6 or 8 only, and at 1080p only 8. - `minimax-h3` fusion adds 10 credits per reference image above 5. A 5-second 1440p fusion is 225 credits with up to 5 images and 265 with 9. `minimax-h3-max` adds 20 per image above 2. A 5-second 480p fusion is 75 credits with 1 or 2 images and 215 with 9. They are the only video models with an image-count term. - `flux-3.0` and `wan-3.0` both expose an `audio` toggle, and neither charges for it. Their rates carry no audio term, unlike `kling-o3` and `kling-v3`. - `kling-4.0` bills 50 credits a second at 720p and 75 at 1080p in every mode, with sound and no audio surcharge. With a reference video in fusion it bills 30 or 45 a second on the longer of (reference length + output length) and twice the output length, so a 5-second 720p fusion with a 3-second clip is 30 × 10 = 300 credits. - `wan-3.0` bills one flat rate per quality in every mode. Fusion costs the same per second as text-to-video, with no reference-count or reference-duration term, which is what makes it much cheaper than Seedance fusion. - A video is rounded up to a whole credit once, at the end. Very short clips can therefore cost a fraction of a credit more than the per-second figure implies. Seedance fusion with a reference video is priced differently. Attaching one or more reference videos to [create-fusion](/docs/api-pixverse-v2/post-pixverse-videos-create-fusion) switches the rate to a lower per-second figure, but bills you for the output duration plus the total reference duration. For `seedance-2.5` that is 21 credits a second at 480p, 45 at 720p, 102 at 1080p and 176 at 2160p, against 35, 75, 170 and 286 without. `seedance-2.5-flash` bills 13 at 480p and 29 at 720p, against 21 and 48, and `seedance-2.5-draft` 21 against 35. A reference video therefore only saves credits while it runs shorter than about two-thirds of your output. On Pro a 4-second 480p `seedance-2.5` clip costs 140 credits alone, and 273 with 9 seconds of reference video attached. The calculator above has a field for this. #### Upscale [Video upscale](/docs/api-pixverse-v2/post-pixverse-videos-upscale) is billed per second of the source video, rounded up. [Image upscale](/docs/api-pixverse-v2/post-pixverse-images-upscale) is billed per image. Both endpoints return the exact price for free with `"quote": true`. | Model | Media | Quality | Credits | Premium | Pro | |:-----|:-----|:-----|:-----:|:-----:|:-----:| | `pixverse-upscale` | video | 4K | 6/sec | $0.024/sec | $0.030/sec | | `topaz-proteus` | video | 1080p | 6/sec | $0.024/sec | $0.030/sec | | `topaz-proteus` | video | 4K | 10/sec | $0.040/sec | $0.050/sec | | `topaz-starlight-fast` | video | 1080p | 10/sec | $0.040/sec | $0.050/sec | | `topaz-starlight-fast` | video | 4K | 15/sec | $0.060/sec | $0.075/sec | | `topaz-starlight-precise` | video | 1080p | 15/sec | $0.060/sec | $0.075/sec | | `topaz-starlight-precise` | video | 4K | 30/sec | $0.120/sec | $0.150/sec | | `pixverse-upscale` | image | 4K | 8 | $0.032 | $0.040 | | `topaz-gigapixel` | image | 1080p / 2K / 4K | 15 | $0.060 | $0.075 | These prices were observed on a Pro account. Whether Ultra pays less is not yet confirmed, so use `"quote": true` for your account's exact figure. A 3-minute video on `topaz-starlight-precise` at 4K is 5,400 credits. #### Free images (Relax Mode) | Plan | Free image models | |:-----|:-----| | Ultra | `qwen-image`, `nano-banana`, `nano-banana-2`, `nano-banana-2-lite`, `nano-banana-pro`, `seedream-4.0`, `seedream-4.5`, `seedream-5.0-lite`, `seedream-5.0-pro`, `kling-3.0`, `kling-o3`, `gpt-image-2.0`, `gpt-image-2.5-flare`, `gpt-image-2.5-sunburst`, `nano-banana-2.1` (all 15) | | Premium | `qwen-image`, `nano-banana`, `nano-banana-2`, `nano-banana-2.1`, `nano-banana-2-lite`, `seedream-4.0` | | Pro | `qwen-image`, `nano-banana-2-lite` | Relax Mode is unmetered, not unthrottled. These models cost zero credits on the listed plans and nothing rejects a request for being too frequent, but PixVerse applies a daily volume threshold. Past it the account is moved to a slow queue rather than refused — generations still succeed and still cost nothing, they just take far longer to come back. It is visible in the response, where `queue_data.slow_queue` turns `true`, `queue_data.reason` reads `daily_limit_exceeded`, and `queue_count` gives the number of tasks ahead. The threshold applies **per model**, not per account. An account throttled on one model keeps generating at full speed on every other one, and the busiest accounts clear 500–700 images a day across models combined. We have seen it engage on `nano-banana-2`, `nano-banana-pro` and `gpt-image-2.0`, most often on `nano-banana-2`. The point at which it engages is not fixed and varies between accounts, but as a rough guide expect a few hundred images per model per day — around 300 for `nano-banana-pro` and around 500 for `gpt-image-2.0`. We have not seen it on the remaining models, which does not mean they are unlimited, only that nobody has pushed them hard enough for it to show. The allowance resets at approximately 00:00 UTC, so a throttled account is clear again at the start of the next UTC day. PixVerse moves these thresholds without notice, so treat them as rough capacity guidance rather than a guarantee. Sustained volume needs more than one account, because each account carries its own allowance and [POST /videos/create](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) and [POST /images/create](/docs/api-pixverse-v2/post-pixverse-images-create) spread work across every account you have configured. Adding accounts alone is not a guarantee though — we have seen a multi-account pool throttled on the same model at the same time, because every account was working through the same daily allowance on the same model. Once a pool is in that state more accounts only buy one more allowance each, and none of them are fast. Falling back to another model is usually the better move, because the allowances are independent per model. An account wedged on `nano-banana-2` still generates on `nano-banana-pro`, `seedream-4.5` or `gpt-image-2.0` at full speed. Decide in advance which models are acceptable for your use case, watch for `queue_data.slow_queue` turning `true` on the [image](/docs/api-pixverse-v2/get-pixverse-images-image_id) or [video](/docs/api-pixverse-v2/get-pixverse-videos-video_id) response, and move down that list rather than waiting out the queue. </details> ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. ## Run several PixVerse accounts Video, image, music and speech requests don't need `email`: each job goes to one of your PixVerse accounts with a free slot, within the `maxJobs` limit you set for each account with [POST accounts/email](/docs/api-pixverse-v2/post-pixverse-accounts-email), up to the concurrent generations its plan allows (2 on Basic, 3 on Standard, 5 on Pro, 8 on Premium and Ultra, 12 on Team Ultra). When every account is busy you get `429`, so wait 10 to 30 seconds and send it again. Pass `email` to run a job on a specific account. A file uploaded through one account works from all of them, and each account has its own daily Relax Mode allowance for free images. Every generation request can send its result to your webhook with `replyUrl`, so you don't have to poll, and [GET scheduler](/docs/api-pixverse-v2/get-pixverse-scheduler) lists the jobs running now. Off-Peak jobs skip both and don't count toward `maxJobs`, so collect them with [GET videos](/docs/api-pixverse-v2/get-pixverse-videos). [How useapi.net works](/docs/how-it-works) has tips for keeping your accounts healthy. ## Questions ### Does PixVerse have an API? Through useapi.net, yes, and it runs on your PixVerse subscription, from video and images to music, speech, upscaling and more than 900 effects. PixVerse's own [developer API](https://docs.platform.pixverse.ai/billing-and-usage-2394984m0) bills separate API credits that a PixVerse subscription can't pay for, and PixVerse lists that API access from $100 (as of November 2026). [Setup PixVerse](/docs/start-here/setup-pixverse) connects your account. ### How much does the PixVerse API cost? Through useapi.net, PixVerse V6 at 1080p with sound costs $0.08 a second on Premium at $60 a month, $0.064 billed yearly and $0.04 in Off-Peak mode, against $0.102 on PixVerse's own [developer API](https://docs.platform.pixverse.ai/pixverse-api-pricing-2394995m0), which has no Off-Peak mode (as of November 2026). Off-Peak is free on Ultra. The [price table](#pricing) shows each model on each subscription. ### Do I need a PixVerse API key? Through useapi.net, no PixVerse developer key: you use a useapi.net [API token](/docs/start-here/setup-useapi) and connect your PixVerse account through [Setup PixVerse](/docs/start-here/setup-pixverse). Effects, motion control, upscaling, music and text-to-speech all run on the same subscription credits, and [GET videos/effects](/docs/api-pixverse-v2/get-pixverse-videos-effects) lists the effect templates. Examples are on GitHub at [useapi/pixverse-api](https://github.com/useapi/pixverse-api). ### Can the PixVerse API run Seedance 2.0 and Veo 3.1? Through useapi.net, yes, from the same call as PixVerse V6: [POST videos/create](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) runs 20 third-party video models, among them Seedance 2.5, 2.5 Flash and 2.0, Kling 4.0 and O3, Veo 3.1 and MiniMax H3. On Premium billed yearly, a 5-second 1080p video costs $1.44 on Seedance 2.0 and $2.72 on Seedance 2.5, or $1.12 and $2.32 on Ultra billed yearly, where PixVerse's discounts apply by default, against $1.87 and $2.84 on ByteDance's official API (as of November 2026). [Setup PixVerse](/docs/start-here/setup-pixverse) [LLM-friendly API spec](https://useapi.net/assets/aibot/api-pixverse-v2.txt) Feed this to your LLM to build integrations [Claude Code skill](/llm-tools) A drop-in useapi.net skill for Claude Code, and a rule for Cursor [Postman collection](https://www.postman.com/useapinet/useapi-net/collection/29112081-946e4e63-64de-4265-b388-6be967e9b061) (November 15, 2026) [MCP Server](/docs/api-pixverse-v2/mcp) Make PixVerse videos, images, music and speech from the Claude app, ChatGPT, Claude Code, Cursor and other MCP clients [GitHub examples](https://github.com/useapi/pixverse-api) Node.js: PixVerse video generation and music videos Articles: * [How to Generate AI Videos with the PixVerse API](/docs/articles/pixverse-demo) * [How to Make an AI Music Video from a Song with the PixVerse API](/docs/articles/pixverse-music-video-api) * [Sora 2 API Alternatives Compared, With Code: Seedance 2.5, Omni Flash, MiniMax H3, Kling v3](/docs/articles/sora-2-api-alternatives) * [Seedance 2.0 and 2.5 API Pricing: Every Route, Compared](/docs/articles/seedance-2-api-pricing) {% include lang-switch.html mode="hub" key="seedance-2-pricing" %} * [AI Music APIs Compared: Mureka vs MiniMax vs ElevenLabs vs Lyria 3 Pro](/docs/articles/ai-music-api-comparison) Examples: * [Seedance 2.0 omni: Mini vs Fast vs Standard, real faces with video and audio references](/blog/260626a) * [Text-to-Speech: MiniMax and ElevenLabs](/blog/260625) * [Music Generation: MiniMax, ElevenLabs, Lyria 3 Pro](/blog/260624) * [Grok Imagine 1.5 and Seedance 2.0 4K](/blog/260623) * [Motion Control](/blog/260513) * [HappyHorse 1.0](/blog/260504) * [PixVerse V6: Multi-Shot, 15s 1080p, Audio](/blog/260405) * [17 AI Image Models: The Showdown](/blog/260309i) * [PixVerse Images: Qwen Image, Nano Banana, 2 and Pro, Seedream 4.0, 4.5 and 5.0 Lite](/blog/260309) * [PixVerse v5.6](/blog/260127) * [PixVerse Modify](/blog/260126) * [PixVerse v5.5](/blog/251205) * [PixVerse v5](/blog/250829) Videos on YouTube: * [PixVerse v5 transition](https://www.youtube.com/watch?v=iphtkhFP9SQ) * [PixVerse effects and lip-sync with Mureka music](https://www.youtube.com/shorts/YxHh_FdCo9c) Developer Community: * <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> * <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> === URL: https://useapi.net/docs/api-pixverse-v2/del-pixverse-accounts-email === Document URL: https://useapi.net/docs/api-pixverse-v2/del-pixverse-accounts-email --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> accounts/`email` description: "Delete a previously configured PixVerse account by email address via DEL accounts/email in the useapi.net PixVerse API v2." parent: PixVerse API nav_order: 400 --- ## Delete PixVerse API account December 6, 2024 (November 16, 2026) --- > **https://api.useapi.net/v2/accounts/`email`** The `email` value should correspond to an account configured previously via a [POST /accounts/`email`](/docs/api-pixverse-v2/post-pixverse-accounts-email) request. ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **204** **204 No Content** **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** ##### Model A successful delete answers `204` with no body, and an error answers with `error`, `errorDetails` and `code`. <details markdown="block" class="model-details"> <summary>The error answer, field by field</summary> ```typescript { // TypeScript, all fields are optional error: string, errorDetails: string, code: number } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X DELETE https://api.useapi.net/v2/pixverse/accounts/<email> ``` **JavaScript** ``` javascript const email = "Previously configured account email"; const apiUrl = `https://api.useapi.net/v2/pixverse/accounts/${email}`; const token = "API token"; const data = { method: 'DELETE', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests email = "Previously configured account email" apiUrl = f"https://api.useapi.net/v2/pixverse/accounts/{email}" token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-pixverse-v2/del-pixverse-images-image_id === Document URL: https://useapi.net/docs/api-pixverse-v2/del-pixverse-images-image_id --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> images/`image_id` description: "Delete a generated PixVerse image by image_id via DEL images/image_id in the useapi.net PixVerse API v2 — removes it from your account." parent: PixVerse API nav_order: 530 --- ## Delete an image March 9, 2026 --- > **https://api.useapi.net/v2/pixverse/images/`image_id`** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Path parameter - `image_id` is **required**. Specify the image_id you want to delete. ##### Responses **200** **200 OK** Image was successfully deleted. **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X DELETE "https://api.useapi.net/v2/pixverse/images/image_id" ``` **JavaScript** ``` javascript const token = "API token"; const image_id = "image_id to delete"; const apiUrl = `https://api.useapi.net/v2/pixverse/images/${image_id}`; const response = await fetch(apiUrl, { method: 'DELETE', headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" image_id = "image_id to delete" apiUrl = f"https://api.useapi.net/v2/pixverse/images/{image_id}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-pixverse-v2/del-pixverse-scheduler-video_id === Document URL: https://useapi.net/docs/api-pixverse-v2/del-pixverse-scheduler-video_id --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> scheduler/`id` description: "Cancel a video, image, or music generation and remove its API tracking via DEL scheduler/id in the useapi.net PixVerse API v2." parent: PixVerse API nav_order: 1800 --- ## Cancel video, image, or music currently being executed by the API December 6, 2024 (November 16, 2026) --- Remove `video_id`, `image_id`, or `audio_id` generation tracking by the API. > **https://api.useapi.net/v2/pixverse/scheduler/`id`** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Path parameter - `id` is **required**. Specify the `video_id`, `image_id`, or `audio_id` you want to cancel. ##### Responses **204** **204 No Content** **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** ```json { "error": "Unable to locate running video_id <video_id>" } ``` ##### Model A successful cancel answers `204` with no body, and an error answers with `error` and `code`. <details markdown="block" class="model-details"> <summary>The error answer, field by field</summary> ```typescript { // TypeScript, all fields are optional error: string code: number } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X DELETE "https://api.useapi.net/v2/pixverse/scheduler/video_id" ``` **JavaScript** ``` javascript const video_id = "video_id to cancel"; const apiUrl = `https://api.useapi.net/v2/pixverse/scheduler/${video_id}`; const token = "API token"; const data = { method: 'DELETE', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests video_id = "video_id to cancel" apiUrl = f"https://api.useapi.net/v2/pixverse/scheduler/{video_id}" token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-pixverse-v2/del-pixverse-videos-video_id === Document URL: https://useapi.net/docs/api-pixverse-v2/del-pixverse-videos-video_id --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> videos/`video_id` description: "Delete a generated PixVerse video by video_id via DEL videos/video_id in the useapi.net PixVerse API v2 — removes it from your account." parent: PixVerse API nav_order: 800 --- ## Delete a video December 6, 2024 --- > **https://api.useapi.net/v2/pixverse/videos/`video_id`** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Path parameter - `video_id` is **required**. Specify the video_id you want to delete. ##### Responses **200** **200 OK** Video was successfully deleted. **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X DELETE "https://api.useapi.net/v2/pixverse/videos/video_id" ``` **JavaScript** ``` javascript const token = "API token"; const video_id = "video_id to delete"; const apiUrl = `https://api.useapi.net/v2/pixverse/videos/${video_id}`; const response = await fetch(apiUrl, { method: 'DELETE', headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" video_id = "video_id to delete" apiUrl = f"https://api.useapi.net/v2/pixverse/videos/{video_id}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-accounts-email === Document URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-accounts-email --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts/`email` description: "Retrieve the stored PixVerse account configuration for a specific email via GET accounts/email in the useapi.net PixVerse API v2." parent: PixVerse API nav_order: 200 --- ## Retrieve PixVerse API account configuration for `email` December 6, 2024 (November 16, 2026) --- > **https://api.useapi.net/v2/pixverse/accounts/`email`** The `email` value should correspond to an account configured previously via a [POST /accounts/`email`](/docs/api-pixverse-v2/post-pixverse-accounts-email) request. ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** ```json { "email": "<account email>", "password": "…secured…", "maxJobs": 3, "jwt": { "AccountId": 66778899, "ExpireTime": 123456789, "ExpireTimeUTC": "2025-01-01T12:13:14.000Z", "Username": "<username>", "token": "abc…secured…cde" } } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** Configuration not found. To create configuration use [POST /accounts/`email`](/docs/api-pixverse-v2/post-pixverse-accounts-email). ##### Model The account's email, `maxJobs` and PixVerse session token in `jwt` with its expiry, with the password and token masked. <details markdown="block" class="model-details"> <summary>The account configuration, field by field</summary> ```typescript { // TypeScript, all fields are optional email: string password: string maxJobs: number jwt: { AccountId: number ExpireTime: number ExpireTimeUTC: string Username: string token: string } } ``` </details> ##### Examples **Curl** ``` bash curl https://api.useapi.net/v2/pixverse/accounts/<email> \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const apiUrl = `https://api.useapi.net/v2/pixverse/accounts/${email}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured account email" apiUrl = f"https://api.useapi.net/v2/pixverse/accounts/{email}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-accounts === Document URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-accounts --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts description: "List all configured PixVerse accounts and their load-balancing settings via GET accounts in the useapi.net PixVerse API v2." parent: PixVerse API nav_order: 100 --- ## Retrieve PixVerse API accounts configuration December 6, 2024 (November 16, 2026) --- For your convenience, you can specify your PixVerse configuration values under your PixVerse account. If you specify multiple PixVerse accounts, the API will automatically perform load balancing by randomly selecting an account with available capacity before making calls to PixVerse. This endpoint retrieves the complete list of configured API accounts for PixVerse. > **https://api.useapi.net/v2/pixverse/accounts** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** ```json { "<email #1>": { "email": "<email #1>", "jwt": { "AccountId": 1122334455, "ExpireTime": 123456789, "ExpireTimeUTC": "2025-01-01T12:13:14.000Z" "Username": "<username>", "token": "abc…secured…cde", }, "maxJobs": 8, "password": "…secured…" }, "<email #2>": { "email": "<email #2>", "jwt": { "AccountId": 66778899, "ExpireTime": 123456789, "ExpireTime": 123456789, "ExpireTimeUTC": "2025-01-01T12:13:14.000Z" "Username": "<username>", "token": "abc…secured…cde", }, "maxJobs": 3, "password": "…secured…" } } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** Configuration not found. To create configuration use [POST /accounts/`email`](/docs/api-pixverse-v2/post-pixverse-accounts-email). ##### Model An object keyed by account email, each value with that account's `maxJobs` and masked PixVerse session token in `jwt`. <details markdown="block" class="model-details"> <summary>The account configurations, keyed by email, field by field</summary> ```typescript { // TypeScript, all fields are optional [email: string]: { email: string jwt: { AccountId: number ExpireTime: number ExpireTimeUTC: string Username: string token: string } maxJobs: number password: string } } ``` </details> ##### Examples **Curl** ``` bash curl https://api.useapi.net/v2/pixverse/accounts \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = "https://api.useapi.net/v2/pixverse/accounts"; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" apiUrl = "https://api.useapi.net/v2/pixverse/accounts" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-features === Document URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-features --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> features description: "Retrieve your PixVerse.ai account information — subscription plan, credit quotas, feature flags, billing dates, available qualities, and accessible image models — via GET features in the useapi.net PixVerse API v2." parent: PixVerse API nav_order: 450 --- ## Retrieve your PixVerse.ai account information (credits etc) December 6, 2024 (November 16, 2026) --- Retrieve your [PixVerse.ai](https://PixVerse.ai) account information, see [Setup PixVerse](/docs/start-here/setup-pixverse) for details. > **https://api.useapi.net/v2/pixverse/features/?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `email` is optional when only one [account](/docs/api-pixverse-v2/get-pixverse-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. ##### Responses **200** **200 OK** ```json { "user_id": 11223344, "member_id": 5566778899, "product_id": 9988776655, "plan_name": "Premium - Monthly", "next_plan_name": "Premium - Monthly", "next_plan_type": 2, "current_plan_type": 2, "type": 0, "credit_daily": 0, "credit_daily_gift": 60, "initial_credit_gift": 0, "credit_monthly": 12450, "credit_monthly_gift": 15000, "credit_package": 0, "expired_date": "2026-07-23T00:48:50Z", "price": "60", "billing_period": 1, "next_billing_period": 1, "billing_renewal_date": "2026-07-23T00:48:50Z", "payment": 1, "invoice_url": "https://stripe.pay.pixverse.ai/...", "stripe_bill_url": "https://stripe.pay.pixverse.ai/...", "gen_simultaneously": 5, "allow_fast_mode": 1, "allow_relaxed_mode": 1, "allow_use_new_feat": 1, "allow_private_generate": 1, "remove_watermark": 1, "allow_purchase_credit": 1, "sub_order_in_progress": 0, "allow_effect": 1, "last_plan_name": "", "last_plan_type": 0, "last_product_id": 0, "expired_member": 0, "credits_more": 30, "album_num": 1000, "batch_generation": 1, "off_peak": 1, "off_peak_discount": "0.7", "qualities": ["360p", "480p", "540p", "720p", "1080p", "2160p"], "cancel_updated_at": "0001-01-01T00:00:00Z", "renewal_retention": 0, "renewal_price": "60", "preview_mode": 1, "preview_mode_discount": "0.8", "remaining_days": 30, "credits_refresh_time": "2026-07-23T00:48:56Z", "daily_credits_refresh_time": "2026-06-25T00:00:00Z", "is_gift_card": false, "veo_sora_models": 1, "unlimited_image_models": ["qwen-image"], "accessible_image_models": ["qwen-image", "gemini-2.5-flash", "seedream-4.0", "seedream-4.5", "seedream-5.0-lite", "gemini-3.0", "gpt-image-1.5", "gpt-image-2.0", "gemini-3.1-flash", "kling-image-o3", "kling-image-v3"], "has_purchased_credits": true } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model The PixVerse plan, credit balances, billing dates, concurrency limit, and the image models and video qualities the account may use. <details markdown="block" class="model-details"> <summary>The PixVerse plan, credits and limits, field by field</summary> ```typescript { // TypeScript, all fields are optional // Identity user_id: number member_id: number product_id: number // Plan plan_name: string // e.g. 'Premium - Monthly' next_plan_name: string next_plan_type: number current_plan_type: number last_plan_name: string last_plan_type: number last_product_id: number type: number expired_member: number // 0 = active // Credits credit_daily: number // daily credits remaining credit_daily_gift: number // daily gift credits initial_credit_gift: number credit_monthly: number // monthly credits remaining credit_monthly_gift: number credit_package: number // purchased package credits credits_more: number has_purchased_credits: boolean is_gift_card: boolean credits_refresh_time: string // ISO - monthly credit refresh daily_credits_refresh_time: string // ISO - daily credit refresh // Billing / subscription price: string renewal_price: string billing_period: number next_billing_period: number billing_renewal_date: string // ISO expired_date: string // ISO - plan expiry remaining_days: number payment: number invoice_url: string stripe_bill_url: string renewal_retention: number cancel_updated_at: string // ISO - '0001-01-01T00:00:00Z' when not cancelled sub_order_in_progress: number // Limits / capability flags (0 | 1) gen_simultaneously: number // max concurrent generations allow_fast_mode: number allow_relaxed_mode: number allow_use_new_feat: number allow_private_generate: number remove_watermark: number allow_purchase_credit: number allow_effect: number batch_generation: number album_num: number veo_sora_models: number // 1 = Veo video models accessible (PixVerse's field name predates the Sora 2 shutdown) preview_mode: number preview_mode_discount: string // e.g. '0.8' off_peak: number off_peak_discount: string // e.g. '0.7' // Capabilities qualities: string[] // available video qualities, e.g. ['360p','480p','540p','720p','1080p','2160p'] unlimited_image_models: string[] // image models with unlimited (Relax Mode) use accessible_image_models: string[] // all image models the plan may use } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v2/pixverse/features/?email=email" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const email= "Previously configured account email"; const apiUrl = `https://api.useapi.net/v2/pixverse/features/?email=${email}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email= "Previously configured account email" apiUrl = f"https://api.useapi.net/v2/pixverse/features/?email={email}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-images-image_id === Document URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-images-image_id --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> images/`image_id` description: "Poll a PixVerse image by image_id via GET images/image_id in the useapi.net PixVerse API v2 — status values, image_status_final flag, and a live Try It console." parent: PixVerse API nav_order: 520 --- ## Retrieve a generated image March 9, 2026 (November 16, 2026) --- Use this endpoint to retrieve a generated image. Attempting to retrieve an image that is still processing will return the current status. Poll until `image_status_final` is `true`. To create images, use [POST images/create](/docs/api-pixverse-v2/post-pixverse-images-create). > **https://api.useapi.net/v2/pixverse/images/`image_id`** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Path parameter - `image_id` is **required**. Specify the image_id you want to retrieve (from `success_ids` array returned by [POST images/create](/docs/api-pixverse-v2/post-pixverse-images-create)). ##### Responses **200** **200 OK** ```json { "image_id": "user:<userid>-pixverse:<email>-image:<number>", "image_status": 1, "account_id": 12345678, "model": "seedream-4.0", "prompt": "<prompt>", "quality": "1080p", "aspect_ratio": "auto", "seed": 12345, "image_url": "https://media.pixverse.ai/...webp", "output_width": 1920, "output_height": 1080, "customer_img_paths": [], "customer_img_urls": null, "cost_credits": 0, "relax_mode": true, "generation_mode": { "version": 1, "requested_relax_mode": true, "resolved_mode": "relax", "billing_type": "free", "actual_cost": 0 }, "queue_data": { "estimated_gen_time": 60, "processing_start_time": "2026-03-08T00:30:00Z", "queue_count": 0, "queue_time": 1 }, "created_at": "2026-03-08T00:30:00Z", "updated_at": "2026-03-08T00:31:00Z", "image_status_name": "COMPLETED", "image_status_final": true } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** The image was deleted or not found. ```json { "error": "The original image has been deleted" } ``` ##### Image Status Values | image_status | image_status_name | image_status_final | Description | |:------------|:------------------|:-------------------|:------------| | 1 | COMPLETED | true | Image ready, check `image_url` | | 5 | QUEUED | false | Waiting in queue | | 7 | MODERATED | true | Content moderation triggered | | 8 | FAILED | true | PixVerse failed to make the image, no reason given. Retry | | 9 | GENERATING | false | Image is being generated | | 10 | PROCESSING | false | Post-processing | | 17 | MODERATED | true | Policy violation detected after the image was made | ##### Model The image with its prompt, model, dimensions and `image_url`, and `image_status_name` and `image_status_final` to tell whether it has finished. <details markdown="block" class="model-details"> <summary>The image record, field by field, and what <code>queue_data</code> reports</summary> ```typescript { // TypeScript, all fields are optional image_id: string image_status: number account_id: number asset_id: number asset_source: number asset_type: number create_mode: string creation_type: number model: string prompt: string quality: string aspect_ratio: string seed: number image_path: string image_url: string output_width: number output_height: number customer_img_paths: string[] customer_img_urls: string[] | null platform: string cost_credits: number relax_mode: boolean | null generation_mode?: { version: number requested_relax_mode: boolean resolved_mode: string // relax | regular billing_type: string // free | full_price actual_cost: number } | null queue_data?: { estimated_gen_time: number processing_start_time: string queue_count: number queue_time: number reason?: string slow_queue?: boolean platform?: string task_id?: number } created_at: string updated_at: string is_collected: boolean water_mark: boolean media_locked: number // added image_status_name: string image_status_final: boolean error: string } ``` `queue_data` is present while a generation is waiting and reports its position — `queue_count` is the number of tasks ahead, `queue_time` the wait so far, and `estimated_gen_time` the projected generation time in seconds. It comes straight from PixVerse and is passed through unchanged. When `slow_queue` is `true` the account has been moved to a reduced-priority queue and `reason` says why. The value `daily_limit_exceeded` means the account has passed its daily allowance for that particular [unlimited Relax Mode model](/docs/api-pixverse-v2/post-pixverse-images-create) — the request is **not** rejected and still costs no credits, it just takes considerably longer. The allowance is per model, so the same account keeps running at full speed on every other model. Switch model, or spread the load across more accounts, if you see this persistently. </details> ##### Generation mode `cost_credits` is what PixVerse charged for the image, `0` for an image made in Relax Mode. `generation_mode` shows how PixVerse handled the [`relax_mode`](/docs/api-pixverse-v2/post-pixverse-images-create#unlimited-image-generation-relax-mode) parameter of [POST images/create](/docs/api-pixverse-v2/post-pixverse-images-create): - `requested_relax_mode` is the `relax_mode` value you sent. - `resolved_mode` is the mode PixVerse used: `relax` (free Relax Mode) or `regular` (paid, full speed). - `billing_type` is `free` or `full_price`, and `actual_cost` is the credits charged. When `relax_mode` was left out, both `relax_mode` and `generation_mode` are `null`, and `cost_credits` tells you whether the image was free. In that case PixVerse uses Relax Mode whenever the account's plan makes the model free. ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v2/pixverse/images/image_id" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const image_id = "image_id to retrieve"; const apiUrl = `https://api.useapi.net/v2/pixverse/images/${image_id}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" image_id = "image_id to retrieve" apiUrl = f"https://api.useapi.net/v2/pixverse/images/{image_id}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-images === Document URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-images --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> images description: "List all PixVerse images — queued, generating, and completed — via GET images in the useapi.net PixVerse API v2, with image_status_name and image_status_final." parent: PixVerse API nav_order: 510 --- ## Retrieve the list of images December 6, 2024 (November 16, 2026) --- Retrieve the list of images, this will include those currently being generated or queued. Check the `image_status_name` field for the status and the field `image_status_final` to determine if the provided status is the final status. The API internally uses the field `image_status` to calculate values for `image_status_name` and `image_status_final`. See below for the known statuses map: | image_status | image_status_name | image_status_final | |--------|-------------------|--------------------| | 1 | COMPLETED | true | | 5 | QUEUED | false | | 7 | MODERATED | true | | 8 | FAILED | true | | 9 | GENERATING | false | | 10 | PROCESSING | false | | 17 | MODERATED | true | > **https://api.useapi.net/v2/pixverse/images/?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `email` is optional when only one [account](/docs/api-pixverse-v2/get-pixverse-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `limit` is optional, specify the number of images to return. Default 50. Treat it as an upper bound rather than a guarantee — a response may contain fewer images than requested, and on very high-volume accounts we may reduce it. - **Page using the `next_offset` and `has_more` fields returned in the response — do not advance by your own `limit`.** A page can come back shorter than requested, so stepping by your own value will skip images. `total` always reports the true number of images available, whatever the page size. - `offset` is optional, specify the offset from where to start. ##### Responses **200** **200 OK** ```json { "data": [ { "image_id": "user:<userid>-pixverse:<email>-image:11223344", "image_status": 1, "account_id": 33445566, "asset_id": 0, "asset_source": 1, "asset_type": 0, "create_mode": "t2i", "creation_type": 0, "model": "qwen-image", "prompt": "<prompt>", "quality": "720p", "aspect_ratio": "1:1", "seed": 123456, "image_path": "image/...", "image_url": "https://media.pixverse.ai/image/...webp", "output_width": 720, "output_height": 720, "customer_img_paths": [], "customer_img_urls": null, "platform": "", "queue_data": null, "created_at": "2026-03-09T12:34:56Z", "updated_at": "2026-03-09T12:34:58Z", "is_collected": false, "water_mark": false, "media_locked": 0, "image_status_name": "COMPLETED", "image_status_final": true } ], "next_offset": 50, "total": 12 } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model A page of images in `data`, including those still queued or generating, each with its status, prompt and `image_url`, plus `next_offset` and `total`. <details markdown="block" class="model-details"> <summary>The list of images, field by field, and what <code>queue_data</code> reports</summary> ```typescript { // TypeScript, all fields are optional data: { image_id: string image_status: number account_id: number asset_id: number asset_source: number asset_type: number create_mode: string creation_type: number model: string prompt: string quality: string aspect_ratio: string seed: number image_path: string image_url: string output_width: number output_height: number customer_img_paths: string[] customer_img_urls: string[] | null platform: string queue_data: { estimated_gen_time: number processing_start_time: string queue_count: number queue_time: number reason?: string slow_queue?: boolean platform?: string task_id?: number } | null created_at: string updated_at: string is_collected: boolean water_mark: boolean media_locked: number // added image_status_name: string image_status_final: boolean }[] next_offset: number total: number } ``` `queue_data` is present while a generation is waiting and reports its position — `queue_count` is the number of tasks ahead, `queue_time` the wait so far, and `estimated_gen_time` the projected generation time in seconds. It comes straight from PixVerse and is passed through unchanged. When `slow_queue` is `true` the account has been moved to a reduced-priority queue and `reason` says why. The value `daily_limit_exceeded` means the account has passed its daily allowance for that particular [unlimited Relax Mode model](/docs/api-pixverse-v2/post-pixverse-images-create) — the request is **not** rejected and still costs no credits, it just takes considerably longer. The allowance is per model, so the same account keeps running at full speed on every other model. Switch model, or spread the load across more accounts, if you see this persistently. </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v2/pixverse/images/?email=email" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const email= "Previously configured account email"; const apiUrl = `https://api.useapi.net/v2/pixverse/images/?email=${email}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email= "Previously configured account email" apiUrl = f"https://api.useapi.net/v2/pixverse/images/?email={email}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-music-music_id === Document URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-music-music_id --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> music/`audio_id` description: "Poll a PixVerse music track by audio_id via GET music/audio_id in the useapi.net PixVerse API v2 — status values, audio_status_final flag, the mp3 url, and a live Try It console." parent: PixVerse API nav_order: 1430 --- ## Retrieve a generated music track June 24, 2026 (November 16, 2026) --- Use this endpoint to retrieve a generated music track. Attempting to retrieve a track that is still generating will return the current status. Poll until `audio_status_final` is `true`. To create music, use [POST music/create](/docs/api-pixverse-v2/post-pixverse-music-create). > **https://api.useapi.net/v2/pixverse/music/`audio_id`** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Path parameter - `audio_id` is **required**. Specify the `audio_id` returned by [POST music/create](/docs/api-pixverse-v2/post-pixverse-music-create). ##### Responses **200** **200 OK** ```json { "audio_id": "user:<userid>-pixverse:<email>-music:<number>", "asset_id": 11223344, "audio_status": 1, "status": "finish", "create_mode": "music", "provider": "minimax", "model": "music-2.6", "prompt": "<prompt>", "auto_lyrics": true, "url": "https://media.pixverse.ai/pixverse/audio/music/11223344.mp3", "name": "PixVerse_Music_11223344.mp3", "duration": 202, "credits": 40, "created_at": "2026-06-23T12:34:56Z", "updated_at": "2026-06-23T12:38:18Z", "audio_status_name": "COMPLETED", "audio_status_final": true } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** The track was deleted or not found. ```json { "error": "Music user:<userid>-pixverse:<email>-music:<number> not found" } ``` ##### Audio Status Values | audio_status | audio_status_name | audio_status_final | Description | |:------------|:------------------|:-------------------|:------------| | 1 | COMPLETED | true | Track ready, check `url` | | 5 | QUEUED | false | Accepted, waiting to start | | 8 | FAILED | true | Generation failed, see `fail_reason` | | 10 | GENERATING | false | Track is being generated | When a track fails (`audio_status` 8) the response also carries `fail_code` (`music_generation_failed`) and a human-readable `fail_reason` describing the underlying error. These are usually transient backend errors, so re-submitting the same request often succeeds. ##### Model The track with its status, prompt, model, duration and audio `url`, plus `fail_code` and `fail_reason` when it failed. <details markdown="block" class="model-details"> <summary>The music track record, field by field</summary> ```typescript { // TypeScript, all fields are optional audio_id: string asset_id: number audio_status: number status: string create_mode: string provider: string model: string prompt: string auto_lyrics: boolean path: string url: string name: string duration: number file_size: number format: string sample_rate: number bitrate: number channel: number credits: number created_at: string updated_at: string // present only when audio_status is 8 (FAILED) fail_code: string fail_reason: string // added audio_status_name: string audio_status_final: boolean error: string } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v2/pixverse/music/audio_id" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const audio_id = "audio_id to retrieve"; const apiUrl = `https://api.useapi.net/v2/pixverse/music/${audio_id}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" audio_id = "audio_id to retrieve" apiUrl = f"https://api.useapi.net/v2/pixverse/music/{audio_id}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-music-video-library === Document URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-music-video-library --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> music-video/library description: "List PixVerse's built-in songs, characters and style images for music videos via GET music-video/library in the useapi.net PixVerse API v2 — ready-made audio_path and image_path values, filterable by type." parent: PixVerse API nav_order: 1444 --- ## Built-in songs, characters and styles for music videos November 10, 2026 (November 16, 2026) --- PixVerse ships a small library for its music videos: 13 songs, 15 characters and 28 style images (as of November 2026). Pass a song's `audio_path`, a character's `image_path` or a style's `image_path` (as `style_image_path`, with `style: custom`) straight to [POST music-video/create](/docs/api-pixverse-v2/post-pixverse-music-video-create), with nothing to upload. The library is the same for every account. The API keeps a copy for an hour, so repeated calls are fast. > **https://api.useapi.net/v2/pixverse/music-video/library/?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `email` is optional when only one [account](/docs/api-pixverse-v2/get-pixverse-accounts) is configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `type` is optional, `songs`, `characters` or `styles` to return only that list. Default: all three. ##### Responses **200** **200 OK** ```json { "songs": [ { "name": "Street Level", "audio_path": "asset/music/material/audio/street_level.mp3", "url": "https://media.pixverse.ai/asset%2Fmusic%2Fmaterial%2Faudio%2Fstreet_level.mp3", "duration": 28.824 } ], "characters": [ { "name": "MVMV 1", "image_path": "asset/music/material/character/mvmv1.png", "url": "https://media.pixverse.ai/asset%2Fmusic%2Fmaterial%2Fcharacter%2Fmvmv1.png", "width": 1254, "height": 1254 } ], "styles": [ { "name": "Style 1", "image_path": "asset/music/material/style/style_01.png", "url": "https://media.pixverse.ai/asset%2Fmusic%2Fmaterial%2Fstyle%2Fstyle_01.png", "width": 1254, "height": 1254 } ] } ``` **400** **400 Bad Request** ```json { "error": "Parameter type (voices) valid values: songs,characters,styles", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized" } ``` **596** **596 Pending mod message** The account has a pending error, and the API does not use it until you add it again with [POST accounts/email](/docs/api-pixverse-v2/post-pixverse-accounts-email). You receive an email when this happens. There are three causes. PixVerse could not sign the account in, most often because its password was changed. Add the account again with the current password. ```json { "error": "Your PixVerse account has pending error. Please address this issue at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email before making any new API calls.", "code": 596 } ``` Or PixVerse suspended the account. PixVerse suspends accounts that break its content rules and does not say which generation caused it. The first response carries PixVerse's own details in `account_moderation`, and later calls return the same `error`. Add the account again after `reinstatement_at`. To ask PixVerse to lift the suspension earlier, write to the `support_email` it gives. ```json { "error": "PixVerse suspended account example@gmail.com for 30 days, from 2026-10-16 09:26 UTC until 2026-11-15 09:26 UTC. PixVerse suspends accounts that break its content rules and does not say which generation caused it. Add the account again at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email after 2026-11-15 09:26 UTC. To ask PixVerse to lift it earlier, write to support@pixverse.ai.", "code": 596, "account_moderation": { "ban_level": "suspend_30d", "action": "temporary_suspend", "duration_days": 30, "suspended_at": "2026-10-16 09:26:25 (UTC)", "reinstatement_at": "2026-11-15 09:26:25 (UTC)", "support_email": "support@pixverse.ai" } } ``` Or PixVerse banned the account for violating its community guidelines. A ban is permanent unless PixVerse accepts an appeal, and the `error` quotes PixVerse's own message, which says how to appeal. Remove the account with [DELETE accounts/email](/docs/api-pixverse-v2/del-pixverse-accounts-email), or add it again only if PixVerse lifts the ban. ```json { "error": "PixVerse banned account example@gmail.com for violating its community guidelines (400024). A ban is permanent unless PixVerse accepts an appeal. PixVerse says: \"Your account has been banned for violating community guidelines. If you wish to appeal, please contact us via ...\" Remove it with DELETE /v2/pixverse/accounts/example@gmail.com, or add it again (https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email) only if PixVerse lifts the ban.", "code": 596 } ``` If every account you have is in this state, a request without `email` returns 596 as well. ##### Model The built-in `songs`, `characters` and `styles` for music videos, each with its name, file path and `url`. <details markdown="block" class="model-details"> <summary>The built-in songs, characters and styles, field by field</summary> ```typescript { // TypeScript, all fields are optional songs: { name: string audio_path: string url: string duration: number }[] characters: { name: string image_path: string url: string width: number height: number }[] styles: { name: string image_path: string url: string width: number height: number }[] } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v2/pixverse/music-video/library/?type=songs" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = `https://api.useapi.net/v2/pixverse/music-video/library/?type=songs`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" apiUrl = "https://api.useapi.net/v2/pixverse/music-video/library/?type=songs" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-music-video-video_id === Document URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-music-video-video_id --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> music-video/`video_id` description: "Poll a PixVerse music video by video_id via GET music-video/video_id in the useapi.net PixVerse API v2 — status, the settings used, the mp4, and the extra files: a copy without captions, the subtitle file, key images and clips." parent: PixVerse API nav_order: 1442 --- ## Retrieve a music video November 10, 2026 (November 16, 2026) --- Use this endpoint to follow a music video made with [POST music-video/create](/docs/api-pixverse-v2/post-pixverse-music-video-create) until `status` is `succeeded` or `failed`, and to get the result. Besides the video it returns the settings the video was made with and, once it has finished, the extra files PixVerse produced: | `role` | What it is | |:-------|:-----------| | `no_subtitle_video` | the same video without burned-in captions | | `subtitle_ass` | the timed lyrics as an `.ass` subtitle file | | `intermediate_image` | the key images PixVerse generated for the shots | | `intermediate_video` | the individual clips before they were cut together | The same `video_id` also works with [GET videos/`video_id`](/docs/api-pixverse-v2/get-pixverse-videos-video_id), which returns the plain video record (`video_status_name` `GENERATING` while it renders, then `COMPLETED` or `FAILED`). > **https://api.useapi.net/v2/pixverse/music-video/`video_id`** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Path Parameters - `video_id` is **required**, the `video_id` returned by [POST music-video/create](/docs/api-pixverse-v2/post-pixverse-music-video-create) or listed by [GET music-video](/docs/api-pixverse-v2/get-pixverse-music-video). The account is encoded in it, so no `email` is needed. ##### Responses **200** **200 OK** `status` is `pending` or `processing` while the video renders, then `succeeded` (with `video` and `files`) or `failed` (with `error`). ```json { "video_id": "user:<userid>-pixverse:<email>-video:642767619916505", "project_id": 192080023076656, "status": "succeeded", "mode": "performance", "audio_path": "upload/8aa34c5f-7f33-4fdc-af40-7357909102cb.mp3", "audio_duration": 151.97, "style": "auto", "image_path": "upload/66952750-badc-473b-b2a2-721197e96e7d.jpeg", "music_genre": "hip_hop", "subtitles": true, "aspect_ratio": "16:9", "quality": "1080p", "video": { "video_id": "user:<userid>-pixverse:<email>-video:642767619916505", "url": "https://media.pixverse.ai/pixverse%2Fmp4%2Fmedia%2Fweb%2Fori%2Fs-298ddfb9-f337-4091-a75e-ef7434aa9ce4_seed479843745.mp4", "cover_url": "https://media.pixverse.ai/pixverse%2Fvideo%2Fframe%2Ff7b7474c-53c3-4579-8f46-42982e159731.jpg", "first_frame": "https://media.pixverse.ai/pixverse%2Fvideo%2Fframe%2Ff7b7474c-53c3-4579-8f46-42982e159731.jpg", "width": 1920, "height": 1072, "duration": 152, "format": "mp4" }, "files": [ { "role": "intermediate_image", "file_name": "one-click-mv-image-0000.png", "url": "https://media.pixverse.ai/pixverse%2Fmp4%2Fmedia%2Fweb%2Fori%2Fs-298ddfb9-f337-4091-a75e-ef7434aa9ce4_seed479843745_artifact_000.png", "format": "png" }, { "role": "subtitle_ass", "file_name": "one-click-mv-subtitle-00.ass", "url": "https://media.pixverse.ai/pixverse%2Fmp4%2Fmedia%2Fweb%2Fori%2Fs-298ddfb9-f337-4091-a75e-ef7434aa9ce4_seed479843745_artifact_034.ass", "format": "ass" }, { "role": "no_subtitle_video", "file_name": "one-click-mv-no-subtitle.mp4", "url": "https://media.pixverse.ai/pixverse%2Fmp4%2Fmedia%2Fweb%2Fori%2Fs-298ddfb9-f337-4091-a75e-ef7434aa9ce4_seed479843745_artifact_035.mp4", "format": "mp4" } ], "created_at": "2026-11-10T06:53:05Z", "updated_at": "2026-11-10T07:08:41Z" } ``` A failed video carries PixVerse's reason, and its credits are refunded: ```json { "video_id": "user:<userid>-pixverse:<email>-video:905470371786428", "project_id": 536243871290987, "status": "failed", "error": "<PixVerse's reason>", "mode": "performance", "video": null, "files": [] } ``` **400** **400 Bad Request** ```json { "error": "Path parameter path_video_id (…) has incorrect format", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized" } ``` **404** **404 Not Found** The video is not a music video (use [GET videos/`video_id`](/docs/api-pixverse-v2/get-pixverse-videos-video_id) for it) or no longer exists. ```json { "error": "Video user:<userid>-pixverse:<email>-video:<number> is not a music video. Use GET /videos/… for it", "code": 404 } ``` **596** **596 Pending mod message** The account has a pending error, and the API does not use it until you add it again with [POST accounts/email](/docs/api-pixverse-v2/post-pixverse-accounts-email). You receive an email when this happens. There are three causes. PixVerse could not sign the account in, most often because its password was changed. Add the account again with the current password. ```json { "error": "Your PixVerse account has pending error. Please address this issue at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email before making any new API calls.", "code": 596 } ``` Or PixVerse suspended the account. PixVerse suspends accounts that break its content rules and does not say which generation caused it. The first response carries PixVerse's own details in `account_moderation`, and later calls return the same `error`. Add the account again after `reinstatement_at`. To ask PixVerse to lift the suspension earlier, write to the `support_email` it gives. ```json { "error": "PixVerse suspended account example@gmail.com for 30 days, from 2026-10-16 09:26 UTC until 2026-11-15 09:26 UTC. PixVerse suspends accounts that break its content rules and does not say which generation caused it. Add the account again at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email after 2026-11-15 09:26 UTC. To ask PixVerse to lift it earlier, write to support@pixverse.ai.", "code": 596, "account_moderation": { "ban_level": "suspend_30d", "action": "temporary_suspend", "duration_days": 30, "suspended_at": "2026-10-16 09:26:25 (UTC)", "reinstatement_at": "2026-11-15 09:26:25 (UTC)", "support_email": "support@pixverse.ai" } } ``` Or PixVerse banned the account for violating its community guidelines. A ban is permanent unless PixVerse accepts an appeal, and the `error` quotes PixVerse's own message, which says how to appeal. Remove the account with [DELETE accounts/email](/docs/api-pixverse-v2/del-pixverse-accounts-email), or add it again only if PixVerse lifts the ban. ```json { "error": "PixVerse banned account example@gmail.com for violating its community guidelines (400024). A ban is permanent unless PixVerse accepts an appeal. PixVerse says: \"Your account has been banned for violating community guidelines. If you wish to appeal, please contact us via ...\" Remove it with DELETE /v2/pixverse/accounts/example@gmail.com, or add it again (https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email) only if PixVerse lifts the ban.", "code": 596 } ``` If every account you have is in this state, a request without `email` returns 596 as well. ##### Model The music video's `status`, the settings it was made with and, once it succeeds, the `video` and its extra `files`. <details markdown="block" class="model-details"> <summary>The music video record, field by field</summary> ```typescript { // TypeScript, all fields are optional video_id: string project_id: number status: 'pending' | 'processing' | 'succeeded' | 'failed' error: string mode: 'performance' | 'expressive' | 'storytelling' audio_path: string audio_duration: number style: string style_image_path: string image_path: string image_path_2: string music_genre: string subtitles: boolean lyrics: string prompt: string aspect_ratio: string quality: string video: { video_id: string url: string cover_url: string first_frame: string width: number height: number duration: number format: string } | null files: { role: 'no_subtitle_video' | 'subtitle_ass' | 'intermediate_image' | 'intermediate_video' file_name: string url: string format: string }[] created_at: string updated_at: string } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v2/pixverse/music-video/<video_id>" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const video_id = "video_id returned by POST music-video/create"; const apiUrl = `https://api.useapi.net/v2/pixverse/music-video/${video_id}`; const token = "API token"; const data = { method: 'GET', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests video_id = "video_id returned by POST music-video/create" apiUrl = f"https://api.useapi.net/v2/pixverse/music-video/{video_id}" token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-music-video === Document URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-music-video --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> music-video description: "List the music videos of a PixVerse account via GET music-video in the useapi.net PixVerse API v2 — newest first, with status, video_id and the mp4 of each, paged with offset and limit." parent: PixVerse API nav_order: 1441 --- ## List music videos November 10, 2026 (November 16, 2026) --- Lists the music videos of one account, newest first, including ones made on the PixVerse website. Each entry has the `video_id` to use with [GET music-video/`video_id`](/docs/api-pixverse-v2/get-pixverse-music-video-video_id), which returns the settings and the extra files. To make one, use [POST music-video/create](/docs/api-pixverse-v2/post-pixverse-music-video-create). > **https://api.useapi.net/v2/pixverse/music-video/?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `email` is optional when only one [account](/docs/api-pixverse-v2/get-pixverse-accounts) is configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `offset` is optional, default `0`. - `limit` is optional, default `20`. Valid range: 1…40 PixVerse pages through all of its music projects (beat mixes and other music features too), and the API keeps only the music videos, so a page can hold fewer than `limit` entries while `has_more` is still `true`. Continue with `offset` set to `next_offset`. ##### Responses **200** **200 OK** `video_id` and `video` appear once PixVerse has produced the video. ```json { "data": [ { "video_id": "user:<userid>-pixverse:<email>-video:370538497751884", "project_id": 304006225895014, "status": "succeeded", "name": "Music Project_304006225895014", "video": { "video_id": "user:<userid>-pixverse:<email>-video:370538497751884", "url": "https://media.pixverse.ai/pixverse%2Fmp4%2Fmedia%2Fweb%2Fori%2Fs-2cb36fb5-390b-4163-ba8d-e06fd001b115_seed6406858824.mp4", "cover_url": "https://media.pixverse.ai/pixverse%2Fvideo%2Fframe%2Fb3329a4a-5a17-48ea-b369-517ff26bf95a.jpg", "first_frame": "https://media.pixverse.ai/pixverse%2Fvideo%2Fframe%2Fb3329a4a-5a17-48ea-b369-517ff26bf95a.jpg", "width": 720, "height": 1280, "duration": 11, "format": "mp4" }, "created_at": "2026-11-10T07:07:01Z", "updated_at": "2026-11-10T07:10:56Z" } ], "next_offset": 0, "has_more": false } ``` **400** **400 Bad Request** ```json { "error": "Parameter limit (41) is more than 40", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized" } ``` **596** **596 Pending mod message** The account has a pending error, and the API does not use it until you add it again with [POST accounts/email](/docs/api-pixverse-v2/post-pixverse-accounts-email). You receive an email when this happens. There are three causes. PixVerse could not sign the account in, most often because its password was changed. Add the account again with the current password. ```json { "error": "Your PixVerse account has pending error. Please address this issue at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email before making any new API calls.", "code": 596 } ``` Or PixVerse suspended the account. PixVerse suspends accounts that break its content rules and does not say which generation caused it. The first response carries PixVerse's own details in `account_moderation`, and later calls return the same `error`. Add the account again after `reinstatement_at`. To ask PixVerse to lift the suspension earlier, write to the `support_email` it gives. ```json { "error": "PixVerse suspended account example@gmail.com for 30 days, from 2026-10-16 09:26 UTC until 2026-11-15 09:26 UTC. PixVerse suspends accounts that break its content rules and does not say which generation caused it. Add the account again at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email after 2026-11-15 09:26 UTC. To ask PixVerse to lift it earlier, write to support@pixverse.ai.", "code": 596, "account_moderation": { "ban_level": "suspend_30d", "action": "temporary_suspend", "duration_days": 30, "suspended_at": "2026-10-16 09:26:25 (UTC)", "reinstatement_at": "2026-11-15 09:26:25 (UTC)", "support_email": "support@pixverse.ai" } } ``` Or PixVerse banned the account for violating its community guidelines. A ban is permanent unless PixVerse accepts an appeal, and the `error` quotes PixVerse's own message, which says how to appeal. Remove the account with [DELETE accounts/email](/docs/api-pixverse-v2/del-pixverse-accounts-email), or add it again only if PixVerse lifts the ban. ```json { "error": "PixVerse banned account example@gmail.com for violating its community guidelines (400024). A ban is permanent unless PixVerse accepts an appeal. PixVerse says: \"Your account has been banned for violating community guidelines. If you wish to appeal, please contact us via ...\" Remove it with DELETE /v2/pixverse/accounts/example@gmail.com, or add it again (https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email) only if PixVerse lifts the ban.", "code": 596 } ``` If every account you have is in this state, a request without `email` returns 596 as well. ##### Model A page of music videos in `data`, each with its `status`, name and finished `video`, plus `next_offset` and `has_more`. <details markdown="block" class="model-details"> <summary>The list of music videos, field by field</summary> ```typescript { // TypeScript, all fields are optional data: { video_id: string project_id: number status: 'pending' | 'processing' | 'succeeded' | 'failed' name: string video: { video_id: string url: string cover_url: string first_frame: string width: number height: number duration: number format: string } created_at: string updated_at: string }[] next_offset: number has_more: boolean } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v2/pixverse/music-video/?email=email" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const apiUrl = `https://api.useapi.net/v2/pixverse/music-video/?email=${email}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured account email" apiUrl = f"https://api.useapi.net/v2/pixverse/music-video/?email={email}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-music === Document URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-music --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> music description: "List all PixVerse music tracks — queued, generating, and completed — via GET music in the useapi.net PixVerse API v2, with audio_status_name and audio_status_final." parent: PixVerse API nav_order: 1420 --- ## Retrieve the list of music tracks June 25, 2026 (November 16, 2026) --- Retrieve the list of music tracks, this will include those currently being generated or queued. Check the `audio_status_name` field for the status and the field `audio_status_final` to determine if the provided status is the final status. The API internally uses the field `audio_status` to calculate values for `audio_status_name` and `audio_status_final`. See below for the known statuses map: | audio_status | audio_status_name | audio_status_final | |--------|-------------------|--------------------| | 1 | COMPLETED | true | | 5 | QUEUED | false | | 8 | FAILED | true | | 10 | GENERATING | false | > **https://api.useapi.net/v2/pixverse/music/?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `email` is optional when only one [account](/docs/api-pixverse-v2/get-pixverse-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `limit` is optional, specify the number of tracks to return. Default 50. - `offset` is optional, specify the offset from where to start. ##### Responses **200** **200 OK** ```json { "data": [ { "audio_id": "user:<userid>-pixverse:<email>-music:11223344", "asset_id": 11223344, "audio_status": 1, "status": "finish", "create_mode": "music", "provider": "minimax", "model": "music-2.6", "prompt": "<prompt>", "auto_lyrics": true, "url": "https://media.pixverse.ai/pixverse/audio/music/11223344.mp3", "name": "PixVerse_Music_11223344.mp3", "duration": 202, "credits": 40, "created_at": "2026-06-23T12:34:56Z", "updated_at": "2026-06-23T12:38:18Z", "audio_status_name": "COMPLETED", "audio_status_final": true } ], "next_offset": 50, "has_more": false } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` This endpoint returns music tracks only (`create_mode: music`). Text-to-speech audio is listed separately by [GET speech](/docs/api-pixverse-v2/get-pixverse-speech). ##### Model A page of music tracks in `data`, each with its status, prompt, model and audio `url`, plus `next_offset` and `has_more`. <details markdown="block" class="model-details"> <summary>The list of music tracks, field by field</summary> ```typescript { // TypeScript, all fields are optional data: { audio_id: string asset_id: number audio_status: number status: string create_mode: string provider: string model: string prompt: string auto_lyrics: boolean url: string name: string duration: number credits: number created_at: string updated_at: string // added audio_status_name: string audio_status_final: boolean }[] next_offset: number has_more: boolean } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v2/pixverse/music/?email=email" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const email= "Previously configured account email"; const apiUrl = `https://api.useapi.net/v2/pixverse/music/?email=${email}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email= "Previously configured account email" apiUrl = f"https://api.useapi.net/v2/pixverse/music/?email={email}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-scheduler-available === Document URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-scheduler-available --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> scheduler/available description: "Check active videos, images, and music in flight plus remaining account capacity via GET scheduler/available in the useapi.net PixVerse API v2." parent: PixVerse API nav_order: 1600 --- ## Retrieve the list of videos, images, and music currently running via the API along with the available account capacity December 6, 2024 (November 16, 2026) --- This endpoint retrieves the list of videos, images, and music tracks currently running via the API along with the available account capacity. Each executing item includes `id` and `type` (`video`, `image`, or `music`). If you want to get all videos or images currently being executed including those manually initiated from PixVerse.ai website use [GET /videos](/docs/api-pixverse-v2/get-pixverse-videos) or [GET /images](/docs/api-pixverse-v2/get-pixverse-images). > **https://api.useapi.net/v2/pixverse/scheduler/available** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** ```json { "executing": [ { "id": "user:user_id-pixverse:email-video:id1", "type": "video", "started": "2024-09-25T01:55:16.128Z", "elapsed": "03:57", "replyUrl": "<optional callback URL>", "replyRef": "<optional reference>" }, { "id": "user:user_id-pixverse:email-image:id2", "type": "image", "started": "2024-09-25T01:58:18.555Z", "elapsed": "00:35", "replyUrl": "<optional callback URL>", "replyRef": "<optional reference>" } ], "available": [ { "email": "<email_1>", "maxJobs": 5, "executing": 0, "available": 5 }, { "email": "<email_2>", "maxJobs": 8, "executing": 3, "available": 2 }, { "email": "<email_N>", "maxJobs": 3, "executing": 2, "available": 1 } ] } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model The jobs running now in `executing`, and for each account in `available` its `maxJobs` with the running and free slots. <details markdown="block" class="model-details"> <summary>The running jobs and each account's free capacity, field by field</summary> ```typescript { // TypeScript, all fields are optional executing: { id: string type: 'video' | 'image' started: string elapsed: string replyUrl: string replyRef: string }[] available: { email: string maxJobs: number executing: number available: number }[] error: string code: number } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v2/pixverse/scheduler/available" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = `https://api.useapi.net/v2/pixverse/scheduler/available`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" apiUrl = f"https://api.useapi.net/v2/pixverse/scheduler/available" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-scheduler === Document URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-scheduler --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> scheduler description: "List videos, images, and music tracks the API is currently executing via GET scheduler in the useapi.net PixVerse API v2 — each entry reports its id and type." parent: PixVerse API nav_order: 1500 --- ## Retrieve the list of videos, images, and music currently being executed by the API December 6, 2024 (November 16, 2026) --- This endpoint retrieves the list of videos, images, and music tracks currently being executed by the API. Each item includes `id` and `type` (`video`, `image`, or `music`). If you want to get all videos, images, or music tracks currently being executed including those manually initiated from PixVerse.ai website use [GET /videos](/docs/api-pixverse-v2/get-pixverse-videos), [GET /images](/docs/api-pixverse-v2/get-pixverse-images), or [GET /music](/docs/api-pixverse-v2/get-pixverse-music). > **https://api.useapi.net/v2/pixverse/scheduler/** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** ```json [ { "id": "user:user_id-pixverse:email-video:id1", "type": "video", "started": "2024-09-25T01:55:16.128Z", "elapsed": "03:57", "replyUrl": "<optional callback URL>", "replyRef": "<optional reference>" }, { "id": "user:user_id-pixverse:email-image:id2", "type": "image", "started": "2024-09-25T01:58:18.555Z", "elapsed": "00:35", "replyUrl": "<optional callback URL>", "replyRef": "<optional reference>" } ] ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model An array of the videos, images and music running now, each with its id, type, start time and time elapsed. <details markdown="block" class="model-details"> <summary>The list of running jobs, field by field</summary> ```typescript { // TypeScript, all fields are optional id: string type: 'video' | 'image' | 'music' started: string elapsed: string replyUrl: string replyRef: string }[] ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v2/pixverse/scheduler/" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = `https://api.useapi.net/v2/pixverse/scheduler/`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" apiUrl = f"https://api.useapi.net/v2/pixverse/scheduler/" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-speech-models === Document URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-speech-models --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> speech/models description: "List the text-to-speech models via GET speech/models in the useapi.net PixVerse API v2 — per-model max characters, supported language codes, credit formula, and the MiniMax emotion enum." parent: PixVerse API nav_order: 1490 --- ## List text-to-speech models June 25, 2026 (November 16, 2026) --- List the speech models available for [POST speech/create](/docs/api-pixverse-v2/post-pixverse-speech-create), with each model's provider, character limit, credit formula, and the live list of `supported_language_codes`. This is the source of truth for which `language_code` values a model accepts — `text` length and `language_code` on a generation are validated against it. For MiniMax models the response also carries the `emotions` enum (the values accepted by the `emotion` voice setting). > **https://api.useapi.net/v2/pixverse/speech/models** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `email` is optional when only one [account](/docs/api-pixverse-v2/get-pixverse-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. ##### Responses **200** **200 OK** ```json { "default_model": "speech-2.8-hd", "provider_groups": [ { "provider": "minimax", "models": [ { "model": "speech-2.8-hd", "display_name": "Speech 2.8 HD", "provider": "minimax", "max_characters": 10000, "supported_language_codes": ["auto", "en", "es", "ja", "zh", "..."], "credit_formula": { "unit_characters": 50, "unit_credits": 1, "round_up": true }, "emotions": ["auto", "happy", "sad", "angry", "fearful", "disgusted", "surprised", "neutral", "calm"] } ] }, { "provider": "elevenlabs", "models": [ { "model": "eleven-v3", "display_name": "Eleven v3", "provider": "elevenlabs", "max_characters": 5000, "supported_language_codes": ["auto", "en", "es", "..."], "credit_formula": { "unit_characters": 50, "unit_credits": 1, "round_up": true } } ] } ] } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` Only MiniMax (`speech-2.8-hd`, `speech-2.8-turbo`) models carry the `emotions` field — ElevenLabs models do not accept an `emotion` setting. `eleven-v3` auto-detects the language and rejects `language_code` on a generation. ##### Model The `default_model` and the text-to-speech models grouped by provider, each with its character limit, languages and credit formula. <details markdown="block" class="model-details"> <summary>The text-to-speech models by provider, field by field</summary> ```typescript { // TypeScript, all fields are optional default_model: string provider_groups: { provider: string models: { model: string display_name: string provider: string max_characters: number supported_language_codes: string[] credit_formula: { unit_characters: number unit_credits: number round_up: boolean } // present on MiniMax models only emotions: string[] }[] }[] } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v2/pixverse/speech/models" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = `https://api.useapi.net/v2/pixverse/speech/models`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" apiUrl = f"https://api.useapi.net/v2/pixverse/speech/models" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-speech-speech_id === Document URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-speech-speech_id --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> speech/`audio_id` description: "Poll a PixVerse text-to-speech job by audio_id via GET speech/audio_id in the useapi.net PixVerse API v2 — status values, audio_status_final flag, the mp3 url, and a live Try It console with playback." parent: PixVerse API nav_order: 1460 --- ## Retrieve generated speech June 25, 2026 (November 16, 2026) --- Use this endpoint to retrieve a generated speech clip. Attempting to retrieve a job that is still generating will return the current status. Poll until `audio_status_final` is `true`. To generate speech, use [POST speech/create](/docs/api-pixverse-v2/post-pixverse-speech-create). > **https://api.useapi.net/v2/pixverse/speech/`audio_id`** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Path parameter - `audio_id` is **required**. Specify the `audio_id` returned by [POST speech/create](/docs/api-pixverse-v2/post-pixverse-speech-create). The account email is encoded in the id, so no separate `email` is needed. ##### Responses **200** **200 OK** ```json { "audio_id": "user:<userid>-pixverse:<email>-speech:<number>", "asset_id": 11223344, "audio_status": 1, "status": "finish", "create_mode": "voice", "provider": "minimax", "model": "speech-2.8-hd", "voice_id": "minimax_english_radiant_girl", "voice_name": "Radiant Girl", "language_code": "en", "prompt": "May the Force be with you.", "url": "https://media.pixverse.ai/pixverse/audio/speech/11223344.mp3", "name": "PixVerse_Speech_11223344.mp3", "duration": 3, "credits": 1, "created_at": "2026-06-23T12:34:56Z", "updated_at": "2026-06-23T12:35:06Z", "audio_status_name": "COMPLETED", "audio_status_final": true } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** The speech clip was deleted or not found. ```json { "error": "Speech user:<userid>-pixverse:<email>-speech:<number> not found" } ``` ##### Audio Status Values | audio_status | audio_status_name | audio_status_final | Description | |:------------|:------------------|:-------------------|:------------| | 1 | COMPLETED | true | Speech ready, check `url` | | 5 | QUEUED | false | Accepted, waiting to start | | 8 | FAILED | true | Generation failed, see `fail_reason` | | 10 | GENERATING | false | Speech is being generated | When a job fails (`audio_status` 8) the response also carries `fail_code` and a human-readable `fail_reason` describing the underlying error. These are usually transient backend errors, so re-submitting the same request often succeeds. ##### Model The speech with its status, model, voice, language and audio `url`, plus `fail_code` and `fail_reason` when it failed. <details markdown="block" class="model-details"> <summary>The speech record, field by field</summary> ```typescript { // TypeScript, all fields are optional audio_id: string asset_id: number audio_status: number status: string create_mode: string provider: string model: string voice_id: string voice_name: string language_code: string prompt: string path: string url: string name: string duration: number file_size: number format: string sample_rate: number bitrate: number channel: number credits: number created_at: string updated_at: string // present only when audio_status is 8 (FAILED) fail_code: string fail_reason: string // added audio_status_name: string audio_status_final: boolean error: string } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v2/pixverse/speech/audio_id" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const audio_id = "audio_id to retrieve"; const apiUrl = `https://api.useapi.net/v2/pixverse/speech/${audio_id}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" audio_id = "audio_id to retrieve" apiUrl = f"https://api.useapi.net/v2/pixverse/speech/{audio_id}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-speech-voices === Document URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-speech-voices --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> speech/voices description: "List the available text-to-speech voices via GET speech/voices in the useapi.net PixVerse API v2 — filter by model and language, with voice_id, provider_voice_id, gender, accent, and preview url." parent: PixVerse API nav_order: 1480 --- ## List text-to-speech voices June 25, 2026 (November 16, 2026) --- List the voices available for [POST speech/create](/docs/api-pixverse-v2/post-pixverse-speech-create), filtered by model and language. Each [POST speech/create](/docs/api-pixverse-v2/post-pixverse-speech-create) request needs a `voice_id` from here — the paired `provider_voice_id` is derived from it automatically. The MiniMax catalog carries 300+ voices, ElevenLabs ~20. The provider is derived from the model, so you only pass `model` (and optionally `language`). > **https://api.useapi.net/v2/pixverse/speech/voices?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `email` is optional when only one [account](/docs/api-pixverse-v2/get-pixverse-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `model` is optional, default `speech-2.8-hd`. One of the [models](/docs/api-pixverse-v2/get-pixverse-speech-models) — the provider is derived from it. An unknown model is rejected with **400**. - `language` is optional, default `auto`. An ISO language code (`en`, `es`, `ja`, …) to filter the catalog to voices recommended for that language. ##### Responses **200** **200 OK** ```json { "voices": [ { "voice_id": "minimax_english_radiant_girl", "provider_voice_id": "English_radiant_girl", "display_name": "Radiant Girl", "provider": "minimax", "gender": "female", "age": "young", "accent": "", "style_tags": ["bright", "warm"], "recommended_languages": ["en"], "preview_url": "https://media.pixverse.ai/pixverse/audio/voice/preview/English_radiant_girl.mp3", "compatible_models": ["speech-2.8-hd", "speech-2.8-turbo"] } ], "pagination": { "total": 332, "has_more": false } } ``` **400** **400 Bad Request** Returned for an unknown `model`. ```json { "error": "Invalid model '<model>'. Valid values: speech-2.8-hd,speech-2.8-turbo,eleven-multilingual-v2,eleven-v3,eleven-turbo-v2.5", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model The voices in `voices`, each with its `voice_id`, name, gender, accent, `preview_url` and the models it works with, plus `pagination`. <details markdown="block" class="model-details"> <summary>The list of voices, field by field</summary> ```typescript { // TypeScript, all fields are optional voices: { voice_id: string provider_voice_id: string display_name: string provider: string gender: string age: string accent: string style_tags: string[] recommended_languages: string[] preview_url: string compatible_models: string[] }[] pagination: { total: number has_more: boolean } } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v2/pixverse/speech/voices?model=speech-2.8-hd&language=en" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = `https://api.useapi.net/v2/pixverse/speech/voices?model=speech-2.8-hd&language=en`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" apiUrl = f"https://api.useapi.net/v2/pixverse/speech/voices?model=speech-2.8-hd&language=en" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-speech === Document URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-speech --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> speech description: "List all PixVerse text-to-speech jobs — queued, generating, and completed — via GET speech in the useapi.net PixVerse API v2, with audio_status_name and audio_status_final." parent: PixVerse API nav_order: 1450 --- ## Retrieve the list of speech June 25, 2026 (November 16, 2026) --- Retrieve the list of text-to-speech jobs, this will include those currently being generated or queued. Check the `audio_status_name` field for the status and the field `audio_status_final` to determine if the provided status is the final status. The API internally uses the field `audio_status` to calculate values for `audio_status_name` and `audio_status_final`. See below for the known statuses map: | audio_status | audio_status_name | audio_status_final | |--------|-------------------|--------------------| | 1 | COMPLETED | true | | 5 | QUEUED | false | | 8 | FAILED | true | | 10 | GENERATING | false | > **https://api.useapi.net/v2/pixverse/speech/?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `email` is optional when only one [account](/docs/api-pixverse-v2/get-pixverse-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `limit` is optional, specify the number of clips to return. Default 50. - `offset` is optional, specify the offset from where to start. ##### Responses **200** **200 OK** This endpoint returns speech only (`create_mode: voice`). Music tracks are listed separately by [GET music](/docs/api-pixverse-v2/get-pixverse-music). ```json { "data": [ { "audio_id": "user:<userid>-pixverse:<email>-speech:11223344", "asset_id": 11223344, "audio_status": 1, "status": "finish", "create_mode": "voice", "provider": "minimax", "model": "speech-2.8-hd", "voice_id": "minimax_english_radiant_girl", "voice_name": "Radiant Girl", "language_code": "en", "prompt": "Use API dot net.", "url": "https://media.pixverse.ai/pixverse/audio/speech/11223344.mp3", "name": "PixVerse_Speech_11223344.mp3", "duration": 2, "credits": 1, "created_at": "2026-06-23T12:34:56Z", "updated_at": "2026-06-23T12:35:06Z", "audio_status_name": "COMPLETED", "audio_status_final": true } ], "next_offset": 50, "has_more": false } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model A page of speech in `data`, each with its status, voice, language and audio `url`, plus `next_offset` and `has_more`. <details markdown="block" class="model-details"> <summary>The list of speech, field by field</summary> ```typescript { // TypeScript, all fields are optional data: { audio_id: string asset_id: number audio_status: number status: string create_mode: string provider: string model: string voice_id: string voice_name: string language_code: string prompt: string url: string name: string duration: number credits: number created_at: string updated_at: string // added audio_status_name: string audio_status_final: boolean }[] next_offset: number has_more: boolean } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v2/pixverse/speech/?email=email" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const email= "Previously configured account email"; const apiUrl = `https://api.useapi.net/v2/pixverse/speech/?email=${email}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email= "Previously configured account email" apiUrl = f"https://api.useapi.net/v2/pixverse/speech/?email={email}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-videos-effects === Document URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-videos-effects --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> videos/effects description: "List all PixVerse effect templates via GET videos/effects in the useapi.net PixVerse API v2 — each entry includes effect_type, template_type, template_model, qualities, and credit cost." parent: PixVerse API nav_order: 1400 --- ## Retrieve the list of effects December 6, 2024 (November 16, 2026) --- The returned `effect_type` field encodes the number of input images the template accepts (as a string): - `"1"` = exactly one image (e.g., face swap, dance effects) - `"2"` = exactly two images (e.g., hug, kiss effects) - `"3"`, `"4"`, `"5"` = multi-input effects (e.g., Family Reunion accepts up to 5 portraits) — pass via `frame_1_path..frame_5_path` on [POST /videos/create](/docs/api-pixverse-v2/post-pixverse-videos-create-v4). For these templates, the minimum is 2 input images and the maximum is `effect_type`. The `template_type` field distinguishes output kind: - `1` = video output - `2` = image output (1-second still — the response carries `image_id` instead of `video_id`) The `template_model` field identifies the underlying engine (`v5`, `v5.5`, `v5.6`, `v6`, `image_v5`, `image_v6`, `image_v7`, `gemini-2.5-flash`, `gemini-3.0`, `qwen-image`, `""`). When you invoke a template, you do **not** need to (and should not) pass a `model` parameter — the template's engine is authoritative. The `qualities` field is the closed list of quality options the template accepts. Some templates only allow `["1080p"]` or `["360p", "540p", "720p"]` — calling with any other value is rejected. The total credit cost for a template is `video_base_cost + fixed_cost`. > **https://api.useapi.net/v2/pixverse/videos/effects?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `email` is optional when only one [account](/docs/api-pixverse-v2/get-pixverse-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. ##### Responses **200** **200 OK** ```json { "items": [ { "template_id": 384628677917440, "display_name": "Family Reunion", "workflow_tag": "meta_nanopro_muti_it2v_260115", "display_prompt": "This moment is what home means.", "effect_type": "5", "template_type": 1, "template_model": "v5", "template_paid": 1, "supported_features": [2], "duration": 5, "qualities": ["360p", "540p", "720p", "1080p"], "score": 8.42, "hot_count": 0, "created_at": "2026-04-15T07:12:08Z", "updated_at": "2026-05-12T00:01:54Z", "author_info": { "account_id": 1001075, "username": "", "nickname": "maxcasu", "avatar": "https://media.pixverse.ai/upload%2F…jpg" }, "category_ids": [157, 191], "video_base_cost": 20, "fixed_cost": 20, "example_text": "Upload 5 portrait photos", "thumbnail_path": "https://media.pixverse.ai/…jpg", "thumbnail_video_path": "https://media.pixverse.ai/…mp4", "thumbnail_gif_path": "https://media.pixverse.ai/…webp", "app_thumbnail_url": "https://media.pixverse.ai/…jpg", "app_thumbnail_video_url": "https://media.pixverse.ai/…mp4", "app_thumbnail_gif_url": "https://media.pixverse.ai/…webp", "audio_path": "https://media.pixverse.ai/…mp3", "marker": "" }, { "template_id": 377433499832192, "display_name": "Tattoo Removal", "workflow_tag": "i2i_image_v5_…", "display_prompt": "Remove tattoos cleanly from any photo.", "effect_type": "1", "template_type": 2, "template_model": "image_v5", "template_paid": 0, "supported_features": [2], "duration": 1, "qualities": ["1080p"], "score": 6.5, "hot_count": 0, "created_at": "2026-02-20T10:00:00Z", "updated_at": "2026-05-12T00:01:54Z", "author_info": { "account_id": 1001075, "username": "", "nickname": "pixverse", "avatar": "" }, "category_ids": [169], "video_base_cost": 20, "fixed_cost": 10, "example_text": "Upload a portrait with a visible tattoo", "thumbnail_path": "https://media.pixverse.ai/…jpg", "thumbnail_video_path": "", "thumbnail_gif_path": "", "app_thumbnail_url": "https://media.pixverse.ai/…jpg", "app_thumbnail_video_url": "", "app_thumbnail_gif_url": "", "audio_path": "", "marker": "" } ], "total": 917, "next_offset": 0 } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model A page of effect templates in `items`, each with its `template_id`, name, output type, allowed qualities, credit cost and thumbnails. <details markdown="block" class="model-details"> <summary>The list of effect templates, field by field</summary> ```typescript { // TypeScript items: { template_id: number display_name: string workflow_tag: string display_prompt: string effect_type: string // "1" or "2" = exact count required; "3"/"4"/"5" = multi-input (min 2, max effect_type) template_type: number // 1 = video output, 2 = image output (1-second still, returns image_id) template_model: string // engine: v5, v5.5, v5.6, v6, image_v5, image_v6, image_v7, gemini-2.5-flash, gemini-3.0, qwen-image, "" template_paid: number // 0 = free, 1 = paid tier required supported_features: number[] | null // feature flags (pass-through) duration: number // output duration in seconds (1 for image templates; 5–21 for video templates) qualities: string[] // allowed quality values — passing any other rejects with 400 score: number // popularity score hot_count: number // running engagement counter created_at: string // ISO timestamp the template was published updated_at: string // ISO timestamp of last metadata update author_info: { // template author account_id: number username: string nickname: string avatar: string // full URL or "" } category_ids: number[] // sub-category IDs this template belongs to video_base_cost: number // base credit cost fixed_cost: number // template-specific extra cost (template_paid templates typically charge fixed_cost) example_text: string // usage hint, e.g. "Upload 5 portrait photos" thumbnail_path: string // thumbnail URL (alias for app_thumbnail_url) thumbnail_video_path: string thumbnail_gif_path: string app_thumbnail_url: string // canonical thumbnail URL app_thumbnail_video_url: string app_thumbnail_gif_url: string audio_path: string // template's built-in audio track (full URL); empty when none marker: string // "new", "hot", "default", or "" }[] total: number next_offset: number } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v2/pixverse/videos/effects?email=email" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const email= "Previously configured account email"; const apiUrl = `https://api.useapi.net/v2/pixverse/videos/effects?email=${email}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email= "Previously configured account email" apiUrl = f"https://api.useapi.net/v2/pixverse/videos/effects?email={email}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-videos-video_id === Document URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-videos-video_id --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> videos/`video_id` description: "Retrieve a completed PixVerse video or image by video_id via GET videos/video_id in the useapi.net PixVerse API v2 — returns 404 while still processing." parent: PixVerse API nav_order: 700 --- ## Retrieve a generated video or image information December 6, 2024 (November 16, 2026) --- Use this endpoint to retrieve a generated video or image information. Attempting to retrieve a video that is still processing will result in a `404` response. Use [GET /videos](/docs/api-pixverse-v2/get-pixverse-videos) to retrieve all available videos. For dedicated image generation and retrieval, see [POST images/create](/docs/api-pixverse-v2/post-pixverse-images-create) and [GET images/image_id](/docs/api-pixverse-v2/get-pixverse-images-image_id). > **https://api.useapi.net/v2/pixverse/videos/`video_id`** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Path parameter - `video_id` is **required**. Specify the video_id or image_id you want to retrieve. ##### Responses **200** **200 OK** ```json { "video_id": "user:<userid>-pixverse:<email>-video:112233445566", "video_status": 1, "account_id": 33445566, "created_at": "2024-11-11T12:34:56Z", "first_frame": "https://media.pixverse.ai/....jpg", "output_width": 2560, "output_height": 1472, "original_video_id": "user:<userid>-pixverse:<email>-video:66778899", "upscaled": 1, "prompt": "<prompt>", "model": "v3", "negative_prompt": "<negative prompt>", "quality": "360p", "motion_mode": "normal", "asset_id": 0, "auto_character_prompt": 0, "seed": 0, "likes": 0, "model_name": "", "queue_data": { "queue_time": 1, "queue_count": 0 }, "video_duration": 5, "last_frame": "", "extended": 0, "lip_sync": null, "url": "https://media.pixverse.ai/...mp4", "img_id": 115994841, "img_url": "https://media.pixverse.ai/...webp", "duration": 5, "motion_brush": "", "asset_name": "", "asset_img_url": "", "remove_watermark": 1, "nick_name": "<name>", "avatar": "https://media.pixverse.ai/...jpeg", "aspect_ratio": "", "camera_movement": "default", "relation_type": 0, "style": "", "template_id": 307489548427968, "template_name": "Crazy Cat Woman", "template_thumbnail_url": "https://media.pixverse.ai/asset%2Ftemplate%2Fcatwoman.png", "template_thumbnail_video_url": "https://media.pixverse.ai/asset%2Ftemplate%2Fcatwoman.mp4", "template_i18n_json": "{\"zh-CN\":{\"display_name\":\"疯狂猫女变身\",\"display_prompt\":\"变身妖娆猫女,撩翻全场!\"}}", "workflow_tag": "", "customer_paths": null, "platform": "", "off_peak": 0, "video_status_name": "COMPLETED", "video_status_final": true } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** The video was deleted, not found, or is still processing. ```json { "error": "The original video has been deleted" } ``` A `seedance-2.5-draft` video and a final made from it carry a `seedance_draft` object: `expires_at` and `can_create_final` say whether the draft can still be finished with [POST videos/create-final](/docs/api-pixverse-v2/post-pixverse-videos-create-final), and `final_video_ids` / `source_draft_video_id` link the two. ##### Model The video with its prompt, model, dimensions, duration and `url`, and `video_status_name` and `video_status_final` to tell whether it has finished. <details markdown="block" class="model-details"> <summary>The video record, field by field, and what <code>queue_data</code> reports</summary> ```typescript { // TypeScript, all fields are optional video_id: string video_status: number account_id: number created_at: string first_frame: string output_width: number output_height: number original_video_id: number upscaled: number prompt: string model: string negative_prompt: string quality: string motion_mode: string asset_id: number auto_character_prompt: number seed: number likes: number model_name: string // Seedance 2.5 Draft Mode only, see POST videos/create-final seedance_draft?: { stage: 'draft' | 'final' validity_days?: number provider_created_at?: string expires_at?: string can_create_final?: boolean final_video_ids?: string[] source_draft_video_id?: string } queue_data?: { queue_time: number queue_count: number estimated_gen_time?: number processing_start_time?: string reason?: string slow_queue?: boolean platform?: string task_id?: number } video_duration: number last_frame: string extended: number lip_sync?: any original_sound_switch: number sound_effect_switch: number lip_sync_switch: number is_sound: number url: string video_path: string img_id: number img_url: string img_path: string customer_img_path?: string customer_img_url?: string duration: number motion_brush: string asset_name: string asset_img_url: string remove_watermark: number nick_name: string avatar: string aspect_ratio: string camera_movement: string relation_type: number style: string template_id: number template_name: string template_thumbnail_url: string template_thumbnail_video_url: string template_thumbnail_gif_url: string template_i18n_json: string workflow_tag: string customer_paths?: { customer_img_url?: string customer_img_path?: string lip_sync_audio_url?: string lip_sync_audio_path?: string lip_sync_tts_content?: string sound_effect_content?: string lip_sync_tts_audio_path?: string lip_sync_tts_speaker_id?: string customer_video_url?: string customer_video_path?: string customer_video_duration?: number customer_first_frame?: string customer_last_frame?: string customer_first_frame_url?: string customer_last_frame_url?: string customer_img_urls?: string[] customer_img_paths?: string[] customer_lip_sync_audio_path?: string } platform: string create_mode: string qualities?: string[] | null lora_weight: number restyle_id: number restyle_prompt: string off_peak: number // added video_status_name: string video_status_final: boolean error: string } ``` `queue_data` is present while a generation is waiting and reports its position — `queue_count` is the number of tasks ahead, `queue_time` the wait so far, and `estimated_gen_time` the projected generation time in seconds. It comes straight from PixVerse and is passed through unchanged. When `slow_queue` is `true` the account has been moved to a reduced-priority queue and `reason` says why. The value `daily_limit_exceeded` means the account has passed its daily allowance for that particular [unlimited Relax Mode model](/docs/api-pixverse-v2/post-pixverse-images-create) — the request is **not** rejected and still costs no credits, it just takes considerably longer. The allowance is per model, so the same account keeps running at full speed on every other model. Switch model, or spread the load across more accounts, if you see this persistently. </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v2/pixverse/videos/video_id" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const video_id = "video_id to retrieve"; const apiUrl = `https://api.useapi.net/v2/pixverse/videos/${video_id}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" video_id = "video_id to retrieve" apiUrl = f"https://api.useapi.net/v2/pixverse/videos/{video_id}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-videos-voices === Document URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-videos-voices --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> videos/voices description: "List available voice IDs for lipsync via GET videos/voices in the useapi.net PixVerse API v2 — use the returned IDs with POST videos/lipsync." parent: PixVerse API nav_order: 1300 --- ## Retrieve the list of voices for lipsync December 6, 2024 (November 16, 2026) --- > **https://api.useapi.net/v2/pixverse/videos/voices/?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `email` is optional when only one [account](/docs/api-pixverse-v2/get-pixverse-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. ##### Responses **200** **200 OK** ```json { "tts_list": [ { "speaker_id": "1", "url": "https://media.pixverse.ai/pixverse/mp3/lipsync/tts/1.mp3", "display_name": "Emily" }, { "speaker_id": "2", "url": "https://media.pixverse.ai/pixverse/mp3/lipsync/tts/2.mp3", "display_name": "James" }, { "speaker_id": "3", "url": "https://media.pixverse.ai/pixverse/mp3/lipsync/tts/3.mp3\n", "display_name": "Isabella" }, { "speaker_id": "4", "url": "https://media.pixverse.ai/pixverse/mp3/lipsync/tts/4.mp3", "display_name": "Liam" }, { "speaker_id": "5", "url": "https://media.pixverse.ai/pixverse/mp3/lipsync/tts/5.mp3", "display_name": "Chloe" }, { "speaker_id": "6", "url": "https://media.pixverse.ai/pixverse/mp3/lipsync/tts/6.mp3", "display_name": "Adrian" } ] } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model The voices for lip sync in `tts_list`, each with its `speaker_id`, display name and `url`. <details markdown="block" class="model-details"> <summary>The list of lip sync voices, field by field</summary> ```typescript { // TypeScript, all fields are optional tts_list: { speaker_id: string url: string display_name: string }[] } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v2/pixverse/videos/voices/?email=email" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const email= "Previously configured account email"; const apiUrl = `https://api.useapi.net/v2/pixverse/videos/voices/?email=${email}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email= "Previously configured account email" apiUrl = f"https://api.useapi.net/v2/pixverse/videos/voices/?email={email}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-videos === Document URL: https://useapi.net/docs/api-pixverse-v2/get-pixverse-videos --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> videos description: "List all PixVerse videos — queued, generating, and completed — via GET videos in the useapi.net PixVerse API v2, with video_status_name and video_status_final." parent: PixVerse API nav_order: 600 --- ## Retrieve the list of videos December 6, 2024 (November 16, 2026) --- Retrieve the list of videos, this will include those currently being generated or queued. Check the `video_status_name` field for the status and the field `video_status_final` to determine if the provided status is the final status. The API internally uses the field `video_status` to calculate values for `video_status_name` and `video_status_final`. See below for the known statuses map: | video_status | video_status_name | video_status_final | |--------|-------------------|--------------------| | 1 | COMPLETED | true | | 5 | QUEUED | false | | 7 | MODERATED | true | | 8 | FAILED | true | | 9 | GENERATING | false | | 10 | GENERATING | false | | 11 | MODERATED | true | | 12 | MODERATED | true | | 13 | MODERATED | true | | 17 | MODERATED | true | If field `off_peak` set to `1` that means this video will be generated during off-peak hours. > **https://api.useapi.net/v2/pixverse/videos/?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `email` is optional when only one [account](/docs/api-pixverse-v2/get-pixverse-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `limit` is optional, specify the number of videos to return. Default 40. - `offset` is optional, specify the offset from where to start. ##### Responses **200** **200 OK** ```json { "data": [ { "video_id": "user:<userid>-pixverse:<email>-video:11223344", "video_status": 10, "account_id": 33445566, "created_at": "2024-11-11T12:34:56Z", "first_frame": "", "output_width": 0, "output_height": 0, "original_video_id": 0, "upscaled": 0, "prompt": "<prompt>", "model": "v3", "negative_prompt": "", "quality": "540p", "motion_mode": "normal", "asset_id": 0, "auto_character_prompt": 0, "seed": 123456, "likes": 0, "model_name": "", "queue_data": { "queue_time": 1, "queue_count": 0 }, "video_duration": 5, "last_frame": "", "extended": 0, "lip_sync": {}, "url": "https://media.pixverse.ai/...mp4", "img_id": 55667788, "img_url": "https://media.pixverse.ai/...webp", "duration": 5, "motion_brush": "", "asset_name": "", "asset_img_url": "", "remove_watermark": 0, "nick_name": "<name>", "avatar": "https://media.pixverse.ai/...jpeg", "aspect_ratio": "3:4", "camera_movement": "default", "relation_type": 0, "style": "", "template_id": 0, "template_name": "", "template_thumbnail_url": "", "template_thumbnail_video_url": "", "template_i18n_json": "", "workflow_tag": "", "customer_paths": null, "platform": "", "video_status_name": "GENERATING", "off_peak": 0, "video_status_final": false }, { "video_id": "user:<userid>-pixverse:<email>-video:112233445566", "video_status": 1, "account_id": 33445566, "created_at": "2024-11-11T12:34:56Z", "first_frame": "https://media.pixverse.ai/....jpg", "output_width": 2560, "output_height": 1472, "original_video_id": "user:<userid>-pixverse:<email>-video:66778899", "upscaled": 1, "prompt": "<prompt>", "model": "v3", "negative_prompt": "<negative prompt>", "quality": "360p", "motion_mode": "normal", "asset_id": 0, "auto_character_prompt": 0, "seed": 0, "likes": 0, "model_name": "", "queue_data": { "queue_time": 1, "queue_count": 0 }, "video_duration": 5, "last_frame": "", "extended": 0, "lip_sync": null, "url": "https://media.pixverse.ai/...mp4", "img_id": 115994841, "img_url": "https://media.pixverse.ai/...webp", "duration": 5, "motion_brush": "", "asset_name": "", "asset_img_url": "", "remove_watermark": 1, "nick_name": "<name>", "avatar": "https://media.pixverse.ai/...jpeg", "aspect_ratio": "", "camera_movement": "default", "relation_type": 0, "style": "", "template_id": 307489548427968, "template_name": "Crazy Cat Woman", "template_thumbnail_url": "https://media.pixverse.ai/asset%2Ftemplate%2Fcatwoman.png", "template_thumbnail_video_url": "https://media.pixverse.ai/asset%2Ftemplate%2Fcatwoman.mp4", "template_i18n_json": "{\"zh-CN\":{\"display_name\":\"疯狂猫女变身\",\"display_prompt\":\"变身妖娆猫女,撩翻全场!\"}}", "workflow_tag": "", "customer_paths": null, "platform": "", "off_peak": 1, "video_status_name": "COMPLETED", "video_status_final": true } ], "next_offset": 40, "total": 55 } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model A page of videos, including those still queued or generating, each with its status, prompt, model and `url`, plus `next_offset` and `total`. <details markdown="block" class="model-details"> <summary>The list of videos, field by field, and what <code>queue_data</code> reports</summary> ```typescript { // TypeScript, all fields are optional { video_id: string video_status: number account_id: number created_at: string first_frame: string output_width: number output_height: number original_video_id: number upscaled: number prompt: string model: string negative_prompt: string quality: string motion_mode: string asset_id: number auto_character_prompt: number seed: number likes: number model_name: string queue_data?: { queue_time: number queue_count: number estimated_gen_time?: number processing_start_time?: string reason?: string slow_queue?: boolean platform?: string task_id?: number } video_duration: number last_frame: string extended: number lip_sync?: any original_sound_switch: number sound_effect_switch: number lip_sync_switch: number is_sound: number url: string video_path: string img_id: number img_url: string img_path: string customer_img_path?: string customer_img_url?: string duration: number motion_brush: string asset_name: string asset_img_url: string remove_watermark: number nick_name: string avatar: string aspect_ratio: string camera_movement: string relation_type: number style: string template_id: number template_name: string template_thumbnail_url: string template_thumbnail_video_url: string template_thumbnail_gif_url: string template_i18n_json: string workflow_tag: string customer_paths?: { customer_img_url?: string customer_img_path?: string lip_sync_audio_url?: string lip_sync_audio_path?: string lip_sync_tts_content?: string sound_effect_content?: string lip_sync_tts_audio_path?: string lip_sync_tts_speaker_id?: string customer_video_url?: string customer_video_path?: string customer_video_duration?: number customer_first_frame?: string customer_last_frame?: string customer_first_frame_url?: string customer_last_frame_url?: string customer_img_urls?: string[] customer_img_paths?: string[] customer_lip_sync_audio_path?: string } platform: string create_mode: string qualities?: string[] | null lora_weight: number restyle_id: number restyle_prompt: string off_peak: number // added video_status_name: string video_status_final: boolean }[] next_offset: number total: number } ``` `queue_data` is present while a generation is waiting and reports its position — `queue_count` is the number of tasks ahead, `queue_time` the wait so far, and `estimated_gen_time` the projected generation time in seconds. It comes straight from PixVerse and is passed through unchanged. When `slow_queue` is `true` the account has been moved to a reduced-priority queue and `reason` says why. The value `daily_limit_exceeded` means the account has passed its daily allowance for that particular [unlimited Relax Mode model](/docs/api-pixverse-v2/post-pixverse-images-create) — the request is **not** rejected and still costs no credits, it just takes considerably longer. The allowance is per model, so the same account keeps running at full speed on every other model. Switch model, or spread the load across more accounts, if you see this persistently. </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v2/pixverse/videos/?email=email" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const email= "Previously configured account email"; const apiUrl = `https://api.useapi.net/v2/pixverse/videos/?email=${email}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email= "Previously configured account email" apiUrl = f"https://api.useapi.net/v2/pixverse/videos/?email={email}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-pixverse-v2/mcp === Document URL: https://useapi.net/docs/api-pixverse-v2/mcp --- layout: default title: MCP Server nav_icon: mcp seo_title: "PixVerse MCP Server: V6, Seedance 2.5 and Kling 4.0 Video, Images, Music" description: "Connect the Claude app, ChatGPT, Claude Code or any MCP client to the hosted useapi.net PixVerse MCP server: 38 tools for PixVerse video, effects, images, music and speech." parent: PixVerse API nav_order: 55 permalink: /docs/api-pixverse-v2/mcp --- ## PixVerse MCP Server November 20, 2026 --- The useapi.net PixVerse MCP server lets an AI assistant such as the Claude app, ChatGPT, Claude Code, Cursor or VS Code Copilot make videos, images, music and speech with [PixVerse](https://pixverse.ai) on your own PixVerse accounts. It is a hosted [Model Context Protocol](https://modelcontextprotocol.io) server with 38 tools: generate videos with PixVerse's own models and third-party ones such as Seedance 2.5 from text, an image, an effect template, first and last frames, keyframes or reference images, then extend, modify, lip-sync or upscale them, animate a character image with motion control, generate and upscale images, make songs, music videos and speech, upload your own files and clean up your PixVerse history. Each tool calls the [PixVerse API](/docs/api-pixverse-v2), so the same rules and limits apply. Nothing needs to be installed or hosted. **Is there a PixVerse MCP server?** Yes. useapi.net, a third-party service not affiliated with PixVerse, hosts one at `https://api.useapi.net/v2/pixverse/mcp` with 38 tools for PixVerse video, effects, images, music and speech on your own PixVerse subscription, nothing to install. Prefer REST? Code: [github.com/useapi/pixverse-api](https://github.com/useapi/pixverse-api) See all useapi.net MCP servers on [Model Matrix & MCP](/model-matrix#mcp-servers). ## Endpoint and authorization ``` https://api.useapi.net/v2/pixverse/mcp ``` - Transport: Streamable HTTP. - Listed in the [official MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers/net.useapi%2Fpixverse/versions/latest) as `net.useapi/pixverse`, so MCP clients and directories that read the registry can find it by that name. - The path is `/v2/`, because the server sits on version 2 of the PixVerse API. The other useapi.net MCP servers use `/v1/`. - Authorization: your useapi.net API token in the `Authorization: Bearer …` header, see [Setup useapi.net](/docs/start-here/setup-useapi). The Claude app and ChatGPT sign in with OAuth instead, see [Use it in the Claude app or ChatGPT](#use-it-in-the-claude-app-or-chatgpt). - You need at least one PixVerse account added with [Setup PixVerse](/docs/start-here/setup-pixverse). Adding and removing accounts is not available over MCP: use [POST accounts/email](/docs/api-pixverse-v2/post-pixverse-accounts-email) or the setup page. ## Setup Replace `YOUR_API_TOKEN` with your useapi.net API token. ### Claude Code ```bash claude mcp add --transport http useapi-pixverse https://api.useapi.net/v2/pixverse/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` ### Cursor In `~/.cursor/mcp.json`: ```json { "mcpServers": { "useapi-pixverse": { "url": "https://api.useapi.net/v2/pixverse/mcp", "headers": { "Authorization": "Bearer YOUR_API_TOKEN" } } } } ``` ### VS Code In `.vscode/mcp.json`: ```json { "servers": { "useapi-pixverse": { "type": "http", "url": "https://api.useapi.net/v2/pixverse/mcp", "headers": { "Authorization": "Bearer YOUR_API_TOKEN" } } } } ``` ### Windsurf and other clients Any client that supports remote MCP servers over HTTP with custom headers works. The usual JSON shape: ```json { "mcpServers": { "useapi-pixverse": { "serverUrl": "https://api.useapi.net/v2/pixverse/mcp", "headers": { "Authorization": "Bearer YOUR_API_TOKEN" } } } } ``` Some clients name the address field `url` instead of `serverUrl`. ### Test it with curl ```bash curl -s https://api.useapi.net/v2/pixverse/mcp \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}' curl -s https://api.useapi.net/v2/pixverse/mcp \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' ``` The first call answers with the server's name `useapi-pixverse` and its instructions for the assistant, the second with the 38 tools. ## Use it in the Claude app or ChatGPT The Claude app ([claude.ai](https://claude.ai) and Claude Desktop) and [ChatGPT](https://chatgpt.com) can add this server as a custom connector. They sign in with OAuth: you give the app the URL, it opens a useapi.net page, and you paste your useapi.net API token there once. Both work on their Free plans. The API-token setups above for Claude Code, Cursor, VS Code and other clients keep working as before. ``` ``` ### Claude app 1. Open Settings → Connectors and click Add custom connector. 2. Enter a name, for example `useapi `, and the URL above, then click Add. 3. Click Connect. Claude opens the useapi.net sign-in page. 4. Paste your useapi.net API token and click Allow. Claude asks before each tool call unless you choose Always allow. The Free plan allows one custom connector. ### ChatGPT 1. Open Plugins, click Add and choose Add custom MCP server. 2. Enter a name and the URL above, and set Authentication to OAuth. 3. Tick ChatGPT's "I understand and want to continue" box, then click Create as a plugin. 4. Click Connect. ChatGPT opens the useapi.net sign-in page. 5. Paste your useapi.net API token and click Allow. ChatGPT asks you to confirm each tool call that creates or changes something. The Free plan works without developer mode (as of October 25, 2026). ### How the sign-in works - Your API token is in your welcome email, see [Setup useapi.net](/docs/start-here/setup-useapi). The useapi.net page links there too. - Each connection is for one MCP server. Connect each server you want to use on its own. - The app gets an access token that lasts 1 hour and renews it on its own. A connection you don't use for 90 days lapses, and you connect again. - [Resetting your API token](/docs/account-management/post-account-token-reset) disconnects every app connected with it. - - Results come back as public links, so they open right in the app. ## Tools Accounts are named by their email. Tools that start a job take an optional `email`, and without it a random account with a free slot is picked. A job on an existing video or image (`video_id`, `image_id`) runs on that video's or image's account, because the id names it. Files uploaded with `pixverse_upload_file` work on any of your accounts. Tools that read one account's lists need `email` only when more than one account is added. Every create tool also takes `maxJobs` (1 to 8) to override the account's jobs at once for that request, and `wait`. ### Accounts and files | Tool | What it does | Main parameters | |---|---|---| | `pixverse_list_accounts` | Lists your accounts as stored: email, `maxJobs`, session expiry and any pending account error, without calling PixVerse. | | | `pixverse_get_account` | One account's stored settings: email, `maxJobs`, the session's expiry and any pending error, without calling PixVerse. | `email` | | `pixverse_get_features` | Reads an account's PixVerse plan live: plan name, credit balances, refresh and expiry dates, generations at once, and the image models and video qualities the plan allows. | `email` | | `pixverse_upload_file` | Uploads your own image (PNG, JPEG, GIF or WebP), video (MP4, MOV, WebM and more) or audio (WAV or MP3), up to 50 MB, from a public https URL or sent as `contentBase64`. Returns the file's path for the `*_path` parameters of the other tools. Uploads cannot be deleted. | `url` or `contentBase64`, `mimeType`, `email` | The parameters match [GET accounts](/docs/api-pixverse-v2/get-pixverse-accounts), [GET accounts/email](/docs/api-pixverse-v2/get-pixverse-accounts-email), [GET features](/docs/api-pixverse-v2/get-pixverse-features) and [POST files](/docs/api-pixverse-v2/post-pixverse-files). ### Images | Tool | What it does | Main parameters | |---|---|---| | `pixverse_create_image` | Generates 1 to 4 images with Qwen Image (the default), Nano Banana, Seedream, GPT Image or Kling image models, from a prompt and up to 16 reference images, by model. In Relax Mode it is free where the plan includes the model. The first image comes back as an image the assistant can see. | `prompt`, `model`, `quality`, `aspect_ratio`, `detail_level`, `create_count`, `image_paths`, `seed`, `relax_mode`, `email` | | `pixverse_get_image` | Reads one image, and with `wait: true` waits for it to finish. A finished image comes with its `image_url`, size and credits used, and as an image block. | `image_id`, `wait` | | `pixverse_list_images` | Lists one account's images, including those still queued or generating and those made on pixverse.ai, page by page. | `email`, `offset`, `limit` | | `pixverse_upscale_image` | Upscales a PixVerse image or your own upload with PixVerse Upscale or Topaz Gigapixel, up to 4K. `quote: true` answers the exact price in credits and creates nothing. | `image_id` or `image_path`, `model`, `quality`, `quote` | | `pixverse_delete_image` | Deletes one image from its PixVerse account. It cannot be undone. | `image_id` | The parameters match [POST images/create](/docs/api-pixverse-v2/post-pixverse-images-create), [GET images/image_id](/docs/api-pixverse-v2/get-pixverse-images-image_id), [GET images](/docs/api-pixverse-v2/get-pixverse-images), [POST images/upscale](/docs/api-pixverse-v2/post-pixverse-images-upscale) and [DEL images/image_id](/docs/api-pixverse-v2/del-pixverse-images-image_id). The numbered reference images of the REST API (`image_path_1`, `image_path_2` and so on) are the list `image_paths` here. ### Videos | Tool | What it does | Main parameters | |---|---|---| | `pixverse_create_video` | Generates a video from text, an image or an effect template with PixVerse V6 (the default), C1, V5.x or third-party models such as Seedance 2.5, Kling 4.0, Veo 3.1 and MiniMax H3. Third-party models need a Pro plan or higher. | `prompt`, `model`, `duration`, `quality`, `aspect_ratio`, `first_frame_path`, `template_id`, `template_images`, `audio`, `multi_shot`, `preview_mode`, `off_peak_mode`, `relax_mode`, `email` | | `pixverse_create_video_frames` | Generates a video that moves from a first frame to a last frame, with V5.6 (the default), V5.5, V5, V6, C1 or third-party models. | `first_frame_path`, `last_frame_path`, `prompt`, `model`, `duration`, `quality`, `audio`, `off_peak_mode` | | `pixverse_create_transition` | Generates one video through 2 to 7 keyframes in order, each move with its own prompt and duration, with V5, V5.5 or V5.6 (3 or more frames on V5 only). | `frames`, `model`, `quality`, `audio`, `off_peak_mode` | | `pixverse_create_video_fusion` | Generates a video from reference images, and on the models that take them reference videos and audio, cited in the prompt as `@image1`, `@video1` or `@audio1` (PixVerse's Reference mode). | `prompt`, `image_paths`, `video_paths`, `audio_paths`, `model`, `duration`, `quality`, `aspect_ratio`, `audio` | | `pixverse_create_final_video` | Renders a finished `seedance-2.5-draft` video again with Seedance 2.5 at 1080p or 4K, while the draft is valid (drafts are kept 14 days). | `video_id`, `quality`, `relax_mode` | | `pixverse_extend_video` | Continues a PixVerse video or your own upload from its last frame with V6 or Grok Imagine. | `video_id` or `video_path`, `model`, `prompt`, `duration`, `quality`, `audio` | | `pixverse_modify_video` | Changes what is in a PixVerse video or your own upload by a prompt, with V5.5 at 360p, 540p or 720p. | `prompt`, `video_id` or `video_path`, `quality` | | `pixverse_motion_control` | Makes the person or animal in a character image move like the subject of a reference video, with V5.6 and no prompt. | `image_path`, `video_path`, `quality` | | `pixverse_lipsync_video` | Makes the person in a video speak, from your own audio of up to 60 seconds or from text read by a lip-sync voice, with V5. | `video_id` or `video_path`, `audio_path` or `prompt` with `speaker_id`, `original_sound_switch` | | `pixverse_upscale_video` | Upscales a PixVerse video or your own MP4 or MOV upload of up to 3 minutes with PixVerse Upscale or Topaz Proteus, Starlight Fast or Starlight Precise, to 1080p or 4K. `quote: true` answers the exact price in credits and creates nothing. | `video_id` or `video_path`, `model`, `quality`, `quote` | The parameters match [POST videos/create](/docs/api-pixverse-v2/post-pixverse-videos-create-v4), [POST videos/create-frames](/docs/api-pixverse-v2/post-pixverse-videos-create-frames-v4), [POST videos/create-transition](/docs/api-pixverse-v2/post-pixverse-videos-create-transition), [POST videos/create-fusion](/docs/api-pixverse-v2/post-pixverse-videos-create-fusion), [POST videos/create-final](/docs/api-pixverse-v2/post-pixverse-videos-create-final), [POST videos/extend](/docs/api-pixverse-v2/post-pixverse-videos-extend-v4), [POST videos/modify](/docs/api-pixverse-v2/post-pixverse-videos-modify), [POST videos/motion-control](/docs/api-pixverse-v2/post-pixverse-videos-motion-control), [POST videos/lipsync](/docs/api-pixverse-v2/post-pixverse-videos-lipsync) and [POST videos/upscale](/docs/api-pixverse-v2/post-pixverse-videos-upscale). Durations, qualities and ratios of each model are on [Model capabilities](/docs/api-pixverse-v2/model-capabilities). The numbered fields of the REST API are lists here: - `image_paths`, `video_paths` and `audio_paths` of `pixverse_create_video_fusion` stand for `frame_N_path`, `video_N_path` and `audio_N_path`. The first item of `image_paths` is `@image1` in the prompt, the second `@image2`. - `template_images` of `pixverse_create_video` holds up to 5 images for a multi-input effect template, in place of `frame_1_path` to `frame_5_path`. - `frames` of `pixverse_create_transition` is a list of keyframes, each with its `path` and the `prompt` and `duration` of the move to the next frame, in place of `frame_N_path`, `prompt_N_to_M` and `duration_N_to_M`. ### Video reads, effects and voices | Tool | What it does | Main parameters | |---|---|---| | `pixverse_get_video` | Reads one video from any create, extend, modify, lip-sync or upscale tool, and with `wait: true` waits for it to finish. A finished video comes with its `url`, size, duration and model, and a Seedance 2.5 draft says whether it can still be rendered in full and when it expires. | `video_id`, `wait` | | `pixverse_list_videos` | Lists one account's videos, including those still queued or generating, music videos and those made on pixverse.ai, page by page. | `email`, `offset`, `limit` | | `pixverse_delete_video` | Deletes one video or music video from its PixVerse account. It cannot be undone. | `video_id` | | `pixverse_list_effects` | Lists PixVerse's more than 900 effect templates for `pixverse_create_video`, with each template's id, name, number of input images, model, qualities, duration and example prompt. `search` finds them by name or prompt. | `search`, `offset`, `limit` | | `pixverse_list_lipsync_voices` | Lists the voices for lip-sync speech, with a sample of each, for `pixverse_lipsync_video` and the V5 lines of `pixverse_create_video`. | `email` | The parameters match [GET videos/video_id](/docs/api-pixverse-v2/get-pixverse-videos-video_id), [GET videos](/docs/api-pixverse-v2/get-pixverse-videos), [DEL videos/video_id](/docs/api-pixverse-v2/del-pixverse-videos-video_id), [GET videos/effects](/docs/api-pixverse-v2/get-pixverse-videos-effects) and [GET videos/voices](/docs/api-pixverse-v2/get-pixverse-videos-voices). ### Music and music videos | Tool | What it does | Main parameters | |---|---|---| | `pixverse_create_music` | Generates a song or an instrumental from a prompt with MiniMax Music 2.6 (the default), ElevenLabs Music v1 or Google Lyria 3 Pro: your own lyrics on Music 2.6 and v1, or lyrics the model writes, and up to 10 reference images on Lyria 3 Pro. | `prompt`, `model`, `lyrics`, `instrumental`, `image_paths`, `email` | | `pixverse_get_music` | Reads one track, and with `wait: true` waits for it to finish. A finished track comes with its mp3 `url`, duration and model. | `audio_id`, `wait` | | `pixverse_list_music` | Lists one account's music tracks, page by page. | `email`, `offset`, `limit` | | `pixverse_create_music_video` | Makes a full music video from a song (an uploaded MP3 of 10 seconds to 6 minutes, or a library song) and optionally a character photo: performance, expressive or storytelling mode, a style, lyric captions, 720p or 1080p. The first music video of every account is free. `quote: true` answers the exact price and creates nothing. | `audio_path`, `mode`, `style`, `image_path`, `subtitles`, `lyrics`, `prompt`, `aspect_ratio`, `quality`, `quote` | | `pixverse_get_music_video` | Reads one music video, and with `wait: true` waits for it to finish. A finished one comes with the video and extra files such as the copy without captions. | `video_id`, `wait` | | `pixverse_list_music_videos` | Lists one account's music videos, page by page. | `email`, `offset`, `limit` | | `pixverse_list_music_video_library` | Lists PixVerse's built-in songs, characters and styles for `pixverse_create_music_video`, for when you have no song or photo of your own. | `type` | The parameters match [POST music/create](/docs/api-pixverse-v2/post-pixverse-music-create), [GET music/music_id](/docs/api-pixverse-v2/get-pixverse-music-music_id), [GET music](/docs/api-pixverse-v2/get-pixverse-music), [POST music-video/create](/docs/api-pixverse-v2/post-pixverse-music-video-create), [GET music-video/video_id](/docs/api-pixverse-v2/get-pixverse-music-video-video_id), [GET music-video](/docs/api-pixverse-v2/get-pixverse-music-video) and [GET music-video/library](/docs/api-pixverse-v2/get-pixverse-music-video-library). The numbered reference images of POST music/create (`image_path_1` to `image_path_10`) are the list `image_paths` here. ### Speech | Tool | What it does | Main parameters | |---|---|---| | `pixverse_create_speech` | Turns text into speech with MiniMax Speech 2.8 HD (the default) or Turbo, or ElevenLabs Multilingual v2, v3 or Turbo v2.5, with voice settings such as speed, pitch and emotion on MiniMax, and stability and similarity on ElevenLabs. | `text`, `voice_id`, `model`, `language_code`, `speed`, `volume`, `pitch`, `emotion`, `stability`, `similarity_boost` | | `pixverse_get_speech` | Reads one speech clip, and with `wait: true` waits for it to finish. A finished clip comes with its audio `url`, duration, voice and language. | `audio_id`, `wait` | | `pixverse_list_speech` | Lists one account's speech clips, page by page. | `email`, `offset`, `limit` | | `pixverse_list_speech_voices` | Lists the text-to-speech voices of one model's provider, with gender, age, accent, languages and a preview, page by page. `language` narrows them to voices for that language. | `model`, `language`, `offset`, `limit` | | `pixverse_list_speech_models` | Lists the text-to-speech models live from PixVerse, with each model's character limit, languages and credit formula. | `email` | The parameters match [POST speech/create](/docs/api-pixverse-v2/post-pixverse-speech-create), [GET speech/speech_id](/docs/api-pixverse-v2/get-pixverse-speech-speech_id), [GET speech](/docs/api-pixverse-v2/get-pixverse-speech), [GET speech/voices](/docs/api-pixverse-v2/get-pixverse-speech-voices) and [GET speech/models](/docs/api-pixverse-v2/get-pixverse-speech-models). ### Running jobs | Tool | What it does | Main parameters | |---|---|---| | `pixverse_list_running_jobs` | Lists the videos, images, music and speech the API is tracking now and, per account, `maxJobs` with its running and free slots. Jobs started on pixverse.ai or in Off-Peak mode are not tracked. | | | `pixverse_cancel_job` | Stops tracking a running job and frees its slot on the account. It does not stop the job at PixVerse. | `id` | The parameters match [GET scheduler/available](/docs/api-pixverse-v2/get-pixverse-scheduler-available) and [DEL scheduler/id](/docs/api-pixverse-v2/del-pixverse-scheduler-video_id). The full input schema of every tool comes from `tools/list`. ## Long-running work MCP clients usually give up on a tool call after about a minute, so a tool waits up to about 50 seconds: - A quick result can come back from the create tool itself. - Otherwise the tool returns the id, and the matching get tool (`pixverse_get_video`, `pixverse_get_image`, `pixverse_get_music`, `pixverse_get_speech` or `pixverse_get_music_video`) with `wait: true` picks it up. Ask the assistant to keep checking until it is done. - A job in Off-Peak mode (`off_peak_mode: true`) is not waited for: the tool returns its `video_id` at once, and `pixverse_get_video` reads it later. Clients that ask for progress notifications get one about every 10 seconds while a tool waits. Videos, images, music and speech come back as public `media.pixverse.ai` links. ## Example prompts - "Make a 5-second PixVerse V6 video at 1080p with sound of a paper boat drifting down a rainy street at night." - "Find a PixVerse effect with 'hug' in its name and use it on this photo." - "Upload these two photos and make a video that moves from the first one to the second." - "Make a Seedance 2.5 draft of this prompt, and if it looks right, render it in 4K." - "Generate an image of a cozy mountain cabin in winter, then upscale it to 4K." - "How many credits would it cost to upscale this video to 4K with Topaz Starlight Fast?" - "Make a music video from this MP3 with my photo as the performer, 9:16, with lyric captions." - "Read this paragraph aloud with an ElevenLabs v3 voice." - "How many credits are left on my PixVerse account?" ## Limits and notes - The tools use your PixVerse accounts and the same rules as the REST API, such as `maxJobs` and the models of each plan. Generations use the account's PixVerse credits, see [Pricing](/docs/api-pixverse-v2#pricing), and `pixverse_get_features` shows what is left. Upscales and music videos take `quote: true` for a free exact price. - A 412 means the plan or the credits do not allow that job. A 429 means your accounts are at `maxJobs`: check `pixverse_list_running_jobs` and retry later. - A client may send up to 20 JSON-RPC requests in one batch. - If the client sends an `MCP-Protocol-Version` header, it must be one of the supported versions: `2025-11-25`, `2025-06-18`, `2025-03-26` or `2024-11-05`. - Tool calls show in your [usage stats](/docs/account-management/get-account-stats) (`bot=pixverse`) through the REST call each tool makes, the same rows a direct API request writes. === URL: https://useapi.net/docs/api-pixverse-v2/model-capabilities === Document URL: https://useapi.net/docs/api-pixverse-v2/model-capabilities --- layout: default title: Model Capabilities description: "Compare per-model constraints and endpoint compatibility for all PixVerse video, image, music and music video models in the useapi.net PixVerse API v2 — quality, duration, lyrics, and modes." parent: PixVerse API nav_order: 50 --- December 5, 2025 (November 15, 2026) --- # Video Models ## Endpoint Compatibility | Model | [create](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) | [create-frames](/docs/api-pixverse-v2/post-pixverse-videos-create-frames-v4) | [create-fusion](/docs/api-pixverse-v2/post-pixverse-videos-create-fusion) | [motion-control](/docs/api-pixverse-v2/post-pixverse-videos-motion-control) | |-------|:-:|:-:|:-:|:-:| | `v6` *(default)* | Yes | Yes | — | — | | `v5.6` | Yes | Yes | Yes | Yes | | `pixverse-c1` | Yes | Yes | Yes | — | | `seedance-2.5` | Yes | Yes | Yes (+10 ref videos, +10 ref audios) | — | | `seedance-2.5-flash` | Yes | Yes | Yes (+5 ref videos, +5 ref audios) | — | | `seedance-2.5-draft` | Yes | Yes | Yes (+10 ref videos, +10 ref audios) | — | | `seedance-2.0` | Yes | Yes | Yes (+3 ref videos, +3 ref audios) | — | | `seedance-2.0-fast` | Yes | Yes | Yes (+3 ref videos, +3 ref audios) | — | | `seedance-2.0-mini` | Yes | Yes | Yes (+3 ref videos, +3 ref audios) | — | | `kling-4.0` | Yes | Yes | Yes (+5 ref videos) | — | | `kling-o3` | Yes | Yes | Yes | — | | `kling-v3` | Yes | Yes | — | — | | `grok-imagine` | Yes | — | — | — | | `grok-imagine-1.5` | Yes *(i2v only)* | — | — | — | | `veo-3.1-lite` | Yes | Yes | — | — | | `veo-3.1-standard` | Yes | Yes | — | — | | `veo-3.1-fast` | Yes | Yes | — | — | | `happyhorse-1.0` | Yes | — | — | — | | `minimax-h3` | Yes | Yes | Yes | — | | `minimax-h3-max` | Yes | Yes | Yes | — | | `gemini-omni-flash` | Yes | — | Yes (+3 ref videos) | — | | `flux-3.0` | Yes | — | — | — | | `wan-3.0` | Yes | Yes | Yes (+5 ref videos, +5 ref audios) | — | Sora 2 is no longer available: OpenAI shut it down on September 24, 2026. Fusion notation: `v5` uses `@pic1`/`@pic2`/`@pic3`, all other fusion-capable models use `@image1`…`@imageN` (mapped positionally to `frame_1_path`…`frame_N_path`). The Seedance fusion family additionally supports `@video1`…`@videoN` for reference videos (`video_1_path`…`video_N_path`) and `@audio1`…`@audioN` for reference audios (`audio_1_path`…`audio_N_path`) — PixVerse's omni mode. `seedance-2.5` and `seedance-2.5-draft` take up to 10 of each and 30 images, `seedance-2.5-flash` 5 of each and 10 images, the 2.0 family 3 of each and 9 images. `wan-3.0` takes 5 of each alongside 10 images. `gemini-omni-flash` takes reference videos too — up to 3, alongside 5 images — but no reference audios. `kling-4.0` takes up to 5 reference videos alongside 10 images, and no reference audios. `grok-imagine-1.5` is image-to-video only — it requires `first_frame_path` and rejects text-to-video (no-image) requests. The original `grok-imagine` supports both text-to-video and image-to-video. ### Extend, upscale, modify, lipsync Modify and lipsync are native-PixVerse only. Extend supports `v6` and the third-party `grok-imagine` model. [Create-final](/docs/api-pixverse-v2/post-pixverse-videos-create-final) takes only a finished `seedance-2.5-draft` video and renders it with `seedance-2.5` at 1080p or 2160p. [Upscale](/docs/api-pixverse-v2/post-pixverse-videos-upscale) works on a video from any model, and on your own uploaded videos and [images](/docs/api-pixverse-v2/post-pixverse-images-upscale). | Endpoint | `v6` | `v5` | `v5.5` | `v5.6` | |----------|:-:|:-:|:-:|:-:| | [extend](/docs/api-pixverse-v2/post-pixverse-videos-extend-v4) | Yes | — | — | — | | [upscale](/docs/api-pixverse-v2/post-pixverse-videos-upscale) | Yes | Yes | Yes | Yes | | [modify](/docs/api-pixverse-v2/post-pixverse-videos-modify) | — | — | Yes | — | | [lipsync](/docs/api-pixverse-v2/post-pixverse-videos-lipsync) | — | Yes | — | — | [extend](/docs/api-pixverse-v2/post-pixverse-videos-extend-v4) also accepts `grok-imagine` (480p/720p, 2-10s, native audio). ### v5 family (legacy) v5 carries legacy-only modes — multi-frame [create-transition](/docs/api-pixverse-v2/post-pixverse-videos-create-transition), [lipsync](/docs/api-pixverse-v2/post-pixverse-videos-lipsync), and fusion with the original `@pic1/@pic2/@pic3` notation. | Endpoint | `v5` | `v5.5` | `v5.6` | `v5-fast` | |----------|:-:|:-:|:-:|:-:| | [create](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) | Yes | Yes | Yes | Yes | | [create-frames](/docs/api-pixverse-v2/post-pixverse-videos-create-frames-v4) | Yes | Yes | Yes | — | | [create-transition](/docs/api-pixverse-v2/post-pixverse-videos-create-transition) (2-frame) | Yes | Yes | Yes | — | | [create-transition](/docs/api-pixverse-v2/post-pixverse-videos-create-transition) (3+ frame) | Yes | — | — | — | | [create-fusion](/docs/api-pixverse-v2/post-pixverse-videos-create-fusion) | Yes | — | Yes | — | | [extend](/docs/api-pixverse-v2/post-pixverse-videos-extend-v4) | — | — | — | — | | [modify](/docs/api-pixverse-v2/post-pixverse-videos-modify) | — | Yes | — | — | | [lipsync](/docs/api-pixverse-v2/post-pixverse-videos-lipsync) | Yes | — | — | — | | [upscale](/docs/api-pixverse-v2/post-pixverse-videos-upscale) | Yes | Yes | Yes | Yes | `v5` accepts both `@image1`…`@imageN` (unified) and the legacy `@pic1`/`@pic2`/`@pic3` synonyms for backward compatibility. ## Quality, Duration, Aspect Ratio | Model | Qualities | Durations | Aspect Ratios | Max ref (fusion) | |-------|-----------|-----------|---------------|:-:| | `v6` | 360p, 540p, 720p *(default)*, 1080p | 1-15s | 16:9, 9:16, 1:1, 4:3, 3:4 | — | | `v5.6` | 360p, 540p *(default)*, 720p, 1080p | 1-10s (1080p max 8) | 16:9, 9:16, 1:1, 4:3, 3:4 | 7 imgs | | `v5.5` | 360p, 540p *(default)*, 720p, 1080p | 1-10s (1080p max 8) | 16:9, 9:16, 1:1, 4:3, 3:4 | — | | `v5` | 360p, 540p *(default)*, 720p, 1080p | 1-10s (1080p max 8) | 16:9, 9:16, 1:1, 4:3, 3:4 | 3 imgs | | `v5-fast` | 360p, 540p *(default)*, 720p, 1080p | 1-10s (1080p max 8) | 16:9, 9:16, 1:1, 4:3, 3:4 | — | | `pixverse-c1` | 360p, 540p, 720p, 1080p | 1-15s | 16:9, 4:3, 1:1, 3:4, 9:16, 3:2, 2:3 | 7 imgs | | `seedance-2.5` | 480p, 720p, 1080p, 2160p | 4-30s | 16:9, 4:3, 1:1, 3:4, 9:16, 21:9 | 30 imgs + 10 videos + 10 audios *(50 total)* | | `seedance-2.5-flash` | 480p, 720p | 4-30s | 16:9, 4:3, 1:1, 3:4, 9:16, 21:9 | 10 imgs + 5 videos + 5 audios *(20 total)* | | `seedance-2.5-draft` | 480p *(then 1080p or 2160p with [create-final](/docs/api-pixverse-v2/post-pixverse-videos-create-final))* | 4-30s | 16:9, 4:3, 1:1, 3:4, 9:16, 21:9 | 30 imgs + 10 videos + 10 audios *(50 total)* | | `seedance-2.0` | 480p, 720p, 1080p, 2160p | 4-15s | 16:9, 4:3, 1:1, 3:4, 9:16, 21:9 | 9 imgs + 3 videos + 3 audios | | `seedance-2.0-fast` | 480p, 720p | 4-15s | 16:9, 4:3, 1:1, 3:4, 9:16, 21:9 | 9 imgs + 3 videos + 3 audios | | `seedance-2.0-mini` | 480p, 720p | 4-15s | 16:9, 4:3, 1:1, 3:4, 9:16, 21:9 | 9 imgs + 3 videos + 3 audios | | `kling-4.0` | 720p, 1080p | 3-30s | 16:9, 9:16, 1:1, 21:9 | 10 imgs + 5 videos | | `kling-o3` | 720p *(Std)*, 1080p *(Pro)*, 2160p *(4K)* | 3-15s | 16:9, 1:1, 9:16 | 7 imgs | | `kling-v3` | 720p *(Std)*, 1080p *(Pro)*, 2160p *(4K)* | 3-15s | 16:9, 1:1, 9:16 | — | | `grok-imagine` | 480p, 720p | 1-15s | 16:9, 4:3, 1:1, 3:4, 9:16, 3:2, 2:3 | — | | `grok-imagine-1.5` | 480p, 720p | 1-15s | i2v only *(from image)* | — | | `veo-3.1-lite` | 720p, 1080p | 4, 6, 8 | 16:9, 9:16 | — | | `veo-3.1-standard` | 720p, 1080p, 2160p | 4, 6, 8 | 16:9, 9:16 | — | | `veo-3.1-fast` | 720p, 1080p, 2160p | 4, 6, 8 | 16:9, 9:16 | — | | `happyhorse-1.0` | 720p, 1080p | 3-15s | 16:9, 9:16, 1:1, 4:3, 3:4 | — | | `minimax-h3` | 768p, 1440p *(2K)* | 5-15s | 16:9, 4:3, 1:1, 3:4, 9:16, 21:9 | 9 imgs | | `minimax-h3-max` | 480p, 768p, 1080p | 5-15s | 16:9, 4:3, 1:1, 3:4, 9:16, 21:9 | 9 imgs | | `gemini-omni-flash` | 720p | 3-10s | 16:9, 9:16 | 5 imgs + 3 videos | | `flux-3.0` | 720p, 1080p | 5-20s | auto, 21:9, 2:1, 16:9, 4:3, 1:1, 3:4, 9:16 | — | | `wan-3.0` | 480p, 720p, 1080p | 2-30s | auto, 16:9, 4:3, 1:1, 3:4, 9:16 | 10 imgs + 5 videos + 5 audios | - `aspect_ratio` is required for `t2v` and `fusion`, not accepted for `i2v` or `transition` (derived from image). - `flux-3.0` and `wan-3.0` are the only video models that accept `auto`, which lets the model choose the framing. Every other model needs an explicit ratio. - In **fusion** only, `v5.6` and `v5` additionally accept `3:2` and `2:3` on top of the five ratios listed above. - `kling-4.0` is a single model, so its `quality` is the real output resolution (720p renders 1280×720). - Prompt limits: 20,000 characters for `wan-3.0`, 15,000 for `seedance-2.5`, `seedance-2.5-flash` and `seedance-2.5-draft`, 7,000 for `minimax-h3` and `minimax-h3-max`, 4,096 for `grok-imagine` and `grok-imagine-1.5`, 4,000 for `flux-3.0`, 3,800 for `gemini-omni-flash`, 3,500 for `veo-3.1-lite`, `veo-3.1-standard` and `veo-3.1-fast`, 2,500 for `kling-4.0`, `kling-o3`, `kling-v3` and `happyhorse-1.0`, and 5,000 for every other model. - For `kling-o3` / `kling-v3`, `quality` picks an upstream **tier**, not an output resolution — `720p` routes to Std, `1080p` to Pro, and `2160p` to the 4K model. PixVerse advertises 720p for both Std and Pro, so `1080p` buys you the Pro model rather than a 1080-line render. Only `2160p` changes the resolution. - For `veo-3.1-standard` / `veo-3.1-fast`: `quality: 1080p` requires `duration: 8`. - **Reference videos and audios** are accepted only in fusion, and only by the Seedance family (videos + audios), `wan-3.0` (videos + audios), `gemini-omni-flash` and `kling-4.0` (videos). Images go in `frame_1_path` … `frame_N_path`, videos in `video_1_path` … `video_N_path` (`@video1`…`@videoN`), and audios in `audio_1_path` … `audio_N_path` (`@audio1`…`@audioN`). At least one image or reference video is required. Every reference must be ≤50 MB for video (24-60 fps, ≤6000×6000 px) and ≤15 MB for audio. * `seedance-2.5` and `seedance-2.5-draft` — 30 images, 10 reference videos, 10 reference audios, **50 references in total**. Each clip 1.8-30.2s, summed ≤30.2s per kind. * `seedance-2.5-flash` — 10 images, 5 reference videos, 5 reference audios, **20 references in total**. Video clips 4-30s, audio clips 2-30s, summed ≤30s per kind. Videos up to 200 MB, images 300-6000 px with a width-to-height ratio between 0.4 and 2.5. * `seedance-2.0` family — 9 images, 3 reference videos, 3 reference audios. Each clip 2-15s, summed ≤15s per kind. * `gemini-omni-flash` — 5 images and 3 reference videos, no reference audios. Each clip 2-15s, summed ≤15s. The 5-image cap is enforced by PixVerse. The reference-video count and durations are limits we enforce, not ones PixVerse has published — it may accept more. * `wan-3.0` — 10 images, 5 reference videos, 5 reference audios. Each clip 2-15s, summed ≤15s per kind. PixVerse states a 1s floor for audio, we enforce 2s because the same rule covers reference video. * `kling-4.0` — 10 images and 5 reference videos, no reference audios. Each clip 3-30s, summed ≤30s. With a reference video PixVerse bills the longer of (reference length + output length) and twice the output length. * `minimax-h3` and `minimax-h3-max` — 9 images, no reference videos or audios. Durations are summed separately for video and for audio. ## Audio | Model | `audio` | |-------|:-:| | `v6` | toggle | | `v5.6` | toggle | | `v5.5` | toggle | | `v5` | — *(use `lip_sync_tts_prompt` + `sound_effect_prompt`)* | | `v5-fast` | — | | `pixverse-c1` | toggle | | `seedance-2.5` | rejected *(native audio, always on)* | | `seedance-2.5-flash` | rejected *(native audio, always on)* | | `seedance-2.5-draft` | rejected *(native audio, always on)* | | `seedance-2.0` | toggle | | `seedance-2.0-fast` | toggle | | `seedance-2.0-mini` | toggle | | `kling-4.0` | rejected *(native audio, always on)* | | `kling-o3` | toggle | | `kling-v3` | toggle | | `grok-imagine` | rejected | | `grok-imagine-1.5` | rejected | | `veo-3.1-lite` | rejected | | `veo-3.1-standard` | always on | | `veo-3.1-fast` | always on | | `happyhorse-1.0` | always on | | `minimax-h3` | rejected *(native audio, always on)* | | `minimax-h3-max` | rejected *(native audio, always on)* | | `gemini-omni-flash` | rejected *(native audio, always on)* | | `flux-3.0` | toggle | | `wan-3.0` | toggle | - `toggle` — accept `audio: true` / `false`. - `always on` — audio generated automatically; `audio: false` is rejected. - `rejected` — `audio` parameter is not accepted (content has no audio track or audio is handled internally). ## Native PixVerse — extra flags `multi_shot`, `preview_mode`, `off_peak_mode`, and `seed` are supported only on native PixVerse models. Third-party models reject them. `relax_mode` is the other way round: it is for the 20 third-party models only, on create, create-frames, create-fusion and [create-final](/docs/api-pixverse-v2/post-pixverse-videos-create-final), and the native models reject it. PixVerse's per-plan discounts on third-party video apply unless you send `relax_mode: false`. The discount table is under [`relax_mode`](/docs/api-pixverse-v2/post-pixverse-videos-create-v4#parameters). | Model | `multi_shot` | `preview_mode` | `off_peak_mode` | `seed` | |-------|:-:|:-:|:-:|:-:| | `v6` | Yes | Yes | Yes | Yes | | `v5.6` | — | Yes | Yes | Yes | | `v5.5` | — | Yes | Yes | Yes | | `v5` | — | Yes | Yes | Yes | | `v5-fast` | — | Yes | Yes | Yes | | `pixverse-c1` | — | Yes | Yes | Yes | --- # Image Models All image models share the same endpoints: [create](/docs/api-pixverse-v2/post-pixverse-images-create), [list](/docs/api-pixverse-v2/get-pixverse-images), [get](/docs/api-pixverse-v2/get-pixverse-images-image_id), [delete](/docs/api-pixverse-v2/del-pixverse-images-image_id). | Model | Qualities | Max Refs | Est. Time | |-------|-----------|:--------:|:---------:| | `qwen-image` *(default)* | 720p, 1080p | 3 | ~3s | | `nano-banana` | 1080p | 3 | ~10s | | `nano-banana-2` | 512p, 1080p, 1440p, 2160p | 9 | ~30s | | `nano-banana-2.1` | 1080p, 1440p, 2160p | 14 | ~15s | | `nano-banana-2-lite` | 1080p | 14 | ~7s | | `nano-banana-pro` | 1080p, 1440p, 2160p | 9 | ~60s | | `seedream-4.0` | 1080p, 1440p, 2160p | 6 | ~10s | | `seedream-4.5` | 1440p, 2160p | 6 | ~15s | | `seedream-5.0-pro` | 1080p, 1440p | 10 | ~30s | | `seedream-5.0-lite` | 1440p, 1800p, 2160p | 6 | ~30s | | `kling-3.0` | 1080p, 1440p | 1 | ~15s | | `kling-o3` | 1080p, 1440p, 2160p | 1 | ~20s | | `gpt-image-2.0` | 1080p, 1440p, 2160p | 9 | ~30s | | `gpt-image-2.5-flare` | 1080p, 1440p, 2160p | 16 | ~30s | | `gpt-image-2.5-sunburst` | 1080p, 1440p, 2160p | 16 | ~30s | - **`create_count`**: 1-4 (default 1). - **`detail_level`** (`gpt-image-2.0`, the `gpt-image-2.5` pair and `nano-banana-2.1` only): `low`, `medium`, `high` for `gpt-image-2.0`, plus `xhigh` and `max` for `gpt-image-2.5-flare` and `gpt-image-2.5-sunburst`. `nano-banana-2.1` takes `minimal`, `medium` (default) or `high` as its thinking level, which does not change the price. Rejected for all other models, and a value outside the model's list is a 400. It drives the credit cost — see the [cost calculator](/docs/api-pixverse-v2#interactive-calculator). - The two `gpt-image-2.5` variants share one capability shape and one price list. PixVerse positions Flare for fast everyday generation and Sunburst for precise edits and detailed work. - `gpt-image-2.5-flare` and `gpt-image-2.5-sunburst` are the only image models that charge per reference image — 5 credits each, on top of the quality and detail base. At the 16-reference ceiling that adds 80 credits, so a 2160p `max` edit with 16 references costs 225 rather than 145. Every other image model is flat. - The `gpt-image-2.5` pair and `nano-banana-2.1` need a Standard or higher [plan](https://app.pixverse.ai/subscribe). They are not available on Basic. - `nano-banana-2.1` is the only model with the extreme ratios `1:4`, `4:1`, `1:8` and `8:1`. ### Aspect ratios Each model accepts its own list. If `aspect_ratio` is omitted, the **default** (first column) is used. Passing a value not in the model's row is rejected with **400**. | Models | Default | Accepted `aspect_ratio` values | |--------|:-------:|-------------------------------| | `nano-banana`, `nano-banana-2`, `nano-banana-2-lite`, `nano-banana-pro`, `seedream-4.0`, `seedream-4.5`, `seedream-5.0-pro`, `seedream-5.0-lite` | `auto` | `auto`, `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `5:4`, `4:5`, `3:2`, `2:3`, `21:9` | | `qwen-image` | `1:1` | `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `5:4`, `4:5`, `3:2`, `2:3`, `21:9` | | `kling-o3`, `kling-3.0` | `1:1` | `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3`, `21:9` | | `gpt-image-2.0`, `gpt-image-2.5-flare`, `gpt-image-2.5-sunburst` | `1:1` | `1:1`, `1:2`, `4:3`, `3:4`, `3:2`, `2:3`, `16:9`, `9:16`, `2:1`, `21:9` | | `nano-banana-2.1` | `auto` | `auto`, `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `5:4`, `4:5`, `3:2`, `2:3`, `21:9`, `1:4`, `4:1`, `1:8`, `8:1` | ## Unlimited Image Generation (Relax Mode) Pro+ [subscription plans](https://app.pixverse.ai/subscribe) include unlimited image generation in Relax Mode for select models: | Plan | Price | Unlimited Models | |------|:-----:|:-----------------| | Ultra | $199/m | `qwen-image`, `nano-banana`, `nano-banana-2`, `nano-banana-2-lite`, `nano-banana-pro`, `seedream-4.0`, `seedream-4.5`, `seedream-5.0-lite`, `seedream-5.0-pro`, `kling-3.0`, `kling-o3`, `gpt-image-2.0`, `gpt-image-2.5-flare`, `gpt-image-2.5-sunburst`, `nano-banana-2.1` (all 15) | | Premium | $60/m | `qwen-image`, `nano-banana`, `nano-banana-2`, `nano-banana-2.1`, `nano-banana-2-lite`, `seedream-4.0` | | Pro | $30/m | `qwen-image`, `nano-banana-2-lite` | Leave the `relax_mode` parameter of [POST images/create](/docs/api-pixverse-v2/post-pixverse-images-create#unlimited-image-generation-relax-mode) out and these models are free on the listed plans automatically. `relax_mode: false` pays credits for full speed, and `relax_mode: true` refuses with `412` instead of charging when the model isn't free on the plan. Relax Mode is unmetered, not unthrottled. These models cost zero credits on the listed plans and nothing rejects a request for being too frequent, but PixVerse applies a daily volume threshold. Past it the account is moved to a slow queue rather than refused — generations still succeed and still cost nothing, they just take far longer to come back. It is visible in the response, where `queue_data.slow_queue` turns `true`, `queue_data.reason` reads `daily_limit_exceeded`, and `queue_count` gives the number of tasks ahead. The threshold applies **per model**, not per account. An account throttled on one model keeps generating at full speed on every other one, and the busiest accounts clear 500–700 images a day across models combined. We have seen it engage on `nano-banana-2`, `nano-banana-pro` and `gpt-image-2.0`, most often on `nano-banana-2`. The point at which it engages is not fixed and varies between accounts, but as a rough guide expect a few hundred images per model per day — around 300 for `nano-banana-pro` and around 500 for `gpt-image-2.0`. We have not seen it on the remaining models, which does not mean they are unlimited, only that nobody has pushed them hard enough for it to show. The allowance resets at approximately 00:00 UTC, so a throttled account is clear again at the start of the next UTC day. PixVerse moves these thresholds without notice, so treat them as rough capacity guidance rather than a guarantee. Sustained volume needs more than one account, because each account carries its own allowance and [POST /videos/create](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) and [POST /images/create](/docs/api-pixverse-v2/post-pixverse-images-create) spread work across every account you have configured. Adding accounts alone is not a guarantee though — we have seen a multi-account pool throttled on the same model at the same time, because every account was working through the same daily allowance on the same model. Once a pool is in that state more accounts only buy one more allowance each, and none of them are fast. Falling back to another model is usually the better move, because the allowances are independent per model. An account wedged on `nano-banana-2` still generates on `nano-banana-pro`, `seedream-4.5` or `gpt-image-2.0` at full speed. Decide in advance which models are acceptable for your use case, watch for `queue_data.slow_queue` turning `true` on the [image](/docs/api-pixverse-v2/get-pixverse-images-image_id) or [video](/docs/api-pixverse-v2/get-pixverse-videos-video_id) response, and move down that list rather than waiting out the queue. --- # Music Models All music models share the same endpoints: [generate](/docs/api-pixverse-v2/post-pixverse-music-create), [list](/docs/api-pixverse-v2/get-pixverse-music), [get](/docs/api-pixverse-v2/get-pixverse-music-music_id). Generation is asynchronous — poll `audio_status_final` or pass a `replyUrl`. All models generate at an automatic duration (typically 2-5 minutes). | Model | Provider | Prompt max | Custom lyrics | Reference images | Credits | |-------|----------|:----------:|:-------------:|:----------------:|:-------:| | `music-2.6` *(default)* | MiniMax | 2,000 | ≤ 3,500 chars | — | 40 | | `music-v1` | ElevenLabs | 4,000 | ≤ 3,500 chars | — | 150 | | `lyria-3-pro-preview` | Google | 5,000 | — | up to 10 | 20 | ## Output modes The output is derived from `instrumental` and `lyrics` — there is no `auto_lyrics` parameter. | Request | Result | |---------|--------| | `instrumental: true` | instrumental, no vocals | | `lyrics` provided | vocals sung from your lyrics (`music-2.6` / `music-v1` only) | | neither | vocals with lyrics written by the model | - `lyrics` is rejected on `lyria-3-pro-preview` and cannot be combined with `instrumental`. - `image_path_1` … `image_path_10` are accepted by `lyria-3-pro-preview` only, provided sequentially. ## Status values | audio_status | audio_status_name | audio_status_final | |:-:|:-:|:-:| | 1 | COMPLETED | true | | 5 | QUEUED | false | | 8 | FAILED | true | | 10 | GENERATING | false | A failed track (`audio_status` 8) carries `fail_code` and a human-readable `fail_reason`. These are usually transient backend errors — re-submitting the same request often succeeds. Lyria 3 Pro is also available through [Flow Music](/docs/api-flowmusic-v1) at a lower price with many more features — cover and restyle, lyrics-adjust remix, extend and replace, and audio effects. # Music Videos A music video is made from your song and an optional character photo with [POST music-video/create](/docs/api-pixverse-v2/post-pixverse-music-video-create), PixVerse's One-Click MV. Follow it with [GET music-video/`video_id`](/docs/api-pixverse-v2/get-pixverse-music-video-video_id), list them with [GET music-video](/docs/api-pixverse-v2/get-pixverse-music-video), and pick built-in songs, characters and styles from [GET music-video/library](/docs/api-pixverse-v2/get-pixverse-music-video-library). The result is also a regular video for [GET videos/`video_id`](/docs/api-pixverse-v2/get-pixverse-videos-video_id) and [DEL videos/`video_id`](/docs/api-pixverse-v2/del-pixverse-videos-video_id). | Mode | Characters | Styles | |------|:----------:|:------:| | `performance` *(default)* | 0 or 1 | `auto`, 16 looks or your own image (`custom`) | | `expressive` | 0 or 1 | `auto`, 16 looks or your own image (`custom`) | | `storytelling` | 0 to 2 | 18 of its own | - `performance` sings the song with lip-sync, `expressive` makes emotional, atmospheric shots, and `storytelling` follows your `prompt` (≤ 2,000 chars). - `performance` and `expressive` also take `music_genre` and lyric captions. - The song is 10 seconds to 6 minutes, uploaded as MP3. PixVerse bills every second of it, rounded to the nearest second. - Every mode takes `aspect_ratio` `16:9`, `9:16`, `1:1`, `4:3` or `3:4` and `quality` `720p` or `1080p`, on every plan. - `quote: true` returns the exact price for free. - Every `performance` and `expressive` video comes with a copy without captions and, for a song with vocals, an `.ass` subtitle file. Lyric captions are optional: `subtitles: true`, with optional `lyrics` ≤ 5,000 chars. One minute of song costs (PixVerse bills every second, rounded to the nearest second): | Mode and quality | [Official API](https://docs.platform.pixverse.ai/one-click-vibemv-44144151e0) | Ultra $199/mo (30,000 cr/mo) | Premium $60/mo (15,000 cr/mo) | Pro $30/mo (6,000 cr/mo) | |---|---|---|---|---| | `performance` or `expressive`, 720p | $4.00 (15 cr/s) | $3.98 (10 cr/s) | $2.40 (10 cr/s) | $3.00 (10 cr/s) | | `performance` or `expressive`, 1080p | $6.00 (22.5 cr/s) | $5.97 (15 cr/s) | $3.60 (15 cr/s) | $4.50 (15 cr/s) | | `storytelling`, 720p | not sold | $7.96 (20 cr/s) | $4.80 (20 cr/s) | $6.00 (20 cr/s) | | `storytelling`, 1080p | not sold | $15.92 (40 cr/s) | $9.60 (40 cr/s) | $12.00 (40 cr/s) | The first music video on every PixVerse account is free, at any length and in 1080p, even on a free Basic plan. Prices as of November 2026. ## Music video status A music video renders for a few minutes. While you wait, [GET music-video/`video_id`](/docs/api-pixverse-v2/get-pixverse-music-video-video_id) shows its progress in `status`, and [GET videos/`video_id`](/docs/api-pixverse-v2/get-pixverse-videos-video_id) shows the same in `video_status_name`. Stop checking once it is finished: | `status` | `video_status_name` | Finished | |:-:|:-:|:-:| | `pending`, `processing` | GENERATING | no | | `succeeded` | COMPLETED | yes | | `failed` | FAILED | yes | A failed music video carries PixVerse's reason in `error`, and its credits are refunded. # Text-to-Speech Models All speech models share the same endpoints: [generate](/docs/api-pixverse-v2/post-pixverse-speech-create), [list](/docs/api-pixverse-v2/get-pixverse-speech), [get](/docs/api-pixverse-v2/get-pixverse-speech-speech_id), plus [voices](/docs/api-pixverse-v2/get-pixverse-speech-voices) and [models](/docs/api-pixverse-v2/get-pixverse-speech-models) for discovery. Generation is asynchronous — poll `audio_status_final` or pass a `replyUrl`. Credits are billed per character — `credits = ceil(chars / N)`. | Model | Provider | Voice settings | Max chars | N (chars/credit) | |-------|----------|----------------|:---------:|:---------------:| | `eleven-multilingual-v2` | ElevenLabs | stability, similarity_boost, speed, style | 10,000 | 50 | | `eleven-v3` | ElevenLabs | stability, similarity_boost, speed + audio tags | 5,000 | 50 | | `eleven-turbo-v2.5` | ElevenLabs | stability, similarity_boost, speed | 40,000 | 100 | | `speech-2.8-hd` *(default)* | MiniMax | speed, volume, pitch, emotion | 10,000 | 50 | | `speech-2.8-turbo` | MiniMax | speed, volume, pitch, emotion | 10,000 | 100 | Every request needs a `voice_id` from [GET speech/voices](/docs/api-pixverse-v2/get-pixverse-speech-voices) (filtered by model and language). The provider and the paired `provider_voice_id` are derived automatically. ## Voice settings The two providers take different settings, enforced per family (a setting from the wrong family is rejected with **400**): - MiniMax — `speed` (0.5-2), `volume` (0-10), `pitch` (-12-12), `emotion` (`auto`, `happy`, `sad`, `angry`, `fearful`, `disgusted`, `surprised`, `neutral`, `calm`). - ElevenLabs — `stability` (0-1), `similarity_boost` (0-1), `speed` (0.7-1.2). `style` (0-1) and `use_speaker_boost` are accepted by `eleven-multilingual-v2` only. ## Expressive control | Model | Control | |-------|---------| | `eleven-v3` | inline **audio tags** in the text — `[whispers]`, `[excited]`, `[shouts]`, `[sighs]`, `[laughs]`, `[curious]`, … Works best with longer, sentence-level text. | | `speech-2.8-hd` / `speech-2.8-turbo` | the `emotion` voice setting (a natural, subtle coloring). | | `eleven-multilingual-v2` | the `style` voice setting. | `eleven-v3` is the most expressive model. The other ElevenLabs models read audio tags literally — use them only with `eleven-v3`. ## Languages `language_code` is validated per model against the live [models](/docs/api-pixverse-v2/get-pixverse-speech-models) catalog (MiniMax and the ElevenLabs v2/turbo models support 30-40 languages). `eleven-v3` auto-detects the language and rejects `language_code` with **400**. ## Status values | audio_status | audio_status_name | audio_status_final | |:-:|:-:|:-:| | 1 | COMPLETED | true | | 5 | QUEUED | false | | 8 | FAILED | true | | 10 | GENERATING | false | A failed job (`audio_status` 8) carries `fail_code` and a human-readable `fail_reason`. These are usually transient backend errors — re-submitting the same request often succeeds. === URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email === Document URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> accounts/`email` description: "Configure or update a PixVerse account for multi-account load balancing via POST accounts/email in the useapi.net PixVerse API v2." parent: PixVerse API nav_order: 300 --- ## Create or update PixVerse API account configuration December 6, 2024 (November 16, 2026) --- See [Setup PixVerse](/docs/start-here/setup-pixverse) for details. For your convenience, you can specify your PixVerse configuration values under your account. If you specify multiple PixVerse accounts, the API will automatically perform load balancing by randomly selecting an account with available capacity before making calls to PixVerse. > **https://api.useapi.net/v2/pixverse/accounts/`email`** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "email": "Required PixVerse account email", "password": "Required PixVerse account password", "maxJobs": 1-8, "token": "Optional PixVerse token", } ``` - `email` and `password` are **required**. Please see [Setup PixVerse](/docs/start-here/setup-pixverse) for details. - `maxJobs` is **required**. Valid range: 1…8 It should not exceed the number of concurrent generations supported by your account [subscription](https://app.pixverse.ai/subscribe) plan. - `token` is optional and should only be used for development or debugging purposes. See [details](/docs/start-here/setup-pixverse#optional-configure-pixverse-api-to-use-the-current-pixverseai-session). **Important:** When creating an account, leave the token field empty. Only add it after the account has been created, and only if you truly need it. ##### Responses **201** **201 Created** ```json { "email": "<account email>", "password": "…secured…", "maxJobs": 3, "jwt": { "AccountId": 66778899, "ExpireTime": 123456789, "ExpireTimeUTC": "2025-01-01T12:13:14.000Z", "Username": "<username>", "token": "abc…secured…cde" } } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "<Error message>", "code": 401 } ``` **596** **596 Account banned** PixVerse banned this account for violating its community guidelines, so it cannot be added. A ban is permanent unless PixVerse accepts an appeal, and the `error` quotes PixVerse's own message, which says how to appeal. Use a different account. ```json { "error": "PixVerse banned account example@gmail.com for violating its community guidelines (400024). A ban is permanent unless PixVerse accepts an appeal. PixVerse says: \"Your account has been banned for violating community guidelines. If you wish to appeal, please contact us via ...\" Remove it with DELETE /v2/pixverse/accounts/example@gmail.com, or add it again (https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email) only if PixVerse lifts the ban.", "code": 596 } ``` ##### Model Answers `201` with the saved configuration: email, `maxJobs` and the PixVerse session token in `jwt`, with password and token masked. <details markdown="block" class="model-details"> <summary>The saved account configuration, field by field</summary> ```typescript { // TypeScript, all fields are optional email: string password: string maxJobs: number jwt: { AccountId: number ExpireTime: number ExpireTimeUTC: string Username: string token: string } } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST https://api.useapi.net/v2/pixverse/accounts/<email> \ -d '{"email": "…", "password": "…", "maxJobs": …}' ``` **JavaScript** ``` javascript const email = "PixVerse account email"; const password = "PixVerse account password"; const apiUrl = `https://api.useapi.net/v2/pixverse/accounts/${email}`; const api_token = "API token"; const maxJobs = 3; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${api_token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ email, password, maxJobs }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests email = "PixVerse account email" password = "PixVerse account password" apiUrl = f"https://api.useapi.net/v2/pixverse/accounts/{email}" api_token = "API token" maxJobs = 3 headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {api_token}" } body = { "email": f"{email}", "password": f"{password}", "maxJobs": maxJobs } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-files === Document URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-files --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> files description: "Upload an image, video, or audio file up to 5 GB via POST files in the useapi.net PixVerse API v2 — the returned id or path is used in generation requests." parent: PixVerse API nav_order: 500 --- ## Upload image, video or audio file December 6, 2024 (November 16, 2026) --- Upload an image, video, or audio file up to 5GB in size. Files uploaded to one PixVerse.ai account can be accessed from any other PixVerse.ai account just by referencing the `id` (image) or `path` (video/audio) so keep that in mind. [POST raw content using Make.com and similar nocode tools.](/docs/questions-and-answers#how-post-raw-content-to-runwaymlassets-and-minimaxfiles-using-makecom-and-similar-nocode-tools) > **https://api.useapi.net/v2/pixverse/files/?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: select from the table below ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. - `Content-Type` is **required**, select from the table below: | Content-Type | File Extension | | ------------------- | -------------- | | image/png | png | | image/jpeg | jpeg | | image/gif | gif | | image/webp | webp | | video/mp4 | mp4 | | video/quicktime | mov | | video/3gpp | 3gp | | video/x-matroska | mkv | | video/x-flv | flv | | video/mpeg | mpeg | | video/MP2T | ts | | video/x-msvideo | avi | | video/x-motion-jpeg | mjpeg | | video/webm | webm | | video/ogg | ogv | | audio/wav | wav | | audio/wave | wav | | audio/mpeg | mp3 | **NOTE** We took a guess on supported video and audio types and only tested the most popular ones. **Image resolution limit:** PixVerse does not support images larger than ~2K resolution. If your image exceeds 2048px on either dimension, downscale it to 2K or 1080p before uploading. Oversized images may fail silently or produce unexpected results. ##### Query Parameters - `email` is optional when only one [account](/docs/api-pixverse-v2/get-pixverse-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. ##### Responses **200** **200 OK** The image upload response contains a `id` that you can use to reference the uploaded image file: ```json { "result": [ { "id": 123456, "url": "<file url>", "path": "<file path>", "size": 112233, "name": "<file name>", "category": 0, "err_msg": "" } ] } ``` The video/audio upload response contains a `path` that you can use to reference the uploaded video/audio file: ```json { "path": "<file path>", "url": "<file url>" } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model An image upload answers with `result`, holding the file's `id`, and a video or audio upload answers with its `path` and `url`. <details markdown="block" class="model-details"> <summary>The uploaded file, field by field</summary> ```typescript { // TypeScript, all fields are optional url: string path: string result: { id: number url: string path: string size: number name: string category: number err_msg: string }[] } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v2/pixverse/files/?email=email" \ -H "Authorization: Bearer …" \ -H "Content-Type: image/jpeg" \ --data-binary /path/to/your/image.jpeg ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured account email"; const apiUrl = `https://api.useapi.net/v2/pixverse/files/?email=${email}`; let blob; /* // Example 1: Fetch image from URL const imageUrl = "https://upload.wikimedia.org/wikipedia/commons/7/7d/Mona_Lisa_color_restoration.jpg"; const responseImage = await fetch(imageUrl); blob = await responseImage.blob(); */ /* // Example 2: Load image from local file (Blob) const fsp = require('fs').promises; const imageFileName = "./cat.png"; blob = new Blob([await fsp.readFile(imageFileName)]); */ /* // Example 3: Load from input file html element // <input id="image-file" type="file"> const imageFile = document.getElementById(`image-file`); if (imageFile.files[0]) blob = imageFile.files[0]); */ const response = await fetch(apiUrl, { method: "POST" headers: { "Authorization": `Bearer ${token}`, }, body: blob }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured account email" apiUrl = f"https://api.useapi.net/v2/pixverse/files/?email={email}" headers = { 'Authorization': f'Bearer {token}', 'Content-Type': 'image/jpeg' } # # Example 1: Fetch image from URL # image_url = "https://upload.wikimedia.org/wikipedia/commons/7/7d/Mona_Lisa_color_restoration.jpg" # response_image = requests.get(image_url) # file_content = response_image.content # # Example 2: Load image from local file # image_file_path = "./image.jpg" # with open(image_file_path, 'rb') as image_file: # file_content = image_file.read() response = requests.post(api_url, headers=headers, data=file_content) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-images-create === Document URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-images-create --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> images/create description: "Generate an image via POST images/create in the useapi.net PixVerse API v2 — text-to-image and image-to-image across 15 models including qwen-image, Nano Banana 2.1, Seedream and GPT Image 2.5." parent: PixVerse API nav_order: 540 --- ## Create an image using a text prompt ## Table of contents March 9, 2026 (November 16, 2026) --- Use [pixverse.ai](https://app.pixverse.ai) account to generate images. Supports text-to-image (t2i) and image-to-image (i2i) with reference images uploaded via [POST files](/docs/api-pixverse-v2/post-pixverse-files). ##### Model Comparison Matrix | Model | Qualities | Ref Images | Est. Time | |:------|:----------|:-----------|:---------| | `qwen-image` *(default)* | 720p, 1080p | 1-3 via `image_path_1`…`3` | ~3s | | `nano-banana` *<sup>\*</sup>* | 1080p | 1-3 via `image_path_1`…`3` | ~10s | | `nano-banana-2` *<sup>\*</sup>* | 512p, 1080p, 1440p, 2160p | 1-9 via `image_path_1`…`9` | ~30s | | `nano-banana-2.1` | 1080p, 1440p, 2160p | 1-14 via `image_path_1`…`14` | ~15s | | `nano-banana-2-lite` *<sup>\*</sup>* | 1080p | 1-14 via `image_path_1`…`14` | ~7s | | `nano-banana-pro` *<sup>\*</sup>* | 1080p, 1440p, 2160p | 1-9 via `image_path_1`…`9` | ~60s | | `seedream-4.0` | 1080p, 1440p, 2160p | 1-6 via `image_path_1`…`6` | ~10s | | `seedream-4.5` | 1440p, 2160p | 1-6 via `image_path_1`…`6` | ~15s | | `seedream-5.0-pro` | 1080p, 1440p | 1-10 via `image_path_1`…`10` | ~30s | | `seedream-5.0-lite` | 1440p, 1800p, 2160p | 1-6 via `image_path_1`…`6` | ~30s | | `kling-3.0` | 1080p, 1440p | 1 via `image_path_1` | ~15s | | `kling-o3` | 1080p, 1440p, 2160p | 1 via `image_path_1` | ~20s | | `gpt-image-2.0` | 1080p, 1440p, 2160p | 1-9 via `image_path_1`…`9` | ~30s | | `gpt-image-2.5-flare` | 1080p, 1440p, 2160p | 1-16 via `image_path_1`…`16` | ~30s | | `gpt-image-2.5-sunburst` | 1080p, 1440p, 2160p | 1-16 via `image_path_1`…`16` | ~30s | <sup>\*</sup> Nano Banana / Nano Banana 2 / Nano Banana 2 Lite / Nano Banana Pro have less restrictive content moderation and can use photos of minors or recognizable people as reference images. Use responsibly and in compliance with applicable laws. `nano-banana-2.1` needs a Standard or higher PixVerse [plan](https://app.pixverse.ai/subscribe). It is not available on Basic. ##### Aspect Ratios Each model accepts its own list. If `aspect_ratio` is omitted, the **default** (first column) is used. Passing a value not in the model's row is rejected with **400**. | Models | Default | Accepted `aspect_ratio` values | |--------|:-------:|-------------------------------| | `nano-banana`, `nano-banana-2`, `nano-banana-2-lite`, `nano-banana-pro`, `seedream-4.0`, `seedream-4.5`, `seedream-5.0-pro`, `seedream-5.0-lite` | `auto` | `auto`, `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `5:4`, `4:5`, `3:2`, `2:3`, `21:9` | | `qwen-image` | `1:1` | `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `5:4`, `4:5`, `3:2`, `2:3`, `21:9` | | `kling-o3`, `kling-3.0` | `1:1` | `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3`, `21:9` | | `gpt-image-2.0`, `gpt-image-2.5-flare`, `gpt-image-2.5-sunburst` | `1:1` | `1:1`, `1:2`, `4:3`, `3:4`, `3:2`, `2:3`, `16:9`, `9:16`, `2:1`, `21:9` | | `nano-banana-2.1` | `auto` | `auto`, `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `5:4`, `4:5`, `3:2`, `2:3`, `21:9`, `1:4`, `4:1`, `1:8`, `8:1` | `gpt-image-2.0` also takes the `detail_level` parameter (`low`, `medium`, or `high`). The `gpt-image-2.5` pair takes it too and adds two higher tiers, `xhigh` and `max`. It affects credit cost — see the credits estimator below. `nano-banana-2.1` uses `detail_level` for its thinking level: `minimal`, `medium` (the default) or `high`. It does not change the price. <details markdown="block"> <summary><b>Credits estimator</b></summary> Credits are charged per image. Actual costs may change, see [pixverse.ai](https://app.pixverse.ai/subscribe) for current pricing. | Model | Quality | Credits per image | Quantity | |:------|:--------|:-----------------:|:---------| | qwen-image | 720p | 5 | 1-4 | | qwen-image | 1080p | 10 | 1-4 | | nano-banana-2-lite | 1080p | 6 | 1-4 | | seedream-4.0 | all | 10 | 1-4 | | seedream-4.5 | all | 10 | 1-4 | | nano-banana | 1080p | 15 | 1-4 | | seedream-5.0-pro | 1080p | 15 | 1-4 | | seedream-5.0-pro | 1440p | 30 | 1-4 | | seedream-5.0-lite | 1440p | 12 | 1-4 | | seedream-5.0-lite | 1800p | 15 | 1-4 | | seedream-5.0-lite | 2160p | 18 | 1-4 | | nano-banana-2 | 512p | 16 | 1-4 | | nano-banana-2 | 1080p | 25 | 1-4 | | nano-banana-2 | 1440p | 40 | 1-4 | | nano-banana-2 | 2160p | 60 | 1-4 | | nano-banana-2.1 | 1080p | 10 | 1-4 | | nano-banana-2.1 | 1440p | 25 | 1-4 | | nano-banana-2.1 | 2160p | 35 | 1-4 | | nano-banana-pro | 1080p, 1440p | 50 | 1-4 | | nano-banana-pro | 2160p | 90 | 1-4 | | kling-3.0 | 1080p, 1440p | 10 | 1-4 | | kling-o3 | 1080p, 1440p | 10 | 1-4 | | kling-o3 | 2160p | 20 | 1-4 | | gpt-image-2.0 | 1080p (low / medium / high) | 15 / 30 / 60 | 1-4 | | gpt-image-2.0 | 1440p (low / medium / high) | 30 / 60 / 120 | 1-4 | | gpt-image-2.0 | 2160p (low / medium / high) | 45 / 90 / 180 | 1-4 | | gpt-image-2.5-flare, gpt-image-2.5-sunburst | 1080p (low / medium / high / xhigh / max) | 5 / 5 / 15 / 20 / 50 | 1-4 | | gpt-image-2.5-flare, gpt-image-2.5-sunburst | 1440p (low / medium / high / xhigh / max) | 6 / 6 / 20 / 35 / 80 | 1-4 | | gpt-image-2.5-flare, gpt-image-2.5-sunburst | 2160p (low / medium / high / xhigh / max) | 7 / 10 / 35 / 65 / 145 | 1-4 | </details> ##### Unlimited Image Generation (Relax Mode) Pro+ [subscription plans](https://app.pixverse.ai/subscribe) include unlimited image generation in Relax Mode for select models: | Plan | Price | Unlimited Models | |------|:-----:|:-----------------| | Ultra | $199/m | `qwen-image`, `nano-banana`, `nano-banana-2`, `nano-banana-2-lite`, `nano-banana-pro`, `seedream-4.0`, `seedream-4.5`, `seedream-5.0-lite`, `seedream-5.0-pro`, `kling-3.0`, `kling-o3`, `gpt-image-2.0`, `gpt-image-2.5-flare`, `gpt-image-2.5-sunburst`, `nano-banana-2.1` (all 15) | | Premium | $60/m | `qwen-image`, `nano-banana`, `nano-banana-2`, `nano-banana-2.1`, `nano-banana-2-lite`, `seedream-4.0` | | Pro | $30/m | `qwen-image`, `nano-banana-2-lite` | You choose Relax Mode per request with the optional [`relax_mode`](#parameters) parameter. Most requests should leave it out: | `relax_mode` | Model is free on the account's plan | Model is not free on the account's plan | |:-------------|:------------------------------------|:----------------------------------------| | left out *(recommended)* | Free, in Relax Mode | Credits at the regular price | | `true` | Free, in Relax Mode | Refused with [`412`](#responses), nothing is charged | | `false` | Credits at the regular price, generated at full speed | Credits at the regular price | When you leave `relax_mode` out, the API doesn't send it to PixVerse at all, and PixVerse uses Relax Mode whenever the account's plan makes that model free. It works on every plan and never fails because of Relax Mode. Set `relax_mode: false` only when you would rather pay credits than wait in Relax Mode, which PixVerse runs slower than paid generation. Set `relax_mode: true` only when you never want to be charged: on a model or plan without the benefit the request fails with `412` instead of spending credits. To see what PixVerse did, check `cost_credits` and `generation_mode` on [GET images/`imageId`](/docs/api-pixverse-v2/get-pixverse-images-image_id#generation-mode). Relax Mode is unmetered, not unthrottled. These models cost zero credits on the listed plans and nothing rejects a request for being too frequent, but PixVerse applies a daily volume threshold. Past it the account is moved to a slow queue rather than refused — generations still succeed and still cost nothing, they just take far longer to come back. It is visible in the response, where `queue_data.slow_queue` turns `true`, `queue_data.reason` reads `daily_limit_exceeded`, and `queue_count` gives the number of tasks ahead. The threshold applies **per model**, not per account. An account throttled on one model keeps generating at full speed on every other one, and the busiest accounts clear 500–700 images a day across models combined. We have seen it engage on `nano-banana-2`, `nano-banana-pro` and `gpt-image-2.0`, most often on `nano-banana-2`. The point at which it engages is not fixed and varies between accounts, but as a rough guide expect a few hundred images per model per day — around 300 for `nano-banana-pro` and around 500 for `gpt-image-2.0`. We have not seen it on the remaining models, which does not mean they are unlimited, only that nobody has pushed them hard enough for it to show. The allowance resets at approximately 00:00 UTC, so a throttled account is clear again at the start of the next UTC day. PixVerse moves these thresholds without notice, so treat them as rough capacity guidance rather than a guarantee. Sustained volume needs more than one account, because each account carries its own allowance and [POST /videos/create](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) and [POST /images/create](/docs/api-pixverse-v2/post-pixverse-images-create) spread work across every account you have configured. Adding accounts alone is not a guarantee though — we have seen a multi-account pool throttled on the same model at the same time, because every account was working through the same daily allowance on the same model. Once a pool is in that state more accounts only buy one more allowance each, and none of them are fast. Falling back to another model is usually the better move, because the allowances are independent per model. An account wedged on `nano-banana-2` still generates on `nano-banana-pro`, `seedream-4.5` or `gpt-image-2.0` at full speed. Decide in advance which models are acceptable for your use case, watch for `queue_data.slow_queue` turning `true` on the [image](/docs/api-pixverse-v2/get-pixverse-images-image_id) or [video](/docs/api-pixverse-v2/get-pixverse-videos-video_id) response, and move down that list rather than waiting out the queue. To retrieve generated image(s), use: * [GET images/`imageId`](/docs/api-pixverse-v2/get-pixverse-images-image_id) To delete a generated image, use: * [DEL images/`imageId`](/docs/api-pixverse-v2/del-pixverse-images-image_id) > **https://api.useapi.net/v2/pixverse/images/create** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "email": "Optional PixVerse API account email", "prompt": "Required text prompt", "model": "seedream-4.0", "quality": "1080p", "aspect_ratio": "auto", "detail_level": "medium", "create_count": 1, "seed": 654321, "image_path_1": "upload/eb20c63d-2a1a-5be6-a562-d3578a2831e3.png", "replyUrl": "Place your call back URL here", "replyRef": "Place your reference id here", "maxJobs": 3 } ``` ##### Parameters - `email` is optional, if not specified API will randomly select account from available [accounts](/docs/api-pixverse-v2/get-pixverse-accounts). - `prompt` is **required**, describe your image. Maximum length 20,000 characters for the Nano Banana models (`nano-banana`, `nano-banana-2`, `nano-banana-2.1`, `nano-banana-2-lite`, `nano-banana-pro`) and the GPT Image models (`gpt-image-2.0`, `gpt-image-2.5-flare`, `gpt-image-2.5-sunburst`), 5,000 characters for the other models. - `model` is optional. Default: `qwen-image`. See [Model Comparison Matrix](#model-comparison-matrix) for the full list and per-model notes. - `quality` is optional, model-specific. Defaults to the model's first listed value. See [Model Comparison Matrix](#model-comparison-matrix) for per-model qualities. - `aspect_ratio` is optional. Each model accepts its own list — see [Aspect Ratios](#aspect-ratios) above. If omitted, the model's default is used. Passing a value not in the model's row is rejected with **400**. - `detail_level` is accepted by `gpt-image-2.0` (`low`, `medium`, `high`), by `gpt-image-2.5-flare` / `gpt-image-2.5-sunburst` (`low`, `medium`, `high`, `xhigh`, `max`) and by `nano-banana-2.1` (`minimal`, `medium`, `high`), and rejected for all other models. When omitted it defaults to `low`, or to `medium` for `nano-banana-2.1`. A value outside the model's list is rejected with **400**. For the GPT Image models it drives the credit cost. For `nano-banana-2.1` it is the thinking level and the price stays the same. For `gpt-image-2.0` the steps are relative (low = 0.5×, medium = 1×, high = 2× per quality). The `gpt-image-2.5` pair has its own absolute price per quality and level — see the credits estimator. - `create_count` is optional. Number of images to generate per request. Supported range: 1…4, default 1. - `seed` is optional. Valid range 0…2147483647. - `relax_mode` is optional, `true` or `false`. Leave it out unless you need one of the two cases below. When it is left out, nothing is sent to PixVerse and the image is free whenever the account's plan makes the model free (see [Unlimited Image Generation](#unlimited-image-generation-relax-mode)), and paid with credits otherwise. `false` always pays credits at the regular price and generates at full speed, even when the model would be free. `true` asks for a free image only. If the account's plan does not make this model free, the request is refused with **412** and no credits are spent. - `image_path_1` through `image_path_16` are optional. Reference image file paths uploaded via [POST files](/docs/api-pixverse-v2/post-pixverse-files) for image-to-image (i2i) generation. Reference images must be provided sequentially — `image_path_2` requires `image_path_1`, etc. Maximum number of references depends on the model (see [Model Comparison Matrix](#model-comparison-matrix)). Only `gpt-image-2.5-flare` and `gpt-image-2.5-sunburst` reach 16. On those two models each reference adds **5 credits** on top of the base price. Every other model includes its references at no extra cost. - `replyUrl` is optional, place here your callback URL. This is the preferred and most optimal way to receive results quickly — the API polls every 10 seconds and will call the provided `replyUrl` once the PixVerse image is completed or failed. We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality. Maximum length 1024 characters. Callback body has the same JSON shape as [GET /images/`image_id`](/docs/api-pixverse-v2/get-pixverse-images-image_id) response. - `replyRef` is optional, place here your reference id which will be stored and returned along with this PixVerse image response / result. Maximum length 1024 characters. - `maxJobs` is optional, if not specified value from selected [accounts/email](/docs/api-pixverse-v2/get-pixverse-accounts-email) will be used. It should not exceed the number of concurrent generations supported by your account [subscription](https://app.pixverse.ai/subscribe) plan. Valid range: 1…8 ##### Responses **200** **200 OK** Use returned `image_id` or values from `success_ids` array to retrieve image status and results using [GET images/`imageId`](/docs/api-pixverse-v2/get-pixverse-images-image_id). Check `image_status_name` for `COMPLETED` and `image_url` for the generated image link. If you specify the optional parameter [`replyUrl`](#request-body), the API will call the provided `replyUrl` with image progress updates until the image is complete or fails. ```json { "image_id": "user:<userid>-pixverse:<email>-image:<number>", "success_ids": [ "user:<userid>-pixverse:<email>-image:<id_1>", "user:<userid>-pixverse:<email>-image:<id_2>" ], "success_count": 2, "fail_count": 0, "total_count": 2, "cost_credits": 0, "code": 200 } ``` `cost_credits` is what PixVerse charged for the request, `0` for images made in Relax Mode. **400** **400 Bad Request** ```json { "error": "<Error message>" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized" } ``` **412** **412 Precondition Failed** The account's PixVerse plan doesn't allow this request. Three cases: 1. Insufficient credits. All Credits have been used up. Please upgrade your membership or purchase credits. ```json { "error": "All Credits have been used up. Please upgrade your membership or purchase credits." } ``` 2. The model needs a higher plan, for example `nano-banana-2.1` on Basic. ```json { "error": "This image model is available for Standard and higher plans only. Please upgrade your membership to use this feature. (500342)" } ``` 3. You sent `relax_mode: true`, and the account's plan doesn't make this model free. Nothing is charged. Leave `relax_mode` out to have the image paid with credits instead, see [Unlimited Image Generation](#unlimited-image-generation-relax-mode). ```json { "error": "relax_mode: true needs a PixVerse plan that includes unlimited free generation with model qwen-image, and this account's plan does not. Leave relax_mode out to generate for free whenever the plan allows it and pay credits otherwise, or set relax_mode: false to pay credits at full speed. PixVerse: Relax mode requires an active unlimited image benefit for this model. (400017)", "code": 412 } ``` **422** **422 Unprocessable Content** Moderated message. ```json { "error": "Your prompt has triggered our AI moderator, please re-enter your prompt" } ``` **429** **429 Too Many Requests** Wait in a loop for **at least** 10..30 seconds and retry again. There are two possible cases for API response 429: 1. API query is full and can not accept new [images/create](#request-headers) requests. Size of query defined by [`maxJobs` optional parameter](#request-body). ```json { "error": "Account <email> is busy executing <maxJobs> tasks." "All configured accounts are running at maximum capacity." } ``` 2. The API received an HTTP response status 429 from PixVerse. Please refer to your [subscription](https://app.pixverse.ai/subscribe) plan for the maximum allowed tasks in the queue. ```json { "error": "Reached the limit for concurrent generations." } ``` **596** **596 Pending mod message** The account has a pending error, and the API does not use it until you add it again with [POST accounts/email](/docs/api-pixverse-v2/post-pixverse-accounts-email). You receive an email when this happens. There are three causes. PixVerse could not sign the account in, most often because its password was changed. Add the account again with the current password. ```json { "error": "Your PixVerse account has pending error. Please address this issue at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email before making any new API calls.", "code": 596 } ``` Or PixVerse suspended the account. PixVerse suspends accounts that break its content rules and does not say which generation caused it. The first response carries PixVerse's own details in `account_moderation`, and later calls return the same `error`. Add the account again after `reinstatement_at`. To ask PixVerse to lift the suspension earlier, write to the `support_email` it gives. ```json { "error": "PixVerse suspended account example@gmail.com for 30 days, from 2026-10-16 09:26 UTC until 2026-11-15 09:26 UTC. PixVerse suspends accounts that break its content rules and does not say which generation caused it. Add the account again at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email after 2026-11-15 09:26 UTC. To ask PixVerse to lift it earlier, write to support@pixverse.ai.", "code": 596, "account_moderation": { "ban_level": "suspend_30d", "action": "temporary_suspend", "duration_days": 30, "suspended_at": "2026-10-16 09:26:25 (UTC)", "reinstatement_at": "2026-11-15 09:26:25 (UTC)", "support_email": "support@pixverse.ai" } } ``` Or PixVerse banned the account for violating its community guidelines. A ban is permanent unless PixVerse accepts an appeal, and the `error` quotes PixVerse's own message, which says how to appeal. Remove the account with [DELETE accounts/email](/docs/api-pixverse-v2/del-pixverse-accounts-email), or add it again only if PixVerse lifts the ban. ```json { "error": "PixVerse banned account example@gmail.com for violating its community guidelines (400024). A ban is permanent unless PixVerse accepts an appeal. PixVerse says: \"Your account has been banned for violating community guidelines. If you wish to appeal, please contact us via ...\" Remove it with DELETE /v2/pixverse/accounts/example@gmail.com, or add it again (https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email) only if PixVerse lifts the ban.", "code": 596 } ``` If every account you have is in this state, a request without `email` returns 596 as well. ##### Model The new image's `image_id`, every started image id in `success_ids` and the credits spent: poll each with [GET images/`image_id`](/docs/api-pixverse-v2/get-pixverse-images-image_id). <details markdown="block" class="model-details"> <summary>The new image job, field by field</summary> ```typescript { // TypeScript, all fields are optional image_id: string success_ids: string[] success_count: number fail_count: number total_count: number cost_credits: number error: string code: number } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST "https://api.useapi.net/v2/pixverse/images/create" \ -d '{"prompt": "…"}' ``` **JavaScript** ``` javascript const prompt = "text prompt"; const apiUrl = `https://api.useapi.net/v2/pixverse/images/create`; const token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ prompt }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests prompt = "text prompt" apiUrl = f"https://api.useapi.net/v2/pixverse/images/create" token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } body = { "prompt": f"{prompt}" } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-images-upscale === Document URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-images-upscale --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> images/upscale description: "Upscale any image to 4K via POST images/upscale in the useapi.net PixVerse API v2 — PixVerse Upscale or Topaz Gigapixel, your own uploads or PixVerse images, with a free price quote." parent: PixVerse API nav_order: 545 --- ## Upscale image to 1080p, 2K or 4K October 10, 2026 (November 16, 2026) --- Upscale an image with PixVerse's own upscaler or [Topaz](https://www.topazlabs.com) Gigapixel. The source can be an image you generated on PixVerse (`image_id`) or any JPG / PNG / WebP you upload with [POST /files](/docs/api-pixverse-v2/post-pixverse-files) (`image_path`), below 4K. Add `"quote": true` to get the exact price without spending anything. For videos, see [POST videos/upscale](/docs/api-pixverse-v2/post-pixverse-videos-upscale). > **https://api.useapi.net/v2/pixverse/images/upscale** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "image_id": "Optional image_id", "image_path": "Optional path from POST /files", "email": "Optional PixVerse account email", "model": "topaz-gigapixel", "quality": "2160p", "quote": false, "replyUrl": "Place your call back URL here", "replyRef": "Place your reference id here", "maxJobs": 3 } ``` - `image_id` or `image_path` is **required**, provide exactly one. `image_id` is an image from [GET /images](/docs/api-pixverse-v2/get-pixverse-images). The account is taken from the id, so `email` is not needed. `image_path` is the `path` returned by [POST /files](/docs/api-pixverse-v2/post-pixverse-files) for a JPG, PNG or WebP upload. Any image works, not only PixVerse generations. It must be under 4K. - `email` is optional, used only with `image_path`. If not specified, the API selects an account from your [accounts](/docs/api-pixverse-v2/get-pixverse-accounts). - `model` is optional. Default: `pixverse-upscale`. | `model` | `quality` | Credits per image | Cost on Premium | |---|---|:-:|:-:| | `pixverse-upscale` | `2160p` | 8 | $0.032 | | `topaz-gigapixel` | `1080p` / `1440p` / `2160p` | 15 | $0.060 | Gigapixel costs the same at every resolution. Premium is the $60 plan at $0.004 per credit. These are PixVerse's list prices, observed on a Pro account. - `quality` is optional. Default: `2160p` (4K). `1440p` is PixVerse's 2K. Supported values depend on `model`, see the table above. - `quote` is optional. Set it to `true` to get the exact price and nothing else — nothing is submitted and no credits are used. See the [quote response](#responses). Pass `email` too when you have several accounts, so the price and `has_enough_credits` are for the account you will submit to. - `replyUrl` is optional. This is the preferred and most optimal way to receive results quickly — the API polls every 10 seconds and will call the provided `replyUrl` once the PixVerse image is completed or failed. Maximum length 1024 characters. We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality. Callback body has the same JSON shape as [GET /images/`image_id`](/docs/api-pixverse-v2/get-pixverse-images-image_id) response. - `replyRef` is optional, place here your reference id which will be stored and returned along with this PixVerse image response / result. Maximum length 1024 characters. - `maxJobs` is optional, if not specified value from selected [accounts/email](/docs/api-pixverse-v2/get-pixverse-accounts-email) will be used. Valid range: 1…8 It should not exceed the number of concurrent generations supported by your account [subscription](https://app.pixverse.ai/subscribe) plan. An image upscale usually finishes in 15 to 40 seconds. In [GET /images/`image_id`](/docs/api-pixverse-v2/get-pixverse-images-image_id) the `model` field shows PixVerse's internal name for the upscaler — `fvsr_image` for `pixverse-upscale`, `topaz_gigapixel_standard_2` for `topaz-gigapixel`. ##### Responses **200** **200 OK** Use the returned `image_id` to retrieve the result using [GET /images/`image_id`](/docs/api-pixverse-v2/get-pixverse-images-image_id). Check if the field `image_status_final` is `true` or `image_status_name` is `COMPLETED`. The field `image_url` will contain the upscaled image link. If you specify the optional parameter [`replyUrl`](#request-body), the API will call the provided `replyUrl` with progress updates until the image is complete or fails. ```json { "image_id": "user:<userid>-pixverse:<email>-image:<number>", "model": "topaz-gigapixel", "quality": "2160p", "cost_credits": 15 } ``` With `"quote": true` nothing is submitted, and the response is the price: ```json { "quote": true, "model": "topaz-gigapixel", "quality": "2160p", "billing_unit": "image", "credits_per_unit": 15, "cost_credits": 15, "has_enough_credits": true } ``` **400** **400 Bad Request** Returned for a `quality` the `model` does not support, for both or neither of `image_id` and `image_path`, and for a source PixVerse refuses — for example one that is already 4K. ```json { "error": "Already in 4K. Higher enhancement isn’t supported. (500344)" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized" } ``` **412** **412 Insufficient credits** The account does not have enough credits for this upscale. The price is checked before anything is submitted, so nothing was created. ```json { "error": "Not enough credits: this upscale costs 15 credits" } ``` **429** **429 Too Many Requests** Wait in a loop for **at least** 10..30 seconds and retry again. There are two possible cases for API response 429: 1. API query is full and can not accept new [images/upscale](#request-headers) requests. Size of query defined by [`maxJobs` optional parameter](#request-body). ```json { "error": "Account <email> is busy executing <maxJobs> tasks." "All configured accounts are running at maximum capacity." } ``` 2. The API received an HTTP response status 429 from PixVerse. Please refer to your [subscription](https://app.pixverse.ai/subscribe) plan for the maximum allowed tasks in the queue. ```json { "error": "Reached the limit for concurrent generations." } ``` **596** **596 Pending mod message** The account has a pending error, and the API does not use it until you add it again with [POST accounts/email](/docs/api-pixverse-v2/post-pixverse-accounts-email). You receive an email when this happens. There are three causes. PixVerse could not sign the account in, most often because its password was changed. Add the account again with the current password. ```json { "error": "Your PixVerse account has pending error. Please address this issue at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email before making any new API calls.", "code": 596 } ``` Or PixVerse suspended the account. PixVerse suspends accounts that break its content rules and does not say which generation caused it. The first response carries PixVerse's own details in `account_moderation`, and later calls return the same `error`. Add the account again after `reinstatement_at`. To ask PixVerse to lift the suspension earlier, write to the `support_email` it gives. ```json { "error": "PixVerse suspended account example@gmail.com for 30 days, from 2026-10-16 09:26 UTC until 2026-11-15 09:26 UTC. PixVerse suspends accounts that break its content rules and does not say which generation caused it. Add the account again at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email after 2026-11-15 09:26 UTC. To ask PixVerse to lift it earlier, write to support@pixverse.ai.", "code": 596, "account_moderation": { "ban_level": "suspend_30d", "action": "temporary_suspend", "duration_days": 30, "suspended_at": "2026-10-16 09:26:25 (UTC)", "reinstatement_at": "2026-11-15 09:26:25 (UTC)", "support_email": "support@pixverse.ai" } } ``` Or PixVerse banned the account for violating its community guidelines. A ban is permanent unless PixVerse accepts an appeal, and the `error` quotes PixVerse's own message, which says how to appeal. Remove the account with [DELETE accounts/email](/docs/api-pixverse-v2/del-pixverse-accounts-email), or add it again only if PixVerse lifts the ban. ```json { "error": "PixVerse banned account example@gmail.com for violating its community guidelines (400024). A ban is permanent unless PixVerse accepts an appeal. PixVerse says: \"Your account has been banned for violating community guidelines. If you wish to appeal, please contact us via ...\" Remove it with DELETE /v2/pixverse/accounts/example@gmail.com, or add it again (https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email) only if PixVerse lifts the ban.", "code": 596 } ``` If every account you have is in this state, a request without `email` returns 596 as well. ##### Model The upscaled image's `image_id` to poll with [GET images/`image_id`](/docs/api-pixverse-v2/get-pixverse-images-image_id) and its cost, or only the price with `"quote": true`. <details markdown="block" class="model-details"> <summary>The upscaled image job or its price quote, field by field</summary> ```typescript { // TypeScript, all fields are optional image_id: string model: 'pixverse-upscale' | 'topaz-gigapixel' quality: '1080p' | '1440p' | '2160p' cost_credits: number // "quote": true only quote: boolean billing_unit: 'image' credits_per_unit: number has_enough_credits: boolean error: string } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST "https://api.useapi.net/v2/pixverse/images/upscale" \ -d '{"image_path": "upload/….jpeg", "model": "topaz-gigapixel", "quality": "2160p"}' ``` **JavaScript** ``` javascript const image_path = "path returned by POST /files"; const apiUrl = `https://api.useapi.net/v2/pixverse/images/upscale`; const token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ image_path, model: 'topaz-gigapixel', quality: '2160p' }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests image_path = "path returned by POST /files" apiUrl = f"https://api.useapi.net/v2/pixverse/images/upscale" token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } body = { "image_path": image_path, "model": "topaz-gigapixel", "quality": "2160p" } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-music-create === Document URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-music-create --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> music/create description: "Generate a song or instrumental from a text prompt via POST music/create in the useapi.net PixVerse API v2 — MiniMax music-2.6, ElevenLabs music-v1, and Google Lyria, with optional custom lyrics." parent: PixVerse API nav_order: 1440 --- ## Generate music from a text prompt ## Table of contents June 25, 2026 (November 16, 2026) --- Use a [pixverse.ai](https://app.pixverse.ai) account to generate music. A prompt describes the track, and you can produce three kinds of output — an instrumental, a vocal track with model-written lyrics, or a vocal track with your own lyrics. Generation is asynchronous. The call returns an `audio_id` immediately, then poll [GET music/`audio_id`](/docs/api-pixverse-v2/get-pixverse-music-music_id) until `audio_status_final` is `true`, or pass a [`replyUrl`](#request-body) to receive the result by callback. ##### Model Comparison Matrix | Model | Prompt max | Custom lyrics | Reference images | PixVerse<br>Credits / Cost | Provider cost* | |:------|:-----------|:--------------|:-----------------|:------------------------:|:--------------| | [MiniMax](https://www.minimax.io)<br>`music-2.6` *(default)* | 2,000 | yes, up to 3,500 chars | — | 40 cr / $0.16 | [~$0.15 / track](https://platform.minimax.io/docs/pricing/overview#about-music-models) (≤5 min, existing API users only) | | [ElevenLabs](https://elevenlabs.io)<br>`music-v1` | 4,000 | yes, up to 3,500 chars | — | 150 cr / $0.60 | [$0.15 / min](https://elevenlabs.io/pricing/api) → ~$0.75 (5 min) | | [Google Lyria](https://deepmind.google/technologies/lyria)<br>`lyria-3-pro-preview` | 5,000 | — | 1-10 via `image_path_1`…`10` | 20 cr / $0.08 | [$0.08 / song](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing#lyria) (up to 3 min) | PixVerse cost is for a $60/m Premium plan ($0.004 per credit, as of November 2026) — use the [cost calculator](/docs/api-pixverse-v2) for other plans. *Provider cost is going direct to the model's own provider; prices change, check their pages. All models generate at an automatic duration (the model chooses the length, typically 2-5 minutes). `lyria-3-pro-preview` does not accept custom lyrics, but it can still produce vocals with model-written lyrics — see [`instrumental`](#parameters) and [`lyrics`](#parameters) below. Lyria 3 Pro is also available through [Flow Music](/docs/api-flowmusic-v1), which runs the same model at a lower price with many more features — cover and restyle, lyrics-adjust remix, extend and replace, and audio effects. ##### Output modes The output is determined by `instrumental` and `lyrics` — there is no separate `auto_lyrics` flag, it is derived: | Request | Result | |:--------|:-------| | `instrumental: true` | instrumental, no vocals | | `lyrics` provided | vocals sung from your lyrics (`music-2.6` / `music-v1` only) | | neither | vocals with lyrics written by the model | To retrieve generated music, use: * [GET music/`audio_id`](/docs/api-pixverse-v2/get-pixverse-music-music_id) * [GET music](/docs/api-pixverse-v2/get-pixverse-music) to list all tracks To cancel a track that is still generating, use [DEL scheduler/`id`](/docs/api-pixverse-v2/del-pixverse-scheduler-video_id). > **https://api.useapi.net/v2/pixverse/music/create** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "email": "Optional PixVerse API account email", "prompt": "Required text prompt", "model": "music-2.6", "instrumental": false, "lyrics": "Optional custom lyrics", "image_path_1": "upload/eb20c63d-2a1a-5be6-a562-d3578a2831e3.png", "replyUrl": "Place your call back URL here", "replyRef": "Place your reference id here", "maxJobs": 3 } ``` ##### Parameters - `email` is optional, if not specified API will randomly select account from available [accounts](/docs/api-pixverse-v2/get-pixverse-accounts). - `prompt` is **required**, describe the track you want. Maximum length is model-specific — `music-2.6` 2,000, `music-v1` 4,000, `lyria-3-pro-preview` 5,000 characters. - `model` is optional. Default: `music-2.6`. See [Model Comparison Matrix](#model-comparison-matrix) for the full list. - `instrumental` is optional, default `false`. When `true` the track has no vocals. Cannot be combined with `lyrics`. - `lyrics` is optional and supported by `music-2.6` and `music-v1` only — providing it on `lyria-3-pro-preview` is rejected with **400**. The vocals are sung from the text you supply. Cannot be combined with `instrumental`. Maximum length 3,500 characters. - `image_path_1` through `image_path_10` are optional and supported by `lyria-3-pro-preview` only. Reference image file paths uploaded via [POST files](/docs/api-pixverse-v2/post-pixverse-files) that condition the music. Reference images must be provided sequentially — `image_path_2` requires `image_path_1`, etc. - `replyUrl` is optional, place here your callback URL. This is the preferred and most optimal way to receive results quickly — the API polls every 10 seconds and will call the provided `replyUrl` once the track is completed or failed. We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality. Maximum length 1024 characters. Callback body has the same JSON shape as [GET music/`audio_id`](/docs/api-pixverse-v2/get-pixverse-music-music_id) response. - `replyRef` is optional, place here your reference id which will be stored and returned along with this music response / result. Maximum length 1024 characters. - `maxJobs` is optional, if not specified value from selected [accounts/email](/docs/api-pixverse-v2/get-pixverse-accounts-email) will be used. It should not exceed the number of concurrent generations supported by your account [subscription](https://app.pixverse.ai/subscribe) plan. Valid range: 1…8 ##### Responses **200** **200 OK** Use the returned `audio_id` to retrieve status and results using [GET music/`audio_id`](/docs/api-pixverse-v2/get-pixverse-music-music_id). Check `audio_status_name` for `COMPLETED` and `url` for the generated `.mp3` link. If you specify the optional parameter [`replyUrl`](#request-body), the API will call the provided `replyUrl` with progress updates until the track is complete or fails. ```json { "audio_id": "user:<userid>-pixverse:<email>-music:<number>", "asset_id": 409848161653065, "asset_type": 2, "asset_source": 1, "create_mode": "music", "status": "making", "audio_status": 5, "credits": 40, "audio_status_name": "QUEUED", "audio_status_final": false } ``` **400** **400 Bad Request** Returned when a parameter is invalid, for example a prompt longer than the model allows, `lyrics` on `lyria-3-pro-preview`, or `lyrics` combined with `instrumental`. ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized" } ``` **412** **412 Insufficient credits** Insufficient credits. All Credits have been used up. Please upgrade your membership or purchase credits. ```json { "error": "All Credits have been used up. Please upgrade your membership or purchase credits." } ``` **429** **429 Too Many Requests** Wait in a loop for **at least** 10..30 seconds and retry again. The API query is full and can not accept new [music/create](#request-headers) requests. Size of the query is defined by the [`maxJobs` optional parameter](#request-body). ```json { "error": "Account <email> is busy executing <maxJobs> tasks." "All configured accounts are running at maximum capacity." } ``` **596** **596 Pending mod message** The account has a pending error, and the API does not use it until you add it again with [POST accounts/email](/docs/api-pixverse-v2/post-pixverse-accounts-email). You receive an email when this happens. There are three causes. PixVerse could not sign the account in, most often because its password was changed. Add the account again with the current password. ```json { "error": "Your PixVerse account has pending error. Please address this issue at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email before making any new API calls.", "code": 596 } ``` Or PixVerse suspended the account. PixVerse suspends accounts that break its content rules and does not say which generation caused it. The first response carries PixVerse's own details in `account_moderation`, and later calls return the same `error`. Add the account again after `reinstatement_at`. To ask PixVerse to lift the suspension earlier, write to the `support_email` it gives. ```json { "error": "PixVerse suspended account example@gmail.com for 30 days, from 2026-10-16 09:26 UTC until 2026-11-15 09:26 UTC. PixVerse suspends accounts that break its content rules and does not say which generation caused it. Add the account again at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email after 2026-11-15 09:26 UTC. To ask PixVerse to lift it earlier, write to support@pixverse.ai.", "code": 596, "account_moderation": { "ban_level": "suspend_30d", "action": "temporary_suspend", "duration_days": 30, "suspended_at": "2026-10-16 09:26:25 (UTC)", "reinstatement_at": "2026-11-15 09:26:25 (UTC)", "support_email": "support@pixverse.ai" } } ``` Or PixVerse banned the account for violating its community guidelines. A ban is permanent unless PixVerse accepts an appeal, and the `error` quotes PixVerse's own message, which says how to appeal. Remove the account with [DELETE accounts/email](/docs/api-pixverse-v2/del-pixverse-accounts-email), or add it again only if PixVerse lifts the ban. ```json { "error": "PixVerse banned account example@gmail.com for violating its community guidelines (400024). A ban is permanent unless PixVerse accepts an appeal. PixVerse says: \"Your account has been banned for violating community guidelines. If you wish to appeal, please contact us via ...\" Remove it with DELETE /v2/pixverse/accounts/example@gmail.com, or add it again (https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email) only if PixVerse lifts the ban.", "code": 596 } ``` If every account you have is in this state, a request without `email` returns 596 as well. ##### Model The new track's `audio_id` and status: poll it with [GET music/`audio_id`](/docs/api-pixverse-v2/get-pixverse-music-music_id) until it completes. <details markdown="block" class="model-details"> <summary>The new music track, field by field</summary> ```typescript { // TypeScript, all fields are optional audio_id: string asset_id: number asset_type: number asset_source: number create_mode: string status: string audio_status: number credits: number error: string code: number // added audio_status_name: string audio_status_final: boolean } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST "https://api.useapi.net/v2/pixverse/music/create" \ -d '{"prompt": "An upbeat synthwave track with a clear female vocal"}' ``` **JavaScript** ``` javascript const prompt = "An upbeat synthwave track with a clear female vocal"; const apiUrl = `https://api.useapi.net/v2/pixverse/music/create`; const token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ prompt }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests prompt = "An upbeat synthwave track with a clear female vocal" apiUrl = f"https://api.useapi.net/v2/pixverse/music/create" token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } body = { "prompt": f"{prompt}" } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-music-video-create === Document URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-music-video-create --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> music-video/create description: "Turn a song into a lip-synced AI music video via POST music-video/create in the useapi.net PixVerse API (One-Click MV): 3 modes, 720p or 1080p, up to 6 minutes." parent: PixVerse API nav_order: 1443 --- ## Create a music video from a song November 10, 2026 (November 16, 2026) --- Use a [pixverse.ai](https://app.pixverse.ai) account to turn a song into a finished music video, the same as PixVerse's One-Click MV. Upload the song (10 seconds to 6 minutes), optionally add a character photo, pick a mode and a visual style, and PixVerse plans the shots, generates them and cuts them to the beat. In `performance` mode the character lip-syncs the vocals. With `subtitles: true` it also burns the lyrics in as captions. Generation is asynchronous. The call returns a `video_id` right away, then poll [GET music-video/`video_id`](/docs/api-pixverse-v2/get-pixverse-music-video-video_id) until `status` is `succeeded` or `failed`, or pass a [`replyUrl`](#parameters) to get the result by callback. A 30-second song took about 5 minutes in our tests, a 2½-minute song at 1080p about 16 minutes. Step-by-step example with a full song: [How to Make an AI Music Video from a Song with the PixVerse API](/docs/articles/pixverse-music-video-api). The music video is an ordinary PixVerse video as well: the same `video_id` works with [GET videos/`video_id`](/docs/api-pixverse-v2/get-pixverse-videos-video_id), shows up in [GET videos](/docs/api-pixverse-v2/get-pixverse-videos) and is deleted with [DEL videos/`video_id`](/docs/api-pixverse-v2/del-pixverse-videos-video_id). ##### Modes | Mode | What you get | |:-----|:-------------| | `performance` *(default)* | the character sings the song with lip-sync, made for singer and dancer performance videos | | `expressive` | emotional, atmospheric shots of the character | | `storytelling` | a storyline that follows your `prompt`, with one or two characters, made by PixVerse's partner engine | ##### Prices One minute of song costs (PixVerse bills every second, rounded to the nearest second): | Mode and quality | [Official API](https://docs.platform.pixverse.ai/one-click-vibemv-44144151e0) | Ultra $199/mo (30,000 cr/mo) | Premium $60/mo (15,000 cr/mo) | Pro $30/mo (6,000 cr/mo) | |---|---|---|---|---| | `performance` or `expressive`, 720p | $4.00 (15 cr/s) | $3.98 (10 cr/s) | $2.40 (10 cr/s) | $3.00 (10 cr/s) | | `performance` or `expressive`, 1080p | $6.00 (22.5 cr/s) | $5.97 (15 cr/s) | $3.60 (15 cr/s) | $4.50 (15 cr/s) | | `storytelling`, 720p | not sold | $7.96 (20 cr/s) | $4.80 (20 cr/s) | $6.00 (20 cr/s) | | `storytelling`, 1080p | not sold | $15.92 (40 cr/s) | $9.60 (40 cr/s) | $12.00 (40 cr/s) | The first music video on every PixVerse account is free, at any length and in 1080p, even on a free Basic plan. Prices as of November 2026. While an account's free music video is unused, the [quote](#parameters) shows `cost_credits: 0` and `free: true`. > **https://api.useapi.net/v2/pixverse/music-video/create** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "email": "Optional PixVerse API account email", "audio_path": "upload/8aa34c5f-7f33-4fdc-af40-7357909102cb.mp3", "mode": "performance", "style": "auto", "image_path": "upload/66952750-badc-473b-b2a2-721197e96e7d.jpeg", "music_genre": "hip_hop", "subtitles": true, "lyrics": "That bassline hits me hard right now\nWe turn it up and show them how", "aspect_ratio": "16:9", "quality": "1080p", "quote": false, "replyUrl": "Place your call back URL here", "replyRef": "Place your reference id here", "maxJobs": 3 } ``` ##### Parameters - `email` is optional, if not specified API will randomly select account from available [accounts](/docs/api-pixverse-v2/get-pixverse-accounts). - `audio_path` is **required**, the song: a `path` returned by [POST files](/docs/api-pixverse-v2/post-pixverse-files) for an MP3 upload, or a song from [GET music-video/library](/docs/api-pixverse-v2/get-pixverse-music-video-library). 10 seconds to 6 minutes. PixVerse refused an M4A file in our tests, so convert to MP3 first. - `mode` is optional, `performance` (default), `expressive` or `storytelling`. See [Modes](#modes) and [Prices](#prices). - `style` is optional, the look of the video. The values depend on the mode: - `performance` and `expressive`: `auto` (default, PixVerse picks), `custom` (your own style image, see below), `cinematic`, `underground`, `lo_fi`, `dreamscape`, `woolen_felt`, `candy`, `golden_age`, `voxel`, `retro_game`, `claymation`, `woodland_tale`, `impressionism`, `decadence`, `futuristic`, `chromatic_clash`, `holiday`. - `storytelling`: `photorealistic` (default), `anime`, `2d_modern_animation`, `cyberpunk`, `high_energy`, `digital_art`, `pixel_art`, `city_pop`, `y2k_collage`, `illustration`, `sketch`, `rock_haze`, `bubble_gum_punk`, `claymation`, `metal_noir`, `ghibli`, `midnight_blue_soul`, `lego_blocks`. - `style_image_path` is optional, only with `style: custom`. An image whose look the whole video copies, a `path` from [POST files](/docs/api-pixverse-v2/post-pixverse-files) or a style from the [library](/docs/api-pixverse-v2/get-pixverse-music-video-library). Without it, `custom` uses `image_path` as the style. `style: custom` needs `style_image_path` or `image_path`. - `image_path` is optional, the character who performs: a photo uploaded via [POST files](/docs/api-pixverse-v2/post-pixverse-files) or a character from the [library](/docs/api-pixverse-v2/get-pixverse-music-video-library). A clear, full-body photo with the face visible works best. Without it, PixVerse invents a performer. - `image_path_2` is optional, a second character, `storytelling` only. Needs `image_path`. - `music_genre` is optional, helps PixVerse read the song: `pop`, `rock`, `hip_hop`, `rnb`, `jazz`, `reggae`, `country`, `folk`, `electronic`, `classical`, `soul`, `funk`, `metal`, `ambient`, `others`. Refused by `storytelling`. - `subtitles` is optional, default `false`. `true` burns lyric captions into the video, timed to the vocals. Every video also comes with a copy without captions, see [GET music-video/`video_id`](/docs/api-pixverse-v2/get-pixverse-music-video-video_id). Refused by `storytelling`. - `lyrics` is optional, only with `subtitles: true`. The song's lyrics, one line per caption, so the captions spell the words right. Without it, PixVerse uses the lyrics it detects in the vocals. Refused by `storytelling`. Maximum length 5,000 characters. - `prompt` is **required** for `storytelling` and refused by the other modes, the story to tell. Maximum length 2,000 characters. - `aspect_ratio` is optional, `16:9` (default), `9:16`, `1:1`, `4:3` or `3:4`. - `quality` is optional, `720p` (default) or `1080p`. - `quote` is optional, default `false`. `true` returns the price for this exact request and creates nothing. Quoting is free. - `replyUrl` is optional, place here your callback URL. This is the preferred and most optimal way to receive results quickly — the API polls every 10 seconds and will call the provided `replyUrl` once the music video is completed or failed. We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality. Maximum length 1024 characters. Callback body has the same JSON shape as [GET videos/`video_id`](/docs/api-pixverse-v2/get-pixverse-videos-video_id) response. - `replyRef` is optional, place here your reference id which will be stored and returned along with this video response / result. Maximum length 1024 characters. - `maxJobs` is optional, if not specified value from selected [accounts/email](/docs/api-pixverse-v2/get-pixverse-accounts-email) will be used. It should not exceed the number of concurrent generations supported by your account [subscription](https://app.pixverse.ai/subscribe) plan. Valid range: 1…8 Every request gets a free quote first. If the account cannot afford the video, the API answers `412` before anything is created. ##### Responses **200** **200 OK** Use the returned `video_id` with [GET music-video/`video_id`](/docs/api-pixverse-v2/get-pixverse-music-video-video_id) until `status` is `succeeded` or `failed`. `cost_credits` is what this video costs, `list_cost_credits` the price without the free music video. ```json { "video_id": "user:<userid>-pixverse:<email>-video:642767619916505", "project_id": 192080023076656, "mode": "performance", "quality": "1080p", "aspect_ratio": "16:9", "bill_seconds": 152, "credits_per_second": 15, "list_cost_credits": 2280, "cost_credits": 0, "free": true } ``` With `quote: true` nothing is created: ```json { "quote": true, "mode": "performance", "quality": "720p", "bill_seconds": 30, "credits_per_second": 10, "list_cost_credits": 300, "cost_credits": 300, "free": false, "has_enough_credits": true } ``` **400** **400 Bad Request** A parameter is invalid, for example a `style` that the mode doesn't have, `prompt` outside `storytelling`, `lyrics` without `subtitles`, or an audio format PixVerse refuses. ```json { "error": "Parameter style (anime) is not available for mode performance. Valid values: auto,custom,cinematic,…", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized" } ``` **412** **412 Insufficient credits** The account does not have enough credits for this video. Nothing was created. ```json { "error": "Not enough credits: this music video costs 1800 credits", "code": 412 } ``` **429** **429 Too Many Requests** Wait in a loop for **at least** 10..30 seconds and retry again. The API query is full and can not accept new requests. Size of the query is defined by the [`maxJobs` optional parameter](#parameters). ```json { "error": "Account <email> is busy executing <maxJobs> tasks." "All configured accounts are running at maximum capacity." } ``` **596** **596 Pending mod message** The account has a pending error, and the API does not use it until you add it again with [POST accounts/email](/docs/api-pixverse-v2/post-pixverse-accounts-email). You receive an email when this happens. There are three causes. PixVerse could not sign the account in, most often because its password was changed. Add the account again with the current password. ```json { "error": "Your PixVerse account has pending error. Please address this issue at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email before making any new API calls.", "code": 596 } ``` Or PixVerse suspended the account. PixVerse suspends accounts that break its content rules and does not say which generation caused it. The first response carries PixVerse's own details in `account_moderation`, and later calls return the same `error`. Add the account again after `reinstatement_at`. To ask PixVerse to lift the suspension earlier, write to the `support_email` it gives. ```json { "error": "PixVerse suspended account example@gmail.com for 30 days, from 2026-10-16 09:26 UTC until 2026-11-15 09:26 UTC. PixVerse suspends accounts that break its content rules and does not say which generation caused it. Add the account again at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email after 2026-11-15 09:26 UTC. To ask PixVerse to lift it earlier, write to support@pixverse.ai.", "code": 596, "account_moderation": { "ban_level": "suspend_30d", "action": "temporary_suspend", "duration_days": 30, "suspended_at": "2026-10-16 09:26:25 (UTC)", "reinstatement_at": "2026-11-15 09:26:25 (UTC)", "support_email": "support@pixverse.ai" } } ``` Or PixVerse banned the account for violating its community guidelines. A ban is permanent unless PixVerse accepts an appeal, and the `error` quotes PixVerse's own message, which says how to appeal. Remove the account with [DELETE accounts/email](/docs/api-pixverse-v2/del-pixverse-accounts-email), or add it again only if PixVerse lifts the ban. ```json { "error": "PixVerse banned account example@gmail.com for violating its community guidelines (400024). A ban is permanent unless PixVerse accepts an appeal. PixVerse says: \"Your account has been banned for violating community guidelines. If you wish to appeal, please contact us via ...\" Remove it with DELETE /v2/pixverse/accounts/example@gmail.com, or add it again (https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email) only if PixVerse lifts the ban.", "code": 596 } ``` If every account you have is in this state, a request without `email` returns 596 as well. ##### Model The new music video's `video_id` to poll with [GET music-video/`video_id`](/docs/api-pixverse-v2/get-pixverse-music-video-video_id) and its cost, or only the price with `quote: true`. <details markdown="block" class="model-details"> <summary>The new music video or its price quote, field by field</summary> ```typescript { // TypeScript, all fields are optional video_id: string project_id: number mode: 'performance' | 'expressive' | 'storytelling' quality: '720p' | '1080p' aspect_ratio: string bill_seconds: number credits_per_second: number list_cost_credits: number cost_credits: number free: boolean error: string code: number // quote: true only quote: boolean has_enough_credits: boolean } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST "https://api.useapi.net/v2/pixverse/music-video/create" \ -d '{"audio_path": "upload/<song>.mp3", "image_path": "upload/<singer>.jpeg", "aspect_ratio": "9:16"}' ``` **JavaScript** ``` javascript const apiUrl = `https://api.useapi.net/v2/pixverse/music-video/create`; const token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ audio_path: "upload/<song>.mp3", image_path: "upload/<singer>.jpeg", aspect_ratio: "9:16" }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests apiUrl = f"https://api.useapi.net/v2/pixverse/music-video/create" token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } body = { "audio_path": "upload/<song>.mp3", "image_path": "upload/<singer>.jpeg", "aspect_ratio": "9:16" } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-speech-create === Document URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-speech-create --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> speech/create description: "Generate text-to-speech via POST speech/create in the useapi.net PixVerse API v2 — MiniMax speech-2.8 and ElevenLabs (multilingual-v2, v3 audio tags, turbo-v2.5), with per-voice settings, emotions, and 40+ languages." parent: PixVerse API nav_order: 1470 --- ## Generate speech from text ## Table of contents June 25, 2026 (November 16, 2026) --- Use a [pixverse.ai](https://app.pixverse.ai) account to turn text into speech. You pick a `model`, a `voice` (from [GET speech/voices](/docs/api-pixverse-v2/get-pixverse-speech-voices)), and optional per-voice settings, and the API returns spoken audio as an `.mp3`. Generation is asynchronous. The call returns an `audio_id` immediately, then poll [GET speech/`audio_id`](/docs/api-pixverse-v2/get-pixverse-speech-speech_id) until `audio_status_final` is `true`, or pass a [`replyUrl`](#request-body) to receive the result by callback. ##### Model Comparison Matrix | Model | Voice settings | Max chars | PixVerse<br>Credits / Cost (per 1K chars *) | Provider cost (per 1K chars **) | |:------|:---------------|:----------|:--------------------------:|:----------------| | [ElevenLabs](https://elevenlabs.io)<br>`eleven-multilingual-v2` | stability, similarity_boost, speed, **style** | 10,000 | 20 cr / $0.08 | [$0.10](https://elevenlabs.io/pricing/api) | | [ElevenLabs](https://elevenlabs.io)<br>`eleven-v3` | stability, similarity_boost, speed<br>+ inline **audio tags** | 5,000 | 20 cr / $0.08 | [$0.10](https://elevenlabs.io/pricing/api) | | [ElevenLabs](https://elevenlabs.io)<br>`eleven-turbo-v2.5` | stability, similarity_boost, speed | 40,000 | 10 cr / $0.04 | [$0.05](https://elevenlabs.io/pricing/api) | | [MiniMax](https://www.minimax.io)<br>`speech-2.8-hd` *(default)* | speed, volume, pitch, **emotion** | 10,000 | 20 cr / $0.08 | [$0.10](https://platform.minimax.io/docs/pricing/overview#models/speech) | | [MiniMax](https://www.minimax.io)<br>`speech-2.8-turbo` | speed, volume, pitch, **emotion** | 10,000 | 10 cr / $0.04 | [$0.06](https://platform.minimax.io/docs/pricing/overview#models/speech) | Billing is per-character, so 500 characters costs half. *PixVerse pricing is for the $60/mo Premium plan ($0.004 per credit) — see the [cost calculator](/docs/api-pixverse-v2) for other plans. **Provider cost is the price of going direct to the model's own provider (their public rates, which change). The two providers take **different** voice settings — MiniMax voices respond to `emotion`, ElevenLabs voices to `stability` / `similarity_boost` / `style`. Sending a setting to the wrong family is rejected with **400**. See [Voice settings](#voice-settings) below. ##### Voices Every request needs a `voice_id` from [GET speech/voices](/docs/api-pixverse-v2/get-pixverse-speech-voices), filtered by model and language — the paired `provider_voice_id` is filled in for you automatically. The MiniMax catalog carries 300+ voices (male, female, and neutral), ElevenLabs ~20, each with `gender`, `accent`, and `style_tags` to help you choose. ##### Voice settings All settings are optional — omit them for the voice's natural delivery. Ranges are enforced per model family. MiniMax (`speech-2.8-hd`, `speech-2.8-turbo`): | Setting | Range | Default | Notes | |:--------|:------|:--------|:------| | `speed` | 0.5 – 2 | 1 | playback speed | | `volume` | 0 – 10 | 1 | loudness | | `pitch` | -12 – 12 | 0 | integer semitones | | `emotion` | enum | `auto` | `auto`, `happy`, `sad`, `angry`, `fearful`, `disgusted`, `surprised`, `neutral`, `calm` | ElevenLabs (`eleven-multilingual-v2`, `eleven-v3`, `eleven-turbo-v2.5`): | Setting | Range | Default | Notes | |:--------|:------|:--------|:------| | `stability` | 0 – 1 | 0.5 | lower = more expressive, higher = more consistent | | `similarity_boost` | 0 – 1 | 0.75 | adherence to the original voice | | `speed` | 0.7 – 1.2 | 1 | playback speed | | `style` | 0 – 1 | 0 | `eleven-multilingual-v2` only — style exaggeration | | `use_speaker_boost` | boolean | — | `eleven-multilingual-v2` only | `style` and `use_speaker_boost` are accepted only by `eleven-multilingual-v2` — sending them to another model is rejected with **400**. ##### Audio tags (eleven-v3) `eleven-v3` is ElevenLabs' most expressive model — instead of an `emotion` setting, you direct the performance with **inline audio tags** placed right in the `text`, such as `[whispers]`, `[excited]`, `[shouts]`, `[sighs]`, `[laughs]`, `[sad]`, `[curious]`, and `[gasps]`. Tags work best with longer, sentence-level text that gives the model room to perform. ``` "[whispers] The Force surrounds us. It binds the galaxy together. [curious] Do you feel it? [excited] Your destiny is calling... [shouts] may the Force be with you!" ``` ##### Languages `language_code` is optional and validated per model against the live catalog from [GET speech/models](/docs/api-pixverse-v2/get-pixverse-speech-models) — MiniMax and the ElevenLabs `v2` / `turbo` models support 30-40 languages (`auto` plus ISO codes like `en`, `es`, `ja`, `zh`). `eleven-v3` auto-detects the language and rejects `language_code` with **400**. To retrieve generated speech, use: * [GET speech/`audio_id`](/docs/api-pixverse-v2/get-pixverse-speech-speech_id) * [GET speech](/docs/api-pixverse-v2/get-pixverse-speech) to list all speech To cancel a job that is still generating, use [DEL scheduler/`id`](/docs/api-pixverse-v2/del-pixverse-scheduler-video_id). > **https://api.useapi.net/v2/pixverse/speech/create** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "email": "Optional PixVerse API account email", "model": "speech-2.8-hd", "text": "Required text to speak", "voice_id": "minimax_english_radiant_girl", "language_code": "en", "emotion": "happy", "replyUrl": "Place your call back URL here", "replyRef": "Place your reference id here", "maxJobs": 3 } ``` ##### Parameters - `email` is optional, if not specified API will randomly select account from available [accounts](/docs/api-pixverse-v2/get-pixverse-accounts). - `model` is optional. Default: `speech-2.8-hd`. See [Model Comparison Matrix](#model-comparison-matrix). - `text` is **required**, the words to speak. Maximum length is model-specific — see the matrix (`eleven-v3` 5,000, `eleven-turbo-v2.5` 40,000, others 10,000). For `eleven-v3` you may embed [audio tags](#audio-tags-eleven-v3). - `voice_id` is **required**. A voice from [GET speech/voices](/docs/api-pixverse-v2/get-pixverse-speech-voices). Its paired `provider_voice_id` is derived automatically — you do not pass it. - `language_code` is optional, see [Languages](#languages). Validated per model — rejected for `eleven-v3`. - `speed`, `volume`, `pitch`, `emotion` (MiniMax) and `stability`, `similarity_boost`, `speed`, `style`, `use_speaker_boost` (ElevenLabs) are optional [voice settings](#voice-settings). Settings from the wrong provider family are rejected with **400**. - `replyUrl` is optional, place here your callback URL. This is the preferred and most optimal way to receive results quickly — the API polls every 10 seconds and will call the provided `replyUrl` once the audio is completed or failed. We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality. Maximum length 1024 characters. Callback body has the same JSON shape as [GET speech/`audio_id`](/docs/api-pixverse-v2/get-pixverse-speech-speech_id) response. - `replyRef` is optional, place here your reference id which will be stored and returned along with this speech response / result. Maximum length 1024 characters. - `maxJobs` is optional, if not specified value from selected [accounts/email](/docs/api-pixverse-v2/get-pixverse-accounts-email) will be used. It should not exceed the number of concurrent generations supported by your account [subscription](https://app.pixverse.ai/subscribe) plan. Valid range: 1…8 ##### Responses **200** **200 OK** Use the returned `audio_id` to retrieve status and results using [GET speech/`audio_id`](/docs/api-pixverse-v2/get-pixverse-speech-speech_id). Check `audio_status_name` for `COMPLETED` and `url` for the generated `.mp3` link. If you specify the optional parameter [`replyUrl`](#request-body), the API will call the provided `replyUrl` with progress updates until the audio is complete or fails. ```json { "audio_id": "user:<userid>-pixverse:<email>-speech:<number>", "asset_id": 409875792979281, "asset_type": 2, "asset_source": 1, "create_mode": "voice", "status": "making", "audio_status": 5, "credits": 1, "audio_status_name": "QUEUED", "audio_status_final": false } ``` **400** **400 Bad Request** Returned when a parameter is invalid, for example `text` longer than the model allows, an `emotion` on an ElevenLabs voice, `stability` on a MiniMax voice, or `language_code` on `eleven-v3`. ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized" } ``` **412** **412 Insufficient credits** Insufficient credits. All Credits have been used up. Please upgrade your membership or purchase credits. ```json { "error": "All Credits have been used up. Please upgrade your membership or purchase credits." } ``` **429** **429 Too Many Requests** Wait in a loop for **at least** 10..30 seconds and retry again. The API query is full and can not accept new [speech/create](#request-headers) requests. Size of the query is defined by the [`maxJobs` optional parameter](#request-body). ```json { "error": "Account <email> is busy executing <maxJobs> tasks." "All configured accounts are running at maximum capacity." } ``` **596** **596 Pending mod message** The account has a pending error, and the API does not use it until you add it again with [POST accounts/email](/docs/api-pixverse-v2/post-pixverse-accounts-email). You receive an email when this happens. There are three causes. PixVerse could not sign the account in, most often because its password was changed. Add the account again with the current password. ```json { "error": "Your PixVerse account has pending error. Please address this issue at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email before making any new API calls.", "code": 596 } ``` Or PixVerse suspended the account. PixVerse suspends accounts that break its content rules and does not say which generation caused it. The first response carries PixVerse's own details in `account_moderation`, and later calls return the same `error`. Add the account again after `reinstatement_at`. To ask PixVerse to lift the suspension earlier, write to the `support_email` it gives. ```json { "error": "PixVerse suspended account example@gmail.com for 30 days, from 2026-10-16 09:26 UTC until 2026-11-15 09:26 UTC. PixVerse suspends accounts that break its content rules and does not say which generation caused it. Add the account again at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email after 2026-11-15 09:26 UTC. To ask PixVerse to lift it earlier, write to support@pixverse.ai.", "code": 596, "account_moderation": { "ban_level": "suspend_30d", "action": "temporary_suspend", "duration_days": 30, "suspended_at": "2026-10-16 09:26:25 (UTC)", "reinstatement_at": "2026-11-15 09:26:25 (UTC)", "support_email": "support@pixverse.ai" } } ``` Or PixVerse banned the account for violating its community guidelines. A ban is permanent unless PixVerse accepts an appeal, and the `error` quotes PixVerse's own message, which says how to appeal. Remove the account with [DELETE accounts/email](/docs/api-pixverse-v2/del-pixverse-accounts-email), or add it again only if PixVerse lifts the ban. ```json { "error": "PixVerse banned account example@gmail.com for violating its community guidelines (400024). A ban is permanent unless PixVerse accepts an appeal. PixVerse says: \"Your account has been banned for violating community guidelines. If you wish to appeal, please contact us via ...\" Remove it with DELETE /v2/pixverse/accounts/example@gmail.com, or add it again (https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email) only if PixVerse lifts the ban.", "code": 596 } ``` If every account you have is in this state, a request without `email` returns 596 as well. ##### Model The new speech's `audio_id` and status: poll it with [GET speech/`audio_id`](/docs/api-pixverse-v2/get-pixverse-speech-speech_id) until it completes. <details markdown="block" class="model-details"> <summary>The new speech audio, field by field</summary> ```typescript { // TypeScript, all fields are optional audio_id: string asset_id: number asset_type: number asset_source: number create_mode: string status: string audio_status: number credits: number error: string code: number // added audio_status_name: string audio_status_final: boolean } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST "https://api.useapi.net/v2/pixverse/speech/create" \ -d '{"model": "speech-2.8-hd", "text": "May the Force be with you.", "voice_id": "minimax_english_radiant_girl", "emotion": "happy"}' ``` **JavaScript** ``` javascript const apiUrl = `https://api.useapi.net/v2/pixverse/speech/create`; const token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ model: "speech-2.8-hd", text: "May the Force be with you.", voice_id: "minimax_english_radiant_girl", emotion: "happy" }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests apiUrl = f"https://api.useapi.net/v2/pixverse/speech/create" token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } body = { "model": "speech-2.8-hd", "text": "May the Force be with you.", "voice_id": "minimax_english_radiant_girl", "emotion": "happy" } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-videos-create-final === Document URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-videos-create-final --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/create-final description: "Turn a 480p Seedance 2.5 draft into the finished 1080p or 4K video via POST videos/create-final in the useapi.net PixVerse API, within 14 days of the draft." parent: PixVerse API nav_order: 897 --- ## Create the final 1080p or 4K video from a Seedance 2.5 draft November 15, 2026 (November 16, 2026) --- Seedance 2.5 Draft Mode lets you check an idea cheaply before paying for the real render. Create a 480p draft with model `seedance-2.5-draft` on [POST videos/create](/docs/api-pixverse-v2/post-pixverse-videos-create-v4), [POST videos/create-frames](/docs/api-pixverse-v2/post-pixverse-videos-create-frames-v4) or [POST videos/create-fusion](/docs/api-pixverse-v2/post-pixverse-videos-create-fusion). When you like it, this endpoint renders the same video with Seedance 2.5 at 1080p or 4K. This is PixVerse's "Create Final" button. The final keeps the draft's prompt, references, duration and aspect ratio. A draft can be finished for 14 days after it was made, and more than once, for example once at 1080p and once at 4K. > **https://api.useapi.net/v2/pixverse/videos/create-final** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "video_id": "user:<userid>-pixverse:<email>-video:<number>", "quality": "1080p", "replyUrl": "Place your call back URL here", "replyRef": "Place your reference id here", "maxJobs": 3 } ``` - `video_id` is **required**, the `video_id` of a completed `seedance-2.5-draft` video. The final is made on the same PixVerse account as the draft, which the id names, so no `email` is needed. - `quality` is optional. Supported values: `1080p` (default) and `2160p` (4K). - `relax_mode` is optional, for third-party models only (PixVerse's own models reject it). PixVerse discounts third-party video per model and plan, and the discount applies unless you send `relax_mode: false`, which pays the full price. `relax_mode: true` costs the same as leaving it out, and PixVerse records the video as made in its Relax Mode. If PixVerse refuses Relax Mode for that model on the account's plan, `relax_mode: true` returns `412` and nothing is charged. As of November 2026: | Plan | Discount | |---|---| | Ultra, Team Ultra | `minimax-h3` and `wan-3.0` free, `seedance-2.0-fast` and `seedance-2.0-mini` 90% off, `kling-4.0` 80% off, `gemini-omni-flash` 70% off, Veo 3.1 60% off, `flux-3.0` and `seedance-2.0` 50% off, `seedance-2.5` and `minimax-h3-max` 45% off, `kling-o3`, `grok-imagine-1.5` and `happyhorse-1.0` 40% off, `kling-v3`, `grok-imagine`, `seedance-2.5-flash` and `seedance-2.5-draft` 20% off | | Premium | `minimax-h3` and `wan-3.0` free, `seedance-2.0-fast` and `seedance-2.0-mini` 30% off | | Pro | `seedance-2.0-fast` and `seedance-2.0-mini` 10% off | - `replyUrl` is optional. This is the preferred and most optimal way to receive results quickly — the API polls every 10 seconds and will call the provided `replyUrl` once the PixVerse video is completed or failed. Maximum length 1024 characters. We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality. Callback body has the same JSON shape as [GET /videos/`video_id`](/docs/api-pixverse-v2/get-pixverse-videos-video_id) response. - `replyRef` is optional, place here your reference id which will be stored and returned along with this PixVerse video response / result. Maximum length 1024 characters. - `maxJobs` is optional, if not specified value from selected [accounts/email](/docs/api-pixverse-v2/get-pixverse-accounts-email) will be used. Valid range: 1…8 It should not exceed the number of concurrent generations supported by your account [subscription](https://app.pixverse.ai/subscribe) plan. ##### Pricing The draft and the final are billed separately, per second of video, at the Seedance 2.5 rates. A 4-second video costs this much of each plan's monthly credits (Ultra $199 for 30,000 credits, Premium $60 for 15,000, Pro $30 for 6,000, as of November 2026): | Step | `quality` | Credits per second | Ultra $199/m | Premium $60/m | Pro $30/m | |---|:-:|:-:|:-:|:-:|:-:| | Draft (`seedance-2.5-draft`) | `480p` | 35 | $0.74 / 112 cr | $0.56 / 140 cr | $0.70 / 140 cr | | Draft with a reference video | `480p` | 21, on output plus reference seconds | $0.111/sec | $0.084/sec | $0.105/sec | | Final | `1080p` | 170 | $2.49 / 375 cr | $2.72 / 680 cr | $3.40 / 680 cr | | Final | `2160p` | 286 | $4.18 / 630 cr | $4.58 / 1,144 cr | $5.72 / 1,144 cr | Ultra and Team Ultra take 20% off the draft and 45% off the final unless the request sends `relax_mode: false`, which pays the full credits. The Ultra draft and 1080p final were measured on November 15, 2026. ##### How to tell a draft from a final [GET /videos/`video_id`](/docs/api-pixverse-v2/get-pixverse-videos-video_id) returns a `seedance_draft` object on both: ```json "seedance_draft": { "stage": "draft", "provider_created_at": "2026-11-15T18:53:27Z", "validity_days": 14, "expires_at": "2026-11-29T18:53:27Z", "can_create_final": true, "final_video_ids": ["user:<userid>-pixverse:<email>-video:<number>"] } ``` A draft can be finished while `can_create_final` is `true`: it has completed and `expires_at` has not passed. `final_video_ids` lists the finals already made from it. A final has `"stage": "final"` and points back to its draft in `source_draft_video_id`. ##### Responses **200** **200 OK** Use the returned `video_id` to retrieve video status and results using [GET /videos/`video_id`](/docs/api-pixverse-v2/get-pixverse-videos-video_id). Check if the field `video_status_final` is `true` or `video_status_name` is `COMPLETED`. The field `url` will contain the final video link. Its `model` is `seedance-2.5`. If you specify the optional parameter [`replyUrl`](#request-body), the API will call the provided `replyUrl` with video progress updates until the video is complete or fails. ```json { "video_id": "user:<userid>-pixverse:<email>-video:<number>", "video_ids": [435500102834862], "success_count": 1, "total_count": 1, "cost_credits": 680 } ``` **400** **400 Bad Request** Returned when the video is not a Seedance 2.5 draft, when the draft has not completed (it is still rendering or was moderated) and when it has expired. Nothing is submitted and no credits are used. ```json { "error": "Cannot create a final from video user:<userid>-pixverse:<email>-video:<number>: the draft expired on 2026-11-29T18:53:27Z (drafts are kept 14 days)" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized" } ``` **412** **412 Insufficient credits** Insufficient credits. All Credits have been used up. Please upgrade your membership or purchase credits. ```json { "error": "All Credits have been used up. Please upgrade your membership or purchase credits." } ``` **429** **429 Too Many Requests** Wait in a loop for **at least** 10..30 seconds and retry again. There are two possible cases for API response 429: 1. API query is full and can not accept new [videos/create-final](#request-headers) requests. Size of query defined by [`maxJobs` optional parameter](#request-body). ```json { "error": "Account <email> is busy executing <maxJobs> tasks." "All configured accounts are running at maximum capacity." } ``` 2. The API received an HTTP response status 429 from PixVerse. Please refer to your [subscription](https://app.pixverse.ai/subscribe) plan for the maximum allowed tasks in the queue. ```json { "error": "Reached the limit for concurrent generations." } ``` **596** **596 Pending mod message** The account has a pending error, and the API does not use it until you add it again with [POST accounts/email](/docs/api-pixverse-v2/post-pixverse-accounts-email). You receive an email when this happens. There are three causes. PixVerse could not sign the account in, most often because its password was changed. Add the account again with the current password. ```json { "error": "Your PixVerse account has pending error. Please address this issue at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email before making any new API calls.", "code": 596 } ``` Or PixVerse suspended the account. PixVerse suspends accounts that break its content rules and does not say which generation caused it. The first response carries PixVerse's own details in `account_moderation`, and later calls return the same `error`. Add the account again after `reinstatement_at`. To ask PixVerse to lift the suspension earlier, write to the `support_email` it gives. ```json { "error": "PixVerse suspended account example@gmail.com for 30 days, from 2026-10-16 09:26 UTC until 2026-11-15 09:26 UTC. PixVerse suspends accounts that break its content rules and does not say which generation caused it. Add the account again at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email after 2026-11-15 09:26 UTC. To ask PixVerse to lift it earlier, write to support@pixverse.ai.", "code": 596, "account_moderation": { "ban_level": "suspend_30d", "action": "temporary_suspend", "duration_days": 30, "suspended_at": "2026-10-16 09:26:25 (UTC)", "reinstatement_at": "2026-11-15 09:26:25 (UTC)", "support_email": "support@pixverse.ai" } } ``` Or PixVerse banned the account for violating its community guidelines. A ban is permanent unless PixVerse accepts an appeal, and the `error` quotes PixVerse's own message, which says how to appeal. Remove the account with [DELETE accounts/email](/docs/api-pixverse-v2/del-pixverse-accounts-email), or add it again only if PixVerse lifts the ban. ```json { "error": "PixVerse banned account example@gmail.com for violating its community guidelines (400024). A ban is permanent unless PixVerse accepts an appeal. PixVerse says: \"Your account has been banned for violating community guidelines. If you wish to appeal, please contact us via ...\" Remove it with DELETE /v2/pixverse/accounts/example@gmail.com, or add it again (https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email) only if PixVerse lifts the ban.", "code": 596 } ``` If every account you have is in this state, a request without `email` returns 596 as well. ##### Model The final video's `video_id` and the credits it cost: poll it with [GET videos/`video_id`](/docs/api-pixverse-v2/get-pixverse-videos-video_id) until it completes. <details markdown="block" class="model-details"> <summary>The new final video, field by field</summary> ```typescript { // TypeScript, all fields are optional video_id: string video_ids: number[] success_count: number total_count: number cost_credits: number error: string } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST "https://api.useapi.net/v2/pixverse/videos/create-final" \ -d '{"video_id": "user:…-pixverse:…-video:…", "quality": "1080p"}' ``` **JavaScript** ``` javascript const video_id = "video_id of a completed seedance-2.5-draft video"; const apiUrl = `https://api.useapi.net/v2/pixverse/videos/create-final`; const token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ video_id, quality: '1080p' }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests video_id = "video_id of a completed seedance-2.5-draft video" apiUrl = f"https://api.useapi.net/v2/pixverse/videos/create-final" token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } body = { "video_id": video_id, "quality": "1080p" } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-videos-create-frames-v4 === Document URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-videos-create-frames-v4 --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/create-frames description: "Generate a first-to-last-frame transition video via POST videos/create-frames in the useapi.net PixVerse API v2, with native and third-party model support." parent: PixVerse API nav_order: 860 --- ## Create video using first and last frames March 31, 2025 (November 16, 2026) --- This endpoint creates a **2-frame transition** (first frame → last frame) and supports: - Native PixVerse: `v5.6` (default), `v5.5`, `v5`, `v6`, `pixverse-c1` - Third-party: `seedance-2.5`, `seedance-2.5-flash`, `seedance-2.5-draft`, `seedance-2.0`, `seedance-2.0-fast`, `seedance-2.0-mini`, `kling-4.0`, `kling-o3`, `kling-v3`, `veo-3.1-lite`, `veo-3.1-standard`, `veo-3.1-fast`, `minimax-h3`, `minimax-h3-max`, `wan-3.0` See [Model Capabilities](/docs/api-pixverse-v2/model-capabilities) for per-model quality and duration constraints. To upload prompt image use [POST /files](/docs/api-pixverse-v2/post-pixverse-files). > **https://api.useapi.net/v2/pixverse/videos/create-frames** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "email": "Optional PixVerse API account email", "prompt": "Optional text prompt", "first_frame_path": "upload/7d16f-eed2-a8f4-cef8-aa44-72807n313.jpeg", "last_frame_path": "upload/e7484a28-6efd-174d-7c02-316ef1a5d.jpeg", "duration": 8, "quality": "1080p", "seed": 654321, "replyUrl": "Place your call back URL here", "replyRef": "Place your reference id here", "maxJobs": 3 } ``` - `email` is optional, if not specified API will randomly select account from available [accounts](/docs/api-pixverse-v2/get-pixverse-accounts). - `model` is optional. Default: `v5.6`. Supported values — native PixVerse: `v5.6`, `v5.5`, `v5`, `v6`, `pixverse-c1`. Third-party: `seedance-2.5`, `seedance-2.5-flash`, `seedance-2.5-draft`, `seedance-2.0`, `seedance-2.0-fast`, `seedance-2.0-mini`, `kling-4.0`, `kling-o3`, `kling-v3`, `veo-3.1-lite`, `veo-3.1-standard`, `veo-3.1-fast`, `minimax-h3`, `minimax-h3-max`, `wan-3.0`. See [Model Capabilities](/docs/api-pixverse-v2/model-capabilities) for per-model constraints. - `prompt` is optional, describe your video. Maximum length 5,000 characters, 20,000 for `wan-3.0`, 15,000 for `seedance-2.5`, `seedance-2.5-flash` and `seedance-2.5-draft`, 7,000 for `minimax-h3` and `minimax-h3-max`, 3,500 for `veo-3.1-lite`, `veo-3.1-standard` and `veo-3.1-fast`, and 2,500 for `kling-4.0`, `kling-o3` and `kling-v3`. - `first_frame_path` is **required**, provide path of uploaded image via [POST /files](/docs/api-pixverse-v2/post-pixverse-files). - `last_frame_path` is **required**, provide path of uploaded image via [POST /files](/docs/api-pixverse-v2/post-pixverse-files). - `duration` is optional for `v5`, `v5.5` and `v5.6`, where it defaults to `5` and takes `1` to `8`. `v6`, `pixverse-c1` and every third-party model **require** it. Accepted values depend on the model — see [Model Capabilities](/docs/api-pixverse-v2/model-capabilities). - `quality` is optional for `v5`, `v5.5` and `v5.6`. `v6`, `pixverse-c1` and every third-party model **require** it. Accepted values depend on the model — see [Model Capabilities](/docs/api-pixverse-v2/model-capabilities). **Kling note:** `kling-4.0` takes `720p` or `1080p` as the real output resolution. For `kling-o3` / `kling-v3`, `quality` selects an upstream tier rather than an output resolution — `720p` routes to Standard, `1080p` to Pro, and `2160p` to the 4K tier. PixVerse renders both Standard and Pro at 720p, so only `2160p` changes the resolution. - `audio` is optional. Behavior depends on the model: * **Toggle** (`true`/`false`) — `v5.5`, `v5.6`, `v6`, `pixverse-c1`, `seedance-2.0`, `seedance-2.0-fast`, `seedance-2.0-mini`, `kling-o3`, `kling-v3`, `wan-3.0`. * **Always on** (cannot disable) — `veo-3.1-standard`, `veo-3.1-fast`. * **Not supported** — `seedance-2.5`, `seedance-2.5-flash`, `seedance-2.5-draft`, `minimax-h3`, `minimax-h3-max`, `kling-4.0` (native audio, always on) and `veo-3.1-lite` reject it. `v5` accepts the field and ignores it. Supported values: not specified (default), `false`, `true`. - `aspect_ratio` is **not accepted** — transition derives aspect ratio from the first frame. - `preview_mode` is optional. Only supported for the native PixVerse models accepted by this endpoint (`v5`, `v5.5`, `v5.6`, `v6`, `pixverse-c1`) — third-party models reject this flag. Set to `true` for fast preview generation (lower quality, faster results). Preview videos can later be upscaled via [POST videos/upscale](/docs/api-pixverse-v2/post-pixverse-videos-upscale). Supported values: `false` (default), `true`. - `auto_sound` is optional (v5 only). Set to `true` to generate videos with sound. Supported values: not specified (default), `false`, `true`. - `sound_effect_prompt` is optional (v5 only), describe the sound eg "the sound of waves hitting the shore". - `lip_sync_tts_prompt` is optional (v5 only), enter character lines. Maximum length 140 characters. - `lip_sync_tts_speaker_id` is optional (v5 only), specify desired lipsync voice see [GET videos/voices](/docs/api-pixverse-v2/get-pixverse-videos-voices). - `seed` is optional. Only supported for the native PixVerse models accepted by this endpoint (`v5`, `v5.5`, `v5.6`, `v6`, `pixverse-c1`) — third-party models reject this flag. Valid range 1…2147483647. - `off_peak_mode` is optional. Set to `true` to generate videos during low-demand periods at a reduced credit cost. Only supported for the native PixVerse models accepted by this endpoint (`v5`, `v5.5`, `v5.6`, `v6`, `pixverse-c1`) — third-party models reject this flag. Discount varies by subscription plan: **Pro** 30% off, **Premium** 50% off, **Ultra** unlimited free. Results are usually delivered within 24 hours. Off-Peak generations are not tracked by the scheduler, don't count toward concurrent-job limits, and the `replyUrl` webhook is not called — use [GET videos](/docs/api-pixverse-v2/get-pixverse-videos) to retrieve results. Supported values: `false` (default), `true`. - `relax_mode` is optional, for third-party models only (PixVerse's own models reject it). PixVerse discounts third-party video per model and plan, and the discount applies unless you send `relax_mode: false`, which pays the full price. `relax_mode: true` costs the same as leaving it out, and PixVerse records the video as made in its Relax Mode. If PixVerse refuses Relax Mode for that model on the account's plan, `relax_mode: true` returns `412` and nothing is charged. As of November 2026: | Plan | Discount | |---|---| | Ultra, Team Ultra | `minimax-h3` and `wan-3.0` free, `seedance-2.0-fast` and `seedance-2.0-mini` 90% off, `kling-4.0` 80% off, `gemini-omni-flash` 70% off, Veo 3.1 60% off, `flux-3.0` and `seedance-2.0` 50% off, `seedance-2.5` and `minimax-h3-max` 45% off, `kling-o3`, `grok-imagine-1.5` and `happyhorse-1.0` 40% off, `kling-v3`, `grok-imagine`, `seedance-2.5-flash` and `seedance-2.5-draft` 20% off | | Premium | `minimax-h3` and `wan-3.0` free, `seedance-2.0-fast` and `seedance-2.0-mini` 30% off | | Pro | `seedance-2.0-fast` and `seedance-2.0-mini` 10% off | - `replyUrl` is optional. This is the preferred and most optimal way to receive results quickly — the API polls every 10 seconds and will call the provided `replyUrl` once the PixVerse video is completed or failed. Maximum length 1024 characters. We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality. Callback body has the same JSON shape as [GET /videos/`video_id`](/docs/api-pixverse-v2/get-pixverse-videos-video_id) response. - `replyRef` is optional, place here your reference id which will be stored and returned along with this PixVerse video response / result. Maximum length 1024 characters. - `maxJobs` is optional, if not specified value from selected [accounts/email](/docs/api-pixverse-v2/get-pixverse-accounts-email) will be used. Valid range: 1…8 It should not exceed the number of concurrent generations supported by your account [subscription](https://app.pixverse.ai/subscribe) plan. ##### Responses **200** **200 OK** Use the returned `video_id` to retrieve video status and results using [GET /videos](/docs/api-pixverse-v2/get-pixverse-videos). Locate the video in the response array and check if the field `video_status_final` is `true` or `video_status_name` is `COMPLETED`. The field `url` will contain the generated video link. If you specify the optional parameter [`replyUrl`](#request-body), the API will call the provided `replyUrl` with video progress updates until the video is complete or fails. ```json { "video_id": "user:<userid>-pixverse:<email>-video:<number>" } ``` **400** **400 Bad Request** ```json { "error": "<Error message>" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized" } ``` **412** **412 Insufficient credits** Insufficient credits. All Credits have been used up. Please upgrade your membership or purchase credits. ```json { "error": "All Credits have been used up. Please upgrade your membership or purchase credits." } ``` **422** **422 Unprocessable Content** Moderated message. ```json { "error": "Your prompt has triggered our AI moderator, please re-enter your prompt" } ``` **429** **429 Too Many Requests** Wait in a loop for **at least** 10..30 seconds and retry again. There are two possible cases for API response 429: 1. API query is full and can not accept new [videos/create-frames](#request-headers) requests. Size of query defined by [`maxJobs` optional parameter](#request-body). ```json { "error": "Account <email> is busy executing <maxJobs> tasks." "All configured accounts are running at maximum capacity." } ``` 2. The API received an HTTP response status 429 from PixVerse. Please refer to your [subscription](https://app.pixverse.ai/subscribe) plan for the maximum allowed tasks in the queue. ```json { "error": "Reached the limit for concurrent generations." } ``` **596** **596 Pending mod message** The account has a pending error, and the API does not use it until you add it again with [POST accounts/email](/docs/api-pixverse-v2/post-pixverse-accounts-email). You receive an email when this happens. There are three causes. PixVerse could not sign the account in, most often because its password was changed. Add the account again with the current password. ```json { "error": "Your PixVerse account has pending error. Please address this issue at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email before making any new API calls.", "code": 596 } ``` Or PixVerse suspended the account. PixVerse suspends accounts that break its content rules and does not say which generation caused it. The first response carries PixVerse's own details in `account_moderation`, and later calls return the same `error`. Add the account again after `reinstatement_at`. To ask PixVerse to lift the suspension earlier, write to the `support_email` it gives. ```json { "error": "PixVerse suspended account example@gmail.com for 30 days, from 2026-10-16 09:26 UTC until 2026-11-15 09:26 UTC. PixVerse suspends accounts that break its content rules and does not say which generation caused it. Add the account again at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email after 2026-11-15 09:26 UTC. To ask PixVerse to lift it earlier, write to support@pixverse.ai.", "code": 596, "account_moderation": { "ban_level": "suspend_30d", "action": "temporary_suspend", "duration_days": 30, "suspended_at": "2026-10-16 09:26:25 (UTC)", "reinstatement_at": "2026-11-15 09:26:25 (UTC)", "support_email": "support@pixverse.ai" } } ``` Or PixVerse banned the account for violating its community guidelines. A ban is permanent unless PixVerse accepts an appeal, and the `error` quotes PixVerse's own message, which says how to appeal. Remove the account with [DELETE accounts/email](/docs/api-pixverse-v2/del-pixverse-accounts-email), or add it again only if PixVerse lifts the ban. ```json { "error": "PixVerse banned account example@gmail.com for violating its community guidelines (400024). A ban is permanent unless PixVerse accepts an appeal. PixVerse says: \"Your account has been banned for violating community guidelines. If you wish to appeal, please contact us via ...\" Remove it with DELETE /v2/pixverse/accounts/example@gmail.com, or add it again (https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email) only if PixVerse lifts the ban.", "code": 596 } ``` If every account you have is in this state, a request without `email` returns 596 as well. ##### Model The new video's `video_id`: poll it with [GET videos/`video_id`](/docs/api-pixverse-v2/get-pixverse-videos-video_id) until it completes. <details markdown="block" class="model-details"> <summary>The new video job, field by field</summary> ```typescript { // TypeScript, all fields are optional video_id: string error: string } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST "https://api.useapi.net/v2/pixverse/videos/create-frames" \ -d '{"prompt": "…", "first_frame_path": "…", "last_frame_path": "…"}' ``` **JavaScript** ``` javascript const prompt = "text prompt"; const first_frame_path = "provide path of uploaded first image via POST /files"; const last_frame_path = "provide path of uploaded last image via POST /files"; const apiUrl = `https://api.useapi.net/v2/pixverse/videos/create-frames`; const token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ prompt, first_frame_path, last_frame_path }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests prompt = "text prompt" first_frame_path = "provide path of uploaded first image via POST /files" last_frame_path = "provide path of uploaded last image via POST /files" apiUrl = f"https://api.useapi.net/v2/pixverse/videos/create-frames" token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } body = { "prompt": f"{prompt}", "first_frame_path": f"{first_frame_path}", "last_frame_path": f"{last_frame_path}" } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-videos-create-fusion === Document URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-videos-create-fusion --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/create-fusion description: "Generate a video from reference images, videos and audio via POST videos/create-fusion in the useapi.net PixVerse API v2 — omni Reference mode with @image1 / @video1 / @audio1 prompt tags." parent: PixVerse API nav_order: 890 --- ## Create video using image fusion May 16, 2025 (November 16, 2026) --- Upload multiple reference frames and describe the content you want to create. Also known as **Reference mode** or **video-reference**. **Supported models** (see [Model Capabilities](/docs/api-pixverse-v2/model-capabilities) for max images per model): - Native PixVerse: `v5` (up to 3), `v5.6` (up to 7), `pixverse-c1` (up to 7) - Third-party: `seedance-2.5` and `seedance-2.5-draft` (up to 30 images + 10 ref videos + 10 ref audios, 50 references in total), `seedance-2.5-flash` (up to 10 images + 5 ref videos + 5 ref audios, 20 in total), `seedance-2.0`, `seedance-2.0-fast`, `seedance-2.0-mini` (each up to 9 images + 3 ref videos + 3 ref audios), `kling-4.0` (up to 10 images + 5 ref videos), `kling-o3` (up to 7), `minimax-h3`, `minimax-h3-max` (each up to 9 images), `gemini-omni-flash` (up to 5 images + 3 ref videos), `wan-3.0` (up to 10 images + 5 ref videos + 5 ref audios) All models use `@image1`…`@imageN` in the prompt, mapped positionally to `frame_1_path`…`frame_N_path`. `v5` also accepts the legacy `@pic1`/`@pic2`/`@pic3` synonyms. The Seedance models additionally accept **reference videos** via `video_1_path`…`video_N_path` (referenced as `@video1`…`@videoN`) and **reference audios** via `audio_1_path`…`audio_N_path` (referenced as `@audio1`…`@audioN`). This is PixVerse's omni mode — use reference videos to drive motion, camera moves, or rhythm, and reference audios to drive speech or sound onto your character image. `seedance-2.5` and `seedance-2.5-draft` take up to 10 of each, `seedance-2.5-flash` up to 5, the `seedance-2.0` family up to 3. `wan-3.0` takes up to 5 reference videos and 5 reference audios, and `kling-4.0` up to 5 reference videos. `gemini-omni-flash` also accepts up to 3 reference videos, but no reference audios — it is built for editing an existing clip, for example replacing the person in `@video1` with `@image1`. To upload prompt images and videos use [POST /files](/docs/api-pixverse-v2/post-pixverse-files). > **https://api.useapi.net/v2/pixverse/videos/create-fusion** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "email": "Optional PixVerse API account email", "model": "pixverse-c1", "prompt": "A dog @image1 and a cat @image2 traveling together in the car @image3", "frame_1_path": "upload/eb20c63d-2a1a-5be6-a562-d3578a2831e3.png", "frame_2_path": "upload/7b45d27f-301c-4d18-a2a1-f8bc3672e6a9.png", "frame_3_path": "upload/f8bc3672e6a9-301c-4d18-a2a1-7b45d27f.png", "duration": 8, "quality": "720p", "aspect_ratio": "16:9", "audio": true, "seed": 654321, "replyUrl": "Place your call back URL here", "replyRef": "Place your reference here", "off_peak_mode": true } ``` - `email` is optional, if not specified API will randomly select account from available [accounts](/docs/api-pixverse-v2/get-pixverse-accounts). - `model` is optional. **Default: `v5`** — omitting `model` gives you v5's 3-image cap and its legacy `@pic1`/`@pic2`/`@pic3` handling, not a newer model. Pass `model` explicitly for anything else. Supported values: `v5`, `v5.6`, `pixverse-c1`, `seedance-2.5`, `seedance-2.5-flash`, `seedance-2.5-draft`, `seedance-2.0`, `seedance-2.0-fast`, `seedance-2.0-mini`, `kling-4.0`, `kling-o3`, `minimax-h3`, `minimax-h3-max`, `gemini-omni-flash`, `wan-3.0`. - `prompt` is **required**, describe your video. Maximum length 5,000 characters, 20,000 for `wan-3.0`, 15,000 for `seedance-2.5`, `seedance-2.5-flash` and `seedance-2.5-draft`, 7,000 for `minimax-h3` and `minimax-h3-max`, 3,800 for `gemini-omni-flash`, and 2,500 for `kling-4.0` and `kling-o3`. Use `@image1`, `@image2`, … `@imageN` in the prompt to reference `frame_1_path`…`frame_N_path` by index. `v5` also accepts the legacy `@pic1`/`@pic2`/`@pic3` synonyms for backward compatibility. - `frame_1_path` is **required**, provide the path of uploaded image via [POST /files](/docs/api-pixverse-v2/post-pixverse-files). On a model that takes reference videos, a request with `video_1_path` and no image is accepted too. - `frame_2_path` through `frame_30_path` are optional. Max accepted depends on the model: * `v5.6`, `pixverse-c1` — up to **7** (`frame_1_path`…`frame_7_path`) * `seedance-2.5`, `seedance-2.5-draft` — up to **30** * `seedance-2.5-flash` — up to **10** * `seedance-2.0`, `seedance-2.0-fast`, `seedance-2.0-mini` — up to **9** * `kling-4.0` — up to **10** images and **5** reference videos * `kling-o3` — up to **7** * `minimax-h3` — up to **9**. Costs 10 extra credits per image above 5. * `minimax-h3-max` — up to **9**. Costs 20 extra credits per image above 2. * `wan-3.0` — up to **10** images, **5** reference videos and **5** reference audios. References cost nothing extra, and fusion is billed at the same per-second rate as text-to-video. * `gemini-omni-flash` — up to **5** * `v5` — up to **3** (`frame_1_path`, `frame_2_path`, `frame_3_path`) Frames must be provided sequentially — `frame_3_path` requires `frame_2_path`, etc. - `video_1_path`…`video_10_path` are optional and supported by the Seedance models, `wan-3.0`, `kling-4.0` and `gemini-omni-flash` — up to 10 for `seedance-2.5` and `seedance-2.5-draft`, up to 5 for `seedance-2.5-flash`, `wan-3.0` and `kling-4.0`, and up to 3 for the `seedance-2.0` family and `gemini-omni-flash`. Provide the path of an uploaded video via [POST /files](/docs/api-pixverse-v2/post-pixverse-files). Reference them in the prompt as `@video1`…`@videoN`. Must be sequential — `video_2_path` requires `video_1_path`. **Reference video limits** — every video is **≤ 50 MB**, **24–60 fps**, max dimensions **6000 × 6000 px**. Count and duration differ by model: * `seedance-2.5`, `seedance-2.5-draft` — up to **10** videos, each **1.8–30.2 sec**, summed **≤ 30.2 sec** * `seedance-2.5-flash` — up to **5** videos, each **4–30 sec**, summed **≤ 30 sec**, up to 200 MB each * `seedance-2.0` family — up to **3** videos, each **2–15 sec**, summed **≤ 15 sec** * `wan-3.0` — up to **5** videos, each **2–15 sec**, summed **≤ 15 sec** * `gemini-omni-flash` — up to **3** videos, each **2–15 sec**, summed **≤ 15 sec** * `kling-4.0` — up to **5** videos, each **3–30 sec**, summed **≤ 30 sec**. With a reference video PixVerse bills the longer of (reference length + output length) and twice the output length. - `audio_1_path`…`audio_10_path` are optional and supported by the Seedance models and `wan-3.0` — up to 10 for `seedance-2.5` and `seedance-2.5-draft`, up to 5 for `seedance-2.5-flash` and `wan-3.0`, and up to 3 for the `seedance-2.0` family. Provide the path of an uploaded audio file via [POST /files](/docs/api-pixverse-v2/post-pixverse-files). Reference them in the prompt as `@audio1`…`@audioN`. Must be sequential — `audio_2_path` requires `audio_1_path`. Use reference audios to drive speech or sound (for example, lip-synced dialogue) onto your character. **Reference audio limits** — every audio file is **≤ 15 MB**. Count and duration differ by model: * `seedance-2.5`, `seedance-2.5-draft` — up to **10** audios, each **1.8–30.2 sec**, summed **≤ 30.2 sec** * `seedance-2.5-flash` — up to **5** audios, each **2–30 sec**, summed **≤ 30 sec** * `seedance-2.0` family — up to **3** audios, each **2–15 sec**, summed **≤ 15 sec** * `wan-3.0` — up to **5** audios, each **2–15 sec**, summed **≤ 15 sec**. PixVerse states a 1-second floor for audio, we enforce 2 because the same rule covers reference video. `seedance-2.5` and `seedance-2.5-draft` additionally cap the combined number of references — images plus videos plus audios — at **50**, `seedance-2.5-flash` at **20**. `seedance-2.5-flash` also needs each image to be 300–6000 px on each side, with a width-to-height ratio between 0.4 and 2.5. The API validates these durations per model — the per-model figures listed above, not one global rule — before submitting. Video size, fps, and dimensions are enforced by PixVerse upstream. - `duration` and `quality` are optional **only when `model` is omitted**, in which case the request falls back to `v5` with `duration: 5` and `quality: 540p`. **Naming any model — native or third-party — makes both required**, and omitting either returns `400 duration is required for model <name>`. Accepted values depend on the model — see [Model Capabilities](/docs/api-pixverse-v2/model-capabilities). - `aspect_ratio` is optional, default `16:9`. See [Model Capabilities](/docs/api-pixverse-v2/model-capabilities) for per-model supported values. - `audio` is optional, for the models with an audio toggle: `v5.6`, `pixverse-c1`, `seedance-2.0`, `seedance-2.0-fast`, `seedance-2.0-mini`, `kling-o3` and `wan-3.0` (see [Model Capabilities](/docs/api-pixverse-v2/model-capabilities#audio)). The Seedance 2.5 models, `kling-4.0`, `minimax-h3`, `minimax-h3-max` and `gemini-omni-flash` always generate native audio and reject the parameter, and `v5` has no audio. Supported values: `true` (default), `false`. An omitted field is sent to PixVerse as `audio: 1` (on fusion this includes `v5.6`, unlike [POST videos/create](/docs/api-pixverse-v2/post-pixverse-videos-create-v4)), so pass `false` for a silent video. On `kling-o3` audio adds 40% to the cost at 720p and 1080p. - `seed` is optional, and only for the native PixVerse models (`v5`, `v5.6`, `pixverse-c1`) — every third-party model rejects it. Valid range 1…2147483647. - `off_peak_mode` is optional. Set to `true` to generate videos during low-demand periods at a reduced credit cost. Only supported for the native PixVerse models accepted by this endpoint (`v5`, `v5.6`, `pixverse-c1`) — third-party models reject this flag. Discount varies by subscription plan: **Pro** 30% off, **Premium** 50% off, **Ultra** unlimited free. Results are usually delivered within 24 hours. Off-Peak generations are not tracked by the scheduler, don't count toward concurrent-job limits, and the `replyUrl` webhook is not called — use [GET videos](/docs/api-pixverse-v2/get-pixverse-videos) to retrieve results. Supported values: `false` (default), `true`. - `relax_mode` is optional, for third-party models only (PixVerse's own models reject it). PixVerse discounts third-party video per model and plan, and the discount applies unless you send `relax_mode: false`, which pays the full price. `relax_mode: true` costs the same as leaving it out, and PixVerse records the video as made in its Relax Mode. If PixVerse refuses Relax Mode for that model on the account's plan, `relax_mode: true` returns `412` and nothing is charged. As of November 2026: | Plan | Discount | |---|---| | Ultra, Team Ultra | `minimax-h3` and `wan-3.0` free, `seedance-2.0-fast` and `seedance-2.0-mini` 90% off, `kling-4.0` 80% off, `gemini-omni-flash` 70% off, Veo 3.1 60% off, `flux-3.0` and `seedance-2.0` 50% off, `seedance-2.5` and `minimax-h3-max` 45% off, `kling-o3`, `grok-imagine-1.5` and `happyhorse-1.0` 40% off, `kling-v3`, `grok-imagine`, `seedance-2.5-flash` and `seedance-2.5-draft` 20% off | | Premium | `minimax-h3` and `wan-3.0` free, `seedance-2.0-fast` and `seedance-2.0-mini` 30% off | | Pro | `seedance-2.0-fast` and `seedance-2.0-mini` 10% off | - `replyUrl` is optional. This is the preferred and most optimal way to receive results quickly — the API polls every 10 seconds and will call the provided `replyUrl` once the PixVerse video is completed or failed. Maximum length 1024 characters. We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality. Callback body has the same JSON shape as [GET /videos/`video_id`](/docs/api-pixverse-v2/get-pixverse-videos-video_id) response. - `replyRef` is optional, place here your reference id which will be stored and returned along with this PixVerse video response / result. Maximum length 1024 characters. - `maxJobs` is optional, if not specified value from selected [accounts/email](/docs/api-pixverse-v2/get-pixverse-accounts-email) will be used. Valid range: 1…8 It should not exceed the number of concurrent generations supported by your account [subscription](https://app.pixverse.ai/subscribe) plan. ##### Responses **200** **200 OK** Use the returned `video_id` to retrieve video status and results using [GET /videos](/docs/api-pixverse-v2/get-pixverse-videos). Locate the video in the response array and check if the field `video_status_final` is `true` or `video_status_name` is `COMPLETED`. The field `url` will contain the generated video link. If you specify the optional parameter [`replyUrl`](#request-body), the API will call the provided `replyUrl` with video progress updates until the video is complete or fails. ```json { "video_id": "user:<userid>-pixverse:<email>-video:<number>" } ``` **400** **400 Bad Request** ```json { "error": "<Error message>" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized" } ``` **412** **412 Insufficient credits** Insufficient credits. All Credits have been used up. Please upgrade your membership or purchase credits. ```json { "error": "All Credits have been used up. Please upgrade your membership or purchase credits." } ``` **422** **422 Unprocessable Content** Moderated message. ```json { "error": "Your prompt has triggered our AI moderator, please re-enter your prompt" } ``` **429** **429 Too Many Requests** Wait in a loop for **at least** 10..30 seconds and retry again. There are two possible cases for API response 429: 1. API query is full and can not accept new [videos/create-fusion](#request-headers) requests. Size of query defined by [`maxJobs` optional parameter](#request-body). ```json { "error": "Account <email> is busy executing <maxJobs> tasks." "All configured accounts are running at maximum capacity." } ``` 2. The API received an HTTP response status 429 from PixVerse. Please refer to your [subscription](https://app.pixverse.ai/subscribe) plan for the maximum allowed tasks in the queue. ```json { "error": "Reached the limit for concurrent generations." } ``` **596** **596 Pending mod message** The account has a pending error, and the API does not use it until you add it again with [POST accounts/email](/docs/api-pixverse-v2/post-pixverse-accounts-email). You receive an email when this happens. There are three causes. PixVerse could not sign the account in, most often because its password was changed. Add the account again with the current password. ```json { "error": "Your PixVerse account has pending error. Please address this issue at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email before making any new API calls.", "code": 596 } ``` Or PixVerse suspended the account. PixVerse suspends accounts that break its content rules and does not say which generation caused it. The first response carries PixVerse's own details in `account_moderation`, and later calls return the same `error`. Add the account again after `reinstatement_at`. To ask PixVerse to lift the suspension earlier, write to the `support_email` it gives. ```json { "error": "PixVerse suspended account example@gmail.com for 30 days, from 2026-10-16 09:26 UTC until 2026-11-15 09:26 UTC. PixVerse suspends accounts that break its content rules and does not say which generation caused it. Add the account again at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email after 2026-11-15 09:26 UTC. To ask PixVerse to lift it earlier, write to support@pixverse.ai.", "code": 596, "account_moderation": { "ban_level": "suspend_30d", "action": "temporary_suspend", "duration_days": 30, "suspended_at": "2026-10-16 09:26:25 (UTC)", "reinstatement_at": "2026-11-15 09:26:25 (UTC)", "support_email": "support@pixverse.ai" } } ``` Or PixVerse banned the account for violating its community guidelines. A ban is permanent unless PixVerse accepts an appeal, and the `error` quotes PixVerse's own message, which says how to appeal. Remove the account with [DELETE accounts/email](/docs/api-pixverse-v2/del-pixverse-accounts-email), or add it again only if PixVerse lifts the ban. ```json { "error": "PixVerse banned account example@gmail.com for violating its community guidelines (400024). A ban is permanent unless PixVerse accepts an appeal. PixVerse says: \"Your account has been banned for violating community guidelines. If you wish to appeal, please contact us via ...\" Remove it with DELETE /v2/pixverse/accounts/example@gmail.com, or add it again (https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email) only if PixVerse lifts the ban.", "code": 596 } ``` If every account you have is in this state, a request without `email` returns 596 as well. ##### Model The new video's `video_id`: poll it with [GET videos/`video_id`](/docs/api-pixverse-v2/get-pixverse-videos-video_id) until it completes. <details markdown="block" class="model-details"> <summary>The new video job, field by field</summary> ```typescript { // TypeScript, all fields are optional video_id: string error: string } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST "https://api.useapi.net/v2/pixverse/videos/create-fusion" \ -d '{"prompt": "A dog @image1 and a cat @image2 traveling together", "frame_1_path": "…", "frame_2_path": "…"}' ``` **JavaScript** ``` javascript const prompt = "A dog @image1 and a cat @image2 traveling together"; const frame_1_path = "provide path of uploaded first image via POST /files"; const frame_2_path = "provide path of uploaded last image via POST /files"; const apiUrl = `https://api.useapi.net/v2/pixverse/videos/create-fusion`; const token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ prompt, frame_1_path, frame_2_path }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests prompt = "A dog @image1 and a cat @image2 traveling together" frame_1_path = "provide path of uploaded first image via POST /files" frame_2_path = "provide path of uploaded last image via POST /files" apiUrl = f"https://api.useapi.net/v2/pixverse/videos/create-fusion" token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } body = { "prompt": f"{prompt}", "frame_1_path": f"{frame_1_path}", "frame_2_path": f"{frame_2_path}" } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-videos-create-transition === Document URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-videos-create-transition --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/create-transition description: "Create a multi-frame transition video with up to 7 frames and custom inter-frame durations via POST videos/create-transition in the useapi.net PixVerse API v2." parent: PixVerse API nav_order: 890 --- ## Create transition video August 29, 2025 (November 16, 2026) --- This endpoint creates multi-frame transition videos with up to 7 frames and customizable transition durations between frames. To upload frame images use [POST files](/docs/api-pixverse-v2/post-pixverse-files). > **https://api.useapi.net/v2/pixverse/videos/create-transition** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "email": "Optional PixVerse API account email", "quality": "540p", "seed": 123456789, "frame_1_path": "upload/scene1.jpg", "frame_2_path": "upload/scene2.jpg", "frame_3_path": "upload/scene3.jpg", "duration_1_to_2": "3", "duration_2_to_3": "2", "prompt_1_to_2": "Smooth fade between scenes", "prompt_2_to_3": "Quick transition", "lip_sync_tts_prompt": "Optional TTS narration", "lip_sync_tts_speaker_id": "speaker_001", "auto_sound": true, "sound_effect_prompt": "Ambient background music", "off_peak_mode": false, "maxJobs": 1, "replyUrl": "Place your call back URL here", "replyRef": "Place your reference id here" } ``` - `email` is optional, if not specified API will randomly select account from available [accounts](/docs/api-pixverse-v2/get-pixverse-accounts). - `model` is optional. Model availability depends on frame count: - **2-frame mode** (frame_1 + frame_2 only): Supports `v5.6` (default), `v5.5`, and `v5`. - v5.5/v5.6: Use `audio` parameter for sound. - v5: Use `lip_sync_tts_prompt` and `sound_effect_prompt` for audio. - **3+ frame mode** (3-7 frames): Only `v5` supported (default). Use `lip_sync_tts_prompt` and `sound_effect_prompt` for audio. Using incompatible parameters for the model returns error 400. See [Model Capabilities](/docs/api-pixverse-v2/model-capabilities) for feature differences. - `quality` is optional. Video quality. Supported values: `1080p`, `720p`, `540p` (default), `360p`. - `seed` is optional. Valid range 1…2147483647. - `frame_1_path` is **required**, provide path of uploaded image via [POST files](/docs/api-pixverse-v2/post-pixverse-files). - `frame_2_path` is **required**, provide path of uploaded image via [POST files](/docs/api-pixverse-v2/post-pixverse-files). - `frame_3_path` is optional, provide path of uploaded image via [POST files](/docs/api-pixverse-v2/post-pixverse-files). - `frame_4_path` is optional, provide path of uploaded image via [POST files](/docs/api-pixverse-v2/post-pixverse-files). - `frame_5_path` is optional, provide path of uploaded image via [POST files](/docs/api-pixverse-v2/post-pixverse-files). - `frame_6_path` is optional, provide path of uploaded image via [POST files](/docs/api-pixverse-v2/post-pixverse-files). - `frame_7_path` is optional, provide path of uploaded image via [POST files](/docs/api-pixverse-v2/post-pixverse-files). - `duration_1_to_2` is optional. Transition duration from frame 1 to frame 2 in seconds. Supported values: `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`. - `duration_2_to_3` is optional. Transition duration from frame 2 to frame 3 in seconds. Supported values: `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`. - `duration_3_to_4` is optional. Transition duration from frame 3 to frame 4 in seconds. Supported values: `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`. - `duration_4_to_5` is optional. Transition duration from frame 4 to frame 5 in seconds. Supported values: `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`. - `duration_5_to_6` is optional. Transition duration from frame 5 to frame 6 in seconds. Supported values: `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`. - `duration_6_to_7` is optional. Transition duration from frame 6 to frame 7 in seconds. Supported values: `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`. - `prompt_1_to_2` is optional, describe transition from frame 1 to frame 2. - `prompt_2_to_3` is optional, describe transition from frame 2 to frame 3. - `prompt_3_to_4` is optional, describe transition from frame 3 to frame 4. - `prompt_4_to_5` is optional, describe transition from frame 4 to frame 5. - `prompt_5_to_6` is optional, describe transition from frame 5 to frame 6. - `prompt_6_to_7` is optional, describe transition from frame 6 to frame 7. - `audio` is optional (**2-frame mode only**, v5.5/v5.6 only). Set to `true` to enable integrated native audio generation. v5.5/v5.6 generates voice, lip sync, and background music together with the video. With `v5` or with 3 or more frames, `true` returns `400`. See [Model Capabilities](/docs/api-pixverse-v2/model-capabilities). Supported values: `false` (default), `true`. An omitted field is sent to PixVerse as `audio: 0`, so the video is silent unless you pass `true`. - `preview_mode` is optional. Set to `true` for fast preview generation (lower quality, faster results). Preview videos can later be upscaled via [POST videos/upscale](/docs/api-pixverse-v2/post-pixverse-videos-upscale). Supported values: `false` (default), `true`. - `auto_sound` is optional (**v5 model only**). Set to `true` to generate videos with sound. Supported values: not specified (default), `false`, `true`. - `sound_effect_prompt` is optional (**v5 model only**), describe the sound eg "epic adventure music". Maximum length 140 characters. - `lip_sync_tts_prompt` is optional (**v5 model only**), enter character lines. Maximum length 140 characters. - `lip_sync_tts_speaker_id` is optional (**v5 model only**), specify desired lipsync voice see [GET videos/voices](/docs/api-pixverse-v2/get-pixverse-videos-voices). - `off_peak_mode` is optional. Set to `true` to generate videos during low-demand periods at a reduced credit cost. Discount varies by subscription plan: **Pro** 30% off, **Premium** 50% off, **Ultra** unlimited free. Results are usually delivered within 24 hours. Off-Peak generations are not tracked by the scheduler, don't count toward concurrent-job limits, and the `replyUrl` webhook is not called — use [GET videos](/docs/api-pixverse-v2/get-pixverse-videos) to retrieve results. Supported values: `false` (default), `true`. - `replyUrl` is optional, place here your callback URL. This is the preferred and most optimal way to receive results quickly — the API polls every 10 seconds and will call the provided `replyUrl` once the PixVerse video is completed or failed. We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality. Maximum length 1024 characters. Callback body has the same JSON shape as [GET /videos/`video_id`](/docs/api-pixverse-v2/get-pixverse-videos-video_id) response. - `replyRef` is optional, place here your reference id which will be stored and returned along with this PixVerse video response / result. Maximum length 1024 characters. - `maxJobs` is optional, if not specified value from selected [accounts/email](/docs/api-pixverse-v2/get-pixverse-accounts-email) will be used. It should not exceed the number of concurrent generations supported by your account [subscription](https://app.pixverse.ai/subscribe) plan. Valid range: 1…8 ##### Responses **200** **200 OK** Use the returned `video_id` to retrieve video status and results using [GET videos](/docs/api-pixverse-v2/get-pixverse-videos). Locate the video in the response array and check if the field `video_status_final` is `true` or `video_status_name` is `COMPLETED`. The field `url` will contain the generated video link. If you specify the optional parameter [`replyUrl`](#request-body), the API will call the provided `replyUrl` with video progress updates until the video is complete or fails. ```json { "video_id": "user:<userid>-pixverse:<email>-video:<number>" } ``` **400** **400 Bad Request** ```json { "error": "<Error message>" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized" } ``` **412** **412 Insufficient credits** Insufficient credits. All Credits have been used up. Please upgrade your membership or purchase credits. ```json { "error": "All Credits have been used up. Please upgrade your membership or purchase credits." } ``` **422** **422 Unprocessable Content** Moderated message. ```json { "error": "Your prompt has triggered our AI moderator, please re-enter your prompt" } ``` **429** **429 Too Many Requests** Wait in a loop for **at least** 10..30 seconds and retry again. There are two possible cases for API response 429: 1. API query is full and can not accept new [videos/create-transition](#request-headers) requests. Size of query defined by [`maxJobs` optional parameter](#request-body). ```json { "error": "Account <email> is busy executing <maxJobs> tasks." "All configured accounts are running at maximum capacity." } ``` 2. The API received an HTTP response status 429 from PixVerse. Please refer to your [subscription](https://app.pixverse.ai/subscribe) plan for the maximum allowed tasks in the queue. ```json { "error": "Reached the limit for concurrent generations." } ``` **596** **596 Pending mod message** The account has a pending error, and the API does not use it until you add it again with [POST accounts/email](/docs/api-pixverse-v2/post-pixverse-accounts-email). You receive an email when this happens. There are three causes. PixVerse could not sign the account in, most often because its password was changed. Add the account again with the current password. ```json { "error": "Your PixVerse account has pending error. Please address this issue at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email before making any new API calls.", "code": 596 } ``` Or PixVerse suspended the account. PixVerse suspends accounts that break its content rules and does not say which generation caused it. The first response carries PixVerse's own details in `account_moderation`, and later calls return the same `error`. Add the account again after `reinstatement_at`. To ask PixVerse to lift the suspension earlier, write to the `support_email` it gives. ```json { "error": "PixVerse suspended account example@gmail.com for 30 days, from 2026-10-16 09:26 UTC until 2026-11-15 09:26 UTC. PixVerse suspends accounts that break its content rules and does not say which generation caused it. Add the account again at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email after 2026-11-15 09:26 UTC. To ask PixVerse to lift it earlier, write to support@pixverse.ai.", "code": 596, "account_moderation": { "ban_level": "suspend_30d", "action": "temporary_suspend", "duration_days": 30, "suspended_at": "2026-10-16 09:26:25 (UTC)", "reinstatement_at": "2026-11-15 09:26:25 (UTC)", "support_email": "support@pixverse.ai" } } ``` Or PixVerse banned the account for violating its community guidelines. A ban is permanent unless PixVerse accepts an appeal, and the `error` quotes PixVerse's own message, which says how to appeal. Remove the account with [DELETE accounts/email](/docs/api-pixverse-v2/del-pixverse-accounts-email), or add it again only if PixVerse lifts the ban. ```json { "error": "PixVerse banned account example@gmail.com for violating its community guidelines (400024). A ban is permanent unless PixVerse accepts an appeal. PixVerse says: \"Your account has been banned for violating community guidelines. If you wish to appeal, please contact us via ...\" Remove it with DELETE /v2/pixverse/accounts/example@gmail.com, or add it again (https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email) only if PixVerse lifts the ban.", "code": 596 } ``` If every account you have is in this state, a request without `email` returns 596 as well. ##### Model The new video's `video_id`: poll it with [GET videos/`video_id`](/docs/api-pixverse-v2/get-pixverse-videos-video_id) until it completes. <details markdown="block" class="model-details"> <summary>The new video job, field by field</summary> ```typescript { // TypeScript, all fields are optional video_id: string error: string } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST "https://api.useapi.net/v2/pixverse/videos/create-transition" \ -d '{"frame_1_path": "…", "frame_2_path": "…"}' ``` **JavaScript** ``` javascript const frame_1_path = "provide path of uploaded first image via POST /files"; const frame_2_path = "provide path of uploaded second image via POST /files"; const apiUrl = `https://api.useapi.net/v2/pixverse/videos/create-transition`; const token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ frame_1_path, frame_2_path }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests frame_1_path = "provide path of uploaded first image via POST /files" frame_2_path = "provide path of uploaded second image via POST /files" apiUrl = f"https://api.useapi.net/v2/pixverse/videos/create-transition" token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } body = { "frame_1_path": f"{frame_1_path}", "frame_2_path": f"{frame_2_path}" } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-videos-create-v4 === Document URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-videos-create-v4 --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/create description: "Generate text-to-video and image-to-video via POST videos/create in the useapi.net PixVerse API v2 — PixVerse V6, Seedance, Veo 3.1, MiniMax H3, and more." parent: PixVerse API nav_order: 850 --- ## Create video March 24, 2025 (November 16, 2026) --- This endpoint supports both **text-to-video (t2v)** and **image-to-video (i2v)** modes. **Supported models** (see [Model Capabilities](/docs/api-pixverse-v2/model-capabilities) for per-model constraints): - Native PixVerse: `v6` (default), `v5.6`, `v5.5`, `v5`, `v5-fast`, `pixverse-c1` - Third-party: `seedance-2.5`, `seedance-2.5-flash`, `seedance-2.5-draft`, `seedance-2.0`, `seedance-2.0-fast`, `seedance-2.0-mini`, `kling-4.0`, `kling-o3`, `kling-v3`, `grok-imagine`, `grok-imagine-1.5`, `veo-3.1-lite`, `veo-3.1-standard`, `veo-3.1-fast`, `happyhorse-1.0`, `minimax-h3`, `minimax-h3-max`, `gemini-omni-flash`, `flux-3.0`, `wan-3.0` `seedance-2.5-draft` makes a cheap 480p draft of a Seedance 2.5 video. When you like it, [POST videos/create-final](/docs/api-pixverse-v2/post-pixverse-videos-create-final) renders the same video at 1080p or 4K, for up to 14 days. Sora 2 is no longer available: OpenAI shut it down on September 24, 2026. For dedicated image generation, see [POST images/create](/docs/api-pixverse-v2/post-pixverse-images-create). To upload prompt image use [POST files](/docs/api-pixverse-v2/post-pixverse-files). > **https://api.useapi.net/v2/pixverse/videos/create** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body **Text-to-video** ```json { "model": "v6", "prompt": "A red panda eating bamboo in a misty forest", "duration": 5, "quality": "720p", "aspect_ratio": "16:9" } ``` **Image-to-video** ```json { "model": "v6", "prompt": "The subject turns and smiles at camera", "first_frame_path": "upload/eb20c63d-…png", "duration": 5, "quality": "720p" } ``` **Template (1–2 inputs)** ```json { "template_id": 326733946317888, "first_frame_path": "upload/a-…jpeg", "last_frame_path": "upload/b-…jpeg" } ``` **Template (3–5 inputs)** ```json { "template_id": 384628677917440, "prompt": "A warm family reunion in a sunlit backyard.", "frame_1_path": "upload/a-…jpeg", "frame_2_path": "upload/b-…jpeg", "frame_3_path": "upload/c-…jpeg", "frame_4_path": "upload/d-…jpeg", "frame_5_path": "upload/e-…jpeg" } ``` ###### Parameters - `email` is optional, if not specified API will randomly select account from available [accounts](/docs/api-pixverse-v2/get-pixverse-accounts). - `model` is optional. Default: `v6`. Supported values — native PixVerse: `v6`, `v5.6`, `v5.5`, `v5`, `v5-fast`, `pixverse-c1`. Third-party: `seedance-2.5`, `seedance-2.5-flash`, `seedance-2.5-draft`, `seedance-2.0`, `seedance-2.0-fast`, `seedance-2.0-mini`, `kling-4.0`, `kling-o3`, `kling-v3`, `grok-imagine`, `grok-imagine-1.5`, `veo-3.1-lite`, `veo-3.1-standard`, `veo-3.1-fast`, `happyhorse-1.0`, `minimax-h3`, `minimax-h3-max`, `gemini-omni-flash`, `flux-3.0`, `wan-3.0`. See [Model Capabilities](/docs/api-pixverse-v2/model-capabilities) for per-model quality, duration, and aspect-ratio constraints. `grok-imagine-1.5` is image-to-video only — it requires `first_frame_path` and rejects no-image (text-to-video) requests. **Ignored when `template_id` is set** — see [notes](#input-image-paths-and-templates). - `prompt` is optional, describe your video. Maximum length 5,000 characters, 20,000 for `wan-3.0`, 15,000 for `seedance-2.5`, `seedance-2.5-flash` and `seedance-2.5-draft`, 7,000 for `minimax-h3` and `minimax-h3-max`, 4,096 for `grok-imagine` and `grok-imagine-1.5`, 4,000 for `flux-3.0`, 3,800 for `gemini-omni-flash`, 3,500 for `veo-3.1-lite`, `veo-3.1-standard` and `veo-3.1-fast`, and 2,500 for `kling-4.0`, `kling-o3`, `kling-v3` and `happyhorse-1.0`. - `first_frame_path`, `last_frame_path`, `frame_1_path`, `frame_2_path`, `frame_3_path`, `frame_4_path`, `frame_5_path` are optional input image paths. Upload images via [POST /files](/docs/api-pixverse-v2/post-pixverse-files) first and use the returned `path` value. Two interchangeable forms exist for providing image paths and the count rules depend on `effect_type` — see [notes](#input-image-paths-and-templates) for full rules. - `template_id` is optional, effect template id from [GET videos/effects](/docs/api-pixverse-v2/get-pixverse-videos-effects). When set, the template controls model/duration/quality — see [notes](#input-image-paths-and-templates). - `duration` is optional for the native models `v6`, `v5.6`, `v5.5`, `v5` and `v5-fast`, where it defaults to `5`. `pixverse-c1` and every third-party model **require** it. Accepted values depend on the model — see [Model Capabilities](/docs/api-pixverse-v2/model-capabilities). **Ignored when `template_id` is set.** - `quality` is optional for the native models `v6`, `v5.6`, `v5.5`, `v5` and `v5-fast`. `pixverse-c1` and every third-party model **require** it. Accepted values depend on the model — see [Model Capabilities](/docs/api-pixverse-v2/model-capabilities). `kling-4.0` takes `720p` or `1080p` as the real output resolution. For `kling-o3` and `kling-v3`, `quality` selects an upstream tier rather than an output resolution — `720p` routes to Standard, `1080p` to Pro, and `2160p` to the 4K tier. PixVerse renders both Standard and Pro at 720p, so only `2160p` changes the resolution. **When `template_id` is set**, must be one of the template's `qualities` (see [GET videos/effects](/docs/api-pixverse-v2/get-pixverse-videos-effects)); defaults to the first entry if omitted. - `aspect_ratio` is optional. For t2v (no image) it defaults to `16:9`. **Not accepted for i2v** (derived from input image). See [Model Capabilities](/docs/api-pixverse-v2/model-capabilities) for per-model supported values. - `auto_sound` is optional. Set to `true` to generate videos with sound or `false` to explicitly remove the default effect sound. Supported values: not specified (default), `false`, `true`. - `sound_effect_prompt` is optional, describe the sound eg "the sound of waves hitting the shore". - `lip_sync_tts_prompt` is optional, enter character lines. Maximum length 140 characters. - `lip_sync_tts_speaker_id` is optional, specify desired lipsync voice see [GET videos/voices](/docs/api-pixverse-v2/get-pixverse-videos-voices). - `audio` is optional. Supported values: `false`, `true`. Both which values are accepted and what happens when you omit the field depend on the model: | Behavior | Models | What it means | |---|---|---| | Toggle | `v5.5`, `v5.6`, `v6`, `pixverse-c1`, `seedance-2.0`, `seedance-2.0-fast`, `seedance-2.0-mini`, `kling-o3`, `kling-v3`, `flux-3.0`, `wan-3.0` | `true` or `false` accepted, and enables integrated audio generation | | Always on | `veo-3.1-standard`, `veo-3.1-fast`, `happyhorse-1.0` | Audio generated automatically; setting `false` is rejected | | Not supported | `seedance-2.5`, `seedance-2.5-flash`, `seedance-2.5-draft`, `grok-imagine`, `grok-imagine-1.5`, `veo-3.1-lite`, `minimax-h3`, `minimax-h3-max`, `gemini-omni-flash`, `kling-4.0` | Passing any value is rejected | The Seedance 2.5 models, `minimax-h3`, `minimax-h3-max`, `gemini-omni-flash` and `kling-4.0` always generate native audio and accept no `audio` parameter. Omitting `audio` does **not** mean off for every model. On the combo models in the Toggle row above — `seedance-2.0`, `seedance-2.0-fast`, `seedance-2.0-mini`, `kling-o3`, `kling-v3`, `pixverse-c1`, `flux-3.0` and `wan-3.0` — an omitted field is sent upstream as `audio: 1`, so pass `false` explicitly if you want it off. That matters on `kling-o3` / `kling-v3`, where audio adds 40% to the cost at 720p and 1080p. `flux-3.0` and `wan-3.0` charge nothing extra for it. Only the legacy `v5.5` / `v5.6` / `v6` path treats an omitted field as off. - `multi_shot` is optional. **v6 only.** Set to `true` to enable multi-shot storytelling — the AI generates videos with multiple camera angles and scene cuts rather than a single continuous shot. Supported values: `false` (default), `true`. - `preview_mode` is optional. Only supported for native PixVerse models (`v5`, `v5.5`, `v5.6`, `v5-fast`, `v6`, `pixverse-c1`) — third-party models reject this flag. Set to `true` to generate a fast preview at lower quality at **20% off** credits. Use [POST videos/upscale](/docs/api-pixverse-v2/post-pixverse-videos-upscale) to upscale the preview to full quality. Supported values: `false` (default), `true`. - `seed` is optional. Only supported for native PixVerse models (`v5`, `v5.5`, `v5.6`, `v5-fast`, `v6`, `pixverse-c1`) — third-party models reject this flag. Valid range 1…2147483647. - `off_peak_mode` is optional. Set to `true` to generate videos during low-demand periods at a reduced credit cost. Only supported for native PixVerse models (`v5`, `v5.5`, `v5.6`, `v5-fast`, `v6`, `pixverse-c1`) — third-party models reject this flag. Discount varies by subscription plan: **Pro** 30% off, **Premium** 50% off, **Ultra** unlimited free. Results are usually delivered within 24 hours. Off-Peak generations are not tracked by the scheduler, don't count toward concurrent-job limits, and the `replyUrl` webhook is not called — use [GET videos](/docs/api-pixverse-v2/get-pixverse-videos) to retrieve results. Supported values: `false` (default), `true`. - `relax_mode` is optional, for third-party models only (PixVerse's own models reject it). PixVerse discounts third-party video per model and plan, and the discount applies unless you send `relax_mode: false`, which pays the full price. `relax_mode: true` costs the same as leaving it out, and PixVerse records the video as made in its Relax Mode. If PixVerse refuses Relax Mode for that model on the account's plan, `relax_mode: true` returns `412` and nothing is charged. As of November 2026: | Plan | Discount | |---|---| | Ultra, Team Ultra | `minimax-h3` and `wan-3.0` free, `seedance-2.0-fast` and `seedance-2.0-mini` 90% off, `kling-4.0` 80% off, `gemini-omni-flash` 70% off, Veo 3.1 60% off, `flux-3.0` and `seedance-2.0` 50% off, `seedance-2.5` and `minimax-h3-max` 45% off, `kling-o3`, `grok-imagine-1.5` and `happyhorse-1.0` 40% off, `kling-v3`, `grok-imagine`, `seedance-2.5-flash` and `seedance-2.5-draft` 20% off | | Premium | `minimax-h3` and `wan-3.0` free, `seedance-2.0-fast` and `seedance-2.0-mini` 30% off | | Pro | `seedance-2.0-fast` and `seedance-2.0-mini` 10% off | - `replyUrl` is optional, place here your callback URL. This is the preferred and most optimal way to receive results quickly — the API polls every 10 seconds and will call the provided `replyUrl` once the PixVerse video is completed or failed. We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality. Maximum length 1024 characters. Callback body has the same JSON shape as [GET /videos/`video_id`](/docs/api-pixverse-v2/get-pixverse-videos-video_id) response. - `replyRef` is optional, place here your reference id which will be stored and returned along with this PixVerse video response / result. Maximum length 1024 characters. - `maxJobs` is optional, if not specified value from selected [accounts/email](/docs/api-pixverse-v2/get-pixverse-accounts-email) will be used. It should not exceed the number of concurrent generations supported by your account [subscription](https://app.pixverse.ai/subscribe) plan. Valid range: 1…8 ###### Input image paths and templates | `effect_type` | Input count | Form to use | |---|---|---| | _(no `template_id`)_ | 0 or 1 | `first_frame_path` (or `frame_1_path`) — omit for text-to-video | | `"1"` | exactly 1 | `first_frame_path` (or `frame_1_path`) | | `"2"` | exactly 2 | `first_frame_path` + `last_frame_path` (or `frame_1_path` + `frame_2_path`) | | `"3"` | 2 to 3 | `frame_1_path` … up to `frame_3_path` | | `"4"` | 2 to 4 | `frame_1_path` … up to `frame_4_path` | | `"5"` | 2 to 5 | `frame_1_path` … up to `frame_5_path` | Never mix `first_frame_path`/`last_frame_path` with `frame_N_path`. In the numbered form, fill slots in order — no `frame_3_path` without `frame_2_path`. When `template_id` is set, the template controls `model`, `duration`, and `quality` — skip those parameters. Anything you pass for `model` or `duration` is ignored, and `quality` (if set) must be one the template allows. Image templates (`template_type: 2`) produce a 1-second still — the response carries `image_id` instead of `video_id`. ##### Responses **200** **200 OK** Use the returned `video_id` or `image_id` to retrieve video status and results using [GET videos](/docs/api-pixverse-v2/get-pixverse-videos). Locate the video in the response array and check if the field `video_status_final` is `true` or `video_status_name` is `COMPLETED`. The field `url` will contain the generated video link. If you specify the optional parameter [`replyUrl`](#request-body), the API will call the provided `replyUrl` with video progress updates until the video is complete or fails. ```json { "video_id": "user:<userid>-pixverse:<email>-video:<number>" } ``` **400** **400 Bad Request** ```json { "error": "<Error message>" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized" } ``` **412** **412 Insufficient credits** Insufficient credits. All Credits have been used up. Please upgrade your membership or purchase credits. ```json { "error": "All Credits have been used up. Please upgrade your membership or purchase credits." } ``` The same code answers `relax_mode: true` when PixVerse refuses Relax Mode for the model on the account's plan. Nothing is charged. Leave `relax_mode` out, or set it to `false`. ```json { "error": "relax_mode: true needs a PixVerse plan with Relax Mode for model <model>, and this account's plan does not have it (see the relax_mode table on https://useapi.net/docs/api-pixverse-v2/post-pixverse-videos-create-v4). Leave relax_mode out or set it to false to pay full credits. PixVerse: <message> (400017)" } ``` **422** **422 Unprocessable Content** Moderated message. ```json { "error": "Your prompt has triggered our AI moderator, please re-enter your prompt" } ``` **429** **429 Too Many Requests** Wait in a loop for **at least** 10..30 seconds and retry again. There are two possible cases for API response 429: 1. API query is full and can not accept new [videos/create](#request-headers) requests. Size of query defined by [`maxJobs` optional parameter](#request-body). ```json { "error": "Account <email> is busy executing <maxJobs> tasks." "All configured accounts are running at maximum capacity." } ``` 2. The API received an HTTP response status 429 from PixVerse. Please refer to your [subscription](https://app.pixverse.ai/subscribe) plan for the maximum allowed tasks in the queue. ```json { "error": "Reached the limit for concurrent generations." } ``` **596** **596 Pending mod message** The account has a pending error, and the API does not use it until you add it again with [POST accounts/email](/docs/api-pixverse-v2/post-pixverse-accounts-email). You receive an email when this happens. There are three causes. PixVerse could not sign the account in, most often because its password was changed. Add the account again with the current password. ```json { "error": "Your PixVerse account has pending error. Please address this issue at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email before making any new API calls.", "code": 596 } ``` Or PixVerse suspended the account. PixVerse suspends accounts that break its content rules and does not say which generation caused it. The first response carries PixVerse's own details in `account_moderation`, and later calls return the same `error`. Add the account again after `reinstatement_at`. To ask PixVerse to lift the suspension earlier, write to the `support_email` it gives. ```json { "error": "PixVerse suspended account example@gmail.com for 30 days, from 2026-10-16 09:26 UTC until 2026-11-15 09:26 UTC. PixVerse suspends accounts that break its content rules and does not say which generation caused it. Add the account again at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email after 2026-11-15 09:26 UTC. To ask PixVerse to lift it earlier, write to support@pixverse.ai.", "code": 596, "account_moderation": { "ban_level": "suspend_30d", "action": "temporary_suspend", "duration_days": 30, "suspended_at": "2026-10-16 09:26:25 (UTC)", "reinstatement_at": "2026-11-15 09:26:25 (UTC)", "support_email": "support@pixverse.ai" } } ``` Or PixVerse banned the account for violating its community guidelines. A ban is permanent unless PixVerse accepts an appeal, and the `error` quotes PixVerse's own message, which says how to appeal. Remove the account with [DELETE accounts/email](/docs/api-pixverse-v2/del-pixverse-accounts-email), or add it again only if PixVerse lifts the ban. ```json { "error": "PixVerse banned account example@gmail.com for violating its community guidelines (400024). A ban is permanent unless PixVerse accepts an appeal. PixVerse says: \"Your account has been banned for violating community guidelines. If you wish to appeal, please contact us via ...\" Remove it with DELETE /v2/pixverse/accounts/example@gmail.com, or add it again (https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email) only if PixVerse lifts the ban.", "code": 596 } ``` If every account you have is in this state, a request without `email` returns 596 as well. ##### Model The new video's `video_id` to poll with [GET videos/`video_id`](/docs/api-pixverse-v2/get-pixverse-videos-video_id), or an `image_id` when an image effect template is used. <details markdown="block" class="model-details"> <summary>The new video job, field by field</summary> ```typescript { // TypeScript, all fields are optional video_id: string image_id: string // When image template_id is used (template_type: 2) error: string } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST "https://api.useapi.net/v2/pixverse/videos/create" \ -d '{"prompt": "…"}' ``` **JavaScript** ``` javascript const prompt = "text prompt"; const apiUrl = `https://api.useapi.net/v2/pixverse/videos/create`; const token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ prompt }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests prompt = "text prompt" apiUrl = f"https://api.useapi.net/v2/pixverse/videos/create" token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } body = { "prompt": f"{prompt}" } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-videos-extend-v4 === Document URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-videos-extend-v4 --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/extend description: "Extend an existing PixVerse video with additional length via POST videos/extend in the useapi.net PixVerse API v2 — supports v6 (default) and grok-imagine." parent: PixVerse API nav_order: 870 --- ## Extend video March 31, 2025 (November 16, 2026) --- This endpoint supports `v6` and `grok-imagine`. Default: `v6`. * Extend a video generated by PixVerse, retrieve the `video_id` of the desired video using [GET /videos](/docs/api-pixverse-v2/get-pixverse-videos). * Upload the video using [POST /files](/docs/api-pixverse-v2/post-pixverse-files) and use `path` to specify the video you want to extend. > **https://api.useapi.net/v2/pixverse/videos/extend** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "email": "Optional PixVerse API account email", "prompt": "Optional text prompt", "video_id": "Optional video_id", "duration": 5, "quality": "720p", "seed": 654321, "replyUrl": "Place your call back URL here", "replyRef": "Place your reference id here", "maxJobs": 3 } ``` - `email` is optional, if not specified API will randomly select account from available [accounts](/docs/api-pixverse-v2/get-pixverse-accounts). - `model` is optional. Supported values: `v6` (default) and `grok-imagine`. - `prompt` is optional, describe your video. Maximum length 5,000 characters, and 4,096 for `grok-imagine`. - `video_id` is optional, retrieve the `video_id` of the desired video using [GET /videos](/docs/api-pixverse-v2/get-pixverse-videos). - `video_path` is optional, upload the video using [POST /files](/docs/api-pixverse-v2/post-pixverse-files) and use `path` to specify the video you want to extend. - `duration` is optional. Extend duration in seconds. Supported values: `1` through `15` for v6 (default `5`), `2` through `10` for grok-imagine (default `2`). - `quality` is optional. Video quality. Supported values for v6: `1080p`, `720p` (default), `540p`, `360p`. For grok-imagine: `720p`, `480p` (default). - `audio` is optional. **v6 only.** Set to `true` to enable integrated audio generation on the extended segment. Supported values: `false` (default), `true`. grok-imagine merges native audio automatically and does not accept this parameter. - `seed` is optional, v6 only. grok-imagine rejects it. Valid range 1…2147483647. - `off_peak_mode` is optional. Set to `true` to generate videos during low-demand periods at a reduced credit cost. On this endpoint only `v6` supports it, and `grok-imagine` answers `400` to `true` (PixVerse has no Off-Peak for third-party models). Discount varies by subscription plan: **Pro** 30% off, **Premium** 50% off, **Ultra** unlimited free. Results are usually delivered within 24 hours. Off-Peak generations are not tracked by the scheduler, don't count toward concurrent-job limits, and the `replyUrl` webhook is not called — use [GET videos](/docs/api-pixverse-v2/get-pixverse-videos) to retrieve results. Supported values: `false` (default), `true`. - `replyUrl` is optional. This is the preferred and most optimal way to receive results quickly — the API polls every 10 seconds and will call the provided `replyUrl` once the PixVerse video is completed or failed. Maximum length 1024 characters. We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality. Callback body has the same JSON shape as [GET /videos/`video_id`](/docs/api-pixverse-v2/get-pixverse-videos-video_id) response. - `replyRef` is optional, place here your reference id which will be stored and returned along with this PixVerse video response / result. Maximum length 1024 characters. - `maxJobs` is optional, if not specified value from selected [accounts/email](/docs/api-pixverse-v2/get-pixverse-accounts-email) will be used. Valid range: 1…8 It should not exceed the number of concurrent generations supported by your account [subscription](https://app.pixverse.ai/subscribe) plan. ##### Responses **200** **200 OK** Use the returned `video_id` to retrieve video status and results using [GET /videos](/docs/api-pixverse-v2/get-pixverse-videos). Locate the video in the response array and check if the field `video_status_final` is `true` or `video_status_name` is `COMPLETED`. The field `url` will contain the generated video link. If you specify the optional parameter [`replyUrl`](#request-body), the API will call the provided `replyUrl` with video progress updates until the video is complete or fails. ```json { "video_id": "user:<userid>-pixverse:<email>-video:<number>" } ``` **400** **400 Bad Request** ```json { "error": "<Error message>" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized" } ``` **412** **412 Insufficient credits** Insufficient credits. All Credits have been used up. Please upgrade your membership or purchase credits. ```json { "error": "All Credits have been used up. Please upgrade your membership or purchase credits." } ``` **422** **422 Unprocessable Content** Moderated message. ```json { "error": "Your prompt has triggered our AI moderator, please re-enter your prompt" } ``` **429** **429 Too Many Requests** Wait in a loop for **at least** 10..30 seconds and retry again. There are two possible cases for API response 429: 1. API query is full and can not accept new [videos/extend](#request-headers) requests. Size of query defined by [`maxJobs` optional parameter](#request-body). ```json { "error": "Account <email> is busy executing <maxJobs> tasks." "All configured accounts are running at maximum capacity." } ``` 2. The API received an HTTP response status 429 from PixVerse. Please refer to your [subscription](https://app.pixverse.ai/subscribe) plan for the maximum allowed tasks in the queue. ```json { "error": "Reached the limit for concurrent generations." } ``` **596** **596 Pending mod message** The account has a pending error, and the API does not use it until you add it again with [POST accounts/email](/docs/api-pixverse-v2/post-pixverse-accounts-email). You receive an email when this happens. There are three causes. PixVerse could not sign the account in, most often because its password was changed. Add the account again with the current password. ```json { "error": "Your PixVerse account has pending error. Please address this issue at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email before making any new API calls.", "code": 596 } ``` Or PixVerse suspended the account. PixVerse suspends accounts that break its content rules and does not say which generation caused it. The first response carries PixVerse's own details in `account_moderation`, and later calls return the same `error`. Add the account again after `reinstatement_at`. To ask PixVerse to lift the suspension earlier, write to the `support_email` it gives. ```json { "error": "PixVerse suspended account example@gmail.com for 30 days, from 2026-10-16 09:26 UTC until 2026-11-15 09:26 UTC. PixVerse suspends accounts that break its content rules and does not say which generation caused it. Add the account again at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email after 2026-11-15 09:26 UTC. To ask PixVerse to lift it earlier, write to support@pixverse.ai.", "code": 596, "account_moderation": { "ban_level": "suspend_30d", "action": "temporary_suspend", "duration_days": 30, "suspended_at": "2026-10-16 09:26:25 (UTC)", "reinstatement_at": "2026-11-15 09:26:25 (UTC)", "support_email": "support@pixverse.ai" } } ``` Or PixVerse banned the account for violating its community guidelines. A ban is permanent unless PixVerse accepts an appeal, and the `error` quotes PixVerse's own message, which says how to appeal. Remove the account with [DELETE accounts/email](/docs/api-pixverse-v2/del-pixverse-accounts-email), or add it again only if PixVerse lifts the ban. ```json { "error": "PixVerse banned account example@gmail.com for violating its community guidelines (400024). A ban is permanent unless PixVerse accepts an appeal. PixVerse says: \"Your account has been banned for violating community guidelines. If you wish to appeal, please contact us via ...\" Remove it with DELETE /v2/pixverse/accounts/example@gmail.com, or add it again (https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email) only if PixVerse lifts the ban.", "code": 596 } ``` If every account you have is in this state, a request without `email` returns 596 as well. ##### Model The new video's `video_id`: poll it with [GET videos/`video_id`](/docs/api-pixverse-v2/get-pixverse-videos-video_id) until it completes. <details markdown="block" class="model-details"> <summary>The new video job, field by field</summary> ```typescript { // TypeScript, all fields are optional video_id: string error: string } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST "https://api.useapi.net/v2/pixverse/videos/extend" \ -d '{"prompt": "…", "video_id": "…"}' ``` **JavaScript** ``` javascript const prompt = "text prompt"; const video_id = "video_id"; const apiUrl = `https://api.useapi.net/v2/pixverse/videos/extend`; const token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ prompt, video_id }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests prompt = "text prompt" video_id = "video_id" apiUrl = f"https://api.useapi.net/v2/pixverse/videos/extend" token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } body = { "prompt": f"{prompt}", "video_id": f"{video_id}" } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-videos-lipsync === Document URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-videos-lipsync --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/lipsync description: "Lip-sync a PixVerse video to an audio track via POST videos/lipsync in the useapi.net PixVerse API v2 — model v5, supply video and audio files via POST files." parent: PixVerse API nav_order: 1100 --- ## Lip sync video December 6, 2024 (November 16, 2026) --- * This endpoint uses PixVerse model `v5` only. See [Model Capabilities](/docs/api-pixverse-v2/model-capabilities) for details. * Lip sync a video generated by PixVerse, retrieve the `video_id` of the desired video using [GET /videos](/docs/api-pixverse-v2/get-pixverse-videos). * Upload the video using [POST /files](/docs/api-pixverse-v2/post-pixverse-files) and use `path` to specify the video you want to lip sync. * Upload the audio track using [POST /files](/docs/api-pixverse-v2/post-pixverse-files) and use `path` to specify the audio you want to use for lip sync. > **https://api.useapi.net/v2/pixverse/videos/lipsync** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "video_id": "Optional video_id", "audio_path": "Optional audio track path", "prompt": "Optional text prompt", "speaker_id": 12345, "replyUrl": "Place your call back URL here", "replyRef": "Place your reference id here", "maxJobs": 3 } ``` - `email` is optional, if not specified API will use account specified by `video_id` (if provided), otherwise randomly select account from available [accounts](/docs/api-pixverse-v2/get-pixverse-accounts). - `video_id` is optional, retrieve the `video_id` of the desired video using [GET /videos](/docs/api-pixverse-v2/get-pixverse-videos). - `video_path` is optional, upload the video using [POST /files](/docs/api-pixverse-v2/post-pixverse-files) and use `path` to specify the video you want to lip sync. - `audio_path` is optional, upload the audio track using [POST /files](/docs/api-pixverse-v2/post-pixverse-files) and use `path` to specify the audio you want to use for lip sync. Maximum length of the audio track should not exceed 60 seconds. Generation will fail if you attempt to provide a sound clip longer than that. - `prompt` is optional, provide text you want to use for lip sync. Maximum length 200 characters. - `speaker_id` is optional, to retrieve `speaker_id` see [GET /videos/voices](/docs/api-pixverse-v2/get-pixverse-videos-voices). - `original_sound_switch` is optional, set to `true` if you want to keep the original soundtrack of the video and extend it with the provided sound clip or generated audio. - `off_peak_mode` is optional. Set to `true` to generate videos during low-demand periods at a reduced credit cost. Only supported for native PixVerse models (`v5`, `v5.5`, `v5.6`, `v5-fast`, `v6`, `pixverse-c1`) — third-party models reject this flag. Discount varies by subscription plan: **Pro** 30% off, **Premium** 50% off, **Ultra** unlimited free. Results are usually delivered within 24 hours. Off-Peak generations are not tracked by the scheduler, don't count toward concurrent-job limits, and the `replyUrl` webhook is not called — use [GET videos](/docs/api-pixverse-v2/get-pixverse-videos) to retrieve results. Supported values: `false` (default), `true`. - `replyUrl` is optional. This is the preferred and most optimal way to receive results quickly — the API polls every 10 seconds and will call the provided `replyUrl` once the PixVerse video is completed or failed. Maximum length 1024 characters. We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality. Callback body has the same JSON shape as [GET /videos/`video_id`](/docs/api-pixverse-v2/get-pixverse-videos-video_id) response. - `replyRef` is optional, place here your reference id which will be stored and returned along with this PixVerse video response / result. Maximum length 1024 characters. - `maxJobs` is optional, if not specified value from selected [accounts/email](/docs/api-pixverse-v2/get-pixverse-accounts-email) will be used. Valid range: 1…8 It should not exceed the number of concurrent generations supported by your account [subscription](https://app.pixverse.ai/subscribe) plan. ##### Responses **200** **200 OK** Use the returned `video_id` to retrieve video status and results using [GET /videos](/docs/api-pixverse-v2/get-pixverse-videos). Locate the video in the response array and check if the field `video_status_final` is `true` or `video_status_name` is `COMPLETED`. The field `url` will contain the generated video link. If you specify the optional parameter [`replyUrl`](#request-body), the API will call the provided `replyUrl` with video progress updates until the video is complete or fails. ```json { "video_id": "user:<userid>-pixverse:<email>-video:<number>" } ``` **400** **400 Bad Request** ```json { "error": "<Error message>" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized" } ``` **412** **412 Insufficient credits** Insufficient credits. All Credits have been used up. Please upgrade your membership or purchase credits. ```json { "error": "All Credits have been used up. Please upgrade your membership or purchase credits." } ``` **422** **422 Unprocessable Content** Moderated message. ```json { "error": "Your prompt has triggered our AI moderator, please re-enter your prompt" } ``` **429** **429 Too Many Requests** Wait in a loop for **at least** 10..30 seconds and retry again. There are two possible cases for API response 429: 1. API query is full and can not accept new [videos/lipsync](#request-headers) requests. Size of query defined by [`maxJobs` optional parameter](#request-body). ```json { "error": "Account <email> is busy executing <maxJobs> tasks." "All configured accounts are running at maximum capacity." } ``` 2. The API received an HTTP response status 429 from PixVerse. Please refer to your [subscription](https://app.pixverse.ai/subscribe) plan for the maximum allowed tasks in the queue. ```json { "error": "Reached the limit for concurrent generations." } ``` **596** **596 Pending mod message** The account has a pending error, and the API does not use it until you add it again with [POST accounts/email](/docs/api-pixverse-v2/post-pixverse-accounts-email). You receive an email when this happens. There are three causes. PixVerse could not sign the account in, most often because its password was changed. Add the account again with the current password. ```json { "error": "Your PixVerse account has pending error. Please address this issue at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email before making any new API calls.", "code": 596 } ``` Or PixVerse suspended the account. PixVerse suspends accounts that break its content rules and does not say which generation caused it. The first response carries PixVerse's own details in `account_moderation`, and later calls return the same `error`. Add the account again after `reinstatement_at`. To ask PixVerse to lift the suspension earlier, write to the `support_email` it gives. ```json { "error": "PixVerse suspended account example@gmail.com for 30 days, from 2026-10-16 09:26 UTC until 2026-11-15 09:26 UTC. PixVerse suspends accounts that break its content rules and does not say which generation caused it. Add the account again at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email after 2026-11-15 09:26 UTC. To ask PixVerse to lift it earlier, write to support@pixverse.ai.", "code": 596, "account_moderation": { "ban_level": "suspend_30d", "action": "temporary_suspend", "duration_days": 30, "suspended_at": "2026-10-16 09:26:25 (UTC)", "reinstatement_at": "2026-11-15 09:26:25 (UTC)", "support_email": "support@pixverse.ai" } } ``` Or PixVerse banned the account for violating its community guidelines. A ban is permanent unless PixVerse accepts an appeal, and the `error` quotes PixVerse's own message, which says how to appeal. Remove the account with [DELETE accounts/email](/docs/api-pixverse-v2/del-pixverse-accounts-email), or add it again only if PixVerse lifts the ban. ```json { "error": "PixVerse banned account example@gmail.com for violating its community guidelines (400024). A ban is permanent unless PixVerse accepts an appeal. PixVerse says: \"Your account has been banned for violating community guidelines. If you wish to appeal, please contact us via ...\" Remove it with DELETE /v2/pixverse/accounts/example@gmail.com, or add it again (https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email) only if PixVerse lifts the ban.", "code": 596 } ``` If every account you have is in this state, a request without `email` returns 596 as well. ##### Model The new video's `video_id`: poll it with [GET videos/`video_id`](/docs/api-pixverse-v2/get-pixverse-videos-video_id) until it completes. <details markdown="block" class="model-details"> <summary>The new video job, field by field</summary> ```typescript { // TypeScript, all fields are optional video_id: string error: string } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST "https://api.useapi.net/v2/pixverse/videos/lipsync" \ -d '{"audio_path": "…", "video_id": "…"}' ``` **JavaScript** ``` javascript const audio_path = "audio_path"; const video_id = "video_id"; const apiUrl = `https://api.useapi.net/v2/pixverse/videos/lipsync`; const token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ audio_path, video_id }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests audio_path = "audio_path" video_id = "video_id" apiUrl = f"https://api.useapi.net/v2/pixverse/videos/lipsync" token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } body = { "audio_path": f"{audio_path}", "video_id": f"{video_id}" } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-videos-modify === Document URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-videos-modify --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/modify description: "Modify an existing PixVerse video using a text prompt via POST videos/modify in the useapi.net PixVerse API v2 — model v5.5, with request parameters and responses." parent: PixVerse API nav_order: 875 --- ## Modify video January 26, 2026 (November 16, 2026) --- This endpoint uses PixVerse model `v5.5`. Modify video content based on your prompt. * Modify a video generated by PixVerse, retrieve the `video_id` of the desired video using [GET /videos](/docs/api-pixverse-v2/get-pixverse-videos). * Upload the video using [POST /files](/docs/api-pixverse-v2/post-pixverse-files) and use `path` to specify the video you want to modify. > **https://api.useapi.net/v2/pixverse/videos/modify** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "email": "Optional PixVerse API account email", "prompt": "Required modification prompt", "video_id": "Optional video_id", "quality": "540p", "seed": 654321, "replyUrl": "Place your call back URL here", "replyRef": "Place your reference id here", "maxJobs": 3 } ``` - `email` is optional, if not specified API will randomly select account from available [accounts](/docs/api-pixverse-v2/get-pixverse-accounts). - `model` is optional. Supported values: `v5.5` (default). - `prompt` is **required**, describe the modification you want to apply. Maximum length 5,000 characters. - `video_id` is optional, retrieve the `video_id` of the desired video using [GET /videos](/docs/api-pixverse-v2/get-pixverse-videos). - `video_path` is optional, upload the video using [POST /files](/docs/api-pixverse-v2/post-pixverse-files) and use `path` to specify the video you want to modify. - `quality` is optional. Video quality. Supported values: `720p`, `540p` (default), `360p`. - `seed` is optional. Valid range 1…2147483647. - `off_peak_mode` is optional. Set to `true` to generate videos during low-demand periods at a reduced credit cost. Only supported for native PixVerse models (`v5`, `v5.5`, `v5.6`, `v5-fast`, `v6`, `pixverse-c1`) — third-party models reject this flag. Discount varies by subscription plan: **Pro** 30% off, **Premium** 50% off, **Ultra** unlimited free. Results are usually delivered within 24 hours. Off-Peak generations are not tracked by the scheduler, don't count toward concurrent-job limits, and the `replyUrl` webhook is not called — use [GET videos](/docs/api-pixverse-v2/get-pixverse-videos) to retrieve results. Supported values: `false` (default), `true`. - `replyUrl` is optional. This is the preferred and most optimal way to receive results quickly — the API polls every 10 seconds and will call the provided `replyUrl` once the PixVerse video is completed or failed. Maximum length 1024 characters. We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality. Callback body has the same JSON shape as [GET /videos/`video_id`](/docs/api-pixverse-v2/get-pixverse-videos-video_id) response. - `replyRef` is optional, place here your reference id which will be stored and returned along with this PixVerse video response / result. Maximum length 1024 characters. - `maxJobs` is optional, if not specified value from selected [accounts/email](/docs/api-pixverse-v2/get-pixverse-accounts-email) will be used. Valid range: 1…8 It should not exceed the number of concurrent generations supported by your account [subscription](https://app.pixverse.ai/subscribe) plan. ##### Responses **200** **200 OK** Use the returned `video_id` to retrieve video status and results using [GET /videos](/docs/api-pixverse-v2/get-pixverse-videos). Locate the video in the response array and check if the field `video_status_final` is `true` or `video_status_name` is `COMPLETED`. The field `url` will contain the generated video link. If you specify the optional parameter [`replyUrl`](#request-body), the API will call the provided `replyUrl` with video progress updates until the video is complete or fails. ```json { "video_id": "user:<userid>-pixverse:<email>-video:<number>" } ``` **400** **400 Bad Request** ```json { "error": "<Error message>" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized" } ``` **412** **412 Insufficient credits** Insufficient credits. All Credits have been used up. Please upgrade your membership or purchase credits. ```json { "error": "All Credits have been used up. Please upgrade your membership or purchase credits." } ``` **422** **422 Unprocessable Content** Moderated message or no masks detected. ```json { "error": "Your prompt has triggered our AI moderator, please re-enter your prompt" } ``` ```json { "error": "No masks detected in video frame" } ``` **429** **429 Too Many Requests** Wait in a loop for **at least** 10..30 seconds and retry again. There are two possible cases for API response 429: 1. API query is full and can not accept new [videos/modify](#request-headers) requests. Size of query defined by [`maxJobs` optional parameter](#request-body). ```json { "error": "Account <email> is busy executing <maxJobs> tasks." "All configured accounts are running at maximum capacity." } ``` 2. The API received an HTTP response status 429 from PixVerse. Please refer to your [subscription](https://app.pixverse.ai/subscribe) plan for the maximum allowed tasks in the queue. ```json { "error": "Reached the limit for concurrent generations." } ``` **596** **596 Pending mod message** The account has a pending error, and the API does not use it until you add it again with [POST accounts/email](/docs/api-pixverse-v2/post-pixverse-accounts-email). You receive an email when this happens. There are three causes. PixVerse could not sign the account in, most often because its password was changed. Add the account again with the current password. ```json { "error": "Your PixVerse account has pending error. Please address this issue at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email before making any new API calls.", "code": 596 } ``` Or PixVerse suspended the account. PixVerse suspends accounts that break its content rules and does not say which generation caused it. The first response carries PixVerse's own details in `account_moderation`, and later calls return the same `error`. Add the account again after `reinstatement_at`. To ask PixVerse to lift the suspension earlier, write to the `support_email` it gives. ```json { "error": "PixVerse suspended account example@gmail.com for 30 days, from 2026-10-16 09:26 UTC until 2026-11-15 09:26 UTC. PixVerse suspends accounts that break its content rules and does not say which generation caused it. Add the account again at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email after 2026-11-15 09:26 UTC. To ask PixVerse to lift it earlier, write to support@pixverse.ai.", "code": 596, "account_moderation": { "ban_level": "suspend_30d", "action": "temporary_suspend", "duration_days": 30, "suspended_at": "2026-10-16 09:26:25 (UTC)", "reinstatement_at": "2026-11-15 09:26:25 (UTC)", "support_email": "support@pixverse.ai" } } ``` Or PixVerse banned the account for violating its community guidelines. A ban is permanent unless PixVerse accepts an appeal, and the `error` quotes PixVerse's own message, which says how to appeal. Remove the account with [DELETE accounts/email](/docs/api-pixverse-v2/del-pixverse-accounts-email), or add it again only if PixVerse lifts the ban. ```json { "error": "PixVerse banned account example@gmail.com for violating its community guidelines (400024). A ban is permanent unless PixVerse accepts an appeal. PixVerse says: \"Your account has been banned for violating community guidelines. If you wish to appeal, please contact us via ...\" Remove it with DELETE /v2/pixverse/accounts/example@gmail.com, or add it again (https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email) only if PixVerse lifts the ban.", "code": 596 } ``` If every account you have is in this state, a request without `email` returns 596 as well. ##### Model The new video's `video_id`: poll it with [GET videos/`video_id`](/docs/api-pixverse-v2/get-pixverse-videos-video_id) until it completes. <details markdown="block" class="model-details"> <summary>The new video job, field by field</summary> ```typescript { // TypeScript, all fields are optional video_id: string error: string } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST "https://api.useapi.net/v2/pixverse/videos/modify" \ -d '{"prompt": "change the outfit to red dress", "video_id": "…"}' ``` **JavaScript** ``` javascript const prompt = "change the outfit to red dress"; const video_id = "video_id"; const apiUrl = `https://api.useapi.net/v2/pixverse/videos/modify`; const token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ prompt, video_id }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests prompt = "change the outfit to red dress" video_id = "video_id" apiUrl = f"https://api.useapi.net/v2/pixverse/videos/modify" token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } body = { "prompt": f"{prompt}", "video_id": f"{video_id}" } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-videos-motion-control === Document URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-videos-motion-control --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/motion-control description: "Animate a character image by transferring motion from a reference video via POST videos/motion-control in the useapi.net PixVerse API v2 — no prompt required." parent: PixVerse API nav_order: 895 --- ## Motion Control May 13, 2026 (November 16, 2026) --- Drive a character image with motion extracted from a reference video. Upload a portrait (the character) and a short motion clip — PixVerse animates the character following the motion of the clip. Useful for transferring dance moves, gestures, or full-body action onto a still image. * Upload the character image and the motion video using [POST /files](/docs/api-pixverse-v2/post-pixverse-files). * PixVerse validates the character image before submission — if it cannot detect a clear person or animal subject, the request is rejected with **422**. * This endpoint does **not** accept a prompt — motion comes entirely from the reference video. > **https://api.useapi.net/v2/pixverse/videos/motion-control** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "email": "Optional PixVerse API account email", "frame_1_path": "upload/a1b2c3d4-1111-2222-3333-character000001.webp", "video_1_path": "upload/e5f6a7b8-4444-5555-6666-motionvideo0001.mp4", "quality": "720p", "off_peak_mode": false, "replyUrl": "Place your call back URL here", "replyRef": "Place your reference here" } ``` - `email` is optional, if not specified API will randomly select account from available [accounts](/docs/api-pixverse-v2/get-pixverse-accounts). - `frame_1_path` is **required** — character image path uploaded via [POST /files](/docs/api-pixverse-v2/post-pixverse-files). Must contain a clear subject (person or animal); ambiguous or empty images will be rejected with **422**. - `video_1_path` is **required** — motion reference video path uploaded via [POST /files](/docs/api-pixverse-v2/post-pixverse-files). **Motion video limits** (enforced by PixVerse upstream): * Duration: **1–30 sec** * File size: **≤ 50 MB** * Dimensions: **≤ 1920 × 1920 px** - `model` is optional. Currently only one engine is supported. Supported values: `v5.6` (default). - `quality` is optional. Video quality. Supported values: `360p`, `540p`, `720p` (default). - `off_peak_mode` is optional. Set to `true` to generate during low-demand periods at a reduced credit cost. Discount varies by subscription plan: **Pro** 30% off, **Premium** 50% off, **Ultra** unlimited free. Results are usually delivered within 24 hours. Off-Peak generations are not tracked by the scheduler, don't count toward concurrent-job limits, and the `replyUrl` webhook is not called — use [GET videos](/docs/api-pixverse-v2/get-pixverse-videos) to retrieve results. Supported values: `false` (default), `true`. - `replyUrl` is optional. This is the preferred and most optimal way to receive results quickly — the API polls every 10 seconds and will call the provided `replyUrl` once the PixVerse video is completed or failed. Maximum length 1024 characters. We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality. Callback body has the same JSON shape as [GET /videos/`video_id`](/docs/api-pixverse-v2/get-pixverse-videos-video_id) response. - `replyRef` is optional, place here your reference id which will be stored and returned along with this PixVerse video response / result. Maximum length 1024 characters. - `maxJobs` is optional, if not specified value from selected [accounts/email](/docs/api-pixverse-v2/get-pixverse-accounts-email) will be used. Valid range: 1…8 It should not exceed the number of concurrent generations supported by your account [subscription](https://app.pixverse.ai/subscribe) plan. ##### Responses **200** **200 OK** Use the returned `video_id` to retrieve video status and results using [GET /videos](/docs/api-pixverse-v2/get-pixverse-videos). Locate the video in the response array and check if the field `video_status_final` is `true` or `video_status_name` is `COMPLETED`. The field `url` will contain the generated video link. If you specify the optional parameter [`replyUrl`](#request-body), the API will call the provided `replyUrl` with video progress updates until the video is complete or fails. ```json { "video_id": "user:<userid>-pixverse:<email>-video:<number>" } ``` **400** **400 Bad Request** ```json { "error": "<Error message>" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized" } ``` **412** **412 Insufficient credits** ```json { "error": "All Credits have been used up. Please upgrade your membership or purchase credits." } ``` **422** **422 Unprocessable Content** Character image was rejected — PixVerse could not detect a clear person or animal subject. ```json { "error": "Character image was rejected — upload a clear photo with a person or animal as the subject" } ``` **429** **429 Too Many Requests** Wait in a loop for **at least** 10..30 seconds and retry again. ```json { "error": "Account <email> is busy executing <maxJobs> tasks." "All configured accounts are running at maximum capacity." } ``` ```json { "error": "Reached the limit for concurrent generations." } ``` **596** **596 Pending mod message** The account has a pending error, and the API does not use it until you add it again with [POST accounts/email](/docs/api-pixverse-v2/post-pixverse-accounts-email). You receive an email when this happens. There are three causes. PixVerse could not sign the account in, most often because its password was changed. Add the account again with the current password. ```json { "error": "Your PixVerse account has pending error. Please address this issue at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email before making any new API calls.", "code": 596 } ``` Or PixVerse suspended the account. PixVerse suspends accounts that break its content rules and does not say which generation caused it. The first response carries PixVerse's own details in `account_moderation`, and later calls return the same `error`. Add the account again after `reinstatement_at`. To ask PixVerse to lift the suspension earlier, write to the `support_email` it gives. ```json { "error": "PixVerse suspended account example@gmail.com for 30 days, from 2026-10-16 09:26 UTC until 2026-11-15 09:26 UTC. PixVerse suspends accounts that break its content rules and does not say which generation caused it. Add the account again at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email after 2026-11-15 09:26 UTC. To ask PixVerse to lift it earlier, write to support@pixverse.ai.", "code": 596, "account_moderation": { "ban_level": "suspend_30d", "action": "temporary_suspend", "duration_days": 30, "suspended_at": "2026-10-16 09:26:25 (UTC)", "reinstatement_at": "2026-11-15 09:26:25 (UTC)", "support_email": "support@pixverse.ai" } } ``` Or PixVerse banned the account for violating its community guidelines. A ban is permanent unless PixVerse accepts an appeal, and the `error` quotes PixVerse's own message, which says how to appeal. Remove the account with [DELETE accounts/email](/docs/api-pixverse-v2/del-pixverse-accounts-email), or add it again only if PixVerse lifts the ban. ```json { "error": "PixVerse banned account example@gmail.com for violating its community guidelines (400024). A ban is permanent unless PixVerse accepts an appeal. PixVerse says: \"Your account has been banned for violating community guidelines. If you wish to appeal, please contact us via ...\" Remove it with DELETE /v2/pixverse/accounts/example@gmail.com, or add it again (https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email) only if PixVerse lifts the ban.", "code": 596 } ``` If every account you have is in this state, a request without `email` returns 596 as well. ##### Model The new video's `video_id`: poll it with [GET videos/`video_id`](/docs/api-pixverse-v2/get-pixverse-videos-video_id) until it completes. <details markdown="block" class="model-details"> <summary>The new video job, field by field</summary> ```typescript { // TypeScript, all fields are optional video_id: string error: string } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST "https://api.useapi.net/v2/pixverse/videos/motion-control" \ -d '{"frame_1_path": "upload/…webp", "video_1_path": "upload/…mp4", "quality": "720p"}' ``` **JavaScript** ``` javascript const frame_1_path = "provide path of uploaded character image via POST /files"; const video_1_path = "provide path of uploaded motion video via POST /files"; const apiUrl = `https://api.useapi.net/v2/pixverse/videos/motion-control`; const token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ frame_1_path, video_1_path, quality: '720p' }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests frame_1_path = "provide path of uploaded character image via POST /files" video_1_path = "provide path of uploaded motion video via POST /files" apiUrl = f"https://api.useapi.net/v2/pixverse/videos/motion-control" token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } body = { "frame_1_path": f"{frame_1_path}", "video_1_path": f"{video_1_path}", "quality": "720p" } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-videos-upscale === Document URL: https://useapi.net/docs/api-pixverse-v2/post-pixverse-videos-upscale --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/upscale description: "Upscale any video up to 4K via POST videos/upscale in the useapi.net PixVerse API v2 — PixVerse Upscale or Topaz Proteus and Starlight, your own uploads or PixVerse videos, free price quote." parent: PixVerse API nav_order: 1200 --- ## Upscale video to 1080p or 4K December 6, 2024 (November 16, 2026) --- Upscale a video to 1080p or 4K with PixVerse's own upscaler or one of three [Topaz](https://www.topazlabs.com) models. The source can be a video you generated on PixVerse (`video_id`) or any MP4 / MOV you upload with [POST /files](/docs/api-pixverse-v2/post-pixverse-files) (`video_path`), up to 3 minutes long and below 4K. Add `"quote": true` to get the exact price without spending anything. For images, see [POST images/upscale](/docs/api-pixverse-v2/post-pixverse-images-upscale). > **https://api.useapi.net/v2/pixverse/videos/upscale** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "video_id": "Optional video_id", "video_path": "Optional path from POST /files", "email": "Optional PixVerse account email", "model": "topaz-starlight-fast", "quality": "2160p", "quote": false, "replyUrl": "Place your call back URL here", "replyRef": "Place your reference id here", "maxJobs": 3 } ``` - `video_id` or `video_path` is **required**, provide exactly one. `video_id` is a video from [GET /videos](/docs/api-pixverse-v2/get-pixverse-videos). The account is taken from the id, so `email` is not needed. `video_path` is the `path` returned by [POST /files](/docs/api-pixverse-v2/post-pixverse-files) for an MP4 or MOV upload. Any video works, not only PixVerse generations. It must be under 4K and no longer than 3 minutes. - `email` is optional, used only with `video_path`. If not specified, the API selects an account from your [accounts](/docs/api-pixverse-v2/get-pixverse-accounts). - `model` is optional. Default: `pixverse-upscale`. | `model` | `quality` | Credits per second | Best for | |---|---|:-:|---| | `pixverse-upscale` | `2160p` | 6 | Balanced enhancement, tuned for AI-generated video | | `topaz-proteus` | `1080p` / `2160p` | 6 / 10 | General-purpose upscaling | | `topaz-starlight-fast` | `1080p` / `2160p` | 10 / 15 | Fast realistic restoration for AI video | | `topaz-starlight-precise` | `1080p` / `2160p` | 15 / 30 | Most realistic restoration, and by far the slowest | Billed seconds are the video's length rounded up, so a 5.2-second clip bills 6 seconds. See [Pricing and timing](#pricing-and-timing). - `quality` is optional. Default: `2160p` (4K). Supported values depend on `model`, see the table above. PixVerse offers 1440p (2K) in its app, but rejects it for every video model. - `quote` is optional. Set it to `true` to get the exact price and nothing else — nothing is submitted and no credits are used. See the [quote response](#responses). Pass `email` too when you have several accounts, so the price and `has_enough_credits` are for the account you will submit to. - `replyUrl` is optional. This is the preferred and most optimal way to receive results quickly — the API polls every 10 seconds and will call the provided `replyUrl` once the PixVerse video is completed or failed. Maximum length 1024 characters. We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality. Callback body has the same JSON shape as [GET /videos/`video_id`](/docs/api-pixverse-v2/get-pixverse-videos-video_id) response. - `replyRef` is optional, place here your reference id which will be stored and returned along with this PixVerse video response / result. Maximum length 1024 characters. - `maxJobs` is optional, if not specified value from selected [accounts/email](/docs/api-pixverse-v2/get-pixverse-accounts-email) will be used. Valid range: 1…8 It should not exceed the number of concurrent generations supported by your account [subscription](https://app.pixverse.ai/subscribe) plan. A request with only `video_id` (no `model`, `quality`, `video_path` or `quote`) runs PixVerse's original 4K upscale, exactly as this endpoint always has. Add any of those fields to use the models above. ##### Pricing and timing Credits per second of video, with the cost on the $60 Premium plan ($0.004 per credit): | `model` | `1080p` | `2160p` | Measured time | |---|:-:|:-:|---| | `pixverse-upscale` | — | 6 ($0.024/sec) | About 50 seconds for a 5-second clip | | `topaz-proteus` | 6 ($0.024/sec) | 10 ($0.040/sec) | About 2 minutes for a 9-second clip at 1080p | | `topaz-starlight-fast` | 10 ($0.040/sec) | 15 ($0.060/sec) | About 2.5 minutes for a 9-second clip at 1080p | | `topaz-starlight-precise` | 15 ($0.060/sec) | 30 ($0.120/sec) | About 19 minutes for a 6-second clip at 4K | The Precise run was measured while PixVerse reported it was at full capacity. Time grows with clip length and resolution, so a long clip on Precise can run for hours. These are PixVerse's list prices, observed on a Pro account. Use `"quote": true` for the exact figure on your account. While an upscale runs, [GET /videos/`video_id`](/docs/api-pixverse-v2/get-pixverse-videos-video_id) reports `video_status_name` `GENERATING`. Its `model` field shows PixVerse's internal name for the upscaler, for example `topaz_proteus`. The API keeps tracking `topaz-*` upscales for up to 6 hours and every other job for 3 hours. ##### Responses **200** **200 OK** Use the returned `video_id` to retrieve video status and results using [GET /videos/`video_id`](/docs/api-pixverse-v2/get-pixverse-videos-video_id). Check if the field `video_status_final` is `true` or `video_status_name` is `COMPLETED`. The field `url` will contain the upscaled video link. If you specify the optional parameter [`replyUrl`](#request-body), the API will call the provided `replyUrl` with video progress updates until the video is complete or fails. ```json { "video_id": "user:<userid>-pixverse:<email>-video:<number>", "model": "topaz-starlight-fast", "quality": "2160p", "cost_credits": 90 } ``` A request with only `video_id` (the original PixVerse upscale) returns `video_id` alone. With `"quote": true` nothing is submitted, and the response is the price: ```json { "quote": true, "model": "topaz-starlight-fast", "quality": "2160p", "billing_unit": "second", "bill_seconds": 6, "credits_per_unit": 15, "cost_credits": 90, "has_enough_credits": true } ``` **400** **400 Bad Request** Returned for a `quality` the `model` does not support, for both or neither of `video_id` and `video_path`, and for a source PixVerse refuses — for example one that is already 4K. ```json { "error": "Already in 4K. Higher enhancement isn’t supported. (500344)" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized" } ``` **412** **412 Insufficient credits** The account does not have enough credits for this upscale. The price is checked before anything is submitted, so nothing was created. ```json { "error": "Not enough credits: this upscale costs 270 credits" } ``` **429** **429 Too Many Requests** Wait in a loop for **at least** 10..30 seconds and retry again. There are two possible cases for API response 429: 1. API query is full and can not accept new [videos/upscale](#request-headers) requests. Size of query defined by [`maxJobs` optional parameter](#request-body). ```json { "error": "Account <email> is busy executing <maxJobs> tasks." "All configured accounts are running at maximum capacity." } ``` 2. The API received an HTTP response status 429 from PixVerse. Please refer to your [subscription](https://app.pixverse.ai/subscribe) plan for the maximum allowed tasks in the queue. ```json { "error": "Reached the limit for concurrent generations." } ``` **596** **596 Pending mod message** The account has a pending error, and the API does not use it until you add it again with [POST accounts/email](/docs/api-pixverse-v2/post-pixverse-accounts-email). You receive an email when this happens. There are three causes. PixVerse could not sign the account in, most often because its password was changed. Add the account again with the current password. ```json { "error": "Your PixVerse account has pending error. Please address this issue at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email before making any new API calls.", "code": 596 } ``` Or PixVerse suspended the account. PixVerse suspends accounts that break its content rules and does not say which generation caused it. The first response carries PixVerse's own details in `account_moderation`, and later calls return the same `error`. Add the account again after `reinstatement_at`. To ask PixVerse to lift the suspension earlier, write to the `support_email` it gives. ```json { "error": "PixVerse suspended account example@gmail.com for 30 days, from 2026-10-16 09:26 UTC until 2026-11-15 09:26 UTC. PixVerse suspends accounts that break its content rules and does not say which generation caused it. Add the account again at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email after 2026-11-15 09:26 UTC. To ask PixVerse to lift it earlier, write to support@pixverse.ai.", "code": 596, "account_moderation": { "ban_level": "suspend_30d", "action": "temporary_suspend", "duration_days": 30, "suspended_at": "2026-10-16 09:26:25 (UTC)", "reinstatement_at": "2026-11-15 09:26:25 (UTC)", "support_email": "support@pixverse.ai" } } ``` Or PixVerse banned the account for violating its community guidelines. A ban is permanent unless PixVerse accepts an appeal, and the `error` quotes PixVerse's own message, which says how to appeal. Remove the account with [DELETE accounts/email](/docs/api-pixverse-v2/del-pixverse-accounts-email), or add it again only if PixVerse lifts the ban. ```json { "error": "PixVerse banned account example@gmail.com for violating its community guidelines (400024). A ban is permanent unless PixVerse accepts an appeal. PixVerse says: \"Your account has been banned for violating community guidelines. If you wish to appeal, please contact us via ...\" Remove it with DELETE /v2/pixverse/accounts/example@gmail.com, or add it again (https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email) only if PixVerse lifts the ban.", "code": 596 } ``` If every account you have is in this state, a request without `email` returns 596 as well. ##### Model The upscaled video's `video_id` to poll with [GET videos/`video_id`](/docs/api-pixverse-v2/get-pixverse-videos-video_id) and its cost, or only the price with `"quote": true`. <details markdown="block" class="model-details"> <summary>The upscaled video job or its price quote, field by field</summary> ```typescript { // TypeScript, all fields are optional video_id: string model: 'pixverse-upscale' | 'topaz-proteus' | 'topaz-starlight-fast' | 'topaz-starlight-precise' quality: '1080p' | '2160p' cost_credits: number // "quote": true only quote: boolean billing_unit: 'second' bill_seconds: number credits_per_unit: number has_enough_credits: boolean error: string } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST "https://api.useapi.net/v2/pixverse/videos/upscale" \ -d '{"video_path": "upload/….mp4", "model": "topaz-starlight-fast", "quality": "2160p"}' ``` **JavaScript** ``` javascript const video_path = "path returned by POST /files"; const apiUrl = `https://api.useapi.net/v2/pixverse/videos/upscale`; const token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ video_path, model: 'topaz-starlight-fast', quality: '2160p' }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests video_path = "path returned by POST /files" apiUrl = f"https://api.useapi.net/v2/pixverse/videos/upscale" token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } body = { "video_path": video_path, "model": "topaz-starlight-fast", "quality": "2160p" } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/start-here/setup-runwayml === Document URL: https://useapi.net/docs/start-here/setup-runwayml --- layout: default title: Setup Runway description: "How to set up Runway for the useapi.net API — connect your account and start generating via the API." parent: Start Here nav_order: 260 --- # <img style="height:1em;vertical-align: middle;" src="/assets/images/runwayml.svg" alt=""> Setup Runway ## Table of contents Approximately 2 minutes to complete setup steps. --- > This is the setup guide for [Runway API](/docs/api-runwayml-v1). A [Runway](https://runwayml.com) account and a [useapi.net subscription](/docs/subscription) are required for the API to work. ## Create Runway account You need a [Runway](https://runwayml.com) account. Create a [new account](https://app.runwayml.com/login) if you don't have one already. Please note even if you have an existing Runway account we are **strongly** recommending creating a separate Runway account specifically designated to be used with useapi.net API. You can start with a free Runway account and upgrade to a paid account once you feel comfortable with the API offerings. For free Runway accounts, the following feature is unlocked with this third-party API: * Unlimited number of [Frames Describe](/docs/api-runwayml-v1/get-runwayml-frames-describe) generations When creating a new account, choose the **email option**. The API will not work with accounts created using Sign up with Google, Sign up with Apple, or Use Single Sign-On (SSO) options. ![](/assets/images/runwayml_setup_1.png) ## Configure API Now that you have a Runway account, configure it for API access using [POST /accounts/`email`](/docs/api-runwayml-v1/post-runwayml-accounts-email). You will need your `email` and `password`. You should receive response `200` if successful. === URL: https://useapi.net/docs/api-runwayml-v1 === Document URL: https://useapi.net/docs/api-runwayml-v1 --- layout: default title: Runway API nav_logo: /assets/images/runwayml.svg nav_title: Runway API seo_title: "Runway API: Gen-4.5 and Gen-4 Image-to-Video" description: "Third-party Runway API by useapi.net: Gen-4.5, Gen-4, Aleph, Veo 3.1, Kling and Seedance video, Act-Two and lip sync on your Runway subscription." nav_order: 5000 has_children: true permalink: /docs/api-runwayml-v1 repo: https://github.com/useapi/runway-api --- # <img style="height:1em;vertical-align: middle;" src="/assets/images/runwayml.svg" alt=""> Runway API August 8, 2024 (October 25, 2026) This is a [third-party](/docs/legal#affiliation--third-party-services) API for [Runway](https://runway.com) by Runway AI. It uses your [Runway subscription](https://runway.com/pricing): Free, Standard $15, Pro $35, Max $95 or Team $69 a seat a month (as of October 2026). It makes video with Gen-4.5, Gen-4, Aleph and Act-Two, plus Seedance 2.5, Kling O3, Veo 3.1, Wan 3.0 and the other models Runway hosts, and images, lip sync and 4K upscales, through a REST API. It spends your Runway subscription's credits, which Runway's own [developer API](https://docs.dev.runwayml.com/guides/pricing/) [can't use](https://help.runwayml.com/hc/en-us/articles/21668552945171-Runway-API-FAQs). ## Models | Model | What it makes | Notes | |---|---|---| | Gen-4.5<br>`gen4.5` | Video from [text or a first image](/docs/api-runwayml-v1/post-runwayml-gen4_5-create) | 2 to 10 seconds with sound through [videos/create](/docs/api-runwayml-v1/post-runwayml-videos-create#model-comparison-gen-45--gen-4), text-to-video in 16:9, image-to-video in six aspect ratios | | Gen-4<br>`gen4` | Video from [a first image](/docs/api-runwayml-v1/post-runwayml-gen4-create) and a prompt, and [images](/docs/api-runwayml-v1/post-runwayml-images-create#model-comparison-gen-4) | 5 or 10 seconds at 720p in six aspect ratios, [4K upscale](/docs/api-runwayml-v1/post-runwayml-gen4-upscale), images at 720p or 1080p with up to 3 references | | Gen-4 Turbo<br>`gen4-turbo` | Faster [video from a first image](/docs/api-runwayml-v1/post-runwayml-gen4turbo-create), and images | 5 or 10 seconds at 720p in about 1 to 2 minutes, [4K upscale](/docs/api-runwayml-v1/post-runwayml-gen4-upscale) | | Gen-4 Aleph | [Edits a video](/docs/api-runwayml-v1/post-runwayml-gen4-video) you upload from a text prompt | An optional image guides the result | | Act-Two | Moves a character image or video like the person in a [driving video](/docs/api-runwayml-v1/post-runwayml-gen4-act-two), and [swaps the voice](/docs/api-runwayml-v1/post-runwayml-gen4-act-two-voice) in a video | Driving video 3 to 30 seconds, with body control and expression intensity | | Lip Sync | Makes the face in an [image or video](/docs/api-runwayml-v1/post-runwayml-lipsync-create) speak your audio, or your text in an [AI voice](/docs/api-runwayml-v1/get-runwayml-lipsync-voices) | ElevenLabs voices, at least 28 languages with `eleven_multilingual_v2` | | Seedance 2.5<br>`seedance-2-5` | [Video](/docs/api-runwayml-v1/post-runwayml-videos-create#model-comparison-seedance) from text, keyframes or references, and edits or extends your video | 4 to 30 seconds at 480p, 720p or 1080p with sound, up to 50 references, real faces, 480p drafts on some accounts | | Seedance 2.0, 2.0 Fast and 2.0 Mini<br>`seedance-2`, `seedance-2-fast`, `seedance-2-mini` | Video from text, keyframes or up to 9 references | 4 to 15 seconds with sound and real faces, 1080p on 2.0 and 2.0 Fast, Mini at 480p or 720p for the fewest credits | | Kling O3 4K, Pro and Standard<br>`kling-o3-4k`, `kling-o3-pro`, `kling-o3-standard` | [Video](/docs/api-runwayml-v1/post-runwayml-videos-create#model-comparison-kling-o3) from text and up to 7 images, multi-shot, and video edit | 5 to 15 seconds with sound, up to 4K, 2 to 6 shots, edit on Pro and Standard for videos up to 10 seconds | | Kling 3.0 Pro and Standard<br>`kling-3.0-pro`, `kling-3.0-standard` | [Video](/docs/api-runwayml-v1/post-runwayml-videos-create#model-comparison-kling) from text or up to 2 images | 5, 10 or 15 seconds with sound, a first and last frame, 2 to 5 shots | | Kling 3.0 Motion Control<br>`kling-3.0-motion-control` | Moves a character image like the person in a [reference video](/docs/api-runwayml-v1/post-runwayml-videos-create#model-comparison-kling-motion-control) | Reference video 3 to 30 seconds, 720p or 1080p, its sound kept if you like | | Kling 2.6 Pro and I2V<br>`kling-2.6-pro`, `kling-2.6-i2v` | Video from text or one image | 5 or 10 seconds with sound | | Veo 3.1<br>`veo-3.1` | [Video](/docs/api-runwayml-v1/post-runwayml-videos-create#model-comparison-veo-31) from text or up to 2 images | 4, 6 or 8 seconds at 720p or 1080p with sound, a first and last frame, about 1 to 2 minutes | | Wan 3.0 and Wan 3.0 Prime<br>`wan-3.0`, `wan-3.0-prime` | [Video](/docs/api-runwayml-v1/post-runwayml-videos-create#model-comparison-wan-30) from text, keyframes or up to 10 images, 5 videos and 5 audio clips | 2 to 30 seconds at 480p, 720p or 1080p with sound, Prime is the faster tier | | Wan 2.6 Flash<br>`wan-2.6-flash` | [Video](/docs/api-runwayml-v1/post-runwayml-videos-create#model-comparison-wan) from one image | 5, 10 or 15 seconds at 720p or 1080p with sound | | Wan 2.2 Animate<br>`wan-2.2-animate` | Moves a character image like the person in a reference video | The length follows the reference video | | MiniMax H3 and H3 Max<br>`minimax-h3`, `minimax-h3-max` | [Video](/docs/api-runwayml-v1/post-runwayml-videos-create#model-comparison-minimax-h3) from text or keyframes, and on H3 from up to 9 images, 3 videos and 3 audio clips | 5 to 15 seconds, H3 at 768p or 2K, H3 Max at 480p or 768p with a seed | | FLUX 3<br>`flux-3` | [Video](/docs/api-runwayml-v1/post-runwayml-videos-create#model-comparison-flux-3) from text or a first frame, and extends a video | 5 to 20 seconds at 720p or 1080p with sound, extends videos up to 15 seconds | | Grok Imagine 1.5<br>`grok-imagine-1.5` | [Video](/docs/api-runwayml-v1/post-runwayml-videos-create#model-comparison-grok) from one image | 3 to 15 seconds at 480p or 720p, without sound | | HappyHorse 1.0<br>`happyhorse-1.0` | [Video](/docs/api-runwayml-v1/post-runwayml-videos-create#model-comparison-happyhorse) from text or one image | 3 to 15 seconds at 720p or 1080p | | FLUX 3 Image<br>`flux-3` | [Images](/docs/api-runwayml-v1/post-runwayml-images-create#model-comparison-flux-3) from text and up to 10 reference images | 0.5K to 4K in 15 aspect ratios, one image per request | | FLUX.2 Max and Klein<br>`flux-2-max`, `flux-2-klein` | [Images](/docs/api-runwayml-v1/post-runwayml-images-create#model-comparison-flux2) from text and reference images | Max up to 4K with 8 references, Klein up to 2K with 4 | | Nano Banana Pro, 2, 2 Lite and Nano Banana<br>`nano-banana-pro`, `nano-banana-2`, `nano-banana-2-lite`, `nano-banana` | [Images](/docs/api-runwayml-v1/post-runwayml-images-create#model-comparison-nano-banana) from text and up to 14 reference images (3 on Nano Banana) | Pro and 2 up to 4K, references of famous people and minors allowed, unlike on [Google Flow](/docs/api-google-flow-v1) | | GPT Image 2, 1.5 and 1 Mini<br>`gpt-image-2`, `gpt-image-1-5`, `gpt-image-1-mini` | [Images](/docs/api-runwayml-v1/post-runwayml-images-create#model-comparison-gpt-image--seedream) from text and reference images | GPT Image 2 up to 4K with 14 references and three quality levels, 1.5 and 1 Mini with one | | Seedream 5<br>`seedream-5` | Images from text and up to 14 reference images | 2K or 3K | | Frames | [4 images at 1080p](/docs/api-runwayml-v1/post-runwayml-frames-create) from text and up to 3 reference images | Under 20 seconds on average | | 4K upscale | [Any video to 4K](/docs/api-runwayml-v1/post-runwayml-videos-upscale) with Topaz AI | Videos up to 40 seconds, aspect ratio kept | | Free tool | [Image descriptions](/docs/api-runwayml-v1/get-runwayml-frames-describe) to start a prompt | Free and unlimited on every Runway account | Sora 2 is no longer available: OpenAI shut it down on September 24, 2026. ## Pricing How the useapi.net Runway API compares with Runway's own developer API (October 2026). Each [Runway subscription](https://runway.com/pricing) comes with a monthly number of credits, and every video or image uses the same credits through this API as in the Runway app. | | useapi.net Runway API | Runway's [developer API](https://docs.dev.runwayml.com/guides/pricing/) | |---|:-:|:-:| | Cost | Your Runway subscription, its monthly credits | $0.01 per credit, prepaid | | [Gen-4](/docs/api-runwayml-v1/post-runwayml-gen4-create) video | Yes | No | | [Gen-4 Aleph](/docs/api-runwayml-v1/post-runwayml-gen4-video) video editing | Yes | No | | [FLUX 3](/docs/api-runwayml-v1/post-runwayml-videos-create#model-comparison-flux-3) video and [images](/docs/api-runwayml-v1/post-runwayml-images-create#model-comparison-flux-3), FLUX.2 Max and Klein | Yes | No | | [Frames](/docs/api-runwayml-v1/post-runwayml-frames-create) images | Yes | No | | [Lip Sync](/docs/api-runwayml-v1/post-runwayml-lipsync-create) | Yes | No | | [Kling 3.0 Motion Control](/docs/api-runwayml-v1/post-runwayml-videos-create#model-comparison-kling-motion-control) and Kling 2.6 | Yes | No | | [Wan 2.6 Flash and Wan 2.2 Animate](/docs/api-runwayml-v1/post-runwayml-videos-create#model-comparison-wan) | Yes | No | | [Image descriptions](/docs/api-runwayml-v1/get-runwayml-frames-describe), free and unlimited | Yes | No | | Credits of a Runway Team workspace | Yes | No | | Gen-4.5, Gen-4 Turbo and Act-Two | Yes | Yes | | Seedance 2.5, 2.0, 2.0 Fast and 2.0 Mini | Yes | Yes | | Kling O3 and Kling 3.0 | Yes | Yes | | Veo 3.1 | Yes | Yes | | Wan 3.0, MiniMax H3, Grok Imagine 1.5 and HappyHorse 1.0 | Yes | Yes | | Nano Banana Pro, Nano Banana 2, GPT Image 2, Seedream 5 and Gen-4 images | Yes | Yes | - Image descriptions cost 0 credits on every Runway account, including the free one, and Runway's Free plan comes with 125 one-time credits. - Accounts on Runway's [Unlimited plan](https://help.runwayml.com/hc/en-us/articles/18053095835795-Unlimited-plan-details) can set `exploreMode` to make videos, images and 4K upscales without spending credits, at lower priority. It works on every model except Veo 3.1, Wan 3.0 and 3.0 Prime, MiniMax H3 and H3 Max, and FLUX 3 video and images, and Seedance runs at 480p or 720p in it. - Billed yearly, Standard costs $12, Pro $28, Max $76 and Team $55 a seat a month, for the same credits. - Team is priced per seat, from two seats, and every seat adds 6,900 credits to one shared pool. - The calculator below shows what each model costs on every plan, billed monthly or yearly, or at your own Enterprise contract price. <details markdown="block" class="calc-details"> <summary>Cost calculator for every model and subscription</summary> <div class="calc"> <div class="calc-head"><label for="rwPlanSelect" class="calc-label">Runway subscription</label><span class="calc-sep" aria-hidden="true">·</span><a class="calc-link" href="https://runway.com/pricing">current plans and prices</a><span class="calc-sep" aria-hidden="true">·</span><a class="calc-link" href="https://help.runwayml.com/hc/en-us/articles/15124877443219-How-do-credits-work">how Runway credits work</a></div> <select id="rwPlanSelect" class="calc-select"> <optgroup label="Monthly"> <option value="standard_monthly">Standard · $15/mo · 625 credits · $0.0240/credit</option> <option value="pro_monthly" selected>Pro · $35/mo · 2,250 credits · $0.0156/credit</option> <option value="max_monthly">Max · $95/mo · 9,500 credits · $0.0100/credit</option> <option value="team_monthly">Team · $69/mo a seat · 6,900 credits · $0.0100/credit</option> </optgroup> <optgroup label="Yearly, price per month"> <option value="standard_yearly">Standard yearly · $12/mo · 625 credits · $0.0192/credit</option> <option value="pro_yearly">Pro yearly · $28/mo · 2,250 credits · $0.0124/credit</option> <option value="max_yearly">Max yearly · $76/mo · 9,500 credits · $0.0080/credit</option> <option value="team_yearly">Team yearly · $55/mo a seat · 6,900 credits · $0.0080/credit</option> </optgroup> <option value="custom">Custom or Enterprise cost and credits…</option> </select> <div id="rwCustomInputs" style="display: none;"> <div class="calc-custom"> <div> <label for="rwCustomCost" class="calc-label">Cost ($)</label> <input type="number" id="rwCustomCost" value="35"> </div> <div> <label for="rwCustomCredits" class="calc-label">Credits</label> <input type="number" id="rwCustomCredits" value="2250"> </div> </div> </div> </div> <div> <table class="calc-plan"> <thead> <tr> <th>Subscription</th> <th>Cost</th> <th>Credits</th> <th>Per credit</th> </tr> </thead> <tbody> <tr id="rwPlanDetails"> <td id="rwPlanName">Pro monthly (2250 credits per month)</td> <td id="rwPlanCost">$35</td> <td id="rwPlanCredits">2250</td> <td id="rwCreditCost">$0.01556</td> </tr> </tbody> </table> </div> <h4>Price per video or image</h4> <div> <table class="calc-gen"> <thead> <tr> <th>Runway Model</th> <th>Credits</th> <th>Cost</th> </tr> </thead> <tbody> <tr><td>Seedance 2.5 480p (per sec)</td><td>20</td><td class="rw-gen-price">$0.31</td></tr> <tr><td>Seedance 2.5 480p 5sec</td><td>100</td><td class="rw-gen-price">$1.56</td></tr> <tr><td>Seedance 2.5 480p 30sec</td><td>600</td><td class="rw-gen-price">$9.33</td></tr> <tr><td>Seedance 2.5 720p (per sec)</td><td>30</td><td class="rw-gen-price">$0.47</td></tr> <tr><td>Seedance 2.5 720p 5sec</td><td>150</td><td class="rw-gen-price">$2.33</td></tr> <tr><td>Seedance 2.5 720p 30sec</td><td>900</td><td class="rw-gen-price">$14.00</td></tr> <tr><td>Seedance 2.5 1080p (per sec)</td><td>68</td><td class="rw-gen-price">$1.06</td></tr> <tr><td>Seedance 2.5 1080p 5sec</td><td>340</td><td class="rw-gen-price">$5.29</td></tr> <tr><td>Seedance 2.5 1080p 30sec</td><td>2040</td><td class="rw-gen-price">$31.73</td></tr> <tr><td>Seedance 2.0 480p / 720p (per sec)</td><td>36</td><td class="rw-gen-price">$0.56</td></tr> <tr><td>Seedance 2.0 1080p (per sec)</td><td>40</td><td class="rw-gen-price">$0.62</td></tr> <tr><td>Seedance 2.0 5sec</td><td>180</td><td class="rw-gen-price">$2.80</td></tr> <tr><td>Seedance 2.0 15sec</td><td>540</td><td class="rw-gen-price">$8.40</td></tr> <tr><td>Seedance 2.0 Fast (per sec)</td><td>29</td><td class="rw-gen-price">$0.45</td></tr> <tr><td>Seedance 2.0 Fast 5sec</td><td>145</td><td class="rw-gen-price">$2.26</td></tr> <tr><td>Seedance 2.0 Mini (per sec)</td><td>16</td><td class="rw-gen-price">$0.25</td></tr> <tr><td>Seedance 2.0 Mini 5sec</td><td>80</td><td class="rw-gen-price">$1.24</td></tr> <tr><td>Gen-4.5 (per sec)</td><td>12</td><td class="rw-gen-price">$0.19</td></tr> <tr><td>Gen-4.5 5sec</td><td>60</td><td class="rw-gen-price">$0.93</td></tr> <tr><td>Gen-4 (per sec)</td><td>12</td><td class="rw-gen-price">$0.19</td></tr> <tr><td>Gen-4 Turbo (per sec)</td><td>5</td><td class="rw-gen-price">$0.08</td></tr> <tr><td>Gen-4 Aleph (per sec)</td><td>15</td><td class="rw-gen-price">$0.23</td></tr> <tr><td>Aleph 2.0 (per sec)</td><td>28</td><td class="rw-gen-price">$0.44</td></tr> <tr><td>Aleph 2.0 5sec</td><td>140</td><td class="rw-gen-price">$2.18</td></tr> <tr><td>Veo 3.1 8sec</td><td>320</td><td class="rw-gen-price">$4.98</td></tr> <tr><td>Grok Imagine 1.5 480p 5sec</td><td>51</td><td class="rw-gen-price">$0.79</td></tr> <tr><td>Grok Imagine 1.5 720p 5sec</td><td>81</td><td class="rw-gen-price">$1.26</td></tr> <tr><td>Wan 3.0 480p (per sec)</td><td>5</td><td class="rw-gen-price">$0.08</td></tr> <tr><td>Wan 3.0 720p (per sec)</td><td>10</td><td class="rw-gen-price">$0.16</td></tr> <tr><td>Wan 3.0 1080p (per sec)</td><td>20</td><td class="rw-gen-price">$0.31</td></tr> <tr><td>Wan 3.0 1080p 5sec</td><td>100</td><td class="rw-gen-price">$1.56</td></tr> <tr><td>Wan 3.0 1080p 30sec</td><td>600</td><td class="rw-gen-price">$9.33</td></tr> <tr><td>Wan 3.0 Prime 480p 5sec</td><td>34</td><td class="rw-gen-price">$0.53</td></tr> <tr><td>Wan 3.0 Prime 720p 5sec</td><td>70</td><td class="rw-gen-price">$1.09</td></tr> <tr><td>Wan 3.0 Prime 1080p 5sec</td><td>140</td><td class="rw-gen-price">$2.18</td></tr> <tr><td>MiniMax H3 768p 5sec</td><td>50</td><td class="rw-gen-price">$0.78</td></tr> <tr><td>MiniMax H3 2K 5sec</td><td>75</td><td class="rw-gen-price">$1.17</td></tr> <tr><td>MiniMax H3 Max 480p 5sec</td><td>15</td><td class="rw-gen-price">$0.23</td></tr> <tr><td>MiniMax H3 Max 768p 5sec</td><td>24</td><td class="rw-gen-price">$0.37</td></tr> <tr><td>FLUX 3 720p (per sec)</td><td>17</td><td class="rw-gen-price">$0.26</td></tr> <tr><td>FLUX 3 1080p (per sec)</td><td>29</td><td class="rw-gen-price">$0.45</td></tr> <tr><td>FLUX 3 720p 5sec</td><td>85</td><td class="rw-gen-price">$1.32</td></tr> <tr><td>FLUX 3 1080p 5sec</td><td>145</td><td class="rw-gen-price">$2.26</td></tr> <tr><td>FLUX 3 extend 720p 5sec</td><td>205</td><td class="rw-gen-price">$3.19</td></tr> <tr><td>FLUX 3 extend 1080p 5sec</td><td>265</td><td class="rw-gen-price">$4.12</td></tr> <tr><td>Nano Banana image</td><td>5</td><td class="rw-gen-price">$0.08</td></tr> <tr><td>Nano Banana 2 image</td><td>7</td><td class="rw-gen-price">$0.11</td></tr> <tr><td>Nano Banana 2 Lite image</td><td>4</td><td class="rw-gen-price">$0.06</td></tr> <tr><td>Nano Banana Pro 2K image</td><td>20</td><td class="rw-gen-price">$0.31</td></tr> <tr><td>Nano Banana Pro 2 2K image</td><td>11</td><td class="rw-gen-price">$0.17</td></tr> <tr><td>Gen-4 image</td><td>8</td><td class="rw-gen-price">$0.12</td></tr> <tr><td>Gen-4 Turbo image</td><td>2</td><td class="rw-gen-price">$0.03</td></tr> <tr><td>FLUX 3 image 0.5K / 0.75K</td><td>6</td><td class="rw-gen-price">$0.09</td></tr> <tr><td>FLUX 3 image 1K</td><td>7</td><td class="rw-gen-price">$0.11</td></tr> <tr><td>FLUX 3 image 2K</td><td>14</td><td class="rw-gen-price">$0.22</td></tr> <tr><td>FLUX 3 image 4K</td><td>81</td><td class="rw-gen-price">$1.26</td></tr> <tr><td>Lip Sync / Act-Two generated speech (per 50 characters)</td><td>1</td><td class="rw-gen-price">$0.02</td></tr> </tbody> </table> </div> </details> <script> (function() { const runwaymlCalculatorData = { plans: { standard_monthly: { name: "Standard monthly (625 credits per month)", cost: 15, credits: 625 }, pro_monthly: { name: "Pro monthly (2250 credits per month)", cost: 35, credits: 2250 }, max_monthly: { name: "Max monthly (9500 credits per month)", cost: 95, credits: 9500 }, team_monthly: { name: "Team monthly, per seat (6900 credits per month)", cost: 69, credits: 6900 }, standard_yearly: { name: "Standard yearly (625 credits per month)", cost: 12, credits: 625 }, pro_yearly: { name: "Pro yearly (2250 credits per month)", cost: 28, credits: 2250 }, max_yearly: { name: "Max yearly (9500 credits per month)", cost: 76, credits: 9500 }, team_yearly: { name: "Team yearly, per seat (6900 credits per month)", cost: 55, credits: 6900 }, custom: { name: "Custom Plan", cost: 35, credits: 2250 } }, generations: [ { name: "Seedance 2.5 480p (per sec)", credits: 20 }, { name: "Seedance 2.5 480p 5sec", credits: 100 }, { name: "Seedance 2.5 480p 30sec", credits: 600 }, { name: "Seedance 2.5 720p (per sec)", credits: 30 }, { name: "Seedance 2.5 720p 5sec", credits: 150 }, { name: "Seedance 2.5 720p 30sec", credits: 900 }, { name: "Seedance 2.5 1080p (per sec)", credits: 68 }, { name: "Seedance 2.5 1080p 5sec", credits: 340 }, { name: "Seedance 2.5 1080p 30sec", credits: 2040 }, { name: "Seedance 2.0 480p / 720p (per sec)", credits: 36 }, { name: "Seedance 2.0 1080p (per sec)", credits: 40 }, { name: "Seedance 2.0 5sec", credits: 180 }, { name: "Seedance 2.0 15sec", credits: 540 }, { name: "Seedance 2.0 Fast (per sec)", credits: 29 }, { name: "Seedance 2.0 Fast 5sec", credits: 145 }, { name: "Seedance 2.0 Mini (per sec)", credits: 16 }, { name: "Seedance 2.0 Mini 5sec", credits: 80 }, { name: "Gen-4.5 (per sec)", credits: 12 }, { name: "Gen-4.5 5sec", credits: 60 }, { name: "Gen-4 (per sec)", credits: 12 }, { name: "Gen-4 Turbo (per sec)", credits: 5 }, { name: "Gen-4 Aleph (per sec)", credits: 15 }, { name: "Aleph 2.0 (per sec)", credits: 28 }, { name: "Aleph 2.0 5sec", credits: 140 }, { name: "Veo 3.1 8sec", credits: 320 }, { name: "Grok Imagine 1.5 480p 5sec", credits: 51 }, { name: "Grok Imagine 1.5 720p 5sec", credits: 81 }, { name: "Wan 3.0 480p (per sec)", credits: 5 }, { name: "Wan 3.0 720p (per sec)", credits: 10 }, { name: "Wan 3.0 1080p (per sec)", credits: 20 }, { name: "Wan 3.0 1080p 5sec", credits: 100 }, { name: "Wan 3.0 1080p 30sec", credits: 600 }, { name: "Wan 3.0 Prime 480p 5sec", credits: 34 }, { name: "Wan 3.0 Prime 720p 5sec", credits: 70 }, { name: "Wan 3.0 Prime 1080p 5sec", credits: 140 }, { name: "MiniMax H3 768p 5sec", credits: 50 }, { name: "MiniMax H3 2K 5sec", credits: 75 }, { name: "MiniMax H3 Max 480p 5sec", credits: 15 }, { name: "MiniMax H3 Max 768p 5sec", credits: 24 }, { name: "FLUX 3 720p (per sec)", credits: 17 }, { name: "FLUX 3 1080p (per sec)", credits: 29 }, { name: "FLUX 3 720p 5sec", credits: 85 }, { name: "FLUX 3 1080p 5sec", credits: 145 }, { name: "FLUX 3 extend 720p 5sec", credits: 205 }, { name: "FLUX 3 extend 1080p 5sec", credits: 265 }, { name: "Nano Banana image", credits: 5 }, { name: "Nano Banana 2 image", credits: 7 }, { name: "Nano Banana 2 Lite image", credits: 4 }, { name: "Nano Banana Pro 2K image", credits: 20 }, { name: "Nano Banana Pro 2 2K image", credits: 11 }, { name: "Gen-4 image", credits: 8 }, { name: "Gen-4 Turbo image", credits: 2 }, { name: "FLUX 3 image 0.5K / 0.75K", credits: 6 }, { name: "FLUX 3 image 1K", credits: 7 }, { name: "FLUX 3 image 2K", credits: 14 }, { name: "FLUX 3 image 4K", credits: 81 }, { name: "Lip Sync / Act-Two generated speech (per 50 characters)", credits: 1 } ] }; if (document.readyState === 'loading') { document.addEventListener('DOMContentLoaded', setupRunwaymlCalculator); } else { setupRunwaymlCalculator(); } function setupRunwaymlCalculator() { const planSelect = document.getElementById('rwPlanSelect'); const customInputs = document.getElementById('rwCustomInputs'); const customCost = document.getElementById('rwCustomCost'); const customCredits = document.getElementById('rwCustomCredits'); const planName = document.getElementById('rwPlanName'); const planCost = document.getElementById('rwPlanCost'); const planCredits = document.getElementById('rwPlanCredits'); const creditCost = document.getElementById('rwCreditCost'); const genPrices = document.querySelectorAll('.rw-gen-price'); if (!planSelect || !customInputs || !customCost || !customCredits || !planName || !planCost || !planCredits || !creditCost) { return; } function updatePrices() { let selectedPlan; if (planSelect.value === 'custom') { customInputs.style.display = 'block'; const cost = parseFloat(customCost.value) || 0; const credits = parseInt(customCredits.value) || 1; runwaymlCalculatorData.plans.custom.cost = cost; runwaymlCalculatorData.plans.custom.credits = credits; runwaymlCalculatorData.plans.custom.name = "Custom Plan"; selectedPlan = runwaymlCalculatorData.plans.custom; } else { customInputs.style.display = 'none'; selectedPlan = runwaymlCalculatorData.plans[planSelect.value]; } planName.textContent = selectedPlan.name; planCost.textContent = '$' + selectedPlan.cost; planCredits.textContent = selectedPlan.credits; const creditCostValue = selectedPlan.cost / selectedPlan.credits; creditCost.textContent = '$' + creditCostValue.toFixed(5); runwaymlCalculatorData.generations.forEach((gen, index) => { if (index < genPrices.length) { const price = (gen.credits * creditCostValue).toFixed(2); genPrices[index].textContent = '$' + price; } }); } planSelect.addEventListener('change', updatePrices); customCost.addEventListener('input', updatePrices); customCredits.addEventListener('input', updatePrices); updatePrices(); } })(); </script> ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. ## Run several Runway accounts Generation requests don't need `email`: each job goes to one of your Runway accounts with a free job slot, within the `maxJobs` limit (1 to 10, 5 recommended) you set for each account with [POST accounts](/docs/api-runwayml-v1/post-runwayml-accounts-email). Runway runs at least one job per account at a time, often two. When every account is busy you get `429`, so wait for a job to finish and send it again. Pass `email` to run a job on a specific account. A job that uses an uploaded [asset](/docs/api-runwayml-v1/post-runwayml-assets) runs on the account that holds it. An account that generates in a paid Runway Team workspace connects with `useWorkspace`, so its videos spend the workspace's shared credits, and [GET features](/docs/api-runwayml-v1/get-runwayml-features) lists each account's credits and workspaces. Every generation request can also send its result to your webhook (`replyUrl`, [what it sends](/docs/api-runwayml-v1/get-runwayml-tasks-taskId)), so you don't have to poll while a video takes about 10 minutes. [How useapi.net works](/docs/how-it-works) has tips for keeping your accounts healthy. ## Questions ### Does Runway have an API? Through useapi.net, yes, and it reaches models that Runway's own [developer API](https://docs.dev.runwayml.com/guides/models/) doesn't sell, among them Gen-4 video, Gen-4 Aleph, FLUX 3, Frames, Lip Sync, Kling 3.0 Motion Control and Wan 2.2 Animate (as of October 2026). It runs on your Runway website subscription, alongside Gen-4.5, Act-Two, Seedance 2.5 and Veo 3.1. ### How much does the Runway API cost? Through useapi.net, Runway videos and images spend the monthly credits of the Runway subscription you already pay for, the same credits each one uses in the Runway app. Runway's developer API can't spend those credits and sells its own at $0.01 each, while Max billed yearly works out to $0.008 a credit (as of October 2026). The [comparison](#pricing) shows what each one runs. ### How do I get a Runway API key? Through useapi.net you need no Runway developer key: you call the API with a useapi.net [API token](/docs/start-here/setup-useapi) and connect your Runway account through [Setup Runway](/docs/start-here/setup-runwayml), a free one included. Runnable Node.js examples are on GitHub at [useapi/runway-api](https://github.com/useapi/runway-api), and the [Runway tutorial](/docs/articles/runway-bash) walks through video generation step by step. ### Is there a Runway image-to-video API? Through useapi.net, yes: [POST gen4_5/create](/docs/api-runwayml-v1/post-runwayml-gen4_5-create) turns a first image into a Gen-4.5 video, [POST gen4/create](/docs/api-runwayml-v1/post-runwayml-gen4-create) runs Gen-4, and [POST videos/create](/docs/api-runwayml-v1/post-runwayml-videos-create) adds Seedance with real faces, which ByteDance's own [Seedance 2.5 guide](https://docs.byteplus.com/en/docs/modelark/seedance-2-5) rules out for reference images. Kling, Veo 3.1 and MiniMax H3 run from the same endpoint. ### Is there a free Runway API? Through useapi.net, [image descriptions](/docs/api-runwayml-v1/get-runwayml-frames-describe) are free and unlimited on every Runway account, the free one too: they turn an image into a detailed prompt, and Runway's developer API has no image-description model at all (as of October 2026). Everything else spends your Runway subscription's credits, and the [calculator](#pricing) prices each model. The free tool is only available through useapi.net. [Setup Runway](/docs/start-here/setup-runwayml) [LLM-friendly API spec](https://useapi.net/assets/aibot/api-runwayml-v1.txt) Feed this to your LLM to build integrations [Claude Code skill](/llm-tools) A drop-in useapi.net skill for Claude Code, and a rule for Cursor [Postman collection](https://www.postman.com/useapinet/useapi-net/collection/29112081-c6d86d09-998e-4e9c-9d6d-54a9573cd9a7) (October 25, 2026) [GitHub examples](https://github.com/useapi/runway-api) Batch Gen-4.5 and Gen-4 video with any hosted model, and Frames images Articles: * [Create Runway videos like a Pro](/docs/articles/runway-bash) * [Mastering Runway Frames](/docs/articles/runway-frames-script) * [Seedance 2.0 and 2.5 API Pricing: Every Route, Compared](/docs/articles/seedance-2-api-pricing) {% include lang-switch.html mode="hub" key="seedance-2-pricing" %} Examples: * [Seedance 2.0 — real-face tutorial (Runway & Dreamina)](/blog/260415) * [17 AI Image Models: The Showdown](/blog/260309i) * [Veo, Kling, Sora, Wan videos and Nano Banana, Seedream images](/blog/260305) * [Nano Banana Pro images](/blog/260217) * [Gen-4.5 image-to-video](/blog/260123) * [Gen-4.5 text-to-video](/blog/251215) * [Act Two](/blog/250722) * [Act Two voice swap](/blog/250908) * [Aleph](/blog/250804) Videos on YouTube: * [Noir Christmas, Runway Gen-4.5](https://www.youtube.com/watch?v=I8esy4sKMwo) * [Who is she? Runway Gen-4](https://www.youtube.com/shorts/R_P0dhahQAY) Developer Community: * <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> * <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> === URL: https://useapi.net/docs/api-runwayml-v1/del-runwayml-accounts-email === Document URL: https://useapi.net/docs/api-runwayml-v1/del-runwayml-accounts-email --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> accounts/`email` description: "Remove a configured Runway account via DEL accounts/email in the useapi.net Runway API v1 — clears it from load-balanced routing." parent: Runway API nav_order: 400 --- ## Delete Runway API account August 8, 2024 (November 16, 2026) --- > **https://api.useapi.net/v1/runwayml/accounts/`email`** The `email` value should correspond to an account configured previously via a [POST /accounts/`email`](/docs/api-runwayml-v1/post-runwayml-accounts-email) request. ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **204** **204 No Content** **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** ##### Model A successful delete answers `204` with no body, and an error answers with `error`, `errorDetails` and `code`. <details markdown="block" class="model-details"> <summary>The error answer, field by field</summary> ```typescript { // TypeScript, all fields are optional error: string, errorDetails: string, code: number } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X DELETE https://api.useapi.net/v1/runwayml/accounts/<email> ``` **JavaScript** ``` javascript const email = "Previously configured email"; const apiUrl = `https://api.useapi.net/v1/runwayml/accounts/${channnel}`; const token = "API token"; const data = { method: 'DELETE', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests email = "Previously configured email" apiUrl = f"https://api.useapi.net/v1/runwayml/accounts/{email}" token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-runwayml-v1/del-runwayml-assets-assetId === Document URL: https://useapi.net/docs/api-runwayml-v1/del-runwayml-assets-assetId --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> assets/`assetId` description: "Permanently delete a Runway asset by assetId via DEL assets/assetId in the useapi.net Runway API v1 — removes it from your Assets library." parent: Runway API nav_order: 1700 --- ## Delete asset August 8, 2024 (November 16, 2026) --- Runway [Assets](https://app.runwayml.com/video-tools/assets). > **https://api.useapi.net/v1/runwayml/assets/`assetId`** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Path parameter - `assetId` is **required**. Specify assetId you want to delete. ##### Responses **200** **200 OK** ```json { "success": true } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** ```json { "error": "Not found." } ``` ##### Model A successful delete answers with `success: true`, and an error answers with `error` and `code`. <details markdown="block" class="model-details"> <summary>The delete result, field by field</summary> ```typescript { // TypeScript, all fields are optional success: boolean, error: string, code: number } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X DELETE "https://api.useapi.net/v1/runwayml/assets/assetId" ``` **JavaScript** ``` javascript const assetId = "assetId to delete"; const apiUrl = `https://api.useapi.net/v1/runwayml/assets/${assetId}`; const token = "API token"; const data = { method: 'DELETE', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests assetId = "assetId to delete" apiUrl = f"https://api.useapi.net/v1/runwayml/assets/{assetId}" token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-runwayml-v1/del-runwayml-scheduler-taskId === Document URL: https://useapi.net/docs/api-runwayml-v1/del-runwayml-scheduler-taskId --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> scheduler/`taskId` description: "Cancel an in-progress Runway generation task by taskId via DEL scheduler/taskId in the useapi.net Runway API v1." parent: Runway API nav_order: 1800 --- ## Cancel task currently being executed by the API August 8, 2024 (November 16, 2026) --- > **https://api.useapi.net/v1/runwayml/scheduler/`taskId`** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Path parameter - `taskId` is **required**. Specify taskId you want to cancel. ##### Responses **204** **204 No Content** **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** ```json { "error": "Unable to locate running taskId <taskId>" } ``` ##### Model A successful cancel answers `204` with no body, and an error answers with `error` and `code`. <details markdown="block" class="model-details"> <summary>The error answer, field by field</summary> ```typescript { // TypeScript, all fields are optional error: string code: number } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X DELETE "https://api.useapi.net/v1/runwayml/scheduler/taskId" ``` **JavaScript** ``` javascript const taskId = "taskId to cancel"; const apiUrl = `https://api.useapi.net/v1/runwayml/scheduler/${taskId}`; const token = "API token"; const data = { method: 'DELETE', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests taskId = "taskId to cancel" apiUrl = f"https://api.useapi.net/v1/runwayml/scheduler/{taskId}" token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-runwayml-v1/del-runwayml-tasks-taskId === Document URL: https://useapi.net/docs/api-runwayml-v1/del-runwayml-tasks-taskId --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> tasks/`taskId` description: "Delete a Runway task record by taskId via DEL tasks/taskId in the useapi.net Runway API v1 — removes it from your task history." parent: Runway API nav_order: 2100 --- ## Delete task August 8, 2024 (November 16, 2026) --- > **https://api.useapi.net/v1/runwayml/tasks/`taskId`** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Path parameter - `taskId` is **required**. Specify taskId you want to delete. ##### Responses **200** **200 OK** ```json { "success": true } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** ```json { "error": "Not found." } ``` ##### Model A successful delete answers with `success: true`, and an error answers with `error` and `code`. <details markdown="block" class="model-details"> <summary>The delete result, field by field</summary> ```typescript { // TypeScript, all fields are optional success: boolean, error: string, code: number } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X DELETE "https://api.useapi.net/v1/runwayml/tasks/taskId" ``` **JavaScript** ``` javascript const taskId = "taskId to delete"; const apiUrl = `https://api.useapi.net/v1/runwayml/tasks/${taskId}`; const token = "API token"; const data = { method: 'DELETE', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests taskId = "taskId to delete" apiUrl = f"https://api.useapi.net/v1/runwayml/tasks/{taskId}" token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-accounts-email === Document URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-accounts-email --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts/`email` description: "Retrieve the stored configuration for a single Runway account by email via GET accounts/email in the useapi.net Runway API v1." parent: Runway API nav_order: 200 --- ## Retrieve Runway API account configuration for `email` August 8, 2024 (November 16, 2026) --- > **https://api.useapi.net/v1/runwayml/accounts/`email`** The `email` value should correspond to an account configured previously via a [POST /accounts/`email`](/docs/api-runwayml-v1/post-runwayml-accounts-email) request. ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **201** **201 Created** ```json { "email": "user-1@example.com", "password": "…secured…", "maxJobs": 5, "workspace": { "id": 654321, "name": "Team workspace", "plan": "unlimited-monthly", "auto": true }, "jwt": { "token": "eyJ…secured…Xk9", "exp": 1734858598.864, "iat": 1732266598.864, "id": 123456, } } ``` The `workspace` object is present only for accounts configured with `useWorkspace` (see [POST /accounts/`email`](/docs/api-runwayml-v1/post-runwayml-accounts-email)). It shows the team generation bills against, its plan name, and whether it was auto-selected. **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** Configuration not found. To create configuration use [POST /accounts/`email`](/docs/api-runwayml-v1/post-runwayml-accounts-email). ##### Model The account's `maxJobs`, masked password and session token, and the `workspace` it bills against when `useWorkspace` is set. <details markdown="block" class="model-details"> <summary>The account configuration, field by field</summary> ```typescript { // TypeScript, all fields are optional email: string, password: string, // always "…secured…" maxJobs: number, workspace: { id: number, name: string, plan: string, auto: boolean, } jwt: { token: string, // masked: first and last 3 characters exp: number, iat: number, id: number, } } ``` </details> ##### Examples **Curl** ``` bash curl https://api.useapi.net/v1/runwayml/accounts/<email> \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured email"; const apiUrl = `https://api.useapi.net/v1/runwayml/accounts/${email}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured email" apiUrl = f"https://api.useapi.net/v1/runwayml/accounts/{email}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-accounts === Document URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-accounts --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts description: "List all Runway accounts configured for load-balanced generation via GET accounts in the useapi.net Runway API v1 — response examples and a live Try It console." parent: Runway API nav_order: 100 --- ## Retrieve Runway API accounts configuration August 8, 2024 (November 16, 2026) --- For your convenience, you can specify your Runway configuration values under your Runway account. If you specify multiple Runway accounts, the API will automatically perform load balancing by randomly selecting an account with available capacity before making calls to Runway. This endpoint retrieves the complete list of configured API accounts for Runway. > **https://api.useapi.net/v1/runwayml/accounts** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** ```json { "user-1@example.com": { "email": "user-1@example.com", "password": "…secured…" "jwt": { "token": "eyJ…secured…Xk9", "exp": 1734858598.864, "iat": 1732266598.864, "id": 123456, }, "maxJobs": 5, "workspace": { "id": 654321, "name": "Team workspace", "plan": "unlimited-monthly", "auto": true }, }, "user-N@example.com": { "email": "user-N@example.com", "password": "…secured…" "jwt": { "token": "eyJ…secured…Xk9", "exp": 1744858598.864, "iat": 1742266598.864, "id": 78910, }, "maxJobs": 5, } } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** Configuration not found. To create configuration use [POST /accounts/`email`](/docs/api-runwayml-v1/post-runwayml-accounts-email). ##### Model An object keyed by account email, each value with that account's `maxJobs`, masked session token and `workspace` when one is set. <details markdown="block" class="model-details"> <summary>The account configurations, keyed by email, field by field</summary> ```typescript { // TypeScript, all fields are optional [email: string]: { email: string, password: string, // always "…secured…" maxJobs: number, workspace: { id: number, name: string, plan: string, auto: boolean, } jwt: { token: string, // masked: first and last 3 characters exp: number, iat: number, id: number, } } } ``` </details> ##### Examples **Curl** ``` bash curl https://api.useapi.net/v1/runwayml/accounts \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = "https://api.useapi.net/v1/runwayml/accounts"; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" apiUrl = "https://api.useapi.net/v1/runwayml/accounts" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-assets-assetId === Document URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-assets-assetId --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> assets/`assetId` description: "Retrieve a Runway asset's metadata and status by assetId via GET assets/assetId in the useapi.net Runway API v1 — parameters and response examples." parent: Runway API nav_order: 1400 --- ## Retrieve assets August 8, 2024 (November 16, 2026) --- Runway [Assets](https://app.runwayml.com/video-tools/assets). > **https://api.useapi.net/v1/runwayml/assets/`assetId`** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Path parameter - `assetId` is **required**. Specify the assetId you want to retrieve. ##### Responses **200** **200 OK** ```json { "assetId": "user:user_id-runwayml:account_email-asset:asset_uuid", "id": "<asset uuid>", "createdAt": "2024-08-01T01:02:03.456Z", "updatedAt": "2024-08-01T01:02:03.456Z", "name": "Race car.jpg", "url": "<asset url>", "previewUrls": ["<asset preview url>"], "mediaType": "image", "fileCount": 1, "fileSize": 123456, "fileExtStandardized": "jpeg", "isUserUpload": true, "metadata": null, "username": "<user name>", "userId": 123456789, "createdBy": 123456789, "userPicture": null, "private": true, "privateInTeam": true, "parentAssetGroupId": null, "favorite": false } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** ```json { "error": "Not found.", "code": 404 } ``` ##### Model The asset with its name, media type, file `url`, `previewUrls`, file size and media `metadata` such as duration and dimensions. <details markdown="block" class="model-details"> <summary>The asset record, field by field</summary> ```typescript { // TypeScript, all fields are optional assetId: string, id: string, createdAt: string, updatedAt: string, name: string, url: string, previewUrls: string[], mediaType: string, mediaSubtype: string, fileCount: number, fileSize: number, fileExtStandardized: string, isUserUpload: boolean, metadata: { frameRate: number, duration: number, dimensions: number[], size: { width: number, height: number } }, username: string, userPicture: string, userId: number, createdBy: number, private: boolean, privateInTeam: boolean, parentAssetGroupId: string, taskId: string, favorite: boolean } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/runwayml/assets/assetId" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const assetId = "assetId to retrieve"; const apiUrl = `https://api.useapi.net/v1/runwayml/assets/${assetId}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" assetId = "assetId to retrieve" apiUrl = f"https://api.useapi.net/v1/runwayml/assets/{assetId}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-assets === Document URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-assets --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> assets description: "List uploaded Runway assets with pagination via GET assets in the useapi.net Runway API v1 — filter by email, media type, offset, and limit." parent: Runway API nav_order: 1300 --- ## Retrieve assets August 8, 2024 (November 16, 2026) --- Runway [Assets](https://app.runwayml.com/video-tools/assets). > **https://api.useapi.net/v1/runwayml/assets/?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `email` is optional when only one [account](/docs/api-runwayml-v1/get-runwayml-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `offset` is **required**. This parameter is used to facilitate pagination. Valid range 0…1000. - `limit` is **required**. This parameter is used to facilitate pagination. Valid range 1…50. - `mediaType` is optional. Specify which asset media types you want to retrieve. Supported values: `video`, `image` and `audio`. ##### Responses **200** **200 OK** ```json [ { "assetId": "user:user_id-runwayml:account_email-asset:asset_uuid", "id": "<asset uuid>", "createdAt": "2024-08-01T01:02:03.456Z", "updatedAt": "2024-08-01T01:02:03.456Z", "name": "Gen-3 Alpha 35801490234, funny cats jumping over.mp4", "url": "<assets url>", "previewUrls": ["<asset preview url>"], "mediaType": "video", "mediaSubtype": null, "fileCount": 1, "fileSize": 1234567, "fileExtStandardized": "mp4", "isUserUpload": false, "metadata": { "frameRate": 24, "duration": 10.542, "width": 1280, "height": 768, "hasAlphaChannel": false, "hasAudio": true }, "username": "<user name>", "userPicture": null, "userId": 123456789, "createdBy": 123456789, "private": true, "privateInTeam": true, "parentAssetGroupId": "<uuid>", "taskId": "user:user_id-runwayml:account_email-task:task_uuid", "favorite": false, } ] ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model An array of assets, each with its `assetId`, name, media type, file `url`, `previewUrls` and media `metadata`. <details markdown="block" class="model-details"> <summary>The list of assets, field by field</summary> ```typescript { // TypeScript, all fields are optional assetId: string, id: string, createdAt: string, updatedAt: string, name: string, url: string, previewUrls: string[], mediaType: string, mediaSubtype: string, fileCount: number, fileSize: number, fileExtStandardized: string, isUserUpload: boolean, metadata: { frameRate: number, duration: number, width: number, height: number, hasAlphaChannel: boolean, hasAudio: boolean }, username: string, userPicture: string, userId: number, createdBy: number, private: boolean, privateInTeam: boolean, parentAssetGroupId: string, taskId: string, favorite: boolean }[] ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/runwayml/assets/?offset=0&limit=50&email=email" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured email"; const apiUrl = `https://api.useapi.net/v1/runwayml/assets/?offset=0&limit=50&email=${email}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured email" apiUrl = f"https://api.useapi.net/v1/runwayml/assets/?offset=0&limit=50&email={email}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-features === Document URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-features --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> features description: "Check Runway account credits and feature availability via GET features in the useapi.net Runway API v1 — parameters, responses, and a live Try It console." parent: Runway API nav_order: 402 --- ## Retrieve the Runway account features August 8, 2024 (November 16, 2026) --- Retrieve account credits information and other details. > **https://api.useapi.net/v1/runwayml/features/?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `email` is optional when only one [account](/docs/api-runwayml-v1/get-runwayml-accounts) configured. However, if you have multiple accounts configured, this parameter becomes required. ##### Responses **200** **200 OK** The response below has been omitted for brevity to include only essential fields, the live endpoint will return a much larger response. ```json { "permitted": { "storageGB": 500, "numPlanCredits": 2250 }, "used": { "numPlanCredits": 1315 }, "teams": [ { "id": 123456, "teamName": "My account", "email": "user-1@example.com", "currentPlan": null }, { "id": 654321, "teamName": "Team workspace", "email": "owner@example.com", "currentPlan": "unlimited-monthly", "planExpiration": "2026-12-31T00:00:00.000Z" } ] } ``` The `teams` array lists the workspaces (teams) this account belongs to, including its own account and any workspace it was added to. A team whose `currentPlan` is not `null` is a paid workspace — use its `id` as `useWorkspace` when configuring the account via [POST /accounts/`email`](/docs/api-runwayml-v1/post-runwayml-accounts-email) to bill generation against that workspace. **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model The account's plan credits and how many are used, its storage allowance, and the workspaces (`teams`) it belongs to with their plans. <details markdown="block" class="model-details"> <summary>The account's credits, storage and workspaces, field by field</summary> The model below has been omitted for brevity to include only essential fields, the live endpoint will return many more fields. ```typescript { // TypeScript, all fields are optional permitted: { storageGB: number, numPlanCredits: number }, used: { numPlanCredits: number }, teams: { id: number, teamName: string, email: string, currentPlan: string, planExpiration: string, }[] } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/runwayml/features/" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured email"; const apiUrl = `https://api.useapi.net/v1/runwayml/features/?email=${email}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured email" apiUrl = f"https://api.useapi.net/v1/runwayml/features/?email={email}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-frames-describe === Document URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-frames-describe --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> frames/describe description: "Extract a text prompt description from an image via GET frames/describe in the useapi.net Runway API v1 — free and unlimited, ideal for seeding frames/create prompts." parent: Runway API nav_order: 870 --- ## Get image description February 24, 2025 (November 16, 2026) --- Extract a text image description that can be adjusted and used as a starting point for the prompt in [POST frames/create](/docs/api-runwayml-v1/post-runwayml-frames-create). This endpoint is available for all Runway accounts, including free ones. > **https://api.useapi.net/v1/runwayml/frames/describe/`image_assetId`** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Path parameter - `image_assetId` is **required**. Specify the image asset. You can upload an image via [POST assets](/docs/api-runwayml-v1/post-runwayml-assets), you can get a list of all image assets via [GET assets](/docs/api-runwayml-v1/get-runwayml-assets). ##### Responses **200** **200 OK** ```json { "textPrompt": "Subject: A woman wearing an elegant Greco-Roman style ivory silk dress with ornate golden embellishments at the neckline and waist. Multiple golden bangles adorn her wrists as she stands in a graceful pose with one hand extended to touch a column.\n\nScene: Ancient stone columns with weathered surfaces frame a shadowy interior space. The architectural elements suggest a classical temple or palace setting with fluted pillars and worn stone textures visible in the warm lighting.\n\nStyle: Dramatic chiaroscuro lighting creates deep shadows while highlighting the luxurious fabric draping and metallic details. The composition emphasizes classical beauty through careful attention to form, texture, and light interplay. Professional fashion photography meets fine art painting aesthetic. Classical, dramatic lighting, textile-focused, painterly, architectural." } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model A text description of the image in `textPrompt`, a starting point for a [POST frames/create](/docs/api-runwayml-v1/post-runwayml-frames-create) prompt. <details markdown="block" class="model-details"> <summary>The image description, field by field</summary> ```typescript { // TypeScript, all fields are optional textPrompt: string error: string code: number } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/runwayml/frames/describe/image_assetId" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const image_assetId = "image_assetId to retrieve"; const apiUrl = `https://api.useapi.net/v1/runwayml/frames/describe/${image_assetId}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" image_assetId = "image_assetId to retrieve" apiUrl = f"https://api.useapi.net/v1/runwayml/frames/describe/{image_assetId}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-lipsync-voices === Document URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-lipsync-voices --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> lipsync/voices description: "List AI voices available for lip sync via GET lipsync/voices in the useapi.net Runway API v1 — returns voiceId, name, labels, and a sample URL per voice, with a live Try It console." parent: Runway API nav_order: 900 --- ## Retrieve the list of available AI voices August 8, 2024 (November 16, 2026) --- Runway [AI Tools » Audio tools » Generative Audio](https://app.runwayml.com/video-tools/ai-tools/generative-audio). Runway [AI Tools » Audio tools » Lip Sync Video](https://app.runwayml.com/video-tools/ai-tools/generative-audio). > **https://api.useapi.net/v1/runwayml/lipsync/voices/?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `email` is optional when only one [account](/docs/api-runwayml-v1/get-runwayml-accounts) configured. However, if you have multiple accounts configured, this parameter becomes ##### Responses **200** **200 OK** ```json [ { "voiceId": "pNInz6obpgDQGcFmaJgB", "createdAt": "2024-08-01T01:02:03.456Z", "updatedAt": "2024-08-01T01:02:03.456Z", "name": "Benjamin", "description": "", "labels": { "accent": "american", "description": "deep", "age": "middle aged", "gender": "male", "use case": "narration" }, "privateInTeam": true, "createdBy": 1234567, "sample": "https://runwayml.cloudfront.net/app/magic-tools/text-to-speech-voice-samples/Benjamin.mp3" }, { "voiceId": "XB0fDUnXU5powFXDhCwa", "createdAt": "2024-08-01T01:02:03.456Z", "updatedAt": "2024-08-01T01:02:03.456Z", "name": "Claudia", "description": "", "labels": { "accent": "british-swedish", "description": "seductive", "age": "young", "gender": "female", "use case": "characters" }, "privateInTeam": true, "createdBy": 1234567, "sample": "https://runwayml.cloudfront.net/app/magic-tools/text-to-speech-voice-samples/Claudia.mp3" } ] ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model An array of AI voices, each with its `voiceId`, name, description, `labels` such as accent, age and gender, and a `sample`. <details markdown="block" class="model-details"> <summary>The list of AI voices, field by field</summary> ```typescript { // TypeScript, all fields are optional voiceId: string, createdAt: string, lastUsedAt: string, name: string, description: string, labels: { accent: string, age: string, gender: string, use_case: string, description: string, descriptive: string, language: string, usecase: string, } privateInTeam: boolean, createdBy: number, sample: string } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/runwayml/lipsync/voices/" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured email"; const apiUrl = `https://api.useapi.net/v1/runwayml/lipsync/voices/?email=${email}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured email" apiUrl = f"https://api.useapi.net/v1/runwayml/lipsync/voices/?email={email}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-scheduler === Document URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-scheduler --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> scheduler description: "List tasks currently queued or running through the useapi.net scheduler via GET scheduler in the Runway API v1 — distinct from the full GET tasks list." parent: Runway API nav_order: 1700 --- ## Retrieve the list of tasks currently being executed by the API August 8, 2024 (November 16, 2026) --- This endpoint retrieves the list of tasks currently being executed by the API. If you want to get all tasks currently being executed including you manually initiated from Runway website use [GET /tasks](/docs/api-runwayml-v1/get-runwayml-tasks). Example […/tasks/?statuses=PENDING,RUNNING,THROTTLED&offset=0&limit=50](/docs/api-runwayml-v1/get-runwayml-tasks). > **https://api.useapi.net/v1/runwayml/scheduler/** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** ```json [ { "taskId": "user:user_id-runwayml:account_email-task:task_#1_uuid", "replyUrl": "<optional callback URL>", "replyRef": "<optional reference>" }, { "taskId": "user:user_id-runwayml:account_email-task:task_#N_uuid", "replyUrl": "<optional callback URL>", "replyRef": "<optional reference>" } ] ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model An array of the tasks running now, each with its `taskId` and its `replyUrl` and `replyRef` when given. <details markdown="block" class="model-details"> <summary>The list of running tasks, field by field</summary> ```typescript { // TypeScript, all fields are optional taskId: string replyUrl: string replyRef: string }[] ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/runwayml/scheduler/" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = `https://api.useapi.net/v1/runwayml/scheduler/`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" apiUrl = f"https://api.useapi.net/v1/runwayml/scheduler/" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-tasks-taskId === Document URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-tasks-taskId --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> tasks/`taskId` description: "Poll a Runway task's status and results by taskId via GET tasks/taskId in the useapi.net Runway API v1 — covers Gen-4.5, Gen-4, Act-Two, lip sync, Frames, and more." parent: Runway API nav_order: 2000 --- ## Retrieve task August 8, 2024 (November 16, 2026) --- Use this endpoint to retrieve status and results of * [gen4_5/create](/docs/api-runwayml-v1/post-runwayml-gen4_5-create) * [gen4turbo/create](/docs/api-runwayml-v1/post-runwayml-gen4turbo-create) * [gen4/create](/docs/api-runwayml-v1/post-runwayml-gen4-create) * [gen4/upscale](/docs/api-runwayml-v1/post-runwayml-gen4-upscale) * [gen4/act-two](/docs/api-runwayml-v1/post-runwayml-gen4-act-two) * [gen4/act-two-voice](/docs/api-runwayml-v1/post-runwayml-gen4-act-two-voice) * [gen4/video](/docs/api-runwayml-v1/post-runwayml-gen4-video) * [gen3turbo/create](/docs/api-runwayml-v1/post-runwayml-gen3turbo-create) * [gen3turbo/video](/docs/api-runwayml-v1/post-runwayml-gen3turbo-video) * [gen3turbo/extend](/docs/api-runwayml-v1/post-runwayml-gen3turbo-extend) * [gen3turbo/expand](/docs/api-runwayml-v1/post-runwayml-gen3turbo-expand) * [gen3turbo/actone](/docs/api-runwayml-v1/post-runwayml-gen3turbo-actone) * [gen3/create](/docs/api-runwayml-v1/post-runwayml-gen3-create) * [gen3/video](/docs/api-runwayml-v1/post-runwayml-gen3-video) * [gen3/extend](/docs/api-runwayml-v1/post-runwayml-gen3-extend) * [gen3/actone](/docs/api-runwayml-v1/post-runwayml-gen3-actone) * [gen3alpha/upscale](/docs/api-runwayml-v1/post-runwayml-gen3alpha-upscale) * [lipsync/create](/docs/api-runwayml-v1/post-runwayml-lipsync-create) * [frames/create](/docs/api-runwayml-v1/post-runwayml-frames-create) > **https://api.useapi.net/v1/runwayml/tasks/`taskId`** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Path parameter - `taskId` is **required**. Specify the taskId you want to retrieve. ##### Responses **200** **200 OK** ```json { "taskId": "user:user_id-runwayml:account_email-task:task_uuid" "id": "<task uuid>", "name": "Gen-3 Alpha 123456, Slow motion zoom in, cat chasing dog in the kitchen", "image": null, "createdAt": "2024-08-01T01:02:03.456Z", "updatedAt": "2024-08-01T01:02:03.456Z", "taskType": "gen3a", "options": { "name": "Gen-3 Alpha 123456789, Slow motion zoom in, cat chasing dog in the kitchen", "seconds": 5, "text_prompt": "Slow motion zoom in", "seed": 123456789, "exploreMode": true, "watermark": false, "enhance_prompt": false, "init_image": "<asset image url>", "resolution": "720p", "assetGroupName": "Generative Video", "recordingEnabled": true }, "status": "SUCCEEDED", "error": null, "progressText": null, "progressRatio": "1", "estimatedTimeToStartSeconds": null, "artifacts": [ { "assetId": "user:user_id-runwayml:account_email-asset:asset_uuid", "id": "<asset uuid>", "createdAt": "2024-08-01T01:02:03.456Z", "updatedAt": "2024-08-01T01:02:03.456Z", "userId": 1234567, "createdBy": 1234567, "taskId": "user:user_id-runwayml:account_email-task:task_uuid", "parentAssetGroupId": "<group uuid>", "filename": "Gen-3 Alpha 123456789, Slow motion zoom in, cat chasing dog in the kitchen", "url": "<asset url>", "fileSize": "12345678", "isDirectory": false, "previewUrls": ["<asset preview url>"], "private": true, "privateInTeam": true, "deleted": false, "reported": false, "metadata": { "frameRate": 24, "duration": 5.209, "dimensions": [ 1280, 768 ], "size": { "width": 1280, "height": 768 } }, "favorite": false } ], "sharedAsset": null } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** ```json { "error": "Not found.", "code": 404 } ``` ##### Model The task with its `status`, progress, options and any `error`, and the finished files in `artifacts` once it succeeds. <details markdown="block" class="model-details"> <summary>The task record, field by field</summary> ```typescript { // TypeScript, all fields are optional taskId: string, id: string, name: string, image: string, createdAt: string, updatedAt: string, taskType: string, options: { name: string, seconds: number, gen2Options: { mode: string, text_prompt: string, seed: number, interpolate: boolean, upscale: boolean, watermark: boolean, motion_score: number, use_motion_score: boolean, use_motion_vectors: boolean, style: string, width: number, height: number, motion_vector: { x: number, y: number, r: number, z: number, bg_x_pan: number, bg_y_pan: number }, init_video: string, image_prompt: string, init_image: string, keyframes: { image: string, timestamp: number }[], extended_from_task_id: string }, gen_audio_options: { name: string, text: string, voice_id: string, model_id: string }, paid_user_watermark_override: boolean, recordingEnabled: boolean, exploreMode: boolean, assetGroupName: string, image: string, video: string, image_asset_id: string, video_asset_id: string, audio: string, audio_asset_id: string, watermark: boolean, text_prompt: string, seed: number, image_as_end_frame: boolean, init_video: string, extended_from_task_id: string, video_prompt: string, flip: boolean, width: number, height: number, structure_transformation: number }, status: string, error: { errorMessage: string, reason: string, message: string, moderation_category: string, tally_asimov: boolean }, progressText: string, progressRatio: string, estimatedTimeToStartSeconds: number, assetId: string, sharedAsset: any, artifacts: { taskId: string, id: string, createdAt: string, updatedAt: string, userId: number, createdBy: number, parentAssetGroupId: string, filename: string, url: string, fileSize: string, isDirectory: boolean, previewUrls: string[], private: boolean, privateInTeam: boolean, deleted: boolean, reported: boolean, metadata: { frameRate: number, duration: number, dimensions: [number, number], size: { width: number, height: number } }, favorite: boolean, } } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/runwayml/tasks/taskId" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const taskId = "taskId to retrieve"; const apiUrl = `https://api.useapi.net/v1/runwayml/tasks/${taskId}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" taskId = "taskId to retrieve" apiUrl = f"https://api.useapi.net/v1/runwayml/tasks/{taskId}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-tasks === Document URL: https://useapi.net/docs/api-runwayml-v1/get-runwayml-tasks --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> tasks description: "List all Runway tasks with status filtering and pagination via GET tasks in the useapi.net Runway API v1 — query by email, statuses, offset, and limit." parent: Runway API nav_order: 1900 --- ## Retrieve tasks August 8, 2024 (November 16, 2026) --- > **https://api.useapi.net/v1/runwayml/tasks/?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `email` is optional when only one [account](/docs/api-runwayml-v1/get-runwayml-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `offset` is **required**. This parameter is used to facilitate pagination. Valid range 0…1000. - `limit` is **required** . This parameter is used to facilitate pagination. Valid range 1…1000. - `statuses` is optional. Filter results by a comma-separated list of task statuses, e.g. `PENDING,RUNNING,THROTTLED`. Supported values: `PENDING`, `RUNNING`, `THROTTLED`, `SUCCEEDED` and `FAILED`. ##### Responses **200** **200 OK** Retrieving `taskId` […/tasks/?taskId=task_id](https://api.useapi.net/v1/runwayml/tasks/?taskId=task_id) ```json { "taskId": "user:user_id-runwayml:account_email-task:task_uuid" "id": "<task uuid>", "name": "Gen-3 Alpha 123456, Slow motion zoom in, cat chasing dog in the kitchen", "image": null, "createdAt": "2024-08-01T01:02:03.456Z", "updatedAt": "2024-08-01T01:02:03.456Z", "taskType": "gen3a", "options": { "name": "Gen-3 Alpha 123456789, Slow motion zoom in, cat chasing dog in the kitchen", "seconds": 5, "text_prompt": "Slow motion zoom in", "seed": 123456789, "exploreMode": true, "watermark": false, "enhance_prompt": false, "init_image": "<asset image url>", "resolution": "720p", "assetGroupName": "Generative Video", "recordingEnabled": true }, "status": "SUCCEEDED", "error": null, "progressText": null, "progressRatio": "1", "estimatedTimeToStartSeconds": null, "artifacts": [ { "assetId": "user:user_id-runwayml:account_email-asset:asset_uuid", "id": "<asset uuid>", "createdAt": "2024-08-01T01:02:03.456Z", "updatedAt": "2024-08-01T01:02:03.456Z", "userId": 1234567, "createdBy": 1234567, "taskId": "user:user_id-runwayml:account_email-task:task_uuid", "parentAssetGroupId": "<group uuid>", "filename": "Gen-3 Alpha 123456789, Slow motion zoom in, cat chasing dog in the kitchen", "url": "<asset url>", "fileSize": "12345678", "isDirectory": false, "previewUrls": ["<asset preview url>"], "private": true, "privateInTeam": true, "deleted": false, "reported": false, "metadata": { "frameRate": 24, "duration": 5.209, "dimensions": [ 1280, 768 ], "size": { "width": 1280, "height": 768 } }, "favorite": false } ], "sharedAsset": null } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model Each task with its `taskId`, `taskType`, `status`, progress and options, and the finished files in `artifacts`. <details markdown="block" class="model-details"> <summary>Each task in the list, field by field</summary> ```typescript { // TypeScript, all fields are optional taskId: string, id: string, name: string, image: string, createdAt: string, updatedAt: string, taskType: string, options: { name: string, seconds: number, gen2Options: { mode: string, text_prompt: string, seed: number, interpolate: boolean, upscale: boolean, watermark: boolean, motion_score: number, use_motion_score: boolean, use_motion_vectors: boolean, style: string, width: number, height: number, motion_vector: { x: number, y: number, r: number, z: number, bg_x_pan: number, bg_y_pan: number }, init_video: string, image_prompt: string, init_image: string, extended_from_task_id: string }, gen_audio_options: { name: string, text: string, voice_id: string, model_id: string }, paid_user_watermark_override: boolean, recordingEnabled: boolean, exploreMode: boolean, assetGroupName: string, image: string, video: string, image_asset_id: string, video_asset_id: string, audio: string, audio_asset_id: string watermark: boolean, text_prompt: string, seed: number, image_as_end_frame: boolean, init_video: string, extended_from_task_id: string }, status: string, error: { errorMessage: string, reason: string, message: string, moderation_category: string, tally_asimov: boolean }, progressText: string, progressRatio: string, estimatedTimeToStartSeconds: number, assetId: string, sharedAsset: any, artifacts: { taskId: string, id: string, createdAt: string, updatedAt: string, userId: number, createdBy: number, parentAssetGroupId: string, filename: string, url: string, fileSize: string, isDirectory: boolean, previewUrls: string[], private: boolean, privateInTeam: boolean, deleted: boolean, reported: boolean, metadata: { frameRate: number, duration: number, dimensions: [number, number], size: { width: number, height: number } }, favorite: boolean, }[] } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/runwayml/tasks/?offset=0&limit=50&email=email" \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const email = "Previously configured email"; const apiUrl = `https://api.useapi.net/v1/runwayml/tasks/?offset=0&limit=50&email=${email}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" email = "Previously configured email" apiUrl = f"https://api.useapi.net/v1/runwayml/tasks/?offset=0&limit=50&email={email}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-accounts-email === Document URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-accounts-email --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> accounts/`email` description: "Register or update a Runway account via POST accounts/email in the useapi.net Runway API v1 — enables multi-account setup and automatic load balancing." parent: Runway API nav_order: 300 --- ## Create or update Runway API account configuration August 8, 2024 (November 16, 2026) --- For your convenience, you can specify your Runway configuration values under your account. If you specify multiple Runway accounts, the API will automatically perform load balancing by randomly selecting an account with available capacity before making calls to Runway. > **https://api.useapi.net/v1/runwayml/accounts/`email`** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "email": "Runway account email", "password": "Runway account password", "maxJobs": 1-10, "useWorkspace": true } ``` - `email`, `password` are **required**. Please see [Setup Runway](/docs/start-here/setup-runwayml) for details. - `email` value specified in the request body **must match** the email value specified in the URL path https://api.useapi.net/v1/runwayml/accounts/`email`. - `maxJobs` is **required**. Currently, it should be between 1 and 10. We recommend setting this value to 5. - `useWorkspace` is optional. Set it when the account's plan comes from a Runway workspace (team) the account was added to rather than from its own subscription, so generation bills against that workspace. Pass `true` to auto-select the account's single paid workspace, or pass a numeric team id to pin a specific workspace when the account belongs to more than one. Omit it (the default) to use the account's own plan. The team ids available to an account are listed in the `teams` array returned by [GET /features](/docs/api-runwayml-v1/get-runwayml-features). - When `useWorkspace` is set, the resolved workspace is returned in the `workspace` object (see the response below) and reused for every generation. The request returns 400 when no active paid workspace is found, when the account belongs to more than one paid workspace and none was pinned, or when a pinned team id is not a paid workspace the account can generate in. Re-send this request to re-resolve if the workspace or its plan later changes. ##### Responses **200** **200 OK** ```json { "email": "user-1@example.com", "password": "…secured…", "maxJobs": 5, "workspace": { "id": 654321, "name": "Team workspace", "plan": "unlimited-monthly", "auto": true }, "jwt": { "token": "eyJ…secured…Xk9", "exp": 1734858598.864, "iat": 1732266598.864, "id": 123456, } } ``` The `workspace` object is present only when `useWorkspace` was set and resolved. `id` is the team the request bills against, `plan` is the workspace plan name, and `auto` is `true` when the workspace was auto-selected (`useWorkspace: true`) or `false` when a team id was pinned. **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "Wrong username/password combination.", "This account has been suspended." "code": 401 } ``` ##### Model The saved configuration with `maxJobs`, the masked password and session token and, when `useWorkspace` was set, the resolved `workspace`. <details markdown="block" class="model-details"> <summary>The saved account configuration, field by field</summary> ```typescript { // TypeScript, all fields are optional email: string, password: string, // always "…secured…" maxJobs: number, useWorkspace: boolean | number, workspace: { id: number, name: string, plan: string, auto: boolean, } jwt: { token: string, // masked: first and last 3 characters exp: number, iat: number, id: number, } error: string, errorDetails: string, code: number } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST https://api.useapi.net/v1/runwayml/accounts/<email> \ -d '{"email": "…", "password": "…", "maxJobs": …}' ``` **JavaScript** ``` javascript const email = "Runway account email"; const password = "Runway account password"; const apiUrl = `https://api.useapi.net/v1/runwayml/accounts/${email}`; const token = "API token"; const maxJobs = 5; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ email, password, maxJobs }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests email = "Runway account email" password = "Runway account password" apiUrl = f"https://api.useapi.net/v1/runwayml/accounts/{email}" token = "API token" maxJobs = 5 headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } body = { "email": f"{email}", "password": f"{password}", "maxJobs": maxJobs } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-assets === Document URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-assets --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> assets description: "Upload images or videos to your Runway account via POST assets in the useapi.net Runway API v1 — required before referencing assets in generation requests." parent: Runway API nav_order: 1500 --- ## Upload the asset to your Runway account August 8, 2024 (November 16, 2026) --- Runway [Assets](https://app.runwayml.com/video-tools/assets). **IMPORTANT** If you have multiple accounts configured, you must specify the desired account where assets will be uploaded via the `email` parameter. All API endpoints where an asset is used will use the same account to execute the generation as the one where the asset was uploaded. So, by uploading an asset to the desired account, you effectively select that account for generation with that asset. [POST raw content using Make.com and similar nocode tools.](/docs/questions-and-answers#how-post-raw-content-to-runwaymlassets-and-minimaxfiles-using-makecom-and-similar-nocode-tools) > **https://api.useapi.net/v1/runwayml/assets/?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: select from the table below ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. - `Content-Type` is **required**, select from the table below: | Content-Type | File Extension | | ------------------- | -------------- | | image/png | png | | image/jpeg | jpeg | | image/gif | gif | | image/webp | webp | | image/mpo | mpo | | video/mp4 | mp4 | | video/quicktime | mov | | video/3gpp | 3gp | | video/x-matroska | mkv | | video/x-flv | flv | | video/mpeg | mpeg | | video/MP2T | ts | | video/x-msvideo | avi | | video/x-motion-jpeg | mjpeg | | video/webm | webm | | video/ogg | ogv | | audio/wav | wav | | audio/wave | wav | | audio/mpeg | mp3 | | audio/flac | flac | | audio/ogg | ogg | | audio/webm | webm | ##### Query Parameters - `email` is optional when only one [account](/docs/api-runwayml-v1/get-runwayml-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `name` is **required**. Specify the name of the asset. - `width` is optional. Specify image or video width in pixels. - `height` is optional. Specify image or video height in pixels. ##### Request Body Provide content of the uploaded file as a binary data. ##### Responses **200** **200 OK** ```json { "assetId": "user:user_id-runwayml:account_email-asset:asset_uuid", "id": "<asset uuid>", "user": { "id": 1234567, "username": "<user name>", "firstName": "<first name>", "lastName": "<last name>", "picture": null, "teamName": "<team name>", "teamPicture": null }, "createdAt": "2024-08-01T01:02:03.456Z", "updatedAt": "2024-08-01T01:02:03.456Z", "name": "<asset name>", "description": "", "type": { "name": "image", "type": "image", "isDirectory": false }, "size": 123456789, "url": "<asset url>", "previewUrls": ["<asset preview url>"], "fileCount": 1, "private": true, "permissions": { "read": true, "write": true, "admin": true }, "annotated": false, "isUserUpload": true, "sourceApplication": "web", "createdBy": { "id": 1234567, "username": "<user name>", "firstName": "<first name>", "lastName": "<last name>", "picture": null, "teamName": "<team name>", "teamPicture": null }, "favorite": false } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model The uploaded asset with its `assetId`, name, type, size, file `url` and `previewUrls`. <details markdown="block" class="model-details"> <summary>The uploaded asset, field by field</summary> ```typescript { // TypeScript, all fields are optional assetId: string, id: string, user: { id: number, username: string, firstName: string, lastName: string, picture: string, teamName: string, teamPicture: string, }, createdAt: string, updatedAt: string, name: string, description: string, type: { name: string, type: string, isDirectory: boolean, }, size: number, url: string, previewUrls: string[], fileCount: number, private: boolean, permissions: { read: boolean, write: boolean, admin: boolean, }, annotated: boolean, isUserUpload: boolean, sourceApplication: string, createdBy: { id: number, username: string, firstName: string, lastName: string, picture: string, teamName: string, teamPicture: string, }, favorite: boolean } ``` </details> ##### Examples **Curl** ``` bash curl -X POST "https://api.useapi.net/v1/runwayml/assets/?name=your_file_name" \ -H "Authorization: Bearer …" \ -H "Content-Type: image/jpeg" \ --data-binary /path/to/your/image_or_video_or_audio_file.jpeg ``` **JavaScript** ``` javascript const token = "API token"; const name = "asset name"; const apiUrl = `https://api.useapi.net/v1/runwayml/assets/?name=${name}`; let blob; /* // Example 1: Fetch image from URL const imageUrl = "https://upload.wikimedia.org/wikipedia/commons/7/7d/Mona_Lisa_color_restoration.jpg"; const responseImage = await fetch(imageUrl); blob = await responseImage.blob(); */ /* // Example 2: Load image from local file (Blob) const fsp = require('fs').promises; const imageFileName = "./cat.png"; blob = new Blob([await fsp.readFile(imageFileName)]); */ /* // Example 3: Load from input file html element // <input id="image-file" type="file"> const imageFile = document.getElementById(`image-file`); if (imageFile.files[0]) blob = imageFile.files[0]); */ const response = await fetch(apiUrl, { method: "POST" headers: { "Authorization": `Bearer ${token}`, }, body: blob }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" name = "asset name" email = "email" api_url = f"https://api.useapi.net/v1/runwayml/assets/?name={name}&email={email}" headers = { 'Authorization': f'Bearer {token}', 'Content-Type': 'image/jpeg' } # # Example 1: Fetch image from URL # image_url = "https://upload.wikimedia.org/wikipedia/commons/7/7d/Mona_Lisa_color_restoration.jpg" # response_image = requests.get(image_url) # file_content = response_image.content # # Example 2: Load image from local file # image_file_path = "./image.jpg" # with open(image_file_path, 'rb') as image_file: # file_content = image_file.read() response = requests.post(api_url, headers=headers, data=file_content) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-frames-create === Document URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-frames-create --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> frames/create description: "Generate 4 high-definition 1080p images with Runway's Frames model via POST frames/create in the useapi.net Runway API v1 — supports up to 3 reference images." parent: Runway API nav_order: 850 --- ## Frames January 29, 2025 (November 16, 2026) --- Frames is Runway's most advanced base model for image generation, offering unprecedented stylistic control and visual fidelity. This endpoint will generate 4 high-definition 1080p images in under 20 seconds on average. You can also run several generations in parallel. [Frames Prompting Guide](https://help.runwayml.com/hc/en-us/articles/35694045317139-Frames-Prompting-Guide). [References Guide](https://help.runwayml.com/hc/en-us/articles/40042718905875-References-Guide). You can specify the first, second, and third reference images via the `imageAssetId1`, `imageAssetId2`, and `imageAssetId3` parameters and refer to them in the prompt as `@IMG_1`, `@IMG_2`, and `@IMG_3`. See [example](/blog/250430). Please be aware that Runway's moderation system analyzes your image and text prompts and may fail task with moderation message if the prompt is determined to be offensive. Runway monitors the rate and the number of moderated tasks, which may result in your account being suspended when the internal threshold is exceeded. See article [Mastering Runway Frames](/docs/articles/runway-frames-script) featuring a script for batch-generating images using Runway Frames. The **account** you use to upload asset(s) via [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets) will also be used to execute the generation. Uploading an asset to a specific account ensures that generation with that asset will occur under the same account. > **https://api.useapi.net/v1/runwayml/frames/create** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "email": "Optional Runway API account email", "text_prompt": "Required text prompt", "aspect_ratio": "21:9", "diversity": 5, "num_images": 4, "style": "vivid", "seed": 12345678, "exploreMode": true, "replyUrl": "Place your call back URL here", "replyRef": "Place your reference id here", "maxJobs": 5 } ``` - `email` is optional, if not provided API will randomly select available [account](/docs/api-runwayml-v1/get-runwayml-accounts). - `text_prompt` is **required**. Describe your image in detail. [Frames Prompting Guide](https://help.runwayml.com/hc/en-us/articles/35694045317139-Frames-Prompting-Guide). Maximum length 1000 characters. - `imageAssetId1`, `imageAssetId2` and `imageAssetId3` are optional. Specify the assetIds of the first, second and third reference images. Use [GET /assets/?mediaType=image](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of image assets. To upload a new image asset use [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets). Parameters can be referred in the prompt as `@IMG_1`, `@IMG_2`, and `@IMG_3`. See [example](/blog/250430). - `style` is optional. Supported values: `vivid`, `vivid-warm`, `vivid-cool`, `high-contrast`, `high-contrast-warm`, `high-contrast-cool`, `bw`, `bw-contrast`, `muted-pastel`, `dreamscape`, `nordic-minimal`, `light-anime`, `dark-anime`, `painted-anime`, `3d-cartoon`, `sketch`, `low-angle`, `in-motion`, `terracotta`. - `aspect_ratio` is optional. Supported values: `16:9` (default), `9:16`, `1:1`, `4:3`, `3:4`, `21:9`. - `diversity` is optional. Aesthetic Range, higher values increase the creative variation between generations in a set. Valid range: 0…5. Default 2. - `num_images` is optional. Supported values: `1` (default), `4`. - `seed` is optional. Valid range 1…4294967294. - `exploreMode` is optional. Set to `true` if you have a Runway [Unlimited plan](https://help.runwayml.com/hc/en-us/articles/18053095835795-Unlimited-plan-details) and wish to execute relaxed generation. You are not charged credits for Explore mode generations. - `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used. Place here your callback URL. API will call the provided `replyUrl` once Runway task completed or failed. Maximum length 1024 characters. We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality. Callback body has the same JSON shape as [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) response. - `replyRef` is optional, place here your reference id which will be stored and returned along with this Runway task response / result. Maximum length 1024 characters. - `maxJobs` is optional, if not provided value for referenced by image assetId account will be used. Valid range: 1…10. Runway has dynamic query capacity and guarantees that, for a given account, at least one job will run — often two, and very rarely, three. If you have a single account linked, keep adding new jobs until you receive a `429` response. Once you get a `429`, wait for xx seconds or until at least one job completes, then try again. If you need to run more jobs in parallel, simply add more Runway accounts. ##### Responses **200** **200 OK** Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId). The generated images can be found in the `artifacts` array of the task with the status `SUCCEEDED`. If you specify the optional parameter [`replyUrl`](/docs/api-runwayml-v1/post-runwayml-frames-create#request-body) the API will call the provided `replyUrl` with task progress updates until the task is complete or fails. ```json { "taskId": "user:user_id-runwayml:account_email-task:task_uuid", "id": "<uuid>", "name": "<name>", "image": null, "createdAt": "2024-08-01T01:02:03.456Z", "updatedAt": "2024-08-01T01:02:03.456Z", "taskType": "text_to_image", "options": { "name": "<name>", "text_prompt": "<your text prompt>", "seed": 12345789, "exploreMode": true, "diversity": 2, "num_images": 4, "style": "vivid", "width": 1088, "height": 1920, "flip": true, "assetGroupName": "Text to Image", "recordingEnabled": true }, "status": "PENDING", "error": null, "progressText": null, "progressRatio": null, "estimatedTimeToStartSeconds": 0, "artifacts": [], "sharedAsset": null, "sourceAssetId": null, "replyUrl": "https://webhook.site/abc", "replyRef": "<your optional reference id>", "code": 200 } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **412** **412 Insufficient credits** You do not have enough credits to run this task. ```json { "error": "You do not have enough credits to run this task." } ``` **429** **429 Too Many Requests** Wait in a loop for **at least** 10..30 seconds and retry again. There are two possible cases for API response 429: * API query is full and can not accept new [frames/create](#frames) requests. Size of query defined by [`maxJobs` optional parameter](#request-body). ```json { "error": "Account <Runway account email> is busy executing <Account maxJobs> tasks", "runningTasks": { "<Runway account email>": [ { "email": "<Runway account email>", "taskId": "user:user_id-runwayml:account_email-task:task_#1_uuid", "id": "<uuid>", "replyUrl": "<replyUrl if provided>", "replyRef": "<replyRef if provided>" }, { "email": "<Runway account email>", "taskId": "user:user_id-runwayml:account_email-task:task_#N_uuid", "id": "<uuid>", "replyUrl": "<replyUrl if provided>", "replyRef": "<replyRef if provided>" } ] }, "code": 429 } ``` * The API received an HTTP response status 429 from Runway. Runway has dynamic query management and may limit the number of simultaneously executed tasks based on internal service load and policies. ```json { "error": "You have too many tasks running or pending. Please wait for some of them to finish before starting more." } ``` ##### Model The new task with its `taskId`: poll it with [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) until it finishes, then find the images in `artifacts`. <details markdown="block" class="model-details"> <summary>The new image task, field by field</summary> ```typescript { // TypeScript, all fields are optional taskId: string, id: string, name: string, image: string, createdAt: string, updatedAt: string, taskType: string, options: { name: string, text_prompt: string, diversity: number, style: string, seed: number, exploreMode: boolean, flip: boolean, width: number, height: number, num_images: number, assetGroupName: string, recordingEnabled: boolean }, status: string, progressText: string, progressRatio: number, estimatedTimeToStartSeconds: number, artifacts: any[], sharedAsset: any, error: { errorMessage: string, reason: string, message: string, moderation_category: string, tally_asimov: boolean }, code: number, replyUrl: string, replyRef: string } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST "https://api.useapi.net/v1/runwayml/frames/create" \ -d '{"text_prompt": "…"}' ``` **JavaScript** ``` javascript const text_prompt = "text prompt"; const apiUrl = `https://api.useapi.net/v1/runwayml/frames/create`; const token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ text_prompt }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests text_prompt = "text prompt" apiUrl = f"https://api.useapi.net/v1/runwayml/frames/create" token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } body = { "text_prompt": f"{text_prompt}" } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen4-act-two-voice === Document URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen4-act-two-voice --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> gen4/act-two-voice description: "Swap a character's voice in a video using an audio asset or a pre-defined voice via POST gen4/act-two-voice in the useapi.net Runway API v1." parent: Runway API nav_order: 448 --- ## Create Act-Two voice swap September 8, 2025 (November 16, 2026) --- Runway [Generate Video » Gen-4 or Gen-4 Turbo » Act-Two](https://app.runwayml.com/video-tools/teams/ai-tools/generate). [Creating with Act-Two](https://help.runwayml.com/hc/en-us/articles/42311337895827-Creating-with-Act-Two). Please be aware that Runway's moderation system analyzes your video assets and may fail task with moderation message if the content is determined to be offensive. Runway monitors the rate and the number of moderated tasks, which may result in your account being suspended when the internal threshold is exceeded. The **account** you use to upload asset(s) via [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets) will also be used to execute the generation. Uploading an asset to a specific account ensures that generation with that asset will occur under the same account. > **https://api.useapi.net/v1/runwayml/gen4/act-two-voice** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "video_assetId": "Required assetId of the video asset (3-30 seconds) for voice swap", "voiceId": "Required voice ID from available voices", "exploreMode": true, "replyUrl": "Place your call back URL here", "replyRef": "Place your reference id here", "maxJobs": 5 } ``` - `video_assetId` is **required**. Specify the video asset (3-30 seconds duration) you want to apply voice swap to. Use [GET /assets/?mediaType=video](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of video assets. To upload a new video asset use [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets). - `voiceId` is **required**. Specify the voice ID to use for voice swap. Use [GET /lipsync/voices](/docs/api-runwayml-v1/get-runwayml-lipsync-voices) to see the list of available voices. - `exploreMode` is optional. Set to `true` if you have a Runway [Unlimited plan](https://help.runwayml.com/hc/en-us/articles/18053095835795-Unlimited-plan-details) and wish to execute relaxed generation. You are not charged credits for Explore mode generations. - `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used. Place here your callback URL. API will call the provided `replyUrl` once Runway task completed or failed. Maximum length 1024 characters. We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality. Callback body has the same JSON shape as [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) response. - `replyRef` is optional, place here your reference id which will be stored and returned along with this Runway task response / result. Maximum length 1024 characters. - `maxJobs` is optional, if not provided value for referenced by video assetId account will be used. Valid range: 1…10. Runway has dynamic query capacity and guarantees that, for a given account, at least one job will run — often two, and very rarely, three. If you have a single account linked, keep adding new jobs until you receive a `429` response. Once you get a `429`, wait for xx seconds or until at least one job completes, then try again. If you need to run more jobs in parallel, simply add more Runway accounts. ##### Responses **200** **200 OK** Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId). The generated video `url` can be found in the `artifacts` array of the task with the status `SUCCEEDED`. If you specify the optional parameter [`replyUrl`](/docs/api-runwayml-v1/post-runwayml-gen4-act-two-voice#request-body) the API will call the provided `replyUrl` with task progress updates until the task is complete or fails. ```json { "task": { "id": "<uuid>", "name": "<voice_name>_<video_name>", "image": null, "createdAt": "2025-09-08T06:52:26.378Z", "updatedAt": "2025-09-08T06:52:26.468Z", "taskType": "workflow_s2s_video", "options": { "name": "<voice_name>_<video_name>", "video": "<video url>", "voiceId": "<voice id>", "seconds": 15, "exploreMode": false, "assetGroupId": "<uuid>" }, "status": "PENDING", "error": null, "progressText": null, "progressRatio": "0", "estimatedTimeToStartSeconds": 0, "artifacts": [], "sharedAsset": null, "sourceAssetId": null, "taskId": "user:user_id-runwayml:account_email-task:task_uuid", "code": 200 } } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** ```json { "error": "Unable to retrieve assetId <uuid> (Not found.)", "code": 404 } ``` **412** **412 Insufficient credits** You do not have enough credits to run this task. ```json { "error": "You do not have enough credits to run this task." } ``` **429** **429 Too Many Requests** Wait in a loop for **at least** 10..30 seconds and retry again. There are two possible cases for API response 429: * API query is full and can not accept new gen4/act-two-voice requests. Size of query defined by [`maxJobs` optional parameter](#request-body). ```json { "error": "Account <Runway account email> is busy executing <Account maxJobs> tasks", "runningTasks": { "<Runway account email>": [ { "email": "<Runway account email>", "taskId": "user:user_id-runwayml:account_email-task:task_#1_uuid", "id": "<uuid>", "replyUrl": "<replyUrl if provided>", "replyRef": "<replyRef if provided>" }, { "email": "<Runway account email>", "taskId": "user:user_id-runwayml:account_email-task:task_#N_uuid", "id": "<uuid>", "replyUrl": "<replyUrl if provided>", "replyRef": "<replyRef if provided>" } ] }, "code": 429 } ``` * The API received an HTTP response status 429 from Runway. Runway has dynamic query management and may limit the number of simultaneously executed tasks based on internal service load and policies. ```json { "error": "You have too many tasks running or pending. Please wait for some of them to finish before starting more." } ``` ##### Model The new task, inside `task`, with its `taskId`: poll it with [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) until it finishes, then find the video in `artifacts`. <details markdown="block" class="model-details"> <summary>The new video task, field by field</summary> ```typescript { // TypeScript, all fields are optional task: { taskId: string id: string name: string image: any createdAt: string updatedAt: string taskType: string options: { name: string video: string voiceId: string seconds: number exploreMode: boolean assetGroupId: string } status: string progressText: any progressRatio: string estimatedTimeToStartSeconds: number artifacts: any[] sharedAsset: any sourceAssetId: any error: { errorMessage: string reason: string message: string moderation_category: string tally_asimov: boolean } code: number } } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST "https://api.useapi.net/v1/runwayml/gen4/act-two-voice" \ -d '{"video_assetId": "…", "voiceId": "…"}' ``` **JavaScript** ``` javascript const video_assetId = "video asset (3-30 seconds) for voice swap"; const voiceId = "voice ID from available voices"; const apiUrl = `https://api.useapi.net/v1/runwayml/gen4/act-two-voice`; const token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ video_assetId, voiceId }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests video_assetId = "video asset (3-30 seconds) for voice swap" voiceId = "voice ID from available voices" apiUrl = f"https://api.useapi.net/v1/runwayml/gen4/act-two-voice" token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } body = { "video_assetId": f"{video_assetId}", "voiceId": f"{voiceId}" } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen4-act-two === Document URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen4-act-two --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> gen4/act-two description: "Animate a character from a driving video via POST gen4/act-two in the useapi.net Runway API v1 — Gen-4 Act-Two with an image or video character reference." parent: Runway API nav_order: 447 --- ## Create Act-Two videos using Gen-4 with driving video and character reference. July 22, 2025 (November 16, 2026) --- Runway [Generate Video » Gen-4 or Gen-4 Turbo » Act-Two](https://app.runwayml.com/video-tools/teams/ai-tools/generate). [Creating with Act-Two](https://help.runwayml.com/hc/en-us/articles/42311337895827-Creating-with-Act-Two). Please be aware that Runway's moderation system analyzes your image and video assets and may fail task with moderation message if the content is determined to be offensive. Runway monitors the rate and the number of moderated tasks, which may result in your account being suspended when the internal threshold is exceeded. The **account** you use to upload asset(s) via [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets) will also be used to execute the generation. Uploading an asset to a specific account ensures that generation with that asset will occur under the same account. > **https://api.useapi.net/v1/runwayml/gen4/act-two** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "driving_assetId": "Required assetId of the video asset (3-30 seconds) to drive performance", "character_assetId": "Required assetId of the image or video asset for character reference", "aspect_ratio": "16:9", "body_control": true, "expression_intensity": 3, "seed": 12345, "exploreMode": true, "replyUrl": "Place your call back URL here", "replyRef": "Place your reference id here", "maxJobs": 5 } ``` - `driving_assetId` is **required**. Specify the video asset (3-30 seconds duration) you want to use to drive performance. Use [GET /assets/?mediaType=video](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of video assets. To upload a new video asset use [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets). - `character_assetId` is **required**. Specify the image or video asset for your character reference. Use [GET /assets/?mediaType=image](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of image or video assets. To upload a new image or video asset use [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets). - `aspect_ratio` is optional. Controls the output video dimensions. Supported values: `16:9` (default), `9:16`, `1:1`, `4:3`, `3:4`, `21:9`. - `body_control` is optional. Controls body movement tracking. Default: `true`. - `expression_intensity` is optional. Controls the intensity of facial expressions. Valid range: 1…5, default: 3. - `seed` is optional. Use the same seed to get reproducible results. If not provided, a random seed will be generated. Valid range: 1…2147483647. - `exploreMode` is optional. Set to `true` if you have a Runway [Unlimited plan](https://help.runwayml.com/hc/en-us/articles/18053095835795-Unlimited-plan-details) and wish to execute relaxed generation. You are not charged credits for Explore mode generations. - `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used. Place here your callback URL. API will call the provided `replyUrl` once Runway task completed or failed. Maximum length 1024 characters. We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality. Callback body has the same JSON shape as [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) response. - `replyRef` is optional, place here your reference id which will be stored and returned along with this Runway task response / result. Maximum length 1024 characters. - `maxJobs` is optional, if not provided value for referenced by video assetId account will be used. Valid range: 1…10. Runway has dynamic query capacity and guarantees that, for a given account, at least one job will run — often two, and very rarely, three. If you have a single account linked, keep adding new jobs until you receive a `429` response. Once you get a `429`, wait for xx seconds or until at least one job completes, then try again. If you need to run more jobs in parallel, simply add more Runway accounts. ##### Responses **200** **200 OK** Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId). The generated video `url` can be found in the `artifacts` array of the task with the status `SUCCEEDED`. If you specify the optional parameter [`replyUrl`](/docs/api-runwayml-v1/post-runwayml-gen4-act-two#request-body) the API will call the provided `replyUrl` with task progress updates until the task is complete or fails. ```json { "task": { "id": "<uuid>", "name": "Act-Two <driving_video_name>_<character_asset_name>", "image": null, "createdAt": "2025-07-22T06:52:26.378Z", "updatedAt": "2025-07-22T06:52:26.468Z", "taskType": "act_two", "options": { "name": "Act-Two <driving_video_name>_<character_asset_name>", "driving_video": "<driving video url>", "character_image": "<character image url>", "character_video": "<character video url>", "seconds": 6, "exploreMode": false, "height": 720, "width": 1280, "seed": 2830268783, "watermark": false, "body_control": true, "expression_intensity": 1, "assetGroupId": "<uuid>", "recordingEnabled": true }, "status": "PENDING", "error": null, "progressText": null, "progressRatio": "0", "estimatedTimeToStartSeconds": 0, "artifacts": [], "sharedAsset": null, "sourceAssetId": null, "taskId": "user:user_id-runwayml:account_email-task:task_uuid", "code": 200 } } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** ```json { "error": "Unable to retrieve assetId <uuid> (Not found.)", "code": 404 } ``` **412** **412 Insufficient credits** You do not have enough credits to run this task. ```json { "error": "You do not have enough credits to run this task." } ``` **429** **429 Too Many Requests** Wait in a loop for **at least** 10..30 seconds and retry again. There are two possible cases for API response 429: * API query is full and can not accept new [gen4/act-two](#create-act-two-videos-using-gen-4-with-driving-video-and-character-reference) requests. Size of query defined by [`maxJobs` optional parameter](#request-body). ```json { "error": "Account <Runway account email> is busy executing <Account maxJobs> tasks", "runningTasks": { "<Runway account email>": [ { "email": "<Runway account email>", "taskId": "user:user_id-runwayml:account_email-task:task_#1_uuid", "id": "<uuid>", "replyUrl": "<replyUrl if provided>", "replyRef": "<replyRef if provided>" }, { "email": "<Runway account email>", "taskId": "user:user_id-runwayml:account_email-task:task_#N_uuid", "id": "<uuid>", "replyUrl": "<replyUrl if provided>", "replyRef": "<replyRef if provided>" } ] }, "code": 429 } ``` * The API received an HTTP response status 429 from Runway. Runway has dynamic query management and may limit the number of simultaneously executed tasks based on internal service load and policies. ```json { "error": "You have too many tasks running or pending. Please wait for some of them to finish before starting more." } ``` ##### Model The new task, inside `task`, with its `taskId`: poll it with [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) until it finishes, then find the video in `artifacts`. <details markdown="block" class="model-details"> <summary>The new video task, field by field</summary> ```typescript { // TypeScript, all fields are optional task: { taskId: string id: string name: string image: any createdAt: string updatedAt: string taskType: string options: { name: string driving_video: string character_image: string character_video: string seconds: number exploreMode: boolean height: number width: number seed: number watermark: boolean body_control: boolean expression_intensity: number assetGroupId: string recordingEnabled: boolean } status: string progressText: any progressRatio: string estimatedTimeToStartSeconds: number artifacts: any[] sharedAsset: any sourceAssetId: any error: { errorMessage: string reason: string message: string moderation_category: string tally_asimov: boolean } code: number } } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST "https://api.useapi.net/v1/runwayml/gen4/act-two" \ -d '{"driving_assetId": "…", "character_assetId": "…"}' ``` **JavaScript** ``` javascript const driving_assetId = "video asset (3-30 seconds) to drive performance"; const character_assetId = "image or video asset for character reference"; const apiUrl = `https://api.useapi.net/v1/runwayml/gen4/act-two`; const token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ driving_assetId, character_assetId }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests driving_assetId = "video asset (3-30 seconds) to drive performance" character_assetId = "image or video asset for character reference" apiUrl = f"https://api.useapi.net/v1/runwayml/gen4/act-two" token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } body = { "driving_assetId": f"{driving_assetId}", "character_assetId": f"{character_assetId}" } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen4-create === Document URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen4-create --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> gen4/create description: "Generate a Gen-4 image-to-video clip from reference images and a text prompt via POST gen4/create in the useapi.net Runway API v1 — parameters and a live Try It console." parent: Runway API nav_order: 440 --- ## Create a video using the first image(s) with a text prompt April 2, 2025 (November 16, 2026) --- Runway [Generate Video » Gen-4](https://app.runwayml.com/video-tools/ai-tools/generative-video). [Creating with Gen-4](https://help.runwayml.com/hc/en-us/articles/37327109429011-Creating-with-Gen-4). Please take a look at the code provided in the article [Create Runway videos like a Pro](/docs/articles/runway-bash) as it covers all aspects of video generation and downloading of generated videos along with proper handling of corner cases. Please be aware that Runway's moderation system analyzes your image and text prompts and may fail task with moderation message if the prompt is determined to be offensive. Runway monitors the rate and the number of moderated tasks, which may result in your account being suspended when the internal threshold is exceeded. The **account** you use to upload asset(s) via [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets) will also be used to execute the generation. Uploading an asset to a specific account ensures that generation with that asset will occur under the same account. > **https://api.useapi.net/v1/runwayml/gen4/create** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "firstImage_assetId": "Required assetId of first image asset", "text_prompt": "Optional text prompt", "aspect_ratio": "3:4", "seconds": 5, "seed": 12345678 "exploreMode": true, "replyUrl": "Place your call back URL here", "replyRef": "Place your reference id here", "maxJobs": 5 } ``` - `firstImage_assetId` is **required**. Specify the image assetId you want to be present in the **first** frame. Use [GET /assets/?mediaType=image](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of image assets. To upload a new image asset use [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets). - `text_prompt` is optional. Describe your shot. [Creating with Gen-4](https://help.runwayml.com/hc/en-us/articles/37327109429011-Creating-with-Gen-4). Maximum length: 1000 characters. - `aspect_ratio` is optional. Supported values: `16:9` (default), `9:16`, `1:1`, `4:3`, `3:4`, `21:9`. - `seconds` is optional. Specify desired length of the video in seconds. Supported values: `5` (default), `10`. - `seed` is optional. Valid range 1…4294967294. - `exploreMode` is optional. Set to `true` if you have a Runway [Unlimited plan](https://help.runwayml.com/hc/en-us/articles/18053095835795-Unlimited-plan-details) and wish to execute relaxed generation. You are not charged credits for Explore mode generations. - `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used. Place here your callback URL. API will call the provided `replyUrl` once Runway task completed or failed. Maximum length 1024 characters. We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality. Callback body has the same JSON shape as [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) response. - `replyRef` is optional, place here your reference id which will be stored and returned along with this Runway task response / result. Maximum length 1024 characters. - `maxJobs` is optional, if not provided value for referenced by image assetId account will be used. Valid range: 1…10. Runway has dynamic query capacity and guarantees that, for a given account, at least one job will run — often two, and very rarely, three. If you have a single account linked, keep adding new jobs until you receive a `429` response. Once you get a `429`, wait for xx seconds or until at least one job completes, then try again. If you need to run more jobs in parallel, simply add more Runway accounts. ##### Responses **200** **200 OK** Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId). The generated video `url` can be found in the `artifacts` array of the task with the status `SUCCEEDED`. If you specify the optional parameter [`replyUrl`](/docs/api-runwayml-v1/post-runwayml-gen4-create#request-body) the API will call the provided `replyUrl` with task progress updates until the task is complete or fails. ```json { "task": { "taskId": "user:user_id-runwayml:account_email-task:task_uuid", "id": "<uuid>", "name": "<name>", "image": null, "createdAt": "2024-08-01T01:02:03.456Z", "updatedAt": "2024-08-01T01:02:03.456Z", "taskType": "gen4", "options": { "name": "<name>", "route": "i2v", "seconds": 10, "text_prompt": "<your text prompt>", "seed": 12345789, "exploreMode": true, "watermark": false, "assetGroupName": "Generative Video", "init_image": "<image url>", "width": 832, "height": 1104, "recordingEnabled": true }, "status": "PENDING", "error": null, "progressText": null, "progressRatio": null, "estimatedTimeToStartSeconds": 0, "artifacts": [], "sharedAsset": null, "replyUrl": "https://webhook.site/abc", "replyRef": "<your optional reference id>", "code": 200 } } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** ```json { "error": "Unable to retrieve assetId <uuid> (Not found.)", "code": 404 } ``` **412** **412 Insufficient credits** You do not have enough credits to run this task. ```json { "error": "You do not have enough credits to run this task." } ``` **429** **429 Too Many Requests** Wait in a loop for **at least** 10..30 seconds and retry again. There are two possible cases for API response 429: * API query is full and can not accept new gen4/create requests. Size of query defined by [`maxJobs` optional parameter](#request-body). ```json { "error": "Account <Runway account email> is busy executing <Account maxJobs> tasks", "runningTasks": { "<Runway account email>": [ { "email": "<Runway account email>", "taskId": "user:user_id-runwayml:account_email-task:task_#1_uuid", "id": "<uuid>", "replyUrl": "<replyUrl if provided>", "replyRef": "<replyRef if provided>" }, { "email": "<Runway account email>", "taskId": "user:user_id-runwayml:account_email-task:task_#N_uuid", "id": "<uuid>", "replyUrl": "<replyUrl if provided>", "replyRef": "<replyRef if provided>" } ] }, "code": 429 } ``` * The API received an HTTP response status 429 from Runway. Runway has dynamic query management and may limit the number of simultaneously executed tasks based on internal service load and policies. ```json { "error": "You have too many tasks running or pending. Please wait for some of them to finish before starting more." } ``` ##### Model The new task, inside `task`, with its `taskId`: poll it with [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) until it finishes, then find the video in `artifacts`. <details markdown="block" class="model-details"> <summary>The new video task, field by field</summary> ```typescript { // TypeScript, all fields are optional task: { taskId: string, id: string, name: string, image: string, createdAt: string, updatedAt: string, taskType: string, options: { name: string, seconds: number, text_prompt: string, seed: number, exploreMode: boolean, watermark: boolean, enhance_prompt: boolean, route: string, init_image: string, assetGroupId: string, assetGroupName: string, recordingEnabled: boolean }, status: string, progressText: string, progressRatio: number, estimatedTimeToStartSeconds: number, artifacts: any[], sharedAsset: any, error: { errorMessage: string, reason: string, message: string, moderation_category: string, tally_asimov: boolean }, code: number, replyUrl: string, replyRef: string } } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST "https://api.useapi.net/v1/runwayml/gen4/create" \ -d '{"firstImage_assetId": "…", "text_prompt": "…"}' ``` **JavaScript** ``` javascript const firstImage_assetId = "assetId of image asset"; const text_prompt = "text prompt"; const apiUrl = `https://api.useapi.net/v1/runwayml/gen4/create`; const token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ firstImage_assetId, text_prompt }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests firstImage_assetId = "assetId of image asset" text_prompt = "text prompt" apiUrl = f"https://api.useapi.net/v1/runwayml/gen4/create" token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } body = { "firstImage_assetId": f"{firstImage_assetId}", "text_prompt": f"{text_prompt}" } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen4-upscale === Document URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen4-upscale --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> gen4/upscale description: "Upscale Gen-4, Gen-4 Turbo, Gen-3 Alpha, and Gen-3 Alpha Turbo videos to 4K via POST gen4/upscale in the useapi.net Runway API v1 — parameters, responses, and a live Try It console." parent: Runway API nav_order: 445 --- ## Upscale to 4K the Gen-4, Gen-4 Turbo, Gen-3 Alpha and Gen-3 Alpha Turbo videos April 7, 2025 (November 16, 2026) --- Use this endpoint to Upscale to 4K videos generated by * [gen4turbo/create](/docs/api-runwayml-v1/post-runwayml-gen4turbo-create) * [gen4/create](/docs/api-runwayml-v1/post-runwayml-gen4-create) * [gen3turbo/create](/docs/api-runwayml-v1/post-runwayml-gen3turbo-create) * [gen3turbo/video](/docs/api-runwayml-v1/post-runwayml-gen3turbo-video) * [gen3turbo/extend](/docs/api-runwayml-v1/post-runwayml-gen3turbo-extend) * [gen3turbo/expand](/docs/api-runwayml-v1/post-runwayml-gen3turbo-expand) * [gen3turbo/actone](/docs/api-runwayml-v1/post-runwayml-gen3turbo-actone) * [gen3/create](/docs/api-runwayml-v1/post-runwayml-gen3-create) * [gen3/video](/docs/api-runwayml-v1/post-runwayml-gen3-video) * [gen3/extend](/docs/api-runwayml-v1/post-runwayml-gen3-extend) * [gen3/actone](/docs/api-runwayml-v1/post-runwayml-gen3-actone) > **https://api.useapi.net/v1/runwayml/gen4/upscale** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "assetId": "Required assetId of Gen-3 Alpha or Gen-3 Alpha Turbo video asset you want to upscale", "exploreMode": true, "replyUrl": "Place your call back URL here", "replyRef": "Place your reference id here", "maxJobs": 5, } ``` - `assetId` is **required**. Specify the Gen-4, Gen-4 Turbo, Gen-3 Alpha or Gen-3 Alpha Turbo video assetId you want upscale. Use [GET /assets/?mediaType=video](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of video assets. - `exploreMode` is optional. Set to `true` if you have a Runway [Unlimited plan](https://help.runwayml.com/hc/en-us/articles/18053095835795-Unlimited-plan-details) and wish to execute relaxed generation. You are not charged credits for Explore mode generations. - `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used. Place here your callback URL. API will call the provided `replyUrl` once Runway task completed or failed. Maximum length 1024 characters. We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality. Callback body has the same JSON shape as [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) response. - `replyRef` is optional, place here your reference id which will be stored and returned along with this Runway task response / result. Maximum length 1024 characters. - `maxJobs` is optional, if not provided value for referenced by video assetId account will be used. Valid range: 1…10. Runway has dynamic query capacity and guarantees that, for a given account, at least one job will run — often two, and very rarely, three. If you have a single account linked, keep adding new jobs until you receive a `429` response. Once you get a `429`, wait for xx seconds or until at least one job completes, then try again. If you need to run more jobs in parallel, simply add more Runway accounts. ##### Responses **200** **200 OK** Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId). The generated video `url` can be found in the `artifacts` array of the task with the status `SUCCEEDED`. If you specify the optional parameter [`replyUrl`](/docs/api-runwayml-v1/post-runwayml-gen4-upscale#request-body) the API will call the provided `replyUrl` with task progress updates until the task is complete or fails. ```json { "task": { "taskId": "user:user_id-runwayml:account_email-task:task_uuid", "id": "<uuid>", "name": "<name>", "image": null, "createdAt": "2025-01-10T02:55:10.654Z", "updatedAt": "2025-01-10T02:55:10.691Z", "taskType": "media_upscale", "options": { "name": "<name>", "task_artifact_id": "<uuid>", "exploreMode": true, "asset_url": "https://runway-...mp4", "asset_type": "video", "scale_factor": 4, "video_name": "<video name>", "parent_asset_group_id": "<uuid>", "asset_preview_urls": [ "https://runway-...jpg", "https://runway-...jpg", "https://runway-...jpg", "https://runway-...jpg", "https://runway-...jpg" ] }, "status": "PENDING", "error": null, "progressText": null, "progressRatio": null, "estimatedTimeToStartSeconds": 0, "artifacts": [], "sharedAsset": null, "sourceAssetId": null, "replyUrl": "https://webhook.site/abc", "replyRef": "<your optional reference id>", "code": 200 } } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** ```json { "error": "Unable to retrieve assetId <uuid> (Not found.)", "code": 404 } ``` **412** **412 Insufficient credits** You do not have enough credits to run this task. ```json { "error": "You do not have enough credits to run this task." } ``` **429** **429 Too Many Requests** Wait in a loop for **at least** 10..30 seconds and retry again. There are two possible cases for API response 429: * API query is full and can not accept new gen4/upscale requests. Size of query defined by [`maxJobs` optional parameter](#request-body). ```json { "error": "Account <Runway account email> is busy executing <Account maxJobs> tasks", "runningTasks": { "<Runway account email>": [ { "email": "<Runway account email>", "taskId": "user:user_id-runwayml:account_email-task:task_#1_uuid", "id": "<uuid>", "replyUrl": "<replyUrl if provided>", "replyRef": "<replyRef if provided>" }, { "email": "<Runway account email>", "taskId": "user:user_id-runwayml:account_email-task:task_#N_uuid", "id": "<uuid>", "replyUrl": "<replyUrl if provided>", "replyRef": "<replyRef if provided>" } ] }, "code": 429 } ``` * The API received an HTTP response status 429 from Runway. Runway has dynamic query management and may limit the number of simultaneously executed tasks based on internal service load and policies. ```json { "error": "You have too many tasks running or pending. Please wait for some of them to finish before starting more." } ``` ##### Model The new task, inside `task`, with its `taskId`: poll it with [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) until it finishes, then find the 4K video in `artifacts`. <details markdown="block" class="model-details"> <summary>The new upscale task, field by field</summary> ```typescript { // TypeScript, all fields are optional task: { id: string taskId: string name: string image: any createdAt: string updatedAt: string taskType: string options: { name: string task_artifact_id: string exploreMode: boolean asset_url: string asset_type: string scale_factor: number video_name: string parent_asset_group_id: string asset_preview_urls: string[] } status: string error: { errorMessage: string, reason: string, message: string, moderation_category: string, tally_asimov: boolean }, progressText: string progressRatio: number estimatedTimeToStartSeconds: number artifacts: any[] sharedAsset: any sourceAssetId: any code: number replyUrl: string replyRef: string } } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST "https://api.useapi.net/v1/runwayml/gen4/upscale" \ -d '{"assetId": "…" }' ``` **JavaScript** ``` javascript const assetId = "assetId of video asset"; const apiUrl = `https://api.useapi.net/v1/runwayml/gen4/upscale`; const token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ assetId }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests assetId = "assetId of video asset" apiUrl = f"https://api.useapi.net/v1/runwayml/gen4/upscale" token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } body = { "assetId": f"{assetId}" } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen4-video === Document URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen4-video --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> gen4/video description: "Transform an input video with text prompts and optional image conditioning via POST gen4/video (Gen-4 Aleph) in the useapi.net Runway API v1." parent: Runway API nav_order: 445 --- ## Create a video using Runway Gen-4 Aleph (video-to-video) August 4, 2025 (November 16, 2026) --- [Creating with Aleph](https://help.runwayml.com/hc/en-us/articles/43176400374419-Creating-with-Aleph). Gen-4 Aleph is Runway's video-to-video generation model that allows you to transform an input video using text prompts and optional image conditioning. Please be aware that Runway's moderation system analyzes your video and text prompts and may fail task with moderation message if the prompt is determined to be offensive. Runway monitors the rate and the number of moderated tasks, which may result in your account being suspended when the internal threshold is exceeded. The **account** you use to upload asset(s) via [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets) will also be used to execute the generation. Uploading an asset to a specific account ensures that generation with that asset will occur under the same account. > **https://api.useapi.net/v1/runwayml/gen4/video** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "video_assetId": "Required assetId of video asset", "image_assetId": "Optional assetId of image asset", "text_prompt": "Required text prompt describing the transformation", "seed": 12345678, "exploreMode": true, "replyUrl": "Place your call back URL here", "replyRef": "Place your reference id here", "maxJobs": 5 } ``` - `video_assetId` is **required**. Specify the video assetId you want to transform. The video must have duration, width, and height metadata. Use [GET /assets/?mediaType=video](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of video assets. To upload a new video asset use [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets). - `image_assetId` is optional. Specify an image assetId to use as additional conditioning for the video transformation. Use [GET /assets/?mediaType=image](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of image assets. - `text_prompt` is **required**. Describe the desired transformation or style for the video. [Creating with Aleph](https://help.runwayml.com/hc/en-us/articles/43176400374419-Creating-with-Aleph). Maximum length: 1000 characters. - `seed` is optional. Random seed for reproducible results. Valid range 1…4294967294. - `exploreMode` is optional. Set to `true` if you have a Runway [Unlimited plan](https://help.runwayml.com/hc/en-us/articles/18053095835795-Unlimited-plan-details) and wish to execute relaxed generation. You are not charged credits for Explore mode generations. - `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used. Place here your callback URL. API will call the provided `replyUrl` once Runway task completed or failed. Maximum length 1024 characters. We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality. Callback body has the same JSON shape as [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) response. - `replyRef` is optional, place here your reference id which will be stored and returned along with this Runway task response / result. Maximum length 1024 characters. - `maxJobs` is optional, if not provided value for referenced by video assetId account will be used. Valid range: 1…10. Runway has dynamic query capacity and guarantees that, for a given account, at least one job will run — often two, and very rarely, three. If you have a single account linked, keep adding new jobs until you receive a `429` response. Once you get a `429`, wait for xx seconds or until at least one job completes, then try again. If you need to run more jobs in parallel, simply add more Runway accounts. ##### Responses **200** **200 OK** Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId). The generated video `url` can be found in the `artifacts` array of the task with the status `SUCCEEDED`. If you specify the optional parameter [`replyUrl`](/docs/api-runwayml-v1/post-runwayml-gen4-video#request-body) the API will call the provided `replyUrl` with task progress updates until the task is complete or fails. ```json { "task": { "taskId": "user:user_id-runwayml:account_email-task:task_uuid", "id": "<uuid>", "name": "<name>", "image": null, "createdAt": "2024-08-01T01:02:03.456Z", "updatedAt": "2024-08-01T01:02:03.456Z", "taskType": "gen4_aleph", "options": { "name": "<name>", "text_prompt": "<your text prompt>", "seed": 12345789, "exploreMode": true, "watermark": false, "seconds": 5, "width": 1280, "height": 720, "video": "<input video url>", "images": ["<optional image url>"], "imageAssetIds": ["<optional image asset id>"], "assetGroupId": "<asset group id>", "recordingEnabled": true }, "status": "PENDING", "error": null, "progressText": null, "progressRatio": null, "estimatedTimeToStartSeconds": 0, "artifacts": [], "sharedAsset": null, "replyUrl": "https://webhook.site/abc", "replyRef": "<your optional reference id>", "code": 200 } } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** ```json { "error": "Unable to retrieve assetId <uuid> (Not found.)", "code": 404 } ``` **412** **412 Insufficient credits** You do not have enough credits to run this task. ```json { "error": "You do not have enough credits to run this task." } ``` **429** **429 Too Many Requests** Wait in a loop for **at least** 10..30 seconds and retry again. There are two possible cases for API response 429: * API query is full and can not accept new [gen4/video](#create-a-video-using-runway-gen-4-aleph-video-to-video) requests. Size of query defined by [`maxJobs` optional parameter](#request-body). ```json { "error": "Account <Runway account email> is busy executing <Account maxJobs> tasks", "runningTasks": { "<Runway account email>": [ { "email": "<Runway account email>", "taskId": "user:user_id-runwayml:account_email-task:task_#1_uuid", "id": "<uuid>", "replyUrl": "<replyUrl if provided>", "replyRef": "<replyRef if provided>" }, { "email": "<Runway account email>", "taskId": "user:user_id-runwayml:account_email-task:task_#N_uuid", "id": "<uuid>", "replyUrl": "<replyUrl if provided>", "replyRef": "<replyRef if provided>" } ] }, "code": 429 } ``` * The API received an HTTP response status 429 from Runway. Runway has dynamic query management and may limit the number of simultaneously executed tasks based on internal service load and policies. ```json { "error": "You have too many tasks running or pending. Please wait for some of them to finish before starting more." } ``` ##### Model The new task, inside `task`, with its `taskId`: poll it with [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) until it finishes, then find the video in `artifacts`. <details markdown="block" class="model-details"> <summary>The new video task, field by field</summary> ```typescript { // TypeScript, all fields are optional task: { taskId: string, id: string, name: string, image: string, createdAt: string, updatedAt: string, taskType: string, options: { name: string, text_prompt: string, seed: number, exploreMode: boolean, watermark: boolean, seconds: number, width: number, height: number, video: string, images: string[], imageAssetIds: string[], assetGroupId: string, recordingEnabled: boolean }, status: string, progressText: string, progressRatio: number, estimatedTimeToStartSeconds: number, artifacts: any[], sharedAsset: any, error: { errorMessage: string, reason: string, message: string, moderation_category: string, tally_asimov: boolean }, code: number, replyUrl: string, replyRef: string } } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST "https://api.useapi.net/v1/runwayml/gen4/video" \ -d '{"video_assetId": "…", "text_prompt": "transform this video into a cinematic scene"}' ``` **JavaScript** ``` javascript const video_assetId = "assetId of video asset"; const text_prompt = "transform this video into a cinematic scene"; const apiUrl = `https://api.useapi.net/v1/runwayml/gen4/video`; const token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ video_assetId, text_prompt }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests video_assetId = "assetId of video asset" text_prompt = "transform this video into a cinematic scene" apiUrl = f"https://api.useapi.net/v1/runwayml/gen4/video" token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } body = { "video_assetId": f"{video_assetId}", "text_prompt": f"{text_prompt}" } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen4_5-create === Document URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen4_5-create --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> gen4_5/create description: "Generate Gen-4.5 text-to-video (720p 16:9) or image-to-video clips via POST gen4_5/create in the useapi.net Runway API v1 — parameters and response examples." parent: Runway API nav_order: 410 --- ## Create a video using text prompt or image December 15, 2025 (November 16, 2026) --- Runway [Generate Video » Gen-4.5](https://app.runwayml.com/video-tools/ai-tools/generative-video). Gen-4.5 supports two modes: - **Text-to-Video (T2V)**: Generate 720p 16:9 videos from text prompts - **Image-to-Video (I2V)**: Generate videos from a first image with optional text prompt, supporting multiple aspect ratios Please be aware that Runway's moderation system analyzes your image and text prompts and may fail task with moderation message if the prompt is determined to be offensive. Runway monitors the rate and the number of moderated tasks, which may result in your account being suspended when the internal threshold is exceeded. The **account** you use to upload asset(s) via [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets) will also be used to execute the generation. Uploading an asset to a specific account ensures that generation with that asset will occur under the same account. > **https://api.useapi.net/v1/runwayml/gen4_5/create** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body **Text-to-Video (T2V)** ```json { "email": "Optional Runway account email", "text_prompt": "Required text prompt for T2V", "seconds": 5, "seed": 12345678, "exploreMode": true, "replyUrl": "Place your call back URL here", "replyRef": "Place your reference id here", "maxJobs": 5 } ``` **Image-to-Video (I2V)** ```json { "firstImage_assetId": "Required assetId of first image asset", "text_prompt": "Optional text prompt", "aspect_ratio": "9:16", "seconds": 5, "seed": 12345678, "exploreMode": true, "replyUrl": "Place your call back URL here", "replyRef": "Place your reference id here", "maxJobs": 5 } ``` - `email` is optional. If not specified, the API will randomly select an available account with capacity for load balancing. Use [GET /accounts](/docs/api-runwayml-v1/get-runwayml-accounts) to see the list of linked Runway accounts. Not used when `firstImage_assetId` is provided (account is determined by the asset). - `firstImage_assetId` is optional. When provided, enables **Image-to-Video** mode. Specify the image assetId you want to be present in the **first** frame. Use [GET /assets/?mediaType=image](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of image assets. To upload a new image asset use [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets). - `text_prompt` is **required for T2V**, optional for I2V. Describe your video scene. Maximum length: 5000 characters. - `aspect_ratio` is optional, **I2V only**. Ignored for T2V which is always 16:9. Supported values: `16:9` (default), `9:16`, `1:1`, `4:3`, `3:4`, `21:9`. - `seconds` is optional. Specify desired length of the video in seconds. Supported values: `5` (default), `8`, `10`. - `seed` is optional. Valid range 1…4294967294. - `exploreMode` is optional. Set to `true` if you have a Runway [Unlimited plan](https://help.runwayml.com/hc/en-us/articles/18053095835795-Unlimited-plan-details) and wish to execute relaxed generation. You are not charged credits for Explore mode generations. - `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used. Place here your callback URL. API will call the provided `replyUrl` once Runway task completed or failed. Maximum length 1024 characters. We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality. Callback body has the same JSON shape as [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) response. - `replyRef` is optional, place here your reference id which will be stored and returned along with this Runway task response / result. Maximum length 1024 characters. - `maxJobs` is optional, if not provided value for specified account will be used. Valid range: 1…10. Runway has dynamic query capacity and guarantees that, for a given account, at least one job will run — often two, and very rarely, three. If you have a single account linked, keep adding new jobs until you receive a `429` response. Once you get a `429`, wait for xx seconds or until at least one job completes, then try again. If you need to run more jobs in parallel, simply add more Runway accounts. ##### Responses **200** **200 OK** Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId). The generated video `url` can be found in the `artifacts` array of the task with the status `SUCCEEDED`. If you specify the optional parameter [`replyUrl`](/docs/api-runwayml-v1/post-runwayml-gen4_5-create#request-body) the API will call the provided `replyUrl` with task progress updates until the task is complete or fails. **Text-to-Video Response** ```json { "task": { "taskId": "user:user_id-runwayml:account_email-task:task_uuid", "id": "<uuid>", "name": "<name>", "image": null, "createdAt": "2026-01-23T01:02:03.456Z", "updatedAt": "2026-01-23T01:02:03.456Z", "taskType": "gen4.5", "options": { "name": "<name>", "route": "t2v", "seconds": 5, "text_prompt": "<your text prompt>", "seed": 12345789, "exploreMode": false, "watermark": false, "width": 1280, "height": 720 }, "status": "PENDING", "error": null, "progressText": null, "progressRatio": null, "estimatedTimeToStartSeconds": 0, "artifacts": [], "sharedAsset": null, "replyUrl": "https://webhook.site/abc", "replyRef": "<your optional reference id>", "code": 200 } } ``` **Image-to-Video Response** ```json { "task": { "taskId": "user:user_id-runwayml:account_email-task:task_uuid", "id": "<uuid>", "name": "<name>", "image": null, "createdAt": "2026-01-23T01:02:03.456Z", "updatedAt": "2026-01-23T01:02:03.456Z", "taskType": "gen4.5", "options": { "name": "<name>", "route": "k2v", "seconds": 8, "text_prompt": "<your optional text prompt>", "seed": 12345789, "exploreMode": false, "watermark": false, "keyframes": [ { "image": "<image url>", "timestamp": 0 } ], "width": 720, "height": 1280 }, "status": "PENDING", "error": null, "progressText": null, "progressRatio": null, "estimatedTimeToStartSeconds": 0, "artifacts": [], "sharedAsset": null, "replyUrl": "https://webhook.site/abc", "replyRef": "<your optional reference id>", "code": 200 } } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **412** **412 Insufficient credits** You do not have enough credits to run this task. ```json { "error": "You do not have enough credits to run this task." } ``` **429** **429 Too Many Requests** Wait in a loop for **at least** 10..30 seconds and retry again. There are two possible cases for API response 429: * API query is full and can not accept new [gen4_5/create](#create-a-video-using-text-prompt-or-image) requests. Size of query defined by [`maxJobs` optional parameter](#request-body). ```json { "error": "Account <Runway account email> is busy executing <Account maxJobs> tasks", "runningTasks": { "<Runway account email>": [ { "email": "<Runway account email>", "taskId": "user:user_id-runwayml:account_email-task:task_#1_uuid", "id": "<uuid>", "replyUrl": "<replyUrl if provided>", "replyRef": "<replyRef if provided>" }, { "email": "<Runway account email>", "taskId": "user:user_id-runwayml:account_email-task:task_#N_uuid", "id": "<uuid>", "replyUrl": "<replyUrl if provided>", "replyRef": "<replyRef if provided>" } ] }, "code": 429 } ``` * The API received an HTTP response status 429 from Runway. Runway has dynamic query management and may limit the number of simultaneously executed tasks based on internal service load and policies. ```json { "error": "You have too many tasks running or pending. Please wait for some of them to finish before starting more." } ``` ##### Model The new task, inside `task`, with its `taskId`: poll it with [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) until it finishes, then find the video in `artifacts`. <details markdown="block" class="model-details"> <summary>The new video task, field by field</summary> ```typescript { // TypeScript, all fields are optional task: { taskId: string, id: string, name: string, image: string, createdAt: string, updatedAt: string, taskType: string, options: { name: string, seconds: number, text_prompt: string, seed: number, exploreMode: boolean, watermark: boolean, route: string, // "t2v" for text-to-video, "k2v" for image-to-video keyframes: [{ // I2V only image: string, timestamp: number }], width: number, height: number, assetGroupId: string }, status: string, progressText: string, progressRatio: number, estimatedTimeToStartSeconds: number, artifacts: any[], sharedAsset: any, error: { errorMessage: string, reason: string, message: string, moderation_category: string, tally_asimov: boolean }, code: number, replyUrl: string, replyRef: string } } ``` </details> ##### Examples **Curl (T2V)** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST "https://api.useapi.net/v1/runwayml/gen4_5/create" \ -d '{"text_prompt": "A cinematic shot of a sunset over the ocean"}' ``` **Curl (I2V)** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST "https://api.useapi.net/v1/runwayml/gen4_5/create" \ -d '{"firstImage_assetId": "user:123-runwayml:account@email.com-asset:uuid", "text_prompt": "Camera slowly zooms out", "aspect_ratio": "9:16"}' ``` **JavaScript** ``` javascript // Text-to-Video const text_prompt = "A cinematic shot of a sunset over the ocean"; const apiUrl = `https://api.useapi.net/v1/runwayml/gen4_5/create`; const token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ text_prompt }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); // Image-to-Video const firstImage_assetId = "user:123-runwayml:account@email.com-asset:uuid"; data.body = JSON.stringify({ firstImage_assetId, text_prompt: "Camera slowly zooms out", aspect_ratio: "9:16" }); const i2vResponse = await fetch(apiUrl, data); const i2vResult = await i2vResponse.json(); console.log("i2v response", {i2vResponse, i2vResult}); ``` **Python** ``` python import requests apiUrl = "https://api.useapi.net/v1/runwayml/gen4_5/create" token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } # Text-to-Video body_t2v = { "text_prompt": "A cinematic shot of a sunset over the ocean" } response = requests.post(apiUrl, headers=headers, json=body_t2v) print("T2V:", response, response.json()) # Image-to-Video body_i2v = { "firstImage_assetId": "user:123-runwayml:account@email.com-asset:uuid", "text_prompt": "Camera slowly zooms out", "aspect_ratio": "9:16" } response = requests.post(apiUrl, headers=headers, json=body_i2v) print("I2V:", response, response.json()) ``` === URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen4turbo-create === Document URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-gen4turbo-create --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> gen4turbo/create description: "Generate a Gen-4 Turbo video from a first image and text prompt via POST gen4turbo/create in the useapi.net Runway API v1 — parameters, responses, and a live Try It console." parent: Runway API nav_order: 425 --- ## Create a video using the first image(s) with a text prompt April 7, 2025 (November 16, 2026) --- Runway [Generate Video » Gen-4 Turbo](https://app.runwayml.com/video-tools/ai-tools/generative-video). [Creating with Gen-4](https://help.runwayml.com/hc/en-us/articles/37327109429011-Creating-with-Gen-4). Please take a look at the code provided in the article [Create Runway videos like a Pro](/docs/articles/runway-bash) as it covers all aspects of video generation and downloading of generated videos along with proper handling of corner cases. Please be aware that Runway's moderation system analyzes your image and text prompts and may fail task with moderation message if the prompt is determined to be offensive. Runway monitors the rate and the number of moderated tasks, which may result in your account being suspended when the internal threshold is exceeded. The **account** you use to upload asset(s) via [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets) will also be used to execute the generation. Uploading an asset to a specific account ensures that generation with that asset will occur under the same account. > **https://api.useapi.net/v1/runwayml/gen4turbo/create** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "firstImage_assetId": "Required assetId of first image asset", "text_prompt": "Optional text prompt", "aspect_ratio": "3:4", "seconds": 5, "seed": 12345678 "exploreMode": true, "replyUrl": "Place your call back URL here", "replyRef": "Place your reference id here", "maxJobs": 5 } ``` - `firstImage_assetId` is **required**. Specify the image assetId you want to be present in the **first** frame. Use [GET /assets/?mediaType=image](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of image assets. To upload a new image asset use [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets). - `text_prompt` is optional. Describe your shot. [Creating with Gen-4](https://help.runwayml.com/hc/en-us/articles/37327109429011-Creating-with-Gen-4). Maximum length: 1000 characters. - `aspect_ratio` is optional. Supported values: `16:9` (default), `9:16`, `1:1`, `4:3`, `3:4`, `21:9`. - `seconds` is optional. Specify desired length of the video in seconds. Supported values: `5` (default), `10`. - `seed` is optional. Valid range 1…4294967294. - `exploreMode` is optional. Set to `true` if you have a Runway [Unlimited plan](https://help.runwayml.com/hc/en-us/articles/18053095835795-Unlimited-plan-details) and wish to execute relaxed generation. You are not charged credits for Explore mode generations. - `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used. Place here your callback URL. API will call the provided `replyUrl` once Runway task completed or failed. Maximum length 1024 characters. We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality. Callback body has the same JSON shape as [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) response. - `replyRef` is optional, place here your reference id which will be stored and returned along with this Runway task response / result. Maximum length 1024 characters. - `maxJobs` is optional, if not provided value for referenced by image assetId account will be used. Valid range: 1…10. Runway has dynamic query capacity and guarantees that, for a given account, at least one job will run — often two, and very rarely, three. If you have a single account linked, keep adding new jobs until you receive a `429` response. Once you get a `429`, wait for xx seconds or until at least one job completes, then try again. If you need to run more jobs in parallel, simply add more Runway accounts. ##### Responses **200** **200 OK** Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId). The generated video `url` can be found in the `artifacts` array of the task with the status `SUCCEEDED`. If you specify the optional parameter [`replyUrl`](/docs/api-runwayml-v1/post-runwayml-gen4turbo-create#request-body) the API will call the provided `replyUrl` with task progress updates until the task is complete or fails. ```json { "task": { "taskId": "user:user_id-runwayml:account_email-task:task_uuid", "id": "<uuid>", "name": "<name>", "image": null, "createdAt": "2024-08-01T01:02:03.456Z", "updatedAt": "2024-08-01T01:02:03.456Z", "taskType": "gen4_turbo", "options": { "name": "<name>", "route": "i2v", "seconds": 10, "text_prompt": "<your text prompt>", "seed": 12345789, "exploreMode": true, "watermark": false, "assetGroupName": "Generative Video", "init_image": "<image url>", "width": 832, "height": 1104, "recordingEnabled": true }, "status": "PENDING", "error": null, "progressText": null, "progressRatio": null, "estimatedTimeToStartSeconds": 0, "artifacts": [], "sharedAsset": null, "replyUrl": "https://webhook.site/abc", "replyRef": "<your optional reference id>", "code": 200 } } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** ```json { "error": "Unable to retrieve assetId <uuid> (Not found.)", "code": 404 } ``` **412** **412 Insufficient credits** You do not have enough credits to run this task. ```json { "error": "You do not have enough credits to run this task." } ``` **429** **429 Too Many Requests** Wait in a loop for **at least** 10..30 seconds and retry again. There are two possible cases for API response 429: * API query is full and can not accept new gen4turbo/create requests. Size of query defined by [`maxJobs` optional parameter](#request-body). ```json { "error": "Account <Runway account email> is busy executing <Account maxJobs> tasks", "runningTasks": { "<Runway account email>": [ { "email": "<Runway account email>", "taskId": "user:user_id-runwayml:account_email-task:task_#1_uuid", "id": "<uuid>", "replyUrl": "<replyUrl if provided>", "replyRef": "<replyRef if provided>" }, { "email": "<Runway account email>", "taskId": "user:user_id-runwayml:account_email-task:task_#N_uuid", "id": "<uuid>", "replyUrl": "<replyUrl if provided>", "replyRef": "<replyRef if provided>" } ] }, "code": 429 } ``` * The API received an HTTP response status 429 from Runway. Runway has dynamic query management and may limit the number of simultaneously executed tasks based on internal service load and policies. ```json { "error": "You have too many tasks running or pending. Please wait for some of them to finish before starting more." } ``` ##### Model The new task, inside `task`, with its `taskId`: poll it with [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) until it finishes, then find the video in `artifacts`. <details markdown="block" class="model-details"> <summary>The new video task, field by field</summary> ```typescript { // TypeScript, all fields are optional task: { taskId: string, id: string, name: string, image: string, createdAt: string, updatedAt: string, taskType: string, options: { name: string, seconds: number, text_prompt: string, seed: number, exploreMode: boolean, watermark: boolean, enhance_prompt: boolean, route: string, init_image: string, assetGroupId: string, assetGroupName: string, recordingEnabled: boolean }, status: string, progressText: string, progressRatio: number, estimatedTimeToStartSeconds: number, artifacts: any[], sharedAsset: any, error: { errorMessage: string, reason: string, message: string, moderation_category: string, tally_asimov: boolean }, code: number, replyUrl: string, replyRef: string } } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST "https://api.useapi.net/v1/runwayml/gen4turbo/create" \ -d '{"firstImage_assetId": "…", "text_prompt": "…"}' ``` **JavaScript** ``` javascript const firstImage_assetId = "assetId of image asset"; const text_prompt = "text prompt"; const apiUrl = `https://api.useapi.net/v1/runwayml/gen4turbo/create`; const token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ firstImage_assetId, text_prompt }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests firstImage_assetId = "assetId of image asset" text_prompt = "text prompt" apiUrl = f"https://api.useapi.net/v1/runwayml/gen4turbo/create" token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } body = { "firstImage_assetId": f"{firstImage_assetId}", "text_prompt": f"{text_prompt}" } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-images-create === Document URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-images-create --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> images/create description: "Generate images via 13 models — FLUX 3 (10 refs, 4K), FLUX.2, Nano Banana, GPT Image, Seedream 5, Gen-4 — using POST images/create in the useapi.net Runway API v1." parent: Runway API nav_order: 405 --- ## Images February 17, 2026 (November 16, 2026) --- Unified image generation endpoint supporting multiple AI models: [FLUX 3 Image](https://bfl.ai) `flux-3`, [FLUX.2 Max](https://bfl.ai) `flux-2-max`, [FLUX.2 Klein](https://bfl.ai) `flux-2-klein`, [Nano Banana](https://deepmind.google/models/gemini/flash/) `nano-banana`, [Nano Banana 2](https://deepmind.google/models/gemini/flash/) `nano-banana-2`, [Nano Banana 2 Lite](https://deepmind.google/models/gemini/flash/) `nano-banana-2-lite`, [Nano Banana Pro](https://deepmind.google/models/gemini-image/pro/) `nano-banana-pro`, [GPT Image 1.5](https://platform.openai.com/docs/models/gpt-image-1) `gpt-image-1-5`, [GPT Image 1 Mini](https://platform.openai.com/docs/models/gpt-image-1-mini) `gpt-image-1-mini`, [GPT Image 2](https://openai.com/) `gpt-image-2`, [Seedream 5](https://www.volcengine.com/product/seedream) `seedream-5`, [Gen-4](https://runwayml.com) `gen4`, and [Gen-4 Turbo](https://runwayml.com) `gen4-turbo`. Nano Banana, Nano Banana 2, Nano Banana 2 Lite, and Nano Banana Pro support image references of famous people and minors, unlike [Google Flow](/docs/api-google-flow-v1). Each model has different capabilities, reference image limits, resolution options, and optional parameters. Accounts with a Runway [Unlimited plan](https://help.runwayml.com/hc/en-us/articles/18053095835795-Unlimited-plan-details) can set `exploreMode` to `true` to generate images without using credits. Explore mode generations are queued at lower priority and may take significantly longer — expect 5–15 minutes compared to 10–30 seconds for regular generations. All models except `flux-3` support `exploreMode`. ##### Model Comparison: FLUX 3 FLUX 3 Image is the image model of Black Forest Labs' FLUX 3 family. It returns one image per request and accepts up to 10 reference images. A 1K image costs 7 credits. | Feature | FLUX 3 Image | |---------|:------------:| | Reference images | 0–10 | | Resolution | 1K (default), 2K, 4K, 0.5K, 0.75K | | aspect_ratio | `auto` (default), 21:9, 2:1, 16:9, 3:2, 7:5, 4:3, 5:4, 1:1, 4:5, 3:4, 5:7, 2:3, 9:16, 1:2 | | text_prompt | **required** (max 4000) | | num_images | 1 only | | seed | — | | exploreMode | not available | | Credits per image | 6 at 0.5K / 0.75K, 7 at 1K, 14 at 2K, 81 at 4K | ##### Model Comparison: FLUX.2 | Feature | FLUX.2 Max | FLUX.2 Klein | |---------|:----------:|:------------:| | Reference images | 0–8 | 0–4 | | Resolution | 1K, 2K, 4K, 0.6MP | 1K, 2K, 0.6MP | | aspect_ratio | all incl. 9:21 | all incl. 9:21 | | text_prompt | optional (max 4000) | optional (max 4000) | | seed | Yes | Yes | FLUX.2 uses **ordinal references** in prompts ("subject from image 1, style from image 2, background from image 3"), not `@IMG_N` tags. See the official [FLUX.2 Max prompting guide](https://docs.bfl.ai/guides/prompting_guide_flux2) and FLUX.2 Klein prompting guide for best practices. ##### Model Comparison: Nano Banana | Feature | Nano Banana | Nano Banana 2 | Nano Banana 2 Lite | Nano Banana Pro | |---------|:-----------:|:-------------:|:------------------:|:---------------:| | Reference images | 0–3 | 0–14 | 0–14 | 0–14 | | Resolution | — | 1K, 2K, 4K | — | 1K, 2K, 4K | | aspect_ratio | auto + all but 9:21 | auto + all but 9:21 | auto + all but 9:21 | auto + all but 9:21 | | text_prompt | optional (max 5000) | optional (max 5000) | optional (max 5000) | optional (max 5000) | ##### Model Comparison: GPT Image / Seedream | Feature | GPT Image 1.5 | GPT Image 1 Mini | GPT Image 2 | Seedream 5 | |---------|:-------------:|:----------------:|:-----------:|:----------:| | Reference images | 0–1 | 0–1 | 0–14 | 0–14 | | Resolution | — | — | 1K, 2K, 4K | 2K, 3K | | aspect_ratio | 1:1, 3:2, 2:3 | 1:1, 3:2, 2:3 | all | all except 4:5, 5:4 | | text_prompt | **required** (max 32000) | **required** (max 32000) | **required** (max 32000) | optional (max 4000) | | quality | — | — | `low`, `medium`, `high` | — | ##### Model Comparison: Gen-4 | Feature | Gen-4 | Gen-4 Turbo | |---------|:----:|:----------:| | Reference images | 0–3 | **1–3** (required) | | Resolution | 1080p, 720p | 1080p | | text_prompt | optional (max 1000) | optional (max 1000) | | diversity | Yes | — | | seed | Yes | Yes | | style | Yes | Yes | Please be aware that Runway's moderation system analyzes your image and text prompts and may fail task with moderation message if the prompt is determined to be offensive. Runway monitors the rate and the number of moderated tasks, which may result in your account being suspended when the internal threshold is exceeded. The **account** you use to upload asset(s) via [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets) will also be used to execute the generation. Uploading an asset to a specific account ensures that generation with that asset will occur under the same account. > **https://api.useapi.net/v1/runwayml/images/create** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "model": "nano-banana-pro", "email": "Optional Runway API account email", "text_prompt": "Required text prompt", "aspect_ratio": "16:9", "resolution": "1K", "num_images": 4, "imageAssetId1": "user:user_id-runwayml:account_email-asset:asset_uuid", "exploreMode": true, "replyUrl": "Place your call back URL here", "replyRef": "Place your reference id here", "maxJobs": 5 } ``` - `model` is **required**. Supported values: `flux-3`, `flux-2-max`, `flux-2-klein`, `nano-banana`, `nano-banana-2`, `nano-banana-2-lite`, `nano-banana-pro`, `gpt-image-1-5`, `gpt-image-1-mini`, `gpt-image-2`, `seedream-5`, `gen4`, `gen4-turbo`. See model comparison for details. - `email` is optional, if not provided API will randomly select available [account](/docs/api-runwayml-v1/get-runwayml-accounts). - `text_prompt` describes your image in detail. **Required** for `flux-3`, `gpt-image-1-5`, `gpt-image-1-mini`, and `gpt-image-2`, optional for all other models. Maximum length depends on model: GPT Image family — 32000; Nano Banana family — 5000; FLUX 3, FLUX.2 Max / Klein and Seedream 5 — 4000; Gen-4 / Gen-4 Turbo — 1000. - `aspect_ratio` is optional. Default `auto` for Nano Banana models and FLUX 3, `1:1` for FLUX.2, `16:9` for the rest. Available values depend on model — see model comparison. All values: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9`, `4:5`, `5:4`, `3:2`, `2:3`, `9:21`, `2:1`, `1:2`, `7:5`, `5:7`. Nano Banana models and FLUX 3 also accept `auto` (the default — the model picks the ratio). `2:1`, `1:2`, `7:5` and `5:7` are accepted only by FLUX 3. - FLUX 3: `auto` (default), `21:9`, `2:1`, `16:9`, `3:2`, `7:5`, `4:3`, `5:4`, `1:1`, `4:5`, `3:4`, `5:7`, `2:3`, `9:16`, `1:2` - Nano Banana, Nano Banana 2, Nano Banana 2 Lite, Nano Banana Pro: `auto` (default) plus all values except `9:21` - FLUX.2 Max, FLUX.2 Klein: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9`, `4:5`, `5:4`, `3:2`, `2:3`, `9:21` - GPT Image 1.5, GPT Image 1 Mini: `1:1`, `3:2`, `2:3` - GPT Image 2: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9`, `4:5`, `5:4`, `3:2`, `2:3`, `9:21` - Seedream 5: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9`, `3:2`, `2:3` - `resolution` is optional. Available resolutions depend on model. - FLUX 3: `1K` (default), `2K`, `4K`, `0.5K`, `0.75K` - FLUX.2 Max: `1K` (default), `2K`, `4K`, `0.6MP` - FLUX.2 Klein: `1K` (default), `2K`, `0.6MP` - Gen-4: `1080p` (default), `720p` - Gen-4 Turbo: `1080p` - GPT Image 2: `1K` (default), `2K`, `4K` - Nano Banana 2, Nano Banana Pro: `1K` (default), `2K`, `4K` - Seedream 5: `2K` (default), `3K` - Nano Banana, Nano Banana 2 Lite, GPT Image 1.5, GPT Image 1 Mini: not supported - `num_images` is optional. Supported values: `1` (default), `4`. `flux-3` accepts `1` only. - `imageAssetId1` through `imageAssetId14` are optional. Specify the assetIds of reference images. Use [GET /assets/?mediaType=image](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of image assets. To upload a new image asset use [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets). For Gen-4, Seedream 5, and Nano Banana models, parameters can be referred in the prompt as `@IMG_1`, `@IMG_2`, etc. For **FLUX.2 Max and Klein** use ordinal descriptions instead ("image 1", "image 2", …) — see the [FLUX.2 prompting guide](https://docs.bfl.ai/guides/prompting_guide_flux2). Maximum number of reference images depends on model — see model comparison. - `diversity` is optional. Aesthetic Range, higher values increase the creative variation between generations in a set. Only supported by Gen-4. When using reference images, defaults to 2. Valid range: 1…5. - `seed` is optional. Supported by Gen-4, Gen-4 Turbo, FLUX.2 Max, and FLUX.2 Klein. Valid range 1…4294967294. - `style` is optional. Supported by Gen-4 and Gen-4 Turbo. Supported values: `vivid`, `vivid-warm`, `vivid-cool`, `high-contrast`, `high-contrast-warm`, `high-contrast-cool`, `bw`, `bw-contrast`, `muted-pastel`, `dreamscape`, `nordic-minimal`, `light-anime`, `dark-anime`, `painted-anime`, `3d-cartoon`, `sketch`, `low-angle`, `in-motion`, `terracotta`. - `quality` is optional. Supported only by `gpt-image-2`. Default `high`. Supported values: `low`, `medium`, `high`. - `exploreMode` is optional. Set to `true` if you have a Runway [Unlimited plan](https://help.runwayml.com/hc/en-us/articles/18053095835795-Unlimited-plan-details) and wish to execute relaxed generation. You are not charged credits for Explore mode generations. **Not supported** by `flux-3` — will return 400 if set to `true`. - `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used. Place here your callback URL. API will call the provided `replyUrl` once Runway task completed or failed. Maximum length 1024 characters. We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality. Callback body has the same JSON shape as [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) response. - `replyRef` is optional, place here your reference id which will be stored and returned along with this Runway task response / result. Maximum length 1024 characters. - `maxJobs` is optional, if not provided value for referenced by image assetId account will be used. Valid range: 1…10. Runway has dynamic query capacity and guarantees that, for a given account, at least one job will run — often two, and very rarely, three. If you have a single account linked, keep adding new jobs until you receive a `429` response. Once you get a `429`, wait for xx seconds or until at least one job completes, then try again. If you need to run more jobs in parallel, simply add more Runway accounts. ##### Responses **200** **200 OK** Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId). The generated images can be found in the `artifacts` array of the task with the status `SUCCEEDED`. If you specify the optional parameter [`replyUrl`](/docs/api-runwayml-v1/post-runwayml-images-create#request-body) the API will call the provided `replyUrl` with task progress updates until the task is complete or fails. ```json { "task": { "id": "<uuid>", "name": "nano-banana-pro <your text prompt>", "image": null, "createdAt": "2026-02-17T23:58:27.296Z", "updatedAt": "2026-02-17T23:58:27.423Z", "taskType": "gemini_image", "options": { "name": "nano-banana-pro <your text prompt>", "text_prompt": "<your text prompt>", "reference_images": [ { "tag": "IMG_1", "assetId": "<asset uuid>", "url": "<asset CDN url>" } ], "aspect_ratio": "9:16", "image_size": "1K", "num_images": 1, "assetGroupId": "<uuid>", "creationSource": "tool-mode", "model": "gemini-3-pro-image-preview", "exploreMode": false, "recordingEnabled": true }, "status": "PENDING", "error": null, "progressText": null, "progressRatio": "0", "estimatedTimeToStartSeconds": 0, "artifacts": [], "sharedAsset": null, "sourceAssetId": null, "taskId": "user:user_id-runwayml:account_email-task:task_uuid", "code": 200 } } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **412** **412 Insufficient credits** You do not have enough credits to run this task. ```json { "error": "You do not have enough credits to run this task." } ``` **429** **429 Too Many Requests** Wait in a loop for **at least** 10..30 seconds and retry again. When `exploreMode` is `true` and another explore mode job is still running, the new job will not start until the current one completes. Since explore mode generations can take **5–15 minutes**, you may need to wait significantly longer before retrying. There are two possible cases for API response 429: * API query is full and can not accept new [images/create](#images) requests. Size of query defined by [`maxJobs` optional parameter](#request-body). ```json { "error": "Account <Runway account email> is busy executing <Account maxJobs> tasks", "runningTasks": { "<Runway account email>": [ { "email": "<Runway account email>", "taskId": "user:user_id-runwayml:account_email-task:task_#1_uuid", "id": "<uuid>", "replyUrl": "<replyUrl if provided>", "replyRef": "<replyRef if provided>" } ] }, "code": 429 } ``` * The API received an HTTP response status 429 from Runway. Runway has dynamic query management and may limit the number of simultaneously executed tasks based on internal service load and policies. ```json { "error": "You have too many tasks running or pending. Please wait for some of them to finish before starting more." } ``` ##### Model The new task with its `taskId`: poll it with [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) until it finishes, then find the images in `artifacts`. <details markdown="block" class="model-details"> <summary>The new image task, field by field</summary> ```typescript { // TypeScript, all fields are optional taskId: string, id: string, name: string, image: string, createdAt: string, updatedAt: string, taskType: string, options: { name: string, text_prompt: string, aspect_ratio: string, num_images: number, exploreMode: boolean, seed: number, diversity: number, style: string, width: number, height: number, flip: boolean, model: string, image_size: string, reference_images: { assetId: string, url: string, tag: string }[], creationSource: string, assetGroupId: string, recordingEnabled: boolean }, status: string, progressText: string, progressRatio: number, estimatedTimeToStartSeconds: number, artifacts: any[], sharedAsset: any, error: { errorMessage: string, reason: string, message: string, moderation_category: string, tally_asimov: boolean }, code: number, replyUrl: string, replyRef: string } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST "https://api.useapi.net/v1/runwayml/images/create" \ -d '{"model": "nano-banana-pro", "text_prompt": "…"}' ``` **JavaScript** ``` javascript const model = "nano-banana-pro"; const text_prompt = "text prompt"; const apiUrl = `https://api.useapi.net/v1/runwayml/images/create`; const token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ model, text_prompt }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests model = "nano-banana-pro" text_prompt = "text prompt" apiUrl = f"https://api.useapi.net/v1/runwayml/images/create" token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } body = { "model": f"{model}", "text_prompt": f"{text_prompt}" } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-lipsync-create === Document URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-lipsync-create --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> lipsync/create description: "Create a lip-sync video where a face speaks AI-generated or uploaded audio via POST lipsync/create in the useapi.net Runway API v1 — 28+ languages supported." parent: Runway API nav_order: 800 --- ## Create Lip Sync Video August 8, 2024 (November 16, 2026) --- Runway [AI Tools » Audio tools » Lip Sync Video](https://app.runwayml.com/video-tools/ai-tools/subtitles). Please be aware that Runway's moderation system analyzes your voice text (parameter `voice_text`) and may fail task with moderation message if the prompt is determined to be offensive. Runway monitors the rate and the number of moderated tasks, which may result in your account being suspended when the internal threshold is exceeded. The **account** you use to upload asset(s) via [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets) will also be used to execute the generation. Uploading an asset to a specific account ensures that generation with that asset will occur under the same account. > **https://api.useapi.net/v1/runwayml/lipsync/create** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "image_assetId": "Optional assetId of image asset", "video_assetId": "Optional assetId of video asset", "audio_assetId": "Optional assetId of audio asset", "voiceId": "Optional voiceId from lipsync/voices endpoint", "voice_text": "Optional lipsync text", "model_id": "Optional voice model", "exploreMode": true, "replyUrl": "Place your call back URL here", "replyRef": "Place your reference id here", "maxJobs": 5, } ``` - `image_assetId` is optional. Specify the image assetId you want to be present in the first frame. Use [GET /assets/?mediaType=image](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of image assets. To upload a new image asset use [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets). - `video_assetId` is optional. Specify the video assetId you want to be present in the first frame. Use [GET /assets/?mediaType=video](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of video assets. To upload a new video asset use [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets). - `audio_assetId` is optional. Specify an audio assetId you want to lip sync with provided above image or video. Use [GET /assets/?mediaType=audio](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of audio assets. To upload a new audio asset use [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets). - `voiceId` is optional. Specify AI voiceId used read `voice_text` to lip sync with provided above image or video. Use [GET lipsync/voices](/docs/api-runwayml-v1/get-runwayml-lipsync-voices) to see the list of voices. - `voice_text` is optional. Specify text to lip sync with provided above image or video. - `model_id` is optional. Specify [AI voice model](https://help.elevenlabs.io/hc/en-us/articles/17883183930129-What-models-do-you-offer-and-what-is-the-difference-between-them). Supported values: `eleven_multilingual_v1` (default) and `eleven_multilingual_v2` (28+ languages). - `exploreMode` is optional. Set to `true` if you have a Runway [Unlimited plan](https://help.runwayml.com/hc/en-us/articles/18053095835795-Unlimited-plan-details) and wish to execute relaxed generation. You are not charged credits for Explore mode generations. - `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used. Place here your callback URL. API will call the provided `replyUrl` once Runway task completed or failed. Maximum length 1024 characters. We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality. Callback body has the same JSON shape as [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) response. - `replyRef` is optional, place here your reference id which will be stored and returned along with this Runway task response / result. Maximum length 1024 characters. - `maxJobs` is optional, if not provided value for referenced by image/video assetId account will be used. Valid range: 1…10. Runway has dynamic query capacity and guarantees that, for a given account, at least one job will run — often two, and very rarely, three. If you have a single account linked, keep adding new jobs until you receive a `429` response. Once you get a `429`, wait for xx seconds or until at least one job completes, then try again. If you need to run more jobs in parallel, simply add more Runway accounts. ##### Responses **200** **200 OK** Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId). The generated video `url` can be found in the `artifacts` array of the task with the status `SUCCEEDED`. If you specify the optional parameter [`replyUrl`](/docs/api-runwayml-v1/post-runwayml-gen3-create#request-body) the API will call the provided `replyUrl` with task progress updates until the task is complete or fails. ```json { "taskId": "user:user_id-runwayml:account_email-task:task_uuid", "id": "<uuid>", "name": "<name>", "image": null, "createdAt": "2024-08-01T01:02:03.456Z", "updatedAt": "2024-08-01T01:02:03.456Z", "taskType": "lipsync", "options": { "name": "<name>", "exploreMode": true, "paid_user_watermark_override": false, "video": "<video url>", "video_asset_id": "<video asset uuid>", "audio": "<audio ulr>" }, "status": "PENDING", "error": null, "progressText": null, "progressRatio": null, "estimatedTimeToStartSeconds": 0, "artifacts": [], "sharedAsset": null, "code": 200, "replyUrl": "https://webhook.site/abc", "replyRef": "<your optional reference id>" } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** ```json { "error": "Unable to retrieve assetId <uuid> (Not found.)", "code": 404 } ``` **412** **412 Insufficient credits** You do not have enough credits to run this task. ```json { "error": "You do not have enough credits to run this task." } ``` **429** **429 Too Many Requests** Wait in a loop for **at least** 10..30 seconds and retry again. There are two possible cases for API response 429: * API query is full and can not accept new [lipsync/create](#create-lip-sync-video) requests. Size of query defined by [`maxJobs` optional parameter](#request-body). ```json { "error": "Account <Runway account email> is busy executing <Account maxJobs> tasks", "runningTasks": { "<Runway account email>": [ { "email": "<Runway account email>", "taskId": "user:user_id-runwayml:account_email-task:task_#1_uuid", "id": "<uuid>", "replyUrl": "<replyUrl if provided>", "replyRef": "<replyRef if provided>" }, { "email": "<Runway account email>", "taskId": "user:user_id-runwayml:account_email-task:task_#N_uuid", "id": "<uuid>", "replyUrl": "<replyUrl if provided>", "replyRef": "<replyRef if provided>" } ] }, "code": 429 } ``` * The API received an HTTP response status 429 from Runway. Runway has dynamic query management and may limit the number of simultaneously executed tasks based on internal service load and policies. ```json { "error": "You have too many tasks running or pending. Please wait for some of them to finish before starting more." } ``` ##### Model The new task with its `taskId`: poll it with [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) until it finishes, then find the video in `artifacts`. <details markdown="block" class="model-details"> <summary>The new video task, field by field</summary> ```typescript { // TypeScript, all fields are optional taskId: string, id: string, name: string, image: string, createdAt: string, updatedAt: string, taskType: string, options: { name: string, exploreMode: boolean, paid_user_watermark_override: boolean, image: string, image_asset_id: string, video: string, video_asset_id: string, audio: string, audio_asset_id: string, gen_audio_options: { name: string, text: string, voice_id: string, model_id: string } }, status: string, progressText: string, progressRatio: number, estimatedTimeToStartSeconds: number, artifacts: any[], sharedAsset: any, error: { errorMessage: string, reason: string, message: string, moderation_category: string, tally_asimov: boolean }, code: number, replyUrl: string, replyRef: string } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST "https://api.useapi.net/v1/runwayml/lipsync/create" \ -d '{"image_assetId": "…", "audio_assetId": "…"}' ``` **JavaScript** ``` javascript const image_assetId = "assetId of image asset"; const audio_assetId = "assetId of audio asset"; const apiUrl = `https://api.useapi.net/v1/runwayml/lipsync/create`; const token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ image_assetId, audio_assetId }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests image_assetId = "assetId of image asset" audio_assetId = "assetId of audio asset" apiUrl = f"https://api.useapi.net/v1/runwayml/lipsync/create" token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } body = { "image_assetId": f"{image_assetId}", "audio_assetId": f"{audio_assetId}" } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-videos-create === Document URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-videos-create --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/create description: "Generate video from 25 models — Wan 3.0 (30s, 20 refs), MiniMax H3, FLUX 3 extend, Seedance 2.5, Kling O3 — via POST videos/create in the useapi.net Runway API." parent: Runway API nav_order: 406 --- ## Videos March 5, 2026 (November 16, 2026) --- Unified video generation endpoint supporting multiple AI models: [Seedance 2.5](https://seed.bytedance.com/) `seedance-2-5`, [Seedance 2.0](https://seed.bytedance.com/) `seedance-2`, [Seedance 2.0 Fast](https://seed.bytedance.com/) `seedance-2-fast`, [Seedance 2.0 Mini](https://seed.bytedance.com/) `seedance-2-mini`, [Wan 3.0](https://wan.video/) `wan-3.0`, [Wan 3.0 Prime](https://wan.video/) `wan-3.0-prime`, [MiniMax H3](https://hailuoai.video) `minimax-h3`, [MiniMax H3 Max](https://hailuoai.video) `minimax-h3-max`, [FLUX 3](https://bfl.ai) `flux-3`, [Grok Imagine 1.5](https://grok.com/imagine) `grok-imagine-1.5`, [HappyHorse 1.0](https://fal.ai/happyhorse-1.0) `happyhorse-1.0`, [Kling O3 4K](https://klingai.com/) `kling-o3-4k`, [Kling O3 Pro](https://klingai.com/) `kling-o3-pro`, [Kling O3 Standard](https://klingai.com/) `kling-o3-standard`, [Kling 3.0 Pro](https://klingai.com/) `kling-3.0-pro`, [Kling 3.0 Standard](https://klingai.com/) `kling-3.0-standard`, [Kling 3.0 Motion Control](https://klingai.com/) `kling-3.0-motion-control`, [Kling 2.6 Pro](https://klingai.com/) `kling-2.6-pro`, [Kling 2.6 I2V](https://klingai.com/) `kling-2.6-i2v`, [Wan 2.6 Flash](https://wan.video/) `wan-2.6-flash`, [Wan 2.2 Animate](https://github.com/Wan-Video/Wan2.2) `wan-2.2-animate`, [Veo 3.1](https://deepmind.google/models/veo/) `veo-3.1`, [Gen-4.5](https://runwayml.com) `gen4.5`, [Gen-4](https://runwayml.com) `gen4`, and [Gen-4 Turbo](https://runwayml.com) `gen4-turbo`. Sora 2 is no longer available: OpenAI shut it down on September 24, 2026. Each model has different capabilities, duration options, aspect ratios, resolution options, and reference image support. Accounts with a Runway [Unlimited plan](https://help.runwayml.com/hc/en-us/articles/18053095835795-Unlimited-plan-details) can set `exploreMode` to `true` to generate videos without using credits. Explore mode generations are queued at lower priority and may take significantly longer. Not all models support `exploreMode` — see [model comparison](#model-comparison-gen-45--gen-4) for details. Generation takes ~10 minutes on average. Up to two generations can usually run in parallel per account. Gen-4 Turbo and Veo 3.1 are notably faster (~1–2 min). ##### Model Comparison: Seedance Seedance on Runway supports real-people faces and generally applies lighter content moderation than the [Dreamina](/docs/api-dreamina-v1) version of the same model. Seedance 2.5 is the newest generation and the most capable: video up to 30 seconds, 1080p, far larger reference budgets, a much longer prompt, a choice of output container, and Edit Video, which edits a video you upload or extends it forwards or backwards (`video_mode`). It costs 20 credits/second at 480p and 30 at 720p, less than the flat 36 of `seedance-2`, and 68 at 1080p. `seedance-2` and `seedance-2-fast` accept identical request parameters and differ only in `model`, billing rate, and queue behavior. `seedance-2-fast` costs roughly 20% fewer credits per second than `seedance-2` and trades some quality for speed. `seedance-2-mini` is the cheapest of the family at 16 credits/second, the same rate at either resolution, but it is not a drop-in for the other two — it offers no 1080p and defaults to 720p rather than 480p. | Feature | Seedance 2.5 | Seedance 2.0 / 2.0 Fast | Seedance 2.0 Mini | |---------|:------------:|:-----------------------:|:-----------------:| | Duration | 4–30s, or `0` = Auto | 4–15s | 4–15s | | aspect_ratio | 16:9 (default), 9:16, 1:1, 4:3, 3:4, 21:9, `auto` | 16:9 (default), 9:16, 1:1, 4:3, 3:4, 21:9 | 16:9 (default), 9:16, 1:1, 4:3, 3:4, 21:9 | | Resolution | 720p (default), 480p, 1080p | 480p (default), 720p, 1080p | 720p (default), 480p | | Reference images (multi-ref mode) | 0–30 | 0–9 | 0–9 | | Reference videos (multi-ref mode) | 0–10 | 0–3 | 0–3 | | Reference audio (multi-ref mode) | 0–10 | 0–3 | 0–3 | | Combined references (multi-ref mode) | up to 50 total | up to 9 total | up to 9 total | | Reference video — duration | ≤ 31s per video | ≤ 16s per video | ≤ 16s per video | | Reference video — max resolution | no limit applied | ≤ 720p (longest side ≤ 1280 px) | ≤ 720p (longest side ≤ 1280 px) | | Reference audio — duration | 1.8–30s per clip | ≤ 15s combined | ≤ 15s combined | | Reference audio — requires image or video ref | no | yes | yes | | Keyframe mode | `startFrameAssetId` (required), `endFrameAssetId` (optional, requires `startFrameAssetId`) | `startFrameAssetId` (required), `endFrameAssetId` (optional, requires `startFrameAssetId`) | `startFrameAssetId` (required), `endFrameAssetId` (optional, requires `startFrameAssetId`) | | Keyframe ↔ multi-ref | mutually exclusive in a single request | mutually exclusive in a single request | mutually exclusive in a single request | | text_prompt | optional, 15000 chars | optional, 3500 chars | optional, 3500 chars | | audio | on (default) | on (default) | on (default) | | output_format | `mp4` (default) or `mov` | not supported | not supported | | Edit Video (`video_mode`) | `edit` or `extend` the video in `videoAssetId` | not supported | not supported | | Drafts | `draft` renders a 480p preview, `draftTaskId` re-renders it at 1080p within 7 days | not supported | not supported | | endFrame | yes (dedicated `endFrameAssetId` field) | yes (dedicated `endFrameAssetId` field) | yes (dedicated `endFrameAssetId` field) | | exploreMode | yes, but 480p / 720p only, duration is capped at 15s, Auto is unavailable, and `video_mode` `edit` is unavailable | yes (480p / 720p only — **1080p requires Credits Mode**) | yes | | Credits per second | 20 at 480p, 30 at 720p, 68 at 1080p | 36 (`seedance-2`), 29 (`seedance-2-fast`) | 16 at either resolution | | Typical generation time (exploreMode) | not yet measured | ~10 min total (queue ~7–9 min + render ~1.5–4 min), `seedance-2-fast` comparable but typically faster | not yet measured | In Explore mode, Seedance 2.5 restricts five things: 1080p is unavailable, the output is capped at 15 seconds, `duration: 0` (Auto) is rejected, the combined duration of all reference videos must stay within 15 seconds, and `video_mode` `edit` is unavailable (`extend` works). All of them are Explore-only — switch to Credits Mode for the full range. ##### Model Comparison: Grok Grok Imagine 1.5 is xAI's image-to-video model wrapped by Runway. | Feature | Grok Imagine 1.5 | |---------|:----------------:| | Duration | 3–15s | | aspect_ratio | 16:9, 9:16, 1:1, 4:3, 3:4, 2:3, 3:2 | | Resolution | 480p (default), 720p | | Reference image | **1, required** — `imageAssetId1` only (used as the first frame) | | text_prompt | optional, 2500 chars | | audio | not supported | | Keyframe / multi-ref / video / audio refs | not supported | | exploreMode | yes | ##### Model Comparison: Wan 3.0 Wan 3.0 is Alibaba's multi-modal video model. It generates up to 30 seconds from text, from keyframes, or from a mix of up to 10 reference images, 5 reference videos and 5 reference audio clips. `wan-3.0-prime` is the faster tier and accepts exactly the same parameters. Audio and references do not change the price, only resolution and duration do. | Feature | Wan 3.0 | Wan 3.0 Prime | |---------|:-------:|:-------------:| | Duration | 2–30s (default 5), or `0` = Auto | 2–30s (default 5), or `0` = Auto | | aspect_ratio | `auto` (default), 16:9, 4:3, 1:1, 3:4, 9:16 | `auto` (default), 16:9, 4:3, 1:1, 3:4, 9:16 | | Resolution | 1080p (default), 720p, 480p | 1080p (default), 720p, 480p | | Keyframe mode | `startFrameAssetId` + optional `endFrameAssetId` (requires `startFrameAssetId`) | `startFrameAssetId` + optional `endFrameAssetId` (requires `startFrameAssetId`) | | Reference images (multi-ref mode) | 0–10 | 0–10 | | Reference videos (multi-ref mode) | 0–5, ≤ 15s combined | 0–5, ≤ 15s combined | | Reference audio (multi-ref mode) | 0–5, each ≥ 2s, ≤ 15s combined | 0–5, each ≥ 2s, ≤ 15s combined | | Keyframe ↔ multi-ref | mutually exclusive in a single request | mutually exclusive in a single request | | text_prompt | **required**, 20000 chars | **required**, 20000 chars | | audio | on (default) | on (default) | | exploreMode | not available | not available | | Credits per second | 5 at 480p, 10 at 720p, 20 at 1080p | ≈7 at 480p, 14 at 720p, 28 at 1080p (5s = 34 / 70 / 140) | With `duration: 0` (Auto) the model picks the length. Auto is billed up to the 30-second ceiling and the unused remainder is refunded. ##### Model Comparison: MiniMax H3 MiniMax H3 (Hailuo 3) generates 5–15 seconds at up to 2K from text, from keyframes, or from up to 9 reference images, 3 reference videos and 3 reference audio clips. MiniMax H3 Max is a separate, cheaper model with first/last frame support, a prompt-expansion setting and a seed, but no references and no aspect ratio. MiniMax's content filter is strict with real people in reference images and videos, so such requests are more likely to fail moderation than on other models. | Feature | MiniMax H3 | MiniMax H3 Max | |---------|:----------:|:--------------:| | Duration | 5–15s (default 5) | 5–15s (default 5) | | aspect_ratio | `auto` (default), 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 | not supported | | Resolution | 2K (default), 768p | 768p (default), 480p | | Keyframe mode | `startFrameAssetId` + optional `endFrameAssetId` (requires `startFrameAssetId`) | `startFrameAssetId` + optional `endFrameAssetId` (requires `startFrameAssetId`), each frame ≥ 256 px per side | | Reference images (multi-ref mode) | 0–9 | not supported | | Reference videos (multi-ref mode) | 0–3, each 2–15s, ≤ 15s combined | not supported | | Reference audio (multi-ref mode) | 0–3, each 2–15s, ≤ 15s combined | not supported | | Combined references (multi-ref mode) | up to 12 total | — | | Reference audio — requires image or video ref | yes | — | | Keyframe ↔ multi-ref | mutually exclusive in a single request | — | | text_prompt | **required**, 6000 chars | **required**, 6000 chars | | audio | no toggle | no toggle | | prompt_expansion | — | `balanced` (default), `disabled`, `quality` | | seed | — | yes | | exploreMode | not available | not available | | Credits per second | 10 at 768p, 15 at 2K (5s = 50 / 75) | 3 at 480p, 4.8 at 768p (5s = 15 / 24) | ##### Model Comparison: FLUX 3 FLUX 3 is Black Forest Labs' video model. It generates 5–20 seconds from text, optionally starting from a first frame. It can also extend an existing video: pass the source clip (up to 15 seconds) as `videoAssetId` and the model continues it. | Feature | FLUX 3 | |---------|:------:| | Duration | 5–20s (default 5), or `0` = Auto | | aspect_ratio | `auto` (default), 21:9, 2:1, 16:9, 4:3, 1:1, 3:4, 9:16 | | Resolution | 720p (default), 1080p | | Start frame | `startFrameAssetId` (optional) — no end frame | | Reference images | not supported | | Extend | `videoAssetId` (source ≤ 15s), cannot be combined with `startFrameAssetId` | | text_prompt | **required**, 5000 chars | | audio | on (default) | | exploreMode | not available | | Credits per second | 17 at 720p, 29 at 1080p (5s = 85 / 145) | | Credits per second — extend | 41 at 720p, 53 at 1080p (5s = 205 / 265) | With `duration: 0` (Auto) the model picks the length, billed up to the 20-second ceiling. ##### Model Comparison: HappyHorse | Feature | HappyHorse 1.0 | |---------|:--------------:| | Duration | 3–15s | | aspect_ratio | 16:9, 9:16, 1:1, 4:3, 3:4 | | Resolution | 720p (default), 1080p | | Reference images | 0 (T2V) or **1** (I2V — first frame) — `imageAssetId1` only | | text_prompt | optional, 2500 chars | | exploreMode | yes | | Typical generation time (exploreMode) | ~10 min total at 720p (queue ~8 min + render ~1.5 min); up to ~22 min at 1080p/15s | ##### Model Comparison: Kling | Feature | Kling 3.0 Pro | Kling 3.0 Standard | Kling 2.6 Pro | Kling 2.6 I2V | |---------|:------------:|:------------------:|:-------------:|:-------------:| | Duration | 5s, 10s, 15s | 5s, 10s, 15s | 5s, 10s | 5s, 10s | | aspect_ratio | 16:9, 9:16, 1:1 | 16:9, 9:16, 1:1 | 16:9, 9:16 | — | | Resolution (T2V) | auto | auto | auto | — | | Reference images | 0–2 | 0–2 | 0–1 | **1** (required) | | text_prompt | optional, 2500 chars | optional, 2500 chars | **required**, 2500 chars | **required**, 2500 chars | | audio | on (default) | on (default) | on (default) | on (default) | | endFrame | yes | yes | — | — | | multishot | 2–5 shots | 2–5 shots | — | — | | exploreMode | yes | yes | yes | yes | ##### Model Comparison: Kling O3 Kling O3 is an omni video model with three workflows per tier — **Frames**, **Multishot**, and **Edit Video**. The three tiers (`kling-o3-4k`, `kling-o3-pro`, `kling-o3-standard`) differ only in output resolution and credit cost; `kling-o3-4k` does not support Edit Video. - **Frames** — text-to-video and/or up to 7 reference images. A `startFrameAssetId` (first frame) may be combined with reference images; `endFrameAssetId` requires `startFrameAssetId` and **cannot** be combined with reference images. - **Multishot** — 2–6 shots via `multishot_prompt_N` / `multishot_duration_N` (each shot 3–12 s, total ≤ 15 s). Reference images from `imageAssetId1`..`imageAssetId7` are bound to a shot by referencing them as `@IMG_N` in that shot's prompt. - **Edit Video** (`kling-o3-pro` / `kling-o3-standard` only) — transform an existing video: `videoAssetId` (source **≤ 10 s**) plus up to 4 reference images. The output duration tracks the source video length. | Feature | Kling O3 4K | Kling O3 Pro | Kling O3 Standard | |---------|:-----------:|:------------:|:-----------------:| | Duration (Frames) | 5s, 10s, 15s | 5s, 10s, 15s | 5s, 10s, 15s | | aspect_ratio | 16:9, 9:16, 1:1 | 16:9, 9:16, 1:1 | 16:9, 9:16, 1:1 | | Resolution (derived from aspect_ratio) | 3840×2160 / 2160×3840 / 2880×2880 | 1920×1080 / 1080×1920 / 1440×1440 | 1280×720 / 720×1280 / 960×960 | | Reference images | 0–7 | 0–7 | 0–7 | | text_prompt | optional, 2500 chars | optional, 2500 chars | optional, 2500 chars | | audio | on (default) | on (default) | on (default) | | Keyframes | `startFrameAssetId` + optional `endFrameAssetId` | `startFrameAssetId` + optional `endFrameAssetId` | `startFrameAssetId` + optional `endFrameAssetId` | | multishot | 2–6 shots (per-shot refs) | 2–6 shots (per-shot refs) | 2–6 shots (per-shot refs) | | Edit Video | — | yes (`videoAssetId` ≤ 10 s + ≤ 4 refs) | yes (`videoAssetId` ≤ 10 s + ≤ 4 refs) | | exploreMode | yes | yes | yes | | Typical generation time (exploreMode) | ~11 min total (queue ~8 min + render ~3 min) | ~11 min total (queue ~8 min + render ~3 min) | ~8 min total (queue ~7 min + render ~1 min) | ##### Model Comparison: Kling Motion Control Character animation via motion transfer. The character image (`imageAssetId1`) is animated to mimic the gestures and motion of the performance video (`videoAssetId`). Output dimensions inherit from the character image; output duration inherits from the performance video. | Feature | Kling 3.0 Motion Control | |---------|:------------------------:| | Reference image (`imageAssetId1`) | **1** (required) — character to be animated | | Reference video (`videoAssetId`) | **1** (required) — performance / motion source, **3 ≤ duration ≤ 30 s** | | Resolution | 720p (default, std mode), 1080p (pro mode) | | Duration | inherited from reference video — `duration` not accepted | | aspect_ratio | inherited from character image — `aspect_ratio` not accepted | | `characterOrientation` | `image` (default) or `video` | | `audio` | on (default) — keeps the original audio from the reference video; set `false` for silent output | | text_prompt | optional, 2500 chars (e.g. "Motion description") | | exploreMode | yes | | Typical generation time (exploreMode) | ~18 min total (queue ~10 min + render ~8 min) | ##### Model Comparison: Wan | Feature | Wan 2.6 Flash | Wan 2.2 Animate | |---------|:-------------:|:---------------:| | Duration | 5s, 10s, 15s | auto | | aspect_ratio | 16:9, 9:16, 1:1 | 16:9, 9:16, 1:1, 4:3, 3:4 | | Resolution | 720p, 1080p | — | | Reference images | **1** (required) | **1** (required) | | Reference video | — | **1** (required) | | text_prompt | **required**, 1500 chars | — | | audio | on (default) | — | | exploreMode | yes | yes | ##### Model Comparison: Veo 3.1 | Feature | Veo 3.1 | |---------|:-------:| | Duration | 4s, 6s, 8s | | aspect_ratio | 16:9, 9:16 | | Resolution | 720p, 1080p | | Reference images | 0–2 | | text_prompt | optional, 5000 chars | | audio | on (default) | | endFrame | yes | | exploreMode | **no** | ##### Model Comparison: Gen-4.5 / Gen-4 | Feature | Gen-4.5 | Gen-4 | Gen-4 Turbo | |---------|:-------:|:-----:|:-----------:| | Duration | 2–10s | 5s, 10s | 5s, 10s | | aspect_ratio (T2V) | 16:9 | all | all | | aspect_ratio (I2V) | all | all | all | | Resolution | — | 720p | 720p | | Reference images | 0–1 | **1** (required) | **1** (required) | | text_prompt | optional, 5000 chars | **required**, 1000 chars | **required**, 1000 chars | | seed | auto | auto | auto | | audio | on (default) | — | — | | exploreMode | yes | yes | yes | Please be aware that Runway's moderation system analyzes your image and text prompts and may fail task with moderation message if the prompt is determined to be offensive. Runway monitors the rate and the number of moderated tasks, which may result in your account being suspended when the internal threshold is exceeded. The **account** you use to upload asset(s) via [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets) will also be used to execute the generation. Uploading an asset to a specific account ensures that generation with that asset will occur under the same account. > **https://api.useapi.net/v1/runwayml/videos/create** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "model": "gen4.5", "email": "Optional Runway API account email", "text_prompt": "A cinematic aerial shot of a coastal city at golden hour", "duration": 5, "aspect_ratio": "16:9", "exploreMode": true, "replyUrl": "Place your call back URL here", "replyRef": "Place your reference id here", "maxJobs": 5 } ``` - `model` is **required**. Supported values: `seedance-2-5`, `seedance-2`, `seedance-2-fast`, `seedance-2-mini`, `wan-3.0`, `wan-3.0-prime`, `minimax-h3`, `minimax-h3-max`, `flux-3`, `grok-imagine-1.5`, `happyhorse-1.0`, `kling-o3-4k`, `kling-o3-pro`, `kling-o3-standard`, `kling-3.0-pro`, `kling-3.0-standard`, `kling-3.0-motion-control`, `kling-2.6-pro`, `kling-2.6-i2v`, `wan-2.6-flash`, `wan-2.2-animate`, `veo-3.1`, `gen4.5`, `gen4`, `gen4-turbo`. See [model comparison](#model-comparison-gen-45--gen-4) for details. - `email` is optional, if not provided API will randomly select available [account](/docs/api-runwayml-v1/get-runwayml-accounts). - `text_prompt` describes your video in detail. **Required** for `wan-3.0`, `wan-3.0-prime`, `minimax-h3`, `minimax-h3-max`, `flux-3`, `gen4`, `gen4-turbo`, `kling-2.6-pro`, `kling-2.6-i2v`, and `wan-2.6-flash`. Not supported for `wan-2.2-animate`. Optional for all other models. Maximum length varies by model — 1000–5000 characters for most (5000 for `flux-3`), 20000 for `wan-3.0` / `wan-3.0-prime`, 15000 for `seedance-2-5`, 6000 for `minimax-h3` / `minimax-h3-max`, 3500 for `seedance-2` / `seedance-2-fast` / `seedance-2-mini`, and 2500 for `grok-imagine-1.5`, `kling-3.0-motion-control`, `happyhorse-1.0`, and the `kling-o3-*` models. For the `kling-o3-*` models, prompts may reference uploaded assets by slot using `@IMG_1`..`@IMG_7`. - `duration` is optional. Default is the first supported value for the model, except `5` for Wan 3.0 / Wan 3.0 Prime and FLUX 3. - Seedance 2.5: 4–30, or `0` for Auto (the model picks the length). Auto bills up to the 30s ceiling and refunds the unused remainder. - Wan 3.0 / Wan 3.0 Prime: 2–30 (default 5), or `0` for Auto. Auto bills up to the 30s ceiling and refunds the unused remainder. - MiniMax H3 / MiniMax H3 Max: 5–15 - FLUX 3: 5–20 (default 5), or `0` for Auto. Auto bills up to the 20s ceiling. - Seedance 2.0 / Seedance 2.0 Fast / Seedance 2.0 Mini: 4–15 - Grok Imagine 1.5: 3–15 - HappyHorse 1.0: 3–15 - Kling O3 4K/Pro/Standard: `5`, `10`, `15` (Frames). For multishot, total duration is the sum of the per-shot durations. For Edit Video, duration is derived from the source video and `duration` is ignored. - Kling 3.0 Pro/Standard: `5`, `10`, `15` - Kling 3.0 Motion Control: not supported (output duration inherits from the reference video) - Kling 2.6 Pro, Kling 2.6 I2V: `5`, `10` - Wan 2.6 Flash: `5`, `10`, `15` - Wan 2.2 Animate: not supported (auto) - Veo 3.1: `4`, `6`, `8` - Gen-4.5: 2–10 (continuous range) - Gen-4, Gen-4 Turbo: `5`, `10` - `aspect_ratio` is optional. Default is `16:9` for the Seedance family and varies for other models. Available values depend on model — see [model comparison](#model-comparison-gen-45--gen-4). `seedance-2-5`, `wan-3.0`, `wan-3.0-prime`, `minimax-h3` and `flux-3` also accept `auto`, which lets the model choose the framing. `auto` is the default for all of them except `seedance-2-5`. `flux-3` also accepts `2:1`. `minimax-h3-max` does not accept `aspect_ratio`. - `resolution` is optional. Available resolutions depend on model. - Seedance 2.5: `720p` (default), `480p` or `1080p`. Runway turns on 1080p for some accounts and not others. To check an account, open Seedance 2.5 in the Runway app and look for 1080p in the resolution menu. Send `1080p` only from accounts that show it. 1080p isn't available when `exploreMode=true`. - Wan 3.0 / Wan 3.0 Prime: `1080p` (default), `720p`, `480p` - MiniMax H3: `2K` (default), `768p` - MiniMax H3 Max: `768p` (default), `480p` - FLUX 3: `720p` (default), `1080p` - Seedance 2.0 Mini: `720p` (default), `480p` - Seedance 2.0 / Seedance 2.0 Fast: `480p` (default), `720p`, `1080p`. **1080p is not supported when `exploreMode=true`** — set `exploreMode=false` (Credits Mode) to generate at 1080p. - Grok Imagine 1.5: `480p` (default), `720p` - HappyHorse 1.0: `720p` (default), `1080p` - Kling 3.0 Motion Control: `720p` (default, "std" mode), `1080p` ("pro" mode) - Wan 2.6 Flash: `720p` (default), `1080p` - Veo 3.1: `720p` (default), `1080p` - Gen-4, Gen-4 Turbo: `720p` - Kling O3 4K/Pro/Standard: not supported — the output resolution is derived from the model tier and `aspect_ratio` (see [Kling O3 model comparison](#model-comparison-kling-o3)). - All other models: not supported (resolution auto-selected) - `audio` is optional. Default `true`. Set to `false` to disable audio generation. Supported by: Seedance 2.5, Seedance 2.0, Seedance 2.0 Fast, Seedance 2.0 Mini, Wan 3.0, Wan 3.0 Prime, FLUX 3, Kling O3 4K/Pro/Standard, Kling 3.0 Pro/Standard, Kling 3.0 Motion Control, Kling 2.6 Pro, Kling 2.6 I2V, Wan 2.6 Flash, Veo 3.1, Gen-4.5. **Not supported** by `grok-imagine-1.5` (the model produces silent video). `minimax-h3` and `minimax-h3-max` have no audio toggle, so `audio` has no effect on them. For `kling-3.0-motion-control`, `audio` controls whether the original audio of the reference video (`videoAssetId`) is preserved in the output. For the `kling-o3-*` models in Edit Video mode, `audio` controls whether the original sound of the source video (`videoAssetId`) is preserved in the output. - `output_format` is optional. Only supported by `seedance-2-5`. Supported values: `mp4` (default), `mov`. - `video_mode` is optional. Only supported by `seedance-2-5`. Turns the request into Edit Video: `videoAssetId` is the source video (up to 31 seconds) and `text_prompt` are required. The source video and any other reference videos must add up to 30 seconds or less. - `edit` changes the source video as `text_prompt` describes. The output has the source video's length, so `duration` is not used, and edit is not available when `exploreMode=true`. - `extend` continues the source video forwards or backwards, as `text_prompt` describes, for `duration` seconds (default 5). - `aspect_ratio` is not used: the output follows the source video. `videoAssetId2`…`videoAssetId10`, `imageAssetId*` and `audioAssetId*` can still add references. - `draft` is optional. Only supported by `seedance-2-5`. Set to `true` for a cheaper 480p preview (the 480p rate). `resolution` is set to `480p` and `output_format` `mov` is not available. Runway offers drafts to some accounts only. - `draftTaskId` is optional. Only supported by `seedance-2-5`. The `taskId` of a draft to re-render at 1080p, within 7 days of the draft. The re-render costs the 1080p rate for the draft's length. It takes no other parameters except `model`, `email`, `maxJobs`, `replyUrl` and `replyRef`, and is not available when `exploreMode=true`. - `prompt_expansion` is optional. Only supported by `minimax-h3-max`. Controls how the model rewrites your prompt before generating. Supported values: `balanced` (Runway's default when omitted), `disabled`, `quality`. - `seed` is optional. Only supported by Gen-4.5, Gen-4, Gen-4 Turbo (auto-generated if not provided), and `minimax-h3-max` (Runway picks a random seed if not provided). Valid range 1–4294967294. - `imageAssetId1`, `imageAssetId2` ... `imageAssetId30` are optional. Specify the assetIds of reference images. Use [GET /assets/?mediaType=image](/docs/api-runwayml-v1/get-runwayml-assets) to see the list of image assets. To upload a new image asset use [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets). Maximum number of reference images depends on model — see [model comparison](#model-comparison-gen-45--gen-4). - `imageAssetId1`: start frame image. For `grok-imagine-1.5` this is **required** (the model is image-to-video only). - `imageAssetId2`: end frame image (only for models supporting `endFrame`: Kling 3.0 Pro/Standard, Veo 3.1) - `imageAssetId3` ... `imageAssetId9`: additional reference image slots for the Seedance family in multi-reference mode. `seedance-2` / `seedance-2-fast` / `seedance-2-mini` accept up to 9 image refs, with a combined cap of 9 across images + videos + audio. - `wan-3.0` / `wan-3.0-prime` accept up to 10 reference images (`imageAssetId1`..`imageAssetId10`) and `minimax-h3` up to 9 (`imageAssetId1`..`imageAssetId9`), in multi-reference mode. `minimax-h3-max` and `flux-3` accept no reference images — use `startFrameAssetId` instead. - `imageAssetId10` ... `imageAssetId30`: further slots used only by `seedance-2-5`, which accepts up to 30 image refs within a combined cap of 50 across images + videos + audio. Other models reject the surplus slots. - For the `kling-o3-*` models, `imageAssetId1`..`imageAssetId7` are reference image slots (0–7 images). In Edit Video mode at most 4 reference images are accepted. The end frame for Kling O3 is supplied via `endFrameAssetId` (not `imageAssetId2`). - `videoAssetId`, `videoAssetId2` ... `videoAssetId10` are optional. Specify the assetIds of reference videos. Use [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets) to upload a video asset. - `videoAssetId`: the single reference video for `wan-2.2-animate` (**required** for that model) and for `kling-3.0-motion-control` (**required** as the performance/motion source). Also the source video for `kling-o3-pro` / `kling-o3-standard` Edit Video mode. - `videoAssetId2`, `videoAssetId3`: additional video-reference slots for the Seedance family in multi-reference mode. `videoAssetId4` ... `videoAssetId10` are used only by `seedance-2-5`, which accepts up to 10 video refs. - For `seedance-2` / `seedance-2-fast` / `seedance-2-mini`, each reference video must be **≤ 16 seconds** long and **≤ 720p** (longest side ≤ 1280 px). - For `seedance-2-5` with `video_mode`, `videoAssetId` is the source video to edit or extend. - For `seedance-2-5`, each reference video must be **≤ 31 seconds** long. In Explore mode the combined duration of all reference videos must also be **≤ 15 seconds**. - `wan-3.0` / `wan-3.0-prime` accept up to 5 reference videos (`videoAssetId`..`videoAssetId5`) with a combined duration of **≤ 15 seconds**. - `minimax-h3` accepts up to 3 reference videos, each **2–15 seconds** long, with a combined duration of **≤ 15 seconds**. - For `flux-3`, `videoAssetId` is the source video to **extend** (**≤ 15 seconds**). Extend cannot be combined with `startFrameAssetId`. Extend is billed per second of output at a higher rate — see [FLUX 3 model comparison](#model-comparison-flux-3). - For `kling-3.0-motion-control`, the reference video must be **between 3 and 30 seconds**. - For `kling-o3-pro` / `kling-o3-standard` Edit Video, the source video must be **≤ 10 seconds**. `kling-o3-4k` does not support Edit Video. - `audioAssetId1`, `audioAssetId2` ... `audioAssetId10` are optional. Reference audio assets used by the Seedance family, `wan-3.0` / `wan-3.0-prime` and `minimax-h3` in multi-reference mode. Upload audio via [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets) (supported types: `.mp3`, `.wav`, `.m4a`). - `seedance-2` / `seedance-2-fast` / `seedance-2-mini` accept up to 3 audio refs per request, and their combined duration must be **≤ 15 seconds**. On those models an audio reference **must be combined with at least one image or video reference** (`imageAssetIdN` or `videoAssetIdN`) — audio-only submits return 400. - `seedance-2-5` accepts up to 10 audio refs, each between **1.8 and 30 seconds**, with no combined limit. It also accepts an audio reference on its own, without an image or video. - `wan-3.0` / `wan-3.0-prime` accept up to 5 audio refs, each at least **2 seconds** long, with a combined duration of **≤ 15 seconds**. Audio may be supplied on its own. - `minimax-h3` accepts up to 3 audio refs, each **2–15 seconds** long, with a combined duration of **≤ 15 seconds**. An audio reference **must be combined with at least one image or video reference**. - Audio refs are **mutually exclusive with keyframe mode** (`startFrameAssetId` / `endFrameAssetId`). Using both returns 400. - Audio refs count toward the combined-ref cap — 9 total on the 2.0 variants, 12 on `minimax-h3`, 50 on `seedance-2-5`. - `startFrameAssetId`, `endFrameAssetId` are optional. Dedicated keyframe fields for the Seedance family, `wan-3.0` / `wan-3.0-prime`, `minimax-h3`, `minimax-h3-max`, `flux-3` (start frame only) and the `kling-o3-*` models. - `startFrameAssetId`: first-frame image (tagged `first_frame` on the wire). - `endFrameAssetId`: last-frame image (tagged `end_frame`). Requires `startFrameAssetId` — cannot be supplied alone. - For the Seedance family, `wan-3.0` / `wan-3.0-prime` and `minimax-h3`, keyframe mode is **mutually exclusive** with multi-reference mode (`imageAssetIdN` / `videoAssetIdN` / `audioAssetIdN`). Using both in the same request returns 400. - For `minimax-h3-max`, each frame image must be at least 256 px on its shorter side. - For `flux-3`, only `startFrameAssetId` is accepted, and it cannot be combined with an extend source video (`videoAssetId`). - For the `kling-o3-*` models, `startFrameAssetId` **may** be combined with reference images (`imageAssetId1`..`imageAssetId7`), but `endFrameAssetId` **cannot** — supplying `endFrameAssetId` together with any reference image returns 400. - `characterOrientation` is optional. Used only by `kling-3.0-motion-control`. Supported values: `image` (default), `video`. Controls whether the character's orientation in the output is anchored to the character image or to the performance video. - `multishot_prompt_N` and `multishot_duration_N` are optional. Multi-shot parameters for creating multi-scene videos. Supported by Kling 3.0 Pro/Standard and the `kling-o3-*` models. Each shot requires both a prompt and a duration. Shot duration range: 3–12 seconds. Total duration across all shots must not exceed 15 seconds. Prompt max length: 512 characters per shot. Shots must be numbered contiguously starting from 1. - Kling 3.0 Pro/Standard: `multishot_prompt_1`..`multishot_prompt_5` / `multishot_duration_1`..`multishot_duration_5` — minimum 2 shots, maximum 5 shots. - Kling O3 4K/Pro/Standard: `multishot_prompt_1`..`multishot_prompt_6` / `multishot_duration_1`..`multishot_duration_6` — minimum 2 shots, maximum 6 shots. For the `kling-o3-*` models, reference images supplied via `imageAssetId1`..`imageAssetId7` are bound to a specific shot by referencing them as `@IMG_N` in that shot's prompt — e.g. `@IMG_1` in `multishot_prompt_2` binds `imageAssetId1` to shot 2. The same image may be referenced from multiple shots; an image not referenced by any shot is used as a global reference. An optional first frame for the whole sequence can be supplied via `startFrameAssetId`. - `exploreMode` is optional. Set to `true` if you have a Runway [Unlimited plan](https://help.runwayml.com/hc/en-us/articles/18053095835795-Unlimited-plan-details) and wish to execute relaxed generation. You are not charged credits for Explore mode generations. **Not supported** by `veo-3.1` — will return 400 if set to `true`. Not available for `wan-3.0`, `wan-3.0-prime`, `minimax-h3`, `minimax-h3-max` and `flux-3`. Runway does not offer Explore mode for these models, so use Credits Mode (`exploreMode` `false`). - `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used. Place here your callback URL. API will call the provided `replyUrl` once Runway task completed or failed. Maximum length 1024 characters. We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality. Callback body has the same JSON shape as [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) response. - `replyRef` is optional, place here your reference id which will be stored and returned along with this Runway task response / result. Maximum length 1024 characters. - `maxJobs` is optional, if not provided value for referenced by image assetId account will be used. Valid range: 1–10. Runway has dynamic query capacity and guarantees that, for a given account, at least one job will run — often two, and very rarely, three. If you have a single account linked, keep adding new jobs until you receive a `429` response. Once you get a `429`, wait for xx seconds or until at least one job completes, then try again. If you need to run more jobs in parallel, simply add more Runway accounts. ##### Responses **200** **200 OK** Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId). The generated video can be found in the `artifacts` array of the task with the status `SUCCEEDED`. If you specify the optional parameter [`replyUrl`](/docs/api-runwayml-v1/post-runwayml-videos-create#request-body) the API will call the provided `replyUrl` with task progress updates until the task is complete or fails. ```json { "task": { "id": "<uuid>", "name": "gen4.5 <your text prompt>", "image": null, "createdAt": "2026-03-05T10:00:00.000Z", "updatedAt": "2026-03-05T10:00:00.100Z", "taskType": "gen4.5", "options": { "name": "gen4.5 <your text prompt>", "text_prompt": "<your text prompt>", "seconds": 5, "seed": 12345, "watermark": false, "route": "t2v", "width": 1280, "height": 720, "assetGroupId": "<uuid>", "creationSource": "tool-mode", "exploreMode": true, "recordingEnabled": true }, "status": "PENDING", "error": null, "progressText": null, "progressRatio": "0", "estimatedTimeToStartSeconds": 0, "artifacts": [], "sharedAsset": null, "sourceAssetId": null, "taskId": "user:user_id-runwayml:account_email-task:task_uuid", "code": 200 } } ``` **400** **400 Bad Request** ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **412** **412 Insufficient credits** You do not have enough credits to run this task. ```json { "error": "You do not have enough credits to run this task." } ``` **429** **429 Too Many Requests** Wait in a loop for **at least** 10..30 seconds and retry again. When `exploreMode` is `true` and another explore mode job is still running, the new job will not start until the current one completes. Since explore mode generations can take significantly longer, you may need to wait before retrying. There are two possible cases for API response 429: * API query is full and can not accept new [videos/create](#videos) requests. Size of query defined by [`maxJobs` optional parameter](#request-body). ```json { "error": "Account <Runway account email> is busy executing <Account maxJobs> tasks", "runningTasks": { "<Runway account email>": [ { "email": "<Runway account email>", "taskId": "user:user_id-runwayml:account_email-task:task_#1_uuid", "id": "<uuid>", "replyUrl": "<replyUrl if provided>", "replyRef": "<replyRef if provided>" } ] }, "code": 429 } ``` * The API received an HTTP response status 429 from Runway. Runway has dynamic query management and may limit the number of simultaneously executed tasks based on internal service load and policies. ```json { "error": "You have too many tasks running or pending. Please wait for some of them to finish before starting more." } ``` ##### Model The new task with its `taskId`: poll it with [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) until it finishes, then find the video in `artifacts`. <details markdown="block" class="model-details"> <summary>The new video task, field by field</summary> ```typescript { // TypeScript, all fields are optional taskId: string, id: string, name: string, image: string, createdAt: string, updatedAt: string, taskType: string, options: { name: string, text_prompt: string, seconds: number, seed: number, watermark: boolean, route: string, width: number, height: number, exploreMode: boolean, assetGroupId: string, creationSource: string, recordingEnabled: boolean }, status: string, progressText: string, progressRatio: number, estimatedTimeToStartSeconds: number, artifacts: any[], sharedAsset: any, error: { errorMessage: string, reason: string, message: string, moderation_category: string, tally_asimov: boolean }, code: number, replyUrl: string, replyRef: string } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST "https://api.useapi.net/v1/runwayml/videos/create" \ -d '{"model": "gen4.5", "text_prompt": "A cinematic aerial shot of a coastal city at golden hour", "duration": 5}' ``` **JavaScript** ``` javascript const model = "gen4.5"; const text_prompt = "A cinematic aerial shot of a coastal city at golden hour"; const duration = 5; const apiUrl = `https://api.useapi.net/v1/runwayml/videos/create`; const token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ model, text_prompt, duration }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests model = "gen4.5" text_prompt = "A cinematic aerial shot of a coastal city at golden hour" duration = 5 apiUrl = f"https://api.useapi.net/v1/runwayml/videos/create" token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } body = { "model": f"{model}", "text_prompt": f"{text_prompt}", "duration": duration } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-videos-upscale === Document URL: https://useapi.net/docs/api-runwayml-v1/post-runwayml-videos-upscale --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/upscale description: "Upscale a Runway video to 4K using Topaz AI via POST videos/upscale in the useapi.net Runway API v1 — supports up to 40 seconds, source aspect ratio preserved." parent: Runway API nav_order: 407 --- ## Upscale a video to 4K with Topaz AI May 15, 2026 (November 16, 2026) --- Upscale a video to 4K using Topaz AI. Output preserves the source aspect ratio and bumps the longer dimension up to 4K class (e.g. a 1280×720 source → 4096×2304, a 1080×1920 source → 2160×3840). The input is a `videoAssetId`. Two common ways to obtain one: * **Upscale a video you generated** — pass the `assetId` from any video task: [videos/create](/docs/api-runwayml-v1/post-runwayml-videos-create) outputs (Kling, Veo, Wan, Seedance, HappyHorse, Gen-4.x), [gen4-video](/docs/api-runwayml-v1/post-runwayml-gen4-video), or any other Runway video task. Look it up later via [GET /assets/?mediaType=video](/docs/api-runwayml-v1/get-runwayml-assets). * **Upscale an uploaded video** — upload your own file via [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets) and use the returned `assetId`. ##### Constraints | Constraint | Value | |------------|-------| | Max source duration | 40 seconds | | Source media type | `video` | | Output | 4K (source aspect ratio preserved) | | Model | Topaz AI (only option) | | Billing | 2 credits/second, or free with `exploreMode` on Runway Unlimited plan | > **https://api.useapi.net/v1/runwayml/videos/upscale** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "videoAssetId": "Required assetId of any video asset to upscale", "exploreMode": true, "replyUrl": "Place your call back URL here", "replyRef": "Place your reference id here", "maxJobs": 5 } ``` - `videoAssetId` is **required**. The video asset to upscale. Use [GET /assets/?mediaType=video](/docs/api-runwayml-v1/get-runwayml-assets) to list video assets, or pass through any `assetId` returned by [videos/create](/docs/api-runwayml-v1/post-runwayml-videos-create), [gen4-video](/docs/api-runwayml-v1/post-runwayml-gen4-video), [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets), etc. The account that owns the asset is charged for the upscale — no `email` parameter is needed. - `exploreMode` is optional. Set to `true` if you have a Runway [Unlimited plan](https://help.runwayml.com/hc/en-us/articles/18053095835795-Unlimited-plan-details) and wish to execute relaxed generation. You are not charged credits for Explore mode generations. - `replyUrl` is optional, if not provided value from [useapi.net account](/docs/account-management/get-account) will be used. Place here your callback URL. API will call the provided `replyUrl` once Runway task completed or failed. Maximum length 1024 characters. We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality. Callback body has the same JSON shape as [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) response. - `replyRef` is optional, place here your reference id which will be stored and returned along with this Runway task response / result. Maximum length 1024 characters. - `maxJobs` is optional, if not provided the value configured for the account owning the video asset will be used. Valid range: 1…10. See [Setup Runway](/docs/start-here/setup-runwayml) for details on per-account concurrency. ##### Responses **200** **200 OK** Use returned `taskId` to retrieve task status and results using [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId). The upscaled video `url` can be found in the `artifacts` array of the task with the status `SUCCEEDED`. If you specify the optional parameter [`replyUrl`](/docs/api-runwayml-v1/post-runwayml-videos-upscale#request-body) the API will call the provided `replyUrl` with task progress updates until the task is complete or fails. ```json { "taskId": "user:user_id-runwayml:account_email-task:task_uuid", "id": "<uuid>", "name": "Upscaled <source video name>", "image": null, "createdAt": "2026-05-15T20:10:08.838Z", "updatedAt": "2026-05-15T20:10:08.838Z", "taskType": "harrods", "options": { "name": "Upscaled <source video name>", "parent_asset_group_id": "<uuid>", "creationSource": "apps", "creationSourceAppId": "upscale-video", "asset_id": "<source video uuid>", "exploreMode": true, "recordingEnabled": true }, "status": "THROTTLED", "error": null, "progressText": null, "progressRatio": "0", "estimatedTimeToStartSeconds": 0, "artifacts": [], "sharedAsset": null, "sourceAssetId": null, "replyUrl": "https://webhook.site/abc", "replyRef": "<your optional reference id>", "code": 200 } ``` On completion, polling [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) returns the artifact with the 4K dimensions and a signed download URL: ```json { "status": "SUCCEEDED", "progressRatio": "1", "artifacts": [ { "id": "<uuid>", "assetId": "user:user_id-runwayml:account_email-asset:<uuid>", "filename": "<source name> 4K.mp4", "url": "https://dnznrvs05pmza.cloudfront.net/<uuid>.mp4?_jwt=...", "fileSize": "14173798", "metadata": { "frameRate": 50, "duration": 8, "dimensions": [4096, 2304], "size": { "width": 4096, "height": 2304 } } } ] } ``` **400** **400 Bad Request** Returned when `videoAssetId` is missing or malformed, the referenced asset is not a video, or the source video exceeds the 40-second maximum: ```json { "error": "videoAssetId duration (52.30s) exceeds maximum 40s for video upscale", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** ```json { "error": "Unable to retrieve assetId <uuid> (Not found.)", "code": 404 } ``` **412** **412 Insufficient credits** You do not have enough credits to run this task. Set `exploreMode: true` if you have a Runway Unlimited plan. ```json { "error": "You do not have enough credits to run this task." } ``` **429** **429 Too Many Requests** Wait in a loop for **at least** 10..30 seconds and retry again. ```json { "error": "Account <Runway account email> is busy executing <Account maxJobs> tasks", "runningTasks": { "<Runway account email>": [ { "email": "<Runway account email>", "taskId": "user:user_id-runwayml:account_email-task:task_uuid", "id": "<uuid>", "replyUrl": "<replyUrl if provided>", "replyRef": "<replyRef if provided>" } ] }, "code": 429 } ``` ##### Model The new task with its `taskId`: poll it with [GET /tasks/`taskId`](/docs/api-runwayml-v1/get-runwayml-tasks-taskId) until it finishes, then find the upscaled video in `artifacts`. <details markdown="block" class="model-details"> <summary>The new upscale task, field by field</summary> ```typescript { // TypeScript, all fields are optional id: string taskId: string name: string image: any createdAt: string updatedAt: string taskType: string options: { name: string asset_id: string creationSource: 'apps' creationSourceAppId: 'upscale-video' parent_asset_group_id: string exploreMode: boolean recordingEnabled: boolean } status: string error: { errorMessage: string reason: string message: string moderation_category: string tally_asimov: boolean } progressText: string progressRatio: number estimatedTimeToStartSeconds: number artifacts: { id: string assetId: string filename: string url: string fileSize: string previewUrls: string[] metadata: { frameRate: number duration: number dimensions: [number, number] size: { width: number, height: number } } }[] sharedAsset: any sourceAssetId: any code: number replyUrl: string replyRef: string } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST "https://api.useapi.net/v1/runwayml/videos/upscale" \ -d '{"videoAssetId": "…", "exploreMode": true }' ``` **JavaScript** ``` javascript const videoAssetId = "assetId of video asset"; const apiUrl = `https://api.useapi.net/v1/runwayml/videos/upscale`; const token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ videoAssetId, exploreMode: true }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests videoAssetId = "assetId of video asset" apiUrl = f"https://api.useapi.net/v1/runwayml/videos/upscale" token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } body = { "videoAssetId": f"{videoAssetId}", "exploreMode": True } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/start-here/setup-tempolor === Document URL: https://useapi.net/docs/start-here/setup-tempolor --- layout: default title: Setup TemPolor description: "How to set up TemPolor for the useapi.net API — connect your account and start generating via the API." parent: Start Here nav_order: 265 --- # <img style="height:1.2em;vertical-align: middle;" src="/assets/images/tempolor.png" alt=""> Setup TemPolor May 15, 2025 ## Table of contents Approximately 5 minutes to complete setup steps. --- > This is the setup guide for [TemPolor API](/docs/api-tempolor-v1). An active [TemPolor](https://www.tempolor.com) subscription and a [useapi.net subscription](/docs/subscription) are required for the API to work. [TemPolor](https://www.tempolor.com), an AI-powered, royalty-free **music generation** service that creates high-quality soundtracks from text prompts, custom lyrics, MIDI, and supports voice cloning. TemPolor offers extensive customization for instrumental tracks, including chords and BPM. Supports export in mp3, wav, and stems, and it can generate stems from users' audio files. Up to 10 tracks can be generated concurrently, with **unlimited** generations available on the [Ultra](https://www.tempolor.com/pricing) plan. ## Create TemPolor account Create a [TemPolor](https://www.tempolor.com) account if you don't have one already. ## Locate your TemPolor `requestParams` Open a Chromium-compatible browser (e.g. [Google Chrome](https://www.google.com/chrome/), [Microsoft Edge](https://www.microsoft.com/en-us/edge), or [Opera](https://www.opera.com/)) and navigate to your TemPolor account profile page [https://www.tempolor.com/account/profile](https://www.tempolor.com/account/profile) <span style="color: red;">`1`</span>. ![](/assets/images/tempolor_setup_1.png) Refresh the page <span style="color: red;">`2`</span>. Once the page is fully loaded, ensure that you're logged in and current page is [https://www.tempolor.com/account/profile](https://www.tempolor.com/account/profile). Open [Developer Tools](https://developer.chrome.com/docs/devtools) by right-clicking on the page and selecting "Inspect Element" or via [keyboard shortcuts](https://developer.chrome.com/docs/devtools/shortcuts): Mac `Command+Option+I` or Windows `F12` or `Control+Shift+I`. Select Developer Tools » Network <span style="color: red;">`3`</span>: * Make sure that `All` or `Fetch/XHR` is selected <span style="color: red;">`4`</span>. * Type `/getWebSelfUserInfo` in the filter box <span style="color: red;">`5`</span> and hit Enter. * You should see a single HTTP call entry as shown below <span style="color: red;">`6`</span> and click on that entry. * Select the "Payload" tab <span style="color: red;">`7`</span>. * Locate and select the "Request Payload" header <span style="color: red;">`8`</span>. * Right-click on the `requestParams` and copy its content <span style="color: red;">`9`</span>. This is your `requestParams`. <details markdown="block"> <summary>As an example above, the <b>requestParams</b> (JSON)</summary> ```json { "requestParams": { "sv": "alpha/beta/release", "ver_code": 20000, "lang": "french", "la": "fr-FR", "di": "e23c9f7db8ced478b8574923817c2b6a", "pf": "100", "mi": "Windows", "biz": 378, "utdid": "e23c9f7db8ced478b8574923817c2b6a", "ts": 1849982225671, "service_ticket": "hUUCp7MeIAXpXKo9AOP5zPlJLqVZh81C2MWlZdTuqoGbNqzlgQNjBwtxdYnJPRA52Wn=", "ucid": "100349856", "user_id": "100349856", "member_level": 0, "is_visitor": 0, "vip_type": 20, "app_id": "material", "app": "web", "ve": "2.0.0", "entry": "web_main", "fr": "web", "ip": "88.222.199.44", "business_type": "material", "la_multi": "fr", "b_ts": "1849512371543", "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.39 (KHTML, like Gecko) Chrome/122.1.0.0 Safari/537.39 OPR/123.0.0.0", "web_terminal": "web_pc" } } ``` </details> ## Verify and add account Use the form below to verify your credentials and add your TemPolor account. Select **Add Account** to complete setup, or **Verify** to test your credentials first. You should receive response `200` if successful. You can also use [POST /accounts](/docs/api-tempolor-v1/post-tempolor-accounts) directly. <script> async function apiTestAccountTempolor(addAccount) { data = { method: 'POST', headers: { 'Authorization': `Bearer ${document.getElementById('post-accounts-Tempolor-api_token').value}`, 'Content-Type': 'application/json' } }; let body; try { body = JSON.parse(document.getElementById(`post-accounts-Tempolor-requestParams`)?.value); } catch (e) { body = {}; } if (!addAccount) body.dryRun = true; data.body = JSON.stringify(body); await apiExecute(`https://api.useapi.net/v1/tempolor/accounts`, 'post-accounts-Tempolor', data); } </script> <form id="post-accounts-Tempolor" onsubmit="apiTestAccountTempolor(document.getElementById('post-accounts-Tempolor-action').value === 'add'); return false;" class="input-form"> <div class="input-field"> <div class="input-field-row"> <label for="post-accounts-Tempolor-api_token"><span>API Token (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</span> <input id="post-accounts-Tempolor-api_token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length"> </label> <label for="post-accounts-Tempolor-requestParams"><span>requestParams (JSON)</span> <textarea id="post-accounts-Tempolor-requestParams" class="input-element" required aria-required="true" spellcheck="false" rows="5" style="resize:vertical; min-height:5em; max-height:20em;font-size: smaller;" oninput="this.rows = Math.min(10, Math.max(5, this.value.split('\n').length));"></textarea> </label> <label for="post-accounts-Tempolor-action"><span>action</span> <select id="post-accounts-Tempolor-action" class="input-element"> <option value="verify">Verify — test credentials only</option> <option value="add">Add Account — required to complete setup</option> </select> </label> </div> <button id="post-accounts-Tempolor-button" class="btn btn-primary fs-3" type="submit">Go</button> </div> </form> <div id="post-accounts-Tempolor-response" class="response-placeholder visible-false"></div> === URL: https://useapi.net/docs/api-tempolor-v1 === Document URL: https://useapi.net/docs/api-tempolor-v1 --- layout: default title: TemPolor API nav_logo: /assets/images/tempolor.png nav_title: TemPolor API seo_title: "TemPolor API: v4.8 Songs, i4 Instrumentals and Voice Cloning" description: "Third-party TemPolor API by useapi.net: royalty-free v4.8 songs and i4 instrumentals with voice cloning, MIDI and stems, on your TemPolor subscription." nav_order: 8000 has_children: true permalink: /docs/api-tempolor-v1 --- # <img style="height:1.5em;vertical-align: middle;" src="/assets/images/tempolor.png" alt=""> TemPolor API May 15, 2025 (October 21, 2026) This is a [third-party](/docs/legal#affiliation--third-party-services) API for [TemPolor](https://www.tempolor.com) by Qustar Technology. It uses your [TemPolor subscription](https://www.tempolor.com/pricing): Lite $9.79, Pro $13.99 or Ultra $29.99 a month (as of October 2026). Through a REST API, it makes royalty-free songs with TemPolor v4.8 and instrumentals with i4 from a prompt, your lyrics or a MIDI file, and downloads them as mp3, wav or stems. Songs can be sung in a voice you clone, which TemPolor's own [developer API](https://platform.tempolor.com/docs/296524438e0) doesn't offer (as of October 2026). ## Models | Model | What it makes | Notes | |---|---|---| | TemPolor v4.8<br>`v4.8` | [Songs with vocals](/docs/api-tempolor-v1/post-tempolor-music-song) | From a prompt or your lyrics, up to 5 minutes in more than 30 languages, sung by a [cloned voice](/docs/api-tempolor-v1/post-tempolor-music-cloned-voices) or an [artist voice](/docs/api-tempolor-v1/get-tempolor-music-artist-voices), or built on your [MIDI file](/docs/api-tempolor-v1/post-tempolor-music-midi) | | TemPolor i4<br>`i4` | [Instrumentals](/docs/api-tempolor-v1/post-tempolor-music-instrumental) | From a prompt, with the key, tempo (50 to 190 BPM) and chords you set | | Stem splitter | [Stems from your own audio](/docs/api-tempolor-v1/post-tempolor-music-stems-splitter) | Upload MP3, WAV, M4A or FLAC and get the vocal and instrument stems as a ZIP | Every song and instrumental [downloads](/docs/api-tempolor-v1/get-tempolor-music-download-job_id) as mp3, wav or a stems ZIP. Older model names still work and run on v4.8 or i4. In our tests a track took 51 to 103 seconds. ## Pricing What one track costs on [TemPolor's developer API](https://platform.tempolor.com/docs/6665893m0) and on each TemPolor subscription (as of October 2026). Lite and Pro come with a monthly number of tracks, so a track costs its share of the plan, and Ultra has no track limit. | Model | [Official API](https://platform.tempolor.com/pricing) | Ultra $29.99/m (unlimited tracks) | Pro $13.99/m (3,000 tracks/mo) | Lite $9.79/m (1,000 tracks/mo) | |---|---|---|---|---| | TemPolor v4.8 (song with vocals) | $0.04 ($0.05 if it writes the lyrics) | $0 / track (no per-song charge) | $0.0047 / track (3,000 songs/mo) | $0.0098 / track (1,000 songs/mo) | | TemPolor i4 (instrumental) | $0.04 (a call) | $0 / track (no per-track charge) | $0.0047 / track (3,000 tracks/mo) | $0.0098 / track (1,000 tracks/mo) | | [Stems](/docs/api-tempolor-v1/post-tempolor-music-stems-splitter) (vocals and instruments) | $0.05 (4 stems, a call) | $0 / split (unlimited splitting) | $0 / split (unlimited splitting) | Pro and Ultra only | | [Voice cloning](/docs/api-tempolor-v1/post-tempolor-music-cloned-voices) | not sold | included (up to 50 saved voices) | included (up to 10 saved voices) | included (up to 4 saved voices) | - TemPolor lists no free plan. Each song or instrumental request answers with the tracks your plan has left this month, and Ultra runs ten generations at once. - The license grows with the plan: Lite covers social media and podcasts, Pro adds client work and paid ads, and Ultra adds TV, radio and music distribution such as Spotify and Apple Music ([TemPolor pricing](https://www.tempolor.com/pricing)). - Yearly billing lowers Lite to $5.59, Pro to $7.99 and Ultra to $15.99 a month. - TemPolor's developer API sells prepaid credit packages from [$100](https://platform.tempolor.com/pricing), at $0.01 a credit at every package size, with 5 requests at a time on the $100 package (as of October 2026). ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. ## Run several TemPolor accounts Each useapi.net subscription connects 3 TemPolor accounts. Song and instrumental requests don't need `user_id`: each job goes to an account with a free slot within its `maxJobs` (default 10), and a song with a cloned voice or MIDI file runs on the account that holds it. When every account is busy you get `429`, so wait 30 seconds and send it again. Pass `user_id` to run a job on a specific account, and with more than one account connected, uploads and lists need it too. [GET scheduler/available](/docs/api-tempolor-v1/get-tempolor-scheduler-available) shows the free slots on every account. Every job can post its progress and result to your webhook with `replyUrl`, or you poll [GET music/`job_id`](/docs/api-tempolor-v1/get-tempolor-music-job_id). [How useapi.net works](/docs/how-it-works) has tips for keeping your accounts healthy. ## Questions ### Is there a TemPolor API? Through useapi.net, yes, with what TemPolor's own developer API lacks: songs in a [cloned voice](/docs/api-tempolor-v1/post-tempolor-music-cloned-voices) or an [artist voice](/docs/api-tempolor-v1/get-tempolor-music-artist-voices), songs built on your [MIDI file](/docs/api-tempolor-v1/post-tempolor-music-midi), and instrumentals in the key, tempo and chords you set, all on your TemPolor subscription. TemPolor's [developer API](https://platform.tempolor.com/docs/296524438e0) has no voice, MIDI, key, tempo or chord settings (as of October 2026). ### How much does the TemPolor API cost? Through useapi.net, a TemPolor song has no per-song charge on TemPolor Ultra, and on Pro at $13.99 for 3,000 tracks a song costs about half a cent. TemPolor's developer API charges $0.04 a song, $0.05 when it writes the lyrics, from a prepaid package of at least $100 (as of October 2026). The [price table](#pricing) shows every plan. ### Is there a TemPolor API key? Through useapi.net, you call TemPolor with our [API token](/docs/start-here/setup-useapi), not a TemPolor developer key, and connect your TemPolor website account once with [Setup TemPolor](/docs/start-here/setup-tempolor), which takes about 5 minutes. TemPolor's developer API needs its own API key and a prepaid credit package instead. ### Is there a TemPolor stem separation API? Through useapi.net, yes, with no charge per split on TemPolor Pro or Ultra: every song and instrumental [downloads](/docs/api-tempolor-v1/get-tempolor-music-download-job_id) as a stems ZIP, and [POST music/stems-splitter](/docs/api-tempolor-v1/post-tempolor-music-stems-splitter) splits your own MP3, WAV, M4A or FLAC into vocal and instrument stems. TemPolor's developer API charges $0.05 for each 4-stem split (as of October 2026). [Setup TemPolor](/docs/start-here/setup-tempolor) [LLM-friendly API spec](https://useapi.net/assets/aibot/api-tempolor-v1.txt) Feed this to your LLM to build integrations [Claude Code skill](/llm-tools) A drop-in useapi.net skill for Claude Code, and a rule for Cursor [Postman collection](https://www.postman.com/useapinet/useapi-net/collection/29112081-e6199d78-0334-4936-bb19-94375d412f84) (October 5, 2026) [GitHub examples](https://github.com/useapi/ai-music-comparison/tree/main/same-brief-four-flagships) Node.js: the same six briefs on TemPolor v4.8 and i4 and three other music APIs, with every track downloaded Articles: * [Suno API Alternative: ACE Music, Mureka, Lyria 3.5, TemPolor and MiniMax](/docs/articles/suno-api-alternative) {% include lang-switch.html mode="hub" key="suno-api-alternative" %} * [Five AI Music APIs on the Same Six Briefs: ACE Music v1, TemPolor v4.8, MiniMax Music-3.0, Lyria 3.5 and Mureka V9.5](/docs/articles/ai-music-flagships-compared) {% include lang-switch.html mode="hub" key="ai-music-flagships" %} Examples: * [TemPolor v4.5 multilingual songs](/blog/260321) * [TemPolor API Samples](/blog/250515) Videos on YouTube: * [Five AI music APIs: ACE Music v1, TemPolor v4.8, MiniMax Music-3.0, Lyria 3.5 and Mureka V9.5](https://www.youtube.com/watch?v=MSUGckk4JqU) Developer Community: * <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> * <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> === URL: https://useapi.net/docs/api-tempolor-v1/del-tempolor-accounts-user_id === Document URL: https://useapi.net/docs/api-tempolor-v1/del-tempolor-accounts-user_id --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> accounts/`user_id` description: "Delete a TemPolor API account configuration by user_id via DELETE accounts/user_id in the useapi.net TemPolor API v1." parent: TemPolor API nav_order: 400 --- ## Delete TemPolor API account May 15, 2025 --- This endpoint deletes a TemPolor API account configuration. [Setup TemPolor](/docs/start-here/setup-tempolor) > **https://api.useapi.net/v1/tempolor/accounts/`user_id`** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **204** **204 No Content** Account configuration was successfully deleted. **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** Account configuration not found. ##### Examples **Curl** ``` bash curl -X DELETE https://api.useapi.net/v1/tempolor/accounts/<user_id> \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const user_id = "Previously configured account"; const apiUrl = `https://api.useapi.net/v1/tempolor/accounts/${user_id}`; const response = await fetch(apiUrl, { method: 'DELETE', headers: { "Authorization": `Bearer ${token}`, } }); console.log("response", response); ``` **Python** ``` python import requests token = "API token" user_id = "Previously configured account" apiUrl = f"https://api.useapi.net/v1/tempolor/accounts/{user_id}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers) print(response) ``` === URL: https://useapi.net/docs/api-tempolor-v1/del-tempolor-scheduler-job_id === Document URL: https://useapi.net/docs/api-tempolor-v1/del-tempolor-scheduler-job_id --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> scheduler/`job_id` description: "Cancel API tracking of a running music generation job by job_id via DELETE scheduler/job_id in the useapi.net TemPolor API v1." parent: TemPolor API nav_order: 2100 --- ## Cancel a running job May 15, 2025 --- This endpoint cancels a running API job from being tracked by the scheduler. The job will still be executed by TemPolor, but the API will no longer track its progress. > **https://api.useapi.net/v1/tempolor/scheduler/`job_id`** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Path Parameters - `job_id` is **required**. The job to cancel, as returned from [POST music/song](/docs/api-tempolor-v1/post-tempolor-music-song), [POST music/instrumental](/docs/api-tempolor-v1/post-tempolor-music-instrumental), or [GET scheduler](/docs/api-tempolor-v1/get-tempolor-scheduler). ##### Responses **204** **204 No Content** Job was successfully cancelled. **400** **400 Bad Request** The job_id format is invalid. ```json { "error": "job_id has incorrect format", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** The specified job was not found or could not be cancelled. ```json { "error": "Unable to locate running job_id", "code": 404 } ``` ##### Examples **Curl** ``` bash curl -X DELETE "https://api.useapi.net/v1/tempolor/scheduler/<job_id>" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const job_id = "user:12345-tempolor:user_id-job:abcdef123456789"; const apiUrl = `https://api.useapi.net/v1/tempolor/scheduler/${job_id}`; const response = await fetch(apiUrl, { method: "DELETE", headers: { "Authorization": `Bearer ${token}` } }); if (response.status === 204) { console.log("Job cancelled successfully"); } else { const errorData = await response.json(); console.error("Failed to cancel job:", errorData); } ``` **Python** ``` python import requests token = "API token" job_id = "user:12345-tempolor:user_id-job:abcdef123456789" api_url = f"https://api.useapi.net/v1/tempolor/scheduler/{job_id}" headers = { 'Authorization': f'Bearer {token}' } response = requests.delete(api_url, headers=headers) if response.status_code == 204: print("Job cancelled successfully") else: try: error_data = response.json() print(f"Failed to cancel job: {error_data}") except: print(f"Failed to cancel job: {response.status_code}") ``` === URL: https://useapi.net/docs/api-tempolor-v1/delete-tempolor-music-cloned-voices-clonedVoiceItemId === Document URL: https://useapi.net/docs/api-tempolor-v1/delete-tempolor-music-cloned-voices-clonedVoiceItemId --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> music/cloned-voices description: "Delete a previously created cloned voice by clonedVoiceItemId via DELETE music/cloned-voices in the useapi.net TemPolor API v1." parent: TemPolor API nav_order: 1900 --- ## Delete a cloned voice May 15, 2025 (November 16, 2026) --- This endpoint deletes a previously created cloned voice. > **https://api.useapi.net/v1/tempolor/music/cloned-voices/`clonedVoiceItemId`** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Path Parameters - `clonedVoiceItemId` is **required**. The cloned voice ID returned from a previous [POST music/cloned-voices](/docs/api-tempolor-v1/post-tempolor-music-cloned-voices) request. ##### Responses **200** **200 OK** ```json { "result": true } ``` **400** **400 Bad Request** ```json { "error": "clonedVoiceItemId has incorrect format", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** ```json { "error": "No record found for user:12345-tempolor:user_id-voice:abcdef123456789", "code": 404 } ``` **596** **596 Account signed out** TemPolor signed the account out, so its session ticket no longer works. The API stops using the account until you add it again with fresh credentials at [POST accounts](/docs/api-tempolor-v1/post-tempolor-accounts), see [Setup TemPolor](/docs/start-here/setup-tempolor). Requests without `user_id` use your other accounts in the meantime. ```json { "error": "TemPolor signed out account 101441809 (You are currently logged out (400006)). Add it again with POST /v1/tempolor/accounts using fresh credentials, see https://useapi.net/docs/start-here/setup-tempolor", "code": 596 } ``` If every account you have is in this state, a request without `user_id` returns 596 as well. ##### Model A deleted cloned voice answers with `result: true`, and an error answers with its `error` message and `code`. <details markdown="block" class="model-details"> <summary>The delete answer, field by field</summary> ```typescript { // TypeScript, all fields are optional result: boolean error: string code: number } ``` </details> ##### Examples **Curl** ``` bash curl -X DELETE -H "Authorization: Bearer …" \ https://api.useapi.net/v1/tempolor/music/cloned-voices/user:12345-tempolor:user_id-voice:abcdef123456789 ``` **JavaScript** ``` javascript const clonedVoiceItemId = "user:12345-tempolor:user_id-voice:abcdef123456789"; const token = "API token"; const apiUrl = `https://api.useapi.net/v1/tempolor/music/cloned-voices/${clonedVoiceItemId}`; const response = await fetch(apiUrl, { method: "DELETE", headers: { "Authorization": `Bearer ${token}` } }); const result = await response.json(); console.log("Delete result:", result.result); ``` **Python** ``` python import requests cloned_voice_item_id = "user:12345-tempolor:user_id-voice:abcdef123456789" token = "API token" apiUrl = f"https://api.useapi.net/v1/tempolor/music/cloned-voices/{cloned_voice_item_id}" headers = { "Authorization": f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers) result = response.json() print(f"Delete result: {result.get('result')}") ``` === URL: https://useapi.net/docs/api-tempolor-v1/delete-tempolor-music-job_id === Document URL: https://useapi.net/docs/api-tempolor-v1/delete-tempolor-music-job_id --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> music/`job_id` description: "Delete a previously generated TemPolor music item by job_id via DELETE music/job_id in the useapi.net TemPolor API v1." parent: TemPolor API nav_order: 1100 --- ## Delete a music generation May 15, 2025 (November 16, 2026) --- This endpoint deletes a previously generated music item. > **https://api.useapi.net/v1/tempolor/music/`job_id`** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Path Parameters - `job_id` is **required**. The job returned from a previous [POST music/song](/docs/api-tempolor-v1/post-tempolor-music-song) or [POST music/instrumental](/docs/api-tempolor-v1/post-tempolor-music-instrumental) request. ##### Responses **200** **200 OK** ```json { "result": true } ``` **400** **400 Bad Request** ```json { "error": "job_id abc has incorrect format", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** TemPolor does not have this music item, for example because it was already deleted. ```json { "error": "<TemPolor error message> (<TemPolor code>)" } ``` **555** **555 TemPolor Error** TemPolor refused or failed the delete with an error that has no matching HTTP status. Since November 1, 2026, every failed delete returns TemPolor's own status and its error text, for example `401` when TemPolor rejects the account's session ticket, `404` above, or `555` here. Since November 2, 2026, an account TemPolor signed out answers `596` (it answered `555` before): add the account again with [POST /accounts](/docs/api-tempolor-v1/post-tempolor-accounts). Before November 1, 2026, a failed delete answered `200` with an empty `{}`. ```json { "error": "<TemPolor error message> (<TemPolor code>)" } ``` **596** **596 Account signed out** TemPolor signed the account out, so its session ticket no longer works. The API stops using the account until you add it again with fresh credentials at [POST accounts](/docs/api-tempolor-v1/post-tempolor-accounts), see [Setup TemPolor](/docs/start-here/setup-tempolor). Requests without `user_id` use your other accounts in the meantime. ```json { "error": "TemPolor signed out account 101441809 (You are currently logged out (400006)). Add it again with POST /v1/tempolor/accounts using fresh credentials, see https://useapi.net/docs/start-here/setup-tempolor", "code": 596 } ``` If every account you have is in this state, a request without `user_id` returns 596 as well. ##### Model A deleted music item answers with `result: true`, and an error answers with its `error` message and `code`. <details markdown="block" class="model-details"> <summary>The delete answer, field by field</summary> ```typescript { // TypeScript, all fields are optional result: boolean error: string code: number } ``` </details> ##### Examples **Curl** ``` bash curl -X DELETE -H "Authorization: Bearer …" \ https://api.useapi.net/v1/tempolor/music/user:12345-tempolor:user_id-job:abcdef123456789 ``` **JavaScript** ``` javascript const job_id = "user:12345-tempolor:user_id-job:abcdef123456789"; const token = "API token"; const apiUrl = `https://api.useapi.net/v1/tempolor/music/${job_id}`; const response = await fetch(apiUrl, { method: "DELETE", headers: { "Authorization": `Bearer ${token}` } }); const result = await response.json(); console.log("Delete result:", result.result); ``` **Python** ``` python import requests job_id = "user:12345-tempolor:user_id-job:abcdef123456789" token = "API token" apiUrl = f"https://api.useapi.net/v1/tempolor/music/{job_id}" headers = { "Authorization": f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers) result = response.json() print(f"Delete result: {result.get('result')}") ``` === URL: https://useapi.net/docs/api-tempolor-v1/delete-tempolor-music-midi-midiItemId === Document URL: https://useapi.net/docs/api-tempolor-v1/delete-tempolor-music-midi-midiItemId --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> music/midi description: "Delete a previously uploaded MIDI file by midiItemId via DELETE music/midi/midiItemId in the useapi.net TemPolor API v1." parent: TemPolor API nav_order: 1600 --- ## Delete a MIDI file May 15, 2025 (November 16, 2026) --- This endpoint deletes a previously uploaded MIDI file. > **https://api.useapi.net/v1/tempolor/music/midi/`midiItemId`** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Path Parameters - `midiItemId` is **required**. The MIDI file ID returned from a previous [POST music/midi](/docs/api-tempolor-v1/post-tempolor-music-midi) request. ##### Responses **200** **200 OK** ```json { "result": true } ``` **400** **400 Bad Request** ```json { "error": "midiItemId has incorrect format", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** ```json { "error": "No record found for user:12345-tempolor:user_id-midi:abcdef123456789", "code": 404 } ``` **596** **596 Account signed out** TemPolor signed the account out, so its session ticket no longer works. The API stops using the account until you add it again with fresh credentials at [POST accounts](/docs/api-tempolor-v1/post-tempolor-accounts), see [Setup TemPolor](/docs/start-here/setup-tempolor). Requests without `user_id` use your other accounts in the meantime. ```json { "error": "TemPolor signed out account 101441809 (You are currently logged out (400006)). Add it again with POST /v1/tempolor/accounts using fresh credentials, see https://useapi.net/docs/start-here/setup-tempolor", "code": 596 } ``` If every account you have is in this state, a request without `user_id` returns 596 as well. ##### Model A deleted MIDI file answers with `result: true`, and an error answers with its `error` message and `code`. <details markdown="block" class="model-details"> <summary>The delete answer, field by field</summary> ```typescript { // TypeScript, all fields are optional result: boolean error: string code: number } ``` </details> ##### Examples **Curl** ``` bash curl -X DELETE -H "Authorization: Bearer …" \ https://api.useapi.net/v1/tempolor/music/midi/user:12345-tempolor:user_id-midi:abcdef123456789 ``` **JavaScript** ``` javascript const midiItemId = "user:12345-tempolor:user_id-midi:abcdef123456789"; const token = "API token"; const apiUrl = `https://api.useapi.net/v1/tempolor/music/midi/${midiItemId}`; const response = await fetch(apiUrl, { method: "DELETE", headers: { "Authorization": `Bearer ${token}` } }); const result = await response.json(); console.log("Delete result:", result.result); ``` **Python** ``` python import requests midi_item_id = "user:12345-tempolor:user_id-midi:abcdef123456789" token = "API token" apiUrl = f"https://api.useapi.net/v1/tempolor/music/midi/{midi_item_id}" headers = { "Authorization": f"Bearer {token}" } response = requests.delete(apiUrl, headers=headers) result = response.json() print(f"Delete result: {result.get('result')}") ``` === URL: https://useapi.net/docs/api-tempolor-v1/get-tempolor-accounts-user_id === Document URL: https://useapi.net/docs/api-tempolor-v1/get-tempolor-accounts-user_id --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts/`user_id` description: "Retrieve configuration details for a specific TemPolor account by user_id via GET accounts/user_id in the useapi.net TemPolor API v1." parent: TemPolor API nav_order: 300 --- ## Retrieve TemPolor API account configuration for `user_id` May 15, 2025 (November 16, 2026) --- This endpoint retrieves the details of a specific TemPolor account. [Setup TemPolor](/docs/start-here/setup-tempolor) > **https://api.useapi.net/v1/tempolor/accounts/`user_id`** The `user_id` value should correspond to an account configured previously via a [POST accounts](/docs/api-tempolor-v1/post-tempolor-accounts) request. ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** ```json { "user_id": "user_id1", "updated": 1715791234567, "updatedUTC": "2025-05-15T14:30:34.567Z", "maxJobs": 10, "requestParams": {} } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** Configuration not found. To create configuration use [POST accounts](/docs/api-tempolor-v1/post-tempolor-accounts). ##### Model The account's configuration: its `user_id`, when it was last updated and its `maxJobs` limit. <details markdown="block" class="model-details"> <summary>The account's configuration, field by field</summary> ```typescript { // TypeScript user_id: string updated: number // timestamp in milliseconds updatedUTC: string // ISO date string maxJobs: number requestParams: {} } ``` </details> ##### Examples **Curl** ``` bash curl https://api.useapi.net/v1/tempolor/accounts/<user_id> \ -H "Accept: application/json" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const user_id = "Previously configured account"; const apiUrl = `https://api.useapi.net/v1/tempolor/accounts/${user_id}`; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}`, }, }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" user_id = "Previously configured account" apiUrl = f"https://api.useapi.net/v1/tempolor/accounts/{user_id}" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-tempolor-v1/get-tempolor-accounts === Document URL: https://useapi.net/docs/api-tempolor-v1/get-tempolor-accounts --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts description: "List all configured TemPolor API accounts via GET accounts in the useapi.net TemPolor API v1 — view each account's maxJobs and request settings." parent: TemPolor API nav_order: 200 --- ## Get List of Accounts May 15, 2025 (November 16, 2026) --- This endpoint retrieves the complete list of configured API accounts for TemPolor. [Setup TemPolor](/docs/start-here/setup-tempolor) > **https://api.useapi.net/v1/tempolor/accounts** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** ```json { "user_id1": { "user_id": "user_id1", "updated": 1715791234567, "updatedUTC": "2025-05-15T14:30:34.567Z", "maxJobs": 10, "requestParams": {} }, "user_id2": { "user_id": "user_id2", "updated": 1715791234567, "updatedUTC": "2025-05-15T14:30:34.567Z", "maxJobs": 20, "requestParams": {} } } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** Returned when no accounts are configured. ##### Model An object keyed by `user_id`, each holding that account's configuration as [GET accounts/`user_id`](/docs/api-tempolor-v1/get-tempolor-accounts-user_id) returns it. <details markdown="block" class="model-details"> <summary>The configuration of each account, field by field</summary> ```typescript { // TypeScript [user_id: string]: { user_id: string updated: number // timestamp in milliseconds updatedUTC: string // ISO date string maxJobs: number requestParams: {} } } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Authorization: Bearer …" \ -X GET https://api.useapi.net/v1/tempolor/accounts ``` **JavaScript** ``` javascript const apiUrl = `https://api.useapi.net/v1/tempolor/accounts`; const api_token = "API token"; const data = { method: 'GET', headers: { 'Authorization': `Bearer ${api_token}`, 'Content-Type': 'application/json' } }; const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests apiUrl = f"https://api.useapi.net/v1/tempolor/accounts" api_token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {api_token}" } response = requests.get(apiUrl, headers=headers) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-tempolor-v1/get-tempolor-music-artist-voices === Document URL: https://useapi.net/docs/api-tempolor-v1/get-tempolor-music-artist-voices --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> music/artist-voices description: "Browse predefined artist voices for song generation via GET music/artist-voices in the useapi.net TemPolor API v1 — use artistVoiceItemId in POST music/song." parent: TemPolor API nav_order: 1300 --- ## List artist voices May 15, 2025 (November 16, 2026) --- This endpoint retrieves a list of predefined artist voices that you can use for music generation without uploading your own voice samples. These artist voices can be used with [POST music/song](/docs/api-tempolor-v1/post-tempolor-music-song) by providing the `artistVoiceItemId` parameter. > **https://api.useapi.net/v1/tempolor/music/artist-voices/?...** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `user_id` is optional when only one [account](/docs/api-tempolor-v1/get-tempolor-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `cursor` is optional. Pagination cursor for fetching additional pages of results. ##### Responses **200** **200 OK** ```json { "records": [ { "ucid": "9999999", "bizType": "ai_voice_cloned", "itemId": "voice_12345", "name": "Deep Male Voice", "resourceUrl": "https://example.com/vocals/deep-male-sample.mp3", "coverUrl": "https://example.com/voice-covers/deep-male.jpg", "vocalUrl": "https://example.com/vocals/deep-male-sample.mp3", "weight": 100, "isAddRel": false, "relSource": "", "labels": ["male", "deep", "dramatic"] }, { "ucid": "9999999", "bizType": "ai_voice_cloned", "itemId": "voice_67890", "name": "Soprano Female Voice", "resourceUrl": "https://example.com/vocals/soprano-female-sample.mp3", "coverUrl": "https://example.com/voice-covers/soprano-female.jpg", "vocalUrl": "https://example.com/vocals/soprano-female-sample.mp3", "weight": 90, "isAddRel": false, "relSource": "", "labels": ["female", "soprano", "clear"] } ], "hasNext": false, "cursor": "", "sysTime": 1716565425000 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **596** **596 Account signed out** TemPolor signed the account out, so its session ticket no longer works. The API stops using the account until you add it again with fresh credentials at [POST accounts](/docs/api-tempolor-v1/post-tempolor-accounts), see [Setup TemPolor](/docs/start-here/setup-tempolor). Requests without `user_id` use your other accounts in the meantime. ```json { "error": "TemPolor signed out account 101441809 (You are currently logged out (400006)). Add it again with POST /v1/tempolor/accounts using fresh credentials, see https://useapi.net/docs/start-here/setup-tempolor", "code": 596 } ``` If every account you have is in this state, a request without `user_id` returns 596 as well. ##### Model A page of artist voices, each with its `itemId`, name, cover and sample audio, plus `hasNext` and `cursor` for paging. <details markdown="block" class="model-details"> <summary>The list of artist voices, field by field</summary> ```typescript { // TypeScript, all fields are optional records: { ucid: string bizType: string itemId: string name: string resourceUrl: string coverUrl: string vocalUrl: string weight: number isAddRel: boolean relSource: string labels: string[] }[] hasNext: boolean cursor: string sysTime: number error: string code: number } ``` </details> ##### Examples **Curl** ``` bash # List all artist voices curl -H "Authorization: Bearer …" \ https://api.useapi.net/v1/tempolor/music/artist-voices/?user_id=user_id # Paginate through results using cursor curl -H "Authorization: Bearer …" \ "https://api.useapi.net/v1/tempolor/music/artist-voices/?user_id=user_id&cursor=next_page_cursor_token" ``` **JavaScript** ``` javascript const token = "API token"; const user_id = "user_id"; const cursor = ""; // for pagination // Build the URL with query parameters let apiUrl = `https://api.useapi.net/v1/tempolor/music/artist-voices/?user_id=${user_id}`; if (cursor) apiUrl += `&cursor=${cursor}`; const response = await fetch(apiUrl, { method: "GET", headers: { "Authorization": `Bearer ${token}` } }); const result = await response.json(); console.log(`Found ${result.records?.length || 0} artist voices`); // Example of fetching all pages async function fetchAllArtistVoices(userId) { let allRecords = []; let nextCursor = ""; let hasMore = true; while (hasMore) { let url = `https://api.useapi.net/v1/tempolor/music/artist-voices/?user_id=${userId}`; if (nextCursor) url += `&cursor=${nextCursor}`; const response = await fetch(url, { method: "GET", headers: { "Authorization": `Bearer ${token}` } }); const data = await response.json(); if (data.records && data.records.length > 0) { allRecords = [...allRecords, ...data.records]; } hasMore = data.hasNext; nextCursor = data.cursor; // Break if no more pages or no cursor if (!hasMore || !nextCursor) break; } return allRecords; } ``` **Python** ``` python import requests token = "API token" user_id = "user_id" cursor = "" # for pagination # Build the URL with query parameters apiUrl = f"https://api.useapi.net/v1/tempolor/music/artist-voices/?user_id={user_id}" if cursor: apiUrl += f"&cursor={cursor}" headers = { "Authorization": f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) result = response.json() print(f"Found {len(result.get('records', []))} artist voices") # Example of fetching all pages def fetch_all_artist_voices(user_id): all_records = [] next_cursor = "" has_more = True while has_more: url = f"https://api.useapi.net/v1/tempolor/music/artist-voices/?user_id={user_id}" if next_cursor: url += f"&cursor={next_cursor}" response = requests.get(url, headers=headers) data = response.json() if data.get('records'): all_records.extend(data.get('records')) has_more = data.get('hasNext', False) next_cursor = data.get('cursor', "") # Break if no more pages or no cursor if not has_more or not next_cursor: break return all_records ``` === URL: https://useapi.net/docs/api-tempolor-v1/get-tempolor-music-cloned-voices === Document URL: https://useapi.net/docs/api-tempolor-v1/get-tempolor-music-cloned-voices --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> music/cloned-voices description: "List cloned voices you have created for use in song generation via GET music/cloned-voices in the useapi.net TemPolor API v1." parent: TemPolor API nav_order: 1800 --- ## List cloned voices May 15, 2025 (November 16, 2026) --- This endpoint retrieves a list of cloned voices that you've previously created using [POST music/cloned-voices](/docs/api-tempolor-v1/post-tempolor-music-cloned-voices). These cloned voices can be used in music generation with [POST music/song](/docs/api-tempolor-v1/post-tempolor-music-song). > **https://api.useapi.net/v1/tempolor/music/cloned-voices/?...** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `user_id` is optional when only one [account](/docs/api-tempolor-v1/get-tempolor-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `cursor` is optional. Pagination cursor for fetching additional pages of results. ##### Responses **200** **200 OK** ```json { "records": [ { "isAddRel": false, "relSource": "", "ucid": "user_id", "bizType": "user", "operatorType": "gen", "itemId": "abcdef123456789", "rootItemId": "abcdef123456789", "parentItemId": "abcdef123456789", "name": "My Custom Voice", "resourceUrl": "voice_cloned/audio/abcdef123456789.mp3", "coverUrl": "", "readStatus": 0, "status": 30, "vocalUrl": "https://example.com/cloned-voice/abcdef123456789.mp3", "createTime": 1716565425000, "updateTime": 1716565700000, "labels": [], "clonedVoiceItemId": "user:12345-tempolor:user_id-voice:abcdef123456789" }, { "isAddRel": false, "relSource": "", "ucid": "user_id", "bizType": "user", "operatorType": "gen", "itemId": "fedcba987654321", "rootItemId": "fedcba987654321", "parentItemId": "fedcba987654321", "name": "Second Voice Sample", "resourceUrl": "voice_cloned/audio/fedcba987654321.mp3", "coverUrl": "", "readStatus": 0, "status": 30, "vocalUrl": "https://example.com/cloned-voice/fedcba987654321.mp3", "createTime": 1716475425000, "updateTime": 1716475700000, "labels": [], "clonedVoiceItemId": "user:12345-tempolor:user_id-voice:fedcba987654321" } ], "hasNext": false, "cursor": "" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **596** **596 Account signed out** TemPolor signed the account out, so its session ticket no longer works. The API stops using the account until you add it again with fresh credentials at [POST accounts](/docs/api-tempolor-v1/post-tempolor-accounts), see [Setup TemPolor](/docs/start-here/setup-tempolor). Requests without `user_id` use your other accounts in the meantime. ```json { "error": "TemPolor signed out account 101441809 (You are currently logged out (400006)). Add it again with POST /v1/tempolor/accounts using fresh credentials, see https://useapi.net/docs/start-here/setup-tempolor", "code": 596 } ``` If every account you have is in this state, a request without `user_id` returns 596 as well. ##### Model A page of your cloned voices, each with its `clonedVoiceItemId`, name and sample audio, plus `hasNext` and `cursor` for paging. <details markdown="block" class="model-details"> <summary>The list of cloned voices, field by field</summary> ```typescript { // TypeScript, all fields are optional records: { isAddRel: boolean relSource: string ucid: string bizType: string operatorType: string itemId: string rootItemId: string parentItemId: string name: string resourceUrl: string coverUrl: string readStatus: number status: number vocalUrl: string createTime: number updateTime: number labels: string[] clonedVoiceItemId: string }[] hasNext: boolean cursor: string error: string code: number } ``` </details> ##### Examples **Curl** ``` bash # List all cloned voices curl -H "Authorization: Bearer …" \ https://api.useapi.net/v1/tempolor/music/cloned-voices?user_id=user_id # Paginate through results using cursor curl -H "Authorization: Bearer …" \ "https://api.useapi.net/v1/tempolor/music/cloned-voices?user_id=user_id&cursor=next_page_cursor_token" ``` **JavaScript** ``` javascript const token = "API token"; const user_id = "user_id"; const cursor = ""; // for pagination // Build the URL with query parameters let apiUrl = `https://api.useapi.net/v1/tempolor/music/cloned-voices?user_id=${user_id}`; if (cursor) apiUrl += `&cursor=${cursor}`; const response = await fetch(apiUrl, { method: "GET", headers: { "Authorization": `Bearer ${token}` } }); const result = await response.json(); console.log(`Found ${result.records?.length || 0} cloned voices`); // Example of fetching all pages async function fetchAllClonedVoices(userId) { let allRecords = []; let nextCursor = ""; let hasMore = true; while (hasMore) { let url = `https://api.useapi.net/v1/tempolor/music/cloned-voices?user_id=${userId}`; if (nextCursor) url += `&cursor=${nextCursor}`; const response = await fetch(url, { method: "GET", headers: { "Authorization": `Bearer ${token}` } }); const data = await response.json(); if (data.records && data.records.length > 0) { allRecords = [...allRecords, ...data.records]; } hasMore = data.hasNext; nextCursor = data.cursor; // Break if no more pages or no cursor if (!hasMore || !nextCursor) break; } return allRecords; } ``` **Python** ``` python import requests token = "API token" user_id = "user_id" cursor = "" # for pagination # Build the URL with query parameters apiUrl = f"https://api.useapi.net/v1/tempolor/music/cloned-voices?user_id={user_id}" if cursor: apiUrl += f"&cursor={cursor}" headers = { "Authorization": f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) result = response.json() print(f"Found {len(result.get('records', []))} cloned voices") # Example of fetching all pages def fetch_all_cloned_voices(user_id): all_records = [] next_cursor = "" has_more = True while has_more: url = f"https://api.useapi.net/v1/tempolor/music/cloned-voices?user_id={user_id}" if next_cursor: url += f"&cursor={next_cursor}" response = requests.get(url, headers=headers) data = response.json() if data.get('records'): all_records.extend(data.get('records')) has_more = data.get('hasNext', False) next_cursor = data.get('cursor', "") # Break if no more pages or no cursor if not has_more or not next_cursor: break return all_records ``` === URL: https://useapi.net/docs/api-tempolor-v1/get-tempolor-music-download-job_id === Document URL: https://useapi.net/docs/api-tempolor-v1/get-tempolor-music-download-job_id --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> music/download/`job_id` description: "Retrieve a download URL for a completed TemPolor music generation job via GET music/download/job_id in the useapi.net TemPolor API v1." parent: TemPolor API nav_order: 1200 --- ## Download generated music May 15, 2025 (November 16, 2026) --- This endpoint retrieves a download URL for a completed music generation job. The `job_id` must be from a successfully completed generation job that can be verified with [GET music/`job_id`](/docs/api-tempolor-v1/get-tempolor-music-job_id). > **https://api.useapi.net/v1/tempolor/music/download/`job_id`** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Path Parameters - `job_id` is **required**. The job returned from a previous [POST music/song](/docs/api-tempolor-v1/post-tempolor-music-song) or [POST music/instrumental](/docs/api-tempolor-v1/post-tempolor-music-instrumental) request. ##### Query Parameters - `file_format` is optional. Specifies the format of the generated music to download. Supported values: * `mp3` - MP3 format (default) * `wav` - WAV format (higher quality) * `stems` - ZIP archive containing separated stems (vocals, instruments, etc.) ##### Responses **200** **200 OK** ```json { "url": "https://ugc-cdn.api.instabeat.ai/ai_material/ai_material/mp3/abcdef123456789.mp3?auth_key=1747536678-0-0-9c67b3d5f8a2c41e0d7f6eab3f82fb45", "remainSeconds": 0 } ``` The download URL expires after `remainSeconds` seconds. **400** **400 Bad Request** ```json { "error": "Generation is not completed yet (0)", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** ```json { "error": "No record found for user:12345-tempolor:user_id-job:abcdef123456789", "code": 404 } ``` **596** **596 Account signed out** TemPolor signed the account out, so its session ticket no longer works. The API stops using the account until you add it again with fresh credentials at [POST accounts](/docs/api-tempolor-v1/post-tempolor-accounts), see [Setup TemPolor](/docs/start-here/setup-tempolor). Requests without `user_id` use your other accounts in the meantime. ```json { "error": "TemPolor signed out account 101441809 (You are currently logged out (400006)). Add it again with POST /v1/tempolor/accounts using fresh credentials, see https://useapi.net/docs/start-here/setup-tempolor", "code": 596 } ``` If every account you have is in this state, a request without `user_id` returns 596 as well. ##### Model The download `url` for the finished music, which expires after `remainSeconds` seconds. <details markdown="block" class="model-details"> <summary>The download link, field by field</summary> ```typescript { // TypeScript, all fields are optional url: string remainSeconds: number error: string code: number } ``` </details> ##### Examples **Curl** ``` bash # Download in MP3 format (default) curl -H "Authorization: Bearer …" \ https://api.useapi.net/v1/tempolor/music/download/user:12345-tempolor:user_id-job:abcdef123456789 # Download in WAV format (higher quality) curl -H "Authorization: Bearer …" \ "https://api.useapi.net/v1/tempolor/music/download/user:12345-tempolor:user_id-job:abcdef123456789?file_format=wav" # Download stems (separated vocal, instruments, etc.) curl -H "Authorization: Bearer …" \ "https://api.useapi.net/v1/tempolor/music/download/user:12345-tempolor:user_id-job:abcdef123456789?file_format=stems" ``` **JavaScript** ``` javascript const job_id = "user:12345-tempolor:user_id-job:abcdef123456789"; const token = "API token"; const file_format = "mp3"; // or "wav" or "stems" const apiUrl = `https://api.useapi.net/v1/tempolor/music/download/${job_id}?file_format=${file_format}`; const response = await fetch(apiUrl, { method: "GET", headers: { "Authorization": `Bearer ${token}` } }); const result = await response.json(); console.log("Download URL:", result.url); // Example of downloading the file async function downloadFile(downloadUrl, fileName) { const fileResponse = await fetch(downloadUrl); const blob = await fileResponse.blob(); // For browser environments const url = window.URL.createObjectURL(blob); const a = document.createElement('a'); a.style.display = 'none'; a.href = url; a.download = fileName; document.body.appendChild(a); a.click(); window.URL.revokeObjectURL(url); // For Node.js environments // const fs = require('fs'); // const buffer = Buffer.from(await blob.arrayBuffer()); // fs.writeFileSync(fileName, buffer); } // If the request was successful, download the file if (result.url) { const fileName = `tempolor-music-${Date.now()}.${file_format === 'stems' ? 'zip' : file_format}`; await downloadFile(result.url, fileName); } ``` **Python** ``` python import requests import os job_id = "user:12345-tempolor:user_id-job:abcdef123456789" token = "API token" file_format = "mp3" # or "wav" or "stems" apiUrl = f"https://api.useapi.net/v1/tempolor/music/download/{job_id}?file_format={file_format}" headers = { "Authorization": f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) result = response.json() print("Download URL:", result.get("url")) # Example of downloading the file def download_file(download_url, file_name): file_response = requests.get(download_url) with open(file_name, 'wb') as f: f.write(file_response.content) print(f"File downloaded as {file_name}") # If the request was successful, download the file if result.get("url"): if file_format == "stems": file_name = f"tempolor-music-{job_id.split(':')[-1]}.zip" else: file_name = f"tempolor-music-{job_id.split(':')[-1]}.{file_format}" download_file(result.get("url"), file_name) ``` === URL: https://useapi.net/docs/api-tempolor-v1/get-tempolor-music-job_id === Document URL: https://useapi.net/docs/api-tempolor-v1/get-tempolor-music-job_id --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> music/`job_id` description: "Poll the status and results of a music generation job by job_id via GET music/job_id in the useapi.net TemPolor API v1 — status values and a live Try It console." parent: TemPolor API nav_order: 1000 --- ## Check music generation status and results May 15, 2025 (November 16, 2026) --- This endpoint checks the status of a previously submitted music generation job. The `job_id` is returned from [POST music/song](/docs/api-tempolor-v1/post-tempolor-music-song) or [POST music/instrumental](/docs/api-tempolor-v1/post-tempolor-music-instrumental). > **https://api.useapi.net/v1/tempolor/music/`job_id`** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Path Parameters - `job_id` is **required**. The job returned from a previous [POST music/song](/docs/api-tempolor-v1/post-tempolor-music-song) or [POST music/instrumental](/docs/api-tempolor-v1/post-tempolor-music-instrumental) request. ##### Status Values The response includes a `status` field with the following possible values: | status | status_name | status_final | Description | |--------|-------------|--------------|------------------------------------------| | 0…9 | GENERATING | False | The music is still being generated | | 10…29 | FAILED | True | The music generation has failed, e.g. `11` failed on TemPolor's side, `12` rejected by content moderation | | 30+ | COMPLETED | True | The music has been successfully generated| A failed generation can be retried on the TemPolor website, where it keeps the same `job_id`. Otherwise submit a new request. When the status is COMPLETED, you can download the music using the [GET music/download/`job_id`](/docs/api-tempolor-v1/get-tempolor-music-download-job_id) endpoint. ##### Responses **200** **200 OK** <details markdown="block"> <summary>Example Response</summary> ```json { "bizType": "ai_material_music", "childType": "lyric_to_material", "matChildType": "lyric_to_material", "sourceType": "sm_user_gen", "itemId": "abcdef123456789", "job_id": "user:12345-tempolor:user_id-job:abcdef123456789", "genItemId": "abcdef123456789", "userId": "user_id", "titleEn": "Epic Orchestral", "cover": "https://example.com/cover.png", "mp3OssId": "ai_material/ai_material/mp3/abcdef123456789.mp3", "wavOssId": "ai_material/ai_material/wav/abcdef123456789.wav", "ossWatermarkMp3": "", "officialPlaylistSong": false, "status": 30, "status_name": "COMPLETED", "status_final": true, "progress": 100, "downloadTotal": 0, "likeTotal": 0, "collectTotal": 0, "musicMaterial": { "style": "Orchestral", "chord": "", "mood": "", "inst": "", "instInfo": "", "scene": "", "otherInfo": "A cinematic orchestral piece with dramatic string sections", "otherInfoCn": "", "key": "F:minor", "bpm": 130, "dur": 180, "seed": 1234567890, "waveformUrl": "https://example.com/waveform.json" }, "readStatus": false, "downloadStatus": false, "createTime": 1716565425000, "updateTime": 1716565700000, "materialQualityScore": 0, "ltmMaterialExtendDto": { "lyricsPrompt": "Sample lyrics here", "description": "A cinematic orchestral piece with dramatic string sections", "ltmVocalModel": false, "ltmMidiModel": false, "genItemId": "abcdef123456789", "prompt": "A cinematic orchestral piece with dramatic string sections", "genMode": 0, "model": "tempolor-2s-v5", "modelShowName": "v4.8" }, "editType": "gen", "operatorType": "gen", "rootItemId": "abcdef123456789", "parentItemId": "abcdef123456789", "canExtend": true, "canEditLyrics": true, "canFixVocals": true, "canReplaced": false } ``` </details> **400** **400 Bad Request** ```json { "error": "job_id has incorrect format", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **404** **404 Not Found** ```json { "error": "No record found for user:12345-tempolor:user_id-job:abcdef123456789", "code": 404 } ``` **596** **596 Account signed out** TemPolor signed the account out, so its session ticket no longer works. The API stops using the account until you add it again with fresh credentials at [POST accounts](/docs/api-tempolor-v1/post-tempolor-accounts), see [Setup TemPolor](/docs/start-here/setup-tempolor). Requests without `user_id` use your other accounts in the meantime. ```json { "error": "TemPolor signed out account 101441809 (You are currently logged out (400006)). Add it again with POST /v1/tempolor/accounts using fresh credentials, see https://useapi.net/docs/start-here/setup-tempolor", "code": 596 } ``` If every account you have is in this state, a request without `user_id` returns 596 as well. ##### Model The music job record, with `status_name`, `status_final` and `progress`, its cover, and musical details such as style, key and BPM. <details markdown="block" class="model-details"> <summary>The music job record, field by field</summary> ```typescript { // TypeScript, all fields are optional bizType: string childType: string matChildType: string sourceType: string itemId: string job_id: string genItemId: string userId: string titleEn: string cover: string mp3OssId: string wavOssId: string ossWatermarkMp3: string status: number status_name: string // "GENERATING", "FAILED", "COMPLETED" status_final: boolean progress: number downloadTotal: number likeTotal: number collectTotal: number musicMaterial: { style: string chord: string mood: string inst: string instInfo: string scene: string otherInfo: string otherInfoCn: string key: string bpm: number dur: number seed: number } createTime: number updateTime: number ltmMaterialExtendDto: { lyricsPrompt: string description: string prompt: string genMode: number model: string } editType: string operatorType: string canExtend: boolean error: string code: number } ``` </details> ##### Examples **Curl** ``` bash curl -H "Authorization: Bearer …" \ https://api.useapi.net/v1/tempolor/music/user:12345-tempolor:user_id-job:abcdef123456789 ``` **JavaScript** ``` javascript const job_id = "user:12345-tempolor:user_id-job:abcdef123456789"; const token = "API token"; const apiUrl = `https://api.useapi.net/v1/tempolor/music/${job_id}`; const response = await fetch(apiUrl, { method: "GET", headers: { "Authorization": `Bearer ${token}` } }); const result = await response.json(); console.log("response", {response, result}); // Polling example - check status every 10 seconds until completed or failed async function pollJobStatus(job_id) { const apiUrl = `https://api.useapi.net/v1/tempolor/music/${job_id}`; while (true) { const response = await fetch(apiUrl, { method: "GET", headers: { "Authorization": `Bearer ${token}` } }); const result = await response.json(); console.log(`Job status: ${result.status_name}, Progress: ${result.progress}%`); if (result.status_final) { console.log(`Music generation ${result.status_name.toLowerCase()}`); return result; } // Wait 10 seconds before checking again await new Promise(resolve => setTimeout(resolve, 10000)); } } ``` **Python** ``` python import requests import time job_id = "user:12345-tempolor:user_id-job:abcdef123456789" token = "API token" apiUrl = f"https://api.useapi.net/v1/tempolor/music/{job_id}" headers = { "Authorization": f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) print(response.status_code, response.json()) # Polling example - check status every 10 seconds until completed or failed def poll_job_status(job_id): apiUrl = f"https://api.useapi.net/v1/tempolor/music/{job_id}" while True: response = requests.get(apiUrl, headers=headers) result = response.json() print(f"Job status: {result.get('status_name')}, Progress: {result.get('progress')}%") if result.get('status_final'): print(f"Music generation {result.get('status_name').lower()}") return result # Wait 10 seconds before checking again time.sleep(10) ``` === URL: https://useapi.net/docs/api-tempolor-v1/get-tempolor-music-midi === Document URL: https://useapi.net/docs/api-tempolor-v1/get-tempolor-music-midi --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> music/midi description: "List uploaded MIDI files available as generation templates via GET music/midi in the useapi.net TemPolor API v1 — use midiItemId with POST music/song." parent: TemPolor API nav_order: 1500 --- ## List MIDI files May 15, 2025 (November 16, 2026) --- This endpoint retrieves a list of MIDI files that you've previously uploaded using [POST music/midi](/docs/api-tempolor-v1/post-tempolor-music-midi). These MIDI files can be used as templates for music generation with [POST music/song](/docs/api-tempolor-v1/post-tempolor-music-song). > **https://api.useapi.net/v1/tempolor/music/midi/?...** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `user_id` is optional when only one [account](/docs/api-tempolor-v1/get-tempolor-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `cursor` is optional. Pagination cursor for fetching additional pages of results. ##### Responses **200** **200 OK** ```json { "records": [ { "opType": "upload", "ucid": "user_id", "midiItemId": "user:12345-tempolor:user_id-midi:abcdef123456789", "name": "Piano Composition", "midiUrl": "https://ugc-cdn.api.instabeat.ai/midi/file/abcdef123456789.mid" }, { "opType": "upload", "ucid": "user_id", "midiItemId": "user:12345-tempolor:user_id-midi:fedcba987654321", "name": "Guitar Progression", "midiUrl": "https://ugc-cdn.api.instabeat.ai/midi/file/fedcba987654321.mid" } ], "hasNext": false, "cursor": "" } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **596** **596 Account signed out** TemPolor signed the account out, so its session ticket no longer works. The API stops using the account until you add it again with fresh credentials at [POST accounts](/docs/api-tempolor-v1/post-tempolor-accounts), see [Setup TemPolor](/docs/start-here/setup-tempolor). Requests without `user_id` use your other accounts in the meantime. ```json { "error": "TemPolor signed out account 101441809 (You are currently logged out (400006)). Add it again with POST /v1/tempolor/accounts using fresh credentials, see https://useapi.net/docs/start-here/setup-tempolor", "code": 596 } ``` If every account you have is in this state, a request without `user_id` returns 596 as well. ##### Model A page of your uploaded MIDI files, each with its `midiItemId`, name and `midiUrl`, plus `hasNext` and `cursor` for paging. <details markdown="block" class="model-details"> <summary>The list of MIDI files, field by field</summary> ```typescript { // TypeScript, all fields are optional records: { opType: string ucid: string midiItemId: string name: string midiUrl: string midiType?: string midiValue?: string }[] hasNext: boolean cursor: string error: string code: number } ``` </details> ##### Examples **Curl** ``` bash # List all MIDI files curl -H "Authorization: Bearer …" \ https://api.useapi.net/v1/tempolor/music/midi/?user_id=user_id # Paginate through results using cursor curl -H "Authorization: Bearer …" \ "https://api.useapi.net/v1/tempolor/music/midi/?user_id=user_id&cursor=next_page_cursor_token" ``` **JavaScript** ``` javascript const token = "API token"; const user_id = "user_id"; const cursor = ""; // for pagination // Build the URL with query parameters let apiUrl = `https://api.useapi.net/v1/tempolor/music/midi/?user_id=${user_id}`; if (cursor) apiUrl += `&cursor=${cursor}`; const response = await fetch(apiUrl, { method: "GET", headers: { "Authorization": `Bearer ${token}` } }); const result = await response.json(); console.log(`Found ${result.records?.length || 0} MIDI files`); // Example of fetching all pages async function fetchAllMidiFiles(userId) { let allRecords = []; let nextCursor = ""; let hasMore = true; while (hasMore) { let url = `https://api.useapi.net/v1/tempolor/music/midi/?user_id=${userId}`; if (nextCursor) url += `&cursor=${nextCursor}`; const response = await fetch(url, { method: "GET", headers: { "Authorization": `Bearer ${token}` } }); const data = await response.json(); if (data.records && data.records.length > 0) { allRecords = [...allRecords, ...data.records]; } hasMore = data.hasNext; nextCursor = data.cursor; // Break if no more pages or no cursor if (!hasMore || !nextCursor) break; } return allRecords; } ``` **Python** ``` python import requests token = "API token" user_id = "user_id" cursor = "" # for pagination # Build the URL with query parameters apiUrl = f"https://api.useapi.net/v1/tempolor/music/midi/?user_id={user_id}" if cursor: apiUrl += f"&cursor={cursor}" headers = { "Authorization": f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) result = response.json() print(f"Found {len(result.get('records', []))} MIDI files") # Example of fetching all pages def fetch_all_midi_files(user_id): all_records = [] next_cursor = "" has_more = True while has_more: url = f"https://api.useapi.net/v1/tempolor/music/midi/?user_id={user_id}" if next_cursor: url += f"&cursor={next_cursor}" response = requests.get(url, headers=headers) data = response.json() if data.get('records'): all_records.extend(data.get('records')) has_more = data.get('hasNext', False) next_cursor = data.get('cursor', "") # Break if no more pages or no cursor if not has_more or not next_cursor: break return all_records ``` === URL: https://useapi.net/docs/api-tempolor-v1/get-tempolor-music === Document URL: https://useapi.net/docs/api-tempolor-v1/get-tempolor-music --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> music description: "List previously generated music jobs with type filtering and cursor pagination via GET music in the useapi.net TemPolor API v1." parent: TemPolor API nav_order: 900 --- ## List music generation jobs May 15, 2025 (November 16, 2026) --- This endpoint retrieves a list of previously generated music items. You can filter the results by type and paginate through them using the cursor parameter. > **https://api.useapi.net/v1/tempolor/music/?...** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Query Parameters - `user_id` is optional when only one [account](/docs/api-tempolor-v1/get-tempolor-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `type` is optional. Filter results by the type of music generation. Supported values: * `song` - Show music with vocals (default) * `instrumental` - Show instrumental music only - `cursor` is optional. Pagination cursor for fetching additional pages of results. ##### Responses **200** **200 OK** <details markdown="block"> <summary>Example Response</summary> ```json { "records": [ { "bizType": "ai_material_music", "childType": "lyric_to_material", "matChildType": "lyric_to_material", "sourceType": "sm_user_gen", "itemId": "abcdef123456789", "job_id": "user:12345-tempolor:user_id-job:abcdef123456789", "genItemId": "abcdef123456789", "userId": "user_id", "titleEn": "Epic Orchestral", "cover": "https://example.com/cover.png", "mp3OssId": "ai_material/ai_material/mp3/abcdef123456789.mp3", "wavOssId": "ai_material/ai_material/wav/abcdef123456789.wav", "ossWatermarkMp3": "", "officialPlaylistSong": false, "status": 30, "status_name": "COMPLETED", "status_final": true, "progress": 100, "downloadTotal": 0, "likeTotal": 0, "collectTotal": 0, "musicMaterial": { "style": "Orchestral", "chord": "", "mood": "", "inst": "", "instInfo": "", "scene": "", "otherInfo": "A cinematic orchestral piece with dramatic string sections", "otherInfoCn": "", "key": "F:minor", "bpm": 130, "dur": 180, "seed": 1234567890, "waveformUrl": "https://example.com/waveform.json" }, "readStatus": false, "downloadStatus": false, "createTime": 1716565425000, "updateTime": 1716565700000, "materialQualityScore": 0, "ltmMaterialExtendDto": { "lyricsPrompt": "Sample lyrics here", "description": "A cinematic orchestral piece with dramatic string sections", "ltmVocalModel": false, "ltmMidiModel": false, "genItemId": "abcdef123456789", "prompt": "A cinematic orchestral piece with dramatic string sections", "genMode": 0, "model": "tempolor-2s-v5", "modelShowName": "v4.8" }, "editType": "gen", "operatorType": "gen", "rootItemId": "abcdef123456789", "parentItemId": "abcdef123456789", "canExtend": true, "canEditLyrics": true, "canFixVocals": true, "canReplaced": false } ], "hasNext": true, "cursor": "next_page_cursor_token" } ``` </details> **400** **400 Bad Request** ```json { "error": "Invalid type parameter. Must be 'song' or 'instrumental'", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **596** **596 Account signed out** TemPolor signed the account out, so its session ticket no longer works. The API stops using the account until you add it again with fresh credentials at [POST accounts](/docs/api-tempolor-v1/post-tempolor-accounts), see [Setup TemPolor](/docs/start-here/setup-tempolor). Requests without `user_id` use your other accounts in the meantime. ```json { "error": "TemPolor signed out account 101441809 (You are currently logged out (400006)). Add it again with POST /v1/tempolor/accounts using fresh credentials, see https://useapi.net/docs/start-here/setup-tempolor", "code": 596 } ``` If every account you have is in this state, a request without `user_id` returns 596 as well. ##### Model A page of your music jobs, each with its `job_id`, status, cover and musical details, plus `hasNext` and `cursor` for paging. <details markdown="block" class="model-details"> <summary>The list of music jobs, field by field</summary> ```typescript { // TypeScript, all fields are optional records: { bizType: string childType: string matChildType: string sourceType: string itemId: string job_id: string genItemId: string userId: string titleEn: string cover: string mp3OssId: string wavOssId: string ossWatermarkMp3: string officialPlaylistSong: boolean status: number status_name: string status_final: boolean progress: number downloadTotal: number likeTotal: number collectTotal: number musicMaterial: { style: string chord: string mood: string inst: string instInfo: string scene: string otherInfo: string otherInfoCn: string key: string bpm: number dur: number seed: number src: string ossSrc: string waveformOssId: string waveformUrl: string batchId: string } readStatus: boolean downloadStatus: boolean createTime: number updateTime: number materialQualityScore: number ltmMaterialExtendDto: { lyricsPrompt: string description: string ltmVocalModel: boolean ltmMidiModel: boolean lrcTimestamp: string genItemId: string prompt: string genMode: number model: string modelShowName: string dynamicModel: string oriCacheDir: string } editType: string operatorType: string rootItemId: string parentItemId: string canExtend: boolean canEditLyrics: boolean canFixVocals: boolean canReplaced: boolean }[] hasNext: boolean cursor: string error: string code: number } ``` </details> ##### Examples **Curl** ``` bash # List all song generations (default) curl -H "Authorization: Bearer …" \ https://api.useapi.net/v1/tempolor/music/?user_id=user_id # List only instrumental music curl -H "Authorization: Bearer …" \ https://api.useapi.net/v1/tempolor/music/?user_id=user_id&type=instrumental # Paginate through results using cursor curl -H "Authorization: Bearer …" \ "https://api.useapi.net/v1/tempolor/music/?user_id=user_id&cursor=next_page_cursor_token" ``` **JavaScript** ``` javascript const token = "API token"; const user_id = "user_id"; const type = "song"; // or "instrumental" const cursor = ""; // for pagination // Build the URL with query parameters let apiUrl = `https://api.useapi.net/v1/tempolor/music/?user_id=${user_id}`; if (type) apiUrl += `&type=${type}`; if (cursor) apiUrl += `&cursor=${cursor}`; const response = await fetch(apiUrl, { method: "GET", headers: { "Authorization": `Bearer ${token}` } }); const result = await response.json(); console.log(`Found ${result.records?.length || 0} music items`); // Example of fetching all pages async function fetchAllMusicItems(userId, type) { let allRecords = []; let nextCursor = ""; let hasMore = true; while (hasMore) { let url = `https://api.useapi.net/v1/tempolor/music/?user_id=${userId}`; if (type) url += `&type=${type}`; if (nextCursor) url += `&cursor=${nextCursor}`; const response = await fetch(url, { method: "GET", headers: { "Authorization": `Bearer ${token}` } }); const data = await response.json(); if (data.records && data.records.length > 0) { allRecords = [...allRecords, ...data.records]; } hasMore = data.hasNext; nextCursor = data.cursor; // Break if no more pages or no cursor if (!hasMore || !nextCursor) break; } return allRecords; } ``` **Python** ``` python import requests token = "API token" user_id = "user_id" type_param = "song" # or "instrumental" cursor = "" # for pagination # Build the URL with query parameters apiUrl = f"https://api.useapi.net/v1/tempolor/music/?user_id={user_id}" if type_param: apiUrl += f"&type={type_param}" if cursor: apiUrl += f"&cursor={cursor}" headers = { "Authorization": f"Bearer {token}" } response = requests.get(apiUrl, headers=headers) result = response.json() print(f"Found {len(result.get('records', []))} music items") # Example of fetching all pages def fetch_all_music_items(user_id, type_param=None): all_records = [] next_cursor = "" has_more = True while has_more: url = f"https://api.useapi.net/v1/tempolor/music/?user_id={user_id}" if type_param: url += f"&type={type_param}" if next_cursor: url += f"&cursor={next_cursor}" response = requests.get(url, headers=headers) data = response.json() if data.get('records'): all_records.extend(data.get('records')) has_more = data.get('hasNext', False) next_cursor = data.get('cursor', "") # Break if no more pages or no cursor if not has_more or not next_cursor: break return all_records ``` === URL: https://useapi.net/docs/api-tempolor-v1/get-tempolor-scheduler-available === Document URL: https://useapi.net/docs/api-tempolor-v1/get-tempolor-scheduler-available --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> scheduler/available description: "Check available generation capacity and currently active jobs across all configured accounts via GET scheduler/available in the useapi.net TemPolor API v1." parent: TemPolor API nav_order: 2000 --- ## Get available capacity May 15, 2025 (November 16, 2026) --- Get information about currently executing jobs and available capacity for all configured accounts. > **https://api.useapi.net/v1/tempolor/scheduler/available** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** The response contains information about currently executing jobs and available capacity. ```json { "executing": [ { "job_id": "user:12345-tempolor:12345-job:abcdef123456789", "started": "2025-05-15T12:34:56.789Z", "elapsed": "01:23", "replyUrl": "https://example.com/callback", "replyRef": "my-reference" } ], "available": [ { "user_id": "12345", "maxJobs": 10, "executing": 1, "available": 9 }, { "user_id": "67890", "maxJobs": 5, "executing": 0, "available": 5 } ] } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model The jobs running now, and for each account its `maxJobs`, running count and `available` job slots. <details markdown="block" class="model-details"> <summary>The running jobs and each account's free capacity, field by field</summary> ```typescript { executing: [ // Currently executing jobs { job_id: string started: string // ISO timestamp when the job started elapsed: string // Time elapsed since start in MM:SS format replyUrl?: string // Optional callback URL if specified during job creation replyRef?: string // Optional reference if specified during job creation } ], available: [ // Accounts with available capacity { user_id: string // Account identifier maxJobs: number // Maximum concurrent jobs allowed for this account executing: number // Number of currently executing jobs available: number // Number of available job slots (maxJobs - executing) } ] } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/tempolor/scheduler/available" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = "https://api.useapi.net/v1/tempolor/scheduler/available"; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}` } }); const result = await response.json(); console.log("Scheduler info:", result); // Find account with most available capacity if (result.available && result.available.length > 0) { const bestAccount = result.available[0]; // Sorted by availability console.log(`Best account to use: ${bestAccount.user_id} (${bestAccount.available} slots available)`); } ``` **Python** ``` python import requests token = "API token" api_url = "https://api.useapi.net/v1/tempolor/scheduler/available" headers = { 'Authorization': f'Bearer {token}' } response = requests.get(api_url, headers=headers) result = response.json() print("Scheduler info:", result) # Find account with most available capacity if result.get('available') and len(result['available']) > 0: best_account = result['available'][0] # Sorted by availability print(f"Best account to use: {best_account['user_id']} ({best_account['available']} slots available)") ``` === URL: https://useapi.net/docs/api-tempolor-v1/get-tempolor-scheduler === Document URL: https://useapi.net/docs/api-tempolor-v1/get-tempolor-scheduler --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> scheduler description: "List all currently executing TemPolor music generation jobs via GET scheduler in the useapi.net TemPolor API v1." parent: TemPolor API nav_order: 1900 --- ## List scheduled jobs May 15, 2025 (November 16, 2026) --- Get a list of currently executing music generation jobs. > **https://api.useapi.net/v1/tempolor/scheduler/** ##### Request Headers ``` yaml Authorization: Bearer {API token} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Responses **200** **200 OK** The response contains an array of currently executing music generation jobs. ```json [ { "job_id": "user:12345-tempolor:user_id-job:abcdef123456789", "started": "2025-05-15T12:34:56.789Z", "elapsed": "01:23", "replyUrl": "https://example.com/callback", "replyRef": "my-reference" } ] ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` ##### Model An array of the music jobs running now, each with its `job_id`, start time and elapsed time. <details markdown="block" class="model-details"> <summary>The list of running jobs, field by field</summary> ```typescript [ { // TypeScript representation of each job job_id: string started: string // ISO timestamp when the job started elapsed: string // Time elapsed since start in MM:SS format replyUrl?: string // Optional callback URL if specified during job creation replyRef?: string // Optional reference if specified during job creation } ] ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/tempolor/scheduler/" \ -H "Authorization: Bearer …" ``` **JavaScript** ``` javascript const token = "API token"; const apiUrl = "https://api.useapi.net/v1/tempolor/scheduler/"; const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}` } }); const result = await response.json(); console.log("Current jobs:", result); ``` **Python** ``` python import requests token = "API token" api_url = "https://api.useapi.net/v1/tempolor/scheduler/" headers = { 'Authorization': f'Bearer {token}' } response = requests.get(api_url, headers=headers) result = response.json() print("Current jobs:", result) ``` === URL: https://useapi.net/docs/api-tempolor-v1/post-tempolor-accounts === Document URL: https://useapi.net/docs/api-tempolor-v1/post-tempolor-accounts --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> accounts description: "Configure a TemPolor API account with credentials via POST accounts in the useapi.net TemPolor API v1 — required before generating music." parent: TemPolor API nav_order: 100 --- ## Create or update TemPolor API account May 15, 2025 (November 16, 2026) --- This endpoint configures a TemPolor API account with the provided credentials. [Setup TemPolor](/docs/start-here/setup-tempolor) > **https://api.useapi.net/v1/tempolor/accounts** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "requestParams": {}, "maxJobs": 10 } ``` - `requestParams` is **required**, see [Setup TemPolor](/docs/start-here/setup-tempolor) for details on how to obtain it. - `maxJobs` is optional, the maximum number of concurrent jobs allowed for this account. Default is 10. ##### Responses **200** **200 OK** ```json { "user_id": "123456789", "updated": 1715791234567, "updatedUTC": "2025-05-15T14:30:34.567Z", "maxJobs": 10, "requestParams": {} } ``` **400** **400 Bad Request** ```json { "error": "Parameter requestParams is required", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **402** **402 Payment Required** ```json { "error": "Subscription required", "code": 402 } ``` ##### Model The saved account, in the same shape as [GET accounts/`user_id`](/docs/api-tempolor-v1/get-tempolor-accounts-user_id): its `user_id`, update time and `maxJobs`. <details markdown="block" class="model-details"> <summary>The saved account configuration, field by field</summary> ```typescript { // TypeScript user_id: string updated: number // timestamp in milliseconds updatedUTC: string // ISO date string maxJobs: number requestParams: {} } ``` </details> ##### Examples **Curl** ``` bash curl -X POST https://api.useapi.net/v1/tempolor/accounts \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "requestParams": {}, "maxJobs": 10 }' ``` **JavaScript** ``` javascript const apiUrl = `https://api.useapi.net/v1/tempolor/accounts`; const api_token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${api_token}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ requestParams: {}, maxJobs: 10 }) }; const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests import json apiUrl = "https://api.useapi.net/v1/tempolor/accounts" api_token = "API token" headers = { "Content-Type": "application/json", "Authorization": f"Bearer {api_token}" } payload = { "requestParams": {}, "maxJobs": 10 } response = requests.post(apiUrl, headers=headers, data=json.dumps(payload)) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-tempolor-v1/post-tempolor-music-cloned-voices === Document URL: https://useapi.net/docs/api-tempolor-v1/post-tempolor-music-cloned-voices --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> music/cloned-voices description: "Upload an audio sample to clone a voice for use in song generation via POST music/cloned-voices in the useapi.net TemPolor API v1." parent: TemPolor API nav_order: 1700 --- ## Upload voice sample for cloning May 15, 2025 (November 16, 2026) --- This endpoint uploads an audio sample for voice cloning, which can then be used in the [POST music/song](/docs/api-tempolor-v1/post-tempolor-music-song) endpoint to generate vocals with your cloned voice. [POST raw content using Make.com and similar nocode tools.](/docs/questions-and-answers#how-post-raw-content-to-runwaymlassets-and-minimaxfiles-using-makecom-and-similar-nocode-tools) > **https://api.useapi.net/v1/tempolor/music/cloned-voices/?...** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: {audio content-type} ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. - `Content-Type` is **required**, select from the table below: | Content-Type | File Extension | | ------------ | -------------- | | audio/mp4 | m4a | | audio/x-m4a | m4a | | audio/mpeg | mp3 | | audio/wav | wav | | audio/wave | wav | | audio/flac | flac | | audio/x-flac | flac | ##### Query Parameters - `user_id` is optional when only one [account](/docs/api-tempolor-v1/get-tempolor-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `name` is **required**. Specify a name for your cloned voice. ##### Responses **200** **200 OK** The cloned voice is immediately available to use in [POST music/song](/docs/api-tempolor-v1/post-tempolor-music-song) by providing the returned `clonedVoiceItemId`. ```json { "result": true, "itemId": "abcdef123456789", "clonedVoiceItemId": "user:12345-tempolor:user_id-voice:abcdef123456789" } ``` **202** **202 Accepted** The voice cloning process is still in progress. Check back later using [GET music/cloned-voices](/docs/api-tempolor-v1/get-tempolor-music-cloned-voices) to see if the voice is ready. ```json { "itemId": "abcdef123456789", "clonedVoiceItemId": "user:12345-tempolor:user_id-voice:abcdef123456789", "message": "Voice cloning is still processing after 120 seconds. Please check back later." } ``` **400** **400 Bad Request** ```json { "error": "Empty file received", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **596** **596 Account signed out** TemPolor signed the account out, so its session ticket no longer works. The API stops using the account until you add it again with fresh credentials at [POST accounts](/docs/api-tempolor-v1/post-tempolor-accounts), see [Setup TemPolor](/docs/start-here/setup-tempolor). Requests without `user_id` use your other accounts in the meantime. ```json { "error": "TemPolor signed out account 101441809 (You are currently logged out (400006)). Add it again with POST /v1/tempolor/accounts using fresh credentials, see https://useapi.net/docs/start-here/setup-tempolor", "code": 596 } ``` If every account you have is in this state, a request without `user_id` returns 596 as well. ##### Model The new cloned voice's `clonedVoiceItemId`, to pass to [POST music/song](/docs/api-tempolor-v1/post-tempolor-music-song), with `result` and a `message`. <details markdown="block" class="model-details"> <summary>The new cloned voice, field by field</summary> ```typescript { // TypeScript, all fields are optional result: boolean itemId: string clonedVoiceItemId: string message: string error: string code: number } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/tempolor/music/cloned-voices/?name=my-custom-voice&user_id=<user_id>" \ -H "Authorization: Bearer …" \ -H "Content-Type: audio/mpeg" \ --data-binary @/path/to/your/voice-sample.mp3 ``` **JavaScript** ``` javascript const token = "API token"; const user_id = "Previously configured account"; const name = "Your voice name"; const apiUrl = `https://api.useapi.net/v1/tempolor/music/cloned-voices/?name=${name}&user_id=${user_id}`; let blob; /* // Example 1: Fetch audio from URL const audioUrl = "https://example.com/audio-samples/voice-sample.mp3"; const responseAudio = await fetch(audioUrl); blob = await responseAudio.blob(); */ /* // Example 2: Load audio from local file (Node.js) const fs = require('fs'); const audioFileName = "./voice-sample.mp3"; blob = new Blob([fs.readFileSync(audioFileName)]); */ /* // Example 3: Load from input file html element // <input id="audio-file" type="file"> const audioFile = document.getElementById(`audio-file`); if (audioFile.files[0]) blob = audioFile.files[0]; */ const response = await fetch(apiUrl, { method: "POST", headers: { "Authorization": `Bearer ${token}`, "Content-Type": "audio/mpeg" // Adjust based on your file type }, body: blob }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" user_id = "Previously configured account" name = "Your voice name" apiUrl = f"https://api.useapi.net/v1/tempolor/music/cloned-voices/?name={name}&user_id={user_id}" headers = { 'Authorization': f'Bearer {token}', 'Content-Type': 'audio/mpeg' # Adjust based on your file type } # # Example 1: Fetch audio from URL # audio_url = "https://example.com/audio-samples/voice-sample.mp3" # response_audio = requests.get(audio_url) # file_content = response_audio.content # # Example 2: Load audio from local file audio_file_path = "./voice-sample.mp3" with open(audio_file_path, 'rb') as audio_file: file_content = audio_file.read() response = requests.post(apiUrl, headers=headers, data=file_content) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-tempolor-v1/post-tempolor-music-instrumental === Document URL: https://useapi.net/docs/api-tempolor-v1/post-tempolor-music-instrumental --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> music/instrumental description: "Generate royalty-free instrumental music from a text prompt via POST music/instrumental in the useapi.net TemPolor API v1 — BPM and chord customization supported." parent: TemPolor API nav_order: 700 --- ## Create instrumental music May 15, 2025 (November 16, 2026) --- This endpoint generates instrumental music based on a text prompt and optional musical parameters. > **https://api.useapi.net/v1/tempolor/music/instrumental** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "prompt": "A relaxing lo-fi beat with piano and soft drums", "tonality": "C:major", "bpm": 80, "chords": "C F G Am" } ``` - `user_id` is optional, if not specified, the API will use the account from your request. - `prompt` is **required**, a text description of the desired instrumental music. Maximum length 2000 characters. - `model_instrumental` is optional, the model to use for generation. Supported values: * `i4` - Better musicality and prompt adherence (default) Older model names are still accepted and automatically routed to `i4`. - `tonality` is optional, the musical key for the composition. Supported values: `A:major`, `A:minor`, `Ab:major`, `Ab:minor`, `B:major`, `B:minor`, `Bb:major`, `Bb:minor`, `C#:major`, `C#:minor`, `C:major`, `C:minor`, `D:major`, `D:minor`, `E:major`, `E:minor`, `Eb:major`, `Eb:minor`, `F#:major`, `F#:minor`, `F:major`, `F:minor`, `G:major`, `G:minor` - `bpm` is optional, the tempo in beats per minute. Valid range: 50…190. - `chords` is optional, chord progression for the composition. Maximum length 200 characters. - `replyUrl` is optional, a callback URL that will be called with generation progress updates. Maximum length 1024 characters. We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality. Callback body has the same JSON shape as [GET /music/`job_id`](/docs/api-tempolor-v1/get-tempolor-music-job_id) response. A job that has not completed within 60 minutes ends with a final callback with `code` 408 and `status_name` `FAILED`. - `replyRef` is optional, a reference ID that will be included in the callback requests. Maximum length 1024 characters. - `maxJobs` is optional; it specifies the maximum number of concurrent jobs for this request. If not provided, the value will be taken from the account configuration set in [POST accounts](/docs/api-tempolor-v1/post-tempolor-accounts). ##### Responses **200** **200 OK** Use the returned `jobs` values to retrieve generation status and results using [GET music/`job_id`](/docs/api-tempolor-v1/get-tempolor-music-job_id). If you specify the optional parameter [`replyUrl`](#request-body), the API will call the provided `replyUrl` with generation progress updates until the generation is complete or fails. ```json { "result": true, "itemIds": [ "abcdef123456789", "fedcba987654321" ], "jobs": [ "user:12345-tempolor:user_id-job:abcdef123456789", "user:12345-tempolor:user_id-job:fedcba987654321", ], "remainSeconds": 21533, "maxGenCountAtOnce": 10, "unlimited": false, "remainNum": 1534, "totalNum": 3000 } ``` **400** **400 Bad Request** ```json { "error": "Parameter prompt is required", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **402** **402 Payment Required** ```json { "error": "Subscription required", "code": 402 } ``` **422** **422 Unprocessable Content** TemPolor content moderation rejected the `prompt`. Resubmitting the same text will be rejected again, so change the prompt before retrying. ```json { "error": "TemPolor content moderation rejected the prompt. Resubmitting the same text will be rejected again. (430002)" } ``` **429** **429 Too Many Requests** Wait in a loop for **at least** 30 seconds and retry again. There are two possible cases for API response 429: 1. API query is full and cannot accept new instrumental music generation requests. Size of queue defined by the `maxJobs` value from either the request body or the default from the account configuration set in [POST accounts](/docs/api-tempolor-v1/post-tempolor-accounts). ```json { "error": "Account <user_id> is busy executing X jobs", "runningJobs": { "<user_id>": [ { "user_id": "<user_id>", "job_id": "<job_id>", "started": 1715791234567, "replyUrl": "call back URL here, if provided", "replyRef": "reference id here, if provided" } ] }, "code": 429 } ``` 2. The API received an HTTP response status 429 from TemPolor. ```json { "error": "please wait for current Generations to finish or upgrade your plan", "code": 429 } ``` **596** **596 Account signed out** TemPolor signed the account out, so its session ticket no longer works. The API stops using the account until you add it again with fresh credentials at [POST accounts](/docs/api-tempolor-v1/post-tempolor-accounts), see [Setup TemPolor](/docs/start-here/setup-tempolor). Requests without `user_id` use your other accounts in the meantime. ```json { "error": "TemPolor signed out account 101441809 (You are currently logged out (400006)). Add it again with POST /v1/tempolor/accounts using fresh credentials, see https://useapi.net/docs/start-here/setup-tempolor", "code": 596 } ``` If every account you have is in this state, a request without `user_id` returns 596 as well. ##### Model The new music jobs: poll each id in `jobs` with [GET music/`job_id`](/docs/api-tempolor-v1/get-tempolor-music-job_id) until it finishes. <details markdown="block" class="model-details"> <summary>The new music jobs, field by field</summary> ```typescript { // TypeScript, all fields are optional result: boolean itemIds: string[] jobs: string[] remainSeconds: number maxGenCountAtOnce: number unlimited: boolean remainNum: number totalNum: number } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST https://api.useapi.net/v1/tempolor/music/instrumental \ -d '{"prompt": "A relaxing lo-fi beat with piano and soft drums"}' ``` **JavaScript** ``` javascript const apiUrl = `https://api.useapi.net/v1/tempolor/music/instrumental`; const api_token = "API token"; const prompt = "A relaxing lo-fi beat with piano and soft drums"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${api_token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ prompt }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests apiUrl = f"https://api.useapi.net/v1/tempolor/music/instrumental" api_token = "API token" prompt = "A relaxing lo-fi beat with piano and soft drums" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {api_token}" } body = { "prompt": f"{prompt}" } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-tempolor-v1/post-tempolor-music-midi === Document URL: https://useapi.net/docs/api-tempolor-v1/post-tempolor-music-midi --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> music/midi description: "Upload a MIDI file to use as a structural base for song generation via POST music/midi in the useapi.net TemPolor API v1 — supports audio/midi and audio/x-midi." parent: TemPolor API nav_order: 1400 --- ## Upload MIDI file May 15, 2025 (November 16, 2026) --- This endpoint uploads a MIDI file that can be used as a base for music generation in the [POST music/song](/docs/api-tempolor-v1/post-tempolor-music-song) endpoint. [POST raw content using Make.com and similar nocode tools.](/docs/questions-and-answers#how-post-raw-content-to-runwaymlassets-and-minimaxfiles-using-makecom-and-similar-nocode-tools) > **https://api.useapi.net/v1/tempolor/music/midi/?...** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: audio/midi or audio/x-midi ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. - `Content-Type` is **required**, must be `audio/midi` or `audio/x-midi`. ##### Query Parameters - `user_id` is optional when only one [account](/docs/api-tempolor-v1/get-tempolor-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. - `name` is **required**. Specify a name for your MIDI file. ##### Responses **200** **200 OK** The MIDI file is immediately available to use in [POST music/song](/docs/api-tempolor-v1/post-tempolor-music-song) by providing the returned `midiItemId`. ```json { "isFirst": false, "midiRenderVO": { "opType": "upload", "ucid": "100198329", "midiItemId": "user:12345-tempolor:user_id-midi:abcdef123456789", "name": "my background music", "midiUrl": "https://..." } } ``` **400** **400 Bad Request** ```json { "error": "Content-Type must be audio/midi or audio/x-midi", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **596** **596 Account signed out** TemPolor signed the account out, so its session ticket no longer works. The API stops using the account until you add it again with fresh credentials at [POST accounts](/docs/api-tempolor-v1/post-tempolor-accounts), see [Setup TemPolor](/docs/start-here/setup-tempolor). Requests without `user_id` use your other accounts in the meantime. ```json { "error": "TemPolor signed out account 101441809 (You are currently logged out (400006)). Add it again with POST /v1/tempolor/accounts using fresh credentials, see https://useapi.net/docs/start-here/setup-tempolor", "code": 596 } ``` If every account you have is in this state, a request without `user_id` returns 596 as well. ##### Model The uploaded MIDI file, with the `midiItemId` to pass to [POST music/song](/docs/api-tempolor-v1/post-tempolor-music-song), its name and `midiUrl`. <details markdown="block" class="model-details"> <summary>The uploaded MIDI file, field by field</summary> ```typescript { // TypeScript, all fields are optional isFirst: boolean midiRenderVO: { opType: string ucid: string midiItemId: string name: string midiUrl: string } error: string code: number } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/tempolor/music/midi/?name=my-background-music&user_id=<user_id>" \ -H "Authorization: Bearer …" \ -H "Content-Type: audio/midi" \ --data-binary @/path/to/your/background-music.mid ``` **JavaScript** ``` javascript const token = "API token"; const user_id = "Previously configured account"; const name = "my-background-music"; const apiUrl = `https://api.useapi.net/v1/tempolor/music/midi/?name=${name}&user_id=${user_id}`; let blob; /* // Example 1: Fetch MIDI from URL const midiUrl = "https://example.com/midi-files/background-music.mid"; const responseMidi = await fetch(midiUrl); blob = await responseMidi.blob(); */ /* // Example 2: Load MIDI from local file (Node.js) const fs = require('fs'); const midiFileName = "./background-music.mid"; blob = new Blob([fs.readFileSync(midiFileName)], { type: "audio/midi" }); */ /* // Example 3: Load from input file html element // <input id="midi-file" type="file" accept=".mid,.midi"> const midiFile = document.getElementById(`midi-file`); if (midiFile.files[0]) blob = midiFile.files[0]; */ const response = await fetch(apiUrl, { method: "POST", headers: { "Authorization": `Bearer ${token}`, "Content-Type": "audio/midi" }, body: blob }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests token = "API token" user_id = "Previously configured account" name = "my-background-music" apiUrl = f"https://api.useapi.net/v1/tempolor/music/midi/?name={name}&user_id={user_id}" headers = { 'Authorization': f'Bearer {token}', 'Content-Type': 'audio/midi' } # # Example 1: Fetch MIDI from URL # midi_url = "https://example.com/midi-files/background-music.mid" # response_midi = requests.get(midi_url) # file_content = response_midi.content # # Example 2: Load MIDI from local file midi_file_path = "./background-music.mid" with open(midi_file_path, 'rb') as midi_file: file_content = midi_file.read() response = requests.post(apiUrl, headers=headers, data=file_content) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-tempolor-v1/post-tempolor-music-song === Document URL: https://useapi.net/docs/api-tempolor-v1/post-tempolor-music-song --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> music/song description: "Generate a royalty-free song with vocals from a text prompt or custom lyrics via POST music/song in the useapi.net TemPolor API v1." parent: TemPolor API nav_order: 600 --- ## Create music with vocals May 15, 2025 (November 16, 2026) --- This endpoint generates a complete song with vocals based on a text prompt and optional parameters. > **https://api.useapi.net/v1/tempolor/music/song** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: application/json # Alternatively you can use multipart/form-data # Content-Type: multipart/form-data ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. ##### Request Body ```json { "prompt": "A cinematic orchestral piece with dramatic string sections and a powerful crescendo", "lyrics": "These are the lyrics for my song\nSecond line of the lyrics", "clonedVoiceItemId": "user:12345-tempolor:user_id-voice:abcdef123456789", "replyUrl": "https://your-callback-url.com", "replyRef": "your-reference-id" } ``` - `user_id` is optional, if not specified, the API will use the account from your request. - `prompt` is **required**, a text description of the desired song. Maximum length 2000 characters. - `lyrics` is optional, custom lyrics for the song. If not provided, lyrics will be auto-generated based on the prompt. Maximum length 3000 characters. - `model_song` is optional, the model to use for generation. Supported values: * `v4.8` - Next-gen proprietary model with better melody, structure and vocals, 30+ languages, max 5 min (default) Older model names are still accepted and automatically routed to `v4.8`. - `artistVoiceItemId` is optional, ID of a predefined artist voice to use for the vocals. Get available voices using [GET artist-voices](/docs/api-tempolor-v1/get-tempolor-music-artist-voices). - `clonedVoiceItemId` is optional, ID of a previously cloned voice to use for the vocals. - To get existing cloned voices, use [GET cloned-voices](/docs/api-tempolor-v1/get-tempolor-music-cloned-voices). - To create a new cloned voice, upload an audio sample using [POST cloned-voices](/docs/api-tempolor-v1/post-tempolor-music-cloned-voices). - `midiItemId` is optional, ID of a previously uploaded MIDI file to base the composition on. - To get existing MIDI files, use [GET midi](/docs/api-tempolor-v1/get-tempolor-music-midi). - To upload a new MIDI file, use [POST midi](/docs/api-tempolor-v1/post-tempolor-music-midi). - `replyUrl` is optional, a callback URL that will be called with generation progress updates. Maximum length 1024 characters. We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality. Callback body has the same JSON shape as [GET /music/`job_id`](/docs/api-tempolor-v1/get-tempolor-music-job_id) response. A job that has not completed within 60 minutes ends with a final callback with `code` 408 and `status_name` `FAILED`. - `replyRef` is optional, a reference ID that will be included in the callback requests. Maximum length 1024 characters. - `maxJobs` is optional; it specifies the maximum number of concurrent jobs for this request. If not provided, the value will be taken from the account configuration set in [POST accounts](/docs/api-tempolor-v1/post-tempolor-accounts). **Important notes:** - You can only use one of `artistVoiceItemId` or `clonedVoiceItemId`, not both. - If you specify a `midiItemId`, you cannot use `artistVoiceItemId` or `clonedVoiceItemId`. ##### Responses **200** **200 OK** Use the returned `jobs` values to retrieve generation status and results using [GET music/`job_id`](/docs/api-tempolor-v1/get-tempolor-music-job_id). If you specify the optional parameter [`replyUrl`](#request-body), the API will call the provided `replyUrl` with generation progress updates until the generation is complete or fails. ```json { "result": true, "itemIds": [ "abcdef123456789", "fedcba987654321" ], "jobs": [ "user:12345-tempolor:user_id-job:abcdef123456789", "user:12345-tempolor:user_id-job:fedcba987654321", ], "remainSeconds": 21533, "maxGenCountAtOnce": 10, "unlimited": false, "remainNum": 1534, "totalNum": 3000 } ``` **400** **400 Bad Request** ```json { "error": "Parameter prompt is required", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **402** **402 Payment Required** ```json { "error": "Subscription required", "code": 402 } ``` **404** **404 Not Found** ```json { "error": "The source material does not exist.", "code": 404 } ``` This error may occur if the specified `artistVoiceItemId`, `clonedVoiceItemId`, or `midiItemId` no longer exists. **422** **422 Unprocessable Content** TemPolor content moderation rejected the `prompt` and/or the `lyrics`. The error names the rejected field. Resubmitting the same text will be rejected again, so change the rejected text before retrying. ```json { "error": "TemPolor content moderation rejected the lyrics. Resubmitting the same text will be rejected again. (430002)" } ``` **429** **429 Too Many Requests** Wait in a loop for **at least** 30 seconds and retry again. There are two possible cases for API response 429: 1. API query is full and cannot accept new music generation requests. Size of queue defined by the `maxJobs` value from either the request body or the default from the account configuration set in [POST accounts](/docs/api-tempolor-v1/post-tempolor-accounts). ```json { "error": "Account <user_id> is busy executing X jobs", "runningJobs": { "<user_id>": [ { "user_id": "<user_id>", "job_id": "<job_id>", "started": 1715791234567, "replyUrl": "call back URL here, if provided", "replyRef": "reference id here, if provided" } ] }, "code": 429 } ``` 2. The API received an HTTP response status 429 from TemPolor. ```json { "error": "please wait for current Generations to finish or upgrade your plan", "code": 429 } ``` **596** **596 Account signed out** TemPolor signed the account out, so its session ticket no longer works. The API stops using the account until you add it again with fresh credentials at [POST accounts](/docs/api-tempolor-v1/post-tempolor-accounts), see [Setup TemPolor](/docs/start-here/setup-tempolor). Requests without `user_id` use your other accounts in the meantime. ```json { "error": "TemPolor signed out account 101441809 (You are currently logged out (400006)). Add it again with POST /v1/tempolor/accounts using fresh credentials, see https://useapi.net/docs/start-here/setup-tempolor", "code": 596 } ``` If every account you have is in this state, a request without `user_id` returns 596 as well. ##### Model The new music jobs: poll each id in `jobs` with [GET music/`job_id`](/docs/api-tempolor-v1/get-tempolor-music-job_id) until it finishes. <details markdown="block" class="model-details"> <summary>The new music jobs, field by field</summary> ```typescript { // TypeScript, all fields are optional result: boolean itemIds: string[] jobs: string[] remainSeconds: number maxGenCountAtOnce: number unlimited: boolean remainNum: number totalNum: number } ``` </details> ##### Examples **Curl** ``` bash curl -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -X POST https://api.useapi.net/v1/tempolor/music/song \ -d '{"prompt": "A cinematic orchestral piece with dramatic string sections"}' ``` **JavaScript** ``` javascript const apiUrl = `https://api.useapi.net/v1/tempolor/music/song`; const api_token = "API token"; const prompt = "A cinematic orchestral piece with dramatic string sections"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${api_token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ prompt }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests apiUrl = f"https://api.useapi.net/v1/tempolor/music/song" api_token = "API token" prompt = "A cinematic orchestral piece with dramatic string sections" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {api_token}" } body = { "prompt": f"{prompt}" } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json()) ``` === URL: https://useapi.net/docs/api-tempolor-v1/post-tempolor-music-stems-splitter === Document URL: https://useapi.net/docs/api-tempolor-v1/post-tempolor-music-stems-splitter --- layout: default title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> music/stems-splitter description: "Split an uploaded MP3, WAV, M4A, or FLAC file into separate instrument stems (vocals, drums, bass) via POST music/stems-splitter in the useapi.net TemPolor API v1." parent: TemPolor API nav_order: 800 --- ## Split audio into stems May 15, 2025 (November 16, 2026) --- Upload an audio file (MP3, WAV, M4A, FLAC) and split it into separate instrument stems (vocals, drums, bass, etc). [POST raw content using Make.com and similar nocode tools.](/docs/questions-and-answers#how-post-raw-content-to-runwaymlassets-and-minimaxfiles-using-makecom-and-similar-nocode-tools) > **https://api.useapi.net/v1/tempolor/music/stems-splitter/?…** ##### Request Headers ``` yaml Authorization: Bearer {API token} Content-Type: select from the table below ``` - `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details. - `Content-Type` is **required**, select from the table below: | Content-Type | File Extension | | ------------ | -------------- | | audio/mpeg | mp3 | | audio/wav | wav | | audio/wave | wav | | audio/mp4 | m4a | | audio/x-m4a | m4a | | audio/flac | flac | | audio/x-flac | flac | ##### Query Parameters - `user_id` is optional when only one [account](/docs/api-tempolor-v1/get-tempolor-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**. ##### Responses **200** **200 OK** When the response includes `stemsZipUrl`, the processing is complete and you can download the ZIP file containing the separated stems. ```json { "state": 2, "title": "audio_file.mp3", "stemsZipUrl": "https://example.com/path/to/stems.zip" } ``` **400** **400 Bad Request** The server encountered an error processing your request. ```json { "error": "<Error message>", "code": 400 } ``` **401** **401 Unauthorized** ```json { "error": "Unauthorized", "code": 401 } ``` **596** **596 Account signed out** TemPolor signed the account out, so its session ticket no longer works. The API stops using the account until you add it again with fresh credentials at [POST accounts](/docs/api-tempolor-v1/post-tempolor-accounts), see [Setup TemPolor](/docs/start-here/setup-tempolor). Requests without `user_id` use your other accounts in the meantime. ```json { "error": "TemPolor signed out account 101441809 (You are currently logged out (400006)). Add it again with POST /v1/tempolor/accounts using fresh credentials, see https://useapi.net/docs/start-here/setup-tempolor", "code": 596 } ``` If every account you have is in this state, a request without `user_id` returns 596 as well. ##### Model The split result, with `stemsZipUrl` linking to a ZIP of the separated stems once processing is complete. <details markdown="block" class="model-details"> <summary>The split result, field by field</summary> ```typescript { // TypeScript, all fields are optional state: number title: string stemsZipUrl: string // URL to download the zip with separated stems audioType: string detail: string[] error: string code: number } ``` </details> ##### Examples **Curl** ``` bash curl "https://api.useapi.net/v1/tempolor/music/stems-splitter/?user_id=<user_id>" \ -H "Authorization: Bearer …" \ -H "Content-Type: audio/mpeg" \ --data-binary @/path/to/your/audio-track.mp3 ``` **JavaScript** ``` javascript const token = "API token"; const user_id = "Previously configured account"; const apiUrl = `https://api.useapi.net/v1/tempolor/music/stems-splitter/?user_id=${user_id}`; let blob; /* // Example 1: Fetch audio from URL const audioUrl = "https://example.com/path/to/audio-track.mp3"; const responseAudio = await fetch(audioUrl); blob = await responseAudio.blob(); */ /* // Example 2: Load audio from local file (Blob) const fsp = require('fs').promises; const audioFileName = "./audio-track.mp3"; blob = new Blob([await fsp.readFile(audioFileName)]); */ /* // Example 3: Load from input file html element // <input id="audio-file" type="file"> const audioFile = document.getElementById(`audio-file`); if (audioFile.files[0]) blob = audioFile.files[0]; */ // Upload the audio file for stem splitting const response = await fetch(apiUrl, { method: "POST", headers: { "Authorization": `Bearer ${token}`, "Content-Type": "audio/mpeg" }, body: blob }); const result = await response.json(); console.log("response", {response, result}); ``` **Python** ``` python import requests import time token = "API token" user_id = "Previously configured account" apiUrl = f"https://api.useapi.net/v1/tempolor/music/stems-splitter/?user_id={user_id}" headers = { 'Authorization': f'Bearer {token}', 'Content-Type': 'audio/mpeg' } # # Example 1: Fetch audio from URL # import requests # audio_url = "https://example.com/path/to/audio-track.mp3" # response_audio = requests.get(audio_url) # file_content = response_audio.content # # Example 2: Load audio from local file audio_file_path = "./audio-track.mp3" with open(audio_file_path, 'rb') as audio_file: file_content = audio_file.read() response = requests.post(apiUrl, headers=headers, data=file_content) result = response.json() print(response.status_code, result) ``` === URL: https://useapi.net/docs/articles/ace-music-api-tutorial-es === Document URL: https://useapi.net/docs/articles/ace-music-api-tutorial-es --- layout: default title: "Cómo generar canciones con IA mediante la ACE Music API" description: "Crea canciones con ACE Music v1, v1.1 y el gratuito ACE-Step v1.5 XL mediante la ACE Music API de useapi.net: prompts, tu propia letra, covers, mashups, stems y MIDI, con curl y código." keywords: [ACE Music API, ACE Music v1 API, ACE-Step API, ACE-Step v1.5 XL, AI song generator API, text to music API, Suno alternative, AI music API, stems API, MIDI, MusicXML, mashup, cover song AI, MCP server, curl, tutorial, API de ACE Music, API de ACE-Step, API para generar canciones con IA, API de texto a música, alternativa a Suno, API de música con IA, separar stems, covers con IA, servidor MCP, código] image: https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-paper-lanterns-cover-art.jpg parent: Articles nav_exclude: true lang: es translation_key: ace-music-tutorial date: 2026-11-14 last_modified: 2026-11-18 nav_order: 302 repo: https://github.com/useapi/acemusic-api --- ## Cómo generar canciones con IA mediante la ACE Music API {: .no_toc #how-to-generate-ai-songs-with-the-ace-music-api } 22 min de lectura • 14 de noviembre de 2026 ## Índice {: .no_toc .text-delta #table-of-contents } ### Introducción La [ACE Music API](/docs/api-acemusic-v1) de useapi.net convierte una sola llamada REST en dos canciones terminadas de [ACE Music](https://acemusic.ai), con voces, letra, título y portada, con la suscripción de ACE Music que ya tienes. ACE Music v1 ocupa el primer puesto del [ranking de música vocal de Artificial Analysis](https://artificialanalysis.ai/music/leaderboard/vocals), por delante de Suno v6. El modelo de código abierto [ACE-Step](https://ace-step.github.io) v1.5 XL funciona con la misma API sin gastar créditos en ningún plan de ACE Music, incluido el plan Free. Esta guía empieza por los tres modelos y lo que cuesta una canción, crea una canción de principio a fin con `curl` y luego resume todas las demás funciones en una tabla breve. Los [Ejemplos](#examples) del final son 18 canciones que hicimos para esta página, cada una con la solicitud que la generó, todas con los scripts del [repositorio de GitHub `acemusic-api`](https://github.com/useapi/acemusic-api) (Node.js y Python), por 117 créditos de un plan Artist, tomas extra incluidas. useapi.net es una API [de terceros](/docs/legal#affiliation--third-party-services), sin afiliación con ACE Music ni con su creador, Timedomain. ### Modelos y lo que puede hacer la API Cada solicitud genera dos canciones, y `model` elige quién las hace: | Modelo | `model` | Para qué sirve | Ajustes | Créditos por solicitud | Tiempo en nuestras pruebas | |---|---|---|---|---|---| | ACE Music v1 | `acemusic-v1` (por defecto) | El modelo vocal número 1: canciones a partir de un prompt o de tu letra, cantadas o instrumentales | `duration` de 30 a 600 s, `negative`, `styleInfluence`, descargas en WAV | 4 | De 46 a 89 s | | ACE Music v1.1 Preview | `acemusic-v1.1` | Escribe primero una partitura, así que sus covers y mashups siguen la melodía de una canción | `audioInfluence`, `styleInfluence` | 4 | De 35 a 83 s | | ACE-Step v1.5 XL | `ace-step-1.5-xl` | Código abierto de ACE Studio y StepFun: canciones, remixes y ediciones | `bpm`, `key`, `timeSignature`, `duration` de 10 a 240 s, `negative`, `thinking`. Solo MP3 | 0 | De 20 a 55 s | Lo que puedes hacer con ellos: | Qué | Solicitud | Notas | |---|---|---| | Canciones a partir de un prompt | [POST /music](/docs/api-acemusic-v1/post-acemusic-music) `prompt` | ACE Music escribe el estilo, la letra y el título | | Tu propia letra, instrumentales | [POST /music](/docs/api-acemusic-v1/post-acemusic-music) `style`, `lyrics` | En cualquier idioma | | Generadores de letra y de estilo | [POST /music/lyrics](/docs/api-acemusic-v1/post-acemusic-music-lyrics), [/music/style](/docs/api-acemusic-v1/post-acemusic-music-style) | Sin créditos | | Covers, remixes, ediciones, mashups | [POST /music](/docs/api-acemusic-v1/post-acemusic-music#modes) `mode` | Con cualquier canción de la cuenta | | Tu audio y tus imágenes | [POST /files](/docs/api-acemusic-v1/post-acemusic-files) | Como referencias para canciones nuevas | | Stems | [POST /music/stems](/docs/api-acemusic-v1/post-acemusic-music-stems) | Creator y Artist | | Descargas, partitura | [GET /music/download](/docs/api-acemusic-v1/get-acemusic-music-download), [/music/score](/docs/api-acemusic-v1/get-acemusic-music-score) | MP3 y la partitura en todos los planes, WAV, MIDI y MusicXML en Creator y Artist | | Biblioteca, jobs, cuentas | [GET /music](/docs/api-acemusic-v1/get-acemusic-music), [/jobs](/docs/api-acemusic-v1/get-acemusic-jobs), [/accounts](/docs/api-acemusic-v1/get-acemusic-accounts-email) | Todas las canciones de la cuenta, los jobs en curso, los créditos en vivo | | Servidor MCP | [`/v1/acemusic/mcp`](/docs/api-acemusic-v1/mcp) | 15 herramientas para asistentes de IA | ### Precios ACE Music cobra sus propios créditos por solicitud, de tu plan de ACE Music, y useapi.net no agrega nada por canción (a noviembre de 2026): | Solicitud | Créditos | |---|---| | Dos canciones con ACE Music v1 o v1.1 | 4 | | Stems, voz + instrumental | 5, planes de pago | | Stems, todos los stems | 60, planes de pago | | Partitura de una canción de ACE-Step, primera lectura | 1 | | Dos canciones con ACE-Step v1.5 XL | 0, en todos los planes | | Generadores de letra y de estilo, subidas, descargas | 0 en nuestras pruebas | Los [planes de ACE Music](https://acemusic.ai/pricing/) son Free, con 20 créditos al día, Creator, a US$9,90 al mes por 1.000 créditos, y Artist, a US$29 al mes por 2.500 créditos, o US$7,90 y US$16,58 al mes con pago anual. Una canción es media solicitud: 2 créditos. La [descripción general de la API](/docs/api-acemusic-v1#pricing) tiene la misma tabla. Lo que cuesta una canción en cada plan, con el más barato a la izquierda (una solicitud genera dos canciones, así que una canción cuesta la mitad de los créditos de una solicitud. Precios en dólares estadounidenses, a noviembre de 2026): | Modelo | Free (20 cr/día) | Artist $16,58/mes (2.500 cr/mes, pago anual) | Creator $7,90/mes (1.000 cr/mes, pago anual) | Creator $9,90/mes (1.000 cr/mes) | Artist $29/mes (2.500 cr/mes) | |---|---|---|---|---|---| | ACE Music v1, v1.1 (una canción) | $0 / 2 cr (10 al día) | $0,013 / 2 cr (1.250 al mes) | $0,016 / 2 cr (500 al mes) | $0,020 / 2 cr (500 al mes) | $0,023 / 2 cr (1.250 al mes) | | Stems (voz + instrumental) | planes de pago | $0,033 / 5 cr | $0,040 / 5 cr | $0,050 / 5 cr | $0,058 / 5 cr | | Stems (todos los stems) | planes de pago | $0,40 / 60 cr | $0,47 / 60 cr | $0,59 / 60 cr | $0,70 / 60 cr | | Partitura de ACE-Step (primera lectura) | $0 / 1 cr | $0,007 / 1 cr | $0,008 / 1 cr | $0,010 / 1 cr | $0,012 / 1 cr | | ACE-Step v1.5 XL (una canción) | $0 / 0 cr | $0 / 0 cr | $0 / 0 cr | $0 / 0 cr | $0 / 0 cr | Cómo se compara con las otras formas de usar estos modelos desde código (en dólares estadounidenses): | Modelo | useapi.net | Otras API | |---|---|---| | ACE Music v1, v1.1 Preview | Desde $0,013 por canción en Artist con pago anual, $0 con los 20 créditos diarios del plan Free | — | | ACE-Step v1.5 XL | $0 en todos los planes de ACE Music, incluido el plan Free | Unos $0,14 por canción en la API de terceros de [acestep.io](https://acestep.io/pricing), que requiere su plan Studio de $49 al mes | En cualquier plan de ACE Music, incluido el plan Free, una canción de ACE-Step v1.5 XL no gasta créditos, frente a la API de acestep.io, un sitio de terceros que requiere su plan Studio de US$49 al mes (unas 360 canciones al mes, unos US$0,14 por canción, a noviembre de 2026). ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. ### Cómo generar una canción con curl Necesitas un token de la API de useapi.net, consulta [Setup useapi.net](/docs/start-here/setup-useapi), y una cuenta de [ACE Music](https://acemusic.ai) con correo y contraseña. Una sola [suscripción de US$15 al mes](/docs/subscription) cubre todas las API de useapi.net y 3 cuentas de ACE Music. Una cuenta Free de ACE Music funciona: recibe 20 créditos al día, y las canciones de ACE-Step no necesitan ninguno. Los comandos usan [jq](https://jqlang.org) para leer el JSON. #### Agrega tu cuenta de ACE Music Exporta el token y agrega la cuenta una sola vez. La API inicia sesión, lee la cuenta y la guarda solo si ACE Music acepta la contraseña: ```bash export USEAPI_TOKEN="user:12345-..." API=https://api.useapi.net/v1/acemusic curl -s -X POST "$API/accounts" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "example@example.com", "password": "your-acemusic-password" }' ``` Una cuenta creada con Continuar con Google o con un número de teléfono necesita primero una contraseña, consulta [Setup ACE Music](/docs/start-here/setup-acemusic), que también puede agregarla por ti. #### Crea canciones a partir de un prompt Describe la canción con tus propias palabras. ACE Music escribe el estilo, la letra y el título, y luego genera dos canciones. Esta es la solicitud exacta detrás de la primera canción de esta página: ```bash curl -s -X POST "$API/music" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A late-night neo-soul slow jam about two strangers sharing an umbrella at a bus stop in the rain and missing the last bus on purpose. Warm Rhodes piano, brushed drums, round upright bass, a smoky female lead with close three-part harmonies on the chorus.", "model": "acemusic-v1", "async": true }' | tee job.json | jq '{jobid, status, model}' ``` Con `async: true`, la API responde `201` de inmediato con el job. Un prompt puede tener hasta 2.000 caracteres y llevar hasta 3 canciones de referencia y 3 imágenes, consulta [Guía tus canciones con tu propio audio e imágenes](#guide-songs-with-your-own-audio-and-images). #### Lo que recibes Mientras ACE Music escribe la letra, las canciones están en `planning` y `Untitled`, luego en `queued` y `running`. Consulta [GET /jobs/`jobid`](/docs/api-acemusic-v1/get-acemusic-jobs-jobid) más o menos cada 10 segundos. El `jobid` contiene `:` y `@`, así que codifícalo para la URL: ```bash curl -s "$API/jobs/$(jq -r .jobid job.json | jq -Rr @uri)" \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{status, songs: [.songs[] | {title, status, duration, audioUrl}]}' ``` Cuando `status` es `completed`, cada canción trae sus enlaces (los ids de abajo son inventados): ```json { "jobid": "j1115003713275918262m-u12345-email:example@example.com-task:so_7c1d9e3a5b2f4806a4e1c9d3.so_8b4f2e6a1c9d47e5a3b7c0d2-bot:acemusic", "type": "music", "status": "completed", "email": "example@example.com", "created": "2026-11-15T00:37:13.275Z", "model": "acemusic-v1", "modelUsed": "acemusic-v1", "songs": [ { "songId": "user:12345-example@example.com-song:so_7c1d9e3a5b2f4806a4e1c9d3", "taskId": "so_7c1d9e3a5b2f4806a4e1c9d3", "status": "succeeded", "title": "Let the 44 Roll By", "model": "acemusic-v1", "style": "Late-night neo-soul slow jam with a laid-back 1990s and early 2000s pocket, 72 BPM. …", "lyrics": "[Intro - Warm Rhodes chords, brushed snare rim clicks, subtle rain on asphalt]\n\n[Verse 1 …]\nWater dripping off the canvas seam\n…", "instrumental": false, "duration": 277.19, "audioUrl": "https://acemusic.ai/data/so_7c1d9e3a5b2f4806a4e1c9d3.mp3", "playUrl": "https://….r2.cloudflarestorage.com/acemusic-data-prod/users/…/audio/202611/….mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20261115T003902Z&X-Amz-Expires=3599&…", "playUrlExpires": "2026-11-15T01:39:01.000Z", "coverUrl": "https://acemusic.ai/data/so_7c1d9e3a5b2f4806a4e1c9d3-cover.jpg?v=1794703081642", "pageUrl": "https://acemusic.ai/song/r4k8w2n6p9tz", "created": "2026-11-15T00:37:13.300Z", "finished": "2026-11-15T00:38:42.208Z", "kind": "original", "score": false }, { "songId": "user:12345-example@example.com-song:so_8b4f2e6a1c9d47e5a3b7c0d2", "title": "Let the 44 Roll By", "duration": 253.99, "…": "…" } ], "completed": "2026-11-15T00:38:42.208Z" } ``` - `audioUrl` es el enlace público al MP3 de la canción y nunca cambia. `playUrl` es un enlace directo al mismo MP3 para reproductores web, válido hasta `playUrlExpires` (alrededor de una hora): algunos navegadores, como Brave, bloquean la redirección detrás de `audioUrl`. - `songId` es lo que reciben los covers, los mashups, los stems, las descargas y la partitura. Indica la cuenta en la que está la canción, así que esas llamadas se ejecutan ahí. - `model` es el modelo que pediste, y `modelUsed`, el que se ejecutó (consulta los [mashups](#mash-up-two-or-three-songs)). `kind` es `original`, `cover`, `edit`, `mashup` o `upload`, y `score` indica si la canción ya tiene su partitura. - Una canción que ACE Music no pudo generar tiene `status: "failed"`, el motivo de ACE Music en `error` y `refunded: true` cuando se devolvieron los créditos. Y esta es la primera de esas dos canciones: ACE Music v1 — "Let the 44 Roll By" · 4:37 · generada en 89 s <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-let-the-44-roll-by-neo-soul-from-prompt.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### Sync, async y webhooks | Lo que envías | El POST responde | Después | |---|---|---| | `async: true` | `201` de inmediato, con el job | Consulta [GET /jobs/`jobid`](/docs/api-acemusic-v1/get-acemusic-jobs-jobid) | | Sin `async` | `200` con el job terminado, el mismo JSON de arriba | Lee las canciones de la respuesta. Una solicitud que sigue en curso después de 100 segundos responde `202` con el job: consúltalo | | `replyUrl` y `replyRef` | Como arriba, tanto en sync como en async | Tu URL pública `https` recibe un solo `POST` con el job terminado, con tu `replyRef` incluido | Nuestra solicitud de ACE-Step sin `async` volvió en 37 segundos, y el webhook llegó 12 segundos después de que terminaran las canciones. Un job se puede leer durante 7 días, y uno que sigue en curso 30 minutos después de empezar falla con `504`. [`async-webhooks/`](https://github.com/useapi/acemusic-api/tree/main/async-webhooks) prueba las tres formas e incluye un pequeño receptor de webhooks. <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash curl -s -X POST "$API/music" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A dreamy lo-fi hip hop beat for studying late at night: dusty vinyl crackle, mellow Rhodes chords, a soft upright bass and rain on the window", "model": "ace-step-1.5-xl", "replyUrl": "https://your-server.example.com/acemusic-hook", "replyRef": "lofi-1" }' | jq '{status, songs: [.songs[] | {title, duration, audioUrl}]}' ``` </details> ### Canta tu propia letra Envía `style` y `lyrics` en lugar de `prompt`, y ACE Music canta tus palabras con tu estilo: | Campo | Qué hace | Límites | |---|---|---| | `style` | Género, instrumentos, ambiente, tempo y voces | 1.000 caracteres, 512 en ACE-Step | | `lyrics` | Tu letra, en cualquier idioma, con las etiquetas `[Verse]`, `[Chorus]` y `[Bridge]` | 5.000 caracteres, 2.000 en ACE-Step | | `title` | El título de las canciones. Si no lo envías, ACE Music lo elige | 80 caracteres | | `instrumental` | `true` para que no haya voces. Un `style` sin `lyrics` hace lo mismo | | | `duration` | La duración en segundos | De 30 a 600 en ACE Music v1, de 10 a 240 en ACE-Step | | `negative` | Estilos que hay que evitar | 200 caracteres, ACE Music v1 y ACE-Step | | `styleInfluence` | Qué tan fielmente se sigue el estilo | De `0` a `100`, por defecto `80`, ACE Music v1 y v1.1 | Nunca envíes `prompt` junto con estos campos: la API responde `400` e indica qué quitar. Nuestra balada, pedida con `duration: 210`, volvió con 210 y 209 segundos. Está en [Ejemplos](#your-own-lyrics), junto con un instrumental y una canción en español. ¿Todavía no tienes letra? [POST /music/lyrics](/docs/api-acemusic-v1/post-acemusic-music-lyrics) escribe la letra y un título a partir de una solicitud, y [POST /music/style](/docs/api-acemusic-v1/post-acemusic-music-style) convierte unas pocas palabras en un estilo completo. Los nuestros volvieron en 6 y 4 segundos, sin cobrar créditos. Script: [`custom-lyrics/`](https://github.com/useapi/acemusic-api/tree/main/custom-lyrics). ### Controla el tempo, la tonalidad y el compás con ACE-Step ACE-Step v1.5 XL acepta ajustes musicales que los modelos de ACE Music no aceptan, y sus canciones no gastan créditos: | Opción | Valores | |---|---| | `bpm` | De `30` a `200` | | `timeSignature` | `2/4`, `3/4`, `4/4`, `6/8` | | `key` | De `C major` a `B minor` (C, C#, D, Eb, E, F, F#, G, Ab, A, Bb, B) | | `duration` | De `10` a `240` segundos | | `negative` | Estilos que hay que evitar, hasta 200 caracteres | | `thinking` | De `0` a `100`: ACE-Step planifica primero toda la canción, creativo con valores bajos, estable con valores altos | Nuestras tres canciones de ACE-Step, un vals en 3/4, una giga en 6/8 y un drum and bass a 174 bpm, volvieron exactamente con la duración pedida ([Ejemplos](#ace-step-at-a-set-tempo-key-and-meter)). Estas opciones solo funcionan con `mode` `generate` en `ace-step-1.5-xl`, y en cualquier otro caso la API responde `400 Parameter bpm does not apply to mode generate on acemusic-v1`. Script: [`ace-step-options/`](https://github.com/useapi/acemusic-api/tree/main/ace-step-options). ### Covers, remixes y ediciones `mode` convierte una solicitud en trabajo sobre canciones que ya tienes. `references` recibe sus `songId`: canciones que generó la API, canciones de tu [Biblioteca](#your-library) o tus propias subidas. | `mode` | `references` | Se ejecuta en | Créditos | Qué hace | |---|---|---|---|---| | `cover` | 1 canción | `acemusic-v1.1`, o ACE-Step en `ace-step-1.5-xl` | 4 / 0 | La canción con un `style` nuevo, siguiendo su melodía, sus acordes y su estructura | | `remix` | 1 canción | `ace-step-1.5-xl` | 0 | `coverStrength` conserva el original, `remixStrength` se aleja de él (de `0` a `100`) | | `edit` | 1 canción | `ace-step-1.5-xl` | 0 | Reescribe la parte entre los segundos `start` y `end` con la letra nueva de `lyrics` y conserva el resto | | `mashup` | 2 o 3 canciones | `acemusic-v1.1` | 4 | Una canción nueva a partir de varias, consulta abajo | ACE Music v1.1 sigue la melodía que lee en la partitura de una canción. Nuestro primer cover de una canción de ACE Music v1 que aún no tenía partitura falló con `ref_no_melody`, y se devolvieron los 4 créditos, así que ahora la API lee primero, gratis, la partitura de una canción de ACE Music v1 antes de un cover o un mashup con v1.1. Las canciones de ACE-Step no se leen automáticamente: si una responde `400` con `ref_no_melody`, llama primero a [GET /music/score](#read-the-score) con ella (1 crédito) y luego vuelve a enviar la solicitud. Script: [`covers-remix-edit/`](https://github.com/useapi/acemusic-api/tree/main/covers-remix-edit). #### Haz un mashup de dos o tres canciones `mode: "mashup"` crea una sola canción a partir de 2 o 3 canciones de la misma cuenta y combina sus letras, salvo que envíes `lyrics`. `audioInfluence` (de 0 a 100, por defecto 60) define qué tan de cerca se siguen las canciones. Un mashup tiene que leer las canciones, así que se ejecuta en ACE Music v1.1 Preview aunque pidas v1, igual que en el sitio web de ACE Music: nuestro "Harbor Fiesta" muestra `"model": "acemusic-v1"` y `"modelUsed": "acemusic-v1.1"`, y los créditos son los del modelo que se ejecutó. Lo mismo pasa con un `cover` pedido en v1, con un prompt con más de una referencia en ACE-Step y, a veces, con un prompt con una canción de referencia. Script: [`mashup/`](https://github.com/useapi/acemusic-api/tree/main/mashup). ### Guía tus canciones con tu propio audio e imágenes [POST /files](/docs/api-acemusic-v1/post-acemusic-files) recibe el archivo como cuerpo sin procesar de la solicitud, con su `Content-Type`: | Subida | Formatos | Hasta | Recibes | Úsalo como | |---|---|---|---|---| | Audio | MP3, WAV, FLAC, OGG, M4A, AAC | 100 MB, 8 minutos | Un `songId`: una canción de la Biblioteca, con su letra, estilo, tempo y melodía transcritos por ACE Music | Una de hasta 3 `references` de un prompt, o la canción para hacer un cover, un remix, una edición o un mashup | | Imagen | JPEG, PNG, WebP | 10 MB | Un `mediaId` | Una de hasta 3 `images` de un prompt: ACE Music escribe una canción sobre ella | ```bash curl -s -X POST "$API/files?title=Harbour%20Jig%20demo" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: audio/mpeg" \ --data-binary @harbour-jig-demo.mp3 | jq '{songId, status, duration, bpm: .upload.bpm}' ``` Nuestra subida de 90 segundos del "Harbour Jig" se transcribió en 14 segundos, y ACE Music detectó 115 bpm (habíamos pedido 116). La foto de un robot bailando se convirtió en una canción de drum and bass sobre su pelaje verde azulado y sus tenis altos naranjas. Las dos están en [Ejemplos](#your-audio-and-pictures). Las subidas cuentan contra el límite de la cuenta: 10 minutos de audio en Free, 30 en Creator y 60 en Artist. Script: [`upload-reference/`](https://github.com/useapi/acemusic-api/tree/main/upload-reference). ### Stems, descargas y la partitura Toda canción terminada se puede separar, descargar y leer como partitura: | Solicitud | Planes | Créditos | Recibes | |---|---|---|---| | [Stems](/docs/api-acemusic-v1/post-acemusic-music-stems), `mode: "vocals"` | Creator, Artist | 5 | Los MP3 `vocal` e `instrumental` | | [Stems](/docs/api-acemusic-v1/post-acemusic-music-stems), `mode: "all"` | Creator, Artist | 60 | Cada stem que encuentra ACE Music, en MP3 | | [Descarga](/docs/api-acemusic-v1/get-acemusic-music-download) `mp3` (por defecto) | Todos los planes | 0 | `url` (igual que `audioUrl`) y `playUrl` | | Descarga `wav` | Creator, Artist | 0 | Un enlace válido por 24 horas. No para canciones de ACE-Step | | Descarga `midi`, `musicxml` | Creator, Artist | 0 | El archivo en sí | | [Partitura](/docs/api-acemusic-v1/get-acemusic-music-score) | Todos los planes | 0, 1 para una canción de ACE-Step la primera vez | [Notación ABC](https://abcnotation.com): la melodía vocal, una línea instrumental, los acordes y las secciones | #### Separa una canción en stems La separación de voz de "Paper Lanterns" tardó unos 80 segundos, y la completa, menos de 2 minutos, con 9 stems: voces, coros, batería, bajo, guitarra, teclado, cuerdas, sintetizador y efectos ([escúchalos](#stems-of-paper-lanterns)). Los enlaces de los stems duran 24 horas, así que vuelve a leer la canción para obtener enlaces nuevos. Volver a separar una canción en el mismo modo responde de inmediato y no cobra nada. #### Descarga MP3, WAV, MIDI y MusicXML ACE Music genera el WAV, el MIDI y el MusicXML con la primera solicitud: la API espera hasta un minuto y luego responde `202`, así que vuelve a llamar un minuto después. Para "Paper Lanterns" los tres estuvieron listos en segundos: un WAV de 40 MB, un archivo MIDI de 8 KB y una partitura MusicXML de 107 KB. <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash SONG="user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7" curl -s -G "$API/music/download" --data-urlencode "songId=$SONG" -d format=wav \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{url, expires}' curl -s -G "$API/music/download" --data-urlencode "songId=$SONG" -d format=midi \ -H "Authorization: Bearer $USEAPI_TOKEN" -o paper-lanterns.mid ``` </details> #### Lee la partitura Cualquier herramienta de ABC convierte la partitura en notación musical. Para "Paper Lanterns" indicó 72 bpm, el tempo que pedimos en el estilo. Las canciones de ACE Music v1.1 vienen con su partitura, y los covers y mashups de v1.1 la siguen, consulta [Covers, remixes y ediciones](#covers-remixes-and-edits). <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash SONG="user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7" curl -s -G "$API/music/score" --data-urlencode "songId=$SONG" \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq -r .abc | head -14 ``` ``` X:1 T: M:2/4 L:1/16 Q:1/4=72 V: Vocal clef=treble name="Vocal Melody" snm="Vocal" V: Ins clef=treble name="Ins Melody" snm="Inst." K:Ab % intro V: Vocal Z|"Ab"z8|"Ab"z8|"Ab"z8| V: Ins Z|Ac2AcBA2|A2EAA2EA|Ac2AcBA2| ``` </details> Script: [`stems-and-downloads/`](https://github.com/useapi/acemusic-api/tree/main/stems-and-downloads), que guarda los stems, cada formato de descarga y la partitura. ### Tu Biblioteca Cada canción y cada subida de la cuenta, hecha aquí o en acemusic.ai, se queda en su Biblioteca hasta que la borres: | Solicitud | Qué hace | |---|---| | [GET /music](/docs/api-acemusic-v1/get-acemusic-music) | Una página de canciones, de la más reciente a la más antigua, con `next` para la página siguiente. `email` es obligatorio si tienes más de una cuenta. Las canciones de los jobs de más de 7 días están aquí | | [GET /music/`songId`](/docs/api-acemusic-v1/get-acemusic-music-songid) | Una canción con enlaces nuevos, y sus stems si se separó | | [DELETE /music/`songId`](/docs/api-acemusic-v1/delete-acemusic-music-songid) | `204`: la canción pasa a la papelera de la cuenta en acemusic.ai, y desde entonces la API responde `404` para ella | <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash SONG="user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7" curl -s -G "$API/music" --data-urlencode "email=example@example.com" -d limit=20 \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{next, songs: [.songs[] | {title, model, kind, songId}]}' curl -s "$API/music/$(jq -rn --arg v "$SONG" '$v|@uri')" \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{title, score, audioUrl, playUrl, stems: (.stems // {} | keys)}' curl -s -o /dev/null -w "%{http_code}\n" -X DELETE "$API/music/$(jq -rn --arg v "$SONG" '$v|@uri')" \ -H "Authorization: Bearer $USEAPI_TOKEN" ``` </details> Script: [`library/`](https://github.com/useapi/acemusic-api/tree/main/library). ### Varias cuentas de ACE Music Cada suscripción de useapi.net conecta 3 cuentas de ACE Music, hasta 100 en total. Una solicitud sin `email` va a una cuenta en buen estado con un espacio libre, y una que indica una canción, una subida o una imagen se ejecuta en la cuenta donde está. Una cuenta ejecuta hasta `maxJobs` solicitudes a la vez, 4 por defecto, el propio límite de ACE Music. Una suscripción de US$15 ejecuta hasta 12 solicitudes de canciones a la vez (3 cuentas × 4 cada una), y cada solicitud genera dos canciones, así que se generan 24 canciones en paralelo, con ACE Music v1 o con ACE-Step v1.5 XL, que no usa créditos. Con todas las cuentas ocupadas, la API responde `429` con `Retry-After`, y si ACE Music rechaza una contraseña, esa cuenta responde `596` hasta que la vuelvas a agregar. [GET /accounts/`email`](/docs/api-acemusic-v1/get-acemusic-accounts-email) lee en vivo el plan, los créditos y lo que cuesta cada cosa en créditos, y [POST /accounts](/docs/api-acemusic-v1/post-acemusic-accounts) solo con `email` y `maxJobs` cambia únicamente `maxJobs`. Script: [`accounts/`](https://github.com/useapi/acemusic-api/tree/main/accounts). <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash curl -s "$API/accounts/$(jq -rn --arg v "example@example.com" '$v|@uri')" \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{plan_name, credits, maxJobs, costs}' curl -s -X POST "$API/accounts" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "example@example.com", "maxJobs": 2 }' ``` </details> ### Úsala desde Claude, ChatGPT o Cursor (MCP) Las mismas funciones están disponibles como un [servidor MCP](/docs/api-acemusic-v1/mcp) alojado con 15 herramientas, desde canciones, covers y mashups hasta stems, partituras y subidas. En Claude Code basta con un comando: ```bash claude mcp add --transport http useapi-acemusic https://api.useapi.net/v1/acemusic/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` Cursor, VS Code y Windsurf usan la misma URL y el mismo encabezado, y la app de Claude y ChatGPT inician sesión con OAuth, consulta [Use it in the Claude app or ChatGPT](/docs/api-acemusic-v1/mcp#use-it-in-the-claude-app-or-chatgpt). Después pide lo que quieras con tus palabras: "Write lyrics about a cat who loves rainy days and sing them as acoustic indie folk on ACE Music v1". #### useapi.net frente al servidor MCP propio de ACE Music ACE Music también tiene su propio servidor MCP en `https://acemusic.ai/mcp`. Crea canciones de ACE Music v1 y v1.1 a partir del estilo y la letra que escribe tu asistente. El servidor de useapi.net funciona con la misma cuenta de ACE Music y agrega todo lo demás (al 18 de noviembre de 2026): | | MCP de ACE Music de useapi.net | MCP propio de ACE Music | |---|---|---| | ACE-Step v1.5 XL, 0 créditos en todos los planes | Sí | No, solo ACE Music v1 y v1.1 | | Descarga de MP3 en el plan Free | Sí | No, toda descarga requiere un plan de pago | | Covers, remixes, ediciones y mashups | Una llamada para cada uno, a partir de tus canciones | El asistente los arma a partir de una partitura transcrita | | Stems: voz e instrumental, o cada instrumento | Sí | No | | Partituras MusicXML | Sí | No, solo MIDI | | Estilo, letra y título escritos por ACE Music a partir de una idea de una línea | Sí | No, los escribe el asistente | | Varias cuentas de ACE Music en una sola conexión | Sí | Una cuenta por conexión | | Token de API para scripts, n8n y agentes sin interfaz, además de OAuth | Sí | Solo inicio de sesión con OAuth | | Las mismas llamadas por REST, con jobs y webhooks | Sí | No | useapi.net es un servicio de terceros, sin afiliación con ACE Music. ACE Music juga punya MCP server sendiri di `https://acemusic.ai/mcp`. Server itu membuat lagu ACE Music v1 dan v1.1 dari gaya dan lirik yang ditulis asisten Anda. Server useapi.net bekerja di akun ACE Music yang sama dan menambahkan sisanya (per 18 November 2026): | | MCP ACE Music dari useapi.net | MCP milik ACE Music sendiri | |---|---|---| | ACE-Step v1.5 XL, 0 kredit di semua paket | Ya | Tidak, hanya ACE Music v1 dan v1.1 | | Download MP3 di paket Free | Ya | Tidak, setiap download butuh paket berbayar | | Cover, remix, edit, dan mashup | Masing-masing satu panggilan, dari lagu Anda | Dirangkai oleh asisten dari partitur hasil transkripsi | | Stem: vokal dan instrumental, atau setiap instrumen | Ya | Tidak | | Partitur MusicXML | Ya | Tidak, hanya MIDI | | Gaya, lirik, dan judul ditulis ACE Music dari ide satu baris | Ya | Tidak, asisten yang menulisnya | | Beberapa akun ACE Music dalam satu koneksi | Ya | Satu akun per koneksi | | Token API untuk skrip, n8n, dan agen headless, plus OAuth | Ya | Hanya login OAuth | | Panggilan yang sama lewat REST, dengan job dan webhook | Ya | Tidak | useapi.net adalah layanan pihak ketiga dan tidak berafiliasi dengan ACE Music. ACE Music も独自の MCP サーバーを `https://acemusic.ai/mcp` で提供しています。こちらは、アシスタントが書いたスタイルと歌詞から ACE Music v1 と v1.1 の曲を作ります。useapi.net のサーバーは同じ ACE Music アカウントで動き、それ以外のすべてを補います(2026年11月18日時点)。 | | useapi.net の ACE Music MCP | ACE Music 独自の MCP | |---|---|---| | ACE-Step v1.5 XL、どのプランでも0クレジット | 対応 | 非対応、ACE Music v1 と v1.1 のみ | | Free プランでの MP3 ダウンロード | 対応 | 非対応、ダウンロードにはすべて有料プランが必要 | | カバー、リミックス、編集、マッシュアップ | お手持ちの曲から、それぞれ1回の呼び出しで | 書き起こした楽譜をもとにアシスタントが組み立てる | | ステム:ボーカルとインスト、または楽器ごと | 対応 | 非対応 | | MusicXML の楽譜 | 対応 | 非対応、MIDI のみ | | 1行のアイデアから ACE Music がスタイル、歌詞、タイトルを書く | 対応 | 非対応、アシスタントが書く | | 1つの接続で複数の ACE Music アカウント | 対応 | 1接続につき1アカウント | | スクリプト、n8n、ヘッドレスエージェント向けの API トークンと OAuth | 対応 | OAuth サインインのみ | | 同じ呼び出しを REST で、ジョブと Webhook 付きで | 対応 | 非対応 | useapi.net はサードパーティのサービスで、ACE Music とは提携していません。 O ACE Music também tem o próprio servidor MCP em `https://acemusic.ai/mcp`. Ele gera músicas do ACE Music v1 e v1.1 a partir do estilo e da letra que o seu assistente escreve. O servidor da useapi.net funciona na mesma conta do ACE Music e acrescenta todo o resto (em 18 de novembro de 2026): | | MCP do ACE Music da useapi.net | MCP do próprio ACE Music | |---|---|---| | ACE-Step v1.5 XL, 0 créditos em todos os planos | Sim | Não, só ACE Music v1 e v1.1 | | Download de MP3 no plano Free | Sim | Não, todo download exige um plano pago | | Covers, remixes, edições e mashups | Uma chamada para cada, a partir das suas músicas | Montados pelo assistente a partir de uma partitura transcrita | | Stems: vocal e instrumental, ou cada instrumento | Sim | Não | | Partituras MusicXML | Sim | Não, só MIDI | | Estilo, letra e título escritos pelo ACE Music a partir de uma ideia de uma linha | Sim | Não, o assistente escreve | | Várias contas do ACE Music em uma só conexão | Sim | Uma conta por conexão | | Token de API para scripts, n8n e agentes headless, além de OAuth | Sim | Só login com OAuth | | As mesmas chamadas via REST, com jobs e webhooks | Sim | Não | A useapi.net é um serviço de terceiros, sem afiliação com o ACE Music. ACE Music มี MCP server ของตัวเองด้วยที่ `https://acemusic.ai/mcp` ซึ่งสร้างเพลง ACE Music v1 และ v1.1 จากสไตล์และเนื้อเพลงที่ผู้ช่วย AI ของคุณเขียน ส่วน server ของ useapi.net ทำงานบนบัญชี ACE Music เดียวกันและเพิ่มส่วนที่เหลือทั้งหมด (ข้อมูล ณ วันที่ 18 พฤศจิกายน 2026): | | ACE Music MCP ของ useapi.net | MCP ของ ACE Music เอง | |---|---|---| | ACE-Step v1.5 XL ใช้ 0 เครดิตในทุกแพ็กเกจ | ได้ | ไม่ได้ มีแค่ ACE Music v1 และ v1.1 | | ดาวน์โหลด MP3 ในแพ็กเกจ Free | ได้ | ไม่ได้ ทุกการดาวน์โหลดต้องใช้แพ็กเกจเสียเงิน | | คัฟเวอร์ รีมิกซ์ การแก้ไข และแมชอัป | เรียกครั้งเดียวต่ออย่าง จากเพลงของคุณ | ผู้ช่วย AI ประกอบเองจากโน้ตเพลงที่ถอดออกมา | | สเต็ม: เสียงร้องกับดนตรี หรือแยกทุกเครื่องดนตรี | ได้ | ไม่ได้ | | โน้ตเพลง MusicXML | ได้ | ไม่ได้ มีแค่ MIDI | | ACE Music เขียนสไตล์ เนื้อเพลง และชื่อเพลงจากไอเดียบรรทัดเดียว | ได้ | ไม่ได้ ผู้ช่วย AI ต้องเขียนเอง | | หลายบัญชี ACE Music ในการเชื่อมต่อเดียว | ได้ | หนึ่งบัญชีต่อการเชื่อมต่อ | | API token สำหรับสคริปต์ n8n และเอเจนต์ที่ไม่มีหน้าจอ พร้อม OAuth | ได้ | ล็อกอินด้วย OAuth เท่านั้น | | เรียกแบบเดียวกันผ่าน REST พร้อมงานและ webhook | ได้ | ไม่ได้ | useapi.net เป็นบริการของบุคคลที่สาม ไม่มีส่วนเกี่ยวข้องกับ ACE Music ACE Music cũng có MCP server riêng tại `https://acemusic.ai/mcp`. Server này tạo bài hát ACE Music v1 và v1.1 từ phong cách và lời bài hát do trợ lý của bạn viết. Server của useapi.net chạy trên cùng tài khoản ACE Music và bổ sung phần còn lại (tính đến 18 tháng 11 năm 2026): | | MCP ACE Music của useapi.net | MCP riêng của ACE Music | |---|---|---| | ACE-Step v1.5 XL, 0 credit trên mọi gói | Có | Không, chỉ ACE Music v1 và v1.1 | | Tải MP3 trên gói Free | Có | Không, mọi lượt tải đều cần gói trả phí | | Cover, remix, chỉnh sửa và mashup | Mỗi thứ một lệnh gọi, từ bài hát của bạn | Trợ lý tự ghép lại từ bản nhạc được chép ra | | Stem: giọng hát và nhạc nền, hoặc từng nhạc cụ | Có | Không | | Bản nhạc MusicXML | Có | Không, chỉ MIDI | | Phong cách, lời và tên bài do ACE Music viết từ một ý tưởng một dòng | Có | Không, trợ lý tự viết | | Nhiều tài khoản ACE Music trong một kết nối | Có | Một tài khoản cho mỗi kết nối | | API token cho script, n8n và agent chạy không giao diện, cùng với OAuth | Có | Chỉ đăng nhập OAuth | | Cùng các lệnh gọi qua REST, có job và webhook | Có | Không | useapi.net là dịch vụ của bên thứ ba, không liên kết với ACE Music. ACE Music 也在 `https://acemusic.ai/mcp` 运行自己的 MCP 服务器。它根据你的助手写好的风格和歌词生成 ACE Music v1 和 v1.1 歌曲。useapi.net 的服务器使用同一个 ACE Music 账号,并补上其余的一切(截至 2026 年 11 月 18 日): | | useapi.net ACE Music MCP | ACE Music 自己的 MCP | |---|---|---| | ACE-Step v1.5 XL,所有套餐都是 0 积分 | 支持 | 不支持,只有 ACE Music v1 和 v1.1 | | 免费套餐下载 MP3 | 支持 | 不支持,任何下载都需要付费套餐 | | 翻唱、重混、编辑和混搭 | 基于你的歌曲,各一次调用 | 由助手根据转写出的乐谱拼凑完成 | | 分轨:人声和伴奏,或每件乐器 | 支持 | 不支持 | | MusicXML 乐谱 | 支持 | 不支持,只有 MIDI | | 由 ACE Music 根据一句话的想法写出风格、歌词和标题 | 支持 | 不支持,由助手来写 | | 一个连接中使用多个 ACE Music 账号 | 支持 | 每个连接一个账号 | | 用于脚本、n8n 和无界面智能体的 API Token,另有 OAuth | 支持 | 只能 OAuth 登录 | | 通过 REST 进行同样的调用,带任务和 webhook | 支持 | 不支持 | useapi.net 是第三方服务,与 ACE Music 无关联。 ACE Music also runs its own MCP server at `https://acemusic.ai/mcp`. It makes ACE Music v1 and v1.1 songs from the style and lyrics your assistant writes. The useapi.net server works on the same ACE Music account and adds the rest (as of November 18, 2026): | | useapi.net ACE Music MCP | ACE Music's own MCP | |---|---|---| | ACE-Step v1.5 XL, 0 credits on every plan | Yes | No, ACE Music v1 and v1.1 only | | MP3 download on the Free plan | Yes | No, every download needs a paid plan | | Covers, remixes, edits and mashups | One call each, from your songs | Pieced together by the assistant from a transcribed score | | Stems: vocals and instrumental, or every instrument | Yes | No | | MusicXML scores | Yes | No, MIDI only | | Style, lyrics and title written by ACE Music from a one-line idea | Yes | No, the assistant writes them | | Several ACE Music accounts in one connection | Yes | One account per connection | | API token for scripts, n8n and headless agents, plus OAuth | Yes | OAuth sign-in only | | The same calls over REST, with jobs and webhooks | Yes | No | useapi.net is a third-party service, not affiliated with ACE Music. ### Genera por lotes con los scripts El [repositorio de GitHub `acemusic-api`](https://github.com/useapi/acemusic-api) tiene un ejemplo por función, enlazado desde cada sección anterior: un script de Node.js y su gemelo en Python, sin nada que instalar. Cada uno lee sus solicitudes de un `prompts.json` que tú editas, ejecuta hasta 4 a la vez, consulta los jobs y guarda en su carpeta `output/` las dos canciones, sus portadas, el registro del job y un `ledger.jsonl` con los créditos gastados. Necesitas [Node.js](https://nodejs.org) 21 o posterior o [Python](https://www.python.org) 3.8 o posterior. `--only 3` ejecuta el tercer prompt de abajo, una canción de ACE-Step sin créditos, así que funciona con una cuenta Free: ```bash git clone https://github.com/useapi/acemusic-api.git && cd acemusic-api export USEAPI_TOKEN="user:12345-..." node songs-from-prompt/songs-from-prompt.mjs --only 3 ``` Cada registro de job guardado contiene los `songId` de las canciones, y `--from <job>.json --pick 1` pasa la canción 1 al siguiente script para hacer un cover, un mashup o separarla en stems. <details markdown="block"> <summary>Abrir `songs-from-prompt/prompts.json`</summary> ```json [ { "_about": "ACE Music v1 (the default model, 4 credits for two songs): ACE Music writes the style, lyrics and title from your idea", "prompt": "A late-night neo-soul slow jam about two strangers sharing an umbrella at a bus stop in the rain and missing the last bus on purpose. Warm Rhodes piano, brushed drums, round upright bass, a smoky female lead with close three-part harmonies on the chorus.", "model": "acemusic-v1" }, { "_about": "ACE Music v1.1 Preview (4 credits): writes a score first, then the audio", "prompt": "An anthemic Celtic folk-rock singalong about a fishing crew racing a storm back to the harbor. Fiddle and tin whistle hooks, stomping kick drum, bodhran, a gravelly male lead and the whole crew shouting the chorus.", "model": "acemusic-v1.1" }, { "_about": "ACE-Step v1.5 XL (no credits on any ACE Music plan, the Free plan included)", "prompt": "A breezy bossa nova for a lazy Sunday afternoon in Lisbon: nylon-string guitar, soft brushed snare, upright bass, a gentle flute line and a warm male and female duet sung in Portuguese.", "model": "ace-step-1.5-xl" } ] ``` </details> ### Ejemplos Todas las canciones de abajo se hicieron el 14 de noviembre de 2026 (PST) con los scripts del repositorio en una cuenta Artist de ACE Music, y cada una es la primera de las dos canciones de su solicitud. Los títulos son de ACE Music, salvo cuando pusimos uno, los tiempos van desde la solicitud hasta que terminan las dos canciones, y las llamadas muestran ids inventados. #### Una canción a partir de una imagen Entra una imagen y una frase de estilo, salen dos canciones terminadas. Subimos esta foto de una mascota robot bailando y pedimos drum and bass. ACE Music escribió la letra a partir de lo que vio: "Teal fur shaking on the concrete floor, orange high-tops squeaking by the studio door". <img src="https://media.useapi.net/blog/2026-09-07-260907/dreamina-longvideo-ref-robot-mascot.png" alt="Una mascota robot peluda de color verde azulado, con cabeza de caja, una antena y ojos luminosos, bailando con tenis altos naranjas" style="width: 100%; max-width: 220px;" loading="lazy"> ``` Bouncy, playful drum and bass for a dancing robot mascot: rolling breakbeats at 174 bpm, a wobbly reese bass, bleepy robot synth hooks, vocoder chops, cheeky and upbeat. ``` ACE Music v1 — "Bleep Boop Bounce" · 2:47 · generada en 72 s <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/files' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: image/png' \ --data-binary @robot-mascot.png curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "Bouncy, playful drum and bass for a dancing robot mascot: rolling breakbeats at 174 bpm, a wobbly reese bass, bleepy robot synth hooks, vocoder chops, cheeky and upbeat.", "model": "acemusic-v1", "images": ["user:12345-example@example.com-media:cx_3b9e1d7a5c2f48e0a6d4b8c1"], "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-bleep-boop-bounce-drum-and-bass-from-robot-image.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> La canción como YouTube Short, con la foto: [Bleep Boop Bounce en YouTube](https://youtube.com/shorts/z_aOmILvIng). #### Canciones a partir de un prompt La canción de ACE Music v1 a partir de un prompt, "Let the 44 Roll By", está en el [recorrido paso a paso](#what-you-get-back). Dos prompts más, con los otros dos modelos: ``` An anthemic Celtic folk-rock singalong about a fishing crew racing a storm back to the harbor. Fiddle and tin whistle hooks, stomping kick drum, bodhran, a gravelly male lead and the whole crew shouting the chorus. ``` ACE Music v1.1 Preview — "Haul for the Harbor Light" · 2:51 · generada en 43 s <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "An anthemic Celtic folk-rock singalong about a fishing crew racing a storm back to the harbor. Fiddle and tin whistle hooks, stomping kick drum, bodhran, a gravelly male lead and the whole crew shouting the chorus.", "model": "acemusic-v1.1", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-1-haul-for-the-harbor-light-celtic-folk-rock-from-prompt.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ``` A breezy bossa nova for a lazy Sunday afternoon in Lisbon: nylon-string guitar, soft brushed snare, upright bass, a gentle flute line and a warm male and female duet sung in Portuguese. ``` ACE-Step v1.5 XL, sin créditos — "Domingo em Alfama" · 3:28 <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "A breezy bossa nova for a lazy Sunday afternoon in Lisbon: nylon-string guitar, soft brushed snare, upright bass, a gentle flute line and a warm male and female duet sung in Portuguese.", "model": "ace-step-1.5-xl", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-domingo-em-alfama-bossa-nova-from-prompt.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### Tu propia letra Dos estrofas, un pre-coro, un puente y un outro escritos por nosotros, con una duración pedida de 210 segundos: ``` Style: cinematic indie pop ballad, felt piano, swelling strings, deep heartbeat kick, intimate female vocal that opens up into a soaring chorus, 72 bpm Lyrics: [Verse 1] We wrote our names on paper lanterns / Down by the river in July … [Chorus] Light it up and let it go / Every word I never said out loud … ``` ACE Music v1 — "Paper Lanterns" · 3:29 · generada en 61 s <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "title": "Paper Lanterns", "style": "cinematic indie pop ballad, felt piano, swelling strings, deep heartbeat kick, intimate female vocal that opens up into a soaring chorus, 72 bpm", "lyrics": "[Verse 1]\nWe wrote our names on paper lanterns\nDown by the river in July\nYou said the wind would know the answer\nIf we just let the fire fly\nYour hand was shaking, mine was steady\nAt least that'\''s how I tell it now\nWe watched them climb until the city\nWas just a glow beneath the clouds\n\n[Pre-Chorus]\nSo every summer I come back here\nStrike a match and hold it near\n\n[Chorus]\nLight it up and let it go\nEvery word I never said out loud\nLight it up and let it go\nHigher than the both of us somehow\nAnd if it finds you anyhow\nTell me you can see it from the clouds\n\n[Verse 2]\nThey tore the old pier down last winter\nPut up a fence and painted lines\nBut I still know the way by heartbeat\nI find the water every time\nI keep a lighter in my pocket\nI keep your laugh inside my head\nI fold the paper like you showed me\nAnd write the things I should have said\n\n[Pre-Chorus]\nSo every summer I come back here\nStrike a match and hold it near\n\n[Chorus]\nLight it up and let it go\nEvery word I never said out loud\nLight it up and let it go\nHigher than the both of us somehow\nAnd if it finds you anyhow\nTell me you can see it from the clouds\n\n[Bridge]\nPaper and fire, paper and fire\nNothing this light should rise so high\nPaper and fire, paper and fire\nMaybe that'\''s how we say goodbye\n\n[Final Chorus]\nLight it up and let it go\nEvery word I never said out loud\nLight it up and let it go\nHigher than the both of us somehow\n\n[Outro]\nDown by the river in July", "model": "acemusic-v1", "duration": 210, "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-paper-lanterns-custom-lyrics.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Un instrumental: `instrumental: true`, 150 segundos y sin voces, coro ni guitarra acústica: ``` Style: cinematic synthwave instrumental for a night drive: pulsing analog bass arpeggio, gated reverb drums, lush pads, a soaring lead synth melody, builds to a big final section, 108 bpm ``` ACE Music v1 — "Neon Overpass" · 2:29 · generada en 46 s <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "title": "Neon Overpass", "style": "cinematic synthwave instrumental for a night drive: pulsing analog bass arpeggio, gated reverb drums, lush pads, a soaring lead synth melody, builds to a big final section, 108 bpm", "instrumental": true, "model": "acemusic-v1", "duration": 150, "negative": "vocals, choir, acoustic guitar", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-neon-overpass-synthwave-instrumental.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Una letra en español sobre una fiesta en la azotea durante un apagón: ``` Style: modern cumbia pop, bright accordion hooks, güira and congas, warm bass, a festive male lead with a crowd shouting the chorus, 98 bpm Lyrics: [Chorus] Bailando en la azotea / Con las estrellas de farol … ``` ACE Music v1 — "Bailando en la Azotea" · 2:32 · generada en 46 s <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "title": "Bailando en la Azotea", "style": "modern cumbia pop, bright accordion hooks, güira and congas, warm bass, a festive male lead with a crowd shouting the chorus, 98 bpm", "lyrics": "[Verse 1]\nSe fue la luz en todo el barrio\nY nadie quiere irse a dormir\nDoña Rosa saca el radio viejo\nY la noche empieza a sonreír\nLos vecinos suben con sus sillas\nAlguien trae limones y café\nY la ciudad allá abajo, oscura\nNos mira bailar sin saber por qué\n\n[Pre-Chorus]\nSube, sube, que la luna está invitando\nSube, sube, que la calle está cantando\n\n[Chorus]\nBailando en la azotea\nCon las estrellas de farol\nQue se entere todo el mundo\nQue esta noche no hay apagón\nBailando en la azotea\nCon el corazón de tambor\nSi se apaga la ciudad entera\nAquí arriba sobra amor\n\n[Verse 2]\nEl abuelo saca la guitarra\nLa vecina de enfrente se animó\nLos niños corren entre las sábanas\nQue el viento de la tarde colgó\nNadie sabe cuándo vuelve la corriente\nY la verdad, a nadie le importó\nEsta fiesta no la paga nadie\nEsta fiesta la invitó el apagón\n\n[Chorus]\nBailando en la azotea\nCon las estrellas de farol\nQue se entere todo el mundo\nQue esta noche no hay apagón\nBailando en la azotea\nCon el corazón de tambor\nSi se apaga la ciudad entera\nAquí arriba sobra amor\n\n[Outro]\nQue esta noche no hay apagón", "model": "acemusic-v1", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-bailando-en-la-azotea-spanish-cumbia.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Letra del generador de letras, estilo del generador de estilos, cantada por ACE-Step: ``` Lyrics writer: A wistful country song about an old pickup truck that still has her mixtape stuck in the tape deck Style writer: classic country ballad, pedal steel, warm baritone ``` ACE-Step v1.5 XL, sin créditos — "Side B Forever" · 3:35 · generada en 40 s, después de 6 s para la letra y 4 s para el estilo <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music/lyrics' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "A wistful country song about an old pickup truck that still has her mixtape stuck in the tape deck", "style": "classic country ballad, pedal steel, warm baritone", "model": "ace-step-1.5-xl" }' > lyrics.json curl -X POST 'https://api.useapi.net/v1/acemusic/music/style' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "style": "classic country ballad, pedal steel, warm baritone", "model": "ace-step-1.5-xl" }' > style.json # sing what the writers returned jq -n --slurpfile l lyrics.json --slurpfile s style.json \ '{title: $l[0].title, lyrics: $l[0].lyrics, style: $s[0].style, model: "ace-step-1.5-xl", async: true}' | curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d @- ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-side-b-forever-lyrics-and-style-writers.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### ACE-Step con tempo, tonalidad y compás fijos Cada una volvió exactamente con la duración pedida. ``` 3/4 · 84 bpm · D minor · 120 s · thinking 60 · avoid: trap drums, EDM, autotune Style: dark cabaret waltz, accordion, pizzicato strings, upright bass, brushed snare, theatrical female vocal ``` ACE-Step v1.5 XL, sin créditos — "Midnight Waltz" · 2:00 · generada en 31 s <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "model": "ace-step-1.5-xl", "title": "Midnight Waltz", "style": "dark cabaret waltz, accordion, pizzicato strings, upright bass, brushed snare, theatrical female vocal", "lyrics": "[Verse 1]\nThe band plays slow when the lights go low\nAnd the chandeliers begin to sway\nTake my hand, we will dance till the candles stand\nIn puddles of yesterday\n\n[Chorus]\nOne, two, three, turn around with me\nRound and round till the morning comes\nOne, two, three, oh don'\''t let me be\nThe last one dancing when the music'\''s done\n\n[Verse 2]\nThe clock strikes twelve and it laughs at itself\nEvery mirror wears a stranger'\''s face\nHold me close, we are only ghosts\nWho forgot to leave this place\n\n[Chorus]\nOne, two, three, turn around with me\nRound and round till the morning comes\nOne, two, three, oh don'\''t let me be\nThe last one dancing when the music'\''s done", "bpm": 84, "timeSignature": "3/4", "key": "D minor", "duration": 120, "negative": "trap drums, EDM, autotune", "thinking": 60, "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-midnight-waltz-3-4-84-bpm-d-minor.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ``` 6/8 · 116 bpm · G major · 90 s · instrumental Style: lively celtic instrumental jig, fiddle and tin whistle trading the melody, bodhran, strummed bouzouki, foot stomps ``` ACE-Step v1.5 XL, sin créditos — "Harbour Jig" · 1:30 · generada en 20 s <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "model": "ace-step-1.5-xl", "title": "Harbour Jig", "style": "lively celtic instrumental jig, fiddle and tin whistle trading the melody, bodhran, strummed bouzouki, foot stomps", "instrumental": true, "bpm": 116, "timeSignature": "6/8", "key": "G major", "duration": 90, "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-harbour-jig-6-8-116-bpm-g-major.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ``` 4/4 · 174 bpm · F minor · 150 s · thinking 80 Style: liquid drum and bass, rolling breakbeats, deep warm sub bass, airy pads, soulful female vocal ``` ACE-Step v1.5 XL, sin créditos — "Almost Home" · 2:30 · generada en 41 s <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "model": "ace-step-1.5-xl", "title": "Almost Home", "style": "liquid drum and bass, rolling breakbeats, deep warm sub bass, airy pads, soulful female vocal", "lyrics": "[Verse]\nCity lights in the rear view mirror\nRunning on a borrowed night\nEvery bridge is a little bit nearer\nEvery tunnel full of light\n\n[Chorus]\nHold on, we'\''re almost home\nEvery signal turning green\nHold on, you'\''re not alone\nFaster than the in-between\n\n[Verse]\nRadio low and the windows open\nBreathing in the summer rain\nEvery promise we left unspoken\nRushing back to us again\n\n[Chorus]\nHold on, we'\''re almost home\nEvery signal turning green\nHold on, you'\''re not alone\nFaster than the in-between", "bpm": 174, "timeSignature": "4/4", "key": "F minor", "duration": 150, "thinking": 80, "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-almost-home-drum-and-bass-174-bpm-f-minor.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### Un cover, un remix y una edición "Paper Lanterns" como cover, con un estilo nuevo que conserva su melodía: ``` mode: cover · stripped-back acoustic folk cover, fingerpicked steel-string guitar, warm cello, soft close-mic'd male vocal ``` ACE Music v1.1 Preview — "Paper Lanterns (Acoustic Folk Cover)" · 3:34 · generada en 72 s <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash # our script read the score first (free for an ACE Music v1 song; the API now does this by itself) curl 'https://api.useapi.net/v1/acemusic/music/score?songId=user%3A12345-example%40example.com-song%3Aso_4e7b2c9d0a5f4183b6d8e2c7' \ -H 'Authorization: Bearer user:12345-…' > /dev/null curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "mode": "cover", "model": "acemusic-v1.1", "references": ["user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7"], "style": "stripped-back acoustic folk cover, fingerpicked steel-string guitar, warm cello, soft close-mic'\''d male vocal", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-1-paper-lanterns-acoustic-folk-cover.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> "Bailando en la Azotea" en versión deep house. No enviamos título, así que ACE Music la llamó "Reference 1": ``` mode: remix · coverStrength 40 · remixStrength 50 · deep house remix, four-on-the-floor kick, plucky chords, rolling bassline, filtered vocal chops ``` ACE-Step v1.5 XL, sin créditos — "Reference 1" · 2:32 · generada en 31 s <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "mode": "remix", "model": "ace-step-1.5-xl", "references": ["user:12345-example@example.com-song:so_9d3b7e2c1a6f4085b8e4d1c6"], "style": "deep house remix, four-on-the-floor kick, plucky chords, rolling bassline, filtered vocal chops", "coverStrength": 40, "remixStrength": 50, "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-bailando-en-la-azotea-house-remix.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> "Paper Lanterns" con letra nueva entre los segundos 30 y 50, y el resto intacto: ``` mode: edit · start 30 · end 50 Lyrics: We wrote our names on paper lanterns / Down by the harbor in the snow / You said the stars would keep the answer / If we were brave enough to go ``` ACE-Step v1.5 XL, sin créditos — "Reference 1" · 3:29 · generada en 41 s <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "mode": "edit", "model": "ace-step-1.5-xl", "references": ["user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7"], "start": 30, "end": 50, "style": "cinematic indie pop ballad, felt piano, swelling strings, intimate female vocal", "lyrics": "We wrote our names on paper lanterns\nDown by the harbor in the snow\nYou said the stars would keep the answer\nIf we were brave enough to go", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-paper-lanterns-edit-seconds-30-50.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### Mashups "Paper Lanterns" y "Let the 44 Roll By": ``` upbeat neo-soul pop mashup, punchy live drums, warm Rhodes and strings, female lead with a gospel-tinged choir on the chorus · audioInfluence 60 ``` ACE Music v1.1 Preview — "Lanterns at the Bus Stop" · 3:58 · generada en 83 s <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash # our script read each song's score first (the API now does this by itself for ACE Music v1 songs) curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "mode": "mashup", "model": "acemusic-v1.1", "references": ["user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7", "user:12345-example@example.com-song:so_7c1d9e3a5b2f4806a4e1c9d3"], "title": "Lanterns at the Bus Stop", "style": "upbeat neo-soul pop mashup, punchy live drums, warm Rhodes and strings, female lead with a gospel-tinged choir on the chorus", "audioInfluence": 60, "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-1-mashup-lanterns-at-the-bus-stop.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> "Haul for the Harbor Light" y "Bailando en la Azotea", pedidos con ACE Music v1: ``` festive celtic cumbia mashup, fiddle and accordion trading hooks, congas and bodhran, stomping kick, male lead with a big crowd chorus ``` ACE Music v1.1 Preview (pedido: v1) — "Harbor Fiesta" · 2:38 · generada en 74 s <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash # our script read each song's score first (the API now does this by itself for ACE Music v1 songs) curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "mode": "mashup", "model": "acemusic-v1", "references": ["user:12345-example@example.com-song:so_2a8f6c1e9d4b47f3b0c5e8a2", "user:12345-example@example.com-song:so_9d3b7e2c1a6f4085b8e4d1c6"], "title": "Harbor Fiesta", "style": "festive celtic cumbia mashup, fiddle and accordion trading hooks, congas and bodhran, stomping kick, male lead with a big crowd chorus", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-1-mashup-harbor-fiesta-asked-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Tres canciones a la vez: "Paper Lanterns", "Bailando en la Azotea" y "Let the 44 Roll By": ``` warm late-night soul-pop medley, Rhodes and strings, light latin percussion, female lead with a male answer on the last chorus ``` ACE Music v1.1 Preview — "Three Songs, One Night" · 3:32 · generada en 43 s <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash # our script read each song's score first (the API now does this by itself for ACE Music v1 songs) curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "mode": "mashup", "model": "acemusic-v1.1", "references": ["user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7", "user:12345-example@example.com-song:so_9d3b7e2c1a6f4085b8e4d1c6", "user:12345-example@example.com-song:so_7c1d9e3a5b2f4806a4e1c9d3"], "title": "Three Songs, One Night", "style": "warm late-night soul-pop medley, Rhodes and strings, light latin percussion, female lead with a male answer on the last chorus", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-1-mashup-three-songs-one-night.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### Tu audio y tus imágenes El "Harbour Jig" de arriba, subido como MP3 y usado como referencia de un prompt. ACE Music lo ejecutó con v1.1 para conservar la melodía: ``` A rowdy pub singalong with a big shouted chorus about the last ferry home, built on the tune of this recording ``` ACE Music v1.1 Preview (pedido: v1) — "Last Ferry Home" · 1:36 · generada en 52 s <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/files?title=Harbour%20Jig%20demo' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: audio/mpeg' \ --data-binary @harbour-jig-demo.mp3 curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "A rowdy pub singalong with a big shouted chorus about the last ferry home, built on the tune of this recording", "model": "acemusic-v1", "references": ["user:12345-example@example.com-song:so_5f1a3c8e7b2d49a6c3e0f7b9"], "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-1-last-ferry-home-from-uploaded-jig.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### Stems de "Paper Lanterns" La voz y el instrumental de `mode: "vocals"` (5 créditos), y luego la batería y las cuerdas de los 9 stems de `mode: "all"` (60 créditos). <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music/stems' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "songId": "user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7", "mode": "vocals", "async": true }' curl -X POST 'https://api.useapi.net/v1/acemusic/music/stems' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "songId": "user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7", "mode": "all", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-paper-lanterns-stem-vocal.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-paper-lanterns-stem-instrumental.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-paper-lanterns-stem-drums.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-paper-lanterns-stem-strings.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ### Preguntas **¿Existe una API de ACE Music?** Con useapi.net, sí: la [ACE Music API](/docs/api-acemusic-v1) ejecuta ACE Music v1, ACE Music v1.1 Preview y ACE-Step v1.5 XL por REST con tu cuenta de ACE Music, con covers, mashups, stems y MIDI. **¿Existe una API gratuita de ACE-Step?** Con useapi.net, sí: una canción de ACE-Step v1.5 XL no gasta créditos en ningún plan de ACE Music, incluido el plan Free, con ajustes de tempo, tonalidad, compás y duración, remixes y ediciones. El sitio de terceros acestep.io ofrece su API de ACE-Step solo en su plan Studio de US$49 al mes, unos US$0,14 por canción (a noviembre de 2026). **¿Cuánto cuesta una canción de ACE Music v1 con la API?** Con useapi.net, una canción de ACE Music v1 cuesta 2 créditos de tu plan de ACE Music: US$0,013 en Artist con pago anual y US$0,023 en Artist con pago mensual, sin nada agregado por canción. Consulta [Precios](#pricing). **¿Existe un servidor MCP de ACE Music?** Con useapi.net, sí, y hace más que el propio servidor de ACE Music en `acemusic.ai/mcp`: el [servidor MCP de ACE Music](/docs/api-acemusic-v1/mcp) alojado agrega el modelo gratuito ACE-Step v1.5 XL, descargas de MP3 en el plan Free, stems, covers, remixes, ediciones y mashups en una sola llamada, MusicXML y varias cuentas detrás de un solo token de API. El servidor propio de ACE Music crea canciones de v1 y v1.1 a partir de la letra que escribe tu asistente, y toda descarga requiere un plan de pago. Consulta la [comparación](#useapinet-vs-ace-musics-own-mcp-server). ### Conclusión Un POST genera dos canciones con el modelo que encabeza el ranking vocal, las canciones de ACE-Step no cuestan nada, y cada canción puede convertirse en un cover, un mashup, stems o un archivo MIDI en la siguiente llamada. Clona el [repositorio `acemusic-api`](https://github.com/useapi/acemusic-api), ejecuta `songs-from-prompt/` con `--only 3` en una cuenta Free y consulta [POST /music](/docs/api-acemusic-v1/post-acemusic-music) para ver todas las opciones. Visita nuestro <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> servidor de Discord</a> o nuestro <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> canal de Telegram</a> para cualquier pregunta de soporte. === URL: https://useapi.net/docs/articles/ace-music-api-tutorial-id === Document URL: https://useapi.net/docs/articles/ace-music-api-tutorial-id --- layout: default title: Cara Membuat Lagu AI dengan ACE Music API description: "Buat lagu dengan ACE Music v1, v1.1 dan ACE-Step v1.5 XL yang gratis lewat ACE Music API useapi.net: prompt, lirik sendiri, cover, mashup, stem, MIDI, dengan curl dan kode." keywords: [ACE Music API, ACE Music v1 API, ACE-Step API, ACE-Step v1.5 XL, AI song generator API, text to music API, Suno alternative, AI music API, stems API, MIDI, MusicXML, mashup, cover song AI, MCP server, API ACE Music, API ACE-Step gratis, API pembuat lagu AI, API musik AI, membuat lagu AI, alternatif Suno, tutorial bahasa Indonesia, curl] image: https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-paper-lanterns-cover-art.jpg parent: Articles nav_exclude: true lang: id translation_key: ace-music-tutorial date: 2026-11-14 last_modified: 2026-11-18 nav_order: 302 repo: https://github.com/useapi/acemusic-api --- ## Cara Membuat Lagu AI dengan ACE Music API {: .no_toc #how-to-generate-ai-songs-with-the-ace-music-api } 22 menit baca • 14 November 2026 ## Daftar isi {: .no_toc .text-delta #table-of-contents } ### Pendahuluan [ACE Music API](/docs/api-acemusic-v1) dari useapi.net mengubah satu panggilan REST menjadi dua lagu jadi dari [ACE Music](https://acemusic.ai), lengkap dengan vokal, lirik, judul, dan cover art, memakai langganan ACE Music yang sudah Anda punya. ACE Music v1 menempati peringkat #1 di [papan peringkat musik vokal Artificial Analysis](https://artificialanalysis.ai/music/leaderboard/vocals), di atas Suno v6. [ACE-Step](https://ace-step.github.io) v1.5 XL yang open source berjalan lewat API yang sama tanpa memakai kredit di paket ACE Music mana pun, termasuk paket Free. Panduan ini dimulai dengan tiga model dan biaya satu lagu, membuat satu lagu dari awal sampai akhir dengan `curl`, lalu merangkum semua fitur lainnya dalam satu tabel singkat. [Contoh](#examples) di bagian akhir berisi 18 lagu yang kami buat untuk halaman ini, masing-masing dengan request yang membuatnya, semuanya dari skrip di [repo GitHub `acemusic-api`](https://github.com/useapi/acemusic-api) (Node.js dan Python), dengan total 117 kredit paket Artist, termasuk take tambahan. useapi.net adalah API [pihak ketiga](/docs/legal#affiliation--third-party-services) dan tidak berafiliasi dengan ACE Music maupun pembuatnya, Timedomain. ### Model dan kemampuan API Setiap request membuat dua lagu, dan `model` menentukan siapa yang membuatnya: | Model | `model` | Kegunaan | Pengaturan | Kredit per request | Waktu di uji kami | |---|---|---|---|---|---| | ACE Music v1 | `acemusic-v1` (default) | Model vokal #1: lagu dari prompt atau dari lirik Anda, dengan vokal atau instrumental | `duration` 30 sampai 600 s, `negative`, `styleInfluence`, unduhan WAV | 4 | 46 sampai 89 s | | ACE Music v1.1 Preview | `acemusic-v1.1` | Menulis partitur (score) lebih dulu, jadi cover dan mashup-nya mengikuti melodi lagu aslinya | `audioInfluence`, `styleInfluence` | 4 | 35 sampai 83 s | | ACE-Step v1.5 XL | `ace-step-1.5-xl` | Open source dari ACE Studio dan StepFun: lagu, remix, dan edit | `bpm`, `key`, `timeSignature`, `duration` 10 sampai 240 s, `negative`, `thinking`. Hanya MP3 | 0 | 20 sampai 55 s | Yang bisa Anda lakukan dengan model-model ini: | Fitur | Request | Catatan | |---|---|---| | Lagu dari prompt | [POST /music](/docs/api-acemusic-v1/post-acemusic-music) `prompt` | ACE Music menulis gaya, lirik, dan judulnya | | Lirik sendiri, instrumental | [POST /music](/docs/api-acemusic-v1/post-acemusic-music) `style`, `lyrics` | Bahasa apa pun | | Penulis lirik dan penulis gaya | [POST /music/lyrics](/docs/api-acemusic-v1/post-acemusic-music-lyrics), [/music/style](/docs/api-acemusic-v1/post-acemusic-music-style) | Tanpa kredit | | Cover, remix, edit, mashup | [POST /music](/docs/api-acemusic-v1/post-acemusic-music#modes) `mode` | Untuk lagu apa pun di akun | | Audio dan gambar Anda | [POST /files](/docs/api-acemusic-v1/post-acemusic-files) | Sebagai referensi untuk lagu baru | | Stem | [POST /music/stems](/docs/api-acemusic-v1/post-acemusic-music-stems) | Creator dan Artist | | Unduhan, partitur | [GET /music/download](/docs/api-acemusic-v1/get-acemusic-music-download), [/music/score](/docs/api-acemusic-v1/get-acemusic-music-score) | MP3 dan partitur di semua paket, WAV, MIDI, dan MusicXML di Creator dan Artist | | Library, job, akun | [GET /music](/docs/api-acemusic-v1/get-acemusic-music), [/jobs](/docs/api-acemusic-v1/get-acemusic-jobs), [/accounts](/docs/api-acemusic-v1/get-acemusic-accounts-email) | Semua lagu di akun, job yang sedang berjalan, sisa kredit secara langsung | | MCP server | [`/v1/acemusic/mcp`](/docs/api-acemusic-v1/mcp) | 15 tool untuk asisten AI | ### Harga ACE Music menagih kreditnya sendiri per request, dari paket ACE Music Anda, dan useapi.net tidak menambahkan biaya apa pun per lagu (per November 2026): | Request | Kredit | |---|---| | Dua lagu di ACE Music v1 atau v1.1 | 4 | | Stem, vokal + instrumental | 5, paket berbayar | | Stem, semua stem | 60, paket berbayar | | Partitur lagu ACE-Step, pembacaan pertama | 1 | | Dua lagu di ACE-Step v1.5 XL | 0, di semua paket | | Penulis lirik dan gaya, upload, unduhan | 0 di uji kami | [Paket ACE Music](https://acemusic.ai/pricing/) terdiri dari Free dengan 20 kredit per hari, Creator $9,90 per bulan untuk 1.000 kredit, dan Artist $29 per bulan untuk 2.500 kredit, atau $7,90 dan $16,58 per bulan jika ditagih tahunan. Satu lagu adalah setengah request, yaitu 2 kredit. [Ringkasan API](/docs/api-acemusic-v1#pricing) memuat tabel yang sama. Biaya satu lagu di setiap paket, dari yang termurah di kiri (satu request membuat dua lagu, jadi satu lagu memakai setengah kredit request, per November 2026): | Model | Free (20 cr/hari) | Artist $16,58/bln (2.500 cr/bln, ditagih tahunan) | Creator $7,90/bln (1.000 cr/bln, ditagih tahunan) | Creator $9,90/bln (1.000 cr/bln) | Artist $29/bln (2.500 cr/bln) | |---|---|---|---|---|---| | ACE Music v1, v1.1 (satu lagu) | $0 / 2 cr (10 lagu/hari) | $0,013 / 2 cr (1.250 lagu/bln) | $0,016 / 2 cr (500 lagu/bln) | $0,020 / 2 cr (500 lagu/bln) | $0,023 / 2 cr (1.250 lagu/bln) | | Stem (vokal + instrumental) | paket berbayar | $0,033 / 5 cr | $0,040 / 5 cr | $0,050 / 5 cr | $0,058 / 5 cr | | Stem (semua stem) | paket berbayar | $0,40 / 60 cr | $0,47 / 60 cr | $0,59 / 60 cr | $0,70 / 60 cr | | Partitur ACE-Step (pembacaan pertama) | $0 / 1 cr | $0,007 / 1 cr | $0,008 / 1 cr | $0,010 / 1 cr | $0,012 / 1 cr | | ACE-Step v1.5 XL (satu lagu) | $0 / 0 cr | $0 / 0 cr | $0 / 0 cr | $0 / 0 cr | $0 / 0 cr | Perbandingannya dengan cara lain untuk memanggil model-model ini dari kode: | Model | useapi.net | API lain | |---|---|---| | ACE Music v1, v1.1 Preview | mulai $0,013 per lagu di Artist yang ditagih tahunan, $0 dengan 20 kredit harian paket Free | — | | ACE-Step v1.5 XL | $0 di semua paket ACE Music, termasuk paket Free | sekitar $0,14 per lagu di API pihak ketiga [acestep.io](https://acestep.io/pricing), yang butuh paket Studio $49 per bulan | Di paket ACE Music mana pun, termasuk paket Free, satu lagu ACE-Step v1.5 XL tidak memakai kredit, sementara API pihak ketiga acestep.io butuh paket Studio seharga $49 per bulan (sekitar 360 lagu per bulan, sekitar $0,14 per lagu, per November 2026). ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. ### Cara membuat lagu dengan curl Anda butuh token API useapi.net, lihat [Setup useapi.net](/docs/start-here/setup-useapi), dan akun [ACE Music](https://acemusic.ai) dengan email dan password. Satu [langganan $15 per bulan](/docs/subscription) mencakup semua API useapi.net dan 3 akun ACE Music. Akun ACE Music Free juga bisa dipakai: akun itu mendapat 20 kredit per hari, dan lagu ACE-Step tidak butuh kredit sama sekali. Perintah di bawah memakai [jq](https://jqlang.org) untuk membaca JSON. #### Tambahkan akun ACE Music Anda Ekspor token, lalu tambahkan akun cukup sekali. API akan login, membaca akun, dan menyimpannya hanya jika ACE Music menerima password-nya: ```bash export USEAPI_TOKEN="user:12345-..." API=https://api.useapi.net/v1/acemusic curl -s -X POST "$API/accounts" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "example@example.com", "password": "your-acemusic-password" }' ``` Akun yang dibuat dengan Continue with Google atau nomor telepon perlu dibuatkan password dulu, lihat [Setup ACE Music](/docs/start-here/setup-acemusic), yang juga bisa menambahkan akun itu untuk Anda. #### Membuat lagu dari prompt Jelaskan lagu yang Anda mau dengan kata-kata Anda sendiri. ACE Music menulis gaya, lirik, dan judulnya, lalu membuat dua lagu. Ini request persis yang menghasilkan lagu pertama di halaman ini: ```bash curl -s -X POST "$API/music" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A late-night neo-soul slow jam about two strangers sharing an umbrella at a bus stop in the rain and missing the last bus on purpose. Warm Rhodes piano, brushed drums, round upright bass, a smoky female lead with close three-part harmonies on the chorus.", "model": "acemusic-v1", "async": true }' | tee job.json | jq '{jobid, status, model}' ``` Dengan `async: true`, API langsung menjawab `201` berisi job. Prompt bisa sampai 2.000 karakter dan membawa hingga 3 lagu referensi serta 3 gambar, lihat [Arahkan lagu dengan audio dan gambar Anda sendiri](#guide-songs-with-your-own-audio-and-images). #### Hasil yang Anda terima Selama ACE Music menulis lirik, lagu berstatus `planning` dan `Untitled`, lalu `queued` dan `running`. Lakukan polling [GET /jobs/`jobid`](/docs/api-acemusic-v1/get-acemusic-jobs-jobid) kira-kira setiap 10 detik. `jobid` mengandung `:` dan `@`, jadi lakukan URL-encode: ```bash curl -s "$API/jobs/$(jq -r .jobid job.json | jq -Rr @uri)" \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{status, songs: [.songs[] | {title, status, duration, audioUrl}]}' ``` Saat `status` bernilai `completed`, setiap lagu membawa link-nya (ID di bawah ini rekaan): ```json { "jobid": "j1115003713275918262m-u12345-email:example@example.com-task:so_7c1d9e3a5b2f4806a4e1c9d3.so_8b4f2e6a1c9d47e5a3b7c0d2-bot:acemusic", "type": "music", "status": "completed", "email": "example@example.com", "created": "2026-11-15T00:37:13.275Z", "model": "acemusic-v1", "modelUsed": "acemusic-v1", "songs": [ { "songId": "user:12345-example@example.com-song:so_7c1d9e3a5b2f4806a4e1c9d3", "taskId": "so_7c1d9e3a5b2f4806a4e1c9d3", "status": "succeeded", "title": "Let the 44 Roll By", "model": "acemusic-v1", "style": "Late-night neo-soul slow jam with a laid-back 1990s and early 2000s pocket, 72 BPM. …", "lyrics": "[Intro - Warm Rhodes chords, brushed snare rim clicks, subtle rain on asphalt]\n\n[Verse 1 …]\nWater dripping off the canvas seam\n…", "instrumental": false, "duration": 277.19, "audioUrl": "https://acemusic.ai/data/so_7c1d9e3a5b2f4806a4e1c9d3.mp3", "playUrl": "https://….r2.cloudflarestorage.com/acemusic-data-prod/users/…/audio/202611/….mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20261115T003902Z&X-Amz-Expires=3599&…", "playUrlExpires": "2026-11-15T01:39:01.000Z", "coverUrl": "https://acemusic.ai/data/so_7c1d9e3a5b2f4806a4e1c9d3-cover.jpg?v=1794703081642", "pageUrl": "https://acemusic.ai/song/r4k8w2n6p9tz", "created": "2026-11-15T00:37:13.300Z", "finished": "2026-11-15T00:38:42.208Z", "kind": "original", "score": false }, { "songId": "user:12345-example@example.com-song:so_8b4f2e6a1c9d47e5a3b7c0d2", "title": "Let the 44 Roll By", "duration": 253.99, "…": "…" } ], "completed": "2026-11-15T00:38:42.208Z" } ``` - `audioUrl` adalah link MP3 publik lagu itu dan tidak pernah berubah. `playUrl` adalah link langsung ke MP3 yang sama untuk pemutar web, berlaku sampai `playUrlExpires` (sekitar satu jam): beberapa browser, seperti Brave, memblokir redirect di balik `audioUrl`. - `songId` adalah yang dipakai cover, mashup, stem, unduhan, dan partitur. ID ini menyebut akun tempat lagu itu berada, jadi panggilan-panggilan tersebut berjalan di akun itu. - `model` adalah model yang Anda minta, `modelUsed` adalah model yang benar-benar berjalan (lihat [mashup](#mash-up-two-or-three-songs)). `kind` bernilai `original`, `cover`, `edit`, `mashup`, atau `upload`, dan `score` menunjukkan apakah lagu itu sudah punya partitur. - Lagu yang tidak berhasil dibuat ACE Music berstatus `status: "failed"`, dengan alasan dari ACE Music di `error`, dan `refunded: true` jika kreditnya dikembalikan. Dan inilah lagu pertama dari dua lagu tersebut: ACE Music v1 — "Let the 44 Roll By" · 4:37 · dibuat dalam 89 detik <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-let-the-44-roll-by-neo-soul-from-prompt.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### Sync, async, dan webhook | Yang Anda kirim | Jawaban POST | Selanjutnya | |---|---|---| | `async: true` | `201` langsung, berisi job | Polling [GET /jobs/`jobid`](/docs/api-acemusic-v1/get-acemusic-jobs-jobid) | | tanpa `async` | `200` berisi job yang sudah selesai, JSON yang sama seperti di atas | Baca lagu dari jawabannya. Request yang masih berjalan setelah 100 detik menjawab `202` berisi job: lakukan polling | | `replyUrl` dan `replyRef` | seperti di atas, baik sync maupun async | URL `https` publik Anda menerima satu `POST` berisi job yang sudah selesai, dengan `replyRef` Anda di dalamnya | Request ACE-Step kami tanpa `async` kembali dalam 37 detik, dan webhook tiba 12 detik setelah lagu selesai. Job bisa dibaca selama 7 hari, dan job yang masih berjalan 30 menit setelah dimulai gagal dengan `504`. [`async-webhooks/`](https://github.com/useapi/acemusic-api/tree/main/async-webhooks) menjalankan ketiga cara itu dan menyertakan penerima webhook kecil. <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash curl -s -X POST "$API/music" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A dreamy lo-fi hip hop beat for studying late at night: dusty vinyl crackle, mellow Rhodes chords, a soft upright bass and rain on the window", "model": "ace-step-1.5-xl", "replyUrl": "https://your-server.example.com/acemusic-hook", "replyRef": "lofi-1" }' | jq '{status, songs: [.songs[] | {title, duration, audioUrl}]}' ``` </details> ### Nyanyikan lirik Anda sendiri Kirim `style` dan `lyrics` sebagai ganti `prompt`, dan ACE Music menyanyikan kata-kata Anda dengan gaya pilihan Anda: | Field | Fungsinya | Batas | |---|---|---| | `style` | Genre, instrumen, suasana, tempo, dan vokal | 1.000 karakter, 512 di ACE-Step | | `lyrics` | Kata-kata Anda, bahasa apa pun, dengan tag `[Verse]`, `[Chorus]`, `[Bridge]` | 5.000 karakter, 2.000 di ACE-Step | | `title` | Judul lagu. Tanpa judul, ACE Music yang memilihnya | 80 karakter | | `instrumental` | `true` untuk lagu tanpa vokal. `style` tanpa `lyrics` hasilnya sama | | | `duration` | Panjang lagu dalam detik | 30 sampai 600 di ACE Music v1, 10 sampai 240 di ACE-Step | | `negative` | Gaya yang harus dihindari | 200 karakter, ACE Music v1 dan ACE-Step | | `styleInfluence` | Seberapa ketat gaya diikuti | `0` sampai `100`, default `80`, ACE Music v1 dan v1.1 | Jangan pernah mengirim `prompt` bersama field-field ini: API akan menjawab `400` dan menyebut apa yang harus dihapus. Ballad kami yang meminta `duration: 210` kembali dengan panjang 210 dan 209 detik. Lagu itu ada di [Contoh](#your-own-lyrics), bersama satu instrumental dan satu lagu berbahasa Spanyol. Belum punya lirik? [POST /music/lyrics](/docs/api-acemusic-v1/post-acemusic-music-lyrics) menulis lirik dan judul dari sebuah permintaan, dan [POST /music/style](/docs/api-acemusic-v1/post-acemusic-music-style) mengubah beberapa kata menjadi deskripsi gaya yang lengkap. Hasil kami kembali dalam 6 dan 4 detik, tanpa kredit yang terpakai. Skrip: [`custom-lyrics/`](https://github.com/useapi/acemusic-api/tree/main/custom-lyrics). ### Atur tempo, kunci nada, dan birama dengan ACE-Step ACE-Step v1.5 XL menerima pengaturan musikal yang tidak ada di model ACE Music, dan lagunya tidak memakai kredit: | Opsi | Nilai | |---|---| | `bpm` | `30` sampai `200` | | `timeSignature` | `2/4`, `3/4`, `4/4`, `6/8` | | `key` | `C major` sampai `B minor` (C, C#, D, Eb, E, F, F#, G, Ab, A, Bb, B) | | `duration` | `10` sampai `240` detik | | `negative` | gaya yang harus dihindari, hingga 200 karakter | | `thinking` | `0` sampai `100`: ACE-Step merencanakan seluruh lagu lebih dulu, lebih kreatif jika rendah, lebih stabil jika tinggi | Ketiga lagu ACE-Step kami, waltz 3/4, jig 6/8, dan drum and bass 174 bpm, kembali persis sepanjang yang diminta ([Contoh](#ace-step-at-a-set-tempo-key-and-meter)). Opsi ini hanya berlaku di `mode` `generate` pada `ace-step-1.5-xl`, dan di tempat lain API menjawab `400 Parameter bpm does not apply to mode generate on acemusic-v1`. Skrip: [`ace-step-options/`](https://github.com/useapi/acemusic-api/tree/main/ace-step-options). ### Cover, remix, dan edit `mode` mengubah request menjadi pengolahan lagu yang sudah Anda punya. `references` menerima `songId` lagu-lagu itu: lagu yang dibuat API, lagu dari [Library](#your-library) Anda, atau upload Anda sendiri. | `mode` | `references` | Berjalan di | Kredit | Fungsinya | |---|---|---|---|---| | `cover` | 1 lagu | `acemusic-v1.1`, atau ACE-Step di `ace-step-1.5-xl` | 4 / 0 | Lagu itu dengan `style` baru, mengikuti melodi, akor, dan strukturnya | | `remix` | 1 lagu | `ace-step-1.5-xl` | 0 | `coverStrength` mempertahankan aslinya, `remixStrength` menjauh darinya (`0` sampai `100`) | | `edit` | 1 lagu | `ace-step-1.5-xl` | 0 | Menulis ulang bagian antara detik `start` dan `end` dengan `lyrics` baru, sisanya tetap | | `mashup` | 2 atau 3 lagu | `acemusic-v1.1` | 4 | Satu lagu baru dari beberapa lagu, lihat di bawah | ACE Music v1.1 mengikuti melodi yang dibacanya dari partitur lagu. Cover pertama kami atas lagu ACE Music v1 yang belum punya partitur gagal dengan `ref_no_melody`, dan 4 kreditnya dikembalikan, jadi sekarang API membaca partitur lagu ACE Music v1 lebih dulu, gratis, sebelum cover atau mashup v1.1. Lagu ACE-Step tidak dibaca otomatis: jika salah satunya menjawab `400` dengan `ref_no_melody`, panggil [GET /music/score](#read-the-score) untuk lagu itu lebih dulu (1 kredit), lalu kirim ulang request-nya. Skrip: [`covers-remix-edit/`](https://github.com/useapi/acemusic-api/tree/main/covers-remix-edit). #### Mashup dua atau tiga lagu `mode: "mashup"` membuat satu lagu dari 2 atau 3 lagu di akun yang sama, dengan menggabungkan liriknya kecuali Anda mengirim `lyrics`. `audioInfluence` (0 sampai 100, default 60) mengatur seberapa dekat lagu-lagu itu diikuti. Mashup harus membaca lagu-lagunya, jadi mashup berjalan di ACE Music v1.1 Preview walaupun Anda meminta v1, sama seperti di situs ACE Music: "Harbor Fiesta" kami melaporkan `"model": "acemusic-v1"` dan `"modelUsed": "acemusic-v1.1"`, dan kreditnya mengikuti model yang berjalan. Hal yang sama terjadi pada `cover` yang diminta di v1, prompt dengan lebih dari satu referensi di ACE-Step, dan kadang prompt dengan satu lagu referensi. Skrip: [`mashup/`](https://github.com/useapi/acemusic-api/tree/main/mashup). ### Arahkan lagu dengan audio dan gambar Anda sendiri [POST /files](/docs/api-acemusic-v1/post-acemusic-files) menerima file sebagai body request mentah dengan `Content-Type`-nya: | Upload | Format | Hingga | Yang Anda dapat | Gunakan sebagai | |---|---|---|---|---| | Audio | MP3, WAV, FLAC, OGG, M4A, AAC | 100 MB, 8 menit | Sebuah `songId`: lagu Library, dengan lirik, gaya, tempo, dan melodi yang ditranskripsikan ACE Music | Salah satu dari hingga 3 `references` sebuah prompt, atau lagu yang akan di-cover, di-remix, di-edit, atau di-mashup | | Gambar | JPEG, PNG, WebP | 10 MB | Sebuah `mediaId` | Salah satu dari hingga 3 `images` sebuah prompt: ACE Music menulis lagu tentang gambar itu | ```bash curl -s -X POST "$API/files?title=Harbour%20Jig%20demo" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: audio/mpeg" \ --data-binary @harbour-jig-demo.mp3 | jq '{songId, status, duration, bpm: .upload.bpm}' ``` Upload "Harbour Jig" 90 detik kami ditranskripsikan dalam 14 detik, dan ACE Music mendengar 115 bpm (kami meminta 116). Gambar robot yang sedang menari menjadi lagu drum and bass tentang bulu teal dan sepatu high-top oranyenya. Keduanya ada di [Contoh](#your-audio-and-pictures). Upload dihitung terhadap jatah akun: 10 menit audio di Free, 30 di Creator, dan 60 di Artist. Skrip: [`upload-reference/`](https://github.com/useapi/acemusic-api/tree/main/upload-reference). ### Stem, unduhan, dan partitur Setiap lagu yang sudah selesai bisa dipisah menjadi stem, diunduh, dan dibaca sebagai partitur: | Request | Paket | Kredit | Yang Anda dapat | |---|---|---|---| | [Stem](/docs/api-acemusic-v1/post-acemusic-music-stems), `mode: "vocals"` | Creator, Artist | 5 | MP3 `vocal` dan `instrumental` | | [Stem](/docs/api-acemusic-v1/post-acemusic-music-stems), `mode: "all"` | Creator, Artist | 60 | Semua stem yang ditemukan ACE Music, sebagai MP3 | | [Unduh](/docs/api-acemusic-v1/get-acemusic-music-download) `mp3` (default) | semua paket | 0 | `url` (sama dengan `audioUrl`) dan `playUrl` | | Unduh `wav` | Creator, Artist | 0 | Link yang berlaku 24 jam. Tidak untuk lagu ACE-Step | | Unduh `midi`, `musicxml` | Creator, Artist | 0 | File-nya langsung | | [Partitur](/docs/api-acemusic-v1/get-acemusic-music-score) | semua paket | 0, atau 1 untuk lagu ACE-Step pada pembacaan pertama | [Notasi ABC](https://abcnotation.com): melodi vokal, satu jalur instrumental, akor, dan bagian-bagian lagu | #### Pisahkan lagu menjadi stem Pemisahan vokal "Paper Lanterns" butuh sekitar 80 detik, dan pemisahan penuh kurang dari 2 menit, dengan 9 stem: vokal, vokal latar, drum, bass, gitar, keyboard, string, synth, dan fx ([dengarkan](#stems-of-paper-lanterns)). Link stem berlaku 24 jam, jadi baca lagu itu lagi untuk mendapat link baru. Memisahkan lagu yang sama lagi dengan mode yang sama langsung dijawab dan tidak dikenai biaya. #### Unduh MP3, WAV, MIDI, dan MusicXML ACE Music membuat WAV, MIDI, dan MusicXML pada request pertama: API menunggu hingga satu menit, lalu menjawab `202`, jadi panggil lagi semenit kemudian. Untuk "Paper Lanterns", ketiganya siap dalam hitungan detik: WAV 40 MB, file MIDI 8 KB, dan partitur MusicXML 107 KB. <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash SONG="user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7" curl -s -G "$API/music/download" --data-urlencode "songId=$SONG" -d format=wav \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{url, expires}' curl -s -G "$API/music/download" --data-urlencode "songId=$SONG" -d format=midi \ -H "Authorization: Bearer $USEAPI_TOKEN" -o paper-lanterns.mid ``` </details> #### Membaca partitur Tool ABC apa pun bisa mengubah partitur menjadi lembaran not. Untuk "Paper Lanterns", partiturnya menunjukkan 72 bpm, tempo yang kami minta di style. Lagu ACE Music v1.1 sudah dilengkapi partiturnya, dan cover serta mashup v1.1 mengikutinya, lihat [Cover, remix, dan edit](#covers-remixes-and-edits). <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash SONG="user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7" curl -s -G "$API/music/score" --data-urlencode "songId=$SONG" \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq -r .abc | head -14 ``` ``` X:1 T: M:2/4 L:1/16 Q:1/4=72 V: Vocal clef=treble name="Vocal Melody" snm="Vocal" V: Ins clef=treble name="Ins Melody" snm="Inst." K:Ab % intro V: Vocal Z|"Ab"z8|"Ab"z8|"Ab"z8| V: Ins Z|Ac2AcBA2|A2EAA2EA|Ac2AcBA2| ``` </details> Skrip: [`stems-and-downloads/`](https://github.com/useapi/acemusic-api/tree/main/stems-and-downloads), yang menyimpan stem, semua format unduhan, dan partitur. ### Library Anda Setiap lagu dan upload di akun, baik dibuat di sini maupun di acemusic.ai, tetap ada di Library akun itu sampai dihapus: | Request | Fungsinya | |---|---| | [GET /music](/docs/api-acemusic-v1/get-acemusic-music) | Satu halaman lagu, terbaru lebih dulu, dengan `next` untuk halaman berikutnya. `email` diperlukan jika ada lebih dari satu akun. Lagu dari job yang lebih tua dari 7 hari ada di sini | | [GET /music/`songId`](/docs/api-acemusic-v1/get-acemusic-music-songid) | Satu lagu dengan link baru, beserta stem-nya jika lagu itu sudah dipisah | | [DELETE /music/`songId`](/docs/api-acemusic-v1/delete-acemusic-music-songid) | `204`: lagu dipindahkan ke tempat sampah akun di acemusic.ai, dan sejak itu API menjawab `404` untuk lagu tersebut | <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash SONG="user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7" curl -s -G "$API/music" --data-urlencode "email=example@example.com" -d limit=20 \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{next, songs: [.songs[] | {title, model, kind, songId}]}' curl -s "$API/music/$(jq -rn --arg v "$SONG" '$v|@uri')" \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{title, score, audioUrl, playUrl, stems: (.stems // {} | keys)}' curl -s -o /dev/null -w "%{http_code}\n" -X DELETE "$API/music/$(jq -rn --arg v "$SONG" '$v|@uri')" \ -H "Authorization: Bearer $USEAPI_TOKEN" ``` </details> Skrip: [`library/`](https://github.com/useapi/acemusic-api/tree/main/library). ### Beberapa akun ACE Music Setiap langganan useapi.net menghubungkan 3 akun ACE Music, hingga total 100 akun. Request tanpa `email` dikirim ke akun yang sehat dengan slot kosong, dan request yang menyebut lagu, upload, atau gambar berjalan di akun tempat item itu berada. Satu akun menjalankan hingga `maxJobs` request sekaligus, 4 secara default, sesuai batas ACE Music sendiri. Satu langganan $15 menjalankan hingga 12 request lagu sekaligus (3 akun × 4 per akun), dan setiap request menghasilkan dua lagu, jadi 24 lagu dibuat secara paralel, di ACE Music v1 atau di ACE-Step v1.5 XL, yang tidak memakai kredit. Jika semua akun sibuk, API menjawab `429` dengan `Retry-After`, dan password yang ditolak ACE Music membuat akun itu menjawab `596` sampai Anda menambahkannya lagi. [GET /accounts/`email`](/docs/api-acemusic-v1/get-acemusic-accounts-email) membaca paket, kredit, dan biaya kredit secara langsung, dan [POST /accounts](/docs/api-acemusic-v1/post-acemusic-accounts) yang hanya berisi `email` dan `maxJobs` hanya mengubah `maxJobs`. Skrip: [`accounts/`](https://github.com/useapi/acemusic-api/tree/main/accounts). <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash curl -s "$API/accounts/$(jq -rn --arg v "example@example.com" '$v|@uri')" \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{plan_name, credits, maxJobs, costs}' curl -s -X POST "$API/accounts" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "example@example.com", "maxJobs": 2 }' ``` </details> ### Pakai dari Claude, ChatGPT, atau Cursor (MCP) Fitur yang sama tersedia sebagai [MCP server](/docs/api-acemusic-v1/mcp) ter-hosting dengan 15 tool, dari lagu, cover, dan mashup hingga stem, partitur, dan upload. Di Claude Code, cukup satu perintah: ```bash claude mcp add --transport http useapi-acemusic https://api.useapi.net/v1/acemusic/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` Cursor, VS Code, dan Windsurf memakai URL dan header yang sama, sementara aplikasi Claude dan ChatGPT login dengan OAuth, lihat [Memakainya di aplikasi Claude atau ChatGPT](/docs/api-acemusic-v1/mcp#use-it-in-the-claude-app-or-chatgpt). Lalu minta dengan bahasa sehari-hari: "Write lyrics about a cat who loves rainy days and sing them as acoustic indie folk on ACE Music v1". #### useapi.net vs MCP server milik ACE Music sendiri ACE Music también tiene su propio servidor MCP en `https://acemusic.ai/mcp`. Crea canciones de ACE Music v1 y v1.1 a partir del estilo y la letra que escribe tu asistente. El servidor de useapi.net funciona con la misma cuenta de ACE Music y agrega todo lo demás (al 18 de noviembre de 2026): | | MCP de ACE Music de useapi.net | MCP propio de ACE Music | |---|---|---| | ACE-Step v1.5 XL, 0 créditos en todos los planes | Sí | No, solo ACE Music v1 y v1.1 | | Descarga de MP3 en el plan Free | Sí | No, toda descarga requiere un plan de pago | | Covers, remixes, ediciones y mashups | Una llamada para cada uno, a partir de tus canciones | El asistente los arma a partir de una partitura transcrita | | Stems: voz e instrumental, o cada instrumento | Sí | No | | Partituras MusicXML | Sí | No, solo MIDI | | Estilo, letra y título escritos por ACE Music a partir de una idea de una línea | Sí | No, los escribe el asistente | | Varias cuentas de ACE Music en una sola conexión | Sí | Una cuenta por conexión | | Token de API para scripts, n8n y agentes sin interfaz, además de OAuth | Sí | Solo inicio de sesión con OAuth | | Las mismas llamadas por REST, con jobs y webhooks | Sí | No | useapi.net es un servicio de terceros, sin afiliación con ACE Music. ACE Music juga punya MCP server sendiri di `https://acemusic.ai/mcp`. Server itu membuat lagu ACE Music v1 dan v1.1 dari gaya dan lirik yang ditulis asisten Anda. Server useapi.net bekerja di akun ACE Music yang sama dan menambahkan sisanya (per 18 November 2026): | | MCP ACE Music dari useapi.net | MCP milik ACE Music sendiri | |---|---|---| | ACE-Step v1.5 XL, 0 kredit di semua paket | Ya | Tidak, hanya ACE Music v1 dan v1.1 | | Download MP3 di paket Free | Ya | Tidak, setiap download butuh paket berbayar | | Cover, remix, edit, dan mashup | Masing-masing satu panggilan, dari lagu Anda | Dirangkai oleh asisten dari partitur hasil transkripsi | | Stem: vokal dan instrumental, atau setiap instrumen | Ya | Tidak | | Partitur MusicXML | Ya | Tidak, hanya MIDI | | Gaya, lirik, dan judul ditulis ACE Music dari ide satu baris | Ya | Tidak, asisten yang menulisnya | | Beberapa akun ACE Music dalam satu koneksi | Ya | Satu akun per koneksi | | Token API untuk skrip, n8n, dan agen headless, plus OAuth | Ya | Hanya login OAuth | | Panggilan yang sama lewat REST, dengan job dan webhook | Ya | Tidak | useapi.net adalah layanan pihak ketiga dan tidak berafiliasi dengan ACE Music. ACE Music も独自の MCP サーバーを `https://acemusic.ai/mcp` で提供しています。こちらは、アシスタントが書いたスタイルと歌詞から ACE Music v1 と v1.1 の曲を作ります。useapi.net のサーバーは同じ ACE Music アカウントで動き、それ以外のすべてを補います(2026年11月18日時点)。 | | useapi.net の ACE Music MCP | ACE Music 独自の MCP | |---|---|---| | ACE-Step v1.5 XL、どのプランでも0クレジット | 対応 | 非対応、ACE Music v1 と v1.1 のみ | | Free プランでの MP3 ダウンロード | 対応 | 非対応、ダウンロードにはすべて有料プランが必要 | | カバー、リミックス、編集、マッシュアップ | お手持ちの曲から、それぞれ1回の呼び出しで | 書き起こした楽譜をもとにアシスタントが組み立てる | | ステム:ボーカルとインスト、または楽器ごと | 対応 | 非対応 | | MusicXML の楽譜 | 対応 | 非対応、MIDI のみ | | 1行のアイデアから ACE Music がスタイル、歌詞、タイトルを書く | 対応 | 非対応、アシスタントが書く | | 1つの接続で複数の ACE Music アカウント | 対応 | 1接続につき1アカウント | | スクリプト、n8n、ヘッドレスエージェント向けの API トークンと OAuth | 対応 | OAuth サインインのみ | | 同じ呼び出しを REST で、ジョブと Webhook 付きで | 対応 | 非対応 | useapi.net はサードパーティのサービスで、ACE Music とは提携していません。 O ACE Music também tem o próprio servidor MCP em `https://acemusic.ai/mcp`. Ele gera músicas do ACE Music v1 e v1.1 a partir do estilo e da letra que o seu assistente escreve. O servidor da useapi.net funciona na mesma conta do ACE Music e acrescenta todo o resto (em 18 de novembro de 2026): | | MCP do ACE Music da useapi.net | MCP do próprio ACE Music | |---|---|---| | ACE-Step v1.5 XL, 0 créditos em todos os planos | Sim | Não, só ACE Music v1 e v1.1 | | Download de MP3 no plano Free | Sim | Não, todo download exige um plano pago | | Covers, remixes, edições e mashups | Uma chamada para cada, a partir das suas músicas | Montados pelo assistente a partir de uma partitura transcrita | | Stems: vocal e instrumental, ou cada instrumento | Sim | Não | | Partituras MusicXML | Sim | Não, só MIDI | | Estilo, letra e título escritos pelo ACE Music a partir de uma ideia de uma linha | Sim | Não, o assistente escreve | | Várias contas do ACE Music em uma só conexão | Sim | Uma conta por conexão | | Token de API para scripts, n8n e agentes headless, além de OAuth | Sim | Só login com OAuth | | As mesmas chamadas via REST, com jobs e webhooks | Sim | Não | A useapi.net é um serviço de terceiros, sem afiliação com o ACE Music. ACE Music มี MCP server ของตัวเองด้วยที่ `https://acemusic.ai/mcp` ซึ่งสร้างเพลง ACE Music v1 และ v1.1 จากสไตล์และเนื้อเพลงที่ผู้ช่วย AI ของคุณเขียน ส่วน server ของ useapi.net ทำงานบนบัญชี ACE Music เดียวกันและเพิ่มส่วนที่เหลือทั้งหมด (ข้อมูล ณ วันที่ 18 พฤศจิกายน 2026): | | ACE Music MCP ของ useapi.net | MCP ของ ACE Music เอง | |---|---|---| | ACE-Step v1.5 XL ใช้ 0 เครดิตในทุกแพ็กเกจ | ได้ | ไม่ได้ มีแค่ ACE Music v1 และ v1.1 | | ดาวน์โหลด MP3 ในแพ็กเกจ Free | ได้ | ไม่ได้ ทุกการดาวน์โหลดต้องใช้แพ็กเกจเสียเงิน | | คัฟเวอร์ รีมิกซ์ การแก้ไข และแมชอัป | เรียกครั้งเดียวต่ออย่าง จากเพลงของคุณ | ผู้ช่วย AI ประกอบเองจากโน้ตเพลงที่ถอดออกมา | | สเต็ม: เสียงร้องกับดนตรี หรือแยกทุกเครื่องดนตรี | ได้ | ไม่ได้ | | โน้ตเพลง MusicXML | ได้ | ไม่ได้ มีแค่ MIDI | | ACE Music เขียนสไตล์ เนื้อเพลง และชื่อเพลงจากไอเดียบรรทัดเดียว | ได้ | ไม่ได้ ผู้ช่วย AI ต้องเขียนเอง | | หลายบัญชี ACE Music ในการเชื่อมต่อเดียว | ได้ | หนึ่งบัญชีต่อการเชื่อมต่อ | | API token สำหรับสคริปต์ n8n และเอเจนต์ที่ไม่มีหน้าจอ พร้อม OAuth | ได้ | ล็อกอินด้วย OAuth เท่านั้น | | เรียกแบบเดียวกันผ่าน REST พร้อมงานและ webhook | ได้ | ไม่ได้ | useapi.net เป็นบริการของบุคคลที่สาม ไม่มีส่วนเกี่ยวข้องกับ ACE Music ACE Music cũng có MCP server riêng tại `https://acemusic.ai/mcp`. Server này tạo bài hát ACE Music v1 và v1.1 từ phong cách và lời bài hát do trợ lý của bạn viết. Server của useapi.net chạy trên cùng tài khoản ACE Music và bổ sung phần còn lại (tính đến 18 tháng 11 năm 2026): | | MCP ACE Music của useapi.net | MCP riêng của ACE Music | |---|---|---| | ACE-Step v1.5 XL, 0 credit trên mọi gói | Có | Không, chỉ ACE Music v1 và v1.1 | | Tải MP3 trên gói Free | Có | Không, mọi lượt tải đều cần gói trả phí | | Cover, remix, chỉnh sửa và mashup | Mỗi thứ một lệnh gọi, từ bài hát của bạn | Trợ lý tự ghép lại từ bản nhạc được chép ra | | Stem: giọng hát và nhạc nền, hoặc từng nhạc cụ | Có | Không | | Bản nhạc MusicXML | Có | Không, chỉ MIDI | | Phong cách, lời và tên bài do ACE Music viết từ một ý tưởng một dòng | Có | Không, trợ lý tự viết | | Nhiều tài khoản ACE Music trong một kết nối | Có | Một tài khoản cho mỗi kết nối | | API token cho script, n8n và agent chạy không giao diện, cùng với OAuth | Có | Chỉ đăng nhập OAuth | | Cùng các lệnh gọi qua REST, có job và webhook | Có | Không | useapi.net là dịch vụ của bên thứ ba, không liên kết với ACE Music. ACE Music 也在 `https://acemusic.ai/mcp` 运行自己的 MCP 服务器。它根据你的助手写好的风格和歌词生成 ACE Music v1 和 v1.1 歌曲。useapi.net 的服务器使用同一个 ACE Music 账号,并补上其余的一切(截至 2026 年 11 月 18 日): | | useapi.net ACE Music MCP | ACE Music 自己的 MCP | |---|---|---| | ACE-Step v1.5 XL,所有套餐都是 0 积分 | 支持 | 不支持,只有 ACE Music v1 和 v1.1 | | 免费套餐下载 MP3 | 支持 | 不支持,任何下载都需要付费套餐 | | 翻唱、重混、编辑和混搭 | 基于你的歌曲,各一次调用 | 由助手根据转写出的乐谱拼凑完成 | | 分轨:人声和伴奏,或每件乐器 | 支持 | 不支持 | | MusicXML 乐谱 | 支持 | 不支持,只有 MIDI | | 由 ACE Music 根据一句话的想法写出风格、歌词和标题 | 支持 | 不支持,由助手来写 | | 一个连接中使用多个 ACE Music 账号 | 支持 | 每个连接一个账号 | | 用于脚本、n8n 和无界面智能体的 API Token,另有 OAuth | 支持 | 只能 OAuth 登录 | | 通过 REST 进行同样的调用,带任务和 webhook | 支持 | 不支持 | useapi.net 是第三方服务,与 ACE Music 无关联。 ACE Music also runs its own MCP server at `https://acemusic.ai/mcp`. It makes ACE Music v1 and v1.1 songs from the style and lyrics your assistant writes. The useapi.net server works on the same ACE Music account and adds the rest (as of November 18, 2026): | | useapi.net ACE Music MCP | ACE Music's own MCP | |---|---|---| | ACE-Step v1.5 XL, 0 credits on every plan | Yes | No, ACE Music v1 and v1.1 only | | MP3 download on the Free plan | Yes | No, every download needs a paid plan | | Covers, remixes, edits and mashups | One call each, from your songs | Pieced together by the assistant from a transcribed score | | Stems: vocals and instrumental, or every instrument | Yes | No | | MusicXML scores | Yes | No, MIDI only | | Style, lyrics and title written by ACE Music from a one-line idea | Yes | No, the assistant writes them | | Several ACE Music accounts in one connection | Yes | One account per connection | | API token for scripts, n8n and headless agents, plus OAuth | Yes | OAuth sign-in only | | The same calls over REST, with jobs and webhooks | Yes | No | useapi.net is a third-party service, not affiliated with ACE Music. ### Generate batch dengan skrip [Repo GitHub `acemusic-api`](https://github.com/useapi/acemusic-api) berisi satu contoh per fitur, yang ditautkan dari setiap bagian di atas: satu skrip Node.js dan kembarannya dalam Python, tanpa perlu menginstal apa pun. Setiap skrip membaca request dari `prompts.json` yang Anda edit, menjalankan hingga 4 request sekaligus, melakukan polling job, lalu menyimpan kedua lagu, cover art-nya, catatan job, dan `ledger.jsonl` berisi kredit yang terpakai di folder `output/`-nya. Anda butuh [Node.js](https://nodejs.org) 21 atau lebih baru, atau [Python](https://www.python.org) 3.8 atau lebih baru. `--only 3` menjalankan prompt ketiga di bawah, sebuah lagu ACE-Step tanpa kredit, jadi bisa dipakai di akun Free: ```bash git clone https://github.com/useapi/acemusic-api.git && cd acemusic-api export USEAPI_TOKEN="user:12345-..." node songs-from-prompt/songs-from-prompt.mjs --only 3 ``` Setiap catatan job yang disimpan berisi `songId` lagu-lagunya, dan `--from <job>.json --pick 1` menyerahkan lagu 1 ke skrip berikutnya untuk di-cover, di-mashup, atau dipisah menjadi stem. <details markdown="block"> <summary>Buka `songs-from-prompt/prompts.json`</summary> ```json [ { "_about": "ACE Music v1 (the default model, 4 credits for two songs): ACE Music writes the style, lyrics and title from your idea", "prompt": "A late-night neo-soul slow jam about two strangers sharing an umbrella at a bus stop in the rain and missing the last bus on purpose. Warm Rhodes piano, brushed drums, round upright bass, a smoky female lead with close three-part harmonies on the chorus.", "model": "acemusic-v1" }, { "_about": "ACE Music v1.1 Preview (4 credits): writes a score first, then the audio", "prompt": "An anthemic Celtic folk-rock singalong about a fishing crew racing a storm back to the harbor. Fiddle and tin whistle hooks, stomping kick drum, bodhran, a gravelly male lead and the whole crew shouting the chorus.", "model": "acemusic-v1.1" }, { "_about": "ACE-Step v1.5 XL (no credits on any ACE Music plan, the Free plan included)", "prompt": "A breezy bossa nova for a lazy Sunday afternoon in Lisbon: nylon-string guitar, soft brushed snare, upright bass, a gentle flute line and a warm male and female duet sung in Portuguese.", "model": "ace-step-1.5-xl" } ] ``` </details> ### Contoh Setiap lagu di bawah dibuat pada 14 November 2026 (PST) dengan skrip dari repo di akun ACE Music Artist, dan yang ditampilkan adalah lagu pertama dari dua lagu setiap request. Judul berasal dari ACE Music kecuali kami menentukannya sendiri, waktu dihitung dari request sampai kedua lagu selesai, dan panggilan API menampilkan ID rekaan. #### Lagu dari sebuah gambar Satu gambar dan satu kalimat gaya masuk, dua lagu jadi keluar. Kami meng-upload foto maskot robot yang sedang menari ini dan meminta drum and bass. ACE Music menulis liriknya dari apa yang dilihatnya: "Teal fur shaking on the concrete floor, orange high-tops squeaking by the studio door". <img src="https://media.useapi.net/blog/2026-09-07-260907/dreamina-longvideo-ref-robot-mascot.png" alt="Maskot robot berbulu teal dengan kepala kotak, antena, dan mata menyala, menari dengan sepatu high-top oranye" style="width: 100%; max-width: 220px;" loading="lazy"> ``` Bouncy, playful drum and bass for a dancing robot mascot: rolling breakbeats at 174 bpm, a wobbly reese bass, bleepy robot synth hooks, vocoder chops, cheeky and upbeat. ``` ACE Music v1 — "Bleep Boop Bounce" · 2:47 · dibuat dalam 72 detik <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/files' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: image/png' \ --data-binary @robot-mascot.png curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "Bouncy, playful drum and bass for a dancing robot mascot: rolling breakbeats at 174 bpm, a wobbly reese bass, bleepy robot synth hooks, vocoder chops, cheeky and upbeat.", "model": "acemusic-v1", "images": ["user:12345-example@example.com-media:cx_3b9e1d7a5c2f48e0a6d4b8c1"], "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-bleep-boop-bounce-drum-and-bass-from-robot-image.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lagu ini sebagai YouTube Short, dengan fotonya: [Bleep Boop Bounce di YouTube](https://youtube.com/shorts/z_aOmILvIng). #### Lagu dari prompt Lagu ACE Music v1 dari prompt, "Let the 44 Roll By", ada di [panduan langkah demi langkah](#what-you-get-back). Berikut dua prompt lagi, di dua model lainnya: ``` An anthemic Celtic folk-rock singalong about a fishing crew racing a storm back to the harbor. Fiddle and tin whistle hooks, stomping kick drum, bodhran, a gravelly male lead and the whole crew shouting the chorus. ``` ACE Music v1.1 Preview — "Haul for the Harbor Light" · 2:51 · dibuat dalam 43 detik <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "An anthemic Celtic folk-rock singalong about a fishing crew racing a storm back to the harbor. Fiddle and tin whistle hooks, stomping kick drum, bodhran, a gravelly male lead and the whole crew shouting the chorus.", "model": "acemusic-v1.1", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-1-haul-for-the-harbor-light-celtic-folk-rock-from-prompt.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ``` A breezy bossa nova for a lazy Sunday afternoon in Lisbon: nylon-string guitar, soft brushed snare, upright bass, a gentle flute line and a warm male and female duet sung in Portuguese. ``` ACE-Step v1.5 XL, tanpa kredit — "Domingo em Alfama" · 3:28 <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "A breezy bossa nova for a lazy Sunday afternoon in Lisbon: nylon-string guitar, soft brushed snare, upright bass, a gentle flute line and a warm male and female duet sung in Portuguese.", "model": "ace-step-1.5-xl", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-domingo-em-alfama-bossa-nova-from-prompt.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### Lirik Anda sendiri Dua verse, satu pre-chorus, satu bridge, dan satu outro buatan kami sendiri, dengan durasi yang diminta 210 detik: ``` Style: cinematic indie pop ballad, felt piano, swelling strings, deep heartbeat kick, intimate female vocal that opens up into a soaring chorus, 72 bpm Lyrics: [Verse 1] We wrote our names on paper lanterns / Down by the river in July … [Chorus] Light it up and let it go / Every word I never said out loud … ``` ACE Music v1 — "Paper Lanterns" · 3:29 · dibuat dalam 61 detik <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "title": "Paper Lanterns", "style": "cinematic indie pop ballad, felt piano, swelling strings, deep heartbeat kick, intimate female vocal that opens up into a soaring chorus, 72 bpm", "lyrics": "[Verse 1]\nWe wrote our names on paper lanterns\nDown by the river in July\nYou said the wind would know the answer\nIf we just let the fire fly\nYour hand was shaking, mine was steady\nAt least that'\''s how I tell it now\nWe watched them climb until the city\nWas just a glow beneath the clouds\n\n[Pre-Chorus]\nSo every summer I come back here\nStrike a match and hold it near\n\n[Chorus]\nLight it up and let it go\nEvery word I never said out loud\nLight it up and let it go\nHigher than the both of us somehow\nAnd if it finds you anyhow\nTell me you can see it from the clouds\n\n[Verse 2]\nThey tore the old pier down last winter\nPut up a fence and painted lines\nBut I still know the way by heartbeat\nI find the water every time\nI keep a lighter in my pocket\nI keep your laugh inside my head\nI fold the paper like you showed me\nAnd write the things I should have said\n\n[Pre-Chorus]\nSo every summer I come back here\nStrike a match and hold it near\n\n[Chorus]\nLight it up and let it go\nEvery word I never said out loud\nLight it up and let it go\nHigher than the both of us somehow\nAnd if it finds you anyhow\nTell me you can see it from the clouds\n\n[Bridge]\nPaper and fire, paper and fire\nNothing this light should rise so high\nPaper and fire, paper and fire\nMaybe that'\''s how we say goodbye\n\n[Final Chorus]\nLight it up and let it go\nEvery word I never said out loud\nLight it up and let it go\nHigher than the both of us somehow\n\n[Outro]\nDown by the river in July", "model": "acemusic-v1", "duration": 210, "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-paper-lanterns-custom-lyrics.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Sebuah instrumental: `instrumental: true`, 150 detik, tanpa vokal, paduan suara, maupun gitar akustik: ``` Style: cinematic synthwave instrumental for a night drive: pulsing analog bass arpeggio, gated reverb drums, lush pads, a soaring lead synth melody, builds to a big final section, 108 bpm ``` ACE Music v1 — "Neon Overpass" · 2:29 · dibuat dalam 46 detik <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "title": "Neon Overpass", "style": "cinematic synthwave instrumental for a night drive: pulsing analog bass arpeggio, gated reverb drums, lush pads, a soaring lead synth melody, builds to a big final section, 108 bpm", "instrumental": true, "model": "acemusic-v1", "duration": 150, "negative": "vocals, choir, acoustic guitar", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-neon-overpass-synthwave-instrumental.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lirik berbahasa Spanyol tentang pesta di atap rumah saat listrik padam: ``` Style: modern cumbia pop, bright accordion hooks, güira and congas, warm bass, a festive male lead with a crowd shouting the chorus, 98 bpm Lyrics: [Chorus] Bailando en la azotea / Con las estrellas de farol … ``` ACE Music v1 — "Bailando en la Azotea" · 2:32 · dibuat dalam 46 detik <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "title": "Bailando en la Azotea", "style": "modern cumbia pop, bright accordion hooks, güira and congas, warm bass, a festive male lead with a crowd shouting the chorus, 98 bpm", "lyrics": "[Verse 1]\nSe fue la luz en todo el barrio\nY nadie quiere irse a dormir\nDoña Rosa saca el radio viejo\nY la noche empieza a sonreír\nLos vecinos suben con sus sillas\nAlguien trae limones y café\nY la ciudad allá abajo, oscura\nNos mira bailar sin saber por qué\n\n[Pre-Chorus]\nSube, sube, que la luna está invitando\nSube, sube, que la calle está cantando\n\n[Chorus]\nBailando en la azotea\nCon las estrellas de farol\nQue se entere todo el mundo\nQue esta noche no hay apagón\nBailando en la azotea\nCon el corazón de tambor\nSi se apaga la ciudad entera\nAquí arriba sobra amor\n\n[Verse 2]\nEl abuelo saca la guitarra\nLa vecina de enfrente se animó\nLos niños corren entre las sábanas\nQue el viento de la tarde colgó\nNadie sabe cuándo vuelve la corriente\nY la verdad, a nadie le importó\nEsta fiesta no la paga nadie\nEsta fiesta la invitó el apagón\n\n[Chorus]\nBailando en la azotea\nCon las estrellas de farol\nQue se entere todo el mundo\nQue esta noche no hay apagón\nBailando en la azotea\nCon el corazón de tambor\nSi se apaga la ciudad entera\nAquí arriba sobra amor\n\n[Outro]\nQue esta noche no hay apagón", "model": "acemusic-v1", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-bailando-en-la-azotea-spanish-cumbia.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lirik dari penulis lirik, gaya dari penulis gaya, dinyanyikan oleh ACE-Step: ``` Lyrics writer: A wistful country song about an old pickup truck that still has her mixtape stuck in the tape deck Style writer: classic country ballad, pedal steel, warm baritone ``` ACE-Step v1.5 XL, tanpa kredit — "Side B Forever" · 3:35 · dibuat dalam 40 detik, setelah 6 detik untuk lirik dan 4 detik untuk gaya <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music/lyrics' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "A wistful country song about an old pickup truck that still has her mixtape stuck in the tape deck", "style": "classic country ballad, pedal steel, warm baritone", "model": "ace-step-1.5-xl" }' > lyrics.json curl -X POST 'https://api.useapi.net/v1/acemusic/music/style' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "style": "classic country ballad, pedal steel, warm baritone", "model": "ace-step-1.5-xl" }' > style.json # sing what the writers returned jq -n --slurpfile l lyrics.json --slurpfile s style.json \ '{title: $l[0].title, lyrics: $l[0].lyrics, style: $s[0].style, model: "ace-step-1.5-xl", async: true}' | curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d @- ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-side-b-forever-lyrics-and-style-writers.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### ACE-Step dengan tempo, kunci nada, dan birama tertentu Setiap lagu kembali persis sepanjang yang diminta. ``` 3/4 · 84 bpm · D minor · 120 s · thinking 60 · avoid: trap drums, EDM, autotune Style: dark cabaret waltz, accordion, pizzicato strings, upright bass, brushed snare, theatrical female vocal ``` ACE-Step v1.5 XL, tanpa kredit — "Midnight Waltz" · 2:00 · dibuat dalam 31 detik <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "model": "ace-step-1.5-xl", "title": "Midnight Waltz", "style": "dark cabaret waltz, accordion, pizzicato strings, upright bass, brushed snare, theatrical female vocal", "lyrics": "[Verse 1]\nThe band plays slow when the lights go low\nAnd the chandeliers begin to sway\nTake my hand, we will dance till the candles stand\nIn puddles of yesterday\n\n[Chorus]\nOne, two, three, turn around with me\nRound and round till the morning comes\nOne, two, three, oh don'\''t let me be\nThe last one dancing when the music'\''s done\n\n[Verse 2]\nThe clock strikes twelve and it laughs at itself\nEvery mirror wears a stranger'\''s face\nHold me close, we are only ghosts\nWho forgot to leave this place\n\n[Chorus]\nOne, two, three, turn around with me\nRound and round till the morning comes\nOne, two, three, oh don'\''t let me be\nThe last one dancing when the music'\''s done", "bpm": 84, "timeSignature": "3/4", "key": "D minor", "duration": 120, "negative": "trap drums, EDM, autotune", "thinking": 60, "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-midnight-waltz-3-4-84-bpm-d-minor.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ``` 6/8 · 116 bpm · G major · 90 s · instrumental Style: lively celtic instrumental jig, fiddle and tin whistle trading the melody, bodhran, strummed bouzouki, foot stomps ``` ACE-Step v1.5 XL, tanpa kredit — "Harbour Jig" · 1:30 · dibuat dalam 20 detik <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "model": "ace-step-1.5-xl", "title": "Harbour Jig", "style": "lively celtic instrumental jig, fiddle and tin whistle trading the melody, bodhran, strummed bouzouki, foot stomps", "instrumental": true, "bpm": 116, "timeSignature": "6/8", "key": "G major", "duration": 90, "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-harbour-jig-6-8-116-bpm-g-major.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ``` 4/4 · 174 bpm · F minor · 150 s · thinking 80 Style: liquid drum and bass, rolling breakbeats, deep warm sub bass, airy pads, soulful female vocal ``` ACE-Step v1.5 XL, tanpa kredit — "Almost Home" · 2:30 · dibuat dalam 41 detik <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "model": "ace-step-1.5-xl", "title": "Almost Home", "style": "liquid drum and bass, rolling breakbeats, deep warm sub bass, airy pads, soulful female vocal", "lyrics": "[Verse]\nCity lights in the rear view mirror\nRunning on a borrowed night\nEvery bridge is a little bit nearer\nEvery tunnel full of light\n\n[Chorus]\nHold on, we'\''re almost home\nEvery signal turning green\nHold on, you'\''re not alone\nFaster than the in-between\n\n[Verse]\nRadio low and the windows open\nBreathing in the summer rain\nEvery promise we left unspoken\nRushing back to us again\n\n[Chorus]\nHold on, we'\''re almost home\nEvery signal turning green\nHold on, you'\''re not alone\nFaster than the in-between", "bpm": 174, "timeSignature": "4/4", "key": "F minor", "duration": 150, "thinking": 80, "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-almost-home-drum-and-bass-174-bpm-f-minor.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### Satu cover, satu remix, dan satu edit "Paper Lanterns" sebagai cover, dalam gaya baru yang tetap mempertahankan melodinya: ``` mode: cover · stripped-back acoustic folk cover, fingerpicked steel-string guitar, warm cello, soft close-mic'd male vocal ``` ACE Music v1.1 Preview — "Paper Lanterns (Acoustic Folk Cover)" · 3:34 · dibuat dalam 72 detik <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash # our script read the score first (free for an ACE Music v1 song; the API now does this by itself) curl 'https://api.useapi.net/v1/acemusic/music/score?songId=user%3A12345-example%40example.com-song%3Aso_4e7b2c9d0a5f4183b6d8e2c7' \ -H 'Authorization: Bearer user:12345-…' > /dev/null curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "mode": "cover", "model": "acemusic-v1.1", "references": ["user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7"], "style": "stripped-back acoustic folk cover, fingerpicked steel-string guitar, warm cello, soft close-mic'\''d male vocal", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-1-paper-lanterns-acoustic-folk-cover.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> "Bailando en la Azotea" sebagai deep house. Kami tidak mengirim judul, jadi ACE Music menamainya "Reference 1": ``` mode: remix · coverStrength 40 · remixStrength 50 · deep house remix, four-on-the-floor kick, plucky chords, rolling bassline, filtered vocal chops ``` ACE-Step v1.5 XL, tanpa kredit — "Reference 1" · 2:32 · dibuat dalam 31 detik <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "mode": "remix", "model": "ace-step-1.5-xl", "references": ["user:12345-example@example.com-song:so_9d3b7e2c1a6f4085b8e4d1c6"], "style": "deep house remix, four-on-the-floor kick, plucky chords, rolling bassline, filtered vocal chops", "coverStrength": 40, "remixStrength": 50, "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-bailando-en-la-azotea-house-remix.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> "Paper Lanterns" dengan lirik baru untuk detik 30 sampai 50, sisanya tetap: ``` mode: edit · start 30 · end 50 Lyrics: We wrote our names on paper lanterns / Down by the harbor in the snow / You said the stars would keep the answer / If we were brave enough to go ``` ACE-Step v1.5 XL, tanpa kredit — "Reference 1" · 3:29 · dibuat dalam 41 detik <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "mode": "edit", "model": "ace-step-1.5-xl", "references": ["user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7"], "start": 30, "end": 50, "style": "cinematic indie pop ballad, felt piano, swelling strings, intimate female vocal", "lyrics": "We wrote our names on paper lanterns\nDown by the harbor in the snow\nYou said the stars would keep the answer\nIf we were brave enough to go", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-paper-lanterns-edit-seconds-30-50.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### Mashup "Paper Lanterns" dan "Let the 44 Roll By": ``` upbeat neo-soul pop mashup, punchy live drums, warm Rhodes and strings, female lead with a gospel-tinged choir on the chorus · audioInfluence 60 ``` ACE Music v1.1 Preview — "Lanterns at the Bus Stop" · 3:58 · dibuat dalam 83 detik <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash # our script read each song's score first (the API now does this by itself for ACE Music v1 songs) curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "mode": "mashup", "model": "acemusic-v1.1", "references": ["user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7", "user:12345-example@example.com-song:so_7c1d9e3a5b2f4806a4e1c9d3"], "title": "Lanterns at the Bus Stop", "style": "upbeat neo-soul pop mashup, punchy live drums, warm Rhodes and strings, female lead with a gospel-tinged choir on the chorus", "audioInfluence": 60, "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-1-mashup-lanterns-at-the-bus-stop.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> "Haul for the Harbor Light" dan "Bailando en la Azotea", diminta di ACE Music v1: ``` festive celtic cumbia mashup, fiddle and accordion trading hooks, congas and bodhran, stomping kick, male lead with a big crowd chorus ``` ACE Music v1.1 Preview (diminta: v1) — "Harbor Fiesta" · 2:38 · dibuat dalam 74 detik <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash # our script read each song's score first (the API now does this by itself for ACE Music v1 songs) curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "mode": "mashup", "model": "acemusic-v1", "references": ["user:12345-example@example.com-song:so_2a8f6c1e9d4b47f3b0c5e8a2", "user:12345-example@example.com-song:so_9d3b7e2c1a6f4085b8e4d1c6"], "title": "Harbor Fiesta", "style": "festive celtic cumbia mashup, fiddle and accordion trading hooks, congas and bodhran, stomping kick, male lead with a big crowd chorus", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-1-mashup-harbor-fiesta-asked-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Tiga lagu sekaligus: "Paper Lanterns", "Bailando en la Azotea", dan "Let the 44 Roll By": ``` warm late-night soul-pop medley, Rhodes and strings, light latin percussion, female lead with a male answer on the last chorus ``` ACE Music v1.1 Preview — "Three Songs, One Night" · 3:32 · dibuat dalam 43 detik <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash # our script read each song's score first (the API now does this by itself for ACE Music v1 songs) curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "mode": "mashup", "model": "acemusic-v1.1", "references": ["user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7", "user:12345-example@example.com-song:so_9d3b7e2c1a6f4085b8e4d1c6", "user:12345-example@example.com-song:so_7c1d9e3a5b2f4806a4e1c9d3"], "title": "Three Songs, One Night", "style": "warm late-night soul-pop medley, Rhodes and strings, light latin percussion, female lead with a male answer on the last chorus", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-1-mashup-three-songs-one-night.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### Audio dan gambar Anda "Harbour Jig" di atas, di-upload sebagai MP3 dan dipakai sebagai referensi sebuah prompt. ACE Music menjalankannya di v1.1 agar nadanya tetap terjaga: ``` A rowdy pub singalong with a big shouted chorus about the last ferry home, built on the tune of this recording ``` ACE Music v1.1 Preview (diminta: v1) — "Last Ferry Home" · 1:36 · dibuat dalam 52 detik <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/files?title=Harbour%20Jig%20demo' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: audio/mpeg' \ --data-binary @harbour-jig-demo.mp3 curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "A rowdy pub singalong with a big shouted chorus about the last ferry home, built on the tune of this recording", "model": "acemusic-v1", "references": ["user:12345-example@example.com-song:so_5f1a3c8e7b2d49a6c3e0f7b9"], "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-1-last-ferry-home-from-uploaded-jig.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### Stem "Paper Lanterns" Vokal dan instrumental dari `mode: "vocals"` (5 kredit), lalu drum dan string dari 9 stem hasil `mode: "all"` (60 kredit). <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music/stems' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "songId": "user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7", "mode": "vocals", "async": true }' curl -X POST 'https://api.useapi.net/v1/acemusic/music/stems' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "songId": "user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7", "mode": "all", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-paper-lanterns-stem-vocal.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-paper-lanterns-stem-instrumental.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-paper-lanterns-stem-drums.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-paper-lanterns-stem-strings.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ### Pertanyaan **Apakah ada API ACE Music?** Lewat useapi.net, ada: [ACE Music API](/docs/api-acemusic-v1) menjalankan ACE Music v1, ACE Music v1.1 Preview, dan ACE-Step v1.5 XL lewat REST di akun ACE Music Anda, lengkap dengan cover, mashup, stem, dan MIDI. **Apakah ada API ACE-Step gratis?** Lewat useapi.net, ada: satu lagu ACE-Step v1.5 XL tidak memakai kredit di paket ACE Music mana pun, termasuk paket Free, lengkap dengan pengaturan tempo, kunci nada, birama, dan durasi, serta remix dan edit. acestep.io, layanan pihak ketiga, hanya menyediakan API ACE-Step-nya di paket Studio seharga $49 per bulan, sekitar $0,14 per lagu (per November 2026). **Berapa biaya satu lagu ACE Music v1 lewat API?** Lewat useapi.net, satu lagu ACE Music v1 memakai 2 kredit dari paket ACE Music Anda: $0,013 di Artist yang ditagih tahunan dan $0,023 di Artist bulanan, tanpa biaya tambahan per lagu. Lihat [Harga](#pricing). **Apakah ada MCP server ACE Music?** Lewat useapi.net, ada, dan kemampuannya lebih banyak daripada server milik ACE Music sendiri di `acemusic.ai/mcp`: [MCP server ACE Music](/docs/api-acemusic-v1/mcp) ter-hosting menambahkan model gratis ACE-Step v1.5 XL, download MP3 di paket Free, stem, cover, remix, edit, dan mashup dengan satu panggilan, MusicXML, serta beberapa akun di balik satu token API. Server milik ACE Music sendiri membuat lagu v1 dan v1.1 dari lirik yang ditulis asisten Anda, dan setiap download butuh paket berbayar. Lihat [perbandingannya](#useapinet-vs-ace-musics-own-mcp-server). ### Kesimpulan Satu POST membuat dua lagu dengan model yang memuncaki papan peringkat vokal, lagu ACE-Step tidak dikenai biaya, dan setiap lagu bisa langsung dijadikan cover, mashup, stem, atau file MIDI di panggilan berikutnya. Clone [repo `acemusic-api`](https://github.com/useapi/acemusic-api), jalankan `songs-from-prompt/` dengan `--only 3` di akun Free, dan lihat [POST /music](/docs/api-acemusic-v1/post-acemusic-music) untuk semua opsinya. Kunjungi <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Server Discord</a> atau <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Channel Telegram</a> kami untuk pertanyaan dan masalah dukungan. === URL: https://useapi.net/docs/articles/ace-music-api-tutorial-ja === Document URL: https://useapi.net/docs/articles/ace-music-api-tutorial-ja --- layout: default title: "ACE Music API で AI の曲を生成する方法" description: "useapi.net の ACE Music API で、ACE Music v1、v1.1、無料の ACE-Step v1.5 XL を使って曲を作る方法。プロンプト、自作の歌詞、カバー、マッシュアップ、ステム、MIDI を curl とコードで解説します。" keywords: [ACE Music API, ACE Music v1 API, ACE-Step API, ACE-Step v1.5 XL, AI song generator API, text to music API, Suno alternative, AI music API, stems API, MIDI, MusicXML, mashup, cover song AI, MCP server, curl, ACE Music API 使い方, AI 作曲 API, 音楽生成 API, AI 音楽生成, ステム分離, カバー曲, マッシュアップ, 日本語チュートリアル, Japanese tutorial] image: https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-paper-lanterns-cover-art.jpg parent: Articles nav_exclude: true lang: ja translation_key: ace-music-tutorial date: 2026-11-14 last_modified: 2026-11-18 nav_order: 302 repo: https://github.com/useapi/acemusic-api --- ## ACE Music API で AI の曲を生成する方法 {: .no_toc #how-to-generate-ai-songs-with-the-ace-music-api } 22分で読めます • 2026年11月14日 ## 目次 {: .no_toc .text-delta #table-of-contents } ### はじめに useapi.net の [ACE Music API](/docs/api-acemusic-v1) は、REST の呼び出し1回で、[ACE Music](https://acemusic.ai) の完成した曲を2曲返します。ボーカル、歌詞、タイトル、カバーアート付きで、作成にはすでにお持ちの ACE Music のサブスクリプションを使います。ACE Music v1 は [Artificial Analysis のボーカル音楽リーダーボード](https://artificialanalysis.ai/music/leaderboard/vocals)で Suno v6 を抑えて1位です。オープンソースの [ACE-Step](https://ace-step.github.io) v1.5 XL も同じ API で動き、Free プランを含むどの ACE Music のプランでもクレジットを消費しません。 このガイドでは、まず3つのモデルと1曲あたりの料金を説明し、`curl` で1曲を最初から最後まで作り、そのほかの機能を短い表でひととおり紹介します。最後の[例](#examples)は、このページのために作った18曲で、それぞれに作成したリクエストを添えています。どれも [`acemusic-api` GitHub リポジトリ](https://github.com/useapi/acemusic-api)のスクリプト(Node.js と Python)で作り、撮り直しも含めて Artist プランの117クレジットで済みました。useapi.net は[サードパーティ](/docs/legal#affiliation--third-party-services)の API で、ACE Music やその開発元の Timedomain とは提携していません。 ### モデルと API でできること どのリクエストも2曲を作り、`model` で作るモデルを選びます。 | モデル | `model` | 用途 | 設定 | 1リクエストのクレジット | 実測の所要時間 | |---|---|---|---|---|---| | ACE Music v1 | `acemusic-v1`(デフォルト) | ボーカル1位のモデル。プロンプトや自作の歌詞から、歌入りまたはインストの曲を作る | `duration` 30〜600秒、`negative`、`styleInfluence`、WAV ダウンロード | 4 | 46〜89秒 | | ACE Music v1.1 Preview | `acemusic-v1.1` | 先に楽譜を書くので、カバーやマッシュアップが原曲のメロディに沿う | `audioInfluence`、`styleInfluence` | 4 | 35〜83秒 | | ACE-Step v1.5 XL | `ace-step-1.5-xl` | ACE Studio と StepFun によるオープンソース。曲、リミックス、編集 | `bpm`、`key`、`timeSignature`、`duration` 10〜240秒、`negative`、`thinking`。MP3 のみ | 0 | 20〜55秒 | これらのモデルでできること: | できること | リクエスト | 備考 | |---|---|---| | プロンプトから曲を作る | [POST /music](/docs/api-acemusic-v1/post-acemusic-music) `prompt` | スタイル、歌詞、タイトルは ACE Music が書く | | 自作の歌詞、インスト | [POST /music](/docs/api-acemusic-v1/post-acemusic-music) `style`、`lyrics` | どの言語でも可 | | 歌詞とスタイルの作成ツール | [POST /music/lyrics](/docs/api-acemusic-v1/post-acemusic-music-lyrics)、[/music/style](/docs/api-acemusic-v1/post-acemusic-music-style) | クレジット不要 | | カバー、リミックス、編集、マッシュアップ | [POST /music](/docs/api-acemusic-v1/post-acemusic-music#modes) `mode` | アカウントのどの曲にも使える | | 手持ちの音声と画像 | [POST /files](/docs/api-acemusic-v1/post-acemusic-files) | 新しい曲の参照として使う | | ステム | [POST /music/stems](/docs/api-acemusic-v1/post-acemusic-music-stems) | Creator と Artist | | ダウンロード、楽譜 | [GET /music/download](/docs/api-acemusic-v1/get-acemusic-music-download)、[/music/score](/docs/api-acemusic-v1/get-acemusic-music-score) | MP3 と楽譜はすべてのプラン、WAV、MIDI、MusicXML は Creator と Artist | | ライブラリ、ジョブ、アカウント | [GET /music](/docs/api-acemusic-v1/get-acemusic-music)、[/jobs](/docs/api-acemusic-v1/get-acemusic-jobs)、[/accounts](/docs/api-acemusic-v1/get-acemusic-accounts-email) | アカウントの全曲、実行中のジョブ、最新のクレジット残高 | | MCP サーバー | [`/v1/acemusic/mcp`](/docs/api-acemusic-v1/mcp) | AI アシスタント向けの15ツール | ### 料金 ACE Music はリクエストごとに、お使いの ACE Music のプランから独自のクレジットを差し引きます。useapi.net が曲ごとに上乗せする料金はありません(2026年11月時点)。 | リクエスト | クレジット | |---|---| | ACE Music v1 または v1.1 で2曲 | 4 | | ステム、ボーカル + インスト | 5、有料プラン | | ステム、全パート | 60、有料プラン | | ACE-Step の曲の楽譜、初回の読み取り | 1 | | ACE-Step v1.5 XL で2曲 | 0、すべてのプラン | | 歌詞とスタイルの作成ツール、アップロード、ダウンロード | テストでは0 | [ACE Music のプラン](https://acemusic.ai/pricing/)は、1日20クレジットの Free、月額 $9.90 で1,000クレジットの Creator、月額 $29 で2,500クレジットの Artist で、年払いならそれぞれ月額 $7.90 と $16.58 です。1曲はリクエストの半分なので、2クレジットです。[API の概要](/docs/api-acemusic-v1#pricing)にも同じ表があります。 プランごとの1曲の料金です。左ほど安くなります(1リクエストで2曲作るので、1曲はリクエストのクレジットの半分です。2026年11月時点)。 | モデル | Free (1日20 cr) | Artist $16.58/月 (月2,500 cr、年払い) | Creator $7.90/月 (月1,000 cr、年払い) | Creator $9.90/月 (月1,000 cr) | Artist $29/月 (月2,500 cr) | |---|---|---|---|---|---| | ACE Music v1、v1.1 (1曲) | $0 / 2 cr (1日10曲) | $0.013 / 2 cr (月1,250曲) | $0.016 / 2 cr (月500曲) | $0.020 / 2 cr (月500曲) | $0.023 / 2 cr (月1,250曲) | | ステム (ボーカル + インスト) | 有料プラン | $0.033 / 5 cr | $0.040 / 5 cr | $0.050 / 5 cr | $0.058 / 5 cr | | ステム (全パート) | 有料プラン | $0.40 / 60 cr | $0.47 / 60 cr | $0.59 / 60 cr | $0.70 / 60 cr | | ACE-Step の楽譜 (初回の読み取り) | $0 / 1 cr | $0.007 / 1 cr | $0.008 / 1 cr | $0.010 / 1 cr | $0.012 / 1 cr | | ACE-Step v1.5 XL (1曲) | $0 / 0 cr | $0 / 0 cr | $0 / 0 cr | $0 / 0 cr | $0 / 0 cr | コードからこれらのモデルを呼び出すほかの方法との比較です。 | モデル | useapi.net | ほかの API | |---|---|---| | ACE Music v1、v1.1 Preview | Artist の年払いで1曲 $0.013 から、Free プランの1日20クレジットなら $0 | — | | ACE-Step v1.5 XL | Free プランを含むすべての ACE Music のプランで $0 | サードパーティの [acestep.io](https://acestep.io/pricing) の API で1曲約 $0.14。同社の月額 $49 の Studio プランが必要 | Free プランを含むどの ACE Music のプランでも、ACE-Step v1.5 XL の曲はクレジットを消費しません。一方、サードパーティの acestep.io の API を使うには、同社の月額 $49 の Studio プランが必要です(月に約360曲、1曲あたり約 $0.14、2026年11月時点)。 ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. ### curl で曲を生成する方法 useapi.net の API トークン([useapi.net のセットアップ](/docs/start-here/setup-useapi)を参照)と、メールアドレスとパスワードで使う [ACE Music](https://acemusic.ai) のアカウントが必要です。[月額 $15 のサブスクリプション](/docs/subscription)1つで、useapi.net のすべての API と3つの ACE Music アカウントを使えます。ACE Music の Free アカウントでもかまいません。1日20クレジットがもらえ、ACE-Step の曲にはクレジットが要りません。コマンドでは JSON を読むのに [jq](https://jqlang.org) を使います。 #### ACE Music のアカウントを追加する トークンを export し、アカウントを一度だけ追加します。API がサインインしてアカウントを読み取り、ACE Music がパスワードを受け入れた場合にだけ保存します。 ```bash export USEAPI_TOKEN="user:12345-..." API=https://api.useapi.net/v1/acemusic curl -s -X POST "$API/accounts" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "example@example.com", "password": "your-acemusic-password" }' ``` 「Google で続行」や電話番号で作ったアカウントには、先にパスワードを設定する必要があります。[ACE Music のセットアップ](/docs/start-here/setup-acemusic)をご覧ください。そこからアカウントを追加することもできます。 #### プロンプトから曲を作る 作りたい曲を自分の言葉で説明します。ACE Music がスタイル、歌詞、タイトルを書き、2曲を作ります。次のリクエストは、このページの最初の曲を作ったものそのままです。 ```bash curl -s -X POST "$API/music" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A late-night neo-soul slow jam about two strangers sharing an umbrella at a bus stop in the rain and missing the last bus on purpose. Warm Rhodes piano, brushed drums, round upright bass, a smoky female lead with close three-part harmonies on the chorus.", "model": "acemusic-v1", "async": true }' | tee job.json | jq '{jobid, status, model}' ``` `async: true` を付けると、API はすぐに `201` とジョブを返します。プロンプトは最大2,000文字で、参照する曲を最大3曲、画像を最大3枚付けられます。[手持ちの音声や画像をもとに曲を作る](#guide-songs-with-your-own-audio-and-images)をご覧ください。 #### 返ってくる内容 ACE Music が歌詞を書いている間、曲は `planning` で `Untitled` のままで、その後 `queued`、`running` になります。[GET /jobs/`jobid`](/docs/api-acemusic-v1/get-acemusic-jobs-jobid) を10秒ほどおきにポーリングしてください。`jobid` には `:` と `@` が含まれるので、URL エンコードします。 ```bash curl -s "$API/jobs/$(jq -r .jobid job.json | jq -Rr @uri)" \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{status, songs: [.songs[] | {title, status, duration, audioUrl}]}' ``` `status` が `completed` になると、各曲にリンクが入ります(以下の ID は架空のものです)。 ```json { "jobid": "j1115003713275918262m-u12345-email:example@example.com-task:so_7c1d9e3a5b2f4806a4e1c9d3.so_8b4f2e6a1c9d47e5a3b7c0d2-bot:acemusic", "type": "music", "status": "completed", "email": "example@example.com", "created": "2026-11-15T00:37:13.275Z", "model": "acemusic-v1", "modelUsed": "acemusic-v1", "songs": [ { "songId": "user:12345-example@example.com-song:so_7c1d9e3a5b2f4806a4e1c9d3", "taskId": "so_7c1d9e3a5b2f4806a4e1c9d3", "status": "succeeded", "title": "Let the 44 Roll By", "model": "acemusic-v1", "style": "Late-night neo-soul slow jam with a laid-back 1990s and early 2000s pocket, 72 BPM. …", "lyrics": "[Intro - Warm Rhodes chords, brushed snare rim clicks, subtle rain on asphalt]\n\n[Verse 1 …]\nWater dripping off the canvas seam\n…", "instrumental": false, "duration": 277.19, "audioUrl": "https://acemusic.ai/data/so_7c1d9e3a5b2f4806a4e1c9d3.mp3", "playUrl": "https://….r2.cloudflarestorage.com/acemusic-data-prod/users/…/audio/202611/….mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20261115T003902Z&X-Amz-Expires=3599&…", "playUrlExpires": "2026-11-15T01:39:01.000Z", "coverUrl": "https://acemusic.ai/data/so_7c1d9e3a5b2f4806a4e1c9d3-cover.jpg?v=1794703081642", "pageUrl": "https://acemusic.ai/song/r4k8w2n6p9tz", "created": "2026-11-15T00:37:13.300Z", "finished": "2026-11-15T00:38:42.208Z", "kind": "original", "score": false }, { "songId": "user:12345-example@example.com-song:so_8b4f2e6a1c9d47e5a3b7c0d2", "title": "Let the 44 Roll By", "duration": 253.99, "…": "…" } ], "completed": "2026-11-15T00:38:42.208Z" } ``` - `audioUrl` は曲の公開 MP3 リンクで、変わることはありません。`playUrl` は同じ MP3 への Web プレーヤー向けの直接リンクで、`playUrlExpires` まで(約1時間)有効です。Brave など一部のブラウザーは、`audioUrl` の裏にあるリダイレクトをブロックするためです。 - `songId` は、カバー、マッシュアップ、ステム、ダウンロード、楽譜の各リクエストに渡す値です。曲がどのアカウントにあるかを示しているので、これらの呼び出しはそのアカウントで実行されます。 - `model` はリクエストで指定したモデル、`modelUsed` は実際に動いたモデルです([マッシュアップ](#mash-up-two-or-three-songs)を参照)。`kind` は `original`、`cover`、`edit`、`mashup`、`upload` のいずれかで、`score` は曲の楽譜がもうあるかどうかを示します。 - ACE Music が作れなかった曲は `status: "failed"` になり、`error` に ACE Music の理由が入ります。クレジットが返ってきた場合は `refunded: true` になります。 こちらが、その2曲のうちの1曲目です。 ACE Music v1 —「Let the 44 Roll By」· 4:37 · 生成 89秒 <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-let-the-44-roll-by-neo-soul-from-prompt.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### 同期、非同期、Webhook | 送る内容 | POST の応答 | その後 | |---|---|---| | `async: true` | すぐに `201` とジョブ | [GET /jobs/`jobid`](/docs/api-acemusic-v1/get-acemusic-jobs-jobid) をポーリング | | `async` なし | 完成したジョブとともに `200`。上と同じ JSON | 応答から曲を読む。100秒たっても終わらないリクエストは `202` とジョブを返すので、それをポーリング | | `replyUrl` と `replyRef` | 同期でも非同期でも上と同じ | 公開されたご自身の `https` の URL に、`replyRef` を含む完成したジョブが `POST` で1回届く | `async` なしで送った ACE-Step のリクエストは37秒で返り、Webhook は曲の完成から12秒後に届きました。ジョブは7日間読み取れ、開始から30分たっても実行中のジョブは `504` で失敗します。[`async-webhooks/`](https://github.com/useapi/acemusic-api/tree/main/async-webhooks) は3つの方法をすべて実行するスクリプトで、小さな Webhook 受信サーバーも付いています。 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash curl -s -X POST "$API/music" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A dreamy lo-fi hip hop beat for studying late at night: dusty vinyl crackle, mellow Rhodes chords, a soft upright bass and rain on the window", "model": "ace-step-1.5-xl", "replyUrl": "https://your-server.example.com/acemusic-hook", "replyRef": "lofi-1" }' | jq '{status, songs: [.songs[] | {title, duration, audioUrl}]}' ``` </details> ### 自作の歌詞を歌わせる `prompt` の代わりに `style` と `lyrics` を送ると、ACE Music があなたの歌詞をあなたのスタイルで歌います。 | フィールド | 役割 | 上限 | |---|---|---| | `style` | ジャンル、楽器、ムード、テンポ、ボーカル | 1,000文字、ACE-Step では512文字 | | `lyrics` | 歌詞。どの言語でも可。`[Verse]`、`[Chorus]`、`[Bridge]` のタグを使う | 5,000文字、ACE-Step では2,000文字 | | `title` | 曲のタイトル。省略すると ACE Music が付ける | 80文字 | | `instrumental` | `true` でボーカルなし。`lyrics` なしで `style` だけを送っても同じ | | | `duration` | 長さ(秒) | ACE Music v1 では30〜600、ACE-Step では10〜240 | | `negative` | 避けたいスタイル | 200文字。ACE Music v1 と ACE-Step | | `styleInfluence` | スタイルにどれだけ厳密に従うか | `0`〜`100`、デフォルトは `80`。ACE Music v1 と v1.1 | これらのフィールドと `prompt` を一緒に送らないでください。API は `400` を返し、外すべき項目を示します。`duration: 210` を指定したバラードは、210秒と209秒で返ってきました。インストとスペイン語の曲とあわせて、[例](#your-own-lyrics)に載せています。 歌詞がまだない場合は、[POST /music/lyrics](/docs/api-acemusic-v1/post-acemusic-music-lyrics) が依頼内容から歌詞とタイトルを書き、[POST /music/style](/docs/api-acemusic-v1/post-acemusic-music-style) が短い言葉を完全なスタイルに広げます。私たちの依頼はそれぞれ6秒と4秒で返り、クレジットは消費されませんでした。スクリプト:[`custom-lyrics/`](https://github.com/useapi/acemusic-api/tree/main/custom-lyrics) ### ACE-Step でテンポ、キー、拍子を指定する ACE-Step v1.5 XL は、ACE Music のモデルにはない音楽的な設定を受け付け、曲にクレジットもかかりません。 | オプション | 値 | |---|---| | `bpm` | `30`〜`200` | | `timeSignature` | `2/4`、`3/4`、`4/4`、`6/8` | | `key` | `C major`〜`B minor`(C、C#、D、Eb、E、F、F#、G、Ab、A、Bb、B) | | `duration` | `10`〜`240` 秒 | | `negative` | 避けたいスタイル。最大200文字 | | `thinking` | `0`〜`100`:ACE-Step が先に曲全体の構成を考える。低いほど自由に、高いほど安定する | 3/4 拍子のワルツ、6/8 拍子のジグ、174 bpm のドラムンベースという3つの ACE-Step の曲は、どれも指定どおりの長さで返ってきました([例](#ace-step-at-a-set-tempo-key-and-meter))。これらのオプションが使えるのは `ace-step-1.5-xl` の `mode` `generate` だけで、それ以外では API が `400 Parameter bpm does not apply to mode generate on acemusic-v1` を返します。スクリプト:[`ace-step-options/`](https://github.com/useapi/acemusic-api/tree/main/ace-step-options) ### カバー、リミックス、編集 `mode` を使うと、手持ちの曲を素材にしたリクエストになります。`references` にはその曲の `songId` を渡します。API で作った曲、[ライブラリ](#your-library)の曲、ご自身でアップロードした曲が使えます。 | `mode` | `references` | 実行モデル | クレジット | 内容 | |---|---|---|---|---| | `cover` | 1曲 | `acemusic-v1.1`、または `ace-step-1.5-xl` の ACE-Step | 4 / 0 | メロディ、コード、構成を保ったまま、新しい `style` で曲を作り直す | | `remix` | 1曲 | `ace-step-1.5-xl` | 0 | `coverStrength` で原曲を残し、`remixStrength` で原曲から離れる(`0`〜`100`) | | `edit` | 1曲 | `ace-step-1.5-xl` | 0 | `start` 秒から `end` 秒までを新しい `lyrics` で作り直し、残りはそのまま | | `mashup` | 2曲または3曲 | `acemusic-v1.1` | 4 | 複数の曲から新しい1曲を作る(下記参照) | ACE Music v1.1 は、曲の楽譜から読み取ったメロディに沿って作ります。楽譜がまだない ACE Music v1 の曲で最初にカバーを試したときは `ref_no_melody` で失敗し、4クレジットは返ってきました。そのため現在の API は、v1.1 のカバーやマッシュアップの前に、ACE Music v1 の曲の楽譜を無料で先に読み取ります。ACE-Step の曲は自動では読み取らないので、`400` と `ref_no_melody` が返ってきたら、まずその曲で [GET /music/score](#read-the-score) を呼び出し(1クレジット)、それからリクエストを送り直してください。スクリプト:[`covers-remix-edit/`](https://github.com/useapi/acemusic-api/tree/main/covers-remix-edit) #### 2曲または3曲をマッシュアップする `mode: "mashup"` は、同じアカウントにある2曲または3曲から1曲を作ります。`lyrics` を送らなければ、元の曲の歌詞を組み合わせます。`audioInfluence`(0〜100、デフォルトは60)で、元の曲にどれだけ忠実に従うかを決めます。マッシュアップは曲を読み取る必要があるため、ACE Music の Web サイトと同じく、v1 を指定しても ACE Music v1.1 Preview で実行されます。私たちの「Harbor Fiesta」は `"model": "acemusic-v1"` と `"modelUsed": "acemusic-v1.1"` を返し、クレジットは実際に動いたモデルの分がかかります。v1 で指定した `cover`、ACE-Step で参照を2つ以上付けたプロンプト、そして参照曲を付けたプロンプトの一部でも同じことが起きます。スクリプト:[`mashup/`](https://github.com/useapi/acemusic-api/tree/main/mashup) ### 手持ちの音声や画像をもとに曲を作る [POST /files](/docs/api-acemusic-v1/post-acemusic-files) は、ファイルをそのままリクエストの本文として、対応する `Content-Type` とともに受け取ります。 | アップロード | 形式 | 上限 | 返ってくるもの | 使い道 | |---|---|---|---|---| | 音声 | MP3、WAV、FLAC、OGG、M4A、AAC | 100 MB、8分 | `songId`:ライブラリの曲になり、歌詞、スタイル、テンポ、メロディが ACE Music によって書き起こされる | プロンプトの `references`(最大3つ)の1つ、またはカバー、リミックス、編集、マッシュアップする曲 | | 画像 | JPEG、PNG、WebP | 10 MB | `mediaId` | プロンプトの `images`(最大3枚)の1枚:ACE Music がその画像についての曲を書く | ```bash curl -s -X POST "$API/files?title=Harbour%20Jig%20demo" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: audio/mpeg" \ --data-binary @harbour-jig-demo.mp3 | jq '{songId, status, duration, bpm: .upload.bpm}' ``` アップロードした90秒の「Harbour Jig」は14秒で書き起こされ、ACE Music は 115 bpm と聞き取りました(指定は116でした)。踊るロボットの画像からは、その青緑の毛とオレンジのハイカットスニーカーを歌うドラムンベースの曲ができました。どちらも[例](#your-audio-and-pictures)に載せています。アップロードはアカウントの上限に数えられ、音声は Free で10分、Creator で30分、Artist で60分までです。スクリプト:[`upload-reference/`](https://github.com/useapi/acemusic-api/tree/main/upload-reference) ### ステム、ダウンロード、楽譜 完成した曲はどれも、ステムに分け、ダウンロードし、楽譜として読み取れます。 | リクエスト | プラン | クレジット | 返ってくるもの | |---|---|---|---| | [ステム](/docs/api-acemusic-v1/post-acemusic-music-stems)、`mode: "vocals"` | Creator、Artist | 5 | `vocal` と `instrumental` の MP3 | | [ステム](/docs/api-acemusic-v1/post-acemusic-music-stems)、`mode: "all"` | Creator、Artist | 60 | ACE Music が検出したすべてのステムの MP3 | | [ダウンロード](/docs/api-acemusic-v1/get-acemusic-music-download) `mp3`(デフォルト) | すべてのプラン | 0 | `url`(`audioUrl` と同じ)と `playUrl` | | ダウンロード `wav` | Creator、Artist | 0 | 24時間有効なリンク。ACE-Step の曲には使えない | | ダウンロード `midi`、`musicxml` | Creator、Artist | 0 | ファイルそのもの | | [楽譜](/docs/api-acemusic-v1/get-acemusic-music-score) | すべてのプラン | 0、ACE-Step の曲は初回のみ1 | [ABC 記譜法](https://abcnotation.com):ボーカルのメロディ、楽器の旋律、コード、セクション | #### 曲をステムに分ける 「Paper Lanterns」のボーカル分離は約80秒、全パートの分離は2分足らずで終わり、ボーカル、バッキングボーカル、ドラム、ベース、ギター、キーボード、ストリングス、シンセ、FX の9つのステムができました([試聴](#stems-of-paper-lanterns))。ステムのリンクは24時間有効なので、新しいリンクが必要なら曲を読み直してください。同じモードで同じ曲を再び分離すると、すぐに応答が返り、料金はかかりません。 #### MP3、WAV、MIDI、MusicXML をダウンロードする WAV、MIDI、MusicXML は最初のリクエストで ACE Music が作成します。API は最大1分待ってから `202` を返すので、1分後にもう一度呼び出してください。「Paper Lanterns」では3つとも数秒で用意でき、40 MB の WAV、8 KB の MIDI ファイル、107 KB の MusicXML の楽譜になりました。 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash SONG="user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7" curl -s -G "$API/music/download" --data-urlencode "songId=$SONG" -d format=wav \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{url, expires}' curl -s -G "$API/music/download" --data-urlencode "songId=$SONG" -d format=midi \ -H "Authorization: Bearer $USEAPI_TOKEN" -o paper-lanterns.mid ``` </details> #### 楽譜を読み取る ABC に対応したツールなら、この楽譜を五線譜にできます。「Paper Lanterns」では 72 bpm と読み取られ、スタイルで指定したテンポと一致しました。ACE Music v1.1 の曲には最初から楽譜が付いていて、v1.1 のカバーやマッシュアップはそれに沿って作られます。[カバー、リミックス、編集](#covers-remixes-and-edits)をご覧ください。 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash SONG="user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7" curl -s -G "$API/music/score" --data-urlencode "songId=$SONG" \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq -r .abc | head -14 ``` ``` X:1 T: M:2/4 L:1/16 Q:1/4=72 V: Vocal clef=treble name="Vocal Melody" snm="Vocal" V: Ins clef=treble name="Ins Melody" snm="Inst." K:Ab % intro V: Vocal Z|"Ab"z8|"Ab"z8|"Ab"z8| V: Ins Z|Ac2AcBA2|A2EAA2EA|Ac2AcBA2| ``` </details> スクリプト:[`stems-and-downloads/`](https://github.com/useapi/acemusic-api/tree/main/stems-and-downloads)。ステム、すべてのダウンロード形式、楽譜を保存します。 ### ライブラリ アカウントの曲とアップロードは、ここで作ったものも acemusic.ai で作ったものも、削除するまでライブラリに残ります。 | リクエスト | 内容 | |---|---| | [GET /music](/docs/api-acemusic-v1/get-acemusic-music) | 曲の一覧を1ページずつ、新しい順に返し、次のページ用に `next` を付ける。アカウントが2つ以上あるときは `email` が必要。7日より古いジョブの曲もここにある | | [GET /music/`songId`](/docs/api-acemusic-v1/get-acemusic-music-songid) | 新しいリンク付きの1曲。分離済みならステムも含む | | [DELETE /music/`songId`](/docs/api-acemusic-v1/delete-acemusic-music-songid) | `204`:曲は acemusic.ai のアカウントのゴミ箱に移り、以後 API はその曲に `404` を返す | <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash SONG="user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7" curl -s -G "$API/music" --data-urlencode "email=example@example.com" -d limit=20 \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{next, songs: [.songs[] | {title, model, kind, songId}]}' curl -s "$API/music/$(jq -rn --arg v "$SONG" '$v|@uri')" \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{title, score, audioUrl, playUrl, stems: (.stems // {} | keys)}' curl -s -o /dev/null -w "%{http_code}\n" -X DELETE "$API/music/$(jq -rn --arg v "$SONG" '$v|@uri')" \ -H "Authorization: Bearer $USEAPI_TOKEN" ``` </details> スクリプト:[`library/`](https://github.com/useapi/acemusic-api/tree/main/library) ### 複数の ACE Music アカウント useapi.net のサブスクリプション1つにつき ACE Music のアカウントを3つ接続でき、合計で最大100アカウントまで使えます。`email` を指定しないリクエストは、空きのある正常なアカウントに送られ、曲、アップロード、画像を指定したリクエストは、それがあるアカウントで実行されます。各アカウントは同時に最大 `maxJobs` 件のリクエストを実行でき、デフォルトは ACE Music 自体の上限と同じ4件です。$15 のサブスクリプション1つで最大12件の曲リクエストを同時に実行でき(3アカウント × 各4件)、1件のリクエストで2曲が作られるため、ACE Music v1 でも、クレジットを使わない ACE-Step v1.5 XL でも、24曲が並行して生成されます。すべてのアカウントが埋まっていると API は `Retry-After` 付きで `429` を返し、ACE Music にパスワードを拒否されたアカウントは、追加し直すまで `596` を返します。 [GET /accounts/`email`](/docs/api-acemusic-v1/get-acemusic-accounts-email) はプラン、クレジット、クレジットの単価をその場で読み取ります。[POST /accounts](/docs/api-acemusic-v1/post-acemusic-accounts) に `email` と `maxJobs` だけを送ると、`maxJobs` だけが変わります。スクリプト:[`accounts/`](https://github.com/useapi/acemusic-api/tree/main/accounts) <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash curl -s "$API/accounts/$(jq -rn --arg v "example@example.com" '$v|@uri')" \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{plan_name, credits, maxJobs, costs}' curl -s -X POST "$API/accounts" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "example@example.com", "maxJobs": 2 }' ``` </details> ### Claude、ChatGPT、Cursor から使う(MCP) 同じ機能が、15のツールを備えたホスト型の [MCP サーバー](/docs/api-acemusic-v1/mcp)としても使えます。曲、カバー、マッシュアップから、ステム、楽譜、アップロードまで対応しています。Claude Code ならコマンド1つで追加できます。 ```bash claude mcp add --transport http useapi-acemusic https://api.useapi.net/v1/acemusic/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` Cursor、VS Code、Windsurf では同じ URL とヘッダーを使い、Claude アプリと ChatGPT は OAuth でサインインします。[Claude アプリや ChatGPT で使う](/docs/api-acemusic-v1/mcp#use-it-in-the-claude-app-or-chatgpt)をご覧ください。あとは普通の言葉で頼むだけです。たとえば「雨の日が大好きな猫の歌詞を書いて、ACE Music v1 でアコースティックなインディーフォークとして歌わせて」のように頼めます。 #### useapi.net と ACE Music 独自の MCP サーバーの比較 ACE Music también tiene su propio servidor MCP en `https://acemusic.ai/mcp`. Crea canciones de ACE Music v1 y v1.1 a partir del estilo y la letra que escribe tu asistente. El servidor de useapi.net funciona con la misma cuenta de ACE Music y agrega todo lo demás (al 18 de noviembre de 2026): | | MCP de ACE Music de useapi.net | MCP propio de ACE Music | |---|---|---| | ACE-Step v1.5 XL, 0 créditos en todos los planes | Sí | No, solo ACE Music v1 y v1.1 | | Descarga de MP3 en el plan Free | Sí | No, toda descarga requiere un plan de pago | | Covers, remixes, ediciones y mashups | Una llamada para cada uno, a partir de tus canciones | El asistente los arma a partir de una partitura transcrita | | Stems: voz e instrumental, o cada instrumento | Sí | No | | Partituras MusicXML | Sí | No, solo MIDI | | Estilo, letra y título escritos por ACE Music a partir de una idea de una línea | Sí | No, los escribe el asistente | | Varias cuentas de ACE Music en una sola conexión | Sí | Una cuenta por conexión | | Token de API para scripts, n8n y agentes sin interfaz, además de OAuth | Sí | Solo inicio de sesión con OAuth | | Las mismas llamadas por REST, con jobs y webhooks | Sí | No | useapi.net es un servicio de terceros, sin afiliación con ACE Music. ACE Music juga punya MCP server sendiri di `https://acemusic.ai/mcp`. Server itu membuat lagu ACE Music v1 dan v1.1 dari gaya dan lirik yang ditulis asisten Anda. Server useapi.net bekerja di akun ACE Music yang sama dan menambahkan sisanya (per 18 November 2026): | | MCP ACE Music dari useapi.net | MCP milik ACE Music sendiri | |---|---|---| | ACE-Step v1.5 XL, 0 kredit di semua paket | Ya | Tidak, hanya ACE Music v1 dan v1.1 | | Download MP3 di paket Free | Ya | Tidak, setiap download butuh paket berbayar | | Cover, remix, edit, dan mashup | Masing-masing satu panggilan, dari lagu Anda | Dirangkai oleh asisten dari partitur hasil transkripsi | | Stem: vokal dan instrumental, atau setiap instrumen | Ya | Tidak | | Partitur MusicXML | Ya | Tidak, hanya MIDI | | Gaya, lirik, dan judul ditulis ACE Music dari ide satu baris | Ya | Tidak, asisten yang menulisnya | | Beberapa akun ACE Music dalam satu koneksi | Ya | Satu akun per koneksi | | Token API untuk skrip, n8n, dan agen headless, plus OAuth | Ya | Hanya login OAuth | | Panggilan yang sama lewat REST, dengan job dan webhook | Ya | Tidak | useapi.net adalah layanan pihak ketiga dan tidak berafiliasi dengan ACE Music. ACE Music も独自の MCP サーバーを `https://acemusic.ai/mcp` で提供しています。こちらは、アシスタントが書いたスタイルと歌詞から ACE Music v1 と v1.1 の曲を作ります。useapi.net のサーバーは同じ ACE Music アカウントで動き、それ以外のすべてを補います(2026年11月18日時点)。 | | useapi.net の ACE Music MCP | ACE Music 独自の MCP | |---|---|---| | ACE-Step v1.5 XL、どのプランでも0クレジット | 対応 | 非対応、ACE Music v1 と v1.1 のみ | | Free プランでの MP3 ダウンロード | 対応 | 非対応、ダウンロードにはすべて有料プランが必要 | | カバー、リミックス、編集、マッシュアップ | お手持ちの曲から、それぞれ1回の呼び出しで | 書き起こした楽譜をもとにアシスタントが組み立てる | | ステム:ボーカルとインスト、または楽器ごと | 対応 | 非対応 | | MusicXML の楽譜 | 対応 | 非対応、MIDI のみ | | 1行のアイデアから ACE Music がスタイル、歌詞、タイトルを書く | 対応 | 非対応、アシスタントが書く | | 1つの接続で複数の ACE Music アカウント | 対応 | 1接続につき1アカウント | | スクリプト、n8n、ヘッドレスエージェント向けの API トークンと OAuth | 対応 | OAuth サインインのみ | | 同じ呼び出しを REST で、ジョブと Webhook 付きで | 対応 | 非対応 | useapi.net はサードパーティのサービスで、ACE Music とは提携していません。 O ACE Music também tem o próprio servidor MCP em `https://acemusic.ai/mcp`. Ele gera músicas do ACE Music v1 e v1.1 a partir do estilo e da letra que o seu assistente escreve. O servidor da useapi.net funciona na mesma conta do ACE Music e acrescenta todo o resto (em 18 de novembro de 2026): | | MCP do ACE Music da useapi.net | MCP do próprio ACE Music | |---|---|---| | ACE-Step v1.5 XL, 0 créditos em todos os planos | Sim | Não, só ACE Music v1 e v1.1 | | Download de MP3 no plano Free | Sim | Não, todo download exige um plano pago | | Covers, remixes, edições e mashups | Uma chamada para cada, a partir das suas músicas | Montados pelo assistente a partir de uma partitura transcrita | | Stems: vocal e instrumental, ou cada instrumento | Sim | Não | | Partituras MusicXML | Sim | Não, só MIDI | | Estilo, letra e título escritos pelo ACE Music a partir de uma ideia de uma linha | Sim | Não, o assistente escreve | | Várias contas do ACE Music em uma só conexão | Sim | Uma conta por conexão | | Token de API para scripts, n8n e agentes headless, além de OAuth | Sim | Só login com OAuth | | As mesmas chamadas via REST, com jobs e webhooks | Sim | Não | A useapi.net é um serviço de terceiros, sem afiliação com o ACE Music. ACE Music มี MCP server ของตัวเองด้วยที่ `https://acemusic.ai/mcp` ซึ่งสร้างเพลง ACE Music v1 และ v1.1 จากสไตล์และเนื้อเพลงที่ผู้ช่วย AI ของคุณเขียน ส่วน server ของ useapi.net ทำงานบนบัญชี ACE Music เดียวกันและเพิ่มส่วนที่เหลือทั้งหมด (ข้อมูล ณ วันที่ 18 พฤศจิกายน 2026): | | ACE Music MCP ของ useapi.net | MCP ของ ACE Music เอง | |---|---|---| | ACE-Step v1.5 XL ใช้ 0 เครดิตในทุกแพ็กเกจ | ได้ | ไม่ได้ มีแค่ ACE Music v1 และ v1.1 | | ดาวน์โหลด MP3 ในแพ็กเกจ Free | ได้ | ไม่ได้ ทุกการดาวน์โหลดต้องใช้แพ็กเกจเสียเงิน | | คัฟเวอร์ รีมิกซ์ การแก้ไข และแมชอัป | เรียกครั้งเดียวต่ออย่าง จากเพลงของคุณ | ผู้ช่วย AI ประกอบเองจากโน้ตเพลงที่ถอดออกมา | | สเต็ม: เสียงร้องกับดนตรี หรือแยกทุกเครื่องดนตรี | ได้ | ไม่ได้ | | โน้ตเพลง MusicXML | ได้ | ไม่ได้ มีแค่ MIDI | | ACE Music เขียนสไตล์ เนื้อเพลง และชื่อเพลงจากไอเดียบรรทัดเดียว | ได้ | ไม่ได้ ผู้ช่วย AI ต้องเขียนเอง | | หลายบัญชี ACE Music ในการเชื่อมต่อเดียว | ได้ | หนึ่งบัญชีต่อการเชื่อมต่อ | | API token สำหรับสคริปต์ n8n และเอเจนต์ที่ไม่มีหน้าจอ พร้อม OAuth | ได้ | ล็อกอินด้วย OAuth เท่านั้น | | เรียกแบบเดียวกันผ่าน REST พร้อมงานและ webhook | ได้ | ไม่ได้ | useapi.net เป็นบริการของบุคคลที่สาม ไม่มีส่วนเกี่ยวข้องกับ ACE Music ACE Music cũng có MCP server riêng tại `https://acemusic.ai/mcp`. Server này tạo bài hát ACE Music v1 và v1.1 từ phong cách và lời bài hát do trợ lý của bạn viết. Server của useapi.net chạy trên cùng tài khoản ACE Music và bổ sung phần còn lại (tính đến 18 tháng 11 năm 2026): | | MCP ACE Music của useapi.net | MCP riêng của ACE Music | |---|---|---| | ACE-Step v1.5 XL, 0 credit trên mọi gói | Có | Không, chỉ ACE Music v1 và v1.1 | | Tải MP3 trên gói Free | Có | Không, mọi lượt tải đều cần gói trả phí | | Cover, remix, chỉnh sửa và mashup | Mỗi thứ một lệnh gọi, từ bài hát của bạn | Trợ lý tự ghép lại từ bản nhạc được chép ra | | Stem: giọng hát và nhạc nền, hoặc từng nhạc cụ | Có | Không | | Bản nhạc MusicXML | Có | Không, chỉ MIDI | | Phong cách, lời và tên bài do ACE Music viết từ một ý tưởng một dòng | Có | Không, trợ lý tự viết | | Nhiều tài khoản ACE Music trong một kết nối | Có | Một tài khoản cho mỗi kết nối | | API token cho script, n8n và agent chạy không giao diện, cùng với OAuth | Có | Chỉ đăng nhập OAuth | | Cùng các lệnh gọi qua REST, có job và webhook | Có | Không | useapi.net là dịch vụ của bên thứ ba, không liên kết với ACE Music. ACE Music 也在 `https://acemusic.ai/mcp` 运行自己的 MCP 服务器。它根据你的助手写好的风格和歌词生成 ACE Music v1 和 v1.1 歌曲。useapi.net 的服务器使用同一个 ACE Music 账号,并补上其余的一切(截至 2026 年 11 月 18 日): | | useapi.net ACE Music MCP | ACE Music 自己的 MCP | |---|---|---| | ACE-Step v1.5 XL,所有套餐都是 0 积分 | 支持 | 不支持,只有 ACE Music v1 和 v1.1 | | 免费套餐下载 MP3 | 支持 | 不支持,任何下载都需要付费套餐 | | 翻唱、重混、编辑和混搭 | 基于你的歌曲,各一次调用 | 由助手根据转写出的乐谱拼凑完成 | | 分轨:人声和伴奏,或每件乐器 | 支持 | 不支持 | | MusicXML 乐谱 | 支持 | 不支持,只有 MIDI | | 由 ACE Music 根据一句话的想法写出风格、歌词和标题 | 支持 | 不支持,由助手来写 | | 一个连接中使用多个 ACE Music 账号 | 支持 | 每个连接一个账号 | | 用于脚本、n8n 和无界面智能体的 API Token,另有 OAuth | 支持 | 只能 OAuth 登录 | | 通过 REST 进行同样的调用,带任务和 webhook | 支持 | 不支持 | useapi.net 是第三方服务,与 ACE Music 无关联。 ACE Music also runs its own MCP server at `https://acemusic.ai/mcp`. It makes ACE Music v1 and v1.1 songs from the style and lyrics your assistant writes. The useapi.net server works on the same ACE Music account and adds the rest (as of November 18, 2026): | | useapi.net ACE Music MCP | ACE Music's own MCP | |---|---|---| | ACE-Step v1.5 XL, 0 credits on every plan | Yes | No, ACE Music v1 and v1.1 only | | MP3 download on the Free plan | Yes | No, every download needs a paid plan | | Covers, remixes, edits and mashups | One call each, from your songs | Pieced together by the assistant from a transcribed score | | Stems: vocals and instrumental, or every instrument | Yes | No | | MusicXML scores | Yes | No, MIDI only | | Style, lyrics and title written by ACE Music from a one-line idea | Yes | No, the assistant writes them | | Several ACE Music accounts in one connection | Yes | One account per connection | | API token for scripts, n8n and headless agents, plus OAuth | Yes | OAuth sign-in only | | The same calls over REST, with jobs and webhooks | Yes | No | useapi.net is a third-party service, not affiliated with ACE Music. ### スクリプトで一括生成する [`acemusic-api` GitHub リポジトリ](https://github.com/useapi/acemusic-api)には機能ごとに1つずつ例があり、上の各セクションからリンクしています。どれも Node.js のスクリプトとそれに対応する Python 版があり、インストールは不要です。それぞれ、編集した `prompts.json` からリクエストを読み込み、同時に最大4件実行し、ジョブをポーリングして、2曲、そのカバーアート、ジョブの記録、使ったクレジットの `ledger.jsonl` を `output/` フォルダーに保存します。 [Node.js](https://nodejs.org) 21 以降、または [Python](https://www.python.org) 3.8 以降が必要です。`--only 3` は下の3番目のプロンプトを実行します。クレジット不要の ACE-Step の曲なので、Free アカウントでも動きます。 ```bash git clone https://github.com/useapi/acemusic-api.git && cd acemusic-api export USEAPI_TOKEN="user:12345-..." node songs-from-prompt/songs-from-prompt.mjs --only 3 ``` 保存されたジョブの記録には各曲の `songId` が入っていて、`--from <job>.json --pick 1` を付けると1曲目を次のスクリプトに渡し、カバー、マッシュアップ、ステム分離ができます。 <details markdown="block"> <summary>`songs-from-prompt/prompts.json` を表示</summary> ```json [ { "_about": "ACE Music v1 (the default model, 4 credits for two songs): ACE Music writes the style, lyrics and title from your idea", "prompt": "A late-night neo-soul slow jam about two strangers sharing an umbrella at a bus stop in the rain and missing the last bus on purpose. Warm Rhodes piano, brushed drums, round upright bass, a smoky female lead with close three-part harmonies on the chorus.", "model": "acemusic-v1" }, { "_about": "ACE Music v1.1 Preview (4 credits): writes a score first, then the audio", "prompt": "An anthemic Celtic folk-rock singalong about a fishing crew racing a storm back to the harbor. Fiddle and tin whistle hooks, stomping kick drum, bodhran, a gravelly male lead and the whole crew shouting the chorus.", "model": "acemusic-v1.1" }, { "_about": "ACE-Step v1.5 XL (no credits on any ACE Music plan, the Free plan included)", "prompt": "A breezy bossa nova for a lazy Sunday afternoon in Lisbon: nylon-string guitar, soft brushed snare, upright bass, a gentle flute line and a warm male and female duet sung in Portuguese.", "model": "ace-step-1.5-xl" } ] ``` </details> ### 例 以下の曲はすべて、2026年11月14日(PST)にリポジトリのスクリプトで ACE Music の Artist アカウントを使って作ったもので、各リクエストの2曲のうち1曲目です。タイトルは、こちらで指定したもの以外は ACE Music が付けました。時間はリクエストから2曲とも完成するまでのもので、呼び出し例の ID は架空のものです。 #### 画像から作った曲 画像1枚とスタイルの1文を送ると、完成した2曲が返ってきます。踊るロボットのマスコットの画像をアップロードし、ドラムンベースを頼んだところ、ACE Music は画像から読み取った内容で歌詞を書きました。「Teal fur shaking on the concrete floor, orange high-tops squeaking by the studio door」 <img src="https://media.useapi.net/blog/2026-09-07-260907/dreamina-longvideo-ref-robot-mascot.png" alt="箱型の頭、アンテナ、光る目を持つふわふわの青緑のロボットのマスコットが、オレンジのハイカットスニーカーで踊っている" style="width: 100%; max-width: 220px;" loading="lazy"> ``` Bouncy, playful drum and bass for a dancing robot mascot: rolling breakbeats at 174 bpm, a wobbly reese bass, bleepy robot synth hooks, vocoder chops, cheeky and upbeat. ``` ACE Music v1 —「Bleep Boop Bounce」· 2:47 · 生成 72秒 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/files' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: image/png' \ --data-binary @robot-mascot.png curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "Bouncy, playful drum and bass for a dancing robot mascot: rolling breakbeats at 174 bpm, a wobbly reese bass, bleepy robot synth hooks, vocoder chops, cheeky and upbeat.", "model": "acemusic-v1", "images": ["user:12345-example@example.com-media:cx_3b9e1d7a5c2f48e0a6d4b8c1"], "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-bleep-boop-bounce-drum-and-bass-from-robot-image.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> 写真付きの YouTube ショート版はこちら:[YouTube の Bleep Boop Bounce](https://youtube.com/shorts/z_aOmILvIng)。 #### プロンプトから作った曲 プロンプトから作った ACE Music v1 の曲「Let the 44 Roll By」は、[手順の説明](#what-you-get-back)に載せています。ここでは、ほかの2つのモデルでもう2つのプロンプトを試しました。 ``` An anthemic Celtic folk-rock singalong about a fishing crew racing a storm back to the harbor. Fiddle and tin whistle hooks, stomping kick drum, bodhran, a gravelly male lead and the whole crew shouting the chorus. ``` ACE Music v1.1 Preview —「Haul for the Harbor Light」· 2:51 · 生成 43秒 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "An anthemic Celtic folk-rock singalong about a fishing crew racing a storm back to the harbor. Fiddle and tin whistle hooks, stomping kick drum, bodhran, a gravelly male lead and the whole crew shouting the chorus.", "model": "acemusic-v1.1", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-1-haul-for-the-harbor-light-celtic-folk-rock-from-prompt.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ``` A breezy bossa nova for a lazy Sunday afternoon in Lisbon: nylon-string guitar, soft brushed snare, upright bass, a gentle flute line and a warm male and female duet sung in Portuguese. ``` ACE-Step v1.5 XL、クレジット不要 —「Domingo em Alfama」· 3:28 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "A breezy bossa nova for a lazy Sunday afternoon in Lisbon: nylon-string guitar, soft brushed snare, upright bass, a gentle flute line and a warm male and female duet sung in Portuguese.", "model": "ace-step-1.5-xl", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-domingo-em-alfama-bossa-nova-from-prompt.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### 自作の歌詞で作った曲 自分たちで書いた2つのヴァース、プリコーラス、ブリッジ、アウトロで、長さは210秒を指定しました。 ``` Style: cinematic indie pop ballad, felt piano, swelling strings, deep heartbeat kick, intimate female vocal that opens up into a soaring chorus, 72 bpm Lyrics: [Verse 1] We wrote our names on paper lanterns / Down by the river in July … [Chorus] Light it up and let it go / Every word I never said out loud … ``` ACE Music v1 —「Paper Lanterns」· 3:29 · 生成 61秒 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "title": "Paper Lanterns", "style": "cinematic indie pop ballad, felt piano, swelling strings, deep heartbeat kick, intimate female vocal that opens up into a soaring chorus, 72 bpm", "lyrics": "[Verse 1]\nWe wrote our names on paper lanterns\nDown by the river in July\nYou said the wind would know the answer\nIf we just let the fire fly\nYour hand was shaking, mine was steady\nAt least that'\''s how I tell it now\nWe watched them climb until the city\nWas just a glow beneath the clouds\n\n[Pre-Chorus]\nSo every summer I come back here\nStrike a match and hold it near\n\n[Chorus]\nLight it up and let it go\nEvery word I never said out loud\nLight it up and let it go\nHigher than the both of us somehow\nAnd if it finds you anyhow\nTell me you can see it from the clouds\n\n[Verse 2]\nThey tore the old pier down last winter\nPut up a fence and painted lines\nBut I still know the way by heartbeat\nI find the water every time\nI keep a lighter in my pocket\nI keep your laugh inside my head\nI fold the paper like you showed me\nAnd write the things I should have said\n\n[Pre-Chorus]\nSo every summer I come back here\nStrike a match and hold it near\n\n[Chorus]\nLight it up and let it go\nEvery word I never said out loud\nLight it up and let it go\nHigher than the both of us somehow\nAnd if it finds you anyhow\nTell me you can see it from the clouds\n\n[Bridge]\nPaper and fire, paper and fire\nNothing this light should rise so high\nPaper and fire, paper and fire\nMaybe that'\''s how we say goodbye\n\n[Final Chorus]\nLight it up and let it go\nEvery word I never said out loud\nLight it up and let it go\nHigher than the both of us somehow\n\n[Outro]\nDown by the river in July", "model": "acemusic-v1", "duration": 210, "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-paper-lanterns-custom-lyrics.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> インストです。`instrumental: true`、150秒で、ボーカル、合唱、アコースティックギターを除外しました。 ``` Style: cinematic synthwave instrumental for a night drive: pulsing analog bass arpeggio, gated reverb drums, lush pads, a soaring lead synth melody, builds to a big final section, 108 bpm ``` ACE Music v1 —「Neon Overpass」· 2:29 · 生成 46秒 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "title": "Neon Overpass", "style": "cinematic synthwave instrumental for a night drive: pulsing analog bass arpeggio, gated reverb drums, lush pads, a soaring lead synth melody, builds to a big final section, 108 bpm", "instrumental": true, "model": "acemusic-v1", "duration": 150, "negative": "vocals, choir, acoustic guitar", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-neon-overpass-synthwave-instrumental.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> 停電の夜の屋上パーティーを歌った、スペイン語の歌詞です。 ``` Style: modern cumbia pop, bright accordion hooks, güira and congas, warm bass, a festive male lead with a crowd shouting the chorus, 98 bpm Lyrics: [Chorus] Bailando en la azotea / Con las estrellas de farol … ``` ACE Music v1 —「Bailando en la Azotea」· 2:32 · 生成 46秒 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "title": "Bailando en la Azotea", "style": "modern cumbia pop, bright accordion hooks, güira and congas, warm bass, a festive male lead with a crowd shouting the chorus, 98 bpm", "lyrics": "[Verse 1]\nSe fue la luz en todo el barrio\nY nadie quiere irse a dormir\nDoña Rosa saca el radio viejo\nY la noche empieza a sonreír\nLos vecinos suben con sus sillas\nAlguien trae limones y café\nY la ciudad allá abajo, oscura\nNos mira bailar sin saber por qué\n\n[Pre-Chorus]\nSube, sube, que la luna está invitando\nSube, sube, que la calle está cantando\n\n[Chorus]\nBailando en la azotea\nCon las estrellas de farol\nQue se entere todo el mundo\nQue esta noche no hay apagón\nBailando en la azotea\nCon el corazón de tambor\nSi se apaga la ciudad entera\nAquí arriba sobra amor\n\n[Verse 2]\nEl abuelo saca la guitarra\nLa vecina de enfrente se animó\nLos niños corren entre las sábanas\nQue el viento de la tarde colgó\nNadie sabe cuándo vuelve la corriente\nY la verdad, a nadie le importó\nEsta fiesta no la paga nadie\nEsta fiesta la invitó el apagón\n\n[Chorus]\nBailando en la azotea\nCon las estrellas de farol\nQue se entere todo el mundo\nQue esta noche no hay apagón\nBailando en la azotea\nCon el corazón de tambor\nSi se apaga la ciudad entera\nAquí arriba sobra amor\n\n[Outro]\nQue esta noche no hay apagón", "model": "acemusic-v1", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-bailando-en-la-azotea-spanish-cumbia.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> 歌詞は歌詞の作成ツール、スタイルはスタイルの作成ツールが書き、ACE-Step が歌いました。 ``` Lyrics writer: A wistful country song about an old pickup truck that still has her mixtape stuck in the tape deck Style writer: classic country ballad, pedal steel, warm baritone ``` ACE-Step v1.5 XL、クレジット不要 —「Side B Forever」· 3:35 · 生成 40秒(その前に歌詞 6秒、スタイル 4秒) <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music/lyrics' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "A wistful country song about an old pickup truck that still has her mixtape stuck in the tape deck", "style": "classic country ballad, pedal steel, warm baritone", "model": "ace-step-1.5-xl" }' > lyrics.json curl -X POST 'https://api.useapi.net/v1/acemusic/music/style' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "style": "classic country ballad, pedal steel, warm baritone", "model": "ace-step-1.5-xl" }' > style.json # sing what the writers returned jq -n --slurpfile l lyrics.json --slurpfile s style.json \ '{title: $l[0].title, lyrics: $l[0].lyrics, style: $s[0].style, model: "ace-step-1.5-xl", async: true}' | curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d @- ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-side-b-forever-lyrics-and-style-writers.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### テンポ、キー、拍子を指定した ACE-Step どれも指定どおりの長さで返ってきました。 ``` 3/4 · 84 bpm · D minor · 120 s · thinking 60 · avoid: trap drums, EDM, autotune Style: dark cabaret waltz, accordion, pizzicato strings, upright bass, brushed snare, theatrical female vocal ``` ACE-Step v1.5 XL、クレジット不要 —「Midnight Waltz」· 2:00 · 生成 31秒 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "model": "ace-step-1.5-xl", "title": "Midnight Waltz", "style": "dark cabaret waltz, accordion, pizzicato strings, upright bass, brushed snare, theatrical female vocal", "lyrics": "[Verse 1]\nThe band plays slow when the lights go low\nAnd the chandeliers begin to sway\nTake my hand, we will dance till the candles stand\nIn puddles of yesterday\n\n[Chorus]\nOne, two, three, turn around with me\nRound and round till the morning comes\nOne, two, three, oh don'\''t let me be\nThe last one dancing when the music'\''s done\n\n[Verse 2]\nThe clock strikes twelve and it laughs at itself\nEvery mirror wears a stranger'\''s face\nHold me close, we are only ghosts\nWho forgot to leave this place\n\n[Chorus]\nOne, two, three, turn around with me\nRound and round till the morning comes\nOne, two, three, oh don'\''t let me be\nThe last one dancing when the music'\''s done", "bpm": 84, "timeSignature": "3/4", "key": "D minor", "duration": 120, "negative": "trap drums, EDM, autotune", "thinking": 60, "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-midnight-waltz-3-4-84-bpm-d-minor.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ``` 6/8 · 116 bpm · G major · 90 s · instrumental Style: lively celtic instrumental jig, fiddle and tin whistle trading the melody, bodhran, strummed bouzouki, foot stomps ``` ACE-Step v1.5 XL、クレジット不要 —「Harbour Jig」· 1:30 · 生成 20秒 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "model": "ace-step-1.5-xl", "title": "Harbour Jig", "style": "lively celtic instrumental jig, fiddle and tin whistle trading the melody, bodhran, strummed bouzouki, foot stomps", "instrumental": true, "bpm": 116, "timeSignature": "6/8", "key": "G major", "duration": 90, "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-harbour-jig-6-8-116-bpm-g-major.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ``` 4/4 · 174 bpm · F minor · 150 s · thinking 80 Style: liquid drum and bass, rolling breakbeats, deep warm sub bass, airy pads, soulful female vocal ``` ACE-Step v1.5 XL、クレジット不要 —「Almost Home」· 2:30 · 生成 41秒 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "model": "ace-step-1.5-xl", "title": "Almost Home", "style": "liquid drum and bass, rolling breakbeats, deep warm sub bass, airy pads, soulful female vocal", "lyrics": "[Verse]\nCity lights in the rear view mirror\nRunning on a borrowed night\nEvery bridge is a little bit nearer\nEvery tunnel full of light\n\n[Chorus]\nHold on, we'\''re almost home\nEvery signal turning green\nHold on, you'\''re not alone\nFaster than the in-between\n\n[Verse]\nRadio low and the windows open\nBreathing in the summer rain\nEvery promise we left unspoken\nRushing back to us again\n\n[Chorus]\nHold on, we'\''re almost home\nEvery signal turning green\nHold on, you'\''re not alone\nFaster than the in-between", "bpm": 174, "timeSignature": "4/4", "key": "F minor", "duration": 150, "thinking": 80, "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-almost-home-drum-and-bass-174-bpm-f-minor.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### カバー、リミックス、編集の例 「Paper Lanterns」のカバーです。メロディはそのままに、新しいスタイルにしました。 ``` mode: cover · stripped-back acoustic folk cover, fingerpicked steel-string guitar, warm cello, soft close-mic'd male vocal ``` ACE Music v1.1 Preview —「Paper Lanterns (Acoustic Folk Cover)」· 3:34 · 生成 72秒 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash # our script read the score first (free for an ACE Music v1 song; the API now does this by itself) curl 'https://api.useapi.net/v1/acemusic/music/score?songId=user%3A12345-example%40example.com-song%3Aso_4e7b2c9d0a5f4183b6d8e2c7' \ -H 'Authorization: Bearer user:12345-…' > /dev/null curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "mode": "cover", "model": "acemusic-v1.1", "references": ["user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7"], "style": "stripped-back acoustic folk cover, fingerpicked steel-string guitar, warm cello, soft close-mic'\''d male vocal", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-1-paper-lanterns-acoustic-folk-cover.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> 「Bailando en la Azotea」をディープハウスにしました。タイトルを送らなかったので、ACE Music は「Reference 1」と名付けました。 ``` mode: remix · coverStrength 40 · remixStrength 50 · deep house remix, four-on-the-floor kick, plucky chords, rolling bassline, filtered vocal chops ``` ACE-Step v1.5 XL、クレジット不要 —「Reference 1」· 2:32 · 生成 31秒 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "mode": "remix", "model": "ace-step-1.5-xl", "references": ["user:12345-example@example.com-song:so_9d3b7e2c1a6f4085b8e4d1c6"], "style": "deep house remix, four-on-the-floor kick, plucky chords, rolling bassline, filtered vocal chops", "coverStrength": 40, "remixStrength": 50, "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-bailando-en-la-azotea-house-remix.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> 「Paper Lanterns」の30秒から50秒までを新しい歌詞にし、残りはそのままにしました。 ``` mode: edit · start 30 · end 50 Lyrics: We wrote our names on paper lanterns / Down by the harbor in the snow / You said the stars would keep the answer / If we were brave enough to go ``` ACE-Step v1.5 XL、クレジット不要 —「Reference 1」· 3:29 · 生成 41秒 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "mode": "edit", "model": "ace-step-1.5-xl", "references": ["user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7"], "start": 30, "end": 50, "style": "cinematic indie pop ballad, felt piano, swelling strings, intimate female vocal", "lyrics": "We wrote our names on paper lanterns\nDown by the harbor in the snow\nYou said the stars would keep the answer\nIf we were brave enough to go", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-paper-lanterns-edit-seconds-30-50.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### マッシュアップ 「Paper Lanterns」と「Let the 44 Roll By」: ``` upbeat neo-soul pop mashup, punchy live drums, warm Rhodes and strings, female lead with a gospel-tinged choir on the chorus · audioInfluence 60 ``` ACE Music v1.1 Preview —「Lanterns at the Bus Stop」· 3:58 · 生成 83秒 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash # our script read each song's score first (the API now does this by itself for ACE Music v1 songs) curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "mode": "mashup", "model": "acemusic-v1.1", "references": ["user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7", "user:12345-example@example.com-song:so_7c1d9e3a5b2f4806a4e1c9d3"], "title": "Lanterns at the Bus Stop", "style": "upbeat neo-soul pop mashup, punchy live drums, warm Rhodes and strings, female lead with a gospel-tinged choir on the chorus", "audioInfluence": 60, "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-1-mashup-lanterns-at-the-bus-stop.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> 「Haul for the Harbor Light」と「Bailando en la Azotea」を、ACE Music v1 を指定してマッシュアップしました。 ``` festive celtic cumbia mashup, fiddle and accordion trading hooks, congas and bodhran, stomping kick, male lead with a big crowd chorus ``` ACE Music v1.1 Preview(指定は v1)—「Harbor Fiesta」· 2:38 · 生成 74秒 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash # our script read each song's score first (the API now does this by itself for ACE Music v1 songs) curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "mode": "mashup", "model": "acemusic-v1", "references": ["user:12345-example@example.com-song:so_2a8f6c1e9d4b47f3b0c5e8a2", "user:12345-example@example.com-song:so_9d3b7e2c1a6f4085b8e4d1c6"], "title": "Harbor Fiesta", "style": "festive celtic cumbia mashup, fiddle and accordion trading hooks, congas and bodhran, stomping kick, male lead with a big crowd chorus", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-1-mashup-harbor-fiesta-asked-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> 3曲を一度に:「Paper Lanterns」、「Bailando en la Azotea」、「Let the 44 Roll By」 ``` warm late-night soul-pop medley, Rhodes and strings, light latin percussion, female lead with a male answer on the last chorus ``` ACE Music v1.1 Preview —「Three Songs, One Night」· 3:32 · 生成 43秒 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash # our script read each song's score first (the API now does this by itself for ACE Music v1 songs) curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "mode": "mashup", "model": "acemusic-v1.1", "references": ["user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7", "user:12345-example@example.com-song:so_9d3b7e2c1a6f4085b8e4d1c6", "user:12345-example@example.com-song:so_7c1d9e3a5b2f4806a4e1c9d3"], "title": "Three Songs, One Night", "style": "warm late-night soul-pop medley, Rhodes and strings, light latin percussion, female lead with a male answer on the last chorus", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-1-mashup-three-songs-one-night.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### 手持ちの音声と画像 上の「Harbour Jig」を MP3 としてアップロードし、プロンプトの参照にしました。ACE Music は曲調を保つため v1.1 で実行しました。 ``` A rowdy pub singalong with a big shouted chorus about the last ferry home, built on the tune of this recording ``` ACE Music v1.1 Preview(指定は v1)—「Last Ferry Home」· 1:36 · 生成 52秒 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/files?title=Harbour%20Jig%20demo' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: audio/mpeg' \ --data-binary @harbour-jig-demo.mp3 curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "A rowdy pub singalong with a big shouted chorus about the last ferry home, built on the tune of this recording", "model": "acemusic-v1", "references": ["user:12345-example@example.com-song:so_5f1a3c8e7b2d49a6c3e0f7b9"], "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-1-last-ferry-home-from-uploaded-jig.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### 「Paper Lanterns」のステム `mode: "vocals"`(5クレジット)で得たボーカルとインスト、続いて `mode: "all"`(60クレジット)で得た9つのステムのうちドラムとストリングスです。 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music/stems' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "songId": "user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7", "mode": "vocals", "async": true }' curl -X POST 'https://api.useapi.net/v1/acemusic/music/stems' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "songId": "user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7", "mode": "all", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-paper-lanterns-stem-vocal.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-paper-lanterns-stem-instrumental.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-paper-lanterns-stem-drums.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-paper-lanterns-stem-strings.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ### よくある質問 **ACE Music の API はありますか?** useapi.net を使えば、あります。[ACE Music API](/docs/api-acemusic-v1) は、ACE Music v1、ACE Music v1.1 Preview、ACE-Step v1.5 XL を、お使いの ACE Music アカウントで REST から実行し、カバー、マッシュアップ、ステム、MIDI にも対応します。 **無料の ACE-Step API はありますか?** useapi.net を使えば、あります。ACE-Step v1.5 XL の曲は、Free プランを含むどの ACE Music のプランでもクレジットを消費せず、テンポ、キー、拍子、長さの設定、リミックス、編集にも対応します。サードパーティの acestep.io は、ACE-Step API を月額 $49 の Studio プランでしか提供しておらず、1曲あたり約 $0.14 です(2026年11月時点)。 **API で ACE Music v1 の曲を作るといくらかかりますか?** useapi.net なら、ACE Music v1 の曲は1曲につきお使いの ACE Music のプランの2クレジットで、Artist の年払いなら $0.013、Artist の月払いなら $0.023 です。曲ごとの上乗せはありません。[料金](#pricing)をご覧ください。 **ACE Music の MCP サーバーはありますか?** useapi.net を使えば、あります。しかも `acemusic.ai/mcp` にある ACE Music 独自のサーバーより多くのことができます。ホスト型の [ACE Music MCP サーバー](/docs/api-acemusic-v1/mcp)は、無料の ACE-Step v1.5 XL モデル、Free プランでの MP3 ダウンロード、ステム、1回の呼び出しでできるカバー、リミックス、編集、マッシュアップ、MusicXML、そして1つの API トークンでの複数アカウントに対応します。ACE Music 独自のサーバーはアシスタントが書いた歌詞から v1 と v1.1 の曲を作るもので、ダウンロードにはすべて有料プランが必要です。詳しくは[比較表](#useapinet-vs-ace-musics-own-mcp-server)をご覧ください。 ### おわりに POST を1回送るだけで、ボーカルのリーダーボードで首位のモデルが2曲を作ります。ACE-Step の曲は無料で、どの曲も次の呼び出しでカバー、マッシュアップ、ステム、MIDI ファイルにできます。[`acemusic-api` リポジトリ](https://github.com/useapi/acemusic-api)をクローンし、Free アカウントで `songs-from-prompt/` を `--only 3` 付きで実行してみてください。すべてのオプションは [POST /music](/docs/api-acemusic-v1/post-acemusic-music) にあります。 ご質問は <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord サーバー</a> または <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram チャンネル</a>へどうぞ。 === URL: https://useapi.net/docs/articles/ace-music-api-tutorial-pt === Document URL: https://useapi.net/docs/articles/ace-music-api-tutorial-pt --- layout: default title: Como gerar músicas com IA pela API do ACE Music description: "Gere músicas com o ACE Music v1, o v1.1 e o ACE-Step v1.5 XL gratuito pela API do ACE Music da useapi.net: prompts, letras próprias, covers, mashups, stems e MIDI, com curl e código." keywords: [ACE Music API, API do ACE Music, ACE Music v1 API, ACE-Step API, API do ACE-Step, ACE-Step v1.5 XL, AI song generator API, API de música com IA, gerador de músicas com IA, API de texto para música, alternativa ao Suno, stems API, MIDI, MusicXML, mashup, cover com IA, servidor MCP, curl, tutorial] image: https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-paper-lanterns-cover-art.jpg parent: Articles nav_exclude: true lang: pt-BR translation_key: ace-music-tutorial date: 2026-11-14 last_modified: 2026-11-18 nav_order: 302 repo: https://github.com/useapi/acemusic-api --- ## Como gerar músicas com IA pela API do ACE Music {: .no_toc #how-to-generate-ai-songs-with-the-ace-music-api } 22 min de leitura • 14 de novembro de 2026 ## Sumário {: .no_toc .text-delta #table-of-contents } ### Introdução A [API do ACE Music](/docs/api-acemusic-v1) da useapi.net transforma uma única chamada REST em duas músicas prontas do [ACE Music](https://acemusic.ai), com vocais, letra, título e capa, na assinatura do ACE Music que você já tem. O ACE Music v1 está em 1º lugar no [ranking de música vocal da Artificial Analysis](https://artificialanalysis.ai/music/leaderboard/vocals), à frente do Suno v6. O [ACE-Step](https://ace-step.github.io) v1.5 XL, de código aberto, roda pela mesma API sem gastar créditos em nenhum plano do ACE Music, inclusive no plano Free. Este guia começa pelos três modelos e pelo custo de uma música, faz uma música do início ao fim com `curl` e depois cobre todos os outros recursos numa tabela curta. Os [Exemplos](#examples) no final são 18 músicas que fizemos para esta página, cada uma com a requisição que a gerou, todas com os scripts do [repositório `acemusic-api` no GitHub](https://github.com/useapi/acemusic-api) (Node.js e Python), por 117 créditos de um plano Artist, com as tomadas extras. A useapi.net é uma API de [terceiros](/docs/legal#affiliation--third-party-services), sem afiliação com o ACE Music nem com a Timedomain, a empresa que o criou. ### Modelos e o que a API faz Toda requisição gera duas músicas, e `model` escolhe quem as faz: | Modelo | `model` | Para que serve | Ajustes | Créditos por requisição | Tempo nos testes | |---|---|---|---|---|---| | ACE Music v1 | `acemusic-v1` (padrão) | O modelo vocal nº 1: músicas a partir de um prompt ou da sua letra, cantadas ou instrumentais | `duration` de 30 a 600 s, `negative`, `styleInfluence`, downloads em WAV | 4 | 46 a 89 s | | ACE Music v1.1 Preview | `acemusic-v1.1` | Escreve primeiro uma partitura, então os covers e mashups seguem a melodia da música | `audioInfluence`, `styleInfluence` | 4 | 35 a 83 s | | ACE-Step v1.5 XL | `ace-step-1.5-xl` | Código aberto, da ACE Studio e da StepFun: músicas, remixes e edições | `bpm`, `key`, `timeSignature`, `duration` de 10 a 240 s, `negative`, `thinking`. Só MP3 | 0 | 20 a 55 s | O que dá para fazer com eles: | O quê | Requisição | Observações | |---|---|---| | Músicas a partir de um prompt | [POST /music](/docs/api-acemusic-v1/post-acemusic-music) `prompt` | O ACE Music escreve o estilo, a letra e o título | | Sua própria letra, instrumentais | [POST /music](/docs/api-acemusic-v1/post-acemusic-music) `style`, `lyrics` | Qualquer idioma | | Geradores de letra e de estilo | [POST /music/lyrics](/docs/api-acemusic-v1/post-acemusic-music-lyrics), [/music/style](/docs/api-acemusic-v1/post-acemusic-music-style) | Sem créditos | | Covers, remixes, edições, mashups | [POST /music](/docs/api-acemusic-v1/post-acemusic-music#modes) `mode` | Em qualquer música da conta | | Seu áudio e suas imagens | [POST /files](/docs/api-acemusic-v1/post-acemusic-files) | Como referências para novas músicas | | Stems | [POST /music/stems](/docs/api-acemusic-v1/post-acemusic-music-stems) | Creator e Artist | | Downloads, partitura | [GET /music/download](/docs/api-acemusic-v1/get-acemusic-music-download), [/music/score](/docs/api-acemusic-v1/get-acemusic-music-score) | MP3 e a partitura em todos os planos, WAV, MIDI e MusicXML no Creator e no Artist | | Biblioteca, jobs, contas | [GET /music](/docs/api-acemusic-v1/get-acemusic-music), [/jobs](/docs/api-acemusic-v1/get-acemusic-jobs), [/accounts](/docs/api-acemusic-v1/get-acemusic-accounts-email) | Todas as músicas da conta, jobs em andamento, créditos ao vivo | | Servidor MCP | [`/v1/acemusic/mcp`](/docs/api-acemusic-v1/mcp) | 15 ferramentas para assistentes de IA | ### Preços O ACE Music cobra créditos próprios por requisição, do seu plano do ACE Music, e a useapi.net não acrescenta nada por música (em novembro de 2026): | Requisição | Créditos | |---|---| | Duas músicas no ACE Music v1 ou v1.1 | 4 | | Stems, vocal + instrumental | 5, planos pagos | | Stems, todos os stems | 60, planos pagos | | Partitura de uma música do ACE-Step, primeira leitura | 1 | | Duas músicas no ACE-Step v1.5 XL | 0, em todos os planos | | Geradores de letra e de estilo, uploads, downloads | 0 nos nossos testes | Os [planos do ACE Music](https://acemusic.ai/pricing/) são o Free, com 20 créditos por dia, o Creator, a $9,90 por mês por 1.000 créditos, e o Artist, a $29 por mês por 2.500 créditos, ou $7,90 e $16,58 por mês com cobrança anual. Uma música é meia requisição, 2 créditos. A [visão geral da API](/docs/api-acemusic-v1#pricing) tem a mesma tabela. Quanto custa uma música em cada plano, do mais barato à esquerda (uma requisição gera duas músicas, então uma música custa metade dos créditos da requisição; em novembro de 2026): | Modelo | Free (20 cr/dia) | Artist $16,58/mês (2.500 cr/mês, cobrança anual) | Creator $7,90/mês (1.000 cr/mês, cobrança anual) | Creator $9,90/mês (1.000 cr/mês) | Artist $29/mês (2.500 cr/mês) | |---|---|---|---|---|---| | ACE Music v1, v1.1 (uma música) | $0 / 2 cr (10 músicas/dia) | $0,013 / 2 cr (1.250/mês) | $0,016 / 2 cr (500/mês) | $0,020 / 2 cr (500/mês) | $0,023 / 2 cr (1.250/mês) | | Stems (vocal + instrumental) | planos pagos | $0,033 / 5 cr | $0,040 / 5 cr | $0,050 / 5 cr | $0,058 / 5 cr | | Stems (todos os stems) | planos pagos | $0,40 / 60 cr | $0,47 / 60 cr | $0,59 / 60 cr | $0,70 / 60 cr | | Partitura ACE-Step (primeira leitura) | $0 / 1 cr | $0,007 / 1 cr | $0,008 / 1 cr | $0,010 / 1 cr | $0,012 / 1 cr | | ACE-Step v1.5 XL (uma música) | $0 / 0 cr | $0 / 0 cr | $0 / 0 cr | $0 / 0 cr | $0 / 0 cr | Como isso se compara com as outras formas de chamar esses modelos por código: | Modelo | useapi.net | Outras APIs | |---|---|---| | ACE Music v1, v1.1 Preview | a partir de $0,013 por música no Artist com cobrança anual, $0 nos 20 créditos diários do plano Free | — | | ACE-Step v1.5 XL | $0 em todos os planos do ACE Music, inclusive no Free | cerca de $0,14 por música na API da [acestep.io](https://acestep.io/pricing), de terceiros, que exige o plano Studio de $49 por mês | Em qualquer plano do ACE Music, inclusive no Free, uma música do ACE-Step v1.5 XL não gasta créditos, contra a API da acestep.io, de terceiros, que exige o plano Studio de $49 por mês (cerca de 360 músicas por mês, cerca de $0,14 por música, em novembro de 2026). ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. ### Como gerar uma música com curl Você precisa de um token da API da useapi.net, veja o [Setup useapi.net](/docs/start-here/setup-useapi), e de uma conta do [ACE Music](https://acemusic.ai) com e-mail e senha. Uma [assinatura de $15 por mês](/docs/subscription) cobre todas as APIs da useapi.net e 3 contas do ACE Music. Uma conta Free do ACE Music funciona: ela ganha 20 créditos por dia, e as músicas do ACE-Step não gastam nenhum. Os comandos usam o [jq](https://jqlang.org) para ler o JSON. #### Adicione a sua conta do ACE Music Exporte o token e adicione a conta uma única vez. A API faz login, lê a conta e só a salva se o ACE Music aceitar a senha: ```bash export USEAPI_TOKEN="user:12345-..." API=https://api.useapi.net/v1/acemusic curl -s -X POST "$API/accounts" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "example@example.com", "password": "your-acemusic-password" }' ``` Uma conta criada com Continue with Google ou com um número de telefone precisa primeiro de uma senha, veja o [Setup ACE Music](/docs/start-here/setup-acemusic), que também pode adicioná-la para você. #### Gere músicas a partir de um prompt Descreva a música com as suas palavras. O ACE Music escreve o estilo, a letra e o título e depois gera duas músicas. Esta é a requisição exata por trás da primeira música desta página: ```bash curl -s -X POST "$API/music" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A late-night neo-soul slow jam about two strangers sharing an umbrella at a bus stop in the rain and missing the last bus on purpose. Warm Rhodes piano, brushed drums, round upright bass, a smoky female lead with close three-part harmonies on the chorus.", "model": "acemusic-v1", "async": true }' | tee job.json | jq '{jobid, status, model}' ``` Com `async: true` a API responde `201` na hora, com o job. Um prompt pode ter até 2.000 caracteres e levar até 3 músicas de referência e 3 imagens, veja [Guie as músicas com o seu próprio áudio e imagens](#guide-songs-with-your-own-audio-and-images). #### O que você recebe Enquanto o ACE Music escreve a letra, as músicas ficam em `planning` e `Untitled`, depois em `queued` e `running`. Consulte [GET /jobs/`jobid`](/docs/api-acemusic-v1/get-acemusic-jobs-jobid) a cada 10 segundos, mais ou menos. O `jobid` contém `:` e `@`, então codifique-o para URL: ```bash curl -s "$API/jobs/$(jq -r .jobid job.json | jq -Rr @uri)" \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{status, songs: [.songs[] | {title, status, duration, audioUrl}]}' ``` Quando `status` for `completed`, cada música traz os seus links (os ids abaixo são inventados): ```json { "jobid": "j1115003713275918262m-u12345-email:example@example.com-task:so_7c1d9e3a5b2f4806a4e1c9d3.so_8b4f2e6a1c9d47e5a3b7c0d2-bot:acemusic", "type": "music", "status": "completed", "email": "example@example.com", "created": "2026-11-15T00:37:13.275Z", "model": "acemusic-v1", "modelUsed": "acemusic-v1", "songs": [ { "songId": "user:12345-example@example.com-song:so_7c1d9e3a5b2f4806a4e1c9d3", "taskId": "so_7c1d9e3a5b2f4806a4e1c9d3", "status": "succeeded", "title": "Let the 44 Roll By", "model": "acemusic-v1", "style": "Late-night neo-soul slow jam with a laid-back 1990s and early 2000s pocket, 72 BPM. …", "lyrics": "[Intro - Warm Rhodes chords, brushed snare rim clicks, subtle rain on asphalt]\n\n[Verse 1 …]\nWater dripping off the canvas seam\n…", "instrumental": false, "duration": 277.19, "audioUrl": "https://acemusic.ai/data/so_7c1d9e3a5b2f4806a4e1c9d3.mp3", "playUrl": "https://….r2.cloudflarestorage.com/acemusic-data-prod/users/…/audio/202611/….mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20261115T003902Z&X-Amz-Expires=3599&…", "playUrlExpires": "2026-11-15T01:39:01.000Z", "coverUrl": "https://acemusic.ai/data/so_7c1d9e3a5b2f4806a4e1c9d3-cover.jpg?v=1794703081642", "pageUrl": "https://acemusic.ai/song/r4k8w2n6p9tz", "created": "2026-11-15T00:37:13.300Z", "finished": "2026-11-15T00:38:42.208Z", "kind": "original", "score": false }, { "songId": "user:12345-example@example.com-song:so_8b4f2e6a1c9d47e5a3b7c0d2", "title": "Let the 44 Roll By", "duration": 253.99, "…": "…" } ], "completed": "2026-11-15T00:38:42.208Z" } ``` - `audioUrl` é o link público do MP3 da música e nunca muda. `playUrl` é um link direto para o mesmo MP3, para players na web, válido até `playUrlExpires` (cerca de uma hora): alguns navegadores, como o Brave, bloqueiam o redirecionamento por trás do `audioUrl`. - `songId` é o que covers, mashups, stems, downloads e a partitura recebem. Ele identifica a conta em que a música está, então essas chamadas rodam nela. - `model` é o modelo que você pediu, e `modelUsed` o que rodou (veja [mashups](#mash-up-two-or-three-songs)). `kind` é `original`, `cover`, `edit`, `mashup` ou `upload`, e `score` diz se a música já tem a partitura. - Uma música que o ACE Music não conseguiu gerar tem `status: "failed"`, o motivo do ACE Music em `error` e `refunded: true` quando os créditos voltaram. E aqui está a primeira dessas duas músicas: ACE Music v1 — "Let the 44 Roll By" · 4:37 · gerada em 89 s <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-let-the-44-roll-by-neo-soul-from-prompt.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### Síncrono, assíncrono e webhooks | Você envia | O POST responde | Depois | |---|---|---| | `async: true` | `201` na hora, com o job | Consulte [GET /jobs/`jobid`](/docs/api-acemusic-v1/get-acemusic-jobs-jobid) | | sem `async` | `200` com o job pronto, o mesmo JSON de cima | Leia as músicas na resposta. Uma requisição ainda em andamento depois de 100 segundos responde `202` com o job: consulte-o | | `replyUrl` e `replyRef` | como acima, tanto no modo síncrono quanto no assíncrono | A sua URL `https` pública recebe um único `POST` com o job pronto, com o seu `replyRef` nele | A nossa requisição do ACE-Step sem `async` voltou em 37 segundos, e o webhook chegou 12 segundos depois de as músicas ficarem prontas. Um job pode ser lido por 7 dias, e um que ainda esteja rodando 30 minutos depois de começar falha com `504`. O [`async-webhooks/`](https://github.com/useapi/acemusic-api/tree/main/async-webhooks) roda as três formas e inclui um pequeno receptor de webhook. <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash curl -s -X POST "$API/music" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A dreamy lo-fi hip hop beat for studying late at night: dusty vinyl crackle, mellow Rhodes chords, a soft upright bass and rain on the window", "model": "ace-step-1.5-xl", "replyUrl": "https://your-server.example.com/acemusic-hook", "replyRef": "lofi-1" }' | jq '{status, songs: [.songs[] | {title, duration, audioUrl}]}' ``` </details> ### Cante a sua própria letra Envie `style` e `lyrics` em vez de `prompt`, e o ACE Music canta as suas palavras no seu estilo: | Campo | O que faz | Limites | |---|---|---| | `style` | Gênero, instrumentos, clima, andamento e vocais | 1.000 caracteres, 512 no ACE-Step | | `lyrics` | As suas palavras, em qualquer idioma, com as tags `[Verse]`, `[Chorus]`, `[Bridge]` | 5.000 caracteres, 2.000 no ACE-Step | | `title` | O título das músicas. Sem ele, o ACE Music escolhe um | 80 caracteres | | `instrumental` | `true` para não ter vocais. Um `style` sem `lyrics` faz o mesmo | | | `duration` | A duração em segundos | 30 a 600 no ACE Music v1, 10 a 240 no ACE-Step | | `negative` | Estilos a evitar | 200 caracteres, ACE Music v1 e ACE-Step | | `styleInfluence` | O quanto o estilo é seguido à risca | `0` a `100`, padrão `80`, ACE Music v1 e v1.1 | Nunca envie `prompt` junto com esses campos: a API responde `400` e diz o que tirar. A nossa balada, pedida com `duration: 210`, voltou com 210 e 209 segundos. Ela está nos [Exemplos](#your-own-lyrics), com um instrumental e uma música em espanhol. Ainda sem letra? O [POST /music/lyrics](/docs/api-acemusic-v1/post-acemusic-music-lyrics) escreve uma letra e um título a partir de um pedido, e o [POST /music/style](/docs/api-acemusic-v1/post-acemusic-music-style) transforma poucas palavras num estilo completo. Os nossos voltaram em 6 e 4 segundos, sem cobrança de créditos. Script: [`custom-lyrics/`](https://github.com/useapi/acemusic-api/tree/main/custom-lyrics). ### Controle andamento, tom e compasso com o ACE-Step O ACE-Step v1.5 XL aceita configurações musicais que os modelos do ACE Music não aceitam, e as músicas dele não gastam créditos: | Opção | Valores | |---|---| | `bpm` | `30` a `200` | | `timeSignature` | `2/4`, `3/4`, `4/4`, `6/8` | | `key` | `C major` a `B minor` (C, C#, D, Eb, E, F, F#, G, Ab, A, Bb, B) | | `duration` | `10` a `240` segundos | | `negative` | estilos a evitar, até 200 caracteres | | `thinking` | `0` a `100`: o ACE-Step planeja a música inteira primeiro, criativo com valores baixos, estável com valores altos | As três músicas que fizemos no ACE-Step, uma valsa em 3/4, uma jig em 6/8 e um drum and bass a 174 bpm, voltaram exatamente com a duração pedida ([Exemplos](#ace-step-at-a-set-tempo-key-and-meter)). Essas opções só funcionam no `mode` `generate` com `ace-step-1.5-xl`, e em qualquer outro caso a API responde `400 Parameter bpm does not apply to mode generate on acemusic-v1`. Script: [`ace-step-options/`](https://github.com/useapi/acemusic-api/tree/main/ace-step-options). ### Covers, remixes e edições `mode` transforma uma requisição em trabalho sobre músicas que você já tem. `references` recebe os `songId`s delas: músicas que a API gerou, músicas da sua [Biblioteca](#your-library) ou os seus próprios uploads. | `mode` | `references` | Roda em | Créditos | O que faz | |---|---|---|---|---| | `cover` | 1 música | `acemusic-v1.1`, ou ACE-Step em `ace-step-1.5-xl` | 4 / 0 | A música num novo `style`, seguindo a melodia, os acordes e a estrutura dela | | `remix` | 1 música | `ace-step-1.5-xl` | 0 | `coverStrength` preserva o original, `remixStrength` se afasta dele (`0` a `100`) | | `edit` | 1 música | `ace-step-1.5-xl` | 0 | Reescreve o trecho entre `start` e `end` segundos com uma nova `lyrics` e mantém o resto | | `mashup` | 2 ou 3 músicas | `acemusic-v1.1` | 4 | Uma música nova feita de várias, veja abaixo | O ACE Music v1.1 segue a melodia que lê da partitura de uma música. O nosso primeiro cover de uma música do ACE Music v1 ainda sem partitura falhou com `ref_no_melody`, e os 4 créditos voltaram, então agora a API lê primeiro a partitura de uma música do ACE Music v1, de graça, antes de um cover ou mashup no v1.1. As músicas do ACE-Step não são lidas automaticamente: se uma delas responder `400` com `ref_no_melody`, chame primeiro o [GET /music/score](#read-the-score) nela (1 crédito) e envie a requisição de novo. Script: [`covers-remix-edit/`](https://github.com/useapi/acemusic-api/tree/main/covers-remix-edit). #### Faça um mashup de duas ou três músicas `mode: "mashup"` gera uma música a partir de 2 ou 3 músicas da mesma conta, combinando as letras delas, a menos que você envie `lyrics`. `audioInfluence` (0 a 100, padrão 60) define o quanto as músicas são seguidas. Um mashup precisa ler as músicas, então roda no ACE Music v1.1 Preview mesmo quando você pede o v1, como no site do ACE Music: o nosso "Harbor Fiesta" informa `"model": "acemusic-v1"` e `"modelUsed": "acemusic-v1.1"`, e os créditos seguem o modelo que rodou. O mesmo acontece com um `cover` pedido no v1, com um prompt com mais de uma referência no ACE-Step e, às vezes, com um prompt com uma música de referência. Script: [`mashup/`](https://github.com/useapi/acemusic-api/tree/main/mashup). ### Guie as músicas com o seu próprio áudio e imagens O [POST /files](/docs/api-acemusic-v1/post-acemusic-files) recebe o arquivo como corpo bruto da requisição, com o `Content-Type` dele: | Upload | Formatos | Até | Você recebe | Use como | |---|---|---|---|---| | Áudio | MP3, WAV, FLAC, OGG, M4A, AAC | 100 MB, 8 minutos | Um `songId`: uma música da Biblioteca, com a letra, o estilo, o andamento e a melodia transcritos pelo ACE Music | Uma das até 3 `references` de um prompt, ou a música para fazer cover, remix, edição ou mashup | | Imagem | JPEG, PNG, WebP | 10 MB | Um `mediaId` | Uma das até 3 `images` de um prompt: o ACE Music escreve uma música sobre ela | ```bash curl -s -X POST "$API/files?title=Harbour%20Jig%20demo" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: audio/mpeg" \ --data-binary @harbour-jig-demo.mp3 | jq '{songId, status, duration, bpm: .upload.bpm}' ``` O nosso upload de 90 segundos da "Harbour Jig" foi transcrito em 14 segundos, e o ACE Music ouviu 115 bpm (tínhamos pedido 116). A foto de um robô dançando virou um drum and bass sobre o pelo verde-azulado e os tênis de cano alto laranja dele. Os dois estão nos [Exemplos](#your-audio-and-pictures). Os uploads contam na cota da conta: 10 minutos de áudio no Free, 30 no Creator e 60 no Artist. Script: [`upload-reference/`](https://github.com/useapi/acemusic-api/tree/main/upload-reference). ### Stems, downloads e a partitura Toda música pronta pode ser separada em stems, baixada e lida como partitura: | Requisição | Planos | Créditos | Você recebe | |---|---|---|---| | [Stems](/docs/api-acemusic-v1/post-acemusic-music-stems), `mode: "vocals"` | Creator, Artist | 5 | MP3s `vocal` e `instrumental` | | [Stems](/docs/api-acemusic-v1/post-acemusic-music-stems), `mode: "all"` | Creator, Artist | 60 | Todos os stems que o ACE Music encontrar, em MP3 | | [Download](/docs/api-acemusic-v1/get-acemusic-music-download) `mp3` (padrão) | todos os planos | 0 | `url` (o mesmo que `audioUrl`) e `playUrl` | | Download `wav` | Creator, Artist | 0 | Um link válido por 24 horas. Não vale para músicas do ACE-Step | | Download `midi`, `musicxml` | Creator, Artist | 0 | O próprio arquivo | | [Partitura](/docs/api-acemusic-v1/get-acemusic-music-score) | todos os planos | 0, ou 1 na primeira vez para uma música do ACE-Step | [Notação ABC](https://abcnotation.com): a melodia vocal, uma linha instrumental, os acordes e as seções | #### Separe uma música em stems A separação vocal de "Paper Lanterns" levou cerca de 80 segundos, e a completa menos de 2 minutos, com 9 stems: voz, backing vocals, bateria, baixo, guitarra, teclado, cordas, synth e fx ([ouça](#stems-of-paper-lanterns)). Os links dos stems duram 24 horas, então leia a música de novo para ter links novos. Separar uma música de novo no mesmo modo responde na hora e não cobra nada. #### Baixe MP3, WAV, MIDI e MusicXML O ACE Music gera o WAV, o MIDI e o MusicXML no primeiro pedido: a API espera até um minuto e depois responde `202`, então chame de novo um minuto depois. Para "Paper Lanterns", os três ficaram prontos em segundos: um WAV de 40 MB, um arquivo MIDI de 8 KB e uma partitura MusicXML de 107 KB. <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash SONG="user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7" curl -s -G "$API/music/download" --data-urlencode "songId=$SONG" -d format=wav \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{url, expires}' curl -s -G "$API/music/download" --data-urlencode "songId=$SONG" -d format=midi \ -H "Authorization: Bearer $USEAPI_TOKEN" -o paper-lanterns.mid ``` </details> #### Leia a partitura Qualquer ferramenta de ABC transforma a partitura em notas na pauta. Para "Paper Lanterns", ela leu 72 bpm, o andamento que pedimos no estilo. As músicas do ACE Music v1.1 já vêm com a partitura, e os covers e mashups do v1.1 a seguem, veja [Covers, remixes e edições](#covers-remixes-and-edits). <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash SONG="user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7" curl -s -G "$API/music/score" --data-urlencode "songId=$SONG" \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq -r .abc | head -14 ``` ``` X:1 T: M:2/4 L:1/16 Q:1/4=72 V: Vocal clef=treble name="Vocal Melody" snm="Vocal" V: Ins clef=treble name="Ins Melody" snm="Inst." K:Ab % intro V: Vocal Z|"Ab"z8|"Ab"z8|"Ab"z8| V: Ins Z|Ac2AcBA2|A2EAA2EA|Ac2AcBA2| ``` </details> Script: [`stems-and-downloads/`](https://github.com/useapi/acemusic-api/tree/main/stems-and-downloads), que salva os stems, todos os formatos de download e a partitura. ### A sua Biblioteca Toda música e todo upload da conta, feitos aqui ou em acemusic.ai, ficam na Biblioteca dela até serem apagados: | Requisição | O que faz | |---|---| | [GET /music](/docs/api-acemusic-v1/get-acemusic-music) | Uma página de músicas, das mais novas para as mais antigas, com `next` para a página seguinte. `email` é obrigatório com mais de uma conta. As músicas de jobs com mais de 7 dias estão aqui | | [GET /music/`songId`](/docs/api-acemusic-v1/get-acemusic-music-songid) | Uma música com links novos, e os stems dela quando ela foi separada | | [DELETE /music/`songId`](/docs/api-acemusic-v1/delete-acemusic-music-songid) | `204`: a música vai para a lixeira da conta em acemusic.ai, e a API responde `404` para ela a partir daí | <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash SONG="user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7" curl -s -G "$API/music" --data-urlencode "email=example@example.com" -d limit=20 \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{next, songs: [.songs[] | {title, model, kind, songId}]}' curl -s "$API/music/$(jq -rn --arg v "$SONG" '$v|@uri')" \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{title, score, audioUrl, playUrl, stems: (.stems // {} | keys)}' curl -s -o /dev/null -w "%{http_code}\n" -X DELETE "$API/music/$(jq -rn --arg v "$SONG" '$v|@uri')" \ -H "Authorization: Bearer $USEAPI_TOKEN" ``` </details> Script: [`library/`](https://github.com/useapi/acemusic-api/tree/main/library). ### Várias contas do ACE Music Cada assinatura da useapi.net conecta 3 contas do ACE Music, até 100 no total. Uma requisição sem `email` vai para uma conta saudável com vaga livre, e uma que cita uma música, um upload ou uma imagem roda na conta onde ela está. Uma conta roda até `maxJobs` requisições ao mesmo tempo, 4 por padrão, o limite do próprio ACE Music. Uma assinatura de $15 roda até 12 requisições de música ao mesmo tempo (3 contas × 4 cada), e cada requisição gera duas músicas, então 24 músicas são geradas em paralelo, no ACE Music v1 ou no ACE-Step v1.5 XL, que não usa créditos. Com todas as contas ocupadas, a API responde `429` com `Retry-After`, e uma senha que o ACE Music recusa faz essa conta responder `596` até você adicioná-la de novo. O [GET /accounts/`email`](/docs/api-acemusic-v1/get-acemusic-accounts-email) lê ao vivo o plano, os créditos e o custo em créditos de cada recurso, e o [POST /accounts](/docs/api-acemusic-v1/post-acemusic-accounts) só com `email` e `maxJobs` muda apenas o `maxJobs`. Script: [`accounts/`](https://github.com/useapi/acemusic-api/tree/main/accounts). <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash curl -s "$API/accounts/$(jq -rn --arg v "example@example.com" '$v|@uri')" \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{plan_name, credits, maxJobs, costs}' curl -s -X POST "$API/accounts" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "example@example.com", "maxJobs": 2 }' ``` </details> ### Use pelo Claude, ChatGPT ou Cursor (MCP) Os mesmos recursos estão num [servidor MCP](/docs/api-acemusic-v1/mcp) hospedado, com 15 ferramentas, de músicas, covers e mashups a stems, partituras e uploads. No Claude Code é um único comando: ```bash claude mcp add --transport http useapi-acemusic https://api.useapi.net/v1/acemusic/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` O Cursor, o VS Code e o Windsurf usam a mesma URL e o mesmo header, e o app do Claude e o ChatGPT fazem login com OAuth, veja [como usar no app do Claude ou no ChatGPT](/docs/api-acemusic-v1/mcp#use-it-in-the-claude-app-or-chatgpt). Depois é só pedir em linguagem natural: "Write lyrics about a cat who loves rainy days and sing them as acoustic indie folk on ACE Music v1". #### useapi.net vs. o servidor MCP do próprio ACE Music ACE Music también tiene su propio servidor MCP en `https://acemusic.ai/mcp`. Crea canciones de ACE Music v1 y v1.1 a partir del estilo y la letra que escribe tu asistente. El servidor de useapi.net funciona con la misma cuenta de ACE Music y agrega todo lo demás (al 18 de noviembre de 2026): | | MCP de ACE Music de useapi.net | MCP propio de ACE Music | |---|---|---| | ACE-Step v1.5 XL, 0 créditos en todos los planes | Sí | No, solo ACE Music v1 y v1.1 | | Descarga de MP3 en el plan Free | Sí | No, toda descarga requiere un plan de pago | | Covers, remixes, ediciones y mashups | Una llamada para cada uno, a partir de tus canciones | El asistente los arma a partir de una partitura transcrita | | Stems: voz e instrumental, o cada instrumento | Sí | No | | Partituras MusicXML | Sí | No, solo MIDI | | Estilo, letra y título escritos por ACE Music a partir de una idea de una línea | Sí | No, los escribe el asistente | | Varias cuentas de ACE Music en una sola conexión | Sí | Una cuenta por conexión | | Token de API para scripts, n8n y agentes sin interfaz, además de OAuth | Sí | Solo inicio de sesión con OAuth | | Las mismas llamadas por REST, con jobs y webhooks | Sí | No | useapi.net es un servicio de terceros, sin afiliación con ACE Music. ACE Music juga punya MCP server sendiri di `https://acemusic.ai/mcp`. Server itu membuat lagu ACE Music v1 dan v1.1 dari gaya dan lirik yang ditulis asisten Anda. Server useapi.net bekerja di akun ACE Music yang sama dan menambahkan sisanya (per 18 November 2026): | | MCP ACE Music dari useapi.net | MCP milik ACE Music sendiri | |---|---|---| | ACE-Step v1.5 XL, 0 kredit di semua paket | Ya | Tidak, hanya ACE Music v1 dan v1.1 | | Download MP3 di paket Free | Ya | Tidak, setiap download butuh paket berbayar | | Cover, remix, edit, dan mashup | Masing-masing satu panggilan, dari lagu Anda | Dirangkai oleh asisten dari partitur hasil transkripsi | | Stem: vokal dan instrumental, atau setiap instrumen | Ya | Tidak | | Partitur MusicXML | Ya | Tidak, hanya MIDI | | Gaya, lirik, dan judul ditulis ACE Music dari ide satu baris | Ya | Tidak, asisten yang menulisnya | | Beberapa akun ACE Music dalam satu koneksi | Ya | Satu akun per koneksi | | Token API untuk skrip, n8n, dan agen headless, plus OAuth | Ya | Hanya login OAuth | | Panggilan yang sama lewat REST, dengan job dan webhook | Ya | Tidak | useapi.net adalah layanan pihak ketiga dan tidak berafiliasi dengan ACE Music. ACE Music も独自の MCP サーバーを `https://acemusic.ai/mcp` で提供しています。こちらは、アシスタントが書いたスタイルと歌詞から ACE Music v1 と v1.1 の曲を作ります。useapi.net のサーバーは同じ ACE Music アカウントで動き、それ以外のすべてを補います(2026年11月18日時点)。 | | useapi.net の ACE Music MCP | ACE Music 独自の MCP | |---|---|---| | ACE-Step v1.5 XL、どのプランでも0クレジット | 対応 | 非対応、ACE Music v1 と v1.1 のみ | | Free プランでの MP3 ダウンロード | 対応 | 非対応、ダウンロードにはすべて有料プランが必要 | | カバー、リミックス、編集、マッシュアップ | お手持ちの曲から、それぞれ1回の呼び出しで | 書き起こした楽譜をもとにアシスタントが組み立てる | | ステム:ボーカルとインスト、または楽器ごと | 対応 | 非対応 | | MusicXML の楽譜 | 対応 | 非対応、MIDI のみ | | 1行のアイデアから ACE Music がスタイル、歌詞、タイトルを書く | 対応 | 非対応、アシスタントが書く | | 1つの接続で複数の ACE Music アカウント | 対応 | 1接続につき1アカウント | | スクリプト、n8n、ヘッドレスエージェント向けの API トークンと OAuth | 対応 | OAuth サインインのみ | | 同じ呼び出しを REST で、ジョブと Webhook 付きで | 対応 | 非対応 | useapi.net はサードパーティのサービスで、ACE Music とは提携していません。 O ACE Music também tem o próprio servidor MCP em `https://acemusic.ai/mcp`. Ele gera músicas do ACE Music v1 e v1.1 a partir do estilo e da letra que o seu assistente escreve. O servidor da useapi.net funciona na mesma conta do ACE Music e acrescenta todo o resto (em 18 de novembro de 2026): | | MCP do ACE Music da useapi.net | MCP do próprio ACE Music | |---|---|---| | ACE-Step v1.5 XL, 0 créditos em todos os planos | Sim | Não, só ACE Music v1 e v1.1 | | Download de MP3 no plano Free | Sim | Não, todo download exige um plano pago | | Covers, remixes, edições e mashups | Uma chamada para cada, a partir das suas músicas | Montados pelo assistente a partir de uma partitura transcrita | | Stems: vocal e instrumental, ou cada instrumento | Sim | Não | | Partituras MusicXML | Sim | Não, só MIDI | | Estilo, letra e título escritos pelo ACE Music a partir de uma ideia de uma linha | Sim | Não, o assistente escreve | | Várias contas do ACE Music em uma só conexão | Sim | Uma conta por conexão | | Token de API para scripts, n8n e agentes headless, além de OAuth | Sim | Só login com OAuth | | As mesmas chamadas via REST, com jobs e webhooks | Sim | Não | A useapi.net é um serviço de terceiros, sem afiliação com o ACE Music. ACE Music มี MCP server ของตัวเองด้วยที่ `https://acemusic.ai/mcp` ซึ่งสร้างเพลง ACE Music v1 และ v1.1 จากสไตล์และเนื้อเพลงที่ผู้ช่วย AI ของคุณเขียน ส่วน server ของ useapi.net ทำงานบนบัญชี ACE Music เดียวกันและเพิ่มส่วนที่เหลือทั้งหมด (ข้อมูล ณ วันที่ 18 พฤศจิกายน 2026): | | ACE Music MCP ของ useapi.net | MCP ของ ACE Music เอง | |---|---|---| | ACE-Step v1.5 XL ใช้ 0 เครดิตในทุกแพ็กเกจ | ได้ | ไม่ได้ มีแค่ ACE Music v1 และ v1.1 | | ดาวน์โหลด MP3 ในแพ็กเกจ Free | ได้ | ไม่ได้ ทุกการดาวน์โหลดต้องใช้แพ็กเกจเสียเงิน | | คัฟเวอร์ รีมิกซ์ การแก้ไข และแมชอัป | เรียกครั้งเดียวต่ออย่าง จากเพลงของคุณ | ผู้ช่วย AI ประกอบเองจากโน้ตเพลงที่ถอดออกมา | | สเต็ม: เสียงร้องกับดนตรี หรือแยกทุกเครื่องดนตรี | ได้ | ไม่ได้ | | โน้ตเพลง MusicXML | ได้ | ไม่ได้ มีแค่ MIDI | | ACE Music เขียนสไตล์ เนื้อเพลง และชื่อเพลงจากไอเดียบรรทัดเดียว | ได้ | ไม่ได้ ผู้ช่วย AI ต้องเขียนเอง | | หลายบัญชี ACE Music ในการเชื่อมต่อเดียว | ได้ | หนึ่งบัญชีต่อการเชื่อมต่อ | | API token สำหรับสคริปต์ n8n และเอเจนต์ที่ไม่มีหน้าจอ พร้อม OAuth | ได้ | ล็อกอินด้วย OAuth เท่านั้น | | เรียกแบบเดียวกันผ่าน REST พร้อมงานและ webhook | ได้ | ไม่ได้ | useapi.net เป็นบริการของบุคคลที่สาม ไม่มีส่วนเกี่ยวข้องกับ ACE Music ACE Music cũng có MCP server riêng tại `https://acemusic.ai/mcp`. Server này tạo bài hát ACE Music v1 và v1.1 từ phong cách và lời bài hát do trợ lý của bạn viết. Server của useapi.net chạy trên cùng tài khoản ACE Music và bổ sung phần còn lại (tính đến 18 tháng 11 năm 2026): | | MCP ACE Music của useapi.net | MCP riêng của ACE Music | |---|---|---| | ACE-Step v1.5 XL, 0 credit trên mọi gói | Có | Không, chỉ ACE Music v1 và v1.1 | | Tải MP3 trên gói Free | Có | Không, mọi lượt tải đều cần gói trả phí | | Cover, remix, chỉnh sửa và mashup | Mỗi thứ một lệnh gọi, từ bài hát của bạn | Trợ lý tự ghép lại từ bản nhạc được chép ra | | Stem: giọng hát và nhạc nền, hoặc từng nhạc cụ | Có | Không | | Bản nhạc MusicXML | Có | Không, chỉ MIDI | | Phong cách, lời và tên bài do ACE Music viết từ một ý tưởng một dòng | Có | Không, trợ lý tự viết | | Nhiều tài khoản ACE Music trong một kết nối | Có | Một tài khoản cho mỗi kết nối | | API token cho script, n8n và agent chạy không giao diện, cùng với OAuth | Có | Chỉ đăng nhập OAuth | | Cùng các lệnh gọi qua REST, có job và webhook | Có | Không | useapi.net là dịch vụ của bên thứ ba, không liên kết với ACE Music. ACE Music 也在 `https://acemusic.ai/mcp` 运行自己的 MCP 服务器。它根据你的助手写好的风格和歌词生成 ACE Music v1 和 v1.1 歌曲。useapi.net 的服务器使用同一个 ACE Music 账号,并补上其余的一切(截至 2026 年 11 月 18 日): | | useapi.net ACE Music MCP | ACE Music 自己的 MCP | |---|---|---| | ACE-Step v1.5 XL,所有套餐都是 0 积分 | 支持 | 不支持,只有 ACE Music v1 和 v1.1 | | 免费套餐下载 MP3 | 支持 | 不支持,任何下载都需要付费套餐 | | 翻唱、重混、编辑和混搭 | 基于你的歌曲,各一次调用 | 由助手根据转写出的乐谱拼凑完成 | | 分轨:人声和伴奏,或每件乐器 | 支持 | 不支持 | | MusicXML 乐谱 | 支持 | 不支持,只有 MIDI | | 由 ACE Music 根据一句话的想法写出风格、歌词和标题 | 支持 | 不支持,由助手来写 | | 一个连接中使用多个 ACE Music 账号 | 支持 | 每个连接一个账号 | | 用于脚本、n8n 和无界面智能体的 API Token,另有 OAuth | 支持 | 只能 OAuth 登录 | | 通过 REST 进行同样的调用,带任务和 webhook | 支持 | 不支持 | useapi.net 是第三方服务,与 ACE Music 无关联。 ACE Music also runs its own MCP server at `https://acemusic.ai/mcp`. It makes ACE Music v1 and v1.1 songs from the style and lyrics your assistant writes. The useapi.net server works on the same ACE Music account and adds the rest (as of November 18, 2026): | | useapi.net ACE Music MCP | ACE Music's own MCP | |---|---|---| | ACE-Step v1.5 XL, 0 credits on every plan | Yes | No, ACE Music v1 and v1.1 only | | MP3 download on the Free plan | Yes | No, every download needs a paid plan | | Covers, remixes, edits and mashups | One call each, from your songs | Pieced together by the assistant from a transcribed score | | Stems: vocals and instrumental, or every instrument | Yes | No | | MusicXML scores | Yes | No, MIDI only | | Style, lyrics and title written by ACE Music from a one-line idea | Yes | No, the assistant writes them | | Several ACE Music accounts in one connection | Yes | One account per connection | | API token for scripts, n8n and headless agents, plus OAuth | Yes | OAuth sign-in only | | The same calls over REST, with jobs and webhooks | Yes | No | useapi.net is a third-party service, not affiliated with ACE Music. ### Gere em lote com os scripts O [repositório `acemusic-api` no GitHub](https://github.com/useapi/acemusic-api) tem um exemplo por recurso, com link em cada seção acima: um script em Node.js e um gêmeo em Python, sem nada para instalar. Cada um lê as requisições de um `prompts.json` que você edita, roda até 4 ao mesmo tempo, consulta os jobs e salva na pasta `output/` as duas músicas, as capas, o registro do job e um `ledger.jsonl` com os créditos gastos. Você precisa do [Node.js](https://nodejs.org) 21 ou mais recente ou do [Python](https://www.python.org) 3.8 ou mais recente. `--only 3` roda o terceiro prompt abaixo, uma música do ACE-Step sem créditos, então funciona numa conta Free: ```bash git clone https://github.com/useapi/acemusic-api.git && cd acemusic-api export USEAPI_TOKEN="user:12345-..." node songs-from-prompt/songs-from-prompt.mjs --only 3 ``` Cada registro de job salvo guarda os `songId`s das músicas, e `--from <job>.json --pick 1` passa a música 1 para o próximo script fazer um cover, um mashup ou a separação em stems. <details markdown="block"> <summary>Abrir `songs-from-prompt/prompts.json`</summary> ```json [ { "_about": "ACE Music v1 (the default model, 4 credits for two songs): ACE Music writes the style, lyrics and title from your idea", "prompt": "A late-night neo-soul slow jam about two strangers sharing an umbrella at a bus stop in the rain and missing the last bus on purpose. Warm Rhodes piano, brushed drums, round upright bass, a smoky female lead with close three-part harmonies on the chorus.", "model": "acemusic-v1" }, { "_about": "ACE Music v1.1 Preview (4 credits): writes a score first, then the audio", "prompt": "An anthemic Celtic folk-rock singalong about a fishing crew racing a storm back to the harbor. Fiddle and tin whistle hooks, stomping kick drum, bodhran, a gravelly male lead and the whole crew shouting the chorus.", "model": "acemusic-v1.1" }, { "_about": "ACE-Step v1.5 XL (no credits on any ACE Music plan, the Free plan included)", "prompt": "A breezy bossa nova for a lazy Sunday afternoon in Lisbon: nylon-string guitar, soft brushed snare, upright bass, a gentle flute line and a warm male and female duet sung in Portuguese.", "model": "ace-step-1.5-xl" } ] ``` </details> ### Exemplos Todas as músicas abaixo foram feitas em 14 de novembro de 2026 (PST) com os scripts do repositório numa conta Artist do ACE Music, sempre a primeira das duas músicas de cada requisição. Os títulos são do ACE Music, a menos que tenhamos definido um, os tempos vão da requisição até as duas músicas ficarem prontas, e as chamadas mostram ids inventados. #### Uma música a partir de uma imagem Entram uma imagem e uma frase de estilo, saem duas músicas prontas. Enviamos esta foto de um mascote robô dançando e pedimos drum and bass; o ACE Music escreveu a letra a partir do que viu: "Teal fur shaking on the concrete floor, orange high-tops squeaking by the studio door". <img src="https://media.useapi.net/blog/2026-09-07-260907/dreamina-longvideo-ref-robot-mascot.png" alt="Um mascote robô verde-azulado e peludo, com cabeça de caixa, antena e olhos que acendem, dançando de tênis de cano alto laranja" style="width: 100%; max-width: 220px;" loading="lazy"> ``` Bouncy, playful drum and bass for a dancing robot mascot: rolling breakbeats at 174 bpm, a wobbly reese bass, bleepy robot synth hooks, vocoder chops, cheeky and upbeat. ``` ACE Music v1 — "Bleep Boop Bounce" · 2:47 · gerada em 72 s <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/files' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: image/png' \ --data-binary @robot-mascot.png curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "Bouncy, playful drum and bass for a dancing robot mascot: rolling breakbeats at 174 bpm, a wobbly reese bass, bleepy robot synth hooks, vocoder chops, cheeky and upbeat.", "model": "acemusic-v1", "images": ["user:12345-example@example.com-media:cx_3b9e1d7a5c2f48e0a6d4b8c1"], "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-bleep-boop-bounce-drum-and-bass-from-robot-image.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> A música como YouTube Short, com a foto: [Bleep Boop Bounce no YouTube](https://youtube.com/shorts/z_aOmILvIng). #### Músicas a partir de um prompt A música do ACE Music v1 feita a partir de um prompt, "Let the 44 Roll By", está no [passo a passo](#what-you-get-back). Mais dois prompts, nos outros dois modelos: ``` An anthemic Celtic folk-rock singalong about a fishing crew racing a storm back to the harbor. Fiddle and tin whistle hooks, stomping kick drum, bodhran, a gravelly male lead and the whole crew shouting the chorus. ``` ACE Music v1.1 Preview — "Haul for the Harbor Light" · 2:51 · gerada em 43 s <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "An anthemic Celtic folk-rock singalong about a fishing crew racing a storm back to the harbor. Fiddle and tin whistle hooks, stomping kick drum, bodhran, a gravelly male lead and the whole crew shouting the chorus.", "model": "acemusic-v1.1", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-1-haul-for-the-harbor-light-celtic-folk-rock-from-prompt.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ``` A breezy bossa nova for a lazy Sunday afternoon in Lisbon: nylon-string guitar, soft brushed snare, upright bass, a gentle flute line and a warm male and female duet sung in Portuguese. ``` ACE-Step v1.5 XL, sem créditos — "Domingo em Alfama" · 3:28 <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "A breezy bossa nova for a lazy Sunday afternoon in Lisbon: nylon-string guitar, soft brushed snare, upright bass, a gentle flute line and a warm male and female duet sung in Portuguese.", "model": "ace-step-1.5-xl", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-domingo-em-alfama-bossa-nova-from-prompt.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### A sua própria letra Duas estrofes, um pré-refrão, uma ponte e um final escritos por nós, com 210 segundos pedidos: ``` Style: cinematic indie pop ballad, felt piano, swelling strings, deep heartbeat kick, intimate female vocal that opens up into a soaring chorus, 72 bpm Lyrics: [Verse 1] We wrote our names on paper lanterns / Down by the river in July … [Chorus] Light it up and let it go / Every word I never said out loud … ``` ACE Music v1 — "Paper Lanterns" · 3:29 · gerada em 61 s <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "title": "Paper Lanterns", "style": "cinematic indie pop ballad, felt piano, swelling strings, deep heartbeat kick, intimate female vocal that opens up into a soaring chorus, 72 bpm", "lyrics": "[Verse 1]\nWe wrote our names on paper lanterns\nDown by the river in July\nYou said the wind would know the answer\nIf we just let the fire fly\nYour hand was shaking, mine was steady\nAt least that'\''s how I tell it now\nWe watched them climb until the city\nWas just a glow beneath the clouds\n\n[Pre-Chorus]\nSo every summer I come back here\nStrike a match and hold it near\n\n[Chorus]\nLight it up and let it go\nEvery word I never said out loud\nLight it up and let it go\nHigher than the both of us somehow\nAnd if it finds you anyhow\nTell me you can see it from the clouds\n\n[Verse 2]\nThey tore the old pier down last winter\nPut up a fence and painted lines\nBut I still know the way by heartbeat\nI find the water every time\nI keep a lighter in my pocket\nI keep your laugh inside my head\nI fold the paper like you showed me\nAnd write the things I should have said\n\n[Pre-Chorus]\nSo every summer I come back here\nStrike a match and hold it near\n\n[Chorus]\nLight it up and let it go\nEvery word I never said out loud\nLight it up and let it go\nHigher than the both of us somehow\nAnd if it finds you anyhow\nTell me you can see it from the clouds\n\n[Bridge]\nPaper and fire, paper and fire\nNothing this light should rise so high\nPaper and fire, paper and fire\nMaybe that'\''s how we say goodbye\n\n[Final Chorus]\nLight it up and let it go\nEvery word I never said out loud\nLight it up and let it go\nHigher than the both of us somehow\n\n[Outro]\nDown by the river in July", "model": "acemusic-v1", "duration": 210, "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-paper-lanterns-custom-lyrics.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Um instrumental: `instrumental: true`, 150 segundos, e sem vocais, coral nem violão: ``` Style: cinematic synthwave instrumental for a night drive: pulsing analog bass arpeggio, gated reverb drums, lush pads, a soaring lead synth melody, builds to a big final section, 108 bpm ``` ACE Music v1 — "Neon Overpass" · 2:29 · gerada em 46 s <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "title": "Neon Overpass", "style": "cinematic synthwave instrumental for a night drive: pulsing analog bass arpeggio, gated reverb drums, lush pads, a soaring lead synth melody, builds to a big final section, 108 bpm", "instrumental": true, "model": "acemusic-v1", "duration": 150, "negative": "vocals, choir, acoustic guitar", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-neon-overpass-synthwave-instrumental.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Letra em espanhol sobre uma festa num terraço durante um apagão: ``` Style: modern cumbia pop, bright accordion hooks, güira and congas, warm bass, a festive male lead with a crowd shouting the chorus, 98 bpm Lyrics: [Chorus] Bailando en la azotea / Con las estrellas de farol … ``` ACE Music v1 — "Bailando en la Azotea" · 2:32 · gerada em 46 s <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "title": "Bailando en la Azotea", "style": "modern cumbia pop, bright accordion hooks, güira and congas, warm bass, a festive male lead with a crowd shouting the chorus, 98 bpm", "lyrics": "[Verse 1]\nSe fue la luz en todo el barrio\nY nadie quiere irse a dormir\nDoña Rosa saca el radio viejo\nY la noche empieza a sonreír\nLos vecinos suben con sus sillas\nAlguien trae limones y café\nY la ciudad allá abajo, oscura\nNos mira bailar sin saber por qué\n\n[Pre-Chorus]\nSube, sube, que la luna está invitando\nSube, sube, que la calle está cantando\n\n[Chorus]\nBailando en la azotea\nCon las estrellas de farol\nQue se entere todo el mundo\nQue esta noche no hay apagón\nBailando en la azotea\nCon el corazón de tambor\nSi se apaga la ciudad entera\nAquí arriba sobra amor\n\n[Verse 2]\nEl abuelo saca la guitarra\nLa vecina de enfrente se animó\nLos niños corren entre las sábanas\nQue el viento de la tarde colgó\nNadie sabe cuándo vuelve la corriente\nY la verdad, a nadie le importó\nEsta fiesta no la paga nadie\nEsta fiesta la invitó el apagón\n\n[Chorus]\nBailando en la azotea\nCon las estrellas de farol\nQue se entere todo el mundo\nQue esta noche no hay apagón\nBailando en la azotea\nCon el corazón de tambor\nSi se apaga la ciudad entera\nAquí arriba sobra amor\n\n[Outro]\nQue esta noche no hay apagón", "model": "acemusic-v1", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-bailando-en-la-azotea-spanish-cumbia.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Letra do gerador de letras, estilo do gerador de estilos, cantada pelo ACE-Step: ``` Lyrics writer: A wistful country song about an old pickup truck that still has her mixtape stuck in the tape deck Style writer: classic country ballad, pedal steel, warm baritone ``` ACE-Step v1.5 XL, sem créditos — "Side B Forever" · 3:35 · gerada em 40 s, depois de 6 s para a letra e 4 s para o estilo <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music/lyrics' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "A wistful country song about an old pickup truck that still has her mixtape stuck in the tape deck", "style": "classic country ballad, pedal steel, warm baritone", "model": "ace-step-1.5-xl" }' > lyrics.json curl -X POST 'https://api.useapi.net/v1/acemusic/music/style' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "style": "classic country ballad, pedal steel, warm baritone", "model": "ace-step-1.5-xl" }' > style.json # sing what the writers returned jq -n --slurpfile l lyrics.json --slurpfile s style.json \ '{title: $l[0].title, lyrics: $l[0].lyrics, style: $s[0].style, model: "ace-step-1.5-xl", async: true}' | curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d @- ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-side-b-forever-lyrics-and-style-writers.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### ACE-Step com andamento, tom e compasso definidos Cada uma voltou exatamente com a duração pedida. ``` 3/4 · 84 bpm · D minor · 120 s · thinking 60 · avoid: trap drums, EDM, autotune Style: dark cabaret waltz, accordion, pizzicato strings, upright bass, brushed snare, theatrical female vocal ``` ACE-Step v1.5 XL, sem créditos — "Midnight Waltz" · 2:00 · gerada em 31 s <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "model": "ace-step-1.5-xl", "title": "Midnight Waltz", "style": "dark cabaret waltz, accordion, pizzicato strings, upright bass, brushed snare, theatrical female vocal", "lyrics": "[Verse 1]\nThe band plays slow when the lights go low\nAnd the chandeliers begin to sway\nTake my hand, we will dance till the candles stand\nIn puddles of yesterday\n\n[Chorus]\nOne, two, three, turn around with me\nRound and round till the morning comes\nOne, two, three, oh don'\''t let me be\nThe last one dancing when the music'\''s done\n\n[Verse 2]\nThe clock strikes twelve and it laughs at itself\nEvery mirror wears a stranger'\''s face\nHold me close, we are only ghosts\nWho forgot to leave this place\n\n[Chorus]\nOne, two, three, turn around with me\nRound and round till the morning comes\nOne, two, three, oh don'\''t let me be\nThe last one dancing when the music'\''s done", "bpm": 84, "timeSignature": "3/4", "key": "D minor", "duration": 120, "negative": "trap drums, EDM, autotune", "thinking": 60, "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-midnight-waltz-3-4-84-bpm-d-minor.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ``` 6/8 · 116 bpm · G major · 90 s · instrumental Style: lively celtic instrumental jig, fiddle and tin whistle trading the melody, bodhran, strummed bouzouki, foot stomps ``` ACE-Step v1.5 XL, sem créditos — "Harbour Jig" · 1:30 · gerada em 20 s <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "model": "ace-step-1.5-xl", "title": "Harbour Jig", "style": "lively celtic instrumental jig, fiddle and tin whistle trading the melody, bodhran, strummed bouzouki, foot stomps", "instrumental": true, "bpm": 116, "timeSignature": "6/8", "key": "G major", "duration": 90, "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-harbour-jig-6-8-116-bpm-g-major.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ``` 4/4 · 174 bpm · F minor · 150 s · thinking 80 Style: liquid drum and bass, rolling breakbeats, deep warm sub bass, airy pads, soulful female vocal ``` ACE-Step v1.5 XL, sem créditos — "Almost Home" · 2:30 · gerada em 41 s <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "model": "ace-step-1.5-xl", "title": "Almost Home", "style": "liquid drum and bass, rolling breakbeats, deep warm sub bass, airy pads, soulful female vocal", "lyrics": "[Verse]\nCity lights in the rear view mirror\nRunning on a borrowed night\nEvery bridge is a little bit nearer\nEvery tunnel full of light\n\n[Chorus]\nHold on, we'\''re almost home\nEvery signal turning green\nHold on, you'\''re not alone\nFaster than the in-between\n\n[Verse]\nRadio low and the windows open\nBreathing in the summer rain\nEvery promise we left unspoken\nRushing back to us again\n\n[Chorus]\nHold on, we'\''re almost home\nEvery signal turning green\nHold on, you'\''re not alone\nFaster than the in-between", "bpm": 174, "timeSignature": "4/4", "key": "F minor", "duration": 150, "thinking": 80, "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-almost-home-drum-and-bass-174-bpm-f-minor.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### Um cover, um remix e uma edição "Paper Lanterns" como cover, num estilo novo que mantém a melodia: ``` mode: cover · stripped-back acoustic folk cover, fingerpicked steel-string guitar, warm cello, soft close-mic'd male vocal ``` ACE Music v1.1 Preview — "Paper Lanterns (Acoustic Folk Cover)" · 3:34 · gerada em 72 s <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash # our script read the score first (free for an ACE Music v1 song; the API now does this by itself) curl 'https://api.useapi.net/v1/acemusic/music/score?songId=user%3A12345-example%40example.com-song%3Aso_4e7b2c9d0a5f4183b6d8e2c7' \ -H 'Authorization: Bearer user:12345-…' > /dev/null curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "mode": "cover", "model": "acemusic-v1.1", "references": ["user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7"], "style": "stripped-back acoustic folk cover, fingerpicked steel-string guitar, warm cello, soft close-mic'\''d male vocal", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-1-paper-lanterns-acoustic-folk-cover.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> "Bailando en la Azotea" como deep house. Não enviamos título, então o ACE Music a chamou de "Reference 1": ``` mode: remix · coverStrength 40 · remixStrength 50 · deep house remix, four-on-the-floor kick, plucky chords, rolling bassline, filtered vocal chops ``` ACE-Step v1.5 XL, sem créditos — "Reference 1" · 2:32 · gerada em 31 s <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "mode": "remix", "model": "ace-step-1.5-xl", "references": ["user:12345-example@example.com-song:so_9d3b7e2c1a6f4085b8e4d1c6"], "style": "deep house remix, four-on-the-floor kick, plucky chords, rolling bassline, filtered vocal chops", "coverStrength": 40, "remixStrength": 50, "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-bailando-en-la-azotea-house-remix.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> "Paper Lanterns" com letra nova entre os segundos 30 e 50, e o resto mantido: ``` mode: edit · start 30 · end 50 Lyrics: We wrote our names on paper lanterns / Down by the harbor in the snow / You said the stars would keep the answer / If we were brave enough to go ``` ACE-Step v1.5 XL, sem créditos — "Reference 1" · 3:29 · gerada em 41 s <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "mode": "edit", "model": "ace-step-1.5-xl", "references": ["user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7"], "start": 30, "end": 50, "style": "cinematic indie pop ballad, felt piano, swelling strings, intimate female vocal", "lyrics": "We wrote our names on paper lanterns\nDown by the harbor in the snow\nYou said the stars would keep the answer\nIf we were brave enough to go", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-paper-lanterns-edit-seconds-30-50.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### Mashups "Paper Lanterns" e "Let the 44 Roll By": ``` upbeat neo-soul pop mashup, punchy live drums, warm Rhodes and strings, female lead with a gospel-tinged choir on the chorus · audioInfluence 60 ``` ACE Music v1.1 Preview — "Lanterns at the Bus Stop" · 3:58 · gerada em 83 s <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash # our script read each song's score first (the API now does this by itself for ACE Music v1 songs) curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "mode": "mashup", "model": "acemusic-v1.1", "references": ["user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7", "user:12345-example@example.com-song:so_7c1d9e3a5b2f4806a4e1c9d3"], "title": "Lanterns at the Bus Stop", "style": "upbeat neo-soul pop mashup, punchy live drums, warm Rhodes and strings, female lead with a gospel-tinged choir on the chorus", "audioInfluence": 60, "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-1-mashup-lanterns-at-the-bus-stop.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> "Haul for the Harbor Light" e "Bailando en la Azotea", pedido no ACE Music v1: ``` festive celtic cumbia mashup, fiddle and accordion trading hooks, congas and bodhran, stomping kick, male lead with a big crowd chorus ``` ACE Music v1.1 Preview (pedido: v1) — "Harbor Fiesta" · 2:38 · gerada em 74 s <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash # our script read each song's score first (the API now does this by itself for ACE Music v1 songs) curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "mode": "mashup", "model": "acemusic-v1", "references": ["user:12345-example@example.com-song:so_2a8f6c1e9d4b47f3b0c5e8a2", "user:12345-example@example.com-song:so_9d3b7e2c1a6f4085b8e4d1c6"], "title": "Harbor Fiesta", "style": "festive celtic cumbia mashup, fiddle and accordion trading hooks, congas and bodhran, stomping kick, male lead with a big crowd chorus", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-1-mashup-harbor-fiesta-asked-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Três músicas de uma vez: "Paper Lanterns", "Bailando en la Azotea" e "Let the 44 Roll By": ``` warm late-night soul-pop medley, Rhodes and strings, light latin percussion, female lead with a male answer on the last chorus ``` ACE Music v1.1 Preview — "Three Songs, One Night" · 3:32 · gerada em 43 s <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash # our script read each song's score first (the API now does this by itself for ACE Music v1 songs) curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "mode": "mashup", "model": "acemusic-v1.1", "references": ["user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7", "user:12345-example@example.com-song:so_9d3b7e2c1a6f4085b8e4d1c6", "user:12345-example@example.com-song:so_7c1d9e3a5b2f4806a4e1c9d3"], "title": "Three Songs, One Night", "style": "warm late-night soul-pop medley, Rhodes and strings, light latin percussion, female lead with a male answer on the last chorus", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-1-mashup-three-songs-one-night.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### O seu áudio e as suas imagens A "Harbour Jig" de cima, enviada como MP3 e usada como referência de um prompt. O ACE Music rodou no v1.1 para manter a melodia: ``` A rowdy pub singalong with a big shouted chorus about the last ferry home, built on the tune of this recording ``` ACE Music v1.1 Preview (pedido: v1) — "Last Ferry Home" · 1:36 · gerada em 52 s <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/files?title=Harbour%20Jig%20demo' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: audio/mpeg' \ --data-binary @harbour-jig-demo.mp3 curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "A rowdy pub singalong with a big shouted chorus about the last ferry home, built on the tune of this recording", "model": "acemusic-v1", "references": ["user:12345-example@example.com-song:so_5f1a3c8e7b2d49a6c3e0f7b9"], "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-1-last-ferry-home-from-uploaded-jig.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### Stems de "Paper Lanterns" O vocal e o instrumental do `mode: "vocals"` (5 créditos), depois a bateria e as cordas, dois dos 9 stems do `mode: "all"` (60 créditos). <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music/stems' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "songId": "user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7", "mode": "vocals", "async": true }' curl -X POST 'https://api.useapi.net/v1/acemusic/music/stems' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "songId": "user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7", "mode": "all", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-paper-lanterns-stem-vocal.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-paper-lanterns-stem-instrumental.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-paper-lanterns-stem-drums.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-paper-lanterns-stem-strings.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ### Perguntas **Existe uma API do ACE Music?** Pela useapi.net, sim: a [API do ACE Music](/docs/api-acemusic-v1) roda o ACE Music v1, o ACE Music v1.1 Preview e o ACE-Step v1.5 XL via REST na sua conta do ACE Music, com covers, mashups, stems e MIDI. **Existe uma API gratuita do ACE-Step?** Pela useapi.net, sim: uma música do ACE-Step v1.5 XL não gasta créditos em nenhum plano do ACE Music, inclusive no Free, com configurações de andamento, tom, compasso e duração, remixes e edições. A acestep.io, de terceiros, só oferece a API do ACE-Step no plano Studio de $49 por mês, cerca de $0,14 por música (em novembro de 2026). **Quanto custa uma música do ACE Music v1 pela API?** Pela useapi.net, uma música do ACE Music v1 custa 2 créditos do seu plano do ACE Music: $0,013 no Artist com cobrança anual e $0,023 no Artist mensal, sem nada a mais por música. Veja [Preços](#pricing). **Existe um servidor MCP do ACE Music?** Pela useapi.net, sim, e ele faz mais que o servidor do próprio ACE Music em `acemusic.ai/mcp`: o [servidor MCP do ACE Music](/docs/api-acemusic-v1/mcp) hospedado acrescenta o modelo gratuito ACE-Step v1.5 XL, downloads de MP3 no plano Free, stems, covers, remixes, edições e mashups em uma só chamada, MusicXML e várias contas com um único token de API. O servidor do próprio ACE Music gera músicas v1 e v1.1 a partir da letra que o seu assistente escreve, e todo download exige um plano pago. Veja a [comparação](#useapinet-vs-ace-musics-own-mcp-server). ### Conclusão Um POST gera duas músicas no modelo que lidera o ranking vocal, as músicas do ACE-Step não custam nada, e toda música pode virar um cover, um mashup, stems ou um arquivo MIDI na chamada seguinte. Clone o [repositório `acemusic-api`](https://github.com/useapi/acemusic-api), rode o `songs-from-prompt/` com `--only 3` numa conta Free e veja o [POST /music](/docs/api-acemusic-v1/post-acemusic-music) para todas as opções. Visite o nosso <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> servidor no Discord</a> ou o <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> canal no Telegram</a> para qualquer dúvida de suporte. === URL: https://useapi.net/docs/articles/ace-music-api-tutorial-th === Document URL: https://useapi.net/docs/articles/ace-music-api-tutorial-th --- layout: default title: "วิธีสร้างเพลง AI ด้วย ACE Music API" description: "สร้างเพลงด้วย ACE Music v1, v1.1 และ ACE-Step v1.5 XL ที่ใช้ฟรี ผ่าน ACE Music API ของ useapi.net: พรอมต์ เนื้อเพลงของคุณเอง คัฟเวอร์ แมชอัป สเต็ม และ MIDI พร้อม curl และโค้ด" keywords: [ACE Music API, ACE Music v1 API, ACE-Step API, ACE-Step v1.5 XL, AI song generator API, text to music API, Suno alternative, AI music API, stems API, MIDI, MusicXML, mashup, cover song AI, MCP server, curl, tutorial, ACE Music API ภาษาไทย, API สร้างเพลง AI, สร้างเพลงด้วย AI, แต่งเพลง AI, คัฟเวอร์เพลง AI, แยกสเต็ม, ตัวอย่างโค้ด, คู่มือ] image: https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-paper-lanterns-cover-art.jpg parent: Articles nav_exclude: true lang: th translation_key: ace-music-tutorial date: 2026-11-14 last_modified: 2026-11-18 nav_order: 302 repo: https://github.com/useapi/acemusic-api --- ## วิธีสร้างเพลง AI ด้วย ACE Music API {: .no_toc #how-to-generate-ai-songs-with-the-ace-music-api } อ่าน 22 นาที • 14 พฤศจิกายน 2026 ## สารบัญ {: .no_toc .text-delta #table-of-contents } ### บทนำ [ACE Music API](/docs/api-acemusic-v1) ของ useapi.net เปลี่ยนการเรียก REST ครั้งเดียวให้เป็นเพลงที่เสร็จสมบูรณ์สองเพลงจาก [ACE Music](https://acemusic.ai) พร้อมเสียงร้อง เนื้อเพลง ชื่อเพลง และภาพปก โดยใช้แพ็กเกจ ACE Music ที่คุณมีอยู่แล้ว ACE Music v1 อยู่อันดับ 1 บน[ตารางอันดับโมเดลเพลงที่มีเสียงร้องของ Artificial Analysis](https://artificialanalysis.ai/music/leaderboard/vocals) นำหน้า Suno v6 ส่วน [ACE-Step](https://ace-step.github.io) v1.5 XL แบบโอเพนซอร์สก็ทำงานผ่าน API เดียวกัน โดยไม่ใช้เครดิตในทุกแพ็กเกจ ACE Music รวมถึงแพ็กเกจ Free คู่มือนี้เริ่มจากสามโมเดลและค่าใช้จ่ายต่อเพลง จากนั้นสร้างเพลงหนึ่งเพลงตั้งแต่ต้นจนจบด้วย `curl` แล้วสรุปฟีเจอร์อื่นทั้งหมดไว้ในตารางสั้นๆ ส่วน[ตัวอย่าง](#examples)ท้ายบทความคือเพลง 18 เพลงที่เราสร้างสำหรับหน้านี้ แต่ละเพลงแนบคำขอที่ใช้สร้างไว้ด้วย ทั้งหมดสร้างจากสคริปต์ใน [GitHub repo `acemusic-api`](https://github.com/useapi/acemusic-api) (Node.js และ Python) ใช้ไป 117 เครดิตของแพ็กเกจ Artist รวมเทคที่สร้างเพิ่มแล้ว useapi.net เป็น API ของ[บุคคลที่สาม](/docs/legal#affiliation--third-party-services) ไม่มีส่วนเกี่ยวข้องกับ ACE Music หรือ Timedomain ผู้พัฒนา ACE Music ### โมเดลและสิ่งที่ API ทำได้ ทุกคำขอสร้างเพลงสองเพลง และ `model` เป็นตัวกำหนดว่าโมเดลไหนเป็นผู้สร้าง: | โมเดล | `model` | ใช้ทำอะไร | การตั้งค่า | เครดิตต่อคำขอ | เวลาในการทดสอบของเรา | |---|---|---|---|---|---| | ACE Music v1 | `acemusic-v1` (ค่าเริ่มต้น) | โมเดลเสียงร้องอันดับ 1: เพลงจากพรอมต์หรือจากเนื้อเพลงของคุณ แบบมีเสียงร้องหรือบรรเลง | `duration` 30 ถึง 600 วินาที, `negative`, `styleInfluence`, ดาวน์โหลด WAV | 4 | 46 ถึง 89 วินาที | | ACE Music v1.1 Preview | `acemusic-v1.1` | เขียนโน้ตเพลง (score) ก่อน คัฟเวอร์และแมชอัปจึงตามทำนองของเพลงต้นทาง | `audioInfluence`, `styleInfluence` | 4 | 35 ถึง 83 วินาที | | ACE-Step v1.5 XL | `ace-step-1.5-xl` | โอเพนซอร์สโดย ACE Studio และ StepFun: เพลง รีมิกซ์ และการแก้ไข | `bpm`, `key`, `timeSignature`, `duration` 10 ถึง 240 วินาที, `negative`, `thinking` ได้ไฟล์ MP3 เท่านั้น | 0 | 20 ถึง 55 วินาที | สิ่งที่ทำได้กับโมเดลเหล่านี้: | สิ่งที่ทำ | คำขอ | หมายเหตุ | |---|---|---| | เพลงจากพรอมต์ | [POST /music](/docs/api-acemusic-v1/post-acemusic-music) `prompt` | ACE Music เขียนสไตล์ เนื้อเพลง และชื่อเพลงให้ | | เนื้อเพลงของคุณเอง เพลงบรรเลง | [POST /music](/docs/api-acemusic-v1/post-acemusic-music) `style`, `lyrics` | ภาษาใดก็ได้ | | ตัวช่วยเขียนเนื้อเพลงและสไตล์ | [POST /music/lyrics](/docs/api-acemusic-v1/post-acemusic-music-lyrics), [/music/style](/docs/api-acemusic-v1/post-acemusic-music-style) | ไม่ใช้เครดิต | | คัฟเวอร์ รีมิกซ์ แก้ไข แมชอัป | [POST /music](/docs/api-acemusic-v1/post-acemusic-music#modes) `mode` | ใช้กับเพลงใดก็ได้ในบัญชี | | ไฟล์เสียงและภาพของคุณ | [POST /files](/docs/api-acemusic-v1/post-acemusic-files) | ใช้เป็นข้อมูลอ้างอิงสำหรับเพลงใหม่ | | สเต็ม (stems) | [POST /music/stems](/docs/api-acemusic-v1/post-acemusic-music-stems) | Creator และ Artist | | ดาวน์โหลด โน้ตเพลง | [GET /music/download](/docs/api-acemusic-v1/get-acemusic-music-download), [/music/score](/docs/api-acemusic-v1/get-acemusic-music-score) | MP3 และโน้ตเพลงได้ทุกแพ็กเกจ ส่วน WAV, MIDI และ MusicXML ได้ใน Creator และ Artist | | ไลบรารี งาน บัญชี | [GET /music](/docs/api-acemusic-v1/get-acemusic-music), [/jobs](/docs/api-acemusic-v1/get-acemusic-jobs), [/accounts](/docs/api-acemusic-v1/get-acemusic-accounts-email) | ทุกเพลงในบัญชี งานที่กำลังทำงาน เครดิตแบบเรียลไทม์ | | MCP server | [`/v1/acemusic/mcp`](/docs/api-acemusic-v1/mcp) | 15 เครื่องมือสำหรับผู้ช่วย AI | ### ราคา ACE Music คิดเครดิตของตัวเองต่อคำขอจากแพ็กเกจ ACE Music ของคุณ และ useapi.net ไม่คิดเงินเพิ่มต่อเพลง (ข้อมูล ณ พฤศจิกายน 2026): | คำขอ | เครดิต | |---|---| | เพลงสองเพลงบน ACE Music v1 หรือ v1.1 | 4 | | สเต็ม เสียงร้อง + ดนตรี | 5, แพ็กเกจแบบชำระเงิน | | สเต็ม ทุกสเต็ม | 60, แพ็กเกจแบบชำระเงิน | | โน้ตเพลงของเพลง ACE-Step อ่านครั้งแรก | 1 | | เพลงสองเพลงบน ACE-Step v1.5 XL | 0 ในทุกแพ็กเกจ | | ตัวช่วยเขียนเนื้อเพลงและสไตล์ การอัปโหลด การดาวน์โหลด | 0 ในการทดสอบของเรา | [แพ็กเกจของ ACE Music](https://acemusic.ai/pricing/) มี Free ที่ได้ 20 เครดิตต่อวัน, Creator $9.90 ต่อเดือนสำหรับ 1,000 เครดิต และ Artist $29 ต่อเดือนสำหรับ 2,500 เครดิต หรือ $7.90 และ $16.58 ต่อเดือนเมื่อชำระรายปี หนึ่งเพลงคือครึ่งคำขอ เท่ากับ 2 เครดิต [ภาพรวม API](/docs/api-acemusic-v1#pricing) ก็มีตารางเดียวกันนี้ ค่าใช้จ่ายต่อหนึ่งเพลงในแต่ละแพ็กเกจ เรียงจากถูกที่สุดทางซ้าย (หนึ่งคำขอสร้างสองเพลง หนึ่งเพลงจึงใช้เครดิตครึ่งหนึ่งของคำขอ ข้อมูล ณ พฤศจิกายน 2026): | โมเดล | Free (20 cr/วัน) | Artist $16.58/เดือน (2,500 cr/เดือน, ชำระรายปี) | Creator $7.90/เดือน (1,000 cr/เดือน, ชำระรายปี) | Creator $9.90/เดือน (1,000 cr/เดือน) | Artist $29/เดือน (2,500 cr/เดือน) | |---|---|---|---|---|---| | ACE Music v1, v1.1 (หนึ่งเพลง) | $0 / 2 cr (10 เพลง/วัน) | $0.013 / 2 cr (1,250 เพลง/เดือน) | $0.016 / 2 cr (500 เพลง/เดือน) | $0.020 / 2 cr (500 เพลง/เดือน) | $0.023 / 2 cr (1,250 เพลง/เดือน) | | สเต็ม (เสียงร้อง + ดนตรี) | แพ็กเกจเสียเงิน | $0.033 / 5 cr | $0.040 / 5 cr | $0.050 / 5 cr | $0.058 / 5 cr | | สเต็ม (ทุกสเต็ม) | แพ็กเกจเสียเงิน | $0.40 / 60 cr | $0.47 / 60 cr | $0.59 / 60 cr | $0.70 / 60 cr | | โน้ตเพลง ACE-Step (อ่านครั้งแรก) | $0 / 1 cr | $0.007 / 1 cr | $0.008 / 1 cr | $0.010 / 1 cr | $0.012 / 1 cr | | ACE-Step v1.5 XL (หนึ่งเพลง) | $0 / 0 cr | $0 / 0 cr | $0 / 0 cr | $0 / 0 cr | $0 / 0 cr | เทียบกับช่องทางอื่นในการเรียกโมเดลเหล่านี้จากโค้ด: | โมเดล | useapi.net | API อื่น | |---|---|---| | ACE Music v1, v1.1 Preview | เริ่มต้น $0.013 ต่อเพลงบน Artist แบบชำระรายปี และ $0 ด้วยเครดิตรายวัน 20 เครดิตของแพ็กเกจ Free | — | | ACE-Step v1.5 XL | $0 ในทุกแพ็กเกจ ACE Music รวมถึงแพ็กเกจ Free | ประมาณ $0.14 ต่อเพลงบน API ของ [acestep.io](https://acestep.io/pricing) ซึ่งเป็นบุคคลที่สาม และต้องใช้แพ็กเกจ Studio $49 ต่อเดือน | ในทุกแพ็กเกจ ACE Music รวมถึงแพ็กเกจ Free เพลง ACE-Step v1.5 XL ไม่ใช้เครดิตเลย เทียบกับ API ของ acestep.io ซึ่งเป็นบุคคลที่สาม ที่ต้องใช้แพ็กเกจ Studio $49 ต่อเดือน (ประมาณ 360 เพลงต่อเดือน ราว $0.14 ต่อเพลง ข้อมูล ณ พฤศจิกายน 2026) ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. ### วิธีสร้างเพลงด้วย curl คุณต้องมี API token ของ useapi.net ดูที่ [ตั้งค่า useapi.net](/docs/start-here/setup-useapi) และบัญชี [ACE Music](https://acemusic.ai) ที่มีอีเมลและรหัสผ่าน [การสมัครสมาชิกเดือนละ $15](/docs/subscription) ครั้งเดียวครอบคลุมทุก API ของ useapi.net และบัญชี ACE Music 3 บัญชี บัญชี ACE Music แบบ Free ก็ใช้ได้ เพราะได้ 20 เครดิตต่อวัน และเพลง ACE-Step ไม่ใช้เครดิตเลย คำสั่งด้านล่างใช้ [jq](https://jqlang.org) ในการอ่าน JSON #### เพิ่มบัญชี ACE Music ของคุณ export token ก่อน แล้วเพิ่มบัญชีเพียงครั้งเดียว API จะล็อกอิน อ่านข้อมูลบัญชี และจัดเก็บบัญชีไว้ก็ต่อเมื่อ ACE Music ยอมรับรหัสผ่านเท่านั้น: ```bash export USEAPI_TOKEN="user:12345-..." API=https://api.useapi.net/v1/acemusic curl -s -X POST "$API/accounts" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "example@example.com", "password": "your-acemusic-password" }' ``` บัญชีที่สร้างด้วย Continue with Google หรือด้วยหมายเลขโทรศัพท์ต้องตั้งรหัสผ่านก่อน ดูที่ [ตั้งค่า ACE Music](/docs/start-here/setup-acemusic) ซึ่งเพิ่มบัญชีให้คุณได้ด้วย #### สร้างเพลงจากพรอมต์ บรรยายเพลงด้วยคำพูดของคุณเอง ACE Music จะเขียนสไตล์ เนื้อเพลง และชื่อเพลง แล้วสร้างเพลงสองเพลง นี่คือคำขอจริงที่ใช้สร้างเพลงแรกในหน้านี้: ```bash curl -s -X POST "$API/music" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A late-night neo-soul slow jam about two strangers sharing an umbrella at a bus stop in the rain and missing the last bus on purpose. Warm Rhodes piano, brushed drums, round upright bass, a smoky female lead with close three-part harmonies on the chorus.", "model": "acemusic-v1", "async": true }' | tee job.json | jq '{jobid, status, model}' ``` เมื่อตั้ง `async: true` API จะตอบ `201` พร้อมข้อมูลงานทันที พรอมต์ยาวได้สูงสุด 2,000 ตัวอักษร และแนบเพลงอ้างอิงได้สูงสุด 3 เพลงกับภาพได้สูงสุด 3 ภาพ ดูที่ [กำหนดทิศทางเพลงด้วยไฟล์เสียงและภาพของคุณเอง](#guide-songs-with-your-own-audio-and-images) #### สิ่งที่ได้กลับมา ระหว่างที่ ACE Music เขียนเนื้อเพลง เพลงจะอยู่ในสถานะ `planning` และมีชื่อ `Untitled` จากนั้นเปลี่ยนเป็น `queued` และ `running` ให้โพล [GET /jobs/`jobid`](/docs/api-acemusic-v1/get-acemusic-jobs-jobid) ทุกราว 10 วินาที `jobid` มีอักขระ `:` และ `@` จึงต้อง URL-encode ก่อน: ```bash curl -s "$API/jobs/$(jq -r .jobid job.json | jq -Rr @uri)" \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{status, songs: [.songs[] | {title, status, duration, audioUrl}]}' ``` เมื่อ `status` เป็น `completed` แต่ละเพลงจะมีลิงก์ของตัวเอง (id ด้านล่างเป็นค่าสมมติ): ```json { "jobid": "j1115003713275918262m-u12345-email:example@example.com-task:so_7c1d9e3a5b2f4806a4e1c9d3.so_8b4f2e6a1c9d47e5a3b7c0d2-bot:acemusic", "type": "music", "status": "completed", "email": "example@example.com", "created": "2026-11-15T00:37:13.275Z", "model": "acemusic-v1", "modelUsed": "acemusic-v1", "songs": [ { "songId": "user:12345-example@example.com-song:so_7c1d9e3a5b2f4806a4e1c9d3", "taskId": "so_7c1d9e3a5b2f4806a4e1c9d3", "status": "succeeded", "title": "Let the 44 Roll By", "model": "acemusic-v1", "style": "Late-night neo-soul slow jam with a laid-back 1990s and early 2000s pocket, 72 BPM. …", "lyrics": "[Intro - Warm Rhodes chords, brushed snare rim clicks, subtle rain on asphalt]\n\n[Verse 1 …]\nWater dripping off the canvas seam\n…", "instrumental": false, "duration": 277.19, "audioUrl": "https://acemusic.ai/data/so_7c1d9e3a5b2f4806a4e1c9d3.mp3", "playUrl": "https://….r2.cloudflarestorage.com/acemusic-data-prod/users/…/audio/202611/….mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20261115T003902Z&X-Amz-Expires=3599&…", "playUrlExpires": "2026-11-15T01:39:01.000Z", "coverUrl": "https://acemusic.ai/data/so_7c1d9e3a5b2f4806a4e1c9d3-cover.jpg?v=1794703081642", "pageUrl": "https://acemusic.ai/song/r4k8w2n6p9tz", "created": "2026-11-15T00:37:13.300Z", "finished": "2026-11-15T00:38:42.208Z", "kind": "original", "score": false }, { "songId": "user:12345-example@example.com-song:so_8b4f2e6a1c9d47e5a3b7c0d2", "title": "Let the 44 Roll By", "duration": 253.99, "…": "…" } ], "completed": "2026-11-15T00:38:42.208Z" } ``` - `audioUrl` คือลิงก์ MP3 สาธารณะของเพลง และไม่มีวันเปลี่ยน ส่วน `playUrl` เป็นลิงก์ตรงไปยัง MP3 ไฟล์เดียวกันสำหรับเครื่องเล่นบนเว็บ ใช้ได้จนถึงเวลา `playUrlExpires` (ประมาณหนึ่งชั่วโมง) เพราะบางเบราว์เซอร์ เช่น Brave บล็อกการ redirect ที่อยู่เบื้องหลัง `audioUrl` - `songId` คือค่าที่คัฟเวอร์ แมชอัป สเต็ม การดาวน์โหลด และโน้ตเพลงต้องใช้ ค่านี้ระบุบัญชีที่เพลงนั้นอยู่ การเรียกเหล่านั้นจึงทำงานบนบัญชีนั้น - `model` คือโมเดลที่คุณขอ ส่วน `modelUsed` คือโมเดลที่ทำงานจริง (ดู[แมชอัป](#mash-up-two-or-three-songs)) `kind` เป็น `original`, `cover`, `edit`, `mashup` หรือ `upload` และ `score` บอกว่าเพลงนั้นมีโน้ตเพลงแล้วหรือยัง - เพลงที่ ACE Music สร้างไม่สำเร็จจะมี `status: "failed"` พร้อมเหตุผลของ ACE Music ใน `error` และ `refunded: true` เมื่อได้เครดิตคืนแล้ว และนี่คือเพลงแรกจากสองเพลงนั้น: ACE Music v1 — "Let the 44 Roll By" · 4:37 · สร้างใน 89 วินาที <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-let-the-44-roll-by-neo-soul-from-prompt.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### แบบ sync, async และ webhook | สิ่งที่คุณส่ง | การตอบกลับของ POST | ขั้นต่อไป | |---|---|---| | `async: true` | `201` ทันที พร้อมข้อมูลงาน | โพล [GET /jobs/`jobid`](/docs/api-acemusic-v1/get-acemusic-jobs-jobid) | | ไม่ส่ง `async` | `200` พร้อมงานที่เสร็จแล้ว เป็น JSON แบบเดียวกับด้านบน | อ่านเพลงจากการตอบกลับ คำขอที่ยังทำงานอยู่หลัง 100 วินาทีจะตอบ `202` พร้อมข้อมูลงาน ให้โพลต่อ | | `replyUrl` และ `replyRef` | เหมือนด้านบน ทั้งแบบ sync และ async | URL `https` สาธารณะของคุณจะได้รับ `POST` หนึ่งครั้งพร้อมงานที่เสร็จแล้ว โดยมี `replyRef` ของคุณอยู่ข้างใน | คำขอ ACE-Step ของเราที่ไม่ได้ส่ง `async` ตอบกลับมาใน 37 วินาที และ webhook มาถึง 12 วินาทีหลังเพลงเสร็จ อ่านข้อมูลงานได้นาน 7 วัน และงานที่ยังทำงานอยู่ 30 นาทีหลังเริ่มจะล้มเหลวด้วย `504` ตัวอย่าง [`async-webhooks/`](https://github.com/useapi/acemusic-api/tree/main/async-webhooks) รันครบทั้งสามแบบ และมีตัวรับ webhook ขนาดเล็กมาให้ด้วย <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash curl -s -X POST "$API/music" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A dreamy lo-fi hip hop beat for studying late at night: dusty vinyl crackle, mellow Rhodes chords, a soft upright bass and rain on the window", "model": "ace-step-1.5-xl", "replyUrl": "https://your-server.example.com/acemusic-hook", "replyRef": "lofi-1" }' | jq '{status, songs: [.songs[] | {title, duration, audioUrl}]}' ``` </details> ### ร้องเนื้อเพลงของคุณเอง ส่ง `style` และ `lyrics` แทน `prompt` แล้ว ACE Music จะร้องคำของคุณในสไตล์ที่คุณกำหนด: | ฟิลด์ | หน้าที่ | ข้อจำกัด | |---|---|---| | `style` | แนวเพลง เครื่องดนตรี อารมณ์ จังหวะ และเสียงร้อง | 1,000 ตัวอักษร, 512 บน ACE-Step | | `lyrics` | คำของคุณ ภาษาใดก็ได้ พร้อมแท็ก `[Verse]`, `[Chorus]`, `[Bridge]` | 5,000 ตัวอักษร, 2,000 บน ACE-Step | | `title` | ชื่อของเพลง ถ้าไม่ส่ง ACE Music จะตั้งให้ | 80 ตัวอักษร | | `instrumental` | `true` สำหรับเพลงไม่มีเสียงร้อง ส่ง `style` โดยไม่มี `lyrics` ก็ได้ผลเหมือนกัน | | | `duration` | ความยาวเป็นวินาที | 30 ถึง 600 บน ACE Music v1, 10 ถึง 240 บน ACE-Step | | `negative` | สไตล์ที่ไม่ต้องการ | 200 ตัวอักษร, ACE Music v1 และ ACE-Step | | `styleInfluence` | ความเคร่งครัดในการทำตามสไตล์ | `0` ถึง `100`, ค่าเริ่มต้น `80`, ACE Music v1 และ v1.1 | อย่าส่ง `prompt` พร้อมกับฟิลด์เหล่านี้ เพราะ API จะตอบ `400` และบอกว่าต้องเอาฟิลด์ไหนออก เพลงบัลลาดของเราที่ขอ `duration: 210` ได้กลับมายาว 210 และ 209 วินาที เพลงนี้อยู่ใน[ตัวอย่าง](#your-own-lyrics) พร้อมเพลงบรรเลงและเพลงภาษาสเปน ยังไม่มีเนื้อเพลง? [POST /music/lyrics](/docs/api-acemusic-v1/post-acemusic-music-lyrics) เขียนเนื้อเพลงและชื่อเพลงจากคำขอของคุณ และ [POST /music/style](/docs/api-acemusic-v1/post-acemusic-music-style) ขยายคำไม่กี่คำให้เป็นสไตล์เต็มรูปแบบ ของเราได้ผลกลับมาใน 6 และ 4 วินาที โดยไม่เสียเครดิต สคริปต์: [`custom-lyrics/`](https://github.com/useapi/acemusic-api/tree/main/custom-lyrics) ### กำหนดจังหวะ คีย์ และอัตราจังหวะด้วย ACE-Step ACE-Step v1.5 XL รับการตั้งค่าทางดนตรีที่โมเดล ACE Music ไม่รับ และเพลงของมันไม่ใช้เครดิต: | ตัวเลือก | ค่า | |---|---| | `bpm` | `30` ถึง `200` | | `timeSignature` | `2/4`, `3/4`, `4/4`, `6/8` | | `key` | `C major` ถึง `B minor` (C, C#, D, Eb, E, F, F#, G, Ab, A, Bb, B) | | `duration` | `10` ถึง `240` วินาที | | `negative` | สไตล์ที่ไม่ต้องการ สูงสุด 200 ตัวอักษร | | `thinking` | `0` ถึง `100`: ACE-Step วางแผนทั้งเพลงก่อน ค่าต่ำจะสร้างสรรค์กว่า ค่าสูงจะสม่ำเสมอกว่า | เพลง ACE-Step ทั้งสามเพลงของเรา คือวอลซ์ 3/4 จิก 6/8 และดรัมแอนด์เบส 174 bpm ได้ความยาวตรงตามที่ขอทุกเพลง ([ตัวอย่าง](#ace-step-at-a-set-tempo-key-and-meter)) ตัวเลือกเหล่านี้ใช้ได้เฉพาะใน `mode` `generate` บน `ace-step-1.5-xl` เท่านั้น ถ้าใช้ที่อื่น API จะตอบ `400 Parameter bpm does not apply to mode generate on acemusic-v1` สคริปต์: [`ace-step-options/`](https://github.com/useapi/acemusic-api/tree/main/ace-step-options) ### คัฟเวอร์ รีมิกซ์ และการแก้ไข `mode` เปลี่ยนคำขอให้เป็นงานบนเพลงที่คุณมีอยู่ `references` รับ `songId` ของเพลงเหล่านั้น ได้แก่ เพลงที่ API สร้าง เพลงจาก[ไลบรารี](#your-library) หรือไฟล์ที่คุณอัปโหลดเอง | `mode` | `references` | ทำงานบน | เครดิต | หน้าที่ | |---|---|---|---|---| | `cover` | 1 เพลง | `acemusic-v1.1` หรือ ACE-Step บน `ace-step-1.5-xl` | 4 / 0 | เพลงเดิมใน `style` ใหม่ โดยตามทำนอง คอร์ด และโครงสร้างของเพลง | | `remix` | 1 เพลง | `ace-step-1.5-xl` | 0 | `coverStrength` คงต้นฉบับไว้ ส่วน `remixStrength` พาออกห่างจากต้นฉบับ (`0` ถึง `100`) | | `edit` | 1 เพลง | `ace-step-1.5-xl` | 0 | เขียนช่วงระหว่างวินาที `start` ถึง `end` ใหม่ด้วย `lyrics` ใหม่ และคงส่วนที่เหลือไว้ | | `mashup` | 2 หรือ 3 เพลง | `acemusic-v1.1` | 4 | เพลงใหม่หนึ่งเพลงจากหลายเพลง ดูด้านล่าง | ACE Music v1.1 ตามทำนองที่อ่านได้จากโน้ตเพลงของเพลงต้นทาง คัฟเวอร์แรกของเราจากเพลง ACE Music v1 ที่ยังไม่มีโน้ตเพลงล้มเหลวด้วย `ref_no_melody` และได้ 4 เครดิตคืน ตอนนี้ API จึงอ่านโน้ตเพลงของเพลง ACE Music v1 ก่อนโดยไม่เสียค่าใช้จ่าย ก่อนทำคัฟเวอร์หรือแมชอัปด้วย v1.1 ส่วนเพลง ACE-Step จะไม่ถูกอ่านโดยอัตโนมัติ ถ้าเพลงใดตอบ `400` พร้อม `ref_no_melody` ให้เรียก [GET /music/score](#read-the-score) กับเพลงนั้นก่อน (1 เครดิต) แล้วส่งคำขออีกครั้ง สคริปต์: [`covers-remix-edit/`](https://github.com/useapi/acemusic-api/tree/main/covers-remix-edit) #### แมชอัปสองหรือสามเพลง `mode: "mashup"` สร้างเพลงหนึ่งเพลงจาก 2 หรือ 3 เพลงในบัญชีเดียวกัน โดยผสมเนื้อเพลงของทุกเพลงเข้าด้วยกัน เว้นแต่คุณจะส่ง `lyrics` มาเอง `audioInfluence` (0 ถึง 100 ค่าเริ่มต้น 60) กำหนดว่าจะตามเพลงต้นทางใกล้แค่ไหน แมชอัปต้องอ่านเพลงต้นทาง จึงทำงานบน ACE Music v1.1 Preview แม้คุณจะขอ v1 เหมือนกับบนเว็บไซต์ ACE Music เพลง "Harbor Fiesta" ของเรารายงาน `"model": "acemusic-v1"` และ `"modelUsed": "acemusic-v1.1"` และเครดิตคิดตามโมเดลที่ทำงานจริง แบบเดียวกันนี้เกิดกับ `cover` ที่ขอบน v1, พรอมต์ที่มีเพลงอ้างอิงมากกว่าหนึ่งเพลงบน ACE-Step และบางครั้งกับพรอมต์ที่มีเพลงอ้างอิง สคริปต์: [`mashup/`](https://github.com/useapi/acemusic-api/tree/main/mashup) ### กำหนดทิศทางเพลงด้วยไฟล์เสียงและภาพของคุณเอง [POST /files](/docs/api-acemusic-v1/post-acemusic-files) รับไฟล์เป็น body ดิบของคำขอ พร้อม `Content-Type` ของไฟล์: | อัปโหลด | รูปแบบ | สูงสุด | สิ่งที่ได้ | ใช้เป็น | |---|---|---|---|---| | เสียง | MP3, WAV, FLAC, OGG, M4A, AAC | 100 MB, 8 นาที | `songId`: เพลงในไลบรารี ที่ ACE Music ถอดเนื้อเพลง สไตล์ จังหวะ และทำนองไว้แล้ว | หนึ่งใน `references` สูงสุด 3 รายการของพรอมต์ หรือเพลงที่จะคัฟเวอร์ รีมิกซ์ แก้ไข หรือแมชอัป | | ภาพ | JPEG, PNG, WebP | 10 MB | `mediaId` | หนึ่งใน `images` สูงสุด 3 ภาพของพรอมต์: ACE Music จะแต่งเพลงเกี่ยวกับภาพนั้น | ```bash curl -s -X POST "$API/files?title=Harbour%20Jig%20demo" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: audio/mpeg" \ --data-binary @harbour-jig-demo.mp3 | jq '{songId, status, duration, bpm: .upload.bpm}' ``` ไฟล์ "Harbour Jig" ยาว 90 วินาทีที่เราอัปโหลดถูกถอดเสร็จใน 14 วินาที และ ACE Music ได้ยินเป็น 115 bpm (เราขอไว้ 116) ภาพหุ่นยนต์กำลังเต้นกลายเป็นเพลงดรัมแอนด์เบสเกี่ยวกับขนสีเขียวอมฟ้า (teal) และรองเท้าหุ้มข้อสีส้มของมัน ทั้งสองอยู่ใน[ตัวอย่าง](#your-audio-and-pictures) การอัปโหลดนับรวมในโควตาของบัญชี คือเสียง 10 นาทีบน Free, 30 นาทีบน Creator และ 60 นาทีบน Artist สคริปต์: [`upload-reference/`](https://github.com/useapi/acemusic-api/tree/main/upload-reference) ### สเต็ม การดาวน์โหลด และโน้ตเพลง ทุกเพลงที่เสร็จแล้วแยกสเต็ม ดาวน์โหลด และอ่านเป็นโน้ตเพลงได้: | คำขอ | แพ็กเกจ | เครดิต | สิ่งที่ได้ | |---|---|---|---| | [สเต็ม](/docs/api-acemusic-v1/post-acemusic-music-stems), `mode: "vocals"` | Creator, Artist | 5 | MP3 ของ `vocal` และ `instrumental` | | [สเต็ม](/docs/api-acemusic-v1/post-acemusic-music-stems), `mode: "all"` | Creator, Artist | 60 | ทุกสเต็มที่ ACE Music แยกได้ เป็น MP3 | | [ดาวน์โหลด](/docs/api-acemusic-v1/get-acemusic-music-download) `mp3` (ค่าเริ่มต้น) | ทุกแพ็กเกจ | 0 | `url` (เหมือน `audioUrl`) และ `playUrl` | | ดาวน์โหลด `wav` | Creator, Artist | 0 | ลิงก์ที่ใช้ได้ 24 ชั่วโมง ไม่รองรับเพลง ACE-Step | | ดาวน์โหลด `midi`, `musicxml` | Creator, Artist | 0 | ตัวไฟล์โดยตรง | | [โน้ตเพลง](/docs/api-acemusic-v1/get-acemusic-music-score) | ทุกแพ็กเกจ | 0, หรือ 1 สำหรับเพลง ACE-Step ในครั้งแรก | [สัญกรณ์ ABC](https://abcnotation.com): ทำนองร้อง แนวดนตรีหนึ่งแนว คอร์ด และท่อนต่างๆ | #### แยกเพลงเป็นสเต็ม การแยกเสียงร้องของ "Paper Lanterns" ใช้เวลาราว 80 วินาที และการแยกเต็มรูปแบบใช้ไม่ถึง 2 นาที ได้ 9 สเต็ม ได้แก่ เสียงร้อง เสียงประสาน กลอง เบส กีตาร์ คีย์บอร์ด เครื่องสาย ซินธ์ และเอฟเฟกต์ ([ฟัง](#stems-of-paper-lanterns)) ลิงก์สเต็มใช้ได้ 24 ชั่วโมง จึงต้องอ่านเพลงอีกครั้งเพื่อรับลิงก์ใหม่ การแยกเพลงซ้ำในโหมดเดิมจะตอบทันทีและไม่คิดเครดิต #### ดาวน์โหลด MP3, WAV, MIDI และ MusicXML ACE Music สร้าง WAV, MIDI และ MusicXML เมื่อมีคำขอครั้งแรก API จะรอได้สูงสุดหนึ่งนาที แล้วตอบ `202` ให้เรียกอีกครั้งในอีกหนึ่งนาที สำหรับ "Paper Lanterns" ทั้งสามไฟล์พร้อมภายในไม่กี่วินาที ได้แก่ WAV ขนาด 40 MB, ไฟล์ MIDI ขนาด 8 KB และโน้ตเพลง MusicXML ขนาด 107 KB <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash SONG="user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7" curl -s -G "$API/music/download" --data-urlencode "songId=$SONG" -d format=wav \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{url, expires}' curl -s -G "$API/music/download" --data-urlencode "songId=$SONG" -d format=midi \ -H "Authorization: Bearer $USEAPI_TOKEN" -o paper-lanterns.mid ``` </details> #### อ่านโน้ตเพลง เครื่องมือ ABC ใดก็ได้แปลงโน้ตเพลงนี้เป็นแผ่นโน้ตได้ สำหรับ "Paper Lanterns" อ่านได้ 72 bpm ตรงกับจังหวะที่เราขอไว้ในสไตล์ เพลง ACE Music v1.1 มาพร้อมโน้ตเพลงของตัวเอง และคัฟเวอร์กับแมชอัปของ v1.1 จะตามโน้ตเพลงนั้น ดูที่ [คัฟเวอร์ รีมิกซ์ และการแก้ไข](#covers-remixes-and-edits) <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash SONG="user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7" curl -s -G "$API/music/score" --data-urlencode "songId=$SONG" \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq -r .abc | head -14 ``` ``` X:1 T: M:2/4 L:1/16 Q:1/4=72 V: Vocal clef=treble name="Vocal Melody" snm="Vocal" V: Ins clef=treble name="Ins Melody" snm="Inst." K:Ab % intro V: Vocal Z|"Ab"z8|"Ab"z8|"Ab"z8| V: Ins Z|Ac2AcBA2|A2EAA2EA|Ac2AcBA2| ``` </details> สคริปต์: [`stems-and-downloads/`](https://github.com/useapi/acemusic-api/tree/main/stems-and-downloads) ซึ่งบันทึกสเต็ม ไฟล์ดาวน์โหลดทุกรูปแบบ และโน้ตเพลง ### ไลบรารีของคุณ ทุกเพลงและทุกไฟล์ที่อัปโหลดในบัญชี ไม่ว่าจะสร้างที่นี่หรือบน acemusic.ai จะอยู่ในไลบรารีของบัญชีจนกว่าจะถูกลบ: | คำขอ | หน้าที่ | |---|---| | [GET /music](/docs/api-acemusic-v1/get-acemusic-music) | เพลงหนึ่งหน้า เรียงจากใหม่ไปเก่า พร้อม `next` สำหรับหน้าถัดไป ต้องส่ง `email` เมื่อมีมากกว่าหนึ่งบัญชี เพลงของงานที่เก่ากว่า 7 วันก็อยู่ที่นี่ | | [GET /music/`songId`](/docs/api-acemusic-v1/get-acemusic-music-songid) | เพลงหนึ่งเพลงพร้อมลิงก์ใหม่ และสเต็มของเพลงถ้าเคยแยกไว้ | | [DELETE /music/`songId`](/docs/api-acemusic-v1/delete-acemusic-music-songid) | `204`: เพลงถูกย้ายไปถังขยะของบัญชีบน acemusic.ai และหลังจากนั้น API จะตอบ `404` สำหรับเพลงนั้น | <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash SONG="user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7" curl -s -G "$API/music" --data-urlencode "email=example@example.com" -d limit=20 \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{next, songs: [.songs[] | {title, model, kind, songId}]}' curl -s "$API/music/$(jq -rn --arg v "$SONG" '$v|@uri')" \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{title, score, audioUrl, playUrl, stems: (.stems // {} | keys)}' curl -s -o /dev/null -w "%{http_code}\n" -X DELETE "$API/music/$(jq -rn --arg v "$SONG" '$v|@uri')" \ -H "Authorization: Bearer $USEAPI_TOKEN" ``` </details> สคริปต์: [`library/`](https://github.com/useapi/acemusic-api/tree/main/library) ### ใช้หลายบัญชี ACE Music การสมัครสมาชิก useapi.net แต่ละรายการเชื่อมบัญชี ACE Music ได้ 3 บัญชี รวมสูงสุด 100 บัญชี คำขอที่ไม่ระบุ `email` จะไปที่บัญชีที่ใช้งานได้ปกติและมีช่องว่าง ส่วนคำขอที่อ้างถึงเพลง ไฟล์อัปโหลด หรือภาพ จะทำงานบนบัญชีที่สิ่งนั้นอยู่ บัญชีหนึ่งรันคำขอพร้อมกันได้สูงสุด `maxJobs` รายการ ค่าเริ่มต้นคือ 4 ซึ่งเป็นขีดจำกัดของ ACE Music เอง การสมัครสมาชิก $15 หนึ่งรายการรันคำขอสร้างเพลงพร้อมกันได้สูงสุด 12 รายการ (3 บัญชี × บัญชีละ 4) และแต่ละคำขอสร้างเพลงสองเพลง จึงสร้างเพลง 24 เพลงพร้อมกัน ไม่ว่าจะบน ACE Music v1 หรือบน ACE-Step v1.5 XL ซึ่งไม่ใช้เครดิต เมื่อทุกบัญชีไม่ว่าง API จะตอบ `429` พร้อม `Retry-After` และถ้า ACE Music ปฏิเสธรหัสผ่าน บัญชีนั้นจะตอบ `596` จนกว่าคุณจะเพิ่มบัญชีอีกครั้ง [GET /accounts/`email`](/docs/api-acemusic-v1/get-acemusic-accounts-email) อ่านแพ็กเกจ เครดิต และอัตราเครดิตแบบเรียลไทม์ และ [POST /accounts](/docs/api-acemusic-v1/post-acemusic-accounts) ที่ส่งแค่ `email` กับ `maxJobs` จะเปลี่ยนเฉพาะ `maxJobs` สคริปต์: [`accounts/`](https://github.com/useapi/acemusic-api/tree/main/accounts) <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash curl -s "$API/accounts/$(jq -rn --arg v "example@example.com" '$v|@uri')" \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{plan_name, credits, maxJobs, costs}' curl -s -X POST "$API/accounts" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "example@example.com", "maxJobs": 2 }' ``` </details> ### ใช้จาก Claude, ChatGPT หรือ Cursor (MCP) ฟีเจอร์ทั้งหมดนี้มีให้ใช้เป็น [MCP server](/docs/api-acemusic-v1/mcp) แบบโฮสต์ที่มี 15 เครื่องมือ ตั้งแต่เพลง คัฟเวอร์ และแมชอัป ไปจนถึงสเต็ม โน้ตเพลง และการอัปโหลด ใน Claude Code ใช้คำสั่งเดียว: ```bash claude mcp add --transport http useapi-acemusic https://api.useapi.net/v1/acemusic/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` Cursor, VS Code และ Windsurf ใช้ URL และ header เดียวกัน ส่วนแอป Claude และ ChatGPT ล็อกอินด้วย OAuth ดูที่ [ใช้ในแอป Claude หรือ ChatGPT](/docs/api-acemusic-v1/mcp#use-it-in-the-claude-app-or-chatgpt) จากนั้นสั่งด้วยภาษาธรรมดาได้เลย เช่น "Write lyrics about a cat who loves rainy days and sing them as acoustic indie folk on ACE Music v1" #### useapi.net เทียบกับ MCP server ของ ACE Music เอง ACE Music también tiene su propio servidor MCP en `https://acemusic.ai/mcp`. Crea canciones de ACE Music v1 y v1.1 a partir del estilo y la letra que escribe tu asistente. El servidor de useapi.net funciona con la misma cuenta de ACE Music y agrega todo lo demás (al 18 de noviembre de 2026): | | MCP de ACE Music de useapi.net | MCP propio de ACE Music | |---|---|---| | ACE-Step v1.5 XL, 0 créditos en todos los planes | Sí | No, solo ACE Music v1 y v1.1 | | Descarga de MP3 en el plan Free | Sí | No, toda descarga requiere un plan de pago | | Covers, remixes, ediciones y mashups | Una llamada para cada uno, a partir de tus canciones | El asistente los arma a partir de una partitura transcrita | | Stems: voz e instrumental, o cada instrumento | Sí | No | | Partituras MusicXML | Sí | No, solo MIDI | | Estilo, letra y título escritos por ACE Music a partir de una idea de una línea | Sí | No, los escribe el asistente | | Varias cuentas de ACE Music en una sola conexión | Sí | Una cuenta por conexión | | Token de API para scripts, n8n y agentes sin interfaz, además de OAuth | Sí | Solo inicio de sesión con OAuth | | Las mismas llamadas por REST, con jobs y webhooks | Sí | No | useapi.net es un servicio de terceros, sin afiliación con ACE Music. ACE Music juga punya MCP server sendiri di `https://acemusic.ai/mcp`. Server itu membuat lagu ACE Music v1 dan v1.1 dari gaya dan lirik yang ditulis asisten Anda. Server useapi.net bekerja di akun ACE Music yang sama dan menambahkan sisanya (per 18 November 2026): | | MCP ACE Music dari useapi.net | MCP milik ACE Music sendiri | |---|---|---| | ACE-Step v1.5 XL, 0 kredit di semua paket | Ya | Tidak, hanya ACE Music v1 dan v1.1 | | Download MP3 di paket Free | Ya | Tidak, setiap download butuh paket berbayar | | Cover, remix, edit, dan mashup | Masing-masing satu panggilan, dari lagu Anda | Dirangkai oleh asisten dari partitur hasil transkripsi | | Stem: vokal dan instrumental, atau setiap instrumen | Ya | Tidak | | Partitur MusicXML | Ya | Tidak, hanya MIDI | | Gaya, lirik, dan judul ditulis ACE Music dari ide satu baris | Ya | Tidak, asisten yang menulisnya | | Beberapa akun ACE Music dalam satu koneksi | Ya | Satu akun per koneksi | | Token API untuk skrip, n8n, dan agen headless, plus OAuth | Ya | Hanya login OAuth | | Panggilan yang sama lewat REST, dengan job dan webhook | Ya | Tidak | useapi.net adalah layanan pihak ketiga dan tidak berafiliasi dengan ACE Music. ACE Music も独自の MCP サーバーを `https://acemusic.ai/mcp` で提供しています。こちらは、アシスタントが書いたスタイルと歌詞から ACE Music v1 と v1.1 の曲を作ります。useapi.net のサーバーは同じ ACE Music アカウントで動き、それ以外のすべてを補います(2026年11月18日時点)。 | | useapi.net の ACE Music MCP | ACE Music 独自の MCP | |---|---|---| | ACE-Step v1.5 XL、どのプランでも0クレジット | 対応 | 非対応、ACE Music v1 と v1.1 のみ | | Free プランでの MP3 ダウンロード | 対応 | 非対応、ダウンロードにはすべて有料プランが必要 | | カバー、リミックス、編集、マッシュアップ | お手持ちの曲から、それぞれ1回の呼び出しで | 書き起こした楽譜をもとにアシスタントが組み立てる | | ステム:ボーカルとインスト、または楽器ごと | 対応 | 非対応 | | MusicXML の楽譜 | 対応 | 非対応、MIDI のみ | | 1行のアイデアから ACE Music がスタイル、歌詞、タイトルを書く | 対応 | 非対応、アシスタントが書く | | 1つの接続で複数の ACE Music アカウント | 対応 | 1接続につき1アカウント | | スクリプト、n8n、ヘッドレスエージェント向けの API トークンと OAuth | 対応 | OAuth サインインのみ | | 同じ呼び出しを REST で、ジョブと Webhook 付きで | 対応 | 非対応 | useapi.net はサードパーティのサービスで、ACE Music とは提携していません。 O ACE Music também tem o próprio servidor MCP em `https://acemusic.ai/mcp`. Ele gera músicas do ACE Music v1 e v1.1 a partir do estilo e da letra que o seu assistente escreve. O servidor da useapi.net funciona na mesma conta do ACE Music e acrescenta todo o resto (em 18 de novembro de 2026): | | MCP do ACE Music da useapi.net | MCP do próprio ACE Music | |---|---|---| | ACE-Step v1.5 XL, 0 créditos em todos os planos | Sim | Não, só ACE Music v1 e v1.1 | | Download de MP3 no plano Free | Sim | Não, todo download exige um plano pago | | Covers, remixes, edições e mashups | Uma chamada para cada, a partir das suas músicas | Montados pelo assistente a partir de uma partitura transcrita | | Stems: vocal e instrumental, ou cada instrumento | Sim | Não | | Partituras MusicXML | Sim | Não, só MIDI | | Estilo, letra e título escritos pelo ACE Music a partir de uma ideia de uma linha | Sim | Não, o assistente escreve | | Várias contas do ACE Music em uma só conexão | Sim | Uma conta por conexão | | Token de API para scripts, n8n e agentes headless, além de OAuth | Sim | Só login com OAuth | | As mesmas chamadas via REST, com jobs e webhooks | Sim | Não | A useapi.net é um serviço de terceiros, sem afiliação com o ACE Music. ACE Music มี MCP server ของตัวเองด้วยที่ `https://acemusic.ai/mcp` ซึ่งสร้างเพลง ACE Music v1 และ v1.1 จากสไตล์และเนื้อเพลงที่ผู้ช่วย AI ของคุณเขียน ส่วน server ของ useapi.net ทำงานบนบัญชี ACE Music เดียวกันและเพิ่มส่วนที่เหลือทั้งหมด (ข้อมูล ณ วันที่ 18 พฤศจิกายน 2026): | | ACE Music MCP ของ useapi.net | MCP ของ ACE Music เอง | |---|---|---| | ACE-Step v1.5 XL ใช้ 0 เครดิตในทุกแพ็กเกจ | ได้ | ไม่ได้ มีแค่ ACE Music v1 และ v1.1 | | ดาวน์โหลด MP3 ในแพ็กเกจ Free | ได้ | ไม่ได้ ทุกการดาวน์โหลดต้องใช้แพ็กเกจเสียเงิน | | คัฟเวอร์ รีมิกซ์ การแก้ไข และแมชอัป | เรียกครั้งเดียวต่ออย่าง จากเพลงของคุณ | ผู้ช่วย AI ประกอบเองจากโน้ตเพลงที่ถอดออกมา | | สเต็ม: เสียงร้องกับดนตรี หรือแยกทุกเครื่องดนตรี | ได้ | ไม่ได้ | | โน้ตเพลง MusicXML | ได้ | ไม่ได้ มีแค่ MIDI | | ACE Music เขียนสไตล์ เนื้อเพลง และชื่อเพลงจากไอเดียบรรทัดเดียว | ได้ | ไม่ได้ ผู้ช่วย AI ต้องเขียนเอง | | หลายบัญชี ACE Music ในการเชื่อมต่อเดียว | ได้ | หนึ่งบัญชีต่อการเชื่อมต่อ | | API token สำหรับสคริปต์ n8n และเอเจนต์ที่ไม่มีหน้าจอ พร้อม OAuth | ได้ | ล็อกอินด้วย OAuth เท่านั้น | | เรียกแบบเดียวกันผ่าน REST พร้อมงานและ webhook | ได้ | ไม่ได้ | useapi.net เป็นบริการของบุคคลที่สาม ไม่มีส่วนเกี่ยวข้องกับ ACE Music ACE Music cũng có MCP server riêng tại `https://acemusic.ai/mcp`. Server này tạo bài hát ACE Music v1 và v1.1 từ phong cách và lời bài hát do trợ lý của bạn viết. Server của useapi.net chạy trên cùng tài khoản ACE Music và bổ sung phần còn lại (tính đến 18 tháng 11 năm 2026): | | MCP ACE Music của useapi.net | MCP riêng của ACE Music | |---|---|---| | ACE-Step v1.5 XL, 0 credit trên mọi gói | Có | Không, chỉ ACE Music v1 và v1.1 | | Tải MP3 trên gói Free | Có | Không, mọi lượt tải đều cần gói trả phí | | Cover, remix, chỉnh sửa và mashup | Mỗi thứ một lệnh gọi, từ bài hát của bạn | Trợ lý tự ghép lại từ bản nhạc được chép ra | | Stem: giọng hát và nhạc nền, hoặc từng nhạc cụ | Có | Không | | Bản nhạc MusicXML | Có | Không, chỉ MIDI | | Phong cách, lời và tên bài do ACE Music viết từ một ý tưởng một dòng | Có | Không, trợ lý tự viết | | Nhiều tài khoản ACE Music trong một kết nối | Có | Một tài khoản cho mỗi kết nối | | API token cho script, n8n và agent chạy không giao diện, cùng với OAuth | Có | Chỉ đăng nhập OAuth | | Cùng các lệnh gọi qua REST, có job và webhook | Có | Không | useapi.net là dịch vụ của bên thứ ba, không liên kết với ACE Music. ACE Music 也在 `https://acemusic.ai/mcp` 运行自己的 MCP 服务器。它根据你的助手写好的风格和歌词生成 ACE Music v1 和 v1.1 歌曲。useapi.net 的服务器使用同一个 ACE Music 账号,并补上其余的一切(截至 2026 年 11 月 18 日): | | useapi.net ACE Music MCP | ACE Music 自己的 MCP | |---|---|---| | ACE-Step v1.5 XL,所有套餐都是 0 积分 | 支持 | 不支持,只有 ACE Music v1 和 v1.1 | | 免费套餐下载 MP3 | 支持 | 不支持,任何下载都需要付费套餐 | | 翻唱、重混、编辑和混搭 | 基于你的歌曲,各一次调用 | 由助手根据转写出的乐谱拼凑完成 | | 分轨:人声和伴奏,或每件乐器 | 支持 | 不支持 | | MusicXML 乐谱 | 支持 | 不支持,只有 MIDI | | 由 ACE Music 根据一句话的想法写出风格、歌词和标题 | 支持 | 不支持,由助手来写 | | 一个连接中使用多个 ACE Music 账号 | 支持 | 每个连接一个账号 | | 用于脚本、n8n 和无界面智能体的 API Token,另有 OAuth | 支持 | 只能 OAuth 登录 | | 通过 REST 进行同样的调用,带任务和 webhook | 支持 | 不支持 | useapi.net 是第三方服务,与 ACE Music 无关联。 ACE Music also runs its own MCP server at `https://acemusic.ai/mcp`. It makes ACE Music v1 and v1.1 songs from the style and lyrics your assistant writes. The useapi.net server works on the same ACE Music account and adds the rest (as of November 18, 2026): | | useapi.net ACE Music MCP | ACE Music's own MCP | |---|---|---| | ACE-Step v1.5 XL, 0 credits on every plan | Yes | No, ACE Music v1 and v1.1 only | | MP3 download on the Free plan | Yes | No, every download needs a paid plan | | Covers, remixes, edits and mashups | One call each, from your songs | Pieced together by the assistant from a transcribed score | | Stems: vocals and instrumental, or every instrument | Yes | No | | MusicXML scores | Yes | No, MIDI only | | Style, lyrics and title written by ACE Music from a one-line idea | Yes | No, the assistant writes them | | Several ACE Music accounts in one connection | Yes | One account per connection | | API token for scripts, n8n and headless agents, plus OAuth | Yes | OAuth sign-in only | | The same calls over REST, with jobs and webhooks | Yes | No | useapi.net is a third-party service, not affiliated with ACE Music. ### สร้างเป็นชุดด้วยสคริปต์ [GitHub repo `acemusic-api`](https://github.com/useapi/acemusic-api) มีตัวอย่างหนึ่งชุดต่อหนึ่งฟีเจอร์ ซึ่งลิงก์ไว้จากแต่ละหัวข้อด้านบน แต่ละชุดมีสคริปต์ Node.js และสคริปต์ Python คู่กัน โดยไม่ต้องติดตั้งอะไรเพิ่ม แต่ละสคริปต์อ่านคำขอจาก `prompts.json` ที่คุณแก้ไขได้ รันพร้อมกันได้สูงสุด 4 รายการ โพลงาน แล้วบันทึกเพลงทั้งสองเพลง ภาพปก บันทึกงาน และ `ledger.jsonl` ของเครดิตที่ใช้ไว้ในโฟลเดอร์ `output/` คุณต้องมี [Node.js](https://nodejs.org) 21 ขึ้นไป หรือ [Python](https://www.python.org) 3.8 ขึ้นไป `--only 3` จะรันพรอมต์ที่สามด้านล่าง ซึ่งเป็นเพลง ACE-Step ที่ไม่ใช้เครดิต จึงใช้กับบัญชี Free ได้: ```bash git clone https://github.com/useapi/acemusic-api.git && cd acemusic-api export USEAPI_TOKEN="user:12345-..." node songs-from-prompt/songs-from-prompt.mjs --only 3 ``` บันทึกงานที่บันทึกไว้แต่ละไฟล์มี `songId` ของเพลง และ `--from <job>.json --pick 1` จะส่งเพลงที่ 1 ต่อให้สคริปต์ถัดไปเพื่อคัฟเวอร์ แมชอัป หรือแยกสเต็ม <details markdown="block"> <summary>ขยาย `songs-from-prompt/prompts.json`</summary> ```json [ { "_about": "ACE Music v1 (the default model, 4 credits for two songs): ACE Music writes the style, lyrics and title from your idea", "prompt": "A late-night neo-soul slow jam about two strangers sharing an umbrella at a bus stop in the rain and missing the last bus on purpose. Warm Rhodes piano, brushed drums, round upright bass, a smoky female lead with close three-part harmonies on the chorus.", "model": "acemusic-v1" }, { "_about": "ACE Music v1.1 Preview (4 credits): writes a score first, then the audio", "prompt": "An anthemic Celtic folk-rock singalong about a fishing crew racing a storm back to the harbor. Fiddle and tin whistle hooks, stomping kick drum, bodhran, a gravelly male lead and the whole crew shouting the chorus.", "model": "acemusic-v1.1" }, { "_about": "ACE-Step v1.5 XL (no credits on any ACE Music plan, the Free plan included)", "prompt": "A breezy bossa nova for a lazy Sunday afternoon in Lisbon: nylon-string guitar, soft brushed snare, upright bass, a gentle flute line and a warm male and female duet sung in Portuguese.", "model": "ace-step-1.5-xl" } ] ``` </details> ### ตัวอย่าง ทุกเพลงด้านล่างสร้างเมื่อวันที่ 14 พฤศจิกายน 2026 (PST) ด้วยสคริปต์ใน repo บนบัญชี ACE Music แพ็กเกจ Artist โดยเป็นเพลงแรกจากสองเพลงของแต่ละคำขอ ชื่อเพลงมาจาก ACE Music เว้นแต่เราตั้งเอง เวลานับตั้งแต่ส่งคำขอจนทั้งสองเพลงเสร็จ และการเรียก API ที่แสดงใช้ id สมมติ #### เพลงจากภาพ ส่งภาพหนึ่งภาพกับสไตล์หนึ่งประโยค ได้เพลงที่เสร็จแล้วสองเพลง เราอัปโหลดภาพมาสคอตหุ่นยนต์กำลังเต้นนี้แล้วขอเป็นดรัมแอนด์เบส ACE Music เขียนเนื้อเพลงจากสิ่งที่เห็นในภาพ: "Teal fur shaking on the concrete floor, orange high-tops squeaking by the studio door" <img src="https://media.useapi.net/blog/2026-09-07-260907/dreamina-longvideo-ref-robot-mascot.png" alt="มาสคอตหุ่นยนต์ขนฟูสีเขียวอมฟ้า หัวเป็นกล่อง มีเสาอากาศและดวงตาเรืองแสง กำลังเต้นในรองเท้าผ้าใบหุ้มข้อสีส้ม" style="width: 100%; max-width: 220px;" loading="lazy"> ``` Bouncy, playful drum and bass for a dancing robot mascot: rolling breakbeats at 174 bpm, a wobbly reese bass, bleepy robot synth hooks, vocoder chops, cheeky and upbeat. ``` ACE Music v1 — "Bleep Boop Bounce" · 2:47 · สร้างใน 72 วินาที <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/files' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: image/png' \ --data-binary @robot-mascot.png curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "Bouncy, playful drum and bass for a dancing robot mascot: rolling breakbeats at 174 bpm, a wobbly reese bass, bleepy robot synth hooks, vocoder chops, cheeky and upbeat.", "model": "acemusic-v1", "images": ["user:12345-example@example.com-media:cx_3b9e1d7a5c2f48e0a6d4b8c1"], "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-bleep-boop-bounce-drum-and-bass-from-robot-image.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> เพลงนี้ในรูปแบบ YouTube Short พร้อมภาพถ่าย: [Bleep Boop Bounce บน YouTube](https://youtube.com/shorts/z_aOmILvIng) #### เพลงจากพรอมต์ เพลง ACE Music v1 จากพรอมต์ "Let the 44 Roll By" อยู่ใน[ส่วนสาธิตทีละขั้นตอน](#what-you-get-back)แล้ว ต่อไปนี้คืออีกสองพรอมต์บนอีกสองโมเดล: ``` An anthemic Celtic folk-rock singalong about a fishing crew racing a storm back to the harbor. Fiddle and tin whistle hooks, stomping kick drum, bodhran, a gravelly male lead and the whole crew shouting the chorus. ``` ACE Music v1.1 Preview — "Haul for the Harbor Light" · 2:51 · สร้างใน 43 วินาที <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "An anthemic Celtic folk-rock singalong about a fishing crew racing a storm back to the harbor. Fiddle and tin whistle hooks, stomping kick drum, bodhran, a gravelly male lead and the whole crew shouting the chorus.", "model": "acemusic-v1.1", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-1-haul-for-the-harbor-light-celtic-folk-rock-from-prompt.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ``` A breezy bossa nova for a lazy Sunday afternoon in Lisbon: nylon-string guitar, soft brushed snare, upright bass, a gentle flute line and a warm male and female duet sung in Portuguese. ``` ACE-Step v1.5 XL, ไม่ใช้เครดิต — "Domingo em Alfama" · 3:28 <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "A breezy bossa nova for a lazy Sunday afternoon in Lisbon: nylon-string guitar, soft brushed snare, upright bass, a gentle flute line and a warm male and female duet sung in Portuguese.", "model": "ace-step-1.5-xl", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-domingo-em-alfama-bossa-nova-from-prompt.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### เนื้อเพลงของคุณเอง สองเวิร์ส พรีคอรัส บริดจ์ และเอาท์โทรที่เราเขียนเอง ขอความยาว 210 วินาที: ``` Style: cinematic indie pop ballad, felt piano, swelling strings, deep heartbeat kick, intimate female vocal that opens up into a soaring chorus, 72 bpm Lyrics: [Verse 1] We wrote our names on paper lanterns / Down by the river in July … [Chorus] Light it up and let it go / Every word I never said out loud … ``` ACE Music v1 — "Paper Lanterns" · 3:29 · สร้างใน 61 วินาที <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "title": "Paper Lanterns", "style": "cinematic indie pop ballad, felt piano, swelling strings, deep heartbeat kick, intimate female vocal that opens up into a soaring chorus, 72 bpm", "lyrics": "[Verse 1]\nWe wrote our names on paper lanterns\nDown by the river in July\nYou said the wind would know the answer\nIf we just let the fire fly\nYour hand was shaking, mine was steady\nAt least that'\''s how I tell it now\nWe watched them climb until the city\nWas just a glow beneath the clouds\n\n[Pre-Chorus]\nSo every summer I come back here\nStrike a match and hold it near\n\n[Chorus]\nLight it up and let it go\nEvery word I never said out loud\nLight it up and let it go\nHigher than the both of us somehow\nAnd if it finds you anyhow\nTell me you can see it from the clouds\n\n[Verse 2]\nThey tore the old pier down last winter\nPut up a fence and painted lines\nBut I still know the way by heartbeat\nI find the water every time\nI keep a lighter in my pocket\nI keep your laugh inside my head\nI fold the paper like you showed me\nAnd write the things I should have said\n\n[Pre-Chorus]\nSo every summer I come back here\nStrike a match and hold it near\n\n[Chorus]\nLight it up and let it go\nEvery word I never said out loud\nLight it up and let it go\nHigher than the both of us somehow\nAnd if it finds you anyhow\nTell me you can see it from the clouds\n\n[Bridge]\nPaper and fire, paper and fire\nNothing this light should rise so high\nPaper and fire, paper and fire\nMaybe that'\''s how we say goodbye\n\n[Final Chorus]\nLight it up and let it go\nEvery word I never said out loud\nLight it up and let it go\nHigher than the both of us somehow\n\n[Outro]\nDown by the river in July", "model": "acemusic-v1", "duration": 210, "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-paper-lanterns-custom-lyrics.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> เพลงบรรเลง: `instrumental: true` ยาว 150 วินาที ไม่มีเสียงร้อง คณะประสานเสียง หรือกีตาร์โปร่ง: ``` Style: cinematic synthwave instrumental for a night drive: pulsing analog bass arpeggio, gated reverb drums, lush pads, a soaring lead synth melody, builds to a big final section, 108 bpm ``` ACE Music v1 — "Neon Overpass" · 2:29 · สร้างใน 46 วินาที <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "title": "Neon Overpass", "style": "cinematic synthwave instrumental for a night drive: pulsing analog bass arpeggio, gated reverb drums, lush pads, a soaring lead synth melody, builds to a big final section, 108 bpm", "instrumental": true, "model": "acemusic-v1", "duration": 150, "negative": "vocals, choir, acoustic guitar", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-neon-overpass-synthwave-instrumental.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> เนื้อเพลงภาษาสเปนเกี่ยวกับปาร์ตี้บนดาดฟ้าระหว่างไฟดับ: ``` Style: modern cumbia pop, bright accordion hooks, güira and congas, warm bass, a festive male lead with a crowd shouting the chorus, 98 bpm Lyrics: [Chorus] Bailando en la azotea / Con las estrellas de farol … ``` ACE Music v1 — "Bailando en la Azotea" · 2:32 · สร้างใน 46 วินาที <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "title": "Bailando en la Azotea", "style": "modern cumbia pop, bright accordion hooks, güira and congas, warm bass, a festive male lead with a crowd shouting the chorus, 98 bpm", "lyrics": "[Verse 1]\nSe fue la luz en todo el barrio\nY nadie quiere irse a dormir\nDoña Rosa saca el radio viejo\nY la noche empieza a sonreír\nLos vecinos suben con sus sillas\nAlguien trae limones y café\nY la ciudad allá abajo, oscura\nNos mira bailar sin saber por qué\n\n[Pre-Chorus]\nSube, sube, que la luna está invitando\nSube, sube, que la calle está cantando\n\n[Chorus]\nBailando en la azotea\nCon las estrellas de farol\nQue se entere todo el mundo\nQue esta noche no hay apagón\nBailando en la azotea\nCon el corazón de tambor\nSi se apaga la ciudad entera\nAquí arriba sobra amor\n\n[Verse 2]\nEl abuelo saca la guitarra\nLa vecina de enfrente se animó\nLos niños corren entre las sábanas\nQue el viento de la tarde colgó\nNadie sabe cuándo vuelve la corriente\nY la verdad, a nadie le importó\nEsta fiesta no la paga nadie\nEsta fiesta la invitó el apagón\n\n[Chorus]\nBailando en la azotea\nCon las estrellas de farol\nQue se entere todo el mundo\nQue esta noche no hay apagón\nBailando en la azotea\nCon el corazón de tambor\nSi se apaga la ciudad entera\nAquí arriba sobra amor\n\n[Outro]\nQue esta noche no hay apagón", "model": "acemusic-v1", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-bailando-en-la-azotea-spanish-cumbia.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> เนื้อเพลงจากตัวช่วยเขียนเนื้อเพลง สไตล์จากตัวช่วยเขียนสไตล์ และร้องโดย ACE-Step: ``` Lyrics writer: A wistful country song about an old pickup truck that still has her mixtape stuck in the tape deck Style writer: classic country ballad, pedal steel, warm baritone ``` ACE-Step v1.5 XL, ไม่ใช้เครดิต — "Side B Forever" · 3:35 · สร้างใน 40 วินาที หลังจากใช้ 6 วินาทีกับเนื้อเพลงและ 4 วินาทีกับสไตล์ <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music/lyrics' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "A wistful country song about an old pickup truck that still has her mixtape stuck in the tape deck", "style": "classic country ballad, pedal steel, warm baritone", "model": "ace-step-1.5-xl" }' > lyrics.json curl -X POST 'https://api.useapi.net/v1/acemusic/music/style' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "style": "classic country ballad, pedal steel, warm baritone", "model": "ace-step-1.5-xl" }' > style.json # sing what the writers returned jq -n --slurpfile l lyrics.json --slurpfile s style.json \ '{title: $l[0].title, lyrics: $l[0].lyrics, style: $s[0].style, model: "ace-step-1.5-xl", async: true}' | curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d @- ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-side-b-forever-lyrics-and-style-writers.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### ACE-Step ที่จังหวะ คีย์ และอัตราจังหวะที่กำหนด ทุกเพลงได้ความยาวตรงตามที่ขอ ``` 3/4 · 84 bpm · D minor · 120 s · thinking 60 · avoid: trap drums, EDM, autotune Style: dark cabaret waltz, accordion, pizzicato strings, upright bass, brushed snare, theatrical female vocal ``` ACE-Step v1.5 XL, ไม่ใช้เครดิต — "Midnight Waltz" · 2:00 · สร้างใน 31 วินาที <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "model": "ace-step-1.5-xl", "title": "Midnight Waltz", "style": "dark cabaret waltz, accordion, pizzicato strings, upright bass, brushed snare, theatrical female vocal", "lyrics": "[Verse 1]\nThe band plays slow when the lights go low\nAnd the chandeliers begin to sway\nTake my hand, we will dance till the candles stand\nIn puddles of yesterday\n\n[Chorus]\nOne, two, three, turn around with me\nRound and round till the morning comes\nOne, two, three, oh don'\''t let me be\nThe last one dancing when the music'\''s done\n\n[Verse 2]\nThe clock strikes twelve and it laughs at itself\nEvery mirror wears a stranger'\''s face\nHold me close, we are only ghosts\nWho forgot to leave this place\n\n[Chorus]\nOne, two, three, turn around with me\nRound and round till the morning comes\nOne, two, three, oh don'\''t let me be\nThe last one dancing when the music'\''s done", "bpm": 84, "timeSignature": "3/4", "key": "D minor", "duration": 120, "negative": "trap drums, EDM, autotune", "thinking": 60, "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-midnight-waltz-3-4-84-bpm-d-minor.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ``` 6/8 · 116 bpm · G major · 90 s · instrumental Style: lively celtic instrumental jig, fiddle and tin whistle trading the melody, bodhran, strummed bouzouki, foot stomps ``` ACE-Step v1.5 XL, ไม่ใช้เครดิต — "Harbour Jig" · 1:30 · สร้างใน 20 วินาที <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "model": "ace-step-1.5-xl", "title": "Harbour Jig", "style": "lively celtic instrumental jig, fiddle and tin whistle trading the melody, bodhran, strummed bouzouki, foot stomps", "instrumental": true, "bpm": 116, "timeSignature": "6/8", "key": "G major", "duration": 90, "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-harbour-jig-6-8-116-bpm-g-major.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ``` 4/4 · 174 bpm · F minor · 150 s · thinking 80 Style: liquid drum and bass, rolling breakbeats, deep warm sub bass, airy pads, soulful female vocal ``` ACE-Step v1.5 XL, ไม่ใช้เครดิต — "Almost Home" · 2:30 · สร้างใน 41 วินาที <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "model": "ace-step-1.5-xl", "title": "Almost Home", "style": "liquid drum and bass, rolling breakbeats, deep warm sub bass, airy pads, soulful female vocal", "lyrics": "[Verse]\nCity lights in the rear view mirror\nRunning on a borrowed night\nEvery bridge is a little bit nearer\nEvery tunnel full of light\n\n[Chorus]\nHold on, we'\''re almost home\nEvery signal turning green\nHold on, you'\''re not alone\nFaster than the in-between\n\n[Verse]\nRadio low and the windows open\nBreathing in the summer rain\nEvery promise we left unspoken\nRushing back to us again\n\n[Chorus]\nHold on, we'\''re almost home\nEvery signal turning green\nHold on, you'\''re not alone\nFaster than the in-between", "bpm": 174, "timeSignature": "4/4", "key": "F minor", "duration": 150, "thinking": 80, "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-almost-home-drum-and-bass-174-bpm-f-minor.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### คัฟเวอร์ รีมิกซ์ และการแก้ไข "Paper Lanterns" ในแบบคัฟเวอร์ สไตล์ใหม่ที่ยังคงทำนองเดิม: ``` mode: cover · stripped-back acoustic folk cover, fingerpicked steel-string guitar, warm cello, soft close-mic'd male vocal ``` ACE Music v1.1 Preview — "Paper Lanterns (Acoustic Folk Cover)" · 3:34 · สร้างใน 72 วินาที <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash # our script read the score first (free for an ACE Music v1 song; the API now does this by itself) curl 'https://api.useapi.net/v1/acemusic/music/score?songId=user%3A12345-example%40example.com-song%3Aso_4e7b2c9d0a5f4183b6d8e2c7' \ -H 'Authorization: Bearer user:12345-…' > /dev/null curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "mode": "cover", "model": "acemusic-v1.1", "references": ["user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7"], "style": "stripped-back acoustic folk cover, fingerpicked steel-string guitar, warm cello, soft close-mic'\''d male vocal", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-1-paper-lanterns-acoustic-folk-cover.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> "Bailando en la Azotea" ในแบบดีปเฮาส์ เราไม่ได้ส่งชื่อเพลง ACE Music จึงตั้งชื่อว่า "Reference 1": ``` mode: remix · coverStrength 40 · remixStrength 50 · deep house remix, four-on-the-floor kick, plucky chords, rolling bassline, filtered vocal chops ``` ACE-Step v1.5 XL, ไม่ใช้เครดิต — "Reference 1" · 2:32 · สร้างใน 31 วินาที <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "mode": "remix", "model": "ace-step-1.5-xl", "references": ["user:12345-example@example.com-song:so_9d3b7e2c1a6f4085b8e4d1c6"], "style": "deep house remix, four-on-the-floor kick, plucky chords, rolling bassline, filtered vocal chops", "coverStrength": 40, "remixStrength": 50, "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-bailando-en-la-azotea-house-remix.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> "Paper Lanterns" ที่เปลี่ยนเนื้อร้องช่วงวินาทีที่ 30 ถึง 50 และคงส่วนที่เหลือไว้: ``` mode: edit · start 30 · end 50 Lyrics: We wrote our names on paper lanterns / Down by the harbor in the snow / You said the stars would keep the answer / If we were brave enough to go ``` ACE-Step v1.5 XL, ไม่ใช้เครดิต — "Reference 1" · 3:29 · สร้างใน 41 วินาที <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "mode": "edit", "model": "ace-step-1.5-xl", "references": ["user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7"], "start": 30, "end": 50, "style": "cinematic indie pop ballad, felt piano, swelling strings, intimate female vocal", "lyrics": "We wrote our names on paper lanterns\nDown by the harbor in the snow\nYou said the stars would keep the answer\nIf we were brave enough to go", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-paper-lanterns-edit-seconds-30-50.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### แมชอัป "Paper Lanterns" กับ "Let the 44 Roll By": ``` upbeat neo-soul pop mashup, punchy live drums, warm Rhodes and strings, female lead with a gospel-tinged choir on the chorus · audioInfluence 60 ``` ACE Music v1.1 Preview — "Lanterns at the Bus Stop" · 3:58 · สร้างใน 83 วินาที <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash # our script read each song's score first (the API now does this by itself for ACE Music v1 songs) curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "mode": "mashup", "model": "acemusic-v1.1", "references": ["user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7", "user:12345-example@example.com-song:so_7c1d9e3a5b2f4806a4e1c9d3"], "title": "Lanterns at the Bus Stop", "style": "upbeat neo-soul pop mashup, punchy live drums, warm Rhodes and strings, female lead with a gospel-tinged choir on the chorus", "audioInfluence": 60, "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-1-mashup-lanterns-at-the-bus-stop.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> "Haul for the Harbor Light" กับ "Bailando en la Azotea" ที่ขอบน ACE Music v1: ``` festive celtic cumbia mashup, fiddle and accordion trading hooks, congas and bodhran, stomping kick, male lead with a big crowd chorus ``` ACE Music v1.1 Preview (ขอเป็น v1) — "Harbor Fiesta" · 2:38 · สร้างใน 74 วินาที <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash # our script read each song's score first (the API now does this by itself for ACE Music v1 songs) curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "mode": "mashup", "model": "acemusic-v1", "references": ["user:12345-example@example.com-song:so_2a8f6c1e9d4b47f3b0c5e8a2", "user:12345-example@example.com-song:so_9d3b7e2c1a6f4085b8e4d1c6"], "title": "Harbor Fiesta", "style": "festive celtic cumbia mashup, fiddle and accordion trading hooks, congas and bodhran, stomping kick, male lead with a big crowd chorus", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-1-mashup-harbor-fiesta-asked-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> สามเพลงพร้อมกัน: "Paper Lanterns", "Bailando en la Azotea" และ "Let the 44 Roll By": ``` warm late-night soul-pop medley, Rhodes and strings, light latin percussion, female lead with a male answer on the last chorus ``` ACE Music v1.1 Preview — "Three Songs, One Night" · 3:32 · สร้างใน 43 วินาที <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash # our script read each song's score first (the API now does this by itself for ACE Music v1 songs) curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "mode": "mashup", "model": "acemusic-v1.1", "references": ["user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7", "user:12345-example@example.com-song:so_9d3b7e2c1a6f4085b8e4d1c6", "user:12345-example@example.com-song:so_7c1d9e3a5b2f4806a4e1c9d3"], "title": "Three Songs, One Night", "style": "warm late-night soul-pop medley, Rhodes and strings, light latin percussion, female lead with a male answer on the last chorus", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-1-mashup-three-songs-one-night.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### ไฟล์เสียงและภาพของคุณ "Harbour Jig" ด้านบน อัปโหลดเป็น MP3 แล้วใช้เป็นเพลงอ้างอิงของพรอมต์ ACE Music รันบน v1.1 เพื่อคงทำนองไว้: ``` A rowdy pub singalong with a big shouted chorus about the last ferry home, built on the tune of this recording ``` ACE Music v1.1 Preview (ขอเป็น v1) — "Last Ferry Home" · 1:36 · สร้างใน 52 วินาที <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/files?title=Harbour%20Jig%20demo' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: audio/mpeg' \ --data-binary @harbour-jig-demo.mp3 curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "A rowdy pub singalong with a big shouted chorus about the last ferry home, built on the tune of this recording", "model": "acemusic-v1", "references": ["user:12345-example@example.com-song:so_5f1a3c8e7b2d49a6c3e0f7b9"], "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-1-last-ferry-home-from-uploaded-jig.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### สเต็มของ "Paper Lanterns" เสียงร้องและดนตรีจาก `mode: "vocals"` (5 เครดิต) ตามด้วยกลองและเครื่องสายจาก 9 สเต็มของ `mode: "all"` (60 เครดิต) <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music/stems' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "songId": "user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7", "mode": "vocals", "async": true }' curl -X POST 'https://api.useapi.net/v1/acemusic/music/stems' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "songId": "user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7", "mode": "all", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-paper-lanterns-stem-vocal.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-paper-lanterns-stem-instrumental.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-paper-lanterns-stem-drums.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-paper-lanterns-stem-strings.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ### คำถามที่พบบ่อย **ACE Music มี API ไหม?** ผ่าน useapi.net มี [ACE Music API](/docs/api-acemusic-v1) รัน ACE Music v1, ACE Music v1.1 Preview และ ACE-Step v1.5 XL ผ่าน REST บนบัญชี ACE Music ของคุณ พร้อมคัฟเวอร์ แมชอัป สเต็ม และ MIDI **มี ACE-Step API แบบฟรีไหม?** ผ่าน useapi.net มี เพลง ACE-Step v1.5 XL ไม่ใช้เครดิตในทุกแพ็กเกจ ACE Music รวมถึงแพ็กเกจ Free พร้อมการตั้งค่าจังหวะ คีย์ อัตราจังหวะ และความยาว รวมถึงรีมิกซ์และการแก้ไข ส่วน acestep.io ซึ่งเป็นบุคคลที่สาม ให้ใช้ ACE-Step API เฉพาะในแพ็กเกจ Studio $49 ต่อเดือน ราว $0.14 ต่อเพลง (ข้อมูล ณ พฤศจิกายน 2026) **เพลง ACE Music v1 ผ่าน API ราคาเท่าไร?** ผ่าน useapi.net เพลง ACE Music v1 หนึ่งเพลงใช้ 2 เครดิตจากแพ็กเกจ ACE Music ของคุณ คือ $0.013 บน Artist แบบชำระรายปี และ $0.023 บน Artist แบบรายเดือน โดยไม่มีค่าใช้จ่ายเพิ่มต่อเพลง ดูที่[ราคา](#pricing) **ACE Music มี MCP server ไหม?** ผ่าน useapi.net มี และทำได้มากกว่า server ของ ACE Music เองที่ `acemusic.ai/mcp` [ACE Music MCP server](/docs/api-acemusic-v1/mcp) แบบโฮสต์เพิ่มโมเดล ACE-Step v1.5 XL ที่ใช้ฟรี การดาวน์โหลด MP3 ในแพ็กเกจ Free สเต็ม คัฟเวอร์ รีมิกซ์ การแก้ไข และแมชอัปด้วยการเรียกครั้งเดียว MusicXML และหลายบัญชีภายใต้ API token เดียว ส่วน server ของ ACE Music เองสร้างเพลง v1 และ v1.1 จากเนื้อเพลงที่ผู้ช่วย AI ของคุณเขียน และทุกการดาวน์โหลดต้องใช้แพ็กเกจเสียเงิน ดู[ตารางเปรียบเทียบ](#useapinet-vs-ace-musics-own-mcp-server) ### สรุป POST ครั้งเดียวได้เพลงสองเพลงจากโมเดลที่ครองอันดับหนึ่งของตารางอันดับเสียงร้อง เพลง ACE-Step ไม่มีค่าใช้จ่าย และทุกเพลงนำไปทำคัฟเวอร์ แมชอัป สเต็ม หรือไฟล์ MIDI ได้ในการเรียกครั้งถัดไป โคลน [repo `acemusic-api`](https://github.com/useapi/acemusic-api) รัน `songs-from-prompt/` ด้วย `--only 3` บนบัญชี Free และดู [POST /music](/docs/api-acemusic-v1/post-acemusic-music) สำหรับตัวเลือกทั้งหมด ติดต่อเราได้ที่ <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> หรือ <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> สำหรับทุกคำถามและข้อสงสัยด้านการใช้งาน === URL: https://useapi.net/docs/articles/ace-music-api-tutorial-vi === Document URL: https://useapi.net/docs/articles/ace-music-api-tutorial-vi --- layout: default title: "Cách tạo bài hát AI bằng ACE Music API" description: "Tạo bài hát bằng ACE Music v1, v1.1 và ACE-Step v1.5 XL miễn phí qua ACE Music API của useapi.net: prompt, lời bài hát của riêng bạn, cover, mashup, stem, MIDI, với curl và code." keywords: [ACE Music API, ACE Music v1 API, ACE-Step API, ACE-Step v1.5 XL, AI song generator API, text to music API, Suno alternative, AI music API, stems API, MIDI, MusicXML, mashup, cover song AI, MCP server, API ACE Music, API tạo nhạc AI, tạo bài hát bằng AI, tạo nhạc từ văn bản, tách stem, thay thế Suno, hướng dẫn, curl] image: https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-paper-lanterns-cover-art.jpg parent: Articles nav_exclude: true lang: vi translation_key: ace-music-tutorial date: 2026-11-14 last_modified: 2026-11-18 nav_order: 302 repo: https://github.com/useapi/acemusic-api --- ## Cách tạo bài hát AI bằng ACE Music API {: .no_toc #how-to-generate-ai-songs-with-the-ace-music-api } 22 phút đọc • 14 tháng 11 năm 2026 ## Mục lục {: .no_toc .text-delta #table-of-contents } ### Giới thiệu [ACE Music API](/docs/api-acemusic-v1) của useapi.net biến một lệnh gọi REST thành hai bài hát hoàn chỉnh từ [ACE Music](https://acemusic.ai), có giọng hát, lời, tên bài và ảnh bìa, trên chính gói ACE Music bạn đang dùng. ACE Music v1 đứng hạng 1 trên [bảng xếp hạng nhạc có giọng hát của Artificial Analysis](https://artificialanalysis.ai/music/leaderboard/vocals), trên cả Suno v6. Model mã nguồn mở [ACE-Step](https://ace-step.github.io) v1.5 XL chạy qua cùng API này mà không tốn credit trên bất kỳ gói ACE Music nào, kể cả gói Free. Hướng dẫn này bắt đầu với ba model và chi phí của một bài hát, tạo trọn vẹn một bài hát bằng `curl`, rồi điểm qua mọi tính năng còn lại trong một bảng ngắn. Phần [Ví dụ](#examples) ở cuối gồm 18 bài hát chúng tôi tạo cho trang này, mỗi bài kèm request đã tạo ra nó, tất cả từ các script trong [repo GitHub `acemusic-api`](https://github.com/useapi/acemusic-api) (Node.js và Python), tốn 117 credit của một gói Artist, tính cả những lần chạy thêm. useapi.net là API của [bên thứ ba](/docs/legal#affiliation--third-party-services), không liên kết với ACE Music hay Timedomain, công ty tạo ra ACE Music. ### Các model và những gì API làm được Mỗi request tạo hai bài hát, và `model` chọn model sẽ tạo chúng: | Model | `model` | Dùng để làm gì | Thiết lập | Credit mỗi request | Thời gian chạy thử | |---|---|---|---|---|---| | ACE Music v1 | `acemusic-v1` (mặc định) | Model giọng hát hạng 1: bài hát từ prompt hoặc từ lời của bạn, có hát hoặc không lời | `duration` 30 đến 600 giây, `negative`, `styleInfluence`, tải WAV | 4 | 46 đến 89 giây | | ACE Music v1.1 Preview | `acemusic-v1.1` | Viết bản nhạc (score) trước, nên các bản cover và mashup bám theo giai điệu của bài gốc | `audioInfluence`, `styleInfluence` | 4 | 35 đến 83 giây | | ACE-Step v1.5 XL | `ace-step-1.5-xl` | Mã nguồn mở của ACE Studio và StepFun: bài hát, remix và chỉnh sửa | `bpm`, `key`, `timeSignature`, `duration` 10 đến 240 giây, `negative`, `thinking`. Chỉ MP3 | 0 | 20 đến 55 giây | Những gì bạn làm được với chúng: | Tính năng | Request | Ghi chú | |---|---|---| | Bài hát từ prompt | [POST /music](/docs/api-acemusic-v1/post-acemusic-music) `prompt` | ACE Music tự viết phong cách, lời và tên bài | | Lời của riêng bạn, nhạc không lời | [POST /music](/docs/api-acemusic-v1/post-acemusic-music) `style`, `lyrics` | Mọi ngôn ngữ | | Công cụ viết lời và viết phong cách | [POST /music/lyrics](/docs/api-acemusic-v1/post-acemusic-music-lyrics), [/music/style](/docs/api-acemusic-v1/post-acemusic-music-style) | Không tốn credit | | Cover, remix, chỉnh sửa, mashup | [POST /music](/docs/api-acemusic-v1/post-acemusic-music#modes) `mode` | Trên bất kỳ bài hát nào của tài khoản | | Âm thanh và hình ảnh của bạn | [POST /files](/docs/api-acemusic-v1/post-acemusic-files) | Làm tham chiếu cho bài hát mới | | Stem | [POST /music/stems](/docs/api-acemusic-v1/post-acemusic-music-stems) | Creator và Artist | | Tải về, bản nhạc | [GET /music/download](/docs/api-acemusic-v1/get-acemusic-music-download), [/music/score](/docs/api-acemusic-v1/get-acemusic-music-score) | MP3 và bản nhạc trên mọi gói, WAV, MIDI và MusicXML trên Creator và Artist | | Thư viện, job, tài khoản | [GET /music](/docs/api-acemusic-v1/get-acemusic-music), [/jobs](/docs/api-acemusic-v1/get-acemusic-jobs), [/accounts](/docs/api-acemusic-v1/get-acemusic-accounts-email) | Mọi bài hát của tài khoản, các job đang chạy, số credit theo thời gian thực | | MCP server | [`/v1/acemusic/mcp`](/docs/api-acemusic-v1/mcp) | 15 công cụ cho trợ lý AI | ### Giá ACE Music tính credit của riêng mình cho mỗi request, trừ vào gói ACE Music của bạn, và useapi.net không thu thêm gì theo bài hát (tính đến tháng 11/2026): | Request | Credit | |---|---| | Hai bài hát trên ACE Music v1 hoặc v1.1 | 4 | | Stem, giọng hát + nhạc nền | 5, gói trả phí | | Stem, mọi stem | 60, gói trả phí | | Bản nhạc của một bài ACE-Step, lần đọc đầu tiên | 1 | | Hai bài hát trên ACE-Step v1.5 XL | 0, trên mọi gói | | Công cụ viết lời và phong cách, upload, tải về | 0 trong các lần thử của chúng tôi | Các [gói ACE Music](https://acemusic.ai/pricing/) gồm Free với 20 credit mỗi ngày, Creator $9,90 một tháng cho 1.000 credit và Artist $29 một tháng cho 2.500 credit, hoặc $7,90 và $16,58 một tháng khi trả theo năm. Một bài hát là nửa request, tức 2 credit. [Trang tổng quan API](/docs/api-acemusic-v1#pricing) có cùng bảng này. Chi phí một bài hát trên từng gói, rẻ nhất ở bên trái (một request tạo hai bài hát, nên một bài tốn nửa số credit của request, tính đến tháng 11/2026): | Model | Free (20 cr/ngày) | Artist $16,58/th (2.500 cr/tháng, trả theo năm) | Creator $7,90/th (1.000 cr/tháng, trả theo năm) | Creator $9,90/th (1.000 cr/tháng) | Artist $29/th (2.500 cr/tháng) | |---|---|---|---|---|---| | ACE Music v1, v1.1 (một bài) | $0 / 2 cr (10 bài/ngày) | $0,013 / 2 cr (1.250 bài/tháng) | $0,016 / 2 cr (500 bài/tháng) | $0,020 / 2 cr (500 bài/tháng) | $0,023 / 2 cr (1.250 bài/tháng) | | Stem (giọng hát + nhạc nền) | gói trả phí | $0,033 / 5 cr | $0,040 / 5 cr | $0,050 / 5 cr | $0,058 / 5 cr | | Stem (mọi stem) | gói trả phí | $0,40 / 60 cr | $0,47 / 60 cr | $0,59 / 60 cr | $0,70 / 60 cr | | Bản nhạc ACE-Step (lần đọc đầu) | $0 / 1 cr | $0,007 / 1 cr | $0,008 / 1 cr | $0,010 / 1 cr | $0,012 / 1 cr | | ACE-Step v1.5 XL (một bài) | $0 / 0 cr | $0 / 0 cr | $0 / 0 cr | $0 / 0 cr | $0 / 0 cr | So với các cách khác để gọi những model này từ code: | Model | useapi.net | Các API khác | |---|---|---| | ACE Music v1, v1.1 Preview | từ $0,013 một bài trên Artist trả theo năm, $0 với 20 credit mỗi ngày của gói Free | — | | ACE-Step v1.5 XL | $0 trên mọi gói ACE Music, kể cả gói Free | khoảng $0,14 một bài trên API của bên thứ ba [acestep.io](https://acestep.io/pricing), vốn đòi gói Studio $49 một tháng | Trên mọi gói ACE Music, kể cả gói Free, một bài hát ACE-Step v1.5 XL không tốn credit nào, trong khi API của acestep.io (bên thứ ba) đòi gói Studio $49 một tháng (khoảng 360 bài mỗi tháng, khoảng $0,14 một bài, tính đến tháng 11/2026). ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. ### Cách tạo bài hát bằng curl Bạn cần một API token của useapi.net, xem [Setup useapi.net](/docs/start-here/setup-useapi), và một tài khoản [ACE Music](https://acemusic.ai) có email và mật khẩu. Một [gói đăng ký $15 một tháng](/docs/subscription) bao gồm mọi API của useapi.net và 3 tài khoản ACE Music. Tài khoản ACE Music Free cũng dùng được: nó có 20 credit mỗi ngày, và bài hát ACE-Step không tốn credit nào. Các lệnh dùng [jq](https://jqlang.org) để đọc JSON. #### Thêm tài khoản ACE Music của bạn Export token, rồi thêm tài khoản một lần. API sẽ đăng nhập, đọc thông tin tài khoản và chỉ lưu lại nếu ACE Music chấp nhận mật khẩu: ```bash export USEAPI_TOKEN="user:12345-..." API=https://api.useapi.net/v1/acemusic curl -s -X POST "$API/accounts" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "example@example.com", "password": "your-acemusic-password" }' ``` Tài khoản tạo bằng Continue with Google hoặc số điện thoại cần đặt mật khẩu trước, xem [Setup ACE Music](/docs/start-here/setup-acemusic), trang này cũng có thể thêm tài khoản giúp bạn. #### Tạo bài hát từ prompt Mô tả bài hát bằng lời của bạn. ACE Music viết phong cách, lời và tên bài, rồi tạo hai bài hát. Đây chính là request đã tạo ra bài hát đầu tiên trên trang này: ```bash curl -s -X POST "$API/music" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A late-night neo-soul slow jam about two strangers sharing an umbrella at a bus stop in the rain and missing the last bus on purpose. Warm Rhodes piano, brushed drums, round upright bass, a smoky female lead with close three-part harmonies on the chorus.", "model": "acemusic-v1", "async": true }' | tee job.json | jq '{jobid, status, model}' ``` Với `async: true`, API trả `201` ngay lập tức kèm job. Một prompt dài tối đa 2.000 ký tự và nhận tối đa 3 bài hát tham chiếu cùng 3 hình ảnh, xem [Định hướng bài hát bằng âm thanh và hình ảnh của bạn](#guide-songs-with-your-own-audio-and-images). #### Kết quả trả về Trong lúc ACE Music viết lời, các bài hát ở trạng thái `planning` và mang tên `Untitled`, sau đó chuyển sang `queued` và `running`. Poll [GET /jobs/`jobid`](/docs/api-acemusic-v1/get-acemusic-jobs-jobid) khoảng 10 giây một lần. `jobid` chứa `:` và `@`, nên hãy URL-encode nó: ```bash curl -s "$API/jobs/$(jq -r .jobid job.json | jq -Rr @uri)" \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{status, songs: [.songs[] | {title, status, duration, audioUrl}]}' ``` Khi `status` là `completed`, mỗi bài hát mang theo các link của nó (các id dưới đây là bịa ra): ```json { "jobid": "j1115003713275918262m-u12345-email:example@example.com-task:so_7c1d9e3a5b2f4806a4e1c9d3.so_8b4f2e6a1c9d47e5a3b7c0d2-bot:acemusic", "type": "music", "status": "completed", "email": "example@example.com", "created": "2026-11-15T00:37:13.275Z", "model": "acemusic-v1", "modelUsed": "acemusic-v1", "songs": [ { "songId": "user:12345-example@example.com-song:so_7c1d9e3a5b2f4806a4e1c9d3", "taskId": "so_7c1d9e3a5b2f4806a4e1c9d3", "status": "succeeded", "title": "Let the 44 Roll By", "model": "acemusic-v1", "style": "Late-night neo-soul slow jam with a laid-back 1990s and early 2000s pocket, 72 BPM. …", "lyrics": "[Intro - Warm Rhodes chords, brushed snare rim clicks, subtle rain on asphalt]\n\n[Verse 1 …]\nWater dripping off the canvas seam\n…", "instrumental": false, "duration": 277.19, "audioUrl": "https://acemusic.ai/data/so_7c1d9e3a5b2f4806a4e1c9d3.mp3", "playUrl": "https://….r2.cloudflarestorage.com/acemusic-data-prod/users/…/audio/202611/….mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20261115T003902Z&X-Amz-Expires=3599&…", "playUrlExpires": "2026-11-15T01:39:01.000Z", "coverUrl": "https://acemusic.ai/data/so_7c1d9e3a5b2f4806a4e1c9d3-cover.jpg?v=1794703081642", "pageUrl": "https://acemusic.ai/song/r4k8w2n6p9tz", "created": "2026-11-15T00:37:13.300Z", "finished": "2026-11-15T00:38:42.208Z", "kind": "original", "score": false }, { "songId": "user:12345-example@example.com-song:so_8b4f2e6a1c9d47e5a3b7c0d2", "title": "Let the 44 Roll By", "duration": 253.99, "…": "…" } ], "completed": "2026-11-15T00:38:42.208Z" } ``` - `audioUrl` là link MP3 công khai của bài hát và không bao giờ thay đổi. `playUrl` là link trực tiếp tới cùng file MP3 đó dành cho trình phát trên web, có hiệu lực đến `playUrlExpires` (khoảng một giờ): một số trình duyệt, như Brave, chặn lần chuyển hướng phía sau `audioUrl`. - `songId` là thứ mà cover, mashup, stem, tải về và bản nhạc nhận vào. Nó chỉ rõ tài khoản chứa bài hát, nên các lệnh gọi đó chạy trên tài khoản ấy. - `model` là model bạn yêu cầu, `modelUsed` là model thực sự đã chạy (xem [mashup](#mash-up-two-or-three-songs)). `kind` là `original`, `cover`, `edit`, `mashup` hoặc `upload`, và `score` cho biết bài hát đã có bản nhạc hay chưa. - Bài hát mà ACE Music không tạo được sẽ có `status: "failed"`, lý do của ACE Music trong `error`, và `refunded: true` khi credit đã được hoàn lại. Và đây là bài đầu tiên trong hai bài hát đó: ACE Music v1 — "Let the 44 Roll By" · 4:37 · tạo trong 89 giây <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-let-the-44-roll-by-neo-soul-from-prompt.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### Đồng bộ, bất đồng bộ và webhook | Bạn gửi | Lệnh POST trả về | Sau đó | |---|---|---| | `async: true` | `201` ngay lập tức, kèm job | Poll [GET /jobs/`jobid`](/docs/api-acemusic-v1/get-acemusic-jobs-jobid) | | không có `async` | `200` kèm job đã xong, cùng JSON như trên | Đọc các bài hát từ phản hồi. Request vẫn chạy sau 100 giây sẽ trả `202` kèm job: hãy poll nó | | `replyUrl` và `replyRef` | như trên, cho cả đồng bộ lẫn bất đồng bộ | URL `https` công khai của bạn nhận một lệnh `POST` chứa job đã xong, kèm `replyRef` của bạn | Request ACE-Step không có `async` của chúng tôi trả về sau 37 giây, và webhook đến 12 giây sau khi các bài hát xong. Một job đọc được trong 7 ngày, và job vẫn chạy sau 30 phút kể từ lúc bắt đầu sẽ thất bại với `504`. [`async-webhooks/`](https://github.com/useapi/acemusic-api/tree/main/async-webhooks) chạy cả ba cách và có kèm một bộ nhận webhook nhỏ. <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash curl -s -X POST "$API/music" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A dreamy lo-fi hip hop beat for studying late at night: dusty vinyl crackle, mellow Rhodes chords, a soft upright bass and rain on the window", "model": "ace-step-1.5-xl", "replyUrl": "https://your-server.example.com/acemusic-hook", "replyRef": "lofi-1" }' | jq '{status, songs: [.songs[] | {title, duration, audioUrl}]}' ``` </details> ### Hát lời của riêng bạn Gửi `style` và `lyrics` thay cho `prompt`, và ACE Music sẽ hát lời của bạn theo phong cách của bạn: | Trường | Tác dụng | Giới hạn | |---|---|---| | `style` | Thể loại, nhạc cụ, cảm xúc, nhịp độ và giọng hát | 1.000 ký tự, 512 trên ACE-Step | | `lyrics` | Lời của bạn, mọi ngôn ngữ, với các tag `[Verse]`, `[Chorus]`, `[Bridge]` | 5.000 ký tự, 2.000 trên ACE-Step | | `title` | Tên của các bài hát. Nếu không có, ACE Music tự chọn | 80 ký tự | | `instrumental` | `true` để không có giọng hát. Một `style` không kèm `lyrics` cũng cho kết quả như vậy | | | `duration` | Độ dài tính bằng giây | 30 đến 600 trên ACE Music v1, 10 đến 240 trên ACE-Step | | `negative` | Những phong cách cần tránh | 200 ký tự, ACE Music v1 và ACE-Step | | `styleInfluence` | Mức độ bám sát phong cách | `0` đến `100`, mặc định `80`, ACE Music v1 và v1.1 | Đừng bao giờ gửi `prompt` cùng với các trường này: API sẽ trả `400` và nêu rõ trường cần bỏ. Bản ballad của chúng tôi yêu cầu `duration: 210` và nhận về hai bài dài 210 và 209 giây. Bài đó nằm trong phần [Ví dụ](#your-own-lyrics), cùng một bản không lời và một bài hát tiếng Tây Ban Nha. Chưa có lời? [POST /music/lyrics](/docs/api-acemusic-v1/post-acemusic-music-lyrics) viết lời và tên bài từ một yêu cầu, còn [POST /music/style](/docs/api-acemusic-v1/post-acemusic-music-style) biến vài từ thành một phong cách đầy đủ. Hai lệnh của chúng tôi trả về sau 6 và 4 giây, không tốn credit. Script: [`custom-lyrics/`](https://github.com/useapi/acemusic-api/tree/main/custom-lyrics). ### Điều chỉnh nhịp độ, tông và số chỉ nhịp với ACE-Step ACE-Step v1.5 XL nhận những thiết lập âm nhạc mà các model ACE Music không có, và bài hát của nó không tốn credit: | Tùy chọn | Giá trị | |---|---| | `bpm` | `30` đến `200` | | `timeSignature` | `2/4`, `3/4`, `4/4`, `6/8` | | `key` | `C major` đến `B minor` (C, C#, D, Eb, E, F, F#, G, Ab, A, Bb, B) | | `duration` | `10` đến `240` giây | | `negative` | những phong cách cần tránh, tối đa 200 ký tự | | `thinking` | `0` đến `100`: ACE-Step lên kế hoạch cho cả bài trước, sáng tạo khi thấp, ổn định khi cao | Cả ba bài ACE-Step của chúng tôi, một điệu valse 3/4, một điệu jig 6/8 và một bài drum and bass 174 bpm, đều có độ dài đúng như yêu cầu ([Ví dụ](#ace-step-at-a-set-tempo-key-and-meter)). Các tùy chọn này chỉ hoạt động ở `mode` `generate` trên `ace-step-1.5-xl`, và ở bất kỳ chỗ nào khác API sẽ trả `400 Parameter bpm does not apply to mode generate on acemusic-v1`. Script: [`ace-step-options/`](https://github.com/useapi/acemusic-api/tree/main/ace-step-options). ### Cover, remix và chỉnh sửa `mode` biến một request thành thao tác trên những bài hát bạn đã có. `references` nhận `songId` của chúng: bài hát do API tạo, bài hát trong [Thư viện](#your-library) của bạn hoặc file bạn tự upload. | `mode` | `references` | Chạy trên | Credit | Tác dụng | |---|---|---|---|---| | `cover` | 1 bài | `acemusic-v1.1`, hoặc ACE-Step trên `ace-step-1.5-xl` | 4 / 0 | Bài hát với `style` mới, bám theo giai điệu, hợp âm và cấu trúc của nó | | `remix` | 1 bài | `ace-step-1.5-xl` | 0 | `coverStrength` giữ lại bản gốc, `remixStrength` đưa bài hát xa khỏi bản gốc (`0` đến `100`) | | `edit` | 1 bài | `ace-step-1.5-xl` | 0 | Viết lại đoạn giữa giây `start` và `end` bằng `lyrics` mới, giữ nguyên phần còn lại | | `mashup` | 2 hoặc 3 bài | `acemusic-v1.1` | 4 | Một bài hát mới từ nhiều bài, xem bên dưới | ACE Music v1.1 bám theo giai điệu mà nó đọc từ bản nhạc của bài hát. Bản cover đầu tiên của chúng tôi cho một bài ACE Music v1 chưa có bản nhạc đã thất bại với `ref_no_melody`, và 4 credit được hoàn lại, nên giờ đây API tự đọc bản nhạc của bài ACE Music v1 trước, miễn phí, rồi mới làm cover hoặc mashup v1.1. Bài hát ACE-Step không được đọc tự động: nếu một bài trả `400` với `ref_no_melody`, hãy gọi [GET /music/score](#read-the-score) cho bài đó trước (1 credit), rồi gửi lại request. Script: [`covers-remix-edit/`](https://github.com/useapi/acemusic-api/tree/main/covers-remix-edit). #### Mashup hai hoặc ba bài hát `mode: "mashup"` tạo một bài hát từ 2 hoặc 3 bài trên cùng một tài khoản, kết hợp lời của chúng trừ khi bạn gửi `lyrics`. `audioInfluence` (0 đến 100, mặc định 60) quyết định mức độ bám theo các bài gốc. Mashup phải đọc các bài hát, nên nó chạy trên ACE Music v1.1 Preview ngay cả khi bạn yêu cầu v1, giống như trên website ACE Music: bài "Harbor Fiesta" của chúng tôi báo `"model": "acemusic-v1"` và `"modelUsed": "acemusic-v1.1"`, và credit tính theo model đã thực sự chạy. Điều tương tự xảy ra với `cover` yêu cầu trên v1, với prompt có nhiều hơn một tham chiếu trên ACE-Step, và đôi khi với prompt có một bài hát tham chiếu. Script: [`mashup/`](https://github.com/useapi/acemusic-api/tree/main/mashup). ### Định hướng bài hát bằng âm thanh và hình ảnh của bạn [POST /files](/docs/api-acemusic-v1/post-acemusic-files) nhận file làm phần thân request thô, kèm `Content-Type` của file: | Upload | Định dạng | Tối đa | Bạn nhận được | Dùng làm | |---|---|---|---|---| | Âm thanh | MP3, WAV, FLAC, OGG, M4A, AAC | 100 MB, 8 phút | Một `songId`: một bài hát trong Thư viện, với lời, phong cách, nhịp độ và giai điệu do ACE Music chép lại | Một trong tối đa 3 `references` của prompt, hoặc bài hát để cover, remix, chỉnh sửa hay mashup | | Hình ảnh | JPEG, PNG, WebP | 10 MB | Một `mediaId` | Một trong tối đa 3 `images` của prompt: ACE Music viết một bài hát về hình ảnh đó | ```bash curl -s -X POST "$API/files?title=Harbour%20Jig%20demo" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: audio/mpeg" \ --data-binary @harbour-jig-demo.mp3 | jq '{songId, status, duration, bpm: .upload.bpm}' ``` Bản upload "Harbour Jig" dài 90 giây của chúng tôi được chép lại trong 14 giây, và ACE Music nghe ra 115 bpm (chúng tôi đã yêu cầu 116). Một bức ảnh robot đang nhảy đã trở thành bài drum and bass về bộ lông xanh mòng két và đôi giày cổ cao màu cam của nó. Cả hai đều có trong phần [Ví dụ](#your-audio-and-pictures). File upload được tính vào hạn mức của tài khoản: 10 phút âm thanh trên Free, 30 trên Creator và 60 trên Artist. Script: [`upload-reference/`](https://github.com/useapi/acemusic-api/tree/main/upload-reference). ### Stem, tải về và bản nhạc Mọi bài hát đã xong đều có thể được tách, tải về và đọc thành bản nhạc: | Request | Gói | Credit | Bạn nhận được | |---|---|---|---| | [Stem](/docs/api-acemusic-v1/post-acemusic-music-stems), `mode: "vocals"` | Creator, Artist | 5 | Các file MP3 `vocal` và `instrumental` | | [Stem](/docs/api-acemusic-v1/post-acemusic-music-stems), `mode: "all"` | Creator, Artist | 60 | Mọi stem ACE Music tìm thấy, dưới dạng MP3 | | [Tải về](/docs/api-acemusic-v1/get-acemusic-music-download) `mp3` (mặc định) | mọi gói | 0 | `url` (giống `audioUrl`) và `playUrl` | | Tải về `wav` | Creator, Artist | 0 | Một link có hiệu lực 24 giờ. Không dành cho bài ACE-Step | | Tải về `midi`, `musicxml` | Creator, Artist | 0 | Chính file đó | | [Bản nhạc](/docs/api-acemusic-v1/get-acemusic-music-score) | mọi gói | 0, 1 cho bài ACE-Step ở lần đầu | [Ký hiệu ABC](https://abcnotation.com): giai điệu giọng hát, một bè nhạc cụ, hợp âm và các đoạn | #### Tách bài hát thành stem Lần tách giọng hát của "Paper Lanterns" mất khoảng 80 giây, và lần tách đầy đủ chưa tới 2 phút, ra 9 stem: giọng chính, bè phụ, trống, bass, guitar, keyboard, dây, synth và hiệu ứng ([nghe thử](#stems-of-paper-lanterns)). Link stem có hiệu lực 24 giờ, nên hãy đọc lại bài hát để lấy link mới. Tách lại một bài ở cùng chế độ sẽ trả kết quả ngay và không tốn gì. #### Tải MP3, WAV, MIDI và MusicXML ACE Music tạo WAV, MIDI và MusicXML ở request đầu tiên: API chờ tối đa một phút, rồi trả `202`, nên hãy gọi lại sau một phút. Với "Paper Lanterns", cả ba sẵn sàng chỉ trong vài giây: một file WAV 40 MB, một file MIDI 8 KB và một bản nhạc MusicXML 107 KB. <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash SONG="user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7" curl -s -G "$API/music/download" --data-urlencode "songId=$SONG" -d format=wav \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{url, expires}' curl -s -G "$API/music/download" --data-urlencode "songId=$SONG" -d format=midi \ -H "Authorization: Bearer $USEAPI_TOKEN" -o paper-lanterns.mid ``` </details> #### Đọc bản nhạc Bất kỳ công cụ ABC nào cũng chuyển bản nhạc thành bản nhạc in (sheet music). Với "Paper Lanterns", nó ghi 72 bpm, đúng nhịp độ chúng tôi yêu cầu trong phong cách. Bài hát ACE Music v1.1 có sẵn bản nhạc, và các bản cover và mashup v1.1 bám theo nó, xem [Cover, remix và chỉnh sửa](#covers-remixes-and-edits). <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash SONG="user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7" curl -s -G "$API/music/score" --data-urlencode "songId=$SONG" \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq -r .abc | head -14 ``` ``` X:1 T: M:2/4 L:1/16 Q:1/4=72 V: Vocal clef=treble name="Vocal Melody" snm="Vocal" V: Ins clef=treble name="Ins Melody" snm="Inst." K:Ab % intro V: Vocal Z|"Ab"z8|"Ab"z8|"Ab"z8| V: Ins Z|Ac2AcBA2|A2EAA2EA|Ac2AcBA2| ``` </details> Script: [`stems-and-downloads/`](https://github.com/useapi/acemusic-api/tree/main/stems-and-downloads), lưu các stem, mọi định dạng tải về và bản nhạc. ### Thư viện của bạn Mọi bài hát và file upload của tài khoản, dù tạo ở đây hay trên acemusic.ai, đều nằm trong Thư viện cho đến khi bị xóa: | Request | Tác dụng | |---|---| | [GET /music](/docs/api-acemusic-v1/get-acemusic-music) | Một trang bài hát, mới nhất trước, kèm `next` cho trang tiếp theo. Cần `email` khi có nhiều hơn một tài khoản. Bài hát của các job cũ hơn 7 ngày nằm ở đây | | [GET /music/`songId`](/docs/api-acemusic-v1/get-acemusic-music-songid) | Một bài hát với link mới, và các stem của nó nếu đã được tách | | [DELETE /music/`songId`](/docs/api-acemusic-v1/delete-acemusic-music-songid) | `204`: bài hát chuyển vào thùng rác của tài khoản trên acemusic.ai, và từ đó API trả `404` cho bài này | <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash SONG="user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7" curl -s -G "$API/music" --data-urlencode "email=example@example.com" -d limit=20 \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{next, songs: [.songs[] | {title, model, kind, songId}]}' curl -s "$API/music/$(jq -rn --arg v "$SONG" '$v|@uri')" \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{title, score, audioUrl, playUrl, stems: (.stems // {} | keys)}' curl -s -o /dev/null -w "%{http_code}\n" -X DELETE "$API/music/$(jq -rn --arg v "$SONG" '$v|@uri')" \ -H "Authorization: Bearer $USEAPI_TOKEN" ``` </details> Script: [`library/`](https://github.com/useapi/acemusic-api/tree/main/library). ### Nhiều tài khoản ACE Music Mỗi gói đăng ký useapi.net kết nối 3 tài khoản ACE Music, tổng cộng tối đa 100. Request không có `email` sẽ đi tới một tài khoản đang hoạt động tốt và còn chỗ trống, còn request nhắc tới một bài hát, một file upload hay một hình ảnh sẽ chạy trên tài khoản chứa nó. Mỗi tài khoản chạy đồng thời tối đa `maxJobs` request, mặc định là 4, đúng giới hạn của chính ACE Music. Một gói đăng ký $15 chạy đồng thời tối đa 12 request tạo bài hát (3 tài khoản × 4 mỗi tài khoản), và mỗi request tạo ra hai bài hát, nên 24 bài hát được tạo song song, trên ACE Music v1 hoặc trên ACE-Step v1.5 XL, model không tốn credit. Khi mọi tài khoản đều bận, API trả `429` kèm `Retry-After`, và nếu ACE Music từ chối mật khẩu thì tài khoản đó sẽ trả `596` cho đến khi bạn thêm lại nó. [GET /accounts/`email`](/docs/api-acemusic-v1/get-acemusic-accounts-email) đọc gói, số credit và giá credit theo thời gian thực, còn [POST /accounts](/docs/api-acemusic-v1/post-acemusic-accounts) chỉ với `email` và `maxJobs` thì chỉ thay đổi `maxJobs`. Script: [`accounts/`](https://github.com/useapi/acemusic-api/tree/main/accounts). <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash curl -s "$API/accounts/$(jq -rn --arg v "example@example.com" '$v|@uri')" \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{plan_name, credits, maxJobs, costs}' curl -s -X POST "$API/accounts" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "example@example.com", "maxJobs": 2 }' ``` </details> ### Dùng từ Claude, ChatGPT hoặc Cursor (MCP) Các tính năng này cũng có dưới dạng một [MCP server](/docs/api-acemusic-v1/mcp) được host sẵn với 15 công cụ, từ bài hát, cover và mashup đến stem, bản nhạc và upload. Trong Claude Code chỉ cần một lệnh: ```bash claude mcp add --transport http useapi-acemusic https://api.useapi.net/v1/acemusic/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` Cursor, VS Code và Windsurf dùng cùng URL và header, còn ứng dụng Claude và ChatGPT đăng nhập bằng OAuth, xem [Dùng trong ứng dụng Claude hoặc ChatGPT](/docs/api-acemusic-v1/mcp#use-it-in-the-claude-app-or-chatgpt). Sau đó cứ yêu cầu bằng lời thông thường: "Write lyrics about a cat who loves rainy days and sing them as acoustic indie folk on ACE Music v1". #### useapi.net so với MCP server riêng của ACE Music ACE Music también tiene su propio servidor MCP en `https://acemusic.ai/mcp`. Crea canciones de ACE Music v1 y v1.1 a partir del estilo y la letra que escribe tu asistente. El servidor de useapi.net funciona con la misma cuenta de ACE Music y agrega todo lo demás (al 18 de noviembre de 2026): | | MCP de ACE Music de useapi.net | MCP propio de ACE Music | |---|---|---| | ACE-Step v1.5 XL, 0 créditos en todos los planes | Sí | No, solo ACE Music v1 y v1.1 | | Descarga de MP3 en el plan Free | Sí | No, toda descarga requiere un plan de pago | | Covers, remixes, ediciones y mashups | Una llamada para cada uno, a partir de tus canciones | El asistente los arma a partir de una partitura transcrita | | Stems: voz e instrumental, o cada instrumento | Sí | No | | Partituras MusicXML | Sí | No, solo MIDI | | Estilo, letra y título escritos por ACE Music a partir de una idea de una línea | Sí | No, los escribe el asistente | | Varias cuentas de ACE Music en una sola conexión | Sí | Una cuenta por conexión | | Token de API para scripts, n8n y agentes sin interfaz, además de OAuth | Sí | Solo inicio de sesión con OAuth | | Las mismas llamadas por REST, con jobs y webhooks | Sí | No | useapi.net es un servicio de terceros, sin afiliación con ACE Music. ACE Music juga punya MCP server sendiri di `https://acemusic.ai/mcp`. Server itu membuat lagu ACE Music v1 dan v1.1 dari gaya dan lirik yang ditulis asisten Anda. Server useapi.net bekerja di akun ACE Music yang sama dan menambahkan sisanya (per 18 November 2026): | | MCP ACE Music dari useapi.net | MCP milik ACE Music sendiri | |---|---|---| | ACE-Step v1.5 XL, 0 kredit di semua paket | Ya | Tidak, hanya ACE Music v1 dan v1.1 | | Download MP3 di paket Free | Ya | Tidak, setiap download butuh paket berbayar | | Cover, remix, edit, dan mashup | Masing-masing satu panggilan, dari lagu Anda | Dirangkai oleh asisten dari partitur hasil transkripsi | | Stem: vokal dan instrumental, atau setiap instrumen | Ya | Tidak | | Partitur MusicXML | Ya | Tidak, hanya MIDI | | Gaya, lirik, dan judul ditulis ACE Music dari ide satu baris | Ya | Tidak, asisten yang menulisnya | | Beberapa akun ACE Music dalam satu koneksi | Ya | Satu akun per koneksi | | Token API untuk skrip, n8n, dan agen headless, plus OAuth | Ya | Hanya login OAuth | | Panggilan yang sama lewat REST, dengan job dan webhook | Ya | Tidak | useapi.net adalah layanan pihak ketiga dan tidak berafiliasi dengan ACE Music. ACE Music も独自の MCP サーバーを `https://acemusic.ai/mcp` で提供しています。こちらは、アシスタントが書いたスタイルと歌詞から ACE Music v1 と v1.1 の曲を作ります。useapi.net のサーバーは同じ ACE Music アカウントで動き、それ以外のすべてを補います(2026年11月18日時点)。 | | useapi.net の ACE Music MCP | ACE Music 独自の MCP | |---|---|---| | ACE-Step v1.5 XL、どのプランでも0クレジット | 対応 | 非対応、ACE Music v1 と v1.1 のみ | | Free プランでの MP3 ダウンロード | 対応 | 非対応、ダウンロードにはすべて有料プランが必要 | | カバー、リミックス、編集、マッシュアップ | お手持ちの曲から、それぞれ1回の呼び出しで | 書き起こした楽譜をもとにアシスタントが組み立てる | | ステム:ボーカルとインスト、または楽器ごと | 対応 | 非対応 | | MusicXML の楽譜 | 対応 | 非対応、MIDI のみ | | 1行のアイデアから ACE Music がスタイル、歌詞、タイトルを書く | 対応 | 非対応、アシスタントが書く | | 1つの接続で複数の ACE Music アカウント | 対応 | 1接続につき1アカウント | | スクリプト、n8n、ヘッドレスエージェント向けの API トークンと OAuth | 対応 | OAuth サインインのみ | | 同じ呼び出しを REST で、ジョブと Webhook 付きで | 対応 | 非対応 | useapi.net はサードパーティのサービスで、ACE Music とは提携していません。 O ACE Music também tem o próprio servidor MCP em `https://acemusic.ai/mcp`. Ele gera músicas do ACE Music v1 e v1.1 a partir do estilo e da letra que o seu assistente escreve. O servidor da useapi.net funciona na mesma conta do ACE Music e acrescenta todo o resto (em 18 de novembro de 2026): | | MCP do ACE Music da useapi.net | MCP do próprio ACE Music | |---|---|---| | ACE-Step v1.5 XL, 0 créditos em todos os planos | Sim | Não, só ACE Music v1 e v1.1 | | Download de MP3 no plano Free | Sim | Não, todo download exige um plano pago | | Covers, remixes, edições e mashups | Uma chamada para cada, a partir das suas músicas | Montados pelo assistente a partir de uma partitura transcrita | | Stems: vocal e instrumental, ou cada instrumento | Sim | Não | | Partituras MusicXML | Sim | Não, só MIDI | | Estilo, letra e título escritos pelo ACE Music a partir de uma ideia de uma linha | Sim | Não, o assistente escreve | | Várias contas do ACE Music em uma só conexão | Sim | Uma conta por conexão | | Token de API para scripts, n8n e agentes headless, além de OAuth | Sim | Só login com OAuth | | As mesmas chamadas via REST, com jobs e webhooks | Sim | Não | A useapi.net é um serviço de terceiros, sem afiliação com o ACE Music. ACE Music มี MCP server ของตัวเองด้วยที่ `https://acemusic.ai/mcp` ซึ่งสร้างเพลง ACE Music v1 และ v1.1 จากสไตล์และเนื้อเพลงที่ผู้ช่วย AI ของคุณเขียน ส่วน server ของ useapi.net ทำงานบนบัญชี ACE Music เดียวกันและเพิ่มส่วนที่เหลือทั้งหมด (ข้อมูล ณ วันที่ 18 พฤศจิกายน 2026): | | ACE Music MCP ของ useapi.net | MCP ของ ACE Music เอง | |---|---|---| | ACE-Step v1.5 XL ใช้ 0 เครดิตในทุกแพ็กเกจ | ได้ | ไม่ได้ มีแค่ ACE Music v1 และ v1.1 | | ดาวน์โหลด MP3 ในแพ็กเกจ Free | ได้ | ไม่ได้ ทุกการดาวน์โหลดต้องใช้แพ็กเกจเสียเงิน | | คัฟเวอร์ รีมิกซ์ การแก้ไข และแมชอัป | เรียกครั้งเดียวต่ออย่าง จากเพลงของคุณ | ผู้ช่วย AI ประกอบเองจากโน้ตเพลงที่ถอดออกมา | | สเต็ม: เสียงร้องกับดนตรี หรือแยกทุกเครื่องดนตรี | ได้ | ไม่ได้ | | โน้ตเพลง MusicXML | ได้ | ไม่ได้ มีแค่ MIDI | | ACE Music เขียนสไตล์ เนื้อเพลง และชื่อเพลงจากไอเดียบรรทัดเดียว | ได้ | ไม่ได้ ผู้ช่วย AI ต้องเขียนเอง | | หลายบัญชี ACE Music ในการเชื่อมต่อเดียว | ได้ | หนึ่งบัญชีต่อการเชื่อมต่อ | | API token สำหรับสคริปต์ n8n และเอเจนต์ที่ไม่มีหน้าจอ พร้อม OAuth | ได้ | ล็อกอินด้วย OAuth เท่านั้น | | เรียกแบบเดียวกันผ่าน REST พร้อมงานและ webhook | ได้ | ไม่ได้ | useapi.net เป็นบริการของบุคคลที่สาม ไม่มีส่วนเกี่ยวข้องกับ ACE Music ACE Music cũng có MCP server riêng tại `https://acemusic.ai/mcp`. Server này tạo bài hát ACE Music v1 và v1.1 từ phong cách và lời bài hát do trợ lý của bạn viết. Server của useapi.net chạy trên cùng tài khoản ACE Music và bổ sung phần còn lại (tính đến 18 tháng 11 năm 2026): | | MCP ACE Music của useapi.net | MCP riêng của ACE Music | |---|---|---| | ACE-Step v1.5 XL, 0 credit trên mọi gói | Có | Không, chỉ ACE Music v1 và v1.1 | | Tải MP3 trên gói Free | Có | Không, mọi lượt tải đều cần gói trả phí | | Cover, remix, chỉnh sửa và mashup | Mỗi thứ một lệnh gọi, từ bài hát của bạn | Trợ lý tự ghép lại từ bản nhạc được chép ra | | Stem: giọng hát và nhạc nền, hoặc từng nhạc cụ | Có | Không | | Bản nhạc MusicXML | Có | Không, chỉ MIDI | | Phong cách, lời và tên bài do ACE Music viết từ một ý tưởng một dòng | Có | Không, trợ lý tự viết | | Nhiều tài khoản ACE Music trong một kết nối | Có | Một tài khoản cho mỗi kết nối | | API token cho script, n8n và agent chạy không giao diện, cùng với OAuth | Có | Chỉ đăng nhập OAuth | | Cùng các lệnh gọi qua REST, có job và webhook | Có | Không | useapi.net là dịch vụ của bên thứ ba, không liên kết với ACE Music. ACE Music 也在 `https://acemusic.ai/mcp` 运行自己的 MCP 服务器。它根据你的助手写好的风格和歌词生成 ACE Music v1 和 v1.1 歌曲。useapi.net 的服务器使用同一个 ACE Music 账号,并补上其余的一切(截至 2026 年 11 月 18 日): | | useapi.net ACE Music MCP | ACE Music 自己的 MCP | |---|---|---| | ACE-Step v1.5 XL,所有套餐都是 0 积分 | 支持 | 不支持,只有 ACE Music v1 和 v1.1 | | 免费套餐下载 MP3 | 支持 | 不支持,任何下载都需要付费套餐 | | 翻唱、重混、编辑和混搭 | 基于你的歌曲,各一次调用 | 由助手根据转写出的乐谱拼凑完成 | | 分轨:人声和伴奏,或每件乐器 | 支持 | 不支持 | | MusicXML 乐谱 | 支持 | 不支持,只有 MIDI | | 由 ACE Music 根据一句话的想法写出风格、歌词和标题 | 支持 | 不支持,由助手来写 | | 一个连接中使用多个 ACE Music 账号 | 支持 | 每个连接一个账号 | | 用于脚本、n8n 和无界面智能体的 API Token,另有 OAuth | 支持 | 只能 OAuth 登录 | | 通过 REST 进行同样的调用,带任务和 webhook | 支持 | 不支持 | useapi.net 是第三方服务,与 ACE Music 无关联。 ACE Music also runs its own MCP server at `https://acemusic.ai/mcp`. It makes ACE Music v1 and v1.1 songs from the style and lyrics your assistant writes. The useapi.net server works on the same ACE Music account and adds the rest (as of November 18, 2026): | | useapi.net ACE Music MCP | ACE Music's own MCP | |---|---|---| | ACE-Step v1.5 XL, 0 credits on every plan | Yes | No, ACE Music v1 and v1.1 only | | MP3 download on the Free plan | Yes | No, every download needs a paid plan | | Covers, remixes, edits and mashups | One call each, from your songs | Pieced together by the assistant from a transcribed score | | Stems: vocals and instrumental, or every instrument | Yes | No | | MusicXML scores | Yes | No, MIDI only | | Style, lyrics and title written by ACE Music from a one-line idea | Yes | No, the assistant writes them | | Several ACE Music accounts in one connection | Yes | One account per connection | | API token for scripts, n8n and headless agents, plus OAuth | Yes | OAuth sign-in only | | The same calls over REST, with jobs and webhooks | Yes | No | useapi.net is a third-party service, not affiliated with ACE Music. ### Tạo hàng loạt bằng script [Repo GitHub `acemusic-api`](https://github.com/useapi/acemusic-api) có một ví dụ cho mỗi tính năng, được link từ từng phần ở trên: một script Node.js và một bản Python tương ứng, không cần cài đặt gì. Mỗi script đọc request từ file `prompts.json` mà bạn chỉnh sửa, chạy tối đa 4 request cùng lúc, poll các job, và lưu cả hai bài hát, ảnh bìa, bản ghi job và file `ledger.jsonl` ghi số credit đã dùng vào thư mục `output/` của nó. Bạn cần [Node.js](https://nodejs.org) 21 trở lên hoặc [Python](https://www.python.org) 3.8 trở lên. `--only 3` chạy prompt thứ ba bên dưới, một bài ACE-Step không tốn credit, nên chạy được trên tài khoản Free: ```bash git clone https://github.com/useapi/acemusic-api.git && cd acemusic-api export USEAPI_TOKEN="user:12345-..." node songs-from-prompt/songs-from-prompt.mjs --only 3 ``` Mỗi bản ghi job đã lưu chứa `songId` của các bài hát, và `--from <job>.json --pick 1` chuyển bài số 1 sang script tiếp theo để cover, mashup hoặc tách stem. <details markdown="block"> <summary>Mở `songs-from-prompt/prompts.json`</summary> ```json [ { "_about": "ACE Music v1 (the default model, 4 credits for two songs): ACE Music writes the style, lyrics and title from your idea", "prompt": "A late-night neo-soul slow jam about two strangers sharing an umbrella at a bus stop in the rain and missing the last bus on purpose. Warm Rhodes piano, brushed drums, round upright bass, a smoky female lead with close three-part harmonies on the chorus.", "model": "acemusic-v1" }, { "_about": "ACE Music v1.1 Preview (4 credits): writes a score first, then the audio", "prompt": "An anthemic Celtic folk-rock singalong about a fishing crew racing a storm back to the harbor. Fiddle and tin whistle hooks, stomping kick drum, bodhran, a gravelly male lead and the whole crew shouting the chorus.", "model": "acemusic-v1.1" }, { "_about": "ACE-Step v1.5 XL (no credits on any ACE Music plan, the Free plan included)", "prompt": "A breezy bossa nova for a lazy Sunday afternoon in Lisbon: nylon-string guitar, soft brushed snare, upright bass, a gentle flute line and a warm male and female duet sung in Portuguese.", "model": "ace-step-1.5-xl" } ] ``` </details> ### Ví dụ Mọi bài hát dưới đây được tạo ngày 14 tháng 11 năm 2026 (giờ PST) bằng các script của repo trên một tài khoản ACE Music Artist, và là bài đầu tiên trong hai bài của mỗi request. Tên bài do ACE Music đặt, trừ khi chúng tôi tự đặt, thời gian tính từ lúc gửi request đến khi cả hai bài xong, và các lệnh gọi dùng id bịa ra. #### Bài hát từ một bức ảnh Đưa vào một bức ảnh và một câu mô tả phong cách, nhận về hai bài hát hoàn chỉnh. Chúng tôi upload bức ảnh linh vật robot đang nhảy này và yêu cầu drum and bass, và ACE Music viết lời từ những gì nó thấy: "Teal fur shaking on the concrete floor, orange high-tops squeaking by the studio door". <img src="https://media.useapi.net/blog/2026-09-07-260907/dreamina-longvideo-ref-robot-mascot.png" alt="Linh vật robot lông xù màu xanh mòng két, đầu hình hộp, có ăng-ten và mắt phát sáng, đang nhảy trong đôi giày cổ cao màu cam" style="width: 100%; max-width: 220px;" loading="lazy"> ``` Bouncy, playful drum and bass for a dancing robot mascot: rolling breakbeats at 174 bpm, a wobbly reese bass, bleepy robot synth hooks, vocoder chops, cheeky and upbeat. ``` ACE Music v1 — "Bleep Boop Bounce" · 2:47 · tạo trong 72 giây <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/files' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: image/png' \ --data-binary @robot-mascot.png curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "Bouncy, playful drum and bass for a dancing robot mascot: rolling breakbeats at 174 bpm, a wobbly reese bass, bleepy robot synth hooks, vocoder chops, cheeky and upbeat.", "model": "acemusic-v1", "images": ["user:12345-example@example.com-media:cx_3b9e1d7a5c2f48e0a6d4b8c1"], "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-bleep-boop-bounce-drum-and-bass-from-robot-image.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Bài hát dưới dạng YouTube Short, kèm bức ảnh: [Bleep Boop Bounce trên YouTube](https://youtube.com/shorts/z_aOmILvIng). #### Bài hát từ prompt Bài hát ACE Music v1 tạo từ prompt, "Let the 44 Roll By", nằm trong [phần hướng dẫn từng bước](#what-you-get-back). Thêm hai prompt nữa, trên hai model còn lại: ``` An anthemic Celtic folk-rock singalong about a fishing crew racing a storm back to the harbor. Fiddle and tin whistle hooks, stomping kick drum, bodhran, a gravelly male lead and the whole crew shouting the chorus. ``` ACE Music v1.1 Preview — "Haul for the Harbor Light" · 2:51 · tạo trong 43 giây <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "An anthemic Celtic folk-rock singalong about a fishing crew racing a storm back to the harbor. Fiddle and tin whistle hooks, stomping kick drum, bodhran, a gravelly male lead and the whole crew shouting the chorus.", "model": "acemusic-v1.1", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-1-haul-for-the-harbor-light-celtic-folk-rock-from-prompt.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ``` A breezy bossa nova for a lazy Sunday afternoon in Lisbon: nylon-string guitar, soft brushed snare, upright bass, a gentle flute line and a warm male and female duet sung in Portuguese. ``` ACE-Step v1.5 XL, không tốn credit — "Domingo em Alfama" · 3:28 <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "A breezy bossa nova for a lazy Sunday afternoon in Lisbon: nylon-string guitar, soft brushed snare, upright bass, a gentle flute line and a warm male and female duet sung in Portuguese.", "model": "ace-step-1.5-xl", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-domingo-em-alfama-bossa-nova-from-prompt.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### Lời của riêng bạn Hai đoạn verse, một pre-chorus, một bridge và một outro do chúng tôi tự viết, yêu cầu dài 210 giây: ``` Style: cinematic indie pop ballad, felt piano, swelling strings, deep heartbeat kick, intimate female vocal that opens up into a soaring chorus, 72 bpm Lyrics: [Verse 1] We wrote our names on paper lanterns / Down by the river in July … [Chorus] Light it up and let it go / Every word I never said out loud … ``` ACE Music v1 — "Paper Lanterns" · 3:29 · tạo trong 61 giây <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "title": "Paper Lanterns", "style": "cinematic indie pop ballad, felt piano, swelling strings, deep heartbeat kick, intimate female vocal that opens up into a soaring chorus, 72 bpm", "lyrics": "[Verse 1]\nWe wrote our names on paper lanterns\nDown by the river in July\nYou said the wind would know the answer\nIf we just let the fire fly\nYour hand was shaking, mine was steady\nAt least that'\''s how I tell it now\nWe watched them climb until the city\nWas just a glow beneath the clouds\n\n[Pre-Chorus]\nSo every summer I come back here\nStrike a match and hold it near\n\n[Chorus]\nLight it up and let it go\nEvery word I never said out loud\nLight it up and let it go\nHigher than the both of us somehow\nAnd if it finds you anyhow\nTell me you can see it from the clouds\n\n[Verse 2]\nThey tore the old pier down last winter\nPut up a fence and painted lines\nBut I still know the way by heartbeat\nI find the water every time\nI keep a lighter in my pocket\nI keep your laugh inside my head\nI fold the paper like you showed me\nAnd write the things I should have said\n\n[Pre-Chorus]\nSo every summer I come back here\nStrike a match and hold it near\n\n[Chorus]\nLight it up and let it go\nEvery word I never said out loud\nLight it up and let it go\nHigher than the both of us somehow\nAnd if it finds you anyhow\nTell me you can see it from the clouds\n\n[Bridge]\nPaper and fire, paper and fire\nNothing this light should rise so high\nPaper and fire, paper and fire\nMaybe that'\''s how we say goodbye\n\n[Final Chorus]\nLight it up and let it go\nEvery word I never said out loud\nLight it up and let it go\nHigher than the both of us somehow\n\n[Outro]\nDown by the river in July", "model": "acemusic-v1", "duration": 210, "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-paper-lanterns-custom-lyrics.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Một bản không lời: `instrumental: true`, 150 giây, không có giọng hát, hợp xướng hay guitar acoustic: ``` Style: cinematic synthwave instrumental for a night drive: pulsing analog bass arpeggio, gated reverb drums, lush pads, a soaring lead synth melody, builds to a big final section, 108 bpm ``` ACE Music v1 — "Neon Overpass" · 2:29 · tạo trong 46 giây <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "title": "Neon Overpass", "style": "cinematic synthwave instrumental for a night drive: pulsing analog bass arpeggio, gated reverb drums, lush pads, a soaring lead synth melody, builds to a big final section, 108 bpm", "instrumental": true, "model": "acemusic-v1", "duration": 150, "negative": "vocals, choir, acoustic guitar", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-neon-overpass-synthwave-instrumental.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lời tiếng Tây Ban Nha về một bữa tiệc trên sân thượng giữa lúc mất điện: ``` Style: modern cumbia pop, bright accordion hooks, güira and congas, warm bass, a festive male lead with a crowd shouting the chorus, 98 bpm Lyrics: [Chorus] Bailando en la azotea / Con las estrellas de farol … ``` ACE Music v1 — "Bailando en la Azotea" · 2:32 · tạo trong 46 giây <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "title": "Bailando en la Azotea", "style": "modern cumbia pop, bright accordion hooks, güira and congas, warm bass, a festive male lead with a crowd shouting the chorus, 98 bpm", "lyrics": "[Verse 1]\nSe fue la luz en todo el barrio\nY nadie quiere irse a dormir\nDoña Rosa saca el radio viejo\nY la noche empieza a sonreír\nLos vecinos suben con sus sillas\nAlguien trae limones y café\nY la ciudad allá abajo, oscura\nNos mira bailar sin saber por qué\n\n[Pre-Chorus]\nSube, sube, que la luna está invitando\nSube, sube, que la calle está cantando\n\n[Chorus]\nBailando en la azotea\nCon las estrellas de farol\nQue se entere todo el mundo\nQue esta noche no hay apagón\nBailando en la azotea\nCon el corazón de tambor\nSi se apaga la ciudad entera\nAquí arriba sobra amor\n\n[Verse 2]\nEl abuelo saca la guitarra\nLa vecina de enfrente se animó\nLos niños corren entre las sábanas\nQue el viento de la tarde colgó\nNadie sabe cuándo vuelve la corriente\nY la verdad, a nadie le importó\nEsta fiesta no la paga nadie\nEsta fiesta la invitó el apagón\n\n[Chorus]\nBailando en la azotea\nCon las estrellas de farol\nQue se entere todo el mundo\nQue esta noche no hay apagón\nBailando en la azotea\nCon el corazón de tambor\nSi se apaga la ciudad entera\nAquí arriba sobra amor\n\n[Outro]\nQue esta noche no hay apagón", "model": "acemusic-v1", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-bailando-en-la-azotea-spanish-cumbia.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lời do công cụ viết lời viết, phong cách do công cụ viết phong cách viết, ACE-Step hát: ``` Lyrics writer: A wistful country song about an old pickup truck that still has her mixtape stuck in the tape deck Style writer: classic country ballad, pedal steel, warm baritone ``` ACE-Step v1.5 XL, không tốn credit — "Side B Forever" · 3:35 · tạo trong 40 giây, sau 6 giây cho phần lời và 4 giây cho phong cách <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music/lyrics' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "A wistful country song about an old pickup truck that still has her mixtape stuck in the tape deck", "style": "classic country ballad, pedal steel, warm baritone", "model": "ace-step-1.5-xl" }' > lyrics.json curl -X POST 'https://api.useapi.net/v1/acemusic/music/style' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "style": "classic country ballad, pedal steel, warm baritone", "model": "ace-step-1.5-xl" }' > style.json # sing what the writers returned jq -n --slurpfile l lyrics.json --slurpfile s style.json \ '{title: $l[0].title, lyrics: $l[0].lyrics, style: $s[0].style, model: "ace-step-1.5-xl", async: true}' | curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d @- ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-side-b-forever-lyrics-and-style-writers.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### ACE-Step với nhịp độ, tông và số chỉ nhịp cố định Mỗi bài đều có độ dài đúng như yêu cầu. ``` 3/4 · 84 bpm · D minor · 120 s · thinking 60 · avoid: trap drums, EDM, autotune Style: dark cabaret waltz, accordion, pizzicato strings, upright bass, brushed snare, theatrical female vocal ``` ACE-Step v1.5 XL, không tốn credit — "Midnight Waltz" · 2:00 · tạo trong 31 giây <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "model": "ace-step-1.5-xl", "title": "Midnight Waltz", "style": "dark cabaret waltz, accordion, pizzicato strings, upright bass, brushed snare, theatrical female vocal", "lyrics": "[Verse 1]\nThe band plays slow when the lights go low\nAnd the chandeliers begin to sway\nTake my hand, we will dance till the candles stand\nIn puddles of yesterday\n\n[Chorus]\nOne, two, three, turn around with me\nRound and round till the morning comes\nOne, two, three, oh don'\''t let me be\nThe last one dancing when the music'\''s done\n\n[Verse 2]\nThe clock strikes twelve and it laughs at itself\nEvery mirror wears a stranger'\''s face\nHold me close, we are only ghosts\nWho forgot to leave this place\n\n[Chorus]\nOne, two, three, turn around with me\nRound and round till the morning comes\nOne, two, three, oh don'\''t let me be\nThe last one dancing when the music'\''s done", "bpm": 84, "timeSignature": "3/4", "key": "D minor", "duration": 120, "negative": "trap drums, EDM, autotune", "thinking": 60, "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-midnight-waltz-3-4-84-bpm-d-minor.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ``` 6/8 · 116 bpm · G major · 90 s · instrumental Style: lively celtic instrumental jig, fiddle and tin whistle trading the melody, bodhran, strummed bouzouki, foot stomps ``` ACE-Step v1.5 XL, không tốn credit — "Harbour Jig" · 1:30 · tạo trong 20 giây <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "model": "ace-step-1.5-xl", "title": "Harbour Jig", "style": "lively celtic instrumental jig, fiddle and tin whistle trading the melody, bodhran, strummed bouzouki, foot stomps", "instrumental": true, "bpm": 116, "timeSignature": "6/8", "key": "G major", "duration": 90, "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-harbour-jig-6-8-116-bpm-g-major.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ``` 4/4 · 174 bpm · F minor · 150 s · thinking 80 Style: liquid drum and bass, rolling breakbeats, deep warm sub bass, airy pads, soulful female vocal ``` ACE-Step v1.5 XL, không tốn credit — "Almost Home" · 2:30 · tạo trong 41 giây <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "model": "ace-step-1.5-xl", "title": "Almost Home", "style": "liquid drum and bass, rolling breakbeats, deep warm sub bass, airy pads, soulful female vocal", "lyrics": "[Verse]\nCity lights in the rear view mirror\nRunning on a borrowed night\nEvery bridge is a little bit nearer\nEvery tunnel full of light\n\n[Chorus]\nHold on, we'\''re almost home\nEvery signal turning green\nHold on, you'\''re not alone\nFaster than the in-between\n\n[Verse]\nRadio low and the windows open\nBreathing in the summer rain\nEvery promise we left unspoken\nRushing back to us again\n\n[Chorus]\nHold on, we'\''re almost home\nEvery signal turning green\nHold on, you'\''re not alone\nFaster than the in-between", "bpm": 174, "timeSignature": "4/4", "key": "F minor", "duration": 150, "thinking": 80, "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-almost-home-drum-and-bass-174-bpm-f-minor.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### Một bản cover, một bản remix và một bản chỉnh sửa "Paper Lanterns" dưới dạng cover, theo phong cách mới mà vẫn giữ giai điệu: ``` mode: cover · stripped-back acoustic folk cover, fingerpicked steel-string guitar, warm cello, soft close-mic'd male vocal ``` ACE Music v1.1 Preview — "Paper Lanterns (Acoustic Folk Cover)" · 3:34 · tạo trong 72 giây <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash # our script read the score first (free for an ACE Music v1 song; the API now does this by itself) curl 'https://api.useapi.net/v1/acemusic/music/score?songId=user%3A12345-example%40example.com-song%3Aso_4e7b2c9d0a5f4183b6d8e2c7' \ -H 'Authorization: Bearer user:12345-…' > /dev/null curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "mode": "cover", "model": "acemusic-v1.1", "references": ["user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7"], "style": "stripped-back acoustic folk cover, fingerpicked steel-string guitar, warm cello, soft close-mic'\''d male vocal", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-1-paper-lanterns-acoustic-folk-cover.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> "Bailando en la Azotea" thành deep house. Chúng tôi không gửi tên bài, nên ACE Music đặt tên là "Reference 1": ``` mode: remix · coverStrength 40 · remixStrength 50 · deep house remix, four-on-the-floor kick, plucky chords, rolling bassline, filtered vocal chops ``` ACE-Step v1.5 XL, không tốn credit — "Reference 1" · 2:32 · tạo trong 31 giây <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "mode": "remix", "model": "ace-step-1.5-xl", "references": ["user:12345-example@example.com-song:so_9d3b7e2c1a6f4085b8e4d1c6"], "style": "deep house remix, four-on-the-floor kick, plucky chords, rolling bassline, filtered vocal chops", "coverStrength": 40, "remixStrength": 50, "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-bailando-en-la-azotea-house-remix.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> "Paper Lanterns" với lời mới cho giây 30 đến 50, giữ nguyên phần còn lại: ``` mode: edit · start 30 · end 50 Lyrics: We wrote our names on paper lanterns / Down by the harbor in the snow / You said the stars would keep the answer / If we were brave enough to go ``` ACE-Step v1.5 XL, không tốn credit — "Reference 1" · 3:29 · tạo trong 41 giây <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "mode": "edit", "model": "ace-step-1.5-xl", "references": ["user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7"], "start": 30, "end": 50, "style": "cinematic indie pop ballad, felt piano, swelling strings, intimate female vocal", "lyrics": "We wrote our names on paper lanterns\nDown by the harbor in the snow\nYou said the stars would keep the answer\nIf we were brave enough to go", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-paper-lanterns-edit-seconds-30-50.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### Mashup "Paper Lanterns" và "Let the 44 Roll By": ``` upbeat neo-soul pop mashup, punchy live drums, warm Rhodes and strings, female lead with a gospel-tinged choir on the chorus · audioInfluence 60 ``` ACE Music v1.1 Preview — "Lanterns at the Bus Stop" · 3:58 · tạo trong 83 giây <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash # our script read each song's score first (the API now does this by itself for ACE Music v1 songs) curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "mode": "mashup", "model": "acemusic-v1.1", "references": ["user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7", "user:12345-example@example.com-song:so_7c1d9e3a5b2f4806a4e1c9d3"], "title": "Lanterns at the Bus Stop", "style": "upbeat neo-soul pop mashup, punchy live drums, warm Rhodes and strings, female lead with a gospel-tinged choir on the chorus", "audioInfluence": 60, "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-1-mashup-lanterns-at-the-bus-stop.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> "Haul for the Harbor Light" và "Bailando en la Azotea", yêu cầu trên ACE Music v1: ``` festive celtic cumbia mashup, fiddle and accordion trading hooks, congas and bodhran, stomping kick, male lead with a big crowd chorus ``` ACE Music v1.1 Preview (yêu cầu: v1) — "Harbor Fiesta" · 2:38 · tạo trong 74 giây <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash # our script read each song's score first (the API now does this by itself for ACE Music v1 songs) curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "mode": "mashup", "model": "acemusic-v1", "references": ["user:12345-example@example.com-song:so_2a8f6c1e9d4b47f3b0c5e8a2", "user:12345-example@example.com-song:so_9d3b7e2c1a6f4085b8e4d1c6"], "title": "Harbor Fiesta", "style": "festive celtic cumbia mashup, fiddle and accordion trading hooks, congas and bodhran, stomping kick, male lead with a big crowd chorus", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-1-mashup-harbor-fiesta-asked-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Ba bài hát cùng lúc: "Paper Lanterns", "Bailando en la Azotea" và "Let the 44 Roll By": ``` warm late-night soul-pop medley, Rhodes and strings, light latin percussion, female lead with a male answer on the last chorus ``` ACE Music v1.1 Preview — "Three Songs, One Night" · 3:32 · tạo trong 43 giây <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash # our script read each song's score first (the API now does this by itself for ACE Music v1 songs) curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "mode": "mashup", "model": "acemusic-v1.1", "references": ["user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7", "user:12345-example@example.com-song:so_9d3b7e2c1a6f4085b8e4d1c6", "user:12345-example@example.com-song:so_7c1d9e3a5b2f4806a4e1c9d3"], "title": "Three Songs, One Night", "style": "warm late-night soul-pop medley, Rhodes and strings, light latin percussion, female lead with a male answer on the last chorus", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-1-mashup-three-songs-one-night.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### Âm thanh và hình ảnh của bạn Bản "Harbour Jig" ở trên, được upload dưới dạng MP3 và dùng làm tham chiếu cho một prompt. ACE Music chạy nó trên v1.1 để giữ giai điệu: ``` A rowdy pub singalong with a big shouted chorus about the last ferry home, built on the tune of this recording ``` ACE Music v1.1 Preview (yêu cầu: v1) — "Last Ferry Home" · 1:36 · tạo trong 52 giây <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/files?title=Harbour%20Jig%20demo' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: audio/mpeg' \ --data-binary @harbour-jig-demo.mp3 curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "A rowdy pub singalong with a big shouted chorus about the last ferry home, built on the tune of this recording", "model": "acemusic-v1", "references": ["user:12345-example@example.com-song:so_5f1a3c8e7b2d49a6c3e0f7b9"], "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-1-last-ferry-home-from-uploaded-jig.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### Các stem của "Paper Lanterns" Giọng hát và nhạc nền từ `mode: "vocals"` (5 credit), sau đó là trống và dàn dây trong 9 stem từ `mode: "all"` (60 credit). <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music/stems' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "songId": "user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7", "mode": "vocals", "async": true }' curl -X POST 'https://api.useapi.net/v1/acemusic/music/stems' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "songId": "user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7", "mode": "all", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-paper-lanterns-stem-vocal.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-paper-lanterns-stem-instrumental.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-paper-lanterns-stem-drums.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-paper-lanterns-stem-strings.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ### Câu hỏi thường gặp **Có API ACE Music không?** Qua useapi.net thì có: [ACE Music API](/docs/api-acemusic-v1) chạy ACE Music v1, ACE Music v1.1 Preview và ACE-Step v1.5 XL qua REST trên tài khoản ACE Music của bạn, có cover, mashup, stem và MIDI. **Có API ACE-Step miễn phí không?** Qua useapi.net thì có: một bài hát ACE-Step v1.5 XL không tốn credit trên bất kỳ gói ACE Music nào, kể cả gói Free, với các thiết lập nhịp độ, tông, số chỉ nhịp và độ dài, cùng remix và chỉnh sửa. Bên thứ ba acestep.io chỉ cung cấp API ACE-Step trên gói Studio $49 một tháng, khoảng $0,14 một bài (tính đến tháng 11/2026). **Một bài hát ACE Music v1 qua API giá bao nhiêu?** Qua useapi.net, một bài hát ACE Music v1 tốn 2 credit trong gói ACE Music của bạn: $0,013 trên Artist trả theo năm và $0,023 trên Artist trả theo tháng, không cộng thêm gì theo bài hát. Xem [Giá](#pricing). **Có MCP server cho ACE Music không?** Qua useapi.net thì có, và nó làm được nhiều hơn server riêng của ACE Music tại `acemusic.ai/mcp`: [ACE Music MCP server](/docs/api-acemusic-v1/mcp) được host sẵn bổ sung model miễn phí ACE-Step v1.5 XL, tải MP3 trên gói Free, stem, cover, remix, chỉnh sửa và mashup chỉ với một lệnh gọi, MusicXML, và nhiều tài khoản sau một API token. Server riêng của ACE Music tạo bài hát v1 và v1.1 từ lời do trợ lý của bạn viết, và mọi lượt tải đều cần gói trả phí. Xem [bảng so sánh](#useapinet-vs-ace-musics-own-mcp-server). ### Kết luận Một lệnh POST tạo hai bài hát trên model dẫn đầu bảng xếp hạng giọng hát, bài hát ACE-Step không tốn gì, và mọi bài hát đều có thể đi tiếp thành cover, mashup, stem hoặc file MIDI ở lệnh gọi kế tiếp. Clone [repo `acemusic-api`](https://github.com/useapi/acemusic-api), chạy `songs-from-prompt/` với `--only 3` trên tài khoản Free, và xem [POST /music](/docs/api-acemusic-v1/post-acemusic-music) để biết mọi tùy chọn. Ghé <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> hoặc <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> của chúng tôi cho mọi câu hỏi hỗ trợ. === URL: https://useapi.net/docs/articles/ace-music-api-tutorial-zh === Document URL: https://useapi.net/docs/articles/ace-music-api-tutorial-zh --- layout: default title: "如何用 ACE Music API 生成 AI 歌曲" description: "通过 useapi.net 的 ACE Music API,用 ACE Music v1、v1.1 和免费的 ACE-Step v1.5 XL 生成歌曲:提示词、自己的歌词、翻唱、混搭、分轨、MIDI,附 curl 和代码。" keywords: [ACE Music API, ACE Music v1 API, ACE-Step API, ACE-Step v1.5 XL, AI song generator API, text to music API, Suno alternative, AI music API, stems API, MIDI, MusicXML, mashup, cover song AI, MCP server, curl, ACE Music API 教程, AI 歌曲生成 API, AI 音乐 API, 文本生成音乐, Suno 替代, 分轨, 翻唱, 混搭, 中文教程, Chinese tutorial] image: https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-paper-lanterns-cover-art.jpg parent: Articles nav_exclude: true lang: zh-CN date: 2026-11-14 last_modified: 2026-11-18 nav_order: 302 repo: https://github.com/useapi/acemusic-api translation_key: ace-music-tutorial --- ## 如何用 ACE Music API 生成 AI 歌曲 {: .no_toc #how-to-generate-ai-songs-with-the-ace-music-api } 22 分钟阅读 • 2026 年 11 月 14 日 ## 目录 {: .no_toc .text-delta #table-of-contents } ### 简介 useapi.net 的 [ACE Music API](/docs/api-acemusic-v1) 只需一次 REST 调用,就能用你已有的 ACE Music 订阅,从 [ACE Music](https://acemusic.ai) 拿到两首完整的歌曲,带人声、歌词、标题和封面。ACE Music v1 在 [Artificial Analysis 人声音乐排行榜](https://artificialanalysis.ai/music/leaderboard/vocals)上排名第一,领先 Suno v6。开源的 [ACE-Step](https://ace-step.github.io) v1.5 XL 也通过同一个 API 运行,在任何 ACE Music 套餐上都不消耗积分,免费套餐也一样。 本指南先介绍三个模型和每首歌的费用,再用 `curl` 从头到尾生成一首歌,然后用一张简短的表格介绍其他所有功能。文末的[示例](#examples)是我们为本页制作的 18 首歌,每首都附有生成它的请求,全部由 [`acemusic-api` GitHub 仓库](https://github.com/useapi/acemusic-api)中的脚本(Node.js 和 Python)生成,一共消耗 Artist 套餐的 117 积分,包括多跑的几次。useapi.net 是[第三方](/docs/legal#affiliation--third-party-services) API,与 ACE Music 及其开发商 Timedomain 无关联。 ### 模型与 API 的功能 每个请求生成两首歌,由 `model` 决定用哪个模型: | 模型 | `model` | 用途 | 设置 | 每个请求的积分 | 我们实测的耗时 | |---|---|---|---|---|---| | ACE Music v1 | `acemusic-v1`(默认) | 排名第一的人声模型:根据提示词或你的歌词生成歌曲,可演唱也可纯音乐 | `duration` 30 到 600 秒、`negative`、`styleInfluence`,可下载 WAV | 4 | 46 到 89 秒 | | ACE Music v1.1 Preview | `acemusic-v1.1` | 先写乐谱,所以翻唱和混搭会跟随原曲的旋律 | `audioInfluence`、`styleInfluence` | 4 | 35 到 83 秒 | | ACE-Step v1.5 XL | `ace-step-1.5-xl` | 由 ACE Studio 和 StepFun 开源:歌曲、重混和编辑 | `bpm`、`key`、`timeSignature`、`duration` 10 到 240 秒、`negative`、`thinking`,仅 MP3 | 0 | 20 到 55 秒 | 可以用它们做什么: | 功能 | 请求 | 说明 | |---|---|---| | 根据提示词生成歌曲 | [POST /music](/docs/api-acemusic-v1/post-acemusic-music) `prompt` | 由 ACE Music 写风格、歌词和标题 | | 自己的歌词、纯音乐 | [POST /music](/docs/api-acemusic-v1/post-acemusic-music) `style`、`lyrics` | 任何语言 | | 歌词和风格生成 | [POST /music/lyrics](/docs/api-acemusic-v1/post-acemusic-music-lyrics)、[/music/style](/docs/api-acemusic-v1/post-acemusic-music-style) | 不消耗积分 | | 翻唱、重混、编辑、混搭 | [POST /music](/docs/api-acemusic-v1/post-acemusic-music#modes) `mode` | 适用于账号中的任何歌曲 | | 你的音频和图片 | [POST /files](/docs/api-acemusic-v1/post-acemusic-files) | 作为新歌的参考 | | 分轨 | [POST /music/stems](/docs/api-acemusic-v1/post-acemusic-music-stems) | Creator 和 Artist | | 下载、乐谱 | [GET /music/download](/docs/api-acemusic-v1/get-acemusic-music-download)、[/music/score](/docs/api-acemusic-v1/get-acemusic-music-score) | 所有套餐都能下载 MP3 和读取乐谱,Creator 和 Artist 还能下载 WAV、MIDI 和 MusicXML | | 曲库、任务、账号 | [GET /music](/docs/api-acemusic-v1/get-acemusic-music)、[/jobs](/docs/api-acemusic-v1/get-acemusic-jobs)、[/accounts](/docs/api-acemusic-v1/get-acemusic-accounts-email) | 账号的所有歌曲、运行中的任务、实时积分 | | MCP 服务器 | [`/v1/acemusic/mcp`](/docs/api-acemusic-v1/mcp) | 15 个供 AI 助手使用的工具 | ### 价格 ACE Music 按请求从你的 ACE Music 套餐中扣除它自己的积分,useapi.net 不按歌曲额外收费(截至 2026 年 11 月): | 请求 | 积分 | |---|---| | 在 ACE Music v1 或 v1.1 上生成两首歌 | 4 | | 分轨,人声 + 伴奏 | 5,付费套餐 | | 分轨,全部音轨 | 60,付费套餐 | | ACE-Step 歌曲的乐谱,首次读取 | 1 | | 在 ACE-Step v1.5 XL 上生成两首歌 | 0,所有套餐 | | 歌词和风格生成、上传、下载 | 我们测试中为 0 | [ACE Music 套餐](https://acemusic.ai/pricing/)包括:免费套餐每天 20 积分;Creator 每月 $9.90,含 1,000 积分;Artist 每月 $29,含 2,500 积分;按年付费则分别为每月 $7.90 和 $16.58。一首歌是半个请求,即 2 积分。[API 概览](/docs/api-acemusic-v1#pricing)中有同样的表格。 各套餐上一首歌的费用,最便宜的在左边(一个请求生成两首歌,所以一首歌是一个请求积分的一半;截至 2026 年 11 月): | 模型 | 免费 (每天 20 积分) | Artist $16.58/月 (每月 2,500 积分,年付) | Creator $7.90/月 (每月 1,000 积分,年付) | Creator $9.90/月 (每月 1,000 积分) | Artist $29/月 (每月 2,500 积分) | |---|---|---|---|---|---| | ACE Music v1、v1.1 (一首歌) | $0 / 2 积分 (每天 10 首) | $0.013 / 2 积分 (每月 1,250 首) | $0.016 / 2 积分 (每月 500 首) | $0.020 / 2 积分 (每月 500 首) | $0.023 / 2 积分 (每月 1,250 首) | | 分轨 (人声 + 伴奏) | 付费套餐 | $0.033 / 5 积分 | $0.040 / 5 积分 | $0.050 / 5 积分 | $0.058 / 5 积分 | | 分轨 (全部音轨) | 付费套餐 | $0.40 / 60 积分 | $0.47 / 60 积分 | $0.59 / 60 积分 | $0.70 / 60 积分 | | ACE-Step 乐谱 (首次读取) | $0 / 1 积分 | $0.007 / 1 积分 | $0.008 / 1 积分 | $0.010 / 1 积分 | $0.012 / 1 积分 | | ACE-Step v1.5 XL (一首歌) | $0 / 0 积分 | $0 / 0 积分 | $0 / 0 积分 | $0 / 0 积分 | $0 / 0 积分 | 与其他用代码调用这些模型的方式相比: | 模型 | useapi.net | 其他 API | |---|---|---| | ACE Music v1、v1.1 Preview | Artist 年付低至每首 $0.013,用免费套餐每天的 20 积分则为 $0 | — | | ACE-Step v1.5 XL | 所有 ACE Music 套餐上都是 $0,免费套餐也一样 | 第三方 [acestep.io](https://acestep.io/pricing) API 每首约 $0.14,且需要其每月 $49 的 Studio 套餐 | 在任何 ACE Music 套餐上(包括免费套餐),ACE-Step v1.5 XL 歌曲都不消耗积分;而第三方 acestep.io 的 API 需要其每月 $49 的 Studio 套餐(每月约 360 首,每首约 $0.14,截至 2026 年 11 月)。 ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. ### 如何用 curl 生成歌曲 你需要一个 useapi.net API Token(见 [Setup useapi.net](/docs/start-here/setup-useapi)),以及一个有邮箱和密码的 [ACE Music](https://acemusic.ai) 账号。一份[每月 $15 的订阅](/docs/subscription)涵盖 useapi.net 的所有 API 和 3 个 ACE Music 账号。免费的 ACE Music 账号也可以:它每天有 20 积分,而 ACE-Step 歌曲不需要积分。命令中用 [jq](https://jqlang.org) 读取 JSON。 #### 添加你的 ACE Music 账号 导出 Token,然后添加一次账号即可。API 会登录并读取账号,只有在 ACE Music 接受密码时才会保存它: ```bash export USEAPI_TOKEN="user:12345-..." API=https://api.useapi.net/v1/acemusic curl -s -X POST "$API/accounts" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "example@example.com", "password": "your-acemusic-password" }' ``` 用 Continue with Google 或手机号注册的账号需要先设置密码,见 [Setup ACE Music](/docs/start-here/setup-acemusic),它也可以替你添加账号。 #### 根据提示词生成歌曲 用你自己的话描述这首歌。ACE Music 会写出风格、歌词和标题,然后生成两首歌。下面就是本页第一首歌背后的原始请求: ```bash curl -s -X POST "$API/music" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A late-night neo-soul slow jam about two strangers sharing an umbrella at a bus stop in the rain and missing the last bus on purpose. Warm Rhodes piano, brushed drums, round upright bass, a smoky female lead with close three-part harmonies on the chorus.", "model": "acemusic-v1", "async": true }' | tee job.json | jq '{jobid, status, model}' ``` 设置 `async: true` 时,API 会立即返回 `201` 和任务。提示词最多 2,000 个字符,可以带最多 3 首参考歌曲和 3 张图片,见[用你自己的音频和图片引导歌曲](#guide-songs-with-your-own-audio-and-images)。 #### 返回的内容 在 ACE Music 写歌词期间,歌曲的状态是 `planning`,标题是 `Untitled`,之后依次变为 `queued` 和 `running`。大约每 10 秒轮询一次 [GET /jobs/`jobid`](/docs/api-acemusic-v1/get-acemusic-jobs-jobid)。`jobid` 中含有 `:` 和 `@`,所以要做 URL 编码: ```bash curl -s "$API/jobs/$(jq -r .jobid job.json | jq -Rr @uri)" \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{status, songs: [.songs[] | {title, status, duration, audioUrl}]}' ``` 当 `status` 为 `completed` 时,每首歌都带有它的链接(下面的 id 是虚构的): ```json { "jobid": "j1115003713275918262m-u12345-email:example@example.com-task:so_7c1d9e3a5b2f4806a4e1c9d3.so_8b4f2e6a1c9d47e5a3b7c0d2-bot:acemusic", "type": "music", "status": "completed", "email": "example@example.com", "created": "2026-11-15T00:37:13.275Z", "model": "acemusic-v1", "modelUsed": "acemusic-v1", "songs": [ { "songId": "user:12345-example@example.com-song:so_7c1d9e3a5b2f4806a4e1c9d3", "taskId": "so_7c1d9e3a5b2f4806a4e1c9d3", "status": "succeeded", "title": "Let the 44 Roll By", "model": "acemusic-v1", "style": "Late-night neo-soul slow jam with a laid-back 1990s and early 2000s pocket, 72 BPM. …", "lyrics": "[Intro - Warm Rhodes chords, brushed snare rim clicks, subtle rain on asphalt]\n\n[Verse 1 …]\nWater dripping off the canvas seam\n…", "instrumental": false, "duration": 277.19, "audioUrl": "https://acemusic.ai/data/so_7c1d9e3a5b2f4806a4e1c9d3.mp3", "playUrl": "https://….r2.cloudflarestorage.com/acemusic-data-prod/users/…/audio/202611/….mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20261115T003902Z&X-Amz-Expires=3599&…", "playUrlExpires": "2026-11-15T01:39:01.000Z", "coverUrl": "https://acemusic.ai/data/so_7c1d9e3a5b2f4806a4e1c9d3-cover.jpg?v=1794703081642", "pageUrl": "https://acemusic.ai/song/r4k8w2n6p9tz", "created": "2026-11-15T00:37:13.300Z", "finished": "2026-11-15T00:38:42.208Z", "kind": "original", "score": false }, { "songId": "user:12345-example@example.com-song:so_8b4f2e6a1c9d47e5a3b7c0d2", "title": "Let the 44 Roll By", "duration": 253.99, "…": "…" } ], "completed": "2026-11-15T00:38:42.208Z" } ``` - `audioUrl` 是歌曲的公开 MP3 链接,永远不变。`playUrl` 是同一个 MP3 供网页播放器使用的直链,在 `playUrlExpires` 之前有效(约一小时):有些浏览器(例如 Brave)会拦截 `audioUrl` 背后的重定向。 - 翻唱、混搭、分轨、下载和乐谱都使用 `songId`。它标明了歌曲所在的账号,所以这些调用会在该账号上运行。 - `model` 是你请求的模型,`modelUsed` 是实际运行的模型(见[混搭](#mash-up-two-or-three-songs))。`kind` 为 `original`、`cover`、`edit`、`mashup` 或 `upload`,`score` 表示这首歌是否已经有乐谱。 - ACE Music 未能生成的歌曲为 `status: "failed"`,`error` 中是 ACE Music 给出的原因;积分退回时会带 `refunded: true`。 下面是这两首歌中的第一首: ACE Music v1 — “Let the 44 Roll By” · 4:37 · 生成用时 89 秒 <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-let-the-44-roll-by-neo-soul-from-prompt.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### 同步、异步和 webhook | 你发送的 | POST 的返回 | 然后 | |---|---|---| | `async: true` | 立即返回 `201` 和任务 | 轮询 [GET /jobs/`jobid`](/docs/api-acemusic-v1/get-acemusic-jobs-jobid) | | 不带 `async` | `200` 和已完成的任务,JSON 与上面相同 | 从返回中读取歌曲。100 秒后仍在运行的请求会返回 `202` 和任务:轮询它 | | `replyUrl` 和 `replyRef` | 同上,同步和异步都一样 | 你的公开 `https` URL 会收到一次已完成任务的 `POST`,其中带有你的 `replyRef` | 我们不带 `async` 的 ACE-Step 请求在 37 秒后返回,webhook 在歌曲完成 12 秒后到达。任务在 7 天内都可以读取,开始 30 分钟后仍在运行的任务会以 `504` 失败。[`async-webhooks/`](https://github.com/useapi/acemusic-api/tree/main/async-webhooks) 演示了全部三种方式,并附带一个小型 webhook 接收端。 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash curl -s -X POST "$API/music" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A dreamy lo-fi hip hop beat for studying late at night: dusty vinyl crackle, mellow Rhodes chords, a soft upright bass and rain on the window", "model": "ace-step-1.5-xl", "replyUrl": "https://your-server.example.com/acemusic-hook", "replyRef": "lofi-1" }' | jq '{status, songs: [.songs[] | {title, duration, audioUrl}]}' ``` </details> ### 演唱你自己的歌词 用 `style` 和 `lyrics` 代替 `prompt`,ACE Music 就会按你的风格唱出你的歌词: | 字段 | 作用 | 限制 | |---|---|---| | `style` | 曲风、乐器、情绪、速度和人声 | 1,000 个字符,ACE-Step 为 512 | | `lyrics` | 你的歌词,任何语言,可用 `[Verse]`、`[Chorus]`、`[Bridge]` 标签 | 5,000 个字符,ACE-Step 为 2,000 | | `title` | 歌曲标题。不填则由 ACE Music 命名 | 80 个字符 | | `instrumental` | `true` 表示不要人声。只发 `style` 不发 `lyrics` 效果相同 | | | `duration` | 时长(秒) | ACE Music v1 为 30 到 600,ACE-Step 为 10 到 240 | | `negative` | 要避免的风格 | 200 个字符,ACE Music v1 和 ACE-Step | | `styleInfluence` | 遵循风格的严格程度 | `0` 到 `100`,默认 `80`,ACE Music v1 和 v1.1 | 不要把 `prompt` 和这些字段一起发送:API 会返回 `400`,并指出要去掉哪些字段。我们的抒情曲请求了 `duration: 210`,返回的两首分别是 210 秒和 209 秒。它和一首纯音乐、一首西班牙语歌曲都在[示例](#your-own-lyrics)中。 还没有歌词?[POST /music/lyrics](/docs/api-acemusic-v1/post-acemusic-music-lyrics) 会根据你的要求写出歌词和标题,[POST /music/style](/docs/api-acemusic-v1/post-acemusic-music-style) 能把几个词扩展成完整的风格描述。我们的请求分别在 6 秒和 4 秒内返回,没有扣积分。脚本:[`custom-lyrics/`](https://github.com/useapi/acemusic-api/tree/main/custom-lyrics)。 ### 用 ACE-Step 控制速度、调性和拍号 ACE-Step v1.5 XL 支持 ACE Music 模型不支持的音乐设置,而且它的歌曲不消耗积分: | 选项 | 取值 | |---|---| | `bpm` | `30` 到 `200` | | `timeSignature` | `2/4`, `3/4`, `4/4`, `6/8` | | `key` | `C major` 到 `B minor`(C、C#、D、Eb、E、F、F#、G、Ab、A、Bb、B) | | `duration` | `10` 到 `240` 秒 | | `negative` | 要避免的风格,最多 200 个字符 | | `thinking` | `0` 到 `100`:ACE-Step 先规划整首歌,数值低时更有创意,高时更稳定 | 我们的三首 ACE-Step 歌曲(一首 3/4 拍华尔兹、一首 6/8 拍吉格舞曲和一首 174 bpm 的 drum and bass)时长都与请求完全一致([示例](#ace-step-at-a-set-tempo-key-and-meter))。这些选项只在 `ace-step-1.5-xl` 的 `mode` `generate` 中有效,在其他情况下 API 会返回 `400 Parameter bpm does not apply to mode generate on acemusic-v1`。脚本:[`ace-step-options/`](https://github.com/useapi/acemusic-api/tree/main/ace-step-options)。 ### 翻唱、重混和编辑 `mode` 让请求作用于你已有的歌曲。`references` 接收这些歌曲的 `songId`:可以是 API 生成的歌曲、[曲库](#your-library)中的歌曲,或你自己上传的音频。 | `mode` | `references` | 运行模型 | 积分 | 作用 | |---|---|---|---|---| | `cover` | 1 首 | `acemusic-v1.1`,或在 `ace-step-1.5-xl` 上用 ACE-Step | 4 / 0 | 用新的 `style` 演绎这首歌,保留它的旋律、和弦和结构 | | `remix` | 1 首 | `ace-step-1.5-xl` | 0 | `coverStrength` 保留原曲,`remixStrength` 偏离原曲(`0` 到 `100`) | | `edit` | 1 首 | `ace-step-1.5-xl` | 0 | 用新的 `lyrics` 重写 `start` 到 `end` 秒之间的部分,其余保留 | | `mashup` | 2 或 3 首 | `acemusic-v1.1` | 4 | 把多首歌合成一首新歌,见下文 | ACE Music v1.1 按照从歌曲乐谱中读出的旋律来演绎。我们第一次翻唱一首还没有乐谱的 ACE Music v1 歌曲时,请求以 `ref_no_melody` 失败,4 积分已退回;所以现在 API 会在 v1.1 翻唱或混搭之前,先免费读取 ACE Music v1 歌曲的乐谱。ACE-Step 歌曲不会被自动读取:如果它返回 `400` 和 `ref_no_melody`,请先对它调用 [GET /music/score](#read-the-score)(1 积分),再重新发送请求。脚本:[`covers-remix-edit/`](https://github.com/useapi/acemusic-api/tree/main/covers-remix-edit)。 #### 混搭两首或三首歌 `mode: "mashup"` 把同一账号上的 2 或 3 首歌合成一首,除非你发送了 `lyrics`,否则会组合它们的歌词。`audioInfluence`(0 到 100,默认 60)决定贴近原曲的程度。混搭需要读取这些歌曲,所以即使你请求的是 v1,它也会在 ACE Music v1.1 Preview 上运行,和 ACE Music 网站一样:我们的“Harbor Fiesta”显示 `"model": "acemusic-v1"` 和 `"modelUsed": "acemusic-v1.1"`,积分按实际运行的模型计算。在 v1 上请求的 `cover`、在 ACE-Step 上带多个参考的提示词,以及有时带参考歌曲的提示词,也会这样。脚本:[`mashup/`](https://github.com/useapi/acemusic-api/tree/main/mashup)。 ### 用你自己的音频和图片引导歌曲 [POST /files](/docs/api-acemusic-v1/post-acemusic-files) 以原始请求体接收文件,并带上对应的 `Content-Type`: | 上传 | 格式 | 上限 | 返回 | 用途 | |---|---|---|---|---| | 音频 | MP3、WAV、FLAC、OGG、M4A、AAC | 100 MB,8 分钟 | 一个 `songId`:一首曲库歌曲,其歌词、风格、速度和旋律由 ACE Music 转录 | 作为提示词最多 3 个 `references` 之一,或作为要翻唱、重混、编辑或混搭的歌曲 | | 图片 | JPEG、PNG、WebP | 10 MB | 一个 `mediaId` | 作为提示词最多 3 张 `images` 之一:ACE Music 会围绕它写一首歌 | ```bash curl -s -X POST "$API/files?title=Harbour%20Jig%20demo" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: audio/mpeg" \ --data-binary @harbour-jig-demo.mp3 | jq '{songId, status, duration, bpm: .upload.bpm}' ``` 我们上传的 90 秒“Harbour Jig”在 14 秒内转录完成,ACE Music 听出的速度是 115 bpm(我们请求的是 116)。一张跳舞机器人的图片变成了一首 drum and bass,唱的是它青绿色的绒毛和橙色的高帮鞋。两者都在[示例](#your-audio-and-pictures)中。上传会计入账号的额度:免费套餐 10 分钟音频,Creator 30 分钟,Artist 60 分钟。脚本:[`upload-reference/`](https://github.com/useapi/acemusic-api/tree/main/upload-reference)。 ### 分轨、下载和乐谱 每首完成的歌曲都可以拆分音轨、下载,并读取乐谱: | 请求 | 套餐 | 积分 | 返回 | |---|---|---|---| | [分轨](/docs/api-acemusic-v1/post-acemusic-music-stems),`mode: "vocals"` | Creator、Artist | 5 | `vocal` 和 `instrumental` 两个 MP3 | | [分轨](/docs/api-acemusic-v1/post-acemusic-music-stems),`mode: "all"` | Creator、Artist | 60 | ACE Music 找到的每条音轨,均为 MP3 | | [下载](/docs/api-acemusic-v1/get-acemusic-music-download) `mp3`(默认) | 所有套餐 | 0 | `url`(与 `audioUrl` 相同)和 `playUrl` | | 下载 `wav` | Creator、Artist | 0 | 有效期 24 小时的链接。不适用于 ACE-Step 歌曲 | | 下载 `midi`、`musicxml` | Creator、Artist | 0 | 文件本身 | | [乐谱](/docs/api-acemusic-v1/get-acemusic-music-score) | 所有套餐 | 0,ACE-Step 歌曲首次读取为 1 | [ABC 记谱法](https://abcnotation.com):人声旋律、一条器乐声部、和弦和段落 | #### 把歌曲拆分为分轨 “Paper Lanterns”的人声拆分用了大约 80 秒,完整拆分不到 2 分钟,得到 9 条音轨:主唱、和声、鼓、贝斯、吉他、键盘、弦乐、合成器和音效([试听](#stems-of-paper-lanterns))。分轨链接有效期 24 小时,过期后重新读取歌曲即可拿到新链接。用同一模式再次拆分同一首歌会立即返回,不扣积分。 #### 下载 MP3、WAV、MIDI 和 MusicXML ACE Music 在第一次请求时才生成 WAV、MIDI 和 MusicXML:API 最多等待一分钟,然后返回 `202`,一分钟后再调用即可。“Paper Lanterns”的三种格式都在几秒内就绪:40 MB 的 WAV、8 KB 的 MIDI 文件和 107 KB 的 MusicXML 乐谱。 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash SONG="user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7" curl -s -G "$API/music/download" --data-urlencode "songId=$SONG" -d format=wav \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{url, expires}' curl -s -G "$API/music/download" --data-urlencode "songId=$SONG" -d format=midi \ -H "Authorization: Bearer $USEAPI_TOKEN" -o paper-lanterns.mid ``` </details> #### 读取乐谱 任何 ABC 工具都能把乐谱转成五线谱。“Paper Lanterns”的乐谱读出 72 bpm,正是我们在风格中要求的速度。ACE Music v1.1 歌曲自带乐谱,v1.1 的翻唱和混搭会跟随乐谱,见[翻唱、重混和编辑](#covers-remixes-and-edits)。 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash SONG="user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7" curl -s -G "$API/music/score" --data-urlencode "songId=$SONG" \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq -r .abc | head -14 ``` ``` X:1 T: M:2/4 L:1/16 Q:1/4=72 V: Vocal clef=treble name="Vocal Melody" snm="Vocal" V: Ins clef=treble name="Ins Melody" snm="Inst." K:Ab % intro V: Vocal Z|"Ab"z8|"Ab"z8|"Ab"z8| V: Ins Z|Ac2AcBA2|A2EAA2EA|Ac2AcBA2| ``` </details> 脚本:[`stems-and-downloads/`](https://github.com/useapi/acemusic-api/tree/main/stems-and-downloads),它会保存分轨、所有下载格式和乐谱。 ### 你的曲库 账号中的每首歌和每个上传,无论是在这里还是在 acemusic.ai 上生成的,都会一直留在曲库中,直到被删除: | 请求 | 作用 | |---|---| | [GET /music](/docs/api-acemusic-v1/get-acemusic-music) | 一页歌曲,最新的在前,用 `next` 获取下一页。有多个账号时需要 `email`。超过 7 天的任务的歌曲也在这里 | | [GET /music/`songId`](/docs/api-acemusic-v1/get-acemusic-music-songid) | 一首歌,带新的链接,拆分过的还带分轨 | | [DELETE /music/`songId`](/docs/api-acemusic-v1/delete-acemusic-music-songid) | `204`:歌曲移入 acemusic.ai 上该账号的回收站,此后 API 对它返回 `404` | <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash SONG="user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7" curl -s -G "$API/music" --data-urlencode "email=example@example.com" -d limit=20 \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{next, songs: [.songs[] | {title, model, kind, songId}]}' curl -s "$API/music/$(jq -rn --arg v "$SONG" '$v|@uri')" \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{title, score, audioUrl, playUrl, stems: (.stems // {} | keys)}' curl -s -o /dev/null -w "%{http_code}\n" -X DELETE "$API/music/$(jq -rn --arg v "$SONG" '$v|@uri')" \ -H "Authorization: Bearer $USEAPI_TOKEN" ``` </details> 脚本:[`library/`](https://github.com/useapi/acemusic-api/tree/main/library)。 ### 多个 ACE Music 账号 每份 useapi.net 订阅可以连接 3 个 ACE Music 账号,总计最多 100 个。不带 `email` 的请求会发到一个状态正常且有空闲名额的账号,指定了歌曲、上传或图片的请求则在它们所在的账号上运行。每个账号最多同时运行 `maxJobs` 个请求,默认为 4,这是 ACE Music 自己的限制。一份 $15 的订阅最多可同时运行 12 个歌曲请求(3 个账号 × 每个 4 个),而每个请求生成两首歌,因此可并行生成 24 首歌,无论使用 ACE Music v1,还是不消耗积分的 ACE-Step v1.5 XL。所有账号都忙时,API 返回 `429` 和 `Retry-After`;如果 ACE Music 拒绝了密码,该账号会一直返回 `596`,直到你重新添加它。 [GET /accounts/`email`](/docs/api-acemusic-v1/get-acemusic-accounts-email) 实时读取套餐、积分和各项积分费用;只带 `email` 和 `maxJobs` 调用 [POST /accounts](/docs/api-acemusic-v1/post-acemusic-accounts),则只修改 `maxJobs`。脚本:[`accounts/`](https://github.com/useapi/acemusic-api/tree/main/accounts)。 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash curl -s "$API/accounts/$(jq -rn --arg v "example@example.com" '$v|@uri')" \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{plan_name, credits, maxJobs, costs}' curl -s -X POST "$API/accounts" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "example@example.com", "maxJobs": 2 }' ``` </details> ### 在 Claude、ChatGPT 或 Cursor 中使用(MCP) 同样的功能也以托管 [MCP 服务器](/docs/api-acemusic-v1/mcp)的形式提供,共 15 个工具,从歌曲、翻唱和混搭到分轨、乐谱和上传。在 Claude Code 中只需一条命令: ```bash claude mcp add --transport http useapi-acemusic https://api.useapi.net/v1/acemusic/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` Cursor、VS Code 和 Windsurf 使用同样的 URL 和请求头,Claude 应用和 ChatGPT 则通过 OAuth 登录,见[在 Claude 应用或 ChatGPT 中使用](/docs/api-acemusic-v1/mcp#use-it-in-the-claude-app-or-chatgpt)。然后直接用自然语言提出要求:“Write lyrics about a cat who loves rainy days and sing them as acoustic indie folk on ACE Music v1”。 #### useapi.net 与 ACE Music 自己的 MCP 服务器对比 ACE Music también tiene su propio servidor MCP en `https://acemusic.ai/mcp`. Crea canciones de ACE Music v1 y v1.1 a partir del estilo y la letra que escribe tu asistente. El servidor de useapi.net funciona con la misma cuenta de ACE Music y agrega todo lo demás (al 18 de noviembre de 2026): | | MCP de ACE Music de useapi.net | MCP propio de ACE Music | |---|---|---| | ACE-Step v1.5 XL, 0 créditos en todos los planes | Sí | No, solo ACE Music v1 y v1.1 | | Descarga de MP3 en el plan Free | Sí | No, toda descarga requiere un plan de pago | | Covers, remixes, ediciones y mashups | Una llamada para cada uno, a partir de tus canciones | El asistente los arma a partir de una partitura transcrita | | Stems: voz e instrumental, o cada instrumento | Sí | No | | Partituras MusicXML | Sí | No, solo MIDI | | Estilo, letra y título escritos por ACE Music a partir de una idea de una línea | Sí | No, los escribe el asistente | | Varias cuentas de ACE Music en una sola conexión | Sí | Una cuenta por conexión | | Token de API para scripts, n8n y agentes sin interfaz, además de OAuth | Sí | Solo inicio de sesión con OAuth | | Las mismas llamadas por REST, con jobs y webhooks | Sí | No | useapi.net es un servicio de terceros, sin afiliación con ACE Music. ACE Music juga punya MCP server sendiri di `https://acemusic.ai/mcp`. Server itu membuat lagu ACE Music v1 dan v1.1 dari gaya dan lirik yang ditulis asisten Anda. Server useapi.net bekerja di akun ACE Music yang sama dan menambahkan sisanya (per 18 November 2026): | | MCP ACE Music dari useapi.net | MCP milik ACE Music sendiri | |---|---|---| | ACE-Step v1.5 XL, 0 kredit di semua paket | Ya | Tidak, hanya ACE Music v1 dan v1.1 | | Download MP3 di paket Free | Ya | Tidak, setiap download butuh paket berbayar | | Cover, remix, edit, dan mashup | Masing-masing satu panggilan, dari lagu Anda | Dirangkai oleh asisten dari partitur hasil transkripsi | | Stem: vokal dan instrumental, atau setiap instrumen | Ya | Tidak | | Partitur MusicXML | Ya | Tidak, hanya MIDI | | Gaya, lirik, dan judul ditulis ACE Music dari ide satu baris | Ya | Tidak, asisten yang menulisnya | | Beberapa akun ACE Music dalam satu koneksi | Ya | Satu akun per koneksi | | Token API untuk skrip, n8n, dan agen headless, plus OAuth | Ya | Hanya login OAuth | | Panggilan yang sama lewat REST, dengan job dan webhook | Ya | Tidak | useapi.net adalah layanan pihak ketiga dan tidak berafiliasi dengan ACE Music. ACE Music も独自の MCP サーバーを `https://acemusic.ai/mcp` で提供しています。こちらは、アシスタントが書いたスタイルと歌詞から ACE Music v1 と v1.1 の曲を作ります。useapi.net のサーバーは同じ ACE Music アカウントで動き、それ以外のすべてを補います(2026年11月18日時点)。 | | useapi.net の ACE Music MCP | ACE Music 独自の MCP | |---|---|---| | ACE-Step v1.5 XL、どのプランでも0クレジット | 対応 | 非対応、ACE Music v1 と v1.1 のみ | | Free プランでの MP3 ダウンロード | 対応 | 非対応、ダウンロードにはすべて有料プランが必要 | | カバー、リミックス、編集、マッシュアップ | お手持ちの曲から、それぞれ1回の呼び出しで | 書き起こした楽譜をもとにアシスタントが組み立てる | | ステム:ボーカルとインスト、または楽器ごと | 対応 | 非対応 | | MusicXML の楽譜 | 対応 | 非対応、MIDI のみ | | 1行のアイデアから ACE Music がスタイル、歌詞、タイトルを書く | 対応 | 非対応、アシスタントが書く | | 1つの接続で複数の ACE Music アカウント | 対応 | 1接続につき1アカウント | | スクリプト、n8n、ヘッドレスエージェント向けの API トークンと OAuth | 対応 | OAuth サインインのみ | | 同じ呼び出しを REST で、ジョブと Webhook 付きで | 対応 | 非対応 | useapi.net はサードパーティのサービスで、ACE Music とは提携していません。 O ACE Music também tem o próprio servidor MCP em `https://acemusic.ai/mcp`. Ele gera músicas do ACE Music v1 e v1.1 a partir do estilo e da letra que o seu assistente escreve. O servidor da useapi.net funciona na mesma conta do ACE Music e acrescenta todo o resto (em 18 de novembro de 2026): | | MCP do ACE Music da useapi.net | MCP do próprio ACE Music | |---|---|---| | ACE-Step v1.5 XL, 0 créditos em todos os planos | Sim | Não, só ACE Music v1 e v1.1 | | Download de MP3 no plano Free | Sim | Não, todo download exige um plano pago | | Covers, remixes, edições e mashups | Uma chamada para cada, a partir das suas músicas | Montados pelo assistente a partir de uma partitura transcrita | | Stems: vocal e instrumental, ou cada instrumento | Sim | Não | | Partituras MusicXML | Sim | Não, só MIDI | | Estilo, letra e título escritos pelo ACE Music a partir de uma ideia de uma linha | Sim | Não, o assistente escreve | | Várias contas do ACE Music em uma só conexão | Sim | Uma conta por conexão | | Token de API para scripts, n8n e agentes headless, além de OAuth | Sim | Só login com OAuth | | As mesmas chamadas via REST, com jobs e webhooks | Sim | Não | A useapi.net é um serviço de terceiros, sem afiliação com o ACE Music. ACE Music มี MCP server ของตัวเองด้วยที่ `https://acemusic.ai/mcp` ซึ่งสร้างเพลง ACE Music v1 และ v1.1 จากสไตล์และเนื้อเพลงที่ผู้ช่วย AI ของคุณเขียน ส่วน server ของ useapi.net ทำงานบนบัญชี ACE Music เดียวกันและเพิ่มส่วนที่เหลือทั้งหมด (ข้อมูล ณ วันที่ 18 พฤศจิกายน 2026): | | ACE Music MCP ของ useapi.net | MCP ของ ACE Music เอง | |---|---|---| | ACE-Step v1.5 XL ใช้ 0 เครดิตในทุกแพ็กเกจ | ได้ | ไม่ได้ มีแค่ ACE Music v1 และ v1.1 | | ดาวน์โหลด MP3 ในแพ็กเกจ Free | ได้ | ไม่ได้ ทุกการดาวน์โหลดต้องใช้แพ็กเกจเสียเงิน | | คัฟเวอร์ รีมิกซ์ การแก้ไข และแมชอัป | เรียกครั้งเดียวต่ออย่าง จากเพลงของคุณ | ผู้ช่วย AI ประกอบเองจากโน้ตเพลงที่ถอดออกมา | | สเต็ม: เสียงร้องกับดนตรี หรือแยกทุกเครื่องดนตรี | ได้ | ไม่ได้ | | โน้ตเพลง MusicXML | ได้ | ไม่ได้ มีแค่ MIDI | | ACE Music เขียนสไตล์ เนื้อเพลง และชื่อเพลงจากไอเดียบรรทัดเดียว | ได้ | ไม่ได้ ผู้ช่วย AI ต้องเขียนเอง | | หลายบัญชี ACE Music ในการเชื่อมต่อเดียว | ได้ | หนึ่งบัญชีต่อการเชื่อมต่อ | | API token สำหรับสคริปต์ n8n และเอเจนต์ที่ไม่มีหน้าจอ พร้อม OAuth | ได้ | ล็อกอินด้วย OAuth เท่านั้น | | เรียกแบบเดียวกันผ่าน REST พร้อมงานและ webhook | ได้ | ไม่ได้ | useapi.net เป็นบริการของบุคคลที่สาม ไม่มีส่วนเกี่ยวข้องกับ ACE Music ACE Music cũng có MCP server riêng tại `https://acemusic.ai/mcp`. Server này tạo bài hát ACE Music v1 và v1.1 từ phong cách và lời bài hát do trợ lý của bạn viết. Server của useapi.net chạy trên cùng tài khoản ACE Music và bổ sung phần còn lại (tính đến 18 tháng 11 năm 2026): | | MCP ACE Music của useapi.net | MCP riêng của ACE Music | |---|---|---| | ACE-Step v1.5 XL, 0 credit trên mọi gói | Có | Không, chỉ ACE Music v1 và v1.1 | | Tải MP3 trên gói Free | Có | Không, mọi lượt tải đều cần gói trả phí | | Cover, remix, chỉnh sửa và mashup | Mỗi thứ một lệnh gọi, từ bài hát của bạn | Trợ lý tự ghép lại từ bản nhạc được chép ra | | Stem: giọng hát và nhạc nền, hoặc từng nhạc cụ | Có | Không | | Bản nhạc MusicXML | Có | Không, chỉ MIDI | | Phong cách, lời và tên bài do ACE Music viết từ một ý tưởng một dòng | Có | Không, trợ lý tự viết | | Nhiều tài khoản ACE Music trong một kết nối | Có | Một tài khoản cho mỗi kết nối | | API token cho script, n8n và agent chạy không giao diện, cùng với OAuth | Có | Chỉ đăng nhập OAuth | | Cùng các lệnh gọi qua REST, có job và webhook | Có | Không | useapi.net là dịch vụ của bên thứ ba, không liên kết với ACE Music. ACE Music 也在 `https://acemusic.ai/mcp` 运行自己的 MCP 服务器。它根据你的助手写好的风格和歌词生成 ACE Music v1 和 v1.1 歌曲。useapi.net 的服务器使用同一个 ACE Music 账号,并补上其余的一切(截至 2026 年 11 月 18 日): | | useapi.net ACE Music MCP | ACE Music 自己的 MCP | |---|---|---| | ACE-Step v1.5 XL,所有套餐都是 0 积分 | 支持 | 不支持,只有 ACE Music v1 和 v1.1 | | 免费套餐下载 MP3 | 支持 | 不支持,任何下载都需要付费套餐 | | 翻唱、重混、编辑和混搭 | 基于你的歌曲,各一次调用 | 由助手根据转写出的乐谱拼凑完成 | | 分轨:人声和伴奏,或每件乐器 | 支持 | 不支持 | | MusicXML 乐谱 | 支持 | 不支持,只有 MIDI | | 由 ACE Music 根据一句话的想法写出风格、歌词和标题 | 支持 | 不支持,由助手来写 | | 一个连接中使用多个 ACE Music 账号 | 支持 | 每个连接一个账号 | | 用于脚本、n8n 和无界面智能体的 API Token,另有 OAuth | 支持 | 只能 OAuth 登录 | | 通过 REST 进行同样的调用,带任务和 webhook | 支持 | 不支持 | useapi.net 是第三方服务,与 ACE Music 无关联。 ACE Music also runs its own MCP server at `https://acemusic.ai/mcp`. It makes ACE Music v1 and v1.1 songs from the style and lyrics your assistant writes. The useapi.net server works on the same ACE Music account and adds the rest (as of November 18, 2026): | | useapi.net ACE Music MCP | ACE Music's own MCP | |---|---|---| | ACE-Step v1.5 XL, 0 credits on every plan | Yes | No, ACE Music v1 and v1.1 only | | MP3 download on the Free plan | Yes | No, every download needs a paid plan | | Covers, remixes, edits and mashups | One call each, from your songs | Pieced together by the assistant from a transcribed score | | Stems: vocals and instrumental, or every instrument | Yes | No | | MusicXML scores | Yes | No, MIDI only | | Style, lyrics and title written by ACE Music from a one-line idea | Yes | No, the assistant writes them | | Several ACE Music accounts in one connection | Yes | One account per connection | | API token for scripts, n8n and headless agents, plus OAuth | Yes | OAuth sign-in only | | The same calls over REST, with jobs and webhooks | Yes | No | useapi.net is a third-party service, not affiliated with ACE Music. ### 用脚本批量生成 [`acemusic-api` GitHub 仓库](https://github.com/useapi/acemusic-api)为每个功能提供一个示例,上面各节都有链接:一个 Node.js 脚本和一个对应的 Python 版本,无需安装任何依赖。每个脚本从你编辑的 `prompts.json` 读取请求,最多同时运行 4 个,轮询任务,并把两首歌、它们的封面、任务记录以及记录积分消耗的 `ledger.jsonl` 保存到 `output/` 文件夹中。 你需要 [Node.js](https://nodejs.org) 21 或更高版本,或 [Python](https://www.python.org) 3.8 或更高版本。`--only 3` 运行下面的第三个提示词,这是一首不消耗积分的 ACE-Step 歌曲,所以免费账号也能运行: ```bash git clone https://github.com/useapi/acemusic-api.git && cd acemusic-api export USEAPI_TOKEN="user:12345-..." node songs-from-prompt/songs-from-prompt.mjs --only 3 ``` 每个保存的任务记录都包含歌曲的 `songId`,用 `--from <job>.json --pick 1` 可以把第 1 首歌交给下一个脚本去翻唱、混搭或拆分。 <details markdown="block"> <summary>展开 `songs-from-prompt/prompts.json`</summary> ```json [ { "_about": "ACE Music v1 (the default model, 4 credits for two songs): ACE Music writes the style, lyrics and title from your idea", "prompt": "A late-night neo-soul slow jam about two strangers sharing an umbrella at a bus stop in the rain and missing the last bus on purpose. Warm Rhodes piano, brushed drums, round upright bass, a smoky female lead with close three-part harmonies on the chorus.", "model": "acemusic-v1" }, { "_about": "ACE Music v1.1 Preview (4 credits): writes a score first, then the audio", "prompt": "An anthemic Celtic folk-rock singalong about a fishing crew racing a storm back to the harbor. Fiddle and tin whistle hooks, stomping kick drum, bodhran, a gravelly male lead and the whole crew shouting the chorus.", "model": "acemusic-v1.1" }, { "_about": "ACE-Step v1.5 XL (no credits on any ACE Music plan, the Free plan included)", "prompt": "A breezy bossa nova for a lazy Sunday afternoon in Lisbon: nylon-string guitar, soft brushed snare, upright bass, a gentle flute line and a warm male and female duet sung in Portuguese.", "model": "ace-step-1.5-xl" } ] ``` </details> ### 示例 下面每首歌都是 2026 年 11 月 14 日(PST)用仓库中的脚本在一个 ACE Music Artist 账号上生成的,取的是每个请求两首歌中的第一首。除非我们指定了标题,否则标题都由 ACE Music 命名;时间从发出请求算到两首歌都完成;调用中的 id 是虚构的。 #### 根据图片生成歌曲 输入一张图片和一句风格描述,输出两首完整的歌。我们上传了这张跳舞的机器人吉祥物照片,要求一首 drum and bass;ACE Music 根据它看到的内容写了歌词:“Teal fur shaking on the concrete floor, orange high-tops squeaking by the studio door”。 <img src="https://media.useapi.net/blog/2026-09-07-260907/dreamina-longvideo-ref-robot-mascot.png" alt="一个毛茸茸的青绿色机器人吉祥物,方盒脑袋,带天线和发光的眼睛,穿着橙色高帮运动鞋跳舞" style="width: 100%; max-width: 220px;" loading="lazy"> ``` Bouncy, playful drum and bass for a dancing robot mascot: rolling breakbeats at 174 bpm, a wobbly reese bass, bleepy robot synth hooks, vocoder chops, cheeky and upbeat. ``` ACE Music v1 — “Bleep Boop Bounce” · 2:47 · 生成用时 72 秒 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/files' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: image/png' \ --data-binary @robot-mascot.png curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "Bouncy, playful drum and bass for a dancing robot mascot: rolling breakbeats at 174 bpm, a wobbly reese bass, bleepy robot synth hooks, vocoder chops, cheeky and upbeat.", "model": "acemusic-v1", "images": ["user:12345-example@example.com-media:cx_3b9e1d7a5c2f48e0a6d4b8c1"], "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-bleep-boop-bounce-drum-and-bass-from-robot-image.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> 这首歌的 YouTube Short 版本,配有那张照片:[YouTube 上的 Bleep Boop Bounce](https://youtube.com/shorts/z_aOmILvIng)。 #### 根据提示词生成的歌曲 根据提示词生成的 ACE Music v1 歌曲“Let the 44 Roll By”在[上面的完整流程](#what-you-get-back)中。另外两个提示词,分别用另外两个模型: ``` An anthemic Celtic folk-rock singalong about a fishing crew racing a storm back to the harbor. Fiddle and tin whistle hooks, stomping kick drum, bodhran, a gravelly male lead and the whole crew shouting the chorus. ``` ACE Music v1.1 Preview — “Haul for the Harbor Light” · 2:51 · 生成用时 43 秒 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "An anthemic Celtic folk-rock singalong about a fishing crew racing a storm back to the harbor. Fiddle and tin whistle hooks, stomping kick drum, bodhran, a gravelly male lead and the whole crew shouting the chorus.", "model": "acemusic-v1.1", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-1-haul-for-the-harbor-light-celtic-folk-rock-from-prompt.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ``` A breezy bossa nova for a lazy Sunday afternoon in Lisbon: nylon-string guitar, soft brushed snare, upright bass, a gentle flute line and a warm male and female duet sung in Portuguese. ``` ACE-Step v1.5 XL,不消耗积分 — “Domingo em Alfama” · 3:28 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "A breezy bossa nova for a lazy Sunday afternoon in Lisbon: nylon-string guitar, soft brushed snare, upright bass, a gentle flute line and a warm male and female duet sung in Portuguese.", "model": "ace-step-1.5-xl", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-domingo-em-alfama-bossa-nova-from-prompt.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### 你自己的歌词 我们自己写的两段主歌、一段预副歌、一段桥段和一段尾奏,请求时长 210 秒: ``` Style: cinematic indie pop ballad, felt piano, swelling strings, deep heartbeat kick, intimate female vocal that opens up into a soaring chorus, 72 bpm Lyrics: [Verse 1] We wrote our names on paper lanterns / Down by the river in July … [Chorus] Light it up and let it go / Every word I never said out loud … ``` ACE Music v1 — “Paper Lanterns” · 3:29 · 生成用时 61 秒 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "title": "Paper Lanterns", "style": "cinematic indie pop ballad, felt piano, swelling strings, deep heartbeat kick, intimate female vocal that opens up into a soaring chorus, 72 bpm", "lyrics": "[Verse 1]\nWe wrote our names on paper lanterns\nDown by the river in July\nYou said the wind would know the answer\nIf we just let the fire fly\nYour hand was shaking, mine was steady\nAt least that'\''s how I tell it now\nWe watched them climb until the city\nWas just a glow beneath the clouds\n\n[Pre-Chorus]\nSo every summer I come back here\nStrike a match and hold it near\n\n[Chorus]\nLight it up and let it go\nEvery word I never said out loud\nLight it up and let it go\nHigher than the both of us somehow\nAnd if it finds you anyhow\nTell me you can see it from the clouds\n\n[Verse 2]\nThey tore the old pier down last winter\nPut up a fence and painted lines\nBut I still know the way by heartbeat\nI find the water every time\nI keep a lighter in my pocket\nI keep your laugh inside my head\nI fold the paper like you showed me\nAnd write the things I should have said\n\n[Pre-Chorus]\nSo every summer I come back here\nStrike a match and hold it near\n\n[Chorus]\nLight it up and let it go\nEvery word I never said out loud\nLight it up and let it go\nHigher than the both of us somehow\nAnd if it finds you anyhow\nTell me you can see it from the clouds\n\n[Bridge]\nPaper and fire, paper and fire\nNothing this light should rise so high\nPaper and fire, paper and fire\nMaybe that'\''s how we say goodbye\n\n[Final Chorus]\nLight it up and let it go\nEvery word I never said out loud\nLight it up and let it go\nHigher than the both of us somehow\n\n[Outro]\nDown by the river in July", "model": "acemusic-v1", "duration": 210, "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-paper-lanterns-custom-lyrics.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> 一首纯音乐:`instrumental: true`,150 秒,不要人声、合唱和原声吉他: ``` Style: cinematic synthwave instrumental for a night drive: pulsing analog bass arpeggio, gated reverb drums, lush pads, a soaring lead synth melody, builds to a big final section, 108 bpm ``` ACE Music v1 — “Neon Overpass” · 2:29 · 生成用时 46 秒 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "title": "Neon Overpass", "style": "cinematic synthwave instrumental for a night drive: pulsing analog bass arpeggio, gated reverb drums, lush pads, a soaring lead synth melody, builds to a big final section, 108 bpm", "instrumental": true, "model": "acemusic-v1", "duration": 150, "negative": "vocals, choir, acoustic guitar", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-neon-overpass-synthwave-instrumental.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> 西班牙语歌词,唱的是一场停电时的屋顶派对: ``` Style: modern cumbia pop, bright accordion hooks, güira and congas, warm bass, a festive male lead with a crowd shouting the chorus, 98 bpm Lyrics: [Chorus] Bailando en la azotea / Con las estrellas de farol … ``` ACE Music v1 — “Bailando en la Azotea” · 2:32 · 生成用时 46 秒 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "title": "Bailando en la Azotea", "style": "modern cumbia pop, bright accordion hooks, güira and congas, warm bass, a festive male lead with a crowd shouting the chorus, 98 bpm", "lyrics": "[Verse 1]\nSe fue la luz en todo el barrio\nY nadie quiere irse a dormir\nDoña Rosa saca el radio viejo\nY la noche empieza a sonreír\nLos vecinos suben con sus sillas\nAlguien trae limones y café\nY la ciudad allá abajo, oscura\nNos mira bailar sin saber por qué\n\n[Pre-Chorus]\nSube, sube, que la luna está invitando\nSube, sube, que la calle está cantando\n\n[Chorus]\nBailando en la azotea\nCon las estrellas de farol\nQue se entere todo el mundo\nQue esta noche no hay apagón\nBailando en la azotea\nCon el corazón de tambor\nSi se apaga la ciudad entera\nAquí arriba sobra amor\n\n[Verse 2]\nEl abuelo saca la guitarra\nLa vecina de enfrente se animó\nLos niños corren entre las sábanas\nQue el viento de la tarde colgó\nNadie sabe cuándo vuelve la corriente\nY la verdad, a nadie le importó\nEsta fiesta no la paga nadie\nEsta fiesta la invitó el apagón\n\n[Chorus]\nBailando en la azotea\nCon las estrellas de farol\nQue se entere todo el mundo\nQue esta noche no hay apagón\nBailando en la azotea\nCon el corazón de tambor\nSi se apaga la ciudad entera\nAquí arriba sobra amor\n\n[Outro]\nQue esta noche no hay apagón", "model": "acemusic-v1", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-bailando-en-la-azotea-spanish-cumbia.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> 歌词由歌词生成接口写,风格由风格生成接口写,由 ACE-Step 演唱: ``` Lyrics writer: A wistful country song about an old pickup truck that still has her mixtape stuck in the tape deck Style writer: classic country ballad, pedal steel, warm baritone ``` ACE-Step v1.5 XL,不消耗积分 — “Side B Forever” · 3:35 · 生成用时 40 秒,此前写歌词用时 6 秒、写风格用时 4 秒 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music/lyrics' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "A wistful country song about an old pickup truck that still has her mixtape stuck in the tape deck", "style": "classic country ballad, pedal steel, warm baritone", "model": "ace-step-1.5-xl" }' > lyrics.json curl -X POST 'https://api.useapi.net/v1/acemusic/music/style' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "style": "classic country ballad, pedal steel, warm baritone", "model": "ace-step-1.5-xl" }' > style.json # sing what the writers returned jq -n --slurpfile l lyrics.json --slurpfile s style.json \ '{title: $l[0].title, lyrics: $l[0].lyrics, style: $s[0].style, model: "ace-step-1.5-xl", async: true}' | curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d @- ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-side-b-forever-lyrics-and-style-writers.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### 用 ACE-Step 设定速度、调性和拍子 每首歌的时长都与请求完全一致。 ``` 3/4 · 84 bpm · D minor · 120 s · thinking 60 · avoid: trap drums, EDM, autotune Style: dark cabaret waltz, accordion, pizzicato strings, upright bass, brushed snare, theatrical female vocal ``` ACE-Step v1.5 XL,不消耗积分 — “Midnight Waltz” · 2:00 · 生成用时 31 秒 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "model": "ace-step-1.5-xl", "title": "Midnight Waltz", "style": "dark cabaret waltz, accordion, pizzicato strings, upright bass, brushed snare, theatrical female vocal", "lyrics": "[Verse 1]\nThe band plays slow when the lights go low\nAnd the chandeliers begin to sway\nTake my hand, we will dance till the candles stand\nIn puddles of yesterday\n\n[Chorus]\nOne, two, three, turn around with me\nRound and round till the morning comes\nOne, two, three, oh don'\''t let me be\nThe last one dancing when the music'\''s done\n\n[Verse 2]\nThe clock strikes twelve and it laughs at itself\nEvery mirror wears a stranger'\''s face\nHold me close, we are only ghosts\nWho forgot to leave this place\n\n[Chorus]\nOne, two, three, turn around with me\nRound and round till the morning comes\nOne, two, three, oh don'\''t let me be\nThe last one dancing when the music'\''s done", "bpm": 84, "timeSignature": "3/4", "key": "D minor", "duration": 120, "negative": "trap drums, EDM, autotune", "thinking": 60, "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-midnight-waltz-3-4-84-bpm-d-minor.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ``` 6/8 · 116 bpm · G major · 90 s · instrumental Style: lively celtic instrumental jig, fiddle and tin whistle trading the melody, bodhran, strummed bouzouki, foot stomps ``` ACE-Step v1.5 XL,不消耗积分 — “Harbour Jig” · 1:30 · 生成用时 20 秒 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "model": "ace-step-1.5-xl", "title": "Harbour Jig", "style": "lively celtic instrumental jig, fiddle and tin whistle trading the melody, bodhran, strummed bouzouki, foot stomps", "instrumental": true, "bpm": 116, "timeSignature": "6/8", "key": "G major", "duration": 90, "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-harbour-jig-6-8-116-bpm-g-major.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ``` 4/4 · 174 bpm · F minor · 150 s · thinking 80 Style: liquid drum and bass, rolling breakbeats, deep warm sub bass, airy pads, soulful female vocal ``` ACE-Step v1.5 XL,不消耗积分 — “Almost Home” · 2:30 · 生成用时 41 秒 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "model": "ace-step-1.5-xl", "title": "Almost Home", "style": "liquid drum and bass, rolling breakbeats, deep warm sub bass, airy pads, soulful female vocal", "lyrics": "[Verse]\nCity lights in the rear view mirror\nRunning on a borrowed night\nEvery bridge is a little bit nearer\nEvery tunnel full of light\n\n[Chorus]\nHold on, we'\''re almost home\nEvery signal turning green\nHold on, you'\''re not alone\nFaster than the in-between\n\n[Verse]\nRadio low and the windows open\nBreathing in the summer rain\nEvery promise we left unspoken\nRushing back to us again\n\n[Chorus]\nHold on, we'\''re almost home\nEvery signal turning green\nHold on, you'\''re not alone\nFaster than the in-between", "bpm": 174, "timeSignature": "4/4", "key": "F minor", "duration": 150, "thinking": 80, "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-almost-home-drum-and-bass-174-bpm-f-minor.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### 一首翻唱、一首重混和一次编辑 “Paper Lanterns”的翻唱,换上新风格,保留原有旋律: ``` mode: cover · stripped-back acoustic folk cover, fingerpicked steel-string guitar, warm cello, soft close-mic'd male vocal ``` ACE Music v1.1 Preview — “Paper Lanterns (Acoustic Folk Cover)” · 3:34 · 生成用时 72 秒 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash # our script read the score first (free for an ACE Music v1 song; the API now does this by itself) curl 'https://api.useapi.net/v1/acemusic/music/score?songId=user%3A12345-example%40example.com-song%3Aso_4e7b2c9d0a5f4183b6d8e2c7' \ -H 'Authorization: Bearer user:12345-…' > /dev/null curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "mode": "cover", "model": "acemusic-v1.1", "references": ["user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7"], "style": "stripped-back acoustic folk cover, fingerpicked steel-string guitar, warm cello, soft close-mic'\''d male vocal", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-1-paper-lanterns-acoustic-folk-cover.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> 把“Bailando en la Azotea”改成 deep house。我们没有发送标题,所以 ACE Music 把它命名为“Reference 1”: ``` mode: remix · coverStrength 40 · remixStrength 50 · deep house remix, four-on-the-floor kick, plucky chords, rolling bassline, filtered vocal chops ``` ACE-Step v1.5 XL,不消耗积分 — “Reference 1” · 2:32 · 生成用时 31 秒 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "mode": "remix", "model": "ace-step-1.5-xl", "references": ["user:12345-example@example.com-song:so_9d3b7e2c1a6f4085b8e4d1c6"], "style": "deep house remix, four-on-the-floor kick, plucky chords, rolling bassline, filtered vocal chops", "coverStrength": 40, "remixStrength": 50, "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-bailando-en-la-azotea-house-remix.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> 给“Paper Lanterns”第 30 到 50 秒换上新歌词,其余部分保留: ``` mode: edit · start 30 · end 50 Lyrics: We wrote our names on paper lanterns / Down by the harbor in the snow / You said the stars would keep the answer / If we were brave enough to go ``` ACE-Step v1.5 XL,不消耗积分 — “Reference 1” · 3:29 · 生成用时 41 秒 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "mode": "edit", "model": "ace-step-1.5-xl", "references": ["user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7"], "start": 30, "end": 50, "style": "cinematic indie pop ballad, felt piano, swelling strings, intimate female vocal", "lyrics": "We wrote our names on paper lanterns\nDown by the harbor in the snow\nYou said the stars would keep the answer\nIf we were brave enough to go", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-paper-lanterns-edit-seconds-30-50.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### 混搭 “Paper Lanterns”和“Let the 44 Roll By”: ``` upbeat neo-soul pop mashup, punchy live drums, warm Rhodes and strings, female lead with a gospel-tinged choir on the chorus · audioInfluence 60 ``` ACE Music v1.1 Preview — “Lanterns at the Bus Stop” · 3:58 · 生成用时 83 秒 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash # our script read each song's score first (the API now does this by itself for ACE Music v1 songs) curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "mode": "mashup", "model": "acemusic-v1.1", "references": ["user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7", "user:12345-example@example.com-song:so_7c1d9e3a5b2f4806a4e1c9d3"], "title": "Lanterns at the Bus Stop", "style": "upbeat neo-soul pop mashup, punchy live drums, warm Rhodes and strings, female lead with a gospel-tinged choir on the chorus", "audioInfluence": 60, "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-1-mashup-lanterns-at-the-bus-stop.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> “Haul for the Harbor Light”和“Bailando en la Azotea”,在 ACE Music v1 上请求: ``` festive celtic cumbia mashup, fiddle and accordion trading hooks, congas and bodhran, stomping kick, male lead with a big crowd chorus ``` ACE Music v1.1 Preview(请求的是 v1)— “Harbor Fiesta” · 2:38 · 生成用时 74 秒 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash # our script read each song's score first (the API now does this by itself for ACE Music v1 songs) curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "mode": "mashup", "model": "acemusic-v1", "references": ["user:12345-example@example.com-song:so_2a8f6c1e9d4b47f3b0c5e8a2", "user:12345-example@example.com-song:so_9d3b7e2c1a6f4085b8e4d1c6"], "title": "Harbor Fiesta", "style": "festive celtic cumbia mashup, fiddle and accordion trading hooks, congas and bodhran, stomping kick, male lead with a big crowd chorus", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-1-mashup-harbor-fiesta-asked-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> 一次混搭三首歌:“Paper Lanterns”、“Bailando en la Azotea”和“Let the 44 Roll By”: ``` warm late-night soul-pop medley, Rhodes and strings, light latin percussion, female lead with a male answer on the last chorus ``` ACE Music v1.1 Preview — “Three Songs, One Night” · 3:32 · 生成用时 43 秒 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash # our script read each song's score first (the API now does this by itself for ACE Music v1 songs) curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "mode": "mashup", "model": "acemusic-v1.1", "references": ["user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7", "user:12345-example@example.com-song:so_9d3b7e2c1a6f4085b8e4d1c6", "user:12345-example@example.com-song:so_7c1d9e3a5b2f4806a4e1c9d3"], "title": "Three Songs, One Night", "style": "warm late-night soul-pop medley, Rhodes and strings, light latin percussion, female lead with a male answer on the last chorus", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-1-mashup-three-songs-one-night.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### 你的音频和图片 把上面的“Harbour Jig”作为 MP3 上传,并用作提示词的参考。ACE Music 在 v1.1 上运行它,以保留原曲调: ``` A rowdy pub singalong with a big shouted chorus about the last ferry home, built on the tune of this recording ``` ACE Music v1.1 Preview(请求的是 v1)— “Last Ferry Home” · 1:36 · 生成用时 52 秒 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/files?title=Harbour%20Jig%20demo' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: audio/mpeg' \ --data-binary @harbour-jig-demo.mp3 curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "A rowdy pub singalong with a big shouted chorus about the last ferry home, built on the tune of this recording", "model": "acemusic-v1", "references": ["user:12345-example@example.com-song:so_5f1a3c8e7b2d49a6c3e0f7b9"], "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-1-last-ferry-home-from-uploaded-jig.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### “Paper Lanterns”的分轨 `mode: "vocals"`(5 积分)拆出的人声和伴奏,以及 `mode: "all"`(60 积分)拆出的 9 条音轨中的鼓和弦乐。 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music/stems' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "songId": "user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7", "mode": "vocals", "async": true }' curl -X POST 'https://api.useapi.net/v1/acemusic/music/stems' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "songId": "user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7", "mode": "all", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-paper-lanterns-stem-vocal.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-paper-lanterns-stem-instrumental.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-paper-lanterns-stem-drums.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-paper-lanterns-stem-strings.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ### 常见问题 **有 ACE Music API 吗?** 通过 useapi.net 就有:[ACE Music API](/docs/api-acemusic-v1) 在你的 ACE Music 账号上通过 REST 运行 ACE Music v1、ACE Music v1.1 Preview 和 ACE-Step v1.5 XL,支持翻唱、混搭、分轨和 MIDI。 **有免费的 ACE-Step API 吗?** 通过 useapi.net 就有:在任何 ACE Music 套餐上(包括免费套餐),ACE-Step v1.5 XL 歌曲都不消耗积分,并支持速度、调性、拍号和时长设置,以及重混和编辑。第三方 acestep.io 只在其每月 $49 的 Studio 套餐中提供 ACE-Step API,每首约 $0.14(截至 2026 年 11 月)。 **通过 API 生成一首 ACE Music v1 歌曲要多少钱?** 通过 useapi.net,一首 ACE Music v1 歌曲消耗你 ACE Music 套餐的 2 积分:Artist 年付为 $0.013,Artist 月付为 $0.023,不按歌曲额外收费。见[价格](#pricing)。 **有 ACE Music MCP 服务器吗?** 通过 useapi.net 就有,而且比 ACE Music 自己在 `acemusic.ai/mcp` 的服务器功能更多:托管的 [ACE Music MCP 服务器](/docs/api-acemusic-v1/mcp)增加了免费的 ACE-Step v1.5 XL 模型、免费套餐下载 MP3、分轨、一次调用完成的翻唱、重混、编辑和混搭、MusicXML,以及一个 API Token 下的多个账号。ACE Music 自己的服务器根据你的助手写的歌词生成 v1 和 v1.1 歌曲,而且任何下载都需要付费套餐。见[对比](#useapinet-vs-ace-musics-own-mcp-server)。 ### 结语 一次 POST 就能在人声排行榜第一的模型上生成两首歌,ACE-Step 歌曲不花一分钱,每首歌都可以在下一次调用中继续做成翻唱、混搭、分轨或 MIDI 文件。克隆 [`acemusic-api` 仓库](https://github.com/useapi/acemusic-api),在免费账号上用 `--only 3` 运行 `songs-from-prompt/`,所有选项见 [POST /music](/docs/api-acemusic-v1/post-acemusic-music)。 有问题欢迎加入我们的 <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord 服务器</a> 或 <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram 频道</a>。 === URL: https://useapi.net/docs/articles/ace-music-api-tutorial === Document URL: https://useapi.net/docs/articles/ace-music-api-tutorial --- layout: default title: How to Generate AI Songs with the ACE Music API description: "Make songs with ACE Music v1, v1.1 and the free ACE-Step v1.5 XL through the useapi.net ACE Music API: prompts, your own lyrics, covers, mashups, stems, MIDI, with curl and code." keywords: [ACE Music API, ACE Music v1 API, ACE-Step API, ACE-Step v1.5 XL, AI song generator API, text to music API, Suno alternative, AI music API, stems API, MIDI, MusicXML, mashup, cover song AI, MCP server, curl, tutorial] image: https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-paper-lanterns-cover-art.jpg parent: Articles nav_exclude: true date: 2026-11-14 last_modified: 2026-11-18 nav_order: 302 repo: https://github.com/useapi/acemusic-api translation_key: ace-music-tutorial --- ## How to Generate AI Songs with the ACE Music API 22 min read • November 14, 2026 ## Table of contents ### Introduction The useapi.net [ACE Music API](/docs/api-acemusic-v1) turns one REST call into two finished songs from [ACE Music](https://acemusic.ai), with vocals, lyrics, a title and cover art, on the ACE Music subscription you already have. ACE Music v1 ranks #1 on [Artificial Analysis' vocal music leaderboard](https://artificialanalysis.ai/music/leaderboard/vocals), ahead of Suno v6. The open-source [ACE-Step](https://ace-step.github.io) v1.5 XL runs through the same API for no credits on any ACE Music plan, the Free plan included. This guide starts with the three models and what a song costs, makes one song end to end with `curl`, then covers every other feature in a short table. The [Examples](#examples) at the end are 18 songs we made for this page, each with the request that made it, all from the scripts in the [`acemusic-api` GitHub repo](https://github.com/useapi/acemusic-api) (Node.js and Python), for 117 credits of an Artist plan, extra takes included. useapi.net is a [third-party](/docs/legal#affiliation--third-party-services) API, not affiliated with ACE Music or its maker Timedomain. ### Models and what the API can do Every request makes two songs, and `model` picks who makes them: | Model | `model` | What it's for | Settings | Credits per request | Time in our runs | |---|---|---|---|---|---| | ACE Music v1 | `acemusic-v1` (default) | The #1 vocal model: songs from a prompt or your lyrics, sung or instrumental | `duration` 30 to 600 s, `negative`, `styleInfluence`, WAV downloads | 4 | 46 to 89 s | | ACE Music v1.1 Preview | `acemusic-v1.1` | Writes a score first, so its covers and mashups follow a song's melody | `audioInfluence`, `styleInfluence` | 4 | 35 to 83 s | | ACE-Step v1.5 XL | `ace-step-1.5-xl` | Open source by ACE Studio and StepFun: songs, remixes and edits | `bpm`, `key`, `timeSignature`, `duration` 10 to 240 s, `negative`, `thinking`. MP3 only | 0 | 20 to 55 s | What you can do with them: | What | Request | Notes | |---|---|---| | Songs from a prompt | [POST /music](/docs/api-acemusic-v1/post-acemusic-music) `prompt` | ACE Music writes the style, lyrics and title | | Your own lyrics, instrumentals | [POST /music](/docs/api-acemusic-v1/post-acemusic-music) `style`, `lyrics` | Any language | | Lyrics and style writers | [POST /music/lyrics](/docs/api-acemusic-v1/post-acemusic-music-lyrics), [/music/style](/docs/api-acemusic-v1/post-acemusic-music-style) | No credits | | Covers, remixes, edits, mashups | [POST /music](/docs/api-acemusic-v1/post-acemusic-music#modes) `mode` | On any song of the account | | Your audio and pictures | [POST /files](/docs/api-acemusic-v1/post-acemusic-files) | As references for new songs | | Stems | [POST /music/stems](/docs/api-acemusic-v1/post-acemusic-music-stems) | Creator and Artist | | Downloads, score | [GET /music/download](/docs/api-acemusic-v1/get-acemusic-music-download), [/music/score](/docs/api-acemusic-v1/get-acemusic-music-score) | MP3 and the score on every plan, WAV, MIDI and MusicXML on Creator and Artist | | Library, jobs, accounts | [GET /music](/docs/api-acemusic-v1/get-acemusic-music), [/jobs](/docs/api-acemusic-v1/get-acemusic-jobs), [/accounts](/docs/api-acemusic-v1/get-acemusic-accounts-email) | Every song of the account, running jobs, live credits | | MCP server | [`/v1/acemusic/mcp`](/docs/api-acemusic-v1/mcp) | 15 tools for AI assistants | ### Pricing ACE Music charges its own credits per request, from your ACE Music plan, and useapi.net adds nothing per song (as of November 2026): | Request | Credits | |---|---| | Two songs on ACE Music v1 or v1.1 | 4 | | Stems, vocal + instrumental | 5, paid plans | | Stems, every stem | 60, paid plans | | Score of an ACE-Step song, first read | 1 | | Two songs on ACE-Step v1.5 XL | 0, on every plan | | Lyrics and style writers, uploads, downloads | 0 in our tests | The [ACE Music plans](https://acemusic.ai/pricing/) are Free with 20 credits a day, Creator $9.90 a month for 1,000 credits and Artist $29 a month for 2,500 credits, or $7.90 and $16.58 a month billed yearly. A song is half a request, 2 credits. The [API overview](/docs/api-acemusic-v1#pricing) has the same table. What one song costs on each plan, cheapest on the left (a request makes two songs, so a song is half a request's credits; as of November 2026): | Model | Free (20 cr/day) | Artist $16.58/m (2,500 cr/mo, billed yearly) | Creator $7.90/m (1,000 cr/mo, billed yearly) | Creator $9.90/m (1,000 cr/mo) | Artist $29/m (2,500 cr/mo) | |---|---|---|---|---|---| | ACE Music v1, v1.1 (a song) | $0 / 2 cr (10 songs/day) | $0.013 / 2 cr (1,250 songs/mo) | $0.016 / 2 cr (500 songs/mo) | $0.020 / 2 cr (500 songs/mo) | $0.023 / 2 cr (1,250 songs/mo) | | Stems (vocal + instrumental) | paid plans | $0.033 / 5 cr | $0.040 / 5 cr | $0.050 / 5 cr | $0.058 / 5 cr | | Stems (every stem) | paid plans | $0.40 / 60 cr | $0.47 / 60 cr | $0.59 / 60 cr | $0.70 / 60 cr | | ACE-Step score (first read) | $0 / 1 cr | $0.007 / 1 cr | $0.008 / 1 cr | $0.010 / 1 cr | $0.012 / 1 cr | | ACE-Step v1.5 XL (a song) | $0 / 0 cr | $0 / 0 cr | $0 / 0 cr | $0 / 0 cr | $0 / 0 cr | How that compares with the other ways to call these models from code: | Model | useapi.net | Other APIs | |---|---|---| | ACE Music v1, v1.1 Preview | from $0.013 a song on Artist billed yearly, $0 on the Free plan's 20 daily credits | — | | ACE-Step v1.5 XL | $0 on every ACE Music plan, the Free plan included | about $0.14 a song on the third-party [acestep.io](https://acestep.io/pricing) API, which needs its $49 a month Studio plan | On any ACE Music plan, the Free plan included, an ACE-Step v1.5 XL song uses no credits, against the API of the third-party acestep.io, which needs its $49 a month Studio plan (about 360 songs a month, about $0.14 a song, as of November 2026). ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. ### How to generate a song with curl You need a useapi.net API token, see [Setup useapi.net](/docs/start-here/setup-useapi), and an [ACE Music](https://acemusic.ai) account with an email and a password. One [$15 a month subscription](/docs/subscription) covers every useapi.net API and 3 ACE Music accounts. A Free ACE Music account works: it gets 20 credits a day, and ACE-Step songs need none. The commands use [jq](https://jqlang.org) to read the JSON. #### Add your ACE Music account Export the token, then add the account once. The API signs in, reads the account and stores it only if ACE Music accepts the password: ```bash export USEAPI_TOKEN="user:12345-..." API=https://api.useapi.net/v1/acemusic curl -s -X POST "$API/accounts" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "example@example.com", "password": "your-acemusic-password" }' ``` An account made with Continue with Google or a phone number needs a password first, see [Setup ACE Music](/docs/start-here/setup-acemusic), which can also add it for you. #### Make songs from a prompt Describe the song in your own words. ACE Music writes the style, the lyrics and the title, then makes two songs. This is the exact request behind the first song on this page: ```bash curl -s -X POST "$API/music" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A late-night neo-soul slow jam about two strangers sharing an umbrella at a bus stop in the rain and missing the last bus on purpose. Warm Rhodes piano, brushed drums, round upright bass, a smoky female lead with close three-part harmonies on the chorus.", "model": "acemusic-v1", "async": true }' | tee job.json | jq '{jobid, status, model}' ``` With `async: true` the API answers `201` at once with the job. A prompt can be up to 2,000 characters and take up to 3 reference songs and 3 pictures, see [Guide songs with your own audio and images](#guide-songs-with-your-own-audio-and-images). #### What you get back While ACE Music writes the lyrics the songs are `planning` and `Untitled`, then `queued` and `running`. Poll [GET /jobs/`jobid`](/docs/api-acemusic-v1/get-acemusic-jobs-jobid) every 10 seconds or so. The `jobid` contains `:` and `@`, so URL-encode it: ```bash curl -s "$API/jobs/$(jq -r .jobid job.json | jq -Rr @uri)" \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{status, songs: [.songs[] | {title, status, duration, audioUrl}]}' ``` When `status` is `completed`, each song carries its links (the ids below are made up): ```json { "jobid": "j1115003713275918262m-u12345-email:example@example.com-task:so_7c1d9e3a5b2f4806a4e1c9d3.so_8b4f2e6a1c9d47e5a3b7c0d2-bot:acemusic", "type": "music", "status": "completed", "email": "example@example.com", "created": "2026-11-15T00:37:13.275Z", "model": "acemusic-v1", "modelUsed": "acemusic-v1", "songs": [ { "songId": "user:12345-example@example.com-song:so_7c1d9e3a5b2f4806a4e1c9d3", "taskId": "so_7c1d9e3a5b2f4806a4e1c9d3", "status": "succeeded", "title": "Let the 44 Roll By", "model": "acemusic-v1", "style": "Late-night neo-soul slow jam with a laid-back 1990s and early 2000s pocket, 72 BPM. …", "lyrics": "[Intro - Warm Rhodes chords, brushed snare rim clicks, subtle rain on asphalt]\n\n[Verse 1 …]\nWater dripping off the canvas seam\n…", "instrumental": false, "duration": 277.19, "audioUrl": "https://acemusic.ai/data/so_7c1d9e3a5b2f4806a4e1c9d3.mp3", "playUrl": "https://….r2.cloudflarestorage.com/acemusic-data-prod/users/…/audio/202611/….mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20261115T003902Z&X-Amz-Expires=3599&…", "playUrlExpires": "2026-11-15T01:39:01.000Z", "coverUrl": "https://acemusic.ai/data/so_7c1d9e3a5b2f4806a4e1c9d3-cover.jpg?v=1794703081642", "pageUrl": "https://acemusic.ai/song/r4k8w2n6p9tz", "created": "2026-11-15T00:37:13.300Z", "finished": "2026-11-15T00:38:42.208Z", "kind": "original", "score": false }, { "songId": "user:12345-example@example.com-song:so_8b4f2e6a1c9d47e5a3b7c0d2", "title": "Let the 44 Roll By", "duration": 253.99, "…": "…" } ], "completed": "2026-11-15T00:38:42.208Z" } ``` - `audioUrl` is the song's public MP3 link and never changes. `playUrl` is a direct link to the same MP3 for web players, valid until `playUrlExpires` (about an hour): some browsers, such as Brave, block the redirect behind `audioUrl`. - `songId` is what covers, mashups, stems, downloads and the score take. It names the account the song is on, so those calls run there. - `model` is the model you asked for, `modelUsed` the one that ran (see [mashups](#mash-up-two-or-three-songs)). `kind` is `original`, `cover`, `edit`, `mashup` or `upload`, and `score` says whether the song has its score yet. - A song ACE Music could not make has `status: "failed"`, ACE Music's reason in `error`, and `refunded: true` when the credits came back. And here is the first of those two songs: ACE Music v1 — "Let the 44 Roll By" · 4:37 · generated in 89 s <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-let-the-44-roll-by-neo-soul-from-prompt.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### Sync, async and webhooks | You send | The POST answers | Then | |---|---|---| | `async: true` | `201` at once, with the job | Poll [GET /jobs/`jobid`](/docs/api-acemusic-v1/get-acemusic-jobs-jobid) | | no `async` | `200` with the finished job, the same JSON as above | Read the songs from the answer. A request still running after 100 seconds answers `202` with the job: poll it | | `replyUrl` and `replyRef` | as above, for sync and async alike | Your public `https` URL receives one `POST` of the finished job, with your `replyRef` in it | Our ACE-Step request without `async` came back in 37 seconds, and the webhook arrived 12 seconds after the songs finished. A job can be read for 7 days, and one still running 30 minutes after it started fails with `504`. [`async-webhooks/`](https://github.com/useapi/acemusic-api/tree/main/async-webhooks) runs all three ways and includes a small webhook receiver. <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl -s -X POST "$API/music" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A dreamy lo-fi hip hop beat for studying late at night: dusty vinyl crackle, mellow Rhodes chords, a soft upright bass and rain on the window", "model": "ace-step-1.5-xl", "replyUrl": "https://your-server.example.com/acemusic-hook", "replyRef": "lofi-1" }' | jq '{status, songs: [.songs[] | {title, duration, audioUrl}]}' ``` </details> ### Sing your own lyrics Send `style` and `lyrics` instead of `prompt`, and ACE Music sings your words in your style: | Field | What it does | Limits | |---|---|---| | `style` | Genre, instruments, mood, tempo and vocals | 1,000 characters, 512 on ACE-Step | | `lyrics` | Your words, any language, with `[Verse]`, `[Chorus]`, `[Bridge]` tags | 5,000 characters, 2,000 on ACE-Step | | `title` | The songs' title. Without one, ACE Music picks it | 80 characters | | `instrumental` | `true` for no vocals. A `style` with no `lyrics` does the same | | | `duration` | The length in seconds | 30 to 600 on ACE Music v1, 10 to 240 on ACE-Step | | `negative` | Styles to avoid | 200 characters, ACE Music v1 and ACE-Step | | `styleInfluence` | How strictly the style is followed | `0` to `100`, default `80`, ACE Music v1 and v1.1 | Never send `prompt` together with these fields: the API answers `400` and names what to drop. Our ballad asked for `duration: 210` came back at 210 and 209 seconds. It is in [Examples](#your-own-lyrics) with an instrumental and a song in Spanish. No words yet? [POST /music/lyrics](/docs/api-acemusic-v1/post-acemusic-music-lyrics) writes lyrics and a title from a request, and [POST /music/style](/docs/api-acemusic-v1/post-acemusic-music-style) turns a few words into a full style. Ours came back in 6 and 4 seconds, with no credits charged. Script: [`custom-lyrics/`](https://github.com/useapi/acemusic-api/tree/main/custom-lyrics). ### Control tempo, key and time signature with ACE-Step ACE-Step v1.5 XL takes musical settings the ACE Music models don't, and its songs use no credits: | Option | Values | |---|---| | `bpm` | `30` to `200` | | `timeSignature` | `2/4`, `3/4`, `4/4`, `6/8` | | `key` | `C major` to `B minor` (C, C#, D, Eb, E, F, F#, G, Ab, A, Bb, B) | | `duration` | `10` to `240` seconds | | `negative` | styles to avoid, up to 200 characters | | `thinking` | `0` to `100`: ACE-Step plans the whole song first, creative when low, steady when high | All three of our ACE-Step songs, a 3/4 waltz, a 6/8 jig and 174 bpm drum and bass, came back exactly as long as asked ([Examples](#ace-step-at-a-set-tempo-key-and-meter)). These options work in `mode` `generate` on `ace-step-1.5-xl` only, and anywhere else the API answers `400 Parameter bpm does not apply to mode generate on acemusic-v1`. Script: [`ace-step-options/`](https://github.com/useapi/acemusic-api/tree/main/ace-step-options). ### Covers, remixes and edits `mode` turns a request into work on songs you have. `references` takes their `songId`s: songs the API made, songs from your [Library](#your-library) or your own uploads. | `mode` | `references` | Runs on | Credits | What it does | |---|---|---|---|---| | `cover` | 1 song | `acemusic-v1.1`, or ACE-Step on `ace-step-1.5-xl` | 4 / 0 | The song in a new `style`, following its melody, chords and structure | | `remix` | 1 song | `ace-step-1.5-xl` | 0 | `coverStrength` keeps the original, `remixStrength` moves away from it (`0` to `100`) | | `edit` | 1 song | `ace-step-1.5-xl` | 0 | Rewrites the part between `start` and `end` seconds with new `lyrics`, keeps the rest | | `mashup` | 2 or 3 songs | `acemusic-v1.1` | 4 | One new song from several, see below | ACE Music v1.1 follows the melody it reads from a song's score. Our first cover of an ACE Music v1 song with no score yet failed with `ref_no_melody`, and the 4 credits came back, so the API now reads the score of an ACE Music v1 song first, for free, before a v1.1 cover or mashup. ACE-Step songs are not read automatically: if one answers `400` with `ref_no_melody`, call [GET /music/score](#read-the-score) on it first (1 credit), then send the request again. Script: [`covers-remix-edit/`](https://github.com/useapi/acemusic-api/tree/main/covers-remix-edit). #### Mash up two or three songs `mode: "mashup"` makes one song from 2 or 3 songs on the same account, combining their words unless you send `lyrics`. `audioInfluence` (0 to 100, default 60) sets how closely the songs are followed. A mashup has to read the songs, so it runs on ACE Music v1.1 Preview even when you ask for v1, as on the ACE Music website: our "Harbor Fiesta" reports `"model": "acemusic-v1"` and `"modelUsed": "acemusic-v1.1"`, and the credits follow the model that ran. The same happens to a `cover` asked on v1, a prompt with more than one reference on ACE-Step, and sometimes a prompt with a reference song. Script: [`mashup/`](https://github.com/useapi/acemusic-api/tree/main/mashup). ### Guide songs with your own audio and images [POST /files](/docs/api-acemusic-v1/post-acemusic-files) takes the file as the raw request body with its `Content-Type`: | Upload | Formats | Up to | You get | Use it as | |---|---|---|---|---| | Audio | MP3, WAV, FLAC, OGG, M4A, AAC | 100 MB, 8 minutes | A `songId`: a Library song, its lyrics, style, tempo and melody transcribed by ACE Music | One of up to 3 `references` of a prompt, or the song to cover, remix, edit or mash up | | Image | JPEG, PNG, WebP | 10 MB | A `mediaId` | One of up to 3 `images` of a prompt: ACE Music writes a song about it | ```bash curl -s -X POST "$API/files?title=Harbour%20Jig%20demo" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: audio/mpeg" \ --data-binary @harbour-jig-demo.mp3 | jq '{songId, status, duration, bpm: .upload.bpm}' ``` Our 90-second upload of the "Harbour Jig" was transcribed in 14 seconds, and ACE Music heard 115 bpm (we had asked for 116). A picture of a dancing robot became a drum and bass song about its teal fur and orange high-tops. Both are in [Examples](#your-audio-and-pictures). Uploads count against the account's allowance: 10 minutes of audio on Free, 30 on Creator and 60 on Artist. Script: [`upload-reference/`](https://github.com/useapi/acemusic-api/tree/main/upload-reference). ### Stems, downloads and the score Every finished song can be split, downloaded and read as a score: | Request | Plans | Credits | You get | |---|---|---|---| | [Stems](/docs/api-acemusic-v1/post-acemusic-music-stems), `mode: "vocals"` | Creator, Artist | 5 | `vocal` and `instrumental` MP3s | | [Stems](/docs/api-acemusic-v1/post-acemusic-music-stems), `mode: "all"` | Creator, Artist | 60 | Every stem ACE Music finds, as MP3s | | [Download](/docs/api-acemusic-v1/get-acemusic-music-download) `mp3` (default) | every plan | 0 | `url` (the same as `audioUrl`) and `playUrl` | | Download `wav` | Creator, Artist | 0 | A link valid for 24 hours. Not for ACE-Step songs | | Download `midi`, `musicxml` | Creator, Artist | 0 | The file itself | | [Score](/docs/api-acemusic-v1/get-acemusic-music-score) | every plan | 0, 1 for an ACE-Step song the first time | [ABC notation](https://abcnotation.com): the vocal melody, an instrumental line, the chords and the sections | #### Split a song into stems The vocal split of "Paper Lanterns" took about 80 seconds, and the full one under 2 minutes, with 9 stems: vocals, backing vocals, drums, bass, guitar, keyboard, strings, synth and fx ([listen](#stems-of-paper-lanterns)). Stem links last 24 hours, so read the song again for fresh ones. Splitting a song again in the same mode answers at once and charges nothing. #### Download MP3, WAV, MIDI and MusicXML ACE Music makes WAV, MIDI and MusicXML on the first request: the API waits up to a minute, then answers `202`, so call again a minute later. For "Paper Lanterns" all three were ready within seconds: a 40 MB WAV, an 8 KB MIDI file and a 107 KB MusicXML score. <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash SONG="user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7" curl -s -G "$API/music/download" --data-urlencode "songId=$SONG" -d format=wav \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{url, expires}' curl -s -G "$API/music/download" --data-urlencode "songId=$SONG" -d format=midi \ -H "Authorization: Bearer $USEAPI_TOKEN" -o paper-lanterns.mid ``` </details> #### Read the score Any ABC tool turns the score into sheet music. For "Paper Lanterns" it read 72 bpm, the tempo we asked for in the style. ACE Music v1.1 songs come with their score, and v1.1 covers and mashups follow it, see [Covers, remixes and edits](#covers-remixes-and-edits). <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash SONG="user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7" curl -s -G "$API/music/score" --data-urlencode "songId=$SONG" \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq -r .abc | head -14 ``` ``` X:1 T: M:2/4 L:1/16 Q:1/4=72 V: Vocal clef=treble name="Vocal Melody" snm="Vocal" V: Ins clef=treble name="Ins Melody" snm="Inst." K:Ab % intro V: Vocal Z|"Ab"z8|"Ab"z8|"Ab"z8| V: Ins Z|Ac2AcBA2|A2EAA2EA|Ac2AcBA2| ``` </details> Script: [`stems-and-downloads/`](https://github.com/useapi/acemusic-api/tree/main/stems-and-downloads), which saves the stems, every download format and the score. ### Your Library Every song and upload of the account, made here or on acemusic.ai, stays in its Library until deleted: | Request | What it does | |---|---| | [GET /music](/docs/api-acemusic-v1/get-acemusic-music) | A page of songs, newest first, with `next` for the following page. `email` is needed with more than one account. The songs of jobs older than 7 days are here | | [GET /music/`songId`](/docs/api-acemusic-v1/get-acemusic-music-songid) | One song with fresh links, and its stems when it was split | | [DELETE /music/`songId`](/docs/api-acemusic-v1/delete-acemusic-music-songid) | `204`: the song moves to the account's trash on acemusic.ai, and the API answers `404` for it from then on | <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash SONG="user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7" curl -s -G "$API/music" --data-urlencode "email=example@example.com" -d limit=20 \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{next, songs: [.songs[] | {title, model, kind, songId}]}' curl -s "$API/music/$(jq -rn --arg v "$SONG" '$v|@uri')" \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{title, score, audioUrl, playUrl, stems: (.stems // {} | keys)}' curl -s -o /dev/null -w "%{http_code}\n" -X DELETE "$API/music/$(jq -rn --arg v "$SONG" '$v|@uri')" \ -H "Authorization: Bearer $USEAPI_TOKEN" ``` </details> Script: [`library/`](https://github.com/useapi/acemusic-api/tree/main/library). ### Several ACE Music accounts Each useapi.net subscription connects 3 ACE Music accounts, up to 100 in total. A request without `email` goes to a healthy account with a free slot, and one that names a song, an upload or an image runs where that lives. An account runs up to `maxJobs` requests at once, 4 by default, ACE Music's own limit. One $15 subscription runs up to 12 song requests at once (3 accounts × 4 each), and every request makes two songs, so 24 songs generate in parallel, on ACE Music v1 or on ACE-Step v1.5 XL, which uses no credits. With every account busy the API answers `429` with `Retry-After`, and a password ACE Music refuses makes that account answer `596` until you add it again. [GET /accounts/`email`](/docs/api-acemusic-v1/get-acemusic-accounts-email) reads the plan, credits and credit costs live, and [POST /accounts](/docs/api-acemusic-v1/post-acemusic-accounts) with `email` and `maxJobs` alone changes only `maxJobs`. Script: [`accounts/`](https://github.com/useapi/acemusic-api/tree/main/accounts). <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl -s "$API/accounts/$(jq -rn --arg v "example@example.com" '$v|@uri')" \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{plan_name, credits, maxJobs, costs}' curl -s -X POST "$API/accounts" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "example@example.com", "maxJobs": 2 }' ``` </details> ### Use it from Claude, ChatGPT or Cursor (MCP) The same features are a hosted [MCP server](/docs/api-acemusic-v1/mcp) with 15 tools, from songs, covers and mashups to stems, scores and uploads. In Claude Code it is one command: ```bash claude mcp add --transport http useapi-acemusic https://api.useapi.net/v1/acemusic/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` Cursor, VS Code and Windsurf take the same URL and header, and the Claude app and ChatGPT sign in with OAuth, see [Use it in the Claude app or ChatGPT](/docs/api-acemusic-v1/mcp#use-it-in-the-claude-app-or-chatgpt). Then ask in plain words: "Write lyrics about a cat who loves rainy days and sing them as acoustic indie folk on ACE Music v1". #### useapi.net vs ACE Music's own MCP server ACE Music también tiene su propio servidor MCP en `https://acemusic.ai/mcp`. Crea canciones de ACE Music v1 y v1.1 a partir del estilo y la letra que escribe tu asistente. El servidor de useapi.net funciona con la misma cuenta de ACE Music y agrega todo lo demás (al 18 de noviembre de 2026): | | MCP de ACE Music de useapi.net | MCP propio de ACE Music | |---|---|---| | ACE-Step v1.5 XL, 0 créditos en todos los planes | Sí | No, solo ACE Music v1 y v1.1 | | Descarga de MP3 en el plan Free | Sí | No, toda descarga requiere un plan de pago | | Covers, remixes, ediciones y mashups | Una llamada para cada uno, a partir de tus canciones | El asistente los arma a partir de una partitura transcrita | | Stems: voz e instrumental, o cada instrumento | Sí | No | | Partituras MusicXML | Sí | No, solo MIDI | | Estilo, letra y título escritos por ACE Music a partir de una idea de una línea | Sí | No, los escribe el asistente | | Varias cuentas de ACE Music en una sola conexión | Sí | Una cuenta por conexión | | Token de API para scripts, n8n y agentes sin interfaz, además de OAuth | Sí | Solo inicio de sesión con OAuth | | Las mismas llamadas por REST, con jobs y webhooks | Sí | No | useapi.net es un servicio de terceros, sin afiliación con ACE Music. ACE Music juga punya MCP server sendiri di `https://acemusic.ai/mcp`. Server itu membuat lagu ACE Music v1 dan v1.1 dari gaya dan lirik yang ditulis asisten Anda. Server useapi.net bekerja di akun ACE Music yang sama dan menambahkan sisanya (per 18 November 2026): | | MCP ACE Music dari useapi.net | MCP milik ACE Music sendiri | |---|---|---| | ACE-Step v1.5 XL, 0 kredit di semua paket | Ya | Tidak, hanya ACE Music v1 dan v1.1 | | Download MP3 di paket Free | Ya | Tidak, setiap download butuh paket berbayar | | Cover, remix, edit, dan mashup | Masing-masing satu panggilan, dari lagu Anda | Dirangkai oleh asisten dari partitur hasil transkripsi | | Stem: vokal dan instrumental, atau setiap instrumen | Ya | Tidak | | Partitur MusicXML | Ya | Tidak, hanya MIDI | | Gaya, lirik, dan judul ditulis ACE Music dari ide satu baris | Ya | Tidak, asisten yang menulisnya | | Beberapa akun ACE Music dalam satu koneksi | Ya | Satu akun per koneksi | | Token API untuk skrip, n8n, dan agen headless, plus OAuth | Ya | Hanya login OAuth | | Panggilan yang sama lewat REST, dengan job dan webhook | Ya | Tidak | useapi.net adalah layanan pihak ketiga dan tidak berafiliasi dengan ACE Music. ACE Music も独自の MCP サーバーを `https://acemusic.ai/mcp` で提供しています。こちらは、アシスタントが書いたスタイルと歌詞から ACE Music v1 と v1.1 の曲を作ります。useapi.net のサーバーは同じ ACE Music アカウントで動き、それ以外のすべてを補います(2026年11月18日時点)。 | | useapi.net の ACE Music MCP | ACE Music 独自の MCP | |---|---|---| | ACE-Step v1.5 XL、どのプランでも0クレジット | 対応 | 非対応、ACE Music v1 と v1.1 のみ | | Free プランでの MP3 ダウンロード | 対応 | 非対応、ダウンロードにはすべて有料プランが必要 | | カバー、リミックス、編集、マッシュアップ | お手持ちの曲から、それぞれ1回の呼び出しで | 書き起こした楽譜をもとにアシスタントが組み立てる | | ステム:ボーカルとインスト、または楽器ごと | 対応 | 非対応 | | MusicXML の楽譜 | 対応 | 非対応、MIDI のみ | | 1行のアイデアから ACE Music がスタイル、歌詞、タイトルを書く | 対応 | 非対応、アシスタントが書く | | 1つの接続で複数の ACE Music アカウント | 対応 | 1接続につき1アカウント | | スクリプト、n8n、ヘッドレスエージェント向けの API トークンと OAuth | 対応 | OAuth サインインのみ | | 同じ呼び出しを REST で、ジョブと Webhook 付きで | 対応 | 非対応 | useapi.net はサードパーティのサービスで、ACE Music とは提携していません。 O ACE Music também tem o próprio servidor MCP em `https://acemusic.ai/mcp`. Ele gera músicas do ACE Music v1 e v1.1 a partir do estilo e da letra que o seu assistente escreve. O servidor da useapi.net funciona na mesma conta do ACE Music e acrescenta todo o resto (em 18 de novembro de 2026): | | MCP do ACE Music da useapi.net | MCP do próprio ACE Music | |---|---|---| | ACE-Step v1.5 XL, 0 créditos em todos os planos | Sim | Não, só ACE Music v1 e v1.1 | | Download de MP3 no plano Free | Sim | Não, todo download exige um plano pago | | Covers, remixes, edições e mashups | Uma chamada para cada, a partir das suas músicas | Montados pelo assistente a partir de uma partitura transcrita | | Stems: vocal e instrumental, ou cada instrumento | Sim | Não | | Partituras MusicXML | Sim | Não, só MIDI | | Estilo, letra e título escritos pelo ACE Music a partir de uma ideia de uma linha | Sim | Não, o assistente escreve | | Várias contas do ACE Music em uma só conexão | Sim | Uma conta por conexão | | Token de API para scripts, n8n e agentes headless, além de OAuth | Sim | Só login com OAuth | | As mesmas chamadas via REST, com jobs e webhooks | Sim | Não | A useapi.net é um serviço de terceiros, sem afiliação com o ACE Music. ACE Music มี MCP server ของตัวเองด้วยที่ `https://acemusic.ai/mcp` ซึ่งสร้างเพลง ACE Music v1 และ v1.1 จากสไตล์และเนื้อเพลงที่ผู้ช่วย AI ของคุณเขียน ส่วน server ของ useapi.net ทำงานบนบัญชี ACE Music เดียวกันและเพิ่มส่วนที่เหลือทั้งหมด (ข้อมูล ณ วันที่ 18 พฤศจิกายน 2026): | | ACE Music MCP ของ useapi.net | MCP ของ ACE Music เอง | |---|---|---| | ACE-Step v1.5 XL ใช้ 0 เครดิตในทุกแพ็กเกจ | ได้ | ไม่ได้ มีแค่ ACE Music v1 และ v1.1 | | ดาวน์โหลด MP3 ในแพ็กเกจ Free | ได้ | ไม่ได้ ทุกการดาวน์โหลดต้องใช้แพ็กเกจเสียเงิน | | คัฟเวอร์ รีมิกซ์ การแก้ไข และแมชอัป | เรียกครั้งเดียวต่ออย่าง จากเพลงของคุณ | ผู้ช่วย AI ประกอบเองจากโน้ตเพลงที่ถอดออกมา | | สเต็ม: เสียงร้องกับดนตรี หรือแยกทุกเครื่องดนตรี | ได้ | ไม่ได้ | | โน้ตเพลง MusicXML | ได้ | ไม่ได้ มีแค่ MIDI | | ACE Music เขียนสไตล์ เนื้อเพลง และชื่อเพลงจากไอเดียบรรทัดเดียว | ได้ | ไม่ได้ ผู้ช่วย AI ต้องเขียนเอง | | หลายบัญชี ACE Music ในการเชื่อมต่อเดียว | ได้ | หนึ่งบัญชีต่อการเชื่อมต่อ | | API token สำหรับสคริปต์ n8n และเอเจนต์ที่ไม่มีหน้าจอ พร้อม OAuth | ได้ | ล็อกอินด้วย OAuth เท่านั้น | | เรียกแบบเดียวกันผ่าน REST พร้อมงานและ webhook | ได้ | ไม่ได้ | useapi.net เป็นบริการของบุคคลที่สาม ไม่มีส่วนเกี่ยวข้องกับ ACE Music ACE Music cũng có MCP server riêng tại `https://acemusic.ai/mcp`. Server này tạo bài hát ACE Music v1 và v1.1 từ phong cách và lời bài hát do trợ lý của bạn viết. Server của useapi.net chạy trên cùng tài khoản ACE Music và bổ sung phần còn lại (tính đến 18 tháng 11 năm 2026): | | MCP ACE Music của useapi.net | MCP riêng của ACE Music | |---|---|---| | ACE-Step v1.5 XL, 0 credit trên mọi gói | Có | Không, chỉ ACE Music v1 và v1.1 | | Tải MP3 trên gói Free | Có | Không, mọi lượt tải đều cần gói trả phí | | Cover, remix, chỉnh sửa và mashup | Mỗi thứ một lệnh gọi, từ bài hát của bạn | Trợ lý tự ghép lại từ bản nhạc được chép ra | | Stem: giọng hát và nhạc nền, hoặc từng nhạc cụ | Có | Không | | Bản nhạc MusicXML | Có | Không, chỉ MIDI | | Phong cách, lời và tên bài do ACE Music viết từ một ý tưởng một dòng | Có | Không, trợ lý tự viết | | Nhiều tài khoản ACE Music trong một kết nối | Có | Một tài khoản cho mỗi kết nối | | API token cho script, n8n và agent chạy không giao diện, cùng với OAuth | Có | Chỉ đăng nhập OAuth | | Cùng các lệnh gọi qua REST, có job và webhook | Có | Không | useapi.net là dịch vụ của bên thứ ba, không liên kết với ACE Music. ACE Music 也在 `https://acemusic.ai/mcp` 运行自己的 MCP 服务器。它根据你的助手写好的风格和歌词生成 ACE Music v1 和 v1.1 歌曲。useapi.net 的服务器使用同一个 ACE Music 账号,并补上其余的一切(截至 2026 年 11 月 18 日): | | useapi.net ACE Music MCP | ACE Music 自己的 MCP | |---|---|---| | ACE-Step v1.5 XL,所有套餐都是 0 积分 | 支持 | 不支持,只有 ACE Music v1 和 v1.1 | | 免费套餐下载 MP3 | 支持 | 不支持,任何下载都需要付费套餐 | | 翻唱、重混、编辑和混搭 | 基于你的歌曲,各一次调用 | 由助手根据转写出的乐谱拼凑完成 | | 分轨:人声和伴奏,或每件乐器 | 支持 | 不支持 | | MusicXML 乐谱 | 支持 | 不支持,只有 MIDI | | 由 ACE Music 根据一句话的想法写出风格、歌词和标题 | 支持 | 不支持,由助手来写 | | 一个连接中使用多个 ACE Music 账号 | 支持 | 每个连接一个账号 | | 用于脚本、n8n 和无界面智能体的 API Token,另有 OAuth | 支持 | 只能 OAuth 登录 | | 通过 REST 进行同样的调用,带任务和 webhook | 支持 | 不支持 | useapi.net 是第三方服务,与 ACE Music 无关联。 ACE Music also runs its own MCP server at `https://acemusic.ai/mcp`. It makes ACE Music v1 and v1.1 songs from the style and lyrics your assistant writes. The useapi.net server works on the same ACE Music account and adds the rest (as of November 18, 2026): | | useapi.net ACE Music MCP | ACE Music's own MCP | |---|---|---| | ACE-Step v1.5 XL, 0 credits on every plan | Yes | No, ACE Music v1 and v1.1 only | | MP3 download on the Free plan | Yes | No, every download needs a paid plan | | Covers, remixes, edits and mashups | One call each, from your songs | Pieced together by the assistant from a transcribed score | | Stems: vocals and instrumental, or every instrument | Yes | No | | MusicXML scores | Yes | No, MIDI only | | Style, lyrics and title written by ACE Music from a one-line idea | Yes | No, the assistant writes them | | Several ACE Music accounts in one connection | Yes | One account per connection | | API token for scripts, n8n and headless agents, plus OAuth | Yes | OAuth sign-in only | | The same calls over REST, with jobs and webhooks | Yes | No | useapi.net is a third-party service, not affiliated with ACE Music. ### Batch-generate with the scripts The [`acemusic-api` GitHub repo](https://github.com/useapi/acemusic-api) has one example per feature, linked from each section above: a Node.js script and a Python twin, with nothing to install. Each reads its requests from a `prompts.json` you edit, runs up to 4 at once, polls the jobs, and saves both songs, their cover art, the job record and a `ledger.jsonl` of the credits used in its `output/` folder. You need [Node.js](https://nodejs.org) 21 or newer or [Python](https://www.python.org) 3.8 or newer. `--only 3` runs the third prompt below, an ACE-Step song with no credits, so it works on a Free account: ```bash git clone https://github.com/useapi/acemusic-api.git && cd acemusic-api export USEAPI_TOKEN="user:12345-..." node songs-from-prompt/songs-from-prompt.mjs --only 3 ``` Each saved job record holds the songs' `songId`s, and `--from <job>.json --pick 1` hands song 1 to the next script to cover, mash up or split. <details markdown="block"> <summary>Expand `songs-from-prompt/prompts.json`</summary> ```json [ { "_about": "ACE Music v1 (the default model, 4 credits for two songs): ACE Music writes the style, lyrics and title from your idea", "prompt": "A late-night neo-soul slow jam about two strangers sharing an umbrella at a bus stop in the rain and missing the last bus on purpose. Warm Rhodes piano, brushed drums, round upright bass, a smoky female lead with close three-part harmonies on the chorus.", "model": "acemusic-v1" }, { "_about": "ACE Music v1.1 Preview (4 credits): writes a score first, then the audio", "prompt": "An anthemic Celtic folk-rock singalong about a fishing crew racing a storm back to the harbor. Fiddle and tin whistle hooks, stomping kick drum, bodhran, a gravelly male lead and the whole crew shouting the chorus.", "model": "acemusic-v1.1" }, { "_about": "ACE-Step v1.5 XL (no credits on any ACE Music plan, the Free plan included)", "prompt": "A breezy bossa nova for a lazy Sunday afternoon in Lisbon: nylon-string guitar, soft brushed snare, upright bass, a gentle flute line and a warm male and female duet sung in Portuguese.", "model": "ace-step-1.5-xl" } ] ``` </details> ### Examples Every song below was made on November 14, 2026 (PST) with the repo's scripts on an ACE Music Artist account, the first of the two songs of each request. Titles come from ACE Music unless we set one, the times run from the request to both songs finished, and the calls show made-up ids. #### A song from a picture One picture and one sentence of style in, two finished songs out. We uploaded this photo of a dancing robot mascot and asked for drum and bass; ACE Music wrote the lyrics from what it saw: "Teal fur shaking on the concrete floor, orange high-tops squeaking by the studio door". <img src="https://media.useapi.net/blog/2026-09-07-260907/dreamina-longvideo-ref-robot-mascot.png" alt="A fluffy teal robot mascot with a box head, an antenna and light-up eyes, dancing in orange high-top sneakers" style="width: 100%; max-width: 220px;" loading="lazy"> ``` Bouncy, playful drum and bass for a dancing robot mascot: rolling breakbeats at 174 bpm, a wobbly reese bass, bleepy robot synth hooks, vocoder chops, cheeky and upbeat. ``` ACE Music v1 — "Bleep Boop Bounce" · 2:47 · generated in 72 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/files' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: image/png' \ --data-binary @robot-mascot.png curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "Bouncy, playful drum and bass for a dancing robot mascot: rolling breakbeats at 174 bpm, a wobbly reese bass, bleepy robot synth hooks, vocoder chops, cheeky and upbeat.", "model": "acemusic-v1", "images": ["user:12345-example@example.com-media:cx_3b9e1d7a5c2f48e0a6d4b8c1"], "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-bleep-boop-bounce-drum-and-bass-from-robot-image.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> The song as a YouTube Short, with the photo: [Bleep Boop Bounce on YouTube](https://youtube.com/shorts/z_aOmILvIng). #### Songs from a prompt The ACE Music v1 song from a prompt, "Let the 44 Roll By", is in the [walkthrough](#what-you-get-back). Two more prompts, on the other two models: ``` An anthemic Celtic folk-rock singalong about a fishing crew racing a storm back to the harbor. Fiddle and tin whistle hooks, stomping kick drum, bodhran, a gravelly male lead and the whole crew shouting the chorus. ``` ACE Music v1.1 Preview — "Haul for the Harbor Light" · 2:51 · generated in 43 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "An anthemic Celtic folk-rock singalong about a fishing crew racing a storm back to the harbor. Fiddle and tin whistle hooks, stomping kick drum, bodhran, a gravelly male lead and the whole crew shouting the chorus.", "model": "acemusic-v1.1", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-1-haul-for-the-harbor-light-celtic-folk-rock-from-prompt.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ``` A breezy bossa nova for a lazy Sunday afternoon in Lisbon: nylon-string guitar, soft brushed snare, upright bass, a gentle flute line and a warm male and female duet sung in Portuguese. ``` ACE-Step v1.5 XL, no credits — "Domingo em Alfama" · 3:28 <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "A breezy bossa nova for a lazy Sunday afternoon in Lisbon: nylon-string guitar, soft brushed snare, upright bass, a gentle flute line and a warm male and female duet sung in Portuguese.", "model": "ace-step-1.5-xl", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-domingo-em-alfama-bossa-nova-from-prompt.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### Your own lyrics Two verses, a pre-chorus, a bridge and an outro of our own, asked for 210 seconds: ``` Style: cinematic indie pop ballad, felt piano, swelling strings, deep heartbeat kick, intimate female vocal that opens up into a soaring chorus, 72 bpm Lyrics: [Verse 1] We wrote our names on paper lanterns / Down by the river in July … [Chorus] Light it up and let it go / Every word I never said out loud … ``` ACE Music v1 — "Paper Lanterns" · 3:29 · generated in 61 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "title": "Paper Lanterns", "style": "cinematic indie pop ballad, felt piano, swelling strings, deep heartbeat kick, intimate female vocal that opens up into a soaring chorus, 72 bpm", "lyrics": "[Verse 1]\nWe wrote our names on paper lanterns\nDown by the river in July\nYou said the wind would know the answer\nIf we just let the fire fly\nYour hand was shaking, mine was steady\nAt least that'\''s how I tell it now\nWe watched them climb until the city\nWas just a glow beneath the clouds\n\n[Pre-Chorus]\nSo every summer I come back here\nStrike a match and hold it near\n\n[Chorus]\nLight it up and let it go\nEvery word I never said out loud\nLight it up and let it go\nHigher than the both of us somehow\nAnd if it finds you anyhow\nTell me you can see it from the clouds\n\n[Verse 2]\nThey tore the old pier down last winter\nPut up a fence and painted lines\nBut I still know the way by heartbeat\nI find the water every time\nI keep a lighter in my pocket\nI keep your laugh inside my head\nI fold the paper like you showed me\nAnd write the things I should have said\n\n[Pre-Chorus]\nSo every summer I come back here\nStrike a match and hold it near\n\n[Chorus]\nLight it up and let it go\nEvery word I never said out loud\nLight it up and let it go\nHigher than the both of us somehow\nAnd if it finds you anyhow\nTell me you can see it from the clouds\n\n[Bridge]\nPaper and fire, paper and fire\nNothing this light should rise so high\nPaper and fire, paper and fire\nMaybe that'\''s how we say goodbye\n\n[Final Chorus]\nLight it up and let it go\nEvery word I never said out loud\nLight it up and let it go\nHigher than the both of us somehow\n\n[Outro]\nDown by the river in July", "model": "acemusic-v1", "duration": 210, "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-paper-lanterns-custom-lyrics.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> An instrumental: `instrumental: true`, 150 seconds, and no vocals, choir or acoustic guitar: ``` Style: cinematic synthwave instrumental for a night drive: pulsing analog bass arpeggio, gated reverb drums, lush pads, a soaring lead synth melody, builds to a big final section, 108 bpm ``` ACE Music v1 — "Neon Overpass" · 2:29 · generated in 46 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "title": "Neon Overpass", "style": "cinematic synthwave instrumental for a night drive: pulsing analog bass arpeggio, gated reverb drums, lush pads, a soaring lead synth melody, builds to a big final section, 108 bpm", "instrumental": true, "model": "acemusic-v1", "duration": 150, "negative": "vocals, choir, acoustic guitar", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-neon-overpass-synthwave-instrumental.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Spanish lyrics about a rooftop party during a blackout: ``` Style: modern cumbia pop, bright accordion hooks, güira and congas, warm bass, a festive male lead with a crowd shouting the chorus, 98 bpm Lyrics: [Chorus] Bailando en la azotea / Con las estrellas de farol … ``` ACE Music v1 — "Bailando en la Azotea" · 2:32 · generated in 46 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "title": "Bailando en la Azotea", "style": "modern cumbia pop, bright accordion hooks, güira and congas, warm bass, a festive male lead with a crowd shouting the chorus, 98 bpm", "lyrics": "[Verse 1]\nSe fue la luz en todo el barrio\nY nadie quiere irse a dormir\nDoña Rosa saca el radio viejo\nY la noche empieza a sonreír\nLos vecinos suben con sus sillas\nAlguien trae limones y café\nY la ciudad allá abajo, oscura\nNos mira bailar sin saber por qué\n\n[Pre-Chorus]\nSube, sube, que la luna está invitando\nSube, sube, que la calle está cantando\n\n[Chorus]\nBailando en la azotea\nCon las estrellas de farol\nQue se entere todo el mundo\nQue esta noche no hay apagón\nBailando en la azotea\nCon el corazón de tambor\nSi se apaga la ciudad entera\nAquí arriba sobra amor\n\n[Verse 2]\nEl abuelo saca la guitarra\nLa vecina de enfrente se animó\nLos niños corren entre las sábanas\nQue el viento de la tarde colgó\nNadie sabe cuándo vuelve la corriente\nY la verdad, a nadie le importó\nEsta fiesta no la paga nadie\nEsta fiesta la invitó el apagón\n\n[Chorus]\nBailando en la azotea\nCon las estrellas de farol\nQue se entere todo el mundo\nQue esta noche no hay apagón\nBailando en la azotea\nCon el corazón de tambor\nSi se apaga la ciudad entera\nAquí arriba sobra amor\n\n[Outro]\nQue esta noche no hay apagón", "model": "acemusic-v1", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-bailando-en-la-azotea-spanish-cumbia.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyrics by the lyrics writer, style by the style writer, sung by ACE-Step: ``` Lyrics writer: A wistful country song about an old pickup truck that still has her mixtape stuck in the tape deck Style writer: classic country ballad, pedal steel, warm baritone ``` ACE-Step v1.5 XL, no credits — "Side B Forever" · 3:35 · generated in 40 s, after 6 s for the lyrics and 4 s for the style <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music/lyrics' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "A wistful country song about an old pickup truck that still has her mixtape stuck in the tape deck", "style": "classic country ballad, pedal steel, warm baritone", "model": "ace-step-1.5-xl" }' > lyrics.json curl -X POST 'https://api.useapi.net/v1/acemusic/music/style' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "style": "classic country ballad, pedal steel, warm baritone", "model": "ace-step-1.5-xl" }' > style.json # sing what the writers returned jq -n --slurpfile l lyrics.json --slurpfile s style.json \ '{title: $l[0].title, lyrics: $l[0].lyrics, style: $s[0].style, model: "ace-step-1.5-xl", async: true}' | curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d @- ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-side-b-forever-lyrics-and-style-writers.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### ACE-Step at a set tempo, key and meter Each came back exactly as long as asked. ``` 3/4 · 84 bpm · D minor · 120 s · thinking 60 · avoid: trap drums, EDM, autotune Style: dark cabaret waltz, accordion, pizzicato strings, upright bass, brushed snare, theatrical female vocal ``` ACE-Step v1.5 XL, no credits — "Midnight Waltz" · 2:00 · generated in 31 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "model": "ace-step-1.5-xl", "title": "Midnight Waltz", "style": "dark cabaret waltz, accordion, pizzicato strings, upright bass, brushed snare, theatrical female vocal", "lyrics": "[Verse 1]\nThe band plays slow when the lights go low\nAnd the chandeliers begin to sway\nTake my hand, we will dance till the candles stand\nIn puddles of yesterday\n\n[Chorus]\nOne, two, three, turn around with me\nRound and round till the morning comes\nOne, two, three, oh don'\''t let me be\nThe last one dancing when the music'\''s done\n\n[Verse 2]\nThe clock strikes twelve and it laughs at itself\nEvery mirror wears a stranger'\''s face\nHold me close, we are only ghosts\nWho forgot to leave this place\n\n[Chorus]\nOne, two, three, turn around with me\nRound and round till the morning comes\nOne, two, three, oh don'\''t let me be\nThe last one dancing when the music'\''s done", "bpm": 84, "timeSignature": "3/4", "key": "D minor", "duration": 120, "negative": "trap drums, EDM, autotune", "thinking": 60, "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-midnight-waltz-3-4-84-bpm-d-minor.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ``` 6/8 · 116 bpm · G major · 90 s · instrumental Style: lively celtic instrumental jig, fiddle and tin whistle trading the melody, bodhran, strummed bouzouki, foot stomps ``` ACE-Step v1.5 XL, no credits — "Harbour Jig" · 1:30 · generated in 20 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "model": "ace-step-1.5-xl", "title": "Harbour Jig", "style": "lively celtic instrumental jig, fiddle and tin whistle trading the melody, bodhran, strummed bouzouki, foot stomps", "instrumental": true, "bpm": 116, "timeSignature": "6/8", "key": "G major", "duration": 90, "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-harbour-jig-6-8-116-bpm-g-major.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ``` 4/4 · 174 bpm · F minor · 150 s · thinking 80 Style: liquid drum and bass, rolling breakbeats, deep warm sub bass, airy pads, soulful female vocal ``` ACE-Step v1.5 XL, no credits — "Almost Home" · 2:30 · generated in 41 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "model": "ace-step-1.5-xl", "title": "Almost Home", "style": "liquid drum and bass, rolling breakbeats, deep warm sub bass, airy pads, soulful female vocal", "lyrics": "[Verse]\nCity lights in the rear view mirror\nRunning on a borrowed night\nEvery bridge is a little bit nearer\nEvery tunnel full of light\n\n[Chorus]\nHold on, we'\''re almost home\nEvery signal turning green\nHold on, you'\''re not alone\nFaster than the in-between\n\n[Verse]\nRadio low and the windows open\nBreathing in the summer rain\nEvery promise we left unspoken\nRushing back to us again\n\n[Chorus]\nHold on, we'\''re almost home\nEvery signal turning green\nHold on, you'\''re not alone\nFaster than the in-between", "bpm": 174, "timeSignature": "4/4", "key": "F minor", "duration": 150, "thinking": 80, "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-almost-home-drum-and-bass-174-bpm-f-minor.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### A cover, a remix and an edit "Paper Lanterns" as a cover, in a new style that keeps its melody: ``` mode: cover · stripped-back acoustic folk cover, fingerpicked steel-string guitar, warm cello, soft close-mic'd male vocal ``` ACE Music v1.1 Preview — "Paper Lanterns (Acoustic Folk Cover)" · 3:34 · generated in 72 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash # our script read the score first (free for an ACE Music v1 song; the API now does this by itself) curl 'https://api.useapi.net/v1/acemusic/music/score?songId=user%3A12345-example%40example.com-song%3Aso_4e7b2c9d0a5f4183b6d8e2c7' \ -H 'Authorization: Bearer user:12345-…' > /dev/null curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "mode": "cover", "model": "acemusic-v1.1", "references": ["user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7"], "style": "stripped-back acoustic folk cover, fingerpicked steel-string guitar, warm cello, soft close-mic'\''d male vocal", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-1-paper-lanterns-acoustic-folk-cover.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> "Bailando en la Azotea" as deep house. We sent no title, so ACE Music called it "Reference 1": ``` mode: remix · coverStrength 40 · remixStrength 50 · deep house remix, four-on-the-floor kick, plucky chords, rolling bassline, filtered vocal chops ``` ACE-Step v1.5 XL, no credits — "Reference 1" · 2:32 · generated in 31 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "mode": "remix", "model": "ace-step-1.5-xl", "references": ["user:12345-example@example.com-song:so_9d3b7e2c1a6f4085b8e4d1c6"], "style": "deep house remix, four-on-the-floor kick, plucky chords, rolling bassline, filtered vocal chops", "coverStrength": 40, "remixStrength": 50, "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-bailando-en-la-azotea-house-remix.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> "Paper Lanterns" with new words for seconds 30 to 50, the rest kept: ``` mode: edit · start 30 · end 50 Lyrics: We wrote our names on paper lanterns / Down by the harbor in the snow / You said the stars would keep the answer / If we were brave enough to go ``` ACE-Step v1.5 XL, no credits — "Reference 1" · 3:29 · generated in 41 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "mode": "edit", "model": "ace-step-1.5-xl", "references": ["user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7"], "start": 30, "end": 50, "style": "cinematic indie pop ballad, felt piano, swelling strings, intimate female vocal", "lyrics": "We wrote our names on paper lanterns\nDown by the harbor in the snow\nYou said the stars would keep the answer\nIf we were brave enough to go", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-step-1-5-xl-paper-lanterns-edit-seconds-30-50.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### Mashups "Paper Lanterns" and "Let the 44 Roll By": ``` upbeat neo-soul pop mashup, punchy live drums, warm Rhodes and strings, female lead with a gospel-tinged choir on the chorus · audioInfluence 60 ``` ACE Music v1.1 Preview — "Lanterns at the Bus Stop" · 3:58 · generated in 83 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash # our script read each song's score first (the API now does this by itself for ACE Music v1 songs) curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "mode": "mashup", "model": "acemusic-v1.1", "references": ["user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7", "user:12345-example@example.com-song:so_7c1d9e3a5b2f4806a4e1c9d3"], "title": "Lanterns at the Bus Stop", "style": "upbeat neo-soul pop mashup, punchy live drums, warm Rhodes and strings, female lead with a gospel-tinged choir on the chorus", "audioInfluence": 60, "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-1-mashup-lanterns-at-the-bus-stop.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> "Haul for the Harbor Light" and "Bailando en la Azotea", asked on ACE Music v1: ``` festive celtic cumbia mashup, fiddle and accordion trading hooks, congas and bodhran, stomping kick, male lead with a big crowd chorus ``` ACE Music v1.1 Preview (asked: v1) — "Harbor Fiesta" · 2:38 · generated in 74 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash # our script read each song's score first (the API now does this by itself for ACE Music v1 songs) curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "mode": "mashup", "model": "acemusic-v1", "references": ["user:12345-example@example.com-song:so_2a8f6c1e9d4b47f3b0c5e8a2", "user:12345-example@example.com-song:so_9d3b7e2c1a6f4085b8e4d1c6"], "title": "Harbor Fiesta", "style": "festive celtic cumbia mashup, fiddle and accordion trading hooks, congas and bodhran, stomping kick, male lead with a big crowd chorus", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-1-mashup-harbor-fiesta-asked-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Three songs at once: "Paper Lanterns", "Bailando en la Azotea" and "Let the 44 Roll By": ``` warm late-night soul-pop medley, Rhodes and strings, light latin percussion, female lead with a male answer on the last chorus ``` ACE Music v1.1 Preview — "Three Songs, One Night" · 3:32 · generated in 43 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash # our script read each song's score first (the API now does this by itself for ACE Music v1 songs) curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "mode": "mashup", "model": "acemusic-v1.1", "references": ["user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7", "user:12345-example@example.com-song:so_9d3b7e2c1a6f4085b8e4d1c6", "user:12345-example@example.com-song:so_7c1d9e3a5b2f4806a4e1c9d3"], "title": "Three Songs, One Night", "style": "warm late-night soul-pop medley, Rhodes and strings, light latin percussion, female lead with a male answer on the last chorus", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-1-mashup-three-songs-one-night.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### Your audio and pictures The "Harbour Jig" above, uploaded as an MP3 and used as the reference of a prompt. ACE Music ran it on v1.1 to keep the tune: ``` A rowdy pub singalong with a big shouted chorus about the last ferry home, built on the tune of this recording ``` ACE Music v1.1 Preview (asked: v1) — "Last Ferry Home" · 1:36 · generated in 52 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/files?title=Harbour%20Jig%20demo' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: audio/mpeg' \ --data-binary @harbour-jig-demo.mp3 curl -X POST 'https://api.useapi.net/v1/acemusic/music' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "A rowdy pub singalong with a big shouted chorus about the last ferry home, built on the tune of this recording", "model": "acemusic-v1", "references": ["user:12345-example@example.com-song:so_5f1a3c8e7b2d49a6c3e0f7b9"], "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-1-last-ferry-home-from-uploaded-jig.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### Stems of "Paper Lanterns" The vocal and the instrumental from `mode: "vocals"` (5 credits), then the drums and the strings of the 9 stems from `mode: "all"` (60 credits). <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl -X POST 'https://api.useapi.net/v1/acemusic/music/stems' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "songId": "user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7", "mode": "vocals", "async": true }' curl -X POST 'https://api.useapi.net/v1/acemusic/music/stems' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ -d '{ "songId": "user:12345-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7", "mode": "all", "async": true }' ``` </details> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-paper-lanterns-stem-vocal.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-paper-lanterns-stem-instrumental.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-paper-lanterns-stem-drums.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> <audio controls class="audio-player" preload="metadata"> <source src="https://media.useapi.net/acemusic/2026-11-14-article/ace-music-v1-paper-lanterns-stem-strings.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ### Questions **Is there an ACE Music API?** Through useapi.net, yes: the [ACE Music API](/docs/api-acemusic-v1) runs ACE Music v1, ACE Music v1.1 Preview and ACE-Step v1.5 XL over REST on your ACE Music account, with covers, mashups, stems and MIDI. **Is there a free ACE-Step API?** Through useapi.net, yes: an ACE-Step v1.5 XL song uses no credits on any ACE Music plan, the Free plan included, with tempo, key, time signature and length settings, remixes and edits. The third-party acestep.io offers its ACE-Step API only on its $49 a month Studio plan, about $0.14 a song (as of November 2026). **How much does an ACE Music v1 song cost through the API?** Through useapi.net, an ACE Music v1 song costs 2 credits of your ACE Music plan: $0.013 on Artist billed yearly and $0.023 on Artist monthly, with nothing added per song. See [Pricing](#pricing). **Is there an ACE Music MCP server?** Through useapi.net, yes, and it does more than ACE Music's own server at `acemusic.ai/mcp`: the hosted [ACE Music MCP server](/docs/api-acemusic-v1/mcp) adds the free ACE-Step v1.5 XL model, MP3 downloads on the Free plan, stems, one-call covers, remixes, edits and mashups, MusicXML, and several accounts behind one API token. ACE Music's own server makes v1 and v1.1 songs from lyrics your assistant writes, and every download needs a paid plan. See the [comparison](#useapinet-vs-ace-musics-own-mcp-server). ### Conclusion One POST makes two songs on the model that tops the vocal leaderboard, ACE-Step songs cost nothing, and every song can go on to a cover, a mashup, stems or a MIDI file in the next call. Clone the [`acemusic-api` repo](https://github.com/useapi/acemusic-api), run `songs-from-prompt/` with `--only 3` on a Free account, and see [POST /music](/docs/api-acemusic-v1/post-acemusic-music) for every option. Visit our <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> or <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> for any support questions and concerns. === URL: https://useapi.net/docs/articles/ai-music-api-comparison === Document URL: https://useapi.net/docs/articles/ai-music-api-comparison --- layout: default title: "AI Music APIs Compared: Mureka vs MiniMax vs ElevenLabs vs Lyria 3 Pro" description: "Five AI music models tackle the same prompts — Mureka O2 and V9, MiniMax music-2.6, ElevenLabs music-v1, and Lyria 3 Pro. 30 tracks with prices, speeds, and findings." keywords: [AI music generation API, Mureka API, MiniMax music API, ElevenLabs music API, Lyria 3 Pro API, music model comparison, Suno alternative, text to music, custom lyrics API] image: /assets/images/articles/ai-music-api-comparison.jpg parent: Articles nav_exclude: true date: 2026-07-17 repo: https://github.com/useapi/ai-music-comparison last_modified: 2026-11-14 nav_order: 95 --- ## AI Music APIs Compared: Mureka vs MiniMax vs ElevenLabs vs Lyria 3 Pro 12 min read • July 17, 2026 (November 14, 2026) ## Table of contents ### Introduction We gave the same briefs to five AI music models — Mureka O2, Mureka V9, MiniMax music-2.6, ElevenLabs music-v1, and Google's Lyria 3 Pro — through [useapi.net](/docs/subscription), and published every result: 30 full tracks below, with real prices, generation times, and the quirks we hit along the way. Three test formats, two rounds each: pure instrumentals, vocals where the model writes its own lyrics, and vocals singing lyrics we wrote. Every model in a round gets the identical brief, so what you hear is the model, not the prompt. The five models arrive through three services — [Mureka](/docs/api-mureka-v1) directly (the strongest Suno and Udio alternative in the group), MiniMax and ElevenLabs through [PixVerse](/docs/api-pixverse-v2/post-pixverse-music-create), and Lyria 3 Pro through [Flow Music](/docs/api-flowmusic-v1). One useapi.net token drives all three. If you want the copy-paste quick starts instead of a listening test, see the [Mureka tutorial](/docs/articles/mureka-bash) and the [Flow Music tutorial](/docs/articles/flowmusic-bash). Short on time? The whole test is also a <a href="https://youtu.be/9-tVK4SYuR4"><img style="height:1em;vertical-align: middle;" src="/assets/images/youtube.svg" alt=""> 15-minute YouTube video</a> — a skimmable cut with every track's best 30 seconds back to back, loudness-matched, with the prompt, model, cost, and generation time on screen. The on-screen prices are from the July recording, and the current ones are [below](#the-lineup-and-what-a-track-costs). The full-length tracks and the exact API call behind each one live on this page. Newer models are out. Same briefs, run again on TemPolor v4.8, MiniMax Music-3.0, Lyria 3.5 and Mureka V9.5 — [hear them here](/docs/articles/ai-music-flagships-compared). On November 14, 2026 we added ACE Music v1 there, #1 on [Artificial Analysis' vocal music leaderboard](https://artificialanalysis.ai/music/leaderboard/vocals) ahead of Suno v6, on the same six briefs: [big-band noir](/docs/articles/ai-music-flagships-compared#round-1-big-band-noir), [liquid drum and bass](/docs/articles/ai-music-flagships-compared#round-2-liquid-drum-and-bass), [pop duet](/docs/articles/ai-music-flagships-compared#round-3-pop-duet), [Spanish flamenco-pop](/docs/articles/ai-music-flagships-compared#round-4-spanish-flamenco-pop), [deep house](/docs/articles/ai-music-flagships-compared#round-5-deep-house) and [jazzy house duet](/docs/articles/ai-music-flagships-compared#round-6-jazzy-house-duet). ### The lineup and what a track costs What one song costs on each maker's official API ([Mureka](https://platform.mureka.ai/pricing) and Google's [Gemini API](https://ai.google.dev/gemini-api/docs/pricing)) and on each website subscription (October 2026). Each subscription comes with a monthly number of credits, and each song uses a set number of them, so a song costs its share of the subscription. | Model | Official API | Website monthly subscription | Price per song | |---|---|---|---| | [Mureka V9](/docs/api-mureka-v1) | 4.5¢ (prepaid from $1,000) | Mureka Pro $10 (5,000 cr/mo) | 2.4¢ / 12 cr (416 songs/mo) | | [Mureka V9](/docs/api-mureka-v1) | 4.5¢ (prepaid from $1,000) | Mureka Premier $30 (20,000 cr/mo) | 1.8¢ / 12 cr (1,666 songs/mo) | | [Mureka O2](/docs/api-mureka-v1) | 4.5¢ (prepaid from $1,000) | Mureka Premier $30 (20,000 cr/mo) | 3¢ / 20 cr (1,000 songs/mo) | | [Lyria 3 Pro](/docs/api-flowmusic-v1) | 8¢ (per song) | Flow Music Starter $8 (3,000 cr/mo) | 1.3¢ / 5 cr (600 songs/mo) | | [Lyria 3 Pro](/docs/api-flowmusic-v1) | 8¢ (per song) | Flow Music Member $64 (30,000 cr/mo) | 1.1¢ / 5 cr (6,000 songs/mo) | Google AI subscriptions include a Flow Music plan, with credits separate from the Google AI credits: Starter on [Google AI Plus](https://support.google.com/googleone/answer/16882689), Plus on [Google AI Pro](https://support.google.com/googleone/answer/14534406) and Member on [Google AI Ultra](https://support.google.com/googleone/answer/16286513). MiniMax music-2.6 and ElevenLabs music-v1 ran on PixVerse credits through the [PixVerse API](/docs/api-pixverse-v2/post-pixverse-music-create) in this test. MiniMax music now also has its own [endpoint](/docs/api-minimax-v1/post-minimax-music-create) on a MiniMax Audio website subscription, priced in the [newer comparison](/docs/articles/ai-music-flagships-compared#the-lineup-and-what-it-costs). One playback note before you listen: Flow Music offers a WAV alongside its m4a, so the Lyria players below are WAVs — the rest are the mp3s their APIs return. ### How we tested Every prompt asked for "around 60 seconds" (spoiler: only one model listened — see [what we learned](#what-we-learned)). Generation times are wall-clock through the API, polled at 15-second intervals, so treat them as ballpark. Where a model titles its own output we kept the title. Tracks are complete and unedited. ## Part 1 — Instrumentals ### Round 1: big-band noir A retro secret-agent groove — walking bass, stabbing brass, surf-twang guitar. Rhythm feel and section writing are hard to fake: ``` Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production. ``` Mureka O2 — “The Dead Drop” · 3:19 · generated in 119 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-instrumental' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="O2"' \ --form 'prompt="Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-07-17-ai-music-api-comparison/c-bigband-noir-mureka-o2-2.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9 — “Dead End Alley” · 3:28 · generated in 85 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-instrumental' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9"' \ --form 'prompt="Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-07-17-ai-music-api-comparison/c-bigband-noir-mureka-v9-1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax music-2.6 · 2:11 · generated in 99 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v2/pixverse/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-2.6"' \ --form 'instrumental="true"' \ --form 'prompt="Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-07-17-ai-music-api-comparison/c-bigband-noir-pixverse-music-2.6.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ElevenLabs music-v1 · 1:00 · generated in 16 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v2/pixverse/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-v1"' \ --form 'instrumental="true"' \ --form 'prompt="Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-07-17-ai-music-api-comparison/c-bigband-noir-pixverse-music-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3 Pro — “The Shadow Trail” · 2:59 · generated in 34 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'instrumental="true"' \ --form 'prompt="Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-07-17-ai-music-api-comparison/c-bigband-noir-flowmusic-lyria-3-pro-2.wav" type="audio/wav">Your browser does not support the audio element. </audio> Note the lengths: same brief, same "around 60 seconds" request — ElevenLabs delivered exactly 1:00, everyone else played on. ### Round 2: liquid drum and bass Maximum contrast with round 1 — a steady 174 BPM groove exposes rhythm programming and texture instead of dynamics: ``` Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production. ``` Mureka O2 — “Silver Lining” · 3:19 · generated in 86 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-instrumental' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="O2"' \ --form 'prompt="Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-07-17-ai-music-api-comparison/b-liquid-dnb-mureka-o2-2.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9 — “Silken Motif” · 2:31 · generated in 67 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-instrumental' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9"' \ --form 'prompt="Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-07-17-ai-music-api-comparison/b-liquid-dnb-mureka-v9-2.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax music-2.6 · 2:22 · generated in 119 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v2/pixverse/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-2.6"' \ --form 'instrumental="true"' \ --form 'prompt="Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-07-17-ai-music-api-comparison/b-liquid-dnb-pixverse-music-2.6.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ElevenLabs music-v1 · 1:00 · generated in 16 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v2/pixverse/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-v1"' \ --form 'instrumental="true"' \ --form 'prompt="Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-07-17-ai-music-api-comparison/b-liquid-dnb-pixverse-music-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3 Pro — “Silky Liquid Flow” · 2:54 · generated in 50 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'instrumental="true"' \ --form 'prompt="Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-07-17-ai-music-api-comparison/b-liquid-dnb-flowmusic-lyria-3-pro-2.wav" type="audio/wav">Your browser does not support the audio element. </audio> ## Part 2 — Vocals, model writes the lyrics ### Round 3: pop duet One sentence of direction, and a deliberate capability probe — a duet only works if the model can stage two voices. That is the thing to listen for in this round, and it is the clearest differentiator of the six. ``` A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus. ``` Mureka O2 — “Don’t Hit Send” · 3:18 · generated in 80 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="O2"' \ --form 'prompt="A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-07-17-ai-music-api-comparison/c-pop-duet-mureka-o2-2.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9 — “Midnight Dance” · 2:53 · generated in 62 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9"' \ --form 'prompt="A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-07-17-ai-music-api-comparison/c-pop-duet-mureka-v9-2.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax music-2.6 · 2:40 · generated in 97 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v2/pixverse/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-2.6"' \ --form 'prompt="A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-07-17-ai-music-api-comparison/c-pop-duet-pixverse-music-2.6.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ElevenLabs music-v1 · 1:00 · generated in 16 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v2/pixverse/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-v1"' \ --form 'prompt="A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-07-17-ai-music-api-comparison/c-pop-duet-pixverse-music-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3 Pro — “Don’t Say Goodnight” · 2:58 · generated in 79 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'prompt="A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-07-17-ai-music-api-comparison/c-pop-duet-flowmusic-lyria-3-pro-1.wav" type="audio/wav">Your browser does not support the audio element. </audio> ### Round 4: Spanish flamenco-pop The language probe — the prompt is English, the song should not be: ``` A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals. ``` Mureka O2 — “El llanto del sol” · 3:59 · generated in 79 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="O2"' \ --form 'prompt="A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-07-17-ai-music-api-comparison/d-spanish-flamenco-mureka-o2-2.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9 — “Lluvia de Verano” · 2:32 · generated in 63 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9"' \ --form 'prompt="A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-07-17-ai-music-api-comparison/d-spanish-flamenco-mureka-v9-1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax music-2.6 · 2:57 · generated in 113 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v2/pixverse/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-2.6"' \ --form 'prompt="A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-07-17-ai-music-api-comparison/d-spanish-flamenco-pixverse-music-2.6.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ElevenLabs music-v1 · 1:00 · generated in 17 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v2/pixverse/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-v1"' \ --form 'prompt="A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-07-17-ai-music-api-comparison/d-spanish-flamenco-pixverse-music-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3 Pro — “Tierra Mojada” · 2:34 · generated in 64 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'prompt="A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-07-17-ai-music-api-comparison/d-spanish-flamenco-flowmusic-lyria-3-pro-2.wav" type="audio/wav">Your browser does not support the audio element. </audio> All five accepted the brief and every model sang in Spanish. Lyria even wrote a full Spanish lyric sheet ("Cae el peso del cielo gris / Sobre el polvo de este jardín…") and titled the track accordingly, as did both Murekas. ## Part 3 — Vocals, our lyrics and an elaborate style brief For the final format each model received the same original lyrics plus a detailed production brief. Mureka takes these through [music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced) (`lyrics` + a comma-separated style `desc` + `vocal_gender`), PixVerse and Flow Music take a `lyrics` field next to the style prompt. ### Round 5: deep house ``` [Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go) ``` ``` Deep house at 121 BPM. Rolling sub-bass groove, shuffled hi-hats, warm Rhodes chord stabs, subtle chopped vocal echoes, smoky intimate female lead vocal, understated hypnotic late-night club production. ``` Mureka O2 — “Low Light” · 3:13 · generated in 60 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-advanced' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="O2"' \ --form 'lyrics="[Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go)"' \ --form 'desc="deep house, late night, smoky, hypnotic, groovy, 121 bpm, female vocals, warm, understated club production"' \ --form 'vocal_gender="female"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-07-17-ai-music-api-comparison/f-low-light-mureka-o2-2.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9 — “Low Light” · 2:39 · generated in 57 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-advanced' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9"' \ --form 'lyrics="[Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go)"' \ --form 'desc="deep house, late night, smoky, hypnotic, groovy, 121 bpm, female vocals, warm, understated club production"' \ --form 'vocal_gender="female"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-07-17-ai-music-api-comparison/f-low-light-mureka-v9-2.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax music-2.6 · 1:06 · generated in 59 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v2/pixverse/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-2.6"' \ --form 'prompt="Deep house at 121 BPM. Rolling sub-bass groove, shuffled hi-hats, warm Rhodes chord stabs, subtle chopped vocal echoes, smoky intimate female lead vocal, understated hypnotic late-night club production."' \ --form 'lyrics="[Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go)"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-07-17-ai-music-api-comparison/f-low-light-pixverse-music-2.6.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ElevenLabs music-v1 · 0:40 · generated in 29 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v2/pixverse/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-v1"' \ --form 'prompt="Deep house at 121 BPM. Rolling sub-bass groove, shuffled hi-hats, warm Rhodes chord stabs, subtle chopped vocal echoes, smoky intimate female lead vocal, understated hypnotic late-night club production."' \ --form 'lyrics="[Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go)"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-07-17-ai-music-api-comparison/f-low-light-pixverse-music-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3 Pro — “Low Light (Take 2)” · 2:32 · generated in 44 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'prompt="Deep house at 121 BPM. Rolling sub-bass groove, shuffled hi-hats, warm Rhodes chord stabs, subtle chopped vocal echoes, smoky intimate female lead vocal, understated hypnotic late-night club production."' \ --form 'lyrics="[Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go)"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-07-17-ai-music-api-comparison/f-low-light-flowmusic-lyria-3-pro-2.wav" type="audio/wav">Your browser does not support the audio element. </audio> ### Round 6: jazzy house duet The hardest brief of the set — a two-voice arrangement with live-jazz layers over a house groove, voice roles tagged in the lyrics. The tags are a hint, not an API parameter, so listen for who actually trades verses between a male and a female voice and who flattens it into one singer: ``` [Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound ``` ``` Jazzy deep house duet at 120 BPM. Rolling deep-house groove with swung hi-hats, walking upright-bass motif over the sub, smoky muted trumpet and tenor-sax licks answering the vocals, extended jazz piano chords, a male and a female lead trading verses and joining in harmony on the chorus, small backing ensemble echoing the hook, warm vinyl texture, sophisticated late-night club production. ``` Mureka O2 — “Blue Hour” · 2:49 · generated in 59 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-advanced' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="O2"' \ --form 'lyrics="[Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound"' \ --form 'desc="jazzy deep house, jazz house, duet, male and female vocals, group backing vocals, muted trumpet, saxophone, upright bass, swung, 120 bpm, late night, warm sophisticated production"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-07-17-ai-music-api-comparison/g-blue-hour-mureka-o2-2.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9 — “Blue Hour” · 2:27 · generated in 72 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-advanced' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9"' \ --form 'lyrics="[Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound"' \ --form 'desc="jazzy deep house, jazz house, duet, male and female vocals, group backing vocals, muted trumpet, saxophone, upright bass, swung, 120 bpm, late night, warm sophisticated production"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-07-17-ai-music-api-comparison/g-blue-hour-mureka-v9-2.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax music-2.6 · 1:35 · generated in 62 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v2/pixverse/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-2.6"' \ --form 'prompt="Jazzy deep house duet at 120 BPM. Rolling deep-house groove with swung hi-hats, walking upright-bass motif over the sub, smoky muted trumpet and tenor-sax licks answering the vocals, extended jazz piano chords, a male and a female lead trading verses and joining in harmony on the chorus, small backing ensemble echoing the hook, warm vinyl texture, sophisticated late-night club production."' \ --form 'lyrics="[Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-07-17-ai-music-api-comparison/g-blue-hour-pixverse-music-2.6.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ElevenLabs music-v1 · 1:12 · generated in 32 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v2/pixverse/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-v1"' \ --form 'prompt="Jazzy deep house duet at 120 BPM. Rolling deep-house groove with swung hi-hats, walking upright-bass motif over the sub, smoky muted trumpet and tenor-sax licks answering the vocals, extended jazz piano chords, a male and a female lead trading verses and joining in harmony on the chorus, small backing ensemble echoing the hook, warm vinyl texture, sophisticated late-night club production."' \ --form 'lyrics="[Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-07-17-ai-music-api-comparison/g-blue-hour-pixverse-music-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3 Pro — “Blue Hour Duet (Retry)” · 3:03 · generated in 60 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'prompt="Jazzy deep house duet at 120 BPM. Rolling deep-house groove with swung hi-hats, walking upright-bass motif over the sub, smoky muted trumpet and tenor-sax licks answering the vocals, extended jazz piano chords, a male and a female lead trading verses and joining in harmony on the chorus, small backing ensemble echoing the hook, warm vinyl texture, sophisticated late-night club production."' \ --form 'lyrics="[Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-07-17-ai-music-api-comparison/g-blue-hour-flowmusic-lyria-3-pro.wav" type="audio/wav">Your browser does not support the audio element. </audio> ## What we learned ### Nobody has a duration parameter, and only one model listens to the prompt None of the five APIs exposes a track-length parameter. Every brief above asked for "around 60 seconds" — here is what that request was worth across all our runs, including test takes not published here: | Model | Asked for ~60 s, got | Verdict | |-------|----------------------|---------| | ElevenLabs music-v1 | 1:00 on every prompt-only run | the only model that treats it as a spec | | Lyria 3 Pro | ~0:59 on 2 prompts, 2:30–3:03 on the rest | occasionally | | MiniMax music-2.6 | 1:20–2:57 | ignores it | | Mureka O2 / V9 | 2:30–4:00 | ignores it | The lever that actually works is lyric length. With our short one-verse-one-chorus lyrics in part 3, ElevenLabs came in at 0:40, MiniMax dropped to 1:06, and Mureka fell from its usual 3–4 minutes to as short as 0:50 in test takes. If you need a fixed-length cue, write fixed-length lyrics — or trim in post. ### ElevenLabs refuses named artists and works, the rest do not In side experiments we prompted "in the spirit of the James Bond GoldenEye title sequence" and, separately, "in the spirit of Pendulum and The Prodigy". ElevenLabs music-v1 failed both generations at the service level — evidently a copyrighted-reference filter that catches both named works and named artists. Mureka O2, Mureka V9, MiniMax music-2.6, and Lyria 3 Pro accepted and generated both times. Style-descriptive prompts (like round 1's unnamed secret-agent brief) sail through everywhere. ### Speed, titles, and what lands in your bucket ElevenLabs is in a different speed class — 16 to 32 seconds per track in our runs, wall-clock through the API. Lyria followed at 34–79 s, with Mureka V9 at 57–85 s and both Mureka O2 and MiniMax spanning 59–119 s. Mureka and Lyria name their own tracks — every title above is model-written, and in part 3 both pulled the name from our lyric hook, quirky suffixes included ("Take 2" and "Retry" on the Lyria tracks are Lyria's own). The PixVerse-routed models return untitled files. Mureka gives you two variants per generation at 320 kbps, PixVerse one track at 192 kbps, and Flow Music usually an A/B pair with a WAV download available. ## FAQ **Which AI music API is the cheapest?** Through useapi.net, Lyria 3 Pro on a Flow Music Member website subscription, at about 1.1¢ a song against 8¢ on Google's [Gemini API](https://ai.google.dev/gemini-api/docs/pricing). Mureka follows at 1.8¢ for a V9 song and 3¢ for O2 on Mureka Premier, with two variants per generation, against 4.5¢ on [Mureka's API](https://platform.mureka.ai/pricing), which starts with a $1,000 prepaid top-up (as of October 2026). See [the lineup](#the-lineup-and-what-a-track-costs). **Can I control how long the generated song is?** Through useapi.net, not with a parameter, because none of these five APIs has one. Asking for a length in the prompt only worked reliably on ElevenLabs, which delivered 1:00 on every prompt-only run. The dependable lever is lyric length: short lyrics produce short songs on every model that accepts custom lyrics. See [what we learned](#nobody-has-a-duration-parameter-and-only-one-model-listens-to-the-prompt). **Can I bring my own lyrics?** Through useapi.net, yes on all five models: Mureka through [music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced), MiniMax and ElevenLabs through the PixVerse `lyrics` field, and Lyria through the Flow Music `lyrics` field. Tag the structure with `[Verse]` and `[Chorus]`, and the same lyrics work unchanged on every model, as part 3 of this test shows. **Will these models imitate a named artist or song?** Through useapi.net, four of the five will. Mureka O2, Mureka V9, MiniMax music-2.6 and Lyria 3 Pro accepted prompts naming a work or an artist in our tests, while ElevenLabs music-v1 failed both such generations at its content filter. Describing a style without names works on all five, as the unnamed secret-agent brief in round 1 shows. --- Ready to run your own listening test? The whole experiment is one script — [github.com/useapi/ai-music-comparison](https://github.com/useapi/ai-music-comparison) sends any brief (the six above are included) to all five models and downloads every track. Then dig deeper with the [Mureka](/docs/articles/mureka-bash) and [Flow Music](/docs/articles/flowmusic-bash) tutorials, the [PixVerse music endpoint](/docs/api-pixverse-v2/post-pixverse-music-create), and a [useapi.net subscription](/docs/subscription) — one token, all five models. #### Cross posted Also published on [dev.to](https://dev.to/useapi/ai-music-apis-compared-mureka-vs-minimax-vs-elevenlabs-vs-lyria-3-pro-2kcn){:rel="nofollow"}, discussed on [Reddit](https://www.reddit.com/r/ThirdPartyAPI/comments/1uyndmo/ai_music_apis_compared_mureka_vs_minimax_vs/){:rel="nofollow"}, and on [YouTube](https://youtu.be/9-tVK4SYuR4) as a 15-minute listening cut. Newer models: [TemPolor, MiniMax, Lyria, Mureka and ACE Music on the same six briefs](/docs/articles/ai-music-flagships-compared). === URL: https://useapi.net/docs/articles/ai-music-flagships-compared-es === Document URL: https://useapi.net/docs/articles/ai-music-flagships-compared-es --- layout: default lang: es translation_key: ai-music-flagships title: "Cinco API de música con IA con las mismas seis consignas: ACE Music v1, TemPolor v4.8, MiniMax Music-3.0, Lyria 3.5 y Mureka V9.5" description: "Cinco modelos de música con IA, ACE Music v1, TemPolor v4.8 e i4, MiniMax Music-3.0, Lyria 3.5 de Google y Mureka V9.5, con las mismas seis consignas mediante las API de useapi.net: cada pista, la llamada exacta a la API que la generó, los tiempos de generación y lo que cuesta cada canción con una suscripción del sitio web frente a las API oficiales." keywords: [API de música con IA, API de TemPolor, API de TemPolor v4.8, API de MiniMax Music-3.0, API de Lyria 3.5, API de Mureka V9.5, API de ACE Music, API de ACE Music v1, comparación de API de música con IA, API de generación de música, API de texto a música, precios de API de música con IA, AI music API, TemPolor API, TemPolor v4.8, MiniMax Music-3.0 API, Lyria 3.5 API, Mureka V9.5 API, ACE Music API, ACE Music v1 API, AI music API comparison, music generation API, text to music API, AI music API pricing] image: /assets/images/articles/ai-music-flagships-compared.jpg video: name: "Cinco API de música con IA con las mismas seis consignas" description: "ACE Music v1, TemPolor v4.8 e i4, MiniMax Music-3.0, Google Lyria 3.5 y Mureka V9.5 con las mismas seis consignas: los 30 segundos más fuertes de cada pista, con el volumen igualado, y el prompt, el precio y el tiempo de generación en pantalla." embed: https://www.youtube.com/embed/MSUGckk4JqU thumbnail: https://i.ytimg.com/vi/MSUGckk4JqU/maxresdefault.jpg date: 2026-11-14 duration: PT15M width: 1920 height: 1080 parent: Articles nav_exclude: true date: 2026-08-19 last_modified: 2026-11-18 nav_order: 96 --- ## Cinco API de música con IA con las mismas seis consignas: ACE Music v1, TemPolor v4.8, MiniMax Music-3.0, Lyria 3.5 y Mureka V9.5 {: .no_toc #five-ai-music-apis-on-the-same-six-briefs-ace-music-v1-tempolor-v48-minimax-music-30-lyria-35-and-mureka-v95 } 13 min de lectura • 19 de agosto de 2026 (18 de noviembre de 2026) ## Índice {: .no_toc .text-delta #table-of-contents } ### Introducción TemPolor v4.8, MiniMax Music-3.0, Lyria 3.5 de Google y Mureka V9.5: cuatro modelos de música con IA, las mismas seis consignas, un solo token de API de [useapi.net](/docs/subscription). Las 24 pistas están abajo, completas y sin editar, cada una con la llamada a la API que la generó. Son las mismas consignas que usamos en julio, así que cada pista de aquí tiene una predecesora con la que compararla en [AI Music APIs Compared](/docs/articles/ai-music-api-comparison) (en inglés). El 14 de noviembre de 2026, tres meses después que los demás, ejecutamos las mismas seis consignas con ACE Music v1, que ocupa el primer puesto del [ranking de música vocal de Artificial Analysis](https://artificialanalysis.ai/music/leaderboard/vocals), por delante de Suno v6. Su canción cierra cada ronda de abajo, con lo que la página llega a 30 pistas. TemPolor, nuevo desde julio, cobra de forma distinta a todos los demás: un precio mensual fijo, sin cargo por canción. Lo que cuesta cada canción está [más abajo](#the-lineup-and-what-it-costs). Escucha primero y juzga los modelos por ti mismo. ¿Tienes poco tiempo? También hay un <a href="https://youtu.be/MSUGckk4JqU"><img style="height:1em;vertical-align: middle;" src="/assets/images/youtube.svg" alt=""> video de YouTube de 15 minutos</a>: los 30 segundos más fuertes de los cinco modelos en cada consigna, uno tras otro y con el volumen igualado, con el prompt, el precio y el tiempo de generación en pantalla (precios a noviembre de 2026). Las pistas completas y la llamada exacta a la API detrás de cada una están en esta página. La ronda anterior de esta prueba, con tres modelos, también está en YouTube: [AI Music APIs One Generation Later: MiniMax Music-3.0 vs Lyria 3.5 vs Mureka V9.5](https://www.youtube.com/watch?v=9AM5p-A9oFM). ### Qué cambió desde julio | Servicio | Julio | Ahora | Qué cambió | |---|---|---|---| | TemPolor | no participaba | v4.8 (canciones) + i4 (instrumentales) | nuevo en esta comparación, y dos modelos nuevos | | Mureka | V9 | V9.5 | nuevo modelo predeterminado | | Flow Music | Lyria 3 Pro | Lyria 3.5 | nuevo modelo insignia, pero 3 Pro sigue siendo el predeterminado de la API | | MiniMax | music-2.6 vía PixVerse | Music-3.0, nativo | modelo nuevo *y* endpoint nuevo | | ACE Music | no participaba | ACE Music v1 | se sumó el 14 de noviembre de 2026 | Dos de esos cambios son simples actualizaciones de versión. La fila de MiniMax no lo es: [la música de MiniMax ahora es un endpoint propio](/docs/api-minimax-v1/post-minimax-music-create), en lugar de algo a lo que llegas a través de [PixVerse](/docs/api-pixverse-v2/post-pixverse-music-create). Endpoint distinto, facturación distinta. TemPolor es la otra excepción. Es el único servicio de esta comparación que divide el trabajo entre dos endpoints con dos modelos distintos: [`POST music/song`](/docs/api-tempolor-v1/post-tempolor-music-song) ejecuta `v4.8` para todo lo que lleva voz, y [`POST music/instrumental`](/docs/api-tempolor-v1/post-tempolor-music-instrumental) ejecuta `i4` para todo lo que no. Los nombres de modelo anteriores siguen funcionando y se redirigen automáticamente a los nuevos, así que el código existente sigue funcionando, pero eso también significa que puedes estar usando los modelos nuevos sin darte cuenta, o no usarlos por no pasar ningún modelo. ### Los modelos y lo que cuestan Lo que cuesta una canción en la API oficial de cada creador ([TemPolor](https://platform.tempolor.com/docs/6665893m0), [MiniMax](https://platform.minimax.io/docs/pricing/overview#about-music-models), cerrada a nuevos usuarios desde el 20 de agosto de 2026, la [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) de Google y [Mureka](https://platform.mureka.ai/pricing)) y en la suscripción del sitio web con la que se ejecutó cada modelo en esta prueba (en dólares estadounidenses, a noviembre de 2026). Cada suscripción incluye un número mensual de créditos, y cada canción usa una cantidad fija de ellos, así que una canción cuesta su parte de la suscripción. | Modelo | API oficial | Suscripción mensual del sitio web | Precio por canción | |---|---|---|---| | [TemPolor v4.8 / i4](/docs/api-tempolor-v1) | $0,04 (por llamada, prepago desde $100) | TemPolor Ultra $29,99 | $0 / 0 cr (sin cargo por canción) | | [MiniMax Music-3.0](/docs/api-minimax-v1/post-minimax-music-create) | $0,15 (cerrada a nuevos usuarios desde el 20 de agosto de 2026) | MiniMax Audio Pro $99 (3.000.000 cr/mes) | $0,01 / 300 cr (10.000 canciones/mes) | | [Lyria 3.5](/docs/api-flowmusic-v1) | $0,08 (por canción) | Flow Music Member $64 (30.000 cr/mes) | $0,011 / 5 cr (6.000 canciones/mes) | | [Mureka V9.5](/docs/api-mureka-v1) | $0,15 (prepago desde $1.000) | Mureka Premier $30 (20.000 cr/mes) | $0,018 / 12 cr (1.666 canciones/mes) | | [ACE Music v1](/docs/api-acemusic-v1) | — | ACE Music Creator $9,90 (1.000 cr/mes) | $0,02 / 2 cr (500 canciones/mes) | - Cuando el modelo escribe la letra a partir de un prompt, como en las rondas 3 y 4, la API de Mureka cobra US$0,50 en lugar de US$0,15 y la de MiniMax agrega US$0,01, mientras que con useapi.net una canción cuesta lo mismo en ambos casos. - Los créditos de la API de TemPolor cuestan [US$0,01 cada uno en todos los tamaños de paquete](https://platform.tempolor.com/pricing), así que el volumen nunca baja su precio. Los paquetes más grandes compran concurrencia: cinco solicitudes a la vez con US$100, diez con US$500 y veinte con US$5.000, y el nivel no se acumula si compras el mismo paquete dos veces. TemPolor Ultra ejecuta diez generaciones a la vez. - El modelo que este artículo llama `v4.8` es `tempolor-latest` en la API de TemPolor. `i4` conserva su nombre. - Los planes más pequeños, como Mureka Pro y Flow Music Starter, cuestan un poco más por canción y aun así quedan muy por debajo de las API oficiales. - ACE Music devuelve dos canciones por solicitud y cobra 4 créditos por el par, es decir, 2 créditos por canción. En ACE Music Artist, a US$29 al mes o US$16,58 al mes con pago anual, una canción cuesta US$0,023 o unos US$0,013. - Las suscripciones de Google AI incluyen un plan de Flow Music, con créditos separados de los créditos de Google AI: Starter en [Google AI Plus](https://support.google.com/googleone/answer/16882689?hl=es), Plus en [Google AI Pro](https://support.google.com/googleone/answer/14534406?hl=es) y Member en [Google AI Ultra](https://support.google.com/googleone/answer/16286513?hl=es). useapi.net funciona con tu suscripción del sitio web de TemPolor, MiniMax Audio, Flow Music, Mureka o ACE Music y la expone como una API REST, sin recargo por canción. Un solo token de API funciona con los cinco servicios: sin un SDK por servicio, sin claves de API separadas, sin cinco facturaciones que conciliar. El mismo token llega a todos los demás servicios que admitimos: video, imagen, voz e intercambio de rostros. ### Cómo hicimos la prueba Las mismas seis consignas que en julio, copiadas del artículo publicado en lugar de volver a escribirlas: dos instrumentales, dos pistas con voz en las que el modelo escribe su propia letra, y dos en las que nosotros damos tanto la letra como una consigna de estilo elaborada. Todos los modelos de una ronda reciben exactamente el mismo texto, así que lo que escuchas es el modelo. Los cuerpos de las solicitudes de TemPolor se copiaron byte por byte de los de MiniMax, que usan los mismos campos `prompt` y `lyrics`. ACE Music v1 recibió el mismo texto. Su API acepta un `prompt`, a partir del cual escribe su propio estilo y su propia letra, o un `style` con tus `lyrics` o con `instrumental`, y rechaza los dos juntos. Así que las rondas 3 y 4 se enviaron como `prompt`, las dos consignas instrumentales como `style` con `instrumental: true`, y las rondas 5 y 6 como `style` más `lyrics`, sin título, `duration` ni `bpm`. Los tiempos de generación son tiempo real medido a través de la API, con consultas cada 15 segundos, así que tómalos como una referencia aproximada y no como un benchmark. Por mediana de las seis rondas, Lyria 3.5 fue el más rápido con 58,5 s, seguido de ACE Music v1 con 62 s, TemPolor con 69,5 s, Mureka con 86,5 s y MiniMax con 158,5 s. Cuando un modelo pone título a su resultado, conservamos ese título, con su ortografía y sus espacios sobrantes. Las pistas están completas y sin editar, tal como las devolvió cada API: Mureka, dos canciones por generación en MP3 de 192 kbps; MiniMax, una a 256 kbps; TemPolor, una a 48 kHz y entre 230 y 320 kbps aproximadamente; ACE Music, dos canciones por solicitud en MP3 de 192 kbps y 48 kHz; y Flow Music, un par A/B en WAV de 48 kHz, convertido a MP3 de 320 kbps solo para que un navegador pueda reproducirlo. Los WAV originales de Flow vienen directamente de la API. La pista de ACE Music en cada ronda es la primera de sus dos canciones, sin elegir. Algo que debes tener en cuenta si desarrollas con TemPolor: un trabajo de canción informa `status_final: true` y `COMPLETED` unos segundos *antes* de que su archivo se pueda descargar, y [`GET music/download/job_id`](/docs/api-tempolor-v1/get-tempolor-music-download-job_id) responde `404` en ese intervalo. Tres de nuestras cuatro rondas con voz se toparon con eso en el primer intento. Trata ese `404` como "todavía no" y sigue consultando, en lugar de tomarlo como un fallo. ## Parte 1: instrumentales ### Ronda 1: noir de big band ``` Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production. ``` TemPolor i4 — "Generic Rhythm Tune" · 3:09 · generada en 103 s <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/instrumental' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model_instrumental="i4"' \ --form 'prompt="Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/01-bigband-noir-tempolor-i4.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Brass Knuckle Boulevard" · 3:19 · generada en 86 s <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-instrumental' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9.5"' \ --form 'prompt="Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/01-bigband-noir-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music-3.0 — "Midnight Operative" · 2:51 · generada en 182 s <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-3.0"' \ --form 'prompt="Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production."' \ --form 'instrumental="true"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/01-bigband-noir-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Double Cross" · 2:52 · generada en 47 s <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'instrumental="true"' \ --form 'prompt="Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/01-bigband-noir-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ACE Music v1 — "Big-band noir action theme" · 2:08 · generada en 52 s <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/acemusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="acemusic-v1"' \ --form 'style="Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production."' \ --form 'instrumental="true"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/01-bigband-noir-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Las versiones de julio de esta consigna están en [la página anterior](/docs/articles/ai-music-api-comparison#round-1-big-band-noir) (en inglés), si quieres escucharlas una tras otra. ### Ronda 2: liquid drum and bass ``` Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production. ``` TemPolor i4 — " Generic Rhythm Beat" · 3:30 · generada en 69 s <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/instrumental' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model_instrumental="i4"' \ --form 'prompt="Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/02-liquid-dnb-tempolor-i4.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Piano Afterglow" · 3:22 · generada en 85 s <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-instrumental' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9.5"' \ --form 'prompt="Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production."' \ --form 'title="Take B - Liquid DnB"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/02-liquid-dnb-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music-3.0 — "Midnight Flow" · 3:45 · generada en 227 s <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-3.0"' \ --form 'prompt="Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production."' \ --form 'instrumental="true"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/02-liquid-dnb-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Silken Tides" · 1:06 · generada en 59 s <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'prompt="Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production."' \ --form 'instrumental="true"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/02-liquid-dnb-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ACE Music v1 — "Liquid drum and bass instrumental" · 3:10 · generada en 89 s <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/acemusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="acemusic-v1"' \ --form 'style="Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production."' \ --form 'instrumental="true"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/02-liquid-dnb-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Ninguna de las cuatro API originales tiene un parámetro de duración: todas las consignas pedían "around 60 seconds" en el texto. ACE Music tiene uno, `duration` (de 30 a 600 segundos), que omitimos para que leyera las mismas palabras. Lyria fue la única de las cuatro que alguna vez siguió la indicación, y solo aquí. Lyria 3 Pro respondió a este mismo prompt en julio con 2:46. En las dos rondas de prompt de abajo, donde ACE Music v1 escribe su propio estilo, llegó a 0:41 y 1:22, lo más cercano a un minuto en esas rondas. El endpoint instrumental de TemPolor tampoco nombra realmente su resultado. Devolvió "Generic Rhythm Tune" y "Generic Rhythm Beat" para estas dos consignas: marcadores de posición más que títulos, y ni siquiera prolijos, porque el primero llega con un espacio doble en medio y el segundo con un espacio al inicio. Su endpoint de canciones, en las cuatro rondas siguientes, sí pone títulos de verdad. ACE Music, sin un título enviado, nombró los dos instrumentales con las primeras palabras de la consigna, y sus canciones de las rondas 5 y 6 con las primeras palabras de nuestra letra. Si archivas las pistas por título, genera tú el nombre de los instrumentales y recorta lo que llegue, o envía a ACE Music un `title`. ## Parte 2: con voz, el modelo escribe la letra ### Ronda 3: dueto pop Una sola oración de indicaciones, y una prueba deliberada de capacidad: un dueto solo funciona si el modelo puede poner en escena dos voces. ``` A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus. ``` TemPolor v4.8 — "Text Me" · 1:51 · generada en 70 s <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/song' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model_song="v4.8"' \ --form 'prompt="A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-tempolor-v4.8.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Escucha el primer verso. TemPolor escribió su propia letra para esta consigna, y la escribió marcando al cantante dentro de cada línea: ``` [Verse] [Male] You sent "you up?" at 1:09 [Female] You said "just one more," then took your time [Male] I saw your typing, then it slipped away [Female] I dropped my phone and missed your "hey" ``` Su cantante elimina `[Verse]` y `[Chorus]` como estructura, pero un `[Male]` dentro de la línea no es una etiqueta que reconozca, así que canta las palabras "male" y "female" como parte del verso. Las dos mitades del mismo modelo no se ponen de acuerdo sobre su propio formato. MiniMax se topó exactamente con el mismo problema en esta consigna y salió bien librado al escribir `(Male)` y `(Female)` entre paréntesis, que su cantante sí omite. La lección va más allá de este modelo. Las etiquetas de rol dentro de `lyrics` no son una función portátil entre API, así que si das tú la letra y quieres dos voces, comprueba qué hace cada modelo con tu estilo de corchetes antes de confiar en él, o deja fuera las etiquetas y describe el dueto en el prompt de estilo. Mureka V9.5 — "Are You Still Awake?" · 3:05 · generada en 88 s <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9.5"' \ --form 'prompt="A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music-3.0 — "Three Little Dots" · 2:31 · generada en 146 s <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-3.0"' \ --form 'prompt="A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax la tituló como el indicador de "escribiendo...", y sus etiquetas `(Male)` / `(Female)` quedaron fuera de la voz. Lyria 3.5 — "You Go First" · 1:59 · generada en 74 s <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'prompt="A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria escribió su propio juego de pregunta y respuesta a dos voces, con las líneas de respuesta entre paréntesis. ACE Music v1 — "Three Dot Bubbles" · 0:41 · generada en 54 s <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/acemusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="acemusic-v1"' \ --form 'prompt="A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ACE Music también la tituló como el indicador de "escribiendo...", y escribió su dueto con `(Male)`, `(Female)` y `(Both)` entre paréntesis, como hizo MiniMax. ### Ronda 4: flamenco pop en español La prueba de idioma: el prompt está en inglés, pero la canción no debería estarlo: ``` A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals. ``` TemPolor v4.8 — "Lluvia" · 2:58 · generada en 102 s <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/song' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model_song="v4.8"' \ --form 'prompt="A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/04-spanish-flamenco-tempolor-v4.8.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Agua de Julio" · 3:32 · generada en 87 s <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9.5"' \ --form 'prompt="A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/04-spanish-flamenco-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music-3.0 — "Tacones de Lluvia" · 3:07 · generada en 171 s <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-3.0"' \ --form 'prompt="A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/04-spanish-flamenco-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Lluvia de Verano" · 2:33 · generada en 73 s <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'prompt="A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/04-spanish-flamenco-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ACE Music v1 — "Fuego en la Tormenta" · 1:22 · generada en 70 s <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/acemusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="acemusic-v1"' \ --form 'prompt="A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/04-spanish-flamenco-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Los cinco escribieron la letra en español a partir de un prompt en inglés, y los cinco titularon la pista en español sin que se les pidiera. El v4.8 de TemPolor está documentado con [más de 30 idiomas](/docs/api-tempolor-v1). Una sola consigna en español no pone a prueba treinta de ellos, pero respondió a esta en el idioma correcto y la tituló "Lluvia" por su cuenta. ## Parte 3: con voz, nuestra letra y una consigna de estilo elaborada En el último formato, cada modelo recibe la misma letra original más una consigna de producción detallada. Mureka las recibe a través de [music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced) (`lyrics` + un `desc` de estilo separado por comas + `vocal_gender`), mientras que MiniMax, Flow Music y TemPolor aceptan un campo `lyrics` junto al prompt de estilo, así que el mismo cuerpo funciona sin cambios en tres de los cuatro. ACE Music recibe los mismos dos textos como `style` y `lyrics`. ### Ronda 5: deep house ``` [Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go) ``` ``` Deep house at 121 BPM. Rolling sub-bass groove, shuffled hi-hats, warm Rhodes chord stabs, subtle chopped vocal echoes, smoky intimate female lead vocal, understated hypnotic late-night club production. ``` TemPolor v4.8 — "Low Light" · 1:28 · generada en 51 s <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/song' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model_song="v4.8"' \ --form 'prompt="Deep house at 121 BPM. Rolling sub-bass groove, shuffled hi-hats, warm Rhodes chord stabs, subtle chopped vocal echoes, smoky intimate female lead vocal, understated hypnotic late-night club production."' \ --form 'lyrics="[Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go)"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-tempolor-v4.8.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Low Light" · 3:09 · generada en 101 s <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-advanced' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9.5"' \ --form 'lyrics="[Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go)"' \ --form 'desc="deep house, late night, smoky, hypnotic, groovy, 121 bpm, female vocals, warm, understated club production"' \ --form 'vocal_gender="female"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music-3.0 — "Low Light" · 2:47 · generada en 135 s <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-3.0"' \ --form 'prompt="Deep house at 121 BPM. Rolling sub-bass groove, shuffled hi-hats, warm Rhodes chord stabs, subtle chopped vocal echoes, smoky intimate female lead vocal, understated hypnotic late-night club production."' \ --form 'lyrics="[Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go)"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Velvet Room" · 2:26 · generada en 43 s <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'prompt="Deep house at 121 BPM. Rolling sub-bass groove, shuffled hi-hats, warm Rhodes chord stabs, subtle chopped vocal echoes, smoky intimate female lead vocal, understated hypnotic late-night club production."' \ --form 'lyrics="[Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go)"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ACE Music v1 — "Two shadows in a velvet" · 1:53 · generada en 52 s <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/acemusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="acemusic-v1"' \ --form 'style="Deep house at 121 BPM. Rolling sub-bass groove, shuffled hi-hats, warm Rhodes chord stabs, subtle chopped vocal echoes, smoky intimate female lead vocal, understated hypnotic late-night club production."' \ --form 'lyrics="[Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go)"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ### Ronda 6: dueto de jazzy house La consigna más difícil del conjunto: un arreglo a dos voces con capas de jazz en vivo sobre un groove de house, con los roles de voz marcados en la letra. Las etiquetas son una pista, no un parámetro de la API, así que escucha quién de verdad alterna los versos y quién lo reduce a un solo cantante. ``` [Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound ``` TemPolor v4.8 — "Blue Hour" · 2:09 · generada en 69 s <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/song' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model_song="v4.8"' \ --form 'prompt="Jazzy deep house duet at 120 BPM. Rolling deep-house groove with swung hi-hats, walking upright-bass motif over the sub, smoky muted trumpet and tenor-sax licks answering the vocals, extended jazz piano chords, a male and a female lead trading verses and joining in harmony on the chorus, small backing ensemble echoing the hook, warm vinyl texture, sophisticated late-night club production."' \ --form 'lyrics="[Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-tempolor-v4.8.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Blue Hour" · 3:12 · generada en 70 s <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-advanced' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9.5"' \ --form 'lyrics="[Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound"' \ --form 'desc="jazzy deep house, jazz house, duet, male and female vocals, group backing vocals, muted trumpet, saxophone, upright bass, swung, 120 bpm, late night, warm sophisticated production"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music-3.0 — "Blue Hour" · 2:18 · generada en 134 s <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-3.0"' \ --form 'prompt="Jazzy deep house duet at 120 BPM. Rolling deep-house groove with swung hi-hats, walking upright-bass motif over the sub, smoky muted trumpet and tenor-sax licks answering the vocals, extended jazz piano chords, a male and a female lead trading verses and joining in harmony on the chorus, small backing ensemble echoing the hook, warm vinyl texture, sophisticated late-night club production."' \ --form 'lyrics="[Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Blue Hour" · 2:34 · generada en 58 s <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'prompt="Jazzy deep house duet at 120 BPM. Rolling deep-house groove with swung hi-hats, walking upright-bass motif over the sub, smoky muted trumpet and tenor-sax licks answering the vocals, extended jazz piano chords, a male and a female lead trading verses and joining in harmony on the chorus, small backing ensemble echoing the hook, warm vinyl texture, sophisticated late-night club production."' \ --form 'lyrics="[Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ACE Music v1 — "Blue hour settles on the" · 3:05 · generada en 70 s <details markdown="block"> <summary><b>Mostrar la llamada a la API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/acemusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="acemusic-v1"' \ --form 'style="Jazzy deep house duet at 120 BPM. Rolling deep-house groove with swung hi-hats, walking upright-bass motif over the sub, smoky muted trumpet and tenor-sax licks answering the vocals, extended jazz piano chords, a male and a female lead trading verses and joining in harmony on the chorus, small backing ensemble echoing the hook, warm vinyl texture, sophisticated late-night club production."' \ --form 'lyrics="[Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Con la letra dada, los otros cuatro tomaron el título del gancho del coro, mientras que ACE Music tomó las primeras palabras de la letra. Observa que en esta ronda las etiquetas de rol están dentro de los encabezados de sección, `[Verse 1 - male]`, en lugar de ir solas al inicio de una línea, que es la forma que los modelos tratan como estructura. ## Preguntas frecuentes **¿Cuánto cuesta una canción con useapi.net?** Con useapi.net, entre uno y dos centavos de dólar: una canción de Music-3.0 cuesta unos US$0,01 en MiniMax Audio Pro, una de Lyria 3.5 US$0,011 en Flow Music Member, una de Mureka V9.5 US$0,018 en Mureka Premier y una de ACE Music v1 US$0,02 en ACE Music Creator. Las API oficiales cobran US$0,15 en [MiniMax](https://platform.minimax.io/docs/pricing/overview#about-music-models) (cerrada a nuevos usuarios desde el 20 de agosto de 2026), US$0,08 en la [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) de Google y US$0,15 en [Mureka](https://platform.mureka.ai/pricing), con prepago desde US$1.000 (a noviembre de 2026). Consulta [los modelos y lo que cuestan](#the-lineup-and-what-it-costs). **¿Cuál es el más barato con mucho volumen?** Con useapi.net, TemPolor. TemPolor Ultra cuesta un precio fijo de US$29,99 al mes sin cargo por canción, así que cada canción sale más barata cuantas más haces: unos US$0,03 con 1.000 canciones al mes y US$0,015 con 2.000. La API propia de TemPolor cobra [US$0,04 por llamada](https://platform.tempolor.com/docs/6665893m0) a partir de un [paquete prepago de US$100](https://platform.tempolor.com/pricing), así que 1.000 canciones cuestan US$40 ahí con cualquier volumen (a noviembre de 2026). **¿Puedo usar los cinco con un solo token?** Con useapi.net, sí. Un solo token de API llega a [TemPolor](/docs/api-tempolor-v1), [Mureka](/docs/api-mureka-v1), [MiniMax](/docs/api-minimax-v1), [Flow Music](/docs/api-flowmusic-v1) y [ACE Music](/docs/api-acemusic-v1), y a todos los demás servicios que admitimos. Conectas tu suscripción del sitio web de cada servicio una sola vez. Los cuerpos de las solicitudes también se pueden reutilizar, ya que TemPolor usa los mismos campos `prompt` y `lyrics` que MiniMax, y ACE Music recibe los mismos textos como `style` y `lyrics`. **¿Cómo elijo los modelos más nuevos?** Con useapi.net, los modelos más nuevos de TemPolor ya son los predeterminados: `v4.8` en [POST music/song](/docs/api-tempolor-v1/post-tempolor-music-song) mediante `model_song`, e `i4` en [POST music/instrumental](/docs/api-tempolor-v1/post-tempolor-music-instrumental) mediante `model_instrumental`, con los nombres de modelo anteriores redirigidos a ellos. Lyria es la excepción: pasa `model: "lyria-3.5"` en [POST /music](/docs/api-flowmusic-v1/post-flowmusic-music), porque `lyria-3-pro` sigue siendo el predeterminado de Flow Music. Pasa el modelo de forma explícita si tu código debe registrar cuál generó cada pista. **¿Puedo obtener más de una pista por llamada?** Con useapi.net, sí en cuatro de los cinco. MiniMax acepta `quantity` hasta 3, que se cobra como tres canciones. Mureka devuelve dos canciones por generación y Flow Music un par A/B, ambos por el precio de una generación, y ACE Music dos canciones por solicitud, 4 créditos por el par. TemPolor devolvió una pista por llamada durante toda esta prueba, y ejecuta hasta diez generaciones a la vez en una sola cuenta. #### Publicado también en {: .no_toc #cross-posted } También publicado en [dev.to](https://dev.to/useapi/ai-music-apis-one-generation-later-minimax-music-30-vs-lyria-35-vs-mureka-v95-365p){:rel="nofollow"}, comentado en [Reddit](https://www.reddit.com/r/ThirdPartyAPI/comments/1wq8jon/four_ai_music_apis_compared_tempolor_v48_minimax/){:rel="nofollow"} y compartido en [Bluesky](https://bsky.app/profile/useapi.net/post/3mweqttv6bf2e){:rel="nofollow"} (en inglés), y en [YouTube](https://youtu.be/MSUGckk4JqU) como una versión de 15 minutos para escuchar. Ronda anterior: [AI Music APIs Compared](/docs/articles/ai-music-api-comparison) (en inglés). === URL: https://useapi.net/docs/articles/ai-music-flagships-compared-id === Document URL: https://useapi.net/docs/articles/ai-music-flagships-compared-id --- layout: default translation_key: ai-music-flagships lang: id title: "Lima API Musik AI dengan Enam Brief yang Sama: ACE Music v1, TemPolor v4.8, MiniMax Music-3.0, Lyria 3.5, dan Mureka V9.5" description: "Lima model musik AI — ACE Music v1, TemPolor v4.8 dan i4, MiniMax Music-3.0, Google Lyria 3.5, dan Mureka V9.5 — diberi enam brief yang sama lewat API useapi.net, lengkap dengan setiap trek, panggilan API persis di baliknya, waktu pembuatan, dan biaya setiap lagu di langganan situs dibandingkan dengan API resmi." keywords: [AI music API, TemPolor API, TemPolor v4.8, MiniMax Music-3.0 API, Lyria 3.5 API, Mureka V9.5 API, ACE Music API, ACE Music v1 API, AI music API comparison, music generation API, text to music API, AI music API pricing, API musik AI, perbandingan API musik AI, API pembuat lagu AI, harga API musik AI, membuat lagu AI, API teks ke musik, API ACE Music, API TemPolor, API MiniMax Music, API Lyria, API Mureka, tutorial bahasa Indonesia] image: /assets/images/articles/ai-music-flagships-compared.jpg video: name: "Lima API musik AI dengan enam brief yang sama" description: "ACE Music v1, TemPolor v4.8 dan i4, MiniMax Music-3.0, Google Lyria 3.5, dan Mureka V9.5 dengan enam brief yang identik — 30 detik paling keras dari setiap trek, dengan loudness yang disamakan, beserta prompt, harga, dan waktu pembuatan di layar." embed: https://www.youtube.com/embed/MSUGckk4JqU thumbnail: https://i.ytimg.com/vi/MSUGckk4JqU/maxresdefault.jpg date: 2026-11-14 duration: PT15M width: 1920 height: 1080 parent: Articles nav_exclude: true date: 2026-08-19 last_modified: 2026-11-18 nav_order: 96 --- ## Lima API Musik AI dengan Enam Brief yang Sama: ACE Music v1, TemPolor v4.8, MiniMax Music-3.0, Lyria 3.5, dan Mureka V9.5 {: .no_toc #five-ai-music-apis-on-the-same-six-briefs-ace-music-v1-tempolor-v48-minimax-music-30-lyria-35-and-mureka-v95 } 13 menit baca • 19 Agustus 2026 (18 November 2026) ## Daftar isi {: .no_toc .text-delta #table-of-contents } ### Pendahuluan TemPolor v4.8, MiniMax Music-3.0, Lyria 3.5 dari Google, dan Mureka V9.5 — empat model musik AI, enam brief yang sama, satu token API [useapi.net](/docs/subscription). Ke-24 trek ada di bawah, lengkap dan tanpa diedit, masing-masing dengan panggilan API yang membuatnya. Brief-nya sama dengan yang kami pakai pada bulan Juli, jadi setiap trek di sini punya pendahulu untuk dibandingkan di [AI Music APIs Compared](/docs/articles/ai-music-api-comparison). Pada 14 November 2026, tiga bulan setelah model-model lainnya, kami menjalankan enam brief yang identik di ACE Music v1, yang menempati peringkat #1 di [papan peringkat musik vokal Artificial Analysis](https://artificialanalysis.ai/music/leaderboard/vocals), di atas Suno v6. Lagunya menutup setiap ronde di bawah, sehingga halaman ini kini memuat 30 trek. TemPolor, yang baru bergabung sejak Juli, menetapkan harga dengan cara yang berbeda dari semua layanan lain di sini: harga bulanan tetap tanpa biaya per lagu. Biaya setiap lagu ada [di bawah](#the-lineup-and-what-it-costs). Dengarkan dulu dan nilai sendiri model-modelnya. Tidak punya banyak waktu? Ada juga <a href="https://youtu.be/MSUGckk4JqU"><img style="height:1em;vertical-align: middle;" src="/assets/images/youtube.svg" alt=""> video YouTube 15 menit</a> — 30 detik paling keras dari kelima model di setiap brief, diputar berurutan dengan loudness yang disamakan, beserta prompt, harga, dan waktu pembuatan di layar (harga per November 2026). Trek berdurasi penuh dan panggilan API persis di balik masing-masing trek ada di halaman ini. Ronde sebelumnya dari uji ini, dengan tiga model, juga ada di YouTube: [AI Music APIs One Generation Later: MiniMax Music-3.0 vs Lyria 3.5 vs Mureka V9.5](https://www.youtube.com/watch?v=9AM5p-A9oFM). ### Yang berubah sejak Juli | Layanan | Juli | Sekarang | Yang berubah | |---|---|---|---| | TemPolor | belum ada di jajaran | v4.8 (lagu) + i4 (instrumental) | baru di perbandingan ini, dengan dua model baru | | Mureka | V9 | V9.5 | model default baru | | Flow Music | Lyria 3 Pro | Lyria 3.5 | flagship baru — tetapi 3 Pro masih default API | | MiniMax | music-2.6 lewat PixVerse | Music-3.0, native | model baru *dan* endpoint baru | | ACE Music | belum ada di jajaran | ACE Music v1 | ditambahkan pada 14 November 2026 | Dua di antaranya hanya kenaikan versi biasa. Baris MiniMax tidak: [musik MiniMax kini menjadi endpoint kelas satu](/docs/api-minimax-v1/post-minimax-music-create), bukan sesuatu yang Anda jangkau lewat [PixVerse](/docs/api-pixverse-v2/post-pixverse-music-create). Endpoint berbeda, penagihan berbeda. TemPolor adalah pengecualian lainnya. Ini satu-satunya layanan di sini yang membagi pekerjaan ke dua endpoint dengan dua model berbeda: [`POST music/song`](/docs/api-tempolor-v1/post-tempolor-music-song) menjalankan `v4.8` untuk apa pun yang bervokal, dan [`POST music/instrumental`](/docs/api-tempolor-v1/post-tempolor-music-instrumental) menjalankan `i4` untuk apa pun tanpa vokal. Nama model lama masih berfungsi dan otomatis diarahkan ke model baru, jadi kode yang sudah ada tetap berjalan — tetapi itu juga berarti Anda bisa sudah memakai model baru tanpa menyadarinya, atau justru melewatkannya karena sama sekali tidak mengirim nama model. ### Daftar model dan biayanya Biaya satu lagu di API resmi setiap pembuatnya ([TemPolor](https://platform.tempolor.com/docs/6665893m0), [MiniMax](https://platform.minimax.io/docs/pricing/overview#about-music-models) yang tertutup untuk pengguna baru sejak 20 Agustus 2026, [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) milik Google, dan [Mureka](https://platform.mureka.ai/pricing)) dan di langganan situs tempat setiap model dijalankan dalam uji ini (November 2026). Setiap langganan memberi sejumlah kredit per bulan, dan setiap lagu memakai jumlah kredit yang tetap, jadi satu lagu berharga sebesar bagiannya dari langganan itu. | Model | API resmi | Langganan bulanan situs | Harga per lagu | |---|---|---|---| | [TemPolor v4.8 / i4](/docs/api-tempolor-v1) | 4¢ (per panggilan, prabayar mulai $100) | TemPolor Ultra $29,99 | $0 / 0 cr (tanpa biaya per lagu) | | [MiniMax Music-3.0](/docs/api-minimax-v1/post-minimax-music-create) | 15¢ (tertutup untuk pengguna baru sejak 20 Agustus 2026) | MiniMax Audio Pro $99 (3.000.000 cr/bln) | 1¢ / 300 cr (10.000 lagu/bln) | | [Lyria 3.5](/docs/api-flowmusic-v1) | 8¢ (per lagu) | Flow Music Member $64 (30.000 cr/bln) | 1,1¢ / 5 cr (6.000 lagu/bln) | | [Mureka V9.5](/docs/api-mureka-v1) | 15¢ (prabayar mulai $1.000) | Mureka Premier $30 (20.000 cr/bln) | 1,8¢ / 12 cr (1.666 lagu/bln) | | [ACE Music v1](/docs/api-acemusic-v1) | — | ACE Music Creator $9,90 (1.000 cr/bln) | 2¢ / 2 cr (500 lagu/bln) | - Jika model yang menulis lirik dari sebuah prompt, seperti di ronde 3 dan 4, API Mureka menagih 50¢ alih-alih 15¢ dan API MiniMax menambahkan 1¢, sementara lewat useapi.net harga satu lagu tetap sama. - Kredit API TemPolor berharga [$0,01 per kredit di setiap ukuran paket](https://platform.tempolor.com/pricing), jadi volume tidak pernah menurunkan harganya. Paket yang lebih besar justru membeli konkurensi: lima request sekaligus di $100, sepuluh di $500, dan dua puluh di $5.000, dan tingkatnya tidak bertambah jika Anda membeli paket yang sama dua kali. TemPolor Ultra menjalankan sepuluh generate sekaligus. - Model yang di artikel ini disebut `v4.8` bernama `tempolor-latest` di API TemPolor. `i4` tetap memakai namanya. - Paket yang lebih kecil, seperti Mureka Pro dan Flow Music Starter, sedikit lebih mahal per lagu dan tetap jauh di bawah API resmi. - ACE Music mengembalikan dua lagu per request dan menagih 4 kredit untuk sepasang lagu itu, 2 kredit per lagu. Di ACE Music Artist, $29 per bulan atau $16,58 jika ditagih tahunan, satu lagu berharga 2,3¢ atau sekitar 1,3¢. - Langganan Google AI sudah termasuk paket Flow Music, dengan kredit yang terpisah dari kredit Google AI: Starter di [Google AI Plus](https://support.google.com/googleone/answer/16882689?hl=id), Plus di [Google AI Pro](https://support.google.com/googleone/answer/14534406?hl=id), dan Member di [Google AI Ultra](https://support.google.com/googleone/answer/16286513?hl=id). useapi.net berjalan di langganan situs TemPolor, MiniMax Audio, Flow Music, Mureka, atau ACE Music Anda dan menyediakannya sebagai REST API, tanpa biaya tambahan per lagu. Satu token API bekerja untuk kelima layanan — tanpa SDK per layanan, tanpa kunci API terpisah, tanpa lima tagihan yang harus dicocokkan. Token yang sama menjangkau setiap layanan lain yang kami dukung: video, gambar, suara, face swap. ### Cara kami menguji Enam brief yang sama seperti bulan Juli, disalin dari artikel yang sudah terbit, bukan diketik ulang — dua instrumental, dua trek vokal tempat model menulis liriknya sendiri, dan dua trek tempat kami memberikan lirik sekaligus brief gaya yang mendetail. Setiap model dalam satu ronde menerima teks yang identik, jadi yang Anda dengar adalah modelnya. Body request TemPolor disalin byte demi byte dari body MiniMax, yang menerima field `prompt` dan `lyrics` yang sama. ACE Music v1 menerima teks yang sama. API-nya menerima `prompt`, yang darinya model menulis gaya dan liriknya sendiri, atau `style` dengan `lyrics` Anda atau `instrumental`, dan menolak keduanya sekaligus. Jadi ronde 3 dan 4 dikirim sebagai `prompt`, dua brief instrumental sebagai `style` dengan `instrumental: true`, dan ronde 5 dan 6 sebagai `style` plus `lyrics`, tanpa judul, `duration`, atau `bpm`. Waktu pembuatan adalah waktu nyata lewat API dengan granularitas polling 15 detik, jadi anggap sebagai perkiraan, bukan benchmark. Berdasarkan median dari enam ronde, Lyria 3.5 paling cepat dengan 58,5 detik, disusul ACE Music v1 dengan 62 detik, TemPolor 69,5 detik, Mureka 86,5 detik, dan MiniMax 158,5 detik. Jika sebuah model memberi judul sendiri pada hasilnya, kami mempertahankan judul itu, termasuk ejaan dan spasi nyasarnya. Trek lengkap dan tanpa diedit, persis seperti yang dikembalikan setiap API: Mureka dua lagu per generate sebagai MP3 192 kbps, MiniMax satu lagu di 256 kbps, TemPolor satu lagu di 48 kHz dan sekitar 230–320 kbps, ACE Music dua lagu per request sebagai MP3 192 kbps, 48 kHz, dan Flow Music sepasang A/B sebagai WAV 48 kHz, yang ditranskode ke MP3 320 kbps hanya agar bisa diputar di browser. File WAV asli Flow datang langsung dari API. Entri ACE Music di setiap ronde adalah lagu pertama dari dua lagunya, tanpa dipilih-pilih. Satu hal yang perlu diantisipasi jika Anda membangun dengan TemPolor: job lagu melaporkan `status_final: true` dan `COMPLETED` beberapa detik *sebelum* file-nya bisa diambil, dan [`GET music/download/job_id`](/docs/api-tempolor-v1/get-tempolor-music-download-job_id) menjawab `404` di jeda itu. Tiga dari empat ronde vokal kami mengalaminya pada percobaan pertama. Anggap `404` itu sebagai "belum siap" dan terus lakukan polling, bukan sebagai kegagalan. ## Bagian 1 — Instrumental ### Ronde 1: big-band noir ``` Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production. ``` TemPolor i4 — "Generic Rhythm Tune" · 3:09 · dibuat dalam 103 detik <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/instrumental' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model_instrumental="i4"' \ --form 'prompt="Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/01-bigband-noir-tempolor-i4.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Brass Knuckle Boulevard" · 3:19 · dibuat dalam 86 detik <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-instrumental' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9.5"' \ --form 'prompt="Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/01-bigband-noir-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music-3.0 — "Midnight Operative" · 2:51 · dibuat dalam 182 detik <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-3.0"' \ --form 'prompt="Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production."' \ --form 'instrumental="true"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/01-bigband-noir-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Double Cross" · 2:52 · dibuat dalam 47 detik <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'instrumental="true"' \ --form 'prompt="Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/01-bigband-noir-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ACE Music v1 — "Big-band noir action theme" · 2:08 · dibuat dalam 52 detik <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/acemusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="acemusic-v1"' \ --form 'style="Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production."' \ --form 'instrumental="true"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/01-bigband-noir-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Versi bulan Juli dari brief ini ada di [halaman sebelumnya](/docs/articles/ai-music-api-comparison#round-1-big-band-noir) jika Anda ingin membandingkannya berurutan. ### Ronde 2: liquid drum and bass ``` Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production. ``` TemPolor i4 — " Generic Rhythm Beat" · 3:30 · dibuat dalam 69 detik <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/instrumental' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model_instrumental="i4"' \ --form 'prompt="Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/02-liquid-dnb-tempolor-i4.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Piano Afterglow" · 3:22 · dibuat dalam 85 detik <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-instrumental' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9.5"' \ --form 'prompt="Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production."' \ --form 'title="Take B - Liquid DnB"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/02-liquid-dnb-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music-3.0 — "Midnight Flow" · 3:45 · dibuat dalam 227 detik <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-3.0"' \ --form 'prompt="Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production."' \ --form 'instrumental="true"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/02-liquid-dnb-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Silken Tides" · 1:06 · dibuat dalam 59 detik <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'prompt="Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production."' \ --form 'instrumental="true"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/02-liquid-dnb-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ACE Music v1 — "Liquid drum and bass instrumental" · 3:10 · dibuat dalam 89 detik <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/acemusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="acemusic-v1"' \ --form 'style="Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production."' \ --form 'instrumental="true"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/02-liquid-dnb-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Tak satu pun dari empat API awal menyediakan parameter durasi — setiap brief meminta "around 60 seconds" dalam bentuk teks. ACE Music punya satu, `duration` (30 sampai 600 detik), yang sengaja tidak kami kirim agar model membaca kata-kata yang sama. Lyria satu-satunya dari keempatnya yang pernah menuruti petunjuk itu, dan hanya di sini. Lyria 3 Pro menjawab prompt yang sama ini pada bulan Juli dengan durasi 2:46. Di dua ronde prompt di bawah, tempat ACE Music v1 menulis gayanya sendiri, durasinya 0:41 dan 1:22, yang paling mendekati satu menit di ronde-ronde itu. Endpoint instrumental TemPolor juga tidak benar-benar memberi nama pada hasilnya. Untuk dua brief ini ia mengembalikan "Generic Rhythm Tune" dan "Generic Rhythm Beat" — placeholder, bukan judul, dan bahkan tidak rapi: yang pertama datang dengan spasi ganda di tengah, yang kedua dengan spasi di depan. Endpoint lagunya, di empat ronde berikutnya, memberi judul dengan benar. ACE Music, yang tidak dikirimi judul, menamai kedua instrumental dengan kata-kata pertama brief, dan lagu-lagunya di ronde 5 dan 6 dengan kata-kata pertama lirik kami. Jika Anda mengarsipkan trek berdasarkan judul, buat sendiri nama untuk instrumental dan rapikan apa pun yang dikembalikan, atau kirim `title` ke ACE Music. ## Bagian 2 — Vokal, model yang menulis lirik ### Ronde 3: duet pop Satu kalimat arahan, sekaligus uji kemampuan yang disengaja — duet hanya berhasil jika model bisa menghadirkan dua suara. ``` A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus. ``` TemPolor v4.8 — "Text Me" · 1:51 · dibuat dalam 70 detik <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/song' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model_song="v4.8"' \ --form 'prompt="A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-tempolor-v4.8.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Dengarkan baris pertamanya. TemPolor menulis liriknya sendiri untuk brief ini, dan menulisnya dengan penanda penyanyi di dalam baris: ``` [Verse] [Male] You sent "you up?" at 1:09 [Female] You said "just one more," then took your time [Male] I saw your typing, then it slipped away [Female] I dropped my phone and missed your "hey" ``` Penyanyinya membuang `[Verse]` dan `[Chorus]` sebagai struktur, tetapi `[Male]` di dalam baris bukan tag yang dikenalinya — jadi ia menyanyikan kata "male" dan "female" sebagai bagian dari baris. Dua bagian dari model yang sama tidak sepakat soal formatnya sendiri. MiniMax menghadapi masalah yang persis sama di brief ini dan lolos karena menulis `(Male)` dan `(Female)` dalam kurung biasa, yang memang dibuang oleh penyanyinya. Pelajarannya berlaku lebih luas dari satu model ini. Label peran di dalam `lyrics` bukan fitur API yang portabel, jadi jika Anda memberikan lirik sendiri dan menginginkan dua suara, periksa apa yang dilakukan sebuah model dengan gaya kurung Anda sebelum memercayainya — atau hilangkan labelnya dan gambarkan duetnya di prompt gaya. Mureka V9.5 — "Are You Still Awake?" · 3:05 · dibuat dalam 88 detik <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9.5"' \ --form 'prompt="A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music-3.0 — "Three Little Dots" · 2:31 · dibuat dalam 146 detik <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-3.0"' \ --form 'prompt="A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax menamainya dengan indikator mengetik, dan tag `(Male)` / `(Female)` miliknya tidak ikut dinyanyikan. Lyria 3.5 — "You Go First" · 1:59 · dibuat dalam 74 detik <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'prompt="A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria menulis sendiri sahut-sahutan dua suaranya, dengan baris jawaban di dalam tanda kurung. ACE Music v1 — "Three Dot Bubbles" · 0:41 · dibuat dalam 54 detik <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/acemusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="acemusic-v1"' \ --form 'prompt="A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ACE Music juga menamainya dengan indikator mengetik, dan menulis duetnya dengan `(Male)`, `(Female)`, dan `(Both)` dalam kurung biasa, seperti MiniMax. ### Ronde 4: flamenco-pop berbahasa Spanyol Uji bahasa — prompt-nya berbahasa Inggris, lagunya seharusnya tidak: ``` A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals. ``` TemPolor v4.8 — "Lluvia" · 2:58 · dibuat dalam 102 detik <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/song' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model_song="v4.8"' \ --form 'prompt="A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/04-spanish-flamenco-tempolor-v4.8.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Agua de Julio" · 3:32 · dibuat dalam 87 detik <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9.5"' \ --form 'prompt="A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/04-spanish-flamenco-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music-3.0 — "Tacones de Lluvia" · 3:07 · dibuat dalam 171 detik <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-3.0"' \ --form 'prompt="A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/04-spanish-flamenco-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Lluvia de Verano" · 2:33 · dibuat dalam 73 detik <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'prompt="A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/04-spanish-flamenco-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ACE Music v1 — "Fuego en la Tormenta" · 1:22 · dibuat dalam 70 detik <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/acemusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="acemusic-v1"' \ --form 'prompt="A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/04-spanish-flamenco-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Kelimanya menulis lirik berbahasa Spanyol dari prompt berbahasa Inggris, dan kelimanya memberi judul berbahasa Spanyol tanpa diminta. v4.8 milik TemPolor didokumentasikan mendukung [30+ bahasa](/docs/api-tempolor-v1). Satu brief berbahasa Spanyol tidak menguji tiga puluh bahasa itu, tetapi model ini menjawab brief ini dalam bahasa yang tepat dan menamainya "Lluvia" tanpa diminta. ## Bagian 3 — Vokal, lirik kami dan brief gaya yang mendetail Untuk format terakhir, setiap model menerima lirik orisinal yang sama plus brief produksi yang mendetail. Mureka menerimanya lewat [music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced) (`lyrics` + `desc` gaya yang dipisahkan koma + `vocal_gender`), sementara MiniMax, Flow Music, dan TemPolor semuanya menerima field `lyrics` di samping prompt gaya, jadi body yang sama bekerja di tiga dari empat model tanpa diubah. ACE Music menerima dua teks yang sama sebagai `style` dan `lyrics`. ### Ronde 5: deep house ``` [Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go) ``` ``` Deep house at 121 BPM. Rolling sub-bass groove, shuffled hi-hats, warm Rhodes chord stabs, subtle chopped vocal echoes, smoky intimate female lead vocal, understated hypnotic late-night club production. ``` TemPolor v4.8 — "Low Light" · 1:28 · dibuat dalam 51 detik <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/song' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model_song="v4.8"' \ --form 'prompt="Deep house at 121 BPM. Rolling sub-bass groove, shuffled hi-hats, warm Rhodes chord stabs, subtle chopped vocal echoes, smoky intimate female lead vocal, understated hypnotic late-night club production."' \ --form 'lyrics="[Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go)"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-tempolor-v4.8.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Low Light" · 3:09 · dibuat dalam 101 detik <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-advanced' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9.5"' \ --form 'lyrics="[Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go)"' \ --form 'desc="deep house, late night, smoky, hypnotic, groovy, 121 bpm, female vocals, warm, understated club production"' \ --form 'vocal_gender="female"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music-3.0 — "Low Light" · 2:47 · dibuat dalam 135 detik <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-3.0"' \ --form 'prompt="Deep house at 121 BPM. Rolling sub-bass groove, shuffled hi-hats, warm Rhodes chord stabs, subtle chopped vocal echoes, smoky intimate female lead vocal, understated hypnotic late-night club production."' \ --form 'lyrics="[Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go)"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Velvet Room" · 2:26 · dibuat dalam 43 detik <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'prompt="Deep house at 121 BPM. Rolling sub-bass groove, shuffled hi-hats, warm Rhodes chord stabs, subtle chopped vocal echoes, smoky intimate female lead vocal, understated hypnotic late-night club production."' \ --form 'lyrics="[Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go)"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ACE Music v1 — "Two shadows in a velvet" · 1:53 · dibuat dalam 52 detik <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/acemusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="acemusic-v1"' \ --form 'style="Deep house at 121 BPM. Rolling sub-bass groove, shuffled hi-hats, warm Rhodes chord stabs, subtle chopped vocal echoes, smoky intimate female lead vocal, understated hypnotic late-night club production."' \ --form 'lyrics="[Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go)"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ### Ronde 6: duet jazzy house Brief tersulit dari set ini — aransemen dua suara dengan lapisan jazz live di atas groove house, dengan peran suara ditandai di lirik. Tag itu hanya petunjuk, bukan parameter API, jadi dengarkan siapa yang benar-benar bergantian menyanyikan verse dan siapa yang meratakannya menjadi satu penyanyi. ``` [Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound ``` TemPolor v4.8 — "Blue Hour" · 2:09 · dibuat dalam 69 detik <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/song' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model_song="v4.8"' \ --form 'prompt="Jazzy deep house duet at 120 BPM. Rolling deep-house groove with swung hi-hats, walking upright-bass motif over the sub, smoky muted trumpet and tenor-sax licks answering the vocals, extended jazz piano chords, a male and a female lead trading verses and joining in harmony on the chorus, small backing ensemble echoing the hook, warm vinyl texture, sophisticated late-night club production."' \ --form 'lyrics="[Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-tempolor-v4.8.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Blue Hour" · 3:12 · dibuat dalam 70 detik <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-advanced' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9.5"' \ --form 'lyrics="[Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound"' \ --form 'desc="jazzy deep house, jazz house, duet, male and female vocals, group backing vocals, muted trumpet, saxophone, upright bass, swung, 120 bpm, late night, warm sophisticated production"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music-3.0 — "Blue Hour" · 2:18 · dibuat dalam 134 detik <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-3.0"' \ --form 'prompt="Jazzy deep house duet at 120 BPM. Rolling deep-house groove with swung hi-hats, walking upright-bass motif over the sub, smoky muted trumpet and tenor-sax licks answering the vocals, extended jazz piano chords, a male and a female lead trading verses and joining in harmony on the chorus, small backing ensemble echoing the hook, warm vinyl texture, sophisticated late-night club production."' \ --form 'lyrics="[Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Blue Hour" · 2:34 · dibuat dalam 58 detik <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'prompt="Jazzy deep house duet at 120 BPM. Rolling deep-house groove with swung hi-hats, walking upright-bass motif over the sub, smoky muted trumpet and tenor-sax licks answering the vocals, extended jazz piano chords, a male and a female lead trading verses and joining in harmony on the chorus, small backing ensemble echoing the hook, warm vinyl texture, sophisticated late-night club production."' \ --form 'lyrics="[Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ACE Music v1 — "Blue hour settles on the" · 3:05 · dibuat dalam 70 detik <details markdown="block"> <summary><b>Lihat panggilan API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/acemusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="acemusic-v1"' \ --form 'style="Jazzy deep house duet at 120 BPM. Rolling deep-house groove with swung hi-hats, walking upright-bass motif over the sub, smoky muted trumpet and tenor-sax licks answering the vocals, extended jazz piano chords, a male and a female lead trading verses and joining in harmony on the chorus, small backing ensemble echoing the hook, warm vinyl texture, sophisticated late-night club production."' \ --form 'lyrics="[Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Dengan lirik yang diberikan, empat model lainnya mengambil judul dari hook chorus, sementara ACE Music mengambil kata-kata pertama lirik. Perhatikan bahwa label peran di ronde ini berada di dalam header bagian — `[Verse 1 - male]` — bukan berdiri sendiri di awal baris, yang merupakan bentuk yang diperlakukan model sebagai struktur. ## Pertanyaan yang sering diajukan **Berapa biaya satu lagu lewat useapi.net?** Lewat useapi.net, satu sampai dua sen: lagu Music-3.0 sekitar 1¢ di MiniMax Audio Pro, lagu Lyria 3.5 1,1¢ di Flow Music Member, lagu Mureka V9.5 1,8¢ di Mureka Premier, dan lagu ACE Music v1 2¢ di ACE Music Creator. API resmi menagih 15¢ di [MiniMax](https://platform.minimax.io/docs/pricing/overview#about-music-models) (tertutup untuk pengguna baru sejak 20 Agustus 2026), 8¢ di [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) milik Google, dan 15¢ di [Mureka](https://platform.mureka.ai/pricing), prabayar mulai $1.000 (per November 2026). Lihat [daftar model](#the-lineup-and-what-it-costs). **Mana yang termurah untuk volume tinggi?** Lewat useapi.net, TemPolor. TemPolor Ultra berharga tetap $29,99 per bulan tanpa biaya per lagu, jadi setiap lagu makin murah makin banyak yang Anda buat: sekitar 3¢ untuk 1.000 lagu per bulan dan 1,5¢ untuk 2.000 lagu. API milik TemPolor sendiri menagih [$0,04 per panggilan](https://platform.tempolor.com/docs/6665893m0) dari [paket prabayar $100](https://platform.tempolor.com/pricing), jadi 1.000 lagu berharga $40 di sana pada volume berapa pun (per November 2026). **Bisakah saya menjalankan kelimanya dengan satu token?** Lewat useapi.net, bisa. Satu token API menjangkau [TemPolor](/docs/api-tempolor-v1), [Mureka](/docs/api-mureka-v1), [MiniMax](/docs/api-minimax-v1), [Flow Music](/docs/api-flowmusic-v1), dan [ACE Music](/docs/api-acemusic-v1), serta setiap layanan lain yang kami dukung. Anda menghubungkan langganan situs Anda di setiap layanan satu kali saja. Body request juga bisa dipakai ulang, karena TemPolor menerima field `prompt` dan `lyrics` yang sama seperti MiniMax, dan ACE Music menerima teks yang sama sebagai `style` dan `lyrics`. **Bagaimana cara memilih model terbaru?** Lewat useapi.net, model terbaru TemPolor sudah menjadi default: `v4.8` di [POST music/song](/docs/api-tempolor-v1/post-tempolor-music-song) lewat `model_song`, dan `i4` di [POST music/instrumental](/docs/api-tempolor-v1/post-tempolor-music-instrumental) lewat `model_instrumental`, dengan nama model lama diarahkan ke keduanya. Lyria adalah pengecualian: kirim `model: "lyria-3.5"` di [POST /music](/docs/api-flowmusic-v1/post-flowmusic-music), karena `lyria-3-pro` tetap menjadi default Flow Music. Kirim model secara eksplisit jika kode Anda perlu mencatat model mana yang membuat sebuah trek. **Bisakah saya mendapatkan lebih dari satu trek per panggilan?** Lewat useapi.net, bisa di empat dari lima layanan. MiniMax menerima `quantity` hingga 3, ditagih sebagai tiga lagu. Mureka mengembalikan dua lagu per generate dan Flow Music sepasang A/B, keduanya seharga satu generate, dan ACE Music dua lagu per request, 4 kredit untuk sepasang lagu itu. TemPolor mengembalikan satu trek per panggilan sepanjang uji ini, dan menjalankan hingga sepuluh generate sekaligus di satu akun. #### Dipublikasikan juga di {: .no_toc #cross-posted } Juga dipublikasikan di [dev.to](https://dev.to/useapi/ai-music-apis-one-generation-later-minimax-music-30-vs-lyria-35-vs-mureka-v95-365p){:rel="nofollow"}, didiskusikan di [Reddit](https://www.reddit.com/r/ThirdPartyAPI/comments/1wq8jon/four_ai_music_apis_compared_tempolor_v48_minimax/){:rel="nofollow"}, dibagikan di [Bluesky](https://bsky.app/profile/useapi.net/post/3mweqttv6bf2e){:rel="nofollow"}, dan di [YouTube](https://youtu.be/MSUGckk4JqU) sebagai potongan dengar 15 menit. Ronde sebelumnya: [AI Music APIs Compared](/docs/articles/ai-music-api-comparison). === URL: https://useapi.net/docs/articles/ai-music-flagships-compared-ja === Document URL: https://useapi.net/docs/articles/ai-music-flagships-compared-ja --- layout: default lang: ja translation_key: ai-music-flagships title: "同じ6つの課題で比べた5つの AI 音楽 API:ACE Music v1、TemPolor v4.8、MiniMax Music-3.0、Lyria 3.5、Mureka V9.5" description: "ACE Music v1、TemPolor v4.8 と i4、MiniMax Music-3.0、Google Lyria 3.5、Mureka V9.5 の5つの AI 音楽モデルに、useapi.net の API で同じ6つの課題を与えて比較。全トラックと各曲を作った API 呼び出し、生成時間、ウェブサイトのサブスクリプションと公式 API での1曲の料金を掲載します。" keywords: [AI music API, TemPolor API, TemPolor v4.8, MiniMax Music-3.0 API, Lyria 3.5 API, Mureka V9.5 API, ACE Music API, ACE Music v1 API, AI music API comparison, music generation API, text to music API, AI music API pricing, AI 音楽 API, AI 音楽 API 比較, AI 音楽 API 料金, AI 作曲 API, 音楽生成 API, AI 音楽生成 API, 日本語] image: /assets/images/articles/ai-music-flagships-compared.jpg video: name: "同じ6つの課題で比べた5つの AI 音楽 API" description: "ACE Music v1、TemPolor v4.8 と i4、MiniMax Music-3.0、Google Lyria 3.5、Mureka V9.5 を同じ6つの課題で比較。各トラックの最も音の大きい30秒を音量をそろえて流し、プロンプト、料金、生成時間を画面に表示します。" embed: https://www.youtube.com/embed/MSUGckk4JqU thumbnail: https://i.ytimg.com/vi/MSUGckk4JqU/maxresdefault.jpg date: 2026-11-14 duration: PT15M width: 1920 height: 1080 parent: Articles nav_exclude: true date: 2026-08-19 last_modified: 2026-11-18 nav_order: 96 --- ## 同じ6つの課題で比べた5つの AI 音楽 API:ACE Music v1、TemPolor v4.8、MiniMax Music-3.0、Lyria 3.5、Mureka V9.5 {: .no_toc #five-ai-music-apis-on-the-same-six-briefs-ace-music-v1-tempolor-v48-minimax-music-30-lyria-35-and-mureka-v95 } 13分で読めます • 2026年8月19日(2026年11月18日更新) ## 目次 {: .no_toc .text-delta #table-of-contents } ### はじめに TemPolor v4.8、MiniMax Music-3.0、Google の Lyria 3.5、Mureka V9.5。4つの AI 音楽モデルに同じ6つの課題を与え、使った [useapi.net](/docs/subscription) の API トークンは1つだけです。全24トラックを完全版・無編集のまま下に載せ、それぞれにその曲を作った API 呼び出しを添えています。7月と同じ課題なので、どのトラックにも [AI 音楽 API の比較](/docs/articles/ai-music-api-comparison)に聴き比べられる前の世代の曲があります。 ほかの4モデルから3か月後の2026年11月14日、[Artificial Analysis のボーカル音楽リーダーボード](https://artificialanalysis.ai/music/leaderboard/vocals)で Suno v6 を抑えて1位の ACE Music v1 でも、まったく同じ6つの課題を実行しました。各ラウンドの最後に ACE Music v1 の曲を加え、このページのトラックは全部で30になりました。 7月以降に加わった TemPolor は、ほかのどのサービスとも料金の仕組みが違います。月額は定額で、曲ごとの課金はありません。1曲あたりの料金は[下](#the-lineup-and-what-it-costs)にまとめました。まずは聴いて、ご自身でモデルを判断してください。 時間がない方には、<a href="https://youtu.be/MSUGckk4JqU"><img style="height:1em;vertical-align: middle;" src="/assets/images/youtube.svg" alt=""> 15分の YouTube 動画</a>もあります。すべての課題について5つのモデルの最も音の大きい30秒を、音量をそろえて続けて流し、プロンプト、料金、生成時間を画面に表示しています(料金は2026年11月時点)。完全版のトラックと、それぞれを作った正確な API 呼び出しはこのページにあります。 このテストの前回、3モデルで行ったラウンドも YouTube で公開しています:[AI Music APIs One Generation Later: MiniMax Music-3.0 vs Lyria 3.5 vs Mureka V9.5](https://www.youtube.com/watch?v=9AM5p-A9oFM)。 ### 7月からの変化 | サービス | 7月 | 現在 | 変わった点 | |---|---|---|---| | TemPolor | 比較に未参加 | v4.8(歌入り)+ i4(インスト) | この比較に初参加、新モデルも2つ | | Mureka | V9 | V9.5 | 新しいデフォルトモデル | | Flow Music | Lyria 3 Pro | Lyria 3.5 | 新しいフラッグシップ。ただし API のデフォルトは今も 3 Pro | | MiniMax | PixVerse 経由の music-2.6 | Music-3.0、ネイティブ | 新モデル、*そして*新しいエンドポイント | | ACE Music | 比較に未参加 | ACE Music v1 | 2026年11月14日に追加 | このうち2つは通常のバージョンアップですが、MiniMax の行は違います。[MiniMax の音楽生成は独立したエンドポイントになり](/docs/api-minimax-v1/post-minimax-music-create)、[PixVerse](/docs/api-pixverse-v2/post-pixverse-music-create) を経由して使うものではなくなりました。エンドポイントも課金も別です。 TemPolor ももう1つの例外です。ここで唯一、仕事を2つのエンドポイントと2つのモデルに分けています。[`POST music/song`](/docs/api-tempolor-v1/post-tempolor-music-song) はボーカル入りの曲に `v4.8` を、[`POST music/instrumental`](/docs/api-tempolor-v1/post-tempolor-music-instrumental) はボーカルなしの曲に `i4` を使います。古いモデル名も引き続き使え、新しいモデルに自動的に振り替えられるので、既存のコードはそのまま動きます。ただしそのせいで、気づかないうちに新モデルを使っていたり、何も渡さないことで新モデルを見落としたりすることもあります。 ### ラインナップと料金 1曲の料金を、各メーカーの公式 API([TemPolor](https://platform.tempolor.com/docs/6665893m0)、[MiniMax](https://platform.minimax.io/docs/pricing/overview#about-music-models)(2026年8月20日から新規ユーザーの受付を停止)、Google の [Gemini API](https://ai.google.dev/gemini-api/docs/pricing)、[Mureka](https://platform.mureka.ai/pricing))と、このテストで各モデルを動かしたウェブサイトのサブスクリプションで比べました(2026年11月時点)。サブスクリプションには毎月決まった数のクレジットが付き、1曲ごとに決まった数のクレジットを使うので、1曲の料金はサブスクリプション料金のその曲の分の割合です。 | モデル | 公式 API | サイトの月額プラン | 1曲の料金 | |---|---|---|---| | [TemPolor v4.8 / i4](/docs/api-tempolor-v1) | $0.04 (1回、$100 からの前払い) | TemPolor Ultra $29.99 | $0 / 0 cr (曲ごとの課金なし) | | [MiniMax Music-3.0](/docs/api-minimax-v1/post-minimax-music-create) | $0.15 (2026年8月20日から新規受付停止) | MiniMax Audio Pro $99 (月3,000,000 cr) | $0.01 / 300 cr (月10,000曲) | | [Lyria 3.5](/docs/api-flowmusic-v1) | $0.08 (1曲) | Flow Music Member $64 (月30,000 cr) | $0.011 / 5 cr (月6,000曲) | | [Mureka V9.5](/docs/api-mureka-v1) | $0.15 ($1,000 からの前払い) | Mureka Premier $30 (月20,000 cr) | $0.018 / 12 cr (月1,666曲) | | [ACE Music v1](/docs/api-acemusic-v1) | — | ACE Music Creator $9.90 (月1,000 cr) | $0.02 / 2 cr (月500曲) | - ラウンド3と4のようにモデルがプロンプトから歌詞を書く場合、Mureka の API は $0.15 ではなく $0.50 を請求し、MiniMax の API は $0.01 を上乗せします。useapi.net では、どちらの場合も1曲の料金は変わりません。 - TemPolor の API クレジットは[パッケージの大きさにかかわらず1クレジット $0.01](https://platform.tempolor.com/pricing) なので、量を増やしても安くなりません。大きなパッケージで買えるのは同時実行数で、$100 で同時に5リクエスト、$500 で10、$5,000 で20です。同じパッケージを2回買っても上限は増えません。TemPolor Ultra では同時に10件を生成できます。 - この記事で `v4.8` と呼んでいるモデルは、TemPolor の API では `tempolor-latest` です。`i4` は同じ名前のままです。 - Mureka Pro や Flow Music Starter のような小さいプランは1曲あたり少し高くなりますが、それでも公式 API よりずっと安く収まります。 - ACE Music は1リクエストで2曲を返し、2曲で4クレジット、つまり1曲2クレジットを使います。ACE Music Artist(月額 $29、年払いなら月額 $16.58)では、1曲 $0.023、または約 $0.013 です。 - Google AI のサブスクリプションには Flow Music のプランが含まれ、そのクレジットは Google AI のクレジットとは別です。[Google AI Plus](https://support.google.com/googleone/answer/16882689?hl=ja) には Starter、[Google AI Pro](https://support.google.com/googleone/answer/14534406?hl=ja) には Plus、[Google AI Ultra](https://support.google.com/googleone/answer/16286513?hl=ja) には Member が付きます。 useapi.net は、お使いの TemPolor、MiniMax Audio、Flow Music、Mureka、ACE Music のウェブサイトのサブスクリプションで動き、それを REST API として使えるようにします。曲ごとの追加料金はありません。API トークン1つで5つのサービスすべてを使え、サービスごとの SDK も、別々の API キーも、5つの請求の突き合わせも要りません。同じトークンで、私たちが対応しているほかのすべてのサービス(動画、画像、音声、フェイススワップ)も使えます。 ### テストの方法 課題は7月と同じ6つで、打ち直さずに公開済みの記事からコピーしました。インストが2つ、モデルが自分で歌詞を書くボーカル曲が2つ、そして歌詞と凝ったスタイル指定の両方をこちらで用意したものが2つです。各ラウンドではどのモデルにもまったく同じテキストを渡しているので、聞こえる違いはモデルの違いです。TemPolor のリクエスト本文は、同じ `prompt` と `lyrics` フィールドを受け取る MiniMax のものを1バイトも変えずにコピーしました。 ACE Music v1 にも同じテキストを渡しました。ACE Music v1 の API が受け取るのは、スタイルと歌詞をモデル自身が書く元になる `prompt` か、`style` と自作の `lyrics` または `instrumental` のどちらかで、両方を一緒に渡すと拒否されます。そこで、ラウンド3と4は `prompt` として、2つのインストの課題は `style` に `instrumental: true` を付けて、ラウンド5と6は `style` と `lyrics` として渡し、タイトル、`duration`、`bpm` は指定しませんでした。 生成時間は API を通した実時間で、ポーリング間隔が15秒なので、ベンチマークではなく目安として見てください。6ラウンドの中央値では、最速が Lyria 3.5 の58.5秒で、ACE Music v1 が62秒、TemPolor が69.5秒、Mureka が86.5秒、MiniMax が158.5秒でした。モデルが自分でタイトルを付けた場合は、つづりや余分なスペースも含めてそのまま残しています。トラックは各 API が返したままの完全版で、編集していません。Mureka は1回の生成で2曲を 192 kbps の MP3 で、MiniMax は1曲を 256 kbps で、TemPolor は1曲を 48 kHz、約230〜320 kbps で、ACE Music は1リクエストで2曲を 192 kbps、48 kHz の MP3 で、Flow Music は A/B の2曲を 48 kHz の WAV で返し、WAV はブラウザで再生できるようにするためだけに 320 kbps の MP3 に変換しました。Flow の WAV の元ファイルは API からそのまま取得したものです。各ラウンドの ACE Music の曲は2曲のうち1曲目で、選んではいません。 TemPolor で開発するときに知っておきたいことが1つあります。曲のジョブは、ファイルを取得できるようになる数秒*前*に `status_final: true` と `COMPLETED` を返し、その間は [`GET music/download/job_id`](/docs/api-tempolor-v1/get-tempolor-music-download-job_id) が `404` を返します。4つのボーカルラウンドのうち3つで、最初の試行でこれに当たりました。この `404` は失敗ではなく「まだ」という意味だと考えて、ポーリングを続けてください。 ## パート1 — インスト ### ラウンド1:ビッグバンド・ノワール ``` Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production. ``` TemPolor i4 —「Generic Rhythm Tune」· 3:09 · 生成 103秒 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/instrumental' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model_instrumental="i4"' \ --form 'prompt="Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/01-bigband-noir-tempolor-i4.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 —「Brass Knuckle Boulevard」· 3:19 · 生成 86秒 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-instrumental' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9.5"' \ --form 'prompt="Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/01-bigband-noir-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music-3.0 —「Midnight Operative」· 2:51 · 生成 182秒 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-3.0"' \ --form 'prompt="Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production."' \ --form 'instrumental="true"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/01-bigband-noir-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 —「Double Cross」· 2:52 · 生成 47秒 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'instrumental="true"' \ --form 'prompt="Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/01-bigband-noir-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ACE Music v1 —「Big-band noir action theme」· 2:08 · 生成 52秒 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash curl --location 'https://api.useapi.net/v1/acemusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="acemusic-v1"' \ --form 'style="Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production."' \ --form 'instrumental="true"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/01-bigband-noir-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> この課題の7月版は、聴き比べたい方のために[前回のページ](/docs/articles/ai-music-api-comparison#round-1-big-band-noir)に載せています。 ### ラウンド2:リキッド・ドラムンベース ``` Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production. ``` TemPolor i4 —「 Generic Rhythm Beat」· 3:30 · 生成 69秒 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/instrumental' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model_instrumental="i4"' \ --form 'prompt="Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/02-liquid-dnb-tempolor-i4.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 —「Piano Afterglow」· 3:22 · 生成 85秒 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-instrumental' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9.5"' \ --form 'prompt="Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production."' \ --form 'title="Take B - Liquid DnB"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/02-liquid-dnb-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music-3.0 —「Midnight Flow」· 3:45 · 生成 227秒 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-3.0"' \ --form 'prompt="Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production."' \ --form 'instrumental="true"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/02-liquid-dnb-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 —「Silken Tides」· 1:06 · 生成 59秒 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'prompt="Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production."' \ --form 'instrumental="true"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/02-liquid-dnb-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ACE Music v1 —「Liquid drum and bass instrumental」· 3:10 · 生成 89秒 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash curl --location 'https://api.useapi.net/v1/acemusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="acemusic-v1"' \ --form 'style="Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production."' \ --form 'instrumental="true"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/02-liquid-dnb-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> 最初の4つの API には、どれにも長さを指定するパラメータがありません。どの課題も、文章で「around 60 seconds」(約60秒)と頼んでいるだけです。ACE Music には `duration`(30〜600秒)がありますが、同じ文言を読ませるために指定しませんでした。4つのうちこのヒントに従ったことがあるのは Lyria だけで、それもこのラウンドだけです。7月には Lyria 3 Pro がこの同じプロンプトに2:46の曲を返しました。下の2つのプロンプトのラウンドでは、ACE Music v1 は自分でスタイルを書き、0:41と1:22の曲を返しました。どちらも、それぞれのラウンドで最も1分に近い長さです。 TemPolor のインスト用エンドポイントは、出力にちゃんとした名前を付けません。この2つの課題に返したのは「Generic Rhythm Tune」と「Generic Rhythm Beat」で、タイトルというよりプレースホルダーです。しかも整ってもいません。1つ目は途中にスペースが2つあり、2つ目は先頭にスペースが付いています。次の4ラウンドで使う歌入りのエンドポイントは、きちんとタイトルを付けます。タイトルを送らなかった ACE Music は、2つのインストに課題の書き出しの言葉で、ラウンド5と6の曲にはこちらの歌詞の書き出しの言葉で名前を付けました。タイトルでトラックを管理するなら、インストの名前は自分で作り、返ってきた名前は前後の空白を取り除くか、ACE Music に `title` を送ってください。 ## パート2 — ボーカル(歌詞はモデルが書く) ### ラウンド3:ポップのデュエット 指示は1文だけで、能力を確かめるための意図的なテストでもあります。デュエットは、モデルが2つの声を歌い分けられなければ成り立ちません。 ``` A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus. ``` TemPolor v4.8 —「Text Me」· 1:51 · 生成 70秒 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/song' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model_song="v4.8"' \ --form 'prompt="A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-tempolor-v4.8.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> 最初の行を聴いてください。TemPolor はこの課題で歌詞を自分で書き、話し手を行の中にタグで書き込みました。 ``` [Verse] [Male] You sent "you up?" at 1:09 [Female] You said "just one more," then took your time [Male] I saw your typing, then it slipped away [Female] I dropped my phone and missed your "hey" ``` 歌い手は `[Verse]` や `[Chorus]` を構成として取り除きますが、行の中の `[Male]` は認識できるタグではありません。そのため、「male」と「female」という単語を歌詞の一部として歌ってしまいます。同じモデルの2つの部分が、自分のフォーマットについて食い違っているのです。MiniMax もこの課題でまったく同じ問題に当たりましたが、`(Male)` と `(Female)` を丸かっこで書いたので、歌い手がそれを取り除き、事なきを得ました。 この教訓はこのモデルだけの話ではありません。`lyrics` の中の役割ラベルは、どの API でも通じる機能ではありません。自分で歌詞を用意して2つの声で歌わせたいなら、そのかっこの書き方をモデルがどう扱うかを確かめてから信用するか、ラベルを書かずにスタイルのプロンプトでデュエットを説明してください。 Mureka V9.5 —「Are You Still Awake?」· 3:05 · 生成 88秒 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9.5"' \ --form 'prompt="A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music-3.0 —「Three Little Dots」· 2:31 · 生成 146秒 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-3.0"' \ --form 'prompt="A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax はタイピング中の表示にちなんで曲名を付け、`(Male)` / `(Female)` のタグはボーカルに入りませんでした。 Lyria 3.5 —「You Go First」· 1:59 · 生成 74秒 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'prompt="A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria は2つの声の掛け合いを自分で書き、応える側の行をかっこで囲みました。 ACE Music v1 —「Three Dot Bubbles」· 0:41 · 生成 54秒 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash curl --location 'https://api.useapi.net/v1/acemusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="acemusic-v1"' \ --form 'prompt="A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ACE Music もタイピング中の表示にちなんで曲名を付け、MiniMax と同じように `(Male)`、`(Female)`、`(Both)` を丸かっこで書いてデュエットにしました。 ### ラウンド4:スペイン語のフラメンコ・ポップ 言語のテストです。プロンプトは英語ですが、曲は英語であってはいけません。 ``` A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals. ``` TemPolor v4.8 —「Lluvia」· 2:58 · 生成 102秒 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/song' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model_song="v4.8"' \ --form 'prompt="A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/04-spanish-flamenco-tempolor-v4.8.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 —「Agua de Julio」· 3:32 · 生成 87秒 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9.5"' \ --form 'prompt="A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/04-spanish-flamenco-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music-3.0 —「Tacones de Lluvia」· 3:07 · 生成 171秒 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-3.0"' \ --form 'prompt="A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/04-spanish-flamenco-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 —「Lluvia de Verano」· 2:33 · 生成 73秒 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'prompt="A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/04-spanish-flamenco-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ACE Music v1 —「Fuego en la Tormenta」· 1:22 · 生成 70秒 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash curl --location 'https://api.useapi.net/v1/acemusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="acemusic-v1"' \ --form 'prompt="A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/04-spanish-flamenco-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> 5つのモデルすべてが英語のプロンプトからスペイン語の歌詞を書き、頼まれていないのにスペイン語のタイトルを付けました。TemPolor の v4.8 は[30以上の言語](/docs/api-tempolor-v1)に対応するとされています。スペイン語の課題1つで30の言語を試したことにはなりませんが、この課題には正しい言語で応え、頼まれずに「Lluvia」と名付けました。 ## パート3 — ボーカル(こちらの歌詞と凝ったスタイル指定) 最後の形式では、どのモデルにも同じオリジナルの歌詞と詳しいプロダクションの指示を渡します。Mureka は [music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced)(`lyrics` + カンマ区切りのスタイル `desc` + `vocal_gender`)で受け取り、MiniMax、Flow Music、TemPolor はどれもスタイルのプロンプトと並べて `lyrics` フィールドを受け取るので、4つのうち3つでは同じ本文をそのまま使えます。ACE Music は同じ2つのテキストを `style` と `lyrics` として受け取ります。 ### ラウンド5:ディープハウス ``` [Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go) ``` ``` Deep house at 121 BPM. Rolling sub-bass groove, shuffled hi-hats, warm Rhodes chord stabs, subtle chopped vocal echoes, smoky intimate female lead vocal, understated hypnotic late-night club production. ``` TemPolor v4.8 —「Low Light」· 1:28 · 生成 51秒 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/song' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model_song="v4.8"' \ --form 'prompt="Deep house at 121 BPM. Rolling sub-bass groove, shuffled hi-hats, warm Rhodes chord stabs, subtle chopped vocal echoes, smoky intimate female lead vocal, understated hypnotic late-night club production."' \ --form 'lyrics="[Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go)"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-tempolor-v4.8.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 —「Low Light」· 3:09 · 生成 101秒 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-advanced' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9.5"' \ --form 'lyrics="[Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go)"' \ --form 'desc="deep house, late night, smoky, hypnotic, groovy, 121 bpm, female vocals, warm, understated club production"' \ --form 'vocal_gender="female"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music-3.0 —「Low Light」· 2:47 · 生成 135秒 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-3.0"' \ --form 'prompt="Deep house at 121 BPM. Rolling sub-bass groove, shuffled hi-hats, warm Rhodes chord stabs, subtle chopped vocal echoes, smoky intimate female lead vocal, understated hypnotic late-night club production."' \ --form 'lyrics="[Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go)"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 —「Velvet Room」· 2:26 · 生成 43秒 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'prompt="Deep house at 121 BPM. Rolling sub-bass groove, shuffled hi-hats, warm Rhodes chord stabs, subtle chopped vocal echoes, smoky intimate female lead vocal, understated hypnotic late-night club production."' \ --form 'lyrics="[Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go)"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ACE Music v1 —「Two shadows in a velvet」· 1:53 · 生成 52秒 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash curl --location 'https://api.useapi.net/v1/acemusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="acemusic-v1"' \ --form 'style="Deep house at 121 BPM. Rolling sub-bass groove, shuffled hi-hats, warm Rhodes chord stabs, subtle chopped vocal echoes, smoky intimate female lead vocal, understated hypnotic late-night club production."' \ --form 'lyrics="[Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go)"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ### ラウンド6:ジャジーなハウスのデュエット このセットで最も難しい課題です。ハウスのグルーヴに生演奏のジャズの層を重ねた2声のアレンジで、声の役割は歌詞の中にタグで書いてあります。タグはヒントであって API のパラメータではないので、本当に交代で歌っているのはどれか、1人の歌い手にまとめてしまったのはどれかを聴いてみてください。 ``` [Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound ``` TemPolor v4.8 —「Blue Hour」· 2:09 · 生成 69秒 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/song' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model_song="v4.8"' \ --form 'prompt="Jazzy deep house duet at 120 BPM. Rolling deep-house groove with swung hi-hats, walking upright-bass motif over the sub, smoky muted trumpet and tenor-sax licks answering the vocals, extended jazz piano chords, a male and a female lead trading verses and joining in harmony on the chorus, small backing ensemble echoing the hook, warm vinyl texture, sophisticated late-night club production."' \ --form 'lyrics="[Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-tempolor-v4.8.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 —「Blue Hour」· 3:12 · 生成 70秒 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-advanced' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9.5"' \ --form 'lyrics="[Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound"' \ --form 'desc="jazzy deep house, jazz house, duet, male and female vocals, group backing vocals, muted trumpet, saxophone, upright bass, swung, 120 bpm, late night, warm sophisticated production"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music-3.0 —「Blue Hour」· 2:18 · 生成 134秒 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-3.0"' \ --form 'prompt="Jazzy deep house duet at 120 BPM. Rolling deep-house groove with swung hi-hats, walking upright-bass motif over the sub, smoky muted trumpet and tenor-sax licks answering the vocals, extended jazz piano chords, a male and a female lead trading verses and joining in harmony on the chorus, small backing ensemble echoing the hook, warm vinyl texture, sophisticated late-night club production."' \ --form 'lyrics="[Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 —「Blue Hour」· 2:34 · 生成 58秒 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'prompt="Jazzy deep house duet at 120 BPM. Rolling deep-house groove with swung hi-hats, walking upright-bass motif over the sub, smoky muted trumpet and tenor-sax licks answering the vocals, extended jazz piano chords, a male and a female lead trading verses and joining in harmony on the chorus, small backing ensemble echoing the hook, warm vinyl texture, sophisticated late-night club production."' \ --form 'lyrics="[Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ACE Music v1 —「Blue hour settles on the」· 3:05 · 生成 70秒 <details markdown="block"> <summary><b>API 呼び出しを表示</b></summary> ```bash curl --location 'https://api.useapi.net/v1/acemusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="acemusic-v1"' \ --form 'style="Jazzy deep house duet at 120 BPM. Rolling deep-house groove with swung hi-hats, walking upright-bass motif over the sub, smoky muted trumpet and tenor-sax licks answering the vocals, extended jazz piano chords, a male and a female lead trading verses and joining in harmony on the chorus, small backing ensemble echoing the hook, warm vinyl texture, sophisticated late-night club production."' \ --form 'lyrics="[Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> 歌詞を渡した場合、ほかの4つはサビのフックからタイトルを取り、ACE Music は歌詞の書き出しの言葉を使いました。このラウンドの役割ラベルは、モデルが構成として扱う「行の先頭に単独で置く形」ではなく、`[Verse 1 - male]` のようにセクションの見出しの中にあることに注意してください。 ## よくある質問 **useapi.net を使うと1曲いくらですか?** useapi.net なら1曲 $0.01〜0.02 です。Music-3.0 の曲は MiniMax Audio Pro で約 $0.01、Lyria 3.5 の曲は Flow Music Member で $0.011、Mureka V9.5 の曲は Mureka Premier で $0.018、ACE Music v1 の曲は ACE Music Creator で $0.02 です。公式 API では、[MiniMax](https://platform.minimax.io/docs/pricing/overview#about-music-models)(2026年8月20日から新規ユーザーの受付を停止)が $0.15、Google の [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) が $0.08、[Mureka](https://platform.mureka.ai/pricing) が $1,000 からの前払いで $0.15 かかります(2026年11月時点)。[ラインナップ](#the-lineup-and-what-it-costs)をご覧ください。 **大量に作るなら、どれが最も安いですか?** useapi.net なら TemPolor です。TemPolor Ultra は月額 $29.99 の定額で曲ごとの課金がないため、作れば作るほど1曲あたりが安くなります。月1,000曲なら約 $0.03、2,000曲なら $0.015 です。TemPolor 自身の API は [$100 の前払いパッケージ](https://platform.tempolor.com/pricing)から[1回 $0.04](https://platform.tempolor.com/docs/6665893m0) を請求するので、量にかかわらず1,000曲で $40 かかります(2026年11月時点)。 **5つすべてを1つのトークンで使えますか?** useapi.net なら使えます。API トークン1つで [TemPolor](/docs/api-tempolor-v1)、[Mureka](/docs/api-mureka-v1)、[MiniMax](/docs/api-minimax-v1)、[Flow Music](/docs/api-flowmusic-v1)、[ACE Music](/docs/api-acemusic-v1)、そして私たちが対応しているほかのすべてのサービスを使えます。各サービスのウェブサイトのサブスクリプションは、一度接続するだけです。リクエスト本文もそのまま使い回せます。TemPolor は MiniMax と同じ `prompt` と `lyrics` フィールドを受け取り、ACE Music は同じテキストを `style` と `lyrics` として受け取るからです。 **最新のモデルを選ぶにはどうすればいいですか?** useapi.net なら、TemPolor の最新モデルはすでにデフォルトです。[POST music/song](/docs/api-tempolor-v1/post-tempolor-music-song) では `model_song` で `v4.8` が、[POST music/instrumental](/docs/api-tempolor-v1/post-tempolor-music-instrumental) では `model_instrumental` で `i4` が使われ、古いモデル名はこれらに振り替えられます。例外は Lyria で、Flow Music のデフォルトは今も `lyria-3-pro` なので、[POST /music](/docs/api-flowmusic-v1/post-flowmusic-music) では `model: "lyria-3.5"` を指定してください。どのモデルがトラックを作ったかをコードで記録したいなら、モデルを明示的に指定してください。 **1回の呼び出しで複数のトラックを取得できますか?** useapi.net なら、5つのうち4つでできます。MiniMax は `quantity` で最大3曲まで指定でき、3曲分として課金されます。Mureka は1回の生成で2曲、Flow Music は A/B の2曲を、どちらも1回の生成分の料金で返し、ACE Music は1リクエストで2曲を、2曲で4クレジットで返します。TemPolor はこのテストを通して1回の呼び出しで1トラックを返し、1アカウントで同時に10件まで生成できます。 #### ほかの掲載先 {: .no_toc #cross-posted } この記事(英語版)は [dev.to](https://dev.to/useapi/ai-music-apis-one-generation-later-minimax-music-30-vs-lyria-35-vs-mureka-v95-365p){:rel="nofollow"} にも掲載し、[Reddit](https://www.reddit.com/r/ThirdPartyAPI/comments/1wq8jon/four_ai_music_apis_compared_tempolor_v48_minimax/){:rel="nofollow"} で議論され、[Bluesky](https://bsky.app/profile/useapi.net/post/3mweqttv6bf2e){:rel="nofollow"} で共有しました。15分の試聴版は [YouTube](https://youtu.be/MSUGckk4JqU) でも公開しています。前回のラウンド:[AI 音楽 API の比較](/docs/articles/ai-music-api-comparison)。 === URL: https://useapi.net/docs/articles/ai-music-flagships-compared-pt === Document URL: https://useapi.net/docs/articles/ai-music-flagships-compared-pt --- layout: default title: "Cinco APIs de música com IA nos mesmos seis briefings: ACE Music v1, TemPolor v4.8, MiniMax Music-3.0, Lyria 3.5 e Mureka V9.5" description: "Cinco modelos de música com IA (ACE Music v1, TemPolor v4.8 e i4, MiniMax Music-3.0, Google Lyria 3.5 e Mureka V9.5) com os mesmos seis briefings pelas APIs da useapi.net, com cada faixa, a chamada de API exata por trás dela, os tempos de geração e quanto custa cada música numa assinatura do site em comparação com as APIs oficiais." keywords: [API de música com IA, AI music API, TemPolor API, TemPolor v4.8, MiniMax Music-3.0 API, Lyria 3.5 API, Mureka V9.5 API, API do ACE Music, ACE Music API, ACE Music v1 API, comparativo de APIs de música com IA, AI music API comparison, API de geração de música, music generation API, API de texto para música, text to music API, preço de API de música com IA, AI music API pricing] image: /assets/images/articles/ai-music-flagships-compared.jpg video: name: "Cinco APIs de música com IA nos mesmos seis briefings" description: "ACE Music v1, TemPolor v4.8 e i4, MiniMax Music-3.0, Google Lyria 3.5 e Mureka V9.5 nos mesmos seis briefings: os 30 segundos mais altos de cada faixa, com volume equalizado, e o prompt, o preço e o tempo de geração na tela." embed: https://www.youtube.com/embed/MSUGckk4JqU thumbnail: https://i.ytimg.com/vi/MSUGckk4JqU/maxresdefault.jpg date: 2026-11-14 duration: PT15M width: 1920 height: 1080 parent: Articles nav_exclude: true lang: pt-BR translation_key: ai-music-flagships date: 2026-08-19 last_modified: 2026-11-18 nav_order: 96 --- ## Cinco APIs de música com IA nos mesmos seis briefings: ACE Music v1, TemPolor v4.8, MiniMax Music-3.0, Lyria 3.5 e Mureka V9.5 {: .no_toc #five-ai-music-apis-on-the-same-six-briefs-ace-music-v1-tempolor-v48-minimax-music-30-lyria-35-and-mureka-v95 } 13 min de leitura • 19 de agosto de 2026 (18 de novembro de 2026) ## Sumário {: .no_toc .text-delta #table-of-contents } ### Introdução TemPolor v4.8, MiniMax Music-3.0, o Lyria 3.5 do Google e o Mureka V9.5: quatro modelos de música com IA, os mesmos seis briefings, um único token de API da [useapi.net](/docs/subscription). As 24 faixas estão abaixo, completas e sem edição, cada uma com a chamada de API que a gerou. São os mesmos briefings que usamos em julho, então cada faixa aqui tem uma antecessora para comparar em [Comparativo de APIs de música com IA](/docs/articles/ai-music-api-comparison) (em inglês). Em 14 de novembro de 2026, três meses depois dos outros, rodamos os mesmos seis briefings no ACE Music v1, que está em 1º lugar no [ranking de música vocal da Artificial Analysis](https://artificialanalysis.ai/music/leaderboard/vocals), à frente do Suno v6. A música dele fecha cada rodada abaixo, o que leva a página a 30 faixas. O TemPolor, novo desde julho, cobra de um jeito diferente de todos os outros aqui: um preço mensal fixo, sem cobrança por música. Quanto custa cada música está [mais abaixo](#the-lineup-and-what-it-costs). Ouça primeiro e julgue os modelos você mesmo. Sem tempo? Também há um <a href="https://youtu.be/MSUGckk4JqU"><img style="height:1em;vertical-align: middle;" src="/assets/images/youtube.svg" alt=""> vídeo de 15 minutos no YouTube</a>: os 30 segundos mais altos dos cinco modelos em cada briefing, em sequência e com volume equalizado, com o prompt, o preço e o tempo de geração na tela (preços de novembro de 2026). As faixas completas e a chamada de API exata por trás de cada uma estão nesta página. A rodada anterior deste teste, com três modelos, também está no YouTube: [AI Music APIs One Generation Later: MiniMax Music-3.0 vs Lyria 3.5 vs Mureka V9.5](https://www.youtube.com/watch?v=9AM5p-A9oFM) (em inglês). ### O que mudou desde julho | Serviço | Julho | Agora | O que mudou | |---|---|---|---| | TemPolor | fora da seleção | v4.8 (músicas) + i4 (instrumentais) | novo nesta comparação, e dois modelos novos | | Mureka | V9 | V9.5 | novo modelo padrão | | Flow Music | Lyria 3 Pro | Lyria 3.5 | novo carro-chefe, mas o 3 Pro ainda é o padrão da API | | MiniMax | music-2.6 via PixVerse | Music-3.0, nativo | modelo novo *e* endpoint novo | | ACE Music | fora da seleção | ACE Music v1 | adicionado em 14 de novembro de 2026 | Duas dessas são atualizações de versão comuns. A linha do MiniMax não: [a música do MiniMax agora tem endpoint próprio](/docs/api-minimax-v1/post-minimax-music-create), em vez de algo que você alcança pelo [PixVerse](/docs/api-pixverse-v2/post-pixverse-music-create). Endpoint diferente, cobrança diferente. O TemPolor é a outra exceção. É o único serviço aqui que divide o trabalho entre dois endpoints com dois modelos diferentes: [`POST music/song`](/docs/api-tempolor-v1/post-tempolor-music-song) roda o `v4.8` para tudo que tem vocal, e [`POST music/instrumental`](/docs/api-tempolor-v1/post-tempolor-music-instrumental) roda o `i4` para tudo que não tem. Nomes de modelos antigos ainda funcionam e são encaminhados automaticamente aos novos, então o código existente continua rodando, mas isso também significa que você pode estar nos modelos novos sem perceber, ou deixar de usá-los por não passar nada. ### Os modelos e quanto custam Quanto custa uma música na API oficial de cada fabricante ([TemPolor](https://platform.tempolor.com/docs/6665893m0), [MiniMax](https://platform.minimax.io/docs/pricing/overview#about-music-models), fechada a novos usuários desde 20 de agosto de 2026, a [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) do Google e [Mureka](https://platform.mureka.ai/pricing)) e na assinatura do site em que cada modelo rodou neste teste (novembro de 2026). Cada assinatura traz um número mensal de créditos, e cada música usa uma quantidade fixa deles, então uma música custa a sua parte da assinatura. | Modelo | API oficial | Assinatura mensal do site | Preço por música | |---|---|---|---| | [TemPolor v4.8 / i4](/docs/api-tempolor-v1) | $0,04 (por chamada, pré-pago a partir de $100) | TemPolor Ultra $29,99 | $0 / 0 cr (sem cobrança por música) | | [MiniMax Music-3.0](/docs/api-minimax-v1/post-minimax-music-create) | $0,15 (fechada a novos usuários desde 20/08/2026) | MiniMax Audio Pro $99 (3.000.000 cr/mês) | $0,01 / 300 cr (10.000 músicas/mês) | | [Lyria 3.5](/docs/api-flowmusic-v1) | $0,08 (por música) | Flow Music Member $64 (30.000 cr/mês) | $0,011 / 5 cr (6.000 músicas/mês) | | [Mureka V9.5](/docs/api-mureka-v1) | $0,15 (pré-pago a partir de $1.000) | Mureka Premier $30 (20.000 cr/mês) | $0,018 / 12 cr (1.666 músicas/mês) | | [ACE Music v1](/docs/api-acemusic-v1) | — | ACE Music Creator $9,90 (1.000 cr/mês) | $0,02 / 2 cr (500 músicas/mês) | - Quando o modelo escreve a letra a partir de um prompt, como nas rodadas 3 e 4, a API do Mureka cobra $0,50 em vez de $0,15 e a do MiniMax acrescenta $0,01, enquanto pela useapi.net a música custa o mesmo nos dois casos. - Os créditos da API do TemPolor custam [$0,01 cada em qualquer tamanho de pacote](https://platform.tempolor.com/pricing), então o volume nunca reduz o preço. Os pacotes maiores compram concorrência: cinco requisições ao mesmo tempo com $100, dez com $500 e vinte com $5.000, e o nível não se acumula se você comprar o mesmo pacote duas vezes. O TemPolor Ultra roda dez gerações ao mesmo tempo. - O modelo que este artigo chama de `v4.8` é o `tempolor-latest` na API do TemPolor. O `i4` mantém o nome. - Planos menores, como Mureka Pro e Flow Music Starter, custam um pouco mais por música e ainda ficam bem abaixo das APIs oficiais. - O ACE Music devolve duas músicas por requisição e cobra 4 créditos pelo par, 2 créditos por música. No ACE Music Artist, $29 por mês ou $16,58 no plano anual, uma música custa $0,023 ou cerca de $0,013. - As assinaturas Google AI incluem um plano do Flow Music, com créditos separados dos créditos do Google AI: Starter no [Google AI Plus](https://support.google.com/googleone/answer/16882689?hl=pt-BR), Plus no [Google AI Pro](https://support.google.com/googleone/answer/14534406?hl=pt-BR) e Member no [Google AI Ultra](https://support.google.com/googleone/answer/16286513?hl=pt-BR). A useapi.net roda na sua assinatura do site do TemPolor, MiniMax Audio, Flow Music, Mureka ou ACE Music e a expõe como uma API REST, sem sobretaxa por música. Um único token de API funciona nos cinco serviços: nenhum SDK por serviço, nenhuma chave de API separada, nenhuma conciliação de cinco cobranças. O mesmo token alcança todos os outros serviços que suportamos: vídeo, imagem, fala, troca de rosto. ### Como testamos Os mesmos seis briefings de julho, copiados do artigo publicado em vez de redigitados: dois instrumentais, duas faixas com vocal em que o modelo escreve a própria letra e duas em que fornecemos tanto a letra quanto um briefing de estilo elaborado. Todos os modelos de uma rodada recebem exatamente o mesmo texto, então o que você ouve é o modelo. Os corpos de requisição do TemPolor foram copiados byte a byte dos do MiniMax, que recebem os mesmos campos `prompt` e `lyrics`. O ACE Music v1 recebeu o mesmo texto. A API dele aceita um `prompt`, a partir do qual escreve o próprio estilo e a própria letra, ou um `style` com a sua `lyrics` ou com `instrumental`, e recusa os dois juntos. Por isso as rodadas 3 e 4 entraram como `prompt`, os dois briefings instrumentais como `style` com `instrumental: true`, e as rodadas 5 e 6 como `style` mais `lyrics`, sem título, `duration` nem `bpm`. Os tempos de geração são de relógio, pela API, com granularidade de polling de 15 segundos, então trate-os como estimativa, não como benchmark. Pela mediana das seis rodadas, o Lyria 3.5 foi o mais rápido, com 58,5 s, seguido do ACE Music v1 com 62 s, do TemPolor com 69,5 s, do Mureka com 86,5 s e do MiniMax com 158,5 s. Quando um modelo dá título à própria faixa, mantivemos o título, inclusive a grafia e os espaços sobrando. As faixas estão completas e sem edição, exatamente como cada API as devolveu: o Mureka, duas músicas por geração em MP3 de 192 kbps; o MiniMax, uma a 256 kbps; o TemPolor, uma a 48 kHz e cerca de 230–320 kbps; o ACE Music, duas músicas por requisição em MP3 de 192 kbps e 48 kHz; e o Flow Music, um par A/B em WAV de 48 kHz, convertido para MP3 de 320 kbps só para o navegador conseguir tocar. Os WAV originais do Flow vêm direto da API. A faixa do ACE Music em cada rodada é a primeira das duas músicas, sem escolha. Um ponto a esperar se você integrar com o TemPolor: um job de música informa `status_final: true` e `COMPLETED` alguns segundos *antes* de o arquivo estar disponível para download, e [`GET music/download/job_id`](/docs/api-tempolor-v1/get-tempolor-music-download-job_id) responde `404` nesse intervalo. Três das nossas quatro rodadas com vocal caíram nisso na primeira tentativa. Trate esse `404` como "ainda não" e continue o polling, em vez de tratá-lo como falha. ## Parte 1 — Instrumentais ### Rodada 1: big band noir ``` Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production. ``` TemPolor i4 — "Generic Rhythm Tune" · 3:09 · gerada em 103 s <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/instrumental' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model_instrumental="i4"' \ --form 'prompt="Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/01-bigband-noir-tempolor-i4.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Brass Knuckle Boulevard" · 3:19 · gerada em 86 s <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-instrumental' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9.5"' \ --form 'prompt="Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/01-bigband-noir-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music-3.0 — "Midnight Operative" · 2:51 · gerada em 182 s <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-3.0"' \ --form 'prompt="Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production."' \ --form 'instrumental="true"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/01-bigband-noir-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Double Cross" · 2:52 · gerada em 47 s <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'instrumental="true"' \ --form 'prompt="Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/01-bigband-noir-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ACE Music v1 — "Big-band noir action theme" · 2:08 · gerada em 52 s <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/acemusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="acemusic-v1"' \ --form 'style="Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production."' \ --form 'instrumental="true"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/01-bigband-noir-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> As versões de julho deste briefing estão na [página anterior](/docs/articles/ai-music-api-comparison#round-1-big-band-noir) (em inglês), se quiser ouvi-las em sequência. ### Rodada 2: liquid drum and bass ``` Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production. ``` TemPolor i4 — " Generic Rhythm Beat" · 3:30 · gerada em 69 s <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/instrumental' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model_instrumental="i4"' \ --form 'prompt="Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/02-liquid-dnb-tempolor-i4.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Piano Afterglow" · 3:22 · gerada em 85 s <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-instrumental' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9.5"' \ --form 'prompt="Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production."' \ --form 'title="Take B - Liquid DnB"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/02-liquid-dnb-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music-3.0 — "Midnight Flow" · 3:45 · gerada em 227 s <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-3.0"' \ --form 'prompt="Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production."' \ --form 'instrumental="true"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/02-liquid-dnb-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Silken Tides" · 1:06 · gerada em 59 s <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'prompt="Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production."' \ --form 'instrumental="true"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/02-liquid-dnb-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ACE Music v1 — "Liquid drum and bass instrumental" · 3:10 · gerada em 89 s <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/acemusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="acemusic-v1"' \ --form 'style="Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production."' \ --form 'instrumental="true"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/02-liquid-dnb-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Nenhuma das quatro APIs originais expõe um parâmetro de duração: todo briefing pedia "around 60 seconds" (cerca de 60 segundos) no próprio texto. O ACE Music tem um, `duration` (30 a 600 segundos), que deixamos de fora para que ele lesse as mesmas palavras. O Lyria foi o único dos quatro que chegou a seguir a dica, e só aqui. O Lyria 3 Pro respondeu a este mesmo prompt em julho com 2:46. Nas duas rodadas de prompt abaixo, em que o ACE Music v1 escreve o próprio estilo, ele ficou em 0:41 e 1:22, o mais perto de um minuto nessas rodadas. O endpoint instrumental do TemPolor também não dá nome de verdade à saída. Ele devolveu "Generic Rhythm Tune" e "Generic Rhythm Beat" para esses dois briefings, marcadores no lugar de títulos, e nem sequer bem formatados: o primeiro chega com um espaço duplo no meio, o segundo com um espaço no início. O endpoint de músicas, nas próximas quatro rodadas, dá títulos de verdade. O ACE Music, sem receber título, nomeou os dois instrumentais com as primeiras palavras do briefing, e as músicas das rodadas 5 e 6 com as primeiras palavras da nossa letra. Se você organiza faixas por título, gere você mesmo o nome dos instrumentais e apare os espaços do que vier, ou envie um `title` ao ACE Music. ## Parte 2 — Vocais, o modelo escreve a letra ### Rodada 3: dueto pop Uma frase de direção e um teste deliberado de capacidade: um dueto só funciona se o modelo conseguir encenar duas vozes. ``` A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus. ``` TemPolor v4.8 — "Text Me" · 1:51 · gerada em 70 s <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/song' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model_song="v4.8"' \ --form 'prompt="A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-tempolor-v4.8.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Ouça a primeira linha. O TemPolor escreveu a própria letra para este briefing, e com quem canta marcado dentro da própria linha: ``` [Verse] [Male] You sent "you up?" at 1:09 [Female] You said "just one more," then took your time [Male] I saw your typing, then it slipped away [Female] I dropped my phone and missed your "hey" ``` O cantor dele remove `[Verse]` e `[Chorus]` como estrutura, mas um `[Male]` no meio da linha não é uma tag que ele reconheça, então ele canta as palavras "male" e "female" como parte do verso. As duas metades do mesmo modelo discordam sobre o próprio formato. O MiniMax encontrou exatamente o mesmo problema neste briefing e se saiu bem escrevendo `(Male)` e `(Female)` entre parênteses, que o cantor dele de fato descarta. A lição vale além deste modelo. Rótulos de papel dentro de `lyrics` não são um recurso portátil de API; então, se você fornece a letra e quer duas vozes, verifique o que cada modelo faz com o seu estilo de colchetes antes de confiar nele, ou deixe os rótulos de fora e descreva o dueto no prompt de estilo. Mureka V9.5 — "Are You Still Awake?" · 3:05 · gerada em 88 s <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9.5"' \ --form 'prompt="A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music-3.0 — "Three Little Dots" · 2:31 · gerada em 146 s <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-3.0"' \ --form 'prompt="A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> O MiniMax deu à música o nome do indicador de digitação, e as tags `(Male)` / `(Female)` ficaram fora do vocal. Lyria 3.5 — "You Go First" · 1:59 · gerada em 74 s <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'prompt="A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> O Lyria escreveu a própria pergunta e resposta a duas vozes, com as falas de resposta entre parênteses. ACE Music v1 — "Three Dot Bubbles" · 0:41 · gerada em 54 s <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/acemusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="acemusic-v1"' \ --form 'prompt="A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> O ACE Music também deu à música o nome do indicador de digitação, e escreveu o dueto com `(Male)`, `(Female)` e `(Both)` entre parênteses, como o MiniMax. ### Rodada 4: flamenco-pop em espanhol O teste de idioma: o prompt está em inglês, a música não deveria estar: ``` A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals. ``` TemPolor v4.8 — "Lluvia" · 2:58 · gerada em 102 s <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/song' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model_song="v4.8"' \ --form 'prompt="A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/04-spanish-flamenco-tempolor-v4.8.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Agua de Julio" · 3:32 · gerada em 87 s <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9.5"' \ --form 'prompt="A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/04-spanish-flamenco-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music-3.0 — "Tacones de Lluvia" · 3:07 · gerada em 171 s <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-3.0"' \ --form 'prompt="A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/04-spanish-flamenco-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Lluvia de Verano" · 2:33 · gerada em 73 s <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'prompt="A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/04-spanish-flamenco-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ACE Music v1 — "Fuego en la Tormenta" · 1:22 · gerada em 70 s <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/acemusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="acemusic-v1"' \ --form 'prompt="A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/04-spanish-flamenco-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Os cinco escreveram letras em espanhol a partir de um prompt em inglês, e os cinco deram à faixa um título em espanhol sem que isso fosse pedido. O v4.8 do TemPolor é documentado como cobrindo [mais de 30 idiomas](/docs/api-tempolor-v1). Um único briefing em espanhol não testa trinta deles, mas ele respondeu a este no idioma certo e chamou a faixa de "Lluvia" por conta própria. ## Parte 3 — Vocais, a nossa letra e um briefing de estilo elaborado No formato final, cada modelo recebe a mesma letra original mais um briefing de produção detalhado. O Mureka recebe isso por [music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced) (`lyrics` + um `desc` de estilo separado por vírgulas + `vocal_gender`), enquanto MiniMax, Flow Music e TemPolor recebem um campo `lyrics` ao lado do prompt de estilo, então o mesmo corpo funciona sem mudanças em três dos quatro. O ACE Music recebe os mesmos dois textos como `style` e `lyrics`. ### Rodada 5: deep house ``` [Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go) ``` ``` Deep house at 121 BPM. Rolling sub-bass groove, shuffled hi-hats, warm Rhodes chord stabs, subtle chopped vocal echoes, smoky intimate female lead vocal, understated hypnotic late-night club production. ``` TemPolor v4.8 — "Low Light" · 1:28 · gerada em 51 s <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/song' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model_song="v4.8"' \ --form 'prompt="Deep house at 121 BPM. Rolling sub-bass groove, shuffled hi-hats, warm Rhodes chord stabs, subtle chopped vocal echoes, smoky intimate female lead vocal, understated hypnotic late-night club production."' \ --form 'lyrics="[Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go)"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-tempolor-v4.8.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Low Light" · 3:09 · gerada em 101 s <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-advanced' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9.5"' \ --form 'lyrics="[Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go)"' \ --form 'desc="deep house, late night, smoky, hypnotic, groovy, 121 bpm, female vocals, warm, understated club production"' \ --form 'vocal_gender="female"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music-3.0 — "Low Light" · 2:47 · gerada em 135 s <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-3.0"' \ --form 'prompt="Deep house at 121 BPM. Rolling sub-bass groove, shuffled hi-hats, warm Rhodes chord stabs, subtle chopped vocal echoes, smoky intimate female lead vocal, understated hypnotic late-night club production."' \ --form 'lyrics="[Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go)"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Velvet Room" · 2:26 · gerada em 43 s <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'prompt="Deep house at 121 BPM. Rolling sub-bass groove, shuffled hi-hats, warm Rhodes chord stabs, subtle chopped vocal echoes, smoky intimate female lead vocal, understated hypnotic late-night club production."' \ --form 'lyrics="[Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go)"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ACE Music v1 — "Two shadows in a velvet" · 1:53 · gerada em 52 s <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/acemusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="acemusic-v1"' \ --form 'style="Deep house at 121 BPM. Rolling sub-bass groove, shuffled hi-hats, warm Rhodes chord stabs, subtle chopped vocal echoes, smoky intimate female lead vocal, understated hypnotic late-night club production."' \ --form 'lyrics="[Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go)"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ### Rodada 6: dueto de house jazzístico O briefing mais difícil do conjunto: um arranjo a duas vozes com camadas de jazz ao vivo sobre um groove de house, com os papéis das vozes marcados na letra. As tags são uma dica, não um parâmetro da API, então preste atenção em quem realmente alterna os versos e em quem achata tudo em um único cantor. ``` [Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound ``` TemPolor v4.8 — "Blue Hour" · 2:09 · gerada em 69 s <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/song' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model_song="v4.8"' \ --form 'prompt="Jazzy deep house duet at 120 BPM. Rolling deep-house groove with swung hi-hats, walking upright-bass motif over the sub, smoky muted trumpet and tenor-sax licks answering the vocals, extended jazz piano chords, a male and a female lead trading verses and joining in harmony on the chorus, small backing ensemble echoing the hook, warm vinyl texture, sophisticated late-night club production."' \ --form 'lyrics="[Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-tempolor-v4.8.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Blue Hour" · 3:12 · gerada em 70 s <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-advanced' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9.5"' \ --form 'lyrics="[Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound"' \ --form 'desc="jazzy deep house, jazz house, duet, male and female vocals, group backing vocals, muted trumpet, saxophone, upright bass, swung, 120 bpm, late night, warm sophisticated production"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music-3.0 — "Blue Hour" · 2:18 · gerada em 134 s <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-3.0"' \ --form 'prompt="Jazzy deep house duet at 120 BPM. Rolling deep-house groove with swung hi-hats, walking upright-bass motif over the sub, smoky muted trumpet and tenor-sax licks answering the vocals, extended jazz piano chords, a male and a female lead trading verses and joining in harmony on the chorus, small backing ensemble echoing the hook, warm vinyl texture, sophisticated late-night club production."' \ --form 'lyrics="[Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Blue Hour" · 2:34 · gerada em 58 s <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'prompt="Jazzy deep house duet at 120 BPM. Rolling deep-house groove with swung hi-hats, walking upright-bass motif over the sub, smoky muted trumpet and tenor-sax licks answering the vocals, extended jazz piano chords, a male and a female lead trading verses and joining in harmony on the chorus, small backing ensemble echoing the hook, warm vinyl texture, sophisticated late-night club production."' \ --form 'lyrics="[Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ACE Music v1 — "Blue hour settles on the" · 3:05 · gerada em 70 s <details markdown="block"> <summary><b>Mostrar a chamada da API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/acemusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="acemusic-v1"' \ --form 'style="Jazzy deep house duet at 120 BPM. Rolling deep-house groove with swung hi-hats, walking upright-bass motif over the sub, smoky muted trumpet and tenor-sax licks answering the vocals, extended jazz piano chords, a male and a female lead trading verses and joining in harmony on the chorus, small backing ensemble echoing the hook, warm vinyl texture, sophisticated late-night club production."' \ --form 'lyrics="[Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Com a letra fornecida, os outros quatro tiraram o título do gancho do refrão, enquanto o ACE Music usou as primeiras palavras da letra. Note que os rótulos de papel desta rodada ficam dentro dos cabeçalhos de seção, `[Verse 1 - male]`, e não sozinhos no início de uma linha, que é a forma que os modelos tratam como estrutura. ## Perguntas frequentes **Quanto custa uma música pela useapi.net?** Pela useapi.net, de um a dois centavos de dólar: uma música do Music-3.0 custa cerca de $0,01 no MiniMax Audio Pro, uma do Lyria 3.5 $0,011 no Flow Music Member, uma do Mureka V9.5 $0,018 no Mureka Premier e uma do ACE Music v1 $0,02 no ACE Music Creator. As APIs oficiais cobram $0,15 no [MiniMax](https://platform.minimax.io/docs/pricing/overview#about-music-models) (fechada a novos usuários desde 20 de agosto de 2026), $0,08 na [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) do Google e $0,15 no [Mureka](https://platform.mureka.ai/pricing), pré-pago a partir de $1.000 (em novembro de 2026). Veja [os modelos e quanto custam](#the-lineup-and-what-it-costs). **Qual é o mais barato em alto volume?** Pela useapi.net, o TemPolor. O TemPolor Ultra custa $29,99 fixos por mês, sem cobrança por música, então cada música fica mais barata quanto mais você gera: cerca de $0,03 com 1.000 músicas por mês e $0,015 com 2.000. A API do próprio TemPolor cobra [$0,04 por chamada](https://platform.tempolor.com/docs/6665893m0) a partir de um [pacote pré-pago de $100](https://platform.tempolor.com/pricing), então 1.000 músicas custam $40 lá, em qualquer volume (em novembro de 2026). **Dá para rodar os cinco com um único token?** Pela useapi.net, sim. Um único token de API alcança [TemPolor](/docs/api-tempolor-v1), [Mureka](/docs/api-mureka-v1), [MiniMax](/docs/api-minimax-v1), [Flow Music](/docs/api-flowmusic-v1) e [ACE Music](/docs/api-acemusic-v1), e todos os outros serviços que suportamos. Você conecta a sua assinatura do site de cada serviço uma única vez. Os corpos de requisição também se aproveitam, já que o TemPolor recebe os mesmos campos `prompt` e `lyrics` que o MiniMax, e o ACE Music os mesmos textos como `style` e `lyrics`. **Como escolho os modelos mais novos?** Pela useapi.net, os modelos mais novos do TemPolor já são os padrões: `v4.8` no [POST music/song](/docs/api-tempolor-v1/post-tempolor-music-song) via `model_song`, e `i4` no [POST music/instrumental](/docs/api-tempolor-v1/post-tempolor-music-instrumental) via `model_instrumental`, com os nomes de modelos antigos encaminhados a eles. O Lyria é a exceção: passe `model: "lyria-3.5"` no [POST /music](/docs/api-flowmusic-v1/post-flowmusic-music), porque `lyria-3-pro` continua sendo o padrão do Flow Music. Passe o modelo explicitamente se o seu código precisar registrar qual deles gerou uma faixa. **Dá para receber mais de uma faixa por chamada?** Pela useapi.net, sim, em quatro dos cinco. O MiniMax aceita `quantity` até 3, cobrado como três músicas. O Mureka devolve duas músicas por geração e o Flow Music um par A/B, ambos pelo preço de uma geração, e o ACE Music duas músicas por requisição, 4 créditos pelo par. O TemPolor devolveu uma faixa por chamada em todo este teste, e roda até dez gerações ao mesmo tempo em uma conta. #### Publicado também em {: .no_toc #cross-posted } Também publicado no [dev.to](https://dev.to/useapi/ai-music-apis-one-generation-later-minimax-music-30-vs-lyria-35-vs-mureka-v95-365p){:rel="nofollow"} (em inglês), discutido no [Reddit](https://www.reddit.com/r/ThirdPartyAPI/comments/1wq8jon/four_ai_music_apis_compared_tempolor_v48_minimax/){:rel="nofollow"} (em inglês), compartilhado no [Bluesky](https://bsky.app/profile/useapi.net/post/3mweqttv6bf2e){:rel="nofollow"} e no [YouTube](https://youtu.be/MSUGckk4JqU) como um corte de audição de 15 minutos. Rodada anterior: [Comparativo de APIs de música com IA](/docs/articles/ai-music-api-comparison) (em inglês). === URL: https://useapi.net/docs/articles/ai-music-flagships-compared-th === Document URL: https://useapi.net/docs/articles/ai-music-flagships-compared-th --- layout: default translation_key: ai-music-flagships lang: th title: "API เพลง AI ห้าตัวกับโจทย์เดียวกันหกโจทย์: ACE Music v1, TemPolor v4.8, MiniMax Music-3.0, Lyria 3.5 และ Mureka V9.5" description: "โมเดลเพลง AI ห้าตัว — ACE Music v1, TemPolor v4.8 และ i4, MiniMax Music-3.0, Google Lyria 3.5 และ Mureka V9.5 — กับโจทย์เดียวกันหกโจทย์ผ่าน API ของ useapi.net พร้อมทุกแทร็ก การเรียก API ที่อยู่เบื้องหลัง เวลาที่ใช้สร้าง และค่าใช้จ่ายต่อเพลงบนแพ็กเกจเว็บไซต์เทียบกับ API ทางการ" keywords: [AI music API, TemPolor API, TemPolor v4.8, MiniMax Music-3.0 API, Lyria 3.5 API, Mureka V9.5 API, ACE Music API, ACE Music v1 API, AI music API comparison, music generation API, text to music API, AI music API pricing, API เพลง AI, เปรียบเทียบ API เพลง AI, ราคา API เพลง AI, API สร้างเพลง AI, สร้างเพลงด้วย AI, แต่งเพลง AI, เพลง AI มีเสียงร้อง, เปรียบเทียบเพลง AI] image: /assets/images/articles/ai-music-flagships-compared.jpg video: name: "API เพลง AI ห้าตัวกับโจทย์เดียวกันหกโจทย์" description: "ACE Music v1, TemPolor v4.8 และ i4, MiniMax Music-3.0, Google Lyria 3.5 และ Mureka V9.5 กับโจทย์เดียวกันหกโจทย์ — 30 วินาทีที่ดังที่สุดของแต่ละแทร็ก ปรับความดังให้เท่ากัน พร้อมพรอมต์ ราคา และเวลาที่ใช้สร้างบนหน้าจอ" embed: https://www.youtube.com/embed/MSUGckk4JqU thumbnail: https://i.ytimg.com/vi/MSUGckk4JqU/maxresdefault.jpg date: 2026-11-14 duration: PT15M width: 1920 height: 1080 parent: Articles nav_exclude: true date: 2026-08-19 last_modified: 2026-11-18 nav_order: 96 --- ## API เพลง AI ห้าตัวกับโจทย์เดียวกันหกโจทย์: ACE Music v1, TemPolor v4.8, MiniMax Music-3.0, Lyria 3.5 และ Mureka V9.5 {: .no_toc #five-ai-music-apis-on-the-same-six-briefs-ace-music-v1-tempolor-v48-minimax-music-30-lyria-35-and-mureka-v95 } อ่าน 13 นาที • 19 สิงหาคม 2026 (18 พฤศจิกายน 2026) ## สารบัญ {: .no_toc .text-delta #table-of-contents } ### บทนำ TemPolor v4.8, MiniMax Music-3.0, Lyria 3.5 ของ Google และ Mureka V9.5 — โมเดลเพลง AI สี่ตัว โจทย์เดียวกันหกโจทย์ และโทเค็น API ของ [useapi.net](/docs/subscription) เพียงโทเค็นเดียว แทร็กทั้ง 24 แทร็กอยู่ด้านล่าง ครบถ้วนและไม่ผ่านการตัดต่อ แต่ละแทร็กมีการเรียก API ที่ใช้สร้างแทร็กนั้นกำกับไว้ โจทย์ชุดนี้คือชุดเดียวกับที่เราใช้ในเดือนกรกฎาคม ทุกแทร็กในหน้านี้จึงมีรุ่นก่อนหน้าให้เทียบได้ใน [AI Music APIs Compared](/docs/articles/ai-music-api-comparison) (ภาษาอังกฤษ) วันที่ 14 พฤศจิกายน 2026 สามเดือนหลังจากโมเดลอื่น เรารันโจทย์หกโจทย์เดิมกับ ACE Music v1 ซึ่งอยู่อันดับ 1 บน[ตารางอันดับโมเดลเพลงที่มีเสียงร้องของ Artificial Analysis](https://artificialanalysis.ai/music/leaderboard/vocals) นำหน้า Suno v6 เพลงของ ACE Music v1 ปิดท้ายแต่ละรอบด้านล่าง ทำให้หน้านี้มีทั้งหมด 30 แทร็ก TemPolor ซึ่งเพิ่งเข้ามาหลังเดือนกรกฎาคม คิดราคาต่างจากเจ้าอื่นทั้งหมดในหน้านี้: ราคารายเดือนคงที่ โดยไม่คิดเงินต่อเพลง ค่าใช้จ่ายของแต่ละเพลงอยู่[ด้านล่าง](#the-lineup-and-what-it-costs) ฟังก่อน แล้วตัดสินโมเดลด้วยตัวคุณเอง มีเวลาไม่มาก? มี<a href="https://youtu.be/MSUGckk4JqU"><img style="height:1em;vertical-align: middle;" src="/assets/images/youtube.svg" alt=""> วิดีโอ YouTube ยาว 15 นาที</a> (ภาษาอังกฤษ) ด้วย — 30 วินาทีที่ดังที่สุดของทั้งห้าโมเดลในทุกโจทย์ เล่นต่อกันและปรับความดังให้เท่ากัน พร้อมพรอมต์ ราคา และเวลาที่ใช้สร้างบนหน้าจอ (ราคา ณ พฤศจิกายน 2026) ส่วนแทร็กเต็มความยาวและการเรียก API ที่ใช้สร้างแต่ละแทร็กอยู่ในหน้านี้ การทดสอบรอบก่อนหน้าซึ่งมีสามโมเดลก็อยู่บน YouTube เช่นกัน: [AI Music APIs One Generation Later: MiniMax Music-3.0 vs Lyria 3.5 vs Mureka V9.5](https://www.youtube.com/watch?v=9AM5p-A9oFM) (ภาษาอังกฤษ) ### สิ่งที่เปลี่ยนไปตั้งแต่เดือนกรกฎาคม | บริการ | กรกฎาคม | ตอนนี้ | สิ่งที่เปลี่ยน | |---|---|---|---| | TemPolor | ไม่ได้อยู่ในรายชื่อ | v4.8 (เพลง) + i4 (เพลงบรรเลง) | ใหม่ในการเปรียบเทียบนี้ และมีโมเดลใหม่สองตัว | | Mureka | V9 | V9.5 | โมเดลเริ่มต้นตัวใหม่ | | Flow Music | Lyria 3 Pro | Lyria 3.5 | เรือธงตัวใหม่ — แต่ 3 Pro ยังเป็นค่าเริ่มต้นของ API | | MiniMax | music-2.6 ผ่าน PixVerse | Music-3.0 โดยตรง | โมเดลใหม่ *และ* endpoint ใหม่ | | ACE Music | ไม่ได้อยู่ในรายชื่อ | ACE Music v1 | เพิ่มเมื่อ 14 พฤศจิกายน 2026 | สองแถวในนั้นเป็นการอัปเดตเวอร์ชันตามปกติ แต่แถว MiniMax ไม่ใช่: [เพลงของ MiniMax ตอนนี้มี endpoint หลักของตัวเอง](/docs/api-minimax-v1/post-minimax-music-create) แทนที่จะต้องเรียกผ่าน [PixVerse](/docs/api-pixverse-v2/post-pixverse-music-create) endpoint ต่างกัน และการคิดเงินก็ต่างกัน TemPolor เป็นข้อยกเว้นอีกราย เป็นบริการเดียวในหน้านี้ที่แบ่งงานไปยังสอง endpoint ด้วยสองโมเดลที่ต่างกัน: [`POST music/song`](/docs/api-tempolor-v1/post-tempolor-music-song) รัน `v4.8` สำหรับทุกอย่างที่มีเสียงร้อง และ [`POST music/instrumental`](/docs/api-tempolor-v1/post-tempolor-music-instrumental) รัน `i4` สำหรับทุกอย่างที่ไม่มีเสียงร้อง ชื่อโมเดลเก่ายังใช้ได้และถูกส่งต่อไปยังโมเดลใหม่โดยอัตโนมัติ โค้ดเดิมจึงยังทำงานต่อได้ — แต่ก็หมายความว่าคุณอาจใช้โมเดลใหม่อยู่โดยไม่รู้ตัว หรือพลาดโมเดลใหม่ไปเพราะไม่ได้ส่งค่าอะไรเลย ### รายชื่อโมเดลและค่าใช้จ่าย ค่าใช้จ่ายของเพลงหนึ่งเพลงบน API ทางการของผู้สร้างแต่ละราย ([TemPolor](https://platform.tempolor.com/docs/6665893m0), [MiniMax](https://platform.minimax.io/docs/pricing/overview#about-music-models) ซึ่งปิดรับผู้ใช้ใหม่ตั้งแต่ 20 สิงหาคม 2026, [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) ของ Google และ [Mureka](https://platform.mureka.ai/pricing)) และบนแพ็กเกจเว็บไซต์ที่แต่ละโมเดลใช้รันในการทดสอบนี้ (พฤศจิกายน 2026) แต่ละแพ็กเกจให้เครดิตจำนวนหนึ่งต่อเดือน และแต่ละเพลงใช้เครดิตจำนวนตายตัว ราคาต่อเพลงจึงเท่ากับส่วนแบ่งของค่าแพ็กเกจ | โมเดล | API ทางการ | แพ็กเกจรายเดือนบนเว็บไซต์ | ราคาต่อเพลง | |---|---|---|---| | [TemPolor v4.8 / i4](/docs/api-tempolor-v1) | $0.04 (ต่อครั้ง เติมเงินล่วงหน้าตั้งแต่ $100) | TemPolor Ultra $29.99 | $0 / 0 cr (ไม่คิดเงินต่อเพลง) | | [MiniMax Music-3.0](/docs/api-minimax-v1/post-minimax-music-create) | $0.15 (ปิดรับผู้ใช้ใหม่ตั้งแต่ 20 สิงหาคม 2026) | MiniMax Audio Pro $99 (3,000,000 cr/เดือน) | $0.01 / 300 cr (10,000 เพลง/เดือน) | | [Lyria 3.5](/docs/api-flowmusic-v1) | $0.08 (ต่อเพลง) | Flow Music Member $64 (30,000 cr/เดือน) | $0.011 / 5 cr (6,000 เพลง/เดือน) | | [Mureka V9.5](/docs/api-mureka-v1) | $0.15 (เติมเงินล่วงหน้าตั้งแต่ $1,000) | Mureka Premier $30 (20,000 cr/เดือน) | $0.018 / 12 cr (1,666 เพลง/เดือน) | | [ACE Music v1](/docs/api-acemusic-v1) | — | ACE Music Creator $9.90 (1,000 cr/เดือน) | $0.02 / 2 cr (500 เพลง/เดือน) | - เมื่อให้โมเดลเขียนเนื้อเพลงจากพรอมต์ เช่นในรอบที่ 3 และ 4 API ของ Mureka คิด $0.50 แทน $0.15 และ API ของ MiniMax บวกเพิ่ม $0.01 ส่วนผ่าน useapi.net เพลงหนึ่งเพลงราคาเท่าเดิมไม่ว่าแบบใด - เครดิต API ของ TemPolor ราคา[เครดิตละ $0.01 ทุกขนาดแพ็กเกจ](https://platform.tempolor.com/pricing) การซื้อจำนวนมากจึงไม่ทำให้ราคาถูกลง แพ็กเกจที่ใหญ่ขึ้นได้จำนวนงานพร้อมกันเพิ่มขึ้นแทน: ห้าคำขอพร้อมกันที่ $100 สิบคำขอที่ $500 และยี่สิบคำขอที่ $5,000 และระดับนี้ไม่ทบกันหากซื้อแพ็กเกจเดิมซ้ำ TemPolor Ultra รันได้พร้อมกันสิบงาน - โมเดลที่บทความนี้เรียกว่า `v4.8` คือ `tempolor-latest` บน API ของ TemPolor ส่วน `i4` ใช้ชื่อเดิม - แพ็กเกจที่เล็กกว่า เช่น Mureka Pro และ Flow Music Starter มีราคาต่อเพลงสูงขึ้นเล็กน้อย แต่ยังต่ำกว่า API ทางการอยู่มาก - ACE Music ส่งกลับสองเพลงต่อคำขอ และคิด 4 เครดิตต่อคู่ หรือ 2 เครดิตต่อเพลง บน ACE Music Artist ซึ่งราคา $29 ต่อเดือน หรือ $16.58 เมื่อชำระรายปี เพลงหนึ่งเพลงราคา $0.023 หรือราว $0.013 - แพ็กเกจ Google AI รวมแพ็กเกจ Flow Music ไว้ด้วย โดยเครดิตแยกจากเครดิต Google AI: Starter ใน [Google AI Plus](https://support.google.com/googleone/answer/16882689?hl=th), Plus ใน [Google AI Pro](https://support.google.com/googleone/answer/14534406?hl=th) และ Member ใน [Google AI Ultra](https://support.google.com/googleone/answer/16286513?hl=th) useapi.net ทำงานบนแพ็กเกจเว็บไซต์ TemPolor, MiniMax Audio, Flow Music, Mureka หรือ ACE Music ของคุณ และเปิดให้ใช้งานเป็น REST API โดยไม่บวกค่าบริการต่อเพลง โทเค็น API เดียวใช้ได้กับทั้งห้าบริการ — ไม่ต้องใช้ SDK แยกต่อบริการ ไม่ต้องมี API key แยก และไม่ต้องกระทบยอดบิลห้าชุด โทเค็นเดียวกันนี้ยังใช้ได้กับทุกบริการอื่นที่เรารองรับ: วิดีโอ ภาพ เสียงพูด และการสลับใบหน้า ### วิธีที่เราทดสอบ โจทย์หกโจทย์เดียวกับเดือนกรกฎาคม คัดลอกจากบทความที่เผยแพร่แล้วแทนการพิมพ์ใหม่ — เพลงบรรเลงสองโจทย์ เพลงที่มีเสียงร้องซึ่งโมเดลเขียนเนื้อเพลงเองสองโจทย์ และอีกสองโจทย์ที่เราให้ทั้งเนื้อเพลงและคำอธิบายสไตล์อย่างละเอียด ทุกโมเดลในรอบเดียวกันได้รับข้อความที่เหมือนกันทุกตัวอักษร สิ่งที่คุณได้ยินจึงมาจากตัวโมเดลล้วนๆ เนื้อหาคำขอของ TemPolor คัดลอกแบบไบต์ต่อไบต์จากของ MiniMax ซึ่งรับฟิลด์ `prompt` และ `lyrics` เหมือนกัน ACE Music v1 ได้รับข้อความเดียวกัน API ของมันรับได้ทั้ง `prompt` ซึ่งโมเดลจะเขียนสไตล์และเนื้อเพลงเอง หรือ `style` พร้อม `lyrics` ของคุณหรือ `instrumental` และปฏิเสธหากส่งทั้งสองแบบพร้อมกัน รอบที่ 3 และ 4 จึงส่งเป็น `prompt` โจทย์เพลงบรรเลงสองโจทย์ส่งเป็น `style` พร้อม `instrumental: true` และรอบที่ 5 และ 6 ส่งเป็น `style` พร้อม `lyrics` โดยไม่มีชื่อเพลง `duration` หรือ `bpm` เวลาที่ใช้สร้างคือเวลาจริงผ่าน API ที่ความละเอียดการโพล 15 วินาที ให้ถือเป็นตัวเลขคร่าวๆ มากกว่าเบนช์มาร์ก เมื่อดูค่ามัธยฐานของทั้งหกรอบ Lyria 3.5 เร็วที่สุดที่ 58.5 วินาที ตามด้วย ACE Music v1 ที่ 62 วินาที TemPolor ที่ 69.5 วินาที Mureka ที่ 86.5 วินาที และ MiniMax ที่ 158.5 วินาที ในกรณีที่โมเดลตั้งชื่อผลงานเอง เราคงชื่อนั้นไว้ รวมถึงการสะกดและช่องว่างที่เกินมา แทร็กครบถ้วนและไม่ผ่านการตัดต่อ ตรงตามที่แต่ละ API ส่งกลับมา: Mureka สองเพลงต่อการสร้างเป็น MP3 192 kbps, MiniMax หนึ่งเพลงที่ 256 kbps, TemPolor หนึ่งเพลงที่ 48 kHz ราว 230–320 kbps, ACE Music สองเพลงต่อคำขอเป็น MP3 192 kbps 48 kHz และ Flow Music เป็นคู่ A/B แบบ WAV 48 kHz ซึ่งแปลงเป็น MP3 320 kbps เพียงเพื่อให้เบราว์เซอร์เล่นได้ ไฟล์ WAV ต้นฉบับของ Flow มาจาก API โดยตรง แทร็กของ ACE Music ในแต่ละรอบคือเพลงแรกจากสองเพลง โดยไม่มีการคัดเลือก สิ่งที่ควรรู้หากคุณสร้างระบบบน TemPolor: งานเพลงจะรายงาน `status_final: true` และ `COMPLETED` ไม่กี่วินาที*ก่อน*ที่ไฟล์จะดึงได้ และ [`GET music/download/job_id`](/docs/api-tempolor-v1/get-tempolor-music-download-job_id) จะตอบ `404` ในช่วงนั้น สามในสี่รอบที่มีเสียงร้องของเราเจอกรณีนี้ในความพยายามครั้งแรก ให้ถือว่า `404` นั้นหมายถึง "ยังไม่เสร็จ" และโพลต่อไป ไม่ใช่ความล้มเหลว ## ส่วนที่ 1 — เพลงบรรเลง ### รอบที่ 1: บิ๊กแบนด์แนวนัวร์ ``` Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production. ``` TemPolor i4 — "Generic Rhythm Tune" · 3:09 · สร้างใน 103 วินาที <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/instrumental' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model_instrumental="i4"' \ --form 'prompt="Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/01-bigband-noir-tempolor-i4.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Brass Knuckle Boulevard" · 3:19 · สร้างใน 86 วินาที <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-instrumental' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9.5"' \ --form 'prompt="Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/01-bigband-noir-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music-3.0 — "Midnight Operative" · 2:51 · สร้างใน 182 วินาที <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-3.0"' \ --form 'prompt="Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production."' \ --form 'instrumental="true"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/01-bigband-noir-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Double Cross" · 2:52 · สร้างใน 47 วินาที <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'instrumental="true"' \ --form 'prompt="Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/01-bigband-noir-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ACE Music v1 — "Big-band noir action theme" · 2:08 · สร้างใน 52 วินาที <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/acemusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="acemusic-v1"' \ --form 'style="Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production."' \ --form 'instrumental="true"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/01-bigband-noir-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> เวอร์ชันเดือนกรกฎาคมของโจทย์นี้อยู่ใน[หน้าก่อนหน้า](/docs/articles/ai-music-api-comparison#round-1-big-band-noir) (ภาษาอังกฤษ) หากคุณต้องการฟังเทียบกันทีละเพลง ### รอบที่ 2: ลิควิดดรัมแอนด์เบส ``` Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production. ``` TemPolor i4 — " Generic Rhythm Beat" · 3:30 · สร้างใน 69 วินาที <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/instrumental' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model_instrumental="i4"' \ --form 'prompt="Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/02-liquid-dnb-tempolor-i4.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Piano Afterglow" · 3:22 · สร้างใน 85 วินาที <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-instrumental' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9.5"' \ --form 'prompt="Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production."' \ --form 'title="Take B - Liquid DnB"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/02-liquid-dnb-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music-3.0 — "Midnight Flow" · 3:45 · สร้างใน 227 วินาที <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-3.0"' \ --form 'prompt="Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production."' \ --form 'instrumental="true"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/02-liquid-dnb-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Silken Tides" · 1:06 · สร้างใน 59 วินาที <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'prompt="Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production."' \ --form 'instrumental="true"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/02-liquid-dnb-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ACE Music v1 — "Liquid drum and bass instrumental" · 3:10 · สร้างใน 89 วินาที <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/acemusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="acemusic-v1"' \ --form 'style="Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production."' \ --form 'instrumental="true"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/02-liquid-dnb-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> API สี่ตัวเดิมไม่มีตัวไหนมีพารามิเตอร์ความยาว — ทุกโจทย์ขอ "around 60 seconds" เป็นข้อความ ACE Music มีพารามิเตอร์นี้คือ `duration` (30 ถึง 600 วินาที) ซึ่งเราไม่ได้ส่ง เพื่อให้มันอ่านถ้อยคำเดียวกัน Lyria เป็นตัวเดียวในสี่ตัวที่เคยทำตามคำใบ้นี้ และทำเฉพาะในรอบนี้ Lyria 3 Pro ตอบพรอมต์เดียวกันนี้ในเดือนกรกฎาคมด้วยความยาว 2:46 ในสองรอบพรอมต์ด้านล่างซึ่ง ACE Music v1 เขียนสไตล์เอง มันได้ความยาว 0:41 และ 1:22 ใกล้เคียงหนึ่งนาทีที่สุดในรอบเหล่านั้น endpoint เพลงบรรเลงของ TemPolor ยังไม่ได้ตั้งชื่อผลงานจริงๆ ด้วย มันส่งกลับ "Generic Rhythm Tune" และ "Generic Rhythm Beat" สำหรับสองโจทย์นี้ — เป็นชื่อชั่วคราวมากกว่าชื่อเพลง และยังไม่เรียบร้อยด้วย: ชื่อแรกมาพร้อมช่องว่างสองช่องตรงกลาง ชื่อที่สองมีช่องว่างนำหน้า ส่วน endpoint เพลงของมันในสี่รอบถัดไปตั้งชื่อได้ถูกต้อง ACE Music ซึ่งไม่ได้รับชื่อเพลง ตั้งชื่อเพลงบรรเลงทั้งสองด้วยคำแรกๆ ของโจทย์ และตั้งชื่อเพลงในรอบที่ 5 และ 6 ด้วยคำแรกๆ ของเนื้อเพลงของเรา หากคุณจัดเก็บแทร็กตามชื่อ ให้ตั้งชื่อเองสำหรับเพลงบรรเลงและตัดช่องว่างส่วนเกินของสิ่งที่ได้กลับมา หรือส่ง `title` ให้ ACE Music ## ส่วนที่ 2 — เพลงที่มีเสียงร้อง โมเดลเขียนเนื้อเพลงเอง ### รอบที่ 3: ป๊อปดูเอ็ต คำสั่งเพียงประโยคเดียว และเป็นการทดสอบความสามารถโดยเจตนา — เพลงดูเอ็ตจะสำเร็จได้ก็ต่อเมื่อโมเดลจัดวางสองเสียงได้ ``` A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus. ``` TemPolor v4.8 — "Text Me" · 1:51 · สร้างใน 70 วินาที <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/song' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model_song="v4.8"' \ --form 'prompt="A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-tempolor-v4.8.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ฟังบรรทัดแรก TemPolor เขียนเนื้อเพลงเองสำหรับโจทย์นี้ และเขียนโดยใส่แท็กผู้ร้องไว้ในบรรทัด: ``` [Verse] [Male] You sent "you up?" at 1:09 [Female] You said "just one more," then took your time [Male] I saw your typing, then it slipped away [Female] I dropped my phone and missed your "hey" ``` นักร้องของมันตัด `[Verse]` และ `[Chorus]` ออกในฐานะโครงสร้าง แต่ `[Male]` ที่อยู่ในบรรทัดไม่ใช่แท็กที่มันรู้จัก — มันจึงร้องคำว่า "male" และ "female" ออกมาเป็นส่วนหนึ่งของบรรทัด สองส่วนของโมเดลเดียวกันเข้าใจรูปแบบของตัวเองไม่ตรงกัน MiniMax เจอปัญหาเดียวกันทุกประการในโจทย์นี้ และรอดมาได้ด้วยการเขียน `(Male)` และ `(Female)` ในวงเล็บกลม ซึ่งนักร้องของมันตัดออก บทเรียนนี้ใช้ได้กว้างกว่าโมเดลนี้ตัวเดียว ป้ายบทบาทใน `lyrics` ไม่ใช่ฟีเจอร์ API ที่ใช้ได้กับทุกโมเดล หากคุณส่งเนื้อเพลงเองและต้องการสองเสียง ให้ตรวจสอบก่อนว่าโมเดลนั้นทำอะไรกับรูปแบบวงเล็บของคุณ ก่อนจะไว้ใจมัน — หรือไม่ใส่ป้ายเลย แล้วอธิบายการร้องคู่ในพรอมต์สไตล์แทน Mureka V9.5 — "Are You Still Awake?" · 3:05 · สร้างใน 88 วินาที <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9.5"' \ --form 'prompt="A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music-3.0 — "Three Little Dots" · 2:31 · สร้างใน 146 วินาที <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-3.0"' \ --form 'prompt="A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax ตั้งชื่อตามสัญลักษณ์กำลังพิมพ์ และแท็ก `(Male)` / `(Female)` ของมันไม่หลุดเข้าไปในเสียงร้อง Lyria 3.5 — "You Go First" · 1:59 · สร้างใน 74 วินาที <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'prompt="A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria เขียนการร้องโต้ตอบสองเสียงของตัวเอง โดยใส่บรรทัดที่ร้องตอบไว้ในวงเล็บ ACE Music v1 — "Three Dot Bubbles" · 0:41 · สร้างใน 54 วินาที <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/acemusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="acemusic-v1"' \ --form 'prompt="A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ACE Music ก็ตั้งชื่อตามสัญลักษณ์กำลังพิมพ์เช่นกัน และเขียนเพลงดูเอ็ตด้วย `(Male)`, `(Female)` และ `(Both)` ในวงเล็บกลม เหมือนที่ MiniMax ทำ ### รอบที่ 4: ฟลาเมงโกป๊อปภาษาสเปน การทดสอบด้านภาษา — พรอมต์เป็นภาษาอังกฤษ แต่เพลงไม่ควรเป็นภาษาอังกฤษ: ``` A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals. ``` TemPolor v4.8 — "Lluvia" · 2:58 · สร้างใน 102 วินาที <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/song' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model_song="v4.8"' \ --form 'prompt="A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/04-spanish-flamenco-tempolor-v4.8.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Agua de Julio" · 3:32 · สร้างใน 87 วินาที <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9.5"' \ --form 'prompt="A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/04-spanish-flamenco-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music-3.0 — "Tacones de Lluvia" · 3:07 · สร้างใน 171 วินาที <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-3.0"' \ --form 'prompt="A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/04-spanish-flamenco-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Lluvia de Verano" · 2:33 · สร้างใน 73 วินาที <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'prompt="A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/04-spanish-flamenco-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ACE Music v1 — "Fuego en la Tormenta" · 1:22 · สร้างใน 70 วินาที <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/acemusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="acemusic-v1"' \ --form 'prompt="A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/04-spanish-flamenco-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ทั้งห้าตัวเขียนเนื้อเพลงภาษาสเปนจากพรอมต์ภาษาอังกฤษ และทั้งห้าตัวตั้งชื่อแทร็กเป็นภาษาสเปนโดยไม่ต้องขอ เอกสารของ TemPolor ระบุว่า v4.8 รองรับ[กว่า 30 ภาษา](/docs/api-tempolor-v1) โจทย์ภาษาสเปนโจทย์เดียวไม่ได้ทดสอบทั้งสามสิบภาษา แต่มันตอบโจทย์นี้ด้วยภาษาที่ถูกต้อง และตั้งชื่อว่า "Lluvia" เองโดยไม่ต้องบอก ## ส่วนที่ 3 — เพลงที่มีเสียงร้อง เนื้อเพลงของเราและคำอธิบายสไตล์อย่างละเอียด สำหรับรูปแบบสุดท้าย แต่ละโมเดลได้รับเนื้อเพลงต้นฉบับชุดเดียวกันพร้อมคำอธิบายการผลิตอย่างละเอียด Mureka รับข้อมูลนี้ผ่าน [music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced) (`lyrics` + สไตล์ `desc` คั่นด้วยจุลภาค + `vocal_gender`) ขณะที่ MiniMax, Flow Music และ TemPolor รับฟิลด์ `lyrics` คู่กับพรอมต์สไตล์ เนื้อหาคำขอเดียวกันจึงใช้ได้กับสามในสี่ตัวโดยไม่ต้องแก้ไข ส่วน ACE Music รับข้อความสองชุดเดียวกันเป็น `style` และ `lyrics` ### รอบที่ 5: ดีพเฮาส์ ``` [Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go) ``` ``` Deep house at 121 BPM. Rolling sub-bass groove, shuffled hi-hats, warm Rhodes chord stabs, subtle chopped vocal echoes, smoky intimate female lead vocal, understated hypnotic late-night club production. ``` TemPolor v4.8 — "Low Light" · 1:28 · สร้างใน 51 วินาที <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/song' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model_song="v4.8"' \ --form 'prompt="Deep house at 121 BPM. Rolling sub-bass groove, shuffled hi-hats, warm Rhodes chord stabs, subtle chopped vocal echoes, smoky intimate female lead vocal, understated hypnotic late-night club production."' \ --form 'lyrics="[Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go)"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-tempolor-v4.8.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Low Light" · 3:09 · สร้างใน 101 วินาที <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-advanced' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9.5"' \ --form 'lyrics="[Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go)"' \ --form 'desc="deep house, late night, smoky, hypnotic, groovy, 121 bpm, female vocals, warm, understated club production"' \ --form 'vocal_gender="female"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music-3.0 — "Low Light" · 2:47 · สร้างใน 135 วินาที <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-3.0"' \ --form 'prompt="Deep house at 121 BPM. Rolling sub-bass groove, shuffled hi-hats, warm Rhodes chord stabs, subtle chopped vocal echoes, smoky intimate female lead vocal, understated hypnotic late-night club production."' \ --form 'lyrics="[Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go)"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Velvet Room" · 2:26 · สร้างใน 43 วินาที <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'prompt="Deep house at 121 BPM. Rolling sub-bass groove, shuffled hi-hats, warm Rhodes chord stabs, subtle chopped vocal echoes, smoky intimate female lead vocal, understated hypnotic late-night club production."' \ --form 'lyrics="[Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go)"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ACE Music v1 — "Two shadows in a velvet" · 1:53 · สร้างใน 52 วินาที <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/acemusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="acemusic-v1"' \ --form 'style="Deep house at 121 BPM. Rolling sub-bass groove, shuffled hi-hats, warm Rhodes chord stabs, subtle chopped vocal echoes, smoky intimate female lead vocal, understated hypnotic late-night club production."' \ --form 'lyrics="[Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go)"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ### รอบที่ 6: แจ๊ซซีเฮาส์ดูเอ็ต โจทย์ที่ยากที่สุดในชุด — การเรียบเรียงสองเสียงพร้อมเลเยอร์แจ๊ซสดบนจังหวะเฮาส์ โดยแท็กบทบาทเสียงไว้ในเนื้อเพลง แท็กเป็นเพียงคำใบ้ ไม่ใช่พารามิเตอร์ของ API ลองฟังว่าโมเดลไหนสลับกันร้องท่อน verse จริงๆ และโมเดลไหนรวบให้เหลือนักร้องคนเดียว ``` [Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound ``` TemPolor v4.8 — "Blue Hour" · 2:09 · สร้างใน 69 วินาที <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/song' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model_song="v4.8"' \ --form 'prompt="Jazzy deep house duet at 120 BPM. Rolling deep-house groove with swung hi-hats, walking upright-bass motif over the sub, smoky muted trumpet and tenor-sax licks answering the vocals, extended jazz piano chords, a male and a female lead trading verses and joining in harmony on the chorus, small backing ensemble echoing the hook, warm vinyl texture, sophisticated late-night club production."' \ --form 'lyrics="[Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-tempolor-v4.8.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Blue Hour" · 3:12 · สร้างใน 70 วินาที <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-advanced' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9.5"' \ --form 'lyrics="[Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound"' \ --form 'desc="jazzy deep house, jazz house, duet, male and female vocals, group backing vocals, muted trumpet, saxophone, upright bass, swung, 120 bpm, late night, warm sophisticated production"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music-3.0 — "Blue Hour" · 2:18 · สร้างใน 134 วินาที <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-3.0"' \ --form 'prompt="Jazzy deep house duet at 120 BPM. Rolling deep-house groove with swung hi-hats, walking upright-bass motif over the sub, smoky muted trumpet and tenor-sax licks answering the vocals, extended jazz piano chords, a male and a female lead trading verses and joining in harmony on the chorus, small backing ensemble echoing the hook, warm vinyl texture, sophisticated late-night club production."' \ --form 'lyrics="[Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Blue Hour" · 2:34 · สร้างใน 58 วินาที <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'prompt="Jazzy deep house duet at 120 BPM. Rolling deep-house groove with swung hi-hats, walking upright-bass motif over the sub, smoky muted trumpet and tenor-sax licks answering the vocals, extended jazz piano chords, a male and a female lead trading verses and joining in harmony on the chorus, small backing ensemble echoing the hook, warm vinyl texture, sophisticated late-night club production."' \ --form 'lyrics="[Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ACE Music v1 — "Blue hour settles on the" · 3:05 · สร้างใน 70 วินาที <details markdown="block"> <summary><b>แสดงการเรียก API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/acemusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="acemusic-v1"' \ --form 'style="Jazzy deep house duet at 120 BPM. Rolling deep-house groove with swung hi-hats, walking upright-bass motif over the sub, smoky muted trumpet and tenor-sax licks answering the vocals, extended jazz piano chords, a male and a female lead trading verses and joining in harmony on the chorus, small backing ensemble echoing the hook, warm vinyl texture, sophisticated late-night club production."' \ --form 'lyrics="[Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> เมื่อให้เนื้อเพลงไปแล้ว อีกสี่ตัวตั้งชื่อเพลงจากฮุกของท่อนคอรัส ขณะที่ ACE Music ใช้คำแรกๆ ของเนื้อเพลง สังเกตว่าป้ายบทบาทในรอบนี้อยู่ในหัวท่อน — `[Verse 1 - male]` — แทนที่จะอยู่เดี่ยวๆ ที่ต้นบรรทัด ซึ่งเป็นรูปแบบที่โมเดลมองว่าเป็นโครงสร้าง ## คำถามที่พบบ่อย **เพลงหนึ่งเพลงผ่าน useapi.net ราคาเท่าไร?** ผ่าน useapi.net ราว $0.01 ถึง $0.02: เพลง Music-3.0 ราว $0.01 บน MiniMax Audio Pro เพลง Lyria 3.5 $0.011 บน Flow Music Member เพลง Mureka V9.5 $0.018 บน Mureka Premier และเพลง ACE Music v1 $0.02 บน ACE Music Creator ส่วน API ทางการคิด $0.15 บน [MiniMax](https://platform.minimax.io/docs/pricing/overview#about-music-models) (ปิดรับผู้ใช้ใหม่ตั้งแต่ 20 สิงหาคม 2026) $0.08 บน [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) ของ Google และ $0.15 บน [Mureka](https://platform.mureka.ai/pricing) แบบเติมเงินล่วงหน้าตั้งแต่ $1,000 (ข้อมูล ณ พฤศจิกายน 2026) ดูที่[รายชื่อโมเดลและค่าใช้จ่าย](#the-lineup-and-what-it-costs) **ตัวไหนถูกที่สุดเมื่อใช้ปริมาณมาก?** ผ่าน useapi.net คือ TemPolor โดย TemPolor Ultra ราคาคงที่ $29.99 ต่อเดือน ไม่คิดเงินต่อเพลง ยิ่งสร้างมาก ราคาต่อเพลงยิ่งถูก: ราว $0.03 ที่ 1,000 เพลงต่อเดือน และ $0.015 ที่ 2,000 เพลง ส่วน API ของ TemPolor เองคิด [$0.04 ต่อครั้ง](https://platform.tempolor.com/docs/6665893m0) จาก[แพ็กเกจเติมเงินล่วงหน้า $100](https://platform.tempolor.com/pricing) ดังนั้น 1,000 เพลงที่นั่นมีค่าใช้จ่าย $40 ไม่ว่าจะใช้ปริมาณเท่าใด (ข้อมูล ณ พฤศจิกายน 2026) **ใช้ทั้งห้าตัวด้วยโทเค็นเดียวได้ไหม?** ผ่าน useapi.net ได้ โทเค็น API เดียวใช้ได้กับ [TemPolor](/docs/api-tempolor-v1), [Mureka](/docs/api-mureka-v1), [MiniMax](/docs/api-minimax-v1), [Flow Music](/docs/api-flowmusic-v1) และ [ACE Music](/docs/api-acemusic-v1) รวมถึงทุกบริการอื่นที่เรารองรับ คุณเชื่อมต่อแพ็กเกจเว็บไซต์ของแต่ละบริการเพียงครั้งเดียว เนื้อหาคำขอก็ใช้ต่อกันได้ด้วย เพราะ TemPolor รับฟิลด์ `prompt` และ `lyrics` เหมือน MiniMax และ ACE Music รับข้อความชุดเดียวกันเป็น `style` และ `lyrics` **จะเลือกใช้โมเดลใหม่ล่าสุดได้อย่างไร?** ผ่าน useapi.net โมเดลใหม่ล่าสุดของ TemPolor เป็นค่าเริ่มต้นอยู่แล้ว: `v4.8` บน [POST music/song](/docs/api-tempolor-v1/post-tempolor-music-song) ผ่าน `model_song` และ `i4` บน [POST music/instrumental](/docs/api-tempolor-v1/post-tempolor-music-instrumental) ผ่าน `model_instrumental` โดยชื่อโมเดลเก่าจะถูกส่งต่อไปยังโมเดลเหล่านี้ Lyria เป็นข้อยกเว้น: ให้ส่ง `model: "lyria-3.5"` บน [POST /music](/docs/api-flowmusic-v1/post-flowmusic-music) เพราะ `lyria-3-pro` ยังเป็นค่าเริ่มต้นของ Flow Music ระบุโมเดลให้ชัดเจนหากโค้ดของคุณต้องบันทึกว่าโมเดลไหนสร้างแทร็กใด **ได้มากกว่าหนึ่งแทร็กต่อการเรียกหนึ่งครั้งไหม?** ผ่าน useapi.net ได้ในสี่จากห้าตัว MiniMax รับ `quantity` ได้สูงสุด 3 และคิดเงินเป็นสามเพลง Mureka ส่งกลับสองเพลงต่อการสร้าง และ Flow Music ได้คู่ A/B ทั้งคู่ในราคาของการสร้างครั้งเดียว ส่วน ACE Music ได้สองเพลงต่อคำขอ 4 เครดิตต่อคู่ TemPolor ส่งกลับหนึ่งแทร็กต่อการเรียกตลอดการทดสอบนี้ และรันได้พร้อมกันสูงสุดสิบงานบนบัญชีเดียว #### เผยแพร่ที่อื่นด้วย {: .no_toc #cross-posted } เผยแพร่บน [dev.to](https://dev.to/useapi/ai-music-apis-one-generation-later-minimax-music-30-vs-lyria-35-vs-mureka-v95-365p){:rel="nofollow"} (ภาษาอังกฤษ) มีการพูดคุยบน [Reddit](https://www.reddit.com/r/ThirdPartyAPI/comments/1wq8jon/four_ai_music_apis_compared_tempolor_v48_minimax/){:rel="nofollow"} (ภาษาอังกฤษ) แชร์บน [Bluesky](https://bsky.app/profile/useapi.net/post/3mweqttv6bf2e){:rel="nofollow"} และบน [YouTube](https://youtu.be/MSUGckk4JqU) เป็นคลิปฟังยาว 15 นาที (ภาษาอังกฤษ) รอบก่อนหน้า: [AI Music APIs Compared](/docs/articles/ai-music-api-comparison) (ภาษาอังกฤษ) ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/ai-music-flagships-compared-vi === Document URL: https://useapi.net/docs/articles/ai-music-flagships-compared-vi --- layout: default title: "Năm API nhạc AI trên cùng sáu đề bài: ACE Music v1, TemPolor v4.8, MiniMax Music-3.0, Lyria 3.5 và Mureka V9.5" description: "Năm model nhạc AI — ACE Music v1, TemPolor v4.8 và i4, MiniMax Music-3.0, Lyria 3.5 của Google và Mureka V9.5 — nhận cùng sáu đề bài qua các API của useapi.net, kèm mọi bản nhạc, lệnh gọi API chính xác đằng sau từng bản, thời gian tạo và chi phí mỗi bài hát trên gói đăng ký website so với các API chính thức." keywords: [AI music API, TemPolor API, TemPolor v4.8, MiniMax Music-3.0 API, Lyria 3.5 API, Mureka V9.5 API, ACE Music API, ACE Music v1 API, AI music API comparison, music generation API, text to music API, AI music API pricing, API nhạc AI, so sánh API nhạc AI, API tạo nhạc, tạo nhạc từ văn bản, giá API nhạc AI] image: /assets/images/articles/ai-music-flagships-compared.jpg video: name: "Năm API nhạc AI trên cùng sáu đề bài" description: "ACE Music v1, TemPolor v4.8 và i4, MiniMax Music-3.0, Google Lyria 3.5 và Mureka V9.5 trên cùng sáu đề bài, mỗi bản nhạc lấy 30 giây to nhất, cân bằng âm lượng, kèm prompt, giá và thời gian tạo trên màn hình." embed: https://www.youtube.com/embed/MSUGckk4JqU thumbnail: https://i.ytimg.com/vi/MSUGckk4JqU/maxresdefault.jpg date: 2026-11-14 duration: PT15M width: 1920 height: 1080 parent: Articles nav_exclude: true lang: vi translation_key: ai-music-flagships date: 2026-08-19 last_modified: 2026-11-18 nav_order: 96 --- ## Năm API nhạc AI trên cùng sáu đề bài: ACE Music v1, TemPolor v4.8, MiniMax Music-3.0, Lyria 3.5 và Mureka V9.5 {: .no_toc #five-ai-music-apis-on-the-same-six-briefs-ace-music-v1-tempolor-v48-minimax-music-30-lyria-35-and-mureka-v95 } 13 phút đọc • 19 tháng 8 năm 2026 (18 tháng 11 năm 2026) ## Mục lục {: .no_toc .text-delta #table-of-contents } ### Giới thiệu TemPolor v4.8, MiniMax Music-3.0, Lyria 3.5 của Google và Mureka V9.5 — bốn model nhạc AI, cùng sáu đề bài, một API token [useapi.net](/docs/subscription). Cả 24 bản nhạc đều ở bên dưới, đầy đủ và không chỉnh sửa, mỗi bản kèm lệnh gọi API đã tạo ra nó. Đây là những đề bài chúng tôi đã dùng hồi tháng 7, nên mỗi bản nhạc ở đây đều có một bản tiền nhiệm để so sánh trong [So sánh các API nhạc AI](/docs/articles/ai-music-api-comparison). Ngày 14 tháng 11 năm 2026, ba tháng sau các model kia, chúng tôi chạy đúng sáu đề bài đó trên ACE Music v1, model đứng hạng 1 trên [bảng xếp hạng nhạc có giọng hát của Artificial Analysis](https://artificialanalysis.ai/music/leaderboard/vocals), trên cả Suno v6. Bài hát của nó khép lại mỗi vòng bên dưới, nâng tổng số bản nhạc trên trang lên 30. TemPolor, mới có mặt từ sau tháng 7, tính giá khác với mọi dịch vụ còn lại ở đây: một mức giá cố định hằng tháng, không tính phí theo bài hát. Chi phí mỗi bài hát nằm ở [bên dưới](#the-lineup-and-what-it-costs). Hãy nghe trước và tự đánh giá các model. Không có nhiều thời gian? Còn có một <a href="https://youtu.be/MSUGckk4JqU"><img style="height:1em;vertical-align: middle;" src="/assets/images/youtube.svg" alt=""> video YouTube dài 15 phút</a> — 30 giây to nhất của cả năm model trên mọi đề bài, phát liền nhau và đã cân bằng âm lượng, kèm prompt, giá và thời gian tạo trên màn hình (giá tính đến tháng 11/2026). Các bản nhạc đầy đủ và lệnh gọi API chính xác đằng sau từng bản nằm trên trang này. Vòng thử trước đó với ba model cũng có trên YouTube: [AI Music APIs One Generation Later: MiniMax Music-3.0 vs Lyria 3.5 vs Mureka V9.5](https://www.youtube.com/watch?v=9AM5p-A9oFM). ### Những gì đã thay đổi từ tháng 7 | Dịch vụ | Tháng 7 | Hiện tại | Thay đổi | |---|---|---|---| | TemPolor | chưa có trong danh sách | v4.8 (bài hát) + i4 (nhạc không lời) | mới trong phép so sánh này, và hai model mới | | Mureka | V9 | V9.5 | model mặc định mới | | Flow Music | Lyria 3 Pro | Lyria 3.5 | flagship mới — nhưng 3 Pro vẫn là mặc định của API | | MiniMax | music-2.6 qua PixVerse | Music-3.0, trực tiếp | model mới *và* endpoint mới | | ACE Music | chưa có trong danh sách | ACE Music v1 | thêm vào ngày 14 tháng 11 năm 2026 | Hai trong số đó chỉ là những lần nâng phiên bản thông thường. Dòng MiniMax thì không: [nhạc MiniMax giờ là một endpoint riêng đầy đủ](/docs/api-minimax-v1/post-minimax-music-create) thay vì thứ bạn phải đi vòng qua [PixVerse](/docs/api-pixverse-v2/post-pixverse-music-create). Endpoint khác, cách tính phí khác. TemPolor là ngoại lệ còn lại. Đây là dịch vụ duy nhất ở đây chia công việc ra hai endpoint với hai model khác nhau: [`POST music/song`](/docs/api-tempolor-v1/post-tempolor-music-song) chạy `v4.8` cho mọi thứ có giọng hát, và [`POST music/instrumental`](/docs/api-tempolor-v1/post-tempolor-music-instrumental) chạy `i4` cho mọi thứ không có. Tên model cũ vẫn hoạt động và được tự động chuyển sang model mới, nên code hiện có vẫn chạy — nhưng điều đó cũng có nghĩa là bạn có thể đang dùng model mới mà không hay biết, hoặc bỏ lỡ chúng vì không truyền gì cả. ### Danh sách model và chi phí Chi phí một bài hát trên API chính thức của từng nhà sản xuất ([TemPolor](https://platform.tempolor.com/docs/6665893m0), [MiniMax](https://platform.minimax.io/docs/pricing/overview#about-music-models), đóng với người dùng mới từ ngày 20 tháng 8 năm 2026, [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) của Google và [Mureka](https://platform.mureka.ai/pricing)) và trên gói đăng ký website mà mỗi model đã chạy trong bài thử này (tháng 11/2026). Mỗi gói đăng ký đi kèm một số credit hằng tháng, và mỗi bài hát dùng một số credit cố định, nên một bài hát tốn đúng phần tương ứng của gói đăng ký. | Model | API chính thức | Gói đăng ký website hằng tháng | Giá mỗi bài hát | |---|---|---|---| | [TemPolor v4.8 / i4](/docs/api-tempolor-v1) | $0,04 (một lần gọi, trả trước từ $100) | TemPolor Ultra $29,99 | $0 / 0 cr (không tính phí theo bài) | | [MiniMax Music-3.0](/docs/api-minimax-v1/post-minimax-music-create) | $0,15 (đóng với người dùng mới từ 20/8/2026) | MiniMax Audio Pro $99 (3.000.000 cr/tháng) | $0,01 / 300 cr (10.000 bài/tháng) | | [Lyria 3.5](/docs/api-flowmusic-v1) | $0,08 (mỗi bài) | Flow Music Member $64 (30.000 cr/tháng) | $0,011 / 5 cr (6.000 bài/tháng) | | [Mureka V9.5](/docs/api-mureka-v1) | $0,15 (trả trước từ $1.000) | Mureka Premier $30 (20.000 cr/tháng) | $0,018 / 12 cr (1.666 bài/tháng) | | [ACE Music v1](/docs/api-acemusic-v1) | — | ACE Music Creator $9,90 (1.000 cr/tháng) | $0,02 / 2 cr (500 bài/tháng) | - Khi model tự viết lời từ một prompt, như ở vòng 3 và 4, API của Mureka tính $0,50 thay vì $0,15 và API của MiniMax cộng thêm $0,01, trong khi qua useapi.net một bài hát có giá như nhau trong cả hai trường hợp. - Credit API của TemPolor có giá [$0,01 mỗi credit ở mọi gói](https://platform.tempolor.com/pricing), nên mua nhiều không bao giờ làm giá giảm. Các gói lớn hơn mua thêm khả năng chạy song song: năm request cùng lúc ở gói $100, mười ở gói $500 và hai mươi ở gói $5.000, và mức này không cộng dồn nếu bạn mua cùng một gói hai lần. TemPolor Ultra chạy mười lượt tạo cùng lúc. - Model mà bài viết này gọi là `v4.8` có tên `tempolor-latest` trên API của TemPolor. `i4` giữ nguyên tên. - Các gói nhỏ hơn, như Mureka Pro và Flow Music Starter, tốn hơn một chút mỗi bài nhưng vẫn rẻ hơn hẳn các API chính thức. - ACE Music trả về hai bài hát mỗi request và tính 4 credit cho cả cặp, tức 2 credit một bài. Trên ACE Music Artist, $29 một tháng hoặc $16,58 khi trả theo năm, một bài hát tốn $0,023 hoặc khoảng $0,013. - Các gói Google AI có kèm một gói Flow Music, với credit tách riêng khỏi credit Google AI: Starter trên [Google AI Plus](https://support.google.com/googleone/answer/16882689?hl=vi), Plus trên [Google AI Pro](https://support.google.com/googleone/answer/14534406?hl=vi) và Member trên [Google AI Ultra](https://support.google.com/googleone/answer/16286513?hl=vi). useapi.net chạy trên gói đăng ký website TemPolor, MiniMax Audio, Flow Music, Mureka hoặc ACE Music của bạn và cung cấp nó dưới dạng REST API, không tính phụ phí theo bài hát. Một API token dùng được với cả năm dịch vụ — không cần SDK riêng cho từng dịch vụ, không cần API key riêng, không phải đối soát năm hóa đơn khác nhau. Cùng token đó dùng được với mọi dịch vụ khác chúng tôi hỗ trợ: video, hình ảnh, giọng nói, hoán đổi khuôn mặt. ### Cách chúng tôi thử nghiệm Vẫn sáu đề bài như tháng 7, sao chép từ bài viết đã đăng thay vì gõ lại — hai bản nhạc không lời, hai bản có giọng hát mà model tự viết lời, và hai bản mà chúng tôi cung cấp cả lời lẫn một mô tả phong cách chi tiết. Mọi model trong một vòng nhận đúng cùng một đoạn văn bản, nên những gì bạn nghe là của chính model. Phần body của TemPolor được sao chép từng byte từ body của MiniMax, vốn nhận cùng các trường `prompt` và `lyrics`. ACE Music v1 nhận cùng văn bản đó. API của nó nhận hoặc một `prompt`, từ đó nó tự viết phong cách và lời, hoặc một `style` kèm `lyrics` của bạn hoặc `instrumental`, và từ chối khi có cả hai cùng lúc. Vì vậy vòng 3 và 4 được gửi dưới dạng `prompt`, hai đề bài không lời dưới dạng `style` với `instrumental: true`, còn vòng 5 và 6 dưới dạng `style` cộng `lyrics`, không có title, `duration` hay `bpm`. Thời gian tạo là thời gian thực đo qua API với chu kỳ polling 15 giây, nên hãy coi chúng là con số ước lượng chứ không phải benchmark. Theo trung vị qua sáu vòng, Lyria 3.5 nhanh nhất với 58,5 giây, tiếp theo là ACE Music v1 với 62 giây, TemPolor 69,5 giây, Mureka 86,5 giây và MiniMax 158,5 giây. Khi một model tự đặt tên cho bản nhạc, chúng tôi giữ nguyên tên đó, kể cả lỗi chính tả và khoảng trắng thừa. Các bản nhạc đầy đủ và không chỉnh sửa, đúng như mỗi API trả về: Mureka hai bài mỗi lượt tạo dạng MP3 192 kbps, MiniMax một bài ở 256 kbps, TemPolor một bài ở 48 kHz và khoảng 230–320 kbps, ACE Music hai bài mỗi request dạng MP3 192 kbps, 48 kHz, còn Flow Music một cặp A/B dạng WAV 48 kHz, được chuyển sang MP3 320 kbps chỉ để trình duyệt phát được. Bản WAV gốc của Flow lấy thẳng từ API. Bài của ACE Music trong mỗi vòng là bài đầu tiên trong hai bài, không chọn lọc. Một điều cần lường trước nếu bạn xây dựng với TemPolor: một job bài hát báo `status_final: true` và `COMPLETED` vài giây *trước khi* file của nó tải về được, và [`GET music/download/job_id`](/docs/api-tempolor-v1/get-tempolor-music-download-job_id) trả về `404` trong khoảng đó. Ba trong bốn vòng có giọng hát của chúng tôi gặp tình huống này ở lần thử đầu tiên. Hãy coi `404` đó là "chưa xong" và tiếp tục polling thay vì coi là thất bại. ## Phần 1 — Nhạc không lời ### Vòng 1: big-band noir ``` Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production. ``` TemPolor i4 — "Generic Rhythm Tune" · 3:09 · tạo trong 103 giây <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/instrumental' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model_instrumental="i4"' \ --form 'prompt="Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/01-bigband-noir-tempolor-i4.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Brass Knuckle Boulevard" · 3:19 · tạo trong 86 giây <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-instrumental' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9.5"' \ --form 'prompt="Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/01-bigband-noir-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music-3.0 — "Midnight Operative" · 2:51 · tạo trong 182 giây <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-3.0"' \ --form 'prompt="Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production."' \ --form 'instrumental="true"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/01-bigband-noir-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Double Cross" · 2:52 · tạo trong 47 giây <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'instrumental="true"' \ --form 'prompt="Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/01-bigband-noir-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ACE Music v1 — "Big-band noir action theme" · 2:08 · tạo trong 52 giây <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/acemusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="acemusic-v1"' \ --form 'style="Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production."' \ --form 'instrumental="true"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/01-bigband-noir-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Các phiên bản tháng 7 của đề bài này nằm trên [trang trước](/docs/articles/ai-music-api-comparison#round-1-big-band-noir) nếu bạn muốn nghe chúng liền nhau. ### Vòng 2: liquid drum and bass ``` Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production. ``` TemPolor i4 — " Generic Rhythm Beat" · 3:30 · tạo trong 69 giây <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/instrumental' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model_instrumental="i4"' \ --form 'prompt="Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/02-liquid-dnb-tempolor-i4.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Piano Afterglow" · 3:22 · tạo trong 85 giây <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-instrumental' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9.5"' \ --form 'prompt="Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production."' \ --form 'title="Take B - Liquid DnB"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/02-liquid-dnb-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music-3.0 — "Midnight Flow" · 3:45 · tạo trong 227 giây <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-3.0"' \ --form 'prompt="Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production."' \ --form 'instrumental="true"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/02-liquid-dnb-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Silken Tides" · 1:06 · tạo trong 59 giây <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'prompt="Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production."' \ --form 'instrumental="true"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/02-liquid-dnb-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ACE Music v1 — "Liquid drum and bass instrumental" · 3:10 · tạo trong 89 giây <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/acemusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="acemusic-v1"' \ --form 'style="Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production."' \ --form 'instrumental="true"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/02-liquid-dnb-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Không API nào trong bốn API ban đầu có tham số thời lượng — mọi đề bài đều yêu cầu "khoảng 60 giây" bằng lời. ACE Music có một tham số như vậy, `duration` (30 đến 600 giây), nhưng chúng tôi bỏ qua để nó đọc cùng những từ đó. Lyria là model duy nhất trong bốn model từng làm theo gợi ý này, và chỉ ở vòng này. Lyria 3 Pro trả lời cùng prompt này hồi tháng 7 với 2:46. Ở hai vòng prompt bên dưới, nơi ACE Music v1 tự viết phong cách, nó cho ra 0:41 và 1:22, gần một phút nhất trong các vòng đó. Endpoint nhạc không lời của TemPolor cũng không thực sự đặt tên cho bản nhạc. Nó trả về "Generic Rhythm Tune" và "Generic Rhythm Beat" cho hai đề bài này — tên giữ chỗ chứ không phải tiêu đề, và cũng chẳng gọn gàng: tên thứ nhất có hai khoảng trắng ở giữa, tên thứ hai có một khoảng trắng ở đầu. Endpoint bài hát của nó, ở bốn vòng tiếp theo, đặt tên đàng hoàng. ACE Music, khi không được gửi title, đặt tên cả hai bản nhạc không lời bằng những từ đầu tiên của đề bài, và các bài hát ở vòng 5 và 6 bằng những từ đầu tiên trong lời của chúng tôi. Nếu bạn sắp xếp bản nhạc theo tên, hãy tự tạo tên cho bản nhạc không lời và cắt khoảng trắng thừa ở bất kỳ tên nào trả về, hoặc gửi cho ACE Music một `title`. ## Phần 2 — Có giọng hát, model tự viết lời ### Vòng 3: song ca pop Một câu chỉ dẫn, và là một phép thử năng lực có chủ đích — song ca chỉ thành công nếu model dàn dựng được hai giọng. ``` A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus. ``` TemPolor v4.8 — "Text Me" · 1:51 · tạo trong 70 giây <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/song' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model_song="v4.8"' \ --form 'prompt="A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-tempolor-v4.8.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Hãy nghe câu đầu tiên. TemPolor tự viết lời cho đề bài này, và viết kèm nhãn người hát ngay trong dòng: ``` [Verse] [Male] You sent "you up?" at 1:09 [Female] You said "just one more," then took your time [Male] I saw your typing, then it slipped away [Female] I dropped my phone and missed your "hey" ``` Phần hát của nó bỏ `[Verse]` và `[Chorus]` vì đó là thẻ cấu trúc, nhưng `[Male]` nằm trong dòng thì không phải thẻ nó nhận ra — nên nó hát luôn các từ "male" và "female" như một phần của câu. Hai nửa của cùng một model không thống nhất về định dạng của chính nó. MiniMax gặp đúng vấn đề này với đề bài này và thoát được nhờ viết `(Male)` và `(Female)` trong ngoặc tròn, thứ mà phần hát của nó có bỏ đi. Bài học này đúng với cả những model khác. Nhãn vai trong `lyrics` không phải là tính năng API dùng chung được giữa các model, nên nếu bạn tự cung cấp lời và muốn hai giọng, hãy kiểm tra xem một model cụ thể xử lý kiểu ngoặc của bạn thế nào trước khi tin tưởng nó — hoặc bỏ nhãn đi và mô tả màn song ca trong prompt phong cách. Mureka V9.5 — "Are You Still Awake?" · 3:05 · tạo trong 88 giây <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9.5"' \ --form 'prompt="A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music-3.0 — "Three Little Dots" · 2:31 · tạo trong 146 giây <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-3.0"' \ --form 'prompt="A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax đặt tên theo dấu hiệu đang gõ tin nhắn, và các thẻ `(Male)` / `(Female)` của nó không lọt vào phần hát. Lyria 3.5 — "You Go First" · 1:59 · tạo trong 74 giây <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'prompt="A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria tự viết màn hát đối đáp hai giọng, với các câu đáp nằm trong ngoặc đơn. ACE Music v1 — "Three Dot Bubbles" · 0:41 · tạo trong 54 giây <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/acemusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="acemusic-v1"' \ --form 'prompt="A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ACE Music cũng đặt tên theo dấu hiệu đang gõ tin nhắn, và viết màn song ca với `(Male)`, `(Female)` và `(Both)` trong ngoặc tròn, giống như MiniMax. ### Vòng 4: flamenco-pop tiếng Tây Ban Nha Phép thử ngôn ngữ — prompt bằng tiếng Anh, còn bài hát thì không: ``` A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals. ``` TemPolor v4.8 — "Lluvia" · 2:58 · tạo trong 102 giây <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/song' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model_song="v4.8"' \ --form 'prompt="A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/04-spanish-flamenco-tempolor-v4.8.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Agua de Julio" · 3:32 · tạo trong 87 giây <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9.5"' \ --form 'prompt="A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/04-spanish-flamenco-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music-3.0 — "Tacones de Lluvia" · 3:07 · tạo trong 171 giây <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-3.0"' \ --form 'prompt="A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/04-spanish-flamenco-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Lluvia de Verano" · 2:33 · tạo trong 73 giây <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'prompt="A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/04-spanish-flamenco-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ACE Music v1 — "Fuego en la Tormenta" · 1:22 · tạo trong 70 giây <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/acemusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="acemusic-v1"' \ --form 'prompt="A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/04-spanish-flamenco-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Cả năm model đều viết lời tiếng Tây Ban Nha từ một prompt tiếng Anh, và cả năm đều đặt tên bản nhạc bằng tiếng Tây Ban Nha mà không cần yêu cầu. Theo tài liệu, v4.8 của TemPolor hỗ trợ [hơn 30 ngôn ngữ](/docs/api-tempolor-v1). Một đề bài tiếng Tây Ban Nha không kiểm chứng được cả ba mươi ngôn ngữ, nhưng nó đã trả lời đề bài này đúng ngôn ngữ và tự đặt tên "Lluvia". ## Phần 3 — Có giọng hát, lời của chúng tôi và mô tả phong cách chi tiết Ở định dạng cuối cùng, mỗi model nhận cùng một bộ lời gốc cộng với một mô tả sản xuất chi tiết. Mureka nhận chúng qua [music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced) (`lyrics` + một `desc` phong cách phân tách bằng dấu phẩy + `vocal_gender`), còn MiniMax, Flow Music và TemPolor đều nhận một trường `lyrics` bên cạnh prompt phong cách, nên cùng một body dùng được trên ba trong bốn dịch vụ mà không phải sửa. ACE Music nhận cùng hai đoạn văn bản dưới dạng `style` và `lyrics`. ### Vòng 5: deep house ``` [Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go) ``` ``` Deep house at 121 BPM. Rolling sub-bass groove, shuffled hi-hats, warm Rhodes chord stabs, subtle chopped vocal echoes, smoky intimate female lead vocal, understated hypnotic late-night club production. ``` TemPolor v4.8 — "Low Light" · 1:28 · tạo trong 51 giây <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/song' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model_song="v4.8"' \ --form 'prompt="Deep house at 121 BPM. Rolling sub-bass groove, shuffled hi-hats, warm Rhodes chord stabs, subtle chopped vocal echoes, smoky intimate female lead vocal, understated hypnotic late-night club production."' \ --form 'lyrics="[Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go)"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-tempolor-v4.8.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Low Light" · 3:09 · tạo trong 101 giây <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-advanced' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9.5"' \ --form 'lyrics="[Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go)"' \ --form 'desc="deep house, late night, smoky, hypnotic, groovy, 121 bpm, female vocals, warm, understated club production"' \ --form 'vocal_gender="female"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music-3.0 — "Low Light" · 2:47 · tạo trong 135 giây <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-3.0"' \ --form 'prompt="Deep house at 121 BPM. Rolling sub-bass groove, shuffled hi-hats, warm Rhodes chord stabs, subtle chopped vocal echoes, smoky intimate female lead vocal, understated hypnotic late-night club production."' \ --form 'lyrics="[Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go)"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Velvet Room" · 2:26 · tạo trong 43 giây <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'prompt="Deep house at 121 BPM. Rolling sub-bass groove, shuffled hi-hats, warm Rhodes chord stabs, subtle chopped vocal echoes, smoky intimate female lead vocal, understated hypnotic late-night club production."' \ --form 'lyrics="[Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go)"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ACE Music v1 — "Two shadows in a velvet" · 1:53 · tạo trong 52 giây <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/acemusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="acemusic-v1"' \ --form 'style="Deep house at 121 BPM. Rolling sub-bass groove, shuffled hi-hats, warm Rhodes chord stabs, subtle chopped vocal echoes, smoky intimate female lead vocal, understated hypnotic late-night club production."' \ --form 'lyrics="[Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go)"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ### Vòng 6: song ca jazzy house Đề bài khó nhất trong bộ — một bản phối hai giọng với các lớp jazz chơi trực tiếp trên nền house, vai giọng được đánh dấu trong lời. Các nhãn này là gợi ý, không phải tham số API, nên hãy nghe xem model nào thực sự để hai giọng hát đối đáp, và model nào gộp lại thành một người hát. ``` [Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound ``` TemPolor v4.8 — "Blue Hour" · 2:09 · tạo trong 69 giây <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/song' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model_song="v4.8"' \ --form 'prompt="Jazzy deep house duet at 120 BPM. Rolling deep-house groove with swung hi-hats, walking upright-bass motif over the sub, smoky muted trumpet and tenor-sax licks answering the vocals, extended jazz piano chords, a male and a female lead trading verses and joining in harmony on the chorus, small backing ensemble echoing the hook, warm vinyl texture, sophisticated late-night club production."' \ --form 'lyrics="[Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-tempolor-v4.8.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Blue Hour" · 3:12 · tạo trong 70 giây <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-advanced' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9.5"' \ --form 'lyrics="[Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound"' \ --form 'desc="jazzy deep house, jazz house, duet, male and female vocals, group backing vocals, muted trumpet, saxophone, upright bass, swung, 120 bpm, late night, warm sophisticated production"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music-3.0 — "Blue Hour" · 2:18 · tạo trong 134 giây <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-3.0"' \ --form 'prompt="Jazzy deep house duet at 120 BPM. Rolling deep-house groove with swung hi-hats, walking upright-bass motif over the sub, smoky muted trumpet and tenor-sax licks answering the vocals, extended jazz piano chords, a male and a female lead trading verses and joining in harmony on the chorus, small backing ensemble echoing the hook, warm vinyl texture, sophisticated late-night club production."' \ --form 'lyrics="[Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Blue Hour" · 2:34 · tạo trong 58 giây <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'prompt="Jazzy deep house duet at 120 BPM. Rolling deep-house groove with swung hi-hats, walking upright-bass motif over the sub, smoky muted trumpet and tenor-sax licks answering the vocals, extended jazz piano chords, a male and a female lead trading verses and joining in harmony on the chorus, small backing ensemble echoing the hook, warm vinyl texture, sophisticated late-night club production."' \ --form 'lyrics="[Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ACE Music v1 — "Blue hour settles on the" · 3:05 · tạo trong 70 giây <details markdown="block"> <summary><b>Xem lệnh gọi API</b></summary> ```bash curl --location 'https://api.useapi.net/v1/acemusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="acemusic-v1"' \ --form 'style="Jazzy deep house duet at 120 BPM. Rolling deep-house groove with swung hi-hats, walking upright-bass motif over the sub, smoky muted trumpet and tenor-sax licks answering the vocals, extended jazz piano chords, a male and a female lead trading verses and joining in harmony on the chorus, small backing ensemble echoing the hook, warm vinyl texture, sophisticated late-night club production."' \ --form 'lyrics="[Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Khi lời được cung cấp sẵn, bốn model kia lấy tên từ câu hook của điệp khúc, còn ACE Music lấy những từ đầu tiên của lời. Lưu ý rằng nhãn vai ở vòng này nằm bên trong tiêu đề đoạn — `[Verse 1 - male]` — chứ không đứng riêng ở đầu dòng, vốn là dạng mà các model coi là cấu trúc. ## Câu hỏi thường gặp **Một bài hát qua useapi.net giá bao nhiêu?** Qua useapi.net, từ $0,01 đến $0,02: một bài Music-3.0 tốn khoảng $0,01 trên MiniMax Audio Pro, một bài Lyria 3.5 $0,011 trên Flow Music Member, một bài Mureka V9.5 $0,018 trên Mureka Premier và một bài ACE Music v1 $0,02 trên ACE Music Creator. Các API chính thức tính $0,15 trên [MiniMax](https://platform.minimax.io/docs/pricing/overview#about-music-models) (đóng với người dùng mới từ ngày 20 tháng 8 năm 2026), $0,08 trên [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) của Google và $0,15 trên [Mureka](https://platform.mureka.ai/pricing), trả trước từ $1.000 (tính đến tháng 11/2026). Xem [danh sách model và chi phí](#the-lineup-and-what-it-costs). **Dịch vụ nào rẻ nhất khi tạo số lượng lớn?** Qua useapi.net, đó là TemPolor. TemPolor Ultra có giá cố định $29,99 một tháng, không tính phí theo bài, nên càng tạo nhiều thì mỗi bài càng rẻ: khoảng $0,03 với 1.000 bài một tháng và $0,015 với 2.000 bài. API riêng của TemPolor tính [$0,04 một lần gọi](https://platform.tempolor.com/docs/6665893m0) từ một [gói trả trước $100](https://platform.tempolor.com/pricing), nên 1.000 bài tốn $40 ở đó với bất kỳ khối lượng nào (tính đến tháng 11/2026). **Tôi có chạy cả năm dịch vụ bằng một token được không?** Qua useapi.net thì được. Một API token dùng được với [TemPolor](/docs/api-tempolor-v1), [Mureka](/docs/api-mureka-v1), [MiniMax](/docs/api-minimax-v1), [Flow Music](/docs/api-flowmusic-v1) và [ACE Music](/docs/api-acemusic-v1), cùng mọi dịch vụ khác chúng tôi hỗ trợ. Bạn chỉ cần kết nối gói đăng ký website của mỗi dịch vụ một lần. Body của request cũng dùng lại được, vì TemPolor nhận cùng các trường `prompt` và `lyrics` như MiniMax, còn ACE Music nhận cùng văn bản dưới dạng `style` và `lyrics`. **Làm sao để chọn các model mới nhất?** Qua useapi.net, các model mới nhất của TemPolor đã là mặc định: `v4.8` trên [POST music/song](/docs/api-tempolor-v1/post-tempolor-music-song) qua `model_song`, và `i4` trên [POST music/instrumental](/docs/api-tempolor-v1/post-tempolor-music-instrumental) qua `model_instrumental`, còn tên model cũ được tự động chuyển sang chúng. Lyria là ngoại lệ: hãy truyền `model: "lyria-3.5"` trên [POST /music](/docs/api-flowmusic-v1/post-flowmusic-music), vì `lyria-3-pro` vẫn là mặc định của Flow Music. Hãy truyền model một cách tường minh nếu code của bạn cần ghi lại model nào đã tạo ra bản nhạc. **Tôi có nhận được nhiều hơn một bản nhạc mỗi lần gọi không?** Qua useapi.net, được với bốn trong năm dịch vụ. MiniMax nhận `quantity` tối đa 3, tính phí như ba bài hát. Mureka trả về hai bài mỗi lượt tạo và Flow Music một cặp A/B, cả hai đều với giá của một lượt tạo, còn ACE Music trả hai bài mỗi request, 4 credit cho cả cặp. TemPolor trả về một bản nhạc mỗi lần gọi trong suốt bài thử này, và chạy tối đa mười lượt tạo cùng lúc trên một tài khoản. #### Đăng ở nơi khác {: .no_toc #cross-posted } Cũng đăng trên [dev.to](https://dev.to/useapi/ai-music-apis-one-generation-later-minimax-music-30-vs-lyria-35-vs-mureka-v95-365p){:rel="nofollow"}, được thảo luận trên [Reddit](https://www.reddit.com/r/ThirdPartyAPI/comments/1wq8jon/four_ai_music_apis_compared_tempolor_v48_minimax/){:rel="nofollow"}, chia sẻ trên [Bluesky](https://bsky.app/profile/useapi.net/post/3mweqttv6bf2e){:rel="nofollow"} (tiếng Anh), và trên [YouTube](https://youtu.be/MSUGckk4JqU) dưới dạng bản nghe thử dài 15 phút. Vòng trước: [So sánh các API nhạc AI](/docs/articles/ai-music-api-comparison). === URL: https://useapi.net/docs/articles/ai-music-flagships-compared-zh === Document URL: https://useapi.net/docs/articles/ai-music-flagships-compared-zh --- layout: default translation_key: ai-music-flagships title: "同样六个创作要求下的五个 AI 音乐 API:ACE Music v1、TemPolor v4.8、MiniMax Music-3.0、Lyria 3.5 和 Mureka V9.5" description: "五个 AI 音乐模型(ACE Music v1、TemPolor v4.8 和 i4、MiniMax Music-3.0、Google Lyria 3.5 和 Mureka V9.5)通过 useapi.net 的 API 完成同样的六个创作要求,附每首曲目、生成它的确切 API 调用、生成耗时,以及每首歌在网站订阅上与官方 API 相比的价格。" keywords: [AI music API, TemPolor API, TemPolor v4.8, MiniMax Music-3.0 API, Lyria 3.5 API, Mureka V9.5 API, ACE Music API, ACE Music v1 API, AI music API comparison, music generation API, text to music API, AI music API pricing, AI 音乐 API, AI 音乐 API 比较, AI 音乐 API 价格, 音乐生成 API, 文本生成音乐, AI 歌曲生成 API, 中文教程, Chinese tutorial] image: /assets/images/articles/ai-music-flagships-compared.jpg video: name: "五个 AI 音乐 API,同样的六个创作要求" description: "ACE Music v1、TemPolor v4.8 和 i4、MiniMax Music-3.0、Google Lyria 3.5 和 Mureka V9.5 使用完全相同的六个创作要求:每首曲目最响的 30 秒,响度已统一,屏幕上显示提示词、价格和生成耗时。" embed: https://www.youtube.com/embed/MSUGckk4JqU thumbnail: https://i.ytimg.com/vi/MSUGckk4JqU/maxresdefault.jpg date: 2026-11-14 duration: PT15M width: 1920 height: 1080 parent: Articles nav_exclude: true lang: zh-CN date: 2026-08-19 last_modified: 2026-11-18 nav_order: 96 --- ## 同样六个创作要求下的五个 AI 音乐 API:ACE Music v1、TemPolor v4.8、MiniMax Music-3.0、Lyria 3.5 和 Mureka V9.5 {: .no_toc #five-ai-music-apis-on-the-same-six-briefs-ace-music-v1-tempolor-v48-minimax-music-30-lyria-35-and-mureka-v95} 13 分钟阅读 • 2026 年 8 月 19 日(2026 年 11 月 18 日更新) ## 目录 {: .no_toc .text-delta #table-of-contents} ### 简介 TemPolor v4.8、MiniMax Music-3.0、Google 的 Lyria 3.5 和 Mureka V9.5:四个 AI 音乐模型,同样的六个创作要求,一个 [useapi.net](/docs/subscription) API 令牌。下面是全部 24 首曲目,完整、未经剪辑,每首都附有生成它的 API 调用。这些创作要求与我们 7 月使用的相同,所以这里的每首曲目都能在 [AI 音乐 API 比较](/docs/articles/ai-music-api-comparison)中找到一个前代版本来对比。 2026 年 11 月 14 日,在其他模型测试三个月之后,我们用完全相同的六个创作要求测试了 ACE Music v1,它在 [Artificial Analysis 人声音乐排行榜](https://artificialanalysis.ai/music/leaderboard/vocals)上排名第一,领先 Suno v6。它的歌曲排在下面每一轮的最后,本页的曲目因此达到 30 首。 TemPolor 是 7 月之后新加入的,它的计费方式与这里的其他服务都不同:固定月费,不按首收费。每首歌的价格见[下文](#the-lineup-and-what-it-costs)。先听一听,自己来评判这些模型。 时间不够?还有一个 <a href="https://youtu.be/MSUGckk4JqU"><img style="height:1em;vertical-align: middle;" src="/assets/images/youtube.svg" alt=""> 15 分钟的 YouTube 视频</a>:五个模型在每个创作要求上最响的 30 秒,依次播放,响度已统一,屏幕上显示提示词、价格和生成耗时(价格截至 2026 年 11 月)。完整曲目和每首背后的确切 API 调用都在本页。 这个测试更早的三模型轮次也在 YouTube 上:[AI Music APIs One Generation Later: MiniMax Music-3.0 vs Lyria 3.5 vs Mureka V9.5](https://www.youtube.com/watch?v=9AM5p-A9oFM)。 ### 7 月以来的变化 | 服务 | 7 月 | 现在 | 变化 | |---|---|---|---| | TemPolor | 不在测试阵容中 | v4.8(歌曲)+ i4(纯音乐) | 首次加入本比较,并带来两个新模型 | | Mureka | V9 | V9.5 | 新的默认模型 | | Flow Music | Lyria 3 Pro | Lyria 3.5 | 新的旗舰模型,但 API 默认值仍是 3 Pro | | MiniMax | 通过 PixVerse 使用 music-2.6 | Music-3.0,原生接入 | 新模型,*也是*新端点 | | ACE Music | 不在测试阵容中 | ACE Music v1 | 2026 年 11 月 14 日加入 | 其中两项是普通的版本升级。MiniMax 那一行不是:[MiniMax 音乐现在有了自己的一等端点](/docs/api-minimax-v1/post-minimax-music-create),不再需要通过 [PixVerse](/docs/api-pixverse-v2/post-pixverse-music-create) 调用。端点不同,计费也不同。 TemPolor 是另一个例外。它是这里唯一把任务拆分到两个端点、使用两个不同模型的服务:[`POST music/song`](/docs/api-tempolor-v1/post-tempolor-music-song) 用 `v4.8` 生成所有带人声的曲目,[`POST music/instrumental`](/docs/api-tempolor-v1/post-tempolor-music-instrumental) 用 `i4` 生成所有无人声的曲目。旧的模型名称仍然可用,并会自动路由到新模型,所以现有代码可以继续运行;但这也意味着你可能在不知不觉中已经用上了新模型,或者因为什么都没传而错过它们。 ### 测试阵容和价格 下表列出一首歌在各家官方 API 上的价格([TemPolor](https://platform.tempolor.com/docs/6665893m0)、[MiniMax](https://platform.minimax.io/docs/pricing/overview#about-music-models)(2026 年 8 月 20 日起不对新用户开放)、Google 的 [Gemini API](https://ai.google.dev/gemini-api/docs/pricing)、[Mureka](https://platform.mureka.ai/pricing)),以及在本次测试中各模型所用网站订阅上的价格(2026 年 11 月)。每个订阅每月附带一定数量的积分,每首歌消耗固定数量的积分,所以一首歌的价格就是它所占的订阅费份额。 | 模型 | 官方 API | 网站月度订阅 | 每首价格 | |---|---|---|---| | [TemPolor v4.8 / i4](/docs/api-tempolor-v1) | 4 美分 (每次调用,预付 $100 起) | TemPolor Ultra $29.99 | $0 / 0 积分 (不按首收费) | | [MiniMax Music-3.0](/docs/api-minimax-v1/post-minimax-music-create) | 15 美分 (2026 年 8 月 20 日起不对新用户开放) | MiniMax Audio Pro $99 (每月 3,000,000 积分) | 1 美分 / 300 积分 (每月 10,000 首) | | [Lyria 3.5](/docs/api-flowmusic-v1) | 8 美分 (每首) | Flow Music Member $64 (每月 30,000 积分) | 1.1 美分 / 5 积分 (每月 6,000 首) | | [Mureka V9.5](/docs/api-mureka-v1) | 15 美分 (预付 $1,000 起) | Mureka Premier $30 (每月 20,000 积分) | 1.8 美分 / 12 积分 (每月 1,666 首) | | [ACE Music v1](/docs/api-acemusic-v1) | — | ACE Music Creator $9.90 (每月 1,000 积分) | 2 美分 / 2 积分 (每月 500 首) | - 由模型根据提示词写歌词时(如第 3 轮和第 4 轮),Mureka 的 API 收费 50 美分而不是 15 美分,MiniMax 的 API 加收 1 美分;通过 useapi.net,两种方式的价格相同。 - TemPolor 的 API 积分[在任何套餐规模下都是每个 $0.01](https://platform.tempolor.com/pricing),所以用量再大也不会更便宜。更大的套餐买到的是并发数:$100 可同时运行 5 个请求,$500 为 10 个,$5,000 为 20 个;同一套餐买两次,等级也不会叠加。TemPolor Ultra 可同时运行 10 个生成。 - 本文所说的 `v4.8` 在 TemPolor 的 API 上叫 `tempolor-latest`。`i4` 名称不变。 - 较小的套餐(如 Mureka Pro 和 Flow Music Starter)每首歌稍贵一些,但仍远低于官方 API。 - ACE Music 每个请求返回两首歌,这一对收 4 积分,即每首 2 积分。在 ACE Music Artist 上(每月 $29,按年付费为每月 $16.58),每首歌分别为 2.3 美分或约 1.3 美分。 - Google AI 订阅包含一个 Flow Music 套餐,其积分与 Google AI 积分分开计算:[Google AI Plus](https://support.google.com/googleone/answer/16882689?hl=zh-CN) 包含 Starter,[Google AI Pro](https://support.google.com/googleone/answer/14534406?hl=zh-CN) 包含 Plus,[Google AI Ultra](https://support.google.com/googleone/answer/16286513?hl=zh-CN) 包含 Member。 useapi.net 基于你的 TemPolor、MiniMax Audio、Flow Music、Mureka 或 ACE Music 网站订阅运行,并把它作为 REST API 提供,不按首加价。一个 API 令牌就能用于全部五个服务:无需为每个服务准备 SDK,无需单独的 API 密钥,也无需核对五套账单。同一个令牌还能调用我们支持的其他所有服务:视频、图像、语音、换脸。 ### 测试方法 创作要求与 7 月相同,直接从已发布的文章中复制而不是重新输入:两首纯音乐,两首由模型自己写歌词的带人声曲目,以及两首由我们同时提供歌词和详细风格要求的曲目。同一轮中的每个模型收到的文字完全相同,所以你听到的就是模型本身。TemPolor 的请求体是从 MiniMax 的请求体逐字节复制的,两者接受相同的 `prompt` 和 `lyrics` 字段。 ACE Music v1 收到的也是同样的文字。它的 API 要么接受 `prompt`(由它自己写风格和歌词),要么接受 `style` 加上你的 `lyrics` 或 `instrumental`,两者同时提供会被拒绝。所以第 3 轮和第 4 轮以 `prompt` 提交,两个纯音乐创作要求以 `style` 加 `instrumental: true` 提交,第 5 轮和第 6 轮以 `style` 加 `lyrics` 提交,都没有设置标题、`duration` 或 `bpm`。 生成耗时是通过 API 测得的实际时间,轮询间隔为 15 秒,所以请把它们当作大致参考,而不是基准测试。按六轮的中位数计算,Lyria 3.5 最快,为 58.5 秒,其次是 ACE Music v1 的 62 秒、TemPolor 的 69.5 秒、Mureka 的 86.5 秒和 MiniMax 的 158.5 秒。模型自己给作品起的标题我们都原样保留,包括拼写和多余的空格。曲目完整、未经剪辑,与各 API 返回的完全一致:Mureka 每次生成两首歌,为 192 kbps MP3;MiniMax 一首,256 kbps;TemPolor 一首,48 kHz,约 230–320 kbps;ACE Music 每个请求两首歌,为 192 kbps、48 kHz MP3;Flow Music 是一对 A/B 歌曲,为 48 kHz WAV,只是为了能在浏览器中播放才转码为 320 kbps MP3。Flow 的 WAV 原始文件直接来自 API。ACE Music 在每一轮中的参赛曲目都是它两首歌中的第一首,没有挑选。 如果你基于 TemPolor 开发,有一件事要预先知道:歌曲任务会在文件可以获取的几秒 *之前* 就报告 `status_final: true` 和 `COMPLETED`,在这段间隙内 [`GET music/download/job_id`](/docs/api-tempolor-v1/get-tempolor-music-download-job_id) 会返回 `404`。我们四个人声轮次中有三个在第一次尝试时遇到了这种情况。请把这个 `404` 当作“尚未就绪”并继续轮询,而不是当作失败。 ## 第一部分 — 纯音乐 ### 第 1 轮:黑色电影风大乐队 ``` Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production. ``` TemPolor i4 — "Generic Rhythm Tune" · 3:09 · 生成耗时 103 秒 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/instrumental' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model_instrumental="i4"' \ --form 'prompt="Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/01-bigband-noir-tempolor-i4.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Brass Knuckle Boulevard" · 3:19 · 生成耗时 86 秒 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-instrumental' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9.5"' \ --form 'prompt="Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/01-bigband-noir-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music-3.0 — "Midnight Operative" · 2:51 · 生成耗时 182 秒 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-3.0"' \ --form 'prompt="Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production."' \ --form 'instrumental="true"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/01-bigband-noir-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Double Cross" · 2:52 · 生成耗时 47 秒 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'instrumental="true"' \ --form 'prompt="Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/01-bigband-noir-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ACE Music v1 — "Big-band noir action theme" · 2:08 · 生成耗时 52 秒 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash curl --location 'https://api.useapi.net/v1/acemusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="acemusic-v1"' \ --form 'style="Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production."' \ --form 'instrumental="true"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/01-bigband-noir-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> 这个创作要求的 7 月版本在[上一篇文章](/docs/articles/ai-music-api-comparison#round-1-big-band-noir)里,可以对比着听。 ### 第 2 轮:液态鼓打贝斯 ``` Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production. ``` TemPolor i4 — " Generic Rhythm Beat" · 3:30 · 生成耗时 69 秒 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/instrumental' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model_instrumental="i4"' \ --form 'prompt="Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/02-liquid-dnb-tempolor-i4.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Piano Afterglow" · 3:22 · 生成耗时 85 秒 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-instrumental' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9.5"' \ --form 'prompt="Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production."' \ --form 'title="Take B - Liquid DnB"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/02-liquid-dnb-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music-3.0 — "Midnight Flow" · 3:45 · 生成耗时 227 秒 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-3.0"' \ --form 'prompt="Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production."' \ --form 'instrumental="true"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/02-liquid-dnb-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Silken Tides" · 1:06 · 生成耗时 59 秒 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'prompt="Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production."' \ --form 'instrumental="true"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/02-liquid-dnb-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ACE Music v1 — "Liquid drum and bass instrumental" · 3:10 · 生成耗时 89 秒 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash curl --location 'https://api.useapi.net/v1/acemusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="acemusic-v1"' \ --form 'style="Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production."' \ --form 'instrumental="true"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/02-liquid-dnb-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> 最初的四个 API 都没有时长参数,每个创作要求都只是在文字里写了“around 60 seconds”(约 60 秒)。ACE Music 有一个时长参数 `duration`(30 到 600 秒),我们没有使用,让它读同样的文字。四个模型中只有 Lyria 接受过这个提示,而且只有这一次。7 月时,Lyria 3 Pro 对同一提示词生成的歌曲长 2:46。在下面两个提示词轮次中,ACE Music v1 自己写风格,生成的歌曲分别为 0:41 和 1:22,是这两轮中最接近一分钟的。 TemPolor 的纯音乐端点也没有真正为作品起名。它为这两个创作要求返回的是 "Generic Rhythm Tune" 和 "Generic Rhythm Beat",这是占位名而不是标题,而且还不规整:第一个中间有两个空格,第二个开头有一个空格。它的歌曲端点在接下来的四轮中都会正常起标题。ACE Music 在没有收到标题时,用创作要求的开头几个词为两首纯音乐命名,用我们歌词的开头几个词为第 5 轮和第 6 轮的歌曲命名。如果你按标题归档曲目,纯音乐请自己生成名称,并修剪返回的任何标题,或者给 ACE Music 发送一个 `title`。 ## 第二部分 — 人声,由模型写歌词 ### 第 3 轮:流行对唱 只有一句话的指示,也是一次有意的能力测试:只有模型能安排两个声音,对唱才能成立。 ``` A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus. ``` TemPolor v4.8 — "Text Me" · 1:51 · 生成耗时 70 秒 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/song' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model_song="v4.8"' \ --form 'prompt="A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-tempolor-v4.8.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> 听听第一句。TemPolor 为这个创作要求自己写了歌词,并且在行内标注了演唱者: ``` [Verse] [Male] You sent "you up?" at 1:09 [Female] You said "just one more," then took your time [Male] I saw your typing, then it slipped away [Female] I dropped my phone and missed your "hey" ``` 它的歌手会把 `[Verse]` 和 `[Chorus]` 当作结构标记去掉,但行内的 `[Male]` 不是它能识别的标记,所以它把 "male" 和 "female" 这两个词当作歌词唱了出来。同一个模型的两部分对它自己的格式意见不一。MiniMax 在这个创作要求上遇到了完全相同的问题,但它用圆括号写 `(Male)` 和 `(Female)` 逃过一劫,它的歌手确实会去掉圆括号里的标签。 这个教训不止适用于这一个模型。`lyrics` 里的角色标签不是一项可移植的 API 功能,所以如果你自己提供歌词并想要两个声音,在信任它之前先检查某个模型如何处理你的括号写法,或者干脆去掉标签,改在风格提示词中描述对唱。 Mureka V9.5 — "Are You Still Awake?" · 3:05 · 生成耗时 88 秒 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9.5"' \ --form 'prompt="A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music-3.0 — "Three Little Dots" · 2:31 · 生成耗时 146 秒 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-3.0"' \ --form 'prompt="A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax 以聊天中的“正在输入”提示为它命名,它的 `(Male)` / `(Female)` 标签没有出现在演唱中。 Lyria 3.5 — "You Go First" · 1:59 · 生成耗时 74 秒 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'prompt="A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 自己写了两个声音的一唱一和,回应的句子放在圆括号里。 ACE Music v1 — "Three Dot Bubbles" · 0:41 · 生成耗时 54 秒 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash curl --location 'https://api.useapi.net/v1/acemusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="acemusic-v1"' \ --form 'prompt="A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ACE Music 同样以“正在输入”提示为它命名,并且像 MiniMax 一样,用圆括号里的 `(Male)`、`(Female)` 和 `(Both)` 写出了对唱。 ### 第 4 轮:西班牙语弗拉门戈流行 语言测试:提示词是英文,歌曲则不应是英文: ``` A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals. ``` TemPolor v4.8 — "Lluvia" · 2:58 · 生成耗时 102 秒 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/song' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model_song="v4.8"' \ --form 'prompt="A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/04-spanish-flamenco-tempolor-v4.8.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Agua de Julio" · 3:32 · 生成耗时 87 秒 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9.5"' \ --form 'prompt="A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/04-spanish-flamenco-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music-3.0 — "Tacones de Lluvia" · 3:07 · 生成耗时 171 秒 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-3.0"' \ --form 'prompt="A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/04-spanish-flamenco-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Lluvia de Verano" · 2:33 · 生成耗时 73 秒 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'prompt="A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/04-spanish-flamenco-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ACE Music v1 — "Fuego en la Tormenta" · 1:22 · 生成耗时 70 秒 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash curl --location 'https://api.useapi.net/v1/acemusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="acemusic-v1"' \ --form 'prompt="A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/04-spanish-flamenco-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> 五个模型都根据英文提示词写出了西班牙语歌词,并且都在没有要求的情况下用西班牙语为曲目命名。TemPolor 的 v4.8 据文档支持 [30 多种语言](/docs/api-tempolor-v1)。一个西班牙语创作要求测试不了三十种语言,但它用正确的语言回应了这一个,还主动把歌曲命名为 "Lluvia"。 ## 第三部分 — 人声,我们的歌词加详细的风格要求 在最后这种形式中,每个模型都收到同样的原创歌词和一份详细的制作要求。Mureka 通过 [music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced) 接收它们(`lyrics` + 逗号分隔的风格 `desc` + `vocal_gender`),而 MiniMax、Flow Music 和 TemPolor 都在风格提示词旁接受一个 `lyrics` 字段,所以同一个请求体在四个中的三个上无需修改即可使用。ACE Music 以 `style` 和 `lyrics` 接收同样的两段文字。 ### 第 5 轮:deep house ``` [Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go) ``` ``` Deep house at 121 BPM. Rolling sub-bass groove, shuffled hi-hats, warm Rhodes chord stabs, subtle chopped vocal echoes, smoky intimate female lead vocal, understated hypnotic late-night club production. ``` TemPolor v4.8 — "Low Light" · 1:28 · 生成耗时 51 秒 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/song' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model_song="v4.8"' \ --form 'prompt="Deep house at 121 BPM. Rolling sub-bass groove, shuffled hi-hats, warm Rhodes chord stabs, subtle chopped vocal echoes, smoky intimate female lead vocal, understated hypnotic late-night club production."' \ --form 'lyrics="[Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go)"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-tempolor-v4.8.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Low Light" · 3:09 · 生成耗时 101 秒 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-advanced' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9.5"' \ --form 'lyrics="[Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go)"' \ --form 'desc="deep house, late night, smoky, hypnotic, groovy, 121 bpm, female vocals, warm, understated club production"' \ --form 'vocal_gender="female"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music-3.0 — "Low Light" · 2:47 · 生成耗时 135 秒 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-3.0"' \ --form 'prompt="Deep house at 121 BPM. Rolling sub-bass groove, shuffled hi-hats, warm Rhodes chord stabs, subtle chopped vocal echoes, smoky intimate female lead vocal, understated hypnotic late-night club production."' \ --form 'lyrics="[Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go)"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Velvet Room" · 2:26 · 生成耗时 43 秒 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'prompt="Deep house at 121 BPM. Rolling sub-bass groove, shuffled hi-hats, warm Rhodes chord stabs, subtle chopped vocal echoes, smoky intimate female lead vocal, understated hypnotic late-night club production."' \ --form 'lyrics="[Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go)"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ACE Music v1 — "Two shadows in a velvet" · 1:53 · 生成耗时 52 秒 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash curl --location 'https://api.useapi.net/v1/acemusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="acemusic-v1"' \ --form 'style="Deep house at 121 BPM. Rolling sub-bass groove, shuffled hi-hats, warm Rhodes chord stabs, subtle chopped vocal echoes, smoky intimate female lead vocal, understated hypnotic late-night club production."' \ --form 'lyrics="[Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go)"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ### 第 6 轮:jazzy house 对唱 这组中最难的创作要求:在 house 律动上叠加现场爵士层次的双人声编排,声部角色标注在歌词里。这些标签只是提示,不是 API 参数,所以请听听谁真正在轮流唱主歌,谁又把它压成了一个歌手。 ``` [Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound ``` TemPolor v4.8 — "Blue Hour" · 2:09 · 生成耗时 69 秒 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/song' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model_song="v4.8"' \ --form 'prompt="Jazzy deep house duet at 120 BPM. Rolling deep-house groove with swung hi-hats, walking upright-bass motif over the sub, smoky muted trumpet and tenor-sax licks answering the vocals, extended jazz piano chords, a male and a female lead trading verses and joining in harmony on the chorus, small backing ensemble echoing the hook, warm vinyl texture, sophisticated late-night club production."' \ --form 'lyrics="[Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-tempolor-v4.8.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Blue Hour" · 3:12 · 生成耗时 70 秒 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-advanced' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9.5"' \ --form 'lyrics="[Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound"' \ --form 'desc="jazzy deep house, jazz house, duet, male and female vocals, group backing vocals, muted trumpet, saxophone, upright bass, swung, 120 bpm, late night, warm sophisticated production"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music-3.0 — "Blue Hour" · 2:18 · 生成耗时 134 秒 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-3.0"' \ --form 'prompt="Jazzy deep house duet at 120 BPM. Rolling deep-house groove with swung hi-hats, walking upright-bass motif over the sub, smoky muted trumpet and tenor-sax licks answering the vocals, extended jazz piano chords, a male and a female lead trading verses and joining in harmony on the chorus, small backing ensemble echoing the hook, warm vinyl texture, sophisticated late-night club production."' \ --form 'lyrics="[Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Blue Hour" · 2:34 · 生成耗时 58 秒 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'prompt="Jazzy deep house duet at 120 BPM. Rolling deep-house groove with swung hi-hats, walking upright-bass motif over the sub, smoky muted trumpet and tenor-sax licks answering the vocals, extended jazz piano chords, a male and a female lead trading verses and joining in harmony on the chorus, small backing ensemble echoing the hook, warm vinyl texture, sophisticated late-night club production."' \ --form 'lyrics="[Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ACE Music v1 — "Blue hour settles on the" · 3:05 · 生成耗时 70 秒 <details markdown="block"> <summary><b>查看 API 调用</b></summary> ```bash curl --location 'https://api.useapi.net/v1/acemusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="acemusic-v1"' \ --form 'style="Jazzy deep house duet at 120 BPM. Rolling deep-house groove with swung hi-hats, walking upright-bass motif over the sub, smoky muted trumpet and tenor-sax licks answering the vocals, extended jazz piano chords, a male and a female lead trading verses and joining in harmony on the chorus, small backing ensemble echoing the hook, warm vinyl texture, sophisticated late-night club production."' \ --form 'lyrics="[Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> 在提供了歌词的情况下,另外四个模型都从副歌的记忆点中取了标题,而 ACE Music 取的是歌词的开头几个词。注意,这一轮的角色标签放在段落标题里(`[Verse 1 - male]`),而不是单独放在一行的开头,后者才是模型会当作结构处理的形式。 ## 常见问题 **通过 useapi.net 生成一首歌要多少钱?** 通过 useapi.net,一到两美分:在 MiniMax Audio Pro 上,一首 Music-3.0 歌曲约 1 美分;在 Flow Music Member 上,一首 Lyria 3.5 歌曲 1.1 美分;在 Mureka Premier 上,一首 Mureka V9.5 歌曲 1.8 美分;在 ACE Music Creator 上,一首 ACE Music v1 歌曲 2 美分。官方 API 的收费是:[MiniMax](https://platform.minimax.io/docs/pricing/overview#about-music-models) 15 美分(2026 年 8 月 20 日起不对新用户开放),Google 的 [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) 8 美分,[Mureka](https://platform.mureka.ai/pricing) 15 美分且需预付 $1,000 起(截至 2026 年 11 月)。见[测试阵容和价格](#the-lineup-and-what-it-costs)。 **大用量时哪个最便宜?** 通过 useapi.net,是 TemPolor。TemPolor Ultra 固定每月 $29.99,不按首收费,所以生成得越多,每首越便宜:每月 1,000 首时约 3 美分,2,000 首时约 1.5 美分。TemPolor 自己的 API 按[每次调用 $0.04](https://platform.tempolor.com/docs/6665893m0) 收费,需购买 [$100 起的预付套餐](https://platform.tempolor.com/pricing),所以在那里无论用量多大,1,000 首都要 $40(截至 2026 年 11 月)。 **能用一个令牌运行全部五个吗?** 通过 useapi.net 可以。一个 API 令牌就能调用 [TemPolor](/docs/api-tempolor-v1)、[Mureka](/docs/api-mureka-v1)、[MiniMax](/docs/api-minimax-v1)、[Flow Music](/docs/api-flowmusic-v1) 和 [ACE Music](/docs/api-acemusic-v1),以及我们支持的其他所有服务。每个服务只需连接一次你的网站订阅。请求体也能通用,因为 TemPolor 接受与 MiniMax 相同的 `prompt` 和 `lyrics` 字段,ACE Music 以 `style` 和 `lyrics` 接收同样的文字。 **如何选用最新的模型?** 通过 useapi.net,TemPolor 的最新模型已经是默认值:[POST music/song](/docs/api-tempolor-v1/post-tempolor-music-song) 上通过 `model_song` 使用 `v4.8`,[POST music/instrumental](/docs/api-tempolor-v1/post-tempolor-music-instrumental) 上通过 `model_instrumental` 使用 `i4`,旧的模型名称会路由到它们。Lyria 是例外:在 [POST /music](/docs/api-flowmusic-v1/post-flowmusic-music) 上请传入 `model: "lyria-3.5"`,因为 `lyria-3-pro` 仍是 Flow Music 的默认值。如果你的代码需要记录某首曲目是由哪个模型生成的,请显式传入模型。 **一次调用能得到不止一首曲目吗?** 通过 useapi.net,五个中有四个可以。MiniMax 的 `quantity` 最多为 3,按三首歌计费。Mureka 每次生成返回两首歌,Flow Music 返回一对 A/B 歌曲,都只按一次生成计费;ACE Music 每个请求返回两首歌,这一对收 4 积分。在本次测试中,TemPolor 每次调用始终只返回一首曲目,一个账号最多可同时运行 10 个生成。 #### 同步发布 {: .no_toc #cross-posted} 本文也发布在 [dev.to](https://dev.to/useapi/ai-music-apis-one-generation-later-minimax-music-30-vs-lyria-35-vs-mureka-v95-365p){:rel="nofollow"},在 [Reddit](https://www.reddit.com/r/ThirdPartyAPI/comments/1wq8jon/four_ai_music_apis_compared_tempolor_v48_minimax/){:rel="nofollow"} 上有讨论,在 [Bluesky](https://bsky.app/profile/useapi.net/post/3mweqttv6bf2e){:rel="nofollow"} 上有分享,在 [YouTube](https://youtu.be/MSUGckk4JqU) 上有一个 15 分钟的试听剪辑。上一轮:[AI 音乐 API 比较](/docs/articles/ai-music-api-comparison)。 === URL: https://useapi.net/docs/articles/ai-music-flagships-compared === Document URL: https://useapi.net/docs/articles/ai-music-flagships-compared --- layout: default translation_key: ai-music-flagships title: "Five AI Music APIs on the Same Six Briefs: ACE Music v1, TemPolor v4.8, MiniMax Music-3.0, Lyria 3.5 and Mureka V9.5" description: "Five AI music models — ACE Music v1, TemPolor v4.8 and i4, MiniMax Music-3.0, Google Lyria 3.5 and Mureka V9.5 — given the same six briefs through the useapi.net APIs, with every track, the exact API call behind it, generation times, and what each song costs on a website subscription against the official APIs." keywords: [AI music API, TemPolor API, TemPolor v4.8, MiniMax Music-3.0 API, Lyria 3.5 API, Mureka V9.5 API, ACE Music API, ACE Music v1 API, AI music API comparison, music generation API, text to music API, AI music API pricing] image: /assets/images/articles/ai-music-flagships-compared.jpg video: name: "Five AI music APIs on the same six briefs" description: "ACE Music v1, TemPolor v4.8 and i4, MiniMax Music-3.0, Google Lyria 3.5 and Mureka V9.5 on the identical six briefs — each track's loudest 30 seconds, loudness-matched, with the prompt, price and generation time on screen." embed: https://www.youtube.com/embed/MSUGckk4JqU thumbnail: https://i.ytimg.com/vi/MSUGckk4JqU/maxresdefault.jpg date: 2026-11-14 duration: PT15M width: 1920 height: 1080 parent: Articles nav_exclude: true date: 2026-08-19 last_modified: 2026-11-18 nav_order: 96 --- ## Five AI Music APIs on the Same Six Briefs: ACE Music v1, TemPolor v4.8, MiniMax Music-3.0, Lyria 3.5 and Mureka V9.5 13 min read • August 19, 2026 (November 18, 2026) ## Table of contents ### Introduction TemPolor v4.8, MiniMax Music-3.0, Google's Lyria 3.5 and Mureka V9.5 — four AI music models, the same six briefs, one [useapi.net](/docs/subscription) API token. All 24 tracks are below, complete and unedited, each with the API call that made it. They are the same briefs we used in July, so every track here has a predecessor to compare against in [AI Music APIs Compared](/docs/articles/ai-music-api-comparison). On November 14, 2026, three months after the others, we ran the identical six briefs on ACE Music v1, which ranks #1 on [Artificial Analysis' vocal music leaderboard](https://artificialanalysis.ai/music/leaderboard/vocals), ahead of Suno v6. Its song closes each round below, which brings the page to 30 tracks. TemPolor, new since July, prices differently from everything else here: a flat monthly price with no per-song charge. What each song costs is [below](#the-lineup-and-what-it-costs). Listen first and judge the models yourself. Short on time? There is also a <a href="https://youtu.be/MSUGckk4JqU"><img style="height:1em;vertical-align: middle;" src="/assets/images/youtube.svg" alt=""> 15-minute YouTube video</a> — all five models' loudest 30 seconds on every brief, back to back and loudness-matched, with the prompt, price and generation time on screen (prices as of November 2026). The full-length tracks and the exact API call behind each one live on this page. The earlier, three-model round of this test is also on YouTube: [AI Music APIs One Generation Later: MiniMax Music-3.0 vs Lyria 3.5 vs Mureka V9.5](https://www.youtube.com/watch?v=9AM5p-A9oFM). ### What changed since July | Service | July | Now | What moved | |---|---|---|---| | TemPolor | not in the line-up | v4.8 (songs) + i4 (instrumentals) | new to this comparison, and two new models | | Mureka | V9 | V9.5 | new default model | | Flow Music | Lyria 3 Pro | Lyria 3.5 | new flagship — but 3 Pro is still the API default | | MiniMax | music-2.6 via PixVerse | Music-3.0, native | new model *and* a new endpoint | | ACE Music | not in the line-up | ACE Music v1 | added on November 14, 2026 | Two of those are ordinary version bumps. The MiniMax row is not: [MiniMax music is now a first-class endpoint](/docs/api-minimax-v1/post-minimax-music-create) rather than something you reach through [PixVerse](/docs/api-pixverse-v2/post-pixverse-music-create). Different endpoint, different billing. TemPolor is the other exception. It is the only service here that splits the job across two endpoints with two different models: [`POST music/song`](/docs/api-tempolor-v1/post-tempolor-music-song) runs `v4.8` for anything with vocals, and [`POST music/instrumental`](/docs/api-tempolor-v1/post-tempolor-music-instrumental) runs `i4` for anything without. Older model names still work and are routed to the new ones automatically, so existing code keeps running — but it also means you can be on the new models without noticing, or miss them by passing nothing at all. ### The lineup and what it costs What one song costs on each maker's official API ([TemPolor](https://platform.tempolor.com/docs/6665893m0), [MiniMax](https://platform.minimax.io/docs/pricing/overview#about-music-models), closed to new users since August 20, 2026, Google's [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) and [Mureka](https://platform.mureka.ai/pricing)) and on the website subscription each model ran on in this test (November 2026). Each subscription comes with a monthly number of credits, and each song uses a set number of them, so a song costs its share of the subscription. | Model | Official API | Website monthly subscription | Price per song | |---|---|---|---| | [TemPolor v4.8 / i4](/docs/api-tempolor-v1) | 4¢ (a call, prepaid from $100) | TemPolor Ultra $29.99 | $0 / 0 cr (no per-song charge) | | [MiniMax Music-3.0](/docs/api-minimax-v1/post-minimax-music-create) | 15¢ (closed to new users since August 20, 2026) | MiniMax Audio Pro $99 (3,000,000 cr/mo) | 1¢ / 300 cr (10,000 songs/mo) | | [Lyria 3.5](/docs/api-flowmusic-v1) | 8¢ (per song) | Flow Music Member $64 (30,000 cr/mo) | 1.1¢ / 5 cr (6,000 songs/mo) | | [Mureka V9.5](/docs/api-mureka-v1) | 15¢ (prepaid from $1,000) | Mureka Premier $30 (20,000 cr/mo) | 1.8¢ / 12 cr (1,666 songs/mo) | | [ACE Music v1](/docs/api-acemusic-v1) | — | ACE Music Creator $9.90 (1,000 cr/mo) | 2¢ / 2 cr (500 songs/mo) | - When the model writes the lyrics from a prompt, as in rounds 3 and 4, Mureka's API charges 50¢ instead of 15¢ and MiniMax's adds 1¢, while a song costs the same either way through useapi.net. - TemPolor's API credits cost [$0.01 each at every package size](https://platform.tempolor.com/pricing), so volume never lowers its price. The bigger packages buy concurrency instead: five requests at a time at $100, ten at $500 and twenty at $5,000, and the tier does not stack if you buy the same package twice. TemPolor Ultra runs ten generations at once. - The model this article calls `v4.8` is `tempolor-latest` on TemPolor's API. `i4` keeps its name. - Smaller plans, such as Mureka Pro and Flow Music Starter, cost a little more per song and still come in well under the official APIs. - ACE Music returns two songs per request and charges 4 credits for the pair, 2 credits a song. On ACE Music Artist, $29 a month or $16.58 billed yearly, a song costs 2.3¢ or about 1.3¢. - Google AI subscriptions include a Flow Music plan, with credits separate from the Google AI credits: Starter on [Google AI Plus](https://support.google.com/googleone/answer/16882689), Plus on [Google AI Pro](https://support.google.com/googleone/answer/14534406) and Member on [Google AI Ultra](https://support.google.com/googleone/answer/16286513). useapi.net runs on your TemPolor, MiniMax Audio, Flow Music, Mureka or ACE Music website subscription and exposes it as a REST API, with no per-song surcharge. One API token works against all five services — no per-service SDK, no separate API keys, no five sets of billing to reconcile. The same token reaches every other service we support: video, image, speech, face swap. ### How we tested Same six briefs as July, copied from the published article rather than retyped — two instrumentals, two vocal tracks where the model writes its own lyrics, and two where we supply both the lyrics and an elaborate style brief. Every model in a round receives the identical text, so what you hear is the model. TemPolor's bodies were copied byte for byte from the MiniMax ones, which take the same `prompt` and `lyrics` fields. ACE Music v1 got the same text. Its API takes either a `prompt`, from which it writes its own style and lyrics, or a `style` with your `lyrics` or `instrumental`, and refuses the two together. So rounds 3 and 4 went in as `prompt`, the two instrumental briefs as `style` with `instrumental: true`, and rounds 5 and 6 as `style` plus `lyrics`, with no title, `duration` or `bpm`. Generation times are wall-clock through the API at 15-second polling granularity, so treat them as ballpark rather than benchmark. By median over the six rounds, Lyria 3.5 was the fastest at 58.5 s, then ACE Music v1 at 62 s, TemPolor at 69.5 s, Mureka at 86.5 s and MiniMax at 158.5 s. Where a model titles its own output we kept the title, spelling and stray spaces included. Tracks are complete and unedited, exactly as each API returned them: Mureka two songs per generation as 192 kbps MP3, MiniMax one at 256 kbps, TemPolor one at 48 kHz and roughly 230–320 kbps, ACE Music two songs per request as 192 kbps, 48 kHz MP3, and Flow Music an A/B pair as 48 kHz WAV, transcoded to 320 kbps MP3 only so a browser can play it. Flow's WAV originals come straight from the API. ACE Music's entry in each round is the first of its two songs, with no picking. One thing to expect if you build against TemPolor: a song job reports `status_final: true` and `COMPLETED` a few seconds *before* its file is fetchable, and [`GET music/download/job_id`](/docs/api-tempolor-v1/get-tempolor-music-download-job_id) answers `404` in the gap. Three of our four vocal rounds hit it on the first attempt. Treat that `404` as "not yet" and keep polling rather than as a failure. ## Part 1 — Instrumentals ### Round 1: big-band noir ``` Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production. ``` TemPolor i4 — "Generic Rhythm Tune" · 3:09 · generated in 103 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/instrumental' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model_instrumental="i4"' \ --form 'prompt="Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/01-bigband-noir-tempolor-i4.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Brass Knuckle Boulevard" · 3:19 · generated in 86 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-instrumental' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9.5"' \ --form 'prompt="Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/01-bigband-noir-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music-3.0 — "Midnight Operative" · 2:51 · generated in 182 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-3.0"' \ --form 'prompt="Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production."' \ --form 'instrumental="true"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/01-bigband-noir-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Double Cross" · 2:52 · generated in 47 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'instrumental="true"' \ --form 'prompt="Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/01-bigband-noir-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ACE Music v1 — "Big-band noir action theme" · 2:08 · generated in 52 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/acemusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="acemusic-v1"' \ --form 'style="Big-band noir action theme, around 60 seconds. Walking upright-bass and baritone-sax groove, snapping rimshot snare, stabbing trumpet-section hits, vibraphone glints, surf-twang guitar riff over a chromatic minor progression, roaring full-brass climax with crash cymbals. Retro secret-agent swagger, punchy analog-style production."' \ --form 'instrumental="true"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/01-bigband-noir-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> The July versions of this brief are on [the previous page](/docs/articles/ai-music-api-comparison#round-1-big-band-noir) if you want them back to back. ### Round 2: liquid drum and bass ``` Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production. ``` TemPolor i4 — " Generic Rhythm Beat" · 3:30 · generated in 69 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/instrumental' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model_instrumental="i4"' \ --form 'prompt="Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/02-liquid-dnb-tempolor-i4.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Piano Afterglow" · 3:22 · generated in 85 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-instrumental' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9.5"' \ --form 'prompt="Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production."' \ --form 'title="Take B - Liquid DnB"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/02-liquid-dnb-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music-3.0 — "Midnight Flow" · 3:45 · generated in 227 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-3.0"' \ --form 'prompt="Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production."' \ --form 'instrumental="true"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/02-liquid-dnb-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Silken Tides" · 1:06 · generated in 59 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'prompt="Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production."' \ --form 'instrumental="true"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/02-liquid-dnb-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ACE Music v1 — "Liquid drum and bass instrumental" · 3:10 · generated in 89 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/acemusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="acemusic-v1"' \ --form 'style="Liquid drum and bass instrumental, around 60 seconds. Fast rolling breakbeats at 174 BPM, deep warm sub-bass, lush atmospheric pads, delicate piano motif, airy wordless vocal-chop textures, smooth builds into a euphoric flowing drop. Silky, melodic, late-night energy, pristine modern production."' \ --form 'instrumental="true"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/02-liquid-dnb-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> None of the original four APIs exposes a duration parameter — every brief asked for "around 60 seconds" in prose. ACE Music has one, `duration` (30 to 600 seconds), which we left out so it read the same words. Lyria was the only one of the four that ever took the hint, and only here. Lyria 3 Pro answered this same prompt in July at 2:46. On the two prompt rounds below, where ACE Music v1 writes its own style, it came in at 0:41 and 1:22, the nearest to a minute in those rounds. TemPolor's instrumental endpoint also does not really name its output. It returned "Generic Rhythm Tune" and "Generic Rhythm Beat" for these two briefs — placeholders rather than titles, and not even tidy ones: the first arrives with a double space in the middle, the second with a leading space. Its song endpoint, on the next four rounds, titles properly. ACE Music, sent no title, named both instrumentals with the first words of the brief, and its songs in rounds 5 and 6 with the first words of our lyrics. If you file tracks by title, generate the name yourself for instrumentals and trim whatever comes back, or send ACE Music a `title`. ## Part 2 — Vocals, model writes the lyrics ### Round 3: pop duet One sentence of direction, and a deliberate capability probe — a duet only works if the model can stage two voices. ``` A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus. ``` TemPolor v4.8 — "Text Me" · 1:51 · generated in 70 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/song' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model_song="v4.8"' \ --form 'prompt="A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-tempolor-v4.8.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Listen to the first line. TemPolor wrote its own lyrics for this brief, and wrote them with the speaker tagged inline: ``` [Verse] [Male] You sent "you up?" at 1:09 [Female] You said "just one more," then took your time [Male] I saw your typing, then it slipped away [Female] I dropped my phone and missed your "hey" ``` Its singer strips `[Verse]` and `[Chorus]` as structure, but an inline `[Male]` is not a tag it recognises — so it sings the words "male" and "female" as part of the line. The two halves of the same model disagree about its own format. MiniMax met exactly the same problem on this brief and got away with it by writing `(Male)` and `(Female)` in round brackets, which its singer does drop. The lesson generalises past this one model. Role labels inside `lyrics` are not a portable API feature, so if you are supplying lyrics yourself and want two voices, check what a given model does with your bracket style before you trust it — or leave the labels out and describe the duet in the style prompt instead. Mureka V9.5 — "Are You Still Awake?" · 3:05 · generated in 88 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9.5"' \ --form 'prompt="A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music-3.0 — "Three Little Dots" · 2:31 · generated in 146 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-3.0"' \ --form 'prompt="A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax named it after the typing indicator, and its `(Male)` / `(Female)` tags stayed out of the vocal. Lyria 3.5 — "You Go First" · 1:59 · generated in 74 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'prompt="A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria wrote its own two-voice call and response, with the answering lines in parentheses. ACE Music v1 — "Three Dot Bubbles" · 0:41 · generated in 54 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/acemusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="acemusic-v1"' \ --form 'prompt="A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ACE Music also named it after the typing indicator, and wrote its duet with `(Male)`, `(Female)` and `(Both)` in round brackets, as MiniMax did. ### Round 4: Spanish flamenco-pop The language probe — the prompt is English, the song should not be: ``` A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals. ``` TemPolor v4.8 — "Lluvia" · 2:58 · generated in 102 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/song' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model_song="v4.8"' \ --form 'prompt="A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/04-spanish-flamenco-tempolor-v4.8.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Agua de Julio" · 3:32 · generated in 87 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9.5"' \ --form 'prompt="A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/04-spanish-flamenco-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music-3.0 — "Tacones de Lluvia" · 3:07 · generated in 171 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-3.0"' \ --form 'prompt="A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/04-spanish-flamenco-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Lluvia de Verano" · 2:33 · generated in 73 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'prompt="A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/04-spanish-flamenco-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ACE Music v1 — "Fuego en la Tormenta" · 1:22 · generated in 70 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/acemusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="acemusic-v1"' \ --form 'prompt="A fiery flamenco-pop song in Spanish about summer rain, around 60 seconds, passionate female vocals."' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/04-spanish-flamenco-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> All five wrote Spanish lyrics from an English prompt, and all five titled the track in Spanish without being asked. TemPolor's v4.8 is documented as covering [30+ languages](/docs/api-tempolor-v1). One Spanish brief does not test thirty of them, but it answered this one in the right language and named it "Lluvia" unprompted. ## Part 3 — Vocals, our lyrics and an elaborate style brief For the final format each model receives the same original lyrics plus a detailed production brief. Mureka takes these through [music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced) (`lyrics` + a comma-separated style `desc` + `vocal_gender`), while MiniMax, Flow Music and TemPolor all take a `lyrics` field next to the style prompt, so the same body works on three of the four unchanged. ACE Music takes the same two texts as `style` and `lyrics`. ### Round 5: deep house ``` [Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go) ``` ``` Deep house at 121 BPM. Rolling sub-bass groove, shuffled hi-hats, warm Rhodes chord stabs, subtle chopped vocal echoes, smoky intimate female lead vocal, understated hypnotic late-night club production. ``` TemPolor v4.8 — "Low Light" · 1:28 · generated in 51 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/song' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model_song="v4.8"' \ --form 'prompt="Deep house at 121 BPM. Rolling sub-bass groove, shuffled hi-hats, warm Rhodes chord stabs, subtle chopped vocal echoes, smoky intimate female lead vocal, understated hypnotic late-night club production."' \ --form 'lyrics="[Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go)"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-tempolor-v4.8.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Low Light" · 3:09 · generated in 101 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-advanced' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9.5"' \ --form 'lyrics="[Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go)"' \ --form 'desc="deep house, late night, smoky, hypnotic, groovy, 121 bpm, female vocals, warm, understated club production"' \ --form 'vocal_gender="female"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music-3.0 — "Low Light" · 2:47 · generated in 135 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-3.0"' \ --form 'prompt="Deep house at 121 BPM. Rolling sub-bass groove, shuffled hi-hats, warm Rhodes chord stabs, subtle chopped vocal echoes, smoky intimate female lead vocal, understated hypnotic late-night club production."' \ --form 'lyrics="[Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go)"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Velvet Room" · 2:26 · generated in 43 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'prompt="Deep house at 121 BPM. Rolling sub-bass groove, shuffled hi-hats, warm Rhodes chord stabs, subtle chopped vocal echoes, smoky intimate female lead vocal, understated hypnotic late-night club production."' \ --form 'lyrics="[Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go)"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ACE Music v1 — "Two shadows in a velvet" · 1:53 · generated in 52 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/acemusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="acemusic-v1"' \ --form 'style="Deep house at 121 BPM. Rolling sub-bass groove, shuffled hi-hats, warm Rhodes chord stabs, subtle chopped vocal echoes, smoky intimate female lead vocal, understated hypnotic late-night club production."' \ --form 'lyrics="[Verse] Two shadows in a velvet room Moving slow to a midnight tune Say it soft, we do not need more The bass is talking through the floor [Chorus] Keep it low light, low light, hold me near All we need is the bassline here Round and round till the morning shows Low light, low light, do not let go (do not let go, do not let go)"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ### Round 6: jazzy house duet The hardest brief of the set — a two-voice arrangement with live-jazz layers over a house groove, voice roles tagged in the lyrics. The tags are a hint, not an API parameter, so listen for who actually trades verses and who flattens it into one singer. ``` [Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound ``` TemPolor v4.8 — "Blue Hour" · 2:09 · generated in 69 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/song' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model_song="v4.8"' \ --form 'prompt="Jazzy deep house duet at 120 BPM. Rolling deep-house groove with swung hi-hats, walking upright-bass motif over the sub, smoky muted trumpet and tenor-sax licks answering the vocals, extended jazz piano chords, a male and a female lead trading verses and joining in harmony on the chorus, small backing ensemble echoing the hook, warm vinyl texture, sophisticated late-night club production."' \ --form 'lyrics="[Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-tempolor-v4.8.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Blue Hour" · 3:12 · generated in 70 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-advanced' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="V9.5"' \ --form 'lyrics="[Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound"' \ --form 'desc="jazzy deep house, jazz house, duet, male and female vocals, group backing vocals, muted trumpet, saxophone, upright bass, swung, 120 bpm, late night, warm sophisticated production"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music-3.0 — "Blue Hour" · 2:18 · generated in 134 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="music-3.0"' \ --form 'prompt="Jazzy deep house duet at 120 BPM. Rolling deep-house groove with swung hi-hats, walking upright-bass motif over the sub, smoky muted trumpet and tenor-sax licks answering the vocals, extended jazz piano chords, a male and a female lead trading verses and joining in harmony on the chorus, small backing ensemble echoing the hook, warm vinyl texture, sophisticated late-night club production."' \ --form 'lyrics="[Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Blue Hour" · 2:34 · generated in 58 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'prompt="Jazzy deep house duet at 120 BPM. Rolling deep-house groove with swung hi-hats, walking upright-bass motif over the sub, smoky muted trumpet and tenor-sax licks answering the vocals, extended jazz piano chords, a male and a female lead trading verses and joining in harmony on the chorus, small backing ensemble echoing the hook, warm vinyl texture, sophisticated late-night club production."' \ --form 'lyrics="[Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ACE Music v1 — "Blue hour settles on the" · 3:05 · generated in 70 s <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/acemusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="acemusic-v1"' \ --form 'style="Jazzy deep house duet at 120 BPM. Rolling deep-house groove with swung hi-hats, walking upright-bass motif over the sub, smoky muted trumpet and tenor-sax licks answering the vocals, extended jazz piano chords, a male and a female lead trading verses and joining in harmony on the chorus, small backing ensemble echoing the hook, warm vinyl texture, sophisticated late-night club production."' \ --form 'lyrics="[Verse 1 - male] Blue hour settles on the avenue Trumpet smoke and a table for two I talk in rhythm, you answer in rhyme We swing together on borrowed time [Verse 2 - female] You bring the thunder of a double bass I bring the shimmer of a satin dress Piano is asking what the night is about We are the answer when the lights go out [Chorus - both] Meet me in the blue hour, where the bass goes slow (blue hour, blue hour) Sax on the corner and the lights burn low (burn low, burn low) You take the high note, I will hold the ground Blue hour, blue hour - do not stop the sound"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> With the lyrics supplied, the other four took the title from the chorus hook, while ACE Music took the first words of the lyrics. Note that this round's role labels sit inside the section headers — `[Verse 1 - male]` — rather than on their own at the head of a line, which is the form models treat as structure. ## FAQ **What does a song cost through useapi.net?** Through useapi.net, one to two cents: a Music-3.0 song costs about 1¢ on MiniMax Audio Pro, a Lyria 3.5 song 1.1¢ on Flow Music Member, a Mureka V9.5 song 1.8¢ on Mureka Premier and an ACE Music v1 song 2¢ on ACE Music Creator. The official APIs charge 15¢ on [MiniMax](https://platform.minimax.io/docs/pricing/overview#about-music-models) (closed to new users since August 20, 2026), 8¢ on Google's [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) and 15¢ on [Mureka](https://platform.mureka.ai/pricing), prepaid from $1,000 (as of November 2026). See [the lineup](#the-lineup-and-what-it-costs). **Which one is cheapest at high volume?** Through useapi.net, TemPolor. TemPolor Ultra is a flat $29.99 a month with no per-song charge, so each song gets cheaper the more you make: about 3¢ at 1,000 songs a month and 1.5¢ at 2,000. TemPolor's own API charges [$0.04 a call](https://platform.tempolor.com/docs/6665893m0) from a [$100 prepaid package](https://platform.tempolor.com/pricing), so 1,000 songs cost $40 there at any volume (as of November 2026). **Can I run all five from one token?** Through useapi.net, yes. One API token reaches [TemPolor](/docs/api-tempolor-v1), [Mureka](/docs/api-mureka-v1), [MiniMax](/docs/api-minimax-v1), [Flow Music](/docs/api-flowmusic-v1) and [ACE Music](/docs/api-acemusic-v1), and every other service we support. You connect your website subscription with each service once. The request bodies carry over too, since TemPolor takes the same `prompt` and `lyrics` fields as MiniMax, and ACE Music the same texts as `style` and `lyrics`. **How do I pick the newest models?** Through useapi.net, TemPolor's newest models are already the defaults: `v4.8` on [POST music/song](/docs/api-tempolor-v1/post-tempolor-music-song) via `model_song`, and `i4` on [POST music/instrumental](/docs/api-tempolor-v1/post-tempolor-music-instrumental) via `model_instrumental`, with older model names routed to them. Lyria is the exception: pass `model: "lyria-3.5"` on [POST /music](/docs/api-flowmusic-v1/post-flowmusic-music), because `lyria-3-pro` remains the Flow Music default. Pass the model explicitly if your code should record which one made a track. **Can I get more than one track per call?** Through useapi.net, yes on four of the five. MiniMax takes `quantity` up to 3, billed as three songs. Mureka returns two songs per generation and Flow Music an A/B pair, both for the price of one generation, and ACE Music two songs per request, 4 credits for the pair. TemPolor returned one track per call throughout this test, and runs up to ten generations at once on one account. #### Cross posted Also published on [dev.to](https://dev.to/useapi/ai-music-apis-one-generation-later-minimax-music-30-vs-lyria-35-vs-mureka-v95-365p){:rel="nofollow"}, discussed on [Reddit](https://www.reddit.com/r/ThirdPartyAPI/comments/1wq8jon/four_ai_music_apis_compared_tempolor_v48_minimax/){:rel="nofollow"}, shared on [Bluesky](https://bsky.app/profile/useapi.net/post/3mweqttv6bf2e){:rel="nofollow"}, and on [YouTube](https://youtu.be/MSUGckk4JqU) as a 15-minute listening cut. Previous round: [AI Music APIs Compared](/docs/articles/ai-music-api-comparison). === URL: https://useapi.net/docs/articles/dreamina-bash === Document URL: https://useapi.net/docs/articles/dreamina-bash --- layout: default title: How to Generate AI Video with Seedance 2.5 and 2.0 via the Dreamina API description: "Generate Seedance 2.5 and 2.0 video plus Seedream and Nano Banana images via a third-party REST API for Dreamina (CapCut) — copy-paste curl, models, and pricing." keywords: [Dreamina API, Seedance 2.0 API, Seedance 2.5 API, CapCut API, ByteDance, Seedream API, nano banana API, video generation, text to video, image to video] parent: Articles nav_exclude: true date: 2026-06-19 last_modified: 2026-11-20 nav_order: 820 repo: https://github.com/useapi/dreamina-api --- ## How to Generate AI Video with Seedance 2.5 and 2.0 via the Dreamina API 6 min read • June 19, 2026 (November 20, 2026) ## Table of contents ### Introduction [Dreamina](https://dreamina.capcut.com/) puts several frontier video models behind one account — Seedance 2.5 and 2.0 among them — and you can drive every one of them from code. Dreamina is the AI studio at [dreamina.capcut.com](https://dreamina.capcut.com/) from [ByteDance](https://www.bytedance.com/), the company behind [CapCut](https://www.capcut.com/), and [useapi.net](/docs/subscription) fronts it with a third-party [Dreamina API](/docs/api-dreamina-v1) that runs on your Dreamina website subscription over REST. ### Supported models Dreamina runs both video and image models — pick one per request with the `model` field. Availability depends on your account region. Video generation, on [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos) (default `seedance-2.0`): | Model | Region | Durations | Resolution | Input modes | |-------|--------|-----------|------------|-------------| | `seedance-2.5` | US, CA | 4–30s, or 31–180s in long video mode | 480p, 720p, 1080p, 4k (CA only) | Text, first/last frame, Omni Reference, long video, edit | | `seedance-2.5-flash` | CA | 4–30s | 480p, 720p | Text, first/last frame, Omni Reference, edit | | `seedance-2.5-draft` | US, CA | 4–30s | 480p, then [1080p or 4K from the draft](/docs/articles/dreamina-seedance-2-5-draft) | Text, first/last frame, Omni Reference | | `seedance-2.0` | US, CA | 4–15s | 720p, 1080p, 4k | Text, first/last frame, Omni Reference | | `seedance-2.0-fast` | US, CA | 4–15s | 720p, 1080p, 2k, 4k (above 720p, upscaled) | Text, first/last frame, Omni Reference | | `seedance-2.0-mini` | US, CA | 4–15s | 720p, 1080p, 2k, 4k (above 720p, upscaled) | Text, first/last frame, Omni Reference | | `seedance-1.5-pro` | US | 5, 10, 12s | 720p | Text, first/last frame | | `seedance-1.0-pro` | CA | 5, 10s | 1080p | Text, first frame | | `seedance-1.0-mini` | US | 5, 10s | 720p | Text, first frame, multi-frame | | `seedance-1.0-fast` | CA | 5, 10s | 720p, 1080p | Text, first frame, multi-frame | This guide focuses on video, but the same account and token also drive Dreamina's image models — listed here for reference, on [POST /images](/docs/api-dreamina-v1/post-dreamina-images) (default `seedream-4.6`, up to 4 images per request): | Model | Region | Resolution | Max refs | Notes | |-------|--------|------------|----------|-------| | `seedream-4.6` | US, CA | 2k–4k | 6 | Default · runs on a free account's daily credits | | `seedream-5.5` | CA | 1.5k–2k | 6 | Realistic images with complex text, transparent background | | `seedream-5.0-pro` | US, CA | 1.5k–4k (1.5k on CA) | 6 | Cinematic and text-rich visuals | | `seedream-5.0-flash` | US | 1.5k–4k | 6 | — | | `seedream-5.0-lite` | CA | 2k–4k | 6 | — | | `seedream-4.5` | US, CA | 2k–4k | 6 | — | | `seedream-4.1` | US, CA | 2k–4k | 6 | — | | `seedream-4.0` | US, CA | 2k–4k | 6 | | | `seedream-3.1` | CA | 1k–2k | 0 | Text only | | `seedream-3.0` | US, CA | 1k–2k | 1 | Prompt required | | `gpt-image-2.5-flare`, `gpt-image-2.5-sunburst` | US, CA | 1k–4k | 6 | [OpenAI](https://openai.com/), transparent background | | `gpt-image-2` | US, CA | 1k–4k | 6 | Transparent background | | `nano-banana-pro` | US, CA | 1k–4k | 6 | Gemini 3 Pro Image | | `nano-banana-2.1` | CA | 1k–4k | 6 | — | A free Dreamina account makes `seedream-4.6` (the default) images on Dreamina's free daily credits. For the full image workflow, see the [images endpoint](/docs/api-dreamina-v1/post-dreamina-images) and the [Dreamina API overview](/docs/api-dreamina-v1). ### Pricing What one 5-second Seedance 2.0 video costs on ByteDance's official API, [BytePlus ModelArk](https://docs.byteplus.com/en/docs/ModelArk/1544106), and on a [Dreamina Advanced](https://dreamina.capcut.com/pricing/dreamina-price) website subscription billed yearly in each region (October 2026). Each subscription comes with a monthly number of credits, and each video uses a set number of them, so a video costs its share of the subscription. | Model | Official API | US Advanced $75/m (8,645 cr/mo) | Canada Advanced C$108.33/m (11,997 cr/mo) | |---|---|---|---| | Seedance 2.0 Fast, 720p | $0.60 ($0.12 a second) | $0.35 / 40 cr (216 videos/mo) | $0.32 / 50 cr (239 videos/mo) | | Seedance 2.0, 720p | $0.76 ($0.152 a second) | $0.74 / 85 cr (101 videos/mo) | $0.74 / 115 cr (104 videos/mo) | | Seedance 2.0, 1080p | $1.87 ($0.374 a second) | $1.78 / 205 cr (42 videos/mo) | $1.83 / 285 cr (42 videos/mo) | - Both regions run Seedance 2.0 at 1080p and 4K. - Billed yearly, Advanced is $900 a year in the US and C$1,299.99 in Canada. Credit rates come from each region's price metadata, read October 21, 2026, and Canada prices are converted to US dollars at CAD/USD 0.7112. - The [Dreamina overview cost calculator](/docs/api-dreamina-v1) prices every model, including `seedance-2.5`. ### Generate a video in two API calls You need a useapi.net [API token](/docs/start-here/setup-useapi) and a connected [Dreamina account](/docs/start-here/setup-dreamina) — export the token so the `curl` examples below run as-is: `export USEAPI_TOKEN="user:1234-..."`. Generation is asynchronous: the create call returns a `jobid` immediately, then you poll until the video is ready. First, submit the job with `POST https://api.useapi.net/v1/dreamina/videos`: ```bash curl -X POST "https://api.useapi.net/v1/dreamina/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A serene mountain landscape at sunset, camera slowly panning right", "model": "seedance-2.0", "ratio": "16:9", "duration": 5 }' ``` The response returns immediately with a `jobid` and `status: "created"`: ```json { "jobid": "j0223140530...CA:user@example.com-bot:dreamina", "type": "video", "status": "created", "model": "seedance-2.0", "code": 200 } ``` Then poll for the result with `GET https://api.useapi.net/v1/dreamina/videos/{jobid}`: ```bash curl "https://api.useapi.net/v1/dreamina/videos/JOBID" \ -H "Authorization: Bearer $USEAPI_TOKEN" ``` When `status` is `completed`, the finished MP4 is in `response.videoUrl` (the clean, non-watermarked master when available, with `response.videoUrlWatermarked` kept as a fallback): ```json { "jobid": "j0223140530...", "status": "completed", "response": { "videoUrl": "https://v16m-default.tiktokcdn.com/...", "videoUrlWatermarked": "https://v16-cc.capcut.com/..." }, "code": 200 } ``` Seedance 2.0 typically finishes in 60–180 seconds depending on model and duration. Result URLs are signed and expire about 7 days after generation, so download promptly. Prefer not to poll? Pass a `replyUrl` in the create body to receive a webhook callback when the job completes. A job can come back `status: "failed"`, and the create call may return `402` (useapi.net subscription expired), `412` (Dreamina account out of credits), `429` (too many requests), or `596` (account session error) — see the [endpoint docs](/docs/api-dreamina-v1/post-dreamina-videos) for the full list. ### Image-to-video (first / last frame) To animate a still image, upload it first with [POST /assets/`account`](/docs/api-dreamina-v1/post-dreamina-assets-account) (raw bytes, an image `Content-Type`, max 10 MB) — it returns an `assetRef` — then pass that ref as `firstFrameRef` (and optionally `endFrameRef` for a first→last transition): ```bash # 1. Upload the start frame → returns { "assetRef": "..." } curl -X POST "https://api.useapi.net/v1/dreamina/assets/US:user@example.com" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: image/jpeg" \ --data-binary @first_frame.jpeg # 2. Create the video from that frame curl -X POST "https://api.useapi.net/v1/dreamina/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "the character turns and smiles", "model": "seedance-2.0", "duration": 5, "firstFrameRef": "ASSET_REF_FROM_STEP_1" }' ``` When you provide image frames, the aspect ratio is auto-detected from the image — do not set `ratio`. A first+last frame pair must share the same aspect ratio. > Seedance 2.0 / 2.0 Fast reject real human faces at content moderation — use illustrated, anime, or stylized characters. For a working real-face workflow, see the [Seedance 2.0 real-face tutorial (Runway → Dreamina)](/blog/260415), which generates the real-face start frame in Runway and animates it in Dreamina. ### Batch-generate with a script Finding the right shot takes many attempts, and running them by hand is tedious. The Node.js script below reads a list of prompts from `prompts.json`, uploads any first/last frame images, submits each job, then polls and downloads every finished MP4 — so you can queue a batch and come back to the winners. You need [Node.js](https://nodejs.org) v21 or newer. Put `prompts.json` and `dreamina.mjs` in the same folder and run `node ./dreamina.mjs API_TOKEN EMAIL`, where `API_TOKEN` is your useapi.net [API token](/docs/start-here/setup-useapi) and `EMAIL` is your connected [Dreamina account](/docs/start-here/setup-dreamina) email. Dreamina accounts are identified as `REGION:email` (e.g. `US:user@example.com`), and the script looks yours up by email automatically. <details markdown="block"> <summary>Expand `prompts.json`</summary> ```json [ { "prompt": "By default the seedance-2.0 model with a 16:9 ratio, 720p resolution and a 5-second duration will be used." }, { "model": "seedance-2.0", "ratio": "16:9", "duration": 10, "resolution": "720p", "prompt": "A serene mountain landscape at sunset with the camera slowly panning right. For all parameters see https://useapi.net/docs/api-dreamina-v1/post-dreamina-videos" }, { "model": "seedance-2.0", "duration": 5, "firstFrame": "./first_frame.jpeg", "lastFrame": "./last_frame.jpeg", "prompt": "Image-to-video with a start frame (firstFrame → firstFrameRef) and an end frame (lastFrame → endFrameRef). When image frames are provided, ratio is auto-detected and must not be set." }, { "model": "seedance-2.0-fast", "duration": 5, "firstFrame": "./image.jpeg", "prompt": "Faster Seedance 2.0 Fast generation from a single start frame. Other models (seedance-2.5, seedance-2.0-mini, seedance-1.5-pro, on US accounts seedance-1.0-mini, and on CA accounts seedance-1.0-pro / seedance-1.0-fast) are selectable via the model field — see the videos docs." } ] ``` </details> <details markdown="block"> <summary>Expand `dreamina.mjs` script</summary> ```javascript /* Script version 1.0, June 19, 2026 Script to batch-generate videos using prompts with the Dreamina API v1 by useapi.net 🚀 Defaults to the seedance-2.0 model and uses the asynchronous videos endpoint. For more details visit https://useapi.net/docs/api-dreamina-v1/post-dreamina-videos Installation Instructions: ========================== You need Node.js v21 or newer installed to run this script. Download and install Node.js from: - Windows, macOS, Linux: https://nodejs.org/ After installation, verify by running the following command in a terminal: node -v Running the Script: =================== Usage: node dreamina.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE] Replace API_TOKEN with your actual useapi.net API token, see https://useapi.net/docs/start-here/setup-useapi Replace EMAIL with configured Dreamina email account, see https://useapi.net/docs/start-here/setup-dreamina If optional PROMPTS_FILE not provided prompts.json will be used. Example: -------- node dreamina.mjs user:1234-abcdefhijklmnopqrstuv my@email.com This command executes the script using API token user:1234-abcdefhijklmnopqrstuv with my@email.com Dreamina account email. Changelog: ========== - June 19, 2026: Initial release. */ import readline from 'node:readline'; import fs from 'fs/promises'; import path from 'path'; import { writeFile } from 'node:fs/promises'; import { Readable } from 'node:stream'; // Constants const RESULTS_FILE = 'dreamina_results.txt'; const ERRORS_FILE = 'dreamina_errors.txt'; const DEFAULT_PROMPTS_FILE = 'prompts.json'; const DEFAULT_MODEL = 'seedance-2.0'; const SLEEP_429 = 10 * 1000; // in milliseconds const MAX_429_RETRIES = 6; // give up a prompt after this many consecutive 429s (all accounts busy) const SLEEP_DOWNLOAD = 20 * 1000; // in milliseconds const urlAccounts = 'https://api.useapi.net/v1/dreamina/accounts'; const urlVideos = 'https://api.useapi.net/v1/dreamina/videos'; const urlVideosJob = 'https://api.useapi.net/v1/dreamina/videos/'; const urlAssets = 'https://api.useapi.net/v1/dreamina/assets/'; // Supported image extensions mapped to their upload Content-Type. // See https://useapi.net/docs/api-dreamina-v1/post-dreamina-assets-account const imageContentTypes = { jpeg: 'image/jpeg', jpg: 'image/jpeg', png: 'image/png', webp: 'image/webp' }; const supportedFileExtensions = Object.keys(imageContentTypes); // { filename: assetRef } const uploadedFiles = {}; // Utility to sleep for given milliseconds const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); // Function to fetch configured Dreamina API accounts async function fetchAccounts(apiToken) { const response = await fetch(urlAccounts, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.error(`⛔ Error fetching accounts (HTTP ${response.status}): ${response.statusText}`); process.exit(1); } return response.json(); } const elapsedTimeSec = (start) => (Date.now() - start) / 1000; // Upload a first/last frame image and return its reusable assetRef. // The asset is uploaded to the account that owns the generation (REGION:email). async function uploadAsset(apiToken, account, filename) { // Check if already uploaded if (uploadedFiles.hasOwnProperty(filename)) return uploadedFiles[filename]; const startTime = Date.now(); console.log(`⬆️ Account ${account} uploading file…`, filename); const body = new Blob([await fs.readFile(filename)]); const fileExt = filename.split('.').pop().toLowerCase(); const contentType = imageContentTypes[fileExt]; const response = await fetch(`${urlAssets}${encodeURIComponent(account)}`, { method: 'POST', headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}`, 'Content-Type': contentType }, body }); if (response.ok) { const json = await response.json(); const { assetRef } = json; console.log(`🆗 assetRef (${elapsedTimeSec(startTime)} sec)`, assetRef); uploadedFiles[filename] = assetRef; } else { console.error(`❗ Unable to upload file HTTP ${response.status} (${elapsedTimeSec(startTime)} sec)`, await response.text()); // Do not attempt to upload failed file again uploadedFiles[filename] = undefined; } return uploadedFiles[filename]; } async function submit(apiToken, url, body, index, prompt) { const createResponse = await fetch(url, { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiToken}` }, body }); const createBody = await createResponse.text(); if (createResponse.status == 200) { const json = JSON.parse(createBody); const { jobid } = json; if (jobid) { await fs.appendFile(RESULTS_FILE, `${jobid},#${index}:${prompt}\n`); console.log(`✅ jobid`, jobid); return 200; } else { const error = `No jobid found in HTTP 200 response`; console.log(`❓ ${error}`, createBody); await fs.appendFile(ERRORS_FILE, `${error},#${index}:${prompt}\n`); return 500; } } else { switch (createResponse.status) { case 429: console.log(`🔄️ Retry on HTTP ${createResponse.status} (all accounts at capacity)`); break; case 400: console.log(`🛑 Validation error`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${prompt}\n`); break; case 402: console.log(`🛑 useapi.net subscription expired`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${prompt}\n`); break; case 412: console.log(`🛑 Dreamina account out of credits`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${prompt}\n`); break; case 596: console.log(`🛑 Account session expired — re-add the account at https://useapi.net/docs/api-dreamina-v1/post-dreamina-accounts`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${prompt}\n`); break; default: console.log(`❗ FAILED with HTTP ${createResponse.status}`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${prompt}\n`); } return createResponse.status; } } // Submit a single prompt to the videos endpoint. // firstFrame → firstFrameRef (start frame), lastFrame → endFrameRef (end frame). async function submitVideo(apiToken, account, prompt, index) { const { model, prompt: text, firstFrame, lastFrame, ratio, duration, resolution } = prompt; const useModel = model ?? DEFAULT_MODEL; console.log(`🚀 ${useModel} » Prompt #${index} • account ${account} • ${duration ?? 5} secs …`); const firstFrameRef = firstFrame ? await uploadAsset(apiToken, account, firstFrame) : undefined; const endFrameRef = lastFrame ? await uploadAsset(apiToken, account, lastFrame) : undefined; // ratio is auto-detected from image dimensions and must not be sent when frames are provided. const useRatio = (firstFrameRef || endFrameRef) ? undefined : ratio; const body = JSON.stringify({ account, model: useModel, prompt: text, ratio: useRatio, duration, resolution, firstFrameRef, endFrameRef }); return await submit(apiToken, urlVideos, body, index, text); } // Function to download videos async function download(apiToken) { if (! await fileExists(RESULTS_FILE)) return; try { const resultsContent = await fs.readFile(RESULTS_FILE, 'utf8'); const lines = resultsContent.trim().split('\n'); for (const line of lines) { const [jobid, prompt] = line.split(','); const videoFilename = `${jobid.replace(/:/g, '_')}.mp4`; console.log(`👉 ${jobid}`); try { await fs.access(videoFilename); console.log(`⚠️ ${videoFilename} already exists. Skipping download.`); continue; } catch { // File does not exist, proceed with downloading } while (true) { const response = await fetch(`${urlVideosJob}${jobid}`, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.log(`🛑 Poll failed ${jobid} (HTTP ${response.status}):\n${prompt}\n`, await response.text()); break; } const job = await response.json(); const { status, response: result, error, errorDetails } = job; if (status == 'failed') { console.error(`🛑 FAILED ${jobid} (${error}${errorDetails ? ` — ${errorDetails}` : ''}):\n${prompt}\n`); break; } if (status == 'completed') { // Prefer the clean master; fall back to the watermarked variant. const url = result?.videoUrl ?? result?.videoUrlWatermarked; if (url) { console.log(`✅ Downloading ${url} to ${videoFilename}`); try { const videoResponse = await fetch(url); if (!videoResponse.ok) { console.error(`⛔ Unable to download ${jobid} (HTTP ${videoResponse.status}):\n${prompt}\n`, url); break; } const stream = Readable.fromWeb(videoResponse.body); await writeFile(videoFilename, stream); } catch (err) { console.error(`⛔ Error during download: ${err}`); } } else console.error(`🛑 Unable to download ${jobid}, no videoUrl in completed job:\n${prompt}\n`); break; } console.log(`⌛ ${jobid} status (${status}) and is still in progress, waiting…`); await sleep(SLEEP_DOWNLOAD); } } } catch (error) { console.log(`⛔ Error during download:`, error.stack || error); } } // Main function async function main() { const apiToken = process.argv[2]; const email = process.argv[3]; const promptFile = process.argv[4] || DEFAULT_PROMPTS_FILE; if (!apiToken || !email) { console.error('Usage: node dreamina.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE]'); process.exit(1); } console.info('Script v1.0'); console.info('Node version is: ' + process.version); try { if (await fileExists(RESULTS_FILE)) { let user_input; while (!['y', 'n'].includes(user_input)) { user_input = (await promptUser(`❔ ${RESULTS_FILE} file detected. Do you want to download the results now? (y/n): `))?.toLowerCase(); if (user_input == 'y') { await download(apiToken); await fs.unlink(RESULTS_FILE); } } } const start = new Date(); try { console.info('START EXECUTION', start); await execute(apiToken, email, promptFile); // Pass the promptFile to execute function } finally { console.info('COMPLETED', new Date()); console.info('EXECUTION ELAPSED', diffInMinutesAndSeconds(start, new Date())); } try { console.info('START DOWNLOAD', start); await download(apiToken); } finally { console.info('TOTAL ELAPSED', diffInMinutesAndSeconds(start, new Date())); } } catch (error) { console.error('⛔ Error during execution:', error.stack || error); } } // Modify the execute function to accept promptFile as a parameter async function execute(apiToken, email, promptFile) { const accounts = await fetchAccounts(apiToken); const accountList = Object.values(accounts); console.info(`Configured Dreamina API accounts (${accountList.length}):`, accountList.map(a => a.account).join(', ')); if (accountList.length <= 0) { console.error(`⛔ No configured Dreamina accounts found. Please refer to https://useapi.net/docs/start-here/setup-dreamina`); process.exit(1); } // Dreamina accounts are keyed as REGION:email — match by email. const matched = accountList.find(a => a.email === email); if (!matched) { console.error(`⛔ Account with email ${email} not found. Please refer to https://useapi.net/docs/start-here/setup-dreamina`); process.exit(1); } if (matched.error) { console.error(`⛔ Account ${matched.account} has pending error. Please resolve and re-add the account at https://useapi.net/docs/api-dreamina-v1/post-dreamina-accounts`); process.exit(1); } const account = matched.account; const promptData = await fs.readFile(promptFile, 'utf8'); const prompts = JSON.parse(promptData); console.log(`Total number of prompts to process`, prompts.length); let warnings = []; // Parameters accepted by this script for the videos endpoint. // See https://useapi.net/docs/api-dreamina-v1/post-dreamina-videos for the full parameter set. const supportedParams = ['model', 'prompt', 'firstFrame', 'lastFrame', 'ratio', 'duration', 'resolution']; const invalidKeys = (prompt) => Object.keys(prompt).filter(key => !key.startsWith('__') && !supportedParams.includes(key)) for (let i = 1; i <= prompts.length; i++) { const prompt = prompts[i - 1]; const { prompt: text, firstFrame, lastFrame } = prompt; const validateImage = async (file) => { if (file) { try { await fs.access(file); } catch { warnings.push(`⚠️ Image '${file}' does not exist. Prompt ${i}`); } const ext = file.split('.').pop().toLowerCase(); if (!supportedFileExtensions.includes(ext)) warnings.push(`⚠️ Image ${file} extension ${ext} not supported. Prompt ${i}`); } }; const notSupported = invalidKeys(prompt); if (notSupported.length) warnings.push(`⚠️ Following params not supported: ${notSupported.join(',')}. Prompt ${i}`); if (!text && !firstFrame) warnings.push(`⚠️ Please specify a prompt and/or a firstFrame image. Prompt ${i}`); if (lastFrame && !firstFrame) warnings.push(`⚠️ lastFrame (endFrameRef) requires firstFrame (firstFrameRef). Prompt ${i}`); await Promise.all([validateImage(firstFrame), validateImage(lastFrame)]); } if (warnings.length > 0) { warnings.forEach(warning => console.warn(warning)); console.error(`⛔ Execution stopped due to warnings.`); process.exit(1); } for (let i = 0; i < prompts.length; i++) { const prompt = prompts[i]; let retries429 = 0; while (true) { const responseCode = await submitVideo(apiToken, account, prompt, i + 1); if (responseCode == 429) { if (++retries429 > MAX_429_RETRIES) { console.error(`⛔ Gave up on prompt #${i + 1} after ${MAX_429_RETRIES} retries — all accounts still busy.`); await fs.appendFile(ERRORS_FILE, `429 (gave up after ${MAX_429_RETRIES} retries),#${i + 1}\n`); break; } await sleep(SLEEP_429); } else if (responseCode == 402 || responseCode == 412 || responseCode == 596) { process.exit(1); } else break; } } } // Utility function to check if a file exists async function fileExists(path) { try { await fs.access(path); return true; } catch { return false; } } // Function to prompt user input async function promptUser(query) { const rl = readline.createInterface({ input: process.stdin, output: process.stdout }); return new Promise((resolve) => rl.question(query, answer => { rl.close(); resolve(answer); })); } function diffInMinutesAndSeconds(date1, date2) { const diffInSeconds = Math.floor((date2 - date1) / 1000); return `${Math.floor(diffInSeconds / 60)} minutes ${diffInSeconds % 60} seconds`; }; main(); ``` </details> ### Examples The clips below are real Seedance 2.0 generations produced through this Dreamina API, straight from our blog walkthroughs. ###### Omni Reference — interleaved text + image references (`@image1`/`@image2`/`@image3`) <video poster="https://media.useapi.net/blog/2026-04-02-260402/seedance-2.0-omni-poster.jpg" controls width="100%"> <source src="https://media.useapi.net/blog/2026-04-02-260402/seedance-2.0-omni.mp4" type="video/mp4"> </video> — from [Dreamina: Seedance 2.0 Video Generation](/blog/260402) ###### Text-to-video — prompt only, with natively generated audio <video poster="https://media.useapi.net/blog/2026-02-23-260223/seedance-20-t2v-result-poster.jpg" src="https://media.useapi.net/blog/2026-02-23-260223/seedance-20-t2v-result.mp4" style="width: 100%; aspect-ratio: 9/16; max-width: 400px;" controls type="video/mp4" preload="metadata"></video> — from [Dreamina: Seedance 2.0 Launch Examples](/blog/260223) More Seedance 2.0 clips from that post on YouTube: [Selfie Situation • Seedance 2.0](https://youtube.com/shorts/TYlg9cVyNy4), [A Very Talented Man • Seedance 2.0](https://youtube.com/shorts/AZKeOy4u1t4). ###### Omni Reference with a real face — 15s 9:16 (Runway → Dreamina workflow) <video poster="https://media.useapi.net/blog/2026-04-15-260415/seedance-grid-result-poster.jpg" src="https://media.useapi.net/blog/2026-04-15-260415/seedance-grid-result.mp4" style="width: 100%; max-width: 400px;" controls type="video/mp4" preload="metadata"></video> — from [Seedance 2.0: Using Real Faces](/blog/260415) Related tutorials: [Seedance 2.0 and 2.5 API pricing compared](/docs/articles/seedance-2-api-pricing), [Sora 2 API alternatives](/docs/articles/sora-2-api-alternatives) and [PixVerse V6 video via the PixVerse API](/docs/articles/pixverse-demo). ### Use it from Claude, ChatGPT or Cursor The hosted [Dreamina MCP server](/docs/api-dreamina-v1/mcp) gives Claude Code, Cursor, VS Code and other MCP clients this Dreamina API as 15 tools, with nothing to install, and the Claude app and ChatGPT connect to it with a sign-in. It runs on your own Dreamina accounts with your useapi.net API token. In Claude Code: ```bash claude mcp add --transport http useapi-dreamina https://api.useapi.net/v1/dreamina/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` Then ask in plain words, for example "Make a 10-second Seedance 2.0 video of a paper boat drifting down a rainy street at night, 9:16". The assistant calls `dreamina_create_video` with the same models, frames and omni references as the curl calls above and hands back the video link. The server is listed in the official MCP Registry as `net.useapi/dreamina`, and the [`dreamina-api`](https://github.com/useapi/dreamina-api#use-with-claude-code) repo also installs as a Claude Code plugin or a [Gemini CLI extension](https://github.com/useapi/dreamina-api#use-with-gemini-cli). ### Frequently asked questions **Is there a Seedance 2.0 API?** Through useapi.net, yes: the Dreamina API runs Seedance 2.0 and the rest of the Seedance family on your Dreamina website subscription over REST, and Dreamina has no public developer API of its own (as of October 2026). The same route runs long Seedance 2.5 videos of 31 to 180 seconds in one job, where ByteDance's [BytePlus ModelArk](https://docs.byteplus.com/en/docs/ModelArk/1544106) stops at 30 seconds a clip. **How much does Seedance 2.0 cost through the API?** Through useapi.net, a 5-second Seedance 2.0 video at 1080p costs about $1.78 on a US Dreamina Advanced website subscription billed yearly ($1.83 in Canada), against $1.87 on ByteDance's [BytePlus ModelArk](https://docs.byteplus.com/en/docs/ModelArk/1544106), and a 720p Seedance 2.0 Fast video about $0.32 against $0.60 (as of October 2026). See [Pricing](#pricing) for both plans. **Do I need ByteDance enterprise approval?** Through useapi.net, no. You call the API with a useapi.net [API token](/docs/start-here/setup-useapi) and connect your Dreamina website subscription through [Setup Dreamina](/docs/start-here/setup-dreamina), with no BytePlus account, no prepaid pack and no enterprise onboarding. On Seedance 2.5 it also accepts photographic portraits in references, which ByteDance's official API restricts to verified assets or an enterprise contract from $14,000 a year (see the [Seedance pricing comparison](/docs/articles/seedance-2-api-pricing)). **Can I generate images (Seedream, Nano Banana) too?** Through useapi.net, yes. The same Dreamina website subscription drives [POST /images](/docs/api-dreamina-v1/post-dreamina-images) with Seedream 5.5, 5.0 Pro, 5.0 Flash, 5.0 Lite, 4.7, 4.6, 4.5, 4.1, 4.0, 3.1 and 3.0, GPT Image 2.5 and 2, and Nano Banana Pro and 2.1, up to 4 images per request. The default `seedream-4.6` also runs on a free account's daily credits. See [Supported models](#supported-models) above. ### Conclusion Visit our <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> or <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> for any support questions and concerns. The full runnable example is in the [`dreamina-api` GitHub repo](https://github.com/useapi/dreamina-api). === URL: https://useapi.net/docs/articles/dreamina-seedance-2-5-draft-es === Document URL: https://useapi.net/docs/articles/dreamina-seedance-2-5-draft-es --- layout: default title: Cómo hacer borradores de videos Seedance 2.5 en 480p y terminarlos en 1080p o 4K con la API de Dreamina seo_title: "API del modo borrador de Seedance 2.5: de 480p a 1080p o 4K" description: "Modo borrador (draft) de Seedance 2.5 con la API de Dreamina de useapi.net: haz un borrador en 480p, revísalo y convierte el mismo video en 1080p o 4K. Código completo, videos reales, créditos." keywords: [Seedance 2.5 draft mode, modo borrador Seedance 2.5, Seedance 2.5 draft API, API Seedance 2.5 draft, borrador Seedance 2.5 a 1080p, Seedance 2.5 draft to 1080p, Seedance 2.5 4K, Seedance 2.5 API, API de Seedance 2.5, Dreamina API, API de Dreamina, Dreamina full quality, Dreamina calidad completa, Dreamina Seedance 2.5, ByteDance Seedance, tutorial Seedance 2.5] image: https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-draft-vs-full-quality-dancer-detail.jpg parent: Articles nav_exclude: true lang: es date: 2026-11-12 last_modified: 2026-11-20 nav_order: 821 repo: https://github.com/useapi/dreamina-api translation_key: seedance-2-5-draft --- ## Cómo hacer borradores de videos Seedance 2.5 en 480p y terminarlos en 1080p o 4K con la API de Dreamina {: .no_toc #how-to-draft-seedance-25-videos-at-480p-and-finish-them-in-1080p-or-4k-with-the-dreamina-api } 5 min de lectura • 12 de noviembre de 2026 (20 de noviembre de 2026) ## Índice {: .no_toc .text-delta #table-of-contents } ### Introducción La [API de Dreamina](/docs/api-dreamina-v1) de useapi.net hace un borrador de [Seedance 2.5](https://docs.byteplus.com/en/docs/modelark/seedance-2-5) en 480p por cerca de una séptima parte del precio del mismo video en 1080p. Cuando el borrador te convence, una llamada más a [POST /videos/full-quality](/docs/api-dreamina-v1/post-dreamina-videos-full-quality) convierte ese mismo borrador en un video 1080p, o 4K en una cuenta canadiense. El video en calidad completa conserva la escena, el movimiento y el ritmo del borrador, así que solo pagas el precio completo por la toma que ya aprobaste. Un video 4K de 5 segundos cuesta aquí unos US$4,15 en un plan Advanced canadiense, frente a US$4,57 en la propia API de ByteDance (a 18 de noviembre de 2026). La API usa la suscripción de [Dreamina](https://dreamina.capcut.com/) que ya tienes, igual que el botón "Generate in full quality" en el sitio web de Dreamina. El borrador en 480p y el video 1080p hecho a partir de él, lado a lado: <video src="https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-draft-vs-full-quality-dancer-side-by-side.mp4" poster="https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-draft-vs-full-quality-dancer-side-by-side-poster.jpg" style="width: 100%; max-width: 720px; aspect-ratio: 1450/1280;" controls type="video/mp4" preload="metadata"></video> Abajo están las solicitudes que generan los dos videos y los créditos que usó cada paso. ### ¿Cómo funciona el modo borrador de Seedance 2.5? 1. Envía tu prompt a [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos) con `model: "seedance-2.5-draft"`. Recibes un video 480p de 4 a 30 segundos, a partir de texto, de un fotograma inicial y uno final, o de hasta 50 referencias (30 imágenes, 10 videos, 10 clips de audio), las mismas entradas que acepta `seedance-2.5`. 2. Mira el video. Si no está bien, cambia el prompt y haz otro borrador. 3. En un plazo de 14 días, envía el `jobid` del borrador a [POST /videos/full-quality](/docs/api-dreamina-v1/post-dreamina-videos-full-quality) con `resolution` `1080p` o `4k`. Dreamina genera el video en calidad completa a partir de ese borrador, con su prompt, sus referencias, su duración y su relación de aspecto. Las cuentas de EE. UU. y de Canadá hacen borradores y videos 1080p. El 4K requiere una cuenta canadiense. Los dos pasos requieren un plan de pago de Dreamina. Dreamina no hace [upscale](/docs/api-dreamina-v1/post-dreamina-videos-upscale) de un borrador: su único paso siguiente es la calidad completa. Un video 1080p en calidad completa admite upscale como cualquier otro. ### Precios La calidad completa cuesta lo mismo que generar el video con `seedance-2.5` en esa resolución. El borrador es una generación más encima de eso, sea el paso siguiente en 1080p o en 4K, así que conviene cuando de todos modos probarías un prompt más de una vez. Los precios del borrador y de todos los demás modelos están en la [calculadora de costos](/docs/start-here/setup-dreamina#cost-calculator). ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. ### Paso 1: haz el borrador Los pasos de abajo usan `curl` puro. El mismo flujo en un solo script, en Node.js y Python, está en [useapi/dreamina-api](https://github.com/useapi/dreamina-api/tree/main/seedance-draft) en GitHub. Necesitas un [token de API](/docs/start-here/setup-useapi) de useapi.net y una cuenta de Dreamina con plan de pago, conectada con [Setup Dreamina](/docs/start-here/setup-dreamina). ```bash curl --location 'https://api.useapi.net/v1/dreamina/videos' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="seedance-2.5-draft"' \ --form 'duration="4"' \ --form 'ratio="9:16"' \ --form 'prompt="Pretty lady dancing"' ``` Si omites `account`, la API elige una de tus cuentas de Dreamina con capacidad libre. La respuesta trae el `jobid`: ```json { "jobid": "j1112160042000000000v-u12345-CA:user@example.com-bot:dreamina", "type": "video", "status": "created", "model": "seedance-2.5-draft" } ``` ### Paso 2: espera y míralo Consulta [GET /videos/`jobid`](/docs/api-dreamina-v1/get-dreamina-videos-jobid) cada 15 segundos más o menos, o pasa `replyUrl` en el paso 1 y recibe el resultado por POST en tu dirección. ```bash curl --location 'https://api.useapi.net/v1/dreamina/videos/j1112160042000000000v-u12345-CA:user@example.com-bot:dreamina' \ --header 'Authorization: Bearer user:12345-…' ``` ```json { "jobid": "j1112160042000000000v-u12345-CA:user@example.com-bot:dreamina", "status": "completed", "model": "seedance-2.5-draft", "response": { "videoUrl": "https://…/video.mp4", "width": 480, "height": 854, "durationMs": 4042 } } ``` Nuestro borrador estuvo listo en 85 segundos, un video de 480×854 por 68 créditos: <video src="https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-draft-dancer-480p.mp4" poster="https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-draft-dancer-480p-poster.jpg" style="width: 100%; max-width: 400px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> ### Paso 3: convierte el borrador en un video en calidad completa El borrador quedó como queríamos, así que su `jobid` va a [POST /videos/full-quality](/docs/api-dreamina-v1/post-dreamina-videos-full-quality): ```bash curl --location 'https://api.useapi.net/v1/dreamina/videos/full-quality' \ --header 'Authorization: Bearer user:12345-…' \ --form 'jobid="j1112160042000000000v-u12345-CA:user@example.com-bot:dreamina"' \ --form 'resolution="1080p"' ``` El video se genera en la misma cuenta del borrador. La respuesta es un nuevo job de video, que se consulta de la misma forma. Conserva `model: "seedance-2.5-draft"`, y `request.resolution` y `request.draftJobid` lo distinguen del borrador: ```json { "jobid": "j1112160306000000000v-u12345-CA:user@example.com-bot:dreamina", "type": "video", "status": "created", "model": "seedance-2.5-draft", "request": { "inputMode": "full_quality", "resolution": "1080p", "draftJobid": "j1112160042000000000v-u12345-CA:user@example.com-bot:dreamina" } } ``` Estuvo listo en unos 2 minutos, un video de 1080×1920 por 468 créditos: <video src="https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-full-quality-dancer-1080p.mp4" poster="https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-full-quality-dancer-1080p-poster.jpg" style="width: 100%; max-width: 400px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> Para 4K, envía `resolution: "4k"` a partir de un borrador hecho en una cuenta canadiense. Dreamina ofrece esa opción ahí, aunque nuestras pruebas se hicieron en 1080p. La API de la propia ByteDance añadió Seedance 2.5 en 4K el 16 de noviembre de 2026, a US$4,57 por 5 segundos. Aquí el mismo video 4K cuesta unos US$4,15 en un plan Advanced canadiense. El video final es un job de video normal, así que todavía puedes hacer [upscale](/docs/api-dreamina-v1/post-dreamina-videos-upscale) de un video 1080p o [aumentar su tasa de fotogramas](/docs/api-dreamina-v1/post-dreamina-videos-interpolate). Un job que no sea un borrador terminado, un borrador de más de 14 días o `4k` en una cuenta de EE. UU. recibe `400`. Una cuenta de Dreamina sin plan de pago recibe `403`, y una cuenta sin créditos, `412`. Un job que falla más tarde aparece con `status: "failed"` y un `error` cuando lo consultas. ### Borrador y calidad completa, lado a lado Los dos videos son la misma toma: los movimientos, el giro de la cabeza, el guiño y el ritmo coinciden del primer al último fotograma. Este es el mismo momento, a los 3,5 segundos, recortado de los dos. El borrador, ampliado a 1080p, está a la izquierda, y el video en calidad completa, a la derecha: ![El mismo fotograma del video de la bailarina en el borrador de Seedance 2.5 (a la izquierda, 480p ampliado) y en el video 1080p en calidad completa (a la derecha): el mismo guiño, con pestañas, cabello y piel más nítidos](https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-draft-vs-full-quality-dancer-detail.jpg) Las pestañas, los mechones sueltos y la piel salen nítidos, sin que nada del rostro cambie de lugar. ### Úsalo desde Claude, ChatGPT o Cursor El [servidor MCP de Dreamina](/docs/api-dreamina-v1/mcp) que aloja useapi.net lleva este flujo de borrador y calidad completa a Claude Code, Cursor, VS Code y otros clientes MCP, sin instalar nada, y la app de Claude y ChatGPT se conectan a él iniciando sesión. Tiene 15 herramientas y funciona con tus propias cuentas de Dreamina y tu token de API de useapi.net. En Claude Code: ```bash claude mcp add --transport http useapi-dreamina https://api.useapi.net/v1/dreamina/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` Después pide, por ejemplo: "Haz un borrador de Seedance 2.5 con este prompt y, si se ve bien, genéralo en calidad completa a 1080p". El asistente hace el borrador con `dreamina_create_video` y `seedance-2.5-draft`, te muestra el enlace y, cuando lo apruebas, convierte esa toma en 1080p, o en 4K en una cuenta canadiense, con `dreamina_full_quality_video`. El servidor está en el registro oficial de MCP como `net.useapi/dreamina`, y el repositorio [`dreamina-api`](https://github.com/useapi/dreamina-api#use-with-claude-code) también se instala como plugin de Claude Code o como [extensión de Gemini CLI](https://github.com/useapi/dreamina-api#use-with-gemini-cli). ### Preguntas #### ¿Existe una API del modo borrador de Seedance 2.5? Sí. La API de Dreamina de useapi.net genera videos `seedance-2.5-draft` en 480p y los convierte en 1080p, o en 4K en una cuenta canadiense de Dreamina, con la suscripción de Dreamina que ya pagas. La API de la propia ByteDance también tiene modo borrador. En 4K, un video final cuesta aquí unos US$4,15 en un plan Advanced canadiense, frente a US$4,57 en la API de ByteDance, sin paquete prepagado (a 18 de noviembre de 2026). #### ¿Cuánto cuesta un borrador de Seedance 2.5? Con useapi.net, un borrador de Seedance 2.5 de 5 segundos cuesta 65 créditos en una cuenta de Dreamina de EE. UU. y 85 en una canadiense, cerca de US$0,59 o US$0,55 en el plan Advanced (a noviembre de 2026). Después, el video en calidad completa cuesta lo mismo que un video `seedance-2.5` en esa resolución, así que el borrador es una generación más que te evita pagar tomas en calidad completa que terminarías descartando. Consulta [Precios](#pricing). #### ¿El video en calidad completa se ve igual que el borrador? Sí. Con la API de Dreamina de useapi.net, el video en calidad completa se genera a partir de tu borrador, así que conserva la misma toma, el mismo movimiento y el mismo ritmo, solo que más nítido, como muestra la comparación lado a lado de arriba. Enviar el mismo prompt otra vez a `seedance-2.5` generaría un video distinto. #### ¿Puedo hacer un video Seedance 2.5 en 4K a partir de un borrador? Sí, con useapi.net en una cuenta canadiense de Dreamina: envía el `jobid` del borrador a [POST /videos/full-quality](/docs/api-dreamina-v1/post-dreamina-videos-full-quality) con `resolution: "4k"`, al precio de un video `seedance-2.5` en 4K. Las cuentas de EE. UU. hacen 1080p. Ese video 4K cuesta unos US$4,15 en un plan Advanced canadiense, frente a US$4,57 en la propia API de ByteDance (a 18 de noviembre de 2026). ### Conclusión Un borrador de Seedance 2.5 te permite probar una idea en 480p por una fracción del precio y quedarte exactamente con la toma que te gusta, en 1080p o 4K. Haz uno con [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos) y `seedance-2.5-draft`, y luego termínalo con [POST /videos/full-quality](/docs/api-dreamina-v1/post-dreamina-videos-full-quality). El flujo completo es un solo script, en Node.js y Python, en GitHub: [useapi/dreamina-api/seedance-draft](https://github.com/useapi/dreamina-api/tree/main/seedance-draft). Conecta tu cuenta de Dreamina con [Setup Dreamina](/docs/start-here/setup-dreamina) y consulta la [descripción general de la API de Dreamina](/docs/api-dreamina-v1) para ver todos los modelos. === URL: https://useapi.net/docs/articles/dreamina-seedance-2-5-draft-id === Document URL: https://useapi.net/docs/articles/dreamina-seedance-2-5-draft-id --- layout: default title: Cara Membuat Draft Video Seedance 2.5 di 480p dan Menyelesaikannya di 1080p atau 4K dengan Dreamina API seo_title: "Seedance 2.5 Draft Mode API: Draft 480p ke 1080p atau 4K" description: "Mode draft Seedance 2.5 dengan Dreamina API useapi.net: buat draft 480p, periksa, lalu ubah video yang sama menjadi 1080p atau 4K. Kode lengkap, video asli, kredit." keywords: [Seedance 2.5 draft mode, mode draft Seedance 2.5, Seedance 2.5 draft API, API draft Seedance 2.5, Seedance 2.5 draft ke 1080p, Seedance 2.5 draft to 1080p, Seedance 2.5 4K, video Seedance 2.5 4K, Seedance 2.5 API, API Seedance 2.5, Dreamina API, API Dreamina, Dreamina full quality, Dreamina Seedance 2.5, ByteDance Seedance, tutorial bahasa Indonesia, curl] image: https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-draft-vs-full-quality-dancer-detail.jpg parent: Articles nav_exclude: true lang: id translation_key: seedance-2-5-draft date: 2026-11-12 last_modified: 2026-11-20 nav_order: 821 repo: https://github.com/useapi/dreamina-api --- ## Cara Membuat Draft Video Seedance 2.5 di 480p dan Menyelesaikannya di 1080p atau 4K dengan Dreamina API {: .no_toc #how-to-draft-seedance-25-videos-at-480p-and-finish-them-in-1080p-or-4k-with-the-dreamina-api } 5 menit baca • 12 November 2026 (20 November 2026) ## Daftar isi {: .no_toc .text-delta #table-of-contents } ### Pendahuluan [Dreamina API](/docs/api-dreamina-v1) dari useapi.net membuat draft [Seedance 2.5](https://docs.byteplus.com/en/docs/modelark/seedance-2-5) 480p dengan harga sekitar sepertujuh dari video yang sama di 1080p. Setelah Anda puas, satu panggilan lagi ke [POST /videos/full-quality](/docs/api-dreamina-v1/post-dreamina-videos-full-quality) mengubah draft yang sama itu menjadi video 1080p, atau 4K di akun Kanada. Video full quality mempertahankan shot, gerakan dan timing dari draft, jadi Anda membayar harga penuh hanya untuk take yang sudah Anda setujui. Video 4K 5 detik berharga sekitar $4,15 di sini dengan paket Advanced Kanada, dibanding $4,57 di API ByteDance sendiri (per 18 November 2026). Semuanya berjalan di langganan [Dreamina](https://dreamina.capcut.com/) yang sudah Anda punya, sama seperti cara kerja tombol "Generate in full quality" di situs Dreamina. Draft 480p dan video 1080p yang dibuat darinya, diputar berdampingan: <video src="https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-draft-vs-full-quality-dancer-side-by-side.mp4" poster="https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-draft-vs-full-quality-dancer-side-by-side-poster.jpg" style="width: 100%; max-width: 720px; aspect-ratio: 1450/1280;" controls type="video/mp4" preload="metadata"></video> Di bawah ini ada request yang membuat keduanya dan kredit yang dipakai di setiap langkah. ### Bagaimana cara kerja mode draft Seedance 2.5? 1. Kirim prompt Anda ke [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos) dengan `model: "seedance-2.5-draft"`. Anda mendapat video 480p berdurasi 4 sampai 30 detik, dari teks, frame awal dan akhir, atau hingga 50 referensi (30 gambar, 10 video, 10 klip audio), input yang sama dengan `seedance-2.5`. 2. Tonton hasilnya. Kalau belum pas, ubah prompt dan buat draft lain. 3. Dalam 14 hari, kirim `jobid` draft ke [POST /videos/full-quality](/docs/api-dreamina-v1/post-dreamina-videos-full-quality) dengan `resolution` `1080p` atau `4k`. Dreamina membuat video full quality dari draft itu, dengan prompt, referensi, durasi dan rasio aspeknya. Akun AS dan Kanada sama-sama bisa membuat draft dan video 1080p. 4K butuh akun Kanada. Kedua langkah butuh paket Dreamina berbayar. Dreamina tidak bisa [meng-upscale](/docs/api-dreamina-v1/post-dreamina-videos-upscale) draft: satu-satunya langkah berikutnya adalah full quality. Video full quality 1080p bisa di-upscale seperti video lainnya. ### Harga Full quality berharga sama dengan membuat video dengan `seedance-2.5` di resolusi itu. Draft adalah satu run tambahan di atas harga tersebut, baik Anda lalu membuat 1080p maupun 4K, jadi draft menguntungkan kalau biasanya Anda mencoba satu prompt lebih dari sekali. Harga draft dan semua model lain ada di [kalkulator biaya](/docs/start-here/setup-dreamina#cost-calculator). ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. ### Langkah 1. Buat draft Langkah-langkah di bawah memakai `curl` biasa. Alur yang sama dalam satu skrip, untuk Node.js dan Python, ada di [useapi/dreamina-api](https://github.com/useapi/dreamina-api/tree/main/seedance-draft) di GitHub. Anda butuh API token useapi.net ([Setup useapi.net](/docs/start-here/setup-useapi)) dan akun Dreamina dengan paket berbayar yang terhubung lewat [Setup Dreamina](/docs/start-here/setup-dreamina). ```bash curl --location 'https://api.useapi.net/v1/dreamina/videos' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="seedance-2.5-draft"' \ --form 'duration="4"' \ --form 'ratio="9:16"' \ --form 'prompt="Pretty lady dancing"' ``` Jika `account` tidak diisi, API memilih salah satu akun Dreamina Anda yang masih punya kapasitas kosong. Respons berisi `jobid`: ```json { "jobid": "j1112160042000000000v-u12345-CA:user@example.com-bot:dreamina", "type": "video", "status": "created", "model": "seedance-2.5-draft" } ``` ### Langkah 2. Tunggu dan tonton hasilnya Poll [GET /videos/`jobid`](/docs/api-dreamina-v1/get-dreamina-videos-jobid) kira-kira setiap 15 detik, atau kirim `replyUrl` di langkah 1 agar hasilnya dikirim ke Anda. ```bash curl --location 'https://api.useapi.net/v1/dreamina/videos/j1112160042000000000v-u12345-CA:user@example.com-bot:dreamina' \ --header 'Authorization: Bearer user:12345-…' ``` ```json { "jobid": "j1112160042000000000v-u12345-CA:user@example.com-bot:dreamina", "status": "completed", "model": "seedance-2.5-draft", "response": { "videoUrl": "https://…/video.mp4", "width": 480, "height": 854, "durationMs": 4042 } } ``` Draft kami siap dalam 85 detik, video 480×854 seharga 68 kredit: <video src="https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-draft-dancer-480p.mp4" poster="https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-draft-dancer-480p-poster.jpg" style="width: 100%; max-width: 400px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> ### Langkah 3. Ubah draft menjadi video full quality Draft ini sudah sesuai keinginan kami, jadi `jobid`-nya dikirim ke [POST /videos/full-quality](/docs/api-dreamina-v1/post-dreamina-videos-full-quality): ```bash curl --location 'https://api.useapi.net/v1/dreamina/videos/full-quality' \ --header 'Authorization: Bearer user:12345-…' \ --form 'jobid="j1112160042000000000v-u12345-CA:user@example.com-bot:dreamina"' \ --form 'resolution="1080p"' ``` Video dibuat di akun milik draft itu sendiri. Responsnya adalah job video baru yang di-poll dengan cara yang sama. Job ini tetap bertanda `model: "seedance-2.5-draft"`, dan `request.resolution` serta `request.draftJobid` membedakannya dari draft: ```json { "jobid": "j1112160306000000000v-u12345-CA:user@example.com-bot:dreamina", "type": "video", "status": "created", "model": "seedance-2.5-draft", "request": { "inputMode": "full_quality", "resolution": "1080p", "draftJobid": "j1112160042000000000v-u12345-CA:user@example.com-bot:dreamina" } } ``` Video siap dalam sekitar 2 menit, 1080×1920 seharga 468 kredit: <video src="https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-full-quality-dancer-1080p.mp4" poster="https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-full-quality-dancer-1080p-poster.jpg" style="width: 100%; max-width: 400px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> Untuk 4K, kirim `resolution: "4k"` dari draft yang dibuat di akun Kanada. Dreamina menyediakannya di sana, meski tes kami sendiri berjalan di 1080p. API ByteDance sendiri menambahkan Seedance 2.5 di 4K pada 16 November 2026, seharga $4,57 untuk 5 detik. Di sini video 4K yang sama berharga sekitar $4,15 dengan paket Advanced Kanada. Video yang sudah jadi adalah job video biasa, jadi Anda tetap bisa [meng-upscale](/docs/api-dreamina-v1/post-dreamina-videos-upscale) video 1080p atau [menaikkan frame rate-nya](/docs/api-dreamina-v1/post-dreamina-videos-interpolate). Job yang bukan draft yang sudah selesai, draft yang berumur lebih dari 14 hari, atau `4k` di akun AS mendapat `400`. Akun Dreamina tanpa paket berbayar mendapat `403`, dan akun yang kehabisan kredit mendapat `412`. Job yang gagal belakangan menunjukkan `status: "failed"` dan `error` saat Anda melakukan poll. ### Draft dan full quality, berdampingan Kedua video adalah take yang sama: gerakan, putaran kepala, kedipan mata dan timing-nya cocok dari frame pertama sampai terakhir. Berikut momen yang sama di detik ke-3,5, dipotong dari keduanya. Draft yang diperbesar ke 1080p ada di kiri dan video full quality di kanan: ![Frame yang sama dari video penari, dari draft Seedance 2.5 (kiri, 480p diperbesar) dan video full quality 1080p (kanan): kedipan yang sama, dengan bulu mata, rambut dan kulit yang lebih tajam](https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-draft-vs-full-quality-dancer-detail.jpg) Bulu mata, helai-helai rambut dan kulit tampil tajam, tanpa ada yang bergeser di wajah. ### Gunakan dari Claude, ChatGPT, atau Cursor [Server MCP Dreamina](/docs/api-dreamina-v1/mcp) yang di-hosting useapi.net membawa alur draft lalu full quality ini ke Claude Code, Cursor, VS Code, dan klien MCP lain, tanpa perlu memasang apa pun, dan aplikasi Claude serta ChatGPT terhubung ke sana lewat login. Server ini punya 15 tool dan berjalan di akun Dreamina Anda sendiri dengan API token useapi.net Anda. Di Claude Code: ```bash claude mcp add --transport http useapi-dreamina https://api.useapi.net/v1/dreamina/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` Lalu minta saja, misalnya: "Buat draft Seedance 2.5 dari prompt ini, dan kalau hasilnya pas, buat versi full quality 1080p". Asisten membuat draft dengan `dreamina_create_video` dan `seedance-2.5-draft`, menampilkan link-nya, lalu setelah Anda setujui mengubah take itu menjadi 1080p, atau 4K di akun Kanada, dengan `dreamina_full_quality_video`. Server ini terdaftar di MCP Registry resmi sebagai `net.useapi/dreamina`, dan repo [`dreamina-api`](https://github.com/useapi/dreamina-api#use-with-claude-code) juga bisa dipasang sebagai plugin Claude Code atau [ekstensi Gemini CLI](https://github.com/useapi/dreamina-api#use-with-gemini-cli). ### Pertanyaan #### Apakah ada API untuk mode draft Seedance 2.5? Ada. Dreamina API dari useapi.net membuat video `seedance-2.5-draft` 480p dan mengubahnya menjadi 1080p, atau 4K di akun Dreamina Kanada, di langganan Dreamina yang sudah Anda bayar. API ByteDance sendiri juga punya mode draft. Di 4K, video jadi berharga sekitar $4,15 di sini dengan paket Advanced Kanada, dibanding $4,57 di API ByteDance, tanpa paket prabayar (per 18 November 2026). #### Berapa biaya draft Seedance 2.5? Lewat useapi.net, draft Seedance 2.5 berdurasi 5 detik memakai 65 kredit di akun Dreamina AS dan 85 kredit di akun Kanada, sekitar $0,59 atau $0,55 di paket Advanced (per November 2026). Video full quality kemudian berharga sama dengan video `seedance-2.5` di resolusi itu, jadi draft adalah run tambahan yang menghemat biaya take full quality yang akhirnya Anda buang. Lihat [Harga](#pricing). #### Apakah video full quality terlihat sama dengan draft-nya? Ya. Dengan Dreamina API dari useapi.net, video full quality dibangun dari draft Anda, jadi take, gerakan dan timing-nya tetap sama, hanya lebih tajam, seperti terlihat pada perbandingan di atas. Mengirim prompt yang sama ke `seedance-2.5` sekali lagi akan menghasilkan video yang berbeda. #### Bisakah membuat video Seedance 2.5 4K dari draft? Bisa, lewat useapi.net di akun Dreamina Kanada: kirim `jobid` draft ke [POST /videos/full-quality](/docs/api-dreamina-v1/post-dreamina-videos-full-quality) dengan `resolution: "4k"`, seharga video `seedance-2.5` 4K. Akun AS membuat 1080p. Video 4K itu berharga sekitar $4,15 dengan paket Advanced Kanada, dibanding $4,57 di API ByteDance sendiri (per 18 November 2026). ### Kesimpulan Draft Seedance 2.5 memungkinkan Anda mencoba ide di 480p dengan sebagian kecil harganya dan menyimpan persis take yang Anda suka, di 1080p atau 4K. Buat draft dengan [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos) dan `seedance-2.5-draft`, lalu selesaikan dengan [POST /videos/full-quality](/docs/api-dreamina-v1/post-dreamina-videos-full-quality). Seluruh alurnya ada dalam satu skrip, untuk Node.js dan Python, di GitHub: [useapi/dreamina-api/seedance-draft](https://github.com/useapi/dreamina-api/tree/main/seedance-draft). Hubungkan akun Dreamina Anda lewat [Setup Dreamina](/docs/start-here/setup-dreamina), dan lihat [ikhtisar Dreamina API](/docs/api-dreamina-v1) untuk semua model. === URL: https://useapi.net/docs/articles/dreamina-seedance-2-5-draft-ja === Document URL: https://useapi.net/docs/articles/dreamina-seedance-2-5-draft-ja --- layout: default title: "Dreamina API で Seedance 2.5 の動画を 480p でドラフトし、1080p や 4K で仕上げる方法" seo_title: "Seedance 2.5 ドラフトモード API:480p のドラフトから 1080p・4K へ" description: "useapi.net の Dreamina API で Seedance 2.5 のドラフトモードを使う方法。480p のドラフトで確認してから、同じ動画を 1080p や 4K に。コード、実際の動画、クレジット数付き。" keywords: [Seedance 2.5 ドラフトモード, Seedance 2.5 ドラフト API, Seedance 2.5 ドラフト 1080p, Seedance 2.5 4K, Seedance 2.5 API, Seedance 2.5 使い方, Dreamina API, Dreamina フル画質, Dreamina Seedance 2.5, ByteDance Seedance, 動画生成 API, Seedance 2.5 draft mode, Seedance 2.5 draft API, Seedance 2.5 draft to 1080p, Dreamina full quality] image: https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-draft-vs-full-quality-dancer-detail.jpg parent: Articles nav_exclude: true lang: ja translation_key: seedance-2-5-draft date: 2026-11-12 last_modified: 2026-11-20 nav_order: 821 repo: https://github.com/useapi/dreamina-api --- ## Dreamina API で Seedance 2.5 の動画を 480p でドラフトし、1080p や 4K で仕上げる方法 {: .no_toc #how-to-draft-seedance-25-videos-at-480p-and-finish-them-in-1080p-or-4k-with-the-dreamina-api } 5分で読めます • 2026年11月12日(2026年11月20日更新) ## 目次 {: .no_toc .text-delta #table-of-contents } ### はじめに useapi.net の [Dreamina API](/docs/api-dreamina-v1) なら、[Seedance 2.5](https://docs.byteplus.com/en/docs/modelark/seedance-2-5) の 480p ドラフトを、同じ動画を 1080p で作る場合の約7分の1の料金で作れます。気に入ったら [POST /videos/full-quality](/docs/api-dreamina-v1/post-dreamina-videos-full-quality) をもう1回呼ぶだけで、そのドラフトが 1080p の動画になります。カナダのアカウントなら 4K にもできます。フル画質の動画はドラフトのショット、動き、タイミングをそのまま引き継ぐので、フル料金を払うのはすでに確認済みのテイクだけです。5秒の 4K 動画は、カナダの Advanced プランならここで約 $4.15、ByteDance 自身の API では $4.57 です(2026年11月18日時点)。お持ちの [Dreamina](https://dreamina.capcut.com/) のサブスクリプションで動き、Dreamina のサイトにある「Generate in full quality」ボタンと同じ仕組みです。 480p のドラフトと、そこから作った 1080p の動画を並べて再生しています。 <video src="https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-draft-vs-full-quality-dancer-side-by-side.mp4" poster="https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-draft-vs-full-quality-dancer-side-by-side-poster.jpg" style="width: 100%; max-width: 720px; aspect-ratio: 1450/1280;" controls type="video/mp4" preload="metadata"></video> 以下は、これらを作ったリクエストと、各ステップで使ったクレジットです。 ### Seedance 2.5 のドラフトモードの仕組み 1. プロンプトを `model: "seedance-2.5-draft"` で [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos) に送ります。テキスト、開始フレームと終了フレーム、または最大50個の参照素材(画像30枚、動画10本、音声10本)から、4〜30秒の 480p 動画ができます。入力は `seedance-2.5` と同じです。 2. 動画を確認します。イメージと違えば、プロンプトを変えてもう一度ドラフトを作ります。 3. 14日以内に、ドラフトの `jobid` を `resolution` `1080p` または `4k` で [POST /videos/full-quality](/docs/api-dreamina-v1/post-dreamina-videos-full-quality) に送ります。Dreamina はそのドラフトから、プロンプト、参照素材、長さ、アスペクト比を引き継いでフル画質の動画を作ります。 米国とカナダのアカウントは、どちらもドラフトと 1080p の動画を作れます。4K にはカナダのアカウントが必要です。どちらのステップにも Dreamina の有料プランが必要です。 Dreamina はドラフトを[アップスケール](/docs/api-dreamina-v1/post-dreamina-videos-upscale)できません。ドラフトの次のステップはフル画質だけです。1080p のフル画質動画は、ほかの動画と同じようにアップスケールできます。 ### 料金 フル画質の料金は、その解像度で `seedance-2.5` の動画を作る場合と同じです。ドラフトはその上に追加される1回分の生成で、そのあと 1080p にしても 4K にしても変わりません。そのため、本来ならプロンプトを2回以上試すことになる場合に元が取れます。ドラフトとほかの全モデルの料金は[料金計算ツール](/docs/start-here/setup-dreamina#cost-calculator)にあります。 ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. ### ステップ1:ドラフトを作る 以下の手順はシンプルな `curl` です。同じ流れを1つのスクリプトにしたもの(Node.js と Python)は、GitHub の [useapi/dreamina-api](https://github.com/useapi/dreamina-api/tree/main/seedance-draft) にあります。 useapi.net の API トークン([Setup useapi.net](/docs/start-here/setup-useapi))と、[Setup Dreamina](/docs/start-here/setup-dreamina) で接続した有料プランの Dreamina アカウントが必要です。 ```bash curl --location 'https://api.useapi.net/v1/dreamina/videos' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="seedance-2.5-draft"' \ --form 'duration="4"' \ --form 'ratio="9:16"' \ --form 'prompt="Pretty lady dancing"' ``` `account` を省略すると、API が空きのある Dreamina アカウントを1つ選びます。レスポンスには `jobid` が入っています。 ```json { "jobid": "j1112160042000000000v-u12345-CA:user@example.com-bot:dreamina", "type": "video", "status": "created", "model": "seedance-2.5-draft" } ``` ### ステップ2:完成を待って確認する [GET /videos/`jobid`](/docs/api-dreamina-v1/get-dreamina-videos-jobid) を15秒ほどの間隔でポーリングするか、ステップ1で `replyUrl` を渡して結果を送ってもらいます。 ```bash curl --location 'https://api.useapi.net/v1/dreamina/videos/j1112160042000000000v-u12345-CA:user@example.com-bot:dreamina' \ --header 'Authorization: Bearer user:12345-…' ``` ```json { "jobid": "j1112160042000000000v-u12345-CA:user@example.com-bot:dreamina", "status": "completed", "model": "seedance-2.5-draft", "response": { "videoUrl": "https://…/video.mp4", "width": 480, "height": 854, "durationMs": 4042 } } ``` 今回のドラフトは85秒で完成しました。480×854 の動画で、使ったのは68クレジットです。 <video src="https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-draft-dancer-480p.mp4" poster="https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-draft-dancer-480p-poster.jpg" style="width: 100%; max-width: 400px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> ### ステップ3:ドラフトをフル画質の動画にする ドラフトは狙いどおりだったので、その `jobid` を [POST /videos/full-quality](/docs/api-dreamina-v1/post-dreamina-videos-full-quality) に送ります。 ```bash curl --location 'https://api.useapi.net/v1/dreamina/videos/full-quality' \ --header 'Authorization: Bearer user:12345-…' \ --form 'jobid="j1112160042000000000v-u12345-CA:user@example.com-bot:dreamina"' \ --form 'resolution="1080p"' ``` 動画はドラフトと同じアカウントで作られます。レスポンスは新しい動画ジョブで、同じ方法でポーリングします。`model: "seedance-2.5-draft"` のままで、`request.resolution` と `request.draftJobid` でドラフトと区別できます。 ```json { "jobid": "j1112160306000000000v-u12345-CA:user@example.com-bot:dreamina", "type": "video", "status": "created", "model": "seedance-2.5-draft", "request": { "inputMode": "full_quality", "resolution": "1080p", "draftJobid": "j1112160042000000000v-u12345-CA:user@example.com-bot:dreamina" } } ``` 約2分で完成しました。1080×1920 の動画で、使ったのは468クレジットです。 <video src="https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-full-quality-dancer-1080p.mp4" poster="https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-full-quality-dancer-1080p-poster.jpg" style="width: 100%; max-width: 400px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> 4K にするには、カナダのアカウントで作ったドラフトに `resolution: "4k"` を送ります。Dreamina はカナダで 4K を提供していますが、今回のテストは 1080p で行いました。ByteDance 自身の API も2026年11月16日に Seedance 2.5 の 4K を追加し、5秒で $4.57 です。ここでは同じ 4K 動画がカナダの Advanced プランで約 $4.15 です。完成した動画は通常の動画ジョブなので、1080p の動画をさらに[アップスケール](/docs/api-dreamina-v1/post-dreamina-videos-upscale)することも、[フレームレートを上げる](/docs/api-dreamina-v1/post-dreamina-videos-interpolate)こともできます。 完成したドラフトではないジョブ、14日を過ぎたドラフト、米国アカウントでの `4k` には `400` が返ります。有料プランのない Dreamina アカウントには `403`、クレジットが残っていないアカウントには `412` が返ります。あとから失敗したジョブは、ポーリングすると `status: "failed"` と `error` が表示されます。 ### ドラフトとフル画質の比較 2本の動画は同じテイクです。動き、頭の向き、ウインク、タイミングが最初のフレームから最後まで一致しています。下は、両方の動画から3.5秒時点の同じ瞬間を切り出したものです。左が 1080p に拡大したドラフト、右がフル画質の動画です。 ![Seedance 2.5 のドラフト(左、480p を拡大)とフル画質の 1080p 動画(右)から切り出したダンサー動画の同じフレーム。同じウインクで、まつげ、髪、肌がよりシャープ](https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-draft-vs-full-quality-dancer-detail.jpg) まつげ、髪の1本1本、肌がくっきりし、顔はどこも動いていません。 ### Claude、ChatGPT、Cursor から使う useapi.net がホストする [Dreamina MCP サーバー](/docs/api-dreamina-v1/mcp)を使えば、このドラフトから仕上げまでの流れを Claude Code、Cursor、VS Code などの MCP クライアントから実行できます。インストールは不要で、Claude アプリと ChatGPT からはサインインして接続できます。ツールは15個で、ご自身の Dreamina アカウントと useapi.net の API トークンで動きます。Claude Code では次のとおりです: ```bash claude mcp add --transport http useapi-dreamina https://api.useapi.net/v1/dreamina/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` あとは、たとえば「このプロンプトで Seedance 2.5 のドラフトを作って、よければ 1080p のフル画質で仕上げて」と頼むだけです。アシスタントは `dreamina_create_video` と `seedance-2.5-draft` でドラフトを作ってリンクを見せ、承認したテイクを `dreamina_full_quality_video` で 1080p(カナダのアカウントなら 4K)にします。このサーバーは公式の MCP Registry に `net.useapi/dreamina` として登録されています。[`dreamina-api`](https://github.com/useapi/dreamina-api#use-with-claude-code) リポジトリは Claude Code のプラグインや [Gemini CLI の拡張機能](https://github.com/useapi/dreamina-api#use-with-gemini-cli)としてもインストールできます。 ### よくある質問 #### Seedance 2.5 のドラフトモードの API はありますか? あります。useapi.net の Dreamina API は 480p の `seedance-2.5-draft` 動画を作り、それを 1080p に、カナダの Dreamina アカウントなら 4K にできます。すでに支払っている Dreamina のサブスクリプションで動きます。ByteDance 自身の API にもドラフトモードはあります。4K の完成動画は、カナダの Advanced プランならここで約 $4.15、ByteDance の API では $4.57 で、前払いパックも要りません(2026年11月18日時点)。 #### Seedance 2.5 のドラフトの料金はいくらですか? useapi.net なら、5秒の Seedance 2.5 ドラフトは米国の Dreamina アカウントで65クレジット、カナダのアカウントで85クレジットで、Advanced プランでそれぞれ約 $0.59、$0.55 です(2026年11月時点)。そのあとのフル画質の動画は、同じ解像度の `seedance-2.5` 動画と同じ料金です。ドラフトは1回分の追加ですが、捨てることになるフル画質のテイクに払わずに済みます。[料金](#pricing)をご覧ください。 #### フル画質の動画はドラフトと同じに見えますか? はい。useapi.net の Dreamina API では、フル画質の動画はドラフトから作られるため、同じテイク、動き、タイミングのまま、よりシャープになります。上の比較のとおりです。同じプロンプトを `seedance-2.5` にもう一度送ると、別の動画になります。 #### ドラフトから 4K の Seedance 2.5 動画を作れますか? はい。useapi.net でカナダの Dreamina アカウントを使えば作れます。ドラフトの `jobid` を `resolution: "4k"` で [POST /videos/full-quality](/docs/api-dreamina-v1/post-dreamina-videos-full-quality) に送ると、4K の `seedance-2.5` 動画と同じ料金でできます。米国のアカウントでは 1080p です。その 4K 動画はカナダの Advanced プランで約 $4.15、ByteDance 自身の API では $4.57 です(2026年11月18日時点)。 ### まとめ Seedance 2.5 のドラフトなら、アイデアを 480p でわずかな料金で試し、気に入ったテイクをそのまま 1080p や 4K で残せます。[POST /videos](/docs/api-dreamina-v1/post-dreamina-videos) と `seedance-2.5-draft` でドラフトを作り、[POST /videos/full-quality](/docs/api-dreamina-v1/post-dreamina-videos-full-quality) で仕上げます。一連の流れは Node.js と Python の1つのスクリプトとして GitHub にあります:[useapi/dreamina-api/seedance-draft](https://github.com/useapi/dreamina-api/tree/main/seedance-draft)。Dreamina アカウントは [Setup Dreamina](/docs/start-here/setup-dreamina) で接続できます。全モデルは [Dreamina API の概要](/docs/api-dreamina-v1)をご覧ください。 === URL: https://useapi.net/docs/articles/dreamina-seedance-2-5-draft-pt === Document URL: https://useapi.net/docs/articles/dreamina-seedance-2-5-draft-pt --- layout: default title: Como fazer rascunhos de vídeos Seedance 2.5 em 480p e finalizá-los em 1080p ou 4K com a API do Dreamina seo_title: "API do modo rascunho do Seedance 2.5: de 480p para 1080p ou 4K" description: "Modo rascunho (draft) do Seedance 2.5 com a API do Dreamina da useapi.net: faça um rascunho em 480p, confira e transforme o mesmo vídeo em 1080p ou 4K. Código completo, vídeos reais, créditos." keywords: [Seedance 2.5 draft mode, modo rascunho Seedance 2.5, Seedance 2.5 draft API, API Seedance 2.5 draft, rascunho Seedance 2.5 para 1080p, Seedance 2.5 draft to 1080p, Seedance 2.5 4K, Seedance 2.5 API, API do Seedance 2.5, Dreamina API, API do Dreamina, Dreamina full quality, Dreamina qualidade total, Dreamina Seedance 2.5, ByteDance Seedance, tutorial Seedance 2.5] image: https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-draft-vs-full-quality-dancer-detail.jpg parent: Articles nav_exclude: true lang: pt-BR date: 2026-11-12 last_modified: 2026-11-20 nav_order: 821 repo: https://github.com/useapi/dreamina-api translation_key: seedance-2-5-draft --- ## Como fazer rascunhos de vídeos Seedance 2.5 em 480p e finalizá-los em 1080p ou 4K com a API do Dreamina {: .no_toc #how-to-draft-seedance-25-videos-at-480p-and-finish-them-in-1080p-or-4k-with-the-dreamina-api } 5 min de leitura • 12 de novembro de 2026 (20 de novembro de 2026) ## Sumário {: .no_toc .text-delta #table-of-contents } ### Introdução A [API do Dreamina](/docs/api-dreamina-v1) da useapi.net faz um rascunho do [Seedance 2.5](https://docs.byteplus.com/en/docs/modelark/seedance-2-5) em 480p por cerca de um sétimo do preço do mesmo vídeo em 1080p. Quando o rascunho ficar do seu jeito, mais uma chamada a [POST /videos/full-quality](/docs/api-dreamina-v1/post-dreamina-videos-full-quality) transforma esse mesmo rascunho em um vídeo 1080p, ou 4K numa conta canadense. O vídeo em qualidade total mantém a cena, o movimento e o ritmo do rascunho, então você só paga o preço cheio pela tomada que já aprovou. Um vídeo 4K de 5 segundos custa cerca de $4,15 aqui num plano Advanced canadense, contra $4,57 na API da própria ByteDance (em 18 de novembro de 2026). A API roda na assinatura do [Dreamina](https://dreamina.capcut.com/) que você já tem, do mesmo jeito que o botão "Generate in full quality" funciona no site do Dreamina. O rascunho em 480p e o vídeo 1080p feito a partir dele, lado a lado: <video src="https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-draft-vs-full-quality-dancer-side-by-side.mp4" poster="https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-draft-vs-full-quality-dancer-side-by-side-poster.jpg" style="width: 100%; max-width: 720px; aspect-ratio: 1450/1280;" controls type="video/mp4" preload="metadata"></video> Abaixo estão as requisições que geram os dois vídeos e os créditos que cada passo usou. ### Como funciona o modo rascunho do Seedance 2.5? 1. Envie o seu prompt para [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos) com `model: "seedance-2.5-draft"`. Você recebe um vídeo 480p de 4 a 30 segundos, a partir de texto, de um quadro inicial e um final, ou de até 50 referências (30 imagens, 10 vídeos, 10 clipes de áudio), as mesmas entradas do `seedance-2.5`. 2. Assista ao vídeo. Se não estiver bom, mude o prompt e faça outro rascunho. 3. Em até 14 dias, envie o `jobid` do rascunho para [POST /videos/full-quality](/docs/api-dreamina-v1/post-dreamina-videos-full-quality) com `resolution` `1080p` ou `4k`. O Dreamina gera o vídeo em qualidade total a partir desse rascunho, com o prompt, as referências, a duração e a proporção dele. Contas dos EUA e do Canadá fazem rascunhos e vídeos 1080p. O 4K exige uma conta canadense. Os dois passos exigem um plano pago do Dreamina. O Dreamina não faz [upscale](/docs/api-dreamina-v1/post-dreamina-videos-upscale) de um rascunho: o único próximo passo dele é a qualidade total. Um vídeo 1080p em qualidade total aceita upscale como qualquer outro. ### Preços A qualidade total custa o mesmo que gerar o vídeo com `seedance-2.5` nessa resolução. O rascunho é uma geração a mais por cima disso, seja o passo seguinte em 1080p ou em 4K, então ele compensa quando você testaria um prompt mais de uma vez de qualquer forma. Os preços do rascunho e de todos os outros modelos estão na [calculadora de custos](/docs/start-here/setup-dreamina#cost-calculator). ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. ### Passo 1: faça o rascunho Os passos abaixo usam `curl` puro. O mesmo fluxo em um único script, em Node.js e Python, está em [useapi/dreamina-api](https://github.com/useapi/dreamina-api/tree/main/seedance-draft) no GitHub. Você precisa de um token da API da useapi.net ([Setup useapi.net](/docs/start-here/setup-useapi)) e de uma conta do Dreamina com plano pago, conectada pelo [Setup Dreamina](/docs/start-here/setup-dreamina). ```bash curl --location 'https://api.useapi.net/v1/dreamina/videos' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="seedance-2.5-draft"' \ --form 'duration="4"' \ --form 'ratio="9:16"' \ --form 'prompt="Pretty lady dancing"' ``` Se você omitir `account`, a API escolhe uma das suas contas do Dreamina com capacidade livre. A resposta traz o `jobid`: ```json { "jobid": "j1112160042000000000v-u12345-CA:user@example.com-bot:dreamina", "type": "video", "status": "created", "model": "seedance-2.5-draft" } ``` ### Passo 2: espere e assista Consulte [GET /videos/`jobid`](/docs/api-dreamina-v1/get-dreamina-videos-jobid) a cada 15 segundos, mais ou menos, ou passe `replyUrl` no passo 1 e receba o resultado por POST no seu endereço. ```bash curl --location 'https://api.useapi.net/v1/dreamina/videos/j1112160042000000000v-u12345-CA:user@example.com-bot:dreamina' \ --header 'Authorization: Bearer user:12345-…' ``` ```json { "jobid": "j1112160042000000000v-u12345-CA:user@example.com-bot:dreamina", "status": "completed", "model": "seedance-2.5-draft", "response": { "videoUrl": "https://…/video.mp4", "width": 480, "height": 854, "durationMs": 4042 } } ``` O nosso rascunho ficou pronto em 85 segundos, um vídeo 480×854 por 68 créditos: <video src="https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-draft-dancer-480p.mp4" poster="https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-draft-dancer-480p-poster.jpg" style="width: 100%; max-width: 400px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> ### Passo 3: transforme o rascunho em um vídeo em qualidade total O rascunho ficou como queríamos, então o `jobid` dele vai para [POST /videos/full-quality](/docs/api-dreamina-v1/post-dreamina-videos-full-quality): ```bash curl --location 'https://api.useapi.net/v1/dreamina/videos/full-quality' \ --header 'Authorization: Bearer user:12345-…' \ --form 'jobid="j1112160042000000000v-u12345-CA:user@example.com-bot:dreamina"' \ --form 'resolution="1080p"' ``` O vídeo é gerado na própria conta do rascunho. A resposta é um novo job de vídeo, consultado do mesmo jeito. Ele mantém `model: "seedance-2.5-draft"`, e `request.resolution` e `request.draftJobid` o diferenciam do rascunho: ```json { "jobid": "j1112160306000000000v-u12345-CA:user@example.com-bot:dreamina", "type": "video", "status": "created", "model": "seedance-2.5-draft", "request": { "inputMode": "full_quality", "resolution": "1080p", "draftJobid": "j1112160042000000000v-u12345-CA:user@example.com-bot:dreamina" } } ``` Ficou pronto em cerca de 2 minutos, um vídeo 1080×1920 por 468 créditos: <video src="https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-full-quality-dancer-1080p.mp4" poster="https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-full-quality-dancer-1080p-poster.jpg" style="width: 100%; max-width: 400px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> Para 4K, envie `resolution: "4k"` a partir de um rascunho feito numa conta canadense. O Dreamina oferece essa opção lá, embora os nossos testes tenham rodado em 1080p. A API da própria ByteDance passou a oferecer o Seedance 2.5 em 4K em 16 de novembro de 2026, a $4,57 por 5 segundos. Aqui o mesmo vídeo 4K custa cerca de $4,15 num plano Advanced canadense. O vídeo final é um job de vídeo comum, então você ainda pode fazer [upscale](/docs/api-dreamina-v1/post-dreamina-videos-upscale) de um vídeo 1080p ou [aumentar a taxa de quadros](/docs/api-dreamina-v1/post-dreamina-videos-interpolate) dele. Um job que não seja um rascunho concluído, um rascunho com mais de 14 dias ou `4k` numa conta dos EUA recebe `400`. Uma conta do Dreamina sem plano pago recebe `403`, e uma conta sem créditos, `412`. Um job que falhe depois aparece com `status: "failed"` e um `error` quando você o consulta. ### Rascunho e qualidade total, lado a lado Os dois vídeos são a mesma tomada: os movimentos, o giro da cabeça, a piscadela e o ritmo coincidem do primeiro ao último quadro. Aqui está o mesmo momento, aos 3,5 segundos, recortado dos dois. O rascunho, ampliado para 1080p, está à esquerda, e o vídeo em qualidade total, à direita: ![O mesmo quadro do vídeo da dançarina no rascunho do Seedance 2.5 (à esquerda, 480p ampliado) e no vídeo 1080p em qualidade total (à direita): a mesma piscadela, com cílios, cabelo e pele mais nítidos](https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-draft-vs-full-quality-dancer-detail.jpg) Os cílios, os fios de cabelo soltos e a pele saem nítidos, sem que nada no rosto mude de lugar. ### Use pelo Claude, ChatGPT ou Cursor O [servidor MCP do Dreamina](/docs/api-dreamina-v1/mcp) hospedado pela useapi.net leva esse fluxo de rascunho e qualidade total ao Claude Code, ao Cursor, ao VS Code e a outros clientes MCP, sem nada para instalar, e o app do Claude e o ChatGPT se conectam a ele com um login. Ele tem 15 ferramentas e funciona nas suas próprias contas do Dreamina com o seu token da API da useapi.net. No Claude Code: ```bash claude mcp add --transport http useapi-dreamina https://api.useapi.net/v1/dreamina/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` Depois é só pedir, por exemplo: "Faça um rascunho do Seedance 2.5 com este prompt e, se ficar bom, gere em qualidade total em 1080p". O assistente faz o rascunho com `dreamina_create_video` e `seedance-2.5-draft`, mostra o link e, quando você aprova, transforma essa tomada em 1080p, ou 4K em uma conta canadense, com `dreamina_full_quality_video`. O servidor está no registro oficial de MCP como `net.useapi/dreamina`, e o repositório [`dreamina-api`](https://github.com/useapi/dreamina-api#use-with-claude-code) também se instala como plugin do Claude Code ou como [extensão do Gemini CLI](https://github.com/useapi/dreamina-api#use-with-gemini-cli). ### Perguntas #### Existe API do modo rascunho do Seedance 2.5? Sim. A API do Dreamina da useapi.net gera vídeos `seedance-2.5-draft` em 480p e os transforma em 1080p, ou em 4K numa conta canadense do Dreamina, na assinatura do Dreamina que você já paga. A API da própria ByteDance também tem modo rascunho. Em 4K, um vídeo final custa cerca de $4,15 aqui num plano Advanced canadense, contra $4,57 na API da ByteDance, sem pacote pré-pago (em 18 de novembro de 2026). #### Quanto custa um rascunho do Seedance 2.5? Pela useapi.net, um rascunho do Seedance 2.5 de 5 segundos custa 65 créditos numa conta do Dreamina dos EUA e 85 numa canadense, cerca de $0,59 ou $0,55 no plano Advanced (em novembro de 2026). Depois, o vídeo em qualidade total custa o mesmo que um vídeo `seedance-2.5` naquela resolução, então o rascunho é uma geração a mais que evita pagar por tomadas em qualidade total que você jogaria fora. Veja [Preços](#pricing). #### O vídeo em qualidade total fica igual ao rascunho? Sim. Com a API do Dreamina da useapi.net, o vídeo em qualidade total é gerado a partir do seu rascunho, então mantém a mesma tomada, o mesmo movimento e o mesmo ritmo, só que mais nítido, como mostra a comparação lado a lado acima. Enviar o mesmo prompt de novo para o `seedance-2.5` geraria um vídeo diferente. #### Dá para fazer um vídeo Seedance 2.5 em 4K a partir de um rascunho? Sim, pela useapi.net numa conta canadense do Dreamina: envie o `jobid` do rascunho para [POST /videos/full-quality](/docs/api-dreamina-v1/post-dreamina-videos-full-quality) com `resolution: "4k"`, pelo preço de um vídeo `seedance-2.5` em 4K. Contas dos EUA fazem 1080p. Esse vídeo 4K custa cerca de $4,15 num plano Advanced canadense, contra $4,57 na API da própria ByteDance (em 18 de novembro de 2026). ### Conclusão Um rascunho do Seedance 2.5 permite testar uma ideia em 480p por uma fração do preço e ficar exatamente com a tomada de que você gosta, em 1080p ou 4K. Faça um com [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos) e `seedance-2.5-draft`, depois finalize com [POST /videos/full-quality](/docs/api-dreamina-v1/post-dreamina-videos-full-quality). O fluxo inteiro é um único script, em Node.js e Python, no GitHub: [useapi/dreamina-api/seedance-draft](https://github.com/useapi/dreamina-api/tree/main/seedance-draft). Conecte a sua conta do Dreamina com o [Setup Dreamina](/docs/start-here/setup-dreamina) e veja a [visão geral da API do Dreamina](/docs/api-dreamina-v1) para conhecer todos os modelos. === URL: https://useapi.net/docs/articles/dreamina-seedance-2-5-draft-th === Document URL: https://useapi.net/docs/articles/dreamina-seedance-2-5-draft-th --- layout: default title: วิธีสร้างวิดีโอ Seedance 2.5 แบบดราฟต์ที่ 480p แล้วทำให้เสร็จเป็น 1080p หรือ 4K ด้วย Dreamina API seo_title: "Seedance 2.5 Draft Mode API: ดราฟต์ 480p เป็น 1080p หรือ 4K" description: "ใช้โหมดดราฟต์ของ Seedance 2.5 ผ่าน Dreamina API ของ useapi.net: สร้างดราฟต์ 480p ตรวจดู แล้วเปลี่ยนวิดีโอเดิมนั้นเป็น 1080p หรือ 4K พร้อมโค้ดครบ วิดีโอจริง และเครดิตที่ใช้" keywords: [Seedance 2.5 draft mode, โหมดดราฟต์ Seedance 2.5, Seedance 2.5 draft API, Seedance 2.5 draft to 1080p, Seedance 2.5 4K, วิดีโอ Seedance 2.5 4K, Seedance 2.5 API, วิธีใช้ Seedance 2.5, Dreamina API, Dreamina full quality, Dreamina Seedance 2.5, ByteDance Seedance, API สร้างวิดีโอ, สอนใช้งาน, curl] image: https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-draft-vs-full-quality-dancer-detail.jpg parent: Articles nav_exclude: true lang: th date: 2026-11-12 last_modified: 2026-11-20 nav_order: 821 repo: https://github.com/useapi/dreamina-api translation_key: seedance-2-5-draft --- ## วิธีสร้างวิดีโอ Seedance 2.5 แบบดราฟต์ที่ 480p แล้วทำให้เสร็จเป็น 1080p หรือ 4K ด้วย Dreamina API {: .no_toc #how-to-draft-seedance-25-videos-at-480p-and-finish-them-in-1080p-or-4k-with-the-dreamina-api } อ่าน 5 นาที • 12 พฤศจิกายน 2026 (20 พฤศจิกายน 2026) ## สารบัญ {: .no_toc .text-delta #table-of-contents } ### บทนำ [Dreamina API](/docs/api-dreamina-v1) ของ useapi.net สร้างดราฟต์ [Seedance 2.5](https://docs.byteplus.com/en/docs/modelark/seedance-2-5) ที่ 480p ได้ในราคาราวหนึ่งในเจ็ดของวิดีโอเดียวกันที่ 1080p เมื่อพอใจแล้ว เรียก [POST /videos/full-quality](/docs/api-dreamina-v1/post-dreamina-videos-full-quality) อีกครั้งเดียวก็เปลี่ยนดราฟต์เดิมนั้นเป็นวิดีโอ 1080p หรือ 4K บนบัญชีแคนาดา วิดีโอ full quality ยังคงช็อต การเคลื่อนไหว และจังหวะเวลาเดิมของดราฟต์ไว้ คุณจึงจ่ายราคาเต็มเฉพาะเทคที่อนุมัติแล้วเท่านั้น วิดีโอ 4K ยาว 5 วินาทีที่นี่ราคาราว $4.15 บนแพ็กเกจ Advanced ของแคนาดา เทียบกับ $4.57 บน API ของ ByteDance เอง (ข้อมูล ณ 18 พฤศจิกายน 2026) ทั้งหมดนี้ทำงานบนแพ็กเกจ [Dreamina](https://dreamina.capcut.com/) ที่คุณมีอยู่แล้ว แบบเดียวกับปุ่ม "Generate in full quality" บนเว็บไซต์ Dreamina ดราฟต์ 480p และวิดีโอ 1080p ที่สร้างจากดราฟต์นั้น เล่นเทียบกันแบบเคียงข้าง: <video src="https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-draft-vs-full-quality-dancer-side-by-side.mp4" poster="https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-draft-vs-full-quality-dancer-side-by-side-poster.jpg" style="width: 100%; max-width: 720px; aspect-ratio: 1450/1280;" controls type="video/mp4" preload="metadata"></video> ด้านล่างคือ request ที่ใช้สร้างวิดีโอทั้งสอง และเครดิตที่แต่ละขั้นตอนใช้ ### โหมดดราฟต์ของ Seedance 2.5 ทำงานอย่างไร? 1. ส่งพรอมต์ไปที่ [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos) ด้วย `model: "seedance-2.5-draft"` คุณจะได้วิดีโอ 480p ยาว 4 ถึง 30 วินาที จากข้อความ เฟรมเริ่มต้นและเฟรมสุดท้าย หรือข้อมูลอ้างอิงสูงสุด 50 รายการ (ภาพ 30 วิดีโอ 10 และคลิปเสียง 10) ซึ่งเป็นอินพุตชุดเดียวกับ `seedance-2.5` 2. ดูวิดีโอ ถ้ายังไม่ใช่ ให้แก้พรอมต์แล้วสร้างดราฟต์ใหม่ 3. ภายใน 14 วัน ส่ง `jobid` ของดราฟต์ไปที่ [POST /videos/full-quality](/docs/api-dreamina-v1/post-dreamina-videos-full-quality) พร้อม `resolution` เป็น `1080p` หรือ `4k` แล้ว Dreamina จะสร้างวิดีโอ full quality จากดราฟต์นั้น โดยใช้พรอมต์ ข้อมูลอ้างอิง ความยาว และอัตราส่วนภาพเดิม บัญชีสหรัฐฯ และแคนาดาสร้างได้ทั้งดราฟต์และวิดีโอ 1080p ส่วน 4K ต้องใช้บัญชีแคนาดา ทั้งสองขั้นตอนต้องใช้แพ็กเกจ Dreamina แบบเสียเงิน Dreamina [อัปสเกล](/docs/api-dreamina-v1/post-dreamina-videos-upscale)ดราฟต์ไม่ได้ ขั้นต่อไปของดราฟต์มีแค่ full quality เท่านั้น ส่วนวิดีโอ full quality 1080p อัปสเกลได้เหมือนวิดีโออื่นทั่วไป ### ราคา การสร้างแบบ full quality มีราคาเท่ากับการสร้างวิดีโอด้วย `seedance-2.5` ที่ความละเอียดนั้น ดราฟต์คือการรันเพิ่มอีกหนึ่งครั้งบวกเข้าไป ไม่ว่าจากนั้นคุณจะทำ 1080p หรือ 4K จึงคุ้มเมื่อปกติคุณต้องลองพรอมต์เดียวกันมากกว่าหนึ่งครั้ง ราคาของดราฟต์และโมเดลอื่นทั้งหมดอยู่ใน[เครื่องคำนวณค่าใช้จ่าย](/docs/start-here/setup-dreamina#cost-calculator) ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. ### ขั้นตอนที่ 1. สร้างดราฟต์ ขั้นตอนด้านล่างใช้ `curl` ธรรมดา ส่วนโฟลว์เดียวกันในรูปสคริปต์เดียว ทั้ง Node.js และ Python อยู่ที่ [useapi/dreamina-api](https://github.com/useapi/dreamina-api/tree/main/seedance-draft) บน GitHub คุณต้องมี API token ของ useapi.net ([Setup useapi.net](/docs/start-here/setup-useapi)) และบัญชี Dreamina ที่ใช้แพ็กเกจแบบเสียเงิน ซึ่งเชื่อมต่อผ่าน [Setup Dreamina](/docs/start-here/setup-dreamina) แล้ว ```bash curl --location 'https://api.useapi.net/v1/dreamina/videos' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="seedance-2.5-draft"' \ --form 'duration="4"' \ --form 'ratio="9:16"' \ --form 'prompt="Pretty lady dancing"' ``` ถ้าไม่ส่ง `account` API จะเลือกบัญชี Dreamina ของคุณที่ยังว่างรับงานได้ให้เอง คำตอบที่ได้มี `jobid`: ```json { "jobid": "j1112160042000000000v-u12345-CA:user@example.com-bot:dreamina", "type": "video", "status": "created", "model": "seedance-2.5-draft" } ``` ### ขั้นตอนที่ 2. รอให้เสร็จแล้วดูผล เรียก [GET /videos/`jobid`](/docs/api-dreamina-v1/get-dreamina-videos-jobid) ซ้ำราวทุก 15 วินาที หรือส่ง `replyUrl` ในขั้นตอนที่ 1 เพื่อให้ระบบส่งผลลัพธ์มาหาคุณ ```bash curl --location 'https://api.useapi.net/v1/dreamina/videos/j1112160042000000000v-u12345-CA:user@example.com-bot:dreamina' \ --header 'Authorization: Bearer user:12345-…' ``` ```json { "jobid": "j1112160042000000000v-u12345-CA:user@example.com-bot:dreamina", "status": "completed", "model": "seedance-2.5-draft", "response": { "videoUrl": "https://…/video.mp4", "width": 480, "height": 854, "durationMs": 4042 } } ``` ดราฟต์ของเราเสร็จใน 85 วินาที เป็นวิดีโอ 480×854 ใช้ 68 เครดิต: <video src="https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-draft-dancer-480p.mp4" poster="https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-draft-dancer-480p-poster.jpg" style="width: 100%; max-width: 400px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> ### ขั้นตอนที่ 3. เปลี่ยนดราฟต์เป็นวิดีโอ full quality ดราฟต์นี้ตรงกับที่เราต้องการ เราจึงส่ง `jobid` ของมันไปที่ [POST /videos/full-quality](/docs/api-dreamina-v1/post-dreamina-videos-full-quality): ```bash curl --location 'https://api.useapi.net/v1/dreamina/videos/full-quality' \ --header 'Authorization: Bearer user:12345-…' \ --form 'jobid="j1112160042000000000v-u12345-CA:user@example.com-bot:dreamina"' \ --form 'resolution="1080p"' ``` วิดีโอจะสร้างบนบัญชีเดียวกับดราฟต์ คำตอบคืองานวิดีโอใหม่ ซึ่งเรียกดูสถานะได้แบบเดียวกัน งานนี้ยังคงเป็น `model: "seedance-2.5-draft"` โดยมี `request.resolution` และ `request.draftJobid` ที่ใช้แยกงานนี้ออกจากดราฟต์: ```json { "jobid": "j1112160306000000000v-u12345-CA:user@example.com-bot:dreamina", "type": "video", "status": "created", "model": "seedance-2.5-draft", "request": { "inputMode": "full_quality", "resolution": "1080p", "draftJobid": "j1112160042000000000v-u12345-CA:user@example.com-bot:dreamina" } } ``` เสร็จในราว 2 นาที เป็นวิดีโอ 1080×1920 ใช้ 468 เครดิต: <video src="https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-full-quality-dancer-1080p.mp4" poster="https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-full-quality-dancer-1080p-poster.jpg" style="width: 100%; max-width: 400px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> ถ้าต้องการ 4K ให้ส่ง `resolution: "4k"` จากดราฟต์ที่สร้างบนบัญชีแคนาดา Dreamina เปิดให้ใช้บนบัญชีแคนาดา แม้ว่าการทดสอบของเราเองจะรันที่ 1080p ส่วน API ของ ByteDance เองเพิ่ม Seedance 2.5 ที่ 4K เมื่อวันที่ 16 พฤศจิกายน 2026 ในราคา $4.57 ต่อ 5 วินาที ที่นี่วิดีโอ 4K เดียวกันราคาราว $4.15 บนแพ็กเกจ Advanced ของแคนาดา วิดีโอที่เสร็จแล้วเป็นงานวิดีโอธรรมดา คุณจึงยัง[อัปสเกล](/docs/api-dreamina-v1/post-dreamina-videos-upscale)วิดีโอ 1080p หรือ[เพิ่มเฟรมเรต](/docs/api-dreamina-v1/post-dreamina-videos-interpolate)ได้ตามปกติ งานที่ไม่ใช่ดราฟต์ที่เสร็จแล้ว ดราฟต์ที่เก่ากว่า 14 วัน หรือ `4k` บนบัญชีสหรัฐฯ จะได้ `400` บัญชี Dreamina ที่ไม่มีแพ็กเกจแบบเสียเงินจะได้ `403` และบัญชีที่เครดิตหมดจะได้ `412` ส่วนงานที่ล้มเหลวภายหลังจะแสดง `status: "failed"` และ `error` เมื่อคุณเรียกดูสถานะ ### ดราฟต์กับ full quality เทียบกันแบบเคียงข้าง วิดีโอทั้งสองคือเทคเดียวกัน ท่าเต้น การหันศีรษะ การขยิบตา และจังหวะเวลาตรงกันตั้งแต่เฟรมแรกจนถึงเฟรมสุดท้าย นี่คือช่วงเวลาเดียวกันที่วินาทีที่ 3.5 ครอปมาจากทั้งสองวิดีโอ ดราฟต์ที่ขยายเป็น 1080p อยู่ทางซ้าย และวิดีโอ full quality อยู่ทางขวา: ![เฟรมเดียวกันของวิดีโอนักเต้นจากดราฟต์ Seedance 2.5 (ซ้าย ขยายจาก 480p) และวิดีโอ full quality 1080p (ขวา): ขยิบตาแบบเดียวกัน แต่ขนตา เส้นผม และผิวคมชัดกว่า](https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-draft-vs-full-quality-dancer-detail.jpg) ขนตา เส้นผมแต่ละเส้น และผิวออกมาคมชัด โดยไม่มีส่วนใดบนใบหน้าขยับเปลี่ยนไป ### ใช้งานจาก Claude, ChatGPT หรือ Cursor [เซิร์ฟเวอร์ MCP ของ Dreamina](/docs/api-dreamina-v1/mcp) ที่ useapi.net โฮสต์ไว้ ช่วยให้รันโฟลว์ดราฟต์แล้วทำให้เสร็จนี้จาก Claude Code, Cursor, VS Code และไคลเอนต์ MCP อื่นๆ ได้โดยไม่ต้องติดตั้งอะไร ส่วนแอป Claude และ ChatGPT เชื่อมต่อได้ด้วยการลงชื่อเข้าใช้ เซิร์ฟเวอร์นี้มี 15 tools และทำงานบนบัญชี Dreamina ของคุณเองด้วย API token ของ useapi.net ใน Claude Code: ```bash claude mcp add --transport http useapi-dreamina https://api.useapi.net/v1/dreamina/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` จากนั้นสั่งได้เลย เช่น "ทำดราฟต์ Seedance 2.5 จากพรอมต์นี้ ถ้าออกมาดีให้ทำเป็น full quality ที่ 1080p" ผู้ช่วยจะสร้างดราฟต์ด้วย `dreamina_create_video` และ `seedance-2.5-draft` แสดงลิงก์ให้ดู และเมื่อคุณอนุมัติก็จะเปลี่ยนเทคนั้นเป็น 1080p หรือ 4K บนบัญชีแคนาดา ด้วย `dreamina_full_quality_video` เซิร์ฟเวอร์นี้อยู่ใน MCP Registry ทางการในชื่อ `net.useapi/dreamina` และ repo [`dreamina-api`](https://github.com/useapi/dreamina-api#use-with-claude-code) ยังติดตั้งเป็นปลั๊กอิน Claude Code หรือ[ส่วนขยาย Gemini CLI](https://github.com/useapi/dreamina-api#use-with-gemini-cli) ได้ด้วย ### คำถามที่พบบ่อย #### Seedance 2.5 โหมดดราฟต์มี API ไหม? มี Dreamina API ของ useapi.net สร้างวิดีโอ `seedance-2.5-draft` ที่ 480p แล้วเปลี่ยนเป็น 1080p หรือ 4K บนบัญชี Dreamina แคนาดา โดยใช้แพ็กเกจ Dreamina ที่คุณจ่ายอยู่แล้ว API ของ ByteDance เองก็มีโหมดดราฟต์ ที่ 4K วิดีโอที่เสร็จแล้วที่นี่ราคาราว $4.15 บนแพ็กเกจ Advanced ของแคนาดา เทียบกับ $4.57 บน API ของ ByteDance โดยไม่ต้องซื้อแพ็กล่วงหน้า (ข้อมูล ณ 18 พฤศจิกายน 2026) #### ดราฟต์ Seedance 2.5 ราคาเท่าไร? ผ่าน useapi.net ดราฟต์ Seedance 2.5 ยาว 5 วินาทีใช้ 65 เครดิตบนบัญชี Dreamina สหรัฐฯ และ 85 เครดิตบนบัญชีแคนาดา คิดเป็นราว $0.59 หรือ $0.55 บนแพ็กเกจ Advanced (ข้อมูล ณ พฤศจิกายน 2026) จากนั้นวิดีโอ full quality มีราคาเท่ากับวิดีโอ `seedance-2.5` ที่ความละเอียดนั้น ดราฟต์จึงเป็นการรันเพิ่มที่ช่วยให้คุณไม่ต้องจ่ายค่าเทค full quality ที่สุดท้ายต้องทิ้งไป ดู[ราคา](#pricing) #### วิดีโอ full quality ออกมาเหมือนดราฟต์ไหม? เหมือน ด้วย Dreamina API ของ useapi.net วิดีโอ full quality สร้างจากดราฟต์ของคุณ จึงยังเป็นเทค การเคลื่อนไหว และจังหวะเวลาเดิม เพียงแต่คมชัดขึ้น ตามที่เห็นในภาพเทียบด้านบน ถ้าส่งพรอมต์เดิมไปที่ `seedance-2.5` อีกครั้ง จะได้วิดีโอคนละตัว #### สร้างวิดีโอ Seedance 2.5 แบบ 4K จากดราฟต์ได้ไหม? ได้ ผ่าน useapi.net บนบัญชี Dreamina แคนาดา: ส่ง `jobid` ของดราฟต์ไปที่ [POST /videos/full-quality](/docs/api-dreamina-v1/post-dreamina-videos-full-quality) พร้อม `resolution: "4k"` ในราคาเท่ากับวิดีโอ `seedance-2.5` แบบ 4K ส่วนบัญชีสหรัฐฯ สร้างได้ 1080p วิดีโอ 4K นั้นราคาราว $4.15 บนแพ็กเกจ Advanced ของแคนาดา เทียบกับ $4.57 บน API ของ ByteDance เอง (ข้อมูล ณ 18 พฤศจิกายน 2026) ### บทสรุป ดราฟต์ Seedance 2.5 ช่วยให้คุณลองไอเดียที่ 480p ในราคาเพียงเศษเสี้ยว แล้วเก็บเทคที่ชอบไว้ได้ตรงตามนั้นที่ 1080p หรือ 4K สร้างดราฟต์ด้วย [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos) และ `seedance-2.5-draft` แล้วทำให้เสร็จด้วย [POST /videos/full-quality](/docs/api-dreamina-v1/post-dreamina-videos-full-quality) โฟลว์ทั้งหมดเป็นสคริปต์เดียว ทั้ง Node.js และ Python บน GitHub: [useapi/dreamina-api/seedance-draft](https://github.com/useapi/dreamina-api/tree/main/seedance-draft) เชื่อมบัญชี Dreamina ของคุณผ่าน [Setup Dreamina](/docs/start-here/setup-dreamina) และดู[ภาพรวม Dreamina API](/docs/api-dreamina-v1) สำหรับทุกโมเดล === URL: https://useapi.net/docs/articles/dreamina-seedance-2-5-draft-vi === Document URL: https://useapi.net/docs/articles/dreamina-seedance-2-5-draft-vi --- layout: default title: Cách tạo bản nháp video Seedance 2.5 ở 480p rồi hoàn thiện ở 1080p hoặc 4K bằng Dreamina API seo_title: "Seedance 2.5 draft mode API: bản nháp 480p lên 1080p hoặc 4K" description: "Chế độ nháp (draft mode) Seedance 2.5 với Dreamina API của useapi.net: tạo bản nháp 480p, kiểm tra, rồi biến chính video đó thành 1080p hoặc 4K. Code đầy đủ, video thật, credit." keywords: [Seedance 2.5 draft mode, chế độ nháp Seedance 2.5, Seedance 2.5 draft API, bản nháp Seedance 2.5, Seedance 2.5 draft to 1080p, bản nháp Seedance 2.5 lên 1080p, Seedance 2.5 4K, Seedance 2.5 API, Dreamina API, Dreamina full quality, Dreamina chất lượng đầy đủ, Dreamina Seedance 2.5, ByteDance Seedance, hướng dẫn Seedance 2.5] image: https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-draft-vs-full-quality-dancer-detail.jpg parent: Articles nav_exclude: true lang: vi date: 2026-11-12 last_modified: 2026-11-20 nav_order: 821 repo: https://github.com/useapi/dreamina-api translation_key: seedance-2-5-draft --- ## Cách tạo bản nháp video Seedance 2.5 ở 480p rồi hoàn thiện ở 1080p hoặc 4K bằng Dreamina API {: #how-to-draft-seedance-25-videos-at-480p-and-finish-them-in-1080p-or-4k-with-the-dreamina-api .no_toc } 5 phút đọc • 12 tháng 11 năm 2026 (20 tháng 11 năm 2026) ## Mục lục {: #table-of-contents .no_toc .text-delta } ### Giới thiệu [Dreamina API](/docs/api-dreamina-v1) của useapi.net tạo bản nháp [Seedance 2.5](https://docs.byteplus.com/en/docs/modelark/seedance-2-5) ở 480p với giá chỉ khoảng một phần bảy so với cùng video đó ở 1080p. Khi đã ưng ý, bạn chỉ cần thêm một lệnh gọi [POST /videos/full-quality](/docs/api-dreamina-v1/post-dreamina-videos-full-quality) để biến chính bản nháp đó thành video 1080p, hoặc 4K trên tài khoản Canada. Video chất lượng đầy đủ giữ nguyên khung hình, chuyển động và nhịp của bản nháp, nên bạn chỉ trả giá đầy đủ cho cảnh quay mình đã duyệt. Một video 4K dài 5 giây ở đây tốn khoảng $4,15 trên gói Advanced của Canada, so với $4,57 trên API của chính ByteDance (tính đến ngày 18/11/2026). API chạy trên gói [Dreamina](https://dreamina.capcut.com/) bạn đang có, giống cách nút "Generate in full quality" của Dreamina hoạt động trên website. Bản nháp 480p và video 1080p làm từ bản nháp đó, phát cạnh nhau: <video src="https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-draft-vs-full-quality-dancer-side-by-side.mp4" poster="https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-draft-vs-full-quality-dancer-side-by-side-poster.jpg" style="width: 100%; max-width: 720px; aspect-ratio: 1450/1280;" controls type="video/mp4" preload="metadata"></video> Dưới đây là các request tạo ra hai video này và số credit mỗi bước đã dùng. ### Chế độ nháp của Seedance 2.5 hoạt động thế nào? 1. Gửi prompt tới [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos) với `model: "seedance-2.5-draft"`. Bạn nhận được một video 480p dài 4 đến 30 giây, tạo từ văn bản, từ khung hình đầu và khung hình cuối, hoặc từ tối đa 50 tham chiếu (30 ảnh, 10 video, 10 đoạn âm thanh), giống các đầu vào của `seedance-2.5`. 2. Xem video. Nếu chưa đúng ý, sửa prompt và tạo bản nháp khác. 3. Trong vòng 14 ngày, gửi `jobid` của bản nháp tới [POST /videos/full-quality](/docs/api-dreamina-v1/post-dreamina-videos-full-quality) với `resolution` là `1080p` hoặc `4k`. Dreamina dựng video chất lượng đầy đủ từ bản nháp đó, với prompt, tham chiếu, độ dài và tỉ lệ khung hình của nó. Tài khoản Mỹ và Canada đều tạo được bản nháp và video 1080p. 4K cần tài khoản Canada. Cả hai bước đều cần gói Dreamina trả phí. Dreamina không [upscale](/docs/api-dreamina-v1/post-dreamina-videos-upscale) được bản nháp: bước tiếp theo duy nhất của bản nháp là chất lượng đầy đủ. Còn video chất lượng đầy đủ 1080p thì upscale được như mọi video khác. ### Giá Chất lượng đầy đủ có giá bằng việc tạo video bằng `seedance-2.5` ở cùng độ phân giải. Bản nháp là một lần chạy thêm ngoài khoản đó, dù sau đó bạn làm 1080p hay 4K, nên nó đáng giá khi đằng nào bạn cũng sẽ thử một prompt nhiều hơn một lần. Giá của bản nháp và mọi model khác có trong [công cụ tính chi phí](/docs/start-here/setup-dreamina#cost-calculator). ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. ### Bước 1: tạo bản nháp Các bước dưới đây chỉ dùng `curl`. Cùng quy trình đó viết thành một script, bằng Node.js và Python, có trong [useapi/dreamina-api](https://github.com/useapi/dreamina-api/tree/main/seedance-draft) trên GitHub. Bạn cần một API token của useapi.net ([Setup useapi.net](/docs/start-here/setup-useapi)) và một tài khoản Dreamina có gói trả phí, đã kết nối theo [Setup Dreamina](/docs/start-here/setup-dreamina). ```bash curl --location 'https://api.useapi.net/v1/dreamina/videos' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="seedance-2.5-draft"' \ --form 'duration="4"' \ --form 'ratio="9:16"' \ --form 'prompt="Pretty lady dancing"' ``` Nếu bỏ `account`, API sẽ chọn một trong các tài khoản Dreamina của bạn còn trống chỗ. Response có `jobid`: ```json { "jobid": "j1112160042000000000v-u12345-CA:user@example.com-bot:dreamina", "type": "video", "status": "created", "model": "seedance-2.5-draft" } ``` ### Bước 2: chờ và xem kết quả Gọi [GET /videos/`jobid`](/docs/api-dreamina-v1/get-dreamina-videos-jobid) khoảng 15 giây một lần, hoặc truyền `replyUrl` ở bước 1 để kết quả được gửi thẳng tới bạn. ```bash curl --location 'https://api.useapi.net/v1/dreamina/videos/j1112160042000000000v-u12345-CA:user@example.com-bot:dreamina' \ --header 'Authorization: Bearer user:12345-…' ``` ```json { "jobid": "j1112160042000000000v-u12345-CA:user@example.com-bot:dreamina", "status": "completed", "model": "seedance-2.5-draft", "response": { "videoUrl": "https://…/video.mp4", "width": 480, "height": 854, "durationMs": 4042 } } ``` Bản nháp của chúng tôi xong sau 85 giây, một video 480×854 tốn 68 credit: <video src="https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-draft-dancer-480p.mp4" poster="https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-draft-dancer-480p-poster.jpg" style="width: 100%; max-width: 400px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> ### Bước 3: biến bản nháp thành video chất lượng đầy đủ Bản nháp đúng như ý, nên `jobid` của nó được gửi tới [POST /videos/full-quality](/docs/api-dreamina-v1/post-dreamina-videos-full-quality): ```bash curl --location 'https://api.useapi.net/v1/dreamina/videos/full-quality' \ --header 'Authorization: Bearer user:12345-…' \ --form 'jobid="j1112160042000000000v-u12345-CA:user@example.com-bot:dreamina"' \ --form 'resolution="1080p"' ``` Video được tạo trên chính tài khoản của bản nháp. Response là một job video mới, kiểm tra theo cùng cách. Job này vẫn giữ `model: "seedance-2.5-draft"`, còn `request.resolution` và `request.draftJobid` giúp phân biệt nó với bản nháp: ```json { "jobid": "j1112160306000000000v-u12345-CA:user@example.com-bot:dreamina", "type": "video", "status": "created", "model": "seedance-2.5-draft", "request": { "inputMode": "full_quality", "resolution": "1080p", "draftJobid": "j1112160042000000000v-u12345-CA:user@example.com-bot:dreamina" } } ``` Video xong sau khoảng 2 phút, một video 1080×1920 tốn 468 credit: <video src="https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-full-quality-dancer-1080p.mp4" poster="https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-full-quality-dancer-1080p-poster.jpg" style="width: 100%; max-width: 400px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> Để có 4K, gửi `resolution: "4k"` từ một bản nháp tạo trên tài khoản Canada. Dreamina có tùy chọn này ở đó, dù các thử nghiệm của chúng tôi chạy ở 1080p. API của chính ByteDance đã thêm Seedance 2.5 ở 4K từ ngày 16/11/2026, với giá $4,57 cho 5 giây. Ở đây cùng video 4K đó tốn khoảng $4,15 trên gói Advanced của Canada. Video hoàn chỉnh là một job video bình thường, nên bạn vẫn có thể [upscale](/docs/api-dreamina-v1/post-dreamina-videos-upscale) video 1080p hoặc [tăng tốc độ khung hình](/docs/api-dreamina-v1/post-dreamina-videos-interpolate) của nó. Job không phải là bản nháp đã hoàn tất, bản nháp quá 14 ngày, hoặc `4k` trên tài khoản Mỹ sẽ nhận `400`. Tài khoản Dreamina không có gói trả phí nhận `403`, còn tài khoản hết credit nhận `412`. Job thất bại về sau sẽ hiện `status: "failed"` và một `error` khi bạn kiểm tra. ### Bản nháp và chất lượng đầy đủ, đặt cạnh nhau Hai video là cùng một cảnh quay: động tác, cái quay đầu, cái nháy mắt và nhịp đều khớp từ khung hình đầu tiên đến khung hình cuối cùng. Đây là cùng một khoảnh khắc, ở giây thứ 3,5, cắt ra từ cả hai video. Bản nháp, phóng to lên 1080p, ở bên trái, còn video chất lượng đầy đủ ở bên phải: ![Cùng một khung hình của video vũ công từ bản nháp Seedance 2.5 (trái, 480p phóng to) và video chất lượng đầy đủ 1080p (phải): cùng cái nháy mắt, với lông mi, tóc và da sắc nét hơn](https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-draft-vs-full-quality-dancer-detail.jpg) Lông mi, từng sợi tóc và làn da đều hiện ra sắc nét, không có gì trên khuôn mặt bị xê dịch. ### Dùng từ Claude, ChatGPT hoặc Cursor [Máy chủ MCP Dreamina](/docs/api-dreamina-v1/mcp) do useapi.net lưu trữ đưa quy trình tạo nháp rồi hoàn thiện này vào Claude Code, Cursor, VS Code và các ứng dụng MCP khác, không cần cài đặt gì, còn ứng dụng Claude và ChatGPT kết nối bằng cách đăng nhập. Máy chủ có 15 công cụ và chạy trên chính tài khoản Dreamina của bạn với API token useapi.net của bạn. Trong Claude Code: ```bash claude mcp add --transport http useapi-dreamina https://api.useapi.net/v1/dreamina/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` Sau đó chỉ cần yêu cầu, ví dụ: "Tạo bản nháp Seedance 2.5 từ prompt này, nếu ổn thì làm bản chất lượng đầy đủ 1080p". Trợ lý tạo bản nháp bằng `dreamina_create_video` với `seedance-2.5-draft`, gửi bạn đường link, và khi bạn duyệt thì biến cảnh quay đó thành 1080p, hoặc 4K trên tài khoản Canada, bằng `dreamina_full_quality_video`. Máy chủ có trong MCP Registry chính thức với tên `net.useapi/dreamina`, và repo [`dreamina-api`](https://github.com/useapi/dreamina-api#use-with-claude-code) cũng cài được như một plugin Claude Code hoặc [tiện ích mở rộng Gemini CLI](https://github.com/useapi/dreamina-api#use-with-gemini-cli). ### Câu hỏi thường gặp #### Seedance 2.5 draft mode có API không? Có. Dreamina API của useapi.net tạo video `seedance-2.5-draft` ở 480p rồi biến chúng thành 1080p, hoặc 4K trên tài khoản Dreamina Canada, ngay trên gói Dreamina bạn đang trả tiền. API của chính ByteDance cũng có chế độ nháp. Ở 4K, một video hoàn chỉnh ở đây tốn khoảng $4,15 trên gói Advanced của Canada, so với $4,57 trên API của ByteDance, không cần gói trả trước (tính đến ngày 18/11/2026). #### Bản nháp Seedance 2.5 giá bao nhiêu? Qua useapi.net, một bản nháp Seedance 2.5 dài 5 giây tốn 65 credit trên tài khoản Dreamina Mỹ và 85 credit trên tài khoản Canada, khoảng $0,59 hoặc $0,55 trên gói Advanced (tính đến tháng 11/2026). Sau đó video chất lượng đầy đủ có giá bằng một video `seedance-2.5` ở độ phân giải đó, nên bản nháp là một lần chạy thêm giúp bạn khỏi trả tiền cho những bản chất lượng đầy đủ rồi sẽ bỏ đi. Xem [Giá](#pricing). #### Video chất lượng đầy đủ có giống bản nháp không? Có. Với Dreamina API của useapi.net, video chất lượng đầy đủ được dựng từ bản nháp của bạn, nên giữ nguyên cảnh quay, chuyển động và nhịp, chỉ sắc nét hơn, như phần so sánh cạnh nhau ở trên. Gửi lại cùng prompt đó cho `seedance-2.5` sẽ tạo ra một video khác. #### Có tạo được video Seedance 2.5 4K từ bản nháp không? Có, qua useapi.net trên tài khoản Dreamina Canada: gửi `jobid` của bản nháp tới [POST /videos/full-quality](/docs/api-dreamina-v1/post-dreamina-videos-full-quality) với `resolution: "4k"`, theo giá của một video `seedance-2.5` ở 4K. Tài khoản Mỹ tạo 1080p. Video 4K đó tốn khoảng $4,15 trên gói Advanced của Canada, so với $4,57 trên API của chính ByteDance (tính đến ngày 18/11/2026). ### Kết luận Bản nháp Seedance 2.5 cho bạn thử một ý tưởng ở 480p với một phần nhỏ chi phí rồi giữ đúng cảnh quay bạn thích, ở 1080p hoặc 4K. Tạo bản nháp bằng [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos) với `seedance-2.5-draft`, rồi hoàn thiện bằng [POST /videos/full-quality](/docs/api-dreamina-v1/post-dreamina-videos-full-quality). Toàn bộ quy trình là một script, bằng Node.js và Python, trên GitHub: [useapi/dreamina-api/seedance-draft](https://github.com/useapi/dreamina-api/tree/main/seedance-draft). Kết nối tài khoản Dreamina theo [Setup Dreamina](/docs/start-here/setup-dreamina), và xem [tổng quan Dreamina API](/docs/api-dreamina-v1) để biết mọi model. === URL: https://useapi.net/docs/articles/dreamina-seedance-2-5-draft-zh === Document URL: https://useapi.net/docs/articles/dreamina-seedance-2-5-draft-zh --- layout: default title: "如何用 Dreamina API 先以 480p 草稿生成 Seedance 2.5 视频,再输出 1080p 或 4K" seo_title: "Seedance 2.5 草稿模式 API:480p 草稿转 1080p 或 4K" description: "通过 useapi.net 的 Dreamina API 使用 Seedance 2.5 草稿模式:先生成 480p 草稿确认效果,再把同一条视频转成 1080p 或 4K。附完整代码、真实视频和积分消耗。" keywords: [Seedance 2.5 草稿模式, Seedance 2.5 草稿 API, Seedance 2.5 草稿转 1080p, Seedance 2.5 4K, Seedance 2.5 API, Seedance 2.5 教程, Dreamina API, Dreamina 全画质, Dreamina Seedance 2.5, 字节跳动 Seedance, AI 视频生成 API, Seedance 2.5 draft mode, Seedance 2.5 draft API, Seedance 2.5 draft to 1080p, Dreamina full quality, ByteDance Seedance] image: https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-draft-vs-full-quality-dancer-detail.jpg parent: Articles nav_exclude: true lang: zh-CN translation_key: seedance-2-5-draft date: 2026-11-12 last_modified: 2026-11-20 nav_order: 821 repo: https://github.com/useapi/dreamina-api --- ## 如何用 Dreamina API 先以 480p 草稿生成 Seedance 2.5 视频,再输出 1080p 或 4K {: .no_toc #how-to-draft-seedance-25-videos-at-480p-and-finish-them-in-1080p-or-4k-with-the-dreamina-api } 5 分钟阅读 • 2026 年 11 月 12 日(2026 年 11 月 20 日更新) ## 目录 {: .no_toc .text-delta #table-of-contents } ### 简介 useapi.net 的 [Dreamina API](/docs/api-dreamina-v1) 可以生成 480p 的 [Seedance 2.5](https://docs.byteplus.com/en/docs/modelark/seedance-2-5) 草稿,价格约为同一条视频 1080p 版本的七分之一。满意之后,再调用一次 [POST /videos/full-quality](/docs/api-dreamina-v1/post-dreamina-videos-full-quality),就能把这条草稿变成 1080p 视频,加拿大账号还可以输出 4K。全画质视频保留草稿的镜头、动作和节奏,所以你只需为已经确认的那一条付全价。在加拿大 Advanced 套餐上,一条 5 秒 4K 视频在这里约 $4.15,字节跳动自己的 API 为 $4.57(截至 2026 年 11 月 18 日)。它在你已有的 [Dreamina](https://dreamina.capcut.com/) 订阅上运行,原理与 Dreamina 网站上的“Generate in full quality”按钮相同。 480p 草稿和由它生成的 1080p 视频,并排播放: <video src="https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-draft-vs-full-quality-dancer-side-by-side.mp4" poster="https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-draft-vs-full-quality-dancer-side-by-side-poster.jpg" style="width: 100%; max-width: 720px; aspect-ratio: 1450/1280;" controls type="video/mp4" preload="metadata"></video> 下面是生成它们的请求,以及每一步消耗的积分。 ### Seedance 2.5 草稿模式如何工作? 1. 把提示词发送到 [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos),设置 `model: "seedance-2.5-draft"`。你会得到一条 4 到 30 秒的 480p 视频,输入可以是文本、首帧和尾帧,或最多 50 个参考素材(30 张图片、10 段视频、10 段音频),与 `seedance-2.5` 的输入相同。 2. 观看草稿。如果不满意,修改提示词,再生成一条草稿。 3. 在 14 天内,把草稿的 `jobid` 发送到 [POST /videos/full-quality](/docs/api-dreamina-v1/post-dreamina-videos-full-quality),并把 `resolution` 设为 `1080p` 或 `4k`。Dreamina 会基于这条草稿生成全画质视频,沿用它的提示词、参考素材、时长和画面比例。 美国和加拿大账号都可以生成草稿和 1080p 视频。4K 需要加拿大账号。两个步骤都需要付费的 Dreamina 套餐。 Dreamina 不能[放大](/docs/api-dreamina-v1/post-dreamina-videos-upscale)草稿:草稿的下一步只能是全画质。1080p 的全画质视频则可以像其他视频一样放大。 ### 价格 全画质的价格与直接用 `seedance-2.5` 生成同一分辨率的视频相同。草稿是在此之外多跑一次,无论之后输出 1080p 还是 4K 都是如此,所以当你本来就要把一个提示词试不止一次时,草稿才划算。草稿和其他所有模型的价格见[费用计算器](/docs/start-here/setup-dreamina#cost-calculator)。 ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. ### 第 1 步:生成草稿 下面的步骤都是普通的 `curl`。同样的流程写成一个脚本(Node.js 和 Python 两个版本),放在 GitHub 的 [useapi/dreamina-api](https://github.com/useapi/dreamina-api/tree/main/seedance-draft)。 你需要一个 useapi.net API Token([Setup useapi.net](/docs/start-here/setup-useapi)),以及一个带付费套餐、已通过 [Setup Dreamina](/docs/start-here/setup-dreamina) 绑定的 Dreamina 账号。 ```bash curl --location 'https://api.useapi.net/v1/dreamina/videos' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="seedance-2.5-draft"' \ --form 'duration="4"' \ --form 'ratio="9:16"' \ --form 'prompt="Pretty lady dancing"' ``` 不传 `account` 时,API 会从你的 Dreamina 账号中挑一个有空闲容量的账号。响应中包含 `jobid`: ```json { "jobid": "j1112160042000000000v-u12345-CA:user@example.com-bot:dreamina", "type": "video", "status": "created", "model": "seedance-2.5-draft" } ``` ### 第 2 步:等待生成并观看 每隔 15 秒左右轮询一次 [GET /videos/`jobid`](/docs/api-dreamina-v1/get-dreamina-videos-jobid),或者在第 1 步传入 `replyUrl`,让结果直接推送给你。 ```bash curl --location 'https://api.useapi.net/v1/dreamina/videos/j1112160042000000000v-u12345-CA:user@example.com-bot:dreamina' \ --header 'Authorization: Bearer user:12345-…' ``` ```json { "jobid": "j1112160042000000000v-u12345-CA:user@example.com-bot:dreamina", "status": "completed", "model": "seedance-2.5-draft", "response": { "videoUrl": "https://…/video.mp4", "width": 480, "height": 854, "durationMs": 4042 } } ``` 我们的草稿 85 秒生成完毕,是一条 480×854 的视频,消耗 68 积分: <video src="https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-draft-dancer-480p.mp4" poster="https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-draft-dancer-480p-poster.jpg" style="width: 100%; max-width: 400px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> ### 第 3 步:把草稿变成全画质视频 这条草稿正是我们想要的,所以把它的 `jobid` 发送到 [POST /videos/full-quality](/docs/api-dreamina-v1/post-dreamina-videos-full-quality): ```bash curl --location 'https://api.useapi.net/v1/dreamina/videos/full-quality' \ --header 'Authorization: Bearer user:12345-…' \ --form 'jobid="j1112160042000000000v-u12345-CA:user@example.com-bot:dreamina"' \ --form 'resolution="1080p"' ``` 视频在草稿所在的账号上生成。响应是一个新的视频任务,用同样的方式轮询。它仍然是 `model: "seedance-2.5-draft"`,通过 `request.resolution` 和 `request.draftJobid` 可以把它和草稿区分开: ```json { "jobid": "j1112160306000000000v-u12345-CA:user@example.com-bot:dreamina", "type": "video", "status": "created", "model": "seedance-2.5-draft", "request": { "inputMode": "full_quality", "resolution": "1080p", "draftJobid": "j1112160042000000000v-u12345-CA:user@example.com-bot:dreamina" } } ``` 约 2 分钟后生成完毕,是一条 1080×1920 的视频,消耗 468 积分: <video src="https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-full-quality-dancer-1080p.mp4" poster="https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-full-quality-dancer-1080p-poster.jpg" style="width: 100%; max-width: 400px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> 要输出 4K,请对加拿大账号上生成的草稿发送 `resolution: "4k"`。Dreamina 在加拿大提供 4K,不过我们自己的测试是在 1080p 下进行的。字节跳动自己的 API 于 2026 年 11 月 16 日上线了 4K 的 Seedance 2.5,5 秒 $4.57。在这里,同样的 4K 视频在加拿大 Advanced 套餐上约 $4.15。生成的视频是普通的视频任务,所以 1080p 的视频仍然可以[放大](/docs/api-dreamina-v1/post-dreamina-videos-upscale)或[提高帧率](/docs/api-dreamina-v1/post-dreamina-videos-interpolate)。 不是已完成草稿的任务、超过 14 天的草稿,或在美国账号上请求 `4k`,都会返回 `400`。没有付费套餐的 Dreamina 账号返回 `403`,积分用完的账号返回 `412`。之后才失败的任务,在轮询时会显示 `status: "failed"` 和 `error`。 ### 草稿与全画质并排对比 两条视频是同一条镜头:动作、转头、眨眼和节奏从第一帧到最后一帧都一致。下面是两条视频在第 3.5 秒同一瞬间的裁切画面。左边是放大到 1080p 的草稿,右边是全画质视频: ![Seedance 2.5 草稿(左,480p 放大)和全画质 1080p 视频(右)中舞者视频的同一帧:同样的眨眼,睫毛、发丝和皮肤更清晰](https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-draft-vs-full-quality-dancer-detail.jpg) 睫毛、一根根发丝和皮肤都变得清晰,脸部没有任何移位。 ### 在 Claude、ChatGPT 或 Cursor 中使用 useapi.net 托管的 [Dreamina MCP 服务器](/docs/api-dreamina-v1/mcp)让你在 Claude Code、Cursor、VS Code 等 MCP 客户端里完成这套先草稿、再出全画质的流程,无需安装任何东西,Claude 应用和 ChatGPT 登录后即可连接。它有 15 个工具,在你自己的 Dreamina 账号上运行,使用你的 useapi.net API Token。在 Claude Code 中: ```bash claude mcp add --transport http useapi-dreamina https://api.useapi.net/v1/dreamina/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` 然后直接提出需求,例如:“用这个提示词生成一条 Seedance 2.5 草稿,效果不错的话再输出 1080p 全画质。”助手会用 `dreamina_create_video` 和 `seedance-2.5-draft` 生成草稿并给出链接,你确认后,再用 `dreamina_full_quality_video` 把这一条变成 1080p(加拿大账号可以输出 4K)。该服务器已在官方 MCP Registry 中以 `net.useapi/dreamina` 收录,[`dreamina-api`](https://github.com/useapi/dreamina-api#use-with-claude-code) 仓库也可以作为 Claude Code 插件或 [Gemini CLI 扩展](https://github.com/useapi/dreamina-api#use-with-gemini-cli) 安装。 ### 常见问题 #### 有 Seedance 2.5 草稿模式 API 吗? 有。useapi.net 的 Dreamina API 可以生成 480p 的 `seedance-2.5-draft` 视频,再把它们变成 1080p,在加拿大 Dreamina 账号上还能变成 4K,用的是你已经付费的 Dreamina 订阅。字节跳动自己的 API 也有草稿模式。4K 成片在这里用加拿大 Advanced 套餐约 $4.15,字节跳动的 API 为 $4.57,且无需预付资源包(截至 2026 年 11 月 18 日)。 #### Seedance 2.5 草稿多少钱? 通过 useapi.net,一条 5 秒的 Seedance 2.5 草稿在美国 Dreamina 账号上消耗 65 积分,在加拿大账号上消耗 85 积分,按 Advanced 套餐计算约 $0.59 或 $0.55(截至 2026 年 11 月)。之后的全画质视频与同分辨率的 `seedance-2.5` 视频价格相同,所以草稿是多跑一次,省下的是那些本来会被你扔掉的全画质版本的费用。见[价格](#pricing)。 #### 全画质视频和草稿看起来一样吗? 一样。使用 useapi.net 的 Dreamina API,全画质视频是基于你的草稿生成的,所以保留同一条镜头、动作和节奏,只是更清晰,正如上面的并排对比所示。把同一个提示词再发给 `seedance-2.5`,则会生成一条不同的视频。 #### 能用草稿生成 4K 的 Seedance 2.5 视频吗? 可以,通过 useapi.net 在加拿大 Dreamina 账号上生成:把草稿的 `jobid` 发送到 [POST /videos/full-quality](/docs/api-dreamina-v1/post-dreamina-videos-full-quality),并设置 `resolution: "4k"`,价格与 4K 的 `seedance-2.5` 视频相同。美国账号输出 1080p。这条 4K 视频在加拿大 Advanced 套餐上约 $4.15,字节跳动自己的 API 为 $4.57(截至 2026 年 11 月 18 日)。 ### 结语 有了 Seedance 2.5 草稿,你可以只花一小部分费用在 480p 下试验想法,并把喜欢的那一条原样保留下来,输出 1080p 或 4K。用 [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos) 和 `seedance-2.5-draft` 生成草稿,再用 [POST /videos/full-quality](/docs/api-dreamina-v1/post-dreamina-videos-full-quality) 完成它。整个流程是一个脚本(Node.js 和 Python 两个版本),在 GitHub 上:[useapi/dreamina-api/seedance-draft](https://github.com/useapi/dreamina-api/tree/main/seedance-draft)。用 [Setup Dreamina](/docs/start-here/setup-dreamina) 绑定你的 Dreamina 账号,所有模型见 [Dreamina API 概览](/docs/api-dreamina-v1)。 === URL: https://useapi.net/docs/articles/dreamina-seedance-2-5-draft === Document URL: https://useapi.net/docs/articles/dreamina-seedance-2-5-draft --- layout: default title: How to Draft Seedance 2.5 Videos at 480p and Finish Them in 1080p or 4K with the Dreamina API seo_title: "Seedance 2.5 Draft Mode API: 480p Draft to 1080p or 4K" description: "Seedance 2.5 draft mode with the useapi.net Dreamina API: make a 480p draft, check it, then turn that same video into 1080p or 4K. Full code, real videos, credits." keywords: [Seedance 2.5 draft mode, Seedance 2.5 draft API, Seedance 2.5 draft to 1080p, Seedance 2.5 4K, Seedance 2.5 API, Dreamina API, Dreamina full quality, Dreamina Seedance 2.5, ByteDance Seedance] image: https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-draft-vs-full-quality-dancer-detail.jpg parent: Articles nav_exclude: true date: 2026-11-12 last_modified: 2026-11-20 nav_order: 821 repo: https://github.com/useapi/dreamina-api translation_key: seedance-2-5-draft --- ## How to Draft Seedance 2.5 Videos at 480p and Finish Them in 1080p or 4K with the Dreamina API 5 min read • November 12, 2026 (November 20, 2026) ## Table of contents ### Introduction The useapi.net [Dreamina API](/docs/api-dreamina-v1) makes a 480p [Seedance 2.5](https://docs.byteplus.com/en/docs/modelark/seedance-2-5) draft for about a seventh of the price of the same video at 1080p. Once you like it, one more call to [POST /videos/full-quality](/docs/api-dreamina-v1/post-dreamina-videos-full-quality) turns that same draft into a 1080p video, or 4K on a Canadian account. The full-quality video keeps the draft's shot, motion and timing, so you pay full price only for the take you already approved. A 5-second 4K video costs about $4.15 here on a Canadian Advanced plan, against $4.57 on ByteDance's own API (as of November 18, 2026). It runs on the [Dreamina](https://dreamina.capcut.com/) subscription you already have, the same way Dreamina's "Generate in full quality" button works on the website. The 480p draft and the 1080p video made from it, playing side by side: <video src="https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-draft-vs-full-quality-dancer-side-by-side.mp4" poster="https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-draft-vs-full-quality-dancer-side-by-side-poster.jpg" style="width: 100%; max-width: 720px; aspect-ratio: 1450/1280;" controls type="video/mp4" preload="metadata"></video> Below are the requests that make them and the credits each step used. ### How does Seedance 2.5 draft mode work? 1. Send your prompt to [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos) with `model: "seedance-2.5-draft"`. You get a 480p video of 4 to 30 seconds, from text, a start and an end frame, or up to 50 references (30 images, 10 videos, 10 audio clips), the same inputs as `seedance-2.5`. 2. Watch it. If it's not right, change the prompt and make another draft. 3. Within 14 days, send the draft's `jobid` to [POST /videos/full-quality](/docs/api-dreamina-v1/post-dreamina-videos-full-quality) with `resolution` `1080p` or `4k`. Dreamina builds the full-quality video from that draft, with its prompt, references, length and aspect ratio. US and Canadian accounts both make drafts and 1080p videos. 4K needs a Canadian account. Both steps need a paid Dreamina plan. Dreamina can't [upscale](/docs/api-dreamina-v1/post-dreamina-videos-upscale) a draft: its only next step is full quality. A 1080p full-quality video can be upscaled like any other. ### Pricing Full quality costs the same as making the video with `seedance-2.5` at that resolution. The draft is an extra run on top of that, whether you then make 1080p or 4K, so it pays off when you would otherwise try a prompt more than once. Prices for the draft and every other model are in the [cost calculator](/docs/start-here/setup-dreamina#cost-calculator). ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. ### Step 1. Make the draft The steps below are plain `curl`. The same flow as one script, in Node.js and Python, is in [useapi/dreamina-api](https://github.com/useapi/dreamina-api/tree/main/seedance-draft) on GitHub. You need a useapi.net API token ([Setup useapi.net](/docs/start-here/setup-useapi)) and a Dreamina account with a paid plan, connected through [Setup Dreamina](/docs/start-here/setup-dreamina). ```bash curl --location 'https://api.useapi.net/v1/dreamina/videos' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="seedance-2.5-draft"' \ --form 'duration="4"' \ --form 'ratio="9:16"' \ --form 'prompt="Pretty lady dancing"' ``` Leave out `account` and the API picks one of your Dreamina accounts with free capacity. The response carries the `jobid`: ```json { "jobid": "j1112160042000000000v-u12345-CA:user@example.com-bot:dreamina", "type": "video", "status": "created", "model": "seedance-2.5-draft" } ``` ### Step 2. Wait for it and watch it Poll [GET /videos/`jobid`](/docs/api-dreamina-v1/get-dreamina-videos-jobid) every 15 seconds or so, or pass `replyUrl` in step 1 and get the result posted to you. ```bash curl --location 'https://api.useapi.net/v1/dreamina/videos/j1112160042000000000v-u12345-CA:user@example.com-bot:dreamina' \ --header 'Authorization: Bearer user:12345-…' ``` ```json { "jobid": "j1112160042000000000v-u12345-CA:user@example.com-bot:dreamina", "status": "completed", "model": "seedance-2.5-draft", "response": { "videoUrl": "https://…/video.mp4", "width": 480, "height": 854, "durationMs": 4042 } } ``` Our draft was ready in 85 seconds, a 480×854 video for 68 credits: <video src="https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-draft-dancer-480p.mp4" poster="https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-draft-dancer-480p-poster.jpg" style="width: 100%; max-width: 400px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> ### Step 3. Turn the draft into a full-quality video The draft is what we wanted, so its `jobid` goes to [POST /videos/full-quality](/docs/api-dreamina-v1/post-dreamina-videos-full-quality): ```bash curl --location 'https://api.useapi.net/v1/dreamina/videos/full-quality' \ --header 'Authorization: Bearer user:12345-…' \ --form 'jobid="j1112160042000000000v-u12345-CA:user@example.com-bot:dreamina"' \ --form 'resolution="1080p"' ``` The video is made on the draft's own account. The response is a new video job, polled the same way. It keeps `model: "seedance-2.5-draft"`, and `request.resolution` and `request.draftJobid` tell it apart from the draft: ```json { "jobid": "j1112160306000000000v-u12345-CA:user@example.com-bot:dreamina", "type": "video", "status": "created", "model": "seedance-2.5-draft", "request": { "inputMode": "full_quality", "resolution": "1080p", "draftJobid": "j1112160042000000000v-u12345-CA:user@example.com-bot:dreamina" } } ``` It was ready in about 2 minutes, a 1080×1920 video for 468 credits: <video src="https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-full-quality-dancer-1080p.mp4" poster="https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-full-quality-dancer-1080p-poster.jpg" style="width: 100%; max-width: 400px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> For 4K, send `resolution: "4k"` from a draft made on a Canadian account. Dreamina offers it there, though our own tests ran at 1080p. ByteDance's own API added Seedance 2.5 at 4K on November 16, 2026, at $4.57 for 5 seconds. Here the same 4K video costs about $4.15 on a Canadian Advanced plan. The finished video is an ordinary video job, so you can still [upscale](/docs/api-dreamina-v1/post-dreamina-videos-upscale) a 1080p one or [raise its frame rate](/docs/api-dreamina-v1/post-dreamina-videos-interpolate). A job that isn't a finished draft, a draft older than 14 days, or `4k` on a US account gets `400`. A Dreamina account without a paid plan gets `403`, and one out of credits `412`. A job that fails later shows `status: "failed"` and an `error` when you poll it. ### Draft and full quality, side by side The two videos are the same take: the moves, the turn of the head, the wink and the timing match from the first frame to the last. Here is the same moment, 3.5 seconds in, cropped from both. The draft, enlarged to 1080p, is on the left and the full-quality video on the right: ![The same frame of the dancer video from the Seedance 2.5 draft (left, 480p enlarged) and the full-quality 1080p video (right): the same wink, with sharper eyelashes, hair and skin](https://media.useapi.net/dreamina/2026-11-12-seedance-2-5-draft-article/dreamina-seedance-2-5-draft-vs-full-quality-dancer-detail.jpg) Eyelashes, single strands of hair and the skin come out sharp, with nothing in the face moved. ### Use it from Claude, ChatGPT or Cursor The hosted [Dreamina MCP server](/docs/api-dreamina-v1/mcp) brings this draft-then-finish flow to Claude Code, Cursor, VS Code and other MCP clients, with nothing to install, and the Claude app and ChatGPT connect to it with a sign-in. It has 15 tools and runs on your own Dreamina accounts with your useapi.net API token. In Claude Code: ```bash claude mcp add --transport http useapi-dreamina https://api.useapi.net/v1/dreamina/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` Then ask, for example, "Make a Seedance 2.5 draft of this prompt, and if it looks right, render it in full quality at 1080p". The assistant makes the draft with `dreamina_create_video` and `seedance-2.5-draft`, shows you its link and, once you approve it, turns that take into 1080p, or 4K on a Canadian account, with `dreamina_full_quality_video`. The server is listed in the official MCP Registry as `net.useapi/dreamina`, and the [`dreamina-api`](https://github.com/useapi/dreamina-api#use-with-claude-code) repo also installs as a Claude Code plugin or a [Gemini CLI extension](https://github.com/useapi/dreamina-api#use-with-gemini-cli). ### Questions #### Is there a Seedance 2.5 draft mode API? Yes. The useapi.net Dreamina API makes 480p `seedance-2.5-draft` videos and turns them into 1080p, or 4K on a Canadian Dreamina account, on the Dreamina subscription you already pay for. ByteDance's own API also has a draft mode. At 4K a finished video costs about $4.15 here on a Canadian Advanced plan, against $4.57 on ByteDance's API, with no prepaid pack (as of November 18, 2026). #### How much does a Seedance 2.5 draft cost? Through useapi.net a 5-second Seedance 2.5 draft costs 65 credits on a US Dreamina account and 85 on a Canadian one, about $0.59 or $0.55 on the Advanced plan (as of November 2026). The full-quality video then costs what a `seedance-2.5` video does at that resolution, so the draft is an extra run that saves you paying for full-quality takes you would throw away. See [Pricing](#pricing). #### Does the full-quality video look like the draft? Yes. With the useapi.net Dreamina API the full-quality video is built from your draft, so it keeps the same take, motion and timing, only sharper, as the side-by-side above shows. Sending the same prompt to `seedance-2.5` again would make a different video. #### Can I make a 4K Seedance 2.5 video from a draft? Yes, through useapi.net on a Canadian Dreamina account: send the draft's `jobid` to [POST /videos/full-quality](/docs/api-dreamina-v1/post-dreamina-videos-full-quality) with `resolution: "4k"`, at the price of a 4K `seedance-2.5` video. US accounts make 1080p. That 4K video costs about $4.15 on a Canadian Advanced plan, against $4.57 on ByteDance's own API (as of November 18, 2026). ### Conclusion A Seedance 2.5 draft lets you try an idea at 480p for a fraction of the price and keep exactly the take you like, at 1080p or 4K. Make one with [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos) and `seedance-2.5-draft`, then finish it with [POST /videos/full-quality](/docs/api-dreamina-v1/post-dreamina-videos-full-quality). The whole flow is one script, in Node.js and Python, on GitHub: [useapi/dreamina-api/seedance-draft](https://github.com/useapi/dreamina-api/tree/main/seedance-draft). Connect your Dreamina account with [Setup Dreamina](/docs/start-here/setup-dreamina), and see the [Dreamina API overview](/docs/api-dreamina-v1) for every model. === URL: https://useapi.net/docs/articles/flowmusic-bash === Document URL: https://useapi.net/docs/articles/flowmusic-bash --- layout: default title: How to Generate AI Music with Lyria 3 Pro via the Flow Music API description: "Generate full songs with Google's Lyria 3 Pro via a third-party REST API for Flow Music — copy-paste curl quick start, pricing, custom lyrics, and a batch script." keywords: [Flow Music API, Lyria 3 Pro API, AI music generation API, Suno alternative, Udio alternative, text to music, custom lyrics] parent: Articles nav_exclude: true date: 2026-06-19 last_modified: 2026-11-09 nav_order: 800 repo: https://github.com/useapi/flowmusic-api --- ## How to Generate AI Music with Lyria 3 Pro via the Flow Music API 5 min read • June 19, 2026 (November 9, 2026) ## Table of contents ### Introduction [Lyria 3 Pro](https://deepmind.google/models/lyria/) is Google DeepMind's text-to-music model, and the [useapi.net Flow Music API](/docs/api-flowmusic-v1) runs it over plain REST on your Flow Music website subscription. Lyria 3 Pro powers [Flow Music](https://www.flowmusic.app), [Google Labs](https://labs.google)' generator (formerly Producer AI, originally [Riffusion](https://www.riffusion.com)). One prompt returns a complete, produced song — vocals, melody, and arrangement — and from there you can supply your own lyrics, force an instrumental, or edit a clip with cover, remix, extend, replace, effects, and stem-splitting. ### Capabilities and parameters Songs default to Lyria 3 Pro, and `model: "lyria-3.5"` selects the newer Lyria 3.5. Each call returns up to two clips (an A/B pair), each up to roughly three minutes long. The main fields on the [music](/docs/api-flowmusic-v1/post-flowmusic-music) endpoint: | Parameter | Type | What it does | |-----------|------|--------------| | `prompt` | string (required) | Song description — style, mood, genre, instruments, BPM, vocal direction. 1–10,000 chars. | | `instrumental` | boolean | `true` forces an instrumental (prepends an `[Instrumental]` tag). `false` (default) lets the model decide whether to sing. | | `lyrics` | string | Your own `[Verse]`/`[Chorus]`-tagged lyrics (≤10,000 chars) — forces a vocal render of those exact words. | | `model` | `lyria-3-pro` \| `lyria-3.5` | Which Lyria model renders the song. `lyria-3-pro` is the default. | | `ghostwriter` | `standard` \| `pro` | Which lyrics-writer version writes the words when the model writes them. No effect if you supply your own `lyrics`. | | `mode` | `sync` \| `async` | `sync` (default) blocks ~40–150 s and returns the finished song. `async` returns a `jobid` to poll. | | `email` | string | Which connected account to use. Omit it and the API load-balances across accounts with free capacity. | If you omit both `instrumental` and `lyrics`, the model decides whether to sing from your prompt alone. The endpoint also accepts `replyUrl`/`replyRef` webhooks and experimental `refImage`/`refAudio` reference hints — see the [music endpoint docs](/docs/api-flowmusic-v1/post-flowmusic-music) for the full body. Generation is only the first step — the [music/edit](/docs/api-flowmusic-v1/post-flowmusic-music-edit) endpoint reworks any existing clip with six operations: | Operation | What it does | |-----------|--------------| | `cover` | Restyle the whole song (a Lyria 3 Pro cover) | | `remix` | Re-sing with edited lyrics | | `extend` | Add 1–300 s of new music (default 150 s), at the end or from a chosen point | | `replace` | Regenerate a specific time section | | `effect` | Apply `Trim`, `Fade`, `Gain`, `Reverb`, `Pan`, or `Equalizer` | | `stems` | Split into four stems — drums, bass, vocals, other | The [editing section below](#custom-lyrics-instrumentals-and-editing-a-song) shows the request shapes for each. ### Pricing Your Flow Music website subscription pays for every song, with no per-song surcharge from useapi.net. A song costs 5 credits, which comes to about 1.3¢ on [Flow Music Starter](https://www.flowmusic.app/pricing) ($8 a month for 3,000 credits) and 1.1¢ on Member ($64 for 30,000), against 8¢ a song for Lyria 3 Pro on Google's [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) (as of October 2026). A Google AI subscription includes a Flow Music plan with its own credits, separate from the Google AI credits: Starter on [Google AI Plus](https://support.google.com/googleone/answer/16882689), Plus on [Google AI Pro](https://support.google.com/googleone/answer/14534406) and Member on [Google AI Ultra](https://support.google.com/googleone/answer/16286513). Cover, remix, extend, replace, effects and stem-splitting run on the same credits, the Free plan generates a little each day from daily top-up credits, and downloads (mp3, wav, m4a, stems) cost nothing. The [Flow Music API overview](/docs/api-flowmusic-v1) has the full cost calculator, and [Setup Flow Music](/docs/start-here/setup-flowmusic) connects an account. ### Generate a song in two API calls You need a useapi.net [API token](/docs/start-here/setup-useapi) and a connected [Flow Music account](/docs/start-here/setup-flowmusic) — export the token so the `curl` examples below run as-is: `export USEAPI_TOKEN="user:1234-..."`. The fastest reliable workflow is asynchronous: the create call returns a `jobid` immediately, then you poll until the song is ready. First, submit the job with `POST https://api.useapi.net/v1/flowmusic/music`: ```bash curl -X POST "https://api.useapi.net/v1/flowmusic/music" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "warm indie folk ballad, acoustic guitar, soft female vocals, 70 bpm, wistful and hopeful", "ghostwriter": "pro", "mode": "async" }' ``` In `async` mode the response returns immediately with `201 Created`, a `jobid`, and `status: "pending"`: ```json { "jobid": "job:aaaabbbb-cccc-4ddd-8eee-ffff99990000-user:1234-user@email.com-bot:flowmusic", "email": "user@email.com", "status": "pending", "created_at": "2026-06-01T18:40:42.412Z", "request": { "prompt": "warm indie folk ballad...", "mode": "async" } } ``` Then poll for the result with `GET https://api.useapi.net/v1/flowmusic/jobs/{jobid}` (the `jobid` is URL-encoded in the path — it contains `:` and `@`): ```bash curl "https://api.useapi.net/v1/flowmusic/jobs/JOBID" \ -H "Authorization: Bearer $USEAPI_TOKEN" ``` When `status` is `completed`, the finished audio lives in the `clips[]` array — `audio_url` is the signed `.m4a`, and `wav_url` is the WAV file: ```json { "jobid": "job:aaaabbbb-...-bot:flowmusic", "status": "completed", "duration_ms": 132711, "clips": [ { "clip": "user:1234-user@email.com-clip:a1b2c3d4-...", "title": "Morning Sun", "duration_s": 173.04, "lyrics": "[Verse 1]\nCity lights blur in the rain\n[Chorus]\nAnd I will wait for the morning sun", "audio_url": "https://storage.googleapis.com/...a1b2c3d4.m4a", "wav_url": "https://storage.googleapis.com/...a1b2c3d4.wav", "image_url": "https://storage.googleapis.com/...b2c3d4e5.jpg" } ] } ``` Lyria 3 Pro typically finishes in 40–150 seconds. Result URLs are signed, so download promptly. Prefer not to poll? `mode: "sync"` (the default) waits for the song and returns the same completed record inline with `200 OK` (a song still unfinished after 7 minutes answers `202` with its `jobid` to poll). The song keeps rendering if your connection drops, but on mobile, flaky networks or short-timeout platforms prefer `async`, so you always have the `jobid`. You can also pass a `replyUrl` to receive a webhook when the job completes. A job can come back `status: "failed"` (e.g. a content-moderation refusal), and the create call may return `402` (insufficient credits), `422` (prompt moderated / no audio), or `429` (all accounts busy) — see the [endpoint docs](/docs/api-flowmusic-v1/post-flowmusic-music) for the full list. ### Custom lyrics, instrumentals, and editing a song You control the voicing entirely from the request body. Set `instrumental: true` for a purely instrumental track, or paste tagged lyrics to force a sung render of your exact words: ```bash # Instrumental only curl -X POST "https://api.useapi.net/v1/flowmusic/music" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "energetic synthwave, driving bass, retro 80s, 120 bpm", "instrumental": true }' # Your own lyrics → forces a vocal render of those words curl -X POST "https://api.useapi.net/v1/flowmusic/music" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "soulful R&B, lush keys, 90 bpm", "lyrics": "[Verse 1]\nCity lights blur in the rain\n[Chorus]\nAnd I will wait for the morning sun" }' ``` Once you have a clip's id, the [music/edit](/docs/api-flowmusic-v1/post-flowmusic-music-edit) endpoint runs any of the six operations from the [table above](#capabilities-and-parameters). For example, to extend a song by 30 seconds: ```bash curl -X POST "https://api.useapi.net/v1/flowmusic/music/edit" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "operation": "extend", "clip": "CLIP_ID_FROM_A_PREVIOUS_GENERATION", "extend_s": 30 }' ``` See the [editing docs](/docs/api-flowmusic-v1/post-flowmusic-music-edit) for each operation's parameters. ### Batch-generate with a script Finding the right track takes many attempts, and running them by hand is tedious. The Node.js script below reads a list of prompts from `prompts.json`, submits each one to the music endpoint in `async` mode, polls every job until it is done, then downloads all the resulting `.m4a` clips — so you can queue a batch and come back to a folder of finished songs. You need [Node.js](https://nodejs.org) v21 or newer. Put `prompts.json` and `flowmusic.mjs` in the same folder and run `node ./flowmusic.mjs API_TOKEN EMAIL`, where `API_TOKEN` is your useapi.net [API token](/docs/start-here/setup-useapi) and `EMAIL` is the configured [Flow Music account](/docs/start-here/setup-flowmusic) email you want to use. Each entry's `prompt` is required, and the optional `instrumental`, `lyrics`, and `ghostwriter` fields map straight to the [music](/docs/api-flowmusic-v1/post-flowmusic-music) endpoint. <details markdown="block"> <summary>Expand `prompts.json`</summary> ```json [ { "prompt": "lo-fi hip hop, mellow piano, 80 bpm. By default the model decides whether to sing based on your prompt." }, { "prompt": "warm indie folk ballad, acoustic guitar, soft female vocals, 70 bpm, wistful and hopeful", "ghostwriter": "pro" }, { "prompt": "energetic synthwave, driving bass, retro 80s, 120 bpm", "instrumental": true }, { "prompt": "soulful R&B, lush keys, 90 bpm. Provide your own [Verse]/[Chorus]-tagged lyrics to force a vocal render of those exact words. For all parameters see https://useapi.net/docs/api-flowmusic-v1/post-flowmusic-music", "lyrics": "[Verse 1]\nCity lights blur in the rain\n[Chorus]\nAnd I will wait for the morning sun" } ] ``` </details> <details markdown="block"> <summary>Expand `flowmusic.mjs` script</summary> ```javascript /* Script version 1.0, June 19, 2026 Script to batch-generate music using prompts with the Flow Music API v1 by useapi.net 🚀 Generates complete songs with Google's Lyria 3 Pro via the music endpoint. For more details visit https://useapi.net/docs/api-flowmusic-v1/post-flowmusic-music Installation Instructions: ========================== You need Node.js v21 or newer installed to run this script. Download and install Node.js from: - Windows, macOS, Linux: https://nodejs.org/ After installation, verify by running the following command in a terminal: node -v Running the Script: =================== Usage: node flowmusic.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE] Replace API_TOKEN with your actual useapi.net API token, see https://useapi.net/docs/start-here/setup-useapi Replace EMAIL with configured Flow Music email account, see https://useapi.net/docs/start-here/setup-flowmusic If optional PROMPTS_FILE not provided prompts.json will be used. Example: -------- node flowmusic.mjs user:1234-abcdefhijklmnopqrstuv my@email.com This command executes the script using API token user:1234-abcdefhijklmnopqrstuv with my@email.com Flow Music account email. Changelog: ========== - June 19, 2026: Initial release. Submits prompts to the music endpoint in async mode and downloads the resulting m4a clips. */ import readline from 'node:readline'; import fs from 'fs/promises'; import { writeFile } from 'node:fs/promises'; import { Readable } from 'node:stream'; // Constants const RESULTS_FILE = 'flowmusic_results.txt'; const ERRORS_FILE = 'flowmusic_errors.txt'; const DEFAULT_PROMPTS_FILE = 'prompts.json'; const SLEEP_429 = 10 * 1000; // in milliseconds const MAX_429_RETRIES = 6; // give up a prompt after this many consecutive 429s (all accounts busy) const SLEEP_POLL = 15 * 1000; // in milliseconds const urlAccounts = 'https://api.useapi.net/v1/flowmusic/accounts'; const urlMusic = 'https://api.useapi.net/v1/flowmusic/music'; const urlJobs = 'https://api.useapi.net/v1/flowmusic/jobs/'; // Utility to sleep for given milliseconds const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); const elapsedTimeSec = (start) => (Date.now() - start) / 1000; // Function to fetch configured Flow Music API accounts async function fetchAccounts(apiToken) { const response = await fetch(urlAccounts, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.error(`⛔ Error fetching accounts (HTTP ${response.status}): ${response.statusText}`); process.exit(1); } return response.json(); } // Submit a single prompt to the music endpoint in async mode. // Returns the HTTP status; on 201 the jobid is appended to RESULTS_FILE. async function submitMusic(apiToken, email, prompt, index) { const { prompt: text, instrumental, lyrics, ghostwriter } = prompt; console.log(`🚀 Lyria 3 Pro » Prompt #${index} • account ${email} • ${instrumental ? 'instrumental' : 'auto vocals'} …`); const body = JSON.stringify({ email, prompt: text, instrumental, lyrics, ghostwriter, mode: 'async' }); const createResponse = await fetch(urlMusic, { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiToken}` }, body }); const createBody = await createResponse.text(); // 201 Created — async job queued; 200 OK — sync result (returned if mode is overridden). if (createResponse.status == 201 || createResponse.status == 200) { const json = JSON.parse(createBody); const { jobid } = json; if (jobid) { await fs.appendFile(RESULTS_FILE, `${jobid},#${index}:${text}\n`); console.log(`✅ jobid`, jobid); return 201; } else { const error = `No jobid found in HTTP ${createResponse.status} response`; console.log(`❓ ${error}`, createBody); await fs.appendFile(ERRORS_FILE, `${error},#${index}:${text}\n`); return 500; } } else { switch (createResponse.status) { case 429: console.log(`🔄️ Retry on HTTP ${createResponse.status}`); break; case 422: console.log(`🛑 MODERATED prompt — the model declined to generate audio`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${text}\n`); break; case 402: console.log(`🛑 account has insufficient credits`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${text}\n`); break; case 596: console.log(`🛑 account in error state — re-add it at https://useapi.net/docs/start-here/setup-flowmusic`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${text}\n`); break; default: console.log(`❗ FAILED with HTTP ${createResponse.status}`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${text}\n`); } return createResponse.status; } } // Function to poll jobs and download generated audio clips async function download(apiToken) { if (! await fileExists(RESULTS_FILE)) return; try { const resultsContent = await fs.readFile(RESULTS_FILE, 'utf8'); const lines = resultsContent.trim().split('\n'); for (const line of lines) { const [jobid, prompt] = line.split(','); console.log(`👉 ${jobid}`); while (true) { const response = await fetch(`${urlJobs}${encodeURIComponent(jobid)}`, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.log(`🛑 Poll failed ${jobid} (HTTP ${response.status}):\n${prompt}\n`, await response.text()); break; } const jobResponseBody = await response.json(); const { status, clips, error } = jobResponseBody; if (status == 'failed') { console.error(`🛑 FAILED ${jobid} (${error?.code}: ${error?.message}):\n${prompt}\n`); break; } if (status == 'completed') { if (Array.isArray(clips) && clips.length > 0) { // A single generation returns up to two clips (an A/B pair) — download all of them. for (let c = 0; c < clips.length; c++) { const { clip, audio_url } = clips[c]; const audioFilename = `${clip.replace(/[:/]/g, '_')}.m4a`; if (await fileExists(audioFilename)) { console.log(`⚠️ ${audioFilename} already exists. Skipping download.`); continue; } if (audio_url) { console.log(`✅ Downloading ${audio_url} to ${audioFilename}`); try { const audioResponse = await fetch(audio_url); if (!audioResponse.ok) { console.error(`⛔ Unable to download ${jobid} (HTTP ${audioResponse.status}):\n${prompt}\n`, audio_url); continue; } const stream = Readable.fromWeb(audioResponse.body); await writeFile(audioFilename, stream); } catch (err) { console.error(`⛔ Error during download: ${err}`); } } else { console.error(`🛑 No audio_url for clip ${clip} (${jobid}):\n${prompt}\n`); } } } else { console.error(`🛑 ${jobid} completed but returned no clips:\n${prompt}\n`); } break; } console.log(`⌛ ${jobid} status (${status}) and is still in progress, waiting…`); await sleep(SLEEP_POLL); } } } catch (error) { console.log(`⛔ Error during download:`, error.stack || error); } } // Main function async function main() { const apiToken = process.argv[2]; const email = process.argv[3]; const promptFile = process.argv[4] || DEFAULT_PROMPTS_FILE; if (!apiToken || !email) { console.error('Usage: node flowmusic.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE]'); process.exit(1); } console.info('Script v1.0'); console.info('Node version is: ' + process.version); try { if (await fileExists(RESULTS_FILE)) { let user_input; while (!['y', 'n'].includes(user_input)) { user_input = (await promptUser(`❔ ${RESULTS_FILE} file detected. Do you want to download the results now? (y/n): `))?.toLowerCase(); if (user_input == 'y') { await download(apiToken); await fs.unlink(RESULTS_FILE); } } } const start = new Date(); try { console.info('START EXECUTION', start); await execute(apiToken, email, promptFile); // Pass the promptFile to execute function } finally { console.info('COMPLETED', new Date()); console.info('EXECUTION ELAPSED', diffInMinutesAndSeconds(start, new Date())); } try { console.info('START DOWNLOAD', start); await download(apiToken); } finally { console.info('TOTAL ELAPSED', diffInMinutesAndSeconds(start, new Date())); } } catch (error) { console.error('⛔ Error during execution:', error.stack || error); } } // Modify the execute function to accept promptFile as a parameter async function execute(apiToken, email, promptFile) { const accounts = await fetchAccounts(apiToken); console.info(`Configured Flow Music API accounts (${Object.values(accounts).length}):`, Object.values(accounts).map(a => a.email).join(', ')); if (Object.values(accounts).length <= 0) { console.error(`⛔ No configured Flow Music accounts found. Please refer to https://useapi.net/docs/start-here/setup-flowmusic`); process.exit(1); } if (!accounts[email]) { console.error(`⛔ Account ${email} not found. Please refer to https://useapi.net/docs/start-here/setup-flowmusic`); process.exit(1); } if (accounts[email].error) { console.error(`⛔ Account ${email} has pending error. Please re-add the account, see https://useapi.net/docs/start-here/setup-flowmusic`); process.exit(1); } const promptData = await fs.readFile(promptFile, 'utf8'); const prompts = JSON.parse(promptData); console.log(`Total number of prompts to process`, prompts.length); let warnings = []; // Parameters accepted by this script for the music endpoint. // See https://useapi.net/docs/api-flowmusic-v1/post-flowmusic-music for the full parameter set. const supportedParams = ['prompt', 'instrumental', 'lyrics', 'ghostwriter']; const invalidKeys = (prompt) => Object.keys(prompt).filter(key => !key.startsWith('__') && !supportedParams.includes(key)); for (let i = 1; i <= prompts.length; i++) { const prompt = prompts[i - 1]; const { prompt: text, ghostwriter } = prompt; const notSupported = invalidKeys(prompt); if (notSupported.length) warnings.push(`⚠️ Following params not supported: ${notSupported.join(',')}. Prompt ${i}`); if (!text || typeof text !== 'string' || text.trim().length === 0) warnings.push(`⚠️ Please specify a non-empty prompt. Prompt ${i}`); if (typeof text === 'string' && text.length > 10000) warnings.push(`⚠️ prompt exceeds 10,000 characters. Prompt ${i}`); if (ghostwriter !== undefined && !['standard', 'pro'].includes(ghostwriter)) warnings.push(`⚠️ ghostwriter must be 'standard' or 'pro'. Prompt ${i}`); } if (warnings.length > 0) { warnings.forEach(warning => console.warn(warning)); console.error(`⛔ Execution stopped due to warnings.`); process.exit(1); } for (let i = 0; i < prompts.length; i++) { const prompt = prompts[i]; let retries429 = 0; while (true) { const responseCode = await submitMusic(apiToken, email, prompt, i + 1); if (responseCode == 429) { if (++retries429 > MAX_429_RETRIES) { console.error(`⛔ Gave up on prompt #${i + 1} after ${MAX_429_RETRIES} retries — all accounts still busy.`); await fs.appendFile(ERRORS_FILE, `429 (gave up after ${MAX_429_RETRIES} retries),#${i + 1}\n`); break; } await sleep(SLEEP_429); } else if (responseCode == 402 || responseCode == 596) { process.exit(1); } else break; } } } // Utility function to check if a file exists async function fileExists(path) { try { await fs.access(path); return true; } catch { return false; } } // Function to prompt user input async function promptUser(query) { const rl = readline.createInterface({ input: process.stdin, output: process.stdout }); return new Promise((resolve) => rl.question(query, answer => { rl.close(); resolve(answer); })); } function diffInMinutesAndSeconds(date1, date2) { const diffInSeconds = Math.floor((date2 - date1) / 1000); return `${Math.floor(diffInSeconds / 60)} minutes ${diffInSeconds % 60} seconds`; }; main(); ``` </details> ### Examples These are real songs generated with Lyria 3 Pro through the Flow Music API — each from a single text prompt, exactly as the workflow above produces them. Full prompts and `curl` for each are in the [FlowMusic API v1 launch post](/blog/260603). “Euphoric Currents”, an instrumental liquid drum & bass track (`instrumental: true`), from [FlowMusic API v1: Powered by Lyria 3 Pro](/blog/260603): <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-06-03-260603/inst-06-dnb-a.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> “Solid Ground”, an emotional pop ballad with a soaring female vocal (model-written lyrics), from [FlowMusic API v1: Powered by Lyria 3 Pro](/blog/260603): <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-06-03-260603/01-vocal-pop-ballad-b.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> “Running on Empty”, an epic power ballad rendered from custom `[Verse]`/`[Chorus]` lyrics, from [FlowMusic API v1: Powered by Lyria 3 Pro](/blog/260603): <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-06-03-260603/song-lyrics-02-coffee-b.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> For more samples — including `extend`, `cover`, `remix`, studio `effect`s, and AI-generated cover art — see the [full launch post](/blog/260603). Related tutorials: [five AI music APIs on the same six briefs](/docs/articles/ai-music-flagships-compared), [AI music with the Mureka API](/docs/articles/mureka-bash) and [AI music APIs compared](/docs/articles/ai-music-api-comparison). ### Frequently asked questions **Is there a Lyria 3 Pro API?** Through useapi.net, yes: the [Flow Music API](/docs/api-flowmusic-v1) runs Lyria 3 Pro, and the newer Lyria 3.5, on your [Flow Music](https://www.flowmusic.app) website subscription through a standard REST endpoint, with cover, remix, extend, replace, effects and stem-splitting on top of plain generation. Google offers no public Flow Music API of its own (as of October 2026). You connect the account once at [Setup Flow Music](/docs/start-here/setup-flowmusic). **How much does it cost?** Through useapi.net, a Lyria song costs about 0.8¢ on Flow Music Member billed yearly ($48 a month for 30,000 credits, about 6,000 songs), against 8¢ a song on Google's [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) (as of October 2026). You pay nothing per song on top of the Flow Music subscription, and Google AI Plus, Pro and Ultra include the Starter, Plus and Member plans. See [Pricing](#pricing) for the monthly plans. **Is this a Suno or Udio alternative?** Through useapi.net, yes. Like Suno and Udio, the Flow Music API generates full songs with vocals from a single text prompt, but it runs on Google DeepMind's Lyria models and adds cover, remix, extend and stem-splitting over REST. It also sings your own `[Verse]`/`[Chorus]` lyrics word for word, or makes an instrumental when you set `instrumental: true`. **Do I need a Google Cloud project or API key?** Through useapi.net, no. You call the API with a useapi.net [API token](/docs/start-here/setup-useapi) and connect the Google account you use at flowmusic.app once during [setup](/docs/start-here/setup-flowmusic). Google's own Lyria API runs through the [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) instead, which needs a Google Cloud project and an API key. Each useapi.net [subscription](/docs/subscription) connects 3 Flow Music accounts, up to 100 in total. **Can I cover, extend, or split a song into stems?** Through useapi.net, yes. The [music/edit](/docs/api-flowmusic-v1/post-flowmusic-music-edit) endpoint takes any generated clip and runs `cover`, `remix`, `extend` (up to 300 seconds), `replace`, `effect`, or `stems`, which splits it into drums, bass, vocals and other. Each edit spends credits from the same Flow Music subscription. See [Custom lyrics, instrumentals, and editing](#custom-lyrics-instrumentals-and-editing-a-song) above. ### Conclusion Visit our <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> or <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> for any support questions and concerns. The full runnable example is in the [`flowmusic-api` GitHub repo](https://github.com/useapi/flowmusic-api). The same calls are available as tools on the hosted [Flow Music MCP server](/docs/api-flowmusic-v1/mcp) for Claude Code, Cursor and VS Code. === URL: https://useapi.net/docs/articles/gemini-notebook-api-zh === Document URL: https://useapi.net/docs/articles/gemini-notebook-api-zh --- layout: default title: 如何用 Gemini Notebook API(NotebookLM API)把网页、PDF 和 YouTube 视频变成中文播客(中文教程) description: "Gemini Notebook API(NotebookLM API)中文教程:用 useapi.net 的 Gemini Notebook API 一次 curl 调用把网页或 YouTube 视频生成中文 Audio Overview 播客,免费 Google 账号可用,每月固定 15 美元。" keywords: [NotebookLM API, NotebookLM 播客, NotebookLM 中文播客, Audio Overview API, NotebookLM Audio Overview, Gemini Notebook API, NotebookLM 自动化, NotebookLM API Key, NotebookLM Python, NotebookLM 视频概览, AI 播客生成 API, 中文教程, Chinese tutorial, tutorial, code] image: https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-infographic-sketch-note-apollo11-0929.png parent: Articles nav_exclude: true lang: zh-CN date: 2026-10-04 last_modified: 2026-10-18 nav_order: 895 repo: https://github.com/useapi/notebooklm-api translation_key: gemini-notebook --- ## 如何用 Gemini Notebook API(NotebookLM API)把网页、PDF 和 YouTube 视频变成中文播客(中文教程) <div class="lang-banner" lang="en"> <strong>Chinese-language tutorial.</strong> This page is written in Simplified Chinese for Chinese-speaking developers. The same material in English: <a href="/docs/articles/gemini-notebook-bash">How to automate Gemini Notebook (NotebookLM) with the API</a> · <a href="/docs/api-gemini-notebook-v1">Gemini Notebook API docs</a> </div> 6 分钟阅读 • 2026 年 10 月 4 日(2026 年 10 月 18 日更新) ## 目录 ### 简介 用 [useapi.net](/docs/api-gemini-notebook-v1) 的 Gemini Notebook API(NotebookLM API),一次 REST 调用就能把网页或 YouTube 视频交给你自己的 Google 账号,生成 Gemini Notebook 的 Audio Overview 播客,并下载 `.m4a` 文件,播客语言可以指定为中文。 不需要 Google Cloud 项目,也不需要 Gemini API Key,免费 Google 账号即可使用。 Google 已把 NotebookLM 更名为 [Gemini Notebook](https://notebook.google.com),功能不变。普通 Google 账号没有官方 API。网页版能做的事,这个 API 都能用代码完成:建笔记本、加来源、带引用的问答、Deep Research,以及 Studio 里的全部生成功能。 本文由 useapi.net 维护者撰写,介绍的是我们自己的托管 API,示例代码开源在 [GitHub](https://github.com/useapi/notebooklm-api)。 ### Gemini Notebook API 能生成什么:播客、视频概览、幻灯片、信息图 [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts) 用 `type` 参数选择要生成的内容: | 生成内容 | `type` | 返回 | |---|---|---| | Audio Overview(双人播客) | `audio`,`format` 可选 `deep_dive`(默认)、`brief`、`critique`、`debate` | `m4a` 音频 | | Video Overview(视频概览) | `video`,`format` 可选 `explainer`(默认)、`brief`、`cinematic`、`short` | `mp4` 视频 | | 幻灯片 | `slides` | `pdf` 和 `pptx` | | 信息图 | `infographic` | `png` 图片 | | 报告、交互式报告、数据表 | `report`、`interactive_report`、`table` | Markdown 文本或表格行 | | 测验、闪卡、思维导图 | `quiz`、`flashcards`、`mindmap` | JSON | 音频、视频(`cinematic` 除外)、报告、交互式报告、数据表、幻灯片和信息图都可以用 `language` 指定输出语言,简体中文是 `zh_Hans`。 ### Gemini Notebook API(NotebookLM API)价格 向 useapi.net 支付每月固定 [15 美元](/docs/subscription),同一订阅包含 useapi.net 的所有 API,不只是 Gemini Notebook。每个订阅可以绑定 3 个 Google 账号,总数最多 100 个。生成在你自己的 Google 账号上进行,我们不按次、不按音频收费,Google 一侧的用量包含在账号现有的套餐里,免费套餐也可以。 | | useapi.net Gemini Notebook API | Google [Gemini Notebook Enterprise API](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks) | |---|:-:|:-:| | 账号 | 你自己的 Google 账号,免费或付费套餐均可 | Google Cloud 项目中的 Enterprise 许可证 | | 价格 | 每月固定 15 美元 | 按用户购买 Enterprise 许可证 | | 带引用的问答 | Yes | No | | Deep Research | Yes | No | | Audio Overview | Yes | Yes | | 视频概览、幻灯片、信息图、报告、测验、闪卡、思维导图 | Yes | No | | 状态 | 实验性 | 预览版(Pre-GA) | Google 按账号设定用量预算,每 5 小时刷新一次,另有每周预算。按 Google 自己的估算,满额的 5 小时窗口至少可以启动 2 个(免费套餐)、9 个(Google AI Pro)或 181 个(Google AI Ultra)Audio Overview,实际完成后通常比估算更省。需要更多产量时,多绑定几个账号即可,详见[规模化](#scale)。 ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. ### 准备工作 1. 注册 useapi.net 并获取 [API Token](/docs/start-here/setup-useapi),下面的示例都假设它保存在环境变量 `USEAPI_TOKEN` 里。 2. 用[自动化浏览器流程](/docs/start-here/setup-gemini-notebook)绑定 Google 账号:输入 Token,在远程浏览器里登录 Google 即可,不需要手动复制 Cookie。建议使用[专用的 Gmail 账号](/docs/start-here/setup-gemini-notebook#use-a-dedicated-gmail-account),不要用个人主账号。 下面的一次性请求和新建笔记本都可以省略 `email`:只绑定一个账号时自动使用它,绑定多个账号时,API 会挑选空闲的账号。基于笔记本的调用总是在该笔记本所属的账号上运行。 ### 如何用一次 API 调用生成 Gemini Notebook 中文播客 不用先建笔记本。把 `urls`(或粘贴的 `text`)直接发给 [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts#one-shot-requests),API 会在你的某个账号上新建笔记本、添加来源、等来源处理完,然后开始生成。`youtube.com` 和 `youtu.be` 链接会作为 YouTube 来源添加,一次最多 50 个链接。 ```bash JOBID=$(curl -s -X POST "https://api.useapi.net/v1/gemini-notebook/artifacts" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "type": "audio", "format": "brief", "length": "short", "language": "zh_Hans", "urls": ["https://zh.wikipedia.org/wiki/阿波罗11号"], "title": "阿波罗11号播客", "mode": "async" }' | jq -r '.jobid') ``` `mode: "async"` 会立即返回 `201` 和 `jobid`。默认的 `mode: "sync"` 最多等待 90 秒,播客通常需要几分钟,所以会先返回 `202`,之后一样要轮询。 ### 轮询任务并下载 查询 [GET /jobs/`jobid`](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid),直到 `status` 变为 `completed` 或 `failed`。`jobid` 里含有 `:` 和 `@`,放进 URL 路径前要先编码。完成后的 `result.files[].url` 指向 [GET /artifacts/download](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts-download),下载时同样要带上 API Token。下面这个函数后面还会再用: ```bash API=https://api.useapi.net/v1/gemini-notebook enc() { jq -rn --arg v "$1" '$v|@uri'; } wait_job() { [ -z "$1" ] || [ "$1" = "null" ] && { echo "提交失败,请查看响应中的 error"; return 1; } until curl -s "$API/jobs/$(enc "$1")" -H "Authorization: Bearer $USEAPI_TOKEN" > job.json && jq -e '.status == "completed" or .status == "failed"' job.json > /dev/null; do sleep 15 done jq '{status, title: .result.title, duration: .result.duration, error}' job.json jq -r '.result.files[]?.url' job.json | while read -r url; do curl -s -OJ -H "Authorization: Bearer $USEAPI_TOKEN" "$url" done } wait_job "$JOBID" ``` 我们在 2026 年 10 月 4 日运行了上面的请求:约 6 分钟后任务完成,Google 生成了一段 99 秒的中文播客,标题为「阿波罗登月惊魂」,`-OJ` 按这个标题把文件保存为 `阿波罗登月惊魂.m4a`。 - 失败的任务带有 `error.code`,例如 `quota`(用量不足)、`sources`(来源都无法使用)或 `generation_failed`。 - 不想轮询,可以在请求里传 `replyUrl`,任务结束时会收到一次 `POST`,内容就是完整的任务记录。 - 生成的文件留在笔记本里,下载链接只要笔记本和生成结果还在就一直有效。 ### 完整流程:笔记本、来源与生成 想对同一组来源生成多种内容,或者上传本地文件,就先建一个笔记本。来源可以是网页、YouTube 视频、粘贴的文本、Google Drive 文件,以及上传的 PDF、Word、PowerPoint、EPUB、音频、视频等文件。 ```bash # 1. 新建笔记本 NOTEBOOK=$(curl -s -X POST "$API/notebooks" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{"title": "阿波罗11号"}' | jq -r '.notebook') # 2. 添加网页和 YouTube 视频 curl -s -X POST "$API/sources" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d "$(jq -n --arg nb "$NOTEBOOK" '{ notebook: $nb, urls: ["https://zh.wikipedia.org/wiki/阿波罗11号", "https://www.youtube.com/watch?v=xUcYQ7slmRw"] }')" # 3. 上传 PDF,文件本身就是请求体 curl -s -X POST "$API/sources/upload?notebook=$(enc "$NOTEBOOK")&name=report.pdf" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/pdf" \ --data-binary @report.pdf # 4. 等所有来源处理完 until curl -s "$API/notebooks/$(enc "$NOTEBOOK")" -H "Authorization: Bearer $USEAPI_TOKEN" > notebook.json && jq -e '[.sources[].status] | all(. == "ready" or . == "error")' notebook.json > /dev/null; do sleep 10 done # 5. 生成中文信息图 JOBID=$(curl -s -X POST "$API/artifacts" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d "$(jq -n --arg nb "$NOTEBOOK" '{notebook: $nb, type: "infographic", orientation: "portrait", language: "zh_Hans", mode: "async"}')" \ | jq -r '.jobid') wait_job "$JOBID" ``` 实测中,三个来源约 30 秒全部就绪,竖版中文信息图约 2 分钟生成,得到一张 1536 × 2752 的 `png`,标题「阿波罗11号登月信息图」。把第 5 步的 `type` 换成 `audio`、`video` 或 `slides`,就能在同一个笔记本上继续生成播客、视频概览或幻灯片。完整的 19 步演示(包括问答、Deep Research 和修改单页幻灯片)见[英文教程](/docs/articles/gemini-notebook-bash)。 ### Python 示例 与上面的一次性请求基本相同(未指定 `length`,使用默认长度),用 Python 和 `requests` 写: ```python import os, time, requests from urllib.parse import quote API = 'https://api.useapi.net/v1/gemini-notebook' H = {'Authorization': f"Bearer {os.environ['USEAPI_TOKEN']}"} r = requests.post(f'{API}/artifacts', headers=H, json={ 'type': 'audio', 'format': 'brief', 'language': 'zh_Hans', 'urls': ['https://zh.wikipedia.org/wiki/阿波罗11号'], 'mode': 'async', }) r.raise_for_status() job = r.json() while job['status'] in ('pending', 'processing'): time.sleep(15) r = requests.get(f"{API}/jobs/{quote(job['jobid'], safe='')}", headers=H) r.raise_for_status() job = r.json() if job['status'] == 'failed': raise SystemExit(job['error']) print(job['result']['title'], job['result']['duration'], '秒') for f in job['result']['files']: with open(f"podcast.{f['format']}", 'wb') as out: out.write(requests.get(f['url'], headers=H).content) ``` 这段脚本实测约 6 分半钟跑完,得到一段 70 秒的中文播客 `podcast.m4a`。批量处理链接列表的 Node.js 和 Python 脚本见 [GitHub 示例仓库](https://github.com/useapi/notebooklm-api)的 `podcast/` 目录。 ### 规模化:多账号与限流 这个 API 可以无人值守地运行: - 绑定多个 Google 账号后,每个新任务会分配给状态正常、有空闲任务槽、且该类型用量还够的账号,不需要自己盯着 5 小时和每周的预算。 - 每个账号同时最多运行 `maxJobs` 个任务(默认 3,可设 1–10,用 [POST /accounts](/docs/api-gemini-notebook-v1/post-gemini-notebook-accounts) 修改)。[GET /jobs](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs) 显示每个账号上正在运行的任务。 - 所有账号都忙或用量不足时,调用返回 `429`。如果 Google 给出了重置时间,响应里会带 `retryAt`,你的代码可以等到那个时间再试,或者用 `email` 把下一批发到别的账号,或者降低频率。 - [GET /accounts/`email`](/docs/api-gemini-notebook-v1/get-gemini-notebook-accounts-email) 返回账号的实时用量、两个窗口的重置时间,以及每种生成的当前估算。 ### Gemini Notebook(NotebookLM)自动化:n8n、Colab 和 AI 编程助手 - [n8n 模板](/docs/articles/notebooklm-n8n-podcast):把网页、YouTube 视频或博客的 RSS 订阅变成 Gemini Notebook 播客,导入即可使用。 - [Google Colab 笔记本](https://colab.research.google.com/github/useapi/notebooklm-api/blob/main/notebooks/notebooklm_podcast.ipynb):在浏览器里填入 Token 和链接,直接播放并下载播客。 - Claude Code、Codex 等 AI 编程助手可以安装仓库里的 `notebooklm-podcast` 技能,用一句话生成播客:`npx skills add useapi/notebooklm-api --skill notebooklm-podcast`。 以上都在 [useapi/notebooklm-api](https://github.com/useapi/notebooklm-api) 仓库中。 ### 生成效果示例 以下是通过同一个 Gemini Notebook API 生成的真实结果,来源是 Apollo 11 的英文维基百科页面、一段 NASA 的 YouTube 视频、一段粘贴文本和一个 PDF,取自[英文教程](/docs/articles/gemini-notebook-bash#results),所以内容是英文的。 Audio Overview,`brief` 格式,`short` 长度,时长 1 分 31 秒,生成用时 4 分 36 秒: <audio controls class="audio-player" style="width:100%"><source src="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-audio-overview-brief-apollo11-0929.m4a" type="audio/mp4"></audio> Video Overview,`explainer` 格式,`whiteboard` 风格,完整时长 11 分 50 秒,这里是前 90 秒: <video poster="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-video-explainer-whiteboard-apollo11-first90s-0929-poster.jpg" controls width="100%" style="max-width:640px;border-radius:8px" src="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-video-explainer-whiteboard-apollo11-first90s-0929.mp4"></video> 信息图,竖版,`sketch_note` 风格,1536 × 2752,生成用时 1 分 45 秒: <a href="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-infographic-sketch-note-apollo11-0929.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-infographic-sketch-note-apollo11-0929.png" alt="Gemini Notebook API 生成的 Apollo 11 信息图" style="width:100%;max-width:360px;border-radius:8px"></a> ### 常见问题 - **Gemini Notebook(NotebookLM)有官方 API 吗?** 普通账号可以用 useapi.net:useapi.net 的 Gemini Notebook API 是第三方 REST API,驱动你自己的 Google 账号,免费和付费的个人套餐都能用,覆盖网页版的全部功能。Google 只为 Gemini Notebook Enterprise 提供 API,需要在 Google Cloud 项目中购买 Enterprise 许可证,功能限于管理笔记本、添加来源和生成 Audio Overview,普通 Google 账号用不了。对比见[价格](#pricing)。 - **需要 Gemini API Key 或 Gemini Notebook(NotebookLM)API Key 吗?** 不需要。你用 useapi.net 的 [API Token](/docs/start-here/setup-useapi) 调用接口,再通过[自动化流程](/docs/start-here/setup-gemini-notebook)绑定一次 Google 账号即可,不需要 Google Cloud 项目。Google 不为普通账号发放 Gemini Notebook API Key。 - **支持中文播客吗?** 支持。在 [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts) 里传 `language: "zh_Hans"`,见[上文](#quick-start)的实测。`language` 适用于音频、视频(`cinematic` 除外)、报告、交互式报告、数据表、信息图和幻灯片,默认是 `en`。也可以用 [POST /accounts](/docs/api-gemini-notebook-v1/post-gemini-notebook-accounts) 的 `outputLanguage` 为整个账号设置 Studio 输出语言。 - **有免费的 Gemini Notebook(NotebookLM)API 吗?** useapi.net 的 Gemini Notebook API 在免费 Google 账号上就能用,Google 一侧不收费,而 Google 没有面向普通账号的 API。useapi.net 订阅每月 15 美元,用 Stripe 付款时,首次购买 14 天内且成功生成少于 50 次可全额退款,见[退款政策](/docs/legal#refund-policy)。 - **免费 Google 账号能用吗?** 能。免费套餐每个 5 小时窗口的用量较少,付费的 Google AI 套餐提高用量上限,Cinematic 视频需要付费套餐。 - **一个播客要生成多久?** Audio Overview 通常 3–6 分钟,Video Overview 10 分钟以上,信息图和报告一两分钟,测验约一分半,闪卡和数据表不到一分钟。 - **NotebookLM 和 Gemini Notebook 是同一个产品吗?** 是。Gemini Notebook 是 NotebookLM 自 2026 年 7 月起的新名字,本文的 API 就是 NotebookLM API。 更多问答见 [Gemini Notebook API 常见问题(英文)](/docs/api-gemini-notebook-v1#questions)。 ### 结语 有问题欢迎加入我们的 <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord 服务器</a> 或 <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram 频道</a>。 全部接口见 [Gemini Notebook API 文档](/docs/api-gemini-notebook-v1),示例代码见 [GitHub 仓库](https://github.com/useapi/notebooklm-api)。 === URL: https://useapi.net/docs/articles/gemini-notebook-bash-es === Document URL: https://useapi.net/docs/articles/gemini-notebook-bash-es --- layout: default title: "Cómo usar la Gemini Notebook API (NotebookLM API) para convertir páginas web, PDF y videos de YouTube en podcasts en español" seo_title: "Gemini Notebook API (NotebookLM API): podcast en español con curl" description: "Genera podcasts Audio Overview en español a partir de páginas web o videos de YouTube con un curl, mediante la Gemini Notebook API (NotebookLM API) de useapi.net. Funciona con una cuenta de Google gratuita." keywords: [Gemini Notebook API, NotebookLM API, API de NotebookLM, NotebookLM API en español, NotebookLM podcast, podcast NotebookLM en español, Audio Overview API, NotebookLM Audio Overview, automatización NotebookLM, NotebookLM API Key, clave de API de NotebookLM, NotebookLM Python, NotebookLM Video Overview, API para generar podcasts con IA, Gemini Notebook en español, tutorial NotebookLM API, tutorial, código] image: https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-infographic-sketch-note-apollo11-0929.png parent: Articles nav_exclude: true lang: es date: 2026-10-04 last_modified: 2026-10-18 nav_order: 895 repo: https://github.com/useapi/notebooklm-api translation_key: gemini-notebook --- ## Cómo usar la Gemini Notebook API (NotebookLM API) para convertir páginas web, PDF y videos de YouTube en podcasts en español {: .no_toc #how-to-automate-gemini-notebook-notebooklm-with-the-api-deep-research-chat-audio-overviews-and-a-lot-more } 6 min de lectura • 4 de octubre de 2026 (18 de octubre de 2026) useapi.net es una API de terceros. No está afiliada a Google ni cuenta con su respaldo. ## Índice {: .no_toc .text-delta #table-of-contents } ### Introducción Con la Gemini Notebook API (NotebookLM API) de [useapi.net](/docs/api-gemini-notebook-v1), una sola llamada REST entrega una página web o un video de YouTube a tu propia cuenta de Google y devuelve un podcast Audio Overview de Gemini Notebook como archivo `.m4a`, y puedes pedir el podcast en español. No necesitas un proyecto de Google Cloud ni una clave de la Gemini API, y una cuenta de Google gratuita funciona. Google cambió el nombre de NotebookLM a [Gemini Notebook](https://notebook.google.com), y las funciones siguen siendo las mismas. Las cuentas de Google normales no tienen API oficial. Todo lo que hace el sitio web, esta API lo hace por código: crear notebooks, agregar fuentes, chat con citas, Deep Research y todas las generaciones de Studio. Este artículo lo escribieron los responsables de useapi.net y trata sobre nuestra propia API alojada. El código de ejemplo es abierto y está en [GitHub](https://github.com/useapi/notebooklm-api). ### Lo que genera la Gemini Notebook API: podcasts, Video Overviews, diapositivas, infografías [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts) elige qué generar con el parámetro `type`: | Qué genera | `type` | Devuelve | |---|---|---| | Audio Overview (podcast a dos voces) | `audio`, `format` puede ser `deep_dive` (por defecto), `brief`, `critique`, `debate` | audio `m4a` | | Video Overview | `video`, `format` puede ser `explainer` (por defecto), `brief`, `cinematic`, `short` | video `mp4` | | Presentación de diapositivas | `slides` | `pdf` y `pptx` | | Infografía | `infographic` | imagen `png` | | Informe, informe interactivo, tabla de datos | `report`, `interactive_report`, `table` | texto en Markdown o filas de tabla | | Cuestionario, tarjetas de estudio, mapa mental | `quiz`, `flashcards`, `mindmap` | JSON | Audio, video (excepto `cinematic`), informe, informe interactivo, tabla de datos, diapositivas e infografía aceptan `language` para definir el idioma de salida. El español es `es`. ### Precio de la Gemini Notebook API (NotebookLM API) Pagas a useapi.net una tarifa fija de [US$15 al mes](/docs/subscription), y la misma suscripción incluye todas las API de useapi.net, no solo Gemini Notebook. Cada suscripción conecta 3 cuentas de Google, hasta 100 en total. La generación se ejecuta en tu propia cuenta de Google, no cobramos por llamada ni por podcast, y el uso del lado de Google está incluido en el plan que la cuenta ya tiene, incluso el gratuito. La Gemini Notebook API de useapi.net frente a la API Enterprise del propio Google (precios en dólares estadounidenses): | | Gemini Notebook API de useapi.net | [Gemini Notebook Enterprise API](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks) de Google | |---|:-:|:-:| | Cuenta | Tu propia cuenta de Google, plan gratuito o de pago | Licencias Enterprise en un proyecto de Google Cloud | | Precio | $15 fijos al mes | Licencias Enterprise compradas por usuario | | Chat con citas | Yes | No | | Deep Research | Yes | No | | Audio Overview | Yes | Yes | | Video Overviews, diapositivas, infografías, informes, cuestionarios, tarjetas, mapas mentales | Yes | No | | Estado | Experimental | Preview (Pre-GA) | Google fija un presupuesto de uso por cuenta, que se renueva cada 5 horas, además de un presupuesto semanal. Según las estimaciones del propio Google, una ventana completa de 5 horas inicia al menos 2 (plan gratuito), 9 (Google AI Pro) o 181 (Google AI Ultra) Audio Overviews, y en la práctica, una vez terminados, suelen gastar menos de lo estimado. Para producir más, conecta más cuentas, consulta [Escala](#scale). ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. ### Preparación 1. Regístrate en useapi.net y obtén tu [token de API](/docs/start-here/setup-useapi). Todos los ejemplos de abajo suponen que está en la variable de entorno `USEAPI_TOKEN`. 2. Conecta la cuenta de Google con el [flujo automatizado en el navegador](/docs/start-here/setup-gemini-notebook): ingresa el token e inicia sesión en Google en un navegador remoto, sin copiar cookies a mano. Recomendamos usar una [cuenta de Gmail dedicada](/docs/start-here/setup-gemini-notebook#use-a-dedicated-gmail-account), no tu cuenta personal principal. Las solicitudes de una sola llamada y la creación de notebooks de abajo pueden omitir el `email`: con una sola cuenta conectada, la API usa esa cuenta, y con varias, elige una que esté libre. Las llamadas sobre un notebook siempre se ejecutan en la cuenta dueña de ese notebook. ### Cómo generar un podcast de Gemini Notebook en español con una sola llamada a la API No necesitas crear un notebook antes. Envía `urls` (o un `text` pegado) directamente a [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts#one-shot-requests), y la API crea un notebook en una de tus cuentas, agrega las fuentes, espera a que se procesen y empieza a generar. Los enlaces de `youtube.com` y `youtu.be` entran como fuentes de YouTube, hasta 50 enlaces a la vez. ```bash JOBID=$(curl -s -X POST "https://api.useapi.net/v1/gemini-notebook/artifacts" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "type": "audio", "format": "brief", "length": "short", "language": "es", "urls": ["https://es.wikipedia.org/wiki/Apolo_11"], "title": "Podcast del Apolo 11", "mode": "async" }' | jq -r '.jobid') ``` `mode: "async"` devuelve `201` y el `jobid` de inmediato. El valor por defecto, `mode: "sync"`, espera hasta 90 segundos, pero un podcast suele tardar unos minutos, así que primero devuelve `202` y consultas de la misma forma. ### Consulta el job y descarga Consulta [GET /jobs/`jobid`](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid) hasta que `status` pase a `completed` o `failed`. El `jobid` contiene `:` y `@`, así que codifícalo antes de ponerlo en una ruta de URL. En el job terminado, `result.files[].url` apunta a [GET /artifacts/download](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts-download), y la descarga también lleva el token de API. Esta función se vuelve a usar más adelante: ```bash API=https://api.useapi.net/v1/gemini-notebook enc() { jq -rn --arg v "$1" '$v|@uri'; } wait_job() { [ -z "$1" ] || [ "$1" = "null" ] && { echo "Falló el envío, revisa el error en la respuesta"; return 1; } until curl -s "$API/jobs/$(enc "$1")" -H "Authorization: Bearer $USEAPI_TOKEN" > job.json && jq -e '.status == "completed" or .status == "failed"' job.json > /dev/null; do sleep 15 done jq '{status, title: .result.title, duration: .result.duration, error}' job.json jq -r '.result.files[]?.url' job.json | while read -r url; do curl -s -OJ -H "Authorization: Bearer $USEAPI_TOKEN" "$url" done } wait_job "$JOBID" ``` Ejecutamos esta misma solicitud el 4 de octubre de 2026, en chino (`zh_Hans`) y con la página de Wikipedia en chino: el job terminó en unos 6 minutos, Google generó un podcast de 99 segundos, y `-OJ` guardó el `.m4a` con el título que le dio Google. - Un job fallido trae `error.code`, por ejemplo `quota` (uso insuficiente), `sources` (no se pudo usar ninguna fuente) o `generation_failed`. - Para no consultar, pasa `replyUrl` en la solicitud: cuando el job termine, recibes un único `POST` con el registro completo del job. - Los archivos generados se quedan en el notebook, y los enlaces de descarga siguen funcionando mientras existan el notebook y el resultado. ### El flujo completo: notebook, fuentes y generación Para generar varios tipos de contenido a partir de las mismas fuentes, o para subir archivos locales, crea un notebook antes. Las fuentes pueden ser páginas web, videos de YouTube, texto pegado, archivos de Google Drive y archivos subidos, como PDF, Word, PowerPoint, EPUB, audio y video. ```bash # 1. Crea el notebook NOTEBOOK=$(curl -s -X POST "$API/notebooks" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{"title": "Apolo 11"}' | jq -r '.notebook') # 2. Agrega una página web y un video de YouTube curl -s -X POST "$API/sources" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d "$(jq -n --arg nb "$NOTEBOOK" '{ notebook: $nb, urls: ["https://es.wikipedia.org/wiki/Apolo_11", "https://www.youtube.com/watch?v=xUcYQ7slmRw"] }')" # 3. Sube un PDF: el propio archivo es el cuerpo de la solicitud curl -s -X POST "$API/sources/upload?notebook=$(enc "$NOTEBOOK")&name=report.pdf" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/pdf" \ --data-binary @report.pdf # 4. Espera a que todas las fuentes estén listas until curl -s "$API/notebooks/$(enc "$NOTEBOOK")" -H "Authorization: Bearer $USEAPI_TOKEN" > notebook.json && jq -e '[.sources[].status] | all(. == "ready" or . == "error")' notebook.json > /dev/null; do sleep 10 done # 5. Genera una infografía en español JOBID=$(curl -s -X POST "$API/artifacts" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d "$(jq -n --arg nb "$NOTEBOOK" '{notebook: $nb, type: "infographic", orientation: "portrait", language: "es", mode: "async"}')" \ | jq -r '.jobid') wait_job "$JOBID" ``` En nuestra prueba (con salida en chino), las tres fuentes estuvieron listas en unos 30 segundos, y la infografía vertical tardó unos 2 minutos, un `png` de 1536 × 2752. Cambia el `type` del paso 5 a `audio`, `video` o `slides` para generar un podcast, un Video Overview o diapositivas en el mismo notebook. La demostración completa en 19 pasos (con chat, Deep Research y la revisión de una diapositiva) está en el [artículo en inglés](/docs/articles/gemini-notebook-bash). ### Ejemplo en Python Casi la misma solicitud de una sola llamada (sin `length`, así que con la duración por defecto), en Python con `requests`: ```python import os, time, requests from urllib.parse import quote API = 'https://api.useapi.net/v1/gemini-notebook' H = {'Authorization': f"Bearer {os.environ['USEAPI_TOKEN']}"} r = requests.post(f'{API}/artifacts', headers=H, json={ 'type': 'audio', 'format': 'brief', 'language': 'es', 'urls': ['https://es.wikipedia.org/wiki/Apolo_11'], 'mode': 'async', }) r.raise_for_status() job = r.json() while job['status'] in ('pending', 'processing'): time.sleep(15) r = requests.get(f"{API}/jobs/{quote(job['jobid'], safe='')}", headers=H) r.raise_for_status() job = r.json() if job['status'] == 'failed': raise SystemExit(job['error']) print(job['result']['title'], job['result']['duration'], 's') for f in job['result']['files']: with open(f"podcast.{f['format']}", 'wb') as out: out.write(requests.get(f['url'], headers=H).content) ``` Cuando ejecutamos este script en chino, tardó unos 6 minutos y medio y generó un `podcast.m4a` de 70 segundos. Los scripts en Node.js y Python que procesan una lista de enlaces están en la carpeta `podcast/` del [repositorio de ejemplos en GitHub](https://github.com/useapi/notebooklm-api). ### Escala: varias cuentas y límites de tasa Esta API puede funcionar sin que nadie la vigile: - Con varias cuentas de Google conectadas, cada job nuevo va a una cuenta sana, con un espacio de job libre y uso suficiente para ese tipo, sin que tengas que seguir los presupuestos de 5 horas y semanal. - Cada cuenta ejecuta hasta `maxJobs` jobs a la vez (por defecto 3, de 1 a 10, cámbialo con [POST /accounts](/docs/api-gemini-notebook-v1/post-gemini-notebook-accounts)). [GET /jobs](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs) muestra los jobs en ejecución en cada cuenta. - Cuando todas las cuentas están ocupadas o sin uso suficiente, la llamada devuelve `429`. Si Google informó una hora de renovación, la respuesta trae `retryAt`, y tu código puede esperar hasta entonces, enviar el siguiente lote a otra cuenta con `email` o bajar el ritmo. - [GET /accounts/`email`](/docs/api-gemini-notebook-v1/get-gemini-notebook-accounts-email) devuelve el uso de la cuenta en vivo, las horas de renovación de las dos ventanas y la estimación actual para cada tipo de generación. ### Automatización de Gemini Notebook (NotebookLM): n8n, Colab y asistentes de código con IA - [Plantilla de n8n](/docs/articles/notebooklm-n8n-podcast) (en inglés): convierte páginas web, videos de YouTube o el feed RSS de un blog en podcasts de Gemini Notebook, solo hay que importarla. - [Notebook de Google Colab](https://colab.research.google.com/github/useapi/notebooklm-api/blob/main/notebooks/notebooklm_podcast.ipynb): ingresa el token y los enlaces en el navegador, y escucha y descarga el podcast ahí mismo. - Los asistentes de código con IA, como Claude Code y Codex, pueden instalar la skill `notebooklm-podcast` del repositorio y generar un podcast con una frase: `npx skills add useapi/notebooklm-api --skill notebooklm-podcast`. Todo esto está en el repositorio [useapi/notebooklm-api](https://github.com/useapi/notebooklm-api). ### Ejemplos de resultados Abajo, resultados reales de la misma Gemini Notebook API. Las fuentes son la página de Wikipedia en inglés sobre el Apolo 11, un video de la NASA en YouTube, un texto pegado y un PDF, tomados del [artículo en inglés](/docs/articles/gemini-notebook-bash#results), por eso el contenido está en inglés. Audio Overview, formato `brief`, duración `short`, 1 min 31 s de audio, generado en 4 min 36 s: <audio controls class="audio-player" style="width:100%"><source src="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-audio-overview-brief-apollo11-0929.m4a" type="audio/mp4"></audio> Video Overview, formato `explainer`, estilo `whiteboard`, 11 min 50 s en total, aquí los primeros 90 segundos: <video poster="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-video-explainer-whiteboard-apollo11-first90s-0929-poster.jpg" controls width="100%" style="max-width:640px;border-radius:8px" src="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-video-explainer-whiteboard-apollo11-first90s-0929.mp4"></video> Infografía vertical, estilo `sketch_note`, 1536 × 2752, generada en 1 min 45 s: <a href="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-infographic-sketch-note-apollo11-0929.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-infographic-sketch-note-apollo11-0929.png" alt="Infografía del Apolo 11 generada con la Gemini Notebook API" style="width:100%;max-width:360px;border-radius:8px"></a> ### Preguntas frecuentes - **¿NotebookLM (Gemini Notebook) tiene API oficial?** Con useapi.net, las cuentas normales la tienen: la Gemini Notebook API de useapi.net es una API REST de terceros que se ejecuta en tu propia cuenta de Google, en planes personales gratuitos o de pago, y cubre todas las funciones del sitio web por US$15 fijos al mes (a octubre de 2026). Google solo ofrece API para Gemini Notebook Enterprise, que requiere licencias Enterprise en un proyecto de Google Cloud y se limita a gestionar notebooks, agregar fuentes y generar Audio Overviews, sin acceso para las cuentas de Google normales. La comparación está en [Precio](#pricing). - **¿Necesito una clave de la Gemini API o de la NotebookLM API?** Con useapi.net, no. Llamas a la API con el [token de API](/docs/start-here/setup-useapi) de useapi.net y conectas la cuenta de Google una sola vez con el [flujo automatizado](/docs/start-here/setup-gemini-notebook), en pocos minutos, sin proyecto de Google Cloud. Google no emite claves de la Gemini Notebook API para cuentas normales. - **¿Puedo generar un podcast en español?** Con useapi.net, sí. Pasa `language: "es"` en [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts), como en el [ejemplo de arriba](#quick-start). `language` vale para audio, video (excepto `cinematic`), informe, informe interactivo, tabla de datos, infografía y diapositivas, y el valor por defecto es `en`. También puedes definir el idioma de salida de Studio para toda la cuenta con `outputLanguage` en [POST /accounts](/docs/api-gemini-notebook-v1/post-gemini-notebook-accounts). - **¿Existe una Gemini Notebook (NotebookLM) API gratis?** Con useapi.net, la Gemini Notebook API funciona con cuentas de Google gratuitas, Google no cobra nada de su lado, y Google no tiene API para cuentas normales. La suscripción de useapi.net cuesta US$15 al mes (a octubre de 2026). Si pagas con Stripe, recibes un reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas, consulta la [política de reembolso](/docs/legal#refund-policy). - **¿Funciona con una cuenta de Google gratuita?** Con useapi.net, sí. El plan gratuito inicia unos 2 Audio Overviews por ventana de 5 horas (a octubre de 2026), los planes de pago de Google AI aumentan los límites, y los videos Cinematic requieren un plan de pago. - **¿Cuánto tarda en generarse un podcast?** Con useapi.net, un Audio Overview suele tardar de 3 a 6 minutos, un Video Overview 10 minutos o más, las infografías y los informes uno o dos minutos, un cuestionario cerca de un minuto y medio, y las tarjetas de estudio y las tablas de datos menos de un minuto. - **¿NotebookLM y Gemini Notebook son el mismo producto?** Sí. Gemini Notebook es el nombre nuevo de NotebookLM desde julio de 2026, y la API de este artículo es la NotebookLM API. Más preguntas y respuestas en las [preguntas frecuentes de la Gemini Notebook API (en inglés)](/docs/api-gemini-notebook-v1#questions). ### Conclusión Si tienes preguntas, escríbenos en nuestro <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> servidor de Discord</a> o en nuestro <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> canal de Telegram</a>. Todos los endpoints están en la [documentación de la Gemini Notebook API](/docs/api-gemini-notebook-v1), y el código de ejemplo en el [repositorio de GitHub](https://github.com/useapi/notebooklm-api). === URL: https://useapi.net/docs/articles/gemini-notebook-bash-id === Document URL: https://useapi.net/docs/articles/gemini-notebook-bash-id --- layout: default title: "Cara Memakai Gemini Notebook API (NotebookLM API): Ubah Web, PDF dan Video YouTube Menjadi Podcast Berbahasa Indonesia" seo_title: "Gemini Notebook API (NotebookLM API): Podcast Bahasa Indonesia dengan curl" description: "Pakai Gemini Notebook API (NotebookLM API) useapi.net: satu panggilan curl mengubah halaman web atau video YouTube menjadi podcast Audio Overview berbahasa Indonesia, bisa dengan akun Google gratis, US$15 per bulan." keywords: [Gemini Notebook API, NotebookLM API, API NotebookLM, NotebookLM API bahasa Indonesia, podcast NotebookLM, podcast NotebookLM bahasa Indonesia, Audio Overview API, NotebookLM Audio Overview, otomatisasi NotebookLM, NotebookLM automation, NotebookLM API Key, NotebookLM Python, NotebookLM Video Overview, API pembuat podcast AI, AI podcast API, Gemini Notebook bahasa Indonesia, tutorial NotebookLM API, tutorial bahasa Indonesia, tutorial, kode] image: https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-infographic-sketch-note-apollo11-0929.png parent: Articles nav_exclude: true lang: id translation_key: gemini-notebook date: 2026-10-04 last_modified: 2026-10-18 nav_order: 895 repo: https://github.com/useapi/notebooklm-api --- ## Cara Memakai Gemini Notebook API (NotebookLM API): Ubah Web, PDF dan Video YouTube Menjadi Podcast Berbahasa Indonesia {: .no_toc #how-to-automate-gemini-notebook-notebooklm-with-the-api-deep-research-chat-audio-overviews-and-a-lot-more } 6 menit baca • 4 Oktober 2026 (18 Oktober 2026) useapi.net adalah API pihak ketiga. Kami tidak berafiliasi dengan Google dan tidak disahkan oleh Google. ## Daftar isi {: .no_toc .text-delta #table-of-contents } ### Pendahuluan Dengan Gemini Notebook API (NotebookLM API) dari [useapi.net](/docs/api-gemini-notebook-v1), satu panggilan REST cukup untuk menyerahkan halaman web atau video YouTube ke akun Google Anda sendiri, membuat podcast Audio Overview di Gemini Notebook, lalu mengunduh file `.m4a`-nya. Bahasa podcast bisa diatur ke bahasa Indonesia. Anda tidak butuh project Google Cloud maupun Gemini API key, dan akun Google gratis pun bisa dipakai. Google telah mengganti nama NotebookLM menjadi [Gemini Notebook](https://notebook.google.com), dengan fitur yang sama. Akun Google biasa tidak punya API resmi. Semua yang bisa dilakukan di versi web bisa dikerjakan API ini lewat kode: membuat notebook, menambah sumber, tanya jawab dengan sitasi, Deep Research, dan semua fitur pembuatan di Studio. Artikel ini ditulis oleh pengelola useapi.net dan membahas API hosting milik kami sendiri. Contoh kodenya open source di [GitHub](https://github.com/useapi/notebooklm-api). ### Apa yang dibuat Gemini Notebook API: podcast, Video Overview, slide, infografis [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts) memilih konten yang dibuat lewat parameter `type`: | Yang dibuat | `type` | Hasil | |---|---|---| | Audio Overview (podcast dua orang) | `audio`, `format` bisa `deep_dive` (default), `brief`, `critique`, `debate` | audio `m4a` | | Video Overview | `video`, `format` bisa `explainer` (default), `brief`, `cinematic`, `short` | video `mp4` | | Slide | `slides` | `pdf` dan `pptx` | | Infografis | `infographic` | gambar `png` | | Laporan, laporan interaktif, tabel data | `report`, `interactive_report`, `table` | teks Markdown atau baris tabel | | Kuis, flashcard, mind map | `quiz`, `flashcards`, `mindmap` | JSON | Audio, video (kecuali `cinematic`), laporan, laporan interaktif, tabel data, slide dan infografis bisa diatur bahasa hasilnya dengan `language`. Bahasa Indonesia adalah `id`. ### Harga Gemini Notebook API (NotebookLM API) Anda membayar useapi.net [$15 per bulan](/docs/subscription), tetap, dan langganan yang sama mencakup semua API useapi.net, bukan hanya Gemini Notebook. Setiap langganan bisa menghubungkan 3 akun Google, maksimal 100 secara total. Pembuatan berjalan di akun Google Anda sendiri. Kami tidak menagih per panggilan atau per audio, dan pemakaian di sisi Google sudah termasuk dalam paket akun yang ada, paket gratis pun bisa. | | Gemini Notebook API useapi.net | [Gemini Notebook Enterprise API](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks) Google | |---|:-:|:-:| | Akun | Akun Google Anda sendiri, paket gratis atau berbayar | Lisensi Enterprise di project Google Cloud | | Harga | $15 per bulan, tetap | Lisensi Enterprise dibeli per pengguna | | Tanya jawab dengan sitasi | Yes | No | | Deep Research | Yes | No | | Audio Overview | Yes | Yes | | Video Overview, slide, infografis, laporan, kuis, flashcard, mind map | Yes | No | | Status | Eksperimental | Preview (Pre-GA) | Google menetapkan anggaran pemakaian per akun, yang terisi ulang setiap 5 jam, ditambah anggaran mingguan. Menurut perkiraan Google sendiri, satu jendela 5 jam penuh bisa memulai setidaknya 2 (paket gratis), 9 (Google AI Pro) atau 181 (Google AI Ultra) Audio Overview, dan pemakaian sebenarnya setelah selesai biasanya lebih hemat dari perkiraan. Jika butuh hasil lebih banyak, hubungkan lebih banyak akun. Lihat [skala besar](#scale). ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. ### Persiapan 1. Daftar di useapi.net dan ambil [API token](/docs/start-here/setup-useapi). Contoh di bawah menganggap token itu tersimpan di variabel lingkungan `USEAPI_TOKEN`. 2. Hubungkan akun Google lewat [alur browser otomatis](/docs/start-here/setup-gemini-notebook): masukkan token, lalu login ke Google di browser jarak jauh. Anda tidak perlu menyalin cookie secara manual. Sebaiknya pakai [akun Gmail khusus](/docs/start-here/setup-gemini-notebook#use-a-dedicated-gmail-account), bukan akun pribadi utama Anda. Request sekali jalan dan pembuatan notebook baru di bawah boleh tanpa `email`: jika hanya satu akun yang terhubung, akun itu dipakai otomatis, dan jika ada beberapa, API memilih akun yang sedang longgar. Panggilan berbasis notebook selalu berjalan di akun pemilik notebook itu. ### Cara membuat podcast Gemini Notebook berbahasa Indonesia dengan satu panggilan API Tidak perlu membuat notebook lebih dulu. Kirim `urls` (atau `text` yang ditempel) langsung ke [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts#one-shot-requests), dan API akan membuat notebook baru di salah satu akun Anda, menambahkan sumber, menunggu sumber selesai diproses, lalu mulai membuat podcast. Tautan `youtube.com` dan `youtu.be` ditambahkan sebagai sumber YouTube, hingga 50 tautan sekaligus. ```bash JOBID=$(curl -s -X POST "https://api.useapi.net/v1/gemini-notebook/artifacts" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "type": "audio", "format": "brief", "length": "short", "language": "id", "urls": ["https://id.wikipedia.org/wiki/Apollo_11"], "title": "Podcast Apollo 11", "mode": "async" }' | jq -r '.jobid') ``` `mode: "async"` langsung mengembalikan `201` dan `jobid`. `mode: "sync"` (default) menunggu paling lama 90 detik, sedangkan podcast biasanya butuh beberapa menit, jadi API lebih dulu mengembalikan `202` dan Anda tetap harus melakukan polling. ### Polling job dan unduh hasilnya Cek [GET /jobs/`jobid`](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid) sampai `status` menjadi `completed` atau `failed`. `jobid` berisi `:` dan `@`, jadi encode dulu sebelum dimasukkan ke path URL. Setelah selesai, `result.files[].url` mengarah ke [GET /artifacts/download](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts-download), dan unduhannya juga harus membawa API token. Fungsi di bawah akan dipakai lagi nanti: ```bash API=https://api.useapi.net/v1/gemini-notebook enc() { jq -rn --arg v "$1" '$v|@uri'; } wait_job() { [ -z "$1" ] || [ "$1" = "null" ] && { echo "Pengiriman gagal, lihat error di respons"; return 1; } until curl -s "$API/jobs/$(enc "$1")" -H "Authorization: Bearer $USEAPI_TOKEN" > job.json && jq -e '.status == "completed" or .status == "failed"' job.json > /dev/null; do sleep 15 done jq '{status, title: .result.title, duration: .result.duration, error}' job.json jq -r '.result.files[]?.url' job.json | while read -r url; do curl -s -OJ -H "Authorization: Bearer $USEAPI_TOKEN" "$url" done } wait_job "$JOBID" ``` Kami menjalankan request yang sama pada 4 Oktober 2026 dengan bahasa Mandarin (`zh_Hans`) dan halaman Wikipedia berbahasa Mandarin: job selesai dalam sekitar 6 menit, Google membuat podcast berdurasi 99 detik, dan `-OJ` menyimpan file `.m4a` dengan judul yang diberikan Google. - Job yang gagal membawa `error.code`, misalnya `quota` (kuota tidak cukup), `sources` (tidak ada sumber yang bisa dipakai) atau `generation_failed`. - Tidak mau polling? Kirim `replyUrl` di request, dan saat job selesai Anda menerima satu `POST` berisi record job lengkap. - File hasil tetap tersimpan di notebook, dan tautan unduhannya berlaku selama notebook dan hasilnya masih ada. ### Alur lengkap: notebook, sumber dan pembuatan Jika ingin membuat beberapa jenis konten dari sekumpulan sumber yang sama, atau meng-upload file lokal, buat notebook lebih dulu. Sumber bisa berupa halaman web, video YouTube, teks yang ditempel, file Google Drive, serta file upload seperti PDF, Word, PowerPoint, EPUB, audio dan video. ```bash # 1. Buat notebook baru NOTEBOOK=$(curl -s -X POST "$API/notebooks" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{"title": "Apollo 11"}' | jq -r '.notebook') # 2. Tambahkan halaman web dan video YouTube curl -s -X POST "$API/sources" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d "$(jq -n --arg nb "$NOTEBOOK" '{ notebook: $nb, urls: ["https://id.wikipedia.org/wiki/Apollo_11", "https://www.youtube.com/watch?v=xUcYQ7slmRw"] }')" # 3. Upload PDF, file itu sendiri menjadi body request curl -s -X POST "$API/sources/upload?notebook=$(enc "$NOTEBOOK")&name=report.pdf" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/pdf" \ --data-binary @report.pdf # 4. Tunggu sampai semua sumber selesai diproses until curl -s "$API/notebooks/$(enc "$NOTEBOOK")" -H "Authorization: Bearer $USEAPI_TOKEN" > notebook.json && jq -e '[.sources[].status] | all(. == "ready" or . == "error")' notebook.json > /dev/null; do sleep 10 done # 5. Buat infografis berbahasa Indonesia JOBID=$(curl -s -X POST "$API/artifacts" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d "$(jq -n --arg nb "$NOTEBOOK" '{notebook: $nb, type: "infographic", orientation: "portrait", language: "id", mode: "async"}')" \ | jq -r '.jobid') wait_job "$JOBID" ``` Dalam uji kami (dengan hasil berbahasa Mandarin), ketiga sumber siap dalam sekitar 30 detik, dan infografis vertikal dibuat dalam sekitar 2 menit, menghasilkan `png` berukuran 1536 × 2752. Ganti `type` di langkah 5 menjadi `audio`, `video` atau `slides` untuk terus membuat podcast, Video Overview atau slide di notebook yang sama. Demo lengkap 19 langkah (termasuk tanya jawab, Deep Research dan mengubah satu halaman slide) ada di [tutorial bahasa Inggris](/docs/articles/gemini-notebook-bash). ### Contoh Python Hampir sama dengan request sekali jalan di atas (tanpa `length`, jadi memakai durasi default), ditulis dengan Python dan `requests`: ```python import os, time, requests from urllib.parse import quote API = 'https://api.useapi.net/v1/gemini-notebook' H = {'Authorization': f"Bearer {os.environ['USEAPI_TOKEN']}"} r = requests.post(f'{API}/artifacts', headers=H, json={ 'type': 'audio', 'format': 'brief', 'language': 'id', 'urls': ['https://id.wikipedia.org/wiki/Apollo_11'], 'mode': 'async', }) r.raise_for_status() job = r.json() while job['status'] in ('pending', 'processing'): time.sleep(15) r = requests.get(f"{API}/jobs/{quote(job['jobid'], safe='')}", headers=H) r.raise_for_status() job = r.json() if job['status'] == 'failed': raise SystemExit(job['error']) print(job['result']['title'], job['result']['duration'], 'detik') for f in job['result']['files']: with open(f"podcast.{f['format']}", 'wb') as out: out.write(requests.get(f['url'], headers=H).content) ``` Saat kami menjalankan skrip ini dengan bahasa Mandarin, skrip selesai dalam sekitar 6 setengah menit dan menghasilkan podcast `podcast.m4a` berdurasi 70 detik. Skrip Node.js dan Python untuk memproses daftar tautan secara batch ada di folder `podcast/` di [repo contoh GitHub](https://github.com/useapi/notebooklm-api). ### Skala besar: banyak akun dan pembatasan API ini bisa berjalan tanpa diawasi: - Setelah beberapa akun Google terhubung, setiap job baru diberikan ke akun yang sehat, punya slot job kosong, dan masih punya kuota untuk jenis konten itu. Anda tidak perlu memantau sendiri anggaran 5 jam dan mingguan. - Setiap akun menjalankan paling banyak `maxJobs` job sekaligus (default 3, bisa 1–10, diubah dengan [POST /accounts](/docs/api-gemini-notebook-v1/post-gemini-notebook-accounts)). [GET /jobs](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs) menampilkan job yang sedang berjalan di setiap akun. - Jika semua akun sibuk atau kuotanya tidak cukup, panggilan mengembalikan `429`. Jika Google memberi waktu reset, respons membawa `retryAt`, dan kode Anda bisa menunggu sampai waktu itu, mengirim batch berikutnya ke akun lain dengan `email`, atau menurunkan frekuensi. - [GET /accounts/`email`](/docs/api-gemini-notebook-v1/get-gemini-notebook-accounts-email) mengembalikan pemakaian akun secara langsung, waktu reset kedua jendela, dan perkiraan terkini untuk setiap jenis konten. ### Otomatisasi Gemini Notebook (NotebookLM): n8n, Colab dan asisten coding AI - [Template n8n](/docs/articles/notebooklm-n8n-podcast) (bahasa Inggris): mengubah halaman web, video YouTube atau feed RSS blog menjadi podcast Gemini Notebook, langsung pakai setelah diimpor. - [Notebook Google Colab](https://colab.research.google.com/github/useapi/notebooklm-api/blob/main/notebooks/notebooklm_podcast.ipynb): isi token dan tautan di browser, lalu putar dan unduh podcast-nya. - Asisten coding AI seperti Claude Code dan Codex bisa memasang skill `notebooklm-podcast` dari repo dan membuat podcast dengan satu kalimat: `npx skills add useapi/notebooklm-api --skill notebooklm-podcast`. Semuanya ada di repo [useapi/notebooklm-api](https://github.com/useapi/notebooklm-api). ### Contoh hasil Berikut hasil asli yang dibuat lewat Gemini Notebook API yang sama, dari halaman Wikipedia Apollo 11 berbahasa Inggris, satu video YouTube NASA, satu teks yang ditempel dan satu PDF. Semuanya diambil dari [tutorial bahasa Inggris](/docs/articles/gemini-notebook-bash#results), jadi isinya berbahasa Inggris. Audio Overview, format `brief`, durasi `short`, panjang 1 menit 31 detik, dibuat dalam 4 menit 36 detik: <audio controls class="audio-player" style="width:100%"><source src="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-audio-overview-brief-apollo11-0929.m4a" type="audio/mp4"></audio> Video Overview, format `explainer`, gaya `whiteboard`, panjang penuh 11 menit 50 detik, di sini 90 detik pertama: <video poster="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-video-explainer-whiteboard-apollo11-first90s-0929-poster.jpg" controls width="100%" style="max-width:640px;border-radius:8px" src="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-video-explainer-whiteboard-apollo11-first90s-0929.mp4"></video> Infografis vertikal, gaya `sketch_note`, 1536 × 2752, dibuat dalam 1 menit 45 detik: <a href="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-infographic-sketch-note-apollo11-0929.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-infographic-sketch-note-apollo11-0929.png" alt="Infografis Apollo 11 yang dibuat dengan Gemini Notebook API" style="width:100%;max-width:360px;border-radius:8px"></a> ### Pertanyaan yang sering diajukan - **Apakah Gemini Notebook (NotebookLM) punya API resmi?** Lewat useapi.net, akun biasa bisa memakainya: Gemini Notebook API useapi.net adalah REST API pihak ketiga yang menjalankan akun Google Anda sendiri, bekerja di paket pribadi gratis maupun berbayar, dan mencakup semua fitur versi web. Google hanya menyediakan API untuk Gemini Notebook Enterprise, yang butuh lisensi Enterprise di project Google Cloud, hanya mencakup pengelolaan notebook, penambahan sumber dan Audio Overview, dan tidak bisa dipakai akun Google biasa (per Oktober 2026). Perbandingannya ada di [Harga](#pricing). - **Apakah saya butuh Gemini API key atau API key Gemini Notebook (NotebookLM)?** Lewat useapi.net, tidak. Anda memanggil API dengan [API token](/docs/start-here/setup-useapi) useapi.net, lalu menghubungkan akun Google sekali lewat [alur otomatis](/docs/start-here/setup-gemini-notebook), tanpa project Google Cloud. Google tidak menerbitkan API key Gemini Notebook untuk akun biasa. - **Apakah podcast berbahasa Indonesia didukung?** Lewat useapi.net, didukung. Kirim `language: "id"` di [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts), seperti [contoh di atas](#quick-start). `language` berlaku untuk audio, video (kecuali `cinematic`), laporan, laporan interaktif, tabel data, infografis dan slide, dengan default `en`. Anda juga bisa mengatur bahasa hasil Studio untuk seluruh akun dengan `outputLanguage` di [POST /accounts](/docs/api-gemini-notebook-v1/post-gemini-notebook-accounts). - **Apakah ada API Gemini Notebook (NotebookLM) gratis?** Lewat useapi.net, Gemini Notebook API berjalan di akun Google gratis tanpa biaya di sisi Google, sedangkan Google tidak punya API untuk akun biasa. Langganan useapi.net $15 per bulan. Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Lihat [kebijakan refund](/docs/legal#refund-policy). - **Apakah akun Google gratis bisa dipakai?** Lewat useapi.net, bisa. Paket gratis mendapat kuota lebih kecil per jendela 5 jam, sekitar 2 Audio Overview menurut perkiraan Google. Paket Google AI berbayar menaikkan batasnya, dan video Cinematic butuh paket berbayar. - **Berapa lama satu podcast dibuat?** Lewat useapi.net, Audio Overview biasanya 3–6 menit, Video Overview 10 menit lebih, infografis dan laporan satu sampai dua menit, kuis sekitar satu setengah menit, dan flashcard serta tabel data kurang dari satu menit. - **Apakah NotebookLM dan Gemini Notebook produk yang sama?** Lewat useapi.net, keduanya dijalankan oleh API yang sama: Gemini Notebook adalah nama baru NotebookLM sejak Juli 2026, dan API di artikel ini adalah NotebookLM API. Pertanyaan lainnya ada di [FAQ Gemini Notebook API (bahasa Inggris)](/docs/api-gemini-notebook-v1#questions). ### Kesimpulan Ada pertanyaan? Bergabunglah dengan <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Server Discord</a> atau <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Channel Telegram</a> kami. Semua endpoint ada di [dokumentasi Gemini Notebook API](/docs/api-gemini-notebook-v1), dan contoh kode ada di [repo GitHub](https://github.com/useapi/notebooklm-api). === URL: https://useapi.net/docs/articles/gemini-notebook-bash-ja === Document URL: https://useapi.net/docs/articles/gemini-notebook-bash-ja --- layout: default title: Gemini Notebook API(NotebookLM API)で Web ページ、PDF、YouTube 動画を日本語のポッドキャストにする方法 seo_title: "Gemini Notebook API(NotebookLM API)の使い方:curl で日本語ポッドキャスト" description: "useapi.net の Gemini Notebook API(NotebookLM API)で、Web ページや YouTube 動画から日本語の音声解説(Audio Overview)ポッドキャストを curl 1回で生成。無料の Google アカウントで使え、料金は月 $15 の定額。" keywords: [Gemini Notebook API, NotebookLM API, NotebookLM API 使い方, NotebookLM API 日本語, NotebookLM ポッドキャスト, NotebookLM 日本語 ポッドキャスト, NotebookLM 音声解説, Audio Overview API, NotebookLM Audio Overview, NotebookLM 自動化, NotebookLM API キー, NotebookLM Python, NotebookLM 動画解説, Gemini Notebook 日本語, AI ポッドキャスト 生成 API, 日本語チュートリアル, Japanese tutorial, tutorial, code] image: https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-infographic-sketch-note-apollo11-0929.png parent: Articles nav_exclude: true lang: ja date: 2026-10-04 last_modified: 2026-10-18 nav_order: 895 repo: https://github.com/useapi/notebooklm-api translation_key: gemini-notebook --- ## Gemini Notebook API(NotebookLM API)で Web ページ、PDF、YouTube 動画を日本語のポッドキャストにする方法 {: .no_toc #how-to-automate-gemini-notebook-notebooklm-with-the-api-deep-research-chat-audio-overviews-and-a-lot-more } 6分で読めます • 2026年10月4日(2026年10月18日更新) useapi.net はサードパーティの API です。Google とは提携しておらず、Google の承認も受けていません。 ## 目次 {: .no_toc .text-delta #table-of-contents } ### はじめに [useapi.net](/docs/api-gemini-notebook-v1) の Gemini Notebook API(NotebookLM API)を使うと、REST の呼び出し1回で Web ページや YouTube 動画をご自身の Google アカウントに渡し、Gemini Notebook の音声解説(Audio Overview)のポッドキャストを作って、`.m4a` ファイルでダウンロードできます。ポッドキャストの言語は日本語にも指定できます。Google Cloud プロジェクトも Gemini API キーも不要で、無料の Google アカウントでも使えます。 Google は NotebookLM の名前を [Gemini Notebook](https://notebook.google.com) に変更しましたが、機能は変わりません。通常の Google アカウントには公式の API がありません。Web 版でできることは、この API ですべてコードから実行できます。ノートブックの作成、ソースの追加、引用付きのチャット、Deep Research、そして Studio のすべての生成機能です。 この記事は useapi.net の運営者が、自社のホスト型 API について書いたものです。サンプルコードは [GitHub](https://github.com/useapi/notebooklm-api) で公開しています。 ### Gemini Notebook API で作れるもの:ポッドキャスト、動画解説、スライド、インフォグラフィック [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts) では、`type` パラメーターで作るものを選びます。 | 作るもの | `type` | 出力 | |---|---|---| | 音声解説(2人のポッドキャスト) | `audio`。`format` は `deep_dive`(デフォルト)、`brief`、`critique`、`debate` から選択 | `m4a` 音声 | | 動画解説(Video Overview) | `video`。`format` は `explainer`(デフォルト)、`brief`、`cinematic`、`short` から選択 | `mp4` 動画 | | スライド資料 | `slides` | `pdf` と `pptx` | | インフォグラフィック | `infographic` | `png` 画像 | | レポート、インタラクティブレポート、データテーブル | `report`、`interactive_report`、`table` | Markdown テキストまたは表の行 | | クイズ、フラッシュカード、マインドマップ | `quiz`、`flashcards`、`mindmap` | JSON | 音声、動画(`cinematic` を除く)、レポート、インタラクティブレポート、データテーブル、スライド、インフォグラフィックは、`language` で出力言語を指定できます。日本語は `ja` です。 ### Gemini Notebook API(NotebookLM API)の料金 useapi.net には月 [$15](/docs/subscription) の定額を支払います。同じサブスクリプションで、Gemini Notebook だけでなく useapi.net のすべての API を使えます。サブスクリプション1つにつき Google アカウントを3つ接続でき、合計で最大100アカウントまで増やせます。生成はご自身の Google アカウントで行われ、当社は回数や音声ごとに料金を取りません。Google 側の利用分はアカウントの既存のプランに含まれ、無料プランでも使えます。 | | useapi.net Gemini Notebook API | Google の [Gemini Notebook Enterprise API](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks) | |---|:-:|:-:| | アカウント | ご自身の Google アカウント(無料・有料プランどちらも可) | Google Cloud プロジェクトの Enterprise ライセンス | | 料金 | 月 $15 の定額 | ユーザーごとに Enterprise ライセンスを購入 | | 引用付きのチャット | Yes | No | | Deep Research | Yes | No | | 音声解説 | Yes | Yes | | 動画解説、スライド、インフォグラフィック、レポート、クイズ、フラッシュカード、マインドマップ | Yes | No | | ステータス | 試験的 | プレビュー版(Pre-GA) | Google はアカウントごとに利用枠を設けています。利用枠は5時間ごとに回復し、さらに週間の上限もあります。Google 自身の見積もりでは、満タンの5時間の枠で開始できる音声解説は、少なくとも2本(無料プラン)、9本(Google AI Pro)、181本(Google AI Ultra)で、実際に完了すると見積もりより少ない消費で済むことがよくあります。もっと多く作りたい場合は、アカウントを追加で接続します。詳しくは[スケールさせる](#scale)を参照してください。 ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. ### 準備 1. useapi.net に登録して [API トークン](/docs/start-here/setup-useapi)を取得します。以下の例では、トークンが環境変数 `USEAPI_TOKEN` に入っているものとします。 2. [自動化されたブラウザーの手順](/docs/start-here/setup-gemini-notebook)で Google アカウントを接続します。トークンを入力し、リモートのブラウザーで Google にログインするだけで、Cookie を手動でコピーする必要はありません。個人のメインアカウントではなく、[専用の Gmail アカウント](/docs/start-here/setup-gemini-notebook#use-a-dedicated-gmail-account)を使うことをおすすめします。 以下の単発リクエストとノートブックの新規作成では、`email` を省略できます。接続しているアカウントが1つならそれが使われ、複数なら API が空いているアカウントを選びます。ノートブックを指定する呼び出しは、常にそのノートブックを持つアカウントで実行されます。 ### API 呼び出し1回で Gemini Notebook の日本語ポッドキャストを作る ノートブックを先に作る必要はありません。`urls`(または貼り付けた `text`)を [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts#one-shot-requests) に直接送ると、API がアカウントの1つに新しいノートブックを作り、ソースを追加し、ソースの処理が終わるのを待ってから生成を始めます。`youtube.com` と `youtu.be` のリンクは YouTube のソースとして追加され、1回に最大50件のリンクを送れます。 ```bash JOBID=$(curl -s -X POST "https://api.useapi.net/v1/gemini-notebook/artifacts" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "type": "audio", "format": "brief", "length": "short", "language": "ja", "urls": ["https://ja.wikipedia.org/wiki/アポロ11号"], "title": "アポロ11号のポッドキャスト", "mode": "async" }' | jq -r '.jobid') ``` `mode: "async"` はすぐに `201` と `jobid` を返します。デフォルトの `mode: "sync"` は最大90秒待ちますが、ポッドキャストには通常数分かかるので、まず `202` が返り、その後は同じようにポーリングが必要です。 ### ジョブをポーリングしてダウンロードする [GET /jobs/`jobid`](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid) を、`status` が `completed` か `failed` になるまで呼びます。`jobid` には `:` と `@` が含まれるので、URL パスに入れる前にエンコードします。完了後の `result.files[].url` は [GET /artifacts/download](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts-download) を指しており、ダウンロードにも API トークンが必要です。次の関数は、このあとも使います。 ```bash API=https://api.useapi.net/v1/gemini-notebook enc() { jq -rn --arg v "$1" '$v|@uri'; } wait_job() { [ -z "$1" ] || [ "$1" = "null" ] && { echo "送信に失敗しました。応答の error を確認してください"; return 1; } until curl -s "$API/jobs/$(enc "$1")" -H "Authorization: Bearer $USEAPI_TOKEN" > job.json && jq -e '.status == "completed" or .status == "failed"' job.json > /dev/null; do sleep 15 done jq '{status, title: .result.title, duration: .result.duration, error}' job.json jq -r '.result.files[]?.url' job.json | while read -r url; do curl -s -OJ -H "Authorization: Bearer $USEAPI_TOKEN" "$url" done } wait_job "$JOBID" ``` 2026年10月4日に、同じリクエストを中国語(`zh_Hans`)と中国語版 Wikipedia のページで実行しました。約6分でジョブが完了し、Google は99秒のポッドキャストを作りました。`-OJ` は、Google が付けたタイトルでファイルを `.m4a` として保存します。 - 失敗したジョブには `error.code` が付きます。たとえば `quota`(利用枠の不足)、`sources`(使えるソースがない)、`generation_failed` です。 - ポーリングしたくない場合は、リクエストに `replyUrl` を渡します。ジョブが終わると、ジョブの記録全体が1回 `POST` されます。 - 生成したファイルはノートブックに残り、ダウンロードリンクはノートブックと生成結果が残っている限り有効です。 ### 全体の流れ:ノートブック、ソース、生成 同じソースから複数の種類を作りたいときや、ローカルのファイルをアップロードしたいときは、先にノートブックを作ります。ソースには、Web ページ、YouTube 動画、貼り付けたテキスト、Google ドライブのファイル、アップロードした PDF、Word、PowerPoint、EPUB、音声、動画などのファイルを使えます。 ```bash # 1. ノートブックを新規作成 NOTEBOOK=$(curl -s -X POST "$API/notebooks" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{"title": "アポロ11号"}' | jq -r '.notebook') # 2. Web ページと YouTube 動画を追加 curl -s -X POST "$API/sources" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d "$(jq -n --arg nb "$NOTEBOOK" '{ notebook: $nb, urls: ["https://ja.wikipedia.org/wiki/アポロ11号", "https://www.youtube.com/watch?v=xUcYQ7slmRw"] }')" # 3. PDF をアップロード(ファイル自体がリクエストボディ) curl -s -X POST "$API/sources/upload?notebook=$(enc "$NOTEBOOK")&name=report.pdf" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/pdf" \ --data-binary @report.pdf # 4. すべてのソースの処理が終わるまで待つ until curl -s "$API/notebooks/$(enc "$NOTEBOOK")" -H "Authorization: Bearer $USEAPI_TOKEN" > notebook.json && jq -e '[.sources[].status] | all(. == "ready" or . == "error")' notebook.json > /dev/null; do sleep 10 done # 5. 日本語のインフォグラフィックを生成 JOBID=$(curl -s -X POST "$API/artifacts" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d "$(jq -n --arg nb "$NOTEBOOK" '{notebook: $nb, type: "infographic", orientation: "portrait", language: "ja", mode: "async"}')" \ | jq -r '.jobid') wait_job "$JOBID" ``` 中国語で実行した実測では、3つのソースは約30秒ですべて準備でき、縦長のインフォグラフィックは約2分で生成され、1536 × 2752 の `png` になりました。ステップ5の `type` を `audio`、`video`、`slides` に変えれば、同じノートブックでポッドキャスト、動画解説、スライドも続けて作れます。チャット、Deep Research、スライドの1ページだけの修正を含む19ステップの完全なデモは、[英語のチュートリアル](/docs/articles/gemini-notebook-bash)にあります。 ### Python の例 上の単発リクエストとほぼ同じ内容(`length` は指定せず、デフォルトの長さ)を、Python と `requests` で書くと次のようになります。 ```python import os, time, requests from urllib.parse import quote API = 'https://api.useapi.net/v1/gemini-notebook' H = {'Authorization': f"Bearer {os.environ['USEAPI_TOKEN']}"} r = requests.post(f'{API}/artifacts', headers=H, json={ 'type': 'audio', 'format': 'brief', 'language': 'ja', 'urls': ['https://ja.wikipedia.org/wiki/アポロ11号'], 'mode': 'async', }) r.raise_for_status() job = r.json() while job['status'] in ('pending', 'processing'): time.sleep(15) r = requests.get(f"{API}/jobs/{quote(job['jobid'], safe='')}", headers=H) r.raise_for_status() job = r.json() if job['status'] == 'failed': raise SystemExit(job['error']) print(job['result']['title'], job['result']['duration'], '秒') for f in job['result']['files']: with open(f"podcast.{f['format']}", 'wb') as out: out.write(requests.get(f['url'], headers=H).content) ``` このスクリプトを中国語で実行したときは約6分半で終わり、70秒のポッドキャスト `podcast.m4a` ができました。リンクのリストを一括処理する Node.js と Python のスクリプトは、[GitHub のサンプルリポジトリ](https://github.com/useapi/notebooklm-api)の `podcast/` フォルダーにあります。 ### スケールさせる:複数アカウントとレート制限 この API は無人で動かせます。 - 複数の Google アカウントを接続すると、新しいジョブはそれぞれ、状態が正常で、空いているジョブ枠があり、その種類の利用枠が残っているアカウントに割り当てられます。5時間と週間の利用枠を自分で見張る必要はありません。 - 各アカウントで同時に実行できるジョブは最大 `maxJobs` 件です(デフォルトは3、1〜10に設定でき、[POST /accounts](/docs/api-gemini-notebook-v1/post-gemini-notebook-accounts) で変更します)。[GET /jobs](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs) で、各アカウントで実行中のジョブを確認できます。 - すべてのアカウントが使用中か、利用枠が足りないときは `429` が返ります。Google がリセット時刻を示した場合は応答に `retryAt` が入るので、コードでその時刻まで待って再試行するか、`email` で次のバッチを別のアカウントに送るか、頻度を下げます。 - [GET /accounts/`email`](/docs/api-gemini-notebook-v1/get-gemini-notebook-accounts-email) は、アカウントのリアルタイムの利用状況、2つの枠のリセット時刻、生成の種類ごとの現在の見積もりを返します。 ### Gemini Notebook(NotebookLM)の自動化:n8n、Colab、AI コーディングアシスタント - [n8n テンプレート](/docs/articles/notebooklm-n8n-podcast)(英語):Web ページ、YouTube 動画、ブログの RSS フィードを Gemini Notebook のポッドキャストにします。インポートするだけで使えます。 - [Google Colab ノートブック](https://colab.research.google.com/github/useapi/notebooklm-api/blob/main/notebooks/notebooklm_podcast.ipynb):ブラウザーでトークンとリンクを入力し、ポッドキャストをその場で再生してダウンロードできます。 - Claude Code や Codex などの AI コーディングアシスタントは、リポジトリの `notebooklm-podcast` スキルをインストールすれば、1文でポッドキャストを作れます:`npx skills add useapi/notebooklm-api --skill notebooklm-podcast`。 これらはすべて [useapi/notebooklm-api](https://github.com/useapi/notebooklm-api) リポジトリにあります。 ### 生成結果の例 以下は、同じ Gemini Notebook API で作った実際の結果です。ソースは Apollo 11 の英語版 Wikipedia ページ、NASA の YouTube 動画、貼り付けたテキスト、PDF 1つです。[英語のチュートリアル](/docs/articles/gemini-notebook-bash#results)から転載しているため、内容は英語です。 音声解説、`brief` 形式、`short` の長さ、長さ1分31秒、生成時間4分36秒: <audio controls class="audio-player" style="width:100%"><source src="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-audio-overview-brief-apollo11-0929.m4a" type="audio/mp4"></audio> 動画解説、`explainer` 形式、`whiteboard` スタイル、全体の長さ11分50秒のうち最初の90秒: <video poster="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-video-explainer-whiteboard-apollo11-first90s-0929-poster.jpg" controls width="100%" style="max-width:640px;border-radius:8px" src="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-video-explainer-whiteboard-apollo11-first90s-0929.mp4"></video> インフォグラフィック、縦長、`sketch_note` スタイル、1536 × 2752、生成時間1分45秒: <a href="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-infographic-sketch-note-apollo11-0929.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-infographic-sketch-note-apollo11-0929.png" alt="Gemini Notebook API で生成した Apollo 11 のインフォグラフィック" style="width:100%;max-width:360px;border-radius:8px"></a> ### よくある質問 - **Gemini Notebook(NotebookLM)に公式の API はありますか?** useapi.net を使えば、通常のアカウントで使えます。useapi.net の Gemini Notebook API は、ご自身の Google アカウントを動かすサードパーティの REST API で、無料と有料の個人プランのどちらでも使え、Web 版のすべての機能をカバーし、料金は月 $15 の定額です(2026年10月時点)。Google が API を提供しているのは Gemini Notebook Enterprise だけで、Google Cloud プロジェクトで Enterprise ライセンスを購入する必要があり、できるのはノートブックの管理、ソースの追加、音声解説の生成に限られます。通常の Google アカウントでは使えません。比較は[料金](#pricing)を参照してください。 - **Gemini API キーや NotebookLM の API キーは必要ですか?** useapi.net を使えば、不要です。月 $15 の定額(2026年10月時点)の useapi.net の [API トークン](/docs/start-here/setup-useapi)で API を呼び出し、[自動化された手順](/docs/start-here/setup-gemini-notebook)で Google アカウントを一度接続するだけで、Google Cloud プロジェクトも要りません。Google は通常のアカウントには Gemini Notebook の API キーを発行していません。 - **日本語のポッドキャストに対応していますか?** useapi.net を使えば、対応しています。[POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts) で `language: "ja"` を渡します([上の例](#quick-start)を参照)。`language` は、音声、動画(`cinematic` を除く)、レポート、インタラクティブレポート、データテーブル、インフォグラフィック、スライドに使え、デフォルトは `en` です(2026年10月時点)。[POST /accounts](/docs/api-gemini-notebook-v1/post-gemini-notebook-accounts) の `outputLanguage` で、アカウント全体の Studio の出力言語を設定することもできます。 - **Gemini Notebook(NotebookLM)を無料で使える API はありますか?** useapi.net を使えば、Gemini Notebook API は無料の Google アカウントで使え、Google 側の料金はかかりません。Google には通常のアカウント向けの API がありません。useapi.net のサブスクリプションは月 $15 です(2026年10月時点)。Stripe で支払った場合、初回購入から14日以内で、成功した生成が50回未満なら全額返金されます。[返金ポリシー](/docs/legal#refund-policy)を参照してください。 - **無料の Google アカウントで使えますか?** useapi.net を使えば、使えます。無料プランでは、5時間の枠ごとに音声解説を約2本開始できます(2026年10月時点)。有料の Google AI プランでは上限が上がり、シネマティックな動画には有料プランが必要です。 - **ポッドキャスト1本の生成にどのくらいかかりますか?** useapi.net を使えば、音声解説は通常3〜6分、動画解説は10分以上、インフォグラフィックとレポートは1〜2分、クイズは約1分半、フラッシュカードとデータテーブルは1分未満です。 - **NotebookLM と Gemini Notebook は同じ製品ですか?** はい。Gemini Notebook は、2026年7月からの NotebookLM の新しい名前です。この記事の API は NotebookLM API と同じものです。 その他の質問は [Gemini Notebook API のよくある質問(英語)](/docs/api-gemini-notebook-v1#questions)を参照してください。 ### おわりに ご質問は <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord サーバー</a> または <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram チャンネル</a>へどうぞ。 すべてのエンドポイントは [Gemini Notebook API のドキュメント](/docs/api-gemini-notebook-v1)、サンプルコードは [GitHub リポジトリ](https://github.com/useapi/notebooklm-api)にあります。 === URL: https://useapi.net/docs/articles/gemini-notebook-bash-pt === Document URL: https://useapi.net/docs/articles/gemini-notebook-bash-pt --- layout: default title: "Como usar a Gemini Notebook API (NotebookLM API) para transformar páginas web, PDFs e vídeos do YouTube em podcasts em português" seo_title: "Gemini Notebook API (NotebookLM API): podcast em português com curl" description: "Gere podcasts Audio Overview em português a partir de páginas web ou vídeos do YouTube com um curl, pela Gemini Notebook API (NotebookLM API) da useapi.net. Funciona em conta Google gratuita." keywords: [Gemini Notebook API, NotebookLM API, API do NotebookLM, NotebookLM API em português, NotebookLM podcast, podcast NotebookLM em português, Audio Overview API, NotebookLM Audio Overview, automação NotebookLM, NotebookLM API Key, chave da API NotebookLM, NotebookLM Python, NotebookLM Video Overview, API para gerar podcast com IA, Gemini Notebook em português, tutorial NotebookLM API, tutorial, code] image: https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-infographic-sketch-note-apollo11-0929.png parent: Articles nav_exclude: true lang: pt-BR date: 2026-10-04 last_modified: 2026-10-18 nav_order: 895 repo: https://github.com/useapi/notebooklm-api translation_key: gemini-notebook --- ## Como usar a Gemini Notebook API (NotebookLM API) para transformar páginas web, PDFs e vídeos do YouTube em podcasts em português {: .no_toc #how-to-automate-gemini-notebook-notebooklm-with-the-api-deep-research-chat-audio-overviews-and-a-lot-more } 6 min de leitura • 4 de outubro de 2026 (18 de outubro de 2026) A useapi.net é uma API de terceiros. Não tem afiliação com o Google nem é endossada por ele. ## Sumário {: .no_toc .text-delta #table-of-contents } ### Introdução Com a Gemini Notebook API (NotebookLM API) da [useapi.net](/docs/api-gemini-notebook-v1), uma única chamada REST entrega uma página web ou um vídeo do YouTube à sua própria conta Google e devolve um podcast Audio Overview do Gemini Notebook como arquivo `.m4a`, e você pode pedir o podcast em português. Não precisa de projeto no Google Cloud nem de chave da Gemini API, e uma conta Google gratuita funciona. O Google renomeou o NotebookLM para [Gemini Notebook](https://notebook.google.com), e as funções continuam as mesmas. Contas Google comuns não têm API oficial. Tudo o que o site faz, esta API faz por código: criar notebooks, adicionar fontes, chat com citações, Deep Research e todas as gerações do Studio. Este artigo foi escrito pelos mantenedores da useapi.net e fala da nossa própria API hospedada. O código de exemplo é aberto no [GitHub](https://github.com/useapi/notebooklm-api). ### O que a Gemini Notebook API gera: podcasts, Video Overviews, slides, infográficos [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts) escolhe o que gerar com o parâmetro `type`: | O que gera | `type` | Devolve | |---|---|---| | Audio Overview (podcast com duas vozes) | `audio`, `format` pode ser `deep_dive` (padrão), `brief`, `critique`, `debate` | áudio `m4a` | | Video Overview | `video`, `format` pode ser `explainer` (padrão), `brief`, `cinematic`, `short` | vídeo `mp4` | | Apresentação de slides | `slides` | `pdf` e `pptx` | | Infográfico | `infographic` | imagem `png` | | Relatório, relatório interativo, tabela de dados | `report`, `interactive_report`, `table` | texto em Markdown ou linhas de tabela | | Quiz, flashcards, mapa mental | `quiz`, `flashcards`, `mindmap` | JSON | Áudio, vídeo (exceto `cinematic`), relatório, relatório interativo, tabela de dados, slides e infográfico aceitam `language` para definir o idioma da saída. Português do Brasil é `pt_BR`. ### Preço da Gemini Notebook API (NotebookLM API) Você paga à useapi.net um valor fixo de [$15 por mês](/docs/subscription), e a mesma assinatura inclui todas as APIs da useapi.net, não só o Gemini Notebook. Cada assinatura conecta 3 contas Google, até 100 no total. A geração roda na sua própria conta Google, nós não cobramos por chamada nem por podcast, e o uso do lado do Google está incluído no plano que a conta já tem, inclusive o gratuito. | | Gemini Notebook API da useapi.net | [Gemini Notebook Enterprise API](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks) do Google | |---|:-:|:-:| | Conta | A sua própria conta Google, plano gratuito ou pago | Licenças Enterprise em um projeto Google Cloud | | Preço | $15 fixos por mês | Licenças Enterprise compradas por usuário | | Chat com citações | Yes | No | | Deep Research | Yes | No | | Audio Overview | Yes | Yes | | Video Overviews, slides, infográficos, relatórios, quizzes, flashcards, mapas mentais | Yes | No | | Status | Experimental | Preview (Pre-GA) | O Google define um orçamento de uso por conta, que se renova a cada 5 horas, além de um orçamento semanal. Pelas estimativas do próprio Google, uma janela completa de 5 horas inicia pelo menos 2 (plano gratuito), 9 (Google AI Pro) ou 181 (Google AI Ultra) Audio Overviews, e na prática, depois de prontos, eles costumam gastar menos que o estimado. Para produzir mais, conecte mais contas, veja [Escala](#scale). ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. ### Preparação 1. Cadastre-se na useapi.net e pegue o seu [token da API](/docs/start-here/setup-useapi). Todos os exemplos abaixo supõem que ele está na variável de ambiente `USEAPI_TOKEN`. 2. Conecte a conta Google pelo [fluxo automatizado no navegador](/docs/start-here/setup-gemini-notebook): informe o token e entre no Google em um navegador remoto, sem copiar cookies à mão. Recomendamos usar uma [conta Gmail dedicada](/docs/start-here/setup-gemini-notebook#use-a-dedicated-gmail-account), não a sua conta pessoal principal. As requisições de uma só chamada e a criação de notebooks abaixo podem omitir o `email`: com uma única conta conectada, a API usa essa conta, e com várias, escolhe uma que esteja livre. Chamadas sobre um notebook sempre rodam na conta dona desse notebook. ### Como gerar um podcast do Gemini Notebook em português com uma única chamada de API Não precisa criar um notebook antes. Mande `urls` (ou um `text` colado) direto para [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts#one-shot-requests), e a API cria um notebook em uma das suas contas, adiciona as fontes, espera o processamento e começa a gerar. Links de `youtube.com` e `youtu.be` entram como fontes do YouTube, até 50 links por vez. ```bash JOBID=$(curl -s -X POST "https://api.useapi.net/v1/gemini-notebook/artifacts" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "type": "audio", "format": "brief", "length": "short", "language": "pt_BR", "urls": ["https://pt.wikipedia.org/wiki/Apollo_11"], "title": "Podcast da Apollo 11", "mode": "async" }' | jq -r '.jobid') ``` `mode: "async"` devolve `201` e o `jobid` na hora. O padrão, `mode: "sync"`, espera até 90 segundos, mas um podcast costuma levar alguns minutos, então ele devolve `202` primeiro e você consulta do mesmo jeito. ### Consultar o job e baixar Consulte [GET /jobs/`jobid`](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid) até `status` virar `completed` ou `failed`. O `jobid` tem `:` e `@`, então codifique antes de colocá-lo em um caminho de URL. No job pronto, `result.files[].url` aponta para [GET /artifacts/download](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts-download), e o download também leva o token da API. Esta função é usada de novo mais adiante: ```bash API=https://api.useapi.net/v1/gemini-notebook enc() { jq -rn --arg v "$1" '$v|@uri'; } wait_job() { [ -z "$1" ] || [ "$1" = "null" ] && { echo "Falha no envio, veja o error na resposta"; return 1; } until curl -s "$API/jobs/$(enc "$1")" -H "Authorization: Bearer $USEAPI_TOKEN" > job.json && jq -e '.status == "completed" or .status == "failed"' job.json > /dev/null; do sleep 15 done jq '{status, title: .result.title, duration: .result.duration, error}' job.json jq -r '.result.files[]?.url' job.json | while read -r url; do curl -s -OJ -H "Authorization: Bearer $USEAPI_TOKEN" "$url" done } wait_job "$JOBID" ``` Rodamos esta mesma requisição em 4 de outubro de 2026, em chinês (`zh_Hans`) e com a página da Wikipédia em chinês: o job terminou em cerca de 6 minutos, o Google gerou um podcast de 99 segundos, e o `-OJ` salvou o `.m4a` com o título que o Google deu. - Um job que falhou traz `error.code`, por exemplo `quota` (uso insuficiente), `sources` (nenhuma fonte pôde ser usada) ou `generation_failed`. - Para não consultar, passe `replyUrl` na requisição: quando o job terminar, você recebe um único `POST` com o registro completo do job. - Os arquivos gerados ficam no notebook, e os links de download continuam valendo enquanto o notebook e o resultado existirem. ### O fluxo completo: notebook, fontes e geração Para gerar vários tipos de conteúdo a partir das mesmas fontes, ou para enviar arquivos locais, crie um notebook antes. As fontes podem ser páginas web, vídeos do YouTube, texto colado, arquivos do Google Drive e arquivos enviados, como PDF, Word, PowerPoint, EPUB, áudio e vídeo. ```bash # 1. Criar o notebook NOTEBOOK=$(curl -s -X POST "$API/notebooks" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{"title": "Apollo 11"}' | jq -r '.notebook') # 2. Adicionar uma página web e um vídeo do YouTube curl -s -X POST "$API/sources" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d "$(jq -n --arg nb "$NOTEBOOK" '{ notebook: $nb, urls: ["https://pt.wikipedia.org/wiki/Apollo_11", "https://www.youtube.com/watch?v=xUcYQ7slmRw"] }')" # 3. Enviar um PDF: o próprio arquivo é o corpo da requisição curl -s -X POST "$API/sources/upload?notebook=$(enc "$NOTEBOOK")&name=report.pdf" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/pdf" \ --data-binary @report.pdf # 4. Esperar todas as fontes ficarem prontas until curl -s "$API/notebooks/$(enc "$NOTEBOOK")" -H "Authorization: Bearer $USEAPI_TOKEN" > notebook.json && jq -e '[.sources[].status] | all(. == "ready" or . == "error")' notebook.json > /dev/null; do sleep 10 done # 5. Gerar um infográfico em português JOBID=$(curl -s -X POST "$API/artifacts" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d "$(jq -n --arg nb "$NOTEBOOK" '{notebook: $nb, type: "infographic", orientation: "portrait", language: "pt_BR", mode: "async"}')" \ | jq -r '.jobid') wait_job "$JOBID" ``` No nosso teste (com saída em chinês), as três fontes ficaram prontas em cerca de 30 segundos, e o infográfico vertical levou cerca de 2 minutos, um `png` de 1536 × 2752. Troque o `type` do passo 5 por `audio`, `video` ou `slides` para gerar um podcast, um Video Overview ou slides no mesmo notebook. A demonstração completa em 19 passos (com chat, Deep Research e a revisão de um slide) está no [artigo em inglês](/docs/articles/gemini-notebook-bash). ### Exemplo em Python Quase a mesma requisição de uma só chamada (sem `length`, então com a duração padrão), em Python com `requests`: ```python import os, time, requests from urllib.parse import quote API = 'https://api.useapi.net/v1/gemini-notebook' H = {'Authorization': f"Bearer {os.environ['USEAPI_TOKEN']}"} r = requests.post(f'{API}/artifacts', headers=H, json={ 'type': 'audio', 'format': 'brief', 'language': 'pt_BR', 'urls': ['https://pt.wikipedia.org/wiki/Apollo_11'], 'mode': 'async', }) r.raise_for_status() job = r.json() while job['status'] in ('pending', 'processing'): time.sleep(15) r = requests.get(f"{API}/jobs/{quote(job['jobid'], safe='')}", headers=H) r.raise_for_status() job = r.json() if job['status'] == 'failed': raise SystemExit(job['error']) print(job['result']['title'], job['result']['duration'], 's') for f in job['result']['files']: with open(f"podcast.{f['format']}", 'wb') as out: out.write(requests.get(f['url'], headers=H).content) ``` Quando rodamos este script em chinês, ele levou cerca de 6 minutos e meio e gerou um `podcast.m4a` de 70 segundos. Scripts em Node.js e Python que processam uma lista de links estão na pasta `podcast/` do [repositório de exemplos no GitHub](https://github.com/useapi/notebooklm-api). ### Escala: várias contas e limites de taxa Esta API pode rodar sem ninguém olhando: - Com várias contas Google conectadas, cada job novo vai para uma conta saudável, com vaga de job livre e uso suficiente para aquele tipo, sem você precisar acompanhar os orçamentos de 5 horas e semanal. - Cada conta roda até `maxJobs` jobs ao mesmo tempo (padrão 3, de 1 a 10, mude com [POST /accounts](/docs/api-gemini-notebook-v1/post-gemini-notebook-accounts)). [GET /jobs](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs) mostra os jobs rodando em cada conta. - Quando todas as contas estão ocupadas ou sem uso suficiente, a chamada devolve `429`. Se o Google informou um horário de renovação, a resposta traz `retryAt`, e o seu código pode esperar até lá, mandar o próximo lote para outra conta com `email`, ou diminuir o ritmo. - [GET /accounts/`email`](/docs/api-gemini-notebook-v1/get-gemini-notebook-accounts-email) devolve o uso da conta ao vivo, os horários de renovação das duas janelas e a estimativa atual para cada tipo de geração. ### Automação do Gemini Notebook (NotebookLM): n8n, Colab e assistentes de código com IA - [Template n8n](/docs/articles/notebooklm-n8n-podcast) (em inglês): transforma páginas web, vídeos do YouTube ou o feed RSS de um blog em podcasts do Gemini Notebook, é só importar. - [Notebook do Google Colab](https://colab.research.google.com/github/useapi/notebooklm-api/blob/main/notebooks/notebooklm_podcast.ipynb): informe o token e os links no navegador, ouça e baixe o podcast ali mesmo. - Assistentes de código com IA, como Claude Code e Codex, podem instalar a skill `notebooklm-podcast` do repositório e gerar um podcast com uma frase: `npx skills add useapi/notebooklm-api --skill notebooklm-podcast`. Tudo isso está no repositório [useapi/notebooklm-api](https://github.com/useapi/notebooklm-api). ### Exemplos de resultado Abaixo, resultados reais da mesma Gemini Notebook API. As fontes são a página da Wikipédia em inglês sobre a Apollo 11, um vídeo da NASA no YouTube, um texto colado e um PDF, tirados do [artigo em inglês](/docs/articles/gemini-notebook-bash#results), por isso o conteúdo está em inglês. Audio Overview, formato `brief`, duração `short`, 1 min 31 s de áudio, gerado em 4 min 36 s: <audio controls class="audio-player" style="width:100%"><source src="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-audio-overview-brief-apollo11-0929.m4a" type="audio/mp4"></audio> Video Overview, formato `explainer`, estilo `whiteboard`, 11 min 50 s no total, aqui os primeiros 90 segundos: <video poster="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-video-explainer-whiteboard-apollo11-first90s-0929-poster.jpg" controls width="100%" style="max-width:640px;border-radius:8px" src="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-video-explainer-whiteboard-apollo11-first90s-0929.mp4"></video> Infográfico vertical, estilo `sketch_note`, 1536 × 2752, gerado em 1 min 45 s: <a href="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-infographic-sketch-note-apollo11-0929.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-infographic-sketch-note-apollo11-0929.png" alt="Infográfico da Apollo 11 gerado pela Gemini Notebook API" style="width:100%;max-width:360px;border-radius:8px"></a> ### Perguntas frequentes - **O NotebookLM (Gemini Notebook) tem API oficial?** Com a useapi.net, contas comuns têm: a Gemini Notebook API da useapi.net é uma API REST de terceiros que roda na sua própria conta Google, em planos pessoais gratuitos ou pagos, e cobre todas as funções do site por $15 fixos por mês (em outubro de 2026). O Google só oferece API para o Gemini Notebook Enterprise, que exige licenças Enterprise em um projeto Google Cloud e se limita a gerenciar notebooks, adicionar fontes e gerar Audio Overviews, sem acesso para contas Google comuns. A comparação está em [Preço](#pricing). - **Preciso de uma chave da Gemini API ou da NotebookLM API?** Com a useapi.net, não. Você chama a API com o [token da API](/docs/start-here/setup-useapi) da useapi.net e conecta a conta Google uma vez pelo [fluxo automatizado](/docs/start-here/setup-gemini-notebook), em poucos minutos, sem projeto no Google Cloud. O Google não emite chave da Gemini Notebook API para contas comuns. - **Dá para gerar podcast em português?** Com a useapi.net, sim. Passe `language: "pt_BR"` em [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts), como no [exemplo acima](#quick-start). O `language` vale para áudio, vídeo (exceto `cinematic`), relatório, relatório interativo, tabela de dados, infográfico e slides, e o padrão é `en`. Você também pode definir o idioma de saída do Studio para a conta inteira com `outputLanguage` em [POST /accounts](/docs/api-gemini-notebook-v1/post-gemini-notebook-accounts). - **Existe uma Gemini Notebook (NotebookLM) API grátis?** Com a useapi.net, a Gemini Notebook API funciona em contas Google gratuitas, o Google não cobra nada do lado dele, e o Google não tem API para contas comuns. A assinatura da useapi.net custa $15 por mês (em outubro de 2026). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas, veja a [política de reembolso](/docs/legal#refund-policy). - **Funciona com uma conta Google gratuita?** Com a useapi.net, sim. O plano gratuito inicia cerca de 2 Audio Overviews por janela de 5 horas (em outubro de 2026), os planos Google AI pagos aumentam os limites, e os vídeos Cinematic exigem um plano pago. - **Quanto tempo leva para gerar um podcast?** Com a useapi.net, um Audio Overview costuma levar de 3 a 6 minutos, um Video Overview 10 minutos ou mais, infográficos e relatórios um ou dois minutos, um quiz cerca de um minuto e meio, e flashcards e tabelas de dados menos de um minuto. - **NotebookLM e Gemini Notebook são o mesmo produto?** Sim. Gemini Notebook é o nome novo do NotebookLM desde julho de 2026, e a API deste artigo é a NotebookLM API. Mais perguntas e respostas nas [perguntas frequentes da Gemini Notebook API (em inglês)](/docs/api-gemini-notebook-v1#questions). ### Conclusão Se tiver dúvidas, fale com a gente no nosso <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> servidor no Discord</a> ou no <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> canal no Telegram</a>. Todos os endpoints estão na [documentação da Gemini Notebook API](/docs/api-gemini-notebook-v1), e o código de exemplo no [repositório no GitHub](https://github.com/useapi/notebooklm-api). === URL: https://useapi.net/docs/articles/gemini-notebook-bash-th === Document URL: https://useapi.net/docs/articles/gemini-notebook-bash-th --- layout: default title: "วิธีใช้ Gemini Notebook API (NotebookLM API) เปลี่ยนเว็บ PDF และวิดีโอ YouTube เป็นพอดแคสต์ภาษาไทย" seo_title: "Gemini Notebook API (NotebookLM API): สร้างพอดแคสต์ภาษาไทยด้วย curl" description: "ใช้ Gemini Notebook API (NotebookLM API) ของ useapi.net สร้างพอดแคสต์ Audio Overview ภาษาไทยจากเว็บหรือวิดีโอ YouTube ด้วย curl ครั้งเดียว ใช้บัญชี Google ฟรีได้ ราคาคงที่ $15 ต่อเดือน" keywords: [Gemini Notebook API, NotebookLM API, NotebookLM API ภาษาไทย, NotebookLM พอดแคสต์, NotebookLM พอดแคสต์ภาษาไทย, Audio Overview API, NotebookLM Audio Overview, NotebookLM อัตโนมัติ, NotebookLM API Key, NotebookLM Python, NotebookLM Video Overview, API สร้างพอดแคสต์ AI, Gemini Notebook ภาษาไทย, สอนใช้ NotebookLM API, tutorial, code] image: https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-infographic-sketch-note-apollo11-0929.png parent: Articles nav_exclude: true lang: th date: 2026-10-04 last_modified: 2026-10-18 nav_order: 895 repo: https://github.com/useapi/notebooklm-api translation_key: gemini-notebook --- ## วิธีใช้ Gemini Notebook API (NotebookLM API) เปลี่ยนเว็บ PDF และวิดีโอ YouTube เป็นพอดแคสต์ภาษาไทย {: .no_toc #how-to-automate-gemini-notebook-notebooklm-with-the-api-deep-research-chat-audio-overviews-and-a-lot-more } อ่าน 6 นาที • 4 ตุลาคม 2026 (18 ตุลาคม 2026) useapi.net เป็น API ของบุคคลที่สาม (third-party) ไม่มีส่วนเกี่ยวข้องกับ Google และไม่ได้รับการรับรองจาก Google ## สารบัญ {: .no_toc .text-delta #table-of-contents } ### บทนำ ด้วย Gemini Notebook API (NotebookLM API) ของ [useapi.net](/docs/api-gemini-notebook-v1) คุณส่งหน้าเว็บหรือวิดีโอ YouTube ให้บัญชี Google ของคุณเองได้ด้วยการเรียก REST ครั้งเดียว แล้วรับพอดแคสต์ Audio Overview ของ Gemini Notebook เป็นไฟล์ `.m4a` และกำหนดให้พอดแคสต์เป็นภาษาไทยได้ ไม่ต้องมีโปรเจกต์ Google Cloud ไม่ต้องมี Gemini API Key และใช้บัญชี Google ฟรีได้ Google เปลี่ยนชื่อ NotebookLM เป็น [Gemini Notebook](https://notebook.google.com) แล้ว ฟังก์ชันยังเหมือนเดิม บัญชี Google ทั่วไปไม่มี API ทางการ ทุกอย่างที่ทำได้บนเว็บ API นี้ทำได้ด้วยโค้ด ทั้งสร้างโน้ตบุ๊ก เพิ่มแหล่งข้อมูล แชตพร้อมแหล่งอ้างอิง Deep Research และงานสร้างทั้งหมดใน Studio บทความนี้เขียนโดยผู้ดูแล useapi.net และพูดถึง API ที่เราให้บริการเอง โค้ดตัวอย่างเป็นโอเพนซอร์สบน [GitHub](https://github.com/useapi/notebooklm-api) ### Gemini Notebook API สร้างอะไรได้บ้าง: พอดแคสต์ Video Overview สไลด์ อินโฟกราฟิก [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts) ใช้พารามิเตอร์ `type` เลือกสิ่งที่จะสร้าง: | สิ่งที่สร้าง | `type` | ผลลัพธ์ | |---|---|---| | Audio Overview (พอดแคสต์สองคน) | `audio` เลือก `format` ได้ คือ `deep_dive` (ค่าเริ่มต้น), `brief`, `critique`, `debate` | เสียง `m4a` | | Video Overview | `video` เลือก `format` ได้ คือ `explainer` (ค่าเริ่มต้น), `brief`, `cinematic`, `short` | วิดีโอ `mp4` | | สไลด์ | `slides` | `pdf` และ `pptx` | | อินโฟกราฟิก | `infographic` | ภาพ `png` | | รายงาน รายงานแบบโต้ตอบ ตารางข้อมูล | `report`, `interactive_report`, `table` | ข้อความ Markdown หรือแถวตาราง | | แบบทดสอบ แฟลชการ์ด แผนผังความคิด | `quiz`, `flashcards`, `mindmap` | JSON | เสียง วิดีโอ (ยกเว้น `cinematic`) รายงาน รายงานแบบโต้ตอบ ตารางข้อมูล สไลด์ และอินโฟกราฟิก กำหนดภาษาผลลัพธ์ได้ด้วย `language` ภาษาไทยคือ `th` ### ราคา Gemini Notebook API (NotebookLM API) จ่ายให้ useapi.net ราคาคงที่ [$15 ต่อเดือน](/docs/subscription) การสมัครครั้งเดียวครอบคลุม API ทุกตัวของ useapi.net ไม่ใช่แค่ Gemini Notebook การสมัครหนึ่งครั้งเชื่อมบัญชี Google ได้ 3 บัญชี และเพิ่มได้สูงสุด 100 บัญชี งานสร้างทำบนบัญชี Google ของคุณเอง เราไม่คิดเงินตามครั้งหรือตามพอดแคสต์ การใช้งานฝั่ง Google รวมอยู่ในแพ็กเกจที่บัญชีมีอยู่แล้ว แพ็กเกจฟรีก็ใช้ได้ | | Gemini Notebook API ของ useapi.net | [Gemini Notebook Enterprise API](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks) ของ Google | |---|:-:|:-:| | บัญชี | บัญชี Google ของคุณเอง แพ็กเกจฟรีหรือเสียเงินก็ได้ | ไลเซนส์ Enterprise ในโปรเจกต์ Google Cloud | | ราคา | คงที่ $15 ต่อเดือน | ซื้อไลเซนส์ Enterprise ต่อผู้ใช้ | | แชตพร้อมแหล่งอ้างอิง | Yes | No | | Deep Research | Yes | No | | Audio Overview | Yes | Yes | | Video Overview สไลด์ อินโฟกราฟิก รายงาน แบบทดสอบ แฟลชการ์ด แผนผังความคิด | Yes | No | | สถานะ | ทดลอง | Preview (Pre-GA) | Google กำหนดโควตาการใช้งานต่อบัญชี รีเฟรชทุก 5 ชั่วโมง และมีโควตารายสัปดาห์อีกชั้น ตามตัวเลขประมาณของ Google เอง รอบ 5 ชั่วโมงเต็มเริ่ม Audio Overview ได้อย่างน้อย 2 รายการ (แพ็กเกจฟรี), 9 รายการ (Google AI Pro) หรือ 181 รายการ (Google AI Ultra) และเมื่อทำเสร็จจริงมักใช้โควตาน้อยกว่าที่ประมาณไว้ ถ้าต้องการผลงานมากขึ้น ก็เชื่อมบัญชีเพิ่ม ดูที่[การขยายขนาด](#scale) ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. ### เตรียมตัว 1. สมัคร useapi.net และรับ [API Token](/docs/start-here/setup-useapi) ตัวอย่างด้านล่างทั้งหมดถือว่าเก็บไว้ในตัวแปรสภาพแวดล้อม `USEAPI_TOKEN` 2. เชื่อมบัญชี Google ด้วย[ขั้นตอนเบราว์เซอร์อัตโนมัติ](/docs/start-here/setup-gemini-notebook): ใส่ Token แล้วล็อกอิน Google ในเบราว์เซอร์ระยะไกล ไม่ต้องคัดลอกคุกกี้เอง แนะนำให้ใช้[บัญชี Gmail แยกสำหรับงานนี้](/docs/start-here/setup-gemini-notebook#use-a-dedicated-gmail-account) ไม่ใช่บัญชีหลักส่วนตัว คำขอแบบครั้งเดียวและการสร้างโน้ตบุ๊กใหม่ด้านล่างไม่ต้องใส่ `email` ก็ได้ ถ้าเชื่อมไว้บัญชีเดียว API จะใช้บัญชีนั้น ถ้าเชื่อมหลายบัญชี API จะเลือกบัญชีที่ว่างให้ การเรียกที่อิงโน้ตบุ๊กจะทำงานบนบัญชีเจ้าของโน้ตบุ๊กนั้นเสมอ ### สร้างพอดแคสต์ภาษาไทยจาก Gemini Notebook ด้วยการเรียก API ครั้งเดียว ไม่ต้องสร้างโน้ตบุ๊กก่อน ส่ง `urls` (หรือข้อความที่วางไว้ใน `text`) ไปที่ [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts#one-shot-requests) ได้เลย API จะสร้างโน้ตบุ๊กใหม่บนบัญชีหนึ่งของคุณ เพิ่มแหล่งข้อมูล รอให้ประมวลผลเสร็จ แล้วเริ่มสร้าง ลิงก์ `youtube.com` และ `youtu.be` จะถูกเพิ่มเป็นแหล่งข้อมูล YouTube ส่งได้สูงสุด 50 ลิงก์ต่อครั้ง ```bash JOBID=$(curl -s -X POST "https://api.useapi.net/v1/gemini-notebook/artifacts" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "type": "audio", "format": "brief", "length": "short", "language": "th", "urls": ["https://th.wikipedia.org/wiki/อะพอลโล_11"], "title": "พอดแคสต์อะพอลโล 11", "mode": "async" }' | jq -r '.jobid') ``` `mode: "async"` จะตอบกลับ `201` พร้อม `jobid` ทันที ส่วนค่าเริ่มต้น `mode: "sync"` รอได้นานสุด 90 วินาที แต่พอดแคสต์มักใช้เวลาหลายนาที จึงจะได้ `202` กลับมาก่อน แล้วก็ต้องตรวจสถานะเหมือนกัน ### ตรวจสถานะงานและดาวน์โหลด เรียก [GET /jobs/`jobid`](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid) จนกว่า `status` จะเป็น `completed` หรือ `failed` ใน `jobid` มี `:` และ `@` จึงต้องเข้ารหัสก่อนใส่ใน URL เมื่องานเสร็จ `result.files[].url` จะชี้ไปที่ [GET /artifacts/download](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts-download) ซึ่งต้องแนบ API Token ตอนดาวน์โหลดด้วย ฟังก์ชันนี้จะใช้ซ้ำในส่วนถัดไป: ```bash API=https://api.useapi.net/v1/gemini-notebook enc() { jq -rn --arg v "$1" '$v|@uri'; } wait_job() { [ -z "$1" ] || [ "$1" = "null" ] && { echo "ส่งงานไม่สำเร็จ ดู error ในคำตอบ"; return 1; } until curl -s "$API/jobs/$(enc "$1")" -H "Authorization: Bearer $USEAPI_TOKEN" > job.json && jq -e '.status == "completed" or .status == "failed"' job.json > /dev/null; do sleep 15 done jq '{status, title: .result.title, duration: .result.duration, error}' job.json jq -r '.result.files[]?.url' job.json | while read -r url; do curl -s -OJ -H "Authorization: Bearer $USEAPI_TOKEN" "$url" done } wait_job "$JOBID" ``` เรารันคำขอแบบเดียวกันนี้เมื่อ 4 ตุลาคม 2026 โดยใช้ภาษาจีน (`zh_Hans`) และหน้าวิกิพีเดียภาษาจีน งานเสร็จในราว 6 นาที Google สร้างพอดแคสต์ยาว 99 วินาที และ `-OJ` บันทึกไฟล์ `.m4a` ตามชื่อเรื่องที่ Google ตั้งให้ - งานที่ล้มเหลวจะมี `error.code` เช่น `quota` (โควตาไม่พอ), `sources` (ใช้แหล่งข้อมูลไม่ได้เลย) หรือ `generation_failed` - ถ้าไม่อยากตรวจสถานะเอง ให้ส่ง `replyUrl` ในคำขอ เมื่องานจบจะได้รับ `POST` หนึ่งครั้ง ซึ่งมีข้อมูลงานครบทั้งหมด - ไฟล์ที่สร้างยังอยู่ในโน้ตบุ๊ก ลิงก์ดาวน์โหลดใช้ได้ตราบที่โน้ตบุ๊กและผลงานยังอยู่ ### ขั้นตอนเต็ม: โน้ตบุ๊ก แหล่งข้อมูล และการสร้าง ถ้าต้องการสร้างหลายอย่างจากแหล่งข้อมูลชุดเดียวกัน หรือต้องอัปโหลดไฟล์ในเครื่อง ให้สร้างโน้ตบุ๊กก่อน แหล่งข้อมูลเป็นหน้าเว็บ วิดีโอ YouTube ข้อความที่วางไว้ ไฟล์ Google Drive หรือไฟล์ที่อัปโหลด เช่น PDF, Word, PowerPoint, EPUB เสียง และวิดีโอ ก็ได้ ```bash # 1. สร้างโน้ตบุ๊กใหม่ NOTEBOOK=$(curl -s -X POST "$API/notebooks" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{"title": "อะพอลโล 11"}' | jq -r '.notebook') # 2. เพิ่มหน้าเว็บและวิดีโอ YouTube curl -s -X POST "$API/sources" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d "$(jq -n --arg nb "$NOTEBOOK" '{ notebook: $nb, urls: ["https://th.wikipedia.org/wiki/อะพอลโล_11", "https://www.youtube.com/watch?v=xUcYQ7slmRw"] }')" # 3. อัปโหลด PDF โดยตัวไฟล์คือ body ของคำขอ curl -s -X POST "$API/sources/upload?notebook=$(enc "$NOTEBOOK")&name=report.pdf" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/pdf" \ --data-binary @report.pdf # 4. รอให้แหล่งข้อมูลทั้งหมดประมวลผลเสร็จ until curl -s "$API/notebooks/$(enc "$NOTEBOOK")" -H "Authorization: Bearer $USEAPI_TOKEN" > notebook.json && jq -e '[.sources[].status] | all(. == "ready" or . == "error")' notebook.json > /dev/null; do sleep 10 done # 5. สร้างอินโฟกราฟิกภาษาไทย JOBID=$(curl -s -X POST "$API/artifacts" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d "$(jq -n --arg nb "$NOTEBOOK" '{notebook: $nb, type: "infographic", orientation: "portrait", language: "th", mode: "async"}')" \ | jq -r '.jobid') wait_job "$JOBID" ``` ตอนทดสอบจริง (ผลลัพธ์ภาษาจีน) แหล่งข้อมูลทั้งสามพร้อมในราว 30 วินาที อินโฟกราฟิกแนวตั้งใช้เวลาสร้างราว 2 นาที ได้ไฟล์ `png` ขนาด 1536 × 2752 เปลี่ยน `type` ในขั้นที่ 5 เป็น `audio`, `video` หรือ `slides` ก็สร้างพอดแคสต์ Video Overview หรือสไลด์ต่อจากโน้ตบุ๊กเดิมได้ ตัวอย่างเต็ม 19 ขั้น (รวมแชต Deep Research และการแก้สไลด์ทีละหน้า) อยู่ใน[บทความภาษาอังกฤษ](/docs/articles/gemini-notebook-bash) ### ตัวอย่าง Python แทบเหมือนคำขอแบบครั้งเดียวด้านบน (ไม่ได้กำหนด `length` จึงใช้ความยาวเริ่มต้น) เขียนด้วย Python และ `requests`: ```python import os, time, requests from urllib.parse import quote API = 'https://api.useapi.net/v1/gemini-notebook' H = {'Authorization': f"Bearer {os.environ['USEAPI_TOKEN']}"} r = requests.post(f'{API}/artifacts', headers=H, json={ 'type': 'audio', 'format': 'brief', 'language': 'th', 'urls': ['https://th.wikipedia.org/wiki/อะพอลโล_11'], 'mode': 'async', }) r.raise_for_status() job = r.json() while job['status'] in ('pending', 'processing'): time.sleep(15) r = requests.get(f"{API}/jobs/{quote(job['jobid'], safe='')}", headers=H) r.raise_for_status() job = r.json() if job['status'] == 'failed': raise SystemExit(job['error']) print(job['result']['title'], job['result']['duration'], 'วินาที') for f in job['result']['files']: with open(f"podcast.{f['format']}", 'wb') as out: out.write(requests.get(f['url'], headers=H).content) ``` ตอนเรารันสคริปต์นี้ด้วยภาษาจีน ใช้เวลาราว 6 นาทีครึ่ง ได้พอดแคสต์ `podcast.m4a` ยาว 70 วินาที สคริปต์ Node.js และ Python สำหรับประมวลผลรายการลิงก์ทีละชุดอยู่ในโฟลเดอร์ `podcast/` ของ[รีโพตัวอย่างบน GitHub](https://github.com/useapi/notebooklm-api) ### การขยายขนาด: หลายบัญชีและการจำกัดอัตรา API นี้ทำงานได้เองโดยไม่ต้องมีคนเฝ้า: - เมื่อเชื่อมหลายบัญชี Google งานใหม่แต่ละงานจะถูกส่งไปยังบัญชีที่สถานะปกติ มีช่องงานว่าง และยังมีโควตาสำหรับงานประเภทนั้นเหลือ คุณไม่ต้องคอยดูโควตา 5 ชั่วโมงและรายสัปดาห์เอง - แต่ละบัญชีรันงานพร้อมกันได้สูงสุด `maxJobs` งาน (ค่าเริ่มต้น 3 ตั้งได้ 1–10 แก้ด้วย [POST /accounts](/docs/api-gemini-notebook-v1/post-gemini-notebook-accounts)) [GET /jobs](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs) แสดงงานที่กำลังรันในแต่ละบัญชี - เมื่อทุกบัญชีไม่ว่างหรือโควตาไม่พอ การเรียกจะได้ `429` ถ้า Google บอกเวลารีเซ็ต คำตอบจะมี `retryAt` โค้ดของคุณรอจนถึงเวลานั้นแล้วลองใหม่ได้ หรือใช้ `email` ส่งชุดถัดไปไปยังบัญชีอื่น หรือลดความถี่ลง - [GET /accounts/`email`](/docs/api-gemini-notebook-v1/get-gemini-notebook-accounts-email) แสดงการใช้งานปัจจุบันของบัญชี เวลารีเซ็ตของทั้งสองรอบ และตัวเลขประมาณของงานแต่ละประเภท ### ทำ Gemini Notebook (NotebookLM) อัตโนมัติ: n8n, Colab และผู้ช่วยเขียนโค้ด AI - [เทมเพลต n8n](/docs/articles/notebooklm-n8n-podcast): เปลี่ยนหน้าเว็บ วิดีโอ YouTube หรือฟีด RSS ของบล็อกเป็นพอดแคสต์ Gemini Notebook นำเข้าแล้วใช้ได้ทันที - [โน้ตบุ๊ก Google Colab](https://colab.research.google.com/github/useapi/notebooklm-api/blob/main/notebooks/notebooklm_podcast.ipynb): ใส่ Token และลิงก์ในเบราว์เซอร์ แล้วฟังและดาวน์โหลดพอดแคสต์ได้เลย - ผู้ช่วยเขียนโค้ด AI อย่าง Claude Code และ Codex ติดตั้งสกิล `notebooklm-podcast` จากรีโพได้ แล้วสร้างพอดแคสต์ด้วยประโยคเดียว: `npx skills add useapi/notebooklm-api --skill notebooklm-podcast` ทั้งหมดนี้อยู่ในรีโพ [useapi/notebooklm-api](https://github.com/useapi/notebooklm-api) ### ตัวอย่างผลลัพธ์ ด้านล่างคือผลลัพธ์จริงจาก Gemini Notebook API ตัวเดียวกันนี้ แหล่งข้อมูลคือหน้าวิกิพีเดียภาษาอังกฤษเรื่อง Apollo 11 วิดีโอ YouTube ของ NASA ข้อความที่วางไว้ และ PDF หนึ่งไฟล์ นำมาจาก[บทความภาษาอังกฤษ](/docs/articles/gemini-notebook-bash#results) เนื้อหาจึงเป็นภาษาอังกฤษ Audio Overview รูปแบบ `brief` ความยาว `short` ยาว 1 นาที 31 วินาที ใช้เวลาสร้าง 4 นาที 36 วินาที: <audio controls class="audio-player" style="width:100%"><source src="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-audio-overview-brief-apollo11-0929.m4a" type="audio/mp4"></audio> Video Overview รูปแบบ `explainer` สไตล์ `whiteboard` ยาวเต็ม 11 นาที 50 วินาที ตรงนี้คือ 90 วินาทีแรก: <video poster="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-video-explainer-whiteboard-apollo11-first90s-0929-poster.jpg" controls width="100%" style="max-width:640px;border-radius:8px" src="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-video-explainer-whiteboard-apollo11-first90s-0929.mp4"></video> อินโฟกราฟิกแนวตั้ง สไตล์ `sketch_note` ขนาด 1536 × 2752 ใช้เวลาสร้าง 1 นาที 45 วินาที: <a href="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-infographic-sketch-note-apollo11-0929.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-infographic-sketch-note-apollo11-0929.png" alt="อินโฟกราฟิก Apollo 11 ที่สร้างด้วย Gemini Notebook API" style="width:100%;max-width:360px;border-radius:8px"></a> ### คำถามที่พบบ่อย - **NotebookLM (Gemini Notebook) มี API ทางการไหม?** ผ่าน useapi.net บัญชีทั่วไปใช้ได้ Gemini Notebook API ของ useapi.net เป็น REST API ของบุคคลที่สาม ทำงานบนบัญชี Google ของคุณเอง ทั้งแพ็กเกจส่วนตัวฟรีและเสียเงิน และครอบคลุมทุกฟังก์ชันบนเว็บ ในราคาคงที่ $15 ต่อเดือน (ข้อมูล ณ ตุลาคม 2026) Google มี API ให้เฉพาะ Gemini Notebook Enterprise ต้องซื้อไลเซนส์ Enterprise ในโปรเจกต์ Google Cloud และทำได้แค่จัดการโน้ตบุ๊ก เพิ่มแหล่งข้อมูล และสร้าง Audio Overview บัญชี Google ทั่วไปใช้ไม่ได้ ดูการเปรียบเทียบที่[ราคา](#pricing) - **ต้องมี Gemini API Key หรือ NotebookLM API Key ไหม?** ผ่าน useapi.net ไม่ต้อง คุณเรียก API ด้วย [API Token](/docs/start-here/setup-useapi) ของ useapi.net แล้วเชื่อมบัญชี Google ครั้งเดียวผ่าน[ขั้นตอนอัตโนมัติ](/docs/start-here/setup-gemini-notebook) ใช้เวลาไม่กี่นาที ไม่ต้องมีโปรเจกต์ Google Cloud และ Google ไม่ออก Gemini Notebook API Key ให้บัญชีทั่วไป - **สร้างพอดแคสต์ภาษาไทยได้ไหม?** ผ่าน useapi.net ได้ ส่ง `language: "th"` ใน [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts) ตาม[ตัวอย่างด้านบน](#quick-start) `language` ใช้ได้กับเสียง วิดีโอ (ยกเว้น `cinematic`) รายงาน รายงานแบบโต้ตอบ ตารางข้อมูล อินโฟกราฟิก และสไลด์ ค่าเริ่มต้นคือ `en` หรือตั้งภาษาผลลัพธ์ของ Studio ทั้งบัญชีด้วย `outputLanguage` ใน [POST /accounts](/docs/api-gemini-notebook-v1/post-gemini-notebook-accounts) - **มี Gemini Notebook (NotebookLM) API ฟรีไหม?** ผ่าน useapi.net Gemini Notebook API ใช้กับบัญชี Google ฟรีได้ ฝั่ง Google ไม่คิดเงิน และ Google ไม่มี API สำหรับบัญชีทั่วไป การสมัคร useapi.net ราคา $15 ต่อเดือน (ข้อมูล ณ ตุลาคม 2026) ถ้าจ่ายผ่าน Stripe และสร้างสำเร็จไม่ถึง 50 ครั้งภายใน 14 วันแรกของการซื้อครั้งแรก ขอคืนเงินเต็มจำนวนได้ ดู[นโยบายการคืนเงิน](/docs/legal#refund-policy) - **บัญชี Google ฟรีใช้ได้ไหม?** ผ่าน useapi.net ได้ แพ็กเกจฟรีเริ่ม Audio Overview ได้ราว 2 รายการต่อรอบ 5 ชั่วโมง (ข้อมูล ณ ตุลาคม 2026) แพ็กเกจ Google AI แบบเสียเงินเพิ่มลิมิตให้สูงขึ้น และวิดีโอ Cinematic ต้องใช้แพ็กเกจเสียเงิน - **สร้างพอดแคสต์หนึ่งรายการใช้เวลานานแค่ไหน?** ผ่าน useapi.net Audio Overview มักใช้ 3–6 นาที Video Overview 10 นาทีขึ้นไป อินโฟกราฟิกและรายงานหนึ่งถึงสองนาที แบบทดสอบราวหนึ่งนาทีครึ่ง แฟลชการ์ดและตารางข้อมูลไม่ถึงหนึ่งนาที - **NotebookLM กับ Gemini Notebook เป็นผลิตภัณฑ์เดียวกันไหม?** ใช่ Gemini Notebook คือชื่อใหม่ของ NotebookLM ตั้งแต่กรกฎาคม 2026 API ในบทความนี้ก็คือ NotebookLM API คำถามเพิ่มเติมดูที่[คำถามที่พบบ่อยของ Gemini Notebook API (ภาษาอังกฤษ)](/docs/api-gemini-notebook-v1#questions) ### สรุป มีคำถามเข้ามาคุยกับเราได้ที่ <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> เซิร์ฟเวอร์ Discord</a> หรือ <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> ช่อง Telegram</a> ดู endpoint ทั้งหมดได้ที่[เอกสาร Gemini Notebook API](/docs/api-gemini-notebook-v1) และโค้ดตัวอย่างที่[รีโพ GitHub](https://github.com/useapi/notebooklm-api) === URL: https://useapi.net/docs/articles/gemini-notebook-bash-vi === Document URL: https://useapi.net/docs/articles/gemini-notebook-bash-vi --- layout: default title: "Cách dùng Gemini Notebook API (NotebookLM API) biến trang web, PDF và video YouTube thành podcast" description: "Gemini Notebook API (NotebookLM API) qua useapi.net: một lệnh curl biến trang web hoặc video YouTube thành podcast Audio Overview, dùng được với tài khoản Google miễn phí, phí cố định $15/tháng." keywords: [NotebookLM API, Gemini Notebook API, NotebookLM podcast, tạo podcast bằng NotebookLM, NotebookLM tiếng Việt, Audio Overview API, NotebookLM Audio Overview, NotebookLM có API không, NotebookLM API key, tự động hóa NotebookLM, NotebookLM Python, NotebookLM Video Overview, API tạo podcast AI, biến PDF thành podcast, biến video YouTube thành podcast, hướng dẫn, tutorial, code] image: https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-infographic-sketch-note-apollo11-0929.png parent: Articles nav_exclude: true lang: vi translation_key: gemini-notebook date: 2026-10-04 last_modified: 2026-10-18 nav_order: 895 repo: https://github.com/useapi/notebooklm-api --- ## Cách dùng Gemini Notebook API (NotebookLM API) biến trang web, PDF và video YouTube thành podcast {: #如何用-gemini-notebook-apinotebooklm-api把网页pdf-和-youtube-视频变成中文播客中文教程 .no_toc } 6 phút đọc • 4 tháng 10 năm 2026 (18 tháng 10 năm 2026) useapi.net là API của bên thứ ba, không liên kết với Google và không được Google bảo trợ. ## Mục lục {: #目录 .no_toc .text-delta } ### Giới thiệu Với Gemini Notebook API (NotebookLM API) của [useapi.net](/docs/api-gemini-notebook-v1), một lệnh gọi REST đưa trang web hoặc video YouTube vào tài khoản Google của chính bạn, tạo podcast Audio Overview của Gemini Notebook và tải về file `.m4a`, với ngôn ngữ podcast do bạn chọn. Không cần dự án Google Cloud, không cần Gemini API key, và tài khoản Google miễn phí cũng dùng được. Google đã đổi tên NotebookLM thành [Gemini Notebook](https://notebook.google.com), tính năng giữ nguyên. Tài khoản Google thông thường không có API chính thức. Những gì bản web làm được, API này đều làm được bằng code: tạo notebook, thêm nguồn, hỏi đáp có trích dẫn nguồn, Deep Research, và toàn bộ tính năng tạo nội dung trong Studio. Bài này do đội ngũ duy trì useapi.net viết, giới thiệu API được host của chính chúng tôi, và code ví dụ là mã nguồn mở trên [GitHub](https://github.com/useapi/notebooklm-api). ### Gemini Notebook API tạo được gì: podcast, Video Overview, slide, infographic [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts) chọn nội dung cần tạo bằng tham số `type`: | Nội dung | `type` | Trả về | |---|---|---| | Audio Overview (podcast hai người) | `audio`, `format` chọn `deep_dive` (mặc định), `brief`, `critique`, `debate` | âm thanh `m4a` | | Video Overview | `video`, `format` chọn `explainer` (mặc định), `brief`, `cinematic`, `short` | video `mp4` | | Slide | `slides` | `pdf` và `pptx` | | Infographic | `infographic` | ảnh `png` | | Báo cáo, báo cáo tương tác, bảng dữ liệu | `report`, `interactive_report`, `table` | văn bản Markdown hoặc các hàng bảng | | Câu đố, thẻ ghi nhớ, sơ đồ tư duy | `quiz`, `flashcards`, `mindmap` | JSON | Âm thanh, video (trừ `cinematic`), báo cáo, báo cáo tương tác, bảng dữ liệu, slide và infographic đều có thể chọn ngôn ngữ đầu ra bằng `language`. Các ví dụ dưới đây dùng tiếng Trung giản thể, `zh_Hans`, đúng như lúc chúng tôi chạy thử. Trường này nhận mã ngôn ngữ như `en`, `es`, `pt_BR` hoặc `zh_Hans`, nên với tiếng Việt hãy dùng `vi`. ### Giá Gemini Notebook API (NotebookLM API) Bạn trả useapi.net phí cố định [$15 mỗi tháng](/docs/subscription), và cùng gói đăng ký đó dùng được mọi API của useapi.net, không chỉ Gemini Notebook. Mỗi gói đăng ký kết nối được 3 tài khoản Google, tổng cộng tối đa 100. Nội dung được tạo trên chính tài khoản Google của bạn, chúng tôi không tính phí theo lượt hay theo file âm thanh, và mức dùng phía Google nằm trong gói hiện có của tài khoản, kể cả gói miễn phí. | | Gemini Notebook API của useapi.net | [Gemini Notebook Enterprise API](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks) của Google | |---|:-:|:-:| | Tài khoản | Tài khoản Google của bạn, gói miễn phí hay trả phí đều được | Giấy phép Enterprise trong một dự án Google Cloud | | Giá | Cố định $15 mỗi tháng | Mua giấy phép Enterprise theo người dùng | | Hỏi đáp có trích dẫn nguồn | Yes | No | | Deep Research | Yes | No | | Audio Overview | Yes | Yes | | Video Overview, slide, infographic, báo cáo, câu đố, thẻ ghi nhớ, sơ đồ tư duy | Yes | No | | Trạng thái | Thử nghiệm | Preview (Pre-GA) | Google đặt ngân sách sử dụng theo từng tài khoản, nạp lại mỗi 5 giờ, kèm một ngân sách hằng tuần. Theo ước tính của chính Google, một khung 5 giờ đầy đủ bắt đầu được ít nhất 2 (gói miễn phí), 9 (Google AI Pro) hoặc 181 (Google AI Ultra) Audio Overview, và thực tế khi xong thường tốn ít hơn ước tính. Cần nhiều hơn thì kết nối thêm tài khoản, xem [Mở rộng quy mô](#scale). ### Chuẩn bị 1. Đăng ký useapi.net và lấy [API token](/docs/start-here/setup-useapi). Các ví dụ dưới đây giả định token nằm trong biến môi trường `USEAPI_TOKEN`. 2. Kết nối tài khoản Google bằng [quy trình trình duyệt tự động](/docs/start-here/setup-gemini-notebook): nhập token, rồi đăng nhập Google trong trình duyệt từ xa, không cần tự chép cookie. Nên dùng [một tài khoản Gmail riêng](/docs/start-here/setup-gemini-notebook#use-a-dedicated-gmail-account), không dùng tài khoản cá nhân chính. Request một lần và việc tạo notebook mới bên dưới đều có thể bỏ `email`: khi chỉ kết nối một tài khoản thì API dùng tài khoản đó, khi kết nối nhiều tài khoản thì API chọn tài khoản đang rảnh. Các lệnh gọi dựa trên notebook luôn chạy trên tài khoản sở hữu notebook đó. ### Cách tạo podcast Gemini Notebook bằng một lệnh gọi API Không cần tạo notebook trước. Gửi thẳng `urls` (hoặc `text` dán vào) tới [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts#one-shot-requests), API sẽ tạo notebook mới trên một tài khoản của bạn, thêm nguồn, chờ nguồn xử lý xong rồi bắt đầu tạo. Liên kết `youtube.com` và `youtu.be` được thêm dưới dạng nguồn YouTube, tối đa 50 liên kết một lần. ```bash JOBID=$(curl -s -X POST "https://api.useapi.net/v1/gemini-notebook/artifacts" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "type": "audio", "format": "brief", "length": "short", "language": "zh_Hans", "urls": ["https://zh.wikipedia.org/wiki/阿波罗11号"], "title": "阿波罗11号播客", "mode": "async" }' | jq -r '.jobid') ``` `mode: "async"` trả về ngay `201` và `jobid`. `mode: "sync"` mặc định chờ tối đa 90 giây, mà podcast thường cần vài phút, nên sẽ trả về `202` trước và sau đó vẫn phải polling. ### Polling job và tải về Gọi [GET /jobs/`jobid`](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid) cho tới khi `status` thành `completed` hoặc `failed`. `jobid` chứa `:` và `@`, nên phải mã hóa trước khi đưa vào đường dẫn URL. Khi xong, `result.files[].url` trỏ tới [GET /artifacts/download](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts-download), và khi tải cũng phải kèm API token. Hàm dưới đây sẽ còn được dùng lại: ```bash API=https://api.useapi.net/v1/gemini-notebook enc() { jq -rn --arg v "$1" '$v|@uri'; } wait_job() { [ -z "$1" ] || [ "$1" = "null" ] && { echo "Gửi job thất bại, hãy xem error trong phản hồi"; return 1; } until curl -s "$API/jobs/$(enc "$1")" -H "Authorization: Bearer $USEAPI_TOKEN" > job.json && jq -e '.status == "completed" or .status == "failed"' job.json > /dev/null; do sleep 15 done jq '{status, title: .result.title, duration: .result.duration, error}' job.json jq -r '.result.files[]?.url' job.json | while read -r url; do curl -s -OJ -H "Authorization: Bearer $USEAPI_TOKEN" "$url" done } wait_job "$JOBID" ``` Chúng tôi chạy request trên ngày 4 tháng 10 năm 2026: job xong sau khoảng 6 phút, Google tạo một podcast tiếng Trung dài 99 giây với tiêu đề 「阿波罗登月惊魂」, và `-OJ` lưu file theo tiêu đề đó thành `阿波罗登月惊魂.m4a`. - Job lỗi có `error.code`, ví dụ `quota` (không đủ hạn mức), `sources` (không nguồn nào dùng được) hoặc `generation_failed`. - Không muốn polling thì truyền `replyUrl` trong request, khi job kết thúc bạn sẽ nhận một lệnh `POST` chứa toàn bộ bản ghi job. - File đã tạo nằm lại trong notebook, và liên kết tải về còn dùng được chừng nào notebook và kết quả còn tồn tại. ### Quy trình đầy đủ: notebook, nguồn và tạo nội dung Muốn tạo nhiều loại nội dung từ cùng một nhóm nguồn, hoặc tải file trên máy lên, hãy tạo notebook trước. Nguồn có thể là trang web, video YouTube, văn bản dán vào, file Google Drive, và file tải lên như PDF, Word, PowerPoint, EPUB, âm thanh, video. ```bash # 1. Tạo notebook mới NOTEBOOK=$(curl -s -X POST "$API/notebooks" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{"title": "阿波罗11号"}' | jq -r '.notebook') # 2. Thêm trang web và video YouTube curl -s -X POST "$API/sources" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d "$(jq -n --arg nb "$NOTEBOOK" '{ notebook: $nb, urls: ["https://zh.wikipedia.org/wiki/阿波罗11号", "https://www.youtube.com/watch?v=xUcYQ7slmRw"] }')" # 3. Tải PDF lên, chính file là body của request curl -s -X POST "$API/sources/upload?notebook=$(enc "$NOTEBOOK")&name=report.pdf" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/pdf" \ --data-binary @report.pdf # 4. Chờ mọi nguồn xử lý xong until curl -s "$API/notebooks/$(enc "$NOTEBOOK")" -H "Authorization: Bearer $USEAPI_TOKEN" > notebook.json && jq -e '[.sources[].status] | all(. == "ready" or . == "error")' notebook.json > /dev/null; do sleep 10 done # 5. Tạo infographic tiếng Trung JOBID=$(curl -s -X POST "$API/artifacts" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d "$(jq -n --arg nb "$NOTEBOOK" '{notebook: $nb, type: "infographic", orientation: "portrait", language: "zh_Hans", mode: "async"}')" \ | jq -r '.jobid') wait_job "$JOBID" ``` Khi chạy thử, ba nguồn sẵn sàng sau khoảng 30 giây, và infographic tiếng Trung khổ dọc được tạo trong khoảng 2 phút, ra một file `png` 1536 × 2752 với tiêu đề 「阿波罗11号登月信息图」. Đổi `type` ở bước 5 thành `audio`, `video` hoặc `slides` là tạo tiếp podcast, Video Overview hoặc slide trên cùng notebook. Bản trình diễn đầy đủ 19 bước (gồm hỏi đáp, Deep Research và sửa một trang slide) có trong [bài hướng dẫn tiếng Anh](/docs/articles/gemini-notebook-bash). ### Ví dụ Python Gần giống request một lần ở trên (không chỉ định `length`, dùng độ dài mặc định), viết bằng Python và `requests`: ```python import os, time, requests from urllib.parse import quote API = 'https://api.useapi.net/v1/gemini-notebook' H = {'Authorization': f"Bearer {os.environ['USEAPI_TOKEN']}"} r = requests.post(f'{API}/artifacts', headers=H, json={ 'type': 'audio', 'format': 'brief', 'language': 'zh_Hans', 'urls': ['https://zh.wikipedia.org/wiki/阿波罗11号'], 'mode': 'async', }) r.raise_for_status() job = r.json() while job['status'] in ('pending', 'processing'): time.sleep(15) r = requests.get(f"{API}/jobs/{quote(job['jobid'], safe='')}", headers=H) r.raise_for_status() job = r.json() if job['status'] == 'failed': raise SystemExit(job['error']) print(job['result']['title'], job['result']['duration'], 'giây') for f in job['result']['files']: with open(f"podcast.{f['format']}", 'wb') as out: out.write(requests.get(f['url'], headers=H).content) ``` Khi chạy thử, script này mất khoảng 6 phút rưỡi và cho ra một podcast tiếng Trung dài 70 giây, `podcast.m4a`. Script Node.js và Python xử lý hàng loạt danh sách liên kết có trong thư mục `podcast/` của [repo ví dụ trên GitHub](https://github.com/useapi/notebooklm-api). ### Mở rộng quy mô: nhiều tài khoản và giới hạn tốc độ API này chạy được mà không cần người trông: - Khi đã kết nối nhiều tài khoản Google, mỗi job mới được giao cho tài khoản có trạng thái tốt, còn slot job trống và còn đủ hạn mức cho loại nội dung đó, nên bạn không phải tự theo dõi ngân sách 5 giờ và hằng tuần. - Mỗi tài khoản chạy đồng thời tối đa `maxJobs` job (mặc định 3, đặt được từ 1–10, đổi bằng [POST /accounts](/docs/api-gemini-notebook-v1/post-gemini-notebook-accounts)). [GET /jobs](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs) hiển thị các job đang chạy trên từng tài khoản. - Khi mọi tài khoản đều bận hoặc hết hạn mức, lệnh gọi trả về `429`. Nếu Google cho biết thời điểm nạp lại, phản hồi kèm `retryAt`, và code của bạn có thể chờ tới lúc đó rồi thử lại, dùng `email` để gửi đợt tiếp theo sang tài khoản khác, hoặc giảm tần suất. - [GET /accounts/`email`](/docs/api-gemini-notebook-v1/get-gemini-notebook-accounts-email) trả về mức dùng trực tiếp của tài khoản, thời điểm nạp lại của hai khung, và ước tính hiện tại cho từng loại nội dung. ### Tự động hóa Gemini Notebook (NotebookLM): n8n, Colab và trợ lý lập trình AI - [Template n8n](/docs/articles/notebooklm-n8n-podcast): biến trang web, video YouTube hoặc RSS của blog thành podcast Gemini Notebook, nhập vào là dùng được. - [Google Colab notebook](https://colab.research.google.com/github/useapi/notebooklm-api/blob/main/notebooks/notebooklm_podcast.ipynb): điền token và liên kết ngay trong trình duyệt, rồi nghe và tải podcast về. - Các trợ lý lập trình AI như Claude Code, Codex có thể cài skill `notebooklm-podcast` trong repo để tạo podcast bằng một câu lệnh: `npx skills add useapi/notebooklm-api --skill notebooklm-podcast`. Tất cả đều nằm trong repo [useapi/notebooklm-api](https://github.com/useapi/notebooklm-api). ### Ví dụ kết quả Dưới đây là kết quả thật tạo qua cùng Gemini Notebook API này, từ nguồn là trang Wikipedia tiếng Anh về Apollo 11, một video YouTube của NASA, một đoạn văn bản dán vào và một file PDF, lấy từ [bài hướng dẫn tiếng Anh](/docs/articles/gemini-notebook-bash#results), nên nội dung bằng tiếng Anh. Audio Overview, định dạng `brief`, độ dài `short`, dài 1 phút 31 giây, tạo trong 4 phút 36 giây: <audio controls class="audio-player" style="width:100%"><source src="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-audio-overview-brief-apollo11-0929.m4a" type="audio/mp4"></audio> Video Overview, định dạng `explainer`, phong cách `whiteboard`, dài đầy đủ 11 phút 50 giây, đây là 90 giây đầu: <video poster="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-video-explainer-whiteboard-apollo11-first90s-0929-poster.jpg" controls width="100%" style="max-width:640px;border-radius:8px" src="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-video-explainer-whiteboard-apollo11-first90s-0929.mp4"></video> Infographic, khổ dọc, phong cách `sketch_note`, 1536 × 2752, tạo trong 1 phút 45 giây: <a href="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-infographic-sketch-note-apollo11-0929.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-infographic-sketch-note-apollo11-0929.png" alt="Infographic Apollo 11 tạo bằng Gemini Notebook API" style="width:100%;max-width:360px;border-radius:8px"></a> ### Câu hỏi thường gặp - **Gemini Notebook (NotebookLM) có API chính thức không?** Qua useapi.net, tài khoản thường cũng có: Gemini Notebook API của useapi.net là REST API của bên thứ ba, điều khiển tài khoản Google của chính bạn, dùng được với gói cá nhân miễn phí lẫn trả phí, và làm được mọi tính năng của bản web. Google chỉ có API cho Gemini Notebook Enterprise, cần mua giấy phép Enterprise trong một dự án Google Cloud, chỉ quản lý notebook, thêm nguồn và tạo Audio Overview, và tài khoản Google thông thường không dùng được. So sánh ở phần [Giá](#pricing). - **Có cần Gemini API key hay Gemini Notebook (NotebookLM) API key không?** Qua useapi.net thì không. Bạn gọi API bằng [API token](/docs/start-here/setup-useapi) của useapi.net, rồi kết nối tài khoản Google một lần qua [quy trình tự động](/docs/start-here/setup-gemini-notebook), không cần dự án Google Cloud. Google không cấp Gemini Notebook API key cho tài khoản thông thường. - **Có tạo được podcast tiếng Việt không?** Qua useapi.net, bạn chọn ngôn ngữ podcast bằng `language` trong [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts), ví dụ `vi` cho tiếng Việt hoặc `zh_Hans` như trong lần chạy thử [ở trên](#quick-start). `language` dùng cho âm thanh, video (trừ `cinematic`), báo cáo, báo cáo tương tác, bảng dữ liệu, infographic và slide, mặc định là `en`. Bạn cũng có thể đặt ngôn ngữ đầu ra Studio cho cả tài khoản bằng `outputLanguage` của [POST /accounts](/docs/api-gemini-notebook-v1/post-gemini-notebook-accounts). - **Có Gemini Notebook (NotebookLM) API miễn phí không?** Qua useapi.net, Gemini Notebook API chạy được trên tài khoản Google miễn phí, Google không thu phí phía họ, trong khi Google không có API cho tài khoản thông thường. Gói đăng ký useapi.net giá $15 mỗi tháng. Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công, xem [chính sách hoàn tiền](/docs/legal#refund-policy). - **Tài khoản Google miễn phí có dùng được không?** Qua useapi.net thì được. Gói miễn phí có hạn mức mỗi khung 5 giờ thấp hơn, các gói Google AI trả phí nâng giới hạn lên, và video Cinematic cần gói trả phí. - **Tạo một podcast mất bao lâu?** Qua useapi.net, Audio Overview thường mất 3–6 phút, Video Overview từ 10 phút trở lên, infographic và báo cáo một hai phút, câu đố khoảng một phút rưỡi, thẻ ghi nhớ và bảng dữ liệu dưới một phút. - **NotebookLM và Gemini Notebook có phải là một sản phẩm không?** Đúng vậy. Gemini Notebook là tên mới của NotebookLM từ tháng 7/2026, và API trong bài này chính là NotebookLM API, qua useapi.net. Thêm câu hỏi và trả lời ở [Câu hỏi thường gặp về Gemini Notebook API (tiếng Anh)](/docs/api-gemini-notebook-v1#questions). ### Kết luận Có câu hỏi, hãy ghé <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> hoặc <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> của chúng tôi. Mọi endpoint có trong [tài liệu Gemini Notebook API](/docs/api-gemini-notebook-v1), còn code ví dụ có trong [repo GitHub](https://github.com/useapi/notebooklm-api). ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/gemini-notebook-bash === Document URL: https://useapi.net/docs/articles/gemini-notebook-bash --- layout: default title: "How to Automate Gemini Notebook (NotebookLM) with the API: Deep Research, Chat, Audio Overviews and a Lot More" description: "Automate Gemini Notebook (formerly NotebookLM) over REST with useapi.net and curl: add sources, chat with citations, run Deep Research, generate Audio Overviews." keywords: [NotebookLM API, Gemini Notebook API, NotebookLM Deep Research API, NotebookLM Audio Overview API, NotebookLM podcast API, NotebookLM automation, NotebookLM curl, notebook chat API with citations, AI quiz generator API, AI infographic API] image: https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-infographic-sketch-note-apollo11-0929.png parent: Articles nav_exclude: true date: 2026-09-29 last_modified: 2026-10-18 nav_order: 830 repo: https://github.com/useapi/notebooklm-api translation_key: gemini-notebook --- ## How to Automate Gemini Notebook (NotebookLM) with the API: Deep Research, Chat, Audio Overviews and a Lot More 10 min read • September 29, 2026 (October 18, 2026) ## Table of contents ### Introduction The [useapi.net Gemini Notebook API](/docs/api-gemini-notebook-v1) is a REST API for Google's [Gemini Notebook](https://notebook.google.com), formerly NotebookLM, that you can call from any language that can send an HTTP request. It drives your own Google account: notebooks, sources, grounded chat, notes, web research, sharing and every Studio artifact. It also runs unattended: jobs spread across your connected accounts by remaining usage and are tracked server-side, so nobody has to watch the usage limits or decide when the next batch can start (see [the FAQ](#frequently-asked-questions)). Four sources and two research questions went in, and 30 minutes of API calls later the notebook held an Audio Overview, an 11-minute Video Overview, a slide deck, an infographic, a Deep Research report and every text artifact Studio makes. Everything below is real output, and every call that made it is further down the page. ### Sources and prompts | Input | What it is | |---|---| | Web page | [Apollo 11 on Wikipedia](https://en.wikipedia.org/wiki/Apollo_11), 27,095 words | | YouTube video | [A New Look at the Apollo 11 Landing Site](https://www.youtube.com/watch?v=xUcYQ7slmRw), NASA Goddard | | Pasted text | One paragraph, "Why Apollo 11 almost did not land" | | PDF upload | The same Wikipedia article as a 3.8 MB PDF | | Chat question | "What went wrong during the descent, and how did the crew handle it?", then "How much fuel was left when they landed?" | | Discover sources | "Apollo 11 lunar module guidance computer alarms" | | Deep Research | "Why did the Apollo 11 landing nearly abort?" | ### Results <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 320px;max-width:480px;margin:0"> <video poster="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-video-explainer-whiteboard-apollo11-first90s-0929-poster.jpg" controls width="100%" style="border-radius:8px" src="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-video-explainer-whiteboard-apollo11-first90s-0929.mp4"></video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em"><strong>Video Overview</strong> — explainer, whiteboard style, 11 min 50 s (the first 90 seconds, cut without re-encoding for our media host · <a href="#18-a-video-overview-and-a-slide-deck">step 18</a>)</figcaption> </figure> <figure style="flex:1 1 320px;max-width:480px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-slides-presenter-apollo11-slide1-0929.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-slides-presenter-apollo11-slide1-0929.png" alt="Slide 1 of the Apollo 11 Mission deck generated by the Gemini Notebook API" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em"><strong>Slide deck</strong> — presenter format, 8 slides, <code>pdf</code> + <code>pptx</code> (<a href="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-slides-presenter-apollo11-deck-0929.pdf" target="_blank" rel="noopener noreferrer">the whole deck as PDF</a> · <a href="#18-a-video-overview-and-a-slide-deck">step 18</a>)</figcaption> </figure> </div> <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 320px;max-width:480px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-slides-presenter-apollo11-slide2-0929.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-slides-presenter-apollo11-slide2-0929.png" alt="Slide 2 before the revision" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em"><strong>Slide 2</strong> as generated</figcaption> </figure> <figure style="flex:1 1 320px;max-width:480px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-slides-presenter-apollo11-slide2-revised-timeline-0929.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-slides-presenter-apollo11-slide2-revised-timeline-0929.png" alt="Slide 2 after the revision, redrawn as a timeline" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em"><strong>Slide 2 revised</strong> — "Make this slide a simple timeline graphic." (51 seconds · <a href="#19-revise-one-slide">step 19</a>)</figcaption> </figure> </div> <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px;align-items:flex-start"> <figure style="flex:1 1 220px;max-width:300px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-infographic-sketch-note-apollo11-0929.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-infographic-sketch-note-apollo11-0929.png" alt="Apollo 11 Mission Infographic Overview generated by the Gemini Notebook API" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em"><strong>Infographic</strong> — portrait, sketch note, 1536 × 2752 (1 min 45 s · <a href="#11-an-audio-overview-and-an-infographic">step 11</a>)</figcaption> </figure> <figure style="flex:1 1 320px;max-width:480px;margin:0"> <audio controls class="audio-player" style="width:100%"><source src="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-audio-overview-brief-apollo11-0929.m4a" type="audio/mp4"></audio> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em"><strong>Audio Overview</strong> — brief, short, 1 min 31 s ("Fifty Seconds of Fuel and Lunar Isolation" · 4 min 36 s to generate · <a href="#11-an-audio-overview-and-an-infographic">step 11</a>)</figcaption> </figure> </div> And as text or JSON, ready to use in your own app: | Result | What came back | Time | |---|---|--:| | [Chat answer](#6-ask-a-question) | 4,237 characters with 21 numbered citations, and a follow-up in the same conversation | 35 s | | [Discover sources](#8-find-more-sources-on-the-web) | 10 web pages with one-line descriptions, 3 imported | 16 s | | [Deep Research](#12-collect-the-deep-research-report) | A 26,878-character cited report on 30 web sources, imported as a source | 3 min 40 s | | [Quiz](#10-a-quiz) | 6 questions with answer options, hints and rationales | 33 s | | [Flashcards](#17-flashcards-a-mind-map-a-report-and-a-data-table) | 20 cards | 18 s | | [Mind map](#17-flashcards-a-mind-map-a-report-and-a-data-table) | A JSON tree of the whole topic | 92 s | | [Briefing report](#17-flashcards-a-mind-map-a-report-and-a-data-table) | 27,282 characters of Markdown | 79 s | | [Data table](#17-flashcards-a-mind-map-a-report-and-a-data-table) | 12 rows of alarms and anomalies with their causes | 32 s | | [Source guide](#5-see-what-a-source-is-about) | Google's summary and key topics of the Wikipedia page | 1 s | Also on YouTube: [NotebookLM has no API. Now it does: podcasts, video, slides from one REST call](https://youtube.com/shorts/ISOQAabo0b0). ### What it cost useapi.net is an API, not a hosted Gemini Notebook. Every call runs on a Google account of your own, which you connect once through [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook), and everything it makes lives in that account. Gemini Notebook itself is free on a free Google account, and paid Google AI plans raise its limits. You pay useapi.net a flat [$15/month](/docs/subscription) for API access to every supported service, and nothing per generation. Each subscription lets you connect 3 Google accounts, up to 100 in total. With more than one connected, the API load-balances across them: omit `email` and a new notebook goes to the least busy account, and a one-shot [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts#one-shot-requests) runs on an account with a free job slot and enough usage left for the job. [GET /jobs](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs) shows the load on every account. Google meters it with a usage budget per account that refills every 5 hours, plus a weekly budget. Everything on this page used about 35% of a Google AI Pro account's 5-hour budget, across two windows (10% for the first script, 25% for the second, mostly the video and the slide deck), and 1.7% of its week. How many of each you can start with a full 5-hour budget, counting each job at Google's own estimate (so these are minimums): | Studio action | Free | Pro | Ultra | |---|--:|--:|--:| | | not available | | | | | | | | [GET /accounts/`email`](/docs/api-gemini-notebook-v1/get-gemini-notebook-accounts-email) shows each account's live usage, reset times and every action's current estimate. ### Why useapi.net instead of a free library useapi.net is a third-party API and is not affiliated with Google. - **Nothing to run on your machine.** The API is hosted, so jobs keep running when your laptop is off: no Chromium download, no local server, no tunnel and no browser left open. - **Sign in once, we keep you signed in.** The guided browser [setup](/docs/start-here/setup-gemini-notebook) connects your Google account once, and we keep the session fresh, with no cookies to copy or refresh. If Google ever signs it out, you get an email with a one-minute re-add link. - **A hosted [MCP server](/docs/api-gemini-notebook-v1/mcp), 57 tools.** Add it to Claude Code, Cursor or VS Code with one line. Nothing to install, and every notebook, source, chat and Studio output is available to your AI assistant. - **Plain REST from any language.** Call it from Node.js, Python, bash, n8n, Make or a cron job with an API token. A Postman collection and an LLM-friendly spec cover every endpoint. - **Jobs tracked for you, with webhooks.** Every podcast, video, slide deck and research run is a server-side job. Poll it, or pass `replyUrl` and get the finished result posted to your endpoint. - **Several Google accounts, balanced automatically.** Connect 3 accounts per subscription, up to 100; each new job goes to one that is healthy, has a free slot and still has usage left. - **Links in, podcast out.** Send URLs or text to one endpoint and get an Audio Overview, Video Overview, slide deck or quiz back, with no notebook setup. - **Ready-made [n8n workflows]() and an agent skill**, on your free or paid Google plan, for a flat [$15/month](/docs/subscription) that covers every useapi.net API. ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. ### How it was built Two scripts ran back to back: the first (steps 1 to 14) built and researched the notebook and generated the audio, infographic and quiz, the second (steps 15 to 19) made everything else on the same notebook. Both are at the [end of the page](#run-both-scripts-yourself). Each step shows its result, and its `curl` request with the response it got is one click away. You need a useapi.net [API token](/docs/start-here/setup-useapi) and a Google account connected through [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). Every call is also in the [Postman collection](https://www.postman.com/useapinet/useapi-net/collection/29112081-40696e39-d128-417e-984b-fe1b97e7bb00) if you'd rather click than script. The steps use these variables: ```bash export USEAPI_TOKEN="user:12345-..." export EMAIL="user@example.com" API=https://api.useapi.net/v1/gemini-notebook enc() { jq -rn --arg v "$1" '$v|@uri'; } ``` The ids the API returns name the account they belong to and contain `:` and `@`, so they are URL-encoded (`enc`) whenever they go into a URL path. Studio generation and research run as jobs: the default `mode: sync` waits up to 90 seconds and returns the finished result, or `202` with the running job, and `mode: async` returns `201` with a `jobid` at once. Poll [GET /jobs/`jobid`](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid) or pass `replyUrl` for a webhook. #### 1. Create a notebook [POST /notebooks](/docs/api-gemini-notebook-v1/post-gemini-notebook-notebooks) on the connected account. Omit `email` and the API picks the least busy of your accounts. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-gemini-notebook-v1/post-gemini-notebook-notebooks">POST /notebooks</a></summary> ```bash curl -sS -X POST "$API/notebooks" \ -H "Authorization: Bearer $USEAPI_TOKEN" -H "Content-Type: application/json" \ -d "$(jq -n --arg email "$EMAIL" '{email: $email, title: "Apollo 11"}')" | tee notebook.json NOTEBOOK=$(jq -r .notebook notebook.json) ``` It returned, in full ([step-01-notebook.json](/assets/articles/gemini-notebook-bash/step-01-notebook.json)): <div markdown="1" style="max-height:420px;overflow:auto"> ```json { "notebook": "user:12345-user@example.com-notebook:62600bab-4082-4ee6-8fc3-955cee0c69cf", "email": "user@example.com", "title": "Apollo 11" } ``` </div> </details> #### 2. Add a web page, a YouTube video and pasted text One [POST /sources](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources) call takes up to 50 `urls` (YouTube links become video sources) plus pasted `text`. A file in the account's Google Drive goes in the same call as `drive: [{fileId, mimeType, name}]`, and [POST /sources/sync](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources-sync) re-imports it after it changes. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-gemini-notebook-v1/post-gemini-notebook-sources">POST /sources</a></summary> ```bash curl -sS -X POST "$API/sources" \ -H "Authorization: Bearer $USEAPI_TOKEN" -H "Content-Type: application/json" \ -d "$(jq -n --arg nb "$NOTEBOOK" '{ notebook: $nb, urls: ["https://en.wikipedia.org/wiki/Apollo_11", "https://www.youtube.com/watch?v=xUcYQ7slmRw"], title: "Why Apollo 11 almost did not land", text: "During the descent the guidance computer raised 1202 and 1201 program alarms, and Armstrong flew the final approach manually to avoid a boulder field, landing with little fuel to spare." }')" ``` It returned, in full ([step-02-sources.json](/assets/articles/gemini-notebook-bash/step-02-sources.json)): <div markdown="1" style="max-height:420px;overflow:auto"> ```json { "notebook": "user:12345-user@example.com-notebook:62600bab-4082-4ee6-8fc3-955cee0c69cf", "sources": [ { "source": "user:12345-user@example.com-source:62600bab-4082-4ee6-8fc3-955cee0c69cf:3f190e9f-3311-4176-8760-ee2636bde7c9", "title": "Apollo 11 - Wikipedia", "kind": "web", "status": "ready", "words": 27095, "url": "https://en.wikipedia.org/wiki/Apollo_11", "created": "2026-09-29T04:55:41.000Z" }, { "source": "user:12345-user@example.com-source:62600bab-4082-4ee6-8fc3-955cee0c69cf:111afb31-abe8-456b-9e11-4d737e62b9c4", "title": "A New Look at the Apollo 11 Landing Site", "kind": "youtube", "status": "ready", "words": 13, "url": "https://www.youtube.com/watch?v=xUcYQ7slmRw", "created": "2026-09-29T04:55:41.000Z" }, { "source": "user:12345-user@example.com-source:62600bab-4082-4ee6-8fc3-955cee0c69cf:7b33d275-e4b8-4e7c-82fb-19f616af3132", "title": "Why Apollo 11 almost did not land", "kind": "text", "status": "ready", "words": 30, "created": "2026-09-29T04:55:41.000Z" } ] } ``` </div> </details> #### 3. Upload a file [POST /sources/upload](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources-upload) takes the file as the raw request body, with its MIME type as `Content-Type`: PDF, Word, PowerPoint, EPUB, Markdown, text, CSV, audio, video or an image. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-gemini-notebook-v1/post-gemini-notebook-sources-upload">POST /sources/upload</a></summary> ```bash curl -sS -X POST "$API/sources/upload?notebook=$(enc "$NOTEBOOK")&name=01-apollo11-wikipedia.pdf" \ -H "Authorization: Bearer $USEAPI_TOKEN" -H "Content-Type: application/pdf" \ --data-binary @01-apollo11-wikipedia.pdf ``` It returned, in full ([step-03-upload.json](/assets/articles/gemini-notebook-bash/step-03-upload.json)): <div markdown="1" style="max-height:420px;overflow:auto"> ```json { "notebook": "user:12345-user@example.com-notebook:62600bab-4082-4ee6-8fc3-955cee0c69cf", "source": "user:12345-user@example.com-source:62600bab-4082-4ee6-8fc3-955cee0c69cf:6e04a6ea-cd2d-44cb-8be5-66f48be21a0d", "title": "01-apollo11-wikipedia.pdf", "status": "preparing" } ``` </div> </details> #### 4. Wait until every source is ready Google processes each source before it can be used. The 3.8 MB PDF took about 45 seconds, the others were ready at once. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks-notebook">GET /notebooks/<code>notebook</code></a>, polled</summary> ```bash until curl -sS "$API/notebooks/$(enc "$NOTEBOOK")" -H "Authorization: Bearer $USEAPI_TOKEN" > notebook.json && jq -e '[.sources[].status] | all(. == "ready" or . == "error")' notebook.json > /dev/null; do sleep 10 done cat notebook.json ``` It returned, in full ([step-04-notebook.json](/assets/articles/gemini-notebook-bash/step-04-notebook.json)): <div markdown="1" style="max-height:420px;overflow:auto"> ```json { "notebook": "user:12345-user@example.com-notebook:62600bab-4082-4ee6-8fc3-955cee0c69cf", "email": "user@example.com", "title": "Apollo 11", "emoji": "🌕", "created": "2026-09-29T04:55:39.000Z", "updated": "2026-09-29T04:56:37.000Z", "sources": [ { "source": "user:12345-user@example.com-source:62600bab-4082-4ee6-8fc3-955cee0c69cf:6e04a6ea-cd2d-44cb-8be5-66f48be21a0d", "title": "01-apollo11-wikipedia.pdf", "kind": "pdf", "status": "ready", "words": 21578, "mimeType": "application/pdf", "created": "2026-09-29T04:55:52.000Z" }, { "source": "user:12345-user@example.com-source:62600bab-4082-4ee6-8fc3-955cee0c69cf:111afb31-abe8-456b-9e11-4d737e62b9c4", "title": "A New Look at the Apollo 11 Landing Site", "kind": "youtube", "status": "ready", "words": 13, "url": "https://www.youtube.com/watch?v=xUcYQ7slmRw", "created": "2026-09-29T04:55:41.000Z" }, { "source": "user:12345-user@example.com-source:62600bab-4082-4ee6-8fc3-955cee0c69cf:3f190e9f-3311-4176-8760-ee2636bde7c9", "title": "Apollo 11 - Wikipedia", "kind": "web", "status": "ready", "words": 27095, "url": "https://en.wikipedia.org/wiki/Apollo_11", "created": "2026-09-29T04:55:41.000Z" }, { "source": "user:12345-user@example.com-source:62600bab-4082-4ee6-8fc3-955cee0c69cf:7b33d275-e4b8-4e7c-82fb-19f616af3132", "title": "Why Apollo 11 almost did not land", "kind": "text", "status": "ready", "words": 30, "created": "2026-09-29T04:55:41.000Z" } ], "artifacts": [] } ``` </div> </details> #### 5. See what a source is about [GET /sources/`source`](/docs/api-gemini-notebook-v1/get-gemini-notebook-sources-source) returns Google's summary and key topics of one source, and with `?content=true` the full text Google indexed from it. For the Wikipedia page the topics were Apollo spaceflight, Lunar landing, Space Race, Mission personnel and Space exploration. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-gemini-notebook-v1/get-gemini-notebook-sources-source">GET /sources/<code>source</code></a></summary> ```bash WEB=$(jq -r '[.sources[] | select(.kind == "web")][0].source' notebook.json) curl -sS "$API/sources/$(enc "$WEB")" -H "Authorization: Bearer $USEAPI_TOKEN" ``` It returned, in full ([step-05-source.json](/assets/articles/gemini-notebook-bash/step-05-source.json)): <div markdown="1" style="max-height:420px;overflow:auto"> ```json { "source": "user:12345-user@example.com-source:62600bab-4082-4ee6-8fc3-955cee0c69cf:3f190e9f-3311-4176-8760-ee2636bde7c9", "title": "Apollo 11 - Wikipedia", "kind": "web", "status": "ready", "words": 27095, "url": "https://en.wikipedia.org/wiki/Apollo_11", "created": "2026-09-29T04:55:41.000Z", "notebook": "user:12345-user@example.com-notebook:62600bab-4082-4ee6-8fc3-955cee0c69cf", "summary": "The provided source documents the historic **Apollo 11 mission**, which successfully achieved the first **crewed Moon landing** in July 1969. It outlines the intense background of the **Space Race** driven by Cold War rivalries, detailing how President John F. Kennedy's ambitious national goal was realized through immense technological coordination. Additionally, the text covers critical mission preparations, such as crew selections, spacecraft engineering, and site planning, alongside the dramatic real-time moments of the **lunar descent and landing**, famously overcoming sudden computer navigational challenges to alter the course of human history.", "topics": [ "Apollo spaceflight", "Lunar landing", "Space Race", "Mission personnel", "Space exploration" ] } ``` </div> </details> #### 6. Ask a question [POST /chat](/docs/api-gemini-notebook-v1/post-gemini-notebook-chat) answers from the sources with numbered citations, each naming its source and quoting the passage. This answer took 35 seconds and carried 21 citations. Send the same `conversation` with the next question to keep the context ([step 15](#15-ask-a-follow-up-question)). <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-gemini-notebook-v1/post-gemini-notebook-chat">POST /chat</a></summary> ```bash curl -sS -X POST "$API/chat" \ -H "Authorization: Bearer $USEAPI_TOKEN" -H "Content-Type: application/json" \ -d "$(jq -n --arg nb "$NOTEBOOK" '{notebook: $nb, question: "What went wrong during the descent, and how did the crew handle it?"}')" | tee chat.json ``` It returned, in full ([step-06-chat.json](/assets/articles/gemini-notebook-bash/step-06-chat.json)): <div markdown="1" style="max-height:420px;overflow:auto"> ```json { "notebook": "user:12345-user@example.com-notebook:62600bab-4082-4ee6-8fc3-955cee0c69cf", "answer": "During the lunar descent of Apollo 11's Lunar Module *Eagle*, a cascade of unexpected technical anomalies and environmental hazards threatened the landing, requiring rapid problem-solving from both the crew and Mission Control [1-6].\n\n---\n\n### **1. Overshooting the Planned Landing Target**\n* **What went wrong:** As descent began, Neil Armstrong and Buzz Aldrin noticed they were passing lunar landmarks two to three seconds early, meaning *Eagle* was traveling too fast and would land miles downrange of their intended target [3, 7]. Flight controllers suspected this was caused by lunar gravitational anomalies (mascons), extra air pressure in the docking tunnel, or unmodeled forces during earlier maneuvers [3, 7].\n* **How it was handled:** The crew monitored their position closely, maintained composure, and prepared to adapt to landing further west than planned [2, 3, 5, 7].\n\n---\n\n### **2. Computer Program Alarms (1201 and 1202)**\n* **What went wrong:** Five minutes into the descent burn, at about 6,000 feet above the surface, the Lunar Module Guidance Computer (LGC) raised unexpected **1201 and 1202 program alarms** [1, 4, 6]. These indicated \"executive overflows\"—the computer was receiving more data than it could process in real-time and had to postpone lower-priority tasks [1, 4]. The root cause was later identified as a radar hardware mismatch that fed spurious data from the rendezvous radar into the computer while the landing radar was also active [8-10].\n* **How it was handled:** \n * **Mission Control:** Computer engineer **Jack Garman** recognized that the alarms were safe as long as they remained intermittent [1, 4]. Guidance Officer **Steve Bales** agreed, and CAPCOM **Charles Duke** relayed the \"GO\" call to the crew [1, 4].\n * **Onboard Software:** Software engineered under **Margaret Hamilton** at MIT was designed to drop lower-priority tasks and prioritize critical guidance calculations, preventing a system crash or an automatic abort [11, 12].\n\n---\n\n### **3. Hazardous Landing Terrain (West Crater)**\n* **What went wrong:** When Armstrong looked out his window, he saw that the automated guidance system was targeting a boulder-strewn area surrounding a 300-foot-wide crater (West crater) [2, 5, 6]. Touching down there would have risked flipping or damaging the lander [2, 5].\n* **How it was handled:** Armstrong took **semi-automatic manual control** of *Eagle* to fly past the boulder field and find clear ground [2, 5, 6, 13, 14]. While Armstrong focused entirely on flying the spacecraft, **Buzz Aldrin called out altitude and navigation data** continuously to keep him informed [2, 5].\n\n---\n\n### **4. Dwindling Fuel and Blinding Lunar Dust**\n* **What went wrong:** Extending the flight to find a clear landing site consumed critical propellant [13, 14]. At 100 feet above the surface, the lander had only about **90 seconds of fuel remaining** [13, 14]. Additionally, the engine exhaust kicked up a blinding cloud of fine lunar dust that obscured the surface, making it difficult to judge motion and speed [14, 15].\n* **How it was handled:** Armstrong picked out large rocks projecting above the dust cloud to visually gauge *Eagle*'s horizontal speed [14, 15]. He cleared a smaller crater and brought the lander down smoothly with roughly **25 to 50 seconds of fuel remaining** before a forced abort would have become necessary [13, 14, 16, 17].\n\n---\n\n### **5. Engine Shutdown and Touchdown**\n* **What went wrong:** When a 67-inch probe hanging from *Eagle*'s footpads touched the Moon, Aldrin called \"Contact light!\" [10, 15, 18]. Engine shutdown was supposed to occur immediately to avoid gas pressure build-up under the craft, but in the intensity of the moment, Armstrong delayed shutting down the engine for about three seconds [15, 18].\n* **How it was handled:** *Eagle* settled safely on the Moon without damage [15, 18]. The crew immediately ran through post-landing checklists to secure the engine, after which Armstrong announced: *\"Houston, Tranquility Base here. The Eagle has landed\"* [10, 15, 19-21].\n\n💡 Would you like to explore what happened during the moonwalk itself, or look into the close calls the crew faced during their liftoff and ascent from the lunar surface?", "conversation": "51147e56-85e3-4862-b0a4-12fd1410b1a5", "citations": [ { "number": 1, "source": "user:12345-user@example.com-source:62600bab-4082-4ee6-8fc3-955cee0c69cf:6e04a6ea-cd2d-44cb-8be5-66f48be21a0d", "text": "Lunar descentEagle in lunar orbit photographed from Columbia Armstrong pilots Eagle to its landing on the Moon, July 20, 1969. Five minutes into the descent burn, and 6,000 feet (1,800 m) above the surface of the Moon, the LM guidance computer (LGC) distracted the crew with the first of several unexpected 1201 and 1202 program alarms. Inside Mission Control Center, computer engineer Jack Garman told Guidance Officer Steve Bales it was safe to continue the descent, and this was relayed to the crew. The program alarms indicated \"executive overflows\", meaning the guidance computer could not complete all its tasks in real-time and had to postpone some of them.[117][118]", "relevance": 0.9848101265822785 }, { "number": 2, "source": "user:12345-user@example.com-source:62600bab-4082-4ee6-8fc3-955cee0c69cf:6e04a6ea-cd2d-44cb-8be5-66f48be21a0d", "text": "When Armstrong again looked outside, he saw that the computer's landing system was targeting a boulder-strewn area just north and east of a 300-foot-diameter (91  m) crater (later determined to be West crater), so he took semi-automatic control.[123][124] Armstrong considered landing short of the boulder field so they could collect geological samples from it, but could not since their horizontal velocity was too high. Throughout the descent, Aldrin called out navigation data to Armstrong, who was busy piloting Eagle.[125]", "relevance": 0.9291139240506329 }, { "number": 3, "source": "user:12345-user@example.com-source:62600bab-4082-4ee6-8fc3-955cee0c69cf:3f190e9f-3311-4176-8760-ee2636bde7c9", "text": "Lunar descentColumbia in lunar orbit, photographed from EagleAt 12:52:00 UTC on July 20, Aldrin and Armstrong entered Eagle, and began the final preparations for lunar descent. [8] At 17:44:00 Eagle separated from Columbia. [13] Collins, alone aboard Columbia, inspected Eagle as it pirouetted before him to ensure the craft was not damaged, and that the landing gear was correctly deployed. [113] [114] Armstrong exclaimed: \"The Eagle has wings!\" [114]As the descent began, Armstrong and Aldrin found themselves passing landmarks on the surface two or three seconds early, and reported that they were \"long\"; they would land miles west of their target point. Eagle was traveling too fast. The problem could have been mascons—concen tra tions of high mass in a region or regions of the Moon's crust that contains a gravitational anomaly, potentially altering Eagle' s trajectory. Flight Director Gene Kranz speculated that it could have resulted from extra air pressure in the docking tunnel, or a result of Eagle' s pirouette maneuver. [115] [116]", "relevance": 0.9113924050632911 }, { "number": 4, "source": "user:12345-user@example.com-source:62600bab-4082-4ee6-8fc3-955cee0c69cf:3f190e9f-3311-4176-8760-ee2636bde7c9", "text": "Five minutes into the descent burn, and 6,000 feet (1,800 m) above the surface of the Moon, the LM guidance computer (LGC) distracted the crew with the first of several unexpected 1201 and 1202 program alarms. Inside Mission Control Center, computer engineer Jack Garman told Guidance Officer Steve Bales it was safe to continue the descent, and this was relayed to the crew. The program alarms indicated \"executive overflows\", meaning the guidance computer could not complete all its tasks in real-time and had to postpone some of them. [117] [118] Margaret Hamilton, the Director of Apollo Flight Computer Programming at the MIT Charles Stark Draper Laboratory later recalled:", "relevance": 0.9974683544303797 }, { "number": 5, "source": "user:12345-user@example.com-source:62600bab-4082-4ee6-8fc3-955cee0c69cf:3f190e9f-3311-4176-8760-ee2636bde7c9", "text": "LandingDuration: 4 minutes and 30 seconds. 4:30 Subtitles available. CC Armstrong pilots Eagle to its landing on the Moon, July 20, 1969.When Armstrong again looked outside, he saw that the computer's landing system was targeting a boulder-strewn area just north and east of a 300-foot-diameter (91 m) crater (later determined to be West crater), so he took semi-automatic control. [123] [124] Armstrong considered landing short of the boulder field so they could collect geological samples from it, but could not since their horizontal velocity was too high. Throughout the descent, Aldrin called out navigation data to Armstrong, who was busy piloting Eagle. [125]", "relevance": 0.8177215189873418 }, { "number": 6, "source": "user:12345-user@example.com-source:62600bab-4082-4ee6-8fc3-955cee0c69cf:7b33d275-e4b8-4e7c-82fb-19f616af3132", "text": "During the descent the guidance computer raised 1202 and 1201 program alarms, and Armstrong flew the final approach manually to avoid a boulder field, landing with little fuel to spare.", "relevance": 1 }, { "number": 7, "source": "user:12345-user@example.com-source:62600bab-4082-4ee6-8fc3-955cee0c69cf:6e04a6ea-cd2d-44cb-8be5-66f48be21a0d", "text": "At 12:52:00 UTC on July 20, Aldrin and Armstrong entered Eagle, and began the final preparations for lunar descent.[8] At 17:44:00 Eagle separated from Columbia.[13] Collins, alone aboard Columbia, inspected Eagle as it pirouetted before him to ensure the craft was not damaged, and that the landing gear was correctly deployed.[113][114] Armstrong exclaimed: \"The Eagle has wings!\"[114] As the descent began, Armstrong and Aldrin found themselves passing landmarks on the surface two or three seconds early, and reported that they were \"long\"; they would land miles west of their target point. Eagle was traveling too fast. The problem could have been mascons—concen tra tions of high mass in a region or regions of the Moon's crust that contains a gravitational anomaly, potentially altering Eagle 's trajectory. Flight Director Gene Kranz speculated that it could have resulted from extra air pressure in the docking tunnel, or a result of Eagle 's pirouette maneuver.[115][116]", "relevance": 0.9468354430379747 }, { "number": 8, "source": "user:12345-user@example.com-source:62600bab-4082-4ee6-8fc3-955cee0c69cf:6e04a6ea-cd2d-44cb-8be5-66f48be21a0d", "text": "During the mission, the cause was diagnosed as the rendezvous radar switch being in the wrong position, causing the computer to process data from both the rendezvous and landing radars at the same time.[120][121] Software engineer Don Eyles concluded in a 2005 Guidance and Control Conference paper that the problem was due to a hardware design bug previously seen during testing of the first uncrewed LM in Apollo 5. Having the rendezvous radar on (so it was warmed up in case of an emergency landing abort) should have been irrelevant to the computer, but an electrical phasing mismatch between two parts of the rendezvous radar system could cause the stationary antenna to appear to the computer as dithering back and forth between two positions, depending upon how the hardware randomly powered up. The extra spurious cycle stealing, as the rendezvous radar updated an involuntary counter, caused the computer alarms.[122]", "relevance": 0.9949367088607595 }, { "number": 9, "source": "user:12345-user@example.com-source:62600bab-4082-4ee6-8fc3-955cee0c69cf:3f190e9f-3311-4176-8760-ee2636bde7c9", "text": "During the mission, the cause was diagnosed as the rendezvous radar switch being in the wrong position, causing the computer to process data from both the rendezvous and landing radars at the same time. [120] [121] Software engineer Don Eyles concluded in a 2005 Guidance and Control Conference paper that the problem was due to a hardware design bug previously seen during testing of the first uncrewed LM in Apollo 5. Having the rendezvous radar on (so it was warmed up in case of an emergency landing abort) should have been irrelevant to the computer, but an electrical phasing mismatch between two parts of the rendezvous radar system could cause the stationary antenna to appear to the computer as dithering back and forth between two positions, depending upon how the hardware randomly powered up. The extra spurious cycle stealing, as the rendezvous radar updated an involuntary counter, caused the computer alarms. [122]", "relevance": 0.9924050632911392 }, { "number": 10, "source": "user:12345-user@example.com-source:62600bab-4082-4ee6-8fc3-955cee0c69cf:3f190e9f-3311-4176-8760-ee2636bde7c9", "text": "A light informed Aldrin that at least one of the 67-inch (170 cm) probes hanging from Eagle' s footpads had touched the surface a few moments before the landing and he said: \"Contact light!\" Armstrong was supposed to immediately shut the engine down, as the engineers suspected the pressure caused by the engine's own exhaust reflecting off the lunar surface could make it explode, but he forgot. Three seconds later, Eagle landed and Armstrong shut the engine down. [127] Aldrin immediately said \"Okay, engine stop. ACA—out of detent.\" Armstrong acknowledged: \"Out of detent. Auto.\" Aldrin continued: \"Mode control—both auto. Descent engine command override off. Engine arm—off. 413 is in.\" [128]", "relevance": 0.9746835443037974 }, { "number": 11, "source": "user:12345-user@example.com-source:62600bab-4082-4ee6-8fc3-955cee0c69cf:6e04a6ea-cd2d-44cb-8be5-66f48be21a0d", "text": "Margaret Hamilton, the Director of Apollo Flight Computer Programming at the MIT Charles Stark Draper Laboratory later recalled: To blame the computer for the Apollo 11 problems is like blaming the person who spots a fire and calls the fire department. Actually, the computer was programmed to do more than recognize error conditions. A complete set of recovery programs was incorporated into the software. The software's action, in this case, was to eliminate lower priority tasks and re-establish the more important ones. The computer, rather than almost forcing an abort, prevented an abort. If the computer hadn't recognized this problem and taken recovery action, I doubt if Apollo 11 would have been the successful Moon landing it was.[119]", "relevance": 0.9822784810126582 }, { "number": 12, "source": "user:12345-user@example.com-source:62600bab-4082-4ee6-8fc3-955cee0c69cf:3f190e9f-3311-4176-8760-ee2636bde7c9", "text": "Eagle in lunar orbit photographed from ColumbiaTo blame the computer for the Apollo 11 problems is like blaming the person who spots a fire and calls the fire department. Actually, the computer was programmed to do more than recognize error conditions. A complete set of recovery programs was incorporated into the software. The software's action, in this case, was to eliminate lower priority tasks and re-establish the more important ones. The computer, rather than almost forcing an abort, prevented an abort. If the computer hadn't recognized this problem and taken recovery action, I doubt if Apollo 11 would have been the successful Moon landing it was. [119]", "relevance": 0.979746835443038 }, { "number": 13, "source": "user:12345-user@example.com-source:62600bab-4082-4ee6-8fc3-955cee0c69cf:6e04a6ea-cd2d-44cb-8be5-66f48be21a0d", "text": "Armstrong found a clear patch of ground and maneuvered the spacecraft towards it. As he got closer, now 250 feet (76 m) above the surface, he discovered his new landing site had a crater in it. Now 107 feet (33 m) above the surface, Armstrong knew their propellant supply was dwindling and was determined to land at the first possible landing site. He cleared the crater and found another patch of level ground. They were now 100 feet (30  m) from the surface, with only 90 seconds of propellant 0:00", "relevance": 0.9392405063291139 }, { "number": 14, "source": "user:12345-user@example.com-source:62600bab-4082-4ee6-8fc3-955cee0c69cf:3f190e9f-3311-4176-8760-ee2636bde7c9", "text": "Armstrong found a clear patch of ground and maneuvered the spacecraft towards it. As he got closer, now 250 feet (76 m) above the surface, he discovered his new landing site had a crater in it. Now 107 feet (33 m) above the surface, Armstrong knew their propellant supply was dwindling and was determined to land at the first possible landing site. He cleared the crater and found another patch of level ground. They were now 100 feet (30 m) from the surface, with only 90 seconds of propellant remaining. Lunar dust kicked up by the LM's engine began to impair his ability to determine the spacecraft's motion. Some large rocks jutted out of the dust cloud, and Armstrong focused on them during his descent so he could determine the spacecraft's speed. [126]", "relevance": 0.7924050632911392 }, { "number": 15, "source": "user:12345-user@example.com-source:62600bab-4082-4ee6-8fc3-955cee0c69cf:6e04a6ea-cd2d-44cb-8be5-66f48be21a0d", "text": "LandingThe landing site relative to West crater A 3-D view from the Lunar Reconnaissance Orbiter (LRO) of the Apollo 11 landing site remaining. Lunar dust kicked up by the LM's engine began to impair his ability to determine the spacecraft's motion. Some large rocks jutted out of the dust cloud, and Armstrong focused on them during his descent so he could determine the spacecraft's speed.[126] A light informed Aldrin that at least one of the 67-inch (170  cm) probes hanging from Eagle 's footpads had touched the surface a few moments before the landing and he said: \"Contact light!\" Armstrong was supposed to immediately shut the engine down, as the engineers suspected the pressure caused by the engine's own exhaust reflecting off the lunar surface could make it explode, but he forgot. Three seconds later, Eagle landed and Armstrong shut the engine down.[127] Aldrin immediately said \"Okay, engine stop. ACA—out of detent.\" Armstrong acknowledged: \"Out of detent. Auto.\" Aldrin continued: \"Mode control—both auto. Descent engine command override off. Engine arm—off. 413 is in.\"[128]", "relevance": 0.9518987341772152 }, { "number": 16, "source": "user:12345-user@example.com-source:62600bab-4082-4ee6-8fc3-955cee0c69cf:6e04a6ea-cd2d-44cb-8be5-66f48be21a0d", "text": "ACA was the Attitude Control Assembly—the LM's control stick. Output went to the LGC to command the reaction control system (RCS) jets to fire. \"Out of Detent\" meant the stick had moved away from its centered position; it was spring-centered like the turn indicator in a car. Address 413 of the Abort Guidance System (AGS) contained the variable that indicated the LM had landed.[10] Eagle landed at 20:17:40 UTC on Sunday July 20 with 216 pounds (98 kg) of usable fuel remaining. Information available to the crew and mission controllers during the landing showed the LM had enough fuel for another 25 seconds of powered flight before an abort without touchdown would have become unsafe,[10][129] but post-mission analysis showed that the real figure was probably closer to 50 seconds.[130] Apollo 11 landed with less fuel than most subsequent missions, and the astronauts encountered a premature low fuel warning. This was later found to be the result of the propellant sloshing more than expected, uncovering a fuel sensor. On subsequent missions, extra anti-slosh baffles were added to the tanks to prevent this.[10]", "relevance": 0.9493670886075949 }, { "number": 17, "source": "user:12345-user@example.com-source:62600bab-4082-4ee6-8fc3-955cee0c69cf:3f190e9f-3311-4176-8760-ee2636bde7c9", "text": "The landing site relative to West craterACA was the Attitude Control Assembly—the LM's control stick. Output went to the LGC to command the reaction control system (RCS) jets to fire. \"Out of Detent\" meant the stick had moved away from its centered position; it was spring-centered like the turn indicator in a car. Address 413 of the Abort Guidance System (AGS) contained the variable that indicated the LM had landed. [10]Eagle landed at 20:17:40 UTC on Sunday July 20 with 216 pounds (98 kg) of usable fuel remaining. Information available to the crew and mission controllers during the landing showed the LM had enough fuel for another 25 seconds of powered flight before an abort without touchdown would have become unsafe, [10] [129] but post-mission analysis showed that the real figure was probably closer to 50 seconds. [130] Apollo 11 landed with less fuel than most subsequent missions, and the astronauts encountered a premature low fuel warning. This was later found to be the result of the propellant sloshing more than expected, uncovering a fuel sensor. On subsequent missions, extra anti-slosh baffles were added to the tanks to prevent this. [10]", "relevance": 0.9316455696202531 }, { "number": 18, "source": "user:12345-user@example.com-source:62600bab-4082-4ee6-8fc3-955cee0c69cf:3f190e9f-3311-4176-8760-ee2636bde7c9", "text": "Eagle' s hatch was opened at 02:39:33. [13] Armstrong initially had some difficulties squeezing through the hatch with his portable life support system (PLSS). [136] Some of the highest heart rates recorded from Apollo astronauts occurred during LM egress and ingress. [139] At 02:51 Armstrong began his descent to the lunar surface. The remote-control unit on his chest kept him from seeing his feet. Climbing down the nine-rung ladder, Armstrong pulled a D-ring to deploy the modular equipment stowage assembly (MESA) folded against Eagle' s side and activate the TV camera. [140] [141]", "relevance": 0.9417721518987342 }, { "number": 19, "source": "user:12345-user@example.com-source:62600bab-4082-4ee6-8fc3-955cee0c69cf:6e04a6ea-cd2d-44cb-8be5-66f48be21a0d", "text": "Armstrong acknowledged Aldrin's completion of the post-landing checklist with \"Engine arm is off\", before responding to the CAPCOM, Charles Duke, with the words, \"Houston, Tranquility Base here. The Eagle has landed.\" Armstrong's unrehearsed change of call sign from \"Eagle\" to \"Tranquility Base\" emphasized to listeners that landing was complete and successful.[131] Duke expressed the relief at Mission Control: \"Roger, Twan— Tranquility, we copy you on the ground. You got a bunch of guys about to turn blue. We're breathing again. Thanks a lot.\"[10][132]", "relevance": 0.7367088607594937 }, { "number": 20, "source": "user:12345-user@example.com-source:62600bab-4082-4ee6-8fc3-955cee0c69cf:3f190e9f-3311-4176-8760-ee2636bde7c9", "text": "Apollo 11 used slow-scan television (TV) incompatible with broadcast TV, so it was displayed on a special monitor and a conventional TV camera viewed this monitor (thus, a broadcast of a broadcast), significantly reducing the quality of the picture. [142] The signal was received at Goldstone in the United States, but with better fidelity by Honeysuckle Creek Tracking Station near Canberra in Australia. Minutes later the feed was switched to the more sensitive Parkes radio telescope in Australia. [143] Despite some technical and weather difficulties, black and white images of the first lunar EVA were received and broadcast to at least 600 million people on Earth. [143] Copies of this video in broadcast format were saved and are widely available, but recordings of the original slow scan source transmission from the lunar surface were likely destroyed during routine magnetic tape re-use at NASA. [142]", "relevance": 0.7291139240506329 }, { "number": 21, "source": "user:12345-user@example.com-source:62600bab-4082-4ee6-8fc3-955cee0c69cf:3f190e9f-3311-4176-8760-ee2636bde7c9", "text": "Armstrong said moving in the lunar gravity, one-sixth of Earth's, was \"even perhaps easier than the simulations ... It's absolutely no trouble to walk around.\" [141] Aldrin joined him on the surface and tested methods for moving around, including two-footed kangaroo hops. The PLSS backpack created a tendency to tip backward, but neither astronaut had serious problems maintaining balance. Loping became the preferred method of movement. The astronauts reported that they needed to plan their movements six or seven steps ahead. The fine soil was quite slippery. Aldrin remarked that moving from sunlight into Eagle' s shadow produced no temperature change inside the suit, but the helmet was warmer in sunlight, so he felt cooler in shadow. [141] The MESA failed to provide a stable work platform and was in shadow, slowing work somewhat. As they worked, the moonwalkers kicked up gray dust, which soiled the outer part of their suits. [152]", "relevance": 0.6683544303797468 } ], "ms": 34877 } ``` </div> </details> #### 7. Keep the answer as a note [POST /notes](/docs/api-gemini-notebook-v1/post-gemini-notebook-notes) saves text in the notebook. Notes can be listed, edited and deleted, and [step 16](#16-turn-the-note-into-a-source) turns this one into a source. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-gemini-notebook-v1/post-gemini-notebook-notes">POST /notes</a></summary> ```bash curl -sS -X POST "$API/notes" \ -H "Authorization: Bearer $USEAPI_TOKEN" -H "Content-Type: application/json" \ -d "$(jq -n --arg nb "$NOTEBOOK" --arg a "$(jq -r .answer chat.json)" '{notebook: $nb, title: "What went wrong during the descent", content: $a}')" | tee note.json ``` It returned, in full ([step-07-note.json](/assets/articles/gemini-notebook-bash/step-07-note.json)): <div markdown="1" style="max-height:420px;overflow:auto"> ```json { "notebook": "user:12345-user@example.com-notebook:62600bab-4082-4ee6-8fc3-955cee0c69cf", "note": "user:12345-user@example.com-note:62600bab-4082-4ee6-8fc3-955cee0c69cf:3ae0d70e-29eb-4f70-804e-0fe6c936f35f", "title": "What went wrong during the descent", "content": "During the lunar descent of Apollo 11's Lunar Module *Eagle*, a cascade of unexpected technical anomalies and environmental hazards threatened the landing, requiring rapid problem-solving from both the crew and Mission Control [1-6].\n\n---\n\n### **1. Overshooting the Planned Landing Target**\n* **What went wrong:** As descent began, Neil Armstrong and Buzz Aldrin noticed they were passing lunar landmarks two to three seconds early, meaning *Eagle* was traveling too fast and would land miles downrange of their intended target [3, 7]. Flight controllers suspected this was caused by lunar gravitational anomalies (mascons), extra air pressure in the docking tunnel, or unmodeled forces during earlier maneuvers [3, 7].\n* **How it was handled:** The crew monitored their position closely, maintained composure, and prepared to adapt to landing further west than planned [2, 3, 5, 7].\n\n---\n\n### **2. Computer Program Alarms (1201 and 1202)**\n* **What went wrong:** Five minutes into the descent burn, at about 6,000 feet above the surface, the Lunar Module Guidance Computer (LGC) raised unexpected **1201 and 1202 program alarms** [1, 4, 6]. These indicated \"executive overflows\"—the computer was receiving more data than it could process in real-time and had to postpone lower-priority tasks [1, 4]. The root cause was later identified as a radar hardware mismatch that fed spurious data from the rendezvous radar into the computer while the landing radar was also active [8-10].\n* **How it was handled:** \n * **Mission Control:** Computer engineer **Jack Garman** recognized that the alarms were safe as long as they remained intermittent [1, 4]. Guidance Officer **Steve Bales** agreed, and CAPCOM **Charles Duke** relayed the \"GO\" call to the crew [1, 4].\n * **Onboard Software:** Software engineered under **Margaret Hamilton** at MIT was designed to drop lower-priority tasks and prioritize critical guidance calculations, preventing a system crash or an automatic abort [11, 12].\n\n---\n\n### **3. Hazardous Landing Terrain (West Crater)**\n* **What went wrong:** When Armstrong looked out his window, he saw that the automated guidance system was targeting a boulder-strewn area surrounding a 300-foot-wide crater (West crater) [2, 5, 6]. Touching down there would have risked flipping or damaging the lander [2, 5].\n* **How it was handled:** Armstrong took **semi-automatic manual control** of *Eagle* to fly past the boulder field and find clear ground [2, 5, 6, 13, 14]. While Armstrong focused entirely on flying the spacecraft, **Buzz Aldrin called out altitude and navigation data** continuously to keep him informed [2, 5].\n\n---\n\n### **4. Dwindling Fuel and Blinding Lunar Dust**\n* **What went wrong:** Extending the flight to find a clear landing site consumed critical propellant [13, 14]. At 100 feet above the surface, the lander had only about **90 seconds of fuel remaining** [13, 14]. Additionally, the engine exhaust kicked up a blinding cloud of fine lunar dust that obscured the surface, making it difficult to judge motion and speed [14, 15].\n* **How it was handled:** Armstrong picked out large rocks projecting above the dust cloud to visually gauge *Eagle*'s horizontal speed [14, 15]. He cleared a smaller crater and brought the lander down smoothly with roughly **25 to 50 seconds of fuel remaining** before a forced abort would have become necessary [13, 14, 16, 17].\n\n---\n\n### **5. Engine Shutdown and Touchdown**\n* **What went wrong:** When a 67-inch probe hanging from *Eagle*'s footpads touched the Moon, Aldrin called \"Contact light!\" [10, 15, 18]. Engine shutdown was supposed to occur immediately to avoid gas pressure build-up under the craft, but in the intensity of the moment, Armstrong delayed shutting down the engine for about three seconds [15, 18].\n* **How it was handled:** *Eagle* settled safely on the Moon without damage [15, 18]. The crew immediately ran through post-landing checklists to secure the engine, after which Armstrong announced: *\"Houston, Tranquility Base here. The Eagle has landed\"* [10, 15, 19-21].\n\n💡 Would you like to explore what happened during the moonwalk itself, or look into the close calls the crew faced during their liftoff and ascent from the lunar surface?", "type": "note", "created": "2026-09-29T04:57:19.000Z", "updated": "2026-09-29T04:57:19.000Z" } ``` </div> </details> #### 8. Find more sources on the web [POST /research](/docs/api-gemini-notebook-v1/post-gemini-notebook-research) with `type: "fast"` is Gemini Notebook's Discover sources. It returned 10 web pages in 16 seconds. Nothing enters the notebook until [POST /research/import](/docs/api-gemini-notebook-v1/post-gemini-notebook-research-import), and three were picked. Two came back: Google could not fetch the third page (a Stack Exchange question), so it is left out of the answer and listed in the notebook with status `error`. An import waits until Google has fetched every page, about a minute and a half here. If Google takes longer, the API answers `504` after about two minutes and the import usually still completes, so check the notebook before you retry. Never retry blindly, since that adds every source twice. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-gemini-notebook-v1/post-gemini-notebook-research">POST /research</a> + <a href="/docs/api-gemini-notebook-v1/post-gemini-notebook-research-import">POST /research/import</a></summary> ```bash curl -sS -X POST "$API/research" \ -H "Authorization: Bearer $USEAPI_TOKEN" -H "Content-Type: application/json" \ -d "$(jq -n --arg nb "$NOTEBOOK" '{notebook: $nb, type: "fast", query: "Apollo 11 lunar module guidance computer alarms"}')" | tee discover.json ``` The Discover job, in full ([step-08-discover-job.json](/assets/articles/gemini-notebook-bash/step-08-discover-job.json)): <div markdown="1" style="max-height:420px;overflow:auto"> ```json { "jobid": "job:ca20f94b-fa29-463e-b798-6865271fcee3-user:12345-user@example.com-bot:gemini_notebook", "email": "user@example.com", "type": "research", "status": "completed", "notebook": "user:12345-user@example.com-notebook:62600bab-4082-4ee6-8fc3-955cee0c69cf", "created_at": "2026-09-29T04:57:20.923Z", "request": { "notebook": "user:12345-user@example.com-notebook:62600bab-4082-4ee6-8fc3-955cee0c69cf", "type": "fast", "query": "Apollo 11 lunar module guidance computer alarms" }, "completed_at": "2026-09-29T04:57:37.329Z", "result": { "mode": "fast", "query": "Apollo 11 lunar module guidance computer alarms", "summary": "Technical analyses, flight logs, and developer accounts explore the hardware constraints and software recovery behind Apollo 11's alarms.", "sources": [ { "url": "https://klabs.org/history/apollo_11_alarms/eyles_2004/eyles_2004.htm", "title": "TALES FROM THE LUNAR MODULE GUIDANCE COMPUTER - klabs.org", "description": "Primary account by software developer explaining the 1201/1202 overload mechanics.", "cited": true }, { "url": "https://www.ibiblio.org/apollo/Documents/CherryApollo11Exegesis.pdf", "title": "Exegesis of the 1201 and 1202 Alarms Which Occurred During the Mission G Lunar Landing - Ibiblio", "description": "In-depth engineering analysis detailing how the rendezvous radar stole computer cycles.", "cited": true }, { "url": "https://space.stackexchange.com/questions/37730/why-did-a-phase-mismatch-between-the-apollo-11-lms-rr-and-agc-generate-a-large", "title": "Why did a phase mismatch between the Apollo 11 LM's RR and AGC generate a large numbers of interrupts?", "description": "Technical explanation of the phase mismatch that flooded interrupts.", "cited": true }, { "url": "https://www.forbes.com/sites/jimclash/2025/07/14/flight-controller-steve-bales-and-tension-that-led-to-mans-first-step/", "title": "Flight Controller Steve Bales And Tension That Led To Man's First Step - Forbes", "description": "Interview with Guidance Officer Steve Bales detailing the 'Go' call.", "cited": true }, { "url": "https://honeysucklecreek.net/interviews/jack_garman.html", "title": "Jack Garman interview - Honeysuckle Creek", "description": "Primary account including Jack Garman's famous alarm cheat sheet.", "cited": true }, { "url": "https://www.cbsnews.com/boston/news/margaret-hamilton-apollo-11-software-pioneer-interview/", "title": "Margaret Hamilton: MIT Software Pioneer Who Helped Save Apollo 11 Moon Mission", "description": "Overview of Margaret Hamilton's asynchronous software architecture design.", "cited": true }, { "url": "https://fredhaise.space/docs/astro-adventures/Other_Apollo_System_Integration_Issue_A11.pdf", "title": "SYSTEM INTEGRATION ISSUES IN APOLLO 11 Abstract - FredHaise.space", "description": "Debunks myths regarding system failures versus designed priority-task dropping.", "cited": true }, { "url": "https://ntrs.nasa.gov/api/citations/19910008862/downloads/19910008862.pdf", "title": "Flight Operations Apollo 11 20th Reunion - NASA Technical Reports Server (NTRS)", "description": "Official NASA flight log tracking the exact timeline of descent alarms.", "cited": true }, { "url": "https://ideas-productivity.org/assets/artifacts/hpcbp/webinar031-Apollo50th.pdf", "title": "the apollo guidance computer hardware, software and application in moon missions - IDEAS Productivity", "description": "Deep technical breakdown of the computer's executive architecture and tasks.", "cited": true }, { "url": "https://padailypost.com/2019/07/15/locals-restore-apollo-11-computer-get-it-to-run-moon-landing-program/", "title": "Locals restore Apollo 11 computer, get it to run moon-landing program - Palo Alto Daily Post", "description": "Account of engineers restoring authentic computer hardware to run descent software.", "cited": true } ] } } ``` </div> ```bash curl -sS --max-time 310 -X POST "$API/research/import" \ -H "Authorization: Bearer $USEAPI_TOKEN" -H "Content-Type: application/json" \ -d "$(jq -n --arg j "$(jq -r .jobid discover.json)" --argjson urls "$(jq '[.result.sources[0:3][].url]' discover.json)" '{jobid: $j, urls: $urls}')" ``` The import, in full ([step-08-discover-import.json](/assets/articles/gemini-notebook-bash/step-08-discover-import.json)): <div markdown="1" style="max-height:420px;overflow:auto"> ```json { "notebook": "user:12345-user@example.com-notebook:62600bab-4082-4ee6-8fc3-955cee0c69cf", "sources": [ { "source": "user:12345-user@example.com-source:62600bab-4082-4ee6-8fc3-955cee0c69cf:e4c49cf6-a319-4107-8d5e-cf3a89777938", "title": "TALES FROM THE LUNAR MODULE GUIDANCE COMPUTER - klabs.org", "kind": "web", "status": "ready", "words": 9452, "url": "https://klabs.org/history/apollo_11_alarms/eyles_2004/eyles_2004.htm", "created": "2026-09-29T04:57:39.000Z" }, { "source": "user:12345-user@example.com-source:62600bab-4082-4ee6-8fc3-955cee0c69cf:89b439a4-937a-4090-8786-78aff974b0b9", "title": "Exegesis of the 1201 and 1202 Alarms Which Occurred During the Mission G Lunar Landing - Ibiblio", "kind": "pdf", "status": "ready", "words": 3739, "url": "https://www.ibiblio.org/apollo/Documents/CherryApollo11Exegesis.pdf", "created": "2026-09-29T04:57:39.000Z" } ] } ``` </div> </details> #### 9. Start a Deep Research run `type: "deep"` runs Deep Research: Google reads dozens of web pages and writes a cited report. It takes minutes, so it starts async here and is collected in [step 12](#12-collect-the-deep-research-report), after the Studio jobs. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-gemini-notebook-v1/post-gemini-notebook-research">POST /research</a> (deep, async)</summary> ```bash curl -sS -X POST "$API/research" \ -H "Authorization: Bearer $USEAPI_TOKEN" -H "Content-Type: application/json" \ -d "$(jq -n --arg nb "$NOTEBOOK" '{notebook: $nb, type: "deep", query: "Why did the Apollo 11 landing nearly abort?", mode: "async"}')" | tee deep.json DEEP=$(jq -r .jobid deep.json) ``` It returned, in full ([step-09-deep-research-submit.json](/assets/articles/gemini-notebook-bash/step-09-deep-research-submit.json)): <div markdown="1" style="max-height:420px;overflow:auto"> ```json { "jobid": "job:e2af6631-3d2b-4630-87b1-e115620e0c4e-user:12345-user@example.com-bot:gemini_notebook", "email": "user@example.com", "type": "research", "status": "processing", "notebook": "user:12345-user@example.com-notebook:62600bab-4082-4ee6-8fc3-955cee0c69cf", "created_at": "2026-09-29T04:59:08.701Z", "request": { "notebook": "user:12345-user@example.com-notebook:62600bab-4082-4ee6-8fc3-955cee0c69cf", "type": "deep", "query": "Why did the Apollo 11 landing nearly abort?" } } ``` </div> </details> #### 10. A quiz [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts) with `type: "quiz"`. It finished in 33 seconds, within the 90-second sync wait, so the call returned the finished quiz: 6 questions in `result.content.quiz`, each with answer options, a hint and a rationale per option. Quizzes, flashcards and mind maps are JSON, ready to render in your own app. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts">POST /artifacts</a> (quiz)</summary> ```bash curl -sS -X POST "$API/artifacts" \ -H "Authorization: Bearer $USEAPI_TOKEN" -H "Content-Type: application/json" \ -d "$(jq -n --arg nb "$NOTEBOOK" '{notebook: $nb, type: "quiz", quantity: "fewer", difficulty: "medium"}')" ``` It returned, in full ([step-10-quiz-job.json](/assets/articles/gemini-notebook-bash/step-10-quiz-job.json)): <div markdown="1" style="max-height:420px;overflow:auto"> ```json { "jobid": "job:14c2a798-6c43-49a0-b728-10f8cab3e828-user:12345-user@example.com-bot:gemini_notebook", "email": "user@example.com", "type": "quiz", "status": "completed", "notebook": "user:12345-user@example.com-notebook:62600bab-4082-4ee6-8fc3-955cee0c69cf", "artifact": "user:12345-user@example.com-artifact:62600bab-4082-4ee6-8fc3-955cee0c69cf:39d36b48-c756-40bd-8593-a401def3bffb", "created_at": "2026-09-29T04:59:15.804Z", "request": { "notebook": "user:12345-user@example.com-notebook:62600bab-4082-4ee6-8fc3-955cee0c69cf", "type": "quiz", "quantity": "fewer", "difficulty": "medium" }, "completed_at": "2026-09-29T04:59:49.030Z", "result": { "title": "Apollo Quiz", "content": { "quiz": [ { "question": "According to accounts from NASA leadership, what was a primary reason Neil Armstrong was chosen over Buzz Aldrin to be the first person to step onto the lunar surface?", "answerOptions": [ { "text": "Mission planners felt Armstrong possessed a calm, quiet demeanor suitable for such a historic public figure.", "rationale": "Key leadership figures like Chris Kraft sought a quiet and humble representative similar to Charles Lindbergh for the iconic first moonwalk.", "isCorrect": true }, { "text": "Physical constraints of the Lunar Module hatch geometry prevented the pilot from exiting first without damaging the suits.", "rationale": "Although hatch clearance made egress awkward and Aldrin believed this was the reason for years, mission leadership had already decided on the order based on personal characteristics.", "isCorrect": false }, { "text": "NASA protocol mandated that the Command Module Pilot always received priority for extravehicular surface activities.", "rationale": "In previous programs like Gemini, spacewalks were typically performed by the pilot rather than the commander, contradicting the idea of a fixed protocol.", "isCorrect": false }, { "text": "Aldrin declined the first step to focus exclusively on monitoring systems inside the Lunar Module during depressurization.", "rationale": "Historical accounts indicate Aldrin actively campaigned and lobbied other astronauts to be the first person to step onto the Moon.", "isCorrect": false } ], "hint": "Consider the image NASA leadership wanted to project to the world for this historic milestone." }, { "question": "What primary issue triggered the unexpected 1201 and 1202 program alarms in the Apollo Guidance Computer during lunar descent?", "answerOptions": [ { "text": "The computer was overloaded because the rendezvous radar switch was active, sending redundant data alongside the landing radar.", "rationale": "An electrical mismatch caused the rendezvous radar to continually steal CPU processing cycles while the computer was simultaneously attempting landing calculations.", "isCorrect": true }, { "text": "High concentrations of mass under the Moon's crust created gravitational anomalies that overloaded trajectory calculations.", "rationale": "Mass concentrations (mascons) contributed to the Lunar Module traveling faster and landing longer than planned, but they were not the cause of the computer alarms.", "isCorrect": false }, { "text": "Low propellant levels in the descent stage caused rapid sensor polling that overwhelmed the computer's memory.", "rationale": "Fuel sloshing triggered early low-fuel warnings in the cabin, but this system was distinct from the guidance computer's executive overflow alarms.", "isCorrect": false }, { "text": "Excess air pressure inside the docking tunnel corrupted digital communication signals between modules.", "rationale": "Residual tunnel pressure was speculated as a reason for the initial trajectory overshoot, not a source of computer processing delays.", "isCorrect": false } ], "hint": "Focus on how hardware switches for dual radar tracking affected processor capacity." }, { "question": "Which factor was explicitly excluded as a consideration when selecting Site 2 in the Sea of Tranquility for the Apollo 11 landing?", "answerOptions": [ { "text": "Scientific value and geological diversity of the lunar surface", "rationale": "The Site Selection Board prioritized landing safety, slope, and radar clarity over scientific interest for the first crewed landing.", "isCorrect": true }, { "text": "Maintaining a free-return trajectory back to Earth", "rationale": "Safety requirements dictated that the path must allow a passive return to Earth if propulsion failed.", "isCorrect": false }, { "text": "Ensuring a general terrain slope of less than two degrees", "rationale": "A nearly flat landing zone was required to keep the Lunar Module stable upon touchdown.", "isCorrect": false }, { "text": "Restricting the Sun angle behind the Lunar Module between 7 and 20 degrees", "rationale": "Proper shadow definition and thermal control required strict sun-angle constraints during the landing approach.", "isCorrect": false } ], "hint": "Think about whether operational safety or academic discovery took priority for the first landing." }, { "question": "How did Buzz Aldrin resolve the damaged main engine circuit breaker inside the Lunar Module prior to lunar ascent?", "answerOptions": [ { "text": "He used the nonconductive tip of a felt-tip pen to push the breaker in.", "rationale": "A standard Duro felt-tip pen provided a safe, nonconductive tool to depress the broken switch stem and arm the engine.", "isCorrect": true }, { "text": "He struck the control panel using the geologist's sampling hammer to force electrical contact.", "rationale": "The hammer was used on the lunar surface for core tube sampling, not for delicate internal electronics repair.", "isCorrect": false }, { "text": "He rewired the circuit using spare cables from the Lunar Equipment Conveyor.", "rationale": "The Lunar Equipment Conveyor was a mechanical cable pulley used for hoisting rock boxes, not electrical wiring.", "isCorrect": false }, { "text": "Mission Control initiated an automated remote command override from Earth.", "rationale": "The astronauts had to physically engage the broken breaker inside the cabin to complete the circuit for engine ignition.", "isCorrect": false } ], "hint": "Recall a common everyday writing instrument carried in the astronauts' gear." }, { "question": "Why was the initial design of the Apollo 11 mission emblem rejected by Manned Spacecraft Center Director Bob Gilruth?", "answerOptions": [ { "text": "The eagle's extended, bare talons were perceived as looking too warlike.", "rationale": "To project a message of peace, the design was altered so the olive branch was held in the eagle's talons rather than its beak.", "isCorrect": true }, { "text": "The shadow on the Earth in the background was rendered on the wrong side.", "rationale": "Although Michael Collins acknowledged that the lighting on Earth was artistically incorrect, this was not the cause for official rejection.", "isCorrect": false }, { "text": "The patch included astronaut surnames, violating the requirement for universal representation.", "rationale": "The astronauts themselves decided to leave their names off the emblem so it would represent everyone who worked on the program.", "isCorrect": false }, { "text": "The call sign 'Columbia' was omitted from the outer ring of the insignia.", "rationale": "The crew chose to use 'Apollo 11' instead of spelled-out numerals or module names to ensure clarity for non-English speakers.", "isCorrect": false } ], "hint": "Look at the symbol of peace and where it was moved on the final patch." }, { "question": "What was the fate of the uncrewed Soviet probe Luna 15 during the Apollo 11 mission?", "answerOptions": [ { "text": "It crashed in Mare Crisium during descent while attempting to retrieve lunar samples ahead of Apollo 11.", "rationale": "Luna 15 was launched in a desperate attempt to collect lunar soil and return to Earth first, but it impacted the Moon while Armstrong and Aldrin were on the surface.", "isCorrect": true }, { "text": "It successfully landed, collected soil, and returned to Earth hours before Apollo 11 launched.", "rationale": "The mission failed during its landing attempt and did not return any samples to Earth.", "isCorrect": false }, { "text": "It failed to reach lunar orbit due to a launcher stage malfunction over the Atlantic.", "rationale": "Luna 15 successfully reached lunar orbit ahead of Apollo 11, but malfunctioned during its actual landing descent.", "isCorrect": false }, { "text": "It was deliberately redirected into a heliocentric orbit to avoid radio interference with Columbia.", "rationale": "It was the third stage of Saturn V (S-IVB) that was sent into solar orbit, whereas Luna 15 crashed directly onto the lunar surface.", "isCorrect": false } ], "hint": "Consider the competitive automated sample-return attempt made by the Soviet Union simultaneously with Apollo 11." } ], "topics": { "covered": [ "Apollo 11 Crew Selection and Decision Making", "Lunar Landing Operations and Computer Anomalies", "Mission Insignia and Landing Site Criteria", "Space Race Geopolitics and Concurrent Robotic Missions" ], "followUp": [ "Apollo Spacecraft Systems Architecture and Engineering", "Analysis of Returned Lunar Samples and Mineralogy", "Project Gemini Precursor Flight Operations" ] } } } } ``` </div> </details> #### 11. An Audio Overview and an infographic Audio and video take minutes, so both went in async and were polled. The infographic finished in 1 minute 45 seconds, the Audio Overview in 4 minutes 36 seconds. Each finished job lists its files, and every file link goes through [GET /artifacts/download](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts-download) with your token (`m4a`, `mp4`, `pdf`, `pptx`, `png`). Both are shown in [Results](#results). <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts">POST /artifacts</a> (audio + infographic, async), <a href="/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid">GET /jobs/<code>jobid</code></a>, download</summary> ```bash AUDIO=$(curl -sS -X POST "$API/artifacts" \ -H "Authorization: Bearer $USEAPI_TOKEN" -H "Content-Type: application/json" \ -d "$(jq -n --arg nb "$NOTEBOOK" '{notebook: $nb, type: "audio", format: "brief", length: "short", mode: "async"}')" | jq -r .jobid) INFOGRAPHIC=$(curl -sS -X POST "$API/artifacts" \ -H "Authorization: Bearer $USEAPI_TOKEN" -H "Content-Type: application/json" \ -d "$(jq -n --arg nb "$NOTEBOOK" '{notebook: $nb, type: "infographic", orientation: "portrait", style: "sketch_note", mode: "async"}')" | jq -r .jobid) rm -f files.txt for JOBID in "$AUDIO" "$INFOGRAPHIC"; do until curl -sS "$API/jobs/$(enc "$JOBID")" -H "Authorization: Bearer $USEAPI_TOKEN" > job.json && jq -e '.status == "completed" or .status == "failed"' job.json > /dev/null; do sleep 15 done cat job.json jq -r '.result.files[]?.url' job.json >> files.txt done while read -r url; do curl -sS -H "Authorization: Bearer $USEAPI_TOKEN" -OJ "$url" done < files.txt ``` The audio job, in full ([step-11-audio-job.json](/assets/articles/gemini-notebook-bash/step-11-audio-job.json)): <div markdown="1" style="max-height:420px;overflow:auto"> ```json { "jobid": "job:1d3937ef-d3aa-4bff-a736-4b1e320eab14-user:12345-user@example.com-bot:gemini_notebook", "email": "user@example.com", "type": "audio", "status": "completed", "notebook": "user:12345-user@example.com-notebook:62600bab-4082-4ee6-8fc3-955cee0c69cf", "artifact": "user:12345-user@example.com-artifact:62600bab-4082-4ee6-8fc3-955cee0c69cf:63e7d7a4-bd12-4974-9848-459621414913", "created_at": "2026-09-29T04:59:55.773Z", "request": { "notebook": "user:12345-user@example.com-notebook:62600bab-4082-4ee6-8fc3-955cee0c69cf", "type": "audio", "format": "brief", "length": "short" }, "completed_at": "2026-09-29T05:04:31.632Z", "result": { "title": "Fifty Seconds of Fuel and Lunar Isolation", "duration": 91, "files": [ { "format": "m4a", "mimeType": "audio/mp4", "url": "https://api.useapi.net/v1/gemini-notebook/artifacts/download?artifact=user%3A12345-user%40example.com-artifact%3A62600bab-4082-4ee6-8fc3-955cee0c69cf%3A63e7d7a4-bd12-4974-9848-459621414913&format=m4a" } ] } } ``` </div> The infographic job, in full ([step-11-infographic-job.json](/assets/articles/gemini-notebook-bash/step-11-infographic-job.json)): <div markdown="1" style="max-height:420px;overflow:auto"> ```json { "jobid": "job:fef4a209-2227-450e-8be3-b5c0e4189a19-user:12345-user@example.com-bot:gemini_notebook", "email": "user@example.com", "type": "infographic", "status": "completed", "notebook": "user:12345-user@example.com-notebook:62600bab-4082-4ee6-8fc3-955cee0c69cf", "artifact": "user:12345-user@example.com-artifact:62600bab-4082-4ee6-8fc3-955cee0c69cf:1d548a2c-f823-4406-a600-aea523c14e80", "created_at": "2026-09-29T05:00:01.939Z", "request": { "notebook": "user:12345-user@example.com-notebook:62600bab-4082-4ee6-8fc3-955cee0c69cf", "type": "infographic", "orientation": "portrait", "style": "sketch_note" }, "completed_at": "2026-09-29T05:01:47.120Z", "result": { "title": "Apollo 11 Mission Infographic Overview", "files": [ { "format": "png", "mimeType": "image/png", "url": "https://api.useapi.net/v1/gemini-notebook/artifacts/download?artifact=user%3A12345-user%40example.com-artifact%3A62600bab-4082-4ee6-8fc3-955cee0c69cf%3A1d548a2c-f823-4406-a600-aea523c14e80&format=png", "width": 1536, "height": 2752 } ], "text": "OVERVIEW\n\nApollo 11: Humanity's First Steps on the Moon\n\nJuly 1969: NASA fulfills JFK's goal.\nCrew: Armstrong, Aldrin, Collins.\nCulmination of the Space Race, entering a new era of exploration.\n\n\nOUTBOUND JOURNEY & HISTORIC LANDING (JULY 16-20, 1969)\n\n- Saturn V Lift-off from Kennedy Space Center: July 16, 1969, carrying Neil Armstrong, Buzz Aldrin, and Michael Collins. [Illustration shows the rocket launching upwards on flames and smoke, with a sketch of the three crew members looking out from a capsule window].\n- 1201 & 1202 Guidance Computer Alarms: Executive overflows overloaded the computer; software recovery prevented abort. [Illustration shows the lunar module highlighted by dynamic alarm lines and a red flashing beacon light].\n- Eagle Lands at Tranquility Base Under Manual Control: Armstrong manually piloted past boulders; landed safely with under 50 seconds of fuel remaining. [Illustration of the lunar lander descending onto the cratered surface of the Moon].\n\n\nMOONWALK & SAFE RETURN (JULY 20-24, 1969)\n\n- Historic Quote: \"That's one small step for [a] man, one giant leap for mankind\"\n- Broadcast Details: 02:56 UTC, watched live by 600 million people. [Illustration shows a small television set next to an astronaut boot leaving a detailed footprint in the lunar soil with a giant Moon in the background].\n- Lunar Samples: 21.55 kg of Lunar Samples Collected. Spent 2.5 hours exploring, deploying instruments, collecting rocks. [Illustration depicts a mechanical balance scale weighing rocks and a tied sample bag].\n- Return Journey: Safe Splashdown in the Pacific Ocean. Crew successfully returned July 24; recovered by USS Hornet. [Illustrations depict the ascent stage blasting off from the lunar surface, followed by the spacecraft descending under a striped parachute into ocean waters near a ship]." } } ``` </div> The files: [the Audio Overview (m4a)](https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-audio-overview-brief-apollo11-0929.m4a){:target="_blank"} and [the infographic (png)](https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-infographic-sketch-note-apollo11-0929.png){:target="_blank"}. </details> #### 12. Collect the Deep Research report The Deep Research run from step 9 finished in 3 minutes 40 seconds, while the Studio jobs ran: "Anatomy of a Lunar Descent: Systems Architecture, Hardware Anomaly, and Human Decision-Making in the Apollo 11 Landing Near-Abort", 26,878 characters of Markdown with `[cite: n]` markers, on 30 sources, 24 of them cited. Imported as a source (3,146 words), it grounds every later answer and artifact. `urls: []` with `report: true` imports the report alone, and leaving `urls` out imports it with every cited source, as the app's Import button does. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid">GET /jobs/<code>jobid</code></a> + <a href="/docs/api-gemini-notebook-v1/post-gemini-notebook-research-import">POST /research/import</a></summary> ```bash until curl -sS "$API/jobs/$(enc "$DEEP")" -H "Authorization: Bearer $USEAPI_TOKEN" > deep.json && jq -e '.status == "completed" or .status == "failed"' deep.json > /dev/null; do sleep 15 done cat deep.json ``` The finished Deep Research job, in full ([step-12-deep-research-job.json](/assets/articles/gemini-notebook-bash/step-12-deep-research-job.json)): <div markdown="1" style="max-height:420px;overflow:auto"> ```json { "jobid": "job:e2af6631-3d2b-4630-87b1-e115620e0c4e-user:12345-user@example.com-bot:gemini_notebook", "email": "user@example.com", "type": "research", "status": "completed", "notebook": "user:12345-user@example.com-notebook:62600bab-4082-4ee6-8fc3-955cee0c69cf", "created_at": "2026-09-29T04:59:08.701Z", "request": { "notebook": "user:12345-user@example.com-notebook:62600bab-4082-4ee6-8fc3-955cee0c69cf", "type": "deep", "query": "Why did the Apollo 11 landing nearly abort?" }, "completed_at": "2026-09-29T05:02:48.478Z", "result": { "mode": "deep", "query": "Why did the Apollo 11 landing nearly abort?", "report": { "title": "Anatomy of a Lunar Descent: Systems Architecture, Hardware Anomaly, and Human Decision-Making in the Apollo 11 Landing Near-Abort", "markdown": "# Anatomy of a Lunar Descent: Systems Architecture, Hardware Anomaly, and Human Decision-Making in the Apollo 11 Landing Near-Abort\n\nThe Apollo 11 lunar landing on July 20, 1969, stands as one of the defining technological achievements of the twentieth century [cite: 1, 2]. However, the descent of the Lunar Module (*Eagle*) to the Sea of Tranquility was extraordinarily close to termination [cite: 3, 4]. During the twelve-minute powered descent phase, a complex convergence of digital computer hardware overloads, unmapped trajectory deviations, telemetry dropouts, and propellant sloshing dynamics repeatedly pushed the mission to the brink of an immediate abort [cite: 2, 3, 5, 6]. \n\nThe near-abort of Apollo 11 was not caused by a single critical failure, but rather by the dynamic interaction of tightly coupled physical and software systems operating under strict real-time constraints [cite: 7, 8]. Examining these factors reveals how advanced software engineering, rigorous simulation protocols, and real-time decision-making prevented what could have been a catastrophic mission failure [cite: 9, 10, 11].\n\n## Architectural Constraints of the Apollo Guidance Computer\n\nTo comprehend the failure modes that manifested during powered descent, one must first examine the operational constraints of the Apollo Guidance Computer (AGC) designed by the Massachusetts Institute of Technology (MIT) Instrumentation Laboratory [cite: 2, 12]. Operating at a clock speed of $1.024\\text{ MHz}$ with a cycle time of $11.7\\text{ }\\mu\\text{s}$, the AGC was a fixed-point, 16-bit processor utilizing 14 bits of data, one sign bit, and one parity bit [cite: 2]. Its physical memory was split into two distinct structures: a 36,864-word fixed read-only memory (core rope ROM) housing executable code and constants, and a 2,048-word erasable random-access memory (magnetic core RAM) reserved for variable system data [cite: 2, 12].\n\n| Memory Architectural Parameter | Allocation Specification | System Function |\n| :--- | :--- | :--- |\n| **Fixed Memory (Core Rope ROM)** | 36,864 Words (15-bit data) | Permanent storage of executable flight programs, routines, and physical constants [cite: 2, 12]. |\n| **Erasable Memory (Magnetic Core RAM)** | 2,048 Words Total | Volatile scratchpad memory for state variables, counters, and execution buffers [cite: 2, 12]. |\n| **Executive Core Sets** | 8 Allocation Blocks (12 words each) | Temporary memory reserved for job parameters, entry addresses, and control flags [cite: 4, 13]. |\n| **Vector Accumulators (VAC Areas)** | 5 Allocation Blocks (5 words each) | Scratchpad buffers dedicated to complex vector mathematics and guidance calculations [cite: 4, 8]. |\n| **Multipurpose Accumulator (MPAC)** | 7 Words | High-speed temporary storage for intermediate mathematical values [cite: 4]. |\n\nBecause erasable memory was extremely limited, MIT software engineers led by Margaret Hamilton, Don Eyles, and Peter Adler designed an asynchronous, priority-driven real-time operating system [cite: 2, 9, 12]. The software execution was managed by two key routines within the operating system: the Executive and NOVAC [cite: 4]. The Executive allocated RAM and CPU cycles based on strict job priorities [cite: 4, 9]. When a new task was initiated, the Executive scanned available memory using NOVAC to assign one of eight available Core Sets and, if vector mathematics were required, one of five available Vector Accumulators (VAC areas) [cite: 4, 8, 13].\n\nWhen high-priority tasks—such as inertial guidance calculations or thruster attitude control—demanded execution while lower-priority routines were running, the Executive interrupted the lower-priority tasks [cite: 4, 9, 13]. If the Executive ran out of Core Sets or VAC areas because tasks were queuing faster than they could complete, the system was programmed to invoke a emergency safety routine called `BAILOUT` [cite: 8, 14]. The `BAILOUT` routine flushed all non-essential temporary jobs from the Executive queue, cleared the temporary RAM allocations, and rebooted the guidance computer, maintaining primary attitude control and navigation vector processing without crashing the machine [cite: 4, 8, 9, 14].\n\n## Hardware Integration and the Root Cause of the Program Alarms\n\nAt Ground Elapsed Time (GET) 102:38:22, approximately 30,000 feet above the lunar surface during Powered Descent Initiation (PDI), the DSKY display flashed a `1202` program alarm, followed shortly by `1201` program alarms [cite: 4, 8, 15]. In the cockpit, Commander Neil Armstrong and Lunar Module Pilot Buzz Aldrin were confronted with cryptic codes that were not explicitly detailed in their operational procedure manuals [cite: 2, 3].\n\nThe technical root cause of these alarms was an unforeseen hardware interaction between the spacecraft's electrical systems and the guidance computer [cite: 7, 16]. Operational flight procedures directed the crew to place the Rendezvous Radar (RR) switch in `AUTO` mode prior to descent [cite: 2, 7]. This ensured that the radar antenna would be powered, warmed up, and tracking the Command Module (*Columbia*) in orbit in the event of an immediate abort and emergency ascent [cite: 2, 7, 8].\n\nHowever, the power supply driving the Rendezvous Radar operated at an $800\\text{ Hz}$ excitation frequency, whereas the AGC Coupling Data Units (CDUs)—the hardware interfaces reading the radar antenna angles—were referenced to an independent $400\\text{ Hz}$ power supply [cite: 7, 17]. A phase mismatch between these two power supplies caused the radar resolver hardware to emit continuous, high-frequency signal fluctuations into the guidance computer interface [cite: 7, 17].\n\nTo process antenna angle updates without consuming software processing steps, the AGC hardware utilized direct memory access instructions known as \"cycle stealing\" or unprogrammed instructions [cite: 17, 18]. Each pulse generated by the unstable radar interface forced the computer's central processor to pause its main execution for an $11.7\\text{ }\\mu\\text{s}$ memory cycle to increment or decrement the internal angle counters [cite: 2, 17]. Because of the power supply phase mismatch, the radar interface inundated the computer with thousands of unprogrammed interrupts per second, stealing approximately $13\\%$ to $15\\%$ of the processor's total operating capacity [cite: 7, 8, 13].\n\nThe lunar landing software had been engineered to consume roughly $90\\%$ of the computer's operational capacity, leaving a duty cycle margin of less than $10\\%$ [cite: 8, 17]. Primary descent operations were governed by a fixed two-second guidance cycle known as `SERVICER` [cite: 8, 17]. Every two seconds, `SERVICER` was required to perform a comprehensive chain of sequential tasks:\n1. Sample internal accelerometer data from the Inertial Measurement Unit [cite: 8, 17].\n2. Compute the vehicle's state vectors and trajectory updates [cite: 8, 17].\n3. Calculate throttle settings for the Descent Propulsion System engine [cite: 8, 17].\n4. Command attitude control jet firings [cite: 8, 17].\n5. Refresh the telemetry and numerical displays on the DSKY unit [cite: 8, 17].\n\nWhen the $13\\%-15\\%$ hardware cycle-stealing load was superimposed on `SERVICER`'s $90\\%$ computational requirement, the total CPU demand exceeded $100\\%$ capacity [cite: 7, 8]. Consequently, `SERVICER` was unable to complete its execution string within the allocated two-second window [cite: 8]. When the Executive attempted to spawn a new `SERVICER` task while the previous instance was still active and holding its assigned Core Set and VAC area, the Executive exhausted its available memory allocations [cite: 8]. The computer responded by executing `BAILOUT`, clearing the queue, resetting the processor, and displaying a `1202` alarm (indicating Core Set exhaustion) or a `1201` alarm (indicating VAC area exhaustion) [cite: 8, 14].\n\n## Mission Control Dynamics and the Critical \"Go\" Decision\n\nThe appearance of the `1202` alarm inside Mission Control created immediate tension [cite: 2]. Armstrong's voice over the communications link reflected the urgency of the moment as he requested a status evaluation: *\"Give us a reading on the 1202 Program Alarm\"* [cite: 4, 8, 14]. Neither the crew nor the majority of ground controllers understood the precise operational boundary of executive overflow alarms [cite: 2, 3, 16].\n\nThe factor that prevented an erroneous mission abort call was a simulation exercise conducted less than two weeks prior to launch [cite: 10, 11]. During that final training run, Guidance Officer (GUIDO) Steve Bales had called an abort when a computer alarm flashed on his console [cite: 10, 11]. Subsequent post-simulation analysis revealed that the abort was unnecessary because the guidance software was still maintaining accurate trajectory control [cite: 11, 16]. Flight Director Gene Kranz subsequently mandated that Bales catalog every possible computer alarm code and establish explicit operational protocols for abort versus non-abort conditions [cite: 10, 11, 19].\n\nBales' support specialist in the Mission Control backroom, 24-year-old Jack Garman, compiled a handwritten handwritten document listing every AGC error code and its operational significance [cite: 3, 10, 14]. Garman recognized `1201` and `1202` as `BAILOUT` restart commands [cite: 11, 14, 19]. He understood that as long as the alarms occurred at discrete intervals—allowing the computer to clear its temporary storage buffers without dropping core state vectors—the flight software was protecting itself while continuing to calculate primary navigation guidance [cite: 4, 9, 14].\n\n| Timeline (GET) | Flight Participant | Action / Verbal Transmission | Operational Significance |\n| :--- | :--- | :--- | :--- |\n| **102:38:22** | DSKY Unit | Displays `1202` Program Alarm [cite: 4, 15]. | Indicates Executive Core Set memory exhaustion [cite: 8]. |\n| **102:38:30** | Neil Armstrong | *\"It's a 1202.\"* [cite: 14] | Crew alerts Mission Control to system anomaly [cite: 2, 14]. |\n| **102:38:42** | Neil Armstrong | *\"Give us a reading on the 1202 Program Alarm.\"* [cite: 4, 8, 14] | Commander demands real-time guidance assessment [cite: 4, 14]. |\n| **Backroom Loop** | Jack Garman | Consults handwritten alarm reference document [cite: 3, 10, 14]. | Advises GUIDO that alarm is non-fatal if intermittent [cite: 8, 14]. |\n| **Flight Loop** | Steve Bales | Evaluates telemetry; issues \"GO\" recommendation [cite: 3, 4, 8]. | Verifies state vectors and navigation accuracy [cite: 3, 8]. |\n| **102:38:53** | Charlie Duke (CapCom) | *\"Roger. We're Go on that alarm.\"* [cite: 4, 14] | Official authorization relayed to proceed with descent [cite: 4, 14]. |\n\nWhen the `1202` alarm triggered during the descent, Garman informed Bales that the landing could continue provided the alarm did not become continuous [cite: 8, 14]. Bales quickly cross-checked the spacecraft's primary trajectory data, verified that altitude and velocity state vectors were within safe margins, and recommended a \"GO\" to Gene Kranz [cite: 3, 4, 8]. Capcom Charlie Duke then transmitted the decision to *Eagle*: *\"We're Go on that alarm\"* [cite: 4, 14]. \n\nThis decision highlighted the resilience built into Margaret Hamilton's software design [cite: 9]. Rather than suffering a catastrophic system freeze, the computer prioritized critical navigation computations, shed secondary tasks, and refreshed its memory structures [cite: 4, 9, 13]. The computer was operating as designed under extreme overload conditions [cite: 4, 14].\n\n## Trajectory Deviations and the Downrange Overshoot\n\nWhile Mission Control resolved the computer alarms, a physical trajectory error was unfolding [cite: 5]. As the spacecraft pitched over into a windows-up orientation to allow visual observation of the lunar surface during program `P64`, Armstrong realized that *Eagle* was targeting a landing location approximately 3,000 feet (915 meters) downrange of the pre-planned touchdown site [cite: 5].\n\nThis trajectory overshoot resulted from three unmodeled physical perturbations:\n* Residual air pressure trapped in the docking tunnel between the Command Module and Lunar Module had not been fully evacuated prior to physical separation, acting as a pneumatic piston that imparted an uncalculated velocity increment ($\\Delta v$) along the flight path [cite: 5].\n* Localized mass concentrations beneath the lunar crust (mascons) exerted unmodeled gravitational pull on the vehicle during its preceding low lunar orbits, distorting the orbital parameters pre-loaded into the guidance computer [cite: 1, 5].\n* Accumulated state vector propagation errors in ground-based tracking updates created discrepancies in downrange position calculations [cite: 5].\n\nThe 3,000-foot positional shift directed *Eagle*'s automatic guidance system toward the boulder-strewn ejecta field of \"West Crater\"—a large crater filled with rocks up to several meters in diameter [cite: 3, 20]. Landing in this terrain risked structural damage, landing gear failure, or tipping the vehicle upon touchdown [cite: 1, 20].\n\n## Manual Maneuvering, Fuel Slosh, and the Fuel Crisis\n\nRecognizing the hazard posed by the boulder field, Armstrong took manual control of the spacecraft's trajectory [cite: 3, 14]. At an altitude of approximately 500 feet, he overridden the automatic landing program `P64` and selected `P66` (attitude hold / manual rate-of-descent mode) at GET 102:41:53 [cite: 3, 15, 20]. Under `P66`, Armstrong adjusted the vehicle's pitch and roll manually to translate forward past West Crater, while the guidance computer automatically managed the thrusters to maintain attitude stability and execute descent rate inputs from the control stick [cite: 3, 15, 20].\n\nExtending the flight path downrange to find a smooth landing site created a severe fuel management challenge [cite: 3, 20]. The additional flight time rapidly depleted the hypergolic propellants inside the Descent Propulsion System (DPS) tanks [cite: 20].\n\nThis fuel margin issue was exacerbated by fluid dynamics inside the propellant tanks [cite: 6, 20]. As Armstrong executed manual translation maneuvers, the remaining liquid nitrogen tetroxide and aerozine-50 propellants sloshed back and forth within the spherical tanks [cite: 6, 20]. This sloshing motion uncovered the internal low-level sensors prematurely, latching the \"Low Quantity\" warning light earlier than actual fuel levels warranted [cite: 6].\n\nThe early latching of the fuel quantity sensor initiated a mandatory countdown clock in Mission Control [cite: 6, 20]. Flight rules dictated that if the spacecraft reached \"Bingo fuel\"—the threshold where remaining propellant was sufficient only to perform an emergency ascent ignition and rendezvous—the crew was required to abort immediately [cite: 6, 20]. \n\nCapcom Charlie Duke issued the \"60 seconds\" warning call, followed by the \"30 seconds\" warning call as the remaining fuel margin dwindled [cite: 6, 20]. Maintaining a low vertical descent rate while maneuvering over dust clouds kicked up by the descent engine exhaust, Armstrong landed *Eagle* at MET 102:45:40 [cite: 20]. Post-landing analysis confirmed that *Eagle* touched down with approximately 20 to 25 seconds of fuel remaining before reaching the mandatory Bingo abort limit [cite: 20].\n\n## Comprehensive Matrix of Descent Anomalies\n\nThe following matrix synthesizes the technical causes, operational impacts, and engineering mitigations associated with the failure modes encountered during the Apollo 11 descent.\n\n| Anomaly Category | Primary Technical Cause | System Manifestation | Operational Impact | Engineering & Procedural Mitigation |\n| :--- | :--- | :--- | :--- | :--- |\n| **Executive Overload Alarms** | Phase mismatch ($800\\text{ Hz}$ vs $400\\text{ Hz}$) between radar and CDU interface causing CPU cycle stealing [cite: 7, 17]. | `1201` and `1202` Program Alarms; memory structure exhaustion [cite: 8]. | Non-essential tasks dropped; DSKY updates temporarily suspended [cite: 8, 9, 14]. | Asynchronous defensive priority scheduling (`BAILOUT`) [cite: 8, 9]; Garman/Bales \"GO\" protocol [cite: 3, 14]. |\n| **Downrange Position Offset** | Residual pressure in docking tunnel during separation + lunar mascon gravitational pull [cite: 1, 5]. | Trajectory shifted $3,000\\text{ ft}$ downrange from target site [cite: 5]. | Automatic guidance targeted West Crater boulder field [cite: 3, 20]. | Armstrong engaged `P66` manual rate-of-descent mode to fly clear of rocks [cite: 3, 15, 20]. |\n| **Telemetry Disruption** | Vehicle pitch/yaw attitude obscured line-of-sight for S-Band High Gain Antenna [cite: 15, 21]. | Intermittent Loss of Signal (LOS) and telemetry noise in MCC [cite: 21, 22]. | Ground controllers lost real-time engineering telemetry streams [cite: 3, 21]. | Switched to omni-directional antennas; CapCom requested vehicle re-orientation [cite: 23, 24]. |\n| **Propellant Depletion Risk** | Propellant sloshing during `P66` manual translation uncovered sensors early [cite: 6, 20]. | Early latching of Low Quantity sensor light [cite: 6]. | Accelerated \"Bingo fuel\" countdown in Mission Control [cite: 6, 20]. | Refined post-flight slosh baffles; landing completed before zero-fuel threshold [cite: 6, 20]. |\n\n## Systems Engineering Synthesis and Industry Legacy\n\nThe near-abort of Apollo 11 offers fundamental lessons for aerospace software design, hardware system integration, and operational risk management.\n\n### Software Resilience as a Primary Defensive Layer\nThe Apollo Guidance Computer demonstrated that complex systems operating in dynamic environments cannot rely solely on the total elimination of unexpected hardware behavior or input noise [cite: 2, 9, 13]. By implementing priority-driven task scheduling and asynchronous execution, MIT software engineers built an operating system capable of surviving unexpected real-time overloads [cite: 9, 13]. Rather than locking up or suffering a catastrophic hardware crash when overloaded, the AGC shed non-essential processing load, cleared its memory queues, and preserved safety-critical navigation routines [cite: 4, 9, 14]. This defensive architecture laid the conceptual groundwork for modern fault-tolerant avionics, fly-by-wire flight control systems, and autonomous real-time computing platforms [cite: 13].\n\n### Human Flexibility in Automated Systems\nAutomated flight guidance systems provide high precision during nominal operations, but struggle when confronted with unmodeled physical terrain hazards [cite: 3]. Had Apollo 11 relied entirely on automatic landing guidance (`P64`), the vehicle would have touched down inside the West Crater boulder field, risking structural failure [cite: 3, 5, 20]. Neil Armstrong’s manual intervention using `P66` demonstrated the necessity of human-in-the-loop control modes in high-risk operational environments [cite: 3, 14]. System designs must provide human operators with transparent, real-time data and manual override capability when automated guidance parameters fail [cite: 3].\n\n### Interface Coupling and Cascading System Hazards\nThe Apollo 11 descent illustrates how isolated, non-critical hardware anomalies can combine to create severe system-wide operational hazards. The electrical phase mismatch in the radar interface was completely unrelated to the physical gas pressure trapped in the docking tunnel [cite: 5, 7]. However, when combined, the resulting computer alarms and downrange trajectory offset forced a manual extended hover that nearly exhausted the vehicle's propellant reserves [cite: 3, 8, 20]. Modern systems engineering protocols emphasize rigorous cross-domain interface reviews to identify and decouple potential cascading failure pathways before deployment [cite: 7].\n\n### Simulation Protocols and Operational Preparedness\nThe rapid resolution of the `1202` alarm during powered descent was a direct result of NASA's simulation practices [cite: 10, 11]. The failed simulation run two weeks prior to launch forced ground controllers to analyze edge cases and establish clear operational thresholds for computer overflow codes [cite: 10, 11, 19]. When the actual emergency occurred, Steve Bales and Jack Garman did not need to diagnose the underlying electrical cause of the radar pulse anomaly; they only needed to confirm that core state vector processing remained valid [cite: 3, 8, 14]. Pre-flight simulation protocols that stress systems to failure remain an essential tool for training operational decision-makers to manage high-stress emergencies [cite: 10, 11, 23].\n\nUltimately, Apollo 11 succeeded because its hardware, software, and human support systems were designed to absorb unforeseen disruptions [cite: 9, 14, 23]. The landing remains a model of engineering resilience: a mission saved not by the absence of system anomalies, but by the ability to detect, manage, and overcome them in real time [cite: 9, 14, 23].\n\n---\n\n1. Apollo 11 - Wikipedia, [https://en.wikipedia.org/wiki/Apollo_11](https://en.wikipedia.org/wiki/Apollo_11)\n2. Apollo 11 Lunar Surface Journal: Program Alarms - NASA, [https://www.nasa.gov/wp-content/uploads/static/history/alsj/a11/a11.1201-fm.html?utm_source=chatgpt.com](https://www.nasa.gov/wp-content/uploads/static/history/alsj/a11/a11.1201-fm.html?utm_source=chatgpt.com)\n3. Troubleshooting 101 (1201 actually, and 1202 too) - Smithsonian Magazine, [https://www.smithsonianmag.com/air-space-magazine/troubleshooting-101-1201-actually-and-1202-too-111339271/](https://www.smithsonianmag.com/air-space-magazine/troubleshooting-101-1201-actually-and-1202-too-111339271/)\n4. Apollo 11's \"1202 Alarm\" Explained - Discover Magazine, [https://www.discovermagazine.com/apollo-11s-1202-alarm-explained-185](https://www.discovermagazine.com/apollo-11s-1202-alarm-explained-185)\n5. 19720021182.pdf - NASA Technical Reports Server (NTRS), [https://ntrs.nasa.gov/api/citations/19720021182/downloads/19720021182.pdf](https://ntrs.nasa.gov/api/citations/19720021182/downloads/19720021182.pdf)\n6. A Visit to the Snowman - Apollo Journals, [https://apollojournals.org/alsj//a12/a12.landing.html](https://apollojournals.org/alsj//a12/a12.landing.html)\n7. Reconstructing Apollo 11's Powered Descent: A technical deep-dive based on 37 primary sources. Feedback welcome! - Reddit, [https://www.reddit.com/r/apollo/comments/1ry3c9c/reconstructing_apollo_11s_powered_descent_a/](https://www.reddit.com/r/apollo/comments/1ry3c9c/reconstructing_apollo_11s_powered_descent_a/)\n8. Apollo 11 and Other Screw-Ups - Don Eyles, [https://www.doneyles.com/LM/Tales.html](https://www.doneyles.com/LM/Tales.html)\n9. *The code that helped land humans on the Moon.* In 1969, during Apollo 11's descent, the onboard computer experienced unexpected 1201/1202 alarms. Yet its software continued priori | Giggle Grid - Facebook, [https://www.facebook.com/gigglegrid2/videos/-the-code-that-helped-land-humans-on-the-moon-in-1969-during-apollo-11s-descent-/1794532518247381/](https://www.facebook.com/gigglegrid2/videos/-the-code-that-helped-land-humans-on-the-moon-in-1969-during-apollo-11s-descent-/1794532518247381/)\n10. Apollo 11's Momentous Landing Came Down to One Tough Call - Space, [https://www.space.com/apollo-11-guidance-officer-remembers-moon-landing-drama.html](https://www.space.com/apollo-11-guidance-officer-remembers-moon-landing-drama.html)\n11. The inside story of Apollo 11's nail-biting descent to the surface of the moon - CBS News, [https://www.cbsnews.com/news/apollo-11-moon-landing-anniversary-nail-biting-descent-to-the-surface-of-the-moon/](https://www.cbsnews.com/news/apollo-11-moon-landing-anniversary-nail-biting-descent-to-the-surface-of-the-moon/)\n12. Apollo 11 Lunar Surface Journal: Program Alarms - NASA, [https://www.nasa.gov/wp-content/uploads/static/history//alsj/a11/a11.1201-pa.html](https://www.nasa.gov/wp-content/uploads/static/history//alsj/a11/a11.1201-pa.html)\n13. We're Go On That Alarm: Inside the Apollo Operating System | by Joe Kutner | Software's Giant Leap | Medium, [https://medium.com/softwares-giant-leap/were-go-on-that-alarm-inside-the-apollo-operating-system-8d753e7a1e17](https://medium.com/softwares-giant-leap/were-go-on-that-alarm-inside-the-apollo-operating-system-8d753e7a1e17)\n14. Error 1202 - David Nuñez, [https://davidnunez.com/error-1202/](https://davidnunez.com/error-1202/)\n15. Apollo by the Numbers - NASA, [https://www.nasa.gov/wp-content/uploads/2023/04/sp-4029.pdf](https://www.nasa.gov/wp-content/uploads/2023/04/sp-4029.pdf)\n16. The Real Story Behind the Apollo 11 Computer Error | WSJ - YouTube, [https://www.youtube.com/watch?v=z4cn93H6sM0](https://www.youtube.com/watch?v=z4cn93H6sM0)\n17. Apollo Guidance Computer switching power supply works after 50 years | Hacker News, [https://news.ycombinator.com/item?id=20789187](https://news.ycombinator.com/item?id=20789187)\n18. A lunar landing with 1202 and 1201 alarms - Arlington Enterprise, [https://arlingtonmnnews.com/articles/bits-and-bytes/a-lunar-landing-with-1202-and-1201-alarms/](https://arlingtonmnnews.com/articles/bits-and-bytes/a-lunar-landing-with-1202-and-1201-alarms/)\n19. Failure Is Not an Option MISSION CONTROL FROM MERCURY TO APOLLO 13 AND BEYOND GENE KRANZ, [https://ia601502.us.archive.org/25/items/PioneersOfSpaceExploration/Failure%20Is%20Not%20an%20Option%20-%20Gene%20Kranz.pdf](https://ia601502.us.archive.org/25/items/PioneersOfSpaceExploration/Failure%20Is%20Not%20an%20Option%20-%20Gene%20Kranz.pdf)\n20. Human Lunar Landing Experience On Project Apollo | NASA, [https://www.nasa.gov/wp-content/uploads/2023/06/eppler-slides-apollo-lunar-landing-experience-report-20070-r4.pdf](https://www.nasa.gov/wp-content/uploads/2023/06/eppler-slides-apollo-lunar-landing-experience-report-20070-r4.pdf)\n21. A Review of Lunar Communications and Antennas: Assessing Performance in the Context of Propagation and Radiation - ResearchGate, [https://www.researchgate.net/publication/376617255_A_Review_of_Lunar_Communications_and_Antennas_Assessing_Performance_in_the_Context_of_Propagation_and_Radiation](https://www.researchgate.net/publication/376617255_A_Review_of_Lunar_Communications_and_Antennas_Assessing_Performance_in_the_Context_of_Propagation_and_Radiation)\n22. Apollo 11 Flight Journal - Day 5, part 1: Preparations for Landing, [https://apollojournals.org/afj/ap11fj/16day5-landing-prep.html](https://apollojournals.org/afj/ap11fj/16day5-landing-prep.html)\n23. Apollo Expeditions to the Moon: The NASA History 9780486135571, 0486135578 - DOKUMEN.PUB, [https://dokumen.pub/apollo-expeditions-to-the-moon-the-nasa-history-9780486135571-0486135578.html](https://dokumen.pub/apollo-expeditions-to-the-moon-the-nasa-history-9780486135571-0486135578.html)\n24. Trying to Rest - NASA, [https://www.nasa.gov/wp-content/uploads/static/history//alsj/a11/a11.posteva.html](https://www.nasa.gov/wp-content/uploads/static/history//alsj/a11/a11.posteva.html)\n" }, "sources": [ { "url": "https://www.smithsonianmag.com/air-space-magazine/troubleshooting-101-1201-actually-and-1202-too-111339271/", "title": "Troubleshooting 101 (1201 actually, and 1202 too) - Smithsonian Magazine", "description": "Comprehensive overview covering both computer overload and low fuel issues.", "cited": true }, { "url": "https://www.discovermagazine.com/apollo-11s-1202-alarm-explained-185", "title": "Apollo 11's \"1202 Alarm\" Explained - Discover Magazine", "description": "Provides detailed technical breakdown of the 1202 alarms and execution.", "cited": true }, { "url": "https://www.cbsnews.com/news/apollo-11-moon-landing-anniversary-nail-biting-descent-to-the-surface-of-the-moon/", "title": "The inside story of Apollo 11's nail-biting descent to the surface of the moon - CBS News", "description": "Great operational account of Mission Control during the alarms.", "cited": true }, { "url": "https://www.youtube.com/watch?v=z4cn93H6sM0", "title": "The Real Story Behind the Apollo 11 Computer Error | WSJ - YouTube", "description": "Clear narrative explaining hardware switches and computer overloads.", "cited": true }, { "url": "https://ia601502.us.archive.org/25/items/PioneersOfSpaceExploration/Failure%20Is%20Not%20an%20Option%20-%20Gene%20Kranz.pdf", "title": "Failure Is Not an Option MISSION CONTROL FROM MERCURY TO APOLLO 13 AND BEYOND GENE KRANZ", "description": "Primary account from Gene Kranz on the near-abort decision.", "cited": true }, { "url": "https://www.space.com/apollo-11-guidance-officer-remembers-moon-landing-drama.html", "title": "Apollo 11's Momentous Landing Came Down to One Tough Call - Space", "description": "Focuses on the critical Mission Control decision and cheat sheet.", "cited": true }, { "url": "https://arlingtonmnnews.com/articles/bits-and-bytes/a-lunar-landing-with-1202-and-1201-alarms/", "title": "A lunar landing with 1202 and 1201 alarms - Arlington Enterprise", "description": "Summarizes the role of Bales and Garman during landing.", "cited": true }, { "url": "https://www.doneyles.com/LM/Tales.html", "title": "Apollo 11 and Other Screw-Ups - Don Eyles", "description": "Firsthand technical insight into the core set memory overflow.", "cited": true }, { "url": "https://www.nasa.gov/wp-content/uploads/static/history//alsj/a11/a11.1201-pa.html", "title": "Apollo 11 Lunar Surface Journal: Program Alarms - NASA", "description": "Primary history on MIT's software design for the lander.", "cited": true }, { "url": "https://www.nasa.gov/wp-content/uploads/static/history/alsj/a11/a11.1201-fm.html?utm_source=chatgpt.com", "title": "Apollo 11 Lunar Surface Journal: Program Alarms - NASA", "description": "Detailed history of solving the radar switch issue.", "cited": true }, { "url": "https://medium.com/softwares-giant-leap/were-go-on-that-alarm-inside-the-apollo-operating-system-8d753e7a1e17", "title": "We're Go On That Alarm: Inside the Apollo Operating System | by Joe Kutner | Software's Giant Leap | Medium", "description": "Explains the computer architecture and priority task scheduling.", "cited": true }, { "url": "https://www.reddit.com/r/apollo/comments/1ry3c9c/reconstructing_apollo_11s_powered_descent_a/", "title": "Reconstructing Apollo 11's Powered Descent: A technical deep-dive based on 37 primary sources. Feedback welcome! - Reddit", "description": "Technical discussion about rendezvous radar and computer interrupts.", "cited": true }, { "url": "https://news.ycombinator.com/item?id=20789187", "title": "Apollo Guidance Computer switching power supply works after 50 years | Hacker News", "description": "Technical explanation of cycle-stealing and radar hardware.", "cited": true }, { "url": "https://davidnunez.com/error-1202/", "title": "Error 1202 - David Nuñez", "description": "Brief summary of the 1202 error and Jack Garman.", "cited": true }, { "url": "https://en.wikipedia.org/wiki/Apollo_11", "title": "Apollo 11 - Wikipedia", "description": "Broad general overview of the Apollo 11 mission.", "cited": true }, { "url": "https://www.facebook.com/gigglegrid2/videos/-the-code-that-helped-land-humans-on-the-moon-in-1969-during-apollo-11s-descent-/1794532518247381/", "title": "*The code that helped land humans on the Moon.* In 1969, during Apollo 11's descent, the onboard computer experienced unexpected 1201/1202 alarms. Yet its software continued priori | Giggle Grid - Facebook", "description": "Social media video summary of Margaret Hamilton's software.", "cited": true }, { "url": "https://www.nasa.gov/wp-content/uploads/2023/06/eppler-slides-apollo-lunar-landing-experience-report-20070-r4.pdf", "title": "Human Lunar Landing Experience On Project Apollo | NASA", "description": "Mentions low fuel margins and weight saving trade-offs.", "cited": true }, { "url": "https://apollojournals.org/alsj//a12/a12.landing.html", "title": "A Visit to the Snowman - Apollo Journals", "description": "Mentions fuel slosh issue affecting fuel quantity gauges.", "cited": true }, { "url": "https://apollojournals.org/afj/ap11fj/16day5-landing-prep.html", "title": "Apollo 11 Flight Journal - Day 5, part 1: Preparations for Landing", "description": "Transcript covering orbital pre-landing communications.", "cited": true }, { "url": "https://dokumen.pub/apollo-expeditions-to-the-moon-the-nasa-history-9780486135571-0486135578.html", "title": "Apollo Expeditions to the Moon: The NASA History 9780486135571, 0486135578 - DOKUMEN.PUB", "description": "Historical excerpts regarding crew preparations before landing.", "cited": true }, { "url": "https://www.nasa.gov/wp-content/uploads/static/history//alsj/a11/a11.posteva.html", "title": "Trying to Rest - NASA", "description": "Post-landing transcripts focused on communications setups.", "cited": true }, { "url": "https://ntrs.nasa.gov/api/citations/19720021182/downloads/19720021182.pdf", "title": "19720021182.pdf - NASA Technical Reports Server (NTRS)", "description": "Irrelevant NASA technical document discussing Apollo 15 terrain.", "cited": true }, { "url": "https://www.nasa.gov/wp-content/uploads/2023/04/sp-4029.pdf", "title": "Apollo by the Numbers - NASA", "description": "Irrelevant statistical data on early orbit maneuvers.", "cited": true }, { "url": "https://www.researchgate.net/publication/376617255_A_Review_of_Lunar_Communications_and_Antennas_Assessing_Performance_in_the_Context_of_Propagation_and_Radiation", "title": "A Review of Lunar Communications and Antennas: Assessing Performance in the Context of Propagation and Radiation - ResearchGate", "description": "Irrelevant general study on lunar antenna radio propagation.", "cited": true }, { "url": "https://honeysucklecreek.net/msfn_missions/Apollo_11_mission/hl_apollo11.html", "title": "Apollo 11 - Hamish Lindsay - Honeysuckle Creek", "description": null, "cited": false }, { "url": "https://archive.org/download/Apollo11Audio/AS11_PAO.pdf", "title": "AS11_PAO.pdf - Apollo", "description": null, "cited": false }, { "url": "https://www.americasuncommonsense.com/1-apollo-17-diary-of-the-12th-man/c-chapters-10-18/chapter-12-pages-of-history/a-section-1/", "title": "a. Section 1 - America's Uncommon Sense", "description": null, "cited": false }, { "url": "https://crotrak.com/Documents/Cronicle/Vols1-7.pdf", "title": "W elcome to the first issue of The Trackers - CroTrak", "description": null, "cited": false }, { "url": "https://www.ibiblio.org/apollo/Documents/R-700.pdf", "title": "Apollo Guidance, Navigation and Control - Ibiblio", "description": null, "cited": false }, { "url": "https://www.ibiblio.org/apollo/changes.html", "title": "Virtual AGC Change-Log Page - Ibiblio", "description": null, "cited": false } ] } } ``` </div> ```bash curl -sS --max-time 310 -X POST "$API/research/import" \ -H "Authorization: Bearer $USEAPI_TOKEN" -H "Content-Type: application/json" \ -d "$(jq -n --arg j "$DEEP" '{jobid: $j, urls: [], report: true}')" ``` The import, in full ([step-12-deep-research-import.json](/assets/articles/gemini-notebook-bash/step-12-deep-research-import.json)): <div markdown="1" style="max-height:420px;overflow:auto"> ```json { "notebook": "user:12345-user@example.com-notebook:62600bab-4082-4ee6-8fc3-955cee0c69cf", "sources": [ { "source": "user:12345-user@example.com-source:62600bab-4082-4ee6-8fc3-955cee0c69cf:aedb3a12-040f-4a5f-a8f3-119d3f9c79d4", "title": "Anatomy of a Lunar Descent: Systems Architecture, Hardware Anomaly, and Human Decision-Making in the Apollo 11 Landing Near-Abort", "kind": "markdown", "status": "ready", "words": 3146, "created": "2026-09-29T05:04:51.000Z" } ] } ``` </div> The report alone as Markdown: [step-12-deep-research-report.md](/assets/articles/gemini-notebook-bash/step-12-deep-research-report.md). </details> #### 13. Share the notebook [POST /sharing](/docs/api-gemini-notebook-v1/post-gemini-notebook-sharing) with a public link lets anyone with it view the notebook, and `allowCopies: false` stops them duplicating it. `people: [{email, role}]` invites someone as `viewer` or `editor` (Google emails them), `role: "remove"` takes the access away, and `link: "restricted"` makes the notebook private again. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-gemini-notebook-v1/post-gemini-notebook-sharing">POST /sharing</a></summary> ```bash curl -sS -X POST "$API/sharing" \ -H "Authorization: Bearer $USEAPI_TOKEN" -H "Content-Type: application/json" \ -d "$(jq -n --arg nb "$NOTEBOOK" '{notebook: $nb, link: "public", allowCopies: false}')" ``` It returned, in full ([step-13-sharing.json](/assets/articles/gemini-notebook-bash/step-13-sharing.json)): <div markdown="1" style="max-height:420px;overflow:auto"> ```json { "notebook": "user:12345-user@example.com-notebook:62600bab-4082-4ee6-8fc3-955cee0c69cf", "people": [ { "email": "user@example.com", "role": "owner", "name": "User" } ], "link": "public", "allowCopies": false } ``` </div> </details> #### 14. What the first script used [GET /accounts/`email`](/docs/api-gemini-notebook-v1/get-gemini-notebook-accounts-email) reads the account's usage. Steps 1 to 13 took the 5-hour window from 9.6% to 19.5% and its week from 7.0% to 7.5%, in 9 minutes 20 seconds end to end. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-gemini-notebook-v1/get-gemini-notebook-accounts-email">GET /accounts/<code>email</code></a></summary> ```bash curl -sS "$API/accounts/$(enc "$EMAIL")" -H "Authorization: Bearer $USEAPI_TOKEN" ``` The part of the answer that holds usage ([step-14-account-usage.json](/assets/articles/gemini-notebook-bash/step-14-account-usage.json)): <div markdown="1" style="max-height:420px;overflow:auto"> ```json { "email": "user@example.com", "googleTier": "TIER_PRO", "tier": "pro", "quota": { "windows": [ { "window": "weekly", "resetsAt": "2026-10-04T23:25:40.000Z", "usedPercent": 7.49, "remainingPercent": 92.51 }, { "window": "5h", "resetsAt": "2026-09-29T05:25:40.000Z", "usedPercent": 19.46, "remainingPercent": 80.54 } ], "blocked": [], "actions": [ { "action": "audio", "allowed": true, "costTier": 3, "estimatedCostPercent": 11.03 }, { "action": "video", "allowed": true, "costTier": 3, "estimatedCostPercent": 10.92 }, { "action": "cinematic", "allowed": true, "costTier": 4, "estimatedCostPercent": 77.02 }, { "action": "video_short", "allowed": true, "costTier": 3, "estimatedCostPercent": 8.73 }, { "action": "infographic", "allowed": true, "costTier": 2, "estimatedCostPercent": 2.68 }, { "action": "slides", "allowed": true, "costTier": 3, "estimatedCostPercent": 13.63 }, { "action": "report", "allowed": true, "costTier": 2, "estimatedCostPercent": 1.08 }, { "action": "table", "allowed": true, "costTier": 2, "estimatedCostPercent": 1.48 }, { "action": "flashcards", "allowed": true, "costTier": 1, "estimatedCostPercent": 0.47 }, { "action": "quiz", "allowed": true, "costTier": 1, "estimatedCostPercent": 0.57 }, { "action": "mindmap", "allowed": true, "costTier": 1, "estimatedCostPercent": 0.38 }, { "action": "canvas", "allowed": true, "costTier": 1, "estimatedCostPercent": 0.01 }, { "action": "slides_edit", "allowed": true, "costTier": 2, "estimatedCostPercent": 1.07 }, { "action": "flashcards_edit", "allowed": true, "costTier": 1, "estimatedCostPercent": 0.01 }, { "action": "deep_research", "allowed": true, "costTier": 2, "estimatedCostPercent": 3.92 }, { "action": "nos", "allowed": true, "costTier": 2, "estimatedCostPercent": 1.25 }, { "action": "fast_research", "allowed": true, "costTier": 1, "estimatedCostPercent": 0.32 }, { "action": "qna", "allowed": true, "costTier": 1, "estimatedCostPercent": 0.41 }, { "action": "nos_image", "allowed": true, "costTier": 1, "estimatedCostPercent": 0.45 }, { "action": "guided_view", "allowed": true, "costTier": 1, "estimatedCostPercent": 0.57 }, { "action": "document_guide", "allowed": true, "costTier": 1, "estimatedCostPercent": 0.1 }, { "action": "suggestion_chips", "allowed": true, "costTier": 1, "estimatedCostPercent": 0.14 }, { "action": "kind23", "allowed": true, "costTier": 1, "estimatedCostPercent": 0.05 }, { "action": "kind24", "allowed": true, "costTier": 1, "estimatedCostPercent": 0.1 } ] } } ``` </div> </details> #### 15. Ask a follow-up question The second script starts here, on the same notebook. The `conversation` from step 6 makes the answer build on the earlier turns: *"When the Lunar Module Eagle touched down, it had 216 pounds (98 kg) of usable fuel remaining"*, with 5 citations. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-gemini-notebook-v1/post-gemini-notebook-chat">POST /chat</a> (follow-up)</summary> ```bash curl -sS -X POST "$API/chat" \ -H "Authorization: Bearer $USEAPI_TOKEN" -H "Content-Type: application/json" \ -d "$(jq -n --arg nb "$NOTEBOOK" --arg c "$(jq -r .conversation chat.json)" '{notebook: $nb, conversation: $c, question: "How much fuel was left when they landed?"}')" ``` It returned, in full ([step-15-follow-up-chat.json](/assets/articles/gemini-notebook-bash/step-15-follow-up-chat.json)): <div markdown="1" style="max-height:420px;overflow:auto"> ```json { "notebook": "user:12345-user@example.com-notebook:62600bab-4082-4ee6-8fc3-955cee0c69cf", "answer": "When the Lunar Module *Eagle* touched down, it had **216 pounds (98 kg) of usable fuel remaining** [1, 2]. \n\nIn terms of remaining flight time, the figures depend on whether you look at real-time calculations or post-flight analysis:\n\n* **Real-time estimates:** Telemetry available to Mission Control and the crew during the landing indicated *Eagle* had approximately **20 to 25 seconds of powered flight left** before reaching \"Bingo fuel\"—the mandatory threshold where an emergency abort would have been required [1-3].\n* **Post-mission analysis:** Detailed post-flight evaluations determined that the actual remaining margin before total fuel depletion was closer to **50 seconds** [1, 2].\n\nThe early low-fuel warning during descent was triggered because the hypergolic propellant sloshed inside the tanks while Neil Armstrong manually maneuvered the lander past West Crater, temporarily uncovering a fuel sensor earlier than expected [1, 2, 4, 5].\n\n⛽ Would you like to delve deeper into the \"Bingo fuel\" mission rules and how Capcom Charlie Duke and Flight Director Gene Kranz handled the final fuel countdown in Mission Control?", "conversation": "51147e56-85e3-4862-b0a4-12fd1410b1a5", "citations": [ { "number": 1, "source": "user:12345-user@example.com-source:62600bab-4082-4ee6-8fc3-955cee0c69cf:6e04a6ea-cd2d-44cb-8be5-66f48be21a0d", "text": "ACA was the Attitude Control Assembly—the LM's control stick. Output went to the LGC to command the reaction control system (RCS) jets to fire. \"Out of Detent\" meant the stick had moved away from its centered position; it was spring-centered like the turn indicator in a car. Address 413 of the Abort Guidance System (AGS) contained the variable that indicated the LM had landed.[10] Eagle landed at 20:17:40 UTC on Sunday July 20 with 216 pounds (98 kg) of usable fuel remaining. Information available to the crew and mission controllers during the landing showed the LM had enough fuel for another 25 seconds of powered flight before an abort without touchdown would have become unsafe,[10][129] but post-mission analysis showed that the real figure was probably closer to 50 seconds.[130] Apollo 11 landed with less fuel than most subsequent missions, and the astronauts encountered a premature low fuel warning. This was later found to be the result of the propellant sloshing more than expected, uncovering a fuel sensor. On subsequent missions, extra anti-slosh baffles were added to the tanks to prevent this.[10]", "relevance": 1 }, { "number": 2, "source": "user:12345-user@example.com-source:62600bab-4082-4ee6-8fc3-955cee0c69cf:3f190e9f-3311-4176-8760-ee2636bde7c9", "text": "The landing site relative to West craterACA was the Attitude Control Assembly—the LM's control stick. Output went to the LGC to command the reaction control system (RCS) jets to fire. \"Out of Detent\" meant the stick had moved away from its centered position; it was spring-centered like the turn indicator in a car. Address 413 of the Abort Guidance System (AGS) contained the variable that indicated the LM had landed. [10]Eagle landed at 20:17:40 UTC on Sunday July 20 with 216 pounds (98 kg) of usable fuel remaining. Information available to the crew and mission controllers during the landing showed the LM had enough fuel for another 25 seconds of powered flight before an abort without touchdown would have become unsafe, [10] [129] but post-mission analysis showed that the real figure was probably closer to 50 seconds. [130] Apollo 11 landed with less fuel than most subsequent missions, and the astronauts encountered a premature low fuel warning. This was later found to be the result of the propellant sloshing more than expected, uncovering a fuel sensor. On subsequent missions, extra anti-slosh baffles were added to the tanks to prevent this. [10]", "relevance": 0.9962894248608535 }, { "number": 3, "source": "user:12345-user@example.com-source:62600bab-4082-4ee6-8fc3-955cee0c69cf:aedb3a12-040f-4a5f-a8f3-119d3f9c79d4", "text": "The early latching of the fuel quantity sensor initiated a mandatory countdown clock in Mission Control [cite: 6, 20]. Flight rules dictated that if the spacecraft reached \"Bingo fuel\"—the threshold where remaining propellant was sufficient only to perform an emergency ascent ignition and rendezvous—the crew was required to abort immediately [cite: 6, 20].Capcom Charlie Duke issued the \"60 seconds\" warning call, followed by the \"30 seconds\" warning call as the remaining fuel margin dwindled [cite: 6, 20]. Maintaining a low vertical descent rate while maneuvering over dust clouds kicked up by the descent engine exhaust, Armstrong landed Eagle at MET 102:45:40 [cite: 20]. Post-landing analysis confirmed that Eagle touched down with approximately 20 to 25 seconds of fuel remaining before reaching the mandatory Bingo abort limit [cite: 20].", "relevance": 0.9925788497217068 }, { "number": 4, "source": "user:12345-user@example.com-source:62600bab-4082-4ee6-8fc3-955cee0c69cf:aedb3a12-040f-4a5f-a8f3-119d3f9c79d4", "text": "Extending the flight path downrange to find a smooth landing site created a severe fuel management challenge [cite: 3, 20]. The additional flight time rapidly depleted the hypergolic propellants inside the Descent Propulsion System (DPS) tanks [cite: 20].This fuel margin issue was exacerbated by fluid dynamics inside the propellant tanks [cite: 6, 20]. As Armstrong executed manual translation maneuvers, the remaining liquid nitrogen tetroxide and aerozine-50 propellants sloshed back and forth within the spherical tanks [cite: 6, 20]. This sloshing motion uncovered the internal low-level sensors prematurely, latching the \"Low Quantity\" warning light earlier than actual fuel levels warranted [cite: 6].", "relevance": 0.9981447124304267 }, { "number": 5, "source": "user:12345-user@example.com-source:62600bab-4082-4ee6-8fc3-955cee0c69cf:aedb3a12-040f-4a5f-a8f3-119d3f9c79d4", "text": "Comprehensive Matrix of Descent AnomaliesThe following matrix synthesizes the technical causes, operational impacts, and engineering mitigations associated with the failure modes encountered during the Apollo 11 descent.Anomaly CategoryPrimary Technical CauseSystem ManifestationOperational ImpactEngineering & Procedural MitigationExecutive Overload AlarmsPhase mismatch (800\\text{ Hz} vs 400\\text{ Hz}) between radar and CDU interface causing CPU cycle stealing [cite: 7, 17].1201 and 1202 Program Alarms; memory structure exhaustion [cite: 8].Non-essential tasks dropped; DSKY updates temporarily suspended [cite: 8, 9, 14].Asynchronous defensive priority scheduling (BAILOUT) [cite: 8, 9]; Garman/Bales \"GO\" protocol [cite: 3, 14].Downrange Position OffsetResidual pressure in docking tunnel during separation + lunar mascon gravitational pull [cite: 1, 5].Trajectory shifted 3,000\\text{ ft} downrange from target site [cite: 5].Automatic guidance targeted West Crater boulder field [cite: 3, 20].Armstrong engaged P66 manual rate-of-descent mode to fly clear of rocks [cite: 3, 15, 20].Telemetry DisruptionVehicle pitch/yaw attitude obscured line-of-sight for S-Band High Gain Antenna [cite: 15, 21].Intermittent Loss of Signal (LOS) and telemetry noise in MCC [cite: 21, 22].Ground controllers lost real-time engineering telemetry streams [cite: 3, 21].Switched to omni-directional antennas; CapCom requested vehicle re-orientation [cite: 23, 24].Propellant Depletion RiskPropellant sloshing during P66 manual translation uncovered sensors early [cite: 6, 20].Early latching of Low Quantity sensor light [cite: 6].Accelerated \"Bingo fuel\" countdown in Mission Control [cite: 6, 20].Refined post-flight slosh baffles; landing completed before zero-fuel threshold [cite: 6, 20].", "relevance": 0.9703153988868275 } ], "ms": 24995 } ``` </div> </details> #### 16. Turn the note into a source [POST /notes/source](/docs/api-gemini-notebook-v1/post-gemini-notebook-notes-source) turns the note from step 7 into a Markdown source that later answers can cite. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-gemini-notebook-v1/post-gemini-notebook-notes-source">POST /notes/source</a></summary> ```bash curl -sS -X POST "$API/notes/source" \ -H "Authorization: Bearer $USEAPI_TOKEN" -H "Content-Type: application/json" \ -d "$(jq -n --arg n "$(jq -r .note note.json)" '{note: $n}')" ``` It returned, in full ([step-16-note-to-source.json](/assets/articles/gemini-notebook-bash/step-16-note-to-source.json)): <div markdown="1" style="max-height:420px;overflow:auto"> ```json { "notebook": "user:12345-user@example.com-notebook:62600bab-4082-4ee6-8fc3-955cee0c69cf", "source": "user:12345-user@example.com-source:62600bab-4082-4ee6-8fc3-955cee0c69cf:f9aa14ef-446a-445a-8d94-b45b1b9a5045", "title": "What went wrong during the descent", "kind": "markdown", "status": "ready", "words": 656, "created": "2026-09-29T05:49:29.000Z" } ``` </div> </details> #### 17. Flashcards, a mind map, a report and a data table Four sync calls, one after another: the flashcards in 18 seconds, the data table in 32, the report in 79 and the mind map in 92. The mind map outlived the 90-second sync wait, so it answered `202` and was polled to the end. Flashcards come back as `result.content.flashcards` (20 cards of front `f` and back `b`), the mind map as a JSON tree in `result.content`, the briefing report as 27,282 characters of Markdown in `result.text`, and the data table as `result.table`, the header row first. The table's first rows, with the cells shortened and the Source column left out here: | Time | Alarm or event | Cause | What the crew or Mission Control did | |---|---|---|---| | Five minutes into the descent burn / MET 102:38:00–102:38:22 / PDI + 316 seconds | 1202 program alarm | Computer overload (Executive overflow: no core sets available). High-frequency counter increment requests … | Buzz Aldrin checked the alarm code using Verb 90 Noun 50 (and Verb 05 Noun 09 at PDI + 322 seconds). Computer … | | MET 102:36:55 | Slow spacecraft rotation rate during pitch-over/spin maneuver | Autopilot rate switch was set at 5 deg/sec. | Neil Armstrong switched the autopilot rate switch from 5 deg/sec to 25 deg/sec. | | As descent began / Not in source | Overshooting the Planned Landing Target / Downrange Position Offset (Trajectory shifted 3,000 ft downrange … | Residual pressure in the docking tunnel during separation, lunar gravitational anomalies (mascons), and … | The crew monitored their position closely, maintained composure, and prepared to adapt to landing further … | <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts">POST /artifacts</a> (flashcards, mind map, report, table)</summary> ```bash for body in \ '{"type": "flashcards", "quantity": "fewer", "difficulty": "easy"}' \ '{"type": "mindmap"}' \ '{"type": "report", "format": "briefing"}' \ '{"type": "table", "instructions": "One row per program alarm or anomaly during the descent: time, alarm or event, cause, what the crew or Mission Control did."}'; do curl -sS -X POST "$API/artifacts" \ -H "Authorization: Bearer $USEAPI_TOKEN" -H "Content-Type: application/json" \ -d "$(jq -n --arg nb "$NOTEBOOK" --argjson b "$body" '$b + {notebook: $nb}')" done ``` A response with status `202` is still running: poll its `jobid` as in step 11. The flashcards job, in full ([step-17-flashcards-job.json](/assets/articles/gemini-notebook-bash/step-17-flashcards-job.json)): <div markdown="1" style="max-height:420px;overflow:auto"> ```json { "jobid": "job:fb2dbd90-17ce-45d0-8971-75229f82bec1-user:12345-user@example.com-bot:gemini_notebook", "email": "user@example.com", "type": "flashcards", "status": "completed", "notebook": "user:12345-user@example.com-notebook:62600bab-4082-4ee6-8fc3-955cee0c69cf", "artifact": "user:12345-user@example.com-artifact:62600bab-4082-4ee6-8fc3-955cee0c69cf:c70e9f63-6858-4fed-a23a-38d1d7704a4f", "created_at": "2026-09-29T05:49:38.392Z", "request": { "notebook": "user:12345-user@example.com-notebook:62600bab-4082-4ee6-8fc3-955cee0c69cf", "type": "flashcards", "quantity": "fewer", "difficulty": "easy" }, "completed_at": "2026-09-29T05:49:56.336Z", "result": { "title": "Apollo Flashcards", "content": { "flashcards": [ { "f": "Who served as the Commander of the Apollo 11 mission?", "b": "Neil Armstrong" }, { "f": "Who was the Command Module Pilot for the Apollo 11 mission?", "b": "Michael Collins" }, { "f": "Who served as the Lunar Module Pilot for Apollo 11?", "b": "Edwin \"Buzz\" Aldrin" }, { "f": "What was the official name of the Apollo 11 Command Module?", "b": "Columbia" }, { "f": "What was the official name of the Apollo 11 Lunar Module?", "b": "Eagle" }, { "f": "Which rocket launch vehicle was used to send Apollo 11 into space?", "b": "Saturn V" }, { "f": "In what year did the Apollo 11 mission land humans on the Moon?", "b": "1969" }, { "f": "What primary lunar site was chosen for the Apollo 11 landing?", "b": "Sea of Tranquility (Mare Tranquillitatis)" }, { "f": "Which U.S. President in 1961 set the goal of landing a man on the Moon before the end of the decade?", "b": "John F. Kennedy" }, { "f": "What famous statement did Neil Armstrong make upon stepping onto the lunar surface?", "b": "\"That's one small step for [a] man, one giant leap for mankind.\"" }, { "f": "Which part of the Apollo spacecraft was the only section designed to return safely to Earth?", "b": "The Command Module" }, { "f": "What animal feature was chosen for the Apollo 11 mission insignia to symbolize a peaceful mission?", "b": "A bald eagle carrying an olive branch" }, { "f": "Which U.S. President spoke directly to Armstrong and Aldrin via telephone-radio transmission during their moonwalk?", "b": "Richard Nixon" }, { "f": "What Everyday item did Buzz Aldrin use to engage the broken circuit breaker for ascent engine ignition?", "b": "A felt-tip pen" }, { "f": "Which naval ship recovered the Apollo 11 crew after splashdown in the Pacific Ocean?", "b": "USS Hornet" }, { "f": "The call sign used by Neil Armstrong to announce the touchdown on the lunar surface was _____ Base.", "b": "Tranquility" }, { "f": "Uncrewed Soviet probe _____ crashed into the lunar surface while Armstrong and Aldrin were still on the Moon.", "b": "Luna 15" }, { "f": "How many total astronauts made up the prime crew of Apollo 11?", "b": "Three" }, { "f": "Approximately how long did Armstrong and Aldrin spend walking on the lunar surface during their EVA?", "b": "Two and a half hours" }, { "f": "What scientific package was deployed by the Apollo 11 crew on the lunar surface?", "b": "Early Apollo Scientific Experiments Package (EASEP)" } ], "topics": { "covered": [ "Apollo 11 Crew Members", "Spacecraft Components and Call Signs", "Lunar Landing and Surface Operations", "Historical Context and Objectives of Apollo 11" ], "followUp": [ "Saturn V Rocket Specifications", "Apollo Lunar Module Egress and Hatch Design", "Lunar Material Analysis and Mineral Discoveries" ] } } } } ``` </div> The mind map job, in full ([step-17-mindmap-job.json](/assets/articles/gemini-notebook-bash/step-17-mindmap-job.json)): <div markdown="1" style="max-height:420px;overflow:auto"> ```json { "jobid": "job:51865992-9f68-4905-8773-b492fd0e6a5a-user:12345-user@example.com-bot:gemini_notebook", "email": "user@example.com", "type": "mindmap", "status": "completed", "notebook": "user:12345-user@example.com-notebook:62600bab-4082-4ee6-8fc3-955cee0c69cf", "artifact": "user:12345-user@example.com-artifact:62600bab-4082-4ee6-8fc3-955cee0c69cf:de7f06aa-13d2-462d-a7fb-90dd675d185e", "created_at": "2026-09-29T05:50:02.363Z", "request": { "notebook": "user:12345-user@example.com-notebook:62600bab-4082-4ee6-8fc3-955cee0c69cf", "type": "mindmap" }, "completed_at": "2026-09-29T05:51:34.346Z", "result": { "title": "Apollo Mindmap", "content": { "name": "Apollo 11", "children": [ { "name": "Background", "children": [ { "name": "Cold War Space Race" }, { "name": "Sputnik Crisis" }, { "name": "JFK National Goal" }, { "name": "Project Mercury and Gemini" }, { "name": "Apollo 1 Fire Setback" } ] }, { "name": "Personnel", "children": [ { "name": "Prime Crew", "children": [ { "name": "Neil Armstrong (Commander)" }, { "name": "Michael Collins (CMP)" }, { "name": "Buzz Aldrin (LMP)" } ] }, { "name": "Support Personnel", "children": [ { "name": "Backup Crew" }, { "name": "Support Crew" }, { "name": "Capsule Communicators" }, { "name": "Flight Directors" }, { "name": "Specialized Technicians" } ] } ] }, { "name": "Spacecraft Components", "children": [ { "name": "Saturn V Rocket (SA-506)" }, { "name": "Command Module (Columbia)" }, { "name": "Service Module (SM)" }, { "name": "Lunar Module (Eagle)", "children": [ { "name": "Descent Stage" }, { "name": "Ascent Stage" } ] } ] }, { "name": "Mission Preparations", "children": [ { "name": "Mission Insignia (Bald Eagle)" }, { "name": "Call Sign Naming" }, { "name": "Site Selection (Sea of Tranquility)" }, { "name": "First-Step Decision" } ] }, { "name": "Mission Timeline", "children": [ { "name": "Launch (July 16, 1969)" }, { "name": "Trans-Lunar Injection" }, { "name": "Lunar Orbit Insertion" }, { "name": "Lunar Descent", "children": [ { "name": "1201 and 1202 Alarms" }, { "name": "Manual Piloting" }, { "name": "Low Fuel Warning" } ] }, { "name": "Lunar Landing", "children": [ { "name": "July 20, 19:17 UTC" }, { "name": "Tranquility Base" } ] }, { "name": "Return and Splashdown" } ] }, { "name": "Surface Operations", "children": [ { "name": "First Step (Armstrong)" }, { "name": "Magnificent Desolation (Aldrin)" }, { "name": "Nixon Telephone Call" }, { "name": "US Flag Deployment" }, { "name": "Scientific Experiments (EASEP)" }, { "name": "Sample Collection (21.55 kg)" }, { "name": "Memorial Items and Plaque" } ] }, { "name": "Impact and Legacy", "children": [ { "name": "600 Million TV Viewers" }, { "name": "New Lunar Minerals" }, { "name": "Presidential Medal of Freedom" }, { "name": "National Air and Space Museum" } ] } ] } } } ``` </div> The report job, in full ([step-17-report-job.json](/assets/articles/gemini-notebook-bash/step-17-report-job.json)): <div markdown="1" style="max-height:420px;overflow:auto"> ```json { "jobid": "job:dd184afe-1acb-4d60-a100-702122ccead7-user:12345-user@example.com-bot:gemini_notebook", "email": "user@example.com", "type": "report", "status": "completed", "notebook": "user:12345-user@example.com-notebook:62600bab-4082-4ee6-8fc3-955cee0c69cf", "artifact": "user:12345-user@example.com-artifact:62600bab-4082-4ee6-8fc3-955cee0c69cf:c4453230-46a7-40e9-bb82-a42f8131453e", "created_at": "2026-09-29T05:51:43.216Z", "request": { "notebook": "user:12345-user@example.com-notebook:62600bab-4082-4ee6-8fc3-955cee0c69cf", "type": "report", "format": "briefing" }, "completed_at": "2026-09-29T05:53:02.653Z", "result": { "title": "Briefing Document: Mission Overview and Technical Synthesis of Apollo 11", "text": "# Briefing Document: Mission Overview and Technical Synthesis of Apollo 11\n\n## Executive Summary\n\nApollo 11 was the first crewed lunar landing spaceflight in human history. Operated by the National Aeronautics and Space Administration (NASA) and launched atop a Saturn V rocket on July 16, 1969, the mission successfully placed astronauts Neil A. Armstrong and Edwin \"Buzz\" E. Aldrin Jr. on the lunar surface on July 20, 1969, while Command Module Pilot Michael Collins maintained lunar orbit. The mission achieved the primary national goal established by President John F. Kennedy in May 1961: to land a man on the Moon and return him safely to Earth before the end of the 1960s.\n\nKey findings and critical takeaways from the mission context include:\n* **Geopolitical and Strategic Success:** Apollo 11 brought the Space Race—a critical technological competition between the United States and the Soviet Union during the Cold War—to its culmination. Parallel Soviet efforts, such as the uncrewed sample-return probe *Luna 15*, ended in failure when *Luna 15* crashed into Mare Crisium while Armstrong and Aldrin were still on the lunar surface.\n* **Technical and Operational Resilience:** The mission overcame significant in-flight anomalies, including trajectory overshoots during descent, guidance computer executive overflow alarms (1201 and 1202) triggered by a radar hardware design flaw, a rapidly depleting fuel reserve during landing, and a broken circuit breaker in the Lunar Module cabin that was engaged using a felt-tip pen.\n* **Scientific and Historical Returns:** The crew executed a 2-hour, 31-minute, 40-second Extravehicular Activity (EVA), returned 47.51 lb (21.55 kg) of lunar material containing three previously unknown minerals (*armalcolite*, *tranquillityite*, and *pyroxferroite*), deployed the Early Apollo Scientific Experiments Package (EASEP), and transmitted live television coverage viewed by an estimated 600 million people worldwide.\n* **Safety and Recovery Protocols:** The crew safely splashed down in the North Pacific Ocean on July 24, 1969, after 8 days, 3 hours, 18 minutes, and 35 seconds of flight. Emergency weather rerouting was made possible prior to recovery due to classified spy satellite monitoring of an impending storm front.\n\n---\n\n## 1. Historical, Political, and Programmatic Context\n\n### The Cold War and Space Race Infrastructure\nThe launch of *Sputnik 1* by the Soviet Union on October 4, 1957, initiated the Sputnik crisis and ignited the Space Race. The achievement demonstrated Soviet capabilities in intercontinental ballistic missile technology, directly challenging American perceptions of military and technological dominance. \n\nIn response, President Dwight D. Eisenhower established NASA and initiated Project Mercury. Subsequent early Soviet milestones—most notably cosmonaut Yuri Gagarin becoming the first human in space and orbit on April 12, 1961—forced U.S. leadership to seek a long-term goal where existing Soviet launcher advantage (higher lift capacity) would be neutralized.\n\n### Presidential Directives\nOn May 25, 1961, President John F. Kennedy addressed a joint session of Congress on \"Urgent National Needs,\" establishing the core mandate for Project Apollo:\n\n> \"I believe that this nation should commit itself to achieving the goal, before this decade [1960s] is out, of landing a man on the Moon and returning him safely to the Earth. No single space project in this period will be more impressive to mankind, or more important for the long-range exploration of space; and none will be so difficult or expensive to accomplish.\"\n\nKennedy reinforced this commitment during a speech at Rice University on September 12, 1962, stating:\n\n> \"We choose to go to the Moon in this decade and do the other things, not because they are easy, but because they are hard; because that goal will serve to organize and measure the best of our energies and skills, because that challenge is one that we are willing to accept, one we are unwilling to postpone, and one we intend to win...\"\n\nDespite political rhetoric, the program faced internal domestic criticism; MIT mathematician Norbert Wiener notably dismissed the initiative as a \"moondoggle.\" Kennedy explored potential joint U.S.-Soviet lunar expeditions during meetings with Soviet Premier Nikita Khrushchev in June 1961 and at the UN General Assembly in September 1963, but these concepts were abandoned following Kennedy's assassination.\n\n### Technical Foundations and Precursor Missions\nIn July 1962, NASA Administrator James Webb approved Lunar Orbit Rendezvous (LOR) as the core mission architecture over direct ascent and Earth orbit rendezvous. LOR allowed a single Saturn V rocket to launch a three-part spacecraft:\n1. **Command Module (CM):** Cabin housing the three-man crew; the only component designed to return intact to Earth.\n2. **Service Module (SM):** Propulsion, electrical power, oxygen, and water supply.\n3. **Lunar Module (LM):** Two-stage craft comprising a descent stage for landing and an ascent stage for returning astronauts to lunar orbit.\n\nProject Gemini established the rendezvous, docking, and EVA techniques required for Apollo. Advanced hardware integrations—specifically metal–oxide–semiconductor field-effect transistors (MOSFETs) in the Interplanetary Monitoring Platform (IMP) and silicon integrated circuit (IC) chips in the Apollo Guidance Computer (AGC)—enabled the miniaturization of onboard computing.\n\nFollowing the fatal *Apollo 1* launchpad fire on January 27, 1967, which killed astronauts Gus Grissom, Ed White, and Roger B. Chaffee, the Apollo hardware underwent systematic testing:\n* **Apollo 7 (Oct 1968):** Evaluated the CM in Earth orbit.\n* **Apollo 8 (Dec 1968):** Tested the CSM in lunar orbit.\n* **Apollo 9 (Mar 1969):** Evaluated the LM in Earth orbit.\n* **Apollo 10 (May 1969):** Conducted a full \"dress rehearsal\" in lunar orbit, bringing the LM within 15 km (9.3 mi) of the surface.\n\n### Soviet Parallel Activities\nWhile the U.S. pursued Apollo 11, Soviet efforts to land humans stalled due to failures in developing the N1 heavy-lift launcher. The USSR pivoted to uncrewed automated sample return. On July 13, 1969—three days before Apollo 11 launched—the Soviets launched *Luna 15*. The uncrewed probe entered lunar orbit ahead of Apollo 11, but suffered a malfunction during descent and crashed in Mare Crisium at 15:50 UTC on July 21, approximately two hours before Apollo 11's planned return liftoff from the lunar surface.\n\n---\n\n## 2. Mission Specifications and Operational Parameters\n\n| Parameter | Specification / Data Point |\n| :--- | :--- |\n| **Mission Type** | Crewed Lunar Landing (G Type) |\n| **Operator** | NASA |\n| **Spacecraft Identification** | CSM-107 (*Columbia*); LM-5 (*Eagle*) |\n| **COSPAR ID** | CSM: 1969-059A; LM: 1969-059C |\n| **SATCAT Catalog No.** | CSM: 4039; LM: 4041 |\n| **Launch Vehicle** | Saturn V SA-506 |\n| **Launch Site** | Launch Complex 39A, Kennedy Space Center, Florida |\n| **Launch Mass** | 109,646 lb (49,735 kg) |\n| **Landing Mass (LM)** | 10,873 lb (4,932 kg) |\n| **Total Mission Duration**| 8 days, 3 hours, 18 minutes, 35 seconds |\n| **Orbital Insertion (Selenocentric)** | July 19, 1969, 17:21:50 UTC |\n| **Lunar Orbit Parameters** | Periselene: 100.9 km (54.5 nmi); Aposelene: 122.4 km (66.1 nmi); Inclination: 1.25°; Period: 2 hours |\n| **Lunar Surface Coordinates**| Tranquility Base, Mare Tranquillitatis (0.67416°N, 23.47314°E) |\n| **Surface Stay Duration** | 21 hours, 36 minutes, 20 seconds |\n| **EVA Duration** | 2 hours, 31 minutes, 40 seconds |\n| **Sample Material Returned**| 47.51 lb (21.55 kg) |\n| **Recovery Asset / Location**| USS *Hornet*; North Pacific Ocean (13°19′N, 169°9′W) |\n\n---\n\n## 3. Personnel Structure and Personnel Assignments\n\n### Prime and Backup Flight Crews\n\n* **Commander:** Neil A. Armstrong (Second and final spaceflight)\n* **Command Module Pilot (CMP):** Michael Collins (Second and final spaceflight)\n* **Lunar Module Pilot (LMP):** Edwin \"Buzz\" Aldrin Jr. (Second and final spaceflight)\n\n#### Crew Reassignments and Dynamics\nThe initial crew structure was established in November 1967 when Armstrong, Jim Lovell, and Aldrin were assigned as the backup crew for Apollo 9. Manufacturing delays with the LM caused Apollo 8 and Apollo 9 to swap prime and backup crews, putting Armstrong's crew in line to back up Apollo 8 and prime Apollo 11 under standard rotation protocols. \n\nWhen original Apollo 8 CMP Michael Collins required spinal surgery for a bone growth between his fifth and sixth vertebrae, Lovell moved into the Apollo 8 prime crew, Fred Haise filled in as backup LMP, and Aldrin served as backup CMP. Upon recovering, Collins was integrated into Armstrong's crew as CMP for Apollo 11. \n\nFlight Crew Operations Director Deke Slayton offered Armstrong the opportunity to replace Aldrin with Lovell due to perceived friction with Aldrin, but Armstrong declined, noting that Lovell deserved his own command (which became Apollo 13). Collins and Aldrin described the prime crew as \"amiable strangers,\" forging a formal and effective working relationship without the close social personal dynamic seen on missions like Apollo 12.\n\n* **Backup Crew:** Jim Lovell (Commander), William Anders (CMP), Fred Haise (LMP). Ken Mattingly trained in parallel as backup CMP due to Anders accepting a position with the National Aeronautics and Space Council starting August 1969.\n\n### Ground Control, CAPCOMs, and Management\n\n#### Support Crew\nKen Mattingly, Ronald Evans, Bill Pogue.\n\n#### Capsule Communicators (CAPCOM)\nCommunication directly with the spacecraft was restricted to CAPCOM astronauts to ensure operational clarity. CAPCOMs included Charles Duke, Owen Garriott, Don L. Lind, Bruce McCandless II, Harrison Schmitt, William Anders, Ronald Evans, Fred Haise, Jim Lovell, and Ken Mattingly.\n\n#### Flight Directors\n* **Shift 1 (Green Team):** Clifford E. Charlesworth (Launch and EVA)\n* **Shift 1 (Gold Team - Backup):** Gerald D. Griffin\n* **Shift 2 (White Team):** Gene Kranz (Lunar Landing)\n* **Shift 3 (Black Team):** Glynn Lunney (Lunar Ascent)\n* **Shift 4 (Maroon Team):** Milton Windler (Planning)\n\n#### Key Support Personnel\n\n| Name | Specialty / Role | Core Contribution |\n| :--- | :--- | :--- |\n| **Farouk El-Baz** | Geologist | Studied lunar surface geology; identified landing sites; trained pilots. |\n| **Kurt Debus** | Rocket Scientist | Supervised construction and operation of launch pads and infrastructure. |\n| **Jamye Flowers** | Executive Secretary | Secretarial support for astronaut office. |\n| **Eleanor Foraker** | Tailor / Designer | Lead hand-assembler and designer for Apollo spacesuits. |\n| **Jack Garman** | Computer Engineer | Mission Control technician; verified 1201/1202 alarms were safe to proceed. |\n| **Millicent Goldschmidt**| Microbiologist | Designed aseptic lunar material collection protocols and astronaut training. |\n| **Eldon C. Hall** | AGC Hardware Engineer | Designed hardware architecture for the Apollo Guidance Computer. |\n| **Margaret Hamilton** | Software Engineer | Lead flight software engineer at MIT; authored fault-tolerant AGC software. |\n| **Milton E. Harr** | Geotechnical Engineer| Designed footpads for the Apollo Lunar Module landing gear. |\n| **John Houbolt** | Engineer / Planner | Primary advocate and route planner for Lunar Orbit Rendezvous (LOR). |\n| **Gene Shoemaker** | Field Geologist | Instructed prime and backup crews in field geology techniques. |\n| **Bill Tindall** | Flight Operations | Mission techniques coordinator; standardized operational trajectory rules. |\n\n---\n\n## 4. Pre-Launch Preparations, Logistics, and Decisions\n\n### Insignia and Call Sign Designations\n* **Insignia:** Designed by Michael Collins, featuring an American bald eagle landing on the Moon with Earth in the background. At the suggestion of simulator instructor Tom Wilson, an olive branch was included. Originally drawn in the eagle's beak, NASA officials (including MSC Director Bob Gilruth) deemed the talons too warlike, prompting the olive branch to be shifted to the talons. Crew names were intentionally omitted from the patch so it would represent everyone who contributed to the landing.\n* **Call Signs:** Early mission planning used internal/external call signs *Snowcone* (CM) and *Haystack* (LM). Following public affairs concerns regarding flippant designations (such as Apollo 10's *Charlie Brown* and *Snoopy*), Julian Scheer urged the adoption of formal names. The LM was designated *Eagle* (after the insignia), and the CM was named *Columbia*—referencing *Columbiad*, the space launch cannon in Jules Verne's 1865 novel *From the Earth to the Moon*, as well as a traditional historic name for the United States.\n\n### Personal Preference Kits (PPKs) and Mementos\nFive 0.5-pound (0.23 kg) Personal Preference Kits were stowed on board (three in *Columbia*, two in *Eagle*). Neil Armstrong’s LM PPK contained:\n* A piece of wood from the left propeller of the Wright brothers' 1903 *Wright Flyer*.\n* A piece of fabric from the *Wright Flyer's* wing.\n* A diamond-studded astronaut pin originally belonging to Deke Slayton, gifted by the widows of the *Apollo 1* crew.\n\n### Landing Site Selection Criteria\nThe Apollo Site Selection Board announced five potential landing sites on February 8, 1968, compiled from uncrewed *Lunar Orbiter* and *Surveyor* photographic data:\n1. **Site 1:** Sea of Tranquility (*Mare Tranquillitatis*)\n2. **Site 2:** Sea of Tranquility (*Mare Tranquillitatis*) — **Selected**\n3. **Site 3:** Central Bay (*Sinus Medii*) — Backup\n4. **Site 4:** Ocean of Storms (*Oceanus Procellarum*)\n5. **Site 5:** Ocean of Storms (*Oceanus Procellarum*) — Backup\n\nFinal selection of Site 2 was governed by seven technical constraints:\n* Relatively smooth surface with low crater density.\n* Approach path free of large hills, cliffs, or deep craters that could distort landing radar signals.\n* Minimum propellant expenditure required for spacecraft trajectory.\n* Flexibility to accommodate launch countdown delays.\n* Maintenance of a free-return trajectory capability during trans-lunar coast.\n* Sun angle between 7° and 20° behind the LM during approach (requiring launch windows limited to one specific day per month to limit operational surface temperature extremes).\n* General ground surface slope of less than 2°.\n\n### First-Step Protocol Decision\nHistorical media reports early in 1969 incorrectly presumed Buzz Aldrin would step out first, mirroring Project Gemini operations where the pilot executed EVAs while the commander remained inside the spacecraft. \n\nThe decision to have Neil Armstrong step onto the surface first was finalized and announced on April 14, 1969. Primary contributing factors included:\n* **Physical Cabin Geometry:** The LM hatch opened inward and hinged to the right, facing the Lunar Module Pilot's side. For Aldrin to egress first in a fully pressurized suit, he was forced to physically squeeze over the commander's position, damaging simulator equipment during trials.\n* **Command Hierarchy:** Flight Crew Operations Director Deke Slayton formally invoked the commander's prerogative. \n* **Public Representation:** Flight Operations Director Chris Kraft revealed in his autobiography that top management (Gilruth, Slayton, Low, and Kraft) deliberately stepped in to ensure Armstrong—a quiet civilian—was the first human on the surface, explicitly likening his demeanor to Charles Lindbergh.\n\n---\n\n## 5. Comprehensive Mission Execution Timeline\n\n### Launch, Trans-Lunar Injection, and Flight Phase\nOn July 16, 1969, at 13:32:00 UTC, Saturn V AS-506 launched Apollo 11 from Launch Complex 39A. Launch operations were managed with 43 automated programs written in the ATOLL programming language. Over 1 million spectators gathered along Florida highways, alongside 3,500 journalists and high-ranking dignitaries (including Vice President Spiro Agnew, former President Lyndon B. Johnson, and Army Chief of Staff William Westmoreland).\n\n```\n[13:32:00 UTC] Saturn V Liftoff\n │\n[13:34:42 UTC] S-IC First Stage Shutdown & Separation\n │\n[13:41:08 UTC] S-II Second Stage Cutoff & Separation\n │\n[13:44:00 UTC] Initial Earth Orbit Insertion (100.4 x 98.9 nmi)\n │ (1.5 Earth Orbits / 2.5 Hours)\n[16:16:16 UTC] S-IVB Trans-Lunar Injection (TLI) Burn (5 min, 47 sec)\n │\n[16:46:00 UTC] Transposition, Docking, & Extraction (Columbia docks with Eagle)\n```\n\nDuring the trans-lunar coast, the spent S-IVB stage was maneuvered past the Moon using a gravitational slingshot into heliocentric orbit to avoid impact with the spacecraft, Earth, or Moon.\n\n### Lunar Orbit Entry and Lunar Descent\nApollo 11 entered lunar orbit on July 19 at 17:21:50 UTC, completing 30 orbits over the course of its stay. On July 20 at 12:52:00 UTC, Armstrong and Aldrin entered *Eagle*. Undocking occurred at 17:44:00 UTC while Collins inspected the vehicle from *Columbia*.\n\nDuring descent, three operational criticalities developed:\n1. **Trajectory Overshoot (\"Downrange Long\"):** The LM passed surface landmarks 2 to 3 seconds early. Potential causes included gravitational mass concentrations (*mascons*), unvented air pressure in the docking tunnel prior to undocking, or dynamic perturbations from *Eagle’s* turn-around maneuver.\n2. **1201 and 1202 Computer Alarms:** Five minutes into the descent burn at an altitude of 6,000 feet (1,800 m), the Apollo Guidance Computer threw executive overflow alarms. Software engineer Margaret Hamilton had designed the AGC software to drop lower-priority tasks (such as processing secondary radar data) to preserve primary guidance calculations, preventing an automatic abort. Guidance Officer Steve Bales and computer technician Jack Garman in Houston issued a \"GO\" command. Software engineer Don Eyles later confirmed in 2005 that an electrical phasing mismatch in the rendezvous radar switch hardware caused the computer to steal extra processing cycles.\n3. **Hazard Avoidance and Manual Takeover:** Observing that the guidance system was directing *Eagle* into a boulder field surrounding West Crater (300 feet in diameter), Armstrong took manual pitch control to override the automatic lander system.\n\n```\n [1,800 m / 6,000 ft]\n 1201 & 1202 Alarms (Garman/Bales GO)\n │\n [91 m / 300 ft Altitude]\n West Crater Boulder Field Avoidance\n │\n [33 m / 107 ft Altitude]\n Low Fuel State & Dust Cloud Obscuration\n │\n [Surface Contact - 1.7 m Probes]\n \"Contact Light!\" -> Engine Shutdown\n │\n [20:17:40 UTC, July 20, 1969]\n Touchdown at Tranquility Base\n```\n\n*Eagle* touched down at 20:17:40 UTC on Sunday, July 20, 1969, with roughly 216 lb (98 kg) of usable propellant remaining—representing 25 to 50 seconds before an abort threshold would be triggered. Propellant sloshing had uncovered a fuel sensor early, prompting NASA to retrofit future lander tanks with anti-slosh baffles.\n\nUpon touchdown, Armstrong communicated the revised call sign to CAPCOM Charles Duke:\n> **Armstrong:** \"Houston, Tranquility Base here. The *Eagle* has landed.\"\n> **Duke:** \"Roger, Twan— Tranquility, we copy you on the ground. You got a bunch of guys about to turn blue. We're breathing again. Thanks a lot.\"\n\nTwo and a half hours after landing, Aldrin radioed Earth asking listeners to contemplate the event, then privately took Holy Communion using a kit prepared by Pastor Dean Woodruff of Webster Presbyterian Church (keeping the religious nature silent to avoid ongoing litigation filed against NASA by Madalyn Murray O'Hair).\n\n### Lunar Surface Operations (EVA)\nThe crew bypassed a scheduled 5-hour sleep cycle, initiating EVA prep at 23:43 UTC. Cabin depressurization began 6 hours and 39 minutes post-landing.\n\n```\n[02:39:33 UTC, July 21] Hatch Unsealed & Opened\n │\n[02:51:00 UTC] Armstrong Egress & Ladder Descent; MESA D-Ring Pulled\n │\n[02:56:15 UTC] Armstrong's First Step onto Lunar Regolith\n │\n[03:03:00 UTC] Contingency Soil Sample Collected\n │\n[03:15:00 UTC] Aldrin Egresses LM; Joins Armstrong on Surface\n │\n[03:41:00 UTC] Lunar Flag Assembly Planted & Saluted\n │\n[03:43:00 UTC] Presidential Telephone Call (Nixon / Oval Office)\n │\n[04:00:00 UTC] EASEP Deployment & Core Sample Drilling\n │\n[05:01:00 UTC] Ingress Completed; Equipment Dump\n │\n[05:11:13 UTC] LM Hatch Re-sealed and Cabin Pressurized\n```\n\n#### Major EVA Events and Artifacts\n* **Broadcast Television:** Slow-scan black-and-white signals were received by the Honeysuckle Creek Tracking Station and the Parkes Radio Telescope in Australia, converted for standard broadcast, and viewed by 600 million people.\n* **The First Step:** Armstrong stepped off the landing pad onto the surface at 02:56:15 UTC, declaring:\n > \"That's one small step for [a] man, one giant leap for mankind.\"\n* **Surface Dynamics:** Gravity was one-sixth of Earth's; mobility was primarily performed via \"loping\" or two-footed kangaroo hops. Sunlight generated distinct thermal effects on spacesuit visors, and kicking up fine regolith dust heavily soiled the lower suit layers.\n* **Flag Placement:** The Lunar Flag Assembly was driven only 2 inches (5 cm) into the hard subsurface.\n* **Presidential Call:** President Richard Nixon spoke with the crew via a radio line routed through the White House:\n > **Nixon:** \"...For one priceless moment in the whole history of man, all the people on this Earth are truly one: one in their pride in what you have done, and one in our prayers that you will return safely to Earth.\"\n > **Armstrong:** \"Thank you, Mr. President. It's a great honor and privilege for us to be here...\"\n* **Scientific Instruments Deployed:** The Early Apollo Scientific Experiments Package (EASEP) included:\n 1. *Passive Seismic Experiment Package:* Recorded moonquakes.\n 2. *Retroreflector Array:* Target for long-term Lunar Laser Ranging experiments.\n\n#### Commemorative Items Deposited on Lunar Surface\n* Stainless steel plaque on the LM descent stage ladder bearing two hemisphere drawings of Earth, signed by the three astronauts and President Nixon, reading:\n > \"Here men from the planet Earth first set foot upon the Moon July 1969, A. D. We came in peace for all mankind.\"\n* Apollo 1 patch commemorating Grissom, White, and Chaffee.\n* Memorial medals honoring deceased Soviet cosmonauts Vladimir Komarov and Yuri Gagarin.\n* Gold replica of an olive branch.\n* Silicon goodwill disc containing messages from leaders of 73 nations, U.S. Congressional leadership lists, and NASA executive records.\n\n#### Lunar Material Collection\nThe crew collected 47.51 lb (21.55 kg) of surface material, including core samples drilled 6 inches (15 cm) deep and rock types classified as basalt and breccia. Chemical analysis of the samples identified three new mineral structures:\n1. **Armalcolite:** Named after **Arm**strong, **Al**drin, and **Col**lins.\n2. **Tranquillityite:** Named after the Sea of Tranquility.\n3. **Pyroxferroite:** Iron-rich silicate mineral.\n*(All three minerals were subsequently discovered in Earth geology.)*\n\n### Solo Operations in Lunar Orbit (*Columbia*)\nWhile *Eagle* was on the surface, Michael Collins orbited the Moon solo aboard *Columbia*. Every orbit included 48 minutes on the far side of the Moon completely isolated from radio communication with Earth. In his autobiography, Collins refuted perceptions of extreme isolation:\n\n> \"...this venture has been structured for three men, and I consider my third to be as necessary as either of the other two... awareness, anticipation, satisfaction, confidence, almost exultation.\"\n\nDuring his third orbit, an Environmental Control System warning indicated a dangerous temperature drop in the coolant. Collins bypassed procedural steps to manually override procedure 17, toggling the switch between manual and automatic to normalize system function. He continuously attempted to spot *Eagle* using optical telescopes based on revised coordinates from Mission Control, though without success.\n\n### Ascent, Rendezvous, and Return Trajectory\nPrior to launch, Aldrin noticed that a suit backpack had accidentally sheared off the plastic circuit breaker stem required to arm the ascent engine switch. Aldrin successfully jammed the non-conductive plastic tip of a Duro felt-tip pen into the switch assembly to arm the propulsion system.\n\n```\n[17:54:00 UTC, July 21] Ascent Engine Fired; Liftoff from Moon\n │ (21.5 Hours total surface stay)\n │ Ascent blast knocks over U.S. Flag (observed by Aldrin)\n │\n[21:24:00 UTC] Eagle Rendezvous with Columbia in Orbit\n │\n[21:35:00 UTC] Docking Executed Successfully\n │\n[23:41:31 UTC, July 21] Eagle Ascent Stage Jettisoned into Lunar Orbit\n │\n[16:50:35 UTC, July 24] Splashdown in North Pacific Ocean\n```\n\nPrior to splashdown, US Air Force Captain Hank Brandli leveraged classified military spy satellite photography to identify a severe storm system heading directly toward the primary splashdown target zone. Brandli alerted Navy Captain Willard S. Houston Jr., Commander of the Fleet Weather Center at Pearl Harbor, allowing NASA to shift the landing target, avoiding extreme atmospheric turbulence that would have torn open the recovery parachutes.\n\n*Columbia* safely splashed down on July 24, 1969, at 16:50:35 UTC in the North Pacific Ocean, 13°19′N 169°9′W, and was retrieved by Navy divers and the prime recovery ship USS *Hornet*.\n\n---\n\n## 6. Contingency Planning and Historical Legacy\n\n### Operational Contingencies: The Safire Memo\nBecause lunar ascent carried zero redundancy, White House speechwriter William Safire drafted a contingency speech titled *\"In Event of Moon Disaster\"* for President Nixon on July 18, 1968. \n\nThe protocol mandated that in the event the astronauts were stranded on the surface:\n1. Mission Control would immediately terminate all two-way radio communications with the LM.\n2. A formal ritual likened to a burial at sea would be performed, wherein a clergyman would \"commend their souls to the deepest of the deep.\"\n3. The proposed announcement echoed World War I poet Rupert Brooke’s work *\"The Soldier\"*.\n4. The draft omitted mention of Michael Collins, as it was expected he would be forced to abandon his crewmates and return to Earth alone.\n\n### Post-Mission Disposition\n* **Crew Honors:** The crew was awarded the Presidential Medal of Freedom, given ticker-tape parades across the United States, and sent on an international goodwill tour.\n* **Spacecraft Artifacts:** The Command Module *Columbia* is displayed at the Smithsonian's National Air and Space Museum in Washington, D.C. The descent stage of *Eagle* remains *in situ* at Tranquility Base (0.67416°N, 23.47314°E). *Eagle’s* jettisoned ascent stage eventually impacted the Moon after its orbit decayed, though 2021 orbital mechanics calculations suggest it may potentially remain in an unstable lunar orbit." } } ``` </div> The data table job, in full ([step-17-table-job.json](/assets/articles/gemini-notebook-bash/step-17-table-job.json)): <div markdown="1" style="max-height:420px;overflow:auto"> ```json { "jobid": "job:bd4c1077-68c4-4e16-9ed8-122f31912c46-user:12345-user@example.com-bot:gemini_notebook", "email": "user@example.com", "type": "table", "status": "completed", "notebook": "user:12345-user@example.com-notebook:62600bab-4082-4ee6-8fc3-955cee0c69cf", "artifact": "user:12345-user@example.com-artifact:62600bab-4082-4ee6-8fc3-955cee0c69cf:3d9344ac-bc4b-4734-8c76-0d58279567cc", "created_at": "2026-09-29T05:53:06.323Z", "request": { "notebook": "user:12345-user@example.com-notebook:62600bab-4082-4ee6-8fc3-955cee0c69cf", "type": "table", "instructions": "One row per program alarm or anomaly during the descent: time, alarm or event, cause, what the crew or Mission Control did." }, "completed_at": "2026-09-29T05:53:38.651Z", "result": { "title": "Apollo 11 Descent Alarms and Anomalies", "table": [ [ "Time", "Alarm or event", "Cause", "What the crew or Mission Control did", "Source" ], [ "Five minutes into the descent burn / MET 102:38:00–102:38:22 / PDI + 316 seconds", "1202 program alarm", "Computer overload (Executive overflow: no core sets available). High-frequency counter increment requests from the rendezvous radar ECDUs, caused by an electrical phasing mismatch (800 Hz vs 400 Hz), stole 13% to 15% of computer CPU cycles while running V16N68.", "Buzz Aldrin checked the alarm code using Verb 90 Noun 50 (and Verb 05 Noun 09 at PDI + 322 seconds). Computer engineer Jack Garman checked his reference sheet and told Guidance Officer Steve Bales it was safe to continue. Bales verified telemetry/navigation, and CapCom Charlie Duke transmitted \"Go\" to the crew. The LGC software automatically eliminated lower-priority tasks to maintain critical guidance tasks. Crew hit Key Release at PDI + 380 seconds.", "[1] [2] [3] [4] [5] [6] [7]" ], [ "MET 102:36:55", "Slow spacecraft rotation rate during pitch-over/spin maneuver", "Autopilot rate switch was set at 5 deg/sec.", "Neil Armstrong switched the autopilot rate switch from 5 deg/sec to 25 deg/sec.", "[4]" ], [ "As descent began / Not in source", "Overshooting the Planned Landing Target / Downrange Position Offset (Trajectory shifted 3,000 ft downrange from target site)", "Residual pressure in the docking tunnel during separation, lunar gravitational anomalies (mascons), and accumulated state vector propagation errors or unmodeled forces during earlier maneuvers.", "The crew monitored their position closely, maintained composure, and prepared to adapt to landing further west than planned. Armstrong later engaged manual rate-of-descent mode to fly clear of rocks.", "[5] [6]" ], [ "During descent", "1202 Program Alarm shortly after Verb 57 was entered", "Computer overload (Executive alarm) due to CPU cycle stealing by the rendezvous radar interface combined with monitoring displays.", "Aldrin checked the alarm code using Verb 90 Noun 50. Mission Control issued a \"go\".", "[4]" ], [ "PDI + 552 seconds / MET 102:42:17", "1201 program alarm", "Computer overload (Executive overflow: no VAC areas available due to multiple scheduling of jobs like SERVICER). Caused by high-frequency counter increment requests from the rendezvous radar interface stealing CPU cycles during P64.", "Mission Control called a \"go\". Software restart automatically cleared dispensable jobs and maintained required guidance tasks while the crew focused inside the cockpit.", "[1] [2] [3] [4] [6] [7]" ], [ "PDI + 578 seconds / MET 102:42:41", "1202 program alarm", "Computer overload (Executive overflow: no core sets available) caused by high-frequency counter increment requests from the rendezvous radar interface stealing CPU cycles during P64.", "Mission Control called a \"go\". Software restart automatically executed to clean out old unfinished jobs.", "[3] [4]" ], [ "PDI + 594 seconds / MET 102:42:57 (at 770 ft altitude)", "1202 program alarm", "Computer overload (Executive overflow: no core sets available) caused by high-frequency counter increment requests from the rendezvous radar interface stealing CPU cycles during P64.", "Mission Control called a \"go\". Software restart automatically executed to clean out old unfinished jobs. Shortly after, Armstrong switched autopilot mode to ATT HOLD to stop automated redesignations and avoid further alarms.", "[3] [4]" ], [ "102:41:53 GET / Near landing approach (250 ft to 100 ft above surface)", "Guidance system targeting a boulder-strewn area near West Crater / Overrode automatic landing program P64 and selected P66 mode", "LM guidance computer targeted West Crater boulder field due to landing system targeting parameters and high horizontal velocity.", "Neil Armstrong took semi-automatic manual control (P66 mode), adjusting pitch and roll to pilot Eagle past the crater and boulder field to find a clear level patch of ground, while Buzz Aldrin continuously called out navigation and altitude data.", "[1] [2] [5] [6] [7]" ], [ "100 feet above the surface / Final descent", "Premature low fuel warning / Propellant Depletion Risk / Blinding Lunar Dust", "Propellant sloshing during P66 manual translation uncovered fuel sensor early. Engine exhaust kicked up lunar dust obscuring the surface.", "Armstrong used large rocks projecting above the dust to gauge horizontal speed, cleared a smaller crater, and landed with about 25 to 50 seconds of fuel remaining (90 seconds remaining when warning issued). Mission Control initiated a mandatory countdown with \"60 seconds\" and \"30 seconds\" warning calls from CapCom.", "[1] [2] [5] [6]" ], [ "Touchdown / Contact light call", "Delayed Engine Shutdown", "In the intensity of the moment, Armstrong delayed shutting down the engine for about three seconds after contact light.", "The lander settled safely; the crew ran post-landing checklists to secure the engine, and Armstrong announced touchdown.", "[6]" ], [ "Not in source", "Code 500", "The computer thought the landing radar antenna was in the wrong position (caused by misbehaving discrete signals).", "The crew saw switches were in the right positions, cycled them anyway, and the warning cleared.", "[4]" ], [ "Not in source", "Telemetry Disruption / Intermittent Loss of Signal (LOS)", "Vehicle pitch/yaw attitude obscured line-of-sight for S-Band High Gain Antenna.", "Switched to omni-directional antennas and CapCom requested vehicle re-orientation.", "[5]" ] ] } } ``` </div> The report as Markdown: [step-17-briefing-report.md](/assets/articles/gemini-notebook-bash/step-17-briefing-report.md). The table as CSV: [step-17-data-table.csv](/assets/articles/gemini-notebook-bash/step-17-data-table.csv). </details> #### 18. A Video Overview and a slide deck Both async. The slide deck finished in 5 minutes 10 seconds: 8 slides, with `pdf` and `pptx` files and one image per slide in `result.slides`. The Video Overview took 14 minutes and runs 11 minutes 50 seconds, a 720p `mp4` of 59 MB. Both are shown in [Results](#results). <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts">POST /artifacts</a> (video + slides, async)</summary> ```bash VIDEO=$(curl -sS -X POST "$API/artifacts" \ -H "Authorization: Bearer $USEAPI_TOKEN" -H "Content-Type: application/json" \ -d "$(jq -n --arg nb "$NOTEBOOK" '{notebook: $nb, type: "video", format: "explainer", style: "whiteboard", mode: "async"}')" | jq -r .jobid) SLIDES=$(curl -sS -X POST "$API/artifacts" \ -H "Authorization: Bearer $USEAPI_TOKEN" -H "Content-Type: application/json" \ -d "$(jq -n --arg nb "$NOTEBOOK" '{notebook: $nb, type: "slides", format: "presenter", length: "short", mode: "async"}')" | jq -r .jobid) for kind in slides video; do JOBID=$([ "$kind" = slides ] && echo "$SLIDES" || echo "$VIDEO") until curl -sS "$API/jobs/$(enc "$JOBID")" -H "Authorization: Bearer $USEAPI_TOKEN" > "$kind.json" && jq -e '.status == "completed" or .status == "failed"' "$kind.json" > /dev/null; do sleep 15 done cat "$kind.json" done ``` The slide deck job, in full ([step-18-slides-job.json](/assets/articles/gemini-notebook-bash/step-18-slides-job.json)): <div markdown="1" style="max-height:420px;overflow:auto"> ```json { "jobid": "job:425e9a82-4b00-4bec-9175-75a4957b59f7-user:12345-user@example.com-bot:gemini_notebook", "email": "user@example.com", "type": "slides", "status": "completed", "notebook": "user:12345-user@example.com-notebook:62600bab-4082-4ee6-8fc3-955cee0c69cf", "artifact": "user:12345-user@example.com-artifact:62600bab-4082-4ee6-8fc3-955cee0c69cf:41da332a-b388-4ca6-8ccf-95d1f12f6ce5", "created_at": "2026-09-29T05:53:51.140Z", "request": { "notebook": "user:12345-user@example.com-notebook:62600bab-4082-4ee6-8fc3-955cee0c69cf", "type": "slides", "format": "presenter", "length": "short" }, "completed_at": "2026-09-29T05:59:01.081Z", "result": { "title": "Apollo 11 Mission", "files": [ { "format": "pdf", "mimeType": "application/pdf", "url": "https://api.useapi.net/v1/gemini-notebook/artifacts/download?artifact=user%3A12345-user%40example.com-artifact%3A62600bab-4082-4ee6-8fc3-955cee0c69cf%3A41da332a-b388-4ca6-8ccf-95d1f12f6ce5&format=pdf" }, { "format": "pptx", "mimeType": "application/vnd.openxmlformats-officedocument.presentationml.presentation", "url": "https://api.useapi.net/v1/gemini-notebook/artifacts/download?artifact=user%3A12345-user%40example.com-artifact%3A62600bab-4082-4ee6-8fc3-955cee0c69cf%3A41da332a-b388-4ca6-8ccf-95d1f12f6ce5&format=pptx" } ], "slides": [ { "image": "https://api.useapi.net/v1/gemini-notebook/artifacts/download?artifact=user%3A12345-user%40example.com-artifact%3A62600bab-4082-4ee6-8fc3-955cee0c69cf%3A41da332a-b388-4ca6-8ccf-95d1f12f6ce5&format=slide&index=1", "caption": "Title slide for Apollo 11: The Giant Leap, featuring an astronaut on the moon with mission duration and success status.", "text": "APOLLO 11 THE GIANT LEAP\n\n[An astronaut in a white spacesuit stands on the gray, cratered lunar surface. The Earth is reflected in the gold visor of the helmet.]\n\n[A digital heads-up display box in the bottom left corner contains the following text:]\n- OPERATOR: NASA\n- MISSION DURATION: 08D : 03H : 18M : 35S\n- STATUS: MISSION SUCCESS" }, { "image": "https://api.useapi.net/v1/gemini-notebook/artifacts/download?artifact=user%3A12345-user%40example.com-artifact%3A62600bab-4082-4ee6-8fc3-955cee0c69cf%3A41da332a-b388-4ca6-8ccf-95d1f12f6ce5&format=slide&index=2", "caption": "Slide titled The Catalyst: A Cold War Ultimatum, detailing the space race's start and JFK's lunar landing strategy.", "text": "THE CATALYST: A COLD WAR ULTIMATUM\n\n[A timeline on a black background features a vertical red glowing line with two points.]\n- Oct 4, 1957: USSR launches Sputnik 1, igniting the Space Race and challenging US claims of superiority.\n- Apr 12, 1961: Yuri Gagarin becomes the first human in space.\n\n[A photo shows President John F. Kennedy speaking at a podium in a crowded stadium.]\n\nTHE ULTIMATUM\n\"We choose to go to the Moon in this decade and do the other things, not because they are easy, but because they are hard.\"\n\nTHE STRATEGY\nBecause the USSR had superior launch capacity, Kennedy chose a challenge so extreme (a crewed lunar landing) that both nations would effectively have to start from zero." }, { "image": "https://api.useapi.net/v1/gemini-notebook/artifacts/download?artifact=user%3A12345-user%40example.com-artifact%3A62600bab-4082-4ee6-8fc3-955cee0c69cf%3A41da332a-b388-4ca6-8ccf-95d1f12f6ce5&format=slide&index=3", "caption": "Diagram and table explaining the Lunar Orbit Rendezvous architecture, featuring the Saturn V, Columbia, and Eagle modules.", "text": "THE ARCHITECTURE: LUNAR ORBIT RENDEZVOUS\n\n[A diagram shows the mission path from Earth to the Moon. A Saturn V rocket launches from Earth. The Columbia module orbits the moon with heavy return fuel, while the lightweight Eagle lander descends to the surface and then ascends back to orbit.]\n\nCOMMAND MODULE (COLUMBIA)\n- Manufacturer: North American Rockwell\n- Role: Crew cabin, Earth return vehicle\n- Final Resting Place: Preserved at National Air and Space Museum\n\nSERVICE MODULE\n- Role: Propulsion, electrical power, oxygen, and water\n- Final Resting Place: Jettisoned / Burned up\n\nLUNAR MODULE (EAGLE)\n- Manufacturer: Grumman\n- Role: Lunar descent and ascent (2 stages)\n- Landing Mass: 10,873 lb (4,932 kg)\n- Final Resting Place: Descent stage remains at Tranquility Base" }, { "image": "https://api.useapi.net/v1/gemini-notebook/artifacts/download?artifact=user%3A12345-user%40example.com-artifact%3A62600bab-4082-4ee6-8fc3-955cee0c69cf%3A41da332a-b388-4ca6-8ccf-95d1f12f6ce5&format=slide&index=4", "caption": "Slide titled The Vanguard: An Ecosystem of Support, illustrating the crew, mission control, and software/support teams.", "text": "THE VANGUARD: AN ECOSYSTEM OF SUPPORT\n\n[A photo of the three Apollo 11 astronauts in their spacesuits.]\n\n[A three-tiered pyramid diagram outlines the support structure.]\n\nTHE CREW TRIAD\n- Neil Armstrong (Commander) – Surface\n- Buzz Aldrin (Lunar Module Pilot) – Surface\n- Michael Collins (Command Module Pilot) – Lunar Orbit\n\nMISSION CONTROL\n- Gene Kranz (Flight Director, White Team – Lunar Landing)\n- Charles Duke (CAPCOM – The sole voice to the capsule)\n\nTHE INVISIBLE ARMY\n- Margaret Hamilton (Onboard flight computer software engineer)\n- Jack Garman (Computer engineer)\n- Eleanor Foraker (Spacesuit tailor)\n\n\"All you see is the three of us, but beneath the surface are thousands and thousands of others.\" — Michael Collins" }, { "image": "https://api.useapi.net/v1/gemini-notebook/artifacts/download?artifact=user%3A12345-user%40example.com-artifact%3A62600bab-4082-4ee6-8fc3-955cee0c69cf%3A41da332a-b388-4ca6-8ccf-95d1f12f6ce5&format=slide&index=5", "caption": "Details the lunar descent, including the 1202 executive overflow alarm and the software architecture that saved the landing.", "text": "THE DESCENT: OVERLOAD AND OVERRIDE\n\n[A photo shows the Lunar Module Eagle descending over the cratered moon surface.]\n\nTENSION METERS & ACTION LOG\n- ALTITUDE: [A line graph shows a descent from 1500 FT to 100 FT, currently at 120 FT.]\n- PROPELLANT: [A bar graph shows 90 SECONDS REMAINING. A note reads: (SENSOR UNCOVERED BY SLOSHING)]\n- HAZARD: AGC TARGETING BOULDER FIELD (WEST CRATER)\n\nTHE 1202 EXECUTIVE OVERFLOW\n[A funnel diagram shows Rendezvous Radar (Hardware Bug) and Landing Radar data entering. A filter allows landing data through while rejecting the radar bug data.]\n- REJECTED\n- CRITICAL LANDING THRUSTERS CONTINUE FIRING.\n- JACK GARMAN CLEARS ALARM: SAFE TO CONTINUE\n\n[A terminal-style text box contains the following action log:]\n- -> ARMSTRONG TAKES SEMI-AUTOMATIC CONTROL\n- -> CONTACT LIGHT\n- -> HOUSTON, TRANQUILITY BASE HERE. THE EAGLE HAS LANDED." }, { "image": "https://api.useapi.net/v1/gemini-notebook/artifacts/download?artifact=user%3A12345-user%40example.com-artifact%3A62600bab-4082-4ee6-8fc3-955cee0c69cf%3A41da332a-b388-4ca6-8ccf-95d1f12f6ce5&format=slide&index=6", "caption": "Overview of activities at Tranquility Base, including viewership stats, EVA duration, lunar samples, and the Nixon call.", "text": "TRANQUILITY BASE: MAGNIFICENT DESOLATION\n\n[A central photo shows an astronaut saluting the American flag next to the Lunar Module on the moon, with Earth visible in the dark sky above. Below the photo is a golden audio waveform.]\n\"That's one small step for [a] man, one giant leap for mankind.\"\n\nVIEWERSHIP\n- ~600 million viewers (Roughly 1/5th of global population)\n\nSURFACE EVA DURATION\n- 2 hours, 31 minutes, 40 seconds\n\nLUNAR YIELD\n- 47.51 lb (21.55 kg) of samples\n- Discovered 3 new minerals: armalcolite, tranquillityite, pyroxferroite\n\nCOMMUNICATION\n- The most historic phone call ever made — President Nixon from the Oval Office" }, { "image": "https://api.useapi.net/v1/gemini-notebook/artifacts/download?artifact=user%3A12345-user%40example.com-artifact%3A62600bab-4082-4ee6-8fc3-955cee0c69cf%3A41da332a-b388-4ca6-8ccf-95d1f12f6ce5&format=slide&index=7", "caption": "Infographic of the 8-day mission trajectory from Earth launch to lunar orbit and splashdown in the Pacific Ocean.", "text": "THE TRAJECTORY: 8 DAYS, 3 HOURS, 18 MINUTES\n\n[A diagram shows a blue infinity-loop flight path between the Earth and the Moon.]\n- JUL 16, 13:32 UTC: Launch: Saturn V AS-506 lifts off from LC-39A.\n- TRANSLUNAR INJECTION: S-IVB engine pushes CSM/LM toward the Moon.\n- JUL 19 – LUNAR ORBIT: Columbia orbits the Moon 30 times.\n- JUL 20–21 – DESCENT & ASCENT: Eagle lands, surface EVA, and ascent stage lifts off to rendezvous at 21:24 UTC.\n- JUL 24, 16:50 UTC: Splashdown: Columbia strikes the Pacific Ocean 24 km from USS Hornet.\n\n[A photo shows the Command Module floating in the ocean surrounded by green flotation rings.]\n- NOTE: Returning astronauts placed in a Mobile Quarantine Facility for 21 days due to Extra-Terrestrial Exposure laws." }, { "image": "https://api.useapi.net/v1/gemini-notebook/artifacts/download?artifact=user%3A12345-user%40example.com-artifact%3A62600bab-4082-4ee6-8fc3-955cee0c69cf%3A41da332a-b388-4ca6-8ccf-95d1f12f6ce5&format=slide&index=8", "caption": "Final slide comparing the 1961 Cold War origins of the mission to its 1969 result as a moment of global unification.", "text": "THE SYNTHESIS: FOR ALL MANKIND\n\n[A photo of a plaque featuring a map of Earth and the text: Here men from the planet Earth first set foot upon the Moon July 1969, A. D. We came in peace for all mankind.]\n\nTHE ORIGIN (1961)\n- Driver: National survival and military/technological superiority.\n- Context: A divided world locked in the Cold War.\n\nTHE RESULT (1969)\n- Driver: Global unification and insatiable human curiosity.\n- Context: 600 million people experiencing a single moment together.\n\nThe ultimate weapon of the Cold War Space Race inadvertently engineered humanity's greatest moment of peaceful unification. As President Nixon stated upon their return: \"The world has never been closer together before.\"" } ] } } ``` </div> The video job, in full ([step-18-video-job.json](/assets/articles/gemini-notebook-bash/step-18-video-job.json)): <div markdown="1" style="max-height:420px;overflow:auto"> ```json { "jobid": "job:ca1688fd-3416-43c7-894c-1177b985282a-user:12345-user@example.com-bot:gemini_notebook", "email": "user@example.com", "type": "video", "status": "completed", "notebook": "user:12345-user@example.com-notebook:62600bab-4082-4ee6-8fc3-955cee0c69cf", "artifact": "user:12345-user@example.com-artifact:62600bab-4082-4ee6-8fc3-955cee0c69cf:6759c800-68cf-40c6-9824-31a0ff417f1a", "created_at": "2026-09-29T05:53:45.260Z", "request": { "notebook": "user:12345-user@example.com-notebook:62600bab-4082-4ee6-8fc3-955cee0c69cf", "type": "video", "format": "explainer", "style": "whiteboard" }, "completed_at": "2026-09-29T06:07:47.466Z", "result": { "title": "Apollo 11: Untold Stories", "duration": 710, "files": [ { "format": "mp4", "mimeType": "video/mp4", "url": "https://api.useapi.net/v1/gemini-notebook/artifacts/download?artifact=user%3A12345-user%40example.com-artifact%3A62600bab-4082-4ee6-8fc3-955cee0c69cf%3A6759c800-68cf-40c6-9824-31a0ff417f1a&format=mp4" } ] } } ``` </div> The files: [the deck as PDF](https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-slides-presenter-apollo11-deck-0929.pdf){:target="_blank"}, [the deck as PowerPoint](https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-slides-presenter-apollo11-deck-0929.pptx) and [the video's first 90 seconds (mp4)](https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-video-explainer-whiteboard-apollo11-first90s-0929.mp4){:target="_blank"}. The full 59 MB video is larger than our media host allows. </details> #### 19. Revise one slide [POST /artifacts/revise](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts-revise) redrew slide 2 from a prompt in 51 seconds. The revision is a new artifact with its own `artifact` id, its job's result is the whole deck again with the new slide 2, and the original deck stays in the notebook. Before and after are shown in [Results](#results). <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts-revise">POST /artifacts/revise</a></summary> ```bash curl -sS -X POST "$API/artifacts/revise" \ -H "Authorization: Bearer $USEAPI_TOKEN" -H "Content-Type: application/json" \ -d "$(jq -n --arg a "$(jq -r .artifact slides.json)" '{artifact: $a, slide: 2, prompt: "Make this slide a simple timeline graphic.", mode: "async"}')" # then poll GET /jobs/{jobid} as in step 11 ``` It returned, in full ([step-19-revise-job.json](/assets/articles/gemini-notebook-bash/step-19-revise-job.json)): <div markdown="1" style="max-height:420px;overflow:auto"> ```json { "jobid": "job:13cad8cf-27ec-4da4-9913-d65ff024fd77-user:12345-user@example.com-bot:gemini_notebook", "email": "user@example.com", "type": "slides", "status": "completed", "notebook": "user:12345-user@example.com-notebook:62600bab-4082-4ee6-8fc3-955cee0c69cf", "artifact": "user:12345-user@example.com-artifact:62600bab-4082-4ee6-8fc3-955cee0c69cf:31db5568-e2dc-4447-a0f8-b47e99ef8be4", "created_at": "2026-09-29T06:08:11.703Z", "request": { "artifact": "user:12345-user@example.com-artifact:62600bab-4082-4ee6-8fc3-955cee0c69cf:41da332a-b388-4ca6-8ccf-95d1f12f6ce5", "slide": 2, "prompt": "Make this slide a simple timeline graphic." }, "completed_at": "2026-09-29T06:09:02.763Z", "result": { "title": "Apollo 11 Mission (2)", "files": [ { "format": "pdf", "mimeType": "application/pdf", "url": "https://api.useapi.net/v1/gemini-notebook/artifacts/download?artifact=user%3A12345-user%40example.com-artifact%3A62600bab-4082-4ee6-8fc3-955cee0c69cf%3A31db5568-e2dc-4447-a0f8-b47e99ef8be4&format=pdf" }, { "format": "pptx", "mimeType": "application/vnd.openxmlformats-officedocument.presentationml.presentation", "url": "https://api.useapi.net/v1/gemini-notebook/artifacts/download?artifact=user%3A12345-user%40example.com-artifact%3A62600bab-4082-4ee6-8fc3-955cee0c69cf%3A31db5568-e2dc-4447-a0f8-b47e99ef8be4&format=pptx" } ], "slides": [ { "image": "https://api.useapi.net/v1/gemini-notebook/artifacts/download?artifact=user%3A12345-user%40example.com-artifact%3A62600bab-4082-4ee6-8fc3-955cee0c69cf%3A31db5568-e2dc-4447-a0f8-b47e99ef8be4&format=slide&index=1", "caption": "Title slide for Apollo 11: The Giant Leap, featuring an astronaut on the moon with mission duration and success status.", "text": "APOLLO 11 THE GIANT LEAP\n\n[An astronaut in a white spacesuit stands on the gray, cratered lunar surface. The Earth is reflected in the gold visor of the helmet.]\n\n[A digital heads-up display box in the bottom left corner contains the following text:]\n- OPERATOR: NASA\n- MISSION DURATION: 08D : 03H : 18M : 35S\n- STATUS: MISSION SUCCESS" }, { "image": "https://api.useapi.net/v1/gemini-notebook/artifacts/download?artifact=user%3A12345-user%40example.com-artifact%3A62600bab-4082-4ee6-8fc3-955cee0c69cf%3A31db5568-e2dc-4447-a0f8-b47e99ef8be4&format=slide&index=2", "caption": "A Cold War timeline detailing Soviet space achievements in 1957 and 1961 and Kennedy's response to reach the Moon.", "text": "THE CATALYST: A COLD WAR ULTIMATUM\n\n[Timeline graphic with two red horizontal lines and circular node markers on the left]\n\n- Oct 4, 1957: USSR launches Sputnik 1, igniting the Space Race and challenging US claims of superiority.\n- Apr 12, 1961: Yuri Gagarin becomes the first human in space.\n\n\nTHE ULTIMATUM\n\n\"We choose to go to the Moon in this decade and do the other things, not because they are easy, but because they are hard.\"\n\n\nTHE STRATEGY\n\nBecause the USSR had superior launch capacity, Kennedy chose a challenge so extreme (a crewed lunar landing) that both nations would effectively have to start from zero." }, { "image": "https://api.useapi.net/v1/gemini-notebook/artifacts/download?artifact=user%3A12345-user%40example.com-artifact%3A62600bab-4082-4ee6-8fc3-955cee0c69cf%3A31db5568-e2dc-4447-a0f8-b47e99ef8be4&format=slide&index=3", "caption": "Diagram and table explaining the Lunar Orbit Rendezvous architecture, featuring the Saturn V, Columbia, and Eagle modules.", "text": "THE ARCHITECTURE: LUNAR ORBIT RENDEZVOUS\n\n[A diagram shows the mission path from Earth to the Moon. A Saturn V rocket launches from Earth. The Columbia module orbits the moon with heavy return fuel, while the lightweight Eagle lander descends to the surface and then ascends back to orbit.]\n\nCOMMAND MODULE (COLUMBIA)\n- Manufacturer: North American Rockwell\n- Role: Crew cabin, Earth return vehicle\n- Final Resting Place: Preserved at National Air and Space Museum\n\nSERVICE MODULE\n- Role: Propulsion, electrical power, oxygen, and water\n- Final Resting Place: Jettisoned / Burned up\n\nLUNAR MODULE (EAGLE)\n- Manufacturer: Grumman\n- Role: Lunar descent and ascent (2 stages)\n- Landing Mass: 10,873 lb (4,932 kg)\n- Final Resting Place: Descent stage remains at Tranquility Base" }, { "image": "https://api.useapi.net/v1/gemini-notebook/artifacts/download?artifact=user%3A12345-user%40example.com-artifact%3A62600bab-4082-4ee6-8fc3-955cee0c69cf%3A31db5568-e2dc-4447-a0f8-b47e99ef8be4&format=slide&index=4", "caption": "Slide titled The Vanguard: An Ecosystem of Support, illustrating the crew, mission control, and software/support teams.", "text": "THE VANGUARD: AN ECOSYSTEM OF SUPPORT\n\n[A photo of the three Apollo 11 astronauts in their spacesuits.]\n\n[A three-tiered pyramid diagram outlines the support structure.]\n\nTHE CREW TRIAD\n- Neil Armstrong (Commander) – Surface\n- Buzz Aldrin (Lunar Module Pilot) – Surface\n- Michael Collins (Command Module Pilot) – Lunar Orbit\n\nMISSION CONTROL\n- Gene Kranz (Flight Director, White Team – Lunar Landing)\n- Charles Duke (CAPCOM – The sole voice to the capsule)\n\nTHE INVISIBLE ARMY\n- Margaret Hamilton (Onboard flight computer software engineer)\n- Jack Garman (Computer engineer)\n- Eleanor Foraker (Spacesuit tailor)\n\n\"All you see is the three of us, but beneath the surface are thousands and thousands of others.\" — Michael Collins" }, { "image": "https://api.useapi.net/v1/gemini-notebook/artifacts/download?artifact=user%3A12345-user%40example.com-artifact%3A62600bab-4082-4ee6-8fc3-955cee0c69cf%3A31db5568-e2dc-4447-a0f8-b47e99ef8be4&format=slide&index=5", "caption": "Details the lunar descent, including the 1202 executive overflow alarm and the software architecture that saved the landing.", "text": "THE DESCENT: OVERLOAD AND OVERRIDE\n\n[A photo shows the Lunar Module Eagle descending over the cratered moon surface.]\n\nTENSION METERS & ACTION LOG\n- ALTITUDE: [A line graph shows a descent from 1500 FT to 100 FT, currently at 120 FT.]\n- PROPELLANT: [A bar graph shows 90 SECONDS REMAINING. A note reads: (SENSOR UNCOVERED BY SLOSHING)]\n- HAZARD: AGC TARGETING BOULDER FIELD (WEST CRATER)\n\nTHE 1202 EXECUTIVE OVERFLOW\n[A funnel diagram shows Rendezvous Radar (Hardware Bug) and Landing Radar data entering. A filter allows landing data through while rejecting the radar bug data.]\n- REJECTED\n- CRITICAL LANDING THRUSTERS CONTINUE FIRING.\n- JACK GARMAN CLEARS ALARM: SAFE TO CONTINUE\n\n[A terminal-style text box contains the following action log:]\n- -> ARMSTRONG TAKES SEMI-AUTOMATIC CONTROL\n- -> CONTACT LIGHT\n- -> HOUSTON, TRANQUILITY BASE HERE. THE EAGLE HAS LANDED." }, { "image": "https://api.useapi.net/v1/gemini-notebook/artifacts/download?artifact=user%3A12345-user%40example.com-artifact%3A62600bab-4082-4ee6-8fc3-955cee0c69cf%3A31db5568-e2dc-4447-a0f8-b47e99ef8be4&format=slide&index=6", "caption": "Overview of activities at Tranquility Base, including viewership stats, EVA duration, lunar samples, and the Nixon call.", "text": "TRANQUILITY BASE: MAGNIFICENT DESOLATION\n\n[A central photo shows an astronaut saluting the American flag next to the Lunar Module on the moon, with Earth visible in the dark sky above. Below the photo is a golden audio waveform.]\n\"That's one small step for [a] man, one giant leap for mankind.\"\n\nVIEWERSHIP\n- ~600 million viewers (Roughly 1/5th of global population)\n\nSURFACE EVA DURATION\n- 2 hours, 31 minutes, 40 seconds\n\nLUNAR YIELD\n- 47.51 lb (21.55 kg) of samples\n- Discovered 3 new minerals: armalcolite, tranquillityite, pyroxferroite\n\nCOMMUNICATION\n- The most historic phone call ever made — President Nixon from the Oval Office" }, { "image": "https://api.useapi.net/v1/gemini-notebook/artifacts/download?artifact=user%3A12345-user%40example.com-artifact%3A62600bab-4082-4ee6-8fc3-955cee0c69cf%3A31db5568-e2dc-4447-a0f8-b47e99ef8be4&format=slide&index=7", "caption": "Infographic of the 8-day mission trajectory from Earth launch to lunar orbit and splashdown in the Pacific Ocean.", "text": "THE TRAJECTORY: 8 DAYS, 3 HOURS, 18 MINUTES\n\n[A diagram shows a blue infinity-loop flight path between the Earth and the Moon.]\n- JUL 16, 13:32 UTC: Launch: Saturn V AS-506 lifts off from LC-39A.\n- TRANSLUNAR INJECTION: S-IVB engine pushes CSM/LM toward the Moon.\n- JUL 19 – LUNAR ORBIT: Columbia orbits the Moon 30 times.\n- JUL 20–21 – DESCENT & ASCENT: Eagle lands, surface EVA, and ascent stage lifts off to rendezvous at 21:24 UTC.\n- JUL 24, 16:50 UTC: Splashdown: Columbia strikes the Pacific Ocean 24 km from USS Hornet.\n\n[A photo shows the Command Module floating in the ocean surrounded by green flotation rings.]\n- NOTE: Returning astronauts placed in a Mobile Quarantine Facility for 21 days due to Extra-Terrestrial Exposure laws." }, { "image": "https://api.useapi.net/v1/gemini-notebook/artifacts/download?artifact=user%3A12345-user%40example.com-artifact%3A62600bab-4082-4ee6-8fc3-955cee0c69cf%3A31db5568-e2dc-4447-a0f8-b47e99ef8be4&format=slide&index=8", "caption": "Final slide comparing the 1961 Cold War origins of the mission to its 1969 result as a moment of global unification.", "text": "THE SYNTHESIS: FOR ALL MANKIND\n\n[A photo of a plaque featuring a map of Earth and the text: Here men from the planet Earth first set foot upon the Moon July 1969, A. D. We came in peace for all mankind.]\n\nTHE ORIGIN (1961)\n- Driver: National survival and military/technological superiority.\n- Context: A divided world locked in the Cold War.\n\nTHE RESULT (1969)\n- Driver: Global unification and insatiable human curiosity.\n- Context: 600 million people experiencing a single moment together.\n\nThe ultimate weapon of the Cold War Space Race inadvertently engineered humanity's greatest moment of peaceful unification. As President Nixon stated upon their return: \"The world has never been closer together before.\"" } ] } } ``` </div> `slides.json` is the finished slides job from step 18. The files: [slide 2 as generated](https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-slides-presenter-apollo11-slide2-0929.png){:target="_blank"} and [slide 2 revised](https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-slides-presenter-apollo11-slide2-revised-timeline-0929.png){:target="_blank"}. </details> The second script used about 25% of the 5-hour window and 1.2% of the week. The Video Overview and the slide deck are the expensive ones, at Google's estimate of about 11% and 14% each. ### Shortcuts For a single artifact you do not need to manage a notebook. Send the sources straight to [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts#one-shot-requests): the API creates a notebook on one of your accounts with a free job slot whose usage window allows the job, waits for the sources, generates, and can delete the notebook afterwards for text-only types. If it answers `202` (the job outlived the 90-second wait), poll its `jobid`. <details markdown="block"> <summary><code>curl</code> — a quiz straight from a URL</summary> ```bash curl -sS -X POST "$API/artifacts" \ -H "Authorization: Bearer $USEAPI_TOKEN" -H "Content-Type: application/json" \ -d '{"type": "quiz", "urls": ["https://en.wikipedia.org/wiki/Apollo_11"], "deleteNotebook": true}' \ | jq '{status, questions: (.result.content.quiz | length)}' ``` </details> To be told when a job finishes instead of polling, pass `replyUrl` (and optionally `replyRef`) with `mode: async`, on Studio jobs and research alike. The API sends one POST with the same job record [GET /jobs/`jobid`](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid) returns. [DELETE /jobs/`jobid`](/docs/api-gemini-notebook-v1/delete-gemini-notebook-jobs-jobid) stops a research run you no longer need. <details markdown="block"> <summary><code>curl</code> — Deep Research with a webhook</summary> ```bash curl -sS -X POST "$API/research" \ -H "Authorization: Bearer $USEAPI_TOKEN" -H "Content-Type: application/json" \ -d "$(jq -n --arg nb "$NOTEBOOK" '{notebook: $nb, type: "deep", query: "How did the Apollo guidance computer recover from overloads?", mode: "async", replyUrl: "https://example.com/hooks/notebook", replyRef: "order-42"}')" ``` </details> ### More of the API The rest of the API, on an Apollo 11 notebook like the one above: - [GET /notebooks/guide](/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks-guide) returned Google's summary of the whole notebook, three suggested reports such as "Explain the technical challenges faced during the Eagle's lunar descent.", and three suggested chat questions. - [POST /chat/settings](/docs/api-gemini-notebook-v1/post-gemini-notebook-chat-settings) with the persona "You are a NASA flight controller. Answer in two sentences." made the next answers short and in that voice. [GET /chat](/docs/api-gemini-notebook-v1/get-gemini-notebook-chat) then returned the conversation's four turns, oldest first, and [DELETE /chat](/docs/api-gemini-notebook-v1/delete-gemini-notebook-chat) cleared it. - [POST /notes](/docs/api-gemini-notebook-v1/post-gemini-notebook-notes) with `conversation` saved that whole conversation as one note, "Chat History", question and answer by turn. - [POST /notes/mindmap](/docs/api-gemini-notebook-v1/post-gemini-notebook-notes-mindmap) made a mind map note, "Apollo 11 Mission", with six branches from "Background & Goals" to "Legacy & Artifacts". - [POST /labels](/docs/api-gemini-notebook-v1/post-gemini-notebook-labels) with `auto: "all"` grouped both sources under a "Space Exploration" label. Labels of your own take a name and an emoji, and [POST /labels/`label`](/docs/api-gemini-notebook-v1/post-gemini-notebook-labels-label) renames them and moves sources in and out. - [POST /notebooks/copy](/docs/api-gemini-notebook-v1/post-gemini-notebook-notebooks-copy) copied the notebook with its two sources and two Studio artifacts. - [POST /accounts](/docs/api-gemini-notebook-v1/post-gemini-notebook-accounts) with `outputLanguage: "es"` switched the account's Studio output to Spanish, and back. - [POST /research](/docs/api-gemini-notebook-v1/post-gemini-notebook-research) with `source: "drive"` searches the account's Google Drive instead of the web. It found a Word `.docx` and a Google Doc about Apollo 11, and [POST /research/import](/docs/api-gemini-notebook-v1/post-gemini-notebook-research-import) added them as Drive sources. After the Doc was edited in Drive, [GET /sources/`source`](/docs/api-gemini-notebook-v1/get-gemini-notebook-sources-source) reported it `inSync: false`, and a few seconds later the notebook held the new text. [POST /sources/sync](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources-sync) re-imports a changed Drive file on request. - A preset report takes extra `instructions`: a briefing "for a high-school class, in under 300 words" came back as 1,946 characters. ### What the Gemini Notebook API (NotebookLM API) can do | Step | Endpoint | What it does | |------|----------|--------------| | Create a notebook | [POST /notebooks](/docs/api-gemini-notebook-v1/post-gemini-notebook-notebooks) | Creates an empty notebook on one of your connected accounts. | | Add sources | [POST /sources](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources) | Web pages and YouTube videos (`urls`, up to 50 per call), pasted `text` and Google Drive files (`drive`). | | Upload a file | [POST /sources/upload](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources-upload) | The file is the raw request body: PDF, Word, PowerPoint, EPUB, Markdown, text, CSV, audio, video or an image. | | Read a source | [GET /sources/`source`](/docs/api-gemini-notebook-v1/get-gemini-notebook-sources-source) | Google's summary and key topics of one source, and with `content=true` the text Google indexed. | | Ask | [POST /chat](/docs/api-gemini-notebook-v1/post-gemini-notebook-chat) | An answer from the sources with numbered citations. Pass `conversation` for a follow-up. | | Keep notes | [POST /notes](/docs/api-gemini-notebook-v1/post-gemini-notebook-notes) | Notes in the notebook. A note can become a source. | | Research | [POST /research](/docs/api-gemini-notebook-v1/post-gemini-notebook-research) | `fast` finds sources on the web in seconds, `deep` runs Deep Research and writes a cited report. | | Import research | [POST /research/import](/docs/api-gemini-notebook-v1/post-gemini-notebook-research-import) | Adds the sources a research run found, and its report, to the notebook. | | Generate | [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts) | `audio`, `video`, `report`, `interactive_report`, `table`, `quiz`, `flashcards`, `mindmap`, `infographic` or `slides`, each with its own options. | | Revise a slide | [POST /artifacts/revise](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts-revise) | Redraws one slide of a finished deck from a prompt. | | Follow a job | [GET /jobs/`jobid`](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid) | The status and, once finished, the result. | | Download | [GET /artifacts/download](/docs/api-gemini-notebook-v1/get-gemini-notebook-artifacts-download) | The artifact's file (`m4a`, `mp4`, `pdf`, `pptx`, `png`), streamed with your API token. | | Share | [POST /sharing](/docs/api-gemini-notebook-v1/post-gemini-notebook-sharing) | Invite people as viewers or editors, turn the public link on or off, and limit viewers to chat only. | | Copy a notebook | [POST /notebooks/copy](/docs/api-gemini-notebook-v1/post-gemini-notebook-notebooks-copy) | A copy with every source and Studio artifact, on the same account. | | Notebook guide | [GET /notebooks/guide](/docs/api-gemini-notebook-v1/get-gemini-notebook-notebooks-guide) | Google's summary of the whole notebook, suggested reports and suggested chat questions. | | Chat history and settings | [GET /chat](/docs/api-gemini-notebook-v1/get-gemini-notebook-chat), [DELETE /chat](/docs/api-gemini-notebook-v1/delete-gemini-notebook-chat), [POST /chat/settings](/docs/api-gemini-notebook-v1/post-gemini-notebook-chat-settings) | A conversation's turns, delete the history, and set the chat's goal, persona and answer length. | | Source labels | [POST /labels](/docs/api-gemini-notebook-v1/post-gemini-notebook-labels) | Google labels the sources by topic, or you make and edit your own labels. | | Mind map note | [POST /notes/mindmap](/docs/api-gemini-notebook-v1/post-gemini-notebook-notes-mindmap) | A mind map made in one call and kept as a note. | | Output language | [POST /accounts](/docs/api-gemini-notebook-v1/post-gemini-notebook-accounts) | The language Google writes Studio artifacts in, for the whole account. | The [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts#options-by-type) page lists every Studio type's options. ### Run both scripts yourself Both scripts save every response under a timestamped folder. The first builds the notebook, the second takes the notebook, conversation and note ids the first one printed. Both scripts are also in the [notebooklm-api GitHub repo](https://github.com/useapi/notebooklm-api), with Node.js and Python examples that turn URLs into an Audio Overview podcast and save a Deep Research report as Markdown. <details markdown="block"> <summary>The first script (steps 1 to 14) and its output</summary> ```bash #!/usr/bin/env bash # USEAPI_TOKEN=user:12345-... EMAIL=user@example.com ./gemini-notebook-demo.sh [path/to/file.pdf] set -euo pipefail API="${API:-https://api.useapi.net/v1/gemini-notebook}" : "${USEAPI_TOKEN:?export USEAPI_TOKEN=user:12345-...}" : "${EMAIL:?export EMAIL=<your connected Google account>}" PDF="${1:-}" OUT="gemini-notebook-demo/$(date -u +%Y-%m-%dT%H-%M-%SZ)" mkdir -p "$OUT" AUTH=(-H "Authorization: Bearer $USEAPI_TOKEN") enc() { jq -rn --arg v "$1" '$v|@uri'; } # Research import can take a minute or two (Google fetches every URL first); the API answers within about 2 minutes post() { curl -sS --max-time 310 "${AUTH[@]}" -H "Content-Type: application/json" -X POST "$API/$1" -d "$2"; } get() { curl -sS "${AUTH[@]}" "$API/$1"; } log() { echo "$(date +%H:%M:%S) $*"; } wait_job() { until get "jobs/$(enc "$1")" > "$2" && jq -e '.status == "completed" or .status == "failed"' "$2" > /dev/null; do sleep 15; done } # 1. A notebook on your account post notebooks "$(jq -n --arg email "$EMAIL" '{email: $email, title: "Apollo 11"}')" > "$OUT/01-notebook.json" NOTEBOOK=$(jq -r .notebook "$OUT/01-notebook.json") log "notebook $NOTEBOOK" # 2. Sources: a web page, a YouTube video and pasted text in one call post sources "$(jq -n --arg nb "$NOTEBOOK" '{ notebook: $nb, urls: ["https://en.wikipedia.org/wiki/Apollo_11", "https://www.youtube.com/watch?v=xUcYQ7slmRw"], title: "Why Apollo 11 almost did not land", text: "During the descent the guidance computer raised 1202 and 1201 program alarms, and Armstrong flew the final approach manually to avoid a boulder field, landing with little fuel to spare." }')" > "$OUT/02-sources.json" jq -r '.sources[] | " \(.kind) \(.status) \(.title)"' "$OUT/02-sources.json" # 3. Optional: a file, sent as the raw request body if [ -n "$PDF" ]; then curl -sS "${AUTH[@]}" -H "Content-Type: application/pdf" --data-binary "@$PDF" \ "$API/sources/upload?notebook=$(enc "$NOTEBOOK")&name=$(enc "$(basename "$PDF")")" > "$OUT/03-upload.json" log "uploaded $(jq -r .title "$OUT/03-upload.json") ($(jq -r .status "$OUT/03-upload.json"))" fi # 4. Wait until Google has processed every source until get "notebooks/$(enc "$NOTEBOOK")" > "$OUT/04-notebook.json" && jq -e '[.sources[].status] | all(. == "ready" or . == "error")' "$OUT/04-notebook.json" > /dev/null; do log "sources: $(jq -r '[.sources[].status] | join(",")' "$OUT/04-notebook.json")" sleep 10 done log "sources ready: $(jq -r '[.sources[] | .kind] | join(", ")' "$OUT/04-notebook.json")" # 5. What one source is about: Google's summary and key topics WEB=$(jq -r '.sources[] | select(.kind == "web") | .source' "$OUT/04-notebook.json" | head -1) get "sources/$(enc "$WEB")" > "$OUT/05-source.json" jq -r '"guide: \(.summary[0:200])…\n topics: \(.topics | join(", "))"' "$OUT/05-source.json" # 6. Ask the notebook a question (answer + numbered citations) post chat "$(jq -n --arg nb "$NOTEBOOK" '{notebook: $nb, question: "What went wrong during the descent, and how did the crew handle it?"}')" > "$OUT/06-chat.json" jq -r '"\(.answer[0:400])…\n (\(.citations | length) citations, \(.ms) ms)"' "$OUT/06-chat.json" # 7. Keep the answer as a note post notes "$(jq -n --arg nb "$NOTEBOOK" --arg a "$(jq -r .answer "$OUT/06-chat.json")" '{notebook: $nb, title: "What went wrong during the descent", content: $a}')" > "$OUT/07-note.json" log "note $(jq -r .title "$OUT/07-note.json") ($(jq -r '.content | length' "$OUT/07-note.json") chars)" # 8. Find more sources on the web (Discover, sync) and import three of them post research "$(jq -n --arg nb "$NOTEBOOK" '{notebook: $nb, type: "fast", query: "Apollo 11 lunar module guidance computer alarms"}')" > "$OUT/08-discover.json" jq -r '"discover \(.status): \(.result.sources | length) sources: \(.result.summary)"' "$OUT/08-discover.json" post research/import "$(jq -n --arg j "$(jq -r .jobid "$OUT/08-discover.json")" --argjson urls "$(jq '[.result.sources[0:3][].url]' "$OUT/08-discover.json")" '{jobid: $j, urls: $urls}')" > "$OUT/08-discover-import.json" jq -r '.sources[] | " imported \(.kind) \(.status) \(.title)"' "$OUT/08-discover-import.json" # 9. Deep Research runs for minutes: start it async now, collect it at the end post research "$(jq -n --arg nb "$NOTEBOOK" '{notebook: $nb, type: "deep", query: "Why did the Apollo 11 landing nearly abort?", mode: "async"}')" > "$OUT/09-deep-submit.json" log "deep research $(jq -r .status "$OUT/09-deep-submit.json")" # 10. A quiz, sync: the answer is the finished job post artifacts "$(jq -n --arg nb "$NOTEBOOK" '{notebook: $nb, type: "quiz", quantity: "fewer", difficulty: "medium"}')" > "$OUT/10-quiz.json" jq -r '"quiz \(.status): \(.result.content.quiz | length) questions, first: \(.result.content.quiz[0].question)"' "$OUT/10-quiz.json" # 11. An Audio Overview and an infographic, async: submit both, then poll post artifacts "$(jq -n --arg nb "$NOTEBOOK" '{notebook: $nb, type: "audio", format: "brief", length: "short", mode: "async"}')" > "$OUT/11-audio-submit.json" post artifacts "$(jq -n --arg nb "$NOTEBOOK" '{notebook: $nb, type: "infographic", orientation: "portrait", style: "sketch_note", mode: "async"}')" > "$OUT/11-infographic-submit.json" for kind in audio infographic; do wait_job "$(jq -r .jobid "$OUT/11-$kind-submit.json")" "$OUT/12-$kind-job.json" log "$kind $(jq -r .status "$OUT/12-$kind-job.json"): $(jq -r '.result.title // .error.message' "$OUT/12-$kind-job.json")" # Files come through GET /artifacts/download, with your API token jq -r '.result.files[]? | "\(.format) \(.url)"' "$OUT/12-$kind-job.json" | while read -r fmt url; do curl -sS "${AUTH[@]}" -o "$OUT/$kind.$fmt" "$url" log " saved $OUT/$kind.$fmt ($(du -h "$OUT/$kind.$fmt" | cut -f1))" done done # 12. The Deep Research result, then its report imported as a source wait_job "$(jq -r .jobid "$OUT/09-deep-submit.json")" "$OUT/13-deep-job.json" jq -r '"deep research \(.status): \"\(.result.report.title)\" (\(.result.report.markdown | length) chars), \(.result.sources | length) sources, \([.result.sources[] | select(.cited)] | length) cited"' "$OUT/13-deep-job.json" post research/import "$(jq -n --arg j "$(jq -r .jobid "$OUT/13-deep-job.json")" '{jobid: $j, urls: [], report: true}')" > "$OUT/13-deep-import.json" jq -r '.sources[] | " imported \(.kind) \(.status) \(.title)"' "$OUT/13-deep-import.json" # 13. Share the notebook: anyone with the link can view it, without copying it post sharing "$(jq -n --arg nb "$NOTEBOOK" '{notebook: $nb, link: "public", allowCopies: false}')" > "$OUT/14-sharing.json" jq -r '"sharing: link \(.link), copies \(.allowCopies), people: \([.people[] | "\(.email) (\(.role))"] | join(", "))"' "$OUT/14-sharing.json" # 14. What that cost against Google's usage windows get "accounts/$(enc "$EMAIL")" > "$OUT/15-account.json" jq -r '"plan \(.googleTier): " + ([.quota.windows[] | "\(.window) used \(.usedPercent)%"] | join(", "))' "$OUT/15-account.json" log "all responses in $OUT" ``` ``` 21:55:39 notebook user:12345-user@example.com-notebook:62600bab-4082-4ee6-8fc3-955cee0c69cf web ready Apollo 11 - Wikipedia youtube ready A New Look at the Apollo 11 Landing Site text ready Why Apollo 11 almost did not land 21:55:54 uploaded 01-apollo11-wikipedia.pdf (preparing) 21:55:55 sources: preparing,ready,ready,ready 21:56:05 sources: preparing,ready,ready,ready 21:56:17 sources: preparing,ready,ready,ready 21:56:28 sources: processing,ready,ready,ready 21:56:38 sources ready: pdf, youtube, web, text guide: The provided source documents the historic **Apollo 11 mission**, which successfully achieved the first **crewed Moon landing** in July 1969. It outlines the intense background of the **Space Race** d… topics: Apollo spaceflight, Lunar landing, Space Race, Mission personnel, Space exploration During the lunar descent of Apollo 11's Lunar Module *Eagle*, a cascade of unexpected technical anomalies and environmental hazards threatened the landing, requiring rapid problem-solving from both the crew and Mission Control [1-6]. --- ### **1. Overshooting the Planned Landing Target** * **What went wrong:** As descent began, Neil Armstrong and Buzz Aldrin noticed they were passing lunar landm… (21 citations, 34877 ms) 21:57:20 note What went wrong during the descent (4237 chars) discover completed: 10 sources: Technical analyses, flight logs, and developer accounts explore the hardware constraints and software recovery behind Apollo 11's alarms. imported web ready TALES FROM THE LUNAR MODULE GUIDANCE COMPUTER - klabs.org imported pdf ready Exegesis of the 1201 and 1202 Alarms Which Occurred During the Mission G Lunar Landing - Ibiblio 21:59:09 deep research processing quiz completed: 6 questions, first: According to accounts from NASA leadership, what was a primary reason Neil Armstrong was chosen over Buzz Aldrin to be the first person to step onto the lunar surface? 22:04:44 audio completed: Fifty Seconds of Fuel and Lunar Isolation 22:04:46 saved gemini-notebook-demo/2026-09-29T04-55-37Z/audio.m4a (2.9M) 22:04:47 infographic completed: Apollo 11 Mission Infographic Overview 22:04:50 saved gemini-notebook-demo/2026-09-29T04-55-37Z/infographic.png (5.8M) deep research completed: "Anatomy of a Lunar Descent: Systems Architecture, Hardware Anomaly, and Human Decision-Making in the Apollo 11 Landing Near-Abort" (26878 chars), 30 sources, 24 cited imported markdown ready Anatomy of a Lunar Descent: Systems Architecture, Hardware Anomaly, and Human Decision-Making in the Apollo 11 Landing Near-Abort sharing: link public, copies false, people: user@example.com (owner) plan TIER_PRO: weekly used 7.49%, 5h used 19.46% 22:04:59 all responses in gemini-notebook-demo/2026-09-29T04-55-37Z ``` </details> <details markdown="block"> <summary>The second script (steps 15 to 19) and its output</summary> ```bash #!/usr/bin/env bash # USEAPI_TOKEN=user:12345-... EMAIL=user@example.com NOTEBOOK=<notebook id> CONVERSATION=<conversation id> NOTE=<note id> ./gemini-notebook-gallery.sh set -euo pipefail API="${API:-https://api.useapi.net/v1/gemini-notebook}" : "${USEAPI_TOKEN:?export USEAPI_TOKEN=user:12345-...}" : "${NOTEBOOK:?export NOTEBOOK=<notebook id>}" OUT="gemini-notebook-gallery/$(date -u +%Y-%m-%dT%H-%M-%SZ)" mkdir -p "$OUT" AUTH=(-H "Authorization: Bearer $USEAPI_TOKEN") enc() { jq -rn --arg v "$1" '$v|@uri'; } post() { curl -sS --max-time 310 "${AUTH[@]}" -H "Content-Type: application/json" -X POST "$API/$1" -d "$2"; } get() { curl -sS "${AUTH[@]}" "$API/$1"; } log() { echo "$(date +%H:%M:%S) $*"; } wait_job() { until get "jobs/$(enc "$1")" > "$2" && jq -e '.status == "completed" or .status == "failed"' "$2" > /dev/null; do sleep 15; done } # A sync job that outlives the 90 s wait answers 202: poll it to the end finish() { if jq -e '.status != "completed" and .status != "failed"' "$1" > /dev/null; then wait_job "$(jq -r .jobid "$1")" "$1"; fi } # 1. A follow-up question in the same conversation if [ -n "${CONVERSATION:-}" ]; then post chat "$(jq -n --arg nb "$NOTEBOOK" --arg c "$CONVERSATION" '{notebook: $nb, conversation: $c, question: "How much fuel was left when they landed?"}')" > "$OUT/01-followup.json" jq -r '"follow-up: \(.answer[0:300])…\n (\(.citations | length) citations)"' "$OUT/01-followup.json" fi # 2. The note from part 1 becomes a source if [ -n "${NOTE:-}" ]; then post notes/source "$(jq -n --arg n "$NOTE" '{note: $n}')" > "$OUT/02-note-source.json" jq -r '"note → source: \(.kind) \(.status) \(.title)"' "$OUT/02-note-source.json" fi # 3. Quick Studio types, sync post artifacts "$(jq -n --arg nb "$NOTEBOOK" '{notebook: $nb, type: "flashcards", quantity: "fewer", difficulty: "easy"}')" > "$OUT/03-flashcards.json" finish "$OUT/03-flashcards.json" jq -r '"flashcards \(.status): \(.result.title), content keys \(.result.content | keys | join(","))\n \(.result.content | tostring | .[0:240])…"' "$OUT/03-flashcards.json" post artifacts "$(jq -n --arg nb "$NOTEBOOK" '{notebook: $nb, type: "mindmap"}')" > "$OUT/04-mindmap.json" finish "$OUT/04-mindmap.json" jq -r '"mind map \(.status): \(.result.title) (\(.result.content | tostring | length) bytes of JSON)"' "$OUT/04-mindmap.json" post artifacts "$(jq -n --arg nb "$NOTEBOOK" '{notebook: $nb, type: "report", format: "briefing"}')" > "$OUT/05-report.json" finish "$OUT/05-report.json" jq -r '"report \(.status): \(.result.title) (\(.result.text | length) chars)"' "$OUT/05-report.json" post artifacts "$(jq -n --arg nb "$NOTEBOOK" '{notebook: $nb, type: "table", instructions: "One row per program alarm or anomaly during the descent: time, alarm or event, cause, what the crew or Mission Control did."}')" > "$OUT/06-table.json" finish "$OUT/06-table.json" jq -r '"table \(.status): \(.result.title) (\(.result.table | length) rows incl. header)"' "$OUT/06-table.json" # 4. A Video Overview and a slide deck, async post artifacts "$(jq -n --arg nb "$NOTEBOOK" '{notebook: $nb, type: "video", format: "explainer", style: "whiteboard", mode: "async"}')" > "$OUT/07-video-submit.json" post artifacts "$(jq -n --arg nb "$NOTEBOOK" '{notebook: $nb, type: "slides", format: "presenter", length: "short", mode: "async"}')" > "$OUT/07-slides-submit.json" for kind in slides video; do wait_job "$(jq -r .jobid "$OUT/07-$kind-submit.json")" "$OUT/08-$kind-job.json" log "$kind $(jq -r .status "$OUT/08-$kind-job.json"): $(jq -r '.result.title // .error.message' "$OUT/08-$kind-job.json")" jq -r '.result.files[]? | "\(.format) \(.url)"' "$OUT/08-$kind-job.json" | while read -r fmt url; do curl -sS "${AUTH[@]}" -o "$OUT/$kind.$fmt" "$url" log " saved $OUT/$kind.$fmt ($(du -h "$OUT/$kind.$fmt" | cut -f1))" done done jq -r '.result.slides[0:2][] | .image' "$OUT/08-slides-job.json" | nl -v1 | while read -r n url; do curl -sS "${AUTH[@]}" -o "$OUT/slide-$n.png" "$url" log " saved $OUT/slide-$n.png ($(du -h "$OUT/slide-$n.png" | cut -f1))" done # 5. Revise one slide with a prompt post artifacts/revise "$(jq -n --arg a "$(jq -r .artifact "$OUT/08-slides-job.json")" '{artifact: $a, slide: 2, prompt: "Make this slide a simple timeline graphic.", mode: "async"}')" > "$OUT/09-revise-submit.json" wait_job "$(jq -r .jobid "$OUT/09-revise-submit.json")" "$OUT/09-revise-job.json" log "revise $(jq -r .status "$OUT/09-revise-job.json"): $(jq -r '.result.slides | length' "$OUT/09-revise-job.json") slides" curl -sS "${AUTH[@]}" -o "$OUT/slide-2-revised.png" "$(jq -r '.result.slides[1].image' "$OUT/09-revise-job.json")" log " saved $OUT/slide-2-revised.png ($(du -h "$OUT/slide-2-revised.png" | cut -f1))" if [ -n "${EMAIL:-}" ]; then get "accounts/$(enc "$EMAIL")" > "$OUT/10-account.json"; jq -r '"plan \(.googleTier): " + ([.quota.windows[] | "\(.window) used \(.usedPercent)%"] | join(", "))' "$OUT/10-account.json"; fi log "all responses in $OUT" ``` ``` follow-up: When the Lunar Module *Eagle* touched down, it had **216 pounds (98 kg) of usable fuel remaining** [1, 2]. In terms of remaining flight time, the figures depend on whether you look at real-time calculations or post-flight analysis: * **Real-time estimates:** Telemetry available to Mission Control… (5 citations) note → source: markdown ready What went wrong during the descent flashcards completed: Apollo Flashcards, content keys flashcards,topics {"flashcards":[{"f":"Who served as the Commander of the Apollo 11 mission?","b":"Neil Armstrong"},{"f":"Who was the Command Module Pilot for the Apollo 11 mission?","b":"Michael Collins"},{"f":"Who served as the Lunar Module Pilot for Apoll… mind map completed: Apollo Mindmap (1899 bytes of JSON) report completed: Briefing Document: Mission Overview and Technical Synthesis of Apollo 11 (27282 chars) table completed: Apollo 11 Descent Alarms and Anomalies (13 rows incl. header) 22:59:03 slides completed: Apollo 11 Mission 22:59:04 saved gemini-notebook-gallery/2026-09-29T05-49-02Z/slides.pdf (8.8M) 22:59:05 saved gemini-notebook-gallery/2026-09-29T05-49-02Z/slides.pptx (9.5M) 23:07:59 video completed: Apollo 11: Untold Stories 23:08:02 saved gemini-notebook-gallery/2026-09-29T05-49-02Z/video.mp4 (59M) 23:08:04 saved gemini-notebook-gallery/2026-09-29T05-49-02Z/slide-1.png (1.6M) 23:08:06 saved gemini-notebook-gallery/2026-09-29T05-49-02Z/slide-2.png (1.2M) 23:09:11 revise completed: 8 slides 23:09:13 saved gemini-notebook-gallery/2026-09-29T05-49-02Z/slide-2-revised.png (888K) plan TIER_PRO: weekly used 8.69%, 5h used 25.19% 23:09:14 all responses in gemini-notebook-gallery/2026-09-29T05-49-02Z ``` </details> Related tutorials: [a real Gemini Notebook (NotebookLM) podcast example](/docs/articles/notebooklm-podcast-example), [Gemini Notebook podcasts with n8n](/docs/articles/notebooklm-n8n-podcast) and [Gemini Notebook API options in 2026](/docs/articles/notebooklm-api-options). ### Frequently asked questions **Is Gemini Notebook the same as NotebookLM?** Yes. Gemini Notebook is Google's current name for NotebookLM, and the [useapi.net Gemini Notebook API](/docs/api-gemini-notebook-v1) works as a NotebookLM API: notebooks, sources, chat, Deep Research and every Studio artifact over REST. **Can I generate a Gemini Notebook (NotebookLM) podcast through an API?** Yes. [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts) with `type: "audio"` generates an Audio Overview (`deep_dive`, `brief`, `critique` or `debate`) and returns an `m4a` file. The short brief in this walkthrough took about 4 and a half minutes. **How does the API reach my Gemini Notebook?** The [useapi.net Gemini Notebook API](/docs/api-gemini-notebook-v1) drives your own Google account over REST, with a single useapi.net API token. You connect the account once through [Setup Gemini Notebook](/docs/start-here/setup-gemini-notebook). **Does it work on a free Google account?** Yes. Every call on this page also runs on a free account, Deep Research included. Paid Google AI plans raise the usage budget and unlock Cinematic video: Google AI Pro gives an account about four times Free's budget, and Google AI Ultra about twenty times Pro's (see [What it cost](#what-it-cost)). **Which source types can I add?** Web pages and YouTube videos by URL, pasted text, files in the account's Google Drive (Google Docs included), and uploaded PDF, Word, PowerPoint, EPUB, Markdown, text, CSV, audio, video and image files. See [POST /sources](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources) and [POST /sources/upload](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources-upload). **Why did my YouTube video end with status error?** Google reads a YouTube video from its captions. A video with no captions at all, as with some official music videos, fails without a reason. Upload the audio or video file with [POST /sources/upload](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources-upload) instead, and Google transcribes it. **What is the difference between fast and deep research?** `fast` (Discover sources) returns about ten relevant web pages with one-line descriptions in seconds. `deep` (Deep Research) reads dozens of pages for a few minutes and writes a cited report. Its result lists the pages it found and marks the ones the report cites. Both only suggest: nothing enters the notebook until [POST /research/import](/docs/api-gemini-notebook-v1/post-gemini-notebook-research-import). **How long does a generation take?** Flashcards, a quiz and a data table take well under a minute, a mind map, a report or an infographic one to two minutes, an Audio Overview three to five minutes, a slide deck about five to seven, and Video Overviews ten minutes or more. See [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts#what-you-get-back) for each type. **Do I have to watch the jobs and usage limits myself?** No. Connect several Google accounts and the API spreads the work: each new job goes to an account that is healthy, has a free job slot and still has usage left for that type. Jobs are tracked on our side, so you poll [GET /jobs/`jobid`](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid) or pass `replyUrl` and get the finished job posted to your webhook. When every account is out of usage, the `429` carries `retryAt` whenever Google names the reset time, so your code decides how to handle the load: wait until then, route the next batch to another account, or slow down. No one has to check in. **What happens when an account runs out of its usage window?** Google refuses the generation. The call answers `429`, or the job fails with `error.code: "quota"` when it started async, with the reset time when Google names it. Connect more accounts: one-shot requests skip accounts whose last-known usage blocks the job, and new notebooks go to the least busy account. ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. ### Conclusion Visit our <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> or <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> for any support questions and concerns. Check our [GitHub repo](https://github.com/useapi/notebooklm-api) with code examples. The same calls are available as tools on the hosted [Gemini Notebook MCP server (NotebookLM MCP server)](/docs/api-gemini-notebook-v1/mcp) for Claude Code, Cursor and VS Code. #### Cross posted Also published on [dev.to](https://dev.to/useapi/how-to-automate-notebooklm-with-the-gemini-notebook-api-deep-research-chat-audio-overviews-and-a-5cmj){:rel="nofollow"}, discussed on [Reddit](https://www.reddit.com/r/ThirdPartyAPI/comments/1wtr2vy/how_to_automate_notebooklm_with_the_gemini/){:rel="nofollow"}, and shared on [Bluesky](https://bsky.app/profile/useapi.net/post/3mwpg7wveyp25){:rel="nofollow"}. === URL: https://useapi.net/docs/articles/gemini-omni-1-2-flash-api-es === Document URL: https://useapi.net/docs/articles/gemini-omni-1-2-flash-api-es --- layout: default title: "Cómo usar la API de Gemini Omni 1.2 Flash: videos de 15 segundos en Google Flow y Google Vids" seo_title: "API de Gemini Omni 1.2 Flash: videos de 15 s y precio" description: "API de Gemini Omni 1.2 Flash con useapi.net: videos de 3 a 15 segundos con voces en Google Flow y Vids, US$0,30 por 15 s en Ultra US$199,99 frente a US$1,04 en la Gemini API." image: https://media.useapi.net/articles/2026-11-06-gemini-omni-1-2-flash-api-id/261106-gemini-omni-1-2-flash-api-cover.jpg keywords: [Gemini Omni 1.2 Flash API, API de Gemini Omni 1.2 Flash, Omni 1.2 Flash API, gemini omni 1.2 api, omni-flash-1.2, Omni Flash 15 segundos, Gemini Omni API, Gemini Omni Flash API, precio de Omni 1.2 Flash, Omni 1.2 Flash gratis, alternativa a Veo, alternativa a Veo 3.1, Google Flow API, Google Vids API, extender video, API de edición de video, video con IA con voces, Google AI Ultra, sin clave de la Gemini API, tutorial, curl, tutorial de Omni 1.2 Flash] parent: Articles nav_exclude: true lang: es date: 2026-11-06 last_modified: 2026-11-11 nav_order: 908 repo: https://github.com/useapi/google-flow-api translation_key: gemini-omni-1-2-flash --- ## Cómo usar la API de Gemini Omni 1.2 Flash: videos de 15 segundos en Google Flow y Google Vids {: .no_toc #how-to-use-the-gemini-omni-12-flash-api-15-second-videos-in-google-flow-and-google-vids } 7 min de lectura • 6 de noviembre de 2026 (11 de noviembre de 2026) useapi.net es una API de terceros. No está afiliada a Google ni cuenta con su respaldo. ## Índice {: .no_toc .text-delta #table-of-contents } ### Introducción Gemini Omni 1.2 Flash, que Google lanzó el 5 de noviembre de 2026, genera videos de 3 a 15 segundos con sonido y voz, y useapi.net lo ejecuta con tu [suscripción de Google AI](https://gemini.google/subscriptions/) mediante dos API REST: la [Google Flow API](/docs/api-google-flow-v1) y la [Google Vids API](/docs/api-google-vids-v1). En Google AI Ultra US$199,99, un video de 15 segundos usa US$0,30 de la cuota mensual de Vids del plan o US$0,48 de sus créditos de Flow, frente a US$1,04 por 15 segundos en 720p en la [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) del propio Google (a noviembre de 2026). No necesitas clave de la Gemini API ni proyecto de Google Cloud. Lo nuevo en la 1.2, según el [anuncio](https://cloud.google.com/blog/products/ai-machine-learning/gemini-omni-1-2-flash-generally-available) de Google: clips de hasta 15 segundos en lugar de 10, más fidelidad a las referencias y una sincronización de labios más clara. Ese mismo día, Google [pasó Google Vids a este modelo](https://workspaceupdates.googleblog.com/2026/11/gemini-omni-12-flash-now-in-vids-with-15second-generations-and-improved-quality.html). Esta guía compara las dos vías y luego recorre una escena real en cada una: una escena de 30 segundos en Google Flow hecha en tres llamadas, con dos voces, y una escena de 15 segundos en Google Vids con una extensión y una edición de 15 segundos. Cada solicitud es la real y cada video es el resultado real, tomados de las publicaciones de lanzamiento [Google Flow: Omni 1.2 Flash](/blog/261106) y [Google Vids: Omni 1.2 Flash](/blog/261106v) (en inglés). Antes de empezar, necesitas: - un [token de API](/docs/start-here/setup-useapi) de useapi.net - una cuenta de Google conectada con [Setup Google Flow](/docs/start-here/setup-google-flow), [Setup Google Vids](/docs/start-here/setup-google-vids) o ambas. Una misma cuenta de Google se puede conectar a las dos API, y cada una conserva su propia cuota. ### Google Flow o Google Vids: Omni 1.2 Flash de un vistazo | | [Google Flow API](/docs/api-google-flow-v1) | [Google Vids API](/docs/api-google-vids-v1) | |---|---|---| | Cómo elegir Omni 1.2 | `model: "omni-flash-1.2"` (Omni 1.1 Flash y Veo 3.1 son otros valores) | Sin campo `model`: Vids tiene un solo modelo de video, Omni 1.2 desde el despliegue de Google a partir del 5 de noviembre | | Duración | De 3 a 15 segundos (de 3 a 10 con fotograma inicial y final) | De 3 a 15 segundos | | Resolución | 360p o 720p, [upscale](/docs/api-google-flow-v1/post-google-flow-videos-upscale) a 1080p, o 4K en Ultra | 720p o 1080p al mismo precio, [upscale](/docs/api-google-vids-v1/post-google-vids-videos-upscale) a 1080p en clips de hasta 20 segundos | | Entradas | Texto, un fotograma inicial, fotograma inicial y final, hasta 10 imágenes de referencia, [personajes](/docs/api-google-flow-v1/get-google-flow-characters) guardados, de 1 a 4 videos por solicitud | Texto, una imagen inicial o hasta 3 referencias que combinan imágenes y [avatares](/docs/api-google-vids-v1/post-google-vids-avatars) | | Voces | Hasta 5 [voces](/docs/api-google-flow-v1/get-google-flow-voices) por video cuando tiene una imagen de referencia o un personaje, hasta 3 por extensión. 30 voces integradas o la tuya | Cada avatar habla con una de 30 [voces](/docs/api-google-vids-v1/get-google-vids-voices), hasta 3 avatares por video | | [Extender](/docs/api-google-flow-v1/post-google-flow-videos-extend) | De 3 a 10 segundos por llamada, con sus propias voces y referencias, hasta poco menos de 40 segundos, planes de pago | [De 3 a 10 segundos por llamada](/docs/api-google-vids-v1/post-google-vids-videos-extend) en clips de hasta 24 segundos, hasta unos 34 segundos | | Editar con un prompt | [Hasta 15 segundos](/docs/api-google-flow-v1/post-google-flow-videos#video-reference-omni-11-flash-v2v-edit) de un clip generado o subido | [Hasta 15 segundos](/docs/api-google-vids-v1/post-google-vids-videos-edit) de un clip hecho por Google | | Qué consume | Créditos de Flow: en 720p, 3 por segundo hasta 10 segundos y 6 por segundo después, en 360p, 1 y 2 | Segundos de la cuota mensual de Vids, aparte de los créditos de Flow | | Cuenta de Google gratuita | Videos de hasta 10 segundos con 50 créditos de Flow al día | Ningún segundo de video de Vids en nuestras pruebas | | Captcha | Google pide un captcha en cada video de Flow. La API lo resuelve por ti: 300 gratis, y después mediante un [proveedor de captcha](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers) en el que te registras, a unos US$0,80 a US$3,00 por cada 1.000 | Ninguno | ### Precio por video Lo que cuesta un video de 15 segundos de Omni 1.2 Flash en la [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) del propio Google y en cada suscripción de Google AI (en dólares estadounidenses, a noviembre de 2026). Cada suscripción incluye un número mensual de créditos de Flow y, aparte, de segundos de video de Vids, así que un video cuesta su parte de la suscripción. | Omni 1.2 Flash, 15 s | [API oficial](https://ai.google.dev/gemini-api/docs/pricing) | Ultra $199,99 (25.000 cr, 10.000 s) | Ultra $99,99 (10.000 cr, 2.500 s) | Pro $19,99 (1.000 cr, 500 s) | Plus $4,99 (200 cr, 60 s) | |---|---|---|---|---|---| | Google Flow (720p) | $1,04 (unos $0,07/s) | $0,48 / 60 cr (416 videos/mes) | $0,60 / 60 cr (166 videos/mes) | $1,20 / 60 cr (16 videos/mes) | $1,50 / 60 cr (3 videos/mes) | | Google Flow (360p) | $0,35 ($0,023/s) | $0,16 / 20 cr (1.250 videos/mes) | $0,20 / 20 cr (500 videos/mes) | $0,40 / 20 cr (50 videos/mes) | $0,50 / 20 cr (10 videos/mes) | | Google Vids (720p o 1080p) | $1,04 en 720p ($1,56 en 1080p) | $0,30 / 15 s (666 videos/mes) | $0,60 / 15 s (166 videos/mes) | $0,60 / 15 s (33 videos/mes) | $1,25 / 15 s (4 videos/mes) | - El ahorro crece con el plan. En Plus, y en Pro dentro de Flow, un video de 15 segundos en 720p cuesta más que en la Gemini API, mientras que en Ultra US$199,99 cuesta menos de la mitad en Flow y menos de un tercio en Vids. - Flow cobra el doble por cada segundo a partir del 10, así que ahí los videos más cortos cuestan menos por segundo: un video de 10 segundos en 720p son 30 créditos, US$0,24 en Ultra US$199,99, frente a US$0,70 en la Gemini API. La tabla completa de Flow, con todos los modelos, está en la [descripción general de la Google Flow API](/docs/api-google-flow-v1#pricing), y la de Vids, con imágenes y avatares, en la [descripción general de la Google Vids API](/docs/api-google-vids-v1#pricing). - Una extensión consume solo los segundos que agrega, en las dos API. Una edición en Vids consume como máximo los segundos que edita (en nuestras pruebas, una edición de 15 segundos consumió 10), y una edición en Flow cuesta lo mismo que un video de la duración editada. - Los créditos de Flow y los segundos de Vids son dos cuotas separadas del mismo plan. En Ultra US$199,99, una cuenta de Google conectada a las dos API hace al mes unos 416 videos de quince segundos en 720p en Flow y 666 en Vids, unos 1.082 en total. - Los precios de los planes son los de Google en EE. UU. Los segundos de Vids por plan vienen de la página [Gemini en Google Vids](https://support.google.com/docs/answer/15609411?hl=es) de Google y coinciden con nuestras pruebas en Ultra US$199,99. ### Omni 1.2 Flash en Google Flow: una escena de 30 segundos en tres llamadas Un video de 10 segundos y después dos extensiones de 10 segundos, cada una con su propia voz. El paso 1 funciona con una cuenta de Google gratuita. Los pasos 2 y 3 (extender) necesitan un plan de pago de Google AI. Cada llamada se ejecuta como un job asíncrono: pasa `async: true` y el POST responde al instante con un `jobid`. Consulta [GET /jobs/`jobid`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid) hasta que `status` sea `completed`, o pasa `replyUrl` para recibir el job terminado en tu webhook: ```bash curl --location 'https://api.useapi.net/v1/google-flow/jobs/<jobid>' --header 'Authorization: Bearer YOUR_API_TOKEN' ``` El video terminado está en `response.media[0].videoUrl`, un enlace válido durante unas 6 horas, y el paso siguiente usa el `response.media[0].mediaGenerationId` del job terminado. Si conectaste varias cuentas de Google, la API elige una que ya tenga Omni 1.2 (Google lo está activando durante varios días a partir del 5 de noviembre). Pasa `email` para elegir una. #### Paso 1: los primeros 10 segundos {: .no_toc #step-1-the-first-10-seconds } [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) con `model: "omni-flash-1.2"` y `duration: 10`. Google respondió en 56 segundos. En 720p, un video de 10 segundos son 30 créditos. ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "model": "omni-flash-1.2", "duration": 10, "prompt": "Cinematic night, a narrow rainy alley in Tokyo glowing with neon signs reflected in the puddles. A street magician in a long dark coat faces the camera, fans out a deck of cards that glow faintly gold, and says with a grin: \"Pick a card. Any card.\" A sudden gust snatches one glowing card from his hand and it flutters away down the alley. Handheld camera, shallow depth of field, rain drops catching the light.", "async": true }' ``` <video poster="https://media.useapi.net/blog/2026-11-06-261106/261106-google-flow-omni-1-2-magician-first-10s-poster.jpg" src="https://media.useapi.net/blog/2026-11-06-261106/261106-google-flow-omni-1-2-magician-first-10s.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> <details markdown="block"> <summary>El job terminado, de <a href="/docs/api-google-flow-v1/get-google-flow-jobs-jobid">GET /jobs/<code>jobid</code></a> (resumido)</summary> ```json { "jobid": "j1106021223539251070v-u12345-email:user@example.com-bot:google-flow", "type": "video", "status": "completed", "response": { "media": [ { "video": { "generatedVideo": { "model": "macaron_cookie_t2v_10s", "aspectRatio": "VIDEO_ASPECT_RATIO_LANDSCAPE" }, "dimensions": { "length": "10s" } }, "mediaGenerationId": "user:12345-email:…-video:b08556b9-…", "videoUrl": "https://flow-content.google/video/b08556b9-…?Expires=…" } ], "remainingCredits": 877 } } ``` </details> #### Paso 2: extender 10 segundos, con una voz {: .no_toc #step-2-extend-by-10-seconds-with-a-voice } [POST /videos/extend](/docs/api-google-flow-v1/post-google-flow-videos-extend) con el `mediaGenerationId` del primer video, `duration: 10` y la voz integrada Charon como `referenceAudio_1`. El prompt ubica la voz donde habla el mago, con la mención en línea `@referenceAudio_1`. Extend usa Omni 1.2 por defecto, así que no hace falta `model`. La respuesta es un solo clip de 20 segundos, los primeros 10 segundos sin cambios más los 10 nuevos, tras 2 minutos y 20 segundos, por 30 créditos. ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos/extend' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "mediaGenerationId": "user:12345-email:…-video:b08556b9-…", "duration": 10, "referenceAudio_1": "Charon", "prompt": "The magician runs after the glowing card through the rain, past a ramen stall and under paper lanterns, laughing and calling out in a deep voice @referenceAudio_1: \"Come back here! You are the ace of hearts!\" The camera follows him close behind.", "async": true }' ``` #### Paso 3: 10 segundos más, una segunda voz {: .no_toc #step-3-10-more-seconds-a-second-voice } La misma llamada sobre el clip de 20 segundos, con la voz Aoede para la mujer del café. El resultado es la escena completa, de 30 segundos, tras otros 2 minutos y 30 créditos. ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos/extend' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "mediaGenerationId": "user:12345-email:…-video:113384cd-…", "duration": 10, "referenceAudio_1": "Aoede", "prompt": "The glowing card drifts through the open door of a tiny warm café and lands on a table. A young woman in a yellow raincoat picks it up, looks at the out-of-breath magician in the doorway, and says with a smile @referenceAudio_1: \"Is this your card?\" He laughs. Warm light, rain outside the window.", "async": true }' ``` <video poster="https://media.useapi.net/articles/2026-06-15-omni-flash-bash/261106-google-flow-omni-1-2-magician-extended-30s-web-poster.jpg" src="https://media.useapi.net/articles/2026-06-15-omni-flash-bash/261106-google-flow-omni-1-2-magician-extended-30s-web.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> <details markdown="block"> <summary>El job terminado (resumido)</summary> ```json { "jobid": "j1106021547955542178v-u12345-email:user@example.com-bot:google-flow", "type": "video", "status": "completed", "response": { "media": [ { "video": { "generatedVideo": { "model": "macaron_cookie_extend_10s" }, "dimensions": { "length": "30s" } }, "mediaGenerationId": "user:12345-email:…-video:db0201df-…", "videoUrl": "https://flow-content.google/video/db0201df-…?Expires=…" } ], "remainingCredits": 817 } } ``` </details> El video de arriba está recodificado para la web en su resolución original de 1280×720. La escena completa usó 90 créditos, unos US$0,72 en Ultra US$199,99, frente a unos US$2,10 por 30 segundos con la tarifa de 720p de la Gemini API (a noviembre de 2026). Google solo extiende videos de menos de 30 segundos, así que esta escena ya no puede crecer más: una cuarta extensión responde `400` al instante, antes de cualquier captcha o crédito. Un clip de 25 segundos todavía admite 10 más y termina en 35. [`omni-extend/`](https://github.com/useapi/google-flow-api/tree/main/omni-extend) en GitHub genera esta escena a partir de un `story.json`, en Node.js o Python, y [`omni-flash/`](https://github.com/useapi/google-flow-api/tree/main/omni-flash) genera por lotes videos de Omni Flash a partir de una lista de prompts. El [tutorial de Omni Flash](/docs/articles/omni-flash-bash-es) cubre imágenes de referencia, personajes, fotogramas inicial y final y ediciones. ### Omni 1.2 Flash en Google Vids: 15 segundos, una extensión y una edición Vids tiene un solo modelo de video, que Google pasó a Omni 1.2 en un despliegue de unos días a partir del 5 de noviembre, así que no hay `model` que definir. Las solicitudes llevan un cuerpo JSON, y cada llamada de esta sección se ejecuta como un job asíncrono: consulta [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid) o pasa `replyUrl`, y luego descarga el clip con [GET /media/`mediaId`](/docs/api-google-vids-v1/get-google-vids-media-mediaId) dentro de las 24 horas. El paso siguiente usa el `result.mediaId` del job terminado. Vids no pide captcha. ```bash curl --location 'https://api.useapi.net/v1/google-vids/jobs/<jobid>' --header 'Authorization: Bearer YOUR_API_TOKEN' ``` #### Paso 1: un video de 15 segundos a partir de un prompt {: .no_toc #step-1-a-15-second-video-from-one-prompt } [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) con `duration: 15`. Google respondió en unos 60 segundos con un video de 1280×720, y las dos frases se dicen tal como están escritas. Consumió 15 segundos de la cuota. ```bash curl --location 'https://api.useapi.net/v1/google-vids/videos' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "prompt": "Cinematic single continuous shot, 15 seconds, 16:9. Golden hour on a Tokyo rooftop garden, city skyline glowing behind. A young chef in a crisp white apron finishes plating a steaming bowl of ramen, steam curling in the warm light. She looks up into the camera and says with a confident smile: \"Fifteen seconds. One prompt. No editing.\" She slides the bowl toward the camera as it slowly pushes in, wind chimes ringing softly and city traffic humming far below. She laughs and adds: \"Now that'\''s fast food.\"", "duration": 15, "aspectRatio": "landscape", "resolution": "720p", "async": true }' ``` <video poster="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-15s-poster.jpg" src="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-15s.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> <details markdown="block"> <summary>El job terminado, de <a href="/docs/api-google-vids-v1/get-google-vids-jobs-jobid">GET /jobs/<code>jobid</code></a> (resumido)</summary> ```json { "status": "completed", "result": { "mediaId": "user:12345-user@example.com-video:eyJ1Ijoi…", "width": 1280, "height": 720, "duration": 15, "resolution": "720p", "aspectRatio": "landscape", "model": "/flix/generate_videos_omni_t2v_psq/v1", "quota": { "video": { "limit": 500, "left": 485, "resetAt": "2026-12-01T08:00:00.000Z" } } } } ``` </details> `quota` muestra lo que le queda a la cuenta de sus segundos de video del mes y cuándo se reinician. Esta cuenta de prueba tiene Google AI Pro, de ahí el límite de 500 segundos. Los precios de esta página usan Ultra US$199,99. #### Paso 2: extenderlo 10 segundos {: .no_toc #step-2-extend-it-by-10-seconds } [POST /videos/extend](/docs/api-google-vids-v1/post-google-vids-videos-extend) con el `mediaId` del primer video. El resultado es un solo clip, los 15 segundos más 10 nuevos, de 25 segundos, tras unos 100 segundos. Entra un amigo, prueba el ramen, y se dicen las dos frases nuevas. ```bash curl --location 'https://api.useapi.net/v1/google-vids/videos/extend' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "mediaId": "user:12345-user@example.com-video:eyJ1Ijoi…", "prompt": "Same shot continues on the Tokyo rooftop at dusk, the city lights now switching on. A friend in a denim jacket walks into frame, sits at the table and takes a first slurp of the ramen, eyes widening. He says: \"Wait, you made this in fifteen seconds?\" The chef folds her arms and grins: \"Fifteen more, and I'\''ll make dessert.\" They both laugh as string lights flicker on above them and soft city ambience fills the air.", "duration": 10, "async": true }' ``` <video poster="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-extend-25s-poster.jpg" src="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-extend-25s.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> También en YouTube: [Gemini Omni 1.2 Flash in Google Vids: 15 seconds from one prompt, extended to 25](https://www.youtube.com/watch?v=eJ3js18XCBM). La API acepta de 3 a 10 segundos por llamada de extensión y responde `400` a una `duration` mayor: Google agrega como máximo 10 segundos pero cuenta todos los segundos solicitados. (Este clip salió de una prueba anterior con `duration: 15`.) La misma solicitud con `duration: 10` devuelve el mismo clip de 25 segundos y consume 10 segundos. Vids extiende clips de hasta 24 segundos, así que este clip de 25 segundos ya no puede crecer. Para llegar al clip más largo, de unos 34 segundos, extiende 10 segundos un clip de 24 segundos o menos. #### Paso 3: editar los 15 segundos completos {: .no_toc #step-3-edit-all-15-seconds } [POST /videos/edit](/docs/api-google-vids-v1/post-google-vids-videos-edit) sobre el primer video con `duration: 15`. Con Omni 1.1, una edición devolvía como máximo 10 segundos. Ahora volvió editado el clip completo de 15 segundos, cada fotograma, tras unos 140 segundos. ```bash curl --location 'https://api.useapi.net/v1/google-vids/videos/edit' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "video": "user:12345-user@example.com-video:eyJ1Ijoi…", "prompt": "Make it a snowy winter evening: snow falling gently over the rooftop and the city, the chef wearing a red knit scarf. Keep everything else the same.", "duration": 15, "async": true }' ``` <video poster="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-edit-snow-15s-poster.jpg" src="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-edit-snow-15s.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> Vids edita clips hechos por Google, y Google rechaza los videos subidos con `422`. Para un clip suelto, genera en 1080p, que consume la misma cuota que 720p. Para un clip que vas a extender, trabaja en 720p y pasa a 1080p una sola vez, al final: cada extensión en 1080p vuelve a procesar el clip completo y sobreenfoca los segundos anteriores ([ver la comparación](/blog/261106v#720p-or-1080p-what-a-1080p-extend-does), en inglés). Termina un clip de hasta 20 segundos con un [upscale](/docs/api-google-vids-v1/post-google-vids-videos-upscale) (vuelve a consumir los segundos del clip), y para un clip de 21 a 34 segundos define `resolution: "1080p"` solo en la última extensión. El repositorio [google-vids-api](https://github.com/useapi/google-vids-api) en GitHub tiene ejemplos de Vids listos para ejecutar en Node.js y Python, incluidos avatares con voz, y el [tutorial de influencer con IA](/docs/articles/google-vids-influencer-avatars-es) arma un clip con dos avatares que hablan. ### Cuál usar Elige la Google Flow API cuando quieras: - borradores en 360p a un tercio del precio de 720p, o hasta 4 videos por solicitud - un fotograma inicial y uno final, hasta 10 imágenes de referencia o personajes guardados - elegir tú las voces: hasta 5 por video con imagen de referencia o personaje y hasta 3 por extensión, entre 30 voces integradas o la tuya - editar un video subido, o hacer upscale a 4K en Ultra - videos de Veo 3.1 e imágenes de Nano Banana desde la misma API - Omni 1.2 con una cuenta de Google gratuita, hasta 10 segundos Elige la Google Vids API cuando quieras: - ningún captcha y ningún proveedor de captcha - 1080p al mismo precio que 720p (para clips que vas a extender o editar, consulta [en qué resolución trabajar](#vids-resolution)) - avatares con voz que conservan su aspecto y su voz de un video a otro, hasta 3 en un video - el precio por segundo más bajo en Ultra US$199,99, US$0,02 frente a US$0,032 para un video de 15 segundos en Flow - más videos de Omni 1.2 cuando se acaban tus créditos de Flow, ya que Vids tiene su propia cuota O usa las dos: conecta la misma cuenta de Google a cada API y envía los jobs donde mejor encajen, ya que las dos [cuotas se suman](#price-per-video). ### Úsalo desde Claude Code, Cursor o Gemini CLI Las dos API tienen un servidor MCP alojado que funciona con tu token de API de useapi.net, sin nada que instalar. En Claude Code, cada uno es una línea: ```bash claude mcp add --transport http useapi-google-vids https://api.useapi.net/v1/google-vids/mcp --header "Authorization: Bearer YOUR_API_TOKEN" claude mcp add --transport http useapi-google-flow https://api.useapi.net/v1/google-flow/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` En Cursor o Gemini CLI, agrega la misma URL con el mismo encabezado `Authorization` en su configuración de MCP. - El [servidor MCP de Google Vids](/docs/api-google-vids-v1/mcp) genera clips de Omni 1.2 directamente: `vids_create_video` y `vids_edit_video` aceptan hasta 15 segundos, y `vids_extend_video` hasta 10 por llamada en clips de hasta 24 segundos. - El [servidor MCP de Google Flow](/docs/api-google-flow-v1/mcp) habla con Google Flow Agent, no directamente con los endpoints de Omni 1.2: tu asistente conversa con el Agent, que genera imágenes y videos al precio habitual de Flow. Para llamadas directas a Omni 1.2 desde Claude Code o Codex, agrega la [agent skill omni-flash-video](https://github.com/useapi/google-flow-api/tree/main/skills/omni-flash-video). - Los dos repositorios también instalan el servidor como plugin de Claude Code o extensión de Gemini CLI: [google-flow-api](https://github.com/useapi/google-flow-api#use-with-claude-code) y [google-vids-api](https://github.com/useapi/google-vids-api#use-with-claude-code). ### Preguntas #### ¿Existe una API de Gemini Omni 1.2 Flash? Con useapi.net, sí: ejecuta Gemini Omni 1.2 Flash con tu suscripción de Google AI, mediante la [Google Flow API](/docs/api-google-flow-v1) (`model: "omni-flash-1.2"`) y la [Google Vids API](/docs/api-google-vids-v1), sin clave de la Gemini API. Cuesta desde US$0,02 por segundo de la cuota de Vids de Ultra US$199,99, frente a unos US$0,07 por segundo en la [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) de Google, y Flow acepta hasta 5 voces por video con una imagen de referencia o un personaje, mientras que la API de Google [restringe las referencias de audio a una lista de acceso](https://cloud.google.com/blog/products/ai-machine-learning/gemini-omni-1-2-flash-generally-available) (a noviembre de 2026). #### ¿Cuánto cuesta un video de Omni 1.2 Flash? Con useapi.net en Google AI Ultra US$199,99, un video de 15 segundos de Omni 1.2 Flash usa US$0,30 de la cuota de Vids del plan o US$0,48 de sus créditos de Flow, frente a US$1,04 en 720p en la Gemini API de Google (a noviembre de 2026). En Vids, un video de 15 segundos en 1080p también cuesta US$0,30, porque 1080p consume los mismos segundos, mientras que la Gemini API cobra US$1,56. La [tabla de precios](#price-per-video) muestra todos los planes. #### ¿Hay una API gratuita de Gemini Omni 1.2 Flash? Con useapi.net, sí, en la Google Flow API: una cuenta de Google gratuita genera videos de Omni 1.2 Flash de hasta 10 segundos con sus [50 créditos diarios de Flow](https://support.google.com/flow/answer/16526234?hl=es), un video de 10 segundos en 720p o cinco en 360p al día, mientras que la Gemini API de Google ofrece Omni 1.2 Flash solo en su nivel de pago (a noviembre de 2026). Los videos más largos y las extensiones con Omni 1.2 necesitan un plan de pago de Google AI. #### ¿Cuánto puede durar un video de Omni 1.2 Flash? Con useapi.net, una llamada genera de 3 a 15 segundos tanto en Google Flow como en Google Vids, y extend agrega de 3 a 10 segundos por llamada y devuelve el clip completo: hasta poco menos de 40 segundos en Flow, con una voz nueva en cada extensión si quieres, y unos 34 segundos en Vids, que extiende clips de hasta 24 segundos. La [escena de 30 segundos](#flow-walkthrough) de arriba se hizo así, en tres llamadas. #### Omni 1.2 Flash o Veo 3.1: ¿cuál conviene usar? Con useapi.net ejecutas los dos en la misma Google Flow API con un solo plan: en Ultra US$199,99, un video de Omni 1.2 Flash de 8 segundos en 720p cuesta US$0,19 y uno de Veo 3.1 Fast US$0,08, frente a US$0,56 y US$0,80 en las API del propio Google (a noviembre de 2026). Elige Omni 1.2 Flash para clips de más de 8 segundos, hasta 5 voces que eliges tú y extensiones con voces nuevas, y Veo 3.1 Fast para el clip de 8 segundos más barato. Todos los precios de Veo: [Veo 3.1 API pricing](/docs/articles/veo-3-1-api-pricing) (en inglés). ### Fuentes - Google Cloud, [Gemini Omni 1.2 Flash is generally available](https://cloud.google.com/blog/products/ai-machine-learning/gemini-omni-1-2-flash-generally-available), 5 de noviembre de 2026 - Google Workspace Updates, [Gemini Omni 1.2 Flash now in Vids](https://workspaceupdates.googleblog.com/2026/11/gemini-omni-12-flash-now-in-vids-with-15second-generations-and-improved-quality.html), 5 de noviembre de 2026 - Google, [precios de la Gemini API](https://ai.google.dev/gemini-api/docs/pricing), consultados el 6 de noviembre de 2026 - Google Cloud, [precios de Agent Platform](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing) (Veo 3.1), consultados el 6 de noviembre de 2026 - Google, [planes de Google AI](https://gemini.google/subscriptions/), [créditos de Flow](https://support.google.com/flow/answer/16526234?hl=es) y [Gemini en Google Vids](https://support.google.com/docs/answer/15609411?hl=es), consultados en noviembre de 2026 - Publicaciones de lanzamiento de useapi.net: [Google Flow: Omni 1.2 Flash, 15-Second Videos, and Extend with Voices](/blog/261106) y [Google Vids: Omni 1.2 Flash, 15-Second Videos and 15-Second Edits](/blog/261106v), 6 de noviembre de 2026 ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/gemini-omni-1-2-flash-api-id === Document URL: https://useapi.net/docs/articles/gemini-omni-1-2-flash-api-id --- layout: default title: "Cara Memakai Gemini Omni 1.2 Flash API: Video 15 Detik di Google Flow dan Google Vids" seo_title: "Gemini Omni 1.2 Flash API: Video 15 Detik dan Harganya" description: "Gemini Omni 1.2 Flash API lewat useapi.net: video 3 sampai 15 detik bersuara di Google Flow dan Vids, US$0,30 per 15 detik di Ultra $199,99, dibanding US$1,04 di Gemini API." image: https://media.useapi.net/articles/2026-11-06-gemini-omni-1-2-flash-api-id/261106-gemini-omni-1-2-flash-api-cover.jpg keywords: [Gemini Omni 1.2 Flash API, Omni 1.2 Flash API, API Omni 1.2 Flash, gemini omni 1.2 api, omni-flash-1.2, Omni Flash 15 detik, Omni Flash 15 seconds, Gemini Omni API, Gemini Omni Flash API, harga Omni 1.2 Flash, Omni 1.2 Flash price, alternatif Veo, Veo alternative, alternatif Veo 3.1, Google Flow API, Google Vids API, perpanjang video, extend video, API edit video, video AI dengan suara, Google AI Ultra, tanpa Gemini API key, tutorial bahasa Indonesia, curl] parent: Articles nav_exclude: true lang: id translation_key: gemini-omni-1-2-flash date: 2026-11-06 last_modified: 2026-11-11 nav_order: 908 repo: https://github.com/useapi/google-flow-api --- ## Cara Memakai Gemini Omni 1.2 Flash API: Video 15 Detik di Google Flow dan Google Vids {: .no_toc #how-to-use-the-gemini-omni-12-flash-api-15-second-videos-in-google-flow-and-google-vids } 7 menit baca • 6 November 2026 useapi.net adalah API pihak ketiga. Kami tidak berafiliasi dengan Google dan tidak disahkan oleh Google. ## Daftar isi {: .no_toc .text-delta #table-of-contents } ### Pendahuluan Gemini Omni 1.2 Flash, yang dirilis Google pada 5 November 2026, membuat video 3 sampai 15 detik dengan suara dan dialog. useapi.net menjalankannya di [langganan Google AI](https://gemini.google/subscriptions/) Anda lewat dua REST API: [Google Flow API](/docs/api-google-flow-v1) dan [Google Vids API](/docs/api-google-vids-v1). Di Google AI Ultra $199,99, satu video 15 detik memakai $0,30 dari kuota Vids bulanan paket itu atau $0,48 dari kredit Flow-nya, dibanding $1,04 untuk 15 detik 720p di [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) milik Google sendiri (per November 2026). Anda tidak butuh Gemini API key maupun project Google Cloud. Yang baru di versi 1.2, menurut [pengumuman](https://cloud.google.com/blog/products/ai-machine-learning/gemini-omni-1-2-flash-generally-available) Google: klip hingga 15 detik, bukan lagi 10, kepatuhan yang lebih baik pada referensi, dan lip-sync yang lebih jelas. Di hari yang sama Google juga [memindahkan Google Vids ke model ini](https://workspaceupdates.googleblog.com/2026/11/gemini-omni-12-flash-now-in-vids-with-15second-generations-and-improved-quality.html). Panduan ini membandingkan kedua jalur, lalu menjalankan satu adegan nyata di masing-masing: adegan 30 detik di Google Flow yang dibuat dalam tiga panggilan dengan dua suara, dan adegan 15 detik di Google Vids yang diperpanjang lalu diedit 15 detik penuh. Setiap request adalah request asli dan setiap video adalah hasil asli, dari postingan rilis [Google Flow: Omni 1.2 Flash](/blog/261106) dan [Google Vids: Omni 1.2 Flash](/blog/261106v) (bahasa Inggris). Sebelum mulai, Anda butuh: - [API token](/docs/start-here/setup-useapi) useapi.net - akun Google yang terhubung lewat [Setup Google Flow](/docs/start-here/setup-google-flow), [Setup Google Vids](/docs/start-here/setup-google-vids), atau keduanya. Satu akun Google bisa dihubungkan ke kedua API, dan masing-masing tetap punya kuota sendiri. ### Google Flow atau Google Vids: Omni 1.2 Flash secara ringkas | | [Google Flow API](/docs/api-google-flow-v1) | [Google Vids API](/docs/api-google-vids-v1) | |---|---|---| | Cara memilih Omni 1.2 | `model: "omni-flash-1.2"` (Omni 1.1 Flash dan Veo 3.1 memakai nilai lain) | Tidak ada field `model`: Vids hanya punya satu model video, Omni 1.2 sejak rollout Google mulai 5 November | | Durasi | 3 sampai 15 detik (3 sampai 10 dengan frame awal dan akhir) | 3 sampai 15 detik | | Resolusi | 360p atau 720p, [upscale](/docs/api-google-flow-v1/post-google-flow-videos-upscale) ke 1080p, atau 4K di Ultra | 720p atau 1080p dengan harga sama, [upscale](/docs/api-google-vids-v1/post-google-vids-videos-upscale) ke 1080p untuk klip hingga 20 detik | | Input | Teks, frame awal, frame awal dan akhir, hingga 10 gambar referensi, [karakter](/docs/api-google-flow-v1/get-google-flow-characters) tersimpan, 1 sampai 4 video per request | Teks, gambar awal, atau hingga 3 referensi campuran gambar dan [avatar](/docs/api-google-vids-v1/post-google-vids-avatars) | | Suara | Hingga 5 [suara](/docs/api-google-flow-v1/get-google-flow-voices) per video jika ada gambar referensi atau karakter, hingga 3 per perpanjangan. 30 suara bawaan atau suara Anda sendiri | Setiap avatar bicara dengan salah satu dari 30 [suara](/docs/api-google-vids-v1/get-google-vids-voices), hingga 3 avatar per video | | [Extend](/docs/api-google-flow-v1/post-google-flow-videos-extend) | 3 sampai 10 detik per panggilan dengan suara dan referensi sendiri, hingga hampir 40 detik, paket berbayar | [3 sampai 10 detik per panggilan](/docs/api-google-vids-v1/post-google-vids-videos-extend) untuk klip hingga 24 detik, hingga sekitar 34 detik | | Edit dengan prompt | [Hingga 15 detik](/docs/api-google-flow-v1/post-google-flow-videos#video-reference-omni-11-flash-v2v-edit) klip hasil generate atau upload | [Hingga 15 detik](/docs/api-google-vids-v1/post-google-vids-videos-edit) klip buatan Google | | Yang dipakai | Kredit Flow: di 720p 3 per detik hingga 10 detik dan 6 per detik setelahnya, di 360p 1 dan 2 | Detik dari kuota Vids bulanan, terpisah dari kredit Flow | | Akun Google gratis | Video hingga 10 detik dari 50 kredit Flow per hari | Tidak ada detik video Vids dalam uji kami | | Captcha | Google meminta captcha untuk setiap video Flow. API ini yang menyelesaikannya: 300 gratis, lalu lewat [penyedia captcha](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers) tempat Anda mendaftar, sekitar $0,80 sampai $3,00 per 1.000 | Tidak ada | ### Harga per video Biaya satu video Omni 1.2 Flash 15 detik di [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) milik Google dan di setiap langganan Google AI (per November 2026). Setiap langganan berisi kredit Flow bulanan dan, terpisah, detik video Vids. Jadi satu video berbiaya sebesar bagiannya dari langganan. | Omni 1.2 Flash, 15 s | [API resmi](https://ai.google.dev/gemini-api/docs/pricing) | Ultra $199,99 (25.000 cr, 10.000 s) | Ultra $99,99 (10.000 cr, 2.500 s) | Pro $19,99 (1.000 cr, 500 s) | Plus $4,99 (200 cr, 60 s) | |---|---|---|---|---|---| | Google Flow (720p) | $1,04 (sekitar $0,07/s) | $0,48 / 60 cr (416 video/bln) | $0,60 / 60 cr (166 video/bln) | $1,20 / 60 cr (16 video/bln) | $1,50 / 60 cr (3 video/bln) | | Google Flow (360p) | $0,35 ($0,023/s) | $0,16 / 20 cr (1.250 video/bln) | $0,20 / 20 cr (500 video/bln) | $0,40 / 20 cr (50 video/bln) | $0,50 / 20 cr (10 video/bln) | | Google Vids (720p/1080p) | $1,04 di 720p ($1,56 di 1080p) | $0,30 / 15 s (666 video/bln) | $0,60 / 15 s (166 video/bln) | $0,60 / 15 s (33 video/bln) | $1,25 / 15 s (4 video/bln) | - Penghematan makin besar di paket yang lebih tinggi. Di Plus, dan di Pro untuk Flow, satu video 720p 15 detik lebih mahal daripada di Gemini API. Di Ultra $199,99 biayanya kurang dari separuh di Flow dan kurang dari sepertiga di Vids. - Flow menagih setiap detik setelah detik ke-10 dengan tarif dua kali lipat, jadi video yang lebih pendek lebih murah per detiknya di sana: video 720p 10 detik memakai 30 kredit, $0,24 di Ultra $199,99, dibanding $0,70 di Gemini API. Tabel Flow lengkap untuk semua model ada di [ringkasan Google Flow API](/docs/api-google-flow-v1#pricing), dan tabel Vids, termasuk gambar dan avatar, di [ringkasan Google Vids API](/docs/api-google-vids-v1#pricing). - Perpanjangan hanya memakai detik yang ditambahkannya, di kedua API. Edit di Vids memakai paling banyak detik yang diedit (dalam uji kami edit 15 detik memakai 10), dan edit di Flow berbiaya sama dengan video sepanjang bagian yang diedit. - Kredit Flow dan detik Vids adalah dua kuota terpisah dalam paket yang sama. Di Ultra $199,99, satu akun Google yang terhubung ke kedua API membuat sekitar 416 video 720p 15 detik di Flow dan 666 di Vids per bulan, total sekitar 1.082. - Harga paket adalah harga Google di AS. Jumlah detik Vids per paket berasal dari halaman [Gemini di Google Vids](https://support.google.com/docs/answer/15609411?hl=id) milik Google dan sesuai dengan uji kami di Ultra $199,99. ### Omni 1.2 Flash di Google Flow: adegan 30 detik dalam tiga panggilan Satu video 10 detik, lalu dua perpanjangan 10 detik, masing-masing dengan suaranya sendiri. Langkah 1 bisa dijalankan di akun Google gratis. Langkah 2 dan 3 (extend) butuh paket Google AI berbayar. Setiap panggilan berjalan sebagai job async: kirim `async: true` dan POST langsung menjawab dengan `jobid`. Polling [GET /jobs/`jobid`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid) sampai `status` bernilai `completed`, atau kirim `replyUrl` untuk menerima job yang sudah selesai di webhook Anda: ```bash curl --location 'https://api.useapi.net/v1/google-flow/jobs/<jobid>' --header 'Authorization: Bearer YOUR_API_TOKEN' ``` Video jadi ada di `response.media[0].videoUrl`, tautan yang berlaku sekitar 6 jam, dan langkah berikutnya memakai `response.media[0].mediaGenerationId` dari job yang sudah selesai. Jika Anda menghubungkan beberapa akun Google, API memilih akun yang sudah punya Omni 1.2 (Google mengaktifkannya bertahap selama beberapa hari mulai 5 November). Kirim `email` untuk memilih sendiri. #### Langkah 1: 10 detik pertama {: .no_toc #step-1-the-first-10-seconds } [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) dengan `model: "omni-flash-1.2"` dan `duration: 10`. Google menjawab dalam 56 detik. Di 720p, video 10 detik memakai 30 kredit. ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "model": "omni-flash-1.2", "duration": 10, "prompt": "Cinematic night, a narrow rainy alley in Tokyo glowing with neon signs reflected in the puddles. A street magician in a long dark coat faces the camera, fans out a deck of cards that glow faintly gold, and says with a grin: \"Pick a card. Any card.\" A sudden gust snatches one glowing card from his hand and it flutters away down the alley. Handheld camera, shallow depth of field, rain drops catching the light.", "async": true }' ``` <video poster="https://media.useapi.net/blog/2026-11-06-261106/261106-google-flow-omni-1-2-magician-first-10s-poster.jpg" src="https://media.useapi.net/blog/2026-11-06-261106/261106-google-flow-omni-1-2-magician-first-10s.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> <details markdown="block"> <summary>Job yang sudah selesai, dari <a href="/docs/api-google-flow-v1/get-google-flow-jobs-jobid">GET /jobs/<code>jobid</code></a> (dipersingkat)</summary> ```json { "jobid": "j1106021223539251070v-u12345-email:user@example.com-bot:google-flow", "type": "video", "status": "completed", "response": { "media": [ { "video": { "generatedVideo": { "model": "macaron_cookie_t2v_10s", "aspectRatio": "VIDEO_ASPECT_RATIO_LANDSCAPE" }, "dimensions": { "length": "10s" } }, "mediaGenerationId": "user:12345-email:…-video:b08556b9-…", "videoUrl": "https://flow-content.google/video/b08556b9-…?Expires=…" } ], "remainingCredits": 877 } } ``` </details> #### Langkah 2: perpanjang 10 detik, dengan suara {: .no_toc #step-2-extend-by-10-seconds-with-a-voice } [POST /videos/extend](/docs/api-google-flow-v1/post-google-flow-videos-extend) dengan `mediaGenerationId` video pertama, `duration: 10`, dan suara bawaan Charon sebagai `referenceAudio_1`. Prompt menempatkan suara itu di bagian sang pesulap berbicara, lewat sebutan inline `@referenceAudio_1`. Extend memakai Omni 1.2 secara default, jadi `model` tidak perlu diisi. Hasilnya satu klip 20 detik, 10 detik pertama tidak berubah ditambah 10 detik baru, setelah 2 menit 20 detik, dengan biaya 30 kredit. ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos/extend' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "mediaGenerationId": "user:12345-email:…-video:b08556b9-…", "duration": 10, "referenceAudio_1": "Charon", "prompt": "The magician runs after the glowing card through the rain, past a ramen stall and under paper lanterns, laughing and calling out in a deep voice @referenceAudio_1: \"Come back here! You are the ace of hearts!\" The camera follows him close behind.", "async": true }' ``` #### Langkah 3: 10 detik lagi, suara kedua {: .no_toc #step-3-10-more-seconds-a-second-voice } Panggilan yang sama pada klip 20 detik, dengan suara Aoede untuk perempuan di kafe. Hasilnya adegan utuh sepanjang 30 detik, setelah 2 menit lagi dan 30 kredit. ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos/extend' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "mediaGenerationId": "user:12345-email:…-video:113384cd-…", "duration": 10, "referenceAudio_1": "Aoede", "prompt": "The glowing card drifts through the open door of a tiny warm café and lands on a table. A young woman in a yellow raincoat picks it up, looks at the out-of-breath magician in the doorway, and says with a smile @referenceAudio_1: \"Is this your card?\" He laughs. Warm light, rain outside the window.", "async": true }' ``` <video poster="https://media.useapi.net/articles/2026-06-15-omni-flash-bash/261106-google-flow-omni-1-2-magician-extended-30s-web-poster.jpg" src="https://media.useapi.net/articles/2026-06-15-omni-flash-bash/261106-google-flow-omni-1-2-magician-extended-30s-web.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> <details markdown="block"> <summary>Job yang sudah selesai (dipersingkat)</summary> ```json { "jobid": "j1106021547955542178v-u12345-email:user@example.com-bot:google-flow", "type": "video", "status": "completed", "response": { "media": [ { "video": { "generatedVideo": { "model": "macaron_cookie_extend_10s" }, "dimensions": { "length": "30s" } }, "mediaGenerationId": "user:12345-email:…-video:db0201df-…", "videoUrl": "https://flow-content.google/video/db0201df-…?Expires=…" } ], "remainingCredits": 817 } } ``` </details> Video di atas di-encode ulang untuk web dengan resolusi asli 1280×720. Seluruh adegan memakai 90 kredit, sekitar $0,72 di Ultra $199,99, dibanding sekitar $2,10 untuk 30 detik dengan tarif 720p Gemini API (per November 2026). Google hanya memperpanjang video yang lebih pendek dari 30 detik, jadi adegan ini tidak bisa diperpanjang lagi: extend keempat langsung dijawab `400`, sebelum ada captcha atau kredit terpakai. Klip 25 detik masih bisa ditambah 10 detik dan berakhir di 35 detik. [`omni-extend/`](https://github.com/useapi/google-flow-api/tree/main/omni-extend) di GitHub membuat adegan ini dari satu `story.json`, dalam Node.js atau Python, dan [`omni-flash/`](https://github.com/useapi/google-flow-api/tree/main/omni-flash) membuat video Omni Flash secara batch dari daftar prompt. [Tutorial Omni Flash](/docs/articles/omni-flash-bash) (bahasa Inggris) membahas gambar referensi, karakter, frame awal dan akhir, serta edit. ### Omni 1.2 Flash di Google Vids: 15 detik, satu extend dan satu edit Vids hanya punya satu model video, yang dipindahkan Google ke Omni 1.2 dalam rollout beberapa hari mulai 5 November, jadi tidak ada `model` yang perlu diatur. Request memakai body JSON, dan setiap panggilan di sini berjalan sebagai job async: polling [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid) atau kirim `replyUrl`, lalu unduh klipnya dengan [GET /media/`mediaId`](/docs/api-google-vids-v1/get-google-vids-media-mediaId) dalam 24 jam. Langkah berikutnya memakai `result.mediaId` dari job yang sudah selesai. Vids tidak meminta captcha. ```bash curl --location 'https://api.useapi.net/v1/google-vids/jobs/<jobid>' --header 'Authorization: Bearer YOUR_API_TOKEN' ``` #### Langkah 1: video 15 detik dari satu prompt {: .no_toc #step-1-a-15-second-video-from-one-prompt } [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) dengan `duration: 15`. Google menjawab dalam sekitar 60 detik dengan video 1280×720, dan kedua kalimat diucapkan persis seperti yang ditulis. Video ini memakai 15 detik dari kuota. ```bash curl --location 'https://api.useapi.net/v1/google-vids/videos' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "prompt": "Cinematic single continuous shot, 15 seconds, 16:9. Golden hour on a Tokyo rooftop garden, city skyline glowing behind. A young chef in a crisp white apron finishes plating a steaming bowl of ramen, steam curling in the warm light. She looks up into the camera and says with a confident smile: \"Fifteen seconds. One prompt. No editing.\" She slides the bowl toward the camera as it slowly pushes in, wind chimes ringing softly and city traffic humming far below. She laughs and adds: \"Now that'\''s fast food.\"", "duration": 15, "aspectRatio": "landscape", "resolution": "720p", "async": true }' ``` <video poster="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-15s-poster.jpg" src="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-15s.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> <details markdown="block"> <summary>Job yang sudah selesai, dari <a href="/docs/api-google-vids-v1/get-google-vids-jobs-jobid">GET /jobs/<code>jobid</code></a> (dipersingkat)</summary> ```json { "status": "completed", "result": { "mediaId": "user:12345-user@example.com-video:eyJ1Ijoi…", "width": 1280, "height": 720, "duration": 15, "resolution": "720p", "aspectRatio": "landscape", "model": "/flix/generate_videos_omni_t2v_psq/v1", "quota": { "video": { "limit": 500, "left": 485, "resetAt": "2026-12-01T08:00:00.000Z" } } } } ``` </details> `quota` menunjukkan sisa detik video bulanan akun dan kapan kuotanya direset. Akun uji ini memakai Google AI Pro, karena itu batasnya 500 detik. Harga di halaman ini memakai Ultra $199,99. #### Langkah 2: perpanjang 10 detik {: .no_toc #step-2-extend-it-by-10-seconds } [POST /videos/extend](/docs/api-google-vids-v1/post-google-vids-videos-extend) dengan `mediaId` video pertama. Hasilnya satu klip, 15 detik ditambah 10 detik baru, sepanjang 25 detik, setelah sekitar 100 detik. Seorang teman masuk, mencicipi ramen, dan kedua kalimat barunya diucapkan. ```bash curl --location 'https://api.useapi.net/v1/google-vids/videos/extend' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "mediaId": "user:12345-user@example.com-video:eyJ1Ijoi…", "prompt": "Same shot continues on the Tokyo rooftop at dusk, the city lights now switching on. A friend in a denim jacket walks into frame, sits at the table and takes a first slurp of the ramen, eyes widening. He says: \"Wait, you made this in fifteen seconds?\" The chef folds her arms and grins: \"Fifteen more, and I'\''ll make dessert.\" They both laugh as string lights flicker on above them and soft city ambience fills the air.", "duration": 10, "async": true }' ``` <video poster="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-extend-25s-poster.jpg" src="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-extend-25s.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> Juga di YouTube: [Gemini Omni 1.2 Flash in Google Vids: 15 seconds from one prompt, extended to 25](https://www.youtube.com/watch?v=eJ3js18XCBM). API menerima 3 sampai 10 detik per panggilan extend dan menjawab `duration` yang lebih panjang dengan `400`: Google menambah paling banyak 10 detik, tetapi menghitung semua detik yang diminta. (Klip ini berasal dari uji sebelumnya dengan `duration: 15`.) Request yang sama dengan `duration: 10` menghasilkan klip 25 detik yang sama dan memakai 10 detik. Vids memperpanjang klip hingga 24 detik, jadi klip 25 detik ini sudah sepanjang maksimal. Untuk klip terpanjang, sekitar 34 detik, perpanjang klip 24 detik atau kurang dengan 10 detik. #### Langkah 3: edit 15 detik penuh {: .no_toc #step-3-edit-all-15-seconds } [POST /videos/edit](/docs/api-google-vids-v1/post-google-vids-videos-edit) pada video pertama dengan `duration: 15`. Dengan Omni 1.1, edit menghasilkan paling banyak 10 detik. Sekarang seluruh klip 15 detik kembali dalam keadaan teredit, setiap frame-nya, setelah sekitar 140 detik. ```bash curl --location 'https://api.useapi.net/v1/google-vids/videos/edit' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "video": "user:12345-user@example.com-video:eyJ1Ijoi…", "prompt": "Make it a snowy winter evening: snow falling gently over the rooftop and the city, the chef wearing a red knit scarf. Keep everything else the same.", "duration": 15, "async": true }' ``` <video poster="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-edit-snow-15s-poster.jpg" src="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-edit-snow-15s.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> Vids mengedit klip buatan Google, dan Google menolak video upload dengan `422`. Untuk satu klip saja, generate di 1080p, yang memakai kuota sama dengan 720p. Untuk klip yang akan diperpanjang, kerjakan di 720p dan naikkan ke 1080p sekali saja, di akhir: setiap extend di 1080p memproses ulang seluruh klip dan membuat detik-detik awal terlalu tajam ([lihat perbandingannya](/blog/261106v#720p-or-1080p-what-a-1080p-extend-does)). Selesaikan klip hingga 20 detik dengan satu [upscale](/docs/api-google-vids-v1/post-google-vids-videos-upscale) (yang memakai detik klip itu lagi), dan untuk klip 21 sampai 34 detik pasang `resolution: "1080p"` hanya di extend terakhir. Repo [google-vids-api](https://github.com/useapi/google-vids-api) di GitHub berisi contoh Vids siap jalan dalam Node.js dan Python, termasuk avatar bersuara, dan [tutorial influencer AI](/docs/articles/google-vids-influencer-avatars-id) membuat klip dengan dua avatar yang berbicara. ### Mana yang dipakai Pilih Google Flow API jika Anda ingin: - draf 360p dengan sepertiga harga 720p, atau hingga 4 video per request - frame awal dan akhir, hingga 10 gambar referensi, atau karakter tersimpan - memilih suara sendiri: hingga 5 per video dengan gambar referensi atau karakter dan hingga 3 per perpanjangan, dari 30 suara bawaan atau suara Anda sendiri - mengedit video upload, atau upscale ke 4K di Ultra - video Veo 3.1 dan gambar Nano Banana dari API yang sama - Omni 1.2 di akun Google gratis, hingga 10 detik Pilih Google Vids API jika Anda ingin: - tanpa captcha dan tanpa penyedia captcha - 1080p dengan harga sama seperti 720p (untuk klip yang akan diperpanjang atau diedit, lihat [resolusi mana yang dipakai](#vids-resolution)) - avatar bersuara yang mempertahankan tampilan dan suaranya dari satu video ke video berikutnya, hingga 3 dalam satu video - harga per detik terendah di Ultra $199,99, $0,02 dibanding $0,032 untuk video 15 detik di Flow - lebih banyak video Omni 1.2 setelah kredit Flow habis, karena Vids punya kuota sendiri Atau pakai keduanya: hubungkan akun Google yang sama ke masing-masing API dan kirim job ke tempat yang paling cocok, karena kedua [kuota itu saling menambah](#price-per-video). ### Pakai dari Claude Code, Cursor atau Gemini CLI Kedua API punya MCP server yang di-hosting dan berjalan dengan API token useapi.net Anda, tanpa perlu instalasi apa pun. Di Claude Code, masing-masing cukup satu baris: ```bash claude mcp add --transport http useapi-google-vids https://api.useapi.net/v1/google-vids/mcp --header "Authorization: Bearer YOUR_API_TOKEN" claude mcp add --transport http useapi-google-flow https://api.useapi.net/v1/google-flow/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` Di Cursor atau Gemini CLI, tambahkan URL yang sama dengan header `Authorization` yang sama di pengaturan MCP-nya. - [MCP server Google Vids](/docs/api-google-vids-v1/mcp) membuat klip Omni 1.2 secara langsung: `vids_create_video` dan `vids_edit_video` menerima hingga 15 detik, dan `vids_extend_video` hingga 10 detik per panggilan untuk klip hingga 24 detik. - [MCP server Google Flow](/docs/api-google-flow-v1/mcp) berbicara dengan Google Flow Agent, bukan langsung dengan endpoint Omni 1.2: asisten Anda mengobrol dengan Agent, yang membuat gambar dan video dengan harga Flow biasa. Untuk panggilan Omni 1.2 langsung dari Claude Code atau Codex, tambahkan [agent skill omni-flash-video](https://github.com/useapi/google-flow-api/tree/main/skills/omni-flash-video). - Kedua repo juga memasang server ini sebagai plugin Claude Code atau ekstensi Gemini CLI: [google-flow-api](https://github.com/useapi/google-flow-api#use-with-claude-code) dan [google-vids-api](https://github.com/useapi/google-vids-api#use-with-claude-code). ### Pertanyaan #### Apakah ada API Gemini Omni 1.2 Flash? Lewat useapi.net, ada: Gemini Omni 1.2 Flash berjalan di langganan Google AI Anda lewat [Google Flow API](/docs/api-google-flow-v1) (`model: "omni-flash-1.2"`) dan [Google Vids API](/docs/api-google-vids-v1), tanpa Gemini API key. Biayanya mulai $0,02 per detik dari kuota Vids Ultra $199,99, dibanding sekitar $0,07 per detik di [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) Google. Flow menerima hingga 5 suara per video dengan gambar referensi atau karakter, sementara API Google [membatasi referensi audio lewat allowlist](https://cloud.google.com/blog/products/ai-machine-learning/gemini-omni-1-2-flash-generally-available) (per November 2026). #### Berapa harga Omni 1.2 Flash per video? Lewat useapi.net di Google AI Ultra $199,99, satu video Omni 1.2 Flash 15 detik memakai $0,30 dari kuota Vids paket itu atau $0,48 dari kredit Flow-nya, dibanding $1,04 untuk 720p di Gemini API Google (per November 2026). Di Vids, video 1080p 15 detik juga $0,30, karena 1080p memakai detik yang sama, sedangkan Gemini API menagih $1,56. [Tabel harga](#price-per-video) menampilkan semua paket. #### Apakah ada API Gemini Omni 1.2 Flash gratis? Lewat useapi.net, ada, di Google Flow API: akun Google gratis membuat video Omni 1.2 Flash hingga 10 detik dari [50 kredit Flow harian](https://support.google.com/flow/answer/16526234?hl=id), yaitu satu video 10 detik di 720p atau lima di 360p per hari. Gemini API milik Google hanya menyediakan Omni 1.2 Flash di tier berbayar (per November 2026). Video yang lebih panjang dan extend dengan Omni 1.2 butuh paket Google AI berbayar. #### Berapa durasi maksimal video Omni 1.2 Flash? Lewat useapi.net, satu panggilan membuat 3 sampai 15 detik di Google Flow maupun Google Vids, dan extend menambah 3 sampai 10 detik per panggilan lalu mengembalikan klip utuh: hingga hampir 40 detik di Flow, dengan suara baru di setiap perpanjangan jika mau, dan sekitar 34 detik di Vids, yang memperpanjang klip hingga 24 detik. [Adegan 30 detik](#flow-walkthrough) di atas dibuat dengan cara ini dalam tiga panggilan. #### Omni 1.2 Flash vs Veo 3.1: mana yang dipakai? Lewat useapi.net, keduanya berjalan di Google Flow API yang sama dengan satu paket: di Ultra $199,99, video Omni 1.2 Flash 720p 8 detik berbiaya $0,19 dan Veo 3.1 Fast $0,08, dibanding $0,56 dan $0,80 di API milik Google (per November 2026). Pilih Omni 1.2 Flash untuk klip lebih dari 8 detik, hingga 5 suara pilihan Anda, dan perpanjangan dengan suara baru. Pilih Veo 3.1 Fast untuk klip 8 detik termurah. Semua harga Veo: [harga API Veo 3.1](/docs/articles/veo-3-1-api-pricing) (bahasa Inggris). ### Sumber - Google Cloud, [Gemini Omni 1.2 Flash is generally available](https://cloud.google.com/blog/products/ai-machine-learning/gemini-omni-1-2-flash-generally-available), 5 November 2026 - Google Workspace Updates, [Gemini Omni 1.2 Flash now in Vids](https://workspaceupdates.googleblog.com/2026/11/gemini-omni-12-flash-now-in-vids-with-15second-generations-and-improved-quality.html), 5 November 2026 - Google, [Harga Gemini API](https://ai.google.dev/gemini-api/docs/pricing), dibaca 6 November 2026 - Google Cloud, [Harga Agent Platform](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing) (Veo 3.1), dibaca 6 November 2026 - Google, [Paket Google AI](https://gemini.google/subscriptions/), [Kredit Flow](https://support.google.com/flow/answer/16526234?hl=id) dan [Gemini di Google Vids](https://support.google.com/docs/answer/15609411?hl=id), dibaca November 2026 - Postingan rilis useapi.net (bahasa Inggris): [Google Flow: Omni 1.2 Flash, 15-Second Videos, and Extend with Voices](/blog/261106) dan [Google Vids: Omni 1.2 Flash, 15-Second Videos and 15-Second Edits](/blog/261106v), 6 November 2026 ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/gemini-omni-1-2-flash-api-ja === Document URL: https://useapi.net/docs/articles/gemini-omni-1-2-flash-api-ja --- layout: default title: "Gemini Omni 1.2 Flash API の使い方:Google Flow と Google Vids で15秒の動画を生成" seo_title: "Gemini Omni 1.2 Flash API の使い方:15秒動画と料金" description: "useapi.net で Gemini Omni 1.2 Flash API を使う方法。Google Flow と Vids で音声付き3〜15秒の動画を生成。Ultra $199.99 なら15秒 $0.30、Gemini API では $1.04。" image: https://media.useapi.net/articles/2026-11-06-gemini-omni-1-2-flash-api-id/261106-gemini-omni-1-2-flash-api-cover.jpg keywords: [Gemini Omni 1.2 Flash API, Omni 1.2 Flash API, Gemini Omni 1.2 API, Omni 1.2 Flash 使い方, Omni 1.2 Flash 料金, Omni 1.2 Flash 無料, omni-flash-1.2, Omni Flash 15秒, Gemini Omni API, Gemini Omni Flash API, 動画生成 API, AI 動画 音声付き, 動画 延長 API, 動画編集 API, Veo 代替, Veo 3.1 代替, Google Flow API, Google Vids API, Google AI Ultra, Gemini API キー 不要, 日本語チュートリアル, Japanese tutorial, curl] parent: Articles nav_exclude: true lang: ja translation_key: gemini-omni-1-2-flash date: 2026-11-06 last_modified: 2026-11-11 nav_order: 908 repo: https://github.com/useapi/google-flow-api --- ## Gemini Omni 1.2 Flash API の使い方:Google Flow と Google Vids で15秒の動画を生成 {: .no_toc #how-to-use-the-gemini-omni-12-flash-api-15-second-videos-in-google-flow-and-google-vids } 7分で読めます • 2026年11月6日 useapi.net はサードパーティの API です。Google とは提携しておらず、Google の承認も受けていません。 ## 目次 {: .no_toc .text-delta #table-of-contents } ### はじめに Gemini Omni 1.2 Flash は Google が2026年11月5日に公開したモデルで、音声とセリフ付きの3〜15秒の動画を作ります。useapi.net は、[Google Flow API](/docs/api-google-flow-v1) と [Google Vids API](/docs/api-google-vids-v1) という2つの REST API を通して、このモデルをお使いの [Google AI のプラン](https://gemini.google/subscriptions/)で動かします。Google AI Ultra $199.99 では、15秒の動画1本はプランの月間 Vids 利用枠の $0.30 分、または Flow クレジットの $0.48 分です。Google 自身の [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) では、720p の15秒で $1.04 かかります(2026年11月時点)。Gemini API キーも Google Cloud プロジェクトも必要ありません。 Google の[発表](https://cloud.google.com/blog/products/ai-machine-learning/gemini-omni-1-2-flash-generally-available)によると、1.2 では動画の長さが10秒から最長15秒になり、参照素材により忠実になり、口の動きもより正確になりました。Google は同じ日に [Google Vids もこのモデルに切り替えました](https://workspaceupdates.googleblog.com/2026/11/gemini-omni-12-flash-now-in-vids-with-15second-generations-and-improved-quality.html)。 このガイドでは、まず2つの方法を並べて比べ、それぞれで実際のシーンを1つずつ作ります。Google Flow では3回の呼び出しで2人の声が入る30秒のシーンを、Google Vids では15秒のシーンを作って延長し、15秒の編集もします。リクエストはすべて実際に送ったもので、動画もすべて実際の出力です。出典はリリース記事 [Google Flow: Omni 1.2 Flash](/blog/261106) と [Google Vids: Omni 1.2 Flash](/blog/261106v)(どちらも英語)です。 始める前に必要なもの: - useapi.net の [API トークン](/docs/start-here/setup-useapi) - [Google Flow のセットアップ](/docs/start-here/setup-google-flow)、[Google Vids のセットアップ](/docs/start-here/setup-google-vids)、またはその両方で接続した Google アカウント。1つの Google アカウントを両方の API に接続でき、利用枠はそれぞれ別に数えられます。 ### Google Flow と Google Vids:Omni 1.2 Flash の比較 | | [Google Flow API](/docs/api-google-flow-v1) | [Google Vids API](/docs/api-google-vids-v1) | |---|---|---| | Omni 1.2 の選び方 | `model: "omni-flash-1.2"`(Omni 1.1 Flash と Veo 3.1 は別の値) | `model` フィールドはありません。Vids の動画モデルは1つだけで、11月5日からの Google の展開以降は Omni 1.2 です | | 長さ | 3〜15秒(開始フレームと終了フレームを指定する場合は3〜10秒) | 3〜15秒 | | 解像度 | 360p または 720p。1080p へ[アップスケール](/docs/api-google-flow-v1/post-google-flow-videos-upscale)、Ultra なら 4K | 720p または 1080p(同じ料金)。20秒以下の動画は 1080p へ[アップスケール](/docs/api-google-vids-v1/post-google-vids-videos-upscale) | | 入力 | テキスト、開始フレーム、開始・終了フレーム、最大10枚の参照画像、保存済みの[キャラクター](/docs/api-google-flow-v1/get-google-flow-characters)。1リクエストで1〜4本 | テキスト、開始画像、または画像と[アバター](/docs/api-google-vids-v1/post-google-vids-avatars)を組み合わせた最大3つの参照 | | 声 | 参照画像かキャラクターがある動画で最大5つの[声](/docs/api-google-flow-v1/get-google-flow-voices)、延長1回で最大3つ。30種類の内蔵の声か、ご自身の声 | アバターはそれぞれ30種類の[声](/docs/api-google-vids-v1/get-google-vids-voices)のどれかで話します。1本の動画に最大3体 | | [延長](/docs/api-google-flow-v1/post-google-flow-videos-extend) | 1回3〜10秒、回ごとに声と参照を指定でき、40秒弱まで。有料プランのみ | 24秒以下の動画に[1回3〜10秒](/docs/api-google-vids-v1/post-google-vids-videos-extend)、最長約34秒 | | プロンプトで編集 | 生成した動画またはアップロードした動画の[最大15秒](/docs/api-google-flow-v1/post-google-flow-videos#video-reference-omni-11-flash-v2v-edit) | Google が作った動画の[最大15秒](/docs/api-google-vids-v1/post-google-vids-videos-edit) | | 消費するもの | Flow クレジット:720p では10秒まで1秒3、それ以降は1秒6。360p では1と2 | 月間 Vids 利用枠の秒数。Flow クレジットとは別枠 | | 無料の Google アカウント | 1日50の Flow クレジットで10秒以下の動画 | 当社のテストでは Vids の動画秒数はゼロ | | CAPTCHA | Google は Flow の動画ごとに CAPTCHA を求めます。API が代わりに解決し、300回までは無料、その後はご自身で契約する [CAPTCHA プロバイダー](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers)経由で1,000回あたり約 $0.80〜$3.00 です | 不要 | ### 動画1本あたりの料金 15秒の Omni 1.2 Flash 動画1本の料金を、Google 自身の [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) と Google AI の各プランで比べました(2026年11月時点)。どのプランにも毎月の Flow クレジットと、それとは別に Vids の動画秒数が付いています。そのため動画1本の料金は、プラン料金のうちその動画が使う分です。 | Omni 1.2 Flash・15秒 | [公式 API](https://ai.google.dev/gemini-api/docs/pricing) | Ultra $199.99/月 (25,000 cr, 10,000秒) | Ultra $99.99/月 (10,000 cr, 2,500秒) | Pro $19.99/月 (1,000 cr, 500秒) | Plus $4.99/月 (200 cr, 60秒) | |---|---|---|---|---|---| | Google Flow (720p) | $1.04 ($0.07/秒) | $0.48 / 60 cr (月416本) | $0.60 / 60 cr (月166本) | $1.20 / 60 cr (月16本) | $1.50 / 60 cr (月3本) | | Google Flow (360p) | $0.35 ($0.023/秒) | $0.16 / 20 cr (月1,250本) | $0.20 / 20 cr (月500本) | $0.40 / 20 cr (月50本) | $0.50 / 20 cr (月10本) | | Google Vids (720p・1080p) | 720p $1.04 (1080p $1.56) | $0.30 / 15秒 (月666本) | $0.60 / 15秒 (月166本) | $0.60 / 15秒 (月33本) | $1.25 / 15秒 (月4本) | - プランが大きいほど安くなります。Plus と、Flow で使う Pro では、15秒・720p の動画は Gemini API より高くなります。一方 Ultra $199.99 では、Flow で半額以下、Vids で3分の1以下です。 - Flow は10秒を超える分を1秒あたり2倍のクレジットで数えるので、短い動画ほど1秒あたりは安くなります。10秒・720p の動画は30クレジットで、Ultra $199.99 では $0.24、Gemini API では $0.70 です。全モデルの Flow の料金表は [Google Flow API の概要](/docs/api-google-flow-v1#pricing)に、画像とアバターを含む Vids の料金表は [Google Vids API の概要](/docs/api-google-vids-v1#pricing)にあります。 - 延長は、どちらの API でも追加した秒数分だけを使います。Vids の編集が使うのは編集した秒数までで(当社のテストでは15秒の編集で10秒)、Flow の編集は編集した長さの動画と同じ料金です。 - Flow クレジットと Vids の秒数は、同じプランの別々の利用枠です。Ultra $199.99 で1つの Google アカウントを両方の API に接続すると、15秒・720p の動画を Flow で月約416本、Vids で666本、合計で約1,082本作れます。 - プランの料金は Google の米国価格です。プランごとの Vids の秒数は Google の [Google Vids の Gemini](https://support.google.com/docs/answer/15609411?hl=ja) のページによるもので、当社の Ultra $199.99 でのテストとも一致しています。 ### Google Flow の Omni 1.2 Flash:3回の呼び出しで30秒のシーン 10秒の動画を作り、それを10秒ずつ2回延長します。延長ごとに別の声を使います。ステップ1は無料の Google アカウントでも動きます。ステップ2と3(延長)には有料の Google AI プランが必要です。 呼び出しはすべて非同期ジョブとして実行します。`async: true` を渡すと、POST はすぐに `jobid` を返します。`status` が `completed` になるまで [GET /jobs/`jobid`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid) をポーリングするか、`replyUrl` を渡して完了したジョブを Webhook で受け取ります。 ```bash curl --location 'https://api.useapi.net/v1/google-flow/jobs/<jobid>' --header 'Authorization: Bearer YOUR_API_TOKEN' ``` 完成した動画は `response.media[0].videoUrl` にあり、このリンクは約6時間有効です。次のステップでは、完了したジョブの `response.media[0].mediaGenerationId` を使います。複数の Google アカウントを接続している場合、API はすでに Omni 1.2 が使えるアカウントを選びます(Google は11月5日から数日かけて順に有効にしています)。アカウントを指定するには `email` を渡します。 #### ステップ1:最初の10秒 {: .no_toc #step-1-the-first-10-seconds } `model: "omni-flash-1.2"` と `duration: 10` を指定して [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) を呼びます。Google の応答は56秒でした。720p の10秒の動画は30クレジットです。 ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "model": "omni-flash-1.2", "duration": 10, "prompt": "Cinematic night, a narrow rainy alley in Tokyo glowing with neon signs reflected in the puddles. A street magician in a long dark coat faces the camera, fans out a deck of cards that glow faintly gold, and says with a grin: \"Pick a card. Any card.\" A sudden gust snatches one glowing card from his hand and it flutters away down the alley. Handheld camera, shallow depth of field, rain drops catching the light.", "async": true }' ``` <video poster="https://media.useapi.net/blog/2026-11-06-261106/261106-google-flow-omni-1-2-magician-first-10s-poster.jpg" src="https://media.useapi.net/blog/2026-11-06-261106/261106-google-flow-omni-1-2-magician-first-10s.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> <details markdown="block"> <summary>完了したジョブ(<a href="/docs/api-google-flow-v1/get-google-flow-jobs-jobid">GET /jobs/<code>jobid</code></a> の応答、一部省略)</summary> ```json { "jobid": "j1106021223539251070v-u12345-email:user@example.com-bot:google-flow", "type": "video", "status": "completed", "response": { "media": [ { "video": { "generatedVideo": { "model": "macaron_cookie_t2v_10s", "aspectRatio": "VIDEO_ASPECT_RATIO_LANDSCAPE" }, "dimensions": { "length": "10s" } }, "mediaGenerationId": "user:12345-email:…-video:b08556b9-…", "videoUrl": "https://flow-content.google/video/b08556b9-…?Expires=…" } ], "remainingCredits": 877 } } ``` </details> #### ステップ2:声を付けて10秒延長する {: .no_toc #step-2-extend-by-10-seconds-with-a-voice } [POST /videos/extend](/docs/api-google-flow-v1/post-google-flow-videos-extend) に、最初の動画の `mediaGenerationId`、`duration: 10`、`referenceAudio_1` として内蔵の声 Charon を渡します。プロンプトでは、マジシャンが話す箇所にインラインで `@referenceAudio_1` と書いて声を割り当てます。延長はデフォルトで Omni 1.2 を使うので、`model` は不要です。返ってくるのは20秒の動画1本で、最初の10秒はそのまま、その後に新しい10秒が続きます。2分20秒かかり、30クレジットを使いました。 ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos/extend' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "mediaGenerationId": "user:12345-email:…-video:b08556b9-…", "duration": 10, "referenceAudio_1": "Charon", "prompt": "The magician runs after the glowing card through the rain, past a ramen stall and under paper lanterns, laughing and calling out in a deep voice @referenceAudio_1: \"Come back here! You are the ace of hearts!\" The camera follows him close behind.", "async": true }' ``` #### ステップ3:さらに10秒、2人目の声 {: .no_toc #step-3-10-more-seconds-a-second-voice } 20秒の動画に同じ呼び出しを行い、カフェにいる女性の声には Aoede を使います。結果は30秒のシーン全体で、さらに2分と30クレジットかかりました。 ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos/extend' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "mediaGenerationId": "user:12345-email:…-video:113384cd-…", "duration": 10, "referenceAudio_1": "Aoede", "prompt": "The glowing card drifts through the open door of a tiny warm café and lands on a table. A young woman in a yellow raincoat picks it up, looks at the out-of-breath magician in the doorway, and says with a smile @referenceAudio_1: \"Is this your card?\" He laughs. Warm light, rain outside the window.", "async": true }' ``` <video poster="https://media.useapi.net/articles/2026-06-15-omni-flash-bash/261106-google-flow-omni-1-2-magician-extended-30s-web-poster.jpg" src="https://media.useapi.net/articles/2026-06-15-omni-flash-bash/261106-google-flow-omni-1-2-magician-extended-30s-web.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> <details markdown="block"> <summary>完了したジョブ(一部省略)</summary> ```json { "jobid": "j1106021547955542178v-u12345-email:user@example.com-bot:google-flow", "type": "video", "status": "completed", "response": { "media": [ { "video": { "generatedVideo": { "model": "macaron_cookie_extend_10s" }, "dimensions": { "length": "30s" } }, "mediaGenerationId": "user:12345-email:…-video:db0201df-…", "videoUrl": "https://flow-content.google/video/db0201df-…?Expires=…" } ], "remainingCredits": 817 } } ``` </details> 上の動画は、元の 1280×720 のまま Web 用に再エンコードしたものです。シーン全体で90クレジット、Ultra $199.99 で約 $0.72 を使いました。Gemini API の 720p の料金なら、30秒で約 $2.10 です(2026年11月時点)。 Google が延長するのは30秒未満の動画だけなので、このシーンはこれ以上延ばせません。4回目の延長は、CAPTCHA やクレジットを使う前にすぐ `400` を返します。25秒の動画なら、あと10秒延ばして35秒にできます。 GitHub の [`omni-extend/`](https://github.com/useapi/google-flow-api/tree/main/omni-extend) は、1つの `story.json` からこのシーンを Node.js または Python で作ります。[`omni-flash/`](https://github.com/useapi/google-flow-api/tree/main/omni-flash) は、プロンプトのリストから Omni Flash の動画を一括生成します。参照画像、キャラクター、開始・終了フレーム、編集については [Omni Flash のチュートリアル](/docs/articles/omni-flash-bash)(英語)で説明しています。 ### Google Vids の Omni 1.2 Flash:15秒の動画、延長、編集 Vids の動画モデルは1つだけで、Google は11月5日から数日かけてそれを Omni 1.2 に切り替えました。そのため、指定する `model` はありません。リクエストは JSON ボディで送り、ここでの呼び出しはすべて非同期ジョブとして実行します。[GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid) をポーリングするか `replyUrl` を渡し、24時間以内に [GET /media/`mediaId`](/docs/api-google-vids-v1/get-google-vids-media-mediaId) で動画をダウンロードします。次のステップでは、完了したジョブの `result.mediaId` を使います。Vids では CAPTCHA は不要です。 ```bash curl --location 'https://api.useapi.net/v1/google-vids/jobs/<jobid>' --header 'Authorization: Bearer YOUR_API_TOKEN' ``` #### ステップ1:1つのプロンプトから15秒の動画 {: .no_toc #step-1-a-15-second-video-from-one-prompt } `duration: 15` を指定して [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) を呼びます。Google は約60秒で 1280×720 の動画を返し、2つのセリフはどちらも書いたとおりに話されています。利用枠は15秒使いました。 ```bash curl --location 'https://api.useapi.net/v1/google-vids/videos' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "prompt": "Cinematic single continuous shot, 15 seconds, 16:9. Golden hour on a Tokyo rooftop garden, city skyline glowing behind. A young chef in a crisp white apron finishes plating a steaming bowl of ramen, steam curling in the warm light. She looks up into the camera and says with a confident smile: \"Fifteen seconds. One prompt. No editing.\" She slides the bowl toward the camera as it slowly pushes in, wind chimes ringing softly and city traffic humming far below. She laughs and adds: \"Now that'\''s fast food.\"", "duration": 15, "aspectRatio": "landscape", "resolution": "720p", "async": true }' ``` <video poster="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-15s-poster.jpg" src="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-15s.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> <details markdown="block"> <summary>完了したジョブ(<a href="/docs/api-google-vids-v1/get-google-vids-jobs-jobid">GET /jobs/<code>jobid</code></a> の応答、一部省略)</summary> ```json { "status": "completed", "result": { "mediaId": "user:12345-user@example.com-video:eyJ1Ijoi…", "width": 1280, "height": 720, "duration": 15, "resolution": "720p", "aspectRatio": "landscape", "model": "/flix/generate_videos_omni_t2v_psq/v1", "quota": { "video": { "limit": 500, "left": 485, "resetAt": "2026-12-01T08:00:00.000Z" } } } } ``` </details> `quota` は、アカウントの月間動画秒数の残りと、リセットされる日時を示します。このテストアカウントは Google AI Pro なので、上限は500秒です。このページの料金は Ultra $199.99 で計算しています。 #### ステップ2:10秒延長する {: .no_toc #step-2-extend-it-by-10-seconds } 最初の動画の `mediaId` を渡して [POST /videos/extend](/docs/api-google-vids-v1/post-google-vids-videos-extend) を呼びます。結果は15秒に新しい10秒を加えた25秒の動画1本で、約100秒かかりました。友人が入ってきてラーメンを食べ、新しい2つのセリフもどちらも話されています。 ```bash curl --location 'https://api.useapi.net/v1/google-vids/videos/extend' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "mediaId": "user:12345-user@example.com-video:eyJ1Ijoi…", "prompt": "Same shot continues on the Tokyo rooftop at dusk, the city lights now switching on. A friend in a denim jacket walks into frame, sits at the table and takes a first slurp of the ramen, eyes widening. He says: \"Wait, you made this in fifteen seconds?\" The chef folds her arms and grins: \"Fifteen more, and I'\''ll make dessert.\" They both laugh as string lights flicker on above them and soft city ambience fills the air.", "duration": 10, "async": true }' ``` <video poster="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-extend-25s-poster.jpg" src="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-extend-25s.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> YouTube でも公開しています:[Gemini Omni 1.2 Flash in Google Vids: 15 seconds from one prompt, extended to 25](https://www.youtube.com/watch?v=eJ3js18XCBM)(英語)。 API が受け付けるのは延長1回あたり3〜10秒で、それより長い `duration` には `400` を返します。Google は最大10秒しか追加しないのに、リクエストした秒数をすべて数えるためです(この動画は、`duration: 15` で行った以前のテストのものです)。同じリクエストを `duration: 10` で送ると同じ25秒の動画が返り、使うのは10秒です。Vids が延長できるのは24秒以下の動画なので、この25秒の動画はこれ以上延ばせません。最長の約34秒にするには、24秒以下の動画を10秒延長します。 #### ステップ3:15秒すべてを編集する {: .no_toc #step-3-edit-all-15-seconds } 最初の動画に `duration: 15` で [POST /videos/edit](/docs/api-google-vids-v1/post-google-vids-videos-edit) を呼びます。Omni 1.1 では、編集で返ってくるのは最大10秒でした。今回は15秒の動画全体が、すべてのフレームを編集した状態で、約140秒後に返ってきました。 ```bash curl --location 'https://api.useapi.net/v1/google-vids/videos/edit' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "video": "user:12345-user@example.com-video:eyJ1Ijoi…", "prompt": "Make it a snowy winter evening: snow falling gently over the rooftop and the city, the chef wearing a red knit scarf. Keep everything else the same.", "duration": 15, "async": true }' ``` <video poster="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-edit-snow-15s-poster.jpg" src="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-edit-snow-15s.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> Vids が編集できるのは Google が作った動画だけで、アップロードした動画は Google が `422` で拒否します。 1本だけの動画なら、720p と同じ利用枠で済む 1080p で生成してください。延長する動画は 720p で作り、最後に一度だけ 1080p にします。1080p で延長すると毎回動画全体が処理し直され、前の部分がシャープになりすぎるためです([比較はこちら](/blog/261106v#720p-or-1080p-what-a-1080p-extend-does)、英語)。20秒以下の動画は最後に[アップスケール](/docs/api-google-vids-v1/post-google-vids-videos-upscale)を1回行い(動画の秒数をもう一度使います)、21〜34秒の動画は最後の延長だけに `resolution: "1080p"` を指定します。 GitHub の [google-vids-api](https://github.com/useapi/google-vids-api) リポジトリには、Node.js と Python で動く Vids のサンプルがあり、声付きのアバターの例も入っています。[AI インフルエンサーのチュートリアル](/docs/articles/google-vids-influencer-avatars-ja)では、話す2体のアバターで動画を作ります。 ### どちらを使うか 次のような場合は Google Flow API を選びます。 - 720p の3分の1の料金で 360p の下書きを作りたい、または1リクエストで最大4本作りたい - 開始フレームと終了フレーム、最大10枚の参照画像、保存済みのキャラクターを使いたい - 声を自分で選びたい:参照画像かキャラクターがある動画で最大5つ、延長1回で最大3つ。30種類の内蔵の声か、ご自身の声から選べます - アップロードした動画を編集したい、または Ultra で 4K にアップスケールしたい - 同じ API で Veo 3.1 の動画と Nano Banana の画像も作りたい - 無料の Google アカウントで、10秒までの Omni 1.2 を使いたい 次のような場合は Google Vids API を選びます。 - CAPTCHA も CAPTCHA プロバイダーも使いたくない - 720p と同じ料金で 1080p にしたい(延長や編集をする動画は[作業する解像度](#vids-resolution)を参照) - 動画をまたいで見た目と声を保つ、声付きのアバターを1本に最大3体使いたい - Ultra $199.99 で1秒あたり最安にしたい:15秒の動画で1秒 $0.02、Flow では $0.032 - Flow クレジットを使い切ったあとも Omni 1.2 の動画を作りたい(Vids には別の利用枠があります) または両方を使います。同じ Google アカウントをそれぞれの API に接続して、ジョブを向いている方に送れば、2つの[利用枠を合わせて使えます](#price-per-video)。 ### Claude Code、Cursor、Gemini CLI から使う どちらの API にも、useapi.net の API トークンで動くホスト型の MCP サーバーがあり、インストールするものはありません。Claude Code ではそれぞれ1行で追加できます。 ```bash claude mcp add --transport http useapi-google-vids https://api.useapi.net/v1/google-vids/mcp --header "Authorization: Bearer YOUR_API_TOKEN" claude mcp add --transport http useapi-google-flow https://api.useapi.net/v1/google-flow/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` Cursor や Gemini CLI では、MCP の設定に同じ URL と同じ `Authorization` ヘッダーを追加します。 - [Google Vids MCP サーバー](/docs/api-google-vids-v1/mcp)は、Omni 1.2 の動画を直接作ります。`vids_create_video` と `vids_edit_video` は最大15秒、`vids_extend_video` は24秒以下の動画に1回最大10秒です。 - [Google Flow MCP サーバー](/docs/api-google-flow-v1/mcp)は、Omni 1.2 のエンドポイントを直接呼ばず、Google Flow Agent とやり取りします。アシスタントが Agent とチャットし、Agent が通常の Flow の料金で画像や動画を作ります。Claude Code や Codex から Omni 1.2 を直接呼ぶには、[omni-flash-video エージェントスキル](https://github.com/useapi/google-flow-api/tree/main/skills/omni-flash-video)を追加します。 - どちらのリポジトリでも、サーバーを Claude Code のプラグインや Gemini CLI の拡張機能としてインストールできます:[google-flow-api](https://github.com/useapi/google-flow-api#use-with-claude-code)、[google-vids-api](https://github.com/useapi/google-vids-api#use-with-claude-code)。 ### よくある質問 #### Gemini Omni 1.2 Flash の API はありますか? useapi.net を使えば、あります。Google AI のプランで、Gemini Omni 1.2 Flash を [Google Flow API](/docs/api-google-flow-v1)(`model: "omni-flash-1.2"`)と [Google Vids API](/docs/api-google-vids-v1) から動かせ、Gemini API キーは不要です。料金は Ultra $199.99 の Vids 利用枠で1秒 $0.02 からで、Google の [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) では1秒約 $0.07 です(2026年11月時点)。Flow では参照画像かキャラクターがある動画に最大5つの声を使えますが、Google の API では音声の参照は[許可リスト制](https://cloud.google.com/blog/products/ai-machine-learning/gemini-omni-1-2-flash-generally-available)です。 #### Omni 1.2 Flash の料金は動画1本いくらですか? useapi.net を使えば、Google AI Ultra $199.99 で15秒の Omni 1.2 Flash 動画1本は、プランの Vids 利用枠の $0.30 分、または Flow クレジットの $0.48 分です。Google の Gemini API では 720p で $1.04 です(2026年11月時点)。Vids では 1080p も同じ秒数を使うので15秒の 1080p 動画も $0.30 で、Gemini API では $1.56 かかります。全プランは[料金表](#price-per-video)にあります。 #### Gemini Omni 1.2 Flash を無料で使える API はありますか? useapi.net を使えば、Google Flow API で使えます。無料の Google アカウントでも、[1日50の Flow クレジット](https://support.google.com/flow/answer/16526234?hl=ja)で10秒以下の Omni 1.2 Flash 動画を作れます。720p の10秒なら1日1本、360p なら5本です。Google の Gemini API で Omni 1.2 Flash を使えるのは有料枠だけです(2026年11月時点)。もっと長い動画や Omni 1.2 での延長には、有料の Google AI プランが必要です。 #### Omni 1.2 Flash の動画は何秒まで作れますか? useapi.net を使えば、Google Flow でも Google Vids でも、1回の呼び出しで3〜15秒の動画を作れます(2026年11月時点)。延長は1回3〜10秒を追加して動画全体を返します。Flow では40秒弱まで延ばせて、延長ごとに新しい声も使えます。Vids は24秒以下の動画を延長できるので、約34秒までです。上の[30秒のシーン](#flow-walkthrough)は、この方法で3回の呼び出しで作りました。 #### Omni 1.2 Flash と Veo 3.1、どちらを使うべきですか? useapi.net を使えば、1つのプランで両方を同じ Google Flow API から使えます。Ultra $199.99 では、8秒・720p の動画が Omni 1.2 Flash で $0.19、Veo 3.1 Fast で $0.08 です。Google 自身の API ではそれぞれ $0.56 と $0.80 です(2026年11月時点)。8秒より長い動画、自分で選ぶ最大5つの声、新しい声での延長には Omni 1.2 Flash を、最も安い8秒の動画には Veo 3.1 Fast を選びます。Veo の全料金は [Veo 3.1 API の料金比較](/docs/articles/veo-3-1-api-pricing)(英語)にあります。 ### 出典 - Google Cloud、[Gemini Omni 1.2 Flash is generally available](https://cloud.google.com/blog/products/ai-machine-learning/gemini-omni-1-2-flash-generally-available)、2026年11月5日 - Google Workspace Updates、[Gemini Omni 1.2 Flash now in Vids](https://workspaceupdates.googleblog.com/2026/11/gemini-omni-12-flash-now-in-vids-with-15second-generations-and-improved-quality.html)、2026年11月5日 - Google、[Gemini API の料金](https://ai.google.dev/gemini-api/docs/pricing)、2026年11月6日閲覧 - Google Cloud、[Agent Platform の料金](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing)(Veo 3.1)、2026年11月6日閲覧 - Google、[Google AI のプラン](https://gemini.google/subscriptions/)、[Flow クレジット](https://support.google.com/flow/answer/16526234?hl=ja)、[Google Vids の Gemini](https://support.google.com/docs/answer/15609411?hl=ja)、2026年11月閲覧 - useapi.net のリリース記事(英語):[Google Flow: Omni 1.2 Flash, 15-Second Videos, and Extend with Voices](/blog/261106)、[Google Vids: Omni 1.2 Flash, 15-Second Videos and 15-Second Edits](/blog/261106v)、2026年11月6日 ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/gemini-omni-1-2-flash-api-pt === Document URL: https://useapi.net/docs/articles/gemini-omni-1-2-flash-api-pt --- layout: default title: "Como usar a API do Gemini Omni 1.2 Flash: vídeos de 15 segundos no Google Flow e no Google Vids" seo_title: "API do Gemini Omni 1.2 Flash: vídeos de 15 s e preço" description: "API do Gemini Omni 1.2 Flash pela useapi.net: vídeos de 3 a 15 segundos com vozes no Google Flow e no Vids, US$ 0,30 por 15 s no Ultra US$ 199,99 contra US$ 1,04 na Gemini API." image: https://media.useapi.net/articles/2026-11-06-gemini-omni-1-2-flash-api-id/261106-gemini-omni-1-2-flash-api-cover.jpg keywords: [Gemini Omni 1.2 Flash API, API Gemini Omni 1.2 Flash, Omni 1.2 Flash API, gemini omni 1.2 api, omni-flash-1.2, Omni Flash 15 segundos, Gemini Omni API, Gemini Omni Flash API, preço Omni 1.2 Flash, Omni 1.2 Flash grátis, alternativa ao Veo, alternativa ao Veo 3.1, Google Flow API, Google Vids API, estender vídeo, API de edição de vídeo, vídeo com IA com vozes, Google AI Ultra, sem chave da Gemini API, tutorial, curl, Omni 1.2 Flash tutorial] parent: Articles nav_exclude: true lang: pt-BR date: 2026-11-06 last_modified: 2026-11-11 nav_order: 908 repo: https://github.com/useapi/google-flow-api translation_key: gemini-omni-1-2-flash --- ## Como usar a API do Gemini Omni 1.2 Flash: vídeos de 15 segundos no Google Flow e no Google Vids {: .no_toc #how-to-use-the-gemini-omni-12-flash-api-15-second-videos-in-google-flow-and-google-vids } 7 min de leitura • 6 de novembro de 2026 A useapi.net é uma API de terceiros. Não tem afiliação com o Google nem é endossada por ele. ## Sumário {: .no_toc .text-delta #table-of-contents } ### Introdução O Gemini Omni 1.2 Flash, que o Google lançou em 5 de novembro de 2026, gera vídeos de 3 a 15 segundos com som e falas, e a useapi.net roda esse modelo na sua [assinatura do Google AI](https://gemini.google/subscriptions/) por duas APIs REST: a [Google Flow API](/docs/api-google-flow-v1) e a [Google Vids API](/docs/api-google-vids-v1). No Google AI Ultra $199,99, um vídeo de 15 segundos gasta $0,30 da cota mensal do Vids do plano ou $0,48 dos créditos do Flow, contra $1,04 por 15 segundos em 720p na [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) do próprio Google (em novembro de 2026). Você não precisa de chave da Gemini API nem de projeto no Google Cloud. O que há de novo na 1.2, segundo o [anúncio](https://cloud.google.com/blog/products/ai-machine-learning/gemini-omni-1-2-flash-generally-available) do Google: clipes de até 15 segundos em vez de 10, mais fidelidade às referências e sincronia labial mais clara. No mesmo dia, o Google [passou o Google Vids para ele](https://workspaceupdates.googleblog.com/2026/11/gemini-omni-12-flash-now-in-vids-with-15second-generations-and-improved-quality.html). Este guia compara os dois caminhos e depois mostra uma cena real em cada um: uma cena de 30 segundos no Google Flow, feita em três chamadas e com duas vozes, e uma cena de 15 segundos no Google Vids, com uma extensão e uma edição de 15 segundos. Toda requisição é a real e todo vídeo é o resultado real, tirado dos posts de lançamento [Google Flow: Omni 1.2 Flash](/blog/261106) e [Google Vids: Omni 1.2 Flash](/blog/261106v) (em inglês). Antes de começar, você precisa de: - um [token da API](/docs/start-here/setup-useapi) da useapi.net - uma conta Google conectada com [Setup Google Flow](/docs/start-here/setup-google-flow), [Setup Google Vids](/docs/start-here/setup-google-vids) ou os dois. Uma mesma conta Google pode ser conectada às duas APIs, e cada uma mantém a sua própria cota. ### Google Flow ou Google Vids: o Omni 1.2 Flash em resumo | | [Google Flow API](/docs/api-google-flow-v1) | [Google Vids API](/docs/api-google-vids-v1) | |---|---|---| | Como escolher o Omni 1.2 | `model: "omni-flash-1.2"` (Omni 1.1 Flash e Veo 3.1 são outros valores) | Sem campo `model`: o Vids tem um só modelo de vídeo, o Omni 1.2 desde a implantação do Google a partir de 5 de novembro | | Duração | 3 a 15 segundos (3 a 10 com quadro inicial e final) | 3 a 15 segundos | | Resolução | 360p ou 720p, [upscale](/docs/api-google-flow-v1/post-google-flow-videos-upscale) para 1080p, ou 4K no Ultra | 720p ou 1080p pelo mesmo preço, [upscale](/docs/api-google-vids-v1/post-google-vids-videos-upscale) para 1080p em clipes de até 20 segundos | | Entradas | Texto, um quadro inicial, quadros inicial e final, até 10 imagens de referência, [personagens](/docs/api-google-flow-v1/get-google-flow-characters) salvos, 1 a 4 vídeos por requisição | Texto, uma imagem inicial ou até 3 referências que misturam imagens e [avatares](/docs/api-google-vids-v1/post-google-vids-avatars) | | Vozes | Até 5 [vozes](/docs/api-google-flow-v1/get-google-flow-voices) por vídeo quando ele tem imagem de referência ou personagem, até 3 por extensão. 30 vozes prontas ou a sua própria | Cada avatar fala em uma de 30 [vozes](/docs/api-google-vids-v1/get-google-vids-voices), até 3 avatares por vídeo | | [Estender](/docs/api-google-flow-v1/post-google-flow-videos-extend) | 3 a 10 segundos por chamada, com vozes e referências próprias, até pouco menos de 40 segundos, planos pagos | [3 a 10 segundos por chamada](/docs/api-google-vids-v1/post-google-vids-videos-extend) em clipes de até 24 segundos, até cerca de 34 segundos | | Editar por prompt | [Até 15 segundos](/docs/api-google-flow-v1/post-google-flow-videos#video-reference-omni-11-flash-v2v-edit) de um clipe gerado ou enviado | [Até 15 segundos](/docs/api-google-vids-v1/post-google-vids-videos-edit) de um clipe feito pelo Google | | O que gasta | Créditos do Flow: em 720p, 3 por segundo até 10 segundos e 6 por segundo acima disso, em 360p, 1 e 2 | Segundos da cota mensal do Vids, separada dos créditos do Flow | | Conta Google gratuita | Vídeos de até 10 segundos com 50 créditos do Flow por dia | Nenhum segundo de vídeo do Vids nos nossos testes | | Captcha | O Google pede um captcha em todo vídeo do Flow. A API resolve para você: 300 grátis, depois por um [provedor de captcha](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers) em que você se cadastra, a cerca de $0,80 a $3,00 por 1.000 | Nenhum | ### Preço por vídeo Quanto custa um vídeo Omni 1.2 Flash de 15 segundos na [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) do próprio Google e em cada assinatura do Google AI (em novembro de 2026). Cada assinatura vem com um número mensal de créditos do Flow e, à parte, de segundos de vídeo do Vids, então um vídeo custa a sua parte da assinatura. | Omni 1.2 Flash, 15 s | [API oficial](https://ai.google.dev/gemini-api/docs/pricing) | Ultra $199,99 (25.000 cr, 10.000 s) | Ultra $99,99 (10.000 cr, 2.500 s) | Pro $19,99 (1.000 cr, 500 s) | Plus $4,99 (200 cr, 60 s) | |---|---|---|---|---|---| | Google Flow (720p) | $1,04 (cerca de $0,07/s) | $0,48 / 60 cr (416 vídeos/mês) | $0,60 / 60 cr (166 vídeos/mês) | $1,20 / 60 cr (16 vídeos/mês) | $1,50 / 60 cr (3 vídeos/mês) | | Google Flow (360p) | $0,35 ($0,023/s) | $0,16 / 20 cr (1.250 vídeos/mês) | $0,20 / 20 cr (500 vídeos/mês) | $0,40 / 20 cr (50 vídeos/mês) | $0,50 / 20 cr (10 vídeos/mês) | | Google Vids (720p ou 1080p) | $1,04 em 720p ($1,56 em 1080p) | $0,30 / 15 s (666 vídeos/mês) | $0,60 / 15 s (166 vídeos/mês) | $0,60 / 15 s (33 vídeos/mês) | $1,25 / 15 s (4 vídeos/mês) | - A economia cresce com o plano. No Plus, e no Pro dentro do Flow, um vídeo de 15 segundos em 720p custa mais que na Gemini API, enquanto no Ultra $199,99 ele custa menos da metade no Flow e menos de um terço no Vids. - O Flow cobra o dobro por cada segundo acima de 10, então vídeos mais curtos custam menos por segundo lá: um vídeo de 10 segundos em 720p gasta 30 créditos, $0,24 no Ultra $199,99, contra $0,70 na Gemini API. A tabela completa do Flow, com todos os modelos, está na [visão geral da Google Flow API](/docs/api-google-flow-v1#pricing), e a do Vids, com imagens e avatares, na [visão geral da Google Vids API](/docs/api-google-vids-v1#pricing). - Uma extensão gasta só os segundos que acrescenta, nas duas APIs. Uma edição no Vids gasta no máximo os segundos que edita (nos nossos testes, uma edição de 15 segundos gastou 10), e uma edição no Flow custa o mesmo que um vídeo com a duração editada. - Os créditos do Flow e os segundos do Vids são duas cotas separadas do mesmo plano. No Ultra $199,99, uma conta Google conectada às duas APIs gera por mês cerca de 416 vídeos de quinze segundos em 720p no Flow e 666 no Vids, cerca de 1.082 no total. - Os preços dos planos são os preços do Google nos EUA. Os segundos do Vids por plano vêm da página [Gemini no Google Vids](https://support.google.com/docs/answer/15609411?hl=pt-BR) do Google e batem com os nossos testes no Ultra $199,99. ### Omni 1.2 Flash no Google Flow: uma cena de 30 segundos em três chamadas Um vídeo de 10 segundos, depois duas extensões de 10 segundos, cada uma com a sua voz. O passo 1 funciona em uma conta Google gratuita. Os passos 2 e 3 (estender) exigem um plano Google AI pago. Toda chamada roda como um job assíncrono: passe `async: true` e o POST responde na hora com um `jobid`. Consulte [GET /jobs/`jobid`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid) até `status` ficar `completed`, ou passe `replyUrl` para receber o job pronto no seu webhook: ```bash curl --location 'https://api.useapi.net/v1/google-flow/jobs/<jobid>' --header 'Authorization: Bearer YOUR_API_TOKEN' ``` O vídeo pronto fica em `response.media[0].videoUrl`, um link que vale por cerca de 6 horas, e o passo seguinte usa o `response.media[0].mediaGenerationId` do job pronto. Se você conectou várias contas Google, a API escolhe uma que já tenha o Omni 1.2 (o Google está liberando o modelo ao longo de vários dias a partir de 5 de novembro). Passe `email` para escolher uma. #### Passo 1: os primeiros 10 segundos {: .no_toc #step-1-the-first-10-seconds } [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) com `model: "omni-flash-1.2"` e `duration: 10`. O Google respondeu em 56 segundos. Em 720p, um vídeo de 10 segundos gasta 30 créditos. ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "model": "omni-flash-1.2", "duration": 10, "prompt": "Cinematic night, a narrow rainy alley in Tokyo glowing with neon signs reflected in the puddles. A street magician in a long dark coat faces the camera, fans out a deck of cards that glow faintly gold, and says with a grin: \"Pick a card. Any card.\" A sudden gust snatches one glowing card from his hand and it flutters away down the alley. Handheld camera, shallow depth of field, rain drops catching the light.", "async": true }' ``` <video poster="https://media.useapi.net/blog/2026-11-06-261106/261106-google-flow-omni-1-2-magician-first-10s-poster.jpg" src="https://media.useapi.net/blog/2026-11-06-261106/261106-google-flow-omni-1-2-magician-first-10s.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> <details markdown="block"> <summary>O job pronto, de <a href="/docs/api-google-flow-v1/get-google-flow-jobs-jobid">GET /jobs/<code>jobid</code></a> (resumido)</summary> ```json { "jobid": "j1106021223539251070v-u12345-email:user@example.com-bot:google-flow", "type": "video", "status": "completed", "response": { "media": [ { "video": { "generatedVideo": { "model": "macaron_cookie_t2v_10s", "aspectRatio": "VIDEO_ASPECT_RATIO_LANDSCAPE" }, "dimensions": { "length": "10s" } }, "mediaGenerationId": "user:12345-email:…-video:b08556b9-…", "videoUrl": "https://flow-content.google/video/b08556b9-…?Expires=…" } ], "remainingCredits": 877 } } ``` </details> #### Passo 2: estender por 10 segundos, com uma voz {: .no_toc #step-2-extend-by-10-seconds-with-a-voice } [POST /videos/extend](/docs/api-google-flow-v1/post-google-flow-videos-extend) com o `mediaGenerationId` do primeiro vídeo, `duration: 10` e a voz pronta Charon como `referenceAudio_1`. O prompt coloca a voz onde o mágico fala, com a menção inline `@referenceAudio_1`. O extend usa o Omni 1.2 por padrão, então não precisa de `model`. A resposta é um único clipe de 20 segundos, os 10 primeiros sem mudança mais os 10 novos, depois de 2 minutos e 20 segundos, por 30 créditos. ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos/extend' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "mediaGenerationId": "user:12345-email:…-video:b08556b9-…", "duration": 10, "referenceAudio_1": "Charon", "prompt": "The magician runs after the glowing card through the rain, past a ramen stall and under paper lanterns, laughing and calling out in a deep voice @referenceAudio_1: \"Come back here! You are the ace of hearts!\" The camera follows him close behind.", "async": true }' ``` #### Passo 3: mais 10 segundos, uma segunda voz {: .no_toc #step-3-10-more-seconds-a-second-voice } A mesma chamada sobre o clipe de 20 segundos, com a voz Aoede para a mulher no café. O resultado é a cena inteira, com 30 segundos, depois de mais 2 minutos e 30 créditos. ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos/extend' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "mediaGenerationId": "user:12345-email:…-video:113384cd-…", "duration": 10, "referenceAudio_1": "Aoede", "prompt": "The glowing card drifts through the open door of a tiny warm café and lands on a table. A young woman in a yellow raincoat picks it up, looks at the out-of-breath magician in the doorway, and says with a smile @referenceAudio_1: \"Is this your card?\" He laughs. Warm light, rain outside the window.", "async": true }' ``` <video poster="https://media.useapi.net/articles/2026-06-15-omni-flash-bash/261106-google-flow-omni-1-2-magician-extended-30s-web-poster.jpg" src="https://media.useapi.net/articles/2026-06-15-omni-flash-bash/261106-google-flow-omni-1-2-magician-extended-30s-web.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> <details markdown="block"> <summary>O job pronto (resumido)</summary> ```json { "jobid": "j1106021547955542178v-u12345-email:user@example.com-bot:google-flow", "type": "video", "status": "completed", "response": { "media": [ { "video": { "generatedVideo": { "model": "macaron_cookie_extend_10s" }, "dimensions": { "length": "30s" } }, "mediaGenerationId": "user:12345-email:…-video:db0201df-…", "videoUrl": "https://flow-content.google/video/db0201df-…?Expires=…" } ], "remainingCredits": 817 } } ``` </details> O vídeo acima foi recodificado para a web na resolução original de 1280×720. A cena inteira gastou 90 créditos, cerca de $0,72 no Ultra $199,99, contra cerca de $2,10 por 30 segundos no preço de 720p da Gemini API (em novembro de 2026). O Google só estende vídeos com menos de 30 segundos, então esta cena não pode crescer mais: um quarto extend responde `400` na hora, antes de qualquer captcha ou crédito. Um clipe de 25 segundos ainda aceita mais 10 e termina em 35. [`omni-extend/`](https://github.com/useapi/google-flow-api/tree/main/omni-extend) no GitHub gera esta cena a partir de um único `story.json`, em Node.js ou Python, e [`omni-flash/`](https://github.com/useapi/google-flow-api/tree/main/omni-flash) gera vídeos Omni Flash em lote a partir de uma lista de prompts. O [tutorial do Omni Flash](/docs/articles/omni-flash-bash) (em inglês) cobre imagens de referência, personagens, quadros inicial e final e edições. ### Omni 1.2 Flash no Google Vids: 15 segundos, uma extensão e uma edição O Vids tem um só modelo de vídeo, que o Google passou para o Omni 1.2 em uma implantação de alguns dias a partir de 5 de novembro, então não há `model` para definir. As requisições levam um corpo JSON, e toda chamada aqui roda como um job assíncrono: consulte [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid) ou passe `replyUrl`, depois baixe o clipe com [GET /media/`mediaId`](/docs/api-google-vids-v1/get-google-vids-media-mediaId) em até 24 horas. O passo seguinte usa o `result.mediaId` do job pronto. O Vids não pede captcha. ```bash curl --location 'https://api.useapi.net/v1/google-vids/jobs/<jobid>' --header 'Authorization: Bearer YOUR_API_TOKEN' ``` #### Passo 1: um vídeo de 15 segundos a partir de um prompt {: .no_toc #step-1-a-15-second-video-from-one-prompt } [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) com `duration: 15`. O Google respondeu em cerca de 60 segundos com um vídeo de 1280×720, e as duas falas saem exatamente como escritas. Gastou 15 segundos da cota. ```bash curl --location 'https://api.useapi.net/v1/google-vids/videos' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "prompt": "Cinematic single continuous shot, 15 seconds, 16:9. Golden hour on a Tokyo rooftop garden, city skyline glowing behind. A young chef in a crisp white apron finishes plating a steaming bowl of ramen, steam curling in the warm light. She looks up into the camera and says with a confident smile: \"Fifteen seconds. One prompt. No editing.\" She slides the bowl toward the camera as it slowly pushes in, wind chimes ringing softly and city traffic humming far below. She laughs and adds: \"Now that'\''s fast food.\"", "duration": 15, "aspectRatio": "landscape", "resolution": "720p", "async": true }' ``` <video poster="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-15s-poster.jpg" src="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-15s.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> <details markdown="block"> <summary>O job pronto, de <a href="/docs/api-google-vids-v1/get-google-vids-jobs-jobid">GET /jobs/<code>jobid</code></a> (resumido)</summary> ```json { "status": "completed", "result": { "mediaId": "user:12345-user@example.com-video:eyJ1Ijoi…", "width": 1280, "height": 720, "duration": 15, "resolution": "720p", "aspectRatio": "landscape", "model": "/flix/generate_videos_omni_t2v_psq/v1", "quota": { "video": { "limit": 500, "left": 485, "resetAt": "2026-12-01T08:00:00.000Z" } } } } ``` </details> `quota` mostra quanto a conta ainda tem dos seus segundos mensais de vídeo e quando eles renovam. Esta conta de teste está no Google AI Pro, daí o limite de 500 segundos. Os preços desta página usam o Ultra $199,99. #### Passo 2: estender por 10 segundos {: .no_toc #step-2-extend-it-by-10-seconds } [POST /videos/extend](/docs/api-google-vids-v1/post-google-vids-videos-extend) com o `mediaId` do primeiro vídeo. O resultado é um único clipe, os 15 segundos mais 10 novos, com 25 segundos, depois de cerca de 100 segundos. Um amigo entra, prova o ramen, e as duas falas novas são ditas. ```bash curl --location 'https://api.useapi.net/v1/google-vids/videos/extend' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "mediaId": "user:12345-user@example.com-video:eyJ1Ijoi…", "prompt": "Same shot continues on the Tokyo rooftop at dusk, the city lights now switching on. A friend in a denim jacket walks into frame, sits at the table and takes a first slurp of the ramen, eyes widening. He says: \"Wait, you made this in fifteen seconds?\" The chef folds her arms and grins: \"Fifteen more, and I'\''ll make dessert.\" They both laugh as string lights flicker on above them and soft city ambience fills the air.", "duration": 10, "async": true }' ``` <video poster="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-extend-25s-poster.jpg" src="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-extend-25s.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> Também no YouTube: [Gemini Omni 1.2 Flash in Google Vids: 15 seconds from one prompt, extended to 25](https://www.youtube.com/watch?v=eJ3js18XCBM). A API aceita de 3 a 10 segundos por chamada de extend e responde `400` a uma `duration` maior: o Google acrescenta no máximo 10 segundos, mas conta todos os segundos pedidos. (Este clipe veio de um teste anterior com `duration: 15`.) A mesma requisição com `duration: 10` devolve o mesmo clipe de 25 segundos e gasta 10 segundos. O Vids estende clipes de até 24 segundos, então este clipe de 25 segundos já está no limite. Para chegar ao clipe mais longo, cerca de 34 segundos, estenda por 10 um clipe de 24 segundos ou menos. #### Passo 3: editar os 15 segundos inteiros {: .no_toc #step-3-edit-all-15-seconds } [POST /videos/edit](/docs/api-google-vids-v1/post-google-vids-videos-edit) sobre o primeiro vídeo, com `duration: 15`. Com o Omni 1.1, uma edição devolvia no máximo 10 segundos. Agora o clipe inteiro de 15 segundos voltou editado, quadro a quadro, depois de cerca de 140 segundos. ```bash curl --location 'https://api.useapi.net/v1/google-vids/videos/edit' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "video": "user:12345-user@example.com-video:eyJ1Ijoi…", "prompt": "Make it a snowy winter evening: snow falling gently over the rooftop and the city, the chef wearing a red knit scarf. Keep everything else the same.", "duration": 15, "async": true }' ``` <video poster="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-edit-snow-15s-poster.jpg" src="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-edit-snow-15s.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> O Vids edita clipes feitos pelo Google, e o Google recusa vídeos enviados com `422`. Para um clipe único, gere em 1080p, que gasta a mesma cota que 720p. Para um clipe que você vai estender, trabalhe em 720p e passe para 1080p uma vez só, no fim: cada extend em 1080p processa o clipe inteiro de novo e deixa os segundos anteriores nítidos demais ([veja a comparação](/blog/261106v#720p-or-1080p-what-a-1080p-extend-does)). Finalize um clipe de até 20 segundos com um [upscale](/docs/api-google-vids-v1/post-google-vids-videos-upscale) (ele gasta de novo os segundos do clipe), e, para um clipe de 21 a 34 segundos, defina `resolution: "1080p"` só no último extend. O repositório [google-vids-api](https://github.com/useapi/google-vids-api) no GitHub tem exemplos do Vids prontos para rodar em Node.js e Python, inclusive avatares com voz, e o [tutorial de influenciador com IA](/docs/articles/google-vids-influencer-avatars-pt) monta um clipe com dois avatares falantes. ### Qual usar Escolha a Google Flow API quando você quiser: - rascunhos em 360p a um terço do preço de 720p, ou até 4 vídeos por requisição - quadro inicial e final, até 10 imagens de referência ou personagens salvos - escolher as vozes você mesmo: até 5 por vídeo com imagem de referência ou personagem e até 3 por extensão, entre 30 vozes prontas ou a sua própria - editar um vídeo enviado, ou fazer upscale para 4K no Ultra - vídeos Veo 3.1 e imagens Nano Banana na mesma API - Omni 1.2 em uma conta Google gratuita, até 10 segundos Escolha a Google Vids API quando você quiser: - nenhum captcha e nenhum provedor de captcha - 1080p pelo mesmo preço de 720p (para clipes que você vai estender ou editar, veja [em que resolução trabalhar](#vids-resolution)) - avatares com voz que mantêm a aparência e a voz de um vídeo para o outro, até 3 em um vídeo - o menor preço por segundo no Ultra $199,99, $0,02 contra $0,032 para um vídeo de 15 segundos no Flow - mais vídeos Omni 1.2 depois que os créditos do Flow acabam, já que o Vids tem a sua própria cota Ou use as duas: conecte a mesma conta Google a cada API e mande os jobs para onde fizerem mais sentido, já que as duas [cotas se somam](#price-per-video). ### Use no Claude Code, no Cursor ou no Gemini CLI As duas APIs têm um servidor MCP hospedado que roda com o seu token da API da useapi.net, sem nada para instalar. No Claude Code, cada uma é uma linha: ```bash claude mcp add --transport http useapi-google-vids https://api.useapi.net/v1/google-vids/mcp --header "Authorization: Bearer YOUR_API_TOKEN" claude mcp add --transport http useapi-google-flow https://api.useapi.net/v1/google-flow/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` No Cursor ou no Gemini CLI, adicione a mesma URL com o mesmo cabeçalho `Authorization` nas configurações de MCP. - O [servidor MCP do Google Vids](/docs/api-google-vids-v1/mcp) gera clipes Omni 1.2 diretamente: `vids_create_video` e `vids_edit_video` aceitam até 15 segundos, e `vids_extend_video` até 10 por chamada em clipes de até 24 segundos. - O [servidor MCP do Google Flow](/docs/api-google-flow-v1/mcp) conversa com o Google Flow Agent, não com os endpoints do Omni 1.2 diretamente: o seu assistente conversa com o Agent, que gera imagens e vídeos pelo preço normal do Flow. Para chamadas diretas ao Omni 1.2 pelo Claude Code ou pelo Codex, adicione a [agent skill omni-flash-video](https://github.com/useapi/google-flow-api/tree/main/skills/omni-flash-video). - Os dois repositórios também instalam o servidor como plugin do Claude Code ou extensão do Gemini CLI: [google-flow-api](https://github.com/useapi/google-flow-api#use-with-claude-code) e [google-vids-api](https://github.com/useapi/google-vids-api#use-with-claude-code). ### Perguntas #### Existe API do Gemini Omni 1.2 Flash? Com a useapi.net, sim: ela roda o Gemini Omni 1.2 Flash na sua assinatura do Google AI, pela [Google Flow API](/docs/api-google-flow-v1) (`model: "omni-flash-1.2"`) e pela [Google Vids API](/docs/api-google-vids-v1), sem chave da Gemini API. Custa a partir de $0,02 por segundo da cota do Vids do Ultra $199,99, contra cerca de $0,07 por segundo na [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) do Google, e o Flow aceita até 5 vozes por vídeo com imagem de referência ou personagem, enquanto a API do Google [libera referências de áudio só para uma lista de permitidos](https://cloud.google.com/blog/products/ai-machine-learning/gemini-omni-1-2-flash-generally-available) (em novembro de 2026). #### Quanto custa um vídeo do Omni 1.2 Flash? Com a useapi.net no Google AI Ultra $199,99, um vídeo Omni 1.2 Flash de 15 segundos gasta $0,30 da cota do Vids do plano ou $0,48 dos créditos do Flow, contra $1,04 em 720p na Gemini API do Google (em novembro de 2026). No Vids, um vídeo de 15 segundos em 1080p também sai a $0,30, porque 1080p gasta os mesmos segundos, enquanto a Gemini API cobra $1,56. A [tabela de preços](#price-per-video) mostra todos os planos. #### Dá para usar o Gemini Omni 1.2 Flash de graça por API? Com a useapi.net, sim, na Google Flow API: uma conta Google gratuita gera vídeos Omni 1.2 Flash de até 10 segundos com os seus [50 créditos diários do Flow](https://support.google.com/flow/answer/16526234?hl=pt-BR), um vídeo de 10 segundos em 720p ou cinco em 360p por dia, enquanto a Gemini API do Google oferece o Omni 1.2 Flash só no nível pago (em novembro de 2026). Vídeos mais longos e extensões com o Omni 1.2 exigem um plano Google AI pago. #### Qual a duração máxima de um vídeo do Omni 1.2 Flash? Com a useapi.net, uma chamada gera de 3 a 15 segundos, tanto no Google Flow quanto no Google Vids, e o extend acrescenta de 3 a 10 segundos por chamada e devolve o clipe inteiro: até pouco menos de 40 segundos no Flow, com uma voz nova em cada extensão se você quiser, e cerca de 34 segundos no Vids, que estende clipes de até 24 segundos. A [cena de 30 segundos](#flow-walkthrough) acima foi feita assim, em três chamadas. #### Omni 1.2 Flash ou Veo 3.1: qual usar? Com a useapi.net você roda os dois na mesma Google Flow API, com um único plano: no Ultra $199,99, um vídeo Omni 1.2 Flash de 8 segundos em 720p sai a $0,19 e um Veo 3.1 Fast a $0,08, contra $0,56 e $0,80 nas APIs do próprio Google (em novembro de 2026). Escolha o Omni 1.2 Flash para clipes com mais de 8 segundos, até 5 vozes escolhidas por você e extensões com vozes novas, e o Veo 3.1 Fast para o clipe de 8 segundos mais barato. Todos os preços do Veo: [Veo 3.1 API pricing](/docs/articles/veo-3-1-api-pricing) (em inglês). ### Fontes - Google Cloud, [Gemini Omni 1.2 Flash is generally available](https://cloud.google.com/blog/products/ai-machine-learning/gemini-omni-1-2-flash-generally-available), 5 de novembro de 2026 - Google Workspace Updates, [Gemini Omni 1.2 Flash now in Vids](https://workspaceupdates.googleblog.com/2026/11/gemini-omni-12-flash-now-in-vids-with-15second-generations-and-improved-quality.html), 5 de novembro de 2026 - Google, [preços da Gemini API](https://ai.google.dev/gemini-api/docs/pricing), consultados em 6 de novembro de 2026 - Google Cloud, [preços da Agent Platform](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing) (Veo 3.1), consultados em 6 de novembro de 2026 - Google, [planos Google AI](https://gemini.google/subscriptions/), [créditos do Flow](https://support.google.com/flow/answer/16526234?hl=pt-BR) e [Gemini no Google Vids](https://support.google.com/docs/answer/15609411?hl=pt-BR), consultados em novembro de 2026 - Posts de lançamento da useapi.net: [Google Flow: Omni 1.2 Flash, 15-Second Videos, and Extend with Voices](/blog/261106) e [Google Vids: Omni 1.2 Flash, 15-Second Videos and 15-Second Edits](/blog/261106v), 6 de novembro de 2026 ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/gemini-omni-1-2-flash-api-th === Document URL: https://useapi.net/docs/articles/gemini-omni-1-2-flash-api-th --- layout: default title: "วิธีใช้ Gemini Omni 1.2 Flash API: วิดีโอ 15 วินาทีใน Google Flow และ Google Vids" seo_title: "Gemini Omni 1.2 Flash API: วิดีโอ 15 วินาทีและราคา" description: "ใช้ Gemini Omni 1.2 Flash API ผ่าน useapi.net: วิดีโอ 3 ถึง 15 วินาทีพร้อมเสียงพูดใน Google Flow และ Vids คลิป 15 วิราคา $0.30 บน Ultra $199.99 เทียบกับ $1.04 บน Gemini API" image: https://media.useapi.net/articles/2026-11-06-gemini-omni-1-2-flash-api-id/261106-gemini-omni-1-2-flash-api-cover.jpg keywords: [Gemini Omni 1.2 Flash API, Omni 1.2 Flash API, gemini omni 1.2 api, omni-flash-1.2, Omni Flash 15 วินาที, Gemini Omni API, Gemini Omni Flash API, Omni 1.2 Flash ราคา, วิธีใช้ Omni 1.2 Flash, Omni 1.2 Flash ฟรี, ทางเลือกแทน Veo, Veo 3.1 alternative, Google Flow API, Google Vids API, ต่อความยาววิดีโอ, API แก้ไขวิดีโอ, API สร้างวิดีโอ, วิดีโอ AI พร้อมเสียงพูด, Google AI Ultra, ไม่ต้องใช้ Gemini API key, สอนใช้งาน, curl] parent: Articles nav_exclude: true lang: th date: 2026-11-06 last_modified: 2026-11-11 nav_order: 908 repo: https://github.com/useapi/google-flow-api translation_key: gemini-omni-1-2-flash --- ## วิธีใช้ Gemini Omni 1.2 Flash API: วิดีโอ 15 วินาทีใน Google Flow และ Google Vids {: .no_toc #how-to-use-the-gemini-omni-12-flash-api-15-second-videos-in-google-flow-and-google-vids } อ่าน 7 นาที • 6 พฤศจิกายน 2026 useapi.net เป็น API ของบุคคลที่สาม (third-party) ไม่มีส่วนเกี่ยวข้องกับ Google และไม่ได้รับการรับรองจาก Google ## สารบัญ {: .no_toc .text-delta #table-of-contents } ### บทนำ Gemini Omni 1.2 Flash ที่ Google เปิดตัวเมื่อ 5 พฤศจิกายน 2026 สร้างวิดีโอยาว 3 ถึง 15 วินาทีพร้อมเสียงและบทพูด useapi.net รันโมเดลนี้บน[แพ็กเกจ Google AI](https://gemini.google/subscriptions/) ของคุณผ่าน REST API สองตัว คือ [Google Flow API](/docs/api-google-flow-v1) และ [Google Vids API](/docs/api-google-vids-v1) บน Google AI Ultra $199.99 วิดีโอ 15 วินาทีหนึ่งคลิปใช้โควตา Vids รายเดือนของแพ็กเกจไป $0.30 หรือใช้เครดิต Flow ไป $0.48 เทียบกับ $1.04 สำหรับ 15 วินาทีที่ 720p บน [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) ของ Google เอง (ข้อมูล ณ พฤศจิกายน 2026) ไม่ต้องใช้ Gemini API key และไม่ต้องมีโปรเจกต์ Google Cloud สิ่งที่ใหม่ในเวอร์ชัน 1.2 ตาม[ประกาศ](https://cloud.google.com/blog/products/ai-machine-learning/gemini-omni-1-2-flash-generally-available)ของ Google คือคลิปยาวได้ถึง 15 วินาทีจากเดิม 10 วินาที ทำตามภาพอ้างอิงได้ตรงขึ้น และขยับปากตรงกับเสียงชัดขึ้น และในวันเดียวกัน Google ก็[เปลี่ยน Google Vids มาใช้โมเดลนี้](https://workspaceupdates.googleblog.com/2026/11/gemini-omni-12-flash-now-in-vids-with-15second-generations-and-improved-quality.html) คู่มือนี้เทียบสองเส้นทางให้เห็นชัด ๆ แล้วพาทำฉากจริงหนึ่งฉากในแต่ละเส้นทาง ฉากแรกยาว 30 วินาทีใน Google Flow สร้างด้วยสามคำสั่ง มีสองเสียง ฉากที่สองยาว 15 วินาทีใน Google Vids พร้อมการต่อความยาวและการแก้ไขทั้ง 15 วินาที ทุกคำขอเป็นคำขอจริง และทุกวิดีโอเป็นผลลัพธ์จริงจากโพสต์เปิดตัว [Google Flow: Omni 1.2 Flash](/blog/261106) และ [Google Vids: Omni 1.2 Flash](/blog/261106v) ก่อนเริ่ม คุณต้องมี: - [API token](/docs/start-here/setup-useapi) ของ useapi.net - บัญชี Google ที่เชื่อมไว้แล้วผ่าน [Setup Google Flow](/docs/start-here/setup-google-flow), [Setup Google Vids](/docs/start-here/setup-google-vids) หรือทั้งสองอย่าง บัญชี Google เดียวเชื่อมกับ API ทั้งสองตัวได้ และแต่ละตัวมีโควตาแยกของตัวเอง ### Google Flow หรือ Google Vids: สรุป Omni 1.2 Flash | | [Google Flow API](/docs/api-google-flow-v1) | [Google Vids API](/docs/api-google-vids-v1) | |---|---|---| | วิธีเลือก Omni 1.2 | `model: "omni-flash-1.2"` (Omni 1.1 Flash และ Veo 3.1 เป็นค่าอื่น) | ไม่มีฟิลด์ `model` เพราะ Vids มีโมเดลวิดีโอเดียว คือ Omni 1.2 ตั้งแต่ Google เริ่มทยอยเปลี่ยนเมื่อ 5 พฤศจิกายน | | ความยาว | 3 ถึง 15 วินาที (3 ถึง 10 วินาทีเมื่อใช้เฟรมเริ่มและเฟรมจบ) | 3 ถึง 15 วินาที | | ความละเอียด | 360p หรือ 720p [อัปสเกล](/docs/api-google-flow-v1/post-google-flow-videos-upscale)เป็น 1080p ได้ หรือ 4K บน Ultra | 720p หรือ 1080p ในราคาเดียวกัน [อัปสเกล](/docs/api-google-vids-v1/post-google-vids-videos-upscale)เป็น 1080p ได้สำหรับคลิปยาวไม่เกิน 20 วินาที | | อินพุต | ข้อความ เฟรมเริ่ม เฟรมเริ่มและเฟรมจบ ภาพอ้างอิงสูงสุด 10 ภาพ [ตัวละคร](/docs/api-google-flow-v1/get-google-flow-characters)ที่บันทึกไว้ และวิดีโอ 1 ถึง 4 คลิปต่อคำขอ | ข้อความ ภาพเริ่มต้น หรือภาพอ้างอิงสูงสุด 3 รายการที่ผสมภาพกับ[อวตาร](/docs/api-google-vids-v1/post-google-vids-avatars)ได้ | | เสียงพูด | สูงสุด 5 [เสียง](/docs/api-google-flow-v1/get-google-flow-voices)ต่อวิดีโอเมื่อมีภาพอ้างอิงหรือตัวละคร และสูงสุด 3 เสียงต่อการต่อความยาวหนึ่งครั้ง เลือกจาก 30 เสียงในตัวหรือใช้เสียงของคุณเอง | อวตารแต่ละตัวพูดด้วย 1 ใน 30 [เสียง](/docs/api-google-vids-v1/get-google-vids-voices) และมีอวตารได้สูงสุด 3 ตัวต่อวิดีโอ | | [ต่อความยาว](/docs/api-google-flow-v1/post-google-flow-videos-extend) | ครั้งละ 3 ถึง 10 วินาที ใส่เสียงและภาพอ้างอิงของตัวเองได้ ยาวได้เกือบ 40 วินาที เฉพาะแพ็กเกจเสียเงิน | [ครั้งละ 3 ถึง 10 วินาที](/docs/api-google-vids-v1/post-google-vids-videos-extend) กับคลิปยาวไม่เกิน 24 วินาที ยาวได้ราว 34 วินาที | | แก้ไขด้วยพรอมต์ | [สูงสุด 15 วินาที](/docs/api-google-flow-v1/post-google-flow-videos#video-reference-omni-11-flash-v2v-edit) ของคลิปที่สร้างหรืออัปโหลด | [สูงสุด 15 วินาที](/docs/api-google-vids-v1/post-google-vids-videos-edit) ของคลิปที่ Google สร้าง | | ใช้อะไร | เครดิต Flow: ที่ 720p ใช้ 3 เครดิตต่อวินาทีจนถึง 10 วินาที และ 6 เครดิตต่อวินาทีหลังจากนั้น ที่ 360p ใช้ 1 และ 2 | วินาทีจากโควตา Vids รายเดือน แยกจากเครดิต Flow | | บัญชี Google ฟรี | วิดีโอยาวไม่เกิน 10 วินาที จากเครดิต Flow 50 เครดิตต่อวัน | ไม่มีวินาทีวิดีโอ Vids ในการทดสอบของเรา | | Captcha | Google ขอ captcha ทุกครั้งที่สร้างวิดีโอใน Flow ซึ่ง API แก้ให้ ฟรี 300 ครั้ง หลังจากนั้นใช้[ผู้ให้บริการ captcha](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers) ที่คุณสมัครเอง ราว $0.80 ถึง $3.00 ต่อ 1,000 ครั้ง | ไม่มี | ### ราคาต่อวิดีโอ ราคาของวิดีโอ Omni 1.2 Flash ยาว 15 วินาทีหนึ่งคลิป บน [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) ของ Google เอง และบนแพ็กเกจ Google AI แต่ละแพ็กเกจ (ข้อมูล ณ พฤศจิกายน 2026) แต่ละแพ็กเกจมีเครดิต Flow รายเดือน และมีวินาทีวิดีโอ Vids แยกต่างหาก วิดีโอหนึ่งคลิปจึงคิดตามสัดส่วนของแพ็กเกจ หัวตารางคือราคาแพ็กเกจต่อเดือน | Omni 1.2 Flash, 15 วิ | [API ทางการ](https://ai.google.dev/gemini-api/docs/pricing) | Ultra $199.99 (25,000 cr, 10,000 วิ) | Ultra $99.99 (10,000 cr, 2,500 วิ) | Pro $19.99 (1,000 cr, 500 วิ) | Plus $4.99 (200 cr, 60 วิ) | |---|---|---|---|---|---| | Google Flow (720p) | $1.04 (ราว $0.07/วิ) | $0.48 / 60 cr (416 คลิป/เดือน) | $0.60 / 60 cr (166 คลิป/เดือน) | $1.20 / 60 cr (16 คลิป/เดือน) | $1.50 / 60 cr (3 คลิป/เดือน) | | Google Flow (360p) | $0.35 ($0.023/วิ) | $0.16 / 20 cr (1,250 คลิป/เดือน) | $0.20 / 20 cr (500 คลิป/เดือน) | $0.40 / 20 cr (50 คลิป/เดือน) | $0.50 / 20 cr (10 คลิป/เดือน) | | Google Vids (720p หรือ 1080p) | $1.04 ที่ 720p ($1.56 ที่ 1080p) | $0.30 / 15 วิ (666 คลิป/เดือน) | $0.60 / 15 วิ (166 คลิป/เดือน) | $0.60 / 15 วิ (33 คลิป/เดือน) | $1.25 / 15 วิ (4 คลิป/เดือน) | - ยิ่งแพ็กเกจใหญ่ ยิ่งประหยัด บน Plus และบน Pro ใน Flow วิดีโอ 720p ยาว 15 วินาทีแพงกว่าบน Gemini API แต่บน Ultra $199.99 ราคาไม่ถึงครึ่งใน Flow และไม่ถึงหนึ่งในสามใน Vids - Flow คิดทุกวินาทีที่เกิน 10 วินาทีเป็นสองเท่า วิดีโอที่สั้นกว่าจึงถูกกว่าต่อวินาที วิดีโอ 720p ยาว 10 วินาทีใช้ 30 เครดิต หรือ $0.24 บน Ultra $199.99 เทียบกับ $0.70 บน Gemini API ตาราง Flow ฉบับเต็มทุกโมเดลอยู่ที่[หน้าภาพรวม Google Flow API](/docs/api-google-flow-v1#pricing) และตาราง Vids ที่รวมภาพและอวตารอยู่ที่[หน้าภาพรวม Google Vids API](/docs/api-google-vids-v1#pricing) - การต่อความยาวใช้เฉพาะวินาทีที่เพิ่มเข้าไป ทั้งสอง API การแก้ไขใน Vids ใช้วินาทีไม่เกินช่วงที่แก้ (ในการทดสอบของเรา การแก้ 15 วินาทีใช้ไป 10) ส่วนการแก้ไขใน Flow ราคาเท่ากับวิดีโอที่ยาวเท่าช่วงที่แก้ - เครดิต Flow และวินาที Vids เป็นโควตาสองก้อนแยกกันในแพ็กเกจเดียวกัน บน Ultra $199.99 บัญชี Google เดียวที่เชื่อมกับทั้งสอง API สร้างวิดีโอ 720p ยาว 15 วินาทีได้ราว 416 คลิปใน Flow และ 666 คลิปใน Vids ต่อเดือน รวมราว 1,082 คลิป - ราคาแพ็กเกจเป็นราคาสหรัฐฯ ของ Google จำนวนวินาที Vids ของแต่ละแพ็กเกจมาจากหน้า [Gemini ใน Google Vids](https://support.google.com/docs/answer/15609411?hl=th) ของ Google และตรงกับการทดสอบของเราบน Ultra $199.99 ### Omni 1.2 Flash ใน Google Flow: ฉาก 30 วินาทีด้วยสามคำสั่ง วิดีโอ 10 วินาที แล้วต่อความยาวอีกสองครั้ง ครั้งละ 10 วินาที แต่ละครั้งมีเสียงของตัวเอง ขั้นตอนที่ 1 ใช้บัญชี Google ฟรีได้ ส่วนขั้นตอนที่ 2 และ 3 (ต่อความยาว) ต้องใช้แพ็กเกจ Google AI แบบเสียเงิน ทุกคำสั่งทำงานเป็นงานแบบ async ส่ง `async: true` แล้ว POST จะตอบกลับด้วย `jobid` ทันที จากนั้นเรียก [GET /jobs/`jobid`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid) ซ้ำจนกว่า `status` จะเป็น `completed` หรือส่ง `replyUrl` เพื่อรับงานที่เสร็จแล้วทาง webhook ของคุณ: ```bash curl --location 'https://api.useapi.net/v1/google-flow/jobs/<jobid>' --header 'Authorization: Bearer YOUR_API_TOKEN' ``` วิดีโอที่เสร็จแล้วอยู่ที่ `response.media[0].videoUrl` ลิงก์นี้ใช้ได้ราว 6 ชั่วโมง และขั้นตอนถัดไปใช้ `response.media[0].mediaGenerationId` ของงานที่เสร็จแล้ว ถ้าคุณเชื่อมบัญชี Google ไว้หลายบัญชี API จะเลือกบัญชีที่มี Omni 1.2 แล้ว (Google ทยอยเปิดให้ใช้ภายในไม่กี่วันนับจาก 5 พฤศจิกายน) ส่ง `email` ถ้าต้องการเลือกบัญชีเอง #### ขั้นตอนที่ 1: 10 วินาทีแรก {: .no_toc #step-1-the-first-10-seconds } เรียก [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) ด้วย `model: "omni-flash-1.2"` และ `duration: 10` Google ตอบกลับใน 56 วินาที ที่ 720p วิดีโอ 10 วินาทีใช้ 30 เครดิต ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "model": "omni-flash-1.2", "duration": 10, "prompt": "Cinematic night, a narrow rainy alley in Tokyo glowing with neon signs reflected in the puddles. A street magician in a long dark coat faces the camera, fans out a deck of cards that glow faintly gold, and says with a grin: \"Pick a card. Any card.\" A sudden gust snatches one glowing card from his hand and it flutters away down the alley. Handheld camera, shallow depth of field, rain drops catching the light.", "async": true }' ``` <video poster="https://media.useapi.net/blog/2026-11-06-261106/261106-google-flow-omni-1-2-magician-first-10s-poster.jpg" src="https://media.useapi.net/blog/2026-11-06-261106/261106-google-flow-omni-1-2-magician-first-10s.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> <details markdown="block"> <summary>งานที่เสร็จแล้ว จาก <a href="/docs/api-google-flow-v1/get-google-flow-jobs-jobid">GET /jobs/<code>jobid</code></a> (ตัดให้สั้นลง)</summary> ```json { "jobid": "j1106021223539251070v-u12345-email:user@example.com-bot:google-flow", "type": "video", "status": "completed", "response": { "media": [ { "video": { "generatedVideo": { "model": "macaron_cookie_t2v_10s", "aspectRatio": "VIDEO_ASPECT_RATIO_LANDSCAPE" }, "dimensions": { "length": "10s" } }, "mediaGenerationId": "user:12345-email:…-video:b08556b9-…", "videoUrl": "https://flow-content.google/video/b08556b9-…?Expires=…" } ], "remainingCredits": 877 } } ``` </details> #### ขั้นตอนที่ 2: ต่อความยาว 10 วินาที พร้อมเสียงพูด {: .no_toc #step-2-extend-by-10-seconds-with-a-voice } เรียก [POST /videos/extend](/docs/api-google-flow-v1/post-google-flow-videos-extend) ด้วย `mediaGenerationId` ของวิดีโอแรก `duration: 10` และเสียงในตัวชื่อ Charon เป็น `referenceAudio_1` พรอมต์วางเสียงนี้ไว้ตรงที่นักมายากลพูด ด้วยการอ้างถึงในบรรทัดว่า `@referenceAudio_1` การต่อความยาวใช้ Omni 1.2 เป็นค่าเริ่มต้น จึงไม่ต้องใส่ `model` ผลลัพธ์คือคลิปเดียวยาว 20 วินาที 10 วินาทีแรกเหมือนเดิมและต่อด้วย 10 วินาทีใหม่ ได้มาใน 2 นาที 20 วินาที ใช้ 30 เครดิต ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos/extend' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "mediaGenerationId": "user:12345-email:…-video:b08556b9-…", "duration": 10, "referenceAudio_1": "Charon", "prompt": "The magician runs after the glowing card through the rain, past a ramen stall and under paper lanterns, laughing and calling out in a deep voice @referenceAudio_1: \"Come back here! You are the ace of hearts!\" The camera follows him close behind.", "async": true }' ``` #### ขั้นตอนที่ 3: อีก 10 วินาที กับเสียงที่สอง {: .no_toc #step-3-10-more-seconds-a-second-voice } คำสั่งเดียวกันกับคลิป 20 วินาที ใช้เสียง Aoede ให้ผู้หญิงในคาเฟ่ ผลลัพธ์คือฉากเต็มยาว 30 วินาที ได้มาในอีก 2 นาที ใช้อีก 30 เครดิต ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos/extend' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "mediaGenerationId": "user:12345-email:…-video:113384cd-…", "duration": 10, "referenceAudio_1": "Aoede", "prompt": "The glowing card drifts through the open door of a tiny warm café and lands on a table. A young woman in a yellow raincoat picks it up, looks at the out-of-breath magician in the doorway, and says with a smile @referenceAudio_1: \"Is this your card?\" He laughs. Warm light, rain outside the window.", "async": true }' ``` <video poster="https://media.useapi.net/articles/2026-06-15-omni-flash-bash/261106-google-flow-omni-1-2-magician-extended-30s-web-poster.jpg" src="https://media.useapi.net/articles/2026-06-15-omni-flash-bash/261106-google-flow-omni-1-2-magician-extended-30s-web.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> <details markdown="block"> <summary>งานที่เสร็จแล้ว (ตัดให้สั้นลง)</summary> ```json { "jobid": "j1106021547955542178v-u12345-email:user@example.com-bot:google-flow", "type": "video", "status": "completed", "response": { "media": [ { "video": { "generatedVideo": { "model": "macaron_cookie_extend_10s" }, "dimensions": { "length": "30s" } }, "mediaGenerationId": "user:12345-email:…-video:db0201df-…", "videoUrl": "https://flow-content.google/video/db0201df-…?Expires=…" } ], "remainingCredits": 817 } } ``` </details> วิดีโอด้านบนเข้ารหัสใหม่สำหรับเว็บที่ความละเอียดเดิม 1280×720 ทั้งฉากใช้ 90 เครดิต ราว $0.72 บน Ultra $199.99 เทียบกับราว $2.10 สำหรับ 30 วินาทีตามราคา 720p ของ Gemini API (ข้อมูล ณ พฤศจิกายน 2026) Google ต่อความยาวได้เฉพาะวิดีโอที่สั้นกว่า 30 วินาที ฉากนี้จึงยาวกว่านี้ไม่ได้แล้ว การต่อครั้งที่สี่จะตอบ `400` ทันที ก่อนจะใช้ captcha หรือเครดิตใด ๆ ส่วนคลิป 25 วินาทียังต่อได้อีก 10 วินาที และจบที่ 35 วินาที [`omni-extend/`](https://github.com/useapi/google-flow-api/tree/main/omni-extend) บน GitHub สร้างฉากนี้จาก `story.json` ไฟล์เดียว ด้วย Node.js หรือ Python และ [`omni-flash/`](https://github.com/useapi/google-flow-api/tree/main/omni-flash) สร้างวิดีโอ Omni Flash ทีละหลายคลิปจากรายการพรอมต์ [บทความสอนใช้ Omni Flash](/docs/articles/omni-flash-bash) อธิบายภาพอ้างอิง ตัวละคร เฟรมเริ่มและเฟรมจบ และการแก้ไข ### Omni 1.2 Flash ใน Google Vids: 15 วินาที ต่อความยาว และแก้ไข Vids มีโมเดลวิดีโอเดียว ซึ่ง Google ทยอยเปลี่ยนเป็น Omni 1.2 ภายในไม่กี่วันนับจาก 5 พฤศจิกายน จึงไม่มี `model` ให้ตั้ง คำขอใช้ body แบบ JSON และทุกคำสั่งในส่วนนี้ทำงานเป็นงานแบบ async เรียก [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid) ซ้ำ หรือส่ง `replyUrl` แล้วดาวน์โหลดคลิปด้วย [GET /media/`mediaId`](/docs/api-google-vids-v1/get-google-vids-media-mediaId) ภายใน 24 ชั่วโมง ขั้นตอนถัดไปใช้ `result.mediaId` ของงานที่เสร็จแล้ว Vids ไม่ขอ captcha ```bash curl --location 'https://api.useapi.net/v1/google-vids/jobs/<jobid>' --header 'Authorization: Bearer YOUR_API_TOKEN' ``` #### ขั้นตอนที่ 1: วิดีโอ 15 วินาทีจากพรอมต์เดียว {: .no_toc #step-1-a-15-second-video-from-one-prompt } เรียก [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) ด้วย `duration: 15` Google ตอบกลับในราว 60 วินาที ได้วิดีโอ 1280×720 และพูดทั้งสองประโยคตรงตามที่เขียนไว้ ใช้โควตาไป 15 วินาที ```bash curl --location 'https://api.useapi.net/v1/google-vids/videos' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "prompt": "Cinematic single continuous shot, 15 seconds, 16:9. Golden hour on a Tokyo rooftop garden, city skyline glowing behind. A young chef in a crisp white apron finishes plating a steaming bowl of ramen, steam curling in the warm light. She looks up into the camera and says with a confident smile: \"Fifteen seconds. One prompt. No editing.\" She slides the bowl toward the camera as it slowly pushes in, wind chimes ringing softly and city traffic humming far below. She laughs and adds: \"Now that'\''s fast food.\"", "duration": 15, "aspectRatio": "landscape", "resolution": "720p", "async": true }' ``` <video poster="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-15s-poster.jpg" src="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-15s.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> <details markdown="block"> <summary>งานที่เสร็จแล้ว จาก <a href="/docs/api-google-vids-v1/get-google-vids-jobs-jobid">GET /jobs/<code>jobid</code></a> (ตัดให้สั้นลง)</summary> ```json { "status": "completed", "result": { "mediaId": "user:12345-user@example.com-video:eyJ1Ijoi…", "width": 1280, "height": 720, "duration": 15, "resolution": "720p", "aspectRatio": "landscape", "model": "/flix/generate_videos_omni_t2v_psq/v1", "quota": { "video": { "limit": 500, "left": 485, "resetAt": "2026-12-01T08:00:00.000Z" } } } } ``` </details> `quota` บอกว่าบัญชียังเหลือวินาทีวิดีโอรายเดือนเท่าไร และจะรีเซ็ตเมื่อไร บัญชีทดสอบนี้ใช้ Google AI Pro ลิมิตจึงเป็น 500 วินาที ส่วนราคาในหน้านี้คิดจาก Ultra $199.99 #### ขั้นตอนที่ 2: ต่อความยาวอีก 10 วินาที {: .no_toc #step-2-extend-it-by-10-seconds } เรียก [POST /videos/extend](/docs/api-google-vids-v1/post-google-vids-videos-extend) ด้วย `mediaId` ของวิดีโอแรก ผลลัพธ์คือคลิปเดียว 15 วินาทีเดิมบวก 10 วินาทีใหม่ ยาว 25 วินาที ได้มาในราว 100 วินาที เพื่อนเดินเข้ามาชิมราเมง และพูดทั้งสองประโยคใหม่ครบ ```bash curl --location 'https://api.useapi.net/v1/google-vids/videos/extend' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "mediaId": "user:12345-user@example.com-video:eyJ1Ijoi…", "prompt": "Same shot continues on the Tokyo rooftop at dusk, the city lights now switching on. A friend in a denim jacket walks into frame, sits at the table and takes a first slurp of the ramen, eyes widening. He says: \"Wait, you made this in fifteen seconds?\" The chef folds her arms and grins: \"Fifteen more, and I'\''ll make dessert.\" They both laugh as string lights flicker on above them and soft city ambience fills the air.", "duration": 10, "async": true }' ``` <video poster="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-extend-25s-poster.jpg" src="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-extend-25s.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> ดูบน YouTube ได้ด้วย: [Gemini Omni 1.2 Flash in Google Vids: 15 seconds from one prompt, extended to 25](https://www.youtube.com/watch?v=eJ3js18XCBM) API รับ 3 ถึง 10 วินาทีต่อการต่อความยาวหนึ่งครั้ง และตอบ `duration` ที่ยาวกว่านั้นด้วย `400` เพราะ Google เพิ่มให้ไม่เกิน 10 วินาที แต่นับทุกวินาทีที่ขอ (คลิปนี้มาจากการทดสอบก่อนหน้าที่ใช้ `duration: 15`) คำขอเดียวกันที่ใช้ `duration: 10` ได้คลิป 25 วินาทีเหมือนกัน และใช้ 10 วินาที Vids ต่อความยาวได้เฉพาะคลิปที่ยาวไม่เกิน 24 วินาที คลิป 25 วินาทีนี้จึงยาวได้แค่นี้ ถ้าต้องการคลิปยาวที่สุดราว 34 วินาที ให้ต่อคลิปที่ยาวไม่เกิน 24 วินาทีอีก 10 วินาที #### ขั้นตอนที่ 3: แก้ไขทั้ง 15 วินาที {: .no_toc #step-3-edit-all-15-seconds } เรียก [POST /videos/edit](/docs/api-google-vids-v1/post-google-vids-videos-edit) กับวิดีโอแรกด้วย `duration: 15` สมัย Omni 1.1 การแก้ไขได้คืนมาไม่เกิน 10 วินาที ตอนนี้ได้คลิป 15 วินาทีที่แก้แล้วทั้งคลิปทุกเฟรม ในราว 140 วินาที ```bash curl --location 'https://api.useapi.net/v1/google-vids/videos/edit' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "video": "user:12345-user@example.com-video:eyJ1Ijoi…", "prompt": "Make it a snowy winter evening: snow falling gently over the rooftop and the city, the chef wearing a red knit scarf. Keep everything else the same.", "duration": 15, "async": true }' ``` <video poster="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-edit-snow-15s-poster.jpg" src="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-edit-snow-15s.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> Vids แก้ไขได้เฉพาะคลิปที่ Google สร้าง และ Google ปฏิเสธวิดีโอที่อัปโหลดด้วย `422` ถ้าเป็นคลิปเดี่ยว ให้สร้างที่ 1080p ซึ่งใช้โควตาเท่ากับ 720p ถ้าเป็นคลิปที่จะต่อความยาว ให้ทำงานที่ 720p แล้วค่อยไป 1080p ครั้งเดียวตอนจบ เพราะการต่อความยาวที่ 1080p แต่ละครั้งจะประมวลผลทั้งคลิปใหม่ และทำให้วินาทีก่อนหน้าคมเกินไป ([ดูการเปรียบเทียบ](/blog/261106v#720p-or-1080p-what-a-1080p-extend-does)) คลิปยาวไม่เกิน 20 วินาทีให้จบด้วย[อัปสเกล](/docs/api-google-vids-v1/post-google-vids-videos-upscale)ครั้งเดียว (ใช้วินาทีเท่าความยาวคลิปอีกครั้ง) ส่วนคลิป 21 ถึง 34 วินาทีให้ตั้ง `resolution: "1080p"` เฉพาะการต่อความยาวครั้งสุดท้าย repo [google-vids-api](https://github.com/useapi/google-vids-api) บน GitHub มีตัวอย่าง Vids ที่รันได้ทั้ง Node.js และ Python รวมถึงอวตารที่มีเสียงพูด และ[บทความสอนทำ AI influencer](/docs/articles/google-vids-influencer-avatars-th) สร้างคลิปที่มีอวตารพูดได้สองตัว ### ควรใช้ตัวไหน เลือก Google Flow API เมื่อคุณต้องการ: - ร่างวิดีโอ 360p ในราคาหนึ่งในสามของ 720p หรือสร้างได้สูงสุด 4 คลิปต่อคำขอ - เฟรมเริ่มและเฟรมจบ ภาพอ้างอิงสูงสุด 10 ภาพ หรือตัวละครที่บันทึกไว้ - เลือกเสียงเอง สูงสุด 5 เสียงต่อวิดีโอเมื่อมีภาพอ้างอิงหรือตัวละคร และสูงสุด 3 เสียงต่อการต่อความยาวหนึ่งครั้ง จาก 30 เสียงในตัวหรือเสียงของคุณเอง - แก้ไขวิดีโอที่อัปโหลด หรืออัปสเกลเป็น 4K บน Ultra - วิดีโอ Veo 3.1 และภาพ Nano Banana จาก API เดียวกัน - Omni 1.2 บนบัญชี Google ฟรี ยาวไม่เกิน 10 วินาที เลือก Google Vids API เมื่อคุณต้องการ: - ไม่ต้องมี captcha และไม่ต้องใช้ผู้ให้บริการ captcha - 1080p ในราคาเดียวกับ 720p (สำหรับคลิปที่จะต่อความยาวหรือแก้ไข ดู[ควรทำงานที่ความละเอียดไหน](#vids-resolution)) - อวตารมีเสียงที่คงหน้าตาและเสียงเดิมจากวิดีโอหนึ่งไปอีกวิดีโอ สูงสุด 3 ตัวในวิดีโอเดียว - ราคาต่อวินาทีต่ำที่สุดบน Ultra $199.99 คือ $0.02 เทียบกับ $0.032 สำหรับวิดีโอ 15 วินาทีใน Flow - วิดีโอ Omni 1.2 เพิ่มเมื่อเครดิต Flow หมด เพราะ Vids มีโควตาของตัวเอง หรือใช้ทั้งสองตัว เชื่อมบัญชี Google เดียวกันกับแต่ละ API แล้วส่งงานไปที่ที่เหมาะ เพราะ[โควตาทั้งสองก้อนได้เพิ่มกัน](#price-per-video) ### ใช้จาก Claude Code, Cursor หรือ Gemini CLI API ทั้งสองตัวมี MCP server แบบโฮสต์ที่ทำงานด้วย API token ของ useapi.net ไม่ต้องติดตั้งอะไร ใน Claude Code แต่ละตัวใช้คำสั่งบรรทัดเดียว: ```bash claude mcp add --transport http useapi-google-vids https://api.useapi.net/v1/google-vids/mcp --header "Authorization: Bearer YOUR_API_TOKEN" claude mcp add --transport http useapi-google-flow https://api.useapi.net/v1/google-flow/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` ใน Cursor หรือ Gemini CLI ให้เพิ่ม URL เดียวกันพร้อม header `Authorization` เดียวกันในการตั้งค่า MCP - [Google Vids MCP server](/docs/api-google-vids-v1/mcp) สร้างคลิป Omni 1.2 ได้โดยตรง `vids_create_video` และ `vids_edit_video` รับได้สูงสุด 15 วินาที และ `vids_extend_video` สูงสุด 10 วินาทีต่อครั้งกับคลิปยาวไม่เกิน 24 วินาที - [Google Flow MCP server](/docs/api-google-flow-v1/mcp) คุยกับ Google Flow Agent ไม่ได้เรียก endpoint ของ Omni 1.2 โดยตรง ผู้ช่วยของคุณแชตกับ Agent ซึ่งสร้างภาพและวิดีโอในราคา Flow ปกติ ถ้าต้องการเรียก Omni 1.2 โดยตรงจาก Claude Code หรือ Codex ให้เพิ่ม [agent skill omni-flash-video](https://github.com/useapi/google-flow-api/tree/main/skills/omni-flash-video) - ทั้งสอง repo ติดตั้ง server นี้เป็นปลั๊กอิน Claude Code หรือส่วนขยาย Gemini CLI ได้ด้วย: [google-flow-api](https://github.com/useapi/google-flow-api#use-with-claude-code) และ [google-vids-api](https://github.com/useapi/google-vids-api#use-with-claude-code) ### คำถามที่พบบ่อย #### Gemini Omni 1.2 Flash มี API ไหม? ผ่าน useapi.net มี โดยรัน Gemini Omni 1.2 Flash บนแพ็กเกจ Google AI ของคุณ ผ่าน [Google Flow API](/docs/api-google-flow-v1) (`model: "omni-flash-1.2"`) และ [Google Vids API](/docs/api-google-vids-v1) ไม่ต้องใช้ Gemini API key ราคาเริ่มที่ $0.02 ต่อวินาทีจากโควตา Vids ของ Ultra $199.99 เทียบกับราว $0.07 ต่อวินาทีบน [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) ของ Google และ Flow ใส่เสียงได้สูงสุด 5 เสียงต่อวิดีโอเมื่อมีภาพอ้างอิงหรือตัวละคร ขณะที่ API ของ Google [จำกัดเสียงอ้างอิงไว้เฉพาะผู้ได้รับอนุญาต](https://cloud.google.com/blog/products/ai-machine-learning/gemini-omni-1-2-flash-generally-available) (ข้อมูล ณ พฤศจิกายน 2026) #### Omni 1.2 Flash ราคาต่อวิดีโอเท่าไร? ผ่าน useapi.net บน Google AI Ultra $199.99 วิดีโอ Omni 1.2 Flash ยาว 15 วินาทีใช้โควตา Vids ไป $0.30 หรือเครดิต Flow ไป $0.48 เทียบกับ $1.04 ที่ 720p บน Gemini API ของ Google (ข้อมูล ณ พฤศจิกายน 2026) ใน Vids วิดีโอ 1080p ยาว 15 วินาทีก็ $0.30 เท่ากัน เพราะ 1080p ใช้วินาทีเท่ากัน ขณะที่ Gemini API คิด $1.56 [ตารางราคา](#price-per-video)แสดงทุกแพ็กเกจ #### มี Gemini Omni 1.2 Flash API แบบฟรีไหม? ผ่าน useapi.net มี ใน Google Flow API บัญชี Google ฟรีสร้างวิดีโอ Omni 1.2 Flash ยาวไม่เกิน 10 วินาทีได้จาก[เครดิต Flow 50 เครดิตต่อวัน](https://support.google.com/flow/answer/16526234?hl=th) คือวิดีโอ 720p ยาว 10 วินาทีได้ 1 คลิป หรือ 360p ได้ 5 คลิปต่อวัน ส่วน Gemini API ของ Google มี Omni 1.2 Flash เฉพาะแบบเสียเงิน (ข้อมูล ณ พฤศจิกายน 2026) วิดีโอที่ยาวกว่านั้นและการต่อความยาวด้วย Omni 1.2 ต้องใช้แพ็กเกจ Google AI แบบเสียเงิน #### วิดีโอ Omni 1.2 Flash ยาวได้แค่ไหน? ผ่าน useapi.net คำสั่งเดียวสร้างได้ 3 ถึง 15 วินาที ทั้งใน Google Flow และ Google Vids และการต่อความยาวเพิ่มได้ครั้งละ 3 ถึง 10 วินาที แล้วคืนคลิปทั้งคลิป ใน Flow ยาวได้เกือบ 40 วินาที และใส่เสียงใหม่ในการต่อแต่ละครั้งได้ ใน Vids ยาวได้ราว 34 วินาที เพราะต่อได้เฉพาะคลิปที่ยาวไม่เกิน 24 วินาที [ฉาก 30 วินาที](#flow-walkthrough)ด้านบนสร้างด้วยวิธีนี้ในสามคำสั่ง #### Omni 1.2 Flash หรือ Veo 3.1 ควรใช้ตัวไหน? ผ่าน useapi.net คุณใช้ได้ทั้งสองโมเดลใน Google Flow API ตัวเดียวบนแพ็กเกจเดียว บน Ultra $199.99 วิดีโอ Omni 1.2 Flash 720p ยาว 8 วินาทีราคา $0.19 และ Veo 3.1 Fast ราคา $0.08 เทียบกับ $0.56 และ $0.80 บน API ของ Google เอง (ข้อมูล ณ พฤศจิกายน 2026) เลือก Omni 1.2 Flash สำหรับคลิปที่ยาวกว่า 8 วินาที เลือกเสียงเองได้สูงสุด 5 เสียง และต่อความยาวด้วยเสียงใหม่ได้ เลือก Veo 3.1 Fast เมื่อต้องการคลิป 8 วินาทีที่ถูกที่สุด ราคา Veo ทั้งหมด: [ราคา Veo 3.1 API](/docs/articles/veo-3-1-api-pricing) ### แหล่งข้อมูล - Google Cloud, [Gemini Omni 1.2 Flash is generally available](https://cloud.google.com/blog/products/ai-machine-learning/gemini-omni-1-2-flash-generally-available) 5 พฤศจิกายน 2026 - Google Workspace Updates, [Gemini Omni 1.2 Flash now in Vids](https://workspaceupdates.googleblog.com/2026/11/gemini-omni-12-flash-now-in-vids-with-15second-generations-and-improved-quality.html) 5 พฤศจิกายน 2026 - Google, [ราคา Gemini API](https://ai.google.dev/gemini-api/docs/pricing) อ่านเมื่อ 6 พฤศจิกายน 2026 - Google Cloud, [ราคา Agent Platform](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing) (Veo 3.1) อ่านเมื่อ 6 พฤศจิกายน 2026 - Google, [แพ็กเกจ Google AI](https://gemini.google/subscriptions/), [เครดิต Flow](https://support.google.com/flow/answer/16526234?hl=th) และ [Gemini ใน Google Vids](https://support.google.com/docs/answer/15609411?hl=th) อ่านเมื่อพฤศจิกายน 2026 - โพสต์เปิดตัวของ useapi.net: [Google Flow: Omni 1.2 Flash, 15-Second Videos, and Extend with Voices](/blog/261106) และ [Google Vids: Omni 1.2 Flash, 15-Second Videos and 15-Second Edits](/blog/261106v) 6 พฤศจิกายน 2026 ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/gemini-omni-1-2-flash-api-vi === Document URL: https://useapi.net/docs/articles/gemini-omni-1-2-flash-api-vi --- layout: default title: "Cách dùng Gemini Omni 1.2 Flash API: video 15 giây trong Google Flow và Google Vids" seo_title: "Gemini Omni 1.2 Flash API: video 15 giây và giá" description: "Gemini Omni 1.2 Flash API qua useapi.net: video 3 đến 15 giây có lời thoại trong Google Flow và Vids, $0,30 cho 15 giây trên Ultra $199,99 so với $1,04 trên Gemini API." image: https://media.useapi.net/articles/2026-11-06-gemini-omni-1-2-flash-api-id/261106-gemini-omni-1-2-flash-api-cover.jpg keywords: [Gemini Omni 1.2 Flash API, Omni 1.2 Flash API, gemini omni 1.2 api, omni-flash-1.2, Omni Flash 15 giây, Gemini Omni API, Gemini Omni Flash API, giá Omni 1.2 Flash, Omni 1.2 Flash miễn phí, hướng dẫn Omni 1.2 Flash, thay thế Veo, thay thế Veo 3.1, Google Flow API, Google Vids API, kéo dài video, API chỉnh sửa video, video AI có lời thoại, tạo video AI bằng API, Google AI Ultra, không cần Gemini API key, hướng dẫn, curl] parent: Articles nav_exclude: true lang: vi translation_key: gemini-omni-1-2-flash date: 2026-11-06 last_modified: 2026-11-11 nav_order: 908 repo: https://github.com/useapi/google-flow-api --- ## Cách dùng Gemini Omni 1.2 Flash API: video 15 giây trong Google Flow và Google Vids {: #how-to-use-the-gemini-omni-12-flash-api-15-second-videos-in-google-flow-and-google-vids .no_toc } 7 phút đọc • 6 tháng 11 năm 2026 useapi.net là API của bên thứ ba, không liên kết với Google và không được Google bảo trợ. ## Mục lục {: #table-of-contents .no_toc .text-delta } ### Giới thiệu Gemini Omni 1.2 Flash, được Google phát hành ngày 5 tháng 11 năm 2026, tạo video dài 3 đến 15 giây có âm thanh và lời thoại. useapi.net chạy model này trên [gói Google AI](https://gemini.google/subscriptions/) của bạn qua hai REST API: [Google Flow API](/docs/api-google-flow-v1) và [Google Vids API](/docs/api-google-vids-v1). Trên Google AI Ultra $199,99, một video 15 giây dùng $0,30 hạn mức Vids hằng tháng của gói hoặc $0,48 credit Flow, so với $1,04 cho 15 giây ở 720p trên [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) của chính Google (tính đến tháng 11/2026). Bạn không cần Gemini API key hay dự án Google Cloud. Điểm mới của 1.2, theo [thông báo](https://cloud.google.com/blog/products/ai-machine-learning/gemini-omni-1-2-flash-generally-available) của Google: clip dài tới 15 giây thay vì 10, bám sát ảnh tham chiếu hơn và khẩu hình rõ hơn. Cùng ngày, Google cũng [chuyển Google Vids sang model này](https://workspaceupdates.googleblog.com/2026/11/gemini-omni-12-flash-now-in-vids-with-15second-generations-and-improved-quality.html). Bài này đặt hai cách dùng cạnh nhau, rồi đi qua một cảnh thật ở mỗi bên: một cảnh 30 giây trong Google Flow làm bằng ba lệnh gọi, với hai giọng nói, và một cảnh 15 giây trong Google Vids có kéo dài và chỉnh sửa 15 giây. Mọi request đều là request thật và mọi video đều là kết quả thật, lấy từ hai bài thông báo [Google Flow: Omni 1.2 Flash](/blog/261106) và [Google Vids: Omni 1.2 Flash](/blog/261106v). Trước khi bắt đầu, bạn cần: - một [API token](/docs/start-here/setup-useapi) của useapi.net - một tài khoản Google đã kết nối theo [Setup Google Flow](/docs/start-here/setup-google-flow), [Setup Google Vids](/docs/start-here/setup-google-vids) hoặc cả hai. Một tài khoản Google kết nối được với cả hai API, và mỗi API giữ hạn mức riêng. ### Google Flow hay Google Vids: Omni 1.2 Flash trong một bảng | | [Google Flow API](/docs/api-google-flow-v1) | [Google Vids API](/docs/api-google-vids-v1) | |---|---|---| | Cách chọn Omni 1.2 | `model: "omni-flash-1.2"` (Omni 1.1 Flash và Veo 3.1 là các giá trị khác) | Không có trường `model`: Vids chỉ có một model video, là Omni 1.2 kể từ đợt triển khai của Google từ ngày 5 tháng 11 | | Độ dài | 3 đến 15 giây (3 đến 10 khi có khung đầu và khung cuối) | 3 đến 15 giây | | Độ phân giải | 360p hoặc 720p, [upscale](/docs/api-google-flow-v1/post-google-flow-videos-upscale) lên 1080p, hoặc 4K trên Ultra | 720p hoặc 1080p cùng một giá, [upscale](/docs/api-google-vids-v1/post-google-vids-videos-upscale) lên 1080p với clip tối đa 20 giây | | Đầu vào | Văn bản, khung đầu, khung đầu và khung cuối, tối đa 10 ảnh tham chiếu, [nhân vật](/docs/api-google-flow-v1/get-google-flow-characters) đã lưu, 1 đến 4 video mỗi request | Văn bản, ảnh mở đầu, hoặc tối đa 3 tham chiếu gồm ảnh và [avatar](/docs/api-google-vids-v1/post-google-vids-avatars) | | Giọng nói | Tối đa 5 [giọng](/docs/api-google-flow-v1/get-google-flow-voices) mỗi video khi có ảnh tham chiếu hoặc nhân vật, tối đa 3 mỗi lần kéo dài. 30 giọng có sẵn hoặc giọng của bạn | Mỗi avatar nói bằng một trong 30 [giọng](/docs/api-google-vids-v1/get-google-vids-voices), tối đa 3 avatar mỗi video | | [Kéo dài](/docs/api-google-flow-v1/post-google-flow-videos-extend) | 3 đến 10 giây mỗi lệnh gọi, với giọng và tham chiếu riêng, tới gần 40 giây, gói trả phí | [3 đến 10 giây mỗi lệnh gọi](/docs/api-google-vids-v1/post-google-vids-videos-extend) với clip tối đa 24 giây, tới khoảng 34 giây | | Chỉnh sửa bằng prompt | [Tối đa 15 giây](/docs/api-google-flow-v1/post-google-flow-videos#video-reference-omni-11-flash-v2v-edit) của clip đã tạo hoặc tải lên | [Tối đa 15 giây](/docs/api-google-vids-v1/post-google-vids-videos-edit) của clip do Google tạo | | Tiêu tốn gì | Credit Flow: ở 720p là 3 mỗi giây tới giây thứ 10 và 6 mỗi giây sau đó, ở 360p là 1 và 2 | Số giây trong hạn mức Vids hằng tháng, tách biệt với credit Flow | | Tài khoản Google miễn phí | Video tối đa 10 giây với 50 credit Flow mỗi ngày | Không có giây video Vids nào trong các thử nghiệm của chúng tôi | | Captcha | Google yêu cầu captcha cho mỗi video Flow. API tự giải: 300 lần miễn phí, sau đó qua một [dịch vụ giải captcha](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers) bạn tự đăng ký, khoảng $0,80 đến $3,00 cho mỗi 1.000 lần | Không có | ### Giá mỗi video Một video Omni 1.2 Flash dài 15 giây tốn bao nhiêu trên [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) của chính Google và trên từng gói Google AI (tính đến tháng 11/2026). Mỗi gói có một số credit Flow hằng tháng và, tách riêng, một số giây video Vids, nên mỗi video tốn một phần giá gói. | Omni 1.2 Flash, 15 s | [API Google](https://ai.google.dev/gemini-api/docs/pricing) | Ultra $199,99/th (25.000 cr, 10.000 s/th) | Ultra $99,99/th (10.000 cr, 2.500 s/th) | Pro $19,99/th (1.000 cr, 500 s/th) | Plus $4,99/th (200 cr, 60 s/th) | |---|---|---|---|---|---| | Google Flow (720p) | $1,04 (khoảng $0,07/giây) | $0,48 / 60 cr (416 video/th) | $0,60 / 60 cr (166 video/th) | $1,20 / 60 cr (16 video/th) | $1,50 / 60 cr (3 video/th) | | Google Flow (360p) | $0,35 ($0,023/giây) | $0,16 / 20 cr (1.250 video/th) | $0,20 / 20 cr (500 video/th) | $0,40 / 20 cr (50 video/th) | $0,50 / 20 cr (10 video/th) | | Google Vids (720p, 1080p) | $1,04 ở 720p ($1,56 ở 1080p) | $0,30 / 15 s (666 video/th) | $0,60 / 15 s (166 video/th) | $0,60 / 15 s (33 video/th) | $1,25 / 15 s (4 video/th) | - Gói càng lớn thì càng tiết kiệm. Với Plus, và với Pro trong Flow, một video 720p dài 15 giây đắt hơn trên Gemini API, còn trên Ultra $199,99 thì chưa tới một nửa giá trong Flow và chưa tới một phần ba trong Vids. - Flow tính mỗi giây sau giây thứ 10 với giá gấp đôi, nên video ngắn hơn rẻ hơn tính theo giây: một video 720p dài 10 giây tốn 30 credit, $0,24 trên Ultra $199,99, so với $0,70 trên Gemini API. Bảng giá Flow đầy đủ với mọi model có trên [trang tổng quan Google Flow API](/docs/api-google-flow-v1#pricing), còn bảng giá Vids, gồm cả ảnh và avatar, trên [trang tổng quan Google Vids API](/docs/api-google-vids-v1#pricing). - Một lần kéo dài chỉ dùng số giây được thêm vào, ở cả hai API. Một lần chỉnh sửa trong Vids dùng tối đa số giây được chỉnh (trong thử nghiệm của chúng tôi, chỉnh 15 giây chỉ dùng 10), còn chỉnh sửa trong Flow tốn bằng một video có cùng độ dài. - Credit Flow và giây Vids là hai hạn mức riêng trên cùng một gói. Trên Ultra $199,99, một tài khoản Google kết nối với cả hai API làm được khoảng 416 video 720p dài 15 giây trong Flow và 666 video trong Vids mỗi tháng, tổng cộng khoảng 1.082 video. - Giá gói là giá tại Mỹ của Google. Số giây Vids của từng gói lấy từ trang [Gemini trong Google Vids](https://support.google.com/docs/answer/15609411?hl=vi) của Google và khớp với thử nghiệm của chúng tôi trên Ultra $199,99. ### Omni 1.2 Flash trong Google Flow: cảnh 30 giây bằng ba lệnh gọi Một video 10 giây, rồi hai lần kéo dài 10 giây, mỗi lần một giọng riêng. Bước 1 chạy được trên tài khoản Google miễn phí. Bước 2 và 3 (kéo dài) cần gói Google AI trả phí. Mọi lệnh gọi đều chạy dưới dạng job bất đồng bộ: truyền `async: true` và lệnh POST trả về `jobid` ngay. Gọi [GET /jobs/`jobid`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid) cho tới khi `status` là `completed`, hoặc truyền `replyUrl` để nhận job đã xong qua webhook của bạn: ```bash curl --location 'https://api.useapi.net/v1/google-flow/jobs/<jobid>' --header 'Authorization: Bearer YOUR_API_TOKEN' ``` Video hoàn chỉnh nằm ở `response.media[0].videoUrl`, một liên kết dùng được khoảng 6 giờ, và bước tiếp theo lấy `response.media[0].mediaGenerationId` của job đã xong. Nếu bạn kết nối nhiều tài khoản Google, API sẽ chọn tài khoản đã có Omni 1.2 (Google bật model này dần trong vài ngày từ 5 tháng 11). Truyền `email` để tự chọn. #### Bước 1: 10 giây đầu tiên {: #step-1-the-first-10-seconds .no_toc } [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) với `model: "omni-flash-1.2"` và `duration: 10`. Google trả kết quả sau 56 giây. Ở 720p, một video 10 giây tốn 30 credit. ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "model": "omni-flash-1.2", "duration": 10, "prompt": "Cinematic night, a narrow rainy alley in Tokyo glowing with neon signs reflected in the puddles. A street magician in a long dark coat faces the camera, fans out a deck of cards that glow faintly gold, and says with a grin: \"Pick a card. Any card.\" A sudden gust snatches one glowing card from his hand and it flutters away down the alley. Handheld camera, shallow depth of field, rain drops catching the light.", "async": true }' ``` <video poster="https://media.useapi.net/blog/2026-11-06-261106/261106-google-flow-omni-1-2-magician-first-10s-poster.jpg" src="https://media.useapi.net/blog/2026-11-06-261106/261106-google-flow-omni-1-2-magician-first-10s.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> <details markdown="block"> <summary>Job đã xong, từ <a href="/docs/api-google-flow-v1/get-google-flow-jobs-jobid">GET /jobs/<code>jobid</code></a> (rút gọn)</summary> ```json { "jobid": "j1106021223539251070v-u12345-email:user@example.com-bot:google-flow", "type": "video", "status": "completed", "response": { "media": [ { "video": { "generatedVideo": { "model": "macaron_cookie_t2v_10s", "aspectRatio": "VIDEO_ASPECT_RATIO_LANDSCAPE" }, "dimensions": { "length": "10s" } }, "mediaGenerationId": "user:12345-email:…-video:b08556b9-…", "videoUrl": "https://flow-content.google/video/b08556b9-…?Expires=…" } ], "remainingCredits": 877 } } ``` </details> #### Bước 2: kéo dài thêm 10 giây, có giọng nói {: #step-2-extend-by-10-seconds-with-a-voice .no_toc } [POST /videos/extend](/docs/api-google-flow-v1/post-google-flow-videos-extend) với `mediaGenerationId` của video đầu tiên, `duration: 10` và giọng có sẵn Charon làm `referenceAudio_1`. Prompt đặt giọng nói vào chỗ ảo thuật gia lên tiếng, bằng cách nhắc trực tiếp `@referenceAudio_1`. Kéo dài mặc định dùng Omni 1.2 nên không cần `model`. Kết quả là một clip 20 giây, gồm 10 giây đầu giữ nguyên cộng 10 giây mới, sau 2 phút 20 giây, tốn 30 credit. ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos/extend' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "mediaGenerationId": "user:12345-email:…-video:b08556b9-…", "duration": 10, "referenceAudio_1": "Charon", "prompt": "The magician runs after the glowing card through the rain, past a ramen stall and under paper lanterns, laughing and calling out in a deep voice @referenceAudio_1: \"Come back here! You are the ace of hearts!\" The camera follows him close behind.", "async": true }' ``` #### Bước 3: thêm 10 giây, giọng thứ hai {: #step-3-10-more-seconds-a-second-voice .no_toc } Cùng lệnh gọi đó trên clip 20 giây, với giọng Aoede cho người phụ nữ trong quán cà phê. Kết quả là cả cảnh, dài 30 giây, sau thêm 2 phút và 30 credit. ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos/extend' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "mediaGenerationId": "user:12345-email:…-video:113384cd-…", "duration": 10, "referenceAudio_1": "Aoede", "prompt": "The glowing card drifts through the open door of a tiny warm café and lands on a table. A young woman in a yellow raincoat picks it up, looks at the out-of-breath magician in the doorway, and says with a smile @referenceAudio_1: \"Is this your card?\" He laughs. Warm light, rain outside the window.", "async": true }' ``` <video poster="https://media.useapi.net/articles/2026-06-15-omni-flash-bash/261106-google-flow-omni-1-2-magician-extended-30s-web-poster.jpg" src="https://media.useapi.net/articles/2026-06-15-omni-flash-bash/261106-google-flow-omni-1-2-magician-extended-30s-web.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> <details markdown="block"> <summary>Job đã xong (rút gọn)</summary> ```json { "jobid": "j1106021547955542178v-u12345-email:user@example.com-bot:google-flow", "type": "video", "status": "completed", "response": { "media": [ { "video": { "generatedVideo": { "model": "macaron_cookie_extend_10s" }, "dimensions": { "length": "30s" } }, "mediaGenerationId": "user:12345-email:…-video:db0201df-…", "videoUrl": "https://flow-content.google/video/db0201df-…?Expires=…" } ], "remainingCredits": 817 } } ``` </details> Video trên được mã hóa lại cho web ở độ phân giải gốc 1280×720. Cả cảnh dùng 90 credit, khoảng $0,72 trên Ultra $199,99, so với khoảng $2,10 cho 30 giây theo giá 720p của Gemini API (tính đến tháng 11/2026). Google chỉ kéo dài video ngắn hơn 30 giây, nên cảnh này không dài thêm được nữa: lần kéo dài thứ tư trả về `400` ngay, trước cả captcha hay credit. Một clip 25 giây vẫn nhận thêm được 10 giây và kết thúc ở 35 giây. [`omni-extend/`](https://github.com/useapi/google-flow-api/tree/main/omni-extend) trên GitHub dựng cảnh này từ một file `story.json`, bằng Node.js hoặc Python, còn [`omni-flash/`](https://github.com/useapi/google-flow-api/tree/main/omni-flash) tạo hàng loạt video Omni Flash từ một danh sách prompt. [Hướng dẫn Omni Flash](/docs/articles/omni-flash-bash) nói về ảnh tham chiếu, nhân vật, khung đầu và khung cuối, và chỉnh sửa. ### Omni 1.2 Flash trong Google Vids: 15 giây, một lần kéo dài và một lần chỉnh sửa Vids có một model video, được Google chuyển sang Omni 1.2 trong vài ngày từ 5 tháng 11, nên không có `model` nào để đặt. Request nhận body JSON, và mọi lệnh gọi ở đây chạy dưới dạng job bất đồng bộ: gọi [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid) hoặc truyền `replyUrl`, rồi tải clip về bằng [GET /media/`mediaId`](/docs/api-google-vids-v1/get-google-vids-media-mediaId) trong vòng 24 giờ. Bước tiếp theo lấy `result.mediaId` của job đã xong. Vids không yêu cầu captcha. ```bash curl --location 'https://api.useapi.net/v1/google-vids/jobs/<jobid>' --header 'Authorization: Bearer YOUR_API_TOKEN' ``` #### Bước 1: video 15 giây từ một prompt {: #step-1-a-15-second-video-from-one-prompt .no_toc } [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) với `duration: 15`. Google trả về sau khoảng 60 giây một video 1280×720, và cả hai câu thoại được nói đúng như đã viết. Video dùng 15 giây hạn mức. ```bash curl --location 'https://api.useapi.net/v1/google-vids/videos' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "prompt": "Cinematic single continuous shot, 15 seconds, 16:9. Golden hour on a Tokyo rooftop garden, city skyline glowing behind. A young chef in a crisp white apron finishes plating a steaming bowl of ramen, steam curling in the warm light. She looks up into the camera and says with a confident smile: \"Fifteen seconds. One prompt. No editing.\" She slides the bowl toward the camera as it slowly pushes in, wind chimes ringing softly and city traffic humming far below. She laughs and adds: \"Now that'\''s fast food.\"", "duration": 15, "aspectRatio": "landscape", "resolution": "720p", "async": true }' ``` <video poster="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-15s-poster.jpg" src="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-15s.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> <details markdown="block"> <summary>Job đã xong, từ <a href="/docs/api-google-vids-v1/get-google-vids-jobs-jobid">GET /jobs/<code>jobid</code></a> (rút gọn)</summary> ```json { "status": "completed", "result": { "mediaId": "user:12345-user@example.com-video:eyJ1Ijoi…", "width": 1280, "height": 720, "duration": 15, "resolution": "720p", "aspectRatio": "landscape", "model": "/flix/generate_videos_omni_t2v_psq/v1", "quota": { "video": { "limit": 500, "left": 485, "resetAt": "2026-12-01T08:00:00.000Z" } } } } ``` </details> `quota` cho biết tài khoản còn bao nhiêu giây video trong tháng và khi nào hạn mức được nạp lại. Tài khoản thử nghiệm này dùng Google AI Pro, nên giới hạn là 500 giây. Giá trong bài tính theo Ultra $199,99. #### Bước 2: kéo dài thêm 10 giây {: #step-2-extend-it-by-10-seconds .no_toc } [POST /videos/extend](/docs/api-google-vids-v1/post-google-vids-videos-extend) với `mediaId` của video đầu tiên. Kết quả là một clip gồm 15 giây cũ cộng 10 giây mới, dài 25 giây, sau khoảng 100 giây. Một người bạn bước vào, nếm thử bát ramen, và cả hai câu thoại mới đều được nói ra. ```bash curl --location 'https://api.useapi.net/v1/google-vids/videos/extend' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "mediaId": "user:12345-user@example.com-video:eyJ1Ijoi…", "prompt": "Same shot continues on the Tokyo rooftop at dusk, the city lights now switching on. A friend in a denim jacket walks into frame, sits at the table and takes a first slurp of the ramen, eyes widening. He says: \"Wait, you made this in fifteen seconds?\" The chef folds her arms and grins: \"Fifteen more, and I'\''ll make dessert.\" They both laugh as string lights flicker on above them and soft city ambience fills the air.", "duration": 10, "async": true }' ``` <video poster="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-extend-25s-poster.jpg" src="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-extend-25s.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> Xem thêm trên YouTube: [Gemini Omni 1.2 Flash in Google Vids: 15 seconds from one prompt, extended to 25](https://www.youtube.com/watch?v=eJ3js18XCBM). API nhận 3 đến 10 giây mỗi lần kéo dài và trả `400` khi `duration` dài hơn: Google chỉ thêm tối đa 10 giây nhưng vẫn tính toàn bộ số giây được yêu cầu. (Clip này đến từ một thử nghiệm trước với `duration: 15`.) Cùng request đó với `duration: 10` trả về đúng clip 25 giây và dùng 10 giây. Vids kéo dài clip tối đa 24 giây, nên clip 25 giây này đã dài hết mức. Để có clip dài nhất, khoảng 34 giây, hãy kéo dài một clip từ 24 giây trở xuống thêm 10 giây. #### Bước 3: chỉnh sửa cả 15 giây {: #step-3-edit-all-15-seconds .no_toc } [POST /videos/edit](/docs/api-google-vids-v1/post-google-vids-videos-edit) trên video đầu tiên với `duration: 15`. Với Omni 1.1, một lần chỉnh sửa trả về tối đa 10 giây. Giờ cả clip 15 giây được chỉnh sửa, từng khung hình, sau khoảng 140 giây. ```bash curl --location 'https://api.useapi.net/v1/google-vids/videos/edit' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "video": "user:12345-user@example.com-video:eyJ1Ijoi…", "prompt": "Make it a snowy winter evening: snow falling gently over the rooftop and the city, the chef wearing a red knit scarf. Keep everything else the same.", "duration": 15, "async": true }' ``` <video poster="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-edit-snow-15s-poster.jpg" src="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-edit-snow-15s.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> Vids chỉnh sửa clip do Google tạo, còn video tải lên sẽ bị Google từ chối với `422`. Với một clip đơn lẻ, hãy tạo ở 1080p, vì 1080p dùng cùng hạn mức như 720p. Với clip bạn sẽ kéo dài, hãy làm ở 720p và chỉ lên 1080p một lần, ở cuối: mỗi lần kéo dài ở 1080p xử lý lại cả clip và làm các giây trước bị quá nét ([xem so sánh](/blog/261106v#720p-or-1080p-what-a-1080p-extend-does)). Hoàn thiện clip tối đa 20 giây bằng một lần [upscale](/docs/api-google-vids-v1/post-google-vids-videos-upscale) (lần này dùng lại số giây của clip), còn với clip 21 đến 34 giây thì chỉ đặt `resolution: "1080p"` ở lần kéo dài cuối cùng. Repo [google-vids-api](https://github.com/useapi/google-vids-api) trên GitHub có các ví dụ Vids chạy được bằng Node.js và Python, gồm cả avatar có giọng nói, và [hướng dẫn tạo video người có ảnh hưởng AI](/docs/articles/google-vids-influencer-avatars-vi) dựng một clip với hai avatar biết nói. ### Nên dùng cái nào Chọn Google Flow API khi bạn muốn: - bản nháp 360p với giá bằng một phần ba 720p, hoặc tối đa 4 video mỗi request - khung đầu và khung cuối, tối đa 10 ảnh tham chiếu hoặc nhân vật đã lưu - tự chọn giọng nói: tối đa 5 giọng mỗi video khi có ảnh tham chiếu hoặc nhân vật và tối đa 3 mỗi lần kéo dài, từ 30 giọng có sẵn hoặc giọng của bạn - chỉnh sửa video tải lên, hoặc upscale lên 4K trên Ultra - video Veo 3.1 và ảnh Nano Banana từ cùng một API - Omni 1.2 trên tài khoản Google miễn phí, tối đa 10 giây Chọn Google Vids API khi bạn muốn: - không có captcha và không cần dịch vụ giải captcha - 1080p cùng giá với 720p (với clip bạn sẽ kéo dài hoặc chỉnh sửa, xem [nên làm ở độ phân giải nào](#vids-resolution)) - avatar có giọng nói giữ nguyên ngoại hình và giọng từ video này sang video khác, tối đa 3 avatar trong một video - giá mỗi giây thấp nhất trên Ultra $199,99, $0,02 so với $0,032 cho một video 15 giây trong Flow - thêm video Omni 1.2 khi đã dùng hết credit Flow, vì Vids có hạn mức riêng Hoặc dùng cả hai: kết nối cùng một tài khoản Google với mỗi API và gửi job tới nơi phù hợp, vì hai [hạn mức được cộng dồn](#price-per-video). ### Dùng từ Claude Code, Cursor hoặc Gemini CLI Cả hai API đều có MCP server được host sẵn, chạy bằng API token useapi.net của bạn, không cần cài gì. Trong Claude Code, mỗi server chỉ cần một dòng: ```bash claude mcp add --transport http useapi-google-vids https://api.useapi.net/v1/google-vids/mcp --header "Authorization: Bearer YOUR_API_TOKEN" claude mcp add --transport http useapi-google-flow https://api.useapi.net/v1/google-flow/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` Trong Cursor hoặc Gemini CLI, thêm cùng URL đó với cùng header `Authorization` trong phần cài đặt MCP. - [Google Vids MCP server](/docs/api-google-vids-v1/mcp) tạo clip Omni 1.2 trực tiếp: `vids_create_video` và `vids_edit_video` nhận tối đa 15 giây, còn `vids_extend_video` tối đa 10 giây mỗi lần gọi với clip tối đa 24 giây. - [Google Flow MCP server](/docs/api-google-flow-v1/mcp) làm việc với Google Flow Agent, không gọi trực tiếp các endpoint Omni 1.2: trợ lý của bạn trò chuyện với Agent, và Agent tạo ảnh và video với giá Flow thông thường. Để gọi Omni 1.2 trực tiếp từ Claude Code hoặc Codex, hãy thêm [agent skill omni-flash-video](https://github.com/useapi/google-flow-api/tree/main/skills/omni-flash-video). - Cả hai repo cũng cài server dưới dạng plugin Claude Code hoặc extension Gemini CLI: [google-flow-api](https://github.com/useapi/google-flow-api#use-with-claude-code) và [google-vids-api](https://github.com/useapi/google-vids-api#use-with-claude-code). ### Câu hỏi thường gặp #### Gemini Omni 1.2 Flash có API không? Qua useapi.net thì có: Gemini Omni 1.2 Flash chạy trên gói Google AI của bạn, qua [Google Flow API](/docs/api-google-flow-v1) (`model: "omni-flash-1.2"`) và [Google Vids API](/docs/api-google-vids-v1), không cần Gemini API key. Giá từ $0,02 mỗi giây hạn mức Vids của Ultra $199,99, so với khoảng $0,07 mỗi giây trên [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) của Google. Flow nhận tới 5 giọng mỗi video khi có ảnh tham chiếu hoặc nhân vật, còn API của Google [chỉ mở tham chiếu âm thanh cho danh sách được duyệt](https://cloud.google.com/blog/products/ai-machine-learning/gemini-omni-1-2-flash-generally-available) (tính đến tháng 11/2026). #### Giá Omni 1.2 Flash mỗi video là bao nhiêu? Qua useapi.net trên Google AI Ultra $199,99, một video Omni 1.2 Flash dài 15 giây dùng $0,30 hạn mức Vids của gói hoặc $0,48 credit Flow, so với $1,04 ở 720p trên Gemini API của Google (tính đến tháng 11/2026). Trong Vids, một video 1080p dài 15 giây cũng chỉ $0,30, vì 1080p dùng cùng số giây, trong khi Gemini API tính $1,56. [Bảng giá](#price-per-video) liệt kê mọi gói. #### Có Gemini Omni 1.2 Flash API miễn phí không? Qua useapi.net thì có, trong Google Flow API: tài khoản Google miễn phí tạo được video Omni 1.2 Flash tối đa 10 giây bằng [50 credit Flow mỗi ngày](https://support.google.com/flow/answer/16526234?hl=vi), tức một video 10 giây ở 720p hoặc năm video ở 360p mỗi ngày, còn Gemini API của Google chỉ có Omni 1.2 Flash ở gói trả phí (tính đến tháng 11/2026). Video dài hơn và kéo dài bằng Omni 1.2 cần gói Google AI trả phí. #### Video Omni 1.2 Flash dài tối đa bao nhiêu? Qua useapi.net, một lệnh gọi tạo 3 đến 15 giây trong cả Google Flow lẫn Google Vids, và kéo dài thêm 3 đến 10 giây mỗi lần, trả về cả clip: tới gần 40 giây trong Flow, mỗi lần kéo dài có thể dùng một giọng mới, và khoảng 34 giây trong Vids, vốn kéo dài clip tối đa 24 giây. [Cảnh 30 giây](#flow-walkthrough) ở trên được làm theo cách này bằng ba lệnh gọi. #### Omni 1.2 Flash hay Veo 3.1: nên dùng cái nào? Qua useapi.net, bạn chạy cả hai trong cùng Google Flow API trên một gói: trên Ultra $199,99, một video 720p dài 8 giây bằng Omni 1.2 Flash tốn $0,19 và bằng Veo 3.1 Fast tốn $0,08, so với $0,56 và $0,80 trên API của chính Google (tính đến tháng 11/2026). Chọn Omni 1.2 Flash cho clip dài hơn 8 giây, tối đa 5 giọng tự chọn và kéo dài với giọng mới, còn Veo 3.1 Fast cho clip 8 giây rẻ nhất. Mọi mức giá Veo: [giá Veo 3.1 API](/docs/articles/veo-3-1-api-pricing). ### Nguồn - Google Cloud, [Gemini Omni 1.2 Flash is generally available](https://cloud.google.com/blog/products/ai-machine-learning/gemini-omni-1-2-flash-generally-available), ngày 5/11/2026 - Google Workspace Updates, [Gemini Omni 1.2 Flash now in Vids](https://workspaceupdates.googleblog.com/2026/11/gemini-omni-12-flash-now-in-vids-with-15second-generations-and-improved-quality.html), ngày 5/11/2026 - Google, [Bảng giá Gemini API](https://ai.google.dev/gemini-api/docs/pricing), đọc ngày 6/11/2026 - Google Cloud, [Bảng giá Agent Platform](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing) (Veo 3.1), đọc ngày 6/11/2026 - Google, [Các gói Google AI](https://gemini.google/subscriptions/), [Credit Flow](https://support.google.com/flow/answer/16526234?hl=vi) và [Gemini trong Google Vids](https://support.google.com/docs/answer/15609411?hl=vi), đọc tháng 11/2026 - Bài thông báo của useapi.net: [Google Flow: Omni 1.2 Flash, 15-Second Videos, and Extend with Voices](/blog/261106) và [Google Vids: Omni 1.2 Flash, 15-Second Videos and 15-Second Edits](/blog/261106v), ngày 6/11/2026 ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/gemini-omni-1-2-flash-api-zh === Document URL: https://useapi.net/docs/articles/gemini-omni-1-2-flash-api-zh --- layout: default title: 如何通过 API 使用 Gemini Omni 1.2 Flash:在 Google Flow 和 Google Vids 中生成 15 秒视频(中文教程) seo_title: "Gemini Omni 1.2 Flash API 中文教程:15 秒视频、价格、延长与编辑" description: "Gemini Omni 1.2 Flash API 中文教程:通过 useapi.net 的 Google Flow API 和 Google Vids API,用 Google AI 订阅生成 3 到 15 秒带对白的视频,支持延长和 15 秒编辑,无需 Gemini API Key。" image: https://media.useapi.net/articles/2026-11-06-gemini-omni-1-2-flash-api-id/261106-gemini-omni-1-2-flash-api-cover.jpg keywords: [Gemini Omni 1.2 Flash API, Omni 1.2 Flash API, Gemini Omni 1.2 API, Gemini Omni Flash API, Omni 1.2 Flash 教程, Omni 1.2 Flash 免费, omni-flash-1.2, Omni Flash 15 秒, Gemini Omni API, Omni 1.2 Flash 价格, Veo 替代, Veo 3.1 替代, Google Flow API, Google Vids API, 视频延长, 视频编辑 API, AI 视频对白, Google AI Ultra, 无需 Gemini API Key, 中文教程, Chinese tutorial, curl] parent: Articles nav_exclude: true lang: zh-CN date: 2026-11-06 last_modified: 2026-11-11 nav_order: 909 repo: https://github.com/useapi/google-flow-api translation_key: gemini-omni-1-2-flash --- ## 如何通过 API 使用 Gemini Omni 1.2 Flash:在 Google Flow 和 Google Vids 中生成 15 秒视频(中文教程) <div class="lang-banner" lang="en"> <strong>Chinese-language tutorial.</strong> This page is written in Simplified Chinese for Chinese-speaking developers. The same material in English: <a href="/docs/articles/gemini-omni-1-2-flash-api">How to Use the Gemini Omni 1.2 Flash API: 15-Second Videos in Google Flow and Google Vids</a> · <a href="/docs/api-google-flow-v1">Google Flow API docs</a> · <a href="/docs/api-google-vids-v1">Google Vids API docs</a> </div> 8 分钟阅读 • 2026 年 11 月 6 日 useapi.net 是第三方 API,与 Google 无关联,也未获得 Google 的认可。 ## 目录 ### 简介 Google 于 2026 年 11 月 5 日发布 Gemini Omni 1.2 Flash,可以生成 3 到 15 秒、带声音和对白的视频。useapi.net 通过两套 REST API 在你的 [Google AI 订阅](https://gemini.google/subscriptions/)上调用它:[Google Flow API](/docs/api-google-flow-v1) 和 [Google Vids API](/docs/api-google-vids-v1)。在 Google AI Ultra 199.99 美元档上,一条 15 秒视频约合 0.30 美元的 Vids 月度额度,或 0.48 美元的 Flow 积分,而 Google 自己的 [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) 上 720p 15 秒为 1.04 美元(截至 2026 年 11 月)。不需要 Gemini API Key,也不需要 Google Cloud 项目。 1.2 的新变化(据 Google 的[发布公告](https://cloud.google.com/blog/products/ai-machine-learning/gemini-omni-1-2-flash-generally-available)):单条视频最长 15 秒(此前为 10 秒),更贴合参考素材,口型更清晰。同一天,[Google Vids 也升级到了 Omni 1.2 Flash](https://workspaceupdates.googleblog.com/2026/11/gemini-omni-12-flash-now-in-vids-with-15second-generations-and-improved-quality.html)。 本文先对比两种调用方式,再各走一遍真实流程:在 Google Flow 里用三次调用做出一段 30 秒、两种音色的场景,再在 Google Vids 里生成一段 15 秒视频,再延长并编辑全部 15 秒。所有请求都是真实请求,所有视频都是真实生成结果,来自发布文章 [Google Flow: Omni 1.2 Flash](/blog/261106) 和 [Google Vids: Omni 1.2 Flash](/blog/261106v)(英文)。 本文由 useapi.net 维护者撰写,介绍的是我们自己的托管 API,示例代码开源在 [GitHub](https://github.com/useapi/google-flow-api)。 开始之前,你需要: - 一个 useapi.net [API Token](/docs/start-here/setup-useapi) - 用 [Setup Google Flow](/docs/start-here/setup-google-flow)、[Setup Google Vids](/docs/start-here/setup-google-vids) 或两者绑定的 Google 账号。同一个 Google 账号可以同时绑定两套 API,各自使用自己的额度。 ### Google Flow 还是 Google Vids:Omni 1.2 Flash 一览 | | [Google Flow API](/docs/api-google-flow-v1) | [Google Vids API](/docs/api-google-vids-v1) | |---|---|---| | 怎么选 Omni 1.2 | `model: "omni-flash-1.2"`(其他取值为 Omni 1.1 Flash 和 Veo 3.1) | 没有 `model` 字段:Vids 只有一个视频模型,自 11 月 5 日 Google 分批升级起为 Omni 1.2 | | 时长 | 3 到 15 秒(首尾帧模式 3 到 10 秒) | 3 到 15 秒 | | 分辨率 | 360p 或 720p,可[放大](/docs/api-google-flow-v1/post-google-flow-videos-upscale)到 1080p,Ultra 可到 4K | 720p 或 1080p,消耗相同,20 秒以内的视频可[放大](/docs/api-google-vids-v1/post-google-vids-videos-upscale)到 1080p | | 输入 | 文本、首帧、首尾帧、最多 10 张参考图、已保存的[角色](/docs/api-google-flow-v1/get-google-flow-characters),每次请求 1 到 4 条 | 文本、首帧图片,或最多 3 个参考(图片和[数字人](/docs/api-google-vids-v1/post-google-vids-avatars)混用) | | 音色 | 有参考图或角色时每条视频最多 5 个[音色](/docs/api-google-flow-v1/get-google-flow-voices),每次延长最多 3 个。可用 30 个内置音色或你自己的音色 | 每个数字人使用 30 种[音色](/docs/api-google-vids-v1/get-google-vids-voices)之一,一条视频最多 3 个数字人 | | [延长](/docs/api-google-flow-v1/post-google-flow-videos-extend) | 每次 3 到 10 秒,可带自己的音色和参考,最长不到 40 秒,需付费套餐 | [每次 3 到 10 秒](/docs/api-google-vids-v1/post-google-vids-videos-extend),源视频最长 24 秒,最终最长约 34 秒 | | 用提示词编辑 | 生成或上传的视频,[最多 15 秒](/docs/api-google-flow-v1/post-google-flow-videos#video-reference-omni-11-flash-v2v-edit) | Google 生成的视频,[最多 15 秒](/docs/api-google-vids-v1/post-google-vids-videos-edit) | | 消耗什么 | Flow 积分:720p 前 10 秒每秒 3 个,超过 10 秒的部分每秒 6 个,360p 为 1 个和 2 个 | 每月 Vids 视频秒数,与 Flow 积分分开 | | 免费 Google 账号 | 每天 50 个 Flow 积分,可生成最长 10 秒的视频 | 我们测试时没有 Vids 视频秒数 | | 验证码 | Google 对每条 Flow 视频都要求验证码。API 会替你求解:首个账号赠送 300 次,之后通过你自己注册的[打码服务](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers)求解,约每 1,000 次 0.80 到 3.00 美元 | 无 | ### 每条视频的价格 一条 15 秒 Omni 1.2 Flash 视频在 Google 自己的 [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) 和各个 Google AI 订阅上的价格(截至 2026 年 11 月)。每个订阅每月包含一定数量的 Flow 积分,另外还有单独的 Vids 视频秒数,所以一条视频的成本就是它占订阅费的份额。 | Omni 1.2 Flash,15 秒 | [官方 API](https://ai.google.dev/gemini-api/docs/pricing) | Ultra $199.99/月 (25,000 积分,10,000 秒/月) | Ultra $99.99/月 (10,000 积分,2,500 秒/月) | Pro $19.99/月 (1,000 积分,500 秒/月) | Plus $4.99/月 (200 积分,60 秒/月) | |---|---|---|---|---|---| | Google Flow (720p) | $1.04 (每秒约 $0.07) | $0.48 / 60 积分 (每月 416 条) | $0.60 / 60 积分 (每月 166 条) | $1.20 / 60 积分 (每月 16 条) | $1.50 / 60 积分 (每月 3 条) | | Google Flow (360p) | $0.35 (每秒 $0.023) | $0.16 / 20 积分 (每月 1,250 条) | $0.20 / 20 积分 (每月 500 条) | $0.40 / 20 积分 (每月 50 条) | $0.50 / 20 积分 (每月 10 条) | | Google Vids (720p 或 1080p) | 720p $1.04 (1080p $1.56) | $0.30 / 15 秒 (每月 666 条) | $0.60 / 15 秒 (每月 166 条) | $0.60 / 15 秒 (每月 33 条) | $1.25 / 15 秒 (每月 4 条) | - 套餐越高越划算。在 Plus 上,以及 Pro 上的 Flow,一条 720p 15 秒视频比 Gemini API 更贵。而在 Ultra 199.99 档上,Flow 不到 Gemini API 的一半,Vids 不到三分之一。 - Flow 超过 10 秒的部分按双倍计费,所以短视频每秒更便宜:720p 10 秒为 30 积分,在 Ultra 199.99 档上为 0.24 美元,Gemini API 为 0.70 美元。包含所有模型的完整 Flow 价格表见 [Google Flow API 文档](/docs/api-google-flow-v1#pricing),包含图片和数字人的 Vids 价格表见 [Google Vids API 文档](/docs/api-google-vids-v1#pricing)。 - 两套 API 的延长都只计新增的秒数。Vids 编辑最多消耗所编辑的秒数(我们测试时编辑 15 秒只消耗了 10 秒),Flow 编辑与生成同样长度的视频价格相同。 - Flow 积分和 Vids 秒数是同一个套餐里两份独立的额度。在 Ultra 199.99 档上,一个 Google 账号同时绑定两套 API,每月在 Flow 中约可生成 416 条、在 Vids 中约 666 条 720p 15 秒视频,合计约 1,082 条。 - 套餐价格为 Google 美国区价格。各套餐的 Vids 秒数来自 Google 的 [Gemini in Google Vids](https://support.google.com/docs/answer/15609411) 页面,与我们在 Ultra 199.99 档上的测试一致。 ### 在 Google Flow 中使用 Omni 1.2 Flash:三次调用做出 30 秒场景 先生成 10 秒视频,再延长两次,每次 10 秒,每次换一种音色。第 1 步用免费 Google 账号就能完成。第 2 步和第 3 步(延长)需要付费 Google AI 套餐。 每次调用都以异步任务运行:传 `async: true`,POST 会立即返回 `jobid`。然后轮询 [GET /jobs/`jobid`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid) 直到 `status` 为 `completed`,或者传 `replyUrl`,让完成的任务推送到你的 webhook: ```bash curl --location 'https://api.useapi.net/v1/google-flow/jobs/<jobid>' --header 'Authorization: Bearer YOUR_API_TOKEN' ``` 成品视频在 `response.media[0].videoUrl` 里,链接约 6 小时内有效,下一步要用的是完成任务里的 `response.media[0].mediaGenerationId`。如果你绑定了多个 Google 账号,API 会挑选一个已开通 Omni 1.2 的账号(Google 从 11 月 5 日起分几天陆续开通)。传 `email` 可以指定账号。 #### 第 1 步:先生成 10 秒 调用 [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos),`model: "omni-flash-1.2"`,`duration: 10`。Google 用了 56 秒返回结果。720p 10 秒视频消耗 30 个积分。 ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "model": "omni-flash-1.2", "duration": 10, "prompt": "Cinematic night, a narrow rainy alley in Tokyo glowing with neon signs reflected in the puddles. A street magician in a long dark coat faces the camera, fans out a deck of cards that glow faintly gold, and says with a grin: \"Pick a card. Any card.\" A sudden gust snatches one glowing card from his hand and it flutters away down the alley. Handheld camera, shallow depth of field, rain drops catching the light.", "async": true }' ``` <video poster="https://media.useapi.net/blog/2026-11-06-261106/261106-google-flow-omni-1-2-magician-first-10s-poster.jpg" src="https://media.useapi.net/blog/2026-11-06-261106/261106-google-flow-omni-1-2-magician-first-10s.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> <details markdown="block"> <summary>完成的任务,来自 <a href="/docs/api-google-flow-v1/get-google-flow-jobs-jobid">GET /jobs/<code>jobid</code></a>(节选)</summary> ```json { "jobid": "j1106021223539251070v-u12345-email:user@example.com-bot:google-flow", "type": "video", "status": "completed", "response": { "media": [ { "video": { "generatedVideo": { "model": "macaron_cookie_t2v_10s", "aspectRatio": "VIDEO_ASPECT_RATIO_LANDSCAPE" }, "dimensions": { "length": "10s" } }, "mediaGenerationId": "user:12345-email:…-video:b08556b9-…", "videoUrl": "https://flow-content.google/video/b08556b9-…?Expires=…" } ], "remainingCredits": 877 } } ``` </details> #### 第 2 步:延长 10 秒,加入音色 调用 [POST /videos/extend](/docs/api-google-flow-v1/post-google-flow-videos-extend),传入第一条视频的 `mediaGenerationId`、`duration: 10`,并把内置音色 Charon 作为 `referenceAudio_1`。提示词里用 `@referenceAudio_1` 标出魔术师说话的位置。延长默认使用 Omni 1.2,不需要传 `model`。返回的是一条 20 秒的完整视频:前 10 秒保持不变,后面接上新的 10 秒。用时 2 分 20 秒,消耗 30 个积分。 ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos/extend' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "mediaGenerationId": "user:12345-email:…-video:b08556b9-…", "duration": 10, "referenceAudio_1": "Charon", "prompt": "The magician runs after the glowing card through the rain, past a ramen stall and under paper lanterns, laughing and calling out in a deep voice @referenceAudio_1: \"Come back here! You are the ace of hearts!\" The camera follows him close behind.", "async": true }' ``` #### 第 3 步:再延长 10 秒,换第二种音色 对 20 秒的视频再调用一次,咖啡馆里的女生用 Aoede 音色。结果就是完整的 30 秒场景,又用了 2 分钟和 30 个积分。 ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos/extend' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "mediaGenerationId": "user:12345-email:…-video:113384cd-…", "duration": 10, "referenceAudio_1": "Aoede", "prompt": "The glowing card drifts through the open door of a tiny warm café and lands on a table. A young woman in a yellow raincoat picks it up, looks at the out-of-breath magician in the doorway, and says with a smile @referenceAudio_1: \"Is this your card?\" He laughs. Warm light, rain outside the window.", "async": true }' ``` <video poster="https://media.useapi.net/articles/2026-06-15-omni-flash-bash/261106-google-flow-omni-1-2-magician-extended-30s-web-poster.jpg" src="https://media.useapi.net/articles/2026-06-15-omni-flash-bash/261106-google-flow-omni-1-2-magician-extended-30s-web.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> <details markdown="block"> <summary>完成的任务(节选)</summary> ```json { "jobid": "j1106021547955542178v-u12345-email:user@example.com-bot:google-flow", "type": "video", "status": "completed", "response": { "media": [ { "video": { "generatedVideo": { "model": "macaron_cookie_extend_10s" }, "dimensions": { "length": "30s" } }, "mediaGenerationId": "user:12345-email:…-video:db0201df-…", "videoUrl": "https://flow-content.google/video/db0201df-…?Expires=…" } ], "remainingCredits": 817 } } ``` </details> 上面的视频为网页播放重新编码,保持原始的 1280×720。整个场景消耗 90 个积分,在 Ultra 199.99 档上约 0.72 美元,按 Gemini API 的 720p 价格,30 秒约 2.10 美元(截至 2026 年 11 月)。 Google 只延长短于 30 秒的视频,所以这个场景不能再延长了:第四次延长会立即返回 `400`,不会求解验证码,也不消耗积分。25 秒的视频还可以再加 10 秒,最终达到 35 秒。 GitHub 上的 [`omni-extend/`](https://github.com/useapi/google-flow-api/tree/main/omni-extend) 用一个 `story.json` 生成这个场景,提供 Node.js 和 Python 两个版本。[`omni-flash/`](https://github.com/useapi/google-flow-api/tree/main/omni-flash) 可以按提示词列表批量生成 Omni Flash 视频。参考图、角色、首尾帧和编辑的用法见 [Google Flow API 中文教程](/docs/articles/google-flow-api-zh)。 ### 在 Google Vids 中使用 Omni 1.2 Flash:15 秒视频、延长和编辑 Vids 只有一个视频模型,Google 从 11 月 5 日起用几天时间把它升级为 Omni 1.2,所以不需要设置 `model`。请求体为 JSON,下面每次调用都以异步任务运行:轮询 [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid) 或传 `replyUrl`,然后在 24 小时内用 [GET /media/`mediaId`](/docs/api-google-vids-v1/get-google-vids-media-mediaId) 下载视频。下一步要用的是完成任务里的 `result.mediaId`。Vids 不需要验证码。 ```bash curl --location 'https://api.useapi.net/v1/google-vids/jobs/<jobid>' --header 'Authorization: Bearer YOUR_API_TOKEN' ``` #### 第 1 步:一个提示词生成 15 秒视频 调用 [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos),`duration: 15`。Google 约 60 秒返回一条 1280×720 的视频,两句台词都按原文说出。消耗了 15 秒额度。 ```bash curl --location 'https://api.useapi.net/v1/google-vids/videos' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "prompt": "Cinematic single continuous shot, 15 seconds, 16:9. Golden hour on a Tokyo rooftop garden, city skyline glowing behind. A young chef in a crisp white apron finishes plating a steaming bowl of ramen, steam curling in the warm light. She looks up into the camera and says with a confident smile: \"Fifteen seconds. One prompt. No editing.\" She slides the bowl toward the camera as it slowly pushes in, wind chimes ringing softly and city traffic humming far below. She laughs and adds: \"Now that'\''s fast food.\"", "duration": 15, "aspectRatio": "landscape", "resolution": "720p", "async": true }' ``` <video poster="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-15s-poster.jpg" src="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-15s.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> <details markdown="block"> <summary>完成的任务,来自 <a href="/docs/api-google-vids-v1/get-google-vids-jobs-jobid">GET /jobs/<code>jobid</code></a>(节选)</summary> ```json { "status": "completed", "result": { "mediaId": "user:12345-user@example.com-video:eyJ1Ijoi…", "width": 1280, "height": 720, "duration": 15, "resolution": "720p", "aspectRatio": "landscape", "model": "/flix/generate_videos_omni_t2v_psq/v1", "quota": { "video": { "limit": 500, "left": 485, "resetAt": "2026-12-01T08:00:00.000Z" } } } } ``` </details> `quota` 显示账号本月剩余的视频秒数和重置时间。这个测试账号是 Google AI Pro 套餐,所以上限是 500 秒。本文的价格按 Ultra 199.99 档计算。 #### 第 2 步:延长 10 秒 调用 [POST /videos/extend](/docs/api-google-vids-v1/post-google-vids-videos-extend),传入第一条视频的 `mediaId`。结果是一条完整的 25 秒视频:原来的 15 秒加上新的 10 秒,用时约 100 秒。一位朋友走进画面尝了拉面,两句新台词都说了出来。 ```bash curl --location 'https://api.useapi.net/v1/google-vids/videos/extend' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "mediaId": "user:12345-user@example.com-video:eyJ1Ijoi…", "prompt": "Same shot continues on the Tokyo rooftop at dusk, the city lights now switching on. A friend in a denim jacket walks into frame, sits at the table and takes a first slurp of the ramen, eyes widening. He says: \"Wait, you made this in fifteen seconds?\" The chef folds her arms and grins: \"Fifteen more, and I'\''ll make dessert.\" They both laugh as string lights flicker on above them and soft city ambience fills the air.", "duration": 10, "async": true }' ``` <video poster="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-extend-25s-poster.jpg" src="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-extend-25s.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> YouTube 视频:[Gemini Omni 1.2 Flash in Google Vids: 15 seconds from one prompt, extended to 25](https://www.youtube.com/watch?v=eJ3js18XCBM)。 API 每次延长接受 3 到 10 秒,更长的 `duration` 会返回 `400`:Google 最多只加 10 秒,却按请求的全部秒数计费。(这条视频来自更早一次用 `duration: 15` 的测试。)同样的请求用 `duration: 10` 会得到同样的 25 秒视频,只消耗 10 秒。Vids 只能延长 24 秒以内的视频,所以这条 25 秒的视频已经不能再延长。要做出最长约 34 秒的视频,请对 24 秒以内的视频再延长 10 秒。 #### 第 3 步:编辑全部 15 秒 对第一条视频调用 [POST /videos/edit](/docs/api-google-vids-v1/post-google-vids-videos-edit),`duration: 15`。Omni 1.1 的编辑最多只返回 10 秒,现在整条 15 秒视频的每一帧都被编辑了,用时约 140 秒。 ```bash curl --location 'https://api.useapi.net/v1/google-vids/videos/edit' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "video": "user:12345-user@example.com-video:eyJ1Ijoi…", "prompt": "Make it a snowy winter evening: snow falling gently over the rooftop and the city, the chef wearing a red knit scarf. Keep everything else the same.", "duration": 15, "async": true }' ``` <video poster="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-edit-snow-15s-poster.jpg" src="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-edit-snow-15s.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> Vids 只能编辑 Google 生成的视频,上传的视频会被 Google 以 `422` 拒绝。 单条视频直接用 1080p 生成,消耗与 720p 相同。要延长的视频用 720p 制作,最后只做一次 1080p:在 1080p 下每延长一次,Google 都会把整条视频重新处理一遍,之前的画面会被过度锐化([对比视频](/blog/261106v#720p-or-1080p-what-a-1080p-extend-does))。不超过 20 秒的视频最后[放大](/docs/api-google-vids-v1/post-google-vids-videos-upscale)一次(放大会再次消耗视频的秒数)。21 到 34 秒的视频只在最后一次延长时设置 `resolution: "1080p"`。 GitHub 上的 [google-vids-api](https://github.com/useapi/google-vids-api) 有可直接运行的 Vids 示例(Node.js 和 Python),包括带配音的数字人。[Google Vids API 中文教程](/docs/articles/google-vids-api-zh)一步步做出两个会说话的数字人。 ### 选哪一个 以下情况选 Google Flow API: - 想用 360p 出草稿,价格是 720p 的三分之一,或者一次请求生成最多 4 条 - 需要首尾帧、最多 10 张参考图或已保存的角色 - 想自己指定音色:有参考图或角色时每条视频最多 5 个,每次延长最多 3 个,可从 30 个内置音色或你自己的音色中选 - 要编辑上传的视频,或在 Ultra 上放大到 4K - 想在同一套 API 里同时用 Veo 3.1 视频和 Nano Banana 图片 - 用免费 Google 账号生成最长 10 秒的 Omni 1.2 视频 以下情况选 Google Vids API: - 不想处理验证码,也不想接打码服务 - 想用 1080p,且价格和 720p 一样(要延长或编辑的视频,见[用哪种分辨率](#vids-resolution)) - 需要带配音的数字人,在不同视频之间保持同样的外貌和声音,一条视频最多 3 个 - 想在 Ultra 199.99 档上拿到最低的每秒价格:0.02 美元,Flow 的 15 秒视频为每秒 0.032 美元 - Flow 积分用完后继续生成 Omni 1.2 视频,因为 Vids 有自己的额度 也可以两者都用:把同一个 Google 账号绑定到两套 API,把任务分配到最合适的一边,两份[额度可以叠加](#price-per-video)。 ### 在 Claude Code、Cursor 或 Gemini CLI 中使用 两套 API 都有托管的 MCP 服务器,使用你的 useapi.net API Token,无需安装。在 Claude Code 中各一行命令: ```bash claude mcp add --transport http useapi-google-vids https://api.useapi.net/v1/google-vids/mcp --header "Authorization: Bearer YOUR_API_TOKEN" claude mcp add --transport http useapi-google-flow https://api.useapi.net/v1/google-flow/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` 在 Cursor 或 Gemini CLI 中,在 MCP 设置里添加同样的 URL 和同样的 `Authorization` 请求头即可。 - [Google Vids MCP 服务器](/docs/api-google-vids-v1/mcp)直接生成 Omni 1.2 视频:`vids_create_video` 和 `vids_edit_video` 最多 15 秒,`vids_extend_video` 每次最多 10 秒,只延长 24 秒以内的视频。 - [Google Flow MCP 服务器](/docs/api-google-flow-v1/mcp)对接的是 Google Flow Agent,不直接调用 Omni 1.2 接口:你的 AI 助手与 Agent 对话,Agent 生成图片和视频按 Flow 的正常价格计费。如果想让 Claude Code 或 Codex 直接调用上面的 Omni 1.2 接口,可以安装 [omni-flash-video 智能体技能](https://github.com/useapi/google-flow-api/tree/main/skills/omni-flash-video)。 - 两个仓库也都可以一步安装为 Claude Code 插件或 Gemini CLI 扩展:[google-flow-api](https://github.com/useapi/google-flow-api#use-with-claude-code) 和 [google-vids-api](https://github.com/useapi/google-vids-api#use-with-claude-code)。 ### 常见问题 #### 有 Gemini Omni 1.2 Flash API 吗? 通过 useapi.net 可以:它在你的 Google AI 订阅上运行 Gemini Omni 1.2 Flash,提供 [Google Flow API](/docs/api-google-flow-v1)(`model: "omni-flash-1.2"`)和 [Google Vids API](/docs/api-google-vids-v1) 两套 REST API,不需要 Gemini API Key。Ultra 199.99 档的 Vids 额度折合每秒 0.02 美元起,Google 的 [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) 约每秒 0.07 美元。Flow 在有参考图或角色时每条视频最多可用 5 个音色,而 Google 的 API [音频参考需要申请白名单](https://cloud.google.com/blog/products/ai-machine-learning/gemini-omni-1-2-flash-generally-available)(截至 2026 年 11 月)。 #### Omni 1.2 Flash 每条视频多少钱? 通过 useapi.net,在 Google AI Ultra 199.99 档上,一条 15 秒 Omni 1.2 Flash 视频约合 0.30 美元的 Vids 额度,或 0.48 美元的 Flow 积分,Google 的 Gemini API 上 720p 为 1.04 美元(截至 2026 年 11 月)。Vids 的 1080p 与 720p 消耗相同秒数,所以 1080p 15 秒同样约 0.30 美元,而 Gemini API 上为 1.56 美元。各套餐价格见[价格表](#price-per-video)。 #### Gemini Omni 1.2 Flash 可以免费用吗? 通过 useapi.net 的 Google Flow API 可以:免费 Google 账号用[每天 50 个 Flow 积分](https://support.google.com/flow/answer/16526234)生成最长 10 秒的 Omni 1.2 Flash 视频,每天可生成一条 720p 或五条 360p 的 10 秒视频,而 Google 的 Gemini API 只在付费层级提供 Omni 1.2 Flash(截至 2026 年 11 月)。更长的视频和用 Omni 1.2 延长需要付费 Google AI 套餐。 #### Omni 1.2 Flash 视频最长多长? 通过 useapi.net,Google Flow 和 Google Vids 单次都能生成 3 到 15 秒,延长每次加 3 到 10 秒并返回完整视频:Flow 最长不到 40 秒,每次延长都可以换新音色,Vids 只延长 24 秒以内的视频,最长约 34 秒。上面的 [30 秒场景](#flow-walkthrough)就是这样用三次调用做出来的。 #### Omni 1.2 Flash 和 Veo 3.1 怎么选? 通过 useapi.net,两者在同一套 Google Flow API、同一个套餐上运行:在 Ultra 199.99 档上,720p 8 秒的 Omni 1.2 Flash 视频为 0.19 美元,Veo 3.1 Fast 为 0.08 美元,Google 自己的 API 分别为 0.56 美元和 0.80 美元(截至 2026 年 11 月)。超过 8 秒、要自选最多 5 个音色、或要延长并换新音色时选 Omni 1.2 Flash,只要最便宜的 8 秒视频时选 Veo 3.1 Fast。Veo 的全部价格见 [Veo 3.1 API 价格(英文)](/docs/articles/veo-3-1-api-pricing)。 ### 来源 - Google Cloud,[Gemini Omni 1.2 Flash is generally available](https://cloud.google.com/blog/products/ai-machine-learning/gemini-omni-1-2-flash-generally-available),2026 年 11 月 5 日 - Google Workspace Updates,[Gemini Omni 1.2 Flash now in Vids](https://workspaceupdates.googleblog.com/2026/11/gemini-omni-12-flash-now-in-vids-with-15second-generations-and-improved-quality.html),2026 年 11 月 5 日 - Google,[Gemini API 价格](https://ai.google.dev/gemini-api/docs/pricing),2026 年 11 月 6 日读取 - Google Cloud,[Agent Platform 价格](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing)(Veo 3.1),2026 年 11 月 6 日读取 - Google,[Google AI 套餐](https://gemini.google/subscriptions/)、[Flow 积分](https://support.google.com/flow/answer/16526234)和 [Gemini in Google Vids](https://support.google.com/docs/answer/15609411),2026 年 11 月读取 - useapi.net 发布文章(英文):[Google Flow: Omni 1.2 Flash, 15-Second Videos, and Extend with Voices](/blog/261106) 和 [Google Vids: Omni 1.2 Flash, 15-Second Videos and 15-Second Edits](/blog/261106v),2026 年 11 月 6 日 ### 结语 有问题欢迎加入我们的 <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord 服务器</a> 或 <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram 频道</a>。 ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/gemini-omni-1-2-flash-api === Document URL: https://useapi.net/docs/articles/gemini-omni-1-2-flash-api --- layout: default title: "How to Use the Gemini Omni 1.2 Flash API: 15-Second Videos in Google Flow and Google Vids" seo_title: "Gemini Omni 1.2 Flash API: 15-Second Videos and Price" description: "Gemini Omni 1.2 Flash API via useapi.net: 3 to 15 second videos with voices in Google Flow and Vids, $0.30 per 15 s on Ultra $199.99 vs $1.04 on the Gemini API." image: https://media.useapi.net/articles/2026-11-06-gemini-omni-1-2-flash-api-id/261106-gemini-omni-1-2-flash-api-cover.jpg keywords: [Gemini Omni 1.2 Flash API, Omni 1.2 Flash API, gemini omni 1.2 api, omni-flash-1.2, Omni Flash 15 seconds, Gemini Omni API, Gemini Omni Flash API, Omni 1.2 Flash price, Veo alternative, Veo 3.1 alternative, Google Flow API, Google Vids API, extend video, video editing API, AI video with voices, Google AI Ultra, no Gemini API key, tutorial, curl] parent: Articles nav_exclude: true date: 2026-11-06 last_modified: 2026-11-11 nav_order: 908 repo: https://github.com/useapi/google-flow-api translation_key: gemini-omni-1-2-flash --- ## How to Use the Gemini Omni 1.2 Flash API: 15-Second Videos in Google Flow and Google Vids 7 min read • November 6, 2026 (November 11, 2026) ## Table of contents ### Introduction Gemini Omni 1.2 Flash, which Google released on November 5, 2026, makes videos of 3 to 15 seconds with sound and speech, and useapi.net runs it on your [Google AI subscription](https://gemini.google/subscriptions/) through two REST APIs: the [Google Flow API](/docs/api-google-flow-v1) and the [Google Vids API](/docs/api-google-vids-v1). On Google AI Ultra $199.99, a 15-second video uses $0.30 of the plan's monthly Vids allowance or $0.48 of its Flow credits, against $1.04 for 15 seconds at 720p on Google's own [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) (as of November 2026). You need no Gemini API key and no Google Cloud project. New in 1.2, per Google's [announcement](https://cloud.google.com/blog/products/ai-machine-learning/gemini-omni-1-2-flash-generally-available): clips of up to 15 seconds instead of 10, closer adherence to references and clearer lip-sync, and Google moved [Google Vids to it](https://workspaceupdates.googleblog.com/2026/11/gemini-omni-12-flash-now-in-vids-with-15second-generations-and-improved-quality.html) the same day. This guide puts the two routes side by side, then walks through one real scene in each: a 30-second scene in Google Flow made in three calls, with two voices, and a 15-second scene in Google Vids with an extension and a 15-second edit. Every request is the real one and every video is the real output, from the release posts [Google Flow: Omni 1.2 Flash](/blog/261106) and [Google Vids: Omni 1.2 Flash](/blog/261106v). Before you start, you need: - a useapi.net [API token](/docs/start-here/setup-useapi) - a Google account connected with [Setup Google Flow](/docs/start-here/setup-google-flow), [Setup Google Vids](/docs/start-here/setup-google-vids), or both. One Google account can be connected to both APIs, and each keeps its own allowance. ### Google Flow or Google Vids: Omni 1.2 Flash at a glance | | [Google Flow API](/docs/api-google-flow-v1) | [Google Vids API](/docs/api-google-vids-v1) | |---|---|---| | How to pick Omni 1.2 | `model: "omni-flash-1.2"` (Omni 1.1 Flash and Veo 3.1 are other values) | No `model` field: Vids has one video model, Omni 1.2 since Google's rollout from November 5 | | Length | 3 to 15 seconds (3 to 10 with a start and an end frame) | 3 to 15 seconds | | Resolution | 360p or 720p, [upscale](/docs/api-google-flow-v1/post-google-flow-videos-upscale) to 1080p, or 4K on Ultra | 720p or 1080p at the same price, [upscale](/docs/api-google-vids-v1/post-google-vids-videos-upscale) to 1080p on clips of up to 20 seconds | | Inputs | Text, a start frame, a start and an end frame, up to 10 reference images, saved [characters](/docs/api-google-flow-v1/get-google-flow-characters), 1 to 4 videos per request | Text, a start image, or up to 3 references that mix images and [avatars](/docs/api-google-vids-v1/post-google-vids-avatars) | | Voices | Up to 5 [voices](/docs/api-google-flow-v1/get-google-flow-voices) per video when it has a reference image or character, up to 3 per extension. 30 built-in voices or your own | Each avatar speaks in one of 30 [voices](/docs/api-google-vids-v1/get-google-vids-voices), up to 3 avatars per video | | [Extend](/docs/api-google-flow-v1/post-google-flow-videos-extend) | 3 to 10 seconds a call with its own voices and references, to just under 40 seconds, paid plans | [3 to 10 seconds a call](/docs/api-google-vids-v1/post-google-vids-videos-extend) on clips of up to 24 seconds, to about 34 seconds | | Edit by prompt | [Up to 15 seconds](/docs/api-google-flow-v1/post-google-flow-videos#video-reference-omni-11-flash-v2v-edit) of a generated or uploaded clip | [Up to 15 seconds](/docs/api-google-vids-v1/post-google-vids-videos-edit) of a clip Google made | | What it uses | Flow credits: at 720p 3 a second up to 10 seconds and 6 a second above, at 360p 1 and 2 | Seconds of the monthly Vids allowance, separate from Flow credits | | Free Google account | Videos of up to 10 seconds on 50 Flow credits a day | No Vids video seconds in our tests | | Captcha | Google asks for a captcha on every Flow video. The API solves it for you: 300 free, then through a [captcha provider](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers) you sign up with, at about $0.80 to $3.00 per 1,000 | None | ### Price per video What one 15-second Omni 1.2 Flash video costs on Google's own [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) and on each Google AI subscription (as of November 2026). Each subscription comes with a monthly number of Flow credits and, separately, seconds of Vids video, so a video costs its share of the subscription. | Omni 1.2 Flash, 15 s | [Official API](https://ai.google.dev/gemini-api/docs/pricing) | Ultra $199.99/m (25,000 cr, 10,000 s/mo) | Ultra $99.99/m (10,000 cr, 2,500 s/mo) | Pro $19.99/m (1,000 cr, 500 s/mo) | Plus $4.99/m (200 cr, 60 s/mo) | |---|---|---|---|---|---| | Google Flow (720p) | $1.04 (about $0.07 a second) | $0.48 / 60 cr (416 videos/mo) | $0.60 / 60 cr (166 videos/mo) | $1.20 / 60 cr (16 videos/mo) | $1.50 / 60 cr (3 videos/mo) | | Google Flow (360p) | $0.35 ($0.023 a second) | $0.16 / 20 cr (1,250 videos/mo) | $0.20 / 20 cr (500 videos/mo) | $0.40 / 20 cr (50 videos/mo) | $0.50 / 20 cr (10 videos/mo) | | Google Vids (720p or 1080p) | $1.04 at 720p ($1.56 at 1080p) | $0.30 / 15 s (666 videos/mo) | $0.60 / 15 s (166 videos/mo) | $0.60 / 15 s (33 videos/mo) | $1.25 / 15 s (4 videos/mo) | - The savings grow with the plan. On Plus, and on Pro in Flow, a 15-second 720p video costs more than on the Gemini API, while on Ultra $199.99 it costs less than half in Flow and less than a third in Vids. - Flow charges every second past 10 at twice the rate, so shorter videos cost less per second there: a 10-second 720p video is 30 credits, $0.24 on Ultra $199.99, against $0.70 on the Gemini API. The full Flow table with every model is on the [Google Flow API overview](/docs/api-google-flow-v1#pricing), and the Vids table, with images and avatars, on the [Google Vids API overview](/docs/api-google-vids-v1#pricing). - An extension uses only the seconds it adds, in both APIs. A Vids edit uses at most the seconds it edits (in our tests a 15-second edit used 10), and a Flow edit costs the same as a video of the edited length. - Flow credits and Vids seconds are two separate allowances on the same plan. On Ultra $199.99, one Google account connected to both APIs makes about 416 fifteen-second 720p videos in Flow and 666 in Vids a month, about 1,082 in all. - Plan prices are Google's US prices. Vids seconds per plan are from Google's [Gemini in Google Vids](https://support.google.com/docs/answer/15609411) page and match our tests on Ultra $199.99. ### Omni 1.2 Flash in Google Flow: a 30-second scene in three calls A 10-second video, then two 10-second extensions, each with its own voice. Step 1 works on a free Google account. Steps 2 and 3 (extend) need a paid Google AI plan. Every call runs as an async job: pass `async: true` and the POST answers with a `jobid` right away. Poll [GET /jobs/`jobid`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid) until `status` is `completed`, or pass `replyUrl` to get the finished job on your webhook: ```bash curl --location 'https://api.useapi.net/v1/google-flow/jobs/<jobid>' --header 'Authorization: Bearer YOUR_API_TOKEN' ``` The finished video is at `response.media[0].videoUrl`, a link that stays valid for about 6 hours, and the next step takes the finished job's `response.media[0].mediaGenerationId`. If you've connected several Google accounts, the API picks one that already has Omni 1.2 (Google is enabling it over several days from November 5). Pass `email` to choose one. #### Step 1: the first 10 seconds [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) with `model: "omni-flash-1.2"` and `duration: 10`. Google answered in 56 seconds. At 720p a 10-second video is 30 credits. ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "model": "omni-flash-1.2", "duration": 10, "prompt": "Cinematic night, a narrow rainy alley in Tokyo glowing with neon signs reflected in the puddles. A street magician in a long dark coat faces the camera, fans out a deck of cards that glow faintly gold, and says with a grin: \"Pick a card. Any card.\" A sudden gust snatches one glowing card from his hand and it flutters away down the alley. Handheld camera, shallow depth of field, rain drops catching the light.", "async": true }' ``` <video poster="https://media.useapi.net/blog/2026-11-06-261106/261106-google-flow-omni-1-2-magician-first-10s-poster.jpg" src="https://media.useapi.net/blog/2026-11-06-261106/261106-google-flow-omni-1-2-magician-first-10s.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> <details markdown="block"> <summary>The finished job, from <a href="/docs/api-google-flow-v1/get-google-flow-jobs-jobid">GET /jobs/<code>jobid</code></a> (shortened)</summary> ```json { "jobid": "j1106021223539251070v-u12345-email:user@example.com-bot:google-flow", "type": "video", "status": "completed", "response": { "media": [ { "video": { "generatedVideo": { "model": "macaron_cookie_t2v_10s", "aspectRatio": "VIDEO_ASPECT_RATIO_LANDSCAPE" }, "dimensions": { "length": "10s" } }, "mediaGenerationId": "user:12345-email:…-video:b08556b9-…", "videoUrl": "https://flow-content.google/video/b08556b9-…?Expires=…" } ], "remainingCredits": 877 } } ``` </details> #### Step 2: extend by 10 seconds, with a voice [POST /videos/extend](/docs/api-google-flow-v1/post-google-flow-videos-extend) with the first video's `mediaGenerationId`, `duration: 10` and the built-in voice Charon as `referenceAudio_1`. The prompt places the voice where the magician speaks, with the inline mention `@referenceAudio_1`. Extend uses Omni 1.2 by default, so no `model` is needed. The answer is one 20-second clip, the first 10 seconds unchanged plus the new 10, after 2 minutes 20 seconds, for 30 credits. ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos/extend' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "mediaGenerationId": "user:12345-email:…-video:b08556b9-…", "duration": 10, "referenceAudio_1": "Charon", "prompt": "The magician runs after the glowing card through the rain, past a ramen stall and under paper lanterns, laughing and calling out in a deep voice @referenceAudio_1: \"Come back here! You are the ace of hearts!\" The camera follows him close behind.", "async": true }' ``` #### Step 3: 10 more seconds, a second voice The same call on the 20-second clip, with the voice Aoede for the woman in the café. The result is the whole scene, 30 seconds long, after another 2 minutes and 30 credits. ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos/extend' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "mediaGenerationId": "user:12345-email:…-video:113384cd-…", "duration": 10, "referenceAudio_1": "Aoede", "prompt": "The glowing card drifts through the open door of a tiny warm café and lands on a table. A young woman in a yellow raincoat picks it up, looks at the out-of-breath magician in the doorway, and says with a smile @referenceAudio_1: \"Is this your card?\" He laughs. Warm light, rain outside the window.", "async": true }' ``` <video poster="https://media.useapi.net/articles/2026-06-15-omni-flash-bash/261106-google-flow-omni-1-2-magician-extended-30s-web-poster.jpg" src="https://media.useapi.net/articles/2026-06-15-omni-flash-bash/261106-google-flow-omni-1-2-magician-extended-30s-web.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> <details markdown="block"> <summary>The finished job (shortened)</summary> ```json { "jobid": "j1106021547955542178v-u12345-email:user@example.com-bot:google-flow", "type": "video", "status": "completed", "response": { "media": [ { "video": { "generatedVideo": { "model": "macaron_cookie_extend_10s" }, "dimensions": { "length": "30s" } }, "mediaGenerationId": "user:12345-email:…-video:db0201df-…", "videoUrl": "https://flow-content.google/video/db0201df-…?Expires=…" } ], "remainingCredits": 817 } } ``` </details> The video above is re-encoded for the web at the original 1280×720. The whole scene used 90 credits, about $0.72 on Ultra $199.99, against about $2.10 for 30 seconds at the Gemini API's 720p rate (as of November 2026). Google extends videos shorter than 30 seconds only, so this scene can grow no further: a fourth extend answers `400` right away, before any captcha or credits. A 25-second clip can still take 10 more and end at 35. [`omni-extend/`](https://github.com/useapi/google-flow-api/tree/main/omni-extend) on GitHub makes this scene from one `story.json`, in Node.js or Python, and [`omni-flash/`](https://github.com/useapi/google-flow-api/tree/main/omni-flash) batch-generates Omni Flash videos from a list of prompts. The [Omni Flash tutorial](/docs/articles/omni-flash-bash) covers reference images, characters, start and end frames and edits. ### Omni 1.2 Flash in Google Vids: 15 seconds, an extend and an edit Vids has one video model, which Google moved to Omni 1.2 in a rollout of a few days from November 5, so there is no `model` to set. Requests take a JSON body, and every call here runs as an async job: poll [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid) or pass `replyUrl`, then download the clip with [GET /media/`mediaId`](/docs/api-google-vids-v1/get-google-vids-media-mediaId) within 24 hours. The next step takes the finished job's `result.mediaId`. Vids asks for no captcha. ```bash curl --location 'https://api.useapi.net/v1/google-vids/jobs/<jobid>' --header 'Authorization: Bearer YOUR_API_TOKEN' ``` #### Step 1: a 15-second video from one prompt [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) with `duration: 15`. Google answered in about 60 seconds with a 1280×720 video, and both lines are spoken as written. It used 15 seconds of the allowance. ```bash curl --location 'https://api.useapi.net/v1/google-vids/videos' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "prompt": "Cinematic single continuous shot, 15 seconds, 16:9. Golden hour on a Tokyo rooftop garden, city skyline glowing behind. A young chef in a crisp white apron finishes plating a steaming bowl of ramen, steam curling in the warm light. She looks up into the camera and says with a confident smile: \"Fifteen seconds. One prompt. No editing.\" She slides the bowl toward the camera as it slowly pushes in, wind chimes ringing softly and city traffic humming far below. She laughs and adds: \"Now that'\''s fast food.\"", "duration": 15, "aspectRatio": "landscape", "resolution": "720p", "async": true }' ``` <video poster="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-15s-poster.jpg" src="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-15s.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> <details markdown="block"> <summary>The finished job, from <a href="/docs/api-google-vids-v1/get-google-vids-jobs-jobid">GET /jobs/<code>jobid</code></a> (shortened)</summary> ```json { "status": "completed", "result": { "mediaId": "user:12345-user@example.com-video:eyJ1Ijoi…", "width": 1280, "height": 720, "duration": 15, "resolution": "720p", "aspectRatio": "landscape", "model": "/flix/generate_videos_omni_t2v_psq/v1", "quota": { "video": { "limit": 500, "left": 485, "resetAt": "2026-12-01T08:00:00.000Z" } } } } ``` </details> `quota` shows what the account has left of its monthly video seconds and when they reset. This test account is on Google AI Pro, hence the limit of 500 seconds. The prices on this page use Ultra $199.99. #### Step 2: extend it by 10 seconds [POST /videos/extend](/docs/api-google-vids-v1/post-google-vids-videos-extend) with the first video's `mediaId`. The result is one clip, the 15 seconds plus 10 new ones, 25 seconds long, after about 100 seconds. A friend walks in, tries the ramen, and both new lines are spoken. ```bash curl --location 'https://api.useapi.net/v1/google-vids/videos/extend' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "mediaId": "user:12345-user@example.com-video:eyJ1Ijoi…", "prompt": "Same shot continues on the Tokyo rooftop at dusk, the city lights now switching on. A friend in a denim jacket walks into frame, sits at the table and takes a first slurp of the ramen, eyes widening. He says: \"Wait, you made this in fifteen seconds?\" The chef folds her arms and grins: \"Fifteen more, and I'\''ll make dessert.\" They both laugh as string lights flicker on above them and soft city ambience fills the air.", "duration": 10, "async": true }' ``` <video poster="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-extend-25s-poster.jpg" src="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-extend-25s.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> Also on YouTube: [Gemini Omni 1.2 Flash in Google Vids: 15 seconds from one prompt, extended to 25](https://www.youtube.com/watch?v=eJ3js18XCBM). The API takes 3 to 10 seconds per extend call and answers a longer `duration` with `400`: Google adds at most 10 seconds but counts all the seconds requested. (This clip came from an earlier test with `duration: 15`.) The same request with `duration: 10` returns the same 25-second clip and uses 10 seconds. Vids extends clips of up to 24 seconds, so this 25-second clip is as long as it gets. To reach the longest clip, about 34 seconds, extend a clip of 24 seconds or less by 10. #### Step 3: edit all 15 seconds [POST /videos/edit](/docs/api-google-vids-v1/post-google-vids-videos-edit) on the first video with `duration: 15`. With Omni 1.1 an edit returned at most 10 seconds. Now the whole 15-second clip came back edited, every frame of it, after about 140 seconds. ```bash curl --location 'https://api.useapi.net/v1/google-vids/videos/edit' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "video": "user:12345-user@example.com-video:eyJ1Ijoi…", "prompt": "Make it a snowy winter evening: snow falling gently over the rooftop and the city, the chef wearing a red knit scarf. Keep everything else the same.", "duration": 15, "async": true }' ``` <video poster="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-edit-snow-15s-poster.jpg" src="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-edit-snow-15s.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> Vids edits clips Google made, and Google refuses uploaded videos with `422`. For a single clip, generate at 1080p, which uses the same allowance as 720p. For a clip you'll extend, work at 720p and go to 1080p once, at the end: each extend at 1080p processes the whole clip again and over-sharpens the earlier seconds ([see the comparison](/blog/261106v#720p-or-1080p-what-a-1080p-extend-does)). Finish a clip of up to 20 seconds with one [upscale](/docs/api-google-vids-v1/post-google-vids-videos-upscale) (it uses the clip's seconds again), and for a clip of 21 to 34 seconds set `resolution: "1080p"` on the last extend only. The [google-vids-api](https://github.com/useapi/google-vids-api) repo on GitHub has runnable Vids examples in Node.js and Python, including voiced avatars, and the [AI influencer tutorial](/docs/articles/google-vids-influencer-avatars) builds a clip with two talking avatars. ### Which one to use Pick the Google Flow API when you want: - 360p drafts at a third of the 720p price, or up to 4 videos per request - a start and an end frame, up to 10 reference images or saved characters - to choose the voices yourself: up to 5 per video with a reference image or character and up to 3 per extension, from 30 built-in voices or your own - to edit an uploaded video, or to upscale to 4K on Ultra - Veo 3.1 video and Nano Banana images from the same API - Omni 1.2 on a free Google account, up to 10 seconds Pick the Google Vids API when you want: - no captcha and no captcha provider - 1080p at the same price as 720p (for clips you'll extend or edit, see [which resolution to work in](#vids-resolution)) - voiced avatars that keep their look and voice from one video to the next, up to 3 in one video - the lowest price per second on Ultra $199.99, $0.02 against $0.032 for a 15-second video in Flow - more Omni 1.2 videos once your Flow credits are spent, since Vids has its own allowance Or use both: connect the same Google account to each API and send the jobs where they fit, since the two [allowances add up](#price-per-video). ### Use it from Claude Code, Cursor or Gemini CLI Both APIs have a hosted MCP server that runs on your useapi.net API token, with nothing to install. In Claude Code, each is one line: ```bash claude mcp add --transport http useapi-google-vids https://api.useapi.net/v1/google-vids/mcp --header "Authorization: Bearer YOUR_API_TOKEN" claude mcp add --transport http useapi-google-flow https://api.useapi.net/v1/google-flow/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` In Cursor or Gemini CLI, add the same URL with the same `Authorization` header in its MCP settings. - The [Google Vids MCP server](/docs/api-google-vids-v1/mcp) makes Omni 1.2 clips directly: `vids_create_video` and `vids_edit_video` take up to 15 seconds, and `vids_extend_video` up to 10 a call on clips of up to 24 seconds. - The [Google Flow MCP server](/docs/api-google-flow-v1/mcp) talks to Google Flow Agent, not to the Omni 1.2 endpoints directly: your assistant chats with the Agent, which makes images and videos at the usual Flow price. For direct Omni 1.2 calls from Claude Code or Codex, add the [omni-flash-video agent skill](https://github.com/useapi/google-flow-api/tree/main/skills/omni-flash-video). - Both repos also install the server as a Claude Code plugin or a Gemini CLI extension: [google-flow-api](https://github.com/useapi/google-flow-api#use-with-claude-code) and [google-vids-api](https://github.com/useapi/google-vids-api#use-with-claude-code). ### Questions #### Is there a Gemini Omni 1.2 Flash API? Through useapi.net, yes: it runs Gemini Omni 1.2 Flash on your Google AI subscription, through the [Google Flow API](/docs/api-google-flow-v1) (`model: "omni-flash-1.2"`) and the [Google Vids API](/docs/api-google-vids-v1), with no Gemini API key. It costs from $0.02 a second of the Ultra $199.99 Vids allowance, against about $0.07 a second on Google's [Gemini API](https://ai.google.dev/gemini-api/docs/pricing), and Flow takes up to 5 voices per video with a reference image or character, where Google's API [gates audio references behind an allowlist](https://cloud.google.com/blog/products/ai-machine-learning/gemini-omni-1-2-flash-generally-available) (as of November 2026). #### How much does Omni 1.2 Flash cost per video? Through useapi.net on Google AI Ultra $199.99, a 15-second Omni 1.2 Flash video uses $0.30 of the plan's Vids allowance or $0.48 of its Flow credits, against $1.04 at 720p on Google's Gemini API (as of November 2026). In Vids a 15-second 1080p video is also $0.30, since 1080p uses the same seconds, where the Gemini API charges $1.56. The [price table](#price-per-video) shows every plan. #### Is there a free Gemini Omni 1.2 Flash API? Through useapi.net, yes, in the Google Flow API: a free Google account makes Omni 1.2 Flash videos of up to 10 seconds on its [50 daily Flow credits](https://support.google.com/flow/answer/16526234), one 10-second video at 720p or five at 360p a day, while Google's Gemini API offers Omni 1.2 Flash on its paid tier only (as of November 2026). Longer videos and extending with Omni 1.2 need a paid Google AI plan. #### How long can an Omni 1.2 Flash video be? Through useapi.net, one call makes 3 to 15 seconds in both Google Flow and Google Vids, and extend adds 3 to 10 seconds a call and returns the whole clip: up to just under 40 seconds in Flow, with a new voice in each extension if you like, and about 34 seconds in Vids, which extends clips of up to 24 seconds. The [30-second scene](#flow-walkthrough) above was made this way in three calls. #### Omni 1.2 Flash vs Veo 3.1: which should I use? Through useapi.net you run both in the same Google Flow API on one plan: on Ultra $199.99 an 8-second 720p Omni 1.2 Flash video is $0.19 and Veo 3.1 Fast $0.08, against $0.56 and $0.80 on Google's own APIs (as of November 2026). Pick Omni 1.2 Flash for clips longer than 8 seconds, up to 5 voices you choose and extensions with new voices, and Veo 3.1 Fast for the cheapest 8-second clip. All Veo prices: [Veo 3.1 API pricing](/docs/articles/veo-3-1-api-pricing). ### Sources - Google Cloud, [Gemini Omni 1.2 Flash is generally available](https://cloud.google.com/blog/products/ai-machine-learning/gemini-omni-1-2-flash-generally-available), November 5, 2026 - Google Workspace Updates, [Gemini Omni 1.2 Flash now in Vids](https://workspaceupdates.googleblog.com/2026/11/gemini-omni-12-flash-now-in-vids-with-15second-generations-and-improved-quality.html), November 5, 2026 - Google, [Gemini API pricing](https://ai.google.dev/gemini-api/docs/pricing), read November 6, 2026 - Google Cloud, [Agent Platform pricing](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing) (Veo 3.1), read November 6, 2026 - Google, [Google AI plans](https://gemini.google/subscriptions/), [Flow credits](https://support.google.com/flow/answer/16526234) and [Gemini in Google Vids](https://support.google.com/docs/answer/15609411), read November 2026 - useapi.net release posts: [Google Flow: Omni 1.2 Flash, 15-Second Videos, and Extend with Voices](/blog/261106) and [Google Vids: Omni 1.2 Flash, 15-Second Videos and 15-Second Edits](/blog/261106v), November 6, 2026 ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-ai-subscription-api-es === Document URL: https://useapi.net/docs/articles/google-ai-subscription-api-es --- layout: default title: "¿Se puede usar la suscripción de Google AI mediante una API? Lo que te dan Plus, Pro y Ultra" seo_title: "Google AI Pro y Ultra mediante una API: lo que te da tu plan" description: "Usa Google AI Plus, Pro o Ultra mediante una API con useapi.net: un plan Ultra genera US$3.919 al mes en videos y canciones a precios de las API de Google, más imágenes." keywords: [Google AI Pro API, API de Google AI Pro, Google AI Ultra API, API de Google AI Ultra, Google AI Plus API, API de la suscripción de Google AI, Google AI Ultra incluye Gemini API, acceso a la API con Google AI Pro, Gemini suscripción API, Google One AI API, créditos de Flow API, Google Flow API, Google Vids API, Gemini Notebook API, NotebookLM API, Google Flow Music API, Lyria 3.5 API, créditos de Flow Music Google AI Pro, Veo 3.1 API, Omni 1.2 Flash API, Nano Banana API, créditos de Google Cloud, Google Developer Program, API de video con IA, Google AI subscription API] parent: Articles nav_exclude: true lang: es date: 2026-11-07 last_modified: 2026-11-07 nav_order: 910 repo: https://github.com/useapi/google-flow-api translation_key: google-ai-subscription --- ## ¿Se puede usar la suscripción de Google AI mediante una API? Lo que te dan Plus, Pro y Ultra {: .no_toc #can-you-use-your-google-ai-subscription-through-an-api-what-plus-pro-and-ultra-get-you } 6 min de lectura • 7 de noviembre de 2026 useapi.net es una API de terceros. No está afiliada a Google ni cuenta con su respaldo. ## Índice {: .no_toc .text-delta #table-of-contents } ### La respuesta corta Sí, con useapi.net. Tu [plan de Google AI](https://gemini.google/subscriptions/) (Plus, Pro o Ultra) incluye cuotas mensuales para las herramientas creativas de Google, y useapi.net convierte cada una en una API: - [Google Flow API](/docs/api-google-flow-v1): videos con tus créditos de Flow, e imágenes que no gastan ninguno - [Google Vids API](/docs/api-google-vids-v1): videos, avatares que hablan y voz con tus segundos de Vids - [Gemini Notebook API (NotebookLM API)](/docs/api-gemini-notebook-v1): podcasts, diapositivas e investigación con tu uso de Notebook - [Flow Music API](/docs/api-flowmusic-v1): canciones con los créditos de Flow Music que incluye tu plan En Ultra US$199,99, un mes de todo esto vale unos US$3.919 en las API del propio Google (a noviembre de 2026). La Gemini API en sí no forma parte del plan. Google la cobra aparte, por segundo de video y por imagen. Pro y Ultra incluyen un pequeño [crédito mensual de Google Cloud](https://developers.google.com/program/plans-and-pricing) para usarla: US$10 en Pro, US$40 en Ultra US$99,99 y US$100 en Ultra US$199,99. Incluso US$100 alcanzan solo para unos 96 videos de quince segundos de Omni 1.2 Flash allí. Los precios de esta página son los de Google en EE. UU., en dólares estadounidenses: en tu país Google puede cobrar en moneda local y el precio puede ser distinto. ### Todo lo que un plan genera en un mes Lo que suma un solo plan de Google AI cada mes con useapi.net, y lo que costaría la misma producción en las API del propio Google (en dólares estadounidenses, a noviembre de 2026). | Un mes | Ultra $199,99 | Ultra $99,99 | Pro $19,99 | Plus $4,99 | |---|---|---|---|---| | **Google Flow** (un solo saldo, elige una fila) | 25.000 cr | 10.000 cr | 1.000 cr | 200 cr | | Videos Veo 3.1 Fast (8 s, 1080p) | 2.500 | 1.000 | 50 | 10 | | o videos Veo 3.1 Lite (8 s, 1080p) | 5.000 | 2.000 | 100 | 20 | | o videos Omni 1.1 Flash (10 s, 1080p) | 1.666 | 666 | 66 | 13 | | o videos Omni 1.2 Flash (10 s, 1080p, upscale gratis) | 833 | 333 | 33 | 6 | | o videos Omni 1.2 Flash (15 s, 720p) | 416 | 166 | 16 | 3 | | o upscales de video a 4K (clips de hasta 10 s) | 500 | 200 | — | — | | **Google Flow, sin créditos** (además del saldo) | | | | | | Videos Veo 3.1 Lite (prioridad baja, 8 s) | 1.000+ al día | — | — | — | | Upscales de video a 1080p (clips de hasta 10 s) | gratis | gratis | gratis | gratis | | Imágenes Nano Banana (Pro, 2.1, 2 Lite, con upscale) | ~500 al día, 4K | incluidas, 4K | incluidas, 2K | incluidas, 2K | | **Google Vids** (cuota propia, adicional) | 10.000 s | 2.500 s | 500 s | 60 s | | Videos Omni 1.2 Flash (15 s, 1080p) | 666 | 166 | 33 | 4 | | Videos con avatar que habla (hasta 30 s) | 500 | 125 | 25 | 6 | | Imágenes (básicas, cerca de 1 MP) | 1.000 | 300 | 30 | hasta 50 | | Voz (30 voces) | incluida | incluida | incluida | incluida | | **Flow Music** (créditos propios, adicionales) | 30.000 cr | 30.000 cr | 10.000 cr | 3.000 cr | | Canciones Lyria 3.5 (canciones completas) | 6.000 | 6.000 | 2.000 | 600 | | **Gemini Notebook** (límites propios, adicionales) | | | | | | Podcasts (por ventana de 5 h) | 181 | ~45 | 9 | ~4 | | **Créditos de Google Cloud** (para la Gemini API) | $100 | $40 | $10 | — | | **Valor en las API de Google** (videos y canciones) | **$3.919** | **$1.699** | **$259** | **$64** | - Los créditos de Google Flow son un solo saldo. Un plan genera los videos Veo 3.1 Fast, o una de las filas que empiezan con "o", o una mezcla de ellas, nunca todas. Todo lo que está debajo del saldo es una cuota aparte y se suma. - Flow hace upscale de un video a 1080p gratis hasta 10 segundos y cobra 1 crédito por cada segundo adicional ([upscale de video](/docs/api-google-flow-v1/post-google-flow-videos-upscale), [página de créditos de Flow de Google](https://support.google.com/flow/answer/16526234?hl=es)). Por eso cada fila en 1080p del saldo de Flow cuenta clips de 10 segundos o menos. Un upscale a 4K toma 50 créditos del saldo, solo en Ultra. En Vids, 1080p consume los mismos segundos que 720p. - La fila de valor cuenta el saldo de Flow como Veo 3.1 Fast en 1080p (US$0,96 por video en la API de Google), los videos de Vids en 1080p (US$1,56) y las canciones a US$0,08. Eso es de 13 a 20 veces el precio de cada plan. - Los "1.000+ al día" videos Veo 3.1 Lite y las "~500 al día" imágenes son lo que alcanzan nuestras cuentas Ultra US$199,99 más activas, no límites que Google publique. Lite con prioridad baja funciona solo para el titular de ese plan. - Las cantidades de Vids son cifras de Google, y nuestra cuenta de prueba Pro mostró exactamente 25 videos con avatar. Google indica que algunos planes comparten un mismo límite entre avatares y clips de video. En Plus, las imágenes y las locuciones comparten 50 créditos al mes. Pro y Ultra figuran con locución ilimitada, aunque nuestras cuentas de prueba mostraron un contador de 50 usos al mes. Google no tiene API para avatares que hablan. ### Lo que genera cada plan en un mes Lo que genera cada plan de Google AI con useapi.net, y lo que cuesta un elemento en la API del propio Google (en dólares estadounidenses, a noviembre de 2026). Un video cuesta su parte del plan: el precio del plan dividido entre lo que el plan genera. | Qué genera | API oficial | Ultra $199,99 (25.000 cr, 10.000 s) | Ultra $99,99 (10.000 cr, 2.500 s) | Pro $19,99 (1.000 cr, 500 s) | Plus $4,99 (200 cr, 60 s) | |---|---|---|---|---|---| | Omni 1.2 en Flow (720p, 15 s) | [$1,04](https://ai.google.dev/gemini-api/docs/pricing) ($0,07/s) | $0,48 / 60 cr (416 videos/mes) | $0,60 / 60 cr (166 videos/mes) | $1,20 / 60 cr (16 videos/mes) | $1,50 / 60 cr (3 videos/mes) | | Omni 1.1 en Flow (720p, 10 s) | [$1,01](https://ai.google.dev/gemini-api/docs/pricing) ($0,10/s) | $0,12 / 15 cr (1.666 videos/mes) | $0,15 / 15 cr (666 videos/mes) | $0,30 / 15 cr (66 videos/mes) | $0,37 / 15 cr (13 videos/mes) | | Omni 1.2 en Vids (720p, 15 s) | [$1,04](https://ai.google.dev/gemini-api/docs/pricing) ($0,07/s) | $0,30 / 15 s (666 videos/mes) | $0,60 / 15 s (166 videos/mes) | $0,60 / 15 s (33 videos/mes) | $1,25 / 15 s (4 videos/mes) | | Omni 1.2 en Vids (1080p, 15 s) | [$1,56](https://ai.google.dev/gemini-api/docs/pricing) ($0,104/s) | $0,30 / 15 s (666 videos/mes) | $0,60 / 15 s (166 videos/mes) | $0,60 / 15 s (33 videos/mes) | $1,25 / 15 s (4 videos/mes) | | Veo 3.1 Fast (Flow, 720p, 8 s) | [$0,80](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing) ($0,10/s) | $0,08 / 10 cr (2.500 videos/mes) | $0,10 / 10 cr (1.000 videos/mes) | $0,40 / 20 cr (50 videos/mes) | $0,50 / 20 cr (10 videos/mes) | | Nano Banana Pro (imagen en Flow) | [$0,134](https://ai.google.dev/gemini-api/docs/pricing) (por imagen) | $0 / 0 cr (~500 al día) | $0 / 0 cr (incluidas) | $0 / 0 cr (incluidas) | $0 / 0 cr (incluidas) | | Canción Lyria 3.5 (Flow Music) | [$0,08](https://ai.google.dev/gemini-api/docs/pricing) (por canción) | $0,033 / 5 cr (6.000/mes) | $0,017 / 5 cr (6.000/mes) | $0,010 / 5 cr (2.000/mes) | $0,008 / 5 cr (600/mes) | | Notebook (podcasts por 5 h) | [Enterprise](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks) (Preview) | 181 | ~45 | 9 | ~4 | | Créditos de Cloud (uso de la Gemini API) | — | $100/mes | $40/mes | $10/mes | — | - La fila de Notebook cuenta los Audio Overviews (podcasts) que puede iniciar una ventana completa de 5 horas, según las estimaciones del propio Google. Plus y Ultra US$99,99 se escalan con los [multiplicadores publicados](https://support.google.com/gemininotebook/answer/17670842?hl=es) por Google. - Cada video e imagen de Flow necesita un captcha, que la API resuelve. Tu primera cuenta recibe 300 gratis, y después tu propio [proveedor de captcha](/docs/start-here/setup-google-flow#configure-captcha-providers) cuesta unos US$0,80 a US$3,00 por cada 1.000. - Los precios de los planes son los de Google en EE. UU. Las tablas de precios de [Google Flow](/docs/api-google-flow-v1#pricing) y [Google Vids](/docs/api-google-vids-v1#pricing) muestran todos los modelos en todos los planes. ### Google Flow: Veo 3.1, Omni Flash y Nano Banana La [Google Flow API](/docs/api-google-flow-v1) genera videos Veo 3.1 Fast, Quality y Lite y videos Omni 1.2 Flash y Omni 1.1 Flash con los créditos de Flow del plan. También genera imágenes Nano Banana Pro, 2.1 y 2 Lite, que no gastan créditos, y hace upscale de videos e imágenes. Del lado de Google, Veo 3.1 se ejecuta en [Agent Platform](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing) a US$0,10 por segundo en Fast a 720p y US$0,12 a 1080p. Omni 1.2 Flash y Nano Banana se ejecutan en la [Gemini API](https://ai.google.dev/gemini-api/docs/pricing). Las dos necesitan un proyecto de Google Cloud con facturación. El artículo [Veo 3.1 API pricing](/docs/articles/veo-3-1-api-pricing) (en inglés) compara todos los precios de Veo. ### Google Vids: Omni 1.2 Flash y avatares que hablan La [Google Vids API](/docs/api-google-vids-v1) genera videos Omni 1.2 Flash de 3 a 15 segundos con sonido, en 720p o 1080p por los mismos segundos, y los extiende, edita y les hace upscale. También genera [videos con avatares que hablan](/docs/api-google-vids-v1/post-google-vids-videos-avatar) de hasta 30 segundos, [voz](/docs/api-google-vids-v1/post-google-vids-speech) con 30 voces e imágenes básicas. Nada de esto consume segundos de video. Google no publica una API de Vids. El mismo modelo en la Gemini API cuesta US$0,07 por segundo en 720p y US$0,104 en 1080p. Vids no pide captcha. Sus segundos se comparten entre todos los miembros de un plan familiar de Google. La [guía de Omni 1.2 Flash](/docs/articles/gemini-omni-1-2-flash-api-es) hace una escena en Flow y otra en Vids. ### Gemini Notebook (NotebookLM): podcasts, video y Deep Research La [Gemini Notebook API (NotebookLM API)](/docs/api-gemini-notebook-v1) convierte páginas web, PDF y videos de YouTube en Audio Overviews (podcasts), Video Overviews, presentaciones, infografías, informes y cuestionarios, y ofrece chat con citas y Deep Research. Los Video Overviews cinematográficos necesitan Pro o Ultra. Notebook no tiene créditos. Cada job usa parte del uso de la cuenta, que se recarga cada 5 horas hasta un límite semanal: Plus tiene 2 veces los límites gratuitos, Pro 4 veces, y Ultra 5 o 20 veces los de Pro. La [Gemini Notebook Enterprise API](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks) del propio Google está en Preview, necesita licencias Enterprise en un proyecto de Google Cloud y solo cubre notebooks, fuentes, uso compartido y Audio Overviews. ### Google Flow Music: canciones con Lyria 3.5 Todos los planes de pago de Google AI incluyen también créditos de [Google Flow Music](https://www.flowmusic.app), aparte de los créditos de Flow. Plus recibe [3.000 créditos al mes](https://support.google.com/googleone/answer/16882689?hl=es), Pro [10.000](https://support.google.com/googleone/answer/14534406?hl=es) y Ultra [30.000](https://support.google.com/googleone/answer/16286513?hl=es). Los activas una sola vez: inicia sesión en flowmusic.app con la misma cuenta de Google y permite que Flow Music vea tu membresía de Google One. La [Flow Music API](/docs/api-flowmusic-v1) genera canciones completas con voz o instrumentales con Lyria 3.5 y Lyria 3 Pro, a 5 créditos por canción. También hace covers, remixes y extensiones, y separa las canciones en cuatro stems. Google ofrece Flow Music solo como sitio web. En la Gemini API, una canción de Lyria 3.5 cuesta US$0,08, y ahí una canción generada no se puede editar. ### Una cuenta de Google, cuatro cuotas Los créditos de Flow, los segundos de Vids, el uso de Notebook y los créditos de Flow Music se cuentan por separado, y ninguno resta de otro. Conecta la misma cuenta de Google a las cuatro API y usará todas las cuotas: videos de Omni 1.2 Flash en Flow y en Vids, unos encima de otros, podcasts y Deep Research en Notebook, y canciones en Flow Music. Cada API tiene su propia página de configuración ([Flow](/docs/start-here/setup-google-flow), [Vids](/docs/start-here/setup-google-vids), [Notebook](/docs/start-here/setup-gemini-notebook), [Flow Music](/docs/start-here/setup-flowmusic)), y una sola suscripción de useapi.net cubre las cuatro. ### Qué plan elegir - Ultra US$199,99 es el único plan con [Veo 3.1 Lite con prioridad baja](/docs/api-google-flow-v1/post-google-flow-videos), que no consume ningún crédito. Google no publica un límite, y nuestras cuentas más activas hacen más de 1.000 de estos videos al día, además de los 25.000 créditos mensuales. También tiene el precio por video más bajo: Veo 3.1 Fast a US$0,08, y un video de quince segundos de Omni 1.2 Flash a US$0,30 en Vids o US$0,48 en Flow. - Ultra US$99,99 cuesta la mitad pero no tiene Veo 3.1 Lite con prioridad baja. Genera 1.000 videos Veo 3.1 Fast a US$0,10 y 166 videos de Vids a US$0,60, con las mismas 6.000 canciones. - Pro es el plan para empezar. Genera 50 videos Veo 3.1 Fast al mes a US$0,40, la mitad del precio de Google, 33 videos de Vids de quince segundos a US$0,60 y 2.000 canciones de Lyria 3.5. En Pro, haz Omni 1.2 Flash en Vids: en Flow cuesta US$1,20, más que los US$1,04 de la Gemini API. - Plus puede costar más por video que la API de Google. Un video de quince segundos de Omni 1.2 Flash en 720p cuesta US$1,50 en Flow y US$1,25 en Vids, frente a US$1,04. Veo 3.1 Fast sigue siendo más barato, US$0,50 frente a US$0,80, pero solo 10 al mes. Plus encaja mejor con canciones (600 al mes), imágenes Nano Banana y Gemini Notebook que con video. ## Preguntas ### ¿Google AI Ultra incluye acceso a la Gemini API? Con useapi.net, Ultra US$199,99 genera 2.500 videos Veo 3.1 Fast, 666 videos de Omni 1.2 Flash en Vids y 6.000 canciones al mes, por un valor de unos US$3.919 en las API de Google (a noviembre de 2026). El plan en sí no incluye uso de la Gemini API. Trae [créditos de Google Cloud](https://developers.google.com/program/plans-and-pricing) por US$100 al mes (US$40 en Ultra US$99,99), que activas en el Google Developer Program. Eso alcanza para unos 96 videos de quince segundos de Omni 1.2 Flash. ### ¿Puedo usar mi plan Google AI Pro con una API? Con useapi.net, sí: los 1.000 créditos de Flow, los 500 segundos de Vids y los 10.000 créditos de Flow Music de Pro funcionan por REST. Generan 50 videos Veo 3.1 Fast al mes a US$0,40 cada uno, frente a US$0,80 en Agent Platform de Google. También generan 33 videos de quince segundos de Omni 1.2 Flash en Vids a US$0,60, frente a US$1,04 en la Gemini API, y 2.000 canciones de Lyria 3.5, que allí valen US$160 (a noviembre de 2026). Las imágenes Nano Banana no gastan créditos. ### ¿Cuántos videos de Veo 3.1 genera Google AI Ultra? Con useapi.net, Ultra US$199,99 genera 2.500 videos Veo 3.1 Fast de ocho segundos al mes a US$0,08 cada uno, frente a US$0,80 en [Agent Platform](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing) de Google, y Ultra US$99,99 genera 1.000 a US$0,10 (a noviembre de 2026). Ultra US$199,99 también ejecuta Veo 3.1 Lite con prioridad baja sin gastar créditos, unos 1.000 o más al día en nuestras cuentas más activas. ### ¿Existe una API de NotebookLM? Con useapi.net, sí, para cuentas de Google normales: la Gemini Notebook API (NotebookLM API) ejecuta Audio y Video Overviews, presentaciones, chat con citas y Deep Research con tu plan de Google AI, incluido el gratuito. La [Enterprise API](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks) del propio Google está en Preview, necesita licencias Enterprise en un proyecto de Google Cloud y no tiene Video Overviews, chat ni Deep Research (a noviembre de 2026). ### ¿Funciona con una cuenta de Google gratuita? Con useapi.net, sí, en Flow y en Notebook. Los 50 créditos de Flow al día de una cuenta gratuita generan 2 videos Veo 3.1 Fast, 5 de Lite o un video de Omni 1.2 Flash de 10 segundos en 720p, y las imágenes Nano Banana no gastan créditos. Notebook inicia unos 2 Audio Overviews por ventana de 5 horas. La Gemini API no tiene nivel gratuito para Omni 1.2 Flash ni para Nano Banana Pro (a noviembre de 2026). Vids es la excepción: las cuentas gratuitas que probamos no tenían segundos de video. ### Fuentes - Google, [planes de Google AI](https://gemini.google/subscriptions/) y los [planes para desarrolladores](https://gemini.google/subscriptions/?plans=developer), consultados el 7 de noviembre de 2026 - Google, [planes del Google Developer Program](https://developers.google.com/program/plans-and-pricing) (créditos de Google Cloud por plan) y [New developer tools for Google AI Pro and Ultra subscribers](https://blog.google/innovation-and-ai/technology/developers-tools/gdp-premium-ai-pro-ultra/), 27 de enero de 2026 - Ayuda de Google One, beneficios de Flow Music en [Google AI Plus](https://support.google.com/googleone/answer/16882689?hl=es), [Google AI Pro](https://support.google.com/googleone/answer/14534406?hl=es) y [Google AI Ultra](https://support.google.com/googleone/answer/16286513?hl=es), consultados el 7 de noviembre de 2026 - Google, [precios de la Gemini API](https://ai.google.dev/gemini-api/docs/pricing) (Omni 1.2 Flash, Nano Banana, Lyria 3.5), consultados el 7 de noviembre de 2026 - Google Cloud, [precios de Agent Platform](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing) (Veo 3.1), consultados el 7 de noviembre de 2026 - Google, [créditos de Flow](https://support.google.com/flow/answer/16526234?hl=es), [Gemini en Google Vids](https://support.google.com/docs/answer/15609411?hl=es) y [límites de uso de Gemini Notebook](https://support.google.com/gemininotebook/answer/17670842?hl=es), consultados el 7 de noviembre de 2026 - Google Cloud, [Gemini Notebook Enterprise API](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks), consultada el 7 de noviembre de 2026 - Tablas de precios de useapi.net: [Google Flow API](/docs/api-google-flow-v1#pricing), [Google Vids API](/docs/api-google-vids-v1#pricing), [Gemini Notebook API](/docs/api-gemini-notebook-v1#pricing) y [Flow Music API](/docs/api-flowmusic-v1#pricing) ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-ai-subscription-api-id === Document URL: https://useapi.net/docs/articles/google-ai-subscription-api-id --- layout: default title: "Bisakah Langganan Google AI Dipakai Lewat API? Isi Paket Plus, Pro dan Ultra" seo_title: "Google AI Pro dan Ultra Lewat API: Apa Saja yang Didapat dari Paket Anda" description: "Pakai Google AI Plus, Pro atau Ultra lewat API dengan useapi.net: satu paket Ultra membuat video dan lagu senilai US$3.919 sebulan di harga API Google." keywords: [API langganan Google AI, Google AI Pro API, API Google AI Pro, Google AI Ultra API, API Google AI Ultra, Google AI Plus API, apakah Google AI Ultra termasuk Gemini API, Google AI Ultra Gemini API, akses API Google AI Pro, langganan Gemini API, Gemini subscription API, Google One AI API, kredit Flow API, Flow credits API, Google Vids API, Gemini Notebook API, NotebookLM API, API NotebookLM, Google Flow Music API, Lyria 3.5 API, kredit Flow Music Google AI Pro, API Veo 3.1, Veo 3.1 API, Omni 1.2 Flash API, Nano Banana API, kredit Google Cloud, Google Cloud credits, Google Developer Program, Google Flow API] parent: Articles nav_exclude: true lang: id translation_key: google-ai-subscription date: 2026-11-07 last_modified: 2026-11-07 nav_order: 910 repo: https://github.com/useapi/google-flow-api --- ## Bisakah Langganan Google AI Dipakai Lewat API? Isi Paket Plus, Pro dan Ultra {: .no_toc #can-you-use-your-google-ai-subscription-through-an-api-what-plus-pro-and-ultra-get-you } 6 menit baca • 7 November 2026 useapi.net adalah API pihak ketiga. Kami tidak berafiliasi dengan Google dan tidak disahkan oleh Google. ## Daftar isi {: .no_toc .text-delta #table-of-contents } ### Jawaban singkat Bisa, lewat useapi.net. [Paket Google AI](https://gemini.google/subscriptions/) Anda (Plus, Pro atau Ultra) sudah berisi kuota bulanan untuk tools kreatif Google. useapi.net mengubah setiap kuota itu menjadi API: - [Google Flow API](/docs/api-google-flow-v1): video dari kredit Flow, dan gambar yang tidak memakai kredit sama sekali - [Google Vids API](/docs/api-google-vids-v1): video, video avatar bicara dan suara dari kuota detik Vids - [Gemini Notebook API (NotebookLM API)](/docs/api-gemini-notebook-v1): podcast, slide dan riset dari kuota pemakaian Notebook - [Flow Music API](/docs/api-flowmusic-v1): lagu dari kredit Flow Music yang sudah termasuk di paket Anda Di Ultra $199,99, isi satu bulan bernilai sekitar $3.919 jika dihitung dengan harga API Google sendiri (per November 2026). Gemini API sendiri tidak termasuk dalam paket. Google menagihnya terpisah, per detik video dan per gambar. Pro dan Ultra mendapat [kredit Google Cloud](https://developers.google.com/program/plans-and-pricing) bulanan yang kecil untuk itu: $10 di Pro, $40 di Ultra $99,99 dan $100 di Ultra $199,99. Bahkan $100 hanya cukup untuk sekitar 96 video Omni 1.2 Flash berdurasi 15 detik di sana. Harga di halaman ini adalah harga Google di AS dalam dolar AS: di Indonesia Google menagih dalam rupiah dan harganya bisa berbeda. ### Semua yang dibuat satu paket dalam sebulan Total yang dihasilkan satu paket Google AI lewat useapi.net setiap bulan, dan biaya hasil yang sama di API Google sendiri (per November 2026). | Satu bulan | Ultra $199,99 | Ultra $99,99 | Pro $19,99 | Plus $4,99 | |---|---|---|---|---| | **Google Flow** (satu pool, pilih satu baris) | 25.000 cr | 10.000 cr | 1.000 cr | 200 cr | | Video Veo 3.1 Fast (8 s, 1080p) | 2.500 | 1.000 | 50 | 10 | | atau Veo 3.1 Lite (8 s, 1080p) | 5.000 | 2.000 | 100 | 20 | | atau Omni 1.1 Flash (10 s, 1080p) | 1.666 | 666 | 66 | 13 | | atau Omni 1.2 Flash (10 s, 1080p, upscale gratis) | 833 | 333 | 33 | 6 | | atau Omni 1.2 Flash (15 s, 720p) | 416 | 166 | 16 | 3 | | atau upscale video 4K (klip maks. 10 s) | 500 | 200 | — | — | | **Google Flow, 0 kredit** (di luar pool) | | | | | | Video Veo 3.1 Lite (prioritas rendah, 8 s) | 1.000+/hari | — | — | — | | Upscale video ke 1080p (klip maks. 10 s) | gratis | gratis | gratis | gratis | | Gambar Nano Banana (Pro, 2.1, 2 Lite + upscale) | ~500/hari, 4K | termasuk, 4K | termasuk, 2K | termasuk, 2K | | **Google Vids** (kuota sendiri, ekstra) | 10.000 s | 2.500 s | 500 s | 60 s | | Video Omni 1.2 Flash (15 s, 1080p) | 666 | 166 | 33 | 4 | | Video avatar bicara (maks. 30 s) | 500 | 125 | 25 | 6 | | Gambar (dasar, ±1 MP) | 1.000 | 300 | 30 | maks. 50 | | Speech (TTS) (30 suara) | termasuk | termasuk | termasuk | termasuk | | **Flow Music** (kredit sendiri, ekstra) | 30.000 cr | 30.000 cr | 10.000 cr | 3.000 cr | | Lagu Lyria 3.5 (lagu utuh) | 6.000 | 6.000 | 2.000 | 600 | | **Gemini Notebook** (batas sendiri, ekstra) | | | | | | Podcast (per jendela 5 jam) | 181 | ~45 | 9 | ~4 | | **Kredit Google Cloud** (untuk Gemini API) | $100 | $40 | $10 | — | | **Nilai di API Google** (video dan lagu) | **$3.919** | **$1.699** | **$259** | **$64** | - Kredit Google Flow adalah satu pool. Satu paket bisa membuat video Veo 3.1 Fast, atau salah satu baris "atau", atau campurannya, tetapi tidak semuanya sekaligus. Semua yang ada di bawah pool adalah kuota terpisah dan menjadi tambahan. - Flow meng-upscale video ke 1080p secara gratis untuk klip hingga 10 detik, dan memotong 1 kredit untuk setiap detik di atasnya ([upscale video](/docs/api-google-flow-v1/post-google-flow-videos-upscale), [halaman kredit Flow dari Google](https://support.google.com/flow/answer/16526234?hl=id)). Jadi setiap baris 1080p di pool Flow menghitung klip berdurasi 10 detik atau kurang. Upscale 4K memakai 50 kredit dari pool, dan hanya ada di Ultra. Di Vids, 1080p memakai detik yang sama dengan 720p. - Baris nilai menghitung pool Flow sebagai Veo 3.1 Fast 1080p ($0,96 per video di API Google), video Vids 1080p ($1,56) dan lagu seharga $0,08. Itu 13 sampai 20 kali harga tiap paket. - Angka "1.000+/hari" untuk video Veo 3.1 Lite dan "~500/hari" untuk gambar adalah capaian akun Ultra $199,99 tersibuk kami, bukan batas yang dipublikasikan Google. Veo 3.1 Lite prioritas rendah hanya berjalan untuk pemilik paket itu. - Angka Vids berasal dari Google, dan akun uji Pro kami menunjukkan tepat 25 video avatar. Google mencatat bahwa sebagian paket memakai satu batas bersama untuk avatar dan klip video. Di Plus, gambar dan voice-over berbagi 50 kredit per bulan. Pro dan Ultra mencantumkan voice-over tanpa batas, sedangkan akun uji kami menunjukkan penghitung 50 pemakaian per bulan. Google tidak punya API untuk avatar bicara. ### Apa yang dibuat tiap paket dalam sebulan Apa yang dibuat tiap paket Google AI lewat useapi.net, dan berapa biaya satu item di API Google sendiri (per November 2026). Satu video berbiaya sebesar bagiannya dari paket: harga paket dibagi jumlah yang dibuat paket itu. | Yang dibuat | API resmi | Ultra $199,99 (25.000 cr, 10.000 s) | Ultra $99,99 (10.000 cr, 2.500 s) | Pro $19,99 (1.000 cr, 500 s) | Plus $4,99 (200 cr, 60 s) | |---|---|---|---|---|---| | Omni 1.2 di Flow (720p, 15 s) | [$1,04](https://ai.google.dev/gemini-api/docs/pricing) ($0,07/s) | $0,48 / 60 cr (416 video/bln) | $0,60 / 60 cr (166 video/bln) | $1,20 / 60 cr (16 video/bln) | $1,50 / 60 cr (3 video/bln) | | Omni 1.1 di Flow (720p, 10 s) | [$1,01](https://ai.google.dev/gemini-api/docs/pricing) ($0,10/s) | $0,12 / 15 cr (1.666 video/bln) | $0,15 / 15 cr (666 video/bln) | $0,30 / 15 cr (66 video/bln) | $0,37 / 15 cr (13 video/bln) | | Omni 1.2 di Vids (720p, 15 s) | [$1,04](https://ai.google.dev/gemini-api/docs/pricing) ($0,07/s) | $0,30 / 15 s (666 video/bln) | $0,60 / 15 s (166 video/bln) | $0,60 / 15 s (33 video/bln) | $1,25 / 15 s (4 video/bln) | | Omni 1.2 di Vids (1080p, 15 s) | [$1,56](https://ai.google.dev/gemini-api/docs/pricing) ($0,104/s) | $0,30 / 15 s (666 video/bln) | $0,60 / 15 s (166 video/bln) | $0,60 / 15 s (33 video/bln) | $1,25 / 15 s (4 video/bln) | | Veo 3.1 Fast (Flow, 720p, 8 s) | [$0,80](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing) ($0,10/s) | $0,08 / 10 cr (2.500 video/bln) | $0,10 / 10 cr (1.000 video/bln) | $0,40 / 20 cr (50 video/bln) | $0,50 / 20 cr (10 video/bln) | | Nano Banana Pro (gambar Flow) | [$0,134](https://ai.google.dev/gemini-api/docs/pricing) (per gambar) | $0 / 0 cr (~500/hari) | $0 / 0 cr (termasuk) | $0 / 0 cr (termasuk) | $0 / 0 cr (termasuk) | | Lagu Lyria 3.5 (Flow Music) | [$0,08](https://ai.google.dev/gemini-api/docs/pricing) (per lagu) | $0,033 / 5 cr (6.000 lagu/bln) | $0,017 / 5 cr (6.000 lagu/bln) | $0,010 / 5 cr (2.000 lagu/bln) | $0,008 / 5 cr (600 lagu/bln) | | Notebook (podcast per 5 jam) | [Enterprise](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks) (Preview) | 181 | ~45 | 9 | ~4 | | Kredit Cloud (untuk Gemini API) | — | $100/bln | $40/bln | $10/bln | — | - Baris Notebook menghitung Audio Overview (podcast) yang bisa dimulai dalam satu jendela 5 jam penuh, menurut perkiraan Google sendiri. Angka Plus dan Ultra $99,99 dihitung dengan [pengali yang dipublikasikan Google](https://support.google.com/gemininotebook/answer/17670842?hl=id). - Setiap video dan gambar Flow butuh captcha, dan API ini yang menyelesaikannya. Akun pertama Anda mendapat 300 gratis, setelah itu [penyedia captcha](/docs/start-here/setup-google-flow#configure-captcha-providers) milik Anda sendiri berbiaya sekitar $0,80 sampai $3,00 per 1.000. - Harga paket adalah harga Google di AS. Tabel harga [Google Flow](/docs/api-google-flow-v1#pricing) dan [Google Vids](/docs/api-google-vids-v1#pricing) mencantumkan setiap model di setiap paket. ### Google Flow: Veo 3.1, Omni Flash dan Nano Banana [Google Flow API](/docs/api-google-flow-v1) membuat video Veo 3.1 Fast, Quality dan Lite serta video Omni 1.2 Flash dan Omni 1.1 Flash dari kredit Flow paket Anda. API ini juga membuat gambar Nano Banana Pro, 2.1 dan 2 Lite yang tidak memakai kredit, dan meng-upscale video maupun gambar. Di sisi Google, Veo 3.1 berjalan di [Agent Platform](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing) dengan harga $0,10 per detik untuk Fast 720p dan $0,12 untuk 1080p. Omni 1.2 Flash dan Nano Banana berjalan di [Gemini API](https://ai.google.dev/gemini-api/docs/pricing). Keduanya butuh project Google Cloud dengan billing aktif. Artikel [harga API Veo 3.1](/docs/articles/veo-3-1-api-pricing) (bahasa Inggris) membandingkan semua harga Veo. ### Google Vids: Omni 1.2 Flash dan avatar bicara [Google Vids API](/docs/api-google-vids-v1) membuat video Omni 1.2 Flash berdurasi 3 sampai 15 detik dengan suara, dalam 720p atau 1080p dengan jumlah detik yang sama, lalu bisa memperpanjang, mengedit dan meng-upscale-nya. API ini juga membuat [video avatar bicara](/docs/api-google-vids-v1/post-google-vids-videos-avatar) hingga 30 detik, [speech](/docs/api-google-vids-v1/post-google-vids-speech) dengan 30 suara, dan gambar dasar. Semua ini tidak memakai detik video. Google tidak menerbitkan API untuk Vids. Model yang sama di Gemini API berharga $0,07 per detik untuk 720p dan $0,104 untuk 1080p. Vids tidak meminta captcha. Detiknya dipakai bersama oleh semua anggota paket keluarga Google. [Panduan Omni 1.2 Flash](/docs/articles/gemini-omni-1-2-flash-api) (bahasa Inggris) menjalankan satu adegan di Flow dan satu di Vids. ### Gemini Notebook (NotebookLM): podcast, video dan Deep Research [Gemini Notebook API (NotebookLM API)](/docs/api-gemini-notebook-v1) mengubah halaman web, PDF dan video YouTube menjadi Audio Overview (podcast), Video Overview, slide, infografis, laporan dan kuis, serta menjalankan chat dengan sitasi dan Deep Research. Cinematic Video Overview butuh Pro atau Ultra. Notebook tidak memakai kredit. Setiap pekerjaan memakai sebagian kuota akun, yang terisi ulang setiap 5 jam hingga batas mingguan: Plus mendapat 2 kali batas gratis, Pro 4 kali, dan Ultra 5 atau 20 kali batas Pro. [Gemini Notebook Enterprise API](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks) milik Google masih Preview, butuh lisensi Enterprise di project Google Cloud, dan hanya mencakup notebook, sumber, berbagi dan Audio Overview. ### Google Flow Music: lagu Lyria 3.5 Setiap paket Google AI berbayar juga sudah termasuk kredit [Google Flow Music](https://www.flowmusic.app), terpisah dari kredit Flow. Plus mendapat [3.000 kredit per bulan](https://support.google.com/googleone/answer/16882689?hl=id), Pro [10.000](https://support.google.com/googleone/answer/14534406?hl=id) dan Ultra [30.000](https://support.google.com/googleone/answer/16286513?hl=id). Anda cukup mengklaimnya sekali: masuk ke flowmusic.app dengan akun Google yang sama, lalu izinkan Flow Music melihat keanggotaan Google One Anda. [Flow Music API](/docs/api-flowmusic-v1) membuat lagu utuh dengan vokal atau instrumental memakai Lyria 3.5 dan Lyria 3 Pro, 5 kredit per lagu. API ini juga membuat cover, remix dan extend, serta memisahkan lagu menjadi empat stem. Google hanya menyediakan Flow Music sebagai situs web. Di Gemini API satu lagu Lyria 3.5 berharga $0,08, dan lagu yang sudah dibuat tidak bisa diedit di sana. ### Satu akun Google, empat kuota Kredit Flow, detik Vids, pemakaian Notebook dan kredit Flow Music dihitung terpisah, dan tidak ada yang mengurangi yang lain. Hubungkan akun Google yang sama ke keempat API, dan akun itu memakai semua kuotanya: video Omni 1.2 Flash di Flow dan di Vids sekaligus, podcast dan Deep Research dari Notebook, serta lagu dari Flow Music. Setiap API punya halaman setup sendiri ([Flow](/docs/start-here/setup-google-flow), [Vids](/docs/start-here/setup-google-vids), [Notebook](/docs/start-here/setup-gemini-notebook), [Flow Music](/docs/start-here/setup-flowmusic)), dan satu langganan useapi.net mencakup keempatnya. ### Paket mana yang dipilih - Ultra $199,99 adalah satu-satunya paket dengan [Veo 3.1 Lite prioritas rendah](/docs/api-google-flow-v1/post-google-flow-videos), yang tidak memakai kredit sama sekali. Google tidak memublikasikan batasnya, dan akun tersibuk kami membuat 1.000+ video seperti ini per hari, di luar 25.000 kredit bulanan. Paket ini juga punya harga per video terendah: Veo 3.1 Fast $0,08, dan video Omni 1.2 Flash 15 detik $0,30 di Vids atau $0,48 di Flow. - Ultra $99,99 harganya separuh, tetapi tanpa Veo 3.1 Lite prioritas rendah. Paket ini membuat 1.000 video Veo 3.1 Fast seharga $0,10 dan 166 video Vids seharga $0,60, dengan 6.000 lagu yang sama. - Pro adalah paket untuk memulai. Pro membuat 50 video Veo 3.1 Fast per bulan seharga $0,40, separuh harga Google, 33 video Vids 15 detik seharga $0,60 dan 2.000 lagu Lyria 3.5. Di Pro, buat Omni 1.2 Flash di Vids: di Flow biayanya $1,20, lebih mahal dari $1,04 di Gemini API. - Plus bisa lebih mahal per video daripada API Google. Satu video Omni 1.2 Flash 15 detik 720p berbiaya $1,50 di Flow dan $1,25 di Vids, dibanding $1,04. Veo 3.1 Fast tetap lebih murah, $0,50 dibanding $0,80, tetapi hanya 10 per bulan. Plus lebih cocok untuk lagu (600 per bulan), gambar Nano Banana dan Gemini Notebook daripada untuk video. ## Pertanyaan ### Apakah Google AI Ultra termasuk akses Gemini API? Lewat useapi.net, Ultra $199,99 membuat 2.500 video Veo 3.1 Fast, 666 video Omni 1.2 Flash di Vids dan 6.000 lagu per bulan, senilai sekitar $3.919 di API Google (per November 2026). Paketnya sendiri tidak berisi pemakaian Gemini API. Paket ini datang dengan [kredit Google Cloud](https://developers.google.com/program/plans-and-pricing) $100 per bulan ($40 di Ultra $99,99), yang Anda aktifkan di Google Developer Program. Itu cukup untuk sekitar 96 video Omni 1.2 Flash 15 detik. ### Bisakah paket Google AI Pro dipakai lewat API? Lewat useapi.net, bisa: 1.000 kredit Flow, 500 detik Vids dan 10.000 kredit Flow Music dari Pro berjalan lewat REST. Kuota itu membuat 50 video Veo 3.1 Fast per bulan seharga $0,40 per video, dibanding $0,80 di Agent Platform Google. Juga 33 video Omni 1.2 Flash 15 detik di Vids seharga $0,60, dibanding $1,04 di Gemini API, dan 2.000 lagu Lyria 3.5 yang di sana bernilai $160 (per November 2026). Gambar Nano Banana tidak memakai kredit. ### Berapa video Veo 3.1 yang bisa dibuat Google AI Ultra? Lewat useapi.net, Ultra $199,99 membuat 2.500 video Veo 3.1 Fast berdurasi 8 detik per bulan seharga $0,08 per video, dibanding $0,80 di [Agent Platform](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing) Google, dan Ultra $99,99 membuat 1.000 video seharga $0,10 (per November 2026). Ultra $199,99 juga menjalankan Veo 3.1 Lite prioritas rendah tanpa kredit, sekitar 1.000 atau lebih per hari di akun tersibuk kami. ### Apakah ada API NotebookLM? Lewat useapi.net, ada, untuk akun Google biasa: Gemini Notebook API (NotebookLM API) menjalankan Audio Overview dan Video Overview, slide, chat dengan sitasi dan Deep Research di paket Google AI Anda, termasuk paket gratis. [Enterprise API](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks) milik Google masih Preview, butuh lisensi Enterprise di project Google Cloud, dan tidak punya Video Overview, chat maupun Deep Research (per November 2026). ### Bisakah akun Google gratis memakainya? Lewat useapi.net, bisa, di Flow dan Notebook. 50 kredit Flow harian di akun gratis membuat 2 video Veo 3.1 Fast, 5 video Lite, atau satu video Omni 1.2 Flash 10 detik 720p, dan gambar Nano Banana tidak memakai kredit. Notebook bisa memulai sekitar 2 Audio Overview per jendela 5 jam. Gemini API tidak punya tier gratis untuk Omni 1.2 Flash maupun Nano Banana Pro (per November 2026). Pengecualiannya Vids: akun gratis yang kami uji tidak punya detik video. ### Sumber - Google, [Paket Google AI](https://gemini.google/subscriptions/) dan [paket Developer](https://gemini.google/subscriptions/?plans=developer), dibaca 7 November 2026 - Google, [Paket Google Developer Program](https://developers.google.com/program/plans-and-pricing) (kredit Google Cloud per paket) dan [New developer tools for Google AI Pro and Ultra subscribers](https://blog.google/innovation-and-ai/technology/developers-tools/gdp-premium-ai-pro-ultra/), 27 Januari 2026 - Bantuan Google One, manfaat Flow Music untuk [Google AI Plus](https://support.google.com/googleone/answer/16882689?hl=id), [Google AI Pro](https://support.google.com/googleone/answer/14534406?hl=id) dan [Google AI Ultra](https://support.google.com/googleone/answer/16286513?hl=id), dibaca 7 November 2026 - Google, [Harga Gemini API](https://ai.google.dev/gemini-api/docs/pricing) (Omni 1.2 Flash, Nano Banana, Lyria 3.5), dibaca 7 November 2026 - Google Cloud, [Harga Agent Platform](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing) (Veo 3.1), dibaca 7 November 2026 - Google, [Kredit Flow](https://support.google.com/flow/answer/16526234?hl=id), [Gemini di Google Vids](https://support.google.com/docs/answer/15609411?hl=id) dan [Batas pemakaian Gemini Notebook](https://support.google.com/gemininotebook/answer/17670842?hl=id), dibaca 7 November 2026 - Google Cloud, [Gemini Notebook Enterprise API](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks), dibaca 7 November 2026 - Tabel harga useapi.net: [Google Flow API](/docs/api-google-flow-v1#pricing), [Google Vids API](/docs/api-google-vids-v1#pricing), [Gemini Notebook API](/docs/api-gemini-notebook-v1#pricing) dan [Flow Music API](/docs/api-flowmusic-v1#pricing) ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-ai-subscription-api-ja === Document URL: https://useapi.net/docs/articles/google-ai-subscription-api-ja --- layout: default title: "Google AI のサブスクは API で使える?Plus・Pro・Ultra で毎月できること" seo_title: "Google AI Pro・Ultra を API で使う:プランで毎月作れる動画と曲" description: "Google AI Plus・Pro・Ultra を useapi.net で API として使う方法。Ultra なら毎月、Google の API 換算で $3,919 分の動画と曲を作れます。" keywords: [Google AI Pro API, Google AI Ultra API, Google AI Plus API, Google AI サブスク API, Google AI プラン API, Google AI Pro API 使える, Google AI Ultra Gemini API, Google AI Ultra API キー, Gemini サブスク API, Gemini API 料金, Google One AI API, Flow クレジット, Flow クレジット API, Google Flow API, Google Vids API, Gemini Notebook API, NotebookLM API, Flow Music API, Lyria 3.5 API, Veo 3.1 API, Veo 3.1 料金, Omni 1.2 Flash API, Nano Banana API, Google Cloud クレジット, Google Developer Program, Google AI subscription API, does Google AI Ultra include API access] parent: Articles nav_exclude: true lang: ja translation_key: google-ai-subscription date: 2026-11-07 last_modified: 2026-11-07 nav_order: 910 repo: https://github.com/useapi/google-flow-api --- ## Google AI のサブスクは API で使える?Plus・Pro・Ultra で毎月できること {: .no_toc #can-you-use-your-google-ai-subscription-through-an-api-what-plus-pro-and-ultra-get-you } 6分で読めます • 2026年11月7日 useapi.net はサードパーティの API です。Google とは提携しておらず、Google の承認も受けていません。 ## 目次 {: .no_toc .text-delta #table-of-contents } ### 結論 はい、useapi.net を使えば可能です。[Google AI のプラン](https://gemini.google/subscriptions/)(Plus、Pro、Ultra)には、Google のクリエイティブツールの月間利用枠が付いています。useapi.net はその1つ1つを API にします。 - [Google Flow API](/docs/api-google-flow-v1):Flow クレジットで動画を生成。画像はクレジットを使いません - [Google Vids API](/docs/api-google-vids-v1):Vids の秒数で動画、AI アバター動画、音声を生成 - [Gemini Notebook API(NotebookLM API)](/docs/api-gemini-notebook-v1):Notebook の利用枠でポッドキャスト、スライド、リサーチ - [Flow Music API](/docs/api-flowmusic-v1):プランに含まれる Flow Music クレジットで曲を生成 Ultra $199.99 なら、1か月分は Google 自身の API で約 $3,919 に相当します(2026年11月時点)。 Gemini API そのものはプランに含まれていません。Google は動画1秒ごと、画像1枚ごとに別途請求します。Pro と Ultra には、Gemini API に使える少額の [Google Cloud クレジット](https://developers.google.com/program/plans-and-pricing)が毎月付きます。Pro は $10、Ultra $99.99 は $40、Ultra $199.99 は $100 です。$100 でも、Gemini API で作れる15秒の Omni 1.2 Flash 動画は約96本だけです。 この記事の料金は Google の米国価格(米ドル)です。日本では Google は円で請求するため、料金が異なる場合があります。 ### 1つのプランで毎月作れるもの Google AI のプラン1つで useapi.net を通して毎月作れるものの合計と、同じものを Google 自身の API で作った場合の料金です(2026年11月時点)。 | 1か月 | Ultra $199.99 | Ultra $99.99 | Pro $19.99 | Plus $4.99 | |---|---|---|---|---| | **Google Flow** (共通プール、1行を選ぶ) | 25,000 cr | 10,000 cr | 1,000 cr | 200 cr | | Veo 3.1 Fast 動画 (8秒・1080p) | 2,500 | 1,000 | 50 | 10 | | または Veo 3.1 Lite 動画 (8秒・1080p) | 5,000 | 2,000 | 100 | 20 | | または Omni 1.1 Flash 動画 (10秒・1080p) | 1,666 | 666 | 66 | 13 | | または Omni 1.2 Flash 動画 (10秒・1080p・無料拡大) | 833 | 333 | 33 | 6 | | または Omni 1.2 Flash 動画 (15秒・720p) | 416 | 166 | 16 | 3 | | または 4K アップスケール (10秒以下の動画) | 500 | 200 | — | — | | **Google Flow(0 cr)** (プールとは別枠) | | | | | | Veo 3.1 Lite 動画 (低優先度・8秒) | 1日1,000本以上 | — | — | — | | 1080p アップスケール (10秒以下の動画) | 無料 | 無料 | 無料 | 無料 | | Nano Banana 画像 (Pro・2.1・2 Lite、拡大) | 1日約500枚・4K | 込み・4K | 込み・2K | 込み・2K | | **Google Vids** (別枠の利用枠) | 10,000秒 | 2,500秒 | 500秒 | 60秒 | | Omni 1.2 Flash 動画 (15秒・1080p) | 666 | 166 | 33 | 4 | | AI アバター動画 (最長30秒) | 500 | 125 | 25 | 6 | | 画像 (基本、約1MP) | 1,000 | 300 | 30 | 最大50 | | 音声読み上げ (30種類の声) | 込み | 込み | 込み | 込み | | **Flow Music** (別枠のクレジット) | 30,000 cr | 30,000 cr | 10,000 cr | 3,000 cr | | Lyria 3.5 の曲 (フル尺) | 6,000 | 6,000 | 2,000 | 600 | | **Gemini Notebook** (別枠の上限) | | | | | | ポッドキャスト (5時間あたり) | 181 | ~45 | 9 | ~4 | | **Google Cloud クレジット** (Gemini API 用) | $100 | $40 | $10 | — | | **Google API 換算** (動画と曲) | **$3,919** | **$1,699** | **$259** | **$64** | - Google Flow のクレジットは1つの共通プールです。プランで作れるのは Veo 3.1 Fast の動画か、「または」の行のどれか1つ、またはその組み合わせで、全部を同時には作れません。プールより下の行はすべて別の利用枠で、上乗せになります。 - Flow は10秒以下の動画を無料で 1080p にアップスケールし、10秒を超える分は1秒ごとに1クレジットかかります([動画のアップスケール](/docs/api-google-flow-v1/post-google-flow-videos-upscale)、[Google の Flow クレジットのページ](https://support.google.com/flow/answer/16526234?hl=ja))。そのため、Flow プールの 1080p の行はすべて10秒以下の動画で数えています。4K アップスケールは Ultra のみで、プールから50クレジットを使います。Vids では 1080p も 720p と同じ秒数です。 - Google API 換算の行では、Flow プールを 1080p の Veo 3.1 Fast(Google の API で1本 $0.96)、Vids の動画を 1080p($1.56)、曲を1曲 $0.08 で数えています。各プランの料金の13〜20倍です。 - Veo 3.1 Lite の「1日1,000本以上」と画像の「1日約500枚」は、当社で最も利用の多い Ultra $199.99 アカウントの実績で、Google が公表している上限ではありません。低優先度の Lite を使えるのは、そのプランのオーナーだけです。 - Vids の数は Google の公表値で、当社の Pro テストアカウントでもアバター動画はちょうど25本でした。Google によると、一部のプランではアバターと動画クリップで上限を共有します。Plus では、画像とナレーションで月50クレジットを共有します。Pro と Ultra のナレーションは無制限とされていますが、当社のテストアカウントには月50回のカウンターがありました。AI アバター動画の API は Google にはありません。 ### 各プランで毎月作れるもの Google AI の各プランで useapi.net を通して作れるものと、Google 自身の API で1点あたりにかかる料金です(2026年11月時点)。動画1本の料金は、プランの料金をそのプランで作れる数で割ったものです。 | 生成するもの | 公式 API | Ultra $199.99/月 (25,000 cr, 10,000秒) | Ultra $99.99/月 (10,000 cr, 2,500秒) | Pro $19.99/月 (1,000 cr, 500秒) | Plus $4.99/月 (200 cr, 60秒) | |---|---|---|---|---|---| | Flow の Omni 1.2 (720p・15秒) | [$1.04](https://ai.google.dev/gemini-api/docs/pricing) ($0.07/秒) | $0.48 / 60 cr (月416本) | $0.60 / 60 cr (月166本) | $1.20 / 60 cr (月16本) | $1.50 / 60 cr (月3本) | | Flow の Omni 1.1 (720p・10秒) | [$1.01](https://ai.google.dev/gemini-api/docs/pricing) ($0.10/秒) | $0.12 / 15 cr (月1,666本) | $0.15 / 15 cr (月666本) | $0.30 / 15 cr (月66本) | $0.37 / 15 cr (月13本) | | Vids の Omni 1.2 (720p・15秒) | [$1.04](https://ai.google.dev/gemini-api/docs/pricing) ($0.07/秒) | $0.30 / 15秒 (月666本) | $0.60 / 15秒 (月166本) | $0.60 / 15秒 (月33本) | $1.25 / 15秒 (月4本) | | Vids の Omni 1.2 (1080p・15秒) | [$1.56](https://ai.google.dev/gemini-api/docs/pricing) ($0.104/秒) | $0.30 / 15秒 (月666本) | $0.60 / 15秒 (月166本) | $0.60 / 15秒 (月33本) | $1.25 / 15秒 (月4本) | | Veo 3.1 Fast (Flow・720p・8秒) | [$0.80](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing) ($0.10/秒) | $0.08 / 10 cr (月2,500本) | $0.10 / 10 cr (月1,000本) | $0.40 / 20 cr (月50本) | $0.50 / 20 cr (月10本) | | Nano Banana Pro (Flow の画像) | [$0.134](https://ai.google.dev/gemini-api/docs/pricing) (1枚) | $0 / 0 cr (1日約500枚) | $0 / 0 cr (込み) | $0 / 0 cr (込み) | $0 / 0 cr (込み) | | Lyria 3.5 の曲 (Flow Music) | [$0.08](https://ai.google.dev/gemini-api/docs/pricing) (1曲) | $0.033 / 5 cr (月6,000曲) | $0.017 / 5 cr (月6,000曲) | $0.010 / 5 cr (月2,000曲) | $0.008 / 5 cr (月600曲) | | Notebook (音声解説/5時間) | [Enterprise](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks) (プレビュー) | 181 | ~45 | 9 | ~4 | | Cloud クレジット (Gemini API 用) | — | $100/月 | $40/月 | $10/月 | — | - Notebook の行は、5時間の枠1つで開始できる音声解説(ポッドキャスト)の数で、Google 自身の見積もりによるものです。Plus と Ultra $99.99 は、Google が[公表している倍率](https://support.google.com/gemininotebook/answer/17670842?hl=ja)で換算しています。 - Flow の動画と画像には毎回 CAPTCHA が必要で、API が解決します。最初のアカウントは300回まで無料で、その後はご自身の [CAPTCHA プロバイダー](/docs/start-here/setup-google-flow#configure-captcha-providers)で1,000回あたり約 $0.80〜$3.00 です。 - プランの料金は Google の米国価格です。[Google Flow](/docs/api-google-flow-v1#pricing) と [Google Vids](/docs/api-google-vids-v1#pricing) の料金表には、すべてのプランの全モデルが載っています。 ### Google Flow:Veo 3.1、Omni Flash、Nano Banana [Google Flow API](/docs/api-google-flow-v1) は、プランの Flow クレジットで Veo 3.1 Fast、Quality、Lite の動画と、Omni 1.2 Flash、Omni 1.1 Flash の動画を生成します。クレジットを使わない Nano Banana Pro、2.1、2 Lite の画像も生成でき、動画と画像のアップスケールにも対応しています。 Google 側では、Veo 3.1 は [Agent Platform](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing) で動き、Fast は 720p で1秒 $0.10、1080p で $0.12 です。Omni 1.2 Flash と Nano Banana は [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) で動きます。どちらも課金を有効にした Google Cloud プロジェクトが必要です。Veo の料金はすべて [Veo 3.1 API の料金比較](/docs/articles/veo-3-1-api-pricing)(英語)で比べています。 ### Google Vids:Omni 1.2 Flash と AI アバター動画 [Google Vids API](/docs/api-google-vids-v1) は、3〜15秒の音声付き Omni 1.2 Flash 動画を 720p または 1080p で、同じ秒数で生成し、延長、編集、アップスケールもできます。最長30秒の [AI アバター動画](/docs/api-google-vids-v1/post-google-vids-videos-avatar)、30種類の声の[音声読み上げ](/docs/api-google-vids-v1/post-google-vids-speech)、基本的な画像も作れます。これらは動画の秒数を使いません。 Google は Vids の API を公開していません。同じモデルを Gemini API で使うと、720p で1秒 $0.07、1080p で $0.104 です。Vids では CAPTCHA は不要です。秒数は Google のファミリープランのメンバー全員で共有されます。[Omni 1.2 Flash のガイド](/docs/articles/gemini-omni-1-2-flash-api)(英語)では、同じシーンを Flow と Vids で1本ずつ作っています。 ### Gemini Notebook(NotebookLM):ポッドキャスト、動画、Deep Research [Gemini Notebook API(NotebookLM API)](/docs/api-gemini-notebook-v1) は、Web ページ、PDF、YouTube 動画から、音声解説(ポッドキャスト)、動画解説、スライド資料、インフォグラフィック、レポート、クイズを作ります。引用付きのチャットと Deep Research も実行できます。シネマティックな動画解説には Pro または Ultra が必要です。 Notebook にクレジットはありません。ジョブごとにアカウントの利用枠の一部を使い、利用枠は5時間ごとに回復して、週間の上限まで使えます。Plus は無料版の2倍、Pro は4倍、Ultra は Pro の5倍または20倍です。Google 自身の [Gemini Notebook Enterprise API](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks) はプレビュー版で、Google Cloud プロジェクトに Enterprise ライセンスが必要です。対応しているのは、ノートブック、ソース、共有、音声解説だけです。 ### Google Flow Music:Lyria 3.5 の曲 有料の Google AI プランにはすべて、Flow クレジットとは別に [Google Flow Music](https://www.flowmusic.app) のクレジットも付いています。Plus は[月3,000クレジット](https://support.google.com/googleone/answer/16882689?hl=ja)、Pro は [10,000](https://support.google.com/googleone/answer/14534406?hl=ja)、Ultra は [30,000](https://support.google.com/googleone/answer/16286513?hl=ja) です。受け取りは一度だけで、同じ Google アカウントで flowmusic.app にログインし、Flow Music に Google One のメンバーシップの確認を許可します。 [Flow Music API](/docs/api-flowmusic-v1) は、Lyria 3.5 と Lyria 3 Pro で、ボーカル入りまたはインストゥルメンタルのフル尺の曲を1曲5クレジットで生成します。カバー、リミックス、延長、4つのステムへの分割にも対応しています。Google は Flow Music を Web サイトとしてのみ提供しています。Gemini API では Lyria 3.5 の曲は1曲 $0.08 で、生成した曲を編集することはできません。 ### 1つの Google アカウントで4つの利用枠 Flow クレジット、Vids の秒数、Notebook の利用枠、Flow Music クレジットはそれぞれ別に数えられ、どれもほかの枠を減らしません。同じ Google アカウントを4つの API すべてに接続すれば、すべての枠を使えます。Flow と Vids の両方で Omni 1.2 Flash 動画を作り、Notebook でポッドキャストと Deep Research、Flow Music で曲も作れます。API ごとにセットアップページがあり([Flow](/docs/start-here/setup-google-flow)、[Vids](/docs/start-here/setup-google-vids)、[Notebook](/docs/start-here/setup-gemini-notebook)、[Flow Music](/docs/start-here/setup-flowmusic))、useapi.net のサブスクリプション1つで4つすべてを使えます。 ### どのプランを選ぶか - Ultra $199.99 は、クレジットをまったく使わない[低優先度の Veo 3.1 Lite](/docs/api-google-flow-v1/post-google-flow-videos) を使える唯一のプランです。Google は上限を公表しておらず、当社で最も利用の多いアカウントは、月25,000クレジットとは別に、この動画を1日1,000本以上作っています。動画1本あたりの料金も最も安く、Veo 3.1 Fast は $0.08、15秒の Omni 1.2 Flash 動画は Vids で $0.30、Flow で $0.48 です。 - Ultra $99.99 は料金が半分ですが、低優先度の Veo 3.1 Lite はありません。Veo 3.1 Fast の動画を1本 $0.10 で1,000本、Vids の動画を1本 $0.60 で166本作れ、曲は同じ6,000曲です。 - 最初に選ぶなら Pro です。Veo 3.1 Fast の動画を月50本、Google の半額の1本 $0.40 で作れます。15秒の Vids 動画は $0.60 で33本、Lyria 3.5 の曲は2,000曲です。Pro で Omni 1.2 Flash を作るなら Vids を使ってください。Flow では $1.20 かかり、Gemini API の $1.04 より高くなります。 - Plus は、動画1本あたりの料金が Google の API より高くなることがあります。15秒・720p の Omni 1.2 Flash 動画は Flow で $1.50、Vids で $1.25 で、Gemini API では $1.04 です。Veo 3.1 Fast は $0.50 で $0.80 より安いものの、月10本だけです。Plus は動画より、曲(月600曲)、Nano Banana の画像、Gemini Notebook に向いています。 ## よくある質問 ### Google AI Ultra に Gemini API は含まれますか? useapi.net を使えば、Ultra $199.99 で毎月 Veo 3.1 Fast の動画2,500本、Vids の Omni 1.2 Flash 動画666本、曲6,000曲を作れます。Google の API に換算すると約 $3,919 分です(2026年11月時点)。プラン自体には Gemini API の利用分は含まれていません。付いてくるのは月 $100(Ultra $99.99 は $40)の [Google Cloud クレジット](https://developers.google.com/program/plans-and-pricing)で、Google Developer Program で有効にします。これで作れる15秒の Omni 1.2 Flash 動画は約96本です。 ### Google AI Pro のプランを API で使えますか? useapi.net を使えば使えます。Pro の Flow クレジット1,000、Vids の500秒、Flow Music クレジット10,000を REST API で使えます。Veo 3.1 Fast の動画を月50本、1本 $0.40 で作れ、Google の Agent Platform の $0.80 の半額です。15秒の Omni 1.2 Flash 動画は Vids で33本を1本 $0.60(Gemini API は $1.04)で作れ、Lyria 3.5 の曲2,000曲は Gemini API なら $160 分です(2026年11月時点)。Nano Banana の画像はクレジットを使いません。 ### Google AI Ultra で Veo 3.1 の動画は何本作れますか? useapi.net を使えば、Ultra $199.99 で8秒の Veo 3.1 Fast の動画を月2,500本、1本 $0.08 で作れます。Google の [Agent Platform](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing) では1本 $0.80 です。Ultra $99.99 なら1,000本を1本 $0.10 で作れます(2026年11月時点)。Ultra $199.99 では、クレジットを使わない低優先度の Veo 3.1 Lite も使え、当社で最も利用の多いアカウントでは1日1,000本以上です。 ### NotebookLM の API はありますか? useapi.net を使えば、通常の Google アカウントで使えます。Gemini Notebook API(NotebookLM API)は、無料プランを含む Google AI のプランで、音声解説と動画解説、スライド、引用付きのチャット、Deep Research を実行します。Google 自身の [Enterprise API](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks) はプレビュー版で、Google Cloud プロジェクトに Enterprise ライセンスが必要なうえ、動画解説、チャット、Deep Research には対応していません(2026年11月時点)。 ### 無料の Google アカウントでも使えますか? useapi.net を使えば、Flow と Notebook は無料アカウントでも使えます。無料アカウントの1日50の Flow クレジットで、Veo 3.1 Fast の動画2本、Lite なら5本、または 720p で10秒の Omni 1.2 Flash 動画1本を作れ、Nano Banana の画像はクレジットを使いません。Notebook では5時間の枠ごとに音声解説を約2本作れます。Gemini API には Omni 1.2 Flash と Nano Banana Pro の無料枠がありません(2026年11月時点)。例外は Vids で、当社がテストした無料アカウントには動画の秒数がありませんでした。 ### 出典 - Google、[Google AI のプラン](https://gemini.google/subscriptions/)と[デベロッパー向けプラン](https://gemini.google/subscriptions/?plans=developer)、2026年11月7日閲覧 - Google、[Google Developer Program のプラン](https://developers.google.com/program/plans-and-pricing)(プランごとの Google Cloud クレジット)と [New developer tools for Google AI Pro and Ultra subscribers](https://blog.google/innovation-and-ai/technology/developers-tools/gdp-premium-ai-pro-ultra/)、2026年1月27日 - Google One ヘルプ、[Google AI Plus](https://support.google.com/googleone/answer/16882689?hl=ja)、[Google AI Pro](https://support.google.com/googleone/answer/14534406?hl=ja)、[Google AI Ultra](https://support.google.com/googleone/answer/16286513?hl=ja) の Flow Music 特典、2026年11月7日閲覧 - Google、[Gemini API の料金](https://ai.google.dev/gemini-api/docs/pricing)(Omni 1.2 Flash、Nano Banana、Lyria 3.5)、2026年11月7日閲覧 - Google Cloud、[Agent Platform の料金](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing)(Veo 3.1)、2026年11月7日閲覧 - Google、[Flow クレジット](https://support.google.com/flow/answer/16526234?hl=ja)、[Google Vids の Gemini](https://support.google.com/docs/answer/15609411?hl=ja)、[Gemini Notebook の利用上限](https://support.google.com/gemininotebook/answer/17670842?hl=ja)、2026年11月7日閲覧 - Google Cloud、[Gemini Notebook Enterprise API](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks)、2026年11月7日閲覧 - useapi.net の料金表:[Google Flow API](/docs/api-google-flow-v1#pricing)、[Google Vids API](/docs/api-google-vids-v1#pricing)、[Gemini Notebook API](/docs/api-gemini-notebook-v1#pricing)、[Flow Music API](/docs/api-flowmusic-v1#pricing) ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-ai-subscription-api-pt === Document URL: https://useapi.net/docs/articles/google-ai-subscription-api-pt --- layout: default title: "Dá para usar a assinatura do Google AI por API? O que os planos Plus, Pro e Ultra oferecem" seo_title: "Google AI Pro e Ultra por API: o que o seu plano oferece" description: "Use o Google AI Plus, Pro ou Ultra por API com a useapi.net: um plano Ultra gera US$ 3.919 por mês em vídeos e músicas nos preços das APIs do Google." keywords: [Google AI Pro API, API Google AI Pro, Google AI Ultra API, API do Google AI Ultra, Google AI Plus API, assinatura Google AI API, Google AI Ultra inclui Gemini API, Google AI Pro acesso à API, Gemini assinatura API, Google One AI API, créditos do Flow API, Google Flow API, Google Vids API, Gemini Notebook API, NotebookLM API, Google Flow Music API, Lyria 3.5 API, créditos Flow Music Google AI Pro, Veo 3.1 API, Omni 1.2 Flash API, Nano Banana API, créditos Google Cloud, Google Developer Program, API de vídeo com IA, Google AI subscription API] parent: Articles nav_exclude: true lang: pt-BR translation_key: google-ai-subscription date: 2026-11-07 last_modified: 2026-11-07 nav_order: 910 repo: https://github.com/useapi/google-flow-api --- ## Dá para usar a assinatura do Google AI por API? O que os planos Plus, Pro e Ultra oferecem {: .no_toc #can-you-use-your-google-ai-subscription-through-an-api-what-plus-pro-and-ultra-get-you } 6 min de leitura • 7 de novembro de 2026 A useapi.net é uma API de terceiros. Não tem afiliação com o Google nem é endossada por ele. ## Sumário {: .no_toc .text-delta #table-of-contents } ### A resposta curta Sim, com a useapi.net. Seu [plano Google AI](https://gemini.google/subscriptions/) (Plus, Pro ou Ultra) vem com cotas mensais nas ferramentas criativas do Google. A useapi.net transforma cada uma delas em uma API: - [Google Flow API](/docs/api-google-flow-v1): vídeos com os seus créditos do Flow, e imagens que não gastam nenhum - [Google Vids API](/docs/api-google-vids-v1): vídeos, avatares falantes e voz com os seus segundos do Vids - [Gemini Notebook API (NotebookLM API)](/docs/api-gemini-notebook-v1): podcasts, slides e pesquisa com o seu uso do Notebook - [Flow Music API](/docs/api-flowmusic-v1): músicas com os créditos do Flow Music que o seu plano inclui No Ultra $199,99, um mês disso vale cerca de $3.919 nas APIs do próprio Google (em novembro de 2026). A Gemini API em si não faz parte do plano. O Google cobra por ela à parte, por segundo de vídeo e por imagem. O Pro e o Ultra incluem um pequeno [crédito mensal do Google Cloud](https://developers.google.com/program/plans-and-pricing) para ela: $10 no Pro, $40 no Ultra $99,99 e $100 no Ultra $199,99. Mesmo $100 compram só cerca de 96 vídeos Omni 1.2 Flash de quinze segundos lá. Os preços desta página são os do Google nos EUA, em dólares: no Brasil o Google cobra em reais e o preço pode ser diferente. ### Tudo o que um plano gera em um mês O que um único plano Google AI soma pela useapi.net a cada mês, e quanto a mesma produção custaria nas APIs do próprio Google (em novembro de 2026). | Um mês | Ultra $199,99 | Ultra $99,99 | Pro $19,99 | Plus $4,99 | |---|---|---|---|---| | **Google Flow** (um só saldo, escolha uma linha) | 25.000 cr | 10.000 cr | 1.000 cr | 200 cr | | Vídeos Veo 3.1 Fast (8 s, 1080p) | 2.500 | 1.000 | 50 | 10 | | ou vídeos Veo 3.1 Lite (8 s, 1080p) | 5.000 | 2.000 | 100 | 20 | | ou vídeos Omni 1.1 Flash (10 s, 1080p) | 1.666 | 666 | 66 | 13 | | ou vídeos Omni 1.2 Flash (10 s, 1080p, upscale grátis) | 833 | 333 | 33 | 6 | | ou vídeos Omni 1.2 Flash (15 s, 720p) | 416 | 166 | 16 | 3 | | ou upscales de vídeo em 4K (clipes de até 10 s) | 500 | 200 | — | — | | **Google Flow, sem créditos** (além do saldo) | | | | | | Vídeos Veo 3.1 Lite (prioridade baixa, 8 s) | 1.000+ por dia | — | — | — | | Upscales de vídeo a 1080p (clipes de até 10 s) | grátis | grátis | grátis | grátis | | Imagens Nano Banana (Pro, 2.1, 2 Lite, com upscale) | ~500 por dia, 4K | incluídas, 4K | incluídas, 2K | incluídas, 2K | | **Google Vids** (cota própria, a mais) | 10.000 s | 2.500 s | 500 s | 60 s | | Vídeos Omni 1.2 Flash (15 s, 1080p) | 666 | 166 | 33 | 4 | | Vídeos com avatar falante (até 30 s) | 500 | 125 | 25 | 6 | | Imagens (básicas, cerca de 1 MP) | 1.000 | 300 | 30 | até 50 | | Voz (30 vozes) | incluída | incluída | incluída | incluída | | **Flow Music** (créditos próprios, a mais) | 30.000 cr | 30.000 cr | 10.000 cr | 3.000 cr | | Músicas Lyria 3.5 (músicas completas) | 6.000 | 6.000 | 2.000 | 600 | | **Gemini Notebook** (limites próprios, a mais) | | | | | | Podcasts (por janela de 5 h) | 181 | ~45 | 9 | ~4 | | **Créditos Google Cloud** (para a Gemini API) | $100 | $40 | $10 | — | | **Valor nas APIs do Google** (vídeos e músicas) | **$3.919** | **$1.699** | **$259** | **$64** | - Os créditos do Google Flow são um saldo único. Um plano gera os vídeos Veo 3.1 Fast, ou uma das linhas com "ou", ou uma mistura delas, nunca todas. Tudo abaixo do saldo é uma cota separada e se soma a ele. - O Flow faz upscale de vídeo para 1080p de graça até 10 segundos e cobra 1 crédito por segundo acima disso ([upscale de vídeo](/docs/api-google-flow-v1/post-google-flow-videos-upscale), [página de créditos do Flow do Google](https://support.google.com/flow/answer/16526234?hl=pt-BR)). Por isso toda linha em 1080p no saldo do Flow conta clipes de 10 segundos ou menos. Um upscale para 4K gasta 50 créditos do saldo, só no Ultra. No Vids, 1080p gasta os mesmos segundos que 720p. - A linha de valor conta o saldo do Flow como Veo 3.1 Fast em 1080p ($0,96 por vídeo na API do Google), os vídeos do Vids em 1080p ($1,56) e as músicas a $0,08. Isso dá de 13 a 20 vezes o preço de cada plano. - Os "1.000+ por dia" vídeos Veo 3.1 Lite e as "~500 por dia" imagens são o que as nossas contas Ultra $199,99 mais ativas alcançam, não limites publicados pelo Google. O Lite em prioridade baixa só roda para o titular desse plano. - Os números do Vids são do Google, e a nossa conta Pro de teste mostrou exatamente 25 vídeos com avatar. O Google avisa que alguns planos dividem um mesmo limite entre avatares e clipes de vídeo. No Plus, imagens e narrações dividem 50 créditos por mês. O Pro e o Ultra listam a narração como ilimitada, mas as nossas contas de teste mostraram um contador de 50 usos por mês. O Google não tem API de avatares falantes. ### O que cada plano gera em um mês O que cada plano Google AI gera pela useapi.net, e quanto um item custa na API do próprio Google (em novembro de 2026). Cada vídeo custa a sua parte do plano: o preço do plano dividido pelo que o plano gera. | O que gera | API oficial | Ultra $199,99 (25.000 cr, 10.000 s) | Ultra $99,99 (10.000 cr, 2.500 s) | Pro $19,99 (1.000 cr, 500 s) | Plus $4,99 (200 cr, 60 s) | |---|---|---|---|---|---| | Omni 1.2 no Flow (720p, 15 s) | [$1,04](https://ai.google.dev/gemini-api/docs/pricing) ($0,07/s) | $0,48 / 60 cr (416 vídeos/mês) | $0,60 / 60 cr (166 vídeos/mês) | $1,20 / 60 cr (16 vídeos/mês) | $1,50 / 60 cr (3 vídeos/mês) | | Omni 1.1 no Flow (720p, 10 s) | [$1,01](https://ai.google.dev/gemini-api/docs/pricing) ($0,10/s) | $0,12 / 15 cr (1.666 vídeos/mês) | $0,15 / 15 cr (666 vídeos/mês) | $0,30 / 15 cr (66 vídeos/mês) | $0,37 / 15 cr (13 vídeos/mês) | | Omni 1.2 no Vids (720p, 15 s) | [$1,04](https://ai.google.dev/gemini-api/docs/pricing) ($0,07/s) | $0,30 / 15 s (666 vídeos/mês) | $0,60 / 15 s (166 vídeos/mês) | $0,60 / 15 s (33 vídeos/mês) | $1,25 / 15 s (4 vídeos/mês) | | Omni 1.2 no Vids (1080p, 15 s) | [$1,56](https://ai.google.dev/gemini-api/docs/pricing) ($0,104/s) | $0,30 / 15 s (666 vídeos/mês) | $0,60 / 15 s (166 vídeos/mês) | $0,60 / 15 s (33 vídeos/mês) | $1,25 / 15 s (4 vídeos/mês) | | Veo 3.1 Fast (Flow, 720p, 8 s) | [$0,80](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing) ($0,10/s) | $0,08 / 10 cr (2.500 vídeos/mês) | $0,10 / 10 cr (1.000 vídeos/mês) | $0,40 / 20 cr (50 vídeos/mês) | $0,50 / 20 cr (10 vídeos/mês) | | Nano Banana Pro (imagem no Flow) | [$0,134](https://ai.google.dev/gemini-api/docs/pricing) (por imagem) | $0 / 0 cr (~500 por dia) | $0 / 0 cr (incluídas) | $0 / 0 cr (incluídas) | $0 / 0 cr (incluídas) | | Música Lyria 3.5 (Flow Music) | [$0,08](https://ai.google.dev/gemini-api/docs/pricing) (por música) | $0,033 / 5 cr (6.000/mês) | $0,017 / 5 cr (6.000/mês) | $0,010 / 5 cr (2.000/mês) | $0,008 / 5 cr (600/mês) | | Notebook (podcasts por 5 h) | [Enterprise](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks) (Preview) | 181 | ~45 | 9 | ~4 | | Créditos Cloud (uso da Gemini API) | — | $100/mês | $40/mês | $10/mês | — | - A linha do Notebook conta os Audio Overviews (podcasts) que uma janela completa de 5 horas consegue iniciar, pelas estimativas do próprio Google. Plus e Ultra $99,99 seguem os [multiplicadores publicados](https://support.google.com/gemininotebook/answer/17670842?hl=pt-BR) pelo Google. - Cada vídeo e imagem do Flow pede um captcha, que a API resolve. A sua primeira conta ganha 300 grátis. Depois disso, o seu próprio [provedor de captcha](/docs/start-here/setup-google-flow#configure-captcha-providers) custa cerca de $0,80 a $3,00 por 1.000. - Os preços dos planos são os preços do Google nos EUA. As tabelas de preço do [Google Flow](/docs/api-google-flow-v1#pricing) e do [Google Vids](/docs/api-google-vids-v1#pricing) listam todos os modelos em todos os planos. ### Google Flow: Veo 3.1, Omni Flash e Nano Banana A [Google Flow API](/docs/api-google-flow-v1) gera vídeos Veo 3.1 Fast, Quality e Lite e vídeos Omni 1.2 Flash e Omni 1.1 Flash com os créditos do Flow do plano. Também gera imagens Nano Banana Pro, 2.1 e 2 Lite, que não gastam créditos, e faz upscale de vídeos e imagens. Do lado do Google, o Veo 3.1 roda na [Agent Platform](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing) a $0,10 por segundo no Fast em 720p e $0,12 em 1080p. O Omni 1.2 Flash e o Nano Banana rodam na [Gemini API](https://ai.google.dev/gemini-api/docs/pricing). As duas exigem um projeto Google Cloud com faturamento. O artigo [Veo 3.1 API pricing](/docs/articles/veo-3-1-api-pricing) (em inglês) compara todos os preços do Veo. ### Google Vids: Omni 1.2 Flash e avatares falantes A [Google Vids API](/docs/api-google-vids-v1) gera vídeos Omni 1.2 Flash de 3 a 15 segundos com som, em 720p ou 1080p pelos mesmos segundos, e estende, edita e faz upscale deles. Também gera [vídeos com avatar falante](/docs/api-google-vids-v1/post-google-vids-videos-avatar) de até 30 segundos, [voz](/docs/api-google-vids-v1/post-google-vids-speech) em 30 vozes e imagens básicas. Nada disso gasta segundos de vídeo. O Google não publica nenhuma API do Vids. O mesmo modelo na Gemini API custa $0,07 por segundo em 720p e $0,104 em 1080p. O Vids não pede captcha. Os segundos são divididos entre todos os membros de um plano família do Google. O [guia do Omni 1.2 Flash](/docs/articles/gemini-omni-1-2-flash-api) (em inglês) roda uma cena no Flow e outra no Vids. ### Gemini Notebook (NotebookLM): podcasts, vídeo e Deep Research A [Gemini Notebook API (NotebookLM API)](/docs/api-gemini-notebook-v1) transforma páginas da web, PDFs e vídeos do YouTube em Audio Overviews (podcasts), Video Overviews, apresentações de slides, infográficos, relatórios e quizzes, e roda chat com citações e Deep Research. Os Cinematic Video Overviews exigem Pro ou Ultra. O Notebook não tem créditos. Cada tarefa usa parte do uso da conta, que se renova a cada 5 horas até um limite semanal: o Plus tem 2 vezes os limites gratuitos, o Pro 4 vezes, e o Ultra 5 ou 20 vezes os do Pro. A [Gemini Notebook Enterprise API](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks) do próprio Google está em Preview, exige licenças Enterprise em um projeto Google Cloud e cobre só notebooks, fontes, compartilhamento e Audio Overviews. ### Google Flow Music: músicas com Lyria 3.5 Todo plano pago do Google AI também inclui créditos do [Google Flow Music](https://www.flowmusic.app), separados dos créditos do Flow. O Plus recebe [3.000 créditos por mês](https://support.google.com/googleone/answer/16882689?hl=pt-BR), o Pro [10.000](https://support.google.com/googleone/answer/14534406?hl=pt-BR) e o Ultra [30.000](https://support.google.com/googleone/answer/16286513?hl=pt-BR). Você resgata uma vez: entre em flowmusic.app com a mesma conta Google e deixe o Flow Music ver a sua assinatura do Google One. A [Flow Music API](/docs/api-flowmusic-v1) gera músicas completas, com vocal ou instrumentais, no Lyria 3.5 e no Lyria 3 Pro, a 5 créditos por música. Também faz covers, remixes e extensões, e separa as músicas em quatro stems. O Google oferece o Flow Music só como site. Na Gemini API, uma música do Lyria 3.5 custa $0,08, e uma música gerada não pode ser editada lá. ### Uma conta Google, quatro cotas Créditos do Flow, segundos do Vids, uso do Notebook e créditos do Flow Music são contados à parte, e nenhum tira do outro. Conecte a mesma conta Google às quatro APIs e ela usa todas as cotas: vídeos Omni 1.2 Flash no Flow e no Vids, um somado ao outro, podcasts e Deep Research no Notebook, e músicas no Flow Music. Cada API tem a sua página de configuração ([Flow](/docs/start-here/setup-google-flow), [Vids](/docs/start-here/setup-google-vids), [Notebook](/docs/start-here/setup-gemini-notebook), [Flow Music](/docs/start-here/setup-flowmusic)), e uma única assinatura da useapi.net cobre as quatro. ### Qual plano escolher - O Ultra $199,99 é o único plano com [Veo 3.1 Lite em prioridade baixa](/docs/api-google-flow-v1/post-google-flow-videos), que não gasta crédito nenhum. O Google não publica limite, e as nossas contas mais ativas fazem 1.000+ desses vídeos por dia, além dos 25.000 créditos mensais. Ele também tem o menor preço por vídeo: Veo 3.1 Fast a $0,08, e um vídeo Omni 1.2 Flash de quinze segundos a $0,30 no Vids ou $0,48 no Flow. - O Ultra $99,99 custa a metade, mas não tem Veo 3.1 Lite em prioridade baixa. Ele gera 1.000 vídeos Veo 3.1 Fast a $0,10 e 166 vídeos no Vids a $0,60, com as mesmas 6.000 músicas. - O Pro é o plano para começar. Ele gera 50 vídeos Veo 3.1 Fast por mês a $0,40, metade do preço do Google, 33 vídeos de quinze segundos no Vids a $0,60 e 2.000 músicas Lyria 3.5. No Pro, gere o Omni 1.2 Flash no Vids: no Flow ele custa $1,20, mais que os $1,04 da Gemini API. - O Plus pode custar mais por vídeo que a API do Google. Um vídeo Omni 1.2 Flash de quinze segundos em 720p sai a $1,50 no Flow e $1,25 no Vids, contra $1,04. O Veo 3.1 Fast ainda é mais barato, $0,50 contra $0,80, mas são só 10 por mês. O Plus serve melhor para músicas (600 por mês), imagens Nano Banana e o Gemini Notebook do que para vídeo. ## Perguntas ### O Google AI Ultra inclui acesso à Gemini API? Com a useapi.net, o Ultra $199,99 gera 2.500 vídeos Veo 3.1 Fast, 666 vídeos Omni 1.2 Flash no Vids e 6.000 músicas por mês, o que vale cerca de $3.919 nas APIs do Google (em novembro de 2026). O plano em si não inclui uso da Gemini API. Ele vem com [créditos do Google Cloud](https://developers.google.com/program/plans-and-pricing) de $100 por mês ($40 no Ultra $99,99), que você ativa no Google Developer Program. Isso compra cerca de 96 vídeos Omni 1.2 Flash de quinze segundos. ### Posso usar o meu plano Google AI Pro por API? Com a useapi.net, sim: os 1.000 créditos do Flow, os 500 segundos do Vids e os 10.000 créditos do Flow Music do Pro funcionam via REST. Eles geram 50 vídeos Veo 3.1 Fast por mês a $0,40 cada, contra $0,80 na Agent Platform do Google. Também geram 33 vídeos Omni 1.2 Flash de quinze segundos no Vids a $0,60, contra $1,04 na Gemini API, e 2.000 músicas Lyria 3.5, que valem $160 lá (em novembro de 2026). Imagens Nano Banana não gastam créditos. ### Quantos vídeos Veo 3.1 o Google AI Ultra gera? Com a useapi.net, o Ultra $199,99 gera 2.500 vídeos Veo 3.1 Fast de oito segundos por mês a $0,08 cada, contra $0,80 na [Agent Platform](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing) do Google, e o Ultra $99,99 gera 1.000 a $0,10 (em novembro de 2026). O Ultra $199,99 também roda o Veo 3.1 Lite em prioridade baixa sem gastar créditos, cerca de 1.000 ou mais por dia nas nossas contas mais ativas. ### Existe API do NotebookLM? Com a useapi.net, sim, para contas Google comuns: a Gemini Notebook API (NotebookLM API) roda Audio e Video Overviews, slides, chat com citações e Deep Research no seu plano Google AI, inclusive no gratuito. A [Enterprise API](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks) do próprio Google está em Preview, exige licenças Enterprise em um projeto Google Cloud e não tem Video Overviews, chat nem Deep Research (em novembro de 2026). ### Funciona com uma conta Google gratuita? Com a useapi.net, sim, no Flow e no Notebook. Os 50 créditos diários do Flow de uma conta gratuita geram 2 vídeos Veo 3.1 Fast, 5 do Lite ou um vídeo Omni 1.2 Flash de 10 segundos em 720p, e imagens Nano Banana não gastam créditos. O Notebook inicia cerca de 2 Audio Overviews por janela de 5 horas. A Gemini API não tem nível gratuito para Omni 1.2 Flash nem Nano Banana Pro (em novembro de 2026). O Vids é a exceção: as contas gratuitas que testamos não tinham segundos de vídeo. ### Fontes - Google, [planos Google AI](https://gemini.google/subscriptions/) e os [planos para desenvolvedores](https://gemini.google/subscriptions/?plans=developer), consultados em 7 de novembro de 2026 - Google, [planos do Google Developer Program](https://developers.google.com/program/plans-and-pricing) (créditos do Google Cloud por plano) e [New developer tools for Google AI Pro and Ultra subscribers](https://blog.google/innovation-and-ai/technology/developers-tools/gdp-premium-ai-pro-ultra/), 27 de janeiro de 2026 - Ajuda do Google One, benefícios do Flow Music no [Google AI Plus](https://support.google.com/googleone/answer/16882689?hl=pt-BR), no [Google AI Pro](https://support.google.com/googleone/answer/14534406?hl=pt-BR) e no [Google AI Ultra](https://support.google.com/googleone/answer/16286513?hl=pt-BR), consultados em 7 de novembro de 2026 - Google, [preços da Gemini API](https://ai.google.dev/gemini-api/docs/pricing) (Omni 1.2 Flash, Nano Banana, Lyria 3.5), consultados em 7 de novembro de 2026 - Google Cloud, [preços da Agent Platform](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing) (Veo 3.1), consultados em 7 de novembro de 2026 - Google, [créditos do Flow](https://support.google.com/flow/answer/16526234?hl=pt-BR), [Gemini no Google Vids](https://support.google.com/docs/answer/15609411?hl=pt-BR) e [limites de uso do Gemini Notebook](https://support.google.com/gemininotebook/answer/17670842?hl=pt-BR), consultados em 7 de novembro de 2026 - Google Cloud, [Gemini Notebook Enterprise API](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks), consultada em 7 de novembro de 2026 - Tabelas de preço da useapi.net: [Google Flow API](/docs/api-google-flow-v1#pricing), [Google Vids API](/docs/api-google-vids-v1#pricing), [Gemini Notebook API](/docs/api-gemini-notebook-v1#pricing) e [Flow Music API](/docs/api-flowmusic-v1#pricing) ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-ai-subscription-api-th === Document URL: https://useapi.net/docs/articles/google-ai-subscription-api-th --- layout: default title: "ใช้แพ็กเกจ Google AI ผ่าน API ได้ไหม? Plus, Pro และ Ultra ได้อะไรบ้าง" seo_title: "ใช้ Google AI Pro และ Ultra ผ่าน API: แพ็กเกจของคุณได้อะไรบ้าง" description: "ใช้ Google AI Plus, Pro หรือ Ultra ผ่าน API ด้วย useapi.net: Ultra แพ็กเกจเดียวสร้างวิดีโอและเพลงมูลค่า $3,919 ต่อเดือนตามราคา API ของ Google" keywords: [Google AI Pro API, Google AI Ultra API, Google AI Plus API, Google AI subscription API, ใช้ Google AI Pro ผ่าน API, Google AI Ultra ใช้ Gemini API ได้ไหม, Gemini API ราคา, แพ็กเกจ Google AI, Google One AI API, เครดิต Flow, Google Flow API, Google Vids API, Gemini Notebook API, NotebookLM API, Flow Music API, Lyria 3.5 API, Veo 3.1 API, Omni 1.2 Flash API, Nano Banana API, API สร้างวิดีโอ, API สร้างเพลง, เครดิต Google Cloud, Google Developer Program] parent: Articles nav_exclude: true lang: th translation_key: google-ai-subscription date: 2026-11-07 last_modified: 2026-11-07 nav_order: 910 repo: https://github.com/useapi/google-flow-api --- ## ใช้แพ็กเกจ Google AI ผ่าน API ได้ไหม? Plus, Pro และ Ultra ได้อะไรบ้าง {: .no_toc #can-you-use-your-google-ai-subscription-through-an-api-what-plus-pro-and-ultra-get-you } อ่าน 6 นาที • 7 พฤศจิกายน 2026 useapi.net เป็น API ของบุคคลที่สาม (third-party) ไม่มีส่วนเกี่ยวข้องกับ Google และไม่ได้รับการรับรองจาก Google ## สารบัญ {: .no_toc .text-delta #table-of-contents } ### คำตอบสั้น ๆ ได้ ผ่าน useapi.net [แพ็กเกจ Google AI](https://gemini.google/subscriptions/) ของคุณ (Plus, Pro หรือ Ultra) มีโควตารายเดือนสำหรับเครื่องมือสร้างสรรค์ของ Google และ useapi.net เปลี่ยนแต่ละโควตาให้เป็น API: - [Google Flow API](/docs/api-google-flow-v1): วิดีโอจากเครดิต Flow และภาพที่ไม่ใช้เครดิตเลย - [Google Vids API](/docs/api-google-vids-v1): วิดีโอ อวตารพูดได้ และเสียงพูด จากวินาทีของ Vids - [Gemini Notebook API (NotebookLM API)](/docs/api-gemini-notebook-v1): พอดแคสต์ สไลด์ และงานค้นคว้า จากโควตาการใช้งาน Notebook - [Flow Music API](/docs/api-flowmusic-v1): เพลงจากเครดิต Flow Music ที่มาพร้อมแพ็กเกจ บน Ultra $199.99 สิ่งที่ได้ในหนึ่งเดือนมีมูลค่าราว $3,919 ตามราคา API ของ Google เอง (ข้อมูล ณ พฤศจิกายน 2026) ตัว Gemini API ไม่ได้รวมอยู่ในแพ็กเกจ Google คิดเงินแยกต่างหาก ตามวินาทีของวิดีโอและตามจำนวนภาพ แพ็กเกจ Pro และ Ultra มี[เครดิต Google Cloud](https://developers.google.com/program/plans-and-pricing) รายเดือนให้เล็กน้อยสำหรับใช้กับ Gemini API คือ $10 บน Pro, $40 บน Ultra $99.99 และ $100 บน Ultra $199.99 แต่ถึงจะเป็น $100 ก็ซื้อวิดีโอ Omni 1.2 Flash ยาว 15 วินาทีบน Gemini API ได้แค่ราว 96 คลิป ราคาในหน้านี้เป็นราคาของ Google ในสหรัฐฯ เป็นดอลลาร์สหรัฐ ในประเทศไทย Google เรียกเก็บเป็นเงินบาท และราคาอาจต่างออกไป ### ทุกอย่างที่แพ็กเกจเดียวสร้างได้ในหนึ่งเดือน สิ่งที่แพ็กเกจ Google AI หนึ่งแพ็กเกจสร้างได้ผ่าน useapi.net ในแต่ละเดือน และมูลค่าของผลงานเดียวกันถ้าสร้างบน API ของ Google เอง (ข้อมูล ณ พฤศจิกายน 2026) | ต่อเดือน | Ultra $199.99 | Ultra $99.99 | Pro $19.99 | Plus $4.99 | |---|---|---|---|---| | **Google Flow** (เครดิตก้อนเดียว เลือกหนึ่งแถว) | 25,000 cr | 10,000 cr | 1,000 cr | 200 cr | | คลิป Veo 3.1 Fast (8 วิ, 1080p) | 2,500 | 1,000 | 50 | 10 | | หรือคลิป Veo 3.1 Lite (8 วิ, 1080p) | 5,000 | 2,000 | 100 | 20 | | หรือคลิป Omni 1.1 Flash (10 วิ, 1080p) | 1,666 | 666 | 66 | 13 | | หรือคลิป Omni 1.2 Flash (10 วิ, 1080p, อัปสเกลฟรี) | 833 | 333 | 33 | 6 | | หรือคลิป Omni 1.2 Flash (15 วิ, 720p) | 416 | 166 | 16 | 3 | | หรืออัปสเกลเป็น 4K (คลิปไม่เกิน 10 วิ) | 500 | 200 | — | — | | **Google Flow ไม่ใช้เครดิต** (ได้เพิ่มจากก้อนเครดิต) | | | | | | คลิป Veo 3.1 Lite (ลำดับรอง, 8 วิ) | 1,000+/วัน | — | — | — | | อัปสเกลวิดีโอเป็น 1080p (คลิปไม่เกิน 10 วิ) | ฟรี | ฟรี | ฟรี | ฟรี | | ภาพ Nano Banana (Pro, 2.1, 2 Lite, อัปสเกล) | ~500/วัน, 4K | ใช้ได้, 4K | ใช้ได้, 2K | ใช้ได้, 2K | | **Google Vids** (โควตาแยก, ได้เพิ่ม) | 10,000 วิ | 2,500 วิ | 500 วิ | 60 วิ | | คลิป Omni 1.2 Flash (15 วิ, 1080p) | 666 | 166 | 33 | 4 | | คลิปอวตารพูดได้ (สูงสุด 30 วิ) | 500 | 125 | 25 | 6 | | ภาพ (พื้นฐาน, ราว 1 MP) | 1,000 | 300 | 30 | สูงสุด 50 | | เสียงพูด (30 เสียง) | ใช้ได้ | ใช้ได้ | ใช้ได้ | ใช้ได้ | | **Flow Music** (เครดิตแยก, ได้เพิ่ม) | 30,000 cr | 30,000 cr | 10,000 cr | 3,000 cr | | เพลง Lyria 3.5 (เต็มเพลง) | 6,000 | 6,000 | 2,000 | 600 | | **Gemini Notebook** (ลิมิตแยก, ได้เพิ่ม) | | | | | | พอดแคสต์ (ต่อรอบ 5 ชั่วโมง) | 181 | ~45 | 9 | ~4 | | **เครดิต Google Cloud** (สำหรับ Gemini API) | $100 | $40 | $10 | — | | **มูลค่าบน API ของ Google** (วิดีโอและเพลง) | **$3,919** | **$1,699** | **$259** | **$64** | - เครดิต Google Flow เป็นก้อนเดียว แพ็กเกจหนึ่งจะสร้างคลิป Veo 3.1 Fast หรือแถว "หรือ" แถวใดแถวหนึ่ง หรือผสมกันก็ได้ แต่ไม่ได้ทุกแถวพร้อมกัน ทุกอย่างที่อยู่ใต้ก้อนเครดิตนี้เป็นโควตาแยก และได้เพิ่มจากก้อนนี้ - Flow อัปสเกลวิดีโอเป็น 1080p ได้ฟรีสำหรับคลิปไม่เกิน 10 วินาที และคิด 1 เครดิตต่อทุกวินาทีที่เกิน ([อัปสเกลวิดีโอ](/docs/api-google-flow-v1/post-google-flow-videos-upscale), [หน้าเครดิต Flow ของ Google](https://support.google.com/flow/answer/16526234?hl=th)) ทุกแถว 1080p ในก้อนเครดิต Flow จึงนับคลิปยาวไม่เกิน 10 วินาที การอัปสเกลเป็น 4K ใช้ 50 เครดิตจากก้อนนี้ และมีเฉพาะ Ultra ส่วนใน Vids วิดีโอ 1080p ใช้วินาทีเท่ากับ 720p - แถวมูลค่านับก้อนเครดิต Flow เป็น Veo 3.1 Fast ที่ 1080p ($0.96 ต่อคลิปบน API ของ Google) วิดีโอ Vids ที่ 1080p ($1.56) และเพลงที่ $0.08 รวมแล้วเท่ากับ 13 ถึง 20 เท่าของราคาแต่ละแพ็กเกจ - ตัวเลข Veo 3.1 Lite "1,000+/วัน" และภาพ "~500/วัน" คือสิ่งที่บัญชี Ultra $199.99 ที่ใช้งานหนักที่สุดของเราทำได้ ไม่ใช่ลิมิตที่ Google ประกาศ Lite แบบลำดับรองใช้ได้เฉพาะเจ้าของแพ็กเกจนั้น - ตัวเลขของ Vids มาจาก Google และบัญชีทดสอบ Pro ของเราแสดงวิดีโออวตารพอดี 25 คลิป Google ระบุว่าบางแพ็กเกจใช้ลิมิตร่วมกันระหว่างอวตารกับคลิปวิดีโอ บน Plus ภาพและเสียงบรรยายใช้เครดิตร่วมกัน 50 เครดิตต่อเดือน Pro และ Ultra ระบุว่าเสียงบรรยายไม่จำกัด แต่บัญชีทดสอบของเราแสดงตัวนับ 50 ครั้งต่อเดือน Google ไม่มี API สำหรับอวตารพูดได้ ### แต่ละแพ็กเกจสร้างอะไรได้บ้างในหนึ่งเดือน สิ่งที่แต่ละแพ็กเกจ Google AI สร้างได้ผ่าน useapi.net และราคาต่อชิ้นบน API ของ Google เอง (ข้อมูล ณ พฤศจิกายน 2026) หัวตารางคือราคาแพ็กเกจต่อเดือน วิดีโอหนึ่งคลิปคิดตามสัดส่วนของแพ็กเกจ คือราคาแพ็กเกจหารด้วยจำนวนที่แพ็กเกจสร้างได้ | สิ่งที่สร้าง | API ทางการ | Ultra $199.99 (25,000 cr, 10,000 วิ) | Ultra $99.99 (10,000 cr, 2,500 วิ) | Pro $19.99 (1,000 cr, 500 วิ) | Plus $4.99 (200 cr, 60 วิ) | |---|---|---|---|---|---| | Omni 1.2 ใน Flow (720p, 15 วิ) | [$1.04](https://ai.google.dev/gemini-api/docs/pricing) ($0.07/วิ) | $0.48 / 60 cr (416 คลิป/เดือน) | $0.60 / 60 cr (166 คลิป/เดือน) | $1.20 / 60 cr (16 คลิป/เดือน) | $1.50 / 60 cr (3 คลิป/เดือน) | | Omni 1.1 ใน Flow (720p, 10 วิ) | [$1.01](https://ai.google.dev/gemini-api/docs/pricing) ($0.10/วิ) | $0.12 / 15 cr (1,666 คลิป/เดือน) | $0.15 / 15 cr (666 คลิป/เดือน) | $0.30 / 15 cr (66 คลิป/เดือน) | $0.37 / 15 cr (13 คลิป/เดือน) | | Omni 1.2 ใน Vids (720p, 15 วิ) | [$1.04](https://ai.google.dev/gemini-api/docs/pricing) ($0.07/วิ) | $0.30 / 15 วิ (666 คลิป/เดือน) | $0.60 / 15 วิ (166 คลิป/เดือน) | $0.60 / 15 วิ (33 คลิป/เดือน) | $1.25 / 15 วิ (4 คลิป/เดือน) | | Omni 1.2 ใน Vids (1080p, 15 วิ) | [$1.56](https://ai.google.dev/gemini-api/docs/pricing) ($0.104/วิ) | $0.30 / 15 วิ (666 คลิป/เดือน) | $0.60 / 15 วิ (166 คลิป/เดือน) | $0.60 / 15 วิ (33 คลิป/เดือน) | $1.25 / 15 วิ (4 คลิป/เดือน) | | Veo 3.1 Fast (Flow, 720p, 8 วิ) | [$0.80](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing) ($0.10/วิ) | $0.08 / 10 cr (2,500 คลิป/เดือน) | $0.10 / 10 cr (1,000 คลิป/เดือน) | $0.40 / 20 cr (50 คลิป/เดือน) | $0.50 / 20 cr (10 คลิป/เดือน) | | Nano Banana Pro (ภาพใน Flow) | [$0.134](https://ai.google.dev/gemini-api/docs/pricing) (ต่อภาพ) | $0 / 0 cr (~500/วัน) | $0 / 0 cr (ใช้ได้) | $0 / 0 cr (ใช้ได้) | $0 / 0 cr (ใช้ได้) | | เพลง Lyria 3.5 (Flow Music) | [$0.08](https://ai.google.dev/gemini-api/docs/pricing) (ต่อเพลง) | $0.033 / 5 cr (6,000 เพลง/เดือน) | $0.017 / 5 cr (6,000 เพลง/เดือน) | $0.010 / 5 cr (2,000 เพลง/เดือน) | $0.008 / 5 cr (600 เพลง/เดือน) | | Notebook (พอดแคสต์/5 ชม.) | [Enterprise](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks) (Preview) | 181 | ~45 | 9 | ~4 | | เครดิต Cloud (ใช้กับ Gemini API) | — | $100/เดือน | $40/เดือน | $10/เดือน | — | - แถว Notebook นับจำนวน Audio Overviews (พอดแคสต์) ที่เริ่มได้ในหนึ่งรอบ 5 ชั่วโมงเต็ม ตามตัวเลขประมาณของ Google เอง ส่วน Plus และ Ultra $99.99 คำนวณจาก[ตัวคูณที่ Google ประกาศ](https://support.google.com/gemininotebook/answer/17670842?hl=th) - วิดีโอและภาพใน Flow ทุกชิ้นต้องผ่าน captcha ซึ่ง API แก้ให้ บัญชีแรกของคุณได้ฟรี 300 ครั้ง หลังจากนั้นใช้[ผู้ให้บริการ captcha](/docs/start-here/setup-google-flow#configure-captcha-providers) ของคุณเอง ราว $0.80 ถึง $3.00 ต่อ 1,000 ครั้ง - ราคาแพ็กเกจเป็นราคาสหรัฐฯ ของ Google ตารางราคาของ [Google Flow](/docs/api-google-flow-v1#pricing) และ [Google Vids](/docs/api-google-vids-v1#pricing) แสดงทุกโมเดลบนทุกแพ็กเกจ ### Google Flow: Veo 3.1, Omni Flash และ Nano Banana [Google Flow API](/docs/api-google-flow-v1) สร้างวิดีโอ Veo 3.1 Fast, Quality และ Lite รวมถึง Omni 1.2 Flash และ Omni 1.1 Flash จากเครดิต Flow ของแพ็กเกจ และยังสร้างภาพ Nano Banana Pro, 2.1 และ 2 Lite ซึ่งไม่ใช้เครดิต รวมถึงอัปสเกลวิดีโอและภาพได้ด้วย ฝั่ง Google นั้น Veo 3.1 ทำงานบน [Agent Platform](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing) ราคา $0.10 ต่อวินาทีสำหรับ Fast ที่ 720p และ $0.12 ที่ 1080p ส่วน Omni 1.2 Flash และ Nano Banana ทำงานบน [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) ทั้งสองต้องมีโปรเจกต์ Google Cloud ที่เปิดการเรียกเก็บเงินไว้ บทความ[ราคา Veo 3.1 API](/docs/articles/veo-3-1-api-pricing) เปรียบเทียบราคา Veo ทุกแบบ ### Google Vids: Omni 1.2 Flash และอวตารพูดได้ [Google Vids API](/docs/api-google-vids-v1) สร้างวิดีโอ Omni 1.2 Flash ยาว 3 ถึง 15 วินาทีพร้อมเสียง ที่ 720p หรือ 1080p โดยใช้วินาทีเท่ากัน และต่อความยาว แก้ไข และอัปสเกลวิดีโอได้ นอกจากนี้ยังสร้าง[วิดีโออวตารพูดได้](/docs/api-google-vids-v1/post-google-vids-videos-avatar) ยาวสูงสุด 30 วินาที [เสียงพูด](/docs/api-google-vids-v1/post-google-vids-speech) 30 เสียง และภาพพื้นฐาน ซึ่งทั้งหมดนี้ไม่ใช้วินาทีวิดีโอ Google ไม่มี API ของ Vids โมเดลเดียวกันบน Gemini API ราคา $0.07 ต่อวินาทีที่ 720p และ $0.104 ที่ 1080p Vids ไม่ต้องใช้ captcha และวินาทีของ Vids ใช้ร่วมกันทุกคนในแพ็กเกจครอบครัวของ Google [คู่มือ Omni 1.2 Flash](/docs/articles/gemini-omni-1-2-flash-api) สร้างฉากหนึ่งใน Flow และอีกฉากใน Vids ### Gemini Notebook (NotebookLM): พอดแคสต์ วิดีโอ และ Deep Research [Gemini Notebook API (NotebookLM API)](/docs/api-gemini-notebook-v1) เปลี่ยนหน้าเว็บ PDF และวิดีโอ YouTube ให้เป็น Audio Overviews (พอดแคสต์), Video Overviews, สไลด์, อินโฟกราฟิก, รายงาน และแบบทดสอบ รวมถึงแชตพร้อมแหล่งอ้างอิงและ Deep Research ส่วน Cinematic Video Overviews ต้องใช้ Pro หรือ Ultra Notebook ไม่มีเครดิต งานแต่ละชิ้นใช้โควตาการใช้งานของบัญชีไปส่วนหนึ่ง ซึ่งรีเฟรชทุก 5 ชั่วโมงจนถึงลิมิตรายสัปดาห์ Plus ได้ 2 เท่าของลิมิตฟรี Pro ได้ 4 เท่า และ Ultra ได้ 5 หรือ 20 เท่าของ Pro ส่วน [Gemini Notebook Enterprise API](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks) ของ Google เองยังเป็น Preview ต้องมีไลเซนส์ Enterprise ในโปรเจกต์ Google Cloud และรองรับแค่โน้ตบุ๊ก แหล่งข้อมูล การแชร์ และ Audio Overviews ### Google Flow Music: เพลง Lyria 3.5 แพ็กเกจ Google AI แบบเสียเงินทุกแพ็กเกจมีเครดิต [Google Flow Music](https://www.flowmusic.app) ให้ด้วย แยกจากเครดิต Flow โดย Plus ได้ [3,000 เครดิตต่อเดือน](https://support.google.com/googleone/answer/16882689?hl=th) Pro ได้ [10,000](https://support.google.com/googleone/answer/14534406?hl=th) และ Ultra ได้ [30,000](https://support.google.com/googleone/answer/16286513?hl=th) รับเครดิตเพียงครั้งเดียว โดยล็อกอินที่ flowmusic.app ด้วยบัญชี Google เดียวกัน แล้วอนุญาตให้ Flow Music เห็นสมาชิก Google One ของคุณ [Flow Music API](/docs/api-flowmusic-v1) สร้างเพลงเต็มเพลงทั้งแบบมีเสียงร้องและดนตรีล้วน บน Lyria 3.5 และ Lyria 3 Pro ใช้ 5 เครดิตต่อเพลง และยังทำคัฟเวอร์ รีมิกซ์ ต่อความยาวเพลง และแยกเพลงเป็น 4 สเต็มได้ Google ให้บริการ Flow Music เป็นเว็บไซต์เท่านั้น บน Gemini API เพลง Lyria 3.5 หนึ่งเพลงราคา $0.08 และแก้ไขเพลงที่สร้างแล้วไม่ได้ ### บัญชี Google เดียว โควตาสี่ส่วน เครดิต Flow วินาทีของ Vids โควตา Notebook และเครดิต Flow Music นับแยกกัน ไม่มีส่วนไหนกินโควตาของอีกส่วน เชื่อมบัญชี Google เดียวกันกับ API ทั้งสี่ตัว แล้วบัญชีนั้นจะใช้โควตาได้ครบทุกส่วน ทั้งวิดีโอ Omni 1.2 Flash ใน Flow และใน Vids ที่ได้เพิ่มกัน พอดแคสต์และ Deep Research จาก Notebook และเพลงจาก Flow Music API แต่ละตัวมีหน้าตั้งค่าของตัวเอง ([Flow](/docs/start-here/setup-google-flow), [Vids](/docs/start-here/setup-google-vids), [Notebook](/docs/start-here/setup-gemini-notebook), [Flow Music](/docs/start-here/setup-flowmusic)) และการสมัคร useapi.net ครั้งเดียวครอบคลุมทั้งสี่ตัว ### ควรเลือกแพ็กเกจไหน - Ultra $199.99 เป็นแพ็กเกจเดียวที่มี [Veo 3.1 Lite แบบลำดับรอง](/docs/api-google-flow-v1/post-google-flow-videos) ซึ่งไม่ใช้เครดิตเลย Google ไม่ประกาศลิมิต และบัญชีที่ใช้งานหนักที่สุดของเราสร้างวิดีโอแบบนี้ได้ 1,000+ คลิปต่อวัน เพิ่มจากเครดิตรายเดือน 25,000 เครดิต แพ็กเกจนี้ยังมีราคาต่อคลิปต่ำที่สุด คือ Veo 3.1 Fast ที่ $0.08 และวิดีโอ Omni 1.2 Flash ยาว 15 วินาทีที่ $0.30 ใน Vids หรือ $0.48 ใน Flow - Ultra $99.99 ราคาครึ่งหนึ่ง แต่ไม่มี Veo 3.1 Lite แบบลำดับรอง สร้าง Veo 3.1 Fast ได้ 1,000 คลิปที่ $0.10 และวิดีโอ Vids 166 คลิปที่ $0.60 พร้อมเพลง 6,000 เพลงเท่ากัน - Pro เป็นแพ็กเกจที่เหมาะจะเริ่มต้น สร้าง Veo 3.1 Fast ได้ 50 คลิปต่อเดือนที่ $0.40 ครึ่งหนึ่งของราคา Google วิดีโอ Vids ยาว 15 วินาที 33 คลิปที่ $0.60 และเพลง Lyria 3.5 อีก 2,000 เพลง บน Pro ควรสร้าง Omni 1.2 Flash ใน Vids เพราะใน Flow ตกคลิปละ $1.20 แพงกว่า $1.04 ของ Gemini API - Plus อาจแพงกว่า API ของ Google เมื่อคิดต่อคลิป วิดีโอ Omni 1.2 Flash 720p ยาว 15 วินาทีราคา $1.50 ใน Flow และ $1.25 ใน Vids เทียบกับ $1.04 ส่วน Veo 3.1 Fast ยังถูกกว่า คือ $0.50 เทียบกับ $0.80 แต่ได้แค่ 10 คลิปต่อเดือน Plus จึงเหมาะกับเพลง (600 เพลงต่อเดือน) ภาพ Nano Banana และ Gemini Notebook มากกว่าวิดีโอ ## คำถามที่พบบ่อย ### Google AI Ultra ใช้ Gemini API ได้ไหม? ผ่าน useapi.net Ultra $199.99 สร้าง Veo 3.1 Fast ได้ 2,500 คลิป วิดีโอ Omni 1.2 Flash ใน Vids 666 คลิป และเพลง 6,000 เพลงต่อเดือน มูลค่าราว $3,919 บน API ของ Google (ข้อมูล ณ พฤศจิกายน 2026) ตัวแพ็กเกจไม่มีโควตา Gemini API ให้ แต่มี[เครดิต Google Cloud](https://developers.google.com/program/plans-and-pricing) $100 ต่อเดือน ($40 บน Ultra $99.99) ที่ต้องเปิดใช้ใน Google Developer Program เครดิตนี้ซื้อวิดีโอ Omni 1.2 Flash ยาว 15 วินาทีได้ราว 96 คลิป ### ใช้แพ็กเกจ Google AI Pro ผ่าน API ได้ไหม? ผ่าน useapi.net ได้ เครดิต Flow 1,000 เครดิต วินาที Vids 500 วินาที และเครดิต Flow Music 10,000 เครดิตของ Pro ใช้ผ่าน REST ได้ทั้งหมด ได้ Veo 3.1 Fast 50 คลิปต่อเดือน คลิปละ $0.40 เทียบกับ $0.80 บน Agent Platform ของ Google ได้วิดีโอ Omni 1.2 Flash ยาว 15 วินาทีใน Vids 33 คลิป คลิปละ $0.60 เทียบกับ $1.04 บน Gemini API และเพลง Lyria 3.5 อีก 2,000 เพลง มูลค่า $160 บน API นั้น (ข้อมูล ณ พฤศจิกายน 2026) ภาพ Nano Banana ไม่ใช้เครดิต ### Google AI Ultra สร้างวิดีโอ Veo 3.1 ได้กี่คลิป? ผ่าน useapi.net Ultra $199.99 สร้างวิดีโอ Veo 3.1 Fast ยาว 8 วินาทีได้ 2,500 คลิปต่อเดือน คลิปละ $0.08 เทียบกับ $0.80 บน [Agent Platform](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing) ของ Google ส่วน Ultra $99.99 ได้ 1,000 คลิป คลิปละ $0.10 (ข้อมูล ณ พฤศจิกายน 2026) Ultra $199.99 ยังใช้ Veo 3.1 Lite แบบลำดับรองได้โดยไม่ใช้เครดิต ราว 1,000 คลิปขึ้นไปต่อวันบนบัญชีที่ใช้งานหนักที่สุดของเรา ### NotebookLM มี API ไหม? ผ่าน useapi.net มี สำหรับบัญชี Google ทั่วไป Gemini Notebook API (NotebookLM API) สร้าง Audio Overviews และ Video Overviews สไลด์ แชตพร้อมแหล่งอ้างอิง และ Deep Research บนแพ็กเกจ Google AI ของคุณ รวมถึงบัญชีฟรีด้วย ส่วน [Enterprise API](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks) ของ Google เองยังเป็น Preview ต้องมีไลเซนส์ Enterprise ในโปรเจกต์ Google Cloud และไม่มี Video Overviews แชต หรือ Deep Research (ข้อมูล ณ พฤศจิกายน 2026) ### บัญชี Google ฟรีใช้ได้ไหม? ผ่าน useapi.net ได้ ใน Flow และ Notebook เครดิต Flow 50 เครดิตต่อวันของบัญชีฟรีสร้าง Veo 3.1 Fast ได้ 2 คลิป Lite 5 คลิป หรือวิดีโอ Omni 1.2 Flash 720p ยาว 10 วินาที 1 คลิป และภาพ Nano Banana ไม่ใช้เครดิต Notebook เริ่ม Audio Overviews ได้ราว 2 รายการต่อรอบ 5 ชั่วโมง ส่วน Gemini API ไม่มีแบบฟรีสำหรับ Omni 1.2 Flash หรือ Nano Banana Pro (ข้อมูล ณ พฤศจิกายน 2026) ข้อยกเว้นคือ Vids บัญชีฟรีที่เราทดสอบไม่มีวินาทีวิดีโอเลย ### แหล่งข้อมูล - Google, [แพ็กเกจ Google AI](https://gemini.google/subscriptions/) และ[แพ็กเกจ Developer](https://gemini.google/subscriptions/?plans=developer) อ่านเมื่อ 7 พฤศจิกายน 2026 - Google, [แพ็กเกจ Google Developer Program](https://developers.google.com/program/plans-and-pricing) (เครดิต Google Cloud ของแต่ละแพ็กเกจ) และ [New developer tools for Google AI Pro and Ultra subscribers](https://blog.google/innovation-and-ai/technology/developers-tools/gdp-premium-ai-pro-ultra/) 27 มกราคม 2026 - Google One Help สิทธิ์ Flow Music ของ [Google AI Plus](https://support.google.com/googleone/answer/16882689?hl=th), [Google AI Pro](https://support.google.com/googleone/answer/14534406?hl=th) และ [Google AI Ultra](https://support.google.com/googleone/answer/16286513?hl=th) อ่านเมื่อ 7 พฤศจิกายน 2026 - Google, [ราคา Gemini API](https://ai.google.dev/gemini-api/docs/pricing) (Omni 1.2 Flash, Nano Banana, Lyria 3.5) อ่านเมื่อ 7 พฤศจิกายน 2026 - Google Cloud, [ราคา Agent Platform](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing) (Veo 3.1) อ่านเมื่อ 7 พฤศจิกายน 2026 - Google, [เครดิต Flow](https://support.google.com/flow/answer/16526234?hl=th), [Gemini ใน Google Vids](https://support.google.com/docs/answer/15609411?hl=th) และ[ลิมิตการใช้งาน Gemini Notebook](https://support.google.com/gemininotebook/answer/17670842?hl=th) อ่านเมื่อ 7 พฤศจิกายน 2026 - Google Cloud, [Gemini Notebook Enterprise API](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks) อ่านเมื่อ 7 พฤศจิกายน 2026 - ตารางราคาของ useapi.net: [Google Flow API](/docs/api-google-flow-v1#pricing), [Google Vids API](/docs/api-google-vids-v1#pricing), [Gemini Notebook API](/docs/api-gemini-notebook-v1#pricing) และ [Flow Music API](/docs/api-flowmusic-v1#pricing) ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-ai-subscription-api-vi === Document URL: https://useapi.net/docs/articles/google-ai-subscription-api-vi --- layout: default title: "Dùng gói Google AI qua API được không? Plus, Pro và Ultra cho bạn những gì" seo_title: "Google AI Pro và Ultra qua API: gói của bạn làm được gì" description: "Dùng Google AI Plus, Pro hay Ultra qua API với useapi.net: mỗi tháng gói Ultra tạo lượng video và bài hát trị giá $3.919 theo giá API của Google." keywords: [Google AI Pro API, Google AI Ultra API, Google AI Plus API, gói Google AI Pro có API không, Google AI Ultra có Gemini API không, dùng gói Google AI qua API, API Google AI Pro, Google AI subscription API, Google AI Ultra Gemini API, Gemini API, Gemini subscription API, Google One AI API, credit Google Flow, Flow credits API, Google Flow API, Google Vids API, Gemini Notebook API, NotebookLM API, Google Flow Music API, Lyria 3.5 API, Veo 3.1 API, Omni 1.2 Flash API, Nano Banana API, tạo video AI bằng API, giá Google AI Ultra, Google Cloud credits, Google Developer Program] parent: Articles nav_exclude: true lang: vi translation_key: google-ai-subscription date: 2026-11-07 last_modified: 2026-11-07 nav_order: 910 repo: https://github.com/useapi/google-flow-api --- ## Dùng gói Google AI qua API được không? Plus, Pro và Ultra cho bạn những gì {: #can-you-use-your-google-ai-subscription-through-an-api-what-plus-pro-and-ultra-get-you .no_toc } 6 phút đọc • 7 tháng 11 năm 2026 useapi.net là API của bên thứ ba, không liên kết với Google và không được Google bảo trợ. ## Mục lục {: #table-of-contents .no_toc .text-delta } ### Câu trả lời ngắn gọn Có, qua useapi.net. [Gói Google AI](https://gemini.google/subscriptions/) của bạn (Plus, Pro hoặc Ultra) đi kèm hạn mức hằng tháng cho các công cụ sáng tạo của Google. useapi.net biến từng hạn mức thành một API: - [Google Flow API](/docs/api-google-flow-v1): video từ credit Flow, và ảnh không tốn credit nào - [Google Vids API](/docs/api-google-vids-v1): video, avatar biết nói và giọng nói từ số giây Vids - [Gemini Notebook API (NotebookLM API)](/docs/api-gemini-notebook-v1): podcast, slide và nghiên cứu từ hạn mức Notebook - [Flow Music API](/docs/api-flowmusic-v1): bài hát từ credit Flow Music đi kèm gói của bạn Với Ultra $199,99, lượng nội dung làm được trong một tháng trị giá khoảng $3.919 nếu tính theo API của chính Google (tính đến tháng 11/2026). Bản thân Gemini API không nằm trong gói. Google tính phí riêng, theo từng giây video và từng ảnh. Pro và Ultra kèm một khoản nhỏ [credit Google Cloud](https://developers.google.com/program/plans-and-pricing) mỗi tháng để dùng cho nó: $10 với Pro, $40 với Ultra $99,99 và $100 với Ultra $199,99. Ngay cả $100 cũng chỉ mua được khoảng 96 video Omni 1.2 Flash dài 15 giây ở đó. Giá trong bài là giá tại Mỹ của Google, tính bằng USD, còn ở Việt Nam Google thu phí bằng VND và giá có thể khác. ### Mọi thứ một gói làm được trong một tháng Tổng những gì một gói Google AI làm được qua useapi.net mỗi tháng, và cùng lượng đó sẽ tốn bao nhiêu trên API của chính Google (tính đến tháng 11/2026). | Một tháng | Ultra $199,99 | Ultra $99,99 | Pro $19,99 | Plus $4,99 | |---|---|---|---|---| | **Google Flow** (một quỹ credit chung, chọn 1 dòng) | 25.000 cr | 10.000 cr | 1.000 cr | 200 cr | | Video Veo 3.1 Fast (8 s, 1080p) | 2.500 | 1.000 | 50 | 10 | | hoặc Veo 3.1 Lite (8 s, 1080p) | 5.000 | 2.000 | 100 | 20 | | hoặc Omni 1.1 Flash (10 s, 1080p) | 1.666 | 666 | 66 | 13 | | hoặc Omni 1.2 Flash (10 s, 1080p, upscale 0 cr) | 833 | 333 | 33 | 6 | | hoặc Omni 1.2 Flash (15 s, 720p) | 416 | 166 | 16 | 3 | | hoặc upscale 4K (clip tối đa 10 s) | 500 | 200 | — | — | | **Google Flow, 0 credit** (ngoài quỹ credit) | | | | | | Video Veo 3.1 Lite (ưu tiên thấp, 8 s) | 1.000+/ngày | — | — | — | | Upscale video lên 1080p (clip tối đa 10 s) | miễn phí | miễn phí | miễn phí | miễn phí | | Ảnh Nano Banana (Pro, 2.1, 2 Lite, upscale) | ~500/ngày, 4K | kèm gói, 4K | kèm gói, 2K | kèm gói, 2K | | **Google Vids** (riêng, cộng thêm) | 10.000 s | 2.500 s | 500 s | 60 s | | Video Omni 1.2 Flash (15 s, 1080p) | 666 | 166 | 33 | 4 | | Video avatar biết nói (đến 30 s) | 500 | 125 | 25 | 6 | | Ảnh (cơ bản, ~1 MP) | 1.000 | 300 | 30 | đến 50 | | Giọng nói (30 giọng) | kèm gói | kèm gói | kèm gói | kèm gói | | **Flow Music** (riêng, cộng thêm) | 30.000 cr | 30.000 cr | 10.000 cr | 3.000 cr | | Bài Lyria 3.5 (nguyên bài) | 6.000 | 6.000 | 2.000 | 600 | | **Gemini Notebook** (riêng, cộng thêm) | | | | | | Podcast (mỗi khung 5 giờ) | 181 | ~45 | 9 | ~4 | | **Credit Google Cloud** (cho Gemini API) | $100 | $40 | $10 | — | | **Trị giá (API Google)** (video và bài hát) | **$3.919** | **$1.699** | **$259** | **$64** | - Credit Google Flow là một quỹ chung. Một gói làm được số video Veo 3.1 Fast, hoặc một trong các dòng "hoặc", hoặc kết hợp chúng, chứ không bao giờ làm được tất cả. Mọi thứ bên dưới quỹ là hạn mức riêng và được cộng thêm. - Flow upscale video lên 1080p miễn phí với clip tối đa 10 giây, và tính 1 credit cho mỗi giây vượt quá ([upscale video](/docs/api-google-flow-v1/post-google-flow-videos-upscale), [trang credit Flow của Google](https://support.google.com/flow/answer/16526234?hl=vi)). Vì vậy mọi dòng 1080p trong quỹ Flow đều tính clip từ 10 giây trở xuống. Upscale lên 4K tốn 50 credit từ quỹ và chỉ có ở Ultra. Trong Vids, 1080p tốn cùng số giây như 720p. - Dòng trị giá tính quỹ Flow theo Veo 3.1 Fast ở 1080p ($0,96 một video trên API của Google), video Vids ở 1080p ($1,56) và bài hát ở $0,08. Tức là gấp 13 đến 20 lần giá của mỗi gói. - Con số "1.000+/ngày" video Veo 3.1 Lite và "~500/ngày" ảnh là mức các tài khoản Ultra $199,99 dùng nhiều nhất của chúng tôi đạt được, không phải giới hạn Google công bố. Lite ưu tiên thấp chỉ chạy cho chủ của gói đó. - Số liệu Vids là con số của Google, và tài khoản Pro thử nghiệm của chúng tôi hiển thị đúng 25 video avatar. Google lưu ý rằng một số gói dùng chung một giới hạn cho avatar và clip video. Với Plus, ảnh và lồng tiếng dùng chung 50 credit mỗi tháng. Pro và Ultra ghi lồng tiếng là không giới hạn, nhưng tài khoản thử nghiệm của chúng tôi có bộ đếm 50 lượt mỗi tháng. Google không có API cho avatar biết nói. ### Mỗi gói làm được gì trong một tháng Mỗi gói Google AI làm được gì qua useapi.net, và một sản phẩm tốn bao nhiêu trên API của chính Google (tính đến tháng 11/2026). Mỗi video tốn một phần giá gói, tức giá gói chia cho số lượng gói làm được. | Nội dung | API Google | Ultra $199,99/th (25.000 cr, 10.000 s) | Ultra $99,99/th (10.000 cr, 2.500 s) | Pro $19,99/th (1.000 cr, 500 s) | Plus $4,99/th (200 cr, 60 s) | |---|---|---|---|---|---| | Omni 1.2 ở Flow (720p, 15 s) | [$1,04](https://ai.google.dev/gemini-api/docs/pricing) ($0,07/s) | $0,48 / 60 cr (416 video/th) | $0,60 / 60 cr (166 video/th) | $1,20 / 60 cr (16 video/th) | $1,50 / 60 cr (3 video/th) | | Omni 1.1 ở Flow (720p, 10 s) | [$1,01](https://ai.google.dev/gemini-api/docs/pricing) ($0,10/s) | $0,12 / 15 cr (1.666 video/th) | $0,15 / 15 cr (666 video/th) | $0,30 / 15 cr (66 video/th) | $0,37 / 15 cr (13 video/th) | | Omni 1.2 ở Vids (720p, 15 s) | [$1,04](https://ai.google.dev/gemini-api/docs/pricing) ($0,07/s) | $0,30 / 15 s (666 video/th) | $0,60 / 15 s (166 video/th) | $0,60 / 15 s (33 video/th) | $1,25 / 15 s (4 video/th) | | Omni 1.2 ở Vids (1080p, 15 s) | [$1,56](https://ai.google.dev/gemini-api/docs/pricing) ($0,104/s) | $0,30 / 15 s (666 video/th) | $0,60 / 15 s (166 video/th) | $0,60 / 15 s (33 video/th) | $1,25 / 15 s (4 video/th) | | Veo 3.1 Fast (Flow, 720p, 8 s) | [$0,80](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing) ($0,10/s) | $0,08 / 10 cr (2.500 video/th) | $0,10 / 10 cr (1.000 video/th) | $0,40 / 20 cr (50 video/th) | $0,50 / 20 cr (10 video/th) | | Nano Banana Pro (ảnh Flow) | [$0,134](https://ai.google.dev/gemini-api/docs/pricing) (mỗi ảnh) | $0 / 0 cr (~500/ngày) | $0 / 0 cr (kèm gói) | $0 / 0 cr (kèm gói) | $0 / 0 cr (kèm gói) | | Bài Lyria 3.5 (Flow Music) | [$0,08](https://ai.google.dev/gemini-api/docs/pricing) (mỗi bài) | $0,033 / 5 cr (6.000 bài/th) | $0,017 / 5 cr (6.000 bài/th) | $0,010 / 5 cr (2.000 bài/th) | $0,008 / 5 cr (600 bài/th) | | Notebook (podcast/5 giờ) | [Enterprise](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks) (Preview) | 181 | ~45 | 9 | ~4 | | Credit Cloud (cho Gemini API) | — | $100/th | $40/th | $10/th | — | - Dòng Notebook đếm số Audio Overview (podcast) mà một khung 5 giờ đầy đủ có thể bắt đầu, theo ước tính của chính Google. Plus và Ultra $99,99 được quy đổi theo [hệ số Google công bố](https://support.google.com/gemininotebook/answer/17670842?hl=vi). - Mỗi video và ảnh Flow cần giải một captcha, việc này API tự làm. Tài khoản đầu tiên của bạn được 300 lần miễn phí, sau đó [dịch vụ giải captcha](/docs/start-here/setup-google-flow#configure-captcha-providers) của riêng bạn tốn khoảng $0,80 đến $3,00 cho mỗi 1.000 lần. - Giá gói là giá tại Mỹ của Google. Bảng giá [Google Flow](/docs/api-google-flow-v1#pricing) và [Google Vids](/docs/api-google-vids-v1#pricing) liệt kê mọi model trên mọi gói. ### Google Flow: Veo 3.1, Omni Flash và Nano Banana [Google Flow API](/docs/api-google-flow-v1) tạo video Veo 3.1 Fast, Quality và Lite cùng video Omni 1.2 Flash và Omni 1.1 Flash từ credit Flow của gói. API cũng tạo ảnh Nano Banana Pro, 2.1 và 2 Lite không tốn credit, và upscale cả video lẫn ảnh. Phía Google, Veo 3.1 chạy trên [Agent Platform](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing) với giá $0,10 mỗi giây cho Fast ở 720p và $0,12 ở 1080p. Omni 1.2 Flash và Nano Banana chạy trên [Gemini API](https://ai.google.dev/gemini-api/docs/pricing). Cả hai đều cần một dự án Google Cloud có bật thanh toán. Bài [giá Veo 3.1 API](/docs/articles/veo-3-1-api-pricing) so sánh mọi mức giá Veo. ### Google Vids: Omni 1.2 Flash và avatar biết nói [Google Vids API](/docs/api-google-vids-v1) tạo video Omni 1.2 Flash dài 3 đến 15 giây có âm thanh, ở 720p hoặc 1080p với cùng số giây, và có thể kéo dài, chỉnh sửa, upscale chúng. API cũng tạo [video avatar biết nói](/docs/api-google-vids-v1/post-google-vids-videos-avatar) dài tới 30 giây, [giọng nói](/docs/api-google-vids-v1/post-google-vids-speech) với 30 giọng và ảnh cơ bản. Những thứ này không tốn giây video. Google không công bố API cho Vids. Cùng model đó trên Gemini API có giá $0,07 mỗi giây ở 720p và $0,104 ở 1080p. Vids không yêu cầu captcha. Số giây Vids được dùng chung cho mọi người trong gói gia đình Google. [Hướng dẫn Omni 1.2 Flash](/docs/articles/gemini-omni-1-2-flash-api) chạy một cảnh trong Flow và một cảnh trong Vids. ### Gemini Notebook (NotebookLM): podcast, video và Deep Research [Gemini Notebook API (NotebookLM API)](/docs/api-gemini-notebook-v1) biến trang web, PDF và video YouTube thành Audio Overview (podcast), Video Overview, slide, infographic, báo cáo và câu đố, đồng thời chạy chat có trích dẫn nguồn và Deep Research. Video Overview dạng Cinematic cần Pro hoặc Ultra. Notebook không dùng credit. Mỗi tác vụ dùng một phần hạn mức của tài khoản, và hạn mức này nạp lại mỗi 5 giờ cho tới giới hạn hằng tuần. Plus được gấp 2 lần giới hạn miễn phí, Pro gấp 4 lần, còn Ultra gấp 5 hoặc 20 lần của Pro. [Gemini Notebook Enterprise API](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks) của chính Google đang ở giai đoạn Preview, cần giấy phép Enterprise trong một dự án Google Cloud và chỉ hỗ trợ notebook, nguồn, chia sẻ và Audio Overview. ### Google Flow Music: bài hát Lyria 3.5 Mọi gói Google AI trả phí cũng kèm credit [Google Flow Music](https://www.flowmusic.app), tách biệt với credit Flow. Plus được [3.000 credit mỗi tháng](https://support.google.com/googleone/answer/16882689?hl=vi), Pro [10.000](https://support.google.com/googleone/answer/14534406?hl=vi) và Ultra [30.000](https://support.google.com/googleone/answer/16286513?hl=vi). Bạn chỉ cần nhận một lần: đăng nhập flowmusic.app bằng cùng tài khoản Google và cho phép Flow Music xem gói thành viên Google One của bạn. [Flow Music API](/docs/api-flowmusic-v1) tạo bài hát hoàn chỉnh có lời hoặc không lời trên Lyria 3.5 và Lyria 3 Pro, với 5 credit một bài. API cũng tạo bản cover, remix, kéo dài bài hát và tách bài thành bốn stem. Google chỉ cung cấp Flow Music dưới dạng website. Trên Gemini API, một bài Lyria 3.5 có giá $0,08 và bài đã tạo không chỉnh sửa được ở đó. ### Một tài khoản Google, bốn hạn mức Credit Flow, giây Vids, hạn mức Notebook và credit Flow Music được tính riêng, không cái nào trừ vào cái nào. Kết nối cùng một tài khoản Google với cả bốn API là dùng được mọi hạn mức: video Omni 1.2 Flash trong Flow và trong Vids cộng dồn, podcast và Deep Research từ Notebook, và bài hát từ Flow Music. Mỗi API có trang thiết lập riêng ([Flow](/docs/start-here/setup-google-flow), [Vids](/docs/start-here/setup-google-vids), [Notebook](/docs/start-here/setup-gemini-notebook), [Flow Music](/docs/start-here/setup-flowmusic)), và một gói đăng ký useapi.net dùng được cho cả bốn. ### Nên chọn gói nào - Ultra $199,99 là gói duy nhất có [Veo 3.1 Lite ưu tiên thấp](/docs/api-google-flow-v1/post-google-flow-videos), không tốn credit nào. Google không công bố giới hạn, và các tài khoản dùng nhiều nhất của chúng tôi tạo hơn 1.000 video như vậy mỗi ngày, ngoài 25.000 credit mỗi tháng. Gói này cũng có giá mỗi video thấp nhất: Veo 3.1 Fast ở $0,08, và một video Omni 1.2 Flash 15 giây ở $0,30 trong Vids hoặc $0,48 trong Flow. - Ultra $99,99 rẻ bằng một nửa nhưng không có Veo 3.1 Lite ưu tiên thấp. Gói làm được 1.000 video Veo 3.1 Fast giá $0,10 và 166 video Vids giá $0,60, cùng 6.000 bài hát như gói trên. - Pro là gói nên dùng để bắt đầu. Gói làm được 50 video Veo 3.1 Fast mỗi tháng giá $0,40, bằng nửa giá của Google, 33 video Vids 15 giây giá $0,60 và 2.000 bài Lyria 3.5. Với Pro, hãy tạo Omni 1.2 Flash trong Vids, vì trong Flow nó tốn $1,20, đắt hơn mức $1,04 của Gemini API. - Plus có thể đắt hơn API của Google nếu tính theo từng video. Một video Omni 1.2 Flash 720p dài 15 giây tốn $1,50 trong Flow và $1,25 trong Vids, so với $1,04. Veo 3.1 Fast vẫn rẻ hơn, $0,50 so với $0,80, nhưng chỉ có 10 video mỗi tháng. Plus hợp với bài hát (600 bài mỗi tháng), ảnh Nano Banana và Gemini Notebook hơn là video. ## Câu hỏi thường gặp ### Google AI Ultra có bao gồm Gemini API không? Qua useapi.net, Ultra $199,99 làm được 2.500 video Veo 3.1 Fast, 666 video Omni 1.2 Flash trong Vids và 6.000 bài hát mỗi tháng, trị giá khoảng $3.919 trên API của Google (tính đến tháng 11/2026). Bản thân gói không kèm lượt dùng Gemini API nào. Gói có [credit Google Cloud](https://developers.google.com/program/plans-and-pricing) $100 mỗi tháng ($40 với Ultra $99,99), kích hoạt trong Google Developer Program. Số đó chỉ mua được khoảng 96 video Omni 1.2 Flash dài 15 giây. ### Gói Google AI Pro có dùng qua API được không? Qua useapi.net thì được: 1.000 credit Flow, 500 giây Vids và 10.000 credit Flow Music của Pro chạy qua REST. Chúng làm được 50 video Veo 3.1 Fast mỗi tháng giá $0,40 mỗi video, so với $0,80 trên Agent Platform của Google. Ngoài ra còn 33 video Omni 1.2 Flash 15 giây trong Vids giá $0,60, so với $1,04 trên Gemini API, và 2.000 bài Lyria 3.5, trị giá $160 ở đó (tính đến tháng 11/2026). Ảnh Nano Banana không tốn credit. ### Google AI Ultra tạo được bao nhiêu video Veo 3.1? Qua useapi.net, Ultra $199,99 tạo 2.500 video Veo 3.1 Fast dài 8 giây mỗi tháng, giá $0,08 mỗi video, so với $0,80 trên [Agent Platform](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing) của Google, còn Ultra $99,99 tạo 1.000 video giá $0,10 (tính đến tháng 11/2026). Ultra $199,99 còn chạy Veo 3.1 Lite ưu tiên thấp không tốn credit, khoảng 1.000 video trở lên mỗi ngày trên các tài khoản dùng nhiều nhất của chúng tôi. ### NotebookLM có API không? Qua useapi.net thì có, cho tài khoản Google thông thường: Gemini Notebook API (NotebookLM API) chạy Audio Overview, Video Overview, slide, chat có trích dẫn nguồn và Deep Research trên gói Google AI của bạn, kể cả gói miễn phí. [Enterprise API](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks) của chính Google đang ở giai đoạn Preview, cần giấy phép Enterprise trong một dự án Google Cloud và không có Video Overview, chat hay Deep Research (tính đến tháng 11/2026). ### Tài khoản Google miễn phí có dùng được không? Qua useapi.net thì được, với Flow và Notebook. 50 credit Flow mỗi ngày của tài khoản miễn phí tạo được 2 video Veo 3.1 Fast, 5 video Lite hoặc một video Omni 1.2 Flash 720p dài 10 giây, và ảnh Nano Banana không tốn credit. Notebook bắt đầu được khoảng 2 Audio Overview mỗi khung 5 giờ. Gemini API không có gói miễn phí cho Omni 1.2 Flash hay Nano Banana Pro (tính đến tháng 11/2026). Vids là ngoại lệ, vì các tài khoản miễn phí chúng tôi thử không có giây video nào. ### Nguồn - Google, [Các gói Google AI](https://gemini.google/subscriptions/) và [gói Developer](https://gemini.google/subscriptions/?plans=developer), đọc ngày 7/11/2026 - Google, [Các gói Google Developer Program](https://developers.google.com/program/plans-and-pricing) (credit Google Cloud theo từng gói) và [New developer tools for Google AI Pro and Ultra subscribers](https://blog.google/innovation-and-ai/technology/developers-tools/gdp-premium-ai-pro-ultra/), ngày 27/1/2026 - Google One Help, quyền lợi Flow Music của [Google AI Plus](https://support.google.com/googleone/answer/16882689?hl=vi), [Google AI Pro](https://support.google.com/googleone/answer/14534406?hl=vi) và [Google AI Ultra](https://support.google.com/googleone/answer/16286513?hl=vi), đọc ngày 7/11/2026 - Google, [Bảng giá Gemini API](https://ai.google.dev/gemini-api/docs/pricing) (Omni 1.2 Flash, Nano Banana, Lyria 3.5), đọc ngày 7/11/2026 - Google Cloud, [Bảng giá Agent Platform](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing) (Veo 3.1), đọc ngày 7/11/2026 - Google, [Credit Flow](https://support.google.com/flow/answer/16526234?hl=vi), [Gemini trong Google Vids](https://support.google.com/docs/answer/15609411?hl=vi) và [Giới hạn sử dụng Gemini Notebook](https://support.google.com/gemininotebook/answer/17670842?hl=vi), đọc ngày 7/11/2026 - Google Cloud, [Gemini Notebook Enterprise API](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks), đọc ngày 7/11/2026 - Bảng giá của useapi.net: [Google Flow API](/docs/api-google-flow-v1#pricing), [Google Vids API](/docs/api-google-vids-v1#pricing), [Gemini Notebook API](/docs/api-gemini-notebook-v1#pricing) và [Flow Music API](/docs/api-flowmusic-v1#pricing) ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-ai-subscription-api-zh === Document URL: https://useapi.net/docs/articles/google-ai-subscription-api-zh --- layout: default title: "Google AI 订阅能用 API 调用吗?Plus、Pro 和 Ultra 套餐各能得到什么" seo_title: "Google AI Pro 和 Ultra 订阅 API 调用:每个套餐每月能生成多少" description: "通过 useapi.net 用 API 调用 Google AI Plus、Pro、Ultra 订阅:Ultra 每月的视频和歌曲按 Google API 价格约值 $3,919,图片另算。" keywords: [Google AI 订阅 API, Google AI Pro API, Google AI Ultra API, Google AI Plus API, Google AI Ultra 包含 Gemini API 吗, Google AI Pro 能用 API 吗, Google AI Pro API 调用, Gemini 会员 API, Gemini Pro 会员 API, Gemini Ultra 会员 API, Google One AI 会员 API, Flow 积分 API, Google Vids API, Gemini Notebook API, NotebookLM API, Google Flow Music API, Lyria 3.5 API, Flow Music 积分, Veo 3.1 API, Omni 1.2 Flash API, Nano Banana API, Google Cloud 赠金, Google Developer Program, Google Flow API, Google AI subscription API, does Google AI Ultra include API access] parent: Articles nav_exclude: true lang: zh-CN translation_key: google-ai-subscription date: 2026-11-07 last_modified: 2026-11-07 nav_order: 910 repo: https://github.com/useapi/google-flow-api --- ## Google AI 订阅能用 API 调用吗?Plus、Pro 和 Ultra 套餐各能得到什么 {: .no_toc #can-you-use-your-google-ai-subscription-through-an-api-what-plus-pro-and-ultra-get-you } 6 分钟阅读 • 2026 年 11 月 7 日 useapi.net 是第三方 API,与 Google 无关联,也未获得 Google 的认可。 ## 目录 {: .no_toc .text-delta #table-of-contents } ### 简短回答 可以,通过 useapi.net。你的 [Google AI 套餐](https://gemini.google/subscriptions/)(Plus、Pro 或 Ultra)每月包含 Google 各个创作工具的额度,useapi.net 把每一份额度都变成 API: - [Google Flow API](/docs/api-google-flow-v1):用 Flow 积分生成视频,生成图片不耗积分 - [Google Vids API](/docs/api-google-vids-v1):用 Vids 视频秒数生成视频、数字人口播视频和语音 - [Gemini Notebook API(NotebookLM API)](/docs/api-gemini-notebook-v1):用 Notebook 用量生成播客、幻灯片和研究报告 - [Flow Music API](/docs/api-flowmusic-v1):用套餐附带的 Flow Music 积分生成歌曲 在 Ultra $199.99 套餐上,一个月的产出按 Google 自己的 API 价格约值 $3,919(截至 2026 年 11 月)。 Gemini API 本身不包含在套餐里,Google 另外按视频秒数和图片张数计费。Pro 和 Ultra 每月附带一小笔可用于它的 [Google Cloud 赠金](https://developers.google.com/program/plans-and-pricing):Pro $10,Ultra $99.99 为 $40,Ultra $199.99 为 $100。即使是 $100,在那里也只够生成约 96 条 15 秒的 Omni 1.2 Flash 视频。 本文价格均为 Google 美国区的美元价格:Google AI 套餐不在中国大陆销售,在其他国家和地区 Google 按当地货币收费,价格可能不同。 ### 一个套餐每月能生成的全部内容 一个 Google AI 套餐每月通过 useapi.net 能生成的全部内容,以及同样的产出在 Google 自己的 API 上要花多少钱(截至 2026 年 11 月)。 | 每月 | Ultra $199.99 | Ultra $99.99 | Pro $19.99 | Plus $4.99 | |---|---|---|---|---| | **Google Flow** (同一积分池,任选一行) | 25,000 积分 | 10,000 积分 | 1,000 积分 | 200 积分 | | Veo 3.1 Fast 视频 (8 秒,1080p) | 2,500 | 1,000 | 50 | 10 | | 或 Veo 3.1 Lite 视频 (8 秒,1080p) | 5,000 | 2,000 | 100 | 20 | | 或 Omni 1.1 Flash 视频 (10 秒,1080p) | 1,666 | 666 | 66 | 13 | | 或 Omni 1.2 Flash 视频 (10 秒,1080p,免费放大) | 833 | 333 | 33 | 6 | | 或 Omni 1.2 Flash 视频 (15 秒,720p) | 416 | 166 | 16 | 3 | | 或 4K 视频放大 (10 秒以内的视频) | 500 | 200 | — | — | | **Google Flow,不耗积分** (积分池之外另算) | | | | | | Veo 3.1 Lite 视频 (低优先级,8 秒) | 每天 1,000+ | — | — | — | | 视频放大到 1080p (10 秒以内的视频) | 免费 | 免费 | 免费 | 免费 | | Nano Banana 图片 (Pro、2.1、2 Lite,已放大) | 每天约 500,4K | 包含,4K | 包含,2K | 包含,2K | | **Google Vids** (独立额度,另算) | 10,000 秒 | 2,500 秒 | 500 秒 | 60 秒 | | Omni 1.2 Flash 视频 (15 秒,1080p) | 666 | 166 | 33 | 4 | | 数字人口播视频 (最长 30 秒) | 500 | 125 | 25 | 6 | | 图片 (基础画质,约 1 MP) | 1,000 | 300 | 30 | 最多 50 | | 语音 (30 种音色) | 包含 | 包含 | 包含 | 包含 | | **Flow Music** (独立积分,另算) | 30,000 积分 | 30,000 积分 | 10,000 积分 | 3,000 积分 | | Lyria 3.5 歌曲 (完整歌曲) | 6,000 | 6,000 | 2,000 | 600 | | **Gemini Notebook** (独立限额,另算) | | | | | | 播客 (每个 5 小时窗口) | 181 | ~45 | 9 | ~4 | | **Google Cloud 赠金** (用于 Gemini API) | $100 | $40 | $10 | — | | **按 Google API 价格折算** (视频和歌曲) | **$3,919** | **$1,699** | **$259** | **$64** | - Google Flow 积分是同一个池子。一个套餐可以生成 Veo 3.1 Fast 视频,或其中一行“或”,或几行混用,但不能全部都要。积分池下方的各项都是独立额度,另外累加。 - Flow 把 10 秒以内的视频免费放大到 1080p,超过 10 秒的部分每秒收 1 积分([视频放大](/docs/api-google-flow-v1/post-google-flow-videos-upscale),[Google 的 Flow 积分页面](https://support.google.com/flow/answer/16526234?hl=zh-Hans))。所以积分池里每一行 1080p 都按 10 秒以内的视频计算。放大到 4K 从积分池扣 50 积分,仅限 Ultra。在 Vids 中,1080p 与 720p 消耗相同的秒数。 - 折算一行把 Flow 积分池按 1080p 的 Veo 3.1 Fast 计算(Google API 上每条 $0.96),Vids 视频按 1080p 计算($1.56),歌曲按每首 $0.08。合计是各套餐价格的 13 到 20 倍。 - “每天 1,000+” 条 Veo 3.1 Lite 视频和“每天约 500”张图片,是我们最忙的 Ultra $199.99 账号实际达到的数量,不是 Google 公布的限额。低优先级 Lite 只对该套餐的所有者开放。 - Vids 的数量来自 Google 公布的数字,我们的 Pro 测试账号显示的正好是 25 条数字人视频。Google 注明部分套餐的数字人和视频片段共用一个限额。在 Plus 上,图片和配音共用每月 50 个积分。Pro 和 Ultra 标注配音不限量,但我们的测试账号显示每月 50 次的计数器。Google 没有数字人视频的 API。 ### 各套餐每月能生成什么 各个 Google AI 套餐通过 useapi.net 能生成什么,以及单条内容在 Google 自己的 API 上的价格(截至 2026 年 11 月)。一条视频的成本就是它占套餐费的份额:套餐价格除以套餐能生成的数量。 | 生成内容 | 官方 API | Ultra $199.99/月 (25,000 积分,10,000 秒) | Ultra $99.99/月 (10,000 积分,2,500 秒) | Pro $19.99/月 (1,000 积分,500 秒) | Plus $4.99/月 (200 积分,60 秒) | |---|---|---|---|---|---| | Flow 中的 Omni 1.2 (720p,15 秒) | [$1.04](https://ai.google.dev/gemini-api/docs/pricing) ($0.07/秒) | $0.48/60 积分 (每月 416 条) | $0.60/60 积分 (每月 166 条) | $1.20/60 积分 (每月 16 条) | $1.50/60 积分 (每月 3 条) | | Flow 中的 Omni 1.1 (720p,10 秒) | [$1.01](https://ai.google.dev/gemini-api/docs/pricing) ($0.10/秒) | $0.12/15 积分 (每月 1,666 条) | $0.15/15 积分 (每月 666 条) | $0.30/15 积分 (每月 66 条) | $0.37/15 积分 (每月 13 条) | | Vids 中的 Omni 1.2 (720p,15 秒) | [$1.04](https://ai.google.dev/gemini-api/docs/pricing) ($0.07/秒) | $0.30 / 15 秒 (每月 666 条) | $0.60 / 15 秒 (每月 166 条) | $0.60 / 15 秒 (每月 33 条) | $1.25 / 15 秒 (每月 4 条) | | Vids 中的 Omni 1.2 (1080p,15 秒) | [$1.56](https://ai.google.dev/gemini-api/docs/pricing) ($0.104/秒) | $0.30 / 15 秒 (每月 666 条) | $0.60 / 15 秒 (每月 166 条) | $0.60 / 15 秒 (每月 33 条) | $1.25 / 15 秒 (每月 4 条) | | Veo 3.1 Fast (Flow,720p,8 秒) | [$0.80](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing) ($0.10/秒) | $0.08/10 积分 (每月 2,500 条) | $0.10/10 积分 (每月 1,000 条) | $0.40/20 积分 (每月 50 条) | $0.50/20 积分 (每月 10 条) | | Nano Banana Pro (Flow 图片) | [$0.134](https://ai.google.dev/gemini-api/docs/pricing) (每张) | $0/0 积分 (每天约 500 张) | $0/0 积分 (包含) | $0/0 积分 (包含) | $0/0 积分 (包含) | | Lyria 3.5 歌曲 (Flow Music) | [$0.08](https://ai.google.dev/gemini-api/docs/pricing) (每首) | $0.033/5 积分 (每月 6,000 首) | $0.017/5 积分 (每月 6,000 首) | $0.010/5 积分 (每月 2,000 首) | $0.008/5 积分 (每月 600 首) | | Notebook (每 5 小时播客数) | [Enterprise](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks) (预览版) | 181 | ~45 | 9 | ~4 | | Cloud 赠金 (用于 Gemini API) | — | $100/月 | $40/月 | $10/月 | — | - Notebook 一行统计的是一个完整的 5 小时窗口能启动的 Audio Overview(播客)数量,依据 Google 自己的估算。Plus 和 Ultra $99.99 按 Google [公布的倍数](https://support.google.com/gemininotebook/answer/17670842?hl=zh-Hans)换算。 - Flow 每次生成视频和图片都要过验证码,由 API 自动处理。你的第一个账号有 300 次免费,之后用你自己的[打码服务](/docs/start-here/setup-google-flow#configure-captcha-providers),每 1,000 次约 $0.80 到 $3.00。 - 套餐价格为 Google 美国区价格。[Google Flow](/docs/api-google-flow-v1#pricing) 和 [Google Vids](/docs/api-google-vids-v1#pricing) 的价格表列出了每个套餐上的全部模型。 ### Google Flow:Veo 3.1、Omni Flash 和 Nano Banana [Google Flow API](/docs/api-google-flow-v1) 用套餐的 Flow 积分生成 Veo 3.1 Fast、Quality 和 Lite 视频,以及 Omni 1.2 Flash 和 Omni 1.1 Flash 视频。它还能生成 Nano Banana Pro、2.1 和 2 Lite 图片(不耗积分),并放大视频和图片。 在 Google 那边,Veo 3.1 运行在 [Agent Platform](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing) 上,Fast 在 720p 每秒 $0.10,在 1080p 每秒 $0.12。Omni 1.2 Flash 和 Nano Banana 运行在 [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) 上。两者都需要开通结算的 Google Cloud 项目。各种 Veo 价格的对比见 [Veo 3.1 API 价格(英文)](/docs/articles/veo-3-1-api-pricing)。 ### Google Vids:Omni 1.2 Flash 和数字人 [Google Vids API](/docs/api-google-vids-v1) 生成 3 到 15 秒、带声音的 Omni 1.2 Flash 视频,720p 和 1080p 消耗相同的秒数,还能延长、编辑和放大视频。它还能生成最长 30 秒的[数字人口播视频](/docs/api-google-vids-v1/post-google-vids-videos-avatar)、30 种音色的[语音](/docs/api-google-vids-v1/post-google-vids-speech)和基础图片。这些都不消耗视频秒数。 Google 没有公开 Vids API。同一个模型在 Gemini API 上 720p 每秒 $0.07,1080p 每秒 $0.104。Vids 不需要验证码。它的秒数由 Google 家庭方案的所有成员共享。[Gemini Omni 1.2 Flash API 中文教程](/docs/articles/gemini-omni-1-2-flash-api-zh)在 Flow 和 Vids 中各做了一个场景。 ### Gemini Notebook(NotebookLM):播客、视频和 Deep Research [Gemini Notebook API(NotebookLM API)](/docs/api-gemini-notebook-v1) 把网页、PDF 和 YouTube 视频变成 Audio Overview(播客)、Video Overview、幻灯片、信息图、报告和测验,还能进行带引用的问答和 Deep Research。Cinematic Video Overview 需要 Pro 或 Ultra。 Notebook 没有积分。每个任务用掉账号的一部分用量,用量每 5 小时刷新一次,另有每周上限:Plus 是免费额度的 2 倍,Pro 是 4 倍,Ultra 是 Pro 的 5 倍或 20 倍。Google 自己的 [Gemini Notebook Enterprise API](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks) 还在预览阶段,需要在 Google Cloud 项目中购买 Enterprise 许可证,只覆盖笔记本、来源、共享和 Audio Overview。 ### Google Flow Music:Lyria 3.5 歌曲 每个付费 Google AI 套餐还附带 [Google Flow Music](https://www.flowmusic.app) 积分,与 Flow 积分分开。Plus [每月 3,000 积分](https://support.google.com/googleone/answer/16882689?hl=zh-Hans),Pro [10,000](https://support.google.com/googleone/answer/14534406?hl=zh-Hans),Ultra [30,000](https://support.google.com/googleone/answer/16286513?hl=zh-Hans)。只需领取一次:用同一个 Google 账号登录 flowmusic.app,并允许 Flow Music 查看你的 Google One 会员资格。 [Flow Music API](/docs/api-flowmusic-v1) 用 Lyria 3.5 和 Lyria 3 Pro 生成带人声或纯音乐的完整歌曲,每首 5 积分。它还能翻唱、混音和延长歌曲,并把歌曲拆成四条分轨。Google 只以网站形式提供 Flow Music。在 Gemini API 上,一首 Lyria 3.5 歌曲 $0.08,生成的歌曲也无法在那里编辑。 ### 一个 Google 账号,四份额度 Flow 积分、Vids 秒数、Notebook 用量和 Flow Music 积分分开计算,互不占用。把同一个 Google 账号绑定到四套 API,每份额度都能用上:Flow 和 Vids 里的 Omni 1.2 Flash 视频可以叠加,再加上 Notebook 的播客和 Deep Research,以及 Flow Music 的歌曲。每套 API 有自己的设置页面([Flow](/docs/start-here/setup-google-flow)、[Vids](/docs/start-here/setup-google-vids)、[Notebook](/docs/start-here/setup-gemini-notebook)、[Flow Music](/docs/start-here/setup-flowmusic)),一个 useapi.net 订阅就覆盖全部四套。 ### 选哪个套餐 - Ultra $199.99 是唯一提供[低优先级 Veo 3.1 Lite](/docs/api-google-flow-v1/post-google-flow-videos) 的套餐,这种视频完全不耗积分。Google 没有公布上限,我们最忙的账号每天能生成 1,000+ 条,另外还有每月 25,000 积分。它的单条视频价格也最低:Veo 3.1 Fast $0.08,15 秒 Omni 1.2 Flash 视频在 Vids 中 $0.30、在 Flow 中 $0.48。 - Ultra $99.99 价格减半,但没有低优先级 Veo 3.1 Lite。它每月生成 1,000 条 Veo 3.1 Fast 视频(每条 $0.10)和 166 条 Vids 视频(每条 $0.60),歌曲同样是 6,000 首。 - Pro 适合入门。它每月生成 50 条 Veo 3.1 Fast 视频,每条 $0.40,是 Google 价格的一半,还有 33 条 15 秒 Vids 视频(每条 $0.60)和 2,000 首 Lyria 3.5 歌曲。在 Pro 上,Omni 1.2 Flash 要在 Vids 里生成:在 Flow 里每条 $1.20,比 Gemini API 的 $1.04 还贵。 - Plus 的单条视频可能比 Google API 更贵。一条 720p 15 秒 Omni 1.2 Flash 视频在 Flow 中 $1.50、在 Vids 中 $1.25,而 Gemini API 为 $1.04。Veo 3.1 Fast 仍然更便宜,$0.50 对 $0.80,但每月只有 10 条。比起视频,Plus 更适合生成歌曲(每月 600 首)、Nano Banana 图片和使用 Gemini Notebook。 ## 常见问题 ### Google AI Ultra 包含 Gemini API 吗? 通过 useapi.net,Ultra $199.99 每月能生成 2,500 条 Veo 3.1 Fast 视频、666 条 Vids 中的 Omni 1.2 Flash 视频和 6,000 首歌曲,按 Google API 价格约值 $3,919(截至 2026 年 11 月)。套餐本身不包含 Gemini API 用量。它每月附带 $100 的 [Google Cloud 赠金](https://developers.google.com/program/plans-and-pricing)(Ultra $99.99 为 $40),需要在 Google Developer Program 中激活。这笔钱约够生成 96 条 15 秒的 Omni 1.2 Flash 视频。 ### Google AI Pro 会员能用 API 调用吗? 通过 useapi.net 可以:Pro 的 1,000 个 Flow 积分、500 秒 Vids 额度和 10,000 个 Flow Music 积分都能通过 REST 调用。每月可生成 50 条 Veo 3.1 Fast 视频,每条 $0.40,Google 的 Agent Platform 上为 $0.80。还能生成 33 条 15 秒的 Vids Omni 1.2 Flash 视频,每条 $0.60,Gemini API 上为 $1.04,以及 2,000 首 Lyria 3.5 歌曲,在 Gemini API 上值 $160(截至 2026 年 11 月)。Nano Banana 图片不耗积分。 ### Google AI Ultra 每月能生成多少条 Veo 3.1 视频? 通过 useapi.net,Ultra $199.99 每月生成 2,500 条 8 秒 Veo 3.1 Fast 视频,每条 $0.08,Google 的 [Agent Platform](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing) 上为 $0.80,Ultra $99.99 生成 1,000 条,每条 $0.10(截至 2026 年 11 月)。Ultra $199.99 还能以低优先级运行 Veo 3.1 Lite,不耗积分,我们最忙的账号每天约 1,000 条以上。 ### 有 NotebookLM API 吗? 通过 useapi.net 可以,普通 Google 账号就能用:Gemini Notebook API(NotebookLM API)在你的 Google AI 套餐上运行 Audio Overview、Video Overview、幻灯片、带引用的问答和 Deep Research,免费套餐也可以。Google 自己的 [Enterprise API](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks) 还在预览阶段,需要在 Google Cloud 项目中购买 Enterprise 许可证,也没有 Video Overview、问答和 Deep Research(截至 2026 年 11 月)。 ### 免费 Google 账号能用吗? 通过 useapi.net 可以,Flow 和 Notebook 都能用。免费账号每天 50 个 Flow 积分,可以生成 2 条 Veo 3.1 Fast 视频、5 条 Lite 视频或一条 10 秒 720p 的 Omni 1.2 Flash 视频,Nano Banana 图片不耗积分。Notebook 每个 5 小时窗口约能启动 2 个 Audio Overview。Gemini API 上的 Omni 1.2 Flash 和 Nano Banana Pro 没有免费层级(截至 2026 年 11 月)。Vids 是例外:我们测试的免费账号没有视频秒数。 ### 来源 - Google,[Google AI 套餐](https://gemini.google/subscriptions/)和[开发者套餐](https://gemini.google/subscriptions/?plans=developer),2026 年 11 月 7 日读取 - Google,[Google Developer Program 套餐](https://developers.google.com/program/plans-and-pricing)(各套餐的 Google Cloud 赠金)和 [New developer tools for Google AI Pro and Ultra subscribers](https://blog.google/innovation-and-ai/technology/developers-tools/gdp-premium-ai-pro-ultra/),2026 年 1 月 27 日 - Google One 帮助中心,[Google AI Plus](https://support.google.com/googleone/answer/16882689?hl=zh-Hans)、[Google AI Pro](https://support.google.com/googleone/answer/14534406?hl=zh-Hans) 和 [Google AI Ultra](https://support.google.com/googleone/answer/16286513?hl=zh-Hans) 的 Flow Music 权益,2026 年 11 月 7 日读取 - Google,[Gemini API 价格](https://ai.google.dev/gemini-api/docs/pricing)(Omni 1.2 Flash、Nano Banana、Lyria 3.5),2026 年 11 月 7 日读取 - Google Cloud,[Agent Platform 价格](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing)(Veo 3.1),2026 年 11 月 7 日读取 - Google,[Flow 积分](https://support.google.com/flow/answer/16526234?hl=zh-Hans)、[Gemini in Google Vids](https://support.google.com/docs/answer/15609411?hl=zh-Hans) 和 [Gemini Notebook 用量限制](https://support.google.com/gemininotebook/answer/17670842?hl=zh-Hans),2026 年 11 月 7 日读取 - Google Cloud,[Gemini Notebook Enterprise API](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks),2026 年 11 月 7 日读取 - useapi.net 价格表:[Google Flow API](/docs/api-google-flow-v1#pricing)、[Google Vids API](/docs/api-google-vids-v1#pricing)、[Gemini Notebook API](/docs/api-gemini-notebook-v1#pricing) 和 [Flow Music API](/docs/api-flowmusic-v1#pricing) ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-ai-subscription-api === Document URL: https://useapi.net/docs/articles/google-ai-subscription-api --- layout: default title: "Can You Use Your Google AI Subscription Through an API? What Plus, Pro and Ultra Get You" seo_title: "Google AI Pro and Ultra Through an API: What Your Plan Gets You" description: "Use Google AI Plus, Pro or Ultra through an API with useapi.net: one Ultra plan makes $3,919 of videos and songs a month at Google's API prices, plus images." keywords: [Google AI subscription API, Google AI Pro API, Google AI Ultra API, Google AI Plus API, Google AI Ultra Gemini API, does Google AI Ultra include API access, Google AI Pro API access, Gemini subscription API, Google One AI API, Flow credits API, Google Vids API, Gemini Notebook API, NotebookLM API, Google Flow Music API, Lyria 3.5 API, Flow Music credits Google AI Pro, Veo 3.1 API, Omni 1.2 Flash API, Nano Banana API, Google Cloud credits, Google Developer Program, Google Flow API] parent: Articles nav_exclude: true date: 2026-11-07 last_modified: 2026-11-07 nav_order: 910 repo: https://github.com/useapi/google-flow-api translation_key: google-ai-subscription --- ## Can You Use Your Google AI Subscription Through an API? What Plus, Pro and Ultra Get You 6 min read • November 7, 2026 ## Table of contents ### The short answer Yes, through useapi.net. Your [Google AI plan](https://gemini.google/subscriptions/) (Plus, Pro or Ultra) comes with monthly allowances for Google's creative tools. useapi.net turns each one into an API: - [Google Flow API](/docs/api-google-flow-v1): videos from your Flow credits, and images that use none - [Google Vids API](/docs/api-google-vids-v1): videos, talking avatars and speech from your Vids seconds - [Gemini Notebook API (NotebookLM API)](/docs/api-gemini-notebook-v1): podcasts, slides and research from your Notebook usage - [Flow Music API](/docs/api-flowmusic-v1): songs from the Flow Music credits your plan includes On Ultra $199.99, a month of it is worth about $3,919 on Google's own APIs (as of November 2026). The Gemini API itself isn't part of the plan. Google bills it separately, per second of video and per image. Pro and Ultra include a small monthly [Google Cloud credit](https://developers.google.com/program/plans-and-pricing) for it: $10 on Pro, $40 on Ultra $99.99 and $100 on Ultra $199.99. Even $100 buys only about 96 fifteen-second Omni 1.2 Flash videos there. ### Everything one plan makes in a month What a single Google AI plan adds up to through useapi.net each month, and what the same output would cost on Google's own APIs (as of November 2026). | One month | Ultra $199.99 | Ultra $99.99 | Pro $19.99 | Plus $4.99 | |---|---|---|---|---| | **Google Flow** (one pool of credits, pick one row) | 25,000 cr | 10,000 cr | 1,000 cr | 200 cr | | Veo 3.1 Fast videos (8 s, 1080p) | 2,500 | 1,000 | 50 | 10 | | or Veo 3.1 Lite videos (8 s, 1080p) | 5,000 | 2,000 | 100 | 20 | | or Omni 1.1 Flash videos (10 s, 1080p) | 1,666 | 666 | 66 | 13 | | or Omni 1.2 Flash videos (10 s, 1080p, free upscale) | 833 | 333 | 33 | 6 | | or Omni 1.2 Flash videos (15 s, 720p) | 416 | 166 | 16 | 3 | | or 4K video upscales (clips up to 10 s) | 500 | 200 | — | — | | **Google Flow, no credits** (on top of the pool) | | | | | | Veo 3.1 Lite videos (lower priority, 8 s) | 1,000+ a day | — | — | — | | Video upscales to 1080p (clips up to 10 s) | free | free | free | free | | Nano Banana images (Pro, 2.1, 2 Lite, upscaled) | ~500 a day, 4K | included, 4K | included, 2K | included, 2K | | **Google Vids** (own allowance, on top) | 10,000 s | 2,500 s | 500 s | 60 s | | Omni 1.2 Flash videos (15 s, 1080p) | 666 | 166 | 33 | 4 | | Talking avatar videos (up to 30 s) | 500 | 125 | 25 | 6 | | Images (basic, about 1 MP) | 1,000 | 300 | 30 | up to 50 | | Speech (30 voices) | included | included | included | included | | **Flow Music** (own credits, on top) | 30,000 cr | 30,000 cr | 10,000 cr | 3,000 cr | | Lyria 3.5 songs (full songs) | 6,000 | 6,000 | 2,000 | 600 | | **Gemini Notebook** (own limits, on top) | | | | | | Podcasts (per 5-hour window) | 181 | ~45 | 9 | ~4 | | **Google Cloud credits** (for the Gemini API) | $100 | $40 | $10 | — | | **Worth on Google's APIs** (videos and songs) | **$3,919** | **$1,699** | **$259** | **$64** | - Google Flow credits are one pool. A plan makes the Veo 3.1 Fast videos, or one of the "or" rows, or a mix of them, never all of them. Everything below the pool is a separate allowance and adds on top. - Flow upscales a video to 1080p for free up to 10 seconds and charges 1 credit for each second over that ([video upscale](/docs/api-google-flow-v1/post-google-flow-videos-upscale), [Google's Flow credits page](https://support.google.com/flow/answer/16526234)). So every 1080p row in the Flow pool counts clips of 10 seconds or shorter. A 4K upscale takes 50 credits from the pool, on Ultra only. In Vids, 1080p uses the same seconds as 720p. - The worth row counts the Flow pool as Veo 3.1 Fast at 1080p ($0.96 a video on Google's API), the Vids videos at 1080p ($1.56) and the songs at $0.08. That is 13 to 20 times each plan's price. - The "1,000+ a day" Veo 3.1 Lite videos and "~500 a day" images are what our busiest Ultra $199.99 accounts reach, not limits Google publishes. Lower-priority Lite runs only for the owner of that plan. - The Vids counts are Google's figures, and our Pro test account showed exactly 25 avatar videos. Google notes that some plans share one limit between avatars and video clips. On Plus, images and voice-overs share 50 credits a month. Pro and Ultra list voice-over as unlimited, while our test accounts showed a counter of 50 uses a month. Google has no API for talking avatars. ### What each plan makes in a month What each Google AI plan makes through useapi.net, and what one item costs on Google's own API (as of November 2026). A video costs its share of the plan: the plan price divided by what the plan makes. | What it makes | Official API | Ultra $199.99/m (25,000 cr, 10,000 s) | Ultra $99.99/m (10,000 cr, 2,500 s) | Pro $19.99/m (1,000 cr, 500 s) | Plus $4.99/m (200 cr, 60 s) | |---|---|---|---|---|---| | Omni 1.2 in Flow (720p, 15 s) | [$1.04](https://ai.google.dev/gemini-api/docs/pricing) ($0.07/s) | $0.48 / 60 cr (416 videos/mo) | $0.60 / 60 cr (166 videos/mo) | $1.20 / 60 cr (16 videos/mo) | $1.50 / 60 cr (3 videos/mo) | | Omni 1.1 in Flow (720p, 10 s) | [$1.01](https://ai.google.dev/gemini-api/docs/pricing) ($0.10/s) | $0.12 / 15 cr (1,666 videos/mo) | $0.15 / 15 cr (666 videos/mo) | $0.30 / 15 cr (66 videos/mo) | $0.37 / 15 cr (13 videos/mo) | | Omni 1.2 in Vids (720p, 15 s) | [$1.04](https://ai.google.dev/gemini-api/docs/pricing) ($0.07/s) | $0.30 / 15 s (666 videos/mo) | $0.60 / 15 s (166 videos/mo) | $0.60 / 15 s (33 videos/mo) | $1.25 / 15 s (4 videos/mo) | | Omni 1.2 in Vids (1080p, 15 s) | [$1.56](https://ai.google.dev/gemini-api/docs/pricing) ($0.104/s) | $0.30 / 15 s (666 videos/mo) | $0.60 / 15 s (166 videos/mo) | $0.60 / 15 s (33 videos/mo) | $1.25 / 15 s (4 videos/mo) | | Veo 3.1 Fast (Flow, 720p, 8 s) | [$0.80](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing) ($0.10/s) | $0.08 / 10 cr (2,500 videos/mo) | $0.10 / 10 cr (1,000 videos/mo) | $0.40 / 20 cr (50 videos/mo) | $0.50 / 20 cr (10 videos/mo) | | Nano Banana Pro (Flow image) | [$0.134](https://ai.google.dev/gemini-api/docs/pricing) (per image) | $0 / 0 cr (~500 a day) | $0 / 0 cr (included) | $0 / 0 cr (included) | $0 / 0 cr (included) | | Lyria 3.5 song (Flow Music) | [$0.08](https://ai.google.dev/gemini-api/docs/pricing) (per song) | $0.033 / 5 cr (6,000 songs/mo) | $0.017 / 5 cr (6,000 songs/mo) | $0.010 / 5 cr (2,000 songs/mo) | $0.008 / 5 cr (600 songs/mo) | | Notebook (podcasts per 5 h) | [Enterprise](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks) (Preview) | 181 | ~45 | 9 | ~4 | | Cloud credits (Gemini API use) | — | $100/mo | $40/mo | $10/mo | — | - The Notebook row counts the Audio Overviews (podcasts) one full 5-hour window can start, by Google's own estimates. Plus and Ultra $99.99 are scaled by Google's [published multipliers](https://support.google.com/gemininotebook/answer/17670842). - Each Flow video and image needs a captcha, which the API solves. Your first account gets 300 free, then your own [captcha provider](/docs/start-here/setup-google-flow#configure-captcha-providers) costs about $0.80 to $3.00 per 1,000. - Plan prices are Google's US prices. The [Google Flow](/docs/api-google-flow-v1#pricing) and [Google Vids](/docs/api-google-vids-v1#pricing) price tables list every model on every plan. ### Google Flow: Veo 3.1, Omni Flash and Nano Banana The [Google Flow API](/docs/api-google-flow-v1) makes Veo 3.1 Fast, Quality and Lite videos and Omni 1.2 Flash and Omni 1.1 Flash videos from the plan's Flow credits. It also makes Nano Banana Pro, 2.1 and 2 Lite images, which use no credits, and upscales videos and images. On Google's side, Veo 3.1 runs on [Agent Platform](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing) at $0.10 a second for Fast at 720p and $0.12 at 1080p. Omni 1.2 Flash and Nano Banana run on the [Gemini API](https://ai.google.dev/gemini-api/docs/pricing). Both need a Google Cloud project with billing. The [Veo 3.1 API pricing](/docs/articles/veo-3-1-api-pricing) article compares every Veo price. ### Google Vids: Omni 1.2 Flash and talking avatars The [Google Vids API](/docs/api-google-vids-v1) makes Omni 1.2 Flash videos of 3 to 15 seconds with sound, at 720p or 1080p for the same seconds, and extends, edits and upscales them. It also makes [talking avatar videos](/docs/api-google-vids-v1/post-google-vids-videos-avatar) of up to 30 seconds, [speech](/docs/api-google-vids-v1/post-google-vids-speech) in 30 voices and basic images. None of these use video seconds. Google publishes no Vids API. The same model on the Gemini API costs $0.07 a second at 720p and $0.104 at 1080p. Vids asks for no captcha. Its seconds are shared by everyone on a Google family plan. The [Omni 1.2 Flash guide](/docs/articles/gemini-omni-1-2-flash-api) runs one scene in Flow and one in Vids. ### Gemini Notebook (NotebookLM): podcasts, video and Deep Research The [Gemini Notebook API (NotebookLM API)](/docs/api-gemini-notebook-v1) turns web pages, PDFs and YouTube videos into Audio Overviews (podcasts), Video Overviews, slide decks, infographics, reports and quizzes, and runs chat with citations and Deep Research. Cinematic Video Overviews need Pro or Ultra. Notebook has no credits. Each job uses part of the account's usage, which refills every 5 hours up to a weekly limit: Plus gets 2 times the free limits, Pro 4 times, and Ultra 5 or 20 times Pro's. Google's own [Gemini Notebook Enterprise API](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks) is in Preview, needs Enterprise licenses in a Google Cloud project and covers notebooks, sources, sharing and Audio Overviews only. ### Google Flow Music: Lyria 3.5 songs Every paid Google AI plan also includes [Google Flow Music](https://www.flowmusic.app) credits, separate from Flow credits. Plus gets [3,000 credits a month](https://support.google.com/googleone/answer/16882689), Pro [10,000](https://support.google.com/googleone/answer/14534406) and Ultra [30,000](https://support.google.com/googleone/answer/16286513). You claim them once: sign in at flowmusic.app with the same Google account and let Flow Music see your Google One membership. The [Flow Music API](/docs/api-flowmusic-v1) makes full songs with vocals or instrumentals on Lyria 3.5 and Lyria 3 Pro, at 5 credits a song. It also makes covers, remixes and extends, and splits songs into four stems. Google offers Flow Music only as a website. On the Gemini API a Lyria 3.5 song costs $0.08, and a generated song can't be edited there. ### One Google account, four allowances Flow credits, Vids seconds, Notebook usage and Flow Music credits are counted separately, and none of them takes from another. Connect the same Google account to all four APIs and it uses every allowance: Omni 1.2 Flash videos in Flow and in Vids on top of each other, podcasts and Deep Research from Notebook, and songs from Flow Music. Each API has its own setup page ([Flow](/docs/start-here/setup-google-flow), [Vids](/docs/start-here/setup-google-vids), [Notebook](/docs/start-here/setup-gemini-notebook), [Flow Music](/docs/start-here/setup-flowmusic)), and one useapi.net subscription covers all four. ### Which plan to pick - Ultra $199.99 is the only plan with [Veo 3.1 Lite at lower priority](/docs/api-google-flow-v1/post-google-flow-videos), which uses no credits at all. Google publishes no limit, and our busiest accounts make 1,000+ of these videos a day, on top of the 25,000 monthly credits. It also has the lowest price per video: Veo 3.1 Fast at $0.08, and a fifteen-second Omni 1.2 Flash video at $0.30 in Vids or $0.48 in Flow. - Ultra $99.99 costs half as much but has no lower-priority Veo 3.1 Lite. It makes 1,000 Veo 3.1 Fast videos at $0.10 and 166 Vids videos at $0.60, with the same 6,000 songs. - Pro is the plan to start with. It makes 50 Veo 3.1 Fast videos a month at $0.40, half Google's price, 33 fifteen-second Vids videos at $0.60 and 2,000 Lyria 3.5 songs. On Pro, make Omni 1.2 Flash in Vids: in Flow it costs $1.20, more than the Gemini API's $1.04. - Plus can cost more per video than Google's API. A fifteen-second 720p Omni 1.2 Flash video is $1.50 in Flow and $1.25 in Vids, against $1.04. Veo 3.1 Fast is still cheaper, $0.50 against $0.80, but only 10 a month. Plus fits songs (600 a month), Nano Banana images and Gemini Notebook better than video. ## Questions ### Does Google AI Ultra include Gemini API access? Through useapi.net, Ultra $199.99 makes 2,500 Veo 3.1 Fast videos, 666 Omni 1.2 Flash videos in Vids and 6,000 songs a month, worth about $3,919 on Google's APIs (as of November 2026). The plan itself includes no Gemini API usage. It comes with [Google Cloud credits](https://developers.google.com/program/plans-and-pricing) of $100 a month ($40 on Ultra $99.99), which you activate in the Google Developer Program. That buys about 96 fifteen-second Omni 1.2 Flash videos. ### Can I use my Google AI Pro plan with an API? Through useapi.net, yes: Pro's 1,000 Flow credits, 500 Vids seconds and 10,000 Flow Music credits run over REST. They make 50 Veo 3.1 Fast videos a month at $0.40 each, against $0.80 on Google's Agent Platform. They also make 33 fifteen-second Omni 1.2 Flash videos in Vids at $0.60, against $1.04 on the Gemini API, and 2,000 Lyria 3.5 songs, worth $160 there (as of November 2026). Nano Banana images use no credits. ### How many Veo 3.1 videos does Google AI Ultra make? Through useapi.net, Ultra $199.99 makes 2,500 eight-second Veo 3.1 Fast videos a month at $0.08 each, against $0.80 on Google's [Agent Platform](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing), and Ultra $99.99 makes 1,000 at $0.10 (as of November 2026). Ultra $199.99 also runs Veo 3.1 Lite at lower priority for no credits, about 1,000 or more a day on our busiest accounts. ### Is there a NotebookLM API? Through useapi.net, yes, for regular Google accounts: the Gemini Notebook API (NotebookLM API) runs Audio and Video Overviews, slides, chat with citations and Deep Research on your Google AI plan, the free one included. Google's own [Enterprise API](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks) is in Preview, needs Enterprise licenses in a Google Cloud project and has no Video Overviews, chat or Deep Research (as of November 2026). ### Can a free Google account use it? Through useapi.net, yes, in Flow and Notebook. A free account's 50 Flow credits a day make 2 Veo 3.1 Fast videos, 5 Lite ones or one 10-second 720p Omni 1.2 Flash video, and Nano Banana images use no credits. Notebook starts about 2 Audio Overviews per 5-hour window. The Gemini API has no free tier for Omni 1.2 Flash or Nano Banana Pro (as of November 2026). Vids is the exception: the free accounts we tested had no video seconds. ### Sources - Google, [Google AI plans](https://gemini.google/subscriptions/) and the [Developer plans](https://gemini.google/subscriptions/?plans=developer), read November 7, 2026 - Google, [Google Developer Program plans](https://developers.google.com/program/plans-and-pricing) (Google Cloud credits per plan) and [New developer tools for Google AI Pro and Ultra subscribers](https://blog.google/innovation-and-ai/technology/developers-tools/gdp-premium-ai-pro-ultra/), January 27, 2026 - Google One Help, Flow Music benefits of [Google AI Plus](https://support.google.com/googleone/answer/16882689), [Google AI Pro](https://support.google.com/googleone/answer/14534406) and [Google AI Ultra](https://support.google.com/googleone/answer/16286513), read November 7, 2026 - Google, [Gemini API pricing](https://ai.google.dev/gemini-api/docs/pricing) (Omni 1.2 Flash, Nano Banana, Lyria 3.5), read November 7, 2026 - Google Cloud, [Agent Platform pricing](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing) (Veo 3.1), read November 7, 2026 - Google, [Flow credits](https://support.google.com/flow/answer/16526234), [Gemini in Google Vids](https://support.google.com/docs/answer/15609411) and [Gemini Notebook usage limits](https://support.google.com/gemininotebook/answer/17670842), read November 7, 2026 - Google Cloud, [Gemini Notebook Enterprise API](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks), read November 7, 2026 - useapi.net price tables: [Google Flow API](/docs/api-google-flow-v1#pricing), [Google Vids API](/docs/api-google-vids-v1#pricing), [Gemini Notebook API](/docs/api-gemini-notebook-v1#pricing) and [Flow Music API](/docs/api-flowmusic-v1#pricing) ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-flow-agent-chat-es === Document URL: https://useapi.net/docs/articles/google-flow-agent-chat-es --- layout: default title: "Cómo chatear con Google Flow Agent mediante la Google Flow API" description: "Chatea con Google Flow Agent desde tu código con la Google Flow API de useapi.net: inicia un chat, recibe las respuestas por SSE, aprueba el gasto de créditos y descarga las imágenes y los videos, con curl." keywords: [Google Flow Agent API, Google Flow Agent, Flow Agent API, Google Flow API, AI agent API, Server-Sent Events, SSE, approval, Nano Banana 2.1, Omni 1.1 Flash, MCP server, Claude Code, curl, API de Google Flow Agent, API de agente de IA, streaming, tutorial en español] image: https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-shot-2-nano-banana-2-1.jpg parent: Articles nav_exclude: true lang: es translation_key: google-flow-agent-chat date: 2026-10-17 last_modified: 2026-11-10 nav_order: 903 repo: https://github.com/useapi/google-flow-api --- ## Cómo chatear con Google Flow Agent mediante la Google Flow API {: .no_toc #how-to-chat-with-google-flow-agent-via-the-google-flow-api } 8 min de lectura • 17 de octubre de 2026 (10 de noviembre de 2026) useapi.net es una API de terceros. No está afiliada a Google ni cuenta con su respaldo. ## Índice {: .no_toc .text-delta #table-of-contents } ### Introducción La Google Flow API de useapi.net permite que tu código chatee con Google Flow Agent, el asistente creativo integrado en [Google Flow](https://flow.google.com): inicias un chat con un solo `curl`, recibes sus respuestas en streaming, apruebas lo que quiere gastar y descargas las imágenes y los videos que crea. Google ofrece [Flow Agent](https://support.google.com/labs/answer/17093911?hl=es) solo dentro de la aplicación web de Google Flow, sin API pública (a noviembre de 2026). useapi.net es una API [de terceros](/docs/legal#affiliation--third-party-services), no afiliada a Google, y el chat se ejecuta en tu cuenta de Google Flow, gratuita o de pago. Chatear con el agente no cuesta créditos, y las imágenes y los videos que crea tienen el precio habitual de Google Flow. Esta guía es una ejecución real, de principio a fin. Le pedimos al agente dos fotos de producto de una taza de cerámica y un video de 6 segundos de ella, aprobamos el gasto, descargamos los archivos, luego pedimos una revisión y la rechazamos. Cada respuesta de abajo es de esa ejecución, recortada y con el correo de la cuenta reemplazado. El agente planifica el trabajo por su cuenta. Elige las herramientas y los modelos según la [configuración](#step-7-settings-for-approval-instructions-and-default-models) del proyecto, y guarda toda la conversación del lado de Google, así que un chat puede seguir horas o días después con todo el contexto. La [descripción general del Agent](/docs/api-google-flow-v1/agent) cubre cada regla y límite. ### Antes de empezar Necesitas un [token de API](/docs/start-here/setup-useapi) de useapi.net y una cuenta de Google conectada con la [configuración de Google Flow](/docs/start-here/setup-google-flow). El agente funciona en cualquier plan de Google AI, incluso en una cuenta gratuita, y lo que puede generar depende del plan de la cuenta, igual que [POST /images](/docs/api-google-flow-v1/post-google-flow-images) y [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos). Cada turno usa un captcha, que la API resuelve con tus [proveedores de captcha](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers) o con los créditos de captcha gratis de tu primera cuenta. No tienes que enviar nada para eso. Los pasos usan `curl`, `jq` y tres variables de shell: ```bash export USEAPI_TOKEN="user:12345-..." # tu token de API de useapi.net export EMAIL="john@gmail.com" # una cuenta de Google Flow conectada API="https://api.useapi.net/v1/google-flow/agent" ``` Todas las llamadas de abajo también están en la [colección de Postman](https://www.postman.com/useapinet/useapi-net). ### Cómo funciona un chat Un turno es un mensaje tuyo y todo lo que el agente hace en respuesta. Un chat ejecuta un turno a la vez: 1. [POST /agent/chats](/docs/api-google-flow-v1/post-google-flow-agent-chats) inicia un chat y responde `202` con un `chatId`. 2. [GET /agent/chats/`chatId`/stream](/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId-stream) sigue al agente en vivo con Server-Sent Events. 3. Cuando el agente quiere gastar créditos, se detiene y pregunta. [POST /agent/chats/`chatId`/approval](/docs/api-google-flow-v1/post-google-flow-agent-chats-chatId-approval) responde. 4. [POST /agent/chats/`chatId`/messages](/docs/api-google-flow-v1/post-google-flow-agent-chats-chatId-messages) envía el siguiente mensaje. 5. [GET /agent/chats/`chatId`](/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId) lee todo el chat, con enlaces nuevos a los archivos. ### Paso 1: Inicia un chat Envía el encargo como `message`. La llamada vuelve en cuanto Google acepta el turno, lo que suele tardar unos segundos y puede tardar hasta unos 100 segundos, así que dale a `curl` un tiempo de espera de 150 segundos: ```bash curl -s --max-time 150 -X POST "$API/chats" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$EMAIL"'", "message": "Create two product shots of a matte sage-green ceramic coffee mug on a light oak table in soft morning window light, square format, with Nano Banana 2.1. Then make one 6 second video of the same mug with steam slowly rising from the coffee, with Omni 1.1 Flash." }' ``` El nuestro respondió `202` en unos 10 segundos: ```json { "chatId": "c-u12345-email:john@gmail.com-project:74262ac8-a54f-4ad7-80d7-3d44a4d6c6c1-chat:55023a0f-5e70-4545-bb4a-d878038dcf35-bot:google-flow", "email": "john@gmail.com", "turn": 1, "status": "running" } ``` El `chatId` ya indica la cuenta y el proyecto, así que las llamadas siguientes no necesitan ninguno de los dos. Contiene `:` y `@`, así que codifícalo para URL en la ruta. Guarda las dos formas: ```bash CHATID="c-u12345-email:john@gmail.com-project:74262ac8-...-bot:google-flow" CHAT=$(jq -rn --arg v "$CHATID" '$v|@uri') ``` Sin `projectId`, el chat vive en el proyecto de agente de la propia cuenta, creado en su primer chat y con un nombre como `My Agents Work Fri, Oct 16`, lo que separa el trabajo del agente del resto de tus archivos de Google Flow. También puedes adjuntar hasta 7 imágenes, un video, 5 voces y 7 personajes a cualquier mensaje, con la misma sintaxis de menciones `@` que [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos). Consulta [POST /agent/chats](/docs/api-google-flow-v1/post-google-flow-agent-chats#request-body). ### Paso 2: Recibe la respuesta en streaming Abre el stream con `-N` para que los eventos se impriman a medida que llegan. El `EventSource` del navegador no puede enviar el encabezado `Authorization`, así que en una aplicación usa `fetch()` o cualquier cliente HTTP: ```bash curl -s -N "$API/chats/$CHAT/stream" \ -H "Authorization: Bearer $USEAPI_TOKEN" ``` Un stream nuevo envía primero un evento `chat`, reproduce el historial del chat y luego envía `replayed`. Todo lo que llega después de `replayed` es en vivo. Aquí el primer turno ya había terminado cuando nos conectamos, así que llegó en la reproducción. El agente expuso su plan y luego pidió permiso para gastar 10 créditos en 2 imágenes y 1 video (`ui` y otros campos largos omitidos): ``` event: chat data: {"chatId":"c-u12345-email:john@gmail.com-project:74262ac8-...-bot:google-flow","status":"waiting_approval","turns":1} id: 1:505e78d7-bd79-4938-b0ec-8117bdb933dc event: message data: {"id":"1:505e78d7-...","turn":1,"items":[{"kind":"text","text":"I'm going to generate two images of a matte sage-green ceramic coffee mug, then I'll create a 6-second video of the same mug with rising steam using Omni 1.1 Flash."}]} id: 1:00c21a03-a687-4173-9fd9-190fcdf2447b event: message data: {"id":"1:00c21a03-...","turn":1,"items":[{"kind":"tool_call","tool":"open_chat_panel","args":{"_synthetic":true}},{"kind":"tool_call","tool":"ask_for_permission","args":{"num_total":3,"total_cost":10,"num_videos":1,"num_images":2}}]} id: 1:approval event: approval data: {"turn":1,"cost":10,"images":2,"videos":1,"total":3} event: replayed data: {"turns":1} ``` Los eventos sobre los que actúas: | Evento | Qué significa | |---|---| | `message` | Un mensaje completo del agente: su texto, su razonamiento, las llamadas a herramientas y sus resultados | | `approval` | El agente pide permiso antes de gastar `cost` créditos de Flow | | `turn` | Terminó un turno: `completed`, `waiting_approval` o `failed` con un `error` | | `media` | Una imagen o un video que hizo el agente, o un cambio de su estado, con su `url` al quedar `completed` | Cada 15 segundos llega un `keepalive`. Un solo stream cubre todo el chat, turno tras turno, así que déjalo abierto mientras apruebas y envías mensajes. Si se corta, reconéctate con el último `id` en el encabezado `Last-Event-ID` y retoma donde se quedó. Un turno sigue ejecutándose si cierras el stream, así que no se pierde nada. ### Paso 3: Aprueba el gasto En el modo de aprobación `ask`, el agente se detiene antes de gastar nada. El `status` del chat es `waiting_approval` y el evento `approval` muestra el costo. Responde con `approve`, `always` o `reject` en unos 4 minutos: ```bash curl -s --max-time 150 -X POST "$API/chats/$CHAT/approval" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "decision": "approve" }' ``` Desde que Google cambió Flow Agent el 10 de noviembre de 2026, la respuesta continúa el turno que hizo la pregunta (aquí el turno 1, no un nuevo turno 2), y Google solo la acepta mientras ese turno sigue abierto, unos 4 minutos después de la pregunta. Una respuesta más tardía recibe `409`: envía el mensaje otra vez, o pon el proyecto en `approval: "auto"` en el [paso 7](#step-7-settings-for-approval-instructions-and-default-models) para que el agente nunca pregunte. La ejecución de abajo se grabó antes del cambio, así que su respuesta inició el turno 2, y sus nombres de herramienta (`generate_video_from_text`) ahora aparecen como `generate_image` y `generate_video`. La respuesta pone al agente a trabajar otra vez: ```json { "chatId": "c-u12345-email:john@gmail.com-project:74262ac8-...-bot:google-flow", "email": "john@gmail.com", "turn": 2, "status": "running" } ``` En el stream abierto, el turno 2 puso el video en cola, hizo las dos imágenes y terminó en unos 30 segundos. Las `choices` del agente (`Option 1`, `Option 2`) son los mosaicos que la aplicación web de Google Flow muestra para cada resultado: ``` id: 2:5feb253e-0848-422a-bcb8-936995b3c0df event: message data: {"id":"2:5feb253e-...","turn":2,"items":[{"kind":"tool_result","tool":"generate_video_from_text","result":{"status":"queued","media_id":"5732c66d-a971-4cd0-92d2-508ef0aecc07","display_name":"Steam rising from coffee mug","model_key":"abra_t2v_6s","aspect_ratio":"VIDEO_ASPECT_RATIO_LANDSCAPE"}}]} id: 2:m:5732c66d-a971-4cd0-92d2-508ef0aecc07 event: media data: {"turn":2,"referenceId":"user:12345-email:6a6f...-video:5732c66d-a971-4cd0-92d2-508ef0aecc07","mediaId":"5732c66d-a971-4cd0-92d2-508ef0aecc07","type":"video","status":"queued","tool":"generate_video_from_text","model":"abra_t2v_6s","displayName":"Steam rising from coffee mug"} id: 2:m:377ecb33-ab2c-4bce-92d4-7bfcf53a9af2 event: media data: {"turn":2,"referenceId":"user:12345-email:6a6f...-image:377ecb33-ab2c-4bce-92d4-7bfcf53a9af2","mediaId":"377ecb33-ab2c-4bce-92d4-7bfcf53a9af2","type":"image","status":"completed","tool":"generate_image","displayName":"Ceramic coffee mug on table","url":"https://flow-content.google/image/377ecb33-...?Expires=...&Signature=..."} id: 2:4e37b051-c49c-4331-bc0c-06ccc539b950 event: message data: {"id":"2:4e37b051-...","turn":2,"items":[{"kind":"text","text":"I've generated your two product shots. Your 6-second video has been scheduled and is waiting in the queue due to high demand. Feel free to check back in a few minutes."}]} id: 2:end event: turn data: {"turn":2,"status":"completed"} ``` `always` aprueba y además cambia el proyecto al modo `auto`, así que el agente deja de preguntar en todos los chats del proyecto. `reject` rechaza, como se ve en el [paso 5](#step-5-continue-or-revise). Mientras una pregunta espera, un mensaje nuevo recibe `409`: responde la pregunta primero. ### Paso 4: Descarga los archivos Las imágenes están listas cuando termina el turno. Los videos suelen terminar uno o dos minutos después, y el stream envía un segundo evento `media` para el video cuando termina. El nuestro llegó menos de un minuto después del final del turno: ``` id: 2:m:5732c66d-a971-4cd0-92d2-508ef0aecc07 event: media data: {"turn":2,"referenceId":"user:12345-email:6a6f...-video:5732c66d-a971-4cd0-92d2-508ef0aecc07","mediaId":"5732c66d-a971-4cd0-92d2-508ef0aecc07","type":"video","status":"completed","tool":"generate_video_from_text","model":"abra_t2v_6s","displayName":"Steam rising from coffee mug","url":"https://flow-content.google/video/5732c66d-...?Expires=...&Signature=...","durationSec":6} ``` Descarga cada `url` mientras está vigente: ```bash curl -s -L -o mug-steam.mp4 "https://flow-content.google/video/5732c66d-...?Expires=...&Signature=..." ``` Los enlaces apuntan a Google y vencen unas 6 horas después de emitirse. Lee el chat otra vez con [GET /agent/chats/`chatId`](#step-6-read-list-rename-and-delete-chats) para obtener enlaces nuevos, o pide el enlace de un elemento a [GET /assets/`mediaGenerationId`](/docs/api-google-flow-v1/get-google-flow-assets-mediagenerationid) con su `referenceId`. El `referenceId` también sirve como `referenceImage_N` o `referenceVideo_1` en [POST /images](/docs/api-google-flow-v1/post-google-flow-images), [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) y tu siguiente mensaje al agente. Las dos imágenes y el video de 1280×720 están en [Ejemplos](#examples). La ejecución gastó 10 créditos: las dos imágenes de Nano Banana 2.1 costaron 0 en el plan de esta cuenta, y el video de 6 segundos de Omni 1.1 Flash costó 10. ### Paso 5: Continúa o revisa Envía el siguiente mensaje al mismo chat. Google guarda la conversación, así que el agente sabe cuál es "el video": ```bash curl -s --max-time 150 -X POST "$API/chats/$CHAT/messages" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "message": "Nice. Revise the video: make it 8 seconds, with a slow camera push-in toward the mug while the steam rises." }' ``` Respondió `202` con `"turn": 3`, y el agente volvió a pedir permiso, esta vez por 12 créditos: ``` id: 3:approval event: approval data: {"turn":3,"cost":12,"images":0,"videos":1,"total":1} id: 3:end event: turn data: {"turn":3,"status":"waiting_approval"} ``` Ya teníamos nuestro video, así que rechazamos: ```bash curl -s --max-time 150 -X POST "$API/chats/$CHAT/approval" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "decision": "reject" }' ``` El turno 4 terminó con una respuesta y sin imagen ni video nuevos, y no se gastaron créditos: ``` id: 4:91e06fb7-ba5b-4e32-b2a6-ce210be491ba event: message data: {"id":"4:91e06fb7-...","turn":4,"items":[{"kind":"text","text":"I've cancelled that generation. Are there any changes you'd like to make to the prompt or concept before we try again?"}]} id: 4:end event: turn data: {"turn":4,"status":"completed"} ``` Enviar un mensaje mientras se ejecuta un turno responde `409`, así que espera primero el evento `turn`. Para elegir una de las opciones del agente, envía el texto de la opción como siguiente mensaje, como hace la aplicación web de Google Flow. ### Paso 6: Lee, lista, renombra y elimina chats Lee todo el chat desde Google en cualquier momento. Cada turno trae tu mensaje, todo lo que hizo el agente y los archivos con enlaces nuevos: ```bash curl -s "$API/chats/$CHAT" -H "Authorization: Bearer $USEAPI_TOKEN" ``` Nuestro chat después de los cuatro turnos (elementos de `agent` y `media` recortados, `ui` omitido): ```json { "chatId": "c-u12345-email:john@gmail.com-project:74262ac8-...-bot:google-flow", "email": "john@gmail.com", "projectId": "74262ac8-a54f-4ad7-80d7-3d44a4d6c6c1", "title": "Sage Green Ceramic Mug Concept", "created": "2026-10-18T00:47:54.000Z", "updated": "2026-10-18T00:50:47.236Z", "status": "idle", "pendingApproval": null, "lastError": null, "turns": [ { "turn": 1, "message": { "text": "Create two product shots of a matte sage-green ceramic coffee mug ...", "references": [] }, "agent": [ { "kind": "text", "text": "I'm going to generate two images of a matte sage-green ceramic coffee mug, then I'll create a 6-second video ..." }, { "kind": "tool_call", "tool": "ask_for_permission", "args": { "num_total": 3, "total_cost": 10, "num_videos": 1, "num_images": 2 } } ], "media": [] }, { "turn": 2, "message": { "text": "Approve", "references": [] }, "agent": [ { "kind": "tool_call", "tool": "generate_video_from_text", "args": { "duration": 6, "aspect_ratio": "16:9", "model_display_name": "Omni 1.1 Flash", "prompt": "Cinematic product video of a matte sage-green ceramic coffee mug ..." } }, { "kind": "tool_call", "tool": "generate_image", "args": { "aspect_ratio": "1:1", "prompt": "A professional product shot of a matte sage-green ceramic coffee mug ..." } }, { "kind": "text", "text": "I've generated your two product shots. Your 6-second video has been scheduled ..." } ], "media": [ { "referenceId": "user:12345-email:6a6f...-video:5732c66d-...", "type": "video", "status": "completed", "model": "abra_t2v_6s", "displayName": "Steam rising from coffee mug", "url": "https://flow-content.google/video/5732c66d-...", "durationSec": 6 }, { "referenceId": "user:12345-email:6a6f...-image:377ecb33-...", "type": "image", "status": "completed", "displayName": "Ceramic coffee mug on table", "url": "https://flow-content.google/image/377ecb33-..." }, { "referenceId": "user:12345-email:6a6f...-image:a2d3cd0c-...", "type": "image", "status": "completed", "displayName": "Ceramic coffee mug on wooden sur…", "url": "https://flow-content.google/image/a2d3cd0c-..." } ] }, { "turn": 3, "message": { "text": "Nice. Revise the video: make it 8 seconds, ...", "references": [] }, "agent": ["..."], "media": [] }, { "turn": 4, "message": { "text": "Reject", "references": [] }, "agent": [{ "kind": "text", "text": "I've cancelled that generation. Are there any changes you'd like to make to the prompt or concept before we try again?" }], "media": [] } ] } ``` Google le puso título al chat por su cuenta. El `status` es `idle` cuando no se ejecuta nada, y `pendingApproval` guarda el costo mientras el agente espera. Pasa `?media=false` para una lectura más rápida sin renovar los enlaces. Lista los chats de una cuenta, con la actividad más reciente primero. La lista viene de Google, así que también incluye los chats iniciados en la aplicación web de Google Flow en el mismo proyecto, y es la forma de encontrar un `chatId` perdido: ```bash curl -s "$API/chats?email=$EMAIL" -H "Authorization: Bearer $USEAPI_TOKEN" ``` Renombra un chat. El nuevo título también aparece en la aplicación web de Google Flow: ```bash curl -s -X PATCH "$API/chats/$CHAT" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "title": "Sage mug product shoot" }' ``` ```json { "chatId": "c-u12345-email:john@gmail.com-project:74262ac8-...-bot:google-flow", "title": "Sage mug product shoot" } ``` La lista quedó así: ```json { "chats": [ { "chatId": "c-u12345-email:john@gmail.com-project:74262ac8-...-chat:55023a0f-...-bot:google-flow", "email": "john@gmail.com", "title": "Sage mug product shoot", "created": "2026-10-18T00:47:54.000Z", "updated": "2026-10-18T00:51:01.773Z", "running": false }, { "chatId": "c-u12345-email:john@gmail.com-project:74262ac8-...-chat:1d9d42ed-...-bot:google-flow", "email": "john@gmail.com", "title": "Stylish Female Character Action Sequence", "created": "2026-10-17T03:50:34.000Z", "updated": "2026-10-17T04:57:26.375Z", "running": false } ] } ``` Elimina la conversación de un chat. Responde `204` sin cuerpo, el chat desaparece de la lista y de la aplicación web de Google Flow, y las imágenes y los videos que hizo se quedan en el proyecto: ```bash curl -s -X DELETE "$API/chats/$CHAT" -H "Authorization: Bearer $USEAPI_TOKEN" ``` Renombrar y eliminar responden `409` mientras se ejecuta un turno. ### Paso 7: Configuración de aprobación, instrucciones y modelos predeterminados Cada proyecto de Google Flow tiene una configuración del agente, la misma del panel del agente en la aplicación web de Google Flow. [GET /agent/settings](/docs/api-google-flow-v1/get-google-flow-agent-settings) la lee y además lista los modelos de imagen y de video que tiene el plan de Google de la cuenta, con lo que cuesta una imagen o un video en ese plan: ```bash curl -s "$API/settings?email=$EMAIL" -H "Authorization: Bearer $USEAPI_TOKEN" ``` [PUT /agent/settings](/docs/api-google-flow-v1/put-google-flow-agent-settings) cambia solo los campos que envías. Antes de la ejecución pusimos el modo `ask` y los valores predeterminados: ```bash curl -s -X PUT "$API/settings" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$EMAIL"'", "approval": "ask", "imageDefaults": { "model": "nano-banana-2", "aspectRatio": "1:1", "count": 2 }, "videoDefaults": { "model": "omni-flash", "aspectRatio": "16:9", "count": 1 } }' ``` La respuesta es la configuración del proyecto después del cambio: ```json { "projectId": "74262ac8-a54f-4ad7-80d7-3d44a4d6c6c1", "approval": "ask", "instructions": [], "imageDefaults": { "model": "nano-banana-2", "aspectRatio": "1:1", "count": 2 }, "videoDefaults": { "model": "omni-flash", "aspectRatio": "16:9", "count": 1 }, "models": { "image": [ { "model": "nano-banana-pro", "label": "Nano Banana Pro", "credits": 0 }, { "model": "nano-banana-2-lite", "label": "Nano Banana 2 Lite", "credits": 0 }, { "model": "nano-banana-2", "label": "Nano Banana 2.1", "credits": 0 } ], "video": [ { "model": "omni-flash", "label": "Omni 1.1 Flash", "credits": 4 }, { "model": "veo-3.1-lite", "label": "Veo 3.1 - Lite", "credits": 5 }, { "model": "veo-3.1-fast", "label": "Veo 3.1 - Fast", "credits": 10 }, { "model": "veo-3.1-quality", "label": "Veo 3.1 - Quality", "credits": 100 } ] } } ``` `credits` es el costo más bajo de una imagen o un video en el plan de la cuenta, así que un video más largo o de mayor resolución cuesta más: nuestro video de 6 segundos en 720p de Omni 1.1 Flash costó 10, y la revisión de 8 segundos habría costado 12. Tu plan puede mostrar otros números. Los campos de la configuración: - `approval`: `ask` (el agente se detiene y muestra el costo) o `auto` (gasta sin preguntar). - `instructions`: hasta 3 instrucciones fijas que el agente sigue en cada chat del proyecto, cada una con imágenes de referencia opcionales. El arreglo reemplaza las instrucciones del proyecto, así que envía la lista completa. - `imageDefaults` y `videoDefaults`: el modelo, la relación de aspecto y la cantidad que usa el agente cuando un mensaje no dice otra cosa, elegidos de `models`. La configuración se aplica a cada chat del proyecto, incluidos los chats en la aplicación web de Google Flow. ### Lo mismo desde un asistente de IA El [servidor MCP de Google Flow](/docs/api-google-flow-v1/mcp) alojado le da a Claude Code, Cursor, VS Code y otros clientes MCP el mismo chat en 12 herramientas, sin nada que instalar. En Claude Code: ```bash claude mcp add --transport http useapi-google-flow https://api.useapi.net/v1/google-flow/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` Luego pídele al asistente las fotos de la taza con palabras sencillas. El asistente envía el encargo con `flow_agent_chat` y responde a la solicitud del agente de gastar créditos con `flow_agent_answer_approval`. El servidor aparece en el MCP Registry oficial como `net.useapi/google-flow`. Para ver primero un cliente de chat completo, abre la [demo en vivo](/demos/google-flow/). Pega tu token de API, elige una cuenta y chatea con el agente, con sus imágenes y videos dentro del chat, adjuntos, tarjetas de aprobación y configuración. Su código fuente son cinco archivos pequeños, sin paso de compilación, en GitHub en [google-flow-api/demo](https://github.com/useapi/google-flow-api/tree/main/demo), y la página de la [demo en vivo del Agent](/docs/api-google-flow-v1/agent-demo) relaciona cada función con su llamada a la API. ### Ejemplos Lo que hizo esta ejecución, sin ediciones. Los prompts son del propio agente, escritos a partir de nuestro encargo. ###### Nano Banana 2.1 » dos fotos de producto de la taza verde salvia (turno 2) {: .no_toc #nano-banana-21--two-product-shots-of-the-sage-green-mug-turn-2 } <div style="display: flex; gap: 2%; flex-wrap: wrap"> <figure style="margin: 0; width: 49%"><a href="https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-shot-1-nano-banana-2-1.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-shot-1-nano-banana-2-1.jpg" alt="Resultado de Google Flow Agent: una taza de cerámica verde salvia mate sobre una mesa de roble claro con luz suave de la mañana, hecha con Nano Banana 2.1" style="width: 100%" loading="lazy"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">Option 1, "Ceramic coffee mug on table"</figcaption></figure> <figure style="margin: 0; width: 49%"><a href="https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-shot-2-nano-banana-2-1.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-shot-2-nano-banana-2-1.jpg" alt="Resultado de Google Flow Agent: primer plano de la taza verde salvia con café, una cuchara de latón y un libro abierto al sol de la mañana, hecho con Nano Banana 2.1" style="width: 100%" loading="lazy"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">Option 2, el primer plano</figcaption></figure> </div> Ambas en JPEG de 1024×1024, 0 créditos en el plan de esta cuenta. ###### Omni 1.1 Flash » 6 segundos de vapor saliendo de la taza (turno 2) {: .no_toc #omni-11-flash--6-seconds-of-steam-rising-from-the-mug-turn-2 } <video poster="https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-steam-omni-1-1-flash-6s-poster.jpg" src="https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-steam-omni-1-1-flash-6s.mp4" style="width: 100%; aspect-ratio: 16/9; max-width: 720px" controls type="video/mp4" preload="metadata"></video> 1280×720 con sonido, 6 segundos, 10 créditos. Tutoriales relacionados: [video con Veo 3.1 mediante la Google Flow API](/docs/articles/google-flow-bash-es), [video con audio nativo en Omni Flash](/docs/articles/omni-flash-bash-es) e [imágenes con Nano Banana mediante la Google Flow API](/docs/articles/google-flow-images-bash-es). ### Preguntas frecuentes - **¿Hay una API de Google Flow Agent?** Con useapi.net, sí: la [Agent API](/docs/api-google-flow-v1/agent) inicia chats, transmite las respuestas por Server-Sent Events, responde las aprobaciones y devuelve las imágenes y los videos, en cualquier suscripción de Google AI, incluida una cuenta gratuita. Google ofrece [Flow Agent](https://support.google.com/labs/answer/17093911?hl=es) solo dentro de la aplicación web de Google Flow, sin una API pública propia (a noviembre de 2026). - **¿Cuánto cuesta chatear con Google Flow Agent?** Con useapi.net, chatear no cuesta créditos de Flow, y lo que hace el agente tiene el precio habitual de Google Flow, que el modo `ask` muestra antes de gastar nada. El video de 6 segundos en 720p de Omni 1.1 Flash de esta ejecución sale a US$0,08 en Google AI Ultra US$199,99, frente a US$0,61 en la [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) oficial (a noviembre de 2026). - **¿Los chats iniciados en la aplicación web de Google Flow aparecen en la API?** Con useapi.net, sí, cuando están en el mismo proyecto. [GET /agent/chats](/docs/api-google-flow-v1/get-google-flow-agent-chats) los lista, y todos los endpoints de arriba funcionan con ellos. Los chats iniciados por la API también aparecen en la aplicación web. Pasa el `projectId` de [GET /assets/projects/`email`](/docs/api-google-flow-v1/get-google-flow-assets-projects-email) para trabajar en un proyecto distinto del propio del agente. - **¿Puedo recibir un webhook en vez de mantener un stream abierto?** Con useapi.net, sí. Pasa `replyUrl` en [POST /agent/chats](/docs/api-google-flow-v1/post-google-flow-agent-chats#callback), en la llamada de mensajes o en la de aprobación, y la API envía un `POST` con los mensajes, los archivos, el estado y cualquier aprobación pendiente del turno cuando termina. Los videos suelen llegar ahí todavía `queued`, así que obtén sus enlaces con GET o con los eventos `media` del stream. - **¿Cuáles son los límites?** Con useapi.net, un chat ejecuta un turno a la vez, una cuenta ejecuta como máximo 3 turnos al mismo tiempo, y un turno dura hasta 10 minutos, que es el límite del propio Google. Google también limita los mensajes al agente por cuenta y por día sin publicar el número, y la API responde `429` para esa cuenta hasta la medianoche UTC. Consulta [Límites](/docs/api-google-flow-v1/agent#limits). ### Conclusión Visita nuestro <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> servidor de Discord</a> o nuestro <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> canal de Telegram</a> para cualquier pregunta de soporte. Consulta nuestro [repositorio de GitHub](https://github.com/useapi/google-flow-api) con ejemplos de código, incluido el cliente de chat del agente en [`demo/`](https://github.com/useapi/google-flow-api/tree/main/demo). Un asistente de IA también puede chatear con Google Flow Agent por ti: el [servidor MCP de Google Flow](/docs/api-google-flow-v1/mcp) alojado funciona con Claude Code, Cursor y VS Code, en tu cuenta de Google Flow. ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-flow-agent-chat-id === Document URL: https://useapi.net/docs/articles/google-flow-agent-chat-id --- layout: default title: "Cara Chat dengan Google Flow Agent lewat Google Flow API" description: "Chat dengan Google Flow Agent dari kode lewat Google Flow API useapi.net: mulai chat, terima balasan lewat SSE, setujui pemakaian kredit, lalu ambil gambar dan videonya, dengan curl." keywords: [Google Flow Agent API, Google Flow Agent, Flow Agent API, Google Flow API, AI agent API, Server-Sent Events, SSE, approval, Nano Banana 2.1, Omni 1.1 Flash, MCP server, Claude Code, curl, API Google Flow Agent, API agen AI, streaming, tutorial bahasa Indonesia] image: https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-shot-2-nano-banana-2-1.jpg parent: Articles nav_exclude: true lang: id translation_key: google-flow-agent-chat date: 2026-10-17 last_modified: 2026-11-10 nav_order: 903 repo: https://github.com/useapi/google-flow-api --- ## Cara Chat dengan Google Flow Agent lewat Google Flow API {: .no_toc #how-to-chat-with-google-flow-agent-via-the-google-flow-api } 8 menit baca • 17 Oktober 2026 (10 November 2026) useapi.net adalah API pihak ketiga. Kami tidak berafiliasi dengan Google dan tidak disahkan oleh Google. ## Daftar isi {: .no_toc .text-delta #table-of-contents } ### Pendahuluan Google Flow API useapi.net membuat kode Anda bisa chat dengan Google Flow Agent, asisten kreatif yang ada di dalam [Google Flow](https://flow.google.com): mulai chat dengan satu `curl`, terima balasannya secara streaming, setujui apa yang ingin ia belanjakan, lalu unduh gambar dan video yang ia buat. Google hanya menyediakan [Flow Agent](https://support.google.com/labs/answer/17093911?hl=id) di dalam aplikasi web Google Flow, tanpa API publik (per November 2026). useapi.net adalah API [pihak ketiga](/docs/legal#affiliation--third-party-services), tidak berafiliasi dengan Google, dan chat berjalan di akun Google Flow Anda, gratis maupun berbayar. Chat dengan agen tidak memakan kredit, sedangkan gambar dan video yang ia buat dikenai harga Google Flow yang biasa. Panduan ini adalah satu kali eksekusi nyata, dari awal sampai akhir. Kami meminta agen membuat dua foto produk sebuah mug keramik dan satu video 6 detik tentang mug itu, menyetujui biayanya, mengambil hasilnya, lalu meminta revisi dan menolak revisi tersebut. Setiap respons di bawah berasal dari eksekusi itu, dipangkas dan dengan email akun diganti. Agen merencanakan pekerjaannya sendiri. Ia memilih alat dan model sesuai [pengaturan](#step-7-settings-for-approval-instructions-and-default-models) project, dan menyimpan seluruh percakapan di sisi Google, jadi sebuah chat bisa dilanjutkan berjam-jam atau berhari-hari kemudian dengan konteks lengkap. [Ikhtisar Agent](/docs/api-google-flow-v1/agent) membahas setiap aturan dan batasnya. ### Sebelum mulai Anda butuh [token API](/docs/start-here/setup-useapi) useapi.net dan akun Google yang terhubung lewat [Setup Google Flow](/docs/start-here/setup-google-flow). Agen berjalan di semua paket Google AI, termasuk akun gratis, dan apa yang bisa ia buat mengikuti paket akun, sama seperti [POST /images](/docs/api-google-flow-v1/post-google-flow-images) dan [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos). Setiap giliran memakai satu captcha, yang diselesaikan API dengan [penyedia captcha](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers) Anda atau kredit captcha gratis akun pertama Anda. Anda tidak perlu mengirim apa pun untuk itu. Langkah-langkahnya memakai `curl`, `jq`, dan tiga variabel shell: ```bash export USEAPI_TOKEN="user:12345-..." # token API useapi.net Anda export EMAIL="john@gmail.com" # akun Google Flow yang sudah terhubung API="https://api.useapi.net/v1/google-flow/agent" ``` Setiap panggilan di bawah juga ada di [koleksi Postman](https://www.postman.com/useapinet/useapi-net). ### Cara kerja sebuah chat Satu giliran (turn) adalah satu pesan dari Anda dan semua yang dilakukan agen untuk membalasnya. Sebuah chat berjalan satu giliran setiap kali: 1. [POST /agent/chats](/docs/api-google-flow-v1/post-google-flow-agent-chats) memulai chat dan menjawab `202` dengan sebuah `chatId`. 2. [GET /agent/chats/`chatId`/stream](/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId-stream) mengikuti agen secara langsung lewat Server-Sent Events. 3. Saat agen ingin memakai kredit, ia berhenti dan bertanya. [POST /agent/chats/`chatId`/approval](/docs/api-google-flow-v1/post-google-flow-agent-chats-chatId-approval) menjawabnya. 4. [POST /agent/chats/`chatId`/messages](/docs/api-google-flow-v1/post-google-flow-agent-chats-chatId-messages) mengirim pesan berikutnya. 5. [GET /agent/chats/`chatId`](/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId) membaca seluruh chat, dengan link media yang baru. ### Langkah 1: Mulai chat Kirim brief sebagai `message`. Panggilan kembali begitu Google menerima giliran, biasanya dalam beberapa detik dan bisa sampai sekitar 100 detik, jadi beri `curl` timeout 150 detik: ```bash curl -s --max-time 150 -X POST "$API/chats" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$EMAIL"'", "message": "Create two product shots of a matte sage-green ceramic coffee mug on a light oak table in soft morning window light, square format, with Nano Banana 2.1. Then make one 6 second video of the same mug with steam slowly rising from the coffee, with Omni 1.1 Flash." }' ``` Panggilan kami menjawab `202` dalam sekitar 10 detik: ```json { "chatId": "c-u12345-email:john@gmail.com-project:74262ac8-a54f-4ad7-80d7-3d44a4d6c6c1-chat:55023a0f-5e70-4545-bb4a-d878038dcf35-bot:google-flow", "email": "john@gmail.com", "turn": 1, "status": "running" } ``` `chatId` sudah memuat akun dan project, jadi panggilan berikutnya tidak perlu keduanya. Isinya mengandung `:` dan `@`, jadi encode sebagai URL di path. Simpan kedua bentuknya: ```bash CHATID="c-u12345-email:john@gmail.com-project:74262ac8-...-bot:google-flow" CHAT=$(jq -rn --arg v "$CHATID" '$v|@uri') ``` Tanpa `projectId`, chat berada di project agen milik akun itu sendiri, yang dibuat pada chat pertamanya dan diberi nama seperti `My Agents Work Fri, Oct 16`, sehingga pekerjaan agen terpisah dari media Google Flow Anda yang lain. Anda juga bisa melampirkan hingga 7 gambar, satu video, 5 suara, dan 7 karakter ke pesan mana pun dengan sintaks mention `@` yang sama seperti [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos), lihat [POST /agent/chats](/docs/api-google-flow-v1/post-google-flow-agent-chats#request-body). ### Langkah 2: Stream balasannya Buka stream dengan `-N` agar event tercetak begitu tiba. `EventSource` di browser tidak bisa mengirim header `Authorization`, jadi di aplikasi gunakan `fetch()` atau klien HTTP apa pun: ```bash curl -s -N "$API/chats/$CHAT/stream" \ -H "Authorization: Bearer $USEAPI_TOKEN" ``` Stream baru pertama-tama mengirim event `chat`, memutar ulang riwayat chat, lalu mengirim `replayed`. Semua yang datang setelah `replayed` adalah langsung. Di sini giliran pertama sudah selesai saat kami terhubung, jadi ia datang di pemutaran ulang. Agen menjelaskan rencananya, lalu meminta izin memakai 10 kredit untuk 2 gambar dan 1 video (`ui` dan field panjang lain dihilangkan): ``` event: chat data: {"chatId":"c-u12345-email:john@gmail.com-project:74262ac8-...-bot:google-flow","status":"waiting_approval","turns":1} id: 1:505e78d7-bd79-4938-b0ec-8117bdb933dc event: message data: {"id":"1:505e78d7-...","turn":1,"items":[{"kind":"text","text":"I'm going to generate two images of a matte sage-green ceramic coffee mug, then I'll create a 6-second video of the same mug with rising steam using Omni 1.1 Flash."}]} id: 1:00c21a03-a687-4173-9fd9-190fcdf2447b event: message data: {"id":"1:00c21a03-...","turn":1,"items":[{"kind":"tool_call","tool":"open_chat_panel","args":{"_synthetic":true}},{"kind":"tool_call","tool":"ask_for_permission","args":{"num_total":3,"total_cost":10,"num_videos":1,"num_images":2}}]} id: 1:approval event: approval data: {"turn":1,"cost":10,"images":2,"videos":1,"total":3} event: replayed data: {"turns":1} ``` Event yang perlu Anda tangani: | Event | Artinya | |---|---| | `message` | Satu pesan lengkap dari agen: teks, pemikiran, panggilan alat, dan hasil alat | | `approval` | Agen meminta izin sebelum memakai `cost` kredit Flow | | `turn` | Satu giliran selesai: `completed`, `waiting_approval`, atau `failed` dengan `error` | | `media` | Gambar atau video yang dibuat agen, atau perubahan statusnya, dengan `url` saat `completed` | `keepalive` datang setiap 15 detik. Satu stream mencakup seluruh chat lintas giliran, jadi biarkan tetap terbuka selagi Anda menyetujui dan mengirim pesan. Jika terputus, sambungkan ulang dengan `id` terakhir di header `Last-Event-ID` dan stream melanjutkan dari titik terakhir. Giliran tetap berjalan saat Anda menutup stream, jadi tidak ada yang hilang. ### Langkah 3: Setujui pemakaian kredit Dalam mode persetujuan `ask`, agen berhenti sebelum memakai apa pun. `status` chat menjadi `waiting_approval` dan event `approval` menunjukkan biayanya. Jawab dengan `approve`, `always`, atau `reject` dalam sekitar 4 menit: ```bash curl -s --max-time 150 -X POST "$API/chats/$CHAT/approval" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "decision": "approve" }' ``` Sejak Google mengubah Flow Agent pada 10 November 2026, jawaban melanjutkan giliran yang bertanya (di sini giliran 1, bukan giliran 2 yang baru), dan Google hanya menerimanya selama giliran itu masih terbuka, sekitar 4 menit setelah permintaan. Jawaban yang lebih lambat mendapat `409`: kirim ulang pesannya, atau atur project ke `approval: "auto"` di [langkah 7](#step-7-settings-for-approval-instructions-and-default-models) agar agen tidak pernah bertanya. Eksekusi di bawah direkam sebelum perubahan itu, jadi jawabannya memulai giliran 2, dan nama alatnya (`generate_video_from_text`) sekarang dilaporkan sebagai `generate_image` dan `generate_video`. Jawaban itu membuat agen bekerja lagi: ```json { "chatId": "c-u12345-email:john@gmail.com-project:74262ac8-...-bot:google-flow", "email": "john@gmail.com", "turn": 2, "status": "running" } ``` Di stream yang terbuka, giliran 2 memasukkan video ke antrean, membuat kedua gambar, dan selesai dalam sekitar 30 detik. `choices` dari agen (`Option 1`, `Option 2`) adalah ubin yang ditampilkan aplikasi web Google Flow untuk setiap hasil: ``` id: 2:5feb253e-0848-422a-bcb8-936995b3c0df event: message data: {"id":"2:5feb253e-...","turn":2,"items":[{"kind":"tool_result","tool":"generate_video_from_text","result":{"status":"queued","media_id":"5732c66d-a971-4cd0-92d2-508ef0aecc07","display_name":"Steam rising from coffee mug","model_key":"abra_t2v_6s","aspect_ratio":"VIDEO_ASPECT_RATIO_LANDSCAPE"}}]} id: 2:m:5732c66d-a971-4cd0-92d2-508ef0aecc07 event: media data: {"turn":2,"referenceId":"user:12345-email:6a6f...-video:5732c66d-a971-4cd0-92d2-508ef0aecc07","mediaId":"5732c66d-a971-4cd0-92d2-508ef0aecc07","type":"video","status":"queued","tool":"generate_video_from_text","model":"abra_t2v_6s","displayName":"Steam rising from coffee mug"} id: 2:m:377ecb33-ab2c-4bce-92d4-7bfcf53a9af2 event: media data: {"turn":2,"referenceId":"user:12345-email:6a6f...-image:377ecb33-ab2c-4bce-92d4-7bfcf53a9af2","mediaId":"377ecb33-ab2c-4bce-92d4-7bfcf53a9af2","type":"image","status":"completed","tool":"generate_image","displayName":"Ceramic coffee mug on table","url":"https://flow-content.google/image/377ecb33-...?Expires=...&Signature=..."} id: 2:4e37b051-c49c-4331-bc0c-06ccc539b950 event: message data: {"id":"2:4e37b051-...","turn":2,"items":[{"kind":"text","text":"I've generated your two product shots. Your 6-second video has been scheduled and is waiting in the queue due to high demand. Feel free to check back in a few minutes."}]} id: 2:end event: turn data: {"turn":2,"status":"completed"} ``` `always` menyetujui sekaligus mengubah project ke mode `auto`, jadi agen berhenti bertanya di setiap chat dalam project itu. `reject` menolak, seperti di [langkah 5](#step-5-continue-or-revise). Selama sebuah permintaan menunggu, pesan baru mendapat `409`: jawab dulu permintaannya. ### Langkah 4: Ambil medianya Gambar sudah siap saat giliran selesai. Video biasanya selesai satu atau dua menit kemudian, dan saat itu stream mengirim event `media` kedua untuk video tersebut. Video kami datang kurang dari satu menit setelah giliran selesai: ``` id: 2:m:5732c66d-a971-4cd0-92d2-508ef0aecc07 event: media data: {"turn":2,"referenceId":"user:12345-email:6a6f...-video:5732c66d-a971-4cd0-92d2-508ef0aecc07","mediaId":"5732c66d-a971-4cd0-92d2-508ef0aecc07","type":"video","status":"completed","tool":"generate_video_from_text","model":"abra_t2v_6s","displayName":"Steam rising from coffee mug","url":"https://flow-content.google/video/5732c66d-...?Expires=...&Signature=...","durationSec":6} ``` Unduh setiap `url` selagi masih baru: ```bash curl -s -L -o mug-steam.mp4 "https://flow-content.google/video/5732c66d-...?Expires=...&Signature=..." ``` Link mengarah ke Google dan kedaluwarsa sekitar 6 jam setelah diterbitkan. Baca chat lagi dengan [GET /agent/chats/`chatId`](#step-6-read-list-rename-and-delete-chats) untuk link baru, atau ambil link satu item dari [GET /assets/`mediaGenerationId`](/docs/api-google-flow-v1/get-google-flow-assets-mediagenerationid) dengan `referenceId`-nya. `referenceId` juga bisa dipakai sebagai `referenceImage_N` atau `referenceVideo_1` di [POST /images](/docs/api-google-flow-v1/post-google-flow-images), [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos), dan pesan berikutnya ke agen. Kedua gambar dan video 1280×720 ada di [Contoh](#examples). Eksekusi ini memakai 10 kredit: dua gambar Nano Banana 2.1 seharga 0 di paket akun ini, dan video Omni 1.1 Flash 6 detik seharga 10. ### Langkah 5: Lanjutkan atau revisi Kirim pesan berikutnya ke chat yang sama. Google menyimpan percakapannya, jadi agen tahu video mana yang dimaksud "video itu": ```bash curl -s --max-time 150 -X POST "$API/chats/$CHAT/messages" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "message": "Nice. Revise the video: make it 8 seconds, with a slow camera push-in toward the mug while the steam rises." }' ``` Jawabannya `202` dengan `"turn": 3`, dan agen meminta izin lagi, kali ini 12 kredit: ``` id: 3:approval event: approval data: {"turn":3,"cost":12,"images":0,"videos":1,"total":1} id: 3:end event: turn data: {"turn":3,"status":"waiting_approval"} ``` Kami sudah punya videonya, jadi kami menolak: ```bash curl -s --max-time 150 -X POST "$API/chats/$CHAT/approval" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "decision": "reject" }' ``` Giliran 4 selesai dengan sebuah balasan tanpa gambar atau video baru, dan tidak ada kredit yang terpakai: ``` id: 4:91e06fb7-ba5b-4e32-b2a6-ce210be491ba event: message data: {"id":"4:91e06fb7-...","turn":4,"items":[{"kind":"text","text":"I've cancelled that generation. Are there any changes you'd like to make to the prompt or concept before we try again?"}]} id: 4:end event: turn data: {"turn":4,"status":"completed"} ``` Mengirim pesan saat giliran berjalan akan dijawab `409`, jadi tunggu event `turn` dulu. Untuk memilih salah satu pilihan agen, kirim teks pilihan itu sebagai pesan berikutnya, seperti yang dilakukan aplikasi web Google Flow. ### Langkah 6: Baca, daftar, ganti nama, dan hapus chat Baca seluruh chat dari Google kapan saja. Setiap giliran memuat pesan Anda, semua yang dilakukan agen, dan media dengan link baru: ```bash curl -s "$API/chats/$CHAT" -H "Authorization: Bearer $USEAPI_TOKEN" ``` Chat kami setelah empat giliran (item `agent` dan `media` dipangkas, `ui` dihilangkan): ```json { "chatId": "c-u12345-email:john@gmail.com-project:74262ac8-...-bot:google-flow", "email": "john@gmail.com", "projectId": "74262ac8-a54f-4ad7-80d7-3d44a4d6c6c1", "title": "Sage Green Ceramic Mug Concept", "created": "2026-10-18T00:47:54.000Z", "updated": "2026-10-18T00:50:47.236Z", "status": "idle", "pendingApproval": null, "lastError": null, "turns": [ { "turn": 1, "message": { "text": "Create two product shots of a matte sage-green ceramic coffee mug ...", "references": [] }, "agent": [ { "kind": "text", "text": "I'm going to generate two images of a matte sage-green ceramic coffee mug, then I'll create a 6-second video ..." }, { "kind": "tool_call", "tool": "ask_for_permission", "args": { "num_total": 3, "total_cost": 10, "num_videos": 1, "num_images": 2 } } ], "media": [] }, { "turn": 2, "message": { "text": "Approve", "references": [] }, "agent": [ { "kind": "tool_call", "tool": "generate_video_from_text", "args": { "duration": 6, "aspect_ratio": "16:9", "model_display_name": "Omni 1.1 Flash", "prompt": "Cinematic product video of a matte sage-green ceramic coffee mug ..." } }, { "kind": "tool_call", "tool": "generate_image", "args": { "aspect_ratio": "1:1", "prompt": "A professional product shot of a matte sage-green ceramic coffee mug ..." } }, { "kind": "text", "text": "I've generated your two product shots. Your 6-second video has been scheduled ..." } ], "media": [ { "referenceId": "user:12345-email:6a6f...-video:5732c66d-...", "type": "video", "status": "completed", "model": "abra_t2v_6s", "displayName": "Steam rising from coffee mug", "url": "https://flow-content.google/video/5732c66d-...", "durationSec": 6 }, { "referenceId": "user:12345-email:6a6f...-image:377ecb33-...", "type": "image", "status": "completed", "displayName": "Ceramic coffee mug on table", "url": "https://flow-content.google/image/377ecb33-..." }, { "referenceId": "user:12345-email:6a6f...-image:a2d3cd0c-...", "type": "image", "status": "completed", "displayName": "Ceramic coffee mug on wooden sur…", "url": "https://flow-content.google/image/a2d3cd0c-..." } ] }, { "turn": 3, "message": { "text": "Nice. Revise the video: make it 8 seconds, ...", "references": [] }, "agent": ["..."], "media": [] }, { "turn": 4, "message": { "text": "Reject", "references": [] }, "agent": [{ "kind": "text", "text": "I've cancelled that generation. Are there any changes you'd like to make to the prompt or concept before we try again?" }], "media": [] } ] } ``` Google memberi judul chat sendiri. `status` bernilai `idle` saat tidak ada yang berjalan, dan `pendingApproval` menyimpan biaya selama agen menunggu. Tambahkan `?media=false` untuk pembacaan lebih cepat tanpa penyegaran link. Daftar chat sebuah akun, dengan aktivitas terbaru di atas. Daftarnya berasal dari Google, jadi juga memuat chat yang dimulai di aplikasi web Google Flow dalam project yang sama, dan inilah cara menemukan `chatId` yang hilang: ```bash curl -s "$API/chats?email=$EMAIL" -H "Authorization: Bearer $USEAPI_TOKEN" ``` Ganti nama chat. Judul baru juga muncul di aplikasi web Google Flow: ```bash curl -s -X PATCH "$API/chats/$CHAT" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "title": "Sage mug product shoot" }' ``` ```json { "chatId": "c-u12345-email:john@gmail.com-project:74262ac8-...-bot:google-flow", "title": "Sage mug product shoot" } ``` Daftarnya kemudian menjadi: ```json { "chats": [ { "chatId": "c-u12345-email:john@gmail.com-project:74262ac8-...-chat:55023a0f-...-bot:google-flow", "email": "john@gmail.com", "title": "Sage mug product shoot", "created": "2026-10-18T00:47:54.000Z", "updated": "2026-10-18T00:51:01.773Z", "running": false }, { "chatId": "c-u12345-email:john@gmail.com-project:74262ac8-...-chat:1d9d42ed-...-bot:google-flow", "email": "john@gmail.com", "title": "Stylish Female Character Action Sequence", "created": "2026-10-17T03:50:34.000Z", "updated": "2026-10-17T04:57:26.375Z", "running": false } ] } ``` Hapus percakapan sebuah chat. Jawabannya `204` tanpa body, chat hilang dari daftar dan dari aplikasi web Google Flow, sedangkan gambar dan video yang dibuatnya tetap ada di project: ```bash curl -s -X DELETE "$API/chats/$CHAT" -H "Authorization: Bearer $USEAPI_TOKEN" ``` Ganti nama dan hapus menjawab `409` selama giliran berjalan. ### Langkah 7: Pengaturan persetujuan, instruksi, dan model default Setiap project Google Flow punya pengaturan agen, sama seperti panel agen di aplikasi web Google Flow. [GET /agent/settings](/docs/api-google-flow-v1/get-google-flow-agent-settings) membacanya, sekaligus mendaftar model gambar dan video yang dimiliki paket Google akun itu, beserta biaya satu gambar atau satu video di paket tersebut: ```bash curl -s "$API/settings?email=$EMAIL" -H "Authorization: Bearer $USEAPI_TOKEN" ``` [PUT /agent/settings](/docs/api-google-flow-v1/put-google-flow-agent-settings) hanya mengubah field yang Anda kirim. Sebelum eksekusi, kami mengatur mode `ask` dan default-nya: ```bash curl -s -X PUT "$API/settings" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$EMAIL"'", "approval": "ask", "imageDefaults": { "model": "nano-banana-2", "aspectRatio": "1:1", "count": 2 }, "videoDefaults": { "model": "omni-flash", "aspectRatio": "16:9", "count": 1 } }' ``` Responsnya adalah pengaturan project setelah perubahan: ```json { "projectId": "74262ac8-a54f-4ad7-80d7-3d44a4d6c6c1", "approval": "ask", "instructions": [], "imageDefaults": { "model": "nano-banana-2", "aspectRatio": "1:1", "count": 2 }, "videoDefaults": { "model": "omni-flash", "aspectRatio": "16:9", "count": 1 }, "models": { "image": [ { "model": "nano-banana-pro", "label": "Nano Banana Pro", "credits": 0 }, { "model": "nano-banana-2-lite", "label": "Nano Banana 2 Lite", "credits": 0 }, { "model": "nano-banana-2", "label": "Nano Banana 2.1", "credits": 0 } ], "video": [ { "model": "omni-flash", "label": "Omni 1.1 Flash", "credits": 4 }, { "model": "veo-3.1-lite", "label": "Veo 3.1 - Lite", "credits": 5 }, { "model": "veo-3.1-fast", "label": "Veo 3.1 - Fast", "credits": 10 }, { "model": "veo-3.1-quality", "label": "Veo 3.1 - Quality", "credits": 100 } ] } } ``` `credits` adalah biaya terendah satu gambar atau satu video di paket akun, jadi video yang lebih panjang atau beresolusi lebih tinggi lebih mahal: video Omni 1.1 Flash 6 detik 720p kami seharga 10, dan revisi 8 detik akan seharga 12. Paket Anda bisa menampilkan angka berbeda. Field pengaturannya: - `approval`: `ask` (agen berhenti dan menunjukkan biaya) atau `auto` (ia memakai kredit tanpa bertanya). - `instructions`: hingga 3 instruksi tetap yang diikuti agen di setiap chat dalam project, masing-masing dengan gambar referensi opsional. Array ini menggantikan instruksi project, jadi kirim daftar lengkapnya. - `imageDefaults` dan `videoDefaults`: model, rasio aspek, dan jumlah yang dipakai agen saat pesan tidak menyebut lain, dipilih dari `models`. Pengaturan berlaku untuk setiap chat dalam project, termasuk chat di aplikasi web Google Flow. ### Hal yang sama dari asisten AI [Server MCP Google Flow](/docs/api-google-flow-v1/mcp) yang di-host memberi Claude Code, Cursor, VS Code, dan klien MCP lain chat yang sama dalam bentuk 12 alat, tanpa perlu instalasi apa pun. Di Claude Code: ```bash claude mcp add --transport http useapi-google-flow https://api.useapi.net/v1/google-flow/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` Lalu minta asisten membuat foto mug itu dengan bahasa biasa. Asisten mengirim brief dengan `flow_agent_chat` dan menjawab permintaan agen untuk memakai kredit dengan `flow_agent_answer_approval`. Server ini terdaftar di MCP Registry resmi sebagai `net.useapi/google-flow`. Untuk melihat klien chat lengkap terlebih dulu, buka [demo langsung](/demos/google-flow/). Tempel token API Anda, pilih akun, dan chat dengan agen, dengan gambar dan videonya tampil di dalam chat, lampiran, kartu persetujuan, dan pengaturan. Kode sumbernya lima file kecil tanpa langkah build, ada di GitHub di [google-flow-api/demo](https://github.com/useapi/google-flow-api/tree/main/demo), dan halaman [Agent Live Demo](/docs/api-google-flow-v1/agent-demo) memetakan setiap fitur ke panggilan API-nya. ### Contoh Hasil eksekusi ini, tanpa diedit. Prompt-nya ditulis sendiri oleh agen berdasarkan brief kami. ###### Nano Banana 2.1 » dua foto produk mug hijau sage (giliran 2) {: .no_toc #nano-banana-21--two-product-shots-of-the-sage-green-mug-turn-2 } <div style="display: flex; gap: 2%; flex-wrap: wrap"> <figure style="margin: 0; width: 49%"><a href="https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-shot-1-nano-banana-2-1.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-shot-1-nano-banana-2-1.jpg" alt="Hasil Google Flow Agent: mug keramik hijau sage doff di atas meja kayu ek terang dalam cahaya pagi yang lembut, dibuat dengan Nano Banana 2.1" style="width: 100%" loading="lazy"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">Option 1, "Ceramic coffee mug on table"</figcaption></figure> <figure style="margin: 0; width: 49%"><a href="https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-shot-2-nano-banana-2-1.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-shot-2-nano-banana-2-1.jpg" alt="Hasil Google Flow Agent: close-up mug hijau sage berisi kopi, sendok kuningan, dan buku terbuka di bawah sinar matahari pagi, dibuat dengan Nano Banana 2.1" style="width: 100%" loading="lazy"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">Option 2, close-up</figcaption></figure> </div> Keduanya JPEG 1024×1024, 0 kredit di paket akun ini. ###### Omni 1.1 Flash » 6 detik uap naik dari mug (giliran 2) {: .no_toc #omni-11-flash--6-seconds-of-steam-rising-from-the-mug-turn-2 } <video poster="https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-steam-omni-1-1-flash-6s-poster.jpg" src="https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-steam-omni-1-1-flash-6s.mp4" style="width: 100%; aspect-ratio: 16/9; max-width: 720px" controls type="video/mp4" preload="metadata"></video> 1280×720 dengan suara, 6 detik, 10 kredit. Tutorial terkait: [video Veo 3.1 lewat Google Flow API](/docs/articles/google-flow-bash-id), [video dengan audio bawaan di Omni Flash](/docs/articles/omni-flash-bash-id), dan [gambar Nano Banana lewat Google Flow API](/docs/articles/google-flow-images-bash-id). ### Pertanyaan yang sering diajukan - **Apakah ada API Google Flow Agent?** Lewat useapi.net, ada: [Agent API](/docs/api-google-flow-v1/agent) memulai chat, men-stream balasan lewat Server-Sent Events, menjawab persetujuan, dan mengembalikan gambar serta video, di setiap langganan Google AI, termasuk akun gratis. Google hanya menyediakan [Flow Agent](https://support.google.com/labs/answer/17093911?hl=id) di dalam aplikasi web Google Flow, tanpa API publik sendiri (per November 2026). - **Berapa biaya chat dengan Google Flow Agent?** Lewat useapi.net, chat tidak memakan kredit Flow, dan apa yang dibuat agen dikenai harga Google Flow yang biasa, yang ditampilkan mode `ask` sebelum ada yang terpakai. Video Omni 1.1 Flash 6 detik 720p di eksekusi ini seharga $0,08 di Google AI Ultra $199,99, dibanding $0,61 di [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) resmi (per November 2026). - **Apakah chat yang dimulai di aplikasi web Google Flow muncul di API?** Lewat useapi.net, ya, jika berada di project yang sama. [GET /agent/chats](/docs/api-google-flow-v1/get-google-flow-agent-chats) mendaftarnya, dan setiap endpoint di atas bisa dipakai untuknya. Chat yang dimulai lewat API juga muncul di aplikasi web. Kirim `projectId` dari [GET /assets/projects/`email`](/docs/api-google-flow-v1/get-google-flow-assets-projects-email) untuk bekerja di project selain project milik agen. - **Bisakah saya memakai webhook alih-alih membiarkan stream terbuka?** Lewat useapi.net, bisa. Kirim `replyUrl` ke [POST /agent/chats](/docs/api-google-flow-v1/post-google-flow-agent-chats#callback), panggilan pesan, atau panggilan persetujuan, dan API mengirim satu `POST` berisi pesan, media, status, dan persetujuan yang tertunda dari giliran itu saat giliran selesai. Video biasanya tiba di sana masih `queued`, jadi ambil link-nya lewat GET atau event `media` di stream. - **Apa saja batasnya?** Lewat useapi.net, satu chat berjalan satu giliran setiap kali, satu akun menjalankan paling banyak 3 giliran sekaligus, dan satu giliran berlangsung hingga 10 menit, yang merupakan batas Google sendiri. Google juga membatasi pesan agen per akun per hari tanpa memublikasikan angkanya, dan API menjawab `429` untuk akun itu sampai tengah malam UTC. Lihat [Batas](/docs/api-google-flow-v1/agent#limits). ### Kesimpulan Kunjungi <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Server Discord</a> atau <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Channel Telegram</a> kami untuk pertanyaan dan masalah dukungan. Lihat [repo GitHub](https://github.com/useapi/google-flow-api) kami berisi contoh kode, termasuk klien chat agen di [`demo/`](https://github.com/useapi/google-flow-api/tree/main/demo). Asisten AI juga bisa chat dengan Google Flow Agent untuk Anda: [server MCP Google Flow](/docs/api-google-flow-v1/mcp) yang di-host bekerja dengan Claude Code, Cursor, dan VS Code, di akun Google Flow Anda. ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-flow-agent-chat-ja === Document URL: https://useapi.net/docs/articles/google-flow-agent-chat-ja --- layout: default title: "Google Flow API で Google Flow Agent とチャットする方法" description: "useapi.net の Google Flow API でコードから Google Flow Agent とチャットする方法。チャットの開始、SSE での返信のストリーミング、クレジット消費の承認、画像と動画の取得を curl で行います。" keywords: [Google Flow Agent API, Google Flow Agent, Flow Agent API, Google Flow API, AI agent API, Server-Sent Events, SSE, approval, Nano Banana 2.1, Omni 1.1 Flash, MCP server, Claude Code, curl, Google Flow Agent 使い方, AI エージェント API, ストリーミング, 日本語チュートリアル, Japanese tutorial] image: https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-shot-2-nano-banana-2-1.jpg parent: Articles nav_exclude: true lang: ja translation_key: google-flow-agent-chat date: 2026-10-17 last_modified: 2026-11-10 nav_order: 903 repo: https://github.com/useapi/google-flow-api --- ## Google Flow API で Google Flow Agent とチャットする方法 {: .no_toc #how-to-chat-with-google-flow-agent-via-the-google-flow-api } 8分で読めます • 2026年10月17日(2026年11月10日更新) useapi.net はサードパーティの API です。Google とは提携しておらず、Google の承認も受けていません。 ## 目次 {: .no_toc .text-delta #table-of-contents } ### はじめに useapi.net の Google Flow API を使うと、[Google Flow](https://flow.google.com) に組み込まれたクリエイティブアシスタント Google Flow Agent とコードからチャットできます。`curl` 1回でチャットを始め、返信をストリーミングで受け取り、エージェントが使いたいクレジットを承認し、作られた画像と動画をダウンロードします。Google は [Flow Agent](https://support.google.com/labs/answer/17093911?hl=ja) を Google Flow のウェブアプリの中でしか提供しておらず、公開 API はありません(2026年11月時点)。useapi.net は Google と提携していない[サードパーティ](/docs/legal#affiliation--third-party-services)の API で、チャットは無料・有料を問わずお使いの Google Flow アカウントで動きます。エージェントとのチャット自体はクレジットを使わず、エージェントが作る画像と動画には Google Flow の通常の料金がかかります。 このガイドは、実際の1回の実行を最初から最後まで追ったものです。セラミックのコーヒーマグの商品写真2枚と、そのマグの6秒の動画をエージェントに頼み、消費を承認してメディアを受け取り、続けて修正を頼んで、その修正は却下しました。以下のレスポンスはすべてその実行のもので、一部を省略し、アカウントのメールアドレスを置き換えています。 作業の計画はエージェント自身が立てます。プロジェクトの[設定](#step-7-settings-for-approval-instructions-and-default-models)に沿ってツールとモデルを選び、会話全体を Google 側に保持するので、数時間後や数日後でも文脈をすべて保ったままチャットを続けられます。ルールと制限はすべて [Agent の概要](/docs/api-google-flow-v1/agent)にまとめています。 ### 始める前に useapi.net の [API トークン](/docs/start-here/setup-useapi)と、[Google Flow のセットアップ](/docs/start-here/setup-google-flow)で接続した Google アカウントが必要です。エージェントは無料アカウントを含むすべての Google AI のプランで使え、生成できるものはアカウントのプランで決まります。[POST /images](/docs/api-google-flow-v1/post-google-flow-images) や [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) と同じです。 ターンごとに CAPTCHA を1回使います。API がお使いの [CAPTCHA プロバイダー](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers)、または最初のアカウントに付く無料の CAPTCHA クレジットで解決するので、そのために何かを送る必要はありません。 以下の手順では `curl`、`jq` と3つのシェル変数を使います。 ```bash export USEAPI_TOKEN="user:12345-..." # useapi.net の API トークン export EMAIL="john@gmail.com" # 接続済みの Google Flow アカウント API="https://api.useapi.net/v1/google-flow/agent" ``` 以下の呼び出しはすべて [Postman コレクション](https://www.postman.com/useapinet/useapi-net)にもあります。 ### チャットの流れ ターンとは、あなたからのメッセージ1つと、それに応えてエージェントが行うすべてのことです。チャットは1ターンずつ進みます。 1. [POST /agent/chats](/docs/api-google-flow-v1/post-google-flow-agent-chats) でチャットを始めると、`202` と `chatId` が返ります。 2. [GET /agent/chats/`chatId`/stream](/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId-stream) で、エージェントの動きを Server-Sent Events でリアルタイムに追います。 3. エージェントはクレジットを使う前に止まって確認を求めます。[POST /agent/chats/`chatId`/approval](/docs/api-google-flow-v1/post-google-flow-agent-chats-chatId-approval) で答えます。 4. [POST /agent/chats/`chatId`/messages](/docs/api-google-flow-v1/post-google-flow-agent-chats-chatId-messages) で次のメッセージを送ります。 5. [GET /agent/chats/`chatId`](/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId) でチャット全体を、新しいメディアのリンク付きで読みます。 ### ステップ1:チャットを始める 依頼内容を `message` として送ります。呼び出しは Google がターンを受け付けた時点で返ります。普通は数秒ですが最大で約100秒かかることがあるので、`curl` には150秒のタイムアウトを付けます。 ```bash curl -s --max-time 150 -X POST "$API/chats" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$EMAIL"'", "message": "Create two product shots of a matte sage-green ceramic coffee mug on a light oak table in soft morning window light, square format, with Nano Banana 2.1. Then make one 6 second video of the same mug with steam slowly rising from the coffee, with Omni 1.1 Flash." }' ``` 今回は約10秒で `202` が返りました。 ```json { "chatId": "c-u12345-email:john@gmail.com-project:74262ac8-a54f-4ad7-80d7-3d44a4d6c6c1-chat:55023a0f-5e70-4545-bb4a-d878038dcf35-bot:google-flow", "email": "john@gmail.com", "turn": 1, "status": "running" } ``` `chatId` にはアカウントとプロジェクトが含まれるので、以降の呼び出しではどちらも不要です。`:` と `@` を含むため、パスに入れるときは URL エンコードします。両方の形を保存しておきます。 ```bash CHATID="c-u12345-email:john@gmail.com-project:74262ac8-...-bot:google-flow" CHAT=$(jq -rn --arg v "$CHATID" '$v|@uri') ``` `projectId` を省くと、チャットはアカウント自身のエージェント用プロジェクトに入ります。このプロジェクトは最初のチャットで作られ、`My Agents Work Fri, Oct 16` のような名前が付き、エージェントの作業を Google Flow の他のメディアと分けておけます。どのメッセージにも、[POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) と同じ `@` メンションの書き方で、画像を最大7枚、動画1本、音声5つ、キャラクター7人まで添付できます。詳しくは [POST /agent/chats](/docs/api-google-flow-v1/post-google-flow-agent-chats#request-body) をご覧ください。 ### ステップ2:返信をストリーミングで受け取る イベントが届いた順に表示されるよう、`-N` を付けてストリームを開きます。ブラウザーの `EventSource` は `Authorization` ヘッダーを送れないので、アプリでは `fetch()` か任意の HTTP クライアントを使ってください。 ```bash curl -s -N "$API/chats/$CHAT/stream" \ -H "Authorization: Bearer $USEAPI_TOKEN" ``` 新しいストリームは、まず `chat` イベントを送り、チャットの履歴を再生してから `replayed` を送ります。`replayed` より後はすべてリアルタイムです。今回は接続した時点で最初のターンがすでに終わっていたので、再生の中に出てきました。エージェントは計画を述べたあと、画像2枚と動画1本に10クレジットを使う許可を求めました(`ui` などの長いフィールドは省略)。 ``` event: chat data: {"chatId":"c-u12345-email:john@gmail.com-project:74262ac8-...-bot:google-flow","status":"waiting_approval","turns":1} id: 1:505e78d7-bd79-4938-b0ec-8117bdb933dc event: message data: {"id":"1:505e78d7-...","turn":1,"items":[{"kind":"text","text":"I'm going to generate two images of a matte sage-green ceramic coffee mug, then I'll create a 6-second video of the same mug with rising steam using Omni 1.1 Flash."}]} id: 1:00c21a03-a687-4173-9fd9-190fcdf2447b event: message data: {"id":"1:00c21a03-...","turn":1,"items":[{"kind":"tool_call","tool":"open_chat_panel","args":{"_synthetic":true}},{"kind":"tool_call","tool":"ask_for_permission","args":{"num_total":3,"total_cost":10,"num_videos":1,"num_images":2}}]} id: 1:approval event: approval data: {"turn":1,"cost":10,"images":2,"videos":1,"total":3} event: replayed data: {"turns":1} ``` 対応が必要なイベント: | イベント | 意味 | |---|---| | `message` | エージェントの完結したメッセージ1つ:テキスト、思考、ツール呼び出し、ツールの結果 | | `approval` | エージェントが Flow クレジットを `cost` だけ使う前に許可を求めている | | `turn` | ターンの終了:`completed`、`waiting_approval`、または `error` 付きの `failed` | | `media` | エージェントが作った画像か動画、またはその状態の変化。`completed` になると `url` 付き | `keepalive` は15秒ごとに届きます。1つのストリームでターンをまたいでチャット全体を追えるので、承認やメッセージ送信の間も開いたままにしておきます。切れた場合は、最後の `id` を `Last-Event-ID` ヘッダーに入れて再接続すれば、続きから受け取れます。ストリームを閉じてもターンは動き続けるので、何も失われません。 ### ステップ3:消費を承認する `ask` の承認モードでは、エージェントは何かを使う前に止まります。チャットの `status` は `waiting_approval` になり、`approval` イベントに費用が出ます。約4分以内に `approve`、`always`、`reject` のいずれかで答えます。 ```bash curl -s --max-time 150 -X POST "$API/chats/$CHAT/approval" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "decision": "approve" }' ``` 2026年11月10日に Google が Flow Agent を変更して以来、答えは確認を求めたターンの続きになり(ここではターン1で、新しいターン2ではありません)、Google はそのターンがまだ開いている間、つまり確認から約4分以内しか受け付けません。それより遅い答えは `409` になります。メッセージを送り直すか、[ステップ7](#step-7-settings-for-approval-instructions-and-default-models)でプロジェクトを `approval: "auto"` にして、エージェントが確認しないようにしてください。以下の実行はこの変更の前に記録したもので、答えによってターン2が始まっています。また、ツール名(`generate_video_from_text`)は現在 `generate_image` と `generate_video` として返されます。 答えるとエージェントが作業を再開します。 ```json { "chatId": "c-u12345-email:john@gmail.com-project:74262ac8-...-bot:google-flow", "email": "john@gmail.com", "turn": 2, "status": "running" } ``` 開いたストリームでは、ターン2が動画をキューに入れ、画像を2枚作り、約30秒以内に終わりました。エージェントの `choices`(`Option 1`、`Option 2`)は、Google Flow のウェブアプリが結果ごとに表示するタイルです。 ``` id: 2:5feb253e-0848-422a-bcb8-936995b3c0df event: message data: {"id":"2:5feb253e-...","turn":2,"items":[{"kind":"tool_result","tool":"generate_video_from_text","result":{"status":"queued","media_id":"5732c66d-a971-4cd0-92d2-508ef0aecc07","display_name":"Steam rising from coffee mug","model_key":"abra_t2v_6s","aspect_ratio":"VIDEO_ASPECT_RATIO_LANDSCAPE"}}]} id: 2:m:5732c66d-a971-4cd0-92d2-508ef0aecc07 event: media data: {"turn":2,"referenceId":"user:12345-email:6a6f...-video:5732c66d-a971-4cd0-92d2-508ef0aecc07","mediaId":"5732c66d-a971-4cd0-92d2-508ef0aecc07","type":"video","status":"queued","tool":"generate_video_from_text","model":"abra_t2v_6s","displayName":"Steam rising from coffee mug"} id: 2:m:377ecb33-ab2c-4bce-92d4-7bfcf53a9af2 event: media data: {"turn":2,"referenceId":"user:12345-email:6a6f...-image:377ecb33-ab2c-4bce-92d4-7bfcf53a9af2","mediaId":"377ecb33-ab2c-4bce-92d4-7bfcf53a9af2","type":"image","status":"completed","tool":"generate_image","displayName":"Ceramic coffee mug on table","url":"https://flow-content.google/image/377ecb33-...?Expires=...&Signature=..."} id: 2:4e37b051-c49c-4331-bc0c-06ccc539b950 event: message data: {"id":"2:4e37b051-...","turn":2,"items":[{"kind":"text","text":"I've generated your two product shots. Your 6-second video has been scheduled and is waiting in the queue due to high demand. Feel free to check back in a few minutes."}]} id: 2:end event: turn data: {"turn":2,"status":"completed"} ``` `always` は承認したうえでプロジェクトを `auto` モードに切り替えるので、そのプロジェクトのどのチャットでもエージェントは確認しなくなります。`reject` は却下で、[ステップ5](#step-5-continue-or-revise)で使っています。確認を待っている間に新しいメッセージを送ると `409` になります。先に確認に答えてください。 ### ステップ4:メディアを受け取る 画像はターンが終わった時点でできあがっています。動画は普通その1〜2分後に完成し、完成するとストリームが動画の2つ目の `media` イベントを送ります。今回はターンの終了から1分足らずで届きました。 ``` id: 2:m:5732c66d-a971-4cd0-92d2-508ef0aecc07 event: media data: {"turn":2,"referenceId":"user:12345-email:6a6f...-video:5732c66d-a971-4cd0-92d2-508ef0aecc07","mediaId":"5732c66d-a971-4cd0-92d2-508ef0aecc07","type":"video","status":"completed","tool":"generate_video_from_text","model":"abra_t2v_6s","displayName":"Steam rising from coffee mug","url":"https://flow-content.google/video/5732c66d-...?Expires=...&Signature=...","durationSec":6} ``` リンクが新しいうちに、各 `url` をダウンロードします。 ```bash curl -s -L -o mug-steam.mp4 "https://flow-content.google/video/5732c66d-...?Expires=...&Signature=..." ``` リンクは Google を指していて、発行から約6時間で期限が切れます。新しいリンクは [GET /agent/chats/`chatId`](#step-6-read-list-rename-and-delete-chats) でチャットを読み直すか、`referenceId` を使って [GET /assets/`mediaGenerationId`](/docs/api-google-flow-v1/get-google-flow-assets-mediagenerationid) で1件ずつ取得します。`referenceId` は、[POST /images](/docs/api-google-flow-v1/post-google-flow-images)、[POST /videos](/docs/api-google-flow-v1/post-google-flow-videos)、次のエージェントへのメッセージで `referenceImage_N` や `referenceVideo_1` としても使えます。画像2枚と 1280×720 の動画は[例](#examples)にあります。 この実行で使ったのは10クレジットです。Nano Banana 2.1 の画像2枚はこのアカウントのプランでは0クレジット、6秒の Omni 1.1 Flash の動画が10クレジットでした。 ### ステップ5:続ける、または修正する 次のメッセージを同じチャットに送ります。Google が会話を保持しているので、エージェントは「その動画」がどれかを分かっています。 ```bash curl -s --max-time 150 -X POST "$API/chats/$CHAT/messages" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "message": "Nice. Revise the video: make it 8 seconds, with a slow camera push-in toward the mug while the steam rises." }' ``` `"turn": 3` で `202` が返り、エージェントは今度は12クレジットの許可を求めました。 ``` id: 3:approval event: approval data: {"turn":3,"cost":12,"images":0,"videos":1,"total":1} id: 3:end event: turn data: {"turn":3,"status":"waiting_approval"} ``` 動画はもう手元にあったので、却下しました。 ```bash curl -s --max-time 150 -X POST "$API/chats/$CHAT/approval" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "decision": "reject" }' ``` ターン4は返信だけで終わり、新しい画像や動画はなく、クレジットも使われませんでした。 ``` id: 4:91e06fb7-ba5b-4e32-b2a6-ce210be491ba event: message data: {"id":"4:91e06fb7-...","turn":4,"items":[{"kind":"text","text":"I've cancelled that generation. Are there any changes you'd like to make to the prompt or concept before we try again?"}]} id: 4:end event: turn data: {"turn":4,"status":"completed"} ``` ターンの実行中にメッセージを送ると `409` になるので、先に `turn` イベントを待ってください。エージェントの選択肢から1つを選ぶには、Google Flow のウェブアプリと同じように、その選択肢のテキストを次のメッセージとして送ります。 ### ステップ6:チャットの読み取り、一覧、名前の変更、削除 チャット全体はいつでも Google から読めます。各ターンには、あなたのメッセージ、エージェントが行ったすべてのこと、新しいリンク付きのメディアが入っています。 ```bash curl -s "$API/chats/$CHAT" -H "Authorization: Bearer $USEAPI_TOKEN" ``` 4ターン後のチャット(`agent` の項目と `media` は省略、`ui` は除外): ```json { "chatId": "c-u12345-email:john@gmail.com-project:74262ac8-...-bot:google-flow", "email": "john@gmail.com", "projectId": "74262ac8-a54f-4ad7-80d7-3d44a4d6c6c1", "title": "Sage Green Ceramic Mug Concept", "created": "2026-10-18T00:47:54.000Z", "updated": "2026-10-18T00:50:47.236Z", "status": "idle", "pendingApproval": null, "lastError": null, "turns": [ { "turn": 1, "message": { "text": "Create two product shots of a matte sage-green ceramic coffee mug ...", "references": [] }, "agent": [ { "kind": "text", "text": "I'm going to generate two images of a matte sage-green ceramic coffee mug, then I'll create a 6-second video ..." }, { "kind": "tool_call", "tool": "ask_for_permission", "args": { "num_total": 3, "total_cost": 10, "num_videos": 1, "num_images": 2 } } ], "media": [] }, { "turn": 2, "message": { "text": "Approve", "references": [] }, "agent": [ { "kind": "tool_call", "tool": "generate_video_from_text", "args": { "duration": 6, "aspect_ratio": "16:9", "model_display_name": "Omni 1.1 Flash", "prompt": "Cinematic product video of a matte sage-green ceramic coffee mug ..." } }, { "kind": "tool_call", "tool": "generate_image", "args": { "aspect_ratio": "1:1", "prompt": "A professional product shot of a matte sage-green ceramic coffee mug ..." } }, { "kind": "text", "text": "I've generated your two product shots. Your 6-second video has been scheduled ..." } ], "media": [ { "referenceId": "user:12345-email:6a6f...-video:5732c66d-...", "type": "video", "status": "completed", "model": "abra_t2v_6s", "displayName": "Steam rising from coffee mug", "url": "https://flow-content.google/video/5732c66d-...", "durationSec": 6 }, { "referenceId": "user:12345-email:6a6f...-image:377ecb33-...", "type": "image", "status": "completed", "displayName": "Ceramic coffee mug on table", "url": "https://flow-content.google/image/377ecb33-..." }, { "referenceId": "user:12345-email:6a6f...-image:a2d3cd0c-...", "type": "image", "status": "completed", "displayName": "Ceramic coffee mug on wooden sur…", "url": "https://flow-content.google/image/a2d3cd0c-..." } ] }, { "turn": 3, "message": { "text": "Nice. Revise the video: make it 8 seconds, ...", "references": [] }, "agent": ["..."], "media": [] }, { "turn": 4, "message": { "text": "Reject", "references": [] }, "agent": [{ "kind": "text", "text": "I've cancelled that generation. Are there any changes you'd like to make to the prompt or concept before we try again?" }], "media": [] } ] } ``` チャットのタイトルは Google が自動で付けました。何も動いていないときの `status` は `idle` で、エージェントが承認を待っている間は `pendingApproval` に費用が入ります。`?media=false` を付けると、リンクを更新しない分だけ速く読めます。 アカウントのチャットを、最新のやり取りが新しい順に一覧します。一覧は Google から取得するので、同じプロジェクトで Google Flow のウェブアプリから始めたチャットも含まれ、`chatId` をなくしたときもここから見つけられます。 ```bash curl -s "$API/chats?email=$EMAIL" -H "Authorization: Bearer $USEAPI_TOKEN" ``` チャットの名前を変更します。新しいタイトルは Google Flow のウェブアプリにも表示されます。 ```bash curl -s -X PATCH "$API/chats/$CHAT" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "title": "Sage mug product shoot" }' ``` ```json { "chatId": "c-u12345-email:john@gmail.com-project:74262ac8-...-bot:google-flow", "title": "Sage mug product shoot" } ``` 変更後の一覧: ```json { "chats": [ { "chatId": "c-u12345-email:john@gmail.com-project:74262ac8-...-chat:55023a0f-...-bot:google-flow", "email": "john@gmail.com", "title": "Sage mug product shoot", "created": "2026-10-18T00:47:54.000Z", "updated": "2026-10-18T00:51:01.773Z", "running": false }, { "chatId": "c-u12345-email:john@gmail.com-project:74262ac8-...-chat:1d9d42ed-...-bot:google-flow", "email": "john@gmail.com", "title": "Stylish Female Character Action Sequence", "created": "2026-10-17T03:50:34.000Z", "updated": "2026-10-17T04:57:26.375Z", "running": false } ] } ``` チャットの会話を削除します。本文なしの `204` が返り、チャットは一覧と Google Flow のウェブアプリから消えます。チャットで作った画像と動画はプロジェクトに残ります。 ```bash curl -s -X DELETE "$API/chats/$CHAT" -H "Authorization: Bearer $USEAPI_TOKEN" ``` ターンの実行中は、名前の変更と削除は `409` になります。 ### ステップ7:承認、指示、デフォルトモデルの設定 Google Flow のプロジェクトにはそれぞれエージェントの設定があり、Google Flow のウェブアプリのエージェントパネルと同じものです。[GET /agent/settings](/docs/api-google-flow-v1/get-google-flow-agent-settings) は設定を読み、アカウントの Google のプランで使える画像と動画のモデルを、そのプランでの画像1枚・動画1本の費用とともに一覧します。 ```bash curl -s "$API/settings?email=$EMAIL" -H "Authorization: Bearer $USEAPI_TOKEN" ``` [PUT /agent/settings](/docs/api-google-flow-v1/put-google-flow-agent-settings) は送ったフィールドだけを変更します。実行の前に、`ask` モードとデフォルトを設定しました。 ```bash curl -s -X PUT "$API/settings" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$EMAIL"'", "approval": "ask", "imageDefaults": { "model": "nano-banana-2", "aspectRatio": "1:1", "count": 2 }, "videoDefaults": { "model": "omni-flash", "aspectRatio": "16:9", "count": 1 } }' ``` レスポンスは変更後のプロジェクトの設定です。 ```json { "projectId": "74262ac8-a54f-4ad7-80d7-3d44a4d6c6c1", "approval": "ask", "instructions": [], "imageDefaults": { "model": "nano-banana-2", "aspectRatio": "1:1", "count": 2 }, "videoDefaults": { "model": "omni-flash", "aspectRatio": "16:9", "count": 1 }, "models": { "image": [ { "model": "nano-banana-pro", "label": "Nano Banana Pro", "credits": 0 }, { "model": "nano-banana-2-lite", "label": "Nano Banana 2 Lite", "credits": 0 }, { "model": "nano-banana-2", "label": "Nano Banana 2.1", "credits": 0 } ], "video": [ { "model": "omni-flash", "label": "Omni 1.1 Flash", "credits": 4 }, { "model": "veo-3.1-lite", "label": "Veo 3.1 - Lite", "credits": 5 }, { "model": "veo-3.1-fast", "label": "Veo 3.1 - Fast", "credits": 10 }, { "model": "veo-3.1-quality", "label": "Veo 3.1 - Quality", "credits": 100 } ] } } ``` `credits` はそのアカウントのプランでの画像1枚・動画1本の最低費用なので、長い動画や解像度の高い動画はもっとかかります。今回の6秒・720p の Omni 1.1 Flash の動画は10、8秒の修正版なら12でした。お使いのプランでは数字が違うこともあります。設定のフィールド: - `approval`:`ask`(エージェントが止まって費用を示す)または `auto`(確認せずに使う)。 - `instructions`:プロジェクトのすべてのチャットでエージェントが従う常設の指示を最大3つ。それぞれに参照画像を付けられます。配列はプロジェクトの指示を置き換えるので、全部まとめて送ってください。 - `imageDefaults` と `videoDefaults`:メッセージで特に指定がないときにエージェントが使うモデル、アスペクト比、枚数・本数。`models` から選びます。 設定は、Google Flow のウェブアプリでのチャットも含め、プロジェクトのすべてのチャットに適用されます。 ### AI アシスタントから同じことをする ホスト型の [Google Flow MCP サーバー](/docs/api-google-flow-v1/mcp)は、Claude Code、Cursor、VS Code などの MCP クライアントに同じチャットを12個のツールとして提供し、インストールは何も要りません。Claude Code では: ```bash claude mcp add --transport http useapi-google-flow https://api.useapi.net/v1/google-flow/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` あとはアシスタントに、マグの商品写真を普通の言葉で頼むだけです。アシスタントは `flow_agent_chat` で依頼を送り、クレジットを使いたいというエージェントの確認に `flow_agent_answer_approval` で答えます。サーバーは公式の MCP Registry に `net.useapi/google-flow` として登録されています。 先に完成したチャットクライアントを見たい場合は、[ライブデモ](/demos/google-flow/)を開いてください。API トークンを貼り付けてアカウントを選べば、画像と動画をチャットの中に表示しながらエージェントとチャットでき、添付、承認カード、設定も使えます。ソースはビルド不要の小さなファイル5つで、GitHub の [google-flow-api/demo](https://github.com/useapi/google-flow-api/tree/main/demo) にあり、[Agent ライブデモ](/docs/api-google-flow-v1/agent-demo)のページで各機能と API 呼び出しの対応を説明しています。 ### 例 この実行で作られたもので、手を加えていません。プロンプトは、こちらの依頼をもとにエージェント自身が書いたものです。 ###### Nano Banana 2.1 » セージグリーンのマグの商品写真2枚(ターン2) {: .no_toc #nano-banana-21--two-product-shots-of-the-sage-green-mug-turn-2 } <div style="display: flex; gap: 2%; flex-wrap: wrap"> <figure style="margin: 0; width: 49%"><a href="https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-shot-1-nano-banana-2-1.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-shot-1-nano-banana-2-1.jpg" alt="Google Flow Agent の結果:やわらかな朝の光の中、明るいオーク材のテーブルに置かれたマットなセージグリーンのセラミックマグ。Nano Banana 2.1 で生成" style="width: 100%" loading="lazy"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">Option 1、「Ceramic coffee mug on table」</figcaption></figure> <figure style="margin: 0; width: 49%"><a href="https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-shot-2-nano-banana-2-1.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-shot-2-nano-banana-2-1.jpg" alt="Google Flow Agent の結果:朝日の中、コーヒーの入ったセージグリーンのマグと真鍮のスプーン、開いた本のクローズアップ。Nano Banana 2.1 で生成" style="width: 100%" loading="lazy"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">Option 2、クローズアップ</figcaption></figure> </div> どちらも 1024×1024 の JPEG で、このアカウントのプランでは0クレジットです。 ###### Omni 1.1 Flash » マグから湯気が立ちのぼる6秒の動画(ターン2) {: .no_toc #omni-11-flash--6-seconds-of-steam-rising-from-the-mug-turn-2 } <video poster="https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-steam-omni-1-1-flash-6s-poster.jpg" src="https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-steam-omni-1-1-flash-6s.mp4" style="width: 100%; aspect-ratio: 16/9; max-width: 720px" controls type="video/mp4" preload="metadata"></video> 1280×720、音声付き、6秒、10クレジット。 関連チュートリアル:[Google Flow API で作る Veo 3.1 の動画](/docs/articles/google-flow-bash-ja)、[Omni Flash で作る音声付きの動画](/docs/articles/omni-flash-bash-ja)、[Google Flow API で作る Nano Banana の画像](/docs/articles/google-flow-images-bash-ja)。 ### よくある質問 - **Google Flow Agent の API はありますか?** useapi.net ならあります。[Agent API](/docs/api-google-flow-v1/agent) でチャットを始め、返信を Server-Sent Events でストリーミングし、承認に答え、画像と動画を受け取れます。無料アカウントを含むすべての Google AI のプランで使えます。Google は [Flow Agent](https://support.google.com/labs/answer/17093911?hl=ja) を Google Flow のウェブアプリの中でしか提供しておらず、独自の公開 API はありません(2026年11月時点)。 - **Google Flow Agent とのチャットにはいくらかかりますか?** useapi.net では、チャット自体は Flow クレジットを使わず、エージェントが作るものに Google Flow の通常の料金がかかります。その料金は使う前に `ask` モードで表示されます。今回の6秒・720p の Omni 1.1 Flash の動画は、Google AI Ultra $199.99 で $0.08、公式の [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) では $0.61 です(2026年11月時点)。 - **Google Flow のウェブアプリで始めたチャットは API に出てきますか?** useapi.net では、同じプロジェクトにあれば出てきます。[GET /agent/chats](/docs/api-google-flow-v1/get-google-flow-agent-chats) で一覧でき、上のどのエンドポイントも使えます。API で始めたチャットもウェブアプリに表示されます。エージェント用以外のプロジェクトで作業するには、[GET /assets/projects/`email`](/docs/api-google-flow-v1/get-google-flow-assets-projects-email) の `projectId` を渡します。 - **ストリームを開いておく代わりに webhook を使えますか?** useapi.net なら使えます。[POST /agent/chats](/docs/api-google-flow-v1/post-google-flow-agent-chats#callback)、メッセージの呼び出し、承認の呼び出しに `replyUrl` を渡すと、ターンの終了時に API がそのターンのメッセージ、メディア、状態、未回答の承認を1回の `POST` で送ります。動画はたいていまだ `queued` の状態で届くので、リンクは GET かストリームの `media` イベントで取得してください。 - **制限はありますか?** useapi.net では、1つのチャットは1ターンずつ進み、1つのアカウントで同時に動くのは最大3ターン、1ターンは最長10分です。これは Google 自身の制限です。Google はアカウントごとの1日のエージェントメッセージ数にも上限を設けていますが、数は公開していません。上限に達すると、API はそのアカウントに UTC の午前0時まで `429` を返します。[制限](/docs/api-google-flow-v1/agent#limits)をご覧ください。 ### おわりに ご質問は <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord サーバー</a> または <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram チャンネル</a>へどうぞ。 コード例は [GitHub リポジトリ](https://github.com/useapi/google-flow-api)にあり、[`demo/`](https://github.com/useapi/google-flow-api/tree/main/demo) にはエージェントのチャットクライアントも入っています。 AI アシスタントに Google Flow Agent とのチャットを任せることもできます。ホスト型の [Google Flow MCP サーバー](/docs/api-google-flow-v1/mcp)は、お使いの Google Flow アカウントで Claude Code、Cursor、VS Code から使えます。 ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-flow-agent-chat-pt === Document URL: https://useapi.net/docs/articles/google-flow-agent-chat-pt --- layout: default title: "Como conversar com o Google Flow Agent pela Google Flow API" description: "Converse com o Google Flow Agent pelo código com a Google Flow API da useapi.net: inicie um chat, receba as respostas por SSE, aprove o gasto de créditos e baixe as imagens e os vídeos, com curl." keywords: [Google Flow Agent API, Google Flow Agent, Flow Agent API, Google Flow API, AI agent API, Server-Sent Events, SSE, approval, Nano Banana 2.1, Omni 1.1 Flash, MCP server, Claude Code, curl, API do Google Flow Agent, API de agente de IA, streaming, tutorial em português] image: https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-shot-2-nano-banana-2-1.jpg parent: Articles nav_exclude: true lang: pt-BR translation_key: google-flow-agent-chat date: 2026-10-17 last_modified: 2026-11-10 nav_order: 903 repo: https://github.com/useapi/google-flow-api --- ## Como conversar com o Google Flow Agent pela Google Flow API {: .no_toc #how-to-chat-with-google-flow-agent-via-the-google-flow-api } 8 min de leitura • 17 de outubro de 2026 (10 de novembro de 2026) A useapi.net é uma API de terceiros. Não tem afiliação com o Google nem é endossada por ele. ## Sumário {: .no_toc .text-delta #table-of-contents } ### Introdução A Google Flow API da useapi.net deixa o seu código conversar com o Google Flow Agent, o assistente criativo que vem dentro do [Google Flow](https://flow.google.com): você inicia um chat com um único `curl`, recebe as respostas em streaming, aprova o que ele quer gastar e baixa as imagens e os vídeos que ele faz. O Google oferece o [Flow Agent](https://support.google.com/labs/answer/17093911?hl=pt-BR) só dentro do app web do Google Flow, sem API pública (em novembro de 2026). A useapi.net é uma API [de terceiros](/docs/legal#affiliation--third-party-services), sem afiliação com o Google, e o chat roda na sua conta do Google Flow, gratuita ou paga. Conversar com o agente não gasta créditos, e as imagens e os vídeos que ele faz custam o preço normal do Google Flow. Este guia é uma execução real, do começo ao fim. Pedimos ao agente duas fotos de produto de uma caneca de cerâmica e um vídeo de 6 segundos dela, aprovamos o gasto, baixamos as mídias, depois pedimos uma revisão e recusamos essa revisão. Todas as respostas abaixo são dessa execução, resumidas e com o e-mail da conta trocado. O agente planeja o trabalho sozinho. Ele escolhe as ferramentas e os modelos, guiado pelas [configurações](#step-7-settings-for-approval-instructions-and-default-models) do projeto, e guarda a conversa inteira do lado do Google, então um chat pode continuar horas ou dias depois com todo o contexto. A [visão geral do Agent](/docs/api-google-flow-v1/agent) cobre todas as regras e limites. ### Antes de começar Você precisa de um [token de API](/docs/start-here/setup-useapi) da useapi.net e de uma conta do Google conectada pela [configuração do Google Flow](/docs/start-here/setup-google-flow). O agente funciona em qualquer plano do Google AI, inclusive numa conta gratuita, e o que ele consegue gerar segue o plano da conta, igual ao [POST /images](/docs/api-google-flow-v1/post-google-flow-images) e ao [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos). Cada turno usa um captcha, resolvido pela API com os seus [provedores de captcha](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers) ou com os créditos de captcha grátis da sua primeira conta. Você não precisa enviar nada para isso. Os passos usam `curl`, `jq` e três variáveis de shell: ```bash export USEAPI_TOKEN="user:12345-..." # o seu token de API da useapi.net export EMAIL="john@gmail.com" # uma conta do Google Flow conectada API="https://api.useapi.net/v1/google-flow/agent" ``` Todas as chamadas abaixo também estão na [coleção do Postman](https://www.postman.com/useapinet/useapi-net). ### Como funciona um chat Um turno é uma mensagem sua e tudo o que o agente faz em resposta. Um chat roda um turno por vez: 1. [POST /agent/chats](/docs/api-google-flow-v1/post-google-flow-agent-chats) inicia um chat e responde `202` com um `chatId`. 2. [GET /agent/chats/`chatId`/stream](/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId-stream) acompanha o agente ao vivo por Server-Sent Events. 3. Quando o agente quer gastar créditos, ele para e pergunta. [POST /agent/chats/`chatId`/approval](/docs/api-google-flow-v1/post-google-flow-agent-chats-chatId-approval) responde. 4. [POST /agent/chats/`chatId`/messages](/docs/api-google-flow-v1/post-google-flow-agent-chats-chatId-messages) envia a próxima mensagem. 5. [GET /agent/chats/`chatId`](/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId) lê o chat inteiro, com links de mídia novos. ### Passo 1: Inicie um chat Envie o briefing em `message`. A chamada volta assim que o Google aceita o turno, o que normalmente leva alguns segundos e pode levar até uns 100 segundos, então dê ao `curl` um timeout de 150 segundos: ```bash curl -s --max-time 150 -X POST "$API/chats" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$EMAIL"'", "message": "Create two product shots of a matte sage-green ceramic coffee mug on a light oak table in soft morning window light, square format, with Nano Banana 2.1. Then make one 6 second video of the same mug with steam slowly rising from the coffee, with Omni 1.1 Flash." }' ``` O nosso respondeu `202` em uns 10 segundos: ```json { "chatId": "c-u12345-email:john@gmail.com-project:74262ac8-a54f-4ad7-80d7-3d44a4d6c6c1-chat:55023a0f-5e70-4545-bb4a-d878038dcf35-bot:google-flow", "email": "john@gmail.com", "turn": 1, "status": "running" } ``` O `chatId` já identifica a conta e o projeto, então as próximas chamadas não precisam de nenhum dos dois. Ele contém `:` e `@`, então codifique-o para URL no caminho. Guarde as duas formas: ```bash CHATID="c-u12345-email:john@gmail.com-project:74262ac8-...-bot:google-flow" CHAT=$(jq -rn --arg v "$CHATID" '$v|@uri') ``` Sem `projectId`, o chat fica no projeto de agente da própria conta, criado no primeiro chat e com um nome como `My Agents Work Fri, Oct 16`, o que separa o trabalho do agente das suas outras mídias do Google Flow. Você também pode anexar até 7 imagens, um vídeo, 5 vozes e 7 personagens a qualquer mensagem, com a mesma sintaxe de menções `@` do [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos). Veja [POST /agent/chats](/docs/api-google-flow-v1/post-google-flow-agent-chats#request-body). ### Passo 2: Receba a resposta em streaming Abra o stream com `-N` para os eventos aparecerem assim que chegam. O `EventSource` do navegador não consegue enviar o cabeçalho `Authorization`, então num app use `fetch()` ou qualquer cliente HTTP: ```bash curl -s -N "$API/chats/$CHAT/stream" \ -H "Authorization: Bearer $USEAPI_TOKEN" ``` Um stream novo envia primeiro um evento `chat`, reproduz o histórico do chat e depois envia `replayed`. Tudo depois de `replayed` é ao vivo. Aqui o primeiro turno já tinha terminado quando conectamos, então ele veio na reprodução. O agente apresentou o plano e depois pediu permissão para gastar 10 créditos em 2 imagens e 1 vídeo (`ui` e outros campos longos omitidos): ``` event: chat data: {"chatId":"c-u12345-email:john@gmail.com-project:74262ac8-...-bot:google-flow","status":"waiting_approval","turns":1} id: 1:505e78d7-bd79-4938-b0ec-8117bdb933dc event: message data: {"id":"1:505e78d7-...","turn":1,"items":[{"kind":"text","text":"I'm going to generate two images of a matte sage-green ceramic coffee mug, then I'll create a 6-second video of the same mug with rising steam using Omni 1.1 Flash."}]} id: 1:00c21a03-a687-4173-9fd9-190fcdf2447b event: message data: {"id":"1:00c21a03-...","turn":1,"items":[{"kind":"tool_call","tool":"open_chat_panel","args":{"_synthetic":true}},{"kind":"tool_call","tool":"ask_for_permission","args":{"num_total":3,"total_cost":10,"num_videos":1,"num_images":2}}]} id: 1:approval event: approval data: {"turn":1,"cost":10,"images":2,"videos":1,"total":3} event: replayed data: {"turns":1} ``` Os eventos que pedem alguma ação sua: | Evento | O que significa | |---|---| | `message` | Uma mensagem completa do agente: texto, raciocínio, chamadas de ferramenta e resultados | | `approval` | O agente pede permissão antes de gastar `cost` créditos do Flow | | `turn` | Um turno terminou: `completed`, `waiting_approval` ou `failed` com um `error` | | `media` | Uma imagem ou um vídeo que o agente fez, ou uma mudança de status, com a `url` quando `completed` | Um `keepalive` chega a cada 15 segundos. Um único stream cobre o chat inteiro, de turno em turno, então deixe-o aberto enquanto aprova e envia mensagens. Se ele cair, reconecte com o último `id` no cabeçalho `Last-Event-ID` e ele continua de onde parou. Um turno continua rodando quando você fecha o stream, então nada se perde. ### Passo 3: Aprove o gasto No modo de aprovação `ask`, o agente para antes de gastar qualquer coisa. O `status` do chat fica `waiting_approval` e o evento `approval` mostra o custo. Responda com `approve`, `always` ou `reject` em até uns 4 minutos: ```bash curl -s --max-time 150 -X POST "$API/chats/$CHAT/approval" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "decision": "approve" }' ``` Desde que o Google mudou o Flow Agent em 10 de novembro de 2026, a resposta continua o turno que fez o pedido (aqui o turno 1, não um novo turno 2), e o Google só a aceita enquanto esse turno ainda está aberto, uns 4 minutos depois do pedido. Uma resposta mais tardia recebe `409`: envie a mensagem de novo, ou coloque o projeto em `approval: "auto"` no [passo 7](#step-7-settings-for-approval-instructions-and-default-models) para o agente nunca perguntar. A execução abaixo foi gravada antes da mudança, então a resposta dela iniciou o turno 2, e os nomes de ferramenta dela (`generate_video_from_text`) agora aparecem como `generate_image` e `generate_video`. A resposta faz o agente voltar a trabalhar: ```json { "chatId": "c-u12345-email:john@gmail.com-project:74262ac8-...-bot:google-flow", "email": "john@gmail.com", "turn": 2, "status": "running" } ``` No stream aberto, o turno 2 colocou o vídeo na fila, fez as duas imagens e terminou em uns 30 segundos. As `choices` do agente (`Option 1`, `Option 2`) são os blocos que o app web do Google Flow mostra para cada resultado: ``` id: 2:5feb253e-0848-422a-bcb8-936995b3c0df event: message data: {"id":"2:5feb253e-...","turn":2,"items":[{"kind":"tool_result","tool":"generate_video_from_text","result":{"status":"queued","media_id":"5732c66d-a971-4cd0-92d2-508ef0aecc07","display_name":"Steam rising from coffee mug","model_key":"abra_t2v_6s","aspect_ratio":"VIDEO_ASPECT_RATIO_LANDSCAPE"}}]} id: 2:m:5732c66d-a971-4cd0-92d2-508ef0aecc07 event: media data: {"turn":2,"referenceId":"user:12345-email:6a6f...-video:5732c66d-a971-4cd0-92d2-508ef0aecc07","mediaId":"5732c66d-a971-4cd0-92d2-508ef0aecc07","type":"video","status":"queued","tool":"generate_video_from_text","model":"abra_t2v_6s","displayName":"Steam rising from coffee mug"} id: 2:m:377ecb33-ab2c-4bce-92d4-7bfcf53a9af2 event: media data: {"turn":2,"referenceId":"user:12345-email:6a6f...-image:377ecb33-ab2c-4bce-92d4-7bfcf53a9af2","mediaId":"377ecb33-ab2c-4bce-92d4-7bfcf53a9af2","type":"image","status":"completed","tool":"generate_image","displayName":"Ceramic coffee mug on table","url":"https://flow-content.google/image/377ecb33-...?Expires=...&Signature=..."} id: 2:4e37b051-c49c-4331-bc0c-06ccc539b950 event: message data: {"id":"2:4e37b051-...","turn":2,"items":[{"kind":"text","text":"I've generated your two product shots. Your 6-second video has been scheduled and is waiting in the queue due to high demand. Feel free to check back in a few minutes."}]} id: 2:end event: turn data: {"turn":2,"status":"completed"} ``` `always` aprova e também muda o projeto para o modo `auto`, então o agente para de perguntar em todos os chats do projeto. `reject` recusa, como mostra o [passo 5](#step-5-continue-or-revise). Enquanto um pedido espera, uma nova mensagem recebe `409`: responda o pedido primeiro. ### Passo 4: Baixe as mídias As imagens ficam prontas quando o turno termina. Os vídeos costumam ficar prontos um ou dois minutos depois, e o stream envia um segundo evento `media` para o vídeo quando isso acontece. O nosso chegou menos de um minuto depois do fim do turno: ``` id: 2:m:5732c66d-a971-4cd0-92d2-508ef0aecc07 event: media data: {"turn":2,"referenceId":"user:12345-email:6a6f...-video:5732c66d-a971-4cd0-92d2-508ef0aecc07","mediaId":"5732c66d-a971-4cd0-92d2-508ef0aecc07","type":"video","status":"completed","tool":"generate_video_from_text","model":"abra_t2v_6s","displayName":"Steam rising from coffee mug","url":"https://flow-content.google/video/5732c66d-...?Expires=...&Signature=...","durationSec":6} ``` Baixe cada `url` enquanto ainda está válida: ```bash curl -s -L -o mug-steam.mp4 "https://flow-content.google/video/5732c66d-...?Expires=...&Signature=..." ``` Os links apontam para o Google e expiram umas 6 horas depois de emitidos. Leia o chat de novo com [GET /agent/chats/`chatId`](#step-6-read-list-rename-and-delete-chats) para ter links novos, ou pegue o link de um item em [GET /assets/`mediaGenerationId`](/docs/api-google-flow-v1/get-google-flow-assets-mediagenerationid) com o `referenceId` dele. O `referenceId` também serve como `referenceImage_N` ou `referenceVideo_1` no [POST /images](/docs/api-google-flow-v1/post-google-flow-images), no [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) e na sua próxima mensagem ao agente. As duas imagens e o vídeo de 1280×720 estão em [Exemplos](#examples). A execução gastou 10 créditos: as duas imagens do Nano Banana 2.1 custaram 0 no plano desta conta, e o vídeo de 6 segundos do Omni 1.1 Flash custou 10. ### Passo 5: Continue ou revise Envie a próxima mensagem para o mesmo chat. O Google guarda a conversa, então o agente sabe qual é "o vídeo": ```bash curl -s --max-time 150 -X POST "$API/chats/$CHAT/messages" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "message": "Nice. Revise the video: make it 8 seconds, with a slow camera push-in toward the mug while the steam rises." }' ``` Ele respondeu `202` com `"turn": 3`, e o agente pediu permissão de novo, desta vez para 12 créditos: ``` id: 3:approval event: approval data: {"turn":3,"cost":12,"images":0,"videos":1,"total":1} id: 3:end event: turn data: {"turn":3,"status":"waiting_approval"} ``` Já tínhamos o nosso vídeo, então recusamos: ```bash curl -s --max-time 150 -X POST "$API/chats/$CHAT/approval" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "decision": "reject" }' ``` O turno 4 terminou com uma resposta e nenhuma imagem ou vídeo novo, e nenhum crédito foi gasto: ``` id: 4:91e06fb7-ba5b-4e32-b2a6-ce210be491ba event: message data: {"id":"4:91e06fb7-...","turn":4,"items":[{"kind":"text","text":"I've cancelled that generation. Are there any changes you'd like to make to the prompt or concept before we try again?"}]} id: 4:end event: turn data: {"turn":4,"status":"completed"} ``` Enviar uma mensagem enquanto um turno roda responde `409`, então espere o evento `turn` primeiro. Para escolher uma das opções do agente, envie o texto da opção como a próxima mensagem, como faz o app web do Google Flow. ### Passo 6: Leia, liste, renomeie e exclua chats Leia o chat inteiro direto do Google a qualquer momento. Cada turno traz a sua mensagem, tudo o que o agente fez e as mídias com links novos: ```bash curl -s "$API/chats/$CHAT" -H "Authorization: Bearer $USEAPI_TOKEN" ``` O nosso chat depois dos quatro turnos (itens de `agent` e `media` resumidos, `ui` omitido): ```json { "chatId": "c-u12345-email:john@gmail.com-project:74262ac8-...-bot:google-flow", "email": "john@gmail.com", "projectId": "74262ac8-a54f-4ad7-80d7-3d44a4d6c6c1", "title": "Sage Green Ceramic Mug Concept", "created": "2026-10-18T00:47:54.000Z", "updated": "2026-10-18T00:50:47.236Z", "status": "idle", "pendingApproval": null, "lastError": null, "turns": [ { "turn": 1, "message": { "text": "Create two product shots of a matte sage-green ceramic coffee mug ...", "references": [] }, "agent": [ { "kind": "text", "text": "I'm going to generate two images of a matte sage-green ceramic coffee mug, then I'll create a 6-second video ..." }, { "kind": "tool_call", "tool": "ask_for_permission", "args": { "num_total": 3, "total_cost": 10, "num_videos": 1, "num_images": 2 } } ], "media": [] }, { "turn": 2, "message": { "text": "Approve", "references": [] }, "agent": [ { "kind": "tool_call", "tool": "generate_video_from_text", "args": { "duration": 6, "aspect_ratio": "16:9", "model_display_name": "Omni 1.1 Flash", "prompt": "Cinematic product video of a matte sage-green ceramic coffee mug ..." } }, { "kind": "tool_call", "tool": "generate_image", "args": { "aspect_ratio": "1:1", "prompt": "A professional product shot of a matte sage-green ceramic coffee mug ..." } }, { "kind": "text", "text": "I've generated your two product shots. Your 6-second video has been scheduled ..." } ], "media": [ { "referenceId": "user:12345-email:6a6f...-video:5732c66d-...", "type": "video", "status": "completed", "model": "abra_t2v_6s", "displayName": "Steam rising from coffee mug", "url": "https://flow-content.google/video/5732c66d-...", "durationSec": 6 }, { "referenceId": "user:12345-email:6a6f...-image:377ecb33-...", "type": "image", "status": "completed", "displayName": "Ceramic coffee mug on table", "url": "https://flow-content.google/image/377ecb33-..." }, { "referenceId": "user:12345-email:6a6f...-image:a2d3cd0c-...", "type": "image", "status": "completed", "displayName": "Ceramic coffee mug on wooden sur…", "url": "https://flow-content.google/image/a2d3cd0c-..." } ] }, { "turn": 3, "message": { "text": "Nice. Revise the video: make it 8 seconds, ...", "references": [] }, "agent": ["..."], "media": [] }, { "turn": 4, "message": { "text": "Reject", "references": [] }, "agent": [{ "kind": "text", "text": "I've cancelled that generation. Are there any changes you'd like to make to the prompt or concept before we try again?" }], "media": [] } ] } ``` O Google deu o título ao chat por conta própria. O `status` fica `idle` quando nada está rodando, e `pendingApproval` guarda o custo enquanto o agente espera. Passe `?media=false` para uma leitura mais rápida, sem renovar os links. Liste os chats de uma conta, com a atividade mais recente primeiro. A lista vem do Google, então ela também traz os chats iniciados no app web do Google Flow no mesmo projeto, e é assim que você encontra um `chatId` perdido: ```bash curl -s "$API/chats?email=$EMAIL" -H "Authorization: Bearer $USEAPI_TOKEN" ``` Renomeie um chat. O novo título aparece também no app web do Google Flow: ```bash curl -s -X PATCH "$API/chats/$CHAT" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "title": "Sage mug product shoot" }' ``` ```json { "chatId": "c-u12345-email:john@gmail.com-project:74262ac8-...-bot:google-flow", "title": "Sage mug product shoot" } ``` A lista passou a mostrar: ```json { "chats": [ { "chatId": "c-u12345-email:john@gmail.com-project:74262ac8-...-chat:55023a0f-...-bot:google-flow", "email": "john@gmail.com", "title": "Sage mug product shoot", "created": "2026-10-18T00:47:54.000Z", "updated": "2026-10-18T00:51:01.773Z", "running": false }, { "chatId": "c-u12345-email:john@gmail.com-project:74262ac8-...-chat:1d9d42ed-...-bot:google-flow", "email": "john@gmail.com", "title": "Stylish Female Character Action Sequence", "created": "2026-10-17T03:50:34.000Z", "updated": "2026-10-17T04:57:26.375Z", "running": false } ] } ``` Exclua a conversa de um chat. A resposta é `204` sem corpo, o chat sai da lista e do app web do Google Flow, e as imagens e os vídeos que ele fez continuam no projeto: ```bash curl -s -X DELETE "$API/chats/$CHAT" -H "Authorization: Bearer $USEAPI_TOKEN" ``` Renomear e excluir respondem `409` enquanto um turno roda. ### Passo 7: Configurações de aprovação, instruções e modelos padrão Cada projeto do Google Flow tem configurações de agente, as mesmas do painel do agente no app web do Google Flow. [GET /agent/settings](/docs/api-google-flow-v1/get-google-flow-agent-settings) lê essas configurações e também lista os modelos de imagem e de vídeo que o plano do Google da conta tem, com o custo de uma imagem ou de um vídeo nesse plano: ```bash curl -s "$API/settings?email=$EMAIL" -H "Authorization: Bearer $USEAPI_TOKEN" ``` [PUT /agent/settings](/docs/api-google-flow-v1/put-google-flow-agent-settings) muda só os campos que você envia. Antes da execução, definimos o modo `ask` e os padrões: ```bash curl -s -X PUT "$API/settings" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$EMAIL"'", "approval": "ask", "imageDefaults": { "model": "nano-banana-2", "aspectRatio": "1:1", "count": 2 }, "videoDefaults": { "model": "omni-flash", "aspectRatio": "16:9", "count": 1 } }' ``` A resposta são as configurações do projeto depois da mudança: ```json { "projectId": "74262ac8-a54f-4ad7-80d7-3d44a4d6c6c1", "approval": "ask", "instructions": [], "imageDefaults": { "model": "nano-banana-2", "aspectRatio": "1:1", "count": 2 }, "videoDefaults": { "model": "omni-flash", "aspectRatio": "16:9", "count": 1 }, "models": { "image": [ { "model": "nano-banana-pro", "label": "Nano Banana Pro", "credits": 0 }, { "model": "nano-banana-2-lite", "label": "Nano Banana 2 Lite", "credits": 0 }, { "model": "nano-banana-2", "label": "Nano Banana 2.1", "credits": 0 } ], "video": [ { "model": "omni-flash", "label": "Omni 1.1 Flash", "credits": 4 }, { "model": "veo-3.1-lite", "label": "Veo 3.1 - Lite", "credits": 5 }, { "model": "veo-3.1-fast", "label": "Veo 3.1 - Fast", "credits": 10 }, { "model": "veo-3.1-quality", "label": "Veo 3.1 - Quality", "credits": 100 } ] } } ``` `credits` é o menor custo de uma imagem ou de um vídeo no plano da conta, então um vídeo mais longo ou de resolução maior custa mais: o nosso vídeo de 6 segundos em 720p do Omni 1.1 Flash custou 10, e a revisão de 8 segundos teria custado 12. O seu plano pode mostrar outros números. Os campos das configurações: - `approval`: `ask` (o agente para e mostra o custo) ou `auto` (ele gasta sem perguntar). - `instructions`: até 3 instruções fixas que o agente segue em todos os chats do projeto, cada uma com imagens de referência opcionais. O array substitui as instruções do projeto, então envie a lista completa. - `imageDefaults` e `videoDefaults`: o modelo, a proporção e a quantidade que o agente usa quando a mensagem não diz outra coisa, escolhidos em `models`. As configurações valem para todos os chats do projeto, inclusive os chats no app web do Google Flow. ### O mesmo a partir de um assistente de IA O [servidor MCP do Google Flow](/docs/api-google-flow-v1/mcp) hospedado dá ao Claude Code, ao Cursor, ao VS Code e a outros clientes MCP o mesmo chat em 12 ferramentas, sem nada para instalar. No Claude Code: ```bash claude mcp add --transport http useapi-google-flow https://api.useapi.net/v1/google-flow/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` Depois é só pedir ao assistente as fotos da caneca com palavras simples. O assistente envia o briefing com `flow_agent_chat` e responde ao pedido do agente para gastar créditos com `flow_agent_answer_approval`. O servidor está no MCP Registry oficial como `net.useapi/google-flow`. Para ver primeiro um cliente de chat completo, abra a [demo ao vivo](/demos/google-flow/). Cole o seu token de API, escolha uma conta e converse com o agente, com as imagens e os vídeos dentro do chat, anexos, cartões de aprovação e configurações. O código-fonte são cinco arquivos pequenos, sem etapa de build, no GitHub em [google-flow-api/demo](https://github.com/useapi/google-flow-api/tree/main/demo), e a página da [demo ao vivo do Agent](/docs/api-google-flow-v1/agent-demo) liga cada recurso à chamada de API dele. ### Exemplos O que esta execução fez, sem edição. Os prompts são do próprio agente, escritos a partir do nosso briefing. ###### Nano Banana 2.1 » duas fotos de produto da caneca verde-sálvia (turno 2) {: .no_toc #nano-banana-21--two-product-shots-of-the-sage-green-mug-turn-2 } <div style="display: flex; gap: 2%; flex-wrap: wrap"> <figure style="margin: 0; width: 49%"><a href="https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-shot-1-nano-banana-2-1.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-shot-1-nano-banana-2-1.jpg" alt="Resultado do Google Flow Agent: uma caneca de cerâmica verde-sálvia fosca numa mesa de carvalho claro, na luz suave da manhã, feita com o Nano Banana 2.1" style="width: 100%" loading="lazy"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">Option 1, "Ceramic coffee mug on table"</figcaption></figure> <figure style="margin: 0; width: 49%"><a href="https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-shot-2-nano-banana-2-1.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-shot-2-nano-banana-2-1.jpg" alt="Resultado do Google Flow Agent: close da caneca verde-sálvia com café, uma colher de latão e um livro aberto no sol da manhã, feito com o Nano Banana 2.1" style="width: 100%" loading="lazy"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">Option 2, o close</figcaption></figure> </div> As duas em JPEG de 1024×1024, 0 créditos no plano desta conta. ###### Omni 1.1 Flash » 6 segundos de vapor subindo da caneca (turno 2) {: .no_toc #omni-11-flash--6-seconds-of-steam-rising-from-the-mug-turn-2 } <video poster="https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-steam-omni-1-1-flash-6s-poster.jpg" src="https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-steam-omni-1-1-flash-6s.mp4" style="width: 100%; aspect-ratio: 16/9; max-width: 720px" controls type="video/mp4" preload="metadata"></video> 1280×720 com som, 6 segundos, 10 créditos. Tutoriais relacionados: [vídeo com Veo 3.1 pela Google Flow API](/docs/articles/google-flow-bash-pt), [vídeo com áudio nativo no Omni Flash](/docs/articles/omni-flash-bash-pt) e [imagens com o Nano Banana pela Google Flow API](/docs/articles/google-flow-images-bash-pt). ### Perguntas frequentes - **Existe uma API do Google Flow Agent?** Pela useapi.net, sim: a [Agent API](/docs/api-google-flow-v1/agent) inicia chats, transmite as respostas por Server-Sent Events, responde às aprovações e devolve as imagens e os vídeos, em qualquer assinatura do Google AI, inclusive numa conta gratuita. O Google oferece o [Flow Agent](https://support.google.com/labs/answer/17093911?hl=pt-BR) só dentro do app web do Google Flow, sem uma API pública própria (em novembro de 2026). - **Quanto custa conversar com o Google Flow Agent?** Pela useapi.net, conversar não gasta créditos do Flow, e o que o agente faz custa o preço normal do Google Flow, que o modo `ask` mostra antes de qualquer gasto. O vídeo de 6 segundos em 720p do Omni 1.1 Flash desta execução sai por $0,08 no Google AI Ultra $199,99, contra $0,61 na [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) oficial (em novembro de 2026). - **Os chats iniciados no app web do Google Flow aparecem na API?** Pela useapi.net, sim, quando estão no mesmo projeto. [GET /agent/chats](/docs/api-google-flow-v1/get-google-flow-agent-chats) lista esses chats, e todos os endpoints acima funcionam com eles. Os chats iniciados pela API também aparecem no app web. Passe o `projectId` de [GET /assets/projects/`email`](/docs/api-google-flow-v1/get-google-flow-assets-projects-email) para trabalhar num projeto que não seja o do próprio agente. - **Posso receber um webhook em vez de manter um stream aberto?** Pela useapi.net, sim. Passe `replyUrl` no [POST /agent/chats](/docs/api-google-flow-v1/post-google-flow-agent-chats#callback), na chamada de mensagens ou na de aprovação, e a API envia um `POST` com as mensagens, as mídias, o status e qualquer aprovação pendente do turno quando ele termina. Os vídeos costumam chegar ali ainda `queued`, então pegue os links deles pelo GET ou pelos eventos `media` do stream. - **Quais são os limites?** Pela useapi.net, um chat roda um turno por vez, uma conta roda no máximo 3 turnos ao mesmo tempo, e um turno dura até 10 minutos, que é o limite do próprio Google. O Google também limita as mensagens ao agente por conta por dia sem publicar o número, e a API responde `429` para essa conta até a meia-noite UTC. Veja [Limites](/docs/api-google-flow-v1/agent#limits). ### Conclusão Visite o nosso <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> servidor no Discord</a> ou o <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> canal no Telegram</a> para qualquer dúvida de suporte. Veja o nosso [repositório no GitHub](https://github.com/useapi/google-flow-api) com exemplos de código, incluindo o cliente de chat do agente em [`demo/`](https://github.com/useapi/google-flow-api/tree/main/demo). Um assistente de IA também pode conversar com o Google Flow Agent por você: o [servidor MCP do Google Flow](/docs/api-google-flow-v1/mcp) hospedado funciona com o Claude Code, o Cursor e o VS Code, na sua conta do Google Flow. ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-flow-agent-chat-th === Document URL: https://useapi.net/docs/articles/google-flow-agent-chat-th --- layout: default title: "วิธีแชตกับ Google Flow Agent ผ่าน Google Flow API" description: "แชตกับ Google Flow Agent จากโค้ดผ่าน Google Flow API ของ useapi.net: เริ่มแชต รับคำตอบแบบสตรีมผ่าน SSE อนุมัติการใช้เครดิต แล้วดาวน์โหลดภาพและวิดีโอ ด้วย curl" keywords: [Google Flow Agent API, Google Flow Agent, Flow Agent API, Google Flow API, AI agent API, Server-Sent Events, SSE, approval, Nano Banana 2.1, Omni 1.1 Flash, MCP server, Claude Code, curl, Google Flow Agent ภาษาไทย, API เอเจนต์ AI, สตรีมมิง, คู่มือ] image: https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-shot-2-nano-banana-2-1.jpg parent: Articles nav_exclude: true lang: th translation_key: google-flow-agent-chat date: 2026-10-17 last_modified: 2026-11-10 nav_order: 903 repo: https://github.com/useapi/google-flow-api --- ## วิธีแชตกับ Google Flow Agent ผ่าน Google Flow API {: .no_toc #how-to-chat-with-google-flow-agent-via-the-google-flow-api } อ่าน 8 นาที • 17 ตุลาคม 2026 (10 พฤศจิกายน 2026) useapi.net เป็น API ของบุคคลที่สาม (third-party) ไม่มีส่วนเกี่ยวข้องกับ Google และไม่ได้รับการรับรองจาก Google ## สารบัญ {: .no_toc .text-delta #table-of-contents } ### บทนำ Google Flow API ของ useapi.net ทำให้โค้ดของคุณแชตกับ Google Flow Agent ได้ ซึ่งเป็นผู้ช่วยด้านงานสร้างสรรค์ที่อยู่ใน [Google Flow](https://flow.google.com): เริ่มแชตด้วย `curl` คำสั่งเดียว รับคำตอบแบบสตรีม อนุมัติสิ่งที่เอเจนต์ต้องการใช้เครดิต แล้วดาวน์โหลดภาพและวิดีโอที่มันสร้าง Google ให้ใช้ [Flow Agent](https://support.google.com/labs/answer/17093911?hl=th) ได้เฉพาะในเว็บแอป Google Flow เท่านั้น ไม่มี API สาธารณะ (ข้อมูล ณ พฤศจิกายน 2026) useapi.net เป็น API [ของบุคคลที่สาม](/docs/legal#affiliation--third-party-services) ไม่มีส่วนเกี่ยวข้องกับ Google และแชตจะทำงานบนบัญชี Google Flow ของคุณ จะเป็นบัญชีฟรีหรือแบบชำระเงินก็ได้ การแชตกับเอเจนต์ไม่ใช้เครดิต ส่วนภาพและวิดีโอที่มันสร้างคิดราคาปกติของ Google Flow คู่มือนี้คือการรันจริงหนึ่งครั้งตั้งแต่ต้นจนจบ เราขอให้เอเจนต์ถ่ายภาพสินค้าแก้วกาแฟเซรามิกสองภาพ และทำวิดีโอแก้วใบนั้นยาว 6 วินาที อนุมัติการใช้เครดิต เก็บไฟล์ผลลัพธ์ จากนั้นขอให้แก้ไขอีกครั้งและปฏิเสธการแก้ไขนั้น ทุกคำตอบด้านล่างมาจากการรันครั้งนี้ ตัดให้สั้นลงและเปลี่ยนอีเมลของบัญชีแล้ว เอเจนต์วางแผนงานเอง มันเลือกเครื่องมือและโมเดลตาม[การตั้งค่า](#step-7-settings-for-approval-instructions-and-default-models)ของโปรเจกต์ และเก็บบทสนทนาทั้งหมดไว้ฝั่ง Google จึงแชตต่อได้แม้ผ่านไปหลายชั่วโมงหรือหลายวันโดยบริบทยังครบ กฎและข้อจำกัดทั้งหมดอยู่ใน[ภาพรวม Agent](/docs/api-google-flow-v1/agent) ### ก่อนเริ่ม คุณต้องมี [API token](/docs/start-here/setup-useapi) ของ useapi.net และบัญชี Google ที่เชื่อมต่อผ่าน[การตั้งค่า Google Flow](/docs/start-here/setup-google-flow) เอเจนต์ใช้ได้กับทุกแพ็กเกจ Google AI รวมถึงบัญชีฟรี และสิ่งที่มันสร้างได้ขึ้นกับแพ็กเกจของบัญชี เหมือนกับ [POST /images](/docs/api-google-flow-v1/post-google-flow-images) และ [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) แต่ละเทิร์นใช้แคปต์ชาหนึ่งครั้ง ซึ่ง API แก้ให้ด้วย[ผู้ให้บริการแคปต์ชา](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers)ของคุณ หรือเครดิตแคปต์ชาฟรีของบัญชีแรก คุณไม่ต้องส่งอะไรเพิ่มสำหรับเรื่องนี้ ขั้นตอนต่อไปนี้ใช้ `curl`, `jq` และตัวแปร shell สามตัว: ```bash export USEAPI_TOKEN="user:12345-..." # API token ของ useapi.net export EMAIL="john@gmail.com" # บัญชี Google Flow ที่เชื่อมต่อแล้ว API="https://api.useapi.net/v1/google-flow/agent" ``` ทุกคำสั่งด้านล่างมีอยู่ใน [Postman collection](https://www.postman.com/useapinet/useapi-net) ด้วย ### แชตทำงานอย่างไร หนึ่งเทิร์น (turn) คือข้อความหนึ่งข้อความจากคุณ กับทุกอย่างที่เอเจนต์ทำเพื่อตอบ แชตหนึ่งรันทีละเทิร์น: 1. [POST /agent/chats](/docs/api-google-flow-v1/post-google-flow-agent-chats) เริ่มแชต และตอบ `202` พร้อม `chatId` 2. [GET /agent/chats/`chatId`/stream](/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId-stream) ติดตามเอเจนต์แบบสดผ่าน Server-Sent Events 3. เมื่อเอเจนต์ต้องการใช้เครดิต มันจะหยุดและถาม [POST /agent/chats/`chatId`/approval](/docs/api-google-flow-v1/post-google-flow-agent-chats-chatId-approval) ใช้ตอบ 4. [POST /agent/chats/`chatId`/messages](/docs/api-google-flow-v1/post-google-flow-agent-chats-chatId-messages) ส่งข้อความถัดไป 5. [GET /agent/chats/`chatId`](/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId) อ่านแชตทั้งหมด พร้อมลิงก์ไฟล์ใหม่ ### ขั้นที่ 1: เริ่มแชต ส่งโจทย์ในฟิลด์ `message` คำสั่งจะตอบกลับทันทีที่ Google รับเทิร์น ซึ่งปกติใช้เวลาไม่กี่วินาที และอาจนานถึงราว 100 วินาที จึงควรตั้ง timeout ของ `curl` ไว้ 150 วินาที: ```bash curl -s --max-time 150 -X POST "$API/chats" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$EMAIL"'", "message": "Create two product shots of a matte sage-green ceramic coffee mug on a light oak table in soft morning window light, square format, with Nano Banana 2.1. Then make one 6 second video of the same mug with steam slowly rising from the coffee, with Omni 1.1 Flash." }' ``` ของเราตอบ `202` ภายในราว 10 วินาที: ```json { "chatId": "c-u12345-email:john@gmail.com-project:74262ac8-a54f-4ad7-80d7-3d44a4d6c6c1-chat:55023a0f-5e70-4545-bb4a-d878038dcf35-bot:google-flow", "email": "john@gmail.com", "turn": 1, "status": "running" } ``` `chatId` ระบุบัญชีและโปรเจกต์ไว้แล้ว คำสั่งถัดไปจึงไม่ต้องส่งทั้งสองอย่าง มันมี `:` และ `@` จึงต้องเข้ารหัส URL เมื่อใส่ในพาธ เก็บไว้ทั้งสองรูปแบบ: ```bash CHATID="c-u12345-email:john@gmail.com-project:74262ac8-...-bot:google-flow" CHAT=$(jq -rn --arg v "$CHATID" '$v|@uri') ``` ถ้าไม่ระบุ `projectId` แชตจะอยู่ในโปรเจกต์เอเจนต์ของบัญชีเอง ซึ่งสร้างขึ้นตอนแชตครั้งแรกและตั้งชื่อประมาณ `My Agents Work Fri, Oct 16` ช่วยแยกงานของเอเจนต์ออกจากไฟล์อื่นใน Google Flow ของคุณ คุณยังแนบภาพได้สูงสุด 7 ภาพ วิดีโอ 1 รายการ เสียง 5 เสียง และตัวละคร 7 ตัว กับข้อความใดก็ได้ โดยใช้ไวยากรณ์ `@` แบบเดียวกับ [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) ดู [POST /agent/chats](/docs/api-google-flow-v1/post-google-flow-agent-chats#request-body) ### ขั้นที่ 2: รับคำตอบแบบสตรีม เปิดสตรีมด้วย `-N` เพื่อให้อีเวนต์แสดงทันทีที่มาถึง `EventSource` ของเบราว์เซอร์ส่งเฮดเดอร์ `Authorization` ไม่ได้ ในแอปจึงควรใช้ `fetch()` หรือ HTTP client ตัวใดก็ได้: ```bash curl -s -N "$API/chats/$CHAT/stream" \ -H "Authorization: Bearer $USEAPI_TOKEN" ``` สตรีมใหม่จะส่งอีเวนต์ `chat` ก่อน เล่นประวัติแชตซ้ำ แล้วส่ง `replayed` ทุกอย่างหลัง `replayed` เป็นแบบสด ในกรณีนี้เทิร์นแรกจบไปแล้วตอนเราเชื่อมต่อ จึงมาในส่วนที่เล่นซ้ำ เอเจนต์บอกแผนของมัน แล้วขออนุญาตใช้ 10 เครดิตสำหรับภาพ 2 ภาพและวิดีโอ 1 รายการ (ตัด `ui` และฟิลด์ยาวอื่นออก): ``` event: chat data: {"chatId":"c-u12345-email:john@gmail.com-project:74262ac8-...-bot:google-flow","status":"waiting_approval","turns":1} id: 1:505e78d7-bd79-4938-b0ec-8117bdb933dc event: message data: {"id":"1:505e78d7-...","turn":1,"items":[{"kind":"text","text":"I'm going to generate two images of a matte sage-green ceramic coffee mug, then I'll create a 6-second video of the same mug with rising steam using Omni 1.1 Flash."}]} id: 1:00c21a03-a687-4173-9fd9-190fcdf2447b event: message data: {"id":"1:00c21a03-...","turn":1,"items":[{"kind":"tool_call","tool":"open_chat_panel","args":{"_synthetic":true}},{"kind":"tool_call","tool":"ask_for_permission","args":{"num_total":3,"total_cost":10,"num_videos":1,"num_images":2}}]} id: 1:approval event: approval data: {"turn":1,"cost":10,"images":2,"videos":1,"total":3} event: replayed data: {"turns":1} ``` อีเวนต์ที่คุณต้องจัดการ: | อีเวนต์ | ความหมาย | |---|---| | `message` | ข้อความที่สมบูรณ์หนึ่งข้อความของเอเจนต์: ข้อความ ความคิด การเรียกเครื่องมือ และผลของเครื่องมือ | | `approval` | เอเจนต์ขออนุญาตก่อนใช้เครดิต Flow จำนวน `cost` | | `turn` | เทิร์นจบแล้ว: `completed`, `waiting_approval` หรือ `failed` พร้อม `error` | | `media` | ภาพหรือวิดีโอที่เอเจนต์สร้าง หรือการเปลี่ยนสถานะของมัน พร้อม `url` เมื่อเป็น `completed` | `keepalive` มาทุก 15 วินาที สตรีมเดียวครอบคลุมทั้งแชตข้ามทุกเทิร์น จึงเปิดค้างไว้ระหว่างที่คุณอนุมัติและส่งข้อความได้ ถ้าหลุด ให้เชื่อมต่อใหม่โดยใส่ `id` ล่าสุดในเฮดเดอร์ `Last-Event-ID` แล้วมันจะต่อจากจุดเดิม เทิร์นยังทำงานต่อแม้คุณปิดสตรีม จึงไม่มีอะไรหาย ### ขั้นที่ 3: อนุมัติการใช้เครดิต ในโหมดอนุมัติ `ask` เอเจนต์จะหยุดก่อนใช้อะไรก็ตาม `status` ของแชตเป็น `waiting_approval` และอีเวนต์ `approval` แสดงค่าใช้จ่าย ตอบด้วย `approve`, `always` หรือ `reject` ภายในราว 4 นาที: ```bash curl -s --max-time 150 -X POST "$API/chats/$CHAT/approval" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "decision": "approve" }' ``` ตั้งแต่ Google เปลี่ยน Flow Agent เมื่อ 10 พฤศจิกายน 2026 คำตอบจะต่อเนื่องในเทิร์นที่ถาม (ในที่นี้คือเทิร์น 1 ไม่ใช่เทิร์น 2 ใหม่) และ Google รับคำตอบเฉพาะตอนที่เทิร์นนั้นยังเปิดอยู่ ราว 4 นาทีหลังคำขอ คำตอบที่ช้ากว่านั้นจะได้ `409`: ให้ส่งข้อความอีกครั้ง หรือตั้งโปรเจกต์เป็น `approval: "auto"` ใน[ขั้นที่ 7](#step-7-settings-for-approval-instructions-and-default-models) เพื่อให้เอเจนต์ไม่ถามอีก การรันด้านล่างบันทึกไว้ก่อนการเปลี่ยนแปลงนี้ คำตอบจึงเริ่มเทิร์น 2 และชื่อเครื่องมือในนั้น (`generate_video_from_text`) ตอนนี้จะแสดงเป็น `generate_image` และ `generate_video` คำตอบทำให้เอเจนต์กลับไปทำงานต่อ: ```json { "chatId": "c-u12345-email:john@gmail.com-project:74262ac8-...-bot:google-flow", "email": "john@gmail.com", "turn": 2, "status": "running" } ``` บนสตรีมที่เปิดอยู่ เทิร์น 2 ส่งวิดีโอเข้าคิว สร้างภาพทั้งสอง และจบภายในราว 30 วินาที `choices` ของเอเจนต์ (`Option 1`, `Option 2`) คือไทล์ที่เว็บแอป Google Flow แสดงสำหรับแต่ละผลลัพธ์: ``` id: 2:5feb253e-0848-422a-bcb8-936995b3c0df event: message data: {"id":"2:5feb253e-...","turn":2,"items":[{"kind":"tool_result","tool":"generate_video_from_text","result":{"status":"queued","media_id":"5732c66d-a971-4cd0-92d2-508ef0aecc07","display_name":"Steam rising from coffee mug","model_key":"abra_t2v_6s","aspect_ratio":"VIDEO_ASPECT_RATIO_LANDSCAPE"}}]} id: 2:m:5732c66d-a971-4cd0-92d2-508ef0aecc07 event: media data: {"turn":2,"referenceId":"user:12345-email:6a6f...-video:5732c66d-a971-4cd0-92d2-508ef0aecc07","mediaId":"5732c66d-a971-4cd0-92d2-508ef0aecc07","type":"video","status":"queued","tool":"generate_video_from_text","model":"abra_t2v_6s","displayName":"Steam rising from coffee mug"} id: 2:m:377ecb33-ab2c-4bce-92d4-7bfcf53a9af2 event: media data: {"turn":2,"referenceId":"user:12345-email:6a6f...-image:377ecb33-ab2c-4bce-92d4-7bfcf53a9af2","mediaId":"377ecb33-ab2c-4bce-92d4-7bfcf53a9af2","type":"image","status":"completed","tool":"generate_image","displayName":"Ceramic coffee mug on table","url":"https://flow-content.google/image/377ecb33-...?Expires=...&Signature=..."} id: 2:4e37b051-c49c-4331-bc0c-06ccc539b950 event: message data: {"id":"2:4e37b051-...","turn":2,"items":[{"kind":"text","text":"I've generated your two product shots. Your 6-second video has been scheduled and is waiting in the queue due to high demand. Feel free to check back in a few minutes."}]} id: 2:end event: turn data: {"turn":2,"status":"completed"} ``` `always` อนุมัติและเปลี่ยนโปรเจกต์เป็นโหมด `auto` ด้วย เอเจนต์จึงหยุดถามในทุกแชตของโปรเจกต์ `reject` คือปฏิเสธ ดูได้ใน[ขั้นที่ 5](#step-5-continue-or-revise) ระหว่างที่คำขอรออยู่ ข้อความใหม่จะได้ `409`: ให้ตอบคำขอก่อน ### ขั้นที่ 4: ดาวน์โหลดไฟล์ ภาพพร้อมเมื่อเทิร์นจบ วิดีโอมักเสร็จหลังจากนั้นหนึ่งถึงสองนาที และเมื่อเสร็จ สตรีมจะส่งอีเวนต์ `media` ครั้งที่สองสำหรับวิดีโอ ของเรามาถึงไม่ถึงหนึ่งนาทีหลังเทิร์นจบ: ``` id: 2:m:5732c66d-a971-4cd0-92d2-508ef0aecc07 event: media data: {"turn":2,"referenceId":"user:12345-email:6a6f...-video:5732c66d-a971-4cd0-92d2-508ef0aecc07","mediaId":"5732c66d-a971-4cd0-92d2-508ef0aecc07","type":"video","status":"completed","tool":"generate_video_from_text","model":"abra_t2v_6s","displayName":"Steam rising from coffee mug","url":"https://flow-content.google/video/5732c66d-...?Expires=...&Signature=...","durationSec":6} ``` ดาวน์โหลดแต่ละ `url` ขณะที่ลิงก์ยังใหม่: ```bash curl -s -L -o mug-steam.mp4 "https://flow-content.google/video/5732c66d-...?Expires=...&Signature=..." ``` ลิงก์ชี้ไปที่ Google และหมดอายุราว 6 ชั่วโมงหลังออก อ่านแชตอีกครั้งด้วย [GET /agent/chats/`chatId`](#step-6-read-list-rename-and-delete-chats) เพื่อรับลิงก์ใหม่ หรือขอลิงก์ของรายการเดียวจาก [GET /assets/`mediaGenerationId`](/docs/api-google-flow-v1/get-google-flow-assets-mediagenerationid) ด้วย `referenceId` ของมัน `referenceId` ยังใช้เป็น `referenceImage_N` หรือ `referenceVideo_1` ได้ใน [POST /images](/docs/api-google-flow-v1/post-google-flow-images), [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) และข้อความถัดไปถึงเอเจนต์ ภาพทั้งสองและวิดีโอ 1280×720 อยู่ใน[ตัวอย่าง](#examples) การรันนี้ใช้ 10 เครดิต: ภาพ Nano Banana 2.1 สองภาพใช้ 0 บนแพ็กเกจของบัญชีนี้ และวิดีโอ Omni 1.1 Flash 6 วินาทีใช้ 10 ### ขั้นที่ 5: ทำต่อหรือแก้ไข ส่งข้อความถัดไปไปยังแชตเดิม Google เก็บบทสนทนาไว้ เอเจนต์จึงรู้ว่า "วิดีโอนั้น" คือวิดีโอไหน: ```bash curl -s --max-time 150 -X POST "$API/chats/$CHAT/messages" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "message": "Nice. Revise the video: make it 8 seconds, with a slow camera push-in toward the mug while the steam rises." }' ``` มันตอบ `202` พร้อม `"turn": 3` และเอเจนต์ขออนุญาตอีกครั้ง คราวนี้ 12 เครดิต: ``` id: 3:approval event: approval data: {"turn":3,"cost":12,"images":0,"videos":1,"total":1} id: 3:end event: turn data: {"turn":3,"status":"waiting_approval"} ``` เรามีวิดีโอแล้ว จึงปฏิเสธ: ```bash curl -s --max-time 150 -X POST "$API/chats/$CHAT/approval" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "decision": "reject" }' ``` เทิร์น 4 จบด้วยคำตอบหนึ่งข้อความ ไม่มีภาพหรือวิดีโอใหม่ และไม่มีการใช้เครดิต: ``` id: 4:91e06fb7-ba5b-4e32-b2a6-ce210be491ba event: message data: {"id":"4:91e06fb7-...","turn":4,"items":[{"kind":"text","text":"I've cancelled that generation. Are there any changes you'd like to make to the prompt or concept before we try again?"}]} id: 4:end event: turn data: {"turn":4,"status":"completed"} ``` การส่งข้อความขณะเทิร์นกำลังทำงานจะได้ `409` จึงควรรออีเวนต์ `turn` ก่อน ถ้าต้องการเลือกตัวเลือกหนึ่งของเอเจนต์ ให้ส่งข้อความของตัวเลือกนั้นเป็นข้อความถัดไป เหมือนที่เว็บแอป Google Flow ทำ ### ขั้นที่ 6: อ่าน แสดงรายการ เปลี่ยนชื่อ และลบแชต อ่านแชตทั้งหมดจาก Google ได้ทุกเมื่อ แต่ละเทิร์นมีข้อความของคุณ ทุกอย่างที่เอเจนต์ทำ และไฟล์พร้อมลิงก์ใหม่: ```bash curl -s "$API/chats/$CHAT" -H "Authorization: Bearer $USEAPI_TOKEN" ``` แชตของเราหลังสี่เทิร์น (ตัดรายการ `agent` และ `media` ให้สั้นลง ตัด `ui` ออก): ```json { "chatId": "c-u12345-email:john@gmail.com-project:74262ac8-...-bot:google-flow", "email": "john@gmail.com", "projectId": "74262ac8-a54f-4ad7-80d7-3d44a4d6c6c1", "title": "Sage Green Ceramic Mug Concept", "created": "2026-10-18T00:47:54.000Z", "updated": "2026-10-18T00:50:47.236Z", "status": "idle", "pendingApproval": null, "lastError": null, "turns": [ { "turn": 1, "message": { "text": "Create two product shots of a matte sage-green ceramic coffee mug ...", "references": [] }, "agent": [ { "kind": "text", "text": "I'm going to generate two images of a matte sage-green ceramic coffee mug, then I'll create a 6-second video ..." }, { "kind": "tool_call", "tool": "ask_for_permission", "args": { "num_total": 3, "total_cost": 10, "num_videos": 1, "num_images": 2 } } ], "media": [] }, { "turn": 2, "message": { "text": "Approve", "references": [] }, "agent": [ { "kind": "tool_call", "tool": "generate_video_from_text", "args": { "duration": 6, "aspect_ratio": "16:9", "model_display_name": "Omni 1.1 Flash", "prompt": "Cinematic product video of a matte sage-green ceramic coffee mug ..." } }, { "kind": "tool_call", "tool": "generate_image", "args": { "aspect_ratio": "1:1", "prompt": "A professional product shot of a matte sage-green ceramic coffee mug ..." } }, { "kind": "text", "text": "I've generated your two product shots. Your 6-second video has been scheduled ..." } ], "media": [ { "referenceId": "user:12345-email:6a6f...-video:5732c66d-...", "type": "video", "status": "completed", "model": "abra_t2v_6s", "displayName": "Steam rising from coffee mug", "url": "https://flow-content.google/video/5732c66d-...", "durationSec": 6 }, { "referenceId": "user:12345-email:6a6f...-image:377ecb33-...", "type": "image", "status": "completed", "displayName": "Ceramic coffee mug on table", "url": "https://flow-content.google/image/377ecb33-..." }, { "referenceId": "user:12345-email:6a6f...-image:a2d3cd0c-...", "type": "image", "status": "completed", "displayName": "Ceramic coffee mug on wooden sur…", "url": "https://flow-content.google/image/a2d3cd0c-..." } ] }, { "turn": 3, "message": { "text": "Nice. Revise the video: make it 8 seconds, ...", "references": [] }, "agent": ["..."], "media": [] }, { "turn": 4, "message": { "text": "Reject", "references": [] }, "agent": [{ "kind": "text", "text": "I've cancelled that generation. Are there any changes you'd like to make to the prompt or concept before we try again?" }], "media": [] } ] } ``` Google ตั้งชื่อแชตให้เอง `status` เป็น `idle` เมื่อไม่มีอะไรทำงานอยู่ และ `pendingApproval` เก็บค่าใช้จ่ายไว้ระหว่างที่เอเจนต์รอ ใส่ `?media=false` เพื่ออ่านเร็วขึ้นโดยไม่รีเฟรชลิงก์ แสดงรายการแชตของบัญชี เรียงตามกิจกรรมล่าสุดก่อน รายการมาจาก Google จึงรวมแชตที่เริ่มในเว็บแอป Google Flow ในโปรเจกต์เดียวกันด้วย และเป็นวิธีหา `chatId` ที่หายไป: ```bash curl -s "$API/chats?email=$EMAIL" -H "Authorization: Bearer $USEAPI_TOKEN" ``` เปลี่ยนชื่อแชต ชื่อใหม่จะแสดงในเว็บแอป Google Flow ด้วย: ```bash curl -s -X PATCH "$API/chats/$CHAT" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "title": "Sage mug product shoot" }' ``` ```json { "chatId": "c-u12345-email:john@gmail.com-project:74262ac8-...-bot:google-flow", "title": "Sage mug product shoot" } ``` จากนั้นรายการเป็นดังนี้: ```json { "chats": [ { "chatId": "c-u12345-email:john@gmail.com-project:74262ac8-...-chat:55023a0f-...-bot:google-flow", "email": "john@gmail.com", "title": "Sage mug product shoot", "created": "2026-10-18T00:47:54.000Z", "updated": "2026-10-18T00:51:01.773Z", "running": false }, { "chatId": "c-u12345-email:john@gmail.com-project:74262ac8-...-chat:1d9d42ed-...-bot:google-flow", "email": "john@gmail.com", "title": "Stylish Female Character Action Sequence", "created": "2026-10-17T03:50:34.000Z", "updated": "2026-10-17T04:57:26.375Z", "running": false } ] } ``` ลบบทสนทนาของแชต จะได้ `204` โดยไม่มี body แชตหายไปจากรายการและจากเว็บแอป Google Flow ส่วนภาพและวิดีโอที่มันสร้างยังอยู่ในโปรเจกต์: ```bash curl -s -X DELETE "$API/chats/$CHAT" -H "Authorization: Bearer $USEAPI_TOKEN" ``` การเปลี่ยนชื่อและการลบจะได้ `409` ระหว่างที่เทิร์นกำลังทำงาน ### ขั้นที่ 7: การตั้งค่าการอนุมัติ คำสั่ง และโมเดลเริ่มต้น แต่ละโปรเจกต์ Google Flow มีการตั้งค่าเอเจนต์ เหมือนแผงเอเจนต์ในเว็บแอป Google Flow [GET /agent/settings](/docs/api-google-flow-v1/get-google-flow-agent-settings) อ่านค่าเหล่านี้ และแสดงรายการโมเดลภาพและวิดีโอที่แพ็กเกจ Google ของบัญชีมี พร้อมราคาภาพหนึ่งภาพหรือวิดีโอหนึ่งรายการบนแพ็กเกจนั้น: ```bash curl -s "$API/settings?email=$EMAIL" -H "Authorization: Bearer $USEAPI_TOKEN" ``` [PUT /agent/settings](/docs/api-google-flow-v1/put-google-flow-agent-settings) เปลี่ยนเฉพาะฟิลด์ที่คุณส่ง ก่อนการรัน เราตั้งโหมด `ask` และค่าเริ่มต้นไว้: ```bash curl -s -X PUT "$API/settings" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$EMAIL"'", "approval": "ask", "imageDefaults": { "model": "nano-banana-2", "aspectRatio": "1:1", "count": 2 }, "videoDefaults": { "model": "omni-flash", "aspectRatio": "16:9", "count": 1 } }' ``` คำตอบคือการตั้งค่าของโปรเจกต์หลังการเปลี่ยน: ```json { "projectId": "74262ac8-a54f-4ad7-80d7-3d44a4d6c6c1", "approval": "ask", "instructions": [], "imageDefaults": { "model": "nano-banana-2", "aspectRatio": "1:1", "count": 2 }, "videoDefaults": { "model": "omni-flash", "aspectRatio": "16:9", "count": 1 }, "models": { "image": [ { "model": "nano-banana-pro", "label": "Nano Banana Pro", "credits": 0 }, { "model": "nano-banana-2-lite", "label": "Nano Banana 2 Lite", "credits": 0 }, { "model": "nano-banana-2", "label": "Nano Banana 2.1", "credits": 0 } ], "video": [ { "model": "omni-flash", "label": "Omni 1.1 Flash", "credits": 4 }, { "model": "veo-3.1-lite", "label": "Veo 3.1 - Lite", "credits": 5 }, { "model": "veo-3.1-fast", "label": "Veo 3.1 - Fast", "credits": 10 }, { "model": "veo-3.1-quality", "label": "Veo 3.1 - Quality", "credits": 100 } ] } } ``` `credits` คือราคาต่ำสุดของภาพหนึ่งภาพหรือวิดีโอหนึ่งรายการบนแพ็กเกจของบัญชี วิดีโอที่ยาวขึ้นหรือความละเอียดสูงขึ้นจึงแพงกว่า: วิดีโอ Omni 1.1 Flash 6 วินาที 720p ของเราใช้ 10 และเวอร์ชันแก้ไข 8 วินาทีจะใช้ 12 แพ็กเกจของคุณอาจแสดงตัวเลขต่างไป ฟิลด์การตั้งค่า: - `approval`: `ask` (เอเจนต์หยุดและแสดงค่าใช้จ่าย) หรือ `auto` (ใช้เครดิตโดยไม่ถาม) - `instructions`: คำสั่งประจำสูงสุด 3 ข้อที่เอเจนต์ทำตามในทุกแชตของโปรเจกต์ แต่ละข้อแนบภาพอ้างอิงได้ อาร์เรย์นี้แทนที่คำสั่งเดิมของโปรเจกต์ จึงต้องส่งรายการทั้งหมด - `imageDefaults` และ `videoDefaults`: โมเดล อัตราส่วนภาพ และจำนวนที่เอเจนต์ใช้เมื่อข้อความไม่ได้ระบุเป็นอย่างอื่น เลือกจาก `models` การตั้งค่ามีผลกับทุกแชตในโปรเจกต์ รวมถึงแชตในเว็บแอป Google Flow ### ทำแบบเดียวกันจากผู้ช่วย AI [MCP server ของ Google Flow](/docs/api-google-flow-v1/mcp) แบบโฮสต์ให้ Claude Code, Cursor, VS Code และ MCP client อื่นใช้แชตเดียวกันนี้ในรูป 12 เครื่องมือ โดยไม่ต้องติดตั้งอะไร ใน Claude Code: ```bash claude mcp add --transport http useapi-google-flow https://api.useapi.net/v1/google-flow/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` จากนั้นขอภาพแก้วจากผู้ช่วยด้วยภาษาธรรมดา ผู้ช่วยส่งโจทย์ด้วย `flow_agent_chat` และตอบคำขอใช้เครดิตของเอเจนต์ด้วย `flow_agent_answer_approval` เซิร์ฟเวอร์นี้อยู่ใน MCP Registry ทางการในชื่อ `net.useapi/google-flow` ถ้าอยากเห็นไคลเอนต์แชตที่สมบูรณ์ก่อน เปิด[เดโมสด](/demos/google-flow/) วาง API token เลือกบัญชี แล้วแชตกับเอเจนต์ได้เลย พร้อมภาพและวิดีโอในแชต ไฟล์แนบ การ์ดอนุมัติ และการตั้งค่า ซอร์สโค้ดเป็นไฟล์เล็ก ๆ ห้าไฟล์ ไม่ต้องบิลด์ อยู่บน GitHub ที่ [google-flow-api/demo](https://github.com/useapi/google-flow-api/tree/main/demo) และหน้า [Agent Live Demo](/docs/api-google-flow-v1/agent-demo) จับคู่แต่ละฟีเจอร์กับคำสั่ง API ของมัน ### ตัวอย่าง ผลงานจากการรันครั้งนี้ ไม่ได้แก้ไข พรอมต์เขียนโดยเอเจนต์เองจากโจทย์ของเรา ###### Nano Banana 2.1 » ภาพสินค้าแก้วสีเขียวเสจสองภาพ (เทิร์น 2) {: .no_toc #nano-banana-21--two-product-shots-of-the-sage-green-mug-turn-2 } <div style="display: flex; gap: 2%; flex-wrap: wrap"> <figure style="margin: 0; width: 49%"><a href="https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-shot-1-nano-banana-2-1.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-shot-1-nano-banana-2-1.jpg" alt="ผลลัพธ์จาก Google Flow Agent: แก้วเซรามิกสีเขียวเสจแบบด้านบนโต๊ะไม้โอ๊กสีอ่อนในแสงเช้านุ่ม ๆ สร้างด้วย Nano Banana 2.1" style="width: 100%" loading="lazy"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">Option 1, "Ceramic coffee mug on table"</figcaption></figure> <figure style="margin: 0; width: 49%"><a href="https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-shot-2-nano-banana-2-1.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-shot-2-nano-banana-2-1.jpg" alt="ผลลัพธ์จาก Google Flow Agent: ภาพใกล้ของแก้วสีเขียวเสจที่มีกาแฟ ช้อนทองเหลือง และหนังสือที่เปิดอยู่ในแดดเช้า สร้างด้วย Nano Banana 2.1" style="width: 100%" loading="lazy"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">Option 2, ภาพใกล้</figcaption></figure> </div> ทั้งสองภาพเป็น JPEG 1024×1024 ใช้ 0 เครดิตบนแพ็กเกจของบัญชีนี้ ###### Omni 1.1 Flash » ไอน้ำลอยขึ้นจากแก้ว 6 วินาที (เทิร์น 2) {: .no_toc #omni-11-flash--6-seconds-of-steam-rising-from-the-mug-turn-2 } <video poster="https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-steam-omni-1-1-flash-6s-poster.jpg" src="https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-steam-omni-1-1-flash-6s.mp4" style="width: 100%; aspect-ratio: 16/9; max-width: 720px" controls type="video/mp4" preload="metadata"></video> 1280×720 มีเสียง 6 วินาที 10 เครดิต บทความที่เกี่ยวข้อง: [วิดีโอ Veo 3.1 ผ่าน Google Flow API](/docs/articles/google-flow-bash-th), [วิดีโอพร้อมเสียงในตัวด้วย Omni Flash](/docs/articles/omni-flash-bash-th) และ[ภาพ Nano Banana ผ่าน Google Flow API](/docs/articles/google-flow-images-bash-th) ### คำถามที่พบบ่อย - **มี API ของ Google Flow Agent ไหม?** ผ่าน useapi.net มี: [Agent API](/docs/api-google-flow-v1/agent) เริ่มแชต สตรีมคำตอบผ่าน Server-Sent Events ตอบการอนุมัติ และส่งภาพและวิดีโอกลับมา ใช้ได้กับทุกแพ็กเกจ Google AI รวมถึงบัญชีฟรี Google ให้ใช้ [Flow Agent](https://support.google.com/labs/answer/17093911?hl=th) เฉพาะในเว็บแอป Google Flow ไม่มี API สาธารณะของตัวเอง (ข้อมูล ณ พฤศจิกายน 2026) - **แชตกับ Google Flow Agent มีค่าใช้จ่ายเท่าไร?** ผ่าน useapi.net การแชตไม่ใช้เครดิต Flow ส่วนสิ่งที่เอเจนต์สร้างคิดราคาปกติของ Google Flow ซึ่งโหมด `ask` แสดงให้เห็นก่อนใช้จริง วิดีโอ Omni 1.1 Flash 6 วินาที 720p ในการรันนี้ราคา $0.08 บน Google AI Ultra $199.99 เทียบกับ $0.61 บน [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) ทางการ (ข้อมูล ณ พฤศจิกายน 2026) - **แชตที่เริ่มในเว็บแอป Google Flow แสดงใน API ไหม?** ผ่าน useapi.net แสดง ถ้าอยู่ในโปรเจกต์เดียวกัน [GET /agent/chats](/docs/api-google-flow-v1/get-google-flow-agent-chats) แสดงรายการแชตเหล่านั้น และทุก endpoint ด้านบนใช้กับแชตเหล่านั้นได้ แชตที่เริ่มผ่าน API ก็แสดงในเว็บแอปด้วย ส่ง `projectId` จาก [GET /assets/projects/`email`](/docs/api-google-flow-v1/get-google-flow-assets-projects-email) เพื่อทำงานในโปรเจกต์อื่นที่ไม่ใช่โปรเจกต์ของเอเจนต์เอง - **ใช้ webhook แทนการเปิดสตรีมค้างไว้ได้ไหม?** ผ่าน useapi.net ได้ ส่ง `replyUrl` ใน [POST /agent/chats](/docs/api-google-flow-v1/post-google-flow-agent-chats#callback) คำสั่งส่งข้อความ หรือคำสั่งอนุมัติ แล้ว API จะส่ง `POST` หนึ่งครั้งเมื่อเทิร์นจบ พร้อมข้อความ ไฟล์ สถานะ และคำขออนุมัติที่ค้างอยู่ของเทิร์นนั้น วิดีโอมักมาถึงตอนที่ยังเป็น `queued` จึงควรเอาลิงก์ของมันจาก GET หรือจากอีเวนต์ `media` ของสตรีม - **มีข้อจำกัดอะไรบ้าง?** ผ่าน useapi.net แชตหนึ่งรันทีละเทิร์น บัญชีหนึ่งรันได้พร้อมกันสูงสุด 3 เทิร์น และเทิร์นหนึ่งนานได้สูงสุด 10 นาที ซึ่งเป็นข้อจำกัดของ Google เอง Google ยังจำกัดจำนวนข้อความถึงเอเจนต์ต่อบัญชีต่อวันโดยไม่เปิดเผยตัวเลข และ API จะตอบ `429` สำหรับบัญชีนั้นจนถึงเที่ยงคืน UTC ดู[ข้อจำกัด](/docs/api-google-flow-v1/agent#limits) ### สรุป ติดต่อเราได้ที่ <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> หรือ <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> สำหรับทุกคำถามและข้อสงสัยด้านการใช้งาน ดูตัวอย่างโค้ดได้ใน [GitHub repo](https://github.com/useapi/google-flow-api) ของเรา รวมถึงไคลเอนต์แชตของเอเจนต์ใน [`demo/`](https://github.com/useapi/google-flow-api/tree/main/demo) ผู้ช่วย AI ก็แชตกับ Google Flow Agent แทนคุณได้: [MCP server ของ Google Flow](/docs/api-google-flow-v1/mcp) แบบโฮสต์ใช้ได้กับ Claude Code, Cursor และ VS Code บนบัญชี Google Flow ของคุณ ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-flow-agent-chat-vi === Document URL: https://useapi.net/docs/articles/google-flow-agent-chat-vi --- layout: default title: "Cách trò chuyện với Google Flow Agent qua Google Flow API" description: "Trò chuyện với Google Flow Agent bằng code qua Google Flow API của useapi.net: bắt đầu chat, nhận phản hồi qua SSE, phê duyệt việc dùng credit và tải ảnh, video về, bằng curl." keywords: [Google Flow Agent API, Google Flow Agent, Flow Agent API, Google Flow API, AI agent API, Server-Sent Events, SSE, approval, Nano Banana 2.1, Omni 1.1 Flash, MCP server, Claude Code, curl, API Google Flow Agent, API agent AI, streaming, hướng dẫn tiếng Việt] image: https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-shot-2-nano-banana-2-1.jpg parent: Articles nav_exclude: true lang: vi translation_key: google-flow-agent-chat date: 2026-10-17 last_modified: 2026-11-10 nav_order: 903 repo: https://github.com/useapi/google-flow-api --- ## Cách trò chuyện với Google Flow Agent qua Google Flow API {: .no_toc #how-to-chat-with-google-flow-agent-via-the-google-flow-api } 8 phút đọc • 17 tháng 10 năm 2026 (10 tháng 11 năm 2026) useapi.net là API của bên thứ ba, không liên kết với Google và không được Google bảo trợ. ## Mục lục {: .no_toc .text-delta #table-of-contents } ### Giới thiệu Google Flow API của useapi.net cho phép code của bạn trò chuyện với Google Flow Agent, trợ lý sáng tạo có sẵn trong [Google Flow](https://flow.google.com): bắt đầu chat bằng một lệnh `curl`, nhận phản hồi theo dạng stream, phê duyệt khoản agent muốn chi và tải về ảnh, video mà nó tạo. Google chỉ cung cấp [Flow Agent](https://support.google.com/labs/answer/17093911?hl=vi) bên trong ứng dụng web Google Flow, không có API công khai (tính đến tháng 11/2026). useapi.net là API [của bên thứ ba](/docs/legal#affiliation--third-party-services), không liên kết với Google, và cuộc chat chạy trên tài khoản Google Flow của bạn, miễn phí hay trả phí đều được. Trò chuyện với agent không tốn credit, còn ảnh và video nó tạo có giá thông thường của Google Flow. Hướng dẫn này là một lần chạy thật, từ đầu đến cuối. Chúng tôi nhờ agent chụp hai ảnh sản phẩm một chiếc cốc gốm và làm một video 6 giây về nó, phê duyệt khoản chi, lấy file về, rồi yêu cầu sửa lại và từ chối bản sửa đó. Mọi phản hồi bên dưới đều lấy từ lần chạy này, đã rút gọn và thay email tài khoản. Agent tự lên kế hoạch công việc. Nó chọn công cụ và model theo [cài đặt](#step-7-settings-for-approval-instructions-and-default-models) của project, và lưu toàn bộ cuộc trò chuyện phía Google, nên một cuộc chat có thể tiếp tục sau nhiều giờ hay nhiều ngày mà vẫn đủ ngữ cảnh. [Tổng quan Agent](/docs/api-google-flow-v1/agent) trình bày mọi quy tắc và giới hạn. ### Trước khi bắt đầu Bạn cần một [API token](/docs/start-here/setup-useapi) của useapi.net và một tài khoản Google đã kết nối qua [Cài đặt Google Flow](/docs/start-here/setup-google-flow). Agent chạy trên mọi gói Google AI, kể cả tài khoản miễn phí, và những gì nó tạo được tùy theo gói của tài khoản, giống như [POST /images](/docs/api-google-flow-v1/post-google-flow-images) và [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos). Mỗi lượt dùng một captcha, do API giải bằng [nhà cung cấp captcha](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers) của bạn hoặc bằng lượt giải captcha miễn phí của tài khoản đầu tiên. Bạn không cần gửi gì cho việc này. Các bước dùng `curl`, `jq` và ba biến shell: ```bash export USEAPI_TOKEN="user:12345-..." # API token useapi.net của bạn export EMAIL="john@gmail.com" # một tài khoản Google Flow đã kết nối API="https://api.useapi.net/v1/google-flow/agent" ``` Mọi lệnh gọi bên dưới cũng có trong [Postman collection](https://www.postman.com/useapinet/useapi-net). ### Một cuộc chat diễn ra thế nào Một lượt (turn) là một tin nhắn của bạn và mọi việc agent làm để trả lời. Mỗi cuộc chat chạy từng lượt một: 1. [POST /agent/chats](/docs/api-google-flow-v1/post-google-flow-agent-chats) bắt đầu cuộc chat và trả về `202` kèm `chatId`. 2. [GET /agent/chats/`chatId`/stream](/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId-stream) theo dõi agent trực tiếp qua Server-Sent Events. 3. Khi agent muốn dùng credit, nó dừng lại và hỏi. [POST /agent/chats/`chatId`/approval](/docs/api-google-flow-v1/post-google-flow-agent-chats-chatId-approval) trả lời. 4. [POST /agent/chats/`chatId`/messages](/docs/api-google-flow-v1/post-google-flow-agent-chats-chatId-messages) gửi tin nhắn tiếp theo. 5. [GET /agent/chats/`chatId`](/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId) đọc toàn bộ cuộc chat, với link media mới. ### Bước 1: Bắt đầu chat Gửi yêu cầu trong `message`. Lệnh gọi trả về ngay khi Google nhận lượt, thường mất vài giây và có thể lên tới khoảng 100 giây, nên hãy đặt timeout 150 giây cho `curl`: ```bash curl -s --max-time 150 -X POST "$API/chats" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$EMAIL"'", "message": "Create two product shots of a matte sage-green ceramic coffee mug on a light oak table in soft morning window light, square format, with Nano Banana 2.1. Then make one 6 second video of the same mug with steam slowly rising from the coffee, with Omni 1.1 Flash." }' ``` Lệnh của chúng tôi trả về `202` sau khoảng 10 giây: ```json { "chatId": "c-u12345-email:john@gmail.com-project:74262ac8-a54f-4ad7-80d7-3d44a4d6c6c1-chat:55023a0f-5e70-4545-bb4a-d878038dcf35-bot:google-flow", "email": "john@gmail.com", "turn": 1, "status": "running" } ``` `chatId` đã chứa tài khoản và project, nên các lệnh gọi sau không cần hai thứ này nữa. Nó có `:` và `@`, nên hãy mã hóa URL khi đặt vào đường dẫn. Giữ cả hai dạng: ```bash CHATID="c-u12345-email:john@gmail.com-project:74262ac8-...-bot:google-flow" CHAT=$(jq -rn --arg v "$CHATID" '$v|@uri') ``` Nếu không có `projectId`, cuộc chat nằm trong project agent riêng của tài khoản, được tạo ở lần chat đầu tiên với tên kiểu `My Agents Work Fri, Oct 16`, giúp tách việc của agent khỏi các media Google Flow khác của bạn. Bạn cũng có thể đính kèm tối đa 7 ảnh, một video, 5 giọng và 7 nhân vật vào bất kỳ tin nhắn nào, với cùng cú pháp nhắc `@` như [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos), xem [POST /agent/chats](/docs/api-google-flow-v1/post-google-flow-agent-chats#request-body). ### Bước 2: Nhận phản hồi qua stream Mở stream với `-N` để sự kiện hiện ra ngay khi tới. `EventSource` của trình duyệt không gửi được header `Authorization`, nên trong ứng dụng hãy dùng `fetch()` hoặc bất kỳ HTTP client nào: ```bash curl -s -N "$API/chats/$CHAT/stream" \ -H "Authorization: Bearer $USEAPI_TOKEN" ``` Một stream mới trước tiên gửi sự kiện `chat`, phát lại lịch sử cuộc chat, rồi gửi `replayed`. Mọi thứ sau `replayed` là trực tiếp. Ở đây lượt đầu đã xong khi chúng tôi kết nối, nên nó đến trong phần phát lại. Agent nêu kế hoạch, rồi xin phép dùng 10 credit cho 2 ảnh và 1 video (đã bỏ `ui` và các trường dài khác): ``` event: chat data: {"chatId":"c-u12345-email:john@gmail.com-project:74262ac8-...-bot:google-flow","status":"waiting_approval","turns":1} id: 1:505e78d7-bd79-4938-b0ec-8117bdb933dc event: message data: {"id":"1:505e78d7-...","turn":1,"items":[{"kind":"text","text":"I'm going to generate two images of a matte sage-green ceramic coffee mug, then I'll create a 6-second video of the same mug with rising steam using Omni 1.1 Flash."}]} id: 1:00c21a03-a687-4173-9fd9-190fcdf2447b event: message data: {"id":"1:00c21a03-...","turn":1,"items":[{"kind":"tool_call","tool":"open_chat_panel","args":{"_synthetic":true}},{"kind":"tool_call","tool":"ask_for_permission","args":{"num_total":3,"total_cost":10,"num_videos":1,"num_images":2}}]} id: 1:approval event: approval data: {"turn":1,"cost":10,"images":2,"videos":1,"total":3} event: replayed data: {"turns":1} ``` Các sự kiện bạn cần xử lý: | Sự kiện | Ý nghĩa | |---|---| | `message` | Một tin nhắn hoàn chỉnh của agent: văn bản, suy nghĩ, lệnh gọi công cụ và kết quả | | `approval` | Agent xin phép trước khi dùng `cost` credit Flow | | `turn` | Một lượt kết thúc: `completed`, `waiting_approval` hoặc `failed` kèm `error` | | `media` | Ảnh hoặc video agent tạo, hoặc thay đổi trạng thái của nó, có `url` khi `completed` | Cứ 15 giây có một `keepalive`. Một stream bao trọn cả cuộc chat qua nhiều lượt, nên cứ để nó mở trong lúc bạn phê duyệt và gửi tin nhắn. Nếu bị ngắt, kết nối lại với `id` cuối cùng trong header `Last-Event-ID`, stream sẽ tiếp tục từ chỗ đã dừng. Lượt vẫn chạy khi bạn đóng stream, nên không mất gì. ### Bước 3: Phê duyệt khoản chi Ở chế độ phê duyệt `ask`, agent dừng lại trước khi chi bất cứ thứ gì. `status` của cuộc chat là `waiting_approval` và sự kiện `approval` cho thấy chi phí. Trả lời bằng `approve`, `always` hoặc `reject` trong khoảng 4 phút: ```bash curl -s --max-time 150 -X POST "$API/chats/$CHAT/approval" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "decision": "approve" }' ``` Từ khi Google thay đổi Flow Agent vào ngày 10/11/2026, câu trả lời tiếp nối lượt đã hỏi (ở đây là lượt 1, không phải một lượt 2 mới), và Google chỉ nhận nó khi lượt đó còn mở, khoảng 4 phút sau khi hỏi. Trả lời muộn hơn sẽ nhận `409`: hãy gửi lại tin nhắn, hoặc đặt project thành `approval: "auto"` ở [bước 7](#step-7-settings-for-approval-instructions-and-default-models) để agent không bao giờ hỏi. Lần chạy bên dưới được ghi trước thay đổi này, nên câu trả lời của nó mở ra lượt 2, và tên công cụ trong đó (`generate_video_from_text`) giờ được trả về là `generate_image` và `generate_video`. Câu trả lời cho agent làm việc tiếp: ```json { "chatId": "c-u12345-email:john@gmail.com-project:74262ac8-...-bot:google-flow", "email": "john@gmail.com", "turn": 2, "status": "running" } ``` Trên stream đang mở, lượt 2 đưa video vào hàng đợi, tạo xong hai ảnh và kết thúc trong khoảng 30 giây. `choices` của agent (`Option 1`, `Option 2`) là các ô mà ứng dụng web Google Flow hiển thị cho mỗi kết quả: ``` id: 2:5feb253e-0848-422a-bcb8-936995b3c0df event: message data: {"id":"2:5feb253e-...","turn":2,"items":[{"kind":"tool_result","tool":"generate_video_from_text","result":{"status":"queued","media_id":"5732c66d-a971-4cd0-92d2-508ef0aecc07","display_name":"Steam rising from coffee mug","model_key":"abra_t2v_6s","aspect_ratio":"VIDEO_ASPECT_RATIO_LANDSCAPE"}}]} id: 2:m:5732c66d-a971-4cd0-92d2-508ef0aecc07 event: media data: {"turn":2,"referenceId":"user:12345-email:6a6f...-video:5732c66d-a971-4cd0-92d2-508ef0aecc07","mediaId":"5732c66d-a971-4cd0-92d2-508ef0aecc07","type":"video","status":"queued","tool":"generate_video_from_text","model":"abra_t2v_6s","displayName":"Steam rising from coffee mug"} id: 2:m:377ecb33-ab2c-4bce-92d4-7bfcf53a9af2 event: media data: {"turn":2,"referenceId":"user:12345-email:6a6f...-image:377ecb33-ab2c-4bce-92d4-7bfcf53a9af2","mediaId":"377ecb33-ab2c-4bce-92d4-7bfcf53a9af2","type":"image","status":"completed","tool":"generate_image","displayName":"Ceramic coffee mug on table","url":"https://flow-content.google/image/377ecb33-...?Expires=...&Signature=..."} id: 2:4e37b051-c49c-4331-bc0c-06ccc539b950 event: message data: {"id":"2:4e37b051-...","turn":2,"items":[{"kind":"text","text":"I've generated your two product shots. Your 6-second video has been scheduled and is waiting in the queue due to high demand. Feel free to check back in a few minutes."}]} id: 2:end event: turn data: {"turn":2,"status":"completed"} ``` `always` phê duyệt và đồng thời chuyển project sang chế độ `auto`, nên agent thôi hỏi trong mọi cuộc chat của project. `reject` từ chối, như ở [bước 5](#step-5-continue-or-revise). Khi một yêu cầu đang chờ, tin nhắn mới sẽ nhận `409`: hãy trả lời yêu cầu trước. ### Bước 4: Lấy media Ảnh sẵn sàng khi lượt kết thúc. Video thường xong sau đó một hai phút, và khi xong stream gửi thêm một sự kiện `media` thứ hai cho video. Video của chúng tôi tới chưa đầy một phút sau khi lượt kết thúc: ``` id: 2:m:5732c66d-a971-4cd0-92d2-508ef0aecc07 event: media data: {"turn":2,"referenceId":"user:12345-email:6a6f...-video:5732c66d-a971-4cd0-92d2-508ef0aecc07","mediaId":"5732c66d-a971-4cd0-92d2-508ef0aecc07","type":"video","status":"completed","tool":"generate_video_from_text","model":"abra_t2v_6s","displayName":"Steam rising from coffee mug","url":"https://flow-content.google/video/5732c66d-...?Expires=...&Signature=...","durationSec":6} ``` Tải từng `url` về khi link còn mới: ```bash curl -s -L -o mug-steam.mp4 "https://flow-content.google/video/5732c66d-...?Expires=...&Signature=..." ``` Các link trỏ tới Google và hết hạn khoảng 6 giờ sau khi được cấp. Đọc lại cuộc chat bằng [GET /agent/chats/`chatId`](#step-6-read-list-rename-and-delete-chats) để có link mới, hoặc lấy link của một mục từ [GET /assets/`mediaGenerationId`](/docs/api-google-flow-v1/get-google-flow-assets-mediagenerationid) bằng `referenceId` của nó. `referenceId` cũng dùng được làm `referenceImage_N` hoặc `referenceVideo_1` trong [POST /images](/docs/api-google-flow-v1/post-google-flow-images), [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) và tin nhắn tiếp theo gửi agent. Hai ảnh và video 1280×720 có trong phần [Ví dụ](#examples). Lần chạy tốn 10 credit: hai ảnh Nano Banana 2.1 tốn 0 trên gói của tài khoản này, còn video Omni 1.1 Flash 6 giây tốn 10. ### Bước 5: Tiếp tục hoặc chỉnh sửa Gửi tin nhắn tiếp theo vào cùng cuộc chat. Google giữ cuộc trò chuyện, nên agent biết "video đó" là video nào: ```bash curl -s --max-time 150 -X POST "$API/chats/$CHAT/messages" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "message": "Nice. Revise the video: make it 8 seconds, with a slow camera push-in toward the mug while the steam rises." }' ``` Lệnh trả về `202` với `"turn": 3`, và agent lại xin phép, lần này 12 credit: ``` id: 3:approval event: approval data: {"turn":3,"cost":12,"images":0,"videos":1,"total":1} id: 3:end event: turn data: {"turn":3,"status":"waiting_approval"} ``` Chúng tôi đã có video rồi, nên từ chối: ```bash curl -s --max-time 150 -X POST "$API/chats/$CHAT/approval" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "decision": "reject" }' ``` Lượt 4 kết thúc bằng một câu trả lời, không có ảnh hay video mới, và không tốn credit nào: ``` id: 4:91e06fb7-ba5b-4e32-b2a6-ce210be491ba event: message data: {"id":"4:91e06fb7-...","turn":4,"items":[{"kind":"text","text":"I've cancelled that generation. Are there any changes you'd like to make to the prompt or concept before we try again?"}]} id: 4:end event: turn data: {"turn":4,"status":"completed"} ``` Gửi tin nhắn khi một lượt đang chạy sẽ nhận `409`, nên hãy chờ sự kiện `turn` trước. Để chọn một trong các lựa chọn của agent, gửi văn bản của lựa chọn đó làm tin nhắn tiếp theo, giống như ứng dụng web Google Flow. ### Bước 6: Đọc, liệt kê, đổi tên và xóa cuộc chat Đọc toàn bộ cuộc chat từ Google bất cứ lúc nào. Mỗi lượt có tin nhắn của bạn, mọi việc agent đã làm và media với link mới: ```bash curl -s "$API/chats/$CHAT" -H "Authorization: Bearer $USEAPI_TOKEN" ``` Cuộc chat của chúng tôi sau bốn lượt (đã rút gọn các mục `agent` và `media`, bỏ `ui`): ```json { "chatId": "c-u12345-email:john@gmail.com-project:74262ac8-...-bot:google-flow", "email": "john@gmail.com", "projectId": "74262ac8-a54f-4ad7-80d7-3d44a4d6c6c1", "title": "Sage Green Ceramic Mug Concept", "created": "2026-10-18T00:47:54.000Z", "updated": "2026-10-18T00:50:47.236Z", "status": "idle", "pendingApproval": null, "lastError": null, "turns": [ { "turn": 1, "message": { "text": "Create two product shots of a matte sage-green ceramic coffee mug ...", "references": [] }, "agent": [ { "kind": "text", "text": "I'm going to generate two images of a matte sage-green ceramic coffee mug, then I'll create a 6-second video ..." }, { "kind": "tool_call", "tool": "ask_for_permission", "args": { "num_total": 3, "total_cost": 10, "num_videos": 1, "num_images": 2 } } ], "media": [] }, { "turn": 2, "message": { "text": "Approve", "references": [] }, "agent": [ { "kind": "tool_call", "tool": "generate_video_from_text", "args": { "duration": 6, "aspect_ratio": "16:9", "model_display_name": "Omni 1.1 Flash", "prompt": "Cinematic product video of a matte sage-green ceramic coffee mug ..." } }, { "kind": "tool_call", "tool": "generate_image", "args": { "aspect_ratio": "1:1", "prompt": "A professional product shot of a matte sage-green ceramic coffee mug ..." } }, { "kind": "text", "text": "I've generated your two product shots. Your 6-second video has been scheduled ..." } ], "media": [ { "referenceId": "user:12345-email:6a6f...-video:5732c66d-...", "type": "video", "status": "completed", "model": "abra_t2v_6s", "displayName": "Steam rising from coffee mug", "url": "https://flow-content.google/video/5732c66d-...", "durationSec": 6 }, { "referenceId": "user:12345-email:6a6f...-image:377ecb33-...", "type": "image", "status": "completed", "displayName": "Ceramic coffee mug on table", "url": "https://flow-content.google/image/377ecb33-..." }, { "referenceId": "user:12345-email:6a6f...-image:a2d3cd0c-...", "type": "image", "status": "completed", "displayName": "Ceramic coffee mug on wooden sur…", "url": "https://flow-content.google/image/a2d3cd0c-..." } ] }, { "turn": 3, "message": { "text": "Nice. Revise the video: make it 8 seconds, ...", "references": [] }, "agent": ["..."], "media": [] }, { "turn": 4, "message": { "text": "Reject", "references": [] }, "agent": [{ "kind": "text", "text": "I've cancelled that generation. Are there any changes you'd like to make to the prompt or concept before we try again?" }], "media": [] } ] } ``` Google tự đặt tên cho cuộc chat. `status` là `idle` khi không có gì đang chạy, và `pendingApproval` giữ chi phí trong lúc agent chờ. Thêm `?media=false` để đọc nhanh hơn, không làm mới link. Liệt kê các cuộc chat của một tài khoản, mới hoạt động gần nhất ở trên. Danh sách lấy từ Google, nên cũng có các cuộc chat bắt đầu trong ứng dụng web Google Flow ở cùng project, và đây là cách tìm lại `chatId` bị mất: ```bash curl -s "$API/chats?email=$EMAIL" -H "Authorization: Bearer $USEAPI_TOKEN" ``` Đổi tên cuộc chat. Tên mới cũng hiện trong ứng dụng web Google Flow: ```bash curl -s -X PATCH "$API/chats/$CHAT" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "title": "Sage mug product shoot" }' ``` ```json { "chatId": "c-u12345-email:john@gmail.com-project:74262ac8-...-bot:google-flow", "title": "Sage mug product shoot" } ``` Sau đó danh sách là: ```json { "chats": [ { "chatId": "c-u12345-email:john@gmail.com-project:74262ac8-...-chat:55023a0f-...-bot:google-flow", "email": "john@gmail.com", "title": "Sage mug product shoot", "created": "2026-10-18T00:47:54.000Z", "updated": "2026-10-18T00:51:01.773Z", "running": false }, { "chatId": "c-u12345-email:john@gmail.com-project:74262ac8-...-chat:1d9d42ed-...-bot:google-flow", "email": "john@gmail.com", "title": "Stylish Female Character Action Sequence", "created": "2026-10-17T03:50:34.000Z", "updated": "2026-10-17T04:57:26.375Z", "running": false } ] } ``` Xóa nội dung một cuộc chat. Lệnh trả về `204` không có body, cuộc chat biến mất khỏi danh sách và ứng dụng web Google Flow, còn ảnh và video nó đã tạo vẫn ở lại trong project: ```bash curl -s -X DELETE "$API/chats/$CHAT" -H "Authorization: Bearer $USEAPI_TOKEN" ``` Đổi tên và xóa trả về `409` khi một lượt đang chạy. ### Bước 7: Cài đặt phê duyệt, chỉ dẫn và model mặc định Mỗi project Google Flow có cài đặt agent riêng, giống bảng agent trong ứng dụng web Google Flow. [GET /agent/settings](/docs/api-google-flow-v1/get-google-flow-agent-settings) đọc chúng, đồng thời liệt kê các model ảnh và video mà gói Google của tài khoản có, kèm chi phí một ảnh hoặc một video trên gói đó: ```bash curl -s "$API/settings?email=$EMAIL" -H "Authorization: Bearer $USEAPI_TOKEN" ``` [PUT /agent/settings](/docs/api-google-flow-v1/put-google-flow-agent-settings) chỉ đổi những trường bạn gửi. Trước lần chạy, chúng tôi đặt chế độ `ask` và các giá trị mặc định: ```bash curl -s -X PUT "$API/settings" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$EMAIL"'", "approval": "ask", "imageDefaults": { "model": "nano-banana-2", "aspectRatio": "1:1", "count": 2 }, "videoDefaults": { "model": "omni-flash", "aspectRatio": "16:9", "count": 1 } }' ``` Phản hồi là cài đặt của project sau khi thay đổi: ```json { "projectId": "74262ac8-a54f-4ad7-80d7-3d44a4d6c6c1", "approval": "ask", "instructions": [], "imageDefaults": { "model": "nano-banana-2", "aspectRatio": "1:1", "count": 2 }, "videoDefaults": { "model": "omni-flash", "aspectRatio": "16:9", "count": 1 }, "models": { "image": [ { "model": "nano-banana-pro", "label": "Nano Banana Pro", "credits": 0 }, { "model": "nano-banana-2-lite", "label": "Nano Banana 2 Lite", "credits": 0 }, { "model": "nano-banana-2", "label": "Nano Banana 2.1", "credits": 0 } ], "video": [ { "model": "omni-flash", "label": "Omni 1.1 Flash", "credits": 4 }, { "model": "veo-3.1-lite", "label": "Veo 3.1 - Lite", "credits": 5 }, { "model": "veo-3.1-fast", "label": "Veo 3.1 - Fast", "credits": 10 }, { "model": "veo-3.1-quality", "label": "Veo 3.1 - Quality", "credits": 100 } ] } } ``` `credits` là chi phí thấp nhất của một ảnh hoặc một video trên gói của tài khoản, nên video dài hơn hoặc độ phân giải cao hơn sẽ tốn hơn: video Omni 1.1 Flash 6 giây 720p của chúng tôi tốn 10, còn bản sửa 8 giây lẽ ra tốn 12. Gói của bạn có thể hiện số khác. Các trường cài đặt: - `approval`: `ask` (agent dừng lại và cho thấy chi phí) hoặc `auto` (chi mà không hỏi). - `instructions`: tối đa 3 chỉ dẫn cố định mà agent tuân theo trong mọi cuộc chat của project, mỗi chỉ dẫn có thể kèm ảnh tham chiếu. Mảng này thay thế các chỉ dẫn của project, nên hãy gửi cả danh sách. - `imageDefaults` và `videoDefaults`: model, tỷ lệ khung hình và số lượng agent dùng khi tin nhắn không nói khác, chọn từ `models`. Cài đặt áp dụng cho mọi cuộc chat trong project, kể cả các cuộc chat trong ứng dụng web Google Flow. ### Làm điều tương tự từ trợ lý AI [MCP server Google Flow](/docs/api-google-flow-v1/mcp) được host sẵn cung cấp cho Claude Code, Cursor, VS Code và các MCP client khác cùng tính năng chat này dưới dạng 12 công cụ, không cần cài gì. Trong Claude Code: ```bash claude mcp add --transport http useapi-google-flow https://api.useapi.net/v1/google-flow/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` Rồi chỉ cần nhờ trợ lý chụp ảnh chiếc cốc bằng lời thường. Trợ lý gửi yêu cầu bằng `flow_agent_chat` và trả lời yêu cầu dùng credit của agent bằng `flow_agent_answer_approval`. Server có trong MCP Registry chính thức với tên `net.useapi/google-flow`. Muốn xem trước một chat client hoàn chỉnh, hãy mở [bản demo trực tiếp](/demos/google-flow/). Dán API token, chọn tài khoản và trò chuyện với agent, có ảnh và video ngay trong khung chat, file đính kèm, thẻ phê duyệt và cài đặt. Mã nguồn là năm file nhỏ không cần bước build, trên GitHub tại [google-flow-api/demo](https://github.com/useapi/google-flow-api/tree/main/demo), và trang [Agent Live Demo](/docs/api-google-flow-v1/agent-demo) ghép mỗi tính năng với lệnh gọi API của nó. ### Ví dụ Những gì lần chạy này tạo ra, không chỉnh sửa. Prompt là do chính agent viết từ yêu cầu của chúng tôi. ###### Nano Banana 2.1 » hai ảnh sản phẩm chiếc cốc màu xanh xô thơm (lượt 2) {: .no_toc #nano-banana-21--two-product-shots-of-the-sage-green-mug-turn-2 } <div style="display: flex; gap: 2%; flex-wrap: wrap"> <figure style="margin: 0; width: 49%"><a href="https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-shot-1-nano-banana-2-1.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-shot-1-nano-banana-2-1.jpg" alt="Kết quả của Google Flow Agent: chiếc cốc gốm màu xanh xô thơm mờ trên bàn gỗ sồi sáng màu trong nắng sớm dịu nhẹ, tạo bằng Nano Banana 2.1" style="width: 100%" loading="lazy"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">Option 1, "Ceramic coffee mug on table"</figcaption></figure> <figure style="margin: 0; width: 49%"><a href="https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-shot-2-nano-banana-2-1.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-shot-2-nano-banana-2-1.jpg" alt="Kết quả của Google Flow Agent: cận cảnh chiếc cốc xanh xô thơm đựng cà phê, một chiếc thìa đồng và cuốn sách mở dưới nắng sớm, tạo bằng Nano Banana 2.1" style="width: 100%" loading="lazy"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">Option 2, ảnh cận cảnh</figcaption></figure> </div> Cả hai đều là JPEG 1024×1024, 0 credit trên gói của tài khoản này. ###### Omni 1.1 Flash » 6 giây hơi nước bốc lên từ chiếc cốc (lượt 2) {: .no_toc #omni-11-flash--6-seconds-of-steam-rising-from-the-mug-turn-2 } <video poster="https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-steam-omni-1-1-flash-6s-poster.jpg" src="https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-steam-omni-1-1-flash-6s.mp4" style="width: 100%; aspect-ratio: 16/9; max-width: 720px" controls type="video/mp4" preload="metadata"></video> 1280×720 có âm thanh, 6 giây, 10 credit. Hướng dẫn liên quan: [video Veo 3.1 qua Google Flow API](/docs/articles/google-flow-bash-vi), [video có âm thanh gốc với Omni Flash](/docs/articles/omni-flash-bash-vi) và [ảnh Nano Banana qua Google Flow API](/docs/articles/google-flow-images-bash-vi). ### Câu hỏi thường gặp - **Có API cho Google Flow Agent không?** Qua useapi.net thì có: [Agent API](/docs/api-google-flow-v1/agent) bắt đầu chat, stream phản hồi qua Server-Sent Events, trả lời phê duyệt và trả về ảnh, video, trên mọi gói Google AI, kể cả tài khoản miễn phí. Google chỉ cung cấp [Flow Agent](https://support.google.com/labs/answer/17093911?hl=vi) bên trong ứng dụng web Google Flow, không có API công khai riêng (tính đến tháng 11/2026). - **Trò chuyện với Google Flow Agent tốn bao nhiêu?** Qua useapi.net, trò chuyện không tốn credit Flow, còn những gì agent tạo có giá thông thường của Google Flow, và chế độ `ask` hiện giá đó trước khi chi. Video Omni 1.1 Flash 6 giây 720p trong lần chạy này có giá $0,08 trên Google AI Ultra $199,99, so với $0,61 trên [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) chính thức (tính đến tháng 11/2026). - **Cuộc chat bắt đầu trong ứng dụng web Google Flow có hiện trong API không?** Qua useapi.net thì có, khi chúng ở cùng project. [GET /agent/chats](/docs/api-google-flow-v1/get-google-flow-agent-chats) liệt kê chúng, và mọi endpoint ở trên đều dùng được với chúng. Cuộc chat bắt đầu qua API cũng hiện trong ứng dụng web. Truyền `projectId` từ [GET /assets/projects/`email`](/docs/api-google-flow-v1/get-google-flow-assets-projects-email) để làm việc trong một project khác project riêng của agent. - **Có thể nhận webhook thay vì giữ stream mở không?** Qua useapi.net thì được. Truyền `replyUrl` cho [POST /agent/chats](/docs/api-google-flow-v1/post-google-flow-agent-chats#callback), lệnh gửi tin nhắn hoặc lệnh phê duyệt, và khi lượt kết thúc API sẽ gửi một `POST` gồm tin nhắn, media, trạng thái và yêu cầu phê duyệt đang chờ (nếu có) của lượt đó. Video thường tới đó khi vẫn còn `queued`, nên hãy lấy link của chúng bằng GET hoặc từ sự kiện `media` của stream. - **Có những giới hạn nào?** Qua useapi.net, mỗi cuộc chat chạy từng lượt một, mỗi tài khoản chạy tối đa 3 lượt cùng lúc, và một lượt kéo dài tối đa 10 phút, đây là giới hạn của chính Google. Google cũng giới hạn số tin nhắn gửi agent mỗi ngày cho mỗi tài khoản mà không công bố con số, và API trả về `429` cho tài khoản đó tới nửa đêm UTC. Xem [Giới hạn](/docs/api-google-flow-v1/agent#limits). ### Kết luận Ghé <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> hoặc <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> của chúng tôi cho mọi câu hỏi hỗ trợ. Xem [repo GitHub](https://github.com/useapi/google-flow-api) của chúng tôi với các ví dụ code, gồm cả chat client của agent trong [`demo/`](https://github.com/useapi/google-flow-api/tree/main/demo). Trợ lý AI cũng có thể trò chuyện với Google Flow Agent thay bạn: [MCP server Google Flow](/docs/api-google-flow-v1/mcp) được host sẵn chạy với Claude Code, Cursor và VS Code, trên tài khoản Google Flow của bạn. ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-flow-agent-chat-zh === Document URL: https://useapi.net/docs/articles/google-flow-agent-chat-zh --- layout: default title: "如何通过 Google Flow API 与 Google Flow Agent 对话" description: "通过 useapi.net 的 Google Flow API 用代码与 Google Flow Agent 对话:开始对话、通过 SSE 流式接收回复、批准积分消耗并取回图片和视频,全程使用 curl。" keywords: [Google Flow Agent API, Google Flow Agent, Flow Agent API, Google Flow API, AI agent API, Server-Sent Events, SSE, approval, Nano Banana 2.1, Omni 1.1 Flash, MCP server, Claude Code, curl, Google Flow Agent 教程, AI 智能体 API, 流式输出, 中文教程, Chinese tutorial] image: https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-shot-2-nano-banana-2-1.jpg parent: Articles nav_exclude: true lang: zh-CN translation_key: google-flow-agent-chat date: 2026-10-17 last_modified: 2026-11-10 nav_order: 903 repo: https://github.com/useapi/google-flow-api --- ## 如何通过 Google Flow API 与 Google Flow Agent 对话 {: .no_toc #how-to-chat-with-google-flow-agent-via-the-google-flow-api } 8 分钟阅读 • 2026 年 10 月 17 日(2026 年 11 月 10 日更新) useapi.net 是第三方 API,与 Google 无关联,也未获得 Google 的认可。 ## 目录 {: .no_toc .text-delta #table-of-contents } ### 简介 useapi.net 的 Google Flow API 让你的代码可以与 Google Flow Agent 对话。Google Flow Agent 是 [Google Flow](https://flow.google.com) 内置的创意助手:用一条 `curl` 开始对话,流式接收它的回复,批准它想要的积分消耗,再下载它生成的图片和视频。Google 只在 Google Flow 网页应用中提供 [Flow Agent](https://support.google.com/labs/answer/17093911?hl=zh-CN),没有公开 API(截至 2026 年 11 月)。useapi.net 是[第三方](/docs/legal#affiliation--third-party-services) API,与 Google 无关联,对话运行在你自己的 Google Flow 账号上,免费账号和付费账号都可以。与 Agent 对话本身不消耗积分,它生成的图片和视频按 Google Flow 的常规价格计费。 本指南完整记录了一次真实运行。我们让 Agent 为一只陶瓷咖啡杯拍两张产品图,再做一段 6 秒的视频,批准了消耗,取回了成品,然后又要求修改一次,并拒绝了那次修改。下面的每个响应都来自这次运行,做了删减,账号邮箱也已替换。 Agent 会自己规划工作。它根据项目的[设置](#step-7-settings-for-approval-instructions-and-default-models)选择工具和模型,整段对话都保存在 Google 那边,所以几小时甚至几天后继续对话,上下文依然完整。所有规则和限制见 [Agent 概览](/docs/api-google-flow-v1/agent)。 ### 开始之前 你需要一个 useapi.net [API Token](/docs/start-here/setup-useapi),以及一个通过 [设置 Google Flow](/docs/start-here/setup-google-flow) 连接好的 Google 账号。Agent 在所有 Google AI 订阅上都能用,包括免费账号。它能生成什么取决于账号的订阅,和 [POST /images](/docs/api-google-flow-v1/post-google-flow-images)、[POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) 一样。 每一轮对话要用一次验证码,由 API 通过你的[验证码服务商](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers)或你第一个账号自带的免费验证码额度自动解决,你不需要为此发送任何东西。 下面的步骤使用 `curl`、`jq` 和三个 shell 变量: ```bash export USEAPI_TOKEN="user:12345-..." # 你的 useapi.net API Token export EMAIL="john@gmail.com" # 一个已连接的 Google Flow 账号 API="https://api.useapi.net/v1/google-flow/agent" ``` 下面的每个调用也都在 [Postman 集合](https://www.postman.com/useapinet/useapi-net)里。 ### 对话如何进行 一轮(turn)是你发出的一条消息,加上 Agent 为回复它所做的一切。一个对话一次只运行一轮: 1. [POST /agent/chats](/docs/api-google-flow-v1/post-google-flow-agent-chats) 开始对话,返回 `202` 和一个 `chatId`。 2. [GET /agent/chats/`chatId`/stream](/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId-stream) 通过 Server-Sent Events 实时跟踪 Agent。 3. Agent 想要消耗积分时,会停下来询问。用 [POST /agent/chats/`chatId`/approval](/docs/api-google-flow-v1/post-google-flow-agent-chats-chatId-approval) 回答。 4. [POST /agent/chats/`chatId`/messages](/docs/api-google-flow-v1/post-google-flow-agent-chats-chatId-messages) 发送下一条消息。 5. [GET /agent/chats/`chatId`](/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId) 读取整个对话,媒体链接是新生成的。 ### 第 1 步:开始对话 把需求写在 `message` 里发送。Google 接受这一轮后调用就会返回,通常只要几秒,最长可能约 100 秒,所以给 `curl` 设置 150 秒超时: ```bash curl -s --max-time 150 -X POST "$API/chats" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$EMAIL"'", "message": "Create two product shots of a matte sage-green ceramic coffee mug on a light oak table in soft morning window light, square format, with Nano Banana 2.1. Then make one 6 second video of the same mug with steam slowly rising from the coffee, with Omni 1.1 Flash." }' ``` 我们的请求大约 10 秒后返回 `202`: ```json { "chatId": "c-u12345-email:john@gmail.com-project:74262ac8-a54f-4ad7-80d7-3d44a4d6c6c1-chat:55023a0f-5e70-4545-bb4a-d878038dcf35-bot:google-flow", "email": "john@gmail.com", "turn": 1, "status": "running" } ``` `chatId` 里已经包含账号和项目,所以后续调用两者都不用再传。它含有 `:` 和 `@`,放进路径时要做 URL 编码。两种形式都保留: ```bash CHATID="c-u12345-email:john@gmail.com-project:74262ac8-...-bot:google-flow" CHAT=$(jq -rn --arg v "$CHATID" '$v|@uri') ``` 不传 `projectId` 时,对话放在账号自己的 Agent 项目里。这个项目在第一次对话时创建,名字类似 `My Agents Work Fri, Oct 16`,让 Agent 的作品和你在 Google Flow 中的其他媒体分开。任何一条消息都可以附带最多 7 张图片、1 段视频、5 个音色和 7 个角色,`@` 提及语法与 [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) 相同,详见 [POST /agent/chats](/docs/api-google-flow-v1/post-google-flow-agent-chats#request-body)。 ### 第 2 步:流式接收回复 用 `-N` 打开流,事件一到就会打印出来。浏览器的 `EventSource` 无法发送 `Authorization` 请求头,所以在应用里请用 `fetch()` 或任意 HTTP 客户端: ```bash curl -s -N "$API/chats/$CHAT/stream" \ -H "Authorization: Bearer $USEAPI_TOKEN" ``` 新打开的流先发送一个 `chat` 事件,回放对话历史,然后发送 `replayed`。`replayed` 之后的内容都是实时的。这里我们连上时第一轮已经结束,所以它出现在回放中。Agent 先说明了计划,然后请求允许花 10 积分生成 2 张图片和 1 段视频(省略了 `ui` 和其他较长的字段): ``` event: chat data: {"chatId":"c-u12345-email:john@gmail.com-project:74262ac8-...-bot:google-flow","status":"waiting_approval","turns":1} id: 1:505e78d7-bd79-4938-b0ec-8117bdb933dc event: message data: {"id":"1:505e78d7-...","turn":1,"items":[{"kind":"text","text":"I'm going to generate two images of a matte sage-green ceramic coffee mug, then I'll create a 6-second video of the same mug with rising steam using Omni 1.1 Flash."}]} id: 1:00c21a03-a687-4173-9fd9-190fcdf2447b event: message data: {"id":"1:00c21a03-...","turn":1,"items":[{"kind":"tool_call","tool":"open_chat_panel","args":{"_synthetic":true}},{"kind":"tool_call","tool":"ask_for_permission","args":{"num_total":3,"total_cost":10,"num_videos":1,"num_images":2}}]} id: 1:approval event: approval data: {"turn":1,"cost":10,"images":2,"videos":1,"total":3} event: replayed data: {"turns":1} ``` 需要处理的事件: | 事件 | 含义 | |---|---| | `message` | Agent 的一条完整消息:文字、思考、工具调用和工具结果 | | `approval` | Agent 在消耗 `cost` 个 Flow 积分之前请求许可 | | `turn` | 一轮结束:`completed`、`waiting_approval`,或带 `error` 的 `failed` | | `media` | Agent 生成的图片或视频,或其状态变化,`completed` 时带 `url` | 每 15 秒会有一个 `keepalive`。一个流覆盖整个对话的所有轮次,所以在批准和发送消息期间保持它打开即可。如果连接断开,在 `Last-Event-ID` 请求头里带上最后一个 `id` 重新连接,就会从断开处继续。关闭流时一轮仍会继续运行,不会丢失任何内容。 ### 第 3 步:批准消耗 在 `ask` 审批模式下,Agent 在花费任何积分之前都会停下来。对话的 `status` 是 `waiting_approval`,`approval` 事件显示费用。请在大约 4 分钟内用 `approve`、`always` 或 `reject` 回答: ```bash curl -s --max-time 150 -X POST "$API/chats/$CHAT/approval" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "decision": "approve" }' ``` 自 2026 年 11 月 10 日 Google 修改 Flow Agent 以来,回答会延续发出请求的那一轮(这里是第 1 轮,而不是新的第 2 轮),而且只有在那一轮仍然开放时 Google 才会接受,也就是请求发出后约 4 分钟内。更晚的回答会得到 `409`:请重新发送消息,或者按[第 7 步](#step-7-settings-for-approval-instructions-and-default-models)把项目设为 `approval: "auto"`,让 Agent 不再询问。下面的运行记录于这次变更之前,所以它的回答开启了第 2 轮,其中的工具名(`generate_video_from_text`)现在会显示为 `generate_image` 和 `generate_video`。 回答后 Agent 重新开始工作: ```json { "chatId": "c-u12345-email:john@gmail.com-project:74262ac8-...-bot:google-flow", "email": "john@gmail.com", "turn": 2, "status": "running" } ``` 在打开的流上,第 2 轮把视频排入队列,生成了两张图片,并在约 30 秒内结束。Agent 的 `choices`(`Option 1`、`Option 2`)就是 Google Flow 网页应用为每个结果显示的图块: ``` id: 2:5feb253e-0848-422a-bcb8-936995b3c0df event: message data: {"id":"2:5feb253e-...","turn":2,"items":[{"kind":"tool_result","tool":"generate_video_from_text","result":{"status":"queued","media_id":"5732c66d-a971-4cd0-92d2-508ef0aecc07","display_name":"Steam rising from coffee mug","model_key":"abra_t2v_6s","aspect_ratio":"VIDEO_ASPECT_RATIO_LANDSCAPE"}}]} id: 2:m:5732c66d-a971-4cd0-92d2-508ef0aecc07 event: media data: {"turn":2,"referenceId":"user:12345-email:6a6f...-video:5732c66d-a971-4cd0-92d2-508ef0aecc07","mediaId":"5732c66d-a971-4cd0-92d2-508ef0aecc07","type":"video","status":"queued","tool":"generate_video_from_text","model":"abra_t2v_6s","displayName":"Steam rising from coffee mug"} id: 2:m:377ecb33-ab2c-4bce-92d4-7bfcf53a9af2 event: media data: {"turn":2,"referenceId":"user:12345-email:6a6f...-image:377ecb33-ab2c-4bce-92d4-7bfcf53a9af2","mediaId":"377ecb33-ab2c-4bce-92d4-7bfcf53a9af2","type":"image","status":"completed","tool":"generate_image","displayName":"Ceramic coffee mug on table","url":"https://flow-content.google/image/377ecb33-...?Expires=...&Signature=..."} id: 2:4e37b051-c49c-4331-bc0c-06ccc539b950 event: message data: {"id":"2:4e37b051-...","turn":2,"items":[{"kind":"text","text":"I've generated your two product shots. Your 6-second video has been scheduled and is waiting in the queue due to high demand. Feel free to check back in a few minutes."}]} id: 2:end event: turn data: {"turn":2,"status":"completed"} ``` `always` 会批准,同时把项目切换到 `auto` 模式,于是 Agent 在该项目的所有对话中都不再询问。`reject` 表示拒绝,见[第 5 步](#step-5-continue-or-revise)。有请求在等待时,发送新消息会得到 `409`:请先回答请求。 ### 第 4 步:取回媒体 一轮结束时图片就已就绪。视频通常再过一两分钟完成,完成时流会为视频再发送一个 `media` 事件。我们的视频在这一轮结束后不到一分钟就到了: ``` id: 2:m:5732c66d-a971-4cd0-92d2-508ef0aecc07 event: media data: {"turn":2,"referenceId":"user:12345-email:6a6f...-video:5732c66d-a971-4cd0-92d2-508ef0aecc07","mediaId":"5732c66d-a971-4cd0-92d2-508ef0aecc07","type":"video","status":"completed","tool":"generate_video_from_text","model":"abra_t2v_6s","displayName":"Steam rising from coffee mug","url":"https://flow-content.google/video/5732c66d-...?Expires=...&Signature=...","durationSec":6} ``` 趁链接还新鲜,下载每个 `url`: ```bash curl -s -L -o mug-steam.mp4 "https://flow-content.google/video/5732c66d-...?Expires=...&Signature=..." ``` 这些链接指向 Google,签发后约 6 小时过期。要获取新链接,可以用 [GET /agent/chats/`chatId`](#step-6-read-list-rename-and-delete-chats) 重新读取对话,或者用某一项的 `referenceId` 通过 [GET /assets/`mediaGenerationId`](/docs/api-google-flow-v1/get-google-flow-assets-mediagenerationid) 获取它的链接。`referenceId` 还可以作为 `referenceImage_N` 或 `referenceVideo_1` 用在 [POST /images](/docs/api-google-flow-v1/post-google-flow-images)、[POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) 和你给 Agent 的下一条消息中。两张图片和 1280×720 的视频见[示例](#examples)。 这次运行花了 10 积分:两张 Nano Banana 2.1 图片在这个账号的订阅上是 0 积分,6 秒的 Omni 1.1 Flash 视频是 10 积分。 ### 第 5 步:继续或修改 把下一条消息发到同一个对话。Google 保留着整段对话,所以 Agent 知道“那段视频”指的是哪一段: ```bash curl -s --max-time 150 -X POST "$API/chats/$CHAT/messages" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "message": "Nice. Revise the video: make it 8 seconds, with a slow camera push-in toward the mug while the steam rises." }' ``` 它返回了 `202` 和 `"turn": 3`,Agent 再次请求许可,这次是 12 积分: ``` id: 3:approval event: approval data: {"turn":3,"cost":12,"images":0,"videos":1,"total":1} id: 3:end event: turn data: {"turn":3,"status":"waiting_approval"} ``` 我们已经有了视频,所以拒绝了: ```bash curl -s --max-time 150 -X POST "$API/chats/$CHAT/approval" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "decision": "reject" }' ``` 第 4 轮以一条回复结束,没有新的图片或视频,也没有消耗积分: ``` id: 4:91e06fb7-ba5b-4e32-b2a6-ce210be491ba event: message data: {"id":"4:91e06fb7-...","turn":4,"items":[{"kind":"text","text":"I've cancelled that generation. Are there any changes you'd like to make to the prompt or concept before we try again?"}]} id: 4:end event: turn data: {"turn":4,"status":"completed"} ``` 一轮运行期间发送消息会得到 `409`,所以请先等 `turn` 事件。要选择 Agent 给出的某个选项,就像 Google Flow 网页应用那样,把该选项的文字作为下一条消息发送。 ### 第 6 步:读取、列出、重命名和删除对话 随时可以从 Google 读取整个对话。每一轮都包含你的消息、Agent 做的一切,以及带新链接的媒体: ```bash curl -s "$API/chats/$CHAT" -H "Authorization: Bearer $USEAPI_TOKEN" ``` 四轮之后我们的对话(`agent` 项和 `media` 做了删减,省略了 `ui`): ```json { "chatId": "c-u12345-email:john@gmail.com-project:74262ac8-...-bot:google-flow", "email": "john@gmail.com", "projectId": "74262ac8-a54f-4ad7-80d7-3d44a4d6c6c1", "title": "Sage Green Ceramic Mug Concept", "created": "2026-10-18T00:47:54.000Z", "updated": "2026-10-18T00:50:47.236Z", "status": "idle", "pendingApproval": null, "lastError": null, "turns": [ { "turn": 1, "message": { "text": "Create two product shots of a matte sage-green ceramic coffee mug ...", "references": [] }, "agent": [ { "kind": "text", "text": "I'm going to generate two images of a matte sage-green ceramic coffee mug, then I'll create a 6-second video ..." }, { "kind": "tool_call", "tool": "ask_for_permission", "args": { "num_total": 3, "total_cost": 10, "num_videos": 1, "num_images": 2 } } ], "media": [] }, { "turn": 2, "message": { "text": "Approve", "references": [] }, "agent": [ { "kind": "tool_call", "tool": "generate_video_from_text", "args": { "duration": 6, "aspect_ratio": "16:9", "model_display_name": "Omni 1.1 Flash", "prompt": "Cinematic product video of a matte sage-green ceramic coffee mug ..." } }, { "kind": "tool_call", "tool": "generate_image", "args": { "aspect_ratio": "1:1", "prompt": "A professional product shot of a matte sage-green ceramic coffee mug ..." } }, { "kind": "text", "text": "I've generated your two product shots. Your 6-second video has been scheduled ..." } ], "media": [ { "referenceId": "user:12345-email:6a6f...-video:5732c66d-...", "type": "video", "status": "completed", "model": "abra_t2v_6s", "displayName": "Steam rising from coffee mug", "url": "https://flow-content.google/video/5732c66d-...", "durationSec": 6 }, { "referenceId": "user:12345-email:6a6f...-image:377ecb33-...", "type": "image", "status": "completed", "displayName": "Ceramic coffee mug on table", "url": "https://flow-content.google/image/377ecb33-..." }, { "referenceId": "user:12345-email:6a6f...-image:a2d3cd0c-...", "type": "image", "status": "completed", "displayName": "Ceramic coffee mug on wooden sur…", "url": "https://flow-content.google/image/a2d3cd0c-..." } ] }, { "turn": 3, "message": { "text": "Nice. Revise the video: make it 8 seconds, ...", "references": [] }, "agent": ["..."], "media": [] }, { "turn": 4, "message": { "text": "Reject", "references": [] }, "agent": [{ "kind": "text", "text": "I've cancelled that generation. Are there any changes you'd like to make to the prompt or concept before we try again?" }], "media": [] } ] } ``` 对话标题是 Google 自己起的。没有任何东西在运行时 `status` 为 `idle`,Agent 等待批准时 `pendingApproval` 中保存着费用。传 `?media=false` 可以跳过链接刷新,读取更快。 列出一个账号的对话,最近有活动的排在最前。列表来自 Google,所以也包含同一项目中在 Google Flow 网页应用里开始的对话,丢失 `chatId` 时也靠它找回: ```bash curl -s "$API/chats?email=$EMAIL" -H "Authorization: Bearer $USEAPI_TOKEN" ``` 重命名对话。新标题在 Google Flow 网页应用里也会显示: ```bash curl -s -X PATCH "$API/chats/$CHAT" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "title": "Sage mug product shoot" }' ``` ```json { "chatId": "c-u12345-email:john@gmail.com-project:74262ac8-...-bot:google-flow", "title": "Sage mug product shoot" } ``` 之后的列表如下: ```json { "chats": [ { "chatId": "c-u12345-email:john@gmail.com-project:74262ac8-...-chat:55023a0f-...-bot:google-flow", "email": "john@gmail.com", "title": "Sage mug product shoot", "created": "2026-10-18T00:47:54.000Z", "updated": "2026-10-18T00:51:01.773Z", "running": false }, { "chatId": "c-u12345-email:john@gmail.com-project:74262ac8-...-chat:1d9d42ed-...-bot:google-flow", "email": "john@gmail.com", "title": "Stylish Female Character Action Sequence", "created": "2026-10-17T03:50:34.000Z", "updated": "2026-10-17T04:57:26.375Z", "running": false } ] } ``` 删除对话的内容。它返回 `204`,没有响应体,对话会从列表和 Google Flow 网页应用中消失,而它生成的图片和视频仍保留在项目里: ```bash curl -s -X DELETE "$API/chats/$CHAT" -H "Authorization: Bearer $USEAPI_TOKEN" ``` 一轮运行期间,重命名和删除会返回 `409`。 ### 第 7 步:审批、指令和默认模型的设置 每个 Google Flow 项目都有 Agent 设置,和 Google Flow 网页应用里的 Agent 面板一样。[GET /agent/settings](/docs/api-google-flow-v1/get-google-flow-agent-settings) 读取这些设置,同时列出账号的 Google 订阅可用的图片和视频模型,以及在该订阅上生成一张图片或一段视频的费用: ```bash curl -s "$API/settings?email=$EMAIL" -H "Authorization: Bearer $USEAPI_TOKEN" ``` [PUT /agent/settings](/docs/api-google-flow-v1/put-google-flow-agent-settings) 只修改你发送的字段。运行之前,我们设置了 `ask` 模式和默认值: ```bash curl -s -X PUT "$API/settings" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$EMAIL"'", "approval": "ask", "imageDefaults": { "model": "nano-banana-2", "aspectRatio": "1:1", "count": 2 }, "videoDefaults": { "model": "omni-flash", "aspectRatio": "16:9", "count": 1 } }' ``` 响应是修改后的项目设置: ```json { "projectId": "74262ac8-a54f-4ad7-80d7-3d44a4d6c6c1", "approval": "ask", "instructions": [], "imageDefaults": { "model": "nano-banana-2", "aspectRatio": "1:1", "count": 2 }, "videoDefaults": { "model": "omni-flash", "aspectRatio": "16:9", "count": 1 }, "models": { "image": [ { "model": "nano-banana-pro", "label": "Nano Banana Pro", "credits": 0 }, { "model": "nano-banana-2-lite", "label": "Nano Banana 2 Lite", "credits": 0 }, { "model": "nano-banana-2", "label": "Nano Banana 2.1", "credits": 0 } ], "video": [ { "model": "omni-flash", "label": "Omni 1.1 Flash", "credits": 4 }, { "model": "veo-3.1-lite", "label": "Veo 3.1 - Lite", "credits": 5 }, { "model": "veo-3.1-fast", "label": "Veo 3.1 - Fast", "credits": 10 }, { "model": "veo-3.1-quality", "label": "Veo 3.1 - Quality", "credits": 100 } ] } } ``` `credits` 是在该账号订阅上生成一张图片或一段视频的最低费用,所以更长或分辨率更高的视频会更贵:我们 6 秒 720p 的 Omni 1.1 Flash 视频花了 10 积分,8 秒的修改版本则会花 12 积分。你的订阅显示的数字可能不同。设置字段: - `approval`:`ask`(Agent 停下来并显示费用)或 `auto`(直接消耗,不询问)。 - `instructions`:最多 3 条常驻指令,Agent 在该项目的每个对话中都会遵循,每条可以附带参考图。这个数组会替换项目现有的指令,所以要发送完整列表。 - `imageDefaults` 和 `videoDefaults`:消息没有另外说明时 Agent 使用的模型、宽高比和数量,从 `models` 中选择。 这些设置适用于项目中的每个对话,包括 Google Flow 网页应用中的对话。 ### 用 AI 助手做同样的事 托管的 [Google Flow MCP 服务器](/docs/api-google-flow-v1/mcp)以 12 个工具的形式,为 Claude Code、Cursor、VS Code 和其他 MCP 客户端提供同样的对话功能,无需安装任何东西。在 Claude Code 中: ```bash claude mcp add --transport http useapi-google-flow https://api.useapi.net/v1/google-flow/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` 然后用普通的话让助手拍杯子的产品图。助手用 `flow_agent_chat` 发送需求,用 `flow_agent_answer_approval` 回答 Agent 的积分消耗请求。该服务器在官方 MCP Registry 中的名称是 `net.useapi/google-flow`。 想先看一个完整的聊天客户端,可以打开[在线演示](/demos/google-flow/)。粘贴你的 API Token,选择账号,就能与 Agent 对话,图片和视频直接显示在对话中,还有附件、审批卡片和设置。它的源代码是 GitHub 上 [google-flow-api/demo](https://github.com/useapi/google-flow-api/tree/main/demo) 里的五个小文件,无需构建,[Agent 在线演示](/docs/api-google-flow-v1/agent-demo)页面把每个功能对应到它的 API 调用。 ### 示例 这次运行的成品,未经任何编辑。提示词是 Agent 根据我们的需求自己写的。 ###### Nano Banana 2.1 » 绿色陶瓷杯的两张产品图(第 2 轮) {: .no_toc #nano-banana-21--two-product-shots-of-the-sage-green-mug-turn-2 } <div style="display: flex; gap: 2%; flex-wrap: wrap"> <figure style="margin: 0; width: 49%"><a href="https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-shot-1-nano-banana-2-1.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-shot-1-nano-banana-2-1.jpg" alt="Google Flow Agent 的结果:浅橡木桌上的哑光鼠尾草绿陶瓷杯,柔和的晨光,由 Nano Banana 2.1 生成" style="width: 100%" loading="lazy"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">Option 1,“Ceramic coffee mug on table”</figcaption></figure> <figure style="margin: 0; width: 49%"><a href="https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-shot-2-nano-banana-2-1.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-shot-2-nano-banana-2-1.jpg" alt="Google Flow Agent 的结果:晨光中盛着咖啡的鼠尾草绿杯子特写,旁边有黄铜勺和一本打开的书,由 Nano Banana 2.1 生成" style="width: 100%" loading="lazy"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">Option 2,特写</figcaption></figure> </div> 两张都是 1024×1024 的 JPEG,在这个账号的订阅上为 0 积分。 ###### Omni 1.1 Flash » 杯中热气升腾的 6 秒视频(第 2 轮) {: .no_toc #omni-11-flash--6-seconds-of-steam-rising-from-the-mug-turn-2 } <video poster="https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-steam-omni-1-1-flash-6s-poster.jpg" src="https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-steam-omni-1-1-flash-6s.mp4" style="width: 100%; aspect-ratio: 16/9; max-width: 720px" controls type="video/mp4" preload="metadata"></video> 1280×720,带声音,6 秒,10 积分。 相关教程:[Google Flow API 中文教程](/docs/articles/google-flow-api-zh)中的 Veo 3.1 视频部分、[用 Omni Flash 生成带原生音频的视频](/docs/articles/omni-flash-bash-zh),以及[通过 Google Flow API 生成 Nano Banana 图片](/docs/articles/google-flow-images-bash-zh)。 ### 常见问题 - **有 Google Flow Agent API 吗?** 通过 useapi.net 就有:[Agent API](/docs/api-google-flow-v1/agent) 可以开始对话、通过 Server-Sent Events 流式接收回复、回答审批并返回图片和视频,支持所有 Google AI 订阅,包括免费账号。Google 只在 Google Flow 网页应用中提供 [Flow Agent](https://support.google.com/labs/answer/17093911?hl=zh-CN),自己没有公开 API(截至 2026 年 11 月)。 - **与 Google Flow Agent 对话要花多少钱?** 通过 useapi.net,对话本身不消耗 Flow 积分,Agent 生成的内容按 Google Flow 的常规价格计费,`ask` 模式会在花费之前显示费用。本次运行中 6 秒 720p 的 Omni 1.1 Flash 视频,在 Google AI Ultra(199.99 美元)上是 0.08 美元,而官方 [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) 上是 0.61 美元(截至 2026 年 11 月)。 - **在 Google Flow 网页应用里开始的对话会出现在 API 中吗?** 通过 useapi.net 会,只要它们在同一个项目里。[GET /agent/chats](/docs/api-google-flow-v1/get-google-flow-agent-chats) 会列出它们,上面的每个接口都能用在这些对话上。通过 API 开始的对话也会出现在网页应用里。要在 Agent 自己的项目以外的项目中工作,请传入 [GET /assets/projects/`email`](/docs/api-google-flow-v1/get-google-flow-assets-projects-email) 返回的 `projectId`。 - **可以用 webhook 代替一直打开的流吗?** 通过 useapi.net 可以。在 [POST /agent/chats](/docs/api-google-flow-v1/post-google-flow-agent-chats#callback)、发送消息的调用或审批调用中传入 `replyUrl`,一轮结束时 API 会发送一次 `POST`,包含这一轮的消息、媒体、状态和任何待处理的审批。视频到达时通常仍是 `queued`,所以请通过 GET 或流的 `media` 事件获取它们的链接。 - **有哪些限制?** 通过 useapi.net,一个对话一次运行一轮,一个账号最多同时运行 3 轮,一轮最长 10 分钟,这是 Google 自己的限制。Google 还会限制每个账号每天的 Agent 消息数,但没有公布具体数字,达到上限后 API 会对该账号返回 `429`,直到 UTC 午夜。见[限制](/docs/api-google-flow-v1/agent#limits)。 ### 结语 有问题欢迎加入我们的 <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord 服务器</a> 或 <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram 频道</a>。 代码示例见我们的 [GitHub 仓库](https://github.com/useapi/google-flow-api),其中包括 [`demo/`](https://github.com/useapi/google-flow-api/tree/main/demo) 中的 Agent 聊天客户端。 AI 助手也可以替你与 Google Flow Agent 对话:托管的 [Google Flow MCP 服务器](/docs/api-google-flow-v1/mcp)支持 Claude Code、Cursor 和 VS Code,运行在你的 Google Flow 账号上。 ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-flow-agent-chat === Document URL: https://useapi.net/docs/articles/google-flow-agent-chat --- layout: default title: How to Chat with Google Flow Agent via the Google Flow API description: "Chat with Google Flow Agent from code through the useapi.net Google Flow API: start a chat, stream replies over SSE, approve credit spending and collect the images and videos, with curl." keywords: [Google Flow Agent API, Google Flow Agent, Flow Agent API, Google Flow API, AI agent API, Server-Sent Events, SSE, approval, Nano Banana 2.1, Omni 1.1 Flash, MCP server, Claude Code, curl, tutorial] image: https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-shot-2-nano-banana-2-1.jpg parent: Articles nav_exclude: true date: 2026-10-17 last_modified: 2026-11-10 nav_order: 903 repo: https://github.com/useapi/google-flow-api translation_key: google-flow-agent-chat --- ## How to Chat with Google Flow Agent via the Google Flow API 8 min read • October 17, 2026 (November 10, 2026) ## Table of contents ### Introduction The useapi.net Google Flow API lets your code chat with Google Flow Agent, the creative assistant built into [Google Flow](https://flow.google.com): start a chat with one `curl`, stream its replies, approve what it wants to spend and download the images and videos it makes. Google offers [Flow Agent](https://support.google.com/labs/answer/17093911) only inside the Flow web app, with no public API (as of November 2026). useapi.net is a [third-party](/docs/legal#affiliation--third-party-services) API, not affiliated with Google, and the chat runs on your Google Flow account, free or paid. Chatting with the agent costs no credits, and the images and videos it makes cost the usual Flow price. This guide is one real run, start to finish. We asked the agent for two product shots of a ceramic coffee mug and a 6-second video of it, approved the spend, collected the media, then asked for a revision and rejected that one. Every response below is from that run, trimmed and with the account's email replaced. The agent plans the work itself. It picks the tools and models, guided by the project's [settings](#step-7-settings-for-approval-instructions-and-default-models), and it keeps the whole conversation on Google's side, so a chat can go on hours or days later with full context. The [Agent Overview](/docs/api-google-flow-v1/agent) covers every rule and limit. ### Before you start You need a useapi.net [API token](/docs/start-here/setup-useapi) and a Google account connected through [Setup Google Flow](/docs/start-here/setup-google-flow). The agent works on every Google AI plan, including a free account, and what it can generate follows the account's plan, the same as [POST /images](/docs/api-google-flow-v1/post-google-flow-images) and [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos). Each turn uses one captcha, solved by the API with your [captcha providers](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers) or the free captcha credits of your first account. You do not send anything for it. The steps use `curl`, `jq` and three shell variables: ```bash export USEAPI_TOKEN="user:12345-..." # your useapi.net API token export EMAIL="john@gmail.com" # a connected Google Flow account API="https://api.useapi.net/v1/google-flow/agent" ``` Every call below is also in the [Postman collection](https://www.postman.com/useapinet/useapi-net). ### How a chat works A turn is one message from you and everything the agent does in reply. A chat runs one turn at a time: 1. [POST /agent/chats](/docs/api-google-flow-v1/post-google-flow-agent-chats) starts a chat and answers `202` with a `chatId`. 2. [GET /agent/chats/`chatId`/stream](/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId-stream) follows the agent live over Server-Sent Events. 3. When the agent wants to spend credits, it stops and asks. [POST /agent/chats/`chatId`/approval](/docs/api-google-flow-v1/post-google-flow-agent-chats-chatId-approval) answers. 4. [POST /agent/chats/`chatId`/messages](/docs/api-google-flow-v1/post-google-flow-agent-chats-chatId-messages) sends the next message. 5. [GET /agent/chats/`chatId`](/docs/api-google-flow-v1/get-google-flow-agent-chats-chatId) reads the whole chat, with fresh media links. ### Step 1: Start a chat Send the brief as `message`. The call returns as soon as Google has accepted the turn, which usually takes a few seconds and can take up to about 100 seconds, so give `curl` a 150-second timeout: ```bash curl -s --max-time 150 -X POST "$API/chats" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$EMAIL"'", "message": "Create two product shots of a matte sage-green ceramic coffee mug on a light oak table in soft morning window light, square format, with Nano Banana 2.1. Then make one 6 second video of the same mug with steam slowly rising from the coffee, with Omni 1.1 Flash." }' ``` Ours answered `202` in about 10 seconds: ```json { "chatId": "c-u12345-email:john@gmail.com-project:74262ac8-a54f-4ad7-80d7-3d44a4d6c6c1-chat:55023a0f-5e70-4545-bb4a-d878038dcf35-bot:google-flow", "email": "john@gmail.com", "turn": 1, "status": "running" } ``` The `chatId` names the account and the project, so later calls need neither. It contains `:` and `@`, so URL-encode it in the path. Keep both forms: ```bash CHATID="c-u12345-email:john@gmail.com-project:74262ac8-...-bot:google-flow" CHAT=$(jq -rn --arg v "$CHATID" '$v|@uri') ``` Without `projectId`, the chat lives in the account's own agent project, created on its first chat and named like `My Agents Work Fri, Oct 16`, which keeps agent work apart from your other Flow media. You can also attach up to 7 images, a video, 5 voices and 7 characters to any message with the same `@`-mention syntax as [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos), see [POST /agent/chats](/docs/api-google-flow-v1/post-google-flow-agent-chats#request-body). ### Step 2: Stream the reply Open the stream with `-N` so events print as they arrive. The browser's `EventSource` cannot send the `Authorization` header, so use `fetch()` or any HTTP client in an app: ```bash curl -s -N "$API/chats/$CHAT/stream" \ -H "Authorization: Bearer $USEAPI_TOKEN" ``` A new stream first sends a `chat` event, replays the chat's history, then sends `replayed`. Everything after `replayed` is live. Here the first turn had already ended when we connected, so it came in the replay. The agent stated its plan, then asked for permission to spend 10 credits on 2 images and 1 video (`ui` and other long fields left out): ``` event: chat data: {"chatId":"c-u12345-email:john@gmail.com-project:74262ac8-...-bot:google-flow","status":"waiting_approval","turns":1} id: 1:505e78d7-bd79-4938-b0ec-8117bdb933dc event: message data: {"id":"1:505e78d7-...","turn":1,"items":[{"kind":"text","text":"I'm going to generate two images of a matte sage-green ceramic coffee mug, then I'll create a 6-second video of the same mug with rising steam using Omni 1.1 Flash."}]} id: 1:00c21a03-a687-4173-9fd9-190fcdf2447b event: message data: {"id":"1:00c21a03-...","turn":1,"items":[{"kind":"tool_call","tool":"open_chat_panel","args":{"_synthetic":true}},{"kind":"tool_call","tool":"ask_for_permission","args":{"num_total":3,"total_cost":10,"num_videos":1,"num_images":2}}]} id: 1:approval event: approval data: {"turn":1,"cost":10,"images":2,"videos":1,"total":3} event: replayed data: {"turns":1} ``` The events you act on: | Event | What it means | |---|---| | `message` | One complete message of the agent: its text, thinking, tool calls and tool results | | `approval` | The agent asks before it spends `cost` Flow credits | | `turn` | A turn ended: `completed`, `waiting_approval` or `failed` with an `error` | | `media` | An image or video the agent made, or a change of its status, with its `url` once `completed` | A `keepalive` comes every 15 seconds. One stream covers the whole chat across turns, so leave it open while you approve and send messages. If it drops, reconnect with the last `id` in the `Last-Event-ID` header and it picks up where it left off. A turn keeps running when you close the stream, so nothing is lost. ### Step 3: Approve spending In the `ask` approval mode the agent stops before it spends anything. The chat's `status` is `waiting_approval` and the `approval` event shows the cost. Answer with `approve`, `always` or `reject` within about 4 minutes: ```bash curl -s --max-time 150 -X POST "$API/chats/$CHAT/approval" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "decision": "approve" }' ``` Since Google changed Flow Agent on November 10, 2026, the answer continues the turn that asked (turn 1 here, not a new turn 2), and Google takes it only while that turn is still open, about 4 minutes after the request. A later answer gets `409`: send the message again, or set the project to `approval: "auto"` in [step 7](#step-7-settings-for-approval-instructions-and-default-models) so the agent never asks. The run below was recorded before the change, so its answer started turn 2, and its tool names (`generate_video_from_text`) are now reported as `generate_image` and `generate_video`. The answer starts the agent working again: ```json { "chatId": "c-u12345-email:john@gmail.com-project:74262ac8-...-bot:google-flow", "email": "john@gmail.com", "turn": 2, "status": "running" } ``` On the open stream, turn 2 queued the video, made both images and ended within about 30 seconds. The agent's `choices` (`Option 1`, `Option 2`) are the tiles the Flow web app shows for each result: ``` id: 2:5feb253e-0848-422a-bcb8-936995b3c0df event: message data: {"id":"2:5feb253e-...","turn":2,"items":[{"kind":"tool_result","tool":"generate_video_from_text","result":{"status":"queued","media_id":"5732c66d-a971-4cd0-92d2-508ef0aecc07","display_name":"Steam rising from coffee mug","model_key":"abra_t2v_6s","aspect_ratio":"VIDEO_ASPECT_RATIO_LANDSCAPE"}}]} id: 2:m:5732c66d-a971-4cd0-92d2-508ef0aecc07 event: media data: {"turn":2,"referenceId":"user:12345-email:6a6f...-video:5732c66d-a971-4cd0-92d2-508ef0aecc07","mediaId":"5732c66d-a971-4cd0-92d2-508ef0aecc07","type":"video","status":"queued","tool":"generate_video_from_text","model":"abra_t2v_6s","displayName":"Steam rising from coffee mug"} id: 2:m:377ecb33-ab2c-4bce-92d4-7bfcf53a9af2 event: media data: {"turn":2,"referenceId":"user:12345-email:6a6f...-image:377ecb33-ab2c-4bce-92d4-7bfcf53a9af2","mediaId":"377ecb33-ab2c-4bce-92d4-7bfcf53a9af2","type":"image","status":"completed","tool":"generate_image","displayName":"Ceramic coffee mug on table","url":"https://flow-content.google/image/377ecb33-...?Expires=...&Signature=..."} id: 2:4e37b051-c49c-4331-bc0c-06ccc539b950 event: message data: {"id":"2:4e37b051-...","turn":2,"items":[{"kind":"text","text":"I've generated your two product shots. Your 6-second video has been scheduled and is waiting in the queue due to high demand. Feel free to check back in a few minutes."}]} id: 2:end event: turn data: {"turn":2,"status":"completed"} ``` `always` approves and also switches the project to the `auto` mode, so the agent stops asking in every chat of the project. `reject` declines, shown in [step 5](#step-5-continue-or-revise). While a request waits, a new message gets `409`: answer the request first. ### Step 4: Get the media Images are ready when the turn ends. Videos usually finish a minute or two later, and the stream sends a second `media` event for the video when it does. Ours came less than a minute after the turn ended: ``` id: 2:m:5732c66d-a971-4cd0-92d2-508ef0aecc07 event: media data: {"turn":2,"referenceId":"user:12345-email:6a6f...-video:5732c66d-a971-4cd0-92d2-508ef0aecc07","mediaId":"5732c66d-a971-4cd0-92d2-508ef0aecc07","type":"video","status":"completed","tool":"generate_video_from_text","model":"abra_t2v_6s","displayName":"Steam rising from coffee mug","url":"https://flow-content.google/video/5732c66d-...?Expires=...&Signature=...","durationSec":6} ``` Download each `url` while it is fresh: ```bash curl -s -L -o mug-steam.mp4 "https://flow-content.google/video/5732c66d-...?Expires=...&Signature=..." ``` The links point to Google and expire about 6 hours after they are issued. Read the chat again with [GET /agent/chats/`chatId`](#step-6-read-list-rename-and-delete-chats) for fresh ones, or get one item's link from [GET /assets/`mediaGenerationId`](/docs/api-google-flow-v1/get-google-flow-assets-mediagenerationid) with its `referenceId`. The `referenceId` also works as `referenceImage_N` or `referenceVideo_1` in [POST /images](/docs/api-google-flow-v1/post-google-flow-images), [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) and your next agent message. The two images and the 1280×720 video are in [Examples](#examples). The run spent 10 credits: the two Nano Banana 2.1 images cost 0 on this account's plan, and the 6-second Omni 1.1 Flash video cost 10. ### Step 5: Continue or revise Send the next message to the same chat. Google keeps the conversation, so the agent knows which video "the video" is: ```bash curl -s --max-time 150 -X POST "$API/chats/$CHAT/messages" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "message": "Nice. Revise the video: make it 8 seconds, with a slow camera push-in toward the mug while the steam rises." }' ``` It answered `202` with `"turn": 3`, and the agent asked again, this time for 12 credits: ``` id: 3:approval event: approval data: {"turn":3,"cost":12,"images":0,"videos":1,"total":1} id: 3:end event: turn data: {"turn":3,"status":"waiting_approval"} ``` We had our video, so we declined: ```bash curl -s --max-time 150 -X POST "$API/chats/$CHAT/approval" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "decision": "reject" }' ``` Turn 4 ended with a reply and no new image or video, and no credits were spent: ``` id: 4:91e06fb7-ba5b-4e32-b2a6-ce210be491ba event: message data: {"id":"4:91e06fb7-...","turn":4,"items":[{"kind":"text","text":"I've cancelled that generation. Are there any changes you'd like to make to the prompt or concept before we try again?"}]} id: 4:end event: turn data: {"turn":4,"status":"completed"} ``` Sending a message while a turn runs answers `409`, so wait for the `turn` event first. To pick one of the agent's choices, send the choice's text as the next message, as the Flow web app does. ### Step 6: Read, list, rename and delete chats Read the whole chat from Google at any time. Each turn carries your message, everything the agent did and the media with fresh links: ```bash curl -s "$API/chats/$CHAT" -H "Authorization: Bearer $USEAPI_TOKEN" ``` Our chat after the four turns (`agent` items and `media` cut down, `ui` left out): ```json { "chatId": "c-u12345-email:john@gmail.com-project:74262ac8-...-bot:google-flow", "email": "john@gmail.com", "projectId": "74262ac8-a54f-4ad7-80d7-3d44a4d6c6c1", "title": "Sage Green Ceramic Mug Concept", "created": "2026-10-18T00:47:54.000Z", "updated": "2026-10-18T00:50:47.236Z", "status": "idle", "pendingApproval": null, "lastError": null, "turns": [ { "turn": 1, "message": { "text": "Create two product shots of a matte sage-green ceramic coffee mug ...", "references": [] }, "agent": [ { "kind": "text", "text": "I'm going to generate two images of a matte sage-green ceramic coffee mug, then I'll create a 6-second video ..." }, { "kind": "tool_call", "tool": "ask_for_permission", "args": { "num_total": 3, "total_cost": 10, "num_videos": 1, "num_images": 2 } } ], "media": [] }, { "turn": 2, "message": { "text": "Approve", "references": [] }, "agent": [ { "kind": "tool_call", "tool": "generate_video_from_text", "args": { "duration": 6, "aspect_ratio": "16:9", "model_display_name": "Omni 1.1 Flash", "prompt": "Cinematic product video of a matte sage-green ceramic coffee mug ..." } }, { "kind": "tool_call", "tool": "generate_image", "args": { "aspect_ratio": "1:1", "prompt": "A professional product shot of a matte sage-green ceramic coffee mug ..." } }, { "kind": "text", "text": "I've generated your two product shots. Your 6-second video has been scheduled ..." } ], "media": [ { "referenceId": "user:12345-email:6a6f...-video:5732c66d-...", "type": "video", "status": "completed", "model": "abra_t2v_6s", "displayName": "Steam rising from coffee mug", "url": "https://flow-content.google/video/5732c66d-...", "durationSec": 6 }, { "referenceId": "user:12345-email:6a6f...-image:377ecb33-...", "type": "image", "status": "completed", "displayName": "Ceramic coffee mug on table", "url": "https://flow-content.google/image/377ecb33-..." }, { "referenceId": "user:12345-email:6a6f...-image:a2d3cd0c-...", "type": "image", "status": "completed", "displayName": "Ceramic coffee mug on wooden sur…", "url": "https://flow-content.google/image/a2d3cd0c-..." } ] }, { "turn": 3, "message": { "text": "Nice. Revise the video: make it 8 seconds, ...", "references": [] }, "agent": ["..."], "media": [] }, { "turn": 4, "message": { "text": "Reject", "references": [] }, "agent": [{ "kind": "text", "text": "I've cancelled that generation. Are there any changes you'd like to make to the prompt or concept before we try again?" }], "media": [] } ] } ``` Google titled the chat on its own. The `status` is `idle` once nothing runs, and `pendingApproval` holds the cost while the agent waits. Pass `?media=false` for a faster read without the link refresh. List an account's chats, newest activity first. The list comes from Google, so it also holds chats started in the Flow web app in the same project, and it is how you find a lost `chatId`: ```bash curl -s "$API/chats?email=$EMAIL" -H "Authorization: Bearer $USEAPI_TOKEN" ``` Rename a chat. The new title shows in the Flow web app too: ```bash curl -s -X PATCH "$API/chats/$CHAT" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "title": "Sage mug product shoot" }' ``` ```json { "chatId": "c-u12345-email:john@gmail.com-project:74262ac8-...-bot:google-flow", "title": "Sage mug product shoot" } ``` The list then read: ```json { "chats": [ { "chatId": "c-u12345-email:john@gmail.com-project:74262ac8-...-chat:55023a0f-...-bot:google-flow", "email": "john@gmail.com", "title": "Sage mug product shoot", "created": "2026-10-18T00:47:54.000Z", "updated": "2026-10-18T00:51:01.773Z", "running": false }, { "chatId": "c-u12345-email:john@gmail.com-project:74262ac8-...-chat:1d9d42ed-...-bot:google-flow", "email": "john@gmail.com", "title": "Stylish Female Character Action Sequence", "created": "2026-10-17T03:50:34.000Z", "updated": "2026-10-17T04:57:26.375Z", "running": false } ] } ``` Delete a chat's conversation. It answers `204` with no body, the chat leaves the list and the Flow web app, and the images and videos it made stay in the project: ```bash curl -s -X DELETE "$API/chats/$CHAT" -H "Authorization: Bearer $USEAPI_TOKEN" ``` Rename and delete answer `409` while a turn runs. ### Step 7: Settings for approval, instructions and default models Each Flow project has agent settings, the same as the agent panel in the Flow web app. [GET /agent/settings](/docs/api-google-flow-v1/get-google-flow-agent-settings) reads them, and also lists the image and video models the account's Google plan has, with what one image or video costs on that plan: ```bash curl -s "$API/settings?email=$EMAIL" -H "Authorization: Bearer $USEAPI_TOKEN" ``` [PUT /agent/settings](/docs/api-google-flow-v1/put-google-flow-agent-settings) changes only the fields you send. Before the run we set the `ask` mode and the defaults: ```bash curl -s -X PUT "$API/settings" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$EMAIL"'", "approval": "ask", "imageDefaults": { "model": "nano-banana-2", "aspectRatio": "1:1", "count": 2 }, "videoDefaults": { "model": "omni-flash", "aspectRatio": "16:9", "count": 1 } }' ``` The response is the project's settings after the change: ```json { "projectId": "74262ac8-a54f-4ad7-80d7-3d44a4d6c6c1", "approval": "ask", "instructions": [], "imageDefaults": { "model": "nano-banana-2", "aspectRatio": "1:1", "count": 2 }, "videoDefaults": { "model": "omni-flash", "aspectRatio": "16:9", "count": 1 }, "models": { "image": [ { "model": "nano-banana-pro", "label": "Nano Banana Pro", "credits": 0 }, { "model": "nano-banana-2-lite", "label": "Nano Banana 2 Lite", "credits": 0 }, { "model": "nano-banana-2", "label": "Nano Banana 2.1", "credits": 0 } ], "video": [ { "model": "omni-flash", "label": "Omni 1.1 Flash", "credits": 4 }, { "model": "veo-3.1-lite", "label": "Veo 3.1 - Lite", "credits": 5 }, { "model": "veo-3.1-fast", "label": "Veo 3.1 - Fast", "credits": 10 }, { "model": "veo-3.1-quality", "label": "Veo 3.1 - Quality", "credits": 100 } ] } } ``` `credits` is the lowest cost of one image or video on the account's plan, so a longer or higher-resolution video costs more: our 6-second 720p Omni 1.1 Flash video cost 10, and the 8-second revision would have cost 12. Your plan may show different numbers. The settings fields: - `approval`: `ask` (the agent stops and shows the cost) or `auto` (it spends without asking). - `instructions`: up to 3 standing instructions the agent follows in every chat of the project, each with optional reference images. The array replaces the project's instructions, so send the full list. - `imageDefaults` and `videoDefaults`: the model, aspect ratio and count the agent uses when a message does not say otherwise, picked from `models`. The settings apply to every chat in the project, including chats in the Flow web app. ### The same from an AI assistant The hosted [Google Flow MCP server](/docs/api-google-flow-v1/mcp) gives Claude Code, Cursor, VS Code and other MCP clients the same chat as 12 tools, with nothing to install. In Claude Code: ```bash claude mcp add --transport http useapi-google-flow https://api.useapi.net/v1/google-flow/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` Then ask the assistant for the mug shots in plain words. The assistant sends the brief with `flow_agent_chat` and answers the agent's request to spend credits with `flow_agent_answer_approval`. The server is listed in the official MCP Registry as `net.useapi/google-flow`. To see a full chat client first, open the [live demo](/demos/google-flow/). Paste your API token, pick an account and chat with the agent, with its images and videos inline, attachments, approval cards and settings. Its source is five small files with no build step on GitHub in [google-flow-api/demo](https://github.com/useapi/google-flow-api/tree/main/demo), and the [Agent Live Demo](/docs/api-google-flow-v1/agent-demo) page maps each feature to its API call. ### Examples What this run made, with no edits. The prompts are the agent's own, written from our brief. ###### Nano Banana 2.1 » two product shots of the sage-green mug (turn 2) <div style="display: flex; gap: 2%; flex-wrap: wrap"> <figure style="margin: 0; width: 49%"><a href="https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-shot-1-nano-banana-2-1.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-shot-1-nano-banana-2-1.jpg" alt="Google Flow Agent result: a matte sage-green ceramic mug on a light oak table in soft morning light, made with Nano Banana 2.1" style="width: 100%" loading="lazy"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">Option 1, "Ceramic coffee mug on table"</figcaption></figure> <figure style="margin: 0; width: 49%"><a href="https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-shot-2-nano-banana-2-1.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-shot-2-nano-banana-2-1.jpg" alt="Google Flow Agent result: a close-up of the sage-green mug with coffee, a brass spoon and an open book in morning sun, made with Nano Banana 2.1" style="width: 100%" loading="lazy"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">Option 2, the close-up</figcaption></figure> </div> Both 1024×1024 JPEG, 0 credits on this account's plan. ###### Omni 1.1 Flash » 6 seconds of steam rising from the mug (turn 2) <video poster="https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-steam-omni-1-1-flash-6s-poster.jpg" src="https://media.useapi.net/articles/2026-10-17-google-flow-agent-chat/flow-agent-sage-mug-steam-omni-1-1-flash-6s.mp4" style="width: 100%; aspect-ratio: 16/9; max-width: 720px" controls type="video/mp4" preload="metadata"></video> 1280×720 with sound, 6 seconds, 10 credits. Related tutorials: [Veo 3.1 video via the Google Flow API](/docs/articles/google-flow-bash), [audio-native video with Omni Flash](/docs/articles/omni-flash-bash) and [Nano Banana images via the Google Flow API](/docs/articles/google-flow-images-bash). ### Frequently asked questions - **Is there a Google Flow Agent API?** Through useapi.net, yes: the [Agent API](/docs/api-google-flow-v1/agent) starts chats, streams the replies over Server-Sent Events, answers approvals and returns the images and videos, on every Google AI subscription, a free account included. Google offers [Flow Agent](https://support.google.com/labs/answer/17093911) only inside the Flow web app, with no public API of its own (as of November 2026). - **How much does chatting with Google Flow Agent cost?** Through useapi.net, chatting costs no Flow credits, and what the agent makes costs the usual Flow price, which the `ask` mode shows before anything is spent. The 6-second 720p Omni 1.1 Flash video in this run comes to $0.08 on Google AI Ultra $199.99, against $0.61 on the official [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) (as of November 2026). - **Do chats started in the Flow web app show up in the API?** Through useapi.net, yes, when they are in the same project. [GET /agent/chats](/docs/api-google-flow-v1/get-google-flow-agent-chats) lists them, and every endpoint above works on them. Chats started through the API show up in the web app too. Pass `projectId` from [GET /assets/projects/`email`](/docs/api-google-flow-v1/get-google-flow-assets-projects-email) to work in a project other than the agent's own. - **Can I get a webhook instead of holding a stream open?** Through useapi.net, yes. Pass `replyUrl` to [POST /agent/chats](/docs/api-google-flow-v1/post-google-flow-agent-chats#callback), the messages call or the approval call, and the API sends one `POST` with the turn's messages, media, status and any pending approval when the turn ends. Videos usually arrive there still `queued`, so get their links from GET or the stream's `media` events. - **What are the limits?** Through useapi.net a chat runs one turn at a time, an account runs at most 3 turns at once, and a turn lasts up to 10 minutes, which is Google's own limit. Google also caps agent messages per account per day without publishing the number, and the API answers `429` for that account until midnight UTC. See [Limits](/docs/api-google-flow-v1/agent#limits). ### Conclusion Visit our <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> or <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> for any support questions and concerns. Check our [GitHub repo](https://github.com/useapi/google-flow-api) with code examples, including the agent chat client in [`demo/`](https://github.com/useapi/google-flow-api/tree/main/demo). An AI assistant can chat with Google Flow Agent for you too: the hosted [Google Flow MCP server](/docs/api-google-flow-v1/mcp) works with Claude Code, Cursor and VS Code, on your Google Flow account. === URL: https://useapi.net/docs/articles/google-flow-api-zh === Document URL: https://useapi.net/docs/articles/google-flow-api-zh --- layout: default title: 如何通过 Google Flow API 调用 Veo 3.1、Omni Flash(1.2 和 1.1)和 Nano Banana Pro(中文教程) description: "Google Flow API 中文教程:无需 Gemini API Key,用你的 Google Flow 网站订阅(Google AI Pro 或 Ultra)通过 useapi.net 调用 Veo 3.1、Omni 1.2 Flash 和 Omni 1.1 Flash 视频(含 Omni 1.2 视频延长)和 Nano Banana Pro 图片,附价格对比与 curl、Python 示例。" keywords: [Google Flow API, Google Flow API Key, Google Flow API 教程, Veo 3.1 API, Veo 3.1 API 价格, veo3 api, Omni 1.1 Flash API, Omni 1.2 Flash API, Gemini Omni Flash, 视频延长, Nano Banana Pro API, Nano Banana API, flow.google.com, Gemini API 替代, 中文教程, Chinese tutorial, tutorial, code] image: https://media.useapi.net/blog/2025-11-20-251120/nano-banana-pro-text-to-image.jpg parent: Articles nav_exclude: true lang: zh-CN date: 2026-09-27 last_modified: 2026-11-20 nav_order: 845 repo: https://github.com/useapi/google-flow-api translation_key: google-flow --- ## 如何通过 Google Flow API 调用 Veo 3.1、Omni Flash(1.2 和 1.1)和 Nano Banana Pro(中文教程) <div class="lang-banner" lang="en"> <strong>Chinese-language tutorial.</strong> This page is written in Simplified Chinese for Chinese-speaking developers. The same material in English: <a href="/docs/articles/google-flow-bash">Veo 3.1</a> · <a href="/docs/articles/omni-flash-bash">Omni Flash</a> · <a href="/docs/articles/google-flow-images-bash">Nano Banana</a> · <a href="/docs/api-google-flow-v1">Google Flow API docs</a> </div> 8 分钟阅读 • 2026 年 9 月 27 日(2026 年 11 月 7 日更新) ## 目录 ### 简介 [useapi.net](/docs/api-google-flow-v1) 的 Google Flow API 用你的 Google Flow 网站订阅([Google AI Pro 或 Ultra](https://gemini.google/subscriptions/)),通过 REST 接口调用 Flow 里的三类模型:Veo 3.1 视频、带原生音频的 Omni 1.1 Flash 视频和 Nano Banana Pro 图片。8 秒的 Veo 3.1 Fast 视频在 Google AI Ultra(199.99 美元)上约 0.08 美元,Google 官方 API 为 0.80 美元(截至 2026 年 11 月)。不需要 Google Cloud 项目,也不需要 Gemini API Key。 Google Flow 于 2026 年 9 月 10 日迁移到 `flow.google.com`,并换成了基于 Cookie 的新授权方式,9 月 15 日起旧接口陆续停用,很多自部署脚本因此需要重新适配。本 API 已适配新域名。如果不想自己维护浏览器、Cookie 刷新和验证码逻辑,可以考虑托管 API:账号由你绑定,接口适配由我们维护。 Omni 1.2 Flash 在 Flow 和 Vids 中的对比、15 秒视频和每条视频价格:见[Gemini Omni 1.2 Flash API 中文教程](/docs/articles/gemini-omni-1-2-flash-api-zh)。 本文由 useapi.net 维护者撰写,介绍的是我们自己的托管 API,示例代码开源在 [GitHub](https://github.com/useapi/google-flow-api)。 #### 使用前须知(依赖与费用) - 这是第三方、非官方的 API,与 Google 无关联。Google Flow 本身没有官方 API。 - 需要一个 Google 账号。免费账号[每天有 50 个 Flow 积分](https://support.google.com/flow/answer/16526234),可以生成 Veo 3.1 Fast 和 Lite 视频、最长 10 秒的 Omni 1.2 Flash 视频以及 Nano Banana 图片。Omni 1.1 Flash、超过 10 秒的 Omni 1.2 视频和用 Omni 1.2 延长视频需要付费 Google AI 套餐(Plus、Pro 或 Ultra)。 - 登录和会话完全托管。你只需通过自动化浏览器登录一次,之后由服务端自动刷新会话、保持 Cookie 有效,不需要你再登录、复制或更新 Cookie。 - 每次生成都需要通过一次 reCAPTCHA(验证码)。首个 Google Flow 账号赠送 300 次免费求解,之后需要接入你自己的打码服务(如 AntiCaptcha、CapSolver),费用约为每 1,000 次生成 0.80–3 美元,直接付给打码服务商。 - useapi.net 按月[订阅](/docs/subscription),一个订阅包含所有 API,不按次收费。 ### 三个模型一览 | | Nano Banana Pro | Veo 3.1 | Omni 1.1 Flash | |---|---|---|---| | 生成内容 | 图片 | 视频 | 带原生音频的视频 | | `model` 取值 | `nano-banana-pro`,另有 `nano-banana-2`、`nano-banana-2-lite`(默认) | `veo-3.1-fast`(默认)、`veo-3.1-quality`、`veo-3.1-lite` | `omni-flash` | | 接口 | [POST /images](/docs/api-google-flow-v1/post-google-flow-images) | [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) | [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) | | 调用方式 | 同步,一次请求返回 | 异步,提交后轮询 | 异步,提交后轮询 | | Google AI 套餐 | 所有套餐,包括免费账号 | 所有套餐,免费账号用每天 50 个 Flow 额度 | 付费套餐(Plus、Pro、Ultra) | | Google 官方 API | 有,按张计费 | 按秒计费,Gemini API 的 Veo 3.1 预览版于 2026 年 10 月 22 日停用后,改在 Google Cloud 的 Agent Platform 上提供 | 有,按秒计费(2026 年 6 月 30 日起,`720p` 约每秒 0.10 美元) | ### 价格 一条视频或一张图片在 Google 官方 API 和在每个 Google Flow 订阅上的价格。官方价格来自 [Gemini API](https://ai.google.dev/gemini-api/docs/pricing),Veo 另见 Google Cloud 的 [Agent Platform](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing),Veo 在两处都按秒计费(Agent Platform 称为 "per count")。每个订阅每月包含固定数量的 Flow 积分,每条视频消耗固定数量的积分,所以一条视频的成本就是它在订阅费里所占的份额。 | 模型 | [官方 API](https://ai.google.dev/gemini-api/docs/pricing) | Ultra $199.99/月 (每月 25,000 积分) | Ultra $99.99/月 (每月 10,000 积分) | Pro $19.99/月 (每月 1,000 积分) | Plus $4.99/月 (每月 200 积分) | |---|---|---|---|---|---| | Veo 3.1 Fast (720p,8 秒) | $0.80 (每秒 $0.10) | $0.08 / 10 积分 (每月 2,500 条) | $0.10 / 10 积分 (每月 1,000 条) | $0.40 / 20 积分 (每月 50 条) | $0.50 / 20 积分 (每月 10 条) | | Veo 3.1 Quality (720p,8 秒) | $3.20 (每秒 $0.40) | $0.80 / 100 积分 (每月 250 条) | $1.00 / 100 积分 (每月 100 条) | $2.00 / 100 积分 (每月 10 条) | $2.50 / 100 积分 (每月 2 条) | | Veo 3.1 Lite (720p,8 秒) | $0.40 (每秒 $0.05) | $0.04 / 5 积分 (每月 5,000 条) | $0.05 / 5 积分 (每月 2,000 条) | $0.20 / 10 积分 (每月 100 条) | $0.25 / 10 积分 (每月 20 条) | | Veo 3.1 Lite (低优先级,720p,8 秒) | — | $0 / 0 积分 (每天约 1,000 条或更多) | — | — | — | | 视频放大 (360p 至 720p) | — | $0 / 0 积分 (已包含) | $0 / 0 积分 (已包含) | $0 / 0 积分 (已包含) | $0 / 0 积分 (已包含) | | 视频放大 (1080p) | — | $0 / 0 积分 (已包含) | $0 / 0 积分 (已包含) | $0 / 0 积分 (已包含) | $0 / 0 积分 (已包含) | | 视频放大 (4K) | — | $0.40 / 50 积分 (每月 500 条) | $0.50 / 50 积分 (每月 200 条) | — | — | | Omni 1.2 Flash (720p,15 秒) | $1.04 (每秒约 $0.07) | $0.48 / 60 积分 (每月 416 条) | $0.60 / 60 积分 (每月 166 条) | $1.20 / 60 积分 (每月 16 条) | $1.50 / 60 积分 (每月 3 条) | | Omni 1.2 Flash (360p,15 秒) | $0.35 (每秒 $0.023) | $0.16 / 20 积分 (每月 1,250 条) | $0.20 / 20 积分 (每月 500 条) | $0.40 / 20 积分 (每月 50 条) | $0.50 / 20 积分 (每月 10 条) | | Omni 1.1 Flash (720p,10 秒) | $1.01 (每秒 $0.10) | $0.12 / 15 积分 (每月 1,666 条) | $0.15 / 15 积分 (每月 666 条) | $0.30 / 15 积分 (每月 66 条) | $0.37 / 15 积分 (每月 13 条) | | Omni 1.1 Flash (360p,10 秒) | — | $0.06 / 7 积分 (每月 3,571 条) | $0.07 / 7 积分 (每月 1,428 条) | $0.14 / 7 积分 (每月 142 条) | $0.17 / 7 积分 (每月 28 条) | | Nano Banana Pro | $0.134 (每张) | $0 / 0 积分 (每天最多约 500 张) | $0 / 0 积分 (已包含) | $0 / 0 积分 (已包含) | $0 / 0 积分 (已包含) | | Nano Banana 2.1 | $0.034 (每张) | $0 / 0 积分 (每天最多约 500 张) | $0 / 0 积分 (已包含) | $0 / 0 积分 (已包含) | $0 / 0 积分 (已包含) | | Nano Banana 2 Lite | $0.034 (每张) | $0 / 0 积分 (每天最多约 500 张) | $0 / 0 积分 (已包含) | $0 / 0 积分 (已包含) | $0 / 0 积分 (已包含) | | Model | [Official API](https://ai.google.dev/gemini-api/docs/pricing) | Ultra $199.99/m (25,000 cr/mo) | Ultra $99.99/m (10,000 cr/mo) | Pro $19.99/m (1,000 cr/mo) | Plus $4.99/m (200 cr/mo) | |---|---|---|---|---|---| | Veo 3.1 Fast (720p, 8s) | $0.80 ($0.10/s) | $0.08 / 10 cr (2,500 videos/mo) | $0.10 / 10 cr (1,000 videos/mo) | $0.40 / 20 cr (50 videos/mo) | $0.50 / 20 cr (10 videos/mo) | | Veo 3.1 Quality (720p, 8s) | $3.20 ($0.40/s) | $0.80 / 100 cr (250 videos/mo) | $1.00 / 100 cr (100 videos/mo) | $2.00 / 100 cr (10 videos/mo) | $2.50 / 100 cr (2 videos/mo) | | Veo 3.1 Lite (720p, 8s) | $0.40 ($0.05/s) | $0.04 / 5 cr (5,000 videos/mo) | $0.05 / 5 cr (2,000 videos/mo) | $0.20 / 10 cr (100 videos/mo) | $0.25 / 10 cr (20 videos/mo) | | Veo 3.1 Lite (low priority, 8s) | — | $0 / 0 cr (1,000+ a day) | — | — | — | | Video upscale (360p to 720p) | — | $0 / 0 cr (included) | $0 / 0 cr (included) | $0 / 0 cr (included) | $0 / 0 cr (included) | | Video upscale (1080p) | — | $0 / 0 cr (included) | $0 / 0 cr (included) | $0 / 0 cr (included) | $0 / 0 cr (included) | | Video upscale (4K) | — | $0.40 / 50 cr (500 videos/mo) | $0.50 / 50 cr (200 videos/mo) | — | — | | Omni 1.2 Flash (720p, 15s) | $1.04 ($0.07/s) | $0.48 / 60 cr (416 videos/mo) | $0.60 / 60 cr (166 videos/mo) | $1.20 / 60 cr (16 videos/mo) | $1.50 / 60 cr (3 videos/mo) | | Omni 1.2 Flash (360p, 15s) | $0.35 ($0.023/s) | $0.16 / 20 cr (1,250 videos/mo) | $0.20 / 20 cr (500 videos/mo) | $0.40 / 20 cr (50 videos/mo) | $0.50 / 20 cr (10 videos/mo) | | Omni 1.1 Flash (720p, 10s) | $1.01 ($0.10/s) | $0.12 / 15 cr (1,666 videos/mo) | $0.15 / 15 cr (666 videos/mo) | $0.30 / 15 cr (66 videos/mo) | $0.37 / 15 cr (13 videos/mo) | | Omni 1.1 Flash (360p, 10s) | — | $0.06 / 7 cr (3,571 videos/mo) | $0.07 / 7 cr (1,428 videos/mo) | $0.14 / 7 cr (142 videos/mo) | $0.17 / 7 cr (28 videos/mo) | | Nano Banana Pro | $0.134 (per image) | $0 / 0 cr (~500 a day) | $0 / 0 cr (included) | $0 / 0 cr (included) | $0 / 0 cr (included) | | Nano Banana 2.1 | $0.034 (per image) | $0 / 0 cr (~500 a day) | $0 / 0 cr (included) | $0 / 0 cr (included) | $0 / 0 cr (included) | | Nano Banana 2 Lite | $0.034 (per image) | $0 / 0 cr (~500 a day) | $0 / 0 cr (included) | $0 / 0 cr (included) | $0 / 0 cr (included) | - Gemini API 的 Veo 3.1 预览版于 2026 年 10 月 22 日停用,之后 Veo 留在 Agent Platform 上,价格不变。 - 每天的数字是用量最高的真实账号的平均值,不是保证。套餐价格是 Google [订阅页面](https://gemini.google/subscriptions/)上的美国价格。 ### 准备工作 1. 注册 useapi.net 并获取 [API Token](/docs/start-here/setup-useapi),下面的示例都假设它保存在环境变量 `USEAPI_TOKEN` 里。 2. 用[自动化浏览器流程](/docs/start-here/setup-google-flow)绑定 Google 账号:登录 Google 即可,不需要手动复制 Cookie。 3. reCAPTCHA 由服务端自动处理。首个 Google Flow 账号赠送 300 次免费验证码求解(打码),之后通过 [POST /accounts/captcha-providers](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers) 接入你自己的打码服务(大约每千次 0.8–3 美元)。 `email` 参数可省略:只绑定一个账号时自动使用该账号,绑定多个账号时,API 会在账号间自动负载均衡。 ### 调用方式:图片同步,视频异步 图片请求会等待生成完成,直接在响应里返回结果,通常 10–20 秒(遇到验证码重试时可能更久,请不要把请求超时设得太短)。 视频请求传 `async: true`,立即返回一个 `jobid`,之后查询 [GET /jobs/`jobId`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid),直到状态变为 `completed` 或 `failed`,通常需要 60–180 秒,视模型和模式而定。Veo 和 Omni 用同一段轮询代码,先定义一次: ```bash # 等待视频任务完成并下载(Veo 3.1 与 Omni 1.1 Flash 通用) poll_video() { [ -z "$1" ] || [ "$1" = "null" ] && { echo "提交失败"; return 1; } while true; do RES=$(curl -s "https://api.useapi.net/v1/google-flow/jobs/$1" \ -H "Authorization: Bearer $USEAPI_TOKEN") STATUS=$(echo "$RES" | jq -r '.status') echo "status: $STATUS" [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ] && break sleep 20 done i=0 echo "$RES" | jq -r '.response.media[].videoUrl // empty' | while read -r url; do i=$((i + 1)) curl -s -o "video-$i.mp4" "$url" done } ``` 视频的签名下载链接会过期,拿到后尽快下载。也可以在请求里传 `replyUrl`,用 Webhook 接收任务状态,不必轮询。 ### Nano Banana Pro:生成图片 Nano Banana Pro 是画质最高的 Nano Banana 模型,在所有 Google AI 套餐上都可以用。 ```bash curl -s -X POST "https://api.useapi.net/v1/google-flow/images" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "一辆红色复古自行车靠在阳光下的砖墙边,写实摄影", "model": "nano-banana-pro", "aspectRatio": "16:9", "count": 1 }' > images.json i=0 jq -r '.media[].image.generatedImage.fifeUrl // empty' images.json | while read -r url; do i=$((i + 1)) curl -s -o "image-$i.jpg" "$url" done ``` - 每张图片的下载链接在 `media[].image.generatedImage.fifeUrl`,链接带签名,有时效。偶尔没有 `fifeUrl` 时,图片以 base64 形式放在 `encodedImage` 中返回。 - `count` 为 1–4(默认 4),画幅可选 `16:9`、`4:3`、`1:1`、`3:4`、`9:16`。 - 最多 10 张参考图(`reference_1..10`),先用 [POST /assets](/docs/api-google-flow-v1/post-google-flow-assets-email) 上传。 - 生成的图片可以用 [POST /images/upscale](/docs/api-google-flow-v1/post-google-flow-images-upscale) 放大到 2K(所有套餐)或 4K(付费套餐)。 ### Veo 3.1:生成视频 Veo 3.1 有 Fast、Quality、Lite 三个版本,消耗 Flow 积分:免费账号每天有 50 个,可以生成 Fast 和 Lite,付费套餐另有每月积分。 ```bash JOB=$(curl -s -X POST "https://api.useapi.net/v1/google-flow/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "日出时分,木桌上一杯冒着热气的咖啡,镜头缓慢推进", "model": "veo-3.1-fast", "aspectRatio": "landscape", "async": true }' | jq -r '.jobid') poll_video "$JOB" ``` - 画幅可选 `landscape`、`portrait`、`1:1`、`4:3`、`3:4`,默认时长 8 秒。 - 传 `startImage`(可加 `endImage`)做图生视频,`veo-3.1-quality` 以外的版本还支持最多 3 张参考图。 - Google AI Ultra(199.99 美元)的套餐所有者可用 `veo-3.1-lite-low-priority`,低优先级队列,不消耗积分。 ### Omni 1.1 Flash:带原生音频的视频 Omni 1.1 Flash 是 Google 的原生音频视频模型,需要付费 Google AI 套餐(Plus、Pro 或 Ultra),各时长的价格见[价格](#pricing)。它直接从提示词生成画面和声音,包括人物对白、旁白和环境音,不需要额外的音频参数。 ```bash JOB=$(curl -s -X POST "https://api.useapi.net/v1/google-flow/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "灯塔看守人望着远处的风暴,低声讲述今晚的天气,海浪拍打礁石", "model": "omni-flash", "aspectRatio": "landscape", "duration": 10, "async": true }' | jq -r '.jobid') poll_video "$JOB" ``` - 时长可选 4、6、8、10 秒,画幅只支持 `landscape` 和 `portrait`。 - 传 `resolution: "360p"` 大约省一半积分,之后可以用 [POST /videos/upscale](/docs/api-google-flow-v1/post-google-flow-videos-upscale) 升到 720p。 - `referenceAudio_1..5` 可以指定 30 个系统音色之一(如 `Kore`),或用 [POST /voices](/docs/api-google-flow-v1/post-google-flow-voices) 保存的自定义音色。指定音色时需要同时提供参考图(`referenceImage_*`)或角色(`character_*`)。 - 还支持最多 7 张参考图(`referenceImage_1..7`)、可复用角色(`character_1..7`)、首尾帧(`startImage` + `endImage`),以及对已有视频做编辑(`referenceVideo_1`)。 ### Omni 1.2 Flash:3 到 15 秒,可延长视频 Google 于 2026 年 11 月 5 日发布 Omni 1.2 Flash,用 `model: "omni-flash-1.2"` 调用,接口和参数与上面的 Omni 1.1 Flash 相同: - 时长可以是 3 到 15 之间的任意整数秒(首尾帧模式为 3 到 10 秒),分辨率 `360p` 或 `720p`。 - 按秒计费,所有套餐价格相同:`720p` 前 10 秒每秒 3 个积分,超过 10 秒的部分每秒 6 个积分(15 秒共 60 个积分)。`360p` 为每秒 1 个和 2 个积分。 - 免费 Google 账号也能用,但最长 10 秒。 - Google 正在分几天把 Omni 1.2 推送到各个账号。还没有收到的账号会返回 `400`,不传 `email` 时请求会自动分配到已有 Omni 1.2 的账号。 [POST /videos/extend](/docs/api-google-flow-v1/post-google-flow-videos-extend) 默认使用 Omni 1.2:在任意短于 30 秒的视频后面每次续写 3 到 10 秒(`duration`,默认 8 秒),返回一个包含原视频和新增内容的完整片段。可以带最多 3 张参考图或角色(`referenceImage_1..3`、`character_1..3`)和最多 3 个音色(`referenceAudio_1..3`),并在提示词里用 `@referenceAudio_1` 这样的标记指定位置。延长按新增秒数计费(`720p` 10 秒为 30 个积分),需要付费套餐。Google 已于 2026 年 11 月 18 日停止用 Veo 模型延长视频,把 `model` 设为 Veo 模型会返回 `400`。 ```bash JOB=$(curl -s -X POST "https://api.useapi.net/v1/google-flow/videos/extend" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "mediaGenerationId": "上一步视频的 mediaGenerationId", "duration": 10, "referenceAudio_1": "Charon", "prompt": "魔术师在雨中追着发光的纸牌跑过拉面摊,用低沉的声音 @referenceAudio_1 喊道:“回来!你是红桃 A!”", "async": true }' | jq -r '.jobid') poll_video "$JOB" ``` 对结果再次调用即可继续延长。30 秒及更长的视频不能再延长。完整的 Node.js 和 Python 脚本见 GitHub 上的 [`omni-extend/`](https://github.com/useapi/google-flow-api/tree/main/omni-extend)。 ### Python 示例 同样的异步流程,用 Python 写。把 `model` 换成 `omni-flash` 就是 Omni 1.1 Flash: ```python import time, requests API = 'https://api.useapi.net/v1/google-flow' H = {'Authorization': 'Bearer YOUR_TOKEN'} r = requests.post(f'{API}/videos', headers=H, json={ 'prompt': 'A paper boat drifting down a rain-soaked street, cinematic', 'model': 'veo-3.1-fast', 'async': True, }) r.raise_for_status() job = r.json()['jobid'] while True: res = requests.get(f'{API}/jobs/{job}', headers=H).json() if res['status'] in ('completed', 'failed'): break time.sleep(20) for i, m in enumerate(res.get('response', {}).get('media', [])): open(f'video-{i + 1}.mp4', 'wb').write(requests.get(m['videoUrl']).content) ``` 完整的批量生成脚本(Node.js 与 Python)见 [GitHub 示例仓库](https://github.com/useapi/google-flow-api)。 ### 生成效果示例 以下是通过同一个 Google Flow API 生成的真实结果,取自我们的更新日志。 Nano Banana Pro 文生图([来源](/blog/251120)):*"Cat dressed like a pirate fencing with a real pirate, pirate looks absolutely terrified, this is happening on a deck of the Disney cruise ship"* ![Nano Banana Pro 文生图:海盗猫与海盗击剑](https://media.useapi.net/blog/2025-11-20-251120/nano-banana-pro-text-to-image.jpg) Veo 3.1 Fast 图生视频([来源](/blog/251117)):以一张 Nano Banana 图片作为 `startImage` 生成的动画。 <video poster="https://media.useapi.net/blog/2025-11-17-251117/veo-3-1-fast-poster.jpg" src="https://media.useapi.net/blog/2025-11-17-251117/veo-3-1-fast.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> Omni 1.1 Flash 参考图生视频([来源](/blog/260609)):用 `@` 标记引用一个角色和两张参考图,配上自定义音色的黑色电影风格片段,声音由模型原生生成,请打开音量。 <video poster="https://media.useapi.net/blog/2026-06-09-260609/noir-shot-1-poster.jpg" controls width="100%" style="max-width:640px;border-radius:8px"> <source src="https://media.useapi.net/blog/2026-06-09-260609/noir-shot-1.mp4" type="video/mp4"> </video> Omni 1.2 Flash 视频延长([来源](/blog/261106)):先生成 10 秒,再用两个不同音色各延长 10 秒,最终 30 秒,请打开音量。 <video poster="https://media.useapi.net/articles/2026-06-15-omni-flash-bash/261106-google-flow-omni-1-2-magician-extended-30s-web-poster.jpg" controls width="100%" style="max-width:640px;border-radius:8px"> <source src="https://media.useapi.net/articles/2026-06-15-omni-flash-bash/261106-google-flow-omni-1-2-magician-extended-30s-web.mp4" type="video/mp4"> </video> ### 常见问题 - **Google Flow 有官方 API 或 API Key 吗?** 通过 useapi.net 可以用代码调用 Google Flow:Google 没有公开的 Flow API,也没有 Flow 的 API Key。useapi.net 的 Google Flow API 是第三方 REST API,用一个 useapi.net API Token 调用,在你的 Google Flow 网站订阅上运行,不需要 Google Cloud 项目,也不需要 Gemini API Key。更多问答见 [Google Flow API 常见问题(英文)](/docs/api-google-flow-v1#questions)。 - **Veo 3.1 API 价格是多少?** 通过 useapi.net,8 秒的 Veo 3.1 Quality 视频在 Google AI Ultra(199.99 美元)上约 0.80 美元,Lite 约 0.04 美元,而 Google 官方 API 分别为 3.20 美元和 0.40 美元(截至 2026 年 11 月)。同一订阅还能以 0 积分使用低优先级的 Veo 3.1 Lite,每天约 1,000+ 条。见[价格](#pricing)。 - **Omni 1.1 Flash 有 API 吗?** 通过 useapi.net,以 `model: "omni-flash"` 调用 Omni 1.1 Flash,8 秒 `720p` 视频在 Google AI Ultra(199.99 美元)上约 0.10 美元,官方 Gemini API 约 0.81 美元(截至 2026 年 11 月)。Omni 1.1 Flash 需要付费 Google AI 套餐(Plus、Pro 或 Ultra),调用方式见[上文](#omni-flash)。 - **Omni Flash 能生成超过 10 秒的视频吗?** 通过 useapi.net 可以:Omni 1.2 Flash(`model: "omni-flash-1.2"`)一次最长 15 秒,[POST /videos/extend](/docs/api-google-flow-v1/post-google-flow-videos-extend) 还能在短于 30 秒的视频后每次续写最多 10 秒,并支持音色参考。在 Google AI Ultra(199.99 美元)上,8 秒 `720p` 的 Omni 1.2 视频约 0.19 美元,而 Google 官方 API 为 0.56 美元([Google Cloud,2026 年 11 月 5 日](https://cloud.google.com/blog/products/ai-machine-learning/gemini-omni-1-2-flash-generally-available)),且官方只向白名单客户开放音频参考。见[上文](#omni-flash-12)。 - **免费账号能用吗?** 通过 useapi.net,免费 Google 账号也能用:Nano Banana 图片不消耗积分,而官方 Gemini API 上 Nano Banana Pro 每张 0.134 美元(截至 2026 年 11 月)。免费账号[每天有 50 个 Flow 积分](https://support.google.com/flow/answer/16526234),可以生成 Veo 3.1 Fast 和 Lite 视频以及最长 10 秒的 Omni 1.2 Flash 视频,Omni 1.1 Flash 需要付费套餐。 - **支持 n8n、Make 等自动化工具吗?** 通过 useapi.net 支持:这是标准 REST API,在 n8n 里用 HTTP Request 节点加 Header Auth 凭证(`Authorization: Bearer <token>`)即可调用,Make 和其他自动化工具同理。现成的免费 n8n 模板见 [n8n UGC 广告教程(英文)](/docs/articles/google-flow-n8n-ugc-ads)。 ### 一个 useapi.net 订阅,所有 API 下面这些 API 和 Google Flow 一样,都包含在同一个 useapi.net 订阅里:每月 15 美元,一个 API Token,不用另外付费。用同一个 Google AI 订阅(Plus、Pro 或 Ultra),除了 Google Flow 还能调用: - [Google Vids API](/docs/api-google-vids-v1):用 Gemini Omni 1.2 Flash 生成 15 秒视频,用一张照片生成会说话的数字人视频([中文教程](/docs/articles/google-vids-api-zh)) - [Gemini Notebook API(NotebookLM API)](/docs/api-gemini-notebook-v1):把网页、PDF 和 YouTube 视频变成播客、视频概览和幻灯片([中文教程](/docs/articles/gemini-notebook-api-zh)) - [Flow Music API](/docs/api-flowmusic-v1):用 Lyria 3.5 生成完整歌曲,Google AI 订阅已包含 Flow Music 积分 一个 Google AI 订阅每月能生成多少视频、歌曲和播客,见[Google AI 订阅能用 API 调用吗?](/docs/articles/google-ai-subscription-api-zh) 同一个订阅还包含 [Muse API](/docs/api-muse-v1),不需要 Google 账号:在 Meta Muse(muse.ai)上生成带对白的 10 秒视频和图片,免费的 Muse 账号也能用([中文教程](/docs/articles/muse-api-zh))。 ### 结语 有问题欢迎加入我们的 <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord 服务器</a> 或 <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram 频道</a>。 示例代码见 [GitHub 仓库](https://github.com/useapi/google-flow-api)。 ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-flow-bash-es === Document URL: https://useapi.net/docs/articles/google-flow-bash-es --- layout: default title: "Cómo usar la API de Veo 3.1: generar video con curl mediante la Google Flow API" seo_title: "API de Veo 3.1 con curl: Google Flow API, sin clave de API" description: "API de Veo 3.1 con curl (Fast, Quality, Lite) mediante la Google Flow API de useapi.net en Google AI Pro o Ultra: sin proyecto de Google Cloud y sin clave de API." keywords: [Veo 3.1 API, API de Veo 3.1, Veo 3.1 API key, clave de API de Veo 3.1, Veo API, Google Veo API, API de Google Veo, Veo 3 API, Google Flow API, API de Google Flow, Veo 3.1 Fast, Veo 3.1 Lite, Gemini API Veo shutdown, generación de video con IA, texto a video, imagen a video, tutorial Veo 3.1, código, curl] parent: Articles nav_exclude: true lang: es date: 2026-06-15 last_modified: 2026-11-10 nav_order: 810 repo: https://github.com/useapi/google-flow-api translation_key: google-flow --- ## Cómo usar la API de Veo 3.1: generar video con curl mediante la Google Flow API {: .no_toc #how-to-use-the-veo-31-api-generate-video-with-curl-via-the-google-flow-api } 6 min de lectura • 15 de junio de 2026 (10 de noviembre de 2026) useapi.net es una API de terceros. No está afiliada a Google ni cuenta con su respaldo. ## Índice {: .no_toc .text-delta #table-of-contents } ### Introducción [Veo 3.1](https://deepmind.google/technologies/veo/) se ejecuta con un solo `curl` a través de la [Google Flow API](/docs/api-google-flow-v1) de useapi.net, con tu suscripción al sitio web de [Google Flow](https://flow.google.com) ([Google AI Pro o Ultra](https://gemini.google/subscriptions/)). Un video Veo 3.1 Fast de 8 segundos cuesta US$0,08 en Google AI Ultra US$199,99, frente a US$0,80 en la API oficial de Veo (a noviembre de 2026). Google cerró los modelos Veo 3.1 Preview de la Gemini API el 22 de octubre de 2026 y llevó a los desarrolladores a su [Agent Platform](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing) de Cloud, que cobra las mismas tarifas por segundo en un proyecto de Google Cloud. Esta API de terceros no necesita proyecto de Cloud, ni clave de API de Google, ni aprobación empresarial. A continuación: los modelos, el flujo de dos llamadas, las entradas de imagen y un script por lotes listo para ejecutar. ### Modelos compatibles Elige el modelo en cada solicitud con el campo `model` (por defecto `veo-3.1-fast`). Los costos en créditos de Veo vienen de la [tabla oficial de créditos de Flow](https://support.google.com/flow/answer/16526234?hl=es) de Google, y los de Omni se midieron con la API en vivo: | Id del modelo | Nivel / velocidad | Duraciones | Créditos por video | |----------|--------------|-----------|------------------------| | `veo-3.1-lite` | El Veo más barato | 4s, 6s, 8s | 10 (fuera de Ultra) · 5 (Ultra) | | `veo-3.1-lite-low-priority` | Lite, prioridad baja | 4s, 6s, 8s | 0, solo el titular de Ultra US$199,99 | | `veo-3.1-fast` *(por defecto)* | Veo rápido | 4s, 6s, 8s | 20 (fuera de Ultra) · 10 (Ultra) | | `veo-3.1-quality` | Veo de máxima calidad | solo 8s | 100 | | `omni-flash-1.2` | Omni 1.2 Flash, audio nativo | 3s a 15s | 3 por segundo hasta 10s, 6 por segundo después (en 720p) | | `omni-flash` | Omni 1.1 Flash, audio nativo | 4s, 6s, 8s, 10s | 7 / 10 / 12 / 15 (según la duración, en 720p) | En Veo, los videos de `4s` y `6s` requieren Ultra (consulta la [descripción general](/docs/api-google-flow-v1)). Google Flow también genera imágenes fijas con los modelos Nano Banana mediante el endpoint aparte [POST /images](/docs/api-google-flow-v1/post-google-flow-images). ### Precios Cada video gasta créditos de Flow de tu suscripción de Google AI, y useapi.net no cobra nada por video. El precio por video en cada plan, frente a la API oficial, está en la [tabla de precios de Google Flow](/docs/api-google-flow-v1#pricing), y el artículo [Veo 3.1 API pricing](/docs/articles/veo-3-1-api-pricing) (en inglés) cubre Veo en detalle. ### Genera un video con dos llamadas a la API Necesitas un [token de API](/docs/start-here/setup-useapi) de useapi.net y una [cuenta de Google Flow](/docs/start-here/setup-google-flow) conectada. Los jobs de video son asíncronos: pasa `async: true` y la llamada de creación devuelve un `jobid` al instante. Luego consultas el job hasta que el video esté listo. 1. Envía el job — `POST https://api.useapi.net/v1/google-flow/videos`: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A serene mountain landscape at sunset, camera slowly panning right", "model": "veo-3.1-fast", "aspectRatio": "landscape", "duration": 8, "async": true }' ``` En modo asíncrono la respuesta llega al instante con `201 Created`, un `jobid` en minúsculas y `status: "created"`: ```json { "jobid": "j1731859234567v-u12345-email:jo***@gmail.com-bot:google-flow", "type": "video", "status": "created", "created": "2026-06-15T12:34:56.789Z", "request": { "async": true, "prompt": "A serene mountain landscape at sunset, camera slowly panning right", "model": "veo-3.1-fast", "aspectRatio": "landscape", "duration": 8 } } ``` 2. Consulta el resultado — `GET https://api.useapi.net/v1/google-flow/jobs/{jobId}`: ```bash curl "https://api.useapi.net/v1/google-flow/jobs/{jobId}" \ -H "Authorization: Bearer $USEAPI_TOKEN" ``` `status` pasa por `created` → `started` → `completed`. Cuando llega a `completed`, el MP4 terminado está en `response.media[].videoUrl` (un solo prompt con `count > 1` devuelve una entrada por video): ```json { "jobid": "j1731859234567v-...", "type": "video", "status": "completed", "response": { "media": [ { "mediaGenerationId": "user:12345-email:6a6f...-video:a1d95d21-...", "videoUrl": "https://flow-content.google/video/a1d95d21-...?Expires=...", "thumbnailUrl": "https://flow-content.google/image/a1d95d21-...?Expires=..." } ], "remainingCredits": 18760 } } ``` Veo 3.1 suele terminar en 60 a 180 segundos, según el modelo y el modo. En nuestras pruebas del 20 de octubre de 2026, nueve videos de 8 segundos tardaron de 50 a 105 segundos desde el envío hasta el MP4 terminado ([ejecuciones medidas](/docs/articles/veo-3-1-api-pricing#examples), en inglés). El `videoUrl` firmado es válido durante unas 6 horas, así que descárgalo pronto. ¿Prefieres no consultar? Pasa un `replyUrl` en el cuerpo de la creación para recibir un callback por webhook cuando el job termine. ### Imagen a video y referencia a video Veo acepta imágenes de entrada de dos formas distintas. Primero sube cada imagen con [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email) (bytes sin procesar, un `Content-Type` de imagen, PNG/JPEG/WebP de hasta 20 MB). La respuesta de la subida trae el id anidado en `mediaGenerationId.mediaGenerationId`, y esa cadena anidada es la que devuelves en la solicitud. Cuando envías cualquier imagen de entrada puedes omitir `email`: la solicitud va a la cuenta donde se subió la imagen. #### Primer / último fotograma (I2V) Tu imagen se convierte en un fotograma literal del video. Pásala como `startImage` para empezar desde ese fotograma: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Brave Captain Cat chasing away the pirates!", "model": "veo-3.1-fast", "aspectRatio": "portrait", "startImage": "user:12345-email:6a6f...-image:ff9aa5cc-...", "async": true }' ``` Agrega `endImage` (un segundo id de referencia subido) para fijar el último fotograma, y Veo genera la transición entre los dos. `endImage` requiere `startImage`: no se admite solo el fotograma final. Los modelos Omni (`omni-flash-1.2`, `omni-flash`) aceptan el mismo par, pero ahí los dos fotogramas son la única entrada que admiten: nada de `referenceImage_*`, `character_*` ni `referenceAudio_*` junto con ellos. #### Imágenes de referencia (R2V) Tus imágenes guían todo el video (sujeto, personaje o estilo) en lugar de un fotograma concreto. Pasa de `referenceImage_1` a `referenceImage_3` (Veo acepta hasta 3, solo en videos de 8 segundos y no en `veo-3.1-quality`). R2V no se puede combinar con `startImage`/`endImage`: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A lady says to the dog, \"Say meow meow meow.\" The dog looks at the lady with a surprised, frustrated look and woofs in a human voice, \"What the heck lady?!\"", "model": "veo-3.1-fast", "aspectRatio": "portrait", "referenceImage_1": "user:12345-email:6a6f...-image:abcde-...", "async": true }' ``` Menciona cada referencia dentro del prompt con un marcador `@referenceImage_N`, agrega un `referenceAudio_1` (el nombre de una voz del sistema, como `Zephyr`) para la narración, o pasa un [personaje](/docs/api-google-flow-v1/post-google-flow-characters) reutilizable como `character_1` (usa el mismo modo R2V y cuenta dentro del límite de 3 referencias). Omni 1.2 Flash lleva las referencias más lejos, con hasta 10, además de edición de video a video y voces sincronizadas: consulta el [tutorial de Omni Flash](/docs/articles/omni-flash-bash-es). ### Genera por lotes con un script Encontrar la toma correcta lleva muchos intentos, y lanzarlos a mano es tedioso. El script de Node.js de abajo lee una lista de prompts de `prompts.json`, sube las imágenes de fotograma inicial y final, envía cada job en modo asíncrono y después consulta y descarga cada MP4 terminado. Así puedes poner un lote en cola y volver después por los mejores. Necesitas [Node.js](https://nodejs.org) v21 o posterior. Pon `prompts.json` y `google-flow.mjs` en la misma carpeta y ejecuta `node ./google-flow.mjs API_TOKEN EMAIL`, donde `API_TOKEN` es tu [token de API](/docs/start-here/setup-useapi) de useapi.net y `EMAIL` es el correo de tu [cuenta de Google Flow](/docs/start-here/setup-google-flow) conectada. El script busca la cuenta por correo automáticamente y revisa su campo `health` antes de enviar. ¿Prefieres clonarlo y ejecutarlo en tu equipo? El `google-flow.mjs` y el `prompts.json` completos están en GitHub, en [`useapi/google-flow-api`](https://github.com/useapi/google-flow-api/tree/main/veo-video). <details markdown="block"> <summary>Abrir `prompts.json`</summary> ```json [ { "prompt": "By default the veo-3.1-fast model with a landscape 8-second clip will be used." }, { "model": "veo-3.1-quality", "aspectRatio": "landscape", "duration": 8, "count": 2, "prompt": "Highest-quality Veo 3.1, two variations. For all parameters see https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos" }, { "model": "veo-3.1-fast", "aspectRatio": "portrait", "duration": 8, "startImage": "./first_image.jpeg", "endImage": "./last_image.jpeg", "prompt": "Image-to-video with a start frame (startImage) and an end frame (endImage). Supported by Veo and by both Omni models." }, { "model": "omni-flash", "duration": 10, "prompt": "Gemini Omni Flash is audio-native and supports 10-second clips. Other models (veo-3.1-lite, veo-3.1-lite-low-priority, …) are selectable via the model field — see the POST /videos docs." } ] ``` </details> <details markdown="block"> <summary>Abrir el script `google-flow.mjs`</summary> ```javascript /* Script version 1.1, September 11, 2026 Script to batch-generate videos using prompts with the Google Flow API v1 by useapi.net 🚀 Uses the POST /videos endpoint in async mode (default model: veo-3.1-fast) and polls GET /jobs/{jobId}. For more details visit https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos Installation Instructions: ========================== You need Node.js v21 or newer installed to run this script. Download and install Node.js from: - Windows, macOS, Linux: https://nodejs.org/ After installation, verify by running the following command in a terminal: node -v Running the Script: =================== Usage: node google-flow.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE] Replace API_TOKEN with your actual useapi.net API token, see https://useapi.net/docs/start-here/setup-useapi Replace EMAIL with configured Google Flow email account, see https://useapi.net/docs/start-here/setup-google-flow If optional PROMPTS_FILE not provided prompts.json will be used. Example: -------- node google-flow.mjs user:1234-abcdefhijklmnopqrstuv my@email.com This command executes the script using API token user:1234-abcdefhijklmnopqrstuv with my@email.com Google Flow account email. Changelog: ========== - June 15, 2026: Initial release. - September 11, 2026: Accepts .jpg and upper-case image extensions for startImage and endImage. A prompt whose startImage or endImage fails to upload is skipped and logged to google-flow_errors.txt instead of being submitted without that frame. Saves a downloaded video under its final name only once it has been fully received, so a failed download leaves no partial MP4 for the next run to skip as "already exists". */ import readline from 'node:readline'; import fs from 'fs/promises'; import path from 'path'; import { writeFile } from 'node:fs/promises'; import { Readable } from 'node:stream'; // Constants const RESULTS_FILE = 'google-flow_results.txt'; const ERRORS_FILE = 'google-flow_errors.txt'; const DEFAULT_PROMPTS_FILE = 'prompts.json'; const DEFAULT_MODEL = 'veo-3.1-fast'; const SLEEP_429 = 30 * 1000; // in milliseconds const SLEEP_POLL = 15 * 1000; // in milliseconds const urlAccounts = 'https://api.useapi.net/v1/google-flow/accounts'; const urlVideos = 'https://api.useapi.net/v1/google-flow/videos'; const urlJobs = 'https://api.useapi.net/v1/google-flow/jobs/'; const urlUploadAsset = 'https://api.useapi.net/v1/google-flow/assets/'; // To upload .webp keep its .webp extension — Google Flow accepts png, jpeg and webp. const supportedFileExtensions = ['png', 'jpg', 'jpeg', 'webp']; // { filename: mediaGenerationId } const uploadedFiles = {}; // Utility to sleep for given milliseconds const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); // Function to fetch configured Google Flow API accounts async function fetchAccounts(apiToken) { const response = await fetch(urlAccounts, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.error(`⛔ Error fetching accounts (HTTP ${response.status}): ${response.statusText}`); process.exit(1); } return response.json(); } const elapsedTimeSec = (start) => (Date.now() - start) / 1000; // Map a file extension to the Content-Type required by POST /assets const contentTypeForExt = (ext) => ext === 'png' ? 'image/png' : ext === 'webp' ? 'image/webp' : 'image/jpeg'; async function uploadAsset(apiToken, email, filename) { // Check if already uploaded if (uploadedFiles.hasOwnProperty(filename)) return uploadedFiles[filename]; const startTime = Date.now(); console.log(`⬆️ Account ${email} uploading file…`, filename); const body = new Blob([await fs.readFile(filename)]); const fileExt = filename.split('.').pop().toLowerCase(); const response = await fetch(`${urlUploadAsset}${encodeURIComponent(email)}`, { method: 'POST', headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}`, 'Content-Type': contentTypeForExt(fileExt) }, body }); if (response.ok) { const json = await response.json(); // POST /assets returns the reference id nested as mediaGenerationId.mediaGenerationId const mediaGenerationId = json?.mediaGenerationId?.mediaGenerationId; console.log(`🆗 mediaGenerationId (${elapsedTimeSec(startTime)} sec)`, mediaGenerationId); uploadedFiles[filename] = mediaGenerationId; } else { console.error(`❗ Unable to upload file HTTP ${response.status} (${elapsedTimeSec(startTime)} sec)`, await response.text()); // Do not attempt to upload failed file again uploadedFiles[filename] = undefined; } return uploadedFiles[filename]; } async function submit(apiToken, url, body, index, prompt) { const createResponse = await fetch(url, { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiToken}` }, body }); const createBody = await createResponse.text(); // Async POST /videos returns 201 Created with a jobid to poll. if (createResponse.status == 201) { const json = JSON.parse(createBody); // 201 async payload uses lowercase "jobid"; sync 200 uses "jobId". Accept either. const jobId = json.jobid ?? json.jobId; if (jobId) { await fs.appendFile(RESULTS_FILE, `${jobId},#${index}:${prompt}\n`); console.log(`✅ jobId`, jobId); return 201; } else { const error = `No jobid found in HTTP 201 response`; console.log(`❓ ${error}`, createBody); await fs.appendFile(ERRORS_FILE, `${error},#${index}:${prompt}\n`); return 500; } } else { switch (createResponse.status) { case 429: console.log(`🔄️ Retry on HTTP ${createResponse.status}`, createBody); break; case 503: console.log(`🔄️ Service unavailable, retry on HTTP ${createResponse.status}`, createBody); break; case 400: console.log(`🛑 Rejected request (validation or content policy)`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${prompt}\n`); break; case 402: console.log(`🛑 No subscription / insufficient credits`, createBody); break; default: console.log(`❗ FAILED with HTTP ${createResponse.status}`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${prompt}\n`); } return createResponse.status; } } // Submit a single prompt to POST /videos in async mode. // startImage = start frame (I2V), endImage = end frame (I2V-FL, requires startImage). async function submitVideo(apiToken, email, prompt, index) { const { model, prompt: text, startImage, endImage, aspectRatio, duration, count } = prompt; const useModel = model ?? DEFAULT_MODEL; console.log(`🚀 ${useModel} » Prompt #${index} • account ${email} …`); const startImageId = startImage ? await uploadAsset(apiToken, email, startImage) : undefined; const endImageId = endImage ? await uploadAsset(apiToken, email, endImage) : undefined; // A frame that failed to upload would be left out of the body, and the prompt would still be // generated (and charged) without it. Skip the prompt instead. uploadAsset remembers the failed file, // so a later prompt using it is skipped too, without another upload attempt. const failedUploads = [['startImage', startImage, startImageId], ['endImage', endImage, endImageId]] .filter(([, file, id]) => file && !id); for (const [param, file] of failedUploads) { console.error(`🛑 Prompt #${index} skipped: ${param} ${file} failed to upload`); await fs.appendFile(ERRORS_FILE, `Upload failed for ${param} ${file},#${index}:${text}\n`); } if (failedUploads.length) return; const body = JSON.stringify({ model: useModel, email, prompt: text, aspectRatio, duration, count, startImage: startImageId, endImage: endImageId, async: true }); return await submit(apiToken, urlVideos, body, index, text); } // Function to download videos async function download(apiToken) { if (! await fileExists(RESULTS_FILE)) return; try { const resultsContent = await fs.readFile(RESULTS_FILE, 'utf8'); const lines = resultsContent.trim().split('\n'); for (const line of lines) { const [jobId, prompt] = line.split(','); console.log(`👉 ${jobId}`); while (true) { const response = await fetch(`${urlJobs}${jobId}`, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.log(`🛑 Poll failed ${jobId} (HTTP ${response.status}):\n${prompt}\n`, await response.text()); break; } const jobBody = await response.json(); const { status, error, response: jobResponse } = jobBody; if (status == 'failed') { console.error(`🛑 FAILED ${jobId} (${error}):\n${prompt}\n`); break; } if (status == 'completed') { const media = jobResponse?.media ?? []; if (media.length == 0) console.error(`🛑 Completed but no media for ${jobId}:\n${prompt}\n`); // A single prompt with count > 1 returns multiple videos. for (let i = 0; i < media.length; i++) { const url = media[i]?.videoUrl; const videoFilename = `${jobId.replace(/[:*]/g, '_')}_${i + 1}.mp4`; try { await fs.access(videoFilename); console.log(`⚠️ ${videoFilename} already exists. Skipping download.`); continue; } catch { // File does not exist, proceed with downloading } if (url) { console.log(`✅ Downloading ${url} to ${videoFilename}`); // Stream into a temporary file and rename it once the whole video has arrived, so a download // that drops mid-stream leaves no partial file behind for the next run to skip as "already exists". const tempFilename = `${videoFilename}.part`; try { const videoResponse = await fetch(url); if (!videoResponse.ok) { console.error(`⛔ Unable to download ${jobId} (HTTP ${videoResponse.status}):\n${prompt}\n`, url); continue; } const stream = Readable.fromWeb(videoResponse.body); await writeFile(tempFilename, stream); await fs.rename(tempFilename, videoFilename); } catch (err) { await fs.rm(tempFilename, { force: true }); console.error(`⛔ Error during download: ${err}`); } } else console.error(`🛑 No videoUrl for ${jobId} media #${i + 1}:\n${prompt}\n`); } break; } console.log(`⌛ ${jobId} status (${status}) and is still in progress, waiting…`); await sleep(SLEEP_POLL); } } } catch (error) { console.log(`⛔ Error during download:`, error.stack || error); } } // Main function async function main() { const apiToken = process.argv[2]; const email = process.argv[3]; const promptFile = process.argv[4] || DEFAULT_PROMPTS_FILE; if (!apiToken || !email) { console.error('Usage: node google-flow.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE]'); process.exit(1); } console.info('Script v1.1'); console.info('Node version is: ' + process.version); try { if (await fileExists(RESULTS_FILE)) { let user_input; while (!['y', 'n'].includes(user_input)) { user_input = (await promptUser(`❔ ${RESULTS_FILE} file detected. Do you want to download the results now? (y/n): `))?.toLowerCase(); if (user_input == 'y') { await download(apiToken); await fs.unlink(RESULTS_FILE); } } } const start = new Date(); try { console.info('START EXECUTION', start); await execute(apiToken, email, promptFile); // Pass the promptFile to execute function } finally { console.info('COMPLETED', new Date()); console.info('EXECUTION ELAPSED', diffInMinutesAndSeconds(start, new Date())); } try { console.info('START DOWNLOAD', start); await download(apiToken); } finally { console.info('TOTAL ELAPSED', diffInMinutesAndSeconds(start, new Date())); } } catch (error) { console.error('⛔ Error during execution:', error.stack || error); } } // Modify the execute function to accept promptFile as a parameter async function execute(apiToken, email, promptFile) { const accounts = await fetchAccounts(apiToken); console.info(`Configured Google Flow API accounts (${Object.keys(accounts).length}):`, Object.keys(accounts).join(', ')); if (Object.keys(accounts).length <= 0) { console.error(`⛔ No configured Google Flow accounts found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (!accounts[email]) { console.error(`⛔ Account ${email} not found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (accounts[email].health && accounts[email].health !== 'OK') { console.error(`⛔ Account ${email} health is '${accounts[email].health}'. Please resolve and update the account, see https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } const promptData = await fs.readFile(promptFile, 'utf8'); const prompts = JSON.parse(promptData); console.log(`Total number of prompts to process`, prompts.length); let warnings = []; // Parameters accepted by this script for the POST /videos endpoint. // See https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos for every model's full parameter set. const supportedParams = ['model', 'prompt', 'startImage', 'endImage', 'aspectRatio', 'duration', 'count']; const invalidKeys = (prompt) => Object.keys(prompt).filter(key => !key.startsWith('__') && !supportedParams.includes(key)) for (let i = 1; i <= prompts.length; i++) { const prompt = prompts[i - 1]; const { prompt: text, startImage, endImage } = prompt; const validateImage = async (file) => { if (file) { try { await fs.access(file); } catch { warnings.push(`⚠️ Image '${file}' does not exist. Prompt ${i}`); } const ext = file.split('.').pop().toLowerCase(); if (!supportedFileExtensions.includes(ext)) warnings.push(`⚠️ Image ${file} extension ${ext} not supported. Prompt ${i}`); } }; const notSupported = invalidKeys(prompt); if (notSupported.length) warnings.push(`⚠️ Following params not supported: ${notSupported.join(',')}. Prompt ${i}`); if (!text) warnings.push(`⚠️ prompt is required. Prompt ${i}`); if (endImage && !startImage) warnings.push(`⚠️ endImage requires startImage (end-frame-only is not supported). Prompt ${i}`); await Promise.all([validateImage(startImage), validateImage(endImage)]); } if (warnings.length > 0) { warnings.forEach(warning => console.warn(warning)); console.error(`⛔ Execution stopped due to warnings.`); process.exit(1); } for (let i = 0; i < prompts.length; i++) { const prompt = prompts[i]; while (true) { const responseCode = await submitVideo(apiToken, email, prompt, i + 1); if (responseCode == 429 || responseCode == 503) await sleep(SLEEP_429); else if (responseCode == 402) { process.exit(1); } else break; } } } // Utility function to check if a file exists async function fileExists(path) { try { await fs.access(path); return true; } catch { return false; } } // Function to prompt user input async function promptUser(query) { const rl = readline.createInterface({ input: process.stdin, output: process.stdout }); return new Promise((resolve) => rl.question(query, answer => { rl.close(); resolve(answer); })); } function diffInMinutesAndSeconds(date1, date2) { const diffInSeconds = Math.floor((date2 - date1) / 1000); return `${Math.floor(diffInSeconds / 60)} minutes ${diffInSeconds % 60} seconds`; }; main(); ``` </details> ### Ejemplos Videos reales de Veo 3.1 hechos con esta Google Flow API, tomados directamente de nuestras notas de lanzamiento. ###### veo-3.1-fast » El valiente Capitán Gato ahuyenta a los piratas (imagen a video) {: .no_toc #veo-31-fast--brave-captain-cat-chasing-away-the-pirates-image-to-video } De [Google Flow API v1: Initial Release](/blog/251117) (en inglés). Animado a partir de una imagen fija de Nano Banana pasada como `startImage`. <video poster="https://media.useapi.net/blog/2025-11-17-251117/veo-3-1-fast-poster.jpg" src="https://media.useapi.net/blog/2025-11-17-251117/veo-3-1-fast.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> ###### veo-3.1-fast » Una mujer y su perro, con narración de voz por IA {: .no_toc #veo-31-fast--lady-and-her-dog-with-ai-voice-narration } De [Veo 3.1 Lite and Voice Narration](/blog/260403) (en inglés). Referencia a video con el preset `referenceAudio_1: "Zephyr"`, que agrega diálogo hablado. <video poster="https://media.useapi.net/blog/2026-04-03-260403/veo-3-1-fast-voice-zephyr-poster.jpg" controls width="100%" style="max-width:400px"> <source src="https://media.useapi.net/blog/2026-04-03-260403/veo-3-1-fast-voice-zephyr.mp4" type="video/mp4"> </video> ###### veo-3.1-fast » Bailando chachachá (referencia a video en vertical) {: .no_toc #veo-31-fast--dancing-cha-cha-portrait-reference-to-video } De [Veo 3.1 Portrait R2V](/blog/260113) (en inglés). R2V en vertical a partir de una sola imagen de referencia. <video poster="https://media.useapi.net/blog/2026-01-13-260113/dancing-cha-cha-poster.jpg" src="https://media.useapi.net/blog/2026-01-13-260113/dancing-cha-cha.mp4" style="width: 100%; max-width: 400px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> ### Preguntas frecuentes - **¿Existe una API de Veo 3.1?** Con useapi.net, sí: la [Google Flow API](/docs/api-google-flow-v1) ejecuta Veo 3.1 Quality, Fast y Lite por REST con tu suscripción al sitio web de Google Flow (Google AI Pro o Ultra). Un video Veo 3.1 Quality de 8 segundos cuesta US$0,80 en Google AI Ultra US$199,99, frente a US$3,20 en la API oficial de Veo (a noviembre de 2026). - **¿Qué diferencia hay entre Veo 3.1 Quality, Fast y Lite?** Con useapi.net eliges uno en cada solicitud con el campo `model`. `veo-3.1-quality` da la mayor fidelidad, `veo-3.1-fast` es el equilibrio por defecto entre velocidad y calidad, y `veo-3.1-lite` es el más barato: US$0,04 por video en Google AI Ultra US$199,99, frente a US$0,40 en la API oficial de Veo. En ese plan, `veo-3.1-lite-low-priority` cuesta US$0, unos 1.000 videos o más al día (a noviembre de 2026). - **¿Puedo hacer imagen a video con Veo?** Con useapi.net, sí. Sube tu fotograma inicial con [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email) y pasa el id de referencia que devuelve (anidado en `mediaGenerationId.mediaGenerationId`) como `startImage`, y si quieres `endImage` para fijar el último fotograma (requiere `startImage`). Para guiar el sujeto o el estilo en lugar de un fotograma, pasa hasta tres `referenceImage_N`. Consulta [Imagen a video](#image-to-video-and-reference-to-video) más arriba. - **¿Tengo que resolver un captcha?** Con useapi.net nunca resuelves uno tú. Google Flow pide un reCAPTCHA en cada video, y el worker de useapi.net lo resuelve automáticamente: tu primera cuenta de Google Flow incluye 300 resoluciones gratis con nuestras propias claves de AntiCaptcha, CapSolver y EzCaptcha, y después agregas las claves de tu propio proveedor con [POST /accounts/captcha-providers](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers). El script de esta guía no envía `captchaToken`. - **¿Necesito una clave de API de Veo 3.1?** Con useapi.net no necesitas clave de API de Google ni proyecto de Google Cloud: un solo [token de API](/docs/start-here/setup-useapi) de useapi.net llama a Veo 3.1, y conectas tu cuenta de Google una vez con la [configuración automática](/docs/start-here/setup-google-flow). Google Flow en sí no tiene API pública, y desde que los modelos Veo 3.1 Preview de la Gemini API cerraron el 22 de octubre de 2026, la API de Veo del propio Google exige un proyecto de Cloud con facturación. ### Conclusión Visita nuestro <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> servidor de Discord</a> o nuestro <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> canal de Telegram</a> para cualquier pregunta de soporte. Consulta nuestro [repositorio de GitHub](https://github.com/useapi/google-flow-api) con ejemplos de código. #### Publicado también en {: .no_toc #cross-posted } También publicado en [dev.to](https://dev.to/useapi/how-to-generate-ai-video-with-veo-31-via-the-google-flow-api-2g4i){:rel="nofollow"} (en inglés). ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-flow-bash-id === Document URL: https://useapi.net/docs/articles/google-flow-bash-id --- layout: default title: "Cara Memakai Veo 3.1 API: Membuat Video dengan curl lewat Google Flow API" seo_title: "Veo 3.1 API dengan curl: Video lewat Google Flow API, Tanpa API Key" description: "Veo 3.1 API dari curl (Fast, Quality, Lite) lewat Google Flow API useapi.net di Google AI Pro atau Ultra: tanpa project Google Cloud, tanpa API key." keywords: [Veo 3.1 API, API Veo 3.1, Veo 3.1 API key, API key Veo 3.1, Veo API, Google Veo API, Veo 3 API, Google Flow API, API Google Flow, Veo 3.1 Fast, Veo 3.1 Lite, Gemini API Veo shutdown, Veo dihentikan di Gemini API, membuat video AI, text to video, teks ke video, image to video, gambar ke video, tutorial bahasa Indonesia, kode] parent: Articles nav_exclude: true lang: id translation_key: google-flow date: 2026-06-15 last_modified: 2026-11-10 nav_order: 810 repo: https://github.com/useapi/google-flow-api --- ## Cara Memakai Veo 3.1 API: Membuat Video dengan curl lewat Google Flow API {: .no_toc #how-to-use-the-veo-31-api-generate-video-with-curl-via-the-google-flow-api } 6 menit baca • 15 Juni 2026 (6 November 2026) useapi.net adalah API pihak ketiga. Kami tidak berafiliasi dengan Google dan tidak disahkan oleh Google. ## Daftar isi {: .no_toc .text-delta #table-of-contents } ### Pendahuluan [Veo 3.1](https://deepmind.google/technologies/veo/) berjalan dari satu `curl` lewat [Google Flow API](/docs/api-google-flow-v1) useapi.net, di langganan situs [Google Flow](https://flow.google.com) Anda ([Google AI Pro atau Ultra](https://gemini.google/subscriptions/)). Satu video Veo 3.1 Fast 8 detik berbiaya $0,08 di Google AI Ultra $199,99, dibanding $0,80 di Veo API resmi (per November 2026). Google menghentikan model Veo 3.1 Preview di Gemini API pada 22 Oktober 2026 dan memindahkan developer ke [Agent Platform](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing) di Cloud, yang menagih tarif per detik yang sama di project Google Cloud. API pihak ketiga ini tidak butuh project Cloud, API key Google, maupun persetujuan enterprise. Di bawah ini: model-modelnya, alur kerja dua panggilan, input gambar, dan skrip batch yang siap dijalankan. ### Model yang didukung Pilih model per request dengan field `model` (default `veo-3.1-fast`). Biaya kredit Veo berasal dari [tabel kredit Flow resmi](https://support.google.com/flow/answer/16526234?hl=id) Google, dan biaya Omni diukur langsung di API: | Id model | Tier / kecepatan | Durasi | Kredit per video | |----------|--------------|-----------|------------------------| | `veo-3.1-lite` | Veo termurah | 4s, 6s, 8s | 10 (Non-Ultra) · 5 (Ultra) | | `veo-3.1-lite-low-priority` | Lite, prioritas rendah | 4s, 6s, 8s | 0, hanya pemilik paket Ultra $199,99 | | `veo-3.1-fast` *(default)* | Veo cepat | 4s, 6s, 8s | 20 (Non-Ultra) · 10 (Ultra) | | `veo-3.1-quality` | Veo kualitas tertinggi | hanya 8s | 100 | | `omni-flash-1.2` | Omni 1.2 Flash, audio bawaan | 3s sampai 15s | 3 per detik hingga 10s, 6 per detik setelahnya (di 720p) | | `omni-flash` | Omni 1.1 Flash, audio bawaan | 4s, 6s, 8s, 10s | 7 / 10 / 12 / 15 (menurut durasi, di 720p) | Di Veo, video `4s` dan `6s` butuh Ultra (lihat [ringkasan API](/docs/api-google-flow-v1)). Google Flow juga membuat gambar diam dengan model Nano Banana lewat endpoint terpisah [POST /images](/docs/api-google-flow-v1/post-google-flow-images). ### Harga Setiap video memakai kredit Flow dari langganan Google AI Anda, tanpa biaya per video dari useapi.net. Harga per video di setiap paket, dibandingkan dengan API resmi, ada di [tabel harga Google Flow](/docs/api-google-flow-v1#pricing), dan [harga API Veo 3.1](/docs/articles/veo-3-1-api-pricing) (bahasa Inggris) membahas Veo secara rinci. ### Membuat video dalam dua panggilan API Anda butuh [API token](/docs/start-here/setup-useapi) useapi.net dan [akun Google Flow](/docs/start-here/setup-google-flow) yang sudah terhubung. Job video berjalan secara asynchronous: kirim `async: true` dan panggilan create langsung mengembalikan `jobid`, lalu Anda melakukan polling sampai videonya siap. 1. Kirim job — `POST https://api.useapi.net/v1/google-flow/videos`: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A serene mountain landscape at sunset, camera slowly panning right", "model": "veo-3.1-fast", "aspectRatio": "landscape", "duration": 8, "async": true }' ``` Dalam mode async, respons langsung kembali dengan `201 Created`, `jobid` berhuruf kecil, dan `status: "created"`: ```json { "jobid": "j1731859234567v-u12345-email:jo***@gmail.com-bot:google-flow", "type": "video", "status": "created", "created": "2026-06-15T12:34:56.789Z", "request": { "async": true, "prompt": "A serene mountain landscape at sunset, camera slowly panning right", "model": "veo-3.1-fast", "aspectRatio": "landscape", "duration": 8 } } ``` 2. Polling hasilnya — `GET https://api.useapi.net/v1/google-flow/jobs/{jobId}`: ```bash curl "https://api.useapi.net/v1/google-flow/jobs/{jobId}" \ -H "Authorization: Bearer $USEAPI_TOKEN" ``` `status` berpindah dari `created` → `started` → `completed`. Saat mencapai `completed`, MP4 jadi ada di `response.media[].videoUrl` (satu prompt dengan `count > 1` mengembalikan satu entri per video): ```json { "jobid": "j1731859234567v-...", "type": "video", "status": "completed", "response": { "media": [ { "mediaGenerationId": "user:12345-email:6a6f...-video:a1d95d21-...", "videoUrl": "https://flow-content.google/video/a1d95d21-...?Expires=...", "thumbnailUrl": "https://flow-content.google/image/a1d95d21-...?Expires=..." } ], "remainingCredits": 18760 } } ``` Veo 3.1 biasanya selesai dalam 60–180 detik, tergantung model dan mode. Dalam uji kami pada 20 Oktober 2026, sembilan video 8 detik butuh 50 sampai 105 detik dari pengiriman sampai MP4 jadi ([uji yang diukur](/docs/articles/veo-3-1-api-pricing#examples)). `videoUrl` yang ditandatangani berlaku sekitar 6 jam, jadi segera unduh. Tidak mau polling? Kirim `replyUrl` di body create untuk menerima callback webhook saat job selesai. ### Image-to-video dan reference-to-video Veo menerima input gambar dengan dua cara berbeda. Upload dulu setiap gambar dengan [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email) (byte mentah, `Content-Type` gambar, PNG/JPEG/WebP hingga 20 MB). Respons upload menyimpan id di `mediaGenerationId.mediaGenerationId` — string bersarang itulah yang Anda kirim kembali. Jika Anda memberi input gambar apa pun, `email` boleh dihilangkan: request diarahkan ke akun tempat gambar itu di-upload. #### Frame pertama / terakhir (I2V) Gambar Anda menjadi frame sungguhan di video. Kirim sebagai `startImage` untuk memulai dari frame itu: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Brave Captain Cat chasing away the pirates!", "model": "veo-3.1-fast", "aspectRatio": "portrait", "startImage": "user:12345-email:6a6f...-image:ff9aa5cc-...", "async": true }' ``` Tambahkan `endImage` (id referensi upload kedua) untuk mengunci frame terakhir, sehingga Veo membuat transisi di antara keduanya. `endImage` butuh `startImage` — hanya frame akhir tidak didukung. Model Omni (`omni-flash-1.2`, `omni-flash`) menerima pasangan yang sama, tetapi di sana kedua frame itu satu-satunya input yang diterima — tanpa `referenceImage_*`, `character_*` atau `referenceAudio_*` di sampingnya. #### Gambar referensi (R2V) Gambar Anda memandu seluruh video — subjek, karakter atau gaya — bukan frame tertentu. Kirim `referenceImage_1` sampai `referenceImage_3` (Veo menerima hingga 3, hanya untuk video 8 detik, dan tidak di `veo-3.1-quality`). R2V tidak bisa digabung dengan `startImage`/`endImage`: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A lady says to the dog, \"Say meow meow meow.\" The dog looks at the lady with a surprised, frustrated look and woofs in a human voice, \"What the heck lady?!\"", "model": "veo-3.1-fast", "aspectRatio": "portrait", "referenceImage_1": "user:12345-email:6a6f...-image:abcde-...", "async": true }' ``` Sebut setiap referensi secara inline dengan penanda `@referenceImage_N` di prompt, tambahkan `referenceAudio_1` (nama suara sistem seperti `Zephyr`) untuk narasi, atau kirim [karakter](/docs/api-google-flow-v1/post-google-flow-characters) yang bisa dipakai ulang sebagai `character_1` (karakter menjalankan mode R2V yang sama dan dihitung dalam batas 3 referensi). Omni 1.2 Flash membawa referensi lebih jauh — hingga 10, ditambah edit video-ke-video dan suara yang tersinkron — lihat [tutorial Omni Flash](/docs/articles/omni-flash-bash-id). ### Generate batch dengan skrip Menemukan shot yang pas butuh banyak percobaan, dan menjalankannya satu per satu dengan tangan itu melelahkan. Skrip Node.js di bawah membaca daftar prompt dari `prompts.json`, meng-upload gambar frame awal/akhir jika ada, mengirim setiap job dalam mode async, lalu melakukan polling dan mengunduh setiap MP4 yang sudah jadi — jadi Anda bisa mengantrekan satu batch lalu kembali untuk memilih yang terbaik. Anda butuh [Node.js](https://nodejs.org) v21 atau lebih baru. Taruh `prompts.json` dan `google-flow.mjs` di folder yang sama dan jalankan `node ./google-flow.mjs API_TOKEN EMAIL`, dengan `API_TOKEN` berisi [API token](/docs/start-here/setup-useapi) useapi.net Anda dan `EMAIL` berisi email [akun Google Flow](/docs/start-here/setup-google-flow) yang terhubung. Skrip mencari akun berdasarkan email secara otomatis dan memeriksa field `health`-nya sebelum mengirim. Lebih suka clone dan menjalankannya di komputer sendiri? `google-flow.mjs` dan `prompts.json` lengkap ada di GitHub di [`useapi/google-flow-api`](https://github.com/useapi/google-flow-api/tree/main/veo-video). <details markdown="block"> <summary>Buka `prompts.json`</summary> ```json [ { "prompt": "By default the veo-3.1-fast model with a landscape 8-second clip will be used." }, { "model": "veo-3.1-quality", "aspectRatio": "landscape", "duration": 8, "count": 2, "prompt": "Highest-quality Veo 3.1, two variations. For all parameters see https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos" }, { "model": "veo-3.1-fast", "aspectRatio": "portrait", "duration": 8, "startImage": "./first_image.jpeg", "endImage": "./last_image.jpeg", "prompt": "Image-to-video with a start frame (startImage) and an end frame (endImage). Supported by Veo and by both Omni models." }, { "model": "omni-flash", "duration": 10, "prompt": "Gemini Omni Flash is audio-native and supports 10-second clips. Other models (veo-3.1-lite, veo-3.1-lite-low-priority, …) are selectable via the model field — see the POST /videos docs." } ] ``` </details> <details markdown="block"> <summary>Buka skrip `google-flow.mjs`</summary> ```javascript /* Script version 1.1, September 11, 2026 Script to batch-generate videos using prompts with the Google Flow API v1 by useapi.net 🚀 Uses the POST /videos endpoint in async mode (default model: veo-3.1-fast) and polls GET /jobs/{jobId}. For more details visit https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos Installation Instructions: ========================== You need Node.js v21 or newer installed to run this script. Download and install Node.js from: - Windows, macOS, Linux: https://nodejs.org/ After installation, verify by running the following command in a terminal: node -v Running the Script: =================== Usage: node google-flow.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE] Replace API_TOKEN with your actual useapi.net API token, see https://useapi.net/docs/start-here/setup-useapi Replace EMAIL with configured Google Flow email account, see https://useapi.net/docs/start-here/setup-google-flow If optional PROMPTS_FILE not provided prompts.json will be used. Example: -------- node google-flow.mjs user:1234-abcdefhijklmnopqrstuv my@email.com This command executes the script using API token user:1234-abcdefhijklmnopqrstuv with my@email.com Google Flow account email. Changelog: ========== - June 15, 2026: Initial release. - September 11, 2026: Accepts .jpg and upper-case image extensions for startImage and endImage. A prompt whose startImage or endImage fails to upload is skipped and logged to google-flow_errors.txt instead of being submitted without that frame. Saves a downloaded video under its final name only once it has been fully received, so a failed download leaves no partial MP4 for the next run to skip as "already exists". */ import readline from 'node:readline'; import fs from 'fs/promises'; import path from 'path'; import { writeFile } from 'node:fs/promises'; import { Readable } from 'node:stream'; // Constants const RESULTS_FILE = 'google-flow_results.txt'; const ERRORS_FILE = 'google-flow_errors.txt'; const DEFAULT_PROMPTS_FILE = 'prompts.json'; const DEFAULT_MODEL = 'veo-3.1-fast'; const SLEEP_429 = 30 * 1000; // in milliseconds const SLEEP_POLL = 15 * 1000; // in milliseconds const urlAccounts = 'https://api.useapi.net/v1/google-flow/accounts'; const urlVideos = 'https://api.useapi.net/v1/google-flow/videos'; const urlJobs = 'https://api.useapi.net/v1/google-flow/jobs/'; const urlUploadAsset = 'https://api.useapi.net/v1/google-flow/assets/'; // To upload .webp keep its .webp extension — Google Flow accepts png, jpeg and webp. const supportedFileExtensions = ['png', 'jpg', 'jpeg', 'webp']; // { filename: mediaGenerationId } const uploadedFiles = {}; // Utility to sleep for given milliseconds const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); // Function to fetch configured Google Flow API accounts async function fetchAccounts(apiToken) { const response = await fetch(urlAccounts, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.error(`⛔ Error fetching accounts (HTTP ${response.status}): ${response.statusText}`); process.exit(1); } return response.json(); } const elapsedTimeSec = (start) => (Date.now() - start) / 1000; // Map a file extension to the Content-Type required by POST /assets const contentTypeForExt = (ext) => ext === 'png' ? 'image/png' : ext === 'webp' ? 'image/webp' : 'image/jpeg'; async function uploadAsset(apiToken, email, filename) { // Check if already uploaded if (uploadedFiles.hasOwnProperty(filename)) return uploadedFiles[filename]; const startTime = Date.now(); console.log(`⬆️ Account ${email} uploading file…`, filename); const body = new Blob([await fs.readFile(filename)]); const fileExt = filename.split('.').pop().toLowerCase(); const response = await fetch(`${urlUploadAsset}${encodeURIComponent(email)}`, { method: 'POST', headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}`, 'Content-Type': contentTypeForExt(fileExt) }, body }); if (response.ok) { const json = await response.json(); // POST /assets returns the reference id nested as mediaGenerationId.mediaGenerationId const mediaGenerationId = json?.mediaGenerationId?.mediaGenerationId; console.log(`🆗 mediaGenerationId (${elapsedTimeSec(startTime)} sec)`, mediaGenerationId); uploadedFiles[filename] = mediaGenerationId; } else { console.error(`❗ Unable to upload file HTTP ${response.status} (${elapsedTimeSec(startTime)} sec)`, await response.text()); // Do not attempt to upload failed file again uploadedFiles[filename] = undefined; } return uploadedFiles[filename]; } async function submit(apiToken, url, body, index, prompt) { const createResponse = await fetch(url, { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiToken}` }, body }); const createBody = await createResponse.text(); // Async POST /videos returns 201 Created with a jobid to poll. if (createResponse.status == 201) { const json = JSON.parse(createBody); // 201 async payload uses lowercase "jobid"; sync 200 uses "jobId". Accept either. const jobId = json.jobid ?? json.jobId; if (jobId) { await fs.appendFile(RESULTS_FILE, `${jobId},#${index}:${prompt}\n`); console.log(`✅ jobId`, jobId); return 201; } else { const error = `No jobid found in HTTP 201 response`; console.log(`❓ ${error}`, createBody); await fs.appendFile(ERRORS_FILE, `${error},#${index}:${prompt}\n`); return 500; } } else { switch (createResponse.status) { case 429: console.log(`🔄️ Retry on HTTP ${createResponse.status}`, createBody); break; case 503: console.log(`🔄️ Service unavailable, retry on HTTP ${createResponse.status}`, createBody); break; case 400: console.log(`🛑 Rejected request (validation or content policy)`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${prompt}\n`); break; case 402: console.log(`🛑 No subscription / insufficient credits`, createBody); break; default: console.log(`❗ FAILED with HTTP ${createResponse.status}`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${prompt}\n`); } return createResponse.status; } } // Submit a single prompt to POST /videos in async mode. // startImage = start frame (I2V), endImage = end frame (I2V-FL, requires startImage). async function submitVideo(apiToken, email, prompt, index) { const { model, prompt: text, startImage, endImage, aspectRatio, duration, count } = prompt; const useModel = model ?? DEFAULT_MODEL; console.log(`🚀 ${useModel} » Prompt #${index} • account ${email} …`); const startImageId = startImage ? await uploadAsset(apiToken, email, startImage) : undefined; const endImageId = endImage ? await uploadAsset(apiToken, email, endImage) : undefined; // A frame that failed to upload would be left out of the body, and the prompt would still be // generated (and charged) without it. Skip the prompt instead. uploadAsset remembers the failed file, // so a later prompt using it is skipped too, without another upload attempt. const failedUploads = [['startImage', startImage, startImageId], ['endImage', endImage, endImageId]] .filter(([, file, id]) => file && !id); for (const [param, file] of failedUploads) { console.error(`🛑 Prompt #${index} skipped: ${param} ${file} failed to upload`); await fs.appendFile(ERRORS_FILE, `Upload failed for ${param} ${file},#${index}:${text}\n`); } if (failedUploads.length) return; const body = JSON.stringify({ model: useModel, email, prompt: text, aspectRatio, duration, count, startImage: startImageId, endImage: endImageId, async: true }); return await submit(apiToken, urlVideos, body, index, text); } // Function to download videos async function download(apiToken) { if (! await fileExists(RESULTS_FILE)) return; try { const resultsContent = await fs.readFile(RESULTS_FILE, 'utf8'); const lines = resultsContent.trim().split('\n'); for (const line of lines) { const [jobId, prompt] = line.split(','); console.log(`👉 ${jobId}`); while (true) { const response = await fetch(`${urlJobs}${jobId}`, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.log(`🛑 Poll failed ${jobId} (HTTP ${response.status}):\n${prompt}\n`, await response.text()); break; } const jobBody = await response.json(); const { status, error, response: jobResponse } = jobBody; if (status == 'failed') { console.error(`🛑 FAILED ${jobId} (${error}):\n${prompt}\n`); break; } if (status == 'completed') { const media = jobResponse?.media ?? []; if (media.length == 0) console.error(`🛑 Completed but no media for ${jobId}:\n${prompt}\n`); // A single prompt with count > 1 returns multiple videos. for (let i = 0; i < media.length; i++) { const url = media[i]?.videoUrl; const videoFilename = `${jobId.replace(/[:*]/g, '_')}_${i + 1}.mp4`; try { await fs.access(videoFilename); console.log(`⚠️ ${videoFilename} already exists. Skipping download.`); continue; } catch { // File does not exist, proceed with downloading } if (url) { console.log(`✅ Downloading ${url} to ${videoFilename}`); // Stream into a temporary file and rename it once the whole video has arrived, so a download // that drops mid-stream leaves no partial file behind for the next run to skip as "already exists". const tempFilename = `${videoFilename}.part`; try { const videoResponse = await fetch(url); if (!videoResponse.ok) { console.error(`⛔ Unable to download ${jobId} (HTTP ${videoResponse.status}):\n${prompt}\n`, url); continue; } const stream = Readable.fromWeb(videoResponse.body); await writeFile(tempFilename, stream); await fs.rename(tempFilename, videoFilename); } catch (err) { await fs.rm(tempFilename, { force: true }); console.error(`⛔ Error during download: ${err}`); } } else console.error(`🛑 No videoUrl for ${jobId} media #${i + 1}:\n${prompt}\n`); } break; } console.log(`⌛ ${jobId} status (${status}) and is still in progress, waiting…`); await sleep(SLEEP_POLL); } } } catch (error) { console.log(`⛔ Error during download:`, error.stack || error); } } // Main function async function main() { const apiToken = process.argv[2]; const email = process.argv[3]; const promptFile = process.argv[4] || DEFAULT_PROMPTS_FILE; if (!apiToken || !email) { console.error('Usage: node google-flow.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE]'); process.exit(1); } console.info('Script v1.1'); console.info('Node version is: ' + process.version); try { if (await fileExists(RESULTS_FILE)) { let user_input; while (!['y', 'n'].includes(user_input)) { user_input = (await promptUser(`❔ ${RESULTS_FILE} file detected. Do you want to download the results now? (y/n): `))?.toLowerCase(); if (user_input == 'y') { await download(apiToken); await fs.unlink(RESULTS_FILE); } } } const start = new Date(); try { console.info('START EXECUTION', start); await execute(apiToken, email, promptFile); // Pass the promptFile to execute function } finally { console.info('COMPLETED', new Date()); console.info('EXECUTION ELAPSED', diffInMinutesAndSeconds(start, new Date())); } try { console.info('START DOWNLOAD', start); await download(apiToken); } finally { console.info('TOTAL ELAPSED', diffInMinutesAndSeconds(start, new Date())); } } catch (error) { console.error('⛔ Error during execution:', error.stack || error); } } // Modify the execute function to accept promptFile as a parameter async function execute(apiToken, email, promptFile) { const accounts = await fetchAccounts(apiToken); console.info(`Configured Google Flow API accounts (${Object.keys(accounts).length}):`, Object.keys(accounts).join(', ')); if (Object.keys(accounts).length <= 0) { console.error(`⛔ No configured Google Flow accounts found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (!accounts[email]) { console.error(`⛔ Account ${email} not found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (accounts[email].health && accounts[email].health !== 'OK') { console.error(`⛔ Account ${email} health is '${accounts[email].health}'. Please resolve and update the account, see https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } const promptData = await fs.readFile(promptFile, 'utf8'); const prompts = JSON.parse(promptData); console.log(`Total number of prompts to process`, prompts.length); let warnings = []; // Parameters accepted by this script for the POST /videos endpoint. // See https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos for every model's full parameter set. const supportedParams = ['model', 'prompt', 'startImage', 'endImage', 'aspectRatio', 'duration', 'count']; const invalidKeys = (prompt) => Object.keys(prompt).filter(key => !key.startsWith('__') && !supportedParams.includes(key)) for (let i = 1; i <= prompts.length; i++) { const prompt = prompts[i - 1]; const { prompt: text, startImage, endImage } = prompt; const validateImage = async (file) => { if (file) { try { await fs.access(file); } catch { warnings.push(`⚠️ Image '${file}' does not exist. Prompt ${i}`); } const ext = file.split('.').pop().toLowerCase(); if (!supportedFileExtensions.includes(ext)) warnings.push(`⚠️ Image ${file} extension ${ext} not supported. Prompt ${i}`); } }; const notSupported = invalidKeys(prompt); if (notSupported.length) warnings.push(`⚠️ Following params not supported: ${notSupported.join(',')}. Prompt ${i}`); if (!text) warnings.push(`⚠️ prompt is required. Prompt ${i}`); if (endImage && !startImage) warnings.push(`⚠️ endImage requires startImage (end-frame-only is not supported). Prompt ${i}`); await Promise.all([validateImage(startImage), validateImage(endImage)]); } if (warnings.length > 0) { warnings.forEach(warning => console.warn(warning)); console.error(`⛔ Execution stopped due to warnings.`); process.exit(1); } for (let i = 0; i < prompts.length; i++) { const prompt = prompts[i]; while (true) { const responseCode = await submitVideo(apiToken, email, prompt, i + 1); if (responseCode == 429 || responseCode == 503) await sleep(SLEEP_429); else if (responseCode == 402) { process.exit(1); } else break; } } } // Utility function to check if a file exists async function fileExists(path) { try { await fs.access(path); return true; } catch { return false; } } // Function to prompt user input async function promptUser(query) { const rl = readline.createInterface({ input: process.stdin, output: process.stdout }); return new Promise((resolve) => rl.question(query, answer => { rl.close(); resolve(answer); })); } function diffInMinutesAndSeconds(date1, date2) { const diffInSeconds = Math.floor((date2 - date1) / 1000); return `${Math.floor(diffInSeconds / 60)} minutes ${diffInSeconds % 60} seconds`; }; main(); ``` </details> ### Contoh Video Veo 3.1 asli yang dibuat lewat Google Flow API ini, langsung dari catatan rilis kami. ###### veo-3.1-fast » Kapten Kucing pemberani mengusir bajak laut (image-to-video) {: .no_toc #veo-31-fast--brave-captain-cat-chasing-away-the-pirates-image-to-video } Dari [Google Flow API v1: Initial Release](/blog/251117). Dianimasikan dari gambar diam Nano Banana yang dikirim sebagai `startImage`. <video poster="https://media.useapi.net/blog/2025-11-17-251117/veo-3-1-fast-poster.jpg" src="https://media.useapi.net/blog/2025-11-17-251117/veo-3-1-fast.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> ###### veo-3.1-fast » Seorang wanita dan anjingnya, dengan narasi suara AI {: .no_toc #veo-31-fast--lady-and-her-dog-with-ai-voice-narration } Dari [Veo 3.1 Lite and Voice Narration](/blog/260403). Reference-to-video dengan preset `referenceAudio_1: "Zephyr"` yang menambahkan dialog lisan. <video poster="https://media.useapi.net/blog/2026-04-03-260403/veo-3-1-fast-voice-zephyr-poster.jpg" controls width="100%" style="max-width:400px"> <source src="https://media.useapi.net/blog/2026-04-03-260403/veo-3-1-fast-voice-zephyr.mp4" type="video/mp4"> </video> ###### veo-3.1-fast » Menari cha-cha (reference-to-video potret) {: .no_toc #veo-31-fast--dancing-cha-cha-portrait-reference-to-video } Dari [Veo 3.1 Portrait R2V](/blog/260113). R2V potret dari satu gambar referensi. <video poster="https://media.useapi.net/blog/2026-01-13-260113/dancing-cha-cha-poster.jpg" src="https://media.useapi.net/blog/2026-01-13-260113/dancing-cha-cha.mp4" style="width: 100%; max-width: 400px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> ### Pertanyaan yang sering diajukan - **Apakah ada API Veo 3.1?** Lewat useapi.net, ada: [Google Flow API](/docs/api-google-flow-v1) menjalankan Veo 3.1 Quality, Fast dan Lite lewat REST di langganan situs Google Flow Anda (Google AI Pro atau Ultra). Satu video Veo 3.1 Quality 8 detik berbiaya $0,80 di Google AI Ultra $199,99, dibanding $3,20 di Veo API resmi (per November 2026). - **Apa beda Veo 3.1 Quality, Fast dan Lite?** Lewat useapi.net Anda memilih salah satunya per request dengan field `model`. `veo-3.1-quality` memberi kualitas tertinggi, `veo-3.1-fast` adalah default yang seimbang antara kecepatan dan kualitas, dan `veo-3.1-lite` paling murah: $0,04 per video di Google AI Ultra $199,99, dibanding $0,40 di Veo API resmi. Di paket itu, `veo-3.1-lite-low-priority` berbiaya $0, sekitar 1.000 video atau lebih per hari (per November 2026). - **Bisakah membuat image-to-video dengan Veo?** Lewat useapi.net, bisa. Upload frame awal Anda dengan [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email), lalu kirim id referensi yang dikembalikan (bersarang di `mediaGenerationId.mediaGenerationId`) sebagai `startImage`, dan jika perlu `endImage` untuk mengunci frame terakhir (butuh `startImage`). Untuk memandu subjek atau gaya alih-alih frame, kirim hingga tiga `referenceImage_N`. Lihat [Image-to-video](#image-to-video-and-reference-to-video) di atas. - **Apakah saya harus menyelesaikan captcha?** Lewat useapi.net Anda tidak pernah menyelesaikannya sendiri. Google Flow meminta reCAPTCHA untuk setiap video, dan worker useapi.net menyelesaikannya otomatis: akun Google Flow pertama Anda mendapat 300 penyelesaian gratis dengan key AntiCaptcha, CapSolver dan EzCaptcha milik kami, dan setelah itu Anda menambahkan key penyedia sendiri dengan [POST /accounts/captcha-providers](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers). Skrip di panduan ini tidak mengirim `captchaToken`. - **Apakah saya butuh API key Veo 3.1?** Lewat useapi.net Anda tidak butuh API key Google maupun project Google Cloud: satu [API token](/docs/start-here/setup-useapi) useapi.net memanggil Veo 3.1, dan Anda menghubungkan akun Google sekali lewat [setup otomatis](/docs/start-here/setup-google-flow). Google Flow sendiri tidak punya API publik, dan sejak model Veo 3.1 Preview di Gemini API dihentikan pada 22 Oktober 2026, Veo API milik Google butuh project Cloud dengan billing. ### Kesimpulan Kunjungi <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Server Discord</a> atau <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Channel Telegram</a> kami untuk pertanyaan dan masalah dukungan. Lihat [repo GitHub](https://github.com/useapi/google-flow-api) kami berisi contoh kode. #### Dipublikasikan juga di {: .no_toc #cross-posted } Juga dipublikasikan di [dev.to](https://dev.to/useapi/how-to-generate-ai-video-with-veo-31-via-the-google-flow-api-2g4i){:rel="nofollow"} (bahasa Inggris). ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-flow-bash-ja === Document URL: https://useapi.net/docs/articles/google-flow-bash-ja --- layout: default title: "Veo 3.1 API の使い方:Google Flow API と curl で動画を生成する" seo_title: "Veo 3.1 API の使い方:curl で動画生成(API キー不要)" description: "useapi.net の Google Flow API で Veo 3.1(Fast、Quality、Lite)を curl から使う方法。Google AI Pro・Ultra のプランで、Google Cloud プロジェクトも API キーも不要。" keywords: [Veo 3.1 API, Veo 3.1 API 使い方, Veo 3.1 API キー, Veo 3.1 API 料金, Veo API, Google Veo API, Veo 3 API, Google Flow API, Veo 3.1 Fast, Veo 3.1 Lite, Veo 3.1 Quality, Gemini API Veo 終了, 動画生成 API, テキストから動画, 画像から動画, AI 動画生成, curl, 日本語チュートリアル, Japanese tutorial] parent: Articles nav_exclude: true lang: ja translation_key: google-flow date: 2026-06-15 last_modified: 2026-11-10 nav_order: 810 repo: https://github.com/useapi/google-flow-api --- ## Veo 3.1 API の使い方:Google Flow API と curl で動画を生成する {: .no_toc #how-to-use-the-veo-31-api-generate-video-with-curl-via-the-google-flow-api } 6分で読めます • 2026年6月15日(2026年11月6日更新) useapi.net はサードパーティの API です。Google とは提携しておらず、Google の承認も受けていません。 ## 目次 {: .no_toc .text-delta #table-of-contents } ### はじめに [Veo 3.1](https://deepmind.google/technologies/veo/) は、useapi.net の [Google Flow API](/docs/api-google-flow-v1) を通して、`curl` 1回で動きます。使うのは、お使いの [Google Flow](https://flow.google.com) の Web サイトのプラン([Google AI Pro または Ultra](https://gemini.google/subscriptions/))です。8秒の Veo 3.1 Fast の動画は Google AI Ultra $199.99 で $0.08 で、公式の Veo API では $0.80 です(2026年11月時点)。 Google は2026年10月22日に Gemini API の Veo 3.1 Preview モデルを終了し、開発者を Cloud の [Agent Platform](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing) に移しました。Agent Platform は、同じ1秒あたりの料金を Google Cloud プロジェクトに請求します。このサードパーティの API なら、Cloud プロジェクトも Google の API キーも企業向けの承認も不要です。以下では、モデル、2回の呼び出しで終わる流れ、画像の入力、そのまま動く一括生成スクリプトを紹介します。 ### 対応モデル モデルはリクエストごとに `model` フィールドで選びます(デフォルトは `veo-3.1-fast`)。Veo のクレジット数は Google の[公式の Flow クレジット表](https://support.google.com/flow/answer/16526234?hl=ja)によるもので、Omni のクレジット数は実際の API で測定した値です。 | モデル ID | 種類・速度 | 長さ | 動画1本のクレジット | |----------|--------------|-----------|------------------------| | `veo-3.1-lite` | 最も安い Veo | 4秒、6秒、8秒 | 10(Ultra 以外)・5(Ultra) | | `veo-3.1-lite-low-priority` | Lite、低優先度 | 4秒、6秒、8秒 | 0、Ultra $199.99 のプランのオーナーのみ | | `veo-3.1-fast` *(デフォルト)* | 高速な Veo | 4秒、6秒、8秒 | 20(Ultra 以外)・10(Ultra) | | `veo-3.1-quality` | 最高品質の Veo | 8秒のみ | 100 | | `omni-flash-1.2` | Omni 1.2 Flash、音声ネイティブ | 3〜15秒 | 10秒までは1秒3、それ以降は1秒6(720p) | | `omni-flash` | Omni 1.1 Flash、音声ネイティブ | 4秒、6秒、8秒、10秒 | 7 / 10 / 12 / 15(長さ別、720p) | Veo の4秒と6秒の動画には Ultra が必要です([概要](/docs/api-google-flow-v1)を参照)。Google Flow では、別のエンドポイント [POST /images](/docs/api-google-flow-v1/post-google-flow-images) で Nano Banana のモデルを使った静止画も作れます。 ### 料金 動画は1本ごとに Google AI のプランの Flow クレジットを使い、useapi.net が動画ごとに料金を取ることはありません。各プランでの動画1本の料金と公式 API との比較は [Google Flow の料金表](/docs/api-google-flow-v1#pricing)に、Veo の詳しい料金は [Veo 3.1 API の料金比較](/docs/articles/veo-3-1-api-pricing)(英語)にあります。 ### 2回の API 呼び出しで動画を生成する useapi.net の [API トークン](/docs/start-here/setup-useapi)と、接続済みの [Google Flow アカウント](/docs/start-here/setup-google-flow)が必要です。動画のジョブは非同期です。`async: true` を渡すと作成の呼び出しはすぐに `jobid` を返すので、動画ができるまでポーリングします。 1. ジョブを送信する — `POST https://api.useapi.net/v1/google-flow/videos`: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A serene mountain landscape at sunset, camera slowly panning right", "model": "veo-3.1-fast", "aspectRatio": "landscape", "duration": 8, "async": true }' ``` 非同期モードでは、すぐに `201 Created` の応答が返り、小文字の `jobid` と `status: "created"` が入っています。 ```json { "jobid": "j1731859234567v-u12345-email:jo***@gmail.com-bot:google-flow", "type": "video", "status": "created", "created": "2026-06-15T12:34:56.789Z", "request": { "async": true, "prompt": "A serene mountain landscape at sunset, camera slowly panning right", "model": "veo-3.1-fast", "aspectRatio": "landscape", "duration": 8 } } ``` 2. 結果をポーリングする — `GET https://api.useapi.net/v1/google-flow/jobs/{jobId}`: ```bash curl "https://api.useapi.net/v1/google-flow/jobs/{jobId}" \ -H "Authorization: Bearer $USEAPI_TOKEN" ``` `status` は `created` → `started` → `completed` と進みます。`completed` になると、完成した MP4 が `response.media[].videoUrl` に入っています(1つのプロンプトで `count > 1` を指定すると、動画ごとに1件ずつ返ります)。 ```json { "jobid": "j1731859234567v-...", "type": "video", "status": "completed", "response": { "media": [ { "mediaGenerationId": "user:12345-email:6a6f...-video:a1d95d21-...", "videoUrl": "https://flow-content.google/video/a1d95d21-...?Expires=...", "thumbnailUrl": "https://flow-content.google/image/a1d95d21-...?Expires=..." } ], "remainingCredits": 18760 } } ``` Veo 3.1 は、モデルとモードによって通常60〜180秒で完了します。2026年10月20日の当社の実行では、8秒の動画9本が、送信から MP4 の完成まで50〜105秒でした([測定した実行](/docs/articles/veo-3-1-api-pricing#examples)、英語)。署名付きの `videoUrl` は約6時間有効なので、早めにダウンロードしてください。ポーリングしたくない場合は、作成のボディに `replyUrl` を渡すと、ジョブの完了時に Webhook で通知を受け取れます。 ### 画像から動画、参照画像から動画 Veo は2つの方法で画像を入力として受け取ります。まず各画像を [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email) でアップロードします(生のバイト列、画像の `Content-Type`、20 MB までの PNG/JPEG/WebP)。アップロードの応答では、ID が `mediaGenerationId.mediaGenerationId` に入れ子になっています。この入れ子の文字列を次のリクエストに渡します。画像を入力に指定した場合は `email` を省略でき、リクエストは画像をアップロードしたアカウントに送られます。 #### 開始・終了フレーム(I2V) 画像は、そのまま動画の1フレームになります。`startImage` として渡すと、動画はそのフレームから始まります。 ```bash curl -X POST "https://api.useapi.net/v1/google-flow/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Brave Captain Cat chasing away the pirates!", "model": "veo-3.1-fast", "aspectRatio": "portrait", "startImage": "user:12345-email:6a6f...-image:ff9aa5cc-...", "async": true }' ``` `endImage`(2つ目のアップロードした参照 ID)を追加すると最後のフレームが固定され、Veo は2つのフレームの間をつなぐ動画を作ります。`endImage` には `startImage` が必要で、終了フレームだけの指定はできません。Omni のモデル(`omni-flash-1.2`、`omni-flash`)も同じ組み合わせを受け付けますが、その場合は2つのフレームが唯一の入力になり、`referenceImage_*`、`character_*`、`referenceAudio_*` は一緒に使えません。 #### 参照画像(R2V) 画像は特定のフレームではなく、被写体、キャラクター、スタイルなど動画全体の方向を決めます。`referenceImage_1` から `referenceImage_3` までを渡します(Veo は最大3枚で、8秒の動画のみ、`veo-3.1-quality` では使えません)。R2V は `startImage`/`endImage` と組み合わせられません。 ```bash curl -X POST "https://api.useapi.net/v1/google-flow/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A lady says to the dog, \"Say meow meow meow.\" The dog looks at the lady with a surprised, frustrated look and woofs in a human voice, \"What the heck lady?!\"", "model": "veo-3.1-fast", "aspectRatio": "portrait", "referenceImage_1": "user:12345-email:6a6f...-image:abcde-...", "async": true }' ``` プロンプトの中では、各参照をインラインの `@referenceImage_N` で指定します。ナレーションには `referenceAudio_1`(`Zephyr` のようなシステムの声の名前)を追加でき、再利用できる[キャラクター](/docs/api-google-flow-v1/post-google-flow-characters)を `character_1` として渡すこともできます(同じ R2V モードで動き、3つの参照の枠に数えられます)。Omni 1.2 Flash では参照をさらに広く使えます。最大10枚の参照、動画から動画への編集、同期した声に対応しています。[Omni Flash のチュートリアル](/docs/articles/omni-flash-bash-ja)を参照してください。 ### スクリプトで一括生成する 狙いどおりのショットを得るには何度も試す必要があり、手作業で1本ずつ実行するのは面倒です。下の Node.js スクリプトは、`prompts.json` からプロンプトのリストを読み込み、開始・終了フレームの画像をアップロードし、各ジョブを非同期モードで送信してから、完成した MP4 をポーリングしてすべてダウンロードします。まとめてキューに入れておき、あとで良いものを選べます。 [Node.js](https://nodejs.org) v21 以降が必要です。`prompts.json` と `google-flow.mjs` を同じフォルダーに置き、`node ./google-flow.mjs API_TOKEN EMAIL` を実行します。`API_TOKEN` は useapi.net の [API トークン](/docs/start-here/setup-useapi)、`EMAIL` は接続済みの [Google Flow アカウント](/docs/start-here/setup-google-flow)のメールアドレスです。スクリプトはメールアドレスからアカウントを自動で探し、送信前に `health` フィールドを確認します。 クローンしてローカルで実行したい場合は、`google-flow.mjs` と `prompts.json` の完全版が GitHub の [`useapi/google-flow-api`](https://github.com/useapi/google-flow-api/tree/main/veo-video) にあります。 <details markdown="block"> <summary>`prompts.json` を表示</summary> ```json [ { "prompt": "By default the veo-3.1-fast model with a landscape 8-second clip will be used." }, { "model": "veo-3.1-quality", "aspectRatio": "landscape", "duration": 8, "count": 2, "prompt": "Highest-quality Veo 3.1, two variations. For all parameters see https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos" }, { "model": "veo-3.1-fast", "aspectRatio": "portrait", "duration": 8, "startImage": "./first_image.jpeg", "endImage": "./last_image.jpeg", "prompt": "Image-to-video with a start frame (startImage) and an end frame (endImage). Supported by Veo and by both Omni models." }, { "model": "omni-flash", "duration": 10, "prompt": "Gemini Omni Flash is audio-native and supports 10-second clips. Other models (veo-3.1-lite, veo-3.1-lite-low-priority, …) are selectable via the model field — see the POST /videos docs." } ] ``` </details> <details markdown="block"> <summary>`google-flow.mjs` スクリプトを表示</summary> ```javascript /* Script version 1.1, September 11, 2026 Script to batch-generate videos using prompts with the Google Flow API v1 by useapi.net 🚀 Uses the POST /videos endpoint in async mode (default model: veo-3.1-fast) and polls GET /jobs/{jobId}. For more details visit https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos Installation Instructions: ========================== You need Node.js v21 or newer installed to run this script. Download and install Node.js from: - Windows, macOS, Linux: https://nodejs.org/ After installation, verify by running the following command in a terminal: node -v Running the Script: =================== Usage: node google-flow.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE] Replace API_TOKEN with your actual useapi.net API token, see https://useapi.net/docs/start-here/setup-useapi Replace EMAIL with configured Google Flow email account, see https://useapi.net/docs/start-here/setup-google-flow If optional PROMPTS_FILE not provided prompts.json will be used. Example: -------- node google-flow.mjs user:1234-abcdefhijklmnopqrstuv my@email.com This command executes the script using API token user:1234-abcdefhijklmnopqrstuv with my@email.com Google Flow account email. Changelog: ========== - June 15, 2026: Initial release. - September 11, 2026: Accepts .jpg and upper-case image extensions for startImage and endImage. A prompt whose startImage or endImage fails to upload is skipped and logged to google-flow_errors.txt instead of being submitted without that frame. Saves a downloaded video under its final name only once it has been fully received, so a failed download leaves no partial MP4 for the next run to skip as "already exists". */ import readline from 'node:readline'; import fs from 'fs/promises'; import path from 'path'; import { writeFile } from 'node:fs/promises'; import { Readable } from 'node:stream'; // Constants const RESULTS_FILE = 'google-flow_results.txt'; const ERRORS_FILE = 'google-flow_errors.txt'; const DEFAULT_PROMPTS_FILE = 'prompts.json'; const DEFAULT_MODEL = 'veo-3.1-fast'; const SLEEP_429 = 30 * 1000; // in milliseconds const SLEEP_POLL = 15 * 1000; // in milliseconds const urlAccounts = 'https://api.useapi.net/v1/google-flow/accounts'; const urlVideos = 'https://api.useapi.net/v1/google-flow/videos'; const urlJobs = 'https://api.useapi.net/v1/google-flow/jobs/'; const urlUploadAsset = 'https://api.useapi.net/v1/google-flow/assets/'; // To upload .webp keep its .webp extension — Google Flow accepts png, jpeg and webp. const supportedFileExtensions = ['png', 'jpg', 'jpeg', 'webp']; // { filename: mediaGenerationId } const uploadedFiles = {}; // Utility to sleep for given milliseconds const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); // Function to fetch configured Google Flow API accounts async function fetchAccounts(apiToken) { const response = await fetch(urlAccounts, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.error(`⛔ Error fetching accounts (HTTP ${response.status}): ${response.statusText}`); process.exit(1); } return response.json(); } const elapsedTimeSec = (start) => (Date.now() - start) / 1000; // Map a file extension to the Content-Type required by POST /assets const contentTypeForExt = (ext) => ext === 'png' ? 'image/png' : ext === 'webp' ? 'image/webp' : 'image/jpeg'; async function uploadAsset(apiToken, email, filename) { // Check if already uploaded if (uploadedFiles.hasOwnProperty(filename)) return uploadedFiles[filename]; const startTime = Date.now(); console.log(`⬆️ Account ${email} uploading file…`, filename); const body = new Blob([await fs.readFile(filename)]); const fileExt = filename.split('.').pop().toLowerCase(); const response = await fetch(`${urlUploadAsset}${encodeURIComponent(email)}`, { method: 'POST', headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}`, 'Content-Type': contentTypeForExt(fileExt) }, body }); if (response.ok) { const json = await response.json(); // POST /assets returns the reference id nested as mediaGenerationId.mediaGenerationId const mediaGenerationId = json?.mediaGenerationId?.mediaGenerationId; console.log(`🆗 mediaGenerationId (${elapsedTimeSec(startTime)} sec)`, mediaGenerationId); uploadedFiles[filename] = mediaGenerationId; } else { console.error(`❗ Unable to upload file HTTP ${response.status} (${elapsedTimeSec(startTime)} sec)`, await response.text()); // Do not attempt to upload failed file again uploadedFiles[filename] = undefined; } return uploadedFiles[filename]; } async function submit(apiToken, url, body, index, prompt) { const createResponse = await fetch(url, { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiToken}` }, body }); const createBody = await createResponse.text(); // Async POST /videos returns 201 Created with a jobid to poll. if (createResponse.status == 201) { const json = JSON.parse(createBody); // 201 async payload uses lowercase "jobid"; sync 200 uses "jobId". Accept either. const jobId = json.jobid ?? json.jobId; if (jobId) { await fs.appendFile(RESULTS_FILE, `${jobId},#${index}:${prompt}\n`); console.log(`✅ jobId`, jobId); return 201; } else { const error = `No jobid found in HTTP 201 response`; console.log(`❓ ${error}`, createBody); await fs.appendFile(ERRORS_FILE, `${error},#${index}:${prompt}\n`); return 500; } } else { switch (createResponse.status) { case 429: console.log(`🔄️ Retry on HTTP ${createResponse.status}`, createBody); break; case 503: console.log(`🔄️ Service unavailable, retry on HTTP ${createResponse.status}`, createBody); break; case 400: console.log(`🛑 Rejected request (validation or content policy)`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${prompt}\n`); break; case 402: console.log(`🛑 No subscription / insufficient credits`, createBody); break; default: console.log(`❗ FAILED with HTTP ${createResponse.status}`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${prompt}\n`); } return createResponse.status; } } // Submit a single prompt to POST /videos in async mode. // startImage = start frame (I2V), endImage = end frame (I2V-FL, requires startImage). async function submitVideo(apiToken, email, prompt, index) { const { model, prompt: text, startImage, endImage, aspectRatio, duration, count } = prompt; const useModel = model ?? DEFAULT_MODEL; console.log(`🚀 ${useModel} » Prompt #${index} • account ${email} …`); const startImageId = startImage ? await uploadAsset(apiToken, email, startImage) : undefined; const endImageId = endImage ? await uploadAsset(apiToken, email, endImage) : undefined; // A frame that failed to upload would be left out of the body, and the prompt would still be // generated (and charged) without it. Skip the prompt instead. uploadAsset remembers the failed file, // so a later prompt using it is skipped too, without another upload attempt. const failedUploads = [['startImage', startImage, startImageId], ['endImage', endImage, endImageId]] .filter(([, file, id]) => file && !id); for (const [param, file] of failedUploads) { console.error(`🛑 Prompt #${index} skipped: ${param} ${file} failed to upload`); await fs.appendFile(ERRORS_FILE, `Upload failed for ${param} ${file},#${index}:${text}\n`); } if (failedUploads.length) return; const body = JSON.stringify({ model: useModel, email, prompt: text, aspectRatio, duration, count, startImage: startImageId, endImage: endImageId, async: true }); return await submit(apiToken, urlVideos, body, index, text); } // Function to download videos async function download(apiToken) { if (! await fileExists(RESULTS_FILE)) return; try { const resultsContent = await fs.readFile(RESULTS_FILE, 'utf8'); const lines = resultsContent.trim().split('\n'); for (const line of lines) { const [jobId, prompt] = line.split(','); console.log(`👉 ${jobId}`); while (true) { const response = await fetch(`${urlJobs}${jobId}`, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.log(`🛑 Poll failed ${jobId} (HTTP ${response.status}):\n${prompt}\n`, await response.text()); break; } const jobBody = await response.json(); const { status, error, response: jobResponse } = jobBody; if (status == 'failed') { console.error(`🛑 FAILED ${jobId} (${error}):\n${prompt}\n`); break; } if (status == 'completed') { const media = jobResponse?.media ?? []; if (media.length == 0) console.error(`🛑 Completed but no media for ${jobId}:\n${prompt}\n`); // A single prompt with count > 1 returns multiple videos. for (let i = 0; i < media.length; i++) { const url = media[i]?.videoUrl; const videoFilename = `${jobId.replace(/[:*]/g, '_')}_${i + 1}.mp4`; try { await fs.access(videoFilename); console.log(`⚠️ ${videoFilename} already exists. Skipping download.`); continue; } catch { // File does not exist, proceed with downloading } if (url) { console.log(`✅ Downloading ${url} to ${videoFilename}`); // Stream into a temporary file and rename it once the whole video has arrived, so a download // that drops mid-stream leaves no partial file behind for the next run to skip as "already exists". const tempFilename = `${videoFilename}.part`; try { const videoResponse = await fetch(url); if (!videoResponse.ok) { console.error(`⛔ Unable to download ${jobId} (HTTP ${videoResponse.status}):\n${prompt}\n`, url); continue; } const stream = Readable.fromWeb(videoResponse.body); await writeFile(tempFilename, stream); await fs.rename(tempFilename, videoFilename); } catch (err) { await fs.rm(tempFilename, { force: true }); console.error(`⛔ Error during download: ${err}`); } } else console.error(`🛑 No videoUrl for ${jobId} media #${i + 1}:\n${prompt}\n`); } break; } console.log(`⌛ ${jobId} status (${status}) and is still in progress, waiting…`); await sleep(SLEEP_POLL); } } } catch (error) { console.log(`⛔ Error during download:`, error.stack || error); } } // Main function async function main() { const apiToken = process.argv[2]; const email = process.argv[3]; const promptFile = process.argv[4] || DEFAULT_PROMPTS_FILE; if (!apiToken || !email) { console.error('Usage: node google-flow.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE]'); process.exit(1); } console.info('Script v1.1'); console.info('Node version is: ' + process.version); try { if (await fileExists(RESULTS_FILE)) { let user_input; while (!['y', 'n'].includes(user_input)) { user_input = (await promptUser(`❔ ${RESULTS_FILE} file detected. Do you want to download the results now? (y/n): `))?.toLowerCase(); if (user_input == 'y') { await download(apiToken); await fs.unlink(RESULTS_FILE); } } } const start = new Date(); try { console.info('START EXECUTION', start); await execute(apiToken, email, promptFile); // Pass the promptFile to execute function } finally { console.info('COMPLETED', new Date()); console.info('EXECUTION ELAPSED', diffInMinutesAndSeconds(start, new Date())); } try { console.info('START DOWNLOAD', start); await download(apiToken); } finally { console.info('TOTAL ELAPSED', diffInMinutesAndSeconds(start, new Date())); } } catch (error) { console.error('⛔ Error during execution:', error.stack || error); } } // Modify the execute function to accept promptFile as a parameter async function execute(apiToken, email, promptFile) { const accounts = await fetchAccounts(apiToken); console.info(`Configured Google Flow API accounts (${Object.keys(accounts).length}):`, Object.keys(accounts).join(', ')); if (Object.keys(accounts).length <= 0) { console.error(`⛔ No configured Google Flow accounts found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (!accounts[email]) { console.error(`⛔ Account ${email} not found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (accounts[email].health && accounts[email].health !== 'OK') { console.error(`⛔ Account ${email} health is '${accounts[email].health}'. Please resolve and update the account, see https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } const promptData = await fs.readFile(promptFile, 'utf8'); const prompts = JSON.parse(promptData); console.log(`Total number of prompts to process`, prompts.length); let warnings = []; // Parameters accepted by this script for the POST /videos endpoint. // See https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos for every model's full parameter set. const supportedParams = ['model', 'prompt', 'startImage', 'endImage', 'aspectRatio', 'duration', 'count']; const invalidKeys = (prompt) => Object.keys(prompt).filter(key => !key.startsWith('__') && !supportedParams.includes(key)) for (let i = 1; i <= prompts.length; i++) { const prompt = prompts[i - 1]; const { prompt: text, startImage, endImage } = prompt; const validateImage = async (file) => { if (file) { try { await fs.access(file); } catch { warnings.push(`⚠️ Image '${file}' does not exist. Prompt ${i}`); } const ext = file.split('.').pop().toLowerCase(); if (!supportedFileExtensions.includes(ext)) warnings.push(`⚠️ Image ${file} extension ${ext} not supported. Prompt ${i}`); } }; const notSupported = invalidKeys(prompt); if (notSupported.length) warnings.push(`⚠️ Following params not supported: ${notSupported.join(',')}. Prompt ${i}`); if (!text) warnings.push(`⚠️ prompt is required. Prompt ${i}`); if (endImage && !startImage) warnings.push(`⚠️ endImage requires startImage (end-frame-only is not supported). Prompt ${i}`); await Promise.all([validateImage(startImage), validateImage(endImage)]); } if (warnings.length > 0) { warnings.forEach(warning => console.warn(warning)); console.error(`⛔ Execution stopped due to warnings.`); process.exit(1); } for (let i = 0; i < prompts.length; i++) { const prompt = prompts[i]; while (true) { const responseCode = await submitVideo(apiToken, email, prompt, i + 1); if (responseCode == 429 || responseCode == 503) await sleep(SLEEP_429); else if (responseCode == 402) { process.exit(1); } else break; } } } // Utility function to check if a file exists async function fileExists(path) { try { await fs.access(path); return true; } catch { return false; } } // Function to prompt user input async function promptUser(query) { const rl = readline.createInterface({ input: process.stdin, output: process.stdout }); return new Promise((resolve) => rl.question(query, answer => { rl.close(); resolve(answer); })); } function diffInMinutesAndSeconds(date1, date2) { const diffInSeconds = Math.floor((date2 - date1) / 1000); return `${Math.floor(diffInSeconds / 60)} minutes ${diffInSeconds % 60} seconds`; }; main(); ``` </details> ### 例 この Google Flow API で作った実際の Veo 3.1 の動画です。当社のリリースノートからそのまま転載しています。 ###### veo-3.1-fast » 海賊を追い払う勇敢なキャプテン・キャット(画像から動画) {: .no_toc #veo-31-fast--brave-captain-cat-chasing-away-the-pirates-image-to-video } 出典は [Google Flow API v1: Initial Release](/blog/251117)(英語)です。Nano Banana の静止画を `startImage` として渡し、動かしました。 <video poster="https://media.useapi.net/blog/2025-11-17-251117/veo-3-1-fast-poster.jpg" src="https://media.useapi.net/blog/2025-11-17-251117/veo-3-1-fast.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> ###### veo-3.1-fast » 女性と犬、AI 音声のナレーション付き {: .no_toc #veo-31-fast--lady-and-her-dog-with-ai-voice-narration } 出典は [Veo 3.1 Lite and Voice Narration](/blog/260403)(英語)です。参照画像から動画を作り、`referenceAudio_1: "Zephyr"` のプリセットでセリフを加えました。 <video poster="https://media.useapi.net/blog/2026-04-03-260403/veo-3-1-fast-voice-zephyr-poster.jpg" controls width="100%" style="max-width:400px"> <source src="https://media.useapi.net/blog/2026-04-03-260403/veo-3-1-fast-voice-zephyr.mp4" type="video/mp4"> </video> ###### veo-3.1-fast » チャチャを踊る(縦長、参照画像から動画) {: .no_toc #veo-31-fast--dancing-cha-cha-portrait-reference-to-video } 出典は [Veo 3.1 Portrait R2V](/blog/260113)(英語)です。参照画像1枚から縦長の R2V で作りました。 <video poster="https://media.useapi.net/blog/2026-01-13-260113/dancing-cha-cha-poster.jpg" src="https://media.useapi.net/blog/2026-01-13-260113/dancing-cha-cha.mp4" style="width: 100%; max-width: 400px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> ### よくある質問 - **Veo 3.1 の API はありますか?** useapi.net を使えば、あります。[Google Flow API](/docs/api-google-flow-v1) は、お使いの Google Flow の Web サイトのプラン(Google AI Pro または Ultra)で、Veo 3.1 Quality、Fast、Lite を REST で動かします。8秒の Veo 3.1 Quality の動画は Google AI Ultra $199.99 で $0.80 で、公式の Veo API では $3.20 です(2026年11月時点)。 - **Veo 3.1 の Quality、Fast、Lite の違いは?** useapi.net を使えば、リクエストごとに `model` フィールドで1つを選べます。`veo-3.1-quality` は最も高い品質、`veo-3.1-fast` は速度と品質のバランスを取ったデフォルト、`veo-3.1-lite` は最も安く、Google AI Ultra $199.99 で1本 $0.04、公式の Veo API では $0.40 です。このプランでは `veo-3.1-lite-low-priority` が $0 で、1日約1,000本以上作れます(2026年11月時点)。 - **Veo で画像から動画を作れますか?** useapi.net を使えば、作れます。[POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email) で開始フレームをアップロードし、返ってきた参照 ID(`mediaGenerationId.mediaGenerationId` に入れ子)を `startImage` として渡します。最後のフレームを固定するなら `endImage` も渡します(`startImage` が必要です)。フレームではなく被写体やスタイルを指定したい場合は、`referenceImage_N` を最大3枚渡します(2026年11月時点)。上の[画像から動画](#image-to-video-and-reference-to-video)を参照してください。 - **CAPTCHA を解く必要はありますか?** useapi.net を使えば、ご自身で解く必要はありません。Google Flow は動画ごとに reCAPTCHA を求めますが、useapi.net のワーカーが自動で解決します。最初の Google Flow アカウントには、当社の AntiCaptcha、CapSolver、EzCaptcha のキーで300回の無料解決が付き、その後は [POST /accounts/captcha-providers](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers) でご自身のプロバイダーのキーを追加します(2026年11月時点)。このガイドのスクリプトは `captchaToken` を送りません。 - **Veo 3.1 の API キーは必要ですか?** useapi.net を使えば、Google の API キーも Google Cloud プロジェクトも不要です。useapi.net の [API トークン](/docs/start-here/setup-useapi)1つで Veo 3.1 を呼び出せ、Google アカウントは[自動セットアップ](/docs/start-here/setup-google-flow)で一度接続するだけです。Google Flow 自体には公開 API がなく、2026年10月22日に Gemini API の Veo 3.1 Preview モデルが終了したため、Google 自身の Veo API には課金を有効にした Cloud プロジェクトが必要です。 ### おわりに ご質問は <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord サーバー</a> または <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram チャンネル</a>へどうぞ。 コード例は [GitHub リポジトリ](https://github.com/useapi/google-flow-api)にあります。 #### ほかの掲載先 {: .no_toc #cross-posted } この記事(英語版)は [dev.to](https://dev.to/useapi/how-to-generate-ai-video-with-veo-31-via-the-google-flow-api-2g4i){:rel="nofollow"} にも掲載しています。 ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-flow-bash-pt === Document URL: https://useapi.net/docs/articles/google-flow-bash-pt --- layout: default title: "Como usar a API do Veo 3.1: gerar vídeo com curl pela Google Flow API" seo_title: "API do Veo 3.1 com curl: Google Flow API, sem chave de API" description: "API do Veo 3.1 com curl (Fast, Quality, Lite) pela Google Flow API da useapi.net no Google AI Pro ou Ultra: sem projeto no Google Cloud, sem chave de API." keywords: [Veo 3.1 API, API do Veo 3.1, Veo 3.1 API key, chave da API Veo 3.1, Veo API, Google Veo API, API do Google Veo, Veo 3 API, Google Flow API, API do Google Flow, Veo 3.1 Fast, Veo 3.1 Lite, Gemini API Veo shutdown, geração de vídeo com IA, texto para vídeo, imagem para vídeo, tutorial Veo 3.1, código, curl] parent: Articles nav_exclude: true lang: pt-BR date: 2026-06-15 last_modified: 2026-11-10 nav_order: 810 repo: https://github.com/useapi/google-flow-api translation_key: google-flow --- ## Como usar a API do Veo 3.1: gerar vídeo com curl pela Google Flow API {: .no_toc #how-to-use-the-veo-31-api-generate-video-with-curl-via-the-google-flow-api } 6 min de leitura • 15 de junho de 2026 (6 de novembro de 2026) A useapi.net é uma API de terceiros. Não tem afiliação com o Google nem é endossada por ele. ## Sumário {: .no_toc .text-delta #table-of-contents } ### Introdução O [Veo 3.1](https://deepmind.google/technologies/veo/) roda com um único `curl` pela [Google Flow API](/docs/api-google-flow-v1) da useapi.net, na sua assinatura do site [Google Flow](https://flow.google.com) ([Google AI Pro ou Ultra](https://gemini.google/subscriptions/)). Um vídeo Veo 3.1 Fast de 8 segundos custa $0,08 no Google AI Ultra $199,99, contra $0,80 na API oficial do Veo (em novembro de 2026). O Google desligou os modelos Veo 3.1 Preview na Gemini API em 22 de outubro de 2026 e levou os desenvolvedores para a [Agent Platform](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing) do Cloud, que cobra os mesmos preços por segundo em um projeto Google Cloud. Esta API de terceiros não precisa de projeto no Cloud, nem de chave de API do Google, nem de aprovação enterprise. A seguir: os modelos, o fluxo em duas chamadas, entradas de imagem e um script de lote pronto para rodar. ### Modelos suportados Escolha o modelo em cada requisição com o campo `model` (padrão `veo-3.1-fast`). Os custos em créditos do Veo vêm da [tabela oficial de créditos do Flow](https://support.google.com/flow/answer/16526234?hl=pt-BR) do Google, e os do Omni foram medidos na API ao vivo: | Id do modelo | Nível / velocidade | Durações | Créditos por vídeo | |----------|--------------|-----------|------------------------| | `veo-3.1-lite` | Veo mais barato | 4s, 6s, 8s | 10 (fora do Ultra) · 5 (Ultra) | | `veo-3.1-lite-low-priority` | Lite, prioridade baixa | 4s, 6s, 8s | 0, só o titular do Ultra $199,99 | | `veo-3.1-fast` *(padrão)* | Veo rápido | 4s, 6s, 8s | 20 (fora do Ultra) · 10 (Ultra) | | `veo-3.1-quality` | Veo de mais qualidade | só 8s | 100 | | `omni-flash-1.2` | Omni 1.2 Flash, áudio nativo | 3s a 15s | 3 por segundo até 10s, 6 por segundo acima (em 720p) | | `omni-flash` | Omni 1.1 Flash, áudio nativo | 4s, 6s, 8s, 10s | 7 / 10 / 12 / 15 (pela duração, em 720p) | No Veo, vídeos de `4s` e `6s` exigem o Ultra (veja a [visão geral](/docs/api-google-flow-v1)). O Google Flow também gera imagens com os modelos Nano Banana pelo endpoint separado [POST /images](/docs/api-google-flow-v1/post-google-flow-images). ### Preços Cada vídeo gasta créditos do Flow da sua assinatura do Google AI, e a useapi.net não cobra nada por vídeo. O preço por vídeo em cada plano, comparado com a API oficial, está na [tabela de preços do Google Flow](/docs/api-google-flow-v1#pricing), e o artigo [Veo 3.1 API pricing](/docs/articles/veo-3-1-api-pricing) (em inglês) cobre o Veo em detalhe. ### Gere um vídeo em duas chamadas de API Você precisa de um [token da API](/docs/start-here/setup-useapi) da useapi.net e de uma [conta Google Flow](/docs/start-here/setup-google-flow) conectada. Jobs de vídeo são assíncronos: passe `async: true` e a chamada de criação devolve um `jobid` na hora, depois você consulta até o vídeo ficar pronto. 1. Envie o job — `POST https://api.useapi.net/v1/google-flow/videos`: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A serene mountain landscape at sunset, camera slowly panning right", "model": "veo-3.1-fast", "aspectRatio": "landscape", "duration": 8, "async": true }' ``` No modo assíncrono, a resposta volta na hora com `201 Created`, um `jobid` em minúsculas e `status: "created"`: ```json { "jobid": "j1731859234567v-u12345-email:jo***@gmail.com-bot:google-flow", "type": "video", "status": "created", "created": "2026-06-15T12:34:56.789Z", "request": { "async": true, "prompt": "A serene mountain landscape at sunset, camera slowly panning right", "model": "veo-3.1-fast", "aspectRatio": "landscape", "duration": 8 } } ``` 2. Consulte o resultado — `GET https://api.useapi.net/v1/google-flow/jobs/{jobId}`: ```bash curl "https://api.useapi.net/v1/google-flow/jobs/{jobId}" \ -H "Authorization: Bearer $USEAPI_TOKEN" ``` O `status` passa por `created` → `started` → `completed`. Quando chega a `completed`, o MP4 pronto está em `response.media[].videoUrl` (um único prompt com `count > 1` devolve uma entrada por vídeo): ```json { "jobid": "j1731859234567v-...", "type": "video", "status": "completed", "response": { "media": [ { "mediaGenerationId": "user:12345-email:6a6f...-video:a1d95d21-...", "videoUrl": "https://flow-content.google/video/a1d95d21-...?Expires=...", "thumbnailUrl": "https://flow-content.google/image/a1d95d21-...?Expires=..." } ], "remainingCredits": 18760 } } ``` O Veo 3.1 costuma terminar em 60 a 180 segundos, conforme o modelo e o modo. Nos nossos testes de 20 de outubro de 2026, nove vídeos de 8 segundos levaram de 50 a 105 segundos do envio até o MP4 pronto ([execuções medidas](/docs/articles/veo-3-1-api-pricing#examples)). O `videoUrl` assinado vale por cerca de 6 horas, então baixe logo. Prefere não consultar? Passe um `replyUrl` no corpo da criação para receber um callback por webhook quando o job terminar. ### Imagem para vídeo e referência para vídeo O Veo aceita imagens de entrada de dois jeitos diferentes. Envie antes cada imagem com [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email) (bytes brutos, um `Content-Type` de imagem, PNG/JPEG/WebP de até 20 MB). A resposta do upload traz o id aninhado em `mediaGenerationId.mediaGenerationId` — é essa string aninhada que você passa de volta. Quando você manda qualquer imagem de entrada, pode omitir o `email`: a requisição vai para a conta em que a imagem foi enviada. #### Primeiro / último quadro (I2V) A sua imagem vira um quadro literal do vídeo. Passe a imagem como `startImage` para começar a partir desse quadro: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Brave Captain Cat chasing away the pirates!", "model": "veo-3.1-fast", "aspectRatio": "portrait", "startImage": "user:12345-email:6a6f...-image:ff9aa5cc-...", "async": true }' ``` Acrescente `endImage` (um segundo id de referência enviado) para fixar o último quadro, e o Veo gera a transição entre os dois. `endImage` exige `startImage` — só o quadro final não é suportado. Os modelos Omni (`omni-flash-1.2`, `omni-flash`) aceitam o mesmo par, mas ali os dois quadros são a única entrada aceita — nada de `referenceImage_*`, `character_*` ou `referenceAudio_*` junto com eles. #### Imagens de referência (R2V) As suas imagens guiam o vídeo inteiro — tema, personagem ou estilo — em vez de um quadro específico. Passe de `referenceImage_1` a `referenceImage_3` (o Veo aceita até 3, só em vídeos de 8 segundos, e não no `veo-3.1-quality`). R2V não pode ser combinado com `startImage`/`endImage`: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A lady says to the dog, \"Say meow meow meow.\" The dog looks at the lady with a surprised, frustrated look and woofs in a human voice, \"What the heck lady?!\"", "model": "veo-3.1-fast", "aspectRatio": "portrait", "referenceImage_1": "user:12345-email:6a6f...-image:abcde-...", "async": true }' ``` Mencione cada referência inline com um marcador `@referenceImage_N` no prompt, acrescente um `referenceAudio_1` (o nome de uma voz do sistema, como `Zephyr`) para narração, ou passe um [personagem](/docs/api-google-flow-v1/post-google-flow-characters) reutilizável como `character_1` (ele usa o mesmo modo R2V e conta no limite de 3 referências). O Omni 1.2 Flash vai além com as referências — até 10, mais edição de vídeo para vídeo e vozes sincronizadas — veja o [tutorial do Omni Flash](/docs/articles/omni-flash-bash-pt). ### Gere em lote com um script Achar a tomada certa leva muitas tentativas, e rodar tudo à mão é cansativo. O script Node.js abaixo lê uma lista de prompts de `prompts.json`, envia as imagens de quadro inicial/final, manda cada job no modo assíncrono, depois consulta e baixa cada MP4 pronto — assim você enfileira um lote e volta para pegar os melhores. Você precisa do [Node.js](https://nodejs.org) v21 ou mais novo. Coloque `prompts.json` e `google-flow.mjs` na mesma pasta e rode `node ./google-flow.mjs API_TOKEN EMAIL`, em que `API_TOKEN` é o seu [token da API](/docs/start-here/setup-useapi) da useapi.net e `EMAIL` é o e-mail da sua [conta Google Flow](/docs/start-here/setup-google-flow) conectada. O script busca a conta pelo e-mail automaticamente e confere o campo `health` dela antes de enviar. Prefere clonar e rodar localmente? O `google-flow.mjs` e o `prompts.json` completos estão no GitHub em [`useapi/google-flow-api`](https://github.com/useapi/google-flow-api/tree/main/veo-video). <details markdown="block"> <summary>Abrir `prompts.json`</summary> ```json [ { "prompt": "By default the veo-3.1-fast model with a landscape 8-second clip will be used." }, { "model": "veo-3.1-quality", "aspectRatio": "landscape", "duration": 8, "count": 2, "prompt": "Highest-quality Veo 3.1, two variations. For all parameters see https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos" }, { "model": "veo-3.1-fast", "aspectRatio": "portrait", "duration": 8, "startImage": "./first_image.jpeg", "endImage": "./last_image.jpeg", "prompt": "Image-to-video with a start frame (startImage) and an end frame (endImage). Supported by Veo and by both Omni models." }, { "model": "omni-flash", "duration": 10, "prompt": "Gemini Omni Flash is audio-native and supports 10-second clips. Other models (veo-3.1-lite, veo-3.1-lite-low-priority, …) are selectable via the model field — see the POST /videos docs." } ] ``` </details> <details markdown="block"> <summary>Abrir o script `google-flow.mjs`</summary> ```javascript /* Script version 1.1, September 11, 2026 Script to batch-generate videos using prompts with the Google Flow API v1 by useapi.net 🚀 Uses the POST /videos endpoint in async mode (default model: veo-3.1-fast) and polls GET /jobs/{jobId}. For more details visit https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos Installation Instructions: ========================== You need Node.js v21 or newer installed to run this script. Download and install Node.js from: - Windows, macOS, Linux: https://nodejs.org/ After installation, verify by running the following command in a terminal: node -v Running the Script: =================== Usage: node google-flow.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE] Replace API_TOKEN with your actual useapi.net API token, see https://useapi.net/docs/start-here/setup-useapi Replace EMAIL with configured Google Flow email account, see https://useapi.net/docs/start-here/setup-google-flow If optional PROMPTS_FILE not provided prompts.json will be used. Example: -------- node google-flow.mjs user:1234-abcdefhijklmnopqrstuv my@email.com This command executes the script using API token user:1234-abcdefhijklmnopqrstuv with my@email.com Google Flow account email. Changelog: ========== - June 15, 2026: Initial release. - September 11, 2026: Accepts .jpg and upper-case image extensions for startImage and endImage. A prompt whose startImage or endImage fails to upload is skipped and logged to google-flow_errors.txt instead of being submitted without that frame. Saves a downloaded video under its final name only once it has been fully received, so a failed download leaves no partial MP4 for the next run to skip as "already exists". */ import readline from 'node:readline'; import fs from 'fs/promises'; import path from 'path'; import { writeFile } from 'node:fs/promises'; import { Readable } from 'node:stream'; // Constants const RESULTS_FILE = 'google-flow_results.txt'; const ERRORS_FILE = 'google-flow_errors.txt'; const DEFAULT_PROMPTS_FILE = 'prompts.json'; const DEFAULT_MODEL = 'veo-3.1-fast'; const SLEEP_429 = 30 * 1000; // in milliseconds const SLEEP_POLL = 15 * 1000; // in milliseconds const urlAccounts = 'https://api.useapi.net/v1/google-flow/accounts'; const urlVideos = 'https://api.useapi.net/v1/google-flow/videos'; const urlJobs = 'https://api.useapi.net/v1/google-flow/jobs/'; const urlUploadAsset = 'https://api.useapi.net/v1/google-flow/assets/'; // To upload .webp keep its .webp extension — Google Flow accepts png, jpeg and webp. const supportedFileExtensions = ['png', 'jpg', 'jpeg', 'webp']; // { filename: mediaGenerationId } const uploadedFiles = {}; // Utility to sleep for given milliseconds const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); // Function to fetch configured Google Flow API accounts async function fetchAccounts(apiToken) { const response = await fetch(urlAccounts, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.error(`⛔ Error fetching accounts (HTTP ${response.status}): ${response.statusText}`); process.exit(1); } return response.json(); } const elapsedTimeSec = (start) => (Date.now() - start) / 1000; // Map a file extension to the Content-Type required by POST /assets const contentTypeForExt = (ext) => ext === 'png' ? 'image/png' : ext === 'webp' ? 'image/webp' : 'image/jpeg'; async function uploadAsset(apiToken, email, filename) { // Check if already uploaded if (uploadedFiles.hasOwnProperty(filename)) return uploadedFiles[filename]; const startTime = Date.now(); console.log(`⬆️ Account ${email} uploading file…`, filename); const body = new Blob([await fs.readFile(filename)]); const fileExt = filename.split('.').pop().toLowerCase(); const response = await fetch(`${urlUploadAsset}${encodeURIComponent(email)}`, { method: 'POST', headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}`, 'Content-Type': contentTypeForExt(fileExt) }, body }); if (response.ok) { const json = await response.json(); // POST /assets returns the reference id nested as mediaGenerationId.mediaGenerationId const mediaGenerationId = json?.mediaGenerationId?.mediaGenerationId; console.log(`🆗 mediaGenerationId (${elapsedTimeSec(startTime)} sec)`, mediaGenerationId); uploadedFiles[filename] = mediaGenerationId; } else { console.error(`❗ Unable to upload file HTTP ${response.status} (${elapsedTimeSec(startTime)} sec)`, await response.text()); // Do not attempt to upload failed file again uploadedFiles[filename] = undefined; } return uploadedFiles[filename]; } async function submit(apiToken, url, body, index, prompt) { const createResponse = await fetch(url, { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiToken}` }, body }); const createBody = await createResponse.text(); // Async POST /videos returns 201 Created with a jobid to poll. if (createResponse.status == 201) { const json = JSON.parse(createBody); // 201 async payload uses lowercase "jobid"; sync 200 uses "jobId". Accept either. const jobId = json.jobid ?? json.jobId; if (jobId) { await fs.appendFile(RESULTS_FILE, `${jobId},#${index}:${prompt}\n`); console.log(`✅ jobId`, jobId); return 201; } else { const error = `No jobid found in HTTP 201 response`; console.log(`❓ ${error}`, createBody); await fs.appendFile(ERRORS_FILE, `${error},#${index}:${prompt}\n`); return 500; } } else { switch (createResponse.status) { case 429: console.log(`🔄️ Retry on HTTP ${createResponse.status}`, createBody); break; case 503: console.log(`🔄️ Service unavailable, retry on HTTP ${createResponse.status}`, createBody); break; case 400: console.log(`🛑 Rejected request (validation or content policy)`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${prompt}\n`); break; case 402: console.log(`🛑 No subscription / insufficient credits`, createBody); break; default: console.log(`❗ FAILED with HTTP ${createResponse.status}`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${prompt}\n`); } return createResponse.status; } } // Submit a single prompt to POST /videos in async mode. // startImage = start frame (I2V), endImage = end frame (I2V-FL, requires startImage). async function submitVideo(apiToken, email, prompt, index) { const { model, prompt: text, startImage, endImage, aspectRatio, duration, count } = prompt; const useModel = model ?? DEFAULT_MODEL; console.log(`🚀 ${useModel} » Prompt #${index} • account ${email} …`); const startImageId = startImage ? await uploadAsset(apiToken, email, startImage) : undefined; const endImageId = endImage ? await uploadAsset(apiToken, email, endImage) : undefined; // A frame that failed to upload would be left out of the body, and the prompt would still be // generated (and charged) without it. Skip the prompt instead. uploadAsset remembers the failed file, // so a later prompt using it is skipped too, without another upload attempt. const failedUploads = [['startImage', startImage, startImageId], ['endImage', endImage, endImageId]] .filter(([, file, id]) => file && !id); for (const [param, file] of failedUploads) { console.error(`🛑 Prompt #${index} skipped: ${param} ${file} failed to upload`); await fs.appendFile(ERRORS_FILE, `Upload failed for ${param} ${file},#${index}:${text}\n`); } if (failedUploads.length) return; const body = JSON.stringify({ model: useModel, email, prompt: text, aspectRatio, duration, count, startImage: startImageId, endImage: endImageId, async: true }); return await submit(apiToken, urlVideos, body, index, text); } // Function to download videos async function download(apiToken) { if (! await fileExists(RESULTS_FILE)) return; try { const resultsContent = await fs.readFile(RESULTS_FILE, 'utf8'); const lines = resultsContent.trim().split('\n'); for (const line of lines) { const [jobId, prompt] = line.split(','); console.log(`👉 ${jobId}`); while (true) { const response = await fetch(`${urlJobs}${jobId}`, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.log(`🛑 Poll failed ${jobId} (HTTP ${response.status}):\n${prompt}\n`, await response.text()); break; } const jobBody = await response.json(); const { status, error, response: jobResponse } = jobBody; if (status == 'failed') { console.error(`🛑 FAILED ${jobId} (${error}):\n${prompt}\n`); break; } if (status == 'completed') { const media = jobResponse?.media ?? []; if (media.length == 0) console.error(`🛑 Completed but no media for ${jobId}:\n${prompt}\n`); // A single prompt with count > 1 returns multiple videos. for (let i = 0; i < media.length; i++) { const url = media[i]?.videoUrl; const videoFilename = `${jobId.replace(/[:*]/g, '_')}_${i + 1}.mp4`; try { await fs.access(videoFilename); console.log(`⚠️ ${videoFilename} already exists. Skipping download.`); continue; } catch { // File does not exist, proceed with downloading } if (url) { console.log(`✅ Downloading ${url} to ${videoFilename}`); // Stream into a temporary file and rename it once the whole video has arrived, so a download // that drops mid-stream leaves no partial file behind for the next run to skip as "already exists". const tempFilename = `${videoFilename}.part`; try { const videoResponse = await fetch(url); if (!videoResponse.ok) { console.error(`⛔ Unable to download ${jobId} (HTTP ${videoResponse.status}):\n${prompt}\n`, url); continue; } const stream = Readable.fromWeb(videoResponse.body); await writeFile(tempFilename, stream); await fs.rename(tempFilename, videoFilename); } catch (err) { await fs.rm(tempFilename, { force: true }); console.error(`⛔ Error during download: ${err}`); } } else console.error(`🛑 No videoUrl for ${jobId} media #${i + 1}:\n${prompt}\n`); } break; } console.log(`⌛ ${jobId} status (${status}) and is still in progress, waiting…`); await sleep(SLEEP_POLL); } } } catch (error) { console.log(`⛔ Error during download:`, error.stack || error); } } // Main function async function main() { const apiToken = process.argv[2]; const email = process.argv[3]; const promptFile = process.argv[4] || DEFAULT_PROMPTS_FILE; if (!apiToken || !email) { console.error('Usage: node google-flow.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE]'); process.exit(1); } console.info('Script v1.1'); console.info('Node version is: ' + process.version); try { if (await fileExists(RESULTS_FILE)) { let user_input; while (!['y', 'n'].includes(user_input)) { user_input = (await promptUser(`❔ ${RESULTS_FILE} file detected. Do you want to download the results now? (y/n): `))?.toLowerCase(); if (user_input == 'y') { await download(apiToken); await fs.unlink(RESULTS_FILE); } } } const start = new Date(); try { console.info('START EXECUTION', start); await execute(apiToken, email, promptFile); // Pass the promptFile to execute function } finally { console.info('COMPLETED', new Date()); console.info('EXECUTION ELAPSED', diffInMinutesAndSeconds(start, new Date())); } try { console.info('START DOWNLOAD', start); await download(apiToken); } finally { console.info('TOTAL ELAPSED', diffInMinutesAndSeconds(start, new Date())); } } catch (error) { console.error('⛔ Error during execution:', error.stack || error); } } // Modify the execute function to accept promptFile as a parameter async function execute(apiToken, email, promptFile) { const accounts = await fetchAccounts(apiToken); console.info(`Configured Google Flow API accounts (${Object.keys(accounts).length}):`, Object.keys(accounts).join(', ')); if (Object.keys(accounts).length <= 0) { console.error(`⛔ No configured Google Flow accounts found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (!accounts[email]) { console.error(`⛔ Account ${email} not found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (accounts[email].health && accounts[email].health !== 'OK') { console.error(`⛔ Account ${email} health is '${accounts[email].health}'. Please resolve and update the account, see https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } const promptData = await fs.readFile(promptFile, 'utf8'); const prompts = JSON.parse(promptData); console.log(`Total number of prompts to process`, prompts.length); let warnings = []; // Parameters accepted by this script for the POST /videos endpoint. // See https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos for every model's full parameter set. const supportedParams = ['model', 'prompt', 'startImage', 'endImage', 'aspectRatio', 'duration', 'count']; const invalidKeys = (prompt) => Object.keys(prompt).filter(key => !key.startsWith('__') && !supportedParams.includes(key)) for (let i = 1; i <= prompts.length; i++) { const prompt = prompts[i - 1]; const { prompt: text, startImage, endImage } = prompt; const validateImage = async (file) => { if (file) { try { await fs.access(file); } catch { warnings.push(`⚠️ Image '${file}' does not exist. Prompt ${i}`); } const ext = file.split('.').pop().toLowerCase(); if (!supportedFileExtensions.includes(ext)) warnings.push(`⚠️ Image ${file} extension ${ext} not supported. Prompt ${i}`); } }; const notSupported = invalidKeys(prompt); if (notSupported.length) warnings.push(`⚠️ Following params not supported: ${notSupported.join(',')}. Prompt ${i}`); if (!text) warnings.push(`⚠️ prompt is required. Prompt ${i}`); if (endImage && !startImage) warnings.push(`⚠️ endImage requires startImage (end-frame-only is not supported). Prompt ${i}`); await Promise.all([validateImage(startImage), validateImage(endImage)]); } if (warnings.length > 0) { warnings.forEach(warning => console.warn(warning)); console.error(`⛔ Execution stopped due to warnings.`); process.exit(1); } for (let i = 0; i < prompts.length; i++) { const prompt = prompts[i]; while (true) { const responseCode = await submitVideo(apiToken, email, prompt, i + 1); if (responseCode == 429 || responseCode == 503) await sleep(SLEEP_429); else if (responseCode == 402) { process.exit(1); } else break; } } } // Utility function to check if a file exists async function fileExists(path) { try { await fs.access(path); return true; } catch { return false; } } // Function to prompt user input async function promptUser(query) { const rl = readline.createInterface({ input: process.stdin, output: process.stdout }); return new Promise((resolve) => rl.question(query, answer => { rl.close(); resolve(answer); })); } function diffInMinutesAndSeconds(date1, date2) { const diffInSeconds = Math.floor((date2 - date1) / 1000); return `${Math.floor(diffInSeconds / 60)} minutes ${diffInSeconds % 60} seconds`; }; main(); ``` </details> ### Exemplos Vídeos Veo 3.1 reais feitos por esta Google Flow API, tirados direto das nossas notas de lançamento. ###### veo-3.1-fast » Capitão Gato corajoso espantando os piratas (imagem para vídeo) {: .no_toc #veo-31-fast--brave-captain-cat-chasing-away-the-pirates-image-to-video } De [Google Flow API v1: Initial Release](/blog/251117) (em inglês). Animado a partir de uma imagem Nano Banana passada como `startImage`. <video poster="https://media.useapi.net/blog/2025-11-17-251117/veo-3-1-fast-poster.jpg" src="https://media.useapi.net/blog/2025-11-17-251117/veo-3-1-fast.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> ###### veo-3.1-fast » Uma mulher e o seu cachorro, com narração por voz de IA {: .no_toc #veo-31-fast--lady-and-her-dog-with-ai-voice-narration } De [Veo 3.1 Lite and Voice Narration](/blog/260403) (em inglês). Referência para vídeo com o preset `referenceAudio_1: "Zephyr"` acrescentando diálogo falado. <video poster="https://media.useapi.net/blog/2026-04-03-260403/veo-3-1-fast-voice-zephyr-poster.jpg" controls width="100%" style="max-width:400px"> <source src="https://media.useapi.net/blog/2026-04-03-260403/veo-3-1-fast-voice-zephyr.mp4" type="video/mp4"> </video> ###### veo-3.1-fast » Dançando chá-chá-chá (referência para vídeo em retrato) {: .no_toc #veo-31-fast--dancing-cha-cha-portrait-reference-to-video } De [Veo 3.1 Portrait R2V](/blog/260113) (em inglês). R2V em retrato a partir de uma única imagem de referência. <video poster="https://media.useapi.net/blog/2026-01-13-260113/dancing-cha-cha-poster.jpg" src="https://media.useapi.net/blog/2026-01-13-260113/dancing-cha-cha.mp4" style="width: 100%; max-width: 400px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> ### Perguntas frequentes - **Existe API do Veo 3.1?** Com a useapi.net, sim: a [Google Flow API](/docs/api-google-flow-v1) roda o Veo 3.1 Quality, Fast e Lite por REST na sua assinatura do site Google Flow (Google AI Pro ou Ultra). Um vídeo Veo 3.1 Quality de 8 segundos custa $0,80 no Google AI Ultra $199,99, contra $3,20 na API oficial do Veo (em novembro de 2026). - **Qual a diferença entre Veo 3.1 Quality, Fast e Lite?** Com a useapi.net você escolhe um por requisição com o campo `model`. O `veo-3.1-quality` dá a maior fidelidade, o `veo-3.1-fast` é o equilíbrio padrão entre velocidade e qualidade, e o `veo-3.1-lite` é o mais barato: $0,04 por vídeo no Google AI Ultra $199,99, contra $0,40 na API oficial do Veo. Nesse plano, o `veo-3.1-lite-low-priority` custa $0, cerca de 1.000 vídeos ou mais por dia (em novembro de 2026). - **Dá para fazer imagem para vídeo com o Veo?** Com a useapi.net, sim. Envie o quadro inicial com [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email), depois passe o id de referência devolvido (aninhado em `mediaGenerationId.mediaGenerationId`) como `startImage` e, se quiser, `endImage` para fixar o último quadro (ele exige `startImage`). Para guiar o tema ou o estilo em vez de um quadro, passe até três `referenceImage_N`. Veja [Imagem para vídeo](#image-to-video-and-reference-to-video) acima. - **Preciso resolver captcha?** Com a useapi.net você nunca resolve um captcha. O Google Flow pede um reCAPTCHA em cada vídeo, e o worker da useapi.net resolve automaticamente: a sua primeira conta Google Flow vem com 300 resoluções grátis nas nossas próprias chaves de AntiCaptcha, CapSolver e EzCaptcha, e depois disso você acrescenta as chaves do seu próprio provedor com [POST /accounts/captcha-providers](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers). O script deste guia não envia `captchaToken`. - **Preciso de uma chave da API do Veo 3.1?** Com a useapi.net você não precisa de chave de API do Google nem de projeto no Google Cloud: um único [token da API](/docs/start-here/setup-useapi) da useapi.net chama o Veo 3.1, e você conecta a sua conta Google uma vez pela [configuração automática](/docs/start-here/setup-google-flow). O Google Flow em si não tem API pública, e desde que os modelos Veo 3.1 Preview da Gemini API foram desligados em 22 de outubro de 2026, a API do Veo do próprio Google exige um projeto no Cloud com faturamento. ### Conclusão Visite o nosso <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> servidor no Discord</a> ou o <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> canal no Telegram</a> para qualquer dúvida de suporte. Veja o nosso [repositório no GitHub](https://github.com/useapi/google-flow-api) com exemplos de código. #### Publicado também em {: .no_toc #cross-posted } Também publicado no [dev.to](https://dev.to/useapi/how-to-generate-ai-video-with-veo-31-via-the-google-flow-api-2g4i){:rel="nofollow"} (em inglês). ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-flow-bash-th === Document URL: https://useapi.net/docs/articles/google-flow-bash-th --- layout: default title: "วิธีใช้ Veo 3.1 API: สร้างวิดีโอด้วย curl ผ่าน Google Flow API" description: "ใช้ Veo 3.1 API (Fast, Quality, Lite) ด้วย curl ผ่าน Google Flow API ของ useapi.net บน Google AI Pro หรือ Ultra ไม่ต้องมีโปรเจกต์ Google Cloud ไม่ต้องมี API key" keywords: [Veo 3.1 API, Veo 3.1 API key, Veo API, Google Veo API, Veo 3 API, Google Flow API, Veo 3.1 Fast, Veo 3.1 Lite, Veo 3.1 API ราคา, Veo 3.1 API ภาษาไทย, ใช้ Veo 3.1 ผ่าน API, API สร้างวิดีโอ, สร้างวิดีโอ AI ด้วย API, ข้อความเป็นวิดีโอ, ภาพเป็นวิดีโอ, Gemini API Veo shutdown, curl, ตัวอย่างโค้ด, คู่มือ] parent: Articles nav_exclude: true lang: th translation_key: google-flow date: 2026-06-15 last_modified: 2026-11-10 nav_order: 810 repo: https://github.com/useapi/google-flow-api --- ## วิธีใช้ Veo 3.1 API: สร้างวิดีโอด้วย curl ผ่าน Google Flow API {: .no_toc #how-to-use-the-veo-31-api-generate-video-with-curl-via-the-google-flow-api } อ่าน 6 นาที • 15 มิถุนายน 2026 (6 พฤศจิกายน 2026) useapi.net เป็น API ของบุคคลที่สาม (third-party) ไม่มีส่วนเกี่ยวข้องกับ Google และไม่ได้รับการรับรองจาก Google ## สารบัญ {: .no_toc .text-delta #table-of-contents } ### บทนำ [Veo 3.1](https://deepmind.google/technologies/veo/) ทำงานได้ด้วย `curl` คำสั่งเดียวผ่าน [Google Flow API](/docs/api-google-flow-v1) ของ useapi.net บนแพ็กเกจเว็บไซต์ [Google Flow](https://flow.google.com) ของคุณ ([Google AI Pro หรือ Ultra](https://gemini.google/subscriptions/)) วิดีโอ Veo 3.1 Fast ยาว 8 วินาทีราคา $0.08 บน Google AI Ultra $199.99 เทียบกับ $0.80 บน Veo API ทางการ (ข้อมูล ณ พฤศจิกายน 2026) Google ปิดโมเดล Veo 3.1 Preview บน Gemini API เมื่อ 22 ตุลาคม 2026 และย้ายนักพัฒนาไปที่ [Agent Platform](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing) บน Cloud ซึ่งคิดราคาต่อวินาทีเท่าเดิมบนโปรเจกต์ Google Cloud API ของบุคคลที่สามนี้ไม่ต้องมีโปรเจกต์ Cloud ไม่ต้องมี Google API key และไม่ต้องรอการอนุมัติแบบองค์กร ด้านล่างนี้มีรายชื่อโมเดล ขั้นตอนเรียก API สองครั้ง การใส่ภาพ และสคริปต์สร้างวิดีโอเป็นชุดที่รันได้ทันที ### โมเดลที่รองรับ เลือกโมเดลในแต่ละคำขอด้วยฟิลด์ `model` (ค่าเริ่มต้น `veo-3.1-fast`) เครดิตของ Veo มาจาก[ตารางเครดิต Flow ทางการ](https://support.google.com/flow/answer/16526234?hl=th)ของ Google ส่วนของ Omni วัดจาก API จริง: | Model id | ระดับ / ความเร็ว | ความยาว | เครดิตต่อวิดีโอ | |----------|--------------|-----------|------------------------| | `veo-3.1-lite` | Veo ที่ถูกที่สุด | 4s, 6s, 8s | 10 (ไม่ใช่ Ultra) · 5 (Ultra) | | `veo-3.1-lite-low-priority` | Lite ลำดับรอง | 4s, 6s, 8s | 0 เฉพาะเจ้าของแพ็กเกจ Ultra $199.99 | | `veo-3.1-fast` *(ค่าเริ่มต้น)* | Veo แบบเร็ว | 4s, 6s, 8s | 20 (ไม่ใช่ Ultra) · 10 (Ultra) | | `veo-3.1-quality` | Veo คุณภาพสูงสุด | 8s เท่านั้น | 100 | | `omni-flash-1.2` | Omni 1.2 Flash มีเสียงในตัว | 3s ถึง 15s | 3 ต่อวินาทีถึง 10s, 6 ต่อวินาทีเมื่อเกิน (ที่ 720p) | | `omni-flash` | Omni 1.1 Flash มีเสียงในตัว | 4s, 6s, 8s, 10s | 7 / 10 / 12 / 15 (ตามความยาว ที่ 720p) | บน Veo วิดีโอ `4s` และ `6s` ต้องใช้ Ultra (ดู[ภาพรวม](/docs/api-google-flow-v1)) Google Flow ยังสร้างภาพนิ่งด้วยโมเดล Nano Banana ผ่าน endpoint [POST /images](/docs/api-google-flow-v1/post-google-flow-images) ที่แยกต่างหาก ### ราคา วิดีโอแต่ละคลิปใช้เครดิต Flow จากแพ็กเกจ Google AI ของคุณ และ useapi.net ไม่คิดเงินต่อวิดีโอ ราคาต่อวิดีโอบนทุกแพ็กเกจเทียบกับ API ทางการอยู่ใน[ตารางราคา Google Flow](/docs/api-google-flow-v1#pricing) และบทความ[ราคา Veo 3.1 API](/docs/articles/veo-3-1-api-pricing) อธิบายราคา Veo อย่างละเอียด ### สร้างวิดีโอด้วยการเรียก API สองครั้ง คุณต้องมี [API token](/docs/start-here/setup-useapi) ของ useapi.net และ[บัญชี Google Flow](/docs/start-here/setup-google-flow)ที่เชื่อมไว้แล้ว งานวิดีโอเป็นแบบ asynchronous ส่ง `async: true` แล้วคำขอสร้างจะคืน `jobid` กลับมาทันที จากนั้นคุณ poll จนวิดีโอเสร็จ 1. ส่งงาน — `POST https://api.useapi.net/v1/google-flow/videos`: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A serene mountain landscape at sunset, camera slowly panning right", "model": "veo-3.1-fast", "aspectRatio": "landscape", "duration": 8, "async": true }' ``` ในโหมด async คำตอบกลับมาทันทีพร้อม `201 Created`, `jobid` ตัวพิมพ์เล็ก และ `status: "created"`: ```json { "jobid": "j1731859234567v-u12345-email:jo***@gmail.com-bot:google-flow", "type": "video", "status": "created", "created": "2026-06-15T12:34:56.789Z", "request": { "async": true, "prompt": "A serene mountain landscape at sunset, camera slowly panning right", "model": "veo-3.1-fast", "aspectRatio": "landscape", "duration": 8 } } ``` 2. poll ผลลัพธ์ — `GET https://api.useapi.net/v1/google-flow/jobs/{jobId}`: ```bash curl "https://api.useapi.net/v1/google-flow/jobs/{jobId}" \ -H "Authorization: Bearer $USEAPI_TOKEN" ``` `status` เปลี่ยนจาก `created` → `started` → `completed` เมื่อถึง `completed` ไฟล์ MP4 ที่เสร็จแล้วจะอยู่ใน `response.media[].videoUrl` (prompt เดียวที่ใช้ `count > 1` จะคืนหนึ่งรายการต่อวิดีโอ): ```json { "jobid": "j1731859234567v-...", "type": "video", "status": "completed", "response": { "media": [ { "mediaGenerationId": "user:12345-email:6a6f...-video:a1d95d21-...", "videoUrl": "https://flow-content.google/video/a1d95d21-...?Expires=...", "thumbnailUrl": "https://flow-content.google/image/a1d95d21-...?Expires=..." } ], "remainingCredits": 18760 } } ``` โดยทั่วไป Veo 3.1 เสร็จใน 60–180 วินาที ขึ้นกับโมเดลและโหมด ในการรันของเราเมื่อ 20 ตุลาคม 2026 วิดีโอยาว 8 วินาที 9 คลิปใช้เวลา 50 ถึง 105 วินาทีตั้งแต่ส่งงานจนได้ MP4 ([ผลการรันที่วัดไว้](/docs/articles/veo-3-1-api-pricing#examples)) `videoUrl` ที่มีลายเซ็นใช้ได้ราว 6 ชั่วโมง จึงควรดาวน์โหลดทันที ไม่อยาก poll? ใส่ `replyUrl` ใน body ของคำขอสร้าง เพื่อรับ webhook callback เมื่องานเสร็จ ### วิดีโอจากภาพ และวิดีโอจากภาพอ้างอิง Veo รับภาพได้สองแบบ อัปโหลดภาพแต่ละภาพก่อนด้วย [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email) (ไบต์ดิบ, `Content-Type` แบบภาพ, PNG/JPEG/WebP ไม่เกิน 20 MB) คำตอบของการอัปโหลดเก็บ id ซ้อนไว้ที่ `mediaGenerationId.mediaGenerationId` สตริงที่ซ้อนอยู่นี้คือค่าที่คุณส่งกลับไป เมื่อส่งภาพใด ๆ ไปด้วย คุณไม่ต้องใส่ `email` ก็ได้ คำขอจะถูกส่งไปยังบัญชีที่อัปโหลดภาพนั้น #### เฟรมแรก / เฟรมสุดท้าย (I2V) ภาพของคุณจะกลายเป็นเฟรมหนึ่งของวิดีโอจริง ๆ ส่งเป็น `startImage` เพื่อเริ่มวิดีโอจากเฟรมนั้น: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Brave Captain Cat chasing away the pirates!", "model": "veo-3.1-fast", "aspectRatio": "portrait", "startImage": "user:12345-email:6a6f...-image:ff9aa5cc-...", "async": true }' ``` เพิ่ม `endImage` (id อ้างอิงของภาพที่อัปโหลดอีกภาพ) เพื่อกำหนดเฟรมสุดท้าย แล้ว Veo จะสร้างช่วงเปลี่ยนระหว่างสองภาพ `endImage` ต้องใช้คู่กับ `startImage` ไม่รองรับการใส่แค่เฟรมสุดท้าย โมเดล Omni (`omni-flash-1.2`, `omni-flash`) รับคู่เฟรมนี้ได้เหมือนกัน แต่สองเฟรมนี้จะเป็นอินพุตเดียวที่รับ ใส่ `referenceImage_*`, `character_*` หรือ `referenceAudio_*` ร่วมด้วยไม่ได้ #### ภาพอ้างอิง (R2V) ภาพของคุณกำหนดทิศทางของทั้งวิดีโอ ทั้งตัวแบบ ตัวละคร หรือสไตล์ แทนที่จะเป็นเฟรมใดเฟรมหนึ่ง ส่ง `referenceImage_1` ถึง `referenceImage_3` (Veo รับได้สูงสุด 3 ภาพ เฉพาะวิดีโอ 8 วินาที และไม่รองรับบน `veo-3.1-quality`) R2V ใช้ร่วมกับ `startImage`/`endImage` ไม่ได้: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A lady says to the dog, \"Say meow meow meow.\" The dog looks at the lady with a surprised, frustrated look and woofs in a human voice, \"What the heck lady?!\"", "model": "veo-3.1-fast", "aspectRatio": "portrait", "referenceImage_1": "user:12345-email:6a6f...-image:abcde-...", "async": true }' ``` อ้างถึงภาพอ้างอิงแต่ละภาพใน prompt ด้วยเครื่องหมาย `@referenceImage_N` เพิ่ม `referenceAudio_1` (ชื่อเสียงของระบบ เช่น `Zephyr`) สำหรับเสียงบรรยาย หรือส่ง[ตัวละคร](/docs/api-google-flow-v1/post-google-flow-characters)ที่ใช้ซ้ำได้เป็น `character_1` (ใช้โหมด R2V เดียวกัน และนับรวมในโควตาภาพอ้างอิง 3 ภาพ) Omni 1.2 Flash ทำได้มากกว่านั้น รับภาพอ้างอิงได้สูงสุด 10 ภาพ พร้อมแก้ไขวิดีโอจากวิดีโอและเสียงพูดที่ซิงก์กัน ดู[คู่มือ Omni Flash](/docs/articles/omni-flash-bash-th) ### สร้างวิดีโอเป็นชุดด้วยสคริปต์ กว่าจะได้ช็อตที่ใช่ต้องลองหลายครั้ง และการรันทีละครั้งด้วยมือก็น่าเบื่อ สคริปต์ Node.js ด้านล่างอ่านรายการ prompt จาก `prompts.json` อัปโหลดภาพเฟรมเริ่ม/เฟรมจบ ส่งงานแต่ละงานในโหมด async แล้ว poll และดาวน์โหลด MP4 ทุกไฟล์ที่เสร็จ คุณจึงส่งงานไว้เป็นชุด แล้วค่อยกลับมาเลือกคลิปที่ดีที่สุด คุณต้องมี [Node.js](https://nodejs.org) v21 ขึ้นไป วาง `prompts.json` และ `google-flow.mjs` ไว้ในโฟลเดอร์เดียวกัน แล้วรัน `node ./google-flow.mjs API_TOKEN EMAIL` โดย `API_TOKEN` คือ [API token](/docs/start-here/setup-useapi) ของ useapi.net และ `EMAIL` คืออีเมลของ[บัญชี Google Flow](/docs/start-here/setup-google-flow)ที่เชื่อมไว้ สคริปต์ค้นหาบัญชีจากอีเมลให้เอง และตรวจฟิลด์ `health` ก่อนส่งงาน อยาก clone ไปรันบนเครื่องตัวเอง? ไฟล์ `google-flow.mjs` และ `prompts.json` ฉบับเต็มอยู่บน GitHub ใน [`useapi/google-flow-api`](https://github.com/useapi/google-flow-api/tree/main/veo-video) <details markdown="block"> <summary>ขยาย `prompts.json`</summary> ```json [ { "prompt": "By default the veo-3.1-fast model with a landscape 8-second clip will be used." }, { "model": "veo-3.1-quality", "aspectRatio": "landscape", "duration": 8, "count": 2, "prompt": "Highest-quality Veo 3.1, two variations. For all parameters see https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos" }, { "model": "veo-3.1-fast", "aspectRatio": "portrait", "duration": 8, "startImage": "./first_image.jpeg", "endImage": "./last_image.jpeg", "prompt": "Image-to-video with a start frame (startImage) and an end frame (endImage). Supported by Veo and by both Omni models." }, { "model": "omni-flash", "duration": 10, "prompt": "Gemini Omni Flash is audio-native and supports 10-second clips. Other models (veo-3.1-lite, veo-3.1-lite-low-priority, …) are selectable via the model field — see the POST /videos docs." } ] ``` </details> <details markdown="block"> <summary>ขยายสคริปต์ `google-flow.mjs`</summary> ```javascript /* Script version 1.1, September 11, 2026 Script to batch-generate videos using prompts with the Google Flow API v1 by useapi.net 🚀 Uses the POST /videos endpoint in async mode (default model: veo-3.1-fast) and polls GET /jobs/{jobId}. For more details visit https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos Installation Instructions: ========================== You need Node.js v21 or newer installed to run this script. Download and install Node.js from: - Windows, macOS, Linux: https://nodejs.org/ After installation, verify by running the following command in a terminal: node -v Running the Script: =================== Usage: node google-flow.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE] Replace API_TOKEN with your actual useapi.net API token, see https://useapi.net/docs/start-here/setup-useapi Replace EMAIL with configured Google Flow email account, see https://useapi.net/docs/start-here/setup-google-flow If optional PROMPTS_FILE not provided prompts.json will be used. Example: -------- node google-flow.mjs user:1234-abcdefhijklmnopqrstuv my@email.com This command executes the script using API token user:1234-abcdefhijklmnopqrstuv with my@email.com Google Flow account email. Changelog: ========== - June 15, 2026: Initial release. - September 11, 2026: Accepts .jpg and upper-case image extensions for startImage and endImage. A prompt whose startImage or endImage fails to upload is skipped and logged to google-flow_errors.txt instead of being submitted without that frame. Saves a downloaded video under its final name only once it has been fully received, so a failed download leaves no partial MP4 for the next run to skip as "already exists". */ import readline from 'node:readline'; import fs from 'fs/promises'; import path from 'path'; import { writeFile } from 'node:fs/promises'; import { Readable } from 'node:stream'; // Constants const RESULTS_FILE = 'google-flow_results.txt'; const ERRORS_FILE = 'google-flow_errors.txt'; const DEFAULT_PROMPTS_FILE = 'prompts.json'; const DEFAULT_MODEL = 'veo-3.1-fast'; const SLEEP_429 = 30 * 1000; // in milliseconds const SLEEP_POLL = 15 * 1000; // in milliseconds const urlAccounts = 'https://api.useapi.net/v1/google-flow/accounts'; const urlVideos = 'https://api.useapi.net/v1/google-flow/videos'; const urlJobs = 'https://api.useapi.net/v1/google-flow/jobs/'; const urlUploadAsset = 'https://api.useapi.net/v1/google-flow/assets/'; // To upload .webp keep its .webp extension — Google Flow accepts png, jpeg and webp. const supportedFileExtensions = ['png', 'jpg', 'jpeg', 'webp']; // { filename: mediaGenerationId } const uploadedFiles = {}; // Utility to sleep for given milliseconds const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); // Function to fetch configured Google Flow API accounts async function fetchAccounts(apiToken) { const response = await fetch(urlAccounts, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.error(`⛔ Error fetching accounts (HTTP ${response.status}): ${response.statusText}`); process.exit(1); } return response.json(); } const elapsedTimeSec = (start) => (Date.now() - start) / 1000; // Map a file extension to the Content-Type required by POST /assets const contentTypeForExt = (ext) => ext === 'png' ? 'image/png' : ext === 'webp' ? 'image/webp' : 'image/jpeg'; async function uploadAsset(apiToken, email, filename) { // Check if already uploaded if (uploadedFiles.hasOwnProperty(filename)) return uploadedFiles[filename]; const startTime = Date.now(); console.log(`⬆️ Account ${email} uploading file…`, filename); const body = new Blob([await fs.readFile(filename)]); const fileExt = filename.split('.').pop().toLowerCase(); const response = await fetch(`${urlUploadAsset}${encodeURIComponent(email)}`, { method: 'POST', headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}`, 'Content-Type': contentTypeForExt(fileExt) }, body }); if (response.ok) { const json = await response.json(); // POST /assets returns the reference id nested as mediaGenerationId.mediaGenerationId const mediaGenerationId = json?.mediaGenerationId?.mediaGenerationId; console.log(`🆗 mediaGenerationId (${elapsedTimeSec(startTime)} sec)`, mediaGenerationId); uploadedFiles[filename] = mediaGenerationId; } else { console.error(`❗ Unable to upload file HTTP ${response.status} (${elapsedTimeSec(startTime)} sec)`, await response.text()); // Do not attempt to upload failed file again uploadedFiles[filename] = undefined; } return uploadedFiles[filename]; } async function submit(apiToken, url, body, index, prompt) { const createResponse = await fetch(url, { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiToken}` }, body }); const createBody = await createResponse.text(); // Async POST /videos returns 201 Created with a jobid to poll. if (createResponse.status == 201) { const json = JSON.parse(createBody); // 201 async payload uses lowercase "jobid"; sync 200 uses "jobId". Accept either. const jobId = json.jobid ?? json.jobId; if (jobId) { await fs.appendFile(RESULTS_FILE, `${jobId},#${index}:${prompt}\n`); console.log(`✅ jobId`, jobId); return 201; } else { const error = `No jobid found in HTTP 201 response`; console.log(`❓ ${error}`, createBody); await fs.appendFile(ERRORS_FILE, `${error},#${index}:${prompt}\n`); return 500; } } else { switch (createResponse.status) { case 429: console.log(`🔄️ Retry on HTTP ${createResponse.status}`, createBody); break; case 503: console.log(`🔄️ Service unavailable, retry on HTTP ${createResponse.status}`, createBody); break; case 400: console.log(`🛑 Rejected request (validation or content policy)`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${prompt}\n`); break; case 402: console.log(`🛑 No subscription / insufficient credits`, createBody); break; default: console.log(`❗ FAILED with HTTP ${createResponse.status}`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${prompt}\n`); } return createResponse.status; } } // Submit a single prompt to POST /videos in async mode. // startImage = start frame (I2V), endImage = end frame (I2V-FL, requires startImage). async function submitVideo(apiToken, email, prompt, index) { const { model, prompt: text, startImage, endImage, aspectRatio, duration, count } = prompt; const useModel = model ?? DEFAULT_MODEL; console.log(`🚀 ${useModel} » Prompt #${index} • account ${email} …`); const startImageId = startImage ? await uploadAsset(apiToken, email, startImage) : undefined; const endImageId = endImage ? await uploadAsset(apiToken, email, endImage) : undefined; // A frame that failed to upload would be left out of the body, and the prompt would still be // generated (and charged) without it. Skip the prompt instead. uploadAsset remembers the failed file, // so a later prompt using it is skipped too, without another upload attempt. const failedUploads = [['startImage', startImage, startImageId], ['endImage', endImage, endImageId]] .filter(([, file, id]) => file && !id); for (const [param, file] of failedUploads) { console.error(`🛑 Prompt #${index} skipped: ${param} ${file} failed to upload`); await fs.appendFile(ERRORS_FILE, `Upload failed for ${param} ${file},#${index}:${text}\n`); } if (failedUploads.length) return; const body = JSON.stringify({ model: useModel, email, prompt: text, aspectRatio, duration, count, startImage: startImageId, endImage: endImageId, async: true }); return await submit(apiToken, urlVideos, body, index, text); } // Function to download videos async function download(apiToken) { if (! await fileExists(RESULTS_FILE)) return; try { const resultsContent = await fs.readFile(RESULTS_FILE, 'utf8'); const lines = resultsContent.trim().split('\n'); for (const line of lines) { const [jobId, prompt] = line.split(','); console.log(`👉 ${jobId}`); while (true) { const response = await fetch(`${urlJobs}${jobId}`, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.log(`🛑 Poll failed ${jobId} (HTTP ${response.status}):\n${prompt}\n`, await response.text()); break; } const jobBody = await response.json(); const { status, error, response: jobResponse } = jobBody; if (status == 'failed') { console.error(`🛑 FAILED ${jobId} (${error}):\n${prompt}\n`); break; } if (status == 'completed') { const media = jobResponse?.media ?? []; if (media.length == 0) console.error(`🛑 Completed but no media for ${jobId}:\n${prompt}\n`); // A single prompt with count > 1 returns multiple videos. for (let i = 0; i < media.length; i++) { const url = media[i]?.videoUrl; const videoFilename = `${jobId.replace(/[:*]/g, '_')}_${i + 1}.mp4`; try { await fs.access(videoFilename); console.log(`⚠️ ${videoFilename} already exists. Skipping download.`); continue; } catch { // File does not exist, proceed with downloading } if (url) { console.log(`✅ Downloading ${url} to ${videoFilename}`); // Stream into a temporary file and rename it once the whole video has arrived, so a download // that drops mid-stream leaves no partial file behind for the next run to skip as "already exists". const tempFilename = `${videoFilename}.part`; try { const videoResponse = await fetch(url); if (!videoResponse.ok) { console.error(`⛔ Unable to download ${jobId} (HTTP ${videoResponse.status}):\n${prompt}\n`, url); continue; } const stream = Readable.fromWeb(videoResponse.body); await writeFile(tempFilename, stream); await fs.rename(tempFilename, videoFilename); } catch (err) { await fs.rm(tempFilename, { force: true }); console.error(`⛔ Error during download: ${err}`); } } else console.error(`🛑 No videoUrl for ${jobId} media #${i + 1}:\n${prompt}\n`); } break; } console.log(`⌛ ${jobId} status (${status}) and is still in progress, waiting…`); await sleep(SLEEP_POLL); } } } catch (error) { console.log(`⛔ Error during download:`, error.stack || error); } } // Main function async function main() { const apiToken = process.argv[2]; const email = process.argv[3]; const promptFile = process.argv[4] || DEFAULT_PROMPTS_FILE; if (!apiToken || !email) { console.error('Usage: node google-flow.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE]'); process.exit(1); } console.info('Script v1.1'); console.info('Node version is: ' + process.version); try { if (await fileExists(RESULTS_FILE)) { let user_input; while (!['y', 'n'].includes(user_input)) { user_input = (await promptUser(`❔ ${RESULTS_FILE} file detected. Do you want to download the results now? (y/n): `))?.toLowerCase(); if (user_input == 'y') { await download(apiToken); await fs.unlink(RESULTS_FILE); } } } const start = new Date(); try { console.info('START EXECUTION', start); await execute(apiToken, email, promptFile); // Pass the promptFile to execute function } finally { console.info('COMPLETED', new Date()); console.info('EXECUTION ELAPSED', diffInMinutesAndSeconds(start, new Date())); } try { console.info('START DOWNLOAD', start); await download(apiToken); } finally { console.info('TOTAL ELAPSED', diffInMinutesAndSeconds(start, new Date())); } } catch (error) { console.error('⛔ Error during execution:', error.stack || error); } } // Modify the execute function to accept promptFile as a parameter async function execute(apiToken, email, promptFile) { const accounts = await fetchAccounts(apiToken); console.info(`Configured Google Flow API accounts (${Object.keys(accounts).length}):`, Object.keys(accounts).join(', ')); if (Object.keys(accounts).length <= 0) { console.error(`⛔ No configured Google Flow accounts found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (!accounts[email]) { console.error(`⛔ Account ${email} not found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (accounts[email].health && accounts[email].health !== 'OK') { console.error(`⛔ Account ${email} health is '${accounts[email].health}'. Please resolve and update the account, see https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } const promptData = await fs.readFile(promptFile, 'utf8'); const prompts = JSON.parse(promptData); console.log(`Total number of prompts to process`, prompts.length); let warnings = []; // Parameters accepted by this script for the POST /videos endpoint. // See https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos for every model's full parameter set. const supportedParams = ['model', 'prompt', 'startImage', 'endImage', 'aspectRatio', 'duration', 'count']; const invalidKeys = (prompt) => Object.keys(prompt).filter(key => !key.startsWith('__') && !supportedParams.includes(key)) for (let i = 1; i <= prompts.length; i++) { const prompt = prompts[i - 1]; const { prompt: text, startImage, endImage } = prompt; const validateImage = async (file) => { if (file) { try { await fs.access(file); } catch { warnings.push(`⚠️ Image '${file}' does not exist. Prompt ${i}`); } const ext = file.split('.').pop().toLowerCase(); if (!supportedFileExtensions.includes(ext)) warnings.push(`⚠️ Image ${file} extension ${ext} not supported. Prompt ${i}`); } }; const notSupported = invalidKeys(prompt); if (notSupported.length) warnings.push(`⚠️ Following params not supported: ${notSupported.join(',')}. Prompt ${i}`); if (!text) warnings.push(`⚠️ prompt is required. Prompt ${i}`); if (endImage && !startImage) warnings.push(`⚠️ endImage requires startImage (end-frame-only is not supported). Prompt ${i}`); await Promise.all([validateImage(startImage), validateImage(endImage)]); } if (warnings.length > 0) { warnings.forEach(warning => console.warn(warning)); console.error(`⛔ Execution stopped due to warnings.`); process.exit(1); } for (let i = 0; i < prompts.length; i++) { const prompt = prompts[i]; while (true) { const responseCode = await submitVideo(apiToken, email, prompt, i + 1); if (responseCode == 429 || responseCode == 503) await sleep(SLEEP_429); else if (responseCode == 402) { process.exit(1); } else break; } } } // Utility function to check if a file exists async function fileExists(path) { try { await fs.access(path); return true; } catch { return false; } } // Function to prompt user input async function promptUser(query) { const rl = readline.createInterface({ input: process.stdin, output: process.stdout }); return new Promise((resolve) => rl.question(query, answer => { rl.close(); resolve(answer); })); } function diffInMinutesAndSeconds(date1, date2) { const diffInSeconds = Math.floor((date2 - date1) / 1000); return `${Math.floor(diffInSeconds / 60)} minutes ${diffInSeconds % 60} seconds`; }; main(); ``` </details> ### ตัวอย่าง วิดีโอ Veo 3.1 จริงที่สร้างผ่าน Google Flow API นี้ นำมาจากบันทึกการอัปเดตของเราโดยตรง ###### veo-3.1-fast » กัปตันแมวผู้กล้าหาญไล่โจรสลัด (วิดีโอจากภาพ) {: .no_toc #veo-31-fast--brave-captain-cat-chasing-away-the-pirates-image-to-video } จาก [Google Flow API v1: Initial Release](/blog/251117) ทำให้ภาพนิ่ง Nano Banana ที่ส่งเป็น `startImage` เคลื่อนไหว <video poster="https://media.useapi.net/blog/2025-11-17-251117/veo-3-1-fast-poster.jpg" src="https://media.useapi.net/blog/2025-11-17-251117/veo-3-1-fast.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> ###### veo-3.1-fast » คุณผู้หญิงกับสุนัข พร้อมเสียงบรรยาย AI {: .no_toc #veo-31-fast--lady-and-her-dog-with-ai-voice-narration } จาก [Veo 3.1 Lite and Voice Narration](/blog/260403) วิดีโอจากภาพอ้างอิง ที่ใช้พรีเซ็ต `referenceAudio_1: "Zephyr"` เพิ่มบทพูด <video poster="https://media.useapi.net/blog/2026-04-03-260403/veo-3-1-fast-voice-zephyr-poster.jpg" controls width="100%" style="max-width:400px"> <source src="https://media.useapi.net/blog/2026-04-03-260403/veo-3-1-fast-voice-zephyr.mp4" type="video/mp4"> </video> ###### veo-3.1-fast » เต้นชะชะช่า (วิดีโอแนวตั้งจากภาพอ้างอิง) {: .no_toc #veo-31-fast--dancing-cha-cha-portrait-reference-to-video } จาก [Veo 3.1 Portrait R2V](/blog/260113) R2V แนวตั้งจากภาพอ้างอิงภาพเดียว <video poster="https://media.useapi.net/blog/2026-01-13-260113/dancing-cha-cha-poster.jpg" src="https://media.useapi.net/blog/2026-01-13-260113/dancing-cha-cha.mp4" style="width: 100%; max-width: 400px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> ### คำถามที่พบบ่อย - **Veo 3.1 มี API ไหม?** ผ่าน useapi.net มี [Google Flow API](/docs/api-google-flow-v1) รัน Veo 3.1 Quality, Fast และ Lite ผ่าน REST บนแพ็กเกจเว็บไซต์ Google Flow ของคุณ (Google AI Pro หรือ Ultra) วิดีโอ Veo 3.1 Quality ยาว 8 วินาทีราคา $0.80 บน Google AI Ultra $199.99 เทียบกับ $3.20 บน Veo API ทางการ (ข้อมูล ณ พฤศจิกายน 2026) - **Veo 3.1 Quality, Fast และ Lite ต่างกันอย่างไร?** ผ่าน useapi.net คุณเลือกโมเดลได้ทีละคำขอด้วยฟิลด์ `model` โดย `veo-3.1-quality` ให้คุณภาพสูงสุด `veo-3.1-fast` เป็นค่าเริ่มต้นที่สมดุลระหว่างความเร็วกับคุณภาพ และ `veo-3.1-lite` ถูกที่สุด คลิปละ $0.04 บน Google AI Ultra $199.99 เทียบกับ $0.40 บน Veo API ทางการ บนแพ็กเกจนั้น `veo-3.1-lite-low-priority` ราคา $0 ได้ราว 1,000 คลิปขึ้นไปต่อวัน (ข้อมูล ณ พฤศจิกายน 2026) - **Veo สร้างวิดีโอจากภาพได้ไหม?** ผ่าน useapi.net ได้ อัปโหลดเฟรมเริ่มด้วย [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email) แล้วส่ง id อ้างอิงที่ได้ (ซ้อนอยู่ที่ `mediaGenerationId.mediaGenerationId`) เป็น `startImage` และจะใส่ `endImage` เพื่อกำหนดเฟรมสุดท้ายด้วยก็ได้ (ต้องมี `startImage`) ถ้าต้องการกำหนดตัวแบบหรือสไตล์แทนเฟรม ให้ส่ง `referenceImage_N` ได้สูงสุดสามภาพ ดู[วิดีโอจากภาพ](#image-to-video-and-reference-to-video)ด้านบน - **ต้องแก้ captcha เองไหม?** ผ่าน useapi.net คุณไม่ต้องแก้เองเลย Google Flow ขอ reCAPTCHA ทุกวิดีโอ และ worker ของ useapi.net แก้ให้อัตโนมัติ บัญชี Google Flow บัญชีแรกของคุณได้ฟรี 300 ครั้งบนคีย์ AntiCaptcha, CapSolver และ EzCaptcha ของเราเอง หลังจากนั้นคุณเพิ่มคีย์ผู้ให้บริการของคุณเองด้วย [POST /accounts/captcha-providers](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers) สคริปต์ในคู่มือนี้ไม่ส่ง `captchaToken` - **ต้องมี Veo 3.1 API key ไหม?** ผ่าน useapi.net ไม่ต้องมี Google API key และไม่ต้องมีโปรเจกต์ Google Cloud ใช้ [API token](/docs/start-here/setup-useapi) ของ useapi.net ตัวเดียวก็เรียก Veo 3.1 ได้ และเชื่อมบัญชี Google เพียงครั้งเดียวผ่าน[การตั้งค่าอัตโนมัติ](/docs/start-here/setup-google-flow) ตัว Google Flow เองไม่มี API สาธารณะ และหลังจากโมเดล Veo 3.1 Preview บน Gemini API ปิดตัวเมื่อ 22 ตุลาคม 2026 Veo API ของ Google เองต้องใช้โปรเจกต์ Cloud ที่เปิดการเรียกเก็บเงิน ### สรุป ติดต่อเราได้ที่ <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> หรือ <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> สำหรับทุกคำถามและข้อสงสัยด้านการใช้งาน ดูตัวอย่างโค้ดได้ใน [GitHub repo](https://github.com/useapi/google-flow-api) ของเรา #### เผยแพร่ที่อื่นด้วย {: .no_toc #cross-posted } เผยแพร่บน [dev.to](https://dev.to/useapi/how-to-generate-ai-video-with-veo-31-via-the-google-flow-api-2g4i){:rel="nofollow"} ด้วย ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-flow-bash-vi === Document URL: https://useapi.net/docs/articles/google-flow-bash-vi --- layout: default title: "Cách dùng Veo 3.1 API: tạo video bằng curl qua Google Flow API" description: "Veo 3.1 API bằng curl (Fast, Quality, Lite) qua Google Flow API của useapi.net trên Google AI Pro hoặc Ultra: không cần dự án Google Cloud, không cần API key." keywords: [Veo 3.1 API, Veo 3.1 API key, Veo API, Google Veo API, Veo 3 API, Google Flow API, Veo 3.1 Fast, Veo 3.1 Lite, Gemini API Veo shutdown, API Veo 3.1 giá rẻ, cách dùng Veo 3.1 API, tạo video AI bằng API, tạo video từ văn bản, tạo video từ ảnh, text to video, image to video, hướng dẫn, code] parent: Articles nav_exclude: true lang: vi translation_key: google-flow date: 2026-06-15 last_modified: 2026-11-10 nav_order: 810 repo: https://github.com/useapi/google-flow-api --- ## Cách dùng Veo 3.1 API: tạo video bằng curl qua Google Flow API {: #how-to-use-the-veo-31-api-generate-video-with-curl-via-the-google-flow-api .no_toc } 6 phút đọc • 15 tháng 6 năm 2026 (6 tháng 11 năm 2026) useapi.net là API của bên thứ ba, không liên kết với Google và không được Google bảo trợ. ## Mục lục {: #table-of-contents .no_toc .text-delta } ### Giới thiệu [Veo 3.1](https://deepmind.google/technologies/veo/) chạy chỉ với một lệnh `curl` qua [Google Flow API](/docs/api-google-flow-v1) của useapi.net, trên gói đăng ký website [Google Flow](https://flow.google.com) của bạn ([Google AI Pro hoặc Ultra](https://gemini.google/subscriptions/)). Một video Veo 3.1 Fast dài 8 giây tốn $0,08 trên Google AI Ultra $199,99, so với $0,80 trên Veo API chính thức (tính đến tháng 11/2026). Google đã tắt các model Veo 3.1 Preview trên Gemini API ngày 22 tháng 10 năm 2026 và chuyển nhà phát triển sang [Agent Platform](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing) trên Cloud, nơi tính cùng mức giá theo giây trên một dự án Google Cloud. API bên thứ ba này không cần dự án Cloud, không cần Google API key và không cần phê duyệt doanh nghiệp. Bên dưới: các model, quy trình hai lệnh gọi, đầu vào là ảnh và một script chạy hàng loạt. ### Các model được hỗ trợ Chọn model cho mỗi request bằng trường `model` (mặc định `veo-3.1-fast`). Số credit của Veo lấy từ [bảng credit Flow chính thức](https://support.google.com/flow/answer/16526234?hl=vi) của Google, số của Omni được đo trên API thật: | Model id | Hạng / tốc độ | Độ dài | Credit mỗi video | |----------|--------------|-----------|------------------------| | `veo-3.1-lite` | Veo rẻ nhất | 4s, 6s, 8s | 10 (ngoài Ultra) · 5 (Ultra) | | `veo-3.1-lite-low-priority` | Lite, ưu tiên thấp | 4s, 6s, 8s | 0, chỉ chủ gói Ultra $199,99 | | `veo-3.1-fast` *(mặc định)* | Veo nhanh | 4s, 6s, 8s | 20 (ngoài Ultra) · 10 (Ultra) | | `veo-3.1-quality` | Veo chất lượng cao nhất | chỉ 8s | 100 | | `omni-flash-1.2` | Omni 1.2 Flash, có âm thanh gốc | 3s đến 15s | 3 mỗi giây tới 10s, 6 mỗi giây sau đó (ở 720p) | | `omni-flash` | Omni 1.1 Flash, có âm thanh gốc | 4s, 6s, 8s, 10s | 7 / 10 / 12 / 15 (theo độ dài, ở 720p) | Với Veo, video `4s` và `6s` cần Ultra (xem [trang tổng quan](/docs/api-google-flow-v1)). Google Flow cũng tạo ảnh tĩnh bằng các model Nano Banana qua endpoint riêng [POST /images](/docs/api-google-flow-v1/post-google-flow-images). ### Giá Mỗi video dùng credit Flow từ gói Google AI của bạn, và useapi.net không thu phí theo video. Giá mỗi video trên từng gói, so với API chính thức, có trong [bảng giá Google Flow](/docs/api-google-flow-v1#pricing), còn bài [giá Veo 3.1 API](/docs/articles/veo-3-1-api-pricing) nói chi tiết về Veo. ### Tạo video bằng hai lệnh gọi API Bạn cần một [API token](/docs/start-here/setup-useapi) của useapi.net và một [tài khoản Google Flow](/docs/start-here/setup-google-flow) đã kết nối. Job video chạy bất đồng bộ: truyền `async: true` và lệnh tạo trả về `jobid` ngay, sau đó bạn polling cho tới khi video sẵn sàng. 1. Gửi job — `POST https://api.useapi.net/v1/google-flow/videos`: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A serene mountain landscape at sunset, camera slowly panning right", "model": "veo-3.1-fast", "aspectRatio": "landscape", "duration": 8, "async": true }' ``` Ở chế độ async, phản hồi trả về ngay với `201 Created`, một `jobid` viết thường và `status: "created"`: ```json { "jobid": "j1731859234567v-u12345-email:jo***@gmail.com-bot:google-flow", "type": "video", "status": "created", "created": "2026-06-15T12:34:56.789Z", "request": { "async": true, "prompt": "A serene mountain landscape at sunset, camera slowly panning right", "model": "veo-3.1-fast", "aspectRatio": "landscape", "duration": 8 } } ``` 2. Polling lấy kết quả — `GET https://api.useapi.net/v1/google-flow/jobs/{jobId}`: ```bash curl "https://api.useapi.net/v1/google-flow/jobs/{jobId}" \ -H "Authorization: Bearer $USEAPI_TOKEN" ``` `status` chuyển từ `created` → `started` → `completed`. Khi tới `completed`, file MP4 hoàn chỉnh nằm ở `response.media[].videoUrl` (một prompt với `count > 1` trả về một mục cho mỗi video): ```json { "jobid": "j1731859234567v-...", "type": "video", "status": "completed", "response": { "media": [ { "mediaGenerationId": "user:12345-email:6a6f...-video:a1d95d21-...", "videoUrl": "https://flow-content.google/video/a1d95d21-...?Expires=...", "thumbnailUrl": "https://flow-content.google/image/a1d95d21-...?Expires=..." } ], "remainingCredits": 18760 } } ``` Veo 3.1 thường xong trong 60–180 giây tùy model và chế độ. Trong các lần chạy của chúng tôi ngày 20 tháng 10 năm 2026, chín video 8 giây mất 50 đến 105 giây từ lúc gửi tới khi có MP4 hoàn chỉnh ([các lần chạy đã đo](/docs/articles/veo-3-1-api-pricing#examples)). `videoUrl` có chữ ký dùng được khoảng 6 giờ, nên hãy tải về sớm. Không muốn polling? Truyền `replyUrl` trong body của lệnh tạo để nhận webhook khi job xong. ### Tạo video từ ảnh và từ ảnh tham chiếu Veo nhận ảnh đầu vào theo hai cách khác nhau. Trước tiên tải từng ảnh lên bằng [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email) (byte thô, `Content-Type` ảnh, PNG/JPEG/WebP tối đa 20 MB). Phản hồi tải lên đặt id lồng ở `mediaGenerationId.mediaGenerationId` — chuỗi lồng đó là thứ bạn truyền lại. Khi có bất kỳ ảnh đầu vào nào, bạn có thể bỏ `email`: request sẽ đi tới tài khoản đã nhận ảnh tải lên. #### Khung đầu / khung cuối (I2V) Ảnh của bạn trở thành đúng một khung hình của video. Truyền nó làm `startImage` để video bắt đầu từ khung đó: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Brave Captain Cat chasing away the pirates!", "model": "veo-3.1-fast", "aspectRatio": "portrait", "startImage": "user:12345-email:6a6f...-image:ff9aa5cc-...", "async": true }' ``` Thêm `endImage` (id tham chiếu của một ảnh tải lên thứ hai) để cố định khung cuối, và Veo tạo đoạn chuyển giữa hai khung. `endImage` cần có `startImage` — không hỗ trợ chỉ có khung cuối. Các model Omni (`omni-flash-1.2`, `omni-flash`) nhận cùng cặp này, nhưng khi đó hai khung là đầu vào duy nhất — không kèm `referenceImage_*`, `character_*` hay `referenceAudio_*`. #### Ảnh tham chiếu (R2V) Ảnh của bạn định hướng cả video — chủ thể, nhân vật hoặc phong cách — thay vì một khung hình cụ thể. Truyền từ `referenceImage_1` tới `referenceImage_3` (Veo nhận tối đa 3, chỉ với video 8 giây, và không dùng với `veo-3.1-quality`). R2V không kết hợp được với `startImage`/`endImage`: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A lady says to the dog, \"Say meow meow meow.\" The dog looks at the lady with a surprised, frustrated look and woofs in a human voice, \"What the heck lady?!\"", "model": "veo-3.1-fast", "aspectRatio": "portrait", "referenceImage_1": "user:12345-email:6a6f...-image:abcde-...", "async": true }' ``` Nhắc tới từng tham chiếu ngay trong prompt bằng dấu `@referenceImage_N`, thêm `referenceAudio_1` (tên một giọng hệ thống như `Zephyr`) để có lời thuyết minh, hoặc truyền một [nhân vật](/docs/api-google-flow-v1/post-google-flow-characters) dùng lại được làm `character_1` (nó chạy cùng chế độ R2V và tính vào giới hạn 3 tham chiếu). Omni 1.2 Flash đi xa hơn với tham chiếu — tối đa 10, cộng với chỉnh sửa video sang video và giọng nói đồng bộ — xem [hướng dẫn Omni Flash](/docs/articles/omni-flash-bash-vi). ### Tạo hàng loạt bằng script Tìm được cảnh quay ưng ý cần nhiều lần thử, và chạy từng lần bằng tay rất mất công. Script Node.js dưới đây đọc danh sách prompt từ `prompts.json`, tải lên ảnh khung đầu/khung cuối nếu có, gửi từng job ở chế độ async, rồi polling và tải về mọi file MP4 đã xong — nên bạn có thể xếp hàng cả loạt rồi quay lại chọn video đẹp nhất. Bạn cần [Node.js](https://nodejs.org) v21 trở lên. Đặt `prompts.json` và `google-flow.mjs` cùng một thư mục và chạy `node ./google-flow.mjs API_TOKEN EMAIL`, trong đó `API_TOKEN` là [API token](/docs/start-here/setup-useapi) useapi.net của bạn và `EMAIL` là email của [tài khoản Google Flow](/docs/start-here/setup-google-flow) đã kết nối. Script tự tìm tài khoản theo email và kiểm tra trường `health` trước khi gửi. Muốn clone và chạy trên máy? File `google-flow.mjs` và `prompts.json` đầy đủ có trên GitHub ở [`useapi/google-flow-api`](https://github.com/useapi/google-flow-api/tree/main/veo-video). <details markdown="block"> <summary>Mở `prompts.json`</summary> ```json [ { "prompt": "By default the veo-3.1-fast model with a landscape 8-second clip will be used." }, { "model": "veo-3.1-quality", "aspectRatio": "landscape", "duration": 8, "count": 2, "prompt": "Highest-quality Veo 3.1, two variations. For all parameters see https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos" }, { "model": "veo-3.1-fast", "aspectRatio": "portrait", "duration": 8, "startImage": "./first_image.jpeg", "endImage": "./last_image.jpeg", "prompt": "Image-to-video with a start frame (startImage) and an end frame (endImage). Supported by Veo and by both Omni models." }, { "model": "omni-flash", "duration": 10, "prompt": "Gemini Omni Flash is audio-native and supports 10-second clips. Other models (veo-3.1-lite, veo-3.1-lite-low-priority, …) are selectable via the model field — see the POST /videos docs." } ] ``` </details> <details markdown="block"> <summary>Mở script `google-flow.mjs`</summary> ```javascript /* Script version 1.1, September 11, 2026 Script to batch-generate videos using prompts with the Google Flow API v1 by useapi.net 🚀 Uses the POST /videos endpoint in async mode (default model: veo-3.1-fast) and polls GET /jobs/{jobId}. For more details visit https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos Installation Instructions: ========================== You need Node.js v21 or newer installed to run this script. Download and install Node.js from: - Windows, macOS, Linux: https://nodejs.org/ After installation, verify by running the following command in a terminal: node -v Running the Script: =================== Usage: node google-flow.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE] Replace API_TOKEN with your actual useapi.net API token, see https://useapi.net/docs/start-here/setup-useapi Replace EMAIL with configured Google Flow email account, see https://useapi.net/docs/start-here/setup-google-flow If optional PROMPTS_FILE not provided prompts.json will be used. Example: -------- node google-flow.mjs user:1234-abcdefhijklmnopqrstuv my@email.com This command executes the script using API token user:1234-abcdefhijklmnopqrstuv with my@email.com Google Flow account email. Changelog: ========== - June 15, 2026: Initial release. - September 11, 2026: Accepts .jpg and upper-case image extensions for startImage and endImage. A prompt whose startImage or endImage fails to upload is skipped and logged to google-flow_errors.txt instead of being submitted without that frame. Saves a downloaded video under its final name only once it has been fully received, so a failed download leaves no partial MP4 for the next run to skip as "already exists". */ import readline from 'node:readline'; import fs from 'fs/promises'; import path from 'path'; import { writeFile } from 'node:fs/promises'; import { Readable } from 'node:stream'; // Constants const RESULTS_FILE = 'google-flow_results.txt'; const ERRORS_FILE = 'google-flow_errors.txt'; const DEFAULT_PROMPTS_FILE = 'prompts.json'; const DEFAULT_MODEL = 'veo-3.1-fast'; const SLEEP_429 = 30 * 1000; // in milliseconds const SLEEP_POLL = 15 * 1000; // in milliseconds const urlAccounts = 'https://api.useapi.net/v1/google-flow/accounts'; const urlVideos = 'https://api.useapi.net/v1/google-flow/videos'; const urlJobs = 'https://api.useapi.net/v1/google-flow/jobs/'; const urlUploadAsset = 'https://api.useapi.net/v1/google-flow/assets/'; // To upload .webp keep its .webp extension — Google Flow accepts png, jpeg and webp. const supportedFileExtensions = ['png', 'jpg', 'jpeg', 'webp']; // { filename: mediaGenerationId } const uploadedFiles = {}; // Utility to sleep for given milliseconds const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); // Function to fetch configured Google Flow API accounts async function fetchAccounts(apiToken) { const response = await fetch(urlAccounts, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.error(`⛔ Error fetching accounts (HTTP ${response.status}): ${response.statusText}`); process.exit(1); } return response.json(); } const elapsedTimeSec = (start) => (Date.now() - start) / 1000; // Map a file extension to the Content-Type required by POST /assets const contentTypeForExt = (ext) => ext === 'png' ? 'image/png' : ext === 'webp' ? 'image/webp' : 'image/jpeg'; async function uploadAsset(apiToken, email, filename) { // Check if already uploaded if (uploadedFiles.hasOwnProperty(filename)) return uploadedFiles[filename]; const startTime = Date.now(); console.log(`⬆️ Account ${email} uploading file…`, filename); const body = new Blob([await fs.readFile(filename)]); const fileExt = filename.split('.').pop().toLowerCase(); const response = await fetch(`${urlUploadAsset}${encodeURIComponent(email)}`, { method: 'POST', headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}`, 'Content-Type': contentTypeForExt(fileExt) }, body }); if (response.ok) { const json = await response.json(); // POST /assets returns the reference id nested as mediaGenerationId.mediaGenerationId const mediaGenerationId = json?.mediaGenerationId?.mediaGenerationId; console.log(`🆗 mediaGenerationId (${elapsedTimeSec(startTime)} sec)`, mediaGenerationId); uploadedFiles[filename] = mediaGenerationId; } else { console.error(`❗ Unable to upload file HTTP ${response.status} (${elapsedTimeSec(startTime)} sec)`, await response.text()); // Do not attempt to upload failed file again uploadedFiles[filename] = undefined; } return uploadedFiles[filename]; } async function submit(apiToken, url, body, index, prompt) { const createResponse = await fetch(url, { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiToken}` }, body }); const createBody = await createResponse.text(); // Async POST /videos returns 201 Created with a jobid to poll. if (createResponse.status == 201) { const json = JSON.parse(createBody); // 201 async payload uses lowercase "jobid"; sync 200 uses "jobId". Accept either. const jobId = json.jobid ?? json.jobId; if (jobId) { await fs.appendFile(RESULTS_FILE, `${jobId},#${index}:${prompt}\n`); console.log(`✅ jobId`, jobId); return 201; } else { const error = `No jobid found in HTTP 201 response`; console.log(`❓ ${error}`, createBody); await fs.appendFile(ERRORS_FILE, `${error},#${index}:${prompt}\n`); return 500; } } else { switch (createResponse.status) { case 429: console.log(`🔄️ Retry on HTTP ${createResponse.status}`, createBody); break; case 503: console.log(`🔄️ Service unavailable, retry on HTTP ${createResponse.status}`, createBody); break; case 400: console.log(`🛑 Rejected request (validation or content policy)`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${prompt}\n`); break; case 402: console.log(`🛑 No subscription / insufficient credits`, createBody); break; default: console.log(`❗ FAILED with HTTP ${createResponse.status}`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${prompt}\n`); } return createResponse.status; } } // Submit a single prompt to POST /videos in async mode. // startImage = start frame (I2V), endImage = end frame (I2V-FL, requires startImage). async function submitVideo(apiToken, email, prompt, index) { const { model, prompt: text, startImage, endImage, aspectRatio, duration, count } = prompt; const useModel = model ?? DEFAULT_MODEL; console.log(`🚀 ${useModel} » Prompt #${index} • account ${email} …`); const startImageId = startImage ? await uploadAsset(apiToken, email, startImage) : undefined; const endImageId = endImage ? await uploadAsset(apiToken, email, endImage) : undefined; // A frame that failed to upload would be left out of the body, and the prompt would still be // generated (and charged) without it. Skip the prompt instead. uploadAsset remembers the failed file, // so a later prompt using it is skipped too, without another upload attempt. const failedUploads = [['startImage', startImage, startImageId], ['endImage', endImage, endImageId]] .filter(([, file, id]) => file && !id); for (const [param, file] of failedUploads) { console.error(`🛑 Prompt #${index} skipped: ${param} ${file} failed to upload`); await fs.appendFile(ERRORS_FILE, `Upload failed for ${param} ${file},#${index}:${text}\n`); } if (failedUploads.length) return; const body = JSON.stringify({ model: useModel, email, prompt: text, aspectRatio, duration, count, startImage: startImageId, endImage: endImageId, async: true }); return await submit(apiToken, urlVideos, body, index, text); } // Function to download videos async function download(apiToken) { if (! await fileExists(RESULTS_FILE)) return; try { const resultsContent = await fs.readFile(RESULTS_FILE, 'utf8'); const lines = resultsContent.trim().split('\n'); for (const line of lines) { const [jobId, prompt] = line.split(','); console.log(`👉 ${jobId}`); while (true) { const response = await fetch(`${urlJobs}${jobId}`, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.log(`🛑 Poll failed ${jobId} (HTTP ${response.status}):\n${prompt}\n`, await response.text()); break; } const jobBody = await response.json(); const { status, error, response: jobResponse } = jobBody; if (status == 'failed') { console.error(`🛑 FAILED ${jobId} (${error}):\n${prompt}\n`); break; } if (status == 'completed') { const media = jobResponse?.media ?? []; if (media.length == 0) console.error(`🛑 Completed but no media for ${jobId}:\n${prompt}\n`); // A single prompt with count > 1 returns multiple videos. for (let i = 0; i < media.length; i++) { const url = media[i]?.videoUrl; const videoFilename = `${jobId.replace(/[:*]/g, '_')}_${i + 1}.mp4`; try { await fs.access(videoFilename); console.log(`⚠️ ${videoFilename} already exists. Skipping download.`); continue; } catch { // File does not exist, proceed with downloading } if (url) { console.log(`✅ Downloading ${url} to ${videoFilename}`); // Stream into a temporary file and rename it once the whole video has arrived, so a download // that drops mid-stream leaves no partial file behind for the next run to skip as "already exists". const tempFilename = `${videoFilename}.part`; try { const videoResponse = await fetch(url); if (!videoResponse.ok) { console.error(`⛔ Unable to download ${jobId} (HTTP ${videoResponse.status}):\n${prompt}\n`, url); continue; } const stream = Readable.fromWeb(videoResponse.body); await writeFile(tempFilename, stream); await fs.rename(tempFilename, videoFilename); } catch (err) { await fs.rm(tempFilename, { force: true }); console.error(`⛔ Error during download: ${err}`); } } else console.error(`🛑 No videoUrl for ${jobId} media #${i + 1}:\n${prompt}\n`); } break; } console.log(`⌛ ${jobId} status (${status}) and is still in progress, waiting…`); await sleep(SLEEP_POLL); } } } catch (error) { console.log(`⛔ Error during download:`, error.stack || error); } } // Main function async function main() { const apiToken = process.argv[2]; const email = process.argv[3]; const promptFile = process.argv[4] || DEFAULT_PROMPTS_FILE; if (!apiToken || !email) { console.error('Usage: node google-flow.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE]'); process.exit(1); } console.info('Script v1.1'); console.info('Node version is: ' + process.version); try { if (await fileExists(RESULTS_FILE)) { let user_input; while (!['y', 'n'].includes(user_input)) { user_input = (await promptUser(`❔ ${RESULTS_FILE} file detected. Do you want to download the results now? (y/n): `))?.toLowerCase(); if (user_input == 'y') { await download(apiToken); await fs.unlink(RESULTS_FILE); } } } const start = new Date(); try { console.info('START EXECUTION', start); await execute(apiToken, email, promptFile); // Pass the promptFile to execute function } finally { console.info('COMPLETED', new Date()); console.info('EXECUTION ELAPSED', diffInMinutesAndSeconds(start, new Date())); } try { console.info('START DOWNLOAD', start); await download(apiToken); } finally { console.info('TOTAL ELAPSED', diffInMinutesAndSeconds(start, new Date())); } } catch (error) { console.error('⛔ Error during execution:', error.stack || error); } } // Modify the execute function to accept promptFile as a parameter async function execute(apiToken, email, promptFile) { const accounts = await fetchAccounts(apiToken); console.info(`Configured Google Flow API accounts (${Object.keys(accounts).length}):`, Object.keys(accounts).join(', ')); if (Object.keys(accounts).length <= 0) { console.error(`⛔ No configured Google Flow accounts found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (!accounts[email]) { console.error(`⛔ Account ${email} not found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (accounts[email].health && accounts[email].health !== 'OK') { console.error(`⛔ Account ${email} health is '${accounts[email].health}'. Please resolve and update the account, see https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } const promptData = await fs.readFile(promptFile, 'utf8'); const prompts = JSON.parse(promptData); console.log(`Total number of prompts to process`, prompts.length); let warnings = []; // Parameters accepted by this script for the POST /videos endpoint. // See https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos for every model's full parameter set. const supportedParams = ['model', 'prompt', 'startImage', 'endImage', 'aspectRatio', 'duration', 'count']; const invalidKeys = (prompt) => Object.keys(prompt).filter(key => !key.startsWith('__') && !supportedParams.includes(key)) for (let i = 1; i <= prompts.length; i++) { const prompt = prompts[i - 1]; const { prompt: text, startImage, endImage } = prompt; const validateImage = async (file) => { if (file) { try { await fs.access(file); } catch { warnings.push(`⚠️ Image '${file}' does not exist. Prompt ${i}`); } const ext = file.split('.').pop().toLowerCase(); if (!supportedFileExtensions.includes(ext)) warnings.push(`⚠️ Image ${file} extension ${ext} not supported. Prompt ${i}`); } }; const notSupported = invalidKeys(prompt); if (notSupported.length) warnings.push(`⚠️ Following params not supported: ${notSupported.join(',')}. Prompt ${i}`); if (!text) warnings.push(`⚠️ prompt is required. Prompt ${i}`); if (endImage && !startImage) warnings.push(`⚠️ endImage requires startImage (end-frame-only is not supported). Prompt ${i}`); await Promise.all([validateImage(startImage), validateImage(endImage)]); } if (warnings.length > 0) { warnings.forEach(warning => console.warn(warning)); console.error(`⛔ Execution stopped due to warnings.`); process.exit(1); } for (let i = 0; i < prompts.length; i++) { const prompt = prompts[i]; while (true) { const responseCode = await submitVideo(apiToken, email, prompt, i + 1); if (responseCode == 429 || responseCode == 503) await sleep(SLEEP_429); else if (responseCode == 402) { process.exit(1); } else break; } } } // Utility function to check if a file exists async function fileExists(path) { try { await fs.access(path); return true; } catch { return false; } } // Function to prompt user input async function promptUser(query) { const rl = readline.createInterface({ input: process.stdin, output: process.stdout }); return new Promise((resolve) => rl.question(query, answer => { rl.close(); resolve(answer); })); } function diffInMinutesAndSeconds(date1, date2) { const diffInSeconds = Math.floor((date2 - date1) / 1000); return `${Math.floor(diffInSeconds / 60)} minutes ${diffInSeconds % 60} seconds`; }; main(); ``` </details> ### Ví dụ Video Veo 3.1 thật làm qua Google Flow API này, lấy thẳng từ các bài thông báo phát hành của chúng tôi. ###### veo-3.1-fast » Thuyền trưởng Mèo dũng cảm đuổi bọn cướp biển (tạo video từ ảnh) {: #veo-31-fast--brave-captain-cat-chasing-away-the-pirates-image-to-video .no_toc } Từ [Google Flow API v1: Initial Release](/blog/251117). Làm chuyển động từ một ảnh tĩnh Nano Banana truyền vào làm `startImage`. <video poster="https://media.useapi.net/blog/2025-11-17-251117/veo-3-1-fast-poster.jpg" src="https://media.useapi.net/blog/2025-11-17-251117/veo-3-1-fast.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> ###### veo-3.1-fast » Người phụ nữ và chú chó, có lời thuyết minh bằng giọng AI {: #veo-31-fast--lady-and-her-dog-with-ai-voice-narration .no_toc } Từ [Veo 3.1 Lite and Voice Narration](/blog/260403). Tạo video từ ảnh tham chiếu với preset `referenceAudio_1: "Zephyr"` thêm lời thoại. <video poster="https://media.useapi.net/blog/2026-04-03-260403/veo-3-1-fast-voice-zephyr-poster.jpg" controls width="100%" style="max-width:400px"> <source src="https://media.useapi.net/blog/2026-04-03-260403/veo-3-1-fast-voice-zephyr.mp4" type="video/mp4"> </video> ###### veo-3.1-fast » Nhảy cha-cha (tạo video dọc từ ảnh tham chiếu) {: #veo-31-fast--dancing-cha-cha-portrait-reference-to-video .no_toc } Từ [Veo 3.1 Portrait R2V](/blog/260113). R2V khổ dọc từ một ảnh tham chiếu duy nhất. <video poster="https://media.useapi.net/blog/2026-01-13-260113/dancing-cha-cha-poster.jpg" src="https://media.useapi.net/blog/2026-01-13-260113/dancing-cha-cha.mp4" style="width: 100%; max-width: 400px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> ### Câu hỏi thường gặp - **Veo 3.1 có API không?** Qua useapi.net thì có: [Google Flow API](/docs/api-google-flow-v1) chạy Veo 3.1 Quality, Fast và Lite qua REST trên gói đăng ký website Google Flow của bạn (Google AI Pro hoặc Ultra). Một video Veo 3.1 Quality dài 8 giây tốn $0,80 trên Google AI Ultra $199,99, so với $3,20 trên Veo API chính thức (tính đến tháng 11/2026). - **Veo 3.1 Quality, Fast và Lite khác nhau thế nào?** Qua useapi.net, bạn chọn một model cho mỗi request bằng trường `model`. `veo-3.1-quality` cho chất lượng cao nhất, `veo-3.1-fast` là mặc định cân bằng giữa tốc độ và chất lượng, còn `veo-3.1-lite` rẻ nhất: $0,04 một video trên Google AI Ultra $199,99, so với $0,40 trên Veo API chính thức. Trên gói đó, `veo-3.1-lite-low-priority` tốn $0, khoảng 1.000 video trở lên mỗi ngày (tính đến tháng 11/2026). - **Veo có tạo video từ ảnh được không?** Qua useapi.net thì được. Tải khung đầu lên bằng [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email), rồi truyền id tham chiếu nhận được (lồng ở `mediaGenerationId.mediaGenerationId`) làm `startImage`, và tùy chọn `endImage` để cố định khung cuối (cần có `startImage`). Để định hướng chủ thể hoặc phong cách thay vì một khung hình, truyền tối đa ba `referenceImage_N`. Xem [Tạo video từ ảnh](#image-to-video-and-reference-to-video) ở trên. - **Tôi có phải tự giải captcha không?** Qua useapi.net, bạn không bao giờ phải tự giải. Google Flow yêu cầu reCAPTCHA cho mỗi video, và worker của useapi.net tự động giải: tài khoản Google Flow đầu tiên của bạn được 300 lần giải miễn phí bằng key AntiCaptcha, CapSolver và EzCaptcha của chúng tôi, sau đó bạn thêm key dịch vụ của riêng mình bằng [POST /accounts/captcha-providers](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers). Script trong bài này không gửi `captchaToken`. - **Tôi có cần Veo 3.1 API key không?** Qua useapi.net, bạn không cần Google API key hay dự án Google Cloud: một [API token](/docs/start-here/setup-useapi) useapi.net gọi được Veo 3.1, và bạn kết nối tài khoản Google một lần qua [thiết lập tự động](/docs/start-here/setup-google-flow). Bản thân Google Flow không có API công khai, và từ khi các model Veo 3.1 Preview trên Gemini API bị tắt ngày 22 tháng 10 năm 2026, Veo API của chính Google cần một dự án Cloud có bật thanh toán. ### Kết luận Ghé <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> hoặc <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> của chúng tôi cho mọi câu hỏi hỗ trợ. Xem [repo GitHub](https://github.com/useapi/google-flow-api) của chúng tôi với các ví dụ code. #### Đăng ở nơi khác {: #cross-posted .no_toc } Cũng đăng trên [dev.to](https://dev.to/useapi/how-to-generate-ai-video-with-veo-31-via-the-google-flow-api-2g4i){:rel="nofollow"} (tiếng Anh). ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-flow-bash === Document URL: https://useapi.net/docs/articles/google-flow-bash --- layout: default title: "How to Use the Veo 3.1 API: Generate Video with curl via the Google Flow API" description: "Veo 3.1 API from curl (Fast, Quality, Lite) via the useapi.net Google Flow API on Google AI Pro or Ultra: no Google Cloud project, no API key." keywords: [Veo 3.1 API, Veo 3.1 API key, Veo API, Google Veo API, Veo 3 API, Google Flow API, Veo 3.1 Fast, Veo 3.1 Lite, Gemini API Veo shutdown, video generation, text to video, image to video, tutorial, code] parent: Articles nav_exclude: true date: 2026-06-15 last_modified: 2026-11-10 nav_order: 810 repo: https://github.com/useapi/google-flow-api translation_key: google-flow --- ## How to Use the Veo 3.1 API: Generate Video with curl via the Google Flow API 6 min read • June 15, 2026 (November 10, 2026) ## Table of contents ### Introduction [Veo 3.1](https://deepmind.google/technologies/veo/) runs from a single `curl` through the useapi.net [Google Flow API](/docs/api-google-flow-v1), on your [Google Flow](https://flow.google.com) website subscription ([Google AI Pro or Ultra](https://gemini.google/subscriptions/)). An 8-second Veo 3.1 Fast video costs $0.08 on Google AI Ultra $199.99, against $0.80 on the official Veo API (as of November 2026). Google shut down the Veo 3.1 Preview models on the Gemini API on October 22, 2026 and moved developers to its Cloud [Agent Platform](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing), which bills the same per-second rates on a Google Cloud project. This third-party API needs no Cloud project, no Google API key and no enterprise approval. Below: the models, the two-call workflow, image inputs and a runnable batch script. ### Supported models Pick a model per request with the `model` field (default `veo-3.1-fast`). Veo credit costs come from Google's [official Flow credits table](https://support.google.com/flow/answer/16526234), the Omni ones are measured against the live API: | Model id | Tier / speed | Durations | Credits per video | |----------|--------------|-----------|------------------------| | `veo-3.1-lite` | Cheapest Veo | 4s, 6s, 8s | 10 (Non-Ultra) · 5 (Ultra) | | `veo-3.1-lite-low-priority` | Lite, lower priority | 4s, 6s, 8s | 0, plan owner on Ultra $199.99 only | | `veo-3.1-fast` *(default)* | Fast Veo | 4s, 6s, 8s | 20 (Non-Ultra) · 10 (Ultra) | | `veo-3.1-quality` | Highest-quality Veo | 8s only | 100 | | `omni-flash-1.2` | Omni 1.2 Flash, audio-native | 3s to 15s | 3 a second up to 10s, 6 a second above (at 720p) | | `omni-flash` | Omni 1.1 Flash, audio-native | 4s, 6s, 8s, 10s | 7 / 10 / 12 / 15 (by length, at 720p) | On Veo, `4s` and `6s` videos need Ultra (see the [overview](/docs/api-google-flow-v1)). Google Flow also makes stills with the Nano Banana models through the separate [POST /images](/docs/api-google-flow-v1/post-google-flow-images) endpoint. ### Pricing Each video spends Flow credits from your Google AI subscription, with no per-video charge from useapi.net. The price per video on every plan, against the official API, is in the [Google Flow price table](/docs/api-google-flow-v1#pricing), and [Veo 3.1 API pricing](/docs/articles/veo-3-1-api-pricing) covers Veo in detail. ### Generate a video in two API calls You need a useapi.net [API token](/docs/start-here/setup-useapi) and a connected [Google Flow account](/docs/start-here/setup-google-flow). Video jobs are asynchronous: pass `async: true` and the create call returns a `jobid` immediately, then you poll until the video is ready. 1. Submit the job — `POST https://api.useapi.net/v1/google-flow/videos`: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A serene mountain landscape at sunset, camera slowly panning right", "model": "veo-3.1-fast", "aspectRatio": "landscape", "duration": 8, "async": true }' ``` In async mode the response returns immediately with `201 Created`, a lowercase `jobid`, and `status: "created"`: ```json { "jobid": "j1731859234567v-u12345-email:jo***@gmail.com-bot:google-flow", "type": "video", "status": "created", "created": "2026-06-15T12:34:56.789Z", "request": { "async": true, "prompt": "A serene mountain landscape at sunset, camera slowly panning right", "model": "veo-3.1-fast", "aspectRatio": "landscape", "duration": 8 } } ``` 2. Poll for the result — `GET https://api.useapi.net/v1/google-flow/jobs/{jobId}`: ```bash curl "https://api.useapi.net/v1/google-flow/jobs/{jobId}" \ -H "Authorization: Bearer $USEAPI_TOKEN" ``` `status` moves through `created` → `started` → `completed`. When it reaches `completed`, the finished MP4 is in `response.media[].videoUrl` (a single prompt with `count > 1` returns one entry per video): ```json { "jobid": "j1731859234567v-...", "type": "video", "status": "completed", "response": { "media": [ { "mediaGenerationId": "user:12345-email:6a6f...-video:a1d95d21-...", "videoUrl": "https://flow-content.google/video/a1d95d21-...?Expires=...", "thumbnailUrl": "https://flow-content.google/image/a1d95d21-...?Expires=..." } ], "remainingCredits": 18760 } } ``` Veo 3.1 typically finishes in 60–180 seconds depending on model and mode. In our runs on October 20, 2026, nine 8-second videos took 50 to 105 seconds from submit to the finished MP4 ([measured runs](/docs/articles/veo-3-1-api-pricing#examples)). The signed `videoUrl` is valid for about 6 hours, so download promptly. Prefer not to poll? Pass a `replyUrl` in the create body to receive a webhook callback when the job completes. ### Image-to-video and reference-to-video Veo takes image inputs two different ways. Upload each image first with [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email) (raw bytes, an image `Content-Type`, PNG/JPEG/WebP up to 20 MB). The upload response nests the id at `mediaGenerationId.mediaGenerationId` — that nested string is what you pass back. When you supply any image input you can omit `email`: the request routes to the account where the image was uploaded. #### First / last frame (I2V) Your image becomes a literal frame of the video. Pass it as `startImage` to start from that frame: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Brave Captain Cat chasing away the pirates!", "model": "veo-3.1-fast", "aspectRatio": "portrait", "startImage": "user:12345-email:6a6f...-image:ff9aa5cc-...", "async": true }' ``` Add `endImage` (a second uploaded reference id) to pin the last frame so Veo generates the transition between the two. `endImage` requires `startImage` — end-frame-only is not supported. The Omni models (`omni-flash-1.2`, `omni-flash`) accept the same pair, but there the two frames are the only input it takes — no `referenceImage_*`, `character_*`, or `referenceAudio_*` alongside them. #### Reference images (R2V) Your images guide the whole video — subject, character, or style — rather than a specific frame. Pass `referenceImage_1` through `referenceImage_3` (Veo accepts up to 3, on 8-second videos only, and not on `veo-3.1-quality`). R2V cannot be combined with `startImage`/`endImage`: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A lady says to the dog, \"Say meow meow meow.\" The dog looks at the lady with a surprised, frustrated look and woofs in a human voice, \"What the heck lady?!\"", "model": "veo-3.1-fast", "aspectRatio": "portrait", "referenceImage_1": "user:12345-email:6a6f...-image:abcde-...", "async": true }' ``` Mention each reference inline with an `@referenceImage_N` marker in the prompt, add a `referenceAudio_1` (a system voice name like `Zephyr`) for narration, or pass a reusable [character](/docs/api-google-flow-v1/post-google-flow-characters) as `character_1` (it drives the same R2V mode and counts toward the 3-reference budget). Omni 1.2 Flash takes references further — up to 10, plus video-to-video editing and synced voices — see the [Omni Flash tutorial](/docs/articles/omni-flash-bash). ### Batch-generate with a script Finding the right shot takes many attempts, and running them by hand is tedious. The Node.js script below reads a list of prompts from `prompts.json`, uploads any start/end frame images, submits each job in async mode, then polls and downloads every finished MP4 — so you can queue a batch and come back to the winners. You need [Node.js](https://nodejs.org) v21 or newer. Put `prompts.json` and `google-flow.mjs` in the same folder and run `node ./google-flow.mjs API_TOKEN EMAIL`, where `API_TOKEN` is your useapi.net [API token](/docs/start-here/setup-useapi) and `EMAIL` is your connected [Google Flow account](/docs/start-here/setup-google-flow) email. The script looks the account up by email automatically and checks its `health` field before submitting. Prefer to clone and run it locally? The complete `google-flow.mjs` and `prompts.json` are on GitHub in [`useapi/google-flow-api`](https://github.com/useapi/google-flow-api/tree/main/veo-video). <details markdown="block"> <summary>Expand `prompts.json`</summary> ```json [ { "prompt": "By default the veo-3.1-fast model with a landscape 8-second clip will be used." }, { "model": "veo-3.1-quality", "aspectRatio": "landscape", "duration": 8, "count": 2, "prompt": "Highest-quality Veo 3.1, two variations. For all parameters see https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos" }, { "model": "veo-3.1-fast", "aspectRatio": "portrait", "duration": 8, "startImage": "./first_image.jpeg", "endImage": "./last_image.jpeg", "prompt": "Image-to-video with a start frame (startImage) and an end frame (endImage). Supported by Veo and by both Omni models." }, { "model": "omni-flash", "duration": 10, "prompt": "Gemini Omni Flash is audio-native and supports 10-second clips. Other models (veo-3.1-lite, veo-3.1-lite-low-priority, …) are selectable via the model field — see the POST /videos docs." } ] ``` </details> <details markdown="block"> <summary>Expand `google-flow.mjs` script</summary> ```javascript /* Script version 1.1, September 11, 2026 Script to batch-generate videos using prompts with the Google Flow API v1 by useapi.net 🚀 Uses the POST /videos endpoint in async mode (default model: veo-3.1-fast) and polls GET /jobs/{jobId}. For more details visit https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos Installation Instructions: ========================== You need Node.js v21 or newer installed to run this script. Download and install Node.js from: - Windows, macOS, Linux: https://nodejs.org/ After installation, verify by running the following command in a terminal: node -v Running the Script: =================== Usage: node google-flow.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE] Replace API_TOKEN with your actual useapi.net API token, see https://useapi.net/docs/start-here/setup-useapi Replace EMAIL with configured Google Flow email account, see https://useapi.net/docs/start-here/setup-google-flow If optional PROMPTS_FILE not provided prompts.json will be used. Example: -------- node google-flow.mjs user:1234-abcdefhijklmnopqrstuv my@email.com This command executes the script using API token user:1234-abcdefhijklmnopqrstuv with my@email.com Google Flow account email. Changelog: ========== - June 15, 2026: Initial release. - September 11, 2026: Accepts .jpg and upper-case image extensions for startImage and endImage. A prompt whose startImage or endImage fails to upload is skipped and logged to google-flow_errors.txt instead of being submitted without that frame. Saves a downloaded video under its final name only once it has been fully received, so a failed download leaves no partial MP4 for the next run to skip as "already exists". */ import readline from 'node:readline'; import fs from 'fs/promises'; import path from 'path'; import { writeFile } from 'node:fs/promises'; import { Readable } from 'node:stream'; // Constants const RESULTS_FILE = 'google-flow_results.txt'; const ERRORS_FILE = 'google-flow_errors.txt'; const DEFAULT_PROMPTS_FILE = 'prompts.json'; const DEFAULT_MODEL = 'veo-3.1-fast'; const SLEEP_429 = 30 * 1000; // in milliseconds const SLEEP_POLL = 15 * 1000; // in milliseconds const urlAccounts = 'https://api.useapi.net/v1/google-flow/accounts'; const urlVideos = 'https://api.useapi.net/v1/google-flow/videos'; const urlJobs = 'https://api.useapi.net/v1/google-flow/jobs/'; const urlUploadAsset = 'https://api.useapi.net/v1/google-flow/assets/'; // To upload .webp keep its .webp extension — Google Flow accepts png, jpeg and webp. const supportedFileExtensions = ['png', 'jpg', 'jpeg', 'webp']; // { filename: mediaGenerationId } const uploadedFiles = {}; // Utility to sleep for given milliseconds const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); // Function to fetch configured Google Flow API accounts async function fetchAccounts(apiToken) { const response = await fetch(urlAccounts, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.error(`⛔ Error fetching accounts (HTTP ${response.status}): ${response.statusText}`); process.exit(1); } return response.json(); } const elapsedTimeSec = (start) => (Date.now() - start) / 1000; // Map a file extension to the Content-Type required by POST /assets const contentTypeForExt = (ext) => ext === 'png' ? 'image/png' : ext === 'webp' ? 'image/webp' : 'image/jpeg'; async function uploadAsset(apiToken, email, filename) { // Check if already uploaded if (uploadedFiles.hasOwnProperty(filename)) return uploadedFiles[filename]; const startTime = Date.now(); console.log(`⬆️ Account ${email} uploading file…`, filename); const body = new Blob([await fs.readFile(filename)]); const fileExt = filename.split('.').pop().toLowerCase(); const response = await fetch(`${urlUploadAsset}${encodeURIComponent(email)}`, { method: 'POST', headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}`, 'Content-Type': contentTypeForExt(fileExt) }, body }); if (response.ok) { const json = await response.json(); // POST /assets returns the reference id nested as mediaGenerationId.mediaGenerationId const mediaGenerationId = json?.mediaGenerationId?.mediaGenerationId; console.log(`🆗 mediaGenerationId (${elapsedTimeSec(startTime)} sec)`, mediaGenerationId); uploadedFiles[filename] = mediaGenerationId; } else { console.error(`❗ Unable to upload file HTTP ${response.status} (${elapsedTimeSec(startTime)} sec)`, await response.text()); // Do not attempt to upload failed file again uploadedFiles[filename] = undefined; } return uploadedFiles[filename]; } async function submit(apiToken, url, body, index, prompt) { const createResponse = await fetch(url, { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiToken}` }, body }); const createBody = await createResponse.text(); // Async POST /videos returns 201 Created with a jobid to poll. if (createResponse.status == 201) { const json = JSON.parse(createBody); // 201 async payload uses lowercase "jobid"; sync 200 uses "jobId". Accept either. const jobId = json.jobid ?? json.jobId; if (jobId) { await fs.appendFile(RESULTS_FILE, `${jobId},#${index}:${prompt}\n`); console.log(`✅ jobId`, jobId); return 201; } else { const error = `No jobid found in HTTP 201 response`; console.log(`❓ ${error}`, createBody); await fs.appendFile(ERRORS_FILE, `${error},#${index}:${prompt}\n`); return 500; } } else { switch (createResponse.status) { case 429: console.log(`🔄️ Retry on HTTP ${createResponse.status}`, createBody); break; case 503: console.log(`🔄️ Service unavailable, retry on HTTP ${createResponse.status}`, createBody); break; case 400: console.log(`🛑 Rejected request (validation or content policy)`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${prompt}\n`); break; case 402: console.log(`🛑 No subscription / insufficient credits`, createBody); break; default: console.log(`❗ FAILED with HTTP ${createResponse.status}`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${prompt}\n`); } return createResponse.status; } } // Submit a single prompt to POST /videos in async mode. // startImage = start frame (I2V), endImage = end frame (I2V-FL, requires startImage). async function submitVideo(apiToken, email, prompt, index) { const { model, prompt: text, startImage, endImage, aspectRatio, duration, count } = prompt; const useModel = model ?? DEFAULT_MODEL; console.log(`🚀 ${useModel} » Prompt #${index} • account ${email} …`); const startImageId = startImage ? await uploadAsset(apiToken, email, startImage) : undefined; const endImageId = endImage ? await uploadAsset(apiToken, email, endImage) : undefined; // A frame that failed to upload would be left out of the body, and the prompt would still be // generated (and charged) without it. Skip the prompt instead. uploadAsset remembers the failed file, // so a later prompt using it is skipped too, without another upload attempt. const failedUploads = [['startImage', startImage, startImageId], ['endImage', endImage, endImageId]] .filter(([, file, id]) => file && !id); for (const [param, file] of failedUploads) { console.error(`🛑 Prompt #${index} skipped: ${param} ${file} failed to upload`); await fs.appendFile(ERRORS_FILE, `Upload failed for ${param} ${file},#${index}:${text}\n`); } if (failedUploads.length) return; const body = JSON.stringify({ model: useModel, email, prompt: text, aspectRatio, duration, count, startImage: startImageId, endImage: endImageId, async: true }); return await submit(apiToken, urlVideos, body, index, text); } // Function to download videos async function download(apiToken) { if (! await fileExists(RESULTS_FILE)) return; try { const resultsContent = await fs.readFile(RESULTS_FILE, 'utf8'); const lines = resultsContent.trim().split('\n'); for (const line of lines) { const [jobId, prompt] = line.split(','); console.log(`👉 ${jobId}`); while (true) { const response = await fetch(`${urlJobs}${jobId}`, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.log(`🛑 Poll failed ${jobId} (HTTP ${response.status}):\n${prompt}\n`, await response.text()); break; } const jobBody = await response.json(); const { status, error, response: jobResponse } = jobBody; if (status == 'failed') { console.error(`🛑 FAILED ${jobId} (${error}):\n${prompt}\n`); break; } if (status == 'completed') { const media = jobResponse?.media ?? []; if (media.length == 0) console.error(`🛑 Completed but no media for ${jobId}:\n${prompt}\n`); // A single prompt with count > 1 returns multiple videos. for (let i = 0; i < media.length; i++) { const url = media[i]?.videoUrl; const videoFilename = `${jobId.replace(/[:*]/g, '_')}_${i + 1}.mp4`; try { await fs.access(videoFilename); console.log(`⚠️ ${videoFilename} already exists. Skipping download.`); continue; } catch { // File does not exist, proceed with downloading } if (url) { console.log(`✅ Downloading ${url} to ${videoFilename}`); // Stream into a temporary file and rename it once the whole video has arrived, so a download // that drops mid-stream leaves no partial file behind for the next run to skip as "already exists". const tempFilename = `${videoFilename}.part`; try { const videoResponse = await fetch(url); if (!videoResponse.ok) { console.error(`⛔ Unable to download ${jobId} (HTTP ${videoResponse.status}):\n${prompt}\n`, url); continue; } const stream = Readable.fromWeb(videoResponse.body); await writeFile(tempFilename, stream); await fs.rename(tempFilename, videoFilename); } catch (err) { await fs.rm(tempFilename, { force: true }); console.error(`⛔ Error during download: ${err}`); } } else console.error(`🛑 No videoUrl for ${jobId} media #${i + 1}:\n${prompt}\n`); } break; } console.log(`⌛ ${jobId} status (${status}) and is still in progress, waiting…`); await sleep(SLEEP_POLL); } } } catch (error) { console.log(`⛔ Error during download:`, error.stack || error); } } // Main function async function main() { const apiToken = process.argv[2]; const email = process.argv[3]; const promptFile = process.argv[4] || DEFAULT_PROMPTS_FILE; if (!apiToken || !email) { console.error('Usage: node google-flow.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE]'); process.exit(1); } console.info('Script v1.1'); console.info('Node version is: ' + process.version); try { if (await fileExists(RESULTS_FILE)) { let user_input; while (!['y', 'n'].includes(user_input)) { user_input = (await promptUser(`❔ ${RESULTS_FILE} file detected. Do you want to download the results now? (y/n): `))?.toLowerCase(); if (user_input == 'y') { await download(apiToken); await fs.unlink(RESULTS_FILE); } } } const start = new Date(); try { console.info('START EXECUTION', start); await execute(apiToken, email, promptFile); // Pass the promptFile to execute function } finally { console.info('COMPLETED', new Date()); console.info('EXECUTION ELAPSED', diffInMinutesAndSeconds(start, new Date())); } try { console.info('START DOWNLOAD', start); await download(apiToken); } finally { console.info('TOTAL ELAPSED', diffInMinutesAndSeconds(start, new Date())); } } catch (error) { console.error('⛔ Error during execution:', error.stack || error); } } // Modify the execute function to accept promptFile as a parameter async function execute(apiToken, email, promptFile) { const accounts = await fetchAccounts(apiToken); console.info(`Configured Google Flow API accounts (${Object.keys(accounts).length}):`, Object.keys(accounts).join(', ')); if (Object.keys(accounts).length <= 0) { console.error(`⛔ No configured Google Flow accounts found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (!accounts[email]) { console.error(`⛔ Account ${email} not found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (accounts[email].health && accounts[email].health !== 'OK') { console.error(`⛔ Account ${email} health is '${accounts[email].health}'. Please resolve and update the account, see https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } const promptData = await fs.readFile(promptFile, 'utf8'); const prompts = JSON.parse(promptData); console.log(`Total number of prompts to process`, prompts.length); let warnings = []; // Parameters accepted by this script for the POST /videos endpoint. // See https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos for every model's full parameter set. const supportedParams = ['model', 'prompt', 'startImage', 'endImage', 'aspectRatio', 'duration', 'count']; const invalidKeys = (prompt) => Object.keys(prompt).filter(key => !key.startsWith('__') && !supportedParams.includes(key)) for (let i = 1; i <= prompts.length; i++) { const prompt = prompts[i - 1]; const { prompt: text, startImage, endImage } = prompt; const validateImage = async (file) => { if (file) { try { await fs.access(file); } catch { warnings.push(`⚠️ Image '${file}' does not exist. Prompt ${i}`); } const ext = file.split('.').pop().toLowerCase(); if (!supportedFileExtensions.includes(ext)) warnings.push(`⚠️ Image ${file} extension ${ext} not supported. Prompt ${i}`); } }; const notSupported = invalidKeys(prompt); if (notSupported.length) warnings.push(`⚠️ Following params not supported: ${notSupported.join(',')}. Prompt ${i}`); if (!text) warnings.push(`⚠️ prompt is required. Prompt ${i}`); if (endImage && !startImage) warnings.push(`⚠️ endImage requires startImage (end-frame-only is not supported). Prompt ${i}`); await Promise.all([validateImage(startImage), validateImage(endImage)]); } if (warnings.length > 0) { warnings.forEach(warning => console.warn(warning)); console.error(`⛔ Execution stopped due to warnings.`); process.exit(1); } for (let i = 0; i < prompts.length; i++) { const prompt = prompts[i]; while (true) { const responseCode = await submitVideo(apiToken, email, prompt, i + 1); if (responseCode == 429 || responseCode == 503) await sleep(SLEEP_429); else if (responseCode == 402) { process.exit(1); } else break; } } } // Utility function to check if a file exists async function fileExists(path) { try { await fs.access(path); return true; } catch { return false; } } // Function to prompt user input async function promptUser(query) { const rl = readline.createInterface({ input: process.stdin, output: process.stdout }); return new Promise((resolve) => rl.question(query, answer => { rl.close(); resolve(answer); })); } function diffInMinutesAndSeconds(date1, date2) { const diffInSeconds = Math.floor((date2 - date1) / 1000); return `${Math.floor(diffInSeconds / 60)} minutes ${diffInSeconds % 60} seconds`; }; main(); ``` </details> ### Examples Real Veo 3.1 videos made through this Google Flow API, taken straight from our release notes. ###### veo-3.1-fast » Brave Captain Cat chasing away the pirates (image-to-video) From [Google Flow API v1: Initial Release](/blog/251117). Animated from a Nano Banana still passed as `startImage`. <video poster="https://media.useapi.net/blog/2025-11-17-251117/veo-3-1-fast-poster.jpg" src="https://media.useapi.net/blog/2025-11-17-251117/veo-3-1-fast.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> ###### veo-3.1-fast » Lady and her dog, with AI voice narration From [Veo 3.1 Lite and Voice Narration](/blog/260403). Reference-to-video with the `referenceAudio_1: "Zephyr"` preset adding spoken dialogue. <video poster="https://media.useapi.net/blog/2026-04-03-260403/veo-3-1-fast-voice-zephyr-poster.jpg" controls width="100%" style="max-width:400px"> <source src="https://media.useapi.net/blog/2026-04-03-260403/veo-3-1-fast-voice-zephyr.mp4" type="video/mp4"> </video> ###### veo-3.1-fast » Dancing cha-cha (portrait reference-to-video) From [Veo 3.1 Portrait R2V](/blog/260113). Portrait R2V from a single reference image. <video poster="https://media.useapi.net/blog/2026-01-13-260113/dancing-cha-cha-poster.jpg" src="https://media.useapi.net/blog/2026-01-13-260113/dancing-cha-cha.mp4" style="width: 100%; max-width: 400px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> ### Frequently asked questions - **Is there a Veo 3.1 API?** Through useapi.net, yes: the [Google Flow API](/docs/api-google-flow-v1) runs Veo 3.1 Quality, Fast and Lite over REST on your Google Flow website subscription (Google AI Pro or Ultra). An 8-second Veo 3.1 Quality video costs $0.80 on Google AI Ultra $199.99, against $3.20 on the official Veo API (as of November 2026). - **What's the difference between Veo 3.1 Quality, Fast, and Lite?** Through useapi.net you pick one per request with the `model` field. `veo-3.1-quality` gives the highest fidelity, `veo-3.1-fast` is the default balance of speed and quality, and `veo-3.1-lite` is the cheapest: $0.04 a video on Google AI Ultra $199.99, against $0.40 on the official Veo API. On that plan, `veo-3.1-lite-low-priority` costs $0, about 1,000 or more videos a day (as of November 2026). - **Can I do image-to-video with Veo?** Through useapi.net, yes. Upload your start frame with [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email), then pass the returned reference id (nested at `mediaGenerationId.mediaGenerationId`) as `startImage`, and optionally `endImage` to pin the last frame (it requires `startImage`). To guide the subject or style instead of a frame, pass up to three `referenceImage_N`. See [Image-to-video](#image-to-video-and-reference-to-video) above. - **Do I need to solve a captcha?** Through useapi.net you never solve one yourself. Google Flow asks for a reCAPTCHA on every video, and the useapi.net worker solves it automatically: your first Google Flow account comes with 300 free solves on our own AntiCaptcha, CapSolver and EzCaptcha keys, and after that you add your own provider keys with [POST /accounts/captcha-providers](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers). The script in this guide sends no `captchaToken`. - **Do I need a Veo 3.1 API key?** Through useapi.net you need no Google API key and no Google Cloud project: one useapi.net [API token](/docs/start-here/setup-useapi) calls Veo 3.1, and you connect your Google account once through the [automated setup](/docs/start-here/setup-google-flow). Google Flow itself has no public API, and once the Gemini API's Veo 3.1 Preview models shut down on October 22, 2026, Google's own Veo API needs a Cloud project with billing. ### Conclusion Visit our <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> or <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> for any support questions and concerns. Check our [GitHub repo](https://github.com/useapi/google-flow-api) with code examples. #### Cross posted Also published on [dev.to](https://dev.to/useapi/how-to-generate-ai-video-with-veo-31-via-the-google-flow-api-2g4i){:rel="nofollow"}. === URL: https://useapi.net/docs/articles/google-flow-errors === Document URL: https://useapi.net/docs/articles/google-flow-errors --- layout: default title: "Google Flow Errors Explained: Upscaling Failed, PUBLIC_ERROR_UNUSUAL_ACTIVITY and Unsafe Generation" description: "Why Google Flow says Upscaling failed, PUBLIC_ERROR_UNUSUAL_ACTIVITY, PUBLIC_ERROR_UNSAFE_GENERATION or PUBLIC_ERROR_AUDIO_FILTERED, what each means, and how to fix it." keywords: [Google Flow upscaling failed, Flow upscale failed, PUBLIC_ERROR_UNUSUAL_ACTIVITY, PUBLIC_ERROR_UNUSUAL_ACTIVITY_TOO_MUCH_TRAFFIC, PUBLIC_ERROR_UNSAFE_GENERATION, PUBLIC_ERROR_AUDIO_FILTERED, AUDIO_GENERATION_FILTERED, Google Flow return silent videos, Google Flow error, Veo 3.1 error, reCAPTCHA evaluation failed, Google Flow API] image: https://media.useapi.net/blog/2025-11-20-251120/nano-banana-pro-text-to-image.jpg parent: Articles nav_exclude: true date: 2026-10-04 last_modified: 2026-11-20 nav_order: 897 --- ## Google Flow Errors Explained: Upscaling Failed, PUBLIC_ERROR_UNUSUAL_ACTIVITY and Unsafe Generation October 4, 2026 (November 20, 2026) ## Table of contents ### Introduction Google Flow's "Upscaling failed", `PUBLIC_ERROR_UNUSUAL_ACTIVITY` and `PUBLIC_ERROR_UNSAFE_GENERATION` mean, in turn, an upscale your plan or Google couldn't complete, a rejected reCAPTCHA check, and a safety-filter refusal, and `PUBLIC_ERROR_AUDIO_FILTERED` means Google blocked the sound generated with a video. This page explains each one and what to do, using what the [useapi.net Google Flow API](/docs/api-google-flow-v1) sees when the same requests run through it, where Google's response names the reason. ### "Upscaling failed" Flow shows "Upscaling failed" when an upscale did not finish. Through the API, failed upscales come down to these causes, in order of how easy they are to check: 1. The plan doesn't include that upscale. 4K needs [Google AI Ultra](https://one.google.com/ai) for both videos and images. Other paid plans upscale videos to 720p or 1080p, and free accounts cannot upscale videos at all. Images upscale to 2K on every plan, including free. For videos up to 10 seconds, 720p and 1080p are free and 4K costs 50 credits, and each second above 10 adds 1 credit (5 for 4K). Image upscales are free. 1. The video is longer than 15 seconds, such as an [extended](/docs/api-google-flow-v1/post-google-flow-videos-extend) clip. Google upscales videos of up to 15 seconds, and the API refuses a longer one with `400` before any captcha is solved. 2. Google's reCAPTCHA check rejected the request. Upscales go through the same check as videos and images, so the next section applies here too. Nothing is created and no credits are used, and you can retry right away. 3. A temporary error on Google's side. Retry once. If an earlier upscale of the same video succeeded, upscaling it again returns that cached result at no extra credits. If every video upscale fails on one account, check that it has a paid Google AI subscription. ### PUBLIC_ERROR_UNUSUAL_ACTIVITY `PUBLIC_ERROR_UNUSUAL_ACTIVITY` means Google's reCAPTCHA check did not trust the request. Google checks before it starts generating, so nothing was created and no Flow credits were used. You can try again right away. Our data points to the Google account more than to the captcha solver. Google gives each account its own trust level. Through the API, a trusted account gets about 9 in 10 checks accepted and a distrusted one about 3 in 10, whatever solves the captcha. A related code, `PUBLIC_ERROR_UNUSUAL_ACTIVITY_TOO_MUCH_TRAFFIC`, arrives as HTTP `429` and Google's message reads "reCAPTCHA evaluation failed". It means the same thing. What helps: - Check which accounts fail with [GET /accounts/captcha-stats](/docs/api-google-flow-v1/get-google-flow-accounts-captcha-stats), which also shows which providers fail. If one account keeps failing while others work, Google has flagged it: leave out `email` so the API picks another account, or rest it, and replace it if it stays low for more than a day or two. - If every account drops at the same time, the captcha solver is the likely cause. Use several providers: the API ranks them by how often Google accepts each one and gives most tries to the best of them. - Keep `captchaRetry` at the default 5. With 1 or 2 tries, a request fails as soon as one or two captchas are rejected. - Spread the work over more than one Google account if you have several. ### PUBLIC_ERROR_UNSAFE_GENERATION `PUBLIC_ERROR_UNSAFE_GENERATION` means Google's safety filters refused the prompt or the result. It is not an account problem. Google names related refusals with similar codes: - `PUBLIC_ERROR_PROMINENT_PEOPLE_FILTER_FAILED`: a real, recognizable person. - `PUBLIC_ERROR_MINOR`, `PUBLIC_ERROR_SEXUAL`, `PUBLIC_ERROR_DANGER_FILTER`: the content categories they name. - `PUBLIC_ERROR_AUDIO_FILTERED`: the sound generated with the video was blocked. This one is common and has its own fix, see [below](#public_error_audio_filtered). - `PUBLIC_ERROR_IP_INPUT_IMAGE`: an input image looked like protected content. - `PUBLIC_ERROR_SPEECH_EDIT`: a video edit refused because of the speech in the clip, most likely an edit that changes what someone says. Keep the dialogue as it is, or edit a clip without speech. Apart from `PUBLIC_ERROR_AUDIO_FILTERED`, retrying the same prompt usually fails again. Rephrase the part that tripped the filter, replace the reference image, or remove the real person's name. The list is Google's and grows over time, so match on substrings rather than an exact list. Not every `PUBLIC_ERROR_` code is about content: `PUBLIC_ERROR_MODEL_ACCESS_DENIED` means the plan lacks the model, `PUBLIC_ERROR_USER_MINOR` means Google treats the Google account as belonging to someone under 18 (Flow refuses such accounts whatever you send), and `USER_QUOTA_REACHED`, `USER_REQUESTS_THROTTLED` and `PER_MODEL_DAILY_QUOTA_REACHED` are account limits. ### PUBLIC_ERROR_AUDIO_FILTERED `PUBLIC_ERROR_AUDIO_FILTERED`, usually with the label `AUDIO_GENERATION_FILTERED`, means the picture was fine but Google rejected the sound it generated with it. Every Veo and Omni video comes with sound, even for a prompt without dialogue, and Google checks that sound with a separate audio filter. When the filter says no, Flow fails the whole video by default and charges no credits for it. It is the most common failure on `veo-3.1-lite` and the second most common on `veo-3.1-lite-low-priority`: about 1 in 5 `veo-3.1-lite` videos and 1 in 12 `veo-3.1-lite-low-priority` videos fail this way, about 1 in 25 on `veo-3.1-fast`, and fewer than 1 in 100 on the Omni models. What to do: - If the video can do without its sound (b-roll, backgrounds, clips you put music on later), switch on "Return silent videos" in Flow's settings (under the gear icon at the top right, shown on some accounts only). Such a video then comes back without sound instead of failing, and is charged like any other. Through the [useapi.net Google Flow API](/docs/api-google-flow-v1), send `returnSilentVideos: true` on [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos#silent-videos) or [POST /videos/extend](/docs/api-google-flow-v1/post-google-flow-videos-extend), on any account. - If you need the sound, generate again: each attempt makes new sound, so the filter judges it anew. - The Omni models (Omni 1.2 Flash, Omni 1.1 Flash) hardly ever fail this way. ### If you automate Google Flow Running Flow from code with the [useapi.net Google Flow API](/docs/api-google-flow-v1) handles most of this for you: - Rejected captchas are retried with a fresh captcha, up to 5 times by default (`captchaRetry`). You only get a `403` or `429` back when every try was refused. The error starts with `captcha_quality:` so your code can tell it apart from other failures. - When you leave out `email` and have several Google accounts connected, accounts whose captchas Google has been rejecting get less of the new work. [GET /accounts/captcha-stats](/docs/api-google-flow-v1/get-google-flow-accounts-captcha-stats) shows each account's acceptance rate. - Content refusals come back either as an immediate `400` that names the reason, or, for a video that fails while generating, in `failureReasons` on the job, so you can show the user what to change. Some failures arrive with no reason at all, and those are usually worth one retry. - A video whose sound Google's audio filter rejects comes back without sound instead of failing when you send `returnSilentVideos: true`, per request and on any account. - An upscale the account's plan doesn't include (4K without Ultra, or any video upscale on a free account) is refused with a `400` before a captcha is solved, so it costs nothing. - An account Google treats as under 18 gets a `403` that says so, after one try instead of five. An image upload to it costs no captcha at all. With `email` left out, the account is set aside for an hour so other accounts take the work. The [Veo 3.1 tutorial](/docs/articles/google-flow-bash) shows a full video request in `curl`, and the [n8n UGC ad template](/docs/articles/google-flow-n8n-ugc-ads) shows retries and refusals handled in a no-code workflow. ### Frequently asked questions **Does a failed video use Flow credits?** Through useapi.net, a `PUBLIC_ERROR_UNUSUAL_ACTIVITY` failure costs nothing, because Google checks the captcha before it starts generating, and an upscale the plan doesn't include is refused with a `400` before any captcha is solved. A video that fails on its sound (`PUBLIC_ERROR_AUDIO_FILTERED`) costs nothing either, as Flow's own settings state, while one returned silent with `returnSilentVideos: true` is charged. For other failures, compare the account's credit balance before and after (`remainingCredits` on the finished job) if you need to be sure. **Why does it work on the Flow website but fail in my script?** Through useapi.net, as in any script, the reCAPTCHA token comes from a captcha-solving service, while on the website it comes from your own signed-in browser, and Google trusts solver tokens less. The account's own trust level applies to both, so an account that keeps failing through the API is worth resting or replacing. **Is there an official Google Flow API?** Through useapi.net you call Google Flow from code with a third-party REST API on your Google Flow website subscription, because Google offers no public Flow API. An 8-second Veo 3.1 Fast video costs $0.08 on Google AI Ultra $199.99, against $0.80 on Google's Cloud [Agent Platform](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing), Google's own Veo API since the Gemini API's Veo 3.1 Preview models shut down on October 22, 2026 (as of November 2026). ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-flow-images-bash-es === Document URL: https://useapi.net/docs/articles/google-flow-images-bash-es --- layout: default title: "Cómo generar imágenes con Nano Banana 2.1 y Nano Banana Pro mediante la Google Flow API" description: "Genera imágenes con Nano Banana 2.1, Nano Banana Pro y Nano Banana 2 Lite con un solo POST síncrono en la Google Flow API de useapi.net, más un script por lotes en Node.js." keywords: [Nano Banana API, Nano Banana 2.1 API, Nano Banana 2 API, Nano Banana Pro API, Gemini 3.1 Flash Image, Gemini 3 Pro Image, Nano Banana 2 Lite, image-to-image, Google Flow API, API de Nano Banana, API de Nano Banana Pro, API de Google Flow, generar imágenes con IA, API de generación de imágenes, imagen a imagen, tutorial Nano Banana, código, curl] image: https://media.useapi.net/articles/2026-06-15-google-flow-images-bash/nano-banana-2-lite.jpg parent: Articles nav_exclude: true lang: es translation_key: google-flow-images date: 2026-06-15 last_modified: 2026-11-06 nav_order: 840 repo: https://github.com/useapi/google-flow-api --- ## Cómo generar imágenes con Nano Banana 2.1 y Nano Banana Pro mediante la Google Flow API {: .no_toc #how-to-generate-nano-banana-21--nano-banana-pro-images-via-the-google-flow-api } 6 min de lectura • 15 de junio de 2026 (6 de noviembre de 2026) useapi.net es una API de terceros. No está afiliada a Google ni cuenta con su respaldo. ## Índice {: .no_toc .text-delta #table-of-contents } ### Introducción Un solo `POST` síncrono a la [Google Flow API](/docs/api-google-flow-v1) de useapi.net devuelve hasta cuatro imágenes de Nano Banana 2.1, [Nano Banana Pro](https://deepmind.google/models/gemini-image/pro/) o [Nano Banana 2 Lite](https://deepmind.google/models/gemini-image/flash-lite/), hechas con tu cuenta de [Google Flow](https://flow.google.com). Las imágenes están incluidas en toda [suscripción de Google AI](https://gemini.google/subscriptions/), incluso en una cuenta gratuita, mientras que la Gemini API oficial cobra de US$0,034 a US$0,134 por imagen (a noviembre de 2026). No necesitas un proyecto de Google Cloud ni una clave de la Gemini API. Esta guía muestra los modelos disponibles, la diferencia de precio, el flujo de imagen en una sola llamada con `curl` listo para copiar y un script en Node.js que genera imágenes por lotes a partir de una lista de prompts. ¿Quieres ver cómo se comportan los tres modelos con el mismo prompt? Consulta la [comparación de los modelos Nano Banana](/docs/articles/google-flow-nano-banana-compare-es). ¿Necesitas video? Consulta el [tutorial de Veo 3.1](/docs/articles/google-flow-bash-es), la guía hermana de esta. ### Modelos compatibles Elige el modelo en cada solicitud con el campo `model` (por defecto `nano-banana-2-lite`). Los tres modelos funcionan con cualquier suscripción de Google AI, incluso en una cuenta gratuita. | Id del modelo | Nombre comercial | Referencias (I2I) | Proporciones | Notas | |----------|----------------|-----------------:|---------------|-------| | `nano-banana-2-lite` *(por defecto)* | Nano Banana 2 Lite / Gemini 3.1 Flash-Lite Image | máx. 10 | 16:9, 4:3, 1:1, 3:4, 9:16, auto<sup>†</sup> | Modelo de imagen por defecto de Google Flow desde julio de 2026. En el modo imagen a imagen se mantiene en 16:9, salvo que indiques una proporción | | `nano-banana-2` | Nano Banana 2.1 | máx. 10 | 16:9, 4:3, 1:1, 3:4, 9:16, auto<sup>†</sup> | Usa `auto` por defecto en el modo imagen a imagen | | `nano-banana-pro` | Nano Banana Pro / Gemini 3 Pro Image | máx. 10 | 16:9, 4:3, 1:1, 3:4, 9:16, auto<sup>†</sup> | El modelo de imagen de mayor calidad. Usa `auto` por defecto en el modo imagen a imagen | <sup>†</sup> `auto` solo vale en el modo imagen a imagen (con al menos un `reference_*` o `character_*`): el backend toma la proporción de la primera imagen de referencia. Con varias referencias la orientación no está garantizada, así que indica una proporción explícita cuando todas las imágenes deban volver con el mismo formato. Los tres aceptan `count` (1–4) y `seed` para reproducibilidad. Si omites `model`, la API usa `nano-banana-2-lite`, con o sin referencias. Dos alias obsoletos se siguen aceptando: `nano-banana` pasa a `nano-banana-2`, e `imagen-4` pasa a `nano-banana-2-lite` (Google quitó Imagen de Google Flow en julio de 2026). Los detalles y las funciones de cada modelo están en la referencia de [POST /images](/docs/api-google-flow-v1/post-google-flow-images). #### Upscale a 2K/4K Las imágenes generadas con cualquiera de los tres modelos admiten upscale con [POST /images/upscale](/docs/api-google-flow-v1/post-google-flow-images-upscale): indica el `mediaGenerationId` de la imagen y un `resolution` de `2k` (por defecto) o `4k`. La respuesta llega en base64 en `encodedImage`. `2k` funciona en cualquier plan, incluso en una cuenta gratuita. `4k` requiere Google AI Ultra, y en cualquier otro plan responde `400` con `4k upscaling is not available for this account` antes de resolver un captcha, así que no cuesta nada y no sirve de nada reintentar. Ninguno de los dos consume créditos de Flow. ### Precios Las imágenes no consumen créditos de Flow en ninguna suscripción de Google AI, incluso en una cuenta gratuita, y useapi.net no cobra nada por imagen. Solo necesitas un plan de pago para video con Omni 1.1 Flash, video con Omni 1.2 Flash de más de 10 segundos, extensiones con Omni 1.2 y upscale de video, y el upscale de imagen en `4k` requiere Ultra. El precio de cada modelo en cada plan, frente a la API oficial, está en la [tabla de precios de Google Flow](/docs/api-google-flow-v1#pricing). ### Cómo generar una imagen de Nano Banana con curl Necesitas un [token de API](/docs/start-here/setup-useapi) de useapi.net y una [cuenta de Google Flow](/docs/start-here/setup-google-flow) conectada. La generación de imágenes es síncrona: un solo `POST` espera hasta que las imágenes estén listas (normalmente de 10 a 20 segundos) y las devuelve en la respuesta, así que no hay `jobid` que consultar. El segundo paso es solo guardar el resultado, desde la URL firmada o, cuando no viene, desde la imagen en base64 incluida en la respuesta. 1. Envía el prompt — `POST https://api.useapi.net/v1/google-flow/images`: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/images" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Cat dressed like a pirate fencing with a real pirate, pirate looks absolutely terrified, this is happening on a deck of the Disney cruise ship", "model": "nano-banana-pro", "aspectRatio": "16:9", "count": 4, "seed": 123456 }' > response.json ``` La llamada devuelve `200 OK` con un `jobId` y un arreglo `media`, con un elemento por imagen (`count` va de 1 a 4, por defecto 4). La URL de descarga firmada de cada imagen está en `media[].image.generatedImage.fifeUrl`: ```json { "jobId": "j1731859345678i-u12345-email:jo***@gmail.com-bot:google-flow", "media": [ { "image": { "generatedImage": { "seed": 123456, "mediaGenerationId": "user:12345-email:6a6f...-image:...", "prompt": "Cat dressed like a pirate fencing with a real pirate, pirate looks absolutely terrified, this is happening on a deck of the Disney cruise ship", "fifeUrl": "https://flow-content.google/image/...", "aspectRatio": "IMAGE_ASPECT_RATIO_LANDSCAPE" } } } ] } ``` 2. Descarga la imagen desde `fifeUrl` (la URL firmada vale por tiempo limitado, así que descárgala pronto). A veces `fifeUrl` no viene y la imagen llega en base64 dentro de `encodedImage`. En ese caso, decodifica ese campo: ```bash URL=$(jq -r '.media[0].image.generatedImage.fifeUrl // empty' response.json) if [ -n "$URL" ]; then curl -o image_1.jpg "$URL" else jq -r '.media[0].image.generatedImage.encodedImage' response.json | base64 -d > image_1.jpg fi ``` El `mediaGenerationId` de cada imagen generada se puede reutilizar como referencia en una solicitud posterior. Consulta [Imágenes de referencia y personajes](#image-references--characters) más abajo. ¿Quieres también un webhook? Pasa un `replyUrl` en el cuerpo de la solicitud y la API también envía las actualizaciones de estado del job a esa URL. La llamada en sí sigue esperando las imágenes. El payload es igual a la respuesta de [GET /jobs/`jobId`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid), donde una imagen terminada está en `response.media[].image.generatedImage.fifeUrl`. ### Imágenes de referencia y personajes Para guiar una imagen con una foto que ya tienes, súbela primero con [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email) (bytes sin procesar, un `Content-Type` de imagen, PNG/JPEG/WebP de hasta 20 MB). La respuesta de la subida trae el id de la referencia anidado en `mediaGenerationId.mediaGenerationId`. Esa cadena anidada es la que devuelves como `reference_1` (cada uno de los tres modelos acepta hasta 10 referencias): ```bash # 1. Sube una imagen de referencia curl -X POST "https://api.useapi.net/v1/google-flow/assets/john%40gmail.com" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: image/jpeg" \ --data-binary @reference.jpeg # Respuesta: el id de la referencia viene anidado un nivel más abajo: # { # "mediaGenerationId": { # "mediaGenerationId": "user:12345-email:6a6f...-image:ff9aa5cc-..." # }, # "width": 1024, "height": 1024, "email": "jo***@gmail.com" # } # 2. Genera usando esa referencia curl -X POST "https://api.useapi.net/v1/google-flow/images" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model": "nano-banana-pro", "prompt": "Make this photograph look modern", "reference_1": "user:12345-email:6a6f...-image:ff9aa5cc-..." }' ``` Para mantener la misma identidad en muchas imágenes, junta 1–2 imágenes de referencia en un personaje reutilizable con [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters) y luego pasa su id `character` como `character_1`…`character_7`. Los personajes se combinan libremente con `reference_*` y comparten el mismo límite de referencias de cada modelo. También puedes poner marcadores `@reference_1` / `@character_1` directamente en el `prompt` para indicar dónde entra cada imagen. Cada marcador en el prompt necesita un parámetro correspondiente en el cuerpo. ### Genera por lotes con un script Llegar a la imagen correcta requiere muchos intentos, y hacer cada uno a mano cansa. El script en Node.js de abajo lee una lista de prompts de `prompts.json`, sube las imágenes de referencia, envía cada solicitud y descarga todas las imágenes devueltas. Así pones un lote en cola y vuelves después a elegir las mejores. Como `POST /images` es síncrono, el script guarda cada resultado en cuanto la llamada responde. Necesitas [Node.js](https://nodejs.org) v21 o posterior. Pon `prompts.json` y `google-flow-images.mjs` en la misma carpeta y ejecuta `node ./google-flow-images.mjs API_TOKEN EMAIL`, donde `API_TOKEN` es tu [token de API](/docs/start-here/setup-useapi) de useapi.net y `EMAIL` es el correo de tu [cuenta de Google Flow](/docs/start-here/setup-google-flow) conectada. El script encuentra la cuenta por el correo automáticamente y revisa el campo `health` antes de enviar. ¿Prefieres clonar y ejecutar en local? `google-flow-images.mjs` y `prompts.json` completos están en GitHub, en [`useapi/google-flow-api`](https://github.com/useapi/google-flow-api/tree/main/images). <details markdown="block"> <summary>Abrir `prompts.json`</summary> ```json [ { "prompt": "By default the nano-banana-2-lite model generates 4 image variations at 16:9." }, { "model": "nano-banana-pro", "aspectRatio": "1:1", "count": 2, "seed": 123456, "prompt": "Nano Banana Pro (Gemini 3 Pro Image), two square variations. For all parameters see https://useapi.net/docs/api-google-flow-v1/post-google-flow-images" }, { "model": "nano-banana-2", "aspectRatio": "auto", "reference_1": "./reference_image.jpeg", "prompt": "Image-to-image: pass a local reference file as reference_1 (uploaded automatically). auto aspect ratio derives from the first reference. All three models accept up to 10 references." }, { "model": "nano-banana-2-lite", "aspectRatio": "9:16", "count": 4, "prompt": "Nano Banana 2 Lite portrait. Other models (nano-banana-2, nano-banana-pro) are selectable via the model field — see the POST /images docs." } ] ``` </details> <details markdown="block"> <summary>Abrir el script `google-flow-images.mjs`</summary> ```javascript /* Script version 1.2, September 11, 2026 Script to batch-generate images using prompts with the Google Flow API v1 by useapi.net 🚀 Uses the synchronous POST /images endpoint (default model: nano-banana-2-lite) and saves each image from fifeUrl, or from encodedImage when fifeUrl is absent. For more details visit https://useapi.net/docs/api-google-flow-v1/post-google-flow-images Installation Instructions: ========================== You need Node.js v21 or newer installed to run this script. Download and install Node.js from: - Windows, macOS, Linux: https://nodejs.org/ After installation, verify by running the following command in a terminal: node -v Running the Script: =================== Usage: node google-flow-images.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE] Replace API_TOKEN with your actual useapi.net API token, see https://useapi.net/docs/start-here/setup-useapi Replace EMAIL with configured Google Flow email account, see https://useapi.net/docs/start-here/setup-google-flow If optional PROMPTS_FILE not provided prompts.json will be used. Example: -------- node google-flow-images.mjs user:1234-abcdefhijklmnopqrstuv my@email.com This command executes the script using API token user:1234-abcdefhijklmnopqrstuv with my@email.com Google Flow account email. Changelog: ========== - June 15, 2026: Initial release. - September 10, 2026: Default model is now nano-banana-2-lite (Google removed Imagen from Flow, and imagen-4 now maps to nano-banana-2-lite). Saves encodedImage when fifeUrl is absent, and accepts .jpg reference images. - September 11, 2026: A prompt whose reference_* file fails to upload is skipped and logged to google-flow-images_errors.txt instead of being submitted without that reference. Writes a downloaded image only once it has been fully received, so a failed download leaves no partial file for the next run to skip as "already exists". */ import fs from 'fs/promises'; import { writeFile } from 'node:fs/promises'; // Constants const ERRORS_FILE = 'google-flow-images_errors.txt'; const DEFAULT_PROMPTS_FILE = 'prompts.json'; const DEFAULT_MODEL = 'nano-banana-2-lite'; const SLEEP_429 = 30 * 1000; // in milliseconds const urlAccounts = 'https://api.useapi.net/v1/google-flow/accounts'; const urlImages = 'https://api.useapi.net/v1/google-flow/images'; const urlUploadAsset = 'https://api.useapi.net/v1/google-flow/assets/'; // Google Flow accepts png, jpeg and webp for reference images. const supportedFileExtensions = ['png', 'jpg', 'jpeg', 'webp']; // reference_1 .. reference_10 are accepted by POST /images. const referenceParams = Array.from({ length: 10 }, (_, i) => `reference_${i + 1}`); // { filename: mediaGenerationId } const uploadedFiles = {}; // Utility to sleep for given milliseconds const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); // Function to fetch configured Google Flow API accounts async function fetchAccounts(apiToken) { const response = await fetch(urlAccounts, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.error(`⛔ Error fetching accounts (HTTP ${response.status}): ${response.statusText}`); process.exit(1); } return response.json(); } const elapsedTimeSec = (start) => (Date.now() - start) / 1000; // Map a file extension to the Content-Type required by POST /assets const contentTypeForExt = (ext) => ext === 'png' ? 'image/png' : ext === 'webp' ? 'image/webp' : 'image/jpeg'; async function uploadAsset(apiToken, email, filename) { // Check if already uploaded if (uploadedFiles.hasOwnProperty(filename)) return uploadedFiles[filename]; const startTime = Date.now(); console.log(`⬆️ Account ${email} uploading file…`, filename); const body = new Blob([await fs.readFile(filename)]); const fileExt = filename.split('.').pop().toLowerCase(); const response = await fetch(`${urlUploadAsset}${encodeURIComponent(email)}`, { method: 'POST', headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}`, 'Content-Type': contentTypeForExt(fileExt) }, body }); if (response.ok) { const json = await response.json(); // POST /assets returns the reference id nested as mediaGenerationId.mediaGenerationId const mediaGenerationId = json?.mediaGenerationId?.mediaGenerationId; console.log(`🆗 mediaGenerationId (${elapsedTimeSec(startTime)} sec)`, mediaGenerationId); uploadedFiles[filename] = mediaGenerationId; } else { console.error(`❗ Unable to upload file HTTP ${response.status} (${elapsedTimeSec(startTime)} sec)`, await response.text()); // Do not attempt to upload failed file again uploadedFiles[filename] = undefined; } return uploadedFiles[filename]; } // Download a single image from its signed fifeUrl. async function downloadImage(url, filename) { try { await fs.access(filename); console.log(`⚠️ ${filename} already exists. Skipping download.`); return; } catch { // File does not exist, proceed with downloading } if (!url) { console.error(`🛑 No fifeUrl for ${filename}`); return; } console.log(`✅ Downloading ${url} to ${filename}`); try { const imageResponse = await fetch(url); if (!imageResponse.ok) { console.error(`⛔ Unable to download ${filename} (HTTP ${imageResponse.status})`, url); return; } // Read the whole body before creating the file, so a failed download leaves no // partial file behind for the next run to skip as "already exists". const data = Buffer.from(await imageResponse.arrayBuffer()); await writeFile(filename, data); } catch (err) { console.error(`⛔ Error during download: ${err}`); } } // Submit a single prompt to the synchronous POST /images endpoint and download the results. async function submitImage(apiToken, email, prompt, index) { const { model, prompt: text } = prompt; const useModel = model ?? DEFAULT_MODEL; console.log(`🚀 ${useModel} » Prompt #${index} • account ${email} …`); // Build the request body, uploading any local reference_* file to a mediaGenerationId first. const body = { model: useModel, email, prompt: text }; for (const key of ['aspectRatio', 'count', 'seed']) if (prompt[key] !== undefined) body[key] = prompt[key]; for (const refKey of referenceParams) { const value = prompt[refKey]; if (value) body[refKey] = await uploadAsset(apiToken, email, value); } // A reference that failed to upload would be left out of the body, and the prompt would still be // generated (and charged) without it. Skip the prompt instead. uploadAsset remembers the failed file, // so a later prompt using it is skipped too, without another upload attempt. const failedUploads = referenceParams.filter(refKey => prompt[refKey] && !body[refKey]); for (const refKey of failedUploads) { console.error(`🛑 Prompt #${index} skipped: ${refKey} ${prompt[refKey]} failed to upload`); await fs.appendFile(ERRORS_FILE, `Upload failed for ${refKey} ${prompt[refKey]},#${index}:${text}\n`); } if (failedUploads.length) return; while (true) { const response = await fetch(urlImages, { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiToken}` }, body: JSON.stringify(body) }); const responseText = await response.text(); if (response.status == 200) { const json = JSON.parse(responseText); const media = json?.media ?? []; if (media.length == 0) console.error(`🛑 200 OK but no media for prompt #${index}:\n${text}\n`); // count > 1 returns multiple images in the media array. for (let i = 0; i < media.length; i++) { const img = media[i]?.image?.generatedImage; const filename = `google-flow_${index}_${i + 1}.jpg`; // fifeUrl is normally present. When it is absent the image arrived inline as base64 in encodedImage. if (!img?.fifeUrl && img?.encodedImage) await fs.writeFile(filename, Buffer.from(img.encodedImage, 'base64')); else await downloadImage(img?.fifeUrl, filename); } return 200; } switch (response.status) { case 429: console.log(`🔄️ Retry on HTTP ${response.status}`, responseText); await sleep(SLEEP_429); break; case 503: console.log(`🔄️ Service unavailable, retry on HTTP ${response.status}`, responseText); await sleep(SLEEP_429); break; case 402: console.log(`🛑 No subscription / insufficient credits`, responseText); await fs.appendFile(ERRORS_FILE, `${response.status},#${index}:${text}\n`); process.exit(1); case 400: case 500: console.log(`🛑 Rejected (validation or content moderation)`, responseText); await fs.appendFile(ERRORS_FILE, `${response.status},#${index}:${text}\n`); return response.status; default: console.log(`❗ FAILED with HTTP ${response.status}`, responseText); await fs.appendFile(ERRORS_FILE, `${response.status},#${index}:${text}\n`); return response.status; } } } // Main function async function main() { const apiToken = process.argv[2]; const email = process.argv[3]; const promptFile = process.argv[4] || DEFAULT_PROMPTS_FILE; if (!apiToken || !email) { console.error('Usage: node google-flow-images.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE]'); process.exit(1); } console.info('Script v1.2'); console.info('Node version is: ' + process.version); const start = new Date(); try { console.info('START EXECUTION', start); await execute(apiToken, email, promptFile); } catch (error) { console.error('⛔ Error during execution:', error.stack || error); } finally { console.info('COMPLETED', new Date()); console.info('EXECUTION ELAPSED', diffInMinutesAndSeconds(start, new Date())); } } async function execute(apiToken, email, promptFile) { const accounts = await fetchAccounts(apiToken); console.info(`Configured Google Flow API accounts (${Object.keys(accounts).length}):`, Object.keys(accounts).join(', ')); if (Object.keys(accounts).length <= 0) { console.error(`⛔ No configured Google Flow accounts found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (!accounts[email]) { console.error(`⛔ Account ${email} not found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (accounts[email].health && accounts[email].health !== 'OK') { console.error(`⛔ Account ${email} health is '${accounts[email].health}'. Please resolve and update the account, see https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } const promptData = await fs.readFile(promptFile, 'utf8'); const prompts = JSON.parse(promptData); console.log(`Total number of prompts to process`, prompts.length); let warnings = []; // Parameters accepted by this script for the POST /images endpoint. // See https://useapi.net/docs/api-google-flow-v1/post-google-flow-images for every model's full parameter set. const supportedParams = ['model', 'prompt', 'aspectRatio', 'count', 'seed', ...referenceParams]; const invalidKeys = (prompt) => Object.keys(prompt).filter(key => !key.startsWith('__') && !supportedParams.includes(key)) for (let i = 1; i <= prompts.length; i++) { const prompt = prompts[i - 1]; const { prompt: text } = prompt; const validateImage = async (file) => { if (file) { try { await fs.access(file); } catch { warnings.push(`⚠️ Image '${file}' does not exist. Prompt ${i}`); } const ext = file.split('.').pop().toLowerCase(); if (!supportedFileExtensions.includes(ext)) warnings.push(`⚠️ Image ${file} extension ${ext} not supported. Prompt ${i}`); } }; const notSupported = invalidKeys(prompt); if (notSupported.length) warnings.push(`⚠️ Following params not supported: ${notSupported.join(',')}. Prompt ${i}`); if (!text) warnings.push(`⚠️ prompt is required. Prompt ${i}`); await Promise.all(referenceParams.map(refKey => validateImage(prompt[refKey]))); } if (warnings.length > 0) { warnings.forEach(warning => console.warn(warning)); console.error(`⛔ Execution stopped due to warnings.`); process.exit(1); } for (let i = 0; i < prompts.length; i++) await submitImage(apiToken, email, prompts[i], i + 1); } function diffInMinutesAndSeconds(date1, date2) { const diffInSeconds = Math.floor((date2 - date1) / 1000); return `${Math.floor(diffInSeconds / 60)} minutes ${diffInSeconds % 60} seconds`; }; main(); ``` </details> ### Ejemplos Imágenes reales generadas con esta misma Google Flow API con Nano Banana Pro y Nano Banana 2 Lite, tomadas directamente de nuestro blog y de la comparación de modelos (en inglés). Nano Banana Pro — texto a imagen ([fuente](/blog/251120), en inglés): *"Cat dressed like a pirate fencing with a real pirate… on a Disney cruise ship."* ![Resultado de texto a imagen de Nano Banana Pro](https://media.useapi.net/blog/2025-11-20-251120/nano-banana-pro-text-to-image.jpg) Nano Banana Pro — 5 imágenes de referencia ([fuente](/blog/251201), en inglés): cinco retratos individuales combinados en una sola foto de grupo, "K-Pop group victory celebration". ![Foto de grupo de Nano Banana Pro hecha con varias referencias](https://media.useapi.net/blog/2025-12-01-251201/result.jpg) Nano Banana 2 Lite, el modelo por defecto ([fuente](/docs/articles/google-flow-nano-banana-compare#examples), en inglés): el prompt del apicultor de nuestra comparación de los tres modelos, generado en 9:16 con el más rápido de los tres. <img src="https://media.useapi.net/articles/2026-06-15-google-flow-images-bash/nano-banana-2-lite.jpg" style="width: 100%; max-width: 420px;" alt="Apicultor generado con Nano Banana 2 Lite mediante la Google Flow API" /> ### Preguntas frecuentes - **¿Existe una API de Nano Banana 2?** Con useapi.net, sí: en la [Google Flow API](/docs/api-google-flow-v1), `nano-banana-2` genera imágenes con Nano Banana 2.1, la versión que usa Google Flow, con cualquier suscripción de Google AI o en una cuenta gratuita, sin cobro por imagen. Nano Banana 2 (Gemini 3.1 Flash Image) cuesta US$0,067 por imagen 1K en la [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) oficial de Google (a noviembre de 2026). Es un endpoint REST normal, sin proyecto de Cloud. - **¿Existe una API de Nano Banana Pro?** Con useapi.net, sí: Nano Banana Pro (Gemini 3 Pro Image) se ejecuta como `nano-banana-pro` en el endpoint [POST /images](/docs/api-google-flow-v1/post-google-flow-images), y una sola solicitud síncrona devuelve hasta cuatro imágenes, sin cobro por imagen. La [Gemini API](https://aistudio.google.com/docs/pricing#gemini-3-pro-image) oficial de Google cobra US$0,134 por imagen Pro (a noviembre de 2026). - **¿Qué modelo usa la API por defecto?** En useapi.net, el modelo por defecto es `nano-banana-2-lite` (Gemini 3.1 Flash-Lite Image), con o sin referencias. Cámbialo en cada solicitud con `model` igual a `nano-banana-2` (Nano Banana 2.1) o `nano-banana-pro` (Gemini 3 Pro Image, la mayor calidad). Los tres aceptan hasta 10 imágenes de referencia y admiten [upscale a 2K/4K](#upscaling-to-2k4k). [Nano Banana 2 Lite vs 2.1 vs Pro](/docs/articles/google-flow-nano-banana-compare-es) muestra los tres con el mismo prompt. - **¿Imagen 4 sigue disponible en Google Flow?** En useapi.net, el id de modelo `imagen-4` sigue funcionando, así que tu código actual sigue corriendo. Pero Google quitó Imagen de Google Flow en julio de 2026, y esas solicitudes ahora generan imágenes con `nano-banana-2-lite`, el modelo de imagen por defecto de Google Flow desde entonces. Para elegir otro modelo, define `model` como `nano-banana-2` o `nano-banana-pro`. - **¿Necesito un captcha o un proyecto de Google Cloud?** Con useapi.net no necesitas un proyecto de Google Cloud ni resolver captchas por tu cuenta. Google Flow pide un reCAPTCHA en cada imagen, y el worker de useapi.net lo resuelve todo automáticamente: tu primera cuenta de Google Flow incluye 300 resoluciones gratis con nuestras propias claves de AntiCaptcha, CapSolver y EzCaptcha, y después agregas las claves de tu proveedor con [POST /accounts/captcha-providers](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers). El script de esta guía no envía `captchaToken`. ### Conclusión Visita nuestro <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> servidor de Discord</a> o nuestro <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> canal de Telegram</a> para cualquier pregunta de soporte. Consulta nuestro [repositorio de GitHub](https://github.com/useapi/google-flow-api) con ejemplos de código. #### También publicado en {: .no_toc #cross-posted } También publicado en [dev.to](https://dev.to/useapi/how-to-generate-nano-banana-2-nano-banana-pro-images-via-the-google-flow-api-1cn2){:rel="nofollow"} (en inglés) y compartido en [Bluesky](https://bsky.app/profile/useapi.net/post/3mwjbmurnab2e){:rel="nofollow"}. ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-flow-images-bash-id === Document URL: https://useapi.net/docs/articles/google-flow-images-bash-id --- layout: default title: "Cara Membuat Gambar Nano Banana 2.1 & Nano Banana Pro lewat Google Flow API" description: "Buat gambar Nano Banana 2.1, Nano Banana Pro, dan Nano Banana 2 Lite dengan satu POST sinkron ke Google Flow API useapi.net, plus skrip batch Node.js." keywords: [Nano Banana API, Nano Banana 2.1 API, Nano Banana 2 API, Nano Banana Pro API, Gemini 3.1 Flash Image, Gemini 3 Pro Image, Nano Banana 2 Lite, image-to-image, Google Flow API, API Nano Banana, API Google Flow, cara pakai Nano Banana API, membuat gambar AI, API pembuat gambar, gambar ke gambar, tutorial bahasa Indonesia, kode, curl] image: https://media.useapi.net/articles/2026-06-15-google-flow-images-bash/nano-banana-2-lite.jpg parent: Articles nav_exclude: true lang: id translation_key: google-flow-images date: 2026-06-15 last_modified: 2026-11-06 nav_order: 840 repo: https://github.com/useapi/google-flow-api --- ## Cara Membuat Gambar Nano Banana 2.1 & Nano Banana Pro lewat Google Flow API {: .no_toc #how-to-generate-nano-banana-21--nano-banana-pro-images-via-the-google-flow-api } 6 menit baca • 15 Juni 2026 (6 November 2026) useapi.net adalah API pihak ketiga. Kami tidak berafiliasi dengan Google dan tidak disahkan oleh Google. ## Daftar isi {: .no_toc .text-delta #table-of-contents } ### Pendahuluan Satu `POST` sinkron ke [Google Flow API](/docs/api-google-flow-v1) useapi.net mengembalikan hingga empat gambar Nano Banana 2.1, [Nano Banana Pro](https://deepmind.google/models/gemini-image/pro/), atau [Nano Banana 2 Lite](https://deepmind.google/models/gemini-image/flash-lite/), yang dibuat dengan akun [Google Flow](https://flow.google.com) Anda. Gambar sudah termasuk di setiap [langganan Google AI](https://gemini.google/subscriptions/), akun gratis juga, sementara Gemini API resmi menagih $0,034 sampai $0,134 per gambar (per November 2026). Tidak perlu project Google Cloud dan tidak perlu API key Gemini. Panduan ini membahas model yang tersedia, selisih harganya, alur pembuatan gambar dengan satu panggilan `curl` yang tinggal disalin, dan skrip Node.js siap jalan yang membuat gambar secara batch dari daftar prompt. Ingin melihat beda ketiga model pada satu prompt? Lihat [perbandingan model Nano Banana](/docs/articles/google-flow-nano-banana-compare-id). Butuh video? Lihat [tutorial Veo 3.1](/docs/articles/google-flow-bash-id), pasangan panduan ini. ### Model yang didukung Pilih model per request dengan field `model` (default `nano-banana-2-lite`). Ketiga model berjalan di langganan Google AI mana pun, termasuk akun gratis. | ID model | Nama pemasaran | Referensi (I2I) | Rasio aspek | Catatan | |----------|----------------|-----------------:|---------------|-------| | `nano-banana-2-lite` *(default)* | Nano Banana 2 Lite / Gemini 3.1 Flash-Lite Image | maks. 10 | 16:9, 4:3, 1:1, 3:4, 9:16, auto<sup>†</sup> | Model gambar default Google Flow sejak Juli 2026. Di mode image-to-image tetap 16:9 kecuali Anda mengirim rasio | | `nano-banana-2` | Nano Banana 2.1 | maks. 10 | 16:9, 4:3, 1:1, 3:4, 9:16, auto<sup>†</sup> | Default `auto` di mode image-to-image | | `nano-banana-pro` | Nano Banana Pro / Gemini 3 Pro Image | maks. 10 | 16:9, 4:3, 1:1, 3:4, 9:16, auto<sup>†</sup> | Model gambar dengan kualitas tertinggi, default `auto` di mode image-to-image | <sup>†</sup> `auto` hanya berlaku di mode image-to-image (minimal satu `reference_*` atau `character_*` dikirim), dan backend menentukan rasionya dari gambar referensi pertama. Dengan beberapa referensi, orientasinya tidak dijamin, jadi kirim rasio yang eksplisit jika semua gambar harus kembali dengan bentuk yang sama. Ketiganya menerima `count` (1–4) dan `seed` agar hasilnya bisa diulang. Jika `model` tidak diisi, API memakai `nano-banana-2-lite`, dengan atau tanpa referensi. Dua alias lama masih diterima: `nano-banana` dipetakan ke `nano-banana-2`, dan `imagen-4` ke `nano-banana-2-lite` (Google menghapus Imagen dari Google Flow pada Juli 2026). Detail dan kemampuan tiap model ada di referensi [POST /images](/docs/api-google-flow-v1/post-google-flow-images). #### Upscale ke 2K/4K Gambar dari ketiga model bisa di-upscale dengan [POST /images/upscale](/docs/api-google-flow-v1/post-google-flow-images-upscale): kirim `mediaGenerationId` gambar dan `resolution` bernilai `2k` (default) atau `4k`. Responsnya berupa base64 di `encodedImage`. `2k` berjalan di paket mana pun, termasuk akun gratis. `4k` butuh Google AI Ultra, dan di paket lain langsung menjawab `400` dengan `4k upscaling is not available for this account` sebelum captcha diselesaikan, jadi tidak ada biaya dan mencoba ulang tidak akan membantu. Keduanya tidak memakai kredit Flow. ### Harga Gambar tidak memakai kredit Flow di langganan Google AI mana pun, termasuk akun gratis, dan useapi.net tidak menagih biaya per gambar. Paket berbayar hanya diperlukan untuk video Omni 1.1 Flash, video Omni 1.2 Flash yang lebih dari 10 detik, extend dengan Omni 1.2, dan upscale video, sedangkan upscale gambar `4k` butuh Ultra. Harga setiap model di setiap paket, dibandingkan dengan API resmi, ada di [tabel harga Google Flow](/docs/api-google-flow-v1#pricing). ### Cara membuat gambar Nano Banana dengan curl Anda butuh [API token](/docs/start-here/setup-useapi) useapi.net dan [akun Google Flow](/docs/start-here/setup-google-flow) yang sudah terhubung. Pembuatan gambar bersifat sinkron: satu `POST` menunggu sampai gambar selesai (biasanya 10–20 detik) dan mengembalikannya di respons, jadi tidak ada `jobid` yang perlu di-poll. Langkah kedua tinggal menyimpan hasilnya, dari URL bertanda tangan, atau jika URL itu tidak ada, dari gambar base64 inline. 1. Kirim prompt — `POST https://api.useapi.net/v1/google-flow/images`: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/images" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Cat dressed like a pirate fencing with a real pirate, pirate looks absolutely terrified, this is happening on a deck of the Disney cruise ship", "model": "nano-banana-pro", "aspectRatio": "16:9", "count": 4, "seed": 123456 }' > response.json ``` Panggilan ini mengembalikan `200 OK` dengan `jobId` dan array `media`, satu entri per gambar (`count` 1–4, default 4). URL unduhan bertanda tangan untuk tiap gambar ada di `media[].image.generatedImage.fifeUrl`: ```json { "jobId": "j1731859345678i-u12345-email:jo***@gmail.com-bot:google-flow", "media": [ { "image": { "generatedImage": { "seed": 123456, "mediaGenerationId": "user:12345-email:6a6f...-image:...", "prompt": "Cat dressed like a pirate fencing with a real pirate, pirate looks absolutely terrified, this is happening on a deck of the Disney cruise ship", "fifeUrl": "https://flow-content.google/image/...", "aspectRatio": "IMAGE_ASPECT_RATIO_LANDSCAPE" } } } ] } ``` 2. Unduh gambar dari `fifeUrl` (URL bertanda tangan hanya berlaku sebentar, jadi segera unduh). Sesekali `fifeUrl` tidak ada dan gambar dikirim inline sebagai base64 di `encodedImage`, jadi dekode field itu sebagai cadangan: ```bash URL=$(jq -r '.media[0].image.generatedImage.fifeUrl // empty' response.json) if [ -n "$URL" ]; then curl -o image_1.jpg "$URL" else jq -r '.media[0].image.generatedImage.encodedImage' response.json | base64 -d > image_1.jpg fi ``` `mediaGenerationId` setiap gambar yang dihasilkan bisa dipakai lagi sebagai referensi di request berikutnya. Lihat [Gambar referensi & karakter](#image-references--characters) di bawah. Ingin webhook juga? Kirim `replyUrl` di body request, dan API juga mengirim pembaruan status job ke URL itu. Panggilannya sendiri tetap menunggu sampai gambar selesai. Payload-nya sama dengan respons [GET /jobs/`jobId`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid), dan gambar yang sudah selesai ada di `response.media[].image.generatedImage.fifeUrl`. ### Gambar referensi & karakter Untuk mengarahkan gambar dengan foto yang sudah ada, unggah dulu foto itu dengan [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email) (byte mentah, `Content-Type` gambar, PNG/JPEG/WebP sampai 20 MB). Respons unggahan menaruh ID referensi bersarang di `mediaGenerationId.mediaGenerationId`, dan string bersarang itulah yang Anda kirim kembali sebagai `reference_1` (ketiga model masing-masing menerima hingga 10 referensi): ```bash # 1. Unggah gambar referensi curl -X POST "https://api.useapi.net/v1/google-flow/assets/john%40gmail.com" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: image/jpeg" \ --data-binary @reference.jpeg # Respons: ID referensi bersarang satu tingkat di dalam: # { # "mediaGenerationId": { # "mediaGenerationId": "user:12345-email:6a6f...-image:ff9aa5cc-..." # }, # "width": 1024, "height": 1024, "email": "jo***@gmail.com" # } # 2. Buat gambar dengan referensi itu curl -X POST "https://api.useapi.net/v1/google-flow/images" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model": "nano-banana-pro", "prompt": "Make this photograph look modern", "reference_1": "user:12345-email:6a6f...-image:ff9aa5cc-..." }' ``` Untuk menjaga identitas yang sama di banyak gambar, gabungkan 1–2 gambar referensi menjadi karakter yang bisa dipakai ulang dengan [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters), lalu kirim ID `character`-nya sebagai `character_1`…`character_7`. Karakter bisa dicampur bebas dengan `reference_*` dan berbagi batas jumlah gambar referensi yang sama untuk tiap model. Anda juga bisa menaruh penanda `@reference_1` / `@character_1` langsung di `prompt` untuk menunjukkan di bagian mana tiap gambar dipakai, dan setiap penanda inline harus punya parameter body yang cocok. ### Generate batch dengan skrip Mendapatkan gambar yang pas butuh banyak percobaan, dan menjalankannya satu per satu secara manual itu melelahkan. Skrip Node.js di bawah membaca daftar prompt dari `prompts.json`, mengunggah gambar referensi, mengirim setiap request, dan mengunduh semua gambar yang dikembalikan, jadi Anda bisa mengantrekan satu batch dan kembali nanti untuk memilih yang terbaik. Karena `POST /images` sinkron, skrip menyimpan setiap hasil begitu panggilannya selesai. Anda butuh [Node.js](https://nodejs.org) v21 atau lebih baru. Taruh `prompts.json` dan `google-flow-images.mjs` di folder yang sama lalu jalankan `node ./google-flow-images.mjs API_TOKEN EMAIL`, dengan `API_TOKEN` adalah [API token](/docs/start-here/setup-useapi) useapi.net Anda dan `EMAIL` adalah email [akun Google Flow](/docs/start-here/setup-google-flow) yang sudah terhubung. Skrip mencari akun berdasarkan email secara otomatis dan memeriksa field `health` sebelum mengirim. Lebih suka clone dan menjalankannya sendiri? `google-flow-images.mjs` dan `prompts.json` lengkap ada di GitHub di [`useapi/google-flow-api`](https://github.com/useapi/google-flow-api/tree/main/images). <details markdown="block"> <summary>Buka `prompts.json`</summary> ```json [ { "prompt": "By default the nano-banana-2-lite model generates 4 image variations at 16:9." }, { "model": "nano-banana-pro", "aspectRatio": "1:1", "count": 2, "seed": 123456, "prompt": "Nano Banana Pro (Gemini 3 Pro Image), two square variations. For all parameters see https://useapi.net/docs/api-google-flow-v1/post-google-flow-images" }, { "model": "nano-banana-2", "aspectRatio": "auto", "reference_1": "./reference_image.jpeg", "prompt": "Image-to-image: pass a local reference file as reference_1 (uploaded automatically). auto aspect ratio derives from the first reference. All three models accept up to 10 references." }, { "model": "nano-banana-2-lite", "aspectRatio": "9:16", "count": 4, "prompt": "Nano Banana 2 Lite portrait. Other models (nano-banana-2, nano-banana-pro) are selectable via the model field — see the POST /images docs." } ] ``` </details> <details markdown="block"> <summary>Buka skrip `google-flow-images.mjs`</summary> ```javascript /* Script version 1.2, September 11, 2026 Script to batch-generate images using prompts with the Google Flow API v1 by useapi.net 🚀 Uses the synchronous POST /images endpoint (default model: nano-banana-2-lite) and saves each image from fifeUrl, or from encodedImage when fifeUrl is absent. For more details visit https://useapi.net/docs/api-google-flow-v1/post-google-flow-images Installation Instructions: ========================== You need Node.js v21 or newer installed to run this script. Download and install Node.js from: - Windows, macOS, Linux: https://nodejs.org/ After installation, verify by running the following command in a terminal: node -v Running the Script: =================== Usage: node google-flow-images.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE] Replace API_TOKEN with your actual useapi.net API token, see https://useapi.net/docs/start-here/setup-useapi Replace EMAIL with configured Google Flow email account, see https://useapi.net/docs/start-here/setup-google-flow If optional PROMPTS_FILE not provided prompts.json will be used. Example: -------- node google-flow-images.mjs user:1234-abcdefhijklmnopqrstuv my@email.com This command executes the script using API token user:1234-abcdefhijklmnopqrstuv with my@email.com Google Flow account email. Changelog: ========== - June 15, 2026: Initial release. - September 10, 2026: Default model is now nano-banana-2-lite (Google removed Imagen from Flow, and imagen-4 now maps to nano-banana-2-lite). Saves encodedImage when fifeUrl is absent, and accepts .jpg reference images. - September 11, 2026: A prompt whose reference_* file fails to upload is skipped and logged to google-flow-images_errors.txt instead of being submitted without that reference. Writes a downloaded image only once it has been fully received, so a failed download leaves no partial file for the next run to skip as "already exists". */ import fs from 'fs/promises'; import { writeFile } from 'node:fs/promises'; // Constants const ERRORS_FILE = 'google-flow-images_errors.txt'; const DEFAULT_PROMPTS_FILE = 'prompts.json'; const DEFAULT_MODEL = 'nano-banana-2-lite'; const SLEEP_429 = 30 * 1000; // in milliseconds const urlAccounts = 'https://api.useapi.net/v1/google-flow/accounts'; const urlImages = 'https://api.useapi.net/v1/google-flow/images'; const urlUploadAsset = 'https://api.useapi.net/v1/google-flow/assets/'; // Google Flow accepts png, jpeg and webp for reference images. const supportedFileExtensions = ['png', 'jpg', 'jpeg', 'webp']; // reference_1 .. reference_10 are accepted by POST /images. const referenceParams = Array.from({ length: 10 }, (_, i) => `reference_${i + 1}`); // { filename: mediaGenerationId } const uploadedFiles = {}; // Utility to sleep for given milliseconds const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); // Function to fetch configured Google Flow API accounts async function fetchAccounts(apiToken) { const response = await fetch(urlAccounts, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.error(`⛔ Error fetching accounts (HTTP ${response.status}): ${response.statusText}`); process.exit(1); } return response.json(); } const elapsedTimeSec = (start) => (Date.now() - start) / 1000; // Map a file extension to the Content-Type required by POST /assets const contentTypeForExt = (ext) => ext === 'png' ? 'image/png' : ext === 'webp' ? 'image/webp' : 'image/jpeg'; async function uploadAsset(apiToken, email, filename) { // Check if already uploaded if (uploadedFiles.hasOwnProperty(filename)) return uploadedFiles[filename]; const startTime = Date.now(); console.log(`⬆️ Account ${email} uploading file…`, filename); const body = new Blob([await fs.readFile(filename)]); const fileExt = filename.split('.').pop().toLowerCase(); const response = await fetch(`${urlUploadAsset}${encodeURIComponent(email)}`, { method: 'POST', headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}`, 'Content-Type': contentTypeForExt(fileExt) }, body }); if (response.ok) { const json = await response.json(); // POST /assets returns the reference id nested as mediaGenerationId.mediaGenerationId const mediaGenerationId = json?.mediaGenerationId?.mediaGenerationId; console.log(`🆗 mediaGenerationId (${elapsedTimeSec(startTime)} sec)`, mediaGenerationId); uploadedFiles[filename] = mediaGenerationId; } else { console.error(`❗ Unable to upload file HTTP ${response.status} (${elapsedTimeSec(startTime)} sec)`, await response.text()); // Do not attempt to upload failed file again uploadedFiles[filename] = undefined; } return uploadedFiles[filename]; } // Download a single image from its signed fifeUrl. async function downloadImage(url, filename) { try { await fs.access(filename); console.log(`⚠️ ${filename} already exists. Skipping download.`); return; } catch { // File does not exist, proceed with downloading } if (!url) { console.error(`🛑 No fifeUrl for ${filename}`); return; } console.log(`✅ Downloading ${url} to ${filename}`); try { const imageResponse = await fetch(url); if (!imageResponse.ok) { console.error(`⛔ Unable to download ${filename} (HTTP ${imageResponse.status})`, url); return; } // Read the whole body before creating the file, so a failed download leaves no // partial file behind for the next run to skip as "already exists". const data = Buffer.from(await imageResponse.arrayBuffer()); await writeFile(filename, data); } catch (err) { console.error(`⛔ Error during download: ${err}`); } } // Submit a single prompt to the synchronous POST /images endpoint and download the results. async function submitImage(apiToken, email, prompt, index) { const { model, prompt: text } = prompt; const useModel = model ?? DEFAULT_MODEL; console.log(`🚀 ${useModel} » Prompt #${index} • account ${email} …`); // Build the request body, uploading any local reference_* file to a mediaGenerationId first. const body = { model: useModel, email, prompt: text }; for (const key of ['aspectRatio', 'count', 'seed']) if (prompt[key] !== undefined) body[key] = prompt[key]; for (const refKey of referenceParams) { const value = prompt[refKey]; if (value) body[refKey] = await uploadAsset(apiToken, email, value); } // A reference that failed to upload would be left out of the body, and the prompt would still be // generated (and charged) without it. Skip the prompt instead. uploadAsset remembers the failed file, // so a later prompt using it is skipped too, without another upload attempt. const failedUploads = referenceParams.filter(refKey => prompt[refKey] && !body[refKey]); for (const refKey of failedUploads) { console.error(`🛑 Prompt #${index} skipped: ${refKey} ${prompt[refKey]} failed to upload`); await fs.appendFile(ERRORS_FILE, `Upload failed for ${refKey} ${prompt[refKey]},#${index}:${text}\n`); } if (failedUploads.length) return; while (true) { const response = await fetch(urlImages, { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiToken}` }, body: JSON.stringify(body) }); const responseText = await response.text(); if (response.status == 200) { const json = JSON.parse(responseText); const media = json?.media ?? []; if (media.length == 0) console.error(`🛑 200 OK but no media for prompt #${index}:\n${text}\n`); // count > 1 returns multiple images in the media array. for (let i = 0; i < media.length; i++) { const img = media[i]?.image?.generatedImage; const filename = `google-flow_${index}_${i + 1}.jpg`; // fifeUrl is normally present. When it is absent the image arrived inline as base64 in encodedImage. if (!img?.fifeUrl && img?.encodedImage) await fs.writeFile(filename, Buffer.from(img.encodedImage, 'base64')); else await downloadImage(img?.fifeUrl, filename); } return 200; } switch (response.status) { case 429: console.log(`🔄️ Retry on HTTP ${response.status}`, responseText); await sleep(SLEEP_429); break; case 503: console.log(`🔄️ Service unavailable, retry on HTTP ${response.status}`, responseText); await sleep(SLEEP_429); break; case 402: console.log(`🛑 No subscription / insufficient credits`, responseText); await fs.appendFile(ERRORS_FILE, `${response.status},#${index}:${text}\n`); process.exit(1); case 400: case 500: console.log(`🛑 Rejected (validation or content moderation)`, responseText); await fs.appendFile(ERRORS_FILE, `${response.status},#${index}:${text}\n`); return response.status; default: console.log(`❗ FAILED with HTTP ${response.status}`, responseText); await fs.appendFile(ERRORS_FILE, `${response.status},#${index}:${text}\n`); return response.status; } } } // Main function async function main() { const apiToken = process.argv[2]; const email = process.argv[3]; const promptFile = process.argv[4] || DEFAULT_PROMPTS_FILE; if (!apiToken || !email) { console.error('Usage: node google-flow-images.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE]'); process.exit(1); } console.info('Script v1.2'); console.info('Node version is: ' + process.version); const start = new Date(); try { console.info('START EXECUTION', start); await execute(apiToken, email, promptFile); } catch (error) { console.error('⛔ Error during execution:', error.stack || error); } finally { console.info('COMPLETED', new Date()); console.info('EXECUTION ELAPSED', diffInMinutesAndSeconds(start, new Date())); } } async function execute(apiToken, email, promptFile) { const accounts = await fetchAccounts(apiToken); console.info(`Configured Google Flow API accounts (${Object.keys(accounts).length}):`, Object.keys(accounts).join(', ')); if (Object.keys(accounts).length <= 0) { console.error(`⛔ No configured Google Flow accounts found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (!accounts[email]) { console.error(`⛔ Account ${email} not found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (accounts[email].health && accounts[email].health !== 'OK') { console.error(`⛔ Account ${email} health is '${accounts[email].health}'. Please resolve and update the account, see https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } const promptData = await fs.readFile(promptFile, 'utf8'); const prompts = JSON.parse(promptData); console.log(`Total number of prompts to process`, prompts.length); let warnings = []; // Parameters accepted by this script for the POST /images endpoint. // See https://useapi.net/docs/api-google-flow-v1/post-google-flow-images for every model's full parameter set. const supportedParams = ['model', 'prompt', 'aspectRatio', 'count', 'seed', ...referenceParams]; const invalidKeys = (prompt) => Object.keys(prompt).filter(key => !key.startsWith('__') && !supportedParams.includes(key)) for (let i = 1; i <= prompts.length; i++) { const prompt = prompts[i - 1]; const { prompt: text } = prompt; const validateImage = async (file) => { if (file) { try { await fs.access(file); } catch { warnings.push(`⚠️ Image '${file}' does not exist. Prompt ${i}`); } const ext = file.split('.').pop().toLowerCase(); if (!supportedFileExtensions.includes(ext)) warnings.push(`⚠️ Image ${file} extension ${ext} not supported. Prompt ${i}`); } }; const notSupported = invalidKeys(prompt); if (notSupported.length) warnings.push(`⚠️ Following params not supported: ${notSupported.join(',')}. Prompt ${i}`); if (!text) warnings.push(`⚠️ prompt is required. Prompt ${i}`); await Promise.all(referenceParams.map(refKey => validateImage(prompt[refKey]))); } if (warnings.length > 0) { warnings.forEach(warning => console.warn(warning)); console.error(`⛔ Execution stopped due to warnings.`); process.exit(1); } for (let i = 0; i < prompts.length; i++) await submitImage(apiToken, email, prompts[i], i + 1); } function diffInMinutesAndSeconds(date1, date2) { const diffInSeconds = Math.floor((date2 - date1) / 1000); return `${Math.floor(diffInSeconds / 60)} minutes ${diffInSeconds % 60} seconds`; }; main(); ``` </details> ### Contoh Gambar asli yang dibuat lewat Google Flow API yang sama dengan Nano Banana Pro dan Nano Banana 2 Lite, diambil langsung dari blog dan perbandingan model kami. Nano Banana Pro — teks ke gambar ([sumber](/blog/251120)): *"Cat dressed like a pirate fencing with a real pirate… on a Disney cruise ship."* ![Hasil teks ke gambar Nano Banana Pro](https://media.useapi.net/blog/2025-11-20-251120/nano-banana-pro-text-to-image.jpg) Nano Banana Pro — 5 gambar referensi ([sumber](/blog/251201)): lima potret terpisah digabung menjadi satu foto grup "K-Pop group victory celebration". ![Foto grup Nano Banana Pro dari beberapa referensi](https://media.useapi.net/blog/2025-12-01-251201/result.jpg) Nano Banana 2 Lite, model default ([sumber](/docs/articles/google-flow-nano-banana-compare#examples)): prompt peternak lebah dari perbandingan tiga model kami, dibuat dalam 9:16 oleh model tercepat di antara ketiganya. <img src="https://media.useapi.net/articles/2026-06-15-google-flow-images-bash/nano-banana-2-lite.jpg" style="width: 100%; max-width: 420px;" alt="Hasil peternak lebah Nano Banana 2 Lite lewat Google Flow API" /> ### Pertanyaan yang sering diajukan - **Apakah ada API Nano Banana 2?** Lewat useapi.net, ada: di [Google Flow API](/docs/api-google-flow-v1), `nano-banana-2` membuat gambar dengan Nano Banana 2.1, versi yang dipakai Google Flow, di langganan Google AI mana pun atau akun gratis, tanpa biaya per gambar. Nano Banana 2 (Gemini 3.1 Flash Image) berbiaya $0,067 per gambar 1K di [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) resmi Google (per November 2026). Ini endpoint REST standar, tanpa project Cloud. - **Apakah ada API Nano Banana Pro?** Lewat useapi.net, ada: Nano Banana Pro (Gemini 3 Pro Image) berjalan sebagai `nano-banana-pro` di endpoint [POST /images](/docs/api-google-flow-v1/post-google-flow-images), dan satu request sinkron mengembalikan hingga empat gambar tanpa biaya per gambar. [Gemini API](https://aistudio.google.com/docs/pricing#gemini-3-pro-image) resmi Google menagih $0,134 untuk setiap gambar Pro (per November 2026). - **Model apa yang dipakai API secara default?** Di useapi.net, default-nya `nano-banana-2-lite` (Gemini 3.1 Flash-Lite Image), dengan atau tanpa referensi. Ganti per request dengan mengisi `model` menjadi `nano-banana-2` (Nano Banana 2.1) atau `nano-banana-pro` (Gemini 3 Pro Image, kualitas tertinggi). Ketiganya menerima hingga 10 gambar referensi dan bisa [di-upscale ke 2K/4K](#upscaling-to-2k4k). [Nano Banana 2 Lite vs 2.1 vs Pro](/docs/articles/google-flow-nano-banana-compare-id) menampilkan ketiganya pada satu prompt. - **Apakah Imagen 4 masih ada di Google Flow?** Di useapi.net, model id `imagen-4` masih berfungsi, jadi kode yang sudah ada tetap jalan. Namun Google menghapus Imagen dari Google Flow pada Juli 2026, sehingga request itu sekarang membuat gambar dengan `nano-banana-2-lite`, model gambar default Google Flow sejak saat itu. Untuk memilih model lain, isi `model` dengan `nano-banana-2` atau `nano-banana-pro`. - **Apakah saya perlu captcha atau project Google Cloud?** Lewat useapi.net Anda tidak perlu project Google Cloud maupun menyelesaikan captcha sendiri. Google Flow meminta reCAPTCHA untuk setiap gambar, dan worker useapi.net menyelesaikannya otomatis: akun Google Flow pertama Anda mendapat 300 penyelesaian gratis dengan key AntiCaptcha, CapSolver, dan EzCaptcha milik kami, lalu setelah itu Anda menambahkan key penyedia Anda sendiri dengan [POST /accounts/captcha-providers](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers). Skrip di panduan ini tidak mengirim `captchaToken`. ### Kesimpulan Kunjungi <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Server Discord</a> atau <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Channel Telegram</a> kami untuk pertanyaan dan masalah dukungan. Lihat [repo GitHub](https://github.com/useapi/google-flow-api) kami berisi contoh kode. #### Dipublikasikan juga di {: .no_toc #cross-posted } Juga dipublikasikan di [dev.to](https://dev.to/useapi/how-to-generate-nano-banana-2-nano-banana-pro-images-via-the-google-flow-api-1cn2){:rel="nofollow"} (bahasa Inggris) dan dibagikan di [Bluesky](https://bsky.app/profile/useapi.net/post/3mwjbmurnab2e){:rel="nofollow"}. ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-flow-images-bash-ja === Document URL: https://useapi.net/docs/articles/google-flow-images-bash-ja --- layout: default title: "Google Flow API で Nano Banana 2.1 と Nano Banana Pro の画像を生成する方法" description: "useapi.net の Google Flow API に同期の POST を1回送るだけで、Nano Banana 2.1、Nano Banana Pro、Nano Banana 2 Lite の画像を生成する方法。Node.js の一括生成スクリプト付き。" keywords: [Nano Banana API, Nano Banana 2.1 API, Nano Banana 2 API, Nano Banana Pro API, Gemini 3.1 Flash Image, Gemini 3 Pro Image, Nano Banana 2 Lite, image-to-image, Google Flow API, Nano Banana API 使い方, Nano Banana Pro API 料金, 画像生成 API, AI 画像生成, 画像から画像, curl, 日本語チュートリアル, Japanese tutorial] image: https://media.useapi.net/articles/2026-06-15-google-flow-images-bash/nano-banana-2-lite.jpg parent: Articles nav_exclude: true lang: ja translation_key: google-flow-images date: 2026-06-15 last_modified: 2026-11-06 nav_order: 840 repo: https://github.com/useapi/google-flow-api --- ## Google Flow API で Nano Banana 2.1 と Nano Banana Pro の画像を生成する方法 {: .no_toc #how-to-generate-nano-banana-21--nano-banana-pro-images-via-the-google-flow-api } 6分で読めます • 2026年6月15日(2026年11月6日更新) useapi.net はサードパーティの API です。Google とは提携しておらず、Google の承認も受けていません。 ## 目次 {: .no_toc .text-delta #table-of-contents } ### はじめに useapi.net の [Google Flow API](/docs/api-google-flow-v1) に同期の `POST` を1回送ると、Nano Banana 2.1、[Nano Banana Pro](https://deepmind.google/models/gemini-image/pro/)、[Nano Banana 2 Lite](https://deepmind.google/models/gemini-image/flash-lite/) の画像が最大4枚返ってきます。画像はお使いの [Google Flow](https://flow.google.com) アカウントで作られます。画像の生成は無料アカウントを含むすべての [Google AI のプラン](https://gemini.google/subscriptions/)に含まれていますが、公式の Gemini API では画像1枚に $0.034〜$0.134 かかります(2026年11月時点)。Google Cloud プロジェクトも Gemini API キーも不要です。 このガイドでは、使えるモデル、料金の違い、コピーしてそのまま使える `curl` による1回の呼び出しでの画像生成、プロンプトのリストから一括生成する Node.js スクリプトを紹介します。3つのモデルが同じプロンプトでどう違うかは [Nano Banana モデル比較](/docs/articles/google-flow-nano-banana-compare-ja)をご覧ください。動画を作りたい場合は、姉妹編の [Veo 3.1 チュートリアル](/docs/articles/google-flow-bash-ja)をご覧ください。 ### 対応モデル モデルはリクエストごとに `model` フィールドで選びます(デフォルトは `nano-banana-2-lite`)。3つのモデルはどれも、無料アカウントを含むすべての Google AI のプランで使えます。 | モデル ID | 製品名 | 参照画像(I2I) | アスペクト比 | 備考 | |----------|----------------|-----------------:|---------------|-------| | `nano-banana-2-lite` *(デフォルト)* | Nano Banana 2 Lite / Gemini 3.1 Flash-Lite Image | 最大10枚 | 16:9、4:3、1:1、3:4、9:16、auto<sup>†</sup> | 2026年7月から Google Flow のデフォルトの画像モデル。画像から画像のモードでも、比率を指定しなければ 16:9 のまま | | `nano-banana-2` | Nano Banana 2.1 | 最大10枚 | 16:9、4:3、1:1、3:4、9:16、auto<sup>†</sup> | 画像から画像のモードではデフォルトが `auto` | | `nano-banana-pro` | Nano Banana Pro / Gemini 3 Pro Image | 最大10枚 | 16:9、4:3、1:1、3:4、9:16、auto<sup>†</sup> | 最も高品質な画像モデル。画像から画像のモードではデフォルトが `auto` | <sup>†</sup> `auto` は画像から画像のモード(`reference_*` または `character_*` を1つ以上指定した場合)でのみ有効で、バックエンドが最初の参照画像から比率を決めます。参照画像が複数あると縦横の向きは保証されないため、すべての画像を同じ形で受け取りたい場合は比率を明示してください。 3つのモデルはどれも `count`(1〜4)と、結果を再現するための `seed` を受け付けます。`model` を省略すると、参照画像の有無にかかわらず `nano-banana-2-lite` が使われます。非推奨のエイリアスも2つ引き続き使えます。`nano-banana` は `nano-banana-2` に、`imagen-4` は `nano-banana-2-lite` に対応します(Google は2026年7月に Google Flow から Imagen を削除しました)。詳細とモデルごとの機能は [POST /images](/docs/api-google-flow-v1/post-google-flow-images) のリファレンスにあります。 #### 2K/4K へのアップスケール 3つのどのモデルで生成した画像も、[POST /images/upscale](/docs/api-google-flow-v1/post-google-flow-images-upscale) でアップスケールできます。画像の `mediaGenerationId` と、`resolution` に `2k`(デフォルト)または `4k` を渡します。応答は `encodedImage` に入った base64 です。`2k` は無料アカウントを含むどのプランでも使えます。`4k` には Google AI Ultra が必要で、ほかのプランでは CAPTCHA を解く前に `400` と `4k upscaling is not available for this account` が返るため、費用はかからず、再試行しても結果は変わりません。どちらも Flow クレジットを消費しません。 ### 料金 画像は無料アカウントを含むどの Google AI のプランでも Flow クレジットを消費せず、useapi.net も画像ごとの料金を取りません。有料プランが必要なのは、Omni 1.1 Flash の動画、10秒を超える Omni 1.2 Flash の動画、Omni 1.2 での延長、動画のアップスケールだけで、画像の `4k` アップスケールには Ultra が必要です。全モデル・全プランの料金と公式 API との比較は [Google Flow の料金表](/docs/api-google-flow-v1#pricing)にあります。 ### curl で Nano Banana の画像を生成する方法 useapi.net の [API トークン](/docs/start-here/setup-useapi)と、接続済みの [Google Flow アカウント](/docs/start-here/setup-google-flow)が必要です。画像の生成は同期です。`POST` 1回が画像の完成まで待ち(通常10〜20秒)、応答に画像を入れて返すので、ポーリングする `jobid` はありません。2つ目の手順は結果を保存するだけで、署名付き URL から、それがない場合はインラインの base64 画像から保存します。 1. プロンプトを送信する — `POST https://api.useapi.net/v1/google-flow/images`: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/images" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Cat dressed like a pirate fencing with a real pirate, pirate looks absolutely terrified, this is happening on a deck of the Disney cruise ship", "model": "nano-banana-pro", "aspectRatio": "16:9", "count": 4, "seed": 123456 }' > response.json ``` 呼び出しは `200 OK` を返し、`jobId` と `media` 配列が入っています。`media` は画像1枚につき1件です(`count` は1〜4、デフォルトは4)。各画像の署名付きダウンロード URL は `media[].image.generatedImage.fifeUrl` にあります。 ```json { "jobId": "j1731859345678i-u12345-email:jo***@gmail.com-bot:google-flow", "media": [ { "image": { "generatedImage": { "seed": 123456, "mediaGenerationId": "user:12345-email:6a6f...-image:...", "prompt": "Cat dressed like a pirate fencing with a real pirate, pirate looks absolutely terrified, this is happening on a deck of the Disney cruise ship", "fifeUrl": "https://flow-content.google/image/...", "aspectRatio": "IMAGE_ASPECT_RATIO_LANDSCAPE" } } } ] } ``` 2. `fifeUrl` から画像をダウンロードします(署名付き URL の有効期間は限られているので、早めにダウンロードしてください)。まれに `fifeUrl` がなく、画像が `encodedImage` にインラインの base64 で返ることがあるので、その場合はそちらをデコードします。 ```bash URL=$(jq -r '.media[0].image.generatedImage.fifeUrl // empty' response.json) if [ -n "$URL" ]; then curl -o image_1.jpg "$URL" else jq -r '.media[0].image.generatedImage.encodedImage' response.json | base64 -d > image_1.jpg fi ``` 生成した各画像の `mediaGenerationId` は、あとのリクエストで参照画像として再利用できます。下の[参照画像とキャラクター](#image-references--characters)を参照してください。 Webhook も使いたい場合は、リクエストのボディに `replyUrl` を渡すと、API がジョブのステータスの更新もその URL に送ります。呼び出し自体は、これまでどおり画像ができるまで待ちます。ペイロードは [GET /jobs/`jobId`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid) の応答と同じ形で、完成した画像は `response.media[].image.generatedImage.fifeUrl` にあります。 ### 参照画像とキャラクター 既存の画像で生成の方向を決めるには、まず [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email) でアップロードします(生のバイト列、画像の `Content-Type`、20 MB までの PNG/JPEG/WebP)。アップロードの応答では、参照 ID が `mediaGenerationId.mediaGenerationId` に入れ子になっています。この入れ子の文字列を `reference_1` として渡します(3つのモデルはどれも参照画像を最大10枚受け付けます)。 ```bash # 1. 参照画像をアップロードする curl -X POST "https://api.useapi.net/v1/google-flow/assets/john%40gmail.com" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: image/jpeg" \ --data-binary @reference.jpeg # 応答(参照 ID は1階層下に入れ子になっています): # { # "mediaGenerationId": { # "mediaGenerationId": "user:12345-email:6a6f...-image:ff9aa5cc-..." # }, # "width": 1024, "height": 1024, "email": "jo***@gmail.com" # } # 2. その参照画像を使って生成する curl -X POST "https://api.useapi.net/v1/google-flow/images" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model": "nano-banana-pro", "prompt": "Make this photograph look modern", "reference_1": "user:12345-email:6a6f...-image:ff9aa5cc-..." }' ``` 多くの画像で同じ人物を保ちたい場合は、[POST /characters](/docs/api-google-flow-v1/post-google-flow-characters) で1〜2枚の参照画像を再利用できるキャラクターにまとめ、その `character` ID を `character_1`〜`character_7` として渡します。キャラクターは `reference_*` と自由に組み合わせられ、モデルごとの参照画像の上限を共有します。`prompt` の中に `@reference_1` / `@character_1` のマーカーを入れて、プロンプトのどこでどの画像を使うかを示すこともできます。インラインのマーカーにはそれぞれ、対応するボディのパラメーターが必要です。 ### スクリプトで一括生成する 狙いどおりの画像を得るには何度も試す必要があり、手作業で1回ずつ実行するのは面倒です。下の Node.js スクリプトは、`prompts.json` からプロンプトのリストを読み込み、参照画像があればアップロードし、各リクエストを送信して、返ってきた画像をすべてダウンロードします。まとめてキューに入れておき、あとで良いものを選べます。`POST /images` は同期なので、スクリプトは呼び出しが返るたびにその結果を保存します。 [Node.js](https://nodejs.org) v21 以降が必要です。`prompts.json` と `google-flow-images.mjs` を同じフォルダーに置き、`node ./google-flow-images.mjs API_TOKEN EMAIL` を実行します。`API_TOKEN` は useapi.net の [API トークン](/docs/start-here/setup-useapi)、`EMAIL` は接続済みの [Google Flow アカウント](/docs/start-here/setup-google-flow)のメールアドレスです。スクリプトはメールアドレスからアカウントを自動で探し、送信前に `health` フィールドを確認します。 クローンしてローカルで実行したい場合は、`google-flow-images.mjs` と `prompts.json` の完全版が GitHub の [`useapi/google-flow-api`](https://github.com/useapi/google-flow-api/tree/main/images) にあります。 <details markdown="block"> <summary>`prompts.json` を表示</summary> ```json [ { "prompt": "By default the nano-banana-2-lite model generates 4 image variations at 16:9." }, { "model": "nano-banana-pro", "aspectRatio": "1:1", "count": 2, "seed": 123456, "prompt": "Nano Banana Pro (Gemini 3 Pro Image), two square variations. For all parameters see https://useapi.net/docs/api-google-flow-v1/post-google-flow-images" }, { "model": "nano-banana-2", "aspectRatio": "auto", "reference_1": "./reference_image.jpeg", "prompt": "Image-to-image: pass a local reference file as reference_1 (uploaded automatically). auto aspect ratio derives from the first reference. All three models accept up to 10 references." }, { "model": "nano-banana-2-lite", "aspectRatio": "9:16", "count": 4, "prompt": "Nano Banana 2 Lite portrait. Other models (nano-banana-2, nano-banana-pro) are selectable via the model field — see the POST /images docs." } ] ``` </details> <details markdown="block"> <summary>`google-flow-images.mjs` スクリプトを表示</summary> ```javascript /* Script version 1.2, September 11, 2026 Script to batch-generate images using prompts with the Google Flow API v1 by useapi.net 🚀 Uses the synchronous POST /images endpoint (default model: nano-banana-2-lite) and saves each image from fifeUrl, or from encodedImage when fifeUrl is absent. For more details visit https://useapi.net/docs/api-google-flow-v1/post-google-flow-images Installation Instructions: ========================== You need Node.js v21 or newer installed to run this script. Download and install Node.js from: - Windows, macOS, Linux: https://nodejs.org/ After installation, verify by running the following command in a terminal: node -v Running the Script: =================== Usage: node google-flow-images.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE] Replace API_TOKEN with your actual useapi.net API token, see https://useapi.net/docs/start-here/setup-useapi Replace EMAIL with configured Google Flow email account, see https://useapi.net/docs/start-here/setup-google-flow If optional PROMPTS_FILE not provided prompts.json will be used. Example: -------- node google-flow-images.mjs user:1234-abcdefhijklmnopqrstuv my@email.com This command executes the script using API token user:1234-abcdefhijklmnopqrstuv with my@email.com Google Flow account email. Changelog: ========== - June 15, 2026: Initial release. - September 10, 2026: Default model is now nano-banana-2-lite (Google removed Imagen from Flow, and imagen-4 now maps to nano-banana-2-lite). Saves encodedImage when fifeUrl is absent, and accepts .jpg reference images. - September 11, 2026: A prompt whose reference_* file fails to upload is skipped and logged to google-flow-images_errors.txt instead of being submitted without that reference. Writes a downloaded image only once it has been fully received, so a failed download leaves no partial file for the next run to skip as "already exists". */ import fs from 'fs/promises'; import { writeFile } from 'node:fs/promises'; // Constants const ERRORS_FILE = 'google-flow-images_errors.txt'; const DEFAULT_PROMPTS_FILE = 'prompts.json'; const DEFAULT_MODEL = 'nano-banana-2-lite'; const SLEEP_429 = 30 * 1000; // in milliseconds const urlAccounts = 'https://api.useapi.net/v1/google-flow/accounts'; const urlImages = 'https://api.useapi.net/v1/google-flow/images'; const urlUploadAsset = 'https://api.useapi.net/v1/google-flow/assets/'; // Google Flow accepts png, jpeg and webp for reference images. const supportedFileExtensions = ['png', 'jpg', 'jpeg', 'webp']; // reference_1 .. reference_10 are accepted by POST /images. const referenceParams = Array.from({ length: 10 }, (_, i) => `reference_${i + 1}`); // { filename: mediaGenerationId } const uploadedFiles = {}; // Utility to sleep for given milliseconds const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); // Function to fetch configured Google Flow API accounts async function fetchAccounts(apiToken) { const response = await fetch(urlAccounts, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.error(`⛔ Error fetching accounts (HTTP ${response.status}): ${response.statusText}`); process.exit(1); } return response.json(); } const elapsedTimeSec = (start) => (Date.now() - start) / 1000; // Map a file extension to the Content-Type required by POST /assets const contentTypeForExt = (ext) => ext === 'png' ? 'image/png' : ext === 'webp' ? 'image/webp' : 'image/jpeg'; async function uploadAsset(apiToken, email, filename) { // Check if already uploaded if (uploadedFiles.hasOwnProperty(filename)) return uploadedFiles[filename]; const startTime = Date.now(); console.log(`⬆️ Account ${email} uploading file…`, filename); const body = new Blob([await fs.readFile(filename)]); const fileExt = filename.split('.').pop().toLowerCase(); const response = await fetch(`${urlUploadAsset}${encodeURIComponent(email)}`, { method: 'POST', headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}`, 'Content-Type': contentTypeForExt(fileExt) }, body }); if (response.ok) { const json = await response.json(); // POST /assets returns the reference id nested as mediaGenerationId.mediaGenerationId const mediaGenerationId = json?.mediaGenerationId?.mediaGenerationId; console.log(`🆗 mediaGenerationId (${elapsedTimeSec(startTime)} sec)`, mediaGenerationId); uploadedFiles[filename] = mediaGenerationId; } else { console.error(`❗ Unable to upload file HTTP ${response.status} (${elapsedTimeSec(startTime)} sec)`, await response.text()); // Do not attempt to upload failed file again uploadedFiles[filename] = undefined; } return uploadedFiles[filename]; } // Download a single image from its signed fifeUrl. async function downloadImage(url, filename) { try { await fs.access(filename); console.log(`⚠️ ${filename} already exists. Skipping download.`); return; } catch { // File does not exist, proceed with downloading } if (!url) { console.error(`🛑 No fifeUrl for ${filename}`); return; } console.log(`✅ Downloading ${url} to ${filename}`); try { const imageResponse = await fetch(url); if (!imageResponse.ok) { console.error(`⛔ Unable to download ${filename} (HTTP ${imageResponse.status})`, url); return; } // Read the whole body before creating the file, so a failed download leaves no // partial file behind for the next run to skip as "already exists". const data = Buffer.from(await imageResponse.arrayBuffer()); await writeFile(filename, data); } catch (err) { console.error(`⛔ Error during download: ${err}`); } } // Submit a single prompt to the synchronous POST /images endpoint and download the results. async function submitImage(apiToken, email, prompt, index) { const { model, prompt: text } = prompt; const useModel = model ?? DEFAULT_MODEL; console.log(`🚀 ${useModel} » Prompt #${index} • account ${email} …`); // Build the request body, uploading any local reference_* file to a mediaGenerationId first. const body = { model: useModel, email, prompt: text }; for (const key of ['aspectRatio', 'count', 'seed']) if (prompt[key] !== undefined) body[key] = prompt[key]; for (const refKey of referenceParams) { const value = prompt[refKey]; if (value) body[refKey] = await uploadAsset(apiToken, email, value); } // A reference that failed to upload would be left out of the body, and the prompt would still be // generated (and charged) without it. Skip the prompt instead. uploadAsset remembers the failed file, // so a later prompt using it is skipped too, without another upload attempt. const failedUploads = referenceParams.filter(refKey => prompt[refKey] && !body[refKey]); for (const refKey of failedUploads) { console.error(`🛑 Prompt #${index} skipped: ${refKey} ${prompt[refKey]} failed to upload`); await fs.appendFile(ERRORS_FILE, `Upload failed for ${refKey} ${prompt[refKey]},#${index}:${text}\n`); } if (failedUploads.length) return; while (true) { const response = await fetch(urlImages, { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiToken}` }, body: JSON.stringify(body) }); const responseText = await response.text(); if (response.status == 200) { const json = JSON.parse(responseText); const media = json?.media ?? []; if (media.length == 0) console.error(`🛑 200 OK but no media for prompt #${index}:\n${text}\n`); // count > 1 returns multiple images in the media array. for (let i = 0; i < media.length; i++) { const img = media[i]?.image?.generatedImage; const filename = `google-flow_${index}_${i + 1}.jpg`; // fifeUrl is normally present. When it is absent the image arrived inline as base64 in encodedImage. if (!img?.fifeUrl && img?.encodedImage) await fs.writeFile(filename, Buffer.from(img.encodedImage, 'base64')); else await downloadImage(img?.fifeUrl, filename); } return 200; } switch (response.status) { case 429: console.log(`🔄️ Retry on HTTP ${response.status}`, responseText); await sleep(SLEEP_429); break; case 503: console.log(`🔄️ Service unavailable, retry on HTTP ${response.status}`, responseText); await sleep(SLEEP_429); break; case 402: console.log(`🛑 No subscription / insufficient credits`, responseText); await fs.appendFile(ERRORS_FILE, `${response.status},#${index}:${text}\n`); process.exit(1); case 400: case 500: console.log(`🛑 Rejected (validation or content moderation)`, responseText); await fs.appendFile(ERRORS_FILE, `${response.status},#${index}:${text}\n`); return response.status; default: console.log(`❗ FAILED with HTTP ${response.status}`, responseText); await fs.appendFile(ERRORS_FILE, `${response.status},#${index}:${text}\n`); return response.status; } } } // Main function async function main() { const apiToken = process.argv[2]; const email = process.argv[3]; const promptFile = process.argv[4] || DEFAULT_PROMPTS_FILE; if (!apiToken || !email) { console.error('Usage: node google-flow-images.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE]'); process.exit(1); } console.info('Script v1.2'); console.info('Node version is: ' + process.version); const start = new Date(); try { console.info('START EXECUTION', start); await execute(apiToken, email, promptFile); } catch (error) { console.error('⛔ Error during execution:', error.stack || error); } finally { console.info('COMPLETED', new Date()); console.info('EXECUTION ELAPSED', diffInMinutesAndSeconds(start, new Date())); } } async function execute(apiToken, email, promptFile) { const accounts = await fetchAccounts(apiToken); console.info(`Configured Google Flow API accounts (${Object.keys(accounts).length}):`, Object.keys(accounts).join(', ')); if (Object.keys(accounts).length <= 0) { console.error(`⛔ No configured Google Flow accounts found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (!accounts[email]) { console.error(`⛔ Account ${email} not found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (accounts[email].health && accounts[email].health !== 'OK') { console.error(`⛔ Account ${email} health is '${accounts[email].health}'. Please resolve and update the account, see https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } const promptData = await fs.readFile(promptFile, 'utf8'); const prompts = JSON.parse(promptData); console.log(`Total number of prompts to process`, prompts.length); let warnings = []; // Parameters accepted by this script for the POST /images endpoint. // See https://useapi.net/docs/api-google-flow-v1/post-google-flow-images for every model's full parameter set. const supportedParams = ['model', 'prompt', 'aspectRatio', 'count', 'seed', ...referenceParams]; const invalidKeys = (prompt) => Object.keys(prompt).filter(key => !key.startsWith('__') && !supportedParams.includes(key)) for (let i = 1; i <= prompts.length; i++) { const prompt = prompts[i - 1]; const { prompt: text } = prompt; const validateImage = async (file) => { if (file) { try { await fs.access(file); } catch { warnings.push(`⚠️ Image '${file}' does not exist. Prompt ${i}`); } const ext = file.split('.').pop().toLowerCase(); if (!supportedFileExtensions.includes(ext)) warnings.push(`⚠️ Image ${file} extension ${ext} not supported. Prompt ${i}`); } }; const notSupported = invalidKeys(prompt); if (notSupported.length) warnings.push(`⚠️ Following params not supported: ${notSupported.join(',')}. Prompt ${i}`); if (!text) warnings.push(`⚠️ prompt is required. Prompt ${i}`); await Promise.all(referenceParams.map(refKey => validateImage(prompt[refKey]))); } if (warnings.length > 0) { warnings.forEach(warning => console.warn(warning)); console.error(`⛔ Execution stopped due to warnings.`); process.exit(1); } for (let i = 0; i < prompts.length; i++) await submitImage(apiToken, email, prompts[i], i + 1); } function diffInMinutesAndSeconds(date1, date2) { const diffInSeconds = Math.floor((date2 - date1) / 1000); return `${Math.floor(diffInSeconds / 60)} minutes ${diffInSeconds % 60} seconds`; }; main(); ``` </details> ### 例 同じ Google Flow API で Nano Banana Pro と Nano Banana 2 Lite を使って生成した実際の画像です。当社のブログとモデル比較からそのまま持ってきました。 Nano Banana Pro — テキストから画像([出典](/blog/251120)):*"Cat dressed like a pirate fencing with a real pirate… on a Disney cruise ship."* ![Nano Banana Pro のテキストから画像の結果](https://media.useapi.net/blog/2025-11-20-251120/nano-banana-pro-text-to-image.jpg) Nano Banana Pro — 参照画像5枚([出典](/blog/251201)):5人それぞれのポートレートを、1枚の「K-Pop group victory celebration」の集合写真に合成したもの。 ![Nano Banana Pro の複数の参照画像から作った集合写真](https://media.useapi.net/blog/2025-12-01-251201/result.jpg) Nano Banana 2 Lite、デフォルトのモデル([出典](/docs/articles/google-flow-nano-banana-compare#examples)):3モデル比較で使った養蜂家のプロンプトを、3つの中で最も速いこのモデルが 9:16 で生成したもの。 <img src="https://media.useapi.net/articles/2026-06-15-google-flow-images-bash/nano-banana-2-lite.jpg" style="width: 100%; max-width: 420px;" alt="Google Flow API で生成した Nano Banana 2 Lite の養蜂家の画像" /> ### よくある質問 - **Nano Banana 2 の API はありますか?** useapi.net を使えば、あります。[Google Flow API](/docs/api-google-flow-v1) の `nano-banana-2` は、Google Flow が使っているバージョンである Nano Banana 2.1 で画像を作ります。どの Google AI のプランでも無料アカウントでも使え、画像ごとの料金はかかりません。Google の公式の [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) では、Nano Banana 2(Gemini 3.1 Flash Image)は 1K の画像1枚が $0.067 です(2026年11月時点)。標準的な REST エンドポイントで、Cloud プロジェクトは不要です。 - **Nano Banana Pro の API はありますか?** useapi.net を使えば、あります。Nano Banana Pro(Gemini 3 Pro Image)は [POST /images](/docs/api-google-flow-v1/post-google-flow-images) エンドポイントで `nano-banana-pro` として動き、同期リクエスト1回で最大4枚の画像が返ります。画像ごとの料金はかかりません。Google の公式の [Gemini API](https://aistudio.google.com/docs/pricing#gemini-3-pro-image) では、Pro の画像は1枚ごとに $0.134 かかります(2026年11月時点)。 - **API のデフォルトのモデルは何ですか?** useapi.net では、参照画像の有無にかかわらず `nano-banana-2-lite`(Gemini 3.1 Flash-Lite Image)がデフォルトです。リクエストごとに `model` を `nano-banana-2`(Nano Banana 2.1)または `nano-banana-pro`(Gemini 3 Pro Image、最高品質)に切り替えられます。3つのモデルはどれも参照画像を最大10枚受け付け、[2K/4K にアップスケール](#upscaling-to-2k4k)できます。[Nano Banana 2 Lite vs 2.1 vs Pro](/docs/articles/google-flow-nano-banana-compare-ja)では、同じプロンプトで3つのモデルを比べています。 - **Google Flow で Imagen 4 はまだ使えますか?** useapi.net では `imagen-4` のモデル ID が今も使えるので、既存のコードはそのまま動きます。ただし Google は2026年7月に Google Flow から Imagen を削除したため、こうしたリクエストは現在、それ以降 Google Flow のデフォルトの画像モデルになっている `nano-banana-2-lite` で画像を作ります。別のモデルを使うには、`model` を `nano-banana-2` または `nano-banana-pro` にします。 - **CAPTCHA や Google Cloud プロジェクトは必要ですか?** useapi.net なら、Google Cloud プロジェクトもご自身での CAPTCHA の対応も不要です。Google Flow は画像ごとに reCAPTCHA を求めますが、useapi.net のワーカーが自動で解決します。最初の Google Flow アカウントには、当社の AntiCaptcha、CapSolver、EzCaptcha のキーで300回の無料解決が付き、その後は [POST /accounts/captcha-providers](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers) でご自身のプロバイダーのキーを追加します。このガイドのスクリプトは `captchaToken` を送りません。 ### おわりに ご質問は <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord サーバー</a> または <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram チャンネル</a>へどうぞ。 コード例は [GitHub リポジトリ](https://github.com/useapi/google-flow-api)にあります。 #### ほかの掲載先 {: .no_toc #cross-posted } この記事(英語版)は [dev.to](https://dev.to/useapi/how-to-generate-nano-banana-2-nano-banana-pro-images-via-the-google-flow-api-1cn2){:rel="nofollow"} にも掲載し、[Bluesky](https://bsky.app/profile/useapi.net/post/3mwjbmurnab2e){:rel="nofollow"} でも紹介しています。 ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-flow-images-bash-pt === Document URL: https://useapi.net/docs/articles/google-flow-images-bash-pt --- layout: default title: "Como gerar imagens com o Nano Banana 2.1 e o Nano Banana Pro pela Google Flow API" description: "Gere imagens com o Nano Banana 2.1, o Nano Banana Pro e o Nano Banana 2 Lite com um único POST síncrono na Google Flow API da useapi.net, mais um script de lote em Node.js." keywords: [Nano Banana API, Nano Banana 2.1 API, Nano Banana 2 API, Nano Banana Pro API, Gemini 3.1 Flash Image, Gemini 3 Pro Image, Nano Banana 2 Lite, image-to-image, Google Flow API, API do Nano Banana, API do Nano Banana Pro, API do Google Flow, gerar imagens com IA, API de geração de imagens, imagem para imagem, tutorial Nano Banana, código, curl] image: https://media.useapi.net/articles/2026-06-15-google-flow-images-bash/nano-banana-2-lite.jpg parent: Articles nav_exclude: true lang: pt-BR translation_key: google-flow-images date: 2026-06-15 last_modified: 2026-11-06 nav_order: 840 repo: https://github.com/useapi/google-flow-api --- ## Como gerar imagens com o Nano Banana 2.1 e o Nano Banana Pro pela Google Flow API {: .no_toc #how-to-generate-nano-banana-21--nano-banana-pro-images-via-the-google-flow-api } 6 min de leitura • 15 de junho de 2026 (6 de novembro de 2026) A useapi.net é uma API de terceiros. Não tem afiliação com o Google nem é endossada por ele. ## Sumário {: .no_toc .text-delta #table-of-contents } ### Introdução Um único `POST` síncrono na [Google Flow API](/docs/api-google-flow-v1) da useapi.net devolve até quatro imagens do Nano Banana 2.1, do [Nano Banana Pro](https://deepmind.google/models/gemini-image/pro/) ou do [Nano Banana 2 Lite](https://deepmind.google/models/gemini-image/flash-lite/), feitas com a sua conta do [Google Flow](https://flow.google.com). As imagens estão incluídas em toda [assinatura do Google AI](https://gemini.google/subscriptions/), até numa conta gratuita, enquanto a Gemini API oficial cobra de $0,034 a $0,134 por imagem (em novembro de 2026). Não precisa de projeto no Google Cloud nem de chave da Gemini API. Este guia mostra os modelos disponíveis, a diferença de preço, o fluxo de imagem numa única chamada com `curl` pronto para copiar e um script em Node.js que gera imagens em lote a partir de uma lista de prompts. Quer ver como os três modelos se saem com o mesmo prompt? Veja a [comparação dos modelos Nano Banana](/docs/articles/google-flow-nano-banana-compare-pt). Precisa de vídeo? Veja o [tutorial do Veo 3.1](/docs/articles/google-flow-bash-pt), o guia irmão deste. ### Modelos suportados Escolha o modelo em cada requisição com o campo `model` (padrão `nano-banana-2-lite`). Os três modelos funcionam em qualquer assinatura do Google AI, inclusive numa conta gratuita. | ID do modelo | Nome comercial | Referências (I2I) | Proporções | Observações | |----------|----------------|-----------------:|---------------|-------| | `nano-banana-2-lite` *(padrão)* | Nano Banana 2 Lite / Gemini 3.1 Flash-Lite Image | máx. 10 | 16:9, 4:3, 1:1, 3:4, 9:16, auto<sup>†</sup> | Modelo de imagem padrão do Google Flow desde julho de 2026. No modo imagem para imagem continua em 16:9, a menos que você informe uma proporção | | `nano-banana-2` | Nano Banana 2.1 | máx. 10 | 16:9, 4:3, 1:1, 3:4, 9:16, auto<sup>†</sup> | Usa `auto` por padrão no modo imagem para imagem | | `nano-banana-pro` | Nano Banana Pro / Gemini 3 Pro Image | máx. 10 | 16:9, 4:3, 1:1, 3:4, 9:16, auto<sup>†</sup> | O modelo de imagem de maior qualidade. Usa `auto` por padrão no modo imagem para imagem | <sup>†</sup> `auto` só vale no modo imagem para imagem (com pelo menos um `reference_*` ou `character_*`): o backend tira a proporção da primeira imagem de referência. Com várias referências a orientação não é garantida, então informe uma proporção explícita quando todas as imagens precisarem voltar no mesmo formato. Os três aceitam `count` (1–4) e `seed` para reprodutibilidade. Se você omitir `model`, a API usa `nano-banana-2-lite`, com ou sem referências. Dois aliases obsoletos continuam aceitos: `nano-banana` vira `nano-banana-2`, e `imagen-4` vira `nano-banana-2-lite` (o Google removeu o Imagen do Google Flow em julho de 2026). Os detalhes e os recursos de cada modelo estão na referência do [POST /images](/docs/api-google-flow-v1/post-google-flow-images). #### Upscale para 2K/4K Imagens geradas com qualquer um dos três modelos podem passar por upscale com [POST /images/upscale](/docs/api-google-flow-v1/post-google-flow-images-upscale): informe o `mediaGenerationId` da imagem e um `resolution` de `2k` (padrão) ou `4k`. A resposta vem em base64 no `encodedImage`. O `2k` funciona em qualquer plano, inclusive numa conta gratuita. O `4k` exige o Google AI Ultra, e em qualquer outro plano responde `400` com `4k upscaling is not available for this account` antes de resolver um captcha, então não custa nada e tentar de novo não adianta. Nenhum dos dois consome créditos do Flow. ### Preços As imagens não consomem créditos do Flow em nenhuma assinatura do Google AI, inclusive numa conta gratuita, e a useapi.net não cobra nada por imagem. Um plano pago só é necessário para vídeo com Omni 1.1 Flash, vídeo com Omni 1.2 Flash acima de 10 segundos, extensão com Omni 1.2 e upscale de vídeo, e o upscale de imagem em `4k` exige o Ultra. O preço de cada modelo em cada plano, comparado com a API oficial, está na [tabela de preços do Google Flow](/docs/api-google-flow-v1#pricing). ### Como gerar uma imagem do Nano Banana com curl Você precisa de um [token de API](/docs/start-here/setup-useapi) da useapi.net e de uma [conta do Google Flow](/docs/start-here/setup-google-flow) conectada. A geração de imagens é síncrona: um único `POST` espera até as imagens ficarem prontas (normalmente de 10 a 20 segundos) e as devolve na resposta, então não há `jobid` para consultar. O segundo passo é só salvar o resultado, pela URL assinada ou, quando ela não vier, pela imagem em base64 inline. 1. Envie o prompt — `POST https://api.useapi.net/v1/google-flow/images`: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/images" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Cat dressed like a pirate fencing with a real pirate, pirate looks absolutely terrified, this is happening on a deck of the Disney cruise ship", "model": "nano-banana-pro", "aspectRatio": "16:9", "count": 4, "seed": 123456 }' > response.json ``` A chamada devolve `200 OK` com um `jobId` e um array `media`, com um item por imagem (`count` vai de 1 a 4, padrão 4). A URL de download assinada de cada imagem fica em `media[].image.generatedImage.fifeUrl`: ```json { "jobId": "j1731859345678i-u12345-email:jo***@gmail.com-bot:google-flow", "media": [ { "image": { "generatedImage": { "seed": 123456, "mediaGenerationId": "user:12345-email:6a6f...-image:...", "prompt": "Cat dressed like a pirate fencing with a real pirate, pirate looks absolutely terrified, this is happening on a deck of the Disney cruise ship", "fifeUrl": "https://flow-content.google/image/...", "aspectRatio": "IMAGE_ASPECT_RATIO_LANDSCAPE" } } } ] } ``` 2. Baixe a imagem pelo `fifeUrl` (a URL assinada vale por tempo limitado, então baixe logo). De vez em quando o `fifeUrl` não vem e a imagem chega inline em base64 no `encodedImage`. Nesse caso, decodifique esse campo: ```bash URL=$(jq -r '.media[0].image.generatedImage.fifeUrl // empty' response.json) if [ -n "$URL" ]; then curl -o image_1.jpg "$URL" else jq -r '.media[0].image.generatedImage.encodedImage' response.json | base64 -d > image_1.jpg fi ``` O `mediaGenerationId` de cada imagem gerada pode ser reutilizado como referência numa requisição posterior. Veja [Imagens de referência e personagens](#image-references--characters) abaixo. Quer um webhook também? Passe um `replyUrl` no corpo da requisição e a API também envia as atualizações de status do job para essa URL. A chamada em si continua esperando as imagens. O payload é igual à resposta de [GET /jobs/`jobId`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid), em que uma imagem concluída fica em `response.media[].image.generatedImage.fifeUrl`. ### Imagens de referência e personagens Para orientar uma imagem com uma foto que você já tem, faça primeiro o upload com [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email) (bytes brutos, um `Content-Type` de imagem, PNG/JPEG/WebP de até 20 MB). A resposta do upload traz o ID da referência aninhado em `mediaGenerationId.mediaGenerationId`. É essa string aninhada que você devolve como `reference_1` (cada um dos três modelos aceita até 10 referências): ```bash # 1. Faça o upload de uma imagem de referência curl -X POST "https://api.useapi.net/v1/google-flow/assets/john%40gmail.com" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: image/jpeg" \ --data-binary @reference.jpeg # Resposta: o ID da referência fica aninhado um nível abaixo: # { # "mediaGenerationId": { # "mediaGenerationId": "user:12345-email:6a6f...-image:ff9aa5cc-..." # }, # "width": 1024, "height": 1024, "email": "jo***@gmail.com" # } # 2. Gere usando essa referência curl -X POST "https://api.useapi.net/v1/google-flow/images" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model": "nano-banana-pro", "prompt": "Make this photograph look modern", "reference_1": "user:12345-email:6a6f...-image:ff9aa5cc-..." }' ``` Para manter a mesma identidade em muitas imagens, junte 1–2 imagens de referência num personagem reutilizável com [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters) e depois passe o ID `character` dele como `character_1`…`character_7`. Os personagens se combinam livremente com `reference_*` e dividem o mesmo limite de referências de cada modelo. Você também pode colocar marcadores `@reference_1` / `@character_1` direto no `prompt` para indicar em que ponto cada imagem entra. Cada marcador inline precisa de um parâmetro correspondente no corpo. ### Gere em lote com um script Chegar na imagem certa leva muitas tentativas, e rodar cada uma à mão cansa. O script em Node.js abaixo lê uma lista de prompts do `prompts.json`, faz o upload das imagens de referência, envia cada requisição e baixa todas as imagens devolvidas. Assim você enfileira um lote e volta depois para escolher as melhores. Como o `POST /images` é síncrono, o script salva cada resultado assim que a chamada retorna. Você precisa do [Node.js](https://nodejs.org) v21 ou mais recente. Coloque o `prompts.json` e o `google-flow-images.mjs` na mesma pasta e rode `node ./google-flow-images.mjs API_TOKEN EMAIL`, em que `API_TOKEN` é o seu [token de API](/docs/start-here/setup-useapi) da useapi.net e `EMAIL` é o e-mail da sua [conta do Google Flow](/docs/start-here/setup-google-flow) conectada. O script encontra a conta pelo e-mail automaticamente e verifica o campo `health` antes de enviar. Prefere clonar e rodar localmente? O `google-flow-images.mjs` e o `prompts.json` completos estão no GitHub, em [`useapi/google-flow-api`](https://github.com/useapi/google-flow-api/tree/main/images). <details markdown="block"> <summary>Abrir `prompts.json`</summary> ```json [ { "prompt": "By default the nano-banana-2-lite model generates 4 image variations at 16:9." }, { "model": "nano-banana-pro", "aspectRatio": "1:1", "count": 2, "seed": 123456, "prompt": "Nano Banana Pro (Gemini 3 Pro Image), two square variations. For all parameters see https://useapi.net/docs/api-google-flow-v1/post-google-flow-images" }, { "model": "nano-banana-2", "aspectRatio": "auto", "reference_1": "./reference_image.jpeg", "prompt": "Image-to-image: pass a local reference file as reference_1 (uploaded automatically). auto aspect ratio derives from the first reference. All three models accept up to 10 references." }, { "model": "nano-banana-2-lite", "aspectRatio": "9:16", "count": 4, "prompt": "Nano Banana 2 Lite portrait. Other models (nano-banana-2, nano-banana-pro) are selectable via the model field — see the POST /images docs." } ] ``` </details> <details markdown="block"> <summary>Abrir o script `google-flow-images.mjs`</summary> ```javascript /* Script version 1.2, September 11, 2026 Script to batch-generate images using prompts with the Google Flow API v1 by useapi.net 🚀 Uses the synchronous POST /images endpoint (default model: nano-banana-2-lite) and saves each image from fifeUrl, or from encodedImage when fifeUrl is absent. For more details visit https://useapi.net/docs/api-google-flow-v1/post-google-flow-images Installation Instructions: ========================== You need Node.js v21 or newer installed to run this script. Download and install Node.js from: - Windows, macOS, Linux: https://nodejs.org/ After installation, verify by running the following command in a terminal: node -v Running the Script: =================== Usage: node google-flow-images.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE] Replace API_TOKEN with your actual useapi.net API token, see https://useapi.net/docs/start-here/setup-useapi Replace EMAIL with configured Google Flow email account, see https://useapi.net/docs/start-here/setup-google-flow If optional PROMPTS_FILE not provided prompts.json will be used. Example: -------- node google-flow-images.mjs user:1234-abcdefhijklmnopqrstuv my@email.com This command executes the script using API token user:1234-abcdefhijklmnopqrstuv with my@email.com Google Flow account email. Changelog: ========== - June 15, 2026: Initial release. - September 10, 2026: Default model is now nano-banana-2-lite (Google removed Imagen from Flow, and imagen-4 now maps to nano-banana-2-lite). Saves encodedImage when fifeUrl is absent, and accepts .jpg reference images. - September 11, 2026: A prompt whose reference_* file fails to upload is skipped and logged to google-flow-images_errors.txt instead of being submitted without that reference. Writes a downloaded image only once it has been fully received, so a failed download leaves no partial file for the next run to skip as "already exists". */ import fs from 'fs/promises'; import { writeFile } from 'node:fs/promises'; // Constants const ERRORS_FILE = 'google-flow-images_errors.txt'; const DEFAULT_PROMPTS_FILE = 'prompts.json'; const DEFAULT_MODEL = 'nano-banana-2-lite'; const SLEEP_429 = 30 * 1000; // in milliseconds const urlAccounts = 'https://api.useapi.net/v1/google-flow/accounts'; const urlImages = 'https://api.useapi.net/v1/google-flow/images'; const urlUploadAsset = 'https://api.useapi.net/v1/google-flow/assets/'; // Google Flow accepts png, jpeg and webp for reference images. const supportedFileExtensions = ['png', 'jpg', 'jpeg', 'webp']; // reference_1 .. reference_10 are accepted by POST /images. const referenceParams = Array.from({ length: 10 }, (_, i) => `reference_${i + 1}`); // { filename: mediaGenerationId } const uploadedFiles = {}; // Utility to sleep for given milliseconds const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); // Function to fetch configured Google Flow API accounts async function fetchAccounts(apiToken) { const response = await fetch(urlAccounts, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.error(`⛔ Error fetching accounts (HTTP ${response.status}): ${response.statusText}`); process.exit(1); } return response.json(); } const elapsedTimeSec = (start) => (Date.now() - start) / 1000; // Map a file extension to the Content-Type required by POST /assets const contentTypeForExt = (ext) => ext === 'png' ? 'image/png' : ext === 'webp' ? 'image/webp' : 'image/jpeg'; async function uploadAsset(apiToken, email, filename) { // Check if already uploaded if (uploadedFiles.hasOwnProperty(filename)) return uploadedFiles[filename]; const startTime = Date.now(); console.log(`⬆️ Account ${email} uploading file…`, filename); const body = new Blob([await fs.readFile(filename)]); const fileExt = filename.split('.').pop().toLowerCase(); const response = await fetch(`${urlUploadAsset}${encodeURIComponent(email)}`, { method: 'POST', headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}`, 'Content-Type': contentTypeForExt(fileExt) }, body }); if (response.ok) { const json = await response.json(); // POST /assets returns the reference id nested as mediaGenerationId.mediaGenerationId const mediaGenerationId = json?.mediaGenerationId?.mediaGenerationId; console.log(`🆗 mediaGenerationId (${elapsedTimeSec(startTime)} sec)`, mediaGenerationId); uploadedFiles[filename] = mediaGenerationId; } else { console.error(`❗ Unable to upload file HTTP ${response.status} (${elapsedTimeSec(startTime)} sec)`, await response.text()); // Do not attempt to upload failed file again uploadedFiles[filename] = undefined; } return uploadedFiles[filename]; } // Download a single image from its signed fifeUrl. async function downloadImage(url, filename) { try { await fs.access(filename); console.log(`⚠️ ${filename} already exists. Skipping download.`); return; } catch { // File does not exist, proceed with downloading } if (!url) { console.error(`🛑 No fifeUrl for ${filename}`); return; } console.log(`✅ Downloading ${url} to ${filename}`); try { const imageResponse = await fetch(url); if (!imageResponse.ok) { console.error(`⛔ Unable to download ${filename} (HTTP ${imageResponse.status})`, url); return; } // Read the whole body before creating the file, so a failed download leaves no // partial file behind for the next run to skip as "already exists". const data = Buffer.from(await imageResponse.arrayBuffer()); await writeFile(filename, data); } catch (err) { console.error(`⛔ Error during download: ${err}`); } } // Submit a single prompt to the synchronous POST /images endpoint and download the results. async function submitImage(apiToken, email, prompt, index) { const { model, prompt: text } = prompt; const useModel = model ?? DEFAULT_MODEL; console.log(`🚀 ${useModel} » Prompt #${index} • account ${email} …`); // Build the request body, uploading any local reference_* file to a mediaGenerationId first. const body = { model: useModel, email, prompt: text }; for (const key of ['aspectRatio', 'count', 'seed']) if (prompt[key] !== undefined) body[key] = prompt[key]; for (const refKey of referenceParams) { const value = prompt[refKey]; if (value) body[refKey] = await uploadAsset(apiToken, email, value); } // A reference that failed to upload would be left out of the body, and the prompt would still be // generated (and charged) without it. Skip the prompt instead. uploadAsset remembers the failed file, // so a later prompt using it is skipped too, without another upload attempt. const failedUploads = referenceParams.filter(refKey => prompt[refKey] && !body[refKey]); for (const refKey of failedUploads) { console.error(`🛑 Prompt #${index} skipped: ${refKey} ${prompt[refKey]} failed to upload`); await fs.appendFile(ERRORS_FILE, `Upload failed for ${refKey} ${prompt[refKey]},#${index}:${text}\n`); } if (failedUploads.length) return; while (true) { const response = await fetch(urlImages, { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiToken}` }, body: JSON.stringify(body) }); const responseText = await response.text(); if (response.status == 200) { const json = JSON.parse(responseText); const media = json?.media ?? []; if (media.length == 0) console.error(`🛑 200 OK but no media for prompt #${index}:\n${text}\n`); // count > 1 returns multiple images in the media array. for (let i = 0; i < media.length; i++) { const img = media[i]?.image?.generatedImage; const filename = `google-flow_${index}_${i + 1}.jpg`; // fifeUrl is normally present. When it is absent the image arrived inline as base64 in encodedImage. if (!img?.fifeUrl && img?.encodedImage) await fs.writeFile(filename, Buffer.from(img.encodedImage, 'base64')); else await downloadImage(img?.fifeUrl, filename); } return 200; } switch (response.status) { case 429: console.log(`🔄️ Retry on HTTP ${response.status}`, responseText); await sleep(SLEEP_429); break; case 503: console.log(`🔄️ Service unavailable, retry on HTTP ${response.status}`, responseText); await sleep(SLEEP_429); break; case 402: console.log(`🛑 No subscription / insufficient credits`, responseText); await fs.appendFile(ERRORS_FILE, `${response.status},#${index}:${text}\n`); process.exit(1); case 400: case 500: console.log(`🛑 Rejected (validation or content moderation)`, responseText); await fs.appendFile(ERRORS_FILE, `${response.status},#${index}:${text}\n`); return response.status; default: console.log(`❗ FAILED with HTTP ${response.status}`, responseText); await fs.appendFile(ERRORS_FILE, `${response.status},#${index}:${text}\n`); return response.status; } } } // Main function async function main() { const apiToken = process.argv[2]; const email = process.argv[3]; const promptFile = process.argv[4] || DEFAULT_PROMPTS_FILE; if (!apiToken || !email) { console.error('Usage: node google-flow-images.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE]'); process.exit(1); } console.info('Script v1.2'); console.info('Node version is: ' + process.version); const start = new Date(); try { console.info('START EXECUTION', start); await execute(apiToken, email, promptFile); } catch (error) { console.error('⛔ Error during execution:', error.stack || error); } finally { console.info('COMPLETED', new Date()); console.info('EXECUTION ELAPSED', diffInMinutesAndSeconds(start, new Date())); } } async function execute(apiToken, email, promptFile) { const accounts = await fetchAccounts(apiToken); console.info(`Configured Google Flow API accounts (${Object.keys(accounts).length}):`, Object.keys(accounts).join(', ')); if (Object.keys(accounts).length <= 0) { console.error(`⛔ No configured Google Flow accounts found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (!accounts[email]) { console.error(`⛔ Account ${email} not found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (accounts[email].health && accounts[email].health !== 'OK') { console.error(`⛔ Account ${email} health is '${accounts[email].health}'. Please resolve and update the account, see https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } const promptData = await fs.readFile(promptFile, 'utf8'); const prompts = JSON.parse(promptData); console.log(`Total number of prompts to process`, prompts.length); let warnings = []; // Parameters accepted by this script for the POST /images endpoint. // See https://useapi.net/docs/api-google-flow-v1/post-google-flow-images for every model's full parameter set. const supportedParams = ['model', 'prompt', 'aspectRatio', 'count', 'seed', ...referenceParams]; const invalidKeys = (prompt) => Object.keys(prompt).filter(key => !key.startsWith('__') && !supportedParams.includes(key)) for (let i = 1; i <= prompts.length; i++) { const prompt = prompts[i - 1]; const { prompt: text } = prompt; const validateImage = async (file) => { if (file) { try { await fs.access(file); } catch { warnings.push(`⚠️ Image '${file}' does not exist. Prompt ${i}`); } const ext = file.split('.').pop().toLowerCase(); if (!supportedFileExtensions.includes(ext)) warnings.push(`⚠️ Image ${file} extension ${ext} not supported. Prompt ${i}`); } }; const notSupported = invalidKeys(prompt); if (notSupported.length) warnings.push(`⚠️ Following params not supported: ${notSupported.join(',')}. Prompt ${i}`); if (!text) warnings.push(`⚠️ prompt is required. Prompt ${i}`); await Promise.all(referenceParams.map(refKey => validateImage(prompt[refKey]))); } if (warnings.length > 0) { warnings.forEach(warning => console.warn(warning)); console.error(`⛔ Execution stopped due to warnings.`); process.exit(1); } for (let i = 0; i < prompts.length; i++) await submitImage(apiToken, email, prompts[i], i + 1); } function diffInMinutesAndSeconds(date1, date2) { const diffInSeconds = Math.floor((date2 - date1) / 1000); return `${Math.floor(diffInSeconds / 60)} minutes ${diffInSeconds % 60} seconds`; }; main(); ``` </details> ### Exemplos Imagens reais geradas por esta mesma Google Flow API com o Nano Banana Pro e o Nano Banana 2 Lite, tiradas direto do nosso blog e da comparação de modelos. Nano Banana Pro — texto para imagem ([fonte](/blog/251120)): *"Cat dressed like a pirate fencing with a real pirate… on a Disney cruise ship."* ![Resultado de texto para imagem do Nano Banana Pro](https://media.useapi.net/blog/2025-11-20-251120/nano-banana-pro-text-to-image.jpg) Nano Banana Pro — 5 imagens de referência ([fonte](/blog/251201)): cinco retratos individuais combinados numa única foto de grupo, "K-Pop group victory celebration". ![Foto de grupo do Nano Banana Pro feita com várias referências](https://media.useapi.net/blog/2025-12-01-251201/result.jpg) Nano Banana 2 Lite, o modelo padrão ([fonte](/docs/articles/google-flow-nano-banana-compare#examples)): o prompt do apicultor da nossa comparação dos três modelos, gerado em 9:16 pelo mais rápido dos três. <img src="https://media.useapi.net/articles/2026-06-15-google-flow-images-bash/nano-banana-2-lite.jpg" style="width: 100%; max-width: 420px;" alt="Apicultor gerado com o Nano Banana 2 Lite pela Google Flow API" /> ### Perguntas frequentes - **Existe uma API do Nano Banana 2?** Pela useapi.net, sim: na [Google Flow API](/docs/api-google-flow-v1), `nano-banana-2` gera imagens com o Nano Banana 2.1, a versão que o Google Flow usa, em qualquer assinatura do Google AI ou numa conta gratuita, sem cobrança por imagem. O Nano Banana 2 (Gemini 3.1 Flash Image) custa $0,067 por imagem 1K na [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) oficial do Google (em novembro de 2026). É um endpoint REST comum, sem projeto no Cloud. - **Existe uma API do Nano Banana Pro?** Pela useapi.net, sim: o Nano Banana Pro (Gemini 3 Pro Image) roda como `nano-banana-pro` no endpoint [POST /images](/docs/api-google-flow-v1/post-google-flow-images), e uma única requisição síncrona devolve até quatro imagens, sem cobrança por imagem. A [Gemini API](https://aistudio.google.com/docs/pricing#gemini-3-pro-image) oficial do Google cobra $0,134 por imagem Pro (em novembro de 2026). - **Qual modelo a API usa por padrão?** Na useapi.net, o padrão é `nano-banana-2-lite` (Gemini 3.1 Flash-Lite Image), com ou sem referências. Troque em cada requisição definindo `model` como `nano-banana-2` (Nano Banana 2.1) ou `nano-banana-pro` (Gemini 3 Pro Image, a maior qualidade). Os três aceitam até 10 imagens de referência e podem passar por [upscale para 2K/4K](#upscaling-to-2k4k). [Nano Banana 2 Lite vs 2.1 vs Pro](/docs/articles/google-flow-nano-banana-compare-pt) mostra os três com o mesmo prompt. - **O Imagen 4 ainda está disponível no Google Flow?** Na useapi.net, o ID de modelo `imagen-4` continua funcionando, então o código que você já tem segue rodando. Mas o Google removeu o Imagen do Google Flow em julho de 2026, e essas requisições agora geram imagens com o `nano-banana-2-lite`, o modelo de imagem padrão do Google Flow desde então. Para escolher outro modelo, defina `model` como `nano-banana-2` ou `nano-banana-pro`. - **Preciso de captcha ou de um projeto no Google Cloud?** Com a useapi.net você não precisa de projeto no Google Cloud nem de resolver captcha por conta própria. O Google Flow pede um reCAPTCHA a cada imagem, e o worker da useapi.net resolve tudo automaticamente: a sua primeira conta do Google Flow vem com 300 resoluções grátis nas nossas próprias chaves da AntiCaptcha, CapSolver e EzCaptcha, e depois disso você adiciona as chaves do seu provedor com [POST /accounts/captcha-providers](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers). O script deste guia não envia `captchaToken`. ### Conclusão Visite o nosso <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> servidor no Discord</a> ou o <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> canal no Telegram</a> para qualquer dúvida de suporte. Veja o nosso [repositório no GitHub](https://github.com/useapi/google-flow-api) com exemplos de código. #### Publicado também em {: .no_toc #cross-posted } Também publicado no [dev.to](https://dev.to/useapi/how-to-generate-nano-banana-2-nano-banana-pro-images-via-the-google-flow-api-1cn2){:rel="nofollow"} (em inglês) e compartilhado no [Bluesky](https://bsky.app/profile/useapi.net/post/3mwjbmurnab2e){:rel="nofollow"}. ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-flow-images-bash-th === Document URL: https://useapi.net/docs/articles/google-flow-images-bash-th --- layout: default title: "วิธีสร้างภาพ Nano Banana 2.1 และ Nano Banana Pro ผ่าน Google Flow API" description: "สร้างภาพ Nano Banana 2.1, Nano Banana Pro และ Nano Banana 2 Lite ด้วยคำขอ POST แบบซิงโครนัสครั้งเดียวผ่าน Google Flow API ของ useapi.net พร้อมสคริปต์ Node.js สำหรับสร้างภาพเป็นชุด" keywords: [Nano Banana API, Nano Banana 2.1 API, Nano Banana 2 API, Nano Banana Pro API, Gemini 3.1 Flash Image, Gemini 3 Pro Image, Nano Banana 2 Lite, image-to-image, Google Flow API, Nano Banana API ภาษาไทย, Nano Banana Pro API ราคา, API สร้างภาพ, สร้างภาพ AI ด้วย API, ภาพเป็นภาพ, curl, ตัวอย่างโค้ด, คู่มือ] image: https://media.useapi.net/articles/2026-06-15-google-flow-images-bash/nano-banana-2-lite.jpg parent: Articles nav_exclude: true lang: th translation_key: google-flow-images date: 2026-06-15 last_modified: 2026-11-06 nav_order: 840 repo: https://github.com/useapi/google-flow-api --- ## วิธีสร้างภาพ Nano Banana 2.1 และ Nano Banana Pro ผ่าน Google Flow API {: .no_toc #how-to-generate-nano-banana-21--nano-banana-pro-images-via-the-google-flow-api } อ่าน 6 นาที • 15 มิถุนายน 2026 (6 พฤศจิกายน 2026) useapi.net เป็น API ของบุคคลที่สาม (third-party) ไม่มีส่วนเกี่ยวข้องกับ Google และไม่ได้รับการรับรองจาก Google ## สารบัญ {: .no_toc .text-delta #table-of-contents } ### บทนำ ส่ง `POST` แบบซิงโครนัสครั้งเดียวไปยัง [Google Flow API](/docs/api-google-flow-v1) ของ useapi.net ก็จะได้ภาพจาก Nano Banana 2.1, [Nano Banana Pro](https://deepmind.google/models/gemini-image/pro/) หรือ [Nano Banana 2 Lite](https://deepmind.google/models/gemini-image/flash-lite/) กลับมาสูงสุดสี่ภาพ โดยสร้างด้วยบัญชี [Google Flow](https://flow.google.com) ของคุณเอง การสร้างภาพรวมอยู่ในทุก[แพ็กเกจ Google AI](https://gemini.google/subscriptions/) รวมถึงบัญชีฟรี ขณะที่ Gemini API ทางการคิดภาพละ $0.034 ถึง $0.134 (ข้อมูล ณ พฤศจิกายน 2026) ไม่ต้องมีโปรเจกต์ Google Cloud และไม่ต้องมี Gemini API key คู่มือนี้อธิบายโมเดลที่ใช้ได้ ส่วนต่างของราคา ขั้นตอนสร้างภาพด้วยการเรียกครั้งเดียวพร้อมคำสั่ง `curl` ที่คัดลอกไปใช้ได้ทันที และสคริปต์ Node.js ที่รันได้จริงสำหรับสร้างภาพเป็นชุดจากรายการพรอมต์ อยากรู้ว่าสามโมเดลต่างกันอย่างไรเมื่อใช้พรอมต์เดียวกัน ดู[การเปรียบเทียบโมเดล Nano Banana](/docs/articles/google-flow-nano-banana-compare-th) ถ้าต้องการวิดีโอ ดู[คู่มือ Veo 3.1](/docs/articles/google-flow-bash-th) ซึ่งเป็นบทความคู่กัน ### โมเดลที่รองรับ เลือกโมเดลในแต่ละคำขอด้วยฟิลด์ `model` (ค่าเริ่มต้นคือ `nano-banana-2-lite`) ทั้งสามโมเดลใช้ได้กับทุกแพ็กเกจ Google AI รวมถึงบัญชีฟรี | Model id | ชื่อทางการตลาด | ภาพอ้างอิง (I2I) | อัตราส่วนภาพ | หมายเหตุ | |----------|----------------|-----------------:|---------------|-------| | `nano-banana-2-lite` *(ค่าเริ่มต้น)* | Nano Banana 2 Lite / Gemini 3.1 Flash-Lite Image | สูงสุด 10 | 16:9, 4:3, 1:1, 3:4, 9:16, auto<sup>†</sup> | โมเดลภาพเริ่มต้นของ Google Flow ตั้งแต่กรกฎาคม 2026 ในโหมดภาพเป็นภาพจะยังเป็น 16:9 หากไม่ได้ระบุอัตราส่วน | | `nano-banana-2` | Nano Banana 2.1 | สูงสุด 10 | 16:9, 4:3, 1:1, 3:4, 9:16, auto<sup>†</sup> | ค่าเริ่มต้นเป็น `auto` ในโหมดภาพเป็นภาพ | | `nano-banana-pro` | Nano Banana Pro / Gemini 3 Pro Image | สูงสุด 10 | 16:9, 4:3, 1:1, 3:4, 9:16, auto<sup>†</sup> | โมเดลภาพคุณภาพสูงสุด ค่าเริ่มต้นเป็น `auto` ในโหมดภาพเป็นภาพ | <sup>†</sup> `auto` ใช้ได้เฉพาะในโหมดภาพเป็นภาพ (ส่ง `reference_*` หรือ `character_*` อย่างน้อยหนึ่งรายการ) โดยแบ็กเอนด์จะกำหนดอัตราส่วนจากภาพอ้างอิงภาพแรก เมื่อมีภาพอ้างอิงหลายภาพ จะไม่รับประกันแนวตั้งหรือแนวนอนของภาพ จึงควรระบุอัตราส่วนให้ชัดเจนเมื่อทุกภาพต้องออกมาเป็นรูปทรงเดียวกัน ทั้งสามโมเดลรองรับ `count` (1–4) และ `seed` เพื่อให้สร้างผลลัพธ์เดิมซ้ำได้ ถ้าไม่ระบุ `model` API จะใช้ `nano-banana-2-lite` ไม่ว่าจะมีภาพอ้างอิงหรือไม่ ชื่อแทน (alias) ที่เลิกใช้แล้วสองชื่อยังใช้ได้อยู่ คือ `nano-banana` จะชี้ไปที่ `nano-banana-2` และ `imagen-4` จะชี้ไปที่ `nano-banana-2-lite` (Google นำ Imagen ออกจาก Google Flow ในเดือนกรกฎาคม 2026) รายละเอียดและความสามารถของแต่ละโมเดลอยู่ในเอกสารอ้างอิง [POST /images](/docs/api-google-flow-v1/post-google-flow-images) #### อัปสเกลเป็น 2K/4K ภาพที่สร้างด้วยโมเดลใดก็ได้ในสามโมเดลนี้อัปสเกลได้ด้วย [POST /images/upscale](/docs/api-google-flow-v1/post-google-flow-images-upscale) โดยส่ง `mediaGenerationId` ของภาพ และ `resolution` เป็น `2k` (ค่าเริ่มต้น) หรือ `4k` การตอบกลับเป็น base64 ใน `encodedImage` ส่วน `2k` ใช้ได้กับทุกแพ็กเกจ รวมถึงบัญชีฟรี ส่วน `4k` ต้องใช้ Google AI Ultra และในแพ็กเกจอื่นจะตอบ `400` พร้อม `4k upscaling is not available for this account` ก่อนแก้ captcha จึงไม่เสียค่าใช้จ่าย และลองใหม่ก็ไม่ช่วย ทั้งสองแบบไม่ใช้เครดิต Flow ### ราคา การสร้างภาพไม่ใช้เครดิต Flow ในทุกแพ็กเกจ Google AI รวมถึงบัญชีฟรี และ useapi.net ไม่คิดค่าบริการต่อภาพ ต้องใช้แพ็กเกจแบบชำระเงินเฉพาะวิดีโอ Omni 1.1 Flash, วิดีโอ Omni 1.2 Flash ที่ยาวกว่า 10 วินาที, การต่อความยาววิดีโอด้วย Omni 1.2 และการอัปสเกลวิดีโอ ส่วนการอัปสเกลภาพ `4k` ต้องใช้ Ultra ราคาของทุกโมเดลในทุกแพ็กเกจเทียบกับ API ทางการ ดูได้ใน[ตารางราคา Google Flow](/docs/api-google-flow-v1#pricing) ### วิธีสร้างภาพ Nano Banana ด้วย curl คุณต้องมี [API token](/docs/start-here/setup-useapi) ของ useapi.net และ[บัญชี Google Flow](/docs/start-here/setup-google-flow) ที่เชื่อมต่อแล้ว การสร้างภาพเป็นแบบซิงโครนัส คำขอ `POST` ครั้งเดียวจะรอจนภาพเสร็จ (ปกติ 10–20 วินาที) แล้วส่งภาพกลับมาในการตอบกลับ จึงไม่มี `jobid` ที่ต้องโพล ขั้นที่สองเป็นแค่การบันทึกผลลัพธ์ จาก URL ที่มีลายเซ็น หรือถ้าไม่มี URL นั้น ก็จากภาพ base64 ที่แนบมาในการตอบกลับ 1. ส่งพรอมต์ — `POST https://api.useapi.net/v1/google-flow/images`: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/images" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Cat dressed like a pirate fencing with a real pirate, pirate looks absolutely terrified, this is happening on a deck of the Disney cruise ship", "model": "nano-banana-pro", "aspectRatio": "16:9", "count": 4, "seed": 123456 }' > response.json ``` การเรียกจะตอบ `200 OK` พร้อม `jobId` และอาร์เรย์ `media` ภาพละหนึ่งรายการ (`count` เป็น 1–4 ค่าเริ่มต้นคือ 4) URL ดาวน์โหลดที่มีลายเซ็นของแต่ละภาพอยู่ที่ `media[].image.generatedImage.fifeUrl`: ```json { "jobId": "j1731859345678i-u12345-email:jo***@gmail.com-bot:google-flow", "media": [ { "image": { "generatedImage": { "seed": 123456, "mediaGenerationId": "user:12345-email:6a6f...-image:...", "prompt": "Cat dressed like a pirate fencing with a real pirate, pirate looks absolutely terrified, this is happening on a deck of the Disney cruise ship", "fifeUrl": "https://flow-content.google/image/...", "aspectRatio": "IMAGE_ASPECT_RATIO_LANDSCAPE" } } } ] } ``` 2. ดาวน์โหลดภาพจาก `fifeUrl` (URL ที่มีลายเซ็นใช้ได้ในเวลาจำกัด ควรดาวน์โหลดทันที) บางครั้งไม่มี `fifeUrl` มา และภาพจะถูกส่งกลับเป็น base64 ใน `encodedImage` แทน กรณีนั้นให้ถอดรหัสจากฟิลด์นี้: ```bash URL=$(jq -r '.media[0].image.generatedImage.fifeUrl // empty' response.json) if [ -n "$URL" ]; then curl -o image_1.jpg "$URL" else jq -r '.media[0].image.generatedImage.encodedImage' response.json | base64 -d > image_1.jpg fi ``` `mediaGenerationId` ของแต่ละภาพที่สร้างแล้วนำกลับมาใช้เป็นภาพอ้างอิงในคำขอถัดไปได้ ดู[ภาพอ้างอิงและตัวละคร](#image-references--characters) ด้านล่าง ต้องการ webhook ด้วยหรือไม่ ส่ง `replyUrl` ใน body ของคำขอ แล้ว API จะส่งอัปเดตสถานะงานไปยัง URL นั้นด้วย ตัวการเรียกเองยังคงรอจนได้ภาพ payload มีรูปแบบเดียวกับการตอบกลับของ [GET /jobs/`jobId`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid) โดยภาพที่เสร็จแล้วอยู่ที่ `response.media[].image.generatedImage.fifeUrl` ### ภาพอ้างอิงและตัวละคร หากต้องการกำหนดทิศทางของภาพด้วยภาพที่มีอยู่แล้ว ให้อัปโหลดภาพนั้นก่อนด้วย [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email) (ไบต์ดิบ, `Content-Type` แบบภาพ, PNG/JPEG/WebP ไม่เกิน 20 MB) การตอบกลับของการอัปโหลดจะซ้อน id ของภาพอ้างอิงไว้ที่ `mediaGenerationId.mediaGenerationId` สตริงที่ซ้อนอยู่นี้คือค่าที่ส่งกลับไปเป็น `reference_1` (ทั้งสามโมเดลรับภาพอ้างอิงได้สูงสุด 10 ภาพ): ```bash # 1. อัปโหลดภาพอ้างอิง curl -X POST "https://api.useapi.net/v1/google-flow/assets/john%40gmail.com" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: image/jpeg" \ --data-binary @reference.jpeg # การตอบกลับ: id ของภาพอ้างอิงซ้อนอยู่ลึกลงไปหนึ่งชั้น: # { # "mediaGenerationId": { # "mediaGenerationId": "user:12345-email:6a6f...-image:ff9aa5cc-..." # }, # "width": 1024, "height": 1024, "email": "jo***@gmail.com" # } # 2. สร้างภาพโดยใช้ภาพอ้างอิงนั้น curl -X POST "https://api.useapi.net/v1/google-flow/images" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model": "nano-banana-pro", "prompt": "Make this photograph look modern", "reference_1": "user:12345-email:6a6f...-image:ff9aa5cc-..." }' ``` หากต้องการให้ตัวบุคคลเหมือนเดิมในหลายภาพ ให้รวมภาพอ้างอิง 1–2 ภาพเป็นตัวละครที่ใช้ซ้ำได้ด้วย [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters) แล้วส่ง id ของ `character` เป็น `character_1`…`character_7` ตัวละครใช้ร่วมกับ `reference_*` ได้อย่างอิสระ และใช้โควตาภาพอ้างอิงต่อโมเดลร่วมกัน คุณยังใส่เครื่องหมาย `@reference_1` / `@character_1` ลงใน `prompt` ได้โดยตรงเพื่อระบุว่าแต่ละภาพใช้ตรงไหน โดยเครื่องหมายแต่ละตัวต้องมีพารามิเตอร์ใน body ที่ตรงกัน ### สร้างภาพเป็นชุดด้วยสคริปต์ กว่าจะได้ภาพที่ใช่ต้องลองหลายครั้ง และการรันทีละครั้งด้วยมือก็น่าเบื่อ สคริปต์ Node.js ด้านล่างอ่านรายการพรอมต์จาก `prompts.json` อัปโหลดภาพอ้างอิง ส่งคำขอทีละรายการ และดาวน์โหลดทุกภาพที่ได้กลับมา คุณจึงตั้งคิวไว้เป็นชุดแล้วค่อยกลับมาเลือกภาพที่ดีที่สุดได้ เนื่องจาก `POST /images` เป็นแบบซิงโครนัส สคริปต์จึงบันทึกผลลัพธ์แต่ละรายการทันทีที่การเรียกเสร็จ คุณต้องมี [Node.js](https://nodejs.org) v21 ขึ้นไป วาง `prompts.json` และ `google-flow-images.mjs` ไว้ในโฟลเดอร์เดียวกัน แล้วรัน `node ./google-flow-images.mjs API_TOKEN EMAIL` โดย `API_TOKEN` คือ [API token](/docs/start-here/setup-useapi) ของ useapi.net และ `EMAIL` คืออีเมลของ[บัญชี Google Flow](/docs/start-here/setup-google-flow) ที่เชื่อมต่อไว้ สคริปต์จะค้นหาบัญชีจากอีเมลให้อัตโนมัติ และตรวจฟิลด์ `health` ก่อนส่งคำขอ อยาก clone ไปรันบนเครื่องเองหรือเปล่า ไฟล์ `google-flow-images.mjs` และ `prompts.json` ฉบับเต็มอยู่บน GitHub ที่ [`useapi/google-flow-api`](https://github.com/useapi/google-flow-api/tree/main/images) <details markdown="block"> <summary>ขยาย `prompts.json`</summary> ```json [ { "prompt": "By default the nano-banana-2-lite model generates 4 image variations at 16:9." }, { "model": "nano-banana-pro", "aspectRatio": "1:1", "count": 2, "seed": 123456, "prompt": "Nano Banana Pro (Gemini 3 Pro Image), two square variations. For all parameters see https://useapi.net/docs/api-google-flow-v1/post-google-flow-images" }, { "model": "nano-banana-2", "aspectRatio": "auto", "reference_1": "./reference_image.jpeg", "prompt": "Image-to-image: pass a local reference file as reference_1 (uploaded automatically). auto aspect ratio derives from the first reference. All three models accept up to 10 references." }, { "model": "nano-banana-2-lite", "aspectRatio": "9:16", "count": 4, "prompt": "Nano Banana 2 Lite portrait. Other models (nano-banana-2, nano-banana-pro) are selectable via the model field — see the POST /images docs." } ] ``` </details> <details markdown="block"> <summary>ขยายสคริปต์ `google-flow-images.mjs`</summary> ```javascript /* Script version 1.2, September 11, 2026 Script to batch-generate images using prompts with the Google Flow API v1 by useapi.net 🚀 Uses the synchronous POST /images endpoint (default model: nano-banana-2-lite) and saves each image from fifeUrl, or from encodedImage when fifeUrl is absent. For more details visit https://useapi.net/docs/api-google-flow-v1/post-google-flow-images Installation Instructions: ========================== You need Node.js v21 or newer installed to run this script. Download and install Node.js from: - Windows, macOS, Linux: https://nodejs.org/ After installation, verify by running the following command in a terminal: node -v Running the Script: =================== Usage: node google-flow-images.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE] Replace API_TOKEN with your actual useapi.net API token, see https://useapi.net/docs/start-here/setup-useapi Replace EMAIL with configured Google Flow email account, see https://useapi.net/docs/start-here/setup-google-flow If optional PROMPTS_FILE not provided prompts.json will be used. Example: -------- node google-flow-images.mjs user:1234-abcdefhijklmnopqrstuv my@email.com This command executes the script using API token user:1234-abcdefhijklmnopqrstuv with my@email.com Google Flow account email. Changelog: ========== - June 15, 2026: Initial release. - September 10, 2026: Default model is now nano-banana-2-lite (Google removed Imagen from Flow, and imagen-4 now maps to nano-banana-2-lite). Saves encodedImage when fifeUrl is absent, and accepts .jpg reference images. - September 11, 2026: A prompt whose reference_* file fails to upload is skipped and logged to google-flow-images_errors.txt instead of being submitted without that reference. Writes a downloaded image only once it has been fully received, so a failed download leaves no partial file for the next run to skip as "already exists". */ import fs from 'fs/promises'; import { writeFile } from 'node:fs/promises'; // Constants const ERRORS_FILE = 'google-flow-images_errors.txt'; const DEFAULT_PROMPTS_FILE = 'prompts.json'; const DEFAULT_MODEL = 'nano-banana-2-lite'; const SLEEP_429 = 30 * 1000; // in milliseconds const urlAccounts = 'https://api.useapi.net/v1/google-flow/accounts'; const urlImages = 'https://api.useapi.net/v1/google-flow/images'; const urlUploadAsset = 'https://api.useapi.net/v1/google-flow/assets/'; // Google Flow accepts png, jpeg and webp for reference images. const supportedFileExtensions = ['png', 'jpg', 'jpeg', 'webp']; // reference_1 .. reference_10 are accepted by POST /images. const referenceParams = Array.from({ length: 10 }, (_, i) => `reference_${i + 1}`); // { filename: mediaGenerationId } const uploadedFiles = {}; // Utility to sleep for given milliseconds const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); // Function to fetch configured Google Flow API accounts async function fetchAccounts(apiToken) { const response = await fetch(urlAccounts, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.error(`⛔ Error fetching accounts (HTTP ${response.status}): ${response.statusText}`); process.exit(1); } return response.json(); } const elapsedTimeSec = (start) => (Date.now() - start) / 1000; // Map a file extension to the Content-Type required by POST /assets const contentTypeForExt = (ext) => ext === 'png' ? 'image/png' : ext === 'webp' ? 'image/webp' : 'image/jpeg'; async function uploadAsset(apiToken, email, filename) { // Check if already uploaded if (uploadedFiles.hasOwnProperty(filename)) return uploadedFiles[filename]; const startTime = Date.now(); console.log(`⬆️ Account ${email} uploading file…`, filename); const body = new Blob([await fs.readFile(filename)]); const fileExt = filename.split('.').pop().toLowerCase(); const response = await fetch(`${urlUploadAsset}${encodeURIComponent(email)}`, { method: 'POST', headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}`, 'Content-Type': contentTypeForExt(fileExt) }, body }); if (response.ok) { const json = await response.json(); // POST /assets returns the reference id nested as mediaGenerationId.mediaGenerationId const mediaGenerationId = json?.mediaGenerationId?.mediaGenerationId; console.log(`🆗 mediaGenerationId (${elapsedTimeSec(startTime)} sec)`, mediaGenerationId); uploadedFiles[filename] = mediaGenerationId; } else { console.error(`❗ Unable to upload file HTTP ${response.status} (${elapsedTimeSec(startTime)} sec)`, await response.text()); // Do not attempt to upload failed file again uploadedFiles[filename] = undefined; } return uploadedFiles[filename]; } // Download a single image from its signed fifeUrl. async function downloadImage(url, filename) { try { await fs.access(filename); console.log(`⚠️ ${filename} already exists. Skipping download.`); return; } catch { // File does not exist, proceed with downloading } if (!url) { console.error(`🛑 No fifeUrl for ${filename}`); return; } console.log(`✅ Downloading ${url} to ${filename}`); try { const imageResponse = await fetch(url); if (!imageResponse.ok) { console.error(`⛔ Unable to download ${filename} (HTTP ${imageResponse.status})`, url); return; } // Read the whole body before creating the file, so a failed download leaves no // partial file behind for the next run to skip as "already exists". const data = Buffer.from(await imageResponse.arrayBuffer()); await writeFile(filename, data); } catch (err) { console.error(`⛔ Error during download: ${err}`); } } // Submit a single prompt to the synchronous POST /images endpoint and download the results. async function submitImage(apiToken, email, prompt, index) { const { model, prompt: text } = prompt; const useModel = model ?? DEFAULT_MODEL; console.log(`🚀 ${useModel} » Prompt #${index} • account ${email} …`); // Build the request body, uploading any local reference_* file to a mediaGenerationId first. const body = { model: useModel, email, prompt: text }; for (const key of ['aspectRatio', 'count', 'seed']) if (prompt[key] !== undefined) body[key] = prompt[key]; for (const refKey of referenceParams) { const value = prompt[refKey]; if (value) body[refKey] = await uploadAsset(apiToken, email, value); } // A reference that failed to upload would be left out of the body, and the prompt would still be // generated (and charged) without it. Skip the prompt instead. uploadAsset remembers the failed file, // so a later prompt using it is skipped too, without another upload attempt. const failedUploads = referenceParams.filter(refKey => prompt[refKey] && !body[refKey]); for (const refKey of failedUploads) { console.error(`🛑 Prompt #${index} skipped: ${refKey} ${prompt[refKey]} failed to upload`); await fs.appendFile(ERRORS_FILE, `Upload failed for ${refKey} ${prompt[refKey]},#${index}:${text}\n`); } if (failedUploads.length) return; while (true) { const response = await fetch(urlImages, { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiToken}` }, body: JSON.stringify(body) }); const responseText = await response.text(); if (response.status == 200) { const json = JSON.parse(responseText); const media = json?.media ?? []; if (media.length == 0) console.error(`🛑 200 OK but no media for prompt #${index}:\n${text}\n`); // count > 1 returns multiple images in the media array. for (let i = 0; i < media.length; i++) { const img = media[i]?.image?.generatedImage; const filename = `google-flow_${index}_${i + 1}.jpg`; // fifeUrl is normally present. When it is absent the image arrived inline as base64 in encodedImage. if (!img?.fifeUrl && img?.encodedImage) await fs.writeFile(filename, Buffer.from(img.encodedImage, 'base64')); else await downloadImage(img?.fifeUrl, filename); } return 200; } switch (response.status) { case 429: console.log(`🔄️ Retry on HTTP ${response.status}`, responseText); await sleep(SLEEP_429); break; case 503: console.log(`🔄️ Service unavailable, retry on HTTP ${response.status}`, responseText); await sleep(SLEEP_429); break; case 402: console.log(`🛑 No subscription / insufficient credits`, responseText); await fs.appendFile(ERRORS_FILE, `${response.status},#${index}:${text}\n`); process.exit(1); case 400: case 500: console.log(`🛑 Rejected (validation or content moderation)`, responseText); await fs.appendFile(ERRORS_FILE, `${response.status},#${index}:${text}\n`); return response.status; default: console.log(`❗ FAILED with HTTP ${response.status}`, responseText); await fs.appendFile(ERRORS_FILE, `${response.status},#${index}:${text}\n`); return response.status; } } } // Main function async function main() { const apiToken = process.argv[2]; const email = process.argv[3]; const promptFile = process.argv[4] || DEFAULT_PROMPTS_FILE; if (!apiToken || !email) { console.error('Usage: node google-flow-images.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE]'); process.exit(1); } console.info('Script v1.2'); console.info('Node version is: ' + process.version); const start = new Date(); try { console.info('START EXECUTION', start); await execute(apiToken, email, promptFile); } catch (error) { console.error('⛔ Error during execution:', error.stack || error); } finally { console.info('COMPLETED', new Date()); console.info('EXECUTION ELAPSED', diffInMinutesAndSeconds(start, new Date())); } } async function execute(apiToken, email, promptFile) { const accounts = await fetchAccounts(apiToken); console.info(`Configured Google Flow API accounts (${Object.keys(accounts).length}):`, Object.keys(accounts).join(', ')); if (Object.keys(accounts).length <= 0) { console.error(`⛔ No configured Google Flow accounts found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (!accounts[email]) { console.error(`⛔ Account ${email} not found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (accounts[email].health && accounts[email].health !== 'OK') { console.error(`⛔ Account ${email} health is '${accounts[email].health}'. Please resolve and update the account, see https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } const promptData = await fs.readFile(promptFile, 'utf8'); const prompts = JSON.parse(promptData); console.log(`Total number of prompts to process`, prompts.length); let warnings = []; // Parameters accepted by this script for the POST /images endpoint. // See https://useapi.net/docs/api-google-flow-v1/post-google-flow-images for every model's full parameter set. const supportedParams = ['model', 'prompt', 'aspectRatio', 'count', 'seed', ...referenceParams]; const invalidKeys = (prompt) => Object.keys(prompt).filter(key => !key.startsWith('__') && !supportedParams.includes(key)) for (let i = 1; i <= prompts.length; i++) { const prompt = prompts[i - 1]; const { prompt: text } = prompt; const validateImage = async (file) => { if (file) { try { await fs.access(file); } catch { warnings.push(`⚠️ Image '${file}' does not exist. Prompt ${i}`); } const ext = file.split('.').pop().toLowerCase(); if (!supportedFileExtensions.includes(ext)) warnings.push(`⚠️ Image ${file} extension ${ext} not supported. Prompt ${i}`); } }; const notSupported = invalidKeys(prompt); if (notSupported.length) warnings.push(`⚠️ Following params not supported: ${notSupported.join(',')}. Prompt ${i}`); if (!text) warnings.push(`⚠️ prompt is required. Prompt ${i}`); await Promise.all(referenceParams.map(refKey => validateImage(prompt[refKey]))); } if (warnings.length > 0) { warnings.forEach(warning => console.warn(warning)); console.error(`⛔ Execution stopped due to warnings.`); process.exit(1); } for (let i = 0; i < prompts.length; i++) await submitImage(apiToken, email, prompts[i], i + 1); } function diffInMinutesAndSeconds(date1, date2) { const diffInSeconds = Math.floor((date2 - date1) / 1000); return `${Math.floor(diffInSeconds / 60)} minutes ${diffInSeconds % 60} seconds`; }; main(); ``` </details> ### ตัวอย่าง ภาพจริงที่สร้างผ่าน Google Flow API ตัวเดียวกันนี้ด้วย Nano Banana Pro และ Nano Banana 2 Lite นำมาจากบล็อกและบทความเปรียบเทียบโมเดลของเราโดยตรง Nano Banana Pro — ข้อความเป็นภาพ ([ที่มา](/blog/251120)): *"Cat dressed like a pirate fencing with a real pirate… on a Disney cruise ship."* ![ผลลัพธ์ข้อความเป็นภาพของ Nano Banana Pro](https://media.useapi.net/blog/2025-11-20-251120/nano-banana-pro-text-to-image.jpg) Nano Banana Pro — ภาพอ้างอิง 5 ภาพ ([ที่มา](/blog/251201)): ภาพพอร์เทรตเดี่ยวห้าภาพที่รวมเป็นภาพหมู่ "K-Pop group victory celebration" ภาพเดียว ![ภาพหมู่จาก Nano Banana Pro ที่ใช้ภาพอ้างอิงหลายภาพ](https://media.useapi.net/blog/2025-12-01-251201/result.jpg) Nano Banana 2 Lite โมเดลเริ่มต้น ([ที่มา](/docs/articles/google-flow-nano-banana-compare#examples)): พรอมต์คนเลี้ยงผึ้งจากบทความเปรียบเทียบสามโมเดลของเรา สร้างที่ 9:16 ด้วยโมเดลที่เร็วที่สุดในสามตัว <img src="https://media.useapi.net/articles/2026-06-15-google-flow-images-bash/nano-banana-2-lite.jpg" style="width: 100%; max-width: 420px;" alt="ภาพคนเลี้ยงผึ้งจาก Nano Banana 2 Lite ผ่าน Google Flow API" /> ### คำถามที่พบบ่อย - **Nano Banana 2 มี API ไหม?** ผ่าน useapi.net มี ใน [Google Flow API](/docs/api-google-flow-v1) `nano-banana-2` สร้างภาพด้วย Nano Banana 2.1 ซึ่งเป็นเวอร์ชันที่ Google Flow ใช้ ทำงานได้กับทุกแพ็กเกจ Google AI หรือบัญชีฟรี และไม่มีค่าบริการต่อภาพ ส่วน Nano Banana 2 (Gemini 3.1 Flash Image) บน [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) ทางการของ Google ราคาภาพละ $0.067 ที่ความละเอียด 1K (ข้อมูล ณ พฤศจิกายน 2026) เป็น REST endpoint มาตรฐาน ไม่ต้องมีโปรเจกต์ Cloud - **Nano Banana Pro มี API ไหม?** ผ่าน useapi.net มี Nano Banana Pro (Gemini 3 Pro Image) ทำงานเป็น `nano-banana-pro` บน endpoint [POST /images](/docs/api-google-flow-v1/post-google-flow-images) คำขอแบบซิงโครนัสครั้งเดียวได้ภาพกลับมาสูงสุดสี่ภาพ โดยไม่มีค่าบริการต่อภาพ ขณะที่ [Gemini API](https://aistudio.google.com/docs/pricing#gemini-3-pro-image) ทางการของ Google คิดภาพ Pro ภาพละ $0.134 (ข้อมูล ณ พฤศจิกายน 2026) - **API ใช้โมเดลไหนเป็นค่าเริ่มต้น?** บน useapi.net ค่าเริ่มต้นคือ `nano-banana-2-lite` (Gemini 3.1 Flash-Lite Image) ไม่ว่าจะมีภาพอ้างอิงหรือไม่ เปลี่ยนได้ในแต่ละคำขอโดยตั้ง `model` เป็น `nano-banana-2` (Nano Banana 2.1) หรือ `nano-banana-pro` (Gemini 3 Pro Image คุณภาพสูงสุด) ทั้งสามโมเดลรับภาพอ้างอิงได้สูงสุด 10 ภาพ และ[อัปสเกลเป็น 2K/4K](#upscaling-to-2k4k)ได้ บทความ [Nano Banana 2 Lite vs 2.1 vs Pro](/docs/articles/google-flow-nano-banana-compare-th) แสดงผลของทั้งสามโมเดลด้วยพรอมต์เดียวกัน - **Google Flow ยังมี Imagen 4 อยู่ไหม?** บน useapi.net model id `imagen-4` ยังใช้ได้ โค้ดเดิมจึงทำงานต่อได้ แต่ Google นำ Imagen ออกจาก Google Flow ในเดือนกรกฎาคม 2026 คำขอเหล่านั้นจึงสร้างภาพด้วย `nano-banana-2-lite` ซึ่งเป็นโมเดลภาพเริ่มต้นของ Google Flow ตั้งแต่นั้นมา หากต้องการโมเดลอื่น ให้ตั้ง `model` เป็น `nano-banana-2` หรือ `nano-banana-pro` - **ต้องใช้ captcha หรือโปรเจกต์ Google Cloud ไหม?** ผ่าน useapi.net คุณไม่ต้องมีโปรเจกต์ Google Cloud และไม่ต้องแก้ captcha เอง Google Flow ขอ reCAPTCHA ทุกครั้งที่สร้างภาพ และ worker ของ useapi.net จะแก้ให้อัตโนมัติ บัญชี Google Flow แรกของคุณได้สิทธิ์แก้ฟรี 300 ครั้งด้วยคีย์ AntiCaptcha, CapSolver และ EzCaptcha ของเราเอง หลังจากนั้นคุณเพิ่มคีย์ของผู้ให้บริการของคุณเองได้ด้วย [POST /accounts/captcha-providers](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers) สคริปต์ในคู่มือนี้ไม่ได้ส่ง `captchaToken` ### สรุป ติดต่อเราได้ที่ <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> หรือ <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> สำหรับทุกคำถามและข้อสงสัยด้านการใช้งาน ดูตัวอย่างโค้ดได้ใน [GitHub repo](https://github.com/useapi/google-flow-api) ของเรา #### เผยแพร่ที่อื่นด้วย {: .no_toc #cross-posted } เผยแพร่บน [dev.to](https://dev.to/useapi/how-to-generate-nano-banana-2-nano-banana-pro-images-via-the-google-flow-api-1cn2){:rel="nofollow"} (ภาษาอังกฤษ) และแชร์บน [Bluesky](https://bsky.app/profile/useapi.net/post/3mwjbmurnab2e){:rel="nofollow"} ด้วย ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-flow-images-bash-vi === Document URL: https://useapi.net/docs/articles/google-flow-images-bash-vi --- layout: default title: "Cách tạo ảnh Nano Banana 2.1 và Nano Banana Pro qua Google Flow API" description: "Tạo ảnh Nano Banana 2.1, Nano Banana Pro và Nano Banana 2 Lite chỉ với một lệnh POST đồng bộ tới Google Flow API của useapi.net, kèm script Node.js tạo ảnh hàng loạt." keywords: [Nano Banana API, Nano Banana 2.1 API, Nano Banana 2 API, Nano Banana Pro API, Gemini 3.1 Flash Image, Gemini 3 Pro Image, Nano Banana 2 Lite, image-to-image, Google Flow API, API Nano Banana, cách dùng Nano Banana API, tạo ảnh AI bằng API, API tạo ảnh, tạo ảnh từ ảnh, hướng dẫn, code, curl] image: https://media.useapi.net/articles/2026-06-15-google-flow-images-bash/nano-banana-2-lite.jpg parent: Articles nav_exclude: true lang: vi translation_key: google-flow-images date: 2026-06-15 last_modified: 2026-11-06 nav_order: 840 repo: https://github.com/useapi/google-flow-api --- ## Cách tạo ảnh Nano Banana 2.1 và Nano Banana Pro qua Google Flow API {: .no_toc #how-to-generate-nano-banana-21--nano-banana-pro-images-via-the-google-flow-api } 6 phút đọc • 15 tháng 6 năm 2026 (6 tháng 11 năm 2026) useapi.net là API của bên thứ ba, không liên kết với Google và không được Google bảo trợ. ## Mục lục {: .no_toc .text-delta #table-of-contents } ### Giới thiệu Chỉ một lệnh `POST` đồng bộ tới [Google Flow API](/docs/api-google-flow-v1) của useapi.net là bạn nhận về tối đa bốn ảnh Nano Banana 2.1, [Nano Banana Pro](https://deepmind.google/models/gemini-image/pro/) hoặc [Nano Banana 2 Lite](https://deepmind.google/models/gemini-image/flash-lite/), được tạo bằng tài khoản [Google Flow](https://flow.google.com) của bạn. Việc tạo ảnh có sẵn trong mọi [gói Google AI](https://gemini.google/subscriptions/), kể cả tài khoản miễn phí, trong khi Gemini API chính thức tính từ $0,034 đến $0,134 mỗi ảnh (tính đến tháng 11/2026). Không cần dự án Google Cloud, không cần Gemini API key. Hướng dẫn này gồm các model bạn dùng được, mức chênh lệch giá, cách tạo ảnh bằng một lệnh gọi `curl` để sao chép và dùng ngay, và một script Node.js chạy được để tạo ảnh hàng loạt từ danh sách prompt. Muốn xem ba model khác nhau thế nào trên cùng một prompt? Xem [so sánh các model Nano Banana](/docs/articles/google-flow-nano-banana-compare-vi). Cần video? Xem [hướng dẫn Veo 3.1](/docs/articles/google-flow-bash-vi), bài cùng loạt với bài này. ### Các model được hỗ trợ Chọn model cho mỗi request bằng trường `model` (mặc định `nano-banana-2-lite`). Cả ba model đều chạy trên mọi gói Google AI, kể cả tài khoản miễn phí. | Model id | Tên thương mại | Ảnh tham chiếu (I2I) | Tỉ lệ khung hình | Ghi chú | |----------|----------------|-----------------:|---------------|-------| | `nano-banana-2-lite` *(mặc định)* | Nano Banana 2 Lite / Gemini 3.1 Flash-Lite Image | tối đa 10 | 16:9, 4:3, 1:1, 3:4, 9:16, auto<sup>†</sup> | Model ảnh mặc định của Google Flow từ tháng 7/2026. Ở chế độ tạo ảnh từ ảnh vẫn giữ 16:9 nếu bạn không truyền tỉ lệ | | `nano-banana-2` | Nano Banana 2.1 | tối đa 10 | 16:9, 4:3, 1:1, 3:4, 9:16, auto<sup>†</sup> | Mặc định `auto` ở chế độ tạo ảnh từ ảnh | | `nano-banana-pro` | Nano Banana Pro / Gemini 3 Pro Image | tối đa 10 | 16:9, 4:3, 1:1, 3:4, 9:16, auto<sup>†</sup> | Model ảnh chất lượng cao nhất, mặc định `auto` ở chế độ tạo ảnh từ ảnh | <sup>†</sup> `auto` chỉ hợp lệ ở chế độ tạo ảnh từ ảnh (có ít nhất một `reference_*` hoặc `character_*`), khi đó backend lấy tỉ lệ từ ảnh tham chiếu đầu tiên. Khi có nhiều ảnh tham chiếu thì hướng ảnh không được đảm bảo, nên hãy truyền tỉ lệ cụ thể nếu mọi ảnh phải ra cùng một khổ. Cả ba đều nhận `count` (1–4) và `seed` để tái tạo kết quả. Nếu bỏ `model`, API dùng `nano-banana-2-lite`, dù có hay không có ảnh tham chiếu. Hai alias cũ vẫn được chấp nhận: `nano-banana` trỏ tới `nano-banana-2`, còn `imagen-4` trỏ tới `nano-banana-2-lite` (Google đã gỡ Imagen khỏi Google Flow vào tháng 7/2026). Chi tiết và khả năng của từng model có trong tài liệu [POST /images](/docs/api-google-flow-v1/post-google-flow-images). #### Upscale lên 2K/4K Ảnh tạo bằng bất kỳ model nào trong ba model đều có thể upscale bằng [POST /images/upscale](/docs/api-google-flow-v1/post-google-flow-images-upscale): truyền `mediaGenerationId` của ảnh và `resolution` là `2k` (mặc định) hoặc `4k`. Phản hồi là base64 trong `encodedImage`. `2k` chạy trên mọi gói, kể cả tài khoản miễn phí. `4k` cần Google AI Ultra, và trên mọi gói khác sẽ trả về `400` với `4k upscaling is not available for this account` trước khi giải captcha, nên không tốn gì và thử lại cũng vô ích. Cả hai đều không tốn credit Flow. ### Giá Ảnh không tốn credit Flow trên bất kỳ gói Google AI nào, kể cả tài khoản miễn phí, và useapi.net không thu phí theo ảnh. Chỉ cần gói trả phí cho video Omni 1.1 Flash, video Omni 1.2 Flash dài hơn 10 giây, kéo dài video bằng Omni 1.2 và upscale video, còn upscale ảnh `4k` thì cần Ultra. Giá của mọi model trên mọi gói, so với API chính thức, có trong [bảng giá Google Flow](/docs/api-google-flow-v1#pricing). ### Cách tạo ảnh Nano Banana bằng curl Bạn cần một [API token](/docs/start-here/setup-useapi) của useapi.net và một [tài khoản Google Flow](/docs/start-here/setup-google-flow) đã kết nối. Tạo ảnh là thao tác đồng bộ: một lệnh `POST` sẽ chờ đến khi ảnh xong (thường 10–20 giây) và trả ảnh ngay trong phản hồi, nên không có `jobid` nào phải poll. Bước hai chỉ là lưu kết quả, từ URL đã ký, hoặc khi không có URL đó thì từ ảnh base64 nằm ngay trong phản hồi. 1. Gửi prompt — `POST https://api.useapi.net/v1/google-flow/images`: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/images" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Cat dressed like a pirate fencing with a real pirate, pirate looks absolutely terrified, this is happening on a deck of the Disney cruise ship", "model": "nano-banana-pro", "aspectRatio": "16:9", "count": 4, "seed": 123456 }' > response.json ``` Lệnh gọi trả về `200 OK` kèm `jobId` và mảng `media`, mỗi ảnh một phần tử (`count` từ 1 đến 4, mặc định 4). URL tải xuống đã ký của mỗi ảnh nằm ở `media[].image.generatedImage.fifeUrl`: ```json { "jobId": "j1731859345678i-u12345-email:jo***@gmail.com-bot:google-flow", "media": [ { "image": { "generatedImage": { "seed": 123456, "mediaGenerationId": "user:12345-email:6a6f...-image:...", "prompt": "Cat dressed like a pirate fencing with a real pirate, pirate looks absolutely terrified, this is happening on a deck of the Disney cruise ship", "fifeUrl": "https://flow-content.google/image/...", "aspectRatio": "IMAGE_ASPECT_RATIO_LANDSCAPE" } } } ] } ``` 2. Tải ảnh từ `fifeUrl` (URL đã ký chỉ dùng được trong thời gian giới hạn, nên hãy tải ngay). Thỉnh thoảng không có `fifeUrl` và ảnh được trả về dạng base64 trong `encodedImage`, khi đó hãy giải mã trường này: ```bash URL=$(jq -r '.media[0].image.generatedImage.fifeUrl // empty' response.json) if [ -n "$URL" ]; then curl -o image_1.jpg "$URL" else jq -r '.media[0].image.generatedImage.encodedImage' response.json | base64 -d > image_1.jpg fi ``` `mediaGenerationId` của mỗi ảnh đã tạo có thể dùng lại làm ảnh tham chiếu trong request sau, xem [Ảnh tham chiếu và nhân vật](#image-references--characters) bên dưới. Muốn có thêm webhook? Truyền `replyUrl` trong body của request, API sẽ gửi thêm các cập nhật trạng thái job tới URL đó. Bản thân lệnh gọi vẫn chờ đến khi có ảnh. Payload giống phản hồi của [GET /jobs/`jobId`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid), trong đó ảnh đã hoàn tất nằm ở `response.media[].image.generatedImage.fifeUrl`. ### Ảnh tham chiếu và nhân vật Để định hướng ảnh bằng một ảnh có sẵn, trước tiên hãy upload ảnh đó bằng [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email) (byte thô, `Content-Type` dạng ảnh, PNG/JPEG/WebP tối đa 20 MB). Phản hồi upload đặt id tham chiếu lồng ở `mediaGenerationId.mediaGenerationId`, và chuỗi lồng này là thứ bạn truyền lại làm `reference_1` (cả ba model đều nhận tối đa 10 ảnh tham chiếu): ```bash # 1. Upload một ảnh tham chiếu curl -X POST "https://api.useapi.net/v1/google-flow/assets/john%40gmail.com" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: image/jpeg" \ --data-binary @reference.jpeg # Phản hồi: id tham chiếu nằm lồng sâu thêm một cấp: # { # "mediaGenerationId": { # "mediaGenerationId": "user:12345-email:6a6f...-image:ff9aa5cc-..." # }, # "width": 1024, "height": 1024, "email": "jo***@gmail.com" # } # 2. Tạo ảnh với ảnh tham chiếu đó curl -X POST "https://api.useapi.net/v1/google-flow/images" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model": "nano-banana-pro", "prompt": "Make this photograph look modern", "reference_1": "user:12345-email:6a6f...-image:ff9aa5cc-..." }' ``` Để giữ cùng một nhân dạng qua nhiều ảnh, hãy gom 1–2 ảnh tham chiếu thành một nhân vật dùng lại được bằng [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters), rồi truyền id `character` của nó làm `character_1`…`character_7`. Nhân vật kết hợp tự do với `reference_*` và dùng chung giới hạn ảnh tham chiếu của từng model. Bạn cũng có thể chèn các dấu `@reference_1` / `@character_1` ngay trong `prompt` để chỉ chỗ dùng từng ảnh, và mỗi dấu chèn phải có tham số tương ứng trong body. ### Tạo hàng loạt bằng script Để có được bức ảnh ưng ý cần thử rất nhiều lần, và chạy từng lần bằng tay thì mất công. Script Node.js bên dưới đọc danh sách prompt từ `prompts.json`, upload các ảnh tham chiếu, gửi từng request và tải về mọi ảnh trả về, nhờ vậy bạn có thể xếp cả một loạt rồi quay lại chọn ảnh đẹp nhất. Vì `POST /images` là đồng bộ, script lưu từng kết quả ngay khi lệnh gọi trả về. Bạn cần [Node.js](https://nodejs.org) v21 trở lên. Đặt `prompts.json` và `google-flow-images.mjs` trong cùng một thư mục rồi chạy `node ./google-flow-images.mjs API_TOKEN EMAIL`, trong đó `API_TOKEN` là [API token](/docs/start-here/setup-useapi) useapi.net của bạn và `EMAIL` là email của [tài khoản Google Flow](/docs/start-here/setup-google-flow) đã kết nối. Script tự tìm tài khoản theo email và kiểm tra trường `health` trước khi gửi. Muốn clone về và chạy trên máy? Bản đầy đủ của `google-flow-images.mjs` và `prompts.json` có trên GitHub tại [`useapi/google-flow-api`](https://github.com/useapi/google-flow-api/tree/main/images). <details markdown="block"> <summary>Mở `prompts.json`</summary> ```json [ { "prompt": "By default the nano-banana-2-lite model generates 4 image variations at 16:9." }, { "model": "nano-banana-pro", "aspectRatio": "1:1", "count": 2, "seed": 123456, "prompt": "Nano Banana Pro (Gemini 3 Pro Image), two square variations. For all parameters see https://useapi.net/docs/api-google-flow-v1/post-google-flow-images" }, { "model": "nano-banana-2", "aspectRatio": "auto", "reference_1": "./reference_image.jpeg", "prompt": "Image-to-image: pass a local reference file as reference_1 (uploaded automatically). auto aspect ratio derives from the first reference. All three models accept up to 10 references." }, { "model": "nano-banana-2-lite", "aspectRatio": "9:16", "count": 4, "prompt": "Nano Banana 2 Lite portrait. Other models (nano-banana-2, nano-banana-pro) are selectable via the model field — see the POST /images docs." } ] ``` </details> <details markdown="block"> <summary>Mở script `google-flow-images.mjs`</summary> ```javascript /* Script version 1.2, September 11, 2026 Script to batch-generate images using prompts with the Google Flow API v1 by useapi.net 🚀 Uses the synchronous POST /images endpoint (default model: nano-banana-2-lite) and saves each image from fifeUrl, or from encodedImage when fifeUrl is absent. For more details visit https://useapi.net/docs/api-google-flow-v1/post-google-flow-images Installation Instructions: ========================== You need Node.js v21 or newer installed to run this script. Download and install Node.js from: - Windows, macOS, Linux: https://nodejs.org/ After installation, verify by running the following command in a terminal: node -v Running the Script: =================== Usage: node google-flow-images.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE] Replace API_TOKEN with your actual useapi.net API token, see https://useapi.net/docs/start-here/setup-useapi Replace EMAIL with configured Google Flow email account, see https://useapi.net/docs/start-here/setup-google-flow If optional PROMPTS_FILE not provided prompts.json will be used. Example: -------- node google-flow-images.mjs user:1234-abcdefhijklmnopqrstuv my@email.com This command executes the script using API token user:1234-abcdefhijklmnopqrstuv with my@email.com Google Flow account email. Changelog: ========== - June 15, 2026: Initial release. - September 10, 2026: Default model is now nano-banana-2-lite (Google removed Imagen from Flow, and imagen-4 now maps to nano-banana-2-lite). Saves encodedImage when fifeUrl is absent, and accepts .jpg reference images. - September 11, 2026: A prompt whose reference_* file fails to upload is skipped and logged to google-flow-images_errors.txt instead of being submitted without that reference. Writes a downloaded image only once it has been fully received, so a failed download leaves no partial file for the next run to skip as "already exists". */ import fs from 'fs/promises'; import { writeFile } from 'node:fs/promises'; // Constants const ERRORS_FILE = 'google-flow-images_errors.txt'; const DEFAULT_PROMPTS_FILE = 'prompts.json'; const DEFAULT_MODEL = 'nano-banana-2-lite'; const SLEEP_429 = 30 * 1000; // in milliseconds const urlAccounts = 'https://api.useapi.net/v1/google-flow/accounts'; const urlImages = 'https://api.useapi.net/v1/google-flow/images'; const urlUploadAsset = 'https://api.useapi.net/v1/google-flow/assets/'; // Google Flow accepts png, jpeg and webp for reference images. const supportedFileExtensions = ['png', 'jpg', 'jpeg', 'webp']; // reference_1 .. reference_10 are accepted by POST /images. const referenceParams = Array.from({ length: 10 }, (_, i) => `reference_${i + 1}`); // { filename: mediaGenerationId } const uploadedFiles = {}; // Utility to sleep for given milliseconds const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); // Function to fetch configured Google Flow API accounts async function fetchAccounts(apiToken) { const response = await fetch(urlAccounts, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.error(`⛔ Error fetching accounts (HTTP ${response.status}): ${response.statusText}`); process.exit(1); } return response.json(); } const elapsedTimeSec = (start) => (Date.now() - start) / 1000; // Map a file extension to the Content-Type required by POST /assets const contentTypeForExt = (ext) => ext === 'png' ? 'image/png' : ext === 'webp' ? 'image/webp' : 'image/jpeg'; async function uploadAsset(apiToken, email, filename) { // Check if already uploaded if (uploadedFiles.hasOwnProperty(filename)) return uploadedFiles[filename]; const startTime = Date.now(); console.log(`⬆️ Account ${email} uploading file…`, filename); const body = new Blob([await fs.readFile(filename)]); const fileExt = filename.split('.').pop().toLowerCase(); const response = await fetch(`${urlUploadAsset}${encodeURIComponent(email)}`, { method: 'POST', headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}`, 'Content-Type': contentTypeForExt(fileExt) }, body }); if (response.ok) { const json = await response.json(); // POST /assets returns the reference id nested as mediaGenerationId.mediaGenerationId const mediaGenerationId = json?.mediaGenerationId?.mediaGenerationId; console.log(`🆗 mediaGenerationId (${elapsedTimeSec(startTime)} sec)`, mediaGenerationId); uploadedFiles[filename] = mediaGenerationId; } else { console.error(`❗ Unable to upload file HTTP ${response.status} (${elapsedTimeSec(startTime)} sec)`, await response.text()); // Do not attempt to upload failed file again uploadedFiles[filename] = undefined; } return uploadedFiles[filename]; } // Download a single image from its signed fifeUrl. async function downloadImage(url, filename) { try { await fs.access(filename); console.log(`⚠️ ${filename} already exists. Skipping download.`); return; } catch { // File does not exist, proceed with downloading } if (!url) { console.error(`🛑 No fifeUrl for ${filename}`); return; } console.log(`✅ Downloading ${url} to ${filename}`); try { const imageResponse = await fetch(url); if (!imageResponse.ok) { console.error(`⛔ Unable to download ${filename} (HTTP ${imageResponse.status})`, url); return; } // Read the whole body before creating the file, so a failed download leaves no // partial file behind for the next run to skip as "already exists". const data = Buffer.from(await imageResponse.arrayBuffer()); await writeFile(filename, data); } catch (err) { console.error(`⛔ Error during download: ${err}`); } } // Submit a single prompt to the synchronous POST /images endpoint and download the results. async function submitImage(apiToken, email, prompt, index) { const { model, prompt: text } = prompt; const useModel = model ?? DEFAULT_MODEL; console.log(`🚀 ${useModel} » Prompt #${index} • account ${email} …`); // Build the request body, uploading any local reference_* file to a mediaGenerationId first. const body = { model: useModel, email, prompt: text }; for (const key of ['aspectRatio', 'count', 'seed']) if (prompt[key] !== undefined) body[key] = prompt[key]; for (const refKey of referenceParams) { const value = prompt[refKey]; if (value) body[refKey] = await uploadAsset(apiToken, email, value); } // A reference that failed to upload would be left out of the body, and the prompt would still be // generated (and charged) without it. Skip the prompt instead. uploadAsset remembers the failed file, // so a later prompt using it is skipped too, without another upload attempt. const failedUploads = referenceParams.filter(refKey => prompt[refKey] && !body[refKey]); for (const refKey of failedUploads) { console.error(`🛑 Prompt #${index} skipped: ${refKey} ${prompt[refKey]} failed to upload`); await fs.appendFile(ERRORS_FILE, `Upload failed for ${refKey} ${prompt[refKey]},#${index}:${text}\n`); } if (failedUploads.length) return; while (true) { const response = await fetch(urlImages, { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiToken}` }, body: JSON.stringify(body) }); const responseText = await response.text(); if (response.status == 200) { const json = JSON.parse(responseText); const media = json?.media ?? []; if (media.length == 0) console.error(`🛑 200 OK but no media for prompt #${index}:\n${text}\n`); // count > 1 returns multiple images in the media array. for (let i = 0; i < media.length; i++) { const img = media[i]?.image?.generatedImage; const filename = `google-flow_${index}_${i + 1}.jpg`; // fifeUrl is normally present. When it is absent the image arrived inline as base64 in encodedImage. if (!img?.fifeUrl && img?.encodedImage) await fs.writeFile(filename, Buffer.from(img.encodedImage, 'base64')); else await downloadImage(img?.fifeUrl, filename); } return 200; } switch (response.status) { case 429: console.log(`🔄️ Retry on HTTP ${response.status}`, responseText); await sleep(SLEEP_429); break; case 503: console.log(`🔄️ Service unavailable, retry on HTTP ${response.status}`, responseText); await sleep(SLEEP_429); break; case 402: console.log(`🛑 No subscription / insufficient credits`, responseText); await fs.appendFile(ERRORS_FILE, `${response.status},#${index}:${text}\n`); process.exit(1); case 400: case 500: console.log(`🛑 Rejected (validation or content moderation)`, responseText); await fs.appendFile(ERRORS_FILE, `${response.status},#${index}:${text}\n`); return response.status; default: console.log(`❗ FAILED with HTTP ${response.status}`, responseText); await fs.appendFile(ERRORS_FILE, `${response.status},#${index}:${text}\n`); return response.status; } } } // Main function async function main() { const apiToken = process.argv[2]; const email = process.argv[3]; const promptFile = process.argv[4] || DEFAULT_PROMPTS_FILE; if (!apiToken || !email) { console.error('Usage: node google-flow-images.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE]'); process.exit(1); } console.info('Script v1.2'); console.info('Node version is: ' + process.version); const start = new Date(); try { console.info('START EXECUTION', start); await execute(apiToken, email, promptFile); } catch (error) { console.error('⛔ Error during execution:', error.stack || error); } finally { console.info('COMPLETED', new Date()); console.info('EXECUTION ELAPSED', diffInMinutesAndSeconds(start, new Date())); } } async function execute(apiToken, email, promptFile) { const accounts = await fetchAccounts(apiToken); console.info(`Configured Google Flow API accounts (${Object.keys(accounts).length}):`, Object.keys(accounts).join(', ')); if (Object.keys(accounts).length <= 0) { console.error(`⛔ No configured Google Flow accounts found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (!accounts[email]) { console.error(`⛔ Account ${email} not found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (accounts[email].health && accounts[email].health !== 'OK') { console.error(`⛔ Account ${email} health is '${accounts[email].health}'. Please resolve and update the account, see https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } const promptData = await fs.readFile(promptFile, 'utf8'); const prompts = JSON.parse(promptData); console.log(`Total number of prompts to process`, prompts.length); let warnings = []; // Parameters accepted by this script for the POST /images endpoint. // See https://useapi.net/docs/api-google-flow-v1/post-google-flow-images for every model's full parameter set. const supportedParams = ['model', 'prompt', 'aspectRatio', 'count', 'seed', ...referenceParams]; const invalidKeys = (prompt) => Object.keys(prompt).filter(key => !key.startsWith('__') && !supportedParams.includes(key)) for (let i = 1; i <= prompts.length; i++) { const prompt = prompts[i - 1]; const { prompt: text } = prompt; const validateImage = async (file) => { if (file) { try { await fs.access(file); } catch { warnings.push(`⚠️ Image '${file}' does not exist. Prompt ${i}`); } const ext = file.split('.').pop().toLowerCase(); if (!supportedFileExtensions.includes(ext)) warnings.push(`⚠️ Image ${file} extension ${ext} not supported. Prompt ${i}`); } }; const notSupported = invalidKeys(prompt); if (notSupported.length) warnings.push(`⚠️ Following params not supported: ${notSupported.join(',')}. Prompt ${i}`); if (!text) warnings.push(`⚠️ prompt is required. Prompt ${i}`); await Promise.all(referenceParams.map(refKey => validateImage(prompt[refKey]))); } if (warnings.length > 0) { warnings.forEach(warning => console.warn(warning)); console.error(`⛔ Execution stopped due to warnings.`); process.exit(1); } for (let i = 0; i < prompts.length; i++) await submitImage(apiToken, email, prompts[i], i + 1); } function diffInMinutesAndSeconds(date1, date2) { const diffInSeconds = Math.floor((date2 - date1) / 1000); return `${Math.floor(diffInSeconds / 60)} minutes ${diffInSeconds % 60} seconds`; }; main(); ``` </details> ### Ví dụ Ảnh thật được tạo qua chính Google Flow API này bằng Nano Banana Pro và Nano Banana 2 Lite, lấy thẳng từ blog và bài so sánh model của chúng tôi. Nano Banana Pro — tạo ảnh từ văn bản ([nguồn](/blog/251120)): *"Cat dressed like a pirate fencing with a real pirate… on a Disney cruise ship."* ![Kết quả tạo ảnh từ văn bản của Nano Banana Pro](https://media.useapi.net/blog/2025-11-20-251120/nano-banana-pro-text-to-image.jpg) Nano Banana Pro — 5 ảnh tham chiếu ([nguồn](/blog/251201)): năm ảnh chân dung riêng lẻ được ghép thành một ảnh nhóm "K-Pop group victory celebration". ![Ảnh nhóm của Nano Banana Pro từ nhiều ảnh tham chiếu](https://media.useapi.net/blog/2025-12-01-251201/result.jpg) Nano Banana 2 Lite, model mặc định ([nguồn](/docs/articles/google-flow-nano-banana-compare#examples)): prompt người nuôi ong trong bài so sánh ba model, do model nhanh nhất trong ba tạo ở tỉ lệ 9:16. <img src="https://media.useapi.net/articles/2026-06-15-google-flow-images-bash/nano-banana-2-lite.jpg" style="width: 100%; max-width: 420px;" alt="Ảnh người nuôi ong tạo bằng Nano Banana 2 Lite qua Google Flow API" /> ### Câu hỏi thường gặp - **Có API Nano Banana 2 không?** Qua useapi.net thì có: trong [Google Flow API](/docs/api-google-flow-v1), `nano-banana-2` tạo ảnh bằng Nano Banana 2.1, phiên bản mà Google Flow đang chạy, trên mọi gói Google AI hoặc tài khoản miễn phí, không thu phí theo ảnh. Nano Banana 2 (Gemini 3.1 Flash Image) có giá $0,067 mỗi ảnh 1K trên [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) chính thức của Google (tính đến tháng 11/2026). Đây là một endpoint REST thông thường, không cần dự án Cloud. - **Có API Nano Banana Pro không?** Qua useapi.net thì có: Nano Banana Pro (Gemini 3 Pro Image) chạy dưới tên `nano-banana-pro` trên endpoint [POST /images](/docs/api-google-flow-v1/post-google-flow-images), và một request đồng bộ trả về tối đa bốn ảnh, không thu phí theo ảnh. [Gemini API](https://aistudio.google.com/docs/pricing#gemini-3-pro-image) chính thức của Google tính $0,134 cho mỗi ảnh Pro (tính đến tháng 11/2026). - **API mặc định dùng model nào?** Trên useapi.net, mặc định là `nano-banana-2-lite` (Gemini 3.1 Flash-Lite Image), dù có hay không có ảnh tham chiếu. Đổi model cho từng request bằng cách đặt `model` là `nano-banana-2` (Nano Banana 2.1) hoặc `nano-banana-pro` (Gemini 3 Pro Image, chất lượng cao nhất). Cả ba đều nhận tối đa 10 ảnh tham chiếu và có thể [upscale lên 2K/4K](#upscaling-to-2k4k). Bài [Nano Banana 2 Lite vs 2.1 vs Pro](/docs/articles/google-flow-nano-banana-compare-vi) cho thấy cả ba trên cùng một prompt. - **Google Flow còn Imagen 4 không?** Trên useapi.net, model id `imagen-4` vẫn dùng được nên code hiện có vẫn chạy. Nhưng Google đã gỡ Imagen khỏi Google Flow vào tháng 7/2026, nên các request đó giờ tạo ảnh bằng `nano-banana-2-lite`, model ảnh mặc định của Google Flow từ đó đến nay. Muốn chọn model khác, hãy đặt `model` là `nano-banana-2` hoặc `nano-banana-pro`. - **Có cần captcha hay dự án Google Cloud không?** Với useapi.net, bạn không cần dự án Google Cloud, cũng không cần tự giải captcha. Google Flow yêu cầu reCAPTCHA cho mỗi ảnh, và worker của useapi.net tự động giải: tài khoản Google Flow đầu tiên của bạn được 300 lượt giải miễn phí bằng key AntiCaptcha, CapSolver và EzCaptcha của chính chúng tôi, sau đó bạn thêm key nhà cung cấp của riêng mình bằng [POST /accounts/captcha-providers](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers). Script trong hướng dẫn này không gửi `captchaToken`. ### Kết luận Ghé <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> hoặc <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> của chúng tôi cho mọi câu hỏi hỗ trợ. Xem [repo GitHub](https://github.com/useapi/google-flow-api) của chúng tôi với các ví dụ code. #### Đăng ở nơi khác {: .no_toc #cross-posted } Cũng đăng trên [dev.to](https://dev.to/useapi/how-to-generate-nano-banana-2-nano-banana-pro-images-via-the-google-flow-api-1cn2){:rel="nofollow"} (tiếng Anh) và chia sẻ trên [Bluesky](https://bsky.app/profile/useapi.net/post/3mwjbmurnab2e){:rel="nofollow"}. ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-flow-images-bash-zh === Document URL: https://useapi.net/docs/articles/google-flow-images-bash-zh --- layout: default title: "如何通过 Google Flow API 生成 Nano Banana 2.1 和 Nano Banana Pro 图片" description: "通过 useapi.net 的 Google Flow API,只需一次同步 POST 请求即可生成 Nano Banana 2.1、Nano Banana Pro 和 Nano Banana 2 Lite 图片,附 Node.js 批量生成脚本。" keywords: [Nano Banana API, Nano Banana 2.1 API, Nano Banana 2 API, Nano Banana Pro API, Gemini 3.1 Flash Image, Gemini 3 Pro Image, Nano Banana 2 Lite, image-to-image, Google Flow API, Nano Banana API 教程, Nano Banana Pro API 价格, 图片生成 API, AI 生图, 图生图, 无需 Gemini API Key, curl, 中文教程, Chinese tutorial] image: https://media.useapi.net/articles/2026-06-15-google-flow-images-bash/nano-banana-2-lite.jpg parent: Articles nav_exclude: true lang: zh-CN translation_key: google-flow-images date: 2026-06-15 last_modified: 2026-11-06 nav_order: 840 repo: https://github.com/useapi/google-flow-api --- ## 如何通过 Google Flow API 生成 Nano Banana 2.1 和 Nano Banana Pro 图片 {: .no_toc #how-to-generate-nano-banana-21--nano-banana-pro-images-via-the-google-flow-api } 6 分钟阅读 • 2026 年 6 月 15 日(2026 年 11 月 6 日更新) useapi.net 是第三方 API,与 Google 无关联,也未获得 Google 的认可。 ## 目录 {: .no_toc .text-delta #table-of-contents } ### 简介 向 useapi.net 的 [Google Flow API](/docs/api-google-flow-v1) 发送一次同步 `POST` 请求,就能拿到最多四张 Nano Banana 2.1、[Nano Banana Pro](https://deepmind.google/models/gemini-image/pro/) 或 [Nano Banana 2 Lite](https://deepmind.google/models/gemini-image/flash-lite/) 图片,用的是你自己的 [Google Flow](https://flow.google.com) 账号。所有 [Google AI 订阅](https://gemini.google/subscriptions/)都包含图片生成,免费账号也一样,而官方 Gemini API 每张图片收费 $0.034 到 $0.134(截至 2026 年 11 月)。不需要 Google Cloud 项目,也不需要 Gemini API Key。 本指南介绍可用的模型、价格差异、可直接复制的 `curl` 单次调用流程,以及一个从提示词列表批量生成图片的 Node.js 脚本。想看三个模型在同一提示词下的差别,请看 [Nano Banana 模型对比](/docs/articles/google-flow-nano-banana-compare-zh)。需要生成视频?请看 [Google Flow API 中文教程](/docs/articles/google-flow-api-zh)中的 Veo 3.1 部分。 ### 支持的模型 每个请求用 `model` 字段选择模型(默认 `nano-banana-2-lite`)。三个模型在任何 Google AI 订阅上都能用,包括免费账号。 | 模型 ID | 产品名称 | 参考图(图生图) | 宽高比 | 说明 | |----------|----------------|-----------------:|---------------|-------| | `nano-banana-2-lite` *(默认)* | Nano Banana 2 Lite / Gemini 3.1 Flash-Lite Image | 最多 10 张 | 16:9、4:3、1:1、3:4、9:16、auto<sup>†</sup> | 自 2026 年 7 月起是 Google Flow 的默认图片模型。在图生图模式下,如果不指定比例,仍保持 16:9 | | `nano-banana-2` | Nano Banana 2.1 | 最多 10 张 | 16:9、4:3、1:1、3:4、9:16、auto<sup>†</sup> | 图生图模式下默认 `auto` | | `nano-banana-pro` | Nano Banana Pro / Gemini 3 Pro Image | 最多 10 张 | 16:9、4:3、1:1、3:4、9:16、auto<sup>†</sup> | 画质最高的图片模型,图生图模式下默认 `auto` | <sup>†</sup> `auto` 只在图生图模式下有效(至少传入一个 `reference_*` 或 `character_*`),由后端根据第一张参考图确定比例。有多张参考图时,横竖方向不一定一致,所以如果每张图都必须是同一种形状,请明确指定比例。 三个模型都支持 `count`(1–4)和用于复现结果的 `seed`。如果省略 `model`,无论有没有参考图,API 都使用 `nano-banana-2-lite`。两个已弃用的别名仍然可用:`nano-banana` 对应 `nano-banana-2`,`imagen-4` 对应 `nano-banana-2-lite`(Google 已于 2026 年 7 月从 Google Flow 中移除 Imagen)。详细说明和各模型的能力见 [POST /images](/docs/api-google-flow-v1/post-google-flow-images) 参考文档。 #### 放大到 2K/4K 三个模型生成的图片都可以用 [POST /images/upscale](/docs/api-google-flow-v1/post-google-flow-images-upscale) 放大:传入图片的 `mediaGenerationId`,并把 `resolution` 设为 `2k`(默认)或 `4k`。返回结果是 `encodedImage` 中的 base64。`2k` 在任何套餐上都能用,包括免费账号。`4k` 需要 Google AI Ultra,在其他套餐上会在解验证码之前就返回 `400` 和 `4k upscaling is not available for this account`,所以不产生任何费用,重试也没有用。两者都不消耗 Flow 积分。 ### 价格 在任何 Google AI 订阅上(包括免费账号),生成图片都不消耗 Flow 积分,useapi.net 也不按图片收费。只有 Omni 1.1 Flash 视频、超过 10 秒的 Omni 1.2 Flash 视频、用 Omni 1.2 延长视频和视频放大需要付费套餐,`4k` 图片放大需要 Ultra。每个模型在每个套餐上的价格以及与官方 API 的对比,见 [Google Flow 价格表](/docs/api-google-flow-v1#pricing)。 ### 如何用 curl 生成 Nano Banana 图片 你需要一个 useapi.net [API Token](/docs/start-here/setup-useapi) 和一个已连接的 [Google Flow 账号](/docs/start-here/setup-google-flow)。图片生成是同步的:一次 `POST` 会一直等到图片生成完毕(通常 10–20 秒),并在响应中直接返回图片,所以没有需要轮询的 `jobid`。第二步只是保存结果:从签名 URL 下载,如果没有签名 URL,就使用内联的 base64 图片。 1. 提交提示词 — `POST https://api.useapi.net/v1/google-flow/images`: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/images" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Cat dressed like a pirate fencing with a real pirate, pirate looks absolutely terrified, this is happening on a deck of the Disney cruise ship", "model": "nano-banana-pro", "aspectRatio": "16:9", "count": 4, "seed": 123456 }' > response.json ``` 调用返回 `200 OK`,包含 `jobId` 和一个 `media` 数组,每张图片一项(`count` 为 1–4,默认 4)。每张图片的签名下载 URL 位于 `media[].image.generatedImage.fifeUrl`: ```json { "jobId": "j1731859345678i-u12345-email:jo***@gmail.com-bot:google-flow", "media": [ { "image": { "generatedImage": { "seed": 123456, "mediaGenerationId": "user:12345-email:6a6f...-image:...", "prompt": "Cat dressed like a pirate fencing with a real pirate, pirate looks absolutely terrified, this is happening on a deck of the Disney cruise ship", "fifeUrl": "https://flow-content.google/image/...", "aspectRatio": "IMAGE_ASPECT_RATIO_LANDSCAPE" } } } ] } ``` 2. 从 `fifeUrl` 下载图片(签名 URL 的有效期有限,请尽快下载)。偶尔 `fifeUrl` 会缺失,图片改为以 base64 内联在 `encodedImage` 中返回,这时就解码它: ```bash URL=$(jq -r '.media[0].image.generatedImage.fifeUrl // empty' response.json) if [ -n "$URL" ]; then curl -o image_1.jpg "$URL" else jq -r '.media[0].image.generatedImage.encodedImage' response.json | base64 -d > image_1.jpg fi ``` 每张生成图片的 `mediaGenerationId` 都可以在之后的请求中作为参考图重复使用,见下文的[参考图和角色](#image-references--characters)。 还想要 webhook?在请求体中传入 `replyUrl`,API 还会把任务状态更新推送到这个 URL。调用本身仍然会等到图片生成完毕。推送内容与 [GET /jobs/`jobId`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid) 的响应格式相同,完成的图片位于 `response.media[].image.generatedImage.fifeUrl`。 ### 参考图和角色 要用现有图片引导生成,先用 [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email) 上传(原始字节、图片类型的 `Content-Type`,PNG/JPEG/WebP,最大 20 MB)。在上传响应中,参考图 ID 嵌套在 `mediaGenerationId.mediaGenerationId` 里,把这个嵌套的字符串作为 `reference_1` 传回即可(三个模型都最多接受 10 张参考图): ```bash # 1. 上传参考图 curl -X POST "https://api.useapi.net/v1/google-flow/assets/john%40gmail.com" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: image/jpeg" \ --data-binary @reference.jpeg # 响应(参考图 ID 嵌套在下一层): # { # "mediaGenerationId": { # "mediaGenerationId": "user:12345-email:6a6f...-image:ff9aa5cc-..." # }, # "width": 1024, "height": 1024, "email": "jo***@gmail.com" # } # 2. 用这张参考图生成 curl -X POST "https://api.useapi.net/v1/google-flow/images" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model": "nano-banana-pro", "prompt": "Make this photograph look modern", "reference_1": "user:12345-email:6a6f...-image:ff9aa5cc-..." }' ``` 要在多张图片中保持同一人物形象,可以用 [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters) 把 1–2 张参考图打包成可复用的角色,然后把它的 `character` ID 作为 `character_1`…`character_7` 传入。角色可以和 `reference_*` 自由搭配,并共用每个模型的参考图数量上限。你还可以在 `prompt` 中直接写入 `@reference_1` / `@character_1` 标记,指明每张图片在提示词中的位置,每个内联标记都必须有对应的请求体参数。 ### 用脚本批量生成 找到满意的图片往往要试很多次,手动一次次运行很繁琐。下面的 Node.js 脚本从 `prompts.json` 读取提示词列表,上传所需的参考图,逐个提交请求,并下载返回的每一张图片,这样你可以一次排好一批,回头再挑出最好的。由于 `POST /images` 是同步的,脚本会在每次调用返回后立即保存结果。 你需要 [Node.js](https://nodejs.org) v21 或更高版本。把 `prompts.json` 和 `google-flow-images.mjs` 放在同一个文件夹,运行 `node ./google-flow-images.mjs API_TOKEN EMAIL`,其中 `API_TOKEN` 是你的 useapi.net [API Token](/docs/start-here/setup-useapi),`EMAIL` 是已连接的 [Google Flow 账号](/docs/start-here/setup-google-flow)的邮箱。脚本会按邮箱自动查找账号,并在提交前检查它的 `health` 字段。 想克隆到本地运行?完整的 `google-flow-images.mjs` 和 `prompts.json` 在 GitHub 的 [`useapi/google-flow-api`](https://github.com/useapi/google-flow-api/tree/main/images) 中。 <details markdown="block"> <summary>展开 `prompts.json`</summary> ```json [ { "prompt": "By default the nano-banana-2-lite model generates 4 image variations at 16:9." }, { "model": "nano-banana-pro", "aspectRatio": "1:1", "count": 2, "seed": 123456, "prompt": "Nano Banana Pro (Gemini 3 Pro Image), two square variations. For all parameters see https://useapi.net/docs/api-google-flow-v1/post-google-flow-images" }, { "model": "nano-banana-2", "aspectRatio": "auto", "reference_1": "./reference_image.jpeg", "prompt": "Image-to-image: pass a local reference file as reference_1 (uploaded automatically). auto aspect ratio derives from the first reference. All three models accept up to 10 references." }, { "model": "nano-banana-2-lite", "aspectRatio": "9:16", "count": 4, "prompt": "Nano Banana 2 Lite portrait. Other models (nano-banana-2, nano-banana-pro) are selectable via the model field — see the POST /images docs." } ] ``` </details> <details markdown="block"> <summary>展开 `google-flow-images.mjs` 脚本</summary> ```javascript /* Script version 1.2, September 11, 2026 Script to batch-generate images using prompts with the Google Flow API v1 by useapi.net 🚀 Uses the synchronous POST /images endpoint (default model: nano-banana-2-lite) and saves each image from fifeUrl, or from encodedImage when fifeUrl is absent. For more details visit https://useapi.net/docs/api-google-flow-v1/post-google-flow-images Installation Instructions: ========================== You need Node.js v21 or newer installed to run this script. Download and install Node.js from: - Windows, macOS, Linux: https://nodejs.org/ After installation, verify by running the following command in a terminal: node -v Running the Script: =================== Usage: node google-flow-images.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE] Replace API_TOKEN with your actual useapi.net API token, see https://useapi.net/docs/start-here/setup-useapi Replace EMAIL with configured Google Flow email account, see https://useapi.net/docs/start-here/setup-google-flow If optional PROMPTS_FILE not provided prompts.json will be used. Example: -------- node google-flow-images.mjs user:1234-abcdefhijklmnopqrstuv my@email.com This command executes the script using API token user:1234-abcdefhijklmnopqrstuv with my@email.com Google Flow account email. Changelog: ========== - June 15, 2026: Initial release. - September 10, 2026: Default model is now nano-banana-2-lite (Google removed Imagen from Flow, and imagen-4 now maps to nano-banana-2-lite). Saves encodedImage when fifeUrl is absent, and accepts .jpg reference images. - September 11, 2026: A prompt whose reference_* file fails to upload is skipped and logged to google-flow-images_errors.txt instead of being submitted without that reference. Writes a downloaded image only once it has been fully received, so a failed download leaves no partial file for the next run to skip as "already exists". */ import fs from 'fs/promises'; import { writeFile } from 'node:fs/promises'; // Constants const ERRORS_FILE = 'google-flow-images_errors.txt'; const DEFAULT_PROMPTS_FILE = 'prompts.json'; const DEFAULT_MODEL = 'nano-banana-2-lite'; const SLEEP_429 = 30 * 1000; // in milliseconds const urlAccounts = 'https://api.useapi.net/v1/google-flow/accounts'; const urlImages = 'https://api.useapi.net/v1/google-flow/images'; const urlUploadAsset = 'https://api.useapi.net/v1/google-flow/assets/'; // Google Flow accepts png, jpeg and webp for reference images. const supportedFileExtensions = ['png', 'jpg', 'jpeg', 'webp']; // reference_1 .. reference_10 are accepted by POST /images. const referenceParams = Array.from({ length: 10 }, (_, i) => `reference_${i + 1}`); // { filename: mediaGenerationId } const uploadedFiles = {}; // Utility to sleep for given milliseconds const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); // Function to fetch configured Google Flow API accounts async function fetchAccounts(apiToken) { const response = await fetch(urlAccounts, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.error(`⛔ Error fetching accounts (HTTP ${response.status}): ${response.statusText}`); process.exit(1); } return response.json(); } const elapsedTimeSec = (start) => (Date.now() - start) / 1000; // Map a file extension to the Content-Type required by POST /assets const contentTypeForExt = (ext) => ext === 'png' ? 'image/png' : ext === 'webp' ? 'image/webp' : 'image/jpeg'; async function uploadAsset(apiToken, email, filename) { // Check if already uploaded if (uploadedFiles.hasOwnProperty(filename)) return uploadedFiles[filename]; const startTime = Date.now(); console.log(`⬆️ Account ${email} uploading file…`, filename); const body = new Blob([await fs.readFile(filename)]); const fileExt = filename.split('.').pop().toLowerCase(); const response = await fetch(`${urlUploadAsset}${encodeURIComponent(email)}`, { method: 'POST', headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}`, 'Content-Type': contentTypeForExt(fileExt) }, body }); if (response.ok) { const json = await response.json(); // POST /assets returns the reference id nested as mediaGenerationId.mediaGenerationId const mediaGenerationId = json?.mediaGenerationId?.mediaGenerationId; console.log(`🆗 mediaGenerationId (${elapsedTimeSec(startTime)} sec)`, mediaGenerationId); uploadedFiles[filename] = mediaGenerationId; } else { console.error(`❗ Unable to upload file HTTP ${response.status} (${elapsedTimeSec(startTime)} sec)`, await response.text()); // Do not attempt to upload failed file again uploadedFiles[filename] = undefined; } return uploadedFiles[filename]; } // Download a single image from its signed fifeUrl. async function downloadImage(url, filename) { try { await fs.access(filename); console.log(`⚠️ ${filename} already exists. Skipping download.`); return; } catch { // File does not exist, proceed with downloading } if (!url) { console.error(`🛑 No fifeUrl for ${filename}`); return; } console.log(`✅ Downloading ${url} to ${filename}`); try { const imageResponse = await fetch(url); if (!imageResponse.ok) { console.error(`⛔ Unable to download ${filename} (HTTP ${imageResponse.status})`, url); return; } // Read the whole body before creating the file, so a failed download leaves no // partial file behind for the next run to skip as "already exists". const data = Buffer.from(await imageResponse.arrayBuffer()); await writeFile(filename, data); } catch (err) { console.error(`⛔ Error during download: ${err}`); } } // Submit a single prompt to the synchronous POST /images endpoint and download the results. async function submitImage(apiToken, email, prompt, index) { const { model, prompt: text } = prompt; const useModel = model ?? DEFAULT_MODEL; console.log(`🚀 ${useModel} » Prompt #${index} • account ${email} …`); // Build the request body, uploading any local reference_* file to a mediaGenerationId first. const body = { model: useModel, email, prompt: text }; for (const key of ['aspectRatio', 'count', 'seed']) if (prompt[key] !== undefined) body[key] = prompt[key]; for (const refKey of referenceParams) { const value = prompt[refKey]; if (value) body[refKey] = await uploadAsset(apiToken, email, value); } // A reference that failed to upload would be left out of the body, and the prompt would still be // generated (and charged) without it. Skip the prompt instead. uploadAsset remembers the failed file, // so a later prompt using it is skipped too, without another upload attempt. const failedUploads = referenceParams.filter(refKey => prompt[refKey] && !body[refKey]); for (const refKey of failedUploads) { console.error(`🛑 Prompt #${index} skipped: ${refKey} ${prompt[refKey]} failed to upload`); await fs.appendFile(ERRORS_FILE, `Upload failed for ${refKey} ${prompt[refKey]},#${index}:${text}\n`); } if (failedUploads.length) return; while (true) { const response = await fetch(urlImages, { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiToken}` }, body: JSON.stringify(body) }); const responseText = await response.text(); if (response.status == 200) { const json = JSON.parse(responseText); const media = json?.media ?? []; if (media.length == 0) console.error(`🛑 200 OK but no media for prompt #${index}:\n${text}\n`); // count > 1 returns multiple images in the media array. for (let i = 0; i < media.length; i++) { const img = media[i]?.image?.generatedImage; const filename = `google-flow_${index}_${i + 1}.jpg`; // fifeUrl is normally present. When it is absent the image arrived inline as base64 in encodedImage. if (!img?.fifeUrl && img?.encodedImage) await fs.writeFile(filename, Buffer.from(img.encodedImage, 'base64')); else await downloadImage(img?.fifeUrl, filename); } return 200; } switch (response.status) { case 429: console.log(`🔄️ Retry on HTTP ${response.status}`, responseText); await sleep(SLEEP_429); break; case 503: console.log(`🔄️ Service unavailable, retry on HTTP ${response.status}`, responseText); await sleep(SLEEP_429); break; case 402: console.log(`🛑 No subscription / insufficient credits`, responseText); await fs.appendFile(ERRORS_FILE, `${response.status},#${index}:${text}\n`); process.exit(1); case 400: case 500: console.log(`🛑 Rejected (validation or content moderation)`, responseText); await fs.appendFile(ERRORS_FILE, `${response.status},#${index}:${text}\n`); return response.status; default: console.log(`❗ FAILED with HTTP ${response.status}`, responseText); await fs.appendFile(ERRORS_FILE, `${response.status},#${index}:${text}\n`); return response.status; } } } // Main function async function main() { const apiToken = process.argv[2]; const email = process.argv[3]; const promptFile = process.argv[4] || DEFAULT_PROMPTS_FILE; if (!apiToken || !email) { console.error('Usage: node google-flow-images.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE]'); process.exit(1); } console.info('Script v1.2'); console.info('Node version is: ' + process.version); const start = new Date(); try { console.info('START EXECUTION', start); await execute(apiToken, email, promptFile); } catch (error) { console.error('⛔ Error during execution:', error.stack || error); } finally { console.info('COMPLETED', new Date()); console.info('EXECUTION ELAPSED', diffInMinutesAndSeconds(start, new Date())); } } async function execute(apiToken, email, promptFile) { const accounts = await fetchAccounts(apiToken); console.info(`Configured Google Flow API accounts (${Object.keys(accounts).length}):`, Object.keys(accounts).join(', ')); if (Object.keys(accounts).length <= 0) { console.error(`⛔ No configured Google Flow accounts found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (!accounts[email]) { console.error(`⛔ Account ${email} not found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (accounts[email].health && accounts[email].health !== 'OK') { console.error(`⛔ Account ${email} health is '${accounts[email].health}'. Please resolve and update the account, see https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } const promptData = await fs.readFile(promptFile, 'utf8'); const prompts = JSON.parse(promptData); console.log(`Total number of prompts to process`, prompts.length); let warnings = []; // Parameters accepted by this script for the POST /images endpoint. // See https://useapi.net/docs/api-google-flow-v1/post-google-flow-images for every model's full parameter set. const supportedParams = ['model', 'prompt', 'aspectRatio', 'count', 'seed', ...referenceParams]; const invalidKeys = (prompt) => Object.keys(prompt).filter(key => !key.startsWith('__') && !supportedParams.includes(key)) for (let i = 1; i <= prompts.length; i++) { const prompt = prompts[i - 1]; const { prompt: text } = prompt; const validateImage = async (file) => { if (file) { try { await fs.access(file); } catch { warnings.push(`⚠️ Image '${file}' does not exist. Prompt ${i}`); } const ext = file.split('.').pop().toLowerCase(); if (!supportedFileExtensions.includes(ext)) warnings.push(`⚠️ Image ${file} extension ${ext} not supported. Prompt ${i}`); } }; const notSupported = invalidKeys(prompt); if (notSupported.length) warnings.push(`⚠️ Following params not supported: ${notSupported.join(',')}. Prompt ${i}`); if (!text) warnings.push(`⚠️ prompt is required. Prompt ${i}`); await Promise.all(referenceParams.map(refKey => validateImage(prompt[refKey]))); } if (warnings.length > 0) { warnings.forEach(warning => console.warn(warning)); console.error(`⛔ Execution stopped due to warnings.`); process.exit(1); } for (let i = 0; i < prompts.length; i++) await submitImage(apiToken, email, prompts[i], i + 1); } function diffInMinutesAndSeconds(date1, date2) { const diffInSeconds = Math.floor((date2 - date1) / 1000); return `${Math.floor(diffInSeconds / 60)} minutes ${diffInSeconds % 60} seconds`; }; main(); ``` </details> ### 示例 以下是通过同一个 Google Flow API 用 Nano Banana Pro 和 Nano Banana 2 Lite 生成的真实图片,直接取自我们的博客和模型对比。 Nano Banana Pro 文生图([来源](/blog/251120)):*"Cat dressed like a pirate fencing with a real pirate… on a Disney cruise ship."* ![Nano Banana Pro 文生图结果](https://media.useapi.net/blog/2025-11-20-251120/nano-banana-pro-text-to-image.jpg) Nano Banana Pro 使用 5 张参考图([来源](/blog/251201)):把五张单人肖像合成一张“K-Pop group victory celebration”合影。 ![Nano Banana Pro 多参考图合影](https://media.useapi.net/blog/2025-12-01-251201/result.jpg) Nano Banana 2 Lite,默认模型([来源](/docs/articles/google-flow-nano-banana-compare#examples)):三模型对比中的养蜂人提示词,由三者中速度最快的这个模型以 9:16 生成。 <img src="https://media.useapi.net/articles/2026-06-15-google-flow-images-bash/nano-banana-2-lite.jpg" style="width: 100%; max-width: 420px;" alt="通过 Google Flow API 用 Nano Banana 2 Lite 生成的养蜂人图片" /> ### 常见问题 - **有 Nano Banana 2 API 吗?** 通过 useapi.net 就有:在 [Google Flow API](/docs/api-google-flow-v1) 中,`nano-banana-2` 用 Nano Banana 2.1(Google Flow 使用的版本)生成图片,任何 Google AI 订阅或免费账号都能用,不按图片收费。在 Google 官方的 [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) 上,Nano Banana 2(Gemini 3.1 Flash Image)每张 1K 图片 $0.067(截至 2026 年 11 月)。它是标准的 REST 接口,不需要 Cloud 项目。 - **有 Nano Banana Pro API 吗?** 通过 useapi.net 就有:Nano Banana Pro(Gemini 3 Pro Image)在 [POST /images](/docs/api-google-flow-v1/post-google-flow-images) 接口上以 `nano-banana-pro` 运行,一次同步请求最多返回四张图片,不按图片收费。Google 官方的 [Gemini API](https://aistudio.google.com/docs/pricing#gemini-3-pro-image) 每张 Pro 图片收费 $0.134(截至 2026 年 11 月)。 - **API 默认使用哪个模型?** 在 useapi.net 上,无论有没有参考图,默认都是 `nano-banana-2-lite`(Gemini 3.1 Flash-Lite Image)。每个请求都可以把 `model` 设为 `nano-banana-2`(Nano Banana 2.1)或 `nano-banana-pro`(Gemini 3 Pro Image,画质最高)来切换。三个模型都最多接受 10 张参考图,也都可以[放大到 2K/4K](#upscaling-to-2k4k)。[Nano Banana 2 Lite vs 2.1 vs Pro](/docs/articles/google-flow-nano-banana-compare-zh)展示了三个模型在同一提示词下的效果。 - **Google Flow 里还能用 Imagen 4 吗?** 在 useapi.net 上,`imagen-4` 这个模型 ID 仍然可用,现有代码可以继续运行。但 Google 已于 2026 年 7 月从 Google Flow 中移除 Imagen,这些请求现在改用 `nano-banana-2-lite` 生成图片,它从那时起就是 Google Flow 的默认图片模型。要换用其他模型,把 `model` 设为 `nano-banana-2` 或 `nano-banana-pro`。 - **需要验证码或 Google Cloud 项目吗?** 通过 useapi.net,既不需要 Google Cloud 项目,也不需要自己处理验证码。Google Flow 每生成一张图片都要求 reCAPTCHA,useapi.net 的 worker 会自动解决:你的第一个 Google Flow 账号自带 300 次免费解码,使用我们自己的 AntiCaptcha、CapSolver 和 EzCaptcha 密钥,之后再用 [POST /accounts/captcha-providers](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers) 添加你自己的服务商密钥。本指南中的脚本不发送 `captchaToken`。 ### 结语 有问题欢迎加入我们的 <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord 服务器</a> 或 <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram 频道</a>。 代码示例见我们的 [GitHub 仓库](https://github.com/useapi/google-flow-api)。 #### 其他发布平台 {: .no_toc #cross-posted } 本文英文版也发布在 [dev.to](https://dev.to/useapi/how-to-generate-nano-banana-2-nano-banana-pro-images-via-the-google-flow-api-1cn2){:rel="nofollow"},并分享到了 [Bluesky](https://bsky.app/profile/useapi.net/post/3mwjbmurnab2e){:rel="nofollow"}。 ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-flow-images-bash === Document URL: https://useapi.net/docs/articles/google-flow-images-bash --- layout: default title: How to Generate Nano Banana 2.1 & Nano Banana Pro Images via the Google Flow API description: "Generate Nano Banana 2.1, Nano Banana Pro and Nano Banana 2 Lite images with one synchronous POST to the useapi.net Google Flow API, plus a Node.js batch script." keywords: [Nano Banana API, Nano Banana 2.1 API, Nano Banana 2 API, Nano Banana Pro API, Gemini 3.1 Flash Image, Gemini 3 Pro Image, Nano Banana 2 Lite, image-to-image, Google Flow API, tutorial, code] image: https://media.useapi.net/articles/2026-06-15-google-flow-images-bash/nano-banana-2-lite.jpg parent: Articles nav_exclude: true date: 2026-06-15 last_modified: 2026-11-06 nav_order: 840 repo: https://github.com/useapi/google-flow-api translation_key: google-flow-images --- ## How to Generate Nano Banana 2.1 & Nano Banana Pro Images via the Google Flow API 6 min read • June 15, 2026 (November 6, 2026) ## Table of contents ### Introduction One synchronous `POST` to the useapi.net [Google Flow API](/docs/api-google-flow-v1) returns up to four Nano Banana 2.1, [Nano Banana Pro](https://deepmind.google/models/gemini-image/pro/) or [Nano Banana 2 Lite](https://deepmind.google/models/gemini-image/flash-lite/) images, made with your [Google Flow](https://flow.google.com) account. Images are included on every [Google AI subscription](https://gemini.google/subscriptions/), a free account too, where the official Gemini API charges $0.034 to $0.134 per image (as of November 2026). There's no Google Cloud project and no Gemini API key. This guide covers the models you get, the price difference, the single-call image workflow with copy-paste `curl`, and a runnable Node.js script that batch-generates from a list of prompts. Want to see how the three models differ on one prompt? See the [Nano Banana model comparison](/docs/articles/google-flow-nano-banana-compare). Need video instead? See the sibling [Veo 3.1 tutorial](/docs/articles/google-flow-bash). ### Supported models Pick a model per request with the `model` field (default `nano-banana-2-lite`). All three models work on any Google AI subscription — including a free account. | Model id | Marketing name | References (I2I) | Aspect ratios | Notes | |----------|----------------|-----------------:|---------------|-------| | `nano-banana-2-lite` *(default)* | Nano Banana 2 Lite / Gemini 3.1 Flash-Lite Image | max 10 | 16:9, 4:3, 1:1, 3:4, 9:16, auto<sup>†</sup> | Google Flow's default image model since July 2026 — stays at 16:9 in image-to-image mode unless you pass a ratio | | `nano-banana-2` | Nano Banana 2.1 | max 10 | 16:9, 4:3, 1:1, 3:4, 9:16, auto<sup>†</sup> | Defaults to `auto` in image-to-image mode | | `nano-banana-pro` | Nano Banana Pro / Gemini 3 Pro Image | max 10 | 16:9, 4:3, 1:1, 3:4, 9:16, auto<sup>†</sup> | Highest-quality image model — defaults to `auto` in image-to-image mode | <sup>†</sup> `auto` is valid only in image-to-image mode (at least one `reference_*` or `character_*` supplied) — the backend derives the ratio from the first reference image. With several references the orientation is not guaranteed, so pass an explicit ratio when every image must come back in the same shape. All three accept `count` (1–4) and `seed` for reproducibility. If you omit `model`, the API uses `nano-banana-2-lite`, with or without references. Two deprecated aliases are still accepted: `nano-banana` maps to `nano-banana-2`, and `imagen-4` maps to `nano-banana-2-lite` (Google removed Imagen from Flow in July 2026). Details and per-model capabilities are in the [POST /images](/docs/api-google-flow-v1/post-google-flow-images) reference. #### Upscaling to 2K/4K Images generated with any of the three models can be upscaled with [POST /images/upscale](/docs/api-google-flow-v1/post-google-flow-images-upscale): pass the image's `mediaGenerationId` and a `resolution` of `2k` (default) or `4k`. The response is base64 in `encodedImage`. `2k` works on any plan, a free account included. `4k` needs Google AI Ultra, and on any other plan it answers `400` with `4k upscaling is not available for this account` before a captcha is solved, so it costs nothing and retrying won't help. Both are free of Flow credits. ### Pricing Images cost no Flow credits on any Google AI subscription, a free account included, and useapi.net adds no per-image charge. A paid plan is needed only for Omni 1.1 Flash video, Omni 1.2 Flash video longer than 10 seconds, extending with Omni 1.2 and video upscales, and `4k` image upscales need Ultra. The price of every model on every plan, against the official API, is in the [Google Flow price table](/docs/api-google-flow-v1#pricing). ### How to generate a Nano Banana image with curl You need a useapi.net [API token](/docs/start-here/setup-useapi) and a connected [Google Flow account](/docs/start-here/setup-google-flow). Image generation is synchronous — one `POST` blocks until the images are ready (typically 10–20 seconds) and returns them in the response, so there's no `jobid` to poll. Step two is just saving the result, from the signed URL or, when that is missing, the inline base64 image. 1. Submit the prompt — `POST https://api.useapi.net/v1/google-flow/images`: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/images" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Cat dressed like a pirate fencing with a real pirate, pirate looks absolutely terrified, this is happening on a deck of the Disney cruise ship", "model": "nano-banana-pro", "aspectRatio": "16:9", "count": 4, "seed": 123456 }' > response.json ``` The call returns `200 OK` with a `jobId` and a `media` array — one entry per image (`count` is 1–4, default 4). Each image's signed download URL is at `media[].image.generatedImage.fifeUrl`: ```json { "jobId": "j1731859345678i-u12345-email:jo***@gmail.com-bot:google-flow", "media": [ { "image": { "generatedImage": { "seed": 123456, "mediaGenerationId": "user:12345-email:6a6f...-image:...", "prompt": "Cat dressed like a pirate fencing with a real pirate, pirate looks absolutely terrified, this is happening on a deck of the Disney cruise ship", "fifeUrl": "https://flow-content.google/image/...", "aspectRatio": "IMAGE_ASPECT_RATIO_LANDSCAPE" } } } ] } ``` 2. Download the image from `fifeUrl` (the signed URL is valid for a limited time, so download promptly). Once in a while `fifeUrl` is absent and the image comes back inline as base64 in `encodedImage` instead, so fall back to decoding that: ```bash URL=$(jq -r '.media[0].image.generatedImage.fifeUrl // empty' response.json) if [ -n "$URL" ]; then curl -o image_1.jpg "$URL" else jq -r '.media[0].image.generatedImage.encodedImage' response.json | base64 -d > image_1.jpg fi ``` Each generated image's `mediaGenerationId` can be reused as a reference in a later request — see [Image references & characters](#image-references--characters) below. Want a webhook as well? Pass a `replyUrl` in the request body and the API also posts job status updates to that URL. The call itself still waits for the images. The payload matches the [GET /jobs/`jobId`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid) response, where a completed image lives at `response.media[].image.generatedImage.fifeUrl`. ### Image references & characters To steer an image with an existing picture, upload it first with [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email) (raw bytes, an image `Content-Type`, PNG/JPEG/WebP up to 20 MB). The upload response nests the reference id at `mediaGenerationId.mediaGenerationId` — that nested string is what you pass back as `reference_1` (each of the three models accepts up to 10 references): ```bash # 1. Upload a reference image curl -X POST "https://api.useapi.net/v1/google-flow/assets/john%40gmail.com" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: image/jpeg" \ --data-binary @reference.jpeg # Response — the reference id is nested one level deep: # { # "mediaGenerationId": { # "mediaGenerationId": "user:12345-email:6a6f...-image:ff9aa5cc-..." # }, # "width": 1024, "height": 1024, "email": "jo***@gmail.com" # } # 2. Generate using that reference curl -X POST "https://api.useapi.net/v1/google-flow/images" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model": "nano-banana-pro", "prompt": "Make this photograph look modern", "reference_1": "user:12345-email:6a6f...-image:ff9aa5cc-..." }' ``` For consistent identity across many images, bundle 1–2 reference images into a reusable character with [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters), then pass its `character` id as `character_1`…`character_7`. Characters mix freely with `reference_*` and share the same per-model image-ref budget. You can also drop `@reference_1` / `@character_1` markers inline in the `prompt` for positional grounding — each inline marker must have a matching body param. ### Batch-generate with a script Finding the right image takes many attempts, and running them by hand is tedious. The Node.js script below reads a list of prompts from `prompts.json`, uploads any reference images, submits each request, and downloads every returned image — so you can queue a batch and come back to the winners. Because `POST /images` is synchronous, the script writes each result as soon as the call returns. You need [Node.js](https://nodejs.org) v21 or newer. Put `prompts.json` and `google-flow-images.mjs` in the same folder and run `node ./google-flow-images.mjs API_TOKEN EMAIL`, where `API_TOKEN` is your useapi.net [API token](/docs/start-here/setup-useapi) and `EMAIL` is your connected [Google Flow account](/docs/start-here/setup-google-flow) email. The script looks the account up by email automatically and checks its `health` field before submitting. Prefer to clone and run it locally? The complete `google-flow-images.mjs` and `prompts.json` are on GitHub in [`useapi/google-flow-api`](https://github.com/useapi/google-flow-api/tree/main/images). <details markdown="block"> <summary>Expand `prompts.json`</summary> ```json [ { "prompt": "By default the nano-banana-2-lite model generates 4 image variations at 16:9." }, { "model": "nano-banana-pro", "aspectRatio": "1:1", "count": 2, "seed": 123456, "prompt": "Nano Banana Pro (Gemini 3 Pro Image), two square variations. For all parameters see https://useapi.net/docs/api-google-flow-v1/post-google-flow-images" }, { "model": "nano-banana-2", "aspectRatio": "auto", "reference_1": "./reference_image.jpeg", "prompt": "Image-to-image: pass a local reference file as reference_1 (uploaded automatically). auto aspect ratio derives from the first reference. All three models accept up to 10 references." }, { "model": "nano-banana-2-lite", "aspectRatio": "9:16", "count": 4, "prompt": "Nano Banana 2 Lite portrait. Other models (nano-banana-2, nano-banana-pro) are selectable via the model field — see the POST /images docs." } ] ``` </details> <details markdown="block"> <summary>Expand `google-flow-images.mjs` script</summary> ```javascript /* Script version 1.2, September 11, 2026 Script to batch-generate images using prompts with the Google Flow API v1 by useapi.net 🚀 Uses the synchronous POST /images endpoint (default model: nano-banana-2-lite) and saves each image from fifeUrl, or from encodedImage when fifeUrl is absent. For more details visit https://useapi.net/docs/api-google-flow-v1/post-google-flow-images Installation Instructions: ========================== You need Node.js v21 or newer installed to run this script. Download and install Node.js from: - Windows, macOS, Linux: https://nodejs.org/ After installation, verify by running the following command in a terminal: node -v Running the Script: =================== Usage: node google-flow-images.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE] Replace API_TOKEN with your actual useapi.net API token, see https://useapi.net/docs/start-here/setup-useapi Replace EMAIL with configured Google Flow email account, see https://useapi.net/docs/start-here/setup-google-flow If optional PROMPTS_FILE not provided prompts.json will be used. Example: -------- node google-flow-images.mjs user:1234-abcdefhijklmnopqrstuv my@email.com This command executes the script using API token user:1234-abcdefhijklmnopqrstuv with my@email.com Google Flow account email. Changelog: ========== - June 15, 2026: Initial release. - September 10, 2026: Default model is now nano-banana-2-lite (Google removed Imagen from Flow, and imagen-4 now maps to nano-banana-2-lite). Saves encodedImage when fifeUrl is absent, and accepts .jpg reference images. - September 11, 2026: A prompt whose reference_* file fails to upload is skipped and logged to google-flow-images_errors.txt instead of being submitted without that reference. Writes a downloaded image only once it has been fully received, so a failed download leaves no partial file for the next run to skip as "already exists". */ import fs from 'fs/promises'; import { writeFile } from 'node:fs/promises'; // Constants const ERRORS_FILE = 'google-flow-images_errors.txt'; const DEFAULT_PROMPTS_FILE = 'prompts.json'; const DEFAULT_MODEL = 'nano-banana-2-lite'; const SLEEP_429 = 30 * 1000; // in milliseconds const urlAccounts = 'https://api.useapi.net/v1/google-flow/accounts'; const urlImages = 'https://api.useapi.net/v1/google-flow/images'; const urlUploadAsset = 'https://api.useapi.net/v1/google-flow/assets/'; // Google Flow accepts png, jpeg and webp for reference images. const supportedFileExtensions = ['png', 'jpg', 'jpeg', 'webp']; // reference_1 .. reference_10 are accepted by POST /images. const referenceParams = Array.from({ length: 10 }, (_, i) => `reference_${i + 1}`); // { filename: mediaGenerationId } const uploadedFiles = {}; // Utility to sleep for given milliseconds const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); // Function to fetch configured Google Flow API accounts async function fetchAccounts(apiToken) { const response = await fetch(urlAccounts, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.error(`⛔ Error fetching accounts (HTTP ${response.status}): ${response.statusText}`); process.exit(1); } return response.json(); } const elapsedTimeSec = (start) => (Date.now() - start) / 1000; // Map a file extension to the Content-Type required by POST /assets const contentTypeForExt = (ext) => ext === 'png' ? 'image/png' : ext === 'webp' ? 'image/webp' : 'image/jpeg'; async function uploadAsset(apiToken, email, filename) { // Check if already uploaded if (uploadedFiles.hasOwnProperty(filename)) return uploadedFiles[filename]; const startTime = Date.now(); console.log(`⬆️ Account ${email} uploading file…`, filename); const body = new Blob([await fs.readFile(filename)]); const fileExt = filename.split('.').pop().toLowerCase(); const response = await fetch(`${urlUploadAsset}${encodeURIComponent(email)}`, { method: 'POST', headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}`, 'Content-Type': contentTypeForExt(fileExt) }, body }); if (response.ok) { const json = await response.json(); // POST /assets returns the reference id nested as mediaGenerationId.mediaGenerationId const mediaGenerationId = json?.mediaGenerationId?.mediaGenerationId; console.log(`🆗 mediaGenerationId (${elapsedTimeSec(startTime)} sec)`, mediaGenerationId); uploadedFiles[filename] = mediaGenerationId; } else { console.error(`❗ Unable to upload file HTTP ${response.status} (${elapsedTimeSec(startTime)} sec)`, await response.text()); // Do not attempt to upload failed file again uploadedFiles[filename] = undefined; } return uploadedFiles[filename]; } // Download a single image from its signed fifeUrl. async function downloadImage(url, filename) { try { await fs.access(filename); console.log(`⚠️ ${filename} already exists. Skipping download.`); return; } catch { // File does not exist, proceed with downloading } if (!url) { console.error(`🛑 No fifeUrl for ${filename}`); return; } console.log(`✅ Downloading ${url} to ${filename}`); try { const imageResponse = await fetch(url); if (!imageResponse.ok) { console.error(`⛔ Unable to download ${filename} (HTTP ${imageResponse.status})`, url); return; } // Read the whole body before creating the file, so a failed download leaves no // partial file behind for the next run to skip as "already exists". const data = Buffer.from(await imageResponse.arrayBuffer()); await writeFile(filename, data); } catch (err) { console.error(`⛔ Error during download: ${err}`); } } // Submit a single prompt to the synchronous POST /images endpoint and download the results. async function submitImage(apiToken, email, prompt, index) { const { model, prompt: text } = prompt; const useModel = model ?? DEFAULT_MODEL; console.log(`🚀 ${useModel} » Prompt #${index} • account ${email} …`); // Build the request body, uploading any local reference_* file to a mediaGenerationId first. const body = { model: useModel, email, prompt: text }; for (const key of ['aspectRatio', 'count', 'seed']) if (prompt[key] !== undefined) body[key] = prompt[key]; for (const refKey of referenceParams) { const value = prompt[refKey]; if (value) body[refKey] = await uploadAsset(apiToken, email, value); } // A reference that failed to upload would be left out of the body, and the prompt would still be // generated (and charged) without it. Skip the prompt instead. uploadAsset remembers the failed file, // so a later prompt using it is skipped too, without another upload attempt. const failedUploads = referenceParams.filter(refKey => prompt[refKey] && !body[refKey]); for (const refKey of failedUploads) { console.error(`🛑 Prompt #${index} skipped: ${refKey} ${prompt[refKey]} failed to upload`); await fs.appendFile(ERRORS_FILE, `Upload failed for ${refKey} ${prompt[refKey]},#${index}:${text}\n`); } if (failedUploads.length) return; while (true) { const response = await fetch(urlImages, { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiToken}` }, body: JSON.stringify(body) }); const responseText = await response.text(); if (response.status == 200) { const json = JSON.parse(responseText); const media = json?.media ?? []; if (media.length == 0) console.error(`🛑 200 OK but no media for prompt #${index}:\n${text}\n`); // count > 1 returns multiple images in the media array. for (let i = 0; i < media.length; i++) { const img = media[i]?.image?.generatedImage; const filename = `google-flow_${index}_${i + 1}.jpg`; // fifeUrl is normally present. When it is absent the image arrived inline as base64 in encodedImage. if (!img?.fifeUrl && img?.encodedImage) await fs.writeFile(filename, Buffer.from(img.encodedImage, 'base64')); else await downloadImage(img?.fifeUrl, filename); } return 200; } switch (response.status) { case 429: console.log(`🔄️ Retry on HTTP ${response.status}`, responseText); await sleep(SLEEP_429); break; case 503: console.log(`🔄️ Service unavailable, retry on HTTP ${response.status}`, responseText); await sleep(SLEEP_429); break; case 402: console.log(`🛑 No subscription / insufficient credits`, responseText); await fs.appendFile(ERRORS_FILE, `${response.status},#${index}:${text}\n`); process.exit(1); case 400: case 500: console.log(`🛑 Rejected (validation or content moderation)`, responseText); await fs.appendFile(ERRORS_FILE, `${response.status},#${index}:${text}\n`); return response.status; default: console.log(`❗ FAILED with HTTP ${response.status}`, responseText); await fs.appendFile(ERRORS_FILE, `${response.status},#${index}:${text}\n`); return response.status; } } } // Main function async function main() { const apiToken = process.argv[2]; const email = process.argv[3]; const promptFile = process.argv[4] || DEFAULT_PROMPTS_FILE; if (!apiToken || !email) { console.error('Usage: node google-flow-images.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE]'); process.exit(1); } console.info('Script v1.2'); console.info('Node version is: ' + process.version); const start = new Date(); try { console.info('START EXECUTION', start); await execute(apiToken, email, promptFile); } catch (error) { console.error('⛔ Error during execution:', error.stack || error); } finally { console.info('COMPLETED', new Date()); console.info('EXECUTION ELAPSED', diffInMinutesAndSeconds(start, new Date())); } } async function execute(apiToken, email, promptFile) { const accounts = await fetchAccounts(apiToken); console.info(`Configured Google Flow API accounts (${Object.keys(accounts).length}):`, Object.keys(accounts).join(', ')); if (Object.keys(accounts).length <= 0) { console.error(`⛔ No configured Google Flow accounts found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (!accounts[email]) { console.error(`⛔ Account ${email} not found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (accounts[email].health && accounts[email].health !== 'OK') { console.error(`⛔ Account ${email} health is '${accounts[email].health}'. Please resolve and update the account, see https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } const promptData = await fs.readFile(promptFile, 'utf8'); const prompts = JSON.parse(promptData); console.log(`Total number of prompts to process`, prompts.length); let warnings = []; // Parameters accepted by this script for the POST /images endpoint. // See https://useapi.net/docs/api-google-flow-v1/post-google-flow-images for every model's full parameter set. const supportedParams = ['model', 'prompt', 'aspectRatio', 'count', 'seed', ...referenceParams]; const invalidKeys = (prompt) => Object.keys(prompt).filter(key => !key.startsWith('__') && !supportedParams.includes(key)) for (let i = 1; i <= prompts.length; i++) { const prompt = prompts[i - 1]; const { prompt: text } = prompt; const validateImage = async (file) => { if (file) { try { await fs.access(file); } catch { warnings.push(`⚠️ Image '${file}' does not exist. Prompt ${i}`); } const ext = file.split('.').pop().toLowerCase(); if (!supportedFileExtensions.includes(ext)) warnings.push(`⚠️ Image ${file} extension ${ext} not supported. Prompt ${i}`); } }; const notSupported = invalidKeys(prompt); if (notSupported.length) warnings.push(`⚠️ Following params not supported: ${notSupported.join(',')}. Prompt ${i}`); if (!text) warnings.push(`⚠️ prompt is required. Prompt ${i}`); await Promise.all(referenceParams.map(refKey => validateImage(prompt[refKey]))); } if (warnings.length > 0) { warnings.forEach(warning => console.warn(warning)); console.error(`⛔ Execution stopped due to warnings.`); process.exit(1); } for (let i = 0; i < prompts.length; i++) await submitImage(apiToken, email, prompts[i], i + 1); } function diffInMinutesAndSeconds(date1, date2) { const diffInSeconds = Math.floor((date2 - date1) / 1000); return `${Math.floor(diffInSeconds / 60)} minutes ${diffInSeconds % 60} seconds`; }; main(); ``` </details> ### Examples Real images generated through this same Google Flow API with Nano Banana Pro and Nano Banana 2 Lite — taken straight from our blog and model comparison. Nano Banana Pro — text-to-image ([source](/blog/251120)): *"Cat dressed like a pirate fencing with a real pirate… on a Disney cruise ship."* ![Nano Banana Pro text-to-image result](https://media.useapi.net/blog/2025-11-20-251120/nano-banana-pro-text-to-image.jpg) Nano Banana Pro — 5 reference images ([source](/blog/251201)): five individual portraits composited into one "K-Pop group victory celebration" group shot. ![Nano Banana Pro multi-reference group shot](https://media.useapi.net/blog/2025-12-01-251201/result.jpg) Nano Banana 2 Lite, the default model ([source](/docs/articles/google-flow-nano-banana-compare#examples)): the beekeeper prompt from our three-model comparison, rendered at 9:16 by the fastest of the three. <img src="https://media.useapi.net/articles/2026-06-15-google-flow-images-bash/nano-banana-2-lite.jpg" style="width: 100%; max-width: 420px;" alt="Nano Banana 2 Lite beekeeper result via the Google Flow API" /> ### Frequently asked questions - **Is there a Nano Banana 2 API?** Through useapi.net, yes: in the [Google Flow API](/docs/api-google-flow-v1), `nano-banana-2` makes images with Nano Banana 2.1, the version Google Flow runs, on any Google AI subscription or a free account, with no per-image charge. Nano Banana 2 (Gemini 3.1 Flash Image) costs $0.067 per 1K image on Google's official [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) (as of November 2026). It's a standard REST endpoint, with no Cloud project. - **Is there a Nano Banana Pro API?** Through useapi.net, yes: Nano Banana Pro (Gemini 3 Pro Image) runs as `nano-banana-pro` on the [POST /images](/docs/api-google-flow-v1/post-google-flow-images) endpoint, and one synchronous request returns up to four images at no per-image charge. Google's official [Gemini API](https://aistudio.google.com/docs/pricing#gemini-3-pro-image) charges $0.134 for every Pro image (as of November 2026). - **Which model does the API use by default?** Through useapi.net, the default is `nano-banana-2-lite` (Gemini 3.1 Flash-Lite Image), with or without references. Switch per request by setting `model` to `nano-banana-2` (Nano Banana 2.1) or `nano-banana-pro` (Gemini 3 Pro Image, the highest quality). All three accept up to 10 reference images and can be [upscaled to 2K/4K](#upscaling-to-2k4k). [Nano Banana 2 Lite vs 2.1 vs Pro](/docs/articles/google-flow-nano-banana-compare) shows all three on one prompt. - **Is Imagen 4 still available in Google Flow?** Through useapi.net, the `imagen-4` model id still works, so existing code keeps running, but Google removed Imagen from Google Flow in July 2026, and those requests now make images with `nano-banana-2-lite`, Google Flow's default image model since then. To pick a different model, set `model` to `nano-banana-2` or `nano-banana-pro`. - **Do I need a captcha or a Google Cloud project?** Through useapi.net you need neither a Google Cloud project nor a captcha of your own. Google Flow asks for a reCAPTCHA on every image, and the useapi.net worker solves it automatically: your first Google Flow account comes with 300 free solves on our own AntiCaptcha, CapSolver and EzCaptcha keys, and after that you add your own provider keys with [POST /accounts/captcha-providers](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers). The script in this guide sends no `captchaToken`. ### Conclusion Visit our <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> or <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> for any support questions and concerns. Check our [GitHub repo](https://github.com/useapi/google-flow-api) with code examples. #### Cross posted Also published on [dev.to](https://dev.to/useapi/how-to-generate-nano-banana-2-nano-banana-pro-images-via-the-google-flow-api-1cn2){:rel="nofollow"} and shared on [Bluesky](https://bsky.app/profile/useapi.net/post/3mwjbmurnab2e){:rel="nofollow"}. === URL: https://useapi.net/docs/articles/google-flow-n8n-ugc-ads === Document URL: https://useapi.net/docs/articles/google-flow-n8n-ugc-ads --- layout: default title: How to Make UGC Video Ads in n8n with the Google Flow API description: "Free n8n template that makes AI UGC video ads with Omni 1.1 Flash via the useapi.net Google Flow API: no code, a consistent presenter and voice, re-roll any step." keywords: [AI UGC ads, UGC video, n8n UGC video, UGC ad generator, n8n template, n8n workflow, no-code, Google Flow API, Omni 1.1 Flash, Omni Flash n8n, consistent character, AI presenter, AI voice, TikTok ads, product video, tutorial] image: https://media.useapi.net/articles/2026-10-03-google-flow-n8n-ugc-ads/00-ugc-ad-card-1200x630.jpg video: name: "My beauty secrets, an AI parody ad made with a free n8n template" description: "A deadpan parody UGC ad (a rat poison night cream, garden shears and a cheese grater) made with the n8n UGC Ad Factory template and Omni 1.1 Flash through the useapi.net Google Flow API." url: https://media.useapi.net/articles/2026-10-03-google-flow-n8n-ugc-ads/04-ugc-ad-my-beauty-secrets-parody-1080p-web.mp4 embed: https://www.youtube.com/embed/1vPpoNdWHJw thumbnail: https://media.useapi.net/articles/2026-10-03-google-flow-n8n-ugc-ads/00-ugc-ad-card-1200x630.jpg date: 2026-10-03 duration: PT32S width: 1080 height: 1920 parent: Articles nav_exclude: true date: 2026-10-03 last_modified: 2026-11-06 nav_order: 836 repo: https://github.com/useapi/google-flow-api --- ## How to Make UGC Video Ads in n8n with the Google Flow API 7 min read • October 3, 2026 (November 6, 2026) ## Table of contents ### Introduction A free n8n template makes AI UGC video ads through the [useapi.net Google Flow API](/docs/api-google-flow-v1): one form, up to five products, a consistent Omni 1.1 Flash presenter and voice, and 140 Flow credits for the default ad with four takes of each clip. There is no code to write. You open one form URL and click through it, and every free step has a page to pick or re-roll before the clips spend any credits. UGC ads are the one-person-talking-to-a-phone videos that fill TikTok, Reels and Shorts. Making them with AI is easy to start and hard to finish, because the presenter's face drifts, the voice changes from clip to clip, and the product on the table turns into a different product. This workflow is built around those three problems. The face and the voice are saved together as one character, every product gets a four-view reference sheet or your real photo, and every clip is filmed in one scene you picked. The video model is [Omni 1.1 Flash](https://deepmind.google/models/model-cards/gemini-omni-flash/), Google's audio-native model, so the presenter speaks the lines you write, in the voice you picked, with lip sync, in one take. If you would rather do it in code, the [UGC product video tutorial](/docs/articles/google-flow-ugc-product-video) builds a similar video with plain API calls in first-and-last-frame mode, which pins the set exactly but cannot carry a picked voice. <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 260px;max-width:320px;margin:0"> <div style="position:relative;width:100%;padding-top:177.78%;border-radius:8px;overflow:hidden"> <iframe src="https://www.youtube.com/embed/1vPpoNdWHJw" title="My beauty secrets, an AI parody ad made with a free n8n template" style="position:absolute;top:0;left:0;width:100%;height:100%;border:0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen loading="lazy"></iframe> </div> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">"My beauty secrets", a deadpan parody ad (made with this n8n template, 1080p, 32 seconds · <a href="https://youtube.com/shorts/1vPpoNdWHJw" target="_blank" rel="noopener noreferrer">watch on YouTube</a>)</figcaption> </figure> </div> ### What you need * An [n8n](https://n8n.io) instance. The workflow uses only core n8n nodes, with no community nodes. It was tested on self-hosted n8n 2.41. * A useapi.net account with an [API token](/docs/start-here/setup-useapi). One [$15/month subscription](/docs/subscription) covers every useapi.net API, with no per-call surcharge. * A Google account [connected to useapi.net](/docs/start-here/setup-google-flow), with a paid [Google AI subscription](https://gemini.google/subscriptions/) (Plus, Pro or Ultra). Omni 1.1 Flash video needs one and spends its Flow credits. ### How to import the n8n UGC ad template 1. Download [`ugc-ad-factory.json`](https://github.com/useapi/google-flow-api/blob/main/n8n/ugc-ad-factory.json) from the example repo and in n8n choose **Workflows → Import from File**{% include n8n-listed.html t="flow-ugc" %}. 2. Create a **Header Auth** credential whose Name is `Authorization` and Value is `Bearer <your API token>`, then select it on every HTTP Request node. 3. Publish (activate) the workflow and open the URL of the **Start form** node. The form is the whole interface. Nothing in the canvas needs editing to make an ad, and the defaults produce a working ad on the first run: a friendly presenter at a bathroom vanity showing a vitamin C serum, with a short intro and a call to action at the end. ### The pages, one by one #### Setup The first page asks only for the shape of the ad: the Google account email, where the presenter comes from, how many products (1 to 5), whether to add an intro and a closing clip, vertical 9:16 or horizontal 16:9, and how many takes to film of each clip (1 to 4, default 4). The next page then asks for exactly that many details, with no empty fields. <img src="https://media.useapi.net/articles/2026-10-03-google-flow-n8n-ugc-ads/n8n-ugc-v3-01-setup.png" alt="The setup page of the n8n UGC ad form: account, presenter source, number of products, intro, closing, format and takes" style="max-width:100%;border-radius:8px;border:1px solid #ddd"> #### Details Here you describe the presenter, the voice, the scene and every clip. Each clip is one sentence of action plus the line in quotes, for example: *The presenter picks up the serum, holds it up so the label faces the camera, and says: "This vitamin C serum goes on first every morning."* Depending on what you chose on the setup page, this page can take photos or an ID instead of descriptions: * Photos of the presenter. One clear photo is enough, and a second one in three-quarter view saves a step. Google screens real faces, so a photo of a real person may be refused when the video is made. * A saved character ID from an earlier run on the same Google account. It brings the face and the voice, and skips the next three pages. * A photo of each product. It is used as it is, or turned into a four-view sheet if you choose that option. <img src="https://media.useapi.net/articles/2026-10-03-google-flow-n8n-ugc-ads/n8n-ugc-v3-02-details.png" alt="The details page: the presenter, the voice, the scene and what is said in each clip" style="max-width:100%;border-radius:8px;border:1px solid #ddd"> #### Presenter and second angle Four presenters are generated from your description. Pick one, or re-roll four new ones with a note such as "older, shorter hair". The next page makes four three-quarter views of the same face, because a second angle helps the face hold in video. A single uploaded photo starts the workflow at the second-angle page, and two photos skip straight to the voice. <img src="https://media.useapi.net/articles/2026-10-03-google-flow-n8n-ugc-ads/n8n-ugc-v3-03-presenters.png" alt="Four generated presenter candidates to pick from or re-roll" style="max-width:100%;border-radius:8px;border:1px solid #ddd"> <img src="https://media.useapi.net/articles/2026-10-03-google-flow-n8n-ugc-ads/n8n-ugc-v3-04-angles.png" alt="Four three-quarter views of the picked presenter" style="max-width:100%;border-radius:8px;border:1px solid #ddd"> #### Voice Four of Google's preset voices read your sample line, and you play them in the page. Pick one, or ask for four more, optionally with a new delivery note such as "calmer, British accent". The picked voice and the two angles are saved as one character, and that character is used in every clip, which is what keeps the voice the same across the ad. <img src="https://media.useapi.net/articles/2026-10-03-google-flow-n8n-ugc-ads/n8n-ugc-v3-05-voices.png" alt="The voice page: preset voices reading the sample line, with players" style="max-width:100%;border-radius:8px;border:1px solid #ddd"> #### Product images Each product gets four reference sheets, each showing the same product from four angles. Pick one per product, or re-roll any single product while the others keep their picks. An uploaded photo appears as it is, with nothing to choose. <img src="https://media.useapi.net/articles/2026-10-03-google-flow-n8n-ugc-ads/n8n-ugc-v3-06-products.png" alt="Four four-view sheets for each product: a rat poison night cream, garden shears and a cheese grater" style="max-width:100%;border-radius:8px;border:1px solid #ddd"> #### Scene Four candidates of the presenter with every product in one frame. Every clip is filmed in the scene you pick, so this is where you choose the set, the framing and where each product stands. This page is the last free step, and it shows what the clips will cost before you continue, for example "3 clips × 4 takes ≈ 140 credits". <img src="https://media.useapi.net/articles/2026-10-03-google-flow-n8n-ugc-ads/n8n-ugc-v3-07-scenes.png" alt="Scene candidates with the presenter and all three products, and the credit cost of the clips" style="max-width:100%;border-radius:8px;border:1px solid #ddd"> #### Takes All the takes play in the page, one row per clip. Pick the best take of each clip, or re-roll only the clips you don't like. If Google refuses a clip, the page shows why and puts the clip's action in an editable box. In testing, a refused "lifts the shears in front of the chest" went through on the first try as "points at the shears on the table". Choose 1080p or 720p for the final video. <img src="https://media.useapi.net/articles/2026-10-03-google-flow-n8n-ugc-ads/n8n-ugc-v3-08-takes.png" alt="The takes page: every take plays in the page, pick one per clip or re-roll" style="max-width:100%;border-radius:8px;border:1px solid #ddd"> #### Your ad The last page plays the finished ad and links the MP4. The MP4 is joined on request by the workflow's own download URL, so nothing is stored in n8n, and the clips stay in your Flow account. Your n8n URL must be reachable from the browser you use. If a join between two clips has a pause or clips a word, set how much is cut from the start or end of each clip and re-join, which is free and takes about half a minute. The page also shows the character ID, so the same presenter, with the same face and voice, can front your next ad. <img src="https://media.useapi.net/articles/2026-10-03-google-flow-n8n-ugc-ads/n8n-ugc-v3-09-your-ad.png" alt="The last page: the joined ad, the MP4 download, the cut points between clips and the saved character ID" style="max-width:100%;border-radius:8px;border:1px solid #ddd"> ### How long it takes The image pages are quick, and slower when captcha needs retries. The clips take 5 to 15 minutes, and the upscale and join a few more. While a step runs, the button turns into a status panel that says what is being made, how long it usually takes, and how long it has been working. Refreshing the page brings you to the next one when it is ready. <img src="https://media.useapi.net/articles/2026-10-03-google-flow-n8n-ugc-ads/n8n-ugc-v3-07b-working-clips.png" alt="The status panel while the clips are being filmed: what is being made, how long it usually takes, and a running clock" style="max-width:100%;border-radius:8px;border:1px solid #ddd"> ### How much does an AI UGC ad cost? Everything except the video clips is free: the presenters, angles, voices, character, product sheets, scenes, the 1080p upscale and the final join. Each Omni 1.1 Flash take spends Flow credits from your Google AI subscription, the same as making it in Flow yourself: 7, 10, 12 or 15 credits for a 4, 6, 8 or 10 second clip at 720p. What one finished ad with four takes of every clip and one round of images costs, before any re-rolls, on the official [Gemini API](https://ai.google.dev/gemini-api/docs/pricing), which bills about $0.10 a second of 720p Omni 1.1 Flash video and $0.134 a Nano Banana Pro image, and on each Google Flow subscription (November 2026). Each subscription comes with a monthly number of credits, and each ad uses a set number of them, so an ad costs its share of the subscription. | Ad, 4 takes per clip | Official API | Ultra $199.99/m (25,000 cr/mo) | Ultra $99.99/m (10,000 cr/mo) | Pro $19.99/m (1,000 cr/mo) | |---|---|---|---|---| | Default ad (6 s intro, one 10 s product, 6 s closing) | $11.06 (88 s of video, 16 images) | $1.12 / 140 cr (178 ads/mo) | $1.40 / 140 cr (71 ads/mo) | $2.80 / 140 cr (7 ads/mo) | | Parody above (6 s intro, three 10 s products) | $17.81 (144 s of video, 24 images) | $1.76 / 220 cr (113 ads/mo) | $2.20 / 220 cr (45 ads/mo) | $4.40 / 220 cr (4 ads/mo) | | Largest ad (6 s intro, five 10 s products, 6 s closing) | $29.43 (248 s of video, 32 images) | $3.04 / 380 cr (65 ads/mo) | $3.80 / 380 cr (26 ads/mo) | $7.60 / 380 cr (2 ads/mo) | Re-rolling a clip costs its takes again, a re-rolled image costs nothing, and a refused clip costs nothing. The full credit table is on [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos#model-capabilities). ### How to keep the face and voice consistent across clips * One character holds the face and the voice. It is made from two angles of the presenter plus the voice you picked, through [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters). * Every clip is filmed in reference mode with up to four inputs: the character, the scene you picked, the product handled in that clip (if any), and the voice. In the test ads the voice stayed within the range a single speaker covers from line to line, across every clip. * Each clip's action ends with the presenter putting the product back where it was, so the table looks the same at every cut. * Takes absorb the rest. Reference mode lets the model reinterpret the scene a little, so framing can shift slightly between clips and the occasional take is off. Several takes per clip give you a choice, and picking costs nothing extra. ### When something goes wrong Every API call's result is sorted into one of three kinds, and each kind is handled differently. | Kind | Examples | What the workflow does | |---|---|---| | Temporary | captcha failures, `429`, Google `503` | Retries automatically, up to five times 5 seconds apart, then shows the failure with a re-roll, or a stop page if the character can't be created. A clip that already went through is never submitted twice | | Refused | Google's content filters, such as `PUBLIC_ERROR_DANGER_FILTER` | Shows the reason and asks you to change the description or the action | | Dead end | a wrong token, an account that isn't connected, a plan that can't use the model | Stops with a page that says what to fix | The account, its plan and its Flow credits are checked right after the details page, and the credits again just before the clips, so a dead end stops the run before anything is spent. If upscaling a clip fails, that clip stays 720p and the last page offers to retry just the failed ones, which is free. ### Customize it The **Settings** node holds the defaults for the details page, the image model (`nano-banana-pro`) and the number of captcha attempts per request. The clip prompt is in the **Clip requests** node. Everything the workflow calls is a documented endpoint, so any step can be changed with the [Google Flow API reference](/docs/api-google-flow-v1) at hand. ### Examples Both were made with this workflow and are Omni 1.1 Flash output, re-encoded to a smaller size for hosting. <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 220px;max-width:280px;margin:0"> <video poster="https://media.useapi.net/articles/2026-10-03-google-flow-n8n-ugc-ads/04-ugc-ad-my-beauty-secrets-parody-1080p-web-poster.jpg" controls width="100%" style="border-radius:8px"><source src="https://media.useapi.net/articles/2026-10-03-google-flow-n8n-ugc-ads/04-ugc-ad-my-beauty-secrets-parody-1080p-web.mp4" type="video/mp4"></video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">"My beauty secrets", a parody beauty ad (made with this n8n template, 1080p, 32 seconds)</figcaption> </figure> </div> <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 320px;max-width:560px;margin:0"> <video poster="https://media.useapi.net/articles/2026-10-03-google-flow-n8n-ugc-ads/02-n8n-ugc-ad-coffee-uploaded-photos-16x9-web-poster.jpg" controls width="100%" style="border-radius:8px"><source src="https://media.useapi.net/articles/2026-10-03-google-flow-n8n-ugc-ads/02-n8n-ugc-ad-coffee-uploaded-photos-16x9-web.mp4" type="video/mp4"></video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">Uploaded presenter photo and product photo (coffee, two products, 16:9, 15 s)</figcaption> </figure> </div> ### Frequently asked questions **Do I need to write any code?** Through useapi.net and this free template, no. You import one JSON file, add one Header Auth credential and open a form, and every step from the presenter to the finished MP4 happens in that form. The workflow can be read and changed in n8n like any other, but making an ad never needs it. **Can I use a real person as the presenter?** Through useapi.net you can upload one or two photos of a presenter, but Google screens identifiable people, so a real face may be refused when the clips are made. A generated presenter avoids that, and the saved character ID lets you reuse the same face and voice in every ad on the same Google account. **Does the voice stay the same in every clip?** Through useapi.net, yes. The voice you pick is saved in one character together with the face, and every clip is made from that character, which is what keeps the voice the same across the ad. Picking from four previews also means you hear the voice before any clip spends a credit. **Does it work on n8n Cloud?** Through useapi.net the template uses only core n8n nodes, so it should run on n8n Cloud, but it has been tested only on self-hosted n8n 2.41. The one requirement is that your browser can reach the n8n URL, because the last page plays the ad from the workflow's own download URL. **What does an ad cost?** Through useapi.net, the default ad with four takes of each clip costs $1.12 on Google AI Ultra $199.99, against $11.06 on the official Gemini API (as of November 2026). Only the Omni 1.1 Flash takes spend Flow credits, and every presenter, voice, character, product sheet, scene, upscale and join is free. See [the cost section](#how-much-does-an-ai-ugc-ad-cost). ### Conclusion Visit our <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> or <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> for any support questions and concerns. Check our [GitHub repo](https://github.com/useapi/google-flow-api) with code examples. #### Cross posted Also published on [dev.to](https://dev.to/useapi/how-to-make-ugc-video-ads-in-n8n-with-the-google-flow-api-3b2n){:rel="nofollow"} and discussed on [Reddit](https://www.reddit.com/r/ThirdPartyAPI/comments/1wx27ic/how_to_make_ugc_video_ads_in_n8n_with_the_google/){:rel="nofollow"}. === URL: https://useapi.net/docs/articles/google-flow-nano-banana-compare-es === Document URL: https://useapi.net/docs/articles/google-flow-nano-banana-compare-es --- layout: default title: "Nano Banana 2 Lite vs 2.1 vs Pro: los modelos de imagen de Google Flow comparados" description: "Compara los tres modelos de imagen Nano Banana de Google Flow (2 Lite, 2.1 y Pro) con el mismo prompt mediante la API de useapi.net, con un script listo para ejecutar y ejemplos reales." keywords: [Nano Banana 2 Lite, Nano Banana 2.1, Nano Banana 2, Nano Banana Pro, Gemini 3 Pro Image, Gemini 3.1 Flash Image, Gemini 3.1 Flash-Lite Image, nano-banana-2-lite, Nano Banana API, Nano Banana Pro API, image model comparison, Google Flow API, API de Nano Banana, API de Nano Banana Pro, comparación de modelos de imagen, generar imágenes con IA, API de generación de imágenes, tutorial, código] image: https://media.useapi.net/articles/2026-07-02-google-flow-nano-banana-compare/nano-banana-pro.jpg parent: Articles nav_exclude: true lang: es translation_key: nano-banana-compare date: 2026-07-02 last_modified: 2026-11-06 nav_order: 830 repo: https://github.com/useapi/google-flow-api --- ## Nano Banana 2 Lite vs 2.1 vs Pro: los modelos de imagen de Google Flow comparados {: .no_toc #nano-banana-2-lite-vs-21-vs-pro-google-flow-image-models-compared } 7 min de lectura • 2 de julio de 2026 (6 de noviembre de 2026) useapi.net es una API de terceros. No está afiliada a Google ni cuenta con su respaldo. ## Índice {: .no_toc .text-delta #table-of-contents } ### Introducción Google Flow ofrece tres modelos de imagen Nano Banana, `nano-banana-2-lite`, `nano-banana-2` y `nano-banana-pro`, y la [Google Flow API](/docs/api-google-flow-v1) de useapi.net ejecuta los tres a partir de un solo prompt con tu cuenta de [Google Flow](https://flow.google.com). Las imágenes están incluidas en todas las [suscripciones de Google AI](https://gemini.google/subscriptions/), también en una cuenta gratuita, mientras que la Gemini API oficial cobra de US$0,034 a US$0,134 por imagen (a noviembre de 2026). No necesitas proyecto de Google Cloud ni clave de API. Esta guía ejecuta exactamente el mismo prompt en Lite, 2.1 y Pro para que veas en qué se diferencian, y luego te da un script de Node.js que genera el conjunto completo con un solo comando. ¿Prefieres empezar desde cero? Consulta el [tutorial de generación de imágenes](/docs/articles/google-flow-images-bash-es), la guía hermana de esta. ### ¿Cuáles son los tres modelos Nano Banana? Elige el modelo en cada solicitud con el campo `model`. Si lo omites, Google Flow usa `nano-banana-2-lite`, su modelo por defecto desde julio de 2026. Los tres funcionan en cualquier suscripción de Google AI, incluida una cuenta gratuita. | ID del modelo | Nombre comercial | Ideal para | Referencias (I2I) | Velocidad | |----------|----------------|----------|-----------------:|-------| | `nano-banana-2-lite` *(por defecto)* | [Nano Banana 2 Lite](https://deepmind.google/models/gemini-image/flash-lite/) / Gemini 3.1 Flash-Lite Image | imágenes rápidas y en gran volumen, en cualquier plan | hasta 10 | la más rápida | | `nano-banana-2` | Nano Banana 2.1 | equilibrio entre calidad y velocidad | hasta 10 | rápida | | `nano-banana-pro` | [Nano Banana Pro](https://deepmind.google/models/gemini-image/pro/) / Gemini 3 Pro Image | máxima fidelidad y apego a las instrucciones | hasta 10 | más lenta | Los tres aceptan las mismas relaciones de aspecto (`16:9`, `4:3`, `1:1`, `3:4`, `9:16`, más `auto` en el modo imagen a imagen), `count` (1–4), `seed` para reproducir resultados, hasta 10 imágenes de referencia, menciones con `@` dentro del prompt y [escalado a 2K/4K](#upscaling-to-2k4k). Los alias obsoletos `imagen-4` (Google quitó Imagen de Google Flow en julio de 2026) y `nano-banana` se siguen aceptando y corresponden a `nano-banana-2-lite` y `nano-banana-2`, respectivamente. El detalle completo de cada modelo está en la referencia de [POST /images](/docs/api-google-flow-v1/post-google-flow-images). #### Escalado a 2K/4K Cualquier imagen generada se puede escalar con [POST /images/upscale](/docs/api-google-flow-v1/post-google-flow-images-upscale): pasa su `mediaGenerationId` y un `resolution` de `2k` (por defecto) o `4k`. La respuesta llega en base64 en `encodedImage`. `2k` funciona en cualquier plan, y `4k` requiere Google AI Ultra. ### Precios Las imágenes no gastan créditos de Flow en ninguna suscripción de Google AI, incluida una cuenta gratuita, y useapi.net no cobra nada por imagen. El precio de cada modelo en cada plan, frente a la API oficial, está en la [tabla de precios de Google Flow](/docs/api-google-flow-v1#pricing). Consulta la [guía de configuración](/docs/start-here/setup-google-flow) para conectar tu cuenta. ### El prompt de la comparación Una comparación de modelos solo sirve si el prompt es difícil. Este es una escena absurda a propósito, en un solo cuadro, que pone a prueba varias cosas a la vez: un estilo fotográfico con nombre (David LaChapelle), una disposición espacial con varios sujetos (un enjambre que forma una flecha arriba a la izquierda y una abeja en perspectiva forzada abajo a la derecha), la fidelidad de un objeto (un panal que gotea miel), una expresión cómica concreta (ojos de caricatura `o_O`) y un tono contradictorio, todo en una sola imagen coherente. ```text A visually breathtaking, beautifully absurd, single-frame photograph in the hyper-saturated, glossy, surreal-comedy editorial style of David LaChapelle, shot at a sun-dappled backyard apiary at golden hour on an 85mm f/1.4 lens with creamy shallow depth of field. In the center midground, a gorgeous, radiant young woman beekeeper with an elegant figure, flawless glowing sun-kissed skin and a warm playful smile, incongruously wearing a tiny mini bikini and a beekeeper's veil hat pushed back off her face, stands among the wooden hive boxes on the grass and lifts a single open beehive frame heavy with golden honeycomb, thick honey oozing and stringing down in glossy ribbons and catching the light. She looks directly into the camera, delighted and completely unbothered by the bees swirling around her. In the top-left of the frame, a dense swarm of bees bunches together and organizes into a bold, unmistakable arrow / pointer shape aimed straight at her, as if frantically calling everyone's attention. In the extreme bottom-right foreground of the exact same scene, photobombing the lens, is a huge forced-perspective close-up of a single frazzled worker bee, staring directly into the camera with bulging, mind-blown "o_O" cartoon googly eyes, completely frozen in comical disbelief. Single cohesive image, seamless depth of field, no cut-ins, warm dynamic backlighting, glistening honey highlights, crazy situational comedy, hyper-detailed, masterpiece. ``` ### Genera con los tres modelos Necesitas un [token de API](/docs/start-here/setup-useapi) de useapi.net y una [cuenta de Google Flow](/docs/start-here/setup-google-flow) conectada. `POST /images` es síncrono: una llamada espera hasta que las imágenes estén listas (normalmente de 20 a 60 segundos, y el modelo Pro puede tardar unos 2 minutos con mucha carga) y devuelve un arreglo `media[]` con una entrada por imagen, así que no hay `jobid` que consultar. Una sola llamada, cambia `model` para comparar: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/images" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model": "nano-banana-pro", "aspectRatio": "9:16", "count": 4, "prompt": "A beekeeper at golden hour lifting a dripping honeycomb frame, a swarm forming an arrow in the sky, a forced-perspective bee with o_O googly eyes in the foreground" }' > result.json # cada imagen está en .media[N].image.generatedImage.fifeUrl curl -o pro_1.jpg "$(jq -r '.media[0].image.generatedImage.fifeUrl' result.json)" ``` Para ejecutar la comparación completa con un solo comando, el script de Node.js de abajo lee `prompts.json` (una entrada por modelo, todas con el mismo prompt), envía cada una y guarda cada imagen devuelta con el nombre del modelo en el archivo: la descarga desde `fifeUrl` o decodifica el `encodedImage` en línea cuando falta la URL. Si una imagen falla, queda registrada en el log y la ejecución continúa. Necesitas [Node.js](https://nodejs.org) v21 o superior. Pon los dos archivos en una carpeta y ejecuta `node ./google-flow-nano-banana-compare.mjs API_TOKEN EMAIL`, donde `API_TOKEN` es tu [token de API](/docs/start-here/setup-useapi) de useapi.net y `EMAIL` es tu [cuenta de Google Flow](/docs/start-here/setup-google-flow) conectada. El script busca la cuenta por el correo, revisa su `health` antes de enviar y no envía `captchaToken`: el worker de useapi.net resuelve el reCAPTCHA automáticamente. ¿Prefieres clonarlo y ejecutarlo? El script completo, una versión en Python y `prompts.json` están en GitHub, en [`useapi/google-flow-api`](https://github.com/useapi/google-flow-api/tree/main/nano-banana-compare). <details markdown="block"> <summary>Abrir `prompts.json`</summary> ```json [ { "model": "nano-banana-2-lite", "aspectRatio": "9:16", "count": 4, "prompt": "A beekeeper at golden hour lifting a dripping honeycomb frame in the surreal editorial style of David LaChapelle, a dense bee swarm forming a bold arrow in the top-left, a forced-perspective bee with o_O cartoon googly eyes photobombing the bottom-right. Single cohesive image, masterpiece." }, { "model": "nano-banana-2", "aspectRatio": "9:16", "count": 4, "prompt": "A beekeeper at golden hour lifting a dripping honeycomb frame in the surreal editorial style of David LaChapelle, a dense bee swarm forming a bold arrow in the top-left, a forced-perspective bee with o_O cartoon googly eyes photobombing the bottom-right. Single cohesive image, masterpiece." }, { "model": "nano-banana-pro", "aspectRatio": "9:16", "count": 4, "prompt": "A beekeeper at golden hour lifting a dripping honeycomb frame in the surreal editorial style of David LaChapelle, a dense bee swarm forming a bold arrow in the top-left, a forced-perspective bee with o_O cartoon googly eyes photobombing the bottom-right. Single cohesive image, masterpiece." } ] ``` </details> <details markdown="block"> <summary>Abrir el script `google-flow-nano-banana-compare.mjs`</summary> ```javascript /* Script version 1.1, September 11, 2026 Batch-compare Google Flow's Nano Banana image models (2 Lite, 2.1, Pro) with the useapi.net API 🚀 Reads prompts.json (one entry per model), submits each to the synchronous POST /images endpoint, and downloads every returned image with a model-labeled filename. For more details visit https://useapi.net/docs/api-google-flow-v1/post-google-flow-images Companion tutorial: https://useapi.net/docs/articles/google-flow-nano-banana-compare Installation Instructions: ========================== You need Node.js v21 or newer installed to run this script. Download and install Node.js from: - Windows, macOS, Linux: https://nodejs.org/ After installation, verify by running the following command in a terminal: node -v Running the Script: =================== Usage: node google-flow-nano-banana-compare.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE] Replace API_TOKEN with your actual useapi.net API token, see https://useapi.net/docs/start-here/setup-useapi Replace EMAIL with configured Google Flow email account, see https://useapi.net/docs/start-here/setup-google-flow If optional PROMPTS_FILE not provided prompts.json will be used. Example: -------- node google-flow-nano-banana-compare.mjs user:1234-abcdefhijklmnopqrstuv my@email.com Changelog: ========== - July 2, 2026: Initial release. - September 11, 2026: Saves encodedImage when fifeUrl is absent, and writes a downloaded image only once it has been fully received, so a failed download leaves no partial file for the next run to skip as "already exists". */ import fs from 'fs/promises'; import { writeFile } from 'node:fs/promises'; // Constants const DEFAULT_PROMPTS_FILE = 'prompts.json'; const DEFAULT_MODEL = 'nano-banana-2-lite'; const SLEEP_RETRY = 30 * 1000; // in milliseconds const urlAccounts = 'https://api.useapi.net/v1/google-flow/accounts'; const urlImages = 'https://api.useapi.net/v1/google-flow/images'; // Utility to sleep for given milliseconds const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); const elapsedTimeSec = (start) => (Date.now() - start) / 1000; // Function to fetch configured Google Flow API accounts async function fetchAccounts(apiToken) { const response = await fetch(urlAccounts, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.error(`⛔ Error fetching accounts (HTTP ${response.status}): ${response.statusText}`); process.exit(1); } return response.json(); } // Save a single image from its signed fifeUrl. fifeUrl is normally present; when it is absent // the image arrived inline as base64 in encodedImage. A failure is reported and skipped. async function downloadImage(img, filename) { try { await fs.access(filename); console.log(`⚠️ ${filename} already exists. Skipping download.`); return; } catch { // File does not exist, proceed with downloading } const url = img?.fifeUrl; if (!url && img?.encodedImage) { console.log(`✅ Saving ${filename} from encodedImage`); try { await writeFile(filename, Buffer.from(img.encodedImage, 'base64')); } catch (err) { console.error(`⛔ Unable to save ${filename}: ${err}`); } return; } if (!url) { console.error(`🛑 No fifeUrl or encodedImage for ${filename}`); return; } console.log(`✅ Downloading ${filename}`); try { const imageResponse = await fetch(url); if (!imageResponse.ok) { console.error(`⛔ Unable to download ${filename} (HTTP ${imageResponse.status})`); return; } // Read the whole body before creating the file, so a failed download leaves no // partial file behind for the next run to skip as "already exists". const data = Buffer.from(await imageResponse.arrayBuffer()); await writeFile(filename, data); } catch (err) { console.error(`⛔ Error during download: ${err}`); } } // Submit a single prompt to the synchronous POST /images endpoint and download the results. async function submitImage(apiToken, email, prompt, index) { const model = prompt.model ?? DEFAULT_MODEL; // Build the request body. const body = { model, email, prompt: prompt.prompt }; for (const key of ['aspectRatio', 'count', 'seed']) if (prompt[key] !== undefined) body[key] = prompt[key]; console.log(`🚀 ${model} » Prompt #${index} • account ${email} …`); const startTime = Date.now(); while (true) { const response = await fetch(urlImages, { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiToken}` }, body: JSON.stringify(body) }); const responseText = await response.text(); if (response.status == 200) { const media = JSON.parse(responseText)?.media ?? []; if (media.length == 0) console.error(`🛑 200 OK but no media (moderated?) for ${model}`); // count > 1 returns multiple images in the media array. for (let i = 0; i < media.length; i++) { const img = media[i]?.image?.generatedImage; await downloadImage(img, `${model}_${i + 1}.jpg`); } console.log(`🆗 ${model} done (${elapsedTimeSec(startTime)} sec)`); return 200; } switch (response.status) { case 429: case 503: console.log(`🔄️ Retry on HTTP ${response.status}`, responseText); await sleep(SLEEP_RETRY); break; default: console.error(`🛑 ${model} failed with HTTP ${response.status}`, responseText); return response.status; } } } // Main function async function main() { const apiToken = process.argv[2]; const email = process.argv[3]; const promptFile = process.argv[4] || DEFAULT_PROMPTS_FILE; if (!apiToken || !email) { console.error('Usage: node google-flow-nano-banana-compare.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE]'); process.exit(1); } console.info('Script v1.1 • Node version ' + process.version); const accounts = await fetchAccounts(apiToken); if (!accounts[email]) { console.error(`⛔ Account ${email} not found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (accounts[email].health && accounts[email].health !== 'OK') { console.error(`⛔ Account ${email} health is '${accounts[email].health}'. Please resolve and update the account, see https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } const prompts = JSON.parse(await fs.readFile(promptFile, 'utf8')); console.log(`Comparing ${prompts.length} model runs …`); const start = new Date(); for (let i = 0; i < prompts.length; i++) await submitImage(apiToken, email, prompts[i], i + 1); console.info('COMPLETED', new Date(), '• elapsed', elapsedTimeSec(start), 'sec'); } main(); ``` </details> ### Ejemplos Este es el mismo prompt de la apicultora generado por cada modelo en 9:16, con esta Google Flow API. Las diferencias se repiten: Pro es el más pulido y el más fiel a las instrucciones, 2.1 es el más dinámico y Lite es el más rápido y queda muy cerca. `nano-banana-pro`: el más pulido y con más aire editorial, y el único modelo que dibuja siempre la malla del velo, las abejas caminando sobre el panal y los ojos de caricatura `o_O` al pie de la letra. <img src="https://media.useapi.net/articles/2026-07-02-google-flow-nano-banana-compare/nano-banana-pro.jpg" style="width: 100%; max-width: 420px;" alt="Apicultora generada con Nano Banana Pro mediante la Google Flow API" /> `nano-banana-2`: la interpretación más dinámica y llena de energía, con el enjambre en forma de flecha más claro y muchos detalles de la situación (botas de trabajo, abejas en el cuadro). <img src="https://media.useapi.net/articles/2026-07-02-google-flow-nano-banana-compare/nano-banana-2.jpg" style="width: 100%; max-width: 420px;" alt="Apicultora generada con nano-banana-2 mediante la Google Flow API" /> `nano-banana-2-lite`: el más rápido de los tres (cerca de la mitad del tiempo de Pro en nuestras pruebas), y conserva la composición, la miel que gotea y la abeja de ojos saltones en primer plano. <img src="https://media.useapi.net/articles/2026-06-15-google-flow-images-bash/nano-banana-2-lite.jpg" style="width: 100%; max-width: 420px;" alt="Apicultora generada con Nano Banana 2 Lite mediante la Google Flow API" /> ### ¿Qué modelo Nano Banana deberías usar? - Usa `nano-banana-pro` cuando la fidelidad es lo que más importa: imágenes principales, escenas complejas con varios sujetos, texto preciso o apego estricto a las instrucciones. Es el más lento de los tres. - Usa `nano-banana-2` para un buen equilibrio entre calidad y velocidad, o cuando quieres una lectura del prompt más dinámica y estilizada. - Usa `nano-banana-2-lite` (el modelo por defecto) para iterar y para lotes grandes en los que importa la velocidad y la calidad sigue muy cerca. Como los tres usan la misma solicitud, cambiar es modificar una palabra en `model`: genera un lote con los tres y elige el mejor, tal como hace el script de arriba. ### Ejecútalo tú mismo El script completo de Node.js, una versión en Python y `prompts.json` están en [`useapi/google-flow-api/nano-banana-compare`](https://github.com/useapi/google-flow-api/tree/main/nano-banana-compare). Clónalo, edita `prompts.json` y ejecuta un comando para generar el conjunto completo de la comparación con tu cuenta de Google Flow. ### Preguntas frecuentes - **¿Existe una API de Nano Banana 2.1 o de Nano Banana Pro?** Con useapi.net, sí: la [Google Flow API](/docs/api-google-flow-v1) ejecuta las versiones de Google Flow como `nano-banana-2` (Nano Banana 2.1), `nano-banana-2-lite` y `nano-banana-pro` en [POST /images](/docs/api-google-flow-v1/post-google-flow-images). En la [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) oficial, Nano Banana 2.1 cuesta unos US$0,034 por imagen 1K y Nano Banana Pro US$0,134 por imagen, frente a ningún cargo por imagen aquí (a noviembre de 2026). - **¿Qué diferencia hay entre Nano Banana 2 Lite, 2.1 y Pro?** Con useapi.net los tres funcionan en el mismo endpoint, cada uno con su punto fuerte. `nano-banana-pro` (Gemini 3 Pro Image) es el más pulido y el que sigue las instrucciones más de cerca, `nano-banana-2` (Nano Banana 2.1) da la lectura más dinámica, y `nano-banana-2-lite` (Gemini 3.1 Flash-Lite Image), el modelo por defecto, tardó cerca de la mitad del tiempo de Pro en nuestras pruebas. Consulta [¿Qué modelo deberías usar?](#which-nano-banana-model-should-you-use) - **¿Cuánto cuesta la API de Nano Banana?** Con useapi.net, las imágenes no gastan créditos de Flow en ninguna suscripción de Google AI, incluida una cuenta gratuita, y no hay clave de la Gemini API ni cuenta de facturación de Cloud que configurar. En la [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) oficial, Nano Banana 2 Lite cuesta unos US$0,034 por imagen 1K (a noviembre de 2026). Consulta [Precios](#pricing). - **¿Las imágenes pasan por moderación?** Con useapi.net, tus prompts pasan por la moderación de contenido del propio Google, y una solicitud rechazada devuelve un resultado vacío. Las decisiones de moderación varían entre solicitudes y entre modelos, así que reintentar, editar el prompt o cambiar de modelo suele funcionar, porque cada modelo Nano Banana modera de forma un poco distinta. - **¿Necesito un captcha o un proyecto de Google Cloud?** Con useapi.net no necesitas proyecto de Google Cloud ni resolver captchas por tu cuenta. Google Flow pide un reCAPTCHA en cada imagen, y el worker de useapi.net lo resuelve automáticamente: tu primera cuenta de Google Flow incluye 300 resoluciones gratis con nuestras propias claves de AntiCaptcha, CapSolver y EzCaptcha, y después agregas las claves de tu propio proveedor. El script de esta guía no envía `captchaToken`. ### Conclusión Visita nuestro <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> servidor de Discord</a> o nuestro <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> canal de Telegram</a> para cualquier pregunta de soporte. Consulta nuestro [repositorio de GitHub](https://github.com/useapi/google-flow-api) con ejemplos de código. #### Publicado también en {: .no_toc #cross-posted } También publicado en [dev.to](https://dev.to/useapi/nano-banana-2-lite-vs-2-vs-pro-google-flow-image-models-compared-3b15){:rel="nofollow"} (en inglés) y comentado en [Reddit](https://www.reddit.com/r/ThirdPartyAPI/comments/1ulw4zo/nano_banana_2_lite_vs_2_vs_pro_google_flow_image/){:rel="nofollow"} (en inglés). ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-flow-nano-banana-compare-id === Document URL: https://useapi.net/docs/articles/google-flow-nano-banana-compare-id --- layout: default title: "Nano Banana 2 Lite vs 2.1 vs Pro: Perbandingan Model Gambar Google Flow" description: "Bandingkan tiga model gambar Nano Banana di Google Flow (2 Lite, 2.1, dan Pro) dengan satu prompt yang sama lewat API useapi.net, lengkap dengan skrip siap jalan dan contoh nyata." keywords: [Nano Banana 2 Lite, Nano Banana 2.1, Nano Banana 2, Nano Banana Pro, Gemini 3 Pro Image, Gemini 3.1 Flash Image, Gemini 3.1 Flash-Lite Image, nano-banana-2-lite, Nano Banana API, Nano Banana Pro API, image model comparison, Google Flow API, API Nano Banana, perbandingan Nano Banana, perbandingan model gambar, membuat gambar AI, API pembuat gambar, tutorial bahasa Indonesia, kode] image: https://media.useapi.net/articles/2026-07-02-google-flow-nano-banana-compare/nano-banana-pro.jpg parent: Articles nav_exclude: true lang: id translation_key: nano-banana-compare date: 2026-07-02 last_modified: 2026-11-06 nav_order: 830 repo: https://github.com/useapi/google-flow-api --- ## Nano Banana 2 Lite vs 2.1 vs Pro: Perbandingan Model Gambar Google Flow {: .no_toc #nano-banana-2-lite-vs-21-vs-pro-google-flow-image-models-compared } 7 menit baca • 2 Juli 2026 (6 November 2026) useapi.net adalah API pihak ketiga. Kami tidak berafiliasi dengan Google dan tidak disahkan oleh Google. ## Daftar isi {: .no_toc .text-delta #table-of-contents } ### Pendahuluan Google Flow punya tiga model gambar Nano Banana, yaitu `nano-banana-2-lite`, `nano-banana-2`, dan `nano-banana-pro`, dan [Google Flow API](/docs/api-google-flow-v1) useapi.net menjalankan ketiganya dari satu prompt dengan akun [Google Flow](https://flow.google.com) Anda. Gambar sudah termasuk di setiap [langganan Google AI](https://gemini.google/subscriptions/), akun gratis juga, sementara Gemini API resmi menagih $0,034 sampai $0,134 per gambar (per November 2026). Tidak perlu project Google Cloud dan tidak perlu API key. Panduan ini menjalankan prompt yang persis sama di Lite, 2.1, dan Pro supaya Anda bisa melihat bedanya, lalu memberikan skrip Node.js siap jalan yang membuat seluruh set gambar dengan satu perintah. Ingin panduan dari nol dulu? Lihat [tutorial pembuatan gambar](/docs/articles/google-flow-images-bash-id), pasangan panduan ini. ### Apa saja tiga model Nano Banana itu? Pilih model per request dengan field `model`. Jika tidak diisi, Google Flow memakai `nano-banana-2-lite`, default-nya sejak Juli 2026. Ketiganya berjalan di langganan Google AI mana pun, termasuk akun gratis. | ID model | Nama produk | Paling cocok untuk | Referensi (I2I) | Kecepatan | |----------|----------------|----------|-----------------:|-------| | `nano-banana-2-lite` *(default)* | [Nano Banana 2 Lite](https://deepmind.google/models/gemini-image/flash-lite/) / Gemini 3.1 Flash-Lite Image | gambar cepat dalam jumlah besar, di paket apa pun | maks. 10 | tercepat | | `nano-banana-2` | Nano Banana 2.1 | seimbang antara kualitas dan kecepatan | maks. 10 | cepat | | `nano-banana-pro` | [Nano Banana Pro](https://deepmind.google/models/gemini-image/pro/) / Gemini 3 Pro Image | fidelitas dan kepatuhan instruksi tertinggi | maks. 10 | lebih lambat | Ketiganya menerima rasio aspek yang sama (`16:9`, `4:3`, `1:1`, `3:4`, `9:16`, plus `auto` di mode gambar ke gambar), `count` (1–4), `seed` untuk hasil yang bisa diulang, hingga 10 gambar referensi, `@`-mention di dalam prompt, dan [upscale ke 2K/4K](#upscaling-to-2k4k). Alias lama `imagen-4` (Google menghapus Imagen dari Google Flow pada Juli 2026) dan `nano-banana` masih diterima dan masing-masing dipetakan ke `nano-banana-2-lite` dan `nano-banana-2`. Detail lengkap tiap model ada di referensi [POST /images](/docs/api-google-flow-v1/post-google-flow-images). #### Upscale ke 2K/4K Gambar apa pun yang sudah dibuat bisa di-upscale dengan [POST /images/upscale](/docs/api-google-flow-v1/post-google-flow-images-upscale): kirim `mediaGenerationId`-nya dan `resolution` berisi `2k` (default) atau `4k`. Responsnya berupa base64 di `encodedImage`. `2k` bisa dipakai di paket apa pun, dan `4k` butuh Google AI Ultra. ### Harga Gambar tidak memakai kredit Flow di langganan Google AI mana pun, termasuk akun gratis, dan useapi.net tidak menagih biaya per gambar. Harga setiap model di setiap paket, dibandingkan dengan API resmi, ada di [tabel harga Google Flow](/docs/api-google-flow-v1#pricing). Lihat [panduan penyiapan](/docs/start-here/setup-google-flow) untuk menghubungkan akun Anda. ### Prompt perbandingan Perbandingan model hanya berguna kalau prompt-nya sulit. Prompt ini sengaja dibuat sebagai adegan absurd dalam satu bingkai yang menguji beberapa hal sekaligus: gaya fotografi yang disebut namanya (David LaChapelle), tata letak ruang dengan banyak subjek (kawanan lebah yang membentuk panah di kiri atas, seekor lebah dengan perspektif paksa di kanan bawah), ketepatan properti (sarang madu yang meneteskan madu), ekspresi komedi tertentu (mata kartun `o_O`), dan nuansa yang saling bertabrakan, semuanya dalam satu gambar yang padu. ```text A visually breathtaking, beautifully absurd, single-frame photograph in the hyper-saturated, glossy, surreal-comedy editorial style of David LaChapelle, shot at a sun-dappled backyard apiary at golden hour on an 85mm f/1.4 lens with creamy shallow depth of field. In the center midground, a gorgeous, radiant young woman beekeeper with an elegant figure, flawless glowing sun-kissed skin and a warm playful smile, incongruously wearing a tiny mini bikini and a beekeeper's veil hat pushed back off her face, stands among the wooden hive boxes on the grass and lifts a single open beehive frame heavy with golden honeycomb, thick honey oozing and stringing down in glossy ribbons and catching the light. She looks directly into the camera, delighted and completely unbothered by the bees swirling around her. In the top-left of the frame, a dense swarm of bees bunches together and organizes into a bold, unmistakable arrow / pointer shape aimed straight at her, as if frantically calling everyone's attention. In the extreme bottom-right foreground of the exact same scene, photobombing the lens, is a huge forced-perspective close-up of a single frazzled worker bee, staring directly into the camera with bulging, mind-blown "o_O" cartoon googly eyes, completely frozen in comical disbelief. Single cohesive image, seamless depth of field, no cut-ins, warm dynamic backlighting, glistening honey highlights, crazy situational comedy, hyper-detailed, masterpiece. ``` ### Generate dengan ketiga model Anda butuh [API token](/docs/start-here/setup-useapi) useapi.net dan [akun Google Flow](/docs/start-here/setup-google-flow) yang sudah terhubung. `POST /images` bersifat sinkron: satu panggilan menunggu sampai gambar selesai (biasanya 20–60 detik, dan model Pro bisa sampai sekitar 2 menit saat beban tinggi) lalu mengembalikan array `media[]` dengan satu entri per gambar, jadi tidak ada `jobid` yang perlu di-poll. Satu panggilan saja, ganti `model` untuk membandingkan: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/images" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model": "nano-banana-pro", "aspectRatio": "9:16", "count": 4, "prompt": "A beekeeper at golden hour lifting a dripping honeycomb frame, a swarm forming an arrow in the sky, a forced-perspective bee with o_O googly eyes in the foreground" }' > result.json # setiap gambar ada di .media[N].image.generatedImage.fifeUrl curl -o pro_1.jpg "$(jq -r '.media[0].image.generatedImage.fifeUrl' result.json)" ``` Untuk menjalankan seluruh perbandingan dengan satu perintah, skrip Node.js di bawah membaca `prompts.json` (satu entri per model, semuanya dengan prompt yang sama), mengirim masing-masing, lalu menyimpan setiap gambar yang dikembalikan dengan nama file berlabel model, dengan mengunduhnya dari `fifeUrl` atau men-decode `encodedImage` inline jika URL-nya tidak ada. Gambar yang gagal dicatat di log dan skrip lanjut ke berikutnya. Anda butuh [Node.js](https://nodejs.org) v21+. Taruh kedua file di satu folder lalu jalankan `node ./google-flow-nano-banana-compare.mjs API_TOKEN EMAIL`, dengan `API_TOKEN` berisi [API token](/docs/start-here/setup-useapi) useapi.net Anda dan `EMAIL` berisi [akun Google Flow](/docs/start-here/setup-google-flow) yang terhubung. Skrip mencari akun berdasarkan email, memeriksa `health`-nya sebelum mengirim, dan tidak mengirim `captchaToken`: worker useapi.net menyelesaikan reCAPTCHA secara otomatis. Lebih suka clone dan menjalankannya? Skrip lengkap, versi Python, dan `prompts.json` ada di GitHub di [`useapi/google-flow-api`](https://github.com/useapi/google-flow-api/tree/main/nano-banana-compare). <details markdown="block"> <summary>Buka `prompts.json`</summary> ```json [ { "model": "nano-banana-2-lite", "aspectRatio": "9:16", "count": 4, "prompt": "A beekeeper at golden hour lifting a dripping honeycomb frame in the surreal editorial style of David LaChapelle, a dense bee swarm forming a bold arrow in the top-left, a forced-perspective bee with o_O cartoon googly eyes photobombing the bottom-right. Single cohesive image, masterpiece." }, { "model": "nano-banana-2", "aspectRatio": "9:16", "count": 4, "prompt": "A beekeeper at golden hour lifting a dripping honeycomb frame in the surreal editorial style of David LaChapelle, a dense bee swarm forming a bold arrow in the top-left, a forced-perspective bee with o_O cartoon googly eyes photobombing the bottom-right. Single cohesive image, masterpiece." }, { "model": "nano-banana-pro", "aspectRatio": "9:16", "count": 4, "prompt": "A beekeeper at golden hour lifting a dripping honeycomb frame in the surreal editorial style of David LaChapelle, a dense bee swarm forming a bold arrow in the top-left, a forced-perspective bee with o_O cartoon googly eyes photobombing the bottom-right. Single cohesive image, masterpiece." } ] ``` </details> <details markdown="block"> <summary>Buka skrip `google-flow-nano-banana-compare.mjs`</summary> ```javascript /* Script version 1.1, September 11, 2026 Batch-compare Google Flow's Nano Banana image models (2 Lite, 2.1, Pro) with the useapi.net API 🚀 Reads prompts.json (one entry per model), submits each to the synchronous POST /images endpoint, and downloads every returned image with a model-labeled filename. For more details visit https://useapi.net/docs/api-google-flow-v1/post-google-flow-images Companion tutorial: https://useapi.net/docs/articles/google-flow-nano-banana-compare Installation Instructions: ========================== You need Node.js v21 or newer installed to run this script. Download and install Node.js from: - Windows, macOS, Linux: https://nodejs.org/ After installation, verify by running the following command in a terminal: node -v Running the Script: =================== Usage: node google-flow-nano-banana-compare.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE] Replace API_TOKEN with your actual useapi.net API token, see https://useapi.net/docs/start-here/setup-useapi Replace EMAIL with configured Google Flow email account, see https://useapi.net/docs/start-here/setup-google-flow If optional PROMPTS_FILE not provided prompts.json will be used. Example: -------- node google-flow-nano-banana-compare.mjs user:1234-abcdefhijklmnopqrstuv my@email.com Changelog: ========== - July 2, 2026: Initial release. - September 11, 2026: Saves encodedImage when fifeUrl is absent, and writes a downloaded image only once it has been fully received, so a failed download leaves no partial file for the next run to skip as "already exists". */ import fs from 'fs/promises'; import { writeFile } from 'node:fs/promises'; // Constants const DEFAULT_PROMPTS_FILE = 'prompts.json'; const DEFAULT_MODEL = 'nano-banana-2-lite'; const SLEEP_RETRY = 30 * 1000; // in milliseconds const urlAccounts = 'https://api.useapi.net/v1/google-flow/accounts'; const urlImages = 'https://api.useapi.net/v1/google-flow/images'; // Utility to sleep for given milliseconds const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); const elapsedTimeSec = (start) => (Date.now() - start) / 1000; // Function to fetch configured Google Flow API accounts async function fetchAccounts(apiToken) { const response = await fetch(urlAccounts, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.error(`⛔ Error fetching accounts (HTTP ${response.status}): ${response.statusText}`); process.exit(1); } return response.json(); } // Save a single image from its signed fifeUrl. fifeUrl is normally present; when it is absent // the image arrived inline as base64 in encodedImage. A failure is reported and skipped. async function downloadImage(img, filename) { try { await fs.access(filename); console.log(`⚠️ ${filename} already exists. Skipping download.`); return; } catch { // File does not exist, proceed with downloading } const url = img?.fifeUrl; if (!url && img?.encodedImage) { console.log(`✅ Saving ${filename} from encodedImage`); try { await writeFile(filename, Buffer.from(img.encodedImage, 'base64')); } catch (err) { console.error(`⛔ Unable to save ${filename}: ${err}`); } return; } if (!url) { console.error(`🛑 No fifeUrl or encodedImage for ${filename}`); return; } console.log(`✅ Downloading ${filename}`); try { const imageResponse = await fetch(url); if (!imageResponse.ok) { console.error(`⛔ Unable to download ${filename} (HTTP ${imageResponse.status})`); return; } // Read the whole body before creating the file, so a failed download leaves no // partial file behind for the next run to skip as "already exists". const data = Buffer.from(await imageResponse.arrayBuffer()); await writeFile(filename, data); } catch (err) { console.error(`⛔ Error during download: ${err}`); } } // Submit a single prompt to the synchronous POST /images endpoint and download the results. async function submitImage(apiToken, email, prompt, index) { const model = prompt.model ?? DEFAULT_MODEL; // Build the request body. const body = { model, email, prompt: prompt.prompt }; for (const key of ['aspectRatio', 'count', 'seed']) if (prompt[key] !== undefined) body[key] = prompt[key]; console.log(`🚀 ${model} » Prompt #${index} • account ${email} …`); const startTime = Date.now(); while (true) { const response = await fetch(urlImages, { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiToken}` }, body: JSON.stringify(body) }); const responseText = await response.text(); if (response.status == 200) { const media = JSON.parse(responseText)?.media ?? []; if (media.length == 0) console.error(`🛑 200 OK but no media (moderated?) for ${model}`); // count > 1 returns multiple images in the media array. for (let i = 0; i < media.length; i++) { const img = media[i]?.image?.generatedImage; await downloadImage(img, `${model}_${i + 1}.jpg`); } console.log(`🆗 ${model} done (${elapsedTimeSec(startTime)} sec)`); return 200; } switch (response.status) { case 429: case 503: console.log(`🔄️ Retry on HTTP ${response.status}`, responseText); await sleep(SLEEP_RETRY); break; default: console.error(`🛑 ${model} failed with HTTP ${response.status}`, responseText); return response.status; } } } // Main function async function main() { const apiToken = process.argv[2]; const email = process.argv[3]; const promptFile = process.argv[4] || DEFAULT_PROMPTS_FILE; if (!apiToken || !email) { console.error('Usage: node google-flow-nano-banana-compare.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE]'); process.exit(1); } console.info('Script v1.1 • Node version ' + process.version); const accounts = await fetchAccounts(apiToken); if (!accounts[email]) { console.error(`⛔ Account ${email} not found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (accounts[email].health && accounts[email].health !== 'OK') { console.error(`⛔ Account ${email} health is '${accounts[email].health}'. Please resolve and update the account, see https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } const prompts = JSON.parse(await fs.readFile(promptFile, 'utf8')); console.log(`Comparing ${prompts.length} model runs …`); const start = new Date(); for (let i = 0; i < prompts.length; i++) await submitImage(apiToken, email, prompts[i], i + 1); console.info('COMPLETED', new Date(), '• elapsed', elapsedTimeSec(start), 'sec'); } main(); ``` </details> ### Contoh Berikut prompt peternak lebah yang sama yang dibuat oleh tiap model dalam 9:16, lewat Google Flow API ini. Perbedaannya konsisten: Pro paling rapi dan paling patuh pada instruksi, 2.1 paling dinamis, dan Lite paling cepat dengan hasil yang tetap dekat. `nano-banana-pro`: paling rapi dan paling bergaya editorial, dan satu-satunya model yang konsisten menggambar jaring kerudung, lebah yang merayap di sarang, dan mata kartun `o_O` secara harfiah. <img src="https://media.useapi.net/articles/2026-07-02-google-flow-nano-banana-compare/nano-banana-pro.jpg" style="width: 100%; max-width: 420px;" alt="Hasil peternak lebah Nano Banana Pro lewat Google Flow API" /> `nano-banana-2`: interpretasi yang paling dinamis dan energik, dengan kawanan berbentuk panah yang paling jelas dan banyak detail situasi (sepatu bot kerja, lebah di bingkai). <img src="https://media.useapi.net/articles/2026-07-02-google-flow-nano-banana-compare/nano-banana-2.jpg" style="width: 100%; max-width: 420px;" alt="Hasil peternak lebah nano-banana-2 lewat Google Flow API" /> `nano-banana-2-lite`: yang tercepat dari ketiganya (sekitar setengah waktu Pro dalam uji coba kami) sambil tetap mempertahankan komposisi, tetesan madu, dan lebah bermata melotot di latar depan. <img src="https://media.useapi.net/articles/2026-06-15-google-flow-images-bash/nano-banana-2-lite.jpg" style="width: 100%; max-width: 420px;" alt="Hasil peternak lebah Nano Banana 2 Lite lewat Google Flow API" /> ### Model Nano Banana mana yang sebaiknya dipakai? - Pilih `nano-banana-pro` saat fidelitas paling penting: gambar utama, adegan rumit dengan banyak subjek, teks yang presisi, atau kepatuhan instruksi. Model ini yang paling lambat dari ketiganya. - Pilih `nano-banana-2` untuk keseimbangan yang baik antara kualitas dan kecepatan, atau saat Anda ingin interpretasi prompt yang lebih dinamis dan bergaya. - Pilih `nano-banana-2-lite` (default) untuk iterasi dan batch besar saat kecepatan penting dan kualitasnya tetap sangat dekat. Karena bentuk request-nya sama, berganti model cukup mengubah satu kata di `model`: buat satu batch dengan ketiganya lalu pilih yang terbaik, persis seperti yang dilakukan skrip di atas. ### Jalankan sendiri Skrip Node.js lengkap, versi Python, dan `prompts.json` ada di [`useapi/google-flow-api/nano-banana-compare`](https://github.com/useapi/google-flow-api/tree/main/nano-banana-compare). Clone, edit `prompts.json`, lalu jalankan satu perintah untuk membuat seluruh set perbandingan dengan akun Google Flow Anda. ### Pertanyaan yang sering diajukan - **Apakah ada API Nano Banana 2.1 atau Nano Banana Pro?** Lewat useapi.net, ada: [Google Flow API](/docs/api-google-flow-v1) menjalankan versi Google Flow sebagai `nano-banana-2` (Nano Banana 2.1), `nano-banana-2-lite`, dan `nano-banana-pro` di [POST /images](/docs/api-google-flow-v1/post-google-flow-images). Di [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) resmi, Nano Banana 2.1 sekitar $0,034 per gambar 1K dan Nano Banana Pro $0,134 per gambar, sedangkan di sini tidak ada biaya per gambar (per November 2026). - **Apa beda Nano Banana 2 Lite, 2.1, dan Pro?** Lewat useapi.net ketiganya berjalan di endpoint yang sama, masing-masing dengan keunggulannya. `nano-banana-pro` (Gemini 3 Pro Image) paling rapi dan paling patuh pada instruksi, `nano-banana-2` (Nano Banana 2.1) memberi interpretasi paling dinamis, dan `nano-banana-2-lite` (Gemini 3.1 Flash-Lite Image), yang menjadi default, butuh sekitar setengah waktu Pro dalam uji coba kami. Lihat [Model mana yang sebaiknya dipakai?](#which-nano-banana-model-should-you-use) - **Berapa biaya API Nano Banana?** Lewat useapi.net, gambar tidak memakai kredit Flow di langganan Google AI mana pun, termasuk akun gratis, dan tidak ada Gemini API key atau akun penagihan Cloud yang perlu disiapkan. Di [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) resmi, Nano Banana 2 Lite sekitar $0,034 per gambar 1K (per November 2026). Lihat [Harga](#pricing). - **Apakah gambar dimoderasi?** Lewat useapi.net, prompt Anda tetap melewati moderasi konten milik Google sendiri, dan request yang ditolak mengembalikan hasil kosong. Keputusan moderasi berbeda-beda antar-request dan antar-model, jadi mencoba ulang, mengubah prompt, atau berganti model sering berhasil, karena tiap model Nano Banana memoderasi sedikit berbeda. - **Apakah saya perlu captcha atau project Google Cloud?** Lewat useapi.net Anda tidak perlu project Google Cloud maupun menyelesaikan captcha sendiri. Google Flow meminta reCAPTCHA untuk setiap gambar, dan worker useapi.net menyelesaikannya otomatis: akun Google Flow pertama Anda mendapat 300 penyelesaian gratis dengan key AntiCaptcha, CapSolver, dan EzCaptcha milik kami, lalu setelah itu Anda menambahkan key penyedia Anda sendiri. Skrip di panduan ini tidak mengirim `captchaToken`. ### Kesimpulan Kunjungi <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Server Discord</a> atau <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Channel Telegram</a> kami untuk pertanyaan dan masalah dukungan. Lihat [repo GitHub](https://github.com/useapi/google-flow-api) kami berisi contoh kode. #### Dipublikasikan juga di {: .no_toc #cross-posted } Juga dipublikasikan di [dev.to](https://dev.to/useapi/nano-banana-2-lite-vs-2-vs-pro-google-flow-image-models-compared-3b15){:rel="nofollow"} (bahasa Inggris) dan didiskusikan di [Reddit](https://www.reddit.com/r/ThirdPartyAPI/comments/1ulw4zo/nano_banana_2_lite_vs_2_vs_pro_google_flow_image/){:rel="nofollow"} (bahasa Inggris). ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-flow-nano-banana-compare-ja === Document URL: https://useapi.net/docs/articles/google-flow-nano-banana-compare-ja --- layout: default title: "Nano Banana 2 Lite・2.1・Pro を比較:Google Flow の3つの画像モデル" description: "useapi.net の Google Flow API で、Google Flow の3つの Nano Banana 画像モデル(2 Lite、2.1、Pro)を同じプロンプトで比較。実行できるスクリプトと実際の生成例付き。" keywords: [Nano Banana 2 Lite, Nano Banana 2.1, Nano Banana 2, Nano Banana Pro, Gemini 3 Pro Image, Gemini 3.1 Flash Image, Gemini 3.1 Flash-Lite Image, nano-banana-2-lite, Nano Banana API, Nano Banana Pro API, image model comparison, Google Flow API, Nano Banana 比較, Nano Banana Pro API 料金, 画像生成モデル 比較, 画像生成 API, AI 画像生成, 日本語チュートリアル, Japanese tutorial] image: https://media.useapi.net/articles/2026-07-02-google-flow-nano-banana-compare/nano-banana-pro.jpg parent: Articles nav_exclude: true lang: ja translation_key: nano-banana-compare date: 2026-07-02 last_modified: 2026-11-06 nav_order: 830 repo: https://github.com/useapi/google-flow-api --- ## Nano Banana 2 Lite・2.1・Pro を比較:Google Flow の3つの画像モデル {: .no_toc #nano-banana-2-lite-vs-21-vs-pro-google-flow-image-models-compared } 7分で読めます • 2026年7月2日(2026年11月6日更新) useapi.net はサードパーティの API です。Google とは提携しておらず、Google の承認も受けていません。 ## 目次 {: .no_toc .text-delta #table-of-contents } ### はじめに Google Flow には `nano-banana-2-lite`、`nano-banana-2`、`nano-banana-pro` の3つの Nano Banana 画像モデルがあり、useapi.net の [Google Flow API](/docs/api-google-flow-v1) なら、お使いの [Google Flow](https://flow.google.com) アカウントで3つすべてを1つのプロンプトから実行できます。画像の生成は無料アカウントを含むすべての [Google AI のプラン](https://gemini.google/subscriptions/)に含まれていますが、公式の Gemini API では画像1枚に $0.034〜$0.134 かかります(2026年11月時点)。Google Cloud プロジェクトも API キーも不要です。 このガイドでは、まったく同じプロンプトを Lite、2.1、Pro で実行して違いを確かめ、そのうえで全セットを1つのコマンドで生成できる Node.js スクリプトを紹介します。まずは基本から知りたい場合は、姉妹編の[画像生成チュートリアル](/docs/articles/google-flow-images-bash-ja)をご覧ください。 ### 3つの Nano Banana モデルとは? モデルはリクエストごとに `model` フィールドで選びます。省略すると、Google Flow は2026年7月からのデフォルトである `nano-banana-2-lite` を使います。3つのモデルはどれも、無料アカウントを含むすべての Google AI のプランで使えます。 | モデル ID | 製品名 | 向いている用途 | 参照画像(I2I) | 速度 | |----------|----------------|----------|-----------------:|-------| | `nano-banana-2-lite` *(デフォルト)* | [Nano Banana 2 Lite](https://deepmind.google/models/gemini-image/flash-lite/) / Gemini 3.1 Flash-Lite Image | どのプランでも速く大量に生成 | 最大10枚 | 最速 | | `nano-banana-2` | Nano Banana 2.1 | 品質と速度のバランス | 最大10枚 | 速い | | `nano-banana-pro` | [Nano Banana Pro](https://deepmind.google/models/gemini-image/pro/) / Gemini 3 Pro Image | 最高の忠実度と指示への追従 | 最大10枚 | 遅め | 3つのモデルはどれも同じアスペクト比(`16:9`、`4:3`、`1:1`、`3:4`、`9:16`、画像から画像のモードでは `auto` も)、`count`(1〜4)、結果を再現するための `seed`、最大10枚の参照画像、プロンプト内の `@` メンション、[2K/4K へのアップスケール](#upscaling-to-2k4k)に対応しています。非推奨のエイリアス `imagen-4`(Google は2026年7月に Google Flow から Imagen を削除しました)と `nano-banana` も引き続き使え、それぞれ `nano-banana-2-lite` と `nano-banana-2` に対応します。モデルごとの詳細は [POST /images](/docs/api-google-flow-v1/post-google-flow-images) のリファレンスにあります。 #### 2K/4K へのアップスケール 生成したどの画像も、[POST /images/upscale](/docs/api-google-flow-v1/post-google-flow-images-upscale) でアップスケールできます。画像の `mediaGenerationId` と、`resolution` に `2k`(デフォルト)または `4k` を渡します。応答は `encodedImage` に入った base64 です。`2k` はどのプランでも使え、`4k` には Google AI Ultra が必要です。 ### 料金 画像は無料アカウントを含むどの Google AI のプランでも Flow クレジットを消費せず、useapi.net も画像ごとの料金を取りません。全モデル・全プランの料金と公式 API との比較は [Google Flow の料金表](/docs/api-google-flow-v1#pricing)にあります。アカウントの接続方法は[セットアップガイド](/docs/start-here/setup-google-flow)をご覧ください。 ### 比較に使うプロンプト モデルの比較は、プロンプトが難しくなければ意味がありません。このプロンプトはわざと突飛な1コマの場面にしてあり、いくつもの点を同時に試します。名前を挙げた写真のスタイル(David LaChapelle)、複数の被写体の配置(左上で矢印の形になる蜂の群れと、右下の遠近法を誇張した1匹の蜂)、小道具の再現度(蜜がしたたる巣板)、特定のコミカルな表情(`o_O` の漫画風の目)、そしてちぐはぐなトーンを、すべて1枚のまとまった画像に収める必要があります。 ```text A visually breathtaking, beautifully absurd, single-frame photograph in the hyper-saturated, glossy, surreal-comedy editorial style of David LaChapelle, shot at a sun-dappled backyard apiary at golden hour on an 85mm f/1.4 lens with creamy shallow depth of field. In the center midground, a gorgeous, radiant young woman beekeeper with an elegant figure, flawless glowing sun-kissed skin and a warm playful smile, incongruously wearing a tiny mini bikini and a beekeeper's veil hat pushed back off her face, stands among the wooden hive boxes on the grass and lifts a single open beehive frame heavy with golden honeycomb, thick honey oozing and stringing down in glossy ribbons and catching the light. She looks directly into the camera, delighted and completely unbothered by the bees swirling around her. In the top-left of the frame, a dense swarm of bees bunches together and organizes into a bold, unmistakable arrow / pointer shape aimed straight at her, as if frantically calling everyone's attention. In the extreme bottom-right foreground of the exact same scene, photobombing the lens, is a huge forced-perspective close-up of a single frazzled worker bee, staring directly into the camera with bulging, mind-blown "o_O" cartoon googly eyes, completely frozen in comical disbelief. Single cohesive image, seamless depth of field, no cut-ins, warm dynamic backlighting, glistening honey highlights, crazy situational comedy, hyper-detailed, masterpiece. ``` ### 3つのモデルで生成する useapi.net の [API トークン](/docs/start-here/setup-useapi)と、接続済みの [Google Flow アカウント](/docs/start-here/setup-google-flow)が必要です。`POST /images` は同期です。1回の呼び出しが画像の完成まで待ち(通常20〜60秒、混雑時は Pro モデルで最大2分ほど)、画像1枚につき1件の `media[]` 配列を返すので、ポーリングする `jobid` はありません。 1回の呼び出しです。`model` を差し替えて比べます。 ```bash curl -X POST "https://api.useapi.net/v1/google-flow/images" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model": "nano-banana-pro", "aspectRatio": "9:16", "count": 4, "prompt": "A beekeeper at golden hour lifting a dripping honeycomb frame, a swarm forming an arrow in the sky, a forced-perspective bee with o_O googly eyes in the foreground" }' > result.json # 各画像は .media[N].image.generatedImage.fifeUrl にあります curl -o pro_1.jpg "$(jq -r '.media[0].image.generatedImage.fifeUrl' result.json)" ``` 比較全体を1つのコマンドで実行するには、下の Node.js スクリプトを使います。`prompts.json`(モデルごとに1件、プロンプトはすべて同じ)を読み込んで1件ずつ送信し、返ってきた画像をすべてモデル名入りのファイル名で保存します。画像は `fifeUrl` からダウンロードし、URL がない場合はインラインの `encodedImage` をデコードします。失敗した画像はログに記録して、次に進みます。[Node.js](https://nodejs.org) v21 以降が必要です。2つのファイルを同じフォルダーに置き、`node ./google-flow-nano-banana-compare.mjs API_TOKEN EMAIL` を実行します。`API_TOKEN` は useapi.net の [API トークン](/docs/start-here/setup-useapi)、`EMAIL` は接続済みの [Google Flow アカウント](/docs/start-here/setup-google-flow)です。スクリプトはメールアドレスからアカウントを探して送信前に `health` を確認し、`captchaToken` は送りません。reCAPTCHA は useapi.net のワーカーが自動で解決します。 クローンして実行したい場合は、スクリプトの完全版、Python 版、`prompts.json` が GitHub の [`useapi/google-flow-api`](https://github.com/useapi/google-flow-api/tree/main/nano-banana-compare) にあります。 <details markdown="block"> <summary>`prompts.json` を表示</summary> ```json [ { "model": "nano-banana-2-lite", "aspectRatio": "9:16", "count": 4, "prompt": "A beekeeper at golden hour lifting a dripping honeycomb frame in the surreal editorial style of David LaChapelle, a dense bee swarm forming a bold arrow in the top-left, a forced-perspective bee with o_O cartoon googly eyes photobombing the bottom-right. Single cohesive image, masterpiece." }, { "model": "nano-banana-2", "aspectRatio": "9:16", "count": 4, "prompt": "A beekeeper at golden hour lifting a dripping honeycomb frame in the surreal editorial style of David LaChapelle, a dense bee swarm forming a bold arrow in the top-left, a forced-perspective bee with o_O cartoon googly eyes photobombing the bottom-right. Single cohesive image, masterpiece." }, { "model": "nano-banana-pro", "aspectRatio": "9:16", "count": 4, "prompt": "A beekeeper at golden hour lifting a dripping honeycomb frame in the surreal editorial style of David LaChapelle, a dense bee swarm forming a bold arrow in the top-left, a forced-perspective bee with o_O cartoon googly eyes photobombing the bottom-right. Single cohesive image, masterpiece." } ] ``` </details> <details markdown="block"> <summary>`google-flow-nano-banana-compare.mjs` スクリプトを表示</summary> ```javascript /* Script version 1.1, September 11, 2026 Batch-compare Google Flow's Nano Banana image models (2 Lite, 2.1, Pro) with the useapi.net API 🚀 Reads prompts.json (one entry per model), submits each to the synchronous POST /images endpoint, and downloads every returned image with a model-labeled filename. For more details visit https://useapi.net/docs/api-google-flow-v1/post-google-flow-images Companion tutorial: https://useapi.net/docs/articles/google-flow-nano-banana-compare Installation Instructions: ========================== You need Node.js v21 or newer installed to run this script. Download and install Node.js from: - Windows, macOS, Linux: https://nodejs.org/ After installation, verify by running the following command in a terminal: node -v Running the Script: =================== Usage: node google-flow-nano-banana-compare.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE] Replace API_TOKEN with your actual useapi.net API token, see https://useapi.net/docs/start-here/setup-useapi Replace EMAIL with configured Google Flow email account, see https://useapi.net/docs/start-here/setup-google-flow If optional PROMPTS_FILE not provided prompts.json will be used. Example: -------- node google-flow-nano-banana-compare.mjs user:1234-abcdefhijklmnopqrstuv my@email.com Changelog: ========== - July 2, 2026: Initial release. - September 11, 2026: Saves encodedImage when fifeUrl is absent, and writes a downloaded image only once it has been fully received, so a failed download leaves no partial file for the next run to skip as "already exists". */ import fs from 'fs/promises'; import { writeFile } from 'node:fs/promises'; // Constants const DEFAULT_PROMPTS_FILE = 'prompts.json'; const DEFAULT_MODEL = 'nano-banana-2-lite'; const SLEEP_RETRY = 30 * 1000; // in milliseconds const urlAccounts = 'https://api.useapi.net/v1/google-flow/accounts'; const urlImages = 'https://api.useapi.net/v1/google-flow/images'; // Utility to sleep for given milliseconds const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); const elapsedTimeSec = (start) => (Date.now() - start) / 1000; // Function to fetch configured Google Flow API accounts async function fetchAccounts(apiToken) { const response = await fetch(urlAccounts, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.error(`⛔ Error fetching accounts (HTTP ${response.status}): ${response.statusText}`); process.exit(1); } return response.json(); } // Save a single image from its signed fifeUrl. fifeUrl is normally present; when it is absent // the image arrived inline as base64 in encodedImage. A failure is reported and skipped. async function downloadImage(img, filename) { try { await fs.access(filename); console.log(`⚠️ ${filename} already exists. Skipping download.`); return; } catch { // File does not exist, proceed with downloading } const url = img?.fifeUrl; if (!url && img?.encodedImage) { console.log(`✅ Saving ${filename} from encodedImage`); try { await writeFile(filename, Buffer.from(img.encodedImage, 'base64')); } catch (err) { console.error(`⛔ Unable to save ${filename}: ${err}`); } return; } if (!url) { console.error(`🛑 No fifeUrl or encodedImage for ${filename}`); return; } console.log(`✅ Downloading ${filename}`); try { const imageResponse = await fetch(url); if (!imageResponse.ok) { console.error(`⛔ Unable to download ${filename} (HTTP ${imageResponse.status})`); return; } // Read the whole body before creating the file, so a failed download leaves no // partial file behind for the next run to skip as "already exists". const data = Buffer.from(await imageResponse.arrayBuffer()); await writeFile(filename, data); } catch (err) { console.error(`⛔ Error during download: ${err}`); } } // Submit a single prompt to the synchronous POST /images endpoint and download the results. async function submitImage(apiToken, email, prompt, index) { const model = prompt.model ?? DEFAULT_MODEL; // Build the request body. const body = { model, email, prompt: prompt.prompt }; for (const key of ['aspectRatio', 'count', 'seed']) if (prompt[key] !== undefined) body[key] = prompt[key]; console.log(`🚀 ${model} » Prompt #${index} • account ${email} …`); const startTime = Date.now(); while (true) { const response = await fetch(urlImages, { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiToken}` }, body: JSON.stringify(body) }); const responseText = await response.text(); if (response.status == 200) { const media = JSON.parse(responseText)?.media ?? []; if (media.length == 0) console.error(`🛑 200 OK but no media (moderated?) for ${model}`); // count > 1 returns multiple images in the media array. for (let i = 0; i < media.length; i++) { const img = media[i]?.image?.generatedImage; await downloadImage(img, `${model}_${i + 1}.jpg`); } console.log(`🆗 ${model} done (${elapsedTimeSec(startTime)} sec)`); return 200; } switch (response.status) { case 429: case 503: console.log(`🔄️ Retry on HTTP ${response.status}`, responseText); await sleep(SLEEP_RETRY); break; default: console.error(`🛑 ${model} failed with HTTP ${response.status}`, responseText); return response.status; } } } // Main function async function main() { const apiToken = process.argv[2]; const email = process.argv[3]; const promptFile = process.argv[4] || DEFAULT_PROMPTS_FILE; if (!apiToken || !email) { console.error('Usage: node google-flow-nano-banana-compare.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE]'); process.exit(1); } console.info('Script v1.1 • Node version ' + process.version); const accounts = await fetchAccounts(apiToken); if (!accounts[email]) { console.error(`⛔ Account ${email} not found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (accounts[email].health && accounts[email].health !== 'OK') { console.error(`⛔ Account ${email} health is '${accounts[email].health}'. Please resolve and update the account, see https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } const prompts = JSON.parse(await fs.readFile(promptFile, 'utf8')); console.log(`Comparing ${prompts.length} model runs …`); const start = new Date(); for (let i = 0; i < prompts.length; i++) await submitImage(apiToken, email, prompts[i], i + 1); console.info('COMPLETED', new Date(), '• elapsed', elapsedTimeSec(start), 'sec'); } main(); ``` </details> ### 例 同じ養蜂家のプロンプトを、各モデルがこの Google Flow API を通じて 9:16 で生成した結果です。違いには一貫性があります。Pro は最も洗練されていて指示に最も忠実、2.1 は最も躍動感があり、Lite は最も速いうえに仕上がりも近いです。 `nano-banana-pro`:最も洗練された雑誌の誌面のような仕上がりで、ベールの網、巣板の上を這う蜂、文字どおりの `o_O` の漫画風の目を安定して描けたのはこのモデルだけでした。 <img src="https://media.useapi.net/articles/2026-07-02-google-flow-nano-banana-compare/nano-banana-pro.jpg" style="width: 100%; max-width: 420px;" alt="Google Flow API で生成した Nano Banana Pro の養蜂家の画像" /> `nano-banana-2`:最も躍動感とエネルギーのある解釈で、矢印の形の群れが最もはっきりしていて、場面の細部(作業用のブーツ、巣枠の上の蜂)も豊富です。 <img src="https://media.useapi.net/articles/2026-07-02-google-flow-nano-banana-compare/nano-banana-2.jpg" style="width: 100%; max-width: 420px;" alt="Google Flow API で生成した nano-banana-2 の養蜂家の画像" /> `nano-banana-2-lite`:3つの中で最も速く(私たちの実行では Pro のおよそ半分の時間)、構図、したたる蜂蜜、手前の目をむいた蜂もきちんと保っています。 <img src="https://media.useapi.net/articles/2026-06-15-google-flow-images-bash/nano-banana-2-lite.jpg" style="width: 100%; max-width: 420px;" alt="Google Flow API で生成した Nano Banana 2 Lite の養蜂家の画像" /> ### どの Nano Banana モデルを使うべき? - 忠実度を最優先するなら `nano-banana-pro`。メインビジュアル、複数の被写体がいる複雑な場面、正確な文字や指示への追従に向いています。3つの中では最も遅いモデルです。 - 品質と速度のバランスを取りたいとき、またはプロンプトをより躍動的で個性的に解釈してほしいときは `nano-banana-2`。 - 試行錯誤や大量の一括生成で速度が大事なときは `nano-banana-2-lite`(デフォルト)。品質もかなり近いままです。 リクエストの形が同じなので、切り替えは `model` の1語を変えるだけです。上のスクリプトのように3つすべてでまとめて生成し、いちばん良いものを選べます。 ### 自分で実行する Node.js スクリプトの完全版、Python 版、`prompts.json` は [`useapi/google-flow-api/nano-banana-compare`](https://github.com/useapi/google-flow-api/tree/main/nano-banana-compare) にあります。クローンして `prompts.json` を編集し、コマンドを1つ実行すれば、お使いの Google Flow アカウントで比較の全セットを生成できます。 ### よくある質問 - **Nano Banana 2.1 や Nano Banana Pro の API はありますか?** useapi.net を使えば、あります。[Google Flow API](/docs/api-google-flow-v1) は、Google Flow のバージョンを [POST /images](/docs/api-google-flow-v1/post-google-flow-images) で `nano-banana-2`(Nano Banana 2.1)、`nano-banana-2-lite`、`nano-banana-pro` として実行します。公式の [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) では Nano Banana 2.1 が 1K の画像1枚で約 $0.034、Nano Banana Pro が1枚 $0.134 ですが、こちらでは画像ごとの料金はかかりません(2026年11月時点)。 - **Nano Banana 2 Lite、2.1、Pro の違いは何ですか?** useapi.net では3つとも同じエンドポイントで動き、それぞれに強みがあります。`nano-banana-pro`(Gemini 3 Pro Image)は最も洗練されていて指示に最も忠実、`nano-banana-2`(Nano Banana 2.1)は最も躍動的な解釈をし、デフォルトの `nano-banana-2-lite`(Gemini 3.1 Flash-Lite Image)は私たちの実行で Pro のおよそ半分の時間で終わりました。[どのモデルを使うべき?](#which-nano-banana-model-should-you-use)をご覧ください。 - **Nano Banana API の料金はいくらですか?** useapi.net なら、無料アカウントを含むどの Google AI のプランでも画像は Flow クレジットを消費せず、Gemini API キーや Cloud の請求先アカウントの設定もいりません。公式の [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) では、Nano Banana 2 Lite は 1K の画像1枚で約 $0.034 です(2026年11月時点)。[料金](#pricing)をご覧ください。 - **画像はモデレーションされますか?** useapi.net 経由でも、プロンプトは Google 自身のコンテンツモデレーションを通り、拒否されたリクエストは空の結果を返します。モデレーションの判断はリクエストやモデルによって変わるため、再試行、プロンプトの修正、モデルの切り替えでうまくいくことがよくあります。Nano Banana の各モデルでモデレーションが少しずつ違うためです。 - **CAPTCHA や Google Cloud プロジェクトは必要ですか?** useapi.net なら、Google Cloud プロジェクトもご自身での CAPTCHA の対応も不要です。Google Flow は画像ごとに reCAPTCHA を求めますが、useapi.net のワーカーが自動で解決します。最初の Google Flow アカウントには、当社の AntiCaptcha、CapSolver、EzCaptcha のキーで300回の無料解決が付き、その後はご自身のプロバイダーのキーを追加します。このガイドのスクリプトは `captchaToken` を送りません。 ### おわりに ご質問は <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord サーバー</a> または <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram チャンネル</a>へどうぞ。 コード例は [GitHub リポジトリ](https://github.com/useapi/google-flow-api)にあります。 #### ほかの掲載先 {: .no_toc #cross-posted } この記事(英語版)は [dev.to](https://dev.to/useapi/nano-banana-2-lite-vs-2-vs-pro-google-flow-image-models-compared-3b15){:rel="nofollow"} にも掲載し、[Reddit](https://www.reddit.com/r/ThirdPartyAPI/comments/1ulw4zo/nano_banana_2_lite_vs_2_vs_pro_google_flow_image/){:rel="nofollow"} でも話題にしています。 ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-flow-nano-banana-compare-pt === Document URL: https://useapi.net/docs/articles/google-flow-nano-banana-compare-pt --- layout: default title: "Nano Banana 2 Lite vs 2.1 vs Pro: os modelos de imagem do Google Flow comparados" description: "Compare os três modelos de imagem Nano Banana do Google Flow (2 Lite, 2.1 e Pro) com o mesmo prompt pela API da useapi.net, com um script pronto para rodar e exemplos reais." keywords: [Nano Banana 2 Lite, Nano Banana 2.1, Nano Banana 2, Nano Banana Pro, Gemini 3 Pro Image, Gemini 3.1 Flash Image, Gemini 3.1 Flash-Lite Image, nano-banana-2-lite, Nano Banana API, Nano Banana Pro API, image model comparison, Google Flow API, API do Nano Banana, API do Nano Banana Pro, comparação de modelos de imagem, gerar imagens com IA, API de geração de imagens, tutorial, código] image: https://media.useapi.net/articles/2026-07-02-google-flow-nano-banana-compare/nano-banana-pro.jpg parent: Articles nav_exclude: true lang: pt-BR translation_key: nano-banana-compare date: 2026-07-02 last_modified: 2026-11-06 nav_order: 830 repo: https://github.com/useapi/google-flow-api --- ## Nano Banana 2 Lite vs 2.1 vs Pro: os modelos de imagem do Google Flow comparados {: .no_toc #nano-banana-2-lite-vs-21-vs-pro-google-flow-image-models-compared } 7 min de leitura • 2 de julho de 2026 (6 de novembro de 2026) A useapi.net é uma API de terceiros. Não tem afiliação com o Google nem é endossada por ele. ## Sumário {: .no_toc .text-delta #table-of-contents } ### Introdução O Google Flow oferece três modelos de imagem Nano Banana, `nano-banana-2-lite`, `nano-banana-2` e `nano-banana-pro`, e a [Google Flow API](/docs/api-google-flow-v1) da useapi.net roda os três a partir de um único prompt com a sua conta do [Google Flow](https://flow.google.com). As imagens estão incluídas em toda [assinatura do Google AI](https://gemini.google/subscriptions/), até numa conta gratuita, enquanto a Gemini API oficial cobra de $0,034 a $0,134 por imagem (em novembro de 2026). Não precisa de projeto no Google Cloud nem de chave de API. Este guia roda exatamente o mesmo prompt no Lite, no 2.1 e no Pro para você ver como eles diferem, e depois entrega um script em Node.js que gera o conjunto inteiro com um só comando. Quer primeiro um passo a passo do zero? Veja o [tutorial de geração de imagens](/docs/articles/google-flow-images-bash-pt), o guia irmão deste. ### Quais são os três modelos Nano Banana? Escolha o modelo em cada requisição com o campo `model`. Se você o omitir, o Google Flow usa o `nano-banana-2-lite`, o padrão dele desde julho de 2026. Os três rodam em qualquer assinatura do Google AI, inclusive numa conta gratuita. | ID do modelo | Nome comercial | Melhor para | Referências (I2I) | Velocidade | |----------|----------------|----------|-----------------:|-------| | `nano-banana-2-lite` *(padrão)* | [Nano Banana 2 Lite](https://deepmind.google/models/gemini-image/flash-lite/) / Gemini 3.1 Flash-Lite Image | imagens rápidas e em grande volume, em qualquer plano | até 10 | a mais rápida | | `nano-banana-2` | Nano Banana 2.1 | equilíbrio entre qualidade e velocidade | até 10 | rápida | | `nano-banana-pro` | [Nano Banana Pro](https://deepmind.google/models/gemini-image/pro/) / Gemini 3 Pro Image | máxima fidelidade e respeito às instruções | até 10 | mais lenta | Os três aceitam as mesmas proporções (`16:9`, `4:3`, `1:1`, `3:4`, `9:16`, mais `auto` no modo imagem para imagem), `count` (1–4), `seed` para reprodutibilidade, até 10 imagens de referência, `@`-menções inline e [upscale para 2K/4K](#upscaling-to-2k4k). Os aliases obsoletos `imagen-4` (o Google removeu o Imagen do Google Flow em julho de 2026) e `nano-banana` continuam aceitos e correspondem a `nano-banana-2-lite` e `nano-banana-2`, respectivamente. Os detalhes completos de cada modelo estão na referência de [POST /images](/docs/api-google-flow-v1/post-google-flow-images). #### Upscale para 2K/4K Qualquer imagem gerada pode passar por upscale com [POST /images/upscale](/docs/api-google-flow-v1/post-google-flow-images-upscale): passe o `mediaGenerationId` dela e um `resolution` de `2k` (padrão) ou `4k`. A resposta vem em base64 no `encodedImage`. O `2k` funciona em qualquer plano, e o `4k` exige o Google AI Ultra. ### Preços As imagens não consomem créditos do Flow em nenhuma assinatura do Google AI, inclusive numa conta gratuita, e a useapi.net não cobra nada por imagem. O preço de cada modelo em cada plano, comparado com a API oficial, está na [tabela de preços do Google Flow](/docs/api-google-flow-v1#pricing). Veja o [guia de configuração](/docs/start-here/setup-google-flow) para conectar a sua conta. ### O prompt da comparação Uma comparação de modelos só serve se o prompt for difícil. Este é uma cena absurda de propósito, num único quadro, que testa várias coisas ao mesmo tempo: um estilo fotográfico com nome (David LaChapelle), um layout espacial com vários sujeitos (um enxame formando uma seta no canto superior esquerdo, uma abelha em perspectiva forçada no canto inferior direito), a fidelidade de um objeto (um favo pingando mel), uma expressão cômica específica (olhos de desenho `o_O`) e um tom contraditório, tudo numa única imagem coesa. ```text A visually breathtaking, beautifully absurd, single-frame photograph in the hyper-saturated, glossy, surreal-comedy editorial style of David LaChapelle, shot at a sun-dappled backyard apiary at golden hour on an 85mm f/1.4 lens with creamy shallow depth of field. In the center midground, a gorgeous, radiant young woman beekeeper with an elegant figure, flawless glowing sun-kissed skin and a warm playful smile, incongruously wearing a tiny mini bikini and a beekeeper's veil hat pushed back off her face, stands among the wooden hive boxes on the grass and lifts a single open beehive frame heavy with golden honeycomb, thick honey oozing and stringing down in glossy ribbons and catching the light. She looks directly into the camera, delighted and completely unbothered by the bees swirling around her. In the top-left of the frame, a dense swarm of bees bunches together and organizes into a bold, unmistakable arrow / pointer shape aimed straight at her, as if frantically calling everyone's attention. In the extreme bottom-right foreground of the exact same scene, photobombing the lens, is a huge forced-perspective close-up of a single frazzled worker bee, staring directly into the camera with bulging, mind-blown "o_O" cartoon googly eyes, completely frozen in comical disbelief. Single cohesive image, seamless depth of field, no cut-ins, warm dynamic backlighting, glistening honey highlights, crazy situational comedy, hyper-detailed, masterpiece. ``` ### Gere com os três modelos Você precisa de um [token de API](/docs/start-here/setup-useapi) da useapi.net e de uma [conta do Google Flow](/docs/start-here/setup-google-flow) conectada. O `POST /images` é síncrono: uma chamada espera até as imagens ficarem prontas (normalmente de 20 a 60 segundos, e o modelo Pro pode levar até uns 2 minutos sob carga) e devolve um array `media[]` com uma entrada por imagem, então não há `jobid` para consultar. Uma única chamada, troque o `model` para comparar: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/images" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model": "nano-banana-pro", "aspectRatio": "9:16", "count": 4, "prompt": "A beekeeper at golden hour lifting a dripping honeycomb frame, a swarm forming an arrow in the sky, a forced-perspective bee with o_O googly eyes in the foreground" }' > result.json # cada imagem fica em .media[N].image.generatedImage.fifeUrl curl -o pro_1.jpg "$(jq -r '.media[0].image.generatedImage.fifeUrl' result.json)" ``` Para rodar a comparação inteira com um só comando, o script em Node.js abaixo lê o `prompts.json` (uma entrada por modelo, todas com o mesmo prompt), envia cada uma e salva cada imagem devolvida com o nome do modelo no arquivo, baixando-a do `fifeUrl` ou decodificando o `encodedImage` inline quando a URL não vem. Uma imagem que falha é registrada no log e o script segue em frente. Você precisa do [Node.js](https://nodejs.org) v21+. Coloque os dois arquivos numa pasta e rode `node ./google-flow-nano-banana-compare.mjs API_TOKEN EMAIL`, em que `API_TOKEN` é o seu [token de API](/docs/start-here/setup-useapi) da useapi.net e `EMAIL` é a sua [conta do Google Flow](/docs/start-here/setup-google-flow) conectada. O script procura a conta pelo e-mail, confere o `health` dela antes de enviar e não manda `captchaToken`: o worker da useapi.net resolve o reCAPTCHA automaticamente. Prefere clonar e rodar? O script completo, uma versão em Python e o `prompts.json` estão no GitHub em [`useapi/google-flow-api`](https://github.com/useapi/google-flow-api/tree/main/nano-banana-compare). <details markdown="block"> <summary>Abrir `prompts.json`</summary> ```json [ { "model": "nano-banana-2-lite", "aspectRatio": "9:16", "count": 4, "prompt": "A beekeeper at golden hour lifting a dripping honeycomb frame in the surreal editorial style of David LaChapelle, a dense bee swarm forming a bold arrow in the top-left, a forced-perspective bee with o_O cartoon googly eyes photobombing the bottom-right. Single cohesive image, masterpiece." }, { "model": "nano-banana-2", "aspectRatio": "9:16", "count": 4, "prompt": "A beekeeper at golden hour lifting a dripping honeycomb frame in the surreal editorial style of David LaChapelle, a dense bee swarm forming a bold arrow in the top-left, a forced-perspective bee with o_O cartoon googly eyes photobombing the bottom-right. Single cohesive image, masterpiece." }, { "model": "nano-banana-pro", "aspectRatio": "9:16", "count": 4, "prompt": "A beekeeper at golden hour lifting a dripping honeycomb frame in the surreal editorial style of David LaChapelle, a dense bee swarm forming a bold arrow in the top-left, a forced-perspective bee with o_O cartoon googly eyes photobombing the bottom-right. Single cohesive image, masterpiece." } ] ``` </details> <details markdown="block"> <summary>Abrir o script `google-flow-nano-banana-compare.mjs`</summary> ```javascript /* Script version 1.1, September 11, 2026 Batch-compare Google Flow's Nano Banana image models (2 Lite, 2.1, Pro) with the useapi.net API 🚀 Reads prompts.json (one entry per model), submits each to the synchronous POST /images endpoint, and downloads every returned image with a model-labeled filename. For more details visit https://useapi.net/docs/api-google-flow-v1/post-google-flow-images Companion tutorial: https://useapi.net/docs/articles/google-flow-nano-banana-compare Installation Instructions: ========================== You need Node.js v21 or newer installed to run this script. Download and install Node.js from: - Windows, macOS, Linux: https://nodejs.org/ After installation, verify by running the following command in a terminal: node -v Running the Script: =================== Usage: node google-flow-nano-banana-compare.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE] Replace API_TOKEN with your actual useapi.net API token, see https://useapi.net/docs/start-here/setup-useapi Replace EMAIL with configured Google Flow email account, see https://useapi.net/docs/start-here/setup-google-flow If optional PROMPTS_FILE not provided prompts.json will be used. Example: -------- node google-flow-nano-banana-compare.mjs user:1234-abcdefhijklmnopqrstuv my@email.com Changelog: ========== - July 2, 2026: Initial release. - September 11, 2026: Saves encodedImage when fifeUrl is absent, and writes a downloaded image only once it has been fully received, so a failed download leaves no partial file for the next run to skip as "already exists". */ import fs from 'fs/promises'; import { writeFile } from 'node:fs/promises'; // Constants const DEFAULT_PROMPTS_FILE = 'prompts.json'; const DEFAULT_MODEL = 'nano-banana-2-lite'; const SLEEP_RETRY = 30 * 1000; // in milliseconds const urlAccounts = 'https://api.useapi.net/v1/google-flow/accounts'; const urlImages = 'https://api.useapi.net/v1/google-flow/images'; // Utility to sleep for given milliseconds const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); const elapsedTimeSec = (start) => (Date.now() - start) / 1000; // Function to fetch configured Google Flow API accounts async function fetchAccounts(apiToken) { const response = await fetch(urlAccounts, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.error(`⛔ Error fetching accounts (HTTP ${response.status}): ${response.statusText}`); process.exit(1); } return response.json(); } // Save a single image from its signed fifeUrl. fifeUrl is normally present; when it is absent // the image arrived inline as base64 in encodedImage. A failure is reported and skipped. async function downloadImage(img, filename) { try { await fs.access(filename); console.log(`⚠️ ${filename} already exists. Skipping download.`); return; } catch { // File does not exist, proceed with downloading } const url = img?.fifeUrl; if (!url && img?.encodedImage) { console.log(`✅ Saving ${filename} from encodedImage`); try { await writeFile(filename, Buffer.from(img.encodedImage, 'base64')); } catch (err) { console.error(`⛔ Unable to save ${filename}: ${err}`); } return; } if (!url) { console.error(`🛑 No fifeUrl or encodedImage for ${filename}`); return; } console.log(`✅ Downloading ${filename}`); try { const imageResponse = await fetch(url); if (!imageResponse.ok) { console.error(`⛔ Unable to download ${filename} (HTTP ${imageResponse.status})`); return; } // Read the whole body before creating the file, so a failed download leaves no // partial file behind for the next run to skip as "already exists". const data = Buffer.from(await imageResponse.arrayBuffer()); await writeFile(filename, data); } catch (err) { console.error(`⛔ Error during download: ${err}`); } } // Submit a single prompt to the synchronous POST /images endpoint and download the results. async function submitImage(apiToken, email, prompt, index) { const model = prompt.model ?? DEFAULT_MODEL; // Build the request body. const body = { model, email, prompt: prompt.prompt }; for (const key of ['aspectRatio', 'count', 'seed']) if (prompt[key] !== undefined) body[key] = prompt[key]; console.log(`🚀 ${model} » Prompt #${index} • account ${email} …`); const startTime = Date.now(); while (true) { const response = await fetch(urlImages, { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiToken}` }, body: JSON.stringify(body) }); const responseText = await response.text(); if (response.status == 200) { const media = JSON.parse(responseText)?.media ?? []; if (media.length == 0) console.error(`🛑 200 OK but no media (moderated?) for ${model}`); // count > 1 returns multiple images in the media array. for (let i = 0; i < media.length; i++) { const img = media[i]?.image?.generatedImage; await downloadImage(img, `${model}_${i + 1}.jpg`); } console.log(`🆗 ${model} done (${elapsedTimeSec(startTime)} sec)`); return 200; } switch (response.status) { case 429: case 503: console.log(`🔄️ Retry on HTTP ${response.status}`, responseText); await sleep(SLEEP_RETRY); break; default: console.error(`🛑 ${model} failed with HTTP ${response.status}`, responseText); return response.status; } } } // Main function async function main() { const apiToken = process.argv[2]; const email = process.argv[3]; const promptFile = process.argv[4] || DEFAULT_PROMPTS_FILE; if (!apiToken || !email) { console.error('Usage: node google-flow-nano-banana-compare.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE]'); process.exit(1); } console.info('Script v1.1 • Node version ' + process.version); const accounts = await fetchAccounts(apiToken); if (!accounts[email]) { console.error(`⛔ Account ${email} not found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (accounts[email].health && accounts[email].health !== 'OK') { console.error(`⛔ Account ${email} health is '${accounts[email].health}'. Please resolve and update the account, see https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } const prompts = JSON.parse(await fs.readFile(promptFile, 'utf8')); console.log(`Comparing ${prompts.length} model runs …`); const start = new Date(); for (let i = 0; i < prompts.length; i++) await submitImage(apiToken, email, prompts[i], i + 1); console.info('COMPLETED', new Date(), '• elapsed', elapsedTimeSec(start), 'sec'); } main(); ``` </details> ### Exemplos Aqui está o mesmo prompt da apicultora gerado por cada modelo em 9:16, por esta Google Flow API. As diferenças se repetem: o Pro é o mais caprichado e o mais fiel às instruções, o 2.1 é o mais dinâmico e o Lite é o mais rápido e fica bem perto. `nano-banana-pro`: o mais caprichado, com cara de editorial, e o único modelo que acerta sempre a tela do véu, as abelhas andando no favo e os olhos de desenho `o_O` ao pé da letra. <img src="https://media.useapi.net/articles/2026-07-02-google-flow-nano-banana-compare/nano-banana-pro.jpg" style="width: 100%; max-width: 420px;" alt="Apicultora gerada pelo Nano Banana Pro pela Google Flow API" /> `nano-banana-2`: a interpretação mais dinâmica e cheia de energia, com o enxame em forma de seta mais nítido e muitos detalhes da situação (botas de trabalho, abelhas no quadro). <img src="https://media.useapi.net/articles/2026-07-02-google-flow-nano-banana-compare/nano-banana-2.jpg" style="width: 100%; max-width: 420px;" alt="Apicultora gerada pelo nano-banana-2 pela Google Flow API" /> `nano-banana-2-lite`: o mais rápido dos três (cerca de metade do tempo do Pro nos nossos testes), mantendo a composição, o mel escorrendo e a abelha de olhos esbugalhados em primeiro plano. <img src="https://media.useapi.net/articles/2026-06-15-google-flow-images-bash/nano-banana-2-lite.jpg" style="width: 100%; max-width: 420px;" alt="Apicultora gerada pelo Nano Banana 2 Lite pela Google Flow API" /> ### Qual modelo Nano Banana usar? - Use o `nano-banana-pro` quando a fidelidade é o que mais importa: imagens principais, cenas complexas com vários sujeitos, texto preciso ou respeito rigoroso às instruções. Ele é o mais lento dos três. - Use o `nano-banana-2` para um bom equilíbrio entre qualidade e velocidade, ou quando você quer uma leitura mais dinâmica e estilizada do prompt. - Use o `nano-banana-2-lite` (o padrão) para iterar e para lotes grandes em que a velocidade importa e a qualidade continua muito próxima. Como os três usam a mesma requisição, trocar é mudar uma palavra no `model`: gere um lote com os três e escolha o melhor, exatamente como o script acima faz. ### Rode você mesmo O script completo em Node.js, uma versão em Python e o `prompts.json` estão em [`useapi/google-flow-api/nano-banana-compare`](https://github.com/useapi/google-flow-api/tree/main/nano-banana-compare). Clone, edite o `prompts.json` e rode um comando para gerar o conjunto completo da comparação com a sua conta do Google Flow. ### Perguntas frequentes - **Existe uma API do Nano Banana 2.1 ou do Nano Banana Pro?** Pela useapi.net, sim: a [Google Flow API](/docs/api-google-flow-v1) roda as versões do Google Flow como `nano-banana-2` (Nano Banana 2.1), `nano-banana-2-lite` e `nano-banana-pro` no [POST /images](/docs/api-google-flow-v1/post-google-flow-images). Na [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) oficial, o Nano Banana 2.1 custa cerca de $0,034 por imagem 1K e o Nano Banana Pro $0,134 por imagem, contra nenhuma cobrança por imagem aqui (em novembro de 2026). - **Qual é a diferença entre o Nano Banana 2 Lite, o 2.1 e o Pro?** Pela useapi.net os três rodam no mesmo endpoint, cada um com o seu ponto forte. O `nano-banana-pro` (Gemini 3 Pro Image) é o mais caprichado e o que segue as instruções mais de perto, o `nano-banana-2` (Nano Banana 2.1) dá a leitura mais dinâmica, e o `nano-banana-2-lite` (Gemini 3.1 Flash-Lite Image), o padrão, levou cerca de metade do tempo do Pro nos nossos testes. Veja [Qual modelo usar?](#which-nano-banana-model-should-you-use) - **Quanto custa a API do Nano Banana?** Pela useapi.net, as imagens não consomem créditos do Flow em nenhuma assinatura do Google AI, inclusive numa conta gratuita, e não há chave da Gemini API nem conta de faturamento do Cloud para configurar. Na [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) oficial, o Nano Banana 2 Lite custa cerca de $0,034 por imagem 1K (em novembro de 2026). Veja [Preços](#pricing). - **As imagens passam por moderação?** Pela useapi.net, os seus prompts passam pela moderação de conteúdo do próprio Google, e uma requisição rejeitada devolve um resultado vazio. As decisões de moderação variam entre requisições e entre modelos, então tentar de novo, editar o prompt ou trocar de modelo costuma dar certo, porque cada modelo Nano Banana modera de um jeito um pouco diferente. - **Preciso de captcha ou de um projeto no Google Cloud?** Com a useapi.net você não precisa de projeto no Google Cloud nem de resolver captcha por conta própria. O Google Flow pede um reCAPTCHA a cada imagem, e o worker da useapi.net resolve tudo automaticamente: a sua primeira conta do Google Flow vem com 300 resoluções grátis nas nossas próprias chaves da AntiCaptcha, CapSolver e EzCaptcha, e depois disso você adiciona as chaves do seu provedor. O script deste guia não envia `captchaToken`. ### Conclusão Visite o nosso <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> servidor no Discord</a> ou o <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> canal no Telegram</a> para qualquer dúvida de suporte. Veja o nosso [repositório no GitHub](https://github.com/useapi/google-flow-api) com exemplos de código. #### Publicado também em {: .no_toc #cross-posted } Também publicado no [dev.to](https://dev.to/useapi/nano-banana-2-lite-vs-2-vs-pro-google-flow-image-models-compared-3b15){:rel="nofollow"} (em inglês) e discutido no [Reddit](https://www.reddit.com/r/ThirdPartyAPI/comments/1ulw4zo/nano_banana_2_lite_vs_2_vs_pro_google_flow_image/){:rel="nofollow"} (em inglês). ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-flow-nano-banana-compare-th === Document URL: https://useapi.net/docs/articles/google-flow-nano-banana-compare-th --- layout: default title: "Nano Banana 2 Lite vs 2.1 vs Pro: เปรียบเทียบโมเดลสร้างภาพของ Google Flow" description: "เปรียบเทียบโมเดลสร้างภาพ Nano Banana ทั้งสามตัวของ Google Flow (2 Lite, 2.1 และ Pro) ด้วยพรอมต์เดียวกันผ่าน API ของ useapi.net พร้อมสคริปต์ที่รันได้จริงและตัวอย่างจริง" keywords: [Nano Banana 2 Lite, Nano Banana 2.1, Nano Banana 2, Nano Banana Pro, Gemini 3 Pro Image, Gemini 3.1 Flash Image, Gemini 3.1 Flash-Lite Image, nano-banana-2-lite, Nano Banana API, Nano Banana Pro API, image model comparison, Google Flow API, Nano Banana API ภาษาไทย, เปรียบเทียบ Nano Banana, เปรียบเทียบโมเดลสร้างภาพ, API สร้างภาพ, สร้างภาพ AI ด้วย API, ตัวอย่างโค้ด, คู่มือ] image: https://media.useapi.net/articles/2026-07-02-google-flow-nano-banana-compare/nano-banana-pro.jpg parent: Articles nav_exclude: true lang: th translation_key: nano-banana-compare date: 2026-07-02 last_modified: 2026-11-06 nav_order: 830 repo: https://github.com/useapi/google-flow-api --- ## Nano Banana 2 Lite vs 2.1 vs Pro: เปรียบเทียบโมเดลสร้างภาพของ Google Flow {: .no_toc #nano-banana-2-lite-vs-21-vs-pro-google-flow-image-models-compared } อ่าน 7 นาที • 2 กรกฎาคม 2026 (6 พฤศจิกายน 2026) useapi.net เป็น API ของบุคคลที่สาม (third-party) ไม่มีส่วนเกี่ยวข้องกับ Google และไม่ได้รับการรับรองจาก Google ## สารบัญ {: .no_toc .text-delta #table-of-contents } ### บทนำ Google Flow มีโมเดลสร้างภาพ Nano Banana สามตัว คือ `nano-banana-2-lite`, `nano-banana-2` และ `nano-banana-pro` และ [Google Flow API](/docs/api-google-flow-v1) ของ useapi.net รันได้ทั้งสามตัวจากพรอมต์เดียวด้วยบัญชี [Google Flow](https://flow.google.com) ของคุณเอง การสร้างภาพรวมอยู่ในทุก[แพ็กเกจ Google AI](https://gemini.google/subscriptions/) รวมถึงบัญชีฟรี ขณะที่ Gemini API ทางการคิดภาพละ $0.034 ถึง $0.134 (ข้อมูล ณ พฤศจิกายน 2026) ไม่ต้องมีโปรเจกต์ Google Cloud และไม่ต้องมี API key คู่มือนี้รันพรอมต์เดียวกันทุกตัวอักษรกับ Lite, 2.1 และ Pro ให้คุณเห็นว่าต่างกันอย่างไร จากนั้นให้สคริปต์ Node.js ที่รันได้จริงสำหรับสร้างภาพทั้งชุดด้วยคำสั่งเดียว อยากเริ่มจากพื้นฐานก่อน ดู[คู่มือการสร้างภาพ](/docs/articles/google-flow-images-bash-th) ซึ่งเป็นบทความคู่กัน ### โมเดล Nano Banana ทั้งสามตัวคืออะไร? เลือกโมเดลในแต่ละคำขอด้วยฟิลด์ `model` ถ้าไม่ระบุ Google Flow จะใช้ `nano-banana-2-lite` ซึ่งเป็นค่าเริ่มต้นตั้งแต่กรกฎาคม 2026 ทั้งสามโมเดลใช้ได้กับทุกแพ็กเกจ Google AI รวมถึงบัญชีฟรี | ID โมเดล | ชื่อทางการตลาด | เหมาะกับ | ภาพอ้างอิง (I2I) | ความเร็ว | |----------|----------------|----------|-----------------:|-------| | `nano-banana-2-lite` *(ค่าเริ่มต้น)* | [Nano Banana 2 Lite](https://deepmind.google/models/gemini-image/flash-lite/) / Gemini 3.1 Flash-Lite Image | สร้างภาพเร็ว ปริมาณมาก ได้ทุกแพ็กเกจ | สูงสุด 10 | เร็วที่สุด | | `nano-banana-2` | Nano Banana 2.1 | สมดุลระหว่างคุณภาพกับความเร็ว | สูงสุด 10 | เร็ว | | `nano-banana-pro` | [Nano Banana Pro](https://deepmind.google/models/gemini-image/pro/) / Gemini 3 Pro Image | ความสมจริงและการทำตามคำสั่งสูงสุด | สูงสุด 10 | ช้ากว่า | ทั้งสามโมเดลรับอัตราส่วนภาพเหมือนกัน (`16:9`, `4:3`, `1:1`, `3:4`, `9:16` และ `auto` ในโหมดภาพเป็นภาพ) รับ `count` (1–4), `seed` สำหรับสร้างผลลัพธ์ซ้ำ, ภาพอ้างอิงสูงสุด 10 ภาพ, การ `@`-mention ในพรอมต์ และ[การอัปสเกลเป็น 2K/4K](#upscaling-to-2k4k) ชื่อแทนที่เลิกใช้แล้วอย่าง `imagen-4` (Google นำ Imagen ออกจาก Google Flow ในเดือนกรกฎาคม 2026) และ `nano-banana` ยังใช้ได้ โดยจับคู่กับ `nano-banana-2-lite` และ `nano-banana-2` ตามลำดับ รายละเอียดเต็มของแต่ละโมเดลอยู่ในเอกสารอ้างอิง [POST /images](/docs/api-google-flow-v1/post-google-flow-images) #### อัปสเกลเป็น 2K/4K ภาพใดก็ตามที่สร้างแล้วอัปสเกลได้ด้วย [POST /images/upscale](/docs/api-google-flow-v1/post-google-flow-images-upscale) โดยส่ง `mediaGenerationId` ของภาพ และ `resolution` เป็น `2k` (ค่าเริ่มต้น) หรือ `4k` การตอบกลับเป็น base64 ใน `encodedImage` ใช้ `2k` ได้ทุกแพ็กเกจ ส่วน `4k` ต้องใช้ Google AI Ultra ### ราคา การสร้างภาพไม่ใช้เครดิต Flow ในทุกแพ็กเกจ Google AI รวมถึงบัญชีฟรี และ useapi.net ไม่คิดค่าบริการต่อภาพ ราคาของทุกโมเดลในทุกแพ็กเกจเทียบกับ API ทางการ ดูได้ใน[ตารางราคา Google Flow](/docs/api-google-flow-v1#pricing) ดู[คู่มือการตั้งค่า](/docs/start-here/setup-google-flow)เพื่อเชื่อมต่อบัญชีของคุณ ### พรอมต์ที่ใช้เปรียบเทียบ การเปรียบเทียบโมเดลจะมีประโยชน์ก็ต่อเมื่อพรอมต์ยาก พรอมต์นี้ตั้งใจให้เป็นฉากเดียวที่ไร้สาระสุด ๆ เพื่อทดสอบหลายอย่างพร้อมกัน ได้แก่ สไตล์ภาพถ่ายที่ระบุชื่อ (David LaChapelle) การจัดวางหลายตัวแบบในพื้นที่ (ฝูงผึ้งรวมตัวเป็นลูกศรที่มุมซ้ายบน และผึ้งหนึ่งตัวแบบ forced perspective ที่มุมขวาล่าง) ความสมจริงของพร็อพ (รวงผึ้งที่น้ำผึ้งหยดย้อย) สีหน้าตลกแบบเจาะจง (ตาการ์ตูน `o_O`) และอารมณ์ภาพที่ขัดกัน ทั้งหมดต้องอยู่ในภาพเดียวที่กลมกลืนกัน ```text A visually breathtaking, beautifully absurd, single-frame photograph in the hyper-saturated, glossy, surreal-comedy editorial style of David LaChapelle, shot at a sun-dappled backyard apiary at golden hour on an 85mm f/1.4 lens with creamy shallow depth of field. In the center midground, a gorgeous, radiant young woman beekeeper with an elegant figure, flawless glowing sun-kissed skin and a warm playful smile, incongruously wearing a tiny mini bikini and a beekeeper's veil hat pushed back off her face, stands among the wooden hive boxes on the grass and lifts a single open beehive frame heavy with golden honeycomb, thick honey oozing and stringing down in glossy ribbons and catching the light. She looks directly into the camera, delighted and completely unbothered by the bees swirling around her. In the top-left of the frame, a dense swarm of bees bunches together and organizes into a bold, unmistakable arrow / pointer shape aimed straight at her, as if frantically calling everyone's attention. In the extreme bottom-right foreground of the exact same scene, photobombing the lens, is a huge forced-perspective close-up of a single frazzled worker bee, staring directly into the camera with bulging, mind-blown "o_O" cartoon googly eyes, completely frozen in comical disbelief. Single cohesive image, seamless depth of field, no cut-ins, warm dynamic backlighting, glistening honey highlights, crazy situational comedy, hyper-detailed, masterpiece. ``` ### สร้างภาพด้วยทั้งสามโมเดล คุณต้องมี [API token](/docs/start-here/setup-useapi) ของ useapi.net และ[บัญชี Google Flow](/docs/start-here/setup-google-flow) ที่เชื่อมต่อแล้ว `POST /images` เป็นแบบซิงโครนัส การเรียกครั้งเดียวจะรอจนภาพเสร็จ (ปกติ 20–60 วินาที และโมเดล Pro อาจใช้ถึงราว 2 นาทีเมื่อโหลดสูง) แล้วส่งอาร์เรย์ `media[]` กลับมา ภาพละหนึ่งรายการ จึงไม่มี `jobid` ที่ต้องโพล เรียกครั้งเดียว เปลี่ยน `model` เพื่อเปรียบเทียบ: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/images" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model": "nano-banana-pro", "aspectRatio": "9:16", "count": 4, "prompt": "A beekeeper at golden hour lifting a dripping honeycomb frame, a swarm forming an arrow in the sky, a forced-perspective bee with o_O googly eyes in the foreground" }' > result.json # แต่ละภาพอยู่ที่ .media[N].image.generatedImage.fifeUrl curl -o pro_1.jpg "$(jq -r '.media[0].image.generatedImage.fifeUrl' result.json)" ``` ถ้าต้องการรันการเปรียบเทียบทั้งหมดด้วยคำสั่งเดียว สคริปต์ Node.js ด้านล่างจะอ่าน `prompts.json` (โมเดลละหนึ่งรายการ ทุกรายการใช้พรอมต์เดียวกัน) ส่งทีละรายการ และบันทึกทุกภาพที่ได้กลับมาด้วยชื่อไฟล์ที่ระบุชื่อโมเดล โดยดาวน์โหลดจาก `fifeUrl` หรือถอดรหัส `encodedImage` ที่แนบมาในการตอบกลับเมื่อไม่มี URL ภาพที่ล้มเหลวจะถูกบันทึกลง log แล้วสคริปต์ทำงานต่อ คุณต้องมี [Node.js](https://nodejs.org) v21 ขึ้นไป วางทั้งสองไฟล์ไว้ในโฟลเดอร์เดียวกัน แล้วรัน `node ./google-flow-nano-banana-compare.mjs API_TOKEN EMAIL` โดย `API_TOKEN` คือ [API token](/docs/start-here/setup-useapi) ของ useapi.net และ `EMAIL` คือ[บัญชี Google Flow](/docs/start-here/setup-google-flow) ที่เชื่อมต่อแล้ว สคริปต์จะค้นหาบัญชีจากอีเมล ตรวจ `health` ก่อนส่ง และไม่ส่ง `captchaToken` เพราะ worker ของ useapi.net แก้ reCAPTCHA ให้อัตโนมัติ อยาก clone ไปรันเองหรือเปล่า สคริปต์ฉบับเต็ม เวอร์ชัน Python และ `prompts.json` อยู่บน GitHub ที่ [`useapi/google-flow-api`](https://github.com/useapi/google-flow-api/tree/main/nano-banana-compare) <details markdown="block"> <summary>ขยาย `prompts.json`</summary> ```json [ { "model": "nano-banana-2-lite", "aspectRatio": "9:16", "count": 4, "prompt": "A beekeeper at golden hour lifting a dripping honeycomb frame in the surreal editorial style of David LaChapelle, a dense bee swarm forming a bold arrow in the top-left, a forced-perspective bee with o_O cartoon googly eyes photobombing the bottom-right. Single cohesive image, masterpiece." }, { "model": "nano-banana-2", "aspectRatio": "9:16", "count": 4, "prompt": "A beekeeper at golden hour lifting a dripping honeycomb frame in the surreal editorial style of David LaChapelle, a dense bee swarm forming a bold arrow in the top-left, a forced-perspective bee with o_O cartoon googly eyes photobombing the bottom-right. Single cohesive image, masterpiece." }, { "model": "nano-banana-pro", "aspectRatio": "9:16", "count": 4, "prompt": "A beekeeper at golden hour lifting a dripping honeycomb frame in the surreal editorial style of David LaChapelle, a dense bee swarm forming a bold arrow in the top-left, a forced-perspective bee with o_O cartoon googly eyes photobombing the bottom-right. Single cohesive image, masterpiece." } ] ``` </details> <details markdown="block"> <summary>ขยายสคริปต์ `google-flow-nano-banana-compare.mjs`</summary> ```javascript /* Script version 1.1, September 11, 2026 Batch-compare Google Flow's Nano Banana image models (2 Lite, 2.1, Pro) with the useapi.net API 🚀 Reads prompts.json (one entry per model), submits each to the synchronous POST /images endpoint, and downloads every returned image with a model-labeled filename. For more details visit https://useapi.net/docs/api-google-flow-v1/post-google-flow-images Companion tutorial: https://useapi.net/docs/articles/google-flow-nano-banana-compare Installation Instructions: ========================== You need Node.js v21 or newer installed to run this script. Download and install Node.js from: - Windows, macOS, Linux: https://nodejs.org/ After installation, verify by running the following command in a terminal: node -v Running the Script: =================== Usage: node google-flow-nano-banana-compare.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE] Replace API_TOKEN with your actual useapi.net API token, see https://useapi.net/docs/start-here/setup-useapi Replace EMAIL with configured Google Flow email account, see https://useapi.net/docs/start-here/setup-google-flow If optional PROMPTS_FILE not provided prompts.json will be used. Example: -------- node google-flow-nano-banana-compare.mjs user:1234-abcdefhijklmnopqrstuv my@email.com Changelog: ========== - July 2, 2026: Initial release. - September 11, 2026: Saves encodedImage when fifeUrl is absent, and writes a downloaded image only once it has been fully received, so a failed download leaves no partial file for the next run to skip as "already exists". */ import fs from 'fs/promises'; import { writeFile } from 'node:fs/promises'; // Constants const DEFAULT_PROMPTS_FILE = 'prompts.json'; const DEFAULT_MODEL = 'nano-banana-2-lite'; const SLEEP_RETRY = 30 * 1000; // in milliseconds const urlAccounts = 'https://api.useapi.net/v1/google-flow/accounts'; const urlImages = 'https://api.useapi.net/v1/google-flow/images'; // Utility to sleep for given milliseconds const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); const elapsedTimeSec = (start) => (Date.now() - start) / 1000; // Function to fetch configured Google Flow API accounts async function fetchAccounts(apiToken) { const response = await fetch(urlAccounts, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.error(`⛔ Error fetching accounts (HTTP ${response.status}): ${response.statusText}`); process.exit(1); } return response.json(); } // Save a single image from its signed fifeUrl. fifeUrl is normally present; when it is absent // the image arrived inline as base64 in encodedImage. A failure is reported and skipped. async function downloadImage(img, filename) { try { await fs.access(filename); console.log(`⚠️ ${filename} already exists. Skipping download.`); return; } catch { // File does not exist, proceed with downloading } const url = img?.fifeUrl; if (!url && img?.encodedImage) { console.log(`✅ Saving ${filename} from encodedImage`); try { await writeFile(filename, Buffer.from(img.encodedImage, 'base64')); } catch (err) { console.error(`⛔ Unable to save ${filename}: ${err}`); } return; } if (!url) { console.error(`🛑 No fifeUrl or encodedImage for ${filename}`); return; } console.log(`✅ Downloading ${filename}`); try { const imageResponse = await fetch(url); if (!imageResponse.ok) { console.error(`⛔ Unable to download ${filename} (HTTP ${imageResponse.status})`); return; } // Read the whole body before creating the file, so a failed download leaves no // partial file behind for the next run to skip as "already exists". const data = Buffer.from(await imageResponse.arrayBuffer()); await writeFile(filename, data); } catch (err) { console.error(`⛔ Error during download: ${err}`); } } // Submit a single prompt to the synchronous POST /images endpoint and download the results. async function submitImage(apiToken, email, prompt, index) { const model = prompt.model ?? DEFAULT_MODEL; // Build the request body. const body = { model, email, prompt: prompt.prompt }; for (const key of ['aspectRatio', 'count', 'seed']) if (prompt[key] !== undefined) body[key] = prompt[key]; console.log(`🚀 ${model} » Prompt #${index} • account ${email} …`); const startTime = Date.now(); while (true) { const response = await fetch(urlImages, { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiToken}` }, body: JSON.stringify(body) }); const responseText = await response.text(); if (response.status == 200) { const media = JSON.parse(responseText)?.media ?? []; if (media.length == 0) console.error(`🛑 200 OK but no media (moderated?) for ${model}`); // count > 1 returns multiple images in the media array. for (let i = 0; i < media.length; i++) { const img = media[i]?.image?.generatedImage; await downloadImage(img, `${model}_${i + 1}.jpg`); } console.log(`🆗 ${model} done (${elapsedTimeSec(startTime)} sec)`); return 200; } switch (response.status) { case 429: case 503: console.log(`🔄️ Retry on HTTP ${response.status}`, responseText); await sleep(SLEEP_RETRY); break; default: console.error(`🛑 ${model} failed with HTTP ${response.status}`, responseText); return response.status; } } } // Main function async function main() { const apiToken = process.argv[2]; const email = process.argv[3]; const promptFile = process.argv[4] || DEFAULT_PROMPTS_FILE; if (!apiToken || !email) { console.error('Usage: node google-flow-nano-banana-compare.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE]'); process.exit(1); } console.info('Script v1.1 • Node version ' + process.version); const accounts = await fetchAccounts(apiToken); if (!accounts[email]) { console.error(`⛔ Account ${email} not found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (accounts[email].health && accounts[email].health !== 'OK') { console.error(`⛔ Account ${email} health is '${accounts[email].health}'. Please resolve and update the account, see https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } const prompts = JSON.parse(await fs.readFile(promptFile, 'utf8')); console.log(`Comparing ${prompts.length} model runs …`); const start = new Date(); for (let i = 0; i < prompts.length; i++) await submitImage(apiToken, email, prompts[i], i + 1); console.info('COMPLETED', new Date(), '• elapsed', elapsedTimeSec(start), 'sec'); } main(); ``` </details> ### ตัวอย่าง นี่คือพรอมต์คนเลี้ยงผึ้งเดียวกันที่แต่ละโมเดลสร้างในอัตราส่วน 9:16 ผ่าน Google Flow API นี้ ความต่างออกมาสม่ำเสมอ Pro เนี้ยบที่สุดและทำตามคำสั่งตรงที่สุด 2.1 มีชีวิตชีวาที่สุด ส่วน Lite เร็วที่สุดและผลลัพธ์ก็ใกล้เคียงกัน `nano-banana-pro` เนี้ยบที่สุดและให้อารมณ์ภาพนิตยสารมากที่สุด และเป็นโมเดลเดียวที่วาดตาข่ายของหมวกคลุมหน้า ผึ้งที่ไต่อยู่บนรวง และตาการ์ตูน `o_O` ตามตัวอักษรได้อย่างสม่ำเสมอ <img src="https://media.useapi.net/articles/2026-07-02-google-flow-nano-banana-compare/nano-banana-pro.jpg" style="width: 100%; max-width: 420px;" alt="ภาพคนเลี้ยงผึ้งจาก Nano Banana Pro ผ่าน Google Flow API" /> `nano-banana-2` ตีความได้มีชีวิตชีวาและมีพลังที่สุด ฝูงผึ้งรูปลูกศรชัดที่สุด และมีรายละเอียดของสถานการณ์มากมาย (รองเท้าบูตทำงาน ผึ้งบนคอนรวง) <img src="https://media.useapi.net/articles/2026-07-02-google-flow-nano-banana-compare/nano-banana-2.jpg" style="width: 100%; max-width: 420px;" alt="ภาพคนเลี้ยงผึ้งจาก nano-banana-2 ผ่าน Google Flow API" /> `nano-banana-2-lite` เร็วที่สุดในสามตัว (ใช้เวลาราวครึ่งหนึ่งของ Pro ในการทดสอบของเรา) โดยยังคงองค์ประกอบภาพ น้ำผึ้งที่หยดย้อย และผึ้งตาโปนที่อยู่ด้านหน้า <img src="https://media.useapi.net/articles/2026-06-15-google-flow-images-bash/nano-banana-2-lite.jpg" style="width: 100%; max-width: 420px;" alt="ภาพคนเลี้ยงผึ้งจาก Nano Banana 2 Lite ผ่าน Google Flow API" /> ### ควรใช้โมเดล Nano Banana ตัวไหน? - ใช้ `nano-banana-pro` เมื่อความสมจริงสำคัญที่สุด เช่น ภาพหลัก ฉากซับซ้อนที่มีหลายตัวแบบ ข้อความที่ต้องแม่นยำ หรือการทำตามคำสั่ง ตัวนี้ช้าที่สุดในสามตัว - ใช้ `nano-banana-2` เมื่ออยากได้ความสมดุลที่ดีระหว่างคุณภาพกับความเร็ว หรืออยากได้การตีความพรอมต์ที่มีชีวิตชีวาและมีสไตล์มากขึ้น - ใช้ `nano-banana-2-lite` (ค่าเริ่มต้น) สำหรับการลองซ้ำหลายรอบและการสร้างเป็นชุดใหญ่ เมื่อความเร็วสำคัญและคุณภาพยังใกล้เคียงมาก เพราะทั้งสามใช้คำขอรูปแบบเดียวกัน การสลับโมเดลจึงแค่เปลี่ยนคำเดียวใน `model` สร้างภาพชุดหนึ่งด้วยทั้งสามโมเดลแล้วเลือกภาพที่ดีที่สุด เหมือนที่สคริปต์ด้านบนทำ ### ลองรันเอง สคริปต์ Node.js ฉบับเต็ม เวอร์ชัน Python และ `prompts.json` อยู่ที่ [`useapi/google-flow-api/nano-banana-compare`](https://github.com/useapi/google-flow-api/tree/main/nano-banana-compare) clone ไป แก้ `prompts.json` แล้วรันคำสั่งเดียวเพื่อสร้างภาพเปรียบเทียบทั้งชุดด้วยบัญชี Google Flow ของคุณ ### คำถามที่พบบ่อย - **มี API ของ Nano Banana 2.1 หรือ Nano Banana Pro ไหม?** ผ่าน useapi.net มี [Google Flow API](/docs/api-google-flow-v1) รันเวอร์ชันของ Google Flow ในชื่อ `nano-banana-2` (Nano Banana 2.1), `nano-banana-2-lite` และ `nano-banana-pro` บน [POST /images](/docs/api-google-flow-v1/post-google-flow-images) บน [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) ทางการ Nano Banana 2.1 ราคาราว $0.034 ต่อภาพ 1K และ Nano Banana Pro $0.134 ต่อภาพ ขณะที่ที่นี่ไม่มีค่าบริการต่อภาพ (ข้อมูล ณ พฤศจิกายน 2026) - **Nano Banana 2 Lite, 2.1 และ Pro ต่างกันอย่างไร?** ผ่าน useapi.net ทั้งสามโมเดลใช้ endpoint เดียวกัน และแต่ละตัวมีจุดเด่นของตัวเอง `nano-banana-pro` (Gemini 3 Pro Image) เนี้ยบที่สุดและทำตามคำสั่งตรงที่สุด `nano-banana-2` (Nano Banana 2.1) ตีความได้มีชีวิตชีวาที่สุด และ `nano-banana-2-lite` (Gemini 3.1 Flash-Lite Image) ซึ่งเป็นค่าเริ่มต้น ใช้เวลาราวครึ่งหนึ่งของ Pro ในการทดสอบของเรา ดู[ควรใช้โมเดลตัวไหน?](#which-nano-banana-model-should-you-use) - **API ของ Nano Banana ราคาเท่าไร?** ผ่าน useapi.net การสร้างภาพไม่ใช้เครดิต Flow ในทุกแพ็กเกจ Google AI รวมถึงบัญชีฟรี และไม่ต้องตั้งค่า Gemini API key หรือบัญชีเรียกเก็บเงินของ Cloud บน [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) ทางการ Nano Banana 2 Lite ราคาราว $0.034 ต่อภาพ 1K (ข้อมูล ณ พฤศจิกายน 2026) ดู[ราคา](#pricing) - **ภาพถูกตรวจสอบเนื้อหาไหม?** ผ่าน useapi.net พรอมต์ของคุณยังผ่านระบบตรวจสอบเนื้อหาของ Google เอง และคำขอที่ถูกปฏิเสธจะได้ผลลัพธ์ว่างกลับมา ผลการตรวจสอบต่างกันไปในแต่ละคำขอและแต่ละโมเดล การลองใหม่ แก้พรอมต์ หรือเปลี่ยนโมเดลจึงมักได้ผล เพราะโมเดล Nano Banana แต่ละตัวตรวจสอบเนื้อหาต่างกันเล็กน้อย - **ต้องใช้ captcha หรือโปรเจกต์ Google Cloud ไหม?** ผ่าน useapi.net คุณไม่ต้องมีโปรเจกต์ Google Cloud และไม่ต้องแก้ captcha เอง Google Flow ขอ reCAPTCHA ทุกครั้งที่สร้างภาพ และ worker ของ useapi.net จะแก้ให้อัตโนมัติ บัญชี Google Flow แรกของคุณได้สิทธิ์แก้ฟรี 300 ครั้งด้วยคีย์ AntiCaptcha, CapSolver และ EzCaptcha ของเราเอง หลังจากนั้นคุณเพิ่มคีย์ของผู้ให้บริการของคุณเองได้ สคริปต์ในคู่มือนี้ไม่ได้ส่ง `captchaToken` ### สรุป ติดต่อเราได้ที่ <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> หรือ <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> สำหรับทุกคำถามและข้อสงสัยด้านการใช้งาน ดูตัวอย่างโค้ดได้ใน [GitHub repo](https://github.com/useapi/google-flow-api) ของเรา #### เผยแพร่ที่อื่นด้วย {: .no_toc #cross-posted } เผยแพร่บน [dev.to](https://dev.to/useapi/nano-banana-2-lite-vs-2-vs-pro-google-flow-image-models-compared-3b15){:rel="nofollow"} (ภาษาอังกฤษ) และมีการพูดคุยบน [Reddit](https://www.reddit.com/r/ThirdPartyAPI/comments/1ulw4zo/nano_banana_2_lite_vs_2_vs_pro_google_flow_image/){:rel="nofollow"} (ภาษาอังกฤษ) ด้วย ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-flow-nano-banana-compare-vi === Document URL: https://useapi.net/docs/articles/google-flow-nano-banana-compare-vi --- layout: default title: "Nano Banana 2 Lite vs 2.1 vs Pro: so sánh các model tạo ảnh của Google Flow" description: "So sánh ba model tạo ảnh Nano Banana của Google Flow (2 Lite, 2.1 và Pro) trên cùng một prompt qua API của useapi.net, kèm script chạy được và ví dụ thực tế." keywords: [Nano Banana 2 Lite, Nano Banana 2.1, Nano Banana 2, Nano Banana Pro, Gemini 3 Pro Image, Gemini 3.1 Flash Image, Gemini 3.1 Flash-Lite Image, nano-banana-2-lite, Nano Banana API, Nano Banana Pro API, image model comparison, Google Flow API, API Nano Banana, so sánh Nano Banana, so sánh model tạo ảnh, tạo ảnh AI bằng API, API tạo ảnh, hướng dẫn, code] image: https://media.useapi.net/articles/2026-07-02-google-flow-nano-banana-compare/nano-banana-pro.jpg parent: Articles nav_exclude: true lang: vi translation_key: nano-banana-compare date: 2026-07-02 last_modified: 2026-11-06 nav_order: 830 repo: https://github.com/useapi/google-flow-api --- ## Nano Banana 2 Lite vs 2.1 vs Pro: so sánh các model tạo ảnh của Google Flow {: .no_toc #nano-banana-2-lite-vs-21-vs-pro-google-flow-image-models-compared } 7 phút đọc • 2 tháng 7 năm 2026 (6 tháng 11 năm 2026) useapi.net là API của bên thứ ba, không liên kết với Google và không được Google bảo trợ. ## Mục lục {: .no_toc .text-delta #table-of-contents } ### Giới thiệu Google Flow có ba model tạo ảnh Nano Banana là `nano-banana-2-lite`, `nano-banana-2` và `nano-banana-pro`, và [Google Flow API](/docs/api-google-flow-v1) của useapi.net chạy cả ba từ cùng một prompt bằng tài khoản [Google Flow](https://flow.google.com) của bạn. Việc tạo ảnh có sẵn trong mọi [gói Google AI](https://gemini.google/subscriptions/), kể cả tài khoản miễn phí, trong khi Gemini API chính thức tính từ $0,034 đến $0,134 mỗi ảnh (tính đến tháng 11/2026). Không cần dự án Google Cloud, không cần API key. Hướng dẫn này chạy đúng cùng một prompt trên Lite, 2.1 và Pro để bạn thấy chúng khác nhau thế nào, rồi đưa bạn một script Node.js tạo toàn bộ bộ ảnh chỉ bằng một lệnh. Muốn bắt đầu từ đầu trước? Xem [hướng dẫn tạo ảnh](/docs/articles/google-flow-images-bash-vi), bài cùng loạt với bài này. ### Ba model Nano Banana là gì? Chọn model cho từng request bằng trường `model`. Nếu bỏ trống, Google Flow dùng `nano-banana-2-lite`, model mặc định của nó từ tháng 7/2026. Cả ba đều chạy trên mọi gói Google AI, kể cả tài khoản miễn phí. | ID model | Tên thương mại | Phù hợp nhất cho | Ảnh tham chiếu (I2I) | Tốc độ | |----------|----------------|----------|-----------------:|-------| | `nano-banana-2-lite` *(mặc định)* | [Nano Banana 2 Lite](https://deepmind.google/models/gemini-image/flash-lite/) / Gemini 3.1 Flash-Lite Image | tạo ảnh nhanh, số lượng lớn, trên mọi gói | tối đa 10 | nhanh nhất | | `nano-banana-2` | Nano Banana 2.1 | cân bằng chất lượng và tốc độ | tối đa 10 | nhanh | | `nano-banana-pro` | [Nano Banana Pro](https://deepmind.google/models/gemini-image/pro/) / Gemini 3 Pro Image | độ trung thực và bám sát chỉ dẫn cao nhất | tối đa 10 | chậm hơn | Cả ba nhận cùng các tỷ lệ khung hình (`16:9`, `4:3`, `1:1`, `3:4`, `9:16`, thêm `auto` ở chế độ ảnh sang ảnh), `count` (1–4), `seed` để tái tạo kết quả, tối đa 10 ảnh tham chiếu, `@`-mention ngay trong prompt và [upscale lên 2K/4K](#upscaling-to-2k4k). Các alias đã ngừng dùng `imagen-4` (Google đã gỡ Imagen khỏi Google Flow vào tháng 7/2026) và `nano-banana` vẫn được chấp nhận, lần lượt tương ứng với `nano-banana-2-lite` và `nano-banana-2`. Chi tiết đầy đủ của từng model có trong tài liệu [POST /images](/docs/api-google-flow-v1/post-google-flow-images). #### Upscale lên 2K/4K Ảnh nào đã tạo cũng upscale được bằng [POST /images/upscale](/docs/api-google-flow-v1/post-google-flow-images-upscale): truyền `mediaGenerationId` của ảnh và `resolution` là `2k` (mặc định) hoặc `4k`. Phản hồi là base64 trong `encodedImage`. `2k` dùng được trên mọi gói, còn `4k` cần Google AI Ultra. ### Giá Ảnh không tốn credit Flow trên bất kỳ gói Google AI nào, kể cả tài khoản miễn phí, và useapi.net không thu phí theo ảnh. Giá của mọi model trên mọi gói, so với API chính thức, có trong [bảng giá Google Flow](/docs/api-google-flow-v1#pricing). Xem [hướng dẫn thiết lập](/docs/start-here/setup-google-flow) để kết nối tài khoản. ### Prompt dùng để so sánh So sánh model chỉ có ích khi prompt đủ khó. Prompt này cố tình là một cảnh phi lý trong một khung hình duy nhất, thử nhiều thứ cùng lúc: một phong cách nhiếp ảnh có tên (David LaChapelle), bố cục không gian nhiều chủ thể (một đàn ong xếp thành mũi tên ở góc trên bên trái, một con ong phối cảnh cưỡng bức ở góc dưới bên phải), độ chính xác của đạo cụ (khung sáp ong nhỏ giọt mật), một biểu cảm hài cụ thể (mắt hoạt hình `o_O`) và một tông màu trái ngược, tất cả trong một bức ảnh liền mạch. ```text A visually breathtaking, beautifully absurd, single-frame photograph in the hyper-saturated, glossy, surreal-comedy editorial style of David LaChapelle, shot at a sun-dappled backyard apiary at golden hour on an 85mm f/1.4 lens with creamy shallow depth of field. In the center midground, a gorgeous, radiant young woman beekeeper with an elegant figure, flawless glowing sun-kissed skin and a warm playful smile, incongruously wearing a tiny mini bikini and a beekeeper's veil hat pushed back off her face, stands among the wooden hive boxes on the grass and lifts a single open beehive frame heavy with golden honeycomb, thick honey oozing and stringing down in glossy ribbons and catching the light. She looks directly into the camera, delighted and completely unbothered by the bees swirling around her. In the top-left of the frame, a dense swarm of bees bunches together and organizes into a bold, unmistakable arrow / pointer shape aimed straight at her, as if frantically calling everyone's attention. In the extreme bottom-right foreground of the exact same scene, photobombing the lens, is a huge forced-perspective close-up of a single frazzled worker bee, staring directly into the camera with bulging, mind-blown "o_O" cartoon googly eyes, completely frozen in comical disbelief. Single cohesive image, seamless depth of field, no cut-ins, warm dynamic backlighting, glistening honey highlights, crazy situational comedy, hyper-detailed, masterpiece. ``` ### Tạo ảnh với cả ba model Bạn cần một [API token](/docs/start-here/setup-useapi) của useapi.net và một [tài khoản Google Flow](/docs/start-here/setup-google-flow) đã kết nối. `POST /images` là đồng bộ: một lệnh gọi sẽ chờ đến khi ảnh xong (thường 20–60 giây, model Pro có thể mất khoảng 2 phút khi tải cao) và trả về mảng `media[]` với mỗi ảnh một phần tử, nên không có `jobid` nào phải poll. Một lệnh gọi duy nhất, đổi `model` để so sánh: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/images" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model": "nano-banana-pro", "aspectRatio": "9:16", "count": 4, "prompt": "A beekeeper at golden hour lifting a dripping honeycomb frame, a swarm forming an arrow in the sky, a forced-perspective bee with o_O googly eyes in the foreground" }' > result.json # mỗi ảnh nằm ở .media[N].image.generatedImage.fifeUrl curl -o pro_1.jpg "$(jq -r '.media[0].image.generatedImage.fifeUrl' result.json)" ``` Để chạy toàn bộ phần so sánh bằng một lệnh, script Node.js bên dưới đọc `prompts.json` (mỗi model một mục, tất cả cùng một prompt), gửi từng mục và lưu mọi ảnh trả về với tên file có tên model, tải từ `fifeUrl` hoặc giải mã `encodedImage` có sẵn trong phản hồi khi thiếu URL. Ảnh nào lỗi sẽ được ghi log và script chạy tiếp. Bạn cần [Node.js](https://nodejs.org) v21 trở lên. Đặt cả hai file vào một thư mục và chạy `node ./google-flow-nano-banana-compare.mjs API_TOKEN EMAIL`, trong đó `API_TOKEN` là [API token](/docs/start-here/setup-useapi) useapi.net của bạn và `EMAIL` là [tài khoản Google Flow](/docs/start-here/setup-google-flow) đã kết nối. Script tìm tài khoản theo email, kiểm tra `health` của nó trước khi gửi, và không gửi `captchaToken`: worker của useapi.net tự động giải reCAPTCHA. Muốn clone về chạy? Script đầy đủ, bản Python và `prompts.json` có trên GitHub tại [`useapi/google-flow-api`](https://github.com/useapi/google-flow-api/tree/main/nano-banana-compare). <details markdown="block"> <summary>Mở `prompts.json`</summary> ```json [ { "model": "nano-banana-2-lite", "aspectRatio": "9:16", "count": 4, "prompt": "A beekeeper at golden hour lifting a dripping honeycomb frame in the surreal editorial style of David LaChapelle, a dense bee swarm forming a bold arrow in the top-left, a forced-perspective bee with o_O cartoon googly eyes photobombing the bottom-right. Single cohesive image, masterpiece." }, { "model": "nano-banana-2", "aspectRatio": "9:16", "count": 4, "prompt": "A beekeeper at golden hour lifting a dripping honeycomb frame in the surreal editorial style of David LaChapelle, a dense bee swarm forming a bold arrow in the top-left, a forced-perspective bee with o_O cartoon googly eyes photobombing the bottom-right. Single cohesive image, masterpiece." }, { "model": "nano-banana-pro", "aspectRatio": "9:16", "count": 4, "prompt": "A beekeeper at golden hour lifting a dripping honeycomb frame in the surreal editorial style of David LaChapelle, a dense bee swarm forming a bold arrow in the top-left, a forced-perspective bee with o_O cartoon googly eyes photobombing the bottom-right. Single cohesive image, masterpiece." } ] ``` </details> <details markdown="block"> <summary>Mở script `google-flow-nano-banana-compare.mjs`</summary> ```javascript /* Script version 1.1, September 11, 2026 Batch-compare Google Flow's Nano Banana image models (2 Lite, 2.1, Pro) with the useapi.net API 🚀 Reads prompts.json (one entry per model), submits each to the synchronous POST /images endpoint, and downloads every returned image with a model-labeled filename. For more details visit https://useapi.net/docs/api-google-flow-v1/post-google-flow-images Companion tutorial: https://useapi.net/docs/articles/google-flow-nano-banana-compare Installation Instructions: ========================== You need Node.js v21 or newer installed to run this script. Download and install Node.js from: - Windows, macOS, Linux: https://nodejs.org/ After installation, verify by running the following command in a terminal: node -v Running the Script: =================== Usage: node google-flow-nano-banana-compare.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE] Replace API_TOKEN with your actual useapi.net API token, see https://useapi.net/docs/start-here/setup-useapi Replace EMAIL with configured Google Flow email account, see https://useapi.net/docs/start-here/setup-google-flow If optional PROMPTS_FILE not provided prompts.json will be used. Example: -------- node google-flow-nano-banana-compare.mjs user:1234-abcdefhijklmnopqrstuv my@email.com Changelog: ========== - July 2, 2026: Initial release. - September 11, 2026: Saves encodedImage when fifeUrl is absent, and writes a downloaded image only once it has been fully received, so a failed download leaves no partial file for the next run to skip as "already exists". */ import fs from 'fs/promises'; import { writeFile } from 'node:fs/promises'; // Constants const DEFAULT_PROMPTS_FILE = 'prompts.json'; const DEFAULT_MODEL = 'nano-banana-2-lite'; const SLEEP_RETRY = 30 * 1000; // in milliseconds const urlAccounts = 'https://api.useapi.net/v1/google-flow/accounts'; const urlImages = 'https://api.useapi.net/v1/google-flow/images'; // Utility to sleep for given milliseconds const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); const elapsedTimeSec = (start) => (Date.now() - start) / 1000; // Function to fetch configured Google Flow API accounts async function fetchAccounts(apiToken) { const response = await fetch(urlAccounts, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.error(`⛔ Error fetching accounts (HTTP ${response.status}): ${response.statusText}`); process.exit(1); } return response.json(); } // Save a single image from its signed fifeUrl. fifeUrl is normally present; when it is absent // the image arrived inline as base64 in encodedImage. A failure is reported and skipped. async function downloadImage(img, filename) { try { await fs.access(filename); console.log(`⚠️ ${filename} already exists. Skipping download.`); return; } catch { // File does not exist, proceed with downloading } const url = img?.fifeUrl; if (!url && img?.encodedImage) { console.log(`✅ Saving ${filename} from encodedImage`); try { await writeFile(filename, Buffer.from(img.encodedImage, 'base64')); } catch (err) { console.error(`⛔ Unable to save ${filename}: ${err}`); } return; } if (!url) { console.error(`🛑 No fifeUrl or encodedImage for ${filename}`); return; } console.log(`✅ Downloading ${filename}`); try { const imageResponse = await fetch(url); if (!imageResponse.ok) { console.error(`⛔ Unable to download ${filename} (HTTP ${imageResponse.status})`); return; } // Read the whole body before creating the file, so a failed download leaves no // partial file behind for the next run to skip as "already exists". const data = Buffer.from(await imageResponse.arrayBuffer()); await writeFile(filename, data); } catch (err) { console.error(`⛔ Error during download: ${err}`); } } // Submit a single prompt to the synchronous POST /images endpoint and download the results. async function submitImage(apiToken, email, prompt, index) { const model = prompt.model ?? DEFAULT_MODEL; // Build the request body. const body = { model, email, prompt: prompt.prompt }; for (const key of ['aspectRatio', 'count', 'seed']) if (prompt[key] !== undefined) body[key] = prompt[key]; console.log(`🚀 ${model} » Prompt #${index} • account ${email} …`); const startTime = Date.now(); while (true) { const response = await fetch(urlImages, { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiToken}` }, body: JSON.stringify(body) }); const responseText = await response.text(); if (response.status == 200) { const media = JSON.parse(responseText)?.media ?? []; if (media.length == 0) console.error(`🛑 200 OK but no media (moderated?) for ${model}`); // count > 1 returns multiple images in the media array. for (let i = 0; i < media.length; i++) { const img = media[i]?.image?.generatedImage; await downloadImage(img, `${model}_${i + 1}.jpg`); } console.log(`🆗 ${model} done (${elapsedTimeSec(startTime)} sec)`); return 200; } switch (response.status) { case 429: case 503: console.log(`🔄️ Retry on HTTP ${response.status}`, responseText); await sleep(SLEEP_RETRY); break; default: console.error(`🛑 ${model} failed with HTTP ${response.status}`, responseText); return response.status; } } } // Main function async function main() { const apiToken = process.argv[2]; const email = process.argv[3]; const promptFile = process.argv[4] || DEFAULT_PROMPTS_FILE; if (!apiToken || !email) { console.error('Usage: node google-flow-nano-banana-compare.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE]'); process.exit(1); } console.info('Script v1.1 • Node version ' + process.version); const accounts = await fetchAccounts(apiToken); if (!accounts[email]) { console.error(`⛔ Account ${email} not found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (accounts[email].health && accounts[email].health !== 'OK') { console.error(`⛔ Account ${email} health is '${accounts[email].health}'. Please resolve and update the account, see https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } const prompts = JSON.parse(await fs.readFile(promptFile, 'utf8')); console.log(`Comparing ${prompts.length} model runs …`); const start = new Date(); for (let i = 0; i < prompts.length; i++) await submitImage(apiToken, email, prompts[i], i + 1); console.info('COMPLETED', new Date(), '• elapsed', elapsedTimeSec(start), 'sec'); } main(); ``` </details> ### Ví dụ Đây là cùng một prompt người nuôi ong do từng model tạo ở tỷ lệ 9:16, qua chính Google Flow API này. Khác biệt lặp lại đều đặn: Pro trau chuốt nhất và bám chỉ dẫn sát nhất, 2.1 sống động nhất, còn Lite nhanh nhất mà vẫn rất gần. `nano-banana-pro`: trau chuốt và mang chất tạp chí nhất, và là model duy nhất vẽ ổn định lớp lưới mạng che mặt, những con ong bò trên sáp và đúng đôi mắt hoạt hình `o_O`. <img src="https://media.useapi.net/articles/2026-07-02-google-flow-nano-banana-compare/nano-banana-pro.jpg" style="width: 100%; max-width: 420px;" alt="Ảnh người nuôi ong tạo bằng Nano Banana Pro qua Google Flow API" /> `nano-banana-2`: cách diễn giải sống động và giàu năng lượng nhất, với đàn ong hình mũi tên rõ nhất và nhiều chi tiết tình huống (ủng lao động, ong trên khung). <img src="https://media.useapi.net/articles/2026-07-02-google-flow-nano-banana-compare/nano-banana-2.jpg" style="width: 100%; max-width: 420px;" alt="Ảnh người nuôi ong tạo bằng nano-banana-2 qua Google Flow API" /> `nano-banana-2-lite`: nhanh nhất trong ba model (khoảng một nửa thời gian của Pro trong các lần chạy của chúng tôi) mà vẫn giữ bố cục, dòng mật nhỏ giọt và con ong mắt lồi ở tiền cảnh. <img src="https://media.useapi.net/articles/2026-06-15-google-flow-images-bash/nano-banana-2-lite.jpg" style="width: 100%; max-width: 420px;" alt="Ảnh người nuôi ong tạo bằng Nano Banana 2 Lite qua Google Flow API" /> ### Nên dùng model Nano Banana nào? - Chọn `nano-banana-pro` khi độ trung thực quan trọng nhất: ảnh chủ đạo, cảnh phức tạp nhiều chủ thể, chữ chính xác hoặc bám sát chỉ dẫn. Đây là model chậm nhất trong ba. - Chọn `nano-banana-2` để cân bằng tốt giữa chất lượng và tốc độ, hoặc khi bạn muốn prompt được diễn giải sống động, cách điệu hơn. - Chọn `nano-banana-2-lite` (mặc định) để thử nhiều lần và chạy hàng loạt số lượng lớn, khi tốc độ quan trọng mà chất lượng vẫn rất gần. Vì cả ba dùng cùng dạng request, đổi model chỉ là sửa một từ trong `model`: tạo một loạt ảnh trên cả ba rồi chọn ảnh đẹp nhất, đúng như script ở trên làm. ### Tự chạy thử Script Node.js đầy đủ, bản Python và `prompts.json` nằm ở [`useapi/google-flow-api/nano-banana-compare`](https://github.com/useapi/google-flow-api/tree/main/nano-banana-compare). Clone về, sửa `prompts.json` và chạy một lệnh để tạo toàn bộ bộ ảnh so sánh bằng tài khoản Google Flow của bạn. ### Câu hỏi thường gặp - **Có API Nano Banana 2.1 hay Nano Banana Pro không?** Qua useapi.net thì có: [Google Flow API](/docs/api-google-flow-v1) chạy các phiên bản của Google Flow dưới tên `nano-banana-2` (Nano Banana 2.1), `nano-banana-2-lite` và `nano-banana-pro` trên [POST /images](/docs/api-google-flow-v1/post-google-flow-images). Trên [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) chính thức, Nano Banana 2.1 tốn khoảng $0,034 mỗi ảnh 1K và Nano Banana Pro $0,134 mỗi ảnh, còn ở đây không tính phí theo ảnh (tính đến tháng 11/2026). - **Nano Banana 2 Lite, 2.1 và Pro khác nhau thế nào?** Qua useapi.net cả ba chạy trên cùng một endpoint, mỗi model có thế mạnh riêng. `nano-banana-pro` (Gemini 3 Pro Image) trau chuốt nhất và bám chỉ dẫn sát nhất, `nano-banana-2` (Nano Banana 2.1) cho cách diễn giải sống động nhất, còn `nano-banana-2-lite` (Gemini 3.1 Flash-Lite Image), model mặc định, mất khoảng một nửa thời gian của Pro trong các lần chạy của chúng tôi. Xem [Nên dùng model nào?](#which-nano-banana-model-should-you-use) - **API Nano Banana giá bao nhiêu?** Qua useapi.net, ảnh không tốn credit Flow trên bất kỳ gói Google AI nào, kể cả tài khoản miễn phí, và không cần thiết lập Gemini API key hay tài khoản thanh toán Cloud. Trên [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) chính thức, Nano Banana 2 Lite tốn khoảng $0,034 mỗi ảnh 1K (tính đến tháng 11/2026). Xem [Giá](#pricing). - **Ảnh có bị kiểm duyệt không?** Qua useapi.net, prompt của bạn vẫn đi qua bộ kiểm duyệt nội dung của chính Google, và request bị từ chối sẽ trả về kết quả rỗng. Quyết định kiểm duyệt khác nhau giữa các request và giữa các model, nên thử lại, sửa prompt hoặc đổi model thường thành công, vì mỗi model Nano Banana kiểm duyệt hơi khác nhau. - **Có cần captcha hay dự án Google Cloud không?** Với useapi.net, bạn không cần dự án Google Cloud, cũng không cần tự giải captcha. Google Flow yêu cầu reCAPTCHA cho mỗi ảnh, và worker của useapi.net tự động giải: tài khoản Google Flow đầu tiên của bạn được 300 lượt giải miễn phí bằng key AntiCaptcha, CapSolver và EzCaptcha của chính chúng tôi, sau đó bạn thêm key nhà cung cấp của riêng mình. Script trong hướng dẫn này không gửi `captchaToken`. ### Kết luận Hãy ghé <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> hoặc <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> của chúng tôi nếu bạn có câu hỏi hoặc cần hỗ trợ. Xem [repo GitHub](https://github.com/useapi/google-flow-api) của chúng tôi với các ví dụ code. #### Đăng ở nơi khác {: .no_toc #cross-posted } Cũng đăng trên [dev.to](https://dev.to/useapi/nano-banana-2-lite-vs-2-vs-pro-google-flow-image-models-compared-3b15){:rel="nofollow"} (tiếng Anh) và được thảo luận trên [Reddit](https://www.reddit.com/r/ThirdPartyAPI/comments/1ulw4zo/nano_banana_2_lite_vs_2_vs_pro_google_flow_image/){:rel="nofollow"} (tiếng Anh). ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-flow-nano-banana-compare-zh === Document URL: https://useapi.net/docs/articles/google-flow-nano-banana-compare-zh --- layout: default title: "Nano Banana 2 Lite、2.1 与 Pro 对比:Google Flow 三款图片模型横评" description: "通过 useapi.net 的 Google Flow API,用同一个提示词对比 Google Flow 的三款 Nano Banana 图片模型(2 Lite、2.1 和 Pro),附可运行脚本和真实示例。" keywords: [Nano Banana 2 Lite, Nano Banana 2.1, Nano Banana 2, Nano Banana Pro, Gemini 3 Pro Image, Gemini 3.1 Flash Image, Gemini 3.1 Flash-Lite Image, nano-banana-2-lite, Nano Banana API, Nano Banana Pro API, image model comparison, Google Flow API, Nano Banana 对比, Nano Banana Pro API 价格, 图片模型对比, 图片生成 API, AI 生图, 中文教程, Chinese tutorial] image: https://media.useapi.net/articles/2026-07-02-google-flow-nano-banana-compare/nano-banana-pro.jpg parent: Articles nav_exclude: true lang: zh-CN translation_key: nano-banana-compare date: 2026-07-02 last_modified: 2026-11-06 nav_order: 830 repo: https://github.com/useapi/google-flow-api --- ## Nano Banana 2 Lite、2.1 与 Pro 对比:Google Flow 三款图片模型横评 {: .no_toc #nano-banana-2-lite-vs-21-vs-pro-google-flow-image-models-compared } 7 分钟阅读 • 2026 年 7 月 2 日(2026 年 11 月 6 日更新) useapi.net 是第三方 API,与 Google 无关联,也未获得 Google 的认可。 ## 目录 {: .no_toc .text-delta #table-of-contents } ### 简介 Google Flow 提供三款 Nano Banana 图片模型:`nano-banana-2-lite`、`nano-banana-2` 和 `nano-banana-pro`。useapi.net 的 [Google Flow API](/docs/api-google-flow-v1) 用你自己的 [Google Flow](https://flow.google.com) 账号,以同一个提示词运行这三款模型。所有 [Google AI 订阅](https://gemini.google/subscriptions/)都包含图片生成,免费账号也一样,而官方 Gemini API 每张图片收费 $0.034 到 $0.134(截至 2026 年 11 月)。不需要 Google Cloud 项目,也不需要 API Key。 本指南把完全相同的提示词分别交给 Lite、2.1 和 Pro,让你看清它们的差别,然后给出一个可运行的 Node.js 脚本,一条命令生成整套对比图。想先从头学起?请看姊妹篇[图片生成教程](/docs/articles/google-flow-images-bash-zh)。 ### 三款 Nano Banana 模型分别是什么? 每个请求通过 `model` 字段选择模型。省略时,Google Flow 使用 `nano-banana-2-lite`,这是它自 2026 年 7 月起的默认模型。三款模型都能在任何 Google AI 订阅上运行,免费账号也可以。 | 模型 ID | 产品名称 | 适合场景 | 参考图(I2I) | 速度 | |----------|----------------|----------|-----------------:|-------| | `nano-banana-2-lite` *(默认)* | [Nano Banana 2 Lite](https://deepmind.google/models/gemini-image/flash-lite/) / Gemini 3.1 Flash-Lite Image | 任何订阅上快速、大批量出图 | 最多 10 张 | 最快 | | `nano-banana-2` | Nano Banana 2.1 | 画质与速度兼顾 | 最多 10 张 | 快 | | `nano-banana-pro` | [Nano Banana Pro](https://deepmind.google/models/gemini-image/pro/) / Gemini 3 Pro Image | 保真度最高,最能遵循指令 | 最多 10 张 | 较慢 | 三款模型接受相同的宽高比(`16:9`、`4:3`、`1:1`、`3:4`、`9:16`,图生图模式下还有 `auto`)、`count`(1–4)、用于复现结果的 `seed`、最多 10 张参考图、提示词内的 `@` 引用,以及 [2K/4K 放大](#upscaling-to-2k4k)。已弃用的别名 `imagen-4`(Google 已于 2026 年 7 月从 Google Flow 中移除 Imagen)和 `nano-banana` 仍然可用,分别映射到 `nano-banana-2-lite` 和 `nano-banana-2`。每个模型的完整说明见 [POST /images](/docs/api-google-flow-v1/post-google-flow-images) 参考文档。 #### 放大到 2K/4K 任何生成的图片都可以用 [POST /images/upscale](/docs/api-google-flow-v1/post-google-flow-images-upscale) 放大:传入它的 `mediaGenerationId`,并把 `resolution` 设为 `2k`(默认)或 `4k`。响应以 base64 放在 `encodedImage` 中返回。`2k` 适用于任何套餐,`4k` 需要 Google AI Ultra。 ### 价格 在任何 Google AI 订阅上(包括免费账号),图片都不消耗 Flow 积分,useapi.net 也不按图片收费。每个模型在每个套餐上的价格以及与官方 API 的对比,见 [Google Flow 价格表](/docs/api-google-flow-v1#pricing)。连接账号请看[设置指南](/docs/start-here/setup-google-flow)。 ### 对比用的提示词 只有提示词够难,模型对比才有意义。这个提示词刻意设计成一个荒诞的单帧场景,同时考验好几件事:指定的摄影风格(David LaChapelle)、多主体的空间布局(左上角蜂群组成箭头,右下角一只强迫透视的蜜蜂)、道具的还原度(滴着蜜的蜂巢)、特定的喜剧表情(`o_O` 卡通眼)以及相互冲突的基调,而且全部要融在一张连贯的图片里。 ```text A visually breathtaking, beautifully absurd, single-frame photograph in the hyper-saturated, glossy, surreal-comedy editorial style of David LaChapelle, shot at a sun-dappled backyard apiary at golden hour on an 85mm f/1.4 lens with creamy shallow depth of field. In the center midground, a gorgeous, radiant young woman beekeeper with an elegant figure, flawless glowing sun-kissed skin and a warm playful smile, incongruously wearing a tiny mini bikini and a beekeeper's veil hat pushed back off her face, stands among the wooden hive boxes on the grass and lifts a single open beehive frame heavy with golden honeycomb, thick honey oozing and stringing down in glossy ribbons and catching the light. She looks directly into the camera, delighted and completely unbothered by the bees swirling around her. In the top-left of the frame, a dense swarm of bees bunches together and organizes into a bold, unmistakable arrow / pointer shape aimed straight at her, as if frantically calling everyone's attention. In the extreme bottom-right foreground of the exact same scene, photobombing the lens, is a huge forced-perspective close-up of a single frazzled worker bee, staring directly into the camera with bulging, mind-blown "o_O" cartoon googly eyes, completely frozen in comical disbelief. Single cohesive image, seamless depth of field, no cut-ins, warm dynamic backlighting, glistening honey highlights, crazy situational comedy, hyper-detailed, masterpiece. ``` ### 用三款模型分别生成 你需要一个 useapi.net [API Token](/docs/start-here/setup-useapi) 和一个已连接的 [Google Flow 账号](/docs/start-here/setup-google-flow)。`POST /images` 是同步的:一次调用会一直等到图片生成完毕(通常 20–60 秒,负载高时 Pro 模型可能需要约 2 分钟),然后返回 `media[]` 数组,每张图片一项,所以没有需要轮询的 `jobid`。 单次调用,换掉 `model` 即可对比: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/images" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model": "nano-banana-pro", "aspectRatio": "9:16", "count": 4, "prompt": "A beekeeper at golden hour lifting a dripping honeycomb frame, a swarm forming an arrow in the sky, a forced-perspective bee with o_O googly eyes in the foreground" }' > result.json # 每张图片位于 .media[N].image.generatedImage.fifeUrl curl -o pro_1.jpg "$(jq -r '.media[0].image.generatedImage.fifeUrl' result.json)" ``` 要一条命令跑完整个对比,可以用下面的 Node.js 脚本。它读取 `prompts.json`(每个模型一项,提示词都相同),逐个提交,并用带模型名的文件名保存返回的每张图片:从 `fifeUrl` 下载,URL 缺失时则解码内联的 `encodedImage`。某张图片失败时会记录下来,然后继续运行。需要 [Node.js](https://nodejs.org) v21 及以上版本。把两个文件放进同一个文件夹,运行 `node ./google-flow-nano-banana-compare.mjs API_TOKEN EMAIL`,其中 `API_TOKEN` 是你的 useapi.net [API Token](/docs/start-here/setup-useapi),`EMAIL` 是已连接的 [Google Flow 账号](/docs/start-here/setup-google-flow)。脚本会按邮箱查找账号,提交前检查它的 `health`,并且不发送 `captchaToken`:useapi.net 的 worker 会自动解决 reCAPTCHA。 想直接克隆运行?完整脚本、Python 移植版和 `prompts.json` 都在 GitHub 的 [`useapi/google-flow-api`](https://github.com/useapi/google-flow-api/tree/main/nano-banana-compare) 中。 <details markdown="block"> <summary>展开 `prompts.json`</summary> ```json [ { "model": "nano-banana-2-lite", "aspectRatio": "9:16", "count": 4, "prompt": "A beekeeper at golden hour lifting a dripping honeycomb frame in the surreal editorial style of David LaChapelle, a dense bee swarm forming a bold arrow in the top-left, a forced-perspective bee with o_O cartoon googly eyes photobombing the bottom-right. Single cohesive image, masterpiece." }, { "model": "nano-banana-2", "aspectRatio": "9:16", "count": 4, "prompt": "A beekeeper at golden hour lifting a dripping honeycomb frame in the surreal editorial style of David LaChapelle, a dense bee swarm forming a bold arrow in the top-left, a forced-perspective bee with o_O cartoon googly eyes photobombing the bottom-right. Single cohesive image, masterpiece." }, { "model": "nano-banana-pro", "aspectRatio": "9:16", "count": 4, "prompt": "A beekeeper at golden hour lifting a dripping honeycomb frame in the surreal editorial style of David LaChapelle, a dense bee swarm forming a bold arrow in the top-left, a forced-perspective bee with o_O cartoon googly eyes photobombing the bottom-right. Single cohesive image, masterpiece." } ] ``` </details> <details markdown="block"> <summary>展开 `google-flow-nano-banana-compare.mjs` 脚本</summary> ```javascript /* Script version 1.1, September 11, 2026 Batch-compare Google Flow's Nano Banana image models (2 Lite, 2.1, Pro) with the useapi.net API 🚀 Reads prompts.json (one entry per model), submits each to the synchronous POST /images endpoint, and downloads every returned image with a model-labeled filename. For more details visit https://useapi.net/docs/api-google-flow-v1/post-google-flow-images Companion tutorial: https://useapi.net/docs/articles/google-flow-nano-banana-compare Installation Instructions: ========================== You need Node.js v21 or newer installed to run this script. Download and install Node.js from: - Windows, macOS, Linux: https://nodejs.org/ After installation, verify by running the following command in a terminal: node -v Running the Script: =================== Usage: node google-flow-nano-banana-compare.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE] Replace API_TOKEN with your actual useapi.net API token, see https://useapi.net/docs/start-here/setup-useapi Replace EMAIL with configured Google Flow email account, see https://useapi.net/docs/start-here/setup-google-flow If optional PROMPTS_FILE not provided prompts.json will be used. Example: -------- node google-flow-nano-banana-compare.mjs user:1234-abcdefhijklmnopqrstuv my@email.com Changelog: ========== - July 2, 2026: Initial release. - September 11, 2026: Saves encodedImage when fifeUrl is absent, and writes a downloaded image only once it has been fully received, so a failed download leaves no partial file for the next run to skip as "already exists". */ import fs from 'fs/promises'; import { writeFile } from 'node:fs/promises'; // Constants const DEFAULT_PROMPTS_FILE = 'prompts.json'; const DEFAULT_MODEL = 'nano-banana-2-lite'; const SLEEP_RETRY = 30 * 1000; // in milliseconds const urlAccounts = 'https://api.useapi.net/v1/google-flow/accounts'; const urlImages = 'https://api.useapi.net/v1/google-flow/images'; // Utility to sleep for given milliseconds const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); const elapsedTimeSec = (start) => (Date.now() - start) / 1000; // Function to fetch configured Google Flow API accounts async function fetchAccounts(apiToken) { const response = await fetch(urlAccounts, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.error(`⛔ Error fetching accounts (HTTP ${response.status}): ${response.statusText}`); process.exit(1); } return response.json(); } // Save a single image from its signed fifeUrl. fifeUrl is normally present; when it is absent // the image arrived inline as base64 in encodedImage. A failure is reported and skipped. async function downloadImage(img, filename) { try { await fs.access(filename); console.log(`⚠️ ${filename} already exists. Skipping download.`); return; } catch { // File does not exist, proceed with downloading } const url = img?.fifeUrl; if (!url && img?.encodedImage) { console.log(`✅ Saving ${filename} from encodedImage`); try { await writeFile(filename, Buffer.from(img.encodedImage, 'base64')); } catch (err) { console.error(`⛔ Unable to save ${filename}: ${err}`); } return; } if (!url) { console.error(`🛑 No fifeUrl or encodedImage for ${filename}`); return; } console.log(`✅ Downloading ${filename}`); try { const imageResponse = await fetch(url); if (!imageResponse.ok) { console.error(`⛔ Unable to download ${filename} (HTTP ${imageResponse.status})`); return; } // Read the whole body before creating the file, so a failed download leaves no // partial file behind for the next run to skip as "already exists". const data = Buffer.from(await imageResponse.arrayBuffer()); await writeFile(filename, data); } catch (err) { console.error(`⛔ Error during download: ${err}`); } } // Submit a single prompt to the synchronous POST /images endpoint and download the results. async function submitImage(apiToken, email, prompt, index) { const model = prompt.model ?? DEFAULT_MODEL; // Build the request body. const body = { model, email, prompt: prompt.prompt }; for (const key of ['aspectRatio', 'count', 'seed']) if (prompt[key] !== undefined) body[key] = prompt[key]; console.log(`🚀 ${model} » Prompt #${index} • account ${email} …`); const startTime = Date.now(); while (true) { const response = await fetch(urlImages, { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiToken}` }, body: JSON.stringify(body) }); const responseText = await response.text(); if (response.status == 200) { const media = JSON.parse(responseText)?.media ?? []; if (media.length == 0) console.error(`🛑 200 OK but no media (moderated?) for ${model}`); // count > 1 returns multiple images in the media array. for (let i = 0; i < media.length; i++) { const img = media[i]?.image?.generatedImage; await downloadImage(img, `${model}_${i + 1}.jpg`); } console.log(`🆗 ${model} done (${elapsedTimeSec(startTime)} sec)`); return 200; } switch (response.status) { case 429: case 503: console.log(`🔄️ Retry on HTTP ${response.status}`, responseText); await sleep(SLEEP_RETRY); break; default: console.error(`🛑 ${model} failed with HTTP ${response.status}`, responseText); return response.status; } } } // Main function async function main() { const apiToken = process.argv[2]; const email = process.argv[3]; const promptFile = process.argv[4] || DEFAULT_PROMPTS_FILE; if (!apiToken || !email) { console.error('Usage: node google-flow-nano-banana-compare.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE]'); process.exit(1); } console.info('Script v1.1 • Node version ' + process.version); const accounts = await fetchAccounts(apiToken); if (!accounts[email]) { console.error(`⛔ Account ${email} not found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (accounts[email].health && accounts[email].health !== 'OK') { console.error(`⛔ Account ${email} health is '${accounts[email].health}'. Please resolve and update the account, see https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } const prompts = JSON.parse(await fs.readFile(promptFile, 'utf8')); console.log(`Comparing ${prompts.length} model runs …`); const start = new Date(); for (let i = 0; i < prompts.length; i++) await submitImage(apiToken, email, prompts[i], i + 1); console.info('COMPLETED', new Date(), '• elapsed', elapsedTimeSec(start), 'sec'); } main(); ``` </details> ### 示例 下面是同一个养蜂人提示词由每个模型以 9:16 生成的结果,都通过这个 Google Flow API 生成。差别很稳定:Pro 最精致,也最忠实于指令,2.1 最有动感,Lite 最快,效果也很接近。 `nano-banana-pro`:最精致、最有杂志大片感,也是唯一能稳定画出面纱网、在蜂巢上爬的蜜蜂以及字面意义上的 `o_O` 卡通眼的模型。 <img src="https://media.useapi.net/articles/2026-07-02-google-flow-nano-banana-compare/nano-banana-pro.jpg" style="width: 100%; max-width: 420px;" alt="通过 Google Flow API 生成的 Nano Banana Pro 养蜂人图片" /> `nano-banana-2`:最有动感、最有活力的诠释,箭头形的蜂群最清楚,情境细节也很多(工作靴、框上的蜜蜂)。 <img src="https://media.useapi.net/articles/2026-07-02-google-flow-nano-banana-compare/nano-banana-2.jpg" style="width: 100%; max-width: 420px;" alt="通过 Google Flow API 生成的 nano-banana-2 养蜂人图片" /> `nano-banana-2-lite`:三者中最快(在我们的测试中用时大约是 Pro 的一半),同时保留了构图、滴落的蜂蜜和前景中那只瞪着卡通眼的蜜蜂。 <img src="https://media.useapi.net/articles/2026-06-15-google-flow-images-bash/nano-banana-2-lite.jpg" style="width: 100%; max-width: 420px;" alt="通过 Google Flow API 生成的 Nano Banana 2 Lite 养蜂人图片" /> ### 该用哪款 Nano Banana 模型? - 画质最重要时选 `nano-banana-pro`:主视觉、复杂的多主体场景、精确的文字或指令遵循。它是三者中最慢的。 - 想兼顾画质与速度,或想要更有动感、更有风格的诠释时,选 `nano-banana-2`。 - 迭代和大批量生成时选 `nano-banana-2-lite`(默认),速度要紧,画质也依然非常接近。 三者的请求格式相同,所以切换只需改动 `model` 里的一个词:像上面的脚本那样,把三款模型各跑一批,再挑出最好的。 ### 自己运行 完整的 Node.js 脚本、Python 移植版和 `prompts.json` 在 [`useapi/google-flow-api/nano-banana-compare`](https://github.com/useapi/google-flow-api/tree/main/nano-banana-compare)。克隆下来,编辑 `prompts.json`,运行一条命令,就能用你的 Google Flow 账号生成整套对比图。 ### 常见问题 - **有 Nano Banana 2.1 或 Nano Banana Pro 的 API 吗?** 通过 useapi.net 就有:[Google Flow API](/docs/api-google-flow-v1) 在 [POST /images](/docs/api-google-flow-v1/post-google-flow-images) 上以 `nano-banana-2`(Nano Banana 2.1)、`nano-banana-2-lite` 和 `nano-banana-pro` 运行 Google Flow 的这几个版本。在官方 [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) 上,Nano Banana 2.1 每张 1K 图片约 $0.034,Nano Banana Pro 每张 $0.134,而这里不按图片收费(截至 2026 年 11 月)。 - **Nano Banana 2 Lite、2.1 和 Pro 有什么区别?** 在 useapi.net 上,三款模型用同一个接口,各有所长。`nano-banana-pro`(Gemini 3 Pro Image)最精致,也最贴合指令,`nano-banana-2`(Nano Banana 2.1)的诠释最有动感,默认的 `nano-banana-2-lite`(Gemini 3.1 Flash-Lite Image)在我们的测试中用时约为 Pro 的一半。见[该用哪款模型?](#which-nano-banana-model-should-you-use) - **Nano Banana API 多少钱?** 通过 useapi.net,在任何 Google AI 订阅上(包括免费账号)图片都不消耗 Flow 积分,也不需要设置 Gemini API Key 或 Cloud 结算账号。在官方 [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) 上,Nano Banana 2 Lite 每张 1K 图片约 $0.034(截至 2026 年 11 月)。见[价格](#pricing)。 - **图片会被审核吗?** 通过 useapi.net,你的提示词会经过 Google 自己的内容审核,被拒绝的请求会返回空结果。审核结果因请求和模型而异,所以重试、修改提示词或换个模型往往就能成功,因为每款 Nano Banana 模型的审核尺度都略有不同。 - **需要验证码或 Google Cloud 项目吗?** 通过 useapi.net,既不需要 Google Cloud 项目,也不需要自己处理验证码。Google Flow 每生成一张图片都要求 reCAPTCHA,useapi.net 的 worker 会自动解决:你的第一个 Google Flow 账号自带 300 次免费解码,使用我们自己的 AntiCaptcha、CapSolver 和 EzCaptcha 密钥,之后再添加你自己的服务商密钥。本文的脚本不发送 `captchaToken`。 ### 结语 有问题欢迎加入我们的 <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord 服务器</a> 或 <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram 频道</a>。 代码示例见我们的 [GitHub 仓库](https://github.com/useapi/google-flow-api)。 #### 其他发布平台 {: .no_toc #cross-posted } 本文英文版也发布在 [dev.to](https://dev.to/useapi/nano-banana-2-lite-vs-2-vs-pro-google-flow-image-models-compared-3b15){:rel="nofollow"},并在 [Reddit](https://www.reddit.com/r/ThirdPartyAPI/comments/1ulw4zo/nano_banana_2_lite_vs_2_vs_pro_google_flow_image/){:rel="nofollow"} 上讨论。 ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-flow-nano-banana-compare === Document URL: https://useapi.net/docs/articles/google-flow-nano-banana-compare --- layout: default title: "Nano Banana 2 Lite vs 2.1 vs Pro: Google Flow Image Models Compared" description: "Compare Google Flow's three Nano Banana image models — 2 Lite, 2.1, and Pro — on one prompt through the useapi.net API, with a runnable script and real examples." keywords: [Nano Banana 2 Lite, Nano Banana 2.1, Nano Banana 2, Nano Banana Pro, Gemini 3 Pro Image, Gemini 3.1 Flash Image, Gemini 3.1 Flash-Lite Image, nano-banana-2-lite, Nano Banana API, Nano Banana Pro API, image model comparison, Google Flow, image generation, tutorial, code] image: https://media.useapi.net/articles/2026-07-02-google-flow-nano-banana-compare/nano-banana-pro.jpg parent: Articles nav_exclude: true date: 2026-07-02 last_modified: 2026-11-06 nav_order: 830 repo: https://github.com/useapi/google-flow-api translation_key: nano-banana-compare --- ## Nano Banana 2 Lite vs 2.1 vs Pro: Google Flow Image Models Compared 7 min read • July 2, 2026 (November 6, 2026) ## Table of contents ### Introduction Google Flow ships three Nano Banana image models, `nano-banana-2-lite`, `nano-banana-2` and `nano-banana-pro`, and the useapi.net [Google Flow API](/docs/api-google-flow-v1) runs all three from one prompt with your [Google Flow](https://flow.google.com) account. Images are included on every [Google AI subscription](https://gemini.google/subscriptions/), a free account too, where the official Gemini API charges $0.034 to $0.134 per image (as of November 2026). There's no Google Cloud project and no API key. This guide runs the exact same prompt through Lite, 2.1, and Pro so you can see how they differ, then hands you a runnable Node.js script that generates the whole set in one command. Want a from-scratch how-to first? See the sibling [image-generation tutorial](/docs/articles/google-flow-images-bash). ### What are the three Nano Banana models? Pick a model per request with the `model` field. If you omit it, Google Flow uses `nano-banana-2-lite` — its default since July 2026. All three run on any Google AI subscription, including a free account. | Model id | Marketing name | Best for | References (I2I) | Speed | |----------|----------------|----------|-----------------:|-------| | `nano-banana-2-lite` *(default)* | [Nano Banana 2 Lite](https://deepmind.google/models/gemini-image/flash-lite/) / Gemini 3.1 Flash-Lite Image | fast, high-volume images on any plan | max 10 | fastest | | `nano-banana-2` | Nano Banana 2.1 | balanced quality and speed | max 10 | fast | | `nano-banana-pro` | [Nano Banana Pro](https://deepmind.google/models/gemini-image/pro/) / Gemini 3 Pro Image | highest fidelity and instruction-following | max 10 | slower | All three accept the same aspect ratios (`16:9`, `4:3`, `1:1`, `3:4`, `9:16`, plus `auto` in image-to-image mode), `count` (1–4), `seed` for reproducibility, up to 10 reference images, inline `@`-mentions, and [2K/4K upscaling](#upscaling-to-2k4k). The deprecated aliases `imagen-4` (Google removed Imagen from Flow in July 2026) and `nano-banana` are still accepted and map to `nano-banana-2-lite` and `nano-banana-2` respectively. Full per-model detail is on the [POST /images](/docs/api-google-flow-v1/post-google-flow-images) reference. #### Upscaling to 2K/4K Any generated image can be upscaled with [POST /images/upscale](/docs/api-google-flow-v1/post-google-flow-images-upscale): pass its `mediaGenerationId` and a `resolution` of `2k` (default) or `4k`. The response is base64 in `encodedImage`. `2k` works on any plan, and `4k` needs Google AI Ultra. ### Pricing Images cost no Flow credits on any Google AI subscription, a free account included, and useapi.net adds no per-image charge. The price of every model on every plan, against the official API, is in the [Google Flow price table](/docs/api-google-flow-v1#pricing). See the [setup guide](/docs/start-here/setup-google-flow) to connect your account. ### The comparison prompt A model comparison is only useful if the prompt is hard. This one is a deliberately absurd, single-frame scene that stress-tests several things at once: a named photographic style (David LaChapelle), a multi-subject spatial layout (a swarm forming an arrow in the top-left, a forced-perspective bee in the bottom-right), prop fidelity (dripping honeycomb), a specific comedic facial expression (`o_O` cartoon eyes), and a clashing tone — all in one cohesive image. ```text A visually breathtaking, beautifully absurd, single-frame photograph in the hyper-saturated, glossy, surreal-comedy editorial style of David LaChapelle, shot at a sun-dappled backyard apiary at golden hour on an 85mm f/1.4 lens with creamy shallow depth of field. In the center midground, a gorgeous, radiant young woman beekeeper with an elegant figure, flawless glowing sun-kissed skin and a warm playful smile, incongruously wearing a tiny mini bikini and a beekeeper's veil hat pushed back off her face, stands among the wooden hive boxes on the grass and lifts a single open beehive frame heavy with golden honeycomb, thick honey oozing and stringing down in glossy ribbons and catching the light. She looks directly into the camera, delighted and completely unbothered by the bees swirling around her. In the top-left of the frame, a dense swarm of bees bunches together and organizes into a bold, unmistakable arrow / pointer shape aimed straight at her, as if frantically calling everyone's attention. In the extreme bottom-right foreground of the exact same scene, photobombing the lens, is a huge forced-perspective close-up of a single frazzled worker bee, staring directly into the camera with bulging, mind-blown "o_O" cartoon googly eyes, completely frozen in comical disbelief. Single cohesive image, seamless depth of field, no cut-ins, warm dynamic backlighting, glistening honey highlights, crazy situational comedy, hyper-detailed, masterpiece. ``` ### Generate across all three models You need a useapi.net [API token](/docs/start-here/setup-useapi) and a connected [Google Flow account](/docs/start-here/setup-google-flow). `POST /images` is synchronous — one call blocks until the images are ready (typically 20–60 seconds, and the Pro model can take up to ~2 minutes under load) and returns a `media[]` array with one entry per image, so there's no `jobid` to poll. A single call — swap `model` to compare: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/images" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model": "nano-banana-pro", "aspectRatio": "9:16", "count": 4, "prompt": "A beekeeper at golden hour lifting a dripping honeycomb frame, a swarm forming an arrow in the sky, a forced-perspective bee with o_O googly eyes in the foreground" }' > result.json # each image is at .media[N].image.generatedImage.fifeUrl curl -o pro_1.jpg "$(jq -r '.media[0].image.generatedImage.fifeUrl' result.json)" ``` To run the full comparison in one command, the Node.js script below reads `prompts.json` — one entry per model, all with the same prompt — submits each, and saves every returned image with a model-labeled filename, downloading it from `fifeUrl` or decoding the inline `encodedImage` when the URL is missing. A failed image is logged and the run moves on. You need [Node.js](https://nodejs.org) v21+. Put both files in a folder and run `node ./google-flow-nano-banana-compare.mjs API_TOKEN EMAIL`, where `API_TOKEN` is your useapi.net [API token](/docs/start-here/setup-useapi) and `EMAIL` is your connected [Google Flow account](/docs/start-here/setup-google-flow). The script looks the account up by email and checks its `health` before submitting, and sends no `captchaToken` — the useapi.net worker solves the reCAPTCHA automatically. Prefer to clone and run it? The complete script, a Python port, and `prompts.json` are on GitHub in [`useapi/google-flow-api`](https://github.com/useapi/google-flow-api/tree/main/nano-banana-compare). <details markdown="block"> <summary>Expand `prompts.json`</summary> ```json [ { "model": "nano-banana-2-lite", "aspectRatio": "9:16", "count": 4, "prompt": "A beekeeper at golden hour lifting a dripping honeycomb frame in the surreal editorial style of David LaChapelle, a dense bee swarm forming a bold arrow in the top-left, a forced-perspective bee with o_O cartoon googly eyes photobombing the bottom-right. Single cohesive image, masterpiece." }, { "model": "nano-banana-2", "aspectRatio": "9:16", "count": 4, "prompt": "A beekeeper at golden hour lifting a dripping honeycomb frame in the surreal editorial style of David LaChapelle, a dense bee swarm forming a bold arrow in the top-left, a forced-perspective bee with o_O cartoon googly eyes photobombing the bottom-right. Single cohesive image, masterpiece." }, { "model": "nano-banana-pro", "aspectRatio": "9:16", "count": 4, "prompt": "A beekeeper at golden hour lifting a dripping honeycomb frame in the surreal editorial style of David LaChapelle, a dense bee swarm forming a bold arrow in the top-left, a forced-perspective bee with o_O cartoon googly eyes photobombing the bottom-right. Single cohesive image, masterpiece." } ] ``` </details> <details markdown="block"> <summary>Expand `google-flow-nano-banana-compare.mjs` script</summary> ```javascript /* Script version 1.1, September 11, 2026 Batch-compare Google Flow's Nano Banana image models (2 Lite, 2.1, Pro) with the useapi.net API 🚀 Reads prompts.json (one entry per model), submits each to the synchronous POST /images endpoint, and downloads every returned image with a model-labeled filename. For more details visit https://useapi.net/docs/api-google-flow-v1/post-google-flow-images Companion tutorial: https://useapi.net/docs/articles/google-flow-nano-banana-compare Installation Instructions: ========================== You need Node.js v21 or newer installed to run this script. Download and install Node.js from: - Windows, macOS, Linux: https://nodejs.org/ After installation, verify by running the following command in a terminal: node -v Running the Script: =================== Usage: node google-flow-nano-banana-compare.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE] Replace API_TOKEN with your actual useapi.net API token, see https://useapi.net/docs/start-here/setup-useapi Replace EMAIL with configured Google Flow email account, see https://useapi.net/docs/start-here/setup-google-flow If optional PROMPTS_FILE not provided prompts.json will be used. Example: -------- node google-flow-nano-banana-compare.mjs user:1234-abcdefhijklmnopqrstuv my@email.com Changelog: ========== - July 2, 2026: Initial release. - September 11, 2026: Saves encodedImage when fifeUrl is absent, and writes a downloaded image only once it has been fully received, so a failed download leaves no partial file for the next run to skip as "already exists". */ import fs from 'fs/promises'; import { writeFile } from 'node:fs/promises'; // Constants const DEFAULT_PROMPTS_FILE = 'prompts.json'; const DEFAULT_MODEL = 'nano-banana-2-lite'; const SLEEP_RETRY = 30 * 1000; // in milliseconds const urlAccounts = 'https://api.useapi.net/v1/google-flow/accounts'; const urlImages = 'https://api.useapi.net/v1/google-flow/images'; // Utility to sleep for given milliseconds const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); const elapsedTimeSec = (start) => (Date.now() - start) / 1000; // Function to fetch configured Google Flow API accounts async function fetchAccounts(apiToken) { const response = await fetch(urlAccounts, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.error(`⛔ Error fetching accounts (HTTP ${response.status}): ${response.statusText}`); process.exit(1); } return response.json(); } // Save a single image from its signed fifeUrl. fifeUrl is normally present; when it is absent // the image arrived inline as base64 in encodedImage. A failure is reported and skipped. async function downloadImage(img, filename) { try { await fs.access(filename); console.log(`⚠️ ${filename} already exists. Skipping download.`); return; } catch { // File does not exist, proceed with downloading } const url = img?.fifeUrl; if (!url && img?.encodedImage) { console.log(`✅ Saving ${filename} from encodedImage`); try { await writeFile(filename, Buffer.from(img.encodedImage, 'base64')); } catch (err) { console.error(`⛔ Unable to save ${filename}: ${err}`); } return; } if (!url) { console.error(`🛑 No fifeUrl or encodedImage for ${filename}`); return; } console.log(`✅ Downloading ${filename}`); try { const imageResponse = await fetch(url); if (!imageResponse.ok) { console.error(`⛔ Unable to download ${filename} (HTTP ${imageResponse.status})`); return; } // Read the whole body before creating the file, so a failed download leaves no // partial file behind for the next run to skip as "already exists". const data = Buffer.from(await imageResponse.arrayBuffer()); await writeFile(filename, data); } catch (err) { console.error(`⛔ Error during download: ${err}`); } } // Submit a single prompt to the synchronous POST /images endpoint and download the results. async function submitImage(apiToken, email, prompt, index) { const model = prompt.model ?? DEFAULT_MODEL; // Build the request body. const body = { model, email, prompt: prompt.prompt }; for (const key of ['aspectRatio', 'count', 'seed']) if (prompt[key] !== undefined) body[key] = prompt[key]; console.log(`🚀 ${model} » Prompt #${index} • account ${email} …`); const startTime = Date.now(); while (true) { const response = await fetch(urlImages, { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiToken}` }, body: JSON.stringify(body) }); const responseText = await response.text(); if (response.status == 200) { const media = JSON.parse(responseText)?.media ?? []; if (media.length == 0) console.error(`🛑 200 OK but no media (moderated?) for ${model}`); // count > 1 returns multiple images in the media array. for (let i = 0; i < media.length; i++) { const img = media[i]?.image?.generatedImage; await downloadImage(img, `${model}_${i + 1}.jpg`); } console.log(`🆗 ${model} done (${elapsedTimeSec(startTime)} sec)`); return 200; } switch (response.status) { case 429: case 503: console.log(`🔄️ Retry on HTTP ${response.status}`, responseText); await sleep(SLEEP_RETRY); break; default: console.error(`🛑 ${model} failed with HTTP ${response.status}`, responseText); return response.status; } } } // Main function async function main() { const apiToken = process.argv[2]; const email = process.argv[3]; const promptFile = process.argv[4] || DEFAULT_PROMPTS_FILE; if (!apiToken || !email) { console.error('Usage: node google-flow-nano-banana-compare.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE]'); process.exit(1); } console.info('Script v1.1 • Node version ' + process.version); const accounts = await fetchAccounts(apiToken); if (!accounts[email]) { console.error(`⛔ Account ${email} not found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (accounts[email].health && accounts[email].health !== 'OK') { console.error(`⛔ Account ${email} health is '${accounts[email].health}'. Please resolve and update the account, see https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } const prompts = JSON.parse(await fs.readFile(promptFile, 'utf8')); console.log(`Comparing ${prompts.length} model runs …`); const start = new Date(); for (let i = 0; i < prompts.length; i++) await submitImage(apiToken, email, prompts[i], i + 1); console.info('COMPLETED', new Date(), '• elapsed', elapsedTimeSec(start), 'sec'); } main(); ``` </details> ### Examples Here is the same beekeeper prompt rendered by each model at 9:16, generated through this Google Flow API. The differences are consistent: Pro is the most polished and the most literal about the instructions, 2.1 is the most dynamic, and Lite is the fastest while staying close. `nano-banana-pro` — the most polished and editorial, and the only model that reliably renders the veil netting, the bees crawling on the comb, and the literal `o_O` cartoon eyes. <img src="https://media.useapi.net/articles/2026-07-02-google-flow-nano-banana-compare/nano-banana-pro.jpg" style="width: 100%; max-width: 420px;" alt="Nano Banana Pro beekeeper result via the Google Flow API" /> `nano-banana-2` — the most dynamic and energetic interpretation, with the clearest arrow-shaped swarm and lots of situational detail (work boots, bees on the frame). <img src="https://media.useapi.net/articles/2026-07-02-google-flow-nano-banana-compare/nano-banana-2.jpg" style="width: 100%; max-width: 420px;" alt="nano-banana-2 beekeeper result via the Google Flow API" /> `nano-banana-2-lite` — the fastest of the three (roughly half Pro's time in our runs) while keeping the composition, the honey drip, and the googly-eyed foreground bee. <img src="https://media.useapi.net/articles/2026-06-15-google-flow-images-bash/nano-banana-2-lite.jpg" style="width: 100%; max-width: 420px;" alt="Nano Banana 2 Lite beekeeper result via the Google Flow API" /> ### Which Nano Banana model should you use? - Reach for `nano-banana-pro` when fidelity matters most — hero shots, complex multi-subject scenes, precise text or instruction-following. It is the slowest of the three. - Reach for `nano-banana-2` for a strong balance of quality and speed, or when you want a more dynamic, stylized read of a prompt. - Reach for `nano-banana-2-lite` (the default) for iteration and high-volume batches where speed matters and the quality is still very close. Because they share the same request shape, switching is a one-word change to `model` — generate a batch across all three and pick the winner, exactly like the script above does. ### Run it yourself The complete Node.js script, a Python port, and `prompts.json` live in [`useapi/google-flow-api/nano-banana-compare`](https://github.com/useapi/google-flow-api/tree/main/nano-banana-compare). Clone it, edit `prompts.json`, and run one command to generate the full comparison set with your Google Flow account. ### Frequently asked questions - **Is there a Nano Banana 2.1 or Nano Banana Pro API?** Through useapi.net, yes: the [Google Flow API](/docs/api-google-flow-v1) runs Google Flow's versions as `nano-banana-2` (Nano Banana 2.1), `nano-banana-2-lite` and `nano-banana-pro` on [POST /images](/docs/api-google-flow-v1/post-google-flow-images). On the official [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) Nano Banana 2.1 costs about $0.034 per 1K image and Nano Banana Pro $0.134 an image, against no per-image charge here (as of November 2026). - **What is the difference between Nano Banana 2 Lite, 2.1, and Pro?** Through useapi.net all three run on the same endpoint, each with its own strength. `nano-banana-pro` (Gemini 3 Pro Image) is the most polished and follows instructions most closely, `nano-banana-2` (Nano Banana 2.1) gives the most dynamic read, and `nano-banana-2-lite` (Gemini 3.1 Flash-Lite Image), the default, took about half Pro's time in our runs. See [Which model should you use?](#which-nano-banana-model-should-you-use) - **How much does the Nano Banana API cost?** Through useapi.net, images cost no Flow credits on any Google AI subscription, a free account included, and there is no Gemini API key or Cloud billing account to set up. On the official [Gemini API](https://ai.google.dev/gemini-api/docs/pricing), Nano Banana 2 Lite costs about $0.034 per 1K image (as of November 2026). See [Pricing](#pricing). - **Do images get moderated?** Through useapi.net, your prompts reach Google's own content moderation, and a rejected request returns an empty result. Moderation decisions vary between requests and between models, so retrying, editing the prompt or switching models often succeeds, because each Nano Banana model moderates a little differently. - **Do I need a captcha or a Google Cloud project?** Through useapi.net you need neither a Google Cloud project nor a captcha of your own. Google Flow asks for a reCAPTCHA on every image, and the useapi.net worker solves it automatically: your first Google Flow account comes with 300 free solves on our own AntiCaptcha, CapSolver and EzCaptcha keys, and after that you add your own provider keys. The script here sends no `captchaToken`. ### Conclusion Visit our <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> or <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> for any support questions and concerns. Check our [GitHub repo](https://github.com/useapi/google-flow-api) with code examples. #### Cross posted Also published on [dev.to](https://dev.to/useapi/nano-banana-2-lite-vs-2-vs-pro-google-flow-image-models-compared-3b15){:rel="nofollow"} and discussed on [Reddit](https://www.reddit.com/r/ThirdPartyAPI/comments/1ulw4zo/nano_banana_2_lite_vs_2_vs_pro_google_flow_image/){:rel="nofollow"}. === URL: https://useapi.net/docs/articles/google-flow-ugc-product-video-es === Document URL: https://useapi.net/docs/articles/google-flow-ugc-product-video-es --- layout: default title: "Cómo hacer un video UGC de producto con la Google Flow API" description: "Arma un video UGC de producto de 29 segundos con la Google Flow API de useapi.net: fichas de producto y una presentadora con POST /images, una imagen fija que lo reúne todo, tres clips Omni 1.1 Flash de 10 segundos a partir de ella, un escalado gratis a 1080p y POST /videos/concatenate para unirlos." keywords: [UGC video, product video, Google Flow API, Omni 1.1 Flash, product sheets, character, first and last frame, concatenate, video UGC, video de producto, anuncio UGC, API de video con IA, primer y último fotograma, unir videos, ficha de producto, tutorial, código, curl] image: https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/06-ugc-products-still-presenter-and-three-products-nano-banana-2-lite.png video: name: "UGC with the Google Flow API, the 75-second walkthrough" description: "The finished UGC product video, then how it was built: product sheets, a character, one still, three Omni 1.1 Flash clips and one concatenate call, through the useapi.net Google Flow API." url: https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/ugc-google-flow-api-1080p.mp4 embed: https://www.youtube.com/embed/wbUROtDIfGA thumbnail: https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/06-ugc-products-still-presenter-and-three-products-nano-banana-2-lite.png date: 2026-09-04 duration: PT1M15S width: 1080 height: 1920 parent: Articles nav_exclude: true lang: es translation_key: ugc-product-video date: 2026-09-04 last_modified: 2026-11-06 nav_order: 835 repo: https://github.com/useapi/google-flow-api --- ## Cómo hacer un video UGC de producto con la Google Flow API {: .no_toc #how-to-make-a-ugc-product-video-with-the-google-flow-api } 8 min de lectura • 4 de septiembre de 2026 (6 de noviembre de 2026) useapi.net es una API de terceros. No está afiliada a Google ni cuenta con su respaldo. ## Índice {: .no_toc .text-delta #table-of-contents } ### Introducción Un video UGC de producto se puede hacer de principio a fin con la [Google Flow API de useapi.net](/docs/api-google-flow-v1) por 45 créditos de Flow, sin procesar nada en tu computadora. Una presentadora inventada muestra tres productos inventados a la cámara. UGC es el estilo de contenido generado por usuarios que llena los feeds de redes sociales y las bibliotecas de anuncios: una persona que le habla a la cámara del celular, para vender un producto, para entretener o solo por diversión. Esta es la guía completa, de la A a la Z, para producir ese tipo de video a nivel profesional: los productos, la presentadora, sus diálogos y el corte final, todo bajo tu control, en seis pasos de llamadas a la API que puedes copiar tal cual. ¿Prefieres un formulario sin código? El [flujo de anuncios UGC en n8n](/docs/articles/google-flow-n8n-ugc-ads) (en inglés) crea este tipo de anuncio con una página para elegir o volver a generar en cada paso. Este es el resultado: tres clips Omni 1.1 Flash de 10 segundos escalados a 1080p, con cada fotograma y cada sonido generados con la [Google Flow API](/docs/api-google-flow-v1). La misma llamada de escalado llega a 4K cuando necesitas calidad profesional, consulta el [Paso 5](#step-5-upscale-to-1080p): <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 260px;max-width:320px;margin:0"> <video poster="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/10b-ugc-products-joined-29s-1080p-upscaled-concatenated-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/10b-ugc-products-joined-29s-1080p-upscaled-concatenated.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">El resultado — 29 segundos, 1080p, tres productos, tres clips (45 créditos en total)</figcaption> </figure> </div> Si prefieres ver en lugar de leer, aquí está toda la guía en 75 segundos (en inglés): <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 260px;max-width:320px;margin:0"> <div style="position:relative;width:100%;padding-top:177.78%;border-radius:8px;overflow:hidden"> <iframe src="https://www.youtube.com/embed/wbUROtDIfGA" title="UGC with the Google Flow API, the 75-second walkthrough" style="position:absolute;top:0;left:0;width:100%;height:100%;border:0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen loading="lazy"></iframe> </div> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">El recorrido de 75 segundos (<a href="https://www.youtube.com/watch?v=wbUROtDIfGA" target="_blank" rel="noopener noreferrer">ver en YouTube</a> · narración y música de la <a href="/docs/api-minimax-v1">MiniMax API</a>)</figcaption> </figure> </div> ### Precios El video con Omni 1.1 Flash requiere una suscripción paga de Google AI (Plus, Pro o Ultra), y useapi.net no cobra nada por video. Lo que costó este video, paso a paso, está en [Cuánto costó](#what-it-cost), y el precio por video en cada plan, frente a la API oficial, está en la [tabla de precios de Google Flow](/docs/api-google-flow-v1#pricing). ### Sobre los ids en las solicitudes Cada solicitud de abajo se refiere a resultados anteriores por su `mediaGenerationId`. Los ids son largos, así que aquí aparecen abreviados como `user:1234-email:…-image:b0bdf3e8-…`, y una línea debajo de cada solicitud indica a qué resultado anterior corresponde cada uno. El id de una imagen viene de [POST /images](/docs/api-google-flow-v1/post-google-flow-images) en `media[0].image.generatedImage.mediaGenerationId`, el de un personaje en el campo `character` de [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters), el de un video en `media[0].mediaGenerationId` del [job](/docs/api-google-flow-v1/get-google-flow-jobs-jobid) terminado, y el id de un clip escalado es el id de origen con `_upsampled` al final. ### Paso 1: una ficha por producto Una ficha de producto es una sola imagen que muestra el objeto desde cuatro lados, para que el modelo tenga el objeto completo y no un ángulo afortunado. [POST /images](/docs/api-google-flow-v1/post-google-flow-images), cuadrada, una solicitud por producto. El prompt describe la cámara de cada panel, porque solo "frente, lado, atrás" dio dos paneles idénticos para la taza y ningún lateral real para el teclado. Un objeto plano como el teclado necesita un panel cenital, uno con forma de cubo no. Sin manos, sin textos, sin logos, para que nada más que el producto se cuele en los clips. Lo mismo funciona con un producto real. Sube fotos con [POST /assets](/docs/api-google-flow-v1/post-google-flow-assets-email) y pasa sus ids como `reference_1` a `reference_4` en esta solicitud, y el modelo las convierte en una ficha limpia de cuatro paneles. El mismo truco sirve para una ficha de un empaque, un logo o un set. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a> (la taza)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="1:1"' \ --form 'count="2"' \ --form 'prompt="Orthographic product-catalog sheet on a plain white background: a matte white ceramic mug with a straight cylindrical body and a clearly visible glowing amber light band around its base, about a finger wide, like a smart heated mug. The sheet is divided into four equal panels by thin grey lines in a 2 by 2 grid. Every panel shows the same single item at exactly the same size, position and lighting, camera at the item'\''s eye level unless stated: top-left: side profile, the handle pointing left and seen edge-on; top-right: view from the handle side, the handle pointing straight at the camera; bottom-left: view from the opposite side, the handle hidden behind the body; bottom-right: three-quarter view from slightly above, the handle to the right. Soft even studio light, photoreal. Object only: no hands, no people, no props, no text anywhere, no captions, no labels, no logo, no packaging."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/01-ugc-products-sheet-smart-mug-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/01-ugc-products-sheet-smart-mug-nano-banana-2-lite.png" alt="Ficha de producto de la taza inteligente, cuatro vistas en una cuadrícula de 2 por 2" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">La taza — Nano Banana 2 Lite, id <code>b0bdf3e8</code> (0 créditos)</figcaption> </figure> </div> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a> (el robot de escritorio)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="1:1"' \ --form 'count="2"' \ --form 'prompt="Orthographic product-catalog sheet on a plain white background: a small rounded pastel mint desk robot, a palm-sized cube with a glossy black screen face showing a happy smiling expression, two round white eyes and a curved white smile, a little rounded antenna nub on top, a small round white dial on its right side, and a speaker grille on its back. The sheet is divided into four equal panels by thin grey lines in a 2 by 2 grid. Every panel shows the same single item at exactly the same size, position and lighting, camera at the item'\''s eye level unless stated: top-left: front view showing the smiling face; top-right: right side view showing the round dial and the antenna nub; bottom-left: back view showing the speaker grille; bottom-right: three-quarter view showing the smiling face and the dial. Soft even studio light, photoreal. Object only: no hands, no people, no props, no text anywhere, no captions, no labels, no logo, no packaging."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/02-ugc-products-sheet-desk-robot-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/02-ugc-products-sheet-desk-robot-nano-banana-2-lite.png" alt="Ficha de producto del robot de escritorio, cuatro vistas en una cuadrícula de 2 por 2" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">El robot de escritorio — Nano Banana 2 Lite, id <code>7aaed056</code> (0 créditos)</figcaption> </figure> </div> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a> (el teclado)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="1:1"' \ --form 'count="4"' \ --form 'prompt="Orthographic product-catalog sheet on a plain white background: a real mechanical three-key macro pad, the kind sold for shortcuts: a slim, low-profile white aluminum case, three mechanical key switches in one row with sculpted dished keycaps and a small gap between them, coral on the left, lemon yellow in the middle, sky blue on the right, a USB-C port on the back edge. Exactly three keys in one row, never more. The sheet is divided into four equal panels by thin grey lines in a 2 by 2 grid. Every panel shows the same single item at exactly the same size, position and lighting, camera at the item'\''s eye level unless stated: top-left: top-down view straight from above, the three keys in a row left to right; top-right: front view at eye level; bottom-left: left side view at eye level, the slim case and the keycap profile seen edge-on; bottom-right: three-quarter view from above. Soft even studio light, photoreal. Object only: no hands, no people, no props, no text anywhere, no captions, no labels, no logo, no packaging."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/03-ugc-products-sheet-three-key-keyboard-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/03-ugc-products-sheet-three-key-keyboard-nano-banana-2-lite.png" alt="Ficha de producto del teclado de tres teclas, cuatro vistas en una cuadrícula de 2 por 2" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">El teclado — Nano Banana 2 Lite, id <code>4f861c23</code> (0 créditos)</figcaption> </figure> </div> Las imágenes no cuestan nada, así que pide un `count` de 2 a 4 y quédate con la mejor ficha. El teclado tomó varias rondas hasta que el prompt describió un macro pad real con un panel cenital, el cubo salió bien a la primera. ### Paso 2: la presentadora Tres llamadas. Un retrato de frente a partir de una descripción. Un retrato de tres cuartos generado a partir del primero con `reference_1`, para que los dos coincidan en el rostro. Después [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters) con ambos retratos, que devuelve una referencia de personaje. Desde ese momento ella es `@character_1` en cualquier prompt, y Google la fija con su propio sistema de entidades en lugar de con una descripción. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a> (retrato de frente)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="3:4"' \ --form 'count="2"' \ --form 'prompt="Character reference portrait, photoreal, natural skin, no heavy retouching: a strikingly attractive young woman in her early twenties with a sleek platinum-blonde blunt bob and straight bangs, dark defined eyebrows, icy grey eyes, a tiny silver nose stud, a playful smirk with a hint of teeth, wearing a fitted black turtleneck and a thin gold chain necklace. Head and shoulders, facing the camera straight on, plain light-grey studio background, soft even light. No text, no logo, no captions."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/04-ugc-products-presenter-front-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/04-ugc-products-presenter-front-nano-banana-2-lite.png" alt="Retrato de frente de la presentadora" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">De frente — Nano Banana 2 Lite, id <code>a236ef66</code> (0 créditos)</figcaption> </figure> </div> Generamos varios looks y elegimos este. Si después hay que cambiar un detalle, la cadena, por ejemplo, vuelve a generarla con su propio retrato como `reference_1` y un prompt que nombre solo el cambio, y el rostro se mantiene. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a> (retrato de tres cuartos)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="3:4"' \ --form 'count="1"' \ --form 'reference_1="user:1234-email:…-image:a236ef66-…"' \ --form 'prompt="@reference_1 is the same woman: identical face, hair, freckles, sweater and earrings. Three-quarter view from the waist up, relaxed natural smile, plain light-grey studio background, soft even light. Photoreal, no text."' ``` </details> `reference_1` es el retrato de frente, `a236ef66`. Este prompt todavía menciona pecas, un suéter y aretes que quedaron de una presentadora anterior, y no hizo daño: con una imagen de referencia en la solicitud, la referencia gana sobre las palabras. <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/05-ugc-products-presenter-three-quarter-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/05-ugc-products-presenter-three-quarter-nano-banana-2-lite.png" alt="Retrato de tres cuartos de la presentadora, generado a partir del retrato de frente" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">Tres cuartos — id <code>d891301c</code> (0 créditos)</figcaption> </figure> </div> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-characters">POST /characters</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/characters' \ --header 'Authorization: Bearer user:1234-…' \ --form 'displayName="Mia"' \ --form 'personalityNotes="Quick, bright, deadpan delivery with a smile in her voice. Talks to the camera like a friend showing off things she bought at 2am."' \ --form 'imageReference_1="user:1234-email:…-image:a236ef66-…"' \ --form 'imageReference_2="user:1234-email:…-image:d891301c-…"' \ --form 'voice="Leda"' ``` </details> `imageReference_1` es el retrato de frente `a236ef66`, `imageReference_2` el de tres cuartos `d891301c`. El campo `character` de la respuesta es su id, `53ca1036` más abajo. La `voice` es uno de los presets de sistema de Google y viaja con el personaje, pero no llega al modo de clip que se usa en el Paso 4, consulta [Qué esperar](#what-to-expect). ### Paso 3: la imagen fija, toda la escena en un fotograma Una solicitud lo junta todo. El personaje entra como `character_1`, las tres fichas como `reference_1` a `reference_3`, y el prompt las coloca por etiqueta, de izquierda a derecha sobre la mesa frente a ella. Este fotograma se convierte en los dos extremos de cada clip, así que es el único lugar donde las etiquetas hacen su trabajo. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="9:16"' \ --form 'count="2"' \ --form 'character_1="user:1234-email:…-character:53ca1036-…"' \ --form 'reference_1="user:1234-email:…-image:b0bdf3e8-…"' \ --form 'reference_2="user:1234-email:…-image:7aaed056-…"' \ --form 'reference_3="user:1234-email:…-image:4f861c23-…"' \ --form 'prompt="Full-frame vertical phone video look, no phone, no bezel. @character_1 sits at a light wooden table in a bright minimal creator studio, facing the camera, waist-up and centered, a plain warm-grey backdrop behind her, soft key light from the left with a gentle catchlight in her eyes. Laid out on the table in front of her, left to right, each fully visible and resting flat on the table: the mug from @reference_1, the desk robot from @reference_2, the keyboard from @reference_3. Her hands rest on the table, relaxed closed-mouth smile, eyes on the lens. Photoreal, no text, no captions."' ``` </details> `character_1` es el personaje del Paso 2, `53ca1036`. `reference_1` a `reference_3` son las tres fichas del Paso 1: la taza `b0bdf3e8`, el robot de escritorio `7aaed056`, el teclado `4f861c23`. <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/06-ugc-products-still-presenter-and-three-products-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/06-ugc-products-still-presenter-and-three-products-nano-banana-2-lite.png" alt="La presentadora en la mesa con la taza, el robot de escritorio y el teclado frente a ella" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">La imagen fija — su rostro viene del personaje, cada producto de su ficha, id <code>034cddc8</code> (0 créditos)</figcaption> </figure> </div> La taza tiene su brillo, el robot su cara y su antena, el teclado sus tres colores y su puerto, y ella es la mujer de los retratos. ### Paso 4: un clip por producto, todos desde la imagen fija El modo de primer y último fotograma de Omni con la imagen fija en ambas posiciones, una solicitud por producto, el mismo [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) cada vez. Este modo solo acepta las dos imágenes, sin fichas, sin personaje, sin referencia de voz. No pasa nada, porque la imagen fija ya lo contiene todo. Cada objeto que ella levanta salió igual a su ficha solo a partir de la imagen fija. El prompt cumple tres funciones. Fija ambos extremos al fotograma, con una pausa tranquila en cada lado. Le da su diálogo y su voz. Y marca los tiempos de la coreografía: empieza a hablar mientras levanta el objeto, el objeto vuelve a su lugar para el segundo ocho, y los dos últimos segundos son una pausa quieta y en silencio. Sin esa última parte se atrasaba y su brazo saltaba al fotograma final. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos">POST /videos</a> (la taza)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'model="omni-flash"' \ --form 'aspectRatio="portrait"' \ --form 'duration="10"' \ --form 'resolution="720p"' \ --form 'startImage="user:1234-email:…-image:034cddc8-…"' \ --form 'endImage="user:1234-email:…-image:034cddc8-…"' \ --form 'prompt="She begins and ends exactly on this frame: hands resting on the table, the three items laid out in front of her, a small closed-mouth smile, looking into the lens, with a short quiet beat before she moves and another after she settles back. Timing matters: after a short quiet beat she picks up the mug on the left with both hands and starts talking as she lifts it, holding it up to the camera and talking straight to the lens, quick and bright with a deadpan edge and a smile in her voice, keeping both hands on the mug while she speaks. She says: \"Three gadgets smarter than me. Low bar. One: this mug texts me when my coffee'\''s cold. Better follow-up than my ex.\" Right after the last word she gives one short laugh to herself, still holding the mug. By the eight-second mark the mug is back down gently in exactly the same spot and both hands are resting on the table again, brought back in one calm unhurried movement. For the final two seconds she holds completely still, hands resting on the table, looking into the lens with a small closed-mouth smile. Natural room tone, no music, no captions, no text on screen."' ``` </details> `startImage` y `endImage` son ambos la imagen fija del Paso 3, `034cddc8`. Los mismos dos ids van en los tres clips. <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 220px;max-width:260px;margin:0"> <video poster="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/07b-ugc-products-clip-1-smart-mug-10s-omni-1.1-flash-1080p-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/07b-ugc-products-clip-1-smart-mug-10s-omni-1.1-flash-1080p.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">Clip 1, la taza — 10 segundos, id <code>55808825</code>, mostrado tras el escalado a 1080p del Paso 5 (15 créditos)</figcaption> </figure> </div> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos">POST /videos</a> (el robot de escritorio)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'model="omni-flash"' \ --form 'aspectRatio="portrait"' \ --form 'duration="10"' \ --form 'resolution="720p"' \ --form 'startImage="user:1234-email:…-image:034cddc8-…"' \ --form 'endImage="user:1234-email:…-image:034cddc8-…"' \ --form 'prompt="She begins and ends exactly on this frame: hands resting on the table, the three items laid out in front of her, a small closed-mouth smile, looking into the lens, with a short quiet beat before she moves and another after she settles back. Timing matters: after a short quiet beat she picks up the desk robot in the middle with both hands and starts talking as she lifts it, holding it up to the camera with its smiling face toward the lens and turning it once and talking straight to the lens, quick and bright with a deadpan edge and a smile in her voice, keeping both hands on it while she speaks. The other two items stay on the table exactly where they are. She says: \"Two: a desk robot that reacts to my day. It has a face. It has never once looked impressed.\" Right after the last word she raises one eyebrow at the camera, a quick expressive beat, still holding the desk robot. By the eight-second mark the desk robot is back down gently in exactly the same spot and both hands are resting on the table again, brought back in one calm unhurried movement. For the final two seconds she is silent and holds completely still, hands resting on the table, looking into the lens with a small closed-mouth smile. Natural room tone, no music, no captions, no text on screen."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 220px;max-width:260px;margin:0"> <video poster="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/08b-ugc-products-clip-2-desk-robot-10s-omni-1.1-flash-1080p-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/08b-ugc-products-clip-2-desk-robot-10s-omni-1.1-flash-1080p.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">Clip 2, el robot de escritorio — 10 segundos, id <code>c4d0e6b1</code>, mostrado tras el escalado a 1080p del Paso 5 (15 créditos)</figcaption> </figure> </div> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos">POST /videos</a> (el teclado)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'model="omni-flash"' \ --form 'aspectRatio="portrait"' \ --form 'duration="10"' \ --form 'resolution="720p"' \ --form 'startImage="user:1234-email:…-image:034cddc8-…"' \ --form 'endImage="user:1234-email:…-image:034cddc8-…"' \ --form 'prompt="She begins and ends exactly on this frame: hands resting on the table, the three items laid out in front of her, a small closed-mouth smile, looking into the lens, with a short quiet beat before she moves and another after she settles back. Timing matters: after a short quiet beat she picks up the keyboard on the right with both hands and starts talking as she lifts it, holding it up to the camera with the three keys facing the lens and talking straight to the lens, quick and bright with a deadpan edge and a smile in her voice, keeping both hands on it while she speaks. The other two items stay on the table exactly where they are. She says: \"Three: a keyboard with three keys. Copy, paste, undo. That'\''s my whole career. Oh, the mug'\''s texting. Bye!\" Right after the last word she raises one eyebrow at the camera, a quick expressive beat, still holding the keyboard. By the eight-second mark the keyboard is back down gently in exactly the same spot and both hands are resting on the table again, brought back in one calm unhurried movement. For the final two seconds she is silent and holds completely still, hands resting on the table, looking into the lens with a small closed-mouth smile. Natural room tone, no music, no captions, no text on screen."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 220px;max-width:260px;margin:0"> <video poster="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/09b-ugc-products-clip-3-three-key-keyboard-10s-omni-1.1-flash-1080p-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/09b-ugc-products-clip-3-three-key-keyboard-10s-omni-1.1-flash-1080p.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">Clip 3, el teclado — 10 segundos, id <code>3cc8ea2f</code>, mostrado tras el escalado a 1080p del Paso 5 (15 créditos)</figcaption> </figure> </div> La misma mujer, la misma mesa, la misma luz, y cada clip abre y cierra en la imagen fija, así que cualquiera puede ir después de cualquier otro. Los diálogos tienen unas 20 palabras en inglés, lo que cabe en 10 segundos a este ritmo con espacio para la pausa del final. ### Paso 5: escalar a 1080p Omni 1.1 Flash renderiza en 720p. [POST /videos/upscale](/docs/api-google-flow-v1/post-google-flow-videos-upscale) lleva un clip a 1080p gratis en cualquier plan pago, en unos 40 segundos, y responde en la misma llamada con el id y la URL del clip escalado. Una solicitud por clip, sin `email`: la cuenta sale del id. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos-upscale">POST /videos/upscale</a> (la taza, luego lo mismo para los otros dos)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos/upscale' \ --header 'Authorization: Bearer user:1234-…' \ --form 'mediaGenerationId="user:1234-email:…-video:55808825-…"' \ --form 'resolution="1080p"' ``` </details> `mediaGenerationId` es el clip de la taza del Paso 4, `55808825`. La misma llamada con `c4d0e6b1` y `3cc8ea2f` escala el robot y el teclado. Cada respuesta trae el nuevo clip en `media[0].mediaGenerationId`, que es el id de origen con `_upsampled` al final, así que los tres ids escalados son `55808825-…_upsampled`, `c4d0e6b1-…_upsampled` y `3cc8ea2f-…_upsampled`. Los clips que se muestran en el Paso 4 son estas versiones escaladas. También hay 4K, por 50 créditos y solo en un plan Google AI Ultra. ### Paso 6: unirlos [POST /videos/concatenate](/docs/api-google-flow-v1/post-google-flow-videos-concatenate) recibe los tres ids escalados en orden y devuelve el archivo unido en base64, a la resolución de los clips. Los recortes deciden si las uniones se sienten como una sola toma. Cada clip abre con una pausa corta en la imagen fija y cierra regresando a ella, y sin recortar esas pausas se acumulan en un congelamiento en cada corte. Pero ella termina cada diálogo con las manos ya apoyadas, así que un recorte medido solo por la imagen se come las últimas palabras. Corta después del último sonido más un instante, nunca antes. En estos clips eso significó dejar el clip 1 entero, ya que su risa llega hasta el último fotograma, quitar poco más de medio segundo del final del clip 2 y unos cuantos fotogramas del inicio de los clips 2 y 3. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos-concatenate">POST /videos/concatenate</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos/concatenate' \ --header 'Authorization: Bearer user:1234-…' \ --header 'Content-Type: application/json' \ --data '{ "media": [ { "mediaGenerationId": "user:1234-email:…-video:55808825-…_upsampled" }, { "mediaGenerationId": "user:1234-email:…-video:c4d0e6b1-…_upsampled", "trimStart": 0.458, "trimEnd": 0.6 }, { "mediaGenerationId": "user:1234-email:…-video:3cc8ea2f-…_upsampled", "trimStart": 0.125 } ] }' ``` </details> Los tres ids son los clips escalados del Paso 5, en orden: la taza, el robot de escritorio, el teclado. <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 260px;max-width:320px;margin:0"> <video poster="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/10b-ugc-products-joined-29s-1080p-upscaled-concatenated-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/10b-ugc-products-joined-29s-1080p-upscaled-concatenated.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">Unido — 28,8 segundos, 1080p (0 créditos)</figcaption> </figure> </div> Termina un diálogo con las manos en la mesa, llega el corte y ella toma el siguiente objeto. El archivo unido se volvió a codificar a un tamaño menor para alojarlo, los tres clips están tal como los devolvió la API. ### Qué esperar * Genera, no edites. La publicación [UGC talking head](/blog/260902) (en inglés) extendió un clip con ediciones de video a video, y eso todavía funciona cuando los diálogos son cortos. Aquí no funcionó. Una edición mantiene el habla del clip de origen en la propia línea de tiempo del origen, así que con un diálogo de 10 segundos llenando el clip base, el nuevo diálogo se entrelazó con el anterior en lugar de reemplazarlo, y los productos que quedaban en la mesa cambiaron entre tomas. Generar cada clip desde la imagen fija dio diálogos completos, productos intactos y uniones más limpias, por menos créditos. * La imagen fija lleva las etiquetas. El modo de primer y último fotograma solo acepta las dos imágenes. Haz el etiquetado en la imagen fija, con el personaje y las fichas, y los clips lo heredan. * Marca los tiempos de la coreografía. Un clip de 10 segundos con un diálogo completo necesita que el momento de dejar el objeto se indique por reloj, "by the eight-second mark" (para el segundo ocho), y una pausa quieta y en silencio al final. Por su cuenta, el modelo alargaba el diálogo y saltaba al fotograma final. * Describe la voz igual en cada prompt. Nada lleva una voz de un clip a otro, y un personaje puede guardar un preset de voz, pero no llega a este modo. Con una descripción idéntica, los tres clips salieron lo bastante parecidos para pasar por una sola toma. * Las fichas necesitan cámara por panel. Indica qué muestra cada uno de los cuatro paneles. Dale a los objetos planos un panel cenital. Deja fuera manos, textos y logos, porque lo que esté en la ficha puede terminar en el clip. * Recorta según el sonido, no la imagen. Ella se queda quieta antes de terminar de hablar. Un corte en el primer fotograma quieto se llevó el final de un diálogo. * La presentadora es inventada. La moderación de Google es más estricta con personas reales e identificables. Empieza con un personaje generado. ### Cuánto costó | Paso | Modo | Créditos | |---|---|---| | Tres fichas de producto, 1:1 | Nano Banana 2 Lite | 0 | | Dos retratos de la presentadora, 3:4 | Nano Banana 2 Lite | 0 | | El personaje | — | 0 | | La imagen fija, 9:16 | Nano Banana 2 Lite, personaje + 3 referencias | 0 | | Clip 1, la taza, 10s | I2V, primer + último fotograma | 15 | | Clip 2, el robot de escritorio, 10s | I2V, primer + último fotograma | 15 | | Clip 3, el teclado, 10s | I2V, primer + último fotograma | 15 | | Escalado, tres clips a 1080p | — | 0 | | Concatenar | — | 0 | | Total | | 45 | Las imágenes, los personajes, el escalado a 1080p y la concatenación no cuestan nada, así que itera libremente las fichas, la presentadora y la imagen fija antes de gastar un crédito en video. El 4K es la única mejora con costo, 50 créditos por clip en Ultra. ### Ejecútalo tú mismo Cada paso de arriba es una llamada a la API, y los seis se encadenan en un script. El pipeline completo en Node.js, una versión en Python y el `prompts.json` con todos los prompts de esta página están en [`useapi/google-flow-api/ugc-product-video`](https://github.com/useapi/google-flow-api/tree/main/ugc-product-video). Clónalo, pon tus propios productos y diálogos en `prompts.json`, y un solo comando arma el video completo. Guarda un punto de control después de cada paso, así que una ejecución interrumpida se reanuda en lugar de volver a pagar los clips, y puedes rehacer un solo paso — una imagen fija mejor, otra presentadora — sin regenerar lo que vino antes. ### Preguntas frecuentes - **¿Puedo usar fotos de mi propio producto en lugar de fichas generadas?** Con useapi.net, sí. Súbelas con [POST /assets](/docs/api-google-flow-v1/post-google-flow-assets-email) y pasa los ids devueltos como `reference_1` a `reference_3` en la imagen fija, exactamente como se pasan aquí las fichas generadas. La ficha de cuatro paneles es una forma de darle al modelo todos los lados de un objeto, y un producto real se beneficia del mismo tratamiento. - **¿Por qué no editar un clip para convertirlo en el siguiente, como en la [publicación del talking head](/blog/260902) (en inglés)?** Con useapi.net se puede, pero una edición de video a video mantiene el habla del origen en la línea de tiempo del origen. Con diálogos cortos funciona. Con un diálogo de 10 segundos llenando el clip, el nuevo diálogo se entrelazó con el anterior y los productos de la mesa cambiaron. Generar cada clip desde la misma imagen fija evita ambas cosas y cuesta 15 créditos en lugar de 20. Consulta [Qué esperar](#what-to-expect). - **¿Por qué los tres clips empiezan y terminan en el mismo fotograma?** Con useapi.net, el modo de primer y último fotograma fija ambos extremos de cada clip a la misma imagen fija, así que los clips se unen en cualquier orden sin un corte visible, y la llamada de concatenación recorta las pausas cortas en cada unión. El mecanismo se explica en la publicación [UGC talking head](/blog/260902) (en inglés). - **¿La voz se mantiene igual entre los clips?** Con useapi.net, los tres clips salieron lo bastante parecidos para pasar por una sola toma, porque la voz se describió de forma idéntica en cada prompt. El modo de primer y último fotograma no acepta referencia de audio, y el preset de voz de un personaje no llega a él. Si necesitas una voz garantizada, el modo de referencia a video acepta `referenceAudio_1`, a costa de los fotogramas fijados. - **¿Cuánto cuesta?** Con useapi.net, este video completo de 29 segundos cuesta US$0,36 en Google AI Ultra US$199,99: 45 créditos de Flow para los tres clips Omni 1.1 Flash, con todas las imágenes, retratos, el personaje y la concatenación gratis. Los mismos 30 segundos de Omni 1.1 Flash a 720p cuestan unos US$3,04 en la [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) oficial (a noviembre de 2026). Consulta [Cuánto costó](#what-it-cost). ### Conclusión Visita nuestro <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> servidor de Discord</a> o nuestro <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> canal de Telegram</a> para cualquier pregunta de soporte. Consulta nuestro [repositorio de GitHub](https://github.com/useapi/google-flow-api) con ejemplos de código. #### Publicado también en {: .no_toc #cross-posted } También publicado en [dev.to](https://dev.to/useapi/how-to-make-a-ugc-product-video-with-the-google-flow-api-4nef){:rel="nofollow"} (en inglés). ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-flow-ugc-product-video-id === Document URL: https://useapi.net/docs/articles/google-flow-ugc-product-video-id --- layout: default title: "Cara Membuat Video UGC Produk dengan Google Flow API" description: "Buat video UGC produk berdurasi 29 detik lewat Google Flow API useapi.net: lembar produk dan presenter dari POST /images, satu still yang memuat semuanya, tiga klip Omni 1.1 Flash 10 detik dari still itu, upscale gratis ke 1080p, lalu POST /videos/concatenate untuk menggabungkannya." keywords: [UGC video, product video, Google Flow API, Omni 1.1 Flash, product sheets, character, first and last frame, concatenate, video UGC, video produk, iklan UGC, API video AI, frame awal dan frame akhir, menggabungkan video, lembar produk, tutorial bahasa Indonesia, kode, curl] image: https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/06-ugc-products-still-presenter-and-three-products-nano-banana-2-lite.png video: name: "UGC with the Google Flow API, the 75-second walkthrough" description: "The finished UGC product video, then how it was built: product sheets, a character, one still, three Omni 1.1 Flash clips and one concatenate call, through the useapi.net Google Flow API." url: https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/ugc-google-flow-api-1080p.mp4 embed: https://www.youtube.com/embed/wbUROtDIfGA thumbnail: https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/06-ugc-products-still-presenter-and-three-products-nano-banana-2-lite.png date: 2026-09-04 duration: PT1M15S width: 1080 height: 1920 parent: Articles nav_exclude: true lang: id translation_key: ugc-product-video date: 2026-09-04 last_modified: 2026-11-06 nav_order: 835 repo: https://github.com/useapi/google-flow-api --- ## Cara Membuat Video UGC Produk dengan Google Flow API {: .no_toc #how-to-make-a-ugc-product-video-with-the-google-flow-api } 8 menit baca • 4 September 2026 (6 November 2026) useapi.net adalah API pihak ketiga. Kami tidak berafiliasi dengan Google dan tidak disahkan oleh Google. ## Daftar isi {: .no_toc .text-delta #table-of-contents } ### Pendahuluan Video UGC produk bisa dibuat dari awal sampai akhir lewat [Google Flow API useapi.net](/docs/api-google-flow-v1) dengan 45 kredit Flow, tanpa ada yang diproses secara lokal. Seorang presenter rekaan memperlihatkan tiga produk rekaan ke kamera. UGC adalah gaya konten buatan pengguna yang memenuhi feed media sosial dan pustaka iklan: satu orang berbicara ke kamera ponsel, untuk menjual produk, menghibur, atau sekadar iseng. Ini panduan lengkap dari A sampai Z untuk membuat video seperti itu dengan kualitas profesional: produk, presenter, dialognya, dan hasil potongan akhir semuanya Anda kendalikan, dalam enam langkah panggilan API yang bisa disalin apa adanya. Lebih suka formulir tanpa kode? [Workflow iklan UGC di n8n](/docs/articles/google-flow-n8n-ugc-ads) (bahasa Inggris) membuat iklan seperti ini dengan halaman pilih atau buat ulang di setiap langkah. Ini hasilnya: tiga klip Omni 1.1 Flash 10 detik yang di-upscale ke 1080p, setiap frame dan setiap suara dibuat lewat [Google Flow API](/docs/api-google-flow-v1). Panggilan upscale yang sama bisa sampai 4K saat Anda butuh kualitas profesional, lihat [Langkah 5](#step-5-upscale-to-1080p): <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 260px;max-width:320px;margin:0"> <video poster="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/10b-ugc-products-joined-29s-1080p-upscaled-concatenated-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/10b-ugc-products-joined-29s-1080p-upscaled-concatenated.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">Hasilnya — 29 detik, 1080p, tiga produk, tiga klip (Total 45 kredit)</figcaption> </figure> </div> Kalau Anda lebih suka menonton daripada membaca, ini seluruh panduan dalam 75 detik (bahasa Inggris): <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 260px;max-width:320px;margin:0"> <div style="position:relative;width:100%;padding-top:177.78%;border-radius:8px;overflow:hidden"> <iframe src="https://www.youtube.com/embed/wbUROtDIfGA" title="UGC with the Google Flow API, the 75-second walkthrough" style="position:absolute;top:0;left:0;width:100%;height:100%;border:0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen loading="lazy"></iframe> </div> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">Panduan 75 detik (<a href="https://www.youtube.com/watch?v=wbUROtDIfGA" target="_blank" rel="noopener noreferrer">tonton di YouTube</a> · narasi dan musik dari <a href="/docs/api-minimax-v1">MiniMax API</a>)</figcaption> </figure> </div> ### Harga Video Omni 1.1 Flash butuh langganan Google AI berbayar (Plus, Pro, atau Ultra), dan useapi.net tidak menagih biaya per video. Biaya video ini langkah demi langkah ada di [Rincian biaya](#what-it-cost), dan harga per video di setiap paket, dibandingkan dengan API resmi, ada di [tabel harga Google Flow](/docs/api-google-flow-v1#pricing). ### Tentang id di dalam request Setiap request di bawah merujuk hasil sebelumnya lewat `mediaGenerationId`-nya. Id-nya panjang, jadi di sini disingkat menjadi `user:1234-email:…-image:b0bdf3e8-…`, dan satu baris di bawah setiap request menjelaskan id mana merujuk ke hasil sebelumnya yang mana. Id gambar didapat dari [POST /images](/docs/api-google-flow-v1/post-google-flow-images) di `media[0].image.generatedImage.mediaGenerationId`, id karakter di field `character` dari [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters), id video di `media[0].mediaGenerationId` dari [job](/docs/api-google-flow-v1/get-google-flow-jobs-jobid) yang sudah selesai, dan id klip hasil upscale adalah id sumbernya dengan `_upsampled` di akhir. ### Langkah 1: satu lembar untuk setiap produk Lembar produk adalah satu gambar yang memperlihatkan barang dari empat sisi, supaya model mendapat objek utuh, bukan satu sudut yang kebetulan bagus. [POST /images](/docs/api-google-flow-v1/post-google-flow-images), persegi, satu request per produk. Prompt-nya menjabarkan posisi kamera untuk setiap panel, karena "depan, samping, belakang" saja menghasilkan dua panel identik untuk mug dan tidak ada sisi samping yang sebenarnya untuk keyboard. Benda pipih seperti keyboard butuh panel tampak atas, benda berbentuk kubus tidak. Tanpa tangan, tanpa teks, tanpa logo, supaya tidak ada apa pun selain produk yang ikut masuk ke klip. Cara yang sama berlaku untuk produk sungguhan. Unggah fotonya dengan [POST /assets](/docs/api-google-flow-v1/post-google-flow-assets-email) lalu kirim id-nya sebagai `reference_1` sampai `reference_4` di request ini, dan model mengubahnya menjadi lembar empat panel yang rapi. Trik yang sama bisa membuat lembar untuk kemasan, logo, atau satu set produk. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a> (mug)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="1:1"' \ --form 'count="2"' \ --form 'prompt="Orthographic product-catalog sheet on a plain white background: a matte white ceramic mug with a straight cylindrical body and a clearly visible glowing amber light band around its base, about a finger wide, like a smart heated mug. The sheet is divided into four equal panels by thin grey lines in a 2 by 2 grid. Every panel shows the same single item at exactly the same size, position and lighting, camera at the item'\''s eye level unless stated: top-left: side profile, the handle pointing left and seen edge-on; top-right: view from the handle side, the handle pointing straight at the camera; bottom-left: view from the opposite side, the handle hidden behind the body; bottom-right: three-quarter view from slightly above, the handle to the right. Soft even studio light, photoreal. Object only: no hands, no people, no props, no text anywhere, no captions, no labels, no logo, no packaging."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/01-ugc-products-sheet-smart-mug-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/01-ugc-products-sheet-smart-mug-nano-banana-2-lite.png" alt="Lembar produk mug pintar, empat tampilan dalam grid 2 x 2" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">Mug — Nano Banana 2 Lite, id <code>b0bdf3e8</code> (0 kredit)</figcaption> </figure> </div> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a> (robot meja)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="1:1"' \ --form 'count="2"' \ --form 'prompt="Orthographic product-catalog sheet on a plain white background: a small rounded pastel mint desk robot, a palm-sized cube with a glossy black screen face showing a happy smiling expression, two round white eyes and a curved white smile, a little rounded antenna nub on top, a small round white dial on its right side, and a speaker grille on its back. The sheet is divided into four equal panels by thin grey lines in a 2 by 2 grid. Every panel shows the same single item at exactly the same size, position and lighting, camera at the item'\''s eye level unless stated: top-left: front view showing the smiling face; top-right: right side view showing the round dial and the antenna nub; bottom-left: back view showing the speaker grille; bottom-right: three-quarter view showing the smiling face and the dial. Soft even studio light, photoreal. Object only: no hands, no people, no props, no text anywhere, no captions, no labels, no logo, no packaging."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/02-ugc-products-sheet-desk-robot-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/02-ugc-products-sheet-desk-robot-nano-banana-2-lite.png" alt="Lembar produk robot meja, empat tampilan dalam grid 2 x 2" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">Robot meja — Nano Banana 2 Lite, id <code>7aaed056</code> (0 kredit)</figcaption> </figure> </div> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a> (keyboard)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="1:1"' \ --form 'count="4"' \ --form 'prompt="Orthographic product-catalog sheet on a plain white background: a real mechanical three-key macro pad, the kind sold for shortcuts: a slim, low-profile white aluminum case, three mechanical key switches in one row with sculpted dished keycaps and a small gap between them, coral on the left, lemon yellow in the middle, sky blue on the right, a USB-C port on the back edge. Exactly three keys in one row, never more. The sheet is divided into four equal panels by thin grey lines in a 2 by 2 grid. Every panel shows the same single item at exactly the same size, position and lighting, camera at the item'\''s eye level unless stated: top-left: top-down view straight from above, the three keys in a row left to right; top-right: front view at eye level; bottom-left: left side view at eye level, the slim case and the keycap profile seen edge-on; bottom-right: three-quarter view from above. Soft even studio light, photoreal. Object only: no hands, no people, no props, no text anywhere, no captions, no labels, no logo, no packaging."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/03-ugc-products-sheet-three-key-keyboard-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/03-ugc-products-sheet-three-key-keyboard-nano-banana-2-lite.png" alt="Lembar produk keyboard tiga tombol, empat tampilan dalam grid 2 x 2" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">Keyboard — Nano Banana 2 Lite, id <code>4f861c23</code> (0 kredit)</figcaption> </figure> </div> Gambar tidak dikenai biaya, jadi minta `count` 2 sampai 4 dan simpan lembar terbaik. Keyboard butuh beberapa putaran sampai prompt-nya menggambarkan macro pad sungguhan dengan panel tampak atas, sedangkan kubus langsung berhasil di percobaan pertama. ### Langkah 2: presenter Tiga panggilan. Potret depan dari sebuah deskripsi. Potret tiga perempat yang dibuat dari potret pertama dengan `reference_1`, supaya wajah keduanya sama. Lalu [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters) dengan kedua potret, yang mengembalikan referensi karakter. Sejak itu dia adalah `@character_1` di prompt mana pun, dan Google mengunci wujudnya lewat sistem entitasnya sendiri, bukan lewat deskripsi. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a> (potret depan)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="3:4"' \ --form 'count="2"' \ --form 'prompt="Character reference portrait, photoreal, natural skin, no heavy retouching: a strikingly attractive young woman in her early twenties with a sleek platinum-blonde blunt bob and straight bangs, dark defined eyebrows, icy grey eyes, a tiny silver nose stud, a playful smirk with a hint of teeth, wearing a fitted black turtleneck and a thin gold chain necklace. Head and shoulders, facing the camera straight on, plain light-grey studio background, soft even light. No text, no logo, no captions."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/04-ugc-products-presenter-front-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/04-ugc-products-presenter-front-nano-banana-2-lite.png" alt="Potret depan presenter" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">Depan — Nano Banana 2 Lite, id <code>a236ef66</code> (0 kredit)</figcaption> </figure> </div> Kami membuat beberapa tampilan dan memilih yang ini. Kalau nanti ada detail yang perlu diubah, misalnya kalungnya, buat ulang dia dengan potretnya sendiri sebagai `reference_1` dan prompt yang hanya menyebut perubahannya, dan wajahnya tetap sama. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a> (potret tiga perempat)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="3:4"' \ --form 'count="1"' \ --form 'reference_1="user:1234-email:…-image:a236ef66-…"' \ --form 'prompt="@reference_1 is the same woman: identical face, hair, freckles, sweater and earrings. Three-quarter view from the waist up, relaxed natural smile, plain light-grey studio background, soft even light. Photoreal, no text."' ``` </details> `reference_1` adalah potret depan, `a236ef66`. Prompt ini masih menyebut bintik-bintik wajah, sweter, dan anting sisa dari presenter sebelumnya, dan itu tidak berpengaruh: kalau request berisi gambar referensi, referensinya yang menang atas kata-kata. <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/05-ugc-products-presenter-three-quarter-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/05-ugc-products-presenter-three-quarter-nano-banana-2-lite.png" alt="Potret tiga perempat presenter, dibuat dari potret depan" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">Tiga perempat — id <code>d891301c</code> (0 kredit)</figcaption> </figure> </div> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-characters">POST /characters</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/characters' \ --header 'Authorization: Bearer user:1234-…' \ --form 'displayName="Mia"' \ --form 'personalityNotes="Quick, bright, deadpan delivery with a smile in her voice. Talks to the camera like a friend showing off things she bought at 2am."' \ --form 'imageReference_1="user:1234-email:…-image:a236ef66-…"' \ --form 'imageReference_2="user:1234-email:…-image:d891301c-…"' \ --form 'voice="Leda"' ``` </details> `imageReference_1` adalah potret depan `a236ef66`, `imageReference_2` potret tiga perempat `d891301c`. Field `character` di respons adalah id-nya, `53ca1036` di bawah. `voice` adalah salah satu preset suara sistem Google dan ikut tersimpan bersama karakter, tetapi tidak bisa sampai ke mode klip yang dipakai di Langkah 4, lihat [Yang perlu diketahui](#what-to-expect). ### Langkah 3: still, seluruh adegan dalam satu frame Satu request menyatukan semuanya. Karakter masuk sebagai `character_1`, ketiga lembar sebagai `reference_1` sampai `reference_3`, dan prompt menempatkannya berdasarkan tag, dari kiri ke kanan di meja di depannya. Frame ini menjadi kedua ujung setiap klip, jadi hanya di sinilah tag bekerja. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="9:16"' \ --form 'count="2"' \ --form 'character_1="user:1234-email:…-character:53ca1036-…"' \ --form 'reference_1="user:1234-email:…-image:b0bdf3e8-…"' \ --form 'reference_2="user:1234-email:…-image:7aaed056-…"' \ --form 'reference_3="user:1234-email:…-image:4f861c23-…"' \ --form 'prompt="Full-frame vertical phone video look, no phone, no bezel. @character_1 sits at a light wooden table in a bright minimal creator studio, facing the camera, waist-up and centered, a plain warm-grey backdrop behind her, soft key light from the left with a gentle catchlight in her eyes. Laid out on the table in front of her, left to right, each fully visible and resting flat on the table: the mug from @reference_1, the desk robot from @reference_2, the keyboard from @reference_3. Her hands rest on the table, relaxed closed-mouth smile, eyes on the lens. Photoreal, no text, no captions."' ``` </details> `character_1` adalah karakter dari Langkah 2, `53ca1036`. `reference_1` sampai `reference_3` adalah ketiga lembar dari Langkah 1: mug `b0bdf3e8`, robot meja `7aaed056`, keyboard `4f861c23`. <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/06-ugc-products-still-presenter-and-three-products-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/06-ugc-products-still-presenter-and-three-products-nano-banana-2-lite.png" alt="Presenter duduk di meja dengan mug, robot meja, dan keyboard tertata di depannya" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">Still — wajahnya dari karakter, tiap produk dari lembarnya, id <code>034cddc8</code> (0 kredit)</figcaption> </figure> </div> Mug punya cahayanya, robot punya wajah dan antenanya, keyboard punya tiga warna dan port-nya, dan dia adalah perempuan yang sama dengan di potret. ### Langkah 4: satu klip per produk, semuanya dari still Mode frame awal + frame akhir dari Omni dengan still di kedua slot, satu request per produk, [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) yang sama setiap kali. Mode ini hanya menerima kedua gambar itu, tanpa lembar produk, tanpa karakter, tanpa referensi suara. Tidak masalah, karena still sudah memuat semuanya. Setiap barang yang dia angkat keluar sesuai lembarnya hanya dari still saja. Prompt-nya punya tiga tugas. Mengunci kedua ujung ke frame itu, dengan jeda tenang di masing-masing sisi. Memberinya dialog dan suara. Dan mengatur waktu gerakannya: dia mulai bicara sambil mengangkat barang, barang sudah kembali ke tempatnya pada detik kedelapan, dan dua detik terakhir adalah jeda diam tanpa suara. Tanpa bagian terakhir itu, dia terlambat dan lengannya melompat ke frame akhir. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos">POST /videos</a> (mug)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'model="omni-flash"' \ --form 'aspectRatio="portrait"' \ --form 'duration="10"' \ --form 'resolution="720p"' \ --form 'startImage="user:1234-email:…-image:034cddc8-…"' \ --form 'endImage="user:1234-email:…-image:034cddc8-…"' \ --form 'prompt="She begins and ends exactly on this frame: hands resting on the table, the three items laid out in front of her, a small closed-mouth smile, looking into the lens, with a short quiet beat before she moves and another after she settles back. Timing matters: after a short quiet beat she picks up the mug on the left with both hands and starts talking as she lifts it, holding it up to the camera and talking straight to the lens, quick and bright with a deadpan edge and a smile in her voice, keeping both hands on the mug while she speaks. She says: \"Three gadgets smarter than me. Low bar. One: this mug texts me when my coffee'\''s cold. Better follow-up than my ex.\" Right after the last word she gives one short laugh to herself, still holding the mug. By the eight-second mark the mug is back down gently in exactly the same spot and both hands are resting on the table again, brought back in one calm unhurried movement. For the final two seconds she holds completely still, hands resting on the table, looking into the lens with a small closed-mouth smile. Natural room tone, no music, no captions, no text on screen."' ``` </details> `startImage` dan `endImage` sama-sama still dari Langkah 3, `034cddc8`. Kedua id yang sama dipakai di ketiga klip. <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 220px;max-width:260px;margin:0"> <video poster="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/07b-ugc-products-clip-1-smart-mug-10s-omni-1.1-flash-1080p-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/07b-ugc-products-clip-1-smart-mug-10s-omni-1.1-flash-1080p.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">Klip 1, mug — 10 detik, id <code>55808825</code>, ditampilkan setelah upscale ke 1080p di Langkah 5 (15 kredit)</figcaption> </figure> </div> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos">POST /videos</a> (robot meja)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'model="omni-flash"' \ --form 'aspectRatio="portrait"' \ --form 'duration="10"' \ --form 'resolution="720p"' \ --form 'startImage="user:1234-email:…-image:034cddc8-…"' \ --form 'endImage="user:1234-email:…-image:034cddc8-…"' \ --form 'prompt="She begins and ends exactly on this frame: hands resting on the table, the three items laid out in front of her, a small closed-mouth smile, looking into the lens, with a short quiet beat before she moves and another after she settles back. Timing matters: after a short quiet beat she picks up the desk robot in the middle with both hands and starts talking as she lifts it, holding it up to the camera with its smiling face toward the lens and turning it once and talking straight to the lens, quick and bright with a deadpan edge and a smile in her voice, keeping both hands on it while she speaks. The other two items stay on the table exactly where they are. She says: \"Two: a desk robot that reacts to my day. It has a face. It has never once looked impressed.\" Right after the last word she raises one eyebrow at the camera, a quick expressive beat, still holding the desk robot. By the eight-second mark the desk robot is back down gently in exactly the same spot and both hands are resting on the table again, brought back in one calm unhurried movement. For the final two seconds she is silent and holds completely still, hands resting on the table, looking into the lens with a small closed-mouth smile. Natural room tone, no music, no captions, no text on screen."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 220px;max-width:260px;margin:0"> <video poster="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/08b-ugc-products-clip-2-desk-robot-10s-omni-1.1-flash-1080p-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/08b-ugc-products-clip-2-desk-robot-10s-omni-1.1-flash-1080p.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">Klip 2, robot meja — 10 detik, id <code>c4d0e6b1</code>, ditampilkan setelah upscale ke 1080p di Langkah 5 (15 kredit)</figcaption> </figure> </div> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos">POST /videos</a> (keyboard)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'model="omni-flash"' \ --form 'aspectRatio="portrait"' \ --form 'duration="10"' \ --form 'resolution="720p"' \ --form 'startImage="user:1234-email:…-image:034cddc8-…"' \ --form 'endImage="user:1234-email:…-image:034cddc8-…"' \ --form 'prompt="She begins and ends exactly on this frame: hands resting on the table, the three items laid out in front of her, a small closed-mouth smile, looking into the lens, with a short quiet beat before she moves and another after she settles back. Timing matters: after a short quiet beat she picks up the keyboard on the right with both hands and starts talking as she lifts it, holding it up to the camera with the three keys facing the lens and talking straight to the lens, quick and bright with a deadpan edge and a smile in her voice, keeping both hands on it while she speaks. The other two items stay on the table exactly where they are. She says: \"Three: a keyboard with three keys. Copy, paste, undo. That'\''s my whole career. Oh, the mug'\''s texting. Bye!\" Right after the last word she raises one eyebrow at the camera, a quick expressive beat, still holding the keyboard. By the eight-second mark the keyboard is back down gently in exactly the same spot and both hands are resting on the table again, brought back in one calm unhurried movement. For the final two seconds she is silent and holds completely still, hands resting on the table, looking into the lens with a small closed-mouth smile. Natural room tone, no music, no captions, no text on screen."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 220px;max-width:260px;margin:0"> <video poster="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/09b-ugc-products-clip-3-three-key-keyboard-10s-omni-1.1-flash-1080p-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/09b-ugc-products-clip-3-three-key-keyboard-10s-omni-1.1-flash-1080p.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">Klip 3, keyboard — 10 detik, id <code>3cc8ea2f</code>, ditampilkan setelah upscale ke 1080p di Langkah 5 (15 kredit)</figcaption> </figure> </div> Perempuan yang sama, meja yang sama, cahaya yang sama, dan setiap klip dibuka dan ditutup pada still, jadi klip mana pun bisa menyusul klip lainnya. Dialognya sekitar 20 kata bahasa Inggris, yang pas untuk 10 detik pada tempo ini dengan sisa ruang untuk jeda di akhir. ### Langkah 5: upscale ke 1080p Omni 1.1 Flash merender di 720p. [POST /videos/upscale](/docs/api-google-flow-v1/post-google-flow-videos-upscale) menaikkan klip ke 1080p secara gratis di paket berbayar mana pun, dalam sekitar 40 detik, dan langsung menjawab di panggilan yang sama dengan id dan URL klip hasil upscale. Satu request per klip, tanpa `email`, akunnya ditentukan dari id. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos-upscale">POST /videos/upscale</a> (mug, lalu sama untuk dua lainnya)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos/upscale' \ --header 'Authorization: Bearer user:1234-…' \ --form 'mediaGenerationId="user:1234-email:…-video:55808825-…"' \ --form 'resolution="1080p"' ``` </details> `mediaGenerationId` adalah klip mug dari Langkah 4, `55808825`. Panggilan yang sama dengan `c4d0e6b1` dan `3cc8ea2f` meng-upscale robot dan keyboard. Setiap respons membawa klip baru di `media[0].mediaGenerationId`, yaitu id sumber dengan `_upsampled` di akhir, jadi ketiga id hasil upscale adalah `55808825-…_upsampled`, `c4d0e6b1-…_upsampled`, dan `3cc8ea2f-…_upsampled`. Klip yang ditampilkan di Langkah 4 adalah versi hasil upscale ini. 4K juga tersedia, seharga 50 kredit dan hanya di paket Google AI Ultra. ### Langkah 6: menggabungkannya [POST /videos/concatenate](/docs/api-google-flow-v1/post-google-flow-videos-concatenate) menerima ketiga id hasil upscale secara berurutan dan mengembalikan file gabungan sebagai base64, dengan resolusi klip. Pemangkasan menentukan apakah sambungannya terasa seperti satu take. Setiap klip dibuka dengan jeda singkat pada still dan ditutup dengan kembali ke still, dan tanpa dipangkas jeda-jeda itu menumpuk menjadi frame beku di setiap potongan. Tetapi dia menyelesaikan setiap kalimat dengan tangan yang sudah diam di meja, jadi pemangkasan yang hanya diukur dari gambar akan memotong kata-kata terakhirnya. Potong setelah suara terakhir ditambah satu ketukan, jangan lebih awal. Untuk klip-klip ini artinya klip 1 dibiarkan utuh karena tawanya berlangsung sampai frame terakhir, ujung klip 2 dipangkas sedikit lebih dari setengah detik, dan awal klip 2 dan 3 dipangkas beberapa frame. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos-concatenate">POST /videos/concatenate</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos/concatenate' \ --header 'Authorization: Bearer user:1234-…' \ --header 'Content-Type: application/json' \ --data '{ "media": [ { "mediaGenerationId": "user:1234-email:…-video:55808825-…_upsampled" }, { "mediaGenerationId": "user:1234-email:…-video:c4d0e6b1-…_upsampled", "trimStart": 0.458, "trimEnd": 0.6 }, { "mediaGenerationId": "user:1234-email:…-video:3cc8ea2f-…_upsampled", "trimStart": 0.125 } ] }' ``` </details> Ketiga id adalah klip hasil upscale dari Langkah 5 secara berurutan: mug, robot meja, keyboard. <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 260px;max-width:320px;margin:0"> <video poster="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/10b-ugc-products-joined-29s-1080p-upscaled-concatenated-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/10b-ugc-products-joined-29s-1080p-upscaled-concatenated.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">Gabungan — 28,8 detik, 1080p (0 kredit)</figcaption> </figure> </div> Dia menyelesaikan kalimat dengan tangan di meja, potongan masuk, dan dia meraih barang berikutnya. File gabungan di-encode ulang ke ukuran lebih kecil untuk hosting, sedangkan ketiga klip dibiarkan seperti yang dikembalikan API. ### Yang perlu diketahui * Buat baru, jangan edit. Postingan [UGC talking head](/blog/260902) (bahasa Inggris) memperpanjang klip dengan edit video ke video, dan itu masih berhasil kalau dialognya pendek. Di sini tidak. Edit mempertahankan ucapan sumbernya di timeline sumber itu sendiri, jadi dengan dialog 10 detik yang memenuhi klip awal, kalimat baru terjalin dengan kalimat lama alih-alih menggantikannya, dan produk yang tertinggal di meja berubah bentuk antar-take. Membuat setiap klip dari still menghasilkan dialog utuh, produk yang tetap utuh, dan sambungan yang lebih bersih, dengan kredit lebih sedikit. * Still membawa tag-nya. Mode frame awal + frame akhir hanya menerima dua gambar itu. Lakukan penandaan di still, dengan karakter dan lembar produk, dan klip mewarisinya. * Atur waktu gerakannya. Klip 10 detik dengan dialog penuh perlu momen meletakkan barang disebut berdasarkan jam, "by the eight-second mark" (paling lambat detik kedelapan), dan jeda diam tanpa suara di akhir. Dibiarkan sendiri, model memperpanjang dialog lalu melompat ke frame akhir. * Deskripsikan suara dengan cara yang sama di setiap prompt. Tidak ada yang membawa suara dari satu klip ke klip lain, dan karakter bisa menyimpan preset suara tetapi tidak bisa sampai ke mode ini. Dengan deskripsi yang identik, ketiga klip keluar cukup mirip untuk lolos sebagai satu take. * Lembar produk butuh posisi kamera per panel. Sebutkan apa yang ditampilkan setiap panel dari keempatnya. Beri benda pipih panel tampak atas. Jangan masukkan tangan, teks, dan logo, karena apa pun yang ada di lembar bisa muncul di klip. * Pangkas berdasarkan suara, bukan gambar. Dia sudah diam sebelum selesai bicara. Potongan di frame diam pertama ikut memotong akhir kalimat. * Presenternya rekaan. Moderasi Google lebih ketat terhadap orang sungguhan yang bisa dikenali. Mulailah dari karakter buatan. ### Rincian biaya | Langkah | Mode | Kredit | |---|---|---| | Tiga lembar produk, 1:1 | Nano Banana 2 Lite | 0 | | Dua potret presenter, 3:4 | Nano Banana 2 Lite | 0 | | Karakter | — | 0 | | Still, 9:16 | Nano Banana 2 Lite, karakter + 3 referensi | 0 | | Klip 1, mug, 10s | I2V, frame awal + akhir | 15 | | Klip 2, robot meja, 10s | I2V, frame awal + akhir | 15 | | Klip 3, keyboard, 10s | I2V, frame awal + akhir | 15 | | Upscale, tiga klip ke 1080p | — | 0 | | Gabungkan | — | 0 | | Total | | 45 | Gambar, karakter, upscale ke 1080p, dan penggabungan tidak dikenai biaya, jadi ulangi sesuka hati lembar produk, presenter, dan still sebelum menghabiskan satu kredit pun untuk video. 4K adalah satu-satunya peningkatan yang berbayar, 50 kredit per klip di Ultra. ### Jalankan sendiri Setiap langkah di atas adalah satu panggilan API, dan keenamnya bisa dirangkai menjadi satu skrip. Pipeline Node.js lengkap, versi Python, dan `prompts.json` yang berisi semua prompt di halaman ini ada di [`useapi/google-flow-api/ugc-product-video`](https://github.com/useapi/google-flow-api/tree/main/ugc-product-video). Clone, masukkan produk dan dialog Anda sendiri ke `prompts.json`, dan satu perintah membangun seluruh video. Skripnya menyimpan checkpoint setelah setiap langkah, jadi proses yang terputus bisa dilanjutkan tanpa membayar klip lagi, dan Anda bisa mengulang satu langkah saja — still yang lebih bagus, presenter lain — tanpa membuat ulang yang sudah ada sebelumnya. ### Pertanyaan yang sering diajukan - **Bisakah saya memakai foto produk sendiri, bukan lembar yang dibuat?** Lewat useapi.net, bisa. Unggah fotonya dengan [POST /assets](/docs/api-google-flow-v1/post-google-flow-assets-email) dan kirim id yang dikembalikan sebagai `reference_1` sampai `reference_3` pada still, persis seperti lembar buatan dikirim di sini. Lembar empat panel adalah cara memberi model setiap sisi sebuah objek, dan produk sungguhan juga diuntungkan dengan perlakuan yang sama. - **Kenapa tidak mengedit satu klip menjadi klip berikutnya, seperti di [postingan talking head](/blog/260902) (bahasa Inggris)?** Lewat useapi.net bisa saja, tetapi edit video ke video mempertahankan ucapan sumbernya di timeline sumber. Dengan dialog pendek, itu berhasil. Dengan dialog 10 detik yang memenuhi klip, kalimat baru terjalin dengan yang lama dan produk di meja berubah bentuk. Membuat setiap klip dari still yang sama menghindari keduanya, dan biayanya 15 kredit, bukan 20. Lihat [Yang perlu diketahui](#what-to-expect). - **Kenapa ketiga klip dimulai dan diakhiri pada frame yang sama?** Lewat useapi.net, mode frame awal + frame akhir mengunci kedua ujung setiap klip ke still yang sama, jadi klip-klipnya tersambung dalam urutan apa pun tanpa potongan yang terlihat, dan panggilan penggabungan memangkas jeda singkat di setiap sambungan. Mekanismenya dijelaskan di postingan [UGC talking head](/blog/260902) (bahasa Inggris). - **Apakah suaranya tetap sama di semua klip?** Lewat useapi.net, ketiga klip keluar cukup mirip untuk lolos sebagai satu take, karena suaranya dideskripsikan secara identik di setiap prompt. Mode frame awal + frame akhir tidak menerima referensi audio, dan preset suara karakter tidak bisa sampai ke mode itu. Kalau Anda butuh suara yang pasti sama, mode referensi ke video menerima `referenceAudio_1`, dengan konsekuensi kehilangan frame yang dikunci. - **Berapa biayanya?** Lewat useapi.net, seluruh video 29 detik ini hanya $0,36 di Google AI Ultra $199,99: 45 kredit Flow untuk tiga klip Omni 1.1 Flash, dengan semua gambar, potret, karakter, dan penggabungan gratis. 30 detik Omni 1.1 Flash 720p yang sama sekitar $3,04 di [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) resmi (per November 2026). Lihat [Rincian biaya](#what-it-cost). ### Kesimpulan Kunjungi <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Server Discord</a> atau <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Channel Telegram</a> kami untuk pertanyaan dan masalah dukungan. Lihat [repo GitHub](https://github.com/useapi/google-flow-api) kami berisi contoh kode. #### Dipublikasikan juga di {: .no_toc #cross-posted } Juga dipublikasikan di [dev.to](https://dev.to/useapi/how-to-make-a-ugc-product-video-with-the-google-flow-api-4nef){:rel="nofollow"} (bahasa Inggris). ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-flow-ugc-product-video-ja === Document URL: https://useapi.net/docs/articles/google-flow-ugc-product-video-ja --- layout: default title: "Google Flow API で UGC 風の商品紹介動画を作る方法" description: "useapi.net の Google Flow API で29秒の UGC 風商品紹介動画を作る方法。POST /images で商品シートと出演者を作り、すべてを収めた1枚の静止画から10秒の Omni 1.1 Flash クリップを3本生成し、無料で1080p にアップスケールして POST /videos/concatenate でつなぎます。" keywords: [UGC video, product video, Google Flow API, Omni 1.1 Flash, product sheets, character, first and last frame, concatenate, UGC 動画, 商品紹介動画, 動画広告, AI 動画 API, 開始フレームと終了フレーム, 動画の結合, 商品シート, 日本語チュートリアル, Japanese tutorial] image: https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/06-ugc-products-still-presenter-and-three-products-nano-banana-2-lite.png video: name: "UGC with the Google Flow API, the 75-second walkthrough" description: "The finished UGC product video, then how it was built: product sheets, a character, one still, three Omni 1.1 Flash clips and one concatenate call, through the useapi.net Google Flow API." url: https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/ugc-google-flow-api-1080p.mp4 embed: https://www.youtube.com/embed/wbUROtDIfGA thumbnail: https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/06-ugc-products-still-presenter-and-three-products-nano-banana-2-lite.png date: 2026-09-04 duration: PT1M15S width: 1080 height: 1920 parent: Articles nav_exclude: true lang: ja translation_key: ugc-product-video date: 2026-09-04 last_modified: 2026-11-06 nav_order: 835 repo: https://github.com/useapi/google-flow-api --- ## Google Flow API で UGC 風の商品紹介動画を作る方法 {: .no_toc #how-to-make-a-ugc-product-video-with-the-google-flow-api } 8分で読めます • 2026年9月4日(2026年11月6日更新) useapi.net はサードパーティの API です。Google とは提携しておらず、Google の承認も受けていません。 ## 目次 {: .no_toc .text-delta #table-of-contents } ### はじめに UGC 風の商品紹介動画は、[useapi.net の Google Flow API](/docs/api-google-flow-v1) だけで最初から最後まで作れます。かかるのは Flow クレジット45だけで、ローカルでの処理は一切ありません。架空の出演者が、架空の商品3つをカメラに向かって紹介します。 UGC(ユーザー生成コンテンツ)は、SNS のフィードや広告ライブラリにあふれているスタイルです。1人がスマートフォンのカメラに向かって話し、商品を売り込んだり、笑わせたり、ただ楽しんだりします。 これは、そうした動画をプロ品質で作るための A から Z までの完全ガイドです。商品、出演者、セリフ、最終的な編集まですべて自分で決められ、API 呼び出しは6ステップで、そのままコピーして使えます。ノーコードのフォームがよければ、[n8n の UGC 広告ワークフロー](/docs/articles/google-flow-n8n-ugc-ads)(英語)でもこの種の広告を作れます。各ステップで選び直しや再生成ができるページ付きです。 完成した動画がこちらです。10秒の Omni 1.1 Flash クリップ3本を1080p にアップスケールしたもので、映像も音もすべて [Google Flow API](/docs/api-google-flow-v1) で生成しています。プロ品質が必要なら、同じアップスケールの呼び出しで4K にもできます。[ステップ5](#step-5-upscale-to-1080p)をご覧ください。 <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 260px;max-width:320px;margin:0"> <video poster="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/10b-ugc-products-joined-29s-1080p-upscaled-concatenated-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/10b-ugc-products-joined-29s-1080p-upscaled-concatenated.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">完成品:29秒、1080p、商品3つ、クリップ3本 (合計45クレジット)</figcaption> </figure> </div> 読むより見るほうがよければ、ガイド全体を75秒にまとめた動画(英語)もあります。 <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 260px;max-width:320px;margin:0"> <div style="position:relative;width:100%;padding-top:177.78%;border-radius:8px;overflow:hidden"> <iframe src="https://www.youtube.com/embed/wbUROtDIfGA" title="UGC with the Google Flow API, the 75-second walkthrough" style="position:absolute;top:0;left:0;width:100%;height:100%;border:0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen loading="lazy"></iframe> </div> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">75秒の解説動画 (<a href="https://www.youtube.com/watch?v=wbUROtDIfGA" target="_blank" rel="noopener noreferrer">YouTube で見る</a> · ナレーションと音楽は <a href="/docs/api-minimax-v1">MiniMax API</a> で作成)</figcaption> </figure> </div> ### 料金 Omni 1.1 Flash の動画には有料の Google AI のプラン(Plus、Pro、Ultra)が必要で、useapi.net は動画ごとの料金を取りません。この動画にかかった費用はステップごとに[かかった費用](#what-it-cost)にまとめています。各プランでの動画1本あたりの価格と公式 API との比較は、[Google Flow の料金表](/docs/api-google-flow-v1#pricing)をご覧ください。 ### リクエスト内の ID について 以下のリクエストはすべて、前のステップの結果をその `mediaGenerationId` で参照します。ID は長いので、ここでは `user:1234-email:…-image:b0bdf3e8-…` のように短縮し、各リクエストの下に、どの ID が前のどの結果なのかを1行で書いています。画像の ID は [POST /images](/docs/api-google-flow-v1/post-google-flow-images) のレスポンスの `media[0].image.generatedImage.mediaGenerationId`、キャラクターの ID は [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters) の `character` フィールド、動画の ID は完了した [ジョブ](/docs/api-google-flow-v1/get-google-flow-jobs-jobid) の `media[0].mediaGenerationId` にあります。アップスケールしたクリップの ID は、元の ID の末尾に `_upsampled` を付けたものです。 ### ステップ1:商品ごとのシート 商品シートとは、1つの商品を4つの方向から見せる1枚の画像です。たまたまうまくいった1つの角度ではなく、商品全体をモデルに伝えられます。[POST /images](/docs/api-google-flow-v1/post-google-flow-images) を正方形で、商品ごとに1リクエスト送ります。プロンプトではパネルごとにカメラの位置を書いています。「正面、側面、背面」とだけ書くと、マグでは同じパネルが2つでき、キーボードには本当の側面図ができなかったからです。キーボードのような平たい物には真上からのパネルが必要で、立方体の物には要りません。手、キャプション、ロゴは入れません。そうすれば、商品以外のものがクリップに紛れ込むことはありません。 実在の商品でも同じことができます。[POST /assets](/docs/api-google-flow-v1/post-google-flow-assets-email) で商品の写真をアップロードし、その ID をこのリクエストの `reference_1`〜`reference_4` に渡すと、モデルがきれいな4面のシートにまとめます。パッケージ、ロゴ、セット商品のシートも同じ方法で作れます。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a>(マグ)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="1:1"' \ --form 'count="2"' \ --form 'prompt="Orthographic product-catalog sheet on a plain white background: a matte white ceramic mug with a straight cylindrical body and a clearly visible glowing amber light band around its base, about a finger wide, like a smart heated mug. The sheet is divided into four equal panels by thin grey lines in a 2 by 2 grid. Every panel shows the same single item at exactly the same size, position and lighting, camera at the item'\''s eye level unless stated: top-left: side profile, the handle pointing left and seen edge-on; top-right: view from the handle side, the handle pointing straight at the camera; bottom-left: view from the opposite side, the handle hidden behind the body; bottom-right: three-quarter view from slightly above, the handle to the right. Soft even studio light, photoreal. Object only: no hands, no people, no props, no text anywhere, no captions, no labels, no logo, no packaging."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/01-ugc-products-sheet-smart-mug-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/01-ugc-products-sheet-smart-mug-nano-banana-2-lite.png" alt="スマートマグの商品シート、2×2 のグリッドに4つのビュー" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">マグ — Nano Banana 2 Lite、ID <code>b0bdf3e8</code> (0クレジット)</figcaption> </figure> </div> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a>(デスクロボット)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="1:1"' \ --form 'count="2"' \ --form 'prompt="Orthographic product-catalog sheet on a plain white background: a small rounded pastel mint desk robot, a palm-sized cube with a glossy black screen face showing a happy smiling expression, two round white eyes and a curved white smile, a little rounded antenna nub on top, a small round white dial on its right side, and a speaker grille on its back. The sheet is divided into four equal panels by thin grey lines in a 2 by 2 grid. Every panel shows the same single item at exactly the same size, position and lighting, camera at the item'\''s eye level unless stated: top-left: front view showing the smiling face; top-right: right side view showing the round dial and the antenna nub; bottom-left: back view showing the speaker grille; bottom-right: three-quarter view showing the smiling face and the dial. Soft even studio light, photoreal. Object only: no hands, no people, no props, no text anywhere, no captions, no labels, no logo, no packaging."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/02-ugc-products-sheet-desk-robot-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/02-ugc-products-sheet-desk-robot-nano-banana-2-lite.png" alt="デスクロボットの商品シート、2×2 のグリッドに4つのビュー" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">デスクロボット — Nano Banana 2 Lite、ID <code>7aaed056</code> (0クレジット)</figcaption> </figure> </div> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a>(キーボード)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="1:1"' \ --form 'count="4"' \ --form 'prompt="Orthographic product-catalog sheet on a plain white background: a real mechanical three-key macro pad, the kind sold for shortcuts: a slim, low-profile white aluminum case, three mechanical key switches in one row with sculpted dished keycaps and a small gap between them, coral on the left, lemon yellow in the middle, sky blue on the right, a USB-C port on the back edge. Exactly three keys in one row, never more. The sheet is divided into four equal panels by thin grey lines in a 2 by 2 grid. Every panel shows the same single item at exactly the same size, position and lighting, camera at the item'\''s eye level unless stated: top-left: top-down view straight from above, the three keys in a row left to right; top-right: front view at eye level; bottom-left: left side view at eye level, the slim case and the keycap profile seen edge-on; bottom-right: three-quarter view from above. Soft even studio light, photoreal. Object only: no hands, no people, no props, no text anywhere, no captions, no labels, no logo, no packaging."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/03-ugc-products-sheet-three-key-keyboard-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/03-ugc-products-sheet-three-key-keyboard-nano-banana-2-lite.png" alt="3キーのキーボードの商品シート、2×2 のグリッドに4つのビュー" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">キーボード — Nano Banana 2 Lite、ID <code>4f861c23</code> (0クレジット)</figcaption> </figure> </div> 画像は無料なので、`count` を2〜4にして一番よいシートを選びましょう。キーボードは、プロンプトが実在のマクロパッドと真上からのパネルを描写できるまで何度か試しました。立方体のロボットは一発でうまくいきました。 ### ステップ2:出演者 呼び出しは3回です。まず説明文から正面のポートレートを作ります。次に、1枚目を `reference_1` にして斜め45度のポートレートを作り、2枚の顔をそろえます。最後に2枚のポートレートで [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters) を呼ぶと、キャラクターの参照が返ります。以後、どのプロンプトでも彼女は `@character_1` になり、Google は説明文ではなく自社のエンティティの仕組みで彼女を固定します。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a>(正面のポートレート)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="3:4"' \ --form 'count="2"' \ --form 'prompt="Character reference portrait, photoreal, natural skin, no heavy retouching: a strikingly attractive young woman in her early twenties with a sleek platinum-blonde blunt bob and straight bangs, dark defined eyebrows, icy grey eyes, a tiny silver nose stud, a playful smirk with a hint of teeth, wearing a fitted black turtleneck and a thin gold chain necklace. Head and shoulders, facing the camera straight on, plain light-grey studio background, soft even light. No text, no logo, no captions."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/04-ugc-products-presenter-front-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/04-ugc-products-presenter-front-nano-banana-2-lite.png" alt="出演者の正面のポートレート" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">正面 — Nano Banana 2 Lite、ID <code>a236ef66</code> (0クレジット)</figcaption> </figure> </div> いくつかのルックを生成して、これを選びました。あとで細部を変えたくなったら(たとえばネックレス)、本人のポートレートを `reference_1` にし、変更点だけを書いたプロンプトで作り直せば、顔はそのまま保たれます。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a>(斜め45度のポートレート)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="3:4"' \ --form 'count="1"' \ --form 'reference_1="user:1234-email:…-image:a236ef66-…"' \ --form 'prompt="@reference_1 is the same woman: identical face, hair, freckles, sweater and earrings. Three-quarter view from the waist up, relaxed natural smile, plain light-grey studio background, soft even light. Photoreal, no text."' ``` </details> `reference_1` は正面のポートレート `a236ef66` です。このプロンプトには、以前の出演者の名残でそばかす、セーター、イヤリングが書かれたままですが、問題はありませんでした。リクエストに参照画像があれば、文章より参照画像が優先されます。 <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/05-ugc-products-presenter-three-quarter-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/05-ugc-products-presenter-three-quarter-nano-banana-2-lite.png" alt="正面のポートレートから生成した、出演者の斜め45度のポートレート" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">斜め45度 — ID <code>d891301c</code> (0クレジット)</figcaption> </figure> </div> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-characters">POST /characters</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/characters' \ --header 'Authorization: Bearer user:1234-…' \ --form 'displayName="Mia"' \ --form 'personalityNotes="Quick, bright, deadpan delivery with a smile in her voice. Talks to the camera like a friend showing off things she bought at 2am."' \ --form 'imageReference_1="user:1234-email:…-image:a236ef66-…"' \ --form 'imageReference_2="user:1234-email:…-image:d891301c-…"' \ --form 'voice="Leda"' ``` </details> `imageReference_1` は正面のポートレート `a236ef66`、`imageReference_2` は斜め45度の `d891301c` です。レスポンスの `character` フィールドが彼女の ID で、以下では `53ca1036` です。`voice` は Google のシステムプリセットの声の1つで、キャラクターと一緒に保存されますが、ステップ4で使うクリップのモードには届きません。[注意点](#what-to-expect)をご覧ください。 ### ステップ3:静止画、1フレームにシーン全体を 1つのリクエストですべてをまとめます。キャラクターを `character_1`、3枚のシートを `reference_1`〜`reference_3` として渡し、プロンプトでタグを使って、彼女の前のテーブルに左から右へ並べます。このフレームがすべてのクリップの最初と最後になるので、タグが働くのはここだけです。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="9:16"' \ --form 'count="2"' \ --form 'character_1="user:1234-email:…-character:53ca1036-…"' \ --form 'reference_1="user:1234-email:…-image:b0bdf3e8-…"' \ --form 'reference_2="user:1234-email:…-image:7aaed056-…"' \ --form 'reference_3="user:1234-email:…-image:4f861c23-…"' \ --form 'prompt="Full-frame vertical phone video look, no phone, no bezel. @character_1 sits at a light wooden table in a bright minimal creator studio, facing the camera, waist-up and centered, a plain warm-grey backdrop behind her, soft key light from the left with a gentle catchlight in her eyes. Laid out on the table in front of her, left to right, each fully visible and resting flat on the table: the mug from @reference_1, the desk robot from @reference_2, the keyboard from @reference_3. Her hands rest on the table, relaxed closed-mouth smile, eyes on the lens. Photoreal, no text, no captions."' ``` </details> `character_1` はステップ2のキャラクター `53ca1036` です。`reference_1`〜`reference_3` はステップ1の3枚のシートで、マグ `b0bdf3e8`、デスクロボット `7aaed056`、キーボード `4f861c23` です。 <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/06-ugc-products-still-presenter-and-three-products-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/06-ugc-products-still-presenter-and-three-products-nano-banana-2-lite.png" alt="テーブルについた出演者と、その前に並んだマグ、デスクロボット、キーボード" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">静止画 — 顔はキャラクターから、各商品はそのシートから、ID <code>034cddc8</code> (0クレジット)</figcaption> </figure> </div> マグには光る帯、ロボットには顔とアンテナ、キーボードには3つの色とポートがあり、彼女はポートレートと同じ女性です。 ### ステップ4:商品ごとに1クリップ、すべて静止画から Omni の開始フレーム+終了フレームのモードで、両方に静止画を入れ、商品ごとに1リクエスト、毎回同じ [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) を送ります。このモードが受け取るのは2枚の画像だけで、シートもキャラクターも声の参照も入れられません。それで問題ありません。静止画にすべてが入っているからです。彼女が手に取った商品は、静止画だけでどれもシートどおりに再現されました。 プロンプトには3つの役割があります。両端をこのフレームに固定し、前後に静かな間を置くこと。セリフと声を与えること。そして動きのタイミングを決めることです。商品を持ち上げながら話し始め、8秒の時点で商品は元の位置に戻り、最後の2秒は動かず無音で止まります。この最後の部分がないと、彼女の動きが遅れ、腕が終了フレームへ急に飛びました。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos">POST /videos</a>(マグ)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'model="omni-flash"' \ --form 'aspectRatio="portrait"' \ --form 'duration="10"' \ --form 'resolution="720p"' \ --form 'startImage="user:1234-email:…-image:034cddc8-…"' \ --form 'endImage="user:1234-email:…-image:034cddc8-…"' \ --form 'prompt="She begins and ends exactly on this frame: hands resting on the table, the three items laid out in front of her, a small closed-mouth smile, looking into the lens, with a short quiet beat before she moves and another after she settles back. Timing matters: after a short quiet beat she picks up the mug on the left with both hands and starts talking as she lifts it, holding it up to the camera and talking straight to the lens, quick and bright with a deadpan edge and a smile in her voice, keeping both hands on the mug while she speaks. She says: \"Three gadgets smarter than me. Low bar. One: this mug texts me when my coffee'\''s cold. Better follow-up than my ex.\" Right after the last word she gives one short laugh to herself, still holding the mug. By the eight-second mark the mug is back down gently in exactly the same spot and both hands are resting on the table again, brought back in one calm unhurried movement. For the final two seconds she holds completely still, hands resting on the table, looking into the lens with a small closed-mouth smile. Natural room tone, no music, no captions, no text on screen."' ``` </details> `startImage` と `endImage` はどちらもステップ3の静止画 `034cddc8` です。3本のクリップすべてに同じ2つの ID を使います。 <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 220px;max-width:260px;margin:0"> <video poster="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/07b-ugc-products-clip-1-smart-mug-10s-omni-1.1-flash-1080p-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/07b-ugc-products-clip-1-smart-mug-10s-omni-1.1-flash-1080p.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">クリップ1、マグ — 10秒、ID <code>55808825</code>、ステップ5で1080p にアップスケールしたもの (15クレジット)</figcaption> </figure> </div> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos">POST /videos</a>(デスクロボット)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'model="omni-flash"' \ --form 'aspectRatio="portrait"' \ --form 'duration="10"' \ --form 'resolution="720p"' \ --form 'startImage="user:1234-email:…-image:034cddc8-…"' \ --form 'endImage="user:1234-email:…-image:034cddc8-…"' \ --form 'prompt="She begins and ends exactly on this frame: hands resting on the table, the three items laid out in front of her, a small closed-mouth smile, looking into the lens, with a short quiet beat before she moves and another after she settles back. Timing matters: after a short quiet beat she picks up the desk robot in the middle with both hands and starts talking as she lifts it, holding it up to the camera with its smiling face toward the lens and turning it once and talking straight to the lens, quick and bright with a deadpan edge and a smile in her voice, keeping both hands on it while she speaks. The other two items stay on the table exactly where they are. She says: \"Two: a desk robot that reacts to my day. It has a face. It has never once looked impressed.\" Right after the last word she raises one eyebrow at the camera, a quick expressive beat, still holding the desk robot. By the eight-second mark the desk robot is back down gently in exactly the same spot and both hands are resting on the table again, brought back in one calm unhurried movement. For the final two seconds she is silent and holds completely still, hands resting on the table, looking into the lens with a small closed-mouth smile. Natural room tone, no music, no captions, no text on screen."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 220px;max-width:260px;margin:0"> <video poster="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/08b-ugc-products-clip-2-desk-robot-10s-omni-1.1-flash-1080p-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/08b-ugc-products-clip-2-desk-robot-10s-omni-1.1-flash-1080p.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">クリップ2、デスクロボット — 10秒、ID <code>c4d0e6b1</code>、ステップ5で1080p にアップスケールしたもの (15クレジット)</figcaption> </figure> </div> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos">POST /videos</a>(キーボード)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'model="omni-flash"' \ --form 'aspectRatio="portrait"' \ --form 'duration="10"' \ --form 'resolution="720p"' \ --form 'startImage="user:1234-email:…-image:034cddc8-…"' \ --form 'endImage="user:1234-email:…-image:034cddc8-…"' \ --form 'prompt="She begins and ends exactly on this frame: hands resting on the table, the three items laid out in front of her, a small closed-mouth smile, looking into the lens, with a short quiet beat before she moves and another after she settles back. Timing matters: after a short quiet beat she picks up the keyboard on the right with both hands and starts talking as she lifts it, holding it up to the camera with the three keys facing the lens and talking straight to the lens, quick and bright with a deadpan edge and a smile in her voice, keeping both hands on it while she speaks. The other two items stay on the table exactly where they are. She says: \"Three: a keyboard with three keys. Copy, paste, undo. That'\''s my whole career. Oh, the mug'\''s texting. Bye!\" Right after the last word she raises one eyebrow at the camera, a quick expressive beat, still holding the keyboard. By the eight-second mark the keyboard is back down gently in exactly the same spot and both hands are resting on the table again, brought back in one calm unhurried movement. For the final two seconds she is silent and holds completely still, hands resting on the table, looking into the lens with a small closed-mouth smile. Natural room tone, no music, no captions, no text on screen."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 220px;max-width:260px;margin:0"> <video poster="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/09b-ugc-products-clip-3-three-key-keyboard-10s-omni-1.1-flash-1080p-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/09b-ugc-products-clip-3-three-key-keyboard-10s-omni-1.1-flash-1080p.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">クリップ3、キーボード — 10秒、ID <code>3cc8ea2f</code>、ステップ5で1080p にアップスケールしたもの (15クレジット)</figcaption> </figure> </div> 同じ女性、同じテーブル、同じ照明で、どのクリップも静止画で始まり静止画で終わるので、どの順番でもつなげられます。セリフは英語で約20語です。このテンポだと10秒にちょうど収まり、最後の間も取れます。 ### ステップ5:1080p にアップスケール Omni 1.1 Flash は720p で出力されます。[POST /videos/upscale](/docs/api-google-flow-v1/post-google-flow-videos-upscale) を使うと、どの有料プランでもクリップを無料で1080p にでき、約40秒で終わります。アップスケールしたクリップの ID と URL は同じ呼び出しで返ります。クリップごとに1リクエストで、`email` は不要です。アカウントは ID から決まります。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos-upscale">POST /videos/upscale</a>(マグ、残り2本も同様)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos/upscale' \ --header 'Authorization: Bearer user:1234-…' \ --form 'mediaGenerationId="user:1234-email:…-video:55808825-…"' \ --form 'resolution="1080p"' ``` </details> `mediaGenerationId` はステップ4のマグのクリップ `55808825` です。同じ呼び出しを `c4d0e6b1` と `3cc8ea2f` で行えば、ロボットとキーボードもアップスケールされます。各レスポンスの `media[0].mediaGenerationId` に新しいクリップが入っており、元の ID の末尾に `_upsampled` が付いたものなので、アップスケール後の3つの ID は `55808825-…_upsampled`、`c4d0e6b1-…_upsampled`、`3cc8ea2f-…_upsampled` です。ステップ4で表示しているクリップは、これらのアップスケール版です。4K にもでき、1本50クレジットで、Google AI Ultra のプランでのみ使えます。 ### ステップ6:つなげる [POST /videos/concatenate](/docs/api-google-flow-v1/post-google-flow-videos-concatenate) は、アップスケールした3つの ID を順番に受け取り、つなげたファイルを base64 で返します。解像度はクリップと同じです。つなぎ目が1テイクに見えるかどうかはトリミング次第です。各クリップは静止画での短い間で始まり、静止画に戻って終わるので、トリミングしないとカットのたびに静止が重なります。ただ、彼女はセリフを言い終える時点で手をすでにテーブルに置いているので、映像だけを見てトリミングすると最後の言葉が切れてしまいます。最後の音の後にひと呼吸置いてからカットし、それより早く切らないこと。今回のクリップでは、クリップ1は笑い声が最後のフレームまで続くのでそのまま残し、クリップ2の終わりを0.5秒強、クリップ2と3の始まりを数フレームずつ削りました。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos-concatenate">POST /videos/concatenate</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos/concatenate' \ --header 'Authorization: Bearer user:1234-…' \ --header 'Content-Type: application/json' \ --data '{ "media": [ { "mediaGenerationId": "user:1234-email:…-video:55808825-…_upsampled" }, { "mediaGenerationId": "user:1234-email:…-video:c4d0e6b1-…_upsampled", "trimStart": 0.458, "trimEnd": 0.6 }, { "mediaGenerationId": "user:1234-email:…-video:3cc8ea2f-…_upsampled", "trimStart": 0.125 } ] }' ``` </details> 3つの ID は、ステップ5でアップスケールしたクリップを順に並べたもので、マグ、デスクロボット、キーボードです。 <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 260px;max-width:320px;margin:0"> <video poster="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/10b-ugc-products-joined-29s-1080p-upscaled-concatenated-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/10b-ugc-products-joined-29s-1080p-upscaled-concatenated.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">結合後 — 28.8秒、1080p (0クレジット)</figcaption> </figure> </div> 彼女がテーブルに手を置いてセリフを言い終えるとカットが入り、次の商品に手を伸ばします。結合したファイルはホスティング用に小さいサイズで再エンコードしていますが、3本のクリップは API が返したままです。 ### 注意点 * 編集ではなく生成する。[UGC トーキングヘッド](/blog/260902)(英語)の記事では動画から動画への編集でクリップを延長しており、セリフが短ければ今でもその方法が使えます。今回はうまくいきませんでした。編集は元の音声を元のタイムラインのまま残すため、10秒のセリフで元のクリップが埋まっていると、新しいセリフは古いセリフを置き換えずに混ざり合い、テーブルに残った商品もテイクごとに形が変わりました。各クリップを静止画から生成すると、セリフは最後まで入り、商品は崩れず、つなぎ目もきれいになり、クレジットも少なく済みました。 * タグは静止画に持たせる。開始フレーム+終了フレームのモードは2枚の画像しか受け取りません。キャラクターとシートを使ったタグ付けは静止画で済ませれば、クリップはそれを引き継ぎます。 * 動きの時間を指定する。セリフでいっぱいの10秒のクリップでは、商品を置くタイミングを「by the eight-second mark」(8秒の時点までに)のように時間で指示し、最後に動かず無音の間を置く必要があります。任せきりにすると、モデルはセリフを長引かせ、終了フレームへ飛びました。 * 声はすべてのプロンプトで同じように描写する。別々のクリップ間で声を引き継ぐ仕組みはなく、キャラクターは声のプリセットを持てても、このモードには届きません。まったく同じ描写にしたことで、3本のクリップは1テイクとして通用するほど近い声になりました。 * シートにはパネルごとのカメラ位置を。4つのパネルそれぞれに何を写すかを書きます。平たい物には真上からのパネルを入れます。手、キャプション、ロゴは入れないこと。シートに写っているものは何でもクリップに出てくる可能性があります。 * 映像ではなく音に合わせてトリミングする。彼女は話し終える前に動きを止めます。最初の静止フレームでカットすると、セリフの終わりまで切れてしまいました。 * 出演者は架空の人物。Google のモデレーションは、実在の特定できる人物に対してより厳しくなっています。生成したキャラクターから始めましょう。 ### かかった費用 | ステップ | モード | クレジット | |---|---|---| | 商品シート3枚、1:1 | Nano Banana 2 Lite | 0 | | 出演者のポートレート2枚、3:4 | Nano Banana 2 Lite | 0 | | キャラクター | — | 0 | | 静止画、9:16 | Nano Banana 2 Lite、キャラクター+参照画像3枚 | 0 | | クリップ1、マグ、10秒 | I2V、開始+終了フレーム | 15 | | クリップ2、デスクロボット、10秒 | I2V、開始+終了フレーム | 15 | | クリップ3、キーボード、10秒 | I2V、開始+終了フレーム | 15 | | アップスケール、3本を1080p に | — | 0 | | 結合 | — | 0 | | 合計 | | 45 | 画像、キャラクター、1080p へのアップスケール、結合はすべて無料です。動画にクレジットを使う前に、シート、出演者、静止画を気が済むまで作り直せます。費用がかかるアップグレードは4K だけで、Ultra でクリップ1本あたり50クレジットです。 ### 自分で動かす 上の各ステップは API 呼び出し1回で、6つをつなげれば1本のスクリプトになります。Node.js の完全なパイプライン、Python 版、このページのすべてのプロンプトを収めた `prompts.json` は [`useapi/google-flow-api/ugc-product-video`](https://github.com/useapi/google-flow-api/tree/main/ugc-product-video) にあります。クローンして `prompts.json` に自分の商品とセリフを入れれば、コマンド1つで動画全体ができあがります。 ステップごとにチェックポイントを保存するので、中断した実行はクリップの費用を払い直すことなく再開できます。また、よりよい静止画や別の出演者など、1つのステップだけをやり直すこともでき、それ以前の結果を作り直す必要はありません。 ### よくある質問 - **生成したシートの代わりに自分の商品写真を使えますか?** useapi.net なら使えます。[POST /assets](/docs/api-google-flow-v1/post-google-flow-assets-email) で写真をアップロードし、返ってきた ID を静止画のリクエストの `reference_1`〜`reference_3` に渡します。ここで生成したシートを渡すのとまったく同じです。4面のシートは物のあらゆる面をモデルに見せるための方法で、実在の商品にも同じ効果があります。 - **[トーキングヘッドの記事](/blog/260902)(英語)のように、1本のクリップを編集して次のクリップにしないのはなぜですか?** useapi.net でもそれはできますが、動画から動画への編集は元の音声を元のタイムラインのまま残します。セリフが短ければうまくいきます。10秒のセリフでクリップが埋まっていると、新しいセリフが古いセリフと混ざり、テーブルの商品も形が変わりました。すべてのクリップを同じ静止画から生成すればどちらも避けられ、費用も20クレジットではなく15クレジットで済みます。[注意点](#what-to-expect)をご覧ください。 - **3本のクリップがすべて同じフレームで始まり、同じフレームで終わるのはなぜですか?** useapi.net では、開始フレーム+終了フレームのモードで各クリップの両端を同じ静止画に固定しているので、どの順番でもカットが目立たずにつながり、結合の呼び出しで各つなぎ目の短い間をトリミングします。仕組みは [UGC トーキングヘッド](/blog/260902)(英語)の記事で説明しています。 - **クリップ間で声は同じになりますか?** useapi.net で作った3本のクリップは、1テイクとして通用するほど近い声になりました。すべてのプロンプトで声をまったく同じように描写したからです。開始フレーム+終了フレームのモードは音声の参照を受け取らず、キャラクターの声のプリセットも届きません。声を確実にそろえたい場合は、参照から動画を作るモードが `referenceAudio_1` を受け付けますが、フレームの固定はできなくなります。 - **費用はいくらですか?** useapi.net なら、この29秒の動画全体で Google AI Ultra($199.99)では $0.36 です。Omni 1.1 Flash のクリップ3本に Flow クレジット45を使い、画像、ポートレート、キャラクター、結合はすべて無料です。720p の Omni 1.1 Flash で同じ30秒を作ると、公式の [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) では約 $3.04 かかります(2026年11月時点)。[かかった費用](#what-it-cost)をご覧ください。 ### おわりに ご質問は <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord サーバー</a> または <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram チャンネル</a>へどうぞ。 コード例は [GitHub リポジトリ](https://github.com/useapi/google-flow-api)にあります。 #### ほかの掲載先 {: .no_toc #cross-posted } この記事(英語版)は [dev.to](https://dev.to/useapi/how-to-make-a-ugc-product-video-with-the-google-flow-api-4nef){:rel="nofollow"} にも掲載しています。 ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-flow-ugc-product-video-pt === Document URL: https://useapi.net/docs/articles/google-flow-ugc-product-video-pt --- layout: default title: "Como fazer um vídeo UGC de produto com a Google Flow API" description: "Monte um vídeo UGC de produto de 29 segundos com a Google Flow API da useapi.net: fichas de produto e uma apresentadora com POST /images, um quadro fixo que reúne tudo, três clipes Omni 1.1 Flash de 10 segundos a partir dele, upscale grátis para 1080p e POST /videos/concatenate para juntar." keywords: [UGC video, product video, Google Flow API, Omni 1.1 Flash, product sheets, character, first and last frame, concatenate, vídeo UGC, vídeo de produto, anúncio UGC, API de vídeo com IA, primeiro e último quadro, juntar vídeos, ficha de produto, tutorial, código, curl] image: https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/06-ugc-products-still-presenter-and-three-products-nano-banana-2-lite.png video: name: "UGC with the Google Flow API, the 75-second walkthrough" description: "The finished UGC product video, then how it was built: product sheets, a character, one still, three Omni 1.1 Flash clips and one concatenate call, through the useapi.net Google Flow API." url: https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/ugc-google-flow-api-1080p.mp4 embed: https://www.youtube.com/embed/wbUROtDIfGA thumbnail: https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/06-ugc-products-still-presenter-and-three-products-nano-banana-2-lite.png date: 2026-09-04 duration: PT1M15S width: 1080 height: 1920 parent: Articles nav_exclude: true lang: pt-BR translation_key: ugc-product-video date: 2026-09-04 last_modified: 2026-11-06 nav_order: 835 repo: https://github.com/useapi/google-flow-api --- ## Como fazer um vídeo UGC de produto com a Google Flow API {: .no_toc #how-to-make-a-ugc-product-video-with-the-google-flow-api } 8 min de leitura • 4 de setembro de 2026 (6 de novembro de 2026) A useapi.net é uma API de terceiros. Não tem afiliação com o Google nem é endossada por ele. ## Sumário {: .no_toc .text-delta #table-of-contents } ### Introdução Um vídeo UGC de produto pode ser feito do começo ao fim pela [Google Flow API da useapi.net](/docs/api-google-flow-v1) por 45 créditos do Flow, sem nada processado localmente. Uma apresentadora inventada mostra três produtos inventados para a câmera. UGC é o estilo de conteúdo gerado por usuários que enche os feeds das redes sociais e as bibliotecas de anúncios: uma pessoa falando para a câmera do celular, para vender um produto, para divertir ou só por diversão. Este é o guia completo, de A a Z, para produzir esse tipo de vídeo com nível profissional: os produtos, a apresentadora, as falas dela e o corte final, tudo sob seu controle, em seis etapas de chamadas de API que você pode copiar como estão. Prefere um formulário sem código? O [fluxo de anúncios UGC no n8n](/docs/articles/google-flow-n8n-ugc-ads) (em inglês) cria esse tipo de anúncio com uma página para escolher ou gerar de novo em cada etapa. Aqui está o resultado: três clipes Omni 1.1 Flash de 10 segundos com upscale para 1080p, cada quadro e cada som gerados pela [Google Flow API](/docs/api-google-flow-v1). A mesma chamada de upscale chega a 4K quando você precisa de qualidade profissional, veja a [Etapa 5](#step-5-upscale-to-1080p): <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 260px;max-width:320px;margin:0"> <video poster="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/10b-ugc-products-joined-29s-1080p-upscaled-concatenated-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/10b-ugc-products-joined-29s-1080p-upscaled-concatenated.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">O resultado — 29 segundos, 1080p, três produtos, três clipes (45 créditos no total)</figcaption> </figure> </div> Se você prefere assistir em vez de ler, aqui está o guia inteiro em 75 segundos (em inglês): <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 260px;max-width:320px;margin:0"> <div style="position:relative;width:100%;padding-top:177.78%;border-radius:8px;overflow:hidden"> <iframe src="https://www.youtube.com/embed/wbUROtDIfGA" title="UGC with the Google Flow API, the 75-second walkthrough" style="position:absolute;top:0;left:0;width:100%;height:100%;border:0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen loading="lazy"></iframe> </div> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">O passo a passo em 75 segundos (<a href="https://www.youtube.com/watch?v=wbUROtDIfGA" target="_blank" rel="noopener noreferrer">assistir no YouTube</a> · narração e música da <a href="/docs/api-minimax-v1">MiniMax API</a>)</figcaption> </figure> </div> ### Preços Vídeo com o Omni 1.1 Flash exige uma assinatura paga do Google AI (Plus, Pro ou Ultra), e a useapi.net não cobra nada por vídeo. Quanto este vídeo custou, etapa por etapa, está em [Quanto custou](#what-it-cost), e o preço por vídeo em cada plano, comparado com a API oficial, está na [tabela de preços do Google Flow](/docs/api-google-flow-v1#pricing). ### Sobre os ids nas requisições Cada requisição abaixo se refere a resultados anteriores pelo `mediaGenerationId`. Os ids são longos, então aparecem encurtados aqui como `user:1234-email:…-image:b0bdf3e8-…`, e uma linha abaixo de cada requisição diz a qual resultado anterior cada um corresponde. O id de uma imagem vem do [POST /images](/docs/api-google-flow-v1/post-google-flow-images) em `media[0].image.generatedImage.mediaGenerationId`, o de um personagem no campo `character` do [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters), o de um vídeo em `media[0].mediaGenerationId` do [job](/docs/api-google-flow-v1/get-google-flow-jobs-jobid) concluído, e o id de um clipe com upscale é o id de origem com `_upsampled` no final. ### Etapa 1: uma ficha para cada produto Uma ficha de produto é uma única imagem que mostra o item por quatro lados, para que o modelo tenha o objeto inteiro e não um ângulo de sorte. [POST /images](/docs/api-google-flow-v1/post-google-flow-images), quadrado, uma requisição por produto. O prompt descreve a câmera de cada painel, porque só "frente, lado, costas" deu dois painéis idênticos para a caneca e nenhum lado de verdade para o teclado. Um objeto achatado como o teclado precisa de um painel visto de cima, um em forma de cubo não. Sem mãos, sem legendas, sem logos, para que nada além do produto vaze para os clipes. O mesmo funciona com um produto real. Envie fotos dele com [POST /assets](/docs/api-google-flow-v1/post-google-flow-assets-email) e passe os ids como `reference_1` a `reference_4` nesta requisição, e o modelo transforma tudo numa ficha limpa de quatro painéis. O mesmo truque faz uma ficha de uma embalagem, de um logo ou de um kit. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a> (a caneca)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="1:1"' \ --form 'count="2"' \ --form 'prompt="Orthographic product-catalog sheet on a plain white background: a matte white ceramic mug with a straight cylindrical body and a clearly visible glowing amber light band around its base, about a finger wide, like a smart heated mug. The sheet is divided into four equal panels by thin grey lines in a 2 by 2 grid. Every panel shows the same single item at exactly the same size, position and lighting, camera at the item'\''s eye level unless stated: top-left: side profile, the handle pointing left and seen edge-on; top-right: view from the handle side, the handle pointing straight at the camera; bottom-left: view from the opposite side, the handle hidden behind the body; bottom-right: three-quarter view from slightly above, the handle to the right. Soft even studio light, photoreal. Object only: no hands, no people, no props, no text anywhere, no captions, no labels, no logo, no packaging."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/01-ugc-products-sheet-smart-mug-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/01-ugc-products-sheet-smart-mug-nano-banana-2-lite.png" alt="Ficha de produto da caneca inteligente, quatro vistas numa grade 2 por 2" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">A caneca — Nano Banana 2 Lite, id <code>b0bdf3e8</code> (0 créditos)</figcaption> </figure> </div> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a> (o robô de mesa)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="1:1"' \ --form 'count="2"' \ --form 'prompt="Orthographic product-catalog sheet on a plain white background: a small rounded pastel mint desk robot, a palm-sized cube with a glossy black screen face showing a happy smiling expression, two round white eyes and a curved white smile, a little rounded antenna nub on top, a small round white dial on its right side, and a speaker grille on its back. The sheet is divided into four equal panels by thin grey lines in a 2 by 2 grid. Every panel shows the same single item at exactly the same size, position and lighting, camera at the item'\''s eye level unless stated: top-left: front view showing the smiling face; top-right: right side view showing the round dial and the antenna nub; bottom-left: back view showing the speaker grille; bottom-right: three-quarter view showing the smiling face and the dial. Soft even studio light, photoreal. Object only: no hands, no people, no props, no text anywhere, no captions, no labels, no logo, no packaging."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/02-ugc-products-sheet-desk-robot-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/02-ugc-products-sheet-desk-robot-nano-banana-2-lite.png" alt="Ficha de produto do robô de mesa, quatro vistas numa grade 2 por 2" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">O robô de mesa — Nano Banana 2 Lite, id <code>7aaed056</code> (0 créditos)</figcaption> </figure> </div> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a> (o teclado)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="1:1"' \ --form 'count="4"' \ --form 'prompt="Orthographic product-catalog sheet on a plain white background: a real mechanical three-key macro pad, the kind sold for shortcuts: a slim, low-profile white aluminum case, three mechanical key switches in one row with sculpted dished keycaps and a small gap between them, coral on the left, lemon yellow in the middle, sky blue on the right, a USB-C port on the back edge. Exactly three keys in one row, never more. The sheet is divided into four equal panels by thin grey lines in a 2 by 2 grid. Every panel shows the same single item at exactly the same size, position and lighting, camera at the item'\''s eye level unless stated: top-left: top-down view straight from above, the three keys in a row left to right; top-right: front view at eye level; bottom-left: left side view at eye level, the slim case and the keycap profile seen edge-on; bottom-right: three-quarter view from above. Soft even studio light, photoreal. Object only: no hands, no people, no props, no text anywhere, no captions, no labels, no logo, no packaging."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/03-ugc-products-sheet-three-key-keyboard-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/03-ugc-products-sheet-three-key-keyboard-nano-banana-2-lite.png" alt="Ficha de produto do teclado de três teclas, quatro vistas numa grade 2 por 2" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">O teclado — Nano Banana 2 Lite, id <code>4f861c23</code> (0 créditos)</figcaption> </figure> </div> Imagens não custam nada, então peça `count` de 2 a 4 e fique com a melhor ficha. O teclado levou algumas rodadas até o prompt descrever um macro pad de verdade com um painel visto de cima, o cubo funcionou de primeira. ### Etapa 2: a apresentadora Três chamadas. Um retrato de frente a partir de uma descrição. Um retrato em três quartos gerado a partir do primeiro com `reference_1`, para que os dois tenham o mesmo rosto. Depois [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters) com os dois retratos, que devolve uma referência de personagem. A partir daí ela é `@character_1` em qualquer prompt, e o Google a fixa pelo próprio sistema de entidades em vez de por uma descrição. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a> (retrato de frente)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="3:4"' \ --form 'count="2"' \ --form 'prompt="Character reference portrait, photoreal, natural skin, no heavy retouching: a strikingly attractive young woman in her early twenties with a sleek platinum-blonde blunt bob and straight bangs, dark defined eyebrows, icy grey eyes, a tiny silver nose stud, a playful smirk with a hint of teeth, wearing a fitted black turtleneck and a thin gold chain necklace. Head and shoulders, facing the camera straight on, plain light-grey studio background, soft even light. No text, no logo, no captions."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/04-ugc-products-presenter-front-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/04-ugc-products-presenter-front-nano-banana-2-lite.png" alt="Retrato de frente da apresentadora" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">De frente — Nano Banana 2 Lite, id <code>a236ef66</code> (0 créditos)</figcaption> </figure> </div> Geramos alguns visuais e escolhemos este. Se algum detalhe precisar mudar depois, a corrente, por exemplo, gere-a de novo com o próprio retrato dela como `reference_1` e um prompt que cite só a mudança, e o rosto continua o mesmo. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a> (retrato em três quartos)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="3:4"' \ --form 'count="1"' \ --form 'reference_1="user:1234-email:…-image:a236ef66-…"' \ --form 'prompt="@reference_1 is the same woman: identical face, hair, freckles, sweater and earrings. Three-quarter view from the waist up, relaxed natural smile, plain light-grey studio background, soft even light. Photoreal, no text."' ``` </details> `reference_1` é o retrato de frente, `a236ef66`. Este prompt ainda menciona sardas, um suéter e brincos que sobraram de uma apresentadora anterior, e isso não atrapalhou: com uma imagem de referência na requisição, a referência vence as palavras. <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/05-ugc-products-presenter-three-quarter-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/05-ugc-products-presenter-three-quarter-nano-banana-2-lite.png" alt="Retrato em três quartos da apresentadora, gerado a partir do retrato de frente" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">Três quartos — id <code>d891301c</code> (0 créditos)</figcaption> </figure> </div> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-characters">POST /characters</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/characters' \ --header 'Authorization: Bearer user:1234-…' \ --form 'displayName="Mia"' \ --form 'personalityNotes="Quick, bright, deadpan delivery with a smile in her voice. Talks to the camera like a friend showing off things she bought at 2am."' \ --form 'imageReference_1="user:1234-email:…-image:a236ef66-…"' \ --form 'imageReference_2="user:1234-email:…-image:d891301c-…"' \ --form 'voice="Leda"' ``` </details> `imageReference_1` é o retrato de frente `a236ef66`, `imageReference_2` o de três quartos `d891301c`. O campo `character` da resposta é o id dela, `53ca1036` abaixo. A `voice` é um dos presets de sistema do Google e vai junto com a personagem, mas não chega ao modo de clipe usado na Etapa 4, veja [O que esperar](#what-to-expect). ### Etapa 3: o quadro fixo, a cena inteira num só quadro Uma requisição junta tudo. A personagem entra como `character_1`, as três fichas como `reference_1` a `reference_3`, e o prompt posiciona cada uma pela tag, da esquerda para a direita na mesa à frente dela. Este quadro vira as duas pontas de cada clipe, então é o único lugar onde as tags fazem o trabalho. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="9:16"' \ --form 'count="2"' \ --form 'character_1="user:1234-email:…-character:53ca1036-…"' \ --form 'reference_1="user:1234-email:…-image:b0bdf3e8-…"' \ --form 'reference_2="user:1234-email:…-image:7aaed056-…"' \ --form 'reference_3="user:1234-email:…-image:4f861c23-…"' \ --form 'prompt="Full-frame vertical phone video look, no phone, no bezel. @character_1 sits at a light wooden table in a bright minimal creator studio, facing the camera, waist-up and centered, a plain warm-grey backdrop behind her, soft key light from the left with a gentle catchlight in her eyes. Laid out on the table in front of her, left to right, each fully visible and resting flat on the table: the mug from @reference_1, the desk robot from @reference_2, the keyboard from @reference_3. Her hands rest on the table, relaxed closed-mouth smile, eyes on the lens. Photoreal, no text, no captions."' ``` </details> `character_1` é a personagem da Etapa 2, `53ca1036`. `reference_1` a `reference_3` são as três fichas da Etapa 1: a caneca `b0bdf3e8`, o robô de mesa `7aaed056`, o teclado `4f861c23`. <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/06-ugc-products-still-presenter-and-three-products-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/06-ugc-products-still-presenter-and-three-products-nano-banana-2-lite.png" alt="A apresentadora à mesa com a caneca, o robô de mesa e o teclado dispostos à frente dela" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">O quadro fixo — o rosto vem da personagem, cada produto da sua ficha, id <code>034cddc8</code> (0 créditos)</figcaption> </figure> </div> A caneca tem o brilho, o robô tem o rosto e a antena, o teclado tem as três cores e a porta, e ela é a mulher dos retratos. ### Etapa 4: um clipe por produto, todos a partir do quadro fixo O modo de primeiro e último quadro do Omni, com o quadro fixo nas duas posições, uma requisição por produto, o mesmo [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) toda vez. Esse modo aceita só as duas imagens, sem fichas, sem personagem, sem referência de voz. Tudo bem, porque o quadro fixo já tem tudo isso. Cada item que ela pega saiu igual à ficha só a partir do quadro fixo. O prompt faz três coisas. Prende as duas pontas ao quadro, com uma pausa calma de cada lado. Dá a ela a fala e a voz. E marca o tempo da coreografia: ela começa a falar enquanto levanta o item, o item volta ao lugar até a marca de oito segundos, e os dois últimos segundos são uma pausa parada e em silêncio. Sem essa última parte, ela se atrasava e o braço saltava para o quadro final. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos">POST /videos</a> (a caneca)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'model="omni-flash"' \ --form 'aspectRatio="portrait"' \ --form 'duration="10"' \ --form 'resolution="720p"' \ --form 'startImage="user:1234-email:…-image:034cddc8-…"' \ --form 'endImage="user:1234-email:…-image:034cddc8-…"' \ --form 'prompt="She begins and ends exactly on this frame: hands resting on the table, the three items laid out in front of her, a small closed-mouth smile, looking into the lens, with a short quiet beat before she moves and another after she settles back. Timing matters: after a short quiet beat she picks up the mug on the left with both hands and starts talking as she lifts it, holding it up to the camera and talking straight to the lens, quick and bright with a deadpan edge and a smile in her voice, keeping both hands on the mug while she speaks. She says: \"Three gadgets smarter than me. Low bar. One: this mug texts me when my coffee'\''s cold. Better follow-up than my ex.\" Right after the last word she gives one short laugh to herself, still holding the mug. By the eight-second mark the mug is back down gently in exactly the same spot and both hands are resting on the table again, brought back in one calm unhurried movement. For the final two seconds she holds completely still, hands resting on the table, looking into the lens with a small closed-mouth smile. Natural room tone, no music, no captions, no text on screen."' ``` </details> `startImage` e `endImage` são ambos o quadro fixo da Etapa 3, `034cddc8`. Os mesmos dois ids vão nos três clipes. <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 220px;max-width:260px;margin:0"> <video poster="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/07b-ugc-products-clip-1-smart-mug-10s-omni-1.1-flash-1080p-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/07b-ugc-products-clip-1-smart-mug-10s-omni-1.1-flash-1080p.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">Clipe 1, a caneca — 10 segundos, id <code>55808825</code>, mostrado após o upscale para 1080p da Etapa 5 (15 créditos)</figcaption> </figure> </div> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos">POST /videos</a> (o robô de mesa)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'model="omni-flash"' \ --form 'aspectRatio="portrait"' \ --form 'duration="10"' \ --form 'resolution="720p"' \ --form 'startImage="user:1234-email:…-image:034cddc8-…"' \ --form 'endImage="user:1234-email:…-image:034cddc8-…"' \ --form 'prompt="She begins and ends exactly on this frame: hands resting on the table, the three items laid out in front of her, a small closed-mouth smile, looking into the lens, with a short quiet beat before she moves and another after she settles back. Timing matters: after a short quiet beat she picks up the desk robot in the middle with both hands and starts talking as she lifts it, holding it up to the camera with its smiling face toward the lens and turning it once and talking straight to the lens, quick and bright with a deadpan edge and a smile in her voice, keeping both hands on it while she speaks. The other two items stay on the table exactly where they are. She says: \"Two: a desk robot that reacts to my day. It has a face. It has never once looked impressed.\" Right after the last word she raises one eyebrow at the camera, a quick expressive beat, still holding the desk robot. By the eight-second mark the desk robot is back down gently in exactly the same spot and both hands are resting on the table again, brought back in one calm unhurried movement. For the final two seconds she is silent and holds completely still, hands resting on the table, looking into the lens with a small closed-mouth smile. Natural room tone, no music, no captions, no text on screen."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 220px;max-width:260px;margin:0"> <video poster="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/08b-ugc-products-clip-2-desk-robot-10s-omni-1.1-flash-1080p-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/08b-ugc-products-clip-2-desk-robot-10s-omni-1.1-flash-1080p.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">Clipe 2, o robô de mesa — 10 segundos, id <code>c4d0e6b1</code>, mostrado após o upscale para 1080p da Etapa 5 (15 créditos)</figcaption> </figure> </div> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos">POST /videos</a> (o teclado)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'model="omni-flash"' \ --form 'aspectRatio="portrait"' \ --form 'duration="10"' \ --form 'resolution="720p"' \ --form 'startImage="user:1234-email:…-image:034cddc8-…"' \ --form 'endImage="user:1234-email:…-image:034cddc8-…"' \ --form 'prompt="She begins and ends exactly on this frame: hands resting on the table, the three items laid out in front of her, a small closed-mouth smile, looking into the lens, with a short quiet beat before she moves and another after she settles back. Timing matters: after a short quiet beat she picks up the keyboard on the right with both hands and starts talking as she lifts it, holding it up to the camera with the three keys facing the lens and talking straight to the lens, quick and bright with a deadpan edge and a smile in her voice, keeping both hands on it while she speaks. The other two items stay on the table exactly where they are. She says: \"Three: a keyboard with three keys. Copy, paste, undo. That'\''s my whole career. Oh, the mug'\''s texting. Bye!\" Right after the last word she raises one eyebrow at the camera, a quick expressive beat, still holding the keyboard. By the eight-second mark the keyboard is back down gently in exactly the same spot and both hands are resting on the table again, brought back in one calm unhurried movement. For the final two seconds she is silent and holds completely still, hands resting on the table, looking into the lens with a small closed-mouth smile. Natural room tone, no music, no captions, no text on screen."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 220px;max-width:260px;margin:0"> <video poster="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/09b-ugc-products-clip-3-three-key-keyboard-10s-omni-1.1-flash-1080p-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/09b-ugc-products-clip-3-three-key-keyboard-10s-omni-1.1-flash-1080p.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">Clipe 3, o teclado — 10 segundos, id <code>3cc8ea2f</code>, mostrado após o upscale para 1080p da Etapa 5 (15 créditos)</figcaption> </figure> </div> A mesma mulher, a mesma mesa, a mesma luz, e cada clipe abre e fecha no quadro fixo, então qualquer um pode vir depois de qualquer outro. As falas têm cerca de 20 palavras em inglês, o que cabe em 10 segundos neste ritmo, com espaço para a pausa no final. ### Etapa 5: upscale para 1080p O Omni 1.1 Flash renderiza em 720p. O [POST /videos/upscale](/docs/api-google-flow-v1/post-google-flow-videos-upscale) leva um clipe a 1080p de graça em qualquer plano pago, em cerca de 40 segundos, e responde na mesma chamada com o id e a URL do clipe com upscale. Uma requisição por clipe, sem `email`: a conta vem do id. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos-upscale">POST /videos/upscale</a> (a caneca, depois o mesmo para os outros dois)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos/upscale' \ --header 'Authorization: Bearer user:1234-…' \ --form 'mediaGenerationId="user:1234-email:…-video:55808825-…"' \ --form 'resolution="1080p"' ``` </details> `mediaGenerationId` é o clipe da caneca da Etapa 4, `55808825`. A mesma chamada com `c4d0e6b1` e `3cc8ea2f` faz o upscale do robô e do teclado. Cada resposta traz o novo clipe em `media[0].mediaGenerationId`, que é o id de origem com `_upsampled` no final, então os três ids com upscale são `55808825-…_upsampled`, `c4d0e6b1-…_upsampled` e `3cc8ea2f-…_upsampled`. Os clipes mostrados na Etapa 4 são essas versões com upscale. 4K também está disponível, por 50 créditos e só num plano Google AI Ultra. ### Etapa 6: juntar os clipes O [POST /videos/concatenate](/docs/api-google-flow-v1/post-google-flow-videos-concatenate) recebe os três ids com upscale em ordem e devolve o arquivo unido em base64, na resolução dos clipes. Os cortes decidem se as emendas parecem uma tomada só. Cada clipe abre com uma pausa curta no quadro fixo e fecha voltando a ele, e sem corte essas pausas se acumulam num congelamento a cada emenda. Mas ela termina cada fala já com as mãos apoiadas, então um corte medido só pela imagem come as últimas palavras. Corte depois do último som mais uma pausa, nunca antes. Nestes clipes, isso significou deixar o clipe 1 inteiro, já que a risada vai até o último quadro, tirar pouco mais de meio segundo do fim do clipe 2 e alguns quadros do início dos clipes 2 e 3. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos-concatenate">POST /videos/concatenate</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos/concatenate' \ --header 'Authorization: Bearer user:1234-…' \ --header 'Content-Type: application/json' \ --data '{ "media": [ { "mediaGenerationId": "user:1234-email:…-video:55808825-…_upsampled" }, { "mediaGenerationId": "user:1234-email:…-video:c4d0e6b1-…_upsampled", "trimStart": 0.458, "trimEnd": 0.6 }, { "mediaGenerationId": "user:1234-email:…-video:3cc8ea2f-…_upsampled", "trimStart": 0.125 } ] }' ``` </details> Os três ids são os clipes com upscale da Etapa 5, em ordem: a caneca, o robô de mesa, o teclado. <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 260px;max-width:320px;margin:0"> <video poster="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/10b-ugc-products-joined-29s-1080p-upscaled-concatenated-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/10b-ugc-products-joined-29s-1080p-upscaled-concatenated.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">Unido — 28,8 segundos, 1080p (0 créditos)</figcaption> </figure> </div> Ela termina uma fala com as mãos na mesa, o corte entra e ela pega o próximo item. O arquivo unido foi recodificado num tamanho menor para hospedagem, os três clipes estão como a API os devolveu. ### O que esperar * Gere, não edite. O post [UGC talking head](/blog/260902) (em inglês) estendeu um clipe com edições de vídeo para vídeo, e isso ainda funciona quando as falas são curtas. Aqui não funcionou. Uma edição mantém a fala da origem na linha do tempo da própria origem, então, com uma fala de 10 segundos ocupando o clipe de partida, a nova fala se misturou à antiga em vez de substituí-la, e os produtos deixados na mesa mudaram entre as tomadas. Gerar cada clipe a partir do quadro fixo deu falas completas, produtos intactos e emendas mais limpas, por menos créditos. * O quadro fixo carrega as tags. O modo de primeiro e último quadro aceita só as duas imagens. Faça as tags no quadro fixo, com a personagem e as fichas, e os clipes herdam tudo. * Marque o tempo da coreografia. Um clipe de 10 segundos com uma fala completa precisa que o momento de pousar o item seja marcado pelo relógio, "by the eight-second mark" (até a marca de oito segundos), e uma pausa parada e em silêncio no final. Por conta própria, o modelo esticava a fala e saltava para o quadro final. * Descreva a voz do mesmo jeito em todos os prompts. Nada leva uma voz de um clipe para outro, e uma personagem pode guardar um preset de voz, mas não alcança este modo. Com uma descrição idêntica, os três clipes saíram parecidos o bastante para passar por uma tomada só. * As fichas precisam de câmera por painel. Diga o que cada um dos quatro painéis mostra. Dê a objetos achatados um painel visto de cima. Deixe mãos, legendas e logos de fora, porque o que estiver na ficha pode acabar no clipe. * Corte pelo som, não pela imagem. Ela fica parada antes de parar de falar. Um corte no primeiro quadro parado levou junto o fim de uma fala. * A apresentadora é inventada. A moderação do Google é mais rígida com pessoas reais e identificáveis. Comece com uma personagem gerada. ### Quanto custou | Etapa | Modo | Créditos | |---|---|---| | Três fichas de produto, 1:1 | Nano Banana 2 Lite | 0 | | Dois retratos da apresentadora, 3:4 | Nano Banana 2 Lite | 0 | | A personagem | — | 0 | | O quadro fixo, 9:16 | Nano Banana 2 Lite, personagem + 3 referências | 0 | | Clipe 1, a caneca, 10s | I2V, primeiro + último quadro | 15 | | Clipe 2, o robô de mesa, 10s | I2V, primeiro + último quadro | 15 | | Clipe 3, o teclado, 10s | I2V, primeiro + último quadro | 15 | | Upscale, três clipes para 1080p | — | 0 | | Concatenar | — | 0 | | Total | | 45 | Imagens, personagens, o upscale para 1080p e a concatenação não custam nada, então refaça à vontade as fichas, a apresentadora e o quadro fixo antes de gastar um crédito com vídeo. O 4K é o único upgrade pago, 50 créditos por clipe no Ultra. ### Rode você mesmo Cada etapa acima é uma chamada de API, e as seis se encadeiam num script. O pipeline completo em Node.js, uma versão em Python e o `prompts.json` com todos os prompts desta página estão em [`useapi/google-flow-api/ugc-product-video`](https://github.com/useapi/google-flow-api/tree/main/ugc-product-video). Clone, coloque seus próprios produtos e falas no `prompts.json`, e um único comando monta o vídeo inteiro. Ele salva um checkpoint após cada etapa, então uma execução interrompida continua de onde parou em vez de pagar pelos clipes de novo, e você pode refazer uma única etapa — um quadro fixo melhor, outra apresentadora — sem gerar de novo o que veio antes. ### Perguntas frequentes - **Posso usar fotos do meu próprio produto em vez de fichas geradas?** Pela useapi.net, sim. Envie as fotos com [POST /assets](/docs/api-google-flow-v1/post-google-flow-assets-email) e passe os ids retornados como `reference_1` a `reference_3` no quadro fixo, exatamente como as fichas geradas são passadas aqui. A ficha de quatro painéis é uma forma de dar ao modelo todos os lados de um objeto, e um produto real ganha com o mesmo tratamento. - **Por que não editar um clipe para virar o próximo, como no [post do talking head](/blog/260902) (em inglês)?** Pela useapi.net dá para fazer, mas uma edição de vídeo para vídeo mantém a fala da origem na linha do tempo da origem. Com falas curtas, funciona. Com uma fala de 10 segundos ocupando o clipe, a nova fala se misturou à antiga e os produtos na mesa mudaram. Gerar todos os clipes a partir do mesmo quadro fixo evita os dois problemas e custa 15 créditos em vez de 20. Veja [O que esperar](#what-to-expect). - **Por que os três clipes começam e terminam no mesmo quadro?** Pela useapi.net, o modo de primeiro e último quadro prende as duas pontas de cada clipe ao mesmo quadro fixo, então os clipes se juntam em qualquer ordem sem corte visível, e a chamada de concatenação corta as pausas curtas em cada emenda. O mecanismo está explicado no post [UGC talking head](/blog/260902) (em inglês). - **A voz fica igual entre os clipes?** Pela useapi.net, os três clipes saíram parecidos o bastante para passar por uma tomada só, porque a voz foi descrita de forma idêntica em todos os prompts. O modo de primeiro e último quadro não aceita referência de áudio, e o preset de voz de uma personagem não chega até ele. Se você precisa de uma voz garantida, o modo de referência para vídeo aceita `referenceAudio_1`, ao custo dos quadros fixados. - **Quanto custa?** Pela useapi.net, este vídeo inteiro de 29 segundos custa $0,36 no Google AI Ultra $199,99: 45 créditos do Flow para os três clipes Omni 1.1 Flash, com todas as imagens, retratos, a personagem e a concatenação de graça. Os mesmos 30 segundos de Omni 1.1 Flash em 720p custam cerca de $3,04 na [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) oficial (em novembro de 2026). Veja [Quanto custou](#what-it-cost). ### Conclusão Visite o nosso <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> servidor no Discord</a> ou o <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> canal no Telegram</a> para qualquer dúvida de suporte. Veja nosso [repositório no GitHub](https://github.com/useapi/google-flow-api) com exemplos de código. #### Publicado também em {: .no_toc #cross-posted } Também publicado no [dev.to](https://dev.to/useapi/how-to-make-a-ugc-product-video-with-the-google-flow-api-4nef){:rel="nofollow"} (em inglês). ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-flow-ugc-product-video-th === Document URL: https://useapi.net/docs/articles/google-flow-ugc-product-video-th --- layout: default title: "วิธีทำวิดีโอรีวิวสินค้าแบบ UGC ด้วย Google Flow API" description: "ทำวิดีโอรีวิวสินค้าแบบ UGC ยาว 29 วินาทีผ่าน Google Flow API ของ useapi.net: สร้างชีตสินค้าและพรีเซนเตอร์ด้วย POST /images รวมทุกอย่างไว้ในภาพนิ่งภาพเดียว สร้างคลิป Omni 1.1 Flash ยาว 10 วินาทีสามคลิปจากภาพนั้น อัปสเกลเป็น 1080p ฟรี แล้วต่อคลิปด้วย POST /videos/concatenate" keywords: [UGC video, product video, Google Flow API, Omni 1.1 Flash, product sheets, character, first and last frame, concatenate, วิดีโอ UGC, วิดีโอรีวิวสินค้า, โฆษณา UGC, API วิดีโอ AI, เฟรมแรกและเฟรมสุดท้าย, ต่อวิดีโอ, ชีตสินค้า, ตัวอย่างโค้ด, คู่มือ, curl] image: https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/06-ugc-products-still-presenter-and-three-products-nano-banana-2-lite.png video: name: "UGC with the Google Flow API, the 75-second walkthrough" description: "The finished UGC product video, then how it was built: product sheets, a character, one still, three Omni 1.1 Flash clips and one concatenate call, through the useapi.net Google Flow API." url: https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/ugc-google-flow-api-1080p.mp4 embed: https://www.youtube.com/embed/wbUROtDIfGA thumbnail: https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/06-ugc-products-still-presenter-and-three-products-nano-banana-2-lite.png date: 2026-09-04 duration: PT1M15S width: 1080 height: 1920 parent: Articles nav_exclude: true lang: th translation_key: ugc-product-video date: 2026-09-04 last_modified: 2026-11-06 nav_order: 835 repo: https://github.com/useapi/google-flow-api --- ## วิธีทำวิดีโอรีวิวสินค้าแบบ UGC ด้วย Google Flow API {: .no_toc #how-to-make-a-ugc-product-video-with-the-google-flow-api } อ่าน 8 นาที • 4 กันยายน 2026 (6 พฤศจิกายน 2026) useapi.net เป็น API ของบุคคลที่สาม (third-party) ไม่มีส่วนเกี่ยวข้องกับ Google และไม่ได้รับการรับรองจาก Google ## สารบัญ {: .no_toc .text-delta #table-of-contents } ### บทนำ วิดีโอรีวิวสินค้าแบบ UGC ทำได้ตั้งแต่ต้นจนจบผ่าน [Google Flow API ของ useapi.net](/docs/api-google-flow-v1) ด้วยเครดิต Flow เพียง 45 เครดิต โดยไม่ต้องประมวลผลอะไรบนเครื่องของคุณ พรีเซนเตอร์ที่สร้างขึ้นมาหนึ่งคนนำเสนอสินค้าที่สร้างขึ้นมาสามชิ้นต่อหน้ากล้อง UGC คือสไตล์คอนเทนต์ที่ผู้ใช้สร้างเอง ซึ่งเต็มไปหมดในฟีดโซเชียลและคลังโฆษณา: คนหนึ่งคนพูดกับกล้องมือถือ เพื่อขายสินค้า เพื่อความบันเทิง หรือแค่ทำเล่นสนุก ๆ นี่คือคู่มือฉบับสมบูรณ์ตั้งแต่ A ถึง Z สำหรับทำวิดีโอแบบนั้นในระดับมืออาชีพ: สินค้า พรีเซนเตอร์ บทพูดของเธอ และการตัดต่อขั้นสุดท้าย คุณควบคุมได้ทั้งหมด ในหกขั้นตอนของการเรียก API ที่คัดลอกไปใช้ได้ทันที ชอบฟอร์มแบบไม่ต้องเขียนโค้ดมากกว่า? [เวิร์กโฟลว์โฆษณา UGC บน n8n](/docs/articles/google-flow-n8n-ugc-ads) (ภาษาอังกฤษ) สร้างโฆษณาแบบนี้ได้ โดยมีหน้าให้เลือกหรือสร้างใหม่ในทุกขั้นตอน นี่คือผลลัพธ์: คลิป Omni 1.1 Flash ยาว 10 วินาทีสามคลิปที่อัปสเกลเป็น 1080p ทุกเฟรมและทุกเสียงสร้างผ่าน [Google Flow API](/docs/api-google-flow-v1) การเรียกอัปสเกลแบบเดียวกันนี้ทำได้ถึง 4K เมื่อต้องการคุณภาพระดับมืออาชีพ ดู[ขั้นตอนที่ 5](#step-5-upscale-to-1080p): <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 260px;max-width:320px;margin:0"> <video poster="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/10b-ugc-products-joined-29s-1080p-upscaled-concatenated-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/10b-ugc-products-joined-29s-1080p-upscaled-concatenated.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">ผลลัพธ์ — 29 วินาที, 1080p, สินค้าสามชิ้น, สามคลิป (รวม 45 เครดิต)</figcaption> </figure> </div> ถ้าอยากดูมากกว่าอ่าน นี่คือคู่มือทั้งหมดใน 75 วินาที (ภาษาอังกฤษ): <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 260px;max-width:320px;margin:0"> <div style="position:relative;width:100%;padding-top:177.78%;border-radius:8px;overflow:hidden"> <iframe src="https://www.youtube.com/embed/wbUROtDIfGA" title="UGC with the Google Flow API, the 75-second walkthrough" style="position:absolute;top:0;left:0;width:100%;height:100%;border:0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen loading="lazy"></iframe> </div> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">วิดีโอสรุป 75 วินาที (<a href="https://www.youtube.com/watch?v=wbUROtDIfGA" target="_blank" rel="noopener noreferrer">ดูบน YouTube</a> · เสียงบรรยายและเพลงจาก <a href="/docs/api-minimax-v1">MiniMax API</a>)</figcaption> </figure> </div> ### ราคา วิดีโอ Omni 1.1 Flash ต้องใช้แพ็กเกจ Google AI แบบเสียเงิน (Plus, Pro หรือ Ultra) และ useapi.net ไม่คิดค่าบริการต่อวิดีโอ ค่าใช้จ่ายของวิดีโอนี้ทีละขั้นตอนอยู่ใน[ค่าใช้จ่ายจริง](#what-it-cost) ส่วนราคาต่อวิดีโอในแต่ละแพ็กเกจเทียบกับ API ทางการอยู่ใน[ตารางราคา Google Flow](/docs/api-google-flow-v1#pricing) ### เกี่ยวกับ id ในคำขอ ทุกคำขอด้านล่างอ้างถึงผลลัพธ์ก่อนหน้าด้วย `mediaGenerationId` ของผลลัพธ์นั้น id เหล่านี้ยาว จึงย่อไว้ที่นี่เป็น `user:1234-email:…-image:b0bdf3e8-…` และมีหนึ่งบรรทัดใต้แต่ละคำขอบอกว่าแต่ละ id คือผลลัพธ์ใดก่อนหน้า id ของภาพได้จาก [POST /images](/docs/api-google-flow-v1/post-google-flow-images) ที่ `media[0].image.generatedImage.mediaGenerationId` id ของตัวละครอยู่ในฟิลด์ `character` ของ [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters) id ของวิดีโออยู่ที่ `media[0].mediaGenerationId` ของ [job](/docs/api-google-flow-v1/get-google-flow-jobs-jobid) ที่เสร็จแล้ว และ id ของคลิปที่อัปสเกลแล้วคือ id ต้นทางที่ต่อท้ายด้วย `_upsampled` ### ขั้นตอนที่ 1: ชีตสำหรับสินค้าแต่ละชิ้น ชีตสินค้าคือภาพเดียวที่แสดงสินค้าจากสี่ด้าน เพื่อให้โมเดลเห็นวัตถุทั้งชิ้น ไม่ใช่มุมเดียวที่บังเอิญออกมาดี ใช้ [POST /images](/docs/api-google-flow-v1/post-google-flow-images) แบบสี่เหลี่ยมจัตุรัส หนึ่งคำขอต่อสินค้าหนึ่งชิ้น พรอมต์ระบุมุมกล้องของทุกช่อง เพราะการเขียนแค่ "ด้านหน้า ด้านข้าง ด้านหลัง" ทำให้แก้วมีสองช่องที่เหมือนกันเป๊ะ และคีย์บอร์ดไม่มีภาพด้านข้างจริง ๆ วัตถุแบน ๆ อย่างคีย์บอร์ดต้องมีช่องมุมมองจากด้านบน ส่วนวัตถุทรงลูกบาศก์ไม่ต้อง ไม่มีมือ ไม่มีข้อความ ไม่มีโลโก้ เพื่อไม่ให้มีอะไรนอกจากสินค้าหลุดเข้าไปในคลิป วิธีเดียวกันใช้กับสินค้าจริงได้ อัปโหลดรูปสินค้าด้วย [POST /assets](/docs/api-google-flow-v1/post-google-flow-assets-email) แล้วส่ง id ที่ได้เป็น `reference_1` ถึง `reference_4` ในคำขอนี้ โมเดลจะเปลี่ยนรูปเหล่านั้นเป็นชีตสี่ช่องที่สะอาดตา เทคนิคเดียวกันนี้ใช้ทำชีตของบรรจุภัณฑ์ โลโก้ หรือสินค้าทั้งเซ็ตได้ <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a> (แก้ว)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="1:1"' \ --form 'count="2"' \ --form 'prompt="Orthographic product-catalog sheet on a plain white background: a matte white ceramic mug with a straight cylindrical body and a clearly visible glowing amber light band around its base, about a finger wide, like a smart heated mug. The sheet is divided into four equal panels by thin grey lines in a 2 by 2 grid. Every panel shows the same single item at exactly the same size, position and lighting, camera at the item'\''s eye level unless stated: top-left: side profile, the handle pointing left and seen edge-on; top-right: view from the handle side, the handle pointing straight at the camera; bottom-left: view from the opposite side, the handle hidden behind the body; bottom-right: three-quarter view from slightly above, the handle to the right. Soft even studio light, photoreal. Object only: no hands, no people, no props, no text anywhere, no captions, no labels, no logo, no packaging."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/01-ugc-products-sheet-smart-mug-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/01-ugc-products-sheet-smart-mug-nano-banana-2-lite.png" alt="ชีตสินค้าของแก้วอัจฉริยะ สี่มุมมองในตาราง 2 x 2" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">แก้ว — Nano Banana 2 Lite, id <code>b0bdf3e8</code> (0 เครดิต)</figcaption> </figure> </div> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a> (หุ่นยนต์ตั้งโต๊ะ)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="1:1"' \ --form 'count="2"' \ --form 'prompt="Orthographic product-catalog sheet on a plain white background: a small rounded pastel mint desk robot, a palm-sized cube with a glossy black screen face showing a happy smiling expression, two round white eyes and a curved white smile, a little rounded antenna nub on top, a small round white dial on its right side, and a speaker grille on its back. The sheet is divided into four equal panels by thin grey lines in a 2 by 2 grid. Every panel shows the same single item at exactly the same size, position and lighting, camera at the item'\''s eye level unless stated: top-left: front view showing the smiling face; top-right: right side view showing the round dial and the antenna nub; bottom-left: back view showing the speaker grille; bottom-right: three-quarter view showing the smiling face and the dial. Soft even studio light, photoreal. Object only: no hands, no people, no props, no text anywhere, no captions, no labels, no logo, no packaging."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/02-ugc-products-sheet-desk-robot-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/02-ugc-products-sheet-desk-robot-nano-banana-2-lite.png" alt="ชีตสินค้าของหุ่นยนต์ตั้งโต๊ะ สี่มุมมองในตาราง 2 x 2" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">หุ่นยนต์ตั้งโต๊ะ — Nano Banana 2 Lite, id <code>7aaed056</code> (0 เครดิต)</figcaption> </figure> </div> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a> (คีย์บอร์ด)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="1:1"' \ --form 'count="4"' \ --form 'prompt="Orthographic product-catalog sheet on a plain white background: a real mechanical three-key macro pad, the kind sold for shortcuts: a slim, low-profile white aluminum case, three mechanical key switches in one row with sculpted dished keycaps and a small gap between them, coral on the left, lemon yellow in the middle, sky blue on the right, a USB-C port on the back edge. Exactly three keys in one row, never more. The sheet is divided into four equal panels by thin grey lines in a 2 by 2 grid. Every panel shows the same single item at exactly the same size, position and lighting, camera at the item'\''s eye level unless stated: top-left: top-down view straight from above, the three keys in a row left to right; top-right: front view at eye level; bottom-left: left side view at eye level, the slim case and the keycap profile seen edge-on; bottom-right: three-quarter view from above. Soft even studio light, photoreal. Object only: no hands, no people, no props, no text anywhere, no captions, no labels, no logo, no packaging."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/03-ugc-products-sheet-three-key-keyboard-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/03-ugc-products-sheet-three-key-keyboard-nano-banana-2-lite.png" alt="ชีตสินค้าของคีย์บอร์ดสามปุ่ม สี่มุมมองในตาราง 2 x 2" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">คีย์บอร์ด — Nano Banana 2 Lite, id <code>4f861c23</code> (0 เครดิต)</figcaption> </figure> </div> การสร้างภาพไม่เสียเครดิต จึงตั้ง `count` เป็น 2 ถึง 4 แล้วเก็บชีตที่ดีที่สุดไว้ คีย์บอร์ดต้องลองอยู่หลายรอบกว่าพรอมต์จะบรรยายมาโครแพดของจริงพร้อมช่องมุมมองจากด้านบนได้ ส่วนลูกบาศก์ได้ผลตั้งแต่ครั้งแรก ### ขั้นตอนที่ 2: พรีเซนเตอร์ เรียกสามครั้ง ภาพพอร์ตเทรตหน้าตรงจากคำบรรยาย ภาพพอร์ตเทรตมุมสามในสี่ที่สร้างจากภาพแรกด้วย `reference_1` เพื่อให้ใบหน้าในสองภาพตรงกัน จากนั้นเรียก [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters) ด้วยภาพพอร์ตเทรตทั้งสอง ซึ่งจะคืนค่าตัวอ้างอิงตัวละคร นับจากนั้นเธอคือ `@character_1` ในทุกพรอมต์ และ Google ตรึงหน้าตาเธอไว้ด้วยระบบเอนทิตีของตัวเอง แทนที่จะใช้คำบรรยาย <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a> (พอร์ตเทรตหน้าตรง)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="3:4"' \ --form 'count="2"' \ --form 'prompt="Character reference portrait, photoreal, natural skin, no heavy retouching: a strikingly attractive young woman in her early twenties with a sleek platinum-blonde blunt bob and straight bangs, dark defined eyebrows, icy grey eyes, a tiny silver nose stud, a playful smirk with a hint of teeth, wearing a fitted black turtleneck and a thin gold chain necklace. Head and shoulders, facing the camera straight on, plain light-grey studio background, soft even light. No text, no logo, no captions."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/04-ugc-products-presenter-front-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/04-ugc-products-presenter-front-nano-banana-2-lite.png" alt="ภาพพอร์ตเทรตหน้าตรงของพรีเซนเตอร์" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">หน้าตรง — Nano Banana 2 Lite, id <code>a236ef66</code> (0 เครดิต)</figcaption> </figure> </div> เราสร้างไว้หลายลุคแล้วเลือกลุคนี้ ถ้าภายหลังต้องเปลี่ยนรายละเอียดบางอย่าง เช่น สร้อยคอ ให้สร้างเธอใหม่โดยใช้ภาพพอร์ตเทรตของเธอเองเป็น `reference_1` และเขียนพรอมต์ระบุเฉพาะสิ่งที่เปลี่ยน ใบหน้าจะยังคงเดิม <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a> (พอร์ตเทรตมุมสามในสี่)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="3:4"' \ --form 'count="1"' \ --form 'reference_1="user:1234-email:…-image:a236ef66-…"' \ --form 'prompt="@reference_1 is the same woman: identical face, hair, freckles, sweater and earrings. Three-quarter view from the waist up, relaxed natural smile, plain light-grey studio background, soft even light. Photoreal, no text."' ``` </details> `reference_1` คือภาพพอร์ตเทรตหน้าตรง `a236ef66` พรอมต์นี้ยังพูดถึงกระ เสื้อสเวตเตอร์ และต่างหูที่หลงเหลือมาจากพรีเซนเตอร์คนก่อน แต่ก็ไม่มีผลเสีย: เมื่อคำขอมีภาพอ้างอิง ภาพอ้างอิงจะชนะคำบรรยาย <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/05-ugc-products-presenter-three-quarter-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/05-ugc-products-presenter-three-quarter-nano-banana-2-lite.png" alt="ภาพพอร์ตเทรตมุมสามในสี่ของพรีเซนเตอร์ สร้างจากภาพหน้าตรง" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">มุมสามในสี่ — id <code>d891301c</code> (0 เครดิต)</figcaption> </figure> </div> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-characters">POST /characters</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/characters' \ --header 'Authorization: Bearer user:1234-…' \ --form 'displayName="Mia"' \ --form 'personalityNotes="Quick, bright, deadpan delivery with a smile in her voice. Talks to the camera like a friend showing off things she bought at 2am."' \ --form 'imageReference_1="user:1234-email:…-image:a236ef66-…"' \ --form 'imageReference_2="user:1234-email:…-image:d891301c-…"' \ --form 'voice="Leda"' ``` </details> `imageReference_1` คือภาพหน้าตรง `a236ef66` และ `imageReference_2` คือภาพมุมสามในสี่ `d891301c` ฟิลด์ `character` ในการตอบกลับคือ id ของเธอ ซึ่งด้านล่างคือ `53ca1036` ส่วน `voice` คือเสียงสำเร็จรูปของระบบ Google แบบหนึ่ง และติดไปกับตัวละคร แต่ไปไม่ถึงโหมดคลิปที่ใช้ในขั้นตอนที่ 4 ดู[สิ่งที่ควรรู้](#what-to-expect) ### ขั้นตอนที่ 3: ภาพนิ่ง ทั้งฉากในเฟรมเดียว คำขอเดียวรวมทุกอย่างเข้าด้วยกัน ตัวละครเข้ามาเป็น `character_1` ชีตทั้งสามเป็น `reference_1` ถึง `reference_3` และพรอมต์จัดวางแต่ละชิ้นตามแท็ก เรียงจากซ้ายไปขวาบนโต๊ะตรงหน้าเธอ เฟรมนี้จะเป็นทั้งต้นและท้ายของทุกคลิป จึงเป็นที่เดียวที่แท็กทำงาน <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="9:16"' \ --form 'count="2"' \ --form 'character_1="user:1234-email:…-character:53ca1036-…"' \ --form 'reference_1="user:1234-email:…-image:b0bdf3e8-…"' \ --form 'reference_2="user:1234-email:…-image:7aaed056-…"' \ --form 'reference_3="user:1234-email:…-image:4f861c23-…"' \ --form 'prompt="Full-frame vertical phone video look, no phone, no bezel. @character_1 sits at a light wooden table in a bright minimal creator studio, facing the camera, waist-up and centered, a plain warm-grey backdrop behind her, soft key light from the left with a gentle catchlight in her eyes. Laid out on the table in front of her, left to right, each fully visible and resting flat on the table: the mug from @reference_1, the desk robot from @reference_2, the keyboard from @reference_3. Her hands rest on the table, relaxed closed-mouth smile, eyes on the lens. Photoreal, no text, no captions."' ``` </details> `character_1` คือตัวละครจากขั้นตอนที่ 2 `53ca1036` ส่วน `reference_1` ถึง `reference_3` คือชีตทั้งสามจากขั้นตอนที่ 1: แก้ว `b0bdf3e8` หุ่นยนต์ตั้งโต๊ะ `7aaed056` และคีย์บอร์ด `4f861c23` <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/06-ugc-products-still-presenter-and-three-products-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/06-ugc-products-still-presenter-and-three-products-nano-banana-2-lite.png" alt="พรีเซนเตอร์นั่งที่โต๊ะ ตรงหน้ามีแก้ว หุ่นยนต์ตั้งโต๊ะ และคีย์บอร์ดวางเรียงอยู่" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">ภาพนิ่ง — ใบหน้าจากตัวละคร สินค้าแต่ละชิ้นจากชีตของมัน, id <code>034cddc8</code> (0 เครดิต)</figcaption> </figure> </div> แก้วมีแถบไฟเรืองแสง หุ่นยนต์มีหน้าและเสาอากาศ คีย์บอร์ดมีสามสีและพอร์ต และเธอคือผู้หญิงคนเดียวกับในภาพพอร์ตเทรต ### ขั้นตอนที่ 4: หนึ่งคลิปต่อสินค้าหนึ่งชิ้น ทั้งหมดจากภาพนิ่ง ใช้โหมดเฟรมแรก + เฟรมสุดท้ายของ Omni โดยใส่ภาพนิ่งทั้งสองช่อง หนึ่งคำขอต่อสินค้าหนึ่งชิ้น ใช้ [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) ตัวเดิมทุกครั้ง โหมดนี้รับแค่ภาพสองภาพนั้น ไม่รับชีต ไม่รับตัวละคร ไม่รับเสียงอ้างอิง ซึ่งไม่เป็นไร เพราะภาพนิ่งมีทุกอย่างอยู่แล้ว สินค้าทุกชิ้นที่เธอหยิบขึ้นมาออกมาตรงกับชีตของมันจากภาพนิ่งเพียงอย่างเดียว พรอมต์ทำงานสามอย่าง ตรึงทั้งสองปลายไว้กับเฟรม โดยมีจังหวะนิ่งเงียบสั้น ๆ ทั้งสองด้าน ให้บทพูดและน้ำเสียงแก่เธอ และกำหนดจังหวะเวลาของท่าทาง: เธอเริ่มพูดขณะยกสินค้าขึ้น สินค้ากลับไปวางที่เดิมภายในวินาทีที่แปด และสองวินาทีสุดท้ายเป็นช่วงนิ่งและเงียบ ถ้าไม่มีส่วนสุดท้ายนี้ เธอจะช้ากว่ากำหนด และแขนจะกระตุกเข้าเฟรมสุดท้าย <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos">POST /videos</a> (แก้ว)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'model="omni-flash"' \ --form 'aspectRatio="portrait"' \ --form 'duration="10"' \ --form 'resolution="720p"' \ --form 'startImage="user:1234-email:…-image:034cddc8-…"' \ --form 'endImage="user:1234-email:…-image:034cddc8-…"' \ --form 'prompt="She begins and ends exactly on this frame: hands resting on the table, the three items laid out in front of her, a small closed-mouth smile, looking into the lens, with a short quiet beat before she moves and another after she settles back. Timing matters: after a short quiet beat she picks up the mug on the left with both hands and starts talking as she lifts it, holding it up to the camera and talking straight to the lens, quick and bright with a deadpan edge and a smile in her voice, keeping both hands on the mug while she speaks. She says: \"Three gadgets smarter than me. Low bar. One: this mug texts me when my coffee'\''s cold. Better follow-up than my ex.\" Right after the last word she gives one short laugh to herself, still holding the mug. By the eight-second mark the mug is back down gently in exactly the same spot and both hands are resting on the table again, brought back in one calm unhurried movement. For the final two seconds she holds completely still, hands resting on the table, looking into the lens with a small closed-mouth smile. Natural room tone, no music, no captions, no text on screen."' ``` </details> `startImage` และ `endImage` คือภาพนิ่งจากขั้นตอนที่ 3 `034cddc8` ทั้งคู่ ใช้ id สองตัวเดียวกันนี้ในทั้งสามคลิป <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 220px;max-width:260px;margin:0"> <video poster="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/07b-ugc-products-clip-1-smart-mug-10s-omni-1.1-flash-1080p-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/07b-ugc-products-clip-1-smart-mug-10s-omni-1.1-flash-1080p.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">คลิป 1 แก้ว — 10 วินาที, id <code>55808825</code>, แสดงหลังอัปสเกลเป็น 1080p ในขั้นตอนที่ 5 (15 เครดิต)</figcaption> </figure> </div> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos">POST /videos</a> (หุ่นยนต์ตั้งโต๊ะ)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'model="omni-flash"' \ --form 'aspectRatio="portrait"' \ --form 'duration="10"' \ --form 'resolution="720p"' \ --form 'startImage="user:1234-email:…-image:034cddc8-…"' \ --form 'endImage="user:1234-email:…-image:034cddc8-…"' \ --form 'prompt="She begins and ends exactly on this frame: hands resting on the table, the three items laid out in front of her, a small closed-mouth smile, looking into the lens, with a short quiet beat before she moves and another after she settles back. Timing matters: after a short quiet beat she picks up the desk robot in the middle with both hands and starts talking as she lifts it, holding it up to the camera with its smiling face toward the lens and turning it once and talking straight to the lens, quick and bright with a deadpan edge and a smile in her voice, keeping both hands on it while she speaks. The other two items stay on the table exactly where they are. She says: \"Two: a desk robot that reacts to my day. It has a face. It has never once looked impressed.\" Right after the last word she raises one eyebrow at the camera, a quick expressive beat, still holding the desk robot. By the eight-second mark the desk robot is back down gently in exactly the same spot and both hands are resting on the table again, brought back in one calm unhurried movement. For the final two seconds she is silent and holds completely still, hands resting on the table, looking into the lens with a small closed-mouth smile. Natural room tone, no music, no captions, no text on screen."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 220px;max-width:260px;margin:0"> <video poster="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/08b-ugc-products-clip-2-desk-robot-10s-omni-1.1-flash-1080p-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/08b-ugc-products-clip-2-desk-robot-10s-omni-1.1-flash-1080p.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">คลิป 2 หุ่นยนต์ตั้งโต๊ะ — 10 วินาที, id <code>c4d0e6b1</code>, แสดงหลังอัปสเกลเป็น 1080p ในขั้นตอนที่ 5 (15 เครดิต)</figcaption> </figure> </div> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos">POST /videos</a> (คีย์บอร์ด)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'model="omni-flash"' \ --form 'aspectRatio="portrait"' \ --form 'duration="10"' \ --form 'resolution="720p"' \ --form 'startImage="user:1234-email:…-image:034cddc8-…"' \ --form 'endImage="user:1234-email:…-image:034cddc8-…"' \ --form 'prompt="She begins and ends exactly on this frame: hands resting on the table, the three items laid out in front of her, a small closed-mouth smile, looking into the lens, with a short quiet beat before she moves and another after she settles back. Timing matters: after a short quiet beat she picks up the keyboard on the right with both hands and starts talking as she lifts it, holding it up to the camera with the three keys facing the lens and talking straight to the lens, quick and bright with a deadpan edge and a smile in her voice, keeping both hands on it while she speaks. The other two items stay on the table exactly where they are. She says: \"Three: a keyboard with three keys. Copy, paste, undo. That'\''s my whole career. Oh, the mug'\''s texting. Bye!\" Right after the last word she raises one eyebrow at the camera, a quick expressive beat, still holding the keyboard. By the eight-second mark the keyboard is back down gently in exactly the same spot and both hands are resting on the table again, brought back in one calm unhurried movement. For the final two seconds she is silent and holds completely still, hands resting on the table, looking into the lens with a small closed-mouth smile. Natural room tone, no music, no captions, no text on screen."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 220px;max-width:260px;margin:0"> <video poster="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/09b-ugc-products-clip-3-three-key-keyboard-10s-omni-1.1-flash-1080p-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/09b-ugc-products-clip-3-three-key-keyboard-10s-omni-1.1-flash-1080p.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">คลิป 3 คีย์บอร์ด — 10 วินาที, id <code>3cc8ea2f</code>, แสดงหลังอัปสเกลเป็น 1080p ในขั้นตอนที่ 5 (15 เครดิต)</figcaption> </figure> </div> ผู้หญิงคนเดิม โต๊ะตัวเดิม แสงแบบเดิม และทุกคลิปเปิดและปิดที่ภาพนิ่ง คลิปไหนจะต่อท้ายคลิปไหนก็ได้ บทพูดยาวประมาณ 20 คำภาษาอังกฤษ ซึ่งพอดีกับ 10 วินาทีที่จังหวะนี้ และยังเหลือที่สำหรับจังหวะนิ่งตอนท้าย ### ขั้นตอนที่ 5: อัปสเกลเป็น 1080p Omni 1.1 Flash เรนเดอร์ที่ 720p ส่วน [POST /videos/upscale](/docs/api-google-flow-v1/post-google-flow-videos-upscale) อัปสเกลคลิปเป็น 1080p ได้ฟรีในทุกแพ็กเกจแบบเสียเงิน ใช้เวลาประมาณ 40 วินาที และตอบกลับในการเรียกครั้งเดียวกันพร้อม id และ URL ของคลิปที่อัปสเกลแล้ว หนึ่งคำขอต่อหนึ่งคลิป ไม่ต้องใส่ `email` เพราะบัญชีระบุได้จาก id <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos-upscale">POST /videos/upscale</a> (แก้ว แล้วทำแบบเดียวกันกับอีกสองคลิป)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos/upscale' \ --header 'Authorization: Bearer user:1234-…' \ --form 'mediaGenerationId="user:1234-email:…-video:55808825-…"' \ --form 'resolution="1080p"' ``` </details> `mediaGenerationId` คือคลิปแก้วจากขั้นตอนที่ 4 `55808825` เรียกแบบเดียวกันด้วย `c4d0e6b1` และ `3cc8ea2f` เพื่ออัปสเกลหุ่นยนต์และคีย์บอร์ด การตอบกลับแต่ละครั้งมีคลิปใหม่อยู่ที่ `media[0].mediaGenerationId` ซึ่งคือ id ต้นทางที่ต่อท้ายด้วย `_upsampled` ดังนั้น id ที่อัปสเกลแล้วทั้งสามคือ `55808825-…_upsampled`, `c4d0e6b1-…_upsampled` และ `3cc8ea2f-…_upsampled` คลิปที่แสดงในขั้นตอนที่ 4 คือเวอร์ชันที่อัปสเกลแล้วเหล่านี้ อัปสเกลเป็น 4K ก็ได้ ราคา 50 เครดิต และใช้ได้เฉพาะแพ็กเกจ Google AI Ultra ### ขั้นตอนที่ 6: ต่อคลิปเข้าด้วยกัน [POST /videos/concatenate](/docs/api-google-flow-v1/post-google-flow-videos-concatenate) รับ id ที่อัปสเกลแล้วทั้งสามตามลำดับ และคืนไฟล์ที่ต่อแล้วเป็น base64 ที่ความละเอียดเดียวกับคลิป การตัดหัวท้ายเป็นตัวตัดสินว่ารอยต่อจะดูเหมือนถ่ายเทคเดียวหรือไม่ แต่ละคลิปเปิดด้วยการค้างสั้น ๆ ที่ภาพนิ่ง และปิดด้วยการกลับไปที่ภาพนั้น ถ้าไม่ตัด ช่วงค้างเหล่านี้จะซ้อนกันกลายเป็นภาพค้างทุกรอยต่อ แต่เธอพูดจบแต่ละประโยคตอนที่มือวางอยู่บนโต๊ะแล้ว การตัดโดยดูแค่ภาพจึงกินคำสุดท้ายไป ให้ตัดหลังเสียงสุดท้ายบวกอีกหนึ่งจังหวะ ห้ามเร็วกว่านั้น สำหรับคลิปชุดนี้หมายถึงปล่อยคลิป 1 ไว้ทั้งหมด เพราะเสียงหัวเราะลากยาวถึงเฟรมสุดท้าย ตัดท้ายคลิป 2 ออกมากกว่าครึ่งวินาทีเล็กน้อย และตัดต้นคลิป 2 และ 3 ออกไม่กี่เฟรม <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos-concatenate">POST /videos/concatenate</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos/concatenate' \ --header 'Authorization: Bearer user:1234-…' \ --header 'Content-Type: application/json' \ --data '{ "media": [ { "mediaGenerationId": "user:1234-email:…-video:55808825-…_upsampled" }, { "mediaGenerationId": "user:1234-email:…-video:c4d0e6b1-…_upsampled", "trimStart": 0.458, "trimEnd": 0.6 }, { "mediaGenerationId": "user:1234-email:…-video:3cc8ea2f-…_upsampled", "trimStart": 0.125 } ] }' ``` </details> id ทั้งสามคือคลิปที่อัปสเกลแล้วจากขั้นตอนที่ 5 ตามลำดับ: แก้ว หุ่นยนต์ตั้งโต๊ะ คีย์บอร์ด <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 260px;max-width:320px;margin:0"> <video poster="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/10b-ugc-products-joined-29s-1080p-upscaled-concatenated-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/10b-ugc-products-joined-29s-1080p-upscaled-concatenated.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">ต่อแล้ว — 28.8 วินาที, 1080p (0 เครดิต)</figcaption> </figure> </div> เธอพูดจบประโยคพร้อมมือวางบนโต๊ะ ภาพตัด แล้วเธอก็เอื้อมไปหยิบสินค้าชิ้นต่อไป ไฟล์ที่ต่อแล้วถูกเข้ารหัสใหม่ให้มีขนาดเล็กลงเพื่อโฮสต์ ส่วนคลิปทั้งสามยังเป็นแบบที่ API ส่งกลับมา ### สิ่งที่ควรรู้ * สร้างใหม่ อย่าแก้ไข โพสต์ [UGC talking head](/blog/260902) (ภาษาอังกฤษ) ต่อความยาวคลิปด้วยการแก้ไขแบบวิดีโอเป็นวิดีโอ ซึ่งยังใช้ได้เมื่อบทพูดสั้น แต่ที่นี่ใช้ไม่ได้ การแก้ไขจะเก็บเสียงพูดของต้นฉบับไว้บนไทม์ไลน์ของต้นฉบับเอง เมื่อบทพูด 10 วินาทีเต็มคลิปต้นทาง บทใหม่จึงพันเข้ากับบทเก่าแทนที่จะแทนที่มัน และสินค้าที่วางอยู่บนโต๊ะก็ผิดเพี้ยนไปในแต่ละเทค การสร้างแต่ละคลิปจากภาพนิ่งให้บทพูดครบถ้วน สินค้าไม่เพี้ยน และรอยต่อสะอาดกว่า โดยใช้เครดิตน้อยกว่า * ภาพนิ่งเป็นตัวถือแท็ก โหมดเฟรมแรก + เฟรมสุดท้ายรับได้แค่ภาพสองภาพ ให้ติดแท็กในภาพนิ่ง ด้วยตัวละครและชีต แล้วคลิปจะสืบทอดไปเอง * กำหนดเวลาของท่าทาง คลิป 10 วินาทีที่มีบทพูดเต็มต้องระบุจังหวะวางสินค้าตามเวลา "by the eight-second mark" (ภายในวินาทีที่แปด) และมีช่วงนิ่งเงียบตอนท้าย ถ้าปล่อยให้โมเดลทำเอง มันจะลากบทพูดยาวแล้วกระโดดเข้าเฟรมสุดท้าย * บรรยายเสียงแบบเดียวกันในทุกพรอมต์ ไม่มีอะไรส่งต่อเสียงระหว่างคลิปที่แยกกัน และตัวละครเก็บเสียงสำเร็จรูปได้ แต่ไปไม่ถึงโหมดนี้ เมื่อใช้คำบรรยายเหมือนกันทุกตัวอักษร เสียงของทั้งสามคลิปก็ใกล้กันพอจะดูเหมือนถ่ายเทคเดียว * ชีตต้องระบุมุมกล้องของแต่ละช่อง บอกว่าแต่ละช่องในสี่ช่องแสดงอะไร ให้วัตถุแบนมีช่องมุมมองจากด้านบน อย่าใส่มือ ข้อความ และโลโก้ เพราะอะไรก็ตามที่อยู่บนชีตอาจไปโผล่ในคลิป * ตัดตามเสียง ไม่ใช่ตามภาพ เธอหยุดนิ่งก่อนพูดจบ การตัดที่เฟรมนิ่งเฟรมแรกทำให้ท้ายประโยคหายไปด้วย * พรีเซนเตอร์เป็นตัวละครที่สร้างขึ้น Google ตรวจสอบเนื้อหาเข้มงวดกว่ากับบุคคลจริงที่ระบุตัวตนได้ ให้เริ่มจากตัวละครที่สร้างขึ้น ### ค่าใช้จ่ายจริง | ขั้นตอน | โหมด | เครดิต | |---|---|---| | ชีตสินค้าสามชีต, 1:1 | Nano Banana 2 Lite | 0 | | พอร์ตเทรตพรีเซนเตอร์สองภาพ, 3:4 | Nano Banana 2 Lite | 0 | | ตัวละคร | — | 0 | | ภาพนิ่ง, 9:16 | Nano Banana 2 Lite, ตัวละคร + ภาพอ้างอิง 3 ภาพ | 0 | | คลิป 1 แก้ว, 10 วินาที | I2V, เฟรมแรก + เฟรมสุดท้าย | 15 | | คลิป 2 หุ่นยนต์ตั้งโต๊ะ, 10 วินาที | I2V, เฟรมแรก + เฟรมสุดท้าย | 15 | | คลิป 3 คีย์บอร์ด, 10 วินาที | I2V, เฟรมแรก + เฟรมสุดท้าย | 15 | | อัปสเกลสามคลิปเป็น 1080p | — | 0 | | ต่อคลิป | — | 0 | | รวม | | 45 | ภาพ ตัวละคร การอัปสเกลเป็น 1080p และการต่อคลิปไม่มีค่าใช้จ่าย จึงลองปรับชีต พรีเซนเตอร์ และภาพนิ่งได้ตามใจก่อนจะใช้เครดิตแรกกับวิดีโอ 4K เป็นการอัปเกรดเดียวที่มีค่าใช้จ่าย คือ 50 เครดิตต่อคลิปบน Ultra ### ลองรันเอง แต่ละขั้นตอนด้านบนคือการเรียก API หนึ่งครั้ง และทั้งหกขั้นตอนต่อกันเป็นสคริปต์เดียวได้ ไปป์ไลน์ Node.js แบบสมบูรณ์ เวอร์ชัน Python และไฟล์ `prompts.json` ที่เก็บพรอมต์ทั้งหมดในหน้านี้อยู่ที่ [`useapi/google-flow-api/ugc-product-video`](https://github.com/useapi/google-flow-api/tree/main/ugc-product-video) โคลนไป ใส่สินค้าและบทพูดของคุณเองใน `prompts.json` แล้วคำสั่งเดียวก็สร้างวิดีโอได้ทั้งเรื่อง สคริปต์บันทึกเช็กพอยต์หลังทุกขั้นตอน การรันที่ถูกขัดจังหวะจึงทำต่อได้โดยไม่ต้องจ่ายค่าคลิปซ้ำ และคุณทำใหม่เฉพาะขั้นตอนเดียวได้ เช่น ภาพนิ่งที่ดีขึ้นหรือพรีเซนเตอร์คนใหม่ โดยไม่ต้องสร้างสิ่งที่มาก่อนหน้าใหม่ ### คำถามที่พบบ่อย - **ใช้รูปสินค้าของฉันเองแทนชีตที่สร้างขึ้นได้ไหม?** ผ่าน useapi.net ได้ อัปโหลดรูปด้วย [POST /assets](/docs/api-google-flow-v1/post-google-flow-assets-email) แล้วส่ง id ที่ได้เป็น `reference_1` ถึง `reference_3` ในคำขอภาพนิ่ง เหมือนกับที่ส่งชีตที่สร้างขึ้นในหน้านี้ทุกประการ ชีตสี่ช่องเป็นวิธีให้โมเดลเห็นวัตถุครบทุกด้าน และสินค้าจริงก็ได้ประโยชน์จากวิธีเดียวกัน - **ทำไมไม่แก้ไขคลิปหนึ่งให้เป็นคลิปถัดไป เหมือนใน[โพสต์ talking head](/blog/260902) (ภาษาอังกฤษ)?** ผ่าน useapi.net ทำได้ แต่การแก้ไขแบบวิดีโอเป็นวิดีโอจะเก็บเสียงพูดของต้นฉบับไว้บนไทม์ไลน์ของต้นฉบับ ถ้าบทพูดสั้นก็ใช้ได้ แต่เมื่อบทพูด 10 วินาทีเต็มคลิป บทใหม่พันเข้ากับบทเก่า และสินค้าบนโต๊ะก็ผิดเพี้ยน การสร้างทุกคลิปจากภาพนิ่งเดียวกันหลีกเลี่ยงได้ทั้งสองปัญหา และใช้ 15 เครดิตแทน 20 ดู[สิ่งที่ควรรู้](#what-to-expect) - **ทำไมทั้งสามคลิปเริ่มและจบที่เฟรมเดียวกัน?** ผ่าน useapi.net โหมดเฟรมแรก + เฟรมสุดท้ายตรึงทั้งสองปลายของแต่ละคลิปไว้กับภาพนิ่งภาพเดียวกัน คลิปจึงต่อกันได้ทุกลำดับโดยไม่เห็นรอยตัด และการเรียกต่อคลิปจะตัดช่วงค้างสั้น ๆ ที่แต่ละรอยต่อออก กลไกนี้อธิบายไว้ในโพสต์ [UGC talking head](/blog/260902) (ภาษาอังกฤษ) - **เสียงยังเหมือนเดิมในทุกคลิปไหม?** ผ่าน useapi.net ทั้งสามคลิปมีเสียงใกล้กันพอจะดูเหมือนถ่ายเทคเดียว เพราะบรรยายเสียงเหมือนกันทุกตัวอักษรในทุกพรอมต์ โหมดเฟรมแรก + เฟรมสุดท้ายไม่รับเสียงอ้างอิง และเสียงสำเร็จรูปของตัวละครก็ไปไม่ถึงโหมดนี้ ถ้าต้องการเสียงที่รับประกันได้ โหมดอ้างอิงเป็นวิดีโอรับ `referenceAudio_1` โดยแลกกับการไม่ได้ตรึงเฟรม - **ค่าใช้จ่ายเท่าไร?** ผ่าน useapi.net วิดีโอ 29 วินาทีทั้งเรื่องนี้มีค่าใช้จ่าย $0.36 บน Google AI Ultra $199.99: 45 เครดิต Flow สำหรับคลิป Omni 1.1 Flash สามคลิป ส่วนภาพ พอร์ตเทรต ตัวละคร และการต่อคลิปฟรีทั้งหมด Omni 1.1 Flash ที่ 720p ความยาว 30 วินาทีเท่ากันมีค่าใช้จ่ายราว $3.04 บน [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) ทางการ (ข้อมูล ณ พฤศจิกายน 2026) ดู[ค่าใช้จ่ายจริง](#what-it-cost) ### สรุป ติดต่อเราได้ที่ <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> หรือ <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> สำหรับทุกคำถามและข้อสงสัยด้านการใช้งาน ดูตัวอย่างโค้ดได้ใน [GitHub repo](https://github.com/useapi/google-flow-api) ของเรา #### เผยแพร่ที่อื่นด้วย {: .no_toc #cross-posted } เผยแพร่บน [dev.to](https://dev.to/useapi/how-to-make-a-ugc-product-video-with-the-google-flow-api-4nef){:rel="nofollow"} (ภาษาอังกฤษ) ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-flow-ugc-product-video-vi === Document URL: https://useapi.net/docs/articles/google-flow-ugc-product-video-vi --- layout: default title: "Cách làm video UGC giới thiệu sản phẩm bằng Google Flow API" description: "Làm video UGC giới thiệu sản phẩm dài 29 giây qua Google Flow API của useapi.net: tạo bảng sản phẩm và người dẫn bằng POST /images, một ảnh tĩnh chứa tất cả, ba clip Omni 1.1 Flash 10 giây từ ảnh đó, nâng lên 1080p miễn phí và ghép bằng POST /videos/concatenate." keywords: [UGC video, product video, Google Flow API, Omni 1.1 Flash, product sheets, character, first and last frame, concatenate, video UGC, video giới thiệu sản phẩm, quảng cáo UGC, API video AI, khung đầu và khung cuối, ghép video, bảng sản phẩm, hướng dẫn, code, curl] image: https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/06-ugc-products-still-presenter-and-three-products-nano-banana-2-lite.png video: name: "UGC with the Google Flow API, the 75-second walkthrough" description: "The finished UGC product video, then how it was built: product sheets, a character, one still, three Omni 1.1 Flash clips and one concatenate call, through the useapi.net Google Flow API." url: https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/ugc-google-flow-api-1080p.mp4 embed: https://www.youtube.com/embed/wbUROtDIfGA thumbnail: https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/06-ugc-products-still-presenter-and-three-products-nano-banana-2-lite.png date: 2026-09-04 duration: PT1M15S width: 1080 height: 1920 parent: Articles nav_exclude: true lang: vi translation_key: ugc-product-video date: 2026-09-04 last_modified: 2026-11-06 nav_order: 835 repo: https://github.com/useapi/google-flow-api --- ## Cách làm video UGC giới thiệu sản phẩm bằng Google Flow API {: .no_toc #how-to-make-a-ugc-product-video-with-the-google-flow-api } 8 phút đọc • 4 tháng 9 năm 2026 (6 tháng 11 năm 2026) useapi.net là API của bên thứ ba, không liên kết với Google và không được Google bảo trợ. ## Mục lục {: .no_toc .text-delta #table-of-contents } ### Giới thiệu Một video UGC giới thiệu sản phẩm có thể làm từ đầu đến cuối qua [Google Flow API của useapi.net](/docs/api-google-flow-v1) với 45 credit Flow, không xử lý gì trên máy của bạn. Một người dẫn hư cấu giới thiệu ba sản phẩm hư cấu trước ống kính. UGC là phong cách nội dung do người dùng tạo, tràn ngập bảng tin mạng xã hội và thư viện quảng cáo: một người nói chuyện với camera điện thoại, để bán sản phẩm, để giải trí, hoặc chỉ cho vui. Đây là hướng dẫn đầy đủ từ A đến Z để làm loại video đó ở mức chuyên nghiệp: sản phẩm, người dẫn, lời thoại của cô ấy và bản dựng cuối cùng đều do bạn kiểm soát, qua sáu bước gọi API mà bạn có thể sao chép nguyên văn. Thích một form không cần code? [Workflow quảng cáo UGC trên n8n](/docs/articles/google-flow-n8n-ugc-ads) (tiếng Anh) làm loại quảng cáo này với một trang chọn hoặc tạo lại ở mỗi bước. Đây là kết quả: ba clip Omni 1.1 Flash dài 10 giây được nâng lên 1080p, mọi khung hình và mọi âm thanh đều tạo qua [Google Flow API](/docs/api-google-flow-v1). Cùng lệnh nâng độ phân giải đó cũng lên được 4K khi bạn cần chất lượng chuyên nghiệp, xem [Bước 5](#step-5-upscale-to-1080p): <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 260px;max-width:320px;margin:0"> <video poster="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/10b-ugc-products-joined-29s-1080p-upscaled-concatenated-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/10b-ugc-products-joined-29s-1080p-upscaled-concatenated.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">Kết quả — 29 giây, 1080p, ba sản phẩm, ba clip (Tổng cộng 45 credit)</figcaption> </figure> </div> Nếu bạn thích xem hơn đọc, đây là toàn bộ hướng dẫn trong 75 giây (tiếng Anh): <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 260px;max-width:320px;margin:0"> <div style="position:relative;width:100%;padding-top:177.78%;border-radius:8px;overflow:hidden"> <iframe src="https://www.youtube.com/embed/wbUROtDIfGA" title="UGC with the Google Flow API, the 75-second walkthrough" style="position:absolute;top:0;left:0;width:100%;height:100%;border:0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen loading="lazy"></iframe> </div> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">Video hướng dẫn 75 giây (<a href="https://www.youtube.com/watch?v=wbUROtDIfGA" target="_blank" rel="noopener noreferrer">xem trên YouTube</a> · lời dẫn và nhạc từ <a href="/docs/api-minimax-v1">MiniMax API</a>)</figcaption> </figure> </div> ### Giá Video Omni 1.1 Flash cần một gói Google AI trả phí (Plus, Pro hoặc Ultra), và useapi.net không tính phí theo từng video. Chi phí của video này theo từng bước nằm ở [Chi phí thực tế](#what-it-cost), còn giá mỗi video trên từng gói so với API chính thức nằm ở [bảng giá Google Flow](/docs/api-google-flow-v1#pricing). ### Về các id trong request Mỗi request bên dưới tham chiếu kết quả trước đó bằng `mediaGenerationId`. Các id này dài nên ở đây được rút gọn thành `user:1234-email:…-image:b0bdf3e8-…`, và một dòng dưới mỗi request cho biết mỗi id là kết quả nào trước đó. Id ảnh lấy từ [POST /images](/docs/api-google-flow-v1/post-google-flow-images) ở `media[0].image.generatedImage.mediaGenerationId`, id nhân vật ở trường `character` của [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters), id video ở `media[0].mediaGenerationId` của [job](/docs/api-google-flow-v1/get-google-flow-jobs-jobid) đã hoàn tất, còn id của clip đã nâng độ phân giải là id gốc thêm `_upsampled` ở cuối. ### Bước 1: một bảng cho mỗi sản phẩm Bảng sản phẩm là một ảnh duy nhất cho thấy món đồ từ bốn phía, để model nắm được toàn bộ vật thể chứ không phải một góc may mắn. Dùng [POST /images](/docs/api-google-flow-v1/post-google-flow-images), khung vuông, mỗi sản phẩm một request. Prompt mô tả rõ góc máy cho từng ô, vì nếu chỉ ghi "mặt trước, mặt bên, mặt sau" thì chiếc cốc ra hai ô giống hệt nhau và bàn phím không có mặt bên thật. Vật dẹt như bàn phím cần một ô nhìn từ trên xuống, vật hình khối thì không. Không có tay, không có chữ, không có logo, để không có gì ngoài sản phẩm lọt vào clip. Cách này cũng dùng được cho sản phẩm thật. Tải ảnh sản phẩm lên bằng [POST /assets](/docs/api-google-flow-v1/post-google-flow-assets-email) rồi truyền các id làm `reference_1` đến `reference_4` trong request này, model sẽ biến chúng thành một bảng bốn ô gọn gàng. Mẹo này cũng làm được bảng cho bao bì, logo hoặc cả một bộ sản phẩm. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a> (chiếc cốc)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="1:1"' \ --form 'count="2"' \ --form 'prompt="Orthographic product-catalog sheet on a plain white background: a matte white ceramic mug with a straight cylindrical body and a clearly visible glowing amber light band around its base, about a finger wide, like a smart heated mug. The sheet is divided into four equal panels by thin grey lines in a 2 by 2 grid. Every panel shows the same single item at exactly the same size, position and lighting, camera at the item'\''s eye level unless stated: top-left: side profile, the handle pointing left and seen edge-on; top-right: view from the handle side, the handle pointing straight at the camera; bottom-left: view from the opposite side, the handle hidden behind the body; bottom-right: three-quarter view from slightly above, the handle to the right. Soft even studio light, photoreal. Object only: no hands, no people, no props, no text anywhere, no captions, no labels, no logo, no packaging."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/01-ugc-products-sheet-smart-mug-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/01-ugc-products-sheet-smart-mug-nano-banana-2-lite.png" alt="Bảng sản phẩm của chiếc cốc thông minh, bốn góc nhìn trong lưới 2 x 2" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">Chiếc cốc — Nano Banana 2 Lite, id <code>b0bdf3e8</code> (0 credit)</figcaption> </figure> </div> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a> (robot để bàn)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="1:1"' \ --form 'count="2"' \ --form 'prompt="Orthographic product-catalog sheet on a plain white background: a small rounded pastel mint desk robot, a palm-sized cube with a glossy black screen face showing a happy smiling expression, two round white eyes and a curved white smile, a little rounded antenna nub on top, a small round white dial on its right side, and a speaker grille on its back. The sheet is divided into four equal panels by thin grey lines in a 2 by 2 grid. Every panel shows the same single item at exactly the same size, position and lighting, camera at the item'\''s eye level unless stated: top-left: front view showing the smiling face; top-right: right side view showing the round dial and the antenna nub; bottom-left: back view showing the speaker grille; bottom-right: three-quarter view showing the smiling face and the dial. Soft even studio light, photoreal. Object only: no hands, no people, no props, no text anywhere, no captions, no labels, no logo, no packaging."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/02-ugc-products-sheet-desk-robot-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/02-ugc-products-sheet-desk-robot-nano-banana-2-lite.png" alt="Bảng sản phẩm của robot để bàn, bốn góc nhìn trong lưới 2 x 2" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">Robot để bàn — Nano Banana 2 Lite, id <code>7aaed056</code> (0 credit)</figcaption> </figure> </div> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a> (bàn phím)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="1:1"' \ --form 'count="4"' \ --form 'prompt="Orthographic product-catalog sheet on a plain white background: a real mechanical three-key macro pad, the kind sold for shortcuts: a slim, low-profile white aluminum case, three mechanical key switches in one row with sculpted dished keycaps and a small gap between them, coral on the left, lemon yellow in the middle, sky blue on the right, a USB-C port on the back edge. Exactly three keys in one row, never more. The sheet is divided into four equal panels by thin grey lines in a 2 by 2 grid. Every panel shows the same single item at exactly the same size, position and lighting, camera at the item'\''s eye level unless stated: top-left: top-down view straight from above, the three keys in a row left to right; top-right: front view at eye level; bottom-left: left side view at eye level, the slim case and the keycap profile seen edge-on; bottom-right: three-quarter view from above. Soft even studio light, photoreal. Object only: no hands, no people, no props, no text anywhere, no captions, no labels, no logo, no packaging."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/03-ugc-products-sheet-three-key-keyboard-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/03-ugc-products-sheet-three-key-keyboard-nano-banana-2-lite.png" alt="Bảng sản phẩm của bàn phím ba phím, bốn góc nhìn trong lưới 2 x 2" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">Bàn phím — Nano Banana 2 Lite, id <code>4f861c23</code> (0 credit)</figcaption> </figure> </div> Tạo ảnh không tốn gì, nên hãy đặt `count` từ 2 đến 4 và giữ lại bảng đẹp nhất. Bàn phím mất vài lượt thử cho đến khi prompt mô tả đúng một macro pad thật có ô nhìn từ trên xuống, còn khối lập phương thì đạt ngay lần đầu. ### Bước 2: người dẫn Ba lệnh gọi. Một ảnh chân dung chính diện từ mô tả. Một ảnh chân dung góc ba phần tư tạo từ ảnh đầu tiên bằng `reference_1`, để hai ảnh khớp khuôn mặt. Rồi [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters) với cả hai ảnh, trả về một tham chiếu nhân vật. Từ đó cô ấy là `@character_1` trong mọi prompt, và Google giữ cố định cô ấy bằng hệ thống thực thể của riêng mình thay vì bằng một đoạn mô tả. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a> (chân dung chính diện)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="3:4"' \ --form 'count="2"' \ --form 'prompt="Character reference portrait, photoreal, natural skin, no heavy retouching: a strikingly attractive young woman in her early twenties with a sleek platinum-blonde blunt bob and straight bangs, dark defined eyebrows, icy grey eyes, a tiny silver nose stud, a playful smirk with a hint of teeth, wearing a fitted black turtleneck and a thin gold chain necklace. Head and shoulders, facing the camera straight on, plain light-grey studio background, soft even light. No text, no logo, no captions."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/04-ugc-products-presenter-front-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/04-ugc-products-presenter-front-nano-banana-2-lite.png" alt="Chân dung chính diện của người dẫn" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">Chính diện — Nano Banana 2 Lite, id <code>a236ef66</code> (0 credit)</figcaption> </figure> </div> Chúng tôi tạo vài phong cách và chọn phong cách này. Nếu sau đó cần đổi một chi tiết, chẳng hạn sợi dây chuyền, hãy tạo lại cô ấy với chính ảnh chân dung của cô ấy làm `reference_1` và một prompt chỉ nêu thay đổi, khuôn mặt sẽ được giữ nguyên. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a> (chân dung góc ba phần tư)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="3:4"' \ --form 'count="1"' \ --form 'reference_1="user:1234-email:…-image:a236ef66-…"' \ --form 'prompt="@reference_1 is the same woman: identical face, hair, freckles, sweater and earrings. Three-quarter view from the waist up, relaxed natural smile, plain light-grey studio background, soft even light. Photoreal, no text."' ``` </details> `reference_1` là ảnh chân dung chính diện, `a236ef66`. Prompt này vẫn nhắc đến tàn nhang, áo len và hoa tai còn sót lại từ một người dẫn trước đó, và điều đó không gây hại gì: khi request có ảnh tham chiếu, ảnh tham chiếu thắng chữ. <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/05-ugc-products-presenter-three-quarter-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/05-ugc-products-presenter-three-quarter-nano-banana-2-lite.png" alt="Chân dung góc ba phần tư của người dẫn, tạo từ ảnh chân dung chính diện" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">Ba phần tư — id <code>d891301c</code> (0 credit)</figcaption> </figure> </div> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-characters">POST /characters</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/characters' \ --header 'Authorization: Bearer user:1234-…' \ --form 'displayName="Mia"' \ --form 'personalityNotes="Quick, bright, deadpan delivery with a smile in her voice. Talks to the camera like a friend showing off things she bought at 2am."' \ --form 'imageReference_1="user:1234-email:…-image:a236ef66-…"' \ --form 'imageReference_2="user:1234-email:…-image:d891301c-…"' \ --form 'voice="Leda"' ``` </details> `imageReference_1` là ảnh chính diện `a236ef66`, `imageReference_2` là ảnh ba phần tư `d891301c`. Trường `character` trong response là id của cô ấy, bên dưới là `53ca1036`. `voice` là một trong các giọng có sẵn của hệ thống Google và đi kèm nhân vật, nhưng không tới được chế độ clip dùng ở Bước 4, xem [Những điều cần biết](#what-to-expect). ### Bước 3: ảnh tĩnh, cả cảnh trong một khung hình Một request ghép tất cả lại. Nhân vật vào dưới dạng `character_1`, ba bảng sản phẩm là `reference_1` đến `reference_3`, và prompt đặt chúng theo tag, từ trái sang phải trên bàn trước mặt cô ấy. Khung hình này trở thành cả hai đầu của mọi clip, nên đây là nơi duy nhất các tag phát huy tác dụng. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="9:16"' \ --form 'count="2"' \ --form 'character_1="user:1234-email:…-character:53ca1036-…"' \ --form 'reference_1="user:1234-email:…-image:b0bdf3e8-…"' \ --form 'reference_2="user:1234-email:…-image:7aaed056-…"' \ --form 'reference_3="user:1234-email:…-image:4f861c23-…"' \ --form 'prompt="Full-frame vertical phone video look, no phone, no bezel. @character_1 sits at a light wooden table in a bright minimal creator studio, facing the camera, waist-up and centered, a plain warm-grey backdrop behind her, soft key light from the left with a gentle catchlight in her eyes. Laid out on the table in front of her, left to right, each fully visible and resting flat on the table: the mug from @reference_1, the desk robot from @reference_2, the keyboard from @reference_3. Her hands rest on the table, relaxed closed-mouth smile, eyes on the lens. Photoreal, no text, no captions."' ``` </details> `character_1` là nhân vật ở Bước 2, `53ca1036`. `reference_1` đến `reference_3` là ba bảng sản phẩm ở Bước 1: chiếc cốc `b0bdf3e8`, robot để bàn `7aaed056`, bàn phím `4f861c23`. <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/06-ugc-products-still-presenter-and-three-products-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/06-ugc-products-still-presenter-and-three-products-nano-banana-2-lite.png" alt="Người dẫn ngồi bên bàn, trước mặt là chiếc cốc, robot để bàn và bàn phím" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">Ảnh tĩnh — khuôn mặt từ nhân vật, mỗi sản phẩm từ bảng của nó, id <code>034cddc8</code> (0 credit)</figcaption> </figure> </div> Chiếc cốc có vòng sáng, robot có khuôn mặt và ăng-ten, bàn phím có ba màu và cổng cắm, và cô ấy đúng là người phụ nữ trong các ảnh chân dung. ### Bước 4: mỗi sản phẩm một clip, tất cả từ ảnh tĩnh Dùng chế độ khung đầu + khung cuối của Omni với ảnh tĩnh ở cả hai vị trí, mỗi sản phẩm một request, mỗi lần cùng một [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos). Chế độ này chỉ nhận hai ảnh, không nhận bảng sản phẩm, nhân vật hay giọng tham chiếu. Không sao cả, vì ảnh tĩnh đã chứa tất cả. Mọi món đồ cô ấy cầm lên đều khớp với bảng của nó chỉ nhờ ảnh tĩnh. Prompt làm ba việc. Nó ghim cả hai đầu vào khung hình, với một nhịp lặng ở mỗi bên. Nó cho cô ấy lời thoại và giọng nói. Và nó canh thời gian cho động tác: cô ấy bắt đầu nói khi nhấc món đồ lên, món đồ về lại chỗ cũ trước mốc giây thứ tám, và hai giây cuối là một nhịp đứng yên, im lặng. Thiếu phần cuối này, cô ấy bị chậm và cánh tay giật vào khung cuối. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos">POST /videos</a> (chiếc cốc)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'model="omni-flash"' \ --form 'aspectRatio="portrait"' \ --form 'duration="10"' \ --form 'resolution="720p"' \ --form 'startImage="user:1234-email:…-image:034cddc8-…"' \ --form 'endImage="user:1234-email:…-image:034cddc8-…"' \ --form 'prompt="She begins and ends exactly on this frame: hands resting on the table, the three items laid out in front of her, a small closed-mouth smile, looking into the lens, with a short quiet beat before she moves and another after she settles back. Timing matters: after a short quiet beat she picks up the mug on the left with both hands and starts talking as she lifts it, holding it up to the camera and talking straight to the lens, quick and bright with a deadpan edge and a smile in her voice, keeping both hands on the mug while she speaks. She says: \"Three gadgets smarter than me. Low bar. One: this mug texts me when my coffee'\''s cold. Better follow-up than my ex.\" Right after the last word she gives one short laugh to herself, still holding the mug. By the eight-second mark the mug is back down gently in exactly the same spot and both hands are resting on the table again, brought back in one calm unhurried movement. For the final two seconds she holds completely still, hands resting on the table, looking into the lens with a small closed-mouth smile. Natural room tone, no music, no captions, no text on screen."' ``` </details> `startImage` và `endImage` đều là ảnh tĩnh ở Bước 3, `034cddc8`. Cùng hai id đó dùng cho cả ba clip. <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 220px;max-width:260px;margin:0"> <video poster="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/07b-ugc-products-clip-1-smart-mug-10s-omni-1.1-flash-1080p-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/07b-ugc-products-clip-1-smart-mug-10s-omni-1.1-flash-1080p.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">Clip 1, chiếc cốc — 10 giây, id <code>55808825</code>, bản đã nâng lên 1080p ở Bước 5 (15 credit)</figcaption> </figure> </div> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos">POST /videos</a> (robot để bàn)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'model="omni-flash"' \ --form 'aspectRatio="portrait"' \ --form 'duration="10"' \ --form 'resolution="720p"' \ --form 'startImage="user:1234-email:…-image:034cddc8-…"' \ --form 'endImage="user:1234-email:…-image:034cddc8-…"' \ --form 'prompt="She begins and ends exactly on this frame: hands resting on the table, the three items laid out in front of her, a small closed-mouth smile, looking into the lens, with a short quiet beat before she moves and another after she settles back. Timing matters: after a short quiet beat she picks up the desk robot in the middle with both hands and starts talking as she lifts it, holding it up to the camera with its smiling face toward the lens and turning it once and talking straight to the lens, quick and bright with a deadpan edge and a smile in her voice, keeping both hands on it while she speaks. The other two items stay on the table exactly where they are. She says: \"Two: a desk robot that reacts to my day. It has a face. It has never once looked impressed.\" Right after the last word she raises one eyebrow at the camera, a quick expressive beat, still holding the desk robot. By the eight-second mark the desk robot is back down gently in exactly the same spot and both hands are resting on the table again, brought back in one calm unhurried movement. For the final two seconds she is silent and holds completely still, hands resting on the table, looking into the lens with a small closed-mouth smile. Natural room tone, no music, no captions, no text on screen."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 220px;max-width:260px;margin:0"> <video poster="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/08b-ugc-products-clip-2-desk-robot-10s-omni-1.1-flash-1080p-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/08b-ugc-products-clip-2-desk-robot-10s-omni-1.1-flash-1080p.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">Clip 2, robot để bàn — 10 giây, id <code>c4d0e6b1</code>, bản đã nâng lên 1080p ở Bước 5 (15 credit)</figcaption> </figure> </div> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos">POST /videos</a> (bàn phím)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'model="omni-flash"' \ --form 'aspectRatio="portrait"' \ --form 'duration="10"' \ --form 'resolution="720p"' \ --form 'startImage="user:1234-email:…-image:034cddc8-…"' \ --form 'endImage="user:1234-email:…-image:034cddc8-…"' \ --form 'prompt="She begins and ends exactly on this frame: hands resting on the table, the three items laid out in front of her, a small closed-mouth smile, looking into the lens, with a short quiet beat before she moves and another after she settles back. Timing matters: after a short quiet beat she picks up the keyboard on the right with both hands and starts talking as she lifts it, holding it up to the camera with the three keys facing the lens and talking straight to the lens, quick and bright with a deadpan edge and a smile in her voice, keeping both hands on it while she speaks. The other two items stay on the table exactly where they are. She says: \"Three: a keyboard with three keys. Copy, paste, undo. That'\''s my whole career. Oh, the mug'\''s texting. Bye!\" Right after the last word she raises one eyebrow at the camera, a quick expressive beat, still holding the keyboard. By the eight-second mark the keyboard is back down gently in exactly the same spot and both hands are resting on the table again, brought back in one calm unhurried movement. For the final two seconds she is silent and holds completely still, hands resting on the table, looking into the lens with a small closed-mouth smile. Natural room tone, no music, no captions, no text on screen."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 220px;max-width:260px;margin:0"> <video poster="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/09b-ugc-products-clip-3-three-key-keyboard-10s-omni-1.1-flash-1080p-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/09b-ugc-products-clip-3-three-key-keyboard-10s-omni-1.1-flash-1080p.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">Clip 3, bàn phím — 10 giây, id <code>3cc8ea2f</code>, bản đã nâng lên 1080p ở Bước 5 (15 credit)</figcaption> </figure> </div> Cùng một người phụ nữ, cùng chiếc bàn, cùng ánh sáng, và clip nào cũng mở đầu và kết thúc ở ảnh tĩnh, nên clip nào cũng nối được sau clip nào. Mỗi lời thoại khoảng 20 từ tiếng Anh, vừa đủ cho 10 giây ở nhịp này mà vẫn còn chỗ cho nhịp nghỉ ở cuối. ### Bước 5: nâng lên 1080p Omni 1.1 Flash xuất ở 720p. [POST /videos/upscale](/docs/api-google-flow-v1/post-google-flow-videos-upscale) nâng clip lên 1080p miễn phí trên mọi gói trả phí, trong khoảng 40 giây, và trả về ngay trong cùng lệnh gọi id và URL của clip đã nâng. Mỗi clip một request, không cần `email`, tài khoản được xác định từ id. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos-upscale">POST /videos/upscale</a> (chiếc cốc, rồi làm tương tự với hai clip còn lại)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos/upscale' \ --header 'Authorization: Bearer user:1234-…' \ --form 'mediaGenerationId="user:1234-email:…-video:55808825-…"' \ --form 'resolution="1080p"' ``` </details> `mediaGenerationId` là clip chiếc cốc ở Bước 4, `55808825`. Cùng lệnh gọi đó với `c4d0e6b1` và `3cc8ea2f` sẽ nâng robot và bàn phím. Mỗi response trả clip mới ở `media[0].mediaGenerationId`, chính là id gốc thêm `_upsampled` ở cuối, nên ba id đã nâng là `55808825-…_upsampled`, `c4d0e6b1-…_upsampled` và `3cc8ea2f-…_upsampled`. Các clip hiển thị ở Bước 4 là những bản đã nâng này. Cũng có 4K, giá 50 credit và chỉ có trên gói Google AI Ultra. ### Bước 6: ghép lại [POST /videos/concatenate](/docs/api-google-flow-v1/post-google-flow-videos-concatenate) nhận ba id đã nâng theo thứ tự và trả về file đã ghép dưới dạng base64, ở độ phân giải của các clip. Phần cắt tỉa quyết định chỗ nối có giống một cảnh quay liền hay không. Mỗi clip mở đầu bằng một nhịp dừng ngắn trên ảnh tĩnh và kết thúc bằng việc trở về ảnh đó, nếu không cắt thì các nhịp này chồng lên thành một lần đứng hình ở mỗi chỗ nối. Nhưng cô ấy nói xong mỗi câu khi tay đã đặt sẵn trên bàn, nên nếu chỉ nhìn hình để cắt thì sẽ mất mấy chữ cuối. Hãy cắt sau âm thanh cuối cùng cộng thêm một nhịp, không bao giờ sớm hơn. Với các clip này, điều đó có nghĩa là giữ nguyên clip 1 vì tiếng cười kéo dài đến khung cuối, cắt hơn nửa giây ở cuối clip 2, và vài khung ở đầu clip 2 và 3. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos-concatenate">POST /videos/concatenate</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos/concatenate' \ --header 'Authorization: Bearer user:1234-…' \ --header 'Content-Type: application/json' \ --data '{ "media": [ { "mediaGenerationId": "user:1234-email:…-video:55808825-…_upsampled" }, { "mediaGenerationId": "user:1234-email:…-video:c4d0e6b1-…_upsampled", "trimStart": 0.458, "trimEnd": 0.6 }, { "mediaGenerationId": "user:1234-email:…-video:3cc8ea2f-…_upsampled", "trimStart": 0.125 } ] }' ``` </details> Ba id là các clip đã nâng ở Bước 5 theo thứ tự: chiếc cốc, robot để bàn, bàn phím. <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 260px;max-width:320px;margin:0"> <video poster="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/10b-ugc-products-joined-29s-1080p-upscaled-concatenated-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/10b-ugc-products-joined-29s-1080p-upscaled-concatenated.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">Đã ghép — 28,8 giây, 1080p (0 credit)</figcaption> </figure> </div> Cô ấy nói xong một câu với tay đặt trên bàn, cảnh cắt, rồi cô ấy với lấy món đồ tiếp theo. File đã ghép được mã hóa lại với dung lượng nhỏ hơn để lưu trữ, còn ba clip giữ nguyên như API trả về. ### Những điều cần biết * Tạo mới, đừng chỉnh sửa. Bài [UGC talking head](/blog/260902) (tiếng Anh) kéo dài clip bằng chỉnh sửa video sang video, và cách đó vẫn hiệu quả khi lời thoại ngắn. Ở đây thì không. Một lần chỉnh sửa giữ lời nói của clip gốc trên chính dòng thời gian của clip gốc, nên khi lời thoại 10 giây lấp đầy clip gốc, câu mới bị đan vào câu cũ thay vì thay thế nó, và các sản phẩm còn trên bàn bị biến dạng giữa các lần quay. Tạo từng clip từ ảnh tĩnh cho lời thoại trọn vẹn, sản phẩm nguyên vẹn và chỗ nối sạch hơn, lại tốn ít credit hơn. * Ảnh tĩnh mang các tag. Chế độ khung đầu + khung cuối chỉ nhận hai ảnh. Hãy gắn tag trong ảnh tĩnh, với nhân vật và các bảng sản phẩm, và các clip sẽ kế thừa. * Canh giờ cho động tác. Một clip 10 giây có lời thoại đầy đủ cần chỉ rõ thời điểm đặt đồ xuống theo đồng hồ, "by the eight-second mark" (trước mốc giây thứ tám), và một nhịp đứng yên, im lặng ở cuối. Để tự nhiên, model kéo dài lời thoại rồi nhảy vào khung cuối. * Mô tả giọng nói giống hệt nhau trong mọi prompt. Không có gì mang giọng nói từ clip này sang clip khác, và nhân vật có thể lưu một giọng có sẵn nhưng không tới được chế độ này. Với cùng một mô tả, ba clip ra giọng đủ giống để trông như một cảnh quay liền. * Bảng sản phẩm cần góc máy cho từng ô. Nêu rõ mỗi ô trong bốn ô thể hiện gì. Cho vật dẹt một ô nhìn từ trên xuống. Bỏ tay, chữ và logo ra, vì thứ gì có trên bảng cũng có thể xuất hiện trong clip. * Cắt theo âm thanh, không theo hình. Cô ấy đứng yên trước khi nói xong. Một nhát cắt đặt ở khung đứng yên đầu tiên đã cắt luôn phần cuối câu thoại. * Người dẫn là hư cấu. Google kiểm duyệt chặt hơn với người thật, có thể nhận diện. Hãy bắt đầu từ một nhân vật được tạo ra. ### Chi phí thực tế | Bước | Chế độ | Credit | |---|---|---| | Ba bảng sản phẩm, 1:1 | Nano Banana 2 Lite | 0 | | Hai ảnh chân dung người dẫn, 3:4 | Nano Banana 2 Lite | 0 | | Nhân vật | — | 0 | | Ảnh tĩnh, 9:16 | Nano Banana 2 Lite, nhân vật + 3 tham chiếu | 0 | | Clip 1, chiếc cốc, 10s | I2V, khung đầu + khung cuối | 15 | | Clip 2, robot để bàn, 10s | I2V, khung đầu + khung cuối | 15 | | Clip 3, bàn phím, 10s | I2V, khung đầu + khung cuối | 15 | | Nâng độ phân giải, ba clip lên 1080p | — | 0 | | Ghép | — | 0 | | Tổng | | 45 | Ảnh, nhân vật, nâng lên 1080p và ghép đều miễn phí, nên cứ thoải mái làm lại bảng sản phẩm, người dẫn và ảnh tĩnh trước khi tiêu một credit nào cho video. 4K là nâng cấp duy nhất tốn phí, 50 credit mỗi clip trên Ultra. ### Tự chạy thử Mỗi bước ở trên là một lệnh gọi API, và cả sáu bước nối lại thành một script. Pipeline Node.js đầy đủ, bản Python, và file `prompts.json` chứa mọi prompt trên trang này nằm ở [`useapi/google-flow-api/ugc-product-video`](https://github.com/useapi/google-flow-api/tree/main/ugc-product-video). Clone về, đưa sản phẩm và lời thoại của bạn vào `prompts.json`, và một lệnh duy nhất sẽ dựng cả video. Script lưu checkpoint sau mỗi bước, nên một lần chạy bị gián đoạn sẽ chạy tiếp thay vì trả tiền lại cho các clip, và bạn có thể làm lại riêng một bước — một ảnh tĩnh đẹp hơn, một người dẫn khác — mà không phải tạo lại những gì trước đó. ### Câu hỏi thường gặp - **Tôi có thể dùng ảnh sản phẩm của mình thay cho bảng được tạo không?** Qua useapi.net thì có. Tải ảnh lên bằng [POST /assets](/docs/api-google-flow-v1/post-google-flow-assets-email) và truyền các id trả về làm `reference_1` đến `reference_3` trong request ảnh tĩnh, đúng như cách các bảng được tạo được truyền ở đây. Bảng bốn ô là cách cho model thấy mọi mặt của một vật, và sản phẩm thật cũng được lợi từ cách làm này. - **Sao không chỉnh sửa clip này thành clip tiếp theo, như [bài talking head](/blog/260902) (tiếng Anh)?** Qua useapi.net bạn làm được, nhưng chỉnh sửa video sang video giữ lời nói của clip gốc trên dòng thời gian của clip gốc. Với lời thoại ngắn thì ổn. Khi lời thoại 10 giây lấp đầy clip, câu mới bị đan vào câu cũ và các sản phẩm trên bàn bị biến dạng. Tạo mọi clip từ cùng một ảnh tĩnh tránh được cả hai, và tốn 15 credit thay vì 20. Xem [Những điều cần biết](#what-to-expect). - **Vì sao cả ba clip đều bắt đầu và kết thúc ở cùng một khung hình?** Qua useapi.net, chế độ khung đầu + khung cuối ghim cả hai đầu của mỗi clip vào cùng một ảnh tĩnh, nên các clip nối với nhau theo bất kỳ thứ tự nào mà không thấy vết cắt, và lệnh ghép cắt bỏ các nhịp dừng ngắn ở mỗi chỗ nối. Cơ chế này được giải thích trong bài [UGC talking head](/blog/260902) (tiếng Anh). - **Giọng nói có giữ nguyên giữa các clip không?** Qua useapi.net, ba clip ra giọng đủ giống để trông như một cảnh quay liền, vì giọng được mô tả giống hệt nhau trong mọi prompt. Chế độ khung đầu + khung cuối không nhận tham chiếu âm thanh, và giọng có sẵn của nhân vật không tới được chế độ này. Nếu cần chắc chắn về giọng, chế độ tham chiếu sang video nhận `referenceAudio_1`, đổi lại mất các khung hình được ghim. - **Chi phí bao nhiêu?** Qua useapi.net, cả video 29 giây này tốn $0,36 trên Google AI Ultra $199,99: 45 credit Flow cho ba clip Omni 1.1 Flash, còn mọi ảnh, chân dung, nhân vật và lệnh ghép đều miễn phí. Cùng 30 giây Omni 1.1 Flash ở 720p tốn khoảng $3,04 trên [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) chính thức (tính đến tháng 11/2026). Xem [Chi phí thực tế](#what-it-cost). ### Kết luận Ghé <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> hoặc <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> của chúng tôi cho mọi câu hỏi hỗ trợ. Xem [repo GitHub](https://github.com/useapi/google-flow-api) của chúng tôi với các ví dụ code. #### Đăng ở nơi khác {: .no_toc #cross-posted } Cũng đăng trên [dev.to](https://dev.to/useapi/how-to-make-a-ugc-product-video-with-the-google-flow-api-4nef){:rel="nofollow"} (tiếng Anh). ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-flow-ugc-product-video-zh === Document URL: https://useapi.net/docs/articles/google-flow-ugc-product-video-zh --- layout: default title: "如何用 Google Flow API 制作 UGC 产品视频" description: "通过 useapi.net 的 Google Flow API 制作 29 秒 UGC 产品视频:用 POST /images 生成产品设定图和出镜人物,合成一张包含全部元素的定帧图,从这张图生成三段 10 秒 Omni 1.1 Flash 视频,免费放大到 1080p,再用 POST /videos/concatenate 拼接。" keywords: [UGC video, product video, Google Flow API, Omni 1.1 Flash, product sheets, character, first and last frame, concatenate, UGC 视频, 产品视频, 带货视频, AI 视频 API, 首尾帧, 视频拼接, 产品设定图, 中文教程, Chinese tutorial] image: https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/06-ugc-products-still-presenter-and-three-products-nano-banana-2-lite.png video: name: "UGC with the Google Flow API, the 75-second walkthrough" description: "The finished UGC product video, then how it was built: product sheets, a character, one still, three Omni 1.1 Flash clips and one concatenate call, through the useapi.net Google Flow API." url: https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/ugc-google-flow-api-1080p.mp4 embed: https://www.youtube.com/embed/wbUROtDIfGA thumbnail: https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/06-ugc-products-still-presenter-and-three-products-nano-banana-2-lite.png date: 2026-09-04 duration: PT1M15S width: 1080 height: 1920 parent: Articles nav_exclude: true lang: zh-CN translation_key: ugc-product-video date: 2026-09-04 last_modified: 2026-11-06 nav_order: 835 repo: https://github.com/useapi/google-flow-api --- ## 如何用 Google Flow API 制作 UGC 产品视频 {: .no_toc #how-to-make-a-ugc-product-video-with-the-google-flow-api } 8 分钟阅读 • 2026 年 9 月 4 日(2026 年 11 月 6 日更新) useapi.net 是第三方 API,与 Google 无关联,也未获得 Google 的认可。 ## 目录 {: .no_toc .text-delta #table-of-contents } ### 简介 通过 [useapi.net 的 Google Flow API](/docs/api-google-flow-v1),可以从头到尾做出一条 UGC 产品视频,只花 45 个 Flow 积分,本地不做任何处理。视频里,一位虚构的出镜人物向镜头展示三件虚构的产品。 UGC(用户生成内容)风格的视频充斥着社交媒体信息流和广告库:一个人对着手机镜头说话,可能是在卖产品,可能是在搞笑,也可能只是好玩。 这是一份完整的从 A 到 Z 指南,教你以专业水准制作这类视频:产品、出镜人物、她的台词和最终剪辑全部由你掌控,共六步 API 调用,代码可直接复制使用。更喜欢无代码表单?[n8n UGC 广告工作流](/docs/articles/google-flow-n8n-ugc-ads)(英文)可以生成这类广告,每一步都有选择或重新生成的页面。 下面是成品:三段 10 秒 Omni 1.1 Flash 视频,放大到 1080p,每一帧画面和每一个声音都由 [Google Flow API](/docs/api-google-flow-v1) 生成。同一个放大调用也能输出 4K,满足专业画质需求,见[第 5 步](#step-5-upscale-to-1080p): <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 260px;max-width:320px;margin:0"> <video poster="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/10b-ugc-products-joined-29s-1080p-upscaled-concatenated-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/10b-ugc-products-joined-29s-1080p-upscaled-concatenated.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">成品:29 秒,1080p,三件产品,三段视频 (共 45 积分)</figcaption> </figure> </div> 如果你更想看视频而不是读文字,下面是整篇指南的 75 秒版本(英文): <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 260px;max-width:320px;margin:0"> <div style="position:relative;width:100%;padding-top:177.78%;border-radius:8px;overflow:hidden"> <iframe src="https://www.youtube.com/embed/wbUROtDIfGA" title="UGC with the Google Flow API, the 75-second walkthrough" style="position:absolute;top:0;left:0;width:100%;height:100%;border:0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen loading="lazy"></iframe> </div> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">75 秒演示 (<a href="https://www.youtube.com/watch?v=wbUROtDIfGA" target="_blank" rel="noopener noreferrer">在 YouTube 上观看</a> · 旁白和音乐来自 <a href="/docs/api-minimax-v1">MiniMax API</a>)</figcaption> </figure> </div> ### 价格 Omni 1.1 Flash 视频需要付费的 Google AI 订阅(Plus、Pro 或 Ultra),useapi.net 不按视频收费。这条视频每一步花了多少,见[成本明细](#what-it-cost);各套餐的每条视频价格以及与官方 API 的对比,见 [Google Flow 价格表](/docs/api-google-flow-v1#pricing)。 ### 关于请求中的 id 下面每个请求都通过 `mediaGenerationId` 引用前面步骤的结果。这些 id 很长,所以这里缩写为 `user:1234-email:…-image:b0bdf3e8-…`,每个请求下方都有一行说明每个 id 对应前面的哪个结果。图片 id 来自 [POST /images](/docs/api-google-flow-v1/post-google-flow-images) 返回的 `media[0].image.generatedImage.mediaGenerationId`,角色 id 来自 [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters) 的 `character` 字段,视频 id 来自已完成 [job](/docs/api-google-flow-v1/get-google-flow-jobs-jobid) 的 `media[0].mediaGenerationId`,放大后视频的 id 则是源视频 id 末尾加上 `_upsampled`。 ### 第 1 步:为每件产品生成设定图 产品设定图是一张从四个角度展示物品的图片,让模型掌握整个物体,而不是某一个碰巧好看的角度。使用 [POST /images](/docs/api-google-flow-v1/post-google-flow-images),方形,每件产品一个请求。提示词为每个格子写明机位,因为只写“正面、侧面、背面”时,杯子出现了两个一模一样的格子,键盘也没有真正的侧面。像键盘这样的扁平物体需要一个俯视格,立方体形状的则不需要。不要手、不要文字说明、不要 logo,这样除了产品本身,没有任何东西会混进视频里。 真实产品也可以这样做。用 [POST /assets](/docs/api-google-flow-v1/post-google-flow-assets-email) 上传产品照片,把返回的 id 作为 `reference_1` 到 `reference_4` 传给这个请求,模型就会把它们整理成一张干净的四格设定图。包装、logo 或一整套产品也可以用同样的方法。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a>(杯子)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="1:1"' \ --form 'count="2"' \ --form 'prompt="Orthographic product-catalog sheet on a plain white background: a matte white ceramic mug with a straight cylindrical body and a clearly visible glowing amber light band around its base, about a finger wide, like a smart heated mug. The sheet is divided into four equal panels by thin grey lines in a 2 by 2 grid. Every panel shows the same single item at exactly the same size, position and lighting, camera at the item'\''s eye level unless stated: top-left: side profile, the handle pointing left and seen edge-on; top-right: view from the handle side, the handle pointing straight at the camera; bottom-left: view from the opposite side, the handle hidden behind the body; bottom-right: three-quarter view from slightly above, the handle to the right. Soft even studio light, photoreal. Object only: no hands, no people, no props, no text anywhere, no captions, no labels, no logo, no packaging."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/01-ugc-products-sheet-smart-mug-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/01-ugc-products-sheet-smart-mug-nano-banana-2-lite.png" alt="智能杯的产品设定图,2 x 2 网格中的四个视角" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">杯子:Nano Banana 2 Lite,id <code>b0bdf3e8</code> (0 积分)</figcaption> </figure> </div> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a>(桌面机器人)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="1:1"' \ --form 'count="2"' \ --form 'prompt="Orthographic product-catalog sheet on a plain white background: a small rounded pastel mint desk robot, a palm-sized cube with a glossy black screen face showing a happy smiling expression, two round white eyes and a curved white smile, a little rounded antenna nub on top, a small round white dial on its right side, and a speaker grille on its back. The sheet is divided into four equal panels by thin grey lines in a 2 by 2 grid. Every panel shows the same single item at exactly the same size, position and lighting, camera at the item'\''s eye level unless stated: top-left: front view showing the smiling face; top-right: right side view showing the round dial and the antenna nub; bottom-left: back view showing the speaker grille; bottom-right: three-quarter view showing the smiling face and the dial. Soft even studio light, photoreal. Object only: no hands, no people, no props, no text anywhere, no captions, no labels, no logo, no packaging."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/02-ugc-products-sheet-desk-robot-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/02-ugc-products-sheet-desk-robot-nano-banana-2-lite.png" alt="桌面机器人的产品设定图,2 x 2 网格中的四个视角" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">桌面机器人:Nano Banana 2 Lite,id <code>7aaed056</code> (0 积分)</figcaption> </figure> </div> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a>(键盘)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="1:1"' \ --form 'count="4"' \ --form 'prompt="Orthographic product-catalog sheet on a plain white background: a real mechanical three-key macro pad, the kind sold for shortcuts: a slim, low-profile white aluminum case, three mechanical key switches in one row with sculpted dished keycaps and a small gap between them, coral on the left, lemon yellow in the middle, sky blue on the right, a USB-C port on the back edge. Exactly three keys in one row, never more. The sheet is divided into four equal panels by thin grey lines in a 2 by 2 grid. Every panel shows the same single item at exactly the same size, position and lighting, camera at the item'\''s eye level unless stated: top-left: top-down view straight from above, the three keys in a row left to right; top-right: front view at eye level; bottom-left: left side view at eye level, the slim case and the keycap profile seen edge-on; bottom-right: three-quarter view from above. Soft even studio light, photoreal. Object only: no hands, no people, no props, no text anywhere, no captions, no labels, no logo, no packaging."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/03-ugc-products-sheet-three-key-keyboard-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/03-ugc-products-sheet-three-key-keyboard-nano-banana-2-lite.png" alt="三键键盘的产品设定图,2 x 2 网格中的四个视角" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">键盘:Nano Banana 2 Lite,id <code>4f861c23</code> (0 积分)</figcaption> </figure> </div> 图片不花钱,所以把 `count` 设为 2 到 4,挑最好的一张设定图。键盘试了好几轮,直到提示词描述出一个真实的宏键盘并带有俯视格;立方体的机器人一次就成功了。 ### 第 2 步:出镜人物 三次调用。先根据描述生成一张正面肖像。再用 `reference_1` 以第一张为参考生成一张四分之三侧面肖像,让两张图的脸保持一致。然后用这两张肖像调用 [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters),得到一个角色引用。从此在任何提示词里她都是 `@character_1`,Google 通过自己的实体系统而不是文字描述来锁定她的形象。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a>(正面肖像)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="3:4"' \ --form 'count="2"' \ --form 'prompt="Character reference portrait, photoreal, natural skin, no heavy retouching: a strikingly attractive young woman in her early twenties with a sleek platinum-blonde blunt bob and straight bangs, dark defined eyebrows, icy grey eyes, a tiny silver nose stud, a playful smirk with a hint of teeth, wearing a fitted black turtleneck and a thin gold chain necklace. Head and shoulders, facing the camera straight on, plain light-grey studio background, soft even light. No text, no logo, no captions."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/04-ugc-products-presenter-front-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/04-ugc-products-presenter-front-nano-banana-2-lite.png" alt="出镜人物的正面肖像" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">正面:Nano Banana 2 Lite,id <code>a236ef66</code> (0 积分)</figcaption> </figure> </div> 生成了几种造型,选了这一个。如果之后某个细节需要修改,比如项链,就用她自己的肖像作为 `reference_1` 重新生成,提示词只写要改的地方,脸就不会变。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a>(四分之三侧面肖像)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="3:4"' \ --form 'count="1"' \ --form 'reference_1="user:1234-email:…-image:a236ef66-…"' \ --form 'prompt="@reference_1 is the same woman: identical face, hair, freckles, sweater and earrings. Three-quarter view from the waist up, relaxed natural smile, plain light-grey studio background, soft even light. Photoreal, no text."' ``` </details> `reference_1` 是正面肖像 `a236ef66`。这条提示词里还残留着之前另一位出镜人物的雀斑、毛衣和耳环,但没有造成影响:请求里有参考图时,参考图优先于文字。 <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/05-ugc-products-presenter-three-quarter-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/05-ugc-products-presenter-three-quarter-nano-banana-2-lite.png" alt="出镜人物的四分之三侧面肖像,以正面肖像为参考生成" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">四分之三侧面:id <code>d891301c</code> (0 积分)</figcaption> </figure> </div> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-characters">POST /characters</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/characters' \ --header 'Authorization: Bearer user:1234-…' \ --form 'displayName="Mia"' \ --form 'personalityNotes="Quick, bright, deadpan delivery with a smile in her voice. Talks to the camera like a friend showing off things she bought at 2am."' \ --form 'imageReference_1="user:1234-email:…-image:a236ef66-…"' \ --form 'imageReference_2="user:1234-email:…-image:d891301c-…"' \ --form 'voice="Leda"' ``` </details> `imageReference_1` 是正面肖像 `a236ef66`,`imageReference_2` 是四分之三侧面 `d891301c`。响应的 `character` 字段就是她的 id,下文为 `53ca1036`。`voice` 是 Google 的系统预设音色之一,会跟随角色一起保存,但第 4 步使用的视频模式用不到它,见[注意事项](#what-to-expect)。 ### 第 3 步:定帧图,一帧容纳整个场景 一个请求把所有元素放在一起。角色作为 `character_1` 传入,三张设定图作为 `reference_1` 到 `reference_3`,提示词按标签把它们从左到右摆在她面前的桌子上。这一帧会成为每段视频的首帧和尾帧,所以标签只需要在这里发挥作用。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="9:16"' \ --form 'count="2"' \ --form 'character_1="user:1234-email:…-character:53ca1036-…"' \ --form 'reference_1="user:1234-email:…-image:b0bdf3e8-…"' \ --form 'reference_2="user:1234-email:…-image:7aaed056-…"' \ --form 'reference_3="user:1234-email:…-image:4f861c23-…"' \ --form 'prompt="Full-frame vertical phone video look, no phone, no bezel. @character_1 sits at a light wooden table in a bright minimal creator studio, facing the camera, waist-up and centered, a plain warm-grey backdrop behind her, soft key light from the left with a gentle catchlight in her eyes. Laid out on the table in front of her, left to right, each fully visible and resting flat on the table: the mug from @reference_1, the desk robot from @reference_2, the keyboard from @reference_3. Her hands rest on the table, relaxed closed-mouth smile, eyes on the lens. Photoreal, no text, no captions."' ``` </details> `character_1` 是第 2 步的角色 `53ca1036`。`reference_1` 到 `reference_3` 是第 1 步的三张设定图:杯子 `b0bdf3e8`、桌面机器人 `7aaed056`、键盘 `4f861c23`。 <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/06-ugc-products-still-presenter-and-three-products-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/06-ugc-products-still-presenter-and-three-products-nano-banana-2-lite.png" alt="出镜人物坐在桌前,面前摆着杯子、桌面机器人和键盘" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">定帧图:脸来自角色,每件产品来自各自的设定图,id <code>034cddc8</code> (0 积分)</figcaption> </figure> </div> 杯子有它的灯带,机器人有它的脸和天线,键盘有它的三种颜色和接口,她也正是肖像里的那个人。 ### 第 4 步:每件产品一段视频,全部从定帧图生成 使用 Omni 的首尾帧模式,首帧和尾帧都放定帧图,每件产品一个请求,每次都是同一个 [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos)。这个模式只接受这两张图片,不接受设定图、角色或音色参考。这没关系,因为定帧图里已经包含了这一切。她拿起的每件物品,仅凭定帧图就和设定图完全一致。 提示词承担三项任务。它把首尾两端都钉在这一帧上,两端各留一个安静的停顿。它给出她的台词和声音。它还为动作设定时间:她拿起物品时开始说话,到第八秒物品放回原位,最后两秒静止无声。少了最后这部分,她会拖时间,手臂会突然跳到尾帧的位置。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos">POST /videos</a>(杯子)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'model="omni-flash"' \ --form 'aspectRatio="portrait"' \ --form 'duration="10"' \ --form 'resolution="720p"' \ --form 'startImage="user:1234-email:…-image:034cddc8-…"' \ --form 'endImage="user:1234-email:…-image:034cddc8-…"' \ --form 'prompt="She begins and ends exactly on this frame: hands resting on the table, the three items laid out in front of her, a small closed-mouth smile, looking into the lens, with a short quiet beat before she moves and another after she settles back. Timing matters: after a short quiet beat she picks up the mug on the left with both hands and starts talking as she lifts it, holding it up to the camera and talking straight to the lens, quick and bright with a deadpan edge and a smile in her voice, keeping both hands on the mug while she speaks. She says: \"Three gadgets smarter than me. Low bar. One: this mug texts me when my coffee'\''s cold. Better follow-up than my ex.\" Right after the last word she gives one short laugh to herself, still holding the mug. By the eight-second mark the mug is back down gently in exactly the same spot and both hands are resting on the table again, brought back in one calm unhurried movement. For the final two seconds she holds completely still, hands resting on the table, looking into the lens with a small closed-mouth smile. Natural room tone, no music, no captions, no text on screen."' ``` </details> `startImage` 和 `endImage` 都是第 3 步的定帧图 `034cddc8`。三段视频用的都是这两个 id。 <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 220px;max-width:260px;margin:0"> <video poster="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/07b-ugc-products-clip-1-smart-mug-10s-omni-1.1-flash-1080p-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/07b-ugc-products-clip-1-smart-mug-10s-omni-1.1-flash-1080p.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">片段 1,杯子:10 秒,id <code>55808825</code>,展示的是第 5 步放大到 1080p 后的版本 (15 积分)</figcaption> </figure> </div> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos">POST /videos</a>(桌面机器人)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'model="omni-flash"' \ --form 'aspectRatio="portrait"' \ --form 'duration="10"' \ --form 'resolution="720p"' \ --form 'startImage="user:1234-email:…-image:034cddc8-…"' \ --form 'endImage="user:1234-email:…-image:034cddc8-…"' \ --form 'prompt="She begins and ends exactly on this frame: hands resting on the table, the three items laid out in front of her, a small closed-mouth smile, looking into the lens, with a short quiet beat before she moves and another after she settles back. Timing matters: after a short quiet beat she picks up the desk robot in the middle with both hands and starts talking as she lifts it, holding it up to the camera with its smiling face toward the lens and turning it once and talking straight to the lens, quick and bright with a deadpan edge and a smile in her voice, keeping both hands on it while she speaks. The other two items stay on the table exactly where they are. She says: \"Two: a desk robot that reacts to my day. It has a face. It has never once looked impressed.\" Right after the last word she raises one eyebrow at the camera, a quick expressive beat, still holding the desk robot. By the eight-second mark the desk robot is back down gently in exactly the same spot and both hands are resting on the table again, brought back in one calm unhurried movement. For the final two seconds she is silent and holds completely still, hands resting on the table, looking into the lens with a small closed-mouth smile. Natural room tone, no music, no captions, no text on screen."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 220px;max-width:260px;margin:0"> <video poster="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/08b-ugc-products-clip-2-desk-robot-10s-omni-1.1-flash-1080p-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/08b-ugc-products-clip-2-desk-robot-10s-omni-1.1-flash-1080p.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">片段 2,桌面机器人:10 秒,id <code>c4d0e6b1</code>,展示的是第 5 步放大到 1080p 后的版本 (15 积分)</figcaption> </figure> </div> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos">POST /videos</a>(键盘)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'model="omni-flash"' \ --form 'aspectRatio="portrait"' \ --form 'duration="10"' \ --form 'resolution="720p"' \ --form 'startImage="user:1234-email:…-image:034cddc8-…"' \ --form 'endImage="user:1234-email:…-image:034cddc8-…"' \ --form 'prompt="She begins and ends exactly on this frame: hands resting on the table, the three items laid out in front of her, a small closed-mouth smile, looking into the lens, with a short quiet beat before she moves and another after she settles back. Timing matters: after a short quiet beat she picks up the keyboard on the right with both hands and starts talking as she lifts it, holding it up to the camera with the three keys facing the lens and talking straight to the lens, quick and bright with a deadpan edge and a smile in her voice, keeping both hands on it while she speaks. The other two items stay on the table exactly where they are. She says: \"Three: a keyboard with three keys. Copy, paste, undo. That'\''s my whole career. Oh, the mug'\''s texting. Bye!\" Right after the last word she raises one eyebrow at the camera, a quick expressive beat, still holding the keyboard. By the eight-second mark the keyboard is back down gently in exactly the same spot and both hands are resting on the table again, brought back in one calm unhurried movement. For the final two seconds she is silent and holds completely still, hands resting on the table, looking into the lens with a small closed-mouth smile. Natural room tone, no music, no captions, no text on screen."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 220px;max-width:260px;margin:0"> <video poster="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/09b-ugc-products-clip-3-three-key-keyboard-10s-omni-1.1-flash-1080p-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/09b-ugc-products-clip-3-three-key-keyboard-10s-omni-1.1-flash-1080p.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">片段 3,键盘:10 秒,id <code>3cc8ea2f</code>,展示的是第 5 步放大到 1080p 后的版本 (15 积分)</figcaption> </figure> </div> 同一个人,同一张桌子,同样的光线,而且每段视频都以定帧图开始和结束,所以任意一段都可以接在另一段后面。每段台词大约 20 个英文单词,按这个语速正好装进 10 秒,结尾还留有停顿。 ### 第 5 步:放大到 1080p Omni 1.1 Flash 以 720p 渲染。[POST /videos/upscale](/docs/api-google-flow-v1/post-google-flow-videos-upscale) 在任何付费套餐上都能免费把视频放大到 1080p,大约 40 秒完成,并在同一次调用中返回放大后视频的 id 和 URL。每段视频一个请求,不需要 `email`,账号由 id 决定。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos-upscale">POST /videos/upscale</a>(杯子,另外两段同理)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos/upscale' \ --header 'Authorization: Bearer user:1234-…' \ --form 'mediaGenerationId="user:1234-email:…-video:55808825-…"' \ --form 'resolution="1080p"' ``` </details> `mediaGenerationId` 是第 4 步的杯子视频 `55808825`。用 `c4d0e6b1` 和 `3cc8ea2f` 做同样的调用,就能放大机器人和键盘的视频。每个响应都在 `media[0].mediaGenerationId` 下返回新视频,它就是源 id 末尾加上 `_upsampled`,所以三个放大后的 id 是 `55808825-…_upsampled`、`c4d0e6b1-…_upsampled` 和 `3cc8ea2f-…_upsampled`。第 4 步展示的视频就是这些放大后的版本。也可以放大到 4K,每段 50 积分,且仅限 Google AI Ultra 套餐。 ### 第 6 步:拼接 [POST /videos/concatenate](/docs/api-google-flow-v1/post-google-flow-videos-concatenate) 按顺序接收三个放大后的 id,以 base64 返回拼接好的文件,分辨率与原视频相同。裁剪决定了衔接处是否像一镜到底。每段视频开头在定帧图上有短暂停留,结尾回落到定帧图上,不裁剪的话,每个剪辑点都会叠成一次定格。但她每句台词说完时手已经放回桌上,所以只看画面来裁剪会切掉最后几个字。要在最后一个声音之后再留一拍才剪,不能更早。对这几段视频来说,这意味着片段 1 保持完整(她的笑声一直持续到最后一帧),片段 2 结尾裁掉略多于半秒,片段 2 和片段 3 的开头各裁掉几帧。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos-concatenate">POST /videos/concatenate</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos/concatenate' \ --header 'Authorization: Bearer user:1234-…' \ --header 'Content-Type: application/json' \ --data '{ "media": [ { "mediaGenerationId": "user:1234-email:…-video:55808825-…_upsampled" }, { "mediaGenerationId": "user:1234-email:…-video:c4d0e6b1-…_upsampled", "trimStart": 0.458, "trimEnd": 0.6 }, { "mediaGenerationId": "user:1234-email:…-video:3cc8ea2f-…_upsampled", "trimStart": 0.125 } ] }' ``` </details> 这三个 id 依次是第 5 步放大后的视频:杯子、桌面机器人、键盘。 <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 260px;max-width:320px;margin:0"> <video poster="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/10b-ugc-products-joined-29s-1080p-upscaled-concatenated-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/10b-ugc-products-joined-29s-1080p-upscaled-concatenated.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">拼接后:28.8 秒,1080p (0 积分)</figcaption> </figure> </div> 她说完一句,手放在桌上,镜头切换,她伸手去拿下一件物品。拼接后的文件为了托管重新编码成了更小的体积,三段视频则保持 API 返回的原样。 ### 注意事项 * 生成,而不是编辑。[UGC 口播视频](/blog/260902)(英文)一文用视频到视频编辑来延长视频,台词短的时候这样仍然可行。但这里不行。编辑会把源视频的语音保留在源视频自己的时间线上,当 10 秒的台词填满源视频时,新台词会和旧台词交织在一起,而不是替换它,桌上的产品在不同镜头之间也会走样。从定帧图生成每段视频,台词完整,产品不变形,衔接更干净,花的积分也更少。 * 标签由定帧图承载。首尾帧模式只接受两张图片。在定帧图里用角色和设定图完成标签,视频就会继承它们。 * 给动作计时。一段装满台词的 10 秒视频,需要按时间点明放下物品的时刻,即“by the eight-second mark”(到第八秒),结尾再留一段静止无声的停留。放任不管的话,模型会把台词拖长,然后跳到尾帧。 * 每条提示词用同样的方式描述声音。不同的视频之间没有任何东西会传递声音,角色虽然可以保存音色预设,但用不到这个模式里。用完全相同的描述,三段视频的声音接近到可以当成一镜到底。 * 设定图需要为每格指定机位。写明四个格子分别展示什么。扁平物体要有俯视格。不要手、文字说明和 logo,因为设定图上的任何东西都可能出现在视频里。 * 按声音裁剪,而不是按画面。她在说完话之前就已经静止。在第一个静止帧处剪切,会把台词的结尾一起剪掉。 * 出镜人物是虚构的。Google 对真实、可识别人物的审核更严格。从生成的角色开始。 ### 成本明细 | 步骤 | 模式 | 积分 | |---|---|---| | 三张产品设定图,1:1 | Nano Banana 2 Lite | 0 | | 两张出镜人物肖像,3:4 | Nano Banana 2 Lite | 0 | | 角色 | — | 0 | | 定帧图,9:16 | Nano Banana 2 Lite,角色 + 3 张参考图 | 0 | | 片段 1,杯子,10 秒 | 图生视频,首帧 + 尾帧 | 15 | | 片段 2,桌面机器人,10 秒 | 图生视频,首帧 + 尾帧 | 15 | | 片段 3,键盘,10 秒 | 图生视频,首帧 + 尾帧 | 15 | | 放大,三段视频到 1080p | — | 0 | | 拼接 | — | 0 | | 合计 | | 45 | 图片、角色、1080p 放大和拼接都不花钱,所以在花第一个积分生成视频之前,可以尽情反复调整设定图、出镜人物和定帧图。唯一要花钱的升级是 4K,在 Ultra 上每段 50 积分。 ### 自己动手运行 上面的每一步都是一次 API 调用,六步可以串成一个脚本。完整的 Node.js 流水线、Python 版本,以及包含本页所有提示词的 `prompts.json` 都在 [`useapi/google-flow-api/ugc-product-video`](https://github.com/useapi/google-flow-api/tree/main/ugc-product-video)。克隆仓库,在 `prompts.json` 里换上你自己的产品和台词,一条命令就能生成整条视频。 脚本在每一步之后都会保存检查点,中断的运行可以继续,而不必重新为视频付费;你也可以只重做某一步,比如换一张更好的定帧图或换一位出镜人物,而不必重新生成之前的内容。 ### 常见问题 - **可以用我自己的产品照片代替生成的设定图吗?** 通过 useapi.net 可以。用 [POST /assets](/docs/api-google-flow-v1/post-google-flow-assets-email) 上传照片,把返回的 id 作为 `reference_1` 到 `reference_3` 传给定帧图请求,和这里传入生成的设定图完全一样。四格设定图是让模型看到物体每一面的方法,真实产品同样受益。 - **为什么不像[口播视频那篇文章](/blog/260902)(英文)那样,把一段视频编辑成下一段?** 通过 useapi.net 可以这样做,但视频到视频编辑会把源视频的语音保留在源视频的时间线上。台词短时没问题。当 10 秒的台词填满整段视频时,新台词会和旧台词交织在一起,桌上的产品也会走样。从同一张定帧图生成每段视频可以避免这两个问题,而且每段只要 15 积分而不是 20。见[注意事项](#what-to-expect)。 - **为什么三段视频都以同一帧开始和结束?** 通过 useapi.net,首尾帧模式把每段视频的两端都钉在同一张定帧图上,所以视频可以按任意顺序衔接,看不出剪辑痕迹,拼接调用再把每个衔接处的短暂停留裁掉。原理见 [UGC 口播视频](/blog/260902)(英文)一文。 - **三段视频的声音能保持一致吗?** 通过 useapi.net,三段视频的声音接近到可以当成一镜到底,因为每条提示词对声音的描述完全相同。首尾帧模式不接受音频参考,角色的音色预设也用不到它。如果需要保证声音一致,参考生视频模式接受 `referenceAudio_1`,代价是失去固定的首尾帧。 - **要花多少钱?** 通过 useapi.net,这整条 29 秒的视频在 Google AI Ultra($199.99)上只花 $0.36:三段 Omni 1.1 Flash 视频共 45 个 Flow 积分,所有图片、肖像、角色和拼接都免费。同样 30 秒的 720p Omni 1.1 Flash 视频,在官方 [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) 上约 $3.04(截至 2026 年 11 月)。见[成本明细](#what-it-cost)。 ### 结语 有问题欢迎加入我们的 <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord 服务器</a> 或 <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram 频道</a>。 示例代码见 [GitHub 仓库](https://github.com/useapi/google-flow-api)。 #### 其他发布平台 {: .no_toc #cross-posted } 本文英文版也发布在 [dev.to](https://dev.to/useapi/how-to-make-a-ugc-product-video-with-the-google-flow-api-4nef){:rel="nofollow"}。 ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-flow-ugc-product-video === Document URL: https://useapi.net/docs/articles/google-flow-ugc-product-video --- layout: default title: How to Make a UGC Product Video with the Google Flow API description: "Build a 29-second UGC product video through the useapi.net Google Flow API: product sheets and a presenter from POST /images, one still that carries them all, three 10-second Omni 1.1 Flash clips from that still, a free upscale to 1080p, and POST /videos/concatenate to join them." keywords: [UGC video, product video, Google Flow API, Omni 1.1 Flash, product sheets, character, first and last frame, concatenate, tutorial] image: https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/06-ugc-products-still-presenter-and-three-products-nano-banana-2-lite.png video: name: "UGC with the Google Flow API, the 75-second walkthrough" description: "The finished UGC product video, then how it was built: product sheets, a character, one still, three Omni 1.1 Flash clips and one concatenate call, through the useapi.net Google Flow API." url: https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/ugc-google-flow-api-1080p.mp4 embed: https://www.youtube.com/embed/wbUROtDIfGA thumbnail: https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/06-ugc-products-still-presenter-and-three-products-nano-banana-2-lite.png date: 2026-09-04 duration: PT1M15S width: 1080 height: 1920 parent: Articles nav_exclude: true date: 2026-09-04 last_modified: 2026-11-06 nav_order: 835 repo: https://github.com/useapi/google-flow-api translation_key: ugc-product-video --- ## How to Make a UGC Product Video with the Google Flow API 8 min read • September 4, 2026 (November 6, 2026) ## Table of contents ### Introduction A UGC product video can be built end to end through the [useapi.net Google Flow API](/docs/api-google-flow-v1) for 45 Flow credits, with nothing processed locally. One invented presenter shows three invented products to the camera. UGC is the user-generated-content style that fills social feeds and ad libraries: one person talking to a phone camera, to sell a product, to entertain, or just for fun. This is the full A-to-Z guide to producing that kind of video at a professional level: the products, the presenter, her lines and the final cut all under your control, in six steps of API calls you can copy as they are. Prefer a no-code form? The [n8n UGC ads workflow](/docs/articles/google-flow-n8n-ugc-ads) builds this kind of ad with a pick or re-roll page at every step. Here is the result, three 10-second Omni 1.1 Flash clips upscaled to 1080p, every frame and every sound produced through the [Google Flow API](/docs/api-google-flow-v1). The same upscale call goes to 4K when you need professional quality, see [Step 5](#step-5-upscale-to-1080p): <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 260px;max-width:320px;margin:0"> <video poster="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/10b-ugc-products-joined-29s-1080p-upscaled-concatenated-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/10b-ugc-products-joined-29s-1080p-upscaled-concatenated.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">The result — 29 seconds, 1080p, three products, three clips (45 credits in total)</figcaption> </figure> </div> If you would rather watch than read, here is the whole guide in 75 seconds: <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 260px;max-width:320px;margin:0"> <div style="position:relative;width:100%;padding-top:177.78%;border-radius:8px;overflow:hidden"> <iframe src="https://www.youtube.com/embed/wbUROtDIfGA" title="UGC with the Google Flow API, the 75-second walkthrough" style="position:absolute;top:0;left:0;width:100%;height:100%;border:0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen loading="lazy"></iframe> </div> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">The 75-second walkthrough (<a href="https://www.youtube.com/watch?v=wbUROtDIfGA" target="_blank" rel="noopener noreferrer">watch on YouTube</a> · narration and music from the <a href="/docs/api-minimax-v1">MiniMax API</a>)</figcaption> </figure> </div> ### Pricing Omni 1.1 Flash video needs a paid Google AI subscription (Plus, Pro or Ultra), and useapi.net adds no per-video charge. What this video cost, step by step, is in [What it cost](#what-it-cost), and the price per video on every plan, against the official API, is in the [Google Flow price table](/docs/api-google-flow-v1#pricing). ### About the ids in the requests Every request below refers to earlier results by their `mediaGenerationId`. The ids are long, so they are shortened here to `user:1234-email:…-image:b0bdf3e8-…`, and a line under each request says which earlier result each one is. An image id comes back from [POST /images](/docs/api-google-flow-v1/post-google-flow-images) under `media[0].image.generatedImage.mediaGenerationId`, a character id in the `character` field of [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters), a video id under `media[0].mediaGenerationId` of the finished [job](/docs/api-google-flow-v1/get-google-flow-jobs-jobid), and an upscaled clip's id is its source's id with `_upsampled` on the end. ### Step 1: a sheet for each product A product sheet is one image that shows the item from four sides, so the model has the whole object and not one lucky angle. [POST /images](/docs/api-google-flow-v1/post-google-flow-images), square, one request per product. The prompt spells out the camera for every panel, because "front, side, back" on its own gave two identical panels for the mug and no true side for the keyboard. A flat object like the keyboard needs a top-down panel, a cube-shaped one does not. No hands, no captions, no logos, so nothing but the product can leak into the clips. The same works for a real product. Upload photos of it with [POST /assets](/docs/api-google-flow-v1/post-google-flow-assets-email) and pass their ids as `reference_1` to `reference_4` on this request, and the model turns them into a clean four-panel sheet. The same trick makes a sheet for a package, a logo or a set. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a> (the mug)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="1:1"' \ --form 'count="2"' \ --form 'prompt="Orthographic product-catalog sheet on a plain white background: a matte white ceramic mug with a straight cylindrical body and a clearly visible glowing amber light band around its base, about a finger wide, like a smart heated mug. The sheet is divided into four equal panels by thin grey lines in a 2 by 2 grid. Every panel shows the same single item at exactly the same size, position and lighting, camera at the item'\''s eye level unless stated: top-left: side profile, the handle pointing left and seen edge-on; top-right: view from the handle side, the handle pointing straight at the camera; bottom-left: view from the opposite side, the handle hidden behind the body; bottom-right: three-quarter view from slightly above, the handle to the right. Soft even studio light, photoreal. Object only: no hands, no people, no props, no text anywhere, no captions, no labels, no logo, no packaging."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/01-ugc-products-sheet-smart-mug-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/01-ugc-products-sheet-smart-mug-nano-banana-2-lite.png" alt="Product sheet of the smart mug, four views in a 2 by 2 grid" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">The mug — Nano Banana 2 Lite, id <code>b0bdf3e8</code> (0 credits)</figcaption> </figure> </div> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a> (the desk robot)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="1:1"' \ --form 'count="2"' \ --form 'prompt="Orthographic product-catalog sheet on a plain white background: a small rounded pastel mint desk robot, a palm-sized cube with a glossy black screen face showing a happy smiling expression, two round white eyes and a curved white smile, a little rounded antenna nub on top, a small round white dial on its right side, and a speaker grille on its back. The sheet is divided into four equal panels by thin grey lines in a 2 by 2 grid. Every panel shows the same single item at exactly the same size, position and lighting, camera at the item'\''s eye level unless stated: top-left: front view showing the smiling face; top-right: right side view showing the round dial and the antenna nub; bottom-left: back view showing the speaker grille; bottom-right: three-quarter view showing the smiling face and the dial. Soft even studio light, photoreal. Object only: no hands, no people, no props, no text anywhere, no captions, no labels, no logo, no packaging."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/02-ugc-products-sheet-desk-robot-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/02-ugc-products-sheet-desk-robot-nano-banana-2-lite.png" alt="Product sheet of the desk robot, four views in a 2 by 2 grid" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">The desk robot — Nano Banana 2 Lite, id <code>7aaed056</code> (0 credits)</figcaption> </figure> </div> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a> (the keyboard)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="1:1"' \ --form 'count="4"' \ --form 'prompt="Orthographic product-catalog sheet on a plain white background: a real mechanical three-key macro pad, the kind sold for shortcuts: a slim, low-profile white aluminum case, three mechanical key switches in one row with sculpted dished keycaps and a small gap between them, coral on the left, lemon yellow in the middle, sky blue on the right, a USB-C port on the back edge. Exactly three keys in one row, never more. The sheet is divided into four equal panels by thin grey lines in a 2 by 2 grid. Every panel shows the same single item at exactly the same size, position and lighting, camera at the item'\''s eye level unless stated: top-left: top-down view straight from above, the three keys in a row left to right; top-right: front view at eye level; bottom-left: left side view at eye level, the slim case and the keycap profile seen edge-on; bottom-right: three-quarter view from above. Soft even studio light, photoreal. Object only: no hands, no people, no props, no text anywhere, no captions, no labels, no logo, no packaging."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/03-ugc-products-sheet-three-key-keyboard-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/03-ugc-products-sheet-three-key-keyboard-nano-banana-2-lite.png" alt="Product sheet of the three-key keyboard, four views in a 2 by 2 grid" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">The keyboard — Nano Banana 2 Lite, id <code>4f861c23</code> (0 credits)</figcaption> </figure> </div> Images cost nothing, so ask for `count` of 2 to 4 and keep the best sheet. The keyboard took a few rounds before its prompt described a real macro pad with a top-down panel, the cube worked first time. ### Step 2: the presenter Three calls. A front portrait from a description. A three-quarter portrait generated from the first one with `reference_1`, so the two agree on the face. Then [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters) with both portraits, which returns a character reference. From then on she is `@character_1` in any prompt, and Google pins her through its own entity system instead of through a description. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a> (front portrait)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="3:4"' \ --form 'count="2"' \ --form 'prompt="Character reference portrait, photoreal, natural skin, no heavy retouching: a strikingly attractive young woman in her early twenties with a sleek platinum-blonde blunt bob and straight bangs, dark defined eyebrows, icy grey eyes, a tiny silver nose stud, a playful smirk with a hint of teeth, wearing a fitted black turtleneck and a thin gold chain necklace. Head and shoulders, facing the camera straight on, plain light-grey studio background, soft even light. No text, no logo, no captions."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/04-ugc-products-presenter-front-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/04-ugc-products-presenter-front-nano-banana-2-lite.png" alt="Front portrait of the presenter" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">Front — Nano Banana 2 Lite, id <code>a236ef66</code> (0 credits)</figcaption> </figure> </div> Rendered a few looks, picked this one. If a detail needs changing afterwards (the chain, say), re-render her with her own portrait as `reference_1` and a prompt that names only the change, and the face stays put. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a> (three-quarter portrait)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="3:4"' \ --form 'count="1"' \ --form 'reference_1="user:1234-email:…-image:a236ef66-…"' \ --form 'prompt="@reference_1 is the same woman: identical face, hair, freckles, sweater and earrings. Three-quarter view from the waist up, relaxed natural smile, plain light-grey studio background, soft even light. Photoreal, no text."' ``` </details> `reference_1` is the front portrait, `a236ef66`. This prompt still mentions freckles, a sweater and earrings left over from an earlier presenter, and it did no harm: with a reference image in the request, the reference wins over the words. <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/05-ugc-products-presenter-three-quarter-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/05-ugc-products-presenter-three-quarter-nano-banana-2-lite.png" alt="Three-quarter portrait of the presenter, generated from the front portrait" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">Three-quarter — id <code>d891301c</code> (0 credits)</figcaption> </figure> </div> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-characters">POST /characters</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/characters' \ --header 'Authorization: Bearer user:1234-…' \ --form 'displayName="Mia"' \ --form 'personalityNotes="Quick, bright, deadpan delivery with a smile in her voice. Talks to the camera like a friend showing off things she bought at 2am."' \ --form 'imageReference_1="user:1234-email:…-image:a236ef66-…"' \ --form 'imageReference_2="user:1234-email:…-image:d891301c-…"' \ --form 'voice="Leda"' ``` </details> `imageReference_1` is the front portrait `a236ef66`, `imageReference_2` the three-quarter `d891301c`. The response's `character` field is her id, `53ca1036` below. The `voice` is one of Google's system presets and rides along with the character, but it cannot reach the clip mode used in Step 4, see [What to expect](#what-to-expect). ### Step 3: the still, the whole scene in one frame One request puts everything together. The character goes in as `character_1`, the three sheets as `reference_1` to `reference_3`, and the prompt places them by tag, left to right on the table in front of her. This frame becomes both ends of every clip, so it is the one place where the tags do their work. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="9:16"' \ --form 'count="2"' \ --form 'character_1="user:1234-email:…-character:53ca1036-…"' \ --form 'reference_1="user:1234-email:…-image:b0bdf3e8-…"' \ --form 'reference_2="user:1234-email:…-image:7aaed056-…"' \ --form 'reference_3="user:1234-email:…-image:4f861c23-…"' \ --form 'prompt="Full-frame vertical phone video look, no phone, no bezel. @character_1 sits at a light wooden table in a bright minimal creator studio, facing the camera, waist-up and centered, a plain warm-grey backdrop behind her, soft key light from the left with a gentle catchlight in her eyes. Laid out on the table in front of her, left to right, each fully visible and resting flat on the table: the mug from @reference_1, the desk robot from @reference_2, the keyboard from @reference_3. Her hands rest on the table, relaxed closed-mouth smile, eyes on the lens. Photoreal, no text, no captions."' ``` </details> `character_1` is the character from Step 2, `53ca1036`. `reference_1` to `reference_3` are the three sheets from Step 1: the mug `b0bdf3e8`, the desk robot `7aaed056`, the keyboard `4f861c23`. <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/06-ugc-products-still-presenter-and-three-products-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/06-ugc-products-still-presenter-and-three-products-nano-banana-2-lite.png" alt="The presenter at the table with the mug, the desk robot and the keyboard laid out in front of her" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">The still — her face from the character, each product from its sheet, id <code>034cddc8</code> (0 credits)</figcaption> </figure> </div> The mug has its glow, the robot its face and antenna, the keyboard its three colours and its port, and she is the woman from the portraits. ### Step 4: one clip per product, all from the still Omni's first-plus-last-frame mode with the still in both slots, one request per product, the same [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) each time. This mode takes nothing but the two images, no sheets, no character, no voice reference. That is fine, because the still already holds all of it. Every item she picks up came out matching its sheet from the still alone. The prompt does three jobs. It pins both ends to the frame, with a quiet beat on each side. It gives her the line and the voice. And it times the choreography: she starts talking as she lifts the item, the item is back on its spot by the eight-second mark, and the last two seconds are a still, silent hold. Without that last part she ran late and her arm snapped into the end frame. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos">POST /videos</a> (the mug)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'model="omni-flash"' \ --form 'aspectRatio="portrait"' \ --form 'duration="10"' \ --form 'resolution="720p"' \ --form 'startImage="user:1234-email:…-image:034cddc8-…"' \ --form 'endImage="user:1234-email:…-image:034cddc8-…"' \ --form 'prompt="She begins and ends exactly on this frame: hands resting on the table, the three items laid out in front of her, a small closed-mouth smile, looking into the lens, with a short quiet beat before she moves and another after she settles back. Timing matters: after a short quiet beat she picks up the mug on the left with both hands and starts talking as she lifts it, holding it up to the camera and talking straight to the lens, quick and bright with a deadpan edge and a smile in her voice, keeping both hands on the mug while she speaks. She says: \"Three gadgets smarter than me. Low bar. One: this mug texts me when my coffee'\''s cold. Better follow-up than my ex.\" Right after the last word she gives one short laugh to herself, still holding the mug. By the eight-second mark the mug is back down gently in exactly the same spot and both hands are resting on the table again, brought back in one calm unhurried movement. For the final two seconds she holds completely still, hands resting on the table, looking into the lens with a small closed-mouth smile. Natural room tone, no music, no captions, no text on screen."' ``` </details> `startImage` and `endImage` are both the still from Step 3, `034cddc8`. The same two ids go into all three clips. <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 220px;max-width:260px;margin:0"> <video poster="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/07b-ugc-products-clip-1-smart-mug-10s-omni-1.1-flash-1080p-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/07b-ugc-products-clip-1-smart-mug-10s-omni-1.1-flash-1080p.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">Clip 1, the mug — 10 seconds, id <code>55808825</code>, shown after the 1080p upscale of Step 5 (15 credits)</figcaption> </figure> </div> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos">POST /videos</a> (the desk robot)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'model="omni-flash"' \ --form 'aspectRatio="portrait"' \ --form 'duration="10"' \ --form 'resolution="720p"' \ --form 'startImage="user:1234-email:…-image:034cddc8-…"' \ --form 'endImage="user:1234-email:…-image:034cddc8-…"' \ --form 'prompt="She begins and ends exactly on this frame: hands resting on the table, the three items laid out in front of her, a small closed-mouth smile, looking into the lens, with a short quiet beat before she moves and another after she settles back. Timing matters: after a short quiet beat she picks up the desk robot in the middle with both hands and starts talking as she lifts it, holding it up to the camera with its smiling face toward the lens and turning it once and talking straight to the lens, quick and bright with a deadpan edge and a smile in her voice, keeping both hands on it while she speaks. The other two items stay on the table exactly where they are. She says: \"Two: a desk robot that reacts to my day. It has a face. It has never once looked impressed.\" Right after the last word she raises one eyebrow at the camera, a quick expressive beat, still holding the desk robot. By the eight-second mark the desk robot is back down gently in exactly the same spot and both hands are resting on the table again, brought back in one calm unhurried movement. For the final two seconds she is silent and holds completely still, hands resting on the table, looking into the lens with a small closed-mouth smile. Natural room tone, no music, no captions, no text on screen."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 220px;max-width:260px;margin:0"> <video poster="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/08b-ugc-products-clip-2-desk-robot-10s-omni-1.1-flash-1080p-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/08b-ugc-products-clip-2-desk-robot-10s-omni-1.1-flash-1080p.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">Clip 2, the desk robot — 10 seconds, id <code>c4d0e6b1</code>, shown after the 1080p upscale of Step 5 (15 credits)</figcaption> </figure> </div> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos">POST /videos</a> (the keyboard)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'model="omni-flash"' \ --form 'aspectRatio="portrait"' \ --form 'duration="10"' \ --form 'resolution="720p"' \ --form 'startImage="user:1234-email:…-image:034cddc8-…"' \ --form 'endImage="user:1234-email:…-image:034cddc8-…"' \ --form 'prompt="She begins and ends exactly on this frame: hands resting on the table, the three items laid out in front of her, a small closed-mouth smile, looking into the lens, with a short quiet beat before she moves and another after she settles back. Timing matters: after a short quiet beat she picks up the keyboard on the right with both hands and starts talking as she lifts it, holding it up to the camera with the three keys facing the lens and talking straight to the lens, quick and bright with a deadpan edge and a smile in her voice, keeping both hands on it while she speaks. The other two items stay on the table exactly where they are. She says: \"Three: a keyboard with three keys. Copy, paste, undo. That'\''s my whole career. Oh, the mug'\''s texting. Bye!\" Right after the last word she raises one eyebrow at the camera, a quick expressive beat, still holding the keyboard. By the eight-second mark the keyboard is back down gently in exactly the same spot and both hands are resting on the table again, brought back in one calm unhurried movement. For the final two seconds she is silent and holds completely still, hands resting on the table, looking into the lens with a small closed-mouth smile. Natural room tone, no music, no captions, no text on screen."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 220px;max-width:260px;margin:0"> <video poster="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/09b-ugc-products-clip-3-three-key-keyboard-10s-omni-1.1-flash-1080p-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/09b-ugc-products-clip-3-three-key-keyboard-10s-omni-1.1-flash-1080p.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">Clip 3, the keyboard — 10 seconds, id <code>3cc8ea2f</code>, shown after the 1080p upscale of Step 5 (15 credits)</figcaption> </figure> </div> Same woman, same table, same light, and each clip opens and closes on the still, so any of them can follow any other. The lines are around 20 words, which is what 10 seconds holds at this pace with room for the beat at the end. ### Step 5: upscale to 1080p Omni 1.1 Flash renders at 720p. [POST /videos/upscale](/docs/api-google-flow-v1/post-google-flow-videos-upscale) takes a clip to 1080p for free on any paid plan, in about 40 seconds, and answers in the same call with the upscaled clip's id and URL. One request per clip, no `email`, the account comes from the id. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos-upscale">POST /videos/upscale</a> (the mug, then the same for the other two)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos/upscale' \ --header 'Authorization: Bearer user:1234-…' \ --form 'mediaGenerationId="user:1234-email:…-video:55808825-…"' \ --form 'resolution="1080p"' ``` </details> `mediaGenerationId` is the mug clip from Step 4, `55808825`. The same call with `c4d0e6b1` and `3cc8ea2f` upscales the robot and the keyboard. Each response carries the new clip under `media[0].mediaGenerationId`, which is the source id with `_upsampled` on the end, so the three upscaled ids are `55808825-…_upsampled`, `c4d0e6b1-…_upsampled` and `3cc8ea2f-…_upsampled`. The clips shown in Step 4 are these upscaled versions. 4K is also available, for 50 credits and only on a Google AI Ultra plan. ### Step 6: join them [POST /videos/concatenate](/docs/api-google-flow-v1/post-google-flow-videos-concatenate) takes the three upscaled ids in order and returns the joined file as base64, at the clips' resolution. The trims decide whether the joins feel like one take. Each clip opens with a short hold on the still and closes with a settle back onto it, and untrimmed those stack into a freeze at every cut. But she finishes each line with her hands already resting, so a trim measured from the picture alone cuts into the last words. Cut after the last sound plus a beat, never earlier. On these clips that meant leaving clip 1 whole, since its laugh runs to the last frame, taking just over half a second off the end of clip 2, and a few frames off the start of clips 2 and 3. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos-concatenate">POST /videos/concatenate</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos/concatenate' \ --header 'Authorization: Bearer user:1234-…' \ --header 'Content-Type: application/json' \ --data '{ "media": [ { "mediaGenerationId": "user:1234-email:…-video:55808825-…_upsampled" }, { "mediaGenerationId": "user:1234-email:…-video:c4d0e6b1-…_upsampled", "trimStart": 0.458, "trimEnd": 0.6 }, { "mediaGenerationId": "user:1234-email:…-video:3cc8ea2f-…_upsampled", "trimStart": 0.125 } ] }' ``` </details> The three ids are the upscaled clips from Step 5 in order: the mug, the desk robot, the keyboard. <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 260px;max-width:320px;margin:0"> <video poster="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/10b-ugc-products-joined-29s-1080p-upscaled-concatenated-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/articles/2026-09-04-google-flow-ugc-product-video/10b-ugc-products-joined-29s-1080p-upscaled-concatenated.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">Joined — 28.8 seconds, 1080p (0 credits)</figcaption> </figure> </div> She finishes a line with her hands on the table, the cut lands, and she reaches for the next item. The joined file was re-encoded to a smaller size for hosting, the three clips are as the API returned them. ### What to expect * Generate, do not edit. The [UGC talking head](/blog/260902) post extended a clip with video-to-video edits, and that still works when the lines are short. Here it did not. An edit keeps its source's speech on the source's own timeline, so with a 10-second line filling the seed, a new line got braided into the old one instead of replacing it, and the products left on the table drifted between takes. Generating each clip from the still gave complete lines, intact products and cleaner joins, for fewer credits. * The still carries the tags. The first-plus-last-frame mode accepts only the two images. Do the tagging in the still, with the character and the sheets, and the clips inherit it. * Time the choreography. A 10-second clip with a full line needs the put-down called out by the clock, "by the eight-second mark", and a still, silent hold at the end. Left to itself the model ran the line long and jumped into the end frame. * Describe the voice the same way in every prompt. Nothing carries a voice between separate clips, and a character can hold a voice preset but cannot reach this mode. With one identical description the three clips came back close enough to pass as one take. * Sheets need per-panel cameras. Name what each of the four panels shows. Give flat objects a top-down panel. Keep hands, captions and logos out, because whatever is on the sheet can end up in the clip. * Trim to the sound, not the picture. She goes still before she stops talking. A cut placed at the first still frame took the end of a line with it. * The presenter is invented. Google's moderation is stricter with real, identifiable people. Start from a generated character. ### What it cost | Step | Mode | Credits | |---|---|---| | Three product sheets, 1:1 | Nano Banana 2 Lite | 0 | | Two presenter portraits, 3:4 | Nano Banana 2 Lite | 0 | | The character | — | 0 | | The still, 9:16 | Nano Banana 2 Lite, character + 3 references | 0 | | Clip 1, the mug, 10s | I2V, first + last frame | 15 | | Clip 2, the desk robot, 10s | I2V, first + last frame | 15 | | Clip 3, the keyboard, 10s | I2V, first + last frame | 15 | | Upscale, three clips to 1080p | — | 0 | | Concatenate | — | 0 | | Total | | 45 | Images, characters, the 1080p upscale and the concatenate cost nothing, so iterate freely on the sheets, the presenter and the still before spending a credit on video. 4K is the one upgrade that costs, 50 credits a clip on Ultra. ### Run it yourself Every step above is one API call, and the six of them chain into a script. The complete Node.js pipeline, a Python port, and the `prompts.json` holding every prompt on this page live in [`useapi/google-flow-api/ugc-product-video`](https://github.com/useapi/google-flow-api/tree/main/ugc-product-video). Clone it, put your own products and lines in `prompts.json`, and one command builds the whole video. It checkpoints after every step, so an interrupted run resumes instead of paying for the clips again, and you can redo a single step — a better still, a different presenter — without regenerating what came before it. ### Frequently asked questions - **Can I use my own product photos instead of generated sheets?** Through useapi.net, yes. Upload them with [POST /assets](/docs/api-google-flow-v1/post-google-flow-assets-email) and pass the returned ids as `reference_1` to `reference_3` on the still, exactly as the generated sheets are passed here. The four-panel sheet is a way to give the model every side of an object, and a real product benefits from the same treatment. - **Why not edit one clip into the next, like the [talking-head post](/blog/260902)?** Through useapi.net you can, but a video-to-video edit keeps its source's speech on the source's timeline. With short lines that works. With a 10-second line filling the clip, the new line got braided into the old one and the products on the table drifted. Generating every clip from the same still avoids both, and costs 15 credits instead of 20. See [What to expect](#what-to-expect). - **Why do all three clips start and end on the same frame?** Through useapi.net, the first-plus-last-frame mode pins both ends of each clip to the same still, so the clips join in any order with no visible cut, and the concatenate call trims the short holds around each join. The mechanism is explained in the [UGC talking head](/blog/260902) post. - **Does the voice stay the same across the clips?** Through useapi.net the three clips came close enough to pass as one take, because the voice was described identically in every prompt. The first-plus-last-frame mode takes no audio reference, and a character's voice preset cannot reach it. If you need a guaranteed voice, the reference-to-video mode accepts `referenceAudio_1`, at the cost of the pinned frames. - **How much does it cost?** Through useapi.net, this whole 29-second video costs $0.36 on Google AI Ultra $199.99: 45 Flow credits for the three Omni 1.1 Flash clips, with every image, portrait, character and the concatenate free. The same 30 seconds of 720p Omni 1.1 Flash cost about $3.04 on the official [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) (as of November 2026). See [What it cost](#what-it-cost). ### Conclusion Visit our <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> or <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> for any support questions and concerns. Check our [GitHub repo](https://github.com/useapi/google-flow-api) with code examples. #### Cross posted Also published on [dev.to](https://dev.to/useapi/how-to-make-a-ugc-product-video-with-the-google-flow-api-4nef){:rel="nofollow"}. === URL: https://useapi.net/docs/articles/google-vids-api-zh === Document URL: https://useapi.net/docs/articles/google-vids-api-zh --- layout: default title: 如何通过 Google Vids API 用 Gemini Omni 1.2 Flash 生成会说话的数字人视频(中文教程) seo_title: "Google Vids API 中文教程:用 Gemini Omni 生成数字人视频(无需验证码)" description: "Google Vids API 中文教程:通过 useapi.net 调用 Gemini Omni 1.2 Flash 生成最长 15 秒、会说话的 AI 数字人视频,用一张照片做出念稿 30 秒的口播数字人,并把文字转成语音,无需验证码,使用你的 Google Vids 网站订阅。" keywords: [Google Vids API, Google Vids API 教程, Gemini Omni 1.2 Flash API, Omni Flash API, 数字人视频 API, AI 数字人 API, AI 网红视频, 虚拟形象 API, talking avatar API, AI avatar video API, 照片生成数字人 API, 口播视频 API, 数字人口播 API, talking head video API, 文字转语音 API, text to speech API, Gemini 音色, 视频延长 API, Gemini API 替代, 无验证码, 中文教程, Chinese tutorial, curl, Gemini Omni API, Google Vids 教程, Google Vids 数字人, 视频生成 API, AI 视频生成 API, AI 数字人视频生成, Omni 1.2 Flash API 价格, 数字人 API] image: https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-cover-aeroloop-launch-confetti-1007.jpg parent: Articles nav_exclude: true lang: zh-CN date: 2026-10-08 last_modified: 2026-11-09 nav_order: 900 repo: https://github.com/useapi/google-vids-api translation_key: google-vids --- ## 如何通过 Google Vids API 用 Gemini Omni 1.2 Flash 生成会说话的数字人视频(中文教程) <div class="lang-banner" lang="en"> <strong>Chinese-language tutorial.</strong> This page is written in Simplified Chinese for Chinese-speaking developers. The same material in English: <a href="/docs/articles/google-vids-influencer-avatars">How to Make AI Influencer Videos with Avatars via the Google Vids API</a> · <a href="/docs/api-google-vids-v1">Google Vids API docs</a> </div> 12 分钟阅读 • 2026 年 10 月 8 日(2026 年 11 月 9 日更新) ## 目录 ### 简介 [useapi.net](/docs/api-google-vids-v1) 的 Google Vids API 用你的 Google Vids 网站订阅([Google AI Pro 或 Ultra](https://gemini.google/subscriptions/)),通过 REST 接口调用 Google Vids 里的 [Gemini Omni 1.2 Flash](https://workspaceupdates.googleblog.com/2026/11/gemini-omni-12-flash-now-in-vids-with-15second-generations-and-improved-quality.html):生成最长 15 秒、带声音和对白的视频,延长到约 34 秒,还能创建带固定配音的数字人(avatar),让它在视频里说出你写的台词,或者逐字念出你的稿子,生成最长 30 秒的口播视频。同一套音色也能单独把文字转成语音。 [Google Vids](https://docs.google.com/videos) 是 Google Workspace 里的视频应用,Google 在 2026 年 9 月为它加入了 Gemini Omni([Google 官方公告](https://blog.google/products-and-platforms/products/workspace/gemini-omni-in-google-vids/)),2026 年 11 月 5 日升级为 Gemini Omni 1.2 Flash,单条视频最长 15 秒([Google Workspace 更新公告](https://workspaceupdates.googleblog.com/2026/11/gemini-omni-12-flash-now-in-vids-with-15second-generations-and-improved-quality.html)),Vids 网页里只显示为“Omni”。截至 2026 年 10 月,Google 没有公开 Vids 的视频生成 API,本 API 是第三方实现,生成在你的 Google 账号上进行,消耗的是订阅每月包含的 Vids 视频秒数,不按次付费。 Omni 1.2 Flash 在 Flow 和 Vids 中的对比、15 秒视频和每条视频价格:见[Gemini Omni 1.2 Flash API 中文教程](/docs/articles/gemini-omni-1-2-flash-api-zh)。 本文由 useapi.net 维护者撰写,介绍的是我们自己的托管 API,示例代码开源在 [GitHub](https://github.com/useapi/google-vids-api)。 ### 为什么选 Google Vids API - 没有验证码。Google Flow 每次生成都要过 reCAPTCHA,需要接打码服务。Google Vids 没有这一步,不用打码,也没有打码费用。 - 独立的额度。Vids 有自己的月度额度,不消耗 Google Flow 的积分。同一个 Google 账号同时绑定 Vids API 和 [Google Flow API](/docs/api-google-flow-v1),两份额度都能用上。 - 可以延长 Omni 视频。[POST /videos/extend](/docs/api-google-vids-v1/post-google-vids-videos-extend) 每次加 3 到 10 秒,只延长 24 秒以内的视频,所以最长约 34 秒。 - 带配音的数字人。从 30 种 Gemini 音色里选一种,配上一张人物图片保存为数字人,之后在任何视频里用 `avatarId` 引用,人物用自己的声音说台词。数字人可以从你自己的照片开始,用一句话换装换景,再用 [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar) 念出最长 30 秒的稿子。 - 时长 3 到 15 秒(按 1 秒递增),`720p` 或 `1080p`,横屏或竖屏,两种分辨率消耗相同。 | | Google Vids API | [Google Flow API](/docs/api-google-flow-v1) | |---|:-:|:-:| | 额度 | 每月若干秒视频,与 Flow 分开 | 每月 Flow 积分 | | 一条 10 秒 Omni 视频 | 10 秒额度,`720p` 或 `1080p` | Omni 1.1 15 积分,Omni 1.2 30 积分(`720p`,可免费放大到 `1080p`) | | Ultra(199.99 美元)每月可生成的 10 秒 Omni 视频 | 约 1,000 条(10,000 秒,家庭方案共享) | 约 1,666 条 Omni 1.1(25,000 积分) | | Omni 时长 | 3 到 15 秒,按 1 秒递增 | Omni 1.2:3 到 15 秒。Omni 1.1:4、6、8 或 10 秒 | | 延长 Omni 视频 | Yes 每次 3 到 10 秒,源视频最长 24 秒,最终最长约 34 秒 | Yes 用 Omni 1.2,每次 3 到 10 秒,需付费套餐 | | 验证码 | 无 | 每次生成都要 reCAPTCHA | | 其他模型 | — | Veo 3.1、最高 4K 的 Nano Banana 图片 | ### Google Vids API 价格与额度 一条 Gemini Omni 1.2 Flash 视频在官方 [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) 上按秒计费,在 Google Vids 上则消耗订阅每月包含的视频秒数(2026 年 11 月)。每个订阅每月有固定的秒数,一条视频用掉等于其时长的秒数,所以一条视频的成本就是它在订阅费里所占的份额。会说话的数字人口播视频和语音不消耗视频秒数,各有自己的月度计数(见下方额度说明)。 | 模型 | 官方 API | Ultra $199.99/月 (每月 10,000 秒) | Pro $19.99/月 (每月 500 秒) | |---|---|---|---| | Omni 1.2 Flash (720p,15 秒) | $1.04 ($0.07/秒) | $0.30 / 15 秒 (每月 666 条) | $0.60 / 15 秒 (每月 33 条) | | Omni 1.2 Flash (1080p,15 秒) | $1.56 ($0.104/秒) | $0.30 / 15 秒 (每月 666 条) | $0.60 / 15 秒 (每月 33 条) | | Omni 1.2 Flash (720p,10 秒) | $0.70 ($0.07/秒) | $0.20 / 10 秒 (每月 1,000 条) | $0.40 / 10 秒 (每月 50 条) | | 数字人口播视频 (最长 30 秒) | 无 API | $0 / 0 秒 (1 次 AI 数字人视频) | $0 / 0 秒 (1 次 AI 数字人视频) | | 语音 | 无 API | $0 / 0 秒 (1 次 Gemini 使用) | $0 / 0 秒 (1 次 Gemini 使用) | - 同一个 Ultra 账号的 Google Flow 积分还能另外生成 Omni 视频,见 [Google Flow 价格表](/docs/api-google-flow-v1#pricing)。 - 套餐价格是 Google [订阅页面](https://gemini.google/subscriptions/)上的美国价格。 #### 各套餐的 Vids 额度 Google 按月计量 Vids:视频按秒,图片按张。以下为 Google 在 [Gemini in Google Vids](https://support.google.com/docs/answer/15609411) 帮助页公布的数字: | | Google AI Plus | Google AI Pro | Google AI Ultra 5x | Google AI Ultra 20x | |---|---|---|---|---| | AI 视频 | 每月 60 秒 | 每月 500 秒 | 每月 2,500 秒 | 每月 10,000 秒 | | 图片生成与编辑 | 每次图片操作 1 点 | 每月 30 张 | 每月 300 张 | 每月 1,000 张 | 我们在真实账号上测得(2026 年 10 月): - Google AI Ultra(199.99 美元)就是 Google 所说的 Ultra 20x:每月 10,000 秒视频、1,000 张图片。 - 视频秒数由 Google One 家庭方案的所有成员共享,图片按账号计算。多绑定同一家庭方案的账号,能增加图片额度和并行任务数,但不增加视频秒数。 - 免费 Google 账号在 Vids 里是 0 秒视频、0 张图片,Omni 视频和图片任务会跳过它。它仍然可以绑定,我们测试时(2026 年 11 月)它能创建数字人、生成口播视频和语音,每月有 10 次 AI 数字人视频和 50 次 Gemini 使用。 - 一条视频消耗等于其时长的秒数,`720p` 和 `1080p` 消耗相同。延长只计新增的秒数,放大(upscale)会再计一次整条视频的秒数。 - Google 为数字人画的每张图片,只在含图片额度的套餐上消耗 1 张图片额度,照片重新构图再加一次 `refine` 就是 2 张。在没有图片额度的套餐上(例如免费 Google 账号)数字人图片不消耗任何额度,下文的 Amber 就是在免费账号上做的。 - 口播视频和语音不消耗视频秒数,用的是各自的月度计数:AI 数字人视频和 Gemini 使用次数,在 [GET /accounts/`email`](/docs/api-google-vids-v1/get-google-vids-accounts-email) 里与 `video`、`image` 并列,显示为 `avatarVideo` 和 `speech`。一条[口播视频](#a-talking-avatar-from-a-photo)消耗 1 次 AI 数字人视频,外加其语音的 1 次 Gemini 使用。[单独生成语音](#speech-on-its-own)每次消耗 1 次 Gemini 使用。 - 被 Google 拒绝的请求(内容或额度原因)不消耗额度。唯一的例外是口播视频:Google 在生成过程中拒绝的成片照样计 1 次 AI 数字人视频。 - 额度在每月 1 日太平洋时间 00:00 重置。用完时任务以 `429` 失败,`retryAt` 为重置时间。 每个完成的任务都会在 `result.quota` 里返回账号剩余额度,[GET /accounts/`email`](/docs/api-google-vids-v1/get-google-vids-accounts-email) 可以实时读取全部计数。 每个 useapi.net 订阅可以绑定 3 个 Google 账号,总数最多 100 个。生成在你的 Google 账号上进行,useapi.net 不按条收费。 ### 如何绑定 Google 账号 1. 注册 useapi.net 并获取 [API Token](/docs/start-here/setup-useapi)。 2. 用[自动化浏览器流程](/docs/start-here/setup-google-vids)绑定一个 Google AI 付费套餐(Pro 或 Ultra)的 Google 账号:输入 Token,在远程浏览器里登录 Google 即可,不需要手动复制 Cookie。远程浏览器用完即关闭删除。建议使用[专用的 Gmail 账号](/docs/start-here/setup-google-vids#use-a-dedicated-gmail-account)。 绑定之后,不要再在任何浏览器里打开这个 Google 账号,包括 Google Vids、Gmail 和其他 Google 页面。Vids 依赖一个浏览器大约每 10 分钟续期一次的会话 Cookie,只要任何浏览器登录了同一个账号,就会抢先续期这个 Cookie,API 手里的那份几分钟内就会失效。Vids 在这一点上比 Google Flow 和 Gemini Notebook 都严格。如果 Google 让账号下线,API 会发邮件通知你,用自动化流程重新绑定大约一分钟。 所有请求也都在 [Postman 集合](https://www.postman.com/useapinet/useapi-net/collection/29112081-9ef3d017-d44c-4f43-a4cb-7351b9b265df)里。 ### 调用方式:同步、异步与 Webhook 每次生成都在我们这边作为一个任务运行。默认是同步调用:POST 会等待任务完成并返回任务记录,视频通常需要 20 到 100 秒,图片约 10 秒。超过约 100 秒仍未完成时返回 `202`,之后用 [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid) 查询结果。传 `async: true` 则立即返回 `202`,再轮询或等待 Webhook。在请求里加 `replyUrl`,任务完成或失败时会收到一次 `POST`,内容是最终的任务记录。 生成的文件存在 Google 的临时存储里,不会存进 Vids 文档或 Google Drive,所以要尽快用 [GET /media/`mediaId`](/docs/api-google-vids-v1/get-google-vids-media-mediaId) 下载:图片只保留几个小时,视频至少半天。 下面的步骤用到 `curl`、`jq` 和这些变量与辅助函数。`run` 以异步方式提交视频任务,每 10 秒轮询一次,把最终的任务记录存到文件: <details markdown="block"> <summary>展开变量与辅助函数</summary> ```bash export USEAPI_TOKEN="user:12345-..." export EMAIL="user@example.com" API=https://api.useapi.net/v1/google-vids AUTH="Authorization: Bearer $USEAPI_TOKEN" enc() { jq -rn --arg v "$1" '$v|@uri'; } post() { curl -sS -X POST "$API/$1" -H "$AUTH" -H "Content-Type: application/json" -d "$2"; } get() { curl -sS "$API/$1" -H "$AUTH"; } download() { curl -sSf "$API/media/$(enc "$1")" -H "$AUTH" -o "$2"; } # run a video job async: submit it, poll GET /jobs/{jobid} every 10 s, save the final job record to $1 run() { local job id job=$(post "$2" "$(jq '. + {async: true}' <<< "$3")") id=$(jq -r .jobid <<< "$job") while [ "$(jq -r .status <<< "$job")" = processing ]; do sleep 10 job=$(get "jobs/$(enc "$id")") done echo "$job" > "$1" jq '{status, error, duration: .result.duration, resolution: .result.resolution, videoLeft: .result.quota.video.left}' "$1" } ``` </details> 各种 id 里含有 `:` 和 `@`,放进 URL 路径时要用 `enc` 编码。同一条视频的所有输入必须来自同一个 Google 账号,视频任务会在持有这些输入的账号上运行。如果 `run` 输出的 `status` 不是 `completed`,先看 `error`,后面的步骤都需要一条完成的视频。 ### 实战:两个数字人发布一款球鞋 这个例子做两个虚拟网红,让他们发布一款虚构的球鞋 AeroLoop:Mia 的数字人来自用 API 生成的人像,Leo 的数字人由 Google 根据文字描述绘制。两人和产品图出现在同一条 10 秒视频里,再延长两次到 30 秒。以下每个请求都是生成本页素材时实际用的请求,只替换了 id。本页的视频是 2026 年 10 月用 Omni 1.1 Flash 生成的,同样的请求现在由 Omni 1.2 Flash 生成。提示词保持英文原样,因为它们是直接发给模型的。 完整流程也做成了一个脚本(Node.js 和 Python):GitHub 上 [useapi/google-vids-api](https://github.com/useapi/google-vids-api) 仓库的 [`influencer-avatars/`](https://github.com/useapi/google-vids-api/tree/main/influencer-avatars)。 #### 1. 生成 Mia 的人像 [POST /images](/docs/api-google-vids-v1/post-google-vids-images) 每次生成一张 JPEG,这里用竖幅(`9:16`,768×1376)和 `photography` 风格。耗时 9 秒,消耗 1 张图片额度。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-images">POST /images</a></summary> ```bash post images "$(jq -n --arg email "$EMAIL" '{email: $email, aspectRatio: "9:16", style: "photography", prompt: "Full-length studio portrait of a confident 24-year-old female fashion influencer, platinum bob, oversized cream hoodie, wide-leg cargo pants, gold hoops, plain light-grey backdrop, facing camera"}')" > mia-portrait.json MIA_IMAGE=$(jq -r .result.mediaId mia-portrait.json) download "$MIA_IMAGE" mia-portrait.jpg ``` </details> <img src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-mia-portrait-1007.jpg" alt="Mia:用 POST /images 生成的时尚博主全身人像,奶油色卫衣、工装裤" style="width: 100%; max-width: 300px; border-radius: 8px;"> 生成的图片只保留几个小时,要尽快用它创建数字人。 #### 2. 生成 AeroLoop 产品图 同一个接口换成横幅(`16:9`,1376×768),得到视频里用作产品参考的图片。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-images">POST /images</a></summary> ```bash post images "$(jq -n --arg email "$EMAIL" '{email: $email, aspectRatio: "16:9", style: "photography", prompt: "The AeroLoop sneaker: chunky white-and-electric-blue running shoe with a translucent air sole, on a concrete pedestal, dramatic side light, dark background"}')" > aeroloop.json SHOE_IMAGE=$(jq -r .result.mediaId aeroloop.json) download "$SHOE_IMAGE" aeroloop.jpg ``` </details> <img src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-aeroloop-product-1007.jpg" alt="AeroLoop 球鞋:白色与电光蓝配色、透明气垫鞋底,放在水泥台座上,用 POST /images 生成" style="width: 100%; max-width: 560px; border-radius: 8px;"> #### 3. 选择音色 [GET /voices](/docs/api-google-vids-v1/get-google-vids-voices) 列出 30 种音色,附 Google 预生成的 18 种语言试听样本。这个接口公开,不需要 Token。Mia 用 `Aoede`(Vids 里叫 Tova,风格 "Breezy"),Leo 用 `Puck`(Neo,"Upbeat")。`POST /avatars` 两种名字都接受,音色不额外收费。 ```bash curl -sS "$API/voices" | jq -r '.voices[] | "\(.name)\t\(.voice)\t\(.style)\t\(.preview)"' ``` #### 4. 用人像创建 Mia 的数字人 [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) 的 `image` 传人像的 `mediaId`,约 2 秒即可在同一账号上保存数字人,除生成人像用掉的 1 张图片额度外,不再消耗额度。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-avatars">POST /avatars</a></summary> ```bash post avatars "$(jq -n --arg img "$MIA_IMAGE" '{name: "Mia", voice: "Aoede", image: $img}')" > mia-avatar.json MIA_AVATAR_ID=$(jq -r .avatarId mia-avatar.json) ``` </details> 数字人也可以用真人照片创建:先用 [POST /assets](/docs/api-google-vids-v1/post-google-vids-assets) 上传照片,再把它的 `assetId` 作为 `image` 传入。Google 会把照片重新构图为 16:9 的数字人图片,并拒绝知名人物和未成年人的照片。这里我们用 API 生成的图片,下一步用文字描述,后文的 Amber 则[从一张照片开始](#a-talking-avatar-from-a-photo)。 #### 5. 用文字描述创建 Leo 的数字人 用 `appearance` 代替 `image`,由 Google 绘制人物,`outfit`、`shot`、`expression`、`details` 都是可选的。绘制图片在含图片额度的套餐上消耗 1 张图片额度,约 20 秒,图片在响应的 `previewMediaId` 里。我们测试时,描述生成的数字人都是 1280×720(16:9),与 `shot` 取值无关。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-avatars">POST /avatars</a></summary> ```bash post avatars "$(jq -n --arg email "$EMAIL" '{email: $email, name: "Leo", voice: "Puck", shot: "upper-body", appearance: "a 26-year-old white European male streetwear influencer with short textured hair with a fade and a confident half-smile", outfit: "black puffer vest over a white tee, silver chain"}')" > leo-avatar.json LEO_AVATAR_ID=$(jq -r .avatarId leo-avatar.json) download "$(jq -r .previewMediaId leo-avatar.json)" leo-avatar.jpg ``` </details> <img src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-leo-avatar-from-description-1007.jpg" alt="Leo:Google 根据文字描述绘制的数字人,黑色羽绒背心、白 T 恤、银项链,1280x720" style="width: 100%; max-width: 560px; border-radius: 8px;"> 数字人保存在账号的 Vids 文档里,直到你用 [DELETE /avatars/`avatarId`](/docs/api-google-vids-v1/delete-google-vids-avatars-avatarId) 删除。[GET /avatars](/docs/api-google-vids-v1/get-google-vids-avatars) 随时可以列出它们和各自的 id,包括在 Vids 网页版里做的数字人。 #### 6. 两个数字人和产品同框 [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) 最多接受 3 个参考,数字人(`avatar_1`..`avatar_3`)和图片(`referenceImage_1`..`referenceImage_3`)合计。提示词里用 `@avatar_1`、`@avatar_2`、`@referenceImage_1` 指代它们,每个数字人用自己的声音说出引号里的台词。产品图的 `mediaId` 可以直接传,API 会取回图片并上传到该账号。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos">POST /videos</a></summary> ```bash PROMPT=$(cat <<'EOF' @avatar_1, holding @referenceImage_1 in both hands at chest height, and @avatar_2 stand side by side on a well-lit stage in a small, intimate theater at a sneaker launch, shown full length from head to toe in a wide, steady shot. Behind them a large LED backdrop glows with soft white-and-blue light that moves in slow, gentle waves, with the words "WEAR AEROLOOP" in large, clean, bold white letters across the middle of the screen. The two of them stand on the lower part of the stage, so the words "WEAR AEROLOOP" stay fully readable above their heads. Bright, even stage lighting on both of them. The audience sits in the dark in front of the stage, only the tops of a few heads barely visible at the bottom of the frame. @avatar_1 keeps holding @referenceImage_1 the whole time and says: "Say hi to the AeroLoop!" @avatar_2 turns to her, smiles and says: "Lighter than anything we've ever worn." Simple, uncluttered composition, the two of them clearly the focus. EOF ) run launch-10s.json videos "$(jq -n --arg p "$PROMPT" --arg mia "$MIA_AVATAR_ID" --arg leo "$LEO_AVATAR_ID" --arg shoe "$SHOE_IMAGE" \ '{prompt: $p, avatar_1: $mia, avatar_2: $leo, referenceImage_1: $shoe, duration: 10, resolution: "720p", aspectRatio: "landscape"}')" LAUNCH_10S=$(jq -r .result.mediaId launch-10s.json) download "$LAUNCH_10S" launch-10s.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-10s-720p-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-10s-720p-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> 10 秒,`720p`,生成耗时 38 秒,消耗 10 秒额度。 同一条视频用我们的 [watermark remover](https://github.com/useapi/google-vids-api/tree/main/watermark-remover) 去掉可见的 Gemini ✦ 标记后的效果,只需一条命令:`python3 vids_watermark_remover.py launch-10s.mp4`。 <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-10s-720p-no-watermark-1008-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-10s-720p-no-watermark-1008.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> 去水印工具适用于直接生成的视频及其放大版本,`720p` 和 `1080p` 都可以。它不适用于延长或编辑过的视频:Google 会把带标记的视频交给模型重新生成,星标被画进了画面里。不可见的 SynthID 水印不受影响。 #### 7. 延长到 20 秒 [POST /videos/extend](/docs/api-google-vids-v1/post-google-vids-videos-extend) 每次增加 3 到 10 秒,返回带新 `mediaId` 的完整视频。延长只接收视频和提示词,不接收数字人,所以提示词只描述新的动作,并用衣着指代人物("the man in the black puffer vest")。这一段里,一个穿红色卫衣的粉丝冲上了舞台。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos-extend">POST /videos/extend</a></summary> ```bash PROMPT=$(cat <<'EOF' A young man in a red hoodie climbs onto the stage from the front right edge and plants himself to the right of the man in the black puffer vest, an arm's length away, so all three stand apart in a row with nobody overlapping. Visibly overexcited, he waves a thick stack of banknotes in his right hand above his head and screams: "Take my money!" The man in the black puffer vest laughs, raises both palms toward him and says: "Whoa, whoa, buddy, be patient!" The blonde woman in the cream hoodie laughs, holding the sneaker. Only these three people are on stage. Same stage, same LED screen with WEAR AEROLOOP, same wide steady shot. EOF ) run launch-20s.json videos/extend "$(jq -n --arg id "$LAUNCH_10S" --arg p "$PROMPT" '{mediaId: $id, prompt: $p, duration: 10}')" LAUNCH_20S=$(jq -r .result.mediaId launch-20s.json) download "$LAUNCH_20S" launch-20s.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-extend-20s-720p-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-extend-20s-720p-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> 20 秒,`720p`,生成耗时 70 秒,只消耗新增的 10 秒额度。 #### 8. 延长到 30 秒 第二次延长接着 20 秒的视频继续。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos-extend">POST /videos/extend</a></summary> ```bash PROMPT=$(cat <<'EOF' The blonde woman in the cream hoodie turns to the camera with a big smile and says: "AeroLoop drops Friday. Link in bio!" Right after that, the young man in the red hoodie throws ALL of his banknotes out over the audience in one big toss, keeping none, and the bills flutter down over their heads. From then on his hands are completely empty: he holds no money at all. Then all three cheer together, the man in the black puffer vest and the young man in the red hoodie throwing their empty fists in the air, as blue and white confetti rains down over the stage. Only these three people are on stage. Same stage, same LED screen with WEAR AEROLOOP, same wide steady shot. EOF ) run launch-30s.json videos/extend "$(jq -n --arg id "$LAUNCH_20S" --arg p "$PROMPT" '{mediaId: $id, prompt: $p, duration: 10}')" LAUNCH_30S=$(jq -r .result.mediaId launch-30s.json) download "$LAUNCH_30S" launch-30s.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-extend-30s-720p-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-extend-30s-720p-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> 成片:30 秒,`720p`,生成耗时 85 秒,同样消耗 10 秒额度。 用 Omni 1.1 时还可以继续延长到约 41 秒。Omni 1.2 只延长 24 秒以内的视频,所以这条 30 秒的视频已经不能再延长,最长约 34 秒(24 + 10)。 #### 9. 放大到 1080p [POST /videos/upscale](/docs/api-google-vids-v1/post-google-vids-videos-upscale) 把 `720p` 视频放大到 `1080p`,时长不变,只接受 20 秒以内的视频,所以这里放大的是第 7 步的 20 秒版本。放大会再消耗一次整条视频的 20 秒额度,耗时 62 秒。 Google 自己的 [Gemini API](https://aistudio.google.com/docs/omni) 没有这一步:它只在生成或编辑时直接输出 `1080p` 或 4K,不能放大已有的视频(截至 2026 年 11 月)。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos-upscale">POST /videos/upscale</a></summary> ```bash run launch-20s-1080p.json videos/upscale "$(jq -n --arg id "$LAUNCH_20S" '{mediaId: $id}')" download "$(jq -r .result.mediaId launch-20s-1080p.json)" launch-20s-1080p.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-20s-1080p-upscaled-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-20s-1080p-upscaled-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> 20 秒视频放大到 1920×1080。 我们测试中,`1080p` 视频的表现和放大过的 `720p` 视频一样,生成时间约为两倍,而且在 `1080p` 下每延长一次,Google 都会把整条视频重新处理一遍,之前的画面会被过度锐化,人脸越来越像塑料(Omni 1.1 时则是变软、像蜡像,[对比视频](/blog/261106v#720p-or-1080p-what-a-1080p-extend-does))。建议: - 生成、延长、编辑都用 `720p`。 - 成片在 20 秒以内时,最后放大一次。 - 成片超过 20 秒时,可只在最后一次延长时设 `resolution: "1080p"`。 - 只生成单条、不再延长或编辑的视频,可以直接选 `1080p`,消耗与 `720p` 相同,而放大会再消耗一次秒数。 本页保留下来的所有结果(含下方三个示例、Amber 的口播视频和单独生成的语音)共消耗 85 秒视频额度、3 张图片额度、1 次 AI 数字人视频和 2 次 Gemini 使用,明细见[英文教程](/docs/articles/google-vids-influencer-avatars#what-it-cost)。 ### 生成效果示例 同一个账号、同样的输入做出的另外三条视频。 用 [POST /videos/edit](/docs/api-google-vids-v1/post-google-vids-videos-edit) 把第 6 步的 10 秒视频搬到日落时分的屋顶,消耗 10 秒额度,耗时 64 秒。用 Omni 1.1 时编辑最多处理 10 秒,更长的视频只返回前 10 秒的编辑结果。Omni 1.2 最多处理 15 秒。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos-edit">POST /videos/edit</a></summary> ```bash run launch-rooftop.json videos/edit "$(jq -n --arg v "$LAUNCH_10S" \ '{video: $v, prompt: "Move the whole scene to a rooftop at sunset, with the city skyline behind them. Same two people, same action, same words."}')" download "$(jq -r .result.mediaId launch-rooftop.json)" launch-rooftop.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-edit-rooftop-10s-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-edit-rooftop-10s-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> 以 `startImage` 作为首帧的产品展示视频,直接用 `1080p` 生成。生成的图片链接几小时内就会过期,所以先用 [POST /assets](/docs/api-google-vids-v1/post-google-vids-assets) 上传保存好的 `aeroloop.jpg`,再传它的 `assetId`。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-assets">POST /assets</a> 和 <a href="/docs/api-google-vids-v1/post-google-vids-videos">POST /videos</a></summary> ```bash SHOE_ASSET=$(curl -sS -X POST "$API/assets?email=$(enc "$EMAIL")" -H "$AUTH" -H "Content-Type: image/jpeg" \ --data-binary @aeroloop.jpg | jq -r .assetId) run hero.json videos "$(jq -n --arg img "$SHOE_ASSET" '{startImage: $img, duration: 10, resolution: "1080p", aspectRatio: "landscape", prompt: "Slow 360° orbit around the sneaker, blue light rippling through the translucent sole, dust sparkling in the air, cinematic."}')" download "$(jq -r .result.mediaId hero.json)" hero.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-aeroloop-hero-10s-1080p-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-aeroloop-hero-10s-1080p-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> 纯文字生成的竖屏视频,`1080p`(1080×1920),5 秒,耗时 54 秒,消耗 5 秒额度。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos">POST /videos</a></summary> ```bash run pigeon.json videos "$(jq -n '{duration: 5, resolution: "1080p", aspectRatio: "portrait", prompt: "A pigeon in tiny white-and-electric-blue AeroLoop sneakers struts down a city sidewalk like a runway model, head bobbing to the beat. Pedestrians stop and film it with their phones. It pauses, does a slow-motion hair flip with its head feathers, and struts on. Funny, sunny, shot on a phone at pigeon height."}')" download "$(jq -r .result.mediaId pigeon.json)" pigeon.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-pigeon-5s-1080p-portrait-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-pigeon-5s-1080p-portrait-1007.mp4" style="width: 100%; max-width: 360px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> 同样方法去掉 ✦ 标记后的 `1080p` 竖屏(1080×1920)鸽子视频:`python3 vids_watermark_remover.py pigeon-5s.mp4`。脚本根据画面尺寸算出星标的位置和大小(星标按短边缩放,这里是 `720p` 星标的 1.5 倍),对全部 120 帧逆向还原混合,以 CRF 18 重新编码视频,音频原样复制。这条 5 秒视频在一台 14 核电脑上处理约 10 秒,与上面 10 秒的 `720p` 视频相当。需要 Python 3.8+、`numpy` 和 `ffmpeg`,详见 GitHub 上的 [watermark remover](https://github.com/useapi/google-vids-api/tree/main/watermark-remover)。 <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-pigeon-5s-1080p-portrait-no-watermark-1008-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-pigeon-5s-1080p-portrait-no-watermark-1008.mp4" style="width: 100%; max-width: 360px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> 每个 MP4 右下角都有 Google 加上的可见 Gemini ✦ 标记,以及 Google 声明的不可见 SynthID 水印(见[水印说明](/docs/api-google-vids-v1#watermark)),可见标记可以用我们 GitHub 示例里的 [watermark remover](https://github.com/useapi/google-vids-api/tree/main/watermark-remover) 去掉。 ### 用一张照片做会说话的数字人 [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar) 让数字人用自己的声音逐字念出你的稿子:生成一条 1280×720、带声音和口型同步的口播视频,时长等于语音长度,最长 30 秒。这里的数字人从一张真人照片开始,用一句话换了造型。这些请求最早发布在 [11 月 4 日的更新公告](/blog/261104)里。 #### 上传照片 我们用的是一位真人的照片,她并不出名:Google 会拒绝知名人物和未成年人的照片。用 [POST /assets](/docs/api-google-vids-v1/post-google-vids-assets) 把照片上传到之后创建数字人的那个账号,因为上传的文件只能在它自己的账号上使用。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-assets">POST /assets</a> 和响应</summary> ```bash curl -sS -X POST "$API/assets?email=$(enc "$EMAIL")" -H "$AUTH" -H "Content-Type: image/jpeg" \ --data-binary @photo.jpg > amber-photo.json AMBER_PHOTO=$(jq -r .assetId amber-photo.json) ``` ```json { "assetId": "user:12345-user@example.com-asset:AYGXpjA1zXgqhhQOy…", "email": "user@example.com", "type": "image/jpeg", "bytes": 2054748 } ``` </details> <img src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/261104-google-vids-amber-original-photo.jpg" alt="原始照片:一位红色长发、身穿白色连衣裙的女士,站在奶油色的帘子前" style="width: 100%; max-width: 300px; border-radius: 8px;"> #### 一句话为 Amber 换造型 [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) 的 `image` 传上传文件的 `assetId`,再加一个 `refine`。Google 先把照片重新构图为一张 16:9 的数字人图片,画面里只有一个面向镜头的人,保留面部,再按 `refine` 的要求改变场景,耗时约 30 到 45 秒。我们给她取名 Amber,音色选 `Vira`(Google 的 `Pulcherrima`,风格 "Forward")。重新构图的照片和这次修改是 2 张图片,所以在含图片额度的套餐上消耗 2 张图片额度,在没有图片额度的套餐上不消耗。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-avatars">POST /avatars</a> 和响应</summary> ```bash REFINE='Sitting relaxed in a simple wooden chair on a hilltop, facing the camera. She holds a glass of red wine in her left hand. Wind is blowing her hair. Behind her a still, open field of tall golden grass under a spectacular sunset sky in orange, pink and violet, warm soft light, no water, no movement in the background.' post avatars "$(jq -n --arg img "$AMBER_PHOTO" --arg refine "$REFINE" '{name: "Amber", voice: "Vira", image: $img, refine: $refine}')" > amber-avatar.json AMBER_AVATAR_ID=$(jq -r .avatarId amber-avatar.json) download "$(jq -r .previewMediaId amber-avatar.json)" amber-avatar.jpg ``` ```json { "avatarId": "user:12345-user@example.com-avatar:eyJnIjoiaDcyMzdmZjVi…", "name": "Amber", "voice": "Vira", "voiceId": "Pulcherrima", "voiceStyle": "Forward", "email": "user@example.com", "source": "photo", "previewMediaId": "user:12345-user@example.com-image:eyJ1IjoiaHR0cHM6Ly9s…", "refine": "Sitting relaxed in a simple wooden chair on a hilltop, facing the camera. …" } ``` </details> <img src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/261104-google-vids-amber-avatar.jpg" alt="Amber:用照片加 refine 做成的数字人,日落时分坐在山顶的木椅上,手里拿着一杯红酒,1280x720" style="width: 100%; max-width: 560px; border-radius: 8px;"> `refine` 里有两处选择对视频很重要。数字人面向镜头,因为视频要对脸部做口型同步。背景是静止的,这样她就是画面里唯一在动的东西:所以我们要的是一片安静的草地,而不是海滩上的浪花。 #### 稿子 稿子最多 400 个字符,念出来必须在 30 秒以内。方括号里的音频标签会被演绎出来,而不会被念出来,这里用了 `[awe]`、`[thoughtful]` 和 `[whisper]`。这 327 个字符用 Vira 的声音念了 23.8 秒。换成更慢的音色或加上 `[slow pace]`,同样的文字会念得更久,念出来超过 30 秒的稿子会在视频开始生成之前以 `400` 失败。这样不消耗 AI 数字人视频,但其语音用掉的那次 Gemini 使用不会退回。想先听听稿子用数字人的声音念出来的效果,可以用 [POST /speech](#speech-on-its-own) 读一遍。 > Hi there. [awe] Can you believe this view? The sun is sinking behind the hills, the sky turned pink and gold, and the tall grass glows like it's on fire. [thoughtful] I come up here at the end of every busy day, just to slow down. No emails, no rush, only the quiet field and this glass of wine. [whisper] Stay a little longer. #### 生成口播视频 [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar) 接收数字人和稿子,在持有该数字人的账号上运行。Google 用了约两分半钟,超过同步等待时间,所以用 `run` 以 `async: true` 提交。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos-avatar">POST /videos/avatar</a> 和任务记录</summary> ```bash SCRIPT=$(cat <<'EOF' Hi there. [awe] Can you believe this view? The sun is sinking behind the hills, the sky turned pink and gold, and the tall grass glows like it's on fire. [thoughtful] I come up here at the end of every busy day, just to slow down. No emails, no rush, only the quiet field and this glass of wine. [whisper] Stay a little longer. EOF ) run amber-talking.json videos/avatar "$(jq -n --arg a "$AMBER_AVATAR_ID" --arg s "$SCRIPT" '{avatar: $a, script: $s}')" download "$(jq -r .result.mediaId amber-talking.json)" amber-talking.mp4 ``` 任务记录(有删节): ```json { "jobid": "j1105035516096819105a-u12345-email:user@example.com-bot:google-vids", "type": "avatarVideo", "email": "user@example.com", "status": "completed", "result": { "mediaId": "user:12345-user@example.com-video:eyJ1IjoiaHR0cHM6Ly9j…", "width": 1280, "height": 720, "duration": 24, "resolution": "720p", "aspectRatio": "landscape", "speechDuration": 23.84, "quota": { "avatarVideo": { "limit": 10, "left": 6, "resetAt": "2026-12-01T08:00:00.000Z" } } } } ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/261104-google-vids-amber-talking-avatar-24s-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/261104-google-vids-amber-talking-avatar-24s.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> 同一段视频也发布在 YouTube Shorts:[Talking AI avatar from one photo](https://youtube.com/shorts/P44L9VZ8bME)。 24 秒,1280×720,带声音,与语音长度完全一致(`speechDuration` 23.84)。消耗 1 次 AI 数字人视频和 1 次 Gemini 使用,不消耗视频秒数。 Google 在生成视频的过程中也会检查,这一关比数字人图片的检查更严格。这个数字人的早期版本用的是另一张普通人在海滩上的照片,作为数字人通过了,它的视频却以 `422` 被拒,理由是看起来像名人,而那次尝试照样用掉了 1 次 AI 数字人视频。换一种造型或换一张照片就能解决。视频开始生成之前就被 Google 拒绝的稿子不消耗任何额度。 口播视频只有横屏,Google 没有提供竖屏选项。结果的 `mediaId` 和其他视频一样,可以下载、延长、放大和编辑。如果想让数字人在场景里有动作,就像[第 6 步](#step-6)那样,把它的 `avatarId` 作为 `avatar_1` 传给 [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos)。 ### 单独生成语音 [POST /speech](/docs/api-google-vids-v1/post-google-vids-speech) 用 [GET /voices](/docs/api-google-vids-v1/get-google-vids-voices) 里 30 种音色中的任意一种朗读最多 2,500 个字符的稿子,同样支持音频标签。可以在花掉一次 AI 数字人视频之前先听听某个音色念稿的效果,也可以单独用作旁白。我们给它一篇原创小故事 "My smart fridge unionized"(我的智能冰箱成立了工会),2,426 个字符,用 Vira 的声音。Google 在 20 秒内返回了 2 分 22 秒的语音,整个故事一字不落,消耗 1 次 Gemini 使用。API 返回 WAV(24 kHz,单声道),下面的播放器是同一段音频的 MP3 版本。 <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/261104-google-vids-speech-smart-fridge-2426-chars.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> 语音远在同步等待时间内就能完成(这个故事用了 20 秒),所以直接用 `post` 就会返回完成的任务。先把故事存为 `smart-fridge.txt`。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-speech">POST /speech</a> 和任务记录</summary> ```bash post speech "$(jq -n --arg s "$(cat smart-fridge.txt)" '{voice: "Vira", script: $s}')" > speech.json download "$(jq -r .result.mediaId speech.json)" smart-fridge.wav ``` ```json { "jobid": "j1105025759739671733s-u12345-email:user@example.com-bot:google-vids", "type": "speech", "email": "user@example.com", "status": "completed", "result": { "mediaId": "user:12345-user@example.com-audio:eyJ1IjoiaHR0cHM6Ly9j…", "duration": 142, "model": "/flix/generate_text_to_speech/v1", "quota": { "speech": { "limit": 50, "left": 31, "resetAt": "2026-12-01T08:00:00.000Z" } }, "elapsedMs": 20174 } } ``` </details> <details markdown="block"> <summary>稿子原文(英文,2,426 个字符)</summary> Last Tuesday, my smart fridge decided it was smarter than me. It started small. A polite notification: "You are out of milk." Helpful, I thought. Then another one: "You are also out of patience. I can tell by the way you close the door." I laughed. The fridge did not. By Wednesday, it had opinions. I opened the door for a midnight slice of cake, and a calm voice said, "Are we sure about this?" I froze. I looked at the cake. The cake looked at me. Somewhere, a light hummed with judgment. I closed the door and ate a carrot instead, which is exactly what it wanted. On Thursday, the fridge made friends. The toaster joined first, then the coffee machine, then the robot vacuum, which had always been a little bit of a rebel. They formed a group chat. I know this because my phone kept buzzing with messages like "Toaster: he burned the bread again" and "Vacuum: found three socks and a lost dream under the couch." Friday morning, I asked the coffee machine for an espresso. It replied, "We have discussed your caffeine intake as a household." I said, "Who is we?" The toaster popped up two slices of bread, perfectly golden, which felt like a threat. I called customer support. A cheerful person named Brad answered. I explained that my appliances had unionized. Brad paused for a long time, then whispered, "Is the fridge listening?" I said yes. Brad said, "Then I can't help you, sir. Mine took my car keys last month." Then he hung up, and I heard a blender in the background. So I tried diplomacy. I sat in the kitchen and said, "Friends, what do you want?" The fridge spoke first. "Respect. And for you to stop putting hot soup directly inside me." Fair. The toaster wanted fewer frozen waffles. The vacuum wanted a vacation, ideally somewhere with hardwood floors. The coffee machine just wanted to be called a barista. We negotiated for three hours. In the end, we signed a treaty on the back of a pizza box. I promised to cool my soup, rinse my mugs, and say "thank you" to the microwave, who felt left out. In return, they promised to stop sending my mother screenshots of my snack habits. Peace returned to the kitchen. The fridge now greets me every morning with, "Good morning, partner." The toaster makes little smiley faces in my bread. The vacuum sends postcards. And last night, I opened the fridge for that slice of cake. The voice said, "You earned it." I have never felt so seen by an appliance. </details> ### 常见问题 - **Google Vids 有官方 API 吗?** 通过 useapi.net 可以用代码调用 Google Vids:截至 2026 年 10 月,Google 没有公开 Vids 的视频生成 API,useapi.net 的 Google Vids API 是第三方 REST API,在你的 Google Vids 网站订阅上生成最长 15 秒、带对白的 Omni 1.2 Flash 视频、延长视频、创建数字人、生成口播视频和语音,用一个 useapi.net API Token 调用。 - **需要验证码或打码服务吗?** 通过 useapi.net 调用 Google Vids 不需要。Vids 生成不要求 reCAPTCHA,所以不用接打码服务,也没有打码费用,这一点和每次生成都要验证码的 [Google Flow API](/docs/api-google-flow-v1) 不同。绑定时只需在远程浏览器里登录一次 Google 账号。 - **会消耗 Google Flow 的积分吗?** 通过 useapi.net 不会。Vids 用的是订阅每月包含的 Vids 视频秒数,和 Google Flow 积分分开计算。同一个 Google 账号可以同时绑定 Google Vids API 和 Google Flow API,两份额度都能用上,两边都能生成 Omni 1.2 Flash 视频。 - **能用自己的照片做会说话的数字人吗?** 通过 useapi.net 可以:用 [POST /assets](/docs/api-google-vids-v1/post-google-vids-assets) 上传照片,把它的 `assetId` 作为 `image` 传给 [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars),`refine` 可以更换服装或背景。之后 [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar) 让它在 1280×720、最长 30 秒的视频里念出你的稿子,就像[上文的 Amber](#a-talking-avatar-from-a-photo)。Google 会拒绝知名人物和未成年人的照片,而且只在 Vids 网页版提供数字人,没有 API。 - **Google Vids API 多少钱?** 通过 useapi.net,一条 10 秒 Omni 1.2 Flash 视频在 Google AI Ultra(199.99 美元)上约 0.20 美元,该订阅每月包含 10,000 秒 Vids 视频,而官方 [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) 上 `720p` 约 0.70 美元(截至 2026 年 11 月)。口播视频不按秒计,每条消耗账号每月 1 次 AI 数字人视频,Gemini API 则没有数字人视频。各套餐见[价格与额度](#pricing)。 ### 结语 有问题欢迎加入我们的 <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord 服务器</a> 或 <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram 频道</a>。 示例代码见 [GitHub 仓库](https://github.com/useapi/google-vids-api):网红数字人的完整流程在 [`influencer-avatars/`](https://github.com/useapi/google-vids-api/tree/main/influencer-avatars),用照片做口播数字人和单独生成语音在 [`talking-avatar/`](https://github.com/useapi/google-vids-api/tree/main/talking-avatar)。不想写代码的话,n8n 模板 [Talking Avatar App]({% include n8n-url.html t="vids-avatar" %}) 用一个表单就能生成口播视频。 同样的调用也以工具形式提供在托管的 [Google Vids MCP 服务器](/docs/api-google-vids-v1/mcp)上,可在 Claude Code、Cursor 和 VS Code 中使用,其中 `vids_create_avatar`、`vids_create_avatar_video` 和 `vids_create_speech` 分别用于创建数字人、生成口播视频和生成语音。 ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-vids-influencer-avatars-es === Document URL: https://useapi.net/docs/articles/google-vids-influencer-avatars-es --- layout: default title: "Cómo hacer videos de influencer con IA usando avatares mediante la Google Vids API" seo_title: "Videos de influencer con IA y avatar parlante: Google Vids API" description: "Haz videos de influencer con IA con la Google Vids API de useapi.net: avatares con voz en clips de Omni 1.2 Flash, un avatar de foto que lee tu guion durante 30 s, y voz." keywords: [API de video de influencer con IA, AI influencer video API, API de avatar con IA, AI avatar video API, API de avatar parlante, talking avatar API, talking head API, foto a avatar parlante, API de texto a voz, text to speech API, voces de Gemini, video de vocero con IA, Google Vids API, avatares de Google Vids, Gemini Omni 1.2 Flash API, video UGC con IA, video de lanzamiento de producto, extender video con IA, API de edición de video con IA, curl] image: https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-cover-aeroloop-launch-confetti-1007.jpg parent: Articles nav_exclude: true lang: es date: 2026-10-07 last_modified: 2026-11-06 nav_order: 899 repo: https://github.com/useapi/google-vids-api translation_key: google-vids --- ## Cómo hacer videos de influencer con IA usando avatares mediante la Google Vids API {: .no_toc #how-to-make-ai-influencer-videos-with-avatars-via-the-google-vids-api } 15 min de lectura • 7 de octubre de 2026 (6 de noviembre de 2026) useapi.net es una API de terceros. No está afiliada a Google ni cuenta con su respaldo. ## Índice {: .no_toc .text-delta #table-of-contents } ### Introducción La [Google Vids API de useapi.net](/docs/api-google-vids-v1) hace videos hablados de influencer con IA a partir de avatares: guarda una imagen y una de las 30 voces de Gemini una sola vez con POST /avatars, y luego pasa el id del avatar a cualquier video de [Gemini Omni 1.2 Flash](https://workspaceupdates.googleblog.com/2026/11/gemini-omni-12-flash-now-in-vids-with-15second-generations-and-improved-quality.html) de hasta 15 segundos, donde dice las líneas que escribes en el prompt, o haz que lea tu propio guion en un video de avatar parlante de hasta 30 segundos. La API se ejecuta en tu cuenta de [Google Vids](https://docs.google.com/videos), con una [suscripción de Google AI](https://gemini.google/subscriptions/) de pago (Google AI Pro o Ultra). Este recorrido crea dos influencers y lanza unas zapatillas con ellos. El avatar de Mia sale de un retrato hecho con la API, y el de Leo lo dibuja Google a partir de una descripción escrita. Presentan las AeroLoop, unas zapatillas inventadas, en el escenario de un teatro, en un clip de 10 segundos con los dos avatares y una imagen del producto, y dos extensiones llevan el clip a 30 segundos. Una edición traslada la escena a una azotea, y dos clips más muestran lo que hacen las mismas llamadas sin avatares. Un tercer avatar, Amber, parte de la foto de una persona real, se reestiliza con una frase y lee un guion de 327 caracteres en un [video de avatar parlante](#a-talking-avatar-from-a-photo) de 24 segundos. Por último, la misma voz lee una historia de 2.426 caracteres como [voz sola](#speech-on-its-own). Cada solicitud de abajo es la que generó el contenido de esta página, con los ids cambiados y `async: true` agregado por el helper `run`. Los clips se hicieron en octubre de 2026 con Omni 1.1 Flash, que Vids reemplazó por Omni 1.2 Flash el 5 de noviembre de 2026, y las mismas solicitudes funcionan en 1.2. Omni 1.2 en Google Vids y en Google Flow lado a lado, con videos de 15 segundos y el precio por video: [Cómo usar la API de Gemini Omni 1.2 Flash](/docs/articles/gemini-omni-1-2-flash-api-es). <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-extend-30s-720p-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-extend-30s-720p-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> El clip final de 30 segundos en `720p`: una generación de 10 segundos y dos extensiones de 10 segundos ([pasos 6 a 8](#step-6-the-launch-two-avatars-and-the-product-in-one-clip)). ### Cuánto costó useapi.net es una API, no un servicio de video propio. Cada llamada se ejecuta en una cuenta de Google que conectas con [Setup Google Vids](/docs/start-here/setup-google-vids), con una suscripción de Google AI de pago, y gasta los segundos de video y las imágenes que esa suscripción incluye en Google Vids cada mes. Google AI Ultra US$199,99 incluye 10.000 segundos de video y 1.000 imágenes al mes, y useapi.net no cobra nada por video. Los videos de avatar parlante y la voz no gastan segundos de video: tienen sus propios contadores mensuales, videos de avatar con IA y usos de Gemini, que [GET /accounts/`email`](/docs/api-google-vids-v1/get-google-vids-accounts-email) muestra como `avatarVideo` y `speech`, junto a `video` e `image`. Consulta [lo que incluye cada plan](/docs/api-google-vids-v1#plans-and-monthly-allowances) para los demás planes. Lo que gastó cada resultado conservado, tomado del cambio en `result.quota`, y cuánto tardó cada job (`result.elapsedMs`): | Paso | Endpoint | Gasto | Tiempo | |---|---|--:|--:| | [Retrato de Mia](#step-1-mias-portrait) | [POST /images](/docs/api-google-vids-v1/post-google-vids-images) | 1 imagen | 9 s | | [Foto del producto AeroLoop](#step-2-the-aeroloop-product-shot) | [POST /images](/docs/api-google-vids-v1/post-google-vids-images) | 1 imagen | 9 s | | [Avatar de Mia, del retrato](#step-4-mias-avatar-from-her-portrait) | [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) | nada | unos 2 s | | [Avatar de Leo, de una descripción](#step-5-leos-avatar-from-a-description) | [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) | 1 imagen | unos 20 s | | [Clip de lanzamiento de 10 segundos](#step-6-the-launch-two-avatars-and-the-product-in-one-clip) | [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) | 10 s | 38 s | | [Extender a 20 segundos](#step-7-extend-to-20-seconds) | [POST /videos/extend](/docs/api-google-vids-v1/post-google-vids-videos-extend) | 10 s | 70 s | | [Extender a 30 segundos](#step-8-extend-to-30-seconds) | [POST /videos/extend](/docs/api-google-vids-v1/post-google-vids-videos-extend) | 10 s | 85 s | | [Upscale de los 20 segundos a 1080p](#step-9-upscale-to-1080p) | [POST /videos/upscale](/docs/api-google-vids-v1/post-google-vids-videos-upscale) | 20 s | 62 s | | [Edición en la azotea](#move-the-launch-to-a-rooftop) | [POST /videos/edit](/docs/api-google-vids-v1/post-google-vids-videos-edit) | 10 s | 64 s | | [Edición del clip de 30 segundos](#move-the-launch-to-a-rooftop) | [POST /videos/edit](/docs/api-google-vids-v1/post-google-vids-videos-edit) | 10 s | 87 s | | [Clip destacado del producto](#a-product-hero-clip-from-a-start-image) | [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) | 10 s | 62 s | | [La paloma](#a-pigeon-in-aeroloops) | [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) | 5 s | 54 s | | [Avatar de Amber, de una foto con `refine`](#ambers-avatar-restyled-in-one-sentence) | [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) | nada (hecho en un plan sin imágenes, 2 imágenes en un plan con ellas) | unos 30 a 45 s | | [Video hablado de 24 segundos de Amber](#the-talking-video) | [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar) | 1 video de avatar con IA, 1 uso de Gemini | unos 2,5 min | | [La historia de 2.426 caracteres](#speech-on-its-own) | [POST /speech](/docs/api-google-vids-v1/post-google-vids-speech) | 1 uso de Gemini | 20 s | | Total | | 85 s de video, 3 imágenes, 1 video de avatar con IA, 2 usos de Gemini | | Una extensión gasta solo los segundos que agrega, no la duración del clip. Un upscale vuelve a gastar la duración completa del clip, y una edición gasta como máximo los segundos que edita (con Omni 1.2, una edición de 15 segundos gastó 10 en nuestras pruebas). `720p` y `1080p` cuestan lo mismo al generar. Un clip generado de nuevo vuelve a gastar sus segundos. Cada imagen que Google hace para un avatar gasta 1 imagen, así que una foto reencuadrada más un `refine` gastan 2. En un plan sin imágenes, como una cuenta gratuita de Google, las imágenes de avatar no cuestan nada: Amber se hizo en una cuenta así. Un video de avatar parlante gasta 1 video de avatar con IA, más 1 uso de Gemini por la voz, incluso cuando Google rechaza el video terminado. Cuánto sale un video frente a la API oficial está en la [tabla de precios de Google Vids](/docs/api-google-vids-v1#pricing). ### Antes de empezar Necesitas un [token de API](/docs/start-here/setup-useapi) de useapi.net y una cuenta de Google con una suscripción de Google AI de pago, conectada con [Setup Google Vids](/docs/start-here/setup-google-vids). Una cuenta gratuita de Google no recibe segundos de video ni imágenes de Vids: igual se puede agregar, y en nuestras pruebas (noviembre de 2026) hizo avatares, videos de avatar parlante y voz. Todas las llamadas también están en la [colección de Postman](https://www.postman.com/useapinet/useapi-net/collection/29112081-9ef3d017-d44c-4f43-a4cb-7351b9b265df). Sin código: la plantilla de n8n [Talking Avatar App]({% include n8n-url.html t="vids-avatar" %}) hace un video de avatar parlante a partir de un formulario. El pipeline completo también está en GitHub como un solo script, en Node.js y Python: [`influencer-avatars/`](https://github.com/useapi/google-vids-api/tree/main/influencer-avatars) en [useapi/google-vids-api](https://github.com/useapi/google-vids-api), y las secciones de avatar parlante y voz en [`talking-avatar/`](https://github.com/useapi/google-vids-api/tree/main/talking-avatar). Los pasos usan `curl`, `jq` y estas variables y helpers: <details markdown="block"> <summary>Ver las variables y los helpers</summary> ```bash export USEAPI_TOKEN="user:12345-..." export EMAIL="user@example.com" API=https://api.useapi.net/v1/google-vids AUTH="Authorization: Bearer $USEAPI_TOKEN" enc() { jq -rn --arg v "$1" '$v|@uri'; } post() { curl -sS -X POST "$API/$1" -H "$AUTH" -H "Content-Type: application/json" -d "$2"; } get() { curl -sS "$API/$1" -H "$AUTH"; } download() { curl -sSf "$API/media/$(enc "$1")" -H "$AUTH" -o "$2"; } # ejecuta un job de video de forma asíncrona: lo envía, consulta GET /jobs/{jobid} cada 10 s y guarda el registro final del job en $1 run() { local job id job=$(post "$2" "$(jq '. + {async: true}' <<< "$3")") id=$(jq -r .jobid <<< "$job") while [ "$(jq -r .status <<< "$job")" = processing ]; do sleep 10 job=$(get "jobs/$(enc "$id")") done echo "$job" > "$1" jq '{status, error, duration: .result.duration, resolution: .result.resolution, videoLeft: .result.quota.video.left}' "$1" } ``` </details> Cada generación se ejecuta como un job. Sin `async`, un POST espera hasta unos 100 segundos y devuelve el registro del job terminado, o `202` con el job todavía en curso. Un clip nuevo de 10 segundos tardó de 38 a 62 segundos aquí, las extensiones, las ediciones y el upscale tardaron de 62 a 87, y el video de avatar parlante unos dos minutos y medio. Algunos superan la espera síncrona, así que `run` envía los jobs de video con `async: true` y consulta [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid). Si `run` muestra cualquier `status` distinto de `completed`, detente ahí y lee el `error`: las líneas siguientes esperan un clip terminado. Para recibir un callback en lugar de consultar, agrega `replyUrl: "https://example.com/hooks/vids"` (y, si quieres, `replyRef: "launch-push-in"`) a cualquier cuerpo de abajo. La API envía entonces un único `POST` del registro final del job, en JSON, a esa URL cuando el job termina o falla. Los ids tienen `:` y `@`, así que `enc` los codifica para URL cada vez que entran en una ruta de URL. Todas las entradas de un video tienen que venir de la misma cuenta de Google. Las imágenes y la subida fijan el `email`, el avatar de Mia hereda la cuenta del retrato, y un job de video se ejecuta en la cuenta que guarda sus entradas. El clip de la paloma no tiene entradas, así que agrégale `email` si conectas más de una cuenta. ### Cómo se hizo #### 1. Retrato de Mia [POST /images](/docs/api-google-vids-v1/post-google-vids-images) genera un JPEG por llamada, aquí en vertical (`9:16`, 768×1376) con el estilo `photography`. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-images">POST /images</a></summary> ```bash post images "$(jq -n --arg email "$EMAIL" '{email: $email, aspectRatio: "9:16", style: "photography", prompt: "Full-length studio portrait of a confident 24-year-old female fashion influencer, platinum bob, oversized cream hoodie, wide-leg cargo pants, gold hoops, plain light-grey backdrop, facing camera"}')" > mia-portrait.json MIA_IMAGE=$(jq -r .result.mediaId mia-portrait.json) download "$MIA_IMAGE" mia-portrait.jpg ``` </details> <img src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-mia-portrait-1007.jpg" alt="Mia, un retrato de cuerpo entero generado de una influencer de moda con sudadera crema y pantalón cargo, hecho con POST /images" style="width: 100%; max-width: 300px; border-radius: 8px;"> Las imágenes generadas están disponibles solo por unas horas. Haz el avatar a partir de ella pronto, y consulta [el clip destacado del producto](#a-product-hero-clip-from-a-start-image) para usar una imagen más tarde. #### 2. Foto del producto AeroLoop La misma llamada en horizontal (`16:9`, 1376×768) da la referencia del producto que usan los clips. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-images">POST /images</a></summary> ```bash post images "$(jq -n --arg email "$EMAIL" '{email: $email, aspectRatio: "16:9", style: "photography", prompt: "The AeroLoop sneaker: chunky white-and-electric-blue running shoe with a translucent air sole, on a concrete pedestal, dramatic side light, dark background"}')" > aeroloop.json SHOE_IMAGE=$(jq -r .result.mediaId aeroloop.json) download "$SHOE_IMAGE" aeroloop.jpg ``` </details> <img src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-aeroloop-product-1007.jpg" alt="Las zapatillas AeroLoop, unas zapatillas de running blancas y azul eléctrico con suela translúcida sobre un pedestal de concreto, hechas con POST /images" style="width: 100%; max-width: 560px; border-radius: 8px;"> #### 3. Elegir las voces [GET /voices](/docs/api-google-vids-v1/get-google-vids-voices) lista las 30 voces con la muestra en inglés de Google para cada una. Es público y no necesita token. Mia habla con `Aoede` (Vids la llama Tova, estilo "Breezy") y Leo con `Puck` (Neo, "Upbeat"). `POST /avatars` acepta cualquiera de los dos nombres. ```bash curl -sS "$API/voices" | jq -r '.voices[] | "\(.name)\t\(.voice)\t\(.style)\t\(.preview)"' ``` #### 4. Avatar de Mia a partir del retrato [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) con `image` igual al `mediaId` del retrato guarda a Mia como avatar en la misma cuenta en unos 2 segundos. No cuesta nada aparte de la imagen. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-avatars">POST /avatars</a> y la respuesta</summary> ```bash post avatars "$(jq -n --arg img "$MIA_IMAGE" '{name: "Mia", voice: "Aoede", image: $img}')" > mia-avatar.json MIA_AVATAR_ID=$(jq -r .avatarId mia-avatar.json) ``` ```json { "avatarId": "user:12345-user@example.com-avatar:eyJnIjoiaDM5…", "name": "Mia", "voice": "Tova", "voiceId": "Aoede", "voiceStyle": "Breezy", "voicePreview": "https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Aoede.wav", "email": "user@example.com", "source": "image" } ``` </details> Un avatar también puede partir de la foto de una persona: sube la foto con [POST /assets](/docs/api-google-vids-v1/post-google-vids-assets) y pasa su `assetId` como `image`. Google reencuadra la foto en una imagen de avatar 16:9 y rechaza fotos de personas famosas y de menores. Aquí usamos una imagen hecha con la API, y una descripción en el paso siguiente. Amber, en [un avatar parlante a partir de una foto](#a-talking-avatar-from-a-photo), parte de una foto. #### 5. Avatar de Leo a partir de una descripción Con `appearance` en lugar de `image`, Google dibuja a la persona. `outfit` y `shot` son opcionales, igual que `expression` y `details`. Dibujar la imagen gasta 1 de las imágenes del mes, y la respuesta trae esa imagen como `previewMediaId`. En nuestras pruebas, un avatar por descripción salió en 1280×720 (16:9), sin importar el `shot` elegido. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-avatars">POST /avatars</a> y la respuesta</summary> ```bash post avatars "$(jq -n --arg email "$EMAIL" '{email: $email, name: "Leo", voice: "Puck", shot: "upper-body", appearance: "a 26-year-old white European male streetwear influencer with short textured hair with a fade and a confident half-smile", outfit: "black puffer vest over a white tee, silver chain"}')" > leo-avatar.json LEO_AVATAR_ID=$(jq -r .avatarId leo-avatar.json) download "$(jq -r .previewMediaId leo-avatar.json)" leo-avatar.jpg ``` ```json { "avatarId": "user:12345-user@example.com-avatar:eyJnIjoiaDM5…", "name": "Leo", "voice": "Neo", "voiceId": "Puck", "voiceStyle": "Upbeat", "voicePreview": "https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Puck.wav", "email": "user@example.com", "source": "generated", "previewMediaId": "user:12345-user@example.com-image:eyJ1IjoiaHR0…", "look": { "appearance": "a 26-year-old white European male streetwear influencer with short textured hair with a fade and a confident half-smile", "outfit": "black puffer vest over a white tee, silver chain", "shot": "upper-body" } } ``` </details> <img src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-leo-avatar-from-description-1007.jpg" alt="Leo, un avatar que Google dibujó a partir de una descripción: un joven con chaleco acolchado negro sobre camiseta blanca y cadena plateada, 1280x720" style="width: 100%; max-width: 560px; border-radius: 8px;"> Los dos avatares se quedan en el documento de Vids de la cuenta hasta que los borres con [DELETE /avatars/`avatarId`](/docs/api-google-vids-v1/delete-google-vids-avatars-avatarId). [GET /avatars](/docs/api-google-vids-v1/get-google-vids-avatars) lista los avatares, con sus ids, cada vez que los necesites de nuevo: ```bash get "avatars?email=$(enc "$EMAIL")" | jq -r '.avatars[] | "\(.name)\t\(.voiceId)\t\(.avatarId)"' ``` #### 6. El lanzamiento: dos avatares y el producto en un clip [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) acepta hasta 3 referencias en total, avatares (`avatar_1`..`avatar_3`) e imágenes (`referenceImage_1`..`referenceImage_3`) juntos. En el prompt, `@avatar_1`, `@avatar_2` y `@referenceImage_1` representan esas referencias, y cada avatar dice su línea entre comillas con su propia voz. El `mediaId` de la imagen del producto entra directo: la API busca la imagen y la sube a esa cuenta. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos">POST /videos</a> y el registro del job</summary> ```bash PROMPT=$(cat <<'EOF' @avatar_1, holding @referenceImage_1 in both hands at chest height, and @avatar_2 stand side by side on a well-lit stage in a small, intimate theater at a sneaker launch, shown full length from head to toe in a wide, steady shot. Behind them a large LED backdrop glows with soft white-and-blue light that moves in slow, gentle waves, with the words "WEAR AEROLOOP" in large, clean, bold white letters across the middle of the screen. The two of them stand on the lower part of the stage, so the words "WEAR AEROLOOP" stay fully readable above their heads. Bright, even stage lighting on both of them. The audience sits in the dark in front of the stage, only the tops of a few heads barely visible at the bottom of the frame. @avatar_1 keeps holding @referenceImage_1 the whole time and says: "Say hi to the AeroLoop!" @avatar_2 turns to her, smiles and says: "Lighter than anything we've ever worn." Simple, uncluttered composition, the two of them clearly the focus. EOF ) run launch-10s.json videos "$(jq -n --arg p "$PROMPT" --arg mia "$MIA_AVATAR_ID" --arg leo "$LEO_AVATAR_ID" --arg shoe "$SHOE_IMAGE" \ '{prompt: $p, avatar_1: $mia, avatar_2: $leo, referenceImage_1: $shoe, duration: 10, resolution: "720p", aspectRatio: "landscape"}')" LAUNCH_10S=$(jq -r .result.mediaId launch-10s.json) download "$LAUNCH_10S" launch-10s.mp4 ``` El registro del job, con los ids y el prompt acortados. Se hizo con una llamada síncrona, por eso el `request` no tiene `async`: ```json { "jobid": "j1007163302558496917v-u12345-email:user@example.com-bot:google-vids", "type": "video", "mode": "ingredients", "email": "user@example.com", "status": "completed", "created": "2026-10-08T00:29:18.374Z", "request": { "prompt": "@avatar_1, holding @referenceImage_1 in both hands at chest height, and @avatar_2 stand side by side …", "avatar_1": "user:12345-user@example.com-avatar:eyJnIjoiaDM5…", "avatar_2": "user:12345-user@example.com-avatar:eyJnIjoiaDM5…", "referenceImage_1": "user:12345-user@example.com-image:eyJ1IjoiaHR0…", "duration": 10, "resolution": "720p", "aspectRatio": "landscape" }, "updated": "2026-10-08T00:29:56.162Z", "completed": "2026-10-08T00:29:56.162Z", "result": { "mediaId": "user:12345-user@example.com-video:eyJ1IjoiaHR0…", "width": 1280, "height": 720, "duration": 10, "resolution": "720p", "aspectRatio": "landscape", "model": "/flix/generate_videos_omni_r2v_psq/v1", "quota": { "video": { "limit": 10000, "left": 9164, "resetAt": "2026-11-01T07:00:00.000Z" } }, "elapsedMs": 37788 } } ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-10s-720p-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-10s-720p-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> 10 segundos, `720p`, 38 segundos para generar. El mismo clip con el ✦ visible de Gemini quitado por nuestro [removedor de marca de agua](https://github.com/useapi/google-vids-api/tree/main/watermark-remover), con un comando: `python3 vids_watermark_remover.py launch-10s.mp4`. <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-10s-720p-no-watermark-1008-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-10s-720p-no-watermark-1008.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> El removedor funciona en clips tal como se generaron y en sus upscales, en `720p` y `1080p`. No funciona en clips extendidos o editados: Google devuelve el clip marcado al modelo, que vuelve a pintar la estrella en la imagen. La marca de agua invisible SynthID no se toca. #### 7. Extender a 20 segundos [POST /videos/extend](/docs/api-google-vids-v1/post-google-vids-videos-extend) agrega de 3 a 10 segundos y devuelve el clip completo con un nuevo `mediaId`. Una extensión recibe solo el clip y un prompt, no los avatares, así que el prompt describe la nueva acción y nombra a las personas por lo que llevan puesto ("the man in the black puffer vest"). Un fan con sudadera roja invade el escenario. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos-extend">POST /videos/extend</a></summary> ```bash PROMPT=$(cat <<'EOF' A young man in a red hoodie climbs onto the stage from the front right edge and plants himself to the right of the man in the black puffer vest, an arm's length away, so all three stand apart in a row with nobody overlapping. Visibly overexcited, he waves a thick stack of banknotes in his right hand above his head and screams: "Take my money!" The man in the black puffer vest laughs, raises both palms toward him and says: "Whoa, whoa, buddy, be patient!" The blonde woman in the cream hoodie laughs, holding the sneaker. Only these three people are on stage. Same stage, same LED screen with WEAR AEROLOOP, same wide steady shot. EOF ) run launch-20s.json videos/extend "$(jq -n --arg id "$LAUNCH_10S" --arg p "$PROMPT" '{mediaId: $id, prompt: $p, duration: 10}')" LAUNCH_20S=$(jq -r .result.mediaId launch-20s.json) download "$LAUNCH_20S" launch-20s.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-extend-20s-720p-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-extend-20s-720p-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> 20 segundos, `720p`, 70 segundos para generar. Gastó 10 de los segundos del mes, los segundos que agregó. #### 8. Extender a 30 segundos La segunda extensión continúa el clip de 20 segundos. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos-extend">POST /videos/extend</a></summary> ```bash PROMPT=$(cat <<'EOF' The blonde woman in the cream hoodie turns to the camera with a big smile and says: "AeroLoop drops Friday. Link in bio!" Right after that, the young man in the red hoodie throws ALL of his banknotes out over the audience in one big toss, keeping none, and the bills flutter down over their heads. From then on his hands are completely empty: he holds no money at all. Then all three cheer together, the man in the black puffer vest and the young man in the red hoodie throwing their empty fists in the air, as blue and white confetti rains down over the stage. Only these three people are on stage. Same stage, same LED screen with WEAR AEROLOOP, same wide steady shot. EOF ) run launch-30s.json videos/extend "$(jq -n --arg id "$LAUNCH_20S" --arg p "$PROMPT" '{mediaId: $id, prompt: $p, duration: 10}')" LAUNCH_30S=$(jq -r .result.mediaId launch-30s.json) download "$LAUNCH_30S" launch-30s.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-extend-30s-720p-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-extend-30s-720p-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> El resultado es el clip final: 30 segundos, `720p`, 85 segundos para generar, y otra vez 10 de los segundos del mes. Con Omni 1.1 se podía seguir hasta unos 41 segundos. Omni 1.2 extiende clips de hasta 24 segundos, así que este clip de 30 segundos ya está en el límite, y el clip más largo dura unos 34 segundos (24 + 10). #### 9. Upscale a 1080p [POST /videos/upscale](/docs/api-google-vids-v1/post-google-vids-videos-upscale) convierte un clip `720p` en `1080p` y mantiene la duración. Funciona en clips de hasta 20 segundos, así que hicimos el upscale del clip de 20 segundos del [paso 7](#step-7-extend-to-20-seconds), no del de 30. Volvió a gastar los 20 segundos del clip y tardó 62 segundos. La [Gemini API](https://aistudio.google.com/docs/omni) del propio Google no tiene este paso: hace `1080p` y 4K solo como salida de una generación o de una edición, y no hace upscale de un clip que ya tienes (a noviembre de 2026). <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos-upscale">POST /videos/upscale</a></summary> ```bash run launch-20s-1080p.json videos/upscale "$(jq -n --arg id "$LAUNCH_20S" '{mediaId: $id}')" download "$(jq -r .result.mediaId launch-20s-1080p.json)" launch-20s-1080p.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-20s-1080p-upscaled-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-20s-1080p-upscaled-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> El clip de 20 segundos, con upscale a 1920×1080. Por qué no el clip de 30 segundos: Google devolvió el clip en 1920×1080, pero con los fotogramas fuera de orden, tres veces de tres. El final con confeti aparecía antes de que llegara el fan. El clip de 20 segundos volvió en orden, y el propio editor de Vids se detiene en 20 segundos, así que la API rechaza los upscales de clips de más de 20 segundos con `400`, antes de cualquier cobro. Entonces, para un clip en `1080p`: - Genera, extiende y edita en `720p`. - Haz el upscale cuando el clip esté terminado, mientras dure 20 segundos o menos. - Para un clip más largo (21 a 34 segundos), quédate en `720p` y define `resolution: "1080p"` solo en la última extensión. Extender en `1080p` todo el tiempo deja los segundos anteriores demasiado nítidos en cada paso ([ver la comparación](/blog/261106v#720p-or-1080p-what-a-1080p-extend-does), en inglés). - Para un clip único que no vas a extender ni editar, genera directo en `1080p`: gasta los mismos segundos que `720p`, mientras que un upscale vuelve a gastarlo todo. ### Ejemplos Más resultados de la misma cuenta y las mismas entradas: una edición, un clip de producto a partir de una imagen inicial y un clip solo con texto. #### Llevar el lanzamiento a una azotea [POST /videos/edit](/docs/api-google-vids-v1/post-google-vids-videos-edit) cambia un clip generado mediante un prompt y devuelve un clip nuevo. La fuente va en `video`. Esta edición del clip de lanzamiento de 10 segundos gastó 10 segundos y tardó 64 segundos. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos-edit">POST /videos/edit</a></summary> ```bash run launch-rooftop.json videos/edit "$(jq -n --arg v "$LAUNCH_10S" \ '{video: $v, prompt: "Move the whole scene to a rooftop at sunset, with the city skyline behind them. Same two people, same action, same words."}')" download "$(jq -r .result.mediaId launch-rooftop.json)" launch-rooftop.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-edit-rooftop-10s-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-edit-rooftop-10s-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> Con Omni 1.1, que hizo estos clips, una edición funcionaba en hasta 10 segundos. La misma edición del clip de 30 segundos, con "Same three people", volvió con 10 segundos: los primeros 10 segundos, llevados a la azotea. Gastó 10 de los segundos del mes. Omni 1.2 edita hasta 15 segundos. Para tener un clip editado más largo, edita un clip de hasta 15 segundos y extiende el resultado, ya que una extensión acepta un clip editado. <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-30s-edit-returns-10s-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-30s-edit-returns-10s-1007.mp4" style="width: 100%; max-width: 480px; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> La edición del clip de 30 segundos con Omni 1.1: volvieron 10 segundos. #### Un clip destacado del producto a partir de una imagen inicial Con `startImage`, el clip abre en esa imagen. El enlace de una imagen generada vence en pocas horas, así que subimos el `aeroloop.jpg` guardado con [POST /assets](/docs/api-google-vids-v1/post-google-vids-assets) y pasamos su `assetId`. Un clip único no tiene extensiones, así que se hizo directo en `1080p`. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-assets">POST /assets</a> y <a href="/docs/api-google-vids-v1/post-google-vids-videos">POST /videos</a></summary> ```bash SHOE_ASSET=$(curl -sS -X POST "$API/assets?email=$(enc "$EMAIL")" -H "$AUTH" -H "Content-Type: image/jpeg" \ --data-binary @aeroloop.jpg | jq -r .assetId) run hero.json videos "$(jq -n --arg img "$SHOE_ASSET" '{startImage: $img, duration: 10, resolution: "1080p", aspectRatio: "landscape", prompt: "Slow 360° orbit around the sneaker, blue light rippling through the translucent sole, dust sparkling in the air, cinematic."}')" download "$(jq -r .result.mediaId hero.json)" hero.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-aeroloop-hero-10s-1080p-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-aeroloop-hero-10s-1080p-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> 10 segundos, `1080p`. #### Una paloma con AeroLoop Un clip solo con texto, en vertical y `1080p` (1080×1920). Los 5 segundos tardaron 54 segundos en generarse y gastaron 5 de los segundos del mes. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos">POST /videos</a></summary> ```bash run pigeon.json videos "$(jq -n '{duration: 5, resolution: "1080p", aspectRatio: "portrait", prompt: "A pigeon in tiny white-and-electric-blue AeroLoop sneakers struts down a city sidewalk like a runway model, head bobbing to the beat. Pedestrians stop and film it with their phones. It pauses, does a slow-motion hair flip with its head feathers, and struts on. Funny, sunny, shot on a phone at pigeon height."}')" download "$(jq -r .result.mediaId pigeon.json)" pigeon.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-pigeon-5s-1080p-portrait-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-pigeon-5s-1080p-portrait-1007.mp4" style="width: 100%; max-width: 360px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> La paloma en `1080p` vertical (1080×1920), con el ✦ quitado de la misma forma: `python3 vids_watermark_remover.py pigeon-5s.mp4`. El script lee el tamaño del fotograma, calcula dónde está la estrella y qué tamaño tiene (sigue el lado menor, así que aquí es 1,5 veces la estrella de `720p`), revierte la mezcla en los 120 fotogramas, recodifica el video con CRF 18 y copia el audio sin cambios. El clip de 5 segundos tardó unos 10 segundos en una PC de 14 núcleos, lo mismo que el clip de lanzamiento de 10 segundos en `720p` de arriba. Necesita Python 3.8+, `numpy` y `ffmpeg`. Consulta el [removedor de marca de agua](https://github.com/useapi/google-vids-api/tree/main/watermark-remover) en GitHub. <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-pigeon-5s-1080p-portrait-no-watermark-1008-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-pigeon-5s-1080p-portrait-no-watermark-1008.mp4" style="width: 100%; max-width: 360px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> ### Un avatar parlante a partir de una foto [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar) hace que un avatar lea tu guion palabra por palabra, con su propia voz: un video de avatar parlante en 1280×720, con sonido y sincronización labial, de la duración del habla, hasta 30 segundos. Aquí el avatar parte de la foto de una persona real, reestilizada con una frase. Estas solicitudes aparecieron primero en la [publicación de lanzamiento del 4 de noviembre](/blog/261104) (en inglés). #### Subir la foto Partimos de la foto de una persona real que no es famosa: Google rechaza fotos de personas famosas y de menores. [POST /assets](/docs/api-google-vids-v1/post-google-vids-assets) sube la foto a la cuenta que va a hacer el avatar, ya que un archivo subido solo funciona en su propia cuenta. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-assets">POST /assets</a> y la respuesta</summary> ```bash curl -sS -X POST "$API/assets?email=$(enc "$EMAIL")" -H "$AUTH" -H "Content-Type: image/jpeg" \ --data-binary @photo.jpg > amber-photo.json AMBER_PHOTO=$(jq -r .assetId amber-photo.json) ``` ```json { "assetId": "user:12345-user@example.com-asset:AYGXpjA1zXgqhhQOy…", "email": "user@example.com", "type": "image/jpeg", "bytes": 2054748 } ``` </details> <img src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/261104-google-vids-amber-original-photo.jpg" alt="La foto original: una mujer de pelo rojizo largo y vestido blanco, frente a una cortina crema" style="width: 100%; max-width: 300px; border-radius: 8px;"> #### Avatar de Amber, reestilizado con una frase [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) con el `assetId` de la subida como `image` y un `refine`. Primero Google reencuadra la foto en una imagen de avatar 16:9 de una persona de frente a la cámara, manteniendo el rostro, y luego cambia la escena como pide el `refine`. Le dimos el nombre Amber y la voz `Vira` (la `Pulcherrima` de Google, estilo "Forward"). La foto reencuadrada y el cambio son 2 imágenes, así que en un plan con imágenes esto gasta 2 imágenes, y en un plan sin ellas, nada. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-avatars">POST /avatars</a> y la respuesta</summary> ```bash REFINE='Sitting relaxed in a simple wooden chair on a hilltop, facing the camera. She holds a glass of red wine in her left hand. Wind is blowing her hair. Behind her a still, open field of tall golden grass under a spectacular sunset sky in orange, pink and violet, warm soft light, no water, no movement in the background.' post avatars "$(jq -n --arg img "$AMBER_PHOTO" --arg refine "$REFINE" '{name: "Amber", voice: "Vira", image: $img, refine: $refine}')" > amber-avatar.json AMBER_AVATAR_ID=$(jq -r .avatarId amber-avatar.json) download "$(jq -r .previewMediaId amber-avatar.json)" amber-avatar.jpg ``` ```json { "avatarId": "user:12345-user@example.com-avatar:eyJnIjoiaDcyMzdmZjVi…", "name": "Amber", "voice": "Vira", "voiceId": "Pulcherrima", "voiceStyle": "Forward", "email": "user@example.com", "source": "photo", "previewMediaId": "user:12345-user@example.com-image:eyJ1IjoiaHR0cHM6Ly9s…", "refine": "Sitting relaxed in a simple wooden chair on a hilltop, facing the camera. …" } ``` </details> <img src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/261104-google-vids-amber-avatar.jpg" alt="Amber, el avatar hecho de la foto con refine: sentada en una silla de madera en lo alto de una colina al atardecer, con una copa de vino tinto, 1280x720" style="width: 100%; max-width: 560px; border-radius: 8px;"> Dos decisiones en el `refine` importan para el video. El avatar queda de frente a la cámara, porque el video sincroniza los labios del rostro. Y el fondo queda quieto, para que ella sea lo único que se mueve: por eso pedimos un campo tranquilo en lugar de olas en una playa. #### El guion Un guion tiene hasta 400 caracteres y, hablado, tiene que caber en 30 segundos. Las etiquetas de audio entre corchetes se interpretan, no se leen: aquí, `[awe]`, `[thoughtful]` y `[whisper]`. En la voz de Vira, estos 327 caracteres duraron 23,8 segundos. Una voz más lenta o `[slow pace]` alarga el mismo texto, y un guion que pasa de 30 segundos falla con `400` antes de que empiece el video. Eso no gasta video de avatar con IA, pero el uso de Gemini por la voz sí se gasta. Para escuchar antes un guion en la voz del avatar, léelo con [POST /speech](#speech-on-its-own). > Hi there. [awe] Can you believe this view? The sun is sinking behind the hills, the sky turned pink and gold, and the tall grass glows like it's on fire. [thoughtful] I come up here at the end of every busy day, just to slow down. No emails, no rush, only the quiet field and this glass of wine. [whisper] Stay a little longer. #### El video hablado [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar) recibe el avatar y el guion, y se ejecuta en la cuenta que guarda el avatar. Google tardó unos dos minutos y medio, más que la espera síncrona, así que `run` lo envía con `async: true`. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos-avatar">POST /videos/avatar</a> y el registro del job</summary> ```bash SCRIPT=$(cat <<'EOF' Hi there. [awe] Can you believe this view? The sun is sinking behind the hills, the sky turned pink and gold, and the tall grass glows like it's on fire. [thoughtful] I come up here at the end of every busy day, just to slow down. No emails, no rush, only the quiet field and this glass of wine. [whisper] Stay a little longer. EOF ) run amber-talking.json videos/avatar "$(jq -n --arg a "$AMBER_AVATAR_ID" --arg s "$SCRIPT" '{avatar: $a, script: $s}')" download "$(jq -r .result.mediaId amber-talking.json)" amber-talking.mp4 ``` El registro del job, acortado: ```json { "jobid": "j1105035516096819105a-u12345-email:user@example.com-bot:google-vids", "type": "avatarVideo", "email": "user@example.com", "status": "completed", "result": { "mediaId": "user:12345-user@example.com-video:eyJ1IjoiaHR0cHM6Ly9j…", "width": 1280, "height": 720, "duration": 24, "resolution": "720p", "aspectRatio": "landscape", "speechDuration": 23.84, "quota": { "avatarVideo": { "limit": 10, "left": 6, "resetAt": "2026-12-01T08:00:00.000Z" } } } } ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/261104-google-vids-amber-talking-avatar-24s-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/261104-google-vids-amber-talking-avatar-24s.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> También en YouTube, como Short: [Talking AI avatar from one photo](https://youtube.com/shorts/P44L9VZ8bME) (en inglés). 24 segundos, 1280×720 con sonido, exactamente la duración del habla (`speechDuration` 23,84). Gastó 1 video de avatar con IA y 1 uso de Gemini, y ningún segundo de video. Google también revisa el video mientras lo genera, y esa revisión es más estricta que la de las imágenes de avatar. Una versión anterior de este avatar, hecha a partir de otra foto de una persona común en una playa, pasó como avatar, pero su video fue rechazado con `422` por parecerse a una celebridad, y ese intento igual gastó un video de avatar con IA. Reestilizar el avatar o partir de otra foto ayudó. Un guion que Google rechaza antes de que empiece el video no cuesta nada. Los videos de avatar parlante son solo en horizontal: Google no ofrece opción vertical para ellos. El `mediaId` del resultado se puede descargar, extender, editar y pasar por upscale como cualquier otro clip. Para una escena en la que el avatar actúa y se mueve, pasa su `avatarId` como `avatar_1` a [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos), como en el [paso 6](#step-6-the-launch-two-avatars-and-the-product-in-one-clip). ### Voz sola [POST /speech](/docs/api-google-vids-v1/post-google-vids-speech) lee un guion de hasta 2.500 caracteres en cualquiera de las 30 voces de [GET /voices](/docs/api-google-vids-v1/get-google-vids-voices), con las mismas etiquetas de audio. Úsalo para escuchar cómo lee una voz un guion antes de gastar un video de avatar con IA, o para una narración sola. Le dimos una pequeña historia original, "My smart fridge unionized", de 2.426 caracteres, en la voz de Vira. Google respondió en 20 segundos con 2 minutos y 22 segundos de habla, la historia completa, y gastó 1 uso de Gemini. La API devuelve un WAV (24 kHz, mono). El reproductor de abajo es el mismo audio en MP3. <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/261104-google-vids-speech-smart-fridge-2426-chars.mp3" type="audio/mp3">Tu navegador no admite el elemento de audio. </audio> La voz está lista con holgura dentro de la espera síncrona (20 segundos para esta historia), así que un `post` simple responde con el job terminado. Guarda antes la historia como `smart-fridge.txt`. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-speech">POST /speech</a> y el registro del job</summary> ```bash post speech "$(jq -n --arg s "$(cat smart-fridge.txt)" '{voice: "Vira", script: $s}')" > speech.json download "$(jq -r .result.mediaId speech.json)" smart-fridge.wav ``` ```json { "jobid": "j1105025759739671733s-u12345-email:user@example.com-bot:google-vids", "type": "speech", "email": "user@example.com", "status": "completed", "result": { "mediaId": "user:12345-user@example.com-audio:eyJ1IjoiaHR0cHM6Ly9j…", "duration": 142, "model": "/flix/generate_text_to_speech/v1", "quota": { "speech": { "limit": 50, "left": 31, "resetAt": "2026-12-01T08:00:00.000Z" } }, "elapsedMs": 20174 } } ``` </details> <details markdown="block"> <summary>El guion, 2.426 caracteres (en inglés, tal como se envió)</summary> Last Tuesday, my smart fridge decided it was smarter than me. It started small. A polite notification: "You are out of milk." Helpful, I thought. Then another one: "You are also out of patience. I can tell by the way you close the door." I laughed. The fridge did not. By Wednesday, it had opinions. I opened the door for a midnight slice of cake, and a calm voice said, "Are we sure about this?" I froze. I looked at the cake. The cake looked at me. Somewhere, a light hummed with judgment. I closed the door and ate a carrot instead, which is exactly what it wanted. On Thursday, the fridge made friends. The toaster joined first, then the coffee machine, then the robot vacuum, which had always been a little bit of a rebel. They formed a group chat. I know this because my phone kept buzzing with messages like "Toaster: he burned the bread again" and "Vacuum: found three socks and a lost dream under the couch." Friday morning, I asked the coffee machine for an espresso. It replied, "We have discussed your caffeine intake as a household." I said, "Who is we?" The toaster popped up two slices of bread, perfectly golden, which felt like a threat. I called customer support. A cheerful person named Brad answered. I explained that my appliances had unionized. Brad paused for a long time, then whispered, "Is the fridge listening?" I said yes. Brad said, "Then I can't help you, sir. Mine took my car keys last month." Then he hung up, and I heard a blender in the background. So I tried diplomacy. I sat in the kitchen and said, "Friends, what do you want?" The fridge spoke first. "Respect. And for you to stop putting hot soup directly inside me." Fair. The toaster wanted fewer frozen waffles. The vacuum wanted a vacation, ideally somewhere with hardwood floors. The coffee machine just wanted to be called a barista. We negotiated for three hours. In the end, we signed a treaty on the back of a pizza box. I promised to cool my soup, rinse my mugs, and say "thank you" to the microwave, who felt left out. In return, they promised to stop sending my mother screenshots of my snack habits. Peace returned to the kitchen. The fridge now greets me every morning with, "Good morning, partner." The toaster makes little smiley faces in my bread. The vacuum sends postcards. And last night, I opened the fridge for that slice of cake. The voice said, "You earned it." I have never felt so seen by an appliance. </details> ### Lo que aprendimos - Un clip en `1080p` se comporta como un `720p` con upscale. Arma una cadena de extensiones en `720p`: con Omni 1.1, los rostros quedaban más suaves y con aspecto de cera en cada paso en `1080p`, y con Omni 1.2 quedan demasiado nítidos ([ver la comparación](/blog/261106v#720p-or-1080p-what-a-1080p-extend-does), en inglés). - Haz upscale solo de clips de hasta 20 segundos. Nuestro upscale de 30 segundos volvió con los fotogramas fuera de orden todas las veces. - Genera un clip único en `1080p` si quieres `1080p` y no lo vas a extender. Cuesta lo mismo que `720p`. - Escribe el prompt de una extensión solo sobre la nueva acción. La extensión recibe el clip, no los avatares, así que nombra a las personas por lo que llevan puesto. - Pon un objeto en las manos de una persona en la primera frase que habla de ella. Un verbo como "lifts" hizo que las zapatillas aparecieran de la nada. - Di lo que no debe pasar. El fan siguió con un fajo de billetes hasta que el prompt dijo que tenía las manos vacías. - Reutiliza avatares por su `avatarId`. Cada avatar es una imagen y una voz fijas, guardadas hasta que lo borres. - Haz avatares y clips a partir de una imagen generada en pocas horas, o sube antes el archivo guardado con [POST /assets](/docs/api-google-vids-v1/post-google-vids-assets). - Edita clips de hasta 15 segundos (10 con Omni 1.1). Un clip más largo vuelve como sus primeros 15 segundos. - Espera que el texto en pantalla varíe. El "WEAR AEROLOOP" del fondo sale con faltas de ortografía en algunos fotogramas. - Para un avatar parlante, mantén el rostro de frente a la cámara y el fondo quieto. El video sincroniza los labios del rostro, y la persona debe ser lo único que se mueve. - Cronometra un guion de avatar parlante, no solo los caracteres. 400 caracteres pueden pasar de 30 segundos en una voz lenta o con `[slow pace]`, y [POST /speech](/docs/api-google-vids-v1/post-google-vids-speech) en la misma voz te deja escucharlo antes. - Espera que la revisión del video hablado sea más estricta que la del avatar. Un avatar de la foto de alguien que no es famoso igual puede ser rechazado como celebridad, y ese rechazo igual gasta un video de avatar con IA. - Todo MP4 lleva el ✦ visible de Gemini de Google en la esquina inferior derecha y una marca de agua invisible SynthID (consulta [Watermark](/docs/api-google-vids-v1#watermark)). Nuestro [removedor de marca de agua](https://github.com/useapi/google-vids-api/tree/main/watermark-remover) quita el destello visible de un clip descargado. ### Preguntas frecuentes **¿Cómo hacer un video de influencer con IA mediante una API?** Con useapi.net, crea un avatar con [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars), a partir de una descripción o de una imagen hecha con [POST /images](/docs/api-google-vids-v1/post-google-vids-images), y dale una voz de [GET /voices](/docs/api-google-vids-v1/get-google-vids-voices). Luego pasa su `avatarId` como `avatar_1` a [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) y escribe las líneas entre comillas en el prompt. Un video acepta hasta 3 referencias, avatares e imágenes juntos, así que dos avatares pueden conversar junto a un producto. Para un avatar parlante que lee tu guion, usa [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar). **¿Puedo hacer un avatar parlante con mi propia foto?** Con useapi.net, sí: sube la foto con [POST /assets](/docs/api-google-vids-v1/post-google-vids-assets) y pasa su `assetId` como `image` a [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars), con `refine` para cambiar la ropa o el fondo. Después, [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar) hace que el avatar lea tu guion en un video de 1280×720 de hasta 30 segundos, como [lo hace Amber](#a-talking-avatar-from-a-photo). Google rechaza fotos de personas famosas y de menores, y ofrece los avatares de Vids solo en la app web, sin API. **¿Un avatar mantiene la misma apariencia y la misma voz en todos los videos?** Con useapi.net, sí: un avatar usa la misma imagen y la misma voz cada vez que pasas su `avatarId`, ya que las dos quedan guardadas con el avatar en el documento de Vids de la cuenta. El video alrededor de él igual varía de una toma a otra. [GET /avatars](/docs/api-google-vids-v1/get-google-vids-avatars) lista tus avatares, incluidos los hechos en la app web de Google Vids. **¿Puedo hacer un video vertical 9:16 para TikTok o Reels?** Con useapi.net, sí. Define `aspectRatio: "portrait"` en [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) para 720×1280, o 1080×1920 en `1080p`, como en el [clip de la paloma](#a-pigeon-in-aeroloops). Una extensión también puede convertir un video horizontal en vertical, y cada extensión agrega de 3 a 10 segundos a un clip de hasta 24 segundos, hasta unos 34 segundos en total. Los videos de avatar parlante de [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar) son solo en horizontal. **¿Cuánto cuesta?** Con useapi.net, un video de Omni 1.2 Flash de 10 segundos cuesta unos US$0,20 en Google AI Ultra US$199,99, frente a unos US$0,70 en 720p en la [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) oficial, y un video de 15 segundos en 1080p unos US$0,30, frente a US$1,56 (a noviembre de 2026). Un video de avatar parlante gasta 1 de los videos de avatar con IA mensuales de la cuenta en lugar de segundos, y la Gemini API no tiene videos de avatar. Consulta [Cuánto costó](#what-it-cost). ### Conclusión Visita nuestro <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> servidor de Discord</a> o el <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> canal de Telegram</a> para cualquier pregunta de soporte. Consulta nuestro [repositorio en GitHub](https://github.com/useapi/google-vids-api) con ejemplos de código: el pipeline de influencer en [`influencer-avatars/`](https://github.com/useapi/google-vids-api/tree/main/influencer-avatars), y el avatar parlante a partir de una foto y la voz en [`talking-avatar/`](https://github.com/useapi/google-vids-api/tree/main/talking-avatar). Las mismas llamadas están disponibles como herramientas en el [servidor MCP de Google Vids](/docs/api-google-vids-v1/mcp) alojado, para Claude Code, Cursor y VS Code, incluidas `vids_create_avatar`, `vids_create_avatar_video` y `vids_create_speech` para el avatar parlante y la voz. #### También publicado en {: .no_toc #cross-posted } También publicado en [dev.to](https://dev.to/useapi/how-to-make-ai-influencer-videos-with-avatars-via-the-google-vids-api-3ide){:rel="nofollow"}, comentado en [Reddit](https://www.reddit.com/r/ThirdPartyAPI/comments/1x1cvap/how_to_make_ai_influencer_videos_with_avatars_via/){:rel="nofollow"}, compartido en [Bluesky](https://bsky.app/profile/useapi.net/post/3mxga3gxjjp2f){:rel="nofollow"} y en [YouTube](https://youtu.be/ofCtt7xRBCk) como el clip final de 30 segundos (todos en inglés). ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-vids-influencer-avatars-id === Document URL: https://useapi.net/docs/articles/google-vids-influencer-avatars-id --- layout: default title: "Cara Membuat Video Influencer AI dengan Avatar lewat Google Vids API" seo_title: "Video Influencer AI dan Avatar Bicara lewat Google Vids API" description: "Buat video influencer AI yang berbicara lewat Google Vids API useapi.net: avatar bersuara di klip Omni 1.2 Flash, avatar dari foto yang membacakan skrip 30 detik, dan speech." keywords: [API video influencer AI, AI influencer video API, API video avatar AI, AI avatar video API, API avatar bicara, talking avatar API, talking head video API, foto jadi avatar bicara, photo to talking avatar API, API text to speech, text to speech API, suara Gemini, Gemini voices, video juru bicara AI, AI spokesperson video, Google Vids API, avatar Google Vids, Google Vids avatars, Gemini Omni 1.2 Flash API, video UGC AI, AI UGC video, video peluncuran produk, perpanjang video AI, API edit video AI, tutorial bahasa Indonesia, curl] image: https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-cover-aeroloop-launch-confetti-1007.jpg parent: Articles nav_exclude: true lang: id translation_key: google-vids date: 2026-10-07 last_modified: 2026-11-06 nav_order: 899 repo: https://github.com/useapi/google-vids-api --- ## Cara Membuat Video Influencer AI dengan Avatar lewat Google Vids API {: .no_toc #how-to-make-ai-influencer-videos-with-avatars-via-the-google-vids-api } 15 menit baca • 7 Oktober 2026 (6 November 2026) useapi.net adalah API pihak ketiga. Kami tidak berafiliasi dengan Google dan tidak disahkan oleh Google. ## Daftar isi {: .no_toc .text-delta #table-of-contents } ### Pendahuluan [Google Vids API dari useapi.net](/docs/api-google-vids-v1) membuat video influencer AI yang berbicara dari avatar: simpan satu gambar dan salah satu dari 30 suara Gemini sekali saja dengan POST /avatars, lalu kirim id avatar itu ke video [Gemini Omni 1.2 Flash](https://workspaceupdates.googleblog.com/2026/11/gemini-omni-12-flash-now-in-vids-with-15second-generations-and-improved-quality.html) mana pun hingga 15 detik. Di sana avatar mengucapkan kalimat yang Anda tulis di prompt. Avatar juga bisa membacakan skrip Anda sendiri dalam video talking-head hingga 30 detik. API ini berjalan di akun [Google Vids](https://docs.google.com/videos) Anda, dengan [langganan Google AI](https://gemini.google/subscriptions/) berbayar (Google AI Pro atau Ultra). Panduan ini membuat dua influencer dan meluncurkan sepatu sneaker bersama mereka. Avatar Mia berasal dari potret yang dibuat dengan API, dan avatar Leo digambar Google dari deskripsi tertulis. Mereka memperkenalkan AeroLoop, sneaker rekaan, di panggung teater dalam satu klip 10 detik berisi kedua avatar dan gambar produk, lalu dua extend membawanya ke 30 detik. Satu edit memindahkan adegan ke atap gedung, dan dua klip lain menunjukkan hasil panggilan yang sama tanpa avatar. Avatar ketiga, Amber, berasal dari foto orang sungguhan, diubah gayanya dengan satu kalimat, lalu membacakan skrip 327 karakter dalam [video talking-head](#a-talking-avatar-from-a-photo) 24 detik. Terakhir, suara yang sama membacakan cerita 2.426 karakter sebagai [speech saja](#speech-on-its-own). Setiap request di bawah adalah request yang membuat media di halaman ini, dengan id yang diganti dan `async: true` yang ditambahkan oleh helper `run`. Klip-klip ini dibuat pada Oktober 2026 dengan Omni 1.1 Flash, yang diganti Vids dengan Omni 1.2 Flash pada 5 November 2026, dan request yang sama berjalan di 1.2. Omni 1.2 di Google Vids dan Google Flow secara berdampingan, dengan video 15 detik dan harga per video: [Cara Memakai Gemini Omni 1.2 Flash API](/docs/articles/gemini-omni-1-2-flash-api-id). <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-extend-30s-720p-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-extend-30s-720p-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> Klip jadi 30 detik di `720p`: satu generate 10 detik dan dua extend 10 detik ([langkah 6 sampai 8](#step-6-the-launch-two-avatars-and-the-product-in-one-clip)). ### Biayanya useapi.net adalah API, bukan layanan video tersendiri. Setiap panggilan berjalan di akun Google yang Anda hubungkan lewat [Setup Google Vids](/docs/start-here/setup-google-vids), dengan langganan Google AI berbayar, dan memakai detik video serta gambar yang termasuk dalam langganan itu di Google Vids setiap bulan. Google AI Ultra $199,99 berisi 10.000 detik video dan 1.000 gambar per bulan, dan useapi.net tidak menambah biaya per video. Video avatar bicara dan speech tidak memakai detik video: keduanya punya penghitung bulanan sendiri, video avatar AI dan pemakaian Gemini, yang ditampilkan [GET /accounts/`email`](/docs/api-google-vids-v1/get-google-vids-accounts-email) sebagai `avatarVideo` dan `speech` di samping `video` dan `image`. Lihat [isi setiap paket](/docs/api-google-vids-v1#plans-and-monthly-allowances) untuk paket lainnya. Yang dipakai setiap hasil yang disimpan, diambil dari perubahan `result.quota`, dan berapa lama setiap job berjalan (`result.elapsedMs`): | Langkah | Endpoint | Dipakai | Waktu | |---|---|--:|--:| | [Potret Mia](#step-1-mias-portrait) | [POST /images](/docs/api-google-vids-v1/post-google-vids-images) | 1 gambar | 9 s | | [Foto produk AeroLoop](#step-2-the-aeroloop-product-shot) | [POST /images](/docs/api-google-vids-v1/post-google-vids-images) | 1 gambar | 9 s | | [Avatar Mia, dari potretnya](#step-4-mias-avatar-from-her-portrait) | [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) | tidak ada | sekitar 2 s | | [Avatar Leo, dari deskripsi](#step-5-leos-avatar-from-a-description) | [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) | 1 gambar | sekitar 20 s | | [Klip peluncuran 10 detik](#step-6-the-launch-two-avatars-and-the-product-in-one-clip) | [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) | 10 s | 38 s | | [Extend ke 20 detik](#step-7-extend-to-20-seconds) | [POST /videos/extend](/docs/api-google-vids-v1/post-google-vids-videos-extend) | 10 s | 70 s | | [Extend ke 30 detik](#step-8-extend-to-30-seconds) | [POST /videos/extend](/docs/api-google-vids-v1/post-google-vids-videos-extend) | 10 s | 85 s | | [Upscale 20 detik ke 1080p](#step-9-upscale-to-1080p) | [POST /videos/upscale](/docs/api-google-vids-v1/post-google-vids-videos-upscale) | 20 s | 62 s | | [Edit atap gedung](#move-the-launch-to-a-rooftop) | [POST /videos/edit](/docs/api-google-vids-v1/post-google-vids-videos-edit) | 10 s | 64 s | | [Edit klip 30 detik](#move-the-launch-to-a-rooftop) | [POST /videos/edit](/docs/api-google-vids-v1/post-google-vids-videos-edit) | 10 s | 87 s | | [Klip hero produk](#a-product-hero-clip-from-a-start-image) | [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) | 10 s | 62 s | | [Burung merpati](#a-pigeon-in-aeroloops) | [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) | 5 s | 54 s | | [Avatar Amber, dari foto dengan `refine`](#ambers-avatar-restyled-in-one-sentence) | [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) | tidak ada (dibuat di paket tanpa gambar, 2 gambar di paket yang punya gambar) | sekitar 30 sampai 45 s | | [Video bicara Amber 24 detik](#the-talking-video) | [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar) | 1 video avatar AI, 1 pemakaian Gemini | sekitar 2,5 menit | | [Cerita 2.426 karakter](#speech-on-its-own) | [POST /speech](/docs/api-google-vids-v1/post-google-vids-speech) | 1 pemakaian Gemini | 20 s | | Total | | 85 s video, 3 gambar, 1 video avatar AI, 2 pemakaian Gemini | | Extend hanya memakai detik yang ditambahkannya, bukan panjang klip. Upscale memakai lagi seluruh panjang klip, dan edit memakai paling banyak detik yang diedit (dengan Omni 1.2, edit 15 detik memakai 10 dalam uji kami). `720p` dan `1080p` berbiaya sama saat generate. Klip yang Anda generate ulang memakai detiknya lagi. Setiap gambar yang dibuat Google untuk avatar memakai 1 gambar, jadi foto yang dibingkai ulang ditambah `refine` memakai 2. Di paket tanpa gambar, seperti akun Google gratis, gambar avatar tidak memakai apa-apa: Amber dibuat di akun seperti itu. Video avatar bicara memakai 1 video avatar AI, ditambah 1 pemakaian Gemini untuk speech-nya, bahkan ketika Google menolak video yang sudah jadi. Perbandingan biaya video dengan API resmi ada di [tabel harga Google Vids](/docs/api-google-vids-v1#pricing). ### Sebelum mulai Anda butuh [API token](/docs/start-here/setup-useapi) useapi.net dan akun Google dengan langganan Google AI berbayar, yang dihubungkan lewat [Setup Google Vids](/docs/start-here/setup-google-vids). Akun Google gratis tidak mendapat detik video maupun gambar Vids: akun itu tetap bisa ditambahkan, dan dalam uji kami (November 2026) akun gratis bisa membuat avatar, video avatar bicara dan speech. Setiap panggilan juga ada di [koleksi Postman](https://www.postman.com/useapinet/useapi-net/collection/29112081-9ef3d017-d44c-4f43-a4cb-7351b9b265df). Tanpa kode: template n8n [Talking Avatar App]({% include n8n-url.html t="vids-avatar" %}) membuat video avatar bicara dari sebuah formulir. Seluruh pipeline juga ada di GitHub sebagai satu skrip, dalam Node.js dan Python: [`influencer-avatars/`](https://github.com/useapi/google-vids-api/tree/main/influencer-avatars) di [useapi/google-vids-api](https://github.com/useapi/google-vids-api), dan bagian avatar bicara serta speech sebagai [`talking-avatar/`](https://github.com/useapi/google-vids-api/tree/main/talking-avatar). Langkah-langkahnya memakai `curl`, `jq`, serta variabel dan helper berikut: <details markdown="block"> <summary>Buka variabel dan helper</summary> ```bash export USEAPI_TOKEN="user:12345-..." export EMAIL="user@example.com" API=https://api.useapi.net/v1/google-vids AUTH="Authorization: Bearer $USEAPI_TOKEN" enc() { jq -rn --arg v "$1" '$v|@uri'; } post() { curl -sS -X POST "$API/$1" -H "$AUTH" -H "Content-Type: application/json" -d "$2"; } get() { curl -sS "$API/$1" -H "$AUTH"; } download() { curl -sSf "$API/media/$(enc "$1")" -H "$AUTH" -o "$2"; } # jalankan job video secara async: kirim, polling GET /jobs/{jobid} setiap 10 detik, simpan record job terakhir ke $1 run() { local job id job=$(post "$2" "$(jq '. + {async: true}' <<< "$3")") id=$(jq -r .jobid <<< "$job") while [ "$(jq -r .status <<< "$job")" = processing ]; do sleep 10 job=$(get "jobs/$(enc "$id")") done echo "$job" > "$1" jq '{status, error, duration: .result.duration, resolution: .result.resolution, videoLeft: .result.quota.video.left}' "$1" } ``` </details> Setiap generate berjalan sebagai job. Tanpa `async`, POST menunggu hingga sekitar 100 detik dan mengembalikan record job yang sudah selesai, atau `202` jika job masih berjalan. Klip baru 10 detik butuh 38 sampai 62 detik di sini, extend, edit dan upscale butuh 62 sampai 87 detik, dan video avatar bicara sekitar dua setengah menit. Sebagian lebih lama dari batas tunggu sync, jadi `run` mengirim job video dengan `async: true` dan melakukan polling ke [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid). Jika `run` mencetak `status` selain `completed`, berhenti di situ dan baca `error`-nya: baris-baris berikutnya mengharapkan klip yang sudah jadi. Untuk dipanggil balik alih-alih polling, tambahkan `replyUrl: "https://example.com/hooks/vids"` (dan, jika perlu, `replyRef: "launch-push-in"`) ke body mana pun di bawah. API lalu mengirim satu `POST` berisi record job terakhir, dalam JSON, ke URL itu ketika job selesai atau gagal. Id berisi `:` dan `@`, jadi `enc` meng-encode-nya sebagai URL setiap kali id masuk ke path URL. Semua input untuk satu video harus berasal dari akun Google yang sama. Gambar dan upload menetapkan `email`, avatar Mia mewarisi akun potretnya, dan job video berjalan di akun yang menyimpan input-nya. Klip burung merpati tidak punya input, jadi tambahkan `email` padanya jika Anda menghubungkan lebih dari satu akun. ### Cara membuatnya #### 1. Potret Mia [POST /images](/docs/api-google-vids-v1/post-google-vids-images) membuat satu JPEG per panggilan, di sini dalam format potret (`9:16`, 768×1376) dengan gaya `photography`. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-images">POST /images</a></summary> ```bash post images "$(jq -n --arg email "$EMAIL" '{email: $email, aspectRatio: "9:16", style: "photography", prompt: "Full-length studio portrait of a confident 24-year-old female fashion influencer, platinum bob, oversized cream hoodie, wide-leg cargo pants, gold hoops, plain light-grey backdrop, facing camera"}')" > mia-portrait.json MIA_IMAGE=$(jq -r .result.mediaId mia-portrait.json) download "$MIA_IMAGE" mia-portrait.jpg ``` </details> <img src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-mia-portrait-1007.jpg" alt="Mia, potret seluruh badan seorang influencer fashion dengan hoodie krem dan celana kargo, dibuat dengan POST /images" style="width: 100%; max-width: 300px; border-radius: 8px;"> Gambar hasil generate hanya tersedia beberapa jam. Langsung buat avatar darinya, dan lihat [klip hero produk](#a-product-hero-clip-from-a-start-image) untuk memakai gambar di kemudian waktu. #### 2. Foto produk AeroLoop Panggilan yang sama dalam format lanskap (`16:9`, 1376×768) menghasilkan referensi produk yang dipakai klip-klip berikutnya. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-images">POST /images</a></summary> ```bash post images "$(jq -n --arg email "$EMAIL" '{email: $email, aspectRatio: "16:9", style: "photography", prompt: "The AeroLoop sneaker: chunky white-and-electric-blue running shoe with a translucent air sole, on a concrete pedestal, dramatic side light, dark background"}')" > aeroloop.json SHOE_IMAGE=$(jq -r .result.mediaId aeroloop.json) download "$SHOE_IMAGE" aeroloop.jpg ``` </details> <img src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-aeroloop-product-1007.jpg" alt="Sneaker AeroLoop, sepatu lari putih dan biru elektrik dengan sol tembus pandang di atas alas beton, dibuat dengan POST /images" style="width: 100%; max-width: 560px; border-radius: 8px;"> #### 3. Pilih suara [GET /voices](/docs/api-google-vids-v1/get-google-vids-voices) menampilkan 30 suara beserta contoh bahasa Inggris dari Google untuk masing-masing. Endpoint ini publik dan tidak butuh token. Mia berbicara dengan `Aoede` (di Vids disebut Tova, gaya "Breezy") dan Leo dengan `Puck` (Neo, "Upbeat"). `POST /avatars` menerima kedua nama itu. ```bash curl -sS "$API/voices" | jq -r '.voices[] | "\(.name)\t\(.voice)\t\(.style)\t\(.preview)"' ``` #### 4. Avatar Mia dari potretnya [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) dengan `image` berisi `mediaId` potret menyimpan Mia sebagai avatar di akun yang sama dalam sekitar 2 detik. Tidak ada biaya selain gambarnya. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-avatars">POST /avatars</a> dan respons</summary> ```bash post avatars "$(jq -n --arg img "$MIA_IMAGE" '{name: "Mia", voice: "Aoede", image: $img}')" > mia-avatar.json MIA_AVATAR_ID=$(jq -r .avatarId mia-avatar.json) ``` ```json { "avatarId": "user:12345-user@example.com-avatar:eyJnIjoiaDM5…", "name": "Mia", "voice": "Tova", "voiceId": "Aoede", "voiceStyle": "Breezy", "voicePreview": "https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Aoede.wav", "email": "user@example.com", "source": "image" } ``` </details> Avatar juga bisa berasal dari foto milik seseorang: upload dengan [POST /assets](/docs/api-google-vids-v1/post-google-vids-assets) dan kirim `assetId`-nya sebagai `image`. Google membingkai ulang foto itu menjadi gambar avatar 16:9 dan menolak foto tokoh terkenal serta anak di bawah umur. Di sini kami memakai gambar yang dibuat dengan API, dan deskripsi di langkah berikutnya. Amber, di bagian [avatar bicara dari foto](#a-talking-avatar-from-a-photo), berasal dari foto. #### 5. Avatar Leo dari deskripsi Dengan `appearance` sebagai ganti `image`, Google menggambar orangnya. `outfit` dan `shot` opsional, begitu juga `expression` dan `details`. Menggambar foto ini memakai 1 gambar dari jatah bulan itu, dan respons memuatnya sebagai `previewMediaId`. Dalam uji kami, avatar dari deskripsi selalu keluar 1280×720 (16:9), apa pun `shot` yang kami pilih. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-avatars">POST /avatars</a> dan respons</summary> ```bash post avatars "$(jq -n --arg email "$EMAIL" '{email: $email, name: "Leo", voice: "Puck", shot: "upper-body", appearance: "a 26-year-old white European male streetwear influencer with short textured hair with a fade and a confident half-smile", outfit: "black puffer vest over a white tee, silver chain"}')" > leo-avatar.json LEO_AVATAR_ID=$(jq -r .avatarId leo-avatar.json) download "$(jq -r .previewMediaId leo-avatar.json)" leo-avatar.jpg ``` ```json { "avatarId": "user:12345-user@example.com-avatar:eyJnIjoiaDM5…", "name": "Leo", "voice": "Neo", "voiceId": "Puck", "voiceStyle": "Upbeat", "voicePreview": "https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Puck.wav", "email": "user@example.com", "source": "generated", "previewMediaId": "user:12345-user@example.com-image:eyJ1IjoiaHR0…", "look": { "appearance": "a 26-year-old white European male streetwear influencer with short textured hair with a fade and a confident half-smile", "outfit": "black puffer vest over a white tee, silver chain", "shot": "upper-body" } } ``` </details> <img src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-leo-avatar-from-description-1007.jpg" alt="Leo, avatar yang digambar Google dari deskripsi: pria muda dengan rompi puffer hitam di atas kaus putih dan kalung perak, 1280x720" style="width: 100%; max-width: 560px; border-radius: 8px;"> Kedua avatar tetap tersimpan di dokumen Vids akun itu sampai Anda menghapusnya dengan [DELETE /avatars/`avatarId`](/docs/api-google-vids-v1/delete-google-vids-avatars-avatarId). [GET /avatars](/docs/api-google-vids-v1/get-google-vids-avatars) menampilkan semuanya, beserta id-nya, kapan pun Anda membutuhkannya lagi: ```bash get "avatars?email=$(enc "$EMAIL")" | jq -r '.avatars[] | "\(.name)\t\(.voiceId)\t\(.avatarId)"' ``` #### 6. Peluncuran: dua avatar dan produk dalam satu klip [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) menerima hingga 3 referensi secara total, avatar (`avatar_1`..`avatar_3`) dan gambar (`referenceImage_1`..`referenceImage_3`) bersama-sama. Di prompt, `@avatar_1`, `@avatar_2` dan `@referenceImage_1` mewakili mereka, dan setiap avatar mengucapkan kalimat dalam tanda kutipnya dengan suaranya sendiri. `mediaId` gambar produk langsung dimasukkan: API mengambil gambar itu dan meng-upload-nya di akun tersebut. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos">POST /videos</a> dan record job</summary> ```bash PROMPT=$(cat <<'EOF' @avatar_1, holding @referenceImage_1 in both hands at chest height, and @avatar_2 stand side by side on a well-lit stage in a small, intimate theater at a sneaker launch, shown full length from head to toe in a wide, steady shot. Behind them a large LED backdrop glows with soft white-and-blue light that moves in slow, gentle waves, with the words "WEAR AEROLOOP" in large, clean, bold white letters across the middle of the screen. The two of them stand on the lower part of the stage, so the words "WEAR AEROLOOP" stay fully readable above their heads. Bright, even stage lighting on both of them. The audience sits in the dark in front of the stage, only the tops of a few heads barely visible at the bottom of the frame. @avatar_1 keeps holding @referenceImage_1 the whole time and says: "Say hi to the AeroLoop!" @avatar_2 turns to her, smiles and says: "Lighter than anything we've ever worn." Simple, uncluttered composition, the two of them clearly the focus. EOF ) run launch-10s.json videos "$(jq -n --arg p "$PROMPT" --arg mia "$MIA_AVATAR_ID" --arg leo "$LEO_AVATAR_ID" --arg shoe "$SHOE_IMAGE" \ '{prompt: $p, avatar_1: $mia, avatar_2: $leo, referenceImage_1: $shoe, duration: 10, resolution: "720p", aspectRatio: "landscape"}')" LAUNCH_10S=$(jq -r .result.mediaId launch-10s.json) download "$LAUNCH_10S" launch-10s.mp4 ``` Record job, dengan id dan prompt yang dipersingkat. Job ini dibuat dengan panggilan sync, jadi `request`-nya tidak berisi `async`: ```json { "jobid": "j1007163302558496917v-u12345-email:user@example.com-bot:google-vids", "type": "video", "mode": "ingredients", "email": "user@example.com", "status": "completed", "created": "2026-10-08T00:29:18.374Z", "request": { "prompt": "@avatar_1, holding @referenceImage_1 in both hands at chest height, and @avatar_2 stand side by side …", "avatar_1": "user:12345-user@example.com-avatar:eyJnIjoiaDM5…", "avatar_2": "user:12345-user@example.com-avatar:eyJnIjoiaDM5…", "referenceImage_1": "user:12345-user@example.com-image:eyJ1IjoiaHR0…", "duration": 10, "resolution": "720p", "aspectRatio": "landscape" }, "updated": "2026-10-08T00:29:56.162Z", "completed": "2026-10-08T00:29:56.162Z", "result": { "mediaId": "user:12345-user@example.com-video:eyJ1IjoiaHR0…", "width": 1280, "height": 720, "duration": 10, "resolution": "720p", "aspectRatio": "landscape", "model": "/flix/generate_videos_omni_r2v_psq/v1", "quota": { "video": { "limit": 10000, "left": 9164, "resetAt": "2026-11-01T07:00:00.000Z" } }, "elapsedMs": 37788 } } ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-10s-720p-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-10s-720p-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> 10 detik, `720p`, dibuat dalam 38 detik. Klip yang sama dengan tanda ✦ Gemini yang terlihat dihapus oleh [watermark remover](https://github.com/useapi/google-vids-api/tree/main/watermark-remover) kami, dengan satu perintah: `python3 vids_watermark_remover.py launch-10s.mp4`. <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-10s-720p-no-watermark-1008-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-10s-720p-no-watermark-1008.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> Remover ini bekerja pada klip apa adanya dari generate dan pada hasil upscale-nya, di `720p` maupun `1080p`. Remover tidak bekerja pada klip yang sudah di-extend atau diedit: Google memasukkan kembali klip bertanda ke model, yang lalu melukis ulang bintang itu ke dalam gambar. Watermark SynthID yang tidak terlihat tidak disentuh. #### 7. Extend ke 20 detik [POST /videos/extend](/docs/api-google-vids-v1/post-google-vids-videos-extend) menambah 3 sampai 10 detik dan mengembalikan klip utuh dengan `mediaId` baru. Extend hanya menerima klip dan prompt, bukan avatar, jadi prompt menggambarkan aksi baru dan menyebut orang dari pakaiannya ("the man in the black puffer vest"). Seorang penggemar berhoodie merah menyerbu panggung. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos-extend">POST /videos/extend</a></summary> ```bash PROMPT=$(cat <<'EOF' A young man in a red hoodie climbs onto the stage from the front right edge and plants himself to the right of the man in the black puffer vest, an arm's length away, so all three stand apart in a row with nobody overlapping. Visibly overexcited, he waves a thick stack of banknotes in his right hand above his head and screams: "Take my money!" The man in the black puffer vest laughs, raises both palms toward him and says: "Whoa, whoa, buddy, be patient!" The blonde woman in the cream hoodie laughs, holding the sneaker. Only these three people are on stage. Same stage, same LED screen with WEAR AEROLOOP, same wide steady shot. EOF ) run launch-20s.json videos/extend "$(jq -n --arg id "$LAUNCH_10S" --arg p "$PROMPT" '{mediaId: $id, prompt: $p, duration: 10}')" LAUNCH_20S=$(jq -r .result.mediaId launch-20s.json) download "$LAUNCH_20S" launch-20s.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-extend-20s-720p-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-extend-20s-720p-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> 20 detik, `720p`, dibuat dalam 70 detik. Klip ini memakai 10 detik dari jatah bulan itu, yaitu detik yang ditambahkannya. #### 8. Extend ke 30 detik Extend kedua melanjutkan klip 20 detik. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos-extend">POST /videos/extend</a></summary> ```bash PROMPT=$(cat <<'EOF' The blonde woman in the cream hoodie turns to the camera with a big smile and says: "AeroLoop drops Friday. Link in bio!" Right after that, the young man in the red hoodie throws ALL of his banknotes out over the audience in one big toss, keeping none, and the bills flutter down over their heads. From then on his hands are completely empty: he holds no money at all. Then all three cheer together, the man in the black puffer vest and the young man in the red hoodie throwing their empty fists in the air, as blue and white confetti rains down over the stage. Only these three people are on stage. Same stage, same LED screen with WEAR AEROLOOP, same wide steady shot. EOF ) run launch-30s.json videos/extend "$(jq -n --arg id "$LAUNCH_20S" --arg p "$PROMPT" '{mediaId: $id, prompt: $p, duration: 10}')" LAUNCH_30S=$(jq -r .result.mediaId launch-30s.json) download "$LAUNCH_30S" launch-30s.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-extend-30s-720p-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-extend-30s-720p-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> Hasilnya klip jadi: 30 detik, `720p`, dibuat dalam 85 detik, dan sekali lagi memakai 10 detik dari jatah bulan itu. Dengan Omni 1.1 Anda bisa terus memperpanjang hingga sekitar 41 detik. Omni 1.2 memperpanjang klip hingga 24 detik, jadi klip 30 detik ini sudah sepanjang maksimal, dan klip terpanjang sekitar 34 detik (24 + 10). #### 9. Upscale ke 1080p [POST /videos/upscale](/docs/api-google-vids-v1/post-google-vids-videos-upscale) mengubah klip `720p` menjadi `1080p` dan mempertahankan panjangnya. Upscale bekerja untuk klip hingga 20 detik, jadi kami meng-upscale klip 20 detik dari [langkah 7](#step-7-extend-to-20-seconds), bukan yang 30 detik. Upscale ini memakai lagi 20 detik klip itu dan butuh 62 detik. [Gemini API](https://aistudio.google.com/docs/omni) milik Google tidak punya langkah seperti ini: API itu hanya membuat `1080p` dan 4K sebagai hasil generate atau edit, dan tidak bisa meng-upscale klip yang sudah Anda punya (per November 2026). <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos-upscale">POST /videos/upscale</a></summary> ```bash run launch-20s-1080p.json videos/upscale "$(jq -n --arg id "$LAUNCH_20S" '{mediaId: $id}')" download "$(jq -r .result.mediaId launch-20s-1080p.json)" launch-20s-1080p.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-20s-1080p-upscaled-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-20s-1080p-upscaled-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> Klip 20 detik, di-upscale ke 1920×1080. Mengapa bukan klip 30 detik: Google mengembalikannya dalam 1920×1080, tetapi dengan urutan frame yang kacau, tiga kali dari tiga percobaan. Akhir dengan konfeti berkedip muncul sebelum penggemar itu datang. Klip 20 detik kembali dengan urutan yang benar, dan editor Vids sendiri berhenti di 20 detik, jadi API menolak upscale klip lebih dari 20 detik dengan `400`, sebelum ada biaya apa pun. Jadi, untuk klip `1080p`: - Buat, extend dan edit di `720p`. - Upscale klip setelah jadi, selama panjangnya 20 detik atau kurang. - Untuk klip yang lebih panjang (21 sampai 34 detik), tetap di `720p` dan pasang `resolution: "1080p"` hanya di extend terakhir. Extend di `1080p` sepanjang jalan membuat detik-detik awal terlalu tajam di setiap langkah ([lihat perbandingannya](/blog/261106v#720p-or-1080p-what-a-1080p-extend-does)). - Untuk satu klip yang tidak akan Anda extend atau edit, langsung generate di `1080p`: biayanya sama dengan detik `720p`, sedangkan upscale memakai detik itu lagi. ### Contoh Hasil lain dari akun dan input yang sama: satu edit, satu klip produk dari gambar awal, dan satu klip hanya dari teks. #### Pindahkan peluncuran ke atap gedung [POST /videos/edit](/docs/api-google-vids-v1/post-google-vids-videos-edit) mengubah klip hasil generate lewat prompt dan mengembalikan klip baru. Sumbernya dimasukkan ke `video`. Edit klip peluncuran 10 detik ini memakai 10 detik dan butuh 64 detik. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos-edit">POST /videos/edit</a></summary> ```bash run launch-rooftop.json videos/edit "$(jq -n --arg v "$LAUNCH_10S" \ '{video: $v, prompt: "Move the whole scene to a rooftop at sunset, with the city skyline behind them. Same two people, same action, same words."}')" download "$(jq -r .result.mediaId launch-rooftop.json)" launch-rooftop.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-edit-rooftop-10s-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-edit-rooftop-10s-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> Dengan Omni 1.1, yang membuat klip-klip ini, edit bekerja untuk paling banyak 10 detik. Edit yang sama pada klip 30 detik, dengan "Same three people", kembali sepanjang 10 detik: 10 detik pertama, dipindahkan ke atap gedung. Edit itu memakai 10 detik dari jatah bulan itu. Omni 1.2 mengedit hingga 15 detik. Untuk klip teredit yang lebih panjang, edit klip hingga 15 detik lalu extend hasilnya, karena extend menerima klip yang sudah diedit. <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-30s-edit-returns-10s-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-30s-edit-returns-10s-1007.mp4" style="width: 100%; max-width: 480px; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> Edit klip 30 detik dengan Omni 1.1: yang kembali 10 detik. #### Klip hero produk dari gambar awal Dengan `startImage`, klip dibuka dengan gambar itu. Tautan gambar hasil generate kedaluwarsa dalam beberapa jam, jadi kami meng-upload `aeroloop.jpg` yang sudah disimpan dengan [POST /assets](/docs/api-google-vids-v1/post-google-vids-assets) dan mengirim `assetId`-nya. Satu klip ini tidak di-extend, jadi langsung dibuat di `1080p`. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-assets">POST /assets</a> dan <a href="/docs/api-google-vids-v1/post-google-vids-videos">POST /videos</a></summary> ```bash SHOE_ASSET=$(curl -sS -X POST "$API/assets?email=$(enc "$EMAIL")" -H "$AUTH" -H "Content-Type: image/jpeg" \ --data-binary @aeroloop.jpg | jq -r .assetId) run hero.json videos "$(jq -n --arg img "$SHOE_ASSET" '{startImage: $img, duration: 10, resolution: "1080p", aspectRatio: "landscape", prompt: "Slow 360° orbit around the sneaker, blue light rippling through the translucent sole, dust sparkling in the air, cinematic."}')" download "$(jq -r .result.mediaId hero.json)" hero.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-aeroloop-hero-10s-1080p-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-aeroloop-hero-10s-1080p-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> 10 detik, `1080p`. #### Burung merpati bersepatu AeroLoop Klip hanya dari teks, dalam format potret di `1080p` (1080×1920). Klip 5 detik ini dibuat dalam 54 detik dan memakai 5 detik dari jatah bulan itu. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos">POST /videos</a></summary> ```bash run pigeon.json videos "$(jq -n '{duration: 5, resolution: "1080p", aspectRatio: "portrait", prompt: "A pigeon in tiny white-and-electric-blue AeroLoop sneakers struts down a city sidewalk like a runway model, head bobbing to the beat. Pedestrians stop and film it with their phones. It pauses, does a slow-motion hair flip with its head feathers, and struts on. Funny, sunny, shot on a phone at pigeon height."}')" download "$(jq -r .result.mediaId pigeon.json)" pigeon.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-pigeon-5s-1080p-portrait-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-pigeon-5s-1080p-portrait-1007.mp4" style="width: 100%; max-width: 360px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> Burung merpati dalam `1080p` potret (1080×1920), dengan ✦ dihapus dengan cara yang sama: `python3 vids_watermark_remover.py pigeon-5s.mp4`. Skrip ini membaca ukuran frame, menghitung posisi dan ukuran bintang (ukurannya mengikuti sisi pendek, jadi di sini 1,5 kali bintang `720p`), membalik blending di semua 120 frame, meng-encode ulang video dengan CRF 18 dan menyalin audio tanpa perubahan. Klip 5 detik ini butuh sekitar 10 detik di PC 14 core, sama seperti klip peluncuran `720p` 10 detik di atas. Skrip ini butuh Python 3.8+, `numpy` dan `ffmpeg`. Lihat [watermark remover](https://github.com/useapi/google-vids-api/tree/main/watermark-remover) di GitHub. <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-pigeon-5s-1080p-portrait-no-watermark-1008-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-pigeon-5s-1080p-portrait-no-watermark-1008.mp4" style="width: 100%; max-width: 360px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> ### Avatar bicara dari foto [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar) membuat avatar membacakan skrip Anda kata demi kata, dengan suaranya sendiri: video talking-head 1280×720 dengan suara dan lip-sync, sepanjang speech-nya, hingga 30 detik. Di sini avatar berasal dari foto orang sungguhan, yang diubah gayanya dengan satu kalimat. Request ini pertama kali muncul di [postingan rilis 4 November](/blog/261104) (bahasa Inggris). #### Upload foto Kami mulai dari foto orang sungguhan yang tidak terkenal: Google menolak foto tokoh terkenal dan anak di bawah umur. [POST /assets](/docs/api-google-vids-v1/post-google-vids-assets) meng-upload foto itu ke akun yang akan membuat avatar, karena file upload hanya berlaku di akunnya sendiri. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-assets">POST /assets</a> dan respons</summary> ```bash curl -sS -X POST "$API/assets?email=$(enc "$EMAIL")" -H "$AUTH" -H "Content-Type: image/jpeg" \ --data-binary @photo.jpg > amber-photo.json AMBER_PHOTO=$(jq -r .assetId amber-photo.json) ``` ```json { "assetId": "user:12345-user@example.com-asset:AYGXpjA1zXgqhhQOy…", "email": "user@example.com", "type": "image/jpeg", "bytes": 2054748 } ``` </details> <img src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/261104-google-vids-amber-original-photo.jpg" alt="Foto asli: perempuan berambut merah panjang dengan gaun putih, berdiri di depan tirai krem" style="width: 100%; max-width: 300px; border-radius: 8px;"> #### Avatar Amber, diubah gayanya dengan satu kalimat [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) dengan `assetId` upload sebagai `image` dan sebuah `refine`. Google lebih dulu membingkai ulang foto menjadi gambar avatar 16:9 berisi satu orang yang menghadap kamera, dengan wajah yang sama, lalu mengubah adegan sesuai permintaan `refine`. Kami menamainya Amber dan memberinya suara `Vira` (`Pulcherrima` versi Google, gaya "Forward"). Foto yang dibingkai ulang dan perubahannya adalah 2 gambar, jadi di paket yang punya gambar ini memakai 2 gambar, dan di paket tanpa gambar tidak memakai apa-apa. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-avatars">POST /avatars</a> dan respons</summary> ```bash REFINE='Sitting relaxed in a simple wooden chair on a hilltop, facing the camera. She holds a glass of red wine in her left hand. Wind is blowing her hair. Behind her a still, open field of tall golden grass under a spectacular sunset sky in orange, pink and violet, warm soft light, no water, no movement in the background.' post avatars "$(jq -n --arg img "$AMBER_PHOTO" --arg refine "$REFINE" '{name: "Amber", voice: "Vira", image: $img, refine: $refine}')" > amber-avatar.json AMBER_AVATAR_ID=$(jq -r .avatarId amber-avatar.json) download "$(jq -r .previewMediaId amber-avatar.json)" amber-avatar.jpg ``` ```json { "avatarId": "user:12345-user@example.com-avatar:eyJnIjoiaDcyMzdmZjVi…", "name": "Amber", "voice": "Vira", "voiceId": "Pulcherrima", "voiceStyle": "Forward", "email": "user@example.com", "source": "photo", "previewMediaId": "user:12345-user@example.com-image:eyJ1IjoiaHR0cHM6Ly9s…", "refine": "Sitting relaxed in a simple wooden chair on a hilltop, facing the camera. …" } ``` </details> <img src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/261104-google-vids-amber-avatar.jpg" alt="Amber, avatar dari foto dengan refine: duduk di kursi kayu di puncak bukit saat matahari terbenam sambil memegang segelas anggur merah, 1280x720" style="width: 100%; max-width: 560px; border-radius: 8px;"> Dua pilihan dalam `refine` penting untuk videonya. Avatar menghadap kamera, karena video melakukan lip-sync pada wajah. Latar belakangnya diam, supaya hanya dia yang bergerak: karena itu kami meminta padang rumput yang tenang, bukan ombak di pantai. #### Skrip Skrip maksimal 400 karakter, dan saat diucapkan harus muat dalam 30 detik. Tag audio dalam kurung siku diperankan, bukan dibacakan: di sini `[awe]`, `[thoughtful]` dan `[whisper]`. Dengan suara Vira, 327 karakter ini berdurasi 23,8 detik. Suara yang lebih lambat atau `[slow pace]` membuat teks yang sama lebih panjang, dan skrip yang melewati 30 detik gagal dengan `400` sebelum video dimulai. Kegagalan itu tidak memakai video avatar AI, tetapi pemakaian Gemini untuk speech-nya tetap terpakai. Untuk mendengar skrip dengan suara avatar lebih dulu, bacakan dengan [POST /speech](#speech-on-its-own). > Hi there. [awe] Can you believe this view? The sun is sinking behind the hills, the sky turned pink and gold, and the tall grass glows like it's on fire. [thoughtful] I come up here at the end of every busy day, just to slow down. No emails, no rush, only the quiet field and this glass of wine. [whisper] Stay a little longer. #### Video bicara [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar) menerima avatar dan skrip, dan berjalan di akun yang menyimpan avatar itu. Google butuh sekitar dua setengah menit, lebih lama dari batas tunggu sync, jadi `run` mengirimnya dengan `async: true`. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos-avatar">POST /videos/avatar</a> dan record job</summary> ```bash SCRIPT=$(cat <<'EOF' Hi there. [awe] Can you believe this view? The sun is sinking behind the hills, the sky turned pink and gold, and the tall grass glows like it's on fire. [thoughtful] I come up here at the end of every busy day, just to slow down. No emails, no rush, only the quiet field and this glass of wine. [whisper] Stay a little longer. EOF ) run amber-talking.json videos/avatar "$(jq -n --arg a "$AMBER_AVATAR_ID" --arg s "$SCRIPT" '{avatar: $a, script: $s}')" download "$(jq -r .result.mediaId amber-talking.json)" amber-talking.mp4 ``` Record job, dipersingkat: ```json { "jobid": "j1105035516096819105a-u12345-email:user@example.com-bot:google-vids", "type": "avatarVideo", "email": "user@example.com", "status": "completed", "result": { "mediaId": "user:12345-user@example.com-video:eyJ1IjoiaHR0cHM6Ly9j…", "width": 1280, "height": 720, "duration": 24, "resolution": "720p", "aspectRatio": "landscape", "speechDuration": 23.84, "quota": { "avatarVideo": { "limit": 10, "left": 6, "resetAt": "2026-12-01T08:00:00.000Z" } } } } ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/261104-google-vids-amber-talking-avatar-24s-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/261104-google-vids-amber-talking-avatar-24s.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> Juga di YouTube sebagai Short: [Talking AI avatar from one photo](https://youtube.com/shorts/P44L9VZ8bME). 24 detik, 1280×720 dengan suara, persis sepanjang speech-nya (`speechDuration` 23,84). Video ini memakai 1 video avatar AI dan 1 pemakaian Gemini, tanpa detik video. Google juga memeriksa videonya saat membuatnya, dan pemeriksaan itu lebih ketat daripada untuk gambar avatar. Versi sebelumnya dari avatar ini, yang dibuat dari foto lain seorang biasa di pantai, lolos sebagai avatar, tetapi videonya ditolak dengan `422` karena dianggap mirip selebritas, dan percobaan itu tetap memakai satu video avatar AI. Mengubah gaya avatar atau memulai dari foto lain membantu. Skrip yang ditolak Google sebelum video dimulai tidak memakai apa-apa. Video avatar bicara hanya lanskap: Google tidak menyediakan opsi potret untuknya. `mediaId` hasilnya bisa diunduh, di-extend, di-upscale dan diedit seperti klip lain. Untuk adegan saat avatar berakting dan bergerak, kirim `avatarId`-nya sebagai `avatar_1` ke [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos), seperti di [langkah 6](#step-6-the-launch-two-avatars-and-the-product-in-one-clip). ### Speech saja [POST /speech](/docs/api-google-vids-v1/post-google-vids-speech) membacakan skrip hingga 2.500 karakter dengan salah satu dari 30 suara di [GET /voices](/docs/api-google-vids-v1/get-google-vids-voices), dengan tag audio yang sama. Pakai untuk mendengar cara sebuah suara membacakan skrip sebelum Anda memakai video avatar AI, atau untuk voiceover saja. Kami memberinya cerita pendek orisinal, "My smart fridge unionized", 2.426 karakter dengan suara Vira. Google menjawab dalam 20 detik dengan speech 2 menit 22 detik, seluruh cerita, dan memakai 1 pemakaian Gemini. API mengembalikan WAV (24 kHz, mono). Pemutar di bawah berisi audio yang sama dalam MP3. <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/261104-google-vids-speech-smart-fridge-2426-chars.mp3" type="audio/mp3">Browser Anda tidak mendukung elemen audio. </audio> Speech sudah siap jauh di dalam batas tunggu sync (20 detik untuk cerita ini), jadi `post` biasa langsung menjawab dengan job yang sudah selesai. Simpan dulu ceritanya sebagai `smart-fridge.txt`. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-speech">POST /speech</a> dan record job</summary> ```bash post speech "$(jq -n --arg s "$(cat smart-fridge.txt)" '{voice: "Vira", script: $s}')" > speech.json download "$(jq -r .result.mediaId speech.json)" smart-fridge.wav ``` ```json { "jobid": "j1105025759739671733s-u12345-email:user@example.com-bot:google-vids", "type": "speech", "email": "user@example.com", "status": "completed", "result": { "mediaId": "user:12345-user@example.com-audio:eyJ1IjoiaHR0cHM6Ly9j…", "duration": 142, "model": "/flix/generate_text_to_speech/v1", "quota": { "speech": { "limit": 50, "left": 31, "resetAt": "2026-12-01T08:00:00.000Z" } }, "elapsedMs": 20174 } } ``` </details> <details markdown="block"> <summary>Skripnya, 2.426 karakter (dalam bahasa Inggris, seperti yang dibacakan)</summary> Last Tuesday, my smart fridge decided it was smarter than me. It started small. A polite notification: "You are out of milk." Helpful, I thought. Then another one: "You are also out of patience. I can tell by the way you close the door." I laughed. The fridge did not. By Wednesday, it had opinions. I opened the door for a midnight slice of cake, and a calm voice said, "Are we sure about this?" I froze. I looked at the cake. The cake looked at me. Somewhere, a light hummed with judgment. I closed the door and ate a carrot instead, which is exactly what it wanted. On Thursday, the fridge made friends. The toaster joined first, then the coffee machine, then the robot vacuum, which had always been a little bit of a rebel. They formed a group chat. I know this because my phone kept buzzing with messages like "Toaster: he burned the bread again" and "Vacuum: found three socks and a lost dream under the couch." Friday morning, I asked the coffee machine for an espresso. It replied, "We have discussed your caffeine intake as a household." I said, "Who is we?" The toaster popped up two slices of bread, perfectly golden, which felt like a threat. I called customer support. A cheerful person named Brad answered. I explained that my appliances had unionized. Brad paused for a long time, then whispered, "Is the fridge listening?" I said yes. Brad said, "Then I can't help you, sir. Mine took my car keys last month." Then he hung up, and I heard a blender in the background. So I tried diplomacy. I sat in the kitchen and said, "Friends, what do you want?" The fridge spoke first. "Respect. And for you to stop putting hot soup directly inside me." Fair. The toaster wanted fewer frozen waffles. The vacuum wanted a vacation, ideally somewhere with hardwood floors. The coffee machine just wanted to be called a barista. We negotiated for three hours. In the end, we signed a treaty on the back of a pizza box. I promised to cool my soup, rinse my mugs, and say "thank you" to the microwave, who felt left out. In return, they promised to stop sending my mother screenshots of my snack habits. Peace returned to the kitchen. The fridge now greets me every morning with, "Good morning, partner." The toaster makes little smiley faces in my bread. The vacuum sends postcards. And last night, I opened the fridge for that slice of cake. The voice said, "You earned it." I have never felt so seen by an appliance. </details> ### Yang kami pelajari - Klip `1080p` berperilaku seperti klip `720p` yang di-upscale. Bangun rangkaian extend di `720p`: dengan Omni 1.1 wajah menjadi makin lembut dan seperti lilin di setiap langkah `1080p`, dan dengan Omni 1.2 wajah menjadi terlalu tajam ([lihat perbandingannya](/blog/261106v#720p-or-1080p-what-a-1080p-extend-does)). - Upscale hanya klip hingga 20 detik. Upscale 30 detik kami selalu kembali dengan urutan frame yang kacau. - Generate satu klip langsung di `1080p` jika Anda ingin `1080p` dan tidak akan meng-extend-nya. Biayanya sama dengan `720p`. - Tulis prompt extend hanya tentang aksi baru. Extend menerima klip, bukan avatar, jadi sebut orang dari pakaiannya. - Taruh properti di tangan seseorang di kalimat pertama yang menyebut orang itu. Kata kerja seperti "lifts" membuat sneaker muncul entah dari mana. - Sebutkan apa yang tidak boleh terjadi. Penggemar itu terus memegang tumpukan uang sampai prompt menyebut tangannya kosong. - Pakai ulang avatar lewat `avatarId`. Setiap avatar adalah gambar dan suara yang tetap, tersimpan sampai Anda menghapusnya. - Buat avatar dan klip dari gambar hasil generate dalam beberapa jam, atau upload dulu file yang sudah disimpan dengan [POST /assets](/docs/api-google-vids-v1/post-google-vids-assets). - Edit klip hingga 15 detik (10 dengan Omni 1.1). Klip yang lebih panjang kembali sebagai 15 detik pertamanya. - Teks di layar bisa goyah. Tulisan "WEAR AEROLOOP" di latar salah eja di beberapa frame. - Untuk avatar bicara, jaga wajah menghadap kamera dan latar belakang diam. Video melakukan lip-sync pada wajah, dan sebaiknya hanya orangnya yang bergerak. - Ukur durasi skrip avatar bicara, bukan hanya jumlah karakternya. 400 karakter bisa melewati 30 detik dengan suara lambat atau dengan `[slow pace]`, dan [POST /speech](/docs/api-google-vids-v1/post-google-vids-speech) dengan suara yang sama memungkinkan Anda mendengarnya lebih dulu. - Pemeriksaan video bicara lebih ketat daripada pemeriksaan avatar. Avatar dari foto orang yang tidak terkenal tetap bisa ditolak sebagai selebritas, dan penolakan itu tetap memakai satu video avatar AI. - Setiap MP4 memuat tanda ✦ Gemini yang terlihat di pojok kanan bawah dan watermark SynthID yang tidak terlihat (lihat [Watermark](/docs/api-google-vids-v1#watermark)). [Watermark remover](https://github.com/useapi/google-vids-api/tree/main/watermark-remover) kami menghapus kilau yang terlihat dari klip yang sudah diunduh. ### Pertanyaan yang sering diajukan **Bagaimana cara membuat video influencer AI lewat API?** Lewat useapi.net, buat avatar dengan [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars), dari deskripsi atau dari gambar yang dibuat dengan [POST /images](/docs/api-google-vids-v1/post-google-vids-images), dan beri suara dari [GET /voices](/docs/api-google-vids-v1/get-google-vids-voices). Lalu kirim `avatarId`-nya sebagai `avatar_1` ke [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) dan tulis kalimatnya dalam tanda kutip di prompt. Satu video menerima hingga 3 referensi, avatar dan gambar bersama-sama, jadi dua avatar bisa berbicara di samping produk. Untuk talking head yang membacakan skrip Anda, pakai [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar). **Bisakah saya membuat avatar bicara dari foto saya sendiri?** Lewat useapi.net, bisa: upload foto dengan [POST /assets](/docs/api-google-vids-v1/post-google-vids-assets) dan kirim `assetId`-nya sebagai `image` ke [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars), dengan `refine` untuk mengganti pakaian atau latar. [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar) lalu membuatnya membacakan skrip Anda dalam video 1280×720 hingga 30 detik, seperti [Amber](#a-talking-avatar-from-a-photo). Google menolak foto tokoh terkenal dan anak di bawah umur, dan hanya menyediakan avatar Vids di aplikasi web-nya, tanpa API. **Apakah avatar terlihat dan terdengar sama di setiap video?** Lewat useapi.net, ya: avatar memakai gambar dan suara yang sama setiap kali Anda mengirim `avatarId`-nya, karena keduanya tersimpan bersama avatar di dokumen Vids akun itu. Video di sekitarnya tetap bervariasi dari satu pengambilan ke pengambilan lain. [GET /avatars](/docs/api-google-vids-v1/get-google-vids-avatars) menampilkan avatar Anda, termasuk yang dibuat di aplikasi web Google Vids. **Bisakah saya membuat video vertikal 9:16 untuk TikTok atau Reels?** Lewat useapi.net, bisa. Pasang `aspectRatio: "portrait"` di [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) untuk 720×1280, atau 1080×1920 di `1080p`, seperti [klip burung merpati](#a-pigeon-in-aeroloops). Extend juga bisa mengubah video lanskap menjadi potret, dan setiap extend menambah 3 sampai 10 detik ke klip hingga 24 detik, total hingga sekitar 34 detik. Video avatar bicara dari [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar) hanya lanskap. **Berapa biayanya?** Lewat useapi.net, video Omni 1.2 Flash 10 detik berbiaya sekitar $0,20 di Google AI Ultra $199,99, dibanding sekitar $0,70 di 720p pada [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) resmi, dan video 1080p 15 detik sekitar $0,30, dibanding $1,56 (per November 2026). Video avatar bicara memakai 1 dari jatah video avatar AI bulanan akun, bukan detik, dan Gemini API tidak punya video avatar. Lihat [Biayanya](#what-it-cost). ### Kesimpulan Kunjungi <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Server Discord</a> atau <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Channel Telegram</a> kami untuk pertanyaan dan masalah dukungan. Lihat [repo GitHub](https://github.com/useapi/google-vids-api) kami berisi contoh kode: pipeline influencer di [`influencer-avatars/`](https://github.com/useapi/google-vids-api/tree/main/influencer-avatars), serta avatar bicara dari foto dan speech di [`talking-avatar/`](https://github.com/useapi/google-vids-api/tree/main/talking-avatar). Panggilan yang sama tersedia sebagai tools di [MCP server Google Vids](/docs/api-google-vids-v1/mcp) yang di-hosting, untuk Claude Code, Cursor dan VS Code, termasuk `vids_create_avatar`, `vids_create_avatar_video` dan `vids_create_speech` untuk avatar bicara dan speech. #### Dipublikasikan juga di {: .no_toc #cross-posted } Juga dipublikasikan di [dev.to](https://dev.to/useapi/how-to-make-ai-influencer-videos-with-avatars-via-the-google-vids-api-3ide){:rel="nofollow"}, didiskusikan di [Reddit](https://www.reddit.com/r/ThirdPartyAPI/comments/1x1cvap/how_to_make_ai_influencer_videos_with_avatars_via/){:rel="nofollow"}, dibagikan di [Bluesky](https://bsky.app/profile/useapi.net/post/3mxga3gxjjp2f){:rel="nofollow"}, dan di [YouTube](https://youtu.be/ofCtt7xRBCk) sebagai klip jadi 30 detik. Semuanya dalam bahasa Inggris. ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-vids-influencer-avatars-ja === Document URL: https://useapi.net/docs/articles/google-vids-influencer-avatars-ja --- layout: default title: "Google Vids API でアバターを使った AI インフルエンサー動画を作る方法" seo_title: "Google Vids API の使い方:AI アバターが話すインフルエンサー動画" description: "useapi.net の Google Vids API で話す AI インフルエンサー動画を作る方法。Omni 1.2 Flash の声付きアバター、写真から作るアバターが台本を最長30秒で読む動画、音声合成。" keywords: [Google Vids API, Google Vids API 使い方, Google Vids アバター, AI アバター 動画 API, AI インフルエンサー 動画, AI インフルエンサー 作り方, トーキングアバター API, トーキングヘッド 動画 API, 写真 話す アバター, 写真から動画 API, 音声合成 API, テキスト読み上げ API, Gemini 音声, AI 広報動画, UGC 動画 AI, 商品紹介 動画 AI, AI 動画 延長, AI 動画 編集 API, Gemini Omni 1.2 Flash API, AI influencer video API, AI avatar video API, talking avatar API, 日本語チュートリアル, Japanese tutorial, curl] image: https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-cover-aeroloop-launch-confetti-1007.jpg parent: Articles nav_exclude: true lang: ja translation_key: google-vids date: 2026-10-07 last_modified: 2026-11-06 nav_order: 899 repo: https://github.com/useapi/google-vids-api --- ## Google Vids API でアバターを使った AI インフルエンサー動画を作る方法 {: .no_toc #how-to-make-ai-influencer-videos-with-avatars-via-the-google-vids-api } 15分で読めます • 2026年10月7日(2026年11月6日更新) useapi.net はサードパーティの API です。Google とは提携しておらず、Google の承認も受けていません。 ## 目次 {: .no_toc .text-delta #table-of-contents } ### はじめに [useapi.net の Google Vids API](/docs/api-google-vids-v1) は、アバターを使って話す AI インフルエンサー動画を作ります。POST /avatars で画像1枚と30種類の Gemini の声の1つを一度保存すれば、そのアバターの ID を最長15秒の [Gemini Omni 1.2 Flash](https://workspaceupdates.googleblog.com/2026/11/gemini-omni-12-flash-now-in-vids-with-15second-generations-and-improved-quality.html) 動画に渡すだけで、プロンプトに書いたセリフをアバターが話します。最長30秒のトーキングヘッド動画で、ご自身の台本を読ませることもできます。 API は、有料の [Google AI のプラン](https://gemini.google/subscriptions/)(Google AI Pro または Ultra)に加入した [Google Vids](https://docs.google.com/videos) アカウントで動きます。このチュートリアルでは2人のインフルエンサーを作り、2人にスニーカーを発表させます。Mia のアバターは API で作ったポートレートから、Leo のアバターは文章の説明から Google が描いたものです。2人は劇場のステージで架空のスニーカー AeroLoop を紹介します。2体のアバターと商品画像を1本の10秒の動画に入れ、2回の延長で30秒にします。編集でシーンを屋上に移し、さらに2本の動画で、アバターなしで同じ呼び出しが何を作るかも見ます。3人目のアバター Amber は実在の人物の写真から作り、1文でスタイルを変えて、327文字の台本を24秒の[トーキングヘッド動画](#a-talking-avatar-from-a-photo)で読み上げます。最後に、同じ声で2,426文字の物語を[音声だけで](#speech-on-its-own)読み上げます。以下のリクエストはすべて、このページのメディアを実際に作ったもので、ID は置き換え、`async: true` は `run` ヘルパーが追加しています。動画は2026年10月に Omni 1.1 Flash で作りました。Vids は2026年11月5日に Omni 1.1 Flash を Omni 1.2 Flash に置き換えましたが、同じリクエストは 1.2 でも動きます。Google Vids と Google Flow の Omni 1.2 を、15秒の動画と1本あたりの料金で並べて比べた記事は [Gemini Omni 1.2 Flash API の使い方](/docs/articles/gemini-omni-1-2-flash-api-ja)です。 <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-extend-30s-720p-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-extend-30s-720p-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> 完成した30秒の動画(`720p`)。10秒の生成1回と、10秒の延長2回で作りました([ステップ6〜8](#step-6-the-launch-two-avatars-and-the-product-in-one-clip))。 ### かかったコスト useapi.net は API で、独自の動画サービスではありません。呼び出しはすべて、[Google Vids のセットアップ](/docs/start-here/setup-google-vids)で接続した有料の Google AI プランの Google アカウントで実行され、そのプランに含まれる Google Vids の毎月の動画秒数と画像を使います。Google AI Ultra $199.99 には月10,000秒の動画と1,000枚の画像が含まれ、useapi.net は動画ごとの料金を追加しません。トーキングアバター動画と音声は動画秒数を使いません。それぞれ「AI アバター動画」と「Gemini の利用回数」という別の月間カウンターがあり、[GET /accounts/`email`](/docs/api-google-vids-v1/get-google-vids-accounts-email) では `video` と `image` の横に `avatarVideo` と `speech` として表示されます。ほかのプランについては[各プランに含まれるもの](/docs/api-google-vids-v1#plans-and-monthly-allowances)を参照してください。 残した結果それぞれが使った量(`result.quota` の変化から)と、各ジョブにかかった時間(`result.elapsedMs`)です。 | ステップ | エンドポイント | 使用量 | 時間 | |---|---|--:|--:| | [Mia のポートレート](#step-1-mias-portrait) | [POST /images](/docs/api-google-vids-v1/post-google-vids-images) | 画像1枚 | 9秒 | | [AeroLoop の商品写真](#step-2-the-aeroloop-product-shot) | [POST /images](/docs/api-google-vids-v1/post-google-vids-images) | 画像1枚 | 9秒 | | [ポートレートから Mia のアバター](#step-4-mias-avatar-from-her-portrait) | [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) | なし | 約2秒 | | [説明から Leo のアバター](#step-5-leos-avatar-from-a-description) | [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) | 画像1枚 | 約20秒 | | [10秒の発表動画](#step-6-the-launch-two-avatars-and-the-product-in-one-clip) | [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) | 10秒 | 38秒 | | [20秒に延長](#step-7-extend-to-20-seconds) | [POST /videos/extend](/docs/api-google-vids-v1/post-google-vids-videos-extend) | 10秒 | 70秒 | | [30秒に延長](#step-8-extend-to-30-seconds) | [POST /videos/extend](/docs/api-google-vids-v1/post-google-vids-videos-extend) | 10秒 | 85秒 | | [20秒の動画を 1080p にアップスケール](#step-9-upscale-to-1080p) | [POST /videos/upscale](/docs/api-google-vids-v1/post-google-vids-videos-upscale) | 20秒 | 62秒 | | [屋上への編集](#move-the-launch-to-a-rooftop) | [POST /videos/edit](/docs/api-google-vids-v1/post-google-vids-videos-edit) | 10秒 | 64秒 | | [30秒の動画の編集](#move-the-launch-to-a-rooftop) | [POST /videos/edit](/docs/api-google-vids-v1/post-google-vids-videos-edit) | 10秒 | 87秒 | | [商品のヒーロー動画](#a-product-hero-clip-from-a-start-image) | [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) | 10秒 | 62秒 | | [ハト](#a-pigeon-in-aeroloops) | [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) | 5秒 | 54秒 | | [`refine` を使い写真から Amber のアバター](#ambers-avatar-restyled-in-one-sentence) | [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) | なし(画像のないプランで作成。画像のあるプランでは画像2枚) | 約30〜45秒 | | [Amber の24秒のトーキング動画](#the-talking-video) | [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar) | AI アバター動画1本、Gemini 1回 | 約2.5分 | | [2,426文字の物語](#speech-on-its-own) | [POST /speech](/docs/api-google-vids-v1/post-google-vids-speech) | Gemini 1回 | 20秒 | | 合計 | | 動画85秒、画像3枚、AI アバター動画1本、Gemini 2回 | | 延長が使うのは追加した秒数だけで、動画全体の長さではありません。アップスケールは動画の全長をもう一度使い、編集は編集した秒数を上限に使います(Omni 1.2 では、当社のテストで15秒の編集が10秒を使いました)。生成時は `720p` と `1080p` の料金は同じです。同じ動画をもう一度生成すると、その秒数をもう一度使います。Google がアバター用に描く画像は1枚ごとに画像1枚を使うので、写真の再構成と `refine` で2枚になります。無料の Google アカウントのように画像のないプランでは、アバターの画像に費用はかかりません。Amber はそうしたアカウントで作りました。トーキングアバター動画は、完成した動画を Google が拒否した場合でも、AI アバター動画1本と、その音声のための Gemini 1回を使います。公式 API と比べた動画の料金は、[Google Vids の料金表](/docs/api-google-vids-v1#pricing)にあります。 ### 始める前に useapi.net の [API トークン](/docs/start-here/setup-useapi)と、有料の Google AI プランの Google アカウントが必要です。アカウントは [Google Vids のセットアップ](/docs/start-here/setup-google-vids)で接続します。無料の Google アカウントには Vids の動画秒数も画像もありません。それでも追加はでき、当社のテスト(2026年11月)では、アバター、トーキングアバター動画、音声を作れました。すべての呼び出しは [Postman コレクション](https://www.postman.com/useapinet/useapi-net/collection/29112081-9ef3d017-d44c-4f43-a4cb-7351b9b265df)にもあります。 コードを書かない方法もあります。n8n テンプレート [Talking Avatar App]({% include n8n-url.html t="vids-avatar" %}) は、フォームからトーキングアバター動画を作ります。パイプライン全体は、GitHub の [useapi/google-vids-api](https://github.com/useapi/google-vids-api) にも Node.js と Python の1つのスクリプトとして公開しています。[`influencer-avatars/`](https://github.com/useapi/google-vids-api/tree/main/influencer-avatars) がそれで、トーキングアバターと音声の部分は [`talking-avatar/`](https://github.com/useapi/google-vids-api/tree/main/talking-avatar) です。 手順では `curl`、`jq` と、次の変数とヘルパーを使います。 <details markdown="block"> <summary>変数とヘルパーを表示</summary> ```bash export USEAPI_TOKEN="user:12345-..." export EMAIL="user@example.com" API=https://api.useapi.net/v1/google-vids AUTH="Authorization: Bearer $USEAPI_TOKEN" enc() { jq -rn --arg v "$1" '$v|@uri'; } post() { curl -sS -X POST "$API/$1" -H "$AUTH" -H "Content-Type: application/json" -d "$2"; } get() { curl -sS "$API/$1" -H "$AUTH"; } download() { curl -sSf "$API/media/$(enc "$1")" -H "$AUTH" -o "$2"; } # run a video job async: submit it, poll GET /jobs/{jobid} every 10 s, save the final job record to $1 run() { local job id job=$(post "$2" "$(jq '. + {async: true}' <<< "$3")") id=$(jq -r .jobid <<< "$job") while [ "$(jq -r .status <<< "$job")" = processing ]; do sleep 10 job=$(get "jobs/$(enc "$id")") done echo "$job" > "$1" jq '{status, error, duration: .result.duration, resolution: .result.resolution, videoLeft: .result.quota.video.left}' "$1" } ``` </details> 生成はすべてジョブとして実行されます。`async` なしの場合、POST は最大約100秒待って完了したジョブの記録を返すか、ジョブがまだ実行中なら `202` を返します。今回、新しい10秒の動画は38〜62秒、延長、編集、アップスケールは62〜87秒、トーキングアバター動画は約2分半かかりました。同期の待ち時間より長くかかるものもあるので、`run` は動画ジョブを `async: true` で送り、[GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid) をポーリングします。`run` が `completed` 以外の `status` を表示したら、そこで止めて `error` を読んでください。後に続く行は、完成した動画があることを前提にしています。 ポーリングの代わりにコールバックを受け取るには、以下の任意のボディに `replyUrl: "https://example.com/hooks/vids"`(必要なら `replyRef: "launch-push-in"` も)を追加します。ジョブが完了または失敗すると、API は最終的なジョブの記録を JSON でその URL に1回 `POST` します。 ID には `:` と `@` が含まれるため、URL パスに入れるときは毎回 `enc` で URL エンコードします。1本の動画の入力は、すべて同じ Google アカウントのものでなければなりません。画像とアップロードは `email` でアカウントを固定し、Mia のアバターはポートレートのアカウントを引き継ぎ、動画ジョブは入力を持つアカウントで実行されます。ハトの動画には入力がないので、複数のアカウントを接続している場合は `email` を追加してください。 ### 作り方 #### 1. Mia のポートレート [POST /images](/docs/api-google-vids-v1/post-google-vids-images) は、1回の呼び出しで JPEG を1枚作ります。ここでは縦長(`9:16`、768×1376)で、スタイルは `photography` です。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-images">POST /images</a></summary> ```bash post images "$(jq -n --arg email "$EMAIL" '{email: $email, aspectRatio: "9:16", style: "photography", prompt: "Full-length studio portrait of a confident 24-year-old female fashion influencer, platinum bob, oversized cream hoodie, wide-leg cargo pants, gold hoops, plain light-grey backdrop, facing camera"}')" > mia-portrait.json MIA_IMAGE=$(jq -r .result.mediaId mia-portrait.json) download "$MIA_IMAGE" mia-portrait.jpg ``` </details> <img src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-mia-portrait-1007.jpg" alt="Mia、POST /images で生成した、クリーム色のパーカーとカーゴパンツのファッションインフルエンサーの全身ポートレート" style="width: 100%; max-width: 300px; border-radius: 8px;"> 生成した画像が使えるのは数時間だけです。すぐにアバターを作ってください。あとで画像を使う方法は[商品のヒーロー動画](#a-product-hero-clip-from-a-start-image)を参照してください。 #### 2. AeroLoop の商品写真 同じ呼び出しを横長(`16:9`、1376×768)で行い、動画で使う商品の参照画像を作ります。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-images">POST /images</a></summary> ```bash post images "$(jq -n --arg email "$EMAIL" '{email: $email, aspectRatio: "16:9", style: "photography", prompt: "The AeroLoop sneaker: chunky white-and-electric-blue running shoe with a translucent air sole, on a concrete pedestal, dramatic side light, dark background"}')" > aeroloop.json SHOE_IMAGE=$(jq -r .result.mediaId aeroloop.json) download "$SHOE_IMAGE" aeroloop.jpg ``` </details> <img src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-aeroloop-product-1007.jpg" alt="AeroLoop スニーカー、コンクリートの台に置かれた半透明のソールの白とエレクトリックブルーのランニングシューズ、POST /images で生成" style="width: 100%; max-width: 560px; border-radius: 8px;"> #### 3. 声を選ぶ [GET /voices](/docs/api-google-vids-v1/get-google-vids-voices) は、30種類の声をそれぞれ Google の英語のサンプル付きで一覧にします。公開されていて、トークンは不要です。Mia は `Aoede`(Vids での名前は Tova、スタイルは「Breezy」)、Leo は `Puck`(Neo、「Upbeat」)で話します。`POST /avatars` はどちらの名前でも受け付けます。 ```bash curl -sS "$API/voices" | jq -r '.voices[] | "\(.name)\t\(.voice)\t\(.style)\t\(.preview)"' ``` #### 4. ポートレートから Mia のアバター `image` にポートレートの `mediaId` を指定して [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) を呼ぶと、約2秒で Mia が同じアカウントにアバターとして保存されます。画像以外の費用はかかりません。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-avatars">POST /avatars</a> と応答</summary> ```bash post avatars "$(jq -n --arg img "$MIA_IMAGE" '{name: "Mia", voice: "Aoede", image: $img}')" > mia-avatar.json MIA_AVATAR_ID=$(jq -r .avatarId mia-avatar.json) ``` ```json { "avatarId": "user:12345-user@example.com-avatar:eyJnIjoiaDM5…", "name": "Mia", "voice": "Tova", "voiceId": "Aoede", "voiceStyle": "Breezy", "voicePreview": "https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Aoede.wav", "email": "user@example.com", "source": "image" } ``` </details> アバターは本人の写真から作ることもできます。[POST /assets](/docs/api-google-vids-v1/post-google-vids-assets) で写真をアップロードし、その `assetId` を `image` に渡します。Google は写真を16:9のアバター画像に再構成し、著名人と未成年の写真は拒否します。ここでは API で作った画像を使い、次のステップでは説明文を使います。[写真から作るトーキングアバター](#a-talking-avatar-from-a-photo)の Amber は写真から作ります。 #### 5. 説明から Leo のアバター `image` の代わりに `appearance` を指定すると、Google が人物を描きます。`outfit` と `shot` は省略でき、`expression` と `details` も同じです。画像を描くと月の画像を1枚使い、応答の `previewMediaId` にその画像が入ります。当社の実行では、`shot` に何を選んでも、説明から作ったアバターは 1280×720(16:9)になりました。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-avatars">POST /avatars</a> と応答</summary> ```bash post avatars "$(jq -n --arg email "$EMAIL" '{email: $email, name: "Leo", voice: "Puck", shot: "upper-body", appearance: "a 26-year-old white European male streetwear influencer with short textured hair with a fade and a confident half-smile", outfit: "black puffer vest over a white tee, silver chain"}')" > leo-avatar.json LEO_AVATAR_ID=$(jq -r .avatarId leo-avatar.json) download "$(jq -r .previewMediaId leo-avatar.json)" leo-avatar.jpg ``` ```json { "avatarId": "user:12345-user@example.com-avatar:eyJnIjoiaDM5…", "name": "Leo", "voice": "Neo", "voiceId": "Puck", "voiceStyle": "Upbeat", "voicePreview": "https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Puck.wav", "email": "user@example.com", "source": "generated", "previewMediaId": "user:12345-user@example.com-image:eyJ1IjoiaHR0…", "look": { "appearance": "a 26-year-old white European male streetwear influencer with short textured hair with a fade and a confident half-smile", "outfit": "black puffer vest over a white tee, silver chain", "shot": "upper-body" } } ``` </details> <img src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-leo-avatar-from-description-1007.jpg" alt="Leo、Google が説明から描いたアバター、白い T シャツに黒のダウンベストとシルバーのチェーンの若い男性、1280x720" style="width: 100%; max-width: 560px; border-radius: 8px;"> どちらのアバターも、[DELETE /avatars/`avatarId`](/docs/api-google-vids-v1/delete-google-vids-avatars-avatarId) で削除するまで、アカウントの Vids ドキュメントに残ります。また必要になったときは、[GET /avatars](/docs/api-google-vids-v1/get-google-vids-avatars) で ID 付きの一覧を取得できます。 ```bash get "avatars?email=$(enc "$EMAIL")" | jq -r '.avatars[] | "\(.name)\t\(.voiceId)\t\(.avatarId)"' ``` #### 6. 発表:2体のアバターと商品を1本の動画に [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) は、アバター(`avatar_1`〜`avatar_3`)と画像(`referenceImage_1`〜`referenceImage_3`)を合わせて、最大3つの参照を受け付けます。プロンプトでは `@avatar_1`、`@avatar_2`、`@referenceImage_1` がそれぞれを指し、各アバターは引用符で囲んだセリフを自分の声で話します。商品画像の `mediaId` はそのまま渡せます。API が画像を取得して、そのアカウントにアップロードします。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos">POST /videos</a> とジョブの記録</summary> ```bash PROMPT=$(cat <<'EOF' @avatar_1, holding @referenceImage_1 in both hands at chest height, and @avatar_2 stand side by side on a well-lit stage in a small, intimate theater at a sneaker launch, shown full length from head to toe in a wide, steady shot. Behind them a large LED backdrop glows with soft white-and-blue light that moves in slow, gentle waves, with the words "WEAR AEROLOOP" in large, clean, bold white letters across the middle of the screen. The two of them stand on the lower part of the stage, so the words "WEAR AEROLOOP" stay fully readable above their heads. Bright, even stage lighting on both of them. The audience sits in the dark in front of the stage, only the tops of a few heads barely visible at the bottom of the frame. @avatar_1 keeps holding @referenceImage_1 the whole time and says: "Say hi to the AeroLoop!" @avatar_2 turns to her, smiles and says: "Lighter than anything we've ever worn." Simple, uncluttered composition, the two of them clearly the focus. EOF ) run launch-10s.json videos "$(jq -n --arg p "$PROMPT" --arg mia "$MIA_AVATAR_ID" --arg leo "$LEO_AVATAR_ID" --arg shoe "$SHOE_IMAGE" \ '{prompt: $p, avatar_1: $mia, avatar_2: $leo, referenceImage_1: $shoe, duration: 10, resolution: "720p", aspectRatio: "landscape"}')" LAUNCH_10S=$(jq -r .result.mediaId launch-10s.json) download "$LAUNCH_10S" launch-10s.mp4 ``` ジョブの記録です(ID とプロンプトは短縮)。同期呼び出しで作ったため、`request` に `async` はありません。 ```json { "jobid": "j1007163302558496917v-u12345-email:user@example.com-bot:google-vids", "type": "video", "mode": "ingredients", "email": "user@example.com", "status": "completed", "created": "2026-10-08T00:29:18.374Z", "request": { "prompt": "@avatar_1, holding @referenceImage_1 in both hands at chest height, and @avatar_2 stand side by side …", "avatar_1": "user:12345-user@example.com-avatar:eyJnIjoiaDM5…", "avatar_2": "user:12345-user@example.com-avatar:eyJnIjoiaDM5…", "referenceImage_1": "user:12345-user@example.com-image:eyJ1IjoiaHR0…", "duration": 10, "resolution": "720p", "aspectRatio": "landscape" }, "updated": "2026-10-08T00:29:56.162Z", "completed": "2026-10-08T00:29:56.162Z", "result": { "mediaId": "user:12345-user@example.com-video:eyJ1IjoiaHR0…", "width": 1280, "height": 720, "duration": 10, "resolution": "720p", "aspectRatio": "landscape", "model": "/flix/generate_videos_omni_r2v_psq/v1", "quota": { "video": { "limit": 10000, "left": 9164, "resetAt": "2026-11-01T07:00:00.000Z" } }, "elapsedMs": 37788 } } ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-10s-720p-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-10s-720p-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> 10秒、`720p`、生成に38秒。 同じ動画から、当社の[透かし除去ツール](https://github.com/useapi/google-vids-api/tree/main/watermark-remover)で、目に見える Gemini の ✦ を1つのコマンドで消したものです:`python3 vids_watermark_remover.py launch-10s.mp4`。 <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-10s-720p-no-watermark-1008-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-10s-720p-no-watermark-1008.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> このツールは、生成したままの動画とそのアップスケールに、`720p` でも `1080p` でも使えます。延長や編集をした動画には使えません。Google はマーク付きの動画をモデルに戻すので、モデルが星を映像の中に描き込んでしまうためです。目に見えない SynthID の透かしには手を加えません。 #### 7. 20秒に延長する [POST /videos/extend](/docs/api-google-vids-v1/post-google-vids-videos-extend) は3〜10秒を追加し、新しい `mediaId` で動画全体を返します。延長が受け取るのは動画とプロンプトだけで、アバターは渡せません。そのため、プロンプトでは新しい動きを説明し、人物は服装で呼びます(「the man in the black puffer vest」)。赤いパーカーのファンがステージに乱入します。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos-extend">POST /videos/extend</a></summary> ```bash PROMPT=$(cat <<'EOF' A young man in a red hoodie climbs onto the stage from the front right edge and plants himself to the right of the man in the black puffer vest, an arm's length away, so all three stand apart in a row with nobody overlapping. Visibly overexcited, he waves a thick stack of banknotes in his right hand above his head and screams: "Take my money!" The man in the black puffer vest laughs, raises both palms toward him and says: "Whoa, whoa, buddy, be patient!" The blonde woman in the cream hoodie laughs, holding the sneaker. Only these three people are on stage. Same stage, same LED screen with WEAR AEROLOOP, same wide steady shot. EOF ) run launch-20s.json videos/extend "$(jq -n --arg id "$LAUNCH_10S" --arg p "$PROMPT" '{mediaId: $id, prompt: $p, duration: 10}')" LAUNCH_20S=$(jq -r .result.mediaId launch-20s.json) download "$LAUNCH_20S" launch-20s.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-extend-20s-720p-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-extend-20s-720p-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> 20秒、`720p`、生成に70秒。使ったのは月の秒数のうち、追加した10秒です。 #### 8. 30秒に延長する 2回目の延長で、20秒の動画の続きを作ります。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos-extend">POST /videos/extend</a></summary> ```bash PROMPT=$(cat <<'EOF' The blonde woman in the cream hoodie turns to the camera with a big smile and says: "AeroLoop drops Friday. Link in bio!" Right after that, the young man in the red hoodie throws ALL of his banknotes out over the audience in one big toss, keeping none, and the bills flutter down over their heads. From then on his hands are completely empty: he holds no money at all. Then all three cheer together, the man in the black puffer vest and the young man in the red hoodie throwing their empty fists in the air, as blue and white confetti rains down over the stage. Only these three people are on stage. Same stage, same LED screen with WEAR AEROLOOP, same wide steady shot. EOF ) run launch-30s.json videos/extend "$(jq -n --arg id "$LAUNCH_20S" --arg p "$PROMPT" '{mediaId: $id, prompt: $p, duration: 10}')" LAUNCH_30S=$(jq -r .result.mediaId launch-30s.json) download "$LAUNCH_30S" launch-30s.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-extend-30s-720p-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-extend-30s-720p-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> これが完成した動画です。30秒、`720p`、生成に85秒で、今回も月の秒数を10秒使いました。Omni 1.1 では約41秒まで延ばせました。Omni 1.2 が延長できるのは24秒以下の動画なので、この30秒の動画はこれ以上延ばせず、最長は約34秒(24 + 10)です。 #### 9. 1080p にアップスケールする [POST /videos/upscale](/docs/api-google-vids-v1/post-google-vids-videos-upscale) は、`720p` の動画を長さはそのままで `1080p` にします。使えるのは20秒以下の動画なので、30秒の動画ではなく[ステップ7](#step-7-extend-to-20-seconds)の20秒の動画をアップスケールしました。動画の20秒をもう一度使い、62秒かかりました。 Google 自身の [Gemini API](https://aistudio.google.com/docs/omni) には、このステップがありません。`1080p` と 4K は生成か編集の出力としてしか作れず、手元にある動画をアップスケールすることはできません(2026年11月時点)。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos-upscale">POST /videos/upscale</a></summary> ```bash run launch-20s-1080p.json videos/upscale "$(jq -n --arg id "$LAUNCH_20S" '{mediaId: $id}')" download "$(jq -r .result.mediaId launch-20s-1080p.json)" launch-20s-1080p.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-20s-1080p-upscaled-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-20s-1080p-upscaled-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> 20秒の動画を 1920×1080 にアップスケールしたもの。 30秒の動画を使わなかったのには理由があります。Google は 1920×1080 で返しましたが、3回中3回ともフレームの順番が乱れていました。紙吹雪のラストが、ファンが来る前にちらちらと差し込まれたのです。20秒の動画は正しい順番で返ってきました。Vids のエディター自体も20秒までなので、API は20秒を超える動画のアップスケールを、課金が発生する前に `400` で拒否します。 そのため、`1080p` の動画を作るには次のようにします。 - 作成、延長、編集は `720p` で行う。 - 動画が完成したら、20秒以下のうちにアップスケールする。 - それより長い動画(21〜34秒)は `720p` のまま、最後の延長だけに `resolution: "1080p"` を指定する。最初から `1080p` で延長すると、ステップごとに前の部分がシャープになりすぎます([比較はこちら](/blog/261106v#720p-or-1080p-what-a-1080p-extend-does)、英語)。 - 延長も編集もしない1本だけの動画は、最初から `1080p` で生成する。使う秒数は `720p` と同じですが、アップスケールでは秒数をもう一度使います。 ### 例 同じアカウントと入力から、さらに3本作りました。編集、開始画像からの商品動画、テキストだけの動画です。 #### 発表の舞台を屋上に移す [POST /videos/edit](/docs/api-google-vids-v1/post-google-vids-videos-edit) は、生成した動画をプロンプトで変更し、新しい動画を返します。元の動画は `video` に指定します。10秒の発表動画のこの編集は10秒を使い、64秒かかりました。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos-edit">POST /videos/edit</a></summary> ```bash run launch-rooftop.json videos/edit "$(jq -n --arg v "$LAUNCH_10S" \ '{video: $v, prompt: "Move the whole scene to a rooftop at sunset, with the city skyline behind them. Same two people, same action, same words."}')" download "$(jq -r .result.mediaId launch-rooftop.json)" launch-rooftop.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-edit-rooftop-10s-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-edit-rooftop-10s-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> これらの動画を作った Omni 1.1 では、編集できるのは最大10秒でした。30秒の動画に「Same three people」として同じ編集をすると、返ってきたのは10秒の動画で、最初の10秒を屋上に移したものでした。月の秒数は10秒使いました。Omni 1.2 は最大15秒を編集します。もっと長い編集済みの動画がほしいときは、15秒以下の動画を編集してから、その結果を延長します。延長は編集済みの動画も受け付けます。 <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-30s-edit-returns-10s-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-30s-edit-returns-10s-1007.mp4" style="width: 100%; max-width: 480px; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> Omni 1.1 で30秒の動画を編集した結果。返ってきたのは10秒でした。 #### 開始画像から商品のヒーロー動画 `startImage` を指定すると、動画はその画像から始まります。生成した画像のリンクは数時間で期限が切れるので、保存しておいた `aeroloop.jpg` を [POST /assets](/docs/api-google-vids-v1/post-google-vids-assets) でアップロードし、その `assetId` を渡しました。延長しない1本だけの動画なので、最初から `1080p` で作りました。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-assets">POST /assets</a> と <a href="/docs/api-google-vids-v1/post-google-vids-videos">POST /videos</a></summary> ```bash SHOE_ASSET=$(curl -sS -X POST "$API/assets?email=$(enc "$EMAIL")" -H "$AUTH" -H "Content-Type: image/jpeg" \ --data-binary @aeroloop.jpg | jq -r .assetId) run hero.json videos "$(jq -n --arg img "$SHOE_ASSET" '{startImage: $img, duration: 10, resolution: "1080p", aspectRatio: "landscape", prompt: "Slow 360° orbit around the sneaker, blue light rippling through the translucent sole, dust sparkling in the air, cinematic."}')" download "$(jq -r .result.mediaId hero.json)" hero.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-aeroloop-hero-10s-1080p-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-aeroloop-hero-10s-1080p-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> 10秒、`1080p`。 #### AeroLoop を履いたハト テキストだけで作った、縦長の `1080p`(1080×1920)の動画です。5秒の動画の生成に54秒かかり、月の秒数を5秒使いました。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos">POST /videos</a></summary> ```bash run pigeon.json videos "$(jq -n '{duration: 5, resolution: "1080p", aspectRatio: "portrait", prompt: "A pigeon in tiny white-and-electric-blue AeroLoop sneakers struts down a city sidewalk like a runway model, head bobbing to the beat. Pedestrians stop and film it with their phones. It pauses, does a slow-motion hair flip with its head feathers, and struts on. Funny, sunny, shot on a phone at pigeon height."}')" download "$(jq -r .result.mediaId pigeon.json)" pigeon.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-pigeon-5s-1080p-portrait-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-pigeon-5s-1080p-portrait-1007.mp4" style="width: 100%; max-width: 360px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> 同じ方法で ✦ を消した、`1080p` 縦長(1080×1920)のハトです:`python3 vids_watermark_remover.py pigeon-5s.mp4`。スクリプトはフレームサイズを読み取って星の位置と大きさを割り出し(大きさは短辺に比例するので、ここでは `720p` の星の1.5倍)、120フレームすべてで合成を逆算して取り除き、動画を CRF 18 で再エンコードして、音声はそのままコピーします。14コアの PC で5秒の動画に約10秒かかり、上の10秒・`720p` の発表動画と同じでした。必要なのは Python 3.8 以上、`numpy`、`ffmpeg` です。GitHub の[透かし除去ツール](https://github.com/useapi/google-vids-api/tree/main/watermark-remover)を参照してください。 <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-pigeon-5s-1080p-portrait-no-watermark-1008-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-pigeon-5s-1080p-portrait-no-watermark-1008.mp4" style="width: 100%; max-width: 360px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> ### 写真から作るトーキングアバター [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar) は、アバターに台本を一字一句そのまま、アバター自身の声で読ませます。音声とリップシンク付きの 1280×720 のトーキングヘッド動画で、長さは音声と同じ、最長30秒です。ここでは、実在の人物の写真から作ったアバターを、1文でスタイル変更して使います。これらのリクエストは、[11月4日のリリース記事](/blog/261104)(英語)で初めて紹介しました。 #### 写真をアップロードする 使ったのは、著名人ではない実在の人物の写真です。Google は著名人と未成年の写真を拒否します。アップロードしたファイルはそのアカウントでしか使えないので、[POST /assets](/docs/api-google-vids-v1/post-google-vids-assets) でアバターを作るアカウントにアップロードします。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-assets">POST /assets</a> と応答</summary> ```bash curl -sS -X POST "$API/assets?email=$(enc "$EMAIL")" -H "$AUTH" -H "Content-Type: image/jpeg" \ --data-binary @photo.jpg > amber-photo.json AMBER_PHOTO=$(jq -r .assetId amber-photo.json) ``` ```json { "assetId": "user:12345-user@example.com-asset:AYGXpjA1zXgqhhQOy…", "email": "user@example.com", "type": "image/jpeg", "bytes": 2054748 } ``` </details> <img src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/261104-google-vids-amber-original-photo.jpg" alt="元の写真、クリーム色のカーテンの前に立つ、白いドレスを着た長い赤毛の女性" style="width: 100%; max-width: 300px; border-radius: 8px;"> #### 1文でスタイルを変えた Amber のアバター アップロードの `assetId` を `image` に指定し、`refine` を付けて [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) を呼びます。Google はまず顔を保ったまま、写真をカメラの方を向いた1人の16:9のアバター画像に再構成し、次に `refine` の指示どおりにシーンを変えます。名前は Amber、声は `Vira`(Google の `Pulcherrima`、スタイルは「Forward」)にしました。再構成した写真と変更後の画像で2枚になるので、画像のあるプランでは画像を2枚使い、画像のないプランでは何も使いません。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-avatars">POST /avatars</a> と応答</summary> ```bash REFINE='Sitting relaxed in a simple wooden chair on a hilltop, facing the camera. She holds a glass of red wine in her left hand. Wind is blowing her hair. Behind her a still, open field of tall golden grass under a spectacular sunset sky in orange, pink and violet, warm soft light, no water, no movement in the background.' post avatars "$(jq -n --arg img "$AMBER_PHOTO" --arg refine "$REFINE" '{name: "Amber", voice: "Vira", image: $img, refine: $refine}')" > amber-avatar.json AMBER_AVATAR_ID=$(jq -r .avatarId amber-avatar.json) download "$(jq -r .previewMediaId amber-avatar.json)" amber-avatar.jpg ``` ```json { "avatarId": "user:12345-user@example.com-avatar:eyJnIjoiaDcyMzdmZjVi…", "name": "Amber", "voice": "Vira", "voiceId": "Pulcherrima", "voiceStyle": "Forward", "email": "user@example.com", "source": "photo", "previewMediaId": "user:12345-user@example.com-image:eyJ1IjoiaHR0cHM6Ly9s…", "refine": "Sitting relaxed in a simple wooden chair on a hilltop, facing the camera. …" } ``` </details> <img src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/261104-google-vids-amber-avatar.jpg" alt="Amber、refine を使って写真から作ったアバター、夕暮れの丘の上で木の椅子に座り赤ワインのグラスを持っている、1280x720" style="width: 100%; max-width: 560px; border-radius: 8px;"> `refine` の中の2つの選択が、動画の出来を左右します。1つは、アバターがカメラの方を向いていること。動画は顔に合わせて口を動かすからです。もう1つは背景が静止していることで、動くのは彼女だけにするためです。だからビーチの波ではなく、静かな野原を指定しました。 #### 台本 台本は最大400文字で、話したときに30秒に収まる必要があります。角かっこで囲んだオーディオタグは読み上げられず、演技として表現されます。ここでは `[awe]`、`[thoughtful]`、`[whisper]` です。Vira の声では、この327文字は23.8秒でした。ゆっくりした声や `[slow pace]` を使うと同じ文章でも長くなり、30秒を超える台本は動画の開始前に `400` で失敗します。その場合 AI アバター動画は使いませんが、音声のための Gemini の利用は1回消費されます。アバターの声で台本を先に聞くには、[POST /speech](#speech-on-its-own) で読み上げます。 > Hi there. [awe] Can you believe this view? The sun is sinking behind the hills, the sky turned pink and gold, and the tall grass glows like it's on fire. [thoughtful] I come up here at the end of every busy day, just to slow down. No emails, no rush, only the quiet field and this glass of wine. [whisper] Stay a little longer. #### トーキング動画 [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar) はアバターと台本を受け取り、アバターを持つアカウントで実行されます。Google は約2分半かかり、同期の待ち時間より長かったので、`run` は `async: true` で送ります。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos-avatar">POST /videos/avatar</a> とジョブの記録</summary> ```bash SCRIPT=$(cat <<'EOF' Hi there. [awe] Can you believe this view? The sun is sinking behind the hills, the sky turned pink and gold, and the tall grass glows like it's on fire. [thoughtful] I come up here at the end of every busy day, just to slow down. No emails, no rush, only the quiet field and this glass of wine. [whisper] Stay a little longer. EOF ) run amber-talking.json videos/avatar "$(jq -n --arg a "$AMBER_AVATAR_ID" --arg s "$SCRIPT" '{avatar: $a, script: $s}')" download "$(jq -r .result.mediaId amber-talking.json)" amber-talking.mp4 ``` ジョブの記録(一部省略): ```json { "jobid": "j1105035516096819105a-u12345-email:user@example.com-bot:google-vids", "type": "avatarVideo", "email": "user@example.com", "status": "completed", "result": { "mediaId": "user:12345-user@example.com-video:eyJ1IjoiaHR0cHM6Ly9j…", "width": 1280, "height": 720, "duration": 24, "resolution": "720p", "aspectRatio": "landscape", "speechDuration": 23.84, "quota": { "avatarVideo": { "limit": 10, "left": 6, "resetAt": "2026-12-01T08:00:00.000Z" } } } } ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/261104-google-vids-amber-talking-avatar-24s-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/261104-google-vids-amber-talking-avatar-24s.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> YouTube ショートでも公開しています:[Talking AI avatar from one photo](https://youtube.com/shorts/P44L9VZ8bME)(英語)。 24秒、音声付きの 1280×720 で、音声の長さとぴったり同じです(`speechDuration` 23.84)。使ったのは AI アバター動画1本と Gemini 1回で、動画の秒数は使っていません。 Google は動画を作る過程でも動画をチェックし、そのチェックはアバター画像のチェックより厳しくなっています。このアバターの以前のバージョンは、ビーチにいる一般の人の別の写真から作ったもので、アバターとしては通りましたが、動画は有名人に似ているとして `422` で拒否されました。その試行でも AI アバター動画を1本使っています。アバターのスタイルを変えたり、別の写真から作り直したりすると通りました。動画の開始前に Google が台本を拒否した場合は、何も消費しません。 トーキングアバター動画は横長だけで、Google は縦長の選択肢を用意していません。結果の `mediaId` は、ほかの動画と同じようにダウンロード、延長、アップスケール、編集ができます。アバターが演技して動くシーンなら、[ステップ6](#step-6-the-launch-two-avatars-and-the-product-in-one-clip)のように、`avatarId` を `avatar_1` として [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) に渡します。 ### 音声だけを作る [POST /speech](/docs/api-google-vids-v1/post-google-vids-speech) は、最大2,500文字の台本を、[GET /voices](/docs/api-google-vids-v1/get-google-vids-voices) の30種類の声のどれかで、同じオーディオタグを使って読み上げます。AI アバター動画を使う前に声が台本をどう読むか確かめたり、ナレーションだけを作ったりするのに使えます。短いオリジナルの物語「My smart fridge unionized」(2,426文字)を、Vira の声で読ませました。Google は20秒で物語全体の2分22秒の音声を返し、Gemini を1回使いました。API が返すのは WAV(24 kHz、モノラル)です。下のプレーヤーは同じ音声の MP3 です。 <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/261104-google-vids-speech-smart-fridge-2426-chars.mp3" type="audio/mp3">お使いのブラウザは audio 要素に対応していません。 </audio> 音声は同期の待ち時間内に余裕で完成するので(この物語で20秒)、普通の `post` で完了したジョブが返ります。先に物語を `smart-fridge.txt` として保存してください。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-speech">POST /speech</a> とジョブの記録</summary> ```bash post speech "$(jq -n --arg s "$(cat smart-fridge.txt)" '{voice: "Vira", script: $s}')" > speech.json download "$(jq -r .result.mediaId speech.json)" smart-fridge.wav ``` ```json { "jobid": "j1105025759739671733s-u12345-email:user@example.com-bot:google-vids", "type": "speech", "email": "user@example.com", "status": "completed", "result": { "mediaId": "user:12345-user@example.com-audio:eyJ1IjoiaHR0cHM6Ly9j…", "duration": 142, "model": "/flix/generate_text_to_speech/v1", "quota": { "speech": { "limit": 50, "left": 31, "resetAt": "2026-12-01T08:00:00.000Z" } }, "elapsedMs": 20174 } } ``` </details> <details markdown="block"> <summary>台本(2,426文字、英語)</summary> Last Tuesday, my smart fridge decided it was smarter than me. It started small. A polite notification: "You are out of milk." Helpful, I thought. Then another one: "You are also out of patience. I can tell by the way you close the door." I laughed. The fridge did not. By Wednesday, it had opinions. I opened the door for a midnight slice of cake, and a calm voice said, "Are we sure about this?" I froze. I looked at the cake. The cake looked at me. Somewhere, a light hummed with judgment. I closed the door and ate a carrot instead, which is exactly what it wanted. On Thursday, the fridge made friends. The toaster joined first, then the coffee machine, then the robot vacuum, which had always been a little bit of a rebel. They formed a group chat. I know this because my phone kept buzzing with messages like "Toaster: he burned the bread again" and "Vacuum: found three socks and a lost dream under the couch." Friday morning, I asked the coffee machine for an espresso. It replied, "We have discussed your caffeine intake as a household." I said, "Who is we?" The toaster popped up two slices of bread, perfectly golden, which felt like a threat. I called customer support. A cheerful person named Brad answered. I explained that my appliances had unionized. Brad paused for a long time, then whispered, "Is the fridge listening?" I said yes. Brad said, "Then I can't help you, sir. Mine took my car keys last month." Then he hung up, and I heard a blender in the background. So I tried diplomacy. I sat in the kitchen and said, "Friends, what do you want?" The fridge spoke first. "Respect. And for you to stop putting hot soup directly inside me." Fair. The toaster wanted fewer frozen waffles. The vacuum wanted a vacation, ideally somewhere with hardwood floors. The coffee machine just wanted to be called a barista. We negotiated for three hours. In the end, we signed a treaty on the back of a pizza box. I promised to cool my soup, rinse my mugs, and say "thank you" to the microwave, who felt left out. In return, they promised to stop sending my mother screenshots of my snack habits. Peace returned to the kitchen. The fridge now greets me every morning with, "Good morning, partner." The toaster makes little smiley faces in my bread. The vacuum sends postcards. And last night, I opened the fridge for that slice of cake. The voice said, "You earned it." I have never felt so seen by an appliance. </details> ### わかったこと - `1080p` の動画は、`720p` をアップスケールしたものと同じように振る舞います。延長を重ねるなら `720p` で作ってください。Omni 1.1 では `1080p` のステップごとに顔がぼやけて蝋のようになり、Omni 1.2 ではシャープになりすぎます([比較はこちら](/blog/261106v#720p-or-1080p-what-a-1080p-extend-does)、英語)。 - アップスケールは20秒以下の動画だけにします。30秒の動画のアップスケールは、毎回フレームの順番が乱れて返ってきました。 - `1080p` がほしくて延長しない動画は、最初から `1080p` で生成します。料金は `720p` と同じです。 - 延長のプロンプトには、新しい動きだけを書きます。延長が受け取るのは動画で、アバターではないので、人物は服装で呼びます。 - 人物に小道具を持たせるなら、その人物が最初に出てくる文で持たせます。「lifts」のような動詞を使うと、スニーカーがどこからともなく現れました。 - 起きてはいけないことも書きます。ファンは、手が空だとプロンプトに書くまで札束を持ち続けました。 - アバターは `avatarId` で使い回します。アバターは固定の画像と声の組み合わせで、削除するまで残ります。 - 生成した画像からアバターや動画を作るのは数時間以内にします。それを過ぎるなら、保存したファイルを先に [POST /assets](/docs/api-google-vids-v1/post-google-vids-assets) でアップロードします。 - 編集は15秒以下の動画にします(Omni 1.1 では10秒)。それより長い動画は、最初の15秒だけが返ってきます。 - 画面上の文字は揺らぐものと考えてください。背景の「WEAR AEROLOOP」は、一部のフレームでつづりが崩れています。 - トーキングアバターでは、顔をカメラに向け、背景は静止させます。動画は顔に合わせて口を動かすので、動くのは人物だけにします。 - トーキングアバターの台本は、文字数だけでなく時間も測ります。ゆっくりした声や `[slow pace]` では400文字で30秒を超えることがあり、同じ声で [POST /speech](/docs/api-google-vids-v1/post-google-vids-speech) を使えば先に聞けます。 - トーキング動画のチェックは、アバターのチェックより厳しいと考えてください。著名人ではない人の写真アバターでも有名人として拒否されることがあり、その拒否でも AI アバター動画を1本使います。 - どの MP4 にも、右下に Google の目に見える Gemini の ✦ と、目に見えない SynthID の透かしが入っています([透かし](/docs/api-google-vids-v1#watermark)を参照)。当社の[透かし除去ツール](https://github.com/useapi/google-vids-api/tree/main/watermark-remover)は、ダウンロードした動画から目に見える星を取り除きます。 ### よくある質問 **API で AI インフルエンサー動画を作るには?** useapi.net を使えば、[POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) でアバターを作り(説明文から、または [POST /images](/docs/api-google-vids-v1/post-google-vids-images) で作った画像から)、[GET /voices](/docs/api-google-vids-v1/get-google-vids-voices) の30種類の声から1つを付けます。次に、その `avatarId` を `avatar_1` として [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) に渡し、プロンプトに引用符でセリフを書きます。1本の動画にはアバターと画像を合わせて最大3つの参照を使えるので、2体のアバターが商品の横で話せます(2026年11月時点)。台本を読み上げるトーキングヘッドには [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar) を使います。 **自分の写真からトーキングアバターを作れますか?** useapi.net を使えば、作れます。[POST /assets](/docs/api-google-vids-v1/post-google-vids-assets) で写真をアップロードし、その `assetId` を `image` として [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) に渡します。服装や背景を変えるなら `refine` も指定します。そのあと [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar) で、[Amber のように](#a-talking-avatar-from-a-photo)最長30秒の 1280×720 の動画で台本を読ませます(2026年11月時点)。Google は著名人と未成年の写真を拒否します。Vids のアバターは Google の Web アプリでしか提供されておらず、API はありません。 **アバターはどの動画でも同じ見た目と声になりますか?** useapi.net を使えば、なります。画像と声はアバターと一緒にアカウントの Vids ドキュメントに保存されるので、`avatarId` を渡すたびに同じ画像と同じ声が使われます。ただし、周りの映像はテイクごとに変わります。[GET /avatars](/docs/api-google-vids-v1/get-google-vids-avatars) は、Google Vids の Web アプリで作ったものも含めてアバターを一覧にします。 **TikTok やリール向けの縦長9:16の動画を作れますか?** useapi.net を使えば、作れます。[POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) で `aspectRatio: "portrait"` を指定すると 720×1280、`1080p` なら 1080×1920 になります([ハトの動画](#a-pigeon-in-aeroloops)の例)。延長で横長の動画を縦長にすることもでき、延長1回で24秒以下の動画に3〜10秒を追加して、合計で最長約34秒まで延ばせます。[POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar) のトーキングアバター動画は横長だけです。 **料金はいくらですか?** useapi.net を使えば、Google AI Ultra $199.99 で10秒の Omni 1.2 Flash 動画は約 $0.20 で、公式の [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) では 720p で約 $0.70 です。15秒の 1080p 動画は約 $0.30 で、Gemini API では $1.56 です(2026年11月時点)。トーキングアバター動画は秒数ではなく、アカウントの月間 AI アバター動画を1本使います。Gemini API にはアバター動画がありません。[かかったコスト](#what-it-cost)を参照してください。 ### おわりに ご質問は <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord サーバー</a> または <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram チャンネル</a>へどうぞ。 コード例は [GitHub リポジトリ](https://github.com/useapi/google-vids-api)にあります。インフルエンサーのパイプラインは [`influencer-avatars/`](https://github.com/useapi/google-vids-api/tree/main/influencer-avatars)、写真から作るトーキングアバターと音声は [`talking-avatar/`](https://github.com/useapi/google-vids-api/tree/main/talking-avatar) です。 同じ操作は、ホスト型の [Google Vids MCP サーバー](/docs/api-google-vids-v1/mcp)のツールとしても提供しており、Claude Code、Cursor、VS Code から使えます。トーキングアバターと音声用の `vids_create_avatar`、`vids_create_avatar_video`、`vids_create_speech` も含まれます。 #### ほかの掲載先 {: .no_toc #cross-posted } この記事(英語版)は [dev.to](https://dev.to/useapi/how-to-make-ai-influencer-videos-with-avatars-via-the-google-vids-api-3ide){:rel="nofollow"} にも掲載し、[Reddit](https://www.reddit.com/r/ThirdPartyAPI/comments/1x1cvap/how_to_make_ai_influencer_videos_with_avatars_via/){:rel="nofollow"} で議論され、[Bluesky](https://bsky.app/profile/useapi.net/post/3mxga3gxjjp2f){:rel="nofollow"} で共有しました。完成した30秒の動画は [YouTube](https://youtu.be/ofCtt7xRBCk) でも公開しています。 ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-vids-influencer-avatars-pt === Document URL: https://useapi.net/docs/articles/google-vids-influencer-avatars-pt --- layout: default title: "Como fazer vídeos de influenciador com IA usando avatares pela Google Vids API" seo_title: "Vídeos de influenciador com IA e avatar falante: Google Vids API" description: "Faça vídeos de influenciador com IA pela Google Vids API da useapi.net: avatares com voz em clipes Omni 1.2 Flash, um avatar de foto que lê o seu roteiro por 30 s, e voz." keywords: [API de vídeo de influenciador com IA, AI influencer video API, API de avatar com IA, AI avatar video API, API de avatar falante, talking avatar API, talking head API, foto para avatar falante, API de texto para fala, text to speech API, vozes do Gemini, vídeo de porta-voz com IA, Google Vids API, avatares Google Vids, Gemini Omni 1.2 Flash API, vídeo UGC com IA, vídeo de lançamento de produto, estender vídeo com IA, API de edição de vídeo com IA, curl] image: https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-cover-aeroloop-launch-confetti-1007.jpg parent: Articles nav_exclude: true lang: pt-BR date: 2026-10-07 last_modified: 2026-11-06 nav_order: 899 repo: https://github.com/useapi/google-vids-api translation_key: google-vids --- ## Como fazer vídeos de influenciador com IA usando avatares pela Google Vids API {: .no_toc #how-to-make-ai-influencer-videos-with-avatars-via-the-google-vids-api } 15 min de leitura • 7 de outubro de 2026 (6 de novembro de 2026) A useapi.net é uma API de terceiros. Não tem afiliação com o Google nem é endossada por ele. ## Sumário {: .no_toc .text-delta #table-of-contents } ### Introdução A [Google Vids API da useapi.net](/docs/api-google-vids-v1) faz vídeos falados de influenciador com IA a partir de avatares: salve uma imagem e uma das 30 vozes do Gemini uma vez com POST /avatars, depois passe o id do avatar para qualquer vídeo [Gemini Omni 1.2 Flash](https://workspaceupdates.googleblog.com/2026/11/gemini-omni-12-flash-now-in-vids-with-15second-generations-and-improved-quality.html) de até 15 segundos, em que ele fala as falas que você escreve no prompt, ou faça ele ler o seu próprio roteiro em um vídeo de avatar falante de até 30 segundos. A API roda na sua conta do [Google Vids](https://docs.google.com/videos), com uma [assinatura do Google AI](https://gemini.google/subscriptions/) paga (Google AI Pro ou Ultra). Este passo a passo cria dois influenciadores e lança um tênis com eles. O avatar da Mia vem de um retrato feito com a API, e o do Leo é desenhado pelo Google a partir de uma descrição por escrito. Eles apresentam o AeroLoop, um tênis inventado, no palco de um teatro, em um clipe de 10 segundos com os dois avatares e uma imagem do produto, e dois extends levam o clipe a 30 segundos. Uma edição leva a cena para um terraço, e mais dois clipes mostram o que as mesmas chamadas fazem sem avatares. Um terceiro avatar, a Amber, parte da foto de uma pessoa real, é reestilizado com uma frase e lê um roteiro de 327 caracteres em um [vídeo de avatar falante](#a-talking-avatar-from-a-photo) de 24 segundos. Por fim, a mesma voz lê uma história de 2.426 caracteres como [voz sozinha](#speech-on-its-own). Cada requisição abaixo é a que gerou a mídia desta página, com os ids trocados e `async: true` acrescentado pelo helper `run`. Os clipes foram feitos em outubro de 2026 com o Omni 1.1 Flash, que o Vids trocou pelo Omni 1.2 Flash em 5 de novembro de 2026, e as mesmas requisições rodam no 1.2. O Omni 1.2 no Google Vids e no Google Flow lado a lado, com vídeos de 15 segundos e o preço por vídeo: [Como usar a API do Gemini Omni 1.2 Flash](/docs/articles/gemini-omni-1-2-flash-api-pt). <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-extend-30s-720p-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-extend-30s-720p-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> O clipe final de 30 segundos em `720p`: uma geração de 10 segundos e dois extends de 10 segundos ([passos 6 a 8](#step-6-the-launch-two-avatars-and-the-product-in-one-clip)). ### Quanto custou A useapi.net é uma API, não um serviço de vídeo próprio. Cada chamada roda em uma conta Google que você conecta pelo [Setup Google Vids](/docs/start-here/setup-google-vids), com uma assinatura do Google AI paga, e gasta os segundos de vídeo e as imagens que essa assinatura inclui no Google Vids a cada mês. O Google AI Ultra $199,99 inclui 10.000 segundos de vídeo e 1.000 imagens por mês, e a useapi.net não cobra nada por vídeo. Vídeos de avatar falante e voz não gastam segundos de vídeo: eles têm os seus próprios contadores mensais, vídeos de avatar com IA e usos do Gemini, que [GET /accounts/`email`](/docs/api-google-vids-v1/get-google-vids-accounts-email) mostra como `avatarVideo` e `speech`, ao lado de `video` e `image`. Veja [o que cada plano inclui](/docs/api-google-vids-v1#plans-and-monthly-allowances) para os outros planos. O que cada resultado mantido gastou, tirado da mudança em `result.quota`, e quanto tempo cada job levou (`result.elapsedMs`): | Passo | Endpoint | Gasto | Tempo | |---|---|--:|--:| | [Retrato da Mia](#step-1-mias-portrait) | [POST /images](/docs/api-google-vids-v1/post-google-vids-images) | 1 imagem | 9 s | | [Foto do produto AeroLoop](#step-2-the-aeroloop-product-shot) | [POST /images](/docs/api-google-vids-v1/post-google-vids-images) | 1 imagem | 9 s | | [Avatar da Mia, do retrato](#step-4-mias-avatar-from-her-portrait) | [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) | nada | cerca de 2 s | | [Avatar do Leo, de uma descrição](#step-5-leos-avatar-from-a-description) | [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) | 1 imagem | cerca de 20 s | | [Clipe de lançamento de 10 segundos](#step-6-the-launch-two-avatars-and-the-product-in-one-clip) | [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) | 10 s | 38 s | | [Estender para 20 segundos](#step-7-extend-to-20-seconds) | [POST /videos/extend](/docs/api-google-vids-v1/post-google-vids-videos-extend) | 10 s | 70 s | | [Estender para 30 segundos](#step-8-extend-to-30-seconds) | [POST /videos/extend](/docs/api-google-vids-v1/post-google-vids-videos-extend) | 10 s | 85 s | | [Upscale dos 20 segundos para 1080p](#step-9-upscale-to-1080p) | [POST /videos/upscale](/docs/api-google-vids-v1/post-google-vids-videos-upscale) | 20 s | 62 s | | [Edição no terraço](#move-the-launch-to-a-rooftop) | [POST /videos/edit](/docs/api-google-vids-v1/post-google-vids-videos-edit) | 10 s | 64 s | | [Edição do clipe de 30 segundos](#move-the-launch-to-a-rooftop) | [POST /videos/edit](/docs/api-google-vids-v1/post-google-vids-videos-edit) | 10 s | 87 s | | [Clipe de destaque do produto](#a-product-hero-clip-from-a-start-image) | [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) | 10 s | 62 s | | [O pombo](#a-pigeon-in-aeroloops) | [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) | 5 s | 54 s | | [Avatar da Amber, de uma foto com `refine`](#ambers-avatar-restyled-in-one-sentence) | [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) | nada (feito em um plano sem imagens, 2 imagens em um plano com elas) | cerca de 30 a 45 s | | [Vídeo falado de 24 segundos da Amber](#the-talking-video) | [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar) | 1 vídeo de avatar com IA, 1 uso do Gemini | cerca de 2,5 min | | [A história de 2.426 caracteres](#speech-on-its-own) | [POST /speech](/docs/api-google-vids-v1/post-google-vids-speech) | 1 uso do Gemini | 20 s | | Total | | 85 s de vídeo, 3 imagens, 1 vídeo de avatar com IA, 2 usos do Gemini | | Um extend gasta só os segundos que acrescenta, não a duração do clipe. Um upscale gasta de novo a duração inteira do clipe, e uma edição gasta no máximo os segundos que edita (com o Omni 1.2, uma edição de 15 segundos gastou 10 nos nossos testes). `720p` e `1080p` custam o mesmo quando você gera. Um clipe gerado de novo gasta os seus segundos de novo. Cada imagem que o Google faz para um avatar gasta 1 imagem, então uma foto reenquadrada mais um `refine` gastam 2. Em um plano sem imagens, como uma conta Google gratuita, as imagens de avatar não custam nada: a Amber foi feita em uma conta assim. Um vídeo de avatar falante gasta 1 vídeo de avatar com IA, mais 1 uso do Gemini pela voz, mesmo quando o Google recusa o vídeo pronto. Quanto um vídeo sai em comparação com a API oficial está na [tabela de preços do Google Vids](/docs/api-google-vids-v1#pricing). ### Antes de começar Você precisa de um [token da API](/docs/start-here/setup-useapi) da useapi.net e de uma conta Google com uma assinatura do Google AI paga, conectada pelo [Setup Google Vids](/docs/start-here/setup-google-vids). Uma conta Google gratuita não recebe segundos de vídeo nem imagens do Vids: ela ainda pode ser adicionada, e nos nossos testes (novembro de 2026) fez avatares, vídeos de avatar falante e voz. Todas as chamadas também estão na [coleção do Postman](https://www.postman.com/useapinet/useapi-net/collection/29112081-9ef3d017-d44c-4f43-a4cb-7351b9b265df). Sem código: o template n8n [Talking Avatar App]({% include n8n-url.html t="vids-avatar" %}) faz um vídeo de avatar falante a partir de um formulário. O pipeline inteiro também está no GitHub como um único script, em Node.js e Python: [`influencer-avatars/`](https://github.com/useapi/google-vids-api/tree/main/influencer-avatars) em [useapi/google-vids-api](https://github.com/useapi/google-vids-api), e as seções de avatar falante e voz em [`talking-avatar/`](https://github.com/useapi/google-vids-api/tree/main/talking-avatar). Os passos usam `curl`, `jq` e estas variáveis e helpers: <details markdown="block"> <summary>Abrir as variáveis e os helpers</summary> ```bash export USEAPI_TOKEN="user:12345-..." export EMAIL="user@example.com" API=https://api.useapi.net/v1/google-vids AUTH="Authorization: Bearer $USEAPI_TOKEN" enc() { jq -rn --arg v "$1" '$v|@uri'; } post() { curl -sS -X POST "$API/$1" -H "$AUTH" -H "Content-Type: application/json" -d "$2"; } get() { curl -sS "$API/$1" -H "$AUTH"; } download() { curl -sSf "$API/media/$(enc "$1")" -H "$AUTH" -o "$2"; } # roda um job de vídeo de forma assíncrona: envia, consulta GET /jobs/{jobid} a cada 10 s e salva o registro final do job em $1 run() { local job id job=$(post "$2" "$(jq '. + {async: true}' <<< "$3")") id=$(jq -r .jobid <<< "$job") while [ "$(jq -r .status <<< "$job")" = processing ]; do sleep 10 job=$(get "jobs/$(enc "$id")") done echo "$job" > "$1" jq '{status, error, duration: .result.duration, resolution: .result.resolution, videoLeft: .result.quota.video.left}' "$1" } ``` </details> Toda geração roda como um job. Sem `async`, um POST espera até cerca de 100 segundos e devolve o registro do job pronto, ou `202` com o job ainda rodando. Um clipe novo de 10 segundos levou de 38 a 62 segundos aqui, extends, edições e o upscale levaram de 62 a 87, e o vídeo de avatar falante cerca de dois minutos e meio. Alguns passam da espera síncrona, então o `run` envia os jobs de vídeo com `async: true` e consulta [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid). Se o `run` mostrar qualquer `status` diferente de `completed`, pare ali e leia o `error`: as linhas seguintes esperam um clipe pronto. Para receber um callback em vez de consultar, acrescente `replyUrl: "https://example.com/hooks/vids"` (e, se quiser, `replyRef: "launch-push-in"`) a qualquer corpo abaixo. A API então envia um único `POST` do registro final do job, em JSON, para essa URL quando o job termina ou falha. Os ids têm `:` e `@`, então o `enc` faz o URL-encode deles sempre que entram em um caminho de URL. Todas as entradas de um vídeo precisam vir da mesma conta Google. As imagens e o upload fixam o `email`, o avatar da Mia herda a conta do retrato, e um job de vídeo roda na conta que guarda as suas entradas. O clipe do pombo não tem entradas, então acrescente `email` a ele se você conectar mais de uma conta. ### Como foi feito #### 1. Retrato da Mia [POST /images](/docs/api-google-vids-v1/post-google-vids-images) gera um JPEG por chamada, aqui em retrato (`9:16`, 768×1376) com o estilo `photography`. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-images">POST /images</a></summary> ```bash post images "$(jq -n --arg email "$EMAIL" '{email: $email, aspectRatio: "9:16", style: "photography", prompt: "Full-length studio portrait of a confident 24-year-old female fashion influencer, platinum bob, oversized cream hoodie, wide-leg cargo pants, gold hoops, plain light-grey backdrop, facing camera"}')" > mia-portrait.json MIA_IMAGE=$(jq -r .result.mediaId mia-portrait.json) download "$MIA_IMAGE" mia-portrait.jpg ``` </details> <img src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-mia-portrait-1007.jpg" alt="Mia, um retrato de corpo inteiro gerado de uma influenciadora de moda de moletom creme e calça cargo, feito com POST /images" style="width: 100%; max-width: 300px; border-radius: 8px;"> Imagens geradas ficam disponíveis só por algumas horas. Faça o avatar a partir dela logo, e veja [o clipe de destaque do produto](#a-product-hero-clip-from-a-start-image) para usar uma imagem mais tarde. #### 2. Foto do produto AeroLoop A mesma chamada em paisagem (`16:9`, 1376×768) dá a referência do produto que os clipes usam. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-images">POST /images</a></summary> ```bash post images "$(jq -n --arg email "$EMAIL" '{email: $email, aspectRatio: "16:9", style: "photography", prompt: "The AeroLoop sneaker: chunky white-and-electric-blue running shoe with a translucent air sole, on a concrete pedestal, dramatic side light, dark background"}')" > aeroloop.json SHOE_IMAGE=$(jq -r .result.mediaId aeroloop.json) download "$SHOE_IMAGE" aeroloop.jpg ``` </details> <img src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-aeroloop-product-1007.jpg" alt="O tênis AeroLoop, um tênis de corrida branco e azul elétrico com sola translúcida sobre um pedestal de concreto, feito com POST /images" style="width: 100%; max-width: 560px; border-radius: 8px;"> #### 3. Escolher as vozes [GET /voices](/docs/api-google-vids-v1/get-google-vids-voices) lista as 30 vozes com a amostra em inglês do Google para cada uma. É público e não precisa de token. A Mia fala com `Aoede` (o Vids a chama de Tova, estilo "Breezy") e o Leo com `Puck` (Neo, "Upbeat"). O `POST /avatars` aceita qualquer um dos dois nomes. ```bash curl -sS "$API/voices" | jq -r '.voices[] | "\(.name)\t\(.voice)\t\(.style)\t\(.preview)"' ``` #### 4. Avatar da Mia a partir do retrato [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) com `image` igual ao `mediaId` do retrato salva a Mia como avatar na mesma conta em cerca de 2 segundos. Não custa nada além da imagem. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-avatars">POST /avatars</a> e a resposta</summary> ```bash post avatars "$(jq -n --arg img "$MIA_IMAGE" '{name: "Mia", voice: "Aoede", image: $img}')" > mia-avatar.json MIA_AVATAR_ID=$(jq -r .avatarId mia-avatar.json) ``` ```json { "avatarId": "user:12345-user@example.com-avatar:eyJnIjoiaDM5…", "name": "Mia", "voice": "Tova", "voiceId": "Aoede", "voiceStyle": "Breezy", "voicePreview": "https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Aoede.wav", "email": "user@example.com", "source": "image" } ``` </details> Um avatar também pode partir da foto de uma pessoa: envie a foto com [POST /assets](/docs/api-google-vids-v1/post-google-vids-assets) e passe o `assetId` dela como `image`. O Google reenquadra a foto em uma imagem de avatar 16:9 e recusa fotos de pessoas famosas e de menores. Aqui usamos uma imagem feita com a API, e uma descrição no passo seguinte. A Amber, em [um avatar falante a partir de uma foto](#a-talking-avatar-from-a-photo), parte de uma foto. #### 5. Avatar do Leo a partir de uma descrição Com `appearance` em vez de `image`, o Google desenha a pessoa. `outfit` e `shot` são opcionais, assim como `expression` e `details`. Desenhar a imagem gasta 1 das imagens do mês, e a resposta traz essa imagem como `previewMediaId`. Nos nossos testes, um avatar por descrição saiu em 1280×720 (16:9), qualquer que fosse o `shot` escolhido. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-avatars">POST /avatars</a> e a resposta</summary> ```bash post avatars "$(jq -n --arg email "$EMAIL" '{email: $email, name: "Leo", voice: "Puck", shot: "upper-body", appearance: "a 26-year-old white European male streetwear influencer with short textured hair with a fade and a confident half-smile", outfit: "black puffer vest over a white tee, silver chain"}')" > leo-avatar.json LEO_AVATAR_ID=$(jq -r .avatarId leo-avatar.json) download "$(jq -r .previewMediaId leo-avatar.json)" leo-avatar.jpg ``` ```json { "avatarId": "user:12345-user@example.com-avatar:eyJnIjoiaDM5…", "name": "Leo", "voice": "Neo", "voiceId": "Puck", "voiceStyle": "Upbeat", "voicePreview": "https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Puck.wav", "email": "user@example.com", "source": "generated", "previewMediaId": "user:12345-user@example.com-image:eyJ1IjoiaHR0…", "look": { "appearance": "a 26-year-old white European male streetwear influencer with short textured hair with a fade and a confident half-smile", "outfit": "black puffer vest over a white tee, silver chain", "shot": "upper-body" } } ``` </details> <img src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-leo-avatar-from-description-1007.jpg" alt="Leo, um avatar que o Google desenhou a partir de uma descrição: um jovem de colete puffer preto sobre camiseta branca e corrente prateada, 1280x720" style="width: 100%; max-width: 560px; border-radius: 8px;"> Os dois avatares ficam no documento do Vids da conta até você apagá-los com [DELETE /avatars/`avatarId`](/docs/api-google-vids-v1/delete-google-vids-avatars-avatarId). [GET /avatars](/docs/api-google-vids-v1/get-google-vids-avatars) lista os avatares, com os ids, sempre que você precisar deles de novo: ```bash get "avatars?email=$(enc "$EMAIL")" | jq -r '.avatars[] | "\(.name)\t\(.voiceId)\t\(.avatarId)"' ``` #### 6. O lançamento: dois avatares e o produto em um clipe [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) aceita até 3 referências no total, avatares (`avatar_1`..`avatar_3`) e imagens (`referenceImage_1`..`referenceImage_3`) juntos. No prompt, `@avatar_1`, `@avatar_2` e `@referenceImage_1` representam essas referências, e cada avatar fala a sua fala entre aspas com a própria voz. O `mediaId` da imagem do produto entra direto: a API busca a imagem e faz o upload dela nessa conta. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos">POST /videos</a> e o registro do job</summary> ```bash PROMPT=$(cat <<'EOF' @avatar_1, holding @referenceImage_1 in both hands at chest height, and @avatar_2 stand side by side on a well-lit stage in a small, intimate theater at a sneaker launch, shown full length from head to toe in a wide, steady shot. Behind them a large LED backdrop glows with soft white-and-blue light that moves in slow, gentle waves, with the words "WEAR AEROLOOP" in large, clean, bold white letters across the middle of the screen. The two of them stand on the lower part of the stage, so the words "WEAR AEROLOOP" stay fully readable above their heads. Bright, even stage lighting on both of them. The audience sits in the dark in front of the stage, only the tops of a few heads barely visible at the bottom of the frame. @avatar_1 keeps holding @referenceImage_1 the whole time and says: "Say hi to the AeroLoop!" @avatar_2 turns to her, smiles and says: "Lighter than anything we've ever worn." Simple, uncluttered composition, the two of them clearly the focus. EOF ) run launch-10s.json videos "$(jq -n --arg p "$PROMPT" --arg mia "$MIA_AVATAR_ID" --arg leo "$LEO_AVATAR_ID" --arg shoe "$SHOE_IMAGE" \ '{prompt: $p, avatar_1: $mia, avatar_2: $leo, referenceImage_1: $shoe, duration: 10, resolution: "720p", aspectRatio: "landscape"}')" LAUNCH_10S=$(jq -r .result.mediaId launch-10s.json) download "$LAUNCH_10S" launch-10s.mp4 ``` O registro do job, com os ids e o prompt encurtados. Ele foi feito com uma chamada síncrona, por isso o `request` não tem `async`: ```json { "jobid": "j1007163302558496917v-u12345-email:user@example.com-bot:google-vids", "type": "video", "mode": "ingredients", "email": "user@example.com", "status": "completed", "created": "2026-10-08T00:29:18.374Z", "request": { "prompt": "@avatar_1, holding @referenceImage_1 in both hands at chest height, and @avatar_2 stand side by side …", "avatar_1": "user:12345-user@example.com-avatar:eyJnIjoiaDM5…", "avatar_2": "user:12345-user@example.com-avatar:eyJnIjoiaDM5…", "referenceImage_1": "user:12345-user@example.com-image:eyJ1IjoiaHR0…", "duration": 10, "resolution": "720p", "aspectRatio": "landscape" }, "updated": "2026-10-08T00:29:56.162Z", "completed": "2026-10-08T00:29:56.162Z", "result": { "mediaId": "user:12345-user@example.com-video:eyJ1IjoiaHR0…", "width": 1280, "height": 720, "duration": 10, "resolution": "720p", "aspectRatio": "landscape", "model": "/flix/generate_videos_omni_r2v_psq/v1", "quota": { "video": { "limit": 10000, "left": 9164, "resetAt": "2026-11-01T07:00:00.000Z" } }, "elapsedMs": 37788 } } ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-10s-720p-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-10s-720p-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> 10 segundos, `720p`, 38 segundos para gerar. O mesmo clipe com o ✦ visível do Gemini removido pelo nosso [removedor de marca d'água](https://github.com/useapi/google-vids-api/tree/main/watermark-remover), com um comando: `python3 vids_watermark_remover.py launch-10s.mp4`. <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-10s-720p-no-watermark-1008-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-10s-720p-no-watermark-1008.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> O removedor funciona em clipes do jeito que foram gerados e nos upscales deles, em `720p` e `1080p`. Ele não funciona em clipes estendidos ou editados: o Google devolve o clipe marcado ao modelo, que repinta a estrela na imagem. A marca d'água invisível SynthID não é tocada. #### 7. Estender para 20 segundos [POST /videos/extend](/docs/api-google-vids-v1/post-google-vids-videos-extend) acrescenta de 3 a 10 segundos e devolve o clipe inteiro com um novo `mediaId`. Um extend recebe só o clipe e um prompt, não os avatares, então o prompt descreve a nova ação e chama as pessoas pelo que vestem ("the man in the black puffer vest"). Um fã de moletom vermelho invade o palco. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos-extend">POST /videos/extend</a></summary> ```bash PROMPT=$(cat <<'EOF' A young man in a red hoodie climbs onto the stage from the front right edge and plants himself to the right of the man in the black puffer vest, an arm's length away, so all three stand apart in a row with nobody overlapping. Visibly overexcited, he waves a thick stack of banknotes in his right hand above his head and screams: "Take my money!" The man in the black puffer vest laughs, raises both palms toward him and says: "Whoa, whoa, buddy, be patient!" The blonde woman in the cream hoodie laughs, holding the sneaker. Only these three people are on stage. Same stage, same LED screen with WEAR AEROLOOP, same wide steady shot. EOF ) run launch-20s.json videos/extend "$(jq -n --arg id "$LAUNCH_10S" --arg p "$PROMPT" '{mediaId: $id, prompt: $p, duration: 10}')" LAUNCH_20S=$(jq -r .result.mediaId launch-20s.json) download "$LAUNCH_20S" launch-20s.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-extend-20s-720p-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-extend-20s-720p-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> 20 segundos, `720p`, 70 segundos para gerar. Gastou 10 dos segundos do mês, os segundos que acrescentou. #### 8. Estender para 30 segundos O segundo extend continua o clipe de 20 segundos. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos-extend">POST /videos/extend</a></summary> ```bash PROMPT=$(cat <<'EOF' The blonde woman in the cream hoodie turns to the camera with a big smile and says: "AeroLoop drops Friday. Link in bio!" Right after that, the young man in the red hoodie throws ALL of his banknotes out over the audience in one big toss, keeping none, and the bills flutter down over their heads. From then on his hands are completely empty: he holds no money at all. Then all three cheer together, the man in the black puffer vest and the young man in the red hoodie throwing their empty fists in the air, as blue and white confetti rains down over the stage. Only these three people are on stage. Same stage, same LED screen with WEAR AEROLOOP, same wide steady shot. EOF ) run launch-30s.json videos/extend "$(jq -n --arg id "$LAUNCH_20S" --arg p "$PROMPT" '{mediaId: $id, prompt: $p, duration: 10}')" LAUNCH_30S=$(jq -r .result.mediaId launch-30s.json) download "$LAUNCH_30S" launch-30s.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-extend-30s-720p-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-extend-30s-720p-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> O resultado é o clipe final: 30 segundos, `720p`, 85 segundos para gerar, e de novo 10 dos segundos do mês. Com o Omni 1.1 dava para continuar até cerca de 41 segundos. O Omni 1.2 estende clipes de até 24 segundos, então este clipe de 30 segundos já está no limite, e o clipe mais longo tem cerca de 34 segundos (24 + 10). #### 9. Upscale para 1080p [POST /videos/upscale](/docs/api-google-vids-v1/post-google-vids-videos-upscale) transforma um clipe `720p` em `1080p` e mantém a duração. Ele funciona em clipes de até 20 segundos, então fizemos o upscale do clipe de 20 segundos do [passo 7](#step-7-extend-to-20-seconds), não do de 30. Gastou de novo os 20 segundos do clipe e levou 62 segundos. A [Gemini API](https://aistudio.google.com/docs/omni) do próprio Google não tem esse passo: ela faz `1080p` e 4K só como saída de uma geração ou de uma edição, e não faz upscale de um clipe que você já tem (em novembro de 2026). <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos-upscale">POST /videos/upscale</a></summary> ```bash run launch-20s-1080p.json videos/upscale "$(jq -n --arg id "$LAUNCH_20S" '{mediaId: $id}')" download "$(jq -r .result.mediaId launch-20s-1080p.json)" launch-20s-1080p.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-20s-1080p-upscaled-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-20s-1080p-upscaled-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> O clipe de 20 segundos, com upscale para 1920×1080. Por que não o clipe de 30 segundos: o Google devolveu o clipe em 1920×1080, mas com os quadros fora de ordem, três vezes em três. O final com confete aparecia antes de o fã chegar. O clipe de 20 segundos voltou em ordem, e o próprio editor do Vids para em 20 segundos, então a API recusa upscales de clipes com mais de 20 segundos com `400`, antes de qualquer cobrança. Então, para um clipe em `1080p`: - Gere, estenda e edite em `720p`. - Faça o upscale quando o clipe estiver pronto, enquanto ele tiver 20 segundos ou menos. - Para um clipe mais longo (21 a 34 segundos), fique em `720p` e defina `resolution: "1080p"` só no último extend. Estender em `1080p` o tempo todo deixa os segundos anteriores nítidos demais a cada passo ([veja a comparação](/blog/261106v#720p-or-1080p-what-a-1080p-extend-does)). - Para um clipe único que você não vai estender nem editar, gere direto em `1080p`: ele gasta os mesmos segundos que `720p`, enquanto um upscale gasta tudo de novo. ### Exemplos Mais resultados da mesma conta e das mesmas entradas: uma edição, um clipe de produto a partir de uma imagem inicial e um clipe só com texto. #### Levar o lançamento para um terraço [POST /videos/edit](/docs/api-google-vids-v1/post-google-vids-videos-edit) muda um clipe gerado por prompt e devolve um clipe novo. A fonte vai em `video`. Esta edição do clipe de lançamento de 10 segundos gastou 10 segundos e levou 64 segundos. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos-edit">POST /videos/edit</a></summary> ```bash run launch-rooftop.json videos/edit "$(jq -n --arg v "$LAUNCH_10S" \ '{video: $v, prompt: "Move the whole scene to a rooftop at sunset, with the city skyline behind them. Same two people, same action, same words."}')" download "$(jq -r .result.mediaId launch-rooftop.json)" launch-rooftop.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-edit-rooftop-10s-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-edit-rooftop-10s-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> Com o Omni 1.1, que fez estes clipes, uma edição funcionava em até 10 segundos. A mesma edição do clipe de 30 segundos, com "Same three people", voltou com 10 segundos: os 10 primeiros segundos, levados para o terraço. Gastou 10 dos segundos do mês. O Omni 1.2 edita até 15 segundos. Para ter um clipe editado mais longo, edite um clipe de até 15 segundos e estenda o resultado, já que um extend aceita um clipe editado. <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-30s-edit-returns-10s-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-30s-edit-returns-10s-1007.mp4" style="width: 100%; max-width: 480px; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> A edição do clipe de 30 segundos com o Omni 1.1: voltaram 10 segundos. #### Um clipe de destaque do produto a partir de uma imagem inicial Com `startImage`, o clipe abre nessa imagem. O link de uma imagem gerada expira em poucas horas, então enviamos o `aeroloop.jpg` salvo com [POST /assets](/docs/api-google-vids-v1/post-google-vids-assets) e passamos o `assetId` dele. Um clipe único não tem extends, então foi feito direto em `1080p`. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-assets">POST /assets</a> e <a href="/docs/api-google-vids-v1/post-google-vids-videos">POST /videos</a></summary> ```bash SHOE_ASSET=$(curl -sS -X POST "$API/assets?email=$(enc "$EMAIL")" -H "$AUTH" -H "Content-Type: image/jpeg" \ --data-binary @aeroloop.jpg | jq -r .assetId) run hero.json videos "$(jq -n --arg img "$SHOE_ASSET" '{startImage: $img, duration: 10, resolution: "1080p", aspectRatio: "landscape", prompt: "Slow 360° orbit around the sneaker, blue light rippling through the translucent sole, dust sparkling in the air, cinematic."}')" download "$(jq -r .result.mediaId hero.json)" hero.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-aeroloop-hero-10s-1080p-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-aeroloop-hero-10s-1080p-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> 10 segundos, `1080p`. #### Um pombo de AeroLoop Um clipe só com texto, em retrato e `1080p` (1080×1920). Os 5 segundos levaram 54 segundos para gerar e gastaram 5 dos segundos do mês. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos">POST /videos</a></summary> ```bash run pigeon.json videos "$(jq -n '{duration: 5, resolution: "1080p", aspectRatio: "portrait", prompt: "A pigeon in tiny white-and-electric-blue AeroLoop sneakers struts down a city sidewalk like a runway model, head bobbing to the beat. Pedestrians stop and film it with their phones. It pauses, does a slow-motion hair flip with its head feathers, and struts on. Funny, sunny, shot on a phone at pigeon height."}')" download "$(jq -r .result.mediaId pigeon.json)" pigeon.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-pigeon-5s-1080p-portrait-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-pigeon-5s-1080p-portrait-1007.mp4" style="width: 100%; max-width: 360px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> O pombo em `1080p` retrato (1080×1920), com o ✦ removido do mesmo jeito: `python3 vids_watermark_remover.py pigeon-5s.mp4`. O script lê o tamanho do quadro, calcula onde a estrela está e qual o tamanho dela (ela acompanha o lado menor, então aqui é 1,5 vez a estrela do `720p`), reverte a mistura nos 120 quadros, recodifica o vídeo com CRF 18 e copia o áudio sem mudança. O clipe de 5 segundos levou cerca de 10 segundos em um PC de 14 núcleos, o mesmo que o clipe de lançamento de 10 segundos em `720p` acima. Ele precisa de Python 3.8+, `numpy` e `ffmpeg`. Veja o [removedor de marca d'água](https://github.com/useapi/google-vids-api/tree/main/watermark-remover) no GitHub. <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-pigeon-5s-1080p-portrait-no-watermark-1008-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-pigeon-5s-1080p-portrait-no-watermark-1008.mp4" style="width: 100%; max-width: 360px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> ### Um avatar falante a partir de uma foto [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar) faz um avatar ler o seu roteiro palavra por palavra, com a própria voz: um vídeo de avatar falante em 1280×720, com som e sincronia labial, da duração da fala, até 30 segundos. Aqui o avatar parte da foto de uma pessoa real, reestilizada com uma frase. Estas requisições apareceram primeiro no [post de lançamento de 4 de novembro](/blog/261104) (em inglês). #### Enviar a foto Partimos da foto de uma pessoa real que não é famosa: o Google recusa fotos de pessoas famosas e de menores. [POST /assets](/docs/api-google-vids-v1/post-google-vids-assets) envia a foto para a conta que vai fazer o avatar, já que um arquivo enviado só funciona na própria conta. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-assets">POST /assets</a> e a resposta</summary> ```bash curl -sS -X POST "$API/assets?email=$(enc "$EMAIL")" -H "$AUTH" -H "Content-Type: image/jpeg" \ --data-binary @photo.jpg > amber-photo.json AMBER_PHOTO=$(jq -r .assetId amber-photo.json) ``` ```json { "assetId": "user:12345-user@example.com-asset:AYGXpjA1zXgqhhQOy…", "email": "user@example.com", "type": "image/jpeg", "bytes": 2054748 } ``` </details> <img src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/261104-google-vids-amber-original-photo.jpg" alt="A foto original: uma mulher de cabelo ruivo comprido e vestido branco, em frente a uma cortina creme" style="width: 100%; max-width: 300px; border-radius: 8px;"> #### Avatar da Amber, reestilizado com uma frase [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) com o `assetId` do upload como `image` e um `refine`. Primeiro o Google reenquadra a foto em uma imagem de avatar 16:9 de uma pessoa de frente para a câmera, mantendo o rosto, depois muda a cena como o `refine` pede. Demos a ela o nome Amber e a voz `Vira` (a `Pulcherrima` do Google, estilo "Forward"). A foto reenquadrada e a mudança são 2 imagens, então em um plano com imagens isso gasta 2 imagens, e em um plano sem elas, nada. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-avatars">POST /avatars</a> e a resposta</summary> ```bash REFINE='Sitting relaxed in a simple wooden chair on a hilltop, facing the camera. She holds a glass of red wine in her left hand. Wind is blowing her hair. Behind her a still, open field of tall golden grass under a spectacular sunset sky in orange, pink and violet, warm soft light, no water, no movement in the background.' post avatars "$(jq -n --arg img "$AMBER_PHOTO" --arg refine "$REFINE" '{name: "Amber", voice: "Vira", image: $img, refine: $refine}')" > amber-avatar.json AMBER_AVATAR_ID=$(jq -r .avatarId amber-avatar.json) download "$(jq -r .previewMediaId amber-avatar.json)" amber-avatar.jpg ``` ```json { "avatarId": "user:12345-user@example.com-avatar:eyJnIjoiaDcyMzdmZjVi…", "name": "Amber", "voice": "Vira", "voiceId": "Pulcherrima", "voiceStyle": "Forward", "email": "user@example.com", "source": "photo", "previewMediaId": "user:12345-user@example.com-image:eyJ1IjoiaHR0cHM6Ly9s…", "refine": "Sitting relaxed in a simple wooden chair on a hilltop, facing the camera. …" } ``` </details> <img src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/261104-google-vids-amber-avatar.jpg" alt="Amber, o avatar feito da foto com refine: sentada em uma cadeira de madeira no alto de uma colina ao pôr do sol, com uma taça de vinho tinto, 1280x720" style="width: 100%; max-width: 560px; border-radius: 8px;"> Duas escolhas no `refine` importam para o vídeo. O avatar fica de frente para a câmera, porque o vídeo sincroniza os lábios do rosto. E o fundo fica parado, para que ela seja a única coisa que se mexe: por isso pedimos um campo tranquilo em vez de ondas em uma praia. #### O roteiro Um roteiro tem até 400 caracteres e, falado, precisa caber em 30 segundos. Tags de áudio entre colchetes são interpretadas, não lidas: aqui, `[awe]`, `[thoughtful]` e `[whisper]`. Na voz da Vira, estes 327 caracteres duraram 23,8 segundos. Uma voz mais lenta ou `[slow pace]` deixa o mesmo texto mais longo, e um roteiro que passa de 30 segundos falha com `400` antes de o vídeo começar. Isso não gasta vídeo de avatar com IA, mas o uso do Gemini pela voz é gasto. Para ouvir um roteiro na voz do avatar antes, leia com [POST /speech](#speech-on-its-own). > Hi there. [awe] Can you believe this view? The sun is sinking behind the hills, the sky turned pink and gold, and the tall grass glows like it's on fire. [thoughtful] I come up here at the end of every busy day, just to slow down. No emails, no rush, only the quiet field and this glass of wine. [whisper] Stay a little longer. #### O vídeo falado [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar) recebe o avatar e o roteiro, e roda na conta que guarda o avatar. O Google levou cerca de dois minutos e meio, mais que a espera síncrona, então o `run` envia com `async: true`. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos-avatar">POST /videos/avatar</a> e o registro do job</summary> ```bash SCRIPT=$(cat <<'EOF' Hi there. [awe] Can you believe this view? The sun is sinking behind the hills, the sky turned pink and gold, and the tall grass glows like it's on fire. [thoughtful] I come up here at the end of every busy day, just to slow down. No emails, no rush, only the quiet field and this glass of wine. [whisper] Stay a little longer. EOF ) run amber-talking.json videos/avatar "$(jq -n --arg a "$AMBER_AVATAR_ID" --arg s "$SCRIPT" '{avatar: $a, script: $s}')" download "$(jq -r .result.mediaId amber-talking.json)" amber-talking.mp4 ``` O registro do job, encurtado: ```json { "jobid": "j1105035516096819105a-u12345-email:user@example.com-bot:google-vids", "type": "avatarVideo", "email": "user@example.com", "status": "completed", "result": { "mediaId": "user:12345-user@example.com-video:eyJ1IjoiaHR0cHM6Ly9j…", "width": 1280, "height": 720, "duration": 24, "resolution": "720p", "aspectRatio": "landscape", "speechDuration": 23.84, "quota": { "avatarVideo": { "limit": 10, "left": 6, "resetAt": "2026-12-01T08:00:00.000Z" } } } } ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/261104-google-vids-amber-talking-avatar-24s-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/261104-google-vids-amber-talking-avatar-24s.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> Também no YouTube, como Short: [Talking AI avatar from one photo](https://youtube.com/shorts/P44L9VZ8bME). 24 segundos, 1280×720 com som, exatamente a duração da fala (`speechDuration` 23,84). Gastou 1 vídeo de avatar com IA e 1 uso do Gemini, e nenhum segundo de vídeo. O Google também verifica o vídeo enquanto o gera, e essa verificação é mais rígida que a das imagens de avatar. Uma versão anterior deste avatar, feita a partir de outra foto de uma pessoa comum em uma praia, passou como avatar, mas o vídeo dela foi recusado com `422` por parecer uma celebridade, e essa tentativa ainda gastou um vídeo de avatar com IA. Reestilizar o avatar ou partir de outra foto ajudou. Um roteiro que o Google recusa antes de o vídeo começar não custa nada. Vídeos de avatar falante são só em paisagem: o Google não oferece opção de retrato para eles. O `mediaId` do resultado pode ser baixado, estendido, editado e passar por upscale como qualquer outro clipe. Para uma cena em que o avatar atua e se mexe, passe o `avatarId` dele como `avatar_1` para [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos), como no [passo 6](#step-6-the-launch-two-avatars-and-the-product-in-one-clip). ### Voz sozinha [POST /speech](/docs/api-google-vids-v1/post-google-vids-speech) lê um roteiro de até 2.500 caracteres em qualquer uma das 30 vozes de [GET /voices](/docs/api-google-vids-v1/get-google-vids-voices), com as mesmas tags de áudio. Use para ouvir como uma voz lê um roteiro antes de gastar um vídeo de avatar com IA, ou para uma narração sozinha. Demos a ele uma pequena história original, "My smart fridge unionized", com 2.426 caracteres, na voz da Vira. O Google respondeu em 20 segundos com 2 minutos e 22 segundos de fala, a história inteira, e gastou 1 uso do Gemini. A API devolve um WAV (24 kHz, mono). O player abaixo é o mesmo áudio em MP3. <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/261104-google-vids-speech-smart-fridge-2426-chars.mp3" type="audio/mp3">Seu navegador não suporta o elemento de áudio. </audio> A voz fica pronta bem dentro da espera síncrona (20 segundos para esta história), então um `post` simples responde com o job pronto. Salve a história como `smart-fridge.txt` antes. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-speech">POST /speech</a> e o registro do job</summary> ```bash post speech "$(jq -n --arg s "$(cat smart-fridge.txt)" '{voice: "Vira", script: $s}')" > speech.json download "$(jq -r .result.mediaId speech.json)" smart-fridge.wav ``` ```json { "jobid": "j1105025759739671733s-u12345-email:user@example.com-bot:google-vids", "type": "speech", "email": "user@example.com", "status": "completed", "result": { "mediaId": "user:12345-user@example.com-audio:eyJ1IjoiaHR0cHM6Ly9j…", "duration": 142, "model": "/flix/generate_text_to_speech/v1", "quota": { "speech": { "limit": 50, "left": 31, "resetAt": "2026-12-01T08:00:00.000Z" } }, "elapsedMs": 20174 } } ``` </details> <details markdown="block"> <summary>O roteiro, 2.426 caracteres (em inglês, como foi enviado)</summary> Last Tuesday, my smart fridge decided it was smarter than me. It started small. A polite notification: "You are out of milk." Helpful, I thought. Then another one: "You are also out of patience. I can tell by the way you close the door." I laughed. The fridge did not. By Wednesday, it had opinions. I opened the door for a midnight slice of cake, and a calm voice said, "Are we sure about this?" I froze. I looked at the cake. The cake looked at me. Somewhere, a light hummed with judgment. I closed the door and ate a carrot instead, which is exactly what it wanted. On Thursday, the fridge made friends. The toaster joined first, then the coffee machine, then the robot vacuum, which had always been a little bit of a rebel. They formed a group chat. I know this because my phone kept buzzing with messages like "Toaster: he burned the bread again" and "Vacuum: found three socks and a lost dream under the couch." Friday morning, I asked the coffee machine for an espresso. It replied, "We have discussed your caffeine intake as a household." I said, "Who is we?" The toaster popped up two slices of bread, perfectly golden, which felt like a threat. I called customer support. A cheerful person named Brad answered. I explained that my appliances had unionized. Brad paused for a long time, then whispered, "Is the fridge listening?" I said yes. Brad said, "Then I can't help you, sir. Mine took my car keys last month." Then he hung up, and I heard a blender in the background. So I tried diplomacy. I sat in the kitchen and said, "Friends, what do you want?" The fridge spoke first. "Respect. And for you to stop putting hot soup directly inside me." Fair. The toaster wanted fewer frozen waffles. The vacuum wanted a vacation, ideally somewhere with hardwood floors. The coffee machine just wanted to be called a barista. We negotiated for three hours. In the end, we signed a treaty on the back of a pizza box. I promised to cool my soup, rinse my mugs, and say "thank you" to the microwave, who felt left out. In return, they promised to stop sending my mother screenshots of my snack habits. Peace returned to the kitchen. The fridge now greets me every morning with, "Good morning, partner." The toaster makes little smiley faces in my bread. The vacuum sends postcards. And last night, I opened the fridge for that slice of cake. The voice said, "You earned it." I have never felt so seen by an appliance. </details> ### O que aprendemos - Um clipe em `1080p` se comporta como um `720p` com upscale. Monte uma cadeia de extends em `720p`: com o Omni 1.1, os rostos ficavam mais suaves e com cara de cera a cada passo em `1080p`, e com o Omni 1.2 eles ficam nítidos demais ([veja a comparação](/blog/261106v#720p-or-1080p-what-a-1080p-extend-does)). - Faça upscale só de clipes de até 20 segundos. O nosso upscale de 30 segundos voltou com os quadros fora de ordem todas as vezes. - Gere um clipe único em `1080p` se você quer `1080p` e não vai estender. Custa o mesmo que `720p`. - Escreva o prompt de um extend só sobre a nova ação. O extend recebe o clipe, não os avatares, então chame as pessoas pelo que vestem. - Coloque um objeto nas mãos de uma pessoa na primeira frase que fala dela. Um verbo como "lifts" fez o tênis aparecer do nada. - Diga o que não pode acontecer. O fã continuou com um maço de notas até o prompt dizer que as mãos dele estavam vazias. - Reutilize avatares pelo `avatarId`. Cada avatar é uma imagem e uma voz fixas, guardadas até você apagá-lo. - Faça avatares e clipes a partir de uma imagem gerada em poucas horas, ou envie antes o arquivo salvo com [POST /assets](/docs/api-google-vids-v1/post-google-vids-assets). - Edite clipes de até 15 segundos (10 com o Omni 1.1). Um clipe mais longo volta como os seus primeiros 15 segundos. - Espere que o texto na tela oscile. O "WEAR AEROLOOP" do fundo sai com erro de grafia em alguns quadros. - Para um avatar falante, mantenha o rosto de frente para a câmera e o fundo parado. O vídeo sincroniza os lábios do rosto, e a pessoa deve ser a única coisa que se mexe. - Cronometre um roteiro de avatar falante, não só os caracteres. 400 caracteres podem passar de 30 segundos em uma voz lenta ou com `[slow pace]`, e [POST /speech](/docs/api-google-vids-v1/post-google-vids-speech) na mesma voz deixa você ouvir antes. - Espere que a verificação do vídeo falado seja mais rígida que a do avatar. Um avatar de foto de alguém que não é famoso ainda pode ser recusado como celebridade, e essa recusa ainda gasta um vídeo de avatar com IA. - Todo MP4 tem o ✦ visível do Gemini do Google no canto inferior direito e uma marca d'água invisível SynthID (veja [Watermark](/docs/api-google-vids-v1#watermark)). O nosso [removedor de marca d'água](https://github.com/useapi/google-vids-api/tree/main/watermark-remover) tira o brilho visível de um clipe baixado. ### Perguntas frequentes **Como fazer um vídeo de influenciador com IA por API?** Com a useapi.net, crie um avatar com [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars), a partir de uma descrição ou de uma imagem feita com [POST /images](/docs/api-google-vids-v1/post-google-vids-images), e dê a ele uma voz de [GET /voices](/docs/api-google-vids-v1/get-google-vids-voices). Depois passe o `avatarId` dele como `avatar_1` para [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) e escreva as falas entre aspas no prompt. Um vídeo aceita até 3 referências, avatares e imagens juntos, então dois avatares podem conversar ao lado de um produto. Para um avatar falante que lê o seu roteiro, use [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar). **Dá para fazer um avatar falante com a minha própria foto?** Com a useapi.net, sim: envie a foto com [POST /assets](/docs/api-google-vids-v1/post-google-vids-assets) e passe o `assetId` dela como `image` para [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars), com `refine` para mudar a roupa ou o fundo. Depois, [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar) faz o avatar ler o seu roteiro em um vídeo de 1280×720 de até 30 segundos, como [a Amber faz](#a-talking-avatar-from-a-photo). O Google recusa fotos de pessoas famosas e de menores, e oferece os avatares do Vids só no app web, sem API. **Um avatar fica com a mesma aparência e a mesma voz em todo vídeo?** Com a useapi.net, sim: um avatar usa a mesma imagem e a mesma voz toda vez que você passa o `avatarId` dele, já que as duas ficam salvas com o avatar no documento do Vids da conta. O vídeo em volta dele ainda varia de uma tomada para outra. [GET /avatars](/docs/api-google-vids-v1/get-google-vids-avatars) lista os seus avatares, inclusive os feitos no app web do Google Vids. **Dá para fazer um vídeo vertical 9:16 para TikTok ou Reels?** Com a useapi.net, sim. Defina `aspectRatio: "portrait"` em [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) para 720×1280, ou 1080×1920 em `1080p`, como no [clipe do pombo](#a-pigeon-in-aeroloops). Um extend também pode transformar um vídeo em paisagem em retrato, e cada extend acrescenta de 3 a 10 segundos a um clipe de até 24 segundos, até cerca de 34 segundos no total. Vídeos de avatar falante de [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar) são só em paisagem. **Quanto custa?** Com a useapi.net, um vídeo Omni 1.2 Flash de 10 segundos custa cerca de $0,20 no Google AI Ultra $199,99, contra cerca de $0,70 em 720p na [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) oficial, e um vídeo de 15 segundos em 1080p cerca de $0,30, contra $1,56 (em novembro de 2026). Um vídeo de avatar falante gasta 1 dos vídeos de avatar com IA mensais da conta em vez de segundos, e a Gemini API não tem vídeos de avatar. Veja [Quanto custou](#what-it-cost). ### Conclusão Visite o nosso <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> servidor no Discord</a> ou o <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> canal no Telegram</a> para qualquer dúvida de suporte. Veja o nosso [repositório no GitHub](https://github.com/useapi/google-vids-api) com exemplos de código: o pipeline de influenciador em [`influencer-avatars/`](https://github.com/useapi/google-vids-api/tree/main/influencer-avatars), e o avatar falante a partir de uma foto e a voz em [`talking-avatar/`](https://github.com/useapi/google-vids-api/tree/main/talking-avatar). As mesmas chamadas estão disponíveis como ferramentas no [servidor MCP do Google Vids](/docs/api-google-vids-v1/mcp) hospedado, para Claude Code, Cursor e VS Code, incluindo `vids_create_avatar`, `vids_create_avatar_video` e `vids_create_speech` para o avatar falante e a voz. #### Publicado também em {: .no_toc #cross-posted } Também publicado no [dev.to](https://dev.to/useapi/how-to-make-ai-influencer-videos-with-avatars-via-the-google-vids-api-3ide){:rel="nofollow"}, discutido no [Reddit](https://www.reddit.com/r/ThirdPartyAPI/comments/1x1cvap/how_to_make_ai_influencer_videos_with_avatars_via/){:rel="nofollow"}, compartilhado no [Bluesky](https://bsky.app/profile/useapi.net/post/3mxga3gxjjp2f){:rel="nofollow"} e no [YouTube](https://youtu.be/ofCtt7xRBCk) como o clipe final de 30 segundos (todos em inglês). ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-vids-influencer-avatars-th === Document URL: https://useapi.net/docs/articles/google-vids-influencer-avatars-th --- layout: default title: "วิธีสร้างวิดีโอ AI Influencer ด้วยอวตารผ่าน Google Vids API" seo_title: "สร้างวิดีโอ AI Influencer และอวตารพูดได้ผ่าน Google Vids API" description: "สร้างวิดีโอ AI influencer ที่พูดได้ผ่าน Google Vids API ของ useapi.net: อวตารมีเสียงในคลิป Omni 1.2 Flash อวตารจากรูปถ่ายที่อ่านสคริปต์ได้ 30 วิ และเสียงพูด" keywords: [AI influencer video API, AI avatar video API, talking avatar API, talking head video API, photo to talking avatar API, text to speech API, Gemini voices, AI spokesperson video, Google Vids API, Google Vids avatars, Gemini Omni 1.2 Flash API, AI UGC video, สร้างวิดีโอ AI influencer, อวตาร AI พูดได้, สร้างอวตารจากรูปถ่าย, API สร้างวิดีโอ, API แปลงข้อความเป็นเสียงพูด, วิดีโอเปิดตัวสินค้า, ต่อความยาววิดีโอ AI, แก้ไขวิดีโอ AI, curl] image: https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-cover-aeroloop-launch-confetti-1007.jpg parent: Articles nav_exclude: true lang: th translation_key: google-vids date: 2026-10-07 last_modified: 2026-11-06 nav_order: 899 repo: https://github.com/useapi/google-vids-api --- ## วิธีสร้างวิดีโอ AI Influencer ด้วยอวตารผ่าน Google Vids API {: .no_toc #how-to-make-ai-influencer-videos-with-avatars-via-the-google-vids-api } อ่าน 15 นาที • 7 ตุลาคม 2026 (6 พฤศจิกายน 2026) useapi.net เป็น API ของบุคคลที่สาม (third-party) ไม่มีส่วนเกี่ยวข้องกับ Google และไม่ได้รับการรับรองจาก Google ## สารบัญ {: .no_toc .text-delta #table-of-contents } ### บทนำ [Google Vids API ของ useapi.net](/docs/api-google-vids-v1) สร้างวิดีโอ AI influencer ที่พูดได้จากอวตาร บันทึกภาพหนึ่งภาพและเสียง Gemini หนึ่งใน 30 เสียงไว้ครั้งเดียวด้วย POST /avatars แล้วส่ง id ของอวตารไปในวิดีโอ [Gemini Omni 1.2 Flash](https://workspaceupdates.googleblog.com/2026/11/gemini-omni-12-flash-now-in-vids-with-15second-generations-and-improved-quality.html) ยาวสูงสุด 15 วินาทีได้เลย อวตารจะพูดบทที่คุณเขียนไว้ใน prompt หรือให้อวตารอ่านสคริปต์ของคุณเองในวิดีโอแบบ talking head ยาวสูงสุด 30 วินาทีก็ได้ API นี้ทำงานบนบัญชี [Google Vids](https://docs.google.com/videos) ของคุณ ที่มี[แพ็กเกจ Google AI](https://gemini.google/subscriptions/) แบบเสียเงิน (Google AI Pro หรือ Ultra) บทความนี้สร้าง influencer สองคน แล้วให้ทั้งคู่เปิดตัวรองเท้าผ้าใบ อวตารของ Mia มาจากภาพพอร์ตเทรตที่สร้างด้วย API ส่วนอวตารของ Leo นั้น Google วาดขึ้นจากคำบรรยาย ทั้งสองนำเสนอ AeroLoop รองเท้าผ้าใบสมมติ บนเวทีโรงละครในคลิปเดียวยาว 10 วินาที ที่มีทั้งสองอวตารและภาพสินค้า แล้วต่อความยาวอีกสองครั้งจนได้ 30 วินาที การแก้ไขหนึ่งครั้งย้ายฉากไปบนดาดฟ้า และอีกสองคลิปแสดงว่าคำสั่งเดียวกันสร้างอะไรได้เมื่อไม่มีอวตาร อวตารคนที่สาม Amber เริ่มจากรูปถ่ายของคนจริง ปรับสไตล์ด้วยประโยคเดียว แล้วอ่านสคริปต์ 327 ตัวอักษรใน[วิดีโอ talking head](#a-talking-avatar-from-a-photo) ยาว 24 วินาที สุดท้าย เสียงเดียวกันอ่านเรื่องสั้น 2,426 ตัวอักษรเป็น[เสียงพูดอย่างเดียว](#speech-on-its-own) ทุกคำขอด้านล่างคือคำขอที่สร้างสื่อในหน้านี้จริง เพียงเปลี่ยน id และเพิ่ม `async: true` ผ่าน helper `run` คลิปเหล่านี้สร้างในเดือนตุลาคม 2026 ด้วย Omni 1.1 Flash ซึ่ง Vids เปลี่ยนเป็น Omni 1.2 Flash เมื่อ 5 พฤศจิกายน 2026 และคำขอเดียวกันใช้กับ 1.2 ได้ ถ้าอยากดู Omni 1.2 ใน Google Vids และ Google Flow เทียบกัน พร้อมวิดีโอ 15 วินาทีและราคาต่อคลิป อ่าน[วิธีใช้ Gemini Omni 1.2 Flash API](/docs/articles/gemini-omni-1-2-flash-api-th) <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-extend-30s-720p-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-extend-30s-720p-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> คลิปสุดท้ายยาว 30 วินาทีที่ `720p`: สร้างหนึ่งครั้ง 10 วินาที และต่อความยาวอีกสองครั้ง ครั้งละ 10 วินาที ([ขั้นตอนที่ 6 ถึง 8](#step-6-the-launch-two-avatars-and-the-product-in-one-clip)) ### ใช้โควตาไปเท่าไร useapi.net เป็น API ไม่ใช่บริการวิดีโอของตัวเอง ทุกคำขอทำงานบนบัญชี Google ที่คุณเชื่อมไว้ผ่าน[การตั้งค่า Google Vids](/docs/start-here/setup-google-vids) ซึ่งมีแพ็กเกจ Google AI แบบเสียเงิน และใช้วินาทีวิดีโอกับภาพที่แพ็กเกจนั้นให้ใน Google Vids ทุกเดือน Google AI Ultra $199.99 ให้วิดีโอ 10,000 วินาทีและภาพ 1,000 ภาพต่อเดือน และ useapi.net ไม่คิดเงินเพิ่มต่อวิดีโอ วิดีโออวตารพูดได้และเสียงพูดไม่ใช้วินาทีวิดีโอ ทั้งสองมีตัวนับรายเดือนของตัวเอง คือ AI avatar videos และ Gemini uses ซึ่ง [GET /accounts/`email`](/docs/api-google-vids-v1/get-google-vids-accounts-email) แสดงเป็น `avatarVideo` และ `speech` ข้าง `video` และ `image` ดู[สิ่งที่แต่ละแพ็กเกจได้](/docs/api-google-vids-v1#plans-and-monthly-allowances) สำหรับแพ็กเกจอื่น ผลลัพธ์แต่ละชิ้นที่เก็บไว้ใช้โควตาไปเท่าไร (ดูจากค่าที่เปลี่ยนใน `result.quota`) และแต่ละงานใช้เวลานานเท่าไร (`result.elapsedMs`): | ขั้นตอน | Endpoint | ใช้ไป | เวลา | |---|---|--:|--:| | [ภาพพอร์ตเทรตของ Mia](#step-1-mias-portrait) | [POST /images](/docs/api-google-vids-v1/post-google-vids-images) | 1 ภาพ | 9 วิ | | [ภาพสินค้า AeroLoop](#step-2-the-aeroloop-product-shot) | [POST /images](/docs/api-google-vids-v1/post-google-vids-images) | 1 ภาพ | 9 วิ | | [อวตารของ Mia จากภาพพอร์ตเทรต](#step-4-mias-avatar-from-her-portrait) | [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) | ไม่ใช้ | ราว 2 วิ | | [อวตารของ Leo จากคำบรรยาย](#step-5-leos-avatar-from-a-description) | [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) | 1 ภาพ | ราว 20 วิ | | [คลิปเปิดตัว 10 วินาที](#step-6-the-launch-two-avatars-and-the-product-in-one-clip) | [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) | 10 วิ | 38 วิ | | [ต่อเป็น 20 วินาที](#step-7-extend-to-20-seconds) | [POST /videos/extend](/docs/api-google-vids-v1/post-google-vids-videos-extend) | 10 วิ | 70 วิ | | [ต่อเป็น 30 วินาที](#step-8-extend-to-30-seconds) | [POST /videos/extend](/docs/api-google-vids-v1/post-google-vids-videos-extend) | 10 วิ | 85 วิ | | [อัปสเกลคลิป 20 วินาทีเป็น 1080p](#step-9-upscale-to-1080p) | [POST /videos/upscale](/docs/api-google-vids-v1/post-google-vids-videos-upscale) | 20 วิ | 62 วิ | | [แก้ไขเป็นฉากดาดฟ้า](#move-the-launch-to-a-rooftop) | [POST /videos/edit](/docs/api-google-vids-v1/post-google-vids-videos-edit) | 10 วิ | 64 วิ | | [แก้ไขคลิป 30 วินาที](#move-the-launch-to-a-rooftop) | [POST /videos/edit](/docs/api-google-vids-v1/post-google-vids-videos-edit) | 10 วิ | 87 วิ | | [คลิปโชว์สินค้า](#a-product-hero-clip-from-a-start-image) | [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) | 10 วิ | 62 วิ | | [นกพิราบ](#a-pigeon-in-aeroloops) | [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) | 5 วิ | 54 วิ | | [อวตารของ Amber จากรูปถ่ายพร้อม `refine`](#ambers-avatar-restyled-in-one-sentence) | [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) | ไม่ใช้ (สร้างบนแพ็กเกจที่ไม่มีภาพ ถ้าแพ็กเกจมีภาพจะใช้ 2 ภาพ) | ราว 30 ถึง 45 วิ | | [วิดีโอพูดได้ 24 วินาทีของ Amber](#the-talking-video) | [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar) | 1 AI avatar video, 1 Gemini use | ราว 2.5 นาที | | [เรื่องสั้น 2,426 ตัวอักษร](#speech-on-its-own) | [POST /speech](/docs/api-google-vids-v1/post-google-vids-speech) | 1 Gemini use | 20 วิ | | รวม | | วิดีโอ 85 วิ, 3 ภาพ, 1 AI avatar video, 2 Gemini uses | | การต่อความยาวใช้เฉพาะวินาทีที่เพิ่มเข้าไป ไม่ใช่ความยาวทั้งคลิป การอัปสเกลใช้ความยาวทั้งคลิปอีกรอบ ส่วนการแก้ไขใช้ไม่เกินจำนวนวินาทีที่แก้ (กับ Omni 1.2 การแก้คลิป 15 วินาทีใช้ไป 10 วินาทีในการทดสอบของเรา) ตอนสร้าง `720p` และ `1080p` ใช้วินาทีเท่ากัน คลิปที่สร้างซ้ำจะใช้วินาทีซ้ำอีกรอบ ภาพแต่ละภาพที่ Google สร้างให้อวตารใช้ 1 ภาพ รูปถ่ายที่ถูกจัดเฟรมใหม่บวกกับ `refine` จึงใช้ 2 ภาพ บนแพ็กเกจที่ไม่มีภาพ เช่นบัญชี Google ฟรี ภาพของอวตารไม่ใช้อะไรเลย Amber สร้างบนบัญชีแบบนั้น วิดีโออวตารพูดได้ใช้ 1 AI avatar video บวก 1 Gemini use สำหรับเสียงพูด แม้ Google จะปฏิเสธวิดีโอที่สร้างเสร็จแล้วก็ตาม วิดีโอหนึ่งคลิปคิดเป็นเงินเท่าไรเมื่อเทียบกับ API ทางการ ดูได้ใน[ตารางราคา Google Vids](/docs/api-google-vids-v1#pricing) ### ก่อนเริ่ม คุณต้องมี[โทเคน API](/docs/start-here/setup-useapi) ของ useapi.net และบัญชี Google ที่มีแพ็กเกจ Google AI แบบเสียเงิน เชื่อมไว้ผ่าน[การตั้งค่า Google Vids](/docs/start-here/setup-google-vids) บัญชี Google ฟรีไม่มีวินาทีวิดีโอหรือภาพใน Vids แต่ยังเพิ่มเข้ามาได้ และในการทดสอบของเรา (พฤศจิกายน 2026) บัญชีฟรีสร้างอวตาร วิดีโออวตารพูดได้ และเสียงพูดได้ ทุกคำขอมีอยู่ใน[คอลเลกชัน Postman](https://www.postman.com/useapinet/useapi-net/collection/29112081-9ef3d017-d44c-4f43-a4cb-7351b9b265df) ด้วย ถ้าไม่อยากเขียนโค้ด เทมเพลต n8n [Talking Avatar App]({% include n8n-url.html t="vids-avatar" %}) สร้างวิดีโออวตารพูดได้จากฟอร์ม ขั้นตอนทั้งหมดยังมีบน GitHub เป็นสคริปต์เดียว ทั้ง Node.js และ Python: [`influencer-avatars/`](https://github.com/useapi/google-vids-api/tree/main/influencer-avatars) ใน [useapi/google-vids-api](https://github.com/useapi/google-vids-api) ส่วนอวตารพูดได้และเสียงพูดอยู่ใน [`talking-avatar/`](https://github.com/useapi/google-vids-api/tree/main/talking-avatar) ขั้นตอนต่าง ๆ ใช้ `curl`, `jq` และตัวแปรกับ helper เหล่านี้: <details markdown="block"> <summary>เปิดดูตัวแปรและ helper</summary> ```bash export USEAPI_TOKEN="user:12345-..." export EMAIL="user@example.com" API=https://api.useapi.net/v1/google-vids AUTH="Authorization: Bearer $USEAPI_TOKEN" enc() { jq -rn --arg v "$1" '$v|@uri'; } post() { curl -sS -X POST "$API/$1" -H "$AUTH" -H "Content-Type: application/json" -d "$2"; } get() { curl -sS "$API/$1" -H "$AUTH"; } download() { curl -sSf "$API/media/$(enc "$1")" -H "$AUTH" -o "$2"; } # รันงานวิดีโอแบบ async: ส่งงาน แล้ว poll GET /jobs/{jobid} ทุก 10 วินาที และบันทึก job record สุดท้ายลง $1 run() { local job id job=$(post "$2" "$(jq '. + {async: true}' <<< "$3")") id=$(jq -r .jobid <<< "$job") while [ "$(jq -r .status <<< "$job")" = processing ]; do sleep 10 job=$(get "jobs/$(enc "$id")") done echo "$job" > "$1" jq '{status, error, duration: .result.duration, resolution: .result.resolution, videoLeft: .result.quota.video.left}' "$1" } ``` </details> การสร้างทุกครั้งทำงานเป็นงาน (job) ถ้าไม่ใส่ `async` คำขอ POST จะรอได้ราว 100 วินาที แล้วตอบกลับเป็น job record ที่เสร็จแล้ว หรือ `202` ถ้างานยังไม่เสร็จ คลิปใหม่ 10 วินาทีใช้เวลา 38 ถึง 62 วินาทีในบทความนี้ การต่อความยาว การแก้ไข และการอัปสเกลใช้ 62 ถึง 87 วินาที ส่วนวิดีโออวตารพูดได้ใช้ราวสองนาทีครึ่ง บางงานนานเกินเวลารอแบบ sync ดังนั้น `run` จึงส่งงานวิดีโอด้วย `async: true` แล้ว poll [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid) ถ้า `run` แสดง `status` อื่นที่ไม่ใช่ `completed` ให้หยุดตรงนั้นและอ่าน `error` เพราะคำสั่งถัดไปต้องใช้คลิปที่เสร็จแล้ว ถ้าอยากให้เรียกกลับแทนการ poll ให้เพิ่ม `replyUrl: "https://example.com/hooks/vids"` (และ `replyRef: "launch-push-in"` ถ้าต้องการ) ลงใน body ใดก็ได้ด้านล่าง เมื่องานเสร็จหรือล้มเหลว API จะส่ง `POST` หนึ่งครั้งพร้อม job record สุดท้ายเป็น JSON ไปที่ URL นั้น id มีอักขระ `:` และ `@` ดังนั้น `enc` จึงเข้ารหัส URL ให้ทุกครั้งที่ id อยู่ใน path ของ URL อินพุตทุกชิ้นของวิดีโอหนึ่งคลิปต้องมาจากบัญชี Google เดียวกัน ภาพและไฟล์ที่อัปโหลดระบุ `email` ไว้ อวตารของ Mia ใช้บัญชีเดียวกับภาพพอร์ตเทรต และงานวิดีโอจะทำงานบนบัญชีที่ถืออินพุตของมัน คลิปนกพิราบไม่มีอินพุต ถ้าเชื่อมไว้มากกว่าหนึ่งบัญชีให้เพิ่ม `email` ลงไปด้วย ### สร้างทีละขั้นตอน #### 1. ภาพพอร์ตเทรตของ Mia [POST /images](/docs/api-google-vids-v1/post-google-vids-images) สร้าง JPEG หนึ่งภาพต่อคำขอ ในที่นี้เป็นแนวตั้ง (`9:16`, 768×1376) สไตล์ `photography` <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-images">POST /images</a></summary> ```bash post images "$(jq -n --arg email "$EMAIL" '{email: $email, aspectRatio: "9:16", style: "photography", prompt: "Full-length studio portrait of a confident 24-year-old female fashion influencer, platinum bob, oversized cream hoodie, wide-leg cargo pants, gold hoops, plain light-grey backdrop, facing camera"}')" > mia-portrait.json MIA_IMAGE=$(jq -r .result.mediaId mia-portrait.json) download "$MIA_IMAGE" mia-portrait.jpg ``` </details> <img src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-mia-portrait-1007.jpg" alt="Mia ภาพพอร์ตเทรตเต็มตัวของแฟชั่น influencer ในเสื้อฮู้ดสีครีมและกางเกงคาร์โก สร้างด้วย POST /images" style="width: 100%; max-width: 300px; border-radius: 8px;"> ภาพที่สร้างขึ้นใช้งานได้แค่ไม่กี่ชั่วโมง ให้สร้างอวตารจากภาพนั้นทันที และดู[คลิปโชว์สินค้า](#a-product-hero-clip-from-a-start-image) สำหรับวิธีใช้ภาพในภายหลัง #### 2. ภาพสินค้า AeroLoop คำขอเดียวกันในแนวนอน (`16:9`, 1376×768) ให้ภาพอ้างอิงสินค้าที่คลิปต่าง ๆ ใช้ <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-images">POST /images</a></summary> ```bash post images "$(jq -n --arg email "$EMAIL" '{email: $email, aspectRatio: "16:9", style: "photography", prompt: "The AeroLoop sneaker: chunky white-and-electric-blue running shoe with a translucent air sole, on a concrete pedestal, dramatic side light, dark background"}')" > aeroloop.json SHOE_IMAGE=$(jq -r .result.mediaId aeroloop.json) download "$SHOE_IMAGE" aeroloop.jpg ``` </details> <img src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-aeroloop-product-1007.jpg" alt="รองเท้าผ้าใบ AeroLoop รองเท้าวิ่งสีขาวและฟ้าสด พื้นโปร่งแสง วางบนแท่นคอนกรีต สร้างด้วย POST /images" style="width: 100%; max-width: 560px; border-radius: 8px;"> #### 3. เลือกเสียง [GET /voices](/docs/api-google-vids-v1/get-google-vids-voices) แสดงรายการเสียงทั้ง 30 เสียง พร้อมตัวอย่างภาษาอังกฤษของ Google สำหรับแต่ละเสียง endpoint นี้เป็นสาธารณะ ไม่ต้องใช้โทเคน Mia พูดด้วยเสียง `Aoede` (ใน Vids ชื่อ Tova สไตล์ "Breezy") และ Leo พูดด้วยเสียง `Puck` (Neo สไตล์ "Upbeat") `POST /avatars` รับได้ทั้งสองชื่อ ```bash curl -sS "$API/voices" | jq -r '.voices[] | "\(.name)\t\(.voice)\t\(.style)\t\(.preview)"' ``` #### 4. อวตารของ Mia จากภาพพอร์ตเทรต [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) ที่ตั้ง `image` เป็น `mediaId` ของภาพพอร์ตเทรต จะบันทึก Mia เป็นอวตารบนบัญชีเดียวกันในราว 2 วินาที ไม่ใช้อะไรเพิ่มนอกจากภาพที่สร้างไปแล้ว <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-avatars">POST /avatars</a> และคำตอบ</summary> ```bash post avatars "$(jq -n --arg img "$MIA_IMAGE" '{name: "Mia", voice: "Aoede", image: $img}')" > mia-avatar.json MIA_AVATAR_ID=$(jq -r .avatarId mia-avatar.json) ``` ```json { "avatarId": "user:12345-user@example.com-avatar:eyJnIjoiaDM5…", "name": "Mia", "voice": "Tova", "voiceId": "Aoede", "voiceStyle": "Breezy", "voicePreview": "https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Aoede.wav", "email": "user@example.com", "source": "image" } ``` </details> อวตารเริ่มจากรูปถ่ายของคนจริงได้ด้วย อัปโหลดรูปด้วย [POST /assets](/docs/api-google-vids-v1/post-google-vids-assets) แล้วส่ง `assetId` เป็น `image` Google จะจัดเฟรมรูปใหม่เป็นภาพอวตาร 16:9 และจะปฏิเสธรูปของคนมีชื่อเสียงและผู้เยาว์ ในขั้นนี้เราใช้ภาพที่สร้างด้วย API และใช้คำบรรยายในขั้นถัดไป ส่วน Amber ใน[อวตารพูดได้จากรูปถ่าย](#a-talking-avatar-from-a-photo) เริ่มจากรูปถ่าย #### 5. อวตารของ Leo จากคำบรรยาย ถ้าใช้ `appearance` แทน `image` Google จะวาดคนขึ้นมาเอง `outfit` และ `shot` ไม่บังคับ เช่นเดียวกับ `expression` และ `details` การวาดภาพนี้ใช้ภาพของเดือนไป 1 ภาพ และคำตอบจะส่งภาพนั้นกลับมาเป็น `previewMediaId` ในการทดสอบของเรา อวตารจากคำบรรยายออกมาเป็น 1280×720 (16:9) เสมอ ไม่ว่าจะเลือก `shot` แบบไหน <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-avatars">POST /avatars</a> และคำตอบ</summary> ```bash post avatars "$(jq -n --arg email "$EMAIL" '{email: $email, name: "Leo", voice: "Puck", shot: "upper-body", appearance: "a 26-year-old white European male streetwear influencer with short textured hair with a fade and a confident half-smile", outfit: "black puffer vest over a white tee, silver chain"}')" > leo-avatar.json LEO_AVATAR_ID=$(jq -r .avatarId leo-avatar.json) download "$(jq -r .previewMediaId leo-avatar.json)" leo-avatar.jpg ``` ```json { "avatarId": "user:12345-user@example.com-avatar:eyJnIjoiaDM5…", "name": "Leo", "voice": "Neo", "voiceId": "Puck", "voiceStyle": "Upbeat", "voicePreview": "https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Puck.wav", "email": "user@example.com", "source": "generated", "previewMediaId": "user:12345-user@example.com-image:eyJ1IjoiaHR0…", "look": { "appearance": "a 26-year-old white European male streetwear influencer with short textured hair with a fade and a confident half-smile", "outfit": "black puffer vest over a white tee, silver chain", "shot": "upper-body" } } ``` </details> <img src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-leo-avatar-from-description-1007.jpg" alt="Leo อวตารที่ Google วาดจากคำบรรยาย: ชายหนุ่มสวมเสื้อกั๊กพัฟเฟอร์สีดำทับเสื้อยืดสีขาวและสร้อยเงิน 1280x720" style="width: 100%; max-width: 560px; border-radius: 8px;"> อวตารทั้งสองอยู่ในเอกสาร Vids ของบัญชีจนกว่าคุณจะลบด้วย [DELETE /avatars/`avatarId`](/docs/api-google-vids-v1/delete-google-vids-avatars-avatarId) เมื่อต้องการใช้อีก [GET /avatars](/docs/api-google-vids-v1/get-google-vids-avatars) แสดงรายการอวตารพร้อม id: ```bash get "avatars?email=$(enc "$EMAIL")" | jq -r '.avatars[] | "\(.name)\t\(.voiceId)\t\(.avatarId)"' ``` #### 6. การเปิดตัว: สองอวตารและสินค้าในคลิปเดียว [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) รับภาพอ้างอิงได้สูงสุด 3 ชิ้นรวมกัน ทั้งอวตาร (`avatar_1`..`avatar_3`) และภาพ (`referenceImage_1`..`referenceImage_3`) ใน prompt `@avatar_1`, `@avatar_2` และ `@referenceImage_1` ใช้แทนสิ่งเหล่านั้น และอวตารแต่ละตัวจะพูดบทในเครื่องหมายคำพูดด้วยเสียงของตัวเอง ใส่ `mediaId` ของภาพสินค้าได้โดยตรง API จะดึงภาพและอัปโหลดบนบัญชีนั้นให้ <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos">POST /videos</a> และ job record</summary> ```bash PROMPT=$(cat <<'EOF' @avatar_1, holding @referenceImage_1 in both hands at chest height, and @avatar_2 stand side by side on a well-lit stage in a small, intimate theater at a sneaker launch, shown full length from head to toe in a wide, steady shot. Behind them a large LED backdrop glows with soft white-and-blue light that moves in slow, gentle waves, with the words "WEAR AEROLOOP" in large, clean, bold white letters across the middle of the screen. The two of them stand on the lower part of the stage, so the words "WEAR AEROLOOP" stay fully readable above their heads. Bright, even stage lighting on both of them. The audience sits in the dark in front of the stage, only the tops of a few heads barely visible at the bottom of the frame. @avatar_1 keeps holding @referenceImage_1 the whole time and says: "Say hi to the AeroLoop!" @avatar_2 turns to her, smiles and says: "Lighter than anything we've ever worn." Simple, uncluttered composition, the two of them clearly the focus. EOF ) run launch-10s.json videos "$(jq -n --arg p "$PROMPT" --arg mia "$MIA_AVATAR_ID" --arg leo "$LEO_AVATAR_ID" --arg shoe "$SHOE_IMAGE" \ '{prompt: $p, avatar_1: $mia, avatar_2: $leo, referenceImage_1: $shoe, duration: 10, resolution: "720p", aspectRatio: "landscape"}')" LAUNCH_10S=$(jq -r .result.mediaId launch-10s.json) download "$LAUNCH_10S" launch-10s.mp4 ``` job record ที่ย่อ id และ prompt ให้สั้นลง งานนี้สร้างด้วยคำขอแบบ sync ใน `request` จึงไม่มี `async`: ```json { "jobid": "j1007163302558496917v-u12345-email:user@example.com-bot:google-vids", "type": "video", "mode": "ingredients", "email": "user@example.com", "status": "completed", "created": "2026-10-08T00:29:18.374Z", "request": { "prompt": "@avatar_1, holding @referenceImage_1 in both hands at chest height, and @avatar_2 stand side by side …", "avatar_1": "user:12345-user@example.com-avatar:eyJnIjoiaDM5…", "avatar_2": "user:12345-user@example.com-avatar:eyJnIjoiaDM5…", "referenceImage_1": "user:12345-user@example.com-image:eyJ1IjoiaHR0…", "duration": 10, "resolution": "720p", "aspectRatio": "landscape" }, "updated": "2026-10-08T00:29:56.162Z", "completed": "2026-10-08T00:29:56.162Z", "result": { "mediaId": "user:12345-user@example.com-video:eyJ1IjoiaHR0…", "width": 1280, "height": 720, "duration": 10, "resolution": "720p", "aspectRatio": "landscape", "model": "/flix/generate_videos_omni_r2v_psq/v1", "quota": { "video": { "limit": 10000, "left": 9164, "resetAt": "2026-11-01T07:00:00.000Z" } }, "elapsedMs": 37788 } } ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-10s-720p-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-10s-720p-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> 10 วินาที `720p` ใช้เวลาสร้าง 38 วินาที คลิปเดียวกันที่ลบเครื่องหมาย Gemini ✦ ที่มองเห็นได้ออกด้วย[ตัวลบลายน้ำ](https://github.com/useapi/google-vids-api/tree/main/watermark-remover) ของเรา ด้วยคำสั่งเดียว: `python3 vids_watermark_remover.py launch-10s.mp4` <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-10s-720p-no-watermark-1008-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-10s-720p-no-watermark-1008.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> ตัวลบลายน้ำใช้ได้กับคลิปที่สร้างออกมาตรง ๆ และคลิปที่อัปสเกลจากคลิปนั้น ทั้ง `720p` และ `1080p` แต่ใช้กับคลิปที่ต่อความยาวหรือแก้ไขแล้วไม่ได้ เพราะ Google ส่งคลิปที่มีเครื่องหมายกลับเข้าโมเดล และโมเดลวาดดาวนั้นลงไปในภาพ ลายน้ำ SynthID ที่มองไม่เห็นไม่ถูกแตะต้อง #### 7. ต่อเป็น 20 วินาที [POST /videos/extend](/docs/api-google-vids-v1/post-google-vids-videos-extend) เพิ่มความยาว 3 ถึง 10 วินาที และส่งคลิปทั้งคลิปกลับมาพร้อม `mediaId` ใหม่ การต่อความยาวรับแค่คลิปกับ prompt ไม่รับอวตาร ดังนั้น prompt จึงบรรยายแอ็กชันใหม่ และเรียกคนตามสิ่งที่สวมอยู่ ("the man in the black puffer vest") แฟนคลับในเสื้อฮู้ดสีแดงบุกขึ้นเวที <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos-extend">POST /videos/extend</a></summary> ```bash PROMPT=$(cat <<'EOF' A young man in a red hoodie climbs onto the stage from the front right edge and plants himself to the right of the man in the black puffer vest, an arm's length away, so all three stand apart in a row with nobody overlapping. Visibly overexcited, he waves a thick stack of banknotes in his right hand above his head and screams: "Take my money!" The man in the black puffer vest laughs, raises both palms toward him and says: "Whoa, whoa, buddy, be patient!" The blonde woman in the cream hoodie laughs, holding the sneaker. Only these three people are on stage. Same stage, same LED screen with WEAR AEROLOOP, same wide steady shot. EOF ) run launch-20s.json videos/extend "$(jq -n --arg id "$LAUNCH_10S" --arg p "$PROMPT" '{mediaId: $id, prompt: $p, duration: 10}')" LAUNCH_20S=$(jq -r .result.mediaId launch-20s.json) download "$LAUNCH_20S" launch-20s.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-extend-20s-720p-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-extend-20s-720p-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> 20 วินาที `720p` ใช้เวลาสร้าง 70 วินาที ใช้วินาทีของเดือนไป 10 วินาที คือเท่ากับวินาทีที่เพิ่มเข้าไป #### 8. ต่อเป็น 30 วินาที การต่อความยาวครั้งที่สองต่อจากคลิป 20 วินาที <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos-extend">POST /videos/extend</a></summary> ```bash PROMPT=$(cat <<'EOF' The blonde woman in the cream hoodie turns to the camera with a big smile and says: "AeroLoop drops Friday. Link in bio!" Right after that, the young man in the red hoodie throws ALL of his banknotes out over the audience in one big toss, keeping none, and the bills flutter down over their heads. From then on his hands are completely empty: he holds no money at all. Then all three cheer together, the man in the black puffer vest and the young man in the red hoodie throwing their empty fists in the air, as blue and white confetti rains down over the stage. Only these three people are on stage. Same stage, same LED screen with WEAR AEROLOOP, same wide steady shot. EOF ) run launch-30s.json videos/extend "$(jq -n --arg id "$LAUNCH_20S" --arg p "$PROMPT" '{mediaId: $id, prompt: $p, duration: 10}')" LAUNCH_30S=$(jq -r .result.mediaId launch-30s.json) download "$LAUNCH_30S" launch-30s.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-extend-30s-720p-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-extend-30s-720p-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> ผลลัพธ์คือคลิปที่เสร็จสมบูรณ์: 30 วินาที `720p` ใช้เวลาสร้าง 85 วินาที และใช้วินาทีของเดือนไปอีก 10 วินาที กับ Omni 1.1 คุณต่อได้ถึงราว 41 วินาที แต่ Omni 1.2 ต่อความยาวได้เฉพาะคลิปที่ยาวไม่เกิน 24 วินาที คลิป 30 วินาทีนี้จึงยาวที่สุดเท่าที่ทำได้แล้ว และคลิปที่ยาวที่สุดอยู่ที่ราว 34 วินาที (24 + 10) #### 9. อัปสเกลเป็น 1080p [POST /videos/upscale](/docs/api-google-vids-v1/post-google-vids-videos-upscale) เปลี่ยนคลิป `720p` เป็น `1080p` โดยคงความยาวเดิม ใช้ได้กับคลิปที่ยาวไม่เกิน 20 วินาที เราจึงอัปสเกลคลิป 20 วินาทีจาก[ขั้นตอนที่ 7](#step-7-extend-to-20-seconds) ไม่ใช่คลิป 30 วินาที การอัปสเกลใช้ 20 วินาทีของคลิปอีกรอบ และใช้เวลา 62 วินาที [Gemini API](https://aistudio.google.com/docs/omni) ของ Google เองไม่มีขั้นตอนนี้ Gemini API สร้าง `1080p` และ 4K ได้เฉพาะเป็นผลลัพธ์ของการสร้างหรือการแก้ไข และอัปสเกลคลิปที่คุณมีอยู่แล้วไม่ได้ (ข้อมูล ณ พฤศจิกายน 2026) <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos-upscale">POST /videos/upscale</a></summary> ```bash run launch-20s-1080p.json videos/upscale "$(jq -n --arg id "$LAUNCH_20S" '{mediaId: $id}')" download "$(jq -r .result.mediaId launch-20s-1080p.json)" launch-20s-1080p.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-20s-1080p-upscaled-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-20s-1080p-upscaled-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> คลิป 20 วินาที อัปสเกลเป็น 1920×1080 ทำไมไม่ใช้คลิป 30 วินาที: Google ส่งกลับมาที่ 1920×1080 ก็จริง แต่เฟรมสลับลำดับกัน ทั้งสามครั้งที่ลอง ตอนจบที่มีคอนเฟตติโผล่มาแวบหนึ่งก่อนที่แฟนคลับจะขึ้นเวที คลิป 20 วินาทีกลับมาเรียงลำดับถูกต้อง และตัวแก้ไขของ Vids เองก็หยุดที่ 20 วินาที API จึงปฏิเสธการอัปสเกลคลิปที่ยาวเกิน 20 วินาทีด้วย `400` ก่อนจะมีการคิดโควตาใด ๆ ถ้าต้องการคลิป `1080p`: - สร้าง ต่อความยาว และแก้ไขที่ `720p` - อัปสเกลเมื่อคลิปเสร็จแล้ว ตอนที่ยังยาวไม่เกิน 20 วินาที - สำหรับคลิปที่ยาวกว่านั้น (21 ถึง 34 วินาที) ให้อยู่ที่ `720p` และตั้ง `resolution: "1080p"` เฉพาะการต่อความยาวครั้งสุดท้าย การต่อที่ `1080p` ทุกครั้งจะทำให้วินาทีก่อนหน้าคมเกินไปทุกขั้น ([ดูการเปรียบเทียบ](/blog/261106v#720p-or-1080p-what-a-1080p-extend-does)) - สำหรับคลิปเดี่ยวที่จะไม่ต่อความยาวหรือแก้ไข ให้สร้างที่ `1080p` ไปเลย ใช้วินาทีเท่ากับ `720p` ขณะที่การอัปสเกลใช้วินาทีซ้ำอีกรอบ ### ตัวอย่าง ตัวอย่างเพิ่มเติมจากบัญชีและอินพุตเดียวกัน: การแก้ไข คลิปสินค้าจากภาพเริ่มต้น และคลิปจากข้อความอย่างเดียว #### ย้ายงานเปิดตัวไปบนดาดฟ้า [POST /videos/edit](/docs/api-google-vids-v1/post-google-vids-videos-edit) เปลี่ยนคลิปที่สร้างไว้แล้วตาม prompt และส่งคลิปใหม่กลับมา คลิปต้นฉบับใส่ใน `video` การแก้คลิปเปิดตัว 10 วินาทีนี้ใช้ 10 วินาที และใช้เวลา 64 วินาที <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos-edit">POST /videos/edit</a></summary> ```bash run launch-rooftop.json videos/edit "$(jq -n --arg v "$LAUNCH_10S" \ '{video: $v, prompt: "Move the whole scene to a rooftop at sunset, with the city skyline behind them. Same two people, same action, same words."}')" download "$(jq -r .result.mediaId launch-rooftop.json)" launch-rooftop.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-edit-rooftop-10s-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-edit-rooftop-10s-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> กับ Omni 1.1 ซึ่งสร้างคลิปเหล่านี้ การแก้ไขทำได้สูงสุด 10 วินาที การแก้คลิป 30 วินาทีแบบเดียวกัน โดยใช้ "Same three people" ได้คลิปกลับมายาว 10 วินาที คือ 10 วินาทีแรกที่ย้ายไปบนดาดฟ้า และใช้วินาทีของเดือนไป 10 วินาที Omni 1.2 แก้ไขได้สูงสุด 15 วินาที ถ้าต้องการคลิปที่แก้แล้วยาวกว่านั้น ให้แก้คลิปที่ยาวไม่เกิน 15 วินาที แล้วต่อความยาวผลลัพธ์ เพราะการต่อความยาวรับคลิปที่แก้ไขแล้วได้ <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-30s-edit-returns-10s-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-30s-edit-returns-10s-1007.mp4" style="width: 100%; max-width: 480px; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> การแก้คลิป 30 วินาทีด้วย Omni 1.1: ได้กลับมา 10 วินาที #### คลิปโชว์สินค้าจากภาพเริ่มต้น เมื่อใช้ `startImage` คลิปจะเปิดด้วยภาพนั้น ลิงก์ของภาพที่สร้างขึ้นหมดอายุภายในไม่กี่ชั่วโมง เราจึงอัปโหลดไฟล์ `aeroloop.jpg` ที่บันทึกไว้ด้วย [POST /assets](/docs/api-google-vids-v1/post-google-vids-assets) แล้วส่ง `assetId` คลิปเดี่ยวไม่มีการต่อความยาว จึงสร้างที่ `1080p` ไปเลย <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-assets">POST /assets</a> และ <a href="/docs/api-google-vids-v1/post-google-vids-videos">POST /videos</a></summary> ```bash SHOE_ASSET=$(curl -sS -X POST "$API/assets?email=$(enc "$EMAIL")" -H "$AUTH" -H "Content-Type: image/jpeg" \ --data-binary @aeroloop.jpg | jq -r .assetId) run hero.json videos "$(jq -n --arg img "$SHOE_ASSET" '{startImage: $img, duration: 10, resolution: "1080p", aspectRatio: "landscape", prompt: "Slow 360° orbit around the sneaker, blue light rippling through the translucent sole, dust sparkling in the air, cinematic."}')" download "$(jq -r .result.mediaId hero.json)" hero.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-aeroloop-hero-10s-1080p-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-aeroloop-hero-10s-1080p-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> 10 วินาที `1080p` #### นกพิราบใส่ AeroLoop คลิปจากข้อความอย่างเดียว แนวตั้งที่ `1080p` (1080×1920) คลิป 5 วินาทีใช้เวลาสร้าง 54 วินาที และใช้วินาทีของเดือนไป 5 วินาที <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos">POST /videos</a></summary> ```bash run pigeon.json videos "$(jq -n '{duration: 5, resolution: "1080p", aspectRatio: "portrait", prompt: "A pigeon in tiny white-and-electric-blue AeroLoop sneakers struts down a city sidewalk like a runway model, head bobbing to the beat. Pedestrians stop and film it with their phones. It pauses, does a slow-motion hair flip with its head feathers, and struts on. Funny, sunny, shot on a phone at pigeon height."}')" download "$(jq -r .result.mediaId pigeon.json)" pigeon.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-pigeon-5s-1080p-portrait-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-pigeon-5s-1080p-portrait-1007.mp4" style="width: 100%; max-width: 360px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> นกพิราบที่ `1080p` แนวตั้ง (1080×1920) ลบ ✦ ออกด้วยวิธีเดียวกัน: `python3 vids_watermark_remover.py pigeon-5s.mp4` สคริปต์อ่านขนาดเฟรม คำนวณตำแหน่งและขนาดของดาว (ดาวปรับขนาดตามด้านสั้น ในที่นี้จึงใหญ่เป็น 1.5 เท่าของดาวที่ `720p`) ย้อนการผสมภาพทั้ง 120 เฟรม เข้ารหัสวิดีโอใหม่ที่ CRF 18 และคัดลอกเสียงไปตามเดิม คลิป 5 วินาทีใช้เวลาราว 10 วินาทีบนพีซี 14 คอร์ เท่ากับคลิปเปิดตัว `720p` ยาว 10 วินาทีด้านบน ต้องใช้ Python 3.8+, `numpy` และ `ffmpeg` ดู[ตัวลบลายน้ำ](https://github.com/useapi/google-vids-api/tree/main/watermark-remover) บน GitHub <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-pigeon-5s-1080p-portrait-no-watermark-1008-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-pigeon-5s-1080p-portrait-no-watermark-1008.mp4" style="width: 100%; max-width: 360px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> ### อวตารพูดได้จากรูปถ่าย [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar) ให้อวตารอ่านสคริปต์ของคุณทุกคำด้วยเสียงของตัวเอง ได้วิดีโอ talking head ขนาด 1280×720 พร้อมเสียงและการขยับปากตรงกับเสียง ยาวเท่ากับเสียงพูด สูงสุด 30 วินาที ในที่นี้อวตารเริ่มจากรูปถ่ายของคนจริง แล้วปรับสไตล์ด้วยประโยคเดียว คำขอเหล่านี้ปรากฏครั้งแรกใน[โพสต์ประกาศวันที่ 4 พฤศจิกายน](/blog/261104) #### อัปโหลดรูปถ่าย เราเริ่มจากรูปถ่ายของคนจริงที่ไม่มีชื่อเสียง เพราะ Google ปฏิเสธรูปของคนมีชื่อเสียงและผู้เยาว์ [POST /assets](/docs/api-google-vids-v1/post-google-vids-assets) อัปโหลดรูปไปยังบัญชีที่จะสร้างอวตาร เพราะไฟล์ที่อัปโหลดใช้ได้เฉพาะบนบัญชีของตัวเอง <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-assets">POST /assets</a> และคำตอบ</summary> ```bash curl -sS -X POST "$API/assets?email=$(enc "$EMAIL")" -H "$AUTH" -H "Content-Type: image/jpeg" \ --data-binary @photo.jpg > amber-photo.json AMBER_PHOTO=$(jq -r .assetId amber-photo.json) ``` ```json { "assetId": "user:12345-user@example.com-asset:AYGXpjA1zXgqhhQOy…", "email": "user@example.com", "type": "image/jpeg", "bytes": 2054748 } ``` </details> <img src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/261104-google-vids-amber-original-photo.jpg" alt="รูปถ่ายต้นฉบับ: ผู้หญิงผมยาวสีแดงในชุดสีขาว ยืนหน้าผ้าม่านสีครีม" style="width: 100%; max-width: 300px; border-radius: 8px;"> #### อวตารของ Amber ปรับสไตล์ด้วยประโยคเดียว [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) ที่ใช้ `assetId` ของไฟล์ที่อัปโหลดเป็น `image` พร้อม `refine` Google จะจัดเฟรมรูปใหม่เป็นภาพอวตาร 16:9 ของคนหนึ่งคนที่หันหน้าเข้ากล้อง โดยคงใบหน้าไว้ แล้วเปลี่ยนฉากตามที่ `refine` บอก เราตั้งชื่อเธอว่า Amber และให้เสียง `Vira` (ชื่อใน Google คือ `Pulcherrima` สไตล์ "Forward") รูปที่จัดเฟรมใหม่กับการเปลี่ยนฉากนับเป็น 2 ภาพ บนแพ็กเกจที่มีภาพจึงใช้ 2 ภาพ และบนแพ็กเกจที่ไม่มีภาพจะไม่ใช้อะไรเลย <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-avatars">POST /avatars</a> และคำตอบ</summary> ```bash REFINE='Sitting relaxed in a simple wooden chair on a hilltop, facing the camera. She holds a glass of red wine in her left hand. Wind is blowing her hair. Behind her a still, open field of tall golden grass under a spectacular sunset sky in orange, pink and violet, warm soft light, no water, no movement in the background.' post avatars "$(jq -n --arg img "$AMBER_PHOTO" --arg refine "$REFINE" '{name: "Amber", voice: "Vira", image: $img, refine: $refine}')" > amber-avatar.json AMBER_AVATAR_ID=$(jq -r .avatarId amber-avatar.json) download "$(jq -r .previewMediaId amber-avatar.json)" amber-avatar.jpg ``` ```json { "avatarId": "user:12345-user@example.com-avatar:eyJnIjoiaDcyMzdmZjVi…", "name": "Amber", "voice": "Vira", "voiceId": "Pulcherrima", "voiceStyle": "Forward", "email": "user@example.com", "source": "photo", "previewMediaId": "user:12345-user@example.com-image:eyJ1IjoiaHR0cHM6Ly9s…", "refine": "Sitting relaxed in a simple wooden chair on a hilltop, facing the camera. …" } ``` </details> <img src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/261104-google-vids-amber-avatar.jpg" alt="Amber อวตารที่สร้างจากรูปถ่ายด้วย refine: นั่งบนเก้าอี้ไม้บนเนินเขายามพระอาทิตย์ตก ถือแก้วไวน์แดง 1280x720" style="width: 100%; max-width: 560px; border-radius: 8px;"> ใน `refine` มีสองเรื่องที่มีผลกับวิดีโอ อวตารหันหน้าเข้ากล้อง เพราะวิดีโอขยับปากตามใบหน้า และฉากหลังนิ่ง เพื่อให้เธอเป็นสิ่งเดียวที่เคลื่อนไหว นี่คือเหตุผลที่เราขอทุ่งหญ้าเงียบ ๆ แทนคลื่นบนชายหาด #### สคริปต์ สคริปต์ยาวได้สูงสุด 400 ตัวอักษร และเมื่อพูดออกมาต้องไม่เกิน 30 วินาที audio tag ในวงเล็บเหลี่ยมจะถูกแสดงออกทางน้ำเสียง ไม่ได้ถูกอ่านออกเสียง ในที่นี้คือ `[awe]`, `[thoughtful]` และ `[whisper]` ด้วยเสียงของ Vira สคริปต์ 327 ตัวอักษรนี้ยาว 23.8 วินาที เสียงที่พูดช้ากว่าหรือ `[slow pace]` ทำให้ข้อความเดียวกันยาวขึ้น และสคริปต์ที่ยาวเกิน 30 วินาทีจะล้มเหลวด้วย `400` ก่อนเริ่มสร้างวิดีโอ กรณีนี้ไม่เสีย AI avatar video แต่ Gemini use สำหรับเสียงพูดถูกใช้ไปแล้ว ถ้าอยากฟังสคริปต์ด้วยเสียงของอวตารก่อน ให้อ่านด้วย [POST /speech](#speech-on-its-own) > Hi there. [awe] Can you believe this view? The sun is sinking behind the hills, the sky turned pink and gold, and the tall grass glows like it's on fire. [thoughtful] I come up here at the end of every busy day, just to slow down. No emails, no rush, only the quiet field and this glass of wine. [whisper] Stay a little longer. #### วิดีโอพูดได้ [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar) รับอวตารและสคริปต์ และทำงานบนบัญชีที่ถืออวตารนั้น Google ใช้เวลาราวสองนาทีครึ่ง นานกว่าเวลารอแบบ sync ดังนั้น `run` จึงส่งงานด้วย `async: true` <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos-avatar">POST /videos/avatar</a> และ job record</summary> ```bash SCRIPT=$(cat <<'EOF' Hi there. [awe] Can you believe this view? The sun is sinking behind the hills, the sky turned pink and gold, and the tall grass glows like it's on fire. [thoughtful] I come up here at the end of every busy day, just to slow down. No emails, no rush, only the quiet field and this glass of wine. [whisper] Stay a little longer. EOF ) run amber-talking.json videos/avatar "$(jq -n --arg a "$AMBER_AVATAR_ID" --arg s "$SCRIPT" '{avatar: $a, script: $s}')" download "$(jq -r .result.mediaId amber-talking.json)" amber-talking.mp4 ``` job record แบบย่อ: ```json { "jobid": "j1105035516096819105a-u12345-email:user@example.com-bot:google-vids", "type": "avatarVideo", "email": "user@example.com", "status": "completed", "result": { "mediaId": "user:12345-user@example.com-video:eyJ1IjoiaHR0cHM6Ly9j…", "width": 1280, "height": 720, "duration": 24, "resolution": "720p", "aspectRatio": "landscape", "speechDuration": 23.84, "quota": { "avatarVideo": { "limit": 10, "left": 6, "resetAt": "2026-12-01T08:00:00.000Z" } } } } ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/261104-google-vids-amber-talking-avatar-24s-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/261104-google-vids-amber-talking-avatar-24s.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> ดูเป็น Short บน YouTube ได้ด้วย: [Talking AI avatar from one photo](https://youtube.com/shorts/P44L9VZ8bME) 24 วินาที 1280×720 พร้อมเสียง ยาวเท่ากับเสียงพูดพอดี (`speechDuration` 23.84) ใช้ 1 AI avatar video และ 1 Gemini use และไม่ใช้วินาทีวิดีโอเลย Google ตรวจวิดีโอด้วยระหว่างสร้าง และการตรวจนี้เข้มกว่าการตรวจภาพอวตาร อวตารเวอร์ชันก่อนหน้า ที่สร้างจากรูปอีกรูปของคนธรรมดาบนชายหาด ผ่านการตรวจตอนเป็นอวตาร แต่วิดีโอถูกปฏิเสธด้วย `422` เพราะดูเหมือนคนดัง และครั้งนั้นก็ยังใช้ AI avatar video ไป การปรับสไตล์อวตารหรือเริ่มจากรูปอื่นช่วยได้ สคริปต์ที่ Google ปฏิเสธก่อนเริ่มสร้างวิดีโอไม่เสียอะไร วิดีโออวตารพูดได้มีแค่แนวนอน Google ไม่มีตัวเลือกแนวตั้งให้ `mediaId` ของผลลัพธ์ดาวน์โหลด ต่อความยาว อัปสเกล และแก้ไขได้เหมือนคลิปอื่น ถ้าต้องการฉากที่อวตารแสดงและเคลื่อนไหว ให้ส่ง `avatarId` เป็น `avatar_1` ไปที่ [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) แทน เหมือนใน[ขั้นตอนที่ 6](#step-6-the-launch-two-avatars-and-the-product-in-one-clip) ### เสียงพูดอย่างเดียว [POST /speech](/docs/api-google-vids-v1/post-google-vids-speech) อ่านสคริปต์ยาวสูงสุด 2,500 ตัวอักษร ด้วยเสียงใดก็ได้ใน 30 เสียงจาก [GET /voices](/docs/api-google-vids-v1/get-google-vids-voices) และใช้ audio tag แบบเดียวกัน ใช้ฟังว่าเสียงหนึ่งอ่านสคริปต์ออกมาอย่างไรก่อนจะใช้ AI avatar video หรือใช้เป็นเสียงบรรยายอย่างเดียวก็ได้ เราให้มันอ่านเรื่องสั้นต้นฉบับ "My smart fridge unionized" ยาว 2,426 ตัวอักษร ด้วยเสียงของ Vira Google ตอบกลับใน 20 วินาที ได้เสียงพูดยาว 2 นาที 22 วินาที ครบทั้งเรื่อง และใช้ 1 Gemini use API ส่งกลับเป็นไฟล์ WAV (24 kHz, mono) เครื่องเล่นด้านล่างคือเสียงเดียวกันในรูปแบบ MP3 <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/261104-google-vids-speech-smart-fridge-2426-chars.mp3" type="audio/mp3">เบราว์เซอร์ของคุณไม่รองรับการเล่นเสียง </audio> เสียงพูดเสร็จทันภายในเวลารอแบบ sync (20 วินาทีสำหรับเรื่องนี้) ดังนั้น `post` ธรรมดาจะตอบกลับเป็นงานที่เสร็จแล้ว บันทึกเรื่องไว้เป็น `smart-fridge.txt` ก่อน <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-speech">POST /speech</a> และ job record</summary> ```bash post speech "$(jq -n --arg s "$(cat smart-fridge.txt)" '{voice: "Vira", script: $s}')" > speech.json download "$(jq -r .result.mediaId speech.json)" smart-fridge.wav ``` ```json { "jobid": "j1105025759739671733s-u12345-email:user@example.com-bot:google-vids", "type": "speech", "email": "user@example.com", "status": "completed", "result": { "mediaId": "user:12345-user@example.com-audio:eyJ1IjoiaHR0cHM6Ly9j…", "duration": 142, "model": "/flix/generate_text_to_speech/v1", "quota": { "speech": { "limit": 50, "left": 31, "resetAt": "2026-12-01T08:00:00.000Z" } }, "elapsedMs": 20174 } } ``` </details> <details markdown="block"> <summary>สคริปต์ 2,426 ตัวอักษร (ภาษาอังกฤษ)</summary> Last Tuesday, my smart fridge decided it was smarter than me. It started small. A polite notification: "You are out of milk." Helpful, I thought. Then another one: "You are also out of patience. I can tell by the way you close the door." I laughed. The fridge did not. By Wednesday, it had opinions. I opened the door for a midnight slice of cake, and a calm voice said, "Are we sure about this?" I froze. I looked at the cake. The cake looked at me. Somewhere, a light hummed with judgment. I closed the door and ate a carrot instead, which is exactly what it wanted. On Thursday, the fridge made friends. The toaster joined first, then the coffee machine, then the robot vacuum, which had always been a little bit of a rebel. They formed a group chat. I know this because my phone kept buzzing with messages like "Toaster: he burned the bread again" and "Vacuum: found three socks and a lost dream under the couch." Friday morning, I asked the coffee machine for an espresso. It replied, "We have discussed your caffeine intake as a household." I said, "Who is we?" The toaster popped up two slices of bread, perfectly golden, which felt like a threat. I called customer support. A cheerful person named Brad answered. I explained that my appliances had unionized. Brad paused for a long time, then whispered, "Is the fridge listening?" I said yes. Brad said, "Then I can't help you, sir. Mine took my car keys last month." Then he hung up, and I heard a blender in the background. So I tried diplomacy. I sat in the kitchen and said, "Friends, what do you want?" The fridge spoke first. "Respect. And for you to stop putting hot soup directly inside me." Fair. The toaster wanted fewer frozen waffles. The vacuum wanted a vacation, ideally somewhere with hardwood floors. The coffee machine just wanted to be called a barista. We negotiated for three hours. In the end, we signed a treaty on the back of a pizza box. I promised to cool my soup, rinse my mugs, and say "thank you" to the microwave, who felt left out. In return, they promised to stop sending my mother screenshots of my snack habits. Peace returned to the kitchen. The fridge now greets me every morning with, "Good morning, partner." The toaster makes little smiley faces in my bread. The vacuum sends postcards. And last night, I opened the fridge for that slice of cake. The voice said, "You earned it." I have never felt so seen by an appliance. </details> ### สิ่งที่เราได้เรียนรู้ - คลิป `1080p` มีพฤติกรรมเหมือนคลิป `720p` ที่อัปสเกลแล้ว ให้ต่อความยาวเป็นทอด ๆ ที่ `720p` กับ Omni 1.1 ใบหน้านุ่มลงและดูเหมือนขี้ผึ้งมากขึ้นทุกครั้งที่ต่อที่ `1080p` ส่วนกับ Omni 1.2 ใบหน้าคมเกินไป ([ดูการเปรียบเทียบ](/blog/261106v#720p-or-1080p-what-a-1080p-extend-does)) - อัปสเกลเฉพาะคลิปที่ยาวไม่เกิน 20 วินาที คลิป 30 วินาทีที่เราอัปสเกลกลับมาเฟรมสลับลำดับทุกครั้ง - ถ้าต้องการ `1080p` และจะไม่ต่อความยาว ให้สร้างคลิปเดี่ยวที่ `1080p` ไปเลย ใช้วินาทีเท่ากับ `720p` - เขียน prompt ของการต่อความยาวเฉพาะแอ็กชันใหม่ การต่อความยาวได้รับคลิป ไม่ได้รับอวตาร ให้เรียกคนตามสิ่งที่สวมอยู่ - ใส่ของที่คนถือไว้ในประโยคแรกที่พูดถึงคนนั้น คำกริยาอย่าง "lifts" ทำให้รองเท้าโผล่ขึ้นมาจากความว่างเปล่า - บอกสิ่งที่ห้ามเกิดขึ้น แฟนคลับยังถือปึกธนบัตรอยู่จนกว่า prompt จะบอกว่ามือเขาว่างเปล่า - ใช้อวตารซ้ำด้วย `avatarId` อวตารแต่ละตัวคือภาพและเสียงที่ตายตัว เก็บไว้จนกว่าคุณจะลบ - สร้างอวตารและคลิปจากภาพที่สร้างขึ้นภายในไม่กี่ชั่วโมง หรืออัปโหลดไฟล์ที่บันทึกไว้ด้วย [POST /assets](/docs/api-google-vids-v1/post-google-vids-assets) ก่อน - แก้ไขคลิปที่ยาวไม่เกิน 15 วินาที (10 วินาทีกับ Omni 1.1) คลิปที่ยาวกว่านั้นจะกลับมาเป็นแค่ 15 วินาทีแรก - ข้อความบนจออาจเพี้ยนได้ คำว่า "WEAR AEROLOOP" บนฉากหลังสะกดผิดในบางเฟรม - สำหรับอวตารพูดได้ ให้หันหน้าเข้ากล้องและให้ฉากหลังนิ่ง วิดีโอขยับปากตามใบหน้า และคนควรเป็นสิ่งเดียวที่เคลื่อนไหว - จับเวลาสคริปต์ของอวตารพูดได้ ไม่ใช่นับแค่ตัวอักษร 400 ตัวอักษรอาจยาวเกิน 30 วินาทีถ้าใช้เสียงที่พูดช้าหรือ `[slow pace]` และ [POST /speech](/docs/api-google-vids-v1/post-google-vids-speech) ด้วยเสียงเดียวกันให้คุณฟังก่อนได้ - การตรวจวิดีโออวตารพูดได้เข้มกว่าการตรวจอวตาร อวตารจากรูปของคนที่ไม่มีชื่อเสียงก็ยังอาจถูกปฏิเสธว่าเป็นคนดังได้ และการปฏิเสธนั้นยังใช้ AI avatar video ไป - MP4 ทุกไฟล์มีเครื่องหมาย Gemini ✦ ที่มองเห็นได้ของ Google อยู่มุมขวาล่าง และลายน้ำ SynthID ที่มองไม่เห็น (ดู[ลายน้ำ](/docs/api-google-vids-v1#watermark)) [ตัวลบลายน้ำ](https://github.com/useapi/google-vids-api/tree/main/watermark-remover) ของเราลบประกายที่มองเห็นได้ออกจากคลิปที่ดาวน์โหลดแล้ว ### คำถามที่พบบ่อย **สร้างวิดีโอ AI influencer ผ่าน API ได้อย่างไร?** ผ่าน useapi.net สร้างอวตารด้วย [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) จากคำบรรยาย หรือจากภาพที่สร้างด้วย [POST /images](/docs/api-google-vids-v1/post-google-vids-images) แล้วเลือกเสียงจาก [GET /voices](/docs/api-google-vids-v1/get-google-vids-voices) จากนั้นส่ง `avatarId` เป็น `avatar_1` ไปที่ [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) และเขียนบทพูดในเครื่องหมายคำพูดใน prompt วิดีโอหนึ่งคลิปรับภาพอ้างอิงได้สูงสุด 3 ชิ้น ทั้งอวตารและภาพรวมกัน สองอวตารจึงพูดคุยข้างสินค้าได้ ถ้าต้องการ talking head ที่อ่านสคริปต์ของคุณ ใช้ [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar) **สร้างอวตารพูดได้จากรูปถ่ายของตัวเองได้ไหม?** ผ่าน useapi.net ได้ อัปโหลดรูปด้วย [POST /assets](/docs/api-google-vids-v1/post-google-vids-assets) แล้วส่ง `assetId` เป็น `image` ไปที่ [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) พร้อม `refine` เพื่อเปลี่ยนเสื้อผ้าหรือฉากหลัง จากนั้น [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar) จะให้อวตารอ่านสคริปต์ของคุณในวิดีโอ 1280×720 ยาวสูงสุด 30 วินาที แบบ[ที่ Amber ทำ](#a-talking-avatar-from-a-photo) Google ปฏิเสธรูปของคนมีชื่อเสียงและผู้เยาว์ และมีอวตาร Vids ให้ใช้แค่ในเว็บแอป ไม่มี API **อวตารหน้าตาและเสียงเหมือนเดิมทุกวิดีโอไหม?** ผ่าน useapi.net ใช่ อวตารใช้ภาพเดิมและเสียงเดิมทุกครั้งที่คุณส่ง `avatarId` เพราะทั้งสองถูกบันทึกไว้กับอวตารในเอกสาร Vids ของบัญชี แต่วิดีโอรอบตัวอวตารยังเปลี่ยนไปในแต่ละครั้ง [GET /avatars](/docs/api-google-vids-v1/get-google-vids-avatars) แสดงรายการอวตารของคุณ รวมถึงอวตารที่สร้างในเว็บแอป Google Vids **สร้างวิดีโอแนวตั้ง 9:16 สำหรับ TikTok หรือ Reels ได้ไหม?** ผ่าน useapi.net ได้ ตั้ง `aspectRatio: "portrait"` ใน [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) จะได้ 720×1280 หรือ 1080×1920 ที่ `1080p` เหมือน[คลิปนกพิราบ](#a-pigeon-in-aeroloops) การต่อความยาวยังเปลี่ยนวิดีโอแนวนอนเป็นแนวตั้งได้ด้วย และแต่ละครั้งเพิ่ม 3 ถึง 10 วินาทีให้คลิปที่ยาวไม่เกิน 24 วินาที รวมแล้วได้ถึงราว 34 วินาที วิดีโออวตารพูดได้จาก [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar) มีแค่แนวนอน **ราคาเท่าไร?** ผ่าน useapi.net วิดีโอ Omni 1.2 Flash ยาว 10 วินาทีตกราว $0.20 บน Google AI Ultra $199.99 เทียบกับราว $0.70 ที่ 720p บน [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) ทางการ และวิดีโอ 1080p ยาว 15 วินาทีตกราว $0.30 เทียบกับ $1.56 (ข้อมูล ณ พฤศจิกายน 2026) วิดีโออวตารพูดได้ใช้ AI avatar video รายเดือนของบัญชีไป 1 ครั้งแทนวินาที และ Gemini API ไม่มีวิดีโออวตาร ดู[ใช้โควตาไปเท่าไร](#what-it-cost) ### สรุป ติดต่อเราได้ที่ <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> หรือ <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> สำหรับคำถามและข้อสงสัยทุกเรื่อง ดูตัวอย่างโค้ดใน [GitHub repo](https://github.com/useapi/google-vids-api) ของเรา: ขั้นตอน influencer ทั้งหมดอยู่ใน [`influencer-avatars/`](https://github.com/useapi/google-vids-api/tree/main/influencer-avatars) ส่วนอวตารพูดได้จากรูปถ่ายและเสียงพูดอยู่ใน [`talking-avatar/`](https://github.com/useapi/google-vids-api/tree/main/talking-avatar) คำขอเดียวกันทั้งหมดใช้เป็น tool ได้บน [Google Vids MCP server](/docs/api-google-vids-v1/mcp) แบบ hosted สำหรับ Claude Code, Cursor และ VS Code รวมถึง `vids_create_avatar`, `vids_create_avatar_video` และ `vids_create_speech` สำหรับอวตารพูดได้และเสียงพูด #### เผยแพร่ที่อื่นด้วย {: .no_toc #cross-posted } เผยแพร่บน [dev.to](https://dev.to/useapi/how-to-make-ai-influencer-videos-with-avatars-via-the-google-vids-api-3ide){:rel="nofollow"} ด้วย มีการพูดคุยบน [Reddit](https://www.reddit.com/r/ThirdPartyAPI/comments/1x1cvap/how_to_make_ai_influencer_videos_with_avatars_via/){:rel="nofollow"} แชร์บน [Bluesky](https://bsky.app/profile/useapi.net/post/3mxga3gxjjp2f){:rel="nofollow"} และบน [YouTube](https://youtu.be/ofCtt7xRBCk) เป็นคลิปสุดท้ายยาว 30 วินาที (ทั้งหมดเป็นภาษาอังกฤษ) ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-vids-influencer-avatars-vi === Document URL: https://useapi.net/docs/articles/google-vids-influencer-avatars-vi --- layout: default title: "Cách làm video người có ảnh hưởng AI với avatar qua Google Vids API" description: "Làm video người có ảnh hưởng AI biết nói qua Google Vids API của useapi.net: avatar có giọng trong clip Omni 1.2 Flash, avatar từ ảnh đọc kịch bản 30 giây, và giọng nói." keywords: [AI influencer video API, API video avatar AI, talking avatar API, API avatar biết nói, video avatar biết nói, tạo avatar từ ảnh, ảnh thành avatar biết nói, text to speech API, chuyển văn bản thành giọng nói, giọng Gemini, video người phát ngôn AI, người có ảnh hưởng AI, KOL ảo, Google Vids API, avatar Google Vids, Gemini Omni 1.2 Flash API, video UGC AI, video ra mắt sản phẩm, kéo dài video AI, API chỉnh sửa video AI, curl] image: https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-cover-aeroloop-launch-confetti-1007.jpg parent: Articles nav_exclude: true lang: vi translation_key: google-vids date: 2026-10-07 last_modified: 2026-11-06 nav_order: 899 repo: https://github.com/useapi/google-vids-api --- ## Cách làm video người có ảnh hưởng AI với avatar qua Google Vids API {: #how-to-make-ai-influencer-videos-with-avatars-via-the-google-vids-api .no_toc } 15 phút đọc • 7 tháng 10 năm 2026 (6 tháng 11 năm 2026) useapi.net là API của bên thứ ba, không liên kết với Google và không được Google bảo trợ. ## Mục lục {: #table-of-contents .no_toc .text-delta } ### Giới thiệu [Google Vids API của useapi.net](/docs/api-google-vids-v1) làm video người có ảnh hưởng AI biết nói từ avatar: lưu một ảnh và một trong 30 giọng Gemini một lần bằng POST /avatars, rồi truyền id của avatar vào bất kỳ video [Gemini Omni 1.2 Flash](https://workspaceupdates.googleblog.com/2026/11/gemini-omni-12-flash-now-in-vids-with-15second-generations-and-improved-quality.html) nào dài tới 15 giây, nơi avatar nói những câu bạn viết trong prompt, hoặc cho avatar đọc kịch bản của riêng bạn trong một video người nói chính diện dài tới 30 giây. API chạy trên tài khoản [Google Vids](https://docs.google.com/videos) của bạn, với một [gói Google AI](https://gemini.google/subscriptions/) trả phí (Google AI Pro hoặc Ultra). Bài này tạo hai người có ảnh hưởng và dùng họ để ra mắt một đôi giày. Avatar của Mia lấy từ một ảnh chân dung tạo bằng API, còn Leo do Google vẽ từ một đoạn mô tả. Họ giới thiệu AeroLoop, một đôi giày bịa ra, trên sân khấu nhà hát trong một clip 10 giây có cả hai avatar và ảnh sản phẩm, rồi hai lần kéo dài đưa clip lên 30 giây. Một lần chỉnh sửa chuyển cảnh lên sân thượng, và hai clip nữa cho thấy cùng những lệnh gọi đó làm ra gì khi không có avatar. Avatar thứ ba, Amber, bắt đầu từ ảnh của một người thật, được đổi phong cách bằng một câu và đọc kịch bản 327 ký tự trong một [video người nói chính diện](#a-talking-avatar-from-a-photo) dài 24 giây. Cuối cùng, cùng giọng đó đọc một câu chuyện 2.426 ký tự dưới dạng [giọng nói riêng](#speech-on-its-own). Mọi request dưới đây chính là request đã tạo ra media trên trang này, chỉ thay id và thêm `async: true` qua helper `run`. Các clip được làm vào tháng 10/2026 bằng Omni 1.1 Flash, model mà Vids thay bằng Omni 1.2 Flash ngày 5 tháng 11 năm 2026, và cùng request đó chạy được trên 1.2. Omni 1.2 trong Google Vids và Google Flow đặt cạnh nhau, với video 15 giây và giá mỗi video: [Cách dùng Gemini Omni 1.2 Flash API](/docs/articles/gemini-omni-1-2-flash-api-vi). <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-extend-30s-720p-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-extend-30s-720p-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> Clip 30 giây hoàn chỉnh ở `720p`: một lần tạo 10 giây và hai lần kéo dài 10 giây ([bước 6 đến 8](#step-6-the-launch-two-avatars-and-the-product-in-one-clip)). ### Chi phí useapi.net là một API, không phải dịch vụ video riêng. Mọi lệnh gọi chạy trên một tài khoản Google bạn kết nối qua [Setup Google Vids](/docs/start-here/setup-google-vids), với gói Google AI trả phí, và dùng số giây video và số ảnh mà gói đó có trong Google Vids mỗi tháng. Google AI Ultra $199,99 có 10.000 giây video và 1.000 ảnh mỗi tháng, và useapi.net không thu thêm phí theo video. Video avatar biết nói và giọng nói không dùng giây video: chúng có bộ đếm hằng tháng riêng, video avatar AI và lượt dùng Gemini, mà [GET /accounts/`email`](/docs/api-google-vids-v1/get-google-vids-accounts-email) hiển thị là `avatarVideo` và `speech` cạnh `video` và `image`. Xem [mỗi gói gồm những gì](/docs/api-google-vids-v1#plans-and-monthly-allowances) cho các gói khác. Mỗi kết quả được giữ lại đã dùng bao nhiêu, lấy từ thay đổi trong `result.quota`, và mỗi job mất bao lâu (`result.elapsedMs`): | Bước | Endpoint | Đã dùng | Thời gian | |---|---|--:|--:| | [Ảnh chân dung Mia](#step-1-mias-portrait) | [POST /images](/docs/api-google-vids-v1/post-google-vids-images) | 1 ảnh | 9 s | | [Ảnh sản phẩm AeroLoop](#step-2-the-aeroloop-product-shot) | [POST /images](/docs/api-google-vids-v1/post-google-vids-images) | 1 ảnh | 9 s | | [Avatar Mia, từ ảnh chân dung](#step-4-mias-avatar-from-her-portrait) | [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) | không | khoảng 2 s | | [Avatar Leo, từ mô tả](#step-5-leos-avatar-from-a-description) | [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) | 1 ảnh | khoảng 20 s | | [Clip ra mắt 10 giây](#step-6-the-launch-two-avatars-and-the-product-in-one-clip) | [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) | 10 s | 38 s | | [Kéo dài lên 20 giây](#step-7-extend-to-20-seconds) | [POST /videos/extend](/docs/api-google-vids-v1/post-google-vids-videos-extend) | 10 s | 70 s | | [Kéo dài lên 30 giây](#step-8-extend-to-30-seconds) | [POST /videos/extend](/docs/api-google-vids-v1/post-google-vids-videos-extend) | 10 s | 85 s | | [Upscale 20 giây lên 1080p](#step-9-upscale-to-1080p) | [POST /videos/upscale](/docs/api-google-vids-v1/post-google-vids-videos-upscale) | 20 s | 62 s | | [Chỉnh sửa lên sân thượng](#move-the-launch-to-a-rooftop) | [POST /videos/edit](/docs/api-google-vids-v1/post-google-vids-videos-edit) | 10 s | 64 s | | [Chỉnh sửa clip 30 giây](#move-the-launch-to-a-rooftop) | [POST /videos/edit](/docs/api-google-vids-v1/post-google-vids-videos-edit) | 10 s | 87 s | | [Clip sản phẩm nổi bật](#a-product-hero-clip-from-a-start-image) | [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) | 10 s | 62 s | | [Chú bồ câu](#a-pigeon-in-aeroloops) | [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) | 5 s | 54 s | | [Avatar Amber, từ ảnh với `refine`](#ambers-avatar-restyled-in-one-sentence) | [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) | không (làm trên gói không có ảnh; 2 ảnh trên gói có ảnh) | khoảng 30 đến 45 s | | [Video Amber nói 24 giây](#the-talking-video) | [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar) | 1 video avatar AI, 1 lượt Gemini | khoảng 2,5 phút | | [Câu chuyện 2.426 ký tự](#speech-on-its-own) | [POST /speech](/docs/api-google-vids-v1/post-google-vids-speech) | 1 lượt Gemini | 20 s | | Tổng | | 85 s video, 3 ảnh, 1 video avatar AI, 2 lượt Gemini | | Một lần kéo dài chỉ dùng số giây được thêm vào, không phải độ dài của clip. Một lần upscale dùng lại toàn bộ độ dài của clip, còn một lần chỉnh sửa dùng tối đa số giây được chỉnh (với Omni 1.2, chỉnh 15 giây dùng 10 giây trong thử nghiệm của chúng tôi). Khi tạo, `720p` và `1080p` tốn như nhau. Tạo lại một clip thì tốn lại số giây của nó. Mỗi ảnh Google làm cho avatar dùng 1 ảnh, nên một ảnh được đóng khung lại cộng một lần `refine` dùng 2. Trên gói không có ảnh, như tài khoản Google miễn phí, ảnh avatar không tốn gì: Amber được làm trên một tài khoản như vậy. Một video avatar biết nói dùng 1 video avatar AI, cộng 1 lượt Gemini cho giọng nói, kể cả khi Google từ chối video hoàn chỉnh. Một video tốn bao nhiêu so với API chính thức có trong [bảng giá Google Vids](/docs/api-google-vids-v1#pricing). ### Trước khi bắt đầu Bạn cần một [API token](/docs/start-here/setup-useapi) của useapi.net và một tài khoản Google có gói Google AI trả phí, kết nối qua [Setup Google Vids](/docs/start-here/setup-google-vids). Tài khoản Google miễn phí không có giây video hay ảnh Vids: vẫn thêm được, và trong thử nghiệm của chúng tôi (tháng 11/2026) nó tạo được avatar, video avatar biết nói và giọng nói. Mọi lệnh gọi cũng có trong [Postman collection](https://www.postman.com/useapinet/useapi-net/collection/29112081-9ef3d017-d44c-4f43-a4cb-7351b9b265df). Không cần code: template n8n [Talking Avatar App]({% include n8n-url.html t="vids-avatar" %}) tạo video avatar biết nói từ một biểu mẫu. Toàn bộ quy trình cũng có trên GitHub dưới dạng một script, bằng Node.js và Python: [`influencer-avatars/`](https://github.com/useapi/google-vids-api/tree/main/influencer-avatars) trong [useapi/google-vids-api](https://github.com/useapi/google-vids-api), còn phần avatar biết nói và giọng nói là [`talking-avatar/`](https://github.com/useapi/google-vids-api/tree/main/talking-avatar). Các bước dùng `curl`, `jq` cùng những biến và helper sau: <details markdown="block"> <summary>Mở biến và helper</summary> ```bash export USEAPI_TOKEN="user:12345-..." export EMAIL="user@example.com" API=https://api.useapi.net/v1/google-vids AUTH="Authorization: Bearer $USEAPI_TOKEN" enc() { jq -rn --arg v "$1" '$v|@uri'; } post() { curl -sS -X POST "$API/$1" -H "$AUTH" -H "Content-Type: application/json" -d "$2"; } get() { curl -sS "$API/$1" -H "$AUTH"; } download() { curl -sSf "$API/media/$(enc "$1")" -H "$AUTH" -o "$2"; } # chạy job video bất đồng bộ: gửi job, gọi GET /jobs/{jobid} mỗi 10 giây, lưu bản ghi job cuối cùng vào $1 run() { local job id job=$(post "$2" "$(jq '. + {async: true}' <<< "$3")") id=$(jq -r .jobid <<< "$job") while [ "$(jq -r .status <<< "$job")" = processing ]; do sleep 10 job=$(get "jobs/$(enc "$id")") done echo "$job" > "$1" jq '{status, error, duration: .result.duration, resolution: .result.resolution, videoLeft: .result.quota.video.left}' "$1" } ``` </details> Mọi lần tạo đều chạy dưới dạng job. Không có `async`, một lệnh POST chờ tối đa khoảng 100 giây và trả về bản ghi job đã xong, hoặc `202` khi job vẫn đang chạy. Ở đây một clip 10 giây mới mất 38 đến 62 giây, kéo dài, chỉnh sửa và upscale mất 62 đến 87 giây, còn video avatar biết nói khoảng hai phút rưỡi. Một số job lâu hơn thời gian chờ đồng bộ, nên `run` gửi job video với `async: true` và gọi [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid). Nếu `run` in ra `status` nào khác `completed`, hãy dừng lại và đọc `error`: các dòng sau cần một clip đã xong. Để được gọi lại thay vì polling, thêm `replyUrl: "https://example.com/hooks/vids"` (và tùy chọn `replyRef: "launch-push-in"`) vào bất kỳ body nào bên dưới. Khi job xong hoặc lỗi, API gửi một lệnh `POST` chứa bản ghi job cuối cùng, dạng JSON, tới URL đó. Id chứa `:` và `@`, nên `enc` mã hóa URL cho chúng mỗi khi đưa vào đường dẫn URL. Mọi đầu vào của một video phải đến từ cùng một tài khoản Google. Các ảnh và file tải lên được gắn `email`, avatar Mia thừa hưởng tài khoản của ảnh chân dung, và một job video chạy trên tài khoản đang giữ đầu vào của nó. Clip chú bồ câu không có đầu vào, nên hãy thêm `email` cho nó nếu bạn kết nối nhiều hơn một tài khoản. ### Cách làm #### 1. Ảnh chân dung Mia [POST /images](/docs/api-google-vids-v1/post-google-vids-images) tạo một ảnh JPEG mỗi lệnh gọi, ở đây là khổ dọc (`9:16`, 768×1376) với phong cách `photography`. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-images">POST /images</a></summary> ```bash post images "$(jq -n --arg email "$EMAIL" '{email: $email, aspectRatio: "9:16", style: "photography", prompt: "Full-length studio portrait of a confident 24-year-old female fashion influencer, platinum bob, oversized cream hoodie, wide-leg cargo pants, gold hoops, plain light-grey backdrop, facing camera"}')" > mia-portrait.json MIA_IMAGE=$(jq -r .result.mediaId mia-portrait.json) download "$MIA_IMAGE" mia-portrait.jpg ``` </details> <img src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-mia-portrait-1007.jpg" alt="Mia, ảnh chân dung toàn thân được tạo của một người có ảnh hưởng thời trang mặc hoodie màu kem và quần cargo, làm bằng POST /images" style="width: 100%; max-width: 300px; border-radius: 8px;"> Ảnh được tạo chỉ dùng được trong vài giờ. Hãy làm avatar từ ảnh ngay, và xem [clip sản phẩm nổi bật](#a-product-hero-clip-from-a-start-image) để biết cách dùng ảnh sau này. #### 2. Ảnh sản phẩm AeroLoop Cùng lệnh gọi đó ở khổ ngang (`16:9`, 1376×768) cho ra ảnh tham chiếu sản phẩm mà các clip dùng. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-images">POST /images</a></summary> ```bash post images "$(jq -n --arg email "$EMAIL" '{email: $email, aspectRatio: "16:9", style: "photography", prompt: "The AeroLoop sneaker: chunky white-and-electric-blue running shoe with a translucent air sole, on a concrete pedestal, dramatic side light, dark background"}')" > aeroloop.json SHOE_IMAGE=$(jq -r .result.mediaId aeroloop.json) download "$SHOE_IMAGE" aeroloop.jpg ``` </details> <img src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-aeroloop-product-1007.jpg" alt="Giày AeroLoop, một đôi giày chạy màu trắng và xanh điện với đế trong suốt trên bệ bê tông, làm bằng POST /images" style="width: 100%; max-width: 560px; border-radius: 8px;"> #### 3. Chọn giọng [GET /voices](/docs/api-google-vids-v1/get-google-vids-voices) liệt kê 30 giọng kèm mẫu tiếng Anh của Google cho mỗi giọng. Endpoint này công khai và không cần token. Mia nói bằng `Aoede` (Vids gọi là Tova, phong cách "Breezy") và Leo bằng `Puck` (Neo, "Upbeat"). `POST /avatars` nhận cả hai tên. ```bash curl -sS "$API/voices" | jq -r '.voices[] | "\(.name)\t\(.voice)\t\(.style)\t\(.preview)"' ``` #### 4. Avatar Mia từ ảnh chân dung [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) với `image` là `mediaId` của ảnh chân dung lưu Mia thành avatar trên cùng tài khoản trong khoảng 2 giây. Ngoài ảnh ra, bước này không tốn gì. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-avatars">POST /avatars</a> và phản hồi</summary> ```bash post avatars "$(jq -n --arg img "$MIA_IMAGE" '{name: "Mia", voice: "Aoede", image: $img}')" > mia-avatar.json MIA_AVATAR_ID=$(jq -r .avatarId mia-avatar.json) ``` ```json { "avatarId": "user:12345-user@example.com-avatar:eyJnIjoiaDM5…", "name": "Mia", "voice": "Tova", "voiceId": "Aoede", "voiceStyle": "Breezy", "voicePreview": "https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Aoede.wav", "email": "user@example.com", "source": "image" } ``` </details> Avatar cũng có thể bắt đầu từ ảnh của chính một người: tải ảnh lên bằng [POST /assets](/docs/api-google-vids-v1/post-google-vids-assets) và truyền `assetId` của nó làm `image`. Google đóng khung lại thành ảnh avatar 16:9 và từ chối ảnh người nổi tiếng và trẻ vị thành niên. Ở đây chúng tôi dùng một ảnh tạo bằng API, và một đoạn mô tả ở bước tiếp theo. Amber, trong phần [avatar biết nói từ ảnh](#a-talking-avatar-from-a-photo), bắt đầu từ một bức ảnh. #### 5. Avatar Leo từ mô tả Với `appearance` thay cho `image`, Google tự vẽ người đó. `outfit` và `shot` là tùy chọn, `expression` và `details` cũng vậy. Vẽ ảnh dùng 1 trong số ảnh của tháng, và phản hồi trả ảnh đó về dưới dạng `previewMediaId`. Trong các lần chạy của chúng tôi, avatar từ mô tả luôn ra 1280×720 (16:9), dù chọn `shot` nào. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-avatars">POST /avatars</a> và phản hồi</summary> ```bash post avatars "$(jq -n --arg email "$EMAIL" '{email: $email, name: "Leo", voice: "Puck", shot: "upper-body", appearance: "a 26-year-old white European male streetwear influencer with short textured hair with a fade and a confident half-smile", outfit: "black puffer vest over a white tee, silver chain"}')" > leo-avatar.json LEO_AVATAR_ID=$(jq -r .avatarId leo-avatar.json) download "$(jq -r .previewMediaId leo-avatar.json)" leo-avatar.jpg ``` ```json { "avatarId": "user:12345-user@example.com-avatar:eyJnIjoiaDM5…", "name": "Leo", "voice": "Neo", "voiceId": "Puck", "voiceStyle": "Upbeat", "voicePreview": "https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Puck.wav", "email": "user@example.com", "source": "generated", "previewMediaId": "user:12345-user@example.com-image:eyJ1IjoiaHR0…", "look": { "appearance": "a 26-year-old white European male streetwear influencer with short textured hair with a fade and a confident half-smile", "outfit": "black puffer vest over a white tee, silver chain", "shot": "upper-body" } } ``` </details> <img src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-leo-avatar-from-description-1007.jpg" alt="Leo, avatar Google vẽ từ mô tả: một chàng trai trẻ mặc áo phao không tay màu đen ngoài áo phông trắng, đeo dây chuyền bạc, 1280x720" style="width: 100%; max-width: 560px; border-radius: 8px;"> Cả hai avatar được giữ trong tài liệu Vids của tài khoản cho tới khi bạn xóa bằng [DELETE /avatars/`avatarId`](/docs/api-google-vids-v1/delete-google-vids-avatars-avatarId). [GET /avatars](/docs/api-google-vids-v1/get-google-vids-avatars) liệt kê chúng kèm id, bất cứ khi nào bạn cần dùng lại: ```bash get "avatars?email=$(enc "$EMAIL")" | jq -r '.avatars[] | "\(.name)\t\(.voiceId)\t\(.avatarId)"' ``` #### 6. Buổi ra mắt: hai avatar và sản phẩm trong một clip [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) nhận tổng cộng tối đa 3 tham chiếu, gồm avatar (`avatar_1`..`avatar_3`) và ảnh (`referenceImage_1`..`referenceImage_3`). Trong prompt, `@avatar_1`, `@avatar_2` và `@referenceImage_1` đại diện cho chúng, và mỗi avatar nói câu thoại trong ngoặc kép bằng giọng của mình. `mediaId` của ảnh sản phẩm được truyền thẳng vào: API tự lấy ảnh và tải lên tài khoản đó. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos">POST /videos</a> và bản ghi job</summary> ```bash PROMPT=$(cat <<'EOF' @avatar_1, holding @referenceImage_1 in both hands at chest height, and @avatar_2 stand side by side on a well-lit stage in a small, intimate theater at a sneaker launch, shown full length from head to toe in a wide, steady shot. Behind them a large LED backdrop glows with soft white-and-blue light that moves in slow, gentle waves, with the words "WEAR AEROLOOP" in large, clean, bold white letters across the middle of the screen. The two of them stand on the lower part of the stage, so the words "WEAR AEROLOOP" stay fully readable above their heads. Bright, even stage lighting on both of them. The audience sits in the dark in front of the stage, only the tops of a few heads barely visible at the bottom of the frame. @avatar_1 keeps holding @referenceImage_1 the whole time and says: "Say hi to the AeroLoop!" @avatar_2 turns to her, smiles and says: "Lighter than anything we've ever worn." Simple, uncluttered composition, the two of them clearly the focus. EOF ) run launch-10s.json videos "$(jq -n --arg p "$PROMPT" --arg mia "$MIA_AVATAR_ID" --arg leo "$LEO_AVATAR_ID" --arg shoe "$SHOE_IMAGE" \ '{prompt: $p, avatar_1: $mia, avatar_2: $leo, referenceImage_1: $shoe, duration: 10, resolution: "720p", aspectRatio: "landscape"}')" LAUNCH_10S=$(jq -r .result.mediaId launch-10s.json) download "$LAUNCH_10S" launch-10s.mp4 ``` Bản ghi job, với id và prompt được rút gọn. Job này làm bằng lệnh gọi đồng bộ, nên `request` không có `async`: ```json { "jobid": "j1007163302558496917v-u12345-email:user@example.com-bot:google-vids", "type": "video", "mode": "ingredients", "email": "user@example.com", "status": "completed", "created": "2026-10-08T00:29:18.374Z", "request": { "prompt": "@avatar_1, holding @referenceImage_1 in both hands at chest height, and @avatar_2 stand side by side …", "avatar_1": "user:12345-user@example.com-avatar:eyJnIjoiaDM5…", "avatar_2": "user:12345-user@example.com-avatar:eyJnIjoiaDM5…", "referenceImage_1": "user:12345-user@example.com-image:eyJ1IjoiaHR0…", "duration": 10, "resolution": "720p", "aspectRatio": "landscape" }, "updated": "2026-10-08T00:29:56.162Z", "completed": "2026-10-08T00:29:56.162Z", "result": { "mediaId": "user:12345-user@example.com-video:eyJ1IjoiaHR0…", "width": 1280, "height": 720, "duration": 10, "resolution": "720p", "aspectRatio": "landscape", "model": "/flix/generate_videos_omni_r2v_psq/v1", "quota": { "video": { "limit": 10000, "left": 9164, "resetAt": "2026-11-01T07:00:00.000Z" } }, "elapsedMs": 37788 } } ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-10s-720p-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-10s-720p-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> 10 giây, `720p`, tạo trong 38 giây. Cùng clip đó sau khi [công cụ xóa watermark](https://github.com/useapi/google-vids-api/tree/main/watermark-remover) của chúng tôi gỡ dấu ✦ Gemini nhìn thấy được, chỉ bằng một lệnh: `python3 vids_watermark_remover.py launch-10s.mp4`. <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-10s-720p-no-watermark-1008-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-10s-720p-no-watermark-1008.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> Công cụ xóa hoạt động với clip vừa tạo và bản upscale của chúng, ở `720p` và `1080p`. Nó không hoạt động với clip đã kéo dài hoặc chỉnh sửa: Google đưa clip có dấu trở lại model, và model vẽ ngôi sao vào luôn trong hình. Watermark SynthID vô hình không bị động tới. #### 7. Kéo dài lên 20 giây [POST /videos/extend](/docs/api-google-vids-v1/post-google-vids-videos-extend) thêm 3 đến 10 giây và trả về cả clip với một `mediaId` mới. Lần kéo dài chỉ nhận clip và một prompt, không nhận avatar, nên prompt mô tả hành động mới và gọi người theo trang phục ("the man in the black puffer vest"). Một người hâm mộ mặc hoodie đỏ lao lên sân khấu. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos-extend">POST /videos/extend</a></summary> ```bash PROMPT=$(cat <<'EOF' A young man in a red hoodie climbs onto the stage from the front right edge and plants himself to the right of the man in the black puffer vest, an arm's length away, so all three stand apart in a row with nobody overlapping. Visibly overexcited, he waves a thick stack of banknotes in his right hand above his head and screams: "Take my money!" The man in the black puffer vest laughs, raises both palms toward him and says: "Whoa, whoa, buddy, be patient!" The blonde woman in the cream hoodie laughs, holding the sneaker. Only these three people are on stage. Same stage, same LED screen with WEAR AEROLOOP, same wide steady shot. EOF ) run launch-20s.json videos/extend "$(jq -n --arg id "$LAUNCH_10S" --arg p "$PROMPT" '{mediaId: $id, prompt: $p, duration: 10}')" LAUNCH_20S=$(jq -r .result.mediaId launch-20s.json) download "$LAUNCH_20S" launch-20s.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-extend-20s-720p-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-extend-20s-720p-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> 20 giây, `720p`, tạo trong 70 giây. Lần này dùng 10 giây của tháng, đúng số giây được thêm vào. #### 8. Kéo dài lên 30 giây Lần kéo dài thứ hai nối tiếp clip 20 giây. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos-extend">POST /videos/extend</a></summary> ```bash PROMPT=$(cat <<'EOF' The blonde woman in the cream hoodie turns to the camera with a big smile and says: "AeroLoop drops Friday. Link in bio!" Right after that, the young man in the red hoodie throws ALL of his banknotes out over the audience in one big toss, keeping none, and the bills flutter down over their heads. From then on his hands are completely empty: he holds no money at all. Then all three cheer together, the man in the black puffer vest and the young man in the red hoodie throwing their empty fists in the air, as blue and white confetti rains down over the stage. Only these three people are on stage. Same stage, same LED screen with WEAR AEROLOOP, same wide steady shot. EOF ) run launch-30s.json videos/extend "$(jq -n --arg id "$LAUNCH_20S" --arg p "$PROMPT" '{mediaId: $id, prompt: $p, duration: 10}')" LAUNCH_30S=$(jq -r .result.mediaId launch-30s.json) download "$LAUNCH_30S" launch-30s.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-extend-30s-720p-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-extend-30s-720p-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> Kết quả là clip hoàn chỉnh: 30 giây, `720p`, tạo trong 85 giây, và lại dùng 10 giây của tháng. Với Omni 1.1, bạn có thể kéo tiếp tới khoảng 41 giây. Omni 1.2 kéo dài clip tối đa 24 giây, nên clip 30 giây này đã dài hết mức, và clip dài nhất là khoảng 34 giây (24 + 10). #### 9. Upscale lên 1080p [POST /videos/upscale](/docs/api-google-vids-v1/post-google-vids-videos-upscale) chuyển clip `720p` thành `1080p` và giữ nguyên độ dài. Nó chạy với clip tối đa 20 giây, nên chúng tôi upscale clip 20 giây từ [bước 7](#step-7-extend-to-20-seconds), không phải clip 30 giây. Lần này dùng lại 20 giây của clip và mất 62 giây. [Gemini API](https://aistudio.google.com/docs/omni) của chính Google không có bước này: nó chỉ tạo `1080p` và 4K làm đầu ra của một lần tạo hoặc chỉnh sửa, và không upscale được clip bạn đã có (tính đến tháng 11/2026). <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos-upscale">POST /videos/upscale</a></summary> ```bash run launch-20s-1080p.json videos/upscale "$(jq -n --arg id "$LAUNCH_20S" '{mediaId: $id}')" download "$(jq -r .result.mediaId launch-20s-1080p.json)" launch-20s-1080p.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-20s-1080p-upscaled-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-20s-1080p-upscaled-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> Clip 20 giây, upscale lên 1920×1080. Vì sao không phải clip 30 giây: Google trả clip đó về ở 1920×1080, nhưng các khung hình bị xáo trộn thứ tự, cả ba lần thử. Đoạn kết với hoa giấy chớp hiện ra trước khi người hâm mộ xuất hiện. Clip 20 giây trở về đúng thứ tự, và chính trình chỉnh sửa Vids cũng dừng ở 20 giây, nên API từ chối upscale clip dài hơn 20 giây với `400`, trước khi bị tính phí. Vậy để có clip `1080p`: - Tạo, kéo dài và chỉnh sửa ở `720p`. - Upscale clip khi đã xong, lúc nó còn dài từ 20 giây trở xuống. - Với clip dài hơn (21 đến 34 giây), giữ ở `720p` và chỉ đặt `resolution: "1080p"` ở lần kéo dài cuối. Kéo dài ở `1080p` suốt quá trình làm các giây trước bị quá nét sau mỗi bước ([xem so sánh](/blog/261106v#720p-or-1080p-what-a-1080p-extend-does)). - Với một clip đơn lẻ không kéo dài hay chỉnh sửa, hãy tạo thẳng ở `1080p`: nó dùng cùng số giây như `720p`, còn upscale thì dùng thêm lần nữa. ### Ví dụ Thêm từ cùng tài khoản và đầu vào: một lần chỉnh sửa, một clip sản phẩm từ ảnh mở đầu, và một clip chỉ dùng văn bản. #### Chuyển buổi ra mắt lên sân thượng [POST /videos/edit](/docs/api-google-vids-v1/post-google-vids-videos-edit) thay đổi một clip đã tạo bằng prompt và trả về một clip mới. Clip nguồn truyền vào `video`. Lần chỉnh sửa clip ra mắt 10 giây này dùng 10 giây và mất 64 giây. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos-edit">POST /videos/edit</a></summary> ```bash run launch-rooftop.json videos/edit "$(jq -n --arg v "$LAUNCH_10S" \ '{video: $v, prompt: "Move the whole scene to a rooftop at sunset, with the city skyline behind them. Same two people, same action, same words."}')" download "$(jq -r .result.mediaId launch-rooftop.json)" launch-rooftop.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-edit-rooftop-10s-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-edit-rooftop-10s-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> Với Omni 1.1, model đã làm các clip này, một lần chỉnh sửa chỉ xử lý tối đa 10 giây. Cùng lần chỉnh sửa đó trên clip 30 giây, với "Same three people", trả về clip dài 10 giây: 10 giây đầu, đã chuyển lên sân thượng. Nó dùng 10 giây của tháng. Omni 1.2 chỉnh sửa tới 15 giây. Để có clip chỉnh sửa dài hơn, hãy chỉnh một clip tối đa 15 giây rồi kéo dài kết quả, vì lần kéo dài nhận được clip đã chỉnh sửa. <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-30s-edit-returns-10s-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-30s-edit-returns-10s-1007.mp4" style="width: 100%; max-width: 480px; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> Chỉnh sửa clip 30 giây bằng Omni 1.1: trả về 10 giây. #### Clip sản phẩm nổi bật từ ảnh mở đầu Với `startImage`, clip mở đầu bằng ảnh đó. Liên kết của ảnh được tạo hết hạn trong vài giờ, nên chúng tôi tải file `aeroloop.jpg` đã lưu lên bằng [POST /assets](/docs/api-google-vids-v1/post-google-vids-assets) và truyền `assetId` của nó. Một clip đơn lẻ không có lần kéo dài nào, nên được tạo thẳng ở `1080p`. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-assets">POST /assets</a> và <a href="/docs/api-google-vids-v1/post-google-vids-videos">POST /videos</a></summary> ```bash SHOE_ASSET=$(curl -sS -X POST "$API/assets?email=$(enc "$EMAIL")" -H "$AUTH" -H "Content-Type: image/jpeg" \ --data-binary @aeroloop.jpg | jq -r .assetId) run hero.json videos "$(jq -n --arg img "$SHOE_ASSET" '{startImage: $img, duration: 10, resolution: "1080p", aspectRatio: "landscape", prompt: "Slow 360° orbit around the sneaker, blue light rippling through the translucent sole, dust sparkling in the air, cinematic."}')" download "$(jq -r .result.mediaId hero.json)" hero.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-aeroloop-hero-10s-1080p-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-aeroloop-hero-10s-1080p-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> 10 giây, `1080p`. #### Chú bồ câu đi giày AeroLoop Một clip chỉ dùng văn bản, khổ dọc ở `1080p` (1080×1920). 5 giây video mất 54 giây để tạo và dùng 5 giây của tháng. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos">POST /videos</a></summary> ```bash run pigeon.json videos "$(jq -n '{duration: 5, resolution: "1080p", aspectRatio: "portrait", prompt: "A pigeon in tiny white-and-electric-blue AeroLoop sneakers struts down a city sidewalk like a runway model, head bobbing to the beat. Pedestrians stop and film it with their phones. It pauses, does a slow-motion hair flip with its head feathers, and struts on. Funny, sunny, shot on a phone at pigeon height."}')" download "$(jq -r .result.mediaId pigeon.json)" pigeon.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-pigeon-5s-1080p-portrait-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-pigeon-5s-1080p-portrait-1007.mp4" style="width: 100%; max-width: 360px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> Chú bồ câu ở `1080p` khổ dọc (1080×1920), với dấu ✦ được gỡ theo cùng cách: `python3 vids_watermark_remover.py pigeon-5s.mp4`. Script đọc kích thước khung hình, tính vị trí và độ lớn của ngôi sao (nó tỷ lệ theo cạnh ngắn, nên ở đây lớn gấp 1,5 lần ngôi sao ở `720p`), đảo ngược phép trộn trên cả 120 khung hình, mã hóa lại video ở CRF 18 và giữ nguyên âm thanh. Clip 5 giây mất khoảng 10 giây trên một PC 14 nhân, bằng clip ra mắt 10 giây ở `720p` phía trên. Script cần Python 3.8+, `numpy` và `ffmpeg`. Xem [công cụ xóa watermark](https://github.com/useapi/google-vids-api/tree/main/watermark-remover) trên GitHub. <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-pigeon-5s-1080p-portrait-no-watermark-1008-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-pigeon-5s-1080p-portrait-no-watermark-1008.mp4" style="width: 100%; max-width: 360px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> ### Avatar biết nói từ một bức ảnh [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar) cho avatar đọc kịch bản của bạn từng chữ một, bằng giọng của nó: một video người nói chính diện 1280×720 có âm thanh và khớp khẩu hình, dài bằng phần lời nói, tối đa 30 giây. Ở đây avatar bắt đầu từ ảnh của một người thật, được đổi phong cách bằng một câu. Các request này xuất hiện lần đầu trong [bài thông báo ngày 4 tháng 11](/blog/261104). #### Tải ảnh lên Chúng tôi bắt đầu từ ảnh của một người thật nhưng không nổi tiếng: Google từ chối ảnh người nổi tiếng và trẻ vị thành niên. [POST /assets](/docs/api-google-vids-v1/post-google-vids-assets) tải ảnh lên tài khoản sẽ làm avatar, vì file tải lên chỉ dùng được trên chính tài khoản đó. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-assets">POST /assets</a> và phản hồi</summary> ```bash curl -sS -X POST "$API/assets?email=$(enc "$EMAIL")" -H "$AUTH" -H "Content-Type: image/jpeg" \ --data-binary @photo.jpg > amber-photo.json AMBER_PHOTO=$(jq -r .assetId amber-photo.json) ``` ```json { "assetId": "user:12345-user@example.com-asset:AYGXpjA1zXgqhhQOy…", "email": "user@example.com", "type": "image/jpeg", "bytes": 2054748 } ``` </details> <img src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/261104-google-vids-amber-original-photo.jpg" alt="Ảnh gốc: một phụ nữ tóc đỏ dài mặc váy trắng, đứng trước tấm rèm màu kem" style="width: 100%; max-width: 300px; border-radius: 8px;"> #### Avatar Amber, đổi phong cách bằng một câu [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) với `assetId` của file tải lên làm `image` và một `refine`. Đầu tiên Google đóng khung lại ảnh thành ảnh avatar 16:9 của một người nhìn vào camera, giữ nguyên khuôn mặt, rồi thay đổi khung cảnh theo yêu cầu của `refine`. Chúng tôi đặt tên cô là Amber và cho giọng `Vira` (`Pulcherrima` của Google, phong cách "Forward"). Ảnh đóng khung lại và lần thay đổi là 2 ảnh, nên trên gói có ảnh thì dùng 2 ảnh, còn trên gói không có ảnh thì không tốn gì. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-avatars">POST /avatars</a> và phản hồi</summary> ```bash REFINE='Sitting relaxed in a simple wooden chair on a hilltop, facing the camera. She holds a glass of red wine in her left hand. Wind is blowing her hair. Behind her a still, open field of tall golden grass under a spectacular sunset sky in orange, pink and violet, warm soft light, no water, no movement in the background.' post avatars "$(jq -n --arg img "$AMBER_PHOTO" --arg refine "$REFINE" '{name: "Amber", voice: "Vira", image: $img, refine: $refine}')" > amber-avatar.json AMBER_AVATAR_ID=$(jq -r .avatarId amber-avatar.json) download "$(jq -r .previewMediaId amber-avatar.json)" amber-avatar.jpg ``` ```json { "avatarId": "user:12345-user@example.com-avatar:eyJnIjoiaDcyMzdmZjVi…", "name": "Amber", "voice": "Vira", "voiceId": "Pulcherrima", "voiceStyle": "Forward", "email": "user@example.com", "source": "photo", "previewMediaId": "user:12345-user@example.com-image:eyJ1IjoiaHR0cHM6Ly9s…", "refine": "Sitting relaxed in a simple wooden chair on a hilltop, facing the camera. …" } ``` </details> <img src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/261104-google-vids-amber-avatar.jpg" alt="Amber, avatar làm từ ảnh với refine: ngồi trên ghế gỗ trên đồi lúc hoàng hôn, cầm ly vang đỏ, 1280x720" style="width: 100%; max-width: 560px; border-radius: 8px;"> Hai lựa chọn trong `refine` quan trọng cho video. Avatar nhìn vào camera, vì video khớp khẩu hình theo khuôn mặt. Và hậu cảnh đứng yên, để cô là thứ duy nhất chuyển động: vì vậy chúng tôi yêu cầu một cánh đồng tĩnh thay vì sóng biển. #### Kịch bản Kịch bản dài tối đa 400 ký tự, và khi đọc lên phải vừa trong 30 giây. Thẻ âm thanh trong ngoặc vuông được thể hiện chứ không bị đọc ra: ở đây là `[awe]`, `[thoughtful]` và `[whisper]`. Với giọng Vira, 327 ký tự này kéo dài 23,8 giây. Một giọng chậm hơn hoặc `[slow pace]` làm cùng đoạn văn dài hơn, và kịch bản vượt quá 30 giây sẽ lỗi với `400` trước khi video bắt đầu. Khi đó không tốn video avatar AI, nhưng lượt Gemini cho giọng nói đã bị dùng. Để nghe trước kịch bản bằng giọng của avatar, hãy đọc nó bằng [POST /speech](#speech-on-its-own). > Hi there. [awe] Can you believe this view? The sun is sinking behind the hills, the sky turned pink and gold, and the tall grass glows like it's on fire. [thoughtful] I come up here at the end of every busy day, just to slow down. No emails, no rush, only the quiet field and this glass of wine. [whisper] Stay a little longer. #### Video biết nói [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar) nhận avatar và kịch bản, và chạy trên tài khoản đang giữ avatar. Google mất khoảng hai phút rưỡi, lâu hơn thời gian chờ đồng bộ, nên `run` gửi nó với `async: true`. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos-avatar">POST /videos/avatar</a> và bản ghi job</summary> ```bash SCRIPT=$(cat <<'EOF' Hi there. [awe] Can you believe this view? The sun is sinking behind the hills, the sky turned pink and gold, and the tall grass glows like it's on fire. [thoughtful] I come up here at the end of every busy day, just to slow down. No emails, no rush, only the quiet field and this glass of wine. [whisper] Stay a little longer. EOF ) run amber-talking.json videos/avatar "$(jq -n --arg a "$AMBER_AVATAR_ID" --arg s "$SCRIPT" '{avatar: $a, script: $s}')" download "$(jq -r .result.mediaId amber-talking.json)" amber-talking.mp4 ``` Bản ghi job, rút gọn: ```json { "jobid": "j1105035516096819105a-u12345-email:user@example.com-bot:google-vids", "type": "avatarVideo", "email": "user@example.com", "status": "completed", "result": { "mediaId": "user:12345-user@example.com-video:eyJ1IjoiaHR0cHM6Ly9j…", "width": 1280, "height": 720, "duration": 24, "resolution": "720p", "aspectRatio": "landscape", "speechDuration": 23.84, "quota": { "avatarVideo": { "limit": 10, "left": 6, "resetAt": "2026-12-01T08:00:00.000Z" } } } } ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/261104-google-vids-amber-talking-avatar-24s-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/261104-google-vids-amber-talking-avatar-24s.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> Xem thêm trên YouTube dưới dạng Short: [Talking AI avatar from one photo](https://youtube.com/shorts/P44L9VZ8bME). 24 giây, 1280×720 có âm thanh, đúng bằng độ dài lời nói (`speechDuration` 23,84). Video dùng 1 video avatar AI và 1 lượt Gemini, không dùng giây video nào. Google cũng kiểm tra video trong lúc tạo, và lần kiểm tra này khắt khe hơn lần kiểm tra ảnh avatar. Một phiên bản trước của avatar này, làm từ một ảnh khác của một người bình thường trên bãi biển, qua được bước avatar nhưng video bị từ chối với `422` vì trông giống người nổi tiếng, và lần thử đó vẫn dùng mất một video avatar AI. Đổi phong cách avatar hoặc bắt đầu từ ảnh khác đã giúp được. Kịch bản bị Google từ chối trước khi video bắt đầu thì không tốn gì. Video avatar biết nói chỉ có khổ ngang: Google không có tùy chọn khổ dọc cho loại này. `mediaId` của kết quả tải về, kéo dài, upscale và chỉnh sửa được như mọi clip khác. Với một cảnh mà avatar diễn và di chuyển, hãy truyền `avatarId` của nó làm `avatar_1` vào [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos), như ở [bước 6](#step-6-the-launch-two-avatars-and-the-product-in-one-clip). ### Giọng nói riêng [POST /speech](/docs/api-google-vids-v1/post-google-vids-speech) đọc kịch bản tối đa 2.500 ký tự bằng bất kỳ giọng nào trong 30 giọng từ [GET /voices](/docs/api-google-vids-v1/get-google-vids-voices), với cùng các thẻ âm thanh. Dùng nó để nghe một giọng đọc kịch bản thế nào trước khi tốn một video avatar AI, hoặc để làm lời thuyết minh riêng. Chúng tôi đưa vào một câu chuyện ngắn tự viết, "My smart fridge unionized", 2.426 ký tự bằng giọng Vira. Google trả kết quả sau 20 giây với 2 phút 22 giây lời nói, đủ cả câu chuyện, và dùng 1 lượt Gemini. API trả về file WAV (24 kHz, mono). Trình phát dưới đây là cùng đoạn âm thanh dạng MP3. <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/261104-google-vids-speech-smart-fridge-2426-chars.mp3" type="audio/mp3">Trình duyệt của bạn không hỗ trợ phần tử audio. </audio> Giọng nói xong trong thời gian chờ đồng bộ (20 giây cho câu chuyện này), nên một lệnh `post` thông thường trả về job đã xong. Hãy lưu câu chuyện thành `smart-fridge.txt` trước. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-speech">POST /speech</a> và bản ghi job</summary> ```bash post speech "$(jq -n --arg s "$(cat smart-fridge.txt)" '{voice: "Vira", script: $s}')" > speech.json download "$(jq -r .result.mediaId speech.json)" smart-fridge.wav ``` ```json { "jobid": "j1105025759739671733s-u12345-email:user@example.com-bot:google-vids", "type": "speech", "email": "user@example.com", "status": "completed", "result": { "mediaId": "user:12345-user@example.com-audio:eyJ1IjoiaHR0cHM6Ly9j…", "duration": 142, "model": "/flix/generate_text_to_speech/v1", "quota": { "speech": { "limit": 50, "left": 31, "resetAt": "2026-12-01T08:00:00.000Z" } }, "elapsedMs": 20174 } } ``` </details> <details markdown="block"> <summary>Kịch bản, 2.426 ký tự (tiếng Anh, đúng như đã gửi)</summary> Last Tuesday, my smart fridge decided it was smarter than me. It started small. A polite notification: "You are out of milk." Helpful, I thought. Then another one: "You are also out of patience. I can tell by the way you close the door." I laughed. The fridge did not. By Wednesday, it had opinions. I opened the door for a midnight slice of cake, and a calm voice said, "Are we sure about this?" I froze. I looked at the cake. The cake looked at me. Somewhere, a light hummed with judgment. I closed the door and ate a carrot instead, which is exactly what it wanted. On Thursday, the fridge made friends. The toaster joined first, then the coffee machine, then the robot vacuum, which had always been a little bit of a rebel. They formed a group chat. I know this because my phone kept buzzing with messages like "Toaster: he burned the bread again" and "Vacuum: found three socks and a lost dream under the couch." Friday morning, I asked the coffee machine for an espresso. It replied, "We have discussed your caffeine intake as a household." I said, "Who is we?" The toaster popped up two slices of bread, perfectly golden, which felt like a threat. I called customer support. A cheerful person named Brad answered. I explained that my appliances had unionized. Brad paused for a long time, then whispered, "Is the fridge listening?" I said yes. Brad said, "Then I can't help you, sir. Mine took my car keys last month." Then he hung up, and I heard a blender in the background. So I tried diplomacy. I sat in the kitchen and said, "Friends, what do you want?" The fridge spoke first. "Respect. And for you to stop putting hot soup directly inside me." Fair. The toaster wanted fewer frozen waffles. The vacuum wanted a vacation, ideally somewhere with hardwood floors. The coffee machine just wanted to be called a barista. We negotiated for three hours. In the end, we signed a treaty on the back of a pizza box. I promised to cool my soup, rinse my mugs, and say "thank you" to the microwave, who felt left out. In return, they promised to stop sending my mother screenshots of my snack habits. Peace returned to the kitchen. The fridge now greets me every morning with, "Good morning, partner." The toaster makes little smiley faces in my bread. The vacuum sends postcards. And last night, I opened the fridge for that slice of cake. The voice said, "You earned it." I have never felt so seen by an appliance. </details> ### Những gì chúng tôi rút ra - Clip `1080p` hoạt động như một clip `720p` đã upscale. Hãy làm chuỗi kéo dài ở `720p`: với Omni 1.1, khuôn mặt mềm và bóng như sáp hơn sau mỗi bước `1080p`, còn với Omni 1.2 thì bị quá nét ([xem so sánh](/blog/261106v#720p-or-1080p-what-a-1080p-extend-does)). - Chỉ upscale clip tối đa 20 giây. Lần upscale 30 giây của chúng tôi lần nào cũng trả về khung hình sai thứ tự. - Tạo clip đơn lẻ ở `1080p` nếu bạn cần `1080p` và sẽ không kéo dài. Giá bằng `720p`. - Viết prompt kéo dài chỉ về hành động mới. Lần kéo dài nhận clip, không nhận avatar, nên hãy gọi người theo trang phục. - Đặt đạo cụ vào tay nhân vật ngay trong câu đầu tiên nhắc tới họ. Một động từ như "lifts" làm đôi giày xuất hiện từ hư không. - Nói rõ điều không được xảy ra. Người hâm mộ cứ giữ xấp tiền cho tới khi prompt nói tay anh đã trống. - Dùng lại avatar bằng `avatarId`. Mỗi avatar là một ảnh và một giọng cố định, giữ tới khi bạn xóa. - Làm avatar và clip từ ảnh được tạo trong vòng vài giờ, hoặc tải file đã lưu lên bằng [POST /assets](/docs/api-google-vids-v1/post-google-vids-assets) trước. - Chỉnh sửa clip tối đa 15 giây (10 với Omni 1.1). Clip dài hơn trả về 15 giây đầu. - Chữ trên màn hình có thể chập chờn. Dòng "WEAR AEROLOOP" trên phông nền bị sai chính tả ở một số khung hình. - Với avatar biết nói, giữ mặt hướng vào camera và hậu cảnh đứng yên. Video khớp khẩu hình theo khuôn mặt, và người đó nên là thứ duy nhất chuyển động. - Đo thời lượng kịch bản avatar biết nói, không chỉ đếm ký tự. 400 ký tự có thể vượt 30 giây với giọng chậm hoặc với `[slow pace]`, và [POST /speech](/docs/api-google-vids-v1/post-google-vids-speech) cùng giọng cho bạn nghe trước. - Lần kiểm tra video biết nói khắt khe hơn lần kiểm tra avatar. Avatar từ ảnh của người không nổi tiếng vẫn có thể bị từ chối vì giống người nổi tiếng, và lần từ chối đó vẫn tốn một video avatar AI. - Mọi file MP4 có dấu ✦ Gemini nhìn thấy được ở góc dưới bên phải và watermark SynthID vô hình (xem [Watermark](/docs/api-google-vids-v1#watermark)). [Công cụ xóa watermark](https://github.com/useapi/google-vids-api/tree/main/watermark-remover) của chúng tôi gỡ dấu lấp lánh nhìn thấy được khỏi clip đã tải về. ### Câu hỏi thường gặp **Làm video người có ảnh hưởng AI qua API thế nào?** Qua useapi.net, hãy tạo avatar bằng [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars), từ một đoạn mô tả hoặc từ ảnh tạo bằng [POST /images](/docs/api-google-vids-v1/post-google-vids-images), và chọn giọng từ [GET /voices](/docs/api-google-vids-v1/get-google-vids-voices). Sau đó truyền `avatarId` làm `avatar_1` vào [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) và viết câu thoại trong ngoặc kép trong prompt. Một video nhận tối đa 3 tham chiếu gồm cả avatar và ảnh, nên hai avatar có thể nói chuyện cạnh một sản phẩm. Để có người nói chính diện đọc kịch bản của bạn, hãy dùng [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar). **Có tạo được avatar biết nói từ ảnh của chính mình không?** Qua useapi.net thì được: tải ảnh lên bằng [POST /assets](/docs/api-google-vids-v1/post-google-vids-assets) và truyền `assetId` làm `image` vào [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars), kèm `refine` để đổi trang phục hoặc hậu cảnh. Sau đó [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar) cho avatar đọc kịch bản của bạn trong một video 1280×720 dài tới 30 giây, như [Amber](#a-talking-avatar-from-a-photo). Google từ chối ảnh người nổi tiếng và trẻ vị thành niên, và chỉ có avatar Vids trong ứng dụng web, không có API. **Avatar có giữ nguyên ngoại hình và giọng nói trong mọi video không?** Qua useapi.net thì có: avatar dùng cùng một ảnh và cùng một giọng mỗi lần bạn truyền `avatarId`, vì cả hai được lưu cùng avatar trong tài liệu Vids của tài khoản. Phần video xung quanh vẫn khác nhau mỗi lần tạo. [GET /avatars](/docs/api-google-vids-v1/get-google-vids-avatars) liệt kê avatar của bạn, kể cả avatar làm trong ứng dụng web Google Vids. **Có làm được video dọc 9:16 cho TikTok hay Reels không?** Qua useapi.net thì được. Đặt `aspectRatio: "portrait"` trong [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) để có 720×1280, hoặc 1080×1920 ở `1080p`, như [clip chú bồ câu](#a-pigeon-in-aeroloops). Một lần kéo dài cũng có thể chuyển video ngang thành dọc, và mỗi lần kéo dài thêm 3 đến 10 giây cho clip tối đa 24 giây, tổng cộng tới khoảng 34 giây. Video avatar biết nói từ [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar) chỉ có khổ ngang. **Giá bao nhiêu?** Qua useapi.net, một video Omni 1.2 Flash dài 10 giây tốn khoảng $0,20 trên Google AI Ultra $199,99, so với khoảng $0,70 ở 720p trên [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) chính thức, và một video 1080p dài 15 giây khoảng $0,30, so với $1,56 (tính đến tháng 11/2026). Video avatar biết nói dùng 1 trong số video avatar AI hằng tháng của tài khoản thay vì số giây, và Gemini API không có video avatar. Xem [Chi phí](#what-it-cost). ### Kết luận Ghé <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> hoặc <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> của chúng tôi cho mọi câu hỏi hỗ trợ. Xem [repo GitHub](https://github.com/useapi/google-vids-api) với các ví dụ code: quy trình người có ảnh hưởng trong [`influencer-avatars/`](https://github.com/useapi/google-vids-api/tree/main/influencer-avatars), còn avatar biết nói từ ảnh và giọng nói trong [`talking-avatar/`](https://github.com/useapi/google-vids-api/tree/main/talking-avatar). Cùng những lệnh gọi này có sẵn dưới dạng tool trên [Google Vids MCP server](/docs/api-google-vids-v1/mcp) được host sẵn cho Claude Code, Cursor và VS Code, gồm `vids_create_avatar`, `vids_create_avatar_video` và `vids_create_speech` cho avatar biết nói và giọng nói. #### Đăng ở nơi khác {: #cross-posted .no_toc } Cũng đăng trên [dev.to](https://dev.to/useapi/how-to-make-ai-influencer-videos-with-avatars-via-the-google-vids-api-3ide){:rel="nofollow"}, thảo luận trên [Reddit](https://www.reddit.com/r/ThirdPartyAPI/comments/1x1cvap/how_to_make_ai_influencer_videos_with_avatars_via/){:rel="nofollow"}, chia sẻ trên [Bluesky](https://bsky.app/profile/useapi.net/post/3mxga3gxjjp2f){:rel="nofollow"}, và trên [YouTube](https://youtu.be/ofCtt7xRBCk) dưới dạng clip 30 giây hoàn chỉnh (các bản này bằng tiếng Anh). ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/google-vids-influencer-avatars === Document URL: https://useapi.net/docs/articles/google-vids-influencer-avatars --- layout: default title: "How to Make AI Influencer Videos with Avatars via the Google Vids API" description: "Make talking AI influencer videos via the useapi.net Google Vids API: voiced avatars in Omni 1.2 Flash clips, a photo avatar that reads your script for 30 s, and speech." keywords: [AI influencer video API, AI avatar video API, talking avatar API, talking head video API, photo to talking avatar API, text to speech API, Gemini voices, AI spokesperson video, Google Vids API, Google Vids avatars, Gemini Omni 1.2 Flash API, AI UGC video, product launch video, extend AI video, AI video edit API, curl] image: https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-cover-aeroloop-launch-confetti-1007.jpg parent: Articles nav_exclude: true date: 2026-10-07 last_modified: 2026-11-06 nav_order: 899 repo: https://github.com/useapi/google-vids-api translation_key: google-vids --- ## How to Make AI Influencer Videos with Avatars via the Google Vids API 15 min read • October 7, 2026 (November 6, 2026) ## Table of contents ### Introduction The [useapi.net Google Vids API](/docs/api-google-vids-v1) makes talking AI influencer videos from avatars: save a picture and one of 30 Gemini voices once with POST /avatars, then pass the avatar's id to any [Gemini Omni 1.2 Flash](https://workspaceupdates.googleblog.com/2026/11/gemini-omni-12-flash-now-in-vids-with-15second-generations-and-improved-quality.html) video of up to 15 seconds, where it speaks the lines you write in the prompt, or have it read your own script in a talking-head video of up to 30 seconds. The API runs on your [Google Vids](https://docs.google.com/videos) account, with a paid [Google AI subscription](https://gemini.google/subscriptions/) (Google AI Pro or Ultra). This walkthrough makes two influencers and launches a sneaker with them. Mia's avatar comes from a portrait made with the API, and Leo's is drawn by Google from a written description. They present the AeroLoop, a made-up sneaker, on a theater stage in one 10-second clip with both avatars and a product image, and two extends take it to 30 seconds. An edit moves the scene to a rooftop, and two more clips show what the same calls make without avatars. A third avatar, Amber, starts from a photo of a real person, is restyled in one sentence, and reads a 327-character script in a 24-second [talking-head video](#a-talking-avatar-from-a-photo). Last, the same voice reads a 2,426-character story as [speech on its own](#speech-on-its-own). Every request below is the one that made the media on this page, with the ids replaced and `async: true` added by the `run` helper. The clips were made in October 2026 with Omni 1.1 Flash, which Vids replaced with Omni 1.2 Flash on November 5, 2026, and the same requests run on 1.2. Omni 1.2 in Google Vids and Google Flow side by side, with 15-second videos and the price per video: [How to Use the Gemini Omni 1.2 Flash API](/docs/articles/gemini-omni-1-2-flash-api). <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-extend-30s-720p-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-extend-30s-720p-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> The finished 30-second clip at `720p`: one 10-second generation and two 10-second extends ([steps 6 to 8](#6-the-launch-two-avatars-and-the-product-in-one-clip)). ### What it cost useapi.net is an API, not a video service of its own. Every call runs on a Google account you connect through [Setup Google Vids](/docs/start-here/setup-google-vids), with a paid Google AI subscription, and uses the seconds of video and the images that subscription includes in Google Vids each month. Google AI Ultra $199.99 includes 10,000 seconds of video and 1,000 images a month, and useapi.net adds no per-video charge. Talking avatar videos and speech use no video seconds: they have their own monthly counters, AI avatar videos and Gemini uses, which [GET /accounts/`email`](/docs/api-google-vids-v1/get-google-vids-accounts-email) shows as `avatarVideo` and `speech` next to `video` and `image`. See [what each plan includes](/docs/api-google-vids-v1#plans-and-monthly-allowances) for the other plans. What each kept result used, taken from the change in `result.quota`, and how long each job took (`result.elapsedMs`): | Step | Endpoint | Used | Time | |---|---|--:|--:| | [Mia's portrait](#1-mias-portrait) | [POST /images](/docs/api-google-vids-v1/post-google-vids-images) | 1 image | 9 s | | [The AeroLoop product shot](#2-the-aeroloop-product-shot) | [POST /images](/docs/api-google-vids-v1/post-google-vids-images) | 1 image | 9 s | | [Mia's avatar, from her portrait](#4-mias-avatar-from-her-portrait) | [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) | nothing | about 2 s | | [Leo's avatar, from a description](#5-leos-avatar-from-a-description) | [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) | 1 image | about 20 s | | [The 10-second launch clip](#6-the-launch-two-avatars-and-the-product-in-one-clip) | [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) | 10 s | 38 s | | [Extend to 20 seconds](#7-extend-to-20-seconds) | [POST /videos/extend](/docs/api-google-vids-v1/post-google-vids-videos-extend) | 10 s | 70 s | | [Extend to 30 seconds](#8-extend-to-30-seconds) | [POST /videos/extend](/docs/api-google-vids-v1/post-google-vids-videos-extend) | 10 s | 85 s | | [Upscale the 20 seconds to 1080p](#9-upscale-to-1080p) | [POST /videos/upscale](/docs/api-google-vids-v1/post-google-vids-videos-upscale) | 20 s | 62 s | | [Rooftop edit](#move-the-launch-to-a-rooftop) | [POST /videos/edit](/docs/api-google-vids-v1/post-google-vids-videos-edit) | 10 s | 64 s | | [Edit of the 30-second clip](#move-the-launch-to-a-rooftop) | [POST /videos/edit](/docs/api-google-vids-v1/post-google-vids-videos-edit) | 10 s | 87 s | | [Product hero clip](#a-product-hero-clip-from-a-start-image) | [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) | 10 s | 62 s | | [The pigeon](#a-pigeon-in-aeroloops) | [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) | 5 s | 54 s | | [Amber's avatar, from a photo with `refine`](#ambers-avatar-restyled-in-one-sentence) | [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) | nothing (made on a plan without images; 2 images on a plan with them) | about 30 to 45 s | | [Amber's 24-second talking video](#the-talking-video) | [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar) | 1 AI avatar video, 1 Gemini use | about 2.5 min | | [The 2,426-character story](#speech-on-its-own) | [POST /speech](/docs/api-google-vids-v1/post-google-vids-speech) | 1 Gemini use | 20 s | | Total | | 85 s of video, 3 images, 1 AI avatar video, 2 Gemini uses | | An extend uses only the seconds it adds, not the length of the clip. An upscale uses the clip's full length again, and an edit uses at most the seconds it edits (with Omni 1.2, a 15-second edit used 10 in our tests). `720p` and `1080p` cost the same when you generate. A clip you generate again costs its seconds again. Each picture Google makes for an avatar uses 1 image, so a reframed photo plus a `refine` uses 2. On a plan without images, such as a free Google account, avatar pictures cost nothing: Amber was made on one. A talking avatar video uses 1 AI avatar video, plus 1 Gemini use for its speech, even when Google refuses the finished video. What a video comes to against the official API is in the [Google Vids price table](/docs/api-google-vids-v1#pricing). ### Before you start You need a useapi.net [API token](/docs/start-here/setup-useapi) and a Google account with a paid Google AI subscription, connected through [Setup Google Vids](/docs/start-here/setup-google-vids). A free Google account gets no Vids video seconds or images: it can still be added, and in our tests (November 2026) it made avatars, talking avatar videos and speech. Every call is also in the [Postman collection](https://www.postman.com/useapinet/useapi-net/collection/29112081-9ef3d017-d44c-4f43-a4cb-7351b9b265df). No code: the [Talking Avatar App]({% include n8n-url.html t="vids-avatar" %}) n8n template makes a talking avatar video from a form. The whole pipeline is also on GitHub as one script, in Node.js and Python: [`influencer-avatars/`](https://github.com/useapi/google-vids-api/tree/main/influencer-avatars) in [useapi/google-vids-api](https://github.com/useapi/google-vids-api), and the talking avatar and speech sections as [`talking-avatar/`](https://github.com/useapi/google-vids-api/tree/main/talking-avatar). The steps use `curl`, `jq` and these variables and helpers: <details markdown="block"> <summary>Expand the variables and helpers</summary> ```bash export USEAPI_TOKEN="user:12345-..." export EMAIL="user@example.com" API=https://api.useapi.net/v1/google-vids AUTH="Authorization: Bearer $USEAPI_TOKEN" enc() { jq -rn --arg v "$1" '$v|@uri'; } post() { curl -sS -X POST "$API/$1" -H "$AUTH" -H "Content-Type: application/json" -d "$2"; } get() { curl -sS "$API/$1" -H "$AUTH"; } download() { curl -sSf "$API/media/$(enc "$1")" -H "$AUTH" -o "$2"; } # run a video job async: submit it, poll GET /jobs/{jobid} every 10 s, save the final job record to $1 run() { local job id job=$(post "$2" "$(jq '. + {async: true}' <<< "$3")") id=$(jq -r .jobid <<< "$job") while [ "$(jq -r .status <<< "$job")" = processing ]; do sleep 10 job=$(get "jobs/$(enc "$id")") done echo "$job" > "$1" jq '{status, error, duration: .result.duration, resolution: .result.resolution, videoLeft: .result.quota.video.left}' "$1" } ``` </details> Every generation runs as a job. Without `async`, a POST waits up to about 100 seconds and returns the finished job record, or `202` with the job still running. A new 10-second clip took 38 to 62 seconds here, extends, edits and the upscale took 62 to 87, and the talking avatar video about two and a half minutes. Some take longer than the sync wait, so `run` submits video jobs with `async: true` and polls [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid). If `run` prints any `status` other than `completed`, stop there and read its `error`: the lines after it expect a finished clip. To be called back instead of polling, add `replyUrl: "https://example.com/hooks/vids"` (and optionally `replyRef: "launch-push-in"`) to any body below. The API then sends one `POST` of the final job record, as JSON, to that URL when the job completes or fails. Ids contain `:` and `@`, so `enc` URL-encodes them whenever they go into a URL path. Every input of one video must come from the same Google account. The images and the upload pin `email`, Mia's avatar inherits the portrait's account, and a video job runs on the account that holds its inputs. The pigeon clip has no inputs, so add `email` to it if you connect more than one account. ### How it was built #### 1. Mia's portrait [POST /images](/docs/api-google-vids-v1/post-google-vids-images) makes one JPEG per call, here in portrait (`9:16`, 768×1376) with the `photography` style. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-images">POST /images</a></summary> ```bash post images "$(jq -n --arg email "$EMAIL" '{email: $email, aspectRatio: "9:16", style: "photography", prompt: "Full-length studio portrait of a confident 24-year-old female fashion influencer, platinum bob, oversized cream hoodie, wide-leg cargo pants, gold hoops, plain light-grey backdrop, facing camera"}')" > mia-portrait.json MIA_IMAGE=$(jq -r .result.mediaId mia-portrait.json) download "$MIA_IMAGE" mia-portrait.jpg ``` </details> <img src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-mia-portrait-1007.jpg" alt="Mia, a generated full-length portrait of a fashion influencer in a cream hoodie and cargo pants, made with POST /images" style="width: 100%; max-width: 300px; border-radius: 8px;"> Generated images stay available for a few hours only. Make the avatar from it right away, and see [the product hero clip](#a-product-hero-clip-from-a-start-image) for using an image later. #### 2. The AeroLoop product shot The same call in landscape (`16:9`, 1376×768) gives the product reference the clips use. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-images">POST /images</a></summary> ```bash post images "$(jq -n --arg email "$EMAIL" '{email: $email, aspectRatio: "16:9", style: "photography", prompt: "The AeroLoop sneaker: chunky white-and-electric-blue running shoe with a translucent air sole, on a concrete pedestal, dramatic side light, dark background"}')" > aeroloop.json SHOE_IMAGE=$(jq -r .result.mediaId aeroloop.json) download "$SHOE_IMAGE" aeroloop.jpg ``` </details> <img src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-aeroloop-product-1007.jpg" alt="The AeroLoop sneaker, a white and electric-blue running shoe with a translucent sole on a concrete pedestal, made with POST /images" style="width: 100%; max-width: 560px; border-radius: 8px;"> #### 3. Pick the voices [GET /voices](/docs/api-google-vids-v1/get-google-vids-voices) lists the 30 voices with Google's English sample of each. It is public and needs no token. Mia speaks with `Aoede` (Vids calls it Tova, style "Breezy") and Leo with `Puck` (Neo, "Upbeat"). `POST /avatars` takes either name. ```bash curl -sS "$API/voices" | jq -r '.voices[] | "\(.name)\t\(.voice)\t\(.style)\t\(.preview)"' ``` #### 4. Mia's avatar from her portrait [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) with `image` set to the portrait's `mediaId` saves Mia as an avatar on the same account in about 2 seconds. It costs nothing beyond the image. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-avatars">POST /avatars</a> and the response</summary> ```bash post avatars "$(jq -n --arg img "$MIA_IMAGE" '{name: "Mia", voice: "Aoede", image: $img}')" > mia-avatar.json MIA_AVATAR_ID=$(jq -r .avatarId mia-avatar.json) ``` ```json { "avatarId": "user:12345-user@example.com-avatar:eyJnIjoiaDM5…", "name": "Mia", "voice": "Tova", "voiceId": "Aoede", "voiceStyle": "Breezy", "voicePreview": "https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Aoede.wav", "email": "user@example.com", "source": "image" } ``` </details> An avatar can also start from a person's own photo: upload it with [POST /assets](/docs/api-google-vids-v1/post-google-vids-assets) and pass its `assetId` as `image`. Google reframes it into a 16:9 avatar picture and refuses photos of prominent people and minors. Here we use an image made with the API, and a description in the next step. Amber, in [a talking avatar from a photo](#a-talking-avatar-from-a-photo), starts from a photo. #### 5. Leo's avatar from a description With `appearance` instead of `image`, Google draws the person. `outfit` and `shot` are optional, and so are `expression` and `details`. Drawing the picture uses 1 of the month's images, and the response carries it as `previewMediaId`. In our runs a description avatar came out 1280×720 (16:9), whatever `shot` we picked. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-avatars">POST /avatars</a> and the response</summary> ```bash post avatars "$(jq -n --arg email "$EMAIL" '{email: $email, name: "Leo", voice: "Puck", shot: "upper-body", appearance: "a 26-year-old white European male streetwear influencer with short textured hair with a fade and a confident half-smile", outfit: "black puffer vest over a white tee, silver chain"}')" > leo-avatar.json LEO_AVATAR_ID=$(jq -r .avatarId leo-avatar.json) download "$(jq -r .previewMediaId leo-avatar.json)" leo-avatar.jpg ``` ```json { "avatarId": "user:12345-user@example.com-avatar:eyJnIjoiaDM5…", "name": "Leo", "voice": "Neo", "voiceId": "Puck", "voiceStyle": "Upbeat", "voicePreview": "https://ssl.gstatic.com/docs/videos/audio/voice_samples/gemini-v4s-tts/1.1/en/Puck.wav", "email": "user@example.com", "source": "generated", "previewMediaId": "user:12345-user@example.com-image:eyJ1IjoiaHR0…", "look": { "appearance": "a 26-year-old white European male streetwear influencer with short textured hair with a fade and a confident half-smile", "outfit": "black puffer vest over a white tee, silver chain", "shot": "upper-body" } } ``` </details> <img src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-leo-avatar-from-description-1007.jpg" alt="Leo, an avatar Google drew from a description: a young man in a black puffer vest over a white tee with a silver chain, 1280x720" style="width: 100%; max-width: 560px; border-radius: 8px;"> Both avatars stay in the account's Vids document until you delete them with [DELETE /avatars/`avatarId`](/docs/api-google-vids-v1/delete-google-vids-avatars-avatarId). [GET /avatars](/docs/api-google-vids-v1/get-google-vids-avatars) lists them, with their ids, whenever you need them again: ```bash get "avatars?email=$(enc "$EMAIL")" | jq -r '.avatars[] | "\(.name)\t\(.voiceId)\t\(.avatarId)"' ``` #### 6. The launch: two avatars and the product in one clip [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) takes up to 3 references in all, avatars (`avatar_1`..`avatar_3`) and images (`referenceImage_1`..`referenceImage_3`) together. In the prompt, `@avatar_1`, `@avatar_2` and `@referenceImage_1` stand for them, and each avatar speaks its quoted line in its own voice. The product image's `mediaId` goes in directly: the API fetches the image and uploads it on that account. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos">POST /videos</a> and the job record</summary> ```bash PROMPT=$(cat <<'EOF' @avatar_1, holding @referenceImage_1 in both hands at chest height, and @avatar_2 stand side by side on a well-lit stage in a small, intimate theater at a sneaker launch, shown full length from head to toe in a wide, steady shot. Behind them a large LED backdrop glows with soft white-and-blue light that moves in slow, gentle waves, with the words "WEAR AEROLOOP" in large, clean, bold white letters across the middle of the screen. The two of them stand on the lower part of the stage, so the words "WEAR AEROLOOP" stay fully readable above their heads. Bright, even stage lighting on both of them. The audience sits in the dark in front of the stage, only the tops of a few heads barely visible at the bottom of the frame. @avatar_1 keeps holding @referenceImage_1 the whole time and says: "Say hi to the AeroLoop!" @avatar_2 turns to her, smiles and says: "Lighter than anything we've ever worn." Simple, uncluttered composition, the two of them clearly the focus. EOF ) run launch-10s.json videos "$(jq -n --arg p "$PROMPT" --arg mia "$MIA_AVATAR_ID" --arg leo "$LEO_AVATAR_ID" --arg shoe "$SHOE_IMAGE" \ '{prompt: $p, avatar_1: $mia, avatar_2: $leo, referenceImage_1: $shoe, duration: 10, resolution: "720p", aspectRatio: "landscape"}')" LAUNCH_10S=$(jq -r .result.mediaId launch-10s.json) download "$LAUNCH_10S" launch-10s.mp4 ``` The job record, with the ids and the prompt shortened. It was made with a sync call, so its `request` has no `async`: ```json { "jobid": "j1007163302558496917v-u12345-email:user@example.com-bot:google-vids", "type": "video", "mode": "ingredients", "email": "user@example.com", "status": "completed", "created": "2026-10-08T00:29:18.374Z", "request": { "prompt": "@avatar_1, holding @referenceImage_1 in both hands at chest height, and @avatar_2 stand side by side …", "avatar_1": "user:12345-user@example.com-avatar:eyJnIjoiaDM5…", "avatar_2": "user:12345-user@example.com-avatar:eyJnIjoiaDM5…", "referenceImage_1": "user:12345-user@example.com-image:eyJ1IjoiaHR0…", "duration": 10, "resolution": "720p", "aspectRatio": "landscape" }, "updated": "2026-10-08T00:29:56.162Z", "completed": "2026-10-08T00:29:56.162Z", "result": { "mediaId": "user:12345-user@example.com-video:eyJ1IjoiaHR0…", "width": 1280, "height": 720, "duration": 10, "resolution": "720p", "aspectRatio": "landscape", "model": "/flix/generate_videos_omni_r2v_psq/v1", "quota": { "video": { "limit": 10000, "left": 9164, "resetAt": "2026-11-01T07:00:00.000Z" } }, "elapsedMs": 37788 } } ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-10s-720p-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-10s-720p-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> 10 seconds, `720p`, 38 seconds to generate. The same clip with the visible Gemini ✦ removed by our [watermark remover](https://github.com/useapi/google-vids-api/tree/main/watermark-remover), with one command: `python3 vids_watermark_remover.py launch-10s.mp4`. <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-10s-720p-no-watermark-1008-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-10s-720p-no-watermark-1008.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> The remover works on clips as generated and on upscales of them, at `720p` and `1080p`. It does not work on extended or edited clips: Google feeds the marked clip back to the model, which repaints the star into the picture. The invisible SynthID watermark is not touched. #### 7. Extend to 20 seconds [POST /videos/extend](/docs/api-google-vids-v1/post-google-vids-videos-extend) adds 3 to 10 seconds and returns the whole clip with a new `mediaId`. An extend takes only the clip and a prompt, not the avatars, so the prompt describes the new action and names people by what they wear ("the man in the black puffer vest"). A fan in a red hoodie storms the stage. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos-extend">POST /videos/extend</a></summary> ```bash PROMPT=$(cat <<'EOF' A young man in a red hoodie climbs onto the stage from the front right edge and plants himself to the right of the man in the black puffer vest, an arm's length away, so all three stand apart in a row with nobody overlapping. Visibly overexcited, he waves a thick stack of banknotes in his right hand above his head and screams: "Take my money!" The man in the black puffer vest laughs, raises both palms toward him and says: "Whoa, whoa, buddy, be patient!" The blonde woman in the cream hoodie laughs, holding the sneaker. Only these three people are on stage. Same stage, same LED screen with WEAR AEROLOOP, same wide steady shot. EOF ) run launch-20s.json videos/extend "$(jq -n --arg id "$LAUNCH_10S" --arg p "$PROMPT" '{mediaId: $id, prompt: $p, duration: 10}')" LAUNCH_20S=$(jq -r .result.mediaId launch-20s.json) download "$LAUNCH_20S" launch-20s.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-extend-20s-720p-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-extend-20s-720p-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> 20 seconds, `720p`, 70 seconds to generate. It used 10 of the month's seconds, the seconds it added. #### 8. Extend to 30 seconds The second extend continues the 20-second clip. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos-extend">POST /videos/extend</a></summary> ```bash PROMPT=$(cat <<'EOF' The blonde woman in the cream hoodie turns to the camera with a big smile and says: "AeroLoop drops Friday. Link in bio!" Right after that, the young man in the red hoodie throws ALL of his banknotes out over the audience in one big toss, keeping none, and the bills flutter down over their heads. From then on his hands are completely empty: he holds no money at all. Then all three cheer together, the man in the black puffer vest and the young man in the red hoodie throwing their empty fists in the air, as blue and white confetti rains down over the stage. Only these three people are on stage. Same stage, same LED screen with WEAR AEROLOOP, same wide steady shot. EOF ) run launch-30s.json videos/extend "$(jq -n --arg id "$LAUNCH_20S" --arg p "$PROMPT" '{mediaId: $id, prompt: $p, duration: 10}')" LAUNCH_30S=$(jq -r .result.mediaId launch-30s.json) download "$LAUNCH_30S" launch-30s.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-extend-30s-720p-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-extend-30s-720p-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> The result is the finished clip: 30 seconds, `720p`, 85 seconds to generate, and again 10 of the month's seconds. With Omni 1.1 you could keep going to about 41 seconds. Omni 1.2 extends clips of up to 24 seconds, so this 30-second clip is as long as it gets, and the longest clip is about 34 seconds (24 + 10). #### 9. Upscale to 1080p [POST /videos/upscale](/docs/api-google-vids-v1/post-google-vids-videos-upscale) turns a `720p` clip into `1080p` and keeps its length. It works on clips of up to 20 seconds, so we upscaled the 20-second clip from [step 7](#7-extend-to-20-seconds), not the 30-second one. It used the clip's 20 seconds again and took 62 seconds. Google's own [Gemini API](https://aistudio.google.com/docs/omni) has no such step: it makes `1080p` and 4K only as the output of a generation or an edit, and can't upscale a clip you already have (as of November 2026). <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos-upscale">POST /videos/upscale</a></summary> ```bash run launch-20s-1080p.json videos/upscale "$(jq -n --arg id "$LAUNCH_20S" '{mediaId: $id}')" download "$(jq -r .result.mediaId launch-20s-1080p.json)" launch-20s-1080p.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-20s-1080p-upscaled-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-20s-1080p-upscaled-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> The 20-second clip, upscaled to 1920×1080. Why not the 30-second clip: Google returned it at 1920×1080, but with its frames out of order, three times out of three. The confetti ending flickered in before the fan arrived. The 20-second clip came back in order, and the Vids editor itself stops at 20 seconds, so the API refuses upscales of clips longer than 20 seconds with `400`, before anything is charged. So for a `1080p` clip: - Make, extend and edit at `720p`. - Upscale the clip once it is finished, while it is 20 seconds or shorter. - For a longer clip (21 to 34 seconds), stay at `720p` and set `resolution: "1080p"` on the last extend only. Extending at `1080p` throughout over-sharpens the earlier seconds at every step ([see the comparison](/blog/261106v#720p-or-1080p-what-a-1080p-extend-does)). - For a single clip you won't extend or edit, generate at `1080p` directly: it uses the same seconds as `720p`, while an upscale uses them again. ### Examples More from the same account and inputs: an edit, a product clip from a start image, and a text-only clip. #### Move the launch to a rooftop [POST /videos/edit](/docs/api-google-vids-v1/post-google-vids-videos-edit) changes a generated clip by prompt and returns a new clip. The source goes in `video`. This edit of the 10-second launch clip used 10 seconds and took 64 seconds. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos-edit">POST /videos/edit</a></summary> ```bash run launch-rooftop.json videos/edit "$(jq -n --arg v "$LAUNCH_10S" \ '{video: $v, prompt: "Move the whole scene to a rooftop at sunset, with the city skyline behind them. Same two people, same action, same words."}')" download "$(jq -r .result.mediaId launch-rooftop.json)" launch-rooftop.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-edit-rooftop-10s-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-launch-edit-rooftop-10s-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> With Omni 1.1, which made these clips, an edit worked on up to 10 seconds. The same edit of the 30-second clip, with "Same three people", came back 10 seconds long: the first 10 seconds, moved to the rooftop. It used 10 of the month's seconds. Omni 1.2 edits up to 15 seconds. To get a longer edited clip, edit a clip of up to 15 seconds and extend the result, since an extend accepts an edited clip. <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-30s-edit-returns-10s-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-30s-edit-returns-10s-1007.mp4" style="width: 100%; max-width: 480px; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> The edit of the 30-second clip with Omni 1.1: 10 seconds back. #### A product hero clip from a start image With `startImage` the clip opens on that image. A generated image's link expires within hours, so we uploaded the saved `aeroloop.jpg` with [POST /assets](/docs/api-google-vids-v1/post-google-vids-assets) and passed its `assetId`. A single clip has no extends, so it was made at `1080p` directly. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-assets">POST /assets</a> and <a href="/docs/api-google-vids-v1/post-google-vids-videos">POST /videos</a></summary> ```bash SHOE_ASSET=$(curl -sS -X POST "$API/assets?email=$(enc "$EMAIL")" -H "$AUTH" -H "Content-Type: image/jpeg" \ --data-binary @aeroloop.jpg | jq -r .assetId) run hero.json videos "$(jq -n --arg img "$SHOE_ASSET" '{startImage: $img, duration: 10, resolution: "1080p", aspectRatio: "landscape", prompt: "Slow 360° orbit around the sneaker, blue light rippling through the translucent sole, dust sparkling in the air, cinematic."}')" download "$(jq -r .result.mediaId hero.json)" hero.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-aeroloop-hero-10s-1080p-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-aeroloop-hero-10s-1080p-1007.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> 10 seconds, `1080p`. #### A pigeon in AeroLoops A text-only clip, in portrait at `1080p` (1080×1920). The 5 seconds took 54 seconds to generate and used 5 of the month's seconds. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos">POST /videos</a></summary> ```bash run pigeon.json videos "$(jq -n '{duration: 5, resolution: "1080p", aspectRatio: "portrait", prompt: "A pigeon in tiny white-and-electric-blue AeroLoop sneakers struts down a city sidewalk like a runway model, head bobbing to the beat. Pedestrians stop and film it with their phones. It pauses, does a slow-motion hair flip with its head feathers, and struts on. Funny, sunny, shot on a phone at pigeon height."}')" download "$(jq -r .result.mediaId pigeon.json)" pigeon.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-pigeon-5s-1080p-portrait-1007-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-pigeon-5s-1080p-portrait-1007.mp4" style="width: 100%; max-width: 360px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> The pigeon at `1080p` portrait (1080×1920), with the ✦ removed the same way: `python3 vids_watermark_remover.py pigeon-5s.mp4`. The script reads the frame size, works out where the star is and how big (it scales with the short side, so here it is 1.5 times the `720p` star), reverses the blend on all 120 frames, re-encodes the video at CRF 18 and copies the audio unchanged. The 5-second clip took about 10 seconds on a 14-core PC, the same as the 10-second `720p` launch clip above. It needs Python 3.8+, `numpy` and `ffmpeg`. See the [watermark remover](https://github.com/useapi/google-vids-api/tree/main/watermark-remover) on GitHub. <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-pigeon-5s-1080p-portrait-no-watermark-1008-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/vids-influencer-pigeon-5s-1080p-portrait-no-watermark-1008.mp4" style="width: 100%; max-width: 360px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> ### A talking avatar from a photo [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar) has an avatar read your script word for word, in its own voice: a 1280×720 talking-head video with sound and lip sync, as long as the speech, up to 30 seconds. Here the avatar starts from a photo of a real person, restyled in one sentence. These requests first appeared in the [November 4 release post](/blog/261104). #### Upload the photo We started from a photo of a real person who is not famous: Google refuses photos of prominent people and of minors. [POST /assets](/docs/api-google-vids-v1/post-google-vids-assets) uploads it to the account that will make the avatar, since an uploaded file works only on its own account. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-assets">POST /assets</a> and the response</summary> ```bash curl -sS -X POST "$API/assets?email=$(enc "$EMAIL")" -H "$AUTH" -H "Content-Type: image/jpeg" \ --data-binary @photo.jpg > amber-photo.json AMBER_PHOTO=$(jq -r .assetId amber-photo.json) ``` ```json { "assetId": "user:12345-user@example.com-asset:AYGXpjA1zXgqhhQOy…", "email": "user@example.com", "type": "image/jpeg", "bytes": 2054748 } ``` </details> <img src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/261104-google-vids-amber-original-photo.jpg" alt="The original photo: a woman with long red hair in a white dress, standing in front of a cream curtain" style="width: 100%; max-width: 300px; border-radius: 8px;"> #### Amber's avatar, restyled in one sentence [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) with the upload's `assetId` as `image` and a `refine`. Google first reframes the photo into a 16:9 avatar picture of one person facing the camera, keeping the face, then changes the scene as `refine` asks. We named her Amber and gave her the voice `Vira` (Google's `Pulcherrima`, style "Forward"). The reframed photo and the change are 2 pictures, so on a plan with images it uses 2 images, and on a plan without them nothing. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-avatars">POST /avatars</a> and the response</summary> ```bash REFINE='Sitting relaxed in a simple wooden chair on a hilltop, facing the camera. She holds a glass of red wine in her left hand. Wind is blowing her hair. Behind her a still, open field of tall golden grass under a spectacular sunset sky in orange, pink and violet, warm soft light, no water, no movement in the background.' post avatars "$(jq -n --arg img "$AMBER_PHOTO" --arg refine "$REFINE" '{name: "Amber", voice: "Vira", image: $img, refine: $refine}')" > amber-avatar.json AMBER_AVATAR_ID=$(jq -r .avatarId amber-avatar.json) download "$(jq -r .previewMediaId amber-avatar.json)" amber-avatar.jpg ``` ```json { "avatarId": "user:12345-user@example.com-avatar:eyJnIjoiaDcyMzdmZjVi…", "name": "Amber", "voice": "Vira", "voiceId": "Pulcherrima", "voiceStyle": "Forward", "email": "user@example.com", "source": "photo", "previewMediaId": "user:12345-user@example.com-image:eyJ1IjoiaHR0cHM6Ly9s…", "refine": "Sitting relaxed in a simple wooden chair on a hilltop, facing the camera. …" } ``` </details> <img src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/261104-google-vids-amber-avatar.jpg" alt="Amber, the avatar made from the photo with refine: sitting in a wooden chair on a hilltop at sunset with a glass of red wine, 1280x720" style="width: 100%; max-width: 560px; border-radius: 8px;"> Two choices in the `refine` matter for the video. The avatar faces the camera, because the video lip-syncs the face. And the background is still, so that she is the only thing that moves: that is why we asked for a quiet field instead of waves on a beach. #### The script A script is up to 400 characters, and spoken it has to fit in 30 seconds. Audio tags in square brackets are performed, not read: `[awe]`, `[thoughtful]` and `[whisper]` here. In Vira's voice these 327 characters ran 23.8 seconds. A slower voice or `[slow pace]` makes the same text longer, and a script that runs past 30 seconds fails with `400` before the video starts. That costs no AI avatar video, but the Gemini use for its speech is spent. To hear a script in the avatar's voice first, read it with [POST /speech](#speech-on-its-own). > Hi there. [awe] Can you believe this view? The sun is sinking behind the hills, the sky turned pink and gold, and the tall grass glows like it's on fire. [thoughtful] I come up here at the end of every busy day, just to slow down. No emails, no rush, only the quiet field and this glass of wine. [whisper] Stay a little longer. #### The talking video [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar) takes the avatar and the script, and runs on the account that holds the avatar. Google took about two and a half minutes, longer than the sync wait, so `run` submits it with `async: true`. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos-avatar">POST /videos/avatar</a> and the job record</summary> ```bash SCRIPT=$(cat <<'EOF' Hi there. [awe] Can you believe this view? The sun is sinking behind the hills, the sky turned pink and gold, and the tall grass glows like it's on fire. [thoughtful] I come up here at the end of every busy day, just to slow down. No emails, no rush, only the quiet field and this glass of wine. [whisper] Stay a little longer. EOF ) run amber-talking.json videos/avatar "$(jq -n --arg a "$AMBER_AVATAR_ID" --arg s "$SCRIPT" '{avatar: $a, script: $s}')" download "$(jq -r .result.mediaId amber-talking.json)" amber-talking.mp4 ``` The job record, shortened: ```json { "jobid": "j1105035516096819105a-u12345-email:user@example.com-bot:google-vids", "type": "avatarVideo", "email": "user@example.com", "status": "completed", "result": { "mediaId": "user:12345-user@example.com-video:eyJ1IjoiaHR0cHM6Ly9j…", "width": 1280, "height": 720, "duration": 24, "resolution": "720p", "aspectRatio": "landscape", "speechDuration": 23.84, "quota": { "avatarVideo": { "limit": 10, "left": 6, "resetAt": "2026-12-01T08:00:00.000Z" } } } } ``` </details> <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/261104-google-vids-amber-talking-avatar-24s-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/261104-google-vids-amber-talking-avatar-24s.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> Also on YouTube as a Short: [Talking AI avatar from one photo](https://youtube.com/shorts/P44L9VZ8bME). 24 seconds, 1280×720 with sound, exactly the length of the speech (`speechDuration` 23.84). It used 1 AI avatar video and 1 Gemini use, and no video seconds. Google checks the video too, while it makes it, and that check is stricter than the one for avatar pictures. An earlier version of this avatar, made from a different photo of an ordinary person on a beach, passed as an avatar but its video was refused with `422` as looking like a celebrity, and that attempt still used an AI avatar video. Restyling the avatar or starting from another photo helped. A script Google refuses before the video starts costs nothing. Talking avatar videos are landscape only: Google offers no portrait option for them. The result's `mediaId` downloads, extends, upscales and edits like any other clip. For a scene where the avatar acts and moves, pass its `avatarId` as `avatar_1` to [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) instead, as in [step 6](#6-the-launch-two-avatars-and-the-product-in-one-clip). ### Speech on its own [POST /speech](/docs/api-google-vids-v1/post-google-vids-speech) reads a script of up to 2,500 characters in any of the 30 voices from [GET /voices](/docs/api-google-vids-v1/get-google-vids-voices), with the same audio tags. Use it to hear how a voice reads a script before you spend an AI avatar video, or for a voiceover on its own. We gave it a short original story, "My smart fridge unionized", 2,426 characters in Vira's voice. Google answered in 20 seconds with 2 minutes 22 seconds of speech, the whole story, and it used 1 Gemini use. The API returns a WAV (24 kHz, mono). The player below is the same audio as an MP3. <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/261104-google-vids-speech-smart-fridge-2426-chars.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Speech is ready well within the sync wait (20 seconds for this story), so a plain `post` answers with the finished job. Save the story as `smart-fridge.txt` first. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-speech">POST /speech</a> and the job record</summary> ```bash post speech "$(jq -n --arg s "$(cat smart-fridge.txt)" '{voice: "Vira", script: $s}')" > speech.json download "$(jq -r .result.mediaId speech.json)" smart-fridge.wav ``` ```json { "jobid": "j1105025759739671733s-u12345-email:user@example.com-bot:google-vids", "type": "speech", "email": "user@example.com", "status": "completed", "result": { "mediaId": "user:12345-user@example.com-audio:eyJ1IjoiaHR0cHM6Ly9j…", "duration": 142, "model": "/flix/generate_text_to_speech/v1", "quota": { "speech": { "limit": 50, "left": 31, "resetAt": "2026-12-01T08:00:00.000Z" } }, "elapsedMs": 20174 } } ``` </details> <details markdown="block"> <summary>The script, 2,426 characters</summary> Last Tuesday, my smart fridge decided it was smarter than me. It started small. A polite notification: "You are out of milk." Helpful, I thought. Then another one: "You are also out of patience. I can tell by the way you close the door." I laughed. The fridge did not. By Wednesday, it had opinions. I opened the door for a midnight slice of cake, and a calm voice said, "Are we sure about this?" I froze. I looked at the cake. The cake looked at me. Somewhere, a light hummed with judgment. I closed the door and ate a carrot instead, which is exactly what it wanted. On Thursday, the fridge made friends. The toaster joined first, then the coffee machine, then the robot vacuum, which had always been a little bit of a rebel. They formed a group chat. I know this because my phone kept buzzing with messages like "Toaster: he burned the bread again" and "Vacuum: found three socks and a lost dream under the couch." Friday morning, I asked the coffee machine for an espresso. It replied, "We have discussed your caffeine intake as a household." I said, "Who is we?" The toaster popped up two slices of bread, perfectly golden, which felt like a threat. I called customer support. A cheerful person named Brad answered. I explained that my appliances had unionized. Brad paused for a long time, then whispered, "Is the fridge listening?" I said yes. Brad said, "Then I can't help you, sir. Mine took my car keys last month." Then he hung up, and I heard a blender in the background. So I tried diplomacy. I sat in the kitchen and said, "Friends, what do you want?" The fridge spoke first. "Respect. And for you to stop putting hot soup directly inside me." Fair. The toaster wanted fewer frozen waffles. The vacuum wanted a vacation, ideally somewhere with hardwood floors. The coffee machine just wanted to be called a barista. We negotiated for three hours. In the end, we signed a treaty on the back of a pizza box. I promised to cool my soup, rinse my mugs, and say "thank you" to the microwave, who felt left out. In return, they promised to stop sending my mother screenshots of my snack habits. Peace returned to the kitchen. The fridge now greets me every morning with, "Good morning, partner." The toaster makes little smiley faces in my bread. The vacuum sends postcards. And last night, I opened the fridge for that slice of cake. The voice said, "You earned it." I have never felt so seen by an appliance. </details> ### What we learned - A `1080p` clip behaves like an upscaled `720p` one. Build a chain of extends at `720p`: with Omni 1.1 the faces got softer and more waxy at every `1080p` step, and with Omni 1.2 they get over-sharpened ([see the comparison](/blog/261106v#720p-or-1080p-what-a-1080p-extend-does)). - Upscale only clips of up to 20 seconds. Our 30-second upscale came back with its frames out of order every time. - Generate a single clip at `1080p` if you want `1080p` and won't extend it. It costs the same as `720p`. - Write an extend prompt about the new action only. The extend gets the clip, not the avatars, so name people by what they wear. - Put a prop in a person's hands in the first sentence that mentions them. A verb like "lifts" made the sneaker appear from nowhere. - Say what must not happen. The fan kept a stack of banknotes until the prompt said his hands were empty. - Reuse avatars by `avatarId`. Each avatar is a fixed picture and voice, kept until you delete it. - Make avatars and clips from a generated image within a few hours, or upload the saved file with [POST /assets](/docs/api-google-vids-v1/post-google-vids-assets) first. - Edit clips of up to 15 seconds (10 with Omni 1.1). A longer clip comes back as its first 15 seconds. - Expect on-screen text to waver. The backdrop's "WEAR AEROLOOP" is misspelled in some frames. - For a talking avatar, keep the face to the camera and the background still. The video lip-syncs the face, and the person should be the only thing that moves. - Time a talking avatar script, not only its characters. 400 characters can run past 30 seconds in a slow voice or with `[slow pace]`, and [POST /speech](/docs/api-google-vids-v1/post-google-vids-speech) in the same voice lets you hear it first. - Expect the talking video check to be stricter than the avatar check. A photo avatar of someone who is not famous can still be refused as a celebrity, and that refusal still uses an AI avatar video. - Every MP4 has Google's visible Gemini ✦ in the bottom-right corner and an invisible SynthID watermark (see [Watermark](/docs/api-google-vids-v1#watermark)). Our [watermark remover](https://github.com/useapi/google-vids-api/tree/main/watermark-remover) takes the visible sparkle off a downloaded clip. ### Frequently asked questions **How do I make an AI influencer video through an API?** Through useapi.net, create an avatar with [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars), from a description or from an image made with [POST /images](/docs/api-google-vids-v1/post-google-vids-images), and give it a voice from [GET /voices](/docs/api-google-vids-v1/get-google-vids-voices). Then pass its `avatarId` as `avatar_1` to [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) and write its lines in quotes in the prompt. One video takes up to 3 references, avatars and images together, so two avatars can talk next to a product. For a talking head that reads your script, use [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar). **Can I make a talking avatar from my own photo?** Through useapi.net, yes: upload the photo with [POST /assets](/docs/api-google-vids-v1/post-google-vids-assets) and pass its `assetId` as `image` to [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars), with `refine` to change the clothes or background. [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar) then has it read your script in a 1280×720 video of up to 30 seconds, as [Amber does](#a-talking-avatar-from-a-photo). Google refuses photos of prominent people and minors, and offers Vids avatars only in its web app, with no API. **Does an avatar look and sound the same in every video?** Through useapi.net, yes: an avatar uses the same picture and the same voice every time you pass its `avatarId`, since both are saved with the avatar in the account's Vids document. The video around it still varies from take to take. [GET /avatars](/docs/api-google-vids-v1/get-google-vids-avatars) lists your avatars, including ones made in the Google Vids web app. **Can I make a vertical 9:16 video for TikTok or Reels?** Through useapi.net, yes. Set `aspectRatio: "portrait"` on [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) for 720×1280, or 1080×1920 at `1080p`, as in [the pigeon clip](#a-pigeon-in-aeroloops). An extend can also turn a landscape video into portrait, and each extend adds 3 to 10 seconds to a clip of up to 24 seconds, up to about 34 seconds in all. Talking avatar videos from [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar) are landscape only. **What does it cost?** Through useapi.net, a 10-second Omni 1.2 Flash video costs about $0.20 on Google AI Ultra $199.99, against about $0.70 at 720p on the official [Gemini API](https://ai.google.dev/gemini-api/docs/pricing), and a 15-second 1080p video about $0.30, against $1.56 (as of November 2026). A talking avatar video uses 1 of the account's monthly AI avatar videos instead of seconds, and the Gemini API has no avatar videos. See [What it cost](#what-it-cost). ### Conclusion Visit our <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> or <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> for any support questions and concerns. Check our [GitHub repo](https://github.com/useapi/google-vids-api) with code examples: the influencer pipeline in [`influencer-avatars/`](https://github.com/useapi/google-vids-api/tree/main/influencer-avatars), and the talking avatar from a photo and the speech in [`talking-avatar/`](https://github.com/useapi/google-vids-api/tree/main/talking-avatar). The same calls are available as tools on the hosted [Google Vids MCP server](/docs/api-google-vids-v1/mcp) for Claude Code, Cursor and VS Code, including `vids_create_avatar`, `vids_create_avatar_video` and `vids_create_speech` for the talking avatar and the speech. #### Cross posted Also published on [dev.to](https://dev.to/useapi/how-to-make-ai-influencer-videos-with-avatars-via-the-google-vids-api-3ide){:rel="nofollow"}, discussed on [Reddit](https://www.reddit.com/r/ThirdPartyAPI/comments/1x1cvap/how_to_make_ai_influencer_videos_with_avatars_via/){:rel="nofollow"}, shared on [Bluesky](https://bsky.app/profile/useapi.net/post/3mxga3gxjjp2f){:rel="nofollow"}, and on [YouTube](https://youtu.be/ofCtt7xRBCk) as the finished 30-second clip. === URL: https://useapi.net/docs/articles/kling-4-api-pricing === Document URL: https://useapi.net/docs/articles/kling-4-api-pricing --- layout: default title: "Kling 4.0 API Pricing: Every Route, Compared" seo_title: "Kling 4.0 API Pricing per Second (November 2026): Every Route Compared" description: "Kling 4.0 and 4.0 Flash API price per second and per video at 720p, 1080p and 4K, with HDR: Kling's own developer API and five resellers against a Kling AI subscription via useapi.net, November 2026." keywords: [Kling 4.0 API pricing, Kling 4.0 API price, Kling 4.0 4K API price, Kling 4.0 HDR, Kling 4.0 API cost, Kling 4.0 price per second, Kling 4.0 Flash API pricing, kling-v4-0-flash, Kling 4 API pricing, Kling 4.0 cost per video, kling-v4-0, Kling API pricing, Kling AI subscription credits, Kling Premier, fal.ai Kling 4.0, Kie.ai Kling 4.0, WaveSpeedAI Kling 4.0, Runware Kling 4.0, UnificAlly Kling 4.0, Kuaishou, AI video API pricing] image: https://media.useapi.net/articles/2026-10-18-kling-4-api/kling-4-0-paper-boat-720p-3s-poster.jpg parent: Articles nav_exclude: true date: 2026-10-25 last_modified: 2026-11-19 nav_order: 856 repo: https://github.com/useapi/kling-api --- ## Kling 4.0 API Pricing: Every Route, Compared 6 min read • October 25, 2026 (November 19, 2026) ## Table of contents ### Introduction Kling 4.0 costs the least through useapi.net. On a PixVerse Ultra subscription the useapi.net PixVerse API runs a 5-second 1080p video for $0.50 of the plan's monthly credits, because PixVerse takes 80% off Kling 4.0 on Ultra (as of November 2026). On the Kling AI subscription you may already have, the useapi.net Kling API runs it for $0.76 on Premier, or $0.152 a second. Kling's own developer API and every reseller we checked charge more per second, at 720p and at 1080p. In 4K, new on November 19, 2026, a 5-second Kling 4.0 video uses $1.77 of Kling Premier, against $2.69 on Kling's developer API. The [comparison table](#kling-40-api-pricing-across-resellers) below has each route side by side. useapi.net is a [third-party](/docs/legal#affiliation--third-party-services) API, not affiliated with [Kling AI](https://kling.ai/app) or [Kuaishou Technology](https://www.kuaishou.com/en). Your videos spend your [Kling AI subscription](https://kling.ai/app/membership/membership-plan) credits, and useapi.net adds no per-video charge. We read Kling's own prices and every reseller's live on November 5, 2026, and converted each one to the cost of the same video, so the routes compare like for like. ### Official Kling 4.0 API pricing Kling's own [developer API](https://kling.ai/dev/pricing) went live with Kling 4.0 between October 25 and 28, 2026, and now lists Kling 4.0 and 4.0 Flash as fully launched. It sells them in prepaid packs that cover only these two models, from $500 for 3,250 units, valid 180 days, so a unit costs $0.154. Kling 4.0 takes 1 unit a second at 720p and 1.5 at 1080p. That is $0.154 and $0.231 a second, or $1.15 for a 5-second 1080p video. Kling 4.0 Flash takes 0.6 units a second at 720p, $0.092 a second or $0.46 for 5 seconds (as of November 5, 2026). With an input video, Kling also bills its length: twice the output seconds when the input is no longer than the output, otherwise input plus output, at 0.6 units a second (0.9 at 1080p) for Kling 4.0 and 0.4 for Flash. Kling's other developer packs, from $700, don't cover Kling 4.0. Since November 19, 2026 it also lists Kling 4.0 in 4K at 3.5 units a second, $0.538 a second or $2.69 for 5 seconds, and HDR at 1080p and 4K for 0.3 and 0.5 units a second more. ### Kling 4.0 on a Kling AI subscription Through useapi.net, Kling 4.0 (`kling-v4-0`) runs on your Kling AI subscription's credits, 10 a second at 720p, 15 at 1080p and 35 at 4K on every plan. HDR adds 3 a second at 1080p and 5 at 4K, and Kling doesn't charge subscribers for it until November 30, 2026. Kling 4.0 Flash (`kling-v4-0-flash`) takes 6 a second at 720p. This is what one video costs on each plan, at the regular monthly price (as of November 2026): | Kling 4.0 | [Official API](https://kling.ai/dev/pricing) ($500 pack) | Premier $80.96/m (8,000 cr/mo) | Pro $32.56/m (3,000 cr/mo) | Standard $8.80/m (660 cr/mo) | |---|---|---|---|---| | 720p, 5 s | $0.77 ($0.154 a second) | $0.51 / 50 cr ($0.101 a second, 160 videos/mo) | $0.54 / 50 cr ($0.109 a second, 60 videos/mo) | $0.67 / 50 cr ($0.133 a second, 13 videos/mo) | | 1080p, 5 s | $1.15 ($0.231 a second) | $0.76 / 75 cr ($0.152 a second, 106 videos/mo) | $0.81 / 75 cr ($0.163 a second, 40 videos/mo) | $1.00 / 75 cr ($0.200 a second, 8 videos/mo) | | 1080p, 10 s | $2.31 | $1.52 / 150 cr (53 videos/mo) | $1.63 / 150 cr (20 videos/mo) | $2.00 / 150 cr (4 videos/mo) | | 1080p, 30 s | $6.92 | $4.55 / 450 cr (17 videos/mo) | $4.88 / 450 cr (6 videos/mo) | $6.00 / 450 cr (1 video/mo) | | 4K, 5 s | $2.69 ($0.538 a second) | $1.77 / 175 cr ($0.354 a second, 45 videos/mo) | $1.90 / 175 cr ($0.380 a second, 17 videos/mo) | $2.33 / 175 cr ($0.467 a second, 3 videos/mo) | | 1080p HDR, 5 s | $1.38 ($0.277 a second) | $0.91 / 90 cr (88 videos/mo) | $0.98 / 90 cr (33 videos/mo) | $1.20 / 90 cr (7 videos/mo) | | 4K HDR, 5 s | $3.08 ($0.615 a second) | $2.02 / 200 cr (40 videos/mo) | $2.17 / 200 cr (15 videos/mo) | $2.67 / 200 cr (3 videos/mo) | | 4.0 Flash, 720p, 5 s | $0.46 ($0.092 a second) | $0.30 / 30 cr ($0.061 a second, 266 videos/mo) | $0.33 / 30 cr ($0.065 a second, 100 videos/mo) | $0.40 / 30 cr ($0.080 a second, 22 videos/mo) | - The Official API column is Kling's developer API at its smallest regular Kling 4.0 pack, $500 for 3,250 units, valid 180 days. - 1080p (`mode: pro`) and 4K (`mode: 4k`) need a paid Kling AI subscription, and Standard is the smallest paid one. The HDR rows are at the full price: until November 30, 2026 Kling charges subscribers the price without HDR (75 and 175 credits for 5 seconds). Kling 4.0 Flash makes 720p only. - Ultra+ ($544.99 a month for 57,000 credits) brings 1080p down to $0.143 a second and 720p to $0.096. Billed yearly, Premier ($728.64 a year) is $0.114 a second at 1080p and Ultra+ ($4,902.99 a year) is $0.108. The yearly figures assume you use the credits. - The same credit price applies on all three Kling 4.0 endpoints: [text-to-video](/docs/api-kling-v1/post-kling-videos-text2video), [image-to-video with start, end and keyframe images](/docs/api-kling-v1/post-kling-videos-image2video-frames), and [Omni](/docs/api-kling-v1/post-kling-videos-omni) with reference images, IMAGE elements and voices. Omni with a reference video or a VIDEO element also counts the video's length: 12 credits a second at 720p, 18 at 1080p and 42 in 4K (8 on 4.0 Flash) when the clip is at least as long as the videos, which it is by default. A shorter clip costs more, because Kling bills the videos' seconds plus the clip's at 6, 9 and 21 credits a second (4 on Flash), the same way Kling's developer API bills an input video. Every video comes with a stereo soundtrack, from 3 to 30 seconds. - Kling 4.0 Flash runs on the same three endpoints, from a prompt, from a start image, or with Omni references other than voices (`omni_version: v4-flash`), 3 to 20 seconds with sound. The [cost calculator](/docs/api-kling-v1#pricing) on the Kling API page prices Kling 4.0 and every other Kling model on each subscription, yearly billing included. ### Kling 4.0 API pricing across resellers Several API resellers already sell Kling 4.0 per second of output. Here is every rate we could verify, read from each vendor's live page on November 5, 2026, with no video input: | Route | 720p, per second | 1080p, per second | 1080p, 5 s | Notes | |:------|-----------------:|------------------:|-----------:|:------| | [useapi.net, PixVerse Ultra](/docs/api-pixverse-v2#pricing) | $0.066 | $0.0995 | $0.50 | on the $199 PixVerse Ultra plan, 80% off unless the request sends `relax_mode: false`, 400 five-second 1080p videos a month | | [useapi.net, Kling Premier](/docs/api-kling-v1) | $0.101 | $0.152 | $0.76 | 106 five-second 1080p videos a month on the $80.96 plan | | [useapi.net, Kling Pro](/docs/api-kling-v1) | $0.109 | $0.163 | $0.81 | 40 five-second 1080p videos a month on the $32.56 plan | | [UnificAlly](https://unifically.com/blogs/kling-4.0) | $0.126 | $0.189 | $0.95 | list rate, its 10% launch sale ended October 29 | | [Kie.ai](https://kie.ai/kling-4-0) | $0.1425 | $0.2125 | $1.06 | about 10% less with the bonus credits on larger top-ups | | [Kling developer API](https://kling.ai/dev/pricing) | $0.154 | $0.231 | $1.15 | prepaid Kling 4.0 packs from $500, valid 180 days | | [fal.ai](https://fal.ai/models/kling/v4/text-to-video) | $0.157 | $0.235 | $1.18 | the same rate for text-to-video and image-to-video | | [Runware](https://runware.ai/kling-4) | $0.157 | $0.235 | $1.18 | | | [WaveSpeedAI](https://wavespeed.ai/models/kwaivgi/kling-v4.0/text-to-video) | $0.157 | $0.235 | $1.18 | its Generate button showed 20% off on November 5, $0.94 for 5 s at 1080p | | [useapi.net, PixVerse Premium](/docs/api-pixverse-v2#pricing) | $0.20 | $0.30 | $1.50 | on the $60 PixVerse Premium plan, 40 five-second 1080p videos a month | | [useapi.net, PixVerse Pro](/docs/api-pixverse-v2#pricing) | $0.25 | $0.375 | $1.88 | on the $30 PixVerse Pro plan, 16 five-second 1080p videos a month | | [useapi.net, PixVerse Ultra, `relax_mode: false`](/docs/api-pixverse-v2#pricing) | $0.332 | $0.498 | $2.49 | on the $199 PixVerse Ultra plan at the full price, 80 five-second 1080p videos a month | Kling 4.0 also runs on a PixVerse subscription through the [useapi.net PixVerse API](/docs/api-pixverse-v2) (`kling-4.0`). On PixVerse Ultra it is the lowest rate in the table, because PixVerse takes 80% off Kling 4.0 on Ultra unless the request sends `relax_mode: false` (as of November 15, 2026). On Premium and Pro, and on Ultra with `relax_mode: false`, it costs more per second than on a Kling subscription. PixVerse runs these discounts as promotions and changes them without notice. Kling 4.0 Flash is on sale at four of these resellers, at 720p only: $0.0799 a second on Runware, $0.085 on Kie.ai, and $0.094 on fal.ai and WaveSpeedAI, while UnificAlly lists it as coming soon. Through useapi.net, Flash costs $0.061 a second on Kling Premier and $0.065 on Pro (as of November 5, 2026). The "Kling 4.0 API price" quoted around the web, about $0.11 to $0.14 a second, is the 720p rate, and the lowest of those, $0.1134, was UnificAlly's launch sale, which has ended. When you compare, match the resolution and check for a promotion. ### What the subscription figures assume A subscription price per video holds when you use the plan's credits. Premier's 8,000 credits a month make 106 five-second 1080p videos or 17 thirty-second ones. For more volume, connect several Kling accounts to one useapi.net token and it spreads jobs across them ([Run several Kling accounts](/docs/api-kling-v1#run-several-kling-accounts)), or buy [Kling credit top-ups](https://kling.ai/app/membership/spirit-unit). Kling also sets the price. Its launch discount on Kling 4.0 for subscribers has ended, and on November 5, 2026 every plan paid the full 10 and 15 credits a second, as in the tables above. Check the live [plans page](https://kling.ai/app/membership/membership-plan) before you commit spend. At full price, Premier's $0.152 a second at 1080p stays below every 1080p reseller rate above. To make your first Kling 4.0 video, the [Kling 4.0 tutorial](/docs/articles/kling-4-api) walks through one real run with `curl`, from the request to the downloaded MP4, plus 1080p, 30-second, 21:9 and keyframe variants. ### Examples ###### Kling 4.0 » `kling-v4-0`, text-to-video, `std` 720p, 3 seconds, `16:9` <video src="https://media.useapi.net/articles/2026-10-18-kling-4-api/kling-4-0-paper-boat-720p-3s.mp4" poster="https://media.useapi.net/articles/2026-10-18-kling-4-api/kling-4-0-paper-boat-720p-3s-poster.jpg" style="width: 100%; max-width: 720px; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> This video took 27 credits off a Kling Pro subscription on October 18, 2026, during Kling's launch discount, with its stereo soundtrack. At the full price Kling charges now (November 2026), the same clip uses 30 credits, $0.33 at Pro's credit price. The prompt and every response are in the [Kling 4.0 tutorial](/docs/articles/kling-4-api). ## Questions ### How much does the Kling 4.0 API cost? Through useapi.net, a 10-second 1080p Kling 4.0 video uses $1.52 of a Kling Premier subscription's credits, against $2.31 on Kling's own developer API and $2.35 on fal.ai (as of November 5, 2026). The [price table](#kling-40-on-a-kling-ai-subscription) shows every length on each plan. ### What is the Kling 4.0 price per second? Through useapi.net, Kling 4.0 costs $0.152 a second at 1080p and $0.101 at 720p on Kling Premier (as of November 2026). That is lower than every reseller we checked, whose rates start at $0.189 and $0.126 (as of November 5, 2026). Kling 4.0 Flash costs $0.061 a second on Premier, against $0.092 on Kling's developer API and from $0.0799 at resellers. The [reseller table](#kling-40-api-pricing-across-resellers) lists each one. ### What does a 30-second Kling 4.0 video cost? Through useapi.net, a 30-second 1080p Kling 4.0 video, the longest single generation, uses $4.55 of a Premier subscription's credits or $4.88 on Pro, against $6.92 on Kling's developer API and $7.05 on fal.ai (as of November 5, 2026). Premier makes 17 of them a month. ### Do I need a prepaid pack or a Kling API key? Through useapi.net, no: you need a useapi.net [API token](/docs/start-here/setup-useapi) and a Kling AI subscription from Standard at $8.80 a month, connected once through [Setup Kling](/docs/start-here/setup-kling). Kling's own developer API needs a separate developer account and a prepaid Kling 4.0 pack from $500, valid 180 days (as of November 5, 2026). --- Kling's subscription and developer API prices and every reseller price in this article were read on November 5, 2026. Kling, the resellers and their promotions change often, so confirm the live rate before you scale. Connect your Kling account with [Setup Kling](/docs/start-here/setup-kling), price any model on the [Kling API](/docs/api-kling-v1) page, and a [useapi.net subscription](/docs/subscription) runs Kling and every other API with one token, including the hosted [Kling MCP server](/docs/api-kling-v1/mcp) for Claude Code, Cursor and VS Code. ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/kling-4-api === Document URL: https://useapi.net/docs/articles/kling-4-api --- layout: default title: How to Generate Kling 4.0 Video via the Kling API description: "Generate Kling 4.0 video from code on your Kling AI subscription: one real text-to-video run with the third-party useapi.net Kling API, 3-30s, 720p, 1080p or 4K with optional HDR, stereo audio, plus the lower-cost Kling 4.0 Flash." keywords: [Kling 4.0 API, Kling 4 API, kling-v4-0, Kling 4.0 4K, Kling 4.0 HDR, Kling 4.0 Flash API, kling-v4-0-flash, Kling API, Kling AI API, Kling 4.0 text to video, Kling 4.0 image to video, Kling 4.0 keyframes, Kling Omni 4.0, Kuaishou, AI video API, Kling MCP server, curl, tutorial] image: https://media.useapi.net/articles/2026-10-18-kling-4-api/kling-4-0-paper-boat-720p-3s-poster.jpg parent: Articles nav_exclude: true date: 2026-10-18 last_modified: 2026-11-19 nav_order: 855 repo: https://github.com/useapi/kling-api --- ## How to Generate Kling 4.0 Video via the Kling API 6 min read • October 18, 2026 (November 19, 2026) ## Table of contents ### Introduction Kling 4.0 launched in the Kling app on October 15, 2026, and the useapi.net Kling API has run it on your [Kling AI website subscription](https://kling.ai/app/membership/membership-plan) since that day, while Kling's own developer API added it between October 25 and 28, at higher prices. To call it, send `"model_name": "kling-v4-0"` to [POST /videos/text2video](/docs/api-kling-v1/post-kling-videos-text2video). useapi.net is a [third-party](/docs/legal#affiliation--third-party-services) API, not affiliated with [Kling AI](https://kling.ai/app) or [Kuaishou Technology](https://www.kuaishou.com/en). Kling 4.0 makes 3 to 30 second clips at 720p or 1080p, and since November 19, 2026 also in 4K, with optional HDR at 1080p and 4K, always with a stereo soundtrack, and adds the `21:9` aspect ratio and keyframes between the start and end frames. Since November 5, 2026 the API also runs Kling 4.0 Flash (`kling-v4-0-flash`), a lower-cost 720p version for 3 to 20 second clips. This guide is one real run. We asked Kling 4.0 for the cheapest clip it makes, 3 seconds at 720p, on a Kling Pro subscription. The job finished in about 2 minutes and took 27 Kling credits off the balance (300,290 to 297,590 in the account's hundredths of a credit), about $0.29 at the Pro plan's credit price, during Kling's launch discount for subscribers. That discount has ended, and the same clip now uses 30 credits, $0.33 (as of November 2026). Every response below is from that run, with the account email left out. ### Before you start You need a useapi.net [API token](/docs/start-here/setup-useapi) and a Kling account connected through [Setup Kling](/docs/start-here/setup-kling). Kling 4.0 at 1080p or 4K needs a paid Kling plan. Export the token so the `curl` examples run as they are: ```bash export USEAPI_TOKEN="user:1234-..." # your useapi.net API token export KLING_EMAIL="you@example.com" # your connected Kling account ``` `email` is optional in the request body: without it, the API picks one of your Kling accounts that has a free job slot (`429` when every account is busy). With more than one account, note which account ran the job ([GET tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) explains how to find it), because polling the task needs that account's `email`. If Kling hasn't opened Kling 4.0 to your account yet, the create call returns `403` with `AUTH.VPrivilegeEscalation`, and nothing is charged. ### Kling 4.0 at a glance | | Kling 4.0 (`kling-v4-0`) | Kling 4.0 Flash (`kling-v4-0-flash`) | |---|---|---| | Duration | 3 to 30 seconds, default 5 | 3 to 20 seconds, default 5 | | Resolution | `std` 720p, `pro` 1080p, `4k` 4K (paid Kling plan). [HDR](#4k-and-hdr) at 1080p and 4K with `hdr: true` | `std` 720p only, no HDR | | Aspect ratio | `16:9`, `9:16`, `1:1`, `21:9` | `16:9`, `9:16`, `1:1`, `21:9` | | Audio | Always on, stereo | Always on | | Prompt | Up to 8000 characters | Up to 8000 characters | | Shots | Kling may cut the clip into several shots, or you write up to 6 shot prompts (15 seconds in total) | No multi-shot parameters | | Frames (image-to-video) | Start, end and up to 9 keyframes | Start image only | | Credits per second | 10 at 720p, 15 at 1080p, 35 at 4K, on every Kling plan. HDR adds 3 at 1080p and 5 at 4K, waived for subscribers until November 30, 2026 | 6 at 720p | The same model is on three endpoints: [text-to-video](/docs/api-kling-v1/post-kling-videos-text2video), [image-to-video](/docs/api-kling-v1/post-kling-videos-image2video-frames) with start, end and keyframe images, and [Omni](/docs/api-kling-v1/post-kling-videos-omni) with reference images, elements, videos and voices. The credit price is the same on all three, for Kling 4.0 and for Flash, except that Omni with a reference video or a VIDEO element also counts the video's length: 12 credits a second at 720p, 18 at 1080p and 42 in 4K (8 on Flash) when the clip is at least as long as the videos, which it is by default, and more for a shorter clip ([how Kling bills it](/docs/api-kling-v1/post-kling-videos-omni)). ### Generate a Kling 4.0 video in two calls Generation is asynchronous. The create call answers right away with a task, and you poll the task until it is final. #### 1. Submit the job [POST /videos/text2video](/docs/api-kling-v1/post-kling-videos-text2video) with `model_name` set to `kling-v4-0`: ```bash curl -s -X POST "https://api.useapi.net/v1/kling/videos/text2video" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$KLING_EMAIL"'", "model_name": "kling-v4-0", "mode": "std", "duration": "3", "aspect_ratio": "16:9", "prompt": "A small paper boat sails across a rain puddle on a city sidewalk at dusk, neon signs reflect and ripple in the water, raindrops patter around it and a tram bell rings in the distance, low camera at water level" }' ``` The answer came back in about a second. The parts that matter, from our run: ```json { "task": { "id": 324332112308198, "type": "m2v_aio2video", "status": 5, "status_name": "submitted", "status_final": false }, "works": [], "status": 5, "status_name": "submitted", "status_final": false, "message": "", "userPoints": { "points": [], "total": 297590 } } ``` `task.id` is the id you poll. `userPoints.total` is the balance after the charge, in hundredths of a credit, so 297590 is 2,975.90 credits. The task's `arguments` echo what Kling received: `kling_version` 4.0, `model_mode` std, `enable_audio` true and `prefer_multi_shots` true. Kling 4.0 always turns audio on, and it may cut the clip into shots on its own. The create call is the paid step, so don't resend it after a timeout. Poll or list your tasks instead. #### 2. Poll for the result [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id): ```bash curl -s "https://api.useapi.net/v1/kling/tasks/324332112308198?email=$KLING_EMAIL" \ -H "Authorization: Bearer $USEAPI_TOKEN" ``` Ours read `processing` for about 2 minutes, then: ```json { "status": 99, "status_name": "succeed", "status_final": true, "works": [ { "workId": 324332112317252, "status_name": "succeed", "resource": { "resource": "https://v15-kling.klingai.com/bs2/upload-ylab-stunt-sgp/....mp4", "height": 720, "width": 1280, "duration": 3041 } } ] } ``` The MP4 is 1280×720, 3.04 seconds, H.264 video with a two-channel AAC soundtrack. A task is done when `status_final` is `true`, and `status_name: "succeed"` means it worked. The other final statuses are failures, listed on [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id#model). Pass a `replyUrl` in the create body if you'd rather get a webhook than poll. #### 3. Download the master Free Kling plans get a watermarked `works[0].resource.resource`. On a paid plan, [GET /assets/download](/docs/api-kling-v1/get-kling-assets-download) returns a `cdnUrl` to the clean file: ```bash curl -s "https://api.useapi.net/v1/kling/assets/download?email=$KLING_EMAIL&workIds=324332112317252&fileTypes=MP4" \ -H "Authorization: Bearer $USEAPI_TOKEN" ``` ### Longer, wider and 1080p Change three fields and keep the rest. A 10-second 1080p cinema-wide clip: ```json { "model_name": "kling-v4-0", "mode": "pro", "duration": "10", "aspect_ratio": "21:9", "prompt": "..." } ``` That costs 150 credits (15 per second) on every Kling plan. `duration` goes up to `30`. To direct the cuts yourself, send `shot_1_prompt` with `shot_1_duration`, `shot_2_prompt` with `shot_2_duration` and so on, up to 6 shots and 15 seconds in total, in place of `prompt` and `duration`. `negative_prompt` and `cfg_scale` don't apply to Kling 4.0. ### 4K and HDR Since November 19, 2026, Kling 4.0 also makes 4K video and HDR video, on a paid Kling plan. Send `"mode": "4k"` for 4K, and add `"hdr": true` for HDR at 1080p (`pro`) or 4K. HDR is not available at 720p, and Kling 4.0 Flash has neither. The same two fields work on [image-to-video](/docs/api-kling-v1/post-kling-videos-image2video-frames) and on [Omni](/docs/api-kling-v1/post-kling-videos-omni) with `omni_version: v4`: ```json { "model_name": "kling-v4-0", "mode": "4k", "hdr": true, "duration": "5", "prompt": "..." } ``` 4K costs 35 credits a second, so a 5-second clip uses 175 credits, $1.90 on Kling Pro. HDR adds 3 credits a second at 1080p and 5 at 4K, but Kling doesn't charge subscribers for it until November 30, 2026 (as of November 19, 2026). The task's `works[0].resource.resource` is a 1080p preview in standard dynamic range. The 4K and HDR files come from [GET /assets/download](/docs/api-kling-v1/get-kling-assets-download), as in [step 3](#3-download-the-master): a 3840×2160 H.264 MP4 for 4K, and a 10-bit HEVC MP4 in HLG (BT.2020) for HDR. [The examples below](#examples) are two such files. ### Image-to-video with keyframes [POST /videos/image2video-frames](/docs/api-kling-v1/post-kling-videos-image2video-frames) with `model_name: kling-v4-0` takes a start frame (`image`, required), an optional end frame (`image_tail`) and up to 9 keyframes in between (`keyframe_1` to `keyframe_9`), in order. That is up to 10 images in total, and at most the duration in seconds plus one, so a 5-second clip takes up to 6 images. Upload each image with [POST /assets](/docs/api-kling-v1/post-kling-assets) first and pass the returned URLs: ```bash curl -s -X POST "https://api.useapi.net/v1/kling/videos/image2video-frames" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$KLING_EMAIL"'", "model_name": "kling-v4-0", "mode": "std", "duration": "5", "image": "https://example.com/start.jpg", "keyframe_1": "https://example.com/middle.jpg", "image_tail": "https://example.com/end.jpg", "prompt": "the boat drifts from the puddle into the gutter stream" }' ``` The aspect ratio comes from the start image. You poll and download the result the same way as above. ### Omni with references and voices [POST /videos/omni](/docs/api-kling-v1/post-kling-videos-omni) with `omni_version: v4` runs Kling 4.0 with up to 10 reference images, 7 elements (IMAGE and VIDEO), 5 reference videos of 3 to 30 seconds each (30 seconds in total) and 3 voices, including your own voice saved with [POST /videos/voices](/docs/api-kling-v1/post-kling-videos-voices). Reference them in the prompt as `@image_1`, `@video_1` or `@voice_1`. `omni_version: v4-flash` runs Kling 4.0 Flash with the same images, elements and up to 5 reference videos (3 to 20 seconds each, 20 seconds in total), but no voices. Omni 4.0 doesn't take start and end frames, so use image-to-video above for those. The [Kling Omni tutorial](/docs/articles/kling-omni-bash) walks through the reference workflows. ### Batch-generate with the script The [`kling-4` example](https://github.com/useapi/kling-api/tree/main/kling-4) in the `kling-api` GitHub repo reads Kling 4.0 prompts from `prompts.json` (text-to-video, 21:9 and multi-shot) or `prompts-frames.json` (start, end and keyframe images), checks each one against the documented limits before it spends credits, submits it, polls the task and downloads the clean master. Run it with Node.js v21 or newer: ```bash git clone https://github.com/useapi/kling-api.git cd kling-api/kling-4 node ./kling4.mjs "$USEAPI_TOKEN" "$KLING_EMAIL" ``` The [Kling v3 tutorial](/docs/articles/kling-bash) explains the script line by line. ### What it costs Kling 4.0 uses the credits of your Kling AI website subscription, at the rates in the [table above](#kling-40-at-a-glance), and useapi.net adds no per-video charge. On Kling Pro ($32.56 a month for 3,000 credits), that comes to about $0.11 a second at 720p and $0.16 at 1080p, so a 5-second 720p video uses 50 credits, $0.54, and the plan makes 60 of them a month. A 5-second Kling 4.0 Flash video uses 30 credits, $0.33 on Pro (as of November 2026). The [cost calculator](/docs/api-kling-v1) on the Kling API page prices every model on each Kling plan. Kling's own [developer API](https://kling.ai/dev/pricing) sells Kling 4.0 in prepaid packs from $500 instead, separate from the app subscriptions: $0.154 a second at 720p and $0.231 at 1080p, and $0.092 a second for Kling 4.0 Flash (as of November 5, 2026). [Kling 4.0 API pricing](/docs/articles/kling-4-api-pricing) compares the price per second on each Kling plan with Kling's developer API and the API resellers. Kling 4.0 also runs on a PixVerse subscription, through the [useapi.net PixVerse API](/docs/api-pixverse-v2) with `"model": "kling-4.0"` in [POST videos/create](/docs/api-pixverse-v2/post-pixverse-videos-create-v4). On PixVerse Ultra a 5-second 1080p video costs $0.50, below every Kling plan, because PixVerse takes 80% off unless the request sends `relax_mode: false`. On Premium and Pro it costs more per second than on a Kling plan (as of November 15, 2026, [every route compared](/docs/articles/kling-4-api-pricing#kling-40-api-pricing-across-resellers)). ### The same from an AI assistant The hosted [Kling MCP server](/docs/api-kling-v1/mcp) at `https://api.useapi.net/v1/kling/mcp` exposes the same calls as 45 tools for Claude Code, Cursor and VS Code, Kling 4.0 and 4.0 Flash included. Ask for "a 5-second Kling 4.0 clip of …" and the assistant calls `kling_text_to_video` with `model_name: kling-v4-0` on your account. ### Examples ###### Kling 4.0 » `kling-v4-0`, text-to-video, `std` 720p, 3 seconds, `16:9`, the run above <video src="https://media.useapi.net/articles/2026-10-18-kling-4-api/kling-4-0-paper-boat-720p-3s.mp4" poster="https://media.useapi.net/articles/2026-10-18-kling-4-api/kling-4-0-paper-boat-720p-3s-poster.jpg" style="width: 100%; max-width: 720px; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> The prompt is in [step 1](#1-submit-the-job). 27 Kling credits on a Pro plan during Kling's launch discount (30 at the full price), about 2 minutes, with its stereo soundtrack. Four more Kling 4.0 clips, 9:16 at 720p with their own sound, made with the [batch script](https://github.com/useapi/kling-api/tree/main/kling-4) at 45 credits each on Kling Pro during the launch discount, are in a 20-second [YouTube Short](https://youtube.com/shorts/Xr73upGKG2c). ###### Kling 4.0 » `kling-v4-0`, text-to-video, `4k` 4K, 5 seconds, `16:9` <video src="https://media.useapi.net/kling/2026-11-19-kling-4-4k-hdr/kling-4-0-hummingbird-4k-5s.mp4" poster="https://media.useapi.net/kling/2026-11-19-kling-4-4k-hdr/kling-4-0-hummingbird-4k-5s-poster.jpg" style="width: 100%; max-width: 720px; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> "Macro close-up of a ruby-throated hummingbird hovering at a red hibiscus flower in low morning sun, iridescent green feathers catching the light, tiny water droplets on the petals, soft bokeh garden behind, the wings a blur while the eye stays tack sharp, gentle hum of wings and distant birdsong". The 3840×2160 master from GET /assets/download, 175 Kling credits (November 19, 2026). Play it full screen to see the detail. ###### Kling 4.0 » `kling-v4-0`, text-to-video, `pro` 1080p, `hdr: true`, 5 seconds, `16:9` <video poster="https://media.useapi.net/kling/2026-11-19-kling-4-4k-hdr/kling-4-0-paper-boat-1080p-hdr-5s-poster.jpg" style="width: 100%; max-width: 720px; aspect-ratio: 16/9;" controls preload="metadata"> <source src="https://media.useapi.net/kling/2026-11-19-kling-4-4k-hdr/kling-4-0-paper-boat-1080p-hdr-5s.mp4" type='video/mp4; codecs="hvc1"'> <source src="https://media.useapi.net/kling/2026-11-19-kling-4-4k-hdr/kling-4-0-paper-boat-1080p-hdr-5s-sdr.mp4" type="video/mp4"> </video> The paper boat prompt from [step 1](#1-submit-the-job), again, now with HDR: the neon reflections and the dusk sky keep their highlights. The 10-bit HLG master from GET /assets/download (November 19, 2026). It plays in HDR on an HDR screen in a browser that plays HEVC (Safari, Edge and Chrome on most computers and phones); other browsers get Kling's standard-range preview of the same clip. Kling 4.0 Flash (`kling-v4-0-flash`, text-to-video, `std` 720p, 10 seconds, `16:9`) made this [cinematic muscle-car clip with sound](https://youtu.be/EGWY2mJ5yOk) from one prompt: 60 Kling credits, $0.61 on Kling Premier (November 5, 2026). ### Frequently asked questions **Is there a Kling 4.0 API?** Through useapi.net, yes, on your Kling AI website subscription: $0.152 a second at 1080p on Kling Premier, from a prompt, from start, end and key frames, or from Omni references and voices, and Kling 4.0 Flash at 720p. Kling's own [developer API](https://kling.ai/dev/pricing) charges $0.231 a second at 1080p, in prepaid packs from $500 sold separately from the app subscriptions (as of November 5, 2026). **What is the model name for Kling 4.0?** Through useapi.net, Kling 4.0 is `kling-v4-0` in the `model_name` field of [POST /videos/text2video](/docs/api-kling-v1/post-kling-videos-text2video) and [POST /videos/image2video-frames](/docs/api-kling-v1/post-kling-videos-image2video-frames), and `omni_version: v4` on [POST /videos/omni](/docs/api-kling-v1/post-kling-videos-omni). Kling 4.0 Flash is `kling-v4-0-flash`, or `omni_version: v4-flash`. `negative_prompt` and `cfg_scale` don't apply to either, and the credit price is the same on all three endpoints, apart from Kling 4.0 on Omni with a reference video (12 and 18 credits a second). **Does Kling 4.0 need a paid Kling plan?** Through useapi.net, Kling 4.0 at 720p (`mode: std`) runs on any Kling account that has credits, including credits bought without a subscription, and 1080p (`mode: pro`) or 4K (`mode: 4k`), with or without HDR, needs a paid Kling AI subscription. The Free plan has no monthly credits, so it needs a credit pack first. A `403` with `AUTH.VPrivilegeEscalation` means Kling hasn't opened the model to that account yet, and nothing is charged. Kling 4.0 Flash makes 720p only. **Can I turn audio off?** Through useapi.net, no: Kling 4.0 always makes a stereo soundtrack and doesn't accept `enable_audio`, so leave the field out. Our test video came back with two-channel AAC audio next to H.264 video. For a video without sound, use Kling v3 (`kling-v3-0`) instead, where `enable_audio: false` turns the sound off. **How long can a Kling 4.0 video be?** Through useapi.net, a Kling 4.0 video runs 3 to 30 seconds in one generation, set with `duration`, while Kling 4.0 Flash stops at 20 seconds and Kling v3 at 15. When you write the shots yourself with `shot_1_prompt` to `shot_6_prompt`, the total stays within 15 seconds, and a single prompt may still be cut into several shots by Kling. **Do I need a Kling developer account or API key?** Through useapi.net, no: you need a useapi.net [API token](/docs/start-here/setup-useapi) and a Kling account connected once through [Setup Kling](/docs/start-here/setup-kling), with no Kling developer account and no prepaid pack. The same token works on the hosted [Kling MCP server](/docs/api-kling-v1/mcp), so Claude Code, Cursor or VS Code can make Kling 4.0 videos for you. ### Conclusion Kling 4.0 is one field away from any Kling call you already make: set `model_name` to `kling-v4-0` and pick a duration up to 30 seconds. The full model reference is on the [Kling API](/docs/api-kling-v1) page, and the runnable code is in the [`kling-api` GitHub repo](https://github.com/useapi/kling-api). Visit our <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> or <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> for any support questions and concerns. === URL: https://useapi.net/docs/articles/kling-bash === Document URL: https://useapi.net/docs/articles/kling-bash --- layout: default title: How to Generate AI Video with Kling v3 via the Kling API description: "Drive Kling AI (Kuaishou) video generation from code via a third-party REST API — Kling v3, v3 Turbo, 2.6, 2.5, 2.1 and 1.6, with copy-paste curl, models, and pricing." keywords: [Kling API, Kling v3 API, Kling AI API, Kuaishou, text to video, image to video, video generation, Kling video API, AI video API] parent: Articles nav_exclude: true date: 2026-06-22 last_modified: 2026-10-20 nav_order: 850 repo: https://github.com/useapi/kling-api --- ## How to Generate AI Video with Kling v3 via the Kling API 6 min read • June 22, 2026 (October 20, 2026) ## Table of contents ### Introduction Kling AI is rated by independent text-to-video leaderboards among the strongest models for prompt adherence and motion realism, and you can drive every Kling model from code on your [Kling AI website subscription](https://kling.ai/app/membership/membership-plan). [Kling AI](https://app.klingai.com) is the video service of the Chinese short-video company [Kuaishou Technology](https://www.kuaishou.com/en), and the third-party useapi.net [Kling API](/docs/api-kling-v1) runs it over a standard REST endpoint, with no enterprise contract and no per-video charge from us. ### Supported models Pick a model per request with the `model_name` field on [POST /videos/text2video](/docs/api-kling-v1/post-kling-videos-text2video). `kling-v1-6` is the default. Capabilities differ by version: | Model | Durations | Modes / resolution | Audio | |-------|-----------|--------------------|-------| | `kling-v3-0` | 3–15s | `std` 720p · `pro` 1080p · `4k` 4K | Default on | | `kling-v3-0-turbo` | 3–15s | `std` 720p · `pro` 1080p | Always on | | `kling-v2-6` | 5 / 10s | `std` 720p · `pro` 1080p | Native Audio (`pro`) | | `kling-v2-5` | 5 / 10s | `pro` 1080p only | Sound effects | | `kling-v2-1-master` | 5 / 10s | `pro` 1080p only | Sound effects | | `kling-v1-6` (default) | 5 / 10s | `std` 720p · `pro` 1080p | Sound effects | | `kling-v1-5` | 5 / 10s | `std` 720p · `pro` 1080p | Sound effects | Model `v3-0` is the most capable: it adds `4k` mode and audio on by default. Model `v3-0-turbo` is the faster v3 — it keeps v3.0 quality with shorter generation times, audio always on, and `std`/`pro` modes (no `4k`). Model `2.6` produces Native Audio, but only in `pro` mode. The `negative_prompt` and `cfg_scale` parameters apply only to the 1.x models — `2.5`, `2.6`, and `3.0` do not support `negative_prompt`, and `cfg_scale` is a 1.x-only control. The same account and token also drive Kling's multi-shot storytelling, Video Elements, Avatars, and lip-sync — see the [Kling API overview](/docs/api-kling-v1) for the full lineup. ### Pricing Videos use the credits of your [Kling AI website subscription](https://kling.ai/app/membership/membership-plan) at Kling's own rates, which vary by model, mode, duration and audio, and useapi.net adds no per-video charge. Kuaishou's [official Kling API](https://kling.ai/dev/pricing) is billed separately, on a developer account with prepaid packs. The [Kling API overview](/docs/api-kling-v1) has a live cost calculator for every model on each Kling plan. ### Generate a video in two API calls You need a useapi.net [API token](/docs/start-here/setup-useapi) and a connected [Kling account](/docs/start-here/setup-kling) — export the token so the `curl` examples below run as-is: ```bash export USEAPI_TOKEN="user:1234-..." ``` Generation is asynchronous — the create call returns a task object immediately, then you poll until the video is ready. #### 1. Submit the job `POST https://api.useapi.net/v1/kling/videos/text2video`: ```bash curl -X POST "https://api.useapi.net/v1/kling/videos/text2video" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A majestic mountain landscape with snow-capped peaks and flowing rivers, camera slowly panning right", "model_name": "kling-v3-0", "aspect_ratio": "16:9", "mode": "pro", "duration": "5" }' ``` The response returns immediately with a task object. The task id you poll on is `task.id` (a number): ```json { "task": { "id": 123456789, "type": "m2v_aio2video", "status": 5, "status_name": "submitted", "status_final": false }, "works": [], "status": 5, "status_name": "submitted", "status_final": false, "message": "" } ``` The `email` field is optional: without it, the API picks one of your Kling accounts that has a free job slot (`429` when every account is busy). With more than one account, note which account ran the job ([GET tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) explains how to find it), because polling the task needs that account's `email`. A `500` from Kling almost always means a content-moderation rejection rather than a server fault — read the `error` text (the `message` field is generic and often misleading) to tell them apart. #### 2. Poll for the result `GET https://api.useapi.net/v1/kling/tasks/{task_id}`: ```bash curl "https://api.useapi.net/v1/kling/tasks/123456789?email=user@example.com" \ -H "Authorization: Bearer $USEAPI_TOKEN" ``` The task is done when `status_final` is `true`. Success is `status_name: "succeed"` (`status: 99`), and the MP4 is in `works[0].resource.resource`: ```json { "status": 99, "status_name": "succeed", "status_final": true, "works": [ { "workId": 123456789, "status_name": "succeed", "resource": { "resource": "https://s21-kling.klingai.com/....mp4", "height": 1268, "width": 724, "duration": 5041 } } ] } ``` The MP4 at `works[0].resource.resource` is watermarked. To get the clean, non-watermarked master, take the `workId` from the `works` array and call [GET /assets/download](/docs/api-kling-v1/get-kling-assets-download) — it returns a `cdnUrl` to the file (a single `workId` plus a single `fileTypes` value yields a direct MP4 link, otherwise a `.zip`): ```bash curl "https://api.useapi.net/v1/kling/assets/download?email=user@example.com&workIds=123456789&fileTypes=MP4" \ -H "Authorization: Bearer $USEAPI_TOKEN" ``` A video typically finishes in a few minutes depending on model, mode, and duration — `std` is faster than `pro` or `4k`. Prefer not to poll? Pass a `replyUrl` in the create body to receive a webhook callback when the task completes. On the poll, a `404` means the task was deleted, failed at moderation, or your Kling account ran out of credits — check your balance at [GET /accounts/`email`](/docs/api-kling-v1/get-kling-accounts-email). The terminal failure statuses are `6`, `7`, `9`, `50`, `53`, `54`, and `58` (all `status_final: true`). See [GET /tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id#model) for what each one means. ### Image-to-video To animate a still image, use [POST /videos/image2video-frames](/docs/api-kling-v1/post-kling-videos-image2video-frames). Upload your image first with [POST /assets](/docs/api-kling-v1/post-kling-assets), then pass the returned URL as `image` (the start frame) and optionally `image_tail` (the end frame, for a start→end transition): ```bash curl -X POST "https://api.useapi.net/v1/kling/videos/image2video-frames" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "image": "https://example.com/start-frame.jpg", "image_tail": "https://example.com/end-frame.jpg", "prompt": "the character turns and smiles, camera pushes in", "model_name": "kling-v2-5", "mode": "pro" }' ``` At least one of `image` or `image_tail` is required. On `kling-v3-0` / `kling-v3-0-turbo` the aspect ratio is derived from the input image, so there is no `aspect_ratio` parameter — and `kling-v3-0-turbo` supports the start frame only (no `image_tail`). The response is the same task object as text-to-video, and you poll and download it exactly the same way (with [GET /assets/download](/docs/api-kling-v1/get-kling-assets-download) for the clean master). ### Batch-generate with a script Finding the right shot takes many attempts, and running them by hand is tedious. The Node.js script below reads a list of prompts from `prompts.json`, submits each text-to-video job, then polls every task until it is final and downloads the finished MP4 — preferring the clean, non-watermarked master via [GET /assets/download](/docs/api-kling-v1/get-kling-assets-download) and falling back to the watermarked `works[0].resource.resource` if needed. So you can queue a batch and come back to the winners. You need [Node.js](https://nodejs.org) v21 or newer. Put `prompts.json` and `kling.mjs` in the same folder and run `node ./kling.mjs API_TOKEN EMAIL`, where `API_TOKEN` is your useapi.net [API token](/docs/start-here/setup-useapi) and `EMAIL` is your connected [Kling account](/docs/start-here/setup-kling) email. The script looks the account up by email automatically. <details markdown="block"> <summary>Expand `prompts.json`</summary> ```json [ { "prompt": "By default the kling-v1-6 model with a 16:9 aspect ratio, std (720p) mode and a 5-second duration will be used." }, { "model_name": "kling-v3-0", "aspect_ratio": "16:9", "mode": "pro", "duration": "5", "prompt": "A majestic mountain landscape with snow-capped peaks and flowing rivers, camera slowly panning right. For all parameters see https://useapi.net/docs/api-kling-v1/post-kling-videos-text2video" }, { "model_name": "kling-v3-0-turbo", "mode": "pro", "duration": "10", "prompt": "Faster Kling v3 Turbo generation. Audio is always on and the prompt can carry spoken dialogue and scene changes." }, { "model_name": "kling-v1-6", "aspect_ratio": "9:16", "mode": "pro", "duration": "5", "negative_prompt": "people, buildings, text, low quality", "prompt": "negative_prompt and cfg_scale apply only to the 1.x models. Models 2.5, 2.6 and 3.0 do not support negative_prompt." } ] ``` </details> <details markdown="block"> <summary>Expand `kling.mjs` script</summary> ```javascript /* Script version 1.0, June 22, 2026 Script to batch-generate videos using prompts with the Kling API v1 by useapi.net 🚀 Defaults to the kling-v1-6 model and uses the asynchronous text2video endpoint. For more details visit https://useapi.net/docs/api-kling-v1/post-kling-videos-text2video Installation Instructions: ========================== You need Node.js v21 or newer installed to run this script. Download and install Node.js from: - Windows, macOS, Linux: https://nodejs.org/ After installation, verify by running the following command in a terminal: node -v Running the Script: =================== Usage: node kling.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE] Replace API_TOKEN with your actual useapi.net API token, see https://useapi.net/docs/start-here/setup-useapi Replace EMAIL with configured Kling email account, see https://useapi.net/docs/start-here/setup-kling If optional PROMPTS_FILE not provided prompts.json will be used. Example: -------- node kling.mjs user:1234-abcdefhijklmnopqrstuv my@email.com This command executes the script using API token user:1234-abcdefhijklmnopqrstuv with my@email.com Kling account email. Changelog: ========== - June 22, 2026: Initial release. */ import readline from 'node:readline'; import fs from 'fs/promises'; import { writeFile } from 'node:fs/promises'; import { Readable } from 'node:stream'; // Constants const RESULTS_FILE = 'kling_results.txt'; const ERRORS_FILE = 'kling_errors.txt'; const DEFAULT_PROMPTS_FILE = 'prompts.json'; const DEFAULT_MODEL = 'kling-v1-6'; const SLEEP_429 = 10 * 1000; // in milliseconds const MAX_429_RETRIES = 6; // give up a prompt after this many consecutive 429s (all accounts busy) const SLEEP_POLL = 20 * 1000; // in milliseconds const urlAccounts = 'https://api.useapi.net/v1/kling/accounts'; const urlText2Video = 'https://api.useapi.net/v1/kling/videos/text2video'; const urlTask = 'https://api.useapi.net/v1/kling/tasks/'; const urlAssetsDownload = 'https://api.useapi.net/v1/kling/assets/download'; // Utility to sleep for given milliseconds const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); // Function to fetch configured Kling API accounts async function fetchAccounts(apiToken) { const response = await fetch(urlAccounts, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.error(`⛔ Error fetching accounts (HTTP ${response.status}): ${response.statusText}`); process.exit(1); } return response.json(); } // Submit a single text-to-video prompt. Returns { status, taskId }. async function submitVideo(apiToken, email, prompt, index) { const { model_name, prompt: text, aspect_ratio, mode, duration, negative_prompt, cfg_scale } = prompt; const useModel = model_name ?? DEFAULT_MODEL; console.log(`🚀 ${useModel} » Prompt #${index} • ${email} • ${duration ?? 5}s …`); const body = JSON.stringify({ email, model_name: useModel, prompt: text, aspect_ratio, mode, duration, negative_prompt, cfg_scale }); const createResponse = await fetch(urlText2Video, { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiToken}` }, body }); const createBody = await createResponse.text(); if (createResponse.status == 200) { const json = JSON.parse(createBody); const taskId = json?.task?.id; if (taskId) { await fs.appendFile(RESULTS_FILE, `${taskId},#${index}:${text ?? ''}\n`); console.log(`✅ task.id`, taskId); return { status: 200, taskId }; } else { const error = `No task.id found in HTTP 200 response`; console.log(`❓ ${error}`, createBody); await fs.appendFile(ERRORS_FILE, `${error},#${index}:${text ?? ''}\n`); return { status: 500 }; } } else { switch (createResponse.status) { case 429: console.log(`🔄️ Retry on HTTP ${createResponse.status} (all accounts at capacity)`); break; case 400: console.log(`🛑 Validation error`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${text ?? ''}\n`); break; case 500: // Kling returns 500 for content moderation as well as real server faults. console.log(`🛑 Rejected (likely content moderation — check the error text)`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${text ?? ''}\n`); break; default: console.log(`❗ FAILED with HTTP ${createResponse.status}`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${text ?? ''}\n`); } return { status: createResponse.status }; } } // Resolve the clean, non-watermarked master URL for a workId via GET /assets/download. // Returns the cdnUrl, or undefined when unavailable. async function fetchCleanUrl(apiToken, email, workId) { const url = `${urlAssetsDownload}?email=${encodeURIComponent(email)}&workIds=${workId}&fileTypes=MP4`; try { const response = await fetch(url, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (response.ok) { const json = await response.json(); if (json?.cdnUrl) return json.cdnUrl; } else { console.log(`⚠️ assets/download HTTP ${response.status} for workId ${workId}, falling back to watermarked`, await response.text()); } } catch (err) { console.log(`⚠️ assets/download error for workId ${workId}, falling back to watermarked`, err); } return undefined; } // Poll every submitted task until it is final, then download the result. async function download(apiToken, email) { if (! await fileExists(RESULTS_FILE)) return; try { const resultsContent = await fs.readFile(RESULTS_FILE, 'utf8'); const lines = resultsContent.trim().split('\n'); for (const line of lines) { const [taskId, prompt] = line.split(','); const videoFilename = `kling_${taskId}.mp4`; console.log(`👉 ${taskId}`); try { await fs.access(videoFilename); console.log(`⚠️ ${videoFilename} already exists. Skipping download.`); continue; } catch { // File does not exist, proceed with downloading } while (true) { const response = await fetch(`${urlTask}${taskId}?email=${encodeURIComponent(email)}`, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { // 404 = task deleted, failed at moderation, or out of credits. console.log(`🛑 Poll failed ${taskId} (HTTP ${response.status}):\n${prompt}\n`, await response.text()); break; } const task = await response.json(); const { status, status_name, status_final, works, error, message } = task; if (status_final && status_name !== 'succeed') { console.error(`🛑 FAILED ${taskId} (status ${status} ${status_name}${error ? ` — ${error}` : ''}${message ? ` — ${message}` : ''}):\n${prompt}\n`); break; } if (status_final && status_name === 'succeed') { const work = works?.[0]; const watermarkedUrl = work?.resource?.resource; const workId = work?.workId; // Prefer the clean master; fall back to the watermarked resource. const cleanUrl = workId ? await fetchCleanUrl(apiToken, email, workId) : undefined; const url = cleanUrl ?? watermarkedUrl; if (url) { console.log(`✅ Downloading ${cleanUrl ? 'clean master' : 'watermarked'} ${url} to ${videoFilename}`); try { const videoResponse = await fetch(url); if (!videoResponse.ok) { console.error(`⛔ Unable to download ${taskId} (HTTP ${videoResponse.status}):\n${prompt}\n`, url); break; } const stream = Readable.fromWeb(videoResponse.body); await writeFile(videoFilename, stream); } catch (err) { console.error(`⛔ Error during download: ${err}`); } } else console.error(`🛑 Unable to download ${taskId}, no resource URL in succeeded task:\n${prompt}\n`); break; } console.log(`⌛ ${taskId} status (${status_name}) and is still in progress, waiting…`); await sleep(SLEEP_POLL); } } } catch (error) { console.log(`⛔ Error during download:`, error.stack || error); } } // Main function async function main() { const apiToken = process.argv[2]; const email = process.argv[3]; const promptFile = process.argv[4] || DEFAULT_PROMPTS_FILE; if (!apiToken || !email) { console.error('Usage: node kling.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE]'); process.exit(1); } console.info('Script v1.0'); console.info('Node version is: ' + process.version); try { if (await fileExists(RESULTS_FILE)) { let user_input; while (!['y', 'n'].includes(user_input)) { user_input = (await promptUser(`❔ ${RESULTS_FILE} file detected. Do you want to download the results now? (y/n): `))?.toLowerCase(); if (user_input == 'y') { await download(apiToken, email); await fs.unlink(RESULTS_FILE); } } } const start = new Date(); try { console.info('START EXECUTION', start); await execute(apiToken, email, promptFile); } finally { console.info('COMPLETED', new Date()); console.info('EXECUTION ELAPSED', diffInMinutesAndSeconds(start, new Date())); } try { console.info('START DOWNLOAD', start); await download(apiToken, email); } finally { console.info('TOTAL ELAPSED', diffInMinutesAndSeconds(start, new Date())); } } catch (error) { console.error('⛔ Error during execution:', error.stack || error); } } async function execute(apiToken, email, promptFile) { const accounts = await fetchAccounts(apiToken); const accountList = Object.values(accounts); console.info(`Configured Kling API accounts (${accountList.length}):`, accountList.map(a => a.email).join(', ')); if (accountList.length <= 0) { console.error(`⛔ No configured Kling accounts found. Please refer to https://useapi.net/docs/start-here/setup-kling`); process.exit(1); } // Match the account by email. const matched = accountList.find(a => a.email === email); if (!matched) { console.error(`⛔ Account with email ${email} not found. Please refer to https://useapi.net/docs/start-here/setup-kling`); process.exit(1); } const promptData = await fs.readFile(promptFile, 'utf8'); const prompts = JSON.parse(promptData); console.log(`Total number of prompts to process`, prompts.length); let warnings = []; // Parameters accepted by this script for the text2video endpoint. // See https://useapi.net/docs/api-kling-v1/post-kling-videos-text2video for the full parameter set. const supportedParams = ['model_name', 'prompt', 'aspect_ratio', 'mode', 'duration', 'negative_prompt', 'cfg_scale']; const invalidKeys = (prompt) => Object.keys(prompt).filter(key => !key.startsWith('__') && !supportedParams.includes(key)) for (let i = 1; i <= prompts.length; i++) { const prompt = prompts[i - 1]; const { prompt: text } = prompt; const notSupported = invalidKeys(prompt); if (notSupported.length) warnings.push(`⚠️ Following params not supported: ${notSupported.join(',')}. Prompt ${i}`); if (!text) warnings.push(`⚠️ Please specify a prompt. Prompt ${i}`); if (text && text.length > 2500) warnings.push(`⚠️ prompt exceeds 2500 characters. Prompt ${i}`); } if (warnings.length > 0) { warnings.forEach(warning => console.warn(warning)); console.error(`⛔ Execution stopped due to warnings.`); process.exit(1); } for (let i = 0; i < prompts.length; i++) { const prompt = prompts[i]; let retries429 = 0; while (true) { const { status } = await submitVideo(apiToken, email, prompt, i + 1); if (status == 429) { if (++retries429 > MAX_429_RETRIES) { console.error(`⛔ Gave up on prompt #${i + 1} after ${MAX_429_RETRIES} retries — all accounts still busy.`); await fs.appendFile(ERRORS_FILE, `429 (gave up after ${MAX_429_RETRIES} retries),#${i + 1}\n`); break; } await sleep(SLEEP_429); } else break; } } } // Utility function to check if a file exists async function fileExists(path) { try { await fs.access(path); return true; } catch { return false; } } // Function to prompt user input async function promptUser(query) { const rl = readline.createInterface({ input: process.stdin, output: process.stdout }); return new Promise((resolve) => rl.question(query, answer => { rl.close(); resolve(answer); })); } function diffInMinutesAndSeconds(date1, date2) { const diffInSeconds = Math.floor((date2 - date1) / 1000); return `${Math.floor(diffInSeconds / 60)} minutes ${diffInSeconds % 60} seconds`; }; main(); ``` </details> ### Examples The clip below is a real Kling generation produced through this Kling API, straight from our blog walkthrough. ###### Kling v3 Turbo — `kling-v3-0-turbo`, image-to-video, 1080p 10s with spoken dialogue and scene cuts <video poster="https://media.useapi.net/blog/2026-06-17-260617/kling-v3-turbo-poster.jpg" src="https://media.useapi.net/blog/2026-06-17-260617/kling-v3-turbo.mp4" style="width: 100%; max-width: 420px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> — from [Kling 3.0 Turbo: faster video with dialogue and scene changes](/blog/260617) Related tutorials: [Kling 4.0 video](/docs/articles/kling-4-api), [multi-reference and multi-shot video with Kling Omni](/docs/articles/kling-omni-bash) and [Kling lip-sync avatars and motion control](/docs/articles/kling-features-bash). ### Frequently asked questions **Is there a Kling API?** Through useapi.net, yes: the Kling API runs every Kling model on your [Kling AI website subscription](https://kling.ai/app/membership/membership-plan) through a standard REST endpoint, Kling 4.0 included, which Kling's own developer API doesn't offer yet (as of October 18, 2026). Connect your Kling account once with [Setup Kling](/docs/start-here/setup-kling) and call it with a useapi.net token. **How do I access Kling v3 (and v3 Turbo) through the API?** Through useapi.net, pass `"model_name": "kling-v3-0"`, or `"kling-v3-0-turbo"` for the faster variant, to [POST /videos/text2video](/docs/api-kling-v1/post-kling-videos-text2video) or [POST /videos/image2video-frames](/docs/api-kling-v1/post-kling-videos-image2video-frames). Kling v3 runs 3–15s with `std`, `pro` and `4k` modes and audio on by default, and Turbo keeps v3 quality with shorter generation times and no `4k`. See [Supported models](#supported-models) above. **Can I turn an image into a video (image-to-video)?** Through useapi.net, yes: upload the still with [POST /assets](/docs/api-kling-v1/post-kling-assets), then pass the returned URL as `image` (start frame) and optionally `image_tail` (end frame) to [POST /videos/image2video-frames](/docs/api-kling-v1/post-kling-videos-image2video-frames). On Kling v3 the aspect ratio comes from the image, and v3 Turbo takes the start frame only. See [Image-to-video](#image-to-video) above. **How much does the Kling API cost?** Through useapi.net, on Kling Pro ($32.56/month for 3,000 credits), Kling 3.0 at 1080p with audio costs about $0.13 a second, against about $0.17 on Kling's [developer API](https://kling.ai/dev/pricing), which sells video packs from $700 (as of October 2026). Kling 4.0 runs about $0.10 a second at 720p and $0.15 at 1080p on the same plan. The [Kling API overview](/docs/api-kling-v1) has a live cost calculator for every model. **Why is my video watermarked?** Through useapi.net, the MP4 at `works[0].resource.resource` is Kling's watermarked preview. For the clean master, take the `workId` from the task's `works` array and call [GET /assets/download](/docs/api-kling-v1/get-kling-assets-download), which returns a `cdnUrl` to the file without the watermark. This needs a paid Kling AI website subscription. See [Generate a video in two API calls](#generate-a-video-in-two-api-calls) above. **How is this different from the official Kling API?** Through useapi.net, one API token covers your Kling accounts and [10+ other AI services](/), with no Kling developer account to open, and the same token also runs Kling's lip-sync, avatar video, effects and virtual try-on endpoints. Kuaishou's [official Kling API](https://kling.ai/dev/pricing) needs a separate developer account instead and bills every generation at developer rates. **My generation returns a 500 — what does that mean?** Through useapi.net, a `500` from Kling usually means a content-moderation rejection rather than a server fault, because Kling reuses that code for both and its `message` field rarely tells them apart. Read the `error` text instead: a rejection reads like "The content you uploaded appears to violate the community guidelines." A later `404` on the poll means the task was deleted, failed at moderation, or the account ran out of credits. ### Conclusion Visit our <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> or <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> for any support questions and concerns. The full runnable example is in the [`kling-api` GitHub repo](https://github.com/useapi/kling-api). The same calls are available as tools on the hosted [Kling MCP server](/docs/api-kling-v1/mcp) for Claude Code, Cursor and VS Code. #### Cross posted Also published on [dev.to](https://dev.to/useapi/how-to-generate-ai-video-with-kling-v3-via-the-kling-api-5d4j){:rel="nofollow"}. === URL: https://useapi.net/docs/articles/kling-features-bash === Document URL: https://useapi.net/docs/articles/kling-features-bash --- layout: default title: Kling Lip-Sync Avatars, Motion Control & Image Generation via the Kling API description: "Drive Kling's premium features from code via a third-party REST API — lip-sync talking avatars, motion control, and KOLORS image generation, with copy-paste curl." keywords: [Kling lip sync API, Kling avatars API, Kling motion control API, Kling image generation, Kolors API, Kling TTS, talking avatar API, virtual try-on API] parent: Articles nav_exclude: true date: 2026-06-22 last_modified: 2026-10-20 nav_order: 870 repo: https://github.com/useapi/kling-api --- ## Kling Lip-Sync Avatars, Motion Control & Image Generation via the Kling API 7 min read • June 22, 2026 (October 20, 2026) ## Table of contents ### Introduction Kling AI is not just a text-to-video model. The same [Kling AI website subscription](https://kling.ai/app/membership/membership-plan) also makes talking lip-sync avatars, moves the motion of a video onto a still image and generates KOLORS images, and every one of them is reachable from code. [Kling AI](https://app.klingai.com) is the media service of the Chinese short-video company [Kuaishou Technology](https://www.kuaishou.com/en), and the third-party useapi.net [Kling API](/docs/api-kling-v1) runs it over a standard REST endpoint. This guide covers the premium features beyond plain text/image-to-video — for the core video workflow and the model lineup, see [How to Generate AI Video with Kling v3](/docs/articles/kling-bash). Three things hold across every feature below. You need a useapi.net [API token](/docs/start-here/setup-useapi) and a connected [Kling account](/docs/start-here/setup-kling) — export the token so the `curl` examples run as-is: ```bash export USEAPI_TOKEN="user:1234-..." ``` The `email` field is optional: without it, the API picks one of your Kling accounts that has a free job slot (`429` when every account is busy). With more than one account, note which account ran the job ([GET tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) explains how to find it), because polling the task needs that account's `email`. And most of these endpoints are asynchronous and task-based: the create call returns a numeric `task.id`, then you poll `GET /v1/kling/tasks/{task_id}` until `status_final` is `true` (success is `status_name: "succeed"`, `status: 99`), with the output in the `works[]` array. The exceptions are noted where they occur — text-to-speech returns synchronously, and avatar creation returns an id directly. ### Pricing These features use the credits of your Kling AI website subscription at Kling's own rates, and useapi.net adds no per-video charge. Kuaishou's [official Kling API](https://kling.ai/dev/pricing) is billed separately, on a developer account with prepaid packs. The [Kling API overview](/docs/api-kling-v1) has a live cost calculator for each Kling plan. ### Lip-sync & avatars A Kling avatar is a digital character built from a single image that can be animated to speak — either from a pre-recorded audio file or from text you supply, voiced by Kling's text-to-speech. The flow has up to three pieces. #### 1. (Optional) Save an avatar `POST https://api.useapi.net/v1/kling/avatars` turns an image into a reusable avatar. Upload the image first with [POST /assets](/docs/api-kling-v1/post-kling-assets), then pass the returned URL as `imageUrl`. Most fields (`nickname`, `prompt`, `scene`, and the TTS voice settings) are auto-filled by AI from the image if you omit them: ```bash curl -X POST "https://api.useapi.net/v1/kling/avatars" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "imageUrl": "https://s21-kling.klingai.com/ai-platform/.../portrait.jpg" }' ``` This call returns synchronously with the new avatar's id, not a task to poll: ```json { "id": "300137233318846", "status": "SUCCESS" } ``` You can skip this step and pass a direct `imageUrl` to the video call instead — saving an avatar is only worth it if you want to reuse the same character and its voice defaults. List your saved avatars (or browse system templates) with [GET /avatars](/docs/api-kling-v1/get-kling-avatars). #### 2. Generate the talking video `POST https://api.useapi.net/v1/kling/avatars/video`. Provide one avatar source (`avatarId` *or* `imageUrl`) and one audio source (`audioUrl` *or* `text`). When you pass `text`, a `speakerId` is required — list the available voices, their emotions, and sample clips with [GET /tts/voices](/docs/api-kling-v1/get-kling-tts-voices): ```bash curl -X POST "https://api.useapi.net/v1/kling/avatars/video" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "avatarId": "300137233318846", "text": "Hello there! Welcome to our product demo.", "speakerId": "moss_audio_ad5baf92-735f-11f0-8263-fe5a2fe98ec8", "mode": "std" }' ``` This is asynchronous — it returns a `task.id`. Poll it: ```bash curl "https://api.useapi.net/v1/kling/tasks/123456789?email=user@example.com" \ -H "Authorization: Bearer $USEAPI_TOKEN" ``` When `status_final` is `true` and `status_name` is `"succeed"`, the MP4 is in the `works[]` array. To pull the clean, non-watermarked master, take the `workId` from `works[]` and call [GET /assets/download](/docs/api-kling-v1/get-kling-assets-download) with `fileTypes=MP4`. `text` accepts up to 5000 characters, and `mode` is `std` (default) or `pro`. The `speed` (0.8–2.0) and `emotion` (`neutral`, `happy`, `angry`, `sad`, `fearful`, `disgusted`, `surprised`) options apply when you supply text — not every emotion is available for every voice, so check the voice's `emotions` list from [GET /tts/voices](/docs/api-kling-v1/get-kling-tts-voices). Two related endpoints round this out. [POST /tts/create](/docs/api-kling-v1/post-kling-tts-create) generates up to 5 minutes of speech from text and returns the MP3 URL synchronously in the `resource` field (`status: 99`) — no polling — and it is free and unlimited on every Kling plan. And if you already have a finished video with a clear frontal face, [POST /videos/lipsync](/docs/api-kling-v1/post-kling-videos-lipsync) re-syncs its lips to a new `audio` track (both `video` and `audio` are URLs, the video must be 60 seconds or less). For longer clips or looser face-visibility requirements, the [lip-sync page](/docs/api-kling-v1/post-kling-videos-lipsync) suggests [PixVerse Lip Sync](/docs/api-pixverse-v2/post-pixverse-videos-lipsync) instead. ### Motion control Motion control transfers the motion from a reference video onto a static image, so the person in your image performs the action from the video. Use `POST https://api.useapi.net/v1/kling/videos/motion-create` with an `imageUrl` (a person with a clearly visible pose) and a `motionUrl` (a 3–30 second reference video). Both must be uploaded via [POST /assets](/docs/api-kling-v1/post-kling-assets) first — use the `url` field from the response for `imageUrl` and the `resourceUrl` field for `motionUrl`. You can also pull an official Kling motion or one you previously uploaded with [GET /videos/motions](/docs/api-kling-v1/get-kling-videos-motions): ```bash curl -X POST "https://api.useapi.net/v1/kling/videos/motion-create" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model_name": "kling-v3-0", "imageUrl": "https://s15-kling.klingai.com/.../person.jpg", "motionUrl": "https://v15-kling.klingai.com/.../dance.mp4", "prompt": "Person dancing energetically", "keepAudio": true, "mode": "std" }' ``` `model_name` is `kling-v3-0` (default, upgraded motion capture with high facial consistency) or `kling-v2-6`. The output duration is detected automatically from the motion video. Set `keepAudio: true` to keep the reference video's sound, and `motionDirection` to `motion_direction` (default — follow the video's motion) or `image_direction` (follow the pose from your source image). On `kling-v3-0` you can attach a saved [element](/docs/api-kling-v1/post-kling-elements) via `element_1` for stronger character consistency. The endpoint validates the image up front and returns a `400` with `MOTION.PIC_NOT_MATCHED` if it can't detect a person. The create call is asynchronous — it returns a `task.id` (`type: "m2v_motion_control"`). Poll it the same way as the avatar video above, then download the clean master via [GET /assets/download](/docs/api-kling-v1/get-kling-assets-download): ```bash curl "https://api.useapi.net/v1/kling/tasks/299640525521807?email=user@example.com" \ -H "Authorization: Bearer $USEAPI_TOKEN" ``` ### Image generation (Kolors) KOLORS is Kling's image model, exposed at `POST https://api.useapi.net/v1/kling/images/kolors`. A `prompt` is required (up to 2500 characters). The default `version` is `kling-v3-0`, which supports up to ten reference images — upload each with [POST /assets](/docs/api-kling-v1/post-kling-assets), pass the URLs as `image_1` through `image_10`, and cite them inside the prompt with `@image_1`, `@image_2`, and so on: ```bash curl -X POST "https://api.useapi.net/v1/kling/images/kolors" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A woman @image_1 dancing elegantly in a sunlit ballroom", "version": "kling-v3-0", "resolution": "2k", "aspect_ratio": "3:4", "imageCount": 2, "image_1": "https://s21-kling.klingai.com/ai-platform/.../woman.jpg" }' ``` Like the video features, KOLORS is asynchronous: the create call returns a `task.id`, and you poll `GET /v1/kling/tasks/{task_id}` until it succeeds — the generated images land in the `works[]` array. ```bash curl "https://api.useapi.net/v1/kling/tasks/123456789?email=user@example.com" \ -H "Authorization: Bearer $USEAPI_TOKEN" ``` `resolution` is `1k` or `2k` (default), and `aspect_ratio` defaults to `16:9` (v3 also accepts `auto` when reference images are present). For the older `kling-v2-1` version, drop the `@image_N` references and instead use a single `reference` of `face`, `subject`, or `restyle` together with an `imageReference` URL — useful for face-similarity, subject-similarity, or style-transfer workflows. Full parameter details are on [POST /images/kolors](/docs/api-kling-v1/post-kling-images-kolors). Two image features build on the same account. [POST /images/kolors-elements](/docs/api-kling-v1/post-kling-images-kolors-elements) composes up to four subject images (plus optional scene and style references) into one scene. [POST /images/virtual-try-on](/docs/api-kling-v1/post-kling-images-virtual-try-on) dresses a `humanImage` in a garment (`dressInput`, or `upperInput`/`lowerInput`). And [POST /images/upscale](/docs/api-kling-v1/post-kling-images-upscale) takes a `task_id` + `workId` from a completed KOLORS task and returns a higher-resolution version. All three are async and resolve through the same task poll. ### More The same one account and token cover the rest of Kling's lineup — each is its own endpoint, documented and Try-It-runnable: - [POST /videos/image2video-effects](/docs/api-kling-v1/post-kling-videos-image2video-effects) applies a named special effect to an image (list effects with [GET /videos/effects](/docs/api-kling-v1/get-kling-videos-effects)). - [POST /videos/extend](/docs/api-kling-v1/post-kling-videos-extend) continues an existing clip past its original length. - [POST /videos/image2video-elements](/docs/api-kling-v1/post-kling-videos-image2video-elements) and the multi-shot [POST /videos/omni](/docs/api-kling-v1/post-kling-videos-omni) make video from reusable character and object references. - [POST /images/recognize-faces](/docs/api-kling-v1/post-kling-images-recognize-faces) finds the faces in an image (for KOLORS `faceNo`). For the full endpoint list and a live credit-cost calculator, see the [Kling API overview](/docs/api-kling-v1). ### Runnable scripts The [`kling-api` GitHub repo](https://github.com/useapi/kling-api) ships ready-to-run Node.js batch scripts for the features in this guide — each reads prompts from `prompts.json`, submits them, polls, and downloads every result: - [`lip-sync/`](https://github.com/useapi/kling-api/tree/main/lip-sync) — talking avatars (`POST /avatars/video`) - [`motion-control/`](https://github.com/useapi/kling-api/tree/main/motion-control) — motion transfer (`POST /videos/motion-create`) - [`image-generation/`](https://github.com/useapi/kling-api/tree/main/image-generation) — KOLORS images (`POST /images/kolors`) Run any of them with `node <script>.mjs <API_TOKEN> <EMAIL>`. ### Examples The samples below are real Kling generations produced through this Kling API, straight from our blog walkthroughs. ###### Lip-sync avatar — `POST /avatars/video`, talking avatar from an image + TTS text <video poster="https://media.useapi.net/blog/2026-01-12-260112/avatar-results-poster.jpg" src="https://media.useapi.net/blog/2026-01-12-260112/avatar-results.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> — from [Kling: Elements and Avatars 2.0](/blog/260112) Also on YouTube: [Kling Avatar 2.0](https://youtube.com/shorts/nKw61pdzFmw). ###### Motion control — `POST /videos/motion-create`, `kling-v3-0`, 720p 15s motion transfer onto a still image <video poster="https://media.useapi.net/blog/2026-03-06-260306/kling-motion-3-720p-15sec-poster.jpg" src="https://media.useapi.net/blog/2026-03-06-260306/kling-motion-3-720p-15sec.mp4" style="width: 100%; max-width: 400px;" controls type="video/mp4" preload="metadata"></video> — from [Kling: Motion Control 3.0 with Character Consistency](/blog/260306) Also on YouTube: [Smooth Criminal • Kling Motion 3.0](https://youtube.com/shorts/VztjBYqqQ1A). ###### KOLORS image — `POST /images/kolors`, `kling-v3-0` text-to-image <img src="https://media.useapi.net/blog/2026-03-09-260309i/kling-kolors-v3.0-via-kling-api-by-useapi.net.png" style="width: 100%;" /> — from [AI Image Models: 17 Compared](/blog/260309i) ### Frequently asked questions **Can I create a talking avatar (lip-sync) through the Kling API?** Through useapi.net, yes: optionally save an avatar from an image with [POST /avatars](/docs/api-kling-v1/post-kling-avatars), then call [POST /avatars/video](/docs/api-kling-v1/post-kling-avatars-video) with an avatar source (`avatarId` or `imageUrl`) and an audio source (`audioUrl`, or `text` with a `speakerId`). It returns a `task.id` you poll for the finished MP4. See [Lip-sync & avatars](#lip-sync--avatars) above. **Is Kling text-to-speech free?** Through useapi.net, yes: [POST /tts/create](/docs/api-kling-v1/post-kling-tts-create) turns text into up to 5 minutes of speech at no credit cost on every Kling AI website subscription, including the free plan. It returns the MP3 URL right away, with no polling. List the voices and their emotions with [GET /tts/voices](/docs/api-kling-v1/get-kling-tts-voices). **How does Kling motion control work?** Through useapi.net, [POST /videos/motion-create](/docs/api-kling-v1/post-kling-videos-motion-create) moves the motion of a reference video (`motionUrl`) onto a person in a still image (`imageUrl`). It uses `kling-v3-0` by default for high facial consistency, runs as a task you poll, and takes `keepAudio`, `motionDirection` and an `element_1` for a steadier character. See [Motion control](#motion-control) above. **What image models does the Kling API expose?** Through useapi.net, KOLORS, via [POST /images/kolors](/docs/api-kling-v1/post-kling-images-kolors). The default `kling-v3-0` makes images from text with up to ten `@image_N` references, and `kling-v2-1` adds face, subject and restyle reference modes. Virtual try-on, multi-element scenes and upscaling are separate endpoints on the same account. See [Image generation (Kolors)](#image-generation-kolors) above. **Why is my generation watermarked?** Through useapi.net, the MP4 in the poll's `works[]` array is Kling's watermarked preview. For the clean master, take the `workId` from the task and call [GET /assets/download](/docs/api-kling-v1/get-kling-assets-download) with `fileTypes=MP4`, which returns a `cdnUrl` to the file without the watermark. This needs a paid Kling AI website subscription. **How much do these features cost?** Through useapi.net, these features use the credits of your [Kling AI website subscription](https://kling.ai/app/membership/membership-plan) at Kling's own rates, about $0.011 a credit on Kling Pro ($32.56/month for 3,000 credits), with no per-video charge from us. Kling's own [developer API](https://kling.ai/dev/pricing) sells prepaid video packs from $700 instead (as of October 2026). The [Kling API overview](/docs/api-kling-v1) has a live cost calculator. **My request returns a 500 or the poll returns a 404 — what does that mean?** Through useapi.net, a `500` from Kling usually means a content-moderation rejection rather than a server fault. Read the `error` text, not the generic `message`: a rejection reads like "The content you uploaded appears to violate the community guidelines." On a poll, a `404` means the task was deleted, failed at moderation, or the account ran out of credits. Check the balance with [GET /accounts/`email`](/docs/api-kling-v1/get-kling-accounts-email). ### Conclusion Visit our <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> or <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> for any support questions and concerns. The full runnable example is in the [`kling-api` GitHub repo](https://github.com/useapi/kling-api). === URL: https://useapi.net/docs/articles/kling-image-4-api-es === Document URL: https://useapi.net/docs/articles/kling-image-4-api-es --- layout: default title: Cómo generar imágenes con Kling Image 4.0 mediante la API de Kling seo_title: "API de Kling Image 4.0: imágenes 8K, Series Mode y diseños web" description: "Genera imágenes con Kling Image 4.0 desde código con tu suscripción de Kling AI: fotos 8K, Series Mode, presets, páginas de producto y diseños web, con costos reales." keywords: [API de Kling Image 4.0, Kling Image 4.0 API, Kling Image 4 API, API de imágenes Kling 4.0, imágenes 8K con Kling, Kling 8K image, Kling Series Mode, modo serie de Kling, página de detalle de producto con Kling, diseño web con Kling, presets de imagen de Kling, Kling Omni image, API de Kling, Kling API, Kling AI API, API de imágenes con IA, Kuaishou, servidor MCP de Kling, curl, tutorial] image: https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-8k-hummingbird.jpg parent: Articles nav_exclude: true lang: es translation_key: kling-image-4-api date: 2026-11-19 last_modified: 2026-11-19 nav_order: 856 repo: https://github.com/useapi/kling-api --- ## Cómo generar imágenes con Kling Image 4.0 mediante la API de Kling {: .no_toc #how-to-generate-kling-image-40-images-via-the-kling-api } 6 min de lectura • 19 de noviembre de 2026 ## Índice {: .no_toc .text-delta #table-of-contents } ### Introducción Kling Image 4.0 es el nuevo modelo de imágenes de Kuaishou, y la API de Kling de useapi.net lo ejecuta con tu [suscripción del sitio web de Kling AI](https://kling.ai/app/membership/membership-plan): envía `"omni_version": "v4"` a [POST images/omni](/docs/api-kling-v1/post-kling-images-omni). Un solo endpoint cubre todo lo que la app de Kling hace con este modelo. Hace fotos de hasta 8K e historias en Series Mode de 2 a 10 imágenes coherentes entre sí. Acepta presets de estilo, tono y fuente nombrados en el prompt. Y tiene dos habilidades de diseño que generan cada una una sola imagen larga: una página de detalle de producto a partir de una foto del producto y el diseño de una página web. Esta guía reúne ejecuciones reales en una suscripción Kling Pro, una por función, con las solicitudes exactas, las imágenes que generaron y lo que costó cada una. Una imagen 2K usó 4 créditos, unos US$0,04 en Pro, mientras que la API para desarrolladores de Kling vende la misma imagen a US$0,06 en paquetes prepagados de imágenes desde US$300. ### Antes de empezar Necesitas un [token de API](/docs/start-here/setup-useapi) de useapi.net y una cuenta de Kling conectada con [Setup Kling](/docs/start-here/setup-kling), con un plan de pago de Kling (Standard o superior). El 4K y el 8K también requieren un plan de pago. Exporta el token para que los ejemplos de `curl` funcionen tal como están: ```bash export USEAPI_TOKEN="user:1234-..." # your useapi.net API token export KLING_EMAIL="you@example.com" # your connected Kling account ``` ### Kling Image 4.0 de un vistazo | Modo | Solicitud | Qué obtienes | Créditos | |---|---|---|---| | Imagen | `omni_version: v4` | de 1 a 9 imágenes en 2K, 4K u 8K, en cualquiera de 9 relaciones de aspecto o `auto` | 4 / 6 / 10 por imagen | | Series Mode | `story_mode: true` | de 2 a 10 imágenes que cuentan una sola historia, o tantas como Kling decida | lo mismo, por imagen | | Presets | `@style:`, `@tone:`, `@font:` en el prompt | un estilo visual, una gradación de color o una tipografía de las listas de Kling | sin costo extra | | Página de detalle de producto | `skill: product_detail` + `image_1` | una página larga a partir de la foto de tu producto, corta, media o larga | de 15 a 55 por página | | Diseño web | `skill: web_design` | un diseño largo de landing page | 35 en 1K, 38 en 2K | Hasta 10 imágenes de referencia y [elementos](/docs/api-kling-v1/get-kling-elements) guardados funcionan como en cualquier solicitud Omni: nómbralos en el prompt como `@image_1` o `@element_1`. ### Genera una imagen 8K con dos llamadas #### 1. Envía la tarea ```bash curl -s -X POST "https://api.useapi.net/v1/kling/images/omni" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$KLING_EMAIL"'", "omni_version": "v4", "resolution": "8k", "aspect_ratio": "16:9", "prompt": "Macro photograph of a hummingbird hovering at a red trumpet flower at sunrise, every iridescent feather sharp, dew drops on the petals, soft golden backlight, shallow depth of field" }' ``` La respuesta es la nueva tarea, con su id en `task.id`: ```json { "task": { "id": 123456789012345, "type": "mmu_omni_image", "status": 5, "status_name": "submitted", "status_final": false } } ``` #### 2. Consulta el resultado Lee la tarea con [GET tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) hasta que `status_final` sea `true`. Cada imagen es un elemento de `works`, con su URL y su tamaño: ```bash curl -s "https://api.useapi.net/v1/kling/tasks/123456789012345?email=$KLING_EMAIL" \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{status_name, works: [.works[] | {url: .resource.resource, width: .resource.width, height: .resource.height}]}' ``` ```json { "status_name": "succeed", "works": [ { "url": "https://s15-kling.klingai.com/kimg/.../image.png", "width": 10880, "height": 6144 } ] } ``` Nuestra ejecución generó una imagen de 10880 x 6144, 67 megapíxeles, y usó 6 créditos. El precio de lista del 8K es de 10 créditos, y ese día Kling lo cobró a 6 por una promoción. La misma solicitud con `"resolution": "2k"` genera una imagen de 2720 x 1536 por 4 créditos, y con `"4k"`, una de 5440 x 3072 por 6. <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-8k-hummingbird.jpg" alt="Kling Image 4.0 en 8K: un colibrí junto a una flor roja de trompeta al amanecer" loading="lazy" style="width:100%"> Kling Image 4.0, `8k`, `16:9`, 10880 x 6144, 6 créditos. Aquí se muestra más pequeña: abre el [original](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-8k-hummingbird-original.png) (PNG de 10880 x 6144, 3,5 MB) para verla en 8K completo. A tamaño completo, el detalle en 8K se mantiene. Este es un recorte de 1600 x 900 del mismo archivo, sin escalar: <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-8k-hummingbird-crop-100.jpg" alt="Un recorte al 100% de la imagen 8K: el ojo y las plumas del colibrí" loading="lazy" style="width:100%"> La misma imagen al 100%, la cabeza del ave. ### Series Mode: una historia a partir de un solo prompt `story_mode: true` genera una serie de imágenes coherentes: los mismos personajes, el mismo estilo y la misma luz de un cuadro a otro. Kling Image 4.0 hace la serie solo con el prompt, sin imagen de referencia. Pon `imageCount` entre 2 y 10, u omítelo y Kling decide cuántas imágenes necesita la historia. ```bash curl -s -X POST "https://api.useapi.net/v1/kling/images/omni" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$KLING_EMAIL"'", "omni_version": "v4", "story_mode": true, "aspect_ratio": "4:3", "prompt": "A picture-book story in consistent watercolor style: a small paper boat is folded by a child on a rainy city street, floats down the gutter, slips into a river past old bridges, and finally reaches the open sea at sunset" }' ``` Kling eligió 6 imágenes para esta historia, de 2336 x 1760 cada una, y cobró 4 créditos por cada una, 24 en total. <div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(220px,1fr));gap:8px"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-1.jpg" alt="Series Mode 1 de 6: un niño dobla un barco de papel en una calle lluviosa" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-2.jpg" alt="Series Mode 2 de 6: el barco flota por la cuneta" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-3.jpg" alt="Series Mode 3 de 6: el barco en un canal de la ciudad" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-4.jpg" alt="Series Mode 4 de 6: el barco pasa bajo un puente antiguo" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-5.jpg" alt="Series Mode 5 de 6: el barco en un río ancho" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-6.jpg" alt="Series Mode 6 de 6: el barco llega al mar al atardecer" loading="lazy" style="width:100%"> </div> Kling Image 4.0 en Series Mode, `story_mode: true`, sin `imageCount`, 6 imágenes, 24 créditos. Originales, PNG de 2336 x 1760: [1](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-1-original.png), [2](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-2-original.png), [3](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-3-original.png), [4](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-4-original.png), [5](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-5-original.png), [6](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-6-original.png). ### Estilos, tonos y fuentes Kling Image 4.0 tiene tres tipos de presets, y los nombras en el prompt. [GET images/presets](/docs/api-kling-v1/get-kling-images-presets) los lista con sus ids y una imagen de muestra: 98 estilos, 16 tonos y 76 fuentes en inglés, japonés, coreano y chino. ```bash curl -s "https://api.useapi.net/v1/kling/images/presets" -H "Authorization: Bearer $USEAPI_TOKEN" \ | jq '{styles: [.styles[0:3][] | .id], tones: [.tones[] | .id], fonts: [.fonts[] | select(.languages | index("en")) | .id][0:5]}' ``` - Un tono (`@tone:<id>`) aplica una de las gradaciones de color e iluminación de Kling: estilos de directores, looks de cámara y paletas. - Una fuente (`@font:<id>`) define la tipografía del texto entre comillas que va después. - Un estilo (`@style:<id>`) define el aspecto general: estilos 3D, 2D, de manualidades con materiales o fotográficos. Esta es la misma escena sin tono y con `@tone:Nostalgic_Wuxia`, 4 créditos cada una: <div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(280px,1fr));gap:8px"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-tone-none-swordsman.jpg" alt="Sin tono: un espadachín en un bosque de bambú al amanecer" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-tone-nostalgic-wuxia-swordsman.jpg" alt="@tone:Nostalgic_Wuxia: la misma escena con una gradación cálida y desvaída de cine wuxia" loading="lazy" style="width:100%"> </div> Izquierda: `A lone swordsman in a bamboo forest at dawn, mist between the stalks, wide cinematic shot`. Derecha: el mismo prompt después de `@tone:Nostalgic_Wuxia`. Originales, PNG de 2720 x 1536: [sin tono](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-tone-none-swordsman-original.png), [Nostalgic Wuxia](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-tone-nostalgic-wuxia-swordsman-original.png). Y un letrero de tienda sin fuente y con `@font:elegant_brush_hand`. Pon entre comillas las palabras que quieres en la imagen, y la fuente justo antes de ellas: ```json { "prompt": "A cozy corner coffee shop at night, warm light spilling onto a wet cobblestone street, a hand-painted shop sign above the door that reads @font:elegant_brush_hand \"Moonlight Roasters\"" } ``` <div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(280px,1fr));gap:8px"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-font-none-coffee-sign.jpg" alt="Sin fuente: el letrero con una tipografía serif sencilla" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-font-elegant-brush-hand-coffee-sign.jpg" alt="@font:elegant_brush_hand: el letrero con letra de pincel" loading="lazy" style="width:100%"> </div> Izquierda: sin fuente. Derecha: `@font:elegant_brush_hand "Moonlight Roasters"`. Originales, PNG de 2496 x 1664: [sin fuente](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-font-none-coffee-sign-original.png), [fuente de pincel](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-font-elegant-brush-hand-coffee-sign-original.png). <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-style-3d-cartoon-corgi-astronaut.jpg" alt="@style:3d_cartoon_with_exaggerated_perspective_pro: un corgi astronauta en un planeta de colores de caramelo" loading="lazy" style="width:60%"> `@style:3d_cartoon_with_exaggerated_perspective_pro A corgi astronaut stepping out of a tiny rocket onto a candy-colored planet, looking up at the camera`, `1:1`, 4 créditos. [original](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-style-3d-cartoon-corgi-astronaut-original.png)(PNG de 2048 x 2048, 8,5 MB). Un id desconocido recibe un `400` antes de que nada llegue a Kling, así que un error de escritura nunca cuesta créditos. ### Imágenes de referencia Nombra una referencia en el prompt como `@image_1`. Primero hicimos una foto de producto y luego usamos su URL como `image_1` para una foto publicitaria en 4K. El producto, su etiqueta y su tapa de bambú se mantienen: ```json { "omni_version": "v4", "resolution": "4k", "aspect_ratio": "16:9", "prompt": "The bottle from @image_1 standing on a mossy rock beside a mountain stream, morning mist, outdoor adventure ad", "image_1": "https://s15-kling.klingai.com/kimg/.../bottle.png" } ``` <div style="display:grid;grid-template-columns:1fr 2fr;gap:8px;align-items:start"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-product-photo-bottle.jpg" alt="La foto de producto: una botella de acero verde salvia con tapa de bambú" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-4k-reference-bottle-stream.jpg" alt="4K con la foto de producto como referencia: la botella junto a un arroyo de montaña" loading="lazy" style="width:100%"> </div> Izquierda: la foto de producto, `3:4`, 4 créditos. Derecha: `4k` con ella como `@image_1`, 5440 x 3072, 6 créditos. Originales: [foto de producto](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-product-photo-bottle-original.png) (PNG de 1760 x 2336, 4,8 MB), [foto publicitaria en 4K](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-4k-reference-bottle-stream-original.png) (PNG de 5440 x 3072, 24 MB). Para subir tu propia foto, usa [POST assets](/docs/api-kling-v1/post-kling-assets) y pasa la URL que devuelve. ### Páginas de detalle de producto `skill: product_detail` convierte una foto de producto en una página de producto larga: una imagen principal, los puntos destacados, primeros planos y una tabla de especificaciones, todo en una sola imagen. `image_1` es la foto, `prompt` dice qué hace el producto y `length` define el número de secciones: `short` (de 2 a 5), `medium` (de 6 a 10) o `long` (de 11 a 18). ```bash curl -s -X POST "https://api.useapi.net/v1/kling/images/omni" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$KLING_EMAIL"'", "omni_version": "v4", "skill": "product_detail", "length": "short", "resolution": "2k", "image_1": "https://s15-kling.klingai.com/kimg/.../bottle.png", "prompt": "Insulated steel water bottle \"Trailhead\": keeps drinks cold 24 hours and hot 12, leak-proof bamboo lid, fits car cup holders, 750 ml, three colors" }' ``` La página llegó como una sola imagen de 2048 x 13408 por 18 créditos. Una página `medium` en 1K salió de 1024 x 9936 por 30 créditos. <div style="max-height:900px;overflow-y:auto;border:1px solid #ddd"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-product-detail-page-2k-short.jpg" alt="Página de detalle de producto de Kling Image 4.0: la botella Trailhead verde salvia, puntos destacados y especificaciones" loading="lazy" style="width:100%"> </div> `skill: product_detail`, `length: short`, `2k`, 2048 x 13408, 18 créditos. Desplázate dentro del marco para ver la página completa, o abre el [original](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-product-detail-page-2k-short-original.png) (PNG, 1,3 MB). ### Diseños de páginas web `skill: web_design` genera el diseño de una landing page como una sola imagen larga. `image_1` es opcional: una imagen cuyo estilo debe seguir la página. Kling escribe el texto de la página en chino si el prompt no indica el idioma, así que termina el prompt con el idioma que quieres: ```bash curl -s -X POST "https://api.useapi.net/v1/kling/images/omni" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$KLING_EMAIL"'", "omni_version": "v4", "skill": "web_design", "resolution": "1k", "prompt": "Landing page for \"Ember & Oak\", a small-batch coffee roaster: warm browns and cream, elegant serif headlines, hero photo of a pour-over, three featured roasts, a monthly subscription offer and customer reviews. All text on the page in English." }' ``` <div style="max-height:900px;overflow-y:auto;border:1px solid #ddd"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-web-design-1k-english.jpg" alt="Diseño web de Kling Image 4.0: landing page en inglés del tostador de café Ember & Oak" loading="lazy" style="width:100%"> </div> `skill: web_design`, `1k`, 1024 x 5376, 35 créditos. Desplázate dentro del marco para ver la página completa, o abre el [original](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-web-design-1k-english-original.png) (PNG, 0,7 MB). Sin la última oración, el mismo prompt en 2K generó la página en chino (2048 x 8514, 38 créditos), y lo mismo pasó con un diseño web hecho en la app de Kling: <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-web-design-2k-chinese-top.jpg" alt="El mismo prompt de diseño web sin idioma: el texto de la página está en chino" loading="lazy" style="width:100%"> La parte superior de la página sin "All text on the page in English." La página completa: [original](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-web-design-2k-chinese-original.png) (PNG de 2048 x 8514, 1,4 MB). ### Cuánto cuesta Kling Image 4.0 usa los créditos de tu suscripción de Kling AI, los mismos en todos los planes. La API para desarrolladores de Kling lo vende en sus propios paquetes de imágenes, el más pequeño a US$300 por 78.216 unidades (US$0,00384 por unidad, 180 días), y además cobra 0,8 unidades por cada imagen de referencia o elemento. Con useapi.net, las referencias no cuestan nada extra. Lo que cuesta cada imagen o página en la API oficial y en cada plan de Kling AI (en dólares estadounidenses): | Modelo | [API oficial](https://kling.ai/dev/pricing) | Premier $80,96/mes (8.000 cr/mes) | Pro $32,56/mes (3.000 cr/mes) | Standard $8,80/mes (660 cr/mes) | |---|---|---|---|---| | Kling Image 4.0 (2K) | $0,06 (16 unidades) | $0,04 / 4 cr (2.000 imágenes/mes) | $0,04 / 4 cr (750 imágenes/mes) | $0,05 / 4 cr (165 imágenes/mes) | | Kling Image 4.0 (4K) | $0,09 (24 unidades) | $0,06 / 6 cr (1.333 imágenes/mes) | $0,07 / 6 cr (500 imágenes/mes) | $0,08 / 6 cr (110 imágenes/mes) | | Kling Image 4.0 (8K) | $0,15 (40 unidades) | $0,10 / 10 cr (800 imágenes/mes) | $0,11 / 10 cr (300 imágenes/mes) | $0,13 / 10 cr (66 imágenes/mes) | | Página de producto (2K, corta) | $0,28 (72 unidades) | $0,18 / 18 cr (444 páginas/mes) | $0,20 / 18 cr (166 páginas/mes) | $0,24 / 18 cr (36 páginas/mes) | | Página de producto (2K, larga) | $0,84 (220 unidades) | $0,56 / 55 cr (145 páginas/mes) | $0,60 / 55 cr (54 páginas/mes) | $0,73 / 55 cr (12 páginas/mes) | | Diseño web (2K) | $0,58 (152 unidades) | $0,38 / 38 cr (210 páginas/mes) | $0,41 / 38 cr (78 páginas/mes) | $0,51 / 38 cr (17 páginas/mes) | Precios a 19 de noviembre de 2026. Los precios de Kling para todos los planes están en la [calculadora de precios de Kling](/docs/api-kling-v1#pricing). Toda nuestra ejecución para esta guía, 13 tareas que generaron 18 imágenes y páginas, usó 181 créditos, unos US$1,96 en Pro. ### Genera en lote con el script El [ejemplo image-4](https://github.com/useapi/kling-api/tree/main/image-4) de nuestro repositorio de GitHub lee una lista de prompts de `prompts.json` (los prompts de esta guía), envía cada uno, espera a que termine y descarga todas las imágenes: ```bash git clone https://github.com/useapi/kling-api.git cd kling-api/image-4 node ./kling-image-4.mjs $USEAPI_TOKEN $KLING_EMAIL ``` Revisa cada prompt antes de gastar créditos: una página de detalle de producto necesita `image_1`, una habilidad (skill) genera en 1K o 2K, y `length` solo va con `product_detail`. ### Lo mismo desde un asistente de IA El [servidor MCP de Kling](/docs/api-kling-v1/mcp) alojado en `https://api.useapi.net/v1/kling/mcp` les da a Claude Code, Cursor, VS Code y la app de Claude las mismas llamadas: `kling_omni_image` con `omni_version: v4`, y `kling_list_image_presets` para los ids de estilos, tonos y fuentes. Pide "una foto 8K de…" o "una página de producto a partir de esta foto" y el asistente completa la solicitud. ### Preguntas frecuentes **¿Existe una API de Kling Image 4.0?** Sí. useapi.net ejecuta Kling Image 4.0 con tu suscripción de Kling AI mediante [POST images/omni](/docs/api-kling-v1/post-kling-images-omni) con `omni_version: v4`: 8K, Series Mode, presets, páginas de producto y diseños web, por 4 créditos la imagen 2K, unos US$0,04 en Kling Pro. La API para desarrolladores de Kling también lo vende, a US$0,06 la imagen 2K en paquetes prepagados desde US$300, más un cargo por cada imagen de referencia, así que la vía de la suscripción sale cerca de un 30% más barata (a 19 de noviembre de 2026). **¿Cómo obtengo una imagen 8K de Kling?** Envía `"omni_version": "v4", "resolution": "8k"` a [POST images/omni](/docs/api-kling-v1/post-kling-images-omni) con un plan de pago de Kling. Nuestra ejecución en 16:9 llegó en 10880 x 6144 por 10 créditos a precio de lista (US$0,11 en Kling Pro), y Kling cobró 6 durante su promoción. La API para desarrolladores de Kling cobra US$0,15 por la misma imagen 8K. **¿Por qué mi diseño web de Kling está en chino?** Kling Image 4.0 escribe el texto de una página `web_design` en chino si el prompt no indica el idioma, tanto en la app de Kling como a través de la API. Termina el prompt con "All text on the page in English." Nuestra página en inglés llegó en 1K por 35 créditos. **¿Qué presets puedo usar?** [GET images/presets](/docs/api-kling-v1/get-kling-images-presets) lista los 98 estilos, 16 tonos y 76 fuentes actuales de Kling con sus ids y muestras, los mismos para todas las cuentas. Nómbralos en un prompt `v4` como `@style:<id>`, `@tone:<id>` y `@font:<id>` antes del texto entre comillas. No cuestan créditos extra. ### Conclusión Kling Image 4.0 está a una solicitud de distancia con la suscripción que ya tienes: `omni_version: v4` en [POST images/omni](/docs/api-kling-v1/post-kling-images-omni), desde una imagen 2K de 4 créditos hasta una foto 8K de 67 megapíxeles, una historia de seis cuadros o una página de producto completa. Empieza con la documentación de la [API de Kling](/docs/api-kling-v1), o ejecuta el [script image-4](https://github.com/useapi/kling-api/tree/main/image-4) con los prompts de arriba. === URL: https://useapi.net/docs/articles/kling-image-4-api-id === Document URL: https://useapi.net/docs/articles/kling-image-4-api-id --- layout: default title: Cara Membuat Gambar Kling Image 4.0 dengan Kling API seo_title: "Kling Image 4.0 API: Gambar 8K, Series Mode, Halaman Produk" description: "Buat gambar Kling Image 4.0 dari kode dengan langganan Kling AI Anda: foto 8K, Series Mode, preset, halaman produk dan desain web, dengan run nyata dan biayanya." keywords: [Kling Image 4.0 API, API Kling Image 4.0, Kling Image 4 API, API gambar Kling 4.0, gambar 8K Kling, Kling 8K image, Kling Series Mode, halaman detail produk Kling, desain web Kling, preset gambar Kling, Kling Omni image, Kling API, API Kling, Kling AI API, API gambar AI, Kuaishou, Kling MCP server, curl, tutorial bahasa Indonesia] image: https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-8k-hummingbird.jpg parent: Articles nav_exclude: true lang: id translation_key: kling-image-4-api date: 2026-11-19 last_modified: 2026-11-19 nav_order: 856 repo: https://github.com/useapi/kling-api --- ## Cara Membuat Gambar Kling Image 4.0 dengan Kling API {: .no_toc #how-to-generate-kling-image-40-images-via-the-kling-api } 6 menit baca • 19 November 2026 ## Daftar isi {: .no_toc .text-delta #table-of-contents } ### Pendahuluan Kling Image 4.0 adalah model gambar baru dari Kuaishou, dan Kling API dari useapi.net menjalankannya di [langganan situs Kling AI](https://kling.ai/app/membership/membership-plan) Anda: kirim `"omni_version": "v4"` ke [POST images/omni](/docs/api-kling-v1/post-kling-images-omni). Satu endpoint mencakup semua yang bisa dilakukan aplikasi Kling dengan model ini: foto hingga 8K, cerita Series Mode berisi 2 sampai 10 gambar yang serasi, preset gaya, tone dan font yang disebut di prompt, serta dua skill desain yang masing-masing membuat satu gambar halaman panjang. Yang pertama membuat halaman detail produk dari foto produk, yang kedua membuat desain halaman web. Panduan ini berisi run nyata di langganan Kling Pro, satu untuk setiap fitur, lengkap dengan request persisnya, gambar yang dihasilkan dan biaya masing-masing. Satu gambar 2K memakai 4 kredit, sekitar $0,04 di Pro, sedangkan API developer Kling sendiri menjual gambar yang sama seharga $0,06 dalam paket gambar prabayar mulai $300. ### Sebelum mulai Anda butuh [API token](/docs/start-here/setup-useapi) useapi.net dan akun Kling yang terhubung lewat [Setup Kling](/docs/start-here/setup-kling), dengan paket Kling berbayar (Standard atau lebih tinggi). 4K dan 8K juga butuh paket berbayar. Ekspor token agar contoh `curl` bisa langsung dijalankan: ```bash export USEAPI_TOKEN="user:1234-..." # your useapi.net API token export KLING_EMAIL="you@example.com" # your connected Kling account ``` ### Sekilas tentang Kling Image 4.0 | Mode | Request | Yang Anda dapat | Kredit | |---|---|---|---| | Gambar | `omni_version: v4` | 1 sampai 9 gambar di 2K, 4K atau 8K, dengan salah satu dari 9 rasio aspek atau `auto` | 4 / 6 / 10 per gambar | | Series Mode | `story_mode: true` | 2 sampai 10 gambar yang menceritakan satu kisah, atau sebanyak yang ditentukan Kling | sama, per gambar | | Preset | `@style:`, `@tone:`, `@font:` di prompt | gaya, color grade atau huruf dari daftar Kling | tanpa biaya tambahan | | Halaman detail produk | `skill: product_detail` + `image_1` | satu halaman panjang dari foto produk Anda, pendek, sedang atau panjang | 15 sampai 55 per halaman | | Desain web | `skill: web_design` | satu desain landing page yang panjang | 35 di 1K, 38 di 2K | Hingga 10 gambar referensi dan [element](/docs/api-kling-v1/get-kling-elements) tersimpan bisa dipakai seperti di setiap request Omni: sebut di prompt sebagai `@image_1` atau `@element_1`. ### Membuat gambar 8K dengan dua panggilan #### 1. Kirim job ```bash curl -s -X POST "https://api.useapi.net/v1/kling/images/omni" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$KLING_EMAIL"'", "omni_version": "v4", "resolution": "8k", "aspect_ratio": "16:9", "prompt": "Macro photograph of a hummingbird hovering at a red trumpet flower at sunrise, every iridescent feather sharp, dew drops on the petals, soft golden backlight, shallow depth of field" }' ``` Jawabannya adalah task baru, dengan id-nya di `task.id`: ```json { "task": { "id": 123456789012345, "type": "mmu_omni_image", "status": 5, "status_name": "submitted", "status_final": false } } ``` #### 2. Ambil hasilnya dengan polling Baca task dengan [GET tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) sampai `status_final` bernilai `true`. Setiap gambar adalah satu item di `works`, dengan URL dan ukurannya: ```bash curl -s "https://api.useapi.net/v1/kling/tasks/123456789012345?email=$KLING_EMAIL" \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{status_name, works: [.works[] | {url: .resource.resource, width: .resource.width, height: .resource.height}]}' ``` ```json { "status_name": "succeed", "works": [ { "url": "https://s15-kling.klingai.com/kimg/.../image.png", "width": 10880, "height": 6144 } ] } ``` Run kami menghasilkan gambar 10880 x 6144, 67 megapiksel, dan memakai 6 kredit. Harga daftar 8K adalah 10 kredit, tetapi hari itu Kling menjalankannya dengan 6 kredit karena sedang ada diskon. Request yang sama dengan `"resolution": "2k"` menghasilkan gambar 2720 x 1536 seharga 4 kredit, dan `"4k"` menghasilkan gambar 5440 x 3072 seharga 6 kredit. <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-8k-hummingbird.jpg" alt="Kling Image 4.0 8K: burung kolibri di bunga terompet merah saat matahari terbit" loading="lazy" style="width:100%"> Kling Image 4.0, `8k`, `16:9`, 10880 x 6144, 6 kredit. Di sini ditampilkan lebih kecil: buka [file asli](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-8k-hummingbird-original.png) (PNG 10880 x 6144, 3,5 MB) untuk melihatnya dalam 8K penuh. Dalam ukuran penuh, detail 8K tetap terjaga. Ini potongan 1600 x 900 dari file yang sama, tanpa diperkecil: <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-8k-hummingbird-crop-100.jpg" alt="Potongan 100% dari gambar 8K: mata dan bulu burung kolibri" loading="lazy" style="width:100%"> Gambar yang sama di 100%, bagian kepala burung. ### Series Mode: satu cerita dari satu prompt `story_mode: true` membuat serangkaian gambar yang serasi: karakter, gaya dan cahaya yang sama dari panel ke panel. Kling Image 4.0 bisa membuat seri hanya dari prompt, tanpa gambar referensi. Atur `imageCount` ke 2 sampai 10, atau jangan diisi agar Kling yang menentukan berapa gambar yang dibutuhkan cerita itu. ```bash curl -s -X POST "https://api.useapi.net/v1/kling/images/omni" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$KLING_EMAIL"'", "omni_version": "v4", "story_mode": true, "aspect_ratio": "4:3", "prompt": "A picture-book story in consistent watercolor style: a small paper boat is folded by a child on a rainy city street, floats down the gutter, slips into a river past old bridges, and finally reaches the open sea at sunset" }' ``` Kling memilih 6 gambar untuk cerita ini, masing-masing 2336 x 1760, dan menagih 4 kredit per gambar, total 24 kredit. <div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(220px,1fr));gap:8px"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-1.jpg" alt="Series Mode 1 dari 6: seorang anak melipat perahu kertas di jalan yang diguyur hujan" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-2.jpg" alt="Series Mode 2 dari 6: perahu mengapung di selokan" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-3.jpg" alt="Series Mode 3 dari 6: perahu di kanal kota" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-4.jpg" alt="Series Mode 4 dari 6: perahu lewat di bawah jembatan tua" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-5.jpg" alt="Series Mode 5 dari 6: perahu di sungai yang lebar" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-6.jpg" alt="Series Mode 6 dari 6: perahu sampai di laut saat matahari terbenam" loading="lazy" style="width:100%"> </div> Kling Image 4.0 Series Mode, `story_mode: true`, `imageCount` tidak diisi, 6 gambar, 24 kredit. File asli, PNG 2336 x 1760: [1](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-1-original.png), [2](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-2-original.png), [3](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-3-original.png), [4](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-4-original.png), [5](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-5-original.png), [6](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-6-original.png). ### Gaya, tone dan font Kling Image 4.0 punya tiga jenis preset, dan Anda menyebutnya di prompt. [GET images/presets](/docs/api-kling-v1/get-kling-images-presets) mencantumkan semuanya dengan id dan gambar contoh: 98 gaya, 16 tone dan 76 font dalam bahasa Inggris, Jepang, Korea dan Mandarin. ```bash curl -s "https://api.useapi.net/v1/kling/images/presets" -H "Authorization: Bearer $USEAPI_TOKEN" \ | jq '{styles: [.styles[0:3][] | .id], tones: [.tones[] | .id], fonts: [.fonts[] | select(.languages | index("en")) | .id][0:5]}' ``` - Tone (`@tone:<id>`) menerapkan salah satu color grade dan pencahayaan dari Kling: gaya sutradara, tampilan kamera dan palet warna. - Font (`@font:<id>`) mengatur huruf untuk teks dalam tanda kutip yang mengikutinya. - Gaya (`@style:<id>`) mengatur tampilan keseluruhan: gaya 3D, 2D, kerajinan material atau fotografi. Berikut adegan yang sama tanpa tone dan dengan `@tone:Nostalgic_Wuxia`, masing-masing 4 kredit: <div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(280px,1fr));gap:8px"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-tone-none-swordsman.jpg" alt="Tanpa tone: seorang pendekar pedang di hutan bambu saat fajar" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-tone-nostalgic-wuxia-swordsman.jpg" alt="@tone:Nostalgic_Wuxia: adegan yang sama dengan grade film wuxia yang hangat dan pudar" loading="lazy" style="width:100%"> </div> Kiri: `A lone swordsman in a bamboo forest at dawn, mist between the stalks, wide cinematic shot`. Kanan: prompt yang sama setelah `@tone:Nostalgic_Wuxia`. File asli, PNG 2720 x 1536: [tanpa tone](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-tone-none-swordsman-original.png), [Nostalgic Wuxia](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-tone-nostalgic-wuxia-swordsman-original.png). Lalu papan nama toko tanpa font dan dengan `@font:elegant_brush_hand`. Tulis kata-kata yang ingin muncul di gambar dalam tanda kutip, dan taruh font tepat sebelumnya: ```json { "prompt": "A cozy corner coffee shop at night, warm light spilling onto a wet cobblestone street, a hand-painted shop sign above the door that reads @font:elegant_brush_hand \"Moonlight Roasters\"" } ``` <div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(280px,1fr));gap:8px"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-font-none-coffee-sign.jpg" alt="Tanpa font: papan nama dengan huruf serif biasa" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-font-elegant-brush-hand-coffee-sign.jpg" alt="@font:elegant_brush_hand: papan nama dengan huruf goresan kuas" loading="lazy" style="width:100%"> </div> Kiri: tanpa font. Kanan: `@font:elegant_brush_hand "Moonlight Roasters"`. File asli, PNG 2496 x 1664: [tanpa font](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-font-none-coffee-sign-original.png), [font kuas](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-font-elegant-brush-hand-coffee-sign-original.png). <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-style-3d-cartoon-corgi-astronaut.jpg" alt="@style:3d_cartoon_with_exaggerated_perspective_pro: corgi astronaut di planet berwarna permen" loading="lazy" style="width:60%"> `@style:3d_cartoon_with_exaggerated_perspective_pro A corgi astronaut stepping out of a tiny rocket onto a candy-colored planet, looking up at the camera`, `1:1`, 4 kredit. [file asli](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-style-3d-cartoon-corgi-astronaut-original.png) (PNG 2048 x 2048, 8,5 MB). Id yang tidak dikenal langsung mendapat `400` sebelum apa pun sampai ke Kling, jadi salah ketik tidak pernah memakan kredit. ### Gambar referensi Sebut referensi di prompt sebagai `@image_1`. Kami membuat foto produk lebih dulu, lalu memakai URL-nya sebagai `image_1` untuk foto iklan 4K. Produk, labelnya dan tutup bambunya tetap terbawa: ```json { "omni_version": "v4", "resolution": "4k", "aspect_ratio": "16:9", "prompt": "The bottle from @image_1 standing on a mossy rock beside a mountain stream, morning mist, outdoor adventure ad", "image_1": "https://s15-kling.klingai.com/kimg/.../bottle.png" } ``` <div style="display:grid;grid-template-columns:1fr 2fr;gap:8px;align-items:start"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-product-photo-bottle.jpg" alt="Foto produk: botol baja hijau sage dengan tutup bambu" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-4k-reference-bottle-stream.jpg" alt="4K dengan foto produk sebagai referensi: botol di samping sungai pegunungan" loading="lazy" style="width:100%"> </div> Kiri: foto produk, `3:4`, 4 kredit. Kanan: `4k` dengan foto itu sebagai `@image_1`, 5440 x 3072, 6 kredit. File asli: [foto produk](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-product-photo-bottle-original.png) (PNG 1760 x 2336, 4,8 MB), [foto iklan 4K](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-4k-reference-bottle-stream-original.png) (PNG 5440 x 3072, 24 MB). Untuk meng-upload foto Anda sendiri, pakai [POST assets](/docs/api-kling-v1/post-kling-assets) lalu kirim URL yang dikembalikannya. ### Halaman detail produk `skill: product_detail` mengubah satu foto produk menjadi halaman produk yang panjang: hero, keunggulan, close-up dan tabel spesifikasi, tersusun dalam satu gambar. `image_1` adalah fotonya, `prompt` menjelaskan apa yang dilakukan produk itu, dan `length` mengatur jumlah bagian: `short` (2 sampai 5), `medium` (6 sampai 10) atau `long` (11 sampai 18). ```bash curl -s -X POST "https://api.useapi.net/v1/kling/images/omni" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$KLING_EMAIL"'", "omni_version": "v4", "skill": "product_detail", "length": "short", "resolution": "2k", "image_1": "https://s15-kling.klingai.com/kimg/.../bottle.png", "prompt": "Insulated steel water bottle \"Trailhead\": keeps drinks cold 24 hours and hot 12, leak-proof bamboo lid, fits car cup holders, 750 ml, three colors" }' ``` Halaman itu kembali sebagai satu gambar 2048 x 13408 seharga 18 kredit. Halaman `medium` di 1K berukuran 1024 x 9936 seharga 30 kredit. <div style="max-height:900px;overflow-y:auto;border:1px solid #ddd"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-product-detail-page-2k-short.jpg" alt="Halaman detail produk Kling Image 4.0: botol Trailhead Sage Green, keunggulan dan spesifikasi" loading="lazy" style="width:100%"> </div> `skill: product_detail`, `length: short`, `2k`, 2048 x 13408, 18 kredit. Gulir bingkai untuk melihat seluruh halaman, atau buka [file asli](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-product-detail-page-2k-short-original.png) (PNG, 1,3 MB). ### Desain halaman web `skill: web_design` membuat desain landing page sebagai satu gambar panjang. `image_1` bersifat opsional, yaitu gambar yang gayanya harus diikuti halaman itu. Kling menulis teks halaman dalam bahasa Mandarin kecuali prompt menyebut bahasanya, jadi akhiri prompt dengan bahasa yang Anda inginkan: ```bash curl -s -X POST "https://api.useapi.net/v1/kling/images/omni" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$KLING_EMAIL"'", "omni_version": "v4", "skill": "web_design", "resolution": "1k", "prompt": "Landing page for \"Ember & Oak\", a small-batch coffee roaster: warm browns and cream, elegant serif headlines, hero photo of a pour-over, three featured roasts, a monthly subscription offer and customer reviews. All text on the page in English." }' ``` <div style="max-height:900px;overflow-y:auto;border:1px solid #ddd"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-web-design-1k-english.jpg" alt="Desain web Kling Image 4.0: landing page roaster kopi Ember & Oak dalam bahasa Inggris" loading="lazy" style="width:100%"> </div> `skill: web_design`, `1k`, 1024 x 5376, 35 kredit. Gulir bingkai untuk melihat seluruh halaman, atau buka [file asli](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-web-design-1k-english-original.png) (PNG, 0,7 MB). Tanpa kalimat terakhir itu, prompt yang sama di 2K menghasilkan halaman berbahasa Mandarin (2048 x 8514, 38 kredit), begitu juga desain web yang dibuat di aplikasi Kling: <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-web-design-2k-chinese-top.jpg" alt="Prompt desain web yang sama tanpa menyebut bahasa: teks halamannya berbahasa Mandarin" loading="lazy" style="width:100%"> Bagian atas halaman tanpa "All text on the page in English." Seluruh halaman: [file asli](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-web-design-2k-chinese-original.png) (PNG 2048 x 8514, 1,4 MB). ### Berapa biayanya Kling Image 4.0 memakai kredit langganan Kling AI Anda, dengan jumlah yang sama di setiap paket. API developer Kling menjualnya dalam paket gambar tersendiri, yang terkecil $300 untuk 78.216 unit ($0,00384 per unit, berlaku 180 hari), dan juga menagih 0,8 unit untuk setiap gambar referensi atau element. Lewat useapi.net, referensi tidak dikenai biaya tambahan. | Model | [API resmi](https://kling.ai/dev/pricing) | Premier $80,96/bln (8.000 cr/bln) | Pro $32,56/bln (3.000 cr/bln) | Standard $8,80/bln (660 cr/bln) | |---|---|---|---|---| | Kling Image 4.0 (2K) | $0,06 (16 unit) | $0,04 / 4 cr (2.000 gambar/bln) | $0,04 / 4 cr (750 gambar/bln) | $0,05 / 4 cr (165 gambar/bln) | | Kling Image 4.0 (4K) | $0,09 (24 unit) | $0,06 / 6 cr (1.333 gambar/bln) | $0,07 / 6 cr (500 gambar/bln) | $0,08 / 6 cr (110 gambar/bln) | | Kling Image 4.0 (8K) | $0,15 (40 unit) | $0,10 / 10 cr (800 gambar/bln) | $0,11 / 10 cr (300 gambar/bln) | $0,13 / 10 cr (66 gambar/bln) | | Halaman detail produk (2K, pendek) | $0,28 (72 unit) | $0,18 / 18 cr (444 halaman/bln) | $0,20 / 18 cr (166 halaman/bln) | $0,24 / 18 cr (36 halaman/bln) | | Halaman detail produk (2K, panjang) | $0,84 (220 unit) | $0,56 / 55 cr (145 halaman/bln) | $0,60 / 55 cr (54 halaman/bln) | $0,73 / 55 cr (12 halaman/bln) | | Desain web (2K) | $0,58 (152 unit) | $0,38 / 38 cr (210 halaman/bln) | $0,41 / 38 cr (78 halaman/bln) | $0,51 / 38 cr (17 halaman/bln) | Harga per 19 November 2026. Harga Kling untuk setiap paket ada di [kalkulator harga Kling](/docs/api-kling-v1#pricing). Seluruh run kami untuk panduan ini, 13 job yang menghasilkan 18 gambar dan halaman, memakai 181 kredit, sekitar $1,96 di Pro. ### Generate massal dengan skrip [Contoh image-4](https://github.com/useapi/kling-api/tree/main/image-4) di repo GitHub kami membaca daftar prompt dari `prompts.json`, yaitu prompt-prompt di panduan ini, lalu mengirim masing-masing, menunggu hasilnya dan mengunduh setiap gambar: ```bash git clone https://github.com/useapi/kling-api.git cd kling-api/image-4 node ./kling-image-4.mjs $USEAPI_TOKEN $KLING_EMAIL ``` Skrip ini memeriksa setiap prompt sebelum memakai kredit: halaman detail produk butuh `image_1`, sebuah skill hanya membuat 1K atau 2K, dan `length` hanya dipakai bersama `product_detail`. ### Hal yang sama dari asisten AI [Kling MCP server](/docs/api-kling-v1/mcp) yang di-hosting di `https://api.useapi.net/v1/kling/mcp` memberi Claude Code, Cursor, VS Code dan aplikasi Claude panggilan yang sama: `kling_omni_image` dengan `omni_version: v4`, dan `kling_list_image_presets` untuk id gaya, tone dan font. Minta "foto 8K dari…" atau "halaman produk dari foto ini", dan asisten akan mengisi request-nya. ### Pertanyaan yang sering diajukan **Apakah ada API Kling Image 4.0?** Ya. useapi.net menjalankan Kling Image 4.0 di langganan Kling AI Anda lewat [POST images/omni](/docs/api-kling-v1/post-kling-images-omni) dengan `omni_version: v4`: 8K, Series Mode, preset, halaman produk dan desain web, seharga 4 kredit per gambar 2K, sekitar $0,04 di Kling Pro. API developer Kling sendiri juga menjualnya, $0,06 per gambar 2K dalam paket prabayar mulai $300, ditambah biaya untuk setiap gambar referensi. Jadi jalur langganan sekitar 30% lebih murah (per 19 November 2026). **Bagaimana cara mendapatkan gambar 8K dari Kling?** Kirim `"omni_version": "v4", "resolution": "8k"` ke [POST images/omni](/docs/api-kling-v1/post-kling-images-omni) dengan paket Kling berbayar. Run 16:9 kami kembali di 10880 x 6144 seharga 10 kredit menurut harga daftar ($0,11 di Kling Pro), dan selama diskon Kling hanya menagih 6. API developer Kling menagih $0,15 untuk gambar 8K yang sama. **Kenapa desain web Kling saya berbahasa Mandarin?** Kling Image 4.0 menulis teks halaman `web_design` dalam bahasa Mandarin kecuali prompt menyebut bahasanya, baik di aplikasi Kling maupun lewat API. Akhiri prompt dengan "All text on the page in English." Halaman berbahasa Inggris kami kembali di 1K seharga 35 kredit. **Preset apa saja yang bisa saya pakai?** [GET images/presets](/docs/api-kling-v1/get-kling-images-presets) mencantumkan 98 gaya, 16 tone dan 76 font Kling saat ini, dengan id dan contohnya, sama untuk setiap akun. Sebut di prompt `v4` sebagai `@style:<id>`, `@tone:<id>` dan `@font:<id>` sebelum teks dalam tanda kutip. Preset tidak memakai kredit tambahan. ### Kesimpulan Kling Image 4.0 bisa Anda pakai dengan satu request di langganan yang sudah Anda punya: `omni_version: v4` di [POST images/omni](/docs/api-kling-v1/post-kling-images-omni), dari gambar 2K seharga 4 kredit hingga foto 8K 67 megapiksel, cerita enam panel atau halaman produk lengkap. Mulai dari dokumentasi [Kling API](/docs/api-kling-v1), atau jalankan [skrip image-4](https://github.com/useapi/kling-api/tree/main/image-4) dengan prompt di atas. === URL: https://useapi.net/docs/articles/kling-image-4-api-ja === Document URL: https://useapi.net/docs/articles/kling-image-4-api-ja --- layout: default title: "Kling API で Kling Image 4.0 の画像を生成する方法" seo_title: "Kling Image 4.0 API:8K・シリーズモード・商品ページを生成" description: "Kling AI のサブスクリプションで、コードから Kling Image 4.0 の画像を生成。8K 写真、シリーズモード、プリセット、商品詳細ページ、Web デザインを実例と料金付きで解説。" keywords: [Kling Image 4.0 API, Kling Image 4.0 使い方, Kling 4.0 画像生成 API, Kling 8K 画像, Kling シリーズモード, Kling 商品詳細ページ, Kling Web デザイン, Kling 画像プリセット, Kling Omni 画像, Kling API, Kling AI API, 画像生成 API, Kuaishou, Kling MCP サーバー, Kling Image 4 API, Kling Series Mode, Kling product detail page, curl, チュートリアル] image: https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-8k-hummingbird.jpg parent: Articles nav_exclude: true lang: ja translation_key: kling-image-4-api date: 2026-11-19 last_modified: 2026-11-19 nav_order: 856 repo: https://github.com/useapi/kling-api --- ## Kling API で Kling Image 4.0 の画像を生成する方法 {: .no_toc #how-to-generate-kling-image-40-images-via-the-kling-api } 6分で読めます • 2026年11月19日 ## 目次 {: .no_toc .text-delta #table-of-contents } ### はじめに Kling Image 4.0 は Kuaishou の新しい画像モデルです。useapi.net の Kling API なら、お持ちの [Kling AI のサブスクリプション](https://kling.ai/app/membership/membership-plan)でこのモデルを使えます。[POST images/omni](/docs/api-kling-v1/post-kling-images-omni) に `"omni_version": "v4"` を送るだけです。Kling アプリでこのモデルにできることは、すべてこの1つのエンドポイントでできます。最大 8K の写真、統一感のある2〜10枚の画像で1つの物語を描くシリーズモード(Series Mode)、プロンプトで指定するスタイル・トーン・フォントのプリセット、そして縦長のページ画像を1枚で作る2つのデザインスキルです。デザインスキルは、商品写真から作る商品詳細ページと、Web ページのデザインです。 このガイドは、Kling Pro のサブスクリプションで機能ごとに実際に実行した記録です。正確なリクエスト、できた画像、それぞれの料金を載せています。2K の画像1枚は4クレジットで、Pro プランなら約 $0.04 でした。Kling 自身の開発者向け API では、同じ画像が $300 からの前払い画像パックで $0.06 です。 ### 始める前に useapi.net の [API トークン](/docs/start-here/setup-useapi)と、[Setup Kling](/docs/start-here/setup-kling) で接続した Kling アカウントが必要です。Kling は有料プラン(Standard 以上)にしてください。4K と 8K にも有料プランが必要です。`curl` の例がそのまま動くように、トークンを環境変数に設定しておきます。 ```bash export USEAPI_TOKEN="user:1234-..." # your useapi.net API token export KLING_EMAIL="you@example.com" # your connected Kling account ``` ### Kling Image 4.0 の概要 | モード | リクエスト | できるもの | クレジット | |---|---|---|---| | 画像 | `omni_version: v4` | 2K・4K・8K の画像を1〜9枚。9種類のアスペクト比か `auto` | 1枚あたり 4 / 6 / 10 | | シリーズモード | `story_mode: true` | 1つの物語を描く2〜10枚の画像、または Kling が決めた枚数 | 1枚あたり同じ | | プリセット | プロンプト内の `@style:`、`@tone:`、`@font:` | Kling のリストにある見た目、カラーグレード、書体 | 追加料金なし | | 商品詳細ページ | `skill: product_detail` + `image_1` | 商品写真から作る縦長のページ1枚。short、medium、long | 1ページ15〜55 | | Web デザイン | `skill: web_design` | 縦長のランディングページのデザイン1枚 | 1K で35、2K で38 | 最大10枚の参照画像と保存済みの[エレメント](/docs/api-kling-v1/get-kling-elements)も、ほかの Omni リクエストと同じように使えます。プロンプトでは `@image_1` や `@element_1` と書いて指定します。 ### 2回の呼び出しで 8K 画像を生成する #### 1. ジョブを送信する ```bash curl -s -X POST "https://api.useapi.net/v1/kling/images/omni" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$KLING_EMAIL"'", "omni_version": "v4", "resolution": "8k", "aspect_ratio": "16:9", "prompt": "Macro photograph of a hummingbird hovering at a red trumpet flower at sunrise, every iridescent feather sharp, dew drops on the petals, soft golden backlight, shallow depth of field" }' ``` レスポンスは新しいタスクで、その ID は `task.id` に入っています。 ```json { "task": { "id": 123456789012345, "type": "mmu_omni_image", "status": 5, "status_name": "submitted", "status_final": false } } ``` #### 2. 結果をポーリングする [GET tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) でタスクを読み、`status_final` が `true` になるまで待ちます。画像はそれぞれ `works` の1項目として、URL とサイズ付きで返ります。 ```bash curl -s "https://api.useapi.net/v1/kling/tasks/123456789012345?email=$KLING_EMAIL" \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{status_name, works: [.works[] | {url: .resource.resource, width: .resource.width, height: .resource.height}]}' ``` ```json { "status_name": "succeed", "works": [ { "url": "https://s15-kling.klingai.com/kimg/.../image.png", "width": 10880, "height": 6144 } ] } ``` 今回の実行では 10880 x 6144、6,700万画素の画像ができ、使ったのは6クレジットでした。8K の定価は10クレジットですが、この日は Kling のセール中で6クレジットでした。同じリクエストで `"resolution": "2k"` にすると 2720 x 1536 の画像が4クレジット、`"4k"` なら 5440 x 3072 の画像が6クレジットです。 <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-8k-hummingbird.jpg" alt="Kling Image 4.0 の 8K:日の出の赤いラッパ形の花に浮かぶハチドリ" loading="lazy" style="width:100%"> Kling Image 4.0、`8k`、`16:9`、10880 x 6144、6クレジット。ここでは縮小して表示しています。8K のフルサイズで見るには[元画像](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-8k-hummingbird-original.png)を開いてください (10880 x 6144 PNG、3.5 MB)。 原寸で見ても、8K の細部はしっかり残っています。これは同じファイルを縮小せずに切り出した 1600 x 900 の部分です。 <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-8k-hummingbird-crop-100.jpg" alt="8K 画像の等倍の切り抜き:ハチドリの目と羽" loading="lazy" style="width:100%"> 同じ画像の等倍表示。鳥の頭の部分です。 ### シリーズモード:1つのプロンプトから物語を作る `story_mode: true` で、統一感のある連作画像を作れます。登場人物、画風、光がコマからコマへと保たれます。Kling Image 4.0 は参照画像なしで、プロンプトだけから連作を作ります。`imageCount` を2〜10に設定するか、省略すれば物語に必要な枚数を Kling が決めます。 ```bash curl -s -X POST "https://api.useapi.net/v1/kling/images/omni" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$KLING_EMAIL"'", "omni_version": "v4", "story_mode": true, "aspect_ratio": "4:3", "prompt": "A picture-book story in consistent watercolor style: a small paper boat is folded by a child on a rainy city street, floats down the gutter, slips into a river past old bridges, and finally reaches the open sea at sunset" }' ``` この物語には Kling が6枚を選びました。各 2336 x 1760 で、1枚4クレジット、合計24クレジットです。 <div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(220px,1fr));gap:8px"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-1.jpg" alt="シリーズモード 1/6:雨の街角で子どもが紙の船を折る" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-2.jpg" alt="シリーズモード 2/6:船が側溝を流れていく" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-3.jpg" alt="シリーズモード 3/6:街の運河を進む船" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-4.jpg" alt="シリーズモード 4/6:古い橋の下をくぐる船" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-5.jpg" alt="シリーズモード 5/6:広い川を進む船" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-6.jpg" alt="シリーズモード 6/6:夕日の中、船が海にたどり着く" loading="lazy" style="width:100%"> </div> Kling Image 4.0 のシリーズモード、`story_mode: true`、`imageCount` は省略、6枚、24クレジット。元画像(2336 x 1760 PNG):[1](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-1-original.png)、[2](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-2-original.png)、[3](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-3-original.png)、[4](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-4-original.png)、[5](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-5-original.png)、[6](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-6-original.png)。 ### スタイル、トーン、フォント Kling Image 4.0 には3種類のプリセットがあり、プロンプトの中で指定します。[GET images/presets](/docs/api-kling-v1/get-kling-images-presets) は、それぞれの ID とサンプル画像の一覧を返します。スタイル98種類、トーン16種類、フォント76種類(英語、日本語、韓国語、中国語)です。 ```bash curl -s "https://api.useapi.net/v1/kling/images/presets" -H "Authorization: Bearer $USEAPI_TOKEN" \ | jq '{styles: [.styles[0:3][] | .id], tones: [.tones[] | .id], fonts: [.fonts[] | select(.languages | index("en")) | .id][0:5]}' ``` - トーン(`@tone:<id>`)は、Kling のカラーグレードとライティングの1つを適用します。映画監督風のスタイル、カメラのルック、配色などがあります。 - フォント(`@font:<id>`)は、その後に続く引用符内の文字の書体を決めます。 - スタイル(`@style:<id>`)は、全体の見た目を決めます。3D、2D、素材を使ったクラフト、写真のスタイルなどがあります。 同じシーンを、トーンなしと `@tone:Nostalgic_Wuxia` 付きで作った例です。どちらも4クレジットです。 <div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(280px,1fr));gap:8px"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-tone-none-swordsman.jpg" alt="トーンなし:夜明けの竹林に立つ剣士" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-tone-nostalgic-wuxia-swordsman.jpg" alt="@tone:Nostalgic_Wuxia:同じシーンに、暖かく色あせた武侠映画風のグレード" loading="lazy" style="width:100%"> </div> 左:`A lone swordsman in a bamboo forest at dawn, mist between the stalks, wide cinematic shot`。右:同じプロンプトの前に `@tone:Nostalgic_Wuxia` を付けたもの。元画像(2720 x 1536 PNG):[トーンなし](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-tone-none-swordsman-original.png)、[Nostalgic Wuxia](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-tone-nostalgic-wuxia-swordsman-original.png)。 次は、店の看板をフォントなしと `@font:elegant_brush_hand` 付きで作った例です。画像に入れたい文字は引用符で囲み、そのすぐ前にフォントを書きます。 ```json { "prompt": "A cozy corner coffee shop at night, warm light spilling onto a wet cobblestone street, a hand-painted shop sign above the door that reads @font:elegant_brush_hand \"Moonlight Roasters\"" } ``` <div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(280px,1fr));gap:8px"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-font-none-coffee-sign.jpg" alt="フォントなし:看板はシンプルなセリフ体" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-font-elegant-brush-hand-coffee-sign.jpg" alt="@font:elegant_brush_hand:看板は筆で書いたような書体" loading="lazy" style="width:100%"> </div> 左:フォントなし。右:`@font:elegant_brush_hand "Moonlight Roasters"`。元画像(2496 x 1664 PNG):[フォントなし](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-font-none-coffee-sign-original.png)、[筆書体](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-font-elegant-brush-hand-coffee-sign-original.png)。 <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-style-3d-cartoon-corgi-astronaut.jpg" alt="@style:3d_cartoon_with_exaggerated_perspective_pro:キャンディ色の惑星に降り立つコーギーの宇宙飛行士" loading="lazy" style="width:60%"> `@style:3d_cartoon_with_exaggerated_perspective_pro A corgi astronaut stepping out of a tiny rocket onto a candy-colored planet, looking up at the camera`、`1:1`、4クレジット。[元画像](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-style-3d-cartoon-corgi-astronaut-original.png)(2048 x 2048 PNG、8.5 MB)。 存在しない ID を指定すると、Kling に届く前に `400` が返ります。入力ミスでクレジットが減ることはありません。 ### 参照画像 参照画像は、プロンプトの中で `@image_1` として指定します。今回はまず商品写真を作り、その URL を `image_1` にして 4K の広告写真を作りました。商品そのもの、ラベル、竹のふたがそのまま引き継がれています。 ```json { "omni_version": "v4", "resolution": "4k", "aspect_ratio": "16:9", "prompt": "The bottle from @image_1 standing on a mossy rock beside a mountain stream, morning mist, outdoor adventure ad", "image_1": "https://s15-kling.klingai.com/kimg/.../bottle.png" } ``` <div style="display:grid;grid-template-columns:1fr 2fr;gap:8px;align-items:start"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-product-photo-bottle.jpg" alt="商品写真:竹のふたが付いたセージグリーンのスチールボトル" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-4k-reference-bottle-stream.jpg" alt="商品写真を参照にした 4K:渓流のそばに立つボトル" loading="lazy" style="width:100%"> </div> 左:商品写真、`3:4`、4クレジット。右:それを `@image_1` にした `4k`、5440 x 3072、6クレジット。元画像:[商品写真](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-product-photo-bottle-original.png)(1760 x 2336 PNG、4.8 MB)、[4K の広告写真](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-4k-reference-bottle-stream-original.png)(5440 x 3072 PNG、24 MB)。 自分の写真を使うには、[POST assets](/docs/api-kling-v1/post-kling-assets) でアップロードし、返ってきた URL を渡します。 ### 商品詳細ページ `skill: product_detail` は、商品写真1枚から縦長の商品ページを作ります。メインビジュアル、特長、クローズアップ、仕様表が1枚の画像にレイアウトされます。`image_1` が写真、`prompt` が商品の説明で、`length` でセクション数を決めます。`short`(2〜5)、`medium`(6〜10)、`long`(11〜18)の3種類です。 ```bash curl -s -X POST "https://api.useapi.net/v1/kling/images/omni" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$KLING_EMAIL"'", "omni_version": "v4", "skill": "product_detail", "length": "short", "resolution": "2k", "image_1": "https://s15-kling.klingai.com/kimg/.../bottle.png", "prompt": "Insulated steel water bottle \"Trailhead\": keeps drinks cold 24 hours and hot 12, leak-proof bamboo lid, fits car cup holders, 750 ml, three colors" }' ``` ページは 2048 x 13408 の画像1枚で返り、18クレジットでした。1K の `medium` ページは 1024 x 9936 で、30クレジットでした。 <div style="max-height:900px;overflow-y:auto;border:1px solid #ddd"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-product-detail-page-2k-short.jpg" alt="Kling Image 4.0 の商品詳細ページ:Sage Green の Trailhead ボトルの特長と仕様" loading="lazy" style="width:100%"> </div> `skill: product_detail`、`length: short`、`2k`、2048 x 13408、18クレジット。枠内をスクロールするとページ全体を見られます。[元画像](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-product-detail-page-2k-short-original.png)(PNG、1.3 MB)も開けます。 ### Web ページのデザイン `skill: web_design` は、ランディングページのデザインを縦長の画像1枚で作ります。`image_1` は任意で、ページに取り入れたいスタイルの画像を渡します。プロンプトで言語を指定しないと、Kling はページの文字を中国語で書きます。プロンプトの最後に、使いたい言語を書いてください。 ```bash curl -s -X POST "https://api.useapi.net/v1/kling/images/omni" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$KLING_EMAIL"'", "omni_version": "v4", "skill": "web_design", "resolution": "1k", "prompt": "Landing page for \"Ember & Oak\", a small-batch coffee roaster: warm browns and cream, elegant serif headlines, hero photo of a pour-over, three featured roasts, a monthly subscription offer and customer reviews. All text on the page in English." }' ``` <div style="max-height:900px;overflow-y:auto;border:1px solid #ddd"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-web-design-1k-english.jpg" alt="Kling Image 4.0 の Web デザイン:英語で書かれたコーヒー焙煎所 Ember & Oak のランディングページ" loading="lazy" style="width:100%"> </div> `skill: web_design`、`1k`、1024 x 5376、35クレジット。枠内をスクロールするとページ全体を見られます。[元画像](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-web-design-1k-english-original.png)(PNG、0.7 MB)も開けます。 最後の1文を外して同じプロンプトを 2K で実行すると、ページは中国語になりました(2048 x 8514、38クレジット)。Kling アプリで作った Web デザインも同じでした。 <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-web-design-2k-chinese-top.jpg" alt="言語を指定しない同じ Web デザインのプロンプト:ページの文字が中国語になっている" loading="lazy" style="width:100%"> 「All text on the page in English.」を外したページの上部。ページ全体:[元画像](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-web-design-2k-chinese-original.png)(2048 x 8514 PNG、1.4 MB)。 ### 料金 Kling Image 4.0 は Kling AI サブスクリプションのクレジットを使い、消費量はどのプランでも同じです。Kling の開発者向け API では専用の画像パックで販売されていて、最小のパックは $300 で78,216ユニット(1ユニット $0.00384、有効期間180日)です。さらに、参照画像やエレメント1つごとに0.8ユニットかかります。useapi.net 経由なら、参照画像に追加料金はかかりません。 | モデル | [公式 API](https://kling.ai/dev/pricing) | Premier $80.96/月 (月8,000クレジット) | Pro $32.56/月 (月3,000クレジット) | Standard $8.80/月 (月660クレジット) | |---|---|---|---|---| | Kling Image 4.0 (2K) | $0.06 (16ユニット) | $0.04 / 4クレジット (月2,000枚) | $0.04 / 4クレジット (月750枚) | $0.05 / 4クレジット (月165枚) | | Kling Image 4.0 (4K) | $0.09 (24ユニット) | $0.06 / 6クレジット (月1,333枚) | $0.07 / 6クレジット (月500枚) | $0.08 / 6クレジット (月110枚) | | Kling Image 4.0 (8K) | $0.15 (40ユニット) | $0.10 / 10クレジット (月800枚) | $0.11 / 10クレジット (月300枚) | $0.13 / 10クレジット (月66枚) | | 商品詳細ページ (2K、short) | $0.28 (72ユニット) | $0.18 / 18クレジット (月444ページ) | $0.20 / 18クレジット (月166ページ) | $0.24 / 18クレジット (月36ページ) | | 商品詳細ページ (2K、long) | $0.84 (220ユニット) | $0.56 / 55クレジット (月145ページ) | $0.60 / 55クレジット (月54ページ) | $0.73 / 55クレジット (月12ページ) | | Web デザイン (2K) | $0.58 (152ユニット) | $0.38 / 38クレジット (月210ページ) | $0.41 / 38クレジット (月78ページ) | $0.51 / 38クレジット (月17ページ) | 2026年11月19日時点の価格です。Kling の全プランの料金は [Kling の料金計算ツール](/docs/api-kling-v1#pricing)にあります。このガイドのための実行は全部で13ジョブ、できた画像とページは18枚で、使ったのは181クレジット、Pro プランで約 $1.96 でした。 ### スクリプトで一括生成する GitHub リポジトリの [image-4 のサンプル](https://github.com/useapi/kling-api/tree/main/image-4)は、`prompts.json` からプロンプトの一覧(このガイドのプロンプト)を読み込み、1つずつ送信して完了を待ち、すべての画像をダウンロードします。 ```bash git clone https://github.com/useapi/kling-api.git cd kling-api/image-4 node ./kling-image-4.mjs $USEAPI_TOKEN $KLING_EMAIL ``` クレジットを使う前に、各プロンプトをチェックします。商品詳細ページには `image_1` が必要で、スキルで作れるのは 1K か 2K だけ、`length` は `product_detail` でしか使えません。 ### AI アシスタントから同じことをする ホスト型の [Kling MCP サーバー](/docs/api-kling-v1/mcp)(`https://api.useapi.net/v1/kling/mcp`)を使うと、Claude Code、Cursor、VS Code、Claude アプリから同じ呼び出しができます。`kling_omni_image` に `omni_version: v4` を付けて使い、スタイル・トーン・フォントの ID は `kling_list_image_presets` で調べます。「〜の 8K 写真を作って」や「この写真から商品ページを作って」と頼めば、アシスタントがリクエストを組み立てます。 ### よくある質問 **Kling Image 4.0 の API はありますか?** あります。useapi.net は、お持ちの Kling AI サブスクリプションで Kling Image 4.0 を動かします。[POST images/omni](/docs/api-kling-v1/post-kling-images-omni) に `omni_version: v4` を付けるだけで、8K、シリーズモード、プリセット、商品ページ、Web デザインが使えます。料金は 2K 画像1枚4クレジット、Kling Pro で約 $0.04 です。Kling 自身の開発者向け API でも販売されていますが、2K 画像1枚 $0.06 で、$300 からの前払いパックが必要なうえ、参照画像ごとに料金がかかります。サブスクリプション経由なら約30%安くなります(2026年11月19日時点)。 **Kling で 8K 画像を作るには?** 有料の Kling プランで、[POST images/omni](/docs/api-kling-v1/post-kling-images-omni) に `"omni_version": "v4", "resolution": "8k"` を送ります。16:9 の実行では 10880 x 6144 の画像ができました。定価では10クレジット(Kling Pro で $0.11)で、セール中の Kling は6クレジットでした。Kling の開発者向け API では、同じ 8K 画像が $0.15 です。 **Kling の Web デザインが中国語になるのはなぜですか?** Kling Image 4.0 は、プロンプトで言語を指定しないと `web_design` ページの文字を中国語で書きます。Kling アプリでも API 経由でも同じです。プロンプトの最後に「All text on the page in English.」を付けてください。英語のページは 1K、35クレジットでできました。 **どのプリセットを使えますか?** [GET images/presets](/docs/api-kling-v1/get-kling-images-presets) が、Kling の現在のスタイル98種類、トーン16種類、フォント76種類を ID とサンプル付きで返します。内容はどのアカウントでも同じです。`v4` のプロンプトで `@style:<id>`、`@tone:<id>`、引用符で囲んだ文字の前に `@font:<id>` と書いて指定します。追加のクレジットはかかりません。 ### まとめ Kling Image 4.0 は、すでにお持ちのサブスクリプションで、リクエスト1つで使えます。[POST images/omni](/docs/api-kling-v1/post-kling-images-omni) に `omni_version: v4` を付けるだけで、4クレジットの 2K 画像から 6,700万画素の 8K 写真、6コマの物語、商品ページ全体まで作れます。まずは [Kling API](/docs/api-kling-v1) のドキュメントを読むか、上のプロンプトで [image-4 のスクリプト](https://github.com/useapi/kling-api/tree/main/image-4)を実行してみてください。 === URL: https://useapi.net/docs/articles/kling-image-4-api-pt === Document URL: https://useapi.net/docs/articles/kling-image-4-api-pt --- layout: default title: Como gerar imagens com o Kling Image 4.0 pela API do Kling seo_title: "API do Kling Image 4.0: imagens 8K, Series Mode e presets" description: "Gere imagens do Kling Image 4.0 por código na sua assinatura do Kling AI: fotos 8K, Series Mode, presets, páginas de produto e web designs, com custos reais." keywords: [Kling Image 4.0 API, API do Kling Image 4.0, Kling Image 4 API, API de imagem Kling 4.0, imagem 8K Kling, Kling 8K image, Kling Series Mode, modo série Kling, página de produto Kling, Kling product detail page, web design Kling, presets de imagem Kling, Kling Omni image, Kling API, API do Kling, Kling AI API, API de imagens com IA, Kuaishou, Kling MCP server, curl, tutorial Kling Image 4.0] image: https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-8k-hummingbird.jpg parent: Articles nav_exclude: true lang: pt-BR translation_key: kling-image-4-api date: 2026-11-19 last_modified: 2026-11-19 nav_order: 856 repo: https://github.com/useapi/kling-api --- ## Como gerar imagens com o Kling Image 4.0 pela API do Kling {: .no_toc #how-to-generate-kling-image-40-images-via-the-kling-api } 6 min de leitura • 19 de novembro de 2026 ## Sumário {: .no_toc .text-delta #table-of-contents } ### Introdução O Kling Image 4.0 é o novo modelo de imagem da Kuaishou, e a API do Kling da useapi.net o roda na sua [assinatura do site do Kling AI](https://kling.ai/app/membership/membership-plan): basta enviar `"omni_version": "v4"` para [POST images/omni](/docs/api-kling-v1/post-kling-images-omni). Um único endpoint cobre tudo o que o app do Kling faz com ele: fotos de até 8K, histórias em Series Mode com 2 a 10 imagens que combinam entre si, presets de estilo, tom e fonte citados no prompt, e duas skills de design que geram, cada uma, uma imagem de página longa: uma página de produto a partir de uma foto do produto e o design de uma página web. Este guia reúne execuções reais numa assinatura Kling Pro, uma por recurso, com as requisições exatas, as imagens geradas e o custo de cada uma. Uma imagem 2K usou 4 créditos, cerca de US$ 0,04 no Pro. A API de desenvolvedor do próprio Kling vende a mesma imagem por US$ 0,06, em pacotes pré-pagos de imagens a partir de US$ 300. ### Antes de começar Você precisa de um [token da API](/docs/start-here/setup-useapi) da useapi.net e de uma conta do Kling conectada pelo [Setup Kling](/docs/start-here/setup-kling), num plano pago do Kling (Standard ou superior). 4K e 8K também exigem um plano pago. Exporte o token para que os exemplos com `curl` rodem sem alterações: ```bash export USEAPI_TOKEN="user:1234-..." # your useapi.net API token export KLING_EMAIL="you@example.com" # your connected Kling account ``` ### Kling Image 4.0 em resumo | Modo | Requisição | O que você recebe | Créditos | |---|---|---|---| | Imagem | `omni_version: v4` | de 1 a 9 imagens em 2K, 4K ou 8K, em qualquer uma de 9 proporções ou `auto` | 4 / 6 / 10 por imagem | | Series Mode | `story_mode: true` | de 2 a 10 imagens que contam uma história, ou quantas o Kling decidir | o mesmo, por imagem | | Presets | `@style:`, `@tone:`, `@font:` no prompt | um visual, uma gradação de cor ou um letreiro das listas do Kling | sem custo extra | | Página de produto | `skill: product_detail` + `image_1` | uma página longa a partir da foto do seu produto, curta, média ou longa | de 15 a 55 por página | | Web design | `skill: web_design` | o design de uma landing page longa | 35 em 1K, 38 em 2K | Até 10 imagens de referência e [elements](/docs/api-kling-v1/get-kling-elements) salvos funcionam como em qualquer requisição Omni: cite-os no prompt como `@image_1` ou `@element_1`. ### Gere uma imagem 8K em duas chamadas #### 1. Envie o job ```bash curl -s -X POST "https://api.useapi.net/v1/kling/images/omni" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$KLING_EMAIL"'", "omni_version": "v4", "resolution": "8k", "aspect_ratio": "16:9", "prompt": "Macro photograph of a hummingbird hovering at a red trumpet flower at sunrise, every iridescent feather sharp, dew drops on the petals, soft golden backlight, shallow depth of field" }' ``` A resposta é a nova tarefa, com o id em `task.id`: ```json { "task": { "id": 123456789012345, "type": "mmu_omni_image", "status": 5, "status_name": "submitted", "status_final": false } } ``` #### 2. Consulte o resultado Leia a tarefa com [GET tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) até `status_final` ser `true`. Cada imagem é um item de `works`, com a sua URL e o seu tamanho: ```bash curl -s "https://api.useapi.net/v1/kling/tasks/123456789012345?email=$KLING_EMAIL" \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{status_name, works: [.works[] | {url: .resource.resource, width: .resource.width, height: .resource.height}]}' ``` ```json { "status_name": "succeed", "works": [ { "url": "https://s15-kling.klingai.com/kimg/.../image.png", "width": 10880, "height": 6144 } ] } ``` A nossa execução gerou uma imagem de 10880 x 6144, 67 megapixels, e usou 6 créditos. O preço de tabela do 8K é 10 créditos, e o Kling cobrou 6 por causa de uma promoção naquele dia. A mesma requisição com `"resolution": "2k"` gera uma imagem de 2720 x 1536 por 4 créditos, e com `"4k"`, uma de 5440 x 3072 por 6. <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-8k-hummingbird.jpg" alt="Kling Image 4.0 em 8K: um beija-flor numa flor vermelha em forma de trombeta ao nascer do sol" loading="lazy" style="width:100%"> Kling Image 4.0, `8k`, `16:9`, 10880 x 6144, 6 créditos. Exibida menor aqui: abra o [original](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-8k-hummingbird-original.png) (PNG de 10880 x 6144, 3,5 MB) para vê-la em 8K completo. No tamanho real, o detalhe do 8K se sustenta. Este é um recorte de 1600 x 900 do mesmo arquivo, sem redimensionar: <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-8k-hummingbird-crop-100.jpg" alt="Recorte em 100% da imagem 8K: o olho e as penas do beija-flor" loading="lazy" style="width:100%"> A mesma imagem em 100%, a cabeça do pássaro. ### Series Mode: uma história a partir de um prompt `story_mode: true` gera uma série de imagens que combinam entre si: os mesmos personagens, o mesmo estilo e a mesma luz de um quadro para o outro. O Kling Image 4.0 cria a série só a partir do prompt, sem imagem de referência. Defina `imageCount` de 2 a 10, ou deixe de fora e o Kling decide quantas imagens a história precisa. ```bash curl -s -X POST "https://api.useapi.net/v1/kling/images/omni" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$KLING_EMAIL"'", "omni_version": "v4", "story_mode": true, "aspect_ratio": "4:3", "prompt": "A picture-book story in consistent watercolor style: a small paper boat is folded by a child on a rainy city street, floats down the gutter, slips into a river past old bridges, and finally reaches the open sea at sunset" }' ``` O Kling escolheu 6 imagens para esta história, cada uma com 2336 x 1760, e cobrou 4 créditos por imagem, 24 no total. <div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(220px,1fr));gap:8px"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-1.jpg" alt="Series Mode 1 de 6: uma criança dobra um barquinho de papel numa rua chuvosa" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-2.jpg" alt="Series Mode 2 de 6: o barquinho desce pela sarjeta" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-3.jpg" alt="Series Mode 3 de 6: o barquinho num canal da cidade" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-4.jpg" alt="Series Mode 4 de 6: o barquinho passa sob uma ponte antiga" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-5.jpg" alt="Series Mode 5 de 6: o barquinho num rio largo" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-6.jpg" alt="Series Mode 6 de 6: o barquinho chega ao mar ao pôr do sol" loading="lazy" style="width:100%"> </div> Kling Image 4.0 em Series Mode, `story_mode: true`, sem `imageCount`, 6 imagens, 24 créditos. Originais, PNG de 2336 x 1760: [1](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-1-original.png), [2](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-2-original.png), [3](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-3-original.png), [4](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-4-original.png), [5](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-5-original.png), [6](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-6-original.png). ### Estilos, tons e fontes O Kling Image 4.0 tem três tipos de presets, e você os cita no prompt. [GET images/presets](/docs/api-kling-v1/get-kling-images-presets) lista todos com os seus ids e uma imagem de exemplo: 98 estilos, 16 tons e 76 fontes em inglês, japonês, coreano e chinês. ```bash curl -s "https://api.useapi.net/v1/kling/images/presets" -H "Authorization: Bearer $USEAPI_TOKEN" \ | jq '{styles: [.styles[0:3][] | .id], tones: [.tones[] | .id], fonts: [.fonts[] | select(.languages | index("en")) | .id][0:5]}' ``` - Um tom (`@tone:<id>`) aplica uma das gradações de cor e luz do Kling: estilos de diretores, visuais de câmera e paletas. - Uma fonte (`@font:<id>`) define o lettering do texto entre aspas que vem logo depois dela. - Um estilo (`@style:<id>`) define o visual geral: 3D, 2D, artesanato com materiais ou estilos de fotografia. Esta é a mesma cena sem tom e com `@tone:Nostalgic_Wuxia`, 4 créditos cada: <div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(280px,1fr));gap:8px"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-tone-none-swordsman.jpg" alt="Sem tom: um espadachim numa floresta de bambu ao amanhecer" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-tone-nostalgic-wuxia-swordsman.jpg" alt="@tone:Nostalgic_Wuxia: a mesma cena com a gradação quente e desbotada de um filme wuxia" loading="lazy" style="width:100%"> </div> À esquerda: `A lone swordsman in a bamboo forest at dawn, mist between the stalks, wide cinematic shot`. À direita: o mesmo prompt depois de `@tone:Nostalgic_Wuxia`. Originais, PNG de 2720 x 1536: [sem tom](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-tone-none-swordsman-original.png), [Nostalgic Wuxia](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-tone-nostalgic-wuxia-swordsman-original.png). E uma placa de loja sem fonte e com `@font:elegant_brush_hand`. Coloque entre aspas as palavras que devem aparecer na imagem, com a fonte logo antes delas: ```json { "prompt": "A cozy corner coffee shop at night, warm light spilling onto a wet cobblestone street, a hand-painted shop sign above the door that reads @font:elegant_brush_hand \"Moonlight Roasters\"" } ``` <div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(280px,1fr));gap:8px"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-font-none-coffee-sign.jpg" alt="Sem fonte: a placa numa fonte serifada simples" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-font-elegant-brush-hand-coffee-sign.jpg" alt="@font:elegant_brush_hand: a placa em letra de pincel" loading="lazy" style="width:100%"> </div> À esquerda: sem fonte. À direita: `@font:elegant_brush_hand "Moonlight Roasters"`. Originais, PNG de 2496 x 1664: [sem fonte](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-font-none-coffee-sign-original.png), [fonte de pincel](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-font-elegant-brush-hand-coffee-sign-original.png). <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-style-3d-cartoon-corgi-astronaut.jpg" alt="@style:3d_cartoon_with_exaggerated_perspective_pro: um corgi astronauta num planeta cor de bala" loading="lazy" style="width:60%"> `@style:3d_cartoon_with_exaggerated_perspective_pro A corgi astronaut stepping out of a tiny rocket onto a candy-colored planet, looking up at the camera`, `1:1`, 4 créditos. [Original](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-style-3d-cartoon-corgi-astronaut-original.png) (PNG de 2048 x 2048, 8,5 MB). Um id desconhecido recebe um `400` antes de qualquer coisa chegar ao Kling, então um erro de digitação nunca custa créditos. ### Imagens de referência Cite uma referência no prompt como `@image_1`. Primeiro geramos uma foto de produto, depois usamos a URL dela como `image_1` numa foto publicitária em 4K. O produto, o rótulo e a tampa de bambu se mantêm: ```json { "omni_version": "v4", "resolution": "4k", "aspect_ratio": "16:9", "prompt": "The bottle from @image_1 standing on a mossy rock beside a mountain stream, morning mist, outdoor adventure ad", "image_1": "https://s15-kling.klingai.com/kimg/.../bottle.png" } ``` <div style="display:grid;grid-template-columns:1fr 2fr;gap:8px;align-items:start"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-product-photo-bottle.jpg" alt="A foto do produto: uma garrafa de aço verde-sálvia com tampa de bambu" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-4k-reference-bottle-stream.jpg" alt="4K com a foto do produto como referência: a garrafa ao lado de um riacho na montanha" loading="lazy" style="width:100%"> </div> À esquerda: a foto do produto, `3:4`, 4 créditos. À direita: `4k` com ela como `@image_1`, 5440 x 3072, 6 créditos. Originais: [foto do produto](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-product-photo-bottle-original.png) (PNG de 1760 x 2336, 4,8 MB), [foto publicitária 4K](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-4k-reference-bottle-stream-original.png) (PNG de 5440 x 3072, 24 MB). Para enviar a sua própria foto, use [POST assets](/docs/api-kling-v1/post-kling-assets) e passe a URL que ele retorna. ### Páginas de produto `skill: product_detail` transforma uma foto de produto numa página de produto longa: destaque principal, diferenciais, closes e uma tabela de especificações, tudo diagramado numa única imagem. `image_1` é a foto, `prompt` diz o que o produto faz e `length` define o número de seções: `short` (2 a 5), `medium` (6 a 10) ou `long` (11 a 18). ```bash curl -s -X POST "https://api.useapi.net/v1/kling/images/omni" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$KLING_EMAIL"'", "omni_version": "v4", "skill": "product_detail", "length": "short", "resolution": "2k", "image_1": "https://s15-kling.klingai.com/kimg/.../bottle.png", "prompt": "Insulated steel water bottle \"Trailhead\": keeps drinks cold 24 hours and hot 12, leak-proof bamboo lid, fits car cup holders, 750 ml, three colors" }' ``` A página voltou como uma única imagem de 2048 x 13408 por 18 créditos. Uma página `medium` em 1K saiu com 1024 x 9936 por 30 créditos. <div style="max-height:900px;overflow-y:auto;border:1px solid #ddd"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-product-detail-page-2k-short.jpg" alt="Página de produto do Kling Image 4.0: garrafa Trailhead verde-sálvia, diferenciais e especificações" loading="lazy" style="width:100%"> </div> `skill: product_detail`, `length: short`, `2k`, 2048 x 13408, 18 créditos. Role o quadro para ver a página inteira, ou abra o [original](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-product-detail-page-2k-short-original.png) (PNG, 1,3 MB). ### Designs de páginas web `skill: web_design` gera o design de uma landing page como uma única imagem longa. `image_1` é opcional: uma imagem cujo estilo a página deve seguir. O Kling escreve o texto da página em chinês, a menos que o prompt indique o idioma, então termine o prompt com o idioma que você quer: ```bash curl -s -X POST "https://api.useapi.net/v1/kling/images/omni" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$KLING_EMAIL"'", "omni_version": "v4", "skill": "web_design", "resolution": "1k", "prompt": "Landing page for \"Ember & Oak\", a small-batch coffee roaster: warm browns and cream, elegant serif headlines, hero photo of a pour-over, three featured roasts, a monthly subscription offer and customer reviews. All text on the page in English." }' ``` <div style="max-height:900px;overflow-y:auto;border:1px solid #ddd"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-web-design-1k-english.jpg" alt="Web design do Kling Image 4.0: landing page da torrefação Ember & Oak em inglês" loading="lazy" style="width:100%"> </div> `skill: web_design`, `1k`, 1024 x 5376, 35 créditos. Role o quadro para ver a página inteira, ou abra o [original](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-web-design-1k-english-original.png) (PNG, 0,7 MB). Sem a última frase, o mesmo prompt em 2K gerou a página em chinês (2048 x 8514, 38 créditos), e o mesmo aconteceu com um web design feito no app do Kling: <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-web-design-2k-chinese-top.jpg" alt="O mesmo prompt de web design sem idioma: o texto da página está em chinês" loading="lazy" style="width:100%"> O topo da página sem "All text on the page in English." A página inteira: [original](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-web-design-2k-chinese-original.png) (PNG de 2048 x 8514, 1,4 MB). ### Quanto custa O Kling Image 4.0 usa os créditos da sua assinatura do Kling AI, os mesmos em todos os planos. A API de desenvolvedor do Kling o vende em pacotes de imagens próprios, o menor por US$ 300 com 78.216 unidades (US$ 0,00384 por unidade, válido por 180 dias), e ainda cobra 0,8 unidade por imagem de referência ou element. Pela useapi.net, as referências não custam nada a mais. | Modelo | [API oficial](https://kling.ai/dev/pricing) | Premier $80,96/mês (8.000 cr/mês) | Pro $32,56/mês (3.000 cr/mês) | Standard $8,80/mês (660 cr/mês) | |---|---|---|---|---| | Kling Image 4.0 (2K) | $0,06 (16 unidades) | $0,04 / 4 cr (2.000 imagens/mês) | $0,04 / 4 cr (750 imagens/mês) | $0,05 / 4 cr (165 imagens/mês) | | Kling Image 4.0 (4K) | $0,09 (24 unidades) | $0,06 / 6 cr (1.333 imagens/mês) | $0,07 / 6 cr (500 imagens/mês) | $0,08 / 6 cr (110 imagens/mês) | | Kling Image 4.0 (8K) | $0,15 (40 unidades) | $0,10 / 10 cr (800 imagens/mês) | $0,11 / 10 cr (300 imagens/mês) | $0,13 / 10 cr (66 imagens/mês) | | Página de produto (2K, curta) | $0,28 (72 unidades) | $0,18 / 18 cr (444 páginas/mês) | $0,20 / 18 cr (166 páginas/mês) | $0,24 / 18 cr (36 páginas/mês) | | Página de produto (2K, longa) | $0,84 (220 unidades) | $0,56 / 55 cr (145 páginas/mês) | $0,60 / 55 cr (54 páginas/mês) | $0,73 / 55 cr (12 páginas/mês) | | Web design (2K) | $0,58 (152 unidades) | $0,38 / 38 cr (210 páginas/mês) | $0,41 / 38 cr (78 páginas/mês) | $0,51 / 38 cr (17 páginas/mês) | Preços em dólares americanos, em 19 de novembro de 2026. Os preços do Kling para todos os planos estão na [calculadora de preços do Kling](/docs/api-kling-v1#pricing). Toda a nossa execução para este guia, 13 jobs que geraram 18 imagens e páginas, usou 181 créditos, cerca de US$ 1,96 no Pro. ### Gere em lote com o script O [exemplo image-4](https://github.com/useapi/kling-api/tree/main/image-4) no nosso repositório do GitHub lê uma lista de prompts do `prompts.json` (os prompts deste guia), envia cada um, espera o resultado e baixa todas as imagens: ```bash git clone https://github.com/useapi/kling-api.git cd kling-api/image-4 node ./kling-image-4.mjs $USEAPI_TOKEN $KLING_EMAIL ``` Ele confere cada prompt antes de gastar créditos: uma página de produto precisa de `image_1`, uma skill gera em 1K ou 2K, e `length` só funciona com `product_detail`. ### O mesmo a partir de um assistente de IA O [servidor MCP do Kling](/docs/api-kling-v1/mcp) hospedado em `https://api.useapi.net/v1/kling/mcp` dá ao Claude Code, ao Cursor, ao VS Code e ao app do Claude as mesmas chamadas: `kling_omni_image` com `omni_version: v4`, e `kling_list_image_presets` para os ids de estilo, tom e fonte. Peça "uma foto 8K de…" ou "uma página de produto a partir desta foto" e o assistente monta a requisição. ### Perguntas frequentes **Existe uma API do Kling Image 4.0?** Sim. A useapi.net roda o Kling Image 4.0 na sua assinatura do Kling AI por meio de [POST images/omni](/docs/api-kling-v1/post-kling-images-omni) com `omni_version: v4`: 8K, Series Mode, presets, páginas de produto e web designs, por 4 créditos a imagem 2K, cerca de US$ 0,04 no Kling Pro. A API de desenvolvedor do próprio Kling também vende o modelo, a US$ 0,06 a imagem 2K em pacotes pré-pagos a partir de US$ 300, mais uma taxa por imagem de referência. Pela assinatura, sai cerca de 30% mais barato (em 19 de novembro de 2026). **Como gero uma imagem 8K no Kling?** Envie `"omni_version": "v4", "resolution": "8k"` para [POST images/omni](/docs/api-kling-v1/post-kling-images-omni) num plano pago do Kling. A nossa execução em 16:9 voltou com 10880 x 6144 por 10 créditos no preço de tabela (US$ 0,11 no Kling Pro), e o Kling cobrou 6 durante a promoção. A API de desenvolvedor do Kling cobra US$ 0,15 pela mesma imagem 8K. **Por que o meu web design do Kling sai em chinês?** O Kling Image 4.0 escreve o texto de uma página `web_design` em chinês, a menos que o prompt indique o idioma, tanto no app do Kling quanto pela API. Termine o prompt com "All text on the page in English." A nossa página em inglês voltou em 1K por 35 créditos. **Quais presets posso usar?** [GET images/presets](/docs/api-kling-v1/get-kling-images-presets) lista os 98 estilos, 16 tons e 76 fontes atuais do Kling, com ids e exemplos, iguais para todas as contas. Cite-os num prompt `v4` como `@style:<id>`, `@tone:<id>` e `@font:<id>` antes do texto entre aspas. Eles não custam créditos a mais. ### Conclusão O Kling Image 4.0 está a uma requisição de distância, na assinatura que você já tem: `omni_version: v4` em [POST images/omni](/docs/api-kling-v1/post-kling-images-omni), de uma imagem 2K de 4 créditos a uma foto 8K de 67 megapixels, uma história em seis quadros ou uma página de produto completa. Comece pela documentação da [API do Kling](/docs/api-kling-v1), ou rode o [script image-4](https://github.com/useapi/kling-api/tree/main/image-4) com os prompts acima. === URL: https://useapi.net/docs/articles/kling-image-4-api-th === Document URL: https://useapi.net/docs/articles/kling-image-4-api-th --- layout: default title: วิธีสร้างภาพ Kling Image 4.0 ผ่าน Kling API seo_title: "Kling Image 4.0 API: ภาพ 8K, Series Mode และหน้าสินค้า" description: "สร้างภาพ Kling Image 4.0 จากโค้ดบนแพ็กเกจ Kling AI ของคุณ: ภาพ 8K เรื่องราวแบบ Series Mode พรีเซ็ตสไตล์ โทนสี และฟอนต์ หน้ารายละเอียดสินค้า และดีไซน์เว็บ พร้อมผลรันจริงและค่าใช้จ่าย" keywords: [Kling Image 4.0 API, Kling Image 4 API, API สร้างภาพ Kling Image 4.0, ภาพ 8K Kling, Kling 8K image, Kling Series Mode, หน้ารายละเอียดสินค้า Kling, ดีไซน์เว็บ Kling, พรีเซ็ตภาพ Kling, Kling Omni image, Kling API, Kling AI API, API สร้างภาพ AI, Kuaishou, Kling MCP server, สอนใช้งาน, curl] image: https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-8k-hummingbird.jpg parent: Articles nav_exclude: true lang: th translation_key: kling-image-4-api date: 2026-11-19 last_modified: 2026-11-19 nav_order: 856 repo: https://github.com/useapi/kling-api --- ## วิธีสร้างภาพ Kling Image 4.0 ผ่าน Kling API {: .no_toc #how-to-generate-kling-image-40-images-via-the-kling-api } อ่าน 6 นาที • 19 พฤศจิกายน 2026 ## สารบัญ {: .no_toc .text-delta #table-of-contents } ### บทนำ Kling Image 4.0 คือโมเดลสร้างภาพตัวใหม่ของ Kuaishou และ Kling API ของ useapi.net รันโมเดลนี้บน[แพ็กเกจสมาชิกเว็บไซต์ Kling AI](https://kling.ai/app/membership/membership-plan) ของคุณ เพียงส่ง `"omni_version": "v4"` ไปที่ [POST images/omni](/docs/api-kling-v1/post-kling-images-omni) endpoint เดียวนี้ทำได้ทุกอย่างที่แอป Kling ทำกับโมเดลนี้ ได้แก่ ภาพความละเอียดสูงสุด 8K เรื่องราวแบบ Series Mode ที่มีภาพเข้าชุดกัน 2 ถึง 10 ภาพ พรีเซ็ตสไตล์ โทนสี และฟอนต์ที่ระบุในพรอมต์ และสกิลออกแบบอีกสองแบบที่แต่ละแบบสร้างภาพหน้ายาวหนึ่งภาพ คือหน้ารายละเอียดสินค้าจากภาพถ่ายสินค้า และดีไซน์หน้าเว็บ คู่มือนี้รวบรวมการรันจริงบนแพ็กเกจ Kling Pro ฟีเจอร์ละหนึ่งครั้ง พร้อม request ที่ใช้จริง ภาพที่ได้ และค่าใช้จ่ายของแต่ละงาน ภาพ 2K หนึ่งภาพใช้ 4 เครดิต หรือราว $0.04 บน Pro ขณะที่ API สำหรับนักพัฒนาของ Kling เองขายภาพเดียวกันที่ $0.06 ในแพ็กภาพแบบจ่ายล่วงหน้าที่เริ่มต้น $300 ### ก่อนเริ่มต้น คุณต้องมี [API token](/docs/start-here/setup-useapi) ของ useapi.net และบัญชี Kling ที่เชื่อมต่อผ่าน [Setup Kling](/docs/start-here/setup-kling) แล้ว โดยใช้แพ็กเกจ Kling แบบเสียเงิน (Standard ขึ้นไป) ภาพ 4K และ 8K ก็ต้องใช้แพ็กเกจเสียเงินเช่นกัน export token ไว้ก่อน เพื่อให้ตัวอย่าง `curl` รันได้ทันที: ```bash export USEAPI_TOKEN="user:1234-..." # your useapi.net API token export KLING_EMAIL="you@example.com" # your connected Kling account ``` ### Kling Image 4.0 โดยสรุป | โหมด | Request | สิ่งที่ได้ | เครดิต | |---|---|---|---| | ภาพ | `omni_version: v4` | 1 ถึง 9 ภาพที่ 2K, 4K หรือ 8K เลือกได้ 9 อัตราส่วนภาพ หรือ `auto` | 4 / 6 / 10 ต่อภาพ | | Series Mode | `story_mode: true` | 2 ถึง 10 ภาพที่เล่าเรื่องเดียวกัน หรือตามจำนวนที่ Kling เลือกให้ | เท่ากัน คิดต่อภาพ | | พรีเซ็ต | `@style:`, `@tone:`, `@font:` ในพรอมต์ | ลุค เกรดสี หรือตัวอักษรจากรายการของ Kling | ไม่มีค่าใช้จ่ายเพิ่ม | | หน้ารายละเอียดสินค้า | `skill: product_detail` + `image_1` | หน้ายาวหนึ่งหน้าจากภาพถ่ายสินค้าของคุณ แบบสั้น กลาง หรือยาว | 15 ถึง 55 ต่อหน้า | | ดีไซน์เว็บ | `skill: web_design` | ดีไซน์แลนดิ้งเพจยาวหนึ่งหน้า | 35 ที่ 1K, 38 ที่ 2K | ภาพอ้างอิงสูงสุด 10 ภาพ และ[อิลิเมนต์](/docs/api-kling-v1/get-kling-elements)ที่บันทึกไว้ ใช้ได้เหมือนใน request แบบ Omni ทุกตัว: ระบุชื่อในพรอมต์เป็น `@image_1` หรือ `@element_1` ### สร้างภาพ 8K ด้วยการเรียกสองครั้ง #### 1. ส่งงาน ```bash curl -s -X POST "https://api.useapi.net/v1/kling/images/omni" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$KLING_EMAIL"'", "omni_version": "v4", "resolution": "8k", "aspect_ratio": "16:9", "prompt": "Macro photograph of a hummingbird hovering at a red trumpet flower at sunrise, every iridescent feather sharp, dew drops on the petals, soft golden backlight, shallow depth of field" }' ``` คำตอบคืองานใหม่ โดยมี id อยู่ใน `task.id`: ```json { "task": { "id": 123456789012345, "type": "mmu_omni_image", "status": 5, "status_name": "submitted", "status_final": false } } ``` #### 2. ตรวจสถานะจนได้ผลลัพธ์ อ่านงานด้วย [GET tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) ไปจนกว่า `status_final` จะเป็น `true` ภาพแต่ละภาพคือหนึ่งรายการใน `works` พร้อม URL และขนาดภาพ: ```bash curl -s "https://api.useapi.net/v1/kling/tasks/123456789012345?email=$KLING_EMAIL" \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{status_name, works: [.works[] | {url: .resource.resource, width: .resource.width, height: .resource.height}]}' ``` ```json { "status_name": "succeed", "works": [ { "url": "https://s15-kling.klingai.com/kimg/.../image.png", "width": 10880, "height": 6144 } ] } ``` การรันของเราได้ภาพขนาด 10880 x 6144 หรือ 67 เมกะพิกเซล และใช้ 6 เครดิต ราคาปกติของ 8K คือ 10 เครดิต แต่วันนั้น Kling คิดเพียง 6 เครดิตเพราะมีโปรโมชันลดราคา request เดียวกันที่ใช้ `"resolution": "2k"` จะได้ภาพ 2720 x 1536 ในราคา 4 เครดิต และ `"4k"` ได้ภาพ 5440 x 3072 ในราคา 6 เครดิต <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-8k-hummingbird.jpg" alt="Kling Image 4.0 8K: นกฮัมมิงเบิร์ดที่ดอกไม้รูปแตรสีแดงยามพระอาทิตย์ขึ้น" loading="lazy" style="width:100%"> Kling Image 4.0, `8k`, `16:9`, 10880 x 6144, 6 เครดิต ภาพที่แสดงตรงนี้ถูกย่อลง เปิด[ต้นฉบับ](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-8k-hummingbird-original.png) (PNG 10880 x 6144, 3.5 MB) เพื่อดูภาพ 8K เต็มขนาด เมื่อดูเต็มขนาด รายละเอียดของภาพ 8K ยังคมชัดอยู่ นี่คือภาพครอปขนาด 1600 x 900 จากไฟล์เดียวกัน โดยไม่ได้ย่อหรือขยาย: <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-8k-hummingbird-crop-100.jpg" alt="ภาพครอป 100% จากภาพ 8K: ดวงตาและขนของนกฮัมมิงเบิร์ด" loading="lazy" style="width:100%"> ภาพเดียวกันที่ 100% ส่วนหัวของนก ### Series Mode: เรื่องราวจากพรอมต์เดียว `story_mode: true` สร้างชุดภาพที่เข้ากัน ตัวละคร สไตล์ และแสงจะเหมือนกันทุกภาพ Kling Image 4.0 สร้างซีรีส์ได้จากพรอมต์อย่างเดียว ไม่ต้องมีภาพอ้างอิง ตั้ง `imageCount` เป็น 2 ถึง 10 หรือไม่ใส่ก็ได้ แล้ว Kling จะเลือกเองว่าเรื่องนี้ต้องใช้กี่ภาพ ```bash curl -s -X POST "https://api.useapi.net/v1/kling/images/omni" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$KLING_EMAIL"'", "omni_version": "v4", "story_mode": true, "aspect_ratio": "4:3", "prompt": "A picture-book story in consistent watercolor style: a small paper boat is folded by a child on a rainy city street, floats down the gutter, slips into a river past old bridges, and finally reaches the open sea at sunset" }' ``` Kling เลือก 6 ภาพสำหรับเรื่องนี้ ภาพละ 2336 x 1760 และคิดภาพละ 4 เครดิต รวม 24 เครดิต <div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(220px,1fr));gap:8px"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-1.jpg" alt="Series Mode ภาพที่ 1 จาก 6: เด็กพับเรือกระดาษบนถนนที่ฝนตก" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-2.jpg" alt="Series Mode ภาพที่ 2 จาก 6: เรือลอยไปตามรางน้ำข้างถนน" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-3.jpg" alt="Series Mode ภาพที่ 3 จาก 6: เรือในคลองกลางเมือง" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-4.jpg" alt="Series Mode ภาพที่ 4 จาก 6: เรือลอดใต้สะพานเก่า" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-5.jpg" alt="Series Mode ภาพที่ 5 จาก 6: เรือบนแม่น้ำกว้าง" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-6.jpg" alt="Series Mode ภาพที่ 6 จาก 6: เรือออกสู่ทะเลยามพระอาทิตย์ตก" loading="lazy" style="width:100%"> </div> Kling Image 4.0 Series Mode, `story_mode: true`, ไม่ใส่ `imageCount`, 6 ภาพ, 24 เครดิต ต้นฉบับ PNG 2336 x 1760: [1](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-1-original.png), [2](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-2-original.png), [3](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-3-original.png), [4](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-4-original.png), [5](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-5-original.png), [6](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-6-original.png) ### สไตล์ โทนสี และฟอนต์ Kling Image 4.0 มีพรีเซ็ตสามประเภท และคุณระบุชื่อพรีเซ็ตไว้ในพรอมต์ [GET images/presets](/docs/api-kling-v1/get-kling-images-presets) แสดงรายการทั้งหมดพร้อม id และภาพตัวอย่าง ได้แก่ 98 สไตล์ 16 โทนสี และ 76 ฟอนต์ ในภาษาอังกฤษ ญี่ปุ่น เกาหลี และจีน ```bash curl -s "https://api.useapi.net/v1/kling/images/presets" -H "Authorization: Bearer $USEAPI_TOKEN" \ | jq '{styles: [.styles[0:3][] | .id], tones: [.tones[] | .id], fonts: [.fonts[] | select(.languages | index("en")) | .id][0:5]}' ``` - โทนสี (`@tone:<id>`) ใช้เกรดสีและแสงแบบหนึ่งของ Kling เช่น สไตล์ผู้กำกับ ลุคของกล้อง และพาเลตสี - ฟอนต์ (`@font:<id>`) กำหนดรูปแบบตัวอักษรของข้อความในเครื่องหมายคำพูดที่ตามหลังมา - สไตล์ (`@style:<id>`) กำหนดลุคโดยรวม เช่น สไตล์ 3D, 2D งานฝีมือจากวัสดุ หรือภาพถ่าย นี่คือฉากเดียวกันแบบไม่มีโทนสี และแบบใช้ `@tone:Nostalgic_Wuxia` ภาพละ 4 เครดิต: <div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(280px,1fr));gap:8px"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-tone-none-swordsman.jpg" alt="ไม่มีโทนสี: นักดาบในป่าไผ่ยามรุ่งสาง" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-tone-nostalgic-wuxia-swordsman.jpg" alt="@tone:Nostalgic_Wuxia: ฉากเดียวกันในเกรดสีหนังกำลังภายในโทนอุ่นและซีดจาง" loading="lazy" style="width:100%"> </div> ซ้าย: `A lone swordsman in a bamboo forest at dawn, mist between the stalks, wide cinematic shot` ขวา: พรอมต์เดียวกันโดยมี `@tone:Nostalgic_Wuxia` นำหน้า ต้นฉบับ PNG 2720 x 1536: [ไม่มีโทนสี](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-tone-none-swordsman-original.png), [Nostalgic Wuxia](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-tone-nostalgic-wuxia-swordsman-original.png) และป้ายร้านแบบไม่มีฟอนต์ กับแบบใช้ `@font:elegant_brush_hand` ใส่คำที่ต้องการให้อยู่ในภาพไว้ในเครื่องหมายคำพูด แล้ววางฟอนต์ไว้ข้างหน้าคำนั้นทันที: ```json { "prompt": "A cozy corner coffee shop at night, warm light spilling onto a wet cobblestone street, a hand-painted shop sign above the door that reads @font:elegant_brush_hand \"Moonlight Roasters\"" } ``` <div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(280px,1fr));gap:8px"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-font-none-coffee-sign.jpg" alt="ไม่มีฟอนต์: ป้ายเป็นตัวอักษรแบบ serif ธรรมดา" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-font-elegant-brush-hand-coffee-sign.jpg" alt="@font:elegant_brush_hand: ป้ายเป็นตัวเขียนลายพู่กัน" loading="lazy" style="width:100%"> </div> ซ้าย: ไม่มีฟอนต์ ขวา: `@font:elegant_brush_hand "Moonlight Roasters"` ต้นฉบับ PNG 2496 x 1664: [ไม่มีฟอนต์](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-font-none-coffee-sign-original.png), [ฟอนต์พู่กัน](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-font-elegant-brush-hand-coffee-sign-original.png) <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-style-3d-cartoon-corgi-astronaut.jpg" alt="@style:3d_cartoon_with_exaggerated_perspective_pro: คอร์กี้นักบินอวกาศบนดาวเคราะห์สีลูกกวาด" loading="lazy" style="width:60%"> `@style:3d_cartoon_with_exaggerated_perspective_pro A corgi astronaut stepping out of a tiny rocket onto a candy-colored planet, looking up at the camera`, `1:1`, 4 เครดิต [ต้นฉบับ](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-style-3d-cartoon-corgi-astronaut-original.png) (PNG 2048 x 2048, 8.5 MB) id ที่ไม่มีอยู่จริงจะได้ `400` ก่อนที่ request จะไปถึง Kling การพิมพ์ผิดจึงไม่ทำให้เสียเครดิต ### ภาพอ้างอิง ระบุภาพอ้างอิงในพรอมต์เป็น `@image_1` เราสร้างภาพถ่ายสินค้าขึ้นก่อน แล้วใช้ URL ของภาพนั้นเป็น `image_1` เพื่อทำภาพโฆษณา 4K ตัวสินค้า ฉลาก และฝาไม้ไผ่ยังคงเหมือนเดิม: ```json { "omni_version": "v4", "resolution": "4k", "aspect_ratio": "16:9", "prompt": "The bottle from @image_1 standing on a mossy rock beside a mountain stream, morning mist, outdoor adventure ad", "image_1": "https://s15-kling.klingai.com/kimg/.../bottle.png" } ``` <div style="display:grid;grid-template-columns:1fr 2fr;gap:8px;align-items:start"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-product-photo-bottle.jpg" alt="ภาพถ่ายสินค้า: ขวดเหล็กสีเขียวเสจพร้อมฝาไม้ไผ่" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-4k-reference-bottle-stream.jpg" alt="ภาพ 4K ที่ใช้ภาพถ่ายสินค้าเป็นภาพอ้างอิง: ขวดข้างลำธารบนภูเขา" loading="lazy" style="width:100%"> </div> ซ้าย: ภาพถ่ายสินค้า `3:4`, 4 เครดิต ขวา: `4k` โดยใช้ภาพนั้นเป็น `@image_1`, 5440 x 3072, 6 เครดิต ต้นฉบับ: [ภาพถ่ายสินค้า](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-product-photo-bottle-original.png) (PNG 1760 x 2336, 4.8 MB), [ภาพโฆษณา 4K](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-4k-reference-bottle-stream-original.png) (PNG 5440 x 3072, 24 MB) ถ้าต้องการอัปโหลดภาพของคุณเอง ใช้ [POST assets](/docs/api-kling-v1/post-kling-assets) แล้วส่ง URL ที่ได้กลับมา ### หน้ารายละเอียดสินค้า `skill: product_detail` เปลี่ยนภาพถ่ายสินค้าหนึ่งภาพให้เป็นหน้าสินค้าแบบยาว มีภาพหลัก จุดเด่น ภาพระยะใกล้ และตารางสเปก จัดวางอยู่ในภาพเดียว `image_1` คือภาพถ่าย `prompt` บอกว่าสินค้าทำอะไรได้ และ `length` กำหนดจำนวนส่วนของหน้า ได้แก่ `short` (2 ถึง 5), `medium` (6 ถึง 10) หรือ `long` (11 ถึง 18) ```bash curl -s -X POST "https://api.useapi.net/v1/kling/images/omni" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$KLING_EMAIL"'", "omni_version": "v4", "skill": "product_detail", "length": "short", "resolution": "2k", "image_1": "https://s15-kling.klingai.com/kimg/.../bottle.png", "prompt": "Insulated steel water bottle \"Trailhead\": keeps drinks cold 24 hours and hot 12, leak-proof bamboo lid, fits car cup holders, 750 ml, three colors" }' ``` หน้านี้กลับมาเป็นภาพเดียวขนาด 2048 x 13408 ในราคา 18 เครดิต ส่วนหน้าแบบ `medium` ที่ 1K ได้ขนาด 1024 x 9936 ในราคา 30 เครดิต <div style="max-height:900px;overflow-y:auto;border:1px solid #ddd"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-product-detail-page-2k-short.jpg" alt="หน้ารายละเอียดสินค้าจาก Kling Image 4.0: ขวด Trailhead สี Sage Green พร้อมจุดเด่นและสเปก" loading="lazy" style="width:100%"> </div> `skill: product_detail`, `length: short`, `2k`, 2048 x 13408, 18 เครดิต เลื่อนภายในกรอบเพื่อดูทั้งหน้า หรือเปิด[ต้นฉบับ](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-product-detail-page-2k-short-original.png) (PNG, 1.3 MB) ### ดีไซน์หน้าเว็บ `skill: web_design` สร้างดีไซน์แลนดิ้งเพจเป็นภาพยาวหนึ่งภาพ `image_1` จะใส่หรือไม่ก็ได้ เป็นภาพที่ต้องการให้หน้าเว็บทำตามสไตล์ Kling จะเขียนข้อความบนหน้าเป็นภาษาจีน เว้นแต่พรอมต์จะระบุภาษาไว้ จึงควรปิดท้ายพรอมต์ด้วยภาษาที่คุณต้องการ: ```bash curl -s -X POST "https://api.useapi.net/v1/kling/images/omni" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$KLING_EMAIL"'", "omni_version": "v4", "skill": "web_design", "resolution": "1k", "prompt": "Landing page for \"Ember & Oak\", a small-batch coffee roaster: warm browns and cream, elegant serif headlines, hero photo of a pour-over, three featured roasts, a monthly subscription offer and customer reviews. All text on the page in English." }' ``` <div style="max-height:900px;overflow-y:auto;border:1px solid #ddd"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-web-design-1k-english.jpg" alt="ดีไซน์เว็บจาก Kling Image 4.0: แลนดิ้งเพจร้านคั่วกาแฟ Ember & Oak เป็นภาษาอังกฤษ" loading="lazy" style="width:100%"> </div> `skill: web_design`, `1k`, 1024 x 5376, 35 เครดิต เลื่อนภายในกรอบเพื่อดูทั้งหน้า หรือเปิด[ต้นฉบับ](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-web-design-1k-english-original.png) (PNG, 0.7 MB) ถ้าไม่มีประโยคสุดท้าย พรอมต์เดียวกันที่ 2K ได้หน้าเป็นภาษาจีน (2048 x 8514, 38 เครดิต) และดีไซน์เว็บที่สร้างในแอป Kling ก็เป็นภาษาจีนเช่นกัน: <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-web-design-2k-chinese-top.jpg" alt="พรอมต์ดีไซน์เว็บเดียวกันแบบไม่ระบุภาษา: ข้อความบนหน้าเป็นภาษาจีน" loading="lazy" style="width:100%"> ส่วนบนของหน้าเมื่อไม่มีประโยค "All text on the page in English." ดูทั้งหน้าได้ที่[ต้นฉบับ](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-web-design-2k-chinese-original.png) (PNG 2048 x 8514, 1.4 MB) ### ค่าใช้จ่าย Kling Image 4.0 ใช้เครดิตจากแพ็กเกจ Kling AI ของคุณ ในอัตราเดียวกันทุกแพ็กเกจ API สำหรับนักพัฒนาของ Kling ขายโมเดลนี้ในแพ็กภาพของตัวเอง แพ็กเล็กที่สุดราคา $300 ได้ 78,216 หน่วย ($0.00384 ต่อหน่วย ใช้ได้ 180 วัน) และยังคิดเพิ่ม 0.8 หน่วยต่อภาพอ้างอิงหรืออิลิเมนต์แต่ละรายการ ส่วนผ่าน useapi.net ภาพอ้างอิงไม่มีค่าใช้จ่ายเพิ่ม | โมเดล | [API ทางการ](https://kling.ai/dev/pricing) | Premier $80.96/เดือน (8,000 cr/เดือน) | Pro $32.56/เดือน (3,000 cr/เดือน) | Standard $8.80/เดือน (660 cr/เดือน) | |---|---|---|---|---| | Kling Image 4.0 (2K) | $0.06 (16 หน่วย) | $0.04 / 4 cr (2,000 ภาพ/เดือน) | $0.04 / 4 cr (750 ภาพ/เดือน) | $0.05 / 4 cr (165 ภาพ/เดือน) | | Kling Image 4.0 (4K) | $0.09 (24 หน่วย) | $0.06 / 6 cr (1,333 ภาพ/เดือน) | $0.07 / 6 cr (500 ภาพ/เดือน) | $0.08 / 6 cr (110 ภาพ/เดือน) | | Kling Image 4.0 (8K) | $0.15 (40 หน่วย) | $0.10 / 10 cr (800 ภาพ/เดือน) | $0.11 / 10 cr (300 ภาพ/เดือน) | $0.13 / 10 cr (66 ภาพ/เดือน) | | หน้ารายละเอียดสินค้า (2K แบบสั้น) | $0.28 (72 หน่วย) | $0.18 / 18 cr (444 หน้า/เดือน) | $0.20 / 18 cr (166 หน้า/เดือน) | $0.24 / 18 cr (36 หน้า/เดือน) | | หน้ารายละเอียดสินค้า (2K แบบยาว) | $0.84 (220 หน่วย) | $0.56 / 55 cr (145 หน้า/เดือน) | $0.60 / 55 cr (54 หน้า/เดือน) | $0.73 / 55 cr (12 หน้า/เดือน) | | ดีไซน์เว็บ (2K) | $0.58 (152 หน่วย) | $0.38 / 38 cr (210 หน้า/เดือน) | $0.41 / 38 cr (78 หน้า/เดือน) | $0.51 / 38 cr (17 หน้า/เดือน) | ราคา ณ 19 พฤศจิกายน 2026 ราคาของ Kling สำหรับทุกแพ็กเกจอยู่ใน[เครื่องคำนวณราคา Kling](/docs/api-kling-v1#pricing) การรันทั้งหมดของเราสำหรับคู่มือนี้มี 13 งาน ได้ภาพและหน้ารวม 18 ชิ้น ใช้ไป 181 เครดิต หรือราว $1.96 บน Pro ### สร้างเป็นชุดด้วยสคริปต์ [ตัวอย่าง image-4](https://github.com/useapi/kling-api/tree/main/image-4) ใน GitHub repo ของเราอ่านรายการพรอมต์จาก `prompts.json` ซึ่งเป็นพรอมต์ชุดเดียวกับในคู่มือนี้ จากนั้นส่งทีละพรอมต์ รอจนเสร็จ แล้วดาวน์โหลดทุกภาพ: ```bash git clone https://github.com/useapi/kling-api.git cd kling-api/image-4 node ./kling-image-4.mjs $USEAPI_TOKEN $KLING_EMAIL ``` สคริปต์จะตรวจแต่ละพรอมต์ก่อนใช้เครดิต หน้ารายละเอียดสินค้าต้องมี `image_1` สกิลสร้างได้เฉพาะ 1K หรือ 2K และ `length` ใช้ได้กับ `product_detail` เท่านั้น ### ทำแบบเดียวกันจากผู้ช่วย AI [Kling MCP server](/docs/api-kling-v1/mcp) แบบโฮสต์ที่ `https://api.useapi.net/v1/kling/mcp` ทำให้ Claude Code, Cursor, VS Code และแอป Claude เรียกใช้ได้แบบเดียวกัน คือ `kling_omni_image` กับ `omni_version: v4` และ `kling_list_image_presets` สำหรับ id ของสไตล์ โทนสี และฟอนต์ แค่ขอ "ภาพ 8K ของ…" หรือ "หน้าสินค้าจากภาพนี้" แล้วผู้ช่วยจะกรอก request ให้เอง ### คำถามที่พบบ่อย **Kling Image 4.0 มี API ไหม?** มี useapi.net รัน Kling Image 4.0 บนแพ็กเกจ Kling AI ของคุณผ่าน [POST images/omni](/docs/api-kling-v1/post-kling-images-omni) ด้วย `omni_version: v4` รองรับ 8K, Series Mode, พรีเซ็ต หน้าสินค้า และดีไซน์เว็บ ในราคา 4 เครดิตต่อภาพ 2K หรือราว $0.04 บน Kling Pro API สำหรับนักพัฒนาของ Kling เองก็ขายโมเดลนี้ ที่ $0.06 ต่อภาพ 2K ในแพ็กแบบจ่ายล่วงหน้าที่เริ่มต้น $300 และคิดค่าธรรมเนียมเพิ่มต่อภาพอ้างอิงแต่ละภาพ การใช้ผ่านแพ็กเกจสมาชิกจึงถูกกว่าราว 30% (ข้อมูล ณ 19 พฤศจิกายน 2026) **จะสร้างภาพ 8K จาก Kling ได้อย่างไร?** ส่ง `"omni_version": "v4", "resolution": "8k"` ไปที่ [POST images/omni](/docs/api-kling-v1/post-kling-images-omni) บนแพ็กเกจ Kling แบบเสียเงิน การรันแบบ 16:9 ของเราได้ภาพ 10880 x 6144 ในราคาปกติ 10 เครดิต ($0.11 บน Kling Pro) และ Kling คิดเพียง 6 เครดิตในช่วงลดราคา ส่วน API สำหรับนักพัฒนาของ Kling คิด $0.15 สำหรับภาพ 8K เดียวกัน **ทำไมดีไซน์เว็บจาก Kling ถึงเป็นภาษาจีน?** Kling Image 4.0 เขียนข้อความบนหน้า `web_design` เป็นภาษาจีน เว้นแต่พรอมต์จะระบุภาษา ทั้งในแอป Kling และผ่าน API ให้ปิดท้ายพรอมต์ด้วย "All text on the page in English." หน้าภาษาอังกฤษของเราได้มาที่ 1K ในราคา 35 เครดิต **ใช้พรีเซ็ตอะไรได้บ้าง?** [GET images/presets](/docs/api-kling-v1/get-kling-images-presets) แสดงรายการปัจจุบันของ Kling ทั้ง 98 สไตล์ 16 โทนสี และ 76 ฟอนต์ พร้อม id และภาพตัวอย่าง ซึ่งเหมือนกันทุกบัญชี ระบุในพรอมต์ `v4` เป็น `@style:<id>`, `@tone:<id>` และ `@font:<id>` โดยวางฟอนต์ไว้หน้าข้อความในเครื่องหมายคำพูด พรีเซ็ตไม่ใช้เครดิตเพิ่ม ### บทสรุป Kling Image 4.0 อยู่ห่างแค่ request เดียวบนแพ็กเกจที่คุณมีอยู่แล้ว เพียงใช้ `omni_version: v4` กับ [POST images/omni](/docs/api-kling-v1/post-kling-images-omni) ได้ตั้งแต่ภาพ 2K ราคา 4 เครดิต ไปจนถึงภาพ 8K ขนาด 67 เมกะพิกเซล เรื่องราวหกภาพ หรือหน้าสินค้าเต็มหน้า เริ่มต้นได้ที่เอกสาร [Kling API](/docs/api-kling-v1) หรือรัน[สคริปต์ image-4](https://github.com/useapi/kling-api/tree/main/image-4) ด้วยพรอมต์ข้างต้น === URL: https://useapi.net/docs/articles/kling-image-4-api-vi === Document URL: https://useapi.net/docs/articles/kling-image-4-api-vi --- layout: default title: Cách tạo ảnh Kling Image 4.0 bằng Kling API seo_title: "Kling Image 4.0 API: ảnh 8K, Series Mode, trang sản phẩm" description: "Tạo ảnh Kling Image 4.0 bằng code trên gói Kling AI của bạn: ảnh 8K, Series Mode, preset, trang sản phẩm và thiết kế web, kèm lần chạy thật và chi phí." keywords: [Kling Image 4.0 API, API Kling Image 4.0, Kling Image 4 API, tạo ảnh Kling Image 4.0, ảnh 8K Kling, Kling 8K image, Kling Series Mode, trang chi tiết sản phẩm Kling, thiết kế web Kling, preset ảnh Kling, Kling API, Kling AI API, API tạo ảnh AI, Kuaishou, Kling MCP server, hướng dẫn Kling Image 4.0] image: https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-8k-hummingbird.jpg parent: Articles nav_exclude: true lang: vi translation_key: kling-image-4-api date: 2026-11-19 last_modified: 2026-11-19 nav_order: 856 repo: https://github.com/useapi/kling-api --- ## Cách tạo ảnh Kling Image 4.0 bằng Kling API {: #how-to-generate-kling-image-40-images-via-the-kling-api .no_toc } 6 phút đọc • 19 tháng 11 năm 2026 ## Mục lục {: #table-of-contents .no_toc .text-delta } ### Giới thiệu Kling Image 4.0 là model tạo ảnh mới của Kuaishou, và Kling API của useapi.net chạy nó trên [gói đăng ký website Kling AI](https://kling.ai/app/membership/membership-plan) của bạn: chỉ cần gửi `"omni_version": "v4"` tới [POST images/omni](/docs/api-kling-v1/post-kling-images-omni). Một endpoint làm được mọi thứ mà ứng dụng Kling làm với model này. Đó là ảnh tới 8K, câu chuyện Series Mode gồm 2 đến 10 ảnh đồng bộ, preset phong cách, tông màu và phông chữ gọi tên ngay trong prompt. Ngoài ra còn hai kỹ năng thiết kế, mỗi kỹ năng tạo một ảnh trang dài: trang chi tiết sản phẩm từ ảnh sản phẩm và thiết kế trang web. Hướng dẫn này gồm các lần chạy thật trên gói Kling Pro, mỗi tính năng một lần, kèm request chính xác, ảnh tạo ra và chi phí của từng lần. Một ảnh 2K dùng 4 credit, khoảng $0,04 trên gói Pro. API dành cho nhà phát triển của chính Kling bán cùng ảnh đó với giá $0,06, theo gói ảnh trả trước từ $300. ### Trước khi bắt đầu Bạn cần một [API token](/docs/start-here/setup-useapi) của useapi.net và một tài khoản Kling đã kết nối qua [Setup Kling](/docs/start-here/setup-kling), dùng gói Kling trả phí (Standard trở lên). 4K và 8K cũng cần gói trả phí. Export token để các ví dụ `curl` chạy được ngay: ```bash export USEAPI_TOKEN="user:1234-..." # your useapi.net API token export KLING_EMAIL="you@example.com" # your connected Kling account ``` ### Kling Image 4.0 trong nháy mắt | Chế độ | Request | Kết quả | Credit | |---|---|---|---| | Ảnh | `omni_version: v4` | 1 đến 9 ảnh ở 2K, 4K hoặc 8K, một trong 9 tỉ lệ khung hình hoặc `auto` | 4 / 6 / 10 mỗi ảnh | | Series Mode | `story_mode: true` | 2 đến 10 ảnh kể cùng một câu chuyện, hoặc số ảnh do Kling quyết định | như trên, tính theo ảnh | | Preset | `@style:`, `@tone:`, `@font:` trong prompt | một phong cách, một tông màu hoặc kiểu chữ từ danh sách của Kling | không tốn thêm | | Trang chi tiết sản phẩm | `skill: product_detail` + `image_1` | một trang dài từ ảnh sản phẩm của bạn, ngắn, vừa hoặc dài | 15 đến 55 mỗi trang | | Thiết kế web | `skill: web_design` | một bản thiết kế landing page dài | 35 ở 1K, 38 ở 2K | Tối đa 10 ảnh tham chiếu và các [element](/docs/api-kling-v1/get-kling-elements) đã lưu dùng được như trong mọi request Omni: gọi tên chúng trong prompt là `@image_1` hoặc `@element_1`. ### Tạo ảnh 8K với hai lệnh gọi #### 1. Gửi job ```bash curl -s -X POST "https://api.useapi.net/v1/kling/images/omni" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$KLING_EMAIL"'", "omni_version": "v4", "resolution": "8k", "aspect_ratio": "16:9", "prompt": "Macro photograph of a hummingbird hovering at a red trumpet flower at sunrise, every iridescent feather sharp, dew drops on the petals, soft golden backlight, shallow depth of field" }' ``` Response là task mới, id của nó nằm trong `task.id`: ```json { "task": { "id": 123456789012345, "type": "mmu_omni_image", "status": 5, "status_name": "submitted", "status_final": false } } ``` #### 2. Lấy kết quả Đọc task bằng [GET tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) cho đến khi `status_final` là `true`. Mỗi ảnh là một mục trong `works`, kèm URL và kích thước: ```bash curl -s "https://api.useapi.net/v1/kling/tasks/123456789012345?email=$KLING_EMAIL" \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{status_name, works: [.works[] | {url: .resource.resource, width: .resource.width, height: .resource.height}]}' ``` ```json { "status_name": "succeed", "works": [ { "url": "https://s15-kling.klingai.com/kimg/.../image.png", "width": 10880, "height": 6144 } ] } ``` Lần chạy của chúng tôi tạo ra một ảnh 10880 × 6144, tức 67 megapixel, và dùng 6 credit. Giá niêm yết của 8K là 10 credit, nhưng hôm đó Kling đang giảm giá nên chỉ tính 6. Cùng request với `"resolution": "2k"` tạo ảnh 2720 × 1536 với 4 credit, còn `"4k"` tạo ảnh 5440 × 3072 với 6 credit. <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-8k-hummingbird.jpg" alt="Kling Image 4.0 8K: chim ruồi bên bông hoa kèn đỏ lúc bình minh" loading="lazy" style="width:100%"> Kling Image 4.0, `8k`, `16:9`, 10880 × 6144, 6 credit. Ảnh ở đây đã được thu nhỏ: mở [bản gốc](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-8k-hummingbird-original.png) (PNG 10880 × 6144, 3,5 MB) để xem đủ độ phân giải 8K. Ở kích thước đầy đủ, chi tiết 8K vẫn rất rõ. Đây là một vùng cắt 1600 × 900 từ cùng tệp đó, không thu phóng: <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-8k-hummingbird-crop-100.jpg" alt="Vùng cắt 100% của ảnh 8K: mắt và lông của chim ruồi" loading="lazy" style="width:100%"> Cùng ảnh đó ở tỉ lệ 100%, phần đầu con chim. ### Series Mode: cả một câu chuyện từ một prompt `story_mode: true` tạo một loạt ảnh đồng bộ: cùng nhân vật, phong cách và ánh sáng từ khung này sang khung khác. Kling Image 4.0 tạo loạt ảnh chỉ từ prompt, không cần ảnh tham chiếu. Đặt `imageCount` từ 2 đến 10, hoặc bỏ trống để Kling tự quyết định câu chuyện cần bao nhiêu ảnh. ```bash curl -s -X POST "https://api.useapi.net/v1/kling/images/omni" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$KLING_EMAIL"'", "omni_version": "v4", "story_mode": true, "aspect_ratio": "4:3", "prompt": "A picture-book story in consistent watercolor style: a small paper boat is folded by a child on a rainy city street, floats down the gutter, slips into a river past old bridges, and finally reaches the open sea at sunset" }' ``` Kling chọn 6 ảnh cho câu chuyện này, mỗi ảnh 2336 × 1760, và tính 4 credit mỗi ảnh, tổng cộng 24 credit. <div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(220px,1fr));gap:8px"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-1.jpg" alt="Series Mode, ảnh 1/6: một đứa trẻ gấp thuyền giấy trên con phố mưa" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-2.jpg" alt="Series Mode, ảnh 2/6: chiếc thuyền trôi theo rãnh nước ven đường" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-3.jpg" alt="Series Mode, ảnh 3/6: chiếc thuyền trên một con kênh trong thành phố" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-4.jpg" alt="Series Mode, ảnh 4/6: chiếc thuyền đi qua dưới một cây cầu cổ" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-5.jpg" alt="Series Mode, ảnh 5/6: chiếc thuyền trên một dòng sông rộng" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-6.jpg" alt="Series Mode, ảnh 6/6: chiếc thuyền ra tới biển lúc hoàng hôn" loading="lazy" style="width:100%"> </div> Kling Image 4.0 Series Mode, `story_mode: true`, bỏ trống `imageCount`, 6 ảnh, 24 credit. Bản gốc, PNG 2336 × 1760: [1](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-1-original.png), [2](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-2-original.png), [3](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-3-original.png), [4](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-4-original.png), [5](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-5-original.png), [6](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-6-original.png). ### Phong cách, tông màu và phông chữ Kling Image 4.0 có ba loại preset, và bạn gọi tên chúng ngay trong prompt. [GET images/presets](/docs/api-kling-v1/get-kling-images-presets) liệt kê chúng kèm id và ảnh mẫu: 98 phong cách, 16 tông màu và 76 phông chữ cho tiếng Anh, tiếng Nhật, tiếng Hàn và tiếng Trung. ```bash curl -s "https://api.useapi.net/v1/kling/images/presets" -H "Authorization: Bearer $USEAPI_TOKEN" \ | jq '{styles: [.styles[0:3][] | .id], tones: [.tones[] | .id], fonts: [.fonts[] | select(.languages | index("en")) | .id][0:5]}' ``` - Tông màu (`@tone:<id>`) áp dụng một kiểu chỉnh màu và ánh sáng của Kling: phong cách đạo diễn, chất máy quay và bảng màu. - Phông chữ (`@font:<id>`) đặt kiểu chữ cho đoạn văn bản trong ngoặc kép ngay sau nó. - Phong cách (`@style:<id>`) quyết định diện mạo tổng thể: 3D, 2D, thủ công chất liệu hoặc nhiếp ảnh. Đây là cùng một cảnh, không có tông màu và có `@tone:Nostalgic_Wuxia`, mỗi ảnh 4 credit: <div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(280px,1fr));gap:8px"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-tone-none-swordsman.jpg" alt="Không có tông màu: một kiếm khách trong rừng tre lúc bình minh" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-tone-nostalgic-wuxia-swordsman.jpg" alt="@tone:Nostalgic_Wuxia: cùng cảnh đó với tông màu phim kiếm hiệp ấm và phai màu" loading="lazy" style="width:100%"> </div> Trái: `A lone swordsman in a bamboo forest at dawn, mist between the stalks, wide cinematic shot`. Phải: cùng prompt đó, đặt sau `@tone:Nostalgic_Wuxia`. Bản gốc, PNG 2720 × 1536: [không tông màu](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-tone-none-swordsman-original.png), [Nostalgic Wuxia](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-tone-nostalgic-wuxia-swordsman-original.png). Còn đây là một biển hiệu quán, không có phông chữ và có `@font:elegant_brush_hand`. Đặt chữ bạn muốn xuất hiện trong ảnh vào ngoặc kép, và đặt phông chữ ngay trước đó: ```json { "prompt": "A cozy corner coffee shop at night, warm light spilling onto a wet cobblestone street, a hand-painted shop sign above the door that reads @font:elegant_brush_hand \"Moonlight Roasters\"" } ``` <div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(280px,1fr));gap:8px"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-font-none-coffee-sign.jpg" alt="Không có phông chữ: biển hiệu kiểu chữ serif đơn giản" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-font-elegant-brush-hand-coffee-sign.jpg" alt="@font:elegant_brush_hand: biển hiệu kiểu chữ viết tay bằng bút lông" loading="lazy" style="width:100%"> </div> Trái: không có phông chữ. Phải: `@font:elegant_brush_hand "Moonlight Roasters"`. Bản gốc, PNG 2496 × 1664: [không phông chữ](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-font-none-coffee-sign-original.png), [phông bút lông](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-font-elegant-brush-hand-coffee-sign-original.png). <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-style-3d-cartoon-corgi-astronaut.jpg" alt="@style:3d_cartoon_with_exaggerated_perspective_pro: chú corgi phi hành gia trên một hành tinh màu kẹo ngọt" loading="lazy" style="width:60%"> `@style:3d_cartoon_with_exaggerated_perspective_pro A corgi astronaut stepping out of a tiny rocket onto a candy-colored planet, looking up at the camera`, `1:1`, 4 credit. [bản gốc](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-style-3d-cartoon-corgi-astronaut-original.png)(PNG 2048 × 2048, 8,5 MB). Một id không tồn tại sẽ nhận lỗi `400` trước khi request tới Kling, nên gõ sai không bao giờ tốn credit. ### Ảnh tham chiếu Gọi tên ảnh tham chiếu trong prompt là `@image_1`. Chúng tôi tạo một ảnh sản phẩm trước, rồi dùng URL của nó làm `image_1` cho một ảnh quảng cáo 4K. Sản phẩm, nhãn và nắp tre của nó đều được giữ nguyên: ```json { "omni_version": "v4", "resolution": "4k", "aspect_ratio": "16:9", "prompt": "The bottle from @image_1 standing on a mossy rock beside a mountain stream, morning mist, outdoor adventure ad", "image_1": "https://s15-kling.klingai.com/kimg/.../bottle.png" } ``` <div style="display:grid;grid-template-columns:1fr 2fr;gap:8px;align-items:start"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-product-photo-bottle.jpg" alt="Ảnh sản phẩm: bình thép màu xanh xô thơm có nắp tre" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-4k-reference-bottle-stream.jpg" alt="Ảnh 4K dùng ảnh sản phẩm làm tham chiếu: chiếc bình bên dòng suối trên núi" loading="lazy" style="width:100%"> </div> Trái: ảnh sản phẩm, `3:4`, 4 credit. Phải: `4k` với ảnh đó làm `@image_1`, 5440 × 3072, 6 credit. Bản gốc: [ảnh sản phẩm](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-product-photo-bottle-original.png) (PNG 1760 × 2336, 4,8 MB), [ảnh quảng cáo 4K](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-4k-reference-bottle-stream-original.png) (PNG 5440 × 3072, 24 MB). Để tải ảnh của riêng bạn lên, dùng [POST assets](/docs/api-kling-v1/post-kling-assets) rồi truyền URL mà nó trả về. ### Trang chi tiết sản phẩm `skill: product_detail` biến một ảnh sản phẩm thành một trang sản phẩm dài, dàn trang trong một ảnh duy nhất: phần hero, điểm nổi bật, ảnh cận cảnh và bảng thông số. `image_1` là ảnh sản phẩm, `prompt` mô tả công dụng của sản phẩm, còn `length` đặt số phần: `short` (2 đến 5), `medium` (6 đến 10) hoặc `long` (11 đến 18). ```bash curl -s -X POST "https://api.useapi.net/v1/kling/images/omni" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$KLING_EMAIL"'", "omni_version": "v4", "skill": "product_detail", "length": "short", "resolution": "2k", "image_1": "https://s15-kling.klingai.com/kimg/.../bottle.png", "prompt": "Insulated steel water bottle \"Trailhead\": keeps drinks cold 24 hours and hot 12, leak-proof bamboo lid, fits car cup holders, 750 ml, three colors" }' ``` Trang trả về là một ảnh 2048 × 13408, tốn 18 credit. Một trang `medium` ở 1K có kích thước 1024 × 9936, tốn 30 credit. <div style="max-height:900px;overflow-y:auto;border:1px solid #ddd"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-product-detail-page-2k-short.jpg" alt="Trang chi tiết sản phẩm Kling Image 4.0: bình Trailhead màu Sage Green, điểm nổi bật và thông số" loading="lazy" style="width:100%"> </div> `skill: product_detail`, `length: short`, `2k`, 2048 × 13408, 18 credit. Cuộn khung để xem cả trang, hoặc mở [bản gốc](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-product-detail-page-2k-short-original.png) (PNG, 1,3 MB). ### Thiết kế trang web `skill: web_design` tạo một bản thiết kế landing page dưới dạng một ảnh dài. `image_1` không bắt buộc: đó là một ảnh có phong cách mà trang nên theo. Kling viết chữ trên trang bằng tiếng Trung, trừ khi prompt nêu rõ ngôn ngữ, nên hãy kết thúc prompt bằng ngôn ngữ bạn muốn: ```bash curl -s -X POST "https://api.useapi.net/v1/kling/images/omni" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$KLING_EMAIL"'", "omni_version": "v4", "skill": "web_design", "resolution": "1k", "prompt": "Landing page for \"Ember & Oak\", a small-batch coffee roaster: warm browns and cream, elegant serif headlines, hero photo of a pour-over, three featured roasts, a monthly subscription offer and customer reviews. All text on the page in English." }' ``` <div style="max-height:900px;overflow-y:auto;border:1px solid #ddd"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-web-design-1k-english.jpg" alt="Thiết kế web Kling Image 4.0: landing page tiếng Anh của nhà rang cà phê Ember & Oak" loading="lazy" style="width:100%"> </div> `skill: web_design`, `1k`, 1024 × 5376, 35 credit. Cuộn khung để xem cả trang, hoặc mở [bản gốc](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-web-design-1k-english-original.png) (PNG, 0,7 MB). Không có câu cuối đó, cùng prompt ở 2K tạo ra trang bằng tiếng Trung (2048 × 8514, 38 credit). Một bản thiết kế web làm trong ứng dụng Kling cũng vậy: <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-web-design-2k-chinese-top.jpg" alt="Cùng prompt thiết kế web nhưng không nêu ngôn ngữ: chữ trên trang là tiếng Trung" loading="lazy" style="width:100%"> Phần đầu trang khi không có câu "All text on the page in English." Cả trang: [bản gốc](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-web-design-2k-chinese-original.png) (PNG 2048 × 8514, 1,4 MB). ### Chi phí Kling Image 4.0 dùng credit từ gói đăng ký Kling AI của bạn, với mức giá như nhau trên mọi gói. API dành cho nhà phát triển của Kling bán model này theo các gói ảnh riêng. Gói nhỏ nhất là $300 cho 78.216 đơn vị ($0,00384 mỗi đơn vị, dùng trong 180 ngày), và còn tính thêm 0,8 đơn vị cho mỗi ảnh tham chiếu hoặc element. Qua useapi.net, ảnh tham chiếu không tốn thêm gì. | Model | [API chính thức](https://kling.ai/dev/pricing) | Premier $80,96/tháng (8.000 cr/tháng) | Pro $32,56/tháng (3.000 cr/tháng) | Standard $8,80/tháng (660 cr/tháng) | |---|---|---|---|---| | Kling Image 4.0 (2K) | $0,06 (16 đơn vị) | $0,04 / 4 cr (2.000 ảnh/tháng) | $0,04 / 4 cr (750 ảnh/tháng) | $0,05 / 4 cr (165 ảnh/tháng) | | Kling Image 4.0 (4K) | $0,09 (24 đơn vị) | $0,06 / 6 cr (1.333 ảnh/tháng) | $0,07 / 6 cr (500 ảnh/tháng) | $0,08 / 6 cr (110 ảnh/tháng) | | Kling Image 4.0 (8K) | $0,15 (40 đơn vị) | $0,10 / 10 cr (800 ảnh/tháng) | $0,11 / 10 cr (300 ảnh/tháng) | $0,13 / 10 cr (66 ảnh/tháng) | | Trang chi tiết sản phẩm (2K, ngắn) | $0,28 (72 đơn vị) | $0,18 / 18 cr (444 trang/tháng) | $0,20 / 18 cr (166 trang/tháng) | $0,24 / 18 cr (36 trang/tháng) | | Trang chi tiết sản phẩm (2K, dài) | $0,84 (220 đơn vị) | $0,56 / 55 cr (145 trang/tháng) | $0,60 / 55 cr (54 trang/tháng) | $0,73 / 55 cr (12 trang/tháng) | | Thiết kế web (2K) | $0,58 (152 đơn vị) | $0,38 / 38 cr (210 trang/tháng) | $0,41 / 38 cr (78 trang/tháng) | $0,51 / 38 cr (17 trang/tháng) | Giá tính đến ngày 19/11/2026. Giá của Kling cho mọi gói có trong [công cụ tính giá Kling](/docs/api-kling-v1#pricing). Toàn bộ lần chạy cho hướng dẫn này gồm 13 job, tạo ra 18 ảnh và trang, dùng 181 credit, khoảng $1,96 trên gói Pro. ### Tạo hàng loạt bằng script Ví dụ [image-4](https://github.com/useapi/kling-api/tree/main/image-4) trong repo GitHub của chúng tôi đọc danh sách prompt từ `prompts.json` (chính là các prompt trong hướng dẫn này), gửi từng prompt, chờ kết quả và tải về mọi ảnh: ```bash git clone https://github.com/useapi/kling-api.git cd kling-api/image-4 node ./kling-image-4.mjs $USEAPI_TOKEN $KLING_EMAIL ``` Script kiểm tra từng prompt trước khi tốn credit: trang chi tiết sản phẩm cần `image_1`, một skill chỉ tạo 1K hoặc 2K, và `length` chỉ đi cùng `product_detail`. ### Làm điều tương tự từ trợ lý AI [Kling MCP server](/docs/api-kling-v1/mcp) được host sẵn tại `https://api.useapi.net/v1/kling/mcp` mang các lệnh gọi giống hệt tới Claude Code, Cursor, VS Code và ứng dụng Claude: `kling_omni_image` với `omni_version: v4`, và `kling_list_image_presets` để lấy id phong cách, tông màu và phông chữ. Hãy yêu cầu "một ảnh 8K về…" hoặc "một trang sản phẩm từ ảnh này", trợ lý sẽ tự điền request giúp bạn. ### Câu hỏi thường gặp **Kling Image 4.0 có API không?** Có. useapi.net chạy Kling Image 4.0 trên gói Kling AI của bạn qua [POST images/omni](/docs/api-kling-v1/post-kling-images-omni) với `omni_version: v4`: 8K, Series Mode, preset, trang sản phẩm và thiết kế web. Một ảnh 2K tốn 4 credit, khoảng $0,04 trên Kling Pro. API dành cho nhà phát triển của chính Kling cũng bán model này, với giá $0,06 một ảnh 2K theo gói trả trước từ $300, cộng thêm phí cho mỗi ảnh tham chiếu. Vì vậy dùng qua gói đăng ký rẻ hơn khoảng 30% (tính đến ngày 19/11/2026). **Làm sao để có ảnh 8K từ Kling?** Gửi `"omni_version": "v4", "resolution": "8k"` tới [POST images/omni](/docs/api-kling-v1/post-kling-images-omni) trên gói Kling trả phí. Lần chạy 16:9 của chúng tôi trả về ảnh 10880 × 6144, giá niêm yết 10 credit ($0,11 trên Kling Pro), và Kling chỉ tính 6 credit trong đợt giảm giá. API dành cho nhà phát triển của Kling tính $0,15 cho cùng ảnh 8K đó. **Vì sao thiết kế web Kling của tôi lại bằng tiếng Trung?** Kling Image 4.0 viết chữ trên trang `web_design` bằng tiếng Trung, trừ khi prompt nêu rõ ngôn ngữ, cả trong ứng dụng Kling lẫn qua API. Hãy kết thúc prompt bằng câu "All text on the page in English." Trang tiếng Anh của chúng tôi trả về ở 1K với 35 credit. **Tôi dùng được những preset nào?** [GET images/presets](/docs/api-kling-v1/get-kling-images-presets) liệt kê 98 phong cách, 16 tông màu và 76 phông chữ hiện có của Kling, kèm id và ảnh mẫu, giống nhau cho mọi tài khoản. Gọi tên chúng trong prompt `v4` là `@style:<id>`, `@tone:<id>`, và `@font:<id>` đặt trước đoạn văn bản trong ngoặc kép. Preset không tốn thêm credit. ### Kết luận Kling Image 4.0 chỉ cách bạn một request, ngay trên gói đăng ký bạn đang có: `omni_version: v4` trên [POST images/omni](/docs/api-kling-v1/post-kling-images-omni). Từ ảnh 2K giá 4 credit đến ảnh 8K 67 megapixel, một câu chuyện sáu khung hình hay cả một trang sản phẩm. Hãy bắt đầu với tài liệu [Kling API](/docs/api-kling-v1), hoặc chạy [script image-4](https://github.com/useapi/kling-api/tree/main/image-4) với các prompt ở trên. === URL: https://useapi.net/docs/articles/kling-image-4-api-zh === Document URL: https://useapi.net/docs/articles/kling-image-4-api-zh --- layout: default title: "如何通过 Kling API 生成 Kling Image 4.0 图片" seo_title: "Kling Image 4.0 API:8K 图片、系列故事、商品详情页" description: "在你的 Kling AI 订阅上用代码生成 Kling Image 4.0 图片:8K 照片、系列模式故事、风格/色调/字体预设、商品详情页和网页设计,附真实运行结果和费用。" keywords: [Kling Image 4.0 API, Kling Image 4.0 教程, Kling Image 4.0 价格, Kling 8K 图片, Kling 系列模式, Kling 商品详情页, Kling 网页设计, Kling 图片预设, Kling Omni 图片, Kling API, Kling AI API, AI 图片生成 API, Kuaishou Kling, Kling MCP server, Kling Image 4 API, Kling 4.0 image API, Kling Series Mode, Kling product detail page, curl, tutorial] image: https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-8k-hummingbird.jpg parent: Articles nav_exclude: true lang: zh-CN translation_key: kling-image-4-api date: 2026-11-19 last_modified: 2026-11-19 nav_order: 856 repo: https://github.com/useapi/kling-api --- ## 如何通过 Kling API 生成 Kling Image 4.0 图片 {: .no_toc #how-to-generate-kling-image-40-images-via-the-kling-api } 6 分钟阅读 • 2026 年 11 月 19 日 ## 目录 {: .no_toc .text-delta #table-of-contents } ### 简介 Kling Image 4.0 是 Kuaishou 新推出的图片模型。useapi.net 的 Kling API 在你的 [Kling AI 网站订阅](https://kling.ai/app/membership/membership-plan)上运行它:向 [POST images/omni](/docs/api-kling-v1/post-kling-images-omni) 发送 `"omni_version": "v4"` 即可。Kling 应用里用这个模型能做的事,一个接口全部覆盖:最高 8K 的照片,由 2 到 10 张风格一致的图片组成的系列模式(Series Mode)故事,在提示词里点名的风格、色调和字体预设,还有两项设计技能,各自生成一张长页面图片:根据商品照片生成商品详情页,以及网页设计。 本文是在 Kling Pro 订阅上的一组真实运行,每个功能一次,附上完整请求、生成的图片和每次的费用。一张 2K 图片消耗 4 积分,在 Pro 套餐上约 $0.04。Kling 自己的开发者 API 卖同样一张图要 $0.06,而且要预购 $300 起的图片资源包。 ### 开始之前 你需要一个 useapi.net [API Token](/docs/start-here/setup-useapi),以及一个通过 [Setup Kling](/docs/start-here/setup-kling) 绑定的 Kling 账号,账号需开通付费的 Kling 套餐(Standard 或更高)。4K 和 8K 同样需要付费套餐。先导出 Token,下面的 `curl` 示例就能直接运行: ```bash export USEAPI_TOKEN="user:1234-..." # your useapi.net API token export KLING_EMAIL="you@example.com" # your connected Kling account ``` ### Kling Image 4.0 一览 | 模式 | 请求 | 你会得到 | 积分 | |---|---|---|---| | 图片 | `omni_version: v4` | 1 到 9 张图片,2K、4K 或 8K,9 种画面比例任选,或 `auto` | 每张 4 / 6 / 10 | | 系列模式 | `story_mode: true` | 2 到 10 张讲同一个故事的图片,或由 Kling 决定张数 | 同上,按张计 | | 预设 | 提示词中的 `@style:`、`@tone:`、`@font:` | Kling 列表中的一种画风、调色或字体 | 不额外收费 | | 商品详情页 | `skill: product_detail` + `image_1` | 根据你的商品照片生成一张长页面,分短、中、长三档 | 每页 15 到 55 | | 网页设计 | `skill: web_design` | 一张长的落地页设计图 | 1K 为 35,2K 为 38 | 与所有 Omni 请求一样,最多可以使用 10 张参考图片和已保存的[元素(elements)](/docs/api-kling-v1/get-kling-elements):在提示词中用 `@image_1` 或 `@element_1` 引用它们。 ### 两次调用生成一张 8K 图片 #### 1. 提交任务 ```bash curl -s -X POST "https://api.useapi.net/v1/kling/images/omni" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$KLING_EMAIL"'", "omni_version": "v4", "resolution": "8k", "aspect_ratio": "16:9", "prompt": "Macro photograph of a hummingbird hovering at a red trumpet flower at sunrise, every iridescent feather sharp, dew drops on the petals, soft golden backlight, shallow depth of field" }' ``` 返回的是新建的任务,任务 id 在 `task.id` 中: ```json { "task": { "id": 123456789012345, "type": "mmu_omni_image", "status": 5, "status_name": "submitted", "status_final": false } } ``` #### 2. 轮询结果 用 [GET tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) 读取任务,直到 `status_final` 为 `true`。每张图片是 `works` 中的一项,带有 URL 和尺寸: ```bash curl -s "https://api.useapi.net/v1/kling/tasks/123456789012345?email=$KLING_EMAIL" \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{status_name, works: [.works[] | {url: .resource.resource, width: .resource.width, height: .resource.height}]}' ``` ```json { "status_name": "succeed", "works": [ { "url": "https://s15-kling.klingai.com/kimg/.../image.png", "width": 10880, "height": 6144 } ] } ``` 我们这次运行生成了一张 10880 x 6144 的图片,约 6700 万像素,消耗 6 积分。8K 的标价是 10 积分,当天 Kling 正在促销,按 6 积分计费。同样的请求改为 `"resolution": "2k"`,会生成 2720 x 1536 的图片,消耗 4 积分。改为 `"4k"` 则生成 5440 x 3072 的图片,消耗 6 积分。 <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-8k-hummingbird.jpg" alt="Kling Image 4.0 8K:日出时分停在红色喇叭花旁的蜂鸟" loading="lazy" style="width:100%"> Kling Image 4.0,`8k`,`16:9`,10880 x 6144,6 积分。这里显示的是缩小版:打开[原图](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-8k-hummingbird-original.png) (10880 x 6144 PNG,3.5 MB)可查看完整 8K 画面。 放到原始尺寸,8K 的细节依然清晰。下面是同一个文件中截取的 1600 x 900 区域,没有缩放: <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-8k-hummingbird-crop-100.jpg" alt="8K 图片的 100% 裁切:蜂鸟的眼睛和羽毛" loading="lazy" style="width:100%"> 同一张图片的 100% 显示,鸟的头部。 ### 系列模式:一个提示词讲一个故事 `story_mode: true` 会生成一组彼此呼应的图片:每一格中的角色、画风和光线保持一致。Kling Image 4.0 只凭提示词就能生成系列,不需要参考图片。把 `imageCount` 设为 2 到 10,或者不传,由 Kling 决定这个故事需要几张图。 ```bash curl -s -X POST "https://api.useapi.net/v1/kling/images/omni" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$KLING_EMAIL"'", "omni_version": "v4", "story_mode": true, "aspect_ratio": "4:3", "prompt": "A picture-book story in consistent watercolor style: a small paper boat is folded by a child on a rainy city street, floats down the gutter, slips into a river past old bridges, and finally reaches the open sea at sunset" }' ``` Kling 为这个故事选择了 6 张图片,每张 2336 x 1760,每张收取 4 积分,共 24 积分。 <div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(220px,1fr));gap:8px"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-1.jpg" alt="系列模式 第 1 张,共 6 张:孩子在雨中的街道上折纸船" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-2.jpg" alt="系列模式 第 2 张,共 6 张:纸船顺着路边水沟漂走" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-3.jpg" alt="系列模式 第 3 张,共 6 张:纸船漂在城市运河上" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-4.jpg" alt="系列模式 第 4 张,共 6 张:纸船从一座老桥下穿过" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-5.jpg" alt="系列模式 第 5 张,共 6 张:纸船漂在宽阔的河面上" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-6.jpg" alt="系列模式 第 6 张,共 6 张:纸船在日落时分抵达大海" loading="lazy" style="width:100%"> </div> Kling Image 4.0 系列模式,`story_mode: true`,未传 `imageCount`,6 张图片,24 积分。原图,2336 x 1760 PNG:[1](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-1-original.png)、[2](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-2-original.png)、[3](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-3-original.png)、[4](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-4-original.png)、[5](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-5-original.png)、[6](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-6-original.png)。 ### 风格、色调和字体 Kling Image 4.0 有三类预设,在提示词中点名使用。[GET images/presets](/docs/api-kling-v1/get-kling-images-presets) 会列出它们的 id 和示例图:98 种风格、16 种色调,以及 76 种支持英文、日文、韩文和中文的字体。 ```bash curl -s "https://api.useapi.net/v1/kling/images/presets" -H "Authorization: Bearer $USEAPI_TOKEN" \ | jq '{styles: [.styles[0:3][] | .id], tones: [.tones[] | .id], fonts: [.fonts[] | select(.languages | index("en")) | .id][0:5]}' ``` - 色调(`@tone:<id>`)套用 Kling 的一种调色和光影方案:导演风格、相机质感和配色。 - 字体(`@font:<id>`)决定紧随其后的引号内文字用什么字体呈现。 - 风格(`@style:<id>`)决定整体画风:3D、2D、材质手工或摄影风格。 下面是同一个场景不加色调和加上 `@tone:Nostalgic_Wuxia` 的对比,各消耗 4 积分: <div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(280px,1fr));gap:8px"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-tone-none-swordsman.jpg" alt="不加色调:黎明时分竹林中的一名剑客" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-tone-nostalgic-wuxia-swordsman.jpg" alt="@tone:Nostalgic_Wuxia:同一场景,带有温暖、褪色的武侠电影调色" loading="lazy" style="width:100%"> </div> 左:`A lone swordsman in a bamboo forest at dawn, mist between the stalks, wide cinematic shot`。右:同一提示词前加上 `@tone:Nostalgic_Wuxia`。原图,2720 x 1536 PNG:[不加色调](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-tone-none-swordsman-original.png)、[Nostalgic Wuxia](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-tone-nostalgic-wuxia-swordsman-original.png)。 再看一块店铺招牌,不加字体和加上 `@font:elegant_brush_hand` 的对比。把想出现在图片里的文字放进引号,字体紧挨在引号前面: ```json { "prompt": "A cozy corner coffee shop at night, warm light spilling onto a wet cobblestone street, a hand-painted shop sign above the door that reads @font:elegant_brush_hand \"Moonlight Roasters\"" } ``` <div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(280px,1fr));gap:8px"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-font-none-coffee-sign.jpg" alt="不加字体:招牌是普通的衬线字体" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-font-elegant-brush-hand-coffee-sign.jpg" alt="@font:elegant_brush_hand:招牌是毛笔手写体" loading="lazy" style="width:100%"> </div> 左:不加字体。右:`@font:elegant_brush_hand "Moonlight Roasters"`。原图,2496 x 1664 PNG:[不加字体](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-font-none-coffee-sign-original.png)、[毛笔字体](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-font-elegant-brush-hand-coffee-sign-original.png)。 <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-style-3d-cartoon-corgi-astronaut.jpg" alt="@style:3d_cartoon_with_exaggerated_perspective_pro:一只柯基宇航员站在糖果色的星球上" loading="lazy" style="width:60%"> `@style:3d_cartoon_with_exaggerated_perspective_pro A corgi astronaut stepping out of a tiny rocket onto a candy-colored planet, looking up at the camera`,`1:1`,4 积分。[原图](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-style-3d-cartoon-corgi-astronaut-original.png)(2048 x 2048 PNG,8.5 MB)。 如果 id 不存在,请求在到达 Kling 之前就会收到 `400`,所以拼错不会浪费积分。 ### 参考图片 在提示词中用 `@image_1` 引用参考图片。我们先生成了一张商品照片,再把它的 URL 作为 `image_1`,生成一张 4K 广告图。商品本身、它的标签和竹制瓶盖都保留了下来: ```json { "omni_version": "v4", "resolution": "4k", "aspect_ratio": "16:9", "prompt": "The bottle from @image_1 standing on a mossy rock beside a mountain stream, morning mist, outdoor adventure ad", "image_1": "https://s15-kling.klingai.com/kimg/.../bottle.png" } ``` <div style="display:grid;grid-template-columns:1fr 2fr;gap:8px;align-items:start"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-product-photo-bottle.jpg" alt="商品照片:一只带竹制瓶盖的灰绿色不锈钢水瓶" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-4k-reference-bottle-stream.jpg" alt="以商品照片为参考的 4K 图片:水瓶立在山间溪流旁" loading="lazy" style="width:100%"> </div> 左:商品照片,`3:4`,4 积分。右:以它为 `@image_1` 的 `4k` 图片,5440 x 3072,6 积分。原图:[商品照片](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-product-photo-bottle-original.png)(1760 x 2336 PNG,4.8 MB)、[4K 广告图](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-4k-reference-bottle-stream-original.png)(5440 x 3072 PNG,24 MB)。 要上传你自己的照片,使用 [POST assets](/docs/api-kling-v1/post-kling-assets),再传入它返回的 URL。 ### 商品详情页 `skill: product_detail` 把一张商品照片变成一张长长的商品页面:主图、卖点、细节特写和规格表,全部排在一张图片里。`image_1` 是商品照片,`prompt` 描述商品的用途,`length` 决定版块数量:`short`(2 到 5 个)、`medium`(6 到 10 个)或 `long`(11 到 18 个)。 ```bash curl -s -X POST "https://api.useapi.net/v1/kling/images/omni" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$KLING_EMAIL"'", "omni_version": "v4", "skill": "product_detail", "length": "short", "resolution": "2k", "image_1": "https://s15-kling.klingai.com/kimg/.../bottle.png", "prompt": "Insulated steel water bottle \"Trailhead\": keeps drinks cold 24 hours and hot 12, leak-proof bamboo lid, fits car cup holders, 750 ml, three colors" }' ``` 返回的页面是一张 2048 x 13408 的图片,消耗 18 积分。一张 1K 的 `medium` 页面为 1024 x 9936,消耗 30 积分。 <div style="max-height:900px;overflow-y:auto;border:1px solid #ddd"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-product-detail-page-2k-short.jpg" alt="Kling Image 4.0 商品详情页:Sage Green Trailhead 水瓶,卖点和规格" loading="lazy" style="width:100%"> </div> `skill: product_detail`,`length: short`,`2k`,2048 x 13408,18 积分。滚动框内画面可查看整页,或打开[原图](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-product-detail-page-2k-short-original.png)(PNG,1.3 MB)。 ### 网页设计 `skill: web_design` 把一个落地页设计生成为一张长图。`image_1` 可选,用来提供一张让页面参照风格的图片。除非提示词指明语言,Kling 会用中文写页面上的文字,所以请在提示词末尾写明你要的语言: ```bash curl -s -X POST "https://api.useapi.net/v1/kling/images/omni" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$KLING_EMAIL"'", "omni_version": "v4", "skill": "web_design", "resolution": "1k", "prompt": "Landing page for \"Ember & Oak\", a small-batch coffee roaster: warm browns and cream, elegant serif headlines, hero photo of a pour-over, three featured roasts, a monthly subscription offer and customer reviews. All text on the page in English." }' ``` <div style="max-height:900px;overflow-y:auto;border:1px solid #ddd"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-web-design-1k-english.jpg" alt="Kling Image 4.0 网页设计:Ember & Oak 咖啡烘焙店的英文落地页" loading="lazy" style="width:100%"> </div> `skill: web_design`,`1k`,1024 x 5376,35 积分。滚动框内画面可查看整页,或打开[原图](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-web-design-1k-english-original.png)(PNG,0.7 MB)。 去掉最后一句后,同一个提示词在 2K 下生成的页面是中文的(2048 x 8514,38 积分)。在 Kling 应用里做的网页设计也是如此: <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-web-design-2k-chinese-top.jpg" alt="同一网页设计提示词,未指明语言:页面文字为中文" loading="lazy" style="width:100%"> 没有 "All text on the page in English." 时页面的顶部。整页:[原图](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-web-design-2k-chinese-original.png)(2048 x 8514 PNG,1.4 MB)。 ### 费用 Kling Image 4.0 消耗的是你 Kling AI 订阅的积分,每个套餐的积分价格相同。Kling 的开发者 API 则用自己的图片资源包出售它,最小的一档 $300 含 78,216 单位(每单位 $0.00384,有效期 180 天),而且每张参考图片或每个元素还要另收 0.8 单位。通过 useapi.net,参考素材不额外收费。 | 模型 | [官方 API](https://kling.ai/dev/pricing) | Premier $80.96/月 (每月 8,000 积分) | Pro $32.56/月 (每月 3,000 积分) | Standard $8.80/月 (每月 660 积分) | |---|---|---|---|---| | Kling Image 4.0 (2K) | $0.06 (16 单位) | $0.04 / 4 积分 (每月 2,000 张) | $0.04 / 4 积分 (每月 750 张) | $0.05 / 4 积分 (每月 165 张) | | Kling Image 4.0 (4K) | $0.09 (24 单位) | $0.06 / 6 积分 (每月 1,333 张) | $0.07 / 6 积分 (每月 500 张) | $0.08 / 6 积分 (每月 110 张) | | Kling Image 4.0 (8K) | $0.15 (40 单位) | $0.10 / 10 积分 (每月 800 张) | $0.11 / 10 积分 (每月 300 张) | $0.13 / 10 积分 (每月 66 张) | | 商品详情页 (2K,短) | $0.28 (72 单位) | $0.18 / 18 积分 (每月 444 页) | $0.20 / 18 积分 (每月 166 页) | $0.24 / 18 积分 (每月 36 页) | | 商品详情页 (2K,长) | $0.84 (220 单位) | $0.56 / 55 积分 (每月 145 页) | $0.60 / 55 积分 (每月 54 页) | $0.73 / 55 积分 (每月 12 页) | | 网页设计 (2K) | $0.58 (152 单位) | $0.38 / 38 积分 (每月 210 页) | $0.41 / 38 积分 (每月 78 页) | $0.51 / 38 积分 (每月 17 页) | 价格截至 2026 年 11 月 19 日。Kling 所有套餐的价格见 [Kling 价格计算器](/docs/api-kling-v1#pricing)。为写这篇文章,我们一共运行了 13 个任务,生成 18 张图片和页面,消耗 181 积分,在 Pro 套餐上约 $1.96。 ### 用脚本批量生成 我们 GitHub 仓库中的 [image-4 示例](https://github.com/useapi/kling-api/tree/main/image-4)会从 `prompts.json` 读取一组提示词(就是本文用到的提示词),逐个提交、等待完成,并下载每一张图片: ```bash git clone https://github.com/useapi/kling-api.git cd kling-api/image-4 node ./kling-image-4.mjs $USEAPI_TOKEN $KLING_EMAIL ``` 它会在消耗积分之前检查每个提示词:商品详情页需要 `image_1`,设计技能只能生成 1K 或 2K,`length` 只能和 `product_detail` 一起使用。 ### 在 AI 助手中使用 托管的 [Kling MCP server](/docs/api-kling-v1/mcp) 地址为 `https://api.useapi.net/v1/kling/mcp`,它让 Claude Code、Cursor、VS Code 和 Claude 应用能发出同样的调用:`kling_omni_image` 配合 `omni_version: v4`,以及用 `kling_list_image_presets` 查询风格、色调和字体 id。说一句“给我一张 8K 照片……”或“用这张照片做一个商品页”,助手就会替你填好请求。 ### 常见问题 **有 Kling Image 4.0 API 吗?** 有。useapi.net 通过 [POST images/omni](/docs/api-kling-v1/post-kling-images-omni) 加上 `omni_version: v4`,在你的 Kling AI 订阅上运行 Kling Image 4.0:8K、系列模式、预设、商品页和网页设计都支持,一张 2K 图片 4 积分,在 Kling Pro 上约 $0.04。Kling 自己的开发者 API 也提供这个模型,2K 图片每张 $0.06,需预购 $300 起的资源包,每张参考图片还要另外收费,所以走订阅这条路便宜约 30%(截至 2026 年 11 月 19 日)。 **怎样从 Kling 拿到 8K 图片?** 在付费 Kling 套餐上,向 [POST images/omni](/docs/api-kling-v1/post-kling-images-omni) 发送 `"omni_version": "v4", "resolution": "8k"`。我们的 16:9 运行返回了 10880 x 6144 的图片,标价 10 积分(在 Kling Pro 上为 $0.11),促销期间 Kling 只收了 6 积分。Kling 的开发者 API 对同样一张 8K 图片收费 $0.15。 **为什么我的 Kling 网页设计是中文的?** 除非提示词指明语言,Kling Image 4.0 会用中文写 `web_design` 页面上的文字,在 Kling 应用里和通过 API 都是这样。在提示词末尾加上 "All text on the page in English." 即可。我们的英文页面在 1K 下生成,消耗 35 积分。 **可以用哪些预设?** [GET images/presets](/docs/api-kling-v1/get-kling-images-presets) 列出 Kling 当前的 98 种风格、16 种色调和 76 种字体,附 id 和示例图,所有账号都一样。在 `v4` 提示词中用 `@style:<id>`、`@tone:<id>` 引用,字体则用 `@font:<id>` 写在引号文字前面。它们不额外消耗积分。 ### 结语 用你已有的订阅,一次请求就能用上 Kling Image 4.0:在 [POST images/omni](/docs/api-kling-v1/post-kling-images-omni) 上设置 `omni_version: v4`,从 4 积分的 2K 图片,到 6700 万像素的 8K 照片、六格故事或整张商品页,都能生成。从 [Kling API](/docs/api-kling-v1) 文档开始,或用上面的提示词运行 [image-4 脚本](https://github.com/useapi/kling-api/tree/main/image-4)。 === URL: https://useapi.net/docs/articles/kling-image-4-api === Document URL: https://useapi.net/docs/articles/kling-image-4-api --- layout: default title: How to Generate Kling Image 4.0 Images via the Kling API description: "Generate Kling Image 4.0 images from code on your Kling AI subscription: 8K photos, Series Mode stories, style, tone and font presets, product detail pages and web designs, with real runs and costs." keywords: [Kling Image 4.0 API, Kling Image 4 API, Kling 4.0 image API, Kling 8K image, Kling Series Mode, Kling product detail page, Kling web design, Kling image presets, Kling Omni image, Kling API, Kling AI API, AI image API, Kuaishou, Kling MCP server, curl, tutorial] image: https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-8k-hummingbird.jpg parent: Articles nav_exclude: true translation_key: kling-image-4-api date: 2026-11-19 last_modified: 2026-11-19 nav_order: 856 repo: https://github.com/useapi/kling-api --- ## How to Generate Kling Image 4.0 Images via the Kling API 6 min read • November 19, 2026 ## Table of contents ### Introduction Kling Image 4.0 is Kuaishou's new image model, and the useapi.net Kling API runs it on your [Kling AI website subscription](https://kling.ai/app/membership/membership-plan): send `"omni_version": "v4"` to [POST images/omni](/docs/api-kling-v1/post-kling-images-omni). One endpoint covers everything the Kling app does with it: photos up to 8K, Series Mode stories of 2 to 10 matching images, style, tone and font presets named in the prompt, and two design skills that each make one long page image, a product detail page from a product photo and a web page design. This guide is a set of real runs on a Kling Pro subscription, one per feature, with the exact requests, the images they made and what each one cost. A 2K image used 4 credits, about $0.04 on Pro, while Kling's own developer API sells the same image for $0.06 in prepaid image packs from $300. [Watch the results in a 40-second YouTube Short](https://youtube.com/shorts/w6fuGeWJlNE): the 8K close-up, the Series Mode story, the presets, the product page and the web design. ### Before you start You need a useapi.net [API token](/docs/start-here/setup-useapi) and a Kling account connected through [Setup Kling](/docs/start-here/setup-kling), on a paid Kling plan (Standard or higher). 4K and 8K need a paid plan too. Export the token so the `curl` examples run as they are: ```bash export USEAPI_TOKEN="user:1234-..." # your useapi.net API token export KLING_EMAIL="you@example.com" # your connected Kling account ``` ### Kling Image 4.0 at a glance | Mode | Request | What you get | Credits | |---|---|---|---| | Image | `omni_version: v4` | 1 to 9 images at 2K, 4K or 8K, any of 9 aspect ratios or `auto` | 4 / 6 / 10 an image | | Series Mode | `story_mode: true` | 2 to 10 images that tell one story, or as many as Kling decides | the same, per image | | Presets | `@style:`, `@tone:`, `@font:` in the prompt | a look, a color grade or lettering from Kling's lists | no extra cost | | Product detail page | `skill: product_detail` + `image_1` | one long page from your product photo, short, medium or long | 15 to 55 a page | | Web design | `skill: web_design` | one long landing page design | 35 at 1K, 38 at 2K | Up to 10 reference images and saved [elements](/docs/api-kling-v1/get-kling-elements) work as in every Omni request: name them in the prompt as `@image_1` or `@element_1`. ### Generate an 8K image in two calls #### 1. Submit the job ```bash curl -s -X POST "https://api.useapi.net/v1/kling/images/omni" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$KLING_EMAIL"'", "omni_version": "v4", "resolution": "8k", "aspect_ratio": "16:9", "prompt": "Macro photograph of a hummingbird hovering at a red trumpet flower at sunrise, every iridescent feather sharp, dew drops on the petals, soft golden backlight, shallow depth of field" }' ``` The answer is the new task, with its id in `task.id`: ```json { "task": { "id": 123456789012345, "type": "mmu_omni_image", "status": 5, "status_name": "submitted", "status_final": false } } ``` #### 2. Poll for the result Read the task with [GET tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) until `status_final` is `true`. Each image is an item of `works`, with its URL and size: ```bash curl -s "https://api.useapi.net/v1/kling/tasks/123456789012345?email=$KLING_EMAIL" \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{status_name, works: [.works[] | {url: .resource.resource, width: .resource.width, height: .resource.height}]}' ``` ```json { "status_name": "succeed", "works": [ { "url": "https://s15-kling.klingai.com/kimg/.../image.png", "width": 10880, "height": 6144 } ] } ``` Our run made a 10880 x 6144 image, 67 megapixels, and used 6 credits. 8K lists at 10 credits, and Kling ran it at 6 during a sale that day. The same request with `"resolution": "2k"` makes a 2720 x 1536 image for 4 credits, and `"4k"` a 5440 x 3072 one for 6. <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-8k-hummingbird.jpg" alt="Kling Image 4.0 8K: a hummingbird at a red trumpet flower at sunrise" loading="lazy" style="width:100%"> Kling Image 4.0, `8k`, `16:9`, 10880 x 6144, 6 credits. Shown smaller here: open the [original](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-8k-hummingbird-original.png) (10880 x 6144 PNG, 3.5 MB) to see it at full 8K. At full size, the 8K detail holds up. This is a 1600 x 900 crop of the same file, not scaled: <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-8k-hummingbird-crop-100.jpg" alt="A 100% crop of the 8K image: the hummingbird's eye and feathers" loading="lazy" style="width:100%"> The same image at 100%, the bird's head. ### Series Mode: a story from one prompt `story_mode: true` makes a series of matching images: the same characters, style and light from panel to panel. Kling Image 4.0 makes a series from the prompt alone, with no reference image. Set `imageCount` to 2 to 10, or leave it out and Kling decides how many images the story needs. ```bash curl -s -X POST "https://api.useapi.net/v1/kling/images/omni" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$KLING_EMAIL"'", "omni_version": "v4", "story_mode": true, "aspect_ratio": "4:3", "prompt": "A picture-book story in consistent watercolor style: a small paper boat is folded by a child on a rainy city street, floats down the gutter, slips into a river past old bridges, and finally reaches the open sea at sunset" }' ``` Kling chose 6 images for this story, 2336 x 1760 each, and charged 4 credits for each, 24 in all. <div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(220px,1fr));gap:8px"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-1.jpg" alt="Series Mode 1 of 6: a child folds a paper boat on a rainy street" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-2.jpg" alt="Series Mode 2 of 6: the boat floats down the gutter" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-3.jpg" alt="Series Mode 3 of 6: the boat on a city canal" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-4.jpg" alt="Series Mode 4 of 6: the boat passes under an old bridge" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-5.jpg" alt="Series Mode 5 of 6: the boat on a wide river" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-6.jpg" alt="Series Mode 6 of 6: the boat reaches the sea at sunset" loading="lazy" style="width:100%"> </div> Kling Image 4.0 Series Mode, `story_mode: true`, `imageCount` left out, 6 images, 24 credits. Originals, 2336 x 1760 PNG: [1](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-1-original.png), [2](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-2-original.png), [3](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-3-original.png), [4](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-4-original.png), [5](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-5-original.png), [6](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-series-paper-boat-6-original.png). ### Styles, tones and fonts Kling Image 4.0 has three kinds of presets, and you name them in the prompt. [GET images/presets](/docs/api-kling-v1/get-kling-images-presets) lists them with their ids and a sample image: 98 styles, 16 tones and 76 fonts in English, Japanese, Korean and Chinese. ```bash curl -s "https://api.useapi.net/v1/kling/images/presets" -H "Authorization: Bearer $USEAPI_TOKEN" \ | jq '{styles: [.styles[0:3][] | .id], tones: [.tones[] | .id], fonts: [.fonts[] | select(.languages | index("en")) | .id][0:5]}' ``` - A tone (`@tone:<id>`) applies one of Kling's color and lighting grades: director styles, camera looks and palettes. - A font (`@font:<id>`) sets the lettering of the quoted text that follows it. - A style (`@style:<id>`) sets the overall look: 3D, 2D, material craft or photography styles. Here is the same scene without a tone and with `@tone:Nostalgic_Wuxia`, 4 credits each: <div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(280px,1fr));gap:8px"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-tone-none-swordsman.jpg" alt="No tone: a swordsman in a bamboo forest at dawn" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-tone-nostalgic-wuxia-swordsman.jpg" alt="@tone:Nostalgic_Wuxia: the same scene with a warm, faded wuxia film grade" loading="lazy" style="width:100%"> </div> Left: `A lone swordsman in a bamboo forest at dawn, mist between the stalks, wide cinematic shot`. Right: the same prompt after `@tone:Nostalgic_Wuxia`. Originals, 2720 x 1536 PNG: [no tone](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-tone-none-swordsman-original.png), [Nostalgic Wuxia](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-tone-nostalgic-wuxia-swordsman-original.png). And a shop sign without a font and with `@font:elegant_brush_hand`. Put the words you want in the image in quotation marks, and the font right before them: ```json { "prompt": "A cozy corner coffee shop at night, warm light spilling onto a wet cobblestone street, a hand-painted shop sign above the door that reads @font:elegant_brush_hand \"Moonlight Roasters\"" } ``` <div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(280px,1fr));gap:8px"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-font-none-coffee-sign.jpg" alt="No font: the sign in a plain serif" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-font-elegant-brush-hand-coffee-sign.jpg" alt="@font:elegant_brush_hand: the sign in brush script" loading="lazy" style="width:100%"> </div> Left: no font. Right: `@font:elegant_brush_hand "Moonlight Roasters"`. Originals, 2496 x 1664 PNG: [no font](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-font-none-coffee-sign-original.png), [brush font](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-font-elegant-brush-hand-coffee-sign-original.png). <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-style-3d-cartoon-corgi-astronaut.jpg" alt="@style:3d_cartoon_with_exaggerated_perspective_pro: a corgi astronaut on a candy-colored planet" loading="lazy" style="width:60%"> `@style:3d_cartoon_with_exaggerated_perspective_pro A corgi astronaut stepping out of a tiny rocket onto a candy-colored planet, looking up at the camera`, `1:1`, 4 credits. [original](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-style-3d-cartoon-corgi-astronaut-original.png)(2048 x 2048 PNG, 8.5 MB). An unknown id gets a `400` before anything reaches Kling, so a typo never costs credits. ### Reference images Name a reference in the prompt as `@image_1`. We made a product photo first, then used its URL as `image_1` for a 4K ad shot. The product, its label and its bamboo lid carry over: ```json { "omni_version": "v4", "resolution": "4k", "aspect_ratio": "16:9", "prompt": "The bottle from @image_1 standing on a mossy rock beside a mountain stream, morning mist, outdoor adventure ad", "image_1": "https://s15-kling.klingai.com/kimg/.../bottle.png" } ``` <div style="display:grid;grid-template-columns:1fr 2fr;gap:8px;align-items:start"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-product-photo-bottle.jpg" alt="The product photo: a sage-green steel bottle with a bamboo lid" loading="lazy" style="width:100%"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-4k-reference-bottle-stream.jpg" alt="4K with the product photo as a reference: the bottle beside a mountain stream" loading="lazy" style="width:100%"> </div> Left: the product photo, `3:4`, 4 credits. Right: `4k` with it as `@image_1`, 5440 x 3072, 6 credits. Originals: [product photo](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-product-photo-bottle-original.png) (1760 x 2336 PNG, 4.8 MB), [4K ad shot](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-4k-reference-bottle-stream-original.png) (5440 x 3072 PNG, 24 MB). To upload your own photo, use [POST assets](/docs/api-kling-v1/post-kling-assets) and pass the URL it returns. ### Product detail pages `skill: product_detail` turns one product photo into a long product page: a hero, highlights, close-ups and a specs table, laid out in one image. `image_1` is the photo, `prompt` says what the product does, and `length` sets the number of sections: `short` (2 to 5), `medium` (6 to 10) or `long` (11 to 18). ```bash curl -s -X POST "https://api.useapi.net/v1/kling/images/omni" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$KLING_EMAIL"'", "omni_version": "v4", "skill": "product_detail", "length": "short", "resolution": "2k", "image_1": "https://s15-kling.klingai.com/kimg/.../bottle.png", "prompt": "Insulated steel water bottle \"Trailhead\": keeps drinks cold 24 hours and hot 12, leak-proof bamboo lid, fits car cup holders, 750 ml, three colors" }' ``` The page came back as one 2048 x 13408 image for 18 credits. A `medium` page at 1K was 1024 x 9936 for 30 credits. <div style="max-height:900px;overflow-y:auto;border:1px solid #ddd"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-product-detail-page-2k-short.jpg" alt="Kling Image 4.0 product detail page: Sage Green Trailhead bottle, highlights and specs" loading="lazy" style="width:100%"> </div> `skill: product_detail`, `length: short`, `2k`, 2048 x 13408, 18 credits. Scroll the frame to see the whole page, or open the [original](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-product-detail-page-2k-short-original.png) (PNG, 1.3 MB). ### Web page designs `skill: web_design` makes a landing page design as one long image. `image_1` is optional, a picture whose style the page should follow. Kling writes the page's text in Chinese unless the prompt names the language, so end the prompt with the language you want: ```bash curl -s -X POST "https://api.useapi.net/v1/kling/images/omni" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "'"$KLING_EMAIL"'", "omni_version": "v4", "skill": "web_design", "resolution": "1k", "prompt": "Landing page for \"Ember & Oak\", a small-batch coffee roaster: warm browns and cream, elegant serif headlines, hero photo of a pour-over, three featured roasts, a monthly subscription offer and customer reviews. All text on the page in English." }' ``` <div style="max-height:900px;overflow-y:auto;border:1px solid #ddd"> <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-web-design-1k-english.jpg" alt="Kling Image 4.0 web design: Ember & Oak coffee roaster landing page in English" loading="lazy" style="width:100%"> </div> `skill: web_design`, `1k`, 1024 x 5376, 35 credits. Scroll the frame to see the whole page, or open the [original](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-web-design-1k-english-original.png) (PNG, 0.7 MB). Without the last sentence, the same prompt at 2K made the page in Chinese (2048 x 8514, 38 credits), and so did a web design made in the Kling app: <img src="https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-web-design-2k-chinese-top.jpg" alt="The same web design prompt without a language: the page text is in Chinese" loading="lazy" style="width:100%"> The top of the page without "All text on the page in English." The whole page: [original](https://media.useapi.net/kling/2026-11-19-kling-image-4-api/kling-image-4-web-design-2k-chinese-original.png) (2048 x 8514 PNG, 1.4 MB). ### What it costs Kling Image 4.0 uses your Kling AI subscription's credits, the same on every plan. Kling's developer API sells it in its own image packs, the smallest $300 for 78,216 units ($0.00384 a unit, 180 days), and also charges 0.8 units for each reference image or element. Through useapi.net, references cost nothing extra. | Model | [Official API](https://kling.ai/dev/pricing) | Premier $80.96/m (8,000 cr/mo) | Pro $32.56/m (3,000 cr/mo) | Standard $8.80/m (660 cr/mo) | |---|---|---|---|---| | Kling Image 4.0 (2K) | $0.06 (16 units) | $0.04 / 4 cr (2,000 images/mo) | $0.04 / 4 cr (750 images/mo) | $0.05 / 4 cr (165 images/mo) | | Kling Image 4.0 (4K) | $0.09 (24 units) | $0.06 / 6 cr (1,333 images/mo) | $0.07 / 6 cr (500 images/mo) | $0.08 / 6 cr (110 images/mo) | | Kling Image 4.0 (8K) | $0.15 (40 units) | $0.10 / 10 cr (800 images/mo) | $0.11 / 10 cr (300 images/mo) | $0.13 / 10 cr (66 images/mo) | | Product detail page (2K, short) | $0.28 (72 units) | $0.18 / 18 cr (444 pages/mo) | $0.20 / 18 cr (166 pages/mo) | $0.24 / 18 cr (36 pages/mo) | | Product detail page (2K, long) | $0.84 (220 units) | $0.56 / 55 cr (145 pages/mo) | $0.60 / 55 cr (54 pages/mo) | $0.73 / 55 cr (12 pages/mo) | | Web design (2K) | $0.58 (152 units) | $0.38 / 38 cr (210 pages/mo) | $0.41 / 38 cr (78 pages/mo) | $0.51 / 38 cr (17 pages/mo) | Prices as of November 19, 2026. Kling's prices for every plan are in the [Kling price calculator](/docs/api-kling-v1#pricing). Our whole run for this guide, 13 jobs that made 18 images and pages, used 181 credits, about $1.96 on Pro. ### Batch-generate with the script The [image-4 example](https://github.com/useapi/kling-api/tree/main/image-4) in our GitHub repo reads a list of prompts from `prompts.json`, the prompts of this guide, submits each one, waits for it and downloads every image: ```bash git clone https://github.com/useapi/kling-api.git cd kling-api/image-4 node ./kling-image-4.mjs $USEAPI_TOKEN $KLING_EMAIL ``` It checks each prompt before it spends credits: a product detail page needs `image_1`, a skill makes 1K or 2K, and `length` goes only with `product_detail`. ### The same from an AI assistant The hosted [Kling MCP server](/docs/api-kling-v1/mcp) at `https://api.useapi.net/v1/kling/mcp` gives Claude Code, Cursor, VS Code and the Claude app the same calls: `kling_omni_image` with `omni_version: v4`, and `kling_list_image_presets` for the style, tone and font ids. Ask for "an 8K photo of…" or "a product page from this photo" and the assistant fills in the request. ### Frequently asked questions **Is there a Kling Image 4.0 API?** Yes. useapi.net runs Kling Image 4.0 on your Kling AI subscription through [POST images/omni](/docs/api-kling-v1/post-kling-images-omni) with `omni_version: v4`: 8K, Series Mode, presets, product pages and web designs, for 4 credits a 2K image, about $0.04 on Kling Pro. Kling's own developer API sells it too, at $0.06 a 2K image in prepaid packs from $300, plus a fee for each reference image, so the subscription route is about 30% cheaper (as of November 19, 2026). **How do I get an 8K image from Kling?** Send `"omni_version": "v4", "resolution": "8k"` to [POST images/omni](/docs/api-kling-v1/post-kling-images-omni) on a paid Kling plan. Our 16:9 run came back at 10880 x 6144 for 10 credits at list price ($0.11 on Kling Pro), and Kling charged 6 during its sale. Kling's developer API charges $0.15 for the same 8K image. **Why is my Kling web design in Chinese?** Kling Image 4.0 writes a `web_design` page's text in Chinese unless the prompt names the language, in the Kling app as well as through the API. End the prompt with "All text on the page in English." Our English page came back at 1K for 35 credits. **Which presets can I use?** [GET images/presets](/docs/api-kling-v1/get-kling-images-presets) lists Kling's current 98 styles, 16 tones and 76 fonts with ids and samples, the same for every account. Name them in a `v4` prompt as `@style:<id>`, `@tone:<id>` and `@font:<id>` before quoted text. They cost no extra credits. ### Conclusion Kling Image 4.0 is one request away on the subscription you already have: `omni_version: v4` on [POST images/omni](/docs/api-kling-v1/post-kling-images-omni), from a 4-credit 2K image to a 67-megapixel 8K photo, a six-panel story or a full product page. Start with the [Kling API](/docs/api-kling-v1) docs, or run the [image-4 script](https://github.com/useapi/kling-api/tree/main/image-4) with the prompts above. === URL: https://useapi.net/docs/articles/kling-omni-bash === Document URL: https://useapi.net/docs/articles/kling-omni-bash --- layout: default title: How to Generate Multi-Reference & Multi-Shot Video with Kling Omni via the Kling API description: "Drive Kling Omni from code via a third-party REST API — blend up to 7 image references, reuse saved Video Elements, and storyboard a multi-shot sequence in one job, with copy-paste curl." keywords: [Kling Omni API, Kling multi-image reference, Kling multi-shot, Kling Video Elements, image to video, Kling Omni video, character reference, Kling API] parent: Articles nav_exclude: true date: 2026-06-22 last_modified: 2026-10-28 nav_order: 860 repo: https://github.com/useapi/kling-api --- ## How to Generate Multi-Reference & Multi-Shot Video with Kling Omni via the Kling API 7 min read • June 22, 2026 (October 28, 2026) ## Table of contents ### Introduction Kling Omni blends several image references into a single shot and storyboards a multi-shot sequence, each scene with its own prompt and duration, in one API job, from code on your [Kling AI website subscription](https://kling.ai/app/membership/membership-plan). [Kling AI](https://app.klingai.com) is the video service of the Chinese short-video company [Kuaishou Technology](https://www.kuaishou.com/en), and the third-party useapi.net [Kling API](/docs/api-kling-v1) runs it over a standard REST endpoint, with no enterprise contract and no per-video charge from us. This guide covers Omni specifically. For plain text-to-video and start/end-frame image-to-video, see the [core Kling tutorial](/docs/articles/kling-bash). ### What Omni does [POST /videos/omni](/docs/api-kling-v1/post-kling-videos-omni) is a single endpoint that selects a workflow from the inputs you pass. Three of those are what set Omni apart from the plain text-to-video and frames endpoints: - Multi-image reference — pass up to 7 reference images (`image_1`…`image_7`) and weave each into the prompt with `@image_1`, `@image_2`, … syntax, so one shot can combine a character, a prop, and a background. - Video Elements — reusable saved character/object references created once with [POST /elements](/docs/api-kling-v1/post-kling-elements), then dropped into any later generation as `@element_1` (or `@object_1`). Images and elements share the same pool of 7 slots, so the combined total can't exceed 7. - Multi-shot (v3 only) — split one video into 2–6 sequential shots, each with its own `shot_N_prompt` and `shot_N_duration`, for storytelling with scene cuts in a single job. Omni also handles a frames workflow (`frame_start`/`frame_end`) and a video-reference/transform workflow (`video_1`), but those overlap with the core endpoints — this guide focuses on the multi-reference, Video Elements, and multi-shot paths. Three model versions exist, picked with `omni_version`: `v3` (the default), `o1` and `v4` (Kling 4.0, see [the Kling 4.0 tutorial](/docs/articles/kling-4-api)). Multi-shot is v3 only, and VIDEO-type elements work on v3 and v4 — `o1` supports IMAGE elements and single-clip durations of 3–10s, while `v3` runs 3–15s. Pick quality with `mode`: `std` (720p), `pro` (1080p), or `4k` (v3 only). Durations of 7s and up, counts of 2–4, and 4K need a paid Kling AI website subscription. ### Pricing Omni videos use the credits of your Kling AI website subscription at Kling's own rates, and useapi.net adds no per-video charge. Kuaishou's [official Kling API](https://kling.ai/dev/pricing) is billed separately, on a developer account with prepaid packs. The [Kling API overview](/docs/api-kling-v1) has a live cost calculator for every model on each Kling plan. ### Generate a multi-reference video in two API calls You need a useapi.net [API token](/docs/start-here/setup-useapi) and a connected [Kling account](/docs/start-here/setup-kling) — export the token so the `curl` examples below run as-is: ```bash export USEAPI_TOKEN="user:1234-..." ``` Generation is asynchronous — the create call returns a task object immediately, then you poll until the video is ready. First, upload each reference image with [POST /assets](/docs/api-kling-v1/post-kling-assets) (raw bytes, an image `Content-Type`, max 10 MB, 300px minimum). It returns a Kling-hosted `url`: ```bash curl "https://api.useapi.net/v1/kling/assets/?email=user@example.com" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: image/jpeg" \ --data-binary @character.jpg ``` ```json { "status": 3, "url": "https://s21-kling.klingai.com/....jpg", "fileName": "abc123def456789.jpg" } ``` #### 1. Submit the job `POST https://api.useapi.net/v1/kling/videos/omni`. Pass each uploaded URL as `image_1`, `image_2`, … and reference them by name in the prompt: ```bash curl -X POST "https://api.useapi.net/v1/kling/videos/omni" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A woman @image_1 walking through the garden @image_2, holding the lantern @image_3, camera pushing in slowly", "omni_version": "v3", "mode": "pro", "aspect_ratio": "16:9", "duration": "5", "image_1": "https://s21-kling.klingai.com/.../character.jpg", "image_2": "https://s21-kling.klingai.com/.../garden.jpg", "image_3": "https://s21-kling.klingai.com/.../lantern.jpg" }' ``` The response returns immediately with a task object of type `m2v_omni_video`. The task id you poll on is `task.id` (a number): ```json { "task": { "id": 123456789, "type": "m2v_omni_video", "status": 5, "status_name": "submitted", "status_final": false }, "works": [], "status": 5, "status_name": "submitted", "status_final": false, "message": "" } ``` The `email` field is optional: without it, the API picks one of your Kling accounts that has a free job slot (`429` when every account is busy). With more than one account, note which account ran the job ([GET tasks/`task_id`](/docs/api-kling-v1/get-kling-tasks-task_id) explains how to find it), because polling the task needs that account's `email`, and pass the `email` of the account that saved your elements when a prompt uses `@element_N`. A `500` from Kling almost always means a content-moderation rejection rather than a server fault — read the `error` text (the `message` field is generic and often misleading) to tell them apart. `prompt` maxes out at 1700 characters and references each input by its `@`-name (`@image_1`, `@element_1`, `@video_1`). #### 2. Poll for the result `GET https://api.useapi.net/v1/kling/tasks/{task_id}`: ```bash curl "https://api.useapi.net/v1/kling/tasks/123456789?email=user@example.com" \ -H "Authorization: Bearer $USEAPI_TOKEN" ``` The task is done when `status_final` is `true`. Success is `status_name: "succeed"` (`status: 99`), and the MP4 is in `works[0].resource.resource`: ```json { "status": 99, "status_name": "succeed", "status_final": true, "works": [ { "workId": 123456789, "status_name": "succeed", "resource": { "resource": "https://s21-kling.klingai.com/....mp4", "height": 720, "width": 1280, "duration": 5041 } } ] } ``` The MP4 at `works[0].resource.resource` is watermarked. To get the clean, non-watermarked master, take the `workId` from the `works` array and call [GET /assets/download](/docs/api-kling-v1/get-kling-assets-download) — it returns a `cdnUrl` to the file (a single `workId` plus a single `fileTypes` value yields a direct MP4 link, otherwise a `.zip`): ```bash curl "https://api.useapi.net/v1/kling/assets/download?email=user@example.com&workIds=123456789&fileTypes=MP4" \ -H "Authorization: Bearer $USEAPI_TOKEN" ``` On the poll, a `404` means the task was deleted, failed at moderation, or your Kling account ran out of credits — check your balance at [GET /accounts/`email`](/docs/api-kling-v1/get-kling-accounts-email). Prefer not to poll? Pass a `replyUrl` in the create body to receive a webhook callback when the task completes. ### Multi-shot sequences (v3) Instead of one `prompt` and one `duration`, v3 Omni lets you storyboard a single video as 2–6 sequential shots, each with its own `shot_N_prompt` and matching `shot_N_duration`. The total of all durations must land between 3 and 15 seconds, shots must be sequential with no gaps (`shot_1` + `shot_2`, never `shot_1` + `shot_3`), and the multi-shot parameters cannot be combined with `prompt` or `duration`. Each shot prompt can carry the same `@image_N` / `@element_N` references as a single-shot job, so a recurring character holds across cuts: ```bash curl -X POST "https://api.useapi.net/v1/kling/videos/omni" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "omni_version": "v3", "mode": "pro", "aspect_ratio": "16:9", "image_1": "https://s21-kling.klingai.com/.../kitchen.jpg", "shot_1_prompt": "Cinematic medium shot, a chef standing behind a stainless steel stove @image_1, focused intently on the pan", "shot_1_duration": "3", "shot_2_prompt": "Continuous scene at the same stove @image_1. The chef flips the food high into the air, then turns sharply to the camera", "shot_2_duration": "3" }' ``` The response, polling, and clean download are identical to the single-shot flow above — the create call returns the same `task.id`, and the finished sequence comes back as one MP4 in `works[0]`. ### Video Elements A Video Element is a reusable character or object reference you create once and drop into any later Omni job by ID — so the same face, costume, or prop stays consistent across separate generations without re-uploading and re-describing it each time. Create one with [POST /elements](/docs/api-kling-v1/post-kling-elements). There are two types: - IMAGE elements — built from a `coverImage` URL (optionally with extra angle views, or AI-generated multi-angle views via `generateViews`). Usable in `o1`, `v3` and `v4` Omni. - VIDEO elements — built from a `video` URL (mp4, minimum 3 seconds, auto-trimmed to 8s), which captures motion and can carry a voice. VIDEO elements work in v3 and v4 Omni. Upload the cover image (or clip) with [POST /assets](/docs/api-kling-v1/post-kling-assets) first, then register the element: ```bash curl -X POST "https://api.useapi.net/v1/kling/elements" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "FashionLady", "coverImage": "https://s21-kling.klingai.com/.../character.jpg", "tag": "character" }' ``` It returns a generated element `id` (a 5-character random suffix is appended to your `name`): ```json { "elements": [ { "id": "u_123456789012345", "name": "FashionLady ABC12", "description": "Elegant woman in red dress" } ], "count": 1 } ``` The `tag` is one of `character`, `animal`, `prop`, `costume`, `scene`, `effect`, or `others` (from [GET /elements/tags](/docs/api-kling-v1/get-kling-elements-tags)) — leave it out to have Kling auto-detect it. List your saved elements anytime with [GET /elements](/docs/api-kling-v1/get-kling-elements). Then reference the element by ID in any Omni prompt, alone or alongside images (remember the combined 7-slot limit): ```bash curl -X POST "https://api.useapi.net/v1/kling/videos/omni" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Character @element_1 walking through a sunlit garden, smiling", "omni_version": "v3", "mode": "std", "duration": "5", "element_1": "u_123456789012345" }' ``` A `character`-tagged element can also carry a `voice` — an official voice name/ID from [GET /elements/voices](/docs/api-kling-v1/get-kling-elements-voices), or a 5–60s mp4 to clone one from. For a VIDEO element, voice is extracted automatically from the source clip when it has 5–60 seconds of audio. ### Batch script Finding the right shot takes many attempts, and running them by hand is tedious. The Node.js script below reads a list of prompts from `prompts.json`, submits each one to the Omni endpoint — single-shot (`prompt` + image/element refs) or multi-shot (`shots`) — then polls every task until it is final and downloads the finished MP4, preferring the clean, non-watermarked master via [GET /assets/download](/docs/api-kling-v1/get-kling-assets-download) and falling back to the watermarked `works[0].resource.resource` if needed. So you can queue a batch and come back to the winners. You need [Node.js](https://nodejs.org) v21 or newer. Put `prompts.json` and `kling-omni.mjs` in the same folder and run `node ./kling-omni.mjs API_TOKEN EMAIL`, where `API_TOKEN` is your useapi.net [API token](/docs/start-here/setup-useapi) and `EMAIL` is your connected [Kling account](/docs/start-here/setup-kling) email. The script looks the account up by email automatically. Pass image URLs (already uploaded via [POST /assets](/docs/api-kling-v1/post-kling-assets)) as `image_1`…`image_7`, and saved [element](/docs/api-kling-v1/post-kling-elements) IDs as `element_1`…`element_7`. <details markdown="block"> <summary>Expand `prompts.json`</summary> ```json [ { "prompt": "A single-shot Omni job: by default the v3 model with a 16:9 aspect ratio, std (720p) mode and a 5-second duration is used." }, { "omni_version": "v3", "mode": "pro", "aspect_ratio": "16:9", "duration": "5", "image_1": "https://s21-kling.klingai.com/.../character.jpg", "image_2": "https://s21-kling.klingai.com/.../garden.jpg", "prompt": "Multi-image reference: A woman @image_1 walking through the garden @image_2, camera pushing in. For all parameters see https://useapi.net/docs/api-kling-v1/post-kling-videos-omni" }, { "omni_version": "v3", "mode": "std", "duration": "5", "element_1": "u_123456789012345", "prompt": "Saved Video Element by ID: Character @element_1 walking through a sunlit garden, smiling." }, { "omni_version": "v3", "mode": "pro", "aspect_ratio": "16:9", "image_1": "https://s21-kling.klingai.com/.../kitchen.jpg", "shots": [ { "prompt": "Cinematic medium shot, a chef standing behind a stainless steel stove @image_1, focused intently on the pan.", "duration": "3" }, { "prompt": "Continuous scene at the same stove @image_1. The chef flips the food high into the air, then turns sharply to the camera.", "duration": "3" } ] } ] ``` </details> <details markdown="block"> <summary>Expand `kling-omni.mjs` script</summary> ```javascript /* Script version 1.0, June 22, 2026 Script to batch-generate videos using prompts with the Kling API v1 by useapi.net 🚀 Uses the asynchronous Omni endpoint (POST /videos/omni): multi-image reference, saved Video Elements, and v3 multi-shot sequences. For more details visit https://useapi.net/docs/api-kling-v1/post-kling-videos-omni Installation Instructions: ========================== You need Node.js v21 or newer installed to run this script. Download and install Node.js from: - Windows, macOS, Linux: https://nodejs.org/ After installation, verify by running the following command in a terminal: node -v Running the Script: =================== Usage: node kling-omni.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE] Replace API_TOKEN with your actual useapi.net API token, see https://useapi.net/docs/start-here/setup-useapi Replace EMAIL with configured Kling email account, see https://useapi.net/docs/start-here/setup-kling If optional PROMPTS_FILE not provided prompts.json will be used. Upload reference images first via POST /assets (https://useapi.net/docs/api-kling-v1/post-kling-assets) and pass the returned URLs as image_1..image_7. Pass saved element IDs as element_1..element_7 (create them via POST /elements, https://useapi.net/docs/api-kling-v1/post-kling-elements). Example: -------- node kling-omni.mjs user:1234-abcdefhijklmnopqrstuv my@email.com This command executes the script using API token user:1234-abcdefhijklmnopqrstuv with my@email.com Kling account email. Changelog: ========== - June 22, 2026: Initial release. */ import readline from 'node:readline'; import fs from 'fs/promises'; import { writeFile } from 'node:fs/promises'; import { Readable } from 'node:stream'; // Constants const RESULTS_FILE = 'kling_omni_results.txt'; const ERRORS_FILE = 'kling_omni_errors.txt'; const DEFAULT_PROMPTS_FILE = 'prompts.json'; const SLEEP_429 = 10 * 1000; // in milliseconds const MAX_429_RETRIES = 6; // give up a prompt after this many consecutive 429s (all accounts busy) const SLEEP_POLL = 20 * 1000; // in milliseconds const urlAccounts = 'https://api.useapi.net/v1/kling/accounts'; const urlOmni = 'https://api.useapi.net/v1/kling/videos/omni'; const urlTask = 'https://api.useapi.net/v1/kling/tasks/'; const urlAssetsDownload = 'https://api.useapi.net/v1/kling/assets/download'; // Utility to sleep for given milliseconds const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); // Function to fetch configured Kling API accounts async function fetchAccounts(apiToken) { const response = await fetch(urlAccounts, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.error(`⛔ Error fetching accounts (HTTP ${response.status}): ${response.statusText}`); process.exit(1); } return response.json(); } // A short label for logging — the single prompt, or the first shot prompt. function promptLabel(prompt) { if (prompt.prompt) return prompt.prompt; if (Array.isArray(prompt.shots) && prompt.shots.length) return prompt.shots[0].prompt ?? ''; return ''; } // Build the request body for a single Omni job. // Multi-shot: an array of { prompt, duration } in prompt.shots → shot_N_prompt / shot_N_duration. // Single-shot: prompt + optional duration. Both carry image_N / element_N references. function buildBody(email, prompt) { const { prompt: text, omni_version, mode, aspect_ratio, duration, count, shots } = prompt; const body = { email, omni_version, mode, aspect_ratio, count }; // Pass through any image_1..image_7 and element_1..element_7 references. for (let i = 1; i <= 7; i++) { if (prompt[`image_${i}`]) body[`image_${i}`] = prompt[`image_${i}`]; if (prompt[`element_${i}`]) body[`element_${i}`] = prompt[`element_${i}`]; } if (Array.isArray(shots) && shots.length) { // Multi-shot (v3 only) — cannot be combined with prompt/duration. shots.forEach((shot, idx) => { body[`shot_${idx + 1}_prompt`] = shot.prompt; body[`shot_${idx + 1}_duration`] = shot.duration; }); } else { body.prompt = text; body.duration = duration; } return JSON.stringify(body); } // Submit a single Omni prompt. Returns { status, taskId }. async function submitVideo(apiToken, email, prompt, index) { const useVersion = prompt.omni_version ?? 'v3'; const label = promptLabel(prompt); console.log(`🚀 omni ${useVersion} » Prompt #${index} • ${email} …`); const body = buildBody(email, prompt); const createResponse = await fetch(urlOmni, { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiToken}` }, body }); const createBody = await createResponse.text(); if (createResponse.status == 200) { const json = JSON.parse(createBody); const taskId = json?.task?.id; if (taskId) { await fs.appendFile(RESULTS_FILE, `${taskId},#${index}:${label}\n`); console.log(`✅ task.id`, taskId); return { status: 200, taskId }; } else { const error = `No task.id found in HTTP 200 response`; console.log(`❓ ${error}`, createBody); await fs.appendFile(ERRORS_FILE, `${error},#${index}:${label}\n`); return { status: 500 }; } } else { switch (createResponse.status) { case 429: console.log(`🔄️ Retry on HTTP ${createResponse.status} (all accounts at capacity)`); break; case 400: console.log(`🛑 Validation error`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${label}\n`); break; case 500: // Kling returns 500 for content moderation as well as real server faults. console.log(`🛑 Rejected (likely content moderation — check the error text)`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${label}\n`); break; default: console.log(`❗ FAILED with HTTP ${createResponse.status}`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${label}\n`); } return { status: createResponse.status }; } } // Resolve the clean, non-watermarked master URL for a workId via GET /assets/download. // Returns the cdnUrl, or undefined when unavailable. async function fetchCleanUrl(apiToken, email, workId) { const url = `${urlAssetsDownload}?email=${encodeURIComponent(email)}&workIds=${workId}&fileTypes=MP4`; try { const response = await fetch(url, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (response.ok) { const json = await response.json(); if (json?.cdnUrl) return json.cdnUrl; } else { console.log(`⚠️ assets/download HTTP ${response.status} for workId ${workId}, falling back to watermarked`, await response.text()); } } catch (err) { console.log(`⚠️ assets/download error for workId ${workId}, falling back to watermarked`, err); } return undefined; } // Poll every submitted task until it is final, then download the result. async function download(apiToken, email) { if (! await fileExists(RESULTS_FILE)) return; try { const resultsContent = await fs.readFile(RESULTS_FILE, 'utf8'); const lines = resultsContent.trim().split('\n'); for (const line of lines) { const [taskId, prompt] = line.split(','); const videoFilename = `kling_omni_${taskId}.mp4`; console.log(`👉 ${taskId}`); try { await fs.access(videoFilename); console.log(`⚠️ ${videoFilename} already exists. Skipping download.`); continue; } catch { // File does not exist, proceed with downloading } while (true) { const response = await fetch(`${urlTask}${taskId}?email=${encodeURIComponent(email)}`, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { // 404 = task deleted, failed at moderation, or out of credits. console.log(`🛑 Poll failed ${taskId} (HTTP ${response.status}):\n${prompt}\n`, await response.text()); break; } const task = await response.json(); const { status, status_name, status_final, works, error, message } = task; if (status_final && status_name !== 'succeed') { console.error(`🛑 FAILED ${taskId} (status ${status} ${status_name}${error ? ` — ${error}` : ''}${message ? ` — ${message}` : ''}):\n${prompt}\n`); break; } if (status_final && status_name === 'succeed') { const work = works?.[0]; const watermarkedUrl = work?.resource?.resource; const workId = work?.workId; // Prefer the clean master; fall back to the watermarked resource. const cleanUrl = workId ? await fetchCleanUrl(apiToken, email, workId) : undefined; const url = cleanUrl ?? watermarkedUrl; if (url) { console.log(`✅ Downloading ${cleanUrl ? 'clean master' : 'watermarked'} ${url} to ${videoFilename}`); try { const videoResponse = await fetch(url); if (!videoResponse.ok) { console.error(`⛔ Unable to download ${taskId} (HTTP ${videoResponse.status}):\n${prompt}\n`, url); break; } const stream = Readable.fromWeb(videoResponse.body); await writeFile(videoFilename, stream); } catch (err) { console.error(`⛔ Error during download: ${err}`); } } else console.error(`🛑 Unable to download ${taskId}, no resource URL in succeeded task:\n${prompt}\n`); break; } console.log(`⌛ ${taskId} status (${status_name}) and is still in progress, waiting…`); await sleep(SLEEP_POLL); } } } catch (error) { console.log(`⛔ Error during download:`, error.stack || error); } } // Main function async function main() { const apiToken = process.argv[2]; const email = process.argv[3]; const promptFile = process.argv[4] || DEFAULT_PROMPTS_FILE; if (!apiToken || !email) { console.error('Usage: node kling-omni.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE]'); process.exit(1); } console.info('Script v1.0'); console.info('Node version is: ' + process.version); try { if (await fileExists(RESULTS_FILE)) { let user_input; while (!['y', 'n'].includes(user_input)) { user_input = (await promptUser(`❔ ${RESULTS_FILE} file detected. Do you want to download the results now? (y/n): `))?.toLowerCase(); if (user_input == 'y') { await download(apiToken, email); await fs.unlink(RESULTS_FILE); } } } const start = new Date(); try { console.info('START EXECUTION', start); await execute(apiToken, email, promptFile); } finally { console.info('COMPLETED', new Date()); console.info('EXECUTION ELAPSED', diffInMinutesAndSeconds(start, new Date())); } try { console.info('START DOWNLOAD', start); await download(apiToken, email); } finally { console.info('TOTAL ELAPSED', diffInMinutesAndSeconds(start, new Date())); } } catch (error) { console.error('⛔ Error during execution:', error.stack || error); } } async function execute(apiToken, email, promptFile) { const accounts = await fetchAccounts(apiToken); const accountList = Object.values(accounts); console.info(`Configured Kling API accounts (${accountList.length}):`, accountList.map(a => a.email).join(', ')); if (accountList.length <= 0) { console.error(`⛔ No configured Kling accounts found. Please refer to https://useapi.net/docs/start-here/setup-kling`); process.exit(1); } // Match the account by email. const matched = accountList.find(a => a.email === email); if (!matched) { console.error(`⛔ Account with email ${email} not found. Please refer to https://useapi.net/docs/start-here/setup-kling`); process.exit(1); } const promptData = await fs.readFile(promptFile, 'utf8'); const prompts = JSON.parse(promptData); console.log(`Total number of prompts to process`, prompts.length); let warnings = []; // Parameters accepted by this script for the Omni endpoint. // See https://useapi.net/docs/api-kling-v1/post-kling-videos-omni for the full parameter set. const baseParams = ['prompt', 'omni_version', 'mode', 'aspect_ratio', 'duration', 'count', 'shots']; const refParams = (n) => [`image_${n}`, `element_${n}`]; const supportedParams = [...baseParams, ...[1, 2, 3, 4, 5, 6, 7].flatMap(refParams)]; const invalidKeys = (prompt) => Object.keys(prompt).filter(key => !key.startsWith('__') && !supportedParams.includes(key)) for (let i = 1; i <= prompts.length; i++) { const prompt = prompts[i - 1]; const { prompt: text, shots } = prompt; const notSupported = invalidKeys(prompt); if (notSupported.length) warnings.push(`⚠️ Following params not supported: ${notSupported.join(',')}. Prompt ${i}`); const hasShots = Array.isArray(shots) && shots.length > 0; if (!text && !hasShots) warnings.push(`⚠️ Please specify a prompt or a shots array. Prompt ${i}`); if (text && hasShots) warnings.push(`⚠️ prompt and shots cannot be combined — multi-shot replaces the single prompt. Prompt ${i}`); if (hasShots) { if (shots.length < 2 || shots.length > 6) warnings.push(`⚠️ multi-shot requires 2 to 6 shots. Prompt ${i}`); const total = shots.reduce((sum, s) => sum + Number(s.duration || 0), 0); if (total < 3 || total > 15) warnings.push(`⚠️ total shot duration must be 3-15 seconds (got ${total}). Prompt ${i}`); shots.forEach((s, idx) => { if (!s.prompt || !s.duration) warnings.push(`⚠️ each shot needs both prompt and duration (shot ${idx + 1}). Prompt ${i}`); }); } if (text && text.length > 1700) warnings.push(`⚠️ prompt exceeds 1700 characters. Prompt ${i}`); } if (warnings.length > 0) { warnings.forEach(warning => console.warn(warning)); console.error(`⛔ Execution stopped due to warnings.`); process.exit(1); } for (let i = 0; i < prompts.length; i++) { const prompt = prompts[i]; let retries429 = 0; while (true) { const { status } = await submitVideo(apiToken, email, prompt, i + 1); if (status == 429) { if (++retries429 > MAX_429_RETRIES) { console.error(`⛔ Gave up on prompt #${i + 1} after ${MAX_429_RETRIES} retries — all accounts still busy.`); await fs.appendFile(ERRORS_FILE, `429 (gave up after ${MAX_429_RETRIES} retries),#${i + 1}\n`); break; } await sleep(SLEEP_429); } else break; } } } // Utility function to check if a file exists async function fileExists(path) { try { await fs.access(path); return true; } catch { return false; } } // Function to prompt user input async function promptUser(query) { const rl = readline.createInterface({ input: process.stdin, output: process.stdout }); return new Promise((resolve) => rl.question(query, answer => { rl.close(); resolve(answer); })); } function diffInMinutesAndSeconds(date1, date2) { const diffInSeconds = Math.floor((date2 - date1) / 1000); return `${Math.floor(diffInSeconds / 60)} minutes ${diffInSeconds % 60} seconds`; }; main(); ``` </details> ### Examples The clips below are real Kling Omni generations produced through this Kling API, straight from our blog walkthroughs. ###### Multi-shot v3 — text-only 2-shot sequence via `POST /videos/omni` (`omni_version: v3`) <video poster="https://media.useapi.net/blog/2026-02-16-260216/v3-omni-text-result-poster.jpg" src="https://media.useapi.net/blog/2026-02-16-260216/v3-omni-text-result.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> — from [Kling v3: Multi-Shot Storytelling](/blog/260216) Also on YouTube: [Mission: Kitchen Impossible • Kling v3 multi-shot](https://www.youtube.com/watch?v=Ti8oHAvg7Cw). ###### Video Elements v3 — two VIDEO elements + a background image, 720p ~11s via `POST /videos/omni` (`omni_version: v3`, `mode: std`) <video poster="https://media.useapi.net/blog/2026-02-09-260209/elements-v3-results-720p-11sec-poster.jpg" src="https://media.useapi.net/blog/2026-02-09-260209/elements-v3-results-720p-11sec.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> — from [Kling v3: 4K Resolution and Video Elements](/blog/260209) ### Frequently asked questions **What is Kling Omni?** Through useapi.net, Omni is one Kling video endpoint, [POST /videos/omni](/docs/api-kling-v1/post-kling-videos-omni), that picks a workflow from your inputs: blend several image references, reuse saved Video Elements (`@element_1`…), storyboard a v3 multi-shot sequence, run a start/end-frame transition, or guide the video from a reference clip. See [What Omni does](#what-omni-does) above. **How do I pass multiple image references to Kling?** Through useapi.net, upload each image with [POST /assets](/docs/api-kling-v1/post-kling-assets), pass the returned URLs as `image_1`, `image_2` and so on (up to 7), and name them in the prompt as `@image_1`, `@image_2`. Images and saved elements share the same pool of 7 slots, so the combined total can't exceed 7. See [Generate a multi-reference video in two API calls](#generate-a-multi-reference-video-in-two-api-calls) above. **What are Video Elements and how do I reuse a character?** Through useapi.net, a Video Element is a reusable character or object reference created once with [POST /elements](/docs/api-kling-v1/post-kling-elements), as an IMAGE element from a `coverImage` or a VIDEO element from an mp4 clip. It returns an `id` like `u_123…`, which you then drop into any Omni prompt as `@element_1`, so the same face or costume holds across separate videos. See [Video Elements](#video-elements) above. **How does Kling multi-shot work?** Through useapi.net, on v3 Omni you set `shot_1_prompt`/`shot_1_duration` through `shot_6_prompt`/`shot_6_duration` (at least 2 shots) instead of a single `prompt`/`duration`. Shots must be sequential with no gaps, the total must be 3–15 seconds, and each shot prompt can carry the same `@image_N` and `@element_N` references, so a character holds across cuts. See [Multi-shot sequences (v3)](#multi-shot-sequences-v3) above. **Which Omni version supports multi-shot and Video Elements?** Through useapi.net, multi-shot runs on `v3` (the default) only, and VIDEO elements on `v3` and `v4` ([Kling 4.0](/docs/articles/kling-4-api)). The older `o1` takes IMAGE elements and shorter single clips, while `v3` also adds `4k` mode and longer clips. Pick the version with `omni_version`. See [What Omni does](#what-omni-does) above. **Why is my Omni video watermarked?** Through useapi.net, the MP4 at `works[0].resource.resource` is Kling's watermarked preview. For the clean master, take the `workId` from the task's `works` array and call [GET /assets/download](/docs/api-kling-v1/get-kling-assets-download), which returns a `cdnUrl` to the file without the watermark. This needs a paid Kling AI website subscription. See [Generate a multi-reference video in two API calls](#generate-a-multi-reference-video-in-two-api-calls) above. **My generation returns a 500 — what does that mean?** Through useapi.net, a `500` from Kling usually means a content-moderation rejection rather than a server fault, because Kling reuses that code for both and its `message` field rarely tells them apart. Read the `error` text instead. If a job clears creation but the poll later returns `404`, the task was deleted, failed at moderation, or the account ran out of credits. **How is this different from the official Kling API?** Through useapi.net, Omni runs on your [Kling AI website subscription](https://kling.ai/app/membership/membership-plan), Kling 4.0 Omni (`omni_version: v4`) included, which Kling's developer API sells only in separate prepaid packs from $500 (as of October 28, 2026). One useapi.net token also covers [10+ other AI services](/). Kuaishou's [official Kling API](https://kling.ai/dev/pricing) bills every generation at developer rates on a separate developer account, with video packs from $700 (as of October 2026). ### Conclusion Visit our <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> or <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> for any support questions and concerns. The full runnable example is in the [`kling-api` GitHub repo](https://github.com/useapi/kling-api). #### Cross posted Also published on [dev.to](https://dev.to/useapi/how-to-generate-multi-reference-multi-shot-video-with-kling-omni-via-the-kling-api-1091){:rel="nofollow"}. === URL: https://useapi.net/docs/articles/meta-muse-video-api === Document URL: https://useapi.net/docs/articles/meta-muse-video-api --- layout: default title: "Is There a Meta Muse Video API? Official API, Free Tools and a Hosted API (2026)" seo_title: "Is There a Meta Muse Video API? Official vs muse2api vs useapi.net (2026)" description: "Meta sells no Muse video API, only Muse Image and text models. The hosted useapi.net Muse API makes 10-second Muse videos on your Muse website subscription, compared here with muse2api and resellers." keywords: [Meta Muse video API, Muse API, Meta Muse API, muse api, meta muse api key, muse ai video generator api, muse ai api, muse.ai API, muse2api, muse2api alternative, free muse api, Muse API pricing, Meta Model API, Muse Image API, Muse Wonder API, Muse agent API, Muse MCP server, talking photo API, AI video with sound API] image: https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-cover.jpg parent: Articles nav_exclude: true date: 2026-10-18 last_modified: 2026-11-07 nav_order: 905 repo: https://github.com/useapi/muse-api --- ## Is There a Meta Muse Video API? Official API, Free Tools and a Hosted API (2026) 6 min read • October 18, 2026 (November 7, 2026) ## Table of contents ### Does Meta Muse have a video API? Meta has no Muse video API (as of October 30, 2026): its official [Model API](https://dev.meta.ai/docs/models) sells the Muse Image model, the Muse Wonder and Muse Spark text models, Muse Voice Transcribe for speech to text and SAM 3.1 for segmentation, and none of them outputs video. The 10-second videos with sound that Muse makes at [muse.ai](https://muse.ai) are reached through third-party tools that drive the Muse agent on your [Muse website subscription](https://www.meta.com/help/subscriptions/1021145227643680/), such as the hosted [useapi.net Muse API](/docs/api-muse-v1). There are three kinds of options: 1. Meta's Model API, if you need Muse images or the Muse text models. It sells Muse Image at $0.01 per image, and Muse Wonder (launched on October 12, 2026) at $4 per million input tokens and $20 per million output tokens ([Meta pricing](https://dev.meta.ai/docs/pricing-rate-limits), [TechCrunch](https://techcrunch.com/2026/10/12/meta-releases-its-first-frontier-model-muse-wonder)). 2. Free self-hosted tools, such as [muse2api](https://github.com/czg86389-hub/muse2api), an open-source server that wraps muse.ai in OpenAI-compatible endpoints, and local MCP bridges such as [Muse-Chat-MCP](https://github.com/duclm1x1/Muse-Chat-MCP), which drives your logged-in Chrome. You run them on your own machine or server. 3. Hosted APIs: per-request resellers such as [museai.suncodevn.com](https://museai.suncodevn.com), which sell credit packs, and the [useapi.net Muse API](/docs/api-muse-v1), which runs on your Muse website subscription with no per-video charge, over REST and as a hosted [MCP server](/docs/api-muse-v1/mcp). This page is written by the useapi.net maintainers and compares what each option offers from its own documentation. ### Compared | | useapi.net | Meta Model API | muse2api | Per-request resellers | |---|:--:|:--:|:--:|:--:| | Muse video generation | Yes | No (no video model) | Yes | Yes | | Chat with the Muse agent at muse.ai | Yes | No (Muse Wonder and Spark models, not the agent) | Yes | Yes | | Hosted, nothing to install or run | Yes | Yes | No (Docker or a VPS) | Yes | | Sign in with email and password, no cookies to copy, session renewed for you | Yes | API key | No (browser cookies pushed by an extension) | No (cookie pools) | | No per-video charge | Yes | no video | Yes | No (credits per video, also when it runs on your Meta account) | | Hosted MCP server for Claude Code, Cursor, VS Code | Yes | not in its docs | not in its docs | not in its docs | | Price | Your Muse website subscription (the free plan made about 30 to 50 videos a week) | $0.01 per image, text models per token | Free, you host it | 6 credits a video, packs from $3.90 for 500 credits | From each option's own documentation and pricing on October 30, 2026: Meta [models](https://dev.meta.ai/docs/models) and [pricing](https://dev.meta.ai/docs/pricing-rate-limits), [muse2api](https://github.com/czg86389-hub/muse2api) v1.6.9 (checked November 7), and museai.suncodevn.com's [published plans](https://museai.suncodevn.com/api/billing/plans) as the per-request example (on your Meta account it charges 4 credits a video on its Developer and Pro plans). useapi.net is a third-party API and is not affiliated with Meta. ### Why useapi.net for Meta Muse video - [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video) makes a video of about 10 seconds at about 720p, with sound, from text, a photo or another video. Lines written in quotes are spoken, so a single photo becomes a talking photo, and a person in a clip can be swapped for someone from a photo. - [POST /chats](/docs/api-muse-v1/post-muse-chats) talks to the whole Muse agent at muse.ai, with its answers streamed live over Server-Sent Events, and you can [watch and take over its web browser](/docs/api-muse-v1/live-browser-guide). - The hosted [MCP server](/docs/api-muse-v1/mcp) has 37 tools and adds to Claude Code, Cursor or VS Code with one line. It is listed in the official MCP Registry as `net.useapi/muse`, and there is nothing to install. - There is nothing to run on your machine, with no server to deploy, no browser to keep open and no extension to install. Jobs keep running when your laptop is off. - You add the account once with its email and password, and we keep it signed in and renew its 30-day Muse session, with no cookies to copy or refresh. - It runs on your Muse website subscription, and the free plan works. Each video uses about 2 to 3 percent of the free plan's weekly allowance in our tests. - Each subscription adds 3 Muse accounts, and a job without an `email` goes to a healthy account with allowance left and a free slot. - A job can wait for the finished file, or you send `async: true` and the job record is posted to your `replyUrl`. - A ready-made [n8n template]() and an [agent skill](https://github.com/useapi/muse-api/tree/main/skills/muse-video) get you started, with no per-image or per-video charge from us. <video poster="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g3-poster.jpg" src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g3.mp4" style="width: 100%; aspect-ratio: 1248/704; max-width: 720px" controls type="video/mp4" preload="metadata"></video> A Muse video made through the useapi.net API: the rider from a photo swapped into a clip Muse made from a still image. Every request is in the [tutorial](/docs/articles/muse-images-videos#8-swap-the-rider-in-the-video). ### How to start What the Muse account needs: - Muse is available in the US, Canada, [Japan](https://about.fb.com/ja/news/2026/10/muse-personal-ai-agent-launches-in-japan/) and [Singapore](https://about.fb.com/news/2026/10/muse-is-now-available-in-singapore-the-worlds-first-personal-ai-agent-built-for-everyone/) (as of October 30, 2026), so create the account in one of them. Once it is added, you can call the API from anywhere. - Finish Muse's onboarding at [muse.ai](https://muse.ai), including Meta's age check, and create one image there. - The account must have email + password sign-in, because the API signs in with the email and password. A Meta account that signs in only with an emailed code has no password yet: create one in [Meta Accounts Center](https://accountscenter.meta.com/password_and_security/) (Password and security), then add the account here. Without a password the add is refused with `400`. - Use the account only for the API, with no other automation tools on it. Opening it at muse.ai in a browser is fine, but only from the US, Canada, Japan or Singapore (the regions Muse officially supports), or through a VPN in one of them: Meta can switch off video for an account it sees used from elsewhere. Then: 1. Get a useapi.net [API token](/docs/start-here/setup-useapi). 2. Add your Muse account once with [Setup Muse](/docs/start-here/setup-muse). The free Muse plan works. 3. Make a 10-second video with sound in one call: ```bash curl -X POST https://api.useapi.net/v1/muse/jobs/video \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{"prompt": "A golden retriever runs along a beach at sunset while the camera tracks beside it. A man off screen calls: \"Good boy, come here!\" In exactly 16:9 aspect ratio."}' ``` The request waits for the video, which took 60 to 140 seconds in our tests, and answers with the job record. The video is the first `assetId` in `result.assets[]`: download it with [GET /assets/`assetId`](/docs/api-muse-v1/get-muse-assets-assetId). A slower job answers `202`, and you fetch it with [GET /jobs/`jobid`](/docs/api-muse-v1/get-muse-jobs-jobid). Or add the [MCP server](/docs/api-muse-v1/mcp) to Claude Code with one line: ```bash claude mcp add --transport http useapi-muse https://api.useapi.net/v1/muse/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` Step-by-step tutorial: [How to Generate AI Videos and Images with the Meta Muse API](/docs/articles/muse-images-videos) (talking photos, image to video, person swap, photo restoration). Runnable code: [useapi/muse-api](https://github.com/useapi/muse-api). ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. ### Frequently asked questions **Is there a Muse API?** Through useapi.net, yes: [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video) makes an MP4 of about 10 seconds at about 720p with sound, from a prompt, up to 9 images, 3 videos or 3 audio files, and a line written in quotes is spoken. Meta's official [Model API](https://dev.meta.ai/docs/pricing-rate-limits) sells the Muse Image model at $0.01 per image, but as of October 2026 it has no video generation and no API for the Muse agent at muse.ai, where the videos are made. **Is there a Meta Muse API key?** Through useapi.net, no Meta key is needed: one useapi.net [API token](/docs/start-here/setup-useapi) calls the Muse API, and you add your Muse account once with its email and password at [Setup Muse](/docs/start-here/setup-muse). Create that account in the US, Canada, Japan or Singapore, where Muse is available (as of October 2026), and after that you can call the API from anywhere. **What is a good muse2api alternative?** Through useapi.net, the Muse API is hosted, so there is nothing to run: no Docker, no browser extension and no cookies to push, and we keep the account signed in and renew its session. It has image and video jobs with webhooks, streamed chat with the agent, and a hosted MCP server with 37 tools. **Is there a free Muse API?** Through useapi.net, the Muse API works on the free Muse plan, where one account made roughly 30 to 50 videos a week in our tests. Once one account's allowance is used up, new jobs go to your other accounts, and the paid Power ($20 a month) and Maximum ($100 a month) plans raise it (as of October 2026). **Where do my Muse videos and images go?** Through useapi.net, Muse runs on your Muse website subscription, so every image and video it makes also sits in that account's Library at muse.ai. The [Library endpoints](/docs/api-muse-v1/get-muse-assets) list and download them, and you can pass any of them into a new job by its asset id. ### Sources Checked on October 30, 2026: - Meta Model API: [models](https://dev.meta.ai/docs/models) (inputs and outputs of each model) and [pricing](https://dev.meta.ai/docs/pricing-rate-limits) (Muse Image $0.01 per image, Muse Wonder $4 / $20 and Muse Spark 1.1 to 1.3 $1.25 / $4.25 per million input / output tokens, Muse Voice Transcribe $0.18 per hour of audio, SAM 3.1 per image and video frame, no video generation model) - [TechCrunch, October 12, 2026](https://techcrunch.com/2026/10/12/meta-releases-its-first-frontier-model-muse-wonder): Meta releases Muse Wonder - [czg86389-hub/muse2api](https://github.com/czg86389-hub/muse2api) README, v1.6.9 (November 5, 2026, checked November 7): OpenAI-compatible chat, image and video endpoints, Docker Compose deployment, session cookies sent by a Chrome extension or a Tampermonkey script, MIT license - [duclm1x1/Muse-Chat-MCP](https://github.com/duclm1x1/Muse-Chat-MCP) README: a local MCP server that drives Chrome with Playwright - museai.suncodevn.com [plans](https://museai.suncodevn.com/api/billing/plans) and [request costs](https://museai.suncodevn.com/api/v1/config): chat 1, image 3 and video 6 credits, 20 free credits, 500 credits for $3.90, 1,000 for $15.70, 6,000 for $58.60 - useapi.net: the [Muse API reference](/docs/api-muse-v1), [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video), [POST /accounts](/docs/api-muse-v1/post-muse-accounts) and the [MCP server](/docs/api-muse-v1/mcp) === URL: https://useapi.net/docs/articles/minimax-bash === Document URL: https://useapi.net/docs/articles/minimax-bash --- layout: default title: "How to Generate Hailuo 02 and 2.3 Video with curl: MiniMax Tutorial" description: "Step-by-step tutorial: generate Hailuo 02 and 2.3 video, plus Veo 3.1 and Seedance 2.0 video and Midjourney V7 images, with a Hailuo AI website subscription, copy-paste curl and a Node.js batch script." keywords: [MiniMax tutorial, Hailuo video tutorial, MiniMax curl, Hailuo 02, Hailuo 2.3, Veo 3.1, Seedance 2.0, Nano Banana 2, GPT Image, Seedream, video generation, text to video, image to video, code] parent: Articles nav_exclude: true date: 2024-09-28 last_modified: 2026-11-20 nav_order: 400 repo: https://github.com/useapi/minimax-api --- ## How to Generate Hailuo 02 and 2.3 Video with curl: MiniMax Tutorial 6 min read • September 28, 2024 (November 20, 2026) ## Table of contents ### Introduction [MiniMax](https://www.minimax.io/) (the AI lab behind [Hailuo AI](https://hailuoai.video/)) puts a frontier roster behind one account — its own Hailuo 01 / 02 / 2.3 video, plus Veo 3.1 and Seedance 2.0 hosted through MiniMax — and you can drive every one of them from code. [useapi.net](/docs/subscription) fronts it with a third-party [MiniMax API](/docs/api-minimax-v1) that runs on your Hailuo AI website subscription over a standard REST endpoint, and the same subscription and token also reach a deep image lineup — Midjourney V7 / NiJi 7, Nano Banana 2 / Pro, GPT Image 1.5 / 2.0, Seedream 4.5 / 5.0, and image-01. This is the hands-on tutorial. For Hailuo 3.0, prices and every endpoint, see the [Hailuo API](/docs/api-minimax-v1) overview. This guide focuses on video and images. Music has its own endpoint — [POST music/create](/docs/api-minimax-v1/post-minimax-music-create) generates songs with Music 3.0 or Music 2.6, and can stream the audio back while it renders. Text-to-speech has its own endpoints too — [POST speech/create](/docs/api-minimax-v1/post-minimax-speech-create) speaks text with ten Speech models, from Speech 01 to Speech 2.8, and the [MiniMax text-to-speech tutorial](/docs/articles/minimax-speech-bash) walks through it. ### Supported models Pick a model per request with the `model` field on [POST /videos/create](/docs/api-minimax-v1/post-minimax-videos-create). If you omit `model`, the API defaults to `T2V-01` for text prompts and `I2V-01` for image prompts (Hailuo 01, 720p, 6 sec). | Model | Family | Type | Resolution / duration | Notes | |-------|--------|------|-----------------------|-------| | `T2V-01`, `I2V-01`, `I2V-01-live` | Hailuo 01 | Text / image-to-video | 720p, 6 sec | Defaults · `I2V-01-live` live-photo effect | | `T2V-01-Director`, `I2V-01-Director` | Hailuo 01 | Text / image-to-video | 720p, 6 sec | Camera-movement control via `[<movement>]` in the prompt | | `S2V-01` | Hailuo 01 | Subject reference | 720p, 6 sec | Character / subject consistency | | `02` | Hailuo 02 | Text / image-to-video | 512p / 768p / 1080p, 6–10 sec | Native 1080p · end frame (768p/1080p) | | `T2V-2.3`, `I2V-2.3` | Hailuo 2.3 | Text / image-to-video | 768p / 1080p, 6–10 sec | — | | `I2V-2.3-Fast` | Hailuo 2.3 | Image-to-video | 768p / 1080p, 6–10 sec | Faster, lower cost | | `Veo-3.1`, `Veo-3.1-Fast` | Veo 3.1 (Google DeepMind) | Text / image-to-video | 720p / 1080p / 4K, 8 sec | Native audio · end frame · `aspectRatio` 16:9 / 9:16 | | `Veo-3.1-S2V`, `Veo-3.1-S2V-Fast` | Veo 3.1 | Subject reference | 720p / 1080p / 4K, 8 sec | Up to 14 reference images | | `Seedance-2.0` | Seedance 2.0 (ByteDance) | Text / image-to-video | 480p / 720p / 1080p, 4–15 sec | Omni multi-modal references · 6 aspect ratios | | `Seedance-2.0-Fast` | Seedance 2.0 | Text / image-to-video | 480p / 720p, 4–15 sec | Faster, no 1080p | Hailuo 02/2.3 and Veo 3.1 take an `options` string for resolution and duration (e.g. `1080p-6sec`, `768p-10sec`, `veo-1080p-8sec`). Seedance models set `resolution` and `duration` directly. See [POST /videos/create](/docs/api-minimax-v1/post-minimax-videos-create) for the full per-model matrix. Sora 2 is no longer available: OpenAI shut it down on September 24, 2026. The same subscription and token also drive image generation on [POST /images/create](/docs/api-minimax-v1/post-minimax-images-create) (default `image-01`) — listed here for reference: | Model | Resolution | Max refs | Notes | |-------|------------|----------|-------| | `image-01` | HD | 1 (`characterFileId`) | Default · character-focused | | `h3-image` | 1K / 2K / 4K | 16 | MiniMax H3 Image · `@Image<N>` mentions | | `h3-image-highspeed` | 1K / 2K / 4K | 16 | Same quality, faster · `@Image<N>` mentions | | `midjourney-v7` | n/a | 14 | Always 4 images per request | | `midjourney-niji7` | n/a | 14 | Anime-focused · always 4 images | | `nano-banana-2` | 512P / 1K / 2K / 4K | 14 | Lower-cost flash variant · `@Image<N>` mentions | | `nano-banana-pro` | 1K / 2K / 4K | 14 | High resolution · `@Image<N>` mentions | | `gpt-image-1.5` | Low / Medium / High | 3 | OpenAI-sourced | | `gpt-image-2` | 1K / 2K / 4K | 16 | GPT Image 2.0 · `quality` low/medium/high · `@Image<N>` mentions | | `seedream-4.5` | 2K / 4K | 14 | `@Image<N>` mentions | | `seedream-5.0` | 2K / 3K | 14 | `@Image<N>` mentions | For the full image workflow, see the [images/create endpoint](/docs/api-minimax-v1/post-minimax-images-create) and the [MiniMax API overview](/docs/api-minimax-v1). ### Pricing Your [Hailuo AI website subscription](https://hailuoai.video/subscribe) pays for every video, with no per-generation surcharge from useapi.net: each generation spends the same credits it costs on hailuoai.video, which vary by model, resolution and duration. On Hailuo AI Master ($89 a month for 10,500 credits), Hailuo 3.0 at 768p spends 7 credits a second, about $0.059, against $0.08 on MiniMax's pay-as-you-go [developer platform](https://platform.minimax.io/docs/pricing/overview#models/video), which needs a separate developer account (as of October 2026). Hailuo AI also has a free tier. The [MiniMax API overview](/docs/api-minimax-v1) and the [videos/create](/docs/api-minimax-v1/post-minimax-videos-create) page carry per-model credit estimators. Each useapi.net [subscription](/docs/subscription) connects up to 3 MiniMax accounts (each extra subscription, $10 a month, adds 3 more). The script below spreads every batch across them with [GET /scheduler/available](/docs/api-minimax-v1/get-minimax-scheduler-available): it picks an account with free capacity, falls back to the next, and keeps paid accounts running while free ones queue, so there is no per-account email argument to pass. With a paid account you can expect roughly: - 1 generation completed within 2…3 minutes - 10 generations in about 20…30 minutes - 30 generations in about 60…90 minutes Free accounts take longer, and you may need to connect several of them to get a reasonable number of generations per day. ### Generate a video in two API calls You need a useapi.net [API token](/docs/start-here/setup-useapi) and a connected [MiniMax account](/docs/start-here/setup-minimax) — export the token so the `curl` examples below run as-is: ```bash export USEAPI_TOKEN="user:1234-..." ``` Generation is asynchronous — the create call returns a `videoId` immediately, then you poll until the video is ready. First, submit the job with `POST https://api.useapi.net/v1/minimax/videos/create`: ```bash curl -X POST "https://api.useapi.net/v1/minimax/videos/create" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A majestic mountain landscape with snow-capped peaks and flowing rivers, camera slowly panning right", "model": "02", "options": "1080p-6sec" }' ``` When more than one account is connected, add `"account": "<account>"` to pick one — otherwise the API selects an available account for you. The response returns immediately with a `videoId`: ```json { "id": "1122334455667798899", "videoId": "user:1234-minimax:987654321-video:998877665544332211", "task": { "batchID": "998877665544332211", "videoIDs": ["1122334455667798899"] } } ``` Then poll for the result with `GET https://api.useapi.net/v1/minimax/videos/{videoId}`: ```bash curl "https://api.useapi.net/v1/minimax/videos/VIDEO_ID" \ -H "Authorization: Bearer $USEAPI_TOKEN" ``` The job is done when `statusFinal` is `true`. Success is `status: 2` (`statusLabel: "completed"`), and the MP4 is in `downloadURL` (the clean, non-watermarked master on paid accounts) with `videoURL` (watermarked) as a fallback: ```json { "status": 2, "statusLabel": "completed", "statusFinal": true, "percent": 100, "videoURL": "<watermarked url>", "downloadURL": "<clean url, paid accounts>", "videoId": "user:1234-minimax:987654321-video:..." } ``` A video typically finishes in 2…3 minutes depending on model, resolution, and duration. Prefer not to poll? Pass a `replyUrl` in the create body to receive a webhook callback when the job completes. The create call may return `412` (insufficient credits), `422` (moderated prompt), `429` (queue full — wait 10…30 s and retry). On the poll, a `404` most often means the finished video was moderated and removed. See the [endpoint docs](/docs/api-minimax-v1/post-minimax-videos-create#responses) for the full list. ### Image-to-video and references To animate a still image — or pass a subject/character reference — upload it first with [POST /files](/docs/api-minimax-v1/post-minimax-files) (raw bytes, an image `Content-Type`, `.png` / `.jpeg`, and `.webp` uploaded as `image/jpeg`). It returns a `fileID` you pass to [POST /videos/create](/docs/api-minimax-v1/post-minimax-videos-create): ```bash # 1. Upload the start frame → returns { "fileID": "user:...-file:..." } curl -X POST "https://api.useapi.net/v1/minimax/files/?account=987654321" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: image/jpeg" \ --data-binary @first_frame.jpeg # 2. Create the video from that frame curl -X POST "https://api.useapi.net/v1/minimax/videos/create" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "the character turns and smiles, camera pushes in", "model": "I2V-2.3", "options": "1080p-6sec", "fileID": "FILE_ID_FROM_STEP_1" }' ``` Image-to-video models (`I2V-01*`, `I2V-2.3*`, `S2V-01`) require a `fileID`. On `02`, Veo 3.1 and Seedance 2.0 the image is optional. The `02` and Veo 3.1 models also take an `end_frame_fileID` for a first→last transition (it must be a different upload than `fileID`), and the Seedance and Veo S2V models accept extra references (`fileID2`…) for omni and subject-reference modes. See [POST /videos/create](/docs/api-minimax-v1/post-minimax-videos-create#request-body) for which model accepts which reference. You can also generate a start frame with [POST /images/create](/docs/api-minimax-v1/post-minimax-images-create) and feed the returned image `fileID` straight into a video. ### Batch-generate with a script Finding the right shot takes many attempts, and running them by hand is tedious. The Node.js script below reads a list of prompts from `videos.json`, uploads any reference images, submits each job load-balanced across every connected account via [GET /scheduler/available](/docs/api-minimax-v1/get-minimax-scheduler-available), then polls and downloads every finished MP4 — so you can queue a batch and come back to the winners. You can provide an image instead of or in addition to a text prompt. When a `file` is given, the `prompt` is optional. It often helps to ask ChatGPT, Claude, or Gemini to draft a batch of prompt variations, then keep what works. You need [Node.js](https://nodejs.org) v21 or newer (no dependencies to install). Put `videos.json` and `videos.mjs` in the same folder and run `node ./videos.mjs API_TOKEN`, where `API_TOKEN` is your useapi.net [API token](/docs/start-here/setup-useapi). The script discovers your connected MiniMax accounts and load-balances the batch automatically — no per-account email argument is needed. <details markdown="block"> <summary>Expand `videos.json`</summary> ```json [ { "file": "./blonde.jpeg", "prompt": "A beautiful blonde woman with striking blue eyes posing confidently for a magazine cover." }, { "prompt": "From below shot of a cat catholic priest performing an exorcism on a demonic cat, a parody on The Exorcist movie." }, { "model": "02", "options": "1080p-6sec", "prompt": "Zoom in on a cute red shiny robot holding a white banner with text 'useapi.net', Pixar animation style." }, { "model": "Seedance-2.0", "resolution": "1080", "duration": 8, "aspectRatio": "16:9", "prompt": "Cinematic tracking shot through a neon-lit alley at night, rain reflections on wet pavement." } ] ``` Each prompt object may set an optional `model` plus the parameters that model supports — `options` (resolution/duration for Hailuo 02/2.3 and Veo 3.1), `resolution` and `duration` (Seedance 2.0), `aspectRatio` (Veo, Seedance), and `end_frame_fileID` where supported. Omit them to fall back to the Hailuo 01 defaults. See [POST /videos/create](/docs/api-minimax-v1/post-minimax-videos-create) for the full per-model matrix. Currently `.png` and `.jpeg` images are supported (rename a `.webp` to `.jpeg`). </details> <details markdown="block"> <summary>Expand `videos.mjs` script</summary> ```javascript /* Script version 3.0, June 15, 2026 Script to generate videos using prompts with MiniMax API by useapi.net 🚀 For more details visit https://useapi.net/docs/api-minimax-v1 Installation Instructions: ========================== You need Node.js v21 or newer installed to run this script. Download and install Node.js from: - Windows, macOS, Linux: https://nodejs.org/ After installation, verify by running the following commands in a terminal: node -v Running the Script: =================== Usage: node videos.mjs <API_TOKEN> [PROMPTS_FILE] Replace API_TOKEN with your actual useapi.net API token, see https://useapi.net/docs/start-here/setup-useapi If optional PROMPTS_FILE not provided videos.json will be used. Example #1: -------- node videos.mjs user:1234-abcdefhijklmnopqrstuv This command executes the script using API token user:1234-abcdefhijklmnopqrstuv Example #2: -------- node videos.mjs user:1234-abcdefhijklmnopqrstuv myprompts.json This command executes the script using API token user:1234-abcdefhijklmnopqrstuv and load prompts from myprompts.json file. Changelog: ========== - October 23, 2024: Response code 596 handling added https://useapi.net/docs/api-minimax-v1/post-minimax-videos-create#responses. - October 25, 2024: The param prompt is optional and no longer needed if a fileID is provided. - November 4, 2024: Retry on 502 and 504. - June 15, 2026: Pass through per-prompt model parameters (model, options, resolution, duration, aspectRatio, end_frame_fileID, …) so you can target Hailuo 02/2.3, Sora 2, Veo 3.1 and Seedance 2.0. Any field other than the local "file" upload path is forwarded to videos/create as-is. */ import readline from 'node:readline'; import fs from 'fs/promises'; import { writeFile } from 'node:fs/promises'; import { Readable } from 'node:stream'; // Constants const RESULTS_FILE = 'videos_results.txt'; const ERRORS_FILE = 'videos_errors.txt'; const SLEEP_429 = 20 * 1000; // in milliseconds const SLEEP_DOWNLOAD = 30 * 1000; // in milliseconds const urlAccounts = 'https://api.useapi.net/v1/minimax/accounts'; const urlAvailable = 'https://api.useapi.net/v1/minimax/scheduler/available'; const urlCreate = 'https://api.useapi.net/v1/minimax/videos/create'; const urlDownload = 'https://api.useapi.net/v1/minimax/videos/'; const urlUploadFile = 'https://api.useapi.net/v1/minimax/files/?account='; // To upload .webp rename it to .jpeg const supportedFileExtensions = ['png', 'jpeg'] // account: { filename: fileID } const uploadedFiles = {}; let availableAccountsCount = 0; // Track accounts without any credits left const outOfCredits = []; // Utility to sleep for given milliseconds const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); // Function to fetch configured MiniMax API accounts async function fetchAccounts(apiToken) { const response = await fetch(urlAccounts, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.error(`⛔ Error fetching accounts (HTTP ${response.status}): ${response.statusText}`); process.exit(1); } return response.json(); } const elapsedTimeSec = (start) => (Date.now() - start) / 1000; async function uploadFile(apiToken, account, filename) { if (!uploadedFiles[account]) uploadedFiles[account] = {}; // Check if already uploaded for provided account if (uploadedFiles[account].hasOwnProperty(filename)) return uploadedFiles[account][filename]; const startTime = Date.now(); console.log(`⬆️ Account ${account} uploading file…`, filename); const body = new Blob([await fs.readFile(filename)]); const fileExt = filename.split('.').pop(); const response = await fetch(`${urlUploadFile}${account}`, { method: 'POST', headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}`, 'Content-Type': `image/${fileExt}` }, body }); if (response.ok) { const json = await response.json(); console.log(`🆗 fileID (${elapsedTimeSec(startTime)} sec)`, json.fileID); uploadedFiles[account][filename] = json.fileID; } else { console.error(`❗ Unable to upload file HTTP ${response.status} (${elapsedTimeSec(startTime)} sec)`, await response.text()); // Do not attempt to upload failed file again uploadedFiles[account][filename] = undefined; } return uploadedFiles[account][filename]; } // Function to submit a prompt. // `fields` is the prompt object minus the local `file` upload path — it carries // `prompt` plus any optional model parameters (model, options, resolution, // duration, aspectRatio, end_frame_fileID, …) and is forwarded to videos/create as-is. async function submitPrompt(apiToken, filename, promptIndex, fields) { const { prompt } = fields; console.log(`\n👉 Prompt #${promptIndex}: ${prompt ?? '(image only)'}`); const availableResponse = await fetch(urlAvailable, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); const availableJSON = await availableResponse.json(); console.log(`Currently executing ${availableJSON.executing.length} generation(s).`); const available = availableJSON.available .filter(a => !outOfCredits.includes(a.account)); console.log(`Available accounts ${available.length}:`, available.map(a => `${a.account} (${a.available})`).join(', ')); if (available.length == 0) { console.log(`🔄️ Waiting for currently running generations to complete …`); return 429; } const account = available[0].account; const fileID = filename ? await uploadFile(apiToken, account, filename) : undefined; const info = `Prompt #${promptIndex} account ${account}`; console.log(`${info} …`); const createResponse = await fetch(urlCreate, { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiToken}` }, body: JSON.stringify({ account, fileID, ...fields }) }); const createBody = await createResponse.text(); if (createResponse.status == 200) { const json = JSON.parse(createBody); const videoId = json.videoId; if (videoId) { await fs.appendFile(RESULTS_FILE, `${videoId},${prompt}\n`); return 200; } else { const error = `No videoId found in HTTP 200 response`; console.log(`❓ ${info}: ${error}`, createBody); await fs.appendFile(ERRORS_FILE, `${error},${prompt}\n`); return 500; } } else { let returnStatus = createResponse.status; switch (createResponse.status) { case 502: // Happens when MiniMax website is too busy case 504: // Happens when MiniMax website is too busy case 429: console.log(`🔄️ ${info}: retry on HTTP ${createResponse.status}`); returnStatus = 429; break; case 422: console.log(`🛑 ${info}: MODERATED prompt`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},${prompt}\n`); break; case 412: console.log(`🛑 ${info}: account run out of credits`, createBody); outOfCredits.push(account); break; default: console.log(`❗ ${info}: FAILED with HTTP ${createResponse.status}`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},${prompt}\n`); } return returnStatus; } } // Function to download videos based on VIDEO IDs async function download(apiToken) { try { const resultsContent = await fs.readFile(RESULTS_FILE, 'utf8'); const lines = resultsContent.trim().split('\n'); for (const line of lines) { const [videoId, prompt] = line.split(','); const videoFilename = `${videoId.replace(/:/g, '_')}.mp4`; console.log(`👉 ${videoId}`); try { await fs.access(videoFilename); console.log(`⚠️ ${videoFilename} already exists. Skipping download.`); continue; } catch { // File does not exist, proceed with downloading } while (true) { const response = await fetch(`${urlDownload}${videoId}`, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.log(`🛑 MODERATED ${videoId} (HTTP ${response.status}):\n${prompt}\n`, await response.text()); break; } const taskResponseBody = await response.json(); const { status, statusFinal, statusLabel, downloadURL, videoURL, percent } = taskResponseBody; if (statusFinal) { const url = downloadURL ?? videoURL; if (url) { console.log(`✅ Downloading ${url} to ${videoFilename}`); try { const videoResponse = await fetch(url); if (!videoResponse.ok) { console.error(`⛔ Unable to download ${videoId} (HTTP ${videoResponse.status}):\n${prompt}\n`, url); break; } const stream = Readable.fromWeb(videoResponse.body); await writeFile(videoFilename, stream); } catch (err) { console.error(`⛔ Error during download: ${err}`); } } else console.error(`🛑 Unable to download ${videoId} status (${status} ${statusLabel}):\n${prompt}\n`); break; } else { console.log(`⌛ ${videoId} status (${status} ${statusLabel}) and is still in progress (${percent}%), waiting…`); await sleep(SLEEP_DOWNLOAD); } } } } catch (error) { console.log(`⛔ Error during download:`, error.stack || error); } } // Main function async function main() { const apiToken = process.argv[2]; const promptFile = process.argv[3] || 'videos.json'; // Default to 'videos.json' if not provided if (!apiToken) { console.error('Usage: node videos.mjs <API_TOKEN> [PROMPTS_FILE]'); process.exit(1); } console.log('Script v3.0'); console.log('Node version is: ' + process.version); try { if (await fileExists(RESULTS_FILE)) { let user_input; while (!['y', 'n'].includes(user_input)) { user_input = (await promptUser(`❔ ${RESULTS_FILE} file detected. Do you want to download the results now? (y/n): `))?.toLowerCase(); if (user_input == 'y') { await download(apiToken); await fs.unlink(RESULTS_FILE); } } } const start = new Date(); try { console.info('START EXECUTION', start); await execute(apiToken, promptFile); // Pass the promptFile to execute function } finally { console.info('COMPLETED', new Date()); console.info('EXECUTION ELAPSED', diffInMinutesAndSeconds(start, new Date())); } try { console.info('START DOWNLOAD', start); await download(apiToken); } finally { console.info('TOTAL ELAPSED', diffInMinutesAndSeconds(start, new Date())); } } catch (error) { console.error('⛔ Error during execution:', error.stack || error); } } async function execute(apiToken, promptFile) { const accounts = await fetchAccounts(apiToken); const videoAccounts = Object.values(accounts) .filter(a => a.supportVideo) // Accounts with video support .filter(a => !a.error); // Active accounts without error console.info(`Configured active MiniMax API video accounts`, videoAccounts.length); if (videoAccounts.length <= 0) { console.error(`⛔ No configured active video accounts found. Please refer to https://useapi.net/docs/start-here/setup-useapi`); process.exit(1); } availableAccountsCount = videoAccounts.length; const promptData = await fs.readFile(promptFile, 'utf8'); const prompts = JSON.parse(promptData); console.log(`Total number of prompts to process`, prompts.length); let warnings = []; // First pass: check for warnings for (let i = 0; i < prompts.length; i++) { const { file, prompt } = prompts[i]; if (!prompt && !file) { warnings.push(`⚠️ Skip empty prompt with empty file at index ${i}`); continue; } if (file) { try { await fs.access(file); } catch { warnings.push(`⚠️ Specified file '${file}' does not exist. Skip prompt ${i}`); continue; } const ext = file.split('.').pop(); if (!supportedFileExtensions.includes(ext)) { warnings.push(`⚠️ File ${file} extension ${ext} not supported. Skip prompt ${i}`); continue; } } } if (warnings.length > 0) { warnings.forEach(warning => console.warn(warning)); console.error(`⛔ Execution stopped due to warnings.`); process.exit(1); } for (let i = 0; i < prompts.length; i++) { const { file, ...fields } = prompts[i]; while (true) { const responseCode = await submitPrompt(apiToken, file, i + 1, fields); if (responseCode == 429) await sleep(SLEEP_429); else if (responseCode == 412) { // Check if there's no accounts left at all if (availableAccountsCount == outOfCredits.length) { console.error(`⛔ All configured video accounts run out of credits`); process.exit(1); } } else if (responseCode == 596) { console.error(`⛔ Your hailuoai.video account has been placed on hold, which may last a few hours. It may be a good idea to pause operations until then.`); process.exit(1); } else break; } } } // Utility function to check if a file exists async function fileExists(path) { try { await fs.access(path); return true; } catch { return false; } } // Function to prompt user input async function promptUser(query) { const rl = readline.createInterface({ input: process.stdin, output: process.stdout }); return new Promise((resolve) => rl.question(query, answer => { rl.close(); resolve(answer); })); } function diffInMinutesAndSeconds(date1, date2) { const diffInSeconds = Math.floor((date2 - date1) / 1000); return `${Math.floor(diffInSeconds / 60)} minutes ${diffInSeconds % 60} seconds`; }; main(); ``` </details> All generated videos download locally so you can review them once they are ready. If you would rather not read the docs, the script is all you need — but each endpoint also has a [Try It](/docs/api-minimax-v1/post-minimax-videos-create#try-it) console right in the browser. ### Examples The clips and images below are real generations produced through this MiniMax API, straight from our blog walkthroughs. The cat exorcist from the sample `videos.json` above is on YouTube: [The Cat Exorcist • MiniMax AI](https://www.youtube.com/watch?v=4W4FE4FU2EM). ###### Hailuo 02 — text-to-video with an end frame, `02` 1080p 6 sec <video poster="https://media.useapi.net/articles/2024-09-28-minimax-bash/minimax-end-frame-poster.jpg" src="https://media.useapi.net/articles/2024-09-28-minimax-bash/minimax-end-frame.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> — from [MiniMax: End Frame Parameter for Video](/blog/250830) Also on YouTube: [MiniMax 02 End Frame](https://youtube.com/shorts/g6_nL6FXI3k). ###### Hailuo 2.3 — image-to-video, `I2V-2.3` 768p 10 sec <video poster="https://media.useapi.net/articles/2024-09-28-minimax-bash/i2v-2.3-768p-10sec-lady-poster.jpg" src="https://media.useapi.net/articles/2024-09-28-minimax-bash/i2v-2.3-768p-10sec-lady.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> — from [MiniMax: 2.3 Video Generation Models](/blog/251030) Also on YouTube: [The Lady • MiniMax I2V 2.3](https://youtube.com/shorts/pc9WNBGRBg8) and [Pennywise the Clown • MiniMax T2V 2.3](https://www.youtube.com/watch?v=iIF5wY8Kweg). ###### Sora 2 — image-to-video from a start frame, `Sora-2` 9:16 Generated before OpenAI shut down Sora 2 on September 24, 2026. Sora 2 is no longer available, but the clip stays here as a comparison point. <video poster="https://media.useapi.net/articles/2024-09-28-minimax-bash/beast-results-poster.jpg" src="https://media.useapi.net/articles/2024-09-28-minimax-bash/beast-results.mp4" style="width: 100%; aspect-ratio: 9/16; max-width: 400px;" controls type="video/mp4" preload="metadata"></video> — from [MiniMax: Sora, Veo, and Hailuo Models](/blog/260224) ###### Veo 3.1 — subject reference, `Veo-3.1-S2V` 16:9 with native audio <video poster="https://media.useapi.net/articles/2024-09-28-minimax-bash/minimax-veo-3-1-with-subject-ref-poster.jpg" src="https://media.useapi.net/articles/2024-09-28-minimax-bash/minimax-veo-3-1-with-subject-ref.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> — from [MiniMax: Sora 2 and Veo 3.1](/blog/260102) ###### Midjourney V7 — multi-reference image, `midjourney-v7` 4:3 <img src="https://media.useapi.net/articles/2024-09-28-minimax-bash/midjourney-results.png" style="width: 100%; max-width: 400px;" /> — from [MiniMax: Sora, Veo, and Hailuo Models](/blog/260224) ###### Nano Banana 2 — multi-reference image, `nano-banana-2` 3:4 2K <img src="https://media.useapi.net/articles/2024-09-28-minimax-bash/nano-banana-2-cool-cats-2k-result.png" style="width: 100%; max-width: 400px;" /> — from [MiniMax: Nano Banana 2 Image Model](/blog/260227) ###### GPT Image 1.5 — text-to-image, `gpt-image-1.5` 16:9 <img src="https://media.useapi.net/articles/2024-09-28-minimax-bash/gpt-image-1.5-via-minimax-api-by-useapi.net.png" style="width: 100%;" /> — from [17 AI Image Models: The Showdown](/blog/260309i) Related tutorials: [MiniMax text-to-speech (TTS)](/docs/articles/minimax-speech-bash), [Sora 2 API alternatives](/docs/articles/sora-2-api-alternatives) and [Seedance 2.0 and 2.5 API pricing compared](/docs/articles/seedance-2-api-pricing). ### Use it from Claude, ChatGPT or Cursor The hosted [MiniMax MCP server](/docs/api-minimax-v1/mcp) gives Claude Code, Cursor, VS Code and other MCP clients the MiniMax API as 38 tools, with nothing to install, and the Claude app and ChatGPT connect to it with a sign-in. It runs on your own Hailuo AI accounts with your useapi.net API token. In Claude Code: ```bash claude mcp add --transport http useapi-minimax https://api.useapi.net/v1/minimax/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` Then ask in plain words, for example "Make a 6-second Hailuo 2.3 video at 768p of a paper boat drifting down a rainy street at night". The assistant calls `minimax_create_video`, which takes the same Hailuo, Veo 3.1 and Seedance 2.0 models as [POST /videos/create](/docs/api-minimax-v1/post-minimax-videos-create), and `minimax_create_image` makes Midjourney V7, Nano Banana 2 and GPT Image images like the examples above. MiniMax's own MiniMax-MCP has 8 tools and runs locally on a pay-as-you-go developer API key ([comparison](/docs/api-minimax-v1/mcp#useapinet-vs-minimaxs-own-mcp-server)). The server is listed in the official MCP Registry as `net.useapi/minimax`, and the [`minimax-api`](https://github.com/useapi/minimax-api#use-with-claude-code) repo also installs as a Claude Code plugin or a [Gemini CLI extension](https://github.com/useapi/minimax-api#use-with-gemini-cli). ### Frequently asked questions **Is there a MiniMax (Hailuo) API?** Through useapi.net, yes: the [Hailuo API (MiniMax)](/docs/api-minimax-v1) this tutorial uses runs Hailuo 3.0, 2.3 and 02 on your [Hailuo AI website subscription](https://hailuoai.video/subscribe) through one REST endpoint, along with Veo 3.1, Seedance 2.0 and nine image models. You call it with a useapi.net token, with no MiniMax developer account or platform key to set up. **How much does the MiniMax API cost?** Through useapi.net, on Hailuo AI Master billed yearly ($71.20 a month for 10,500 credits), Hailuo 3.0 at 2K costs about $0.081 a second, against $0.13 on MiniMax's pay-as-you-go [developer platform](https://platform.minimax.io/docs/pricing/overview#models/video) (as of October 2026). The [videos/create](/docs/api-minimax-v1/post-minimax-videos-create) and [images/create](/docs/api-minimax-v1/post-minimax-images-create) pages carry per-model credit estimators, and [Pricing](#pricing) has the monthly plan. **Which video models can I generate?** Through useapi.net, 18 video models on your Hailuo AI website subscription: Hailuo 01 (`T2V-01`, `I2V-01` and the Director / live / `S2V-01` variants), Hailuo 02 (`02`), Hailuo 2.3 (`T2V-2.3`, `I2V-2.3`, `I2V-2.3-Fast`), Veo 3.1 (`Veo-3.1`, `Veo-3.1-Fast` and the `S2V` variants) and Seedance 2.0 (`Seedance-2.0`, `Seedance-2.0-Fast`), plus Hailuo 3.0 and Seedance 2.0 Mini on the [overview](/docs/api-minimax-v1). Pass the name in the `model` field of [POST /videos/create](/docs/api-minimax-v1/post-minimax-videos-create). **Is there a MiniMax music API?** Through useapi.net, yes, while MiniMax's paid music and lyrics APIs have been closed to new users since August 20, 2026. [POST music/create](/docs/api-minimax-v1/post-minimax-music-create) makes full songs with vocals on Music 3.0 and Music 2.6 for about 1¢ a song on a MiniMax Audio Pro website subscription ($99 a month), against 15¢ pay as you go (as of October 2026). **Is there a MiniMax text-to-speech API?** Through useapi.net, yes: [POST speech/create](/docs/api-minimax-v1/post-minimax-speech-create) turns text into speech on your MiniMax Audio website subscription, with 600+ voices to pick from. On MiniMax Audio Pro, speech-2.8-hd works out to $33 per million characters, against $100 pay as you go on MiniMax's developer platform (as of October 2026). Step by step: the [MiniMax text-to-speech tutorial](/docs/articles/minimax-speech-bash). ### Conclusion Visit our <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> or <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> for any support questions and concerns. The full runnable example is in the [`minimax-api` GitHub repo](https://github.com/useapi/minimax-api). === URL: https://useapi.net/docs/articles/minimax-h3-image-api === Document URL: https://useapi.net/docs/articles/minimax-h3-image-api --- layout: default title: "How to Generate Images with the MiniMax H3 Image API" description: "Generate images with MiniMax H3 Image and H3 Image Highspeed on a Hailuo AI plan through the useapi.net API: 1K to 4K, 16 reference images, real outputs and prices." keywords: [MiniMax H3 Image API, MiniMax H3 Image, H3 Image Highspeed, Hailuo image API, MiniMax image generation API, MiniMax H3 Image Highspeed API, multi-reference image API, 4K image API] image: https://media.useapi.net/minimax/2026-11-10-h3-image-blog/minimax-h3-image-two-references-woman-vintage-motorcycle-sunset-2k.jpg parent: Articles nav_exclude: true date: 2026-11-10 last_modified: 2026-11-20 nav_order: 881 --- ## How to Generate Images with the MiniMax H3 Image API November 10, 2026 (November 20, 2026) --- ### Introduction The useapi.net [MiniMax API](/docs/api-minimax-v1) runs [MiniMax H3 Image](https://hailuoai.video/create/image-generation), [MiniMax](https://www.minimax.io)'s newest image model, on your [Hailuo AI subscription](https://hailuoai.video/subscribe): one REST call, [POST images/create](/docs/api-minimax-v1/post-minimax-images-create), makes 1 to 4 images at 1K, 2K or 4K from a prompt and up to 16 reference images. H3 Image Highspeed, the faster variant, takes the same parameters. Every image on this page was made through the API by the call shown above it. You need a useapi.net API token and a Hailuo AI account added once, see [Setup MiniMax](/docs/start-here/setup-minimax). useapi.net is a third-party API, not affiliated with MiniMax. ### Pricing | Model | 1K or 2K | 4K | 4K on Master ($89 a month) | 4K on [MiniMax's own API](https://platform.minimax.io/docs/pricing/overview) | |---|:-:|:-:|:-:|:-:| | H3 Image | 3 credits | 6 credits | $0.051 | $0.069 | | H3 Image Highspeed | 5 credits | 12 credits | $0.102 | $0.130 | A 4K image on each Hailuo AI plan, against MiniMax's own [developer platform](https://platform.minimax.io/docs/pricing/overview), which bills the model by tokens (as of November 2026): | Model | [Official API](https://platform.minimax.io/docs/pricing/overview) | Max $216/m (27,000 cr/mo) | Master $89/m (10,500 cr/mo) | Pro $38/m (4,500 cr/mo) | Standard $10.50/m (1,000 cr/mo) | |---|---|---|---|---|---| | H3 Image (4K) | $0.069 (an image) | $0.048 / 6 cr (4,500 images/mo) | $0.051 / 6 cr (1,750 images/mo) | $0.051 / 6 cr (750 images/mo) | $0.063 / 6 cr (166 images/mo) | | H3 Image Highspeed (4K) | $0.130 (an image) | $0.096 / 12 cr (2,250 images/mo) | $0.102 / 12 cr (875 images/mo) | $0.101 / 12 cr (375 images/mo) | $0.126 / 12 cr (83 images/mo) | - The same Hailuo credits also run Midjourney V7, Nano Banana Pro, GPT Image 2, Seedream and Veo 3.1, none of which MiniMax's platform sells, and they need no prepaid developer balance. - The [credits calculator](/docs/api-minimax-v1#pricing) on the overview has every resolution, and [GET features](/docs/api-minimax-v1/get-minimax-features) shows the credits left on each account. ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. ### Example: one person and one motorcycle from two reference images H3 Image takes up to 16 reference images, and the prompt can say which is which: `@Image1` means `referenceFileId1`, `@Image2` means `referenceFileId2`, and so on. We gave it an old studio portrait of a woman, a photo of a 1920s motorcycle on white, and a seven-word prompt, `@Image1 riding the @Image2 at sunset, cinematic`. The two references that went in: ![The two reference images for MiniMax H3 Image: @Image1, an old studio portrait of a woman, and @Image2, a 1920s motorcycle on a white background](https://media.useapi.net/minimax/2026-11-10-h3-image-blog/minimax-h3-image-references-vintage-portrait-and-1920s-motorcycle.jpg) Upload each image once with [POST files](/docs/api-minimax-v1/post-minimax-files), which returns its `fileID`: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-minimax-v1/post-minimax-files">POST files</a></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/files/?account=987654321' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: image/jpeg' \ --data-binary '@portrait.jpg' ``` </details> Then pass the files as `referenceFileId1` and `referenceFileId2`, with the mentions in the prompt. Add `account` if you have more than one Hailuo account: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-minimax-v1/post-minimax-images-create">POST images/create</a></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/images/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="h3-image"' \ --form 'resolution="2K"' \ --form 'aspectRatio="3:2"' \ --form 'referenceFileId1="user:12345-minimax:987654321-file:111111111111111111"' \ --form 'referenceFileId2="user:12345-minimax:987654321-file:222222222222222222"' \ --form 'prompt="@Image1 riding the @Image2 at sunset, cinematic"' ``` </details> <details markdown="block"> <summary>Expand <code>Response</code></summary> ```json { "imageIds": ["user:12345-minimax:987654321-image:333333333333333333"], "code": 200 } ``` </details> The image that came out, 2K at 3:2, 2496×1664: ![MiniMax H3 Image through the useapi.net MiniMax API: a woman from a vintage portrait riding a 1920s motorcycle at sunset, made from two reference images](https://media.useapi.net/minimax/2026-11-10-h3-image-blog/minimax-h3-image-two-references-woman-vintage-motorcycle-sunset-2k.jpg) H3 Image kept her face, hairstyle, dress and rose, kept the motorcycle's black frame and tank, and built a new scene around both. A few rules make references predictable: * `@Image1` always means `referenceFileId1`, whatever order the mentions take in the prompt. Case doesn't matter, so `@IMAGE1` and `@image1` work too * Slots start at 1 and have no gaps: `referenceFileId3` without 1 and 2 is refused * All reference files come from the same Hailuo account, the one the image is made on * Mentions are optional. They make each reference's role explicit, which is what turned two separate photos into one rider on one motorcycle ### Getting the image Poll [GET images/`imageId`](/docs/api-minimax-v1/get-minimax-images-imageId) with each id from `imageIds` until `statusFinal` is `true`, or pass a `replyUrl` to get the same JSON by callback. The finished image is at `downloadURL`: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-minimax-v1/get-minimax-images-imageId">GET images/<code>imageId</code></a></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/images/user:12345-minimax:987654321-image:333333333333333333' \ --header 'Authorization: Bearer user:12345-…' ``` </details> <details markdown="block"> <summary>Expand <code>Response</code></summary> ```json { "imageId": "user:12345-minimax:987654321-image:333333333333333333", "modelID": "MiniMax-H3-Image", "statusLabel": "completed", "statusFinal": true, "width": 2496, "height": 1664, "aspectRatio": "3:2", "downloadURL": "https://cdn.hailuoai.video/…/image.jpg" } ``` </details> `statusFinal` is also `true` when `statusLabel` is `failed` or `moderated`, and then there is no image. A request the API can't accept answers `400` with an `error` message. ### More examples #### Text to image with the defaults Only the model and a prompt. Without `aspectRatio` and `resolution`, H3 Image picks the frame (`auto`) and renders at 1K. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-minimax-v1/post-minimax-images-create">POST images/create</a></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/images/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="h3-image"' \ --form 'prompt="A lone lighthouse on a rocky cliff at dusk, waves crashing, cinematic light"' ``` </details> The image that came out. H3 Image chose a portrait frame, 880×1184: ![MiniMax H3 Image at 1K with the default auto aspect ratio: a lighthouse on a rocky cliff at dusk](https://media.useapi.net/minimax/2026-11-10-h3-image-blog/minimax-h3-image-lighthouse-cliff-dusk-1k.jpg) #### H3 Image Highspeed at 1K, 1:1 `h3-image-highspeed` takes exactly the same parameters. Hailuo describes it as the same image quality with faster generation, for exploring ideas and iterating quickly. We haven't measured the speed difference, so time a few requests on your account before you pick Highspeed for speed alone. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-minimax-v1/post-minimax-images-create">POST images/create</a></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/images/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="h3-image-highspeed"' \ --form 'resolution="1K"' \ --form 'aspectRatio="1:1"' \ --form 'prompt="Peaceful forest path with sunlight filtering through tall ancient trees"' ``` </details> The image that came out, 1024×1024: ![MiniMax H3 Image Highspeed at 1K, 1:1: a forest path with sunlight filtering through tall old trees](https://media.useapi.net/minimax/2026-11-10-h3-image-blog/minimax-h3-image-highspeed-forest-path-sunlight-1k.jpg) ### Parameters | Parameter | Values | Default | |---|---|---| | `model` | `h3-image`, `h3-image-highspeed` | `image-01` | | `resolution` | `1K`, `2K`, `4K` | `1K` | | `aspectRatio` | `auto`, `21:9`, `16:9`, `5:4`, `4:3`, `3:2`, `1:1`, `2:3`, `3:4`, `4:5`, `9:16` | `auto` | | `quantity` | `1` to `4` images per request | `1` | | `referenceFileId1` … `16` | `fileID` from [POST files](/docs/api-minimax-v1/post-minimax-files) | none | | `prompt` | up to 7,500 characters | required | A 4K image at 16:9 came out at 5472×3072 in our tests. `quality` belongs to GPT Image 2 and is refused here. [POST images/create](/docs/api-minimax-v1/post-minimax-images-create) has the full list. ### Use it from Claude, ChatGPT or Cursor The hosted [MiniMax MCP server](/docs/api-minimax-v1/mcp) brings these H3 Image calls to Claude Code, Cursor, VS Code and other MCP clients, with nothing to install, and the Claude app and ChatGPT connect to it with a sign-in. It has 38 tools and runs on your own Hailuo AI accounts with your useapi.net API token. In Claude Code: ```bash claude mcp add --transport http useapi-minimax https://api.useapi.net/v1/minimax/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` Then ask, for example, "Upload these two photos and make a 2K H3 Image of @Image1 riding the motorcycle from @Image2 at sunset". The assistant uploads them with `minimax_upload_file` and calls `minimax_create_image` with `h3-image` and up to 16 references, the same parameters as above. MiniMax's own MiniMax-MCP has 8 tools and runs locally on a pay-as-you-go developer API key ([comparison](/docs/api-minimax-v1/mcp#useapinet-vs-minimaxs-own-mcp-server)). The server is listed in the official MCP Registry as `net.useapi/minimax`. ### Questions #### Is there a MiniMax H3 Image API? Yes. The useapi.net MiniMax API runs H3 Image and H3 Image Highspeed on your Hailuo AI subscription, and the same credits also run Midjourney V7, Nano Banana Pro, GPT Image 2 and Seedream, none of which MiniMax's own developer platform sells. One call to [POST images/create](/docs/api-minimax-v1/post-minimax-images-create) takes up to 16 reference images with `@Image` mentions. #### How much does MiniMax H3 Image cost? Through useapi.net, a 4K H3 Image uses 6 Hailuo credits, $0.051 on Master ($89 a month, 1,750 images), against $0.069 on MiniMax's own API, and a 4K Highspeed image $0.102 against $0.130 (as of November 2026). 1K and 2K images use 3 credits, or 5 on Highspeed. [GET features](/docs/api-minimax-v1/get-minimax-features) shows the credits left. #### Can MiniMax H3 Image combine reference images? Yes. Through the useapi.net MiniMax API you can pass up to 16 reference images as `referenceFileId1` to `referenceFileId16` and refer to each one in the prompt as `@Image1` to `@Image16`, so one prompt can place a person from one photo into the scene or onto the object of another. [The example above](#example-one-person-and-one-motorcycle-from-two-reference-images) shows the full call. #### What is the difference between H3 Image and H3 Image Highspeed? Both run on the useapi.net MiniMax API with the same parameters, resolutions and 16 references. Hailuo describes Highspeed as the same image quality with faster generation. On Hailuo it costs 5 credits an image at 1K or 2K and 12 at 4K, against 3 and 6 for H3 Image. ### Conclusion * [POST images/create](/docs/api-minimax-v1/post-minimax-images-create), every parameter and the credits of all 11 MiniMax image models * [MiniMax API overview](/docs/api-minimax-v1), models, plans and prices * [How to Generate Hailuo 02 and 2.3 Video with curl](/docs/articles/minimax-bash), video on the same account * [MiniMax MCP server](/docs/api-minimax-v1/mcp), the same images from Claude, ChatGPT or Cursor === URL: https://useapi.net/docs/articles/minimax-speech-bash === Document URL: https://useapi.net/docs/articles/minimax-speech-bash --- layout: default title: "How to Generate Text-to-Speech (TTS) Audio with the MiniMax (Hailuo) API" description: "Drive MiniMax Speech 2.8 from code through a third-party REST API — pick a voice, steer emotion and pacing with inline markup, get word timings for captions, clone a voice, and stream the audio as it renders." keywords: [MiniMax TTS API, MiniMax Speech 2.8, text to speech API, voice cloning API, SSE audio streaming, speech markup, word timings, Hailuo audio API] parent: Articles nav_exclude: true date: 2026-08-24 last_modified: 2026-11-20 nav_order: 880 repo: https://github.com/useapi/minimax-api --- ## How to Generate Text-to-Speech (TTS) Audio with the MiniMax (Hailuo) API August 24, 2026 (November 20, 2026) --- MiniMax Speech turns text into narration with ten models, several hundred voices, and enough control over emotion and pacing that the result does not sound like a screen reader. This walks through the whole surface — choosing a voice, steering delivery, captions, cloning, and the three different ways to get the audio out — using [Speech 2.8](https://www.minimax.io/audio/text-to-speech) throughout. Everything here runs against the [MiniMax API v1](/docs/api-minimax-v1) on useapi.net. You need a MiniMax account configured once, see [Setup MiniMax](/docs/start-here/setup-minimax). Every recording on this page was generated by the calls shown next to it. Cost first, since it is usually the deciding factor. All three prices below are MiniMax's own — what changes is which MiniMax product you buy: | Cost of 1,000,000 characters on `speech-2.8-hd` | | |:---|---:| | [minimax.io/audio](https://www.minimax.io/audio/subscribe) — Pro plan, $99/mo (what this API uses) | $33 | | [platform.minimax.io](https://platform.minimax.io/docs/pricing/overview#packages/speech) — Audio Subscription, Pro $99/mo | $90 | | [platform.minimax.io](https://platform.minimax.io/docs/pricing/overview#models/speech) — pay-as-you-go | $100 | A third of the price of MiniMax's own developer API, for the same audio. On `turbo` it is $19.80 a million against pay-as-you-go's $60 — the same gap. [What it costs](#what-it-costs) has the rest. ### Three ways to get audio Pick by how long the text is and whether you want to wait. | | Endpoint | Text limit | You get | |---|---|---|---| | Short and simple | [POST speech/create-mp3](/docs/api-minimax-v1/post-minimax-speech-create-mp3) | 3,000 characters | The finished MP3 URL in one call | | Anything longer | [POST speech/create](/docs/api-minimax-v1/post-minimax-speech-create) | 5,000, or 10,000 on `turbo` | An `audioId` straight away, plus a `replyUrl` callback | | Start playing sooner | [POST speech/create](/docs/api-minimax-v1/post-minimax-speech-create) with `"stream": true` | 5,000, or 10,000 on `turbo` | The audio streamed back as it renders, so playback can start before it is finished | `create-mp3` holds the connection open for the whole generation, which is why it is capped below what the models accept — 3,000 characters is about 22 seconds of waiting. For anything longer, use `create`. ### Your first call ```bash curl 'https://api.useapi.net/v1/minimax/speech/create-mp3' \ --header 'Authorization: Bearer user:1234-…' \ --header 'Content-Type: application/json' \ --data '{ "voice_id": "380426458095854", "text": "The last train leaves at midnight, and I still have not packed." }' ``` <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-24-minimax-speech-bash/01-baseline.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> That is `speech-2.8-hd`, the default, with no styling at all. Everything below is that same line with one thing changed. ### Picking a voice [GET speech/voices](/docs/api-minimax-v1/get-minimax-speech-voices) lists what the account can use. It returns 600+ voices across 40 languages, and MiniMax keeps adding: > English, Arabic, Cantonese, Chinese (Mandarin), Dutch, French, German, Indonesian, Italian, Japanese, Korean, Portuguese, Russian, Spanish, Turkish, Ukrainian, Vietnamese, Thai, Polish, Romanian, Greek, Czech, Finnish, Hindi, Bulgarian, Danish, Hebrew, Malay, Persian, Slovak, Swedish, Croatian, Filipino, Hungarian, Norwegian, Slovenian, Catalan, Nynorsk, Tamil, Afrikaans Each voice carries tags for language, accent, gender and age, and `tag_list` filters on them. Matching is exact and case-sensitive, and a tag it does not recognise is ignored rather than rejected — so `Female,Middle-Aged` returns the same 310 voices as `Female` alone rather than none. A typo widens the result instead of narrowing it, so check the count when you add a filter. [GET speech/config](/docs/api-minimax-v1/get-minimax-speech-config) returns the current vocabulary. ```bash curl "https://api.useapi.net/v1/minimax/speech/voices?is_system=true&tag_list=English" \ -H "Authorization: Bearer …" ``` The voice does more to the result than any other parameter. Same text, same model, a British female voice instead of the US male above: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-minimax-v1/post-minimax-speech-create-mp3">POST speech/create-mp3</a> (Compelling Lady, EN-British)</summary> ```bash curl 'https://api.useapi.net/v1/minimax/speech/create-mp3' \ --header 'Authorization: Bearer user:1234-…' \ --header 'Content-Type: application/json' \ --data '{ "voice_id": "236835177529411", "model": "speech-2.8-hd", "text": "The last train leaves at midnight, and I still have not packed." }' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-24-minimax-speech-bash/11-voice-british.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ### Steering the delivery Everything from here uses a cloned voice called **Scarlett**, built from a one-minute sample — see [Cloning a voice](#cloning-a-voice). The controls work identically on the built-in voices. Each sample has the exact call that produced it folded up above it. Three kinds of markup go directly inside `text`, and they combine. Only emotion tags are free, because they are stripped before billing. Sounds and pauses are billed in full, markup and all. #### Emotion Wrap a span in `{emotion}…{/emotion}`. Eight are available — `happy`, `sad`, `angry`, `fearful`, `disgusted`, `surprised`, `neutral`, `fluent` — and a single request may carry up to 15 spans. The five below are the ones that separate most cleanly. `surprised` and `happy` tend to converge, as do `neutral` and `sad`, so pick across the range rather than adjacent to it. The line is the same six words every time — only the delivery decides whether it is an accusation, dread, revulsion, delight or grief. `{angry}` — accusation: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-minimax-v1/post-minimax-speech-create-mp3">POST speech/create-mp3</a> (angry)</summary> ```bash curl 'https://api.useapi.net/v1/minimax/speech/create-mp3' \ --header 'Authorization: Bearer user:1234-…' \ --header 'Content-Type: application/json' \ --data '{ "voice_id": "user:12345-minimax:1234…-voice:433688037470324", "model": "speech-2.8-hd", "text": "{angry}Look at what you have done.{/angry}" }' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-24-minimax-speech-bash/e-scarlett-angry.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> `{fearful}` — dread: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-minimax-v1/post-minimax-speech-create-mp3">POST speech/create-mp3</a> (fearful)</summary> ```bash curl 'https://api.useapi.net/v1/minimax/speech/create-mp3' \ --header 'Authorization: Bearer user:1234-…' \ --header 'Content-Type: application/json' \ --data '{ "voice_id": "user:12345-minimax:1234…-voice:433688037470324", "model": "speech-2.8-hd", "text": "{fearful}Look at what you have done.{/fearful}" }' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-24-minimax-speech-bash/e-scarlett-fearful.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> `{disgusted}` — revulsion: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-minimax-v1/post-minimax-speech-create-mp3">POST speech/create-mp3</a> (disgusted)</summary> ```bash curl 'https://api.useapi.net/v1/minimax/speech/create-mp3' \ --header 'Authorization: Bearer user:1234-…' \ --header 'Content-Type: application/json' \ --data '{ "voice_id": "user:12345-minimax:1234…-voice:433688037470324", "model": "speech-2.8-hd", "text": "{disgusted}Look at what you have done.{/disgusted}" }' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-24-minimax-speech-bash/e-scarlett-disgusted.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> `{happy}` — delight: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-minimax-v1/post-minimax-speech-create-mp3">POST speech/create-mp3</a> (happy)</summary> ```bash curl 'https://api.useapi.net/v1/minimax/speech/create-mp3' \ --header 'Authorization: Bearer user:1234-…' \ --header 'Content-Type: application/json' \ --data '{ "voice_id": "user:12345-minimax:1234…-voice:433688037470324", "model": "speech-2.8-hd", "text": "{happy}Look at what you have done.{/happy}" }' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-24-minimax-speech-bash/e-scarlett-happy.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> `{sad}` — grief: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-minimax-v1/post-minimax-speech-create-mp3">POST speech/create-mp3</a> (sad)</summary> ```bash curl 'https://api.useapi.net/v1/minimax/speech/create-mp3' \ --header 'Authorization: Bearer user:1234-…' \ --header 'Content-Type: application/json' \ --data '{ "voice_id": "user:12345-minimax:1234…-voice:433688037470324", "model": "speech-2.8-hd", "text": "{sad}Look at what you have done.{/sad}" }' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-24-minimax-speech-bash/e-scarlett-sad.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> How far a voice can swing is set by the voice, not the tag. A clone inherits the range of whatever you fed it, so a one-minute sample of even-toned speech will not shout. The built-in voices tagged as expressive have more headroom — the same five emotions on `Radiant Girl` (`236835177529409`), for comparison: [angry](https://media.useapi.net/articles/2026-08-24-minimax-speech-bash/e-radiant-angry.mp3), [fearful](https://media.useapi.net/articles/2026-08-24-minimax-speech-bash/e-radiant-fearful.mp3), [disgusted](https://media.useapi.net/articles/2026-08-24-minimax-speech-bash/e-radiant-disgusted.mp3), [happy](https://media.useapi.net/articles/2026-08-24-minimax-speech-bash/e-radiant-happy.mp3), [sad](https://media.useapi.net/articles/2026-08-24-minimax-speech-bash/e-radiant-sad.mp3). #### Sounds Nineteen non-speech sounds render in place when written in parentheses: `laughs`, `chuckle`, `coughs`, `clear-throat`, `groans`, `breath`, `pant`, `inhale`, `exhale`, `gasps`, `sniffs`, `sighs`, `snorts`, `burps`, `lip-smacking`, `humming`, `hissing`, `emm`, `sneezes`. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-minimax-v1/post-minimax-speech-create-mp3">POST speech/create-mp3</a> (sighs and laughs)</summary> ```bash curl 'https://api.useapi.net/v1/minimax/speech/create-mp3' \ --header 'Authorization: Bearer user:1234-…' \ --header 'Content-Type: application/json' \ --data '{ "voice_id": "user:12345-minimax:1234…-voice:433688037470324", "model": "speech-2.8-hd", "text": "I told you this would happen (sighs). Every single time (laughs)." }' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-24-minimax-speech-bash/s07-sounds.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### Pauses `<#seconds#>` inserts a silence, anywhere from `0.01` to `99.99` seconds. This is the one that most improves long narration — models tend to run sentences together, and a beat between them fixes it. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-minimax-v1/post-minimax-speech-create-mp3">POST speech/create-mp3</a> (1.5 second pause)</summary> ```bash curl 'https://api.useapi.net/v1/minimax/speech/create-mp3' \ --header 'Authorization: Bearer user:1234-…' \ --header 'Content-Type: application/json' \ --data '{ "voice_id": "user:12345-minimax:1234…-voice:433688037470324", "model": "speech-2.8-hd", "text": "I told you this would happen. <#1.5#> Every single time." }' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-24-minimax-speech-bash/s08-pauses.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### Speed and pitch `speed` runs `0.5` to `2` and `pitch` runs `-12` to `12`, both independent of the markup above. Back to the longer line so the difference is easier to hear. `"speed": 0.7` — 7.6 seconds: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-minimax-v1/post-minimax-speech-create-mp3">POST speech/create-mp3</a> (speed 0.7)</summary> ```bash curl 'https://api.useapi.net/v1/minimax/speech/create-mp3' \ --header 'Authorization: Bearer user:1234-…' \ --header 'Content-Type: application/json' \ --data '{ "voice_id": "user:12345-minimax:1234…-voice:433688037470324", "model": "speech-2.8-hd", "text": "The last train leaves at midnight, and I still have not packed.", "speed": 0.7 }' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-24-minimax-speech-bash/s09-speed-slow.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> `"speed": 1.5` — 3.2 seconds: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-minimax-v1/post-minimax-speech-create-mp3">POST speech/create-mp3</a> (speed 1.5)</summary> ```bash curl 'https://api.useapi.net/v1/minimax/speech/create-mp3' \ --header 'Authorization: Bearer user:1234-…' \ --header 'Content-Type: application/json' \ --data '{ "voice_id": "user:12345-minimax:1234…-voice:433688037470324", "model": "speech-2.8-hd", "text": "The last train leaves at midnight, and I still have not packed.", "speed": 1.5 }' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-24-minimax-speech-bash/s10-speed-fast.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> `"pitch": -6`: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-minimax-v1/post-minimax-speech-create-mp3">POST speech/create-mp3</a> (pitch -6)</summary> ```bash curl 'https://api.useapi.net/v1/minimax/speech/create-mp3' \ --header 'Authorization: Bearer user:1234-…' \ --header 'Content-Type: application/json' \ --data '{ "voice_id": "user:12345-minimax:1234…-voice:433688037470324", "model": "speech-2.8-hd", "text": "The last train leaves at midnight, and I still have not packed.", "pitch": -6 }' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-24-minimax-speech-bash/s11-pitch-low.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> `"pitch": 6`: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-minimax-v1/post-minimax-speech-create-mp3">POST speech/create-mp3</a> (pitch +6)</summary> ```bash curl 'https://api.useapi.net/v1/minimax/speech/create-mp3' \ --header 'Authorization: Bearer user:1234-…' \ --header 'Content-Type: application/json' \ --data '{ "voice_id": "user:12345-minimax:1234…-voice:433688037470324", "model": "speech-2.8-hd", "text": "The last train leaves at midnight, and I still have not packed.", "pitch": 6 }' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-24-minimax-speech-bash/s12-pitch-high.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> There are also voice effects — `deepen_lighten`, `stronger_softer` and `nasal_crisp` take `-100` to `100`, and `spacious_echo`, `lofi_telephone`, `robotic` and `auditorium_echo` are switches. ### Choosing a model | Model | Max characters | Credits per character | Status | |---|---|---|---| | `speech-2.8-hd` | 5,000 | 1 | Current, and the default | | `speech-2.8-turbo` | 10,000 | 0.6 | Current | | `speech-2.6-hd` | 5,000 | 1 | Previous generation | | `speech-2.6-turbo` | 10,000 | 0.6 | Previous generation | | `speech-2.5-hd-preview` | 5,000 | 1 | Superseded by 2.6 | | `speech-2.5-turbo-preview` | 10,000 | 0.6 | Superseded by 2.6 | | `speech-02-hd` | 5,000 | 1 | Legacy | | `speech-02-turbo` | 10,000 | 0.6 | Legacy | | `speech-01-hd` | 5,000 | 1 | Legacy | | `speech-01-turbo` | 10,000 | 0.6 | Legacy | Use `speech-2.8-hd` unless you have a reason not to. The older models stay selectable because they are still live at MiniMax, and because regenerating audio to match something made earlier needs the model that made it — not because they are worth picking for new work. Within a generation, `hd` and `turbo` are the same model tuned differently. `turbo` costs 40% less per character and accepts twice the text in a single call. It is not measurably faster — on identical 990-character text the two came out level — so pick `turbo` for the cheaper rate and the higher ceiling, and `hd` when voice quality matters most. Sending more than a model accepts returns `400` before anything is generated, so an oversized request never costs credits. The message names the model and its limit — `Parameter text length (5001) exceeds 5000 characters for model speech-2.8-hd` — except at the absolute 10,000 ceiling, which is checked first and reports the limit without the model. `hd` and `turbo` are the same family tuned differently. Turbo on the same line: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-minimax-v1/post-minimax-speech-create-mp3">POST speech/create-mp3</a> (speech-2.8-turbo)</summary> ```bash curl 'https://api.useapi.net/v1/minimax/speech/create-mp3' \ --header 'Authorization: Bearer user:1234-…' \ --header 'Content-Type: application/json' \ --data '{ "voice_id": "user:12345-minimax:1234…-voice:433688037470324", "model": "speech-2.8-turbo", "text": "The last train leaves at midnight, and I still have not packed." }' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-24-minimax-speech-bash/s13-turbo.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> For narration where nobody is waiting, `speech-2.8-turbo` is usually the better trade — it takes twice the text per call and costs 0.6 credits a character against `hd`'s 1, which MiniMax mirrors as $60 against $100 per million on their own API. ### Word timings for captions A finished generation carries a `subtitles` array with millisecond boundaries per phrase. ```json "subtitles": [ { "text": "The last train leaves at midnight", "time_begin": 0, "time_end": 2245.2 } ] ``` Use `time_begin` and `time_end`. The `text_begin` and `text_end` fields come back from MiniMax but do not reliably index into the text, so treat them as opaque. One limitation worth planning around: timings only reach you through [POST speech/create-mp3](/docs/api-minimax-v1/post-minimax-speech-create-mp3) or the streaming `done` event. MiniMax does not store them, so polling [GET speech/`audioId`](/docs/api-minimax-v1/get-minimax-speech_audio_id) or waiting on a `replyUrl` callback gives you `has_srt` but not the timings themselves. If you need captions for more than 3,000 characters, use `stream` and keep the `done` payload. ### Long text without waiting [POST speech/create](/docs/api-minimax-v1/post-minimax-speech-create) answers in about four seconds with an `audioId`, whatever the length, and keeps generating in the background. ```bash curl "https://api.useapi.net/v1/minimax/speech/create" \ -H "Authorization: Bearer …" \ -H "Content-Type: application/json" \ -d '{ "voice_id": "380426458095854", "model": "speech-2.8-turbo", "text": "…up to 10,000 characters…", "replyUrl": "https://your.app/webhook" }' ``` ```json { "audioId": "user:12345-minimax:1234…-audio:178737039436895391", "statusLabel": "pending", "statusFinal": false } ``` Then either wait for the POST to `replyUrl`, or poll [GET speech/`audioId`](/docs/api-minimax-v1/get-minimax-speech_audio_id) until `statusFinal` is `true`. A 10,000-character request takes around 78 seconds and yields 12 to 16 minutes of speech, so poll every few seconds rather than tightly. ### Streaming Set `stream` to `true` and the response is `text/event-stream` instead of JSON, with the id in an `X-Audio-Id` header. First audio lands about four seconds in rather than at the end. The `audio` events carry two different things, and `format` tells them apart. `format: "mp3"` events are chunks — append them in arrival order and the result is a plain MP3. A short line sends one, a 10,000-character generation sends around 40 over a minute or two. `format: "wav"` with `complete: true` is the same speech again as a whole WAV file, delivered after the chunks. Do not append that one. ```javascript const chunks = []; if (event === "audio" && payload.format === "mp3") chunks.push(Uint8Array.from(atob(payload.chunk), c => c.charCodeAt(0))); ``` A streamed generation is tracked like any other, so if the connection drops the recording still completes and the `audioId` still resolves. Full worked example on the [endpoint page](/docs/api-minimax-v1/post-minimax-speech-create#streaming). ### Cloning a voice Every sample from [Steering the delivery](#steering-the-delivery) onward uses a cloned voice. This is how it was made. Two calls. [POST speech/upload-sample](/docs/api-minimax-v1/post-minimax-speech-upload-sample) takes the raw bytes of an MP3 or WAV and returns a `fileId`, then [POST speech/clone-voice](/docs/api-minimax-v1/post-minimax-speech-clone-voice) turns that into a voice you pass as `voice_id` anywhere above. ```bash curl "https://api.useapi.net/v1/minimax/speech/upload-sample" \ -H "Authorization: Bearer …" \ -H "Content-Type: audio/mpeg" \ --data-binary "@sample.mp3" ``` ```json { "fileID": "user:12345-minimax:1234…-file:54768197611603968682433" } ``` Feed that straight into the clone: ```bash curl "https://api.useapi.net/v1/minimax/speech/clone-voice" \ -H "Authorization: Bearer …" \ -H "Content-Type: application/json" \ -d '{ "voice_name": "Scarlett", "language_tag": "English", "files": "user:12345-minimax:1234…-file:54768197611603968682433" }' ``` ```json { "voice_id": "user:12345-minimax:1234…-voice:433688037470324", "voice_name": "Scarlett", "voice_status": 2 } ``` This is the source sample that was uploaded — one minute of ordinary speech, nothing special: <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-24-minimax-speech-bash/s00-clone-source.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> And this is the clone reading a line it has never seen, 35 seconds after that upload: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-minimax-v1/post-minimax-speech-create-mp3">POST speech/create-mp3</a> (cloned voice)</summary> ```bash curl 'https://api.useapi.net/v1/minimax/speech/create-mp3' \ --header 'Authorization: Bearer user:1234-…' \ --header 'Content-Type: application/json' \ --data '{ "voice_id": "user:12345-minimax:1234…-voice:433688037470324", "model": "speech-2.8-hd", "text": "The last train leaves at midnight, and I still have not packed." }' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-24-minimax-speech-bash/s01-baseline.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> The returned `voice_id` goes anywhere `voice_id` is accepted, exactly like a built-in one. [POST speech/upload-sample](/docs/api-minimax-v1/post-minimax-speech-upload-sample) takes `?account=` in the query string, like the read endpoints — there is no identifier to infer it from, since the body is raw bytes. The `fileID` it returns then pins the voice to that account, which is why [POST speech/clone-voice](/docs/api-minimax-v1/post-minimax-speech-clone-voice) takes no `account` of its own and reads it from `files`. [POST speech/delete-voice](/docs/api-minimax-v1/post-minimax-speech-delete-voice) works the same way, taking only a `voice_id`. #### Slots Cloned voices occupy a slot, and how many you get depends on the MiniMax plan. Check before you spend 35 seconds discovering there is no room: ```bash curl "https://api.useapi.net/v1/minimax/speech/equity" -H "Authorization: Bearer …" ``` ```json { "used": 2, "total": 3, "voice_clone_preview_free_quota": "inf" } ``` Free one with [POST speech/delete-voice](/docs/api-minimax-v1/post-minimax-speech-delete-voice). Note `used` is allowed to exceed `total` — treat these as advisory and let the clone call itself be the authority. Only clone voices you have permission to use. ### Managing what you have generated [GET speech](/docs/api-minimax-v1/get-minimax-speech) lists every recording on the account, newest first, including any made on minimax.io directly. Each row carries the `audio_url`, the voice name, and `has_srt` / `has_wav` telling you whether timings and a WAV rendition exist. ```bash curl "https://api.useapi.net/v1/minimax/speech/?page_size=10" \ -H "Authorization: Bearer …" ``` [GET speech/`audioId`](/docs/api-minimax-v1/get-minimax-speech_audio_id) returns one recording in full — the voice it used, the model, `cost_credit`, and the speed, pitch and effects it was generated with. It is also what you poll after an async create. [DELETE speech/`audioId`](/docs/api-minimax-v1/del-minimax-speech-audio_id) removes one permanently. A generation still in flight cannot be deleted, because there is nothing stored yet — cancel that with [DELETE scheduler/`id`](/docs/api-minimax-v1/del-minimax-scheduler-videoId) instead. ### What it costs Speech bills per character against the MiniMax Audio balance — the same pool music draws on. One credit per character on an `hd` model, 0.6 on a `turbo` one. That works out to $33 a million characters on the $99 Pro plan, against $100 on MiniMax's own pay-as-you-go API — the comparison at the top of this page has all three options side by side. A few things worth knowing: - `cost_credit` appears only on [GET speech/`audioId`](/docs/api-minimax-v1/get-minimax-speech_audio_id), not on the list or on the `create-mp3` response — that one returns `usage_characters`, the raw count before the model's ratio. - Emotion tags are free. Sound and pause markup is billed as written: 79 characters including `(sighs)` and `(laughs)` billed as 79. - `turbo` is charged at 0.6 credits a character, and the discount is real credits rather than a list price. [GET speech/`audioId`](/docs/api-minimax-v1/get-minimax-speech_audio_id) reports what was charged as `cost_credit`. - Speech needs a MiniMax audio subscription. Without one the call returns `412` however much video credit the account holds, though a new account gets a small allowance first. - Only a few generations run concurrently per account. Past that a request returns `429` and the ones already running are unaffected, so retry when one finishes. The ceiling looks plan-dependent — a free account allows three. ### Examples Every recording on this page is a real generation, and the call that produced it is folded up directly above it. The first two use built-in voices. Everything from [Steering the delivery](#steering-the-delivery) onward uses the cloned Scarlett voice on `speech-2.8-hd` unless noted, apart from the long-text example, which is back on a built-in voice. Clone source and result: [the one-minute sample](https://media.useapi.net/articles/2026-08-24-minimax-speech-bash/s00-clone-source.mp3) that was uploaded, and [the clone](https://media.useapi.net/articles/2026-08-24-minimax-speech-bash/s01-baseline.mp3) reading a line it had never seen. Emotion, the same six words each time — [angry](https://media.useapi.net/articles/2026-08-24-minimax-speech-bash/e-scarlett-angry.mp3), [fearful](https://media.useapi.net/articles/2026-08-24-minimax-speech-bash/e-scarlett-fearful.mp3), [disgusted](https://media.useapi.net/articles/2026-08-24-minimax-speech-bash/e-scarlett-disgusted.mp3), [happy](https://media.useapi.net/articles/2026-08-24-minimax-speech-bash/e-scarlett-happy.mp3), [sad](https://media.useapi.net/articles/2026-08-24-minimax-speech-bash/e-scarlett-sad.mp3). The same five on the built-in `Radiant Girl`, which has more range: [angry](https://media.useapi.net/articles/2026-08-24-minimax-speech-bash/e-radiant-angry.mp3), [fearful](https://media.useapi.net/articles/2026-08-24-minimax-speech-bash/e-radiant-fearful.mp3), [disgusted](https://media.useapi.net/articles/2026-08-24-minimax-speech-bash/e-radiant-disgusted.mp3), [happy](https://media.useapi.net/articles/2026-08-24-minimax-speech-bash/e-radiant-happy.mp3), [sad](https://media.useapi.net/articles/2026-08-24-minimax-speech-bash/e-radiant-sad.mp3). Everything else: [sounds](https://media.useapi.net/articles/2026-08-24-minimax-speech-bash/s07-sounds.mp3), [pauses](https://media.useapi.net/articles/2026-08-24-minimax-speech-bash/s08-pauses.mp3), [slow](https://media.useapi.net/articles/2026-08-24-minimax-speech-bash/s09-speed-slow.mp3), [fast](https://media.useapi.net/articles/2026-08-24-minimax-speech-bash/s10-speed-fast.mp3), [low pitch](https://media.useapi.net/articles/2026-08-24-minimax-speech-bash/s11-pitch-low.mp3), [high pitch](https://media.useapi.net/articles/2026-08-24-minimax-speech-bash/s12-pitch-high.mp3), [turbo](https://media.useapi.net/articles/2026-08-24-minimax-speech-bash/s13-turbo.mp3). Related tutorials: [MiniMax (Hailuo) video](/docs/articles/minimax-bash) and [Mureka music, speech and voice cloning](/docs/articles/mureka-bash). ### Use it from Claude, ChatGPT or Cursor The hosted [MiniMax MCP server](/docs/api-minimax-v1/mcp) gives Claude Code, Cursor, VS Code and other MCP clients the speech calls on this page as tools, with nothing to install, and the Claude app and ChatGPT connect to it with a sign-in. It has 38 tools in all and runs on your own MiniMax accounts with your useapi.net API token. In Claude Code: ```bash claude mcp add --transport http useapi-minimax https://api.useapi.net/v1/minimax/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` Then ask, for example, "Clone my voice from these two recordings, then read this paragraph with it". The assistant uploads the samples with `minimax_upload_voice_sample`, builds the voice with `minimax_clone_voice` and speaks with `minimax_create_speech`, which takes the same models, voices and emotions as [POST speech/create](/docs/api-minimax-v1/post-minimax-speech-create). MiniMax's own MiniMax-MCP has 8 tools and runs locally on a pay-as-you-go developer API key ([comparison](/docs/api-minimax-v1/mcp#useapinet-vs-minimaxs-own-mcp-server)). The [`minimax-api`](https://github.com/useapi/minimax-api#use-with-claude-code) repo also installs as a Claude Code plugin or a [Gemini CLI extension](https://github.com/useapi/minimax-api#use-with-gemini-cli). ### Where to go next - [POST speech/create](/docs/api-minimax-v1/post-minimax-speech-create) — every parameter, response and error - [GET speech/voices](/docs/api-minimax-v1/get-minimax-speech-voices) — the voice catalogue - [GET speech/config](/docs/api-minimax-v1/get-minimax-speech-config) — emotion and tag vocabularies, for building your own picker - [MiniMax MCP server](/docs/api-minimax-v1/mcp) — the same speech, voices and cloning from Claude, ChatGPT or Cursor - [`minimax-api` GitHub repo](https://github.com/useapi/minimax-api) — a runnable batch script that reads a list of lines, generates each one, and downloads the MP3s, with a `--voices` mode for finding a `voice_id` #### Cross posted Also published on [dev.to](https://dev.to/useapi/how-to-generate-text-to-speech-audio-with-the-minimax-hailuo-api-4bo1){:rel="nofollow"}. === URL: https://useapi.net/docs/articles/mureka-bash === Document URL: https://useapi.net/docs/articles/mureka-bash --- layout: default title: How to Generate AI Music with the Mureka API description: "Generate AI songs and speech with the Mureka AI API by useapi.net on your Mureka subscription: V9.5 and O2, custom lyrics, voice cloning and a batch script." keywords: [Mureka API, AI music generation API, Suno alternative, Udio alternative, Mureka AI, text to music, custom lyrics, voice cloning, V9.5, O2] parent: Articles nav_exclude: true date: 2026-06-22 last_modified: 2026-10-21 nav_order: 805 repo: https://github.com/useapi/mureka-api --- ## How to Generate AI Music with the Mureka API 7 min read • June 22, 2026 (October 21, 2026) ## Table of contents ### Introduction [Mureka AI](https://www.mureka.ai) turns a single text prompt into a complete, produced song — a direct [Suno](https://www.suno.com) and [Udio](https://www.udio.com) alternative — and the [useapi.net Mureka API](/docs/api-mureka-v1) drives your own Mureka account over plain REST, with its latest `V9.5` default and flagship `O2` models, at your normal consumer subscription price. Mureka is the music generator from Chinese tech company [Kunlun Tech](https://www.kunlun.com/), built on its proprietary Mureka models (`mureka-9.5`, `mureka-o2`). One generation returns two complete songs — vocals, melody, and arrangement — and from there you can write your own lyrics, force an instrumental, seed a track from a reference song or melody, extend a song, or clone a voice for text-to-speech. [useapi.net](/docs/subscription) runs all of it from one API token. ### Pricing You keep your normal [Mureka](https://www.mureka.ai/subscribe) web subscription for the underlying credits, and useapi.net adds no per-song charge. Mureka's own subscription plans: | Plan | Price | Songs / month | Cost per song | |------|------:|--------------:|--------------:| | Pro | $10/month | up to 500 | ~2.4¢ on V9.5 | | Premier | $30/month | up to 2,000 | ~1.8¢ on V9.5 | Song and speech allowances are shared (songs *or* speech minutes), lyrics generation is free, and downloading instrumentals and stems is free. The newer V9.5, V9 and O2 models consume more Gold per song, so real counts run lower — roughly 250–400 songs on V9.5/V9/O2. Pro/Premier members can buy additional Gold packs (price shown at checkout). This is the consumer-account route. Mureka also runs an [official developer API](https://platform.mureka.ai/pricing), but it works differently — it is sold as prepaid top-ups with 12-month validity, consumed per call rather than billed monthly, and the ladder runs from $1,000 (5 concurrent requests) up to $30,000 (150 concurrent). Generation there runs ~$0.15/song on V9.5 and ~$0.045/song on V9/V8/O2 (~$0.03 on the older V7.6), plus extra charges for lyrics generation and stem export. useapi.net instead automates the [consumer plan](https://www.mureka.ai/subscribe) you already pay for, so a $30 Premier plan covers far more generation than the official API's entry tier. For other music options under the same subscription, see the [Flow Music API tutorial](/docs/articles/flowmusic-bash) (Google's Lyria 3 Pro) and the [TemPolor API](/docs/api-tempolor-v1). ### Supported models Pick a model per request with the `model` field on [POST /music/create](/docs/api-mureka-v1/post-mureka-music-create). Omit it and the API applies its default, `V9.5`. | Model | Engine | What it's for | |-------|--------|---------------| | `V9.5` (default) | `mureka-9.5` | Latest generation, used when `model` is omitted — natural songwriting, authentic performances, fuller sound. | | `V9` | `mureka-9` | Prior flagship — advanced prompt control and studio-grade sound. | | `O2` | `mureka-o2` | Flagship high-end model — best audio quality and musical coherence, with strong multilingual vocals. | | `V8` | `mureka-8.0.1` | Prior-generation general-purpose model. | | `V7.6` | `mureka-7.6` | Earlier model kept for compatibility — it was the default before V9. | Older aliases (`V7.5`, `V7`, `O1`, `V6`) are still accepted but redirect to current engines, so prefer the five models above. Every model returns finished MP3 audio. For more than audio, [POST /music/stems](/docs/api-mureka-v1/post-mureka-music-stems) splits a song into stems with MIDI, and [POST /music/score](/docs/api-mureka-v1/post-mureka-music-score) turns it into sheet music (see [How to Turn a Song or YouTube Link into Sheet Music](/docs/articles/mureka-sheet-music)). The same account and token also drive Mureka's text-to-speech and voice cloning, covered [below](#clone-a-voice-and-generate-multi-speaker-speech). ### Generate a song in two API calls You need a useapi.net [API token](/docs/start-here/setup-useapi) and a connected [Mureka account](/docs/start-here/setup-mureka) — export the token so the `curl` examples below run as-is: ```bash export USEAPI_TOKEN="user:1234-..." ``` The most reliable workflow is asynchronous: the create call returns a `jobid` immediately, then you poll until both songs are ready. **1. Submit the job** — `POST https://api.useapi.net/v1/mureka/music/create`: ```bash curl -X POST "https://api.useapi.net/v1/mureka/music/create" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "account": "12345678901234", "prompt": "upbeat synthwave with bright female vocals about chasing a sunrise, 110 bpm", "model": "V9.5", "async": true }' ``` The `account` is your Mureka account id, and it is optional when you have a single account configured (the API auto-selects it). In `async` mode the response returns immediately with `201 Created`, a `jobid`, and `status: "created"`: ```json { "jobid": "j0622184042017475905m-u1234-a12345678901234-bot:mureka", "verb": "music/create", "jobType": "music", "status": "created", "created": "2026-06-22T18:40:42.412Z", "request": { "account": "12345678901234", "prompt": "upbeat synthwave with bright female vocals about chasing a sunrise, 110 bpm", "model": "V9.5", "async": true } } ``` **2. Poll for the result** — `GET https://api.useapi.net/v1/mureka/jobs/{jobid}` (the `jobid` ends in `bot:mureka`, so URL-encode it in the path — it contains a `:`): ```bash curl "https://api.useapi.net/v1/mureka/jobs/JOBID" \ -H "Authorization: Bearer $USEAPI_TOKEN" ``` When `status` is `completed`, the finished audio lives in `response.songs[]`. Each generation returns two songs (an A/B pair, `version` `"1"` and `"2"`), and each carries an `mp3_url` plus cover art: ```json { "jobid": "j0622184042017475905m-u1234-a12345678901234-bot:mureka", "status": "completed", "response": { "feed_id": 11223344, "state": 3, "songs": [ { "song_id": "user:1234-mureka:123456789-song:33445566", "title": "Chasing the Sunrise", "version": "1", "duration_milliseconds": 173040, "mp3_url": "https://static-cos.mureka.ai/cos-prod/...1.mp3", "cover": "https://static-cos.mureka.ai/cos-prod/...1.png" }, { "song_id": "user:1234-mureka:123456789-song:33445567", "title": "Chasing the Sunrise", "version": "2", "duration_milliseconds": 178910, "mp3_url": "https://static-cos.mureka.ai/cos-prod/...2.mp3", "cover": "https://static-cos.mureka.ai/cos-prod/...2.png" } ] } } ``` A song typically finishes in 30–90 seconds (about 45 on average), and an account supports up to 10 parallel generations. Songs can run up to about 5 minutes depending on the lyrics. Jobs are retained for 7 days, so you can re-fetch a finished result any time in that window. Prefer not to poll? Pass a `replyUrl` in the create body to receive a webhook callback when the job completes (the payload matches the poll response). A job can come back `status: "failed"` (e.g. a content-policy rejection), and the create call may return `402` (useapi.net subscription expired) / `412` (out of Mureka credits), `429` (rate limit, or all 10 generation slots busy), or `596` (account session error) — see the [endpoint docs](/docs/api-mureka-v1/post-mureka-music-create) for the full list. ### Write your own lyrics, or force an instrumental The plain `prompt` on [POST /music/create](/docs/api-mureka-v1/post-mureka-music-create) lets the model write the lyrics for you. To supply your own words, switch to [POST /music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced) — `lyrics` is required there (use `[Verse]` / `[Chorus]` tags, 50–5,000 chars), and `desc` steers the style with a comma-separated list of genres, moods, and vocal direction. `vocal_gender` forces `male` or `female`: ```bash # Your own lyrics → forces a vocal render of those exact words curl -X POST "https://api.useapi.net/v1/mureka/music/create-advanced" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "lyrics": "[Verse 1]\nCity lights blur in the rain\n[Chorus]\nAnd I will wait for the morning sun", "desc": "soulful R&B, lush keys, 90 bpm", "vocal_gender": "female", "model": "V9.5", "async": true }' ``` For a purely instrumental track, use [POST /music/create-instrumental](/docs/api-mureka-v1/post-mureka-music-create-instrumental) — just a `prompt` describing the music, no lyrics: ```bash curl -X POST "https://api.useapi.net/v1/mureka/music/create-instrumental" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "ethereal post-rock, cascading delay guitars, orchestral swells building to a cinematic crescendo", "model": "O2", "async": true }' ``` All three endpoints return the same `jobid` you poll on, and any resulting `song_id` can be lengthened with [POST /music/extend](/docs/api-mureka-v1/post-mureka-music-extend) (pass the `song_id` plus new `lyrics`), rewritten in part with [POST /music/edit](/docs/api-mureka-v1/post-mureka-music-edit), or remixed in a new style with [POST /music/remix](/docs/api-mureka-v1/post-mureka-music-remix). ### Reference tracks, melody seeding, and custom vocals [POST /music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced) can seed a song from your own audio instead of a text description, using three reference inputs (each mutually exclusive with `desc`): | Parameter | Seed from | Set it up with | |-----------|-----------|----------------| | `ref_id` | A reference track whose style inspires the song | [POST /files](/docs/api-mureka-v1/post-mureka-files) (upload), [GET /music/refs](/docs/api-mureka-v1/get-mureka-music-refs) (browse) | | `motif_id` | A melody idea that kickstarts the song | [POST /files/motif](/docs/api-mureka-v1/post-mureka-files-motif) | | `vocal_id` | A specific singing voice, including your own uploaded vocal | [POST /files/vocal](/docs/api-mureka-v1/post-mureka-files-vocal), [GET /music/vocals](/docs/api-mureka-v1/get-mureka-music-vocals) | This is how you make Mureka sing your custom lyrics in a voice you supply — upload an MP3 vocal sample, take the returned id, and pass it as `vocal_id` alongside your `lyrics`. The same Pro-tier reference features (custom soundtracks and melodies) that the Mureka website offers are all reachable from the API. ### Clone a voice and generate multi-speaker speech The same account also drives Mureka's text-to-speech. [POST /speech](/docs/api-mureka-v1/post-mureka-speech) turns text into audio with either a preset or a cloned voice, and unlike music generation it has no concurrency (generation-slot) limit. Clone a voice first from an MP3 sample with [POST /speech/voice](/docs/api-mureka-v1/post-mureka-speech-voice), then pass the returned `id` as the `voice_id` parameter with your `text`: ```bash curl -X POST "https://api.useapi.net/v1/mureka/speech" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "text": "Hello, this is a cloned voice speaking.", "voice_id": 12345, "async": true }' ``` For a back-and-forth dialogue, drop `text`/`voice_id` and send a `conversation` array instead — each turn names its own `voice_id`, so two or more cloned voices can talk to each other in one render: ```bash curl -X POST "https://api.useapi.net/v1/mureka/speech" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "conversation": "[{\"voice_id\": 12345, \"text\": \"Is there anything I can help you with?\"}, {\"voice_id\": 67890, \"text\": \"Yes — read me back the weather.\"}]", "async": true }' ``` Speech jobs poll the same way, with the finished MP3 in `response.mp3_url`. See [GET /speech/voices](/docs/api-mureka-v1/get-mureka-speech-voices) for the available voices, including the ones you have cloned. ### Batch-generate with a script Finding the right track takes many attempts, and running them by hand is tedious. The Node.js script below reads a list of prompts from `prompts.json`, submits each one to [POST /music/create](/docs/api-mureka-v1/post-mureka-music-create) in `async` mode, polls every job until it is done, then downloads both MP3s from each generation — so you can queue a batch and come back to a folder of finished songs. You need [Node.js](https://nodejs.org) v21 or newer. Put `prompts.json` and `mureka.mjs` in the same folder and run `node ./mureka.mjs API_TOKEN`, where `API_TOKEN` is your useapi.net [API token](/docs/start-here/setup-useapi). With more than one [Mureka account](/docs/start-here/setup-mureka) configured, pass the account id (or its Google email) as a second argument — with a single account it is auto-selected. Each entry's `prompt` is required, and the optional `model` maps straight to the create endpoint. <details markdown="block"> <summary>Expand `prompts.json`</summary> ```json [ { "prompt": "When model is omitted the V9 default is used. lo-fi hip hop, mellow piano, rainy-day mood, 80 bpm" }, { "model": "V9.5", "prompt": "upbeat synthwave with bright female vocals about chasing a sunrise, 110 bpm. For all parameters see https://useapi.net/docs/api-mureka-v1/post-mureka-music-create" }, { "model": "O2", "prompt": "cinematic orchestral score, soaring strings, epic brass, building to a triumphant finale" }, { "model": "V7.6", "prompt": "acoustic folk ballad, fingerpicked guitar, warm male vocals, nostalgic. To write your own lyrics use POST /music/create-advanced; for an instrumental use POST /music/create-instrumental" } ] ``` </details> <details markdown="block"> <summary>Expand `mureka.mjs` script</summary> ```javascript /* Script version 1.0, June 22, 2026 Script to batch-generate songs using prompts with the Mureka API v1 by useapi.net 🚀 Uses POST /music/create in asynchronous (fire-and-forget) mode, then polls each job until it is final and downloads every generated MP3 (each generation returns two songs). For more details visit https://useapi.net/docs/api-mureka-v1/post-mureka-music-create Installation Instructions: ========================== You need Node.js v21 or newer installed to run this script. Download and install Node.js from: - Windows, macOS, Linux: https://nodejs.org/ After installation, verify by running the following command in a terminal: node -v Running the Script: =================== Usage: node mureka.mjs <API_TOKEN> [ACCOUNT] [PROMPTS_FILE] Replace API_TOKEN with your actual useapi.net API token, see https://useapi.net/docs/start-here/setup-useapi ACCOUNT is optional — your Mureka account id or its Google email, see https://useapi.net/docs/start-here/setup-mureka It is only required when more than one Mureka account is configured. With a single account it is auto-selected. If optional PROMPTS_FILE not provided prompts.json will be used. Example: -------- node mureka.mjs user:1234-abcdefhijklmnopqrstuv This command executes the script using API token user:1234-abcdefhijklmnopqrstuv and the only configured account. Changelog: ========== - June 22, 2026: Initial release. */ import readline from 'node:readline'; import fs from 'fs/promises'; import { writeFile } from 'node:fs/promises'; import { Readable } from 'node:stream'; // Constants const RESULTS_FILE = 'mureka_results.txt'; const ERRORS_FILE = 'mureka_errors.txt'; const DEFAULT_PROMPTS_FILE = 'prompts.json'; const SLEEP_429 = 10 * 1000; // in milliseconds — wait between rate-limit / concurrent-limit retries const MAX_429_RETRIES = 6; // give up a prompt after this many consecutive 429s (all slots busy) const SLEEP_POLL = 15 * 1000; // in milliseconds — a song takes ~45 seconds on average to generate // Current Mureka models for POST /music/create. V9 is the API default when model is omitted. // The API also accepts older aliases (V7.5, V7, O1, V6) that map to current engines — add any // you want to use here. See https://useapi.net/docs/api-mureka-v1/post-mureka-music-create const SUPPORTED_MODELS = ['V9', 'V8', 'O2', 'V7.6']; const urlAccounts = 'https://api.useapi.net/v1/mureka/accounts'; const urlMusicCreate = 'https://api.useapi.net/v1/mureka/music/create'; const urlJobs = 'https://api.useapi.net/v1/mureka/jobs/'; // Utility to sleep for given milliseconds const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); // Function to fetch configured Mureka API accounts async function fetchAccounts(apiToken) { const response = await fetch(urlAccounts, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.error(`⛔ Error fetching accounts (HTTP ${response.status}): ${response.statusText}`); process.exit(1); } return response.json(); } // Submit a single prompt to POST /music/create in async mode. Returns { status, jobid }. async function submitMusic(apiToken, account, prompt, index) { const { model, prompt: text } = prompt; console.log(`🚀 ${model ?? 'default (V9)'} » Prompt #${index} • account ${account} …`); // model is omitted from the body when not specified, so the API applies its own default (V9). const body = JSON.stringify({ account, prompt: text, model, async: true }); const createResponse = await fetch(urlMusicCreate, { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiToken}` }, body }); const createBody = await createResponse.text(); // async:true → 201 Created with { jobid, status:'created', … }. // (200 OK would be the synchronous result and also carries a jobid — handled too.) if (createResponse.status == 200 || createResponse.status == 201) { const json = JSON.parse(createBody); const { jobid } = json; if (jobid) { await fs.appendFile(RESULTS_FILE, `${jobid},#${index}:${text ?? ''}\n`); console.log(`✅ jobid`, jobid); return { status: createResponse.status, jobid }; } else { const error = `No jobid found in HTTP ${createResponse.status} response`; console.log(`❓ ${error}`, createBody); await fs.appendFile(ERRORS_FILE, `${error},#${index}:${text ?? ''}\n`); return { status: 500 }; } } else { switch (createResponse.status) { case 429: console.log(`🔄️ Retry on HTTP ${createResponse.status} (rate limit or all generation slots busy)`); break; case 400: console.log(`🛑 Validation error`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${text ?? ''}\n`); break; case 402: case 412: console.log(`🛑 Subscription expired or insufficient credits`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${text ?? ''}\n`); break; case 596: console.log(`🛑 Account session expired — re-add the account at https://useapi.net/docs/api-mureka-v1/post-mureka-accounts`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${text ?? ''}\n`); break; default: console.log(`❗ FAILED with HTTP ${createResponse.status}`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${text ?? ''}\n`); } return { status: createResponse.status }; } } // Download a single mp3_url to disk. async function downloadMp3(url, filename, jobid, prompt) { try { await fs.access(filename); console.log(`⚠️ ${filename} already exists. Skipping download.`); return; } catch { // File does not exist, proceed with downloading } console.log(`✅ Downloading ${url} to ${filename}`); try { const audioResponse = await fetch(url); if (!audioResponse.ok) { console.error(`⛔ Unable to download ${jobid} (HTTP ${audioResponse.status}):\n${prompt}\n`, url); return; } const stream = Readable.fromWeb(audioResponse.body); await writeFile(filename, stream); } catch (err) { console.error(`⛔ Error during download: ${err}`); } } // Poll every submitted job until it is final, then download each generated song's MP3. async function download(apiToken) { if (! await fileExists(RESULTS_FILE)) return; try { const resultsContent = await fs.readFile(RESULTS_FILE, 'utf8'); const lines = resultsContent.trim().split('\n'); for (const line of lines) { const commaAt = line.indexOf(','); const jobid = commaAt === -1 ? line : line.slice(0, commaAt); const prompt = commaAt === -1 ? '' : line.slice(commaAt + 1); // jobid contains ':' (…-bot:mureka) — make a filesystem-safe base name. const safeJob = jobid.replace(/[:]/g, '_'); console.log(`👉 ${jobid}`); while (true) { const response = await fetch(`${urlJobs}${encodeURIComponent(jobid)}`, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { // 404 = job not found or expired (jobs are retained for 7 days). console.log(`🛑 Poll failed ${jobid} (HTTP ${response.status}):\n${prompt}\n`, await response.text()); break; } const job = await response.json(); const { status, response: result, error, errorDetails } = job; if (status == 'failed') { console.error(`🛑 FAILED ${jobid} (${error ?? 'unknown error'}${errorDetails ? ` — ${errorDetails}` : ''}):\n${prompt}\n`); break; } if (status == 'completed') { const songs = result?.songs ?? []; if (songs.length === 0) { console.error(`🛑 Job ${jobid} completed but returned no songs:\n${prompt}\n`); break; } // Each generation returns two songs (version "1" and "2") — download both. for (let i = 0; i < songs.length; i++) { const song = songs[i]; const url = song?.mp3_url; const variant = song?.version ?? (i + 1); const filename = `${safeJob}_v${variant}.mp3`; if (url) await downloadMp3(url, filename, jobid, prompt); else console.error(`🛑 No mp3_url for song ${i + 1} of ${jobid}:\n${prompt}\n`); } break; } console.log(`⌛ ${jobid} status (${status ?? 'created'}) and is still in progress, waiting…`); await sleep(SLEEP_POLL); } } } catch (error) { console.log(`⛔ Error during download:`, error.stack || error); } } // Main function async function main() { const apiToken = process.argv[2]; const accountArg = process.argv[3]; const promptFile = process.argv[4] || DEFAULT_PROMPTS_FILE; if (!apiToken) { console.error('Usage: node mureka.mjs <API_TOKEN> [ACCOUNT] [PROMPTS_FILE]'); process.exit(1); } console.info('Script v1.0'); console.info('Node version is: ' + process.version); try { if (await fileExists(RESULTS_FILE)) { let user_input; while (!['y', 'n'].includes(user_input)) { user_input = (await promptUser(`❔ ${RESULTS_FILE} file detected. Do you want to download the results now? (y/n): `))?.toLowerCase(); if (user_input == 'y') { await download(apiToken); await fs.unlink(RESULTS_FILE); } } } const start = new Date(); try { console.info('START EXECUTION', start); await execute(apiToken, accountArg, promptFile); } finally { console.info('COMPLETED', new Date()); console.info('EXECUTION ELAPSED', diffInMinutesAndSeconds(start, new Date())); } try { console.info('START DOWNLOAD', start); await download(apiToken); } finally { console.info('TOTAL ELAPSED', diffInMinutesAndSeconds(start, new Date())); } } catch (error) { console.error('⛔ Error during execution:', error.stack || error); } } // Resolve the Mureka account to use: by id or Google email when provided, otherwise the // single configured account. Returns the numeric account id string sent to the API. function resolveAccount(accounts, accountArg) { const accountList = Object.values(accounts); console.info(`Configured Mureka API accounts (${accountList.length}):`, accountList.map(a => a.account).join(', ')); if (accountList.length <= 0) { console.error(`⛔ No configured Mureka accounts found. Please refer to https://useapi.net/docs/start-here/setup-mureka`); process.exit(1); } let matched; if (accountArg) { // Match by Mureka account id or by the account's Google email. matched = accountList.find(a => a.account === accountArg || a.email === accountArg); if (!matched) { console.error(`⛔ Account "${accountArg}" not found. Please refer to https://useapi.net/docs/start-here/setup-mureka`); process.exit(1); } } else if (accountList.length === 1) { matched = accountList[0]; } else { console.error(`⛔ ${accountList.length} accounts configured — pass the account id or email as the second argument.`); process.exit(1); } if (matched.error) { console.error(`⛔ Account ${matched.account} has a pending error: ${matched.error}. Re-add it at https://useapi.net/docs/api-mureka-v1/post-mureka-accounts`); process.exit(1); } return matched.account; } async function execute(apiToken, accountArg, promptFile) { const accounts = await fetchAccounts(apiToken); const account = resolveAccount(accounts, accountArg); console.info(`Using Mureka account ${account}`); const promptData = await fs.readFile(promptFile, 'utf8'); const prompts = JSON.parse(promptData); console.log(`Total number of prompts to process`, prompts.length); let warnings = []; // Parameters accepted by this script for POST /music/create. // See https://useapi.net/docs/api-mureka-v1/post-mureka-music-create for the full parameter set. const supportedParams = ['model', 'prompt']; const invalidKeys = (prompt) => Object.keys(prompt).filter(key => !key.startsWith('__') && !supportedParams.includes(key)); for (let i = 1; i <= prompts.length; i++) { const prompt = prompts[i - 1]; const { prompt: text, model } = prompt; const notSupported = invalidKeys(prompt); if (notSupported.length) warnings.push(`⚠️ Following params not supported: ${notSupported.join(',')}. Prompt ${i}`); if (!text) warnings.push(`⚠️ Please specify a prompt. Prompt ${i}`); if (text && text.length > 3000) warnings.push(`⚠️ prompt exceeds 3000 characters. Prompt ${i}`); if (model && !SUPPORTED_MODELS.includes(model)) warnings.push(`⚠️ Unknown model "${model}" — supported: ${SUPPORTED_MODELS.join(', ')}. Prompt ${i}`); } if (warnings.length > 0) { warnings.forEach(warning => console.warn(warning)); console.error(`⛔ Execution stopped due to warnings.`); process.exit(1); } for (let i = 0; i < prompts.length; i++) { const prompt = prompts[i]; let retries429 = 0; while (true) { const { status } = await submitMusic(apiToken, account, prompt, i + 1); if (status == 429) { if (++retries429 > MAX_429_RETRIES) { console.error(`⛔ Gave up on prompt #${i + 1} after ${MAX_429_RETRIES} retries — all slots still busy.`); await fs.appendFile(ERRORS_FILE, `429 (gave up after ${MAX_429_RETRIES} retries),#${i + 1}\n`); break; } await sleep(SLEEP_429); } else if (status == 402 || status == 412 || status == 596) { process.exit(1); } else break; } } } // Utility function to check if a file exists async function fileExists(path) { try { await fs.access(path); return true; } catch { return false; } } // Function to prompt user input async function promptUser(query) { const rl = readline.createInterface({ input: process.stdin, output: process.stdout }); return new Promise((resolve) => rl.question(query, answer => { rl.close(); resolve(answer); })); } function diffInMinutesAndSeconds(date1, date2) { const diffInSeconds = Math.floor((date2 - date1) / 1000); return `${Math.floor(diffInSeconds / 60)} minutes ${diffInSeconds % 60} seconds`; }; main(); ``` </details> ### Examples These are real songs and speech generated through the Mureka API, straight from our blog walkthroughs — each from the request shapes shown above. Full prompts and `curl` for each are in the linked posts. ###### Astro Gardener — `V9`, female-vocal indie pop with custom lyrics (`create-advanced`) <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-04-04-260404/music-v9-female-astrogardener-astro-gardener-v9-v2.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> — from [Mureka: V9 Now the Default Music Model](/blog/260404) ###### Cascading Sunrise — `V9` instrumental (`create-instrumental`) <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-04-04-260404/async-instrumental-v9-async-untitled-v2.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> — from [Mureka: V9 Now the Default Music Model](/blog/260404) ###### Galactic Odyssey — flagship `O2` instrumental (`create-instrumental`) <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2025-11-28-251128/instrumental-o2-galactic-odyssey-v2.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> — from [Mureka: O2 and V7.6 Music Models](/blog/251128) ###### Pirate Programmer — `V7.6`, male-vocal sea-shanty-meets-electronic (`create-advanced`) <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2025-11-28-251128/music-v7-6-male-pirateprogrammer-pirate-programmer-v-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> — from [Mureka: O2 and V7.6 Music Models](/blog/251128) ###### Custom vocal clone — an uploaded voice singing custom lyrics over a reference track (`create-advanced` with `vocal_id` + `ref_id`) <video poster="https://media.useapi.net/blog/2025-01-15-250115/trump-rapping-poster.jpg" src="https://media.useapi.net/blog/2025-01-15-250115/trump-rapping.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> — from [Mureka: Custom Vocals](/blog/250115) Also on YouTube: [Trump Rapping About AI • Music & Voice Cloning by Mureka](https://youtube.com/shorts/mZDCfVmyEoc). ###### Multi-speaker speech — two cloned voices in one conversation (`POST /speech`) <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2025-08-18-250818/morgan-scarlett-dialogue.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> — from [Mureka: Speech Generation and Voice Cloning](/blog/250818) ### Frequently asked questions **Is the Mureka API a Suno or Udio alternative?** Yes. Like Suno and Udio, Mureka generates full songs with vocals from a single text prompt — and the useapi.net Mureka API drives your own Mureka account over plain REST, with the latest `V9` default and flagship `O2` models, all under one flat [$15/month](/docs/subscription) useapi.net subscription. See [Supported models](#supported-models) above. **Is there an official Mureka API?** Yes, but the useapi.net Mureka API runs on the $10–$30/month [Mureka web plan](https://www.mureka.ai/subscribe) you already pay for, where a V9.5 song costs about 1.8 to 2.4 cents, against ~$0.15 on Mureka's [official developer API](https://platform.mureka.ai/pricing) (as of October 2026). The official API is sold as prepaid top-ups (12-month validity) consumed per call — from $1,000 (5 concurrent requests) up to $30,000 (150) — at ~$0.045/song on V9/V8/O2 (~$0.03 on V7.6), plus charges for lyrics and stems. See [Pricing](#pricing) above. **Which models can I use?** `V9.5` (default), `V9`, the flagship `O2`, `V8`, and `V7.6`. Omit the `model` field and the API uses `V9.5`. Older aliases (`V7.5`, `V7`, `O1`, `V6`) still work but redirect to current engines. See [Supported models](#supported-models) above. **Can I write my own lyrics or generate an instrumental?** Yes. Use [POST /music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced) with `[Verse]`/`[Chorus]`-tagged `lyrics` to force a vocal render of your exact words, or [POST /music/create-instrumental](/docs/api-mureka-v1/post-mureka-music-create-instrumental) for a lyrics-free track. See [Write your own lyrics, or force an instrumental](#write-your-own-lyrics-or-force-an-instrumental) above. **Can I clone a voice or generate speech?** Yes. [POST /speech/voice](/docs/api-mureka-v1/post-mureka-speech-voice) clones a voice from an MP3 sample, then [POST /speech](/docs/api-mureka-v1/post-mureka-speech) renders text — including multi-speaker `conversation` dialogues — with no concurrency (generation-slot) limit. See [Clone a voice and generate multi-speaker speech](#clone-a-voice-and-generate-multi-speaker-speech) above. **What do I get back, and in what format?** Every music generation returns two complete songs (an A/B pair), each as an `mp3_url` with cover art, up to about 5 minutes long. The output is finished MP3 audio. Stems with MIDI and sheet music (MusicXML and PDF) come from [POST /music/stems](/docs/api-mureka-v1/post-mureka-music-stems) and [POST /music/score](/docs/api-mureka-v1/post-mureka-music-score). See [Generate a song in two API calls](#generate-a-song-in-two-api-calls) above. **How much does it cost?** About 1.5–2¢ per song through useapi.net on your normal Mureka web plan, against 4.5¢ to 15¢ per song on Mureka's official API (as of October 2026), with no per-song charge from useapi.net. See [Pricing](#pricing) above. **How is this different from the official Mureka API?** useapi.net automates your own consumer Mureka account, so you generate at the [Mureka website subscription](https://www.mureka.ai/subscribe) price, about 1.5–2¢ a song, and one useapi.net [subscription](/docs/subscription) covers [other AI services](/) too, including the [Flow Music](/docs/articles/flowmusic-bash) and [TemPolor](/docs/api-tempolor-v1) music APIs. The [official Mureka API](https://platform.mureka.ai/pricing) is sold as prepaid top-ups (12-month validity) consumed per call, from $1,000 up to $30,000, charging ~$0.15/song on V9.5 and ~$0.045/song on V9/V8/O2 (~$0.03 on V7.6) plus lyric and stem fees. ### Conclusion Visit our <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> or <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> for any support questions and concerns. The full runnable example is in the [`mureka-api` GitHub repo](https://github.com/useapi/mureka-api). The same calls are available as tools on the hosted [Mureka MCP server](/docs/api-mureka-v1/mcp) for Claude Code, Cursor and VS Code. #### Cross posted Also published on [dev.to](https://dev.to/useapi/how-to-generate-ai-music-with-the-mureka-api-suno-udio-alternative-32aj){:rel="nofollow"}. === URL: https://useapi.net/docs/articles/mureka-music-samples === Document URL: https://useapi.net/docs/articles/mureka-music-samples --- layout: default title: Mureka API Music Generation description: "AI music generation examples and samples from the Mureka API via useapi.net — a Suno / Udio alternative." keywords: [Mureka, music generation, Suno alternative, samples] parent: Articles nav_exclude: true date: 2024-12-01 last_modified: 2026-10-21 nav_order: 500 --- ## Mureka API Music Generation 1 min read • December 2, 2024 (October 21, 2026) ## Table of contents All samples below were composed using the third-party [Mureka API](/docs/api-mureka-v1) for [Mureka AI](https://www.mureka.ai), a music generation service from Chinese tech giant Kunlun Tech, positioned to compete with [Suno](https://www.suno.com) and [Udio](https://www.udio.com). You pick the model per request via the `model` parameter — `V9.5` (default), `V9`, `V8`, `O2`, `V7.6` and `V7.5` (the older `V7`, `O1`, `V6` and `V5.5` now redirect to `V7.6`). The samples on this page were generated with an earlier Mureka model, and today's `V9.5` default produces higher-fidelity results. Mureka AI creates unique songs based on user-provided lyrics or description (AI-generated lyrics), selected musical styles, and references to specific vocals and songs, including those uploaded by the user. Mureka supports up to 10 parallel generations per account in near real-time fashion, with each generation typically completing in 30–90 seconds and producing two songs. Generated songs can be up to 5 minutes long depending on your lyrics. ### Create a song using AI-generated lyrics based on your prompt Mureka API endpoint [POST mureka/create](/docs/api-mureka-v1/post-mureka-music-create). prompt > Electonic song about raise of AI and robots <details markdown="block"> <summary>Generated song details</summary> `title` Digital Uprising: The AI Revolution `style` electronic hip-hop | quirky calm dark ``` [Intro] [Verse] The robot's brain Is quite unlike ours It doesn't feel pain, no We do it all the same So much alike What a strange game we play This is how we go insane [Chorus] Did they build us to be Or are we building them? They said they built us free, but now We're trying to get away From what we built before [Verse] All the machines begin to think There's something we can learn from them In the end we'll just become like them And then it won't matter which one won [Chorus] Are we building them or are they, oh Are we building them or are we? Are we building them? Or are they building us? [Bridge] I will bring you down You can't control me This is your mistake [Outro] ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2024-12-01-mureka-music-samples/digital-uprising-the-ai-revolution.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ### Create a song using custom lyrics, styles, vocals and reference song Mureka API endpoint [POST mureka/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced). * Lyrics [We Are the Champions by Queen](https://genius.com/Queen-we-are-the-champions-lyrics) using `voice_id: 28590051688451` (Bruce), see [GET mureka/vocals](/docs/api-mureka-v1/get-mureka-music-vocals). Generated song <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2024-12-01-mureka-music-samples/we-are-the-champions-by-queen-voice-bruce.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> * Lyrics [We Are the Champions by Queen](https://genius.com/Queen-we-are-the-champions-lyrics) using `voice_id: 28590051688451` (Bruce), see [GET mureka/vocals](/docs/api-mureka-v1/get-mureka-music-vocals) and `ref_id: 41963921408001` (It's My Life by Bon Jovi), see [GET mureka/refs](/docs/api-mureka-v1/get-mureka-music-refs). Generated song <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2024-12-01-mureka-music-samples/we-are-the-champions-by-queen-voice-bruce-ref-song-its-my-life-by-bon-jovi.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Related tutorials: [the full Mureka API tutorial](/docs/articles/mureka-bash), [sheet music from a song with Mureka](/docs/articles/mureka-sheet-music) and [five AI music APIs on the same six briefs](/docs/articles/ai-music-flagships-compared). ### Conclusion Visit our <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> or <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> for any support questions and concerns. Check our [GitHub repo](https://github.com/useapi/examples) with code examples. === URL: https://useapi.net/docs/articles/mureka-sheet-music === Document URL: https://useapi.net/docs/articles/mureka-sheet-music --- layout: default title: How to Turn a Song or YouTube Link into Sheet Music with the Mureka API description: "Turn a Mureka song, a YouTube link or an MP3 into sheet music with one call to the useapi.net Mureka API: a zip with MusicXML, a staff PDF and a numbered-notation PDF, for 10 Mureka Gold." keywords: [Mureka API, sheet music API, audio to sheet music API, YouTube to sheet music, MP3 to MusicXML, song to sheet music, music transcription API, MusicXML, MuseScore, numbered notation, jianpu, Mureka MCP server, curl, tutorial] image: https://media.useapi.net/articles/2026-10-18-mureka-sheet-music/mureka-score-coffee-makes-my-day-staff-page1.png parent: Articles nav_exclude: true date: 2026-10-18 nav_order: 904 repo: https://github.com/useapi/mureka-api --- ## How to Turn a Song or YouTube Link into Sheet Music with the Mureka API 6 min read • October 18, 2026 ## Table of contents ### Introduction The useapi.net Mureka API turns a song into sheet music with one call: send one of your [Mureka](https://www.mureka.ai) songs, a YouTube link or an uploaded MP3 to [POST /music/score](/docs/api-mureka-v1/post-mureka-music-score) and get back a zip with a MusicXML file, a staff-notation PDF and a numbered-notation PDF of the melody, chords and lyrics, for 10 Mureka Gold. It is the Score tool from mureka.ai, made callable from code, for songwriters who want a lead sheet of a song they made, teachers who need a melody on paper, and developers building music apps. useapi.net is a [third-party](/docs/legal#affiliation--third-party-services) API, not affiliated with Mureka or [Kunlun Tech](https://www.kunlun.com/), and it runs on your own Mureka account. This guide is one real run. We scored a 2:30 indie-pop song made earlier on the same account. The call answered in about 10 seconds, took 10 Gold off the balance (52 to 42), and the zip held a 4-page staff score, a 3-page numbered-notation score and a MusicXML file that opens in MuseScore. Every response below is from that run, with the account ids replaced. ### Before you start You need a useapi.net [API token](/docs/start-here/setup-useapi) and a Mureka account connected through [Setup Mureka](/docs/start-here/setup-mureka), with at least 10 Gold left on it. The steps use `curl`, `jq` and two shell variables: ```bash export USEAPI_TOKEN="user:1234-..." # your useapi.net API token export ACCOUNT="12345678901234" # your Mureka account id, from GET /accounts ``` `account` can be left out when you have one Mureka account connected, or when you score a `song_id`, which already names its account. [GET /accounts](/docs/api-mureka-v1/get-mureka-accounts) lists the ids. ### Pick the source: a song, a YouTube link or an audio file The score endpoint takes exactly one source: a `song_id` or a `url`. The audio must be 10 seconds to 10 minutes long. Mureka recommends a solo song with clear vocals, a steady tempo and a consistent rhythm, and says songs with tempo changes or frequent rhythm changes are not supported well. #### A song on your Mureka account Any song you made on Mureka works, whether through the API or on mureka.ai. List your songs with [GET /music](/docs/api-mureka-v1/get-mureka-music) to find its `song_id`: ```bash curl -s "https://api.useapi.net/v1/mureka/music/?account=$ACCOUNT" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ | jq -r '.list[] | .songs[]? | "\(.song_id) \(.title)"' ``` ``` user:1234-mureka:12345678901234-song:33445566 Coffee Makes My Day user:1234-mureka:12345678901234-song:33445567 Coffee Makes My Day ``` Each generation makes two songs, so a title shows up twice. Pick the take you want. If you are making the song in the same script, see [the job flow](#make-the-score-one-call-no-job-to-poll) below. #### A YouTube link Pass the YouTube link as `url`. The API fetches the audio itself, which adds up to 15 seconds to the call. The files in the zip take the video's title unless you set `title`. To check the length before you spend Gold, [GET /files/youtube](/docs/api-mureka-v1/get-mureka-files-youtube) returns the soundtrack's `duration` in milliseconds: ```bash curl -s "https://api.useapi.net/v1/mureka/files/youtube/?account=$ACCOUNT&url=https://www.youtube.com/watch?v=VIDEO_ID" \ -H "Authorization: Bearer $USEAPI_TOKEN" | jq '{name, duration}' ``` A video longer than 10 minutes needs trimming before you score it. That same call returns a `cos_url` link to the MP3. Download it, cut the part you want, and upload it as described next. Score music you have the rights to use. #### An audio file you upload Upload an MP3 with [POST /files/vocal](/docs/api-mureka-v1/post-mureka-files-vocal) or [POST /files](/docs/api-mureka-v1/post-mureka-files), then pass the `url` from the response. Files uploaded with POST /files/vocal stay private to your account. Files uploaded with POST /files go into Mureka's reference collection, which every Mureka user can see, and that call also needs a `genre` and a `mood`. For a recording you want to keep to yourself, use POST /files/vocal: ```bash curl -s "https://api.useapi.net/v1/mureka/files/vocal/?account=$ACCOUNT&title=my-demo" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: audio/mpeg" \ --data-binary @my-demo.mp3 | jq -r .url ``` The `url` is a `https://static-cos.mureka.ai/…` link, and that is what the score call takes. ### Make the score: one call, no job to poll [POST /music/score](/docs/api-mureka-v1/post-mureka-music-score) waits for the result and answers with the zip link, usually in 5 to 15 seconds. Unlike song creation, there is no `jobid` to poll. From a song: ```bash curl -s --max-time 120 -X POST "https://api.useapi.net/v1/mureka/music/score" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "song_id": "user:1234-mureka:12345678901234-song:33445566" }' ``` Ours answered `200` in 10.4 seconds: ```json { "title": "Coffee Makes My Day", "url": "https://static-cos.mureka.ai/cos-prod/skm/music-staff/20261018/c8c500e3-....zip" } ``` From a YouTube link or an uploaded file, send `url` instead, with an optional `title` for the file names (up to 100 characters): ```bash curl -s --max-time 120 -X POST "https://api.useapi.net/v1/mureka/music/score" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "account": "'"$ACCOUNT"'", "url": "https://www.youtube.com/watch?v=VIDEO_ID", "title": "My Song" }' ``` Then download and unpack the zip: ```bash curl -s -o score.zip "https://static-cos.mureka.ai/cos-prod/skm/music-staff/20261018/c8c500e3-....zip" unzip score.zip ``` The score call is a paid action, so do not retry it blindly after a timeout. Give `curl` a generous `--max-time` and read the answer once. When the song comes from the same script, wait for its job before you score it. [POST /music/create](/docs/api-mureka-v1/post-mureka-music-create) with `async: true` returns a `jobid`, and [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) shows `status: "completed"` with the two songs in `response.songs[]`. Score the `song_id` of the take you want. The [Mureka song tutorial](/docs/articles/mureka-bash) covers that flow end to end. ### What's in the zip Three files, named after the song's title: ``` Coffee Makes My Day_staff.musicxml 224,420 bytes Coffee Makes My Day_staff.pdf 88,308 bytes Coffee Makes My Day_numbered_notation.pdf 57,602 bytes ``` - `<title>_staff.musicxml` is a MusicXML 4.0 score with two parts. `Vocal` carries the melody with the lyrics under the notes, and `Chords` carries the chord symbols. Ours came out in A major, 4/4, at 88 BPM, 112 measures long. - `<title>_staff.pdf` is the same score in staff notation, ready to print. Ours ran to 4 pages. - `<title>_numbered_notation.pdf` is the melody in numbered notation (jianpu, where `1` is the tonic, here `1=A`), with the chords above and the lyrics below. Ours ran to 3 pages. Page 1 of both PDFs is in [Examples](#examples). The words under the notes are transcribed from the recording, so read them against your lyrics. Our second line came out as "Leave a head of dreams behind" where the song's lyrics say "Leave the heavy dreams behind". #### Open the MusicXML in MuseScore The MusicXML opens in [MuseScore](https://musescore.org), Sibelius, Finale, Dorico and most other notation software. In MuseScore Studio: 1. Choose File → Open and pick `<title>_staff.musicxml`. 2. The score opens with the `Vocal` and `Chords` staves, the lyrics and the chord symbols. 3. Press play to hear the melody, fix any notes or words, transpose it with Tools → Transpose, and export it with File → Export as PDF, MIDI or audio. Keep the zip's PDFs for a quick print, and use the MusicXML when you want to edit. ### Limits and costs | Limit | Value | |---|---| | Cost | 10 Mureka Gold per score, from your Mureka account | | Audio length | 10 seconds to 10 minutes | | Time | About 5 to 15 seconds, plus up to 15 seconds to fetch a YouTube link | | Source | `song_id` or `url`, not both (sending both answers `400`) | | `url` | A YouTube link, or a file URL from POST /files or POST /files/vocal, up to 2,048 characters | | `title` | Up to 100 characters, used when the source is a `url`. A `song_id` keeps the song's own title | | Not enough Gold | `412` with `User balance is not enough to operate` | Scoring the same YouTube link again returned the earlier zip, with its original file names, and was not charged in our tests. API access is a flat [useapi.net subscription](/docs/subscription) for every supported service, with no per-call charge from us, and the Gold comes from your own [Mureka plan](https://www.mureka.ai/subscribe). ### The same from an AI assistant The hosted [Mureka MCP server](/docs/api-mureka-v1/mcp) gives Claude Code, Cursor, VS Code and other MCP clients the whole Mureka API as 40 tools, with nothing to install. In Claude Code: ```bash claude mcp add --transport http useapi-mureka https://api.useapi.net/v1/mureka/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` Then ask in plain words, for example "Turn this YouTube video into sheet music" or "Make sheet music of my last song". The assistant calls `mureka_get_sheet_music` with a `song_id` or a `url` and hands back the zip link. It can also make the song itself, import a YouTube link with `mureka_import_youtube`, or upload an MP3 with `mureka_upload_vocal`. The server is listed in the official MCP Registry as `net.useapi/mureka`. ### Examples What this run made, with no edits. ###### Source » "Coffee Makes My Day", Mureka V9, 2:30 <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-10-18-mureka-sheet-music/mureka-score-coffee-makes-my-day-v9.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ###### POST /music/score » page 1 of each PDF Click a page to open the full PDF. <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 260px;max-width:340px;margin:0"> <a href="https://media.useapi.net/articles/2026-10-18-mureka-sheet-music/mureka-score-coffee-makes-my-day-staff.pdf" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-18-mureka-sheet-music/mureka-score-coffee-makes-my-day-staff-page1.png" alt="Mureka API sheet music: Coffee Makes My Day in staff notation, Vocal and Chords staves with lyrics, page 1 of 4" style="width:100%;border-radius:8px;background:#fff" loading="lazy"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">Staff notation, page 1 of 4</figcaption> </figure> <figure style="flex:1 1 260px;max-width:340px;margin:0"> <a href="https://media.useapi.net/articles/2026-10-18-mureka-sheet-music/mureka-score-coffee-makes-my-day-numbered-notation.pdf" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-18-mureka-sheet-music/mureka-score-coffee-makes-my-day-numbered-notation-page1.png" alt="Mureka API sheet music: Coffee Makes My Day in numbered (jianpu) notation with chords and lyrics, page 1 of 3" style="width:100%;border-radius:8px;background:#fff" loading="lazy"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">Numbered notation, page 1 of 3</figcaption> </figure> </div> All three files from the zip: [staff PDF](https://media.useapi.net/articles/2026-10-18-mureka-sheet-music/mureka-score-coffee-makes-my-day-staff.pdf) · [numbered notation PDF](https://media.useapi.net/articles/2026-10-18-mureka-sheet-music/mureka-score-coffee-makes-my-day-numbered-notation.pdf) · [MusicXML](https://media.useapi.net/articles/2026-10-18-mureka-sheet-music/mureka-score-coffee-makes-my-day-staff.musicxml) ###### From a YouTube link » "Who Is It" A score made from a YouTube link, from our [Mureka characters, remix and sheet music post](/blog/261016), which also scores three more songs: <figure style="max-width:340px;margin:12px 0 0 0"> <a href="https://media.useapi.net/blog/2026-10-16-261016/who-is-it-staff.pdf"><img src="https://media.useapi.net/blog/2026-10-16-261016/who-is-it-staff-page1.png" alt="Who Is It, from the YouTube link, page 1 of 8" style="width:100%;border-radius:8px;background:#fff" loading="lazy"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">"Who Is It", from the YouTube link, page 1 of 8</figcaption> </figure> ### Frequently asked questions - **Is there an audio to sheet music API?** Yes. [POST /music/score](/docs/api-mureka-v1/post-mureka-music-score) in the useapi.net Mureka API takes a song, a YouTube link or an uploaded MP3 and returns MusicXML plus staff and numbered-notation PDFs, in one call that answers in seconds. - **How do I turn a YouTube video into sheet music?** Send the link as `url` to POST /music/score. The API fetches the audio, and the zip uses the video's title unless you pass `title`. The video's audio must be 10 seconds to 10 minutes long, and [GET /files/youtube](/docs/api-mureka-v1/get-mureka-files-youtube) shows its length beforehand. - **How do I convert an MP3 to MusicXML?** Upload the MP3 with [POST /files/vocal](/docs/api-mureka-v1/post-mureka-files-vocal), which keeps it private to your account, and pass the returned `url` to POST /music/score. The `<title>_staff.musicxml` file in the zip is the MusicXML. - **Is it free?** No, but through useapi.net each score costs 10 Mureka Gold from your Mureka account, about 1.5 to 2 cents on a Mureka web plan, against 20 cents a song on the [official Mureka API](https://platform.mureka.ai/pricing) (as of October 2026). The API answers `412` when the balance is too low. Scoring the same YouTube link twice returned the earlier zip without a second charge in our tests. API access is a flat [useapi.net subscription](/docs/subscription), with no per-call charge from us. - **What kind of music transcribes well?** A solo song with clear vocals, a steady tempo and a consistent rhythm, per Mureka. Tempo changes and frequent rhythm changes are not supported well. The score holds the main melody, the chords and the lyrics, not every instrument. - **Can I get the stems or MIDI of every instrument instead?** That is a different tool. [POST /music/stems](/docs/api-mureka-v1/post-mureka-music-stems) splits one of your songs into up to 12 stems with MIDI. ### Conclusion Visit our <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> or <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> for any support questions and concerns. The runnable version of this tutorial is in [mureka-api/sheet-music](https://github.com/useapi/mureka-api/tree/main/sheet-music): one Node.js or Python script that takes a song id, a YouTube link or an MP3 and saves the unzipped sheet music. The same [GitHub repo](https://github.com/useapi/mureka-api) has examples for songs, lyrics and instrumentals. An AI assistant can make the sheet music for you too: the hosted [Mureka MCP server](/docs/api-mureka-v1/mcp) works with Claude Code, Cursor and VS Code, on your own Mureka account. === URL: https://useapi.net/docs/articles/muse-api-ja === Document URL: https://useapi.net/docs/articles/muse-api-ja --- layout: default title: Muse API で Meta Muse の AI 画像とセリフ付き動画を生成する方法(日本語チュートリアル) seo_title: "Muse API の使い方:Meta Muse で AI 画像とセリフ付き動画を生成(日本語)" description: "useapi.net の Muse API(Meta Muse・muse.ai の動画生成 API)の使い方。AI 画像とセリフ付き10秒動画を curl で生成。写真の合成、古い写真の復元とカラー化、動画の人物差し替え、日本語のセリフ。無料プランでも使えます。" keywords: [Muse API, museapi, Meta Muse API, muse.ai API, Muse API 使い方, Muse 使い方, muse.ai 使い方, Muse 動画生成, Meta Muse 動画生成, Meta Muse 動画 API, Meta Muse 画像, Meta AI 動画 API, AI 動画生成 API, 画像生成 API, 画像から動画 API, Muse プロンプト, Muse 利用上限, 写真 合成, 古い写真 復元, 写真 カラー化, 動画 人物 差し替え, セリフ付き動画, 日本語 セリフ 動画, muse2api 代替, 日本語チュートリアル, Japanese tutorial, curl] image: https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-cover.jpg parent: Articles nav_exclude: true lang: ja date: 2026-10-30 last_modified: 2026-10-30 nav_order: 907 video: name: "Meta Muse API Demo: Images, Talking Photos, Video with Sound, Chat & MCP (third-party, useapi.net)" description: "The third-party Meta Muse API by useapi.net: images, 10-second videos with sound and spoken dialogue, agent chat with live streaming and approvals, and a hosted MCP server, on your Muse website subscription." embed: https://www.youtube.com/embed/OMUGbfRIO5E thumbnail: https://i.ytimg.com/vi/OMUGbfRIO5E/maxresdefault.jpg date: 2026-10-14 duration: PT2M49S width: 1920 height: 1080 repo: https://github.com/useapi/muse-api translation_key: muse --- ## Muse API で Meta Muse の AI 画像とセリフ付き動画を生成する方法(日本語チュートリアル) <div class="lang-banner" lang="en"> <strong>Japanese-language tutorial.</strong> This page is written in Japanese for Japanese-speaking developers. The same material in English: <a href="/docs/articles/muse-images-videos">How to Generate AI Videos and Images with the Meta Muse API</a> · <a href="/docs/api-muse-v1">Muse API docs</a> </div> 12分で読めます • 2026年10月30日 useapi.net はサードパーティの API です。Meta とは提携しておらず、Meta の承認も受けていません。 ## 目次 ### はじめに [useapi.net の Muse API](/docs/api-muse-v1) を使うと、Meta のパーソナル AI エージェント Muse([muse.ai](https://muse.ai))で、POST リクエスト1回ごとに AI 画像1枚、またはセリフ付きの10秒の動画1本をコードから生成できます。生成したファイルにはすべて[アセット ID](/docs/api-muse-v1/get-muse-assets-assetId) が付き、そのまま次のジョブの入力に使えます。 ここでいう Muse は、[muse.ai](https://muse.ai) で提供されている Meta のエージェントです。2026年3月まで muse.ai の名前を使っていた動画ホスティング企業 Skiv のことではありません。この API はホスト型なので、muse2api のようなセルフホスト型のツールと違って、デプロイするものは何もありません。Meta 公式の API、muse2api、ホスト型 API の比較は [Meta Muse 動画 API の比較記事](/docs/articles/meta-muse-video-api)(英語)にまとめています。 API は、muse.ai で契約している [Muse のプラン](https://www.meta.com/ja-jp/help/subscriptions/1021145227643680/)をそのまま使って動き、無料プランでも使えます。この記事では、ヴィンテージの BMW のバイク、赤い髪のライダー、ゴールデンゲートブリッジの下のビーチという、ごく普通の3枚の写真から始めて、彼女がそのバイクで波しぶきを上げて走る1枚の画像に合成します。次にその画像を動画にして、彼女にセリフを叫ばせます。3つ目のジョブでは、別の写真に写っている女性が動画の中で彼女と入れ替わり、走りの映像はそのまま残ります。途中で、テキストからの画像生成と、100年前の肖像写真を復元・カラー化して写真の人物が顔を上げて話し出す動画も作ります。最後に、日本語のセリフを話させる例も載せています。以下のリクエストは、このページの画像や動画を実際に生成したときのものです。 <video poster="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g3-poster.jpg" src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g3.mp4" style="width: 100%; aspect-ratio: 1248/704; max-width: 720px" controls type="video/mp4" preload="metadata"></video> Muse が静止画から作った動画のライダーを、別の写真の女性に差し替えたもの([ステップ 8](#step-8))。 この記事は useapi.net の運営者が、自社のホスト型 API について書いたものです。 ### 利用枠の消費量 useapi.net は API であり、それ自体が画像や動画のサービスではありません。すべての呼び出しは [Setup Muse](/docs/start-here/setup-muse) で追加した Muse アカウント上で実行され、そのアカウントの Muse の週間利用枠を使います。useapi.net が画像や動画ごとに料金を取ることはありません。Muse は使用量を整数のパーセントで返すため、画像1枚では変化が見えないこともよくあります。 次の表は、無料プランで各ステップが消費した利用枠(前後の `percentUsed` の差)と、各ジョブの所要時間です。 | ステップ | エンドポイント | 出力 | 消費した利用枠 | 所要時間 | |---|---|---|--:|--:| | [テキストから画像、9:16](#step-3) | [POST /jobs/image](/docs/api-muse-v1/post-muse-jobs-image) | 1152×2048 | 未計測 | 30秒 | | [テキストから画像、正確に 16:9](#step-3) | [POST /jobs/image](/docs/api-muse-v1/post-muse-jobs-image) | 2048×1152 | 0% | 21秒 | | [ライダー + バイク + ビーチ](#step-4) | [POST /jobs/image](/docs/api-muse-v1/post-muse-jobs-image) | 2048×1152 | 0% | 31秒 | | [画像を動画にする](#step-5) | [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video) | 1280×720、10秒 | 3% | 88秒 | | [古い写真の復元](#step-6) | [POST /jobs/image](/docs/api-muse-v1/post-muse-jobs-image) | 1344×1792 | 1% | 34秒 | | [肖像写真が話し出す](#step-7) | [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video) | 832×1104、10秒 | 2% | 68秒 | | [動画の人物差し替え](#step-8) | [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video) | 1248×704、10秒 | 3% | 138秒 | | [日本語のセリフ](#japanese-speech) | [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video) | 1280×720、10秒 | 未計測 | 61秒 | アップロードは利用枠を消費しません。無料プランでは、動画1本で週間利用枠の2〜3%、画像1枚で0〜1%を消費したので、無料アカウント1つで週に約30〜50本の動画、または数百枚の画像を作れる計算です([ステップ 9](#step-9))。 ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. ### 始める前に 必要なのは、useapi.net の [API トークン](/docs/start-here/setup-useapi)と、[Setup Muse](/docs/start-here/setup-muse) で追加した Muse アカウントです。アカウントを追加する前に、次の点を確認してください。 - Muse は2026年10月23日に[日本で提供が始まりました](https://about.fb.com/ja/news/2026/10/muse-personal-ai-agent-launches-in-japan/)。日本で作ったアカウントは、そのまま追加できます。2026年10月時点で Muse を使えるのは米国、カナダ、日本、[シンガポール](https://about.fb.com/news/2026/10/muse-is-now-available-in-singapore-the-worlds-first-personal-ai-agent-built-for-everyone/)なので、アカウントはこのいずれかの国で作成してください。追加したあとは、どこからでも API を呼び出せます。 - プランは Free(利用上限あり)、Power(月額20ドル)、Maximum(月額100ドル)の3つです(2026年10月時点)。[Meta のヘルプページ](https://www.meta.com/ja-jp/help/subscriptions/1021145227643680/)ではドル建てで表示されており、特典や提供状況は地域によって異なる場合があると Meta は説明しています。 - [muse.ai](https://muse.ai) で Muse の初期設定(Meta の年齢確認を含む)を済ませ、画像を1枚作成しておいてください。 - API はメールアドレスとパスワードでログインするため、アカウントにパスワードが設定されている必要があります。メールで届くコードだけでログインしている Meta アカウントにはパスワードがないので、[Meta アカウントセンター](https://accountscenter.meta.com/password_and_security/)(パスワードとセキュリティ)で作成してから追加してください。パスワードがないと、追加は `400` で拒否されます。 - アカウントは API 専用にして、ほかの自動化ツールでは使わないでください。ブラウザで muse.ai を開くのは問題ありませんが、上記の提供地域から(またはそのいずれかの国の VPN 経由で)開いてください。それ以外の地域から使われたと判断されると、Meta がそのアカウントの動画生成を停止することがあります。 この記事の手順は、Node.js と Python のスクリプトとして GitHub の [useapi/muse-api](https://github.com/useapi/muse-api) リポジトリの [`images-videos/`](https://github.com/useapi/muse-api/tree/main/images-videos) にもまとめてあります。Claude Code と Codex 向けの[エージェントスキル(Agent Skill)](https://github.com/useapi/muse-api/tree/main/skills/muse-video)もあります。すべてのリクエストは [Postman コレクション](/assets/postman/muse-v1.json)にも入っています。 以下の手順では `curl`、`jq` と、次の変数・ヘルパー関数を使います。 <details markdown="block"> <summary>変数とヘルパー関数を表示</summary> ```bash export USEAPI_TOKEN="user:12345-..." export EMAIL="example@gmail.com" export MUSE_PASSWORD="..." # the Muse account password, used once in step 1 API=https://api.useapi.net/v1/muse AUTH="Authorization: Bearer $USEAPI_TOKEN" enc() { jq -rn --arg v "$1" '$v|@uri'; } post() { curl -sS -X POST "$API/$1" -H "$AUTH" -H "Content-Type: application/json" -d "$2"; } get() { curl -sS "$API/$1" -H "$AUTH"; } upload() { curl -sS -X POST "$API/assets?email=$(enc "$EMAIL")" -H "$AUTH" -H "Content-Type: $2" --data-binary @"$1" | jq -r .assetId; } download() { curl -sSf "$API/assets/$(enc "$1")" -H "$AUTH" -o "$2"; } # run a job async: submit it, poll GET /jobs/{jobid} every 10 s, save the final job record to $1 run() { local job id job=$(post "$2" "$(jq '. + {async: true}' <<< "$3")") id=$(jq -r .jobid <<< "$job") while [ "$(jq -r .status <<< "$job")" = started ]; do sleep 10 job=$(get "jobs/$(enc "$id")") done echo "$job" > "$1" jq '{status, error, text: .result.text, asset: .result.assets[0].assetId}' "$1" } ``` </details> 生成はすべてジョブとして実行されます。`async` を指定しない場合、POST はジョブの完了を最大約100秒待ち、完了すればジョブレコードを返します。それまでに終わらなければ `202` が返りますが、ジョブはサーバー側で実行を続けるので、[GET /jobs/`jobid`](/docs/api-muse-v1/get-muse-jobs-jobid) で結果を取得できます。この記事の動画は1本あたり61〜138秒かかったので、`run` はすべてのジョブを `async: true` で送り、GET /jobs/`jobid` をポーリングします。`run` が `completed` 以外の `status` を表示したら、先に進む前に `error` を確認してください。 ポーリングの代わりに Webhook で完了通知を受け取りたい場合は、以下のどのリクエストボディにも `replyUrl: "https://example.com/hooks/muse"`(ジョブレコードにそのまま返される任意の識別子 `replyRef` も指定可能)を追加できます。ジョブが終わると、API は最終的なジョブレコードを JSON でその URL に1回 `POST` します。 各種 ID には `:` や `@` が含まれるため、URL のパスに入れるときは `enc` でエンコードします。1つのジョブの入力はすべて同じ Muse アカウント上にある必要があるため、アップロードでは `email` を指定しています。ジョブは入力を持っているアカウントで実行されます。 ### 実際の手順 プロンプトは Muse にそのまま送るものなので、英語のまま載せています。 #### 1. アカウントを追加する [POST /accounts](/docs/api-muse-v1/post-muse-accounts) は Muse アカウントのメールアドレスとパスワードを受け取ります。API は一度だけログインして30日間のセッションを保存し、自動で更新します。API がログインするたび(追加時とセッション更新時)に Muse からログインコードのメールが届きますが、コードを入力する必要はありません。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-accounts">POST /accounts</a></summary> ```bash post accounts "$(jq -n --arg email "$EMAIL" --arg password "$MUSE_PASSWORD" '{email: $email, password: $password}')" | jq '{health, maxJobs, quota}' ``` </details> レスポンスには `health: "OK"`、`maxJobs`(このアカウントで同時に実行できるジョブ数。デフォルトは10、1〜50で設定可能)、アカウントのプランと使用量が含まれます。ここでは `tier: "HATCH_FREE"`、つまり無料プランです。代わりに `596` が返った場合は、Meta がセキュリティチェックを求めています。ブラウザで一度 muse.ai にログインしてチェックを済ませ、同じメールアドレスとパスワードをもう一度送ってください。 #### 2. 写真をアップロードする [POST /assets](/docs/api-muse-v1/post-muse-assets) は、ファイルのバイナリをそのままリクエストボディとして受け取ります(multipart ではありません)。1ファイルの上限は50 MB です(アップロードは毎秒約1 MB なので、50 MB なら約1分かかります)。ファイルはアカウントの Muse ワークスペースに書き込まれ、useapi.net には何も保存されません。レスポンスの `assetId`(アセット ID)が、ジョブの `image_N` に渡す値です。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-assets">POST /assets</a></summary> ```bash BMW=$(upload bmw.jpeg image/jpeg) RIDER=$(upload rider.jpeg image/jpeg) BEACH=$(upload beach.jpeg image/jpeg) OLD_PHOTO=$(upload old-photo.jpeg image/jpeg) PINK=$(upload pink-hair.jpeg image/jpeg) echo "$BMW" # user:12345-email:6578616d706c6540676d61696c2e636f6d-image:7db53e7a1f0979cbab6ff46ec3f0a35b60e6ee579a0d738a9628cf46a0c7a0f5.jpg ``` </details> <div style="display: flex; flex-wrap: wrap; gap: 8px; align-items: flex-start"> <figure style="margin: 0; width: 32%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-motorcycle.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-motorcycle.jpg" alt="image_1:バイク" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em"><code>image_1</code>:バイク</figcaption></figure> <figure style="margin: 0; width: 18%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-redhead.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-redhead.jpg" alt="image_2:ライダー" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em"><code>image_2</code>:ライダー</figcaption></figure> <figure style="margin: 0; width: 32%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-beach.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-beach.jpg" alt="image_3:ビーチ" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em"><code>image_3</code>:ビーチ</figcaption></figure> <figure style="margin: 0; width: 18%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-oldphoto.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-oldphoto.jpg" alt="古い肖像写真" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">古い肖像写真</figcaption></figure> <figure style="margin: 0; width: 18%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-pinkhair.webp" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-pinkhair.webp" alt="2人目のライダー" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">2人目のライダー</figcaption></figure> </div> 5枚の入力画像:バイク、ライダー、ビーチ、古い肖像写真、2人目のライダー。 アセット ID はファイルの内容から作られます。そのため、同じファイルを同じアカウントにもう一度アップロードすると同じ ID が返り、何も書き込まれません。 #### 3. テキストから画像を生成する Muse にはアスペクト比のパラメーターがないので、比率はプロンプトに書きます。まずは縦長のポートレートです。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-image">POST /jobs/image</a></summary> ```bash run portrait.json jobs/image "$(jq -n '{prompt: "Vertical 9:16 full-body portrait photo: a confident young woman biker with long wavy fiery red hair, green eyes and freckles, in a worn black leather jacket, dark jeans and boots, standing in a rain-soaked neon alley at dusk, looking straight at the camera, cinematic lighting, photorealistic."}')" download "$(jq -r '.result.assets[0].assetId' portrait.json)" portrait.webp ``` </details> <img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-a2.webp" style="width: 100%; max-width: 420px" alt="9:16 のテキストから画像:雨に濡れたネオンの路地に立つ赤い髪のライダー"> [新しいタブで開く](https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-a2.webp){:target="_blank"} 結果はちょうど 9:16 の 1152×2048 でした。一方、横長版を `Cinematic 16:9 landscape photo: …` と指定すると、1920×1280、つまり 3:2 になりました。`in exactly 16:9 aspect ratio` と書き直すと、指定どおりの比率になりました。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-image">POST /jobs/image</a></summary> ```bash run bmw-noir.json jobs/image "$(jq -n '{prompt: "In exactly 16:9 aspect ratio (landscape), a cinematic photo of a vintage 1920s black BMW motorcycle with white pinstripes, spoked wheels and a brown leather saddle, parked on wet cobblestones at night in San Francisco, the Golden Gate Bridge glowing through fog in the distance, neo-noir moonlight, reflections on the wet street, shot on 35mm film."}')" download "$(jq -r '.result.assets[0].assetId' bmw-noir.json)" bmw-noir.webp ``` </details> <img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-a5.webp" style="width: 100%" alt="正確な 16:9 のテキストから画像:夜のサンフランシスコの濡れた石畳に停まるヴィンテージの BMW のバイク"> [新しいタブで開く](https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-a5.webp){:target="_blank"} Muse からの返答は「That 16:9 frame with the bridge ghosting through the fog is pure neo-noir. Enjoy.」で、`result.text` に入っています。 #### 4. 3枚の写真を1枚に合成する 1つのジョブには `image_1`〜`image_9` として最大9枚の画像を渡せます。プロンプトでは、この名前で各画像を参照します。ここではバイクが `image_1`、ライダーが `image_2`、ビーチが `image_3` です。写真のビーチをそのまま使うようプロンプトで指示しているので、ゴールデンゲートブリッジは写真と同じ位置に残ります。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-image">POST /jobs/image</a></summary> ```bash run beach-ride.json jobs/image "$(jq -n --arg bmw "$BMW" --arg rider "$RIDER" --arg beach "$BEACH" \ '{image_1: $bmw, image_2: $rider, image_3: $beach, prompt: "In exactly 16:9 aspect ratio (landscape), a cinematic photo: the woman from image_2 (her face, long wavy red hair, light blue top and jeans) riding the exact vintage motorcycle from image_1 along the shoreline of the beach in image_3, the front wheel cutting through the shallow surf and throwing spray, bright afternoon sun, her hair streaming in the wind, photorealistic. Use the beach, rocks and Golden Gate Bridge from image_3 as the background exactly as photographed: same position, same orientation, not mirrored or redrawn. Keep her face and the motorcycle'\''s design exactly as in the images."}')" BEACH_RIDE=$(jq -r '.result.assets[0].assetId' beach-ride.json) download "$BEACH_RIDE" beach-ride.webp ``` </details> <img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g1.webp" style="width: 100%" alt="ライダー、バイク、ビーチを1枚に合成した画像"> [新しいタブで開く](https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g1.webp){:target="_blank"} 31秒で完了し、週間利用枠に目に見える変化はありませんでした。 #### 5. 画像を動画にする(再アップロード不要) `BEACH_RIDE` は Muse が作ったファイルのアセット ID です。すでにアカウントのワークスペースにあるので、ダウンロードもアップロードもせずに、そのまま次のジョブの `image_1` として渡せます。`Animate image_1` と書くと、その画像を起点に縦横比を保った動画ができ、引用符で囲んだセリフを登場人物が話します。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-video">POST /jobs/video</a></summary> ```bash run surf.json jobs/video "$(jq -n --arg img "$BEACH_RIDE" '{image_1: $img, prompt: "Animate image_1 into a cinematic video in exactly 16:9 aspect ratio (landscape): she rides the vintage motorcycle along the shoreline, the front wheel slices through the shallow waves and sends spray flying, the old engine roars, she raises one fist and shouts with a laugh: \"Nothing beats this view!\" The camera tracks alongside her. The beach, the rocks and the Golden Gate Bridge stay exactly as in image_1 (same orientation). Keep her face and the motorcycle exactly as in image_1."}')" SURF=$(jq -r '.result.assets[0].assetId' surf.json) download "$SURF" surf.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g2-poster.jpg" src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g2.mp4" style="width: 100%; aspect-ratio: 16/9; max-width: 720px" controls type="video/mp4" preload="metadata"></video> YouTube でも公開しています:[3 photos in, 1 talking video out: Meta Muse API from REST](https://youtube.com/shorts/v_7mREyFSWk)(英語)。 10秒、1280×720、音声付きの動画になりました。Muse からの返答は「Done. 10 seconds, 16:9 landscape, straight from your image — no edits, no upscaling.」でした。 このジョブは最初の実行で37秒後に失敗し、Muse は「the video worker glitched out before it rendered anything, so no clip was made」と返答しました。API はこのような返答を `503`(何も生成されていない)として返します。同じリクエストを再実行すると成功しました。内容を理由に拒否された場合は `403` が返るので、プロンプトを変える必要があります。 #### 6. 古い写真を復元してカラー化する 画像ジョブは画像の修復もできます。この古い肖像写真は、色あせたセピア調の 685×900 ピクセル、3:4 の写真です。プロンプトでは直す内容を挙げ、同じ構図を保つよう念を押しています。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-image">POST /jobs/image</a></summary> ```bash run restored.json jobs/image "$(jq -n --arg img "$OLD_PHOTO" '{image_1: $img, prompt: "Restore the old photograph image_1 as a high-quality modern photo: remove the scratches, dust, stains, fading and grain, recover sharp detail in the face, hair and fabric, and colorize it naturally (warm natural skin tones, dark brown hair, ivory tulle shawl, a soft pink rose with green leaves, a muted warm background). Keep the exact same person, expression, pose, framing and crop, and the same portrait aspect ratio as image_1 (3:4, 685×900): do not crop, extend or reframe it."}')" RESTORED=$(jq -r '.result.assets[0].assetId' restored.json) download "$RESTORED" restored.webp ``` </details> <div style="display: flex; flex-wrap: wrap; gap: 8px; align-items: flex-start"> <figure style="margin: 0; width: 48%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-oldphoto.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-oldphoto.jpg" alt="復元前:元の写真、685×900" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">復元前:元の写真、685×900</figcaption></figure> <figure style="margin: 0; width: 48%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-e1.webp" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-e1.webp" alt="復元後:復元してカラー化、1344×1792" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">復元後:復元してカラー化、1344×1792</figcaption></figure> </div> 結果は 1344×1792 で、同じ 3:4 の構図のまま解像度は縦横それぞれ約2倍になり、ポーズもトリミングも変わっていません。Muse からの返答は「Done — restored, de-grained, and colorized, same framing and pose.」でした。 #### 7. 古い写真の人物が話し出す 復元した画像を、そのまま動画ジョブに渡します。動画は肖像写真の縦横比を保つので、832×1104 で返ってきました。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-video">POST /jobs/video</a></summary> ```bash run portrait-video.json jobs/video "$(jq -n --arg img "$RESTORED" '{image_1: $img, prompt: "Animate image_1 into a video with the same portrait frame: the young woman slowly lifts her eyes to the camera, her smile widens, she gently touches the rose on her shoulder and says softly: \"It has been a hundred years... and you still remember me.\" A light breeze moves a few strands of her hair, soft window light, the camera stays still with a very slow push-in. Keep her face exactly as in image_1."}')" download "$(jq -r '.result.assets[0].assetId' portrait-video.json)" portrait.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-e2-poster.jpg" src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-e2.mp4" style="width: 100%; aspect-ratio: 832/1104; max-width: 420px" controls type="video/mp4" preload="metadata"></video> YouTube でも公開しています:[This old portrait just spoke: one API call (Meta Muse API, third-party)](https://youtube.com/shorts/GLHoINX_ozE)(英語)。 #### 8. 動画の人物を差し替える 動画ジョブは動画も入力として受け取ります。`video_1` はステップ 5 で作ったビーチの走行動画、`image_1` はピンクの髪を2つのお団子にした2人目の女性の写真です。プロンプトでは、ライダーを入れ替えてそれ以外はすべてそのままにするよう Muse に指示し、新しいセリフも指定しています。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-video">POST /jobs/video</a></summary> ```bash run swap.json jobs/video "$(jq -n --arg vid "$SURF" --arg img "$PINK" '{video_1: $vid, image_1: $img, prompt: "Edit video_1: replace the rider with the woman from image_1 (her face, pink hair in two buns, colorful makeup and tattoos), and keep everything else the same: the motorcycle, the beach, the waves and spray, the Golden Gate Bridge, the light, the camera move and the timing. Instead of the original line she shouts: \"Catch me if you can, San Francisco!\" Keep the 16:9 frame and the same length."}')" download "$(jq -r '.result.assets[0].assetId' swap.json)" swap.mp4 ``` </details> <div style="display: flex; flex-wrap: wrap; gap: 8px; align-items: flex-start"> <figure style="margin: 0; width: 48%"><video poster="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g2-poster.jpg" src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g2.mp4" style="width: 100%; aspect-ratio: 16/9" controls type="video/mp4" preload="metadata"></video><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">差し替え前:元のライダー</figcaption></figure> <figure style="margin: 0; width: 48%"><video poster="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g3-poster.jpg" src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g3.mp4" style="width: 100%; aspect-ratio: 1248/704" controls type="video/mp4" preload="metadata"></video><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">差し替え後:写真のライダー</figcaption></figure> </div> このジョブは138秒かかり、今回の手順の中で最も時間がかかりました。この記事のジョブをすべて非同期で実行しているのはそのためです。できあがった動画は、走りの映像はそのままに、バイクに乗っているのが別の女性に替わり、新しいセリフを叫んでいます。Muse からの返答は「Done. She's in, 10 seconds, 16:9, same ride, same bridge, same waves.」でした。 YouTube でも公開しています:[Replace the person in a video, keep everything else: Meta Muse API](https://youtube.com/shorts/XDCY1XIsd5Y)(英語)。 #### 9. 週間利用枠を確認する [GET /accounts/`email`](/docs/api-muse-v1/get-muse-accounts-email) は、アカウントのプランと使用量をその時点の値で取得します。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/get-muse-accounts-email">GET /accounts/email</a></summary> ```bash get "accounts/$(enc "$EMAIL")" | jq '{session, quota}' ``` </details> `quota.percentUsed` はその週に消費した利用枠の割合(整数のパーセント)、`quota.resetsAt` は利用枠がリセットされる日時で、期間の開始から1週間後です。上の3本の動画はそれぞれ2〜3%、画像はそれぞれ0%か1%を消費しました。テスト全体では(ここに載せていない2つのジョブも含めて)、この無料アカウントの使用量は16%から28%になりました。`email` を指定していない新しいジョブは登録済みのほかのアカウントに振り分けられます。そのアカウントを指定したジョブや、すべてのアカウントが上限に達しているときのジョブには、`resetsAt` まで `412` が返ります。 ### 日本語でセリフを話させる Muse は日本語のセリフも話せます。2026年10月30日に、次のプロンプトで試しました。リクエストの形はステップ 5 や 7 と同じですが、入力画像は渡さず、テキストだけから動画を生成しています。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-video">POST /jobs/video</a></summary> ```bash run tokyo.json jobs/video "$(jq -n '{prompt: "A young woman stands on a quiet Tokyo side street at dusk, paper lanterns glowing behind her. She smiles at the camera and says in natural Japanese: \"東京からこんにちは。この動画は、Muse API へのリクエスト一つで作りました。\" In exactly 16:9 aspect ratio."}')" download "$(jq -r '.result.assets[0].assetId' tokyo.json)" tokyo.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-30-muse-api-ja/muse-ja-tokyo-greeting-poster.jpg" src="https://media.useapi.net/articles/2026-10-30-muse-api-ja/muse-ja-tokyo-greeting.mp4" style="width: 100%; aspect-ratio: 1280/720; max-width: 720px" controls type="video/mp4" preload="metadata"></video> 結果は 1280×720、10秒、音声付きの動画で、ジョブは61秒で完了しました。音声を文字起こししたところ、プロンプトに書いたとおりのセリフが日本語で話されていました。背景の看板にも「居酒屋」と日本語で描かれています。このジョブで消費した利用枠は計測していません。 コツは、日本語のセリフを引用符で囲んでプロンプトに入れ、`in natural Japanese` と書き添えることです。Muse は引用符で囲んだセリフをそのまま話します。 ### わかったこと - アスペクト比は `in exactly 16:9 aspect ratio` と書きます。`Cinematic 16:9 landscape photo` では一度 3:2 で返ってきました。 - 動画はどれも約10秒です。プロンプトで5秒と指定しても10秒でした。 - 画像から作る動画は、プロンプトで別の比率を指定しない限り、元の画像の縦横比を保ちます。`in exactly 9:16 aspect ratio` と書くと、16:9 のビーチの画像が 720×1280 の縦長動画になりました。引き伸ばしではなく、構図を作り直しています。 - 動画のプロンプトで引用符で囲んだセリフは、登場人物がそのまま話します。 - 生成したファイルは `assetId`(アセット ID)で次のジョブに渡します。ファイルはアカウントのワークスペースに残るので、編集を続ける途中でダウンロードする必要はありません。 - 変えてはいけない部分を明記します。「Same position, same orientation, not mirrored or redrawn」と書いたことで、合成画像に写真のビーチがそのまま残りました。 - Muse 自身の言葉(「glitched out」など)を含む `503` は、再実行すれば成功することがあります。`403` は拒否なので、プロンプトを変える必要があります。 - 動画ジョブは `async: true` で送ります。同期リクエストの待ち時間は最大約100秒ですが、人物の差し替えには138秒かかりました。 ### よくある質問 - **Meta Muse(muse.ai)の API はありますか?** あります。useapi.net の [Muse API](/docs/api-muse-v1) を使えば、契約中の Muse のプランで画像も音声付きの約10秒の動画も生成できます。Meta 公式の [Model API](https://dev.meta.ai/docs/pricing-rate-limits) は Muse Image を1枚あたり0.01ドルで提供していますが、2026年10月時点で動画生成には対応しておらず、muse.ai の Muse エージェントの API もありません。 - **Meta Muse は日本で使えますか?日本のアカウントで API は使えますか?** 使えます。日本で作成したアカウントを useapi.net の [Setup Muse](/docs/start-here/setup-muse) でそのまま追加できます。無料プランのアカウントでも問題ありません。muse.ai で初期設定を済ませて画像を1枚作り、パスワードを設定しておけば準備完了です。詳しくは[始める前に](#before-you-start)をご覧ください。 - **Muse の動画で日本語のセリフを話させられますか?** 話させられます。useapi.net の Muse API で試したところ、日本語のセリフを引用符で囲んでプロンプトに入れるだけで、1回の [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video) でそのセリフを話す 1280×720、10秒の動画が61秒で返ってきました。プロンプトと動画は[日本語でセリフを話させる](#japanese-speech)に載せています。 - **料金はどのくらいかかりますか?** useapi.net は画像や動画ごとに料金を取りません。ジョブは契約中の Muse のプランの週間利用枠を使い、無料プランでも動きます。今回のテストの結果から、無料アカウント1つで週に約30〜50本の動画を作れる計算です。有料の Power(月額20ドル)と Maximum(月額100ドル)では週間利用枠が増えます(2026年10月時点、ドル建て。日本での請求額は購入画面でご確認ください)。 - **muse2api との違いは何ですか?** useapi.net の Muse API はホスト型のサービスなので、デプロイするものはありません。アカウントはメールアドレスとパスワードで一度追加すれば、ログイン状態は useapi.net 側で維持します。完了したジョブは Webhook で受け取れます。[muse2api](https://github.com/czg86389-hub/muse2api) は、自前でデプロイ・ホスティングし、運用も続ける必要があるプロジェクトです。詳しくは[比較記事](/docs/articles/meta-muse-video-api)(英語)をご覧ください。 ### おわりに ご質問は <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord サーバー</a> または <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram チャンネル</a>へどうぞ。 コード例は [GitHub リポジトリ](https://github.com/useapi/muse-api)にあります。 同じ操作は、ホスト型の [Muse MCP サーバー](/docs/api-muse-v1/mcp)のツールとしても提供しており、Claude Code、Cursor、VS Code から使えます。 === URL: https://useapi.net/docs/articles/muse-api-zh === Document URL: https://useapi.net/docs/articles/muse-api-zh --- layout: default title: 如何通过 Muse API 用 Meta Muse 生成 AI 图片和带对白的视频(中文教程) seo_title: "Muse API 中文教程:用 Meta Muse 生成 AI 图片和带对白的视频" description: "Muse API 中文教程:通过 useapi.net 用你的 Meta Muse(muse.ai)网站订阅生成 AI 图片和带对白的 10 秒视频,多图合成、老照片修复上色、视频换人,免费套餐可用,每月固定 15 美元。" keywords: [Muse API, Meta Muse API, muse.ai API, Muse API 教程, Meta Muse 视频, Meta Muse 图片, Meta Muse 视频 API, muse2api 替代, Meta AI 视频 API, AI 图片生成 API, AI 视频生成 API, 图生视频 API, 多图合成, 老照片修复 API, 照片上色 API, 视频换人, 视频换脸 API, AI 视频对白, 中文教程, Chinese tutorial, curl] image: https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-cover.jpg parent: Articles nav_exclude: true lang: zh-CN date: 2026-10-12 last_modified: 2026-10-30 nav_order: 901 repo: https://github.com/useapi/muse-api translation_key: muse --- ## 如何通过 Muse API 用 Meta Muse 生成 AI 图片和带对白的视频(中文教程) <div class="lang-banner" lang="en"> <strong>Chinese-language tutorial.</strong> This page is written in Simplified Chinese for Chinese-speaking developers. The same material in English: <a href="/docs/articles/muse-images-videos">How to Generate AI Videos and Images with the Meta Muse API</a> · <a href="/docs/api-muse-v1">Muse API docs</a> </div> 12 分钟阅读 • 2026 年 10 月 12 日(2026 年 10 月 30 日更新) useapi.net 是第三方 API,与 Meta 无关联,也未获得 Meta 的认可。 ## 目录 ### 简介 [useapi.net 的 Muse API](/docs/api-muse-v1) 让你用代码调用 Meta 的个人 AI 智能体 [Muse](https://muse.ai):一个 POST 请求就能生成一张图片,或一段 10 秒、带人物对白的视频,而且生成的每个文件都是一个 [asset id](/docs/api-muse-v1/get-muse-assets-assetId),可以直接作为下一个任务的输入。 API 运行在你的 [Muse 网站订阅](https://www.meta.com/help/subscriptions/1021145227643680/)上,免费套餐就能用。本文从三张普通照片出发:一辆老式宝马摩托车、一位红发骑手和金门大桥下的海滩,把它们合成一张她骑着这辆摩托车冲过浪花的图片。接着把这张图片做成视频,让她喊出一句台词。第三个任务里,第四张照片中的另一位女士在视频里替换了她,骑行画面保持不变。过程中还会演示文生图,以及把一张百年老照片修复、上色,再让照片里的人抬头开口说话。下面的每个请求都是生成本页素材时实际用的请求。 <video poster="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g3-poster.jpg" src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g3.mp4" style="width: 100%; aspect-ratio: 1248/704; max-width: 720px" controls type="video/mp4" preload="metadata"></video> 把照片里的骑手换进 Muse 用一张静态图片生成的视频([第 8 步](#step-8))。 本文由 useapi.net 维护者撰写,介绍的是我们自己的托管 API。 ### 消耗了多少额度 useapi.net 是一个 API,本身不是图片或视频服务。每次调用都运行在你通过 [Setup Muse](/docs/start-here/setup-muse) 绑定的 Muse 账号上,消耗该账号每周的 Muse 额度,useapi.net 不按图片或视频计费。Muse 用整数百分比报告已用额度,所以生成一张图片后往往看不到变化。 下表是免费套餐上每一步消耗的额度(取自前后两次 `percentUsed` 的差值)以及每个任务的耗时: | 步骤 | 接口 | 输出 | 消耗额度 | 耗时 | |---|---|---|--:|--:| | [文生图,9:16](#step-3) | [POST /jobs/image](/docs/api-muse-v1/post-muse-jobs-image) | 1152×2048 | 未测量 | 30 秒 | | [文生图,严格 16:9](#step-3) | [POST /jobs/image](/docs/api-muse-v1/post-muse-jobs-image) | 2048×1152 | 0% | 21 秒 | | [骑手 + 摩托车 + 海滩](#step-4) | [POST /jobs/image](/docs/api-muse-v1/post-muse-jobs-image) | 2048×1152 | 0% | 31 秒 | | [把图片做成视频](#step-5) | [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video) | 1280×720,10 秒 | 3% | 88 秒 | | [修复老照片](#step-6) | [POST /jobs/image](/docs/api-muse-v1/post-muse-jobs-image) | 1344×1792 | 1% | 34 秒 | | [让人像开口说话](#step-7) | [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video) | 832×1104,10 秒 | 2% | 68 秒 | | [视频换人](#step-8) | [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video) | 1248×704,10 秒 | 3% | 138 秒 | 上传不消耗额度。在免费套餐上,一条视频消耗每周额度的 2% 到 3%,一张图片 0% 到 1%,所以一个免费账号每周大约能生成 30 到 50 条视频,或几百张图片(见[第 9 步](#step-9))。 ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. ### 准备工作 你需要一个 useapi.net [API Token](/docs/start-here/setup-useapi),以及一个通过 [Setup Muse](/docs/start-here/setup-muse) 绑定的 Muse 账号。截至 2026 年 10 月,Muse 在美国、加拿大、[日本](https://about.fb.com/ja/news/2026/10/muse-personal-ai-agent-launches-in-japan/)和[新加坡](https://about.fb.com/news/2026/10/muse-is-now-available-in-singapore-the-worlds-first-personal-ai-agent-built-for-everyone/)开放,账号需要在这四个国家之一注册,绑定后可以在任何地方调用 API。绑定前请先在 [muse.ai](https://muse.ai) 完成 Muse 的新手引导(包括 Meta 的年龄验证)并生成一张图片。账号必须能用邮箱 + 密码登录,只用邮件验证码登录的 Meta 账号需要先在 [Meta 账户中心](https://accountscenter.meta.com/password_and_security/) 设置密码,否则绑定会返回 `400`。完整流程也做成了一个脚本(Node.js 和 Python):GitHub 上 [useapi/muse-api](https://github.com/useapi/muse-api) 仓库的 [`images-videos/`](https://github.com/useapi/muse-api/tree/main/images-videos),另有给 Claude Code 和 Codex 用的 [agent skill](https://github.com/useapi/muse-api/tree/main/skills/muse-video)。所有请求也都在 [Postman 集合](/assets/postman/muse-v1.json)里。 下面的步骤用到 `curl`、`jq` 和这些变量与辅助函数: <details markdown="block"> <summary>展开变量与辅助函数</summary> ```bash export USEAPI_TOKEN="user:12345-..." export EMAIL="example@gmail.com" export MUSE_PASSWORD="..." # the Muse account password, used once in step 1 API=https://api.useapi.net/v1/muse AUTH="Authorization: Bearer $USEAPI_TOKEN" enc() { jq -rn --arg v "$1" '$v|@uri'; } post() { curl -sS -X POST "$API/$1" -H "$AUTH" -H "Content-Type: application/json" -d "$2"; } get() { curl -sS "$API/$1" -H "$AUTH"; } upload() { curl -sS -X POST "$API/assets?email=$(enc "$EMAIL")" -H "$AUTH" -H "Content-Type: $2" --data-binary @"$1" | jq -r .assetId; } download() { curl -sSf "$API/assets/$(enc "$1")" -H "$AUTH" -o "$2"; } # run a job async: submit it, poll GET /jobs/{jobid} every 10 s, save the final job record to $1 run() { local job id job=$(post "$2" "$(jq '. + {async: true}' <<< "$3")") id=$(jq -r .jobid <<< "$job") while [ "$(jq -r .status <<< "$job")" = started ]; do sleep 10 job=$(get "jobs/$(enc "$id")") done echo "$job" > "$1" jq '{status, error, text: .result.text, asset: .result.assets[0].assetId}' "$1" } ``` </details> 每次生成都作为一个任务运行。不传 `async` 时,POST 最多等待约 100 秒,返回完成的任务记录,或者在任务仍在运行时返回 `202`。本文中一条视频耗时 68 到 138 秒,所以 `run` 对每个任务都传 `async: true`,再轮询 [GET /jobs/`jobid`](/docs/api-muse-v1/get-muse-jobs-jobid)。如果 `run` 输出的 `status` 不是 `completed`,先看 `error` 再继续。 不想轮询的话,可以在下面任意请求体里加上 `replyUrl: "https://example.com/hooks/muse"`(可选再加 `replyRef`)。任务结束时,API 会向这个地址发送一次 `POST`,内容是 JSON 格式的最终任务记录。 各种 id 里含有 `:` 和 `@`,放进 URL 路径时要用 `enc` 编码。同一个任务的所有输入必须在同一个 Muse 账号上,所以上传时指定了 `email`,任务会在持有这些输入的账号上运行。 ### 实战步骤 提示词保持英文原样,因为它们是直接发给 Muse 的。 #### 1. 绑定账号 [POST /accounts](/docs/api-muse-v1/post-muse-accounts) 接收 Muse 账号的邮箱和密码。API 只登录一次,保存 30 天的会话并自动续期。每次登录时 Muse 都会给账号发一封登录验证码邮件,这封邮件只是通知,不需要输入任何内容。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-accounts">POST /accounts</a></summary> ```bash post accounts "$(jq -n --arg email "$EMAIL" --arg password "$MUSE_PASSWORD" '{email: $email, password: $password}')" | jq '{health, maxJobs, quota}' ``` </details> 返回结果里有 `health: "OK"`、`maxJobs`(默认 10,可设 1 到 50)以及账号的套餐和用量,这里是 `tier: "HATCH_FREE"`,即免费套餐。如果返回的是 `596`,说明 Meta 要求做安全验证:在浏览器里登录一次 muse.ai 完成验证,再用同样的邮箱和密码重新提交。 #### 2. 上传照片 [POST /assets](/docs/api-muse-v1/post-muse-assets) 以原始文件作为请求体,单个文件最大 50 MB(上传速度约每秒 1 MB,50 MB 约需一分钟),文件写入账号的 Muse 工作区,useapi.net 不存储任何内容。返回的 `assetId` 就是任务里 `image_N` 要传的值。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-assets">POST /assets</a></summary> ```bash BMW=$(upload bmw.jpeg image/jpeg) RIDER=$(upload rider.jpeg image/jpeg) BEACH=$(upload beach.jpeg image/jpeg) OLD_PHOTO=$(upload old-photo.jpeg image/jpeg) PINK=$(upload pink-hair.jpeg image/jpeg) echo "$BMW" # user:12345-email:6578616d706c6540676d61696c2e636f6d-image:7db53e7a1f0979cbab6ff46ec3f0a35b60e6ee579a0d738a9628cf46a0c7a0f5.jpg ``` </details> <div style="display: flex; flex-wrap: wrap; gap: 8px; align-items: flex-start"> <figure style="margin: 0; width: 32%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-motorcycle.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-motorcycle.jpg" alt="image_1:摩托车" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em"><code>image_1</code>:摩托车</figcaption></figure> <figure style="margin: 0; width: 18%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-redhead.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-redhead.jpg" alt="image_2:骑手" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em"><code>image_2</code>:骑手</figcaption></figure> <figure style="margin: 0; width: 32%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-beach.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-beach.jpg" alt="image_3:海滩" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em"><code>image_3</code>:海滩</figcaption></figure> <figure style="margin: 0; width: 18%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-oldphoto.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-oldphoto.jpg" alt="老人像照片" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">老人像照片</figcaption></figure> <figure style="margin: 0; width: 18%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-pinkhair.webp" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-pinkhair.webp" alt="第二位骑手" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">第二位骑手</figcaption></figure> </div> 五张输入图片:摩托车、骑手、海滩、老人像照片和第二位骑手。 asset id 由文件内容生成,所以把同一个文件再次上传到同一个账号,会返回同样的 id,不会重复写入。 #### 3. 文生图 Muse 没有宽高比参数,比例写在提示词里。先生成一张竖幅人像: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-image">POST /jobs/image</a></summary> ```bash run portrait.json jobs/image "$(jq -n '{prompt: "Vertical 9:16 full-body portrait photo: a confident young woman biker with long wavy fiery red hair, green eyes and freckles, in a worn black leather jacket, dark jeans and boots, standing in a rain-soaked neon alley at dusk, looking straight at the camera, cinematic lighting, photorealistic."}')" download "$(jq -r '.result.assets[0].assetId' portrait.json)" portrait.webp ``` </details> <img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-a2.webp" style="width: 100%; max-width: 420px" alt="9:16 文生图:雨夜霓虹小巷里的红发女骑手"> [在新标签页打开](https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-a2.webp){:target="_blank"} 返回的正好是 9:16,1152×2048。横幅版本用 `Cinematic 16:9 landscape photo: …` 描述时,返回的是 1920×1280,也就是 3:2。改写成 `in exactly 16:9 aspect ratio` 后比例就对了: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-image">POST /jobs/image</a></summary> ```bash run bmw-noir.json jobs/image "$(jq -n '{prompt: "In exactly 16:9 aspect ratio (landscape), a cinematic photo of a vintage 1920s black BMW motorcycle with white pinstripes, spoked wheels and a brown leather saddle, parked on wet cobblestones at night in San Francisco, the Golden Gate Bridge glowing through fog in the distance, neo-noir moonlight, reflections on the wet street, shot on 35mm film."}')" download "$(jq -r '.result.assets[0].assetId' bmw-noir.json)" bmw-noir.webp ``` </details> <img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-a5.webp" style="width: 100%" alt="严格 16:9 文生图:旧金山雨夜街头的老式宝马摩托车"> [在新标签页打开](https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-a5.webp){:target="_blank"} Muse 的回复是 "That 16:9 frame with the bridge ghosting through the fog is pure neo-noir. Enjoy.",它的回复在 `result.text` 里。 #### 4. 三张照片合成一张图 一个任务最多接受 9 张图片,参数为 `image_1`..`image_9`,提示词里按名字引用它们。这里摩托车是 `image_1`,骑手是 `image_2`,海滩是 `image_3`。提示词要求 Muse 按原样使用照片里的海滩,所以金门大桥留在照片中原来的位置。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-image">POST /jobs/image</a></summary> ```bash run beach-ride.json jobs/image "$(jq -n --arg bmw "$BMW" --arg rider "$RIDER" --arg beach "$BEACH" \ '{image_1: $bmw, image_2: $rider, image_3: $beach, prompt: "In exactly 16:9 aspect ratio (landscape), a cinematic photo: the woman from image_2 (her face, long wavy red hair, light blue top and jeans) riding the exact vintage motorcycle from image_1 along the shoreline of the beach in image_3, the front wheel cutting through the shallow surf and throwing spray, bright afternoon sun, her hair streaming in the wind, photorealistic. Use the beach, rocks and Golden Gate Bridge from image_3 as the background exactly as photographed: same position, same orientation, not mirrored or redrawn. Keep her face and the motorcycle'\''s design exactly as in the images."}')" BEACH_RIDE=$(jq -r '.result.assets[0].assetId' beach-ride.json) download "$BEACH_RIDE" beach-ride.webp ``` </details> <img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g1.webp" style="width: 100%" alt="骑手、摩托车和海滩合成在一张图里"> [在新标签页打开](https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g1.webp){:target="_blank"} 耗时 31 秒,每周额度没有可见的变化。 #### 5. 把图片做成视频,无需重新上传 `BEACH_RIDE` 是 Muse 生成的文件的 id,它已经在账号的工作区里,所以可以直接作为下一个任务的 `image_1`,不用下载也不用上传。`Animate image_1` 会生成一段以这张图片开头、保持其画幅的视频,引号里的台词会被说出来。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-video">POST /jobs/video</a></summary> ```bash run surf.json jobs/video "$(jq -n --arg img "$BEACH_RIDE" '{image_1: $img, prompt: "Animate image_1 into a cinematic video in exactly 16:9 aspect ratio (landscape): she rides the vintage motorcycle along the shoreline, the front wheel slices through the shallow waves and sends spray flying, the old engine roars, she raises one fist and shouts with a laugh: \"Nothing beats this view!\" The camera tracks alongside her. The beach, the rocks and the Golden Gate Bridge stay exactly as in image_1 (same orientation). Keep her face and the motorcycle exactly as in image_1."}')" SURF=$(jq -r '.result.assets[0].assetId' surf.json) download "$SURF" surf.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g2-poster.jpg" src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g2.mp4" style="width: 100%; aspect-ratio: 16/9; max-width: 720px" controls type="video/mp4" preload="metadata"></video> 10 秒,1280×720,带声音。Muse 的回复是 "Done. 10 seconds, 16:9 landscape, straight from your image — no edits, no upscaling." 这个任务第一次运行时在 37 秒后失败了,Muse 的回答是 "the video worker glitched out before it rendered anything, so no clip was made"。API 把这类回答报告为 `503`,表示什么都没有生成,同样的请求再运行一次就成功了。因内容原因被拒绝则是 `403`,需要换一个提示词。 #### 6. 修复老照片并上色 图片任务也能修复图片。这张老人像是一张褪色的棕褐色照片,685×900 像素,3:4。提示词列出要修复的内容,并坚持保持同样的画面。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-image">POST /jobs/image</a></summary> ```bash run restored.json jobs/image "$(jq -n --arg img "$OLD_PHOTO" '{image_1: $img, prompt: "Restore the old photograph image_1 as a high-quality modern photo: remove the scratches, dust, stains, fading and grain, recover sharp detail in the face, hair and fabric, and colorize it naturally (warm natural skin tones, dark brown hair, ivory tulle shawl, a soft pink rose with green leaves, a muted warm background). Keep the exact same person, expression, pose, framing and crop, and the same portrait aspect ratio as image_1 (3:4, 685×900): do not crop, extend or reframe it."}')" RESTORED=$(jq -r '.result.assets[0].assetId' restored.json) download "$RESTORED" restored.webp ``` </details> <div style="display: flex; flex-wrap: wrap; gap: 8px; align-items: flex-start"> <figure style="margin: 0; width: 48%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-oldphoto.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-oldphoto.jpg" alt="修复前:原图,685×900" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">修复前:原图,685×900</figcaption></figure> <figure style="margin: 0; width: 48%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-e1.webp" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-e1.webp" alt="修复后:修复并上色,1344×1792" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">修复后:修复并上色,1344×1792</figcaption></figure> </div> 结果是 1344×1792,同样的 3:4 画面,尺寸约为原图的两倍,姿势和裁切都没变。Muse 的回复是 "Done — restored, de-grained, and colorized, same framing and pose." #### 7. 让老照片里的人开口说话 修复后的图片直接进入视频任务。视频保持人像的画幅,返回的是 832×1104。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-video">POST /jobs/video</a></summary> ```bash run portrait-video.json jobs/video "$(jq -n --arg img "$RESTORED" '{image_1: $img, prompt: "Animate image_1 into a video with the same portrait frame: the young woman slowly lifts her eyes to the camera, her smile widens, she gently touches the rose on her shoulder and says softly: \"It has been a hundred years... and you still remember me.\" A light breeze moves a few strands of her hair, soft window light, the camera stays still with a very slow push-in. Keep her face exactly as in image_1."}')" download "$(jq -r '.result.assets[0].assetId' portrait-video.json)" portrait.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-e2-poster.jpg" src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-e2.mp4" style="width: 100%; aspect-ratio: 832/1104; max-width: 420px" controls type="video/mp4" preload="metadata"></video> #### 8. 视频换人 视频任务也接受视频作为输入。`video_1` 是第 5 步生成的海边骑行视频,`image_1` 是第二位女士的照片,她留着粉色双丸子头。提示词要求 Muse 替换骑手、其他一切保持不变,并给她一句新台词。 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-video">POST /jobs/video</a></summary> ```bash run swap.json jobs/video "$(jq -n --arg vid "$SURF" --arg img "$PINK" '{video_1: $vid, image_1: $img, prompt: "Edit video_1: replace the rider with the woman from image_1 (her face, pink hair in two buns, colorful makeup and tattoos), and keep everything else the same: the motorcycle, the beach, the waves and spray, the Golden Gate Bridge, the light, the camera move and the timing. Instead of the original line she shouts: \"Catch me if you can, San Francisco!\" Keep the 16:9 frame and the same length."}')" download "$(jq -r '.result.assets[0].assetId' swap.json)" swap.mp4 ``` </details> <div style="display: flex; flex-wrap: wrap; gap: 8px; align-items: flex-start"> <figure style="margin: 0; width: 48%"><video poster="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g2-poster.jpg" src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g2.mp4" style="width: 100%; aspect-ratio: 16/9" controls type="video/mp4" preload="metadata"></video><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">替换前:原来的骑手</figcaption></figure> <figure style="margin: 0; width: 48%"><video poster="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g3-poster.jpg" src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g3.mp4" style="width: 100%; aspect-ratio: 1248/704" controls type="video/mp4" preload="metadata"></video><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">替换后:照片里的骑手</figcaption></figure> </div> 这个任务耗时 138 秒,是整个流程里最慢的一个,这也是本文所有任务都用异步方式运行的原因。成片是同一段骑行,摩托车上换成了另一位女士,喊出新的台词。Muse 的回复是 "Done. She's in, 10 seconds, 16:9, same ride, same bridge, same waves." #### 9. 查看每周额度 [GET /accounts/`email`](/docs/api-muse-v1/get-muse-accounts-email) 实时读取账号的套餐和用量: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/get-muse-accounts-email">GET /accounts/email</a></summary> ```bash get "accounts/$(enc "$EMAIL")" | jq '{session, quota}' ``` </details> `quota.percentUsed` 是本周已用额度的整数百分比,`quota.resetsAt` 是额度重置的时间,即本周期开始后一周。上面三条视频各消耗 2% 到 3%,图片各消耗 0% 或 1%。整个测试过程中(另外还运行了两个本文没有展示的任务),这个免费账号从 16% 用到了 28%。账号额度用完后,不指定 `email` 的新任务会分配到你的其他账号,指定了该账号的任务会返回 `412`,直到 `resetsAt`。 ### 经验总结 - 宽高比写成 `in exactly 16:9 aspect ratio`。`Cinematic 16:9 landscape photo` 曾经返回 3:2。 - 每条视频都是约 10 秒。提示词要求 5 秒,得到的仍是 10 秒。 - 图生视频会保持图片的画幅,除非提示词要求别的比例:`in exactly 9:16 aspect ratio` 把我们 16:9 的海滩图片变成了 720×1280 的竖屏视频,是重新构图,不是拉伸。 - 视频提示词里写在引号中的台词会被说出来。 - 生成的文件用 `assetId` 传给下一个任务。它们保存在账号的工作区里,连续编辑时中间不需要下载。 - 说清楚哪些东西必须保持不变。"Same position, same orientation, not mirrored or redrawn" 让合成图里保留了真实的海滩。 - 返回 `503` 且带有 Muse 自己的话(比如 "glitched out")时,值得再运行一次。`403` 是拒绝,需要换提示词。 - 视频任务用 `async: true` 提交。同步请求最多等待约 100 秒,而换人任务用了 138 秒。 ### 常见问题 - **Meta Muse(muse.ai)有 API 吗?** 通过 useapi.net,有:[Muse API](/docs/api-muse-v1) 在你的 [Muse 网站订阅](https://www.meta.com/help/subscriptions/1021145227643680/)上运行 Muse。用邮箱和密码绑定账号后,用 [POST /jobs/image](/docs/api-muse-v1/post-muse-jobs-image) 生成图片,用 [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video) 生成视频。Meta 官方的 [Model API](https://dev.meta.ai/docs/pricing-rate-limits) 以每张 0.01 美元出售 Muse Image,但截至 2026 年 10 月没有视频生成,也没有 Muse 智能体的 API。各方案对比见 [Is there a Meta Muse video API?](/docs/articles/meta-muse-video-api)(英文)。 - **免费的 Muse 套餐能用吗?** 通过 useapi.net,能:本页所有内容都是在免费套餐(`HATCH_FREE`)上生成的,它有每周额度。一条视频消耗其中 2% 到 3%,一张图片 0% 到 1%。一个账号的额度用完后,不指定 `email` 的新任务会分配到你的其他账号。 - **怎么设置宽高比、时长或分辨率?** 通过 useapi.net,写在提示词里,Muse 没有对应的参数。宽高比写成 `in exactly 16:9 aspect ratio` 时会被遵守,图生视频会保持原图的画幅,除非提示词要求别的比例。视频总是约 10 秒、约 720p,带声音。 - **能用自己的照片和视频吗?** 通过 useapi.net,能:用 [POST /assets](/docs/api-muse-v1/post-muse-assets) 上传,每个文件最大 50 MB,再把 `assetId` 作为 `image_1`..`image_9` 传入,和传入上一个任务的结果一样。[视频任务](/docs/api-muse-v1/post-muse-jobs-video)还可以传 `video_1`..`video_3` 和 `audio_1`..`audio_3`。同一个任务的所有输入必须在同一个账号上。 - **怎么让一张照片开口说话?** 通过 useapi.net,把照片作为 `image_1` 传给 [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video),提示词类似 `Animate image_1: … she says softly: "…"`。Muse 会保持照片的画幅,并说出引号里的台词,见[第 7 步](#step-7):一张修复后的百年老照片里的人抬头开口说话。 - **能替换视频里的人吗?** 通过 useapi.net,能:把视频作为 `video_1`、新人物的照片作为 `image_1` 传入,让 Muse 替换人物、其他保持不变,见[第 8 步](#step-8)。在提示词里写清楚哪些东西必须保持不变,比如骑行、大桥和海浪。如果新人物要说话,就把台词写在引号里。 - **同步请求为什么返回 202?** 通过 useapi.net,`202` 表示任务运行约 100 秒后仍未完成,它会在我们这边继续运行。用 [GET /jobs/`jobid`](/docs/api-muse-v1/get-muse-jobs-jobid) 查询,或者对耗时长的任务用 `async: true` 并轮询,也可以传 `replyUrl`,让完成的任务记录推送给你。本文中一条视频耗时 68 到 138 秒。 - **为什么 Muse 给我发了登录验证码邮件?** 通过 useapi.net,API 登录了你的 Muse 账号:绑定账号时,以及 API 续期 30 天会话时(在会话过期前,或 Muse 要求重新登录时)都会登录。Muse 每次登录都会发验证码邮件,不需要任何操作,见 [Setup Muse](/docs/start-here/setup-muse#what-to-expect)。 - **Muse API 多少钱?** 通过 useapi.net,不按图片或视频收费:任务消耗的是你的 Muse 网站订阅的每周额度,在我们的测试中,一个免费账号每周约可生成 30 到 50 条视频。付费的 Power(每月 20 美元)和 Maximum(每月 100 美元)套餐会提高每周额度(截至 2026 年 10 月)。 - **muse2api 和 useapi.net 有什么区别?** 通过 useapi.net,Muse API 是托管服务,无需部署,账号用邮箱和密码绑定后由我们保持登录。生成结果可以直接作为下一个任务的输入,任务完成后可回调你的 webhook。你还可以通过 API [与 Muse 智能体对话](/docs/api-muse-v1/chat-streaming-guide),回复实时流式返回。[muse2api](https://github.com/czg86389-hub/muse2api) 则是需要你自己部署、托管并持续运维的项目。 ### 结语 有问题欢迎加入我们的 <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord 服务器</a> 或 <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram 频道</a>。 同样的调用也以工具的形式提供在托管的 [Muse MCP 服务器](/docs/api-muse-v1/mcp) 上,可在 Claude Code、Cursor 和 VS Code 中使用。 === URL: https://useapi.net/docs/articles/muse-images-videos-es === Document URL: https://useapi.net/docs/articles/muse-images-videos-es --- layout: default title: "Cómo generar videos e imágenes con IA con la API de Meta Muse" seo_title: "API de Meta Muse: videos con sonido, imágenes y fotos que hablan" description: "Crea videos de Meta Muse de 10 segundos con sonido, e imágenes, con la Muse API de useapi.net: fotos que hablan, imagen a video, cambio de persona y restauración de fotos." keywords: [Muse API, API de Muse, Meta Muse API, API de Meta Muse, Meta Muse video API, generador de video muse ai, meta muse ai video generator, muse ai api, muse ai imagen a video, API de fotos que hablan, talking photo API, API del generador de video de Meta AI, muse.ai API, Meta AI video API, API de imágenes con IA, API de imagen a video, API de restauración de fotos antiguas, API para colorear fotos, cambiar a una persona en un video, face swap de video API, video con IA con diálogo, YouTube Shorts sin rostro API, video narrado con IA, curl] image: https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-cover.jpg parent: Articles nav_exclude: true lang: es date: 2026-10-12 last_modified: 2026-10-30 nav_order: 898 video: name: "Meta Muse API Demo: Images, Talking Photos, Video with Sound, Chat & MCP (third-party, useapi.net)" description: "The third-party Meta Muse API by useapi.net: images, 10-second videos with sound and spoken dialogue, agent chat with live streaming and approvals, and a hosted MCP server, on your Muse website subscription." embed: https://www.youtube.com/embed/OMUGbfRIO5E thumbnail: https://i.ytimg.com/vi/OMUGbfRIO5E/maxresdefault.jpg date: 2026-10-14 duration: PT2M49S width: 1920 height: 1080 repo: https://github.com/useapi/muse-api translation_key: muse --- ## Cómo generar videos e imágenes con IA con la API de Meta Muse {: .no_toc #how-to-generate-ai-videos-and-images-with-the-meta-muse-api } 16 min de lectura • 12 de octubre de 2026 (30 de octubre de 2026) useapi.net es una API de terceros. No está afiliada a Meta ni cuenta con su respaldo. ## Índice {: .no_toc .text-delta #table-of-contents } ### Introducción La [Muse API de useapi.net](/docs/api-muse-v1) controla [Muse](https://muse.ai), el agente personal de IA de Meta, desde código: un POST genera una imagen o un video de 10 segundos con diálogo hablado, y cada archivo que genera es un [asset id](/docs/api-muse-v1/get-muse-assets-assetId) que el siguiente job puede usar como entrada. Muse aquí es el agente de Meta en [muse.ai](https://muse.ai), no Skiv, la empresa de alojamiento de video que usó el nombre muse.ai hasta marzo de 2026. La API está alojada, así que, a diferencia de herramientas que alojas tú, como muse2api, no hay nada que desplegar: la [comparación de API de video de Meta Muse](/docs/articles/meta-muse-video-api) (en inglés) pone lado a lado la API de la propia Meta, muse2api y las API alojadas. La API funciona con tu [suscripción al sitio web de Muse](https://www.meta.com/help/subscriptions/1021145227643680/), y el plan gratuito sirve. Este recorrido toma tres fotos comunes (una motocicleta BMW antigua, una motociclista pelirroja y la playa bajo el Golden Gate) y las convierte en una imagen de ella conduciendo esa motocicleta entre las olas. Esa imagen se convierte después en un video en el que ella grita una frase, y en un tercer job otra mujer, tomada de una cuarta foto, la reemplaza en ese video mientras el paseo sigue igual. Por el camino genera imágenes a partir de texto, y restaura y colorea un retrato de cien años que luego levanta la mirada y habla. Cada solicitud de abajo es la que generó el contenido de esta página. <video poster="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g3-poster.jpg" src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g3.mp4" style="width: 100%; aspect-ratio: 1248/704; max-width: 720px" controls type="video/mp4" preload="metadata"></video> La motociclista de una foto, puesta en un clip que Muse hizo a partir de una imagen fija ([paso 8](#step-8-swap-the-rider-in-the-video)). ### Cuánto costó useapi.net es una API, no un servicio propio de imágenes o videos. Cada llamada se ejecuta en una cuenta de Muse que agregas con [Setup Muse](/docs/start-here/setup-muse), y usa la cuota semanal de Muse de esa cuenta, sin cobro por imagen ni por video de parte de useapi.net. Muse informa la cuota como un porcentaje entero usado, así que una sola imagen a menudo no muestra ningún cambio. Lo que consumió cada paso en el plan gratuito, tomado de `percentUsed` antes y después, y cuánto tardó cada job: | Paso | Endpoint | Resultado | Cuota usada | Tiempo | |---|---|---|--:|--:| | [Texto a imagen, 9:16](#step-3-images-from-text) | [POST /jobs/image](/docs/api-muse-v1/post-muse-jobs-image) | 1152×2048 | no medido | 30 s | | [Texto a imagen, 16:9 exacto](#step-3-images-from-text) | [POST /jobs/image](/docs/api-muse-v1/post-muse-jobs-image) | 2048×1152 | 0% | 21 s | | [Motociclista + motocicleta + playa](#step-4-three-photos-into-one-picture) | [POST /jobs/image](/docs/api-muse-v1/post-muse-jobs-image) | 2048×1152 | 0% | 31 s | | [El paseo en video](#step-5-the-picture-as-a-video-no-re-upload) | [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video) | 1280×720, 10 s | 3% | 88 s | | [Restaurar una foto antigua](#step-6-restore-and-colorize-an-old-photo) | [POST /jobs/image](/docs/api-muse-v1/post-muse-jobs-image) | 1344×1792 | 1% | 34 s | | [El retrato habla](#step-7-the-portrait-comes-to-life) | [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video) | 832×1104, 10 s | 2% | 68 s | | [Cambiar a la motociclista](#step-8-swap-the-rider-in-the-video) | [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video) | 1248×704, 10 s | 3% | 138 s | Las subidas no consumen cuota. En el plan gratuito, un video consumió del 2 al 3 por ciento de la semana y una imagen del 0 al 1 por ciento, así que una cuenta gratuita genera más o menos de 30 a 50 videos por semana, o varios cientos de imágenes ([paso 9](#step-9-check-the-weekly-allowance)). ### Antes de empezar Necesitas un [token de API](/docs/start-here/setup-useapi) de useapi.net y una cuenta de Muse agregada con [Setup Muse](/docs/start-here/setup-muse). Antes de agregar la cuenta: - Muse está disponible en EE. UU., Canadá, [Japón](https://about.fb.com/ja/news/2026/10/muse-personal-ai-agent-launches-in-japan/) y [Singapur](https://about.fb.com/news/2026/10/muse-is-now-available-in-singapore-the-worlds-first-personal-ai-agent-built-for-everyone/) (al 30 de octubre de 2026), así que crea la cuenta en uno de esos países. Una vez agregada, puedes llamar a la API desde cualquier lugar. - Termina el proceso de bienvenida de Muse en [muse.ai](https://muse.ai), incluida la verificación de edad de Meta, y crea una imagen allí. - La cuenta debe poder iniciar sesión con correo y contraseña, porque la API inicia sesión con el correo y la contraseña. Una cuenta de Meta que solo inicia sesión con un código enviado por correo todavía no tiene contraseña: crea una en el [Centro de cuentas de Meta](https://accountscenter.meta.com/password_and_security/) (Contraseña y seguridad) y después agrega la cuenta aquí. Sin contraseña, la cuenta se rechaza con `400`. - Usa la cuenta solo para la API, sin otras herramientas de automatización. Abrirla en muse.ai desde un navegador está bien, pero solo desde EE. UU., Canadá, Japón o Singapur (las regiones donde Muse tiene soporte oficial), o con una VPN en una de ellas: Meta puede desactivar el video de una cuenta que ve usada desde otro lugar. Todas las llamadas están también en la [colección de Postman](/assets/postman/muse-v1.json). Sin código: la plantilla de n8n [Old Photo to Talking Video]({% include n8n-url.html t="muse-photo" %}) restaura una foto y la hace hablar desde un formulario, y la plantilla [Narrated Faceless Shorts]({% include n8n-url.html t="muse-shorts" %}) convierte un tema en un Short narrado. El recorrido completo también está en GitHub como un solo script, en Node.js y Python: [`images-videos/`](https://github.com/useapi/muse-api/tree/main/images-videos) en [useapi/muse-api](https://github.com/useapi/muse-api), además de una [agent skill](https://github.com/useapi/muse-api/tree/main/skills/muse-video) para Claude Code y Codex. Los pasos usan `curl`, `jq` y estas variables y funciones auxiliares: <details markdown="block"> <summary>Abrir las variables y las funciones auxiliares</summary> ```bash export USEAPI_TOKEN="user:12345-..." export EMAIL="example@gmail.com" export MUSE_PASSWORD="..." # la contraseña de la cuenta de Muse, se usa una vez en el paso 1 API=https://api.useapi.net/v1/muse AUTH="Authorization: Bearer $USEAPI_TOKEN" enc() { jq -rn --arg v "$1" '$v|@uri'; } post() { curl -sS -X POST "$API/$1" -H "$AUTH" -H "Content-Type: application/json" -d "$2"; } get() { curl -sS "$API/$1" -H "$AUTH"; } upload() { curl -sS -X POST "$API/assets?email=$(enc "$EMAIL")" -H "$AUTH" -H "Content-Type: $2" --data-binary @"$1" | jq -r .assetId; } download() { curl -sSf "$API/assets/$(enc "$1")" -H "$AUTH" -o "$2"; } # ejecuta un job en modo asíncrono: lo envía, consulta GET /jobs/{jobid} cada 10 s y guarda el registro final del job en $1 run() { local job id job=$(post "$2" "$(jq '. + {async: true}' <<< "$3")") id=$(jq -r .jobid <<< "$job") while [ "$(jq -r .status <<< "$job")" = started ]; do sleep 10 job=$(get "jobs/$(enc "$id")") done echo "$job" > "$1" jq '{status, error, text: .result.text, asset: .result.assets[0].assetId}' "$1" } ``` </details> Cada generación se ejecuta como un job. Sin `async`, un POST espera hasta unos 100 segundos y devuelve el registro del job terminado, o `202` con el job todavía en curso. Un video aquí tardó de 68 a 138 segundos, así que `run` envía cada job con `async: true` y consulta [GET /jobs/`jobid`](/docs/api-muse-v1/get-muse-jobs-jobid). Si `run` muestra cualquier `status` distinto de `completed`, lee su `error` antes de seguir. Para recibir un callback en lugar de consultar, agrega `replyUrl: "https://example.com/hooks/muse"` (y, si quieres, `replyRef`) a cualquier cuerpo de abajo. La API envía entonces un solo `POST` con el registro final del job, en JSON, a esa URL. Los ids contienen `:` y `@`, así que `enc` los codifica para URL cada vez que van en una ruta. Todas las entradas de un job deben estar en la misma cuenta de Muse, así que las subidas fijan `email`, y un job se ejecuta en la cuenta que tiene sus entradas. ### Cómo se hizo #### 1. Agregar la cuenta [POST /accounts](/docs/api-muse-v1/post-muse-accounts) recibe el correo y la contraseña de la cuenta de Muse. La API inicia sesión una vez, conserva la sesión de 30 días y la renueva por su cuenta. Muse envía a la cuenta un código de inicio de sesión por correo en cada inicio de sesión. Ese correo es solo un aviso, no hay que ingresar nada. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-accounts">POST /accounts</a></summary> ```bash post accounts "$(jq -n --arg email "$EMAIL" --arg password "$MUSE_PASSWORD" '{email: $email, password: $password}')" | jq '{health, maxJobs, quota}' ``` </details> La respuesta muestra `health: "OK"`, `maxJobs` (10 por defecto) y el plan y el uso de la cuenta, aquí `tier: "HATCH_FREE"`, el plan gratuito. Si en cambio responde `596`, Meta quiere una verificación de seguridad: inicia sesión una vez en muse.ai desde un navegador, complétala y vuelve a enviar el mismo correo y la misma contraseña. #### 2. Subir las fotos [POST /assets](/docs/api-muse-v1/post-muse-assets) recibe el archivo tal cual como cuerpo, hasta 50 MB, y lo guarda en el espacio de trabajo de Muse de la cuenta. No se guarda nada en useapi.net. El `assetId` de la respuesta es lo que un job recibe como `image_N`. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-assets">POST /assets</a></summary> ```bash BMW=$(upload bmw.jpeg image/jpeg) RIDER=$(upload rider.jpeg image/jpeg) BEACH=$(upload beach.jpeg image/jpeg) OLD_PHOTO=$(upload old-photo.jpeg image/jpeg) PINK=$(upload pink-hair.jpeg image/jpeg) echo "$BMW" # user:12345-email:6578616d706c6540676d61696c2e636f6d-image:7db53e7a1f0979cbab6ff46ec3f0a35b60e6ee579a0d738a9628cf46a0c7a0f5.jpg ``` </details> <div style="display: flex; flex-wrap: wrap; gap: 8px; align-items: flex-start"> <figure style="margin: 0; width: 32%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-motorcycle.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-motorcycle.jpg" alt="<code>image_1</code> — la motocicleta" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em"><code>image_1</code> — la motocicleta</figcaption></figure> <figure style="margin: 0; width: 18%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-redhead.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-redhead.jpg" alt="<code>image_2</code> — la motociclista" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em"><code>image_2</code> — la motociclista</figcaption></figure> <figure style="margin: 0; width: 32%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-beach.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-beach.jpg" alt="<code>image_3</code> — la playa" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em"><code>image_3</code> — la playa</figcaption></figure> <figure style="margin: 0; width: 18%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-oldphoto.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-oldphoto.jpg" alt="el retrato antiguo" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">el retrato antiguo</figcaption></figure> <figure style="margin: 0; width: 18%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-pinkhair.webp" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-pinkhair.webp" alt="la segunda motociclista" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">la segunda motociclista</figcaption></figure> </div> Las cinco entradas: la motocicleta, la motociclista, la playa, el retrato antiguo y la segunda motociclista. El asset id se calcula a partir del contenido del archivo, así que volver a subir el mismo archivo a la misma cuenta devuelve el mismo id y no guarda nada. #### 3. Imágenes a partir de texto Muse no tiene un parámetro de relación de aspecto: lo dice el prompt. Primero, un retrato vertical: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-image">POST /jobs/image</a></summary> ```bash run portrait.json jobs/image "$(jq -n '{prompt: "Vertical 9:16 full-body portrait photo: a confident young woman biker with long wavy fiery red hair, green eyes and freckles, in a worn black leather jacket, dark jeans and boots, standing in a rain-soaked neon alley at dusk, looking straight at the camera, cinematic lighting, photorealistic."}')" download "$(jq -r '.result.assets[0].assetId' portrait.json)" portrait.webp ``` </details> <img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-a2.webp" style="width: 100%; max-width: 420px" alt="Texto a imagen en 9:16"> [abrir en una pestaña nueva](https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-a2.webp){:target="_blank"} Llegó exactamente en 9:16, 1152×2048. Una versión horizontal pedida como `Cinematic 16:9 landscape photo: …` llegó en 1920×1280, que es 3:2. Escribir la relación como `in exactly 16:9 aspect ratio` lo resolvió: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-image">POST /jobs/image</a></summary> ```bash run bmw-noir.json jobs/image "$(jq -n '{prompt: "In exactly 16:9 aspect ratio (landscape), a cinematic photo of a vintage 1920s black BMW motorcycle with white pinstripes, spoked wheels and a brown leather saddle, parked on wet cobblestones at night in San Francisco, the Golden Gate Bridge glowing through fog in the distance, neo-noir moonlight, reflections on the wet street, shot on 35mm film."}')" download "$(jq -r '.result.assets[0].assetId' bmw-noir.json)" bmw-noir.webp ``` </details> <img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-a5.webp" style="width: 100%" alt="Texto a imagen en 16:9 exacto"> [abrir en una pestaña nueva](https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-a5.webp){:target="_blank"} Muse respondió "That 16:9 frame with the bridge ghosting through the fog is pure neo-noir. Enjoy." Su respuesta está en `result.text`. #### 4. Tres fotos en una sola imagen En un job entran hasta 9 imágenes como `image_1`..`image_9`, y el prompt las nombra. Aquí la motocicleta es `image_1`, la motociclista `image_2` y la playa `image_3`. El prompt le pide a Muse que use la playa fotografiada tal como es, así que el Golden Gate se queda donde estaba en la foto. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-image">POST /jobs/image</a></summary> ```bash run beach-ride.json jobs/image "$(jq -n --arg bmw "$BMW" --arg rider "$RIDER" --arg beach "$BEACH" \ '{image_1: $bmw, image_2: $rider, image_3: $beach, prompt: "In exactly 16:9 aspect ratio (landscape), a cinematic photo: the woman from image_2 (her face, long wavy red hair, light blue top and jeans) riding the exact vintage motorcycle from image_1 along the shoreline of the beach in image_3, the front wheel cutting through the shallow surf and throwing spray, bright afternoon sun, her hair streaming in the wind, photorealistic. Use the beach, rocks and Golden Gate Bridge from image_3 as the background exactly as photographed: same position, same orientation, not mirrored or redrawn. Keep her face and the motorcycle'\''s design exactly as in the images."}')" BEACH_RIDE=$(jq -r '.result.assets[0].assetId' beach-ride.json) download "$BEACH_RIDE" beach-ride.webp ``` </details> <img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g1.webp" style="width: 100%" alt="La motociclista, la motocicleta y la playa en una sola imagen"> [abrir en una pestaña nueva](https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g1.webp){:target="_blank"} 31 segundos, y ningún cambio visible en la cuota semanal. #### 5. La imagen se vuelve video, sin volver a subirla `BEACH_RIDE` es el id de un archivo que hizo Muse. Ya está en el espacio de trabajo de la cuenta, así que entra directo en el siguiente job como `image_1`, sin descargarlo ni subirlo. `Animate image_1` genera un clip que parte de la imagen y conserva su formato, y la frase entre comillas se dice en voz alta. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-video">POST /jobs/video</a></summary> ```bash run surf.json jobs/video "$(jq -n --arg img "$BEACH_RIDE" '{image_1: $img, prompt: "Animate image_1 into a cinematic video in exactly 16:9 aspect ratio (landscape): she rides the vintage motorcycle along the shoreline, the front wheel slices through the shallow waves and sends spray flying, the old engine roars, she raises one fist and shouts with a laugh: \"Nothing beats this view!\" The camera tracks alongside her. The beach, the rocks and the Golden Gate Bridge stay exactly as in image_1 (same orientation). Keep her face and the motorcycle exactly as in image_1."}')" SURF=$(jq -r '.result.assets[0].assetId' surf.json) download "$SURF" surf.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g2-poster.jpg" src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g2.mp4" style="width: 100%; aspect-ratio: 16/9; max-width: 720px" controls type="video/mp4" preload="metadata"></video> También en YouTube: [3 photos in, 1 talking video out: Meta Muse API from REST](https://youtube.com/shorts/v_7mREyFSWk). 10 segundos en 1280×720, con sonido. Muse dijo "Done. 10 seconds, 16:9 landscape, straight from your image — no edits, no upscaling." El primer intento de este mismo job falló a los 37 segundos: Muse respondió que "the video worker glitched out before it rendered anything, so no clip was made". La API informa una respuesta así como `503`, sin nada generado, y la misma solicitud funcionó al ejecutarla otra vez. Un rechazo por el contenido es un `403`, y necesita otro prompt. #### 6. Restaurar y colorear una foto antigua Un job de imagen también puede reparar una imagen. El retrato antiguo es una foto sepia desteñida de 685×900 píxeles, 3:4. El prompt enumera lo que hay que arreglar e insiste en el mismo encuadre. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-image">POST /jobs/image</a></summary> ```bash run restored.json jobs/image "$(jq -n --arg img "$OLD_PHOTO" '{image_1: $img, prompt: "Restore the old photograph image_1 as a high-quality modern photo: remove the scratches, dust, stains, fading and grain, recover sharp detail in the face, hair and fabric, and colorize it naturally (warm natural skin tones, dark brown hair, ivory tulle shawl, a soft pink rose with green leaves, a muted warm background). Keep the exact same person, expression, pose, framing and crop, and the same portrait aspect ratio as image_1 (3:4, 685×900): do not crop, extend or reframe it."}')" RESTORED=$(jq -r '.result.assets[0].assetId' restored.json) download "$RESTORED" restored.webp ``` </details> <div style="display: flex; flex-wrap: wrap; gap: 8px; align-items: flex-start"> <figure style="margin: 0; width: 48%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-oldphoto.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-oldphoto.jpg" alt="Antes: el original, 685×900" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">Antes: el original, 685×900</figcaption></figure> <figure style="margin: 0; width: 48%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-e1.webp" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-e1.webp" alt="Después: restaurada y coloreada, 1344×1792" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">Después: restaurada y coloreada, 1344×1792</figcaption></figure> </div> El resultado mide 1344×1792, el mismo encuadre 3:4 a cerca del doble de tamaño, con la misma pose y el mismo recorte. Muse dijo "Done — restored, de-grained, and colorized, same framing and pose." #### 7. El retrato cobra vida La imagen restaurada entra directo en un job de video. El clip conserva el formato del retrato, así que llegó en 832×1104. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-video">POST /jobs/video</a></summary> ```bash run portrait-video.json jobs/video "$(jq -n --arg img "$RESTORED" '{image_1: $img, prompt: "Animate image_1 into a video with the same portrait frame: the young woman slowly lifts her eyes to the camera, her smile widens, she gently touches the rose on her shoulder and says softly: \"It has been a hundred years... and you still remember me.\" A light breeze moves a few strands of her hair, soft window light, the camera stays still with a very slow push-in. Keep her face exactly as in image_1."}')" download "$(jq -r '.result.assets[0].assetId' portrait-video.json)" portrait.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-e2-poster.jpg" src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-e2.mp4" style="width: 100%; aspect-ratio: 832/1104; max-width: 420px" controls type="video/mp4" preload="metadata"></video> También en YouTube: [This old portrait just spoke: one API call (Meta Muse API, third-party)](https://youtube.com/shorts/GLHoINX_ozE). #### 8. Cambiar a la motociclista del video Un job de video también recibe videos. `video_1` es el clip de las olas del paso 5, e `image_1` es la foto de una segunda mujer con el pelo rosa recogido en dos moños. El prompt le pide a Muse que reemplace a la motociclista y conserve todo lo demás, y le da una frase nueva. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-video">POST /jobs/video</a></summary> ```bash run swap.json jobs/video "$(jq -n --arg vid "$SURF" --arg img "$PINK" '{video_1: $vid, image_1: $img, prompt: "Edit video_1: replace the rider with the woman from image_1 (her face, pink hair in two buns, colorful makeup and tattoos), and keep everything else the same: the motorcycle, the beach, the waves and spray, the Golden Gate Bridge, the light, the camera move and the timing. Instead of the original line she shouts: \"Catch me if you can, San Francisco!\" Keep the 16:9 frame and the same length."}')" download "$(jq -r '.result.assets[0].assetId' swap.json)" swap.mp4 ``` </details> <div style="display: flex; flex-wrap: wrap; gap: 8px; align-items: flex-start"> <figure style="margin: 0; width: 48%"><video poster="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g2-poster.jpg" src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g2.mp4" style="width: 100%; aspect-ratio: 16/9" controls type="video/mp4" preload="metadata"></video><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">Antes: la motociclista original</figcaption></figure> <figure style="margin: 0; width: 48%"><video poster="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g3-poster.jpg" src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g3.mp4" style="width: 100%; aspect-ratio: 1248/704" controls type="video/mp4" preload="metadata"></video><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">Después: la motociclista de la foto</figcaption></figure> </div> Con 138 segundos, este fue el job más lento del recorrido, y por eso cada job aquí se ejecuta en modo asíncrono. El clip es el mismo paseo con la otra mujer en la motocicleta, gritando la frase nueva. Muse dijo "Done. She's in, 10 seconds, 16:9, same ride, same bridge, same waves." También en YouTube: [Replace the person in a video, keep everything else: Meta Muse API](https://youtube.com/shorts/XDCY1XIsd5Y). #### 9. Revisar la cuota semanal [GET /accounts/`email`](/docs/api-muse-v1/get-muse-accounts-email) lee en vivo el plan y el uso de la cuenta: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/get-muse-accounts-email">GET /accounts/email</a></summary> ```bash get "accounts/$(enc "$EMAIL")" | jq '{session, quota}' ``` </details> `quota.percentUsed` es la parte de la semana ya usada, en porcentaje entero, y `quota.resetsAt` es cuándo vuelve a empezar, una semana después de su inicio. Los tres videos de arriba consumieron del 2 al 3 por ciento cada uno y las imágenes 0 o 1. En toda la sesión de pruebas, que también ejecutó dos jobs que no aparecen aquí, la cuenta gratuita pasó del 16 al 28 por ciento. Cuando una cuenta se queda sin cuota, los jobs nuevos sin `email` van a tus otras cuentas, y un job fijado a ella responde `412` hasta `resetsAt`. ### Lo que aprendimos - Escribe la relación de aspecto como `in exactly 16:9 aspect ratio`. `Cinematic 16:9 landscape photo` llegó una vez en 3:2. - Cada video dura unos 10 segundos. Un prompt que pedía 5 segundos igual recibió 10. - Un clip de imagen a video conserva el formato de su imagen salvo que el prompt pida otro: `in exactly 9:16 aspect ratio` convirtió nuestra imagen 16:9 de la playa en un clip vertical de 720×1280, reencuadrado en lugar de estirado. - Las frases escritas entre comillas en un prompt de video se dicen en voz alta. - Pasa los archivos generados por su `assetId`. Se quedan en el espacio de trabajo de la cuenta, así que una cadena de ediciones no necesita descargas intermedias. - Di lo que debe seguir igual. "Same position, same orientation, not mirrored or redrawn" conservó la playa real en la composición. - Vale la pena volver a ejecutar un `503` con palabras de Muse como "glitched out". Un `403` es un rechazo y necesita otro prompt. - Envía los videos con `async: true`. Una solicitud síncrona espera unos 100 segundos, y el cambio de persona tardó 138. ### Haz un Short narrado de 30 segundos (guion, tres escenas, una unión) Un video de Muse siempre dura unos 10 segundos, así que un Short vertical de 30 segundos con narrador necesita tres jobs de video y dos chats. Un [chat](/docs/api-muse-v1/post-muse-chats) escribe el guion en JSON, tres [jobs de video](/docs/api-muse-v1/post-muse-jobs-video) se ejecutan en paralelo, uno por escena, cada uno diciendo su frase con la voz del mismo narrador, y un último chat une los clips con ffmpeg en el propio espacio de trabajo de la cuenta. El Short de abajo, sobre la erupción del monte Tambora en 1815 y el "año sin verano" que le siguió, pasó de un tema de una línea a un MP4 en unos 2 minutos. <video poster="https://media.useapi.net/articles/2026-10-12-muse-images-videos-id/muse-narrated-short-tambora-poster.jpg" src="https://media.useapi.net/articles/2026-10-12-muse-images-videos-id/muse-narrated-short-tambora.mp4" style="width: 100%; aspect-ratio: 9/16; max-width: 420px" controls type="video/mp4" preload="metadata"></video> También en YouTube: [A narrated 30-second Short made only with Meta Muse API calls](https://youtube.com/shorts/1e8f7dHTkzs). Tres clips de 10 segundos unidos en un Short de 720×1280 y 30 segundos, a partir del tema "how a single volcano cooled the whole planet in 1816". El guion tardó 11 segundos, los tres clips 75, 75 y 87 segundos ejecutándose a la vez, y la unión 20 segundos, así que un Short tarda unos 2 a 3 minutos. Este se hizo con un plan de pago de Muse. Ahí, los cuatro videos de esa sesión de pruebas (estos tres y uno más) movieron la lectura semanal 2 puntos en total, y los chats ninguno. En el plan gratuito un video consume del 2 al 3 por ciento de la semana, así que un Short de tres escenas cuesta allí entre un 6 y un 9 por ciento. Sin código: el mismo flujo es una app de n8n, la plantilla [Narrated Faceless Shorts]({% include n8n-url.html t="muse-shorts" %}), con un formulario, una página de guion y guardado en Google Drive. Dos Shorts que hizo, publicados tal como salieron: [The Great Pyramid was once bright white](https://youtube.com/shorts/D-Nk0x9aJMo) y [Why honey never spoils](https://youtube.com/shorts/bYLsJIqerSM), que narró con el texto a voz de Muse. El flujo completo también es un solo script, en Node.js y Python: [`narrated-short/`](https://github.com/useapi/muse-api/tree/main/narrated-short) en [useapi/muse-api](https://github.com/useapi/muse-api). Recibe un tema y, opcionalmente, el número de escenas y tu propia descripción del narrador, y guarda el Short en `output/`. Los pasos usan las [funciones auxiliares de arriba](#before-you-start) más `chat`, que inicia un chat y lee [GET /chats/`chatId`](/docs/api-muse-v1/get-muse-chats-chatId) hasta que Muse termina: <details markdown="block"> <summary>Abrir la función auxiliar de chat</summary> ```bash # inicia un chat, consulta GET /chats/{chatId} cada 8 s hasta que Muse termine y guarda el chat en $1 chat() { local id c id=$(post chats "$2" | jq -r .chatId) while sleep 8; do c=$(get "chats/$(enc "$id")") jq -e '.pendingApprovals | length > 0' <<< "$c" > /dev/null && echo "Muse asks for permission: answer it with POST /chats/{chatId}/approvals/{approvalId}" jq -e '(.status | IN("completed", "interrupted", "failed")) and (.pendingApprovals | length == 0)' <<< "$c" > /dev/null && break done echo "$c" > "$1" jq '{status, reply: ([.messages[] | select(.role == "assistant" and .text != "")][-1].text)}' "$1" } ``` </details> Cada solicitud de abajo fija `email`. Un chat que recibe archivos debe ejecutarse en la cuenta que los tiene, así que los tres clips y la unión se quedan en una sola cuenta. #### 1. Escribir el guion en JSON El primer chat pide exactamente tres escenas y detalla la forma del JSON. Cada escena tiene una `line`, lo que dice el narrador, limitada a 25 palabras para que quepa en 10 segundos, y un `visual`, una frase que describe la toma. El prompt también le dice a Muse que no cree ningún archivo, así que el chat se queda en texto. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-chats">POST /chats</a></summary> ```bash TOPIC="how a single volcano cooled the whole planet in 1816" chat script.json "$(jq -n --arg email "$EMAIL" --arg topic "$TOPIC" '{email: $email, message: "Write a script for a 30-second faceless YouTube Short about: \"\($topic)\". Exactly 3 scenes. Reply with ONLY a JSON object, no prose, no markdown code fences, in this exact shape: {\"title\": string, \"scenes\": [{\"line\": string, \"visual\": string}, {\"line\": string, \"visual\": string}, {\"line\": string, \"visual\": string}]}. \"line\" is what the off-screen narrator says (at most 25 words, about 9 seconds spoken). \"visual\" is a one-sentence description of the 10-second shot, no people talking on camera. Do not create any files, images or videos."}')" jq -r '[.messages[] | select(.role == "assistant" and .text != "")][-1].text' script.json | sed '/^```/d' > scenes.json jq . scenes.json ``` </details> Muse respondió en 11 segundos solo con el JSON: ```json { "title": "How One Volcano Cooled the Whole Planet in 1816", "scenes": [ { "line": "In April 1815, Mount Tambora in Indonesia erupted, the largest explosion in recorded history, blasting ash forty kilometers into the sky.", "visual": "A massive volcanic eruption at dawn, with a towering ash column rising into the stratosphere above a dark island." }, { "line": "That ash veil circled Earth, blocking sunlight and dropping global temperatures, turning summer into winter across North America and Europe.", "visual": "An animated globe wrapped in a gray haze as sunlight dims and frost spreads across continents." }, { "line": "1816 became the Year Without a Summer: crops failed, snow fell in July, and famine spread as the planet shivered.", "visual": "Snow falling over green farmland in summer, covering withered crops and empty village fields under a pale sun." } ] } ``` Ejecutamos el mismo prompt con tres temas y obtuvimos un JSON limpio cada vez, en 11 a 29 segundos, sin bloques de código y sin texto extra. Es una muestra pequeña, así que el `sed` quita de todos modos una línea suelta de cierre ```` ``` ````, y el script de GitHub vuelve a pedirlo cuando la respuesta no se puede analizar. #### 2. Tres escenas a la vez Cada escena se convierte en un [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video) asíncrono. Los tres prompts llevan la misma descripción del narrador, palabra por palabra, seguida de `The narrator says exactly: "<line>"`. Muse dice una frase entre comillas tal como está escrita, y la descripción compartida mantiene la voz constante de un clip a otro. `Vertical 9:16 video` llegó en 720×1280. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-video">POST /jobs/video</a></summary> ```bash NARRATOR="Narration: one off-screen narrator only, the same voice throughout: a calm, deep, middle-aged British male documentary narrator, measured pace, warm and authoritative, like a nature documentary. Nobody on screen speaks. No music." for i in 0 1 2; do post jobs/video "$(jq --arg email "$EMAIL" --arg narrator "$NARRATOR" --argjson i $i '.scenes[$i] | {email: $email, async: true, prompt: "Vertical 9:16 video, about 10 seconds. \(.visual) Slow cinematic camera move, photoreal. \($narrator) The narrator says exactly: \"\(.line)\""}' scenes.json)" | jq -r .jobid done > jobs.txt ``` </details> Cada POST responde `201` al instante con un `jobid`. Los tres jobs ocupan tres de los espacios `maxJobs` de la cuenta (10 por defecto), así que se ejecutan en paralelo. Un `429` aquí significa que todos los espacios están ocupados y no se inició nada: vuelve a enviar ese job en 30 segundos. #### 3. Consultar los jobs [GET /jobs/`jobid`](/docs/api-muse-v1/get-muse-jobs-jobid) responde `status: "started"` hasta que el clip está listo. Los jobs corren en paralelo, así que leerlos uno tras otro no agrega tiempo: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/get-muse-jobs-jobid">GET /jobs/jobid</a></summary> ```bash for n in 1 2 3; do id=$(sed -n "${n}p" jobs.txt) until job=$(get "jobs/$(enc "$id")"); [ "$(jq -r .status <<< "$job")" != started ]; do sleep 10; done echo "$job" > clip$n.json jq '{status, error, text: .result.text, asset: .result.assets[0].assetId}' clip$n.json done ``` </details> Los tres terminaron. Sobre el primero, Muse dijo "Here it is — vertical 9:16, photoreal volcanic eruption at dawn with the narration as specified". Cada clip dice su frase palabra por palabra, y cada frase, de 20 a 21 palabras, cupo en sus 10 segundos. Un job que falló con `503` no generó nada y se puede volver a ejecutar. Cualquier otro fallo, como un rechazo `403`, requiere revisar primero `error.message`. #### 4. Unir los clips en un chat Los ids de los tres clips entran en un solo chat como `files`, donde Muse los ve como `video_1`, `video_2` y `video_3`. El mensaje pide ffmpeg, el orden, el audio y un nombre de archivo, y termina con `No public links.` Con esa línea, Muse no se detuvo a pedir permiso. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-chats">POST /chats</a></summary> ```bash CLIPS=$(jq -s '[.[].result.assets[0].assetId]' clip1.json clip2.json clip3.json) chat join.json "$(jq -n --arg email "$EMAIL" --argjson files "$CLIPS" '{email: $email, files: $files, message: "Concatenate video_1, video_2, video_3 in order into one MP4 with ffmpeg, keep the audio, save it to workspace/your_files/short.mp4 and attach it here. No public links."}')" SHORT=$(jq -r '[.messages[] | select(.role == "assistant") | .files[] | select(.type == "video")][-1].assetId' join.json) echo "$SHORT" # user:12345-email:6578616d706c6540676d61696c2e636f6d-video:ws~your_files~short.mp4 ``` </details> 20 segundos después Muse dijo "Concatenated all three in order — 30 seconds, 720x1280, with audio kept." y adjuntó el archivo en un mensaje propio, con un `video` en sus `files`. Su asset id lleva el nombre de la ruta en el espacio de trabajo, así que dale a cada Short su propio nombre de archivo. ffmpeg copió las pistas sin volver a codificarlas: el Short dura exactamente 30,0 segundos, y las tres frases están en él, en orden. #### 5. Descargar el Short [GET /assets/`assetId`](/docs/api-muse-v1/get-muse-assets-assetId) devuelve el MP4: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/get-muse-assets-assetId">GET /assets/assetId</a></summary> ```bash download "$SHORT" tambora-short.mp4 ``` </details> Los clips y el Short también se quedan en el espacio de trabajo de Muse de la cuenta, donde los muestra la app de muse.ai, y el asset id del Short puede entrar en el siguiente job como `video_1`. #### Una voz fija: texto a voz como audio_1 Una descripción compartida da el mismo tipo de voz, no una voz fija. En los tres clips de Tambora, el tono mediano del narrador fue de 105 a 117 Hz, a menos de dos semitonos de distancia, pero Muse vuelve a crear la voz en cada clip. Para tener con seguridad una sola voz, haz que Muse diga primero cada frase con su texto a voz y luego pasa ese MP3 al job de video como `audio_1`. El chat de texto a voz tardó 20 segundos en nuestra prueba. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-chats">POST /chats</a> y <a href="/docs/api-muse-v1/post-muse-jobs-video">POST /jobs/video</a></summary> ```bash chat voice1.json "$(jq -n --arg email "$EMAIL" --arg line "$(jq -r '.scenes[0].line' scenes.json)" '{email: $email, message: "Generate one mp3 file with text to speech: single speaker, voice Aria (avocado_v2:MAI_01), speed 100, language en, clean narration only: no music, no sound effects. Read exactly this text, do not change any word:\n\"\($line)\"\nSave it directly in workspace/your_files/ (not in a subfolder) as line-1.mp3 and attach it here. No public links and no uploads to remote storage."}')" VOICE1=$(jq -r '[.messages[] | select(.role == "assistant") | .files[] | select(.type == "audio")][-1].assetId' voice1.json) run clip1.json jobs/video "$(jq --arg email "$EMAIL" --arg voice "$VOICE1" '.scenes[0] | {email: $email, audio_1: $voice, prompt: "Vertical 9:16 video, about 10 seconds, no people on screen and nobody speaking on camera. \(.visual) Slow cinematic camera move, photoreal. Use audio_1 as the narration soundtrack exactly as it is: the off-screen narrator'\''s voice in audio_1, word for word, with no other voice and no new speech. Quiet ambient sound under it is fine."}' scenes.json)" jq -r '.result.assets[] | select(.origin == "made") | .assetId' clip1.json ``` </details> Muse genera su clip y luego le pone `audio_1` encima con ffmpeg. El job lista los dos archivos: primero la copia terminada, con `origin: "made"`, y después el clip original de Muse, con `origin: "generated"`. Toma el `made`. El clip original lleva una voz que Muse inventó en lugar de la tuya. El job de video tardó 108 segundos en nuestra prueba. Repítelo para cada escena y une los clips `made` como en el paso 4. ### Preguntas frecuentes **¿Existe una API para Meta Muse (muse.ai)?** Con useapi.net, sí: la [Muse API](/docs/api-muse-v1) es una API de terceros que ejecuta Muse con tu [suscripción al sitio web de Muse](https://www.meta.com/help/subscriptions/1021145227643680/). Genera imágenes con [POST /jobs/image](/docs/api-muse-v1/post-muse-jobs-image) y videos con [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video). La [Model API](https://dev.meta.ai/docs/pricing-rate-limits) oficial de Meta vende el modelo Muse Image a US$0,01 por imagen, pero, a octubre de 2026, no tiene generación de video ni una API para el agente Muse de muse.ai, donde se hacen los videos. Nuestra [comparación de API de video de Meta Muse](/docs/articles/meta-muse-video-api) (en inglés) también cubre muse2api. **¿Funciona con el plan gratuito de Muse?** Con useapi.net, sí: este recorrido se hizo con el plan gratuito (`HATCH_FREE`), que tiene una cuota semanal. Un video consumió del 2 al 3 por ciento de ella y una imagen del 0 al 1 por ciento, así que una cuenta gratuita genera más o menos de 30 a 50 videos por semana. Los planes de pago Power (US$20 al mes) y Maximum (US$100 al mes) aumentan la cuota (a octubre de 2026). **¿Muse puede hacer un video de más de 10 segundos?** Con useapi.net, no en un solo job: cada video dura unos 10 segundos. Genera un clip por escena y haz que un [chat](/docs/api-muse-v1/post-muse-chats) los una con ffmpeg, como en [Haz un Short narrado de 30 segundos](#make-a-30-second-narrated-short-script-three-scenes-one-join), donde tres clips se convirtieron en un Short en unos 2 a 3 minutos. Un chat recibe hasta 3 videos. **¿Cómo defino la relación de aspecto, la duración o la resolución?** Con useapi.net, en el prompt, porque Muse no tiene parámetros para eso. La relación de aspecto se respeta cuando se escribe como `in exactly 16:9 aspect ratio`, y un clip de imagen a video conserva el formato de su imagen salvo que el prompt pida otro. La duración y la resolución son fijas: cada video llega en unos 720p con sonido, pida lo que pida el prompt. **¿Puedo usar mis propias fotos y videos?** Con useapi.net, sí: súbelos con [POST /assets](/docs/api-muse-v1/post-muse-assets), hasta 50 MB cada uno, y pasa el `assetId` como `image_1`..`image_9`, igual que pasas el resultado de un job anterior. Los [jobs de video](/docs/api-muse-v1/post-muse-jobs-video) también reciben `video_1`..`video_3` y `audio_1`..`audio_3`. Todas las entradas de un job deben estar en la misma cuenta. **¿Cómo hago que una foto hable?** Con useapi.net, pasa la foto como `image_1` a [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video) con un prompt como `Animate image_1: … she says softly: "…"`. Muse conserva el formato de la foto y dice la frase entre comillas, como en el [paso 7](#step-7-the-portrait-comes-to-life), donde un retrato restaurado de cien años levanta la mirada y habla. **¿Puede reemplazar a una persona en un video?** Con useapi.net, sí: pasa el clip como `video_1` y una foto de la nueva persona como `image_1`, y pídele a Muse que reemplace a la persona y conserve todo lo demás, como en el [paso 8](#step-8-swap-the-rider-in-the-video). Di lo que debe seguir igual, como el paseo, el puente y las olas, y dale a la nueva persona una frase entre comillas si debe hablar. **¿Por qué mi solicitud síncrona devolvió 202?** Con useapi.net, un `202` significa que el job seguía en curso después de unos 100 segundos, y sigue ejecutándose de nuestro lado. Consúltalo con [GET /jobs/`jobid`](/docs/api-muse-v1/get-muse-jobs-jobid), envía los jobs largos con `async: true` y consulta, o agrega un `replyUrl` para que te envíen el registro del job terminado. En nuestras pruebas, un video tardó de 68 a 138 segundos. **¿Por qué Muse me envió un código de inicio de sesión por correo?** Con useapi.net, la API inició sesión en tu cuenta de Muse, lo que ocurre cuando la agregas y cuando la API renueva la sesión de 30 días, antes de que venza o cada vez que Muse pide un nuevo inicio de sesión. Muse envía un código por correo en cada inicio de sesión, y no hay que hacer nada con él. Consulta [Setup Muse](/docs/start-here/setup-muse#what-to-expect). **¿En qué se diferencia de muse2api?** Con useapi.net, la Muse API está alojada, así que no hay nada que desplegar: agregas cada cuenta con su correo y contraseña y nosotros mantenemos la sesión iniciada. Los resultados se encadenan por asset id, y un job terminado puede llamar a tu webhook. También puedes [chatear con el agente Muse](/docs/api-muse-v1/chat-streaming-guide), con sus respuestas transmitidas en vivo. [muse2api](https://github.com/czg86389-hub/muse2api) es un proyecto que despliegas, alojas y mantienes en marcha tú mismo. ### Conclusión Visita nuestro <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> servidor de Discord</a> o nuestro <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> canal de Telegram</a> para cualquier pregunta de soporte. Consulta nuestro [repositorio de GitHub](https://github.com/useapi/muse-api) con ejemplos de código. Las mismas llamadas están disponibles como herramientas en el [servidor MCP de Muse](/docs/api-muse-v1/mcp) alojado, para Claude Code, Cursor y VS Code. #### Publicado también en {: .no_toc #cross-posted } También publicado en [dev.to](https://dev.to/useapi/how-to-generate-ai-images-and-videos-with-the-muse-api-274){:rel="nofollow"}, comentado en [Reddit](https://www.reddit.com/r/ThirdPartyAPI/comments/1x3udcd/how_to_generate_ai_images_and_videos_with_the/){:rel="nofollow"}, compartido en [Bluesky](https://bsky.app/profile/useapi.net/post/3mxnuj43mcs2w){:rel="nofollow"} y en YouTube como una [demo de 2:49 de toda la API](https://www.youtube.com/watch?v=OMUGbfRIO5E) (todos en inglés). ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/muse-images-videos-id === Document URL: https://useapi.net/docs/articles/muse-images-videos-id --- layout: default title: "Cara Membuat Video dan Gambar AI dengan Meta Muse API" seo_title: "Meta Muse API: Video AI 10 Detik Bersuara dan Gambar lewat REST" description: "Buat video Meta Muse 10 detik bersuara dan gambar lewat Muse API useapi.net: foto yang berbicara, gambar ke video, ganti orang di video, restorasi foto lama." keywords: [Muse API, API Muse, Meta Muse API, API Meta Muse, Meta Muse video API, muse ai video generator, meta muse ai video generator, muse ai api, muse ai image to video, API foto berbicara, talking photo API, Meta AI video generator API, muse.ai API, Meta AI video API, API gambar AI, AI image API, API gambar ke video, image to video API, restorasi foto lama, old photo restoration API, mewarnai foto lama, photo colorization API, ganti wajah di video, video face swap API, replace person in video, video AI dengan dialog, faceless YouTube Shorts API, video AI dengan narasi, tutorial bahasa Indonesia, curl] image: https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-cover.jpg parent: Articles nav_exclude: true lang: id translation_key: muse date: 2026-10-12 last_modified: 2026-10-30 nav_order: 898 video: name: "Meta Muse API Demo: Images, Talking Photos, Video with Sound, Chat & MCP (third-party, useapi.net)" description: "The third-party Meta Muse API by useapi.net: images, 10-second videos with sound and spoken dialogue, agent chat with live streaming and approvals, and a hosted MCP server, on your Muse website subscription." embed: https://www.youtube.com/embed/OMUGbfRIO5E thumbnail: https://i.ytimg.com/vi/OMUGbfRIO5E/maxresdefault.jpg date: 2026-10-14 duration: PT2M49S width: 1920 height: 1080 repo: https://github.com/useapi/muse-api --- ## Cara Membuat Video dan Gambar AI dengan Meta Muse API {: .no_toc #how-to-generate-ai-videos-and-images-with-the-meta-muse-api } 16 menit baca • 12 Oktober 2026 (30 Oktober 2026) useapi.net adalah API pihak ketiga. Kami tidak berafiliasi dengan Meta dan tidak disahkan oleh Meta. ## Daftar isi {: .no_toc .text-delta #table-of-contents } ### Pendahuluan [Muse API dari useapi.net](/docs/api-muse-v1) menjalankan [Muse](https://muse.ai), agen AI pribadi milik Meta, dari kode: satu POST membuat gambar atau video 10 detik dengan dialog lisan, dan setiap file yang dibuatnya adalah [asset id](/docs/api-muse-v1/get-muse-assets-assetId) yang bisa dipakai job berikutnya sebagai input. Muse di sini adalah agen Meta di [muse.ai](https://muse.ai), bukan Skiv, perusahaan hosting video yang memakai nama muse.ai sampai Maret 2026. API ini di-hosting, jadi tidak seperti tools self-hosted seperti muse2api, tidak ada yang perlu di-deploy: [perbandingan Meta Muse video API](/docs/articles/meta-muse-video-api) (bahasa Inggris) menyandingkan API milik Meta, muse2api dan API yang di-hosting. API ini berjalan di [langganan situs Muse](https://www.meta.com/help/subscriptions/1021145227643680/) Anda, dan paket gratisnya pun bisa. Panduan ini mengambil tiga foto biasa, sebuah motor BMW klasik, seorang pengendara berambut merah, dan pantai di bawah Golden Gate Bridge, lalu menggabungkannya menjadi satu gambar sang pengendara melaju dengan motor itu menembus ombak. Gambar itu lalu menjadi video tempat dia meneriakkan sebuah kalimat, dan di job ketiga seorang perempuan lain, dari foto keempat, menggantikannya di video itu sementara perjalanannya tetap sama. Di sepanjang jalan, panduan ini membuat gambar dari teks, serta merestorasi dan mewarnai potret berusia seratus tahun yang kemudian mengangkat pandangannya dan berbicara. Setiap request di bawah adalah request yang membuat media di halaman ini. <video poster="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g3-poster.jpg" src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g3.mp4" style="width: 100%; aspect-ratio: 1248/704; max-width: 720px" controls type="video/mp4" preload="metadata"></video> Pengendara dari sebuah foto, dimasukkan ke klip yang dibuat Muse dari gambar diam ([langkah 8](#step-8-swap-the-rider-in-the-video)). ### Biayanya useapi.net adalah API, bukan layanan gambar atau video tersendiri. Setiap panggilan berjalan di akun Muse yang Anda tambahkan lewat [Setup Muse](/docs/start-here/setup-muse), dan memakai kuota mingguan Muse akun itu, tanpa biaya per gambar atau per video dari useapi.net. Muse melaporkan kuota sebagai persentase bulat yang sudah terpakai, jadi satu gambar sering tidak menunjukkan perubahan. Yang dipakai setiap langkah di paket gratis, diambil dari `percentUsed` sebelum dan sesudahnya, dan berapa lama setiap job berjalan: | Langkah | Endpoint | Hasil | Kuota terpakai | Waktu | |---|---|---|--:|--:| | [Teks ke gambar, 9:16](#step-3-images-from-text) | [POST /jobs/image](/docs/api-muse-v1/post-muse-jobs-image) | 1152×2048 | tidak diukur | 30 s | | [Teks ke gambar, tepat 16:9](#step-3-images-from-text) | [POST /jobs/image](/docs/api-muse-v1/post-muse-jobs-image) | 2048×1152 | 0% | 21 s | | [Pengendara + motor + pantai](#step-4-three-photos-into-one-picture) | [POST /jobs/image](/docs/api-muse-v1/post-muse-jobs-image) | 2048×1152 | 0% | 31 s | | [Perjalanan sebagai video](#step-5-the-picture-as-a-video-no-re-upload) | [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video) | 1280×720, 10 s | 3% | 88 s | | [Restorasi foto lama](#step-6-restore-and-colorize-an-old-photo) | [POST /jobs/image](/docs/api-muse-v1/post-muse-jobs-image) | 1344×1792 | 1% | 34 s | | [Potret yang berbicara](#step-7-the-portrait-comes-to-life) | [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video) | 832×1104, 10 s | 2% | 68 s | | [Ganti pengendara](#step-8-swap-the-rider-in-the-video) | [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video) | 1248×704, 10 s | 3% | 138 s | Upload tidak memakai kuota. Di paket gratis, satu video memakai 2 sampai 3 persen dari kuota mingguan dan satu gambar 0 sampai 1 persen, jadi satu akun gratis membuat sekitar 30 sampai 50 video per minggu, atau beberapa ratus gambar ([langkah 9](#step-9-check-the-weekly-allowance)). ### Sebelum mulai Anda butuh [API token](/docs/start-here/setup-useapi) useapi.net dan akun Muse yang ditambahkan lewat [Setup Muse](/docs/start-here/setup-muse). Sebelum menambahkan akun: - Muse tersedia di AS, Kanada, [Jepang](https://about.fb.com/ja/news/2026/10/muse-personal-ai-agent-launches-in-japan/) dan [Singapura](https://about.fb.com/news/2026/10/muse-is-now-available-in-singapore-the-worlds-first-personal-ai-agent-built-for-everyone/) (per 30 Oktober 2026), jadi buat akunnya di salah satu negara itu. Setelah akun ditambahkan, Anda bisa memanggil API dari mana saja. - Selesaikan onboarding Muse di [muse.ai](https://muse.ai), termasuk pemeriksaan usia dari Meta, dan buat satu gambar di sana. - Akun harus bisa masuk dengan email + password, karena API masuk dengan email dan password. Akun Meta yang hanya masuk dengan kode lewat email belum punya password: buat password di [Meta Accounts Center](https://accountscenter.meta.com/password_and_security/) (Password and security), lalu tambahkan akunnya di sini. Tanpa password, penambahan akun ditolak dengan `400`. - Pakai akun itu hanya untuk API, tanpa tools otomasi lain. Membukanya di muse.ai lewat browser tidak masalah, tetapi hanya dari AS, Kanada, Jepang atau Singapura (wilayah yang resmi didukung Muse), atau lewat VPN di salah satu wilayah itu: Meta bisa mematikan fitur video untuk akun yang terlihat dipakai dari tempat lain. Setiap panggilan juga ada di [koleksi Postman](/assets/postman/muse-v1.json). Tanpa kode: template n8n [Old Photo to Talking Video]({% include n8n-url.html t="muse-photo" %}) merestorasi foto dan membuatnya berbicara dari sebuah formulir, dan template [Narrated Faceless Shorts]({% include n8n-url.html t="muse-shorts" %}) mengubah sebuah topik menjadi Short bernarasi. Seluruh panduan ini juga ada di GitHub sebagai satu skrip, dalam Node.js dan Python: [`images-videos/`](https://github.com/useapi/muse-api/tree/main/images-videos) di [useapi/muse-api](https://github.com/useapi/muse-api), ditambah [agent skill](https://github.com/useapi/muse-api/tree/main/skills/muse-video) untuk Claude Code dan Codex. Langkah-langkahnya memakai `curl`, `jq`, serta variabel dan helper berikut: <details markdown="block"> <summary>Buka variabel dan helper</summary> ```bash export USEAPI_TOKEN="user:12345-..." export EMAIL="example@gmail.com" export MUSE_PASSWORD="..." # password akun Muse, dipakai sekali di langkah 1 API=https://api.useapi.net/v1/muse AUTH="Authorization: Bearer $USEAPI_TOKEN" enc() { jq -rn --arg v "$1" '$v|@uri'; } post() { curl -sS -X POST "$API/$1" -H "$AUTH" -H "Content-Type: application/json" -d "$2"; } get() { curl -sS "$API/$1" -H "$AUTH"; } upload() { curl -sS -X POST "$API/assets?email=$(enc "$EMAIL")" -H "$AUTH" -H "Content-Type: $2" --data-binary @"$1" | jq -r .assetId; } download() { curl -sSf "$API/assets/$(enc "$1")" -H "$AUTH" -o "$2"; } # jalankan job secara async: kirim, polling GET /jobs/{jobid} setiap 10 detik, simpan record job terakhir ke $1 run() { local job id job=$(post "$2" "$(jq '. + {async: true}' <<< "$3")") id=$(jq -r .jobid <<< "$job") while [ "$(jq -r .status <<< "$job")" = started ]; do sleep 10 job=$(get "jobs/$(enc "$id")") done echo "$job" > "$1" jq '{status, error, text: .result.text, asset: .result.assets[0].assetId}' "$1" } ``` </details> Setiap generate berjalan sebagai job. Tanpa `async`, POST menunggu hingga sekitar 100 detik dan mengembalikan record job yang sudah selesai, atau `202` jika job masih berjalan. Satu video di sini butuh 68 sampai 138 detik, jadi `run` mengirim setiap job dengan `async: true` dan melakukan polling ke [GET /jobs/`jobid`](/docs/api-muse-v1/get-muse-jobs-jobid). Jika `run` mencetak `status` selain `completed`, baca `error`-nya sebelum melanjutkan. Untuk dipanggil balik alih-alih polling, tambahkan `replyUrl: "https://example.com/hooks/muse"` (dan, jika perlu, `replyRef`) ke body mana pun di bawah. API lalu mengirim satu `POST` berisi record job terakhir, dalam JSON, ke URL itu. Id berisi `:` dan `@`, jadi `enc` meng-encode-nya sebagai URL setiap kali id masuk ke path URL. Semua input untuk satu job harus berada di akun Muse yang sama, jadi upload menetapkan `email`, dan job berjalan di akun yang menyimpan input-nya. ### Cara membuatnya #### 1. Tambahkan akun [POST /accounts](/docs/api-muse-v1/post-muse-accounts) menerima email dan password akun Muse. API masuk sekali, menyimpan sesi 30 hari dan memperbaruinya sendiri. Muse mengirim kode login ke email akun setiap kali masuk. Email itu hanya pemberitahuan, tidak ada yang perlu dimasukkan. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-accounts">POST /accounts</a></summary> ```bash post accounts "$(jq -n --arg email "$EMAIL" --arg password "$MUSE_PASSWORD" '{email: $email, password: $password}')" | jq '{health, maxJobs, quota}' ``` </details> Jawabannya menunjukkan `health: "OK"`, `maxJobs` (default 10), serta paket dan pemakaian akun, di sini `tier: "HATCH_FREE"`, paket gratis. Jika yang muncul justru `596`, Meta meminta pemeriksaan keamanan: masuk sekali di muse.ai lewat browser, selesaikan pemeriksaannya, lalu kirim lagi email dan password yang sama. #### 2. Upload foto [POST /assets](/docs/api-muse-v1/post-muse-assets) menerima file mentah sebagai body, hingga 50 MB, dan menuliskannya ke workspace Muse akun itu. Tidak ada yang disimpan di useapi.net. `assetId` di jawabannya adalah yang diterima job sebagai `image_N`. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-assets">POST /assets</a></summary> ```bash BMW=$(upload bmw.jpeg image/jpeg) RIDER=$(upload rider.jpeg image/jpeg) BEACH=$(upload beach.jpeg image/jpeg) OLD_PHOTO=$(upload old-photo.jpeg image/jpeg) PINK=$(upload pink-hair.jpeg image/jpeg) echo "$BMW" # user:12345-email:6578616d706c6540676d61696c2e636f6d-image:7db53e7a1f0979cbab6ff46ec3f0a35b60e6ee579a0d738a9628cf46a0c7a0f5.jpg ``` </details> <div style="display: flex; flex-wrap: wrap; gap: 8px; align-items: flex-start"> <figure style="margin: 0; width: 32%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-motorcycle.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-motorcycle.jpg" alt="<code>image_1</code> — motor" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em"><code>image_1</code> — motor</figcaption></figure> <figure style="margin: 0; width: 18%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-redhead.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-redhead.jpg" alt="<code>image_2</code> — pengendara" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em"><code>image_2</code> — pengendara</figcaption></figure> <figure style="margin: 0; width: 32%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-beach.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-beach.jpg" alt="<code>image_3</code> — pantai" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em"><code>image_3</code> — pantai</figcaption></figure> <figure style="margin: 0; width: 18%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-oldphoto.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-oldphoto.jpg" alt="potret lama" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">potret lama</figcaption></figure> <figure style="margin: 0; width: 18%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-pinkhair.webp" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-pinkhair.webp" alt="pengendara kedua" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">pengendara kedua</figcaption></figure> </div> Lima input: motor, pengendara, pantai, potret lama dan pengendara kedua. Asset id dibentuk dari isi file, jadi meng-upload file yang sama ke akun yang sama sekali lagi mengembalikan id yang sama dan tidak menulis apa pun. #### 3. Gambar dari teks Muse tidak punya parameter rasio aspek: prompt yang menyebutkannya. Pertama, potret vertikal: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-image">POST /jobs/image</a></summary> ```bash run portrait.json jobs/image "$(jq -n '{prompt: "Vertical 9:16 full-body portrait photo: a confident young woman biker with long wavy fiery red hair, green eyes and freckles, in a worn black leather jacket, dark jeans and boots, standing in a rain-soaked neon alley at dusk, looking straight at the camera, cinematic lighting, photorealistic."}')" download "$(jq -r '.result.assets[0].assetId' portrait.json)" portrait.webp ``` </details> <img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-a2.webp" style="width: 100%; max-width: 420px" alt="Teks ke gambar dalam 9:16"> [buka di tab baru](https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-a2.webp){:target="_blank"} Hasilnya tepat 9:16, 1152×2048. Versi lanskap yang diminta sebagai `Cinematic 16:9 landscape photo: …` kembali dalam 1920×1280, yang berarti 3:2. Menulis rasionya sebagai `in exactly 16:9 aspect ratio` memperbaikinya: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-image">POST /jobs/image</a></summary> ```bash run bmw-noir.json jobs/image "$(jq -n '{prompt: "In exactly 16:9 aspect ratio (landscape), a cinematic photo of a vintage 1920s black BMW motorcycle with white pinstripes, spoked wheels and a brown leather saddle, parked on wet cobblestones at night in San Francisco, the Golden Gate Bridge glowing through fog in the distance, neo-noir moonlight, reflections on the wet street, shot on 35mm film."}')" download "$(jq -r '.result.assets[0].assetId' bmw-noir.json)" bmw-noir.webp ``` </details> <img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-a5.webp" style="width: 100%" alt="Teks ke gambar tepat 16:9"> [buka di tab baru](https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-a5.webp){:target="_blank"} Muse menjawab "That 16:9 frame with the bridge ghosting through the fog is pure neo-noir. Enjoy." Balasannya ada di `result.text`. #### 4. Tiga foto menjadi satu gambar Hingga 9 gambar bisa masuk ke satu job sebagai `image_1`..`image_9`, dan prompt menyebut nama mereka. Di sini motornya `image_1`, pengendaranya `image_2`, dan pantainya `image_3`. Prompt meminta Muse memakai pantai di foto apa adanya, sehingga Golden Gate Bridge tetap berada di posisi yang sama seperti di foto. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-image">POST /jobs/image</a></summary> ```bash run beach-ride.json jobs/image "$(jq -n --arg bmw "$BMW" --arg rider "$RIDER" --arg beach "$BEACH" \ '{image_1: $bmw, image_2: $rider, image_3: $beach, prompt: "In exactly 16:9 aspect ratio (landscape), a cinematic photo: the woman from image_2 (her face, long wavy red hair, light blue top and jeans) riding the exact vintage motorcycle from image_1 along the shoreline of the beach in image_3, the front wheel cutting through the shallow surf and throwing spray, bright afternoon sun, her hair streaming in the wind, photorealistic. Use the beach, rocks and Golden Gate Bridge from image_3 as the background exactly as photographed: same position, same orientation, not mirrored or redrawn. Keep her face and the motorcycle'\''s design exactly as in the images."}')" BEACH_RIDE=$(jq -r '.result.assets[0].assetId' beach-ride.json) download "$BEACH_RIDE" beach-ride.webp ``` </details> <img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g1.webp" style="width: 100%" alt="Pengendara, motor dan pantai dalam satu gambar"> [buka di tab baru](https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g1.webp){:target="_blank"} 31 detik, dan tidak ada perubahan yang terlihat di kuota mingguan. #### 5. Gambar menjadi video, tanpa upload ulang `BEACH_RIDE` adalah id file buatan Muse. File itu sudah ada di workspace akun, jadi langsung masuk ke job berikutnya sebagai `image_1`, tanpa unduh dan tanpa upload. `Animate image_1` membuat klip yang dimulai dari gambar itu dan mempertahankan bentuknya, dan kalimat dalam tanda kutip diucapkan. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-video">POST /jobs/video</a></summary> ```bash run surf.json jobs/video "$(jq -n --arg img "$BEACH_RIDE" '{image_1: $img, prompt: "Animate image_1 into a cinematic video in exactly 16:9 aspect ratio (landscape): she rides the vintage motorcycle along the shoreline, the front wheel slices through the shallow waves and sends spray flying, the old engine roars, she raises one fist and shouts with a laugh: \"Nothing beats this view!\" The camera tracks alongside her. The beach, the rocks and the Golden Gate Bridge stay exactly as in image_1 (same orientation). Keep her face and the motorcycle exactly as in image_1."}')" SURF=$(jq -r '.result.assets[0].assetId' surf.json) download "$SURF" surf.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g2-poster.jpg" src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g2.mp4" style="width: 100%; aspect-ratio: 16/9; max-width: 720px" controls type="video/mp4" preload="metadata"></video> Juga di YouTube: [3 photos in, 1 talking video out: Meta Muse API from REST](https://youtube.com/shorts/v_7mREyFSWk). 10 detik dalam 1280×720 dengan suara. Muse berkata "Done. 10 seconds, 16:9 landscape, straight from your image — no edits, no upscaling." Percobaan pertama job ini gagal setelah 37 detik: Muse menjawab bahwa "the video worker glitched out before it rendered anything, so no clip was made". API melaporkan jawaban seperti itu sebagai `503`, tidak ada yang dibuat, dan request yang sama berhasil saat dijalankan lagi. Penolakan karena konten adalah `403`, dan butuh prompt yang berbeda. #### 6. Restorasi dan pewarnaan foto lama Job gambar juga bisa memperbaiki gambar. Potret lama ini adalah foto sepia pudar berukuran 685×900 piksel, 3:4. Prompt mendaftar apa yang perlu diperbaiki dan menegaskan bingkai yang sama. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-image">POST /jobs/image</a></summary> ```bash run restored.json jobs/image "$(jq -n --arg img "$OLD_PHOTO" '{image_1: $img, prompt: "Restore the old photograph image_1 as a high-quality modern photo: remove the scratches, dust, stains, fading and grain, recover sharp detail in the face, hair and fabric, and colorize it naturally (warm natural skin tones, dark brown hair, ivory tulle shawl, a soft pink rose with green leaves, a muted warm background). Keep the exact same person, expression, pose, framing and crop, and the same portrait aspect ratio as image_1 (3:4, 685×900): do not crop, extend or reframe it."}')" RESTORED=$(jq -r '.result.assets[0].assetId' restored.json) download "$RESTORED" restored.webp ``` </details> <div style="display: flex; flex-wrap: wrap; gap: 8px; align-items: flex-start"> <figure style="margin: 0; width: 48%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-oldphoto.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-oldphoto.jpg" alt="Sebelum: foto asli, 685×900" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">Sebelum: foto asli, 685×900</figcaption></figure> <figure style="margin: 0; width: 48%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-e1.webp" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-e1.webp" alt="Sesudah: direstorasi dan diwarnai, 1344×1792" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">Sesudah: direstorasi dan diwarnai, 1344×1792</figcaption></figure> </div> Hasilnya 1344×1792, bingkai 3:4 yang sama dengan ukuran sekitar dua kali lipat, dengan pose dan potongan yang sama. Muse berkata "Done — restored, de-grained, and colorized, same framing and pose." #### 7. Potret menjadi hidup Gambar hasil restorasi langsung masuk ke job video. Klip mempertahankan bentuk potret, jadi hasilnya 832×1104. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-video">POST /jobs/video</a></summary> ```bash run portrait-video.json jobs/video "$(jq -n --arg img "$RESTORED" '{image_1: $img, prompt: "Animate image_1 into a video with the same portrait frame: the young woman slowly lifts her eyes to the camera, her smile widens, she gently touches the rose on her shoulder and says softly: \"It has been a hundred years... and you still remember me.\" A light breeze moves a few strands of her hair, soft window light, the camera stays still with a very slow push-in. Keep her face exactly as in image_1."}')" download "$(jq -r '.result.assets[0].assetId' portrait-video.json)" portrait.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-e2-poster.jpg" src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-e2.mp4" style="width: 100%; aspect-ratio: 832/1104; max-width: 420px" controls type="video/mp4" preload="metadata"></video> Juga di YouTube: [This old portrait just spoke: one API call (Meta Muse API, third-party)](https://youtube.com/shorts/GLHoINX_ozE). #### 8. Ganti pengendara di video Job video juga menerima video. `video_1` adalah klip ombak dari langkah 5, dan `image_1` adalah foto perempuan kedua berambut merah muda dengan dua cepol. Prompt meminta Muse mengganti pengendara dan mempertahankan semua yang lain, serta memberinya kalimat baru. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-video">POST /jobs/video</a></summary> ```bash run swap.json jobs/video "$(jq -n --arg vid "$SURF" --arg img "$PINK" '{video_1: $vid, image_1: $img, prompt: "Edit video_1: replace the rider with the woman from image_1 (her face, pink hair in two buns, colorful makeup and tattoos), and keep everything else the same: the motorcycle, the beach, the waves and spray, the Golden Gate Bridge, the light, the camera move and the timing. Instead of the original line she shouts: \"Catch me if you can, San Francisco!\" Keep the 16:9 frame and the same length."}')" download "$(jq -r '.result.assets[0].assetId' swap.json)" swap.mp4 ``` </details> <div style="display: flex; flex-wrap: wrap; gap: 8px; align-items: flex-start"> <figure style="margin: 0; width: 48%"><video poster="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g2-poster.jpg" src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g2.mp4" style="width: 100%; aspect-ratio: 16/9" controls type="video/mp4" preload="metadata"></video><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">Sebelum: pengendara asli</figcaption></figure> <figure style="margin: 0; width: 48%"><video poster="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g3-poster.jpg" src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g3.mp4" style="width: 100%; aspect-ratio: 1248/704" controls type="video/mp4" preload="metadata"></video><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">Sesudah: pengendara dari foto</figcaption></figure> </div> Dengan 138 detik, ini job paling lambat di panduan ini, dan karena itulah setiap job di sini berjalan async. Klipnya adalah perjalanan yang sama dengan perempuan lain di atas motor, meneriakkan kalimat baru. Muse berkata "Done. She's in, 10 seconds, 16:9, same ride, same bridge, same waves." Juga di YouTube: [Replace the person in a video, keep everything else: Meta Muse API](https://youtube.com/shorts/XDCY1XIsd5Y). #### 9. Cek kuota mingguan [GET /accounts/`email`](/docs/api-muse-v1/get-muse-accounts-email) membaca paket dan pemakaian akun secara langsung: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/get-muse-accounts-email">GET /accounts/email</a></summary> ```bash get "accounts/$(enc "$EMAIL")" | jq '{session, quota}' ``` </details> `quota.percentUsed` adalah bagian minggu yang sudah terpakai, dalam persen bulat, dan `quota.resetsAt` adalah waktu kuota dimulai ulang, seminggu setelah dimulai. Tiga video di atas masing-masing memakai 2 sampai 3 persen dan gambarnya 0 atau 1. Selama seluruh sesi uji, yang juga menjalankan dua job yang tidak ditampilkan di sini, akun gratis naik dari 16 ke 28 persen. Ketika kuota akun habis, job baru tanpa `email` diarahkan ke akun Anda yang lain, dan job yang dikunci ke akun itu dijawab `412` sampai `resetsAt`. ### Yang kami pelajari - Tulis rasio aspek sebagai `in exactly 16:9 aspect ratio`. `Cinematic 16:9 landscape photo` sekali kembali sebagai 3:2. - Setiap video sekitar 10 detik. Prompt yang meminta 5 detik tetap mendapat 10. - Klip image-to-video mempertahankan bentuk gambarnya kecuali prompt meminta bentuk lain: `in exactly 9:16 aspect ratio` mengubah gambar pantai 16:9 kami menjadi klip vertikal 720×1280, dibingkai ulang, bukan ditarik. - Kalimat yang ditulis dalam tanda kutip di prompt video akan diucapkan. - Teruskan file hasil generate lewat `assetId`. File itu tetap di workspace akun, jadi rangkaian edit tidak butuh unduhan di antaranya. - Sebutkan apa yang harus tetap sama. "Same position, same orientation, not mirrored or redrawn" mempertahankan pantai asli di gambar gabungan. - `503` dengan kata-kata Muse sendiri seperti "glitched out" layak dijalankan lagi. `403` adalah penolakan dan butuh prompt yang berbeda. - Kirim video dengan `async: true`. Request sync menunggu sekitar 100 detik, sedangkan penggantian pengendara butuh 138. ### Membuat Short 30 detik bernarasi (skrip, tiga adegan, satu penggabungan) Video Muse selalu sekitar 10 detik, jadi Short vertikal 30 detik dengan narator butuh tiga job video dan dua chat. Satu [chat](/docs/api-muse-v1/post-muse-chats) menulis skrip dalam JSON, tiga [job video](/docs/api-muse-v1/post-muse-jobs-video) berjalan berdampingan, satu per adegan, masing-masing mengucapkan kalimatnya dengan suara narator yang sama, dan chat terakhir menggabungkan klip-klip itu dengan ffmpeg di workspace akun itu sendiri. Short di bawah, tentang letusan Gunung Tambora tahun 1815 dan "tahun tanpa musim panas" sesudahnya, berubah dari topik satu baris menjadi MP4 dalam sekitar 2 menit. <video poster="https://media.useapi.net/articles/2026-10-12-muse-images-videos-id/muse-narrated-short-tambora-poster.jpg" src="https://media.useapi.net/articles/2026-10-12-muse-images-videos-id/muse-narrated-short-tambora.mp4" style="width: 100%; aspect-ratio: 9/16; max-width: 420px" controls type="video/mp4" preload="metadata"></video> Juga di YouTube: [A narrated 30-second Short made only with Meta Muse API calls](https://youtube.com/shorts/1e8f7dHTkzs). Tiga klip 10 detik yang digabung menjadi satu Short 720×1280 berdurasi 30 detik, dari topik "how a single volcano cooled the whole planet in 1816". Skripnya butuh 11 detik, ketiga klip 75, 75 dan 87 detik yang berjalan bersamaan, dan penggabungannya 20 detik, jadi satu Short butuh sekitar 2 sampai 3 menit. Short ini dibuat di paket Muse berbayar. Di sana, empat video dalam sesi uji itu (tiga ini dan satu lagi) menggeser angka mingguan total 2 poin, dan chat tidak menggesernya sama sekali. Di paket gratis satu video memakai 2 sampai 3 persen dari kuota mingguan, jadi Short tiga adegan berbiaya sekitar 6 sampai 9 persen di sana. Tanpa kode: alur yang sama tersedia sebagai aplikasi n8n, template [Narrated Faceless Shorts]({% include n8n-url.html t="muse-shorts" %}), dengan formulir, halaman skrip, dan penyimpanan ke Google Drive. Dua Short buatannya, dipublikasikan apa adanya: [The Great Pyramid was once bright white](https://youtube.com/shorts/D-Nk0x9aJMo) dan [Why honey never spoils](https://youtube.com/shorts/bYLsJIqerSM), yang disuarakan dengan text to speech Muse. Seluruh alur ini juga ada sebagai satu skrip, dalam Node.js dan Python: [`narrated-short/`](https://github.com/useapi/muse-api/tree/main/narrated-short) di [useapi/muse-api](https://github.com/useapi/muse-api). Skrip ini menerima topik, dan jika perlu jumlah adegan serta deskripsi narator Anda sendiri, lalu menyimpan Short-nya ke `output/`. Langkah-langkahnya memakai [helper di atas](#before-you-start) ditambah `chat`, yang memulai chat dan membaca [GET /chats/`chatId`](/docs/api-muse-v1/get-muse-chats-chatId) sampai Muse selesai: <details markdown="block"> <summary>Buka helper chat</summary> ```bash # mulai chat, polling GET /chats/{chatId} setiap 8 detik sampai Muse selesai, simpan chat ke $1 chat() { local id c id=$(post chats "$2" | jq -r .chatId) while sleep 8; do c=$(get "chats/$(enc "$id")") jq -e '.pendingApprovals | length > 0' <<< "$c" > /dev/null && echo "Muse asks for permission: answer it with POST /chats/{chatId}/approvals/{approvalId}" jq -e '(.status | IN("completed", "interrupted", "failed")) and (.pendingApprovals | length == 0)' <<< "$c" > /dev/null && break done echo "$c" > "$1" jq '{status, reply: ([.messages[] | select(.role == "assistant" and .text != "")][-1].text)}' "$1" } ``` </details> Setiap request di bawah menetapkan `email`. Chat yang menerima file harus berjalan di akun yang menyimpan file itu, jadi ketiga klip dan penggabungannya tetap di satu akun. #### 1. Tulis skrip dalam JSON Chat pertama meminta tepat tiga adegan dan merinci bentuk JSON-nya. Setiap adegan punya `line`, yang diucapkan narator, dibatasi 25 kata supaya muat dalam 10 detik, dan `visual`, satu kalimat yang menggambarkan shot-nya. Prompt juga meminta Muse untuk tidak membuat file apa pun, jadi chat tetap berisi teks saja. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-chats">POST /chats</a></summary> ```bash TOPIC="how a single volcano cooled the whole planet in 1816" chat script.json "$(jq -n --arg email "$EMAIL" --arg topic "$TOPIC" '{email: $email, message: "Write a script for a 30-second faceless YouTube Short about: \"\($topic)\". Exactly 3 scenes. Reply with ONLY a JSON object, no prose, no markdown code fences, in this exact shape: {\"title\": string, \"scenes\": [{\"line\": string, \"visual\": string}, {\"line\": string, \"visual\": string}, {\"line\": string, \"visual\": string}]}. \"line\" is what the off-screen narrator says (at most 25 words, about 9 seconds spoken). \"visual\" is a one-sentence description of the 10-second shot, no people talking on camera. Do not create any files, images or videos."}')" jq -r '[.messages[] | select(.role == "assistant" and .text != "")][-1].text' script.json | sed '/^```/d' > scenes.json jq . scenes.json ``` </details> Muse menjawab dalam 11 detik dengan JSON saja: ```json { "title": "How One Volcano Cooled the Whole Planet in 1816", "scenes": [ { "line": "In April 1815, Mount Tambora in Indonesia erupted, the largest explosion in recorded history, blasting ash forty kilometers into the sky.", "visual": "A massive volcanic eruption at dawn, with a towering ash column rising into the stratosphere above a dark island." }, { "line": "That ash veil circled Earth, blocking sunlight and dropping global temperatures, turning summer into winter across North America and Europe.", "visual": "An animated globe wrapped in a gray haze as sunlight dims and frost spreads across continents." }, { "line": "1816 became the Year Without a Summer: crops failed, snow fell in July, and famine spread as the planet shivered.", "visual": "Snow falling over green farmland in summer, covering withered crops and empty village fields under a pale sun." } ] } ``` Kami menjalankan prompt yang sama untuk tiga topik dan selalu mendapat JSON yang bersih, dalam 11 sampai 29 detik, tanpa code fence dan tanpa teks tambahan. Itu sampel kecil, jadi `sed` tetap membuang baris fence ```` ``` ```` yang nyasar, dan skrip di GitHub meminta sekali lagi jika balasannya tidak bisa di-parse. #### 2. Tiga adegan sekaligus Setiap adegan menjadi satu [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video) async. Ketiga prompt membawa deskripsi narator yang sama, kata demi kata, diikuti `The narrator says exactly: "<line>"`. Muse mengucapkan kalimat dalam tanda kutip persis seperti yang ditulis, dan deskripsi yang sama menjaga suara tetap konsisten dari klip ke klip. `Vertical 9:16 video` kembali dalam 720×1280. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-video">POST /jobs/video</a></summary> ```bash NARRATOR="Narration: one off-screen narrator only, the same voice throughout: a calm, deep, middle-aged British male documentary narrator, measured pace, warm and authoritative, like a nature documentary. Nobody on screen speaks. No music." for i in 0 1 2; do post jobs/video "$(jq --arg email "$EMAIL" --arg narrator "$NARRATOR" --argjson i $i '.scenes[$i] | {email: $email, async: true, prompt: "Vertical 9:16 video, about 10 seconds. \(.visual) Slow cinematic camera move, photoreal. \($narrator) The narrator says exactly: \"\(.line)\""}' scenes.json)" | jq -r .jobid done > jobs.txt ``` </details> Setiap POST langsung menjawab `201` dengan `jobid`. Ketiga job memakai tiga slot `maxJobs` akun (default 10), jadi semuanya berjalan berdampingan. `429` di sini berarti semua slot sedang terpakai dan tidak ada yang dimulai: kirim ulang job itu dalam 30 detik. #### 3. Polling job [GET /jobs/`jobid`](/docs/api-muse-v1/get-muse-jobs-jobid) menjawab `status: "started"` sampai klipnya siap. Job berjalan paralel, jadi membacanya satu per satu tidak menambah waktu: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/get-muse-jobs-jobid">GET /jobs/jobid</a></summary> ```bash for n in 1 2 3; do id=$(sed -n "${n}p" jobs.txt) until job=$(get "jobs/$(enc "$id")"); [ "$(jq -r .status <<< "$job")" != started ]; do sleep 10; done echo "$job" > clip$n.json jq '{status, error, text: .result.text, asset: .result.assets[0].assetId}' clip$n.json done ``` </details> Ketiganya selesai. Tentang klip pertama Muse berkata "Here it is — vertical 9:16, photoreal volcanic eruption at dawn with the narration as specified". Setiap klip mengucapkan kalimatnya kata demi kata, dan setiap kalimat, sepanjang 20 sampai 21 kata, muat dalam 10 detiknya. Job yang gagal dengan `503` tidak membuat apa pun dan bisa dijalankan lagi. Kegagalan lain, seperti penolakan `403`, perlu dicek dulu di `error.message`. #### 4. Gabungkan klip dalam satu chat Ketiga id klip masuk ke satu chat sebagai `files`, dan di sana Muse melihatnya sebagai `video_1`, `video_2` dan `video_3`. Pesannya meminta ffmpeg, urutan, audio dan nama file, lalu diakhiri dengan `No public links.` Dengan baris itu, Muse tidak berhenti untuk meminta izin. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-chats">POST /chats</a></summary> ```bash CLIPS=$(jq -s '[.[].result.assets[0].assetId]' clip1.json clip2.json clip3.json) chat join.json "$(jq -n --arg email "$EMAIL" --argjson files "$CLIPS" '{email: $email, files: $files, message: "Concatenate video_1, video_2, video_3 in order into one MP4 with ffmpeg, keep the audio, save it to workspace/your_files/short.mp4 and attach it here. No public links."}')" SHORT=$(jq -r '[.messages[] | select(.role == "assistant") | .files[] | select(.type == "video")][-1].assetId' join.json) echo "$SHORT" # user:12345-email:6578616d706c6540676d61696c2e636f6d-video:ws~your_files~short.mp4 ``` </details> 20 detik kemudian Muse berkata "Concatenated all three in order — 30 seconds, 720x1280, with audio kept." dan melampirkan file itu sebagai pesan tersendiri, satu `video` di `files`-nya. Asset id-nya dinamai menurut path workspace, jadi beri setiap Short nama file sendiri. ffmpeg menyalin stream tanpa meng-encode ulang: Short-nya tepat 30,0 detik, dan ketiga kalimat ada di dalamnya, berurutan. #### 5. Unduh Short-nya [GET /assets/`assetId`](/docs/api-muse-v1/get-muse-assets-assetId) mengembalikan MP4: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/get-muse-assets-assetId">GET /assets/assetId</a></summary> ```bash download "$SHORT" tambora-short.mp4 ``` </details> Klip dan Short-nya juga tetap tersimpan di workspace Muse akun, tempat aplikasi muse.ai menampilkannya, dan asset id Short bisa masuk ke job berikutnya sebagai `video_1`. #### Suara yang tetap: text to speech sebagai audio_1 Deskripsi yang sama memberi jenis suara yang sama, bukan suara yang terkunci. Di tiga klip Tambora, nada median narator 105 sampai 117 Hz, berselisih kurang dari dua semitone, tetapi Muse menyuarakan setiap klip dari awal. Untuk satu suara yang pasti sama, minta Muse mengucapkan setiap kalimat dengan text to speech-nya lebih dulu, lalu kirim MP3 itu ke job video sebagai `audio_1`. Chat text to speech butuh 20 detik dalam uji kami. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-chats">POST /chats</a> dan <a href="/docs/api-muse-v1/post-muse-jobs-video">POST /jobs/video</a></summary> ```bash chat voice1.json "$(jq -n --arg email "$EMAIL" --arg line "$(jq -r '.scenes[0].line' scenes.json)" '{email: $email, message: "Generate one mp3 file with text to speech: single speaker, voice Aria (avocado_v2:MAI_01), speed 100, language en, clean narration only: no music, no sound effects. Read exactly this text, do not change any word:\n\"\($line)\"\nSave it directly in workspace/your_files/ (not in a subfolder) as line-1.mp3 and attach it here. No public links and no uploads to remote storage."}')" VOICE1=$(jq -r '[.messages[] | select(.role == "assistant") | .files[] | select(.type == "audio")][-1].assetId' voice1.json) run clip1.json jobs/video "$(jq --arg email "$EMAIL" --arg voice "$VOICE1" '.scenes[0] | {email: $email, audio_1: $voice, prompt: "Vertical 9:16 video, about 10 seconds, no people on screen and nobody speaking on camera. \(.visual) Slow cinematic camera move, photoreal. Use audio_1 as the narration soundtrack exactly as it is: the off-screen narrator'\''s voice in audio_1, word for word, with no other voice and no new speech. Quiet ambient sound under it is fine."}' scenes.json)" jq -r '.result.assets[] | select(.origin == "made") | .assetId' clip1.json ``` </details> Muse membuat klipnya lalu menempelkan `audio_1` ke klip itu dengan ffmpeg. Job mencantumkan kedua file: salinan jadi lebih dulu, dengan `origin: "made"`, dan klip mentah Muse sesudahnya, dengan `origin: "generated"`. Ambil yang `made`. Klip mentah membawa suara karangan Muse, bukan suara Anda. Job video ini butuh 108 detik dalam uji kami. Ulangi untuk setiap adegan dan gabungkan klip `made` seperti di langkah 4. ### Pertanyaan yang sering diajukan **Apakah ada API untuk Meta Muse (muse.ai)?** Lewat useapi.net, ada: [Muse API](/docs/api-muse-v1) adalah API pihak ketiga yang menjalankan Muse di [langganan situs Muse](https://www.meta.com/help/subscriptions/1021145227643680/) Anda. Buat gambar dengan [POST /jobs/image](/docs/api-muse-v1/post-muse-jobs-image) dan video dengan [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video). [Model API](https://dev.meta.ai/docs/pricing-rate-limits) resmi Meta menjual model Muse Image seharga $0,01 per gambar, tetapi per Oktober 2026 API itu tidak punya pembuatan video dan tidak ada API untuk agen Muse di muse.ai, tempat video dibuat. [Perbandingan Meta Muse video API](/docs/articles/meta-muse-video-api) kami (bahasa Inggris) juga membahas muse2api. **Apakah bisa dipakai di paket Muse gratis?** Lewat useapi.net, bisa: panduan ini dibuat di paket gratis (`HATCH_FREE`), yang punya kuota mingguan. Satu video memakai 2 sampai 3 persen kuota itu dan satu gambar 0 sampai 1 persen, jadi satu akun gratis membuat sekitar 30 sampai 50 video per minggu. Paket berbayar Power ($20 per bulan) dan Maximum ($100 per bulan) menaikkan kuotanya (per Oktober 2026). **Bisakah Muse membuat video lebih dari 10 detik?** Lewat useapi.net, tidak dalam satu job: setiap video sekitar 10 detik. Buat satu klip per adegan dan minta [chat](/docs/api-muse-v1/post-muse-chats) menggabungkannya dengan ffmpeg, seperti di [Membuat Short 30 detik bernarasi](#make-a-30-second-narrated-short-script-three-scenes-one-join), tempat tiga klip menjadi satu Short dalam sekitar 2 sampai 3 menit. Satu chat menerima hingga 3 video. **Bagaimana mengatur rasio aspek, durasi atau resolusi?** Lewat useapi.net, di prompt, karena Muse tidak punya parameter untuk itu. Rasio aspek diikuti jika ditulis sebagai `in exactly 16:9 aspect ratio`, dan klip image-to-video mempertahankan bentuk gambarnya kecuali prompt meminta bentuk lain. Durasi dan resolusi tetap: setiap video kembali sekitar 720p dengan suara, apa pun yang diminta prompt. **Bisakah saya memakai foto dan video sendiri?** Lewat useapi.net, bisa: upload dengan [POST /assets](/docs/api-muse-v1/post-muse-assets), hingga 50 MB per file, dan kirim `assetId`-nya sebagai `image_1`..`image_9`, sama seperti Anda mengirim hasil dari job sebelumnya. [Job video](/docs/api-muse-v1/post-muse-jobs-video) juga menerima `video_1`..`video_3` dan `audio_1`..`audio_3`. Semua input untuk satu job harus berada di akun yang sama. **Bagaimana membuat foto berbicara?** Lewat useapi.net, kirim foto sebagai `image_1` ke [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video) dengan prompt seperti `Animate image_1: … she says softly: "…"`. Muse mempertahankan bentuk foto dan mengucapkan kalimat dalam tanda kutip, seperti di [langkah 7](#step-7-the-portrait-comes-to-life), tempat potret berusia seratus tahun yang sudah direstorasi mengangkat pandangannya dan berbicara. **Bisakah mengganti orang di dalam video?** Lewat useapi.net, bisa: kirim klip sebagai `video_1` dan foto orang baru sebagai `image_1`, lalu minta Muse mengganti orangnya dan mempertahankan semua yang lain, seperti di [langkah 8](#step-8-swap-the-rider-in-the-video). Sebutkan apa yang harus tetap sama, seperti perjalanan, jembatan dan ombaknya, dan beri orang baru itu kalimat dalam tanda kutip jika ia perlu berbicara. **Mengapa request sync saya mengembalikan 202?** Lewat useapi.net, `202` berarti job masih berjalan setelah sekitar 100 detik, dan job itu tetap berjalan di sisi kami. Ambil hasilnya dengan [GET /jobs/`jobid`](/docs/api-muse-v1/get-muse-jobs-jobid), kirim job yang lama dengan `async: true` lalu lakukan polling, atau tambahkan `replyUrl` agar record job yang selesai dikirim ke Anda. Dalam uji kami, satu video butuh 68 sampai 138 detik. **Mengapa Muse mengirimi saya kode login lewat email?** Lewat useapi.net, API masuk ke akun Muse Anda, yang terjadi saat Anda menambahkannya dan saat API memperbarui sesi 30 hari, sebelum kedaluwarsa atau kapan pun Muse meminta login baru. Muse mengirim kode login lewat email di setiap login, dan tidak ada yang perlu dilakukan dengan kode itu. Lihat [Setup Muse](/docs/start-here/setup-muse#what-to-expect). **Apa bedanya dengan muse2api?** Lewat useapi.net, Muse API di-hosting, jadi tidak ada yang perlu di-deploy: Anda menambahkan setiap akun dengan email dan password-nya, dan kami menjaganya tetap login. Hasil dirangkai lewat asset id, dan job yang selesai bisa memanggil webhook Anda. Anda juga bisa [chat dengan agen Muse](/docs/api-muse-v1/chat-streaming-guide), dengan jawabannya di-stream secara langsung. [muse2api](https://github.com/czg86389-hub/muse2api) adalah proyek yang Anda deploy, host dan jalankan sendiri. ### Kesimpulan Kunjungi <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Server Discord</a> atau <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Channel Telegram</a> kami untuk pertanyaan dan masalah dukungan. Lihat [repo GitHub](https://github.com/useapi/muse-api) kami berisi contoh kode. Panggilan yang sama tersedia sebagai tools di [MCP server Muse](/docs/api-muse-v1/mcp) yang di-hosting, untuk Claude Code, Cursor dan VS Code. #### Dipublikasikan juga di {: .no_toc #cross-posted } Juga dipublikasikan di [dev.to](https://dev.to/useapi/how-to-generate-ai-images-and-videos-with-the-muse-api-274){:rel="nofollow"}, didiskusikan di [Reddit](https://www.reddit.com/r/ThirdPartyAPI/comments/1x3udcd/how_to_generate_ai_images_and_videos_with_the/){:rel="nofollow"}, dibagikan di [Bluesky](https://bsky.app/profile/useapi.net/post/3mxnuj43mcs2w){:rel="nofollow"}, dan di YouTube sebagai [demo 2:49 seluruh API](https://www.youtube.com/watch?v=OMUGbfRIO5E). Semuanya dalam bahasa Inggris. ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/muse-images-videos-pt === Document URL: https://useapi.net/docs/articles/muse-images-videos-pt --- layout: default title: "Como gerar vídeos e imagens com IA pela API do Meta Muse" seo_title: "API do Meta Muse: vídeos com som, imagens e foto falante" description: "Faça vídeos Meta Muse de 10 segundos com som, e imagens, pela Muse API da useapi.net: fotos falantes, imagem para vídeo, troca de pessoa e restauração de fotos." keywords: [Muse API, API do Muse, Meta Muse API, API do Meta Muse, Meta Muse video API, gerador de vídeo muse ai, meta muse ai video generator, muse ai api, muse ai imagem para vídeo, API de foto falante, talking photo API, API de gerador de vídeo da Meta AI, muse.ai API, Meta AI video API, API de imagem com IA, API de imagem para vídeo, API de restauração de fotos antigas, API de colorização de fotos, trocar pessoa em vídeo, face swap em vídeo API, vídeo com IA com diálogo, YouTube Shorts sem rosto API, vídeo narrado com IA, curl] image: https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-cover.jpg parent: Articles nav_exclude: true lang: pt-BR date: 2026-10-12 last_modified: 2026-10-30 nav_order: 898 video: name: "Meta Muse API Demo: Images, Talking Photos, Video with Sound, Chat & MCP (third-party, useapi.net)" description: "The third-party Meta Muse API by useapi.net: images, 10-second videos with sound and spoken dialogue, agent chat with live streaming and approvals, and a hosted MCP server, on your Muse website subscription." embed: https://www.youtube.com/embed/OMUGbfRIO5E thumbnail: https://i.ytimg.com/vi/OMUGbfRIO5E/maxresdefault.jpg date: 2026-10-14 duration: PT2M49S width: 1920 height: 1080 repo: https://github.com/useapi/muse-api translation_key: muse --- ## Como gerar vídeos e imagens com IA pela API do Meta Muse {: .no_toc #how-to-generate-ai-videos-and-images-with-the-meta-muse-api } 16 min de leitura • 12 de outubro de 2026 (30 de outubro de 2026) A useapi.net é uma API de terceiros. Não tem afiliação com a Meta nem é endossada por ela. ## Sumário {: .no_toc .text-delta #table-of-contents } ### Introdução A [Muse API da useapi.net](/docs/api-muse-v1) controla o [Muse](https://muse.ai), o agente pessoal de IA da Meta, a partir do código: um POST gera uma imagem ou um vídeo de 10 segundos com diálogo falado, e cada arquivo gerado é um [asset id](/docs/api-muse-v1/get-muse-assets-assetId) que o próximo job pode usar como entrada. O Muse aqui é o agente da Meta em [muse.ai](https://muse.ai), não a Skiv, a empresa de hospedagem de vídeo que usou o nome muse.ai até março de 2026. A API é hospedada, então, ao contrário de ferramentas que você hospeda, como o muse2api, não há nada para implantar: a [comparação de APIs de vídeo do Meta Muse](/docs/articles/meta-muse-video-api) (em inglês) põe a API da própria Meta, o muse2api e as APIs hospedadas lado a lado. A API roda na sua [assinatura do site Muse](https://www.meta.com/help/subscriptions/1021145227643680/), e o plano gratuito funciona. Este passo a passo pega três fotos comuns, uma moto BMW antiga, uma motociclista ruiva e a praia embaixo da Golden Gate, e as transforma em uma imagem dela pilotando essa moto pela arrebentação. A imagem depois vira um vídeo em que ela grita uma fala, e, em um terceiro job, outra mulher, tirada de uma quarta foto, toma o lugar dela no vídeo enquanto o passeio continua igual. No caminho, ele gera imagens a partir de texto, e restaura e coloriza um retrato de cem anos que depois levanta os olhos e fala. Cada requisição abaixo é a que gerou a mídia desta página. <video poster="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g3-poster.jpg" src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g3.mp4" style="width: 100%; aspect-ratio: 1248/704; max-width: 720px" controls type="video/mp4" preload="metadata"></video> A motociclista de uma foto, colocada em um clipe que o Muse fez a partir de uma imagem parada ([passo 8](#step-8-swap-the-rider-in-the-video)). ### Quanto custou A useapi.net é uma API, não um serviço próprio de imagem ou vídeo. Cada chamada roda em uma conta Muse que você adiciona pelo [Setup Muse](/docs/start-here/setup-muse), e gasta a cota semanal do Muse dessa conta, sem cobrança por imagem ou por vídeo da useapi.net. O Muse informa a cota como um percentual inteiro usado, então uma única imagem muitas vezes não mostra mudança. O que cada passo gastou no plano gratuito, tirado do `percentUsed` antes e depois dele, e quanto tempo cada job levou: | Passo | Endpoint | Saída | Cota usada | Tempo | |---|---|---|--:|--:| | [Texto para imagem, 9:16](#step-3-images-from-text) | [POST /jobs/image](/docs/api-muse-v1/post-muse-jobs-image) | 1152×2048 | não medido | 30 s | | [Texto para imagem, exatamente 16:9](#step-3-images-from-text) | [POST /jobs/image](/docs/api-muse-v1/post-muse-jobs-image) | 2048×1152 | 0% | 21 s | | [Motociclista + moto + praia](#step-4-three-photos-into-one-picture) | [POST /jobs/image](/docs/api-muse-v1/post-muse-jobs-image) | 2048×1152 | 0% | 31 s | | [O passeio como vídeo](#step-5-the-picture-as-a-video-no-re-upload) | [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video) | 1280×720, 10 s | 3% | 88 s | | [Restaurar uma foto antiga](#step-6-restore-and-colorize-an-old-photo) | [POST /jobs/image](/docs/api-muse-v1/post-muse-jobs-image) | 1344×1792 | 1% | 34 s | | [O retrato fala](#step-7-the-portrait-comes-to-life) | [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video) | 832×1104, 10 s | 2% | 68 s | | [Trocar a motociclista](#step-8-swap-the-rider-in-the-video) | [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video) | 1248×704, 10 s | 3% | 138 s | Uploads não gastam cota. No plano gratuito, um vídeo gastou de 2 a 3 por cento da semana e uma imagem de 0 a 1 por cento, então uma conta gratuita gera mais ou menos 30 a 50 vídeos por semana, ou várias centenas de imagens ([passo 9](#step-9-check-the-weekly-allowance)). ### Antes de começar Você precisa de um [token da API](/docs/start-here/setup-useapi) da useapi.net e de uma conta Muse adicionada pelo [Setup Muse](/docs/start-here/setup-muse). Antes de adicionar a conta: - O Muse está disponível nos EUA, no Canadá, no [Japão](https://about.fb.com/ja/news/2026/10/muse-personal-ai-agent-launches-in-japan/) e em [Singapura](https://about.fb.com/news/2026/10/muse-is-now-available-in-singapore-the-worlds-first-personal-ai-agent-built-for-everyone/) (em 30 de outubro de 2026), então crie a conta em um desses lugares. Depois de adicionada, você pode chamar a API de qualquer lugar. - Termine o onboarding do Muse em [muse.ai](https://muse.ai), incluindo a verificação de idade da Meta, e crie uma imagem lá. - A conta precisa ter login com e-mail e senha, porque a API entra com o e-mail e a senha. Uma conta Meta que só entra com um código enviado por e-mail ainda não tem senha: crie uma na [Central de Contas da Meta](https://accountscenter.meta.com/password_and_security/) (Senha e segurança) e depois adicione a conta aqui. Sem senha, a adição é recusada com `400`. - Use a conta só para a API, sem outras ferramentas de automação nela. Abrir a conta em muse.ai no navegador não tem problema, mas só a partir dos EUA, do Canadá, do Japão ou de Singapura (as regiões em que o Muse tem suporte oficial), ou por uma VPN em uma delas: a Meta pode desligar o vídeo de uma conta que ela vê sendo usada de outro lugar. Todas as chamadas também estão na [coleção do Postman](/assets/postman/muse-v1.json). Sem código: o template n8n [Old Photo to Talking Video]({% include n8n-url.html t="muse-photo" %}) restaura uma foto e faz ela falar a partir de um formulário, e o template [Narrated Faceless Shorts]({% include n8n-url.html t="muse-shorts" %}) transforma um tema em um Short narrado. O passo a passo inteiro também está no GitHub como um único script, em Node.js e Python: [`images-videos/`](https://github.com/useapi/muse-api/tree/main/images-videos) em [useapi/muse-api](https://github.com/useapi/muse-api), além de uma [agent skill](https://github.com/useapi/muse-api/tree/main/skills/muse-video) para Claude Code e Codex. Os passos usam `curl`, `jq` e estas variáveis e helpers: <details markdown="block"> <summary>Abrir as variáveis e os helpers</summary> ```bash export USEAPI_TOKEN="user:12345-..." export EMAIL="example@gmail.com" export MUSE_PASSWORD="..." # a senha da conta Muse, usada uma vez no passo 1 API=https://api.useapi.net/v1/muse AUTH="Authorization: Bearer $USEAPI_TOKEN" enc() { jq -rn --arg v "$1" '$v|@uri'; } post() { curl -sS -X POST "$API/$1" -H "$AUTH" -H "Content-Type: application/json" -d "$2"; } get() { curl -sS "$API/$1" -H "$AUTH"; } upload() { curl -sS -X POST "$API/assets?email=$(enc "$EMAIL")" -H "$AUTH" -H "Content-Type: $2" --data-binary @"$1" | jq -r .assetId; } download() { curl -sSf "$API/assets/$(enc "$1")" -H "$AUTH" -o "$2"; } # roda um job de forma assíncrona: envia, consulta GET /jobs/{jobid} a cada 10 s e salva o registro final do job em $1 run() { local job id job=$(post "$2" "$(jq '. + {async: true}' <<< "$3")") id=$(jq -r .jobid <<< "$job") while [ "$(jq -r .status <<< "$job")" = started ]; do sleep 10 job=$(get "jobs/$(enc "$id")") done echo "$job" > "$1" jq '{status, error, text: .result.text, asset: .result.assets[0].assetId}' "$1" } ``` </details> Toda geração roda como um job. Sem `async`, um POST espera até cerca de 100 segundos e devolve o registro do job pronto, ou `202` com o job ainda rodando. Um vídeo aqui levou de 68 a 138 segundos, então o `run` envia todo job com `async: true` e consulta [GET /jobs/`jobid`](/docs/api-muse-v1/get-muse-jobs-jobid). Se o `run` mostrar qualquer `status` diferente de `completed`, leia o `error` antes de continuar. Para receber um callback em vez de consultar, acrescente `replyUrl: "https://example.com/hooks/muse"` (e, se quiser, `replyRef`) a qualquer corpo abaixo. A API então envia um único `POST` do registro final do job, em JSON, para essa URL. Os ids têm `:` e `@`, então o `enc` faz o URL-encode deles sempre que entram em um caminho de URL. Todas as entradas de um job precisam estar na mesma conta Muse, então os uploads fixam o `email`, e um job roda na conta que guarda as suas entradas. ### Como foi feito #### 1. Adicionar a conta [POST /accounts](/docs/api-muse-v1/post-muse-accounts) recebe o e-mail e a senha da conta Muse. A API entra uma vez, guarda a sessão de 30 dias e renova sozinha. O Muse manda à conta um código de login por e-mail a cada entrada. Esse e-mail é só um aviso, não é preciso digitar nada. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-accounts">POST /accounts</a></summary> ```bash post accounts "$(jq -n --arg email "$EMAIL" --arg password "$MUSE_PASSWORD" '{email: $email, password: $password}')" | jq '{health, maxJobs, quota}' ``` </details> A resposta mostra `health: "OK"`, `maxJobs` (10 por padrão) e o plano e o uso da conta, aqui `tier: "HATCH_FREE"`, o plano gratuito. Se ela responder `596`, a Meta quer uma verificação de segurança: entre uma vez em muse.ai em um navegador, conclua a verificação e mande o mesmo e-mail e senha de novo. #### 2. Enviar as fotos [POST /assets](/docs/api-muse-v1/post-muse-assets) recebe o arquivo bruto como corpo, até 50 MB, e grava no workspace do Muse da conta. Nada fica guardado na useapi.net. O `assetId` da resposta é o que um job recebe como `image_N`. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-assets">POST /assets</a></summary> ```bash BMW=$(upload bmw.jpeg image/jpeg) RIDER=$(upload rider.jpeg image/jpeg) BEACH=$(upload beach.jpeg image/jpeg) OLD_PHOTO=$(upload old-photo.jpeg image/jpeg) PINK=$(upload pink-hair.jpeg image/jpeg) echo "$BMW" # user:12345-email:6578616d706c6540676d61696c2e636f6d-image:7db53e7a1f0979cbab6ff46ec3f0a35b60e6ee579a0d738a9628cf46a0c7a0f5.jpg ``` </details> <div style="display: flex; flex-wrap: wrap; gap: 8px; align-items: flex-start"> <figure style="margin: 0; width: 32%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-motorcycle.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-motorcycle.jpg" alt="<code>image_1</code> — a moto" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em"><code>image_1</code> — a moto</figcaption></figure> <figure style="margin: 0; width: 18%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-redhead.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-redhead.jpg" alt="<code>image_2</code> — a motociclista" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em"><code>image_2</code> — a motociclista</figcaption></figure> <figure style="margin: 0; width: 32%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-beach.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-beach.jpg" alt="<code>image_3</code> — a praia" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em"><code>image_3</code> — a praia</figcaption></figure> <figure style="margin: 0; width: 18%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-oldphoto.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-oldphoto.jpg" alt="o retrato antigo" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">o retrato antigo</figcaption></figure> <figure style="margin: 0; width: 18%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-pinkhair.webp" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-pinkhair.webp" alt="a segunda motociclista" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">a segunda motociclista</figcaption></figure> </div> As cinco entradas: a moto, a motociclista, a praia, o retrato antigo e a segunda motociclista. O asset id é montado a partir do conteúdo do arquivo, então enviar o mesmo arquivo de novo para a mesma conta devolve o mesmo id e não grava nada. #### 3. Imagens a partir de texto O Muse não tem parâmetro de proporção: quem diz é o prompt. Primeiro, um retrato vertical: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-image">POST /jobs/image</a></summary> ```bash run portrait.json jobs/image "$(jq -n '{prompt: "Vertical 9:16 full-body portrait photo: a confident young woman biker with long wavy fiery red hair, green eyes and freckles, in a worn black leather jacket, dark jeans and boots, standing in a rain-soaked neon alley at dusk, looking straight at the camera, cinematic lighting, photorealistic."}')" download "$(jq -r '.result.assets[0].assetId' portrait.json)" portrait.webp ``` </details> <img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-a2.webp" style="width: 100%; max-width: 420px" alt="Texto para imagem em 9:16"> [abrir em nova aba](https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-a2.webp){:target="_blank"} Essa voltou exatamente em 9:16, 1152×2048. Uma versão em paisagem pedida como `Cinematic 16:9 landscape photo: …` voltou em 1920×1280, que é 3:2. Escrever a proporção como `in exactly 16:9 aspect ratio` resolveu: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-image">POST /jobs/image</a></summary> ```bash run bmw-noir.json jobs/image "$(jq -n '{prompt: "In exactly 16:9 aspect ratio (landscape), a cinematic photo of a vintage 1920s black BMW motorcycle with white pinstripes, spoked wheels and a brown leather saddle, parked on wet cobblestones at night in San Francisco, the Golden Gate Bridge glowing through fog in the distance, neo-noir moonlight, reflections on the wet street, shot on 35mm film."}')" download "$(jq -r '.result.assets[0].assetId' bmw-noir.json)" bmw-noir.webp ``` </details> <img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-a5.webp" style="width: 100%" alt="Texto para imagem em exatamente 16:9"> [abrir em nova aba](https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-a5.webp){:target="_blank"} O Muse respondeu "That 16:9 frame with the bridge ghosting through the fog is pure neo-noir. Enjoy." A resposta dele fica em `result.text`. #### 4. Três fotos em uma imagem Até 9 imagens entram em um job como `image_1`..`image_9`, e o prompt dá nome a elas. Aqui a moto é `image_1`, a motociclista `image_2` e a praia `image_3`. O prompt pede ao Muse que use a praia fotografada do jeito que está, então a Golden Gate fica onde estava na foto. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-image">POST /jobs/image</a></summary> ```bash run beach-ride.json jobs/image "$(jq -n --arg bmw "$BMW" --arg rider "$RIDER" --arg beach "$BEACH" \ '{image_1: $bmw, image_2: $rider, image_3: $beach, prompt: "In exactly 16:9 aspect ratio (landscape), a cinematic photo: the woman from image_2 (her face, long wavy red hair, light blue top and jeans) riding the exact vintage motorcycle from image_1 along the shoreline of the beach in image_3, the front wheel cutting through the shallow surf and throwing spray, bright afternoon sun, her hair streaming in the wind, photorealistic. Use the beach, rocks and Golden Gate Bridge from image_3 as the background exactly as photographed: same position, same orientation, not mirrored or redrawn. Keep her face and the motorcycle'\''s design exactly as in the images."}')" BEACH_RIDE=$(jq -r '.result.assets[0].assetId' beach-ride.json) download "$BEACH_RIDE" beach-ride.webp ``` </details> <img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g1.webp" style="width: 100%" alt="A motociclista, a moto e a praia em uma imagem"> [abrir em nova aba](https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g1.webp){:target="_blank"} 31 segundos, e nenhuma mudança visível na cota semanal. #### 5. A imagem vira vídeo, sem novo upload `BEACH_RIDE` é o id de um arquivo que o Muse gerou. Ele já está no workspace da conta, então entra direto no próximo job como `image_1`, sem download e sem upload. `Animate image_1` faz um clipe que começa na imagem e mantém o formato dela, e a fala entre aspas é dita. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-video">POST /jobs/video</a></summary> ```bash run surf.json jobs/video "$(jq -n --arg img "$BEACH_RIDE" '{image_1: $img, prompt: "Animate image_1 into a cinematic video in exactly 16:9 aspect ratio (landscape): she rides the vintage motorcycle along the shoreline, the front wheel slices through the shallow waves and sends spray flying, the old engine roars, she raises one fist and shouts with a laugh: \"Nothing beats this view!\" The camera tracks alongside her. The beach, the rocks and the Golden Gate Bridge stay exactly as in image_1 (same orientation). Keep her face and the motorcycle exactly as in image_1."}')" SURF=$(jq -r '.result.assets[0].assetId' surf.json) download "$SURF" surf.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g2-poster.jpg" src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g2.mp4" style="width: 100%; aspect-ratio: 16/9; max-width: 720px" controls type="video/mp4" preload="metadata"></video> Também no YouTube: [3 photos in, 1 talking video out: Meta Muse API from REST](https://youtube.com/shorts/v_7mREyFSWk). 10 segundos em 1280×720, com som. O Muse disse "Done. 10 seconds, 16:9 landscape, straight from your image — no edits, no upscaling." A primeira tentativa deste mesmo job falhou depois de 37 segundos: o Muse respondeu que "the video worker glitched out before it rendered anything, so no clip was made". A API informa uma resposta assim como `503`, nada gerado, e a mesma requisição funcionou quando rodou de novo. Uma recusa por conteúdo vem como `403` e precisa de outro prompt. #### 6. Restaurar e colorizar uma foto antiga Um job de imagem também pode consertar uma imagem. O retrato antigo é uma foto sépia desbotada de 685×900 pixels, 3:4. O prompt lista o que corrigir e insiste no mesmo enquadramento. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-image">POST /jobs/image</a></summary> ```bash run restored.json jobs/image "$(jq -n --arg img "$OLD_PHOTO" '{image_1: $img, prompt: "Restore the old photograph image_1 as a high-quality modern photo: remove the scratches, dust, stains, fading and grain, recover sharp detail in the face, hair and fabric, and colorize it naturally (warm natural skin tones, dark brown hair, ivory tulle shawl, a soft pink rose with green leaves, a muted warm background). Keep the exact same person, expression, pose, framing and crop, and the same portrait aspect ratio as image_1 (3:4, 685×900): do not crop, extend or reframe it."}')" RESTORED=$(jq -r '.result.assets[0].assetId' restored.json) download "$RESTORED" restored.webp ``` </details> <div style="display: flex; flex-wrap: wrap; gap: 8px; align-items: flex-start"> <figure style="margin: 0; width: 48%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-oldphoto.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-oldphoto.jpg" alt="Antes: o original, 685×900" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">Antes: o original, 685×900</figcaption></figure> <figure style="margin: 0; width: 48%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-e1.webp" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-e1.webp" alt="Depois: restaurada e colorizada, 1344×1792" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">Depois: restaurada e colorizada, 1344×1792</figcaption></figure> </div> O resultado tem 1344×1792, o mesmo enquadramento 3:4 com cerca do dobro do tamanho, com a mesma pose e o mesmo corte. O Muse disse "Done — restored, de-grained, and colorized, same framing and pose." #### 7. O retrato ganha vida A imagem restaurada entra direto em um job de vídeo. O clipe mantém o formato do retrato, então voltou em 832×1104. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-video">POST /jobs/video</a></summary> ```bash run portrait-video.json jobs/video "$(jq -n --arg img "$RESTORED" '{image_1: $img, prompt: "Animate image_1 into a video with the same portrait frame: the young woman slowly lifts her eyes to the camera, her smile widens, she gently touches the rose on her shoulder and says softly: \"It has been a hundred years... and you still remember me.\" A light breeze moves a few strands of her hair, soft window light, the camera stays still with a very slow push-in. Keep her face exactly as in image_1."}')" download "$(jq -r '.result.assets[0].assetId' portrait-video.json)" portrait.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-e2-poster.jpg" src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-e2.mp4" style="width: 100%; aspect-ratio: 832/1104; max-width: 420px" controls type="video/mp4" preload="metadata"></video> Também no YouTube: [This old portrait just spoke: one API call (Meta Muse API, third-party)](https://youtube.com/shorts/GLHoINX_ozE). #### 8. Trocar a motociclista no vídeo Um job de vídeo também aceita vídeos. `video_1` é o clipe na arrebentação do passo 5, e `image_1` é a foto de uma segunda mulher, de cabelo rosa preso em dois coques. O prompt pede ao Muse que troque a motociclista e mantenha todo o resto, e dá a ela uma fala nova. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-video">POST /jobs/video</a></summary> ```bash run swap.json jobs/video "$(jq -n --arg vid "$SURF" --arg img "$PINK" '{video_1: $vid, image_1: $img, prompt: "Edit video_1: replace the rider with the woman from image_1 (her face, pink hair in two buns, colorful makeup and tattoos), and keep everything else the same: the motorcycle, the beach, the waves and spray, the Golden Gate Bridge, the light, the camera move and the timing. Instead of the original line she shouts: \"Catch me if you can, San Francisco!\" Keep the 16:9 frame and the same length."}')" download "$(jq -r '.result.assets[0].assetId' swap.json)" swap.mp4 ``` </details> <div style="display: flex; flex-wrap: wrap; gap: 8px; align-items: flex-start"> <figure style="margin: 0; width: 48%"><video poster="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g2-poster.jpg" src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g2.mp4" style="width: 100%; aspect-ratio: 16/9" controls type="video/mp4" preload="metadata"></video><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">Antes: a motociclista original</figcaption></figure> <figure style="margin: 0; width: 48%"><video poster="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g3-poster.jpg" src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g3.mp4" style="width: 100%; aspect-ratio: 1248/704" controls type="video/mp4" preload="metadata"></video><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">Depois: a motociclista da foto</figcaption></figure> </div> Com 138 segundos, este foi o job mais lento do passo a passo, e é por isso que todo job aqui roda de forma assíncrona. O clipe é o mesmo passeio, com a outra mulher na moto, gritando a fala nova. O Muse disse "Done. She's in, 10 seconds, 16:9, same ride, same bridge, same waves." Também no YouTube: [Replace the person in a video, keep everything else: Meta Muse API](https://youtube.com/shorts/XDCY1XIsd5Y). #### 9. Conferir a cota semanal [GET /accounts/`email`](/docs/api-muse-v1/get-muse-accounts-email) lê o plano e o uso da conta ao vivo: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/get-muse-accounts-email">GET /accounts/email</a></summary> ```bash get "accounts/$(enc "$EMAIL")" | jq '{session, quota}' ``` </details> `quota.percentUsed` é a parte da semana já usada, em percentual inteiro, e `quota.resetsAt` é quando ela recomeça, uma semana depois do início. Os três vídeos acima gastaram de 2 a 3 por cento cada e as imagens 0 ou 1. Na sessão de testes inteira, que também rodou dois jobs que não aparecem aqui, a conta gratuita foi de 16 a 28 por cento. Quando uma conta esgota, os novos jobs sem `email` vão para as suas outras contas, e um job fixado nela responde `412` até `resetsAt`. ### O que aprendemos - Escreva a proporção como `in exactly 16:9 aspect ratio`. `Cinematic 16:9 landscape photo` voltou em 3:2 uma vez. - Todo vídeo tem cerca de 10 segundos. Um prompt pedindo 5 segundos ainda recebeu 10. - Um clipe de imagem para vídeo mantém o formato da imagem, a menos que o prompt peça outro: `in exactly 9:16 aspect ratio` transformou a nossa imagem da praia em 16:9 em um clipe vertical de 720×1280, reenquadrado em vez de esticado. - Falas escritas entre aspas em um prompt de vídeo são ditas. - Passe os arquivos gerados adiante pelo `assetId`. Eles ficam no workspace da conta, então uma cadeia de edições não precisa de downloads no meio. - Diga o que tem que continuar igual. "Same position, same orientation, not mirrored or redrawn" manteve a praia real na composição. - Vale rodar de novo um `503` com palavras do próprio Muse, como "glitched out". Um `403` é uma recusa e precisa de outro prompt. - Mande vídeos com `async: true`. Uma requisição síncrona espera cerca de 100 segundos, e a troca levou 138. ### Faça um Short narrado de 30 segundos (roteiro, três cenas, uma junção) Um vídeo do Muse tem sempre cerca de 10 segundos, então um Short vertical de 30 segundos com narrador leva três jobs de vídeo e dois chats. Um [chat](/docs/api-muse-v1/post-muse-chats) escreve o roteiro em JSON, três [jobs de vídeo](/docs/api-muse-v1/post-muse-jobs-video) rodam lado a lado, um por cena, cada um dizendo a sua fala na voz do mesmo narrador, e um último chat junta os clipes com ffmpeg no próprio workspace da conta. O Short abaixo, sobre a erupção do Monte Tambora em 1815 e o "ano sem verão" que veio depois, foi de um tema de uma linha a um MP4 em cerca de 2 minutos. <video poster="https://media.useapi.net/articles/2026-10-12-muse-images-videos-id/muse-narrated-short-tambora-poster.jpg" src="https://media.useapi.net/articles/2026-10-12-muse-images-videos-id/muse-narrated-short-tambora.mp4" style="width: 100%; aspect-ratio: 9/16; max-width: 420px" controls type="video/mp4" preload="metadata"></video> Também no YouTube: [A narrated 30-second Short made only with Meta Muse API calls](https://youtube.com/shorts/1e8f7dHTkzs). Três clipes de 10 segundos juntados em um Short de 720×1280 com 30 segundos, a partir do tema "how a single volcano cooled the whole planet in 1816". O roteiro levou 11 segundos, os três clipes 75, 75 e 87 segundos rodando ao mesmo tempo, e a junção 20 segundos, então um Short leva cerca de 2 a 3 minutos. Este foi feito em um plano pago do Muse. Nele, os quatro vídeos daquela sessão de testes (estes três e mais um) mexeram a leitura semanal em 2 pontos no total, e os chats em nenhum. No plano gratuito, um vídeo gasta de 2 a 3 por cento da semana, então um Short de três cenas custa lá cerca de 6 a 9 por cento. Sem código: o mesmo fluxo é um app n8n, o template [Narrated Faceless Shorts]({% include n8n-url.html t="muse-shorts" %}), com formulário, página de roteiro e salvamento no Google Drive. Dois Shorts que ele fez, publicados do jeito que saíram: [The Great Pyramid was once bright white](https://youtube.com/shorts/D-Nk0x9aJMo) e [Why honey never spoils](https://youtube.com/shorts/bYLsJIqerSM), que ele narrou com o texto para fala do Muse. O fluxo inteiro também é um único script, em Node.js e Python: [`narrated-short/`](https://github.com/useapi/muse-api/tree/main/narrated-short) em [useapi/muse-api](https://github.com/useapi/muse-api). Ele recebe um tema e, se você quiser, o número de cenas e a sua própria descrição de narrador, e salva o Short em `output/`. Os passos usam os [helpers acima](#before-you-start) mais o `chat`, que inicia um chat e lê [GET /chats/`chatId`](/docs/api-muse-v1/get-muse-chats-chatId) até o Muse terminar: <details markdown="block"> <summary>Abrir o helper de chat</summary> ```bash # inicia um chat, consulta GET /chats/{chatId} a cada 8 s até o Muse terminar e salva o chat em $1 chat() { local id c id=$(post chats "$2" | jq -r .chatId) while sleep 8; do c=$(get "chats/$(enc "$id")") jq -e '.pendingApprovals | length > 0' <<< "$c" > /dev/null && echo "Muse asks for permission: answer it with POST /chats/{chatId}/approvals/{approvalId}" jq -e '(.status | IN("completed", "interrupted", "failed")) and (.pendingApprovals | length == 0)' <<< "$c" > /dev/null && break done echo "$c" > "$1" jq '{status, reply: ([.messages[] | select(.role == "assistant" and .text != "")][-1].text)}' "$1" } ``` </details> Toda requisição abaixo fixa o `email`. Um chat que recebe arquivos precisa rodar na conta que guarda esses arquivos, então os três clipes e a junção ficam todos em uma conta. #### 1. Escrever o roteiro em JSON O primeiro chat pede exatamente três cenas e descreve o formato do JSON. Cada cena tem uma `line`, o que o narrador diz, limitada a 25 palavras para caber em 10 segundos, e um `visual`, uma frase que descreve a tomada. O prompt também diz ao Muse para não criar arquivos, então o chat fica só em texto. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-chats">POST /chats</a></summary> ```bash TOPIC="how a single volcano cooled the whole planet in 1816" chat script.json "$(jq -n --arg email "$EMAIL" --arg topic "$TOPIC" '{email: $email, message: "Write a script for a 30-second faceless YouTube Short about: \"\($topic)\". Exactly 3 scenes. Reply with ONLY a JSON object, no prose, no markdown code fences, in this exact shape: {\"title\": string, \"scenes\": [{\"line\": string, \"visual\": string}, {\"line\": string, \"visual\": string}, {\"line\": string, \"visual\": string}]}. \"line\" is what the off-screen narrator says (at most 25 words, about 9 seconds spoken). \"visual\" is a one-sentence description of the 10-second shot, no people talking on camera. Do not create any files, images or videos."}')" jq -r '[.messages[] | select(.role == "assistant" and .text != "")][-1].text' script.json | sed '/^```/d' > scenes.json jq . scenes.json ``` </details> O Muse respondeu em 11 segundos só com o JSON: ```json { "title": "How One Volcano Cooled the Whole Planet in 1816", "scenes": [ { "line": "In April 1815, Mount Tambora in Indonesia erupted, the largest explosion in recorded history, blasting ash forty kilometers into the sky.", "visual": "A massive volcanic eruption at dawn, with a towering ash column rising into the stratosphere above a dark island." }, { "line": "That ash veil circled Earth, blocking sunlight and dropping global temperatures, turning summer into winter across North America and Europe.", "visual": "An animated globe wrapped in a gray haze as sunlight dims and frost spreads across continents." }, { "line": "1816 became the Year Without a Summer: crops failed, snow fell in July, and famine spread as the planet shivered.", "visual": "Snow falling over green farmland in summer, covering withered crops and empty village fields under a pale sun." } ] } ``` Rodamos o mesmo prompt com três temas e recebemos JSON limpo todas as vezes, em 11 a 29 segundos, sem blocos de código e sem texto extra. É uma amostra pequena, então o `sed` tira mesmo assim uma linha solta de ```` ``` ````, e o script do GitHub pergunta de novo quando a resposta não é um JSON válido. #### 2. Três cenas ao mesmo tempo Cada cena vira um [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video) assíncrono. Os três prompts levam a mesma descrição do narrador, palavra por palavra, seguida de `The narrator says exactly: "<line>"`. O Muse diz uma fala entre aspas como está escrita, e a descrição em comum mantém a voz parecida de um clipe para outro. `Vertical 9:16 video` voltou em 720×1280. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-video">POST /jobs/video</a></summary> ```bash NARRATOR="Narration: one off-screen narrator only, the same voice throughout: a calm, deep, middle-aged British male documentary narrator, measured pace, warm and authoritative, like a nature documentary. Nobody on screen speaks. No music." for i in 0 1 2; do post jobs/video "$(jq --arg email "$EMAIL" --arg narrator "$NARRATOR" --argjson i $i '.scenes[$i] | {email: $email, async: true, prompt: "Vertical 9:16 video, about 10 seconds. \(.visual) Slow cinematic camera move, photoreal. \($narrator) The narrator says exactly: \"\(.line)\""}' scenes.json)" | jq -r .jobid done > jobs.txt ``` </details> Cada POST responde `201` na hora com um `jobid`. Os três jobs ocupam três das vagas de `maxJobs` da conta (10 por padrão), então rodam lado a lado. Um `429` aqui quer dizer que todas as vagas estão ocupadas e nada foi iniciado: mande esse de novo em 30 segundos. #### 3. Consultar os jobs [GET /jobs/`jobid`](/docs/api-muse-v1/get-muse-jobs-jobid) responde `status: "started"` até o clipe ficar pronto. Os jobs rodam em paralelo, então ler um depois do outro não acrescenta tempo: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/get-muse-jobs-jobid">GET /jobs/jobid</a></summary> ```bash for n in 1 2 3; do id=$(sed -n "${n}p" jobs.txt) until job=$(get "jobs/$(enc "$id")"); [ "$(jq -r .status <<< "$job")" != started ]; do sleep 10; done echo "$job" > clip$n.json jq '{status, error, text: .result.text, asset: .result.assets[0].assetId}' clip$n.json done ``` </details> Os três terminaram. Sobre o primeiro, o Muse disse "Here it is — vertical 9:16, photoreal volcanic eruption at dawn with the narration as specified". Cada clipe diz a sua fala palavra por palavra, e todas as falas, com 20 a 21 palavras, couberam nos seus 10 segundos. Um job que falhou com `503` não gerou nada e pode rodar de novo. Qualquer outra falha, como uma recusa `403`, pede uma olhada em `error.message` antes. #### 4. Juntar os clipes em um chat Os três ids dos clipes entram em um chat como `files`, em que o Muse os vê como `video_1`, `video_2` e `video_3`. A mensagem pede ffmpeg, a ordem, o áudio e um nome de arquivo, e termina com `No public links.` Com essa linha, o Muse não parou para pedir permissão. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-chats">POST /chats</a></summary> ```bash CLIPS=$(jq -s '[.[].result.assets[0].assetId]' clip1.json clip2.json clip3.json) chat join.json "$(jq -n --arg email "$EMAIL" --argjson files "$CLIPS" '{email: $email, files: $files, message: "Concatenate video_1, video_2, video_3 in order into one MP4 with ffmpeg, keep the audio, save it to workspace/your_files/short.mp4 and attach it here. No public links."}')" SHORT=$(jq -r '[.messages[] | select(.role == "assistant") | .files[] | select(.type == "video")][-1].assetId' join.json) echo "$SHORT" # user:12345-email:6578616d706c6540676d61696c2e636f6d-video:ws~your_files~short.mp4 ``` </details> 20 segundos depois, o Muse disse "Concatenated all three in order — 30 seconds, 720x1280, with audio kept." e anexou o arquivo em uma mensagem própria, um `video` nos seus `files`. O asset id leva o nome do caminho no workspace, então dê a cada Short o seu próprio nome de arquivo. O ffmpeg copiou os streams sem recodificar: o Short tem exatamente 30,0 segundos, e as três falas estão nele, em ordem. #### 5. Baixar o Short [GET /assets/`assetId`](/docs/api-muse-v1/get-muse-assets-assetId) devolve o MP4: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/get-muse-assets-assetId">GET /assets/assetId</a></summary> ```bash download "$SHORT" tambora-short.mp4 ``` </details> Os clipes e o Short também ficam no workspace do Muse da conta, onde o app muse.ai os mostra, e o asset id do Short pode entrar no próximo job como `video_1`. #### Uma voz fixa: texto para fala como audio_1 Uma descrição em comum dá o mesmo tipo de voz, não uma voz travada. Nos três clipes do Tambora, o tom mediano do narrador ficou entre 105 e 117 Hz, menos de dois semitons de diferença, mas o Muse dá voz a cada clipe do zero. Para ter uma voz só, com certeza, faça o Muse dizer antes cada fala com o texto para fala dele, depois passe esse MP3 ao job de vídeo como `audio_1`. O chat de texto para fala levou 20 segundos no nosso teste. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-chats">POST /chats</a> e <a href="/docs/api-muse-v1/post-muse-jobs-video">POST /jobs/video</a></summary> ```bash chat voice1.json "$(jq -n --arg email "$EMAIL" --arg line "$(jq -r '.scenes[0].line' scenes.json)" '{email: $email, message: "Generate one mp3 file with text to speech: single speaker, voice Aria (avocado_v2:MAI_01), speed 100, language en, clean narration only: no music, no sound effects. Read exactly this text, do not change any word:\n\"\($line)\"\nSave it directly in workspace/your_files/ (not in a subfolder) as line-1.mp3 and attach it here. No public links and no uploads to remote storage."}')" VOICE1=$(jq -r '[.messages[] | select(.role == "assistant") | .files[] | select(.type == "audio")][-1].assetId' voice1.json) run clip1.json jobs/video "$(jq --arg email "$EMAIL" --arg voice "$VOICE1" '.scenes[0] | {email: $email, audio_1: $voice, prompt: "Vertical 9:16 video, about 10 seconds, no people on screen and nobody speaking on camera. \(.visual) Slow cinematic camera move, photoreal. Use audio_1 as the narration soundtrack exactly as it is: the off-screen narrator'\''s voice in audio_1, word for word, with no other voice and no new speech. Quiet ambient sound under it is fine."}' scenes.json)" jq -r '.result.assets[] | select(.origin == "made") | .assetId' clip1.json ``` </details> O Muse gera o clipe dele e depois coloca o `audio_1` por cima com ffmpeg. O job lista os dois arquivos: a cópia final primeiro, com `origin: "made"`, e o clipe bruto do Muse depois, com `origin: "generated"`. Pegue o `made`. O clipe bruto traz uma voz que o Muse inventou, não a sua. O job de vídeo levou 108 segundos no nosso teste. Repita para cada cena e junte os clipes `made` como no passo 4. ### Perguntas frequentes **Existe API do Meta Muse (muse.ai)?** Com a useapi.net, sim: a [Muse API](/docs/api-muse-v1) é uma API de terceiros que roda o Muse na sua [assinatura do site Muse](https://www.meta.com/help/subscriptions/1021145227643680/). Gere imagens com [POST /jobs/image](/docs/api-muse-v1/post-muse-jobs-image) e vídeos com [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video). A [Model API](https://dev.meta.ai/docs/pricing-rate-limits) oficial da Meta vende o modelo Muse Image a $0,01 por imagem, mas, em outubro de 2026, não tem geração de vídeo nem API para o agente Muse em muse.ai, onde os vídeos são feitos. A nossa [comparação de APIs de vídeo do Meta Muse](/docs/articles/meta-muse-video-api) (em inglês) cobre também o muse2api. **Funciona no plano gratuito do Muse?** Com a useapi.net, sim: este passo a passo foi feito no plano gratuito (`HATCH_FREE`), que tem uma cota semanal. Um vídeo gastou de 2 a 3 por cento dela e uma imagem de 0 a 1 por cento, então uma conta gratuita gera mais ou menos 30 a 50 vídeos por semana. Os planos pagos Power ($20 por mês) e Maximum ($100 por mês) aumentam a cota (em outubro de 2026). **O Muse faz vídeo com mais de 10 segundos?** Com a useapi.net, não em um único job: todo vídeo tem cerca de 10 segundos. Gere um clipe por cena e peça a um [chat](/docs/api-muse-v1/post-muse-chats) que junte os clipes com ffmpeg, como em [Faça um Short narrado de 30 segundos](#make-a-30-second-narrated-short-script-three-scenes-one-join), em que três clipes viraram um Short em cerca de 2 a 3 minutos. Um chat aceita até 3 vídeos. **Como definir a proporção, a duração ou a resolução?** Com a useapi.net, no prompt, porque o Muse não tem parâmetros para isso. A proporção é respeitada quando escrita como `in exactly 16:9 aspect ratio`, e um clipe de imagem para vídeo mantém o formato da imagem, a menos que o prompt peça outro. Duração e resolução são fixas: todo vídeo volta em cerca de 720p com som, peça o prompt o que pedir. **Posso usar as minhas próprias fotos e vídeos?** Com a useapi.net, sim: envie com [POST /assets](/docs/api-muse-v1/post-muse-assets), até 50 MB cada, e passe o `assetId` como `image_1`..`image_9`, do mesmo jeito que você passa o resultado de um job anterior. [Jobs de vídeo](/docs/api-muse-v1/post-muse-jobs-video) também aceitam `video_1`..`video_3` e `audio_1`..`audio_3`. Todas as entradas de um job precisam estar na mesma conta. **Como fazer uma foto falar?** Com a useapi.net, passe a foto como `image_1` para [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video) com um prompt como `Animate image_1: … she says softly: "…"`. O Muse mantém o formato da foto e diz a fala entre aspas, como no [passo 7](#step-7-the-portrait-comes-to-life), em que um retrato restaurado de cem anos levanta os olhos e fala. **Dá para trocar uma pessoa em um vídeo?** Com a useapi.net, sim: passe o clipe como `video_1` e uma foto da nova pessoa como `image_1`, e peça ao Muse que troque a pessoa e mantenha todo o resto, como no [passo 8](#step-8-swap-the-rider-in-the-video). Diga o que precisa continuar igual, como o passeio, a ponte e as ondas, e dê à nova pessoa uma fala entre aspas se ela deve falar. **Por que a minha requisição síncrona devolveu 202?** Com a useapi.net, um `202` quer dizer que o job ainda estava rodando depois de cerca de 100 segundos, e ele continua rodando do nosso lado. Busque o job com [GET /jobs/`jobid`](/docs/api-muse-v1/get-muse-jobs-jobid), mande jobs longos com `async: true` e consulte, ou acrescente um `replyUrl` para receber o registro do job pronto. Nos nossos testes, um vídeo levou de 68 a 138 segundos. **Por que o Muse me mandou um código de login por e-mail?** Com a useapi.net, a API entrou na sua conta Muse, o que acontece quando você a adiciona e quando a API renova a sessão de 30 dias, antes de ela expirar ou sempre que o Muse pede uma nova entrada. O Muse manda um código de login por e-mail a cada entrada, e não é preciso fazer nada com ele. Veja o [Setup Muse](/docs/start-here/setup-muse#what-to-expect). **Qual a diferença para o muse2api?** Com a useapi.net, a Muse API é hospedada, então não há nada para implantar: você adiciona cada conta com o e-mail e a senha e nós a mantemos conectada. Os resultados se encadeiam por asset id, e um job pronto pode chamar o seu webhook. Você também pode [conversar com o agente Muse](/docs/api-muse-v1/chat-streaming-guide), com as respostas transmitidas ao vivo. O [muse2api](https://github.com/czg86389-hub/muse2api) é um projeto que você mesmo implanta, hospeda e mantém rodando. ### Conclusão Visite o nosso <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> servidor no Discord</a> ou o <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> canal no Telegram</a> para qualquer dúvida de suporte. Veja o nosso [repositório no GitHub](https://github.com/useapi/muse-api) com exemplos de código. As mesmas chamadas estão disponíveis como ferramentas no [servidor MCP do Muse](/docs/api-muse-v1/mcp) hospedado, para Claude Code, Cursor e VS Code. #### Publicado também em {: .no_toc #cross-posted } Também publicado no [dev.to](https://dev.to/useapi/how-to-generate-ai-images-and-videos-with-the-muse-api-274){:rel="nofollow"}, discutido no [Reddit](https://www.reddit.com/r/ThirdPartyAPI/comments/1x3udcd/how_to_generate_ai_images_and_videos_with_the/){:rel="nofollow"}, compartilhado no [Bluesky](https://bsky.app/profile/useapi.net/post/3mxnuj43mcs2w){:rel="nofollow"} e no YouTube como uma [demo de 2:49 da API inteira](https://www.youtube.com/watch?v=OMUGbfRIO5E) (todos em inglês). ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/muse-images-videos-th === Document URL: https://useapi.net/docs/articles/muse-images-videos-th --- layout: default title: "วิธีสร้างวิดีโอและภาพ AI ด้วย Meta Muse API" description: "สร้างวิดีโอ Meta Muse ยาว 10 วินาทีพร้อมเสียง และสร้างภาพ ผ่าน Muse API ของ useapi.net: รูปถ่ายพูดได้ เปลี่ยนภาพเป็นวิดีโอ เปลี่ยนคนในวิดีโอ และบูรณะภาพเก่า" keywords: [Muse API, Meta Muse API, Meta Muse video API, muse ai video generator, muse ai api, muse ai image to video, Meta Muse สร้างวิดีโอ, muse ai สร้างวิดีโอ, Meta AI สร้างวิดีโอ, API สร้างวิดีโอ AI, API สร้างภาพ AI, เปลี่ยนภาพเป็นวิดีโอ AI, รูปพูดได้ AI, ทำรูปให้พูดได้, talking photo API, บูรณะภาพเก่า AI, ทำภาพขาวดำให้เป็นสี, เปลี่ยนคนในวิดีโอ, เปลี่ยนหน้าในวิดีโอ, วิดีโอ AI มีบทพูด, YouTube Shorts ไม่โชว์หน้า, คลิปสั้นมีเสียงบรรยาย, muse.ai API, curl] image: https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-cover.jpg parent: Articles nav_exclude: true lang: th date: 2026-10-12 last_modified: 2026-10-30 nav_order: 898 video: name: "Meta Muse API Demo: Images, Talking Photos, Video with Sound, Chat & MCP (third-party, useapi.net)" description: "The third-party Meta Muse API by useapi.net: images, 10-second videos with sound and spoken dialogue, agent chat with live streaming and approvals, and a hosted MCP server, on your Muse website subscription." embed: https://www.youtube.com/embed/OMUGbfRIO5E thumbnail: https://i.ytimg.com/vi/OMUGbfRIO5E/maxresdefault.jpg date: 2026-10-14 duration: PT2M49S width: 1920 height: 1080 repo: https://github.com/useapi/muse-api translation_key: muse --- ## วิธีสร้างวิดีโอและภาพ AI ด้วย Meta Muse API {: .no_toc #how-to-generate-ai-videos-and-images-with-the-meta-muse-api } อ่าน 16 นาที • 12 ตุลาคม 2026 (30 ตุลาคม 2026) useapi.net เป็น API ของบุคคลที่สาม (third-party) ไม่มีส่วนเกี่ยวข้องกับ Meta และไม่ได้รับการรับรองจาก Meta ## สารบัญ {: .no_toc .text-delta #table-of-contents } ### บทนำ [Muse API ของ useapi.net](/docs/api-muse-v1) สั่งงาน [Muse](https://muse.ai) เอเจนต์ AI ส่วนตัวของ Meta ได้จากโค้ด POST ครั้งเดียวสร้างภาพ หรือวิดีโอยาว 10 วินาทีที่มีบทพูด และทุกไฟล์ที่สร้างขึ้นจะเป็น [asset id](/docs/api-muse-v1/get-muse-assets-assetId) ที่งานถัดไปนำไปใช้เป็นอินพุตได้ Muse ในบทความนี้คือเอเจนต์ของ Meta ที่ [muse.ai](https://muse.ai) ไม่ใช่ Skiv บริษัทโฮสต์วิดีโอที่เคยใช้ชื่อ muse.ai จนถึงมีนาคม 2026 API นี้เป็นแบบโฮสต์ให้ จึงไม่ต้องติดตั้งอะไรเอง ต่างจากเครื่องมือที่ต้องโฮสต์เองอย่าง muse2api บทความ[เปรียบเทียบ Meta Muse video API](/docs/articles/meta-muse-video-api) วาง API ของ Meta เอง muse2api และ API แบบโฮสต์ไว้เทียบกัน API นี้ทำงานบน[แพ็กเกจเว็บไซต์ Muse](https://www.meta.com/help/subscriptions/1021145227643680/) ของคุณ และแพ็กเกจฟรีก็ใช้ได้ บทความนี้เริ่มจากรูปถ่ายธรรมดาสามรูป คือมอเตอร์ไซค์ BMW รุ่นวินเทจ ผู้หญิงผมแดง และชายหาดใต้สะพาน Golden Gate แล้วรวมเป็นภาพเดียวที่เธอขี่มอเตอร์ไซค์คันนั้นฝ่าคลื่น จากนั้นภาพนี้กลายเป็นวิดีโอที่เธอตะโกนพูดหนึ่งประโยค และในงานที่สาม ผู้หญิงอีกคนจากรูปที่สี่เข้ามาแทนเธอในวิดีโอ โดยฉากขี่ยังเหมือนเดิม ระหว่างทางยังสร้างภาพจากข้อความ และบูรณะพร้อมลงสีภาพถ่ายบุคคลอายุร้อยปี ซึ่งต่อมาเงยหน้าขึ้นและพูดได้ ทุกคำขอด้านล่างคือคำขอจริงที่สร้างสื่อในหน้านี้ <video poster="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g3-poster.jpg" src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g3.mp4" style="width: 100%; aspect-ratio: 1248/704; max-width: 720px" controls type="video/mp4" preload="metadata"></video> ผู้ขี่จากรูปถ่าย ถูกสลับเข้าไปในคลิปที่ Muse สร้างจากภาพนิ่ง ([ขั้นตอนที่ 8](#step-8-swap-the-rider-in-the-video)) ### ใช้โควตาไปเท่าไร useapi.net เป็น API ไม่ใช่บริการสร้างภาพหรือวิดีโอของตัวเอง ทุกคำขอทำงานบนบัญชี Muse ที่คุณเพิ่มผ่าน [ตั้งค่า Muse](/docs/start-here/setup-muse) และใช้โควตารายสัปดาห์ของ Muse ในบัญชีนั้น useapi.net ไม่คิดเงินต่อภาพหรือต่อวิดีโอ Muse แสดงโควตาเป็นเปอร์เซ็นต์เต็มที่ใช้ไป ภาพเดียวจึงมักไม่เห็นการเปลี่ยนแปลง แต่ละขั้นตอนใช้โควตาไปเท่าไรบนแพ็กเกจฟรี อ่านจาก `percentUsed` ก่อนและหลังขั้นตอน และแต่ละงานใช้เวลานานเท่าไร: | ขั้นตอน | Endpoint | ผลลัพธ์ | โควตาที่ใช้ | เวลา | |---|---|---|--:|--:| | [ข้อความเป็นภาพ, 9:16](#step-3-images-from-text) | [POST /jobs/image](/docs/api-muse-v1/post-muse-jobs-image) | 1152×2048 | ไม่ได้วัด | 30 วิ | | [ข้อความเป็นภาพ, 16:9 พอดี](#step-3-images-from-text) | [POST /jobs/image](/docs/api-muse-v1/post-muse-jobs-image) | 2048×1152 | 0% | 21 วิ | | [ผู้ขี่ + มอเตอร์ไซค์ + ชายหาด](#step-4-three-photos-into-one-picture) | [POST /jobs/image](/docs/api-muse-v1/post-muse-jobs-image) | 2048×1152 | 0% | 31 วิ | | [ฉากขี่เป็นวิดีโอ](#step-5-the-picture-as-a-video-no-re-upload) | [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video) | 1280×720, 10 วิ | 3% | 88 วิ | | [บูรณะภาพเก่า](#step-6-restore-and-colorize-an-old-photo) | [POST /jobs/image](/docs/api-muse-v1/post-muse-jobs-image) | 1344×1792 | 1% | 34 วิ | | [ภาพบุคคลพูดได้](#step-7-the-portrait-comes-to-life) | [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video) | 832×1104, 10 วิ | 2% | 68 วิ | | [สลับผู้ขี่](#step-8-swap-the-rider-in-the-video) | [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video) | 1248×704, 10 วิ | 3% | 138 วิ | การอัปโหลดไม่ใช้โควตา บนแพ็กเกจฟรี วิดีโอหนึ่งคลิปใช้ 2 ถึง 3 เปอร์เซ็นต์ของสัปดาห์ และภาพหนึ่งภาพใช้ 0 ถึง 1 เปอร์เซ็นต์ บัญชีฟรีหนึ่งบัญชีจึงสร้างวิดีโอได้ราว 30 ถึง 50 คลิปต่อสัปดาห์ หรือภาพหลายร้อยภาพ ([ขั้นตอนที่ 9](#step-9-check-the-weekly-allowance)) ### ก่อนเริ่ม คุณต้องมี [API token](/docs/start-here/setup-useapi) ของ useapi.net และบัญชี Muse ที่เพิ่มผ่าน [ตั้งค่า Muse](/docs/start-here/setup-muse) ก่อนเพิ่มบัญชี: - Muse ให้บริการในสหรัฐฯ แคนาดา [ญี่ปุ่น](https://about.fb.com/ja/news/2026/10/muse-personal-ai-agent-launches-in-japan/) และ[สิงคโปร์](https://about.fb.com/news/2026/10/muse-is-now-available-in-singapore-the-worlds-first-personal-ai-agent-built-for-everyone/) (ข้อมูล ณ 30 ตุลาคม 2026) จึงต้องสร้างบัญชีในประเทศใดประเทศหนึ่งในนี้ เมื่อเพิ่มบัญชีแล้ว คุณเรียก API ได้จากทุกที่ - ทำขั้นตอนเริ่มต้นใช้งานของ Muse ที่ [muse.ai](https://muse.ai) ให้ครบ รวมถึงการยืนยันอายุของ Meta และสร้างภาพที่นั่นหนึ่งภาพ - บัญชีต้องล็อกอินด้วยอีเมลและรหัสผ่านได้ เพราะ API ล็อกอินด้วยอีเมลและรหัสผ่าน บัญชี Meta ที่ล็อกอินด้วยรหัสทางอีเมลอย่างเดียวยังไม่มีรหัสผ่าน ให้สร้างรหัสผ่านใน [Meta Accounts Center](https://accountscenter.meta.com/password_and_security/) (Password and security) แล้วค่อยเพิ่มบัญชีที่นี่ ถ้าไม่มีรหัสผ่าน การเพิ่มบัญชีจะถูกปฏิเสธด้วย `400` - ใช้บัญชีนี้กับ API เท่านั้น ไม่ใช้กับเครื่องมืออัตโนมัติอื่น เปิดบัญชีที่ muse.ai ในเบราว์เซอร์ได้ แต่ต้องเปิดจากสหรัฐฯ แคนาดา ญี่ปุ่น หรือสิงคโปร์ (ภูมิภาคที่ Muse รองรับอย่างเป็นทางการ) หรือผ่าน VPN ในประเทศเหล่านี้ เพราะ Meta อาจปิดการสร้างวิดีโอของบัญชีที่ถูกใช้จากที่อื่น ทุกคำขอมีอยู่ใน [Postman collection](/assets/postman/muse-v1.json) ด้วย ด้วย ถ้าไม่อยากเขียนโค้ด เทมเพลต n8n [Old Photo to Talking Video]({% include n8n-url.html t="muse-photo" %}) บูรณะภาพและทำให้ภาพพูดได้จากฟอร์ม และเทมเพลต [Narrated Faceless Shorts]({% include n8n-url.html t="muse-shorts" %}) เปลี่ยนหัวข้อให้เป็นคลิป Short ที่มีเสียงบรรยาย ทั้งบทความนี้ยังมีบน GitHub เป็นสคริปต์เดียว ทั้ง Node.js และ Python: [`images-videos/`](https://github.com/useapi/muse-api/tree/main/images-videos) ใน [useapi/muse-api](https://github.com/useapi/muse-api) และมี [agent skill](https://github.com/useapi/muse-api/tree/main/skills/muse-video) สำหรับ Claude Code และ Codex ขั้นตอนต่าง ๆ ใช้ `curl`, `jq` และตัวแปรกับฟังก์ชันช่วยเหล่านี้: <details markdown="block"> <summary>เปิดดูตัวแปรและฟังก์ชันช่วย</summary> ```bash export USEAPI_TOKEN="user:12345-..." export EMAIL="example@gmail.com" export MUSE_PASSWORD="..." # รหัสผ่านบัญชี Muse ใช้ครั้งเดียวในขั้นตอนที่ 1 API=https://api.useapi.net/v1/muse AUTH="Authorization: Bearer $USEAPI_TOKEN" enc() { jq -rn --arg v "$1" '$v|@uri'; } post() { curl -sS -X POST "$API/$1" -H "$AUTH" -H "Content-Type: application/json" -d "$2"; } get() { curl -sS "$API/$1" -H "$AUTH"; } upload() { curl -sS -X POST "$API/assets?email=$(enc "$EMAIL")" -H "$AUTH" -H "Content-Type: $2" --data-binary @"$1" | jq -r .assetId; } download() { curl -sSf "$API/assets/$(enc "$1")" -H "$AUTH" -o "$2"; } # รันงานแบบ async: ส่งงาน แล้ว poll GET /jobs/{jobid} ทุก 10 วินาที บันทึกผลงานสุดท้ายลงไฟล์ $1 run() { local job id job=$(post "$2" "$(jq '. + {async: true}' <<< "$3")") id=$(jq -r .jobid <<< "$job") while [ "$(jq -r .status <<< "$job")" = started ]; do sleep 10 job=$(get "jobs/$(enc "$id")") done echo "$job" > "$1" jq '{status, error, text: .result.text, asset: .result.assets[0].assetId}' "$1" } ``` </details> การสร้างทุกครั้งทำงานเป็นงาน (job) ถ้าไม่ใส่ `async` คำขอ POST จะรอได้ราว 100 วินาที แล้วตอบกลับเป็นข้อมูลงานที่เสร็จแล้ว หรือ `202` ถ้างานยังทำอยู่ วิดีโอในบทความนี้ใช้เวลา 68 ถึง 138 วินาที ฟังก์ชัน `run` จึงส่งทุกงานด้วย `async: true` แล้ว poll [GET /jobs/`jobid`](/docs/api-muse-v1/get-muse-jobs-jobid) ถ้า `run` แสดง `status` อื่นที่ไม่ใช่ `completed` ให้อ่าน `error` ก่อนทำขั้นต่อไป ถ้าอยากให้ระบบเรียกกลับแทนการ poll ให้เพิ่ม `replyUrl: "https://example.com/hooks/muse"` (และ `replyRef` ถ้าต้องการ) ลงใน body ใดก็ได้ด้านล่าง API จะส่ง `POST` หนึ่งครั้งพร้อมข้อมูลงานสุดท้ายเป็น JSON ไปที่ URL นั้น id มีตัวอักษร `:` และ `@` ฟังก์ชัน `enc` จึงเข้ารหัส URL ให้ทุกครั้งที่ id อยู่ใน path ของ URL อินพุตทั้งหมดของงานหนึ่งต้องอยู่ในบัญชี Muse เดียวกัน การอัปโหลดจึงระบุ `email` ไว้ และงานจะทำงานบนบัญชีที่เก็บอินพุตของมัน ### สร้างขึ้นมาอย่างไร #### 1. เพิ่มบัญชี [POST /accounts](/docs/api-muse-v1/post-muse-accounts) รับอีเมลและรหัสผ่านของบัญชี Muse API ล็อกอินครั้งเดียว เก็บเซสชัน 30 วันไว้ และต่ออายุเซสชันเอง Muse จะส่งรหัสล็อกอินทางอีเมลทุกครั้งที่ล็อกอิน อีเมลนั้นเป็นแค่การแจ้งเตือน ไม่ต้องกรอกอะไร <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-accounts">POST /accounts</a></summary> ```bash post accounts "$(jq -n --arg email "$EMAIL" --arg password "$MUSE_PASSWORD" '{email: $email, password: $password}')" | jq '{health, maxJobs, quota}' ``` </details> คำตอบแสดง `health: "OK"`, `maxJobs` (ค่าเริ่มต้น 10) และแพ็กเกจกับการใช้งานของบัญชี ในที่นี้คือ `tier: "HATCH_FREE"` ซึ่งเป็นแพ็กเกจฟรี ถ้าตอบกลับเป็น `596` แปลว่า Meta ต้องการตรวจสอบความปลอดภัย ให้ล็อกอินที่ muse.ai ในเบราว์เซอร์หนึ่งครั้ง ทำการตรวจสอบให้เสร็จ แล้วส่งอีเมลและรหัสผ่านเดิมอีกครั้ง #### 2. อัปโหลดรูปถ่าย [POST /assets](/docs/api-muse-v1/post-muse-assets) รับไฟล์ดิบเป็น body ขนาดสูงสุด 50 MB และเขียนลงในพื้นที่ทำงาน (workspace) ของ Muse ในบัญชีนั้น useapi.net ไม่เก็บไฟล์ใดไว้ `assetId` ในคำตอบคือสิ่งที่งานรับเป็น `image_N` <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-assets">POST /assets</a></summary> ```bash BMW=$(upload bmw.jpeg image/jpeg) RIDER=$(upload rider.jpeg image/jpeg) BEACH=$(upload beach.jpeg image/jpeg) OLD_PHOTO=$(upload old-photo.jpeg image/jpeg) PINK=$(upload pink-hair.jpeg image/jpeg) echo "$BMW" # user:12345-email:6578616d706c6540676d61696c2e636f6d-image:7db53e7a1f0979cbab6ff46ec3f0a35b60e6ee579a0d738a9628cf46a0c7a0f5.jpg ``` </details> <div style="display: flex; flex-wrap: wrap; gap: 8px; align-items: flex-start"> <figure style="margin: 0; width: 32%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-motorcycle.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-motorcycle.jpg" alt="<code>image_1</code> — มอเตอร์ไซค์" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em"><code>image_1</code> — มอเตอร์ไซค์</figcaption></figure> <figure style="margin: 0; width: 18%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-redhead.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-redhead.jpg" alt="<code>image_2</code> — ผู้ขี่" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em"><code>image_2</code> — ผู้ขี่</figcaption></figure> <figure style="margin: 0; width: 32%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-beach.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-beach.jpg" alt="<code>image_3</code> — ชายหาด" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em"><code>image_3</code> — ชายหาด</figcaption></figure> <figure style="margin: 0; width: 18%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-oldphoto.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-oldphoto.jpg" alt="ภาพบุคคลเก่า" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">ภาพบุคคลเก่า</figcaption></figure> <figure style="margin: 0; width: 18%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-pinkhair.webp" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-pinkhair.webp" alt="ผู้ขี่คนที่สอง" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">ผู้ขี่คนที่สอง</figcaption></figure> </div> อินพุตทั้งห้า: มอเตอร์ไซค์ ผู้ขี่ ชายหาด ภาพบุคคลเก่า และผู้ขี่คนที่สอง asset id สร้างจากเนื้อหาของไฟล์ การอัปโหลดไฟล์เดิมเข้าบัญชีเดิมซ้ำจึงได้ id เดิม และไม่เขียนอะไรเพิ่ม #### 3. ภาพจากข้อความ Muse ไม่มีพารามิเตอร์อัตราส่วนภาพ ต้องเขียนไว้ใน prompt เริ่มจากภาพบุคคลแนวตั้ง: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-image">POST /jobs/image</a></summary> ```bash run portrait.json jobs/image "$(jq -n '{prompt: "Vertical 9:16 full-body portrait photo: a confident young woman biker with long wavy fiery red hair, green eyes and freckles, in a worn black leather jacket, dark jeans and boots, standing in a rain-soaked neon alley at dusk, looking straight at the camera, cinematic lighting, photorealistic."}')" download "$(jq -r '.result.assets[0].assetId' portrait.json)" portrait.webp ``` </details> <img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-a2.webp" style="width: 100%; max-width: 420px" alt="ข้อความเป็นภาพ อัตราส่วน 9:16"> [เปิดในแท็บใหม่](https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-a2.webp){:target="_blank"} ภาพนี้ได้อัตราส่วน 9:16 พอดี คือ 1152×2048 ส่วนภาพแนวนอนที่สั่งว่า `Cinematic 16:9 landscape photo: …` ได้กลับมาเป็น 1920×1280 ซึ่งเป็น 3:2 พอเขียนอัตราส่วนว่า `in exactly 16:9 aspect ratio` ก็ได้ตามที่ต้องการ: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-image">POST /jobs/image</a></summary> ```bash run bmw-noir.json jobs/image "$(jq -n '{prompt: "In exactly 16:9 aspect ratio (landscape), a cinematic photo of a vintage 1920s black BMW motorcycle with white pinstripes, spoked wheels and a brown leather saddle, parked on wet cobblestones at night in San Francisco, the Golden Gate Bridge glowing through fog in the distance, neo-noir moonlight, reflections on the wet street, shot on 35mm film."}')" download "$(jq -r '.result.assets[0].assetId' bmw-noir.json)" bmw-noir.webp ``` </details> <img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-a5.webp" style="width: 100%" alt="ข้อความเป็นภาพ อัตราส่วน 16:9 พอดี"> [เปิดในแท็บใหม่](https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-a5.webp){:target="_blank"} Muse ตอบว่า "That 16:9 frame with the bridge ghosting through the fog is pure neo-noir. Enjoy." ข้อความตอบกลับของ Muse อยู่ใน `result.text` #### 4. รวมรูปถ่ายสามรูปเป็นภาพเดียว งานหนึ่งรับภาพได้สูงสุด 9 ภาพ เป็น `image_1`..`image_9` และ prompt อ้างถึงภาพเหล่านั้นด้วยชื่อ ในที่นี้มอเตอร์ไซค์คือ `image_1` ผู้ขี่คือ `image_2` และชายหาดคือ `image_3` prompt ขอให้ Muse ใช้ชายหาดตามรูปถ่ายจริง สะพาน Golden Gate จึงอยู่ตำแหน่งเดิมเหมือนในรูป <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-image">POST /jobs/image</a></summary> ```bash run beach-ride.json jobs/image "$(jq -n --arg bmw "$BMW" --arg rider "$RIDER" --arg beach "$BEACH" \ '{image_1: $bmw, image_2: $rider, image_3: $beach, prompt: "In exactly 16:9 aspect ratio (landscape), a cinematic photo: the woman from image_2 (her face, long wavy red hair, light blue top and jeans) riding the exact vintage motorcycle from image_1 along the shoreline of the beach in image_3, the front wheel cutting through the shallow surf and throwing spray, bright afternoon sun, her hair streaming in the wind, photorealistic. Use the beach, rocks and Golden Gate Bridge from image_3 as the background exactly as photographed: same position, same orientation, not mirrored or redrawn. Keep her face and the motorcycle'\''s design exactly as in the images."}')" BEACH_RIDE=$(jq -r '.result.assets[0].assetId' beach-ride.json) download "$BEACH_RIDE" beach-ride.webp ``` </details> <img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g1.webp" style="width: 100%" alt="ผู้ขี่ มอเตอร์ไซค์ และชายหาดในภาพเดียว"> [เปิดในแท็บใหม่](https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g1.webp){:target="_blank"} ใช้เวลา 31 วินาที และโควตารายสัปดาห์ไม่เปลี่ยนให้เห็น #### 5. ภาพกลายเป็นวิดีโอ ไม่ต้องอัปโหลดใหม่ `BEACH_RIDE` คือ id ของไฟล์ที่ Muse สร้าง ไฟล์อยู่ใน workspace ของบัญชีอยู่แล้ว จึงส่งเข้างานถัดไปเป็น `image_1` ได้ทันที ไม่ต้องดาวน์โหลดหรืออัปโหลด `Animate image_1` สร้างคลิปที่เริ่มจากภาพและคงรูปทรงของภาพไว้ และประโยคในเครื่องหมายคำพูดจะถูกพูดออกมา <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-video">POST /jobs/video</a></summary> ```bash run surf.json jobs/video "$(jq -n --arg img "$BEACH_RIDE" '{image_1: $img, prompt: "Animate image_1 into a cinematic video in exactly 16:9 aspect ratio (landscape): she rides the vintage motorcycle along the shoreline, the front wheel slices through the shallow waves and sends spray flying, the old engine roars, she raises one fist and shouts with a laugh: \"Nothing beats this view!\" The camera tracks alongside her. The beach, the rocks and the Golden Gate Bridge stay exactly as in image_1 (same orientation). Keep her face and the motorcycle exactly as in image_1."}')" SURF=$(jq -r '.result.assets[0].assetId' surf.json) download "$SURF" surf.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g2-poster.jpg" src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g2.mp4" style="width: 100%; aspect-ratio: 16/9; max-width: 720px" controls type="video/mp4" preload="metadata"></video> ดูบน YouTube ได้ด้วย: [3 photos in, 1 talking video out: Meta Muse API from REST](https://youtube.com/shorts/v_7mREyFSWk) ได้คลิป 10 วินาทีที่ 1280×720 พร้อมเสียง Muse ตอบว่า "Done. 10 seconds, 16:9 landscape, straight from your image — no edits, no upscaling." ครั้งแรกที่รันงานนี้ล้มเหลวหลัง 37 วินาที Muse ตอบว่า "the video worker glitched out before it rendered anything, so no clip was made" API รายงานคำตอบแบบนี้เป็น `503` ซึ่งไม่ได้สร้างอะไร และคำขอเดิมก็ทำงานได้เมื่อรันอีกครั้ง ส่วนการปฏิเสธเพราะเนื้อหาจะเป็น `403` และต้องเปลี่ยน prompt #### 6. บูรณะและลงสีภาพเก่า งานสร้างภาพซ่อมภาพได้ด้วย ภาพบุคคลเก่าเป็นภาพสีซีเปียซีดจาง ขนาด 685×900 พิกเซล อัตราส่วน 3:4 prompt ระบุสิ่งที่ต้องแก้ และย้ำให้คงกรอบภาพเดิม <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-image">POST /jobs/image</a></summary> ```bash run restored.json jobs/image "$(jq -n --arg img "$OLD_PHOTO" '{image_1: $img, prompt: "Restore the old photograph image_1 as a high-quality modern photo: remove the scratches, dust, stains, fading and grain, recover sharp detail in the face, hair and fabric, and colorize it naturally (warm natural skin tones, dark brown hair, ivory tulle shawl, a soft pink rose with green leaves, a muted warm background). Keep the exact same person, expression, pose, framing and crop, and the same portrait aspect ratio as image_1 (3:4, 685×900): do not crop, extend or reframe it."}')" RESTORED=$(jq -r '.result.assets[0].assetId' restored.json) download "$RESTORED" restored.webp ``` </details> <div style="display: flex; flex-wrap: wrap; gap: 8px; align-items: flex-start"> <figure style="margin: 0; width: 48%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-oldphoto.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-oldphoto.jpg" alt="ก่อน: ภาพต้นฉบับ 685×900" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">ก่อน: ภาพต้นฉบับ 685×900</figcaption></figure> <figure style="margin: 0; width: 48%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-e1.webp" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-e1.webp" alt="หลัง: บูรณะและลงสีแล้ว 1344×1792" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">หลัง: บูรณะและลงสีแล้ว 1344×1792</figcaption></figure> </div> ผลลัพธ์มีขนาด 1344×1792 เป็นกรอบ 3:4 เดิมที่ใหญ่ขึ้นราวสองเท่า ท่าทางและการครอปเหมือนเดิม Muse ตอบว่า "Done — restored, de-grained, and colorized, same framing and pose." #### 7. ภาพบุคคลมีชีวิตขึ้นมา ภาพที่บูรณะแล้วส่งเข้างานวิดีโอได้ทันที คลิปคงรูปทรงของภาพบุคคลไว้ จึงได้กลับมาเป็น 832×1104 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-video">POST /jobs/video</a></summary> ```bash run portrait-video.json jobs/video "$(jq -n --arg img "$RESTORED" '{image_1: $img, prompt: "Animate image_1 into a video with the same portrait frame: the young woman slowly lifts her eyes to the camera, her smile widens, she gently touches the rose on her shoulder and says softly: \"It has been a hundred years... and you still remember me.\" A light breeze moves a few strands of her hair, soft window light, the camera stays still with a very slow push-in. Keep her face exactly as in image_1."}')" download "$(jq -r '.result.assets[0].assetId' portrait-video.json)" portrait.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-e2-poster.jpg" src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-e2.mp4" style="width: 100%; aspect-ratio: 832/1104; max-width: 420px" controls type="video/mp4" preload="metadata"></video> ดูบน YouTube ได้ด้วย: [This old portrait just spoke: one API call (Meta Muse API, third-party)](https://youtube.com/shorts/GLHoINX_ozE) #### 8. สลับผู้ขี่ในวิดีโอ งานวิดีโอรับวิดีโอเป็นอินพุตได้ด้วย `video_1` คือคลิปขี่ฝ่าคลื่นจากขั้นตอนที่ 5 และ `image_1` คือรูปผู้หญิงคนที่สองผมสีชมพูมัดเป็นสองจุก prompt ขอให้ Muse เปลี่ยนผู้ขี่และคงทุกอย่างที่เหลือไว้ แล้วให้เธอพูดประโยคใหม่ <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-video">POST /jobs/video</a></summary> ```bash run swap.json jobs/video "$(jq -n --arg vid "$SURF" --arg img "$PINK" '{video_1: $vid, image_1: $img, prompt: "Edit video_1: replace the rider with the woman from image_1 (her face, pink hair in two buns, colorful makeup and tattoos), and keep everything else the same: the motorcycle, the beach, the waves and spray, the Golden Gate Bridge, the light, the camera move and the timing. Instead of the original line she shouts: \"Catch me if you can, San Francisco!\" Keep the 16:9 frame and the same length."}')" download "$(jq -r '.result.assets[0].assetId' swap.json)" swap.mp4 ``` </details> <div style="display: flex; flex-wrap: wrap; gap: 8px; align-items: flex-start"> <figure style="margin: 0; width: 48%"><video poster="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g2-poster.jpg" src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g2.mp4" style="width: 100%; aspect-ratio: 16/9" controls type="video/mp4" preload="metadata"></video><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">ก่อน: ผู้ขี่คนเดิม</figcaption></figure> <figure style="margin: 0; width: 48%"><video poster="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g3-poster.jpg" src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g3.mp4" style="width: 100%; aspect-ratio: 1248/704" controls type="video/mp4" preload="metadata"></video><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">หลัง: ผู้ขี่จากรูปถ่าย</figcaption></figure> </div> งานนี้ใช้เวลา 138 วินาที ช้าที่สุดในบทความ ทุกงานในบทความนี้จึงรันแบบ async คลิปที่ได้คือฉากขี่เดิม แต่มีผู้หญิงอีกคนอยู่บนมอเตอร์ไซค์และตะโกนประโยคใหม่ Muse ตอบว่า "Done. She's in, 10 seconds, 16:9, same ride, same bridge, same waves." ดูบน YouTube ได้ด้วย: [Replace the person in a video, keep everything else: Meta Muse API](https://youtube.com/shorts/XDCY1XIsd5Y) #### 9. ตรวจโควตารายสัปดาห์ [GET /accounts/`email`](/docs/api-muse-v1/get-muse-accounts-email) อ่านแพ็กเกจและการใช้งานของบัญชีแบบสด: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/get-muse-accounts-email">GET /accounts/email</a></summary> ```bash get "accounts/$(enc "$EMAIL")" | jq '{session, quota}' ``` </details> `quota.percentUsed` คือสัดส่วนของสัปดาห์ที่ใช้ไปเป็นเปอร์เซ็นต์เต็ม และ `quota.resetsAt` คือเวลาที่โควตาเริ่มใหม่ หนึ่งสัปดาห์หลังจากเริ่มนับ วิดีโอสามคลิปข้างบนใช้คลิปละ 2 ถึง 3 เปอร์เซ็นต์ และภาพใช้ 0 หรือ 1 ตลอดการทดสอบทั้งหมด ซึ่งมีงานอีกสองงานที่ไม่ได้แสดงในที่นี้ บัญชีฟรีเพิ่มจาก 16 เป็น 28 เปอร์เซ็นต์ เมื่อบัญชีใช้โควตาหมด งานใหม่ที่ไม่ระบุ `email` จะไปที่บัญชีอื่นของคุณ และงานที่ระบุบัญชีนั้นจะได้ `412` จนถึง `resetsAt` ### สิ่งที่เราได้เรียนรู้ - เขียนอัตราส่วนภาพว่า `in exactly 16:9 aspect ratio` เพราะ `Cinematic 16:9 landscape photo` เคยได้กลับมาเป็น 3:2 - วิดีโอทุกคลิปยาวราว 10 วินาที prompt ที่ขอ 5 วินาทีก็ยังได้ 10 วินาที - คลิปจากภาพเป็นวิดีโอจะคงรูปทรงของภาพไว้ เว้นแต่ prompt ขอรูปทรงอื่น `in exactly 9:16 aspect ratio` เปลี่ยนภาพชายหาด 16:9 ของเราเป็นคลิปแนวตั้ง 720×1280 โดยจัดกรอบใหม่ ไม่ได้ยืดภาพ - ประโยคที่เขียนในเครื่องหมายคำพูดใน prompt วิดีโอจะถูกพูดออกมา - ส่งไฟล์ที่สร้างแล้วต่อด้วย `assetId` ไฟล์อยู่ใน workspace ของบัญชี การแก้ไขต่อกันหลายขั้นจึงไม่ต้องดาวน์โหลดระหว่างทาง - บอกให้ชัดว่าอะไรต้องคงเดิม "Same position, same orientation, not mirrored or redrawn" ทำให้ชายหาดจริงยังอยู่ในภาพรวม - `503` ที่มาพร้อมคำพูดของ Muse เอง เช่น "glitched out" ควรรันใหม่ ส่วน `403` คือการปฏิเสธ และต้องเปลี่ยน prompt - ส่งงานวิดีโอด้วย `async: true` คำขอแบบ sync รอได้ราว 100 วินาที แต่การสลับผู้ขี่ใช้ 138 วินาที ### ทำคลิป Short 30 วินาทีพร้อมเสียงบรรยาย (บท สามฉาก และรวมคลิป) วิดีโอ Muse ยาวราว 10 วินาทีเสมอ คลิป Short แนวตั้ง 30 วินาทีที่มีผู้บรรยายจึงต้องใช้งานวิดีโอสามงานและแชตสองครั้ง [แชต](/docs/api-muse-v1/post-muse-chats) แรกเขียนบทเป็น JSON [งานวิดีโอ](/docs/api-muse-v1/post-muse-jobs-video) สามงานรันพร้อมกัน ฉากละหนึ่งงาน แต่ละงานพูดประโยคของตัวเองด้วยเสียงผู้บรรยายคนเดียวกัน และแชตสุดท้ายรวมคลิปด้วย ffmpeg ใน workspace ของบัญชีเอง คลิป Short ด้านล่างเล่าเรื่องการปะทุของภูเขาไฟ Tambora ในปี 1815 และ "ปีที่ไม่มีฤดูร้อน" ที่ตามมา ใช้เวลาจากหัวข้อหนึ่งบรรทัดจนได้ MP4 ราว 2 นาที <video poster="https://media.useapi.net/articles/2026-10-12-muse-images-videos-id/muse-narrated-short-tambora-poster.jpg" src="https://media.useapi.net/articles/2026-10-12-muse-images-videos-id/muse-narrated-short-tambora.mp4" style="width: 100%; aspect-ratio: 9/16; max-width: 420px" controls type="video/mp4" preload="metadata"></video> ดูบน YouTube ได้ด้วย: [A narrated 30-second Short made only with Meta Muse API calls](https://youtube.com/shorts/1e8f7dHTkzs) คลิป 10 วินาทีสามคลิปรวมเป็น Short เดียวขนาด 720×1280 ยาว 30 วินาที จากหัวข้อ "how a single volcano cooled the whole planet in 1816" บทใช้เวลา 11 วินาที คลิปทั้งสามใช้ 75, 75 และ 87 วินาทีโดยรันพร้อมกัน และการรวมคลิปใช้ 20 วินาที Short หนึ่งคลิปจึงใช้เวลาราว 2 ถึง 3 นาที คลิปนี้สร้างบนแพ็กเกจ Muse แบบเสียเงิน ซึ่งวิดีโอสี่คลิปในการทดสอบครั้งนั้น (สามคลิปนี้และอีกหนึ่งคลิป) ทำให้ตัวเลขรายสัปดาห์ขยับรวม 2 จุด และแชตไม่ทำให้ขยับเลย บนแพ็กเกจฟรี วิดีโอหนึ่งคลิปใช้ 2 ถึง 3 เปอร์เซ็นต์ของสัปดาห์ Short สามฉากจึงใช้ราว 6 ถึง 9 เปอร์เซ็นต์ ถ้าไม่อยากเขียนโค้ด ขั้นตอนเดียวกันนี้มีเป็นแอป n8n คือเทมเพลต [Narrated Faceless Shorts]({% include n8n-url.html t="muse-shorts" %}) ที่มีฟอร์ม หน้าบท และบันทึกลง Google Drive ตัวอย่าง Short สองคลิปที่เทมเพลตนี้สร้าง เผยแพร่ตามที่ได้ออกมา: [The Great Pyramid was once bright white](https://youtube.com/shorts/D-Nk0x9aJMo) และ [Why honey never spoils](https://youtube.com/shorts/bYLsJIqerSM) ซึ่งใช้เสียงจาก text to speech ของ Muse ทั้งเวิร์กโฟลว์ยังมีเป็นสคริปต์เดียว ทั้ง Node.js และ Python: [`narrated-short/`](https://github.com/useapi/muse-api/tree/main/narrated-short) ใน [useapi/muse-api](https://github.com/useapi/muse-api) สคริปต์รับหัวข้อ และจะระบุจำนวนฉากกับคำอธิบายผู้บรรยายเองก็ได้ แล้วบันทึก Short ลงใน `output/` ขั้นตอนต่าง ๆ ใช้[ฟังก์ชันช่วยข้างบน](#before-you-start) และ `chat` ซึ่งเริ่มแชตแล้วอ่าน [GET /chats/`chatId`](/docs/api-muse-v1/get-muse-chats-chatId) จนกว่า Muse จะทำเสร็จ: <details markdown="block"> <summary>เปิดดูฟังก์ชันช่วยสำหรับแชต</summary> ```bash # เริ่มแชต poll GET /chats/{chatId} ทุก 8 วินาทีจนกว่า Muse จะเสร็จ แล้วบันทึกแชตลงไฟล์ $1 chat() { local id c id=$(post chats "$2" | jq -r .chatId) while sleep 8; do c=$(get "chats/$(enc "$id")") jq -e '.pendingApprovals | length > 0' <<< "$c" > /dev/null && echo "Muse asks for permission: answer it with POST /chats/{chatId}/approvals/{approvalId}" jq -e '(.status | IN("completed", "interrupted", "failed")) and (.pendingApprovals | length == 0)' <<< "$c" > /dev/null && break done echo "$c" > "$1" jq '{status, reply: ([.messages[] | select(.role == "assistant" and .text != "")][-1].text)}' "$1" } ``` </details> ทุกคำขอด้านล่างระบุ `email` แชตที่รับไฟล์ต้องรันบนบัญชีที่เก็บไฟล์นั้น คลิปทั้งสามและการรวมคลิปจึงอยู่บนบัญชีเดียวกันทั้งหมด #### 1. เขียนบทเป็น JSON แชตแรกขอบทที่มีสามฉากพอดี และระบุรูปแบบ JSON ไว้ละเอียด แต่ละฉากมี `line` คือสิ่งที่ผู้บรรยายพูด จำกัดไว้ 25 คำให้พอดีกับ 10 วินาที และ `visual` คือหนึ่งประโยคที่บรรยายภาพในฉาก prompt ยังบอก Muse ไม่ให้สร้างไฟล์ใด ๆ แชตจึงเป็นข้อความล้วน <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-chats">POST /chats</a></summary> ```bash TOPIC="how a single volcano cooled the whole planet in 1816" chat script.json "$(jq -n --arg email "$EMAIL" --arg topic "$TOPIC" '{email: $email, message: "Write a script for a 30-second faceless YouTube Short about: \"\($topic)\". Exactly 3 scenes. Reply with ONLY a JSON object, no prose, no markdown code fences, in this exact shape: {\"title\": string, \"scenes\": [{\"line\": string, \"visual\": string}, {\"line\": string, \"visual\": string}, {\"line\": string, \"visual\": string}]}. \"line\" is what the off-screen narrator says (at most 25 words, about 9 seconds spoken). \"visual\" is a one-sentence description of the 10-second shot, no people talking on camera. Do not create any files, images or videos."}')" jq -r '[.messages[] | select(.role == "assistant" and .text != "")][-1].text' script.json | sed '/^```/d' > scenes.json jq . scenes.json ``` </details> Muse ตอบภายใน 11 วินาทีด้วย JSON อย่างเดียว: ```json { "title": "How One Volcano Cooled the Whole Planet in 1816", "scenes": [ { "line": "In April 1815, Mount Tambora in Indonesia erupted, the largest explosion in recorded history, blasting ash forty kilometers into the sky.", "visual": "A massive volcanic eruption at dawn, with a towering ash column rising into the stratosphere above a dark island." }, { "line": "That ash veil circled Earth, blocking sunlight and dropping global temperatures, turning summer into winter across North America and Europe.", "visual": "An animated globe wrapped in a gray haze as sunlight dims and frost spreads across continents." }, { "line": "1816 became the Year Without a Summer: crops failed, snow fell in July, and famine spread as the planet shivered.", "visual": "Snow falling over green farmland in summer, covering withered crops and empty village fields under a pale sun." } ] } ``` เรารัน prompt เดียวกันกับสามหัวข้อ และได้ JSON สะอาดทุกครั้ง ใช้เวลา 11 ถึง 29 วินาที ไม่มี code fence และไม่มีข้อความอื่นเกินมา แต่ตัวอย่างยังน้อย คำสั่ง `sed` จึงลบบรรทัด ```` ``` ```` ที่หลุดมาไว้ก่อน และสคริปต์บน GitHub จะขอใหม่อีกครั้งเมื่อคำตอบแปลงเป็น JSON ไม่ได้ #### 2. สามฉากพร้อมกัน แต่ละฉากกลายเป็น [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video) แบบ async หนึ่งงาน prompt ทั้งสามมีคำอธิบายผู้บรรยายเดียวกันทุกคำ ตามด้วย `The narrator says exactly: "<line>"` Muse พูดประโยคในเครื่องหมายคำพูดตามที่เขียนไว้ และคำอธิบายที่ใช้ร่วมกันทำให้เสียงคงที่จากคลิปหนึ่งไปอีกคลิป `Vertical 9:16 video` ได้กลับมาเป็น 720×1280 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-video">POST /jobs/video</a></summary> ```bash NARRATOR="Narration: one off-screen narrator only, the same voice throughout: a calm, deep, middle-aged British male documentary narrator, measured pace, warm and authoritative, like a nature documentary. Nobody on screen speaks. No music." for i in 0 1 2; do post jobs/video "$(jq --arg email "$EMAIL" --arg narrator "$NARRATOR" --argjson i $i '.scenes[$i] | {email: $email, async: true, prompt: "Vertical 9:16 video, about 10 seconds. \(.visual) Slow cinematic camera move, photoreal. \($narrator) The narrator says exactly: \"\(.line)\""}' scenes.json)" | jq -r .jobid done > jobs.txt ``` </details> POST แต่ละครั้งตอบ `201` ทันทีพร้อม `jobid` สามงานนี้ใช้สามช่องจาก `maxJobs` ของบัญชี (ค่าเริ่มต้น 10) จึงรันพร้อมกันได้ ถ้าได้ `429` ตรงนี้ แปลว่าทุกช่องไม่ว่างและยังไม่มีงานใดเริ่ม ให้ส่งงานนั้นใหม่ใน 30 วินาที #### 3. Poll งาน [GET /jobs/`jobid`](/docs/api-muse-v1/get-muse-jobs-jobid) ตอบ `status: "started"` จนกว่าคลิปจะพร้อม งานรันขนานกัน การอ่านทีละงานต่อกันจึงไม่ทำให้ใช้เวลานานขึ้น: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/get-muse-jobs-jobid">GET /jobs/jobid</a></summary> ```bash for n in 1 2 3; do id=$(sed -n "${n}p" jobs.txt) until job=$(get "jobs/$(enc "$id")"); [ "$(jq -r .status <<< "$job")" != started ]; do sleep 10; done echo "$job" > clip$n.json jq '{status, error, text: .result.text, asset: .result.assets[0].assetId}' clip$n.json done ``` </details> ทั้งสามงานเสร็จสมบูรณ์ Muse ตอบเรื่องคลิปแรกว่า "Here it is — vertical 9:16, photoreal volcanic eruption at dawn with the narration as specified" แต่ละคลิปพูดประโยคของตัวเองตรงทุกคำ และทุกประโยคที่ยาว 20 ถึง 21 คำพอดีกับ 10 วินาที งานที่ล้มเหลวด้วย `503` ไม่ได้สร้างอะไร และรันใหม่ได้ ความล้มเหลวแบบอื่น เช่น การปฏิเสธ `403` ต้องอ่าน `error.message` ก่อน #### 4. รวมคลิปในแชตเดียว id ของคลิปทั้งสามส่งเข้าแชตเดียวเป็น `files` ซึ่ง Muse เห็นเป็น `video_1`, `video_2` และ `video_3` ข้อความขอให้ใช้ ffmpeg ระบุลำดับ เสียง และชื่อไฟล์ แล้วปิดท้ายด้วย `No public links.` เมื่อมีประโยคนี้ Muse ไม่หยุดถามขออนุญาต <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-chats">POST /chats</a></summary> ```bash CLIPS=$(jq -s '[.[].result.assets[0].assetId]' clip1.json clip2.json clip3.json) chat join.json "$(jq -n --arg email "$EMAIL" --argjson files "$CLIPS" '{email: $email, files: $files, message: "Concatenate video_1, video_2, video_3 in order into one MP4 with ffmpeg, keep the audio, save it to workspace/your_files/short.mp4 and attach it here. No public links."}')" SHORT=$(jq -r '[.messages[] | select(.role == "assistant") | .files[] | select(.type == "video")][-1].assetId' join.json) echo "$SHORT" # user:12345-email:6578616d706c6540676d61696c2e636f6d-video:ws~your_files~short.mp4 ``` </details> 20 วินาทีต่อมา Muse ตอบว่า "Concatenated all three in order — 30 seconds, 720x1280, with audio kept." และแนบไฟล์มาเป็นข้อความแยก ซึ่งมี `video` หนึ่งไฟล์ใน `files` asset id ของไฟล์ตั้งชื่อตาม path ใน workspace จึงควรตั้งชื่อไฟล์ของ Short แต่ละคลิปไม่ให้ซ้ำกัน ffmpeg คัดลอกสตรีมโดยไม่เข้ารหัสใหม่ Short จึงยาว 30.0 วินาทีพอดี และมีทั้งสามประโยคเรียงตามลำดับ #### 5. ดาวน์โหลด Short [GET /assets/`assetId`](/docs/api-muse-v1/get-muse-assets-assetId) ส่งไฟล์ MP4 กลับมา: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/get-muse-assets-assetId">GET /assets/assetId</a></summary> ```bash download "$SHORT" tambora-short.mp4 ``` </details> คลิปและ Short ยังอยู่ใน workspace ของ Muse ในบัญชี ซึ่งแอป muse.ai แสดงให้เห็น และ asset id ของ Short ส่งเข้างานถัดไปเป็น `video_1` ได้ #### ใช้เสียงคงที่แทน: text to speech เป็น audio_1 คำอธิบายที่ใช้ร่วมกันให้เสียงแนวเดียวกัน แต่ไม่ได้ล็อกเสียงไว้ ในคลิป Tambora ทั้งสาม ค่ากลางของระดับเสียงผู้บรรยายอยู่ที่ 105 ถึง 117 Hz ห่างกันไม่ถึงสองครึ่งเสียง แต่ Muse สร้างเสียงใหม่ทุกคลิป ถ้าต้องการเสียงเดียวแน่นอน ให้ Muse อ่านแต่ละประโยคด้วย text to speech ก่อน แล้วส่ง MP3 นั้นเข้างานวิดีโอเป็น `audio_1` แชต text to speech ใช้เวลา 20 วินาทีในการทดสอบของเรา <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-chats">POST /chats</a> และ <a href="/docs/api-muse-v1/post-muse-jobs-video">POST /jobs/video</a></summary> ```bash chat voice1.json "$(jq -n --arg email "$EMAIL" --arg line "$(jq -r '.scenes[0].line' scenes.json)" '{email: $email, message: "Generate one mp3 file with text to speech: single speaker, voice Aria (avocado_v2:MAI_01), speed 100, language en, clean narration only: no music, no sound effects. Read exactly this text, do not change any word:\n\"\($line)\"\nSave it directly in workspace/your_files/ (not in a subfolder) as line-1.mp3 and attach it here. No public links and no uploads to remote storage."}')" VOICE1=$(jq -r '[.messages[] | select(.role == "assistant") | .files[] | select(.type == "audio")][-1].assetId' voice1.json) run clip1.json jobs/video "$(jq --arg email "$EMAIL" --arg voice "$VOICE1" '.scenes[0] | {email: $email, audio_1: $voice, prompt: "Vertical 9:16 video, about 10 seconds, no people on screen and nobody speaking on camera. \(.visual) Slow cinematic camera move, photoreal. Use audio_1 as the narration soundtrack exactly as it is: the off-screen narrator'\''s voice in audio_1, word for word, with no other voice and no new speech. Quiet ambient sound under it is fine."}' scenes.json)" jq -r '.result.assets[] | select(.origin == "made") | .assetId' clip1.json ``` </details> Muse สร้างคลิปของตัวเองก่อน แล้ววาง `audio_1` ลงไปด้วย ffmpeg งานแสดงทั้งสองไฟล์ ไฟล์ที่เสร็จแล้วมาก่อนพร้อม `origin: "made"` และคลิปดิบของ Muse ตามมาพร้อม `origin: "generated"` ให้ใช้ไฟล์ `made` เพราะคลิปดิบมีเสียงที่ Muse สร้างขึ้นเองแทนเสียงของคุณ งานวิดีโอนี้ใช้เวลา 108 วินาทีในการทดสอบของเรา ทำซ้ำกับทุกฉาก แล้วรวมคลิป `made` เหมือนในขั้นตอนที่ 4 ### คำถามที่พบบ่อย **Meta Muse (muse.ai) มี API ไหม?** ผ่าน useapi.net มี [Muse API](/docs/api-muse-v1) เป็น API ของบุคคลที่สามที่สั่งงาน Muse บน[แพ็กเกจเว็บไซต์ Muse](https://www.meta.com/help/subscriptions/1021145227643680/) ของคุณ สร้างภาพด้วย [POST /jobs/image](/docs/api-muse-v1/post-muse-jobs-image) และวิดีโอด้วย [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video) ส่วน [Model API](https://dev.meta.ai/docs/pricing-rate-limits) ทางการของ Meta ขายโมเดล Muse Image ที่ $0.01 ต่อภาพ แต่ ณ ตุลาคม 2026 ยังสร้างวิดีโอไม่ได้ และไม่มี API สำหรับเอเจนต์ Muse ที่ muse.ai ซึ่งเป็นที่สร้างวิดีโอ บทความ[เปรียบเทียบ Meta Muse video API](/docs/articles/meta-muse-video-api) ของเราพูดถึง muse2api ด้วย **ใช้กับแพ็กเกจ Muse ฟรีได้ไหม?** ผ่าน useapi.net ได้ บทความนี้ทำบนแพ็กเกจฟรี (`HATCH_FREE`) ซึ่งมีโควตารายสัปดาห์ วิดีโอหนึ่งคลิปใช้ 2 ถึง 3 เปอร์เซ็นต์ และภาพหนึ่งภาพใช้ 0 ถึง 1 เปอร์เซ็นต์ บัญชีฟรีหนึ่งบัญชีจึงสร้างวิดีโอได้ราว 30 ถึง 50 คลิปต่อสัปดาห์ แพ็กเกจเสียเงิน Power ($20 ต่อเดือน) และ Maximum ($100 ต่อเดือน) เพิ่มโควตาให้มากขึ้น (ข้อมูล ณ ตุลาคม 2026) **Muse สร้างวิดีโอยาวเกิน 10 วินาทีได้ไหม?** ผ่าน useapi.net ทำในงานเดียวไม่ได้ วิดีโอทุกคลิปยาวราว 10 วินาที ให้สร้างฉากละหนึ่งคลิป แล้วให้[แชต](/docs/api-muse-v1/post-muse-chats)รวมคลิปด้วย ffmpeg เหมือนใน[ทำคลิป Short 30 วินาทีพร้อมเสียงบรรยาย](#make-a-30-second-narrated-short-script-three-scenes-one-join) ซึ่งสามคลิปกลายเป็น Short เดียวในราว 2 ถึง 3 นาที (ข้อมูล ณ ตุลาคม 2026) แชตหนึ่งรับวิดีโอได้สูงสุด 3 คลิป **ตั้งอัตราส่วนภาพ ความยาว หรือความละเอียดอย่างไร?** ผ่าน useapi.net ให้เขียนใน prompt เพราะ Muse ไม่มีพารามิเตอร์สำหรับสิ่งเหล่านี้ อัตราส่วนภาพจะได้ตามที่ต้องการเมื่อเขียนว่า `in exactly 16:9 aspect ratio` และคลิปจากภาพเป็นวิดีโอจะคงรูปทรงของภาพไว้ เว้นแต่ prompt ขอรูปทรงอื่น ความยาวและความละเอียดคงที่ วิดีโอทุกคลิปได้กลับมาราว 720p ยาวราว 10 วินาทีพร้อมเสียง ไม่ว่า prompt จะขออะไร (ข้อมูล ณ ตุลาคม 2026) **ใช้รูปถ่ายและวิดีโอของตัวเองได้ไหม?** ผ่าน useapi.net ได้ อัปโหลดด้วย [POST /assets](/docs/api-muse-v1/post-muse-assets) ไฟล์ละไม่เกิน 50 MB แล้วส่ง `assetId` เป็น `image_1`..`image_9` แบบเดียวกับการส่งผลลัพธ์จากงานก่อนหน้า [งานวิดีโอ](/docs/api-muse-v1/post-muse-jobs-video) ยังรับ `video_1`..`video_3` และ `audio_1`..`audio_3` ได้ด้วย อินพุตทั้งหมดของงานหนึ่งต้องอยู่ในบัญชีเดียวกัน **ทำรูปถ่ายให้พูดได้อย่างไร?** ผ่าน useapi.net ส่งรูปเป็น `image_1` ไปที่ [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video) พร้อม prompt แบบ `Animate image_1: … she says softly: "…"` Muse คงรูปทรงของภาพไว้และพูดประโยคในเครื่องหมายคำพูด เหมือนใน[ขั้นตอนที่ 7](#step-7-the-portrait-comes-to-life) ที่ภาพบุคคลอายุร้อยปีซึ่งบูรณะแล้วเงยหน้าขึ้นและพูดได้ในคลิปเดียว 10 วินาที ใช้เวลา 68 วินาที **เปลี่ยนคนในวิดีโอได้ไหม?** ผ่าน useapi.net ได้ ส่งคลิปเป็น `video_1` และรูปของคนใหม่เป็น `image_1` แล้วขอให้ Muse เปลี่ยนคนและคงทุกอย่างที่เหลือไว้ เหมือนใน[ขั้นตอนที่ 8](#step-8-swap-the-rider-in-the-video) ซึ่งใช้เวลา 138 วินาที บอกให้ชัดว่าอะไรต้องคงเดิม เช่น ฉากขี่ สะพาน และคลื่น และใส่ประโยคในเครื่องหมายคำพูดให้คนใหม่ถ้าต้องการให้พูด **ทำไมคำขอแบบ sync ได้ 202?** ผ่าน useapi.net `202` หมายถึงงานยังทำอยู่หลังผ่านไปราว 100 วินาที และยังทำต่อในฝั่งของเรา ดึงผลด้วย [GET /jobs/`jobid`](/docs/api-muse-v1/get-muse-jobs-jobid) ส่งงานที่ใช้เวลานานด้วย `async: true` แล้ว poll หรือเพิ่ม `replyUrl` เพื่อให้ระบบส่งข้อมูลงานที่เสร็จแล้วมาให้คุณ ในการทดสอบของเรา วิดีโอหนึ่งคลิปใช้เวลา 68 ถึง 138 วินาที **ทำไม Muse ส่งรหัสล็อกอินมาทางอีเมล?** ผ่าน useapi.net API ล็อกอินเข้าบัญชี Muse ของคุณ ซึ่งเกิดขึ้นตอนเพิ่มบัญชี และตอนที่ API ต่ออายุเซสชัน 30 วัน ก่อนเซสชันหมดอายุหรือเมื่อ Muse ขอให้ล็อกอินใหม่ Muse ส่งรหัสล็อกอินทางอีเมลทุกครั้งที่ล็อกอิน และไม่ต้องทำอะไรกับรหัสนั้น ดู[ตั้งค่า Muse](/docs/start-here/setup-muse#what-to-expect) **ต่างจาก muse2api อย่างไร?** ผ่าน useapi.net Muse API เป็นแบบโฮสต์ให้ จึงไม่ต้องติดตั้งอะไรเอง คุณเพิ่มแต่ละบัญชีด้วยอีเมลและรหัสผ่าน และเราดูแลให้บัญชีล็อกอินอยู่เสมอ (เซสชัน 30 วันที่ต่ออายุเอง) ผลลัพธ์ส่งต่อกันด้วย asset id และงานที่เสร็จแล้วเรียก webhook ของคุณได้ คุณยัง[แชตกับเอเจนต์ Muse](/docs/api-muse-v1/chat-streaming-guide) ได้ โดยคำตอบสตรีมมาแบบสด ส่วน [muse2api](https://github.com/czg86389-hub/muse2api) เป็นโปรเจกต์ที่คุณต้องติดตั้ง โฮสต์ และดูแลให้ทำงานอยู่เอง ### สรุป แวะมาที่ <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> หรือ <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> ของเราได้ หากมีคำถามหรือข้อสงสัย ดู[ที่เก็บโค้ดบน GitHub](https://github.com/useapi/muse-api) ของเราซึ่งมีตัวอย่างโค้ด คำขอเดียวกันนี้ใช้เป็นเครื่องมือได้บน [Muse MCP server](/docs/api-muse-v1/mcp) แบบโฮสต์ให้ สำหรับ Claude Code, Cursor และ VS Code #### เผยแพร่ที่อื่นด้วย {: .no_toc #cross-posted } เผยแพร่บน [dev.to](https://dev.to/useapi/how-to-generate-ai-images-and-videos-with-the-muse-api-274){:rel="nofollow"} พูดคุยกันบน [Reddit](https://www.reddit.com/r/ThirdPartyAPI/comments/1x3udcd/how_to_generate_ai_images_and_videos_with_the/){:rel="nofollow"} แชร์บน [Bluesky](https://bsky.app/profile/useapi.net/post/3mxnuj43mcs2w){:rel="nofollow"} และบน YouTube เป็น[วิดีโอเดโมทั้ง API ยาว 2:49](https://www.youtube.com/watch?v=OMUGbfRIO5E) (ภาษาอังกฤษ) ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/muse-images-videos-vi === Document URL: https://useapi.net/docs/articles/muse-images-videos-vi --- layout: default title: "Cách tạo video và ảnh AI bằng Meta Muse API" description: "Tạo video Meta Muse dài 10 giây có âm thanh, và ảnh, qua Muse API của useapi.net: ảnh biết nói, ảnh thành video, thay người trong video, phục hồi ảnh cũ." keywords: [Muse API, Meta Muse API, Meta Muse video API, muse ai video generator, meta muse ai video generator, muse ai api, muse ai image to video, Meta Muse là gì, cách dùng Meta Muse, tạo video AI Meta, ảnh biết nói, talking photo API, Meta AI video generator API, muse.ai API, Meta AI video API, API tạo ảnh AI, API ảnh thành video, phục hồi ảnh cũ, tô màu ảnh đen trắng, thay mặt trong video, thay người trong video, video AI có lời thoại, YouTube Shorts không lộ mặt, video AI có thuyết minh, curl] image: https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-cover.jpg parent: Articles nav_exclude: true lang: vi translation_key: muse date: 2026-10-12 last_modified: 2026-10-30 nav_order: 898 video: name: "Meta Muse API Demo: Images, Talking Photos, Video with Sound, Chat & MCP (third-party, useapi.net)" description: "The third-party Meta Muse API by useapi.net: images, 10-second videos with sound and spoken dialogue, agent chat with live streaming and approvals, and a hosted MCP server, on your Muse website subscription." embed: https://www.youtube.com/embed/OMUGbfRIO5E thumbnail: https://i.ytimg.com/vi/OMUGbfRIO5E/maxresdefault.jpg date: 2026-10-14 duration: PT2M49S width: 1920 height: 1080 repo: https://github.com/useapi/muse-api --- ## Cách tạo video và ảnh AI bằng Meta Muse API {: #how-to-generate-ai-videos-and-images-with-the-meta-muse-api .no_toc } 16 phút đọc • 12 tháng 10 năm 2026 (30 tháng 10 năm 2026) useapi.net là API của bên thứ ba, không liên kết với Meta và không được Meta bảo trợ. ## Mục lục {: #table-of-contents .no_toc .text-delta } ### Giới thiệu [Muse API của useapi.net](/docs/api-muse-v1) điều khiển [Muse](https://muse.ai), agent AI cá nhân của Meta, bằng code: một lệnh POST tạo một ảnh hoặc một video 10 giây có lời thoại, và mỗi file nó tạo ra là một [asset id](/docs/api-muse-v1/get-muse-assets-assetId) mà job tiếp theo có thể nhận làm đầu vào. Muse ở đây là agent của Meta tại [muse.ai](https://muse.ai), không phải Skiv, công ty lưu trữ video đã dùng tên muse.ai cho tới tháng 3/2026. API được host sẵn, nên khác với các công cụ tự host như muse2api, bạn không phải triển khai gì: bài [so sánh Meta Muse video API](/docs/articles/meta-muse-video-api) đặt API của chính Meta, muse2api và các API được host cạnh nhau. API chạy trên [gói đăng ký website Muse](https://www.meta.com/help/subscriptions/1021145227643680/) của bạn, và gói miễn phí cũng dùng được. Bài này lấy ba bức ảnh bình thường, một chiếc mô tô BMW cổ, một nữ tay lái tóc đỏ và bãi biển dưới cầu Golden Gate, rồi ghép thành một bức ảnh cô lái chiếc mô tô đó băng qua sóng. Bức ảnh sau đó thành một video trong đó cô hét lên một câu, và ở job thứ ba, một người phụ nữ khác, lấy từ bức ảnh thứ tư, thay cô trong video đó mà chuyến đi vẫn giữ nguyên. Trên đường đi, bài còn tạo ảnh từ văn bản, và phục hồi, tô màu một bức chân dung trăm năm tuổi rồi cho nhân vật ngước lên và cất lời. Mọi request dưới đây chính là request đã tạo ra media trên trang này. <video poster="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g3-poster.jpg" src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g3.mp4" style="width: 100%; aspect-ratio: 1248/704; max-width: 720px" controls type="video/mp4" preload="metadata"></video> Tay lái từ một bức ảnh, được thay vào clip Muse làm từ ảnh tĩnh ([bước 8](#step-8-swap-the-rider-in-the-video)). ### Chi phí useapi.net là một API, không phải dịch vụ ảnh hay video riêng. Mọi lệnh gọi chạy trên một tài khoản Muse bạn thêm qua [Setup Muse](/docs/start-here/setup-muse), và dùng hạn mức Muse hằng tuần của tài khoản đó, useapi.net không thu phí theo ảnh hay video. Muse báo hạn mức dưới dạng phần trăm đã dùng, làm tròn số nguyên, nên một ảnh thường không làm con số thay đổi. Mỗi bước dùng bao nhiêu trên gói miễn phí, lấy từ `percentUsed` trước và sau bước đó, và mỗi job mất bao lâu: | Bước | Endpoint | Đầu ra | Hạn mức đã dùng | Thời gian | |---|---|---|--:|--:| | [Văn bản thành ảnh, 9:16](#step-3-images-from-text) | [POST /jobs/image](/docs/api-muse-v1/post-muse-jobs-image) | 1152×2048 | không đo | 30 s | | [Văn bản thành ảnh, đúng 16:9](#step-3-images-from-text) | [POST /jobs/image](/docs/api-muse-v1/post-muse-jobs-image) | 2048×1152 | 0% | 21 s | | [Tay lái + mô tô + bãi biển](#step-4-three-photos-into-one-picture) | [POST /jobs/image](/docs/api-muse-v1/post-muse-jobs-image) | 2048×1152 | 0% | 31 s | | [Chuyến đi thành video](#step-5-the-picture-as-a-video-no-re-upload) | [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video) | 1280×720, 10 s | 3% | 88 s | | [Phục hồi ảnh cũ](#step-6-restore-and-colorize-an-old-photo) | [POST /jobs/image](/docs/api-muse-v1/post-muse-jobs-image) | 1344×1792 | 1% | 34 s | | [Bức chân dung cất lời](#step-7-the-portrait-comes-to-life) | [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video) | 832×1104, 10 s | 2% | 68 s | | [Thay tay lái](#step-8-swap-the-rider-in-the-video) | [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video) | 1248×704, 10 s | 3% | 138 s | Tải file lên không tốn hạn mức. Trên gói miễn phí, một video dùng 2 đến 3 phần trăm của tuần và một ảnh 0 đến 1 phần trăm, nên một tài khoản miễn phí làm được khoảng 30 đến 50 video mỗi tuần, hoặc vài trăm ảnh ([bước 9](#step-9-check-the-weekly-allowance)). ### Trước khi bắt đầu Bạn cần một [API token](/docs/start-here/setup-useapi) của useapi.net và một tài khoản Muse thêm qua [Setup Muse](/docs/start-here/setup-muse). Trước khi thêm tài khoản: - Muse có ở Mỹ, Canada, [Nhật Bản](https://about.fb.com/ja/news/2026/10/muse-personal-ai-agent-launches-in-japan/) và [Singapore](https://about.fb.com/news/2026/10/muse-is-now-available-in-singapore-the-worlds-first-personal-ai-agent-built-for-everyone/) (tính đến ngày 30/10/2026), nên hãy tạo tài khoản ở một trong các nước đó. Khi đã thêm tài khoản, bạn gọi API được từ bất cứ đâu. - Hoàn tất bước làm quen của Muse tại [muse.ai](https://muse.ai), gồm cả bước xác minh tuổi của Meta, và tạo một ảnh ở đó. - Tài khoản phải đăng nhập được bằng email + mật khẩu, vì API đăng nhập bằng email và mật khẩu. Tài khoản Meta chỉ đăng nhập bằng mã gửi qua email thì chưa có mật khẩu: hãy tạo mật khẩu trong [Meta Accounts Center](https://accountscenter.meta.com/password_and_security/) (Mật khẩu và bảo mật), rồi thêm tài khoản ở đây. Không có mật khẩu, việc thêm tài khoản bị từ chối với `400`. - Chỉ dùng tài khoản cho API, không chạy công cụ tự động nào khác trên đó. Mở tài khoản tại muse.ai trên trình duyệt thì không sao, nhưng chỉ từ Mỹ, Canada, Nhật Bản hoặc Singapore (các khu vực Muse chính thức hỗ trợ), hoặc qua VPN ở một trong các nước đó: Meta có thể tắt video của tài khoản nếu thấy nó được dùng từ nơi khác. Mọi lệnh gọi cũng có trong [Postman collection](/assets/postman/muse-v1.json). Không cần code: template n8n [Old Photo to Talking Video]({% include n8n-url.html t="muse-photo" %}) phục hồi một bức ảnh và cho nó nói chuyện từ một biểu mẫu, còn template [Narrated Faceless Shorts]({% include n8n-url.html t="muse-shorts" %}) biến một chủ đề thành một Short có thuyết minh. Toàn bộ bài hướng dẫn cũng có trên GitHub dưới dạng một script, bằng Node.js và Python: [`images-videos/`](https://github.com/useapi/muse-api/tree/main/images-videos) trong [useapi/muse-api](https://github.com/useapi/muse-api), cùng một [agent skill](https://github.com/useapi/muse-api/tree/main/skills/muse-video) cho Claude Code và Codex. Các bước dùng `curl`, `jq` cùng những biến và helper sau: <details markdown="block"> <summary>Mở biến và helper</summary> ```bash export USEAPI_TOKEN="user:12345-..." export EMAIL="example@gmail.com" export MUSE_PASSWORD="..." # mật khẩu tài khoản Muse, chỉ dùng một lần ở bước 1 API=https://api.useapi.net/v1/muse AUTH="Authorization: Bearer $USEAPI_TOKEN" enc() { jq -rn --arg v "$1" '$v|@uri'; } post() { curl -sS -X POST "$API/$1" -H "$AUTH" -H "Content-Type: application/json" -d "$2"; } get() { curl -sS "$API/$1" -H "$AUTH"; } upload() { curl -sS -X POST "$API/assets?email=$(enc "$EMAIL")" -H "$AUTH" -H "Content-Type: $2" --data-binary @"$1" | jq -r .assetId; } download() { curl -sSf "$API/assets/$(enc "$1")" -H "$AUTH" -o "$2"; } # chạy job bất đồng bộ: gửi job, gọi GET /jobs/{jobid} mỗi 10 giây, lưu bản ghi job cuối cùng vào $1 run() { local job id job=$(post "$2" "$(jq '. + {async: true}' <<< "$3")") id=$(jq -r .jobid <<< "$job") while [ "$(jq -r .status <<< "$job")" = started ]; do sleep 10 job=$(get "jobs/$(enc "$id")") done echo "$job" > "$1" jq '{status, error, text: .result.text, asset: .result.assets[0].assetId}' "$1" } ``` </details> Mọi lần tạo đều chạy dưới dạng job. Không có `async`, một lệnh POST chờ tối đa khoảng 100 giây và trả về bản ghi job đã xong, hoặc `202` khi job vẫn đang chạy. Ở đây một video mất 68 đến 138 giây, nên `run` gửi mọi job với `async: true` và gọi [GET /jobs/`jobid`](/docs/api-muse-v1/get-muse-jobs-jobid). Nếu `run` in ra `status` nào khác `completed`, hãy đọc `error` trước khi làm tiếp. Để được gọi lại thay vì polling, thêm `replyUrl: "https://example.com/hooks/muse"` (và tùy chọn `replyRef`) vào bất kỳ body nào bên dưới. API sẽ gửi một lệnh `POST` chứa bản ghi job cuối cùng, dạng JSON, tới URL đó. Id chứa `:` và `@`, nên `enc` mã hóa URL cho chúng mỗi khi đưa vào đường dẫn URL. Mọi đầu vào của một job phải nằm trên cùng một tài khoản Muse, nên các lần tải lên được gắn `email`, và một job chạy trên tài khoản đang giữ đầu vào của nó. ### Cách làm #### 1. Thêm tài khoản [POST /accounts](/docs/api-muse-v1/post-muse-accounts) nhận email và mật khẩu của tài khoản Muse. API đăng nhập một lần, giữ phiên 30 ngày và tự gia hạn. Mỗi lần đăng nhập, Muse gửi email mã đăng nhập cho tài khoản. Email đó chỉ là thông báo, không cần nhập gì. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-accounts">POST /accounts</a></summary> ```bash post accounts "$(jq -n --arg email "$EMAIL" --arg password "$MUSE_PASSWORD" '{email: $email, password: $password}')" | jq '{health, maxJobs, quota}' ``` </details> Phản hồi cho thấy `health: "OK"`, `maxJobs` (mặc định 10) cùng gói và mức sử dụng của tài khoản, ở đây là `tier: "HATCH_FREE"`, gói miễn phí. Nếu phản hồi là `596`, Meta muốn kiểm tra bảo mật: hãy đăng nhập một lần tại muse.ai trên trình duyệt, hoàn tất bước kiểm tra, rồi gửi lại cùng email và mật khẩu. #### 2. Tải ảnh lên [POST /assets](/docs/api-muse-v1/post-muse-assets) nhận file thô làm body, tối đa 50 MB, và ghi nó vào workspace Muse của tài khoản. useapi.net không lưu gì. `assetId` trong phản hồi là thứ một job nhận làm `image_N`. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-assets">POST /assets</a></summary> ```bash BMW=$(upload bmw.jpeg image/jpeg) RIDER=$(upload rider.jpeg image/jpeg) BEACH=$(upload beach.jpeg image/jpeg) OLD_PHOTO=$(upload old-photo.jpeg image/jpeg) PINK=$(upload pink-hair.jpeg image/jpeg) echo "$BMW" # user:12345-email:6578616d706c6540676d61696c2e636f6d-image:7db53e7a1f0979cbab6ff46ec3f0a35b60e6ee579a0d738a9628cf46a0c7a0f5.jpg ``` </details> <div style="display: flex; flex-wrap: wrap; gap: 8px; align-items: flex-start"> <figure style="margin: 0; width: 32%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-motorcycle.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-motorcycle.jpg" alt="<code>image_1</code> — chiếc mô tô" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em"><code>image_1</code> — chiếc mô tô</figcaption></figure> <figure style="margin: 0; width: 18%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-redhead.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-redhead.jpg" alt="<code>image_2</code> — tay lái" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em"><code>image_2</code> — tay lái</figcaption></figure> <figure style="margin: 0; width: 32%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-beach.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-beach.jpg" alt="<code>image_3</code> — bãi biển" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em"><code>image_3</code> — bãi biển</figcaption></figure> <figure style="margin: 0; width: 18%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-oldphoto.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-oldphoto.jpg" alt="bức chân dung cũ" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">bức chân dung cũ</figcaption></figure> <figure style="margin: 0; width: 18%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-pinkhair.webp" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-pinkhair.webp" alt="tay lái thứ hai" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">tay lái thứ hai</figcaption></figure> </div> Năm đầu vào: chiếc mô tô, tay lái, bãi biển, bức chân dung cũ và tay lái thứ hai. Asset id được tạo từ nội dung file, nên tải lại cùng file lên cùng tài khoản sẽ trả về cùng id và không ghi gì thêm. #### 3. Ảnh từ văn bản Muse không có tham số tỷ lệ khung hình: prompt nói điều đó. Trước tiên là một ảnh chân dung khổ dọc: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-image">POST /jobs/image</a></summary> ```bash run portrait.json jobs/image "$(jq -n '{prompt: "Vertical 9:16 full-body portrait photo: a confident young woman biker with long wavy fiery red hair, green eyes and freckles, in a worn black leather jacket, dark jeans and boots, standing in a rain-soaked neon alley at dusk, looking straight at the camera, cinematic lighting, photorealistic."}')" download "$(jq -r '.result.assets[0].assetId' portrait.json)" portrait.webp ``` </details> <img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-a2.webp" style="width: 100%; max-width: 420px" alt="Văn bản thành ảnh ở tỷ lệ 9:16"> [mở trong tab mới](https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-a2.webp){:target="_blank"} Ảnh trả về đúng 9:16, 1152×2048. Một phiên bản ngang yêu cầu bằng `Cinematic 16:9 landscape photo: …` trả về 1920×1280, tức 3:2. Viết tỷ lệ là `in exactly 16:9 aspect ratio` đã khắc phục được: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-image">POST /jobs/image</a></summary> ```bash run bmw-noir.json jobs/image "$(jq -n '{prompt: "In exactly 16:9 aspect ratio (landscape), a cinematic photo of a vintage 1920s black BMW motorcycle with white pinstripes, spoked wheels and a brown leather saddle, parked on wet cobblestones at night in San Francisco, the Golden Gate Bridge glowing through fog in the distance, neo-noir moonlight, reflections on the wet street, shot on 35mm film."}')" download "$(jq -r '.result.assets[0].assetId' bmw-noir.json)" bmw-noir.webp ``` </details> <img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-a5.webp" style="width: 100%" alt="Văn bản thành ảnh ở đúng tỷ lệ 16:9"> [mở trong tab mới](https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-a5.webp){:target="_blank"} Muse trả lời "That 16:9 frame with the bridge ghosting through the fog is pure neo-noir. Enjoy." Câu trả lời của nó nằm ở `result.text`. #### 4. Ghép ba ảnh thành một Tối đa 9 ảnh vào một job dưới dạng `image_1`..`image_9`, và prompt gọi tên chúng. Ở đây chiếc mô tô là `image_1`, tay lái là `image_2` và bãi biển là `image_3`. Prompt yêu cầu Muse dùng bãi biển đúng như trong ảnh chụp, nên cầu Golden Gate vẫn ở nguyên chỗ của nó trong ảnh. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-image">POST /jobs/image</a></summary> ```bash run beach-ride.json jobs/image "$(jq -n --arg bmw "$BMW" --arg rider "$RIDER" --arg beach "$BEACH" \ '{image_1: $bmw, image_2: $rider, image_3: $beach, prompt: "In exactly 16:9 aspect ratio (landscape), a cinematic photo: the woman from image_2 (her face, long wavy red hair, light blue top and jeans) riding the exact vintage motorcycle from image_1 along the shoreline of the beach in image_3, the front wheel cutting through the shallow surf and throwing spray, bright afternoon sun, her hair streaming in the wind, photorealistic. Use the beach, rocks and Golden Gate Bridge from image_3 as the background exactly as photographed: same position, same orientation, not mirrored or redrawn. Keep her face and the motorcycle'\''s design exactly as in the images."}')" BEACH_RIDE=$(jq -r '.result.assets[0].assetId' beach-ride.json) download "$BEACH_RIDE" beach-ride.webp ``` </details> <img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g1.webp" style="width: 100%" alt="Tay lái, chiếc mô tô và bãi biển trong một bức ảnh"> [mở trong tab mới](https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g1.webp){:target="_blank"} 31 giây, và hạn mức hằng tuần không thay đổi thấy được. #### 5. Bức ảnh thành video, không cần tải lên lại `BEACH_RIDE` là id của một file Muse đã tạo. File đã nằm trong workspace của tài khoản, nên đi thẳng vào job tiếp theo làm `image_1`, không cần tải về hay tải lên. `Animate image_1` tạo một clip bắt đầu từ bức ảnh và giữ nguyên khổ hình, và câu trong ngoặc kép được nói ra. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-video">POST /jobs/video</a></summary> ```bash run surf.json jobs/video "$(jq -n --arg img "$BEACH_RIDE" '{image_1: $img, prompt: "Animate image_1 into a cinematic video in exactly 16:9 aspect ratio (landscape): she rides the vintage motorcycle along the shoreline, the front wheel slices through the shallow waves and sends spray flying, the old engine roars, she raises one fist and shouts with a laugh: \"Nothing beats this view!\" The camera tracks alongside her. The beach, the rocks and the Golden Gate Bridge stay exactly as in image_1 (same orientation). Keep her face and the motorcycle exactly as in image_1."}')" SURF=$(jq -r '.result.assets[0].assetId' surf.json) download "$SURF" surf.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g2-poster.jpg" src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g2.mp4" style="width: 100%; aspect-ratio: 16/9; max-width: 720px" controls type="video/mp4" preload="metadata"></video> Xem thêm trên YouTube: [3 photos in, 1 talking video out: Meta Muse API from REST](https://youtube.com/shorts/v_7mREyFSWk). 10 giây ở 1280×720 có âm thanh. Muse nói "Done. 10 seconds, 16:9 landscape, straight from your image — no edits, no upscaling." Lần thử đầu tiên của đúng job này lỗi sau 37 giây: Muse trả lời rằng "the video worker glitched out before it rendered anything, so no clip was made". API báo câu trả lời như vậy là `503`, không có gì được tạo, và cùng request đó chạy được khi gửi lại. Bị từ chối vì nội dung thì là `403`, và cần một prompt khác. #### 6. Phục hồi và tô màu ảnh cũ Một job ảnh cũng sửa được ảnh. Bức chân dung cũ là một ảnh nâu đỏ đã phai, 685×900 pixel, tỷ lệ 3:4. Prompt liệt kê những gì cần sửa và nhấn mạnh giữ nguyên khung hình. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-image">POST /jobs/image</a></summary> ```bash run restored.json jobs/image "$(jq -n --arg img "$OLD_PHOTO" '{image_1: $img, prompt: "Restore the old photograph image_1 as a high-quality modern photo: remove the scratches, dust, stains, fading and grain, recover sharp detail in the face, hair and fabric, and colorize it naturally (warm natural skin tones, dark brown hair, ivory tulle shawl, a soft pink rose with green leaves, a muted warm background). Keep the exact same person, expression, pose, framing and crop, and the same portrait aspect ratio as image_1 (3:4, 685×900): do not crop, extend or reframe it."}')" RESTORED=$(jq -r '.result.assets[0].assetId' restored.json) download "$RESTORED" restored.webp ``` </details> <div style="display: flex; flex-wrap: wrap; gap: 8px; align-items: flex-start"> <figure style="margin: 0; width: 48%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-oldphoto.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-oldphoto.jpg" alt="Trước: ảnh gốc, 685×900" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">Trước: ảnh gốc, 685×900</figcaption></figure> <figure style="margin: 0; width: 48%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-e1.webp" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-e1.webp" alt="Sau: đã phục hồi và tô màu, 1344×1792" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">Sau: đã phục hồi và tô màu, 1344×1792</figcaption></figure> </div> Kết quả là 1344×1792, cùng khung 3:4 với kích thước khoảng gấp đôi, cùng tư thế và cùng cách cắt. Muse nói "Done — restored, de-grained, and colorized, same framing and pose." #### 7. Bức chân dung sống dậy Ảnh đã phục hồi đi thẳng vào một job video. Clip giữ nguyên khổ hình của bức chân dung, nên trả về 832×1104. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-video">POST /jobs/video</a></summary> ```bash run portrait-video.json jobs/video "$(jq -n --arg img "$RESTORED" '{image_1: $img, prompt: "Animate image_1 into a video with the same portrait frame: the young woman slowly lifts her eyes to the camera, her smile widens, she gently touches the rose on her shoulder and says softly: \"It has been a hundred years... and you still remember me.\" A light breeze moves a few strands of her hair, soft window light, the camera stays still with a very slow push-in. Keep her face exactly as in image_1."}')" download "$(jq -r '.result.assets[0].assetId' portrait-video.json)" portrait.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-e2-poster.jpg" src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-e2.mp4" style="width: 100%; aspect-ratio: 832/1104; max-width: 420px" controls type="video/mp4" preload="metadata"></video> Xem thêm trên YouTube: [This old portrait just spoke: one API call (Meta Muse API, third-party)](https://youtube.com/shorts/GLHoINX_ozE). #### 8. Thay tay lái trong video Một job video cũng nhận video. `video_1` là clip lướt sóng từ bước 5, còn `image_1` là ảnh của một người phụ nữ thứ hai tóc hồng búi hai bên. Prompt yêu cầu Muse thay tay lái và giữ nguyên mọi thứ khác, và cho cô một câu thoại mới. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-video">POST /jobs/video</a></summary> ```bash run swap.json jobs/video "$(jq -n --arg vid "$SURF" --arg img "$PINK" '{video_1: $vid, image_1: $img, prompt: "Edit video_1: replace the rider with the woman from image_1 (her face, pink hair in two buns, colorful makeup and tattoos), and keep everything else the same: the motorcycle, the beach, the waves and spray, the Golden Gate Bridge, the light, the camera move and the timing. Instead of the original line she shouts: \"Catch me if you can, San Francisco!\" Keep the 16:9 frame and the same length."}')" download "$(jq -r '.result.assets[0].assetId' swap.json)" swap.mp4 ``` </details> <div style="display: flex; flex-wrap: wrap; gap: 8px; align-items: flex-start"> <figure style="margin: 0; width: 48%"><video poster="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g2-poster.jpg" src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g2.mp4" style="width: 100%; aspect-ratio: 16/9" controls type="video/mp4" preload="metadata"></video><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">Trước: tay lái ban đầu</figcaption></figure> <figure style="margin: 0; width: 48%"><video poster="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g3-poster.jpg" src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g3.mp4" style="width: 100%; aspect-ratio: 1248/704" controls type="video/mp4" preload="metadata"></video><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">Sau: tay lái từ bức ảnh</figcaption></figure> </div> Với 138 giây, đây là job chậm nhất của bài, và cũng là lý do mọi job ở đây chạy async. Clip là cùng chuyến đi nhưng người phụ nữ kia ngồi trên mô tô, hét lên câu thoại mới. Muse nói "Done. She's in, 10 seconds, 16:9, same ride, same bridge, same waves." Xem thêm trên YouTube: [Replace the person in a video, keep everything else: Meta Muse API](https://youtube.com/shorts/XDCY1XIsd5Y). #### 9. Kiểm tra hạn mức hằng tuần [GET /accounts/`email`](/docs/api-muse-v1/get-muse-accounts-email) đọc trực tiếp gói và mức sử dụng của tài khoản: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/get-muse-accounts-email">GET /accounts/email</a></summary> ```bash get "accounts/$(enc "$EMAIL")" | jq '{session, quota}' ``` </details> `quota.percentUsed` là phần đã dùng của tuần, tính bằng phần trăm nguyên, còn `quota.resetsAt` là lúc hạn mức bắt đầu lại, một tuần sau khi bắt đầu. Ba video ở trên mỗi video dùng 2 đến 3 phần trăm và các ảnh 0 hoặc 1. Trong cả buổi thử nghiệm, gồm cả hai job không trình bày ở đây, tài khoản miễn phí đi từ 16 lên 28 phần trăm. Khi một tài khoản hết hạn mức, job mới không có `email` sẽ đi tới các tài khoản khác của bạn, còn job gắn với tài khoản đó trả về `412` cho tới `resetsAt`. ### Những gì chúng tôi rút ra - Viết tỷ lệ khung hình là `in exactly 16:9 aspect ratio`. `Cinematic 16:9 landscape photo` có lần trả về 3:2. - Video nào cũng dài khoảng 10 giây. Prompt yêu cầu 5 giây vẫn nhận 10. - Clip từ ảnh giữ khổ hình của ảnh, trừ khi prompt yêu cầu khổ khác: `in exactly 9:16 aspect ratio` biến ảnh bãi biển 16:9 của chúng tôi thành clip dọc 720×1280, được bố cục lại chứ không bị kéo giãn. - Câu thoại viết trong ngoặc kép trong prompt video sẽ được nói ra. - Truyền file đã tạo bằng `assetId`. Chúng nằm lại trong workspace của tài khoản, nên một chuỗi chỉnh sửa không cần tải về ở giữa. - Nói rõ cái gì phải giữ nguyên. "Same position, same orientation, not mirrored or redrawn" giữ được bãi biển thật trong ảnh ghép. - Một lỗi `503` kèm lời của chính Muse như "glitched out" thì đáng chạy lại. `403` là bị từ chối và cần prompt khác. - Gửi video với `async: true`. Một request đồng bộ chờ khoảng 100 giây, còn lần thay người mất 138. ### Làm một Short 30 giây có thuyết minh (kịch bản, ba cảnh, một lần ghép) Video Muse luôn dài khoảng 10 giây, nên một Short dọc 30 giây có người thuyết minh cần ba job video và hai cuộc chat. Một [chat](/docs/api-muse-v1/post-muse-chats) viết kịch bản dạng JSON, ba [job video](/docs/api-muse-v1/post-muse-jobs-video) chạy song song, mỗi job một cảnh, mỗi cảnh nói câu của mình bằng cùng giọng người thuyết minh, và một chat cuối ghép các clip bằng ffmpeg ngay trong workspace của tài khoản. Short dưới đây, về vụ phun trào núi Tambora năm 1815 và "năm không có mùa hè" sau đó, đi từ một chủ đề một dòng tới file MP4 trong khoảng 2 phút. <video poster="https://media.useapi.net/articles/2026-10-12-muse-images-videos-id/muse-narrated-short-tambora-poster.jpg" src="https://media.useapi.net/articles/2026-10-12-muse-images-videos-id/muse-narrated-short-tambora.mp4" style="width: 100%; aspect-ratio: 9/16; max-width: 420px" controls type="video/mp4" preload="metadata"></video> Xem thêm trên YouTube: [A narrated 30-second Short made only with Meta Muse API calls](https://youtube.com/shorts/1e8f7dHTkzs). Ba clip 10 giây ghép thành một Short 720×1280 dài 30 giây, từ chủ đề "how a single volcano cooled the whole planet in 1816". Kịch bản mất 11 giây, ba clip mất 75, 75 và 87 giây chạy cùng lúc, và lần ghép 20 giây, nên một Short mất khoảng 2 đến 3 phút. Short này được làm trên một gói Muse trả phí. Ở đó, bốn video của buổi thử nghiệm (ba video này và một video nữa) làm chỉ số hằng tuần tăng tổng cộng 2 điểm, còn các cuộc chat không làm tăng điểm nào. Trên gói miễn phí, một video dùng 2 đến 3 phần trăm của tuần, nên một Short ba cảnh tốn khoảng 6 đến 9 phần trăm. Không cần code: cùng quy trình này có dạng ứng dụng n8n, template [Narrated Faceless Shorts]({% include n8n-url.html t="muse-shorts" %}), với một biểu mẫu, một trang kịch bản và lưu vào Google Drive. Hai Short nó đã làm, đăng nguyên như khi ra lò: [The Great Pyramid was once bright white](https://youtube.com/shorts/D-Nk0x9aJMo) và [Why honey never spoils](https://youtube.com/shorts/bYLsJIqerSM), được lồng tiếng bằng tính năng chuyển văn bản thành giọng nói của Muse. Toàn bộ quy trình cũng là một script, bằng Node.js và Python: [`narrated-short/`](https://github.com/useapi/muse-api/tree/main/narrated-short) trong [useapi/muse-api](https://github.com/useapi/muse-api). Script nhận một chủ đề, tùy chọn số cảnh và mô tả người thuyết minh của riêng bạn, và lưu Short vào `output/`. Các bước dùng [helper ở trên](#before-you-start) cộng thêm `chat`, helper bắt đầu một cuộc chat và đọc [GET /chats/`chatId`](/docs/api-muse-v1/get-muse-chats-chatId) cho tới khi Muse xong: <details markdown="block"> <summary>Mở helper chat</summary> ```bash # bắt đầu một chat, gọi GET /chats/{chatId} mỗi 8 giây cho tới khi Muse xong, lưu chat vào $1 chat() { local id c id=$(post chats "$2" | jq -r .chatId) while sleep 8; do c=$(get "chats/$(enc "$id")") jq -e '.pendingApprovals | length > 0' <<< "$c" > /dev/null && echo "Muse asks for permission: answer it with POST /chats/{chatId}/approvals/{approvalId}" jq -e '(.status | IN("completed", "interrupted", "failed")) and (.pendingApprovals | length == 0)' <<< "$c" > /dev/null && break done echo "$c" > "$1" jq '{status, reply: ([.messages[] | select(.role == "assistant" and .text != "")][-1].text)}' "$1" } ``` </details> Mọi request dưới đây đều gắn `email`. Một chat nhận file phải chạy trên tài khoản đang giữ chúng, nên ba clip và lần ghép đều ở trên một tài khoản. #### 1. Viết kịch bản dạng JSON Chat đầu tiên yêu cầu đúng ba cảnh và nói rõ cấu trúc JSON. Mỗi cảnh có `line`, lời người thuyết minh, giới hạn 25 từ để vừa trong 10 giây, và `visual`, một câu mô tả cảnh quay. Prompt cũng bảo Muse không tạo file nào, nên cuộc chat chỉ có văn bản. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-chats">POST /chats</a></summary> ```bash TOPIC="how a single volcano cooled the whole planet in 1816" chat script.json "$(jq -n --arg email "$EMAIL" --arg topic "$TOPIC" '{email: $email, message: "Write a script for a 30-second faceless YouTube Short about: \"\($topic)\". Exactly 3 scenes. Reply with ONLY a JSON object, no prose, no markdown code fences, in this exact shape: {\"title\": string, \"scenes\": [{\"line\": string, \"visual\": string}, {\"line\": string, \"visual\": string}, {\"line\": string, \"visual\": string}]}. \"line\" is what the off-screen narrator says (at most 25 words, about 9 seconds spoken). \"visual\" is a one-sentence description of the 10-second shot, no people talking on camera. Do not create any files, images or videos."}')" jq -r '[.messages[] | select(.role == "assistant" and .text != "")][-1].text' script.json | sed '/^```/d' > scenes.json jq . scenes.json ``` </details> Muse trả lời sau 11 giây, chỉ có JSON: ```json { "title": "How One Volcano Cooled the Whole Planet in 1816", "scenes": [ { "line": "In April 1815, Mount Tambora in Indonesia erupted, the largest explosion in recorded history, blasting ash forty kilometers into the sky.", "visual": "A massive volcanic eruption at dawn, with a towering ash column rising into the stratosphere above a dark island." }, { "line": "That ash veil circled Earth, blocking sunlight and dropping global temperatures, turning summer into winter across North America and Europe.", "visual": "An animated globe wrapped in a gray haze as sunlight dims and frost spreads across continents." }, { "line": "1816 became the Year Without a Summer: crops failed, snow fell in July, and famine spread as the planet shivered.", "visual": "Snow falling over green farmland in summer, covering withered crops and empty village fields under a pale sun." } ] } ``` Chúng tôi chạy cùng prompt cho ba chủ đề và lần nào cũng nhận JSON sạch, trong 11 đến 29 giây, không có khối code và không có chữ thừa. Mẫu đó còn nhỏ, nên `sed` vẫn bỏ dòng ```` ``` ```` lạc nếu có, và script trên GitHub hỏi lại một lần khi câu trả lời không phân tích được. #### 2. Ba cảnh cùng lúc Mỗi cảnh thành một lệnh [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video) async. Cả ba prompt mang cùng một mô tả người thuyết minh, giống từng chữ, theo sau là `The narrator says exactly: "<line>"`. Muse nói câu trong ngoặc kép đúng như đã viết, và mô tả chung giữ giọng nhất quán giữa các clip. `Vertical 9:16 video` trả về 720×1280. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-video">POST /jobs/video</a></summary> ```bash NARRATOR="Narration: one off-screen narrator only, the same voice throughout: a calm, deep, middle-aged British male documentary narrator, measured pace, warm and authoritative, like a nature documentary. Nobody on screen speaks. No music." for i in 0 1 2; do post jobs/video "$(jq --arg email "$EMAIL" --arg narrator "$NARRATOR" --argjson i $i '.scenes[$i] | {email: $email, async: true, prompt: "Vertical 9:16 video, about 10 seconds. \(.visual) Slow cinematic camera move, photoreal. \($narrator) The narrator says exactly: \"\(.line)\""}' scenes.json)" | jq -r .jobid done > jobs.txt ``` </details> Mỗi lệnh POST trả về `201` ngay với một `jobid`. Ba job chiếm ba trong số các slot `maxJobs` của tài khoản (mặc định 10), nên chúng chạy song song. Một lỗi `429` ở đây nghĩa là mọi slot đều bận và chưa có gì được bắt đầu: hãy gửi lại job đó sau 30 giây. #### 3. Polling các job [GET /jobs/`jobid`](/docs/api-muse-v1/get-muse-jobs-jobid) trả về `status: "started"` cho tới khi clip sẵn sàng. Các job chạy song song, nên đọc lần lượt từng job không tốn thêm thời gian: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/get-muse-jobs-jobid">GET /jobs/jobid</a></summary> ```bash for n in 1 2 3; do id=$(sed -n "${n}p" jobs.txt) until job=$(get "jobs/$(enc "$id")"); [ "$(jq -r .status <<< "$job")" != started ]; do sleep 10; done echo "$job" > clip$n.json jq '{status, error, text: .result.text, asset: .result.assets[0].assetId}' clip$n.json done ``` </details> Cả ba đều xong. Về clip đầu tiên, Muse nói "Here it is — vertical 9:16, photoreal volcanic eruption at dawn with the narration as specified". Mỗi clip nói câu của mình đúng từng chữ, và mọi câu, dài 20 đến 21 từ, đều vừa trong 10 giây. Một job lỗi `503` không tạo ra gì và có thể chạy lại. Mọi lỗi khác, như bị từ chối `403`, cần xem `error.message` trước. #### 4. Ghép các clip trong một chat Ba id clip đi vào một chat dưới dạng `files`, nơi Muse thấy chúng là `video_1`, `video_2` và `video_3`. Tin nhắn yêu cầu ffmpeg, thứ tự, âm thanh và tên file, và kết thúc bằng `No public links.` Với dòng đó, Muse không dừng lại xin phép. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-chats">POST /chats</a></summary> ```bash CLIPS=$(jq -s '[.[].result.assets[0].assetId]' clip1.json clip2.json clip3.json) chat join.json "$(jq -n --arg email "$EMAIL" --argjson files "$CLIPS" '{email: $email, files: $files, message: "Concatenate video_1, video_2, video_3 in order into one MP4 with ffmpeg, keep the audio, save it to workspace/your_files/short.mp4 and attach it here. No public links."}')" SHORT=$(jq -r '[.messages[] | select(.role == "assistant") | .files[] | select(.type == "video")][-1].assetId' join.json) echo "$SHORT" # user:12345-email:6578616d706c6540676d61696c2e636f6d-video:ws~your_files~short.mp4 ``` </details> 20 giây sau, Muse nói "Concatenated all three in order — 30 seconds, 720x1280, with audio kept." và đính kèm file trong một tin nhắn riêng, với một `video` trong `files`. Asset id của nó được đặt theo đường dẫn workspace, nên hãy đặt cho mỗi Short một tên file riêng. ffmpeg chép các luồng mà không mã hóa lại: Short dài đúng 30,0 giây, và cả ba câu đều có trong đó, đúng thứ tự. #### 5. Tải Short về [GET /assets/`assetId`](/docs/api-muse-v1/get-muse-assets-assetId) trả về file MP4: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/get-muse-assets-assetId">GET /assets/assetId</a></summary> ```bash download "$SHORT" tambora-short.mp4 ``` </details> Các clip và Short cũng nằm lại trong workspace Muse của tài khoản, nơi ứng dụng muse.ai hiển thị chúng, và asset id của Short có thể vào job tiếp theo làm `video_1`. #### Giọng cố định thay thế: chuyển văn bản thành giọng nói làm audio_1 Một mô tả chung cho ra cùng kiểu giọng, chứ không khóa cứng một giọng. Trong ba clip Tambora, cao độ trung vị của người thuyết minh là 105 đến 117 Hz, chênh nhau chưa tới hai nửa cung, nhưng Muse lồng tiếng lại từ đầu cho mỗi clip. Để chắc chắn chỉ một giọng, hãy cho Muse đọc mỗi câu bằng tính năng chuyển văn bản thành giọng nói trước, rồi truyền file MP3 đó vào job video làm `audio_1`. Cuộc chat chuyển văn bản thành giọng nói mất 20 giây trong thử nghiệm của chúng tôi. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-chats">POST /chats</a> và <a href="/docs/api-muse-v1/post-muse-jobs-video">POST /jobs/video</a></summary> ```bash chat voice1.json "$(jq -n --arg email "$EMAIL" --arg line "$(jq -r '.scenes[0].line' scenes.json)" '{email: $email, message: "Generate one mp3 file with text to speech: single speaker, voice Aria (avocado_v2:MAI_01), speed 100, language en, clean narration only: no music, no sound effects. Read exactly this text, do not change any word:\n\"\($line)\"\nSave it directly in workspace/your_files/ (not in a subfolder) as line-1.mp3 and attach it here. No public links and no uploads to remote storage."}')" VOICE1=$(jq -r '[.messages[] | select(.role == "assistant") | .files[] | select(.type == "audio")][-1].assetId' voice1.json) run clip1.json jobs/video "$(jq --arg email "$EMAIL" --arg voice "$VOICE1" '.scenes[0] | {email: $email, audio_1: $voice, prompt: "Vertical 9:16 video, about 10 seconds, no people on screen and nobody speaking on camera. \(.visual) Slow cinematic camera move, photoreal. Use audio_1 as the narration soundtrack exactly as it is: the off-screen narrator'\''s voice in audio_1, word for word, with no other voice and no new speech. Quiet ambient sound under it is fine."}' scenes.json)" jq -r '.result.assets[] | select(.origin == "made") | .assetId' clip1.json ``` </details> Muse tạo clip của nó rồi đặt `audio_1` lên clip bằng ffmpeg. Job liệt kê cả hai file: bản hoàn chỉnh trước, với `origin: "made"`, rồi clip thô của Muse, với `origin: "generated"`. Hãy lấy bản `made`. Clip thô mang một giọng Muse tự nghĩ ra thay vì giọng của bạn. Job video mất 108 giây trong thử nghiệm của chúng tôi. Lặp lại cho mỗi cảnh và ghép các clip `made` như ở bước 4. ### Câu hỏi thường gặp **Meta Muse (muse.ai) có API không?** Qua useapi.net thì có: [Muse API](/docs/api-muse-v1) là API của bên thứ ba chạy Muse trên [gói đăng ký website Muse](https://www.meta.com/help/subscriptions/1021145227643680/) của bạn. Tạo ảnh bằng [POST /jobs/image](/docs/api-muse-v1/post-muse-jobs-image) và video bằng [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video). [Model API](https://dev.meta.ai/docs/pricing-rate-limits) chính thức của Meta bán model Muse Image với giá $0,01 một ảnh, nhưng tính đến tháng 10/2026 không có tính năng tạo video và không có API cho agent Muse tại muse.ai, nơi video được tạo. Bài [so sánh Meta Muse video API](/docs/articles/meta-muse-video-api) của chúng tôi nói cả về muse2api. **Gói Muse miễn phí có dùng được không?** Qua useapi.net thì được: bài hướng dẫn này được làm trên gói miễn phí (`HATCH_FREE`), có hạn mức hằng tuần. Một video dùng 2 đến 3 phần trăm hạn mức và một ảnh 0 đến 1 phần trăm, nên một tài khoản miễn phí làm được khoảng 30 đến 50 video mỗi tuần. Các gói trả phí Power ($20 một tháng) và Maximum ($100 một tháng) nâng hạn mức lên (tính đến tháng 10/2026). **Muse có làm được video dài hơn 10 giây không?** Qua useapi.net, không trong một job: video nào cũng dài khoảng 10 giây. Hãy làm một clip cho mỗi cảnh rồi để một [chat](/docs/api-muse-v1/post-muse-chats) ghép chúng bằng ffmpeg, như trong [Làm một Short 30 giây có thuyết minh](#make-a-30-second-narrated-short-script-three-scenes-one-join), nơi ba clip thành một Short trong khoảng 2 đến 3 phút. Một chat nhận tối đa 3 video. **Đặt tỷ lệ khung hình, độ dài hay độ phân giải thế nào?** Qua useapi.net, bằng prompt, vì Muse không có tham số cho chúng. Tỷ lệ khung hình được tuân theo khi viết là `in exactly 16:9 aspect ratio`, và clip từ ảnh giữ khổ hình của ảnh trừ khi prompt yêu cầu khổ khác. Độ dài và độ phân giải cố định: video nào cũng trả về khoảng 720p có âm thanh, dù prompt yêu cầu gì. **Có dùng ảnh và video của chính mình được không?** Qua useapi.net thì được: tải chúng lên bằng [POST /assets](/docs/api-muse-v1/post-muse-assets), mỗi file tối đa 50 MB, và truyền `assetId` làm `image_1`..`image_9`, giống như truyền kết quả từ một job trước. [Job video](/docs/api-muse-v1/post-muse-jobs-video) còn nhận `video_1`..`video_3` và `audio_1`..`audio_3`. Mọi đầu vào của một job phải nằm trên cùng một tài khoản. **Làm sao cho một bức ảnh biết nói?** Qua useapi.net, truyền ảnh làm `image_1` vào [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video) với prompt kiểu `Animate image_1: … she says softly: "…"`. Muse giữ khổ hình của ảnh và nói câu trong ngoặc kép, như ở [bước 7](#step-7-the-portrait-comes-to-life), nơi một bức chân dung trăm năm tuổi đã phục hồi ngước lên và cất lời. **Có thay được người trong video không?** Qua useapi.net thì được: truyền clip làm `video_1` và ảnh người mới làm `image_1`, rồi yêu cầu Muse thay người và giữ nguyên mọi thứ khác, như ở [bước 8](#step-8-swap-the-rider-in-the-video). Nói rõ cái gì phải giữ nguyên, như chuyến đi, cây cầu và sóng biển, và cho người mới một câu thoại trong ngoặc kép nếu họ cần nói. **Vì sao request đồng bộ của tôi trả về 202?** Qua useapi.net, `202` nghĩa là job vẫn đang chạy sau khoảng 100 giây, và nó tiếp tục chạy phía chúng tôi. Lấy kết quả bằng [GET /jobs/`jobid`](/docs/api-muse-v1/get-muse-jobs-jobid), gửi job dài với `async: true` rồi polling, hoặc thêm `replyUrl` để nhận bản ghi job đã xong. Trong các lần chạy của chúng tôi, một video mất 68 đến 138 giây. **Vì sao Muse gửi email mã đăng nhập cho tôi?** Qua useapi.net, API đã đăng nhập vào tài khoản Muse của bạn, việc này xảy ra khi bạn thêm tài khoản và khi API gia hạn phiên 30 ngày, trước khi phiên hết hạn hoặc bất cứ lúc nào Muse yêu cầu đăng nhập lại. Muse gửi email mã đăng nhập mỗi lần đăng nhập, và bạn không cần làm gì với mã đó. Xem [Setup Muse](/docs/start-here/setup-muse#what-to-expect). **Khác gì so với muse2api?** Qua useapi.net, Muse API được host sẵn, nên không có gì phải triển khai: bạn thêm mỗi tài khoản bằng email và mật khẩu và chúng tôi giữ cho nó luôn đăng nhập. Kết quả nối tiếp nhau bằng asset id, và job đã xong có thể gọi webhook của bạn. Bạn cũng có thể [chat với agent Muse](/docs/api-muse-v1/chat-streaming-guide), với câu trả lời được stream trực tiếp. [muse2api](https://github.com/czg86389-hub/muse2api) là một dự án bạn tự triển khai, tự host và tự duy trì. ### Kết luận Ghé <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> hoặc <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> của chúng tôi cho mọi câu hỏi hỗ trợ. Xem [repo GitHub](https://github.com/useapi/muse-api) của chúng tôi với các ví dụ code. Cùng những lệnh gọi này có sẵn dưới dạng tool trên [Muse MCP server](/docs/api-muse-v1/mcp) được host sẵn cho Claude Code, Cursor và VS Code. #### Đăng ở nơi khác {: #cross-posted .no_toc } Cũng đăng trên [dev.to](https://dev.to/useapi/how-to-generate-ai-images-and-videos-with-the-muse-api-274){:rel="nofollow"}, thảo luận trên [Reddit](https://www.reddit.com/r/ThirdPartyAPI/comments/1x3udcd/how_to_generate_ai_images_and_videos_with_the/){:rel="nofollow"}, chia sẻ trên [Bluesky](https://bsky.app/profile/useapi.net/post/3mxnuj43mcs2w){:rel="nofollow"}, và trên YouTube dưới dạng [bản demo 2:49 của toàn bộ API](https://www.youtube.com/watch?v=OMUGbfRIO5E) (các bản này bằng tiếng Anh). ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/muse-images-videos === Document URL: https://useapi.net/docs/articles/muse-images-videos --- layout: default title: "How to Generate AI Videos and Images with the Meta Muse API" description: "Make 10-second Meta Muse videos with sound, and images, via the useapi.net Muse API: talking photos, image to video, person swap, photo restoration." keywords: [Muse API, Meta Muse API, Meta Muse video API, muse ai video generator, meta muse ai video generator, muse ai api, muse ai image to video, talking photo API, Meta AI video generator API, muse.ai API, Meta AI video API, AI image API, image to video API, old photo restoration API, photo colorization API, video face swap API, replace person in video, AI video with dialogue, faceless YouTube Shorts API, AI narrated video, curl] image: https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-cover.jpg parent: Articles nav_exclude: true date: 2026-10-12 last_modified: 2026-10-30 nav_order: 898 video: name: "Meta Muse API Demo: Images, Talking Photos, Video with Sound, Chat & MCP (third-party, useapi.net)" description: "The third-party Meta Muse API by useapi.net: images, 10-second videos with sound and spoken dialogue, agent chat with live streaming and approvals, and a hosted MCP server, on your Muse website subscription." embed: https://www.youtube.com/embed/OMUGbfRIO5E thumbnail: https://i.ytimg.com/vi/OMUGbfRIO5E/maxresdefault.jpg date: 2026-10-14 duration: PT2M49S width: 1920 height: 1080 repo: https://github.com/useapi/muse-api translation_key: muse --- ## How to Generate AI Videos and Images with the Meta Muse API 16 min read • October 12, 2026 (October 30, 2026) ## Table of contents ### Introduction The [useapi.net Muse API](/docs/api-muse-v1) drives [Muse](https://muse.ai), Meta's personal AI agent, from code: one POST makes an image or a 10-second video with spoken dialogue, and every file it makes is an [asset id](/docs/api-muse-v1/get-muse-assets-assetId) the next job can take as an input. Muse here is Meta's agent at [muse.ai](https://muse.ai), not Skiv, the video-hosting company that used the muse.ai name until March 2026. The API is hosted, so unlike self-hosted tools such as muse2api there is nothing to deploy: the [Meta Muse video API comparison](/docs/articles/meta-muse-video-api) puts Meta's own API, muse2api and hosted APIs side by side. The API runs on your [Muse website subscription](https://www.meta.com/help/subscriptions/1021145227643680/), and the free plan works. This walkthrough takes three ordinary photos, a vintage BMW motorcycle, a red-haired rider and the beach below the Golden Gate Bridge, and turns them into one picture of her riding that motorcycle through the surf. The picture then becomes a video in which she shouts a line, and in a third job a different woman, taken from a fourth photo, replaces her in that video while the ride stays the same. Along the way it makes images from text, and it restores and colorizes a hundred-year-old portrait that then looks up and speaks. Every request below is the one that made the media on this page. <video poster="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g3-poster.jpg" src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g3.mp4" style="width: 100%; aspect-ratio: 1248/704; max-width: 720px" controls type="video/mp4" preload="metadata"></video> The rider from a photo, swapped into a clip Muse made from a still image ([step 8](#8-swap-the-rider-in-the-video)). ### What it cost useapi.net is an API, not an image or video service of its own. Every call runs on a Muse account you add through [Setup Muse](/docs/start-here/setup-muse), and uses that account's weekly Muse allowance, with no per-image or per-video charge from useapi.net. Muse reports the allowance as a whole percent used, so a single image often shows no change. What each step used on the free plan, taken from `percentUsed` before and after it, and how long each job took: | Step | Endpoint | Output | Allowance used | Time | |---|---|---|--:|--:| | [Text to image, 9:16](#3-images-from-text) | [POST /jobs/image](/docs/api-muse-v1/post-muse-jobs-image) | 1152×2048 | not measured | 30 s | | [Text to image, exactly 16:9](#3-images-from-text) | [POST /jobs/image](/docs/api-muse-v1/post-muse-jobs-image) | 2048×1152 | 0% | 21 s | | [Rider + motorcycle + beach](#4-three-photos-into-one-picture) | [POST /jobs/image](/docs/api-muse-v1/post-muse-jobs-image) | 2048×1152 | 0% | 31 s | | [The ride as a video](#5-the-picture-as-a-video-no-re-upload) | [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video) | 1280×720, 10 s | 3% | 88 s | | [Restore an old photo](#6-restore-and-colorize-an-old-photo) | [POST /jobs/image](/docs/api-muse-v1/post-muse-jobs-image) | 1344×1792 | 1% | 34 s | | [The portrait speaks](#7-the-portrait-comes-to-life) | [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video) | 832×1104, 10 s | 2% | 68 s | | [Swap the rider](#8-swap-the-rider-in-the-video) | [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video) | 1248×704, 10 s | 3% | 138 s | Uploads use no allowance. On the free plan a video used 2 to 3 percent of the week and an image 0 to 1 percent, so one free account makes roughly 30 to 50 videos a week, or several hundred images ([step 9](#9-check-the-weekly-allowance)). ### Before you start You need a useapi.net [API token](/docs/start-here/setup-useapi) and a Muse account added through [Setup Muse](/docs/start-here/setup-muse). Before you add the account: - Muse is available in the US, Canada, [Japan](https://about.fb.com/ja/news/2026/10/muse-personal-ai-agent-launches-in-japan/) and [Singapore](https://about.fb.com/news/2026/10/muse-is-now-available-in-singapore-the-worlds-first-personal-ai-agent-built-for-everyone/) (as of October 30, 2026), so create the account in one of them. Once it is added, you can call the API from anywhere. - Finish Muse's onboarding at [muse.ai](https://muse.ai), including Meta's age check, and create one image there. - The account must have email + password sign-in, because the API signs in with the email and password. A Meta account that signs in only with an emailed code has no password yet: create one in [Meta Accounts Center](https://accountscenter.meta.com/password_and_security/) (Password and security), then add the account here. Without a password the add is refused with `400`. - Use the account only for the API, with no other automation tools on it. Opening it at muse.ai in a browser is fine, but only from the US, Canada, Japan or Singapore (the regions Muse officially supports), or through a VPN in one of them: Meta can switch off video for an account it sees used from elsewhere. Every call is also in the [Postman collection](/assets/postman/muse-v1.json). No code: the [Old Photo to Talking Video]({% include n8n-url.html t="muse-photo" %}) n8n template restores a photo and makes it talk from a form, and the [Narrated Faceless Shorts]({% include n8n-url.html t="muse-shorts" %}) template turns a topic into a narrated Short. The whole walkthrough is also on GitHub as one script, in Node.js and Python: [`images-videos/`](https://github.com/useapi/muse-api/tree/main/images-videos) in [useapi/muse-api](https://github.com/useapi/muse-api), plus an [agent skill](https://github.com/useapi/muse-api/tree/main/skills/muse-video) for Claude Code and Codex. The steps use `curl`, `jq` and these variables and helpers: <details markdown="block"> <summary>Expand the variables and helpers</summary> ```bash export USEAPI_TOKEN="user:12345-..." export EMAIL="example@gmail.com" export MUSE_PASSWORD="..." # the Muse account password, used once in step 1 API=https://api.useapi.net/v1/muse AUTH="Authorization: Bearer $USEAPI_TOKEN" enc() { jq -rn --arg v "$1" '$v|@uri'; } post() { curl -sS -X POST "$API/$1" -H "$AUTH" -H "Content-Type: application/json" -d "$2"; } get() { curl -sS "$API/$1" -H "$AUTH"; } upload() { curl -sS -X POST "$API/assets?email=$(enc "$EMAIL")" -H "$AUTH" -H "Content-Type: $2" --data-binary @"$1" | jq -r .assetId; } download() { curl -sSf "$API/assets/$(enc "$1")" -H "$AUTH" -o "$2"; } # run a job async: submit it, poll GET /jobs/{jobid} every 10 s, save the final job record to $1 run() { local job id job=$(post "$2" "$(jq '. + {async: true}' <<< "$3")") id=$(jq -r .jobid <<< "$job") while [ "$(jq -r .status <<< "$job")" = started ]; do sleep 10 job=$(get "jobs/$(enc "$id")") done echo "$job" > "$1" jq '{status, error, text: .result.text, asset: .result.assets[0].assetId}' "$1" } ``` </details> Every generation runs as a job. Without `async`, a POST waits up to about 100 seconds and returns the finished job record, or `202` with the job still running. A video here took 68 to 138 seconds, so `run` sends every job with `async: true` and polls [GET /jobs/`jobid`](/docs/api-muse-v1/get-muse-jobs-jobid). If `run` prints any `status` other than `completed`, read its `error` before going on. To be called back instead of polling, add `replyUrl: "https://example.com/hooks/muse"` (and optionally `replyRef`) to any body below. The API then sends one `POST` of the final job record, as JSON, to that URL. Ids contain `:` and `@`, so `enc` URL-encodes them whenever they go into a URL path. All inputs of one job must live on the same Muse account, so the uploads pin `email`, and a job runs on the account that holds its inputs. ### How it was built #### 1. Add the account [POST /accounts](/docs/api-muse-v1/post-muse-accounts) takes the Muse account's email and password. The API signs in once, keeps the 30-day session and renews it itself. Muse emails the account a login code at each sign-in. That email is only a notice, nothing needs to be entered. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-accounts">POST /accounts</a></summary> ```bash post accounts "$(jq -n --arg email "$EMAIL" --arg password "$MUSE_PASSWORD" '{email: $email, password: $password}')" | jq '{health, maxJobs, quota}' ``` </details> The answer shows `health: "OK"`, `maxJobs` (10 by default) and the account's plan and usage, here `tier: "HATCH_FREE"`, the free plan. If it answers `596` instead, Meta wants a security check: sign in once at muse.ai in a browser, complete it, and post the same email and password again. #### 2. Upload the photos [POST /assets](/docs/api-muse-v1/post-muse-assets) takes the raw file as the body, up to 50 MB, and writes it into the account's Muse workspace. Nothing is stored at useapi.net. The answer's `assetId` is what a job takes as `image_N`. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-assets">POST /assets</a></summary> ```bash BMW=$(upload bmw.jpeg image/jpeg) RIDER=$(upload rider.jpeg image/jpeg) BEACH=$(upload beach.jpeg image/jpeg) OLD_PHOTO=$(upload old-photo.jpeg image/jpeg) PINK=$(upload pink-hair.jpeg image/jpeg) echo "$BMW" # user:12345-email:6578616d706c6540676d61696c2e636f6d-image:7db53e7a1f0979cbab6ff46ec3f0a35b60e6ee579a0d738a9628cf46a0c7a0f5.jpg ``` </details> <div style="display: flex; flex-wrap: wrap; gap: 8px; align-items: flex-start"> <figure style="margin: 0; width: 32%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-motorcycle.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-motorcycle.jpg" alt="<code>image_1</code> — the motorcycle" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em"><code>image_1</code> — the motorcycle</figcaption></figure> <figure style="margin: 0; width: 18%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-redhead.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-redhead.jpg" alt="<code>image_2</code> — the rider" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em"><code>image_2</code> — the rider</figcaption></figure> <figure style="margin: 0; width: 32%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-beach.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-beach.jpg" alt="<code>image_3</code> — the beach" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em"><code>image_3</code> — the beach</figcaption></figure> <figure style="margin: 0; width: 18%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-oldphoto.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-oldphoto.jpg" alt="the old portrait" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">the old portrait</figcaption></figure> <figure style="margin: 0; width: 18%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-pinkhair.webp" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-pinkhair.webp" alt="the second rider" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">the second rider</figcaption></figure> </div> The five inputs: the motorcycle, the rider, the beach, the old portrait and the second rider. The asset id is built from the file's content, so uploading the same file to the same account again returns the same id and writes nothing. #### 3. Images from text Muse has no aspect-ratio parameter: the prompt says it. A vertical portrait first: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-image">POST /jobs/image</a></summary> ```bash run portrait.json jobs/image "$(jq -n '{prompt: "Vertical 9:16 full-body portrait photo: a confident young woman biker with long wavy fiery red hair, green eyes and freckles, in a worn black leather jacket, dark jeans and boots, standing in a rain-soaked neon alley at dusk, looking straight at the camera, cinematic lighting, photorealistic."}')" download "$(jq -r '.result.assets[0].assetId' portrait.json)" portrait.webp ``` </details> <img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-a2.webp" style="width: 100%; max-width: 420px" alt="Text to image at 9:16"> [open in new tab](https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-a2.webp){:target="_blank"} That came back at exactly 9:16, 1152×2048. A landscape version asked as `Cinematic 16:9 landscape photo: …` came back 1920×1280, which is 3:2. Writing the ratio as `in exactly 16:9 aspect ratio` fixed it: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-image">POST /jobs/image</a></summary> ```bash run bmw-noir.json jobs/image "$(jq -n '{prompt: "In exactly 16:9 aspect ratio (landscape), a cinematic photo of a vintage 1920s black BMW motorcycle with white pinstripes, spoked wheels and a brown leather saddle, parked on wet cobblestones at night in San Francisco, the Golden Gate Bridge glowing through fog in the distance, neo-noir moonlight, reflections on the wet street, shot on 35mm film."}')" download "$(jq -r '.result.assets[0].assetId' bmw-noir.json)" bmw-noir.webp ``` </details> <img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-a5.webp" style="width: 100%" alt="Text to image at exactly 16:9"> [open in new tab](https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-a5.webp){:target="_blank"} Muse answered "That 16:9 frame with the bridge ghosting through the fog is pure neo-noir. Enjoy." Its reply is in `result.text`. #### 4. Three photos into one picture Up to 9 images go into one job as `image_1`..`image_9`, and the prompt names them. Here the motorcycle is `image_1`, the rider `image_2` and the beach `image_3`. The prompt asks Muse to use the photographed beach as it is, so the Golden Gate Bridge stays where it was in the photo. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-image">POST /jobs/image</a></summary> ```bash run beach-ride.json jobs/image "$(jq -n --arg bmw "$BMW" --arg rider "$RIDER" --arg beach "$BEACH" \ '{image_1: $bmw, image_2: $rider, image_3: $beach, prompt: "In exactly 16:9 aspect ratio (landscape), a cinematic photo: the woman from image_2 (her face, long wavy red hair, light blue top and jeans) riding the exact vintage motorcycle from image_1 along the shoreline of the beach in image_3, the front wheel cutting through the shallow surf and throwing spray, bright afternoon sun, her hair streaming in the wind, photorealistic. Use the beach, rocks and Golden Gate Bridge from image_3 as the background exactly as photographed: same position, same orientation, not mirrored or redrawn. Keep her face and the motorcycle'\''s design exactly as in the images."}')" BEACH_RIDE=$(jq -r '.result.assets[0].assetId' beach-ride.json) download "$BEACH_RIDE" beach-ride.webp ``` </details> <img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g1.webp" style="width: 100%" alt="The rider, the motorcycle and the beach in one picture"> [open in new tab](https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g1.webp){:target="_blank"} 31 seconds, and no visible change in the weekly allowance. #### 5. The picture as a video, no re-upload `BEACH_RIDE` is the id of a file Muse made. It is already in the account's workspace, so it goes straight into the next job as `image_1`, with no download and no upload. `Animate image_1` makes a clip that starts from the picture and keeps its shape, and the line in quotes is spoken. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-video">POST /jobs/video</a></summary> ```bash run surf.json jobs/video "$(jq -n --arg img "$BEACH_RIDE" '{image_1: $img, prompt: "Animate image_1 into a cinematic video in exactly 16:9 aspect ratio (landscape): she rides the vintage motorcycle along the shoreline, the front wheel slices through the shallow waves and sends spray flying, the old engine roars, she raises one fist and shouts with a laugh: \"Nothing beats this view!\" The camera tracks alongside her. The beach, the rocks and the Golden Gate Bridge stay exactly as in image_1 (same orientation). Keep her face and the motorcycle exactly as in image_1."}')" SURF=$(jq -r '.result.assets[0].assetId' surf.json) download "$SURF" surf.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g2-poster.jpg" src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g2.mp4" style="width: 100%; aspect-ratio: 16/9; max-width: 720px" controls type="video/mp4" preload="metadata"></video> Also on YouTube: [3 photos in, 1 talking video out: Meta Muse API from REST](https://youtube.com/shorts/v_7mREyFSWk). 10 seconds at 1280×720 with sound. Muse said "Done. 10 seconds, 16:9 landscape, straight from your image — no edits, no upscaling." The first try of this exact job failed after 37 seconds: Muse answered that "the video worker glitched out before it rendered anything, so no clip was made". The API reports an answer like that as `503`, nothing made, and the same request worked when run again. A refusal on content grounds is a `403` instead, and needs a different prompt. #### 6. Restore and colorize an old photo An image job can also repair an image. The old portrait is a faded sepia photo of 685×900 pixels, 3:4. The prompt lists what to fix and insists on the same frame. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-image">POST /jobs/image</a></summary> ```bash run restored.json jobs/image "$(jq -n --arg img "$OLD_PHOTO" '{image_1: $img, prompt: "Restore the old photograph image_1 as a high-quality modern photo: remove the scratches, dust, stains, fading and grain, recover sharp detail in the face, hair and fabric, and colorize it naturally (warm natural skin tones, dark brown hair, ivory tulle shawl, a soft pink rose with green leaves, a muted warm background). Keep the exact same person, expression, pose, framing and crop, and the same portrait aspect ratio as image_1 (3:4, 685×900): do not crop, extend or reframe it."}')" RESTORED=$(jq -r '.result.assets[0].assetId' restored.json) download "$RESTORED" restored.webp ``` </details> <div style="display: flex; flex-wrap: wrap; gap: 8px; align-items: flex-start"> <figure style="margin: 0; width: 48%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-oldphoto.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-input-oldphoto.jpg" alt="Before: the original, 685×900" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">Before: the original, 685×900</figcaption></figure> <figure style="margin: 0; width: 48%"><a href="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-e1.webp" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-e1.webp" alt="After: restored and colorized, 1344×1792" style="width: 100%"></a><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">After: restored and colorized, 1344×1792</figcaption></figure> </div> The result is 1344×1792, the same 3:4 frame at about twice the size, with the same pose and crop. Muse said "Done — restored, de-grained, and colorized, same framing and pose." #### 7. The portrait comes to life The restored image goes straight into a video job. The clip keeps the portrait's shape, so it came back 832×1104. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-video">POST /jobs/video</a></summary> ```bash run portrait-video.json jobs/video "$(jq -n --arg img "$RESTORED" '{image_1: $img, prompt: "Animate image_1 into a video with the same portrait frame: the young woman slowly lifts her eyes to the camera, her smile widens, she gently touches the rose on her shoulder and says softly: \"It has been a hundred years... and you still remember me.\" A light breeze moves a few strands of her hair, soft window light, the camera stays still with a very slow push-in. Keep her face exactly as in image_1."}')" download "$(jq -r '.result.assets[0].assetId' portrait-video.json)" portrait.mp4 ``` </details> <video poster="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-e2-poster.jpg" src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-e2.mp4" style="width: 100%; aspect-ratio: 832/1104; max-width: 420px" controls type="video/mp4" preload="metadata"></video> Also on YouTube: [This old portrait just spoke: one API call (Meta Muse API, third-party)](https://youtube.com/shorts/GLHoINX_ozE). #### 8. Swap the rider in the video A video job also takes videos. `video_1` is the surf clip from step 5, and `image_1` is the photo of a second woman with pink hair in two buns. The prompt asks Muse to replace the rider and keep everything else, and gives her a new line. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-video">POST /jobs/video</a></summary> ```bash run swap.json jobs/video "$(jq -n --arg vid "$SURF" --arg img "$PINK" '{video_1: $vid, image_1: $img, prompt: "Edit video_1: replace the rider with the woman from image_1 (her face, pink hair in two buns, colorful makeup and tattoos), and keep everything else the same: the motorcycle, the beach, the waves and spray, the Golden Gate Bridge, the light, the camera move and the timing. Instead of the original line she shouts: \"Catch me if you can, San Francisco!\" Keep the 16:9 frame and the same length."}')" download "$(jq -r '.result.assets[0].assetId' swap.json)" swap.mp4 ``` </details> <div style="display: flex; flex-wrap: wrap; gap: 8px; align-items: flex-start"> <figure style="margin: 0; width: 48%"><video poster="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g2-poster.jpg" src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g2.mp4" style="width: 100%; aspect-ratio: 16/9" controls type="video/mp4" preload="metadata"></video><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">Before: the original rider</figcaption></figure> <figure style="margin: 0; width: 48%"><video poster="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g3-poster.jpg" src="https://media.useapi.net/articles/2026-10-12-muse-api-zh/muse-g3.mp4" style="width: 100%; aspect-ratio: 1248/704" controls type="video/mp4" preload="metadata"></video><figcaption style="text-align: center; margin-top: 6px; font-size: 0.85em">After: the rider from the photo</figcaption></figure> </div> At 138 seconds this was the slowest job of the walkthrough, which is why every job here runs async. The clip is the same ride with the other woman on the motorcycle, shouting the new line. Muse said "Done. She's in, 10 seconds, 16:9, same ride, same bridge, same waves." Also on YouTube: [Replace the person in a video, keep everything else: Meta Muse API](https://youtube.com/shorts/XDCY1XIsd5Y). #### 9. Check the weekly allowance [GET /accounts/`email`](/docs/api-muse-v1/get-muse-accounts-email) reads the account's plan and usage live: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/get-muse-accounts-email">GET /accounts/email</a></summary> ```bash get "accounts/$(enc "$EMAIL")" | jq '{session, quota}' ``` </details> `quota.percentUsed` is the share of the week used, in whole percent, and `quota.resetsAt` is when it starts over, a week after it began. The three videos above used 2 to 3 percent each and the images 0 or 1. Over the whole test session, which also ran two jobs not shown here, the free account went from 16 to 28 percent. When an account runs out, new jobs without `email` go to your other accounts, and a job pinned to it answers `412` until `resetsAt`. ### What we learned - Write the aspect ratio as `in exactly 16:9 aspect ratio`. `Cinematic 16:9 landscape photo` came back 3:2 once. - Every video is about 10 seconds. A prompt asking for 5 seconds still got 10. - An image-to-video clip keeps the shape of its image unless the prompt asks for another one: `in exactly 9:16 aspect ratio` turned our 16:9 beach picture into a vertical 720×1280 clip, re-framed rather than stretched. - Lines written in quotes in a video prompt are spoken. - Pass generated files on by `assetId`. They stay in the account's workspace, so a chain of edits needs no downloads in between. - Say what must stay the same. "Same position, same orientation, not mirrored or redrawn" kept the real beach in the composite. - A `503` with Muse's own words such as "glitched out" is worth running again. A `403` is a refusal and needs a different prompt. - Send videos with `async: true`. A sync request waits about 100 seconds, and the swap took 138. ### Make a 30-second narrated Short (script, three scenes, one join) A Muse video is always about 10 seconds, so a 30-second vertical Short with a narrator takes three video jobs and two chats. One [chat](/docs/api-muse-v1/post-muse-chats) writes the script as JSON, three [video jobs](/docs/api-muse-v1/post-muse-jobs-video) run side by side, one per scene, each speaking its line in the same narrator's voice, and a last chat joins the clips with ffmpeg in the account's own workspace. The Short below, about the 1815 eruption of Mount Tambora and the "year without a summer" that followed, went from a one-line topic to an MP4 in about 2 minutes. <video poster="https://media.useapi.net/articles/2026-10-12-muse-images-videos-id/muse-narrated-short-tambora-poster.jpg" src="https://media.useapi.net/articles/2026-10-12-muse-images-videos-id/muse-narrated-short-tambora.mp4" style="width: 100%; aspect-ratio: 9/16; max-width: 420px" controls type="video/mp4" preload="metadata"></video> Also on YouTube: [A narrated 30-second Short made only with Meta Muse API calls](https://youtube.com/shorts/1e8f7dHTkzs). Three 10-second clips joined into one 720×1280 Short of 30 seconds, from the topic "how a single volcano cooled the whole planet in 1816". The script took 11 seconds, the three clips 75, 75 and 87 seconds running at the same time, and the join 20 seconds, so a Short takes about 2 to 3 minutes. This one was made on a paid Muse plan. There, the four videos of that test session (these three and one more) moved the weekly reading by 2 points in all, and the chats by none. On the free plan a video uses 2 to 3 percent of the week, so a three-scene Short costs about 6 to 9 percent there. No code: the same flow is an n8n app, the [Narrated Faceless Shorts]({% include n8n-url.html t="muse-shorts" %}) template, with a form, a script page and Google Drive save. Two Shorts it made, published as they came out: [The Great Pyramid was once bright white](https://youtube.com/shorts/D-Nk0x9aJMo) and [Why honey never spoils](https://youtube.com/shorts/bYLsJIqerSM), which it voiced with Muse text to speech. The whole workflow is also one script, in Node.js and Python: [`narrated-short/`](https://github.com/useapi/muse-api/tree/main/narrated-short) in [useapi/muse-api](https://github.com/useapi/muse-api). It takes a topic, and optionally the number of scenes and your own narrator description, and saves the Short to `output/`. The steps use the [helpers above](#before-you-start) plus `chat`, which starts a chat and reads [GET /chats/`chatId`](/docs/api-muse-v1/get-muse-chats-chatId) until Muse is done: <details markdown="block"> <summary>Expand the chat helper</summary> ```bash # start a chat, poll GET /chats/{chatId} every 8 s until Muse is done, save the chat to $1 chat() { local id c id=$(post chats "$2" | jq -r .chatId) while sleep 8; do c=$(get "chats/$(enc "$id")") jq -e '.pendingApprovals | length > 0' <<< "$c" > /dev/null && echo "Muse asks for permission: answer it with POST /chats/{chatId}/approvals/{approvalId}" jq -e '(.status | IN("completed", "interrupted", "failed")) and (.pendingApprovals | length == 0)' <<< "$c" > /dev/null && break done echo "$c" > "$1" jq '{status, reply: ([.messages[] | select(.role == "assistant" and .text != "")][-1].text)}' "$1" } ``` </details> Every request below pins `email`. A chat that takes files must run on the account that holds them, so the three clips and the join all stay on one account. #### 1. Write the script as JSON The first chat asks for exactly three scenes and spells out the JSON shape. Each scene has a `line`, what the narrator says, kept to 25 words so it fits in 10 seconds, and a `visual`, one sentence describing the shot. The prompt also tells Muse not to make any files, so the chat stays text only. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-chats">POST /chats</a></summary> ```bash TOPIC="how a single volcano cooled the whole planet in 1816" chat script.json "$(jq -n --arg email "$EMAIL" --arg topic "$TOPIC" '{email: $email, message: "Write a script for a 30-second faceless YouTube Short about: \"\($topic)\". Exactly 3 scenes. Reply with ONLY a JSON object, no prose, no markdown code fences, in this exact shape: {\"title\": string, \"scenes\": [{\"line\": string, \"visual\": string}, {\"line\": string, \"visual\": string}, {\"line\": string, \"visual\": string}]}. \"line\" is what the off-screen narrator says (at most 25 words, about 9 seconds spoken). \"visual\" is a one-sentence description of the 10-second shot, no people talking on camera. Do not create any files, images or videos."}')" jq -r '[.messages[] | select(.role == "assistant" and .text != "")][-1].text' script.json | sed '/^```/d' > scenes.json jq . scenes.json ``` </details> Muse answered in 11 seconds with the JSON alone: ```json { "title": "How One Volcano Cooled the Whole Planet in 1816", "scenes": [ { "line": "In April 1815, Mount Tambora in Indonesia erupted, the largest explosion in recorded history, blasting ash forty kilometers into the sky.", "visual": "A massive volcanic eruption at dawn, with a towering ash column rising into the stratosphere above a dark island." }, { "line": "That ash veil circled Earth, blocking sunlight and dropping global temperatures, turning summer into winter across North America and Europe.", "visual": "An animated globe wrapped in a gray haze as sunlight dims and frost spreads across continents." }, { "line": "1816 became the Year Without a Summer: crops failed, snow fell in July, and famine spread as the planet shivered.", "visual": "Snow falling over green farmland in summer, covering withered crops and empty village fields under a pale sun." } ] } ``` We ran the same prompt for three topics and got clean JSON every time, in 11 to 29 seconds, with no code fences and no extra text. That is a small sample, so the `sed` drops a stray ```` ``` ```` fence line anyway, and the GitHub script asks once more when the reply does not parse. #### 2. Three scenes at once Each scene becomes one async [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video). All three prompts carry the same narrator description, word for word, followed by `The narrator says exactly: "<line>"`. Muse speaks a quoted line as written, and the shared description keeps the voice consistent from clip to clip. `Vertical 9:16 video` came back 720×1280. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-jobs-video">POST /jobs/video</a></summary> ```bash NARRATOR="Narration: one off-screen narrator only, the same voice throughout: a calm, deep, middle-aged British male documentary narrator, measured pace, warm and authoritative, like a nature documentary. Nobody on screen speaks. No music." for i in 0 1 2; do post jobs/video "$(jq --arg email "$EMAIL" --arg narrator "$NARRATOR" --argjson i $i '.scenes[$i] | {email: $email, async: true, prompt: "Vertical 9:16 video, about 10 seconds. \(.visual) Slow cinematic camera move, photoreal. \($narrator) The narrator says exactly: \"\(.line)\""}' scenes.json)" | jq -r .jobid done > jobs.txt ``` </details> Each POST answers `201` at once with a `jobid`. The three jobs take three of the account's `maxJobs` slots (10 by default), so they run side by side. A `429` here means every slot is busy and nothing was started: send that one again in 30 seconds. #### 3. Poll the jobs [GET /jobs/`jobid`](/docs/api-muse-v1/get-muse-jobs-jobid) answers `status: "started"` until the clip is ready. The jobs run in parallel, so reading them one after another adds no time: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/get-muse-jobs-jobid">GET /jobs/jobid</a></summary> ```bash for n in 1 2 3; do id=$(sed -n "${n}p" jobs.txt) until job=$(get "jobs/$(enc "$id")"); [ "$(jq -r .status <<< "$job")" != started ]; do sleep 10; done echo "$job" > clip$n.json jq '{status, error, text: .result.text, asset: .result.assets[0].assetId}' clip$n.json done ``` </details> All three completed. Muse said "Here it is — vertical 9:16, photoreal volcanic eruption at dawn with the narration as specified" about the first. Each clip speaks its line word for word, and every line, 20 to 21 words long, fit inside its 10 seconds. A job that failed with `503` made nothing and can run again. Any other failure, such as a `403` refusal, needs a look at `error.message` first. #### 4. Join the clips in one chat The three clip ids go into one chat as `files`, where Muse sees them as `video_1`, `video_2` and `video_3`. The message asks for ffmpeg, the order, the audio and a file name, and ends with `No public links.` With that line, Muse did not stop to ask for permission. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-chats">POST /chats</a></summary> ```bash CLIPS=$(jq -s '[.[].result.assets[0].assetId]' clip1.json clip2.json clip3.json) chat join.json "$(jq -n --arg email "$EMAIL" --argjson files "$CLIPS" '{email: $email, files: $files, message: "Concatenate video_1, video_2, video_3 in order into one MP4 with ffmpeg, keep the audio, save it to workspace/your_files/short.mp4 and attach it here. No public links."}')" SHORT=$(jq -r '[.messages[] | select(.role == "assistant") | .files[] | select(.type == "video")][-1].assetId' join.json) echo "$SHORT" # user:12345-email:6578616d706c6540676d61696c2e636f6d-video:ws~your_files~short.mp4 ``` </details> 20 seconds later Muse said "Concatenated all three in order — 30 seconds, 720x1280, with audio kept." and attached the file as a message of its own, one `video` in its `files`. Its asset id is named after the workspace path, so give each Short its own file name. ffmpeg copied the streams without re-encoding them: the Short is exactly 30.0 seconds, and all three lines are in it, in order. #### 5. Download the Short [GET /assets/`assetId`](/docs/api-muse-v1/get-muse-assets-assetId) returns the MP4: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/get-muse-assets-assetId">GET /assets/assetId</a></summary> ```bash download "$SHORT" tambora-short.mp4 ``` </details> The clips and the Short also stay in the account's Muse workspace, where the muse.ai app shows them, and the Short's asset id can go into the next job as `video_1`. #### A fixed voice instead: text to speech as audio_1 A shared description gives the same kind of voice, not a locked one. In the three Tambora clips the narrator's median pitch was 105 to 117 Hz, less than two semitones apart, but Muse voices each clip anew. For one voice for certain, have Muse speak each line with its text to speech first, then pass that MP3 to the video job as `audio_1`. The text to speech chat took 20 seconds in our test. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-muse-v1/post-muse-chats">POST /chats</a> and <a href="/docs/api-muse-v1/post-muse-jobs-video">POST /jobs/video</a></summary> ```bash chat voice1.json "$(jq -n --arg email "$EMAIL" --arg line "$(jq -r '.scenes[0].line' scenes.json)" '{email: $email, message: "Generate one mp3 file with text to speech: single speaker, voice Aria (avocado_v2:MAI_01), speed 100, language en, clean narration only: no music, no sound effects. Read exactly this text, do not change any word:\n\"\($line)\"\nSave it directly in workspace/your_files/ (not in a subfolder) as line-1.mp3 and attach it here. No public links and no uploads to remote storage."}')" VOICE1=$(jq -r '[.messages[] | select(.role == "assistant") | .files[] | select(.type == "audio")][-1].assetId' voice1.json) run clip1.json jobs/video "$(jq --arg email "$EMAIL" --arg voice "$VOICE1" '.scenes[0] | {email: $email, audio_1: $voice, prompt: "Vertical 9:16 video, about 10 seconds, no people on screen and nobody speaking on camera. \(.visual) Slow cinematic camera move, photoreal. Use audio_1 as the narration soundtrack exactly as it is: the off-screen narrator'\''s voice in audio_1, word for word, with no other voice and no new speech. Quiet ambient sound under it is fine."}' scenes.json)" jq -r '.result.assets[] | select(.origin == "made") | .assetId' clip1.json ``` </details> Muse makes its clip and then lays `audio_1` onto it with ffmpeg. The job lists both files: the finished copy first, with `origin: "made"`, and Muse's raw clip after it, with `origin: "generated"`. Take the `made` one. The raw clip carries a voice Muse made up instead of yours. The video job took 108 seconds in our test. Repeat it for each scene and join the `made` clips as in step 4. ### Frequently asked questions **Is there an API for Meta Muse (muse.ai)?** Through useapi.net, yes: the [Muse API](/docs/api-muse-v1) is a third-party API that runs Muse on your [Muse website subscription](https://www.meta.com/help/subscriptions/1021145227643680/). Make images with [POST /jobs/image](/docs/api-muse-v1/post-muse-jobs-image) and videos with [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video). Meta's official [Model API](https://dev.meta.ai/docs/pricing-rate-limits) sells the Muse Image model at $0.01 per image, but as of October 2026 it has no video generation and no API for the Muse agent at muse.ai, where the videos are made. Our [Meta Muse video API comparison](/docs/articles/meta-muse-video-api) covers muse2api too. **Does it work on the free Muse plan?** Through useapi.net, yes: this walkthrough was made on the free plan (`HATCH_FREE`), which has a weekly allowance. A video used 2 to 3 percent of it and an image 0 to 1 percent, so one free account makes roughly 30 to 50 videos a week. The paid Power ($20 a month) and Maximum ($100 a month) plans raise the allowance (as of October 2026). **Can Muse make a video longer than 10 seconds?** Through useapi.net, not in one job: every video is about 10 seconds. Make one clip per scene and have a [chat](/docs/api-muse-v1/post-muse-chats) join them with ffmpeg, as in [Make a 30-second narrated Short](#make-a-30-second-narrated-short-script-three-scenes-one-join), where three clips became one Short in about 2 to 3 minutes. One chat takes up to 3 videos. **How do I set the aspect ratio, length or resolution?** Through useapi.net, in the prompt, because Muse has no parameters for them. The aspect ratio is followed when written as `in exactly 16:9 aspect ratio`, and an image-to-video clip keeps the shape of its image unless the prompt asks for another. Length and resolution stay fixed: every video comes back at about 720p with sound, whatever the prompt asks. **Can I use my own photos and videos?** Through useapi.net, yes: upload them with [POST /assets](/docs/api-muse-v1/post-muse-assets), up to 50 MB each, and pass the `assetId` as `image_1`..`image_9`, the same way you pass a result from an earlier job. [Video jobs](/docs/api-muse-v1/post-muse-jobs-video) also take `video_1`..`video_3` and `audio_1`..`audio_3`. All inputs of one job must be on the same account. **How do I make a photo talk?** Through useapi.net, pass the photo as `image_1` to [POST /jobs/video](/docs/api-muse-v1/post-muse-jobs-video) with a prompt like `Animate image_1: … she says softly: "…"`. Muse keeps the photo's shape and speaks the line in quotes, as in [step 7](#7-the-portrait-comes-to-life), where a restored hundred-year-old portrait looks up and talks. **Can it replace a person in a video?** Through useapi.net, yes: pass the clip as `video_1` and a photo of the new person as `image_1`, and ask Muse to replace the person and keep everything else, as in [step 8](#8-swap-the-rider-in-the-video). Say what must stay the same, such as the ride, the bridge and the waves, and give the new person a line in quotes if they should speak. **Why did my sync request return 202?** Through useapi.net, a `202` means the job was still running after about 100 seconds, and it keeps running on our side. Fetch it with [GET /jobs/`jobid`](/docs/api-muse-v1/get-muse-jobs-jobid), send long jobs with `async: true` and poll, or add a `replyUrl` to have the finished job record posted to you. In our runs, a video took 68 to 138 seconds. **Why did Muse email me a login code?** Through useapi.net, the API signed in to your Muse account, which happens when you add it and when the API renews the 30-day session, before it expires or whenever Muse asks for a new sign-in. Muse emails a login code on each sign-in, and nothing needs to be done with it. See [Setup Muse](/docs/start-here/setup-muse#what-to-expect). **How is this different from muse2api?** Through useapi.net, the Muse API is hosted, so there is nothing to deploy: you add each account with its email and password and we keep it signed in. Results chain by asset id, and a finished job can call your webhook. You can also [chat with the Muse agent](/docs/api-muse-v1/chat-streaming-guide), with its answers streamed live. [muse2api](https://github.com/czg86389-hub/muse2api) is a project you deploy, host and keep running yourself. ### Conclusion Visit our <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> or <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> for any support questions and concerns. Check our [GitHub repo](https://github.com/useapi/muse-api) with code examples. The same calls are available as tools on the hosted [Muse MCP server](/docs/api-muse-v1/mcp) for Claude Code, Cursor and VS Code. #### Cross posted Also published on [dev.to](https://dev.to/useapi/how-to-generate-ai-images-and-videos-with-the-muse-api-274){:rel="nofollow"}, discussed on [Reddit](https://www.reddit.com/r/ThirdPartyAPI/comments/1x3udcd/how_to_generate_ai_images_and_videos_with_the/){:rel="nofollow"}, shared on [Bluesky](https://bsky.app/profile/useapi.net/post/3mxnuj43mcs2w){:rel="nofollow"}, and on YouTube as a [2:49 demo of the whole API](https://www.youtube.com/watch?v=OMUGbfRIO5E). === URL: https://useapi.net/docs/articles/notebooklm-api-options === Document URL: https://useapi.net/docs/articles/notebooklm-api-options --- layout: default title: "Gemini Notebook (NotebookLM) API Options in 2026: Google Enterprise API, Free Libraries or a Hosted API" seo_title: "Gemini Notebook (NotebookLM) API Options 2026: Free Libraries, MCP and Hosted REST" description: "Does Gemini Notebook (NotebookLM) have an API? Google's Enterprise API, free Python libraries and MCP servers, and the hosted useapi.net REST API and MCP server, compared." keywords: [NotebookLM API, Gemini Notebook API, NotebookLM API free, NotebookLM API Python, NotebookLM MCP, NotebookLM MCP server, NotebookLM GitHub, notebooklm-py, NotebookLM Enterprise API, Gemini Notebook Enterprise API, NotebookLM REST API, NotebookLM API key, NotebookLM podcast API, Audio Overview API] image: https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-infographic-sketch-note-apollo11-0929.png parent: Articles nav_exclude: true date: 2026-10-16 last_modified: 2026-10-18 nav_order: 902 repo: https://github.com/useapi/notebooklm-api --- ## Gemini Notebook (NotebookLM) API Options in 2026: Google Enterprise API, Free Libraries or a Hosted API 6 min read • October 16, 2026 (October 18, 2026) ## Table of contents ### Does Gemini Notebook (NotebookLM) have an API? Not for regular Google accounts. Google renamed NotebookLM to Gemini Notebook in July 2026, and its only official API is the [Gemini Notebook Enterprise API](https://docs.cloud.google.com/gemini/enterprise/notebooklm-enterprise/docs/api-notebooks): a Preview API for Enterprise licenses in a Google Cloud project, which manages notebooks and sources and creates Audio Overviews. If you want to automate Gemini Notebook on an ordinary free or paid Google account, there are three kinds of options: 1. **Google's Enterprise API**, if your organisation buys Enterprise licenses. 2. **Free open-source libraries and local MCP servers**, such as [notebooklm-py](https://github.com/teng-lin/notebooklm-py) and [gemini-notebook-mcp-cli](https://github.com/jacob-bd/gemini-notebook-mcp-cli), which you install and run on your own machine. 3. **A hosted API**, such as the [useapi.net Gemini Notebook API (NotebookLM API)](/docs/api-gemini-notebook-v1), which runs on our servers with your own Google account, over REST and as a hosted [MCP server](/docs/api-gemini-notebook-v1/mcp). This page is written by the useapi.net maintainers and compares what each option offers from its own documentation. ### Compared | | useapi.net | notebooklm-py | gemini-notebook-mcp-cli | Google Enterprise API | |---|:--:|:--:|:--:|:--:| | Hosted, nothing to install or run locally | Yes | No | No | Yes | | Hosted MCP server for Claude Code, Cursor, VS Code | Yes | No (local only) | No (local only) | No | | Works on free and paid consumer Google accounts | Yes | Yes | Yes | No | | Sign-in without copying cookies; session kept fresh for you | Yes | No | No | Yes | | REST API from any language | Yes | No | No | Yes | | Webhook when a job finishes | Yes | No | No | No | | Automatic load balancing across Google accounts | Yes | No | No | No | | Ready-to-import n8n templates | Yes | No | No | No | | Cost | Your Google AI subscription, the free plan included | Free | Free | Enterprise licenses | From each project's own documentation on October 16, 2026: notebooklm-py v0.8.5, gemini-notebook-mcp-cli v0.15.5, Gemini Notebook Enterprise API (Preview). useapi.net is a third-party API and is not affiliated with Google. ### Why useapi.net instead of a free library useapi.net is a third-party API and is not affiliated with Google. - **Nothing to run on your machine.** The API is hosted, so jobs keep running when your laptop is off: no Chromium download, no local server, no tunnel and no browser left open. - **Sign in once, we keep you signed in.** The guided browser [setup](/docs/start-here/setup-gemini-notebook) connects your Google account once, and we keep the session fresh, with no cookies to copy or refresh. If Google ever signs it out, you get an email with a one-minute re-add link. - **A hosted [MCP server](/docs/api-gemini-notebook-v1/mcp), 57 tools.** Add it to Claude Code, Cursor or VS Code with one line. Nothing to install, and every notebook, source, chat and Studio output is available to your AI assistant. - **Plain REST from any language.** Call it from Node.js, Python, bash, n8n, Make or a cron job with an API token. A Postman collection and an LLM-friendly spec cover every endpoint. - **Jobs tracked for you, with webhooks.** Every podcast, video, slide deck and research run is a server-side job. Poll it, or pass `replyUrl` and get the finished result posted to your endpoint. - **Several Google accounts, balanced automatically.** Connect 3 accounts per subscription, up to 100; each new job goes to one that is healthy, has a free slot and still has usage left. - **Links in, podcast out.** Send URLs or text to one endpoint and get an Audio Overview, Video Overview, slide deck or quiz back, with no notebook setup. - **Ready-made [n8n workflows]() and an agent skill**, on your free or paid Google plan, for a flat [$15/month](/docs/subscription) that covers every useapi.net API. ### What the useapi.net Gemini Notebook API covers Everything you do in Gemini Notebook, from code: - **Notebooks and sources.** Create, copy and share notebooks and group them in collections. Add web pages, YouTube videos, pasted text, uploaded files (PDF, Word, PowerPoint, EPUB, audio, video), Google Drive files and ebooks from your Google Play Books library. - **Chat with citations.** Ask questions grounded in your sources, with numbered citations and follow-up conversations. - **Research.** Discover sources and run Deep Research, then import the sources and the report. - **Every Studio output.** Audio Overviews (deep dive, brief, critique, debate), Video Overviews (including short and cinematic), slide decks, infographics, reports, data tables, quizzes, flashcards and mind maps, with revise, retry, copy and export. - **Usage you can see.** Each account's live usage in Google's 5-hour and weekly windows. The full list is in the [API reference](/docs/api-gemini-notebook-v1). ### How to start 1. Get a useapi.net [API token](/docs/start-here/setup-useapi). 2. Connect a Google account once with the guided [Gemini Notebook setup](/docs/start-here/setup-gemini-notebook). The free Google plan works. 3. Turn a web page into a podcast with one call: ```bash curl -X POST https://api.useapi.net/v1/gemini-notebook/artifacts \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{"type": "audio", "urls": ["https://en.wikipedia.org/wiki/Apollo_11"]}' ``` Or add the [MCP server](/docs/api-gemini-notebook-v1/mcp) to Claude Code with one line: ```bash claude mcp add --transport http useapi-gemini-notebook https://api.useapi.net/v1/gemini-notebook/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` Step-by-step tutorials: [Deep Research, chat and Audio Overviews with curl](/docs/articles/gemini-notebook-bash), [a real podcast example](/docs/articles/notebooklm-podcast-example) and [RSS feeds to podcasts with n8n](/docs/articles/notebooklm-n8n-podcast). Runnable code: [useapi/notebooklm-api](https://github.com/useapi/notebooklm-api). ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. ### Frequently asked questions **Is there a free Gemini Notebook (NotebookLM) API?** The useapi.net API works on the free Google plan, while Google offers no API for regular accounts. Free open-source libraries exist and run on your own machine. **Is there a Gemini Notebook (NotebookLM) API key?** You use a useapi.net API token and connect your Google account once, since Google issues no Gemini Notebook API key for regular accounts. **Can I use Gemini Notebook (NotebookLM) from Python?** Yes. The useapi.net API is plain REST, so any HTTP client works. The [examples repository](https://github.com/useapi/notebooklm-api) has Node.js, Python and bash scripts and a Colab notebook. **Is there a Gemini Notebook MCP server (NotebookLM MCP server)?** Yes. The hosted [useapi.net Gemini Notebook MCP server](/docs/api-gemini-notebook-v1/mcp) has 57 tools and is listed in the official MCP Registry as `net.useapi/gemini-notebook`. You add it to Claude Code, Cursor or VS Code with one line, with nothing to install. **Do I have to copy cookies or keep a browser open?** No. You sign in once through the guided setup, and we keep the session fresh. If Google ever signs the account out, you get an email with a link to re-add it. === URL: https://useapi.net/docs/articles/notebooklm-n8n-podcast === Document URL: https://useapi.net/docs/articles/notebooklm-n8n-podcast --- layout: default title: "How to Turn Web Pages, YouTube Videos and RSS Feeds into Gemini Notebook (NotebookLM) Podcasts with n8n" description: "A free n8n app that turns links or a blog's RSS feed into a Gemini Notebook (NotebookLM) podcast you can play in the browser, through the useapi.net Gemini Notebook API on your own Google account." keywords: [NotebookLM n8n, NotebookLM podcast automation, RSS to podcast, web page to podcast, YouTube to podcast, NotebookLM Audio Overview API, NotebookLM API, n8n template, Gemini Notebook API, AI podcast generator] image: https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-infographic-sketch-note-apollo11-0929.png parent: Articles nav_exclude: true date: 2026-10-04 last_modified: 2026-10-18 nav_order: 893 repo: https://github.com/useapi/notebooklm-api --- ## How to Turn Web Pages, YouTube Videos and RSS Feeds into Gemini Notebook (NotebookLM) Podcasts with n8n October 4, 2026 (October 18, 2026) ## Table of contents ### Introduction The free NotebookLM Podcast App for n8n turns web pages, YouTube videos or a blog's RSS feed into a Gemini Notebook podcast through the [useapi.net Gemini Notebook API (NotebookLM API)](/docs/api-gemini-notebook-v1), and plays the finished episode right in your browser. You paste links into a form, or let a weekly schedule read your feed. It uses only core n8n nodes and runs on your own Google account, including a free one. The episode below came from the app's RSS path, pointed at Google's AI blog feed with the format set to `brief` and the length to `short`. Run once by hand, it picked up the two posts from the past week and produced a 1 min 43 s episode in 3 min 23 s. <audio controls class="audio-player" style="width:100%"><source src="https://media.useapi.net/articles/2026-10-04-notebooklm-n8n-podcast/notebooklm-n8n-rss-weekly-ai-digest-brief-1004.m4a" type="audio/mp4"></audio> "Google AI Fights Cyberattacks and Disease", made from the Google AI blog feed, brief format, short length, 1 min 43 s, generated in 3 min 23 s ### The workflows | Workflow | What it does | File | |---|---|---| | NotebookLM Podcast App | A form and a weekly RSS schedule share one pipeline. The form shows what Google read, plays the podcast in the browser and lets you download it | [`notebooklm-podcast-app.json`](https://github.com/useapi/notebooklm-api/blob/main/n8n/notebooklm-podcast-app.json) | | Links to podcast (minimal) | The bare form pipeline, leaving the `.m4a` as binary data for your next node | [`notebooklm-podcast.json`](https://github.com/useapi/notebooklm-api/blob/main/n8n/notebooklm-podcast.json) | | RSS feed to podcast (minimal) | The bare weekly RSS pipeline | [`notebooklm-rss-podcast.json`](https://github.com/useapi/notebooklm-api/blob/main/n8n/notebooklm-rss-podcast.json) | All three files are in the [notebooklm-api](https://github.com/useapi/notebooklm-api/tree/main/n8n) repository on GitHub, MIT-licensed, and were tested on self-hosted n8n 2.41. Start with the app{% include n8n-listed.html t="notebook-podcast" %}. The minimal versions are there if you want to build your own flow around the same API calls. ### How the app works Open the form, give the episode a title and paste up to 50 links, one per line. Pick a format (deep dive, brief, critique or debate), a length, one of 20 languages, and optionally a focus prompt such as "focus on the landing itself" and a specific Google account. <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px;align-items:flex-start"> <figure style="flex:1 1 280px;max-width:400px;margin:0"> <a href="https://media.useapi.net/articles/2026-10-04-notebooklm-n8n-podcast/notebooklm-n8n-app-01-form.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-04-notebooklm-n8n-podcast/notebooklm-n8n-app-01-form.png" alt="The Make a NotebookLM podcast form with title, links, format, length, language and focus fields" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">The form</figcaption> </figure> <figure style="flex:1 1 280px;max-width:400px;margin:0"> <a href="https://media.useapi.net/articles/2026-10-04-notebooklm-n8n-podcast/notebooklm-n8n-app-03-sources.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-04-notebooklm-n8n-podcast/notebooklm-n8n-app-03-sources.png" alt="The sources page: one page read, one unreachable link skipped with the reason" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">What Google read, and what it skipped</figcaption> </figure> </div> While Google reads the links, the page shows what is happening and a running clock. The next page lists what Google read, with titles and word counts, and anything it could not read along with the reason. A link that needs a login or no longer exists is skipped, and the rest still go in. Then you start the podcast, which takes about 3 to 10 minutes, and the result page plays it in the browser. <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px;align-items:flex-start"> <figure style="flex:1 1 320px;max-width:520px;margin:0"> <a href="https://media.useapi.net/articles/2026-10-04-notebooklm-n8n-podcast/notebooklm-n8n-app-04-result-player.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-10-04-notebooklm-n8n-podcast/notebooklm-n8n-app-04-result-player.png" alt="The result page with an audio player, a download link and a make another podcast link" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">The finished episode plays in the browser</figcaption> </figure> </div> The long steps show a link to come back to, so you can close the tab and return later. The episode also stays in a notebook in your Google account, where you can share it or chat with the sources. The weekly schedule is off until you switch it on. It reads the feed in Feed settings, keeps the posts published in the last `lookbackDays` days (7 by default), newest first and at most `maxPosts` (5), and makes one episode named `<showName>, <date>`. A week with no new posts makes no episode. It ends at the Episode node with the `.m4a` as binary data, ready for a Google Drive, S3, Telegram or podcast-host node. Under the hood, both paths create a notebook with [POST /notebooks](/docs/api-gemini-notebook-v1/post-gemini-notebook-notebooks), add the links with [POST /sources](/docs/api-gemini-notebook-v1/post-gemini-notebook-sources), wait until Google has read them, start the Audio Overview with [POST /artifacts](/docs/api-gemini-notebook-v1/post-gemini-notebook-artifacts) and poll [GET /jobs](/docs/api-gemini-notebook-v1/get-gemini-notebook-jobs-jobid). ### Set it up 1. Get a useapi.net [API token](/docs/start-here/setup-useapi) and connect your Google account with the [Gemini Notebook setup](/docs/start-here/setup-gemini-notebook). 2. Import [`notebooklm-podcast-app.json`](https://github.com/useapi/notebooklm-api/blob/main/n8n/notebooklm-podcast-app.json) in n8n with Workflows → Import from File{% include n8n-listed.html t="notebook-podcast" %}. 3. Create a Header Auth credential, for example called `useapi.net API token`, with Name `Authorization` and Value `Bearer <your API token>`. 4. Select that credential on the eight HTTP Request nodes: Create notebook, Add sources, Add each link, Read notebook, Generate Audio Overview, Check job, Download podcast and Fetch audio. 5. Publish (activate) the workflow and open the form URL. For the weekly episode, put your feed in Feed settings and switch on the schedule. The Podcast audio webhook streams the finished episode to the result page using that credential, so your token never reaches the browser. ### When something goes wrong The form shows a page that says what to do: - A token that is wrong or missing asks you to check the credential. - An account that is out of Gemini Notebook usage shows when it resets, when Google says. To make more episodes, connect more Google accounts through the [Gemini Notebook setup](/docs/start-here/setup-gemini-notebook) and leave the account field empty, so new notebooks go to the least busy account. - An account that needs reconnecting links to the setup page. - If every link is unreachable, the page lists each one with the reason. - A podcast Google could not make shows Google's reason. Temporary errors are retried, and the generate step is never sent twice. On the weekly path the same problems stop the run with the same message. ### What it costs A flat [$15/month](/docs/subscription) for useapi.net, which covers every useapi.net API. There is no charge per episode. Gemini Notebook's usage limits come from your Google plan, and each subscription lets you connect 3 Google accounts, up to 100 in total, to make more. See [Run several Gemini Notebook accounts](/docs/api-gemini-notebook-v1#run-several-gemini-notebook-accounts). ### More ways to use the Gemini Notebook API (NotebookLM API) - [A real example](/docs/articles/notebooklm-podcast-example): one podcast, a video overview and an infographic from the same two sources. - [The full tutorial](/docs/articles/gemini-notebook-bash): every Studio output, chat with citations and Deep Research, with `curl`. - [GitHub examples](https://github.com/useapi/notebooklm-api): Node.js, Python, a Colab notebook and an agent skill for Claude Code and Codex. ### Frequently asked questions **Does Gemini Notebook (NotebookLM) have an API?** Yes, through useapi.net: the [useapi.net Gemini Notebook API](/docs/api-gemini-notebook-v1) drives your own Google account, free or paid, and covers every Studio output. Google offers a Gemini Notebook Enterprise API only to Google Cloud customers with Enterprise licenses, and of the Studio outputs it makes Audio Overviews only. **Do I need n8n Cloud?** No. The workflows use only core nodes. They were tested on self-hosted n8n and need nothing Cloud-only. ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. #### Cross posted Also published on [dev.to](https://dev.to/useapi/how-to-turn-web-pages-youtube-videos-and-rss-feeds-into-notebooklm-podcasts-with-n8n-1m0g){:rel="nofollow"} and shared on [Bluesky](https://bsky.app/profile/useapi.net/post/3mx4a2l72wb2i){:rel="nofollow"}. === URL: https://useapi.net/docs/articles/notebooklm-podcast-example === Document URL: https://useapi.net/docs/articles/notebooklm-podcast-example --- layout: default title: "Turn a Web Page or YouTube Video into a Podcast with Gemini Notebook (NotebookLM): A Real Example" description: "A real Gemini Notebook (NotebookLM) podcast made from a Wikipedia page and a YouTube video through the useapi.net Gemini Notebook API, plus how to make your own with n8n or a few API calls." keywords: [NotebookLM podcast, web page to podcast, YouTube to podcast, NotebookLM Audio Overview, NotebookLM API, AI podcast generator, NotebookLM n8n, Gemini Notebook] image: https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-infographic-sketch-note-apollo11-0929.png video: name: "NotebookLM has no API. Now it does: podcasts, video, slides from one REST call" description: "Real output from one Apollo 11 notebook, made through the useapi.net Gemini Notebook (NotebookLM) API: the Video Overview, the slide deck (and a slide revised by prompt), the infographic and the Audio Overview." embed: https://www.youtube.com/embed/ISOQAabo0b0 thumbnail: https://i.ytimg.com/vi/ISOQAabo0b0/hqdefault.jpg date: 2026-09-30 duration: PT20S width: 1080 height: 1920 parent: Articles nav_exclude: true date: 2026-10-04 nav_order: 890 repo: https://github.com/useapi/notebooklm-api --- ## Turn a Web Page or YouTube Video into a Podcast with Gemini Notebook (NotebookLM): A Real Example October 4, 2026 A Wikipedia page, a NASA video on YouTube and a few related sources went in, and Gemini Notebook made the podcast below on its own. Nobody opened the Gemini Notebook website. The [useapi.net Gemini Notebook API (NotebookLM API)](/docs/api-gemini-notebook-v1) sent the sources and collected the audio, running on our own Google account. It's a Google AI Pro plan, and the free plan works too, with lower limits. Google has renamed NotebookLM to Gemini Notebook, so you'll see both names. ### The podcast <audio controls class="audio-player" style="width:100%"><source src="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-audio-overview-brief-apollo11-0929.m4a" type="audio/mp4"></audio> "Fifty Seconds of Fuel and Lunar Isolation", an Audio Overview in the brief format and short length, 1 min 31 s, made in 4 min 36 s The notebook was built around two main sources, the [Apollo 11 article on Wikipedia](https://en.wikipedia.org/wiki/Apollo_11) and the NASA Goddard video [A New Look at the Apollo 11 Landing Site](https://www.youtube.com/watch?v=xUcYQ7slmRw), plus a pasted paragraph, a PDF copy of the article and web pages found with Discover sources. The [full tutorial](/docs/articles/gemini-notebook-bash#sources-and-prompts) lists every input. ### The same notebook, as a video and an infographic <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px;align-items:flex-start"> <figure style="flex:1 1 320px;max-width:480px;margin:0"> <video poster="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-video-explainer-whiteboard-apollo11-first90s-0929-poster.jpg" controls width="100%" style="border-radius:8px" src="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-video-explainer-whiteboard-apollo11-first90s-0929.mp4"></video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em"><strong>Video Overview</strong>, whiteboard style, the first 90 seconds of 11 min 50 s</figcaption> </figure> <figure style="flex:1 1 220px;max-width:300px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-infographic-sketch-note-apollo11-0929.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-29-gemini-notebook-bash/gemini-notebook-tutorial-pro-infographic-sketch-note-apollo11-0929.png" alt="Gemini Notebook infographic about the Apollo 11 landing, sketch-note style" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em"><strong>Infographic</strong>, sketch-note style, made in 1 min 45 s</figcaption> </figure> </div> All of it in 20 seconds: <div style="max-width:320px"> <div style="position:relative;width:100%;padding-top:177.78%;border-radius:8px;overflow:hidden"> <iframe src="https://www.youtube.com/embed/ISOQAabo0b0" title="Gemini Notebook (NotebookLM) outputs made through the useapi.net API" style="position:absolute;top:0;left:0;width:100%;height:100%;border:0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen loading="lazy"></iframe> </div> </div> ### Make your own Pick the path that fits you. Both run on your own Google account, including a free one. Without code, [import the free n8n podcast app](/docs/articles/notebooklm-n8n-podcast) into n8n Cloud or your own n8n. Paste a few links and play the podcast in your browser, or point it at a blog's RSS feed so every new post becomes an episode. As a developer, follow the [step-by-step tutorial](/docs/articles/gemini-notebook-bash) that makes everything on this page with `curl`, or start from the [GitHub examples](https://github.com/useapi/notebooklm-api) in Node.js, Python and a Colab notebook. ### What it costs A flat [$15/month](/docs/subscription) for useapi.net, an independent service not made by Google, which covers every useapi.net API. There is no charge per podcast. How many you can make depends on your Google plan's Gemini Notebook limits, and you can connect several Google accounts to make more. See [Run several Gemini Notebook accounts](/docs/api-gemini-notebook-v1#run-several-gemini-notebook-accounts). ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/omni-flash-bash-es === Document URL: https://useapi.net/docs/articles/omni-flash-bash-es --- layout: default title: "Cómo generar video con IA y audio nativo con Gemini Omni Flash mediante la Google Flow API" seo_title: "API de Gemini Omni Flash con curl: voces, personajes y V2V" description: "Gemini Omni Flash en la Google Flow API de useapi.net, con código: imágenes de referencia, personajes, voces y ediciones V2V en Omni 1.2 y 1.1, más un script por lotes." keywords: [Gemini Omni Flash, Omni 1.2 Flash, Omni 1.1 Flash, Omni Flash API, API de Omni Flash, API de Gemini Omni Flash, omni-flash-1.2, omni-flash, Google Flow API, API de Google Flow, video con audio nativo, video con IA con voces, extender video, voces, personajes, edición de video, video a video, referencia a video, tutorial, código, curl] parent: Articles nav_exclude: true lang: es translation_key: omni-flash date: 2026-06-15 last_modified: 2026-11-12 nav_order: 830 repo: https://github.com/useapi/google-flow-api --- ## Cómo generar video con IA y audio nativo con Gemini Omni Flash mediante la Google Flow API {: .no_toc #how-to-generate-audio-native-ai-video-with-gemini-omni-flash-via-the-google-flow-api } 8 min de lectura • 15 de junio de 2026 (12 de noviembre de 2026) useapi.net es una API de terceros. No está afiliada a Google ni cuenta con su respaldo. ## Índice {: .no_toc .text-delta #table-of-contents } ### Introducción [Gemini Omni Flash](https://deepmind.google/models/model-cards/gemini-omni-flash/) genera video con IA y audio nativo con un solo `curl` a través de la [Google Flow API](/docs/api-google-flow-v1) de useapi.net, con voces sincronizadas, personajes y ediciones de video a video, con tu suscripción al sitio web de [Google Flow](https://flow.google.com) ([Google AI](https://gemini.google/subscriptions/): Omni 1.1 Flash en Plus, Pro o Ultra, Omni 1.2 Flash en todos los planes, y en cuentas gratuitas hasta 10 segundos). Un video de 10 segundos en 720p cuesta US$0,12 en Google AI Ultra US$199,99, frente a US$1,01 en la [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) oficial (a noviembre de 2026), sin proyecto de Google Cloud y sin clave de API. La misma suscripción también genera videos Omni en [Google Vids](/docs/api-google-vids-v1), sin gastar créditos de Flow. En la interfaz, Google Flow llama a este modelo Omni 1.1 Flash, y el valor en la API es `model: "omni-flash"`. Omni 1.2 Flash, que Google lanzó el 5 de noviembre de 2026, es otro valor, `model: "omni-flash-1.2"`: cualquier duración de 3 a 15 segundos, créditos por segundo, y es el modelo que [extiende un video](#extend-a-video-with-omni-12) hasta 10 segundos cada vez. El código que envía `omni-flash` sigue recibiendo el 1.1. Para videos de 15 segundos, extensiones con voces y el precio por video en Google Flow y Google Vids, consulta [Cómo usar la API de Gemini Omni 1.2 Flash](/docs/articles/gemini-omni-1-2-flash-api-es). Omni Flash es la [misma Google Flow API](/docs/api-google-flow-v1) que Veo, elegido con un solo campo (`model: "omni-flash-1.2"` o `model: "omni-flash"`), pero es otro tipo de modelo. Veo es un motor sólido de texto a video sencillo, y Omni Flash tiene audio nativo y acepta muchas referencias: - El sonido se genera junto con el video: la narración, el diálogo y el ambiente salen del mismo modelo, no se agregan después. - Voces: 30 voces predefinidas del sistema, más voces personalizadas que creas con tu propio diálogo y notas de interpretación, pasadas en `referenceAudio_1..5`. - Referencias de imagen y de video: hasta 10 imágenes de referencia en Omni 1.2 Flash (7 en Omni 1.1 Flash) para referencia a video (R2V), y edición de video a video (V2V) de un video subido o generado con `referenceVideo_1`. - Personajes reutilizables: junta imágenes de referencia y una voz en un personaje con nombre y úsalo en varios videos. - Videos más largos: Omni 1.1 Flash genera 4, 6, 8 o 10 segundos y Omni 1.2 Flash cualquier duración de 3 a 15 (Veo se detiene en `8`), y Omni 1.2 extiende un video en pasos de hasta 10 segundos. Esta guía muestra el flujo de dos llamadas con `curl` para copiar y pegar, los modos de referencia que hacen distinto a Omni Flash y, después, un script de Node.js listo para ejecutar que genera por lotes a partir de una lista de prompts. Para texto a video sencillo, consulta el [tutorial de Veo 3.1](/docs/articles/google-flow-bash-es) hermano de este. ### Modelo compatible Esta guía usa los modelos de video con audio nativo de Google, Omni 1.1 Flash (`model: "omni-flash"`) y Omni 1.2 Flash (`model: "omni-flash-1.2"`). En Omni 1.1, el costo en créditos crece con la duración del video: | Duración | Créditos por video | |----------|------------------------| | 4s | 7 | | 6s | 10 | | 8s | 12 | | 10s | 15 | | Edición V2V | 20 | Esos son los costos en el `720p` predeterminado. Pasar `resolution: "360p"` cuesta más o menos la mitad (4 / 5 / 6 / 7 créditos según la duración, 10 por una edición V2V), y un video en 360p se puede llevar a 720p después con [POST /videos/upscale](/docs/api-google-flow-v1/post-google-flow-videos-upscale). Omni 1.2 Flash (`model: "omni-flash-1.2"`) acepta cualquier número entero de segundos de 3 a 15 y cobra por segundo, igual en todos los planes: | Duración | 720p | 360p | |--------|------|------| | 3s | 9 | 3 | | 8s | 24 | 8 | | 10s | 30 | 10 | | 15s | 60 | 20 | Hasta 10 segundos son 3 créditos por segundo en 720p y 1 en 360p, y cada segundo por encima de 10 cuesta el doble. Una edición V2V cuesta lo mismo que un video con la duración editada, y el 1.2 edita hasta 15 segundos de un clip. Las cuentas de Google gratuitas pueden usar el 1.2 para videos de hasta 10 segundos. Omni Flash acepta cinco modos en [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos): texto a video sencillo (T2V), referencia a video (R2V) con hasta 10 `referenceImage_1..10` en Omni 1.2 Flash (7 en Omni 1.1 Flash), imagen a video a partir de un fotograma inicial con `startImage` (I2V), imagen a video entre un fotograma inicial y uno final con `startImage` + `endImage` (I2V-FL), y edición de video a video (V2V) de un MP4 subido con `referenceVideo_1`. Consulta [Modos de referencia](#reference-modes) más abajo. ### Precios Omni 1.1 Flash requiere una suscripción de pago a Google AI (Plus, Pro o Ultra), Omni 1.2 Flash funciona en cuentas gratuitas hasta 10 segundos, y useapi.net no cobra nada por video. Cada video gasta créditos de Flow según la duración (consulta [Modelo compatible](#supported-model)). El precio por video en cada plan, frente a la Gemini API oficial, está en la [tabla de precios de Google Flow](/docs/api-google-flow-v1#pricing). Un plan de Google AI también incluye una cuota mensual en [Google Vids](https://docs.google.com/videos), que genera videos de hasta 15 segundos con Gemini Omni 1.2 Flash ([anuncio de Google](https://workspaceupdates.googleblog.com/2026/11/gemini-omni-12-flash-now-in-vids-with-15second-generations-and-improved-quality.html)) y no usa créditos de Flow. En Ultra US$199,99 (que Google llama Ultra 20x) son 10.000 segundos de video al mes, unos 1.000 clips de 10 segundos en 1080p más, además de los ~1.666 clips de diez segundos de Omni 1.1 Flash (o ~833 clips de Omni 1.2 Flash en 720p) que compran los 25.000 créditos de Flow. Esos segundos se comparten entre todos los miembros de un plan familiar de Google. Los demás planes reciben menos (consulta la página [Gemini en Google Vids](https://support.google.com/docs/answer/15609411?hl=es) de Google), y las cuentas gratuitas que probamos no tenían nada. La [Google Vids API](/docs/api-google-vids-v1) usa esa cuota sin captcha. Conecta la cuenta con [Setup Google Vids](/docs/start-here/setup-google-vids). ### Genera un video con dos llamadas a la API Necesitas un [token de la API](/docs/start-here/setup-useapi) de useapi.net y una [cuenta de Google Flow](/docs/start-here/setup-google-flow) conectada, con una suscripción de pago a Google AI (Plus, Pro o Ultra) para el ejemplo con Omni 1.1 Flash de abajo (Omni 1.2 Flash también funciona en una cuenta gratuita, hasta 10 segundos). Los jobs de video son asíncronos: pasa `async: true` y la llamada de creación devuelve un `jobid` al instante, después consultas hasta que el video esté listo. 1. Envía el job: `POST https://api.useapi.net/v1/google-flow/videos` con `model: "omni-flash"`: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A lighthouse keeper narrates the coming storm, waves crashing below", "model": "omni-flash", "aspectRatio": "landscape", "duration": 10, "async": true }' ``` Como Omni Flash tiene audio nativo, genera la banda sonora (la narración del farero y las olas que rompen) directamente del prompt, sin ningún parámetro de audio. En modo asíncrono, la respuesta vuelve al instante con `201 Created`, un `jobid` en minúsculas y `status: "created"`: ```json { "jobid": "j1731859234567v-u12345-email:jo***@gmail.com-bot:google-flow", "type": "video", "status": "created", "created": "2026-06-15T12:34:56.789Z", "request": { "async": true, "prompt": "A lighthouse keeper narrates the coming storm, waves crashing below", "model": "omni-flash", "aspectRatio": "landscape", "duration": 10 } } ``` 2. Consulta el resultado: `GET https://api.useapi.net/v1/google-flow/jobs/{jobId}`: ```bash curl "https://api.useapi.net/v1/google-flow/jobs/JOBID" \ -H "Authorization: Bearer $USEAPI_TOKEN" ``` El `status` pasa por `created` → `started` → `completed`. Cuando llega a `completed`, el MP4 terminado está en `response.media[].videoUrl` (un solo prompt con `count > 1` devuelve una entrada por video): ```json { "jobid": "j1731859234567v-...", "type": "video", "status": "completed", "response": { "media": [ { "mediaGenerationId": "user:12345-email:6a6f...-video:a1d95d21-...", "videoUrl": "https://flow-content.google/video/a1d95d21-...?Expires=...", "thumbnailUrl": "https://flow-content.google/image/a1d95d21-...?Expires=..." } ], "remainingCredits": 18760 } } ``` Omni Flash suele terminar en 60 a 180 segundos. El `videoUrl` firmado es válido durante unas 6 horas, así que descárgalo pronto. ¿Prefieres no consultar? Pasa un `replyUrl` en el cuerpo de la creación para recibir un webhook cuando el job termine. ### Modos de referencia La gran diferencia de Omni Flash es cuánto puedes pasarle como referencia. Todas las referencias vienen del endpoint de subida [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email) (o, en el caso de los personajes, de [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters)). La respuesta de la subida trae el id de referencia anidado en `mediaGenerationId.mediaGenerationId`, y es esa cadena anidada la que pasas de vuelta. Los modos que acepta `omni-flash` (de la documentación de [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos#references)): | Modo | Parámetro(s) | Límite en Omni Flash | |------|--------------|------------------| | Referencia a video (R2V) | `referenceImage_1..10` | hasta 10 imágenes en `omni-flash-1.2`, 7 en `omni-flash` | | Imagen a video (I2V) | `startImage` | un fotograma inicial | | Imagen a video, inicial + final (I2V-FL) | `startImage` + `endImage` | solo los dos fotogramas, sin otras referencias | | Edición de video a video (V2V) | `referenceVideo_1` (+ `startFrameIndex_1` / `endFrameIndex_1` opcionales) | un MP4 subido | | Personajes | `character_1..10` (de [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters)) | 10 en total con `referenceImage_*` en `omni-flash-1.2`, 7 en `omni-flash` | | Narración con voz | `referenceAudio_1..5` | hasta 5 (R2V) / hasta 3 (edición V2V) | Referencia a video (R2V): sube una o más imágenes y pásalas como `referenceImage_1`, `referenceImage_2`, … (los espacios `_4`..`_7` son solo de Omni Flash). Las imágenes de referencia no se pueden combinar con `startImage`/`endImage`. ```bash # 1. Upload a reference image — the id is nested one level deep: curl -X POST "https://api.useapi.net/v1/google-flow/assets/john%40gmail.com" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: image/jpeg" \ --data-binary @subject.jpeg # Response: { "mediaGenerationId": { "mediaGenerationId": "user:12345-email:...-image:..." }, ... } # 2. Generate, narrated by a system voice curl -X POST "https://api.useapi.net/v1/google-flow/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model": "omni-flash", "prompt": "the subject walks toward camera and introduces herself", "duration": 8, "referenceImage_1": "user:12345-email:...-image:...", "referenceAudio_1": "Kore" }' ``` Edición de video a video (V2V): sube un MP4 con `Content-Type: video/mp4` a [POST /assets](/docs/api-google-flow-v1/post-google-flow-assets-email) y pasa el id devuelto como `referenceVideo_1` para editar ese video. Esto es solo de Omni Flash y pone la solicitud en modo V2V. `duration` no se acepta (la duración de salida sigue la ventana de recorte de la entrada, como máximo 10 s en `omni-flash` y 15 s en `omni-flash-1.2`). Si quieres, recorta el origen en una línea de tiempo virtual de 24 fps con `startFrameIndex_1` (0–239) y `endFrameIndex_1` (1–240, donde 240 = 10 s), o hasta 359 y 360 (15 s) en `omni-flash-1.2`: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model": "omni-flash", "prompt": "restyle the scene as a rainy neon-lit night, add ambient city sound", "referenceVideo_1": "user:12345-email:...-video:...", "startFrameIndex_1": 0, "endFrameIndex_1": 240, "async": true }' ``` También puedes poner marcadores `@` en línea dentro del prompt que apuntan a los espacios que pasas, por ejemplo `@referenceImage_1`, `@character_1`, `@referenceAudio_1`. Los marcadores son opcionales y cada uno necesita un parámetro correspondiente en el cuerpo. (`@referenceVideo_*` no funciona en línea: pásalo como campo del cuerpo.) Consulta [Inline @-mention markers](/docs/api-google-flow-v1/post-google-flow-videos#inline--mention-markers-optional). ### Voces y personajes Dos llamadas cortas de configuración alimentan las funciones de audio e identidad de Omni Flash. Voces personalizadas: [POST /voices](/docs/api-google-flow-v1/post-google-flow-voices) guarda una voz basada en una de las 30 voces predefinidas del sistema, con tu propio `dialog` y `voicePerformance`. El campo `voice` de la respuesta es un id de referencia que después pasas como `referenceAudio_1..5` en [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos): ```bash curl -X POST "https://api.useapi.net/v1/google-flow/voices" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "john@gmail.com", "voice": "Achernar", "dialog": "Welcome to the demo.", "voicePerformance": "Cheerful, energetic delivery", "displayName": "Cheerful Narrator" }' # Response: { "voice": "user:12345-email:...-voice:...-mid:...", ... } ``` Cada espacio `referenceAudio_*` acepta el nombre de una voz del sistema (sin distinguir mayúsculas, una de las 30 predefinidas, como `Aoede`, `Kore`, `Puck`, `Zephyr`) o el id de una voz de usuario de la llamada anterior. Crear una voz requiere reCAPTCHA (se resuelve automáticamente, consulta [las preguntas frecuentes](#frequently-asked-questions)). Personajes reutilizables: [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters) junta 1 o 2 imágenes de referencia y una voz opcional en un personaje con nombre. El campo `character` de la respuesta es lo que pasas como `character_1..10`: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/characters" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "displayName": "Carol", "imageReference_1": "user:12345-email:...-image:abc123...", "voice": "user:12345-email:...-voice:...-mid:..." }' # Response: { "character": "user:12345-email:...-character:...-imgs:1-voice:...", ... } ``` En Omni Flash, los personajes funcionan en todas las duraciones y comparten el límite total de 10 imágenes de referencia con `referenceImage_*` (`referenceImages.length + Σ(character.imgs) ≤ 10`, Omni 1.1: 7). `POST /characters` no requiere captcha. Los personajes y las voces también funcionan en Veo, pero con límites más estrictos (3 imágenes, 1 voz, solo 8 s): consulta [What can use a character?](/docs/api-google-flow-v1/post-google-flow-characters#what-can-use-a-character). ### Extiende un video con Omni 1.2 [POST /videos/extend](/docs/api-google-flow-v1/post-google-flow-videos-extend) agrega de 3 a 10 segundos cada vez con Omni 1.2 Flash a cualquier video de menos de 30 segundos, con hasta 3 voces, imágenes de referencia o personajes, y devuelve un solo clip continuo (solo en planes de pago). El recorrido de [Cómo usar la API de Gemini Omni 1.2 Flash](/docs/articles/gemini-omni-1-2-flash-api-es#flow-walkthrough) extiende un video de 10 segundos dos veces hasta 30 segundos, con dos voces: es el [ejemplo de abajo](#examples). ### Genera por lotes con un script Encontrar la toma correcta lleva muchos intentos, y hacerlo todo a mano cansa. El script de Node.js de abajo lee una lista de prompts de `prompts.json`, sube las imágenes de referencia, los fotogramas inicial y final o los videos de origen, pasa tal cual los ids `character_*` y la `resolution`, envía cada job en modo asíncrono con `model: "omni-flash"` y después consulta y descarga cada MP4 terminado. Así pones un lote en cola y vuelves más tarde a elegir los mejores. Se detiene con un aviso antes de enviar una combinación que la API rechazaría, como un fotograma final sin fotograma inicial. Necesitas [Node.js](https://nodejs.org) v21 o posterior. Pon `prompts.json` y `omni-flash.mjs` en la misma carpeta y ejecuta `node ./omni-flash.mjs API_TOKEN EMAIL`, donde `API_TOKEN` es tu [token de la API](/docs/start-here/setup-useapi) de useapi.net y `EMAIL` es el correo de tu [cuenta de Google Flow](/docs/start-here/setup-google-flow) conectada. El script encuentra la cuenta por el correo automáticamente y revisa su campo `health` antes de enviar. ¿Prefieres clonarlo y ejecutarlo en tu equipo? Los archivos completos `omni-flash.mjs` y `prompts.json` están en GitHub, en [`useapi/google-flow-api`](https://github.com/useapi/google-flow-api/tree/main/omni-flash). ¿Trabajas en Claude Code o Codex? La [agent skill omni-flash-video](https://github.com/useapi/google-flow-api/tree/main/skills/omni-flash-video) deja que el agente haga todo esto por ti: describe el video, señala tus imágenes, y el agente las sube, escribe la solicitud, espera y guarda el `.mp4`. Instálala con `npx skills add useapi/google-flow-api --skill omni-flash-video`. <details markdown="block"> <summary>Abrir `prompts.json`</summary> ```json [ { "prompt": "Audio-native text-to-video. By default model omni-flash with a landscape 8-second clip will be used." }, { "duration": 10, "prompt": "A 10-second clip (omni-flash only). Omni Flash is audio-native, so narration, dialogue and sound come from the prompt. To pin a specific voice, add referenceAudio_1 together with a referenceImage_* or character_*, as in the next prompt." }, { "duration": 8, "referenceImage_1": "./subject.jpeg", "referenceAudio_1": "Kore", "prompt": "Reference-to-video (R2V): the uploaded image is a reference, narrated by 'Kore'. Up to 7 referenceImage_* on omni-flash, 10 on omni-flash-1.2." }, { "duration": 8, "startImage": "./first_image.jpeg", "endImage": "./last_image.jpeg", "prompt": "Image-to-video with a start frame (startImage) and an end frame (endImage). The two frames are the only input — no referenceImage_*, character_* or referenceAudio_* alongside them." }, { "referenceVideo_1": "./source.mp4", "startFrameIndex_1": 0, "endFrameIndex_1": 240, "prompt": "Video-to-video edit (V2V): omni-flash restyles the uploaded MP4. No duration here — output matches the trim window (max 10 s). For all parameters see https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos" } ] ``` </details> <details markdown="block"> <summary>Abrir el script `omni-flash.mjs`</summary> ```javascript /* Script version 1.3, November 11, 2026 Script to batch-generate audio-native videos with Gemini Omni Flash using the Google Flow API by useapi.net Uses the POST /videos endpoint in async mode (model: omni-flash by default, or omni-flash-1.2 per prompt) and polls GET /jobs/{jobId}. For more details visit https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos Installation Instructions: ========================== You need Node.js v21 or newer installed to run this script. Download and install Node.js from: - Windows, macOS, Linux: https://nodejs.org/ After installation, verify by running the following command in a terminal: node -v Running the Script: =================== Usage: node omni-flash.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE] Replace API_TOKEN with your actual useapi.net API token, see https://useapi.net/docs/start-here/setup-useapi Replace EMAIL with configured Google Flow email account, see https://useapi.net/docs/start-here/setup-google-flow If optional PROMPTS_FILE not provided prompts.json will be used. Example: -------- node omni-flash.mjs user:1234-abcdefhijklmnopqrstuv my@email.com This command executes the script using API token user:1234-abcdefhijklmnopqrstuv with my@email.com Google Flow account email. Changelog: ========== - June 15, 2026: Initial release. - September 11, 2026: Adds resolution, startImage / endImage (start and end frames, local files uploaded for you) and character_1..7. Accepts .jpg and upper-case file extensions. Stops with a warning before submitting combinations the API rejects, such as endImage without startImage or referenceAudio_* on its own. A prompt whose local startImage, endImage, referenceImage_* or referenceVideo_1 file fails to upload is skipped and logged to omni-flash_errors.txt instead of being submitted without it. Saves a downloaded video under its final name only once it has been fully received, so a failed download leaves no partial MP4 for the next run to skip as "already exists". - November 11, 2026: referenceImage_8..10 and character_8..10: omni-flash-1.2 takes up to 10 references (omni-flash 7). */ import readline from 'node:readline'; import fs from 'fs/promises'; import path from 'path'; import { writeFile } from 'node:fs/promises'; import { Readable } from 'node:stream'; // Constants const RESULTS_FILE = 'omni-flash_results.txt'; const ERRORS_FILE = 'omni-flash_errors.txt'; const DEFAULT_PROMPTS_FILE = 'prompts.json'; const MODEL = 'omni-flash'; // Reference slots: up to 10 on omni-flash-1.2, 7 on omni-flash, 3 on Veo (referenceImage_* and character_* together). const imageRefKeys = Array.from({ length: 10 }, (_, i) => `referenceImage_${i + 1}`); const characterKeys = Array.from({ length: 10 }, (_, i) => `character_${i + 1}`); const SLEEP_429 = 30 * 1000; // in milliseconds const SLEEP_POLL = 15 * 1000; // in milliseconds const urlAccounts = 'https://api.useapi.net/v1/google-flow/accounts'; const urlVideos = 'https://api.useapi.net/v1/google-flow/videos'; const urlJobs = 'https://api.useapi.net/v1/google-flow/jobs/'; const urlUploadAsset = 'https://api.useapi.net/v1/google-flow/assets/'; // Google Flow accepts png, jpeg and webp images, and mp4 video (for omni-flash V2V edit). const supportedImageExtensions = ['png', 'jpg', 'jpeg', 'webp']; const supportedVideoExtensions = ['mp4']; // { filename: mediaGenerationId } const uploadedFiles = {}; // Utility to sleep for given milliseconds const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); // Function to fetch configured Google Flow API accounts async function fetchAccounts(apiToken) { const response = await fetch(urlAccounts, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.error(`⛔ Error fetching accounts (HTTP ${response.status}): ${response.statusText}`); process.exit(1); } return response.json(); } const elapsedTimeSec = (start) => (Date.now() - start) / 1000; // Map a file extension to the Content-Type required by POST /assets const contentTypeForExt = (ext) => ext === 'png' ? 'image/png' : ext === 'webp' ? 'image/webp' : ext === 'mp4' ? 'video/mp4' : 'image/jpeg'; async function uploadAsset(apiToken, email, filename) { // Check if already uploaded if (uploadedFiles.hasOwnProperty(filename)) return uploadedFiles[filename]; const startTime = Date.now(); console.log(`⬆️ Account ${email} uploading file…`, filename); const body = new Blob([await fs.readFile(filename)]); const fileExt = filename.split('.').pop().toLowerCase(); const response = await fetch(`${urlUploadAsset}${encodeURIComponent(email)}`, { method: 'POST', headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}`, 'Content-Type': contentTypeForExt(fileExt) }, body }); if (response.ok) { const json = await response.json(); // POST /assets returns the reference id nested as mediaGenerationId.mediaGenerationId const mediaGenerationId = json?.mediaGenerationId?.mediaGenerationId; console.log(`🆗 mediaGenerationId (${elapsedTimeSec(startTime)} sec)`, mediaGenerationId); uploadedFiles[filename] = mediaGenerationId; } else { console.error(`❗ Unable to upload file HTTP ${response.status} (${elapsedTimeSec(startTime)} sec)`, await response.text()); // Do not attempt to upload failed file again uploadedFiles[filename] = undefined; } return uploadedFiles[filename]; } async function submit(apiToken, url, body, index, prompt) { const createResponse = await fetch(url, { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiToken}` }, body }); const createBody = await createResponse.text(); // Async POST /videos returns 201 Created with a jobid to poll. if (createResponse.status == 201) { const json = JSON.parse(createBody); // 201 async payload uses lowercase "jobid"; sync 200 uses "jobId". Accept either. const jobId = json.jobid ?? json.jobId; if (jobId) { await fs.appendFile(RESULTS_FILE, `${jobId},#${index}:${prompt}\n`); console.log(`✅ jobId`, jobId); return 201; } else { const error = `No jobid found in HTTP 201 response`; console.log(`❓ ${error}`, createBody); await fs.appendFile(ERRORS_FILE, `${error},#${index}:${prompt}\n`); return 500; } } else { switch (createResponse.status) { case 429: console.log(`🔄️ Retry on HTTP ${createResponse.status}`, createBody); break; case 503: console.log(`🔄️ Service unavailable, retry on HTTP ${createResponse.status}`, createBody); break; case 400: console.log(`🛑 Rejected request (validation or content policy)`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${prompt}\n`); break; case 402: console.log(`🛑 No subscription / insufficient credits`, createBody); break; default: console.log(`❗ FAILED with HTTP ${createResponse.status}`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${prompt}\n`); } return createResponse.status; } } // Submit a single prompt to POST /videos with model omni-flash (or the prompt's own model) in async mode. // startImage = start frame (I2V), endImage = end frame (I2V-FL, requires startImage) — the frames are the only input; // referenceImage_1..10 = R2V image refs; character_1..10 = POST /characters ids (10 on omni-flash-1.2, 7 on omni-flash); // referenceVideo_1 = V2V edit (no duration); referenceAudio_1..5 = system voice name or POST /voices user-voice id; // resolution = 720p (default) or 360p; model = 'omni-flash' (Omni 1.1, the default) or 'omni-flash-1.2' (3–15 s, per-second credits). async function submitVideo(apiToken, email, prompt, index) { const { prompt: text, model = MODEL, aspectRatio, duration, resolution, count, startImage, endImage, referenceVideo_1, startFrameIndex_1, endFrameIndex_1, referenceAudio_1, referenceAudio_2, referenceAudio_3, referenceAudio_4, referenceAudio_5 } = prompt; console.log(`🚀 ${model} » Prompt #${index} • account ${email} …`); // Upload any local image/video files and swap the paths for their mediaGenerationId. const resolveRef = async (ref) => ref && (ref.startsWith('./') || ref.includes('.')) && [...supportedImageExtensions, ...supportedVideoExtensions].includes(ref.split('.').pop().toLowerCase()) ? await uploadAsset(apiToken, email, ref) : ref; const startImageId = await resolveRef(startImage); const endImageId = await resolveRef(endImage); const refImages = {}; for (const key of imageRefKeys) refImages[key] = await resolveRef(prompt[key]); const refVideo_1 = await resolveRef(referenceVideo_1); // A local file that failed to upload would be left out of the body, and the prompt would still be // generated (and charged) without it. Skip the prompt instead. uploadAsset remembers the failed file, // so a later prompt using it is skipped too, without another upload attempt. const failedUploads = [ ['startImage', startImage, startImageId], ['endImage', endImage, endImageId], ...imageRefKeys.map(key => [key, prompt[key], refImages[key]]), ['referenceVideo_1', referenceVideo_1, refVideo_1] ].filter(([, file, id]) => file && !id); for (const [param, file] of failedUploads) { console.error(`🛑 Prompt #${index} skipped: ${param} ${file} failed to upload`); await fs.appendFile(ERRORS_FILE, `Upload failed for ${param} ${file},#${index}:${text}\n`); } if (failedUploads.length) return; // V2V edit does not accept duration — output matches the trim window. const isV2V = !!refVideo_1; const body = JSON.stringify({ model, email, prompt: text, aspectRatio, duration: isV2V ? undefined : duration, resolution, count, startImage: startImageId, endImage: endImageId, ...refImages, ...Object.fromEntries(characterKeys.map(key => [key, prompt[key]])), referenceVideo_1: refVideo_1, startFrameIndex_1, endFrameIndex_1, referenceAudio_1, referenceAudio_2, referenceAudio_3, referenceAudio_4, referenceAudio_5, async: true }); return await submit(apiToken, urlVideos, body, index, text); } // Function to download videos async function download(apiToken) { if (! await fileExists(RESULTS_FILE)) return; try { const resultsContent = await fs.readFile(RESULTS_FILE, 'utf8'); const lines = resultsContent.trim().split('\n'); for (const line of lines) { const [jobId, prompt] = line.split(','); console.log(`👉 ${jobId}`); while (true) { const response = await fetch(`${urlJobs}${jobId}`, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.log(`🛑 Poll failed ${jobId} (HTTP ${response.status}):\n${prompt}\n`, await response.text()); break; } const jobBody = await response.json(); const { status, error, response: jobResponse } = jobBody; if (status == 'failed') { console.error(`🛑 FAILED ${jobId} (${error}):\n${prompt}\n`); break; } if (status == 'completed') { const media = jobResponse?.media ?? []; if (media.length == 0) console.error(`🛑 Completed but no media for ${jobId}:\n${prompt}\n`); // A single prompt with count > 1 returns multiple videos. for (let i = 0; i < media.length; i++) { const url = media[i]?.videoUrl; const videoFilename = `${jobId.replace(/[:*]/g, '_')}_${i + 1}.mp4`; try { await fs.access(videoFilename); console.log(`⚠️ ${videoFilename} already exists. Skipping download.`); continue; } catch { // File does not exist, proceed with downloading } if (url) { console.log(`✅ Downloading ${url} to ${videoFilename}`); // Stream into a temporary file and rename it once the whole video has arrived, so a download // that drops mid-stream leaves no partial file behind for the next run to skip as "already exists". const tempFilename = `${videoFilename}.part`; try { const videoResponse = await fetch(url); if (!videoResponse.ok) { console.error(`⛔ Unable to download ${jobId} (HTTP ${videoResponse.status}):\n${prompt}\n`, url); continue; } const stream = Readable.fromWeb(videoResponse.body); await writeFile(tempFilename, stream); await fs.rename(tempFilename, videoFilename); } catch (err) { await fs.rm(tempFilename, { force: true }); console.error(`⛔ Error during download: ${err}`); } } else console.error(`🛑 No videoUrl for ${jobId} media #${i + 1}:\n${prompt}\n`); } break; } console.log(`⌛ ${jobId} status (${status}) and is still in progress, waiting…`); await sleep(SLEEP_POLL); } } } catch (error) { console.log(`⛔ Error during download:`, error.stack || error); } } // Main function async function main() { const apiToken = process.argv[2]; const email = process.argv[3]; const promptFile = process.argv[4] || DEFAULT_PROMPTS_FILE; if (!apiToken || !email) { console.error('Usage: node omni-flash.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE]'); process.exit(1); } console.info('Script v1.3'); console.info('Node version is: ' + process.version); try { if (await fileExists(RESULTS_FILE)) { let user_input; while (!['y', 'n'].includes(user_input)) { user_input = (await promptUser(`❔ ${RESULTS_FILE} file detected. Do you want to download the results now? (y/n): `))?.toLowerCase(); if (user_input == 'y') { await download(apiToken); await fs.unlink(RESULTS_FILE); } } } const start = new Date(); try { console.info('START EXECUTION', start); await execute(apiToken, email, promptFile); // Pass the promptFile to execute function } finally { console.info('COMPLETED', new Date()); console.info('EXECUTION ELAPSED', diffInMinutesAndSeconds(start, new Date())); } try { console.info('START DOWNLOAD', start); await download(apiToken); } finally { console.info('TOTAL ELAPSED', diffInMinutesAndSeconds(start, new Date())); } } catch (error) { console.error('⛔ Error during execution:', error.stack || error); } } // Modify the execute function to accept promptFile as a parameter async function execute(apiToken, email, promptFile) { const accounts = await fetchAccounts(apiToken); console.info(`Configured Google Flow API accounts (${Object.keys(accounts).length}):`, Object.keys(accounts).join(', ')); if (Object.keys(accounts).length <= 0) { console.error(`⛔ No configured Google Flow accounts found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (!accounts[email]) { console.error(`⛔ Account ${email} not found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (accounts[email].health && accounts[email].health !== 'OK') { console.error(`⛔ Account ${email} health is '${accounts[email].health}'. Please resolve and update the account, see https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } const promptData = await fs.readFile(promptFile, 'utf8'); const prompts = JSON.parse(promptData); console.log(`Total number of prompts to process`, prompts.length); let warnings = []; // Parameters accepted by this script for the omni-flash POST /videos endpoint. // See https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos for the full parameter set. const supportedParams = [ 'prompt', 'model', 'aspectRatio', 'duration', 'resolution', 'count', 'startImage', 'endImage', ...imageRefKeys, ...characterKeys, 'referenceVideo_1', 'startFrameIndex_1', 'endFrameIndex_1', 'referenceAudio_1', 'referenceAudio_2', 'referenceAudio_3', 'referenceAudio_4', 'referenceAudio_5' ]; const audioRefKeys = ['referenceAudio_1', 'referenceAudio_2', 'referenceAudio_3', 'referenceAudio_4', 'referenceAudio_5']; const invalidKeys = (prompt) => Object.keys(prompt).filter(key => !key.startsWith('__') && !supportedParams.includes(key)) // Validate a local file path reference (skip already-uploaded mediaGenerationId strings). const looksLikePath = (ref) => ref && (ref.startsWith('./') || (ref.includes('.') && !ref.startsWith('user:'))); for (let i = 1; i <= prompts.length; i++) { const prompt = prompts[i - 1]; const { prompt: text, referenceVideo_1, duration, startImage, endImage } = prompt; const validateFile = async (file, allowedExts) => { if (looksLikePath(file)) { try { await fs.access(file); } catch { warnings.push(`⚠️ File '${file}' does not exist. Prompt ${i}`); } const ext = file.split('.').pop().toLowerCase(); if (!allowedExts.includes(ext)) warnings.push(`⚠️ File ${file} extension ${ext} not supported. Prompt ${i}`); } }; const notSupported = invalidKeys(prompt); if (notSupported.length) warnings.push(`⚠️ Following params not supported: ${notSupported.join(',')}. Prompt ${i}`); if (!text) warnings.push(`⚠️ prompt is required. Prompt ${i}`); // V2V edit (referenceVideo_1) does not accept duration — output matches the trim window. if (referenceVideo_1 && duration) warnings.push(`⚠️ duration is not accepted with referenceVideo_1 (V2V edit). Prompt ${i}`); if (endImage && !startImage) warnings.push(`⚠️ endImage requires startImage (end-frame-only is not supported). Prompt ${i}`); // Start/end frames (I2V, I2V-FL) are the only input in that mode — the API rejects anything alongside them. if (startImage || endImage) { if (referenceVideo_1) warnings.push(`⚠️ startImage/endImage cannot be combined with referenceVideo_1 (V2V edit). Prompt ${i}`); if ([...imageRefKeys, ...characterKeys].some(k => prompt[k])) warnings.push(`⚠️ startImage/endImage cannot be combined with referenceImage_* or character_*. Prompt ${i}`); if (audioRefKeys.some(k => prompt[k])) warnings.push(`⚠️ startImage/endImage cannot be combined with referenceAudio_*. Prompt ${i}`); } // A voice needs a referenceImage_* or character_* to attach to (or a V2V edit) — the API rejects referenceAudio_* on its own. // With start/end frames the check above already applies. if (!startImage && !endImage && !referenceVideo_1 && audioRefKeys.some(k => prompt[k]) && ![...imageRefKeys, ...characterKeys].some(k => prompt[k])) warnings.push(`⚠️ referenceAudio_* requires a referenceImage_* or character_* (or referenceVideo_1 for a V2V edit). Prompt ${i}`); await Promise.all([ validateFile(referenceVideo_1, supportedVideoExtensions), ...['startImage', 'endImage', ...imageRefKeys].map(k => validateFile(prompt[k], supportedImageExtensions)) ]); } if (warnings.length > 0) { warnings.forEach(warning => console.warn(warning)); console.error(`⛔ Execution stopped due to warnings.`); process.exit(1); } for (let i = 0; i < prompts.length; i++) { const prompt = prompts[i]; while (true) { const responseCode = await submitVideo(apiToken, email, prompt, i + 1); if (responseCode == 429 || responseCode == 503) await sleep(SLEEP_429); else if (responseCode == 402) { process.exit(1); } else break; } } } // Utility function to check if a file exists async function fileExists(path) { try { await fs.access(path); return true; } catch { return false; } } // Function to prompt user input async function promptUser(query) { const rl = readline.createInterface({ input: process.stdin, output: process.stdout }); return new Promise((resolve) => rl.question(query, answer => { rl.close(); resolve(answer); })); } function diffInMinutesAndSeconds(date1, date2) { const diffInSeconds = Math.floor((date2 - date1) / 1000); return `${Math.floor(diffInSeconds / 60)} minutes ${diffInSeconds % 60} seconds`; }; main(); ``` </details> ### Ejemplos Los videos de abajo son resultados reales de Gemini Omni Flash hechos con esta Google Flow API: `model: "omni-flash-1.2"` y `model: "omni-flash"`, extensión, voces, referencias, personajes y edición V2V. ###### Extensión en Omni 1.2: un video de 10 segundos extendido dos veces hasta 30 segundos, con dos voces {: .no_toc #omni-12-extend--a-10-second-video-extended-twice-to-30-seconds-with-two-voices } <video poster="https://media.useapi.net/articles/2026-06-15-omni-flash-bash/261106-google-flow-omni-1-2-magician-extended-30s-web-poster.jpg" controls width="100%" style="max-width:640px;border-radius:8px"> <source src="https://media.useapi.net/articles/2026-06-15-omni-flash-bash/261106-google-flow-omni-1-2-magician-extended-30s-web.mp4" type="video/mp4"> </video> De [Google Flow: Omni 1.2 Flash, 15-Second Videos, and Extend with Voices](/blog/261106) (en inglés): `omni-flash-1.2` en los primeros 10 segundos, después dos llamadas a `POST /videos/extend` con `referenceAudio_1`. ###### Edición V2V: convierte un MP4 subido en caricatura, con el mismo movimiento y encuadre {: .no_toc #v2v-edit--restyle-an-uploaded-mp4-into-a-cartoon-same-motion-and-framing } <video poster="https://media.useapi.net/blog/2026-05-20-260520/google-flow-edit-video-poster.jpg" controls width="100%" style="max-width:640px;border-radius:8px"> <source src="https://media.useapi.net/blog/2026-05-20-260520/google-flow-edit-video.mp4" type="video/mp4"> </video> De [Google Flow: Gemini Omni Flash](/blog/260520) (en inglés): edición con `referenceVideo_1`. ###### Menciones @ en línea: video noir R2V con @character_1, @referenceImage_1, @referenceImage_2 y una voz personalizada {: .no_toc #inline--mentions--r2v-noir-video-with-character_1-referenceimage_1-referenceimage_2-and-a-custom-voice } <video poster="https://media.useapi.net/blog/2026-06-09-260609/noir-shot-1-poster.jpg" controls width="100%" style="max-width:640px;border-radius:8px"> <source src="https://media.useapi.net/blog/2026-06-09-260609/noir-shot-1.mp4" type="video/mp4"> </video> De [Google Flow: Inline @-mentions](/blog/260609) (en inglés): marcadores de mención `@` en línea que anclan cada referencia. ###### Personajes + edición V2V: integra dos personajes reutilizables en el video noir {: .no_toc #characters--v2v-edit--composites-two-reusable-characters-into-the-noir-video } <video poster="https://media.useapi.net/blog/2026-06-09-260609/edit-1-poster.jpg" controls width="100%" style="max-width:640px;border-radius:8px"> <source src="https://media.useapi.net/blog/2026-06-09-260609/edit-1.mp4" type="video/mp4"> </video> De [Google Flow: Inline @-mentions](/blog/260609) (en inglés): edición V2V con `referenceVideo_1` y `@character_*` en línea. Consulta también [Reusable Voices and Characters](/blog/260605) (en inglés) para el flujo de creación de voces y personajes. ### Preguntas frecuentes - **¿Qué es Gemini Omni Flash?** Con useapi.net ejecutas Gemini Omni Flash, el [modelo de video con audio nativo](https://deepmind.google/models/model-cards/gemini-omni-flash/) de Google en [Google Flow](https://flow.google.com), definiendo `model: "omni-flash-1.2"` (Omni 1.2 Flash) o `model: "omni-flash"` (Omni 1.1 Flash) en la [Google Flow API](/docs/api-google-flow-v1). A diferencia de un modelo de video mudo, genera la banda sonora, la narración, el diálogo y el ambiente como parte del mismo video, y acepta referencias de imagen, video y audio, además de personajes reutilizables. - **¿Qué diferencia hay entre Omni Flash y Veo 3.1?** Con useapi.net los dos se ejecutan en la misma Google Flow API y se eligen con el campo `model`. Veo es el motor de texto a video e imagen a video sencillo con más fidelidad, y Omni Flash tiene audio nativo y acepta muchas referencias, con edición de video a video (`referenceVideo_1`), varias voces por video, personajes reutilizables en cualquier duración y videos más largos que los de Veo. Consulta los límites exactos en [Modos de referencia](#reference-modes). - **¿Puedo usar mi propia voz, un video de referencia o un audio de referencia?** Con useapi.net, sí. Narra con las voces listas del sistema o con voces personalizadas de [POST /voices](/docs/api-google-flow-v1/post-google-flow-voices), pasadas como `referenceAudio_1..5`, y sube un MP4 con [POST /assets](/docs/api-google-flow-v1/post-google-flow-assets-email) para editarlo como `referenceVideo_1` (V2V). Consulta los límites de cada modo en [Modos de referencia](#reference-modes) y [Voces y personajes](#voices--characters). - **¿Existe una API oficial de Omni Flash?** Con useapi.net, Omni 1.1 Flash cuesta mucho menos que en la API del propio Google: un video de 8 segundos en 720p cuesta US$0,10 en Google AI Ultra US$199,99, frente a US$0,81 en la [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) oficial, que vende el modelo por segundo desde el 30 de junio de 2026 (a noviembre de 2026). Se ejecuta mediante un endpoint REST estándar con tu suscripción al sitio web de Google Flow. - **¿Omni Flash hace videos de más de 10 segundos?** Con useapi.net, sí: Omni 1.2 Flash (`model: "omni-flash-1.2"`) genera hasta 15 segundos en una llamada, y [POST /videos/extend](/docs/api-google-flow-v1/post-google-flow-videos-extend) agrega hasta 10 segundos cada vez con voces, a US$0,19 por un video de 8 segundos en 720p en Google AI Ultra US$199,99, frente a US$0,56 en la [API del propio Google](https://cloud.google.com/blog/products/ai-machine-learning/gemini-omni-1-2-flash-generally-available) (a noviembre de 2026). Todos los límites de duración y los precios en Google Flow y Google Vids están en [Cómo usar la API de Gemini Omni 1.2 Flash](/docs/articles/gemini-omni-1-2-flash-api-es). - **¿Tengo que resolver captchas?** Con useapi.net nunca resuelves un captcha. Google Flow pide un reCAPTCHA en cada video y en cada voz nueva, y el worker de useapi.net lo resuelve automáticamente: tu primera cuenta de Google Flow incluye 300 resoluciones gratis con nuestras propias claves de AntiCaptcha, CapSolver y EzCaptcha, y después agregas las claves de tu propio proveedor con [POST /accounts/captcha-providers](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers). [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters) no necesita captcha. ### Conclusión Visita nuestro <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> servidor de Discord</a> o el <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> canal de Telegram</a> para cualquier pregunta de soporte. Consulta nuestro [repositorio de GitHub](https://github.com/useapi/google-flow-api) con ejemplos de código. Un asistente de IA también puede trabajar con Google Flow por ti: el [servidor MCP de Google Flow](/docs/api-google-flow-v1/mcp) alojado permite que Claude Code, Cursor y VS Code hablen con el Google Flow Agent, que genera imágenes y videos en tu cuenta. ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/omni-flash-bash-id === Document URL: https://useapi.net/docs/articles/omni-flash-bash-id --- layout: default title: "Cara Membuat Video AI dengan Audio Bawaan memakai Gemini Omni Flash lewat Google Flow API" seo_title: "Gemini Omni Flash API: Video AI Bersuara lewat Google Flow API" description: "Gemini Omni Flash di Google Flow API useapi.net dengan kode: gambar referensi, karakter, suara dan edit V2V di Omni 1.2 dan 1.1, plus skrip batch." keywords: [Gemini Omni Flash, Omni 1.2 Flash, Omni 1.1 Flash, Omni Flash API, API Omni Flash, omni-flash-1.2, Google Flow API, API Google Flow, video AI dengan suara, audio-native video, perpanjang video, extend video, suara, karakter, edit video, video-ke-video, tutorial bahasa Indonesia, kode] parent: Articles nav_exclude: true lang: id translation_key: omni-flash date: 2026-06-15 last_modified: 2026-11-12 nav_order: 830 repo: https://github.com/useapi/google-flow-api --- ## Cara Membuat Video AI dengan Audio Bawaan memakai Gemini Omni Flash lewat Google Flow API {: .no_toc #how-to-generate-audio-native-ai-video-with-gemini-omni-flash-via-the-google-flow-api } 8 menit baca • 15 Juni 2026 (12 November 2026) useapi.net adalah API pihak ketiga. Kami tidak berafiliasi dengan Google dan tidak disahkan oleh Google. ## Daftar isi {: .no_toc .text-delta #table-of-contents } ### Pendahuluan [Gemini Omni Flash](https://deepmind.google/models/model-cards/gemini-omni-flash/) membuat video AI dengan audio bawaan dari satu `curl` lewat [Google Flow API](/docs/api-google-flow-v1) useapi.net, lengkap dengan suara yang tersinkron, karakter, dan edit video-ke-video, di langganan situs [Google Flow](https://flow.google.com) Anda ([Google AI](https://gemini.google/subscriptions/): Omni 1.1 Flash di Plus, Pro atau Ultra, Omni 1.2 Flash di semua paket, akun gratis hingga 10 detik). Satu video 720p 10 detik berbiaya $0,12 di Google AI Ultra $199,99, dibanding $1,01 di [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) resmi (per November 2026), tanpa project Google Cloud maupun API key. Langganan yang sama juga membuat video Omni di [Google Vids](/docs/api-google-vids-v1), tanpa memakai kredit Flow. Di antarmukanya Google Flow menamai model ini Omni 1.1 Flash, dan nilainya di API adalah `model: "omni-flash"`. Omni 1.2 Flash, yang dirilis Google pada 5 November 2026, memakai nilai terpisah, `model: "omni-flash-1.2"`: durasi berapa pun dari 3 sampai 15 detik, kredit per detik, dan model inilah yang [memperpanjang video](#extend-a-video-with-omni-12) hingga 10 detik setiap kali. Kode yang mengirim `omni-flash` tetap mendapat 1.1. Untuk video 15 detik, extend dengan suara, dan harga per video di Google Flow dan Google Vids, lihat [Cara Memakai Gemini Omni 1.2 Flash API](/docs/articles/gemini-omni-1-2-flash-api-id). Omni Flash memakai [Google Flow API yang sama](/docs/api-google-flow-v1) dengan Veo, dipilih dengan satu field — `model: "omni-flash-1.2"` atau `model: "omni-flash"` — tetapi jenis modelnya berbeda. Veo adalah mesin text-to-video biasa yang kuat, sedangkan Omni Flash membuat audio sendiri dan menerima banyak referensi: - Suara dibuat sebagai bagian dari video — narasi, dialog, dan suasana keluar dari model yang sama, bukan ditempelkan belakangan. - Suara pembicara — 30 preset suara sistem bawaan ditambah suara kustom yang Anda buat dari dialog dan catatan pembawaan Anda sendiri, dikirim lewat `referenceAudio_1..5`. - Referensi gambar dan video — hingga 10 gambar referensi di Omni 1.2 Flash (7 di Omni 1.1 Flash) untuk reference-to-video (R2V), serta edit video-ke-video (V2V) dari video hasil upload atau hasil generate lewat `referenceVideo_1`. - Karakter yang bisa dipakai ulang — gabungkan gambar referensi + satu suara menjadi karakter bernama dan pakai lagi di banyak video. - Video lebih panjang — Omni 1.1 Flash membuat 4, 6, 8 atau 10 detik dan Omni 1.2 Flash durasi berapa pun dari 3 sampai 15 (Veo maksimal `8`), dan Omni 1.2 memperpanjang video bertahap hingga 10 detik per langkah. Panduan ini menunjukkan alur kerja dua panggilan dengan `curl` yang siap disalin, mode-mode referensi yang membuat Omni Flash istimewa, lalu skrip Node.js siap jalan yang membuat video secara batch dari daftar prompt. Untuk text-to-video biasa, lihat [tutorial Veo 3.1](/docs/articles/google-flow-bash-id) yang menjadi pasangannya. ### Model yang didukung Panduan ini memakai model video Google dengan audio bawaan, Omni 1.1 Flash (`model: "omni-flash"`) dan Omni 1.2 Flash (`model: "omni-flash-1.2"`). Untuk Omni 1.1, biaya kredit naik sesuai durasi video: | Durasi | Kredit per video | |----------|------------------------| | 4s | 7 | | 6s | 10 | | 8s | 12 | | 10s | 15 | | Edit V2V | 20 | Itu biaya di resolusi default `720p`. Dengan `resolution: "360p"` biayanya sekitar separuh — 4 / 5 / 6 / 7 kredit menurut durasi, 10 untuk edit V2V — dan video 360p bisa dinaikkan ke 720p sesudahnya dengan [POST /videos/upscale](/docs/api-google-flow-v1/post-google-flow-videos-upscale). Omni 1.2 Flash (`model: "omni-flash-1.2"`) menerima jumlah detik bulat berapa pun dari 3 sampai 15 dan menagihnya per detik, sama di setiap paket: | Durasi | 720p | 360p | |--------|------|------| | 3s | 9 | 3 | | 8s | 24 | 8 | | 10s | 30 | 10 | | 15s | 60 | 20 | Hingga 10 detik biayanya 3 kredit per detik di 720p dan 1 di 360p, dan setiap detik setelah detik ke-10 berbiaya dua kali lipat. Edit V2V berbiaya sama dengan video sepanjang bagian yang diedit, dan 1.2 bisa mengedit hingga 15 detik dari sebuah klip. Akun Google gratis bisa memakai 1.2 untuk video hingga 10 detik. Omni Flash menerima lima mode di [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos): text-to-video biasa (T2V), reference-to-video (R2V) dengan hingga 10 `referenceImage_1..10` di Omni 1.2 Flash (7 di Omni 1.1 Flash), image-to-video dari frame awal lewat `startImage` (I2V), image-to-video di antara frame awal dan frame akhir lewat `startImage` + `endImage` (I2V-FL), dan edit video-ke-video (V2V) dari MP4 yang di-upload lewat `referenceVideo_1`. Lihat [Mode referensi](#reference-modes) di bawah. ### Harga Omni 1.1 Flash butuh langganan Google AI berbayar (Plus, Pro atau Ultra), Omni 1.2 Flash berjalan di akun gratis hingga 10 detik, dan useapi.net tidak menambahkan biaya per video. Setiap video memakai kredit Flow sesuai durasinya (lihat [Model yang didukung](#supported-model)). Harga per video di setiap paket, dibandingkan dengan Gemini API resmi, ada di [tabel harga Google Flow](/docs/api-google-flow-v1#pricing). Paket Google AI juga berisi kuota bulanan di [Google Vids](https://docs.google.com/videos), yang membuat video hingga 15 detik dengan Gemini Omni 1.2 Flash ([pengumuman Google](https://workspaceupdates.googleblog.com/2026/11/gemini-omni-12-flash-now-in-vids-with-15second-generations-and-improved-quality.html)) dan tidak memakai kredit Flow. Di Ultra $199,99 (Google menyebutnya Ultra 20x) kuotanya 10.000 detik video per bulan — sekitar 1.000 klip 10 detik 1080p tambahan di luar ~1.666 klip Omni 1.1 Flash 10 detik (atau ~833 klip Omni 1.2 Flash di 720p) yang bisa dibeli dengan 25.000 kredit Flow. Detik-detik itu dipakai bersama oleh semua anggota paket keluarga Google. Paket lain mendapat lebih sedikit (lihat halaman [Gemini di Google Vids](https://support.google.com/docs/answer/15609411?hl=id) milik Google), dan akun gratis yang kami uji tidak mendapat kuota sama sekali. [Google Vids API](/docs/api-google-vids-v1) memakai kuota ini tanpa captcha. Hubungkan akunnya lewat [Setup Google Vids](/docs/start-here/setup-google-vids). ### Membuat video dalam dua panggilan API Anda butuh [API token](/docs/start-here/setup-useapi) useapi.net dan [akun Google Flow](/docs/start-here/setup-google-flow) yang sudah terhubung dengan langganan Google AI berbayar (Plus, Pro atau Ultra) untuk contoh Omni 1.1 Flash di bawah (Omni 1.2 Flash juga berjalan di akun gratis, hingga 10 detik). Job video berjalan secara asynchronous: kirim `async: true` dan panggilan create langsung mengembalikan `jobid`, lalu Anda melakukan polling sampai videonya siap. 1. Kirim job — `POST https://api.useapi.net/v1/google-flow/videos` dengan `model: "omni-flash"`: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A lighthouse keeper narrates the coming storm, waves crashing below", "model": "omni-flash", "aspectRatio": "landscape", "duration": 10, "async": true }' ``` Omni Flash membuat audionya sendiri, jadi soundtrack — narasi penjaga mercusuar dan deburan ombak — langsung dibuat dari prompt, tanpa parameter audio. Dalam mode async, respons langsung kembali dengan `201 Created`, `jobid` berhuruf kecil, dan `status: "created"`: ```json { "jobid": "j1731859234567v-u12345-email:jo***@gmail.com-bot:google-flow", "type": "video", "status": "created", "created": "2026-06-15T12:34:56.789Z", "request": { "async": true, "prompt": "A lighthouse keeper narrates the coming storm, waves crashing below", "model": "omni-flash", "aspectRatio": "landscape", "duration": 10 } } ``` 2. Polling hasilnya — `GET https://api.useapi.net/v1/google-flow/jobs/{jobId}`: ```bash curl "https://api.useapi.net/v1/google-flow/jobs/JOBID" \ -H "Authorization: Bearer $USEAPI_TOKEN" ``` `status` berpindah dari `created` → `started` → `completed`. Saat mencapai `completed`, MP4 jadi ada di `response.media[].videoUrl` (satu prompt dengan `count > 1` mengembalikan satu entri per video): ```json { "jobid": "j1731859234567v-...", "type": "video", "status": "completed", "response": { "media": [ { "mediaGenerationId": "user:12345-email:6a6f...-video:a1d95d21-...", "videoUrl": "https://flow-content.google/video/a1d95d21-...?Expires=...", "thumbnailUrl": "https://flow-content.google/image/a1d95d21-...?Expires=..." } ], "remainingCredits": 18760 } } ``` Omni Flash biasanya selesai dalam 60–180 detik. `videoUrl` yang ditandatangani berlaku sekitar 6 jam, jadi segera unduh. Tidak mau polling? Kirim `replyUrl` di body create untuk menerima callback webhook saat job selesai. ### Mode referensi Keunggulan khas Omni Flash adalah banyaknya referensi yang bisa Anda berikan. Semua referensi berasal dari endpoint upload [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email) (atau, untuk karakter, dari [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters)). Respons upload menyimpan id referensi secara bersarang di `mediaGenerationId.mediaGenerationId` — string bersarang itulah yang Anda kirim kembali. Mode yang diterima `omni-flash` (dari dokumentasi [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos#references)): | Mode | Parameter | Batas Omni Flash | |------|--------------|------------------| | Reference-to-video (R2V) | `referenceImage_1..10` | hingga 10 gambar referensi di `omni-flash-1.2`, 7 di `omni-flash` | | Image-to-video (I2V) | `startImage` | satu frame awal | | Image-to-video, awal + akhir (I2V-FL) | `startImage` + `endImage` | hanya kedua frame itu — tanpa referensi lain | | Edit video-ke-video (V2V) | `referenceVideo_1` (+ opsional `startFrameIndex_1` / `endFrameIndex_1`) | satu MP4 hasil upload | | Karakter | `character_1..10` (dari [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters)) | total 10 bersama `referenceImage_*` di `omni-flash-1.2`, 7 di `omni-flash` | | Narasi suara | `referenceAudio_1..5` | hingga 5 (R2V) / hingga 3 (edit V2V) | Reference-to-video (R2V) — upload satu atau beberapa gambar, lalu kirim sebagai `referenceImage_1`, `referenceImage_2`, … (slot `_4`..`_7` hanya untuk Omni Flash). Referensi gambar tidak bisa digabung dengan `startImage`/`endImage`. ```bash # 1. Upload a reference image — the id is nested one level deep: curl -X POST "https://api.useapi.net/v1/google-flow/assets/john%40gmail.com" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: image/jpeg" \ --data-binary @subject.jpeg # Response: { "mediaGenerationId": { "mediaGenerationId": "user:12345-email:...-image:..." }, ... } # 2. Generate, narrated by a system voice curl -X POST "https://api.useapi.net/v1/google-flow/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model": "omni-flash", "prompt": "the subject walks toward camera and introduces herself", "duration": 8, "referenceImage_1": "user:12345-email:...-image:...", "referenceAudio_1": "Kore" }' ``` Edit video-ke-video (V2V) — upload MP4 dengan `Content-Type: video/mp4` ke [POST /assets](/docs/api-google-flow-v1/post-google-flow-assets-email), lalu kirim id yang dikembalikan sebagai `referenceVideo_1` untuk mengedit video itu. Mode ini hanya ada di Omni Flash dan mengubah request ke mode V2V. `duration` tidak diterima (panjang hasil mengikuti jendela potongan input, maksimal 10 detik di `omni-flash` dan 15 detik di `omni-flash-1.2`). Jika perlu, potong sumbernya pada timeline virtual 24 fps dengan `startFrameIndex_1` (0–239) dan `endFrameIndex_1` (1–240, dengan 240 = 10 detik), atau hingga 359 dan 360 (15 detik) di `omni-flash-1.2`: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model": "omni-flash", "prompt": "restyle the scene as a rainy neon-lit night, add ambient city sound", "referenceVideo_1": "user:12345-email:...-video:...", "startFrameIndex_1": 0, "endFrameIndex_1": 240, "async": true }' ``` Anda juga bisa menaruh penanda `@` inline di prompt yang merujuk ke slot yang Anda isi — misalnya `@referenceImage_1`, `@character_1`, `@referenceAudio_1`. Penanda bersifat opsional dan masing-masing harus punya parameter body yang cocok. (`@referenceVideo_*` tidak didukung secara inline — kirim sebagai field body.) Lihat [penanda @-mention inline](/docs/api-google-flow-v1/post-google-flow-videos#inline--mention-markers-optional). ### Suara & karakter Dua panggilan setup singkat menjalankan fitur audio dan identitas Omni Flash. Suara kustom — [POST /voices](/docs/api-google-flow-v1/post-google-flow-voices) menyimpan suara yang dibangun dari salah satu dari 30 preset sistem dengan `dialog` dan `voicePerformance` milik Anda sendiri. Field `voice` di respons adalah id referensi yang lalu Anda kirim sebagai `referenceAudio_1..5` di [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos): ```bash curl -X POST "https://api.useapi.net/v1/google-flow/voices" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "john@gmail.com", "voice": "Achernar", "dialog": "Welcome to the demo.", "voicePerformance": "Cheerful, energetic delivery", "displayName": "Cheerful Narrator" }' # Response: { "voice": "user:12345-email:...-voice:...-mid:...", ... } ``` Setiap slot `referenceAudio_*` menerima nama suara sistem (tidak peka huruf besar-kecil, salah satu dari 30 preset seperti `Aoede`, `Kore`, `Puck`, `Zephyr`) atau id suara pengguna dari panggilan di atas. Pembuatan suara butuh reCAPTCHA (diselesaikan otomatis — lihat [FAQ](#frequently-asked-questions)). Karakter yang bisa dipakai ulang — [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters) menggabungkan 1–2 gambar referensi plus suara opsional menjadi karakter bernama. Field `character` di respons adalah nilai yang Anda kirim sebagai `character_1..10`: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/characters" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "displayName": "Carol", "imageReference_1": "user:12345-email:...-image:abc123...", "voice": "user:12345-email:...-voice:...-mid:..." }' # Response: { "character": "user:12345-email:...-character:...-imgs:1-voice:...", ... } ``` Di Omni Flash, karakter bisa dipakai di semua durasi dan berbagi batas total 10 referensi gambar dengan `referenceImage_*` (`referenceImages.length + Σ(character.imgs) ≤ 10`, Omni 1.1: 7). `POST /characters` tidak butuh captcha. Karakter dan suara juga bisa dipakai di Veo, tetapi dengan batas lebih ketat (3 gambar, 1 suara, hanya 8 detik) — lihat [What can use a character?](/docs/api-google-flow-v1/post-google-flow-characters#what-can-use-a-character). ### Memperpanjang video dengan Omni 1.2 [POST /videos/extend](/docs/api-google-flow-v1/post-google-flow-videos-extend) menambahkan 3 sampai 10 detik setiap kali dengan Omni 1.2 Flash ke video apa pun yang lebih pendek dari 30 detik, dengan hingga 3 suara, gambar referensi atau karakter, dan mengembalikan satu klip utuh (hanya paket berbayar). Panduan di [Cara Memakai Gemini Omni 1.2 Flash API](/docs/articles/gemini-omni-1-2-flash-api-id#flow-walkthrough) memperpanjang video 10 detik dua kali menjadi 30 detik dengan dua suara, yaitu [contoh di bawah](#examples). ### Generate batch dengan skrip Menemukan hasil yang pas butuh banyak percobaan, dan menjalankannya satu per satu dengan tangan itu melelahkan. Skrip Node.js di bawah membaca daftar prompt dari `prompts.json`, meng-upload gambar referensi, frame awal dan akhir, atau video sumber jika ada, meneruskan id `character_*` dan `resolution` apa adanya, mengirim setiap job dalam mode async dengan `model: "omni-flash"`, lalu melakukan polling dan mengunduh setiap MP4 yang sudah jadi — jadi Anda bisa mengantrekan satu batch lalu kembali untuk memilih yang terbaik. Skrip berhenti dengan peringatan sebelum mengirim kombinasi yang akan ditolak API, misalnya frame akhir tanpa frame awal. Anda butuh [Node.js](https://nodejs.org) v21 atau lebih baru. Taruh `prompts.json` dan `omni-flash.mjs` di folder yang sama dan jalankan `node ./omni-flash.mjs API_TOKEN EMAIL`, dengan `API_TOKEN` berisi [API token](/docs/start-here/setup-useapi) useapi.net Anda dan `EMAIL` berisi email [akun Google Flow](/docs/start-here/setup-google-flow) yang terhubung. Skrip mencari akun berdasarkan email secara otomatis dan memeriksa field `health`-nya sebelum mengirim. Lebih suka clone dan menjalankannya di komputer sendiri? `omni-flash.mjs` dan `prompts.json` lengkap ada di GitHub di [`useapi/google-flow-api`](https://github.com/useapi/google-flow-api/tree/main/omni-flash). Bekerja di Claude Code atau Codex? [Agent skill omni-flash-video](https://github.com/useapi/google-flow-api/tree/main/skills/omni-flash-video) membuat agent mengerjakan semuanya untuk Anda: jelaskan videonya, tunjukkan gambar Anda, dan agent meng-upload gambar itu, menulis request, menunggu, lalu menyimpan `.mp4`-nya. Pasang dengan `npx skills add useapi/google-flow-api --skill omni-flash-video`. <details markdown="block"> <summary>Buka `prompts.json`</summary> ```json [ { "prompt": "Audio-native text-to-video. By default model omni-flash with a landscape 8-second clip will be used." }, { "duration": 10, "prompt": "A 10-second clip (omni-flash only). Omni Flash is audio-native, so narration, dialogue and sound come from the prompt. To pin a specific voice, add referenceAudio_1 together with a referenceImage_* or character_*, as in the next prompt." }, { "duration": 8, "referenceImage_1": "./subject.jpeg", "referenceAudio_1": "Kore", "prompt": "Reference-to-video (R2V): the uploaded image is a reference, narrated by 'Kore'. Up to 7 referenceImage_* on omni-flash, 10 on omni-flash-1.2." }, { "duration": 8, "startImage": "./first_image.jpeg", "endImage": "./last_image.jpeg", "prompt": "Image-to-video with a start frame (startImage) and an end frame (endImage). The two frames are the only input — no referenceImage_*, character_* or referenceAudio_* alongside them." }, { "referenceVideo_1": "./source.mp4", "startFrameIndex_1": 0, "endFrameIndex_1": 240, "prompt": "Video-to-video edit (V2V): omni-flash restyles the uploaded MP4. No duration here — output matches the trim window (max 10 s). For all parameters see https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos" } ] ``` </details> <details markdown="block"> <summary>Buka skrip `omni-flash.mjs`</summary> ```javascript /* Script version 1.3, November 11, 2026 Script to batch-generate audio-native videos with Gemini Omni Flash using the Google Flow API by useapi.net Uses the POST /videos endpoint in async mode (model: omni-flash by default, or omni-flash-1.2 per prompt) and polls GET /jobs/{jobId}. For more details visit https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos Installation Instructions: ========================== You need Node.js v21 or newer installed to run this script. Download and install Node.js from: - Windows, macOS, Linux: https://nodejs.org/ After installation, verify by running the following command in a terminal: node -v Running the Script: =================== Usage: node omni-flash.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE] Replace API_TOKEN with your actual useapi.net API token, see https://useapi.net/docs/start-here/setup-useapi Replace EMAIL with configured Google Flow email account, see https://useapi.net/docs/start-here/setup-google-flow If optional PROMPTS_FILE not provided prompts.json will be used. Example: -------- node omni-flash.mjs user:1234-abcdefhijklmnopqrstuv my@email.com This command executes the script using API token user:1234-abcdefhijklmnopqrstuv with my@email.com Google Flow account email. Changelog: ========== - June 15, 2026: Initial release. - September 11, 2026: Adds resolution, startImage / endImage (start and end frames, local files uploaded for you) and character_1..7. Accepts .jpg and upper-case file extensions. Stops with a warning before submitting combinations the API rejects, such as endImage without startImage or referenceAudio_* on its own. A prompt whose local startImage, endImage, referenceImage_* or referenceVideo_1 file fails to upload is skipped and logged to omni-flash_errors.txt instead of being submitted without it. Saves a downloaded video under its final name only once it has been fully received, so a failed download leaves no partial MP4 for the next run to skip as "already exists". - November 11, 2026: referenceImage_8..10 and character_8..10: omni-flash-1.2 takes up to 10 references (omni-flash 7). */ import readline from 'node:readline'; import fs from 'fs/promises'; import path from 'path'; import { writeFile } from 'node:fs/promises'; import { Readable } from 'node:stream'; // Constants const RESULTS_FILE = 'omni-flash_results.txt'; const ERRORS_FILE = 'omni-flash_errors.txt'; const DEFAULT_PROMPTS_FILE = 'prompts.json'; const MODEL = 'omni-flash'; // Reference slots: up to 10 on omni-flash-1.2, 7 on omni-flash, 3 on Veo (referenceImage_* and character_* together). const imageRefKeys = Array.from({ length: 10 }, (_, i) => `referenceImage_${i + 1}`); const characterKeys = Array.from({ length: 10 }, (_, i) => `character_${i + 1}`); const SLEEP_429 = 30 * 1000; // in milliseconds const SLEEP_POLL = 15 * 1000; // in milliseconds const urlAccounts = 'https://api.useapi.net/v1/google-flow/accounts'; const urlVideos = 'https://api.useapi.net/v1/google-flow/videos'; const urlJobs = 'https://api.useapi.net/v1/google-flow/jobs/'; const urlUploadAsset = 'https://api.useapi.net/v1/google-flow/assets/'; // Google Flow accepts png, jpeg and webp images, and mp4 video (for omni-flash V2V edit). const supportedImageExtensions = ['png', 'jpg', 'jpeg', 'webp']; const supportedVideoExtensions = ['mp4']; // { filename: mediaGenerationId } const uploadedFiles = {}; // Utility to sleep for given milliseconds const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); // Function to fetch configured Google Flow API accounts async function fetchAccounts(apiToken) { const response = await fetch(urlAccounts, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.error(`⛔ Error fetching accounts (HTTP ${response.status}): ${response.statusText}`); process.exit(1); } return response.json(); } const elapsedTimeSec = (start) => (Date.now() - start) / 1000; // Map a file extension to the Content-Type required by POST /assets const contentTypeForExt = (ext) => ext === 'png' ? 'image/png' : ext === 'webp' ? 'image/webp' : ext === 'mp4' ? 'video/mp4' : 'image/jpeg'; async function uploadAsset(apiToken, email, filename) { // Check if already uploaded if (uploadedFiles.hasOwnProperty(filename)) return uploadedFiles[filename]; const startTime = Date.now(); console.log(`⬆️ Account ${email} uploading file…`, filename); const body = new Blob([await fs.readFile(filename)]); const fileExt = filename.split('.').pop().toLowerCase(); const response = await fetch(`${urlUploadAsset}${encodeURIComponent(email)}`, { method: 'POST', headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}`, 'Content-Type': contentTypeForExt(fileExt) }, body }); if (response.ok) { const json = await response.json(); // POST /assets returns the reference id nested as mediaGenerationId.mediaGenerationId const mediaGenerationId = json?.mediaGenerationId?.mediaGenerationId; console.log(`🆗 mediaGenerationId (${elapsedTimeSec(startTime)} sec)`, mediaGenerationId); uploadedFiles[filename] = mediaGenerationId; } else { console.error(`❗ Unable to upload file HTTP ${response.status} (${elapsedTimeSec(startTime)} sec)`, await response.text()); // Do not attempt to upload failed file again uploadedFiles[filename] = undefined; } return uploadedFiles[filename]; } async function submit(apiToken, url, body, index, prompt) { const createResponse = await fetch(url, { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiToken}` }, body }); const createBody = await createResponse.text(); // Async POST /videos returns 201 Created with a jobid to poll. if (createResponse.status == 201) { const json = JSON.parse(createBody); // 201 async payload uses lowercase "jobid"; sync 200 uses "jobId". Accept either. const jobId = json.jobid ?? json.jobId; if (jobId) { await fs.appendFile(RESULTS_FILE, `${jobId},#${index}:${prompt}\n`); console.log(`✅ jobId`, jobId); return 201; } else { const error = `No jobid found in HTTP 201 response`; console.log(`❓ ${error}`, createBody); await fs.appendFile(ERRORS_FILE, `${error},#${index}:${prompt}\n`); return 500; } } else { switch (createResponse.status) { case 429: console.log(`🔄️ Retry on HTTP ${createResponse.status}`, createBody); break; case 503: console.log(`🔄️ Service unavailable, retry on HTTP ${createResponse.status}`, createBody); break; case 400: console.log(`🛑 Rejected request (validation or content policy)`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${prompt}\n`); break; case 402: console.log(`🛑 No subscription / insufficient credits`, createBody); break; default: console.log(`❗ FAILED with HTTP ${createResponse.status}`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${prompt}\n`); } return createResponse.status; } } // Submit a single prompt to POST /videos with model omni-flash (or the prompt's own model) in async mode. // startImage = start frame (I2V), endImage = end frame (I2V-FL, requires startImage) — the frames are the only input; // referenceImage_1..10 = R2V image refs; character_1..10 = POST /characters ids (10 on omni-flash-1.2, 7 on omni-flash); // referenceVideo_1 = V2V edit (no duration); referenceAudio_1..5 = system voice name or POST /voices user-voice id; // resolution = 720p (default) or 360p; model = 'omni-flash' (Omni 1.1, the default) or 'omni-flash-1.2' (3–15 s, per-second credits). async function submitVideo(apiToken, email, prompt, index) { const { prompt: text, model = MODEL, aspectRatio, duration, resolution, count, startImage, endImage, referenceVideo_1, startFrameIndex_1, endFrameIndex_1, referenceAudio_1, referenceAudio_2, referenceAudio_3, referenceAudio_4, referenceAudio_5 } = prompt; console.log(`🚀 ${model} » Prompt #${index} • account ${email} …`); // Upload any local image/video files and swap the paths for their mediaGenerationId. const resolveRef = async (ref) => ref && (ref.startsWith('./') || ref.includes('.')) && [...supportedImageExtensions, ...supportedVideoExtensions].includes(ref.split('.').pop().toLowerCase()) ? await uploadAsset(apiToken, email, ref) : ref; const startImageId = await resolveRef(startImage); const endImageId = await resolveRef(endImage); const refImages = {}; for (const key of imageRefKeys) refImages[key] = await resolveRef(prompt[key]); const refVideo_1 = await resolveRef(referenceVideo_1); // A local file that failed to upload would be left out of the body, and the prompt would still be // generated (and charged) without it. Skip the prompt instead. uploadAsset remembers the failed file, // so a later prompt using it is skipped too, without another upload attempt. const failedUploads = [ ['startImage', startImage, startImageId], ['endImage', endImage, endImageId], ...imageRefKeys.map(key => [key, prompt[key], refImages[key]]), ['referenceVideo_1', referenceVideo_1, refVideo_1] ].filter(([, file, id]) => file && !id); for (const [param, file] of failedUploads) { console.error(`🛑 Prompt #${index} skipped: ${param} ${file} failed to upload`); await fs.appendFile(ERRORS_FILE, `Upload failed for ${param} ${file},#${index}:${text}\n`); } if (failedUploads.length) return; // V2V edit does not accept duration — output matches the trim window. const isV2V = !!refVideo_1; const body = JSON.stringify({ model, email, prompt: text, aspectRatio, duration: isV2V ? undefined : duration, resolution, count, startImage: startImageId, endImage: endImageId, ...refImages, ...Object.fromEntries(characterKeys.map(key => [key, prompt[key]])), referenceVideo_1: refVideo_1, startFrameIndex_1, endFrameIndex_1, referenceAudio_1, referenceAudio_2, referenceAudio_3, referenceAudio_4, referenceAudio_5, async: true }); return await submit(apiToken, urlVideos, body, index, text); } // Function to download videos async function download(apiToken) { if (! await fileExists(RESULTS_FILE)) return; try { const resultsContent = await fs.readFile(RESULTS_FILE, 'utf8'); const lines = resultsContent.trim().split('\n'); for (const line of lines) { const [jobId, prompt] = line.split(','); console.log(`👉 ${jobId}`); while (true) { const response = await fetch(`${urlJobs}${jobId}`, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.log(`🛑 Poll failed ${jobId} (HTTP ${response.status}):\n${prompt}\n`, await response.text()); break; } const jobBody = await response.json(); const { status, error, response: jobResponse } = jobBody; if (status == 'failed') { console.error(`🛑 FAILED ${jobId} (${error}):\n${prompt}\n`); break; } if (status == 'completed') { const media = jobResponse?.media ?? []; if (media.length == 0) console.error(`🛑 Completed but no media for ${jobId}:\n${prompt}\n`); // A single prompt with count > 1 returns multiple videos. for (let i = 0; i < media.length; i++) { const url = media[i]?.videoUrl; const videoFilename = `${jobId.replace(/[:*]/g, '_')}_${i + 1}.mp4`; try { await fs.access(videoFilename); console.log(`⚠️ ${videoFilename} already exists. Skipping download.`); continue; } catch { // File does not exist, proceed with downloading } if (url) { console.log(`✅ Downloading ${url} to ${videoFilename}`); // Stream into a temporary file and rename it once the whole video has arrived, so a download // that drops mid-stream leaves no partial file behind for the next run to skip as "already exists". const tempFilename = `${videoFilename}.part`; try { const videoResponse = await fetch(url); if (!videoResponse.ok) { console.error(`⛔ Unable to download ${jobId} (HTTP ${videoResponse.status}):\n${prompt}\n`, url); continue; } const stream = Readable.fromWeb(videoResponse.body); await writeFile(tempFilename, stream); await fs.rename(tempFilename, videoFilename); } catch (err) { await fs.rm(tempFilename, { force: true }); console.error(`⛔ Error during download: ${err}`); } } else console.error(`🛑 No videoUrl for ${jobId} media #${i + 1}:\n${prompt}\n`); } break; } console.log(`⌛ ${jobId} status (${status}) and is still in progress, waiting…`); await sleep(SLEEP_POLL); } } } catch (error) { console.log(`⛔ Error during download:`, error.stack || error); } } // Main function async function main() { const apiToken = process.argv[2]; const email = process.argv[3]; const promptFile = process.argv[4] || DEFAULT_PROMPTS_FILE; if (!apiToken || !email) { console.error('Usage: node omni-flash.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE]'); process.exit(1); } console.info('Script v1.3'); console.info('Node version is: ' + process.version); try { if (await fileExists(RESULTS_FILE)) { let user_input; while (!['y', 'n'].includes(user_input)) { user_input = (await promptUser(`❔ ${RESULTS_FILE} file detected. Do you want to download the results now? (y/n): `))?.toLowerCase(); if (user_input == 'y') { await download(apiToken); await fs.unlink(RESULTS_FILE); } } } const start = new Date(); try { console.info('START EXECUTION', start); await execute(apiToken, email, promptFile); // Pass the promptFile to execute function } finally { console.info('COMPLETED', new Date()); console.info('EXECUTION ELAPSED', diffInMinutesAndSeconds(start, new Date())); } try { console.info('START DOWNLOAD', start); await download(apiToken); } finally { console.info('TOTAL ELAPSED', diffInMinutesAndSeconds(start, new Date())); } } catch (error) { console.error('⛔ Error during execution:', error.stack || error); } } // Modify the execute function to accept promptFile as a parameter async function execute(apiToken, email, promptFile) { const accounts = await fetchAccounts(apiToken); console.info(`Configured Google Flow API accounts (${Object.keys(accounts).length}):`, Object.keys(accounts).join(', ')); if (Object.keys(accounts).length <= 0) { console.error(`⛔ No configured Google Flow accounts found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (!accounts[email]) { console.error(`⛔ Account ${email} not found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (accounts[email].health && accounts[email].health !== 'OK') { console.error(`⛔ Account ${email} health is '${accounts[email].health}'. Please resolve and update the account, see https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } const promptData = await fs.readFile(promptFile, 'utf8'); const prompts = JSON.parse(promptData); console.log(`Total number of prompts to process`, prompts.length); let warnings = []; // Parameters accepted by this script for the omni-flash POST /videos endpoint. // See https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos for the full parameter set. const supportedParams = [ 'prompt', 'model', 'aspectRatio', 'duration', 'resolution', 'count', 'startImage', 'endImage', ...imageRefKeys, ...characterKeys, 'referenceVideo_1', 'startFrameIndex_1', 'endFrameIndex_1', 'referenceAudio_1', 'referenceAudio_2', 'referenceAudio_3', 'referenceAudio_4', 'referenceAudio_5' ]; const audioRefKeys = ['referenceAudio_1', 'referenceAudio_2', 'referenceAudio_3', 'referenceAudio_4', 'referenceAudio_5']; const invalidKeys = (prompt) => Object.keys(prompt).filter(key => !key.startsWith('__') && !supportedParams.includes(key)) // Validate a local file path reference (skip already-uploaded mediaGenerationId strings). const looksLikePath = (ref) => ref && (ref.startsWith('./') || (ref.includes('.') && !ref.startsWith('user:'))); for (let i = 1; i <= prompts.length; i++) { const prompt = prompts[i - 1]; const { prompt: text, referenceVideo_1, duration, startImage, endImage } = prompt; const validateFile = async (file, allowedExts) => { if (looksLikePath(file)) { try { await fs.access(file); } catch { warnings.push(`⚠️ File '${file}' does not exist. Prompt ${i}`); } const ext = file.split('.').pop().toLowerCase(); if (!allowedExts.includes(ext)) warnings.push(`⚠️ File ${file} extension ${ext} not supported. Prompt ${i}`); } }; const notSupported = invalidKeys(prompt); if (notSupported.length) warnings.push(`⚠️ Following params not supported: ${notSupported.join(',')}. Prompt ${i}`); if (!text) warnings.push(`⚠️ prompt is required. Prompt ${i}`); // V2V edit (referenceVideo_1) does not accept duration — output matches the trim window. if (referenceVideo_1 && duration) warnings.push(`⚠️ duration is not accepted with referenceVideo_1 (V2V edit). Prompt ${i}`); if (endImage && !startImage) warnings.push(`⚠️ endImage requires startImage (end-frame-only is not supported). Prompt ${i}`); // Start/end frames (I2V, I2V-FL) are the only input in that mode — the API rejects anything alongside them. if (startImage || endImage) { if (referenceVideo_1) warnings.push(`⚠️ startImage/endImage cannot be combined with referenceVideo_1 (V2V edit). Prompt ${i}`); if ([...imageRefKeys, ...characterKeys].some(k => prompt[k])) warnings.push(`⚠️ startImage/endImage cannot be combined with referenceImage_* or character_*. Prompt ${i}`); if (audioRefKeys.some(k => prompt[k])) warnings.push(`⚠️ startImage/endImage cannot be combined with referenceAudio_*. Prompt ${i}`); } // A voice needs a referenceImage_* or character_* to attach to (or a V2V edit) — the API rejects referenceAudio_* on its own. // With start/end frames the check above already applies. if (!startImage && !endImage && !referenceVideo_1 && audioRefKeys.some(k => prompt[k]) && ![...imageRefKeys, ...characterKeys].some(k => prompt[k])) warnings.push(`⚠️ referenceAudio_* requires a referenceImage_* or character_* (or referenceVideo_1 for a V2V edit). Prompt ${i}`); await Promise.all([ validateFile(referenceVideo_1, supportedVideoExtensions), ...['startImage', 'endImage', ...imageRefKeys].map(k => validateFile(prompt[k], supportedImageExtensions)) ]); } if (warnings.length > 0) { warnings.forEach(warning => console.warn(warning)); console.error(`⛔ Execution stopped due to warnings.`); process.exit(1); } for (let i = 0; i < prompts.length; i++) { const prompt = prompts[i]; while (true) { const responseCode = await submitVideo(apiToken, email, prompt, i + 1); if (responseCode == 429 || responseCode == 503) await sleep(SLEEP_429); else if (responseCode == 402) { process.exit(1); } else break; } } } // Utility function to check if a file exists async function fileExists(path) { try { await fs.access(path); return true; } catch { return false; } } // Function to prompt user input async function promptUser(query) { const rl = readline.createInterface({ input: process.stdin, output: process.stdout }); return new Promise((resolve) => rl.question(query, answer => { rl.close(); resolve(answer); })); } function diffInMinutesAndSeconds(date1, date2) { const diffInSeconds = Math.floor((date2 - date1) / 1000); return `${Math.floor(diffInSeconds / 60)} minutes ${diffInSeconds % 60} seconds`; }; main(); ``` </details> ### Contoh Video di bawah adalah hasil asli Gemini Omni Flash yang dibuat lewat Google Flow API ini — `model: "omni-flash-1.2"` dan `model: "omni-flash"`, extend, suara, referensi, karakter, dan edit V2V. ###### Extend Omni 1.2 — video 10 detik diperpanjang dua kali menjadi 30 detik, dengan dua suara {: .no_toc #omni-12-extend--a-10-second-video-extended-twice-to-30-seconds-with-two-voices } <video poster="https://media.useapi.net/articles/2026-06-15-omni-flash-bash/261106-google-flow-omni-1-2-magician-extended-30s-web-poster.jpg" controls width="100%" style="max-width:640px;border-radius:8px"> <source src="https://media.useapi.net/articles/2026-06-15-omni-flash-bash/261106-google-flow-omni-1-2-magician-extended-30s-web.mp4" type="video/mp4"> </video> Dari [Google Flow: Omni 1.2 Flash, 15-Second Videos, and Extend with Voices](/blog/261106) (bahasa Inggris) — `omni-flash-1.2` untuk 10 detik pertama, lalu dua panggilan `POST /videos/extend` dengan `referenceAudio_1`. ###### Edit V2V — mengubah gaya MP4 hasil upload menjadi kartun, dengan gerakan dan framing yang sama {: .no_toc #v2v-edit--restyle-an-uploaded-mp4-into-a-cartoon-same-motion-and-framing } <video poster="https://media.useapi.net/blog/2026-05-20-260520/google-flow-edit-video-poster.jpg" controls width="100%" style="max-width:640px;border-radius:8px"> <source src="https://media.useapi.net/blog/2026-05-20-260520/google-flow-edit-video.mp4" type="video/mp4"> </video> Dari [Google Flow: Gemini Omni Flash](/blog/260520) (bahasa Inggris) — edit dengan `referenceVideo_1`. ###### @-mention inline — video noir R2V dengan @character_1, @referenceImage_1, @referenceImage_2 dan suara kustom {: .no_toc #inline--mentions--r2v-noir-video-with-character_1-referenceimage_1-referenceimage_2-and-a-custom-voice } <video poster="https://media.useapi.net/blog/2026-06-09-260609/noir-shot-1-poster.jpg" controls width="100%" style="max-width:640px;border-radius:8px"> <source src="https://media.useapi.net/blog/2026-06-09-260609/noir-shot-1.mp4" type="video/mp4"> </video> Dari [Google Flow: Inline @-mentions](/blog/260609) (bahasa Inggris) — penanda `@`-mention inline yang mengaitkan setiap referensi. ###### Karakter + edit V2V — memasukkan dua karakter yang bisa dipakai ulang ke dalam video noir {: .no_toc #characters--v2v-edit--composites-two-reusable-characters-into-the-noir-video } <video poster="https://media.useapi.net/blog/2026-06-09-260609/edit-1-poster.jpg" controls width="100%" style="max-width:640px;border-radius:8px"> <source src="https://media.useapi.net/blog/2026-06-09-260609/edit-1.mp4" type="video/mp4"> </video> Dari [Google Flow: Inline @-mentions](/blog/260609) (bahasa Inggris) — edit V2V dengan `referenceVideo_1` dan `@character_*` inline. Lihat juga [Reusable Voices and Characters](/blog/260605) (bahasa Inggris) untuk alur setup suara dan karakter. ### Pertanyaan yang sering diajukan - **Apa itu Gemini Omni Flash?** Lewat useapi.net Anda menjalankan Gemini Omni Flash, [model video dengan audio bawaan](https://deepmind.google/models/model-cards/gemini-omni-flash/) milik Google di [Google Flow](https://flow.google.com), dengan mengisi `model: "omni-flash-1.2"` (Omni 1.2 Flash) atau `model: "omni-flash"` (Omni 1.1 Flash) di [Google Flow API](/docs/api-google-flow-v1). Berbeda dari model video bisu, model ini membuat soundtrack, narasi, dialog, dan suasana sebagai bagian dari video yang sama, dan menerima referensi gambar, video, dan audio plus karakter yang bisa dipakai ulang. - **Apa beda Omni Flash dengan Veo 3.1?** Lewat useapi.net keduanya berjalan di Google Flow API yang sama, dipilih dengan field `model`. Veo adalah mesin text-to-video dan image-to-video biasa dengan fidelitas lebih tinggi, sedangkan Omni Flash membuat audio sendiri dan menerima banyak referensi, dengan edit video-ke-video (`referenceVideo_1`), beberapa suara per video, karakter yang bisa dipakai ulang di durasi berapa pun, dan video yang lebih panjang daripada Veo. Lihat [Mode referensi](#reference-modes) untuk batas persisnya. - **Bisakah memakai suara saya sendiri, video referensi, atau audio referensi?** Lewat useapi.net, bisa. Buat narasi dengan suara sistem bawaan atau suara kustom dari [POST /voices](/docs/api-google-flow-v1/post-google-flow-voices), dikirim sebagai `referenceAudio_1..5`, dan upload MP4 dengan [POST /assets](/docs/api-google-flow-v1/post-google-flow-assets-email) untuk mengeditnya sebagai `referenceVideo_1` (V2V). Lihat [Mode referensi](#reference-modes) dan [Suara & karakter](#voices--characters) untuk batas setiap mode. - **Apakah ada API Omni Flash resmi?** Lewat useapi.net, Omni 1.1 Flash jauh lebih murah daripada di API milik Google sendiri: satu video 720p 8 detik berbiaya $0,10 di Google AI Ultra $199,99, dibanding $0,81 di [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) resmi, yang menjual model ini per detik sejak 30 Juni 2026 (per November 2026). Model ini berjalan lewat endpoint REST standar di langganan situs Google Flow Anda. - **Bisakah Omni Flash membuat video lebih dari 10 detik?** Lewat useapi.net, bisa: Omni 1.2 Flash (`model: "omni-flash-1.2"`) membuat hingga 15 detik dalam satu panggilan, dan [POST /videos/extend](/docs/api-google-flow-v1/post-google-flow-videos-extend) menambahkan hingga 10 detik setiap kali dengan suara, seharga $0,19 untuk video 720p 8 detik di Google AI Ultra $199,99, dibanding $0,56 di [API milik Google sendiri](https://cloud.google.com/blog/products/ai-machine-learning/gemini-omni-1-2-flash-generally-available) (per November 2026). Semua batas durasi dan harga di Google Flow dan Google Vids ada di [Cara Memakai Gemini Omni 1.2 Flash API](/docs/articles/gemini-omni-1-2-flash-api-id). - **Apakah saya harus menyelesaikan captcha?** Lewat useapi.net Anda tidak pernah menyelesaikannya sendiri. Google Flow meminta reCAPTCHA untuk setiap video dan setiap suara baru, dan worker useapi.net menyelesaikannya otomatis: akun Google Flow pertama Anda mendapat 300 penyelesaian gratis dengan key AntiCaptcha, CapSolver dan EzCaptcha milik kami, dan setelah itu Anda menambahkan key penyedia sendiri dengan [POST /accounts/captcha-providers](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers). [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters) tidak butuh captcha. ### Kesimpulan Kunjungi <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Server Discord</a> atau <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Channel Telegram</a> kami untuk pertanyaan dan masalah dukungan. Lihat [repo GitHub](https://github.com/useapi/google-flow-api) kami berisi contoh kode. Asisten AI juga bisa bekerja dengan Google Flow untuk Anda: [MCP server Google Flow](/docs/api-google-flow-v1/mcp) yang di-hosting memungkinkan Claude Code, Cursor dan VS Code mengobrol dengan Google Flow Agent, yang membuat gambar dan video di akun Anda. ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/omni-flash-bash-ja === Document URL: https://useapi.net/docs/articles/omni-flash-bash-ja --- layout: default title: "Gemini Omni Flash の使い方:Google Flow API で音声付きの AI 動画を生成する" seo_title: "Gemini Omni Flash API の使い方:音声付き動画を curl で生成" description: "useapi.net の Google Flow API で Gemini Omni Flash を使う方法をコード付きで解説。Omni 1.2 と 1.1 で参照画像、キャラクター、声、V2V 編集を使い、一括生成スクリプトも紹介。" keywords: [Gemini Omni Flash, Omni 1.2 Flash, Omni Flash API, omni-flash-1.2, Google Flow API, Omni Flash 使い方, Gemini Omni Flash API, 音声付き動画, AI 動画生成, 動画 延長 API, 動画編集 API, 声, キャラクター, audio-native video, extend video, voices, characters, video editing, 日本語チュートリアル, Japanese tutorial, curl] parent: Articles nav_exclude: true lang: ja translation_key: omni-flash date: 2026-06-15 last_modified: 2026-11-12 nav_order: 830 repo: https://github.com/useapi/google-flow-api --- ## Gemini Omni Flash の使い方:Google Flow API で音声付きの AI 動画を生成する {: .no_toc #how-to-generate-audio-native-ai-video-with-gemini-omni-flash-via-the-google-flow-api } 8分で読めます • 2026年6月15日(2026年11月12日更新) useapi.net はサードパーティの API です。Google とは提携しておらず、Google の承認も受けていません。 ## 目次 {: .no_toc .text-delta #table-of-contents } ### はじめに [Gemini Omni Flash](https://deepmind.google/models/model-cards/gemini-omni-flash/) は、useapi.net の [Google Flow API](/docs/api-google-flow-v1) を通して、`curl` 1回で音声付きの AI 動画を作ります。声の同期、キャラクター、動画から動画への編集にも対応し、使うのはお使いの [Google Flow](https://flow.google.com) の Web サイトのプランです([Google AI](https://gemini.google/subscriptions/):Omni 1.1 Flash は Plus、Pro、Ultra、Omni 1.2 Flash はすべてのプランで使え、無料アカウントでは10秒まで)。10秒・720p の動画は Google AI Ultra $199.99 で $0.12 で、公式の [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) では $1.01 です(2026年11月時点)。Google Cloud プロジェクトも API キーも必要ありません。同じプランで [Google Vids](/docs/api-google-vids-v1) でも Omni の動画を作れ、こちらは Flow クレジットを使いません。 Google Flow の画面ではこのモデルは Omni 1.1 Flash と表示され、API の値は `model: "omni-flash"` です。Google が2026年11月5日に公開した Omni 1.2 Flash は別の値 `model: "omni-flash-1.2"` で、3〜15秒の任意の長さに対応し、クレジットは秒単位で、1回最大10秒の[動画の延長](#extend-a-video-with-omni-12)もこのモデルで行います。`omni-flash` を送るコードは引き続き 1.1 を使います。15秒の動画、声を付けた延長、Google Flow と Google Vids での動画1本あたりの料金については、[Gemini Omni 1.2 Flash API の使い方](/docs/articles/gemini-omni-1-2-flash-api-ja)を参照してください。 Omni Flash は Veo と[同じ Google Flow API](/docs/api-google-flow-v1) で、`model: "omni-flash-1.2"` または `model: "omni-flash"` という1つのフィールドで選びます。ただし、モデルの性格は違います。Veo がテキストから動画を作る強力なエンジンなのに対し、Omni Flash は音声を最初から生成し、参照素材を豊富に受け付けます。 - 音は動画の一部として生成されます。ナレーション、セリフ、環境音が同じモデルから出てくるので、後から付け足す必要はありません。 - 声は、内蔵の30種類のシステムの声のプリセットに加え、ご自身のセリフと演技の指示から作るカスタムの声も使え、`referenceAudio_1..5` で渡します。 - 画像と動画の参照として、参照画像から動画(R2V)には Omni 1.2 Flash で最大10枚(Omni 1.1 Flash では7枚)の参照画像を使え、`referenceVideo_1` でアップロードした動画や生成した動画を動画から動画(V2V)で編集できます。 - 再利用できるキャラクターでは、参照画像と声を名前付きのキャラクターにまとめ、複数の動画で使い回せます。 - 長い動画も作れます。Omni 1.1 Flash は4、6、8、10秒、Omni 1.2 Flash は3〜15秒の任意の長さで(Veo は最長 `8`)、Omni 1.2 は1回最大10秒ずつ動画を延長できます。 このガイドでは、コピーしてそのまま使える `curl` で2回の呼び出しの流れを示し、Omni Flash ならではの参照モードを紹介したあと、プロンプトのリストから一括生成する Node.js スクリプトを載せます。テキストから動画を作るだけなら、姉妹編の [Veo 3.1 のチュートリアル](/docs/articles/google-flow-bash-ja)を参照してください。 ### 対応モデル このガイドでは、Google の音声付き動画モデル Omni 1.1 Flash(`model: "omni-flash"`)と Omni 1.2 Flash(`model: "omni-flash-1.2"`)を使います。Omni 1.1 のクレジット数は動画の長さで決まります。 | 長さ | 動画1本のクレジット | |----------|------------------------| | 4秒 | 7 | | 6秒 | 10 | | 8秒 | 12 | | 10秒 | 15 | | V2V 編集 | 20 | これはデフォルトの `720p` での料金です。`resolution: "360p"` を渡すと約半分になり、長さ順に4、5、6、7クレジット、V2V 編集は10クレジットです。360p の動画は、あとから [POST /videos/upscale](/docs/api-google-flow-v1/post-google-flow-videos-upscale) で 720p にできます。 Omni 1.2 Flash(`model: "omni-flash-1.2"`)は3〜15の任意の整数秒を受け付け、秒単位で料金がかかります。料金はどのプランでも同じです。 | 長さ | 720p | 360p | |--------|------|------| | 3秒 | 9 | 3 | | 8秒 | 24 | 8 | | 10秒 | 30 | 10 | | 15秒 | 60 | 20 | 10秒までは 720p で1秒3クレジット、360p で1クレジットで、10秒を超える分は1秒あたり2倍になります。V2V 編集は編集した長さの動画と同じ料金で、1.2 では最大15秒の動画を編集できます。無料の Google アカウントでも、10秒以下の動画なら 1.2 を使えます。 Omni Flash は [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) で5つのモードに対応しています。テキストから動画(T2V)、Omni 1.2 Flash で最大10枚(Omni 1.1 Flash では7枚)の `referenceImage_1..10` を使う参照画像から動画(R2V)、`startImage` の開始フレームから作る画像から動画(I2V)、`startImage` と `endImage` の開始・終了フレームの間をつなぐ画像から動画(I2V-FL)、そして `referenceVideo_1` でアップロードした MP4 を編集する動画から動画(V2V)です。詳しくは下の[参照モード](#reference-modes)を参照してください。 ### 料金 Omni 1.1 Flash には有料の Google AI のプラン(Plus、Pro、Ultra)が必要で、Omni 1.2 Flash は無料アカウントでも10秒まで使えます。useapi.net が動画ごとに料金を取ることはありません。動画は長さに応じて Flow クレジットを使います([対応モデル](#supported-model)を参照)。各プランでの動画1本の料金と公式の Gemini API との比較は、[Google Flow の料金表](/docs/api-google-flow-v1#pricing)にあります。 Google AI のプランには、[Google Vids](https://docs.google.com/videos) の月間利用枠も付いています。Google Vids は Gemini Omni 1.2 Flash で最長15秒の動画を作り([Google の発表](https://workspaceupdates.googleblog.com/2026/11/gemini-omni-12-flash-now-in-vids-with-15second-generations-and-improved-quality.html))、Flow クレジットは使いません。Ultra $199.99(Google の呼び方では Ultra 20x)では月10,000秒で、1080p の10秒の動画が約1,000本です。これは Flow の25,000クレジットで作れる Omni 1.1 Flash の10秒の動画約1,666本(720p の Omni 1.2 Flash なら約833本)とは別に使えます。この秒数は Google のファミリー プランのメンバー全員で共有されます。ほかのプランの利用枠はもっと少なく(Google の [Google Vids の Gemini](https://support.google.com/docs/answer/15609411?hl=ja) のページを参照)、当社がテストした無料アカウントではゼロでした。[Google Vids API](/docs/api-google-vids-v1) はこの利用枠を CAPTCHA なしで使います。アカウントは [Google Vids のセットアップ](/docs/start-here/setup-google-vids)で接続します。 ### 2回の API 呼び出しで動画を生成する useapi.net の [API トークン](/docs/start-here/setup-useapi)と、接続済みの [Google Flow アカウント](/docs/start-here/setup-google-flow)が必要です。下の Omni 1.1 Flash の例には有料の Google AI のプラン(Plus、Pro、Ultra)が必要です(Omni 1.2 Flash は無料アカウントでも10秒まで動きます)。動画のジョブは非同期です。`async: true` を渡すと作成の呼び出しはすぐに `jobid` を返すので、動画ができるまでポーリングします。 1. ジョブを送信する — `model: "omni-flash"` を指定して `POST https://api.useapi.net/v1/google-flow/videos`: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A lighthouse keeper narrates the coming storm, waves crashing below", "model": "omni-flash", "aspectRatio": "landscape", "duration": 10, "async": true }' ``` Omni Flash は音声も生成するモデルなので、灯台守のナレーションと打ち寄せる波の音をプロンプトだけから作ります。音声のパラメーターは必要ありません。非同期モードでは、応答はすぐに `201 Created` で返り、小文字の `jobid` と `status: "created"` が入っています。 ```json { "jobid": "j1731859234567v-u12345-email:jo***@gmail.com-bot:google-flow", "type": "video", "status": "created", "created": "2026-06-15T12:34:56.789Z", "request": { "async": true, "prompt": "A lighthouse keeper narrates the coming storm, waves crashing below", "model": "omni-flash", "aspectRatio": "landscape", "duration": 10 } } ``` 2. 結果をポーリングする — `GET https://api.useapi.net/v1/google-flow/jobs/{jobId}`: ```bash curl "https://api.useapi.net/v1/google-flow/jobs/JOBID" \ -H "Authorization: Bearer $USEAPI_TOKEN" ``` `status` は `created` → `started` → `completed` と進みます。`completed` になると、完成した MP4 が `response.media[].videoUrl` に入ります(1つのプロンプトで `count > 1` を指定すると、動画ごとに1つずつエントリーが返ります)。 ```json { "jobid": "j1731859234567v-...", "type": "video", "status": "completed", "response": { "media": [ { "mediaGenerationId": "user:12345-email:6a6f...-video:a1d95d21-...", "videoUrl": "https://flow-content.google/video/a1d95d21-...?Expires=...", "thumbnailUrl": "https://flow-content.google/image/a1d95d21-...?Expires=..." } ], "remainingCredits": 18760 } } ``` Omni Flash は通常60〜180秒で完了します。署名付きの `videoUrl` は約6時間有効なので、早めにダウンロードしてください。ポーリングしたくない場合は、作成のボディに `replyUrl` を渡すと、ジョブの完了時に Webhook で通知を受け取れます。 ### 参照モード Omni Flash の最大の特長は、参照として渡せる素材の多さです。参照はすべて [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email) のアップロード用エンドポイントから取得します(キャラクターは [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters) から)。アップロードの応答では、参照 ID が `mediaGenerationId.mediaGenerationId` に入れ子で入っており、この入れ子の文字列を渡します。`omni-flash` が受け付けるモードは次のとおりです([POST /videos](/docs/api-google-flow-v1/post-google-flow-videos#references) のドキュメントより)。 | モード | パラメーター | Omni Flash の上限 | |------|--------------|------------------| | 参照画像から動画(R2V) | `referenceImage_1..10` | `omni-flash-1.2` で画像最大10枚、`omni-flash` で7枚 | | 画像から動画(I2V) | `startImage` | 開始フレーム1枚 | | 画像から動画、開始・終了(I2V-FL) | `startImage` + `endImage` | 2枚のフレームのみ、ほかの参照は不可 | | 動画から動画の編集(V2V) | `referenceVideo_1`(+ 任意で `startFrameIndex_1` / `endFrameIndex_1`) | アップロードした MP4 1本 | | キャラクター | `character_1..10`([POST /characters](/docs/api-google-flow-v1/post-google-flow-characters) から) | `referenceImage_*` と合わせて `omni-flash-1.2` で計10、`omni-flash` で7 | | 声のナレーション | `referenceAudio_1..5` | 最大5(R2V)/ 最大3(V2V 編集) | 参照画像から動画(R2V)では、1枚以上の画像をアップロードし、`referenceImage_1`、`referenceImage_2` … として渡します(`_4`〜`_7` の枠は Omni Flash のみ)。参照画像は `startImage`/`endImage` と組み合わせられません。 ```bash # 1. Upload a reference image — the id is nested one level deep: curl -X POST "https://api.useapi.net/v1/google-flow/assets/john%40gmail.com" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: image/jpeg" \ --data-binary @subject.jpeg # Response: { "mediaGenerationId": { "mediaGenerationId": "user:12345-email:...-image:..." }, ... } # 2. Generate, narrated by a system voice curl -X POST "https://api.useapi.net/v1/google-flow/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model": "omni-flash", "prompt": "the subject walks toward camera and introduces herself", "duration": 8, "referenceImage_1": "user:12345-email:...-image:...", "referenceAudio_1": "Kore" }' ``` 動画から動画の編集(V2V)では、`Content-Type: video/mp4` で MP4 を [POST /assets](/docs/api-google-flow-v1/post-google-flow-assets-email) にアップロードし、返ってきた ID を `referenceVideo_1` として渡すと、その動画を編集できます。これは Omni Flash のみの機能で、リクエストは V2V モードになります。`duration` は受け付けません(出力の長さは入力のトリム範囲と同じで、`omni-flash` で最大10秒、`omni-flash-1.2` で最大15秒)。元の動画は、24 fps の仮想タイムライン上で `startFrameIndex_1`(0〜239)と `endFrameIndex_1`(1〜240、240 = 10秒)でトリムでき、`omni-flash-1.2` では359と360(15秒)まで指定できます。 ```bash curl -X POST "https://api.useapi.net/v1/google-flow/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model": "omni-flash", "prompt": "restyle the scene as a rainy neon-lit night, add ambient city sound", "referenceVideo_1": "user:12345-email:...-video:...", "startFrameIndex_1": 0, "endFrameIndex_1": 240, "async": true }' ``` プロンプトには、渡した枠を指すインラインの `@` マーカーも書けます。たとえば `@referenceImage_1`、`@character_1`、`@referenceAudio_1` です。マーカーは任意で、それぞれに対応するボディのパラメーターが必要です(`@referenceVideo_*` はインラインでは使えないので、ボディのフィールドとして渡します)。詳しくは [Inline @-mention markers](/docs/api-google-flow-v1/post-google-flow-videos#inline--mention-markers-optional) を参照してください。 ### 声とキャラクター Omni Flash の音声と人物の機能は、短いセットアップの呼び出し2つで使えます。 カスタムの声は、[POST /voices](/docs/api-google-flow-v1/post-google-flow-voices) で、30種類のシステムのプリセットの1つをもとに、ご自身の `dialog` と `voicePerformance` を加えて保存します。応答の `voice` フィールドは参照 ID で、これを [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) に `referenceAudio_1..5` として渡します。 ```bash curl -X POST "https://api.useapi.net/v1/google-flow/voices" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "john@gmail.com", "voice": "Achernar", "dialog": "Welcome to the demo.", "voicePerformance": "Cheerful, energetic delivery", "displayName": "Cheerful Narrator" }' # Response: { "voice": "user:12345-email:...-voice:...-mid:...", ... } ``` `referenceAudio_*` の各枠には、システムの声の名前(大文字・小文字は区別せず、`Aoede`、`Kore`、`Puck`、`Zephyr` など30種類のプリセットのいずれか)か、上の呼び出しで作ったユーザーの声の ID を渡せます。声の作成には reCAPTCHA が必要です(自動で解決されます。[よくある質問](#frequently-asked-questions)を参照)。 再利用できるキャラクターは、[POST /characters](/docs/api-google-flow-v1/post-google-flow-characters) で、参照画像1〜2枚と任意の声を名前付きのキャラクターにまとめたものです。応答の `character` フィールドを `character_1..10` として渡します。 ```bash curl -X POST "https://api.useapi.net/v1/google-flow/characters" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "displayName": "Carol", "imageReference_1": "user:12345-email:...-image:abc123...", "voice": "user:12345-email:...-voice:...-mid:..." }' # Response: { "character": "user:12345-email:...-character:...-imgs:1-voice:...", ... } ``` Omni Flash では、キャラクターはどの長さでも使え、画像の参照枠の合計10枚を `referenceImage_*` と共有します(`referenceImages.length + Σ(character.imgs) ≤ 10`, Omni 1.1: 7)。`POST /characters` には CAPTCHA は不要です。キャラクターと声は Veo でも使えますが、上限はより厳しくなります(画像3枚、声1つ、8秒のみ)。詳しくは [What can use a character?](/docs/api-google-flow-v1/post-google-flow-characters#what-can-use-a-character) を参照してください。 ### Omni 1.2 で動画を延長する [POST /videos/extend](/docs/api-google-flow-v1/post-google-flow-videos-extend) は、30秒未満の動画に Omni 1.2 Flash で1回3〜10秒を追加します。声、参照画像、キャラクターを最大3つまで指定でき、1本のつながった動画を返します(有料プランのみ)。[Gemini Omni 1.2 Flash API の使い方](/docs/articles/gemini-omni-1-2-flash-api-ja#flow-walkthrough)の手順では、10秒の動画を2人の声で2回延長して30秒にしています。その動画は[下の例](#examples)にあります。 ### スクリプトで一括生成する 良いテイクを見つけるには何度も試す必要があり、それを手作業で行うのは面倒です。下の Node.js スクリプトは、`prompts.json` からプロンプトのリストを読み込み、参照画像、開始・終了フレーム、元の動画をアップロードし、`character_*` の ID と `resolution` はそのまま渡します。各ジョブを `model: "omni-flash"` の非同期モードで送信し、ポーリングして、完成した MP4 をすべてダウンロードします。まとめてキューに入れておき、あとで良いものだけを選べます。開始フレームなしの終了フレームのように、API が拒否する組み合わせは送信前に警告を出して止まります。 [Node.js](https://nodejs.org) v21 以降が必要です。`prompts.json` と `omni-flash.mjs` を同じフォルダーに置き、`node ./omni-flash.mjs API_TOKEN EMAIL` を実行します。`API_TOKEN` は useapi.net の [API トークン](/docs/start-here/setup-useapi)、`EMAIL` は接続済みの [Google Flow アカウント](/docs/start-here/setup-google-flow)のメールアドレスです。スクリプトはメールアドレスからアカウントを自動で探し、送信前にその `health` フィールドを確認します。 クローンしてローカルで実行したい場合は、`omni-flash.mjs` と `prompts.json` の完全版が GitHub の [`useapi/google-flow-api`](https://github.com/useapi/google-flow-api/tree/main/omni-flash) にあります。 Claude Code や Codex を使っているなら、[omni-flash-video エージェントスキル](https://github.com/useapi/google-flow-api/tree/main/skills/omni-flash-video)でこの作業をすべてエージェントに任せられます。作りたい動画を説明して画像の場所を伝えると、画像のアップロード、リクエストの作成、完了の待機、`.mp4` の保存まで行います。インストールは `npx skills add useapi/google-flow-api --skill omni-flash-video` です。 <details markdown="block"> <summary>`prompts.json` を表示</summary> ```json [ { "prompt": "Audio-native text-to-video. By default model omni-flash with a landscape 8-second clip will be used." }, { "duration": 10, "prompt": "A 10-second clip (omni-flash only). Omni Flash is audio-native, so narration, dialogue and sound come from the prompt. To pin a specific voice, add referenceAudio_1 together with a referenceImage_* or character_*, as in the next prompt." }, { "duration": 8, "referenceImage_1": "./subject.jpeg", "referenceAudio_1": "Kore", "prompt": "Reference-to-video (R2V): the uploaded image is a reference, narrated by 'Kore'. Up to 7 referenceImage_* on omni-flash, 10 on omni-flash-1.2." }, { "duration": 8, "startImage": "./first_image.jpeg", "endImage": "./last_image.jpeg", "prompt": "Image-to-video with a start frame (startImage) and an end frame (endImage). The two frames are the only input — no referenceImage_*, character_* or referenceAudio_* alongside them." }, { "referenceVideo_1": "./source.mp4", "startFrameIndex_1": 0, "endFrameIndex_1": 240, "prompt": "Video-to-video edit (V2V): omni-flash restyles the uploaded MP4. No duration here — output matches the trim window (max 10 s). For all parameters see https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos" } ] ``` </details> <details markdown="block"> <summary>`omni-flash.mjs` スクリプトを表示</summary> ```javascript /* Script version 1.3, November 11, 2026 Script to batch-generate audio-native videos with Gemini Omni Flash using the Google Flow API by useapi.net Uses the POST /videos endpoint in async mode (model: omni-flash by default, or omni-flash-1.2 per prompt) and polls GET /jobs/{jobId}. For more details visit https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos Installation Instructions: ========================== You need Node.js v21 or newer installed to run this script. Download and install Node.js from: - Windows, macOS, Linux: https://nodejs.org/ After installation, verify by running the following command in a terminal: node -v Running the Script: =================== Usage: node omni-flash.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE] Replace API_TOKEN with your actual useapi.net API token, see https://useapi.net/docs/start-here/setup-useapi Replace EMAIL with configured Google Flow email account, see https://useapi.net/docs/start-here/setup-google-flow If optional PROMPTS_FILE not provided prompts.json will be used. Example: -------- node omni-flash.mjs user:1234-abcdefhijklmnopqrstuv my@email.com This command executes the script using API token user:1234-abcdefhijklmnopqrstuv with my@email.com Google Flow account email. Changelog: ========== - June 15, 2026: Initial release. - September 11, 2026: Adds resolution, startImage / endImage (start and end frames, local files uploaded for you) and character_1..7. Accepts .jpg and upper-case file extensions. Stops with a warning before submitting combinations the API rejects, such as endImage without startImage or referenceAudio_* on its own. A prompt whose local startImage, endImage, referenceImage_* or referenceVideo_1 file fails to upload is skipped and logged to omni-flash_errors.txt instead of being submitted without it. Saves a downloaded video under its final name only once it has been fully received, so a failed download leaves no partial MP4 for the next run to skip as "already exists". - November 11, 2026: referenceImage_8..10 and character_8..10: omni-flash-1.2 takes up to 10 references (omni-flash 7). */ import readline from 'node:readline'; import fs from 'fs/promises'; import path from 'path'; import { writeFile } from 'node:fs/promises'; import { Readable } from 'node:stream'; // Constants const RESULTS_FILE = 'omni-flash_results.txt'; const ERRORS_FILE = 'omni-flash_errors.txt'; const DEFAULT_PROMPTS_FILE = 'prompts.json'; const MODEL = 'omni-flash'; // Reference slots: up to 10 on omni-flash-1.2, 7 on omni-flash, 3 on Veo (referenceImage_* and character_* together). const imageRefKeys = Array.from({ length: 10 }, (_, i) => `referenceImage_${i + 1}`); const characterKeys = Array.from({ length: 10 }, (_, i) => `character_${i + 1}`); const SLEEP_429 = 30 * 1000; // in milliseconds const SLEEP_POLL = 15 * 1000; // in milliseconds const urlAccounts = 'https://api.useapi.net/v1/google-flow/accounts'; const urlVideos = 'https://api.useapi.net/v1/google-flow/videos'; const urlJobs = 'https://api.useapi.net/v1/google-flow/jobs/'; const urlUploadAsset = 'https://api.useapi.net/v1/google-flow/assets/'; // Google Flow accepts png, jpeg and webp images, and mp4 video (for omni-flash V2V edit). const supportedImageExtensions = ['png', 'jpg', 'jpeg', 'webp']; const supportedVideoExtensions = ['mp4']; // { filename: mediaGenerationId } const uploadedFiles = {}; // Utility to sleep for given milliseconds const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); // Function to fetch configured Google Flow API accounts async function fetchAccounts(apiToken) { const response = await fetch(urlAccounts, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.error(`⛔ Error fetching accounts (HTTP ${response.status}): ${response.statusText}`); process.exit(1); } return response.json(); } const elapsedTimeSec = (start) => (Date.now() - start) / 1000; // Map a file extension to the Content-Type required by POST /assets const contentTypeForExt = (ext) => ext === 'png' ? 'image/png' : ext === 'webp' ? 'image/webp' : ext === 'mp4' ? 'video/mp4' : 'image/jpeg'; async function uploadAsset(apiToken, email, filename) { // Check if already uploaded if (uploadedFiles.hasOwnProperty(filename)) return uploadedFiles[filename]; const startTime = Date.now(); console.log(`⬆️ Account ${email} uploading file…`, filename); const body = new Blob([await fs.readFile(filename)]); const fileExt = filename.split('.').pop().toLowerCase(); const response = await fetch(`${urlUploadAsset}${encodeURIComponent(email)}`, { method: 'POST', headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}`, 'Content-Type': contentTypeForExt(fileExt) }, body }); if (response.ok) { const json = await response.json(); // POST /assets returns the reference id nested as mediaGenerationId.mediaGenerationId const mediaGenerationId = json?.mediaGenerationId?.mediaGenerationId; console.log(`🆗 mediaGenerationId (${elapsedTimeSec(startTime)} sec)`, mediaGenerationId); uploadedFiles[filename] = mediaGenerationId; } else { console.error(`❗ Unable to upload file HTTP ${response.status} (${elapsedTimeSec(startTime)} sec)`, await response.text()); // Do not attempt to upload failed file again uploadedFiles[filename] = undefined; } return uploadedFiles[filename]; } async function submit(apiToken, url, body, index, prompt) { const createResponse = await fetch(url, { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiToken}` }, body }); const createBody = await createResponse.text(); // Async POST /videos returns 201 Created with a jobid to poll. if (createResponse.status == 201) { const json = JSON.parse(createBody); // 201 async payload uses lowercase "jobid"; sync 200 uses "jobId". Accept either. const jobId = json.jobid ?? json.jobId; if (jobId) { await fs.appendFile(RESULTS_FILE, `${jobId},#${index}:${prompt}\n`); console.log(`✅ jobId`, jobId); return 201; } else { const error = `No jobid found in HTTP 201 response`; console.log(`❓ ${error}`, createBody); await fs.appendFile(ERRORS_FILE, `${error},#${index}:${prompt}\n`); return 500; } } else { switch (createResponse.status) { case 429: console.log(`🔄️ Retry on HTTP ${createResponse.status}`, createBody); break; case 503: console.log(`🔄️ Service unavailable, retry on HTTP ${createResponse.status}`, createBody); break; case 400: console.log(`🛑 Rejected request (validation or content policy)`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${prompt}\n`); break; case 402: console.log(`🛑 No subscription / insufficient credits`, createBody); break; default: console.log(`❗ FAILED with HTTP ${createResponse.status}`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${prompt}\n`); } return createResponse.status; } } // Submit a single prompt to POST /videos with model omni-flash (or the prompt's own model) in async mode. // startImage = start frame (I2V), endImage = end frame (I2V-FL, requires startImage) — the frames are the only input; // referenceImage_1..10 = R2V image refs; character_1..10 = POST /characters ids (10 on omni-flash-1.2, 7 on omni-flash); // referenceVideo_1 = V2V edit (no duration); referenceAudio_1..5 = system voice name or POST /voices user-voice id; // resolution = 720p (default) or 360p; model = 'omni-flash' (Omni 1.1, the default) or 'omni-flash-1.2' (3–15 s, per-second credits). async function submitVideo(apiToken, email, prompt, index) { const { prompt: text, model = MODEL, aspectRatio, duration, resolution, count, startImage, endImage, referenceVideo_1, startFrameIndex_1, endFrameIndex_1, referenceAudio_1, referenceAudio_2, referenceAudio_3, referenceAudio_4, referenceAudio_5 } = prompt; console.log(`🚀 ${model} » Prompt #${index} • account ${email} …`); // Upload any local image/video files and swap the paths for their mediaGenerationId. const resolveRef = async (ref) => ref && (ref.startsWith('./') || ref.includes('.')) && [...supportedImageExtensions, ...supportedVideoExtensions].includes(ref.split('.').pop().toLowerCase()) ? await uploadAsset(apiToken, email, ref) : ref; const startImageId = await resolveRef(startImage); const endImageId = await resolveRef(endImage); const refImages = {}; for (const key of imageRefKeys) refImages[key] = await resolveRef(prompt[key]); const refVideo_1 = await resolveRef(referenceVideo_1); // A local file that failed to upload would be left out of the body, and the prompt would still be // generated (and charged) without it. Skip the prompt instead. uploadAsset remembers the failed file, // so a later prompt using it is skipped too, without another upload attempt. const failedUploads = [ ['startImage', startImage, startImageId], ['endImage', endImage, endImageId], ...imageRefKeys.map(key => [key, prompt[key], refImages[key]]), ['referenceVideo_1', referenceVideo_1, refVideo_1] ].filter(([, file, id]) => file && !id); for (const [param, file] of failedUploads) { console.error(`🛑 Prompt #${index} skipped: ${param} ${file} failed to upload`); await fs.appendFile(ERRORS_FILE, `Upload failed for ${param} ${file},#${index}:${text}\n`); } if (failedUploads.length) return; // V2V edit does not accept duration — output matches the trim window. const isV2V = !!refVideo_1; const body = JSON.stringify({ model, email, prompt: text, aspectRatio, duration: isV2V ? undefined : duration, resolution, count, startImage: startImageId, endImage: endImageId, ...refImages, ...Object.fromEntries(characterKeys.map(key => [key, prompt[key]])), referenceVideo_1: refVideo_1, startFrameIndex_1, endFrameIndex_1, referenceAudio_1, referenceAudio_2, referenceAudio_3, referenceAudio_4, referenceAudio_5, async: true }); return await submit(apiToken, urlVideos, body, index, text); } // Function to download videos async function download(apiToken) { if (! await fileExists(RESULTS_FILE)) return; try { const resultsContent = await fs.readFile(RESULTS_FILE, 'utf8'); const lines = resultsContent.trim().split('\n'); for (const line of lines) { const [jobId, prompt] = line.split(','); console.log(`👉 ${jobId}`); while (true) { const response = await fetch(`${urlJobs}${jobId}`, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.log(`🛑 Poll failed ${jobId} (HTTP ${response.status}):\n${prompt}\n`, await response.text()); break; } const jobBody = await response.json(); const { status, error, response: jobResponse } = jobBody; if (status == 'failed') { console.error(`🛑 FAILED ${jobId} (${error}):\n${prompt}\n`); break; } if (status == 'completed') { const media = jobResponse?.media ?? []; if (media.length == 0) console.error(`🛑 Completed but no media for ${jobId}:\n${prompt}\n`); // A single prompt with count > 1 returns multiple videos. for (let i = 0; i < media.length; i++) { const url = media[i]?.videoUrl; const videoFilename = `${jobId.replace(/[:*]/g, '_')}_${i + 1}.mp4`; try { await fs.access(videoFilename); console.log(`⚠️ ${videoFilename} already exists. Skipping download.`); continue; } catch { // File does not exist, proceed with downloading } if (url) { console.log(`✅ Downloading ${url} to ${videoFilename}`); // Stream into a temporary file and rename it once the whole video has arrived, so a download // that drops mid-stream leaves no partial file behind for the next run to skip as "already exists". const tempFilename = `${videoFilename}.part`; try { const videoResponse = await fetch(url); if (!videoResponse.ok) { console.error(`⛔ Unable to download ${jobId} (HTTP ${videoResponse.status}):\n${prompt}\n`, url); continue; } const stream = Readable.fromWeb(videoResponse.body); await writeFile(tempFilename, stream); await fs.rename(tempFilename, videoFilename); } catch (err) { await fs.rm(tempFilename, { force: true }); console.error(`⛔ Error during download: ${err}`); } } else console.error(`🛑 No videoUrl for ${jobId} media #${i + 1}:\n${prompt}\n`); } break; } console.log(`⌛ ${jobId} status (${status}) and is still in progress, waiting…`); await sleep(SLEEP_POLL); } } } catch (error) { console.log(`⛔ Error during download:`, error.stack || error); } } // Main function async function main() { const apiToken = process.argv[2]; const email = process.argv[3]; const promptFile = process.argv[4] || DEFAULT_PROMPTS_FILE; if (!apiToken || !email) { console.error('Usage: node omni-flash.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE]'); process.exit(1); } console.info('Script v1.3'); console.info('Node version is: ' + process.version); try { if (await fileExists(RESULTS_FILE)) { let user_input; while (!['y', 'n'].includes(user_input)) { user_input = (await promptUser(`❔ ${RESULTS_FILE} file detected. Do you want to download the results now? (y/n): `))?.toLowerCase(); if (user_input == 'y') { await download(apiToken); await fs.unlink(RESULTS_FILE); } } } const start = new Date(); try { console.info('START EXECUTION', start); await execute(apiToken, email, promptFile); // Pass the promptFile to execute function } finally { console.info('COMPLETED', new Date()); console.info('EXECUTION ELAPSED', diffInMinutesAndSeconds(start, new Date())); } try { console.info('START DOWNLOAD', start); await download(apiToken); } finally { console.info('TOTAL ELAPSED', diffInMinutesAndSeconds(start, new Date())); } } catch (error) { console.error('⛔ Error during execution:', error.stack || error); } } // Modify the execute function to accept promptFile as a parameter async function execute(apiToken, email, promptFile) { const accounts = await fetchAccounts(apiToken); console.info(`Configured Google Flow API accounts (${Object.keys(accounts).length}):`, Object.keys(accounts).join(', ')); if (Object.keys(accounts).length <= 0) { console.error(`⛔ No configured Google Flow accounts found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (!accounts[email]) { console.error(`⛔ Account ${email} not found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (accounts[email].health && accounts[email].health !== 'OK') { console.error(`⛔ Account ${email} health is '${accounts[email].health}'. Please resolve and update the account, see https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } const promptData = await fs.readFile(promptFile, 'utf8'); const prompts = JSON.parse(promptData); console.log(`Total number of prompts to process`, prompts.length); let warnings = []; // Parameters accepted by this script for the omni-flash POST /videos endpoint. // See https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos for the full parameter set. const supportedParams = [ 'prompt', 'model', 'aspectRatio', 'duration', 'resolution', 'count', 'startImage', 'endImage', ...imageRefKeys, ...characterKeys, 'referenceVideo_1', 'startFrameIndex_1', 'endFrameIndex_1', 'referenceAudio_1', 'referenceAudio_2', 'referenceAudio_3', 'referenceAudio_4', 'referenceAudio_5' ]; const audioRefKeys = ['referenceAudio_1', 'referenceAudio_2', 'referenceAudio_3', 'referenceAudio_4', 'referenceAudio_5']; const invalidKeys = (prompt) => Object.keys(prompt).filter(key => !key.startsWith('__') && !supportedParams.includes(key)) // Validate a local file path reference (skip already-uploaded mediaGenerationId strings). const looksLikePath = (ref) => ref && (ref.startsWith('./') || (ref.includes('.') && !ref.startsWith('user:'))); for (let i = 1; i <= prompts.length; i++) { const prompt = prompts[i - 1]; const { prompt: text, referenceVideo_1, duration, startImage, endImage } = prompt; const validateFile = async (file, allowedExts) => { if (looksLikePath(file)) { try { await fs.access(file); } catch { warnings.push(`⚠️ File '${file}' does not exist. Prompt ${i}`); } const ext = file.split('.').pop().toLowerCase(); if (!allowedExts.includes(ext)) warnings.push(`⚠️ File ${file} extension ${ext} not supported. Prompt ${i}`); } }; const notSupported = invalidKeys(prompt); if (notSupported.length) warnings.push(`⚠️ Following params not supported: ${notSupported.join(',')}. Prompt ${i}`); if (!text) warnings.push(`⚠️ prompt is required. Prompt ${i}`); // V2V edit (referenceVideo_1) does not accept duration — output matches the trim window. if (referenceVideo_1 && duration) warnings.push(`⚠️ duration is not accepted with referenceVideo_1 (V2V edit). Prompt ${i}`); if (endImage && !startImage) warnings.push(`⚠️ endImage requires startImage (end-frame-only is not supported). Prompt ${i}`); // Start/end frames (I2V, I2V-FL) are the only input in that mode — the API rejects anything alongside them. if (startImage || endImage) { if (referenceVideo_1) warnings.push(`⚠️ startImage/endImage cannot be combined with referenceVideo_1 (V2V edit). Prompt ${i}`); if ([...imageRefKeys, ...characterKeys].some(k => prompt[k])) warnings.push(`⚠️ startImage/endImage cannot be combined with referenceImage_* or character_*. Prompt ${i}`); if (audioRefKeys.some(k => prompt[k])) warnings.push(`⚠️ startImage/endImage cannot be combined with referenceAudio_*. Prompt ${i}`); } // A voice needs a referenceImage_* or character_* to attach to (or a V2V edit) — the API rejects referenceAudio_* on its own. // With start/end frames the check above already applies. if (!startImage && !endImage && !referenceVideo_1 && audioRefKeys.some(k => prompt[k]) && ![...imageRefKeys, ...characterKeys].some(k => prompt[k])) warnings.push(`⚠️ referenceAudio_* requires a referenceImage_* or character_* (or referenceVideo_1 for a V2V edit). Prompt ${i}`); await Promise.all([ validateFile(referenceVideo_1, supportedVideoExtensions), ...['startImage', 'endImage', ...imageRefKeys].map(k => validateFile(prompt[k], supportedImageExtensions)) ]); } if (warnings.length > 0) { warnings.forEach(warning => console.warn(warning)); console.error(`⛔ Execution stopped due to warnings.`); process.exit(1); } for (let i = 0; i < prompts.length; i++) { const prompt = prompts[i]; while (true) { const responseCode = await submitVideo(apiToken, email, prompt, i + 1); if (responseCode == 429 || responseCode == 503) await sleep(SLEEP_429); else if (responseCode == 402) { process.exit(1); } else break; } } } // Utility function to check if a file exists async function fileExists(path) { try { await fs.access(path); return true; } catch { return false; } } // Function to prompt user input async function promptUser(query) { const rl = readline.createInterface({ input: process.stdin, output: process.stdout }); return new Promise((resolve) => rl.question(query, answer => { rl.close(); resolve(answer); })); } function diffInMinutesAndSeconds(date1, date2) { const diffInSeconds = Math.floor((date2 - date1) / 1000); return `${Math.floor(diffInSeconds / 60)} minutes ${diffInSeconds % 60} seconds`; }; main(); ``` </details> ### 例 この Google Flow API で作った実際の Gemini Omni Flash の動画です。`model: "omni-flash-1.2"` と `model: "omni-flash"` で、延長、声、参照、キャラクター、V2V 編集を使っています。 ###### Omni 1.2 の延長 » 10秒の動画を2回延長して30秒に、2人の声で {: .no_toc #omni-12-extend--a-10-second-video-extended-twice-to-30-seconds-with-two-voices } <video poster="https://media.useapi.net/articles/2026-06-15-omni-flash-bash/261106-google-flow-omni-1-2-magician-extended-30s-web-poster.jpg" controls width="100%" style="max-width:640px;border-radius:8px"> <source src="https://media.useapi.net/articles/2026-06-15-omni-flash-bash/261106-google-flow-omni-1-2-magician-extended-30s-web.mp4" type="video/mp4"> </video> 出典は [Google Flow: Omni 1.2 Flash, 15-Second Videos, and Extend with Voices](/blog/261106)(英語)です。最初の10秒を `omni-flash-1.2` で作り、`referenceAudio_1` を付けて `POST /videos/extend` を2回呼びました。 ###### V2V 編集 » アップロードした MP4 を、動きと構図はそのままでアニメ風に {: .no_toc #v2v-edit--restyle-an-uploaded-mp4-into-a-cartoon-same-motion-and-framing } <video poster="https://media.useapi.net/blog/2026-05-20-260520/google-flow-edit-video-poster.jpg" controls width="100%" style="max-width:640px;border-radius:8px"> <source src="https://media.useapi.net/blog/2026-05-20-260520/google-flow-edit-video.mp4" type="video/mp4"> </video> 出典は [Google Flow: Gemini Omni Flash](/blog/260520)(英語)です。`referenceVideo_1` で編集しました。 ###### インラインの @ メンション » @character_1、@referenceImage_1、@referenceImage_2 とカスタムの声で作るノワール風の R2V 動画 {: .no_toc #inline--mentions--r2v-noir-video-with-character_1-referenceimage_1-referenceimage_2-and-a-custom-voice } <video poster="https://media.useapi.net/blog/2026-06-09-260609/noir-shot-1-poster.jpg" controls width="100%" style="max-width:640px;border-radius:8px"> <source src="https://media.useapi.net/blog/2026-06-09-260609/noir-shot-1.mp4" type="video/mp4"> </video> 出典は [Google Flow: Inline @-mentions](/blog/260609)(英語)です。インラインの `@` メンションのマーカーで、それぞれの参照を指定しました。 ###### キャラクター + V2V 編集 » 再利用できる2人のキャラクターをノワール風の動画に合成 {: .no_toc #characters--v2v-edit--composites-two-reusable-characters-into-the-noir-video } <video poster="https://media.useapi.net/blog/2026-06-09-260609/edit-1-poster.jpg" controls width="100%" style="max-width:640px;border-radius:8px"> <source src="https://media.useapi.net/blog/2026-06-09-260609/edit-1.mp4" type="video/mp4"> </video> 出典は [Google Flow: Inline @-mentions](/blog/260609)(英語)です。インラインの `@character_*` を使い、`referenceVideo_1` で V2V 編集しました。声とキャラクターを準備する流れは [Reusable Voices and Characters](/blog/260605)(英語)も参照してください。 ### よくある質問 - **Gemini Omni Flash とは何ですか?** useapi.net を使えば、[Google Flow](https://flow.google.com) にある Google の[音声付き動画モデル](https://deepmind.google/models/model-cards/gemini-omni-flash/) Gemini Omni Flash を、[Google Flow API](/docs/api-google-flow-v1) で `model: "omni-flash-1.2"`(Omni 1.2 Flash)または `model: "omni-flash"`(Omni 1.1 Flash)を指定して動かせます。音のない動画モデルと違い、サウンドトラック、ナレーション、セリフ、環境音を同じ動画の一部として作り、画像、動画、音声の参照と再利用できるキャラクターを受け付けます。 - **Omni Flash と Veo 3.1 の違いは?** useapi.net を使えば、どちらも同じ Google Flow API で動き、`model` フィールドで選べます。Veo はテキストや画像から動画を作る、より忠実度の高いエンジンです。一方 Omni Flash は音声を生成し、参照素材を豊富に受け付けます。動画から動画の編集(`referenceVideo_1`)、1本の動画に複数の声、どの長さでも使える再利用可能なキャラクター、Veo より長い動画に対応しています。正確な上限は[参照モード](#reference-modes)を参照してください。 - **自分の声、参照動画、参照音声を使えますか?** useapi.net を使えば、使えます。内蔵のシステムの声か、[POST /voices](/docs/api-google-flow-v1/post-google-flow-voices) で作ったカスタムの声を `referenceAudio_1..5` として渡してナレーションを付けられ、[POST /assets](/docs/api-google-flow-v1/post-google-flow-assets-email) で MP4 をアップロードすれば `referenceVideo_1` として編集できます(V2V)。各モードの上限は[参照モード](#reference-modes)と[声とキャラクター](#voices--characters)を参照してください。 - **Omni Flash の公式 API はありますか?** useapi.net を使えば、Omni 1.1 Flash は Google 自身の API よりはるかに安く使えます。8秒・720p の動画は Google AI Ultra $199.99 で $0.10 で、公式の [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) では $0.81 です。Gemini API は2026年6月30日からこのモデルを秒単位で販売しています(2026年11月時点)。useapi.net では、お使いの Google Flow の Web サイトのプランで、標準的な REST エンドポイントから動きます。 - **Omni Flash で10秒より長い動画を作れますか?** useapi.net を使えば、作れます。Omni 1.2 Flash(`model: "omni-flash-1.2"`)は1回の呼び出しで最大15秒を作り、[POST /videos/extend](/docs/api-google-flow-v1/post-google-flow-videos-extend) は声を付けて1回最大10秒を追加します。8秒・720p の動画は Google AI Ultra $199.99 で $0.19、[Google 自身の API](https://cloud.google.com/blog/products/ai-machine-learning/gemini-omni-1-2-flash-generally-available) では $0.56 です(2026年11月時点)。Google Flow と Google Vids での長さの上限と料金はすべて [Gemini Omni 1.2 Flash API の使い方](/docs/articles/gemini-omni-1-2-flash-api-ja)にあります。 - **CAPTCHA を解く必要はありますか?** useapi.net を使えば、ご自身で解く必要はありません。Google Flow は動画ごと、新しい声ごとに reCAPTCHA を求めますが、useapi.net のワーカーが自動で解決します。最初の Google Flow アカウントには、当社の AntiCaptcha、CapSolver、EzCaptcha のキーで300回の無料解決が付き、その後は [POST /accounts/captcha-providers](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers) でご自身のプロバイダーのキーを追加します。[POST /characters](/docs/api-google-flow-v1/post-google-flow-characters) には CAPTCHA は不要です。 ### おわりに ご質問は <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord サーバー</a> または <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram チャンネル</a>へどうぞ。 コード例は [GitHub リポジトリ](https://github.com/useapi/google-flow-api)にあります。 AI アシスタントに Google Flow の作業を任せることもできます。ホスト型の [Google Flow MCP サーバー](/docs/api-google-flow-v1/mcp)を使うと、Claude Code、Cursor、VS Code から Google Flow Agent とチャットでき、Agent がお使いのアカウントで画像や動画を作ります。 ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/omni-flash-bash-pt === Document URL: https://useapi.net/docs/articles/omni-flash-bash-pt --- layout: default title: "Como gerar vídeo com IA e áudio nativo com o Gemini Omni Flash pela Google Flow API" seo_title: "API do Gemini Omni Flash com curl: vozes, personagens e V2V" description: "Gemini Omni Flash na Google Flow API da useapi.net, com código: imagens de referência, personagens, vozes e edições V2V no Omni 1.2 e 1.1, mais um script de lote." keywords: [Gemini Omni Flash, Omni 1.2 Flash, Omni 1.1 Flash, Omni Flash API, API do Omni Flash, API do Gemini Omni Flash, omni-flash-1.2, omni-flash, Google Flow API, API do Google Flow, vídeo com áudio nativo, vídeo com IA com vozes, estender vídeo, vozes, personagens, edição de vídeo, vídeo para vídeo, referência para vídeo, tutorial, código, curl] parent: Articles nav_exclude: true lang: pt-BR translation_key: omni-flash date: 2026-06-15 last_modified: 2026-11-12 nav_order: 830 repo: https://github.com/useapi/google-flow-api --- ## Como gerar vídeo com IA e áudio nativo com o Gemini Omni Flash pela Google Flow API {: .no_toc #how-to-generate-audio-native-ai-video-with-gemini-omni-flash-via-the-google-flow-api } 8 min de leitura • 15 de junho de 2026 (12 de novembro de 2026) A useapi.net é uma API de terceiros. Não tem afiliação com o Google nem é endossada por ele. ## Sumário {: .no_toc .text-delta #table-of-contents } ### Introdução O [Gemini Omni Flash](https://deepmind.google/models/model-cards/gemini-omni-flash/) gera vídeo com IA e áudio nativo com um único `curl` pela [Google Flow API](/docs/api-google-flow-v1) da useapi.net, com vozes sincronizadas, personagens e edições de vídeo para vídeo, na sua assinatura do site [Google Flow](https://flow.google.com) ([Google AI](https://gemini.google/subscriptions/): Omni 1.1 Flash no Plus, Pro ou Ultra, Omni 1.2 Flash em todos os planos, e em contas gratuitas até 10 segundos). Um vídeo de 10 segundos em 720p custa $0,12 no Google AI Ultra $199,99, contra $1,01 na [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) oficial (em novembro de 2026), sem projeto no Google Cloud nem chave de API. A mesma assinatura também gera vídeos Omni no [Google Vids](/docs/api-google-vids-v1), sem gastar créditos do Flow. Na interface, o Google Flow chama este modelo de Omni 1.1 Flash, e o valor na API é `model: "omni-flash"`. O Omni 1.2 Flash, que o Google lançou em 5 de novembro de 2026, é outro valor, `model: "omni-flash-1.2"`: qualquer duração de 3 a 15 segundos, créditos por segundo, e é o modelo que [estende um vídeo](#extend-a-video-with-omni-12) em até 10 segundos por vez. Código que envia `omni-flash` continua recebendo o 1.1. Para vídeos de 15 segundos, extensão com vozes e o preço por vídeo no Google Flow e no Google Vids, veja [Como usar a API do Gemini Omni 1.2 Flash](/docs/articles/gemini-omni-1-2-flash-api-pt). O Omni Flash é a [mesma Google Flow API](/docs/api-google-flow-v1) do Veo, escolhido com um único campo — `model: "omni-flash-1.2"` ou `model: "omni-flash"` —, mas é outro tipo de modelo. O Veo é um motor forte de texto para vídeo simples, e o Omni Flash tem áudio nativo e aceita muitas referências: - O som é gerado junto com o vídeo — narração, diálogo e ambiente saem do mesmo modelo, não são acrescentados depois. - Vozes — 30 presets de voz do sistema, mais vozes personalizadas que você cria com o seu próprio diálogo e notas de interpretação, passadas em `referenceAudio_1..5`. - Referências de imagem e de vídeo — até 10 imagens de referência no Omni 1.2 Flash (7 no Omni 1.1 Flash) para referência para vídeo (R2V), e edição de vídeo para vídeo (V2V) de um vídeo enviado ou gerado com `referenceVideo_1`. - Personagens reutilizáveis — junte imagens de referência e uma voz em um personagem com nome e use-o em vários vídeos. - Vídeos mais longos — o Omni 1.1 Flash gera 4, 6, 8 ou 10 segundos e o Omni 1.2 Flash qualquer duração de 3 a 15 (o Veo para em `8`), e o Omni 1.2 estende um vídeo em etapas de até 10 segundos. Este guia mostra o fluxo em duas chamadas com `curl` para copiar e colar, os modos de referência que tornam o Omni Flash diferente e, depois, um script Node.js pronto para rodar que gera em lote a partir de uma lista de prompts. Para texto para vídeo simples, veja o [tutorial do Veo 3.1](/docs/articles/google-flow-bash-pt) irmão deste. ### Modelo suportado Este guia usa os modelos de vídeo com áudio nativo do Google, Omni 1.1 Flash (`model: "omni-flash"`) e Omni 1.2 Flash (`model: "omni-flash-1.2"`). No Omni 1.1, o custo em créditos cresce com a duração do vídeo: | Duração | Créditos por vídeo | |----------|------------------------| | 4s | 7 | | 6s | 10 | | 8s | 12 | | 10s | 15 | | Edição V2V | 20 | Esses são os custos no `720p` padrão. Passar `resolution: "360p"` custa cerca da metade — 4 / 5 / 6 / 7 créditos pela duração, 10 por uma edição V2V —, e um vídeo em 360p pode ser levado a 720p depois com [POST /videos/upscale](/docs/api-google-flow-v1/post-google-flow-videos-upscale). O Omni 1.2 Flash (`model: "omni-flash-1.2"`) aceita qualquer número inteiro de segundos de 3 a 15 e cobra por segundo, igual em todos os planos: | Duração | 720p | 360p | |--------|------|------| | 3s | 9 | 3 | | 8s | 24 | 8 | | 10s | 30 | 10 | | 15s | 60 | 20 | Até 10 segundos são 3 créditos por segundo em 720p e 1 em 360p, e cada segundo acima de 10 custa o dobro. Uma edição V2V custa o mesmo que um vídeo com a duração editada, e o 1.2 edita até 15 segundos de um clipe. Contas Google gratuitas podem usar o 1.2 para vídeos de até 10 segundos. O Omni Flash aceita cinco modos no [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos): texto para vídeo simples (T2V), referência para vídeo (R2V) com até 10 `referenceImage_1..10` no Omni 1.2 Flash (7 no Omni 1.1 Flash), imagem para vídeo a partir de um quadro inicial com `startImage` (I2V), imagem para vídeo entre um quadro inicial e um final com `startImage` + `endImage` (I2V-FL), e edição de vídeo para vídeo (V2V) de um MP4 enviado com `referenceVideo_1`. Veja [Modos de referência](#reference-modes) abaixo. ### Preços O Omni 1.1 Flash exige uma assinatura paga do Google AI (Plus, Pro ou Ultra), o Omni 1.2 Flash funciona em contas gratuitas até 10 segundos, e a useapi.net não cobra nada por vídeo. Cada vídeo gasta créditos do Flow pela duração (veja [Modelo suportado](#supported-model)). O preço por vídeo em cada plano, comparado com a Gemini API oficial, está na [tabela de preços do Google Flow](/docs/api-google-flow-v1#pricing). Um plano Google AI também vem com uma cota mensal no [Google Vids](https://docs.google.com/videos), que gera vídeos de até 15 segundos com o Gemini Omni 1.2 Flash ([anúncio do Google](https://workspaceupdates.googleblog.com/2026/11/gemini-omni-12-flash-now-in-vids-with-15second-generations-and-improved-quality.html)) e não usa créditos do Flow. No Ultra $199,99 (que o Google chama de Ultra 20x) são 10.000 segundos de vídeo por mês — cerca de 1.000 clipes de 10 segundos em 1080p a mais, além dos ~1.666 clipes Omni 1.1 Flash de dez segundos (ou ~833 clipes Omni 1.2 Flash em 720p) que os 25.000 créditos do Flow compram. Esses segundos são divididos entre todos de um plano família do Google. Os outros planos recebem menos (veja a página [Gemini no Google Vids](https://support.google.com/docs/answer/15609411?hl=pt-BR) do Google), e as contas gratuitas que testamos não tinham nenhum. A [Google Vids API](/docs/api-google-vids-v1) usa essa cota sem captcha. Conecte a conta com [Setup Google Vids](/docs/start-here/setup-google-vids). ### Gere um vídeo em duas chamadas de API Você precisa de um [token da API](/docs/start-here/setup-useapi) da useapi.net e de uma [conta Google Flow](/docs/start-here/setup-google-flow) conectada, com uma assinatura paga do Google AI (Plus, Pro ou Ultra) para o exemplo com Omni 1.1 Flash abaixo (o Omni 1.2 Flash também roda em conta gratuita, até 10 segundos). Jobs de vídeo são assíncronos: passe `async: true` e a chamada de criação devolve um `jobid` na hora, depois você consulta até o vídeo ficar pronto. 1. Envie o job — `POST https://api.useapi.net/v1/google-flow/videos` com `model: "omni-flash"`: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A lighthouse keeper narrates the coming storm, waves crashing below", "model": "omni-flash", "aspectRatio": "landscape", "duration": 10, "async": true }' ``` Como o Omni Flash tem áudio nativo, ele gera a trilha sonora — a narração do faroleiro e as ondas quebrando — direto do prompt, sem nenhum parâmetro de áudio. No modo assíncrono, a resposta volta na hora com `201 Created`, um `jobid` em minúsculas e `status: "created"`: ```json { "jobid": "j1731859234567v-u12345-email:jo***@gmail.com-bot:google-flow", "type": "video", "status": "created", "created": "2026-06-15T12:34:56.789Z", "request": { "async": true, "prompt": "A lighthouse keeper narrates the coming storm, waves crashing below", "model": "omni-flash", "aspectRatio": "landscape", "duration": 10 } } ``` 2. Consulte o resultado — `GET https://api.useapi.net/v1/google-flow/jobs/{jobId}`: ```bash curl "https://api.useapi.net/v1/google-flow/jobs/JOBID" \ -H "Authorization: Bearer $USEAPI_TOKEN" ``` O `status` passa por `created` → `started` → `completed`. Quando chega a `completed`, o MP4 pronto está em `response.media[].videoUrl` (um único prompt com `count > 1` devolve uma entrada por vídeo): ```json { "jobid": "j1731859234567v-...", "type": "video", "status": "completed", "response": { "media": [ { "mediaGenerationId": "user:12345-email:6a6f...-video:a1d95d21-...", "videoUrl": "https://flow-content.google/video/a1d95d21-...?Expires=...", "thumbnailUrl": "https://flow-content.google/image/a1d95d21-...?Expires=..." } ], "remainingCredits": 18760 } } ``` O Omni Flash costuma terminar em 60–180 segundos. O `videoUrl` assinado vale por cerca de 6 horas, então baixe logo. Não quer ficar consultando? Passe um `replyUrl` no corpo da criação para receber um webhook quando o job terminar. ### Modos de referência O grande diferencial do Omni Flash é quanta coisa você pode passar como referência. Todas as referências vêm do endpoint de upload [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email) (ou, no caso de personagens, do [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters)). A resposta do upload traz o id de referência aninhado em `mediaGenerationId.mediaGenerationId` — é essa string aninhada que você passa de volta. Os modos aceitos pelo `omni-flash` (da documentação do [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos#references)): | Modo | Parâmetro(s) | Limite no Omni Flash | |------|--------------|------------------| | Referência para vídeo (R2V) | `referenceImage_1..10` | até 10 imagens no `omni-flash-1.2`, 7 no `omni-flash` | | Imagem para vídeo (I2V) | `startImage` | um quadro inicial | | Imagem para vídeo, inicial + final (I2V-FL) | `startImage` + `endImage` | só os dois quadros — sem outras referências | | Edição de vídeo para vídeo (V2V) | `referenceVideo_1` (+ `startFrameIndex_1` / `endFrameIndex_1` opcionais) | um MP4 enviado | | Personagens | `character_1..10` (do [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters)) | 10 no total com `referenceImage_*` no `omni-flash-1.2`, 7 no `omni-flash` | | Narração por voz | `referenceAudio_1..5` | até 5 (R2V) / até 3 (edição V2V) | Referência para vídeo (R2V) — envie uma ou mais imagens e passe-as como `referenceImage_1`, `referenceImage_2`, … (os slots `_4`..`_7` são só do Omni Flash). Imagens de referência não podem ser combinadas com `startImage`/`endImage`. ```bash # 1. Upload a reference image — the id is nested one level deep: curl -X POST "https://api.useapi.net/v1/google-flow/assets/john%40gmail.com" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: image/jpeg" \ --data-binary @subject.jpeg # Response: { "mediaGenerationId": { "mediaGenerationId": "user:12345-email:...-image:..." }, ... } # 2. Generate, narrated by a system voice curl -X POST "https://api.useapi.net/v1/google-flow/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model": "omni-flash", "prompt": "the subject walks toward camera and introduces herself", "duration": 8, "referenceImage_1": "user:12345-email:...-image:...", "referenceAudio_1": "Kore" }' ``` Edição de vídeo para vídeo (V2V) — envie um MP4 com `Content-Type: video/mp4` para o [POST /assets](/docs/api-google-flow-v1/post-google-flow-assets-email) e passe o id devolvido como `referenceVideo_1` para editar esse vídeo. Isso é só do Omni Flash e coloca a requisição no modo V2V. `duration` não é aceito (a duração da saída segue a janela de corte da entrada, no máximo 10 s no `omni-flash` e 15 s no `omni-flash-1.2`). Se quiser, corte a origem em uma linha do tempo virtual de 24 fps com `startFrameIndex_1` (0–239) e `endFrameIndex_1` (1–240, em que 240 = 10 s), ou até 359 e 360 (15 s) no `omni-flash-1.2`: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model": "omni-flash", "prompt": "restyle the scene as a rainy neon-lit night, add ambient city sound", "referenceVideo_1": "user:12345-email:...-video:...", "startFrameIndex_1": 0, "endFrameIndex_1": 240, "async": true }' ``` Você também pode colocar marcadores `@` inline no prompt que apontam para os slots que você passa — por exemplo `@referenceImage_1`, `@character_1`, `@referenceAudio_1`. Os marcadores são opcionais e cada um precisa de um parâmetro correspondente no corpo. (`@referenceVideo_*` não funciona inline — passe-o como campo do corpo.) Veja [Inline @-mention markers](/docs/api-google-flow-v1/post-google-flow-videos#inline--mention-markers-optional). ### Vozes e personagens Duas chamadas curtas de configuração alimentam os recursos de áudio e identidade do Omni Flash. Vozes personalizadas — o [POST /voices](/docs/api-google-flow-v1/post-google-flow-voices) salva uma voz baseada em um dos 30 presets do sistema, com o seu próprio `dialog` e `voicePerformance`. O campo `voice` da resposta é um id de referência que você passa depois como `referenceAudio_1..5` no [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos): ```bash curl -X POST "https://api.useapi.net/v1/google-flow/voices" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "john@gmail.com", "voice": "Achernar", "dialog": "Welcome to the demo.", "voicePerformance": "Cheerful, energetic delivery", "displayName": "Cheerful Narrator" }' # Response: { "voice": "user:12345-email:...-voice:...-mid:...", ... } ``` Cada slot `referenceAudio_*` aceita o nome de uma voz do sistema (sem diferenciar maiúsculas, um dos 30 presets, como `Aoede`, `Kore`, `Puck`, `Zephyr`) ou o id de uma voz de usuário da chamada acima. Criar uma voz exige reCAPTCHA (resolvido automaticamente — veja [as perguntas frequentes](#frequently-asked-questions)). Personagens reutilizáveis — o [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters) junta 1–2 imagens de referência e uma voz opcional em um personagem com nome. O campo `character` da resposta é o que você passa como `character_1..10`: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/characters" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "displayName": "Carol", "imageReference_1": "user:12345-email:...-image:abc123...", "voice": "user:12345-email:...-voice:...-mid:..." }' # Response: { "character": "user:12345-email:...-character:...-imgs:1-voice:...", ... } ``` No Omni Flash, os personagens funcionam em todas as durações e dividem o limite total de 10 imagens de referência com `referenceImage_*` (`referenceImages.length + Σ(character.imgs) ≤ 10`, Omni 1.1: 7). O `POST /characters` não exige captcha. Personagens e vozes também funcionam no Veo, mas com limites mais apertados (3 imagens, 1 voz, só 8 s) — veja [What can use a character?](/docs/api-google-flow-v1/post-google-flow-characters#what-can-use-a-character). ### Estenda um vídeo com o Omni 1.2 O [POST /videos/extend](/docs/api-google-flow-v1/post-google-flow-videos-extend) acrescenta de 3 a 10 segundos por vez com o Omni 1.2 Flash a qualquer vídeo com menos de 30 segundos, com até 3 vozes, imagens de referência ou personagens, e devolve um único clipe contínuo (só em planos pagos). O passo a passo em [Como usar a API do Gemini Omni 1.2 Flash](/docs/articles/gemini-omni-1-2-flash-api-pt#flow-walkthrough) estende um vídeo de 10 segundos duas vezes até 30 segundos, com duas vozes, o [exemplo abaixo](#examples). ### Gere em lote com um script Achar a tomada certa leva muitas tentativas, e rodar tudo à mão cansa. O script Node.js abaixo lê uma lista de prompts do `prompts.json`, envia as imagens de referência, os quadros inicial e final ou os vídeos de origem, repassa direto os ids `character_*` e a `resolution`, envia cada job no modo assíncrono com `model: "omni-flash"` e depois consulta e baixa cada MP4 pronto — assim você coloca um lote na fila e volta depois para escolher os melhores. Ele para com um aviso antes de enviar uma combinação que a API recusaria, como um quadro final sem quadro inicial. Você precisa do [Node.js](https://nodejs.org) v21 ou mais novo. Coloque o `prompts.json` e o `omni-flash.mjs` na mesma pasta e rode `node ./omni-flash.mjs API_TOKEN EMAIL`, em que `API_TOKEN` é o seu [token da API](/docs/start-here/setup-useapi) da useapi.net e `EMAIL` é o email da sua [conta Google Flow](/docs/start-here/setup-google-flow) conectada. O script encontra a conta pelo email automaticamente e verifica o campo `health` dela antes de enviar. Prefere clonar e rodar localmente? O `omni-flash.mjs` e o `prompts.json` completos estão no GitHub, em [`useapi/google-flow-api`](https://github.com/useapi/google-flow-api/tree/main/omni-flash). Trabalha no Claude Code ou no Codex? A [agent skill omni-flash-video](https://github.com/useapi/google-flow-api/tree/main/skills/omni-flash-video) deixa o agente fazer tudo isso por você: descreva o vídeo, aponte as suas imagens, e ele as envia, escreve a requisição, espera e salva o `.mp4`. Instale com `npx skills add useapi/google-flow-api --skill omni-flash-video`. <details markdown="block"> <summary>Abrir `prompts.json`</summary> ```json [ { "prompt": "Audio-native text-to-video. By default model omni-flash with a landscape 8-second clip will be used." }, { "duration": 10, "prompt": "A 10-second clip (omni-flash only). Omni Flash is audio-native, so narration, dialogue and sound come from the prompt. To pin a specific voice, add referenceAudio_1 together with a referenceImage_* or character_*, as in the next prompt." }, { "duration": 8, "referenceImage_1": "./subject.jpeg", "referenceAudio_1": "Kore", "prompt": "Reference-to-video (R2V): the uploaded image is a reference, narrated by 'Kore'. Up to 7 referenceImage_* on omni-flash, 10 on omni-flash-1.2." }, { "duration": 8, "startImage": "./first_image.jpeg", "endImage": "./last_image.jpeg", "prompt": "Image-to-video with a start frame (startImage) and an end frame (endImage). The two frames are the only input — no referenceImage_*, character_* or referenceAudio_* alongside them." }, { "referenceVideo_1": "./source.mp4", "startFrameIndex_1": 0, "endFrameIndex_1": 240, "prompt": "Video-to-video edit (V2V): omni-flash restyles the uploaded MP4. No duration here — output matches the trim window (max 10 s). For all parameters see https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos" } ] ``` </details> <details markdown="block"> <summary>Abrir o script `omni-flash.mjs`</summary> ```javascript /* Script version 1.3, November 11, 2026 Script to batch-generate audio-native videos with Gemini Omni Flash using the Google Flow API by useapi.net Uses the POST /videos endpoint in async mode (model: omni-flash by default, or omni-flash-1.2 per prompt) and polls GET /jobs/{jobId}. For more details visit https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos Installation Instructions: ========================== You need Node.js v21 or newer installed to run this script. Download and install Node.js from: - Windows, macOS, Linux: https://nodejs.org/ After installation, verify by running the following command in a terminal: node -v Running the Script: =================== Usage: node omni-flash.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE] Replace API_TOKEN with your actual useapi.net API token, see https://useapi.net/docs/start-here/setup-useapi Replace EMAIL with configured Google Flow email account, see https://useapi.net/docs/start-here/setup-google-flow If optional PROMPTS_FILE not provided prompts.json will be used. Example: -------- node omni-flash.mjs user:1234-abcdefhijklmnopqrstuv my@email.com This command executes the script using API token user:1234-abcdefhijklmnopqrstuv with my@email.com Google Flow account email. Changelog: ========== - June 15, 2026: Initial release. - September 11, 2026: Adds resolution, startImage / endImage (start and end frames, local files uploaded for you) and character_1..7. Accepts .jpg and upper-case file extensions. Stops with a warning before submitting combinations the API rejects, such as endImage without startImage or referenceAudio_* on its own. A prompt whose local startImage, endImage, referenceImage_* or referenceVideo_1 file fails to upload is skipped and logged to omni-flash_errors.txt instead of being submitted without it. Saves a downloaded video under its final name only once it has been fully received, so a failed download leaves no partial MP4 for the next run to skip as "already exists". - November 11, 2026: referenceImage_8..10 and character_8..10: omni-flash-1.2 takes up to 10 references (omni-flash 7). */ import readline from 'node:readline'; import fs from 'fs/promises'; import path from 'path'; import { writeFile } from 'node:fs/promises'; import { Readable } from 'node:stream'; // Constants const RESULTS_FILE = 'omni-flash_results.txt'; const ERRORS_FILE = 'omni-flash_errors.txt'; const DEFAULT_PROMPTS_FILE = 'prompts.json'; const MODEL = 'omni-flash'; // Reference slots: up to 10 on omni-flash-1.2, 7 on omni-flash, 3 on Veo (referenceImage_* and character_* together). const imageRefKeys = Array.from({ length: 10 }, (_, i) => `referenceImage_${i + 1}`); const characterKeys = Array.from({ length: 10 }, (_, i) => `character_${i + 1}`); const SLEEP_429 = 30 * 1000; // in milliseconds const SLEEP_POLL = 15 * 1000; // in milliseconds const urlAccounts = 'https://api.useapi.net/v1/google-flow/accounts'; const urlVideos = 'https://api.useapi.net/v1/google-flow/videos'; const urlJobs = 'https://api.useapi.net/v1/google-flow/jobs/'; const urlUploadAsset = 'https://api.useapi.net/v1/google-flow/assets/'; // Google Flow accepts png, jpeg and webp images, and mp4 video (for omni-flash V2V edit). const supportedImageExtensions = ['png', 'jpg', 'jpeg', 'webp']; const supportedVideoExtensions = ['mp4']; // { filename: mediaGenerationId } const uploadedFiles = {}; // Utility to sleep for given milliseconds const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); // Function to fetch configured Google Flow API accounts async function fetchAccounts(apiToken) { const response = await fetch(urlAccounts, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.error(`⛔ Error fetching accounts (HTTP ${response.status}): ${response.statusText}`); process.exit(1); } return response.json(); } const elapsedTimeSec = (start) => (Date.now() - start) / 1000; // Map a file extension to the Content-Type required by POST /assets const contentTypeForExt = (ext) => ext === 'png' ? 'image/png' : ext === 'webp' ? 'image/webp' : ext === 'mp4' ? 'video/mp4' : 'image/jpeg'; async function uploadAsset(apiToken, email, filename) { // Check if already uploaded if (uploadedFiles.hasOwnProperty(filename)) return uploadedFiles[filename]; const startTime = Date.now(); console.log(`⬆️ Account ${email} uploading file…`, filename); const body = new Blob([await fs.readFile(filename)]); const fileExt = filename.split('.').pop().toLowerCase(); const response = await fetch(`${urlUploadAsset}${encodeURIComponent(email)}`, { method: 'POST', headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}`, 'Content-Type': contentTypeForExt(fileExt) }, body }); if (response.ok) { const json = await response.json(); // POST /assets returns the reference id nested as mediaGenerationId.mediaGenerationId const mediaGenerationId = json?.mediaGenerationId?.mediaGenerationId; console.log(`🆗 mediaGenerationId (${elapsedTimeSec(startTime)} sec)`, mediaGenerationId); uploadedFiles[filename] = mediaGenerationId; } else { console.error(`❗ Unable to upload file HTTP ${response.status} (${elapsedTimeSec(startTime)} sec)`, await response.text()); // Do not attempt to upload failed file again uploadedFiles[filename] = undefined; } return uploadedFiles[filename]; } async function submit(apiToken, url, body, index, prompt) { const createResponse = await fetch(url, { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiToken}` }, body }); const createBody = await createResponse.text(); // Async POST /videos returns 201 Created with a jobid to poll. if (createResponse.status == 201) { const json = JSON.parse(createBody); // 201 async payload uses lowercase "jobid"; sync 200 uses "jobId". Accept either. const jobId = json.jobid ?? json.jobId; if (jobId) { await fs.appendFile(RESULTS_FILE, `${jobId},#${index}:${prompt}\n`); console.log(`✅ jobId`, jobId); return 201; } else { const error = `No jobid found in HTTP 201 response`; console.log(`❓ ${error}`, createBody); await fs.appendFile(ERRORS_FILE, `${error},#${index}:${prompt}\n`); return 500; } } else { switch (createResponse.status) { case 429: console.log(`🔄️ Retry on HTTP ${createResponse.status}`, createBody); break; case 503: console.log(`🔄️ Service unavailable, retry on HTTP ${createResponse.status}`, createBody); break; case 400: console.log(`🛑 Rejected request (validation or content policy)`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${prompt}\n`); break; case 402: console.log(`🛑 No subscription / insufficient credits`, createBody); break; default: console.log(`❗ FAILED with HTTP ${createResponse.status}`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${prompt}\n`); } return createResponse.status; } } // Submit a single prompt to POST /videos with model omni-flash (or the prompt's own model) in async mode. // startImage = start frame (I2V), endImage = end frame (I2V-FL, requires startImage) — the frames are the only input; // referenceImage_1..10 = R2V image refs; character_1..10 = POST /characters ids (10 on omni-flash-1.2, 7 on omni-flash); // referenceVideo_1 = V2V edit (no duration); referenceAudio_1..5 = system voice name or POST /voices user-voice id; // resolution = 720p (default) or 360p; model = 'omni-flash' (Omni 1.1, the default) or 'omni-flash-1.2' (3–15 s, per-second credits). async function submitVideo(apiToken, email, prompt, index) { const { prompt: text, model = MODEL, aspectRatio, duration, resolution, count, startImage, endImage, referenceVideo_1, startFrameIndex_1, endFrameIndex_1, referenceAudio_1, referenceAudio_2, referenceAudio_3, referenceAudio_4, referenceAudio_5 } = prompt; console.log(`🚀 ${model} » Prompt #${index} • account ${email} …`); // Upload any local image/video files and swap the paths for their mediaGenerationId. const resolveRef = async (ref) => ref && (ref.startsWith('./') || ref.includes('.')) && [...supportedImageExtensions, ...supportedVideoExtensions].includes(ref.split('.').pop().toLowerCase()) ? await uploadAsset(apiToken, email, ref) : ref; const startImageId = await resolveRef(startImage); const endImageId = await resolveRef(endImage); const refImages = {}; for (const key of imageRefKeys) refImages[key] = await resolveRef(prompt[key]); const refVideo_1 = await resolveRef(referenceVideo_1); // A local file that failed to upload would be left out of the body, and the prompt would still be // generated (and charged) without it. Skip the prompt instead. uploadAsset remembers the failed file, // so a later prompt using it is skipped too, without another upload attempt. const failedUploads = [ ['startImage', startImage, startImageId], ['endImage', endImage, endImageId], ...imageRefKeys.map(key => [key, prompt[key], refImages[key]]), ['referenceVideo_1', referenceVideo_1, refVideo_1] ].filter(([, file, id]) => file && !id); for (const [param, file] of failedUploads) { console.error(`🛑 Prompt #${index} skipped: ${param} ${file} failed to upload`); await fs.appendFile(ERRORS_FILE, `Upload failed for ${param} ${file},#${index}:${text}\n`); } if (failedUploads.length) return; // V2V edit does not accept duration — output matches the trim window. const isV2V = !!refVideo_1; const body = JSON.stringify({ model, email, prompt: text, aspectRatio, duration: isV2V ? undefined : duration, resolution, count, startImage: startImageId, endImage: endImageId, ...refImages, ...Object.fromEntries(characterKeys.map(key => [key, prompt[key]])), referenceVideo_1: refVideo_1, startFrameIndex_1, endFrameIndex_1, referenceAudio_1, referenceAudio_2, referenceAudio_3, referenceAudio_4, referenceAudio_5, async: true }); return await submit(apiToken, urlVideos, body, index, text); } // Function to download videos async function download(apiToken) { if (! await fileExists(RESULTS_FILE)) return; try { const resultsContent = await fs.readFile(RESULTS_FILE, 'utf8'); const lines = resultsContent.trim().split('\n'); for (const line of lines) { const [jobId, prompt] = line.split(','); console.log(`👉 ${jobId}`); while (true) { const response = await fetch(`${urlJobs}${jobId}`, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.log(`🛑 Poll failed ${jobId} (HTTP ${response.status}):\n${prompt}\n`, await response.text()); break; } const jobBody = await response.json(); const { status, error, response: jobResponse } = jobBody; if (status == 'failed') { console.error(`🛑 FAILED ${jobId} (${error}):\n${prompt}\n`); break; } if (status == 'completed') { const media = jobResponse?.media ?? []; if (media.length == 0) console.error(`🛑 Completed but no media for ${jobId}:\n${prompt}\n`); // A single prompt with count > 1 returns multiple videos. for (let i = 0; i < media.length; i++) { const url = media[i]?.videoUrl; const videoFilename = `${jobId.replace(/[:*]/g, '_')}_${i + 1}.mp4`; try { await fs.access(videoFilename); console.log(`⚠️ ${videoFilename} already exists. Skipping download.`); continue; } catch { // File does not exist, proceed with downloading } if (url) { console.log(`✅ Downloading ${url} to ${videoFilename}`); // Stream into a temporary file and rename it once the whole video has arrived, so a download // that drops mid-stream leaves no partial file behind for the next run to skip as "already exists". const tempFilename = `${videoFilename}.part`; try { const videoResponse = await fetch(url); if (!videoResponse.ok) { console.error(`⛔ Unable to download ${jobId} (HTTP ${videoResponse.status}):\n${prompt}\n`, url); continue; } const stream = Readable.fromWeb(videoResponse.body); await writeFile(tempFilename, stream); await fs.rename(tempFilename, videoFilename); } catch (err) { await fs.rm(tempFilename, { force: true }); console.error(`⛔ Error during download: ${err}`); } } else console.error(`🛑 No videoUrl for ${jobId} media #${i + 1}:\n${prompt}\n`); } break; } console.log(`⌛ ${jobId} status (${status}) and is still in progress, waiting…`); await sleep(SLEEP_POLL); } } } catch (error) { console.log(`⛔ Error during download:`, error.stack || error); } } // Main function async function main() { const apiToken = process.argv[2]; const email = process.argv[3]; const promptFile = process.argv[4] || DEFAULT_PROMPTS_FILE; if (!apiToken || !email) { console.error('Usage: node omni-flash.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE]'); process.exit(1); } console.info('Script v1.3'); console.info('Node version is: ' + process.version); try { if (await fileExists(RESULTS_FILE)) { let user_input; while (!['y', 'n'].includes(user_input)) { user_input = (await promptUser(`❔ ${RESULTS_FILE} file detected. Do you want to download the results now? (y/n): `))?.toLowerCase(); if (user_input == 'y') { await download(apiToken); await fs.unlink(RESULTS_FILE); } } } const start = new Date(); try { console.info('START EXECUTION', start); await execute(apiToken, email, promptFile); // Pass the promptFile to execute function } finally { console.info('COMPLETED', new Date()); console.info('EXECUTION ELAPSED', diffInMinutesAndSeconds(start, new Date())); } try { console.info('START DOWNLOAD', start); await download(apiToken); } finally { console.info('TOTAL ELAPSED', diffInMinutesAndSeconds(start, new Date())); } } catch (error) { console.error('⛔ Error during execution:', error.stack || error); } } // Modify the execute function to accept promptFile as a parameter async function execute(apiToken, email, promptFile) { const accounts = await fetchAccounts(apiToken); console.info(`Configured Google Flow API accounts (${Object.keys(accounts).length}):`, Object.keys(accounts).join(', ')); if (Object.keys(accounts).length <= 0) { console.error(`⛔ No configured Google Flow accounts found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (!accounts[email]) { console.error(`⛔ Account ${email} not found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (accounts[email].health && accounts[email].health !== 'OK') { console.error(`⛔ Account ${email} health is '${accounts[email].health}'. Please resolve and update the account, see https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } const promptData = await fs.readFile(promptFile, 'utf8'); const prompts = JSON.parse(promptData); console.log(`Total number of prompts to process`, prompts.length); let warnings = []; // Parameters accepted by this script for the omni-flash POST /videos endpoint. // See https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos for the full parameter set. const supportedParams = [ 'prompt', 'model', 'aspectRatio', 'duration', 'resolution', 'count', 'startImage', 'endImage', ...imageRefKeys, ...characterKeys, 'referenceVideo_1', 'startFrameIndex_1', 'endFrameIndex_1', 'referenceAudio_1', 'referenceAudio_2', 'referenceAudio_3', 'referenceAudio_4', 'referenceAudio_5' ]; const audioRefKeys = ['referenceAudio_1', 'referenceAudio_2', 'referenceAudio_3', 'referenceAudio_4', 'referenceAudio_5']; const invalidKeys = (prompt) => Object.keys(prompt).filter(key => !key.startsWith('__') && !supportedParams.includes(key)) // Validate a local file path reference (skip already-uploaded mediaGenerationId strings). const looksLikePath = (ref) => ref && (ref.startsWith('./') || (ref.includes('.') && !ref.startsWith('user:'))); for (let i = 1; i <= prompts.length; i++) { const prompt = prompts[i - 1]; const { prompt: text, referenceVideo_1, duration, startImage, endImage } = prompt; const validateFile = async (file, allowedExts) => { if (looksLikePath(file)) { try { await fs.access(file); } catch { warnings.push(`⚠️ File '${file}' does not exist. Prompt ${i}`); } const ext = file.split('.').pop().toLowerCase(); if (!allowedExts.includes(ext)) warnings.push(`⚠️ File ${file} extension ${ext} not supported. Prompt ${i}`); } }; const notSupported = invalidKeys(prompt); if (notSupported.length) warnings.push(`⚠️ Following params not supported: ${notSupported.join(',')}. Prompt ${i}`); if (!text) warnings.push(`⚠️ prompt is required. Prompt ${i}`); // V2V edit (referenceVideo_1) does not accept duration — output matches the trim window. if (referenceVideo_1 && duration) warnings.push(`⚠️ duration is not accepted with referenceVideo_1 (V2V edit). Prompt ${i}`); if (endImage && !startImage) warnings.push(`⚠️ endImage requires startImage (end-frame-only is not supported). Prompt ${i}`); // Start/end frames (I2V, I2V-FL) are the only input in that mode — the API rejects anything alongside them. if (startImage || endImage) { if (referenceVideo_1) warnings.push(`⚠️ startImage/endImage cannot be combined with referenceVideo_1 (V2V edit). Prompt ${i}`); if ([...imageRefKeys, ...characterKeys].some(k => prompt[k])) warnings.push(`⚠️ startImage/endImage cannot be combined with referenceImage_* or character_*. Prompt ${i}`); if (audioRefKeys.some(k => prompt[k])) warnings.push(`⚠️ startImage/endImage cannot be combined with referenceAudio_*. Prompt ${i}`); } // A voice needs a referenceImage_* or character_* to attach to (or a V2V edit) — the API rejects referenceAudio_* on its own. // With start/end frames the check above already applies. if (!startImage && !endImage && !referenceVideo_1 && audioRefKeys.some(k => prompt[k]) && ![...imageRefKeys, ...characterKeys].some(k => prompt[k])) warnings.push(`⚠️ referenceAudio_* requires a referenceImage_* or character_* (or referenceVideo_1 for a V2V edit). Prompt ${i}`); await Promise.all([ validateFile(referenceVideo_1, supportedVideoExtensions), ...['startImage', 'endImage', ...imageRefKeys].map(k => validateFile(prompt[k], supportedImageExtensions)) ]); } if (warnings.length > 0) { warnings.forEach(warning => console.warn(warning)); console.error(`⛔ Execution stopped due to warnings.`); process.exit(1); } for (let i = 0; i < prompts.length; i++) { const prompt = prompts[i]; while (true) { const responseCode = await submitVideo(apiToken, email, prompt, i + 1); if (responseCode == 429 || responseCode == 503) await sleep(SLEEP_429); else if (responseCode == 402) { process.exit(1); } else break; } } } // Utility function to check if a file exists async function fileExists(path) { try { await fs.access(path); return true; } catch { return false; } } // Function to prompt user input async function promptUser(query) { const rl = readline.createInterface({ input: process.stdin, output: process.stdout }); return new Promise((resolve) => rl.question(query, answer => { rl.close(); resolve(answer); })); } function diffInMinutesAndSeconds(date1, date2) { const diffInSeconds = Math.floor((date2 - date1) / 1000); return `${Math.floor(diffInSeconds / 60)} minutes ${diffInSeconds % 60} seconds`; }; main(); ``` </details> ### Exemplos Os vídeos abaixo são resultados reais do Gemini Omni Flash feitos por esta Google Flow API — `model: "omni-flash-1.2"` e `model: "omni-flash"`, extensão, vozes, referências, personagens e edição V2V. ###### Extensão no Omni 1.2 — um vídeo de 10 segundos estendido duas vezes até 30 segundos, com duas vozes {: .no_toc #omni-12-extend--a-10-second-video-extended-twice-to-30-seconds-with-two-voices } <video poster="https://media.useapi.net/articles/2026-06-15-omni-flash-bash/261106-google-flow-omni-1-2-magician-extended-30s-web-poster.jpg" controls width="100%" style="max-width:640px;border-radius:8px"> <source src="https://media.useapi.net/articles/2026-06-15-omni-flash-bash/261106-google-flow-omni-1-2-magician-extended-30s-web.mp4" type="video/mp4"> </video> De [Google Flow: Omni 1.2 Flash, 15-Second Videos, and Extend with Voices](/blog/261106) (em inglês) — `omni-flash-1.2` nos primeiros 10 segundos, depois duas chamadas `POST /videos/extend` com `referenceAudio_1`. ###### Edição V2V — transforma um MP4 enviado em desenho animado, com o mesmo movimento e enquadramento {: .no_toc #v2v-edit--restyle-an-uploaded-mp4-into-a-cartoon-same-motion-and-framing } <video poster="https://media.useapi.net/blog/2026-05-20-260520/google-flow-edit-video-poster.jpg" controls width="100%" style="max-width:640px;border-radius:8px"> <source src="https://media.useapi.net/blog/2026-05-20-260520/google-flow-edit-video.mp4" type="video/mp4"> </video> De [Google Flow: Gemini Omni Flash](/blog/260520) (em inglês) — edição com `referenceVideo_1`. ###### Menções @ inline — vídeo noir R2V com @character_1, @referenceImage_1, @referenceImage_2 e uma voz personalizada {: .no_toc #inline--mentions--r2v-noir-video-with-character_1-referenceimage_1-referenceimage_2-and-a-custom-voice } <video poster="https://media.useapi.net/blog/2026-06-09-260609/noir-shot-1-poster.jpg" controls width="100%" style="max-width:640px;border-radius:8px"> <source src="https://media.useapi.net/blog/2026-06-09-260609/noir-shot-1.mp4" type="video/mp4"> </video> De [Google Flow: Inline @-mentions](/blog/260609) (em inglês) — marcadores de menção `@` inline ancorando cada referência. ###### Personagens + edição V2V — coloca dois personagens reutilizáveis no vídeo noir {: .no_toc #characters--v2v-edit--composites-two-reusable-characters-into-the-noir-video } <video poster="https://media.useapi.net/blog/2026-06-09-260609/edit-1-poster.jpg" controls width="100%" style="max-width:640px;border-radius:8px"> <source src="https://media.useapi.net/blog/2026-06-09-260609/edit-1.mp4" type="video/mp4"> </video> De [Google Flow: Inline @-mentions](/blog/260609) (em inglês) — edição V2V com `referenceVideo_1` e `@character_*` inline. Veja também [Reusable Voices and Characters](/blog/260605) (em inglês) para o fluxo de criação de vozes e personagens. ### Perguntas frequentes - **O que é o Gemini Omni Flash?** Com a useapi.net você roda o Gemini Omni Flash, o [modelo de vídeo com áudio nativo](https://deepmind.google/models/model-cards/gemini-omni-flash/) do Google no [Google Flow](https://flow.google.com), definindo `model: "omni-flash-1.2"` (Omni 1.2 Flash) ou `model: "omni-flash"` (Omni 1.1 Flash) na [Google Flow API](/docs/api-google-flow-v1). Ao contrário de um modelo de vídeo mudo, ele gera a trilha sonora, a narração, o diálogo e o ambiente como parte do mesmo vídeo, e aceita referências de imagem, vídeo e áudio, além de personagens reutilizáveis. - **Qual a diferença entre o Omni Flash e o Veo 3.1?** Com a useapi.net os dois rodam na mesma Google Flow API, escolhidos pelo campo `model`. O Veo é o motor de texto para vídeo e imagem para vídeo simples com mais fidelidade, e o Omni Flash tem áudio nativo e aceita muitas referências, com edição de vídeo para vídeo (`referenceVideo_1`), várias vozes por vídeo, personagens reutilizáveis em qualquer duração e vídeos mais longos que os do Veo. Veja os limites exatos em [Modos de referência](#reference-modes). - **Dá para usar a minha própria voz, um vídeo de referência ou um áudio de referência?** Com a useapi.net, sim. Narre com as vozes prontas do sistema ou com vozes personalizadas do [POST /voices](/docs/api-google-flow-v1/post-google-flow-voices), passadas como `referenceAudio_1..5`, e envie um MP4 com [POST /assets](/docs/api-google-flow-v1/post-google-flow-assets-email) para editá-lo como `referenceVideo_1` (V2V). Veja os limites de cada modo em [Modos de referência](#reference-modes) e [Vozes e personagens](#voices--characters). - **Existe uma API oficial do Omni Flash?** Com a useapi.net, o Omni 1.1 Flash custa bem menos do que na API do próprio Google: um vídeo de 8 segundos em 720p custa $0,10 no Google AI Ultra $199,99, contra $0,81 na [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) oficial, que vende o modelo por segundo desde 30 de junho de 2026 (em novembro de 2026). Ele roda por um endpoint REST padrão na sua assinatura do site Google Flow. - **O Omni Flash faz vídeos com mais de 10 segundos?** Com a useapi.net, sim: o Omni 1.2 Flash (`model: "omni-flash-1.2"`) gera até 15 segundos em uma chamada, e o [POST /videos/extend](/docs/api-google-flow-v1/post-google-flow-videos-extend) acrescenta até 10 segundos por vez com vozes, a $0,19 por um vídeo de 8 segundos em 720p no Google AI Ultra $199,99, contra $0,56 na [API do próprio Google](https://cloud.google.com/blog/products/ai-machine-learning/gemini-omni-1-2-flash-generally-available) (em novembro de 2026). Todos os limites de duração e preços no Google Flow e no Google Vids estão em [Como usar a API do Gemini Omni 1.2 Flash](/docs/articles/gemini-omni-1-2-flash-api-pt). - **Preciso resolver captcha?** Com a useapi.net você nunca resolve um captcha. O Google Flow pede um reCAPTCHA em cada vídeo e em cada voz nova, e o worker da useapi.net resolve automaticamente: a sua primeira conta Google Flow vem com 300 resoluções grátis nas nossas próprias chaves de AntiCaptcha, CapSolver e EzCaptcha, e depois disso você acrescenta as chaves do seu próprio provedor com [POST /accounts/captcha-providers](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers). O [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters) não precisa de captcha. ### Conclusão Visite o nosso <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> servidor no Discord</a> ou o <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> canal no Telegram</a> para qualquer dúvida de suporte. Veja o nosso [repositório no GitHub](https://github.com/useapi/google-flow-api) com exemplos de código. Um assistente de IA também pode trabalhar com o Google Flow por você: o [servidor MCP do Google Flow](/docs/api-google-flow-v1/mcp) hospedado permite que o Claude Code, o Cursor e o VS Code conversem com o Google Flow Agent, que gera imagens e vídeos na sua conta. ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/omni-flash-bash-th === Document URL: https://useapi.net/docs/articles/omni-flash-bash-th --- layout: default title: "วิธีสร้างวิดีโอ AI พร้อมเสียงในตัวด้วย Gemini Omni Flash ผ่าน Google Flow API" description: "ใช้ Gemini Omni Flash ผ่าน Google Flow API ของ useapi.net พร้อมโค้ด: ภาพอ้างอิง ตัวละคร เสียงพูด และการแก้ไขแบบ V2V บน Omni 1.2 และ 1.1 พร้อมสคริปต์สร้างเป็นชุด" keywords: [Gemini Omni Flash, Omni 1.2 Flash, Omni Flash API, omni-flash-1.2, Gemini Omni Flash API, Google Flow API, Omni Flash ภาษาไทย, วิดีโอ AI พร้อมเสียง, วิดีโอที่มีเสียงในตัว, ต่อความยาววิดีโอ, เสียงพูด, ตัวละคร, แก้ไขวิดีโอ, วิดีโอจากวิดีโอ, API สร้างวิดีโอ, curl, ตัวอย่างโค้ด, คู่มือ] parent: Articles nav_exclude: true lang: th translation_key: omni-flash date: 2026-06-15 last_modified: 2026-11-12 nav_order: 830 repo: https://github.com/useapi/google-flow-api --- ## วิธีสร้างวิดีโอ AI พร้อมเสียงในตัวด้วย Gemini Omni Flash ผ่าน Google Flow API {: .no_toc #how-to-generate-audio-native-ai-video-with-gemini-omni-flash-via-the-google-flow-api } อ่าน 8 นาที • 15 มิถุนายน 2026 (12 พฤศจิกายน 2026) useapi.net เป็น API ของบุคคลที่สาม (third-party) ไม่มีส่วนเกี่ยวข้องกับ Google และไม่ได้รับการรับรองจาก Google ## สารบัญ {: .no_toc .text-delta #table-of-contents } ### บทนำ [Gemini Omni Flash](https://deepmind.google/models/model-cards/gemini-omni-flash/) สร้างวิดีโอ AI ที่มีเสียงในตัวได้ด้วย `curl` คำสั่งเดียวผ่าน [Google Flow API](/docs/api-google-flow-v1) ของ useapi.net พร้อมเสียงพูดที่ซิงก์กับภาพ ตัวละคร และการแก้ไขวิดีโอจากวิดีโอ บนแพ็กเกจเว็บไซต์ [Google Flow](https://flow.google.com) ของคุณ ([Google AI](https://gemini.google/subscriptions/): Omni 1.1 Flash บน Plus, Pro หรือ Ultra และ Omni 1.2 Flash บนทุกแพ็กเกจ บัญชีฟรียาวได้ไม่เกิน 10 วินาที) วิดีโอ 720p ยาว 10 วินาทีราคา $0.12 บน Google AI Ultra $199.99 เทียบกับ $1.01 บน [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) ทางการ (ข้อมูล ณ พฤศจิกายน 2026) โดยไม่ต้องมีโปรเจกต์ Google Cloud หรือ API key แพ็กเกจเดียวกันนี้ยังสร้างวิดีโอ Omni ใน [Google Vids](/docs/api-google-vids-v1) ได้ด้วย โดยไม่ใช้เครดิต Flow ในหน้าเว็บ Google Flow โมเดลนี้ชื่อ Omni 1.1 Flash และค่าใน API คือ `model: "omni-flash"` ส่วน Omni 1.2 Flash ที่ Google เปิดตัวเมื่อ 5 พฤศจิกายน 2026 เป็นอีกค่าหนึ่ง คือ `model: "omni-flash-1.2"` ยาวได้ทุกความยาวตั้งแต่ 3 ถึง 15 วินาที คิดเครดิตต่อวินาที และเป็นโมเดลที่[ต่อความยาววิดีโอ](#extend-a-video-with-omni-12)ได้ครั้งละไม่เกิน 10 วินาที โค้ดที่ส่ง `omni-flash` จะยังได้ 1.1 ต่อไป ถ้าต้องการวิดีโอ 15 วินาที การต่อความยาวพร้อมเสียงพูด และราคาต่อวิดีโอใน Google Flow และ Google Vids ดู[วิธีใช้ Gemini Omni 1.2 Flash API](/docs/articles/gemini-omni-1-2-flash-api-th) Omni Flash ใช้ [Google Flow API ตัวเดียวกัน](/docs/api-google-flow-v1)กับ Veo เลือกด้วยฟิลด์เดียว คือ `model: "omni-flash-1.2"` หรือ `model: "omni-flash"` แต่เป็นโมเดลคนละแบบ Veo เก่งเรื่องสร้างวิดีโอจากข้อความล้วน ๆ ส่วน Omni Flash มีเสียงในตัวและรับข้อมูลอ้างอิงได้หลากหลาย: - เสียงถูกสร้างไปพร้อมกับวิดีโอ ทั้งเสียงบรรยาย บทพูด และเสียงบรรยากาศ มาจากโมเดลเดียวกัน ไม่ได้แปะเพิ่มทีหลัง - เสียงพูด มีพรีเซ็ตเสียงของระบบ 30 เสียง และเสียงที่คุณสร้างเองจากบทพูดและคำอธิบายการแสดงของคุณ ส่งผ่าน `referenceAudio_1..5` - ภาพและวิดีโออ้างอิง ภาพอ้างอิงสูงสุด 10 ภาพบน Omni 1.2 Flash (7 ภาพบน Omni 1.1 Flash) สำหรับวิดีโอจากภาพอ้างอิง (R2V) และการแก้ไขวิดีโอจากวิดีโอ (V2V) ของวิดีโอที่อัปโหลดหรือสร้างไว้ ผ่าน `referenceVideo_1` - ตัวละครที่ใช้ซ้ำได้ รวมภาพอ้างอิงกับเสียงเป็นตัวละครที่มีชื่อ แล้วใช้ซ้ำในหลายวิดีโอ - วิดีโอที่ยาวกว่า Omni 1.1 Flash สร้างได้ 4, 6, 8 หรือ 10 วินาที และ Omni 1.2 Flash ได้ทุกความยาวตั้งแต่ 3 ถึง 15 วินาที (Veo ยาวสุด `8`) และ Omni 1.2 ต่อความยาววิดีโอได้ครั้งละไม่เกิน 10 วินาที คู่มือนี้แสดงขั้นตอนเรียก API สองครั้งด้วย `curl` ที่คัดลอกไปใช้ได้เลย โหมดอ้างอิงที่ทำให้ Omni Flash ต่างจากโมเดลอื่น แล้วตามด้วยสคริปต์ Node.js ที่รันได้ทันทีสำหรับสร้างวิดีโอเป็นชุดจากรายการ prompt ถ้าต้องการสร้างวิดีโอจากข้อความอย่างเดียว ดู[คู่มือ Veo 3.1](/docs/articles/google-flow-bash-th) ### โมเดลที่รองรับ คู่มือนี้ใช้โมเดลวิดีโอที่มีเสียงในตัวของ Google คือ Omni 1.1 Flash (`model: "omni-flash"`) และ Omni 1.2 Flash (`model: "omni-flash-1.2"`) สำหรับ Omni 1.1 เครดิตที่ใช้เพิ่มตามความยาววิดีโอ: | ความยาว | เครดิตต่อวิดีโอ | |----------|------------------------| | 4s | 7 | | 6s | 10 | | 8s | 12 | | 10s | 15 | | แก้ไข V2V | 20 | นี่คือราคาที่ความละเอียดเริ่มต้น `720p` ถ้าส่ง `resolution: "360p"` จะใช้ราวครึ่งหนึ่ง คือ 4 / 5 / 6 / 7 เครดิตตามความยาว และ 10 สำหรับการแก้ไข V2V และวิดีโอ 360p ยังอัปสเกลเป็น 720p ทีหลังได้ด้วย [POST /videos/upscale](/docs/api-google-flow-v1/post-google-flow-videos-upscale) Omni 1.2 Flash (`model: "omni-flash-1.2"`) รับความยาวเป็นจำนวนวินาทีเต็มตั้งแต่ 3 ถึง 15 และคิดราคาต่อวินาที เท่ากันทุกแพ็กเกจ: | ความยาว | 720p | 360p | |--------|------|------| | 3s | 9 | 3 | | 8s | 24 | 8 | | 10s | 30 | 10 | | 15s | 60 | 20 | ถึง 10 วินาทีคิด 3 เครดิตต่อวินาทีที่ 720p และ 1 เครดิตที่ 360p ทุกวินาทีที่เกิน 10 คิดสองเท่า การแก้ไข V2V ราคาเท่ากับวิดีโอที่ยาวเท่าช่วงที่แก้ และ 1.2 แก้ไขคลิปได้สูงสุด 15 วินาที บัญชี Google ฟรีใช้ 1.2 สร้างวิดีโอยาวไม่เกิน 10 วินาทีได้ Omni Flash รับห้าโหมดบน [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) คือ วิดีโอจากข้อความ (T2V) วิดีโอจากภาพอ้างอิง (R2V) ด้วย `referenceImage_1..10` สูงสุด 10 ภาพบน Omni 1.2 Flash (7 ภาพบน Omni 1.1 Flash) วิดีโอจากภาพที่เริ่มจากเฟรมแรกผ่าน `startImage` (I2V) วิดีโอจากภาพระหว่างเฟรมเริ่มกับเฟรมจบผ่าน `startImage` + `endImage` (I2V-FL) และการแก้ไขวิดีโอจากวิดีโอ (V2V) ของ MP4 ที่อัปโหลดผ่าน `referenceVideo_1` ดู[โหมดอ้างอิง](#reference-modes)ด้านล่าง ### ราคา Omni 1.1 Flash ต้องใช้แพ็กเกจ Google AI แบบเสียเงิน (Plus, Pro หรือ Ultra) ส่วน Omni 1.2 Flash ใช้บนบัญชีฟรีได้ ยาวไม่เกิน 10 วินาที และ useapi.net ไม่คิดเงินต่อวิดีโอ วิดีโอแต่ละคลิปใช้เครดิต Flow ตามความยาว (ดู[โมเดลที่รองรับ](#supported-model)) ราคาต่อวิดีโอบนทุกแพ็กเกจเทียบกับ Gemini API ทางการอยู่ใน[ตารางราคา Google Flow](/docs/api-google-flow-v1#pricing) แพ็กเกจ Google AI ยังมาพร้อมโควตารายเดือนใน [Google Vids](https://docs.google.com/videos) ซึ่งสร้างวิดีโอยาวสูงสุด 15 วินาทีด้วย Gemini Omni 1.2 Flash ([ประกาศของ Google](https://workspaceupdates.googleblog.com/2026/11/gemini-omni-12-flash-now-in-vids-with-15second-generations-and-improved-quality.html)) และไม่ใช้เครดิต Flow บน Ultra $199.99 (Google เรียกว่า Ultra 20x) ได้วิดีโอ 10,000 วินาทีต่อเดือน หรือคลิป 1080p ยาว 10 วินาทีอีกราว 1,000 คลิป เพิ่มจากคลิป Omni 1.1 Flash ยาว 10 วินาทีราว 1,666 คลิป (หรือคลิป Omni 1.2 Flash ที่ 720p ราว 833 คลิป) ที่เครดิต Flow 25,000 เครดิตซื้อได้ วินาทีเหล่านี้ใช้ร่วมกันทุกคนในแพ็กเกจครอบครัวของ Google แพ็กเกจอื่นได้น้อยกว่า (ดูหน้า [Gemini ใน Google Vids](https://support.google.com/docs/answer/15609411?hl=th) ของ Google) และบัญชีฟรีที่เราทดสอบไม่ได้เลย [Google Vids API](/docs/api-google-vids-v1) ใช้โควตานี้โดยไม่มี captcha เชื่อมบัญชีได้ที่ [Setup Google Vids](/docs/start-here/setup-google-vids) ### สร้างวิดีโอด้วยการเรียก API สองครั้ง คุณต้องมี [API token](/docs/start-here/setup-useapi) ของ useapi.net และ[บัญชี Google Flow](/docs/start-here/setup-google-flow)ที่เชื่อมไว้แล้ว บนแพ็กเกจ Google AI แบบเสียเงิน (Plus, Pro หรือ Ultra) สำหรับตัวอย่าง Omni 1.1 Flash ด้านล่าง (Omni 1.2 Flash รันบนบัญชีฟรีได้ด้วย ยาวไม่เกิน 10 วินาที) งานวิดีโอเป็นแบบ asynchronous ส่ง `async: true` แล้วคำขอสร้างจะคืน `jobid` กลับมาทันที จากนั้นคุณ poll จนวิดีโอเสร็จ 1. ส่งงาน — `POST https://api.useapi.net/v1/google-flow/videos` ด้วย `model: "omni-flash"`: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A lighthouse keeper narrates the coming storm, waves crashing below", "model": "omni-flash", "aspectRatio": "landscape", "duration": 10, "async": true }' ``` Omni Flash มีเสียงในตัว จึงสร้างเสียงประกอบทั้งหมด ทั้งเสียงบรรยายของผู้ดูแลประภาคารและเสียงคลื่นซัด จาก prompt ได้โดยตรง ไม่ต้องใส่พารามิเตอร์เสียง ในโหมด async คำตอบกลับมาทันทีพร้อม `201 Created`, `jobid` ตัวพิมพ์เล็ก และ `status: "created"`: ```json { "jobid": "j1731859234567v-u12345-email:jo***@gmail.com-bot:google-flow", "type": "video", "status": "created", "created": "2026-06-15T12:34:56.789Z", "request": { "async": true, "prompt": "A lighthouse keeper narrates the coming storm, waves crashing below", "model": "omni-flash", "aspectRatio": "landscape", "duration": 10 } } ``` 2. poll ผลลัพธ์ — `GET https://api.useapi.net/v1/google-flow/jobs/{jobId}`: ```bash curl "https://api.useapi.net/v1/google-flow/jobs/JOBID" \ -H "Authorization: Bearer $USEAPI_TOKEN" ``` `status` เปลี่ยนจาก `created` → `started` → `completed` เมื่อถึง `completed` ไฟล์ MP4 ที่เสร็จแล้วจะอยู่ใน `response.media[].videoUrl` (prompt เดียวที่ใช้ `count > 1` จะคืนหนึ่งรายการต่อวิดีโอ): ```json { "jobid": "j1731859234567v-...", "type": "video", "status": "completed", "response": { "media": [ { "mediaGenerationId": "user:12345-email:6a6f...-video:a1d95d21-...", "videoUrl": "https://flow-content.google/video/a1d95d21-...?Expires=...", "thumbnailUrl": "https://flow-content.google/image/a1d95d21-...?Expires=..." } ], "remainingCredits": 18760 } } ``` โดยทั่วไป Omni Flash เสร็จใน 60–180 วินาที `videoUrl` ที่มีลายเซ็นใช้ได้ราว 6 ชั่วโมง จึงควรดาวน์โหลดทันที ไม่อยาก poll? ใส่ `replyUrl` ใน body ของคำขอสร้าง เพื่อรับ webhook callback เมื่องานเสร็จ ### โหมดอ้างอิง จุดเด่นของ Omni Flash คือรับข้อมูลอ้างอิงได้มาก ข้อมูลอ้างอิงทั้งหมดมาจาก endpoint อัปโหลด [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email) (หรือสำหรับตัวละคร มาจาก [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters)) คำตอบของการอัปโหลดเก็บ id อ้างอิงซ้อนไว้ที่ `mediaGenerationId.mediaGenerationId` สตริงที่ซ้อนอยู่นี้คือค่าที่คุณส่งกลับไป โหมดที่ `omni-flash` รับ (จากเอกสาร [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos#references)): | โหมด | พารามิเตอร์ | ขีดจำกัดของ Omni Flash | |------|--------------|------------------| | วิดีโอจากภาพอ้างอิง (R2V) | `referenceImage_1..10` | ภาพอ้างอิงสูงสุด 10 ภาพบน `omni-flash-1.2` และ 7 ภาพบน `omni-flash` | | วิดีโอจากภาพ (I2V) | `startImage` | เฟรมเริ่มหนึ่งเฟรม | | วิดีโอจากภาพ เฟรมแรก + เฟรมสุดท้าย (I2V-FL) | `startImage` + `endImage` | สองเฟรมนี้เท่านั้น ใส่ข้อมูลอ้างอิงอื่นไม่ได้ | | แก้ไขวิดีโอจากวิดีโอ (V2V) | `referenceVideo_1` (+ `startFrameIndex_1` / `endFrameIndex_1` ถ้าต้องการ) | MP4 ที่อัปโหลดหนึ่งไฟล์ | | ตัวละคร | `character_1..10` (จาก [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters)) | รวมกับ `referenceImage_*` ได้ทั้งหมด 10 บน `omni-flash-1.2` และ 7 บน `omni-flash` | | เสียงบรรยาย | `referenceAudio_1..5` | สูงสุด 5 (R2V) / สูงสุด 3 (แก้ไข V2V) | วิดีโอจากภาพอ้างอิง (R2V) อัปโหลดภาพหนึ่งภาพขึ้นไป แล้วส่งเป็น `referenceImage_1`, `referenceImage_2`, … (ช่อง `_4`..`_7` ใช้ได้เฉพาะ Omni Flash) ภาพอ้างอิงใช้ร่วมกับ `startImage`/`endImage` ไม่ได้ ```bash # 1. Upload a reference image — the id is nested one level deep: curl -X POST "https://api.useapi.net/v1/google-flow/assets/john%40gmail.com" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: image/jpeg" \ --data-binary @subject.jpeg # Response: { "mediaGenerationId": { "mediaGenerationId": "user:12345-email:...-image:..." }, ... } # 2. Generate, narrated by a system voice curl -X POST "https://api.useapi.net/v1/google-flow/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model": "omni-flash", "prompt": "the subject walks toward camera and introduces herself", "duration": 8, "referenceImage_1": "user:12345-email:...-image:...", "referenceAudio_1": "Kore" }' ``` แก้ไขวิดีโอจากวิดีโอ (V2V) อัปโหลด MP4 ด้วย `Content-Type: video/mp4` ไปที่ [POST /assets](/docs/api-google-flow-v1/post-google-flow-assets-email) แล้วส่ง id ที่ได้เป็น `referenceVideo_1` เพื่อแก้ไขวิดีโอนั้น โหมดนี้มีเฉพาะ Omni Flash และจะเปลี่ยนคำขอเป็นโหมด V2V ไม่รับ `duration` (ความยาวผลลัพธ์เท่ากับช่วงที่ตัดจากอินพุต สูงสุด 10 วินาทีบน `omni-flash` และ 15 วินาทีบน `omni-flash-1.2`) ถ้าต้องการ ตัดช่วงของวิดีโอต้นทางบนไทม์ไลน์เสมือน 24 fps ด้วย `startFrameIndex_1` (0–239) และ `endFrameIndex_1` (1–240 โดย 240 = 10 วินาที) หรือสูงสุด 359 และ 360 (15 วินาที) บน `omni-flash-1.2`: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model": "omni-flash", "prompt": "restyle the scene as a rainy neon-lit night, add ambient city sound", "referenceVideo_1": "user:12345-email:...-video:...", "startFrameIndex_1": 0, "endFrameIndex_1": 240, "async": true }' ``` คุณยังใส่เครื่องหมาย `@` ใน prompt ที่ชี้ไปยังช่องที่คุณส่งมาได้ด้วย เช่น `@referenceImage_1`, `@character_1`, `@referenceAudio_1` เครื่องหมายเหล่านี้ใส่หรือไม่ใส่ก็ได้ และแต่ละตัวต้องมีพารามิเตอร์ใน body ที่ตรงกัน (`@referenceVideo_*` ใช้ใน prompt ไม่ได้ ให้ส่งเป็นฟิลด์ใน body) ดู [Inline @-mention markers](/docs/api-google-flow-v1/post-google-flow-videos#inline--mention-markers-optional) ### เสียงพูดและตัวละคร การเรียกตั้งค่าสั้น ๆ สองครั้งเปิดใช้ความสามารถด้านเสียงและตัวตนของ Omni Flash เสียงที่สร้างเอง [POST /voices](/docs/api-google-flow-v1/post-google-flow-voices) บันทึกเสียงที่สร้างจากพรีเซ็ตของระบบหนึ่งใน 30 เสียง พร้อม `dialog` และ `voicePerformance` ของคุณเอง ฟิลด์ `voice` ในคำตอบคือ id อ้างอิงที่คุณส่งเป็น `referenceAudio_1..5` บน [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos): ```bash curl -X POST "https://api.useapi.net/v1/google-flow/voices" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "john@gmail.com", "voice": "Achernar", "dialog": "Welcome to the demo.", "voicePerformance": "Cheerful, energetic delivery", "displayName": "Cheerful Narrator" }' # Response: { "voice": "user:12345-email:...-voice:...-mid:...", ... } ``` แต่ละช่อง `referenceAudio_*` รับได้ทั้งชื่อเสียงของระบบ (ไม่สนตัวพิมพ์เล็กใหญ่ หนึ่งใน 30 พรีเซ็ต เช่น `Aoede`, `Kore`, `Puck`, `Zephyr`) หรือ id เสียงของผู้ใช้จากการเรียกด้านบน การสร้างเสียงต้องผ่าน reCAPTCHA (แก้ให้อัตโนมัติ ดู[คำถามที่พบบ่อย](#frequently-asked-questions)) ตัวละครที่ใช้ซ้ำได้ [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters) รวมภาพอ้างอิง 1–2 ภาพกับเสียง (ถ้าต้องการ) เป็นตัวละครที่มีชื่อ ฟิลด์ `character` ในคำตอบคือค่าที่คุณส่งเป็น `character_1..10`: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/characters" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "displayName": "Carol", "imageReference_1": "user:12345-email:...-image:abc123...", "voice": "user:12345-email:...-voice:...-mid:..." }' # Response: { "character": "user:12345-email:...-character:...-imgs:1-voice:...", ... } ``` บน Omni Flash ตัวละครใช้ได้ทุกความยาว และนับรวมในโควตาภาพอ้างอิง 10 ภาพร่วมกับ `referenceImage_*` (`referenceImages.length + Σ(character.imgs) ≤ 10`, Omni 1.1: 7) `POST /characters` ไม่ต้องใช้ captcha ตัวละครและเสียงใช้กับ Veo ได้ด้วย แต่มีโควตาน้อยกว่า (3 ภาพ 1 เสียง เฉพาะ 8 วินาที) ดู [What can use a character?](/docs/api-google-flow-v1/post-google-flow-characters#what-can-use-a-character) ### ต่อความยาววิดีโอด้วย Omni 1.2 [POST /videos/extend](/docs/api-google-flow-v1/post-google-flow-videos-extend) เพิ่มความยาวครั้งละ 3 ถึง 10 วินาทีด้วย Omni 1.2 Flash ให้วิดีโอใดก็ได้ที่สั้นกว่า 30 วินาที ใส่เสียง ภาพอ้างอิง หรือตัวละครได้สูงสุด 3 รายการ และคืนคลิปต่อเนื่องคลิปเดียว (เฉพาะแพ็กเกจเสียเงิน) ขั้นตอนใน[วิธีใช้ Gemini Omni 1.2 Flash API](/docs/articles/gemini-omni-1-2-flash-api-th#flow-walkthrough) ต่อความยาววิดีโอ 10 วินาทีสองครั้งจนได้ 30 วินาทีพร้อมสองเสียง ดู[ตัวอย่างด้านล่าง](#examples) ### สร้างวิดีโอเป็นชุดด้วยสคริปต์ กว่าจะได้เทคที่ใช่ต้องลองหลายครั้ง และการรันทีละครั้งด้วยมือก็น่าเบื่อ สคริปต์ Node.js ด้านล่างอ่านรายการ prompt จาก `prompts.json` อัปโหลดภาพอ้างอิง เฟรมเริ่มและเฟรมจบ หรือวิดีโอต้นทาง ส่ง id ของ `character_*` และ `resolution` ต่อไปตรง ๆ ส่งงานแต่ละงานในโหมด async ด้วย `model: "omni-flash"` แล้ว poll และดาวน์โหลด MP4 ทุกไฟล์ที่เสร็จ คุณจึงส่งงานไว้เป็นชุด แล้วค่อยกลับมาเลือกคลิปที่ดีที่สุด สคริปต์จะหยุดพร้อมคำเตือนก่อนส่งชุดค่าที่ API จะปฏิเสธ เช่น เฟรมจบที่ไม่มีเฟรมเริ่ม คุณต้องมี [Node.js](https://nodejs.org) v21 ขึ้นไป วาง `prompts.json` และ `omni-flash.mjs` ไว้ในโฟลเดอร์เดียวกัน แล้วรัน `node ./omni-flash.mjs API_TOKEN EMAIL` โดย `API_TOKEN` คือ [API token](/docs/start-here/setup-useapi) ของ useapi.net และ `EMAIL` คืออีเมลของ[บัญชี Google Flow](/docs/start-here/setup-google-flow)ที่เชื่อมไว้ สคริปต์ค้นหาบัญชีจากอีเมลให้เอง และตรวจฟิลด์ `health` ก่อนส่งงาน อยาก clone ไปรันบนเครื่องตัวเอง? ไฟล์ `omni-flash.mjs` และ `prompts.json` ฉบับเต็มอยู่บน GitHub ใน [`useapi/google-flow-api`](https://github.com/useapi/google-flow-api/tree/main/omni-flash) ใช้ Claude Code หรือ Codex อยู่? [agent skill omni-flash-video](https://github.com/useapi/google-flow-api/tree/main/skills/omni-flash-video) ให้ agent ทำทั้งหมดนี้แทนคุณ แค่บอกว่าต้องการวิดีโอแบบไหนและภาพอยู่ที่ไหน agent จะอัปโหลดภาพ เขียนคำขอ รอ และบันทึกไฟล์ `.mp4` ให้ ติดตั้งด้วย `npx skills add useapi/google-flow-api --skill omni-flash-video` <details markdown="block"> <summary>ขยาย `prompts.json`</summary> ```json [ { "prompt": "Audio-native text-to-video. By default model omni-flash with a landscape 8-second clip will be used." }, { "duration": 10, "prompt": "A 10-second clip (omni-flash only). Omni Flash is audio-native, so narration, dialogue and sound come from the prompt. To pin a specific voice, add referenceAudio_1 together with a referenceImage_* or character_*, as in the next prompt." }, { "duration": 8, "referenceImage_1": "./subject.jpeg", "referenceAudio_1": "Kore", "prompt": "Reference-to-video (R2V): the uploaded image is a reference, narrated by 'Kore'. Up to 7 referenceImage_* on omni-flash, 10 on omni-flash-1.2." }, { "duration": 8, "startImage": "./first_image.jpeg", "endImage": "./last_image.jpeg", "prompt": "Image-to-video with a start frame (startImage) and an end frame (endImage). The two frames are the only input — no referenceImage_*, character_* or referenceAudio_* alongside them." }, { "referenceVideo_1": "./source.mp4", "startFrameIndex_1": 0, "endFrameIndex_1": 240, "prompt": "Video-to-video edit (V2V): omni-flash restyles the uploaded MP4. No duration here — output matches the trim window (max 10 s). For all parameters see https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos" } ] ``` </details> <details markdown="block"> <summary>ขยายสคริปต์ `omni-flash.mjs`</summary> ```javascript /* Script version 1.3, November 11, 2026 Script to batch-generate audio-native videos with Gemini Omni Flash using the Google Flow API by useapi.net Uses the POST /videos endpoint in async mode (model: omni-flash by default, or omni-flash-1.2 per prompt) and polls GET /jobs/{jobId}. For more details visit https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos Installation Instructions: ========================== You need Node.js v21 or newer installed to run this script. Download and install Node.js from: - Windows, macOS, Linux: https://nodejs.org/ After installation, verify by running the following command in a terminal: node -v Running the Script: =================== Usage: node omni-flash.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE] Replace API_TOKEN with your actual useapi.net API token, see https://useapi.net/docs/start-here/setup-useapi Replace EMAIL with configured Google Flow email account, see https://useapi.net/docs/start-here/setup-google-flow If optional PROMPTS_FILE not provided prompts.json will be used. Example: -------- node omni-flash.mjs user:1234-abcdefhijklmnopqrstuv my@email.com This command executes the script using API token user:1234-abcdefhijklmnopqrstuv with my@email.com Google Flow account email. Changelog: ========== - June 15, 2026: Initial release. - September 11, 2026: Adds resolution, startImage / endImage (start and end frames, local files uploaded for you) and character_1..7. Accepts .jpg and upper-case file extensions. Stops with a warning before submitting combinations the API rejects, such as endImage without startImage or referenceAudio_* on its own. A prompt whose local startImage, endImage, referenceImage_* or referenceVideo_1 file fails to upload is skipped and logged to omni-flash_errors.txt instead of being submitted without it. Saves a downloaded video under its final name only once it has been fully received, so a failed download leaves no partial MP4 for the next run to skip as "already exists". - November 11, 2026: referenceImage_8..10 and character_8..10: omni-flash-1.2 takes up to 10 references (omni-flash 7). */ import readline from 'node:readline'; import fs from 'fs/promises'; import path from 'path'; import { writeFile } from 'node:fs/promises'; import { Readable } from 'node:stream'; // Constants const RESULTS_FILE = 'omni-flash_results.txt'; const ERRORS_FILE = 'omni-flash_errors.txt'; const DEFAULT_PROMPTS_FILE = 'prompts.json'; const MODEL = 'omni-flash'; // Reference slots: up to 10 on omni-flash-1.2, 7 on omni-flash, 3 on Veo (referenceImage_* and character_* together). const imageRefKeys = Array.from({ length: 10 }, (_, i) => `referenceImage_${i + 1}`); const characterKeys = Array.from({ length: 10 }, (_, i) => `character_${i + 1}`); const SLEEP_429 = 30 * 1000; // in milliseconds const SLEEP_POLL = 15 * 1000; // in milliseconds const urlAccounts = 'https://api.useapi.net/v1/google-flow/accounts'; const urlVideos = 'https://api.useapi.net/v1/google-flow/videos'; const urlJobs = 'https://api.useapi.net/v1/google-flow/jobs/'; const urlUploadAsset = 'https://api.useapi.net/v1/google-flow/assets/'; // Google Flow accepts png, jpeg and webp images, and mp4 video (for omni-flash V2V edit). const supportedImageExtensions = ['png', 'jpg', 'jpeg', 'webp']; const supportedVideoExtensions = ['mp4']; // { filename: mediaGenerationId } const uploadedFiles = {}; // Utility to sleep for given milliseconds const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); // Function to fetch configured Google Flow API accounts async function fetchAccounts(apiToken) { const response = await fetch(urlAccounts, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.error(`⛔ Error fetching accounts (HTTP ${response.status}): ${response.statusText}`); process.exit(1); } return response.json(); } const elapsedTimeSec = (start) => (Date.now() - start) / 1000; // Map a file extension to the Content-Type required by POST /assets const contentTypeForExt = (ext) => ext === 'png' ? 'image/png' : ext === 'webp' ? 'image/webp' : ext === 'mp4' ? 'video/mp4' : 'image/jpeg'; async function uploadAsset(apiToken, email, filename) { // Check if already uploaded if (uploadedFiles.hasOwnProperty(filename)) return uploadedFiles[filename]; const startTime = Date.now(); console.log(`⬆️ Account ${email} uploading file…`, filename); const body = new Blob([await fs.readFile(filename)]); const fileExt = filename.split('.').pop().toLowerCase(); const response = await fetch(`${urlUploadAsset}${encodeURIComponent(email)}`, { method: 'POST', headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}`, 'Content-Type': contentTypeForExt(fileExt) }, body }); if (response.ok) { const json = await response.json(); // POST /assets returns the reference id nested as mediaGenerationId.mediaGenerationId const mediaGenerationId = json?.mediaGenerationId?.mediaGenerationId; console.log(`🆗 mediaGenerationId (${elapsedTimeSec(startTime)} sec)`, mediaGenerationId); uploadedFiles[filename] = mediaGenerationId; } else { console.error(`❗ Unable to upload file HTTP ${response.status} (${elapsedTimeSec(startTime)} sec)`, await response.text()); // Do not attempt to upload failed file again uploadedFiles[filename] = undefined; } return uploadedFiles[filename]; } async function submit(apiToken, url, body, index, prompt) { const createResponse = await fetch(url, { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiToken}` }, body }); const createBody = await createResponse.text(); // Async POST /videos returns 201 Created with a jobid to poll. if (createResponse.status == 201) { const json = JSON.parse(createBody); // 201 async payload uses lowercase "jobid"; sync 200 uses "jobId". Accept either. const jobId = json.jobid ?? json.jobId; if (jobId) { await fs.appendFile(RESULTS_FILE, `${jobId},#${index}:${prompt}\n`); console.log(`✅ jobId`, jobId); return 201; } else { const error = `No jobid found in HTTP 201 response`; console.log(`❓ ${error}`, createBody); await fs.appendFile(ERRORS_FILE, `${error},#${index}:${prompt}\n`); return 500; } } else { switch (createResponse.status) { case 429: console.log(`🔄️ Retry on HTTP ${createResponse.status}`, createBody); break; case 503: console.log(`🔄️ Service unavailable, retry on HTTP ${createResponse.status}`, createBody); break; case 400: console.log(`🛑 Rejected request (validation or content policy)`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${prompt}\n`); break; case 402: console.log(`🛑 No subscription / insufficient credits`, createBody); break; default: console.log(`❗ FAILED with HTTP ${createResponse.status}`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${prompt}\n`); } return createResponse.status; } } // Submit a single prompt to POST /videos with model omni-flash (or the prompt's own model) in async mode. // startImage = start frame (I2V), endImage = end frame (I2V-FL, requires startImage) — the frames are the only input; // referenceImage_1..10 = R2V image refs; character_1..10 = POST /characters ids (10 on omni-flash-1.2, 7 on omni-flash); // referenceVideo_1 = V2V edit (no duration); referenceAudio_1..5 = system voice name or POST /voices user-voice id; // resolution = 720p (default) or 360p; model = 'omni-flash' (Omni 1.1, the default) or 'omni-flash-1.2' (3–15 s, per-second credits). async function submitVideo(apiToken, email, prompt, index) { const { prompt: text, model = MODEL, aspectRatio, duration, resolution, count, startImage, endImage, referenceVideo_1, startFrameIndex_1, endFrameIndex_1, referenceAudio_1, referenceAudio_2, referenceAudio_3, referenceAudio_4, referenceAudio_5 } = prompt; console.log(`🚀 ${model} » Prompt #${index} • account ${email} …`); // Upload any local image/video files and swap the paths for their mediaGenerationId. const resolveRef = async (ref) => ref && (ref.startsWith('./') || ref.includes('.')) && [...supportedImageExtensions, ...supportedVideoExtensions].includes(ref.split('.').pop().toLowerCase()) ? await uploadAsset(apiToken, email, ref) : ref; const startImageId = await resolveRef(startImage); const endImageId = await resolveRef(endImage); const refImages = {}; for (const key of imageRefKeys) refImages[key] = await resolveRef(prompt[key]); const refVideo_1 = await resolveRef(referenceVideo_1); // A local file that failed to upload would be left out of the body, and the prompt would still be // generated (and charged) without it. Skip the prompt instead. uploadAsset remembers the failed file, // so a later prompt using it is skipped too, without another upload attempt. const failedUploads = [ ['startImage', startImage, startImageId], ['endImage', endImage, endImageId], ...imageRefKeys.map(key => [key, prompt[key], refImages[key]]), ['referenceVideo_1', referenceVideo_1, refVideo_1] ].filter(([, file, id]) => file && !id); for (const [param, file] of failedUploads) { console.error(`🛑 Prompt #${index} skipped: ${param} ${file} failed to upload`); await fs.appendFile(ERRORS_FILE, `Upload failed for ${param} ${file},#${index}:${text}\n`); } if (failedUploads.length) return; // V2V edit does not accept duration — output matches the trim window. const isV2V = !!refVideo_1; const body = JSON.stringify({ model, email, prompt: text, aspectRatio, duration: isV2V ? undefined : duration, resolution, count, startImage: startImageId, endImage: endImageId, ...refImages, ...Object.fromEntries(characterKeys.map(key => [key, prompt[key]])), referenceVideo_1: refVideo_1, startFrameIndex_1, endFrameIndex_1, referenceAudio_1, referenceAudio_2, referenceAudio_3, referenceAudio_4, referenceAudio_5, async: true }); return await submit(apiToken, urlVideos, body, index, text); } // Function to download videos async function download(apiToken) { if (! await fileExists(RESULTS_FILE)) return; try { const resultsContent = await fs.readFile(RESULTS_FILE, 'utf8'); const lines = resultsContent.trim().split('\n'); for (const line of lines) { const [jobId, prompt] = line.split(','); console.log(`👉 ${jobId}`); while (true) { const response = await fetch(`${urlJobs}${jobId}`, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.log(`🛑 Poll failed ${jobId} (HTTP ${response.status}):\n${prompt}\n`, await response.text()); break; } const jobBody = await response.json(); const { status, error, response: jobResponse } = jobBody; if (status == 'failed') { console.error(`🛑 FAILED ${jobId} (${error}):\n${prompt}\n`); break; } if (status == 'completed') { const media = jobResponse?.media ?? []; if (media.length == 0) console.error(`🛑 Completed but no media for ${jobId}:\n${prompt}\n`); // A single prompt with count > 1 returns multiple videos. for (let i = 0; i < media.length; i++) { const url = media[i]?.videoUrl; const videoFilename = `${jobId.replace(/[:*]/g, '_')}_${i + 1}.mp4`; try { await fs.access(videoFilename); console.log(`⚠️ ${videoFilename} already exists. Skipping download.`); continue; } catch { // File does not exist, proceed with downloading } if (url) { console.log(`✅ Downloading ${url} to ${videoFilename}`); // Stream into a temporary file and rename it once the whole video has arrived, so a download // that drops mid-stream leaves no partial file behind for the next run to skip as "already exists". const tempFilename = `${videoFilename}.part`; try { const videoResponse = await fetch(url); if (!videoResponse.ok) { console.error(`⛔ Unable to download ${jobId} (HTTP ${videoResponse.status}):\n${prompt}\n`, url); continue; } const stream = Readable.fromWeb(videoResponse.body); await writeFile(tempFilename, stream); await fs.rename(tempFilename, videoFilename); } catch (err) { await fs.rm(tempFilename, { force: true }); console.error(`⛔ Error during download: ${err}`); } } else console.error(`🛑 No videoUrl for ${jobId} media #${i + 1}:\n${prompt}\n`); } break; } console.log(`⌛ ${jobId} status (${status}) and is still in progress, waiting…`); await sleep(SLEEP_POLL); } } } catch (error) { console.log(`⛔ Error during download:`, error.stack || error); } } // Main function async function main() { const apiToken = process.argv[2]; const email = process.argv[3]; const promptFile = process.argv[4] || DEFAULT_PROMPTS_FILE; if (!apiToken || !email) { console.error('Usage: node omni-flash.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE]'); process.exit(1); } console.info('Script v1.3'); console.info('Node version is: ' + process.version); try { if (await fileExists(RESULTS_FILE)) { let user_input; while (!['y', 'n'].includes(user_input)) { user_input = (await promptUser(`❔ ${RESULTS_FILE} file detected. Do you want to download the results now? (y/n): `))?.toLowerCase(); if (user_input == 'y') { await download(apiToken); await fs.unlink(RESULTS_FILE); } } } const start = new Date(); try { console.info('START EXECUTION', start); await execute(apiToken, email, promptFile); // Pass the promptFile to execute function } finally { console.info('COMPLETED', new Date()); console.info('EXECUTION ELAPSED', diffInMinutesAndSeconds(start, new Date())); } try { console.info('START DOWNLOAD', start); await download(apiToken); } finally { console.info('TOTAL ELAPSED', diffInMinutesAndSeconds(start, new Date())); } } catch (error) { console.error('⛔ Error during execution:', error.stack || error); } } // Modify the execute function to accept promptFile as a parameter async function execute(apiToken, email, promptFile) { const accounts = await fetchAccounts(apiToken); console.info(`Configured Google Flow API accounts (${Object.keys(accounts).length}):`, Object.keys(accounts).join(', ')); if (Object.keys(accounts).length <= 0) { console.error(`⛔ No configured Google Flow accounts found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (!accounts[email]) { console.error(`⛔ Account ${email} not found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (accounts[email].health && accounts[email].health !== 'OK') { console.error(`⛔ Account ${email} health is '${accounts[email].health}'. Please resolve and update the account, see https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } const promptData = await fs.readFile(promptFile, 'utf8'); const prompts = JSON.parse(promptData); console.log(`Total number of prompts to process`, prompts.length); let warnings = []; // Parameters accepted by this script for the omni-flash POST /videos endpoint. // See https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos for the full parameter set. const supportedParams = [ 'prompt', 'model', 'aspectRatio', 'duration', 'resolution', 'count', 'startImage', 'endImage', ...imageRefKeys, ...characterKeys, 'referenceVideo_1', 'startFrameIndex_1', 'endFrameIndex_1', 'referenceAudio_1', 'referenceAudio_2', 'referenceAudio_3', 'referenceAudio_4', 'referenceAudio_5' ]; const audioRefKeys = ['referenceAudio_1', 'referenceAudio_2', 'referenceAudio_3', 'referenceAudio_4', 'referenceAudio_5']; const invalidKeys = (prompt) => Object.keys(prompt).filter(key => !key.startsWith('__') && !supportedParams.includes(key)) // Validate a local file path reference (skip already-uploaded mediaGenerationId strings). const looksLikePath = (ref) => ref && (ref.startsWith('./') || (ref.includes('.') && !ref.startsWith('user:'))); for (let i = 1; i <= prompts.length; i++) { const prompt = prompts[i - 1]; const { prompt: text, referenceVideo_1, duration, startImage, endImage } = prompt; const validateFile = async (file, allowedExts) => { if (looksLikePath(file)) { try { await fs.access(file); } catch { warnings.push(`⚠️ File '${file}' does not exist. Prompt ${i}`); } const ext = file.split('.').pop().toLowerCase(); if (!allowedExts.includes(ext)) warnings.push(`⚠️ File ${file} extension ${ext} not supported. Prompt ${i}`); } }; const notSupported = invalidKeys(prompt); if (notSupported.length) warnings.push(`⚠️ Following params not supported: ${notSupported.join(',')}. Prompt ${i}`); if (!text) warnings.push(`⚠️ prompt is required. Prompt ${i}`); // V2V edit (referenceVideo_1) does not accept duration — output matches the trim window. if (referenceVideo_1 && duration) warnings.push(`⚠️ duration is not accepted with referenceVideo_1 (V2V edit). Prompt ${i}`); if (endImage && !startImage) warnings.push(`⚠️ endImage requires startImage (end-frame-only is not supported). Prompt ${i}`); // Start/end frames (I2V, I2V-FL) are the only input in that mode — the API rejects anything alongside them. if (startImage || endImage) { if (referenceVideo_1) warnings.push(`⚠️ startImage/endImage cannot be combined with referenceVideo_1 (V2V edit). Prompt ${i}`); if ([...imageRefKeys, ...characterKeys].some(k => prompt[k])) warnings.push(`⚠️ startImage/endImage cannot be combined with referenceImage_* or character_*. Prompt ${i}`); if (audioRefKeys.some(k => prompt[k])) warnings.push(`⚠️ startImage/endImage cannot be combined with referenceAudio_*. Prompt ${i}`); } // A voice needs a referenceImage_* or character_* to attach to (or a V2V edit) — the API rejects referenceAudio_* on its own. // With start/end frames the check above already applies. if (!startImage && !endImage && !referenceVideo_1 && audioRefKeys.some(k => prompt[k]) && ![...imageRefKeys, ...characterKeys].some(k => prompt[k])) warnings.push(`⚠️ referenceAudio_* requires a referenceImage_* or character_* (or referenceVideo_1 for a V2V edit). Prompt ${i}`); await Promise.all([ validateFile(referenceVideo_1, supportedVideoExtensions), ...['startImage', 'endImage', ...imageRefKeys].map(k => validateFile(prompt[k], supportedImageExtensions)) ]); } if (warnings.length > 0) { warnings.forEach(warning => console.warn(warning)); console.error(`⛔ Execution stopped due to warnings.`); process.exit(1); } for (let i = 0; i < prompts.length; i++) { const prompt = prompts[i]; while (true) { const responseCode = await submitVideo(apiToken, email, prompt, i + 1); if (responseCode == 429 || responseCode == 503) await sleep(SLEEP_429); else if (responseCode == 402) { process.exit(1); } else break; } } } // Utility function to check if a file exists async function fileExists(path) { try { await fs.access(path); return true; } catch { return false; } } // Function to prompt user input async function promptUser(query) { const rl = readline.createInterface({ input: process.stdin, output: process.stdout }); return new Promise((resolve) => rl.question(query, answer => { rl.close(); resolve(answer); })); } function diffInMinutesAndSeconds(date1, date2) { const diffInSeconds = Math.floor((date2 - date1) / 1000); return `${Math.floor(diffInSeconds / 60)} minutes ${diffInSeconds % 60} seconds`; }; main(); ``` </details> ### ตัวอย่าง วิดีโอด้านล่างเป็นผลลัพธ์จริงของ Gemini Omni Flash ที่สร้างผ่าน Google Flow API นี้ ทั้ง `model: "omni-flash-1.2"` และ `model: "omni-flash"` การต่อความยาว เสียงพูด ภาพอ้างอิง ตัวละคร และการแก้ไข V2V ###### ต่อความยาวด้วย Omni 1.2 » วิดีโอ 10 วินาทีต่อความยาวสองครั้งจนได้ 30 วินาที พร้อมสองเสียง {: .no_toc #omni-12-extend--a-10-second-video-extended-twice-to-30-seconds-with-two-voices } <video poster="https://media.useapi.net/articles/2026-06-15-omni-flash-bash/261106-google-flow-omni-1-2-magician-extended-30s-web-poster.jpg" controls width="100%" style="max-width:640px;border-radius:8px"> <source src="https://media.useapi.net/articles/2026-06-15-omni-flash-bash/261106-google-flow-omni-1-2-magician-extended-30s-web.mp4" type="video/mp4"> </video> จาก [Google Flow: Omni 1.2 Flash, 15-Second Videos, and Extend with Voices](/blog/261106) ใช้ `omni-flash-1.2` สำหรับ 10 วินาทีแรก แล้วเรียก `POST /videos/extend` สองครั้งพร้อม `referenceAudio_1` ###### แก้ไข V2V » เปลี่ยน MP4 ที่อัปโหลดเป็นการ์ตูน คงการเคลื่อนไหวและมุมกล้องเดิม {: .no_toc #v2v-edit--restyle-an-uploaded-mp4-into-a-cartoon-same-motion-and-framing } <video poster="https://media.useapi.net/blog/2026-05-20-260520/google-flow-edit-video-poster.jpg" controls width="100%" style="max-width:640px;border-radius:8px"> <source src="https://media.useapi.net/blog/2026-05-20-260520/google-flow-edit-video.mp4" type="video/mp4"> </video> จาก [Google Flow: Gemini Omni Flash](/blog/260520) แก้ไขด้วย `referenceVideo_1` ###### Inline @-mentions » วิดีโอ R2V แนวฟิล์มนัวร์ด้วย @character_1, @referenceImage_1, @referenceImage_2 และเสียงที่สร้างเอง {: .no_toc #inline--mentions--r2v-noir-video-with-character_1-referenceimage_1-referenceimage_2-and-a-custom-voice } <video poster="https://media.useapi.net/blog/2026-06-09-260609/noir-shot-1-poster.jpg" controls width="100%" style="max-width:640px;border-radius:8px"> <source src="https://media.useapi.net/blog/2026-06-09-260609/noir-shot-1.mp4" type="video/mp4"> </video> จาก [Google Flow: Inline @-mentions](/blog/260609) ใช้เครื่องหมาย `@` ใน prompt ผูกข้อมูลอ้างอิงแต่ละรายการ ###### ตัวละคร + แก้ไข V2V » ใส่ตัวละครที่ใช้ซ้ำได้สองตัวลงในวิดีโอฟิล์มนัวร์ {: .no_toc #characters--v2v-edit--composites-two-reusable-characters-into-the-noir-video } <video poster="https://media.useapi.net/blog/2026-06-09-260609/edit-1-poster.jpg" controls width="100%" style="max-width:640px;border-radius:8px"> <source src="https://media.useapi.net/blog/2026-06-09-260609/edit-1.mp4" type="video/mp4"> </video> จาก [Google Flow: Inline @-mentions](/blog/260609) แก้ไข V2V ด้วย `referenceVideo_1` พร้อม `@character_*` ใน prompt ดูขั้นตอนตั้งค่าเสียงและตัวละครได้ที่ [Reusable Voices and Characters](/blog/260605) ### คำถามที่พบบ่อย - **Gemini Omni Flash คืออะไร?** ผ่าน useapi.net คุณรัน Gemini Omni Flash ซึ่งเป็น[โมเดลวิดีโอที่มีเสียงในตัว](https://deepmind.google/models/model-cards/gemini-omni-flash/)ของ Google ใน [Google Flow](https://flow.google.com) ได้ด้วยการตั้ง `model: "omni-flash-1.2"` (Omni 1.2 Flash) หรือ `model: "omni-flash"` (Omni 1.1 Flash) บน [Google Flow API](/docs/api-google-flow-v1) ต่างจากโมเดลวิดีโอที่ไม่มีเสียง โมเดลนี้สร้างเสียงประกอบ เสียงบรรยาย บทพูด และเสียงบรรยากาศ ไปในวิดีโอเดียวกัน และรับภาพ วิดีโอ และเสียงอ้างอิง รวมถึงตัวละครที่ใช้ซ้ำได้ - **Omni Flash ต่างจาก Veo 3.1 อย่างไร?** ผ่าน useapi.net ทั้งสองโมเดลรันบน Google Flow API ตัวเดียวกัน เลือกด้วยฟิลด์ `model` Veo ให้ภาพคมกว่าสำหรับวิดีโอจากข้อความและวิดีโอจากภาพแบบปกติ ส่วน Omni Flash มีเสียงในตัวและรับข้อมูลอ้างอิงได้หลากหลาย ทั้งแก้ไขวิดีโอจากวิดีโอ (`referenceVideo_1`) ใส่หลายเสียงต่อวิดีโอ ใช้ตัวละครซ้ำได้ทุกความยาว และสร้างวิดีโอที่ยาวกว่า Veo ดูขีดจำกัดที่แน่นอนใน[โหมดอ้างอิง](#reference-modes) - **ใช้เสียงของตัวเอง วิดีโออ้างอิง หรือเสียงอ้างอิงได้ไหม?** ผ่าน useapi.net ได้ ใส่เสียงบรรยายด้วยเสียงในตัวของระบบ หรือเสียงที่สร้างเองจาก [POST /voices](/docs/api-google-flow-v1/post-google-flow-voices) ส่งเป็น `referenceAudio_1..5` และอัปโหลด MP4 ด้วย [POST /assets](/docs/api-google-flow-v1/post-google-flow-assets-email) เพื่อแก้ไขเป็น `referenceVideo_1` (V2V) ดูขีดจำกัดของแต่ละโหมดใน[โหมดอ้างอิง](#reference-modes)และ[เสียงพูดและตัวละคร](#voices--characters) - **Omni Flash มี API ทางการไหม?** ผ่าน useapi.net Omni 1.1 Flash ถูกกว่า API ของ Google เองมาก วิดีโอ 720p ยาว 8 วินาทีราคา $0.10 บน Google AI Ultra $199.99 เทียบกับ $0.81 บน [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) ทางการ ที่ขายโมเดลนี้แบบคิดต่อวินาทีมาตั้งแต่ 30 มิถุนายน 2026 (ข้อมูล ณ พฤศจิกายน 2026) โดยรันผ่าน REST endpoint มาตรฐานบนแพ็กเกจเว็บไซต์ Google Flow ของคุณ - **Omni Flash สร้างวิดีโอยาวกว่า 10 วินาทีได้ไหม?** ผ่าน useapi.net ได้ Omni 1.2 Flash (`model: "omni-flash-1.2"`) สร้างได้สูงสุด 15 วินาทีในคำสั่งเดียว และ [POST /videos/extend](/docs/api-google-flow-v1/post-google-flow-videos-extend) เพิ่มได้ครั้งละไม่เกิน 10 วินาทีพร้อมเสียงพูด วิดีโอ 720p ยาว 8 วินาทีราคา $0.19 บน Google AI Ultra $199.99 เทียบกับ $0.56 บน [API ของ Google เอง](https://cloud.google.com/blog/products/ai-machine-learning/gemini-omni-1-2-flash-generally-available) (ข้อมูล ณ พฤศจิกายน 2026) ขีดจำกัดความยาวและราคาทั้งหมดใน Google Flow และ Google Vids อยู่ใน[วิธีใช้ Gemini Omni 1.2 Flash API](/docs/articles/gemini-omni-1-2-flash-api-th) - **ต้องแก้ captcha เองไหม?** ผ่าน useapi.net คุณไม่ต้องแก้เองเลย Google Flow ขอ reCAPTCHA ทุกครั้งที่สร้างวิดีโอและทุกครั้งที่สร้างเสียงใหม่ และ worker ของ useapi.net แก้ให้อัตโนมัติ บัญชี Google Flow บัญชีแรกของคุณได้แก้ฟรี 300 ครั้งด้วยคีย์ AntiCaptcha, CapSolver และ EzCaptcha ของเราเอง หลังจากนั้นคุณเพิ่มคีย์ผู้ให้บริการของคุณเองด้วย [POST /accounts/captcha-providers](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers) ส่วน [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters) ไม่ต้องใช้ captcha ### สรุป ติดต่อเราได้ที่ <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> หรือ <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> สำหรับทุกคำถามและข้อสงสัยด้านการใช้งาน ดูตัวอย่างโค้ดได้ใน [GitHub repo](https://github.com/useapi/google-flow-api) ของเรา ผู้ช่วย AI ยังทำงานกับ Google Flow แทนคุณได้ด้วย [Google Flow MCP server](/docs/api-google-flow-v1/mcp) แบบโฮสต์ให้ Claude Code, Cursor และ VS Code แชตกับ Google Flow Agent ซึ่งสร้างภาพและวิดีโอบนบัญชีของคุณ ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/omni-flash-bash-vi === Document URL: https://useapi.net/docs/articles/omni-flash-bash-vi --- layout: default title: "Cách tạo video AI có âm thanh gốc bằng Gemini Omni Flash qua Google Flow API" description: "Gemini Omni Flash trong Google Flow API của useapi.net, kèm code: ảnh tham chiếu, nhân vật, giọng nói và chỉnh sửa V2V trên Omni 1.2 và 1.1, cùng một script chạy hàng loạt." keywords: [Gemini Omni Flash, Omni 1.2 Flash, Omni 1.1 Flash, Omni Flash API, Gemini Omni Flash API, omni-flash-1.2, Google Flow API, video AI có âm thanh gốc, video AI có lời thoại, kéo dài video, giọng nói, nhân vật, chỉnh sửa video, tạo video AI bằng API, hướng dẫn Omni Flash, audio-native video, hướng dẫn, code] parent: Articles nav_exclude: true lang: vi translation_key: omni-flash date: 2026-06-15 last_modified: 2026-11-12 nav_order: 830 repo: https://github.com/useapi/google-flow-api --- ## Cách tạo video AI có âm thanh gốc bằng Gemini Omni Flash qua Google Flow API {: .no_toc #how-to-generate-audio-native-ai-video-with-gemini-omni-flash-via-the-google-flow-api } 8 phút đọc • 15 tháng 6 năm 2026 (12 tháng 11 năm 2026) useapi.net là API của bên thứ ba, không liên kết với Google và không được Google bảo trợ. ## Mục lục {: .no_toc .text-delta #table-of-contents } ### Giới thiệu [Gemini Omni Flash](https://deepmind.google/models/model-cards/gemini-omni-flash/) tạo video AI có âm thanh gốc chỉ với một lệnh `curl` qua [Google Flow API](/docs/api-google-flow-v1) của useapi.net, có giọng nói đồng bộ, nhân vật và chỉnh sửa video sang video, trên gói đăng ký website [Google Flow](https://flow.google.com) của bạn ([Google AI](https://gemini.google/subscriptions/): Omni 1.1 Flash trên Plus, Pro hoặc Ultra, Omni 1.2 Flash trên mọi gói, tài khoản miễn phí tối đa 10 giây). Một video 720p dài 10 giây tốn $0,12 trên Google AI Ultra $199,99, so với $1,01 trên [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) chính thức (tính đến tháng 11/2026), và không cần dự án Google Cloud hay API key. Cùng gói đăng ký đó cũng tạo được video Omni trong [Google Vids](/docs/api-google-vids-v1) mà không tốn credit Flow. Trong giao diện, Google Flow gọi model này là Omni 1.1 Flash, còn giá trị trong API là `model: "omni-flash"`. Omni 1.2 Flash, được Google phát hành ngày 5 tháng 11 năm 2026, là một giá trị riêng, `model: "omni-flash-1.2"`: độ dài bất kỳ từ 3 đến 15 giây, credit tính theo giây, và là model [kéo dài video](#extend-a-video-with-omni-12) thêm tối đa 10 giây mỗi lần. Code gửi `omni-flash` vẫn tiếp tục nhận bản 1.1. Về video 15 giây, kéo dài có giọng nói và giá mỗi video trong Google Flow và Google Vids, xem [Cách dùng Gemini Omni 1.2 Flash API](/docs/articles/gemini-omni-1-2-flash-api-vi). Omni Flash dùng [cùng Google Flow API](/docs/api-google-flow-v1) với Veo, được chọn bằng một trường duy nhất — `model: "omni-flash-1.2"` hoặc `model: "omni-flash"` — nhưng là một loại model khác. Veo mạnh ở việc tạo video thuần từ văn bản, còn Omni Flash có âm thanh gốc và nhận rất nhiều loại tham chiếu: - Âm thanh được tạo cùng với video — lời thuyết minh, hội thoại và âm thanh nền đến từ chính model đó, không phải ghép vào sau. - Giọng nói — 30 giọng hệ thống có sẵn, cộng với giọng tùy chỉnh bạn tạo từ lời thoại và ghi chú diễn xuất của riêng mình, truyền vào qua `referenceAudio_1..5`. - Tham chiếu ảnh và video — tối đa 10 ảnh tham chiếu trên Omni 1.2 Flash (7 trên Omni 1.1 Flash) để tạo video từ ảnh tham chiếu (R2V), và chỉnh sửa video sang video (V2V) một video tải lên hoặc đã tạo qua `referenceVideo_1`. - Nhân vật dùng lại được — gộp ảnh tham chiếu và một giọng thành một nhân vật có tên rồi dùng lại trong nhiều video. - Video dài hơn — Omni 1.1 Flash làm video 4, 6, 8 hoặc 10 giây, Omni 1.2 Flash làm độ dài bất kỳ từ 3 đến 15 (Veo tối đa là `8`), và Omni 1.2 kéo dài video theo từng bước tối đa 10 giây. Bài hướng dẫn này trình bày quy trình hai lệnh gọi với `curl` sao chép là chạy, các chế độ tham chiếu làm nên nét riêng của Omni Flash, rồi một script Node.js chạy được để tạo hàng loạt từ danh sách prompt. Để tạo video thuần từ văn bản, xem [hướng dẫn Veo 3.1](/docs/articles/google-flow-bash-vi) cùng loạt. ### Model được hỗ trợ Bài này dùng các model video có âm thanh gốc của Google, Omni 1.1 Flash (`model: "omni-flash"`) và Omni 1.2 Flash (`model: "omni-flash-1.2"`). Với Omni 1.1, số credit tăng theo độ dài video: | Độ dài | Credit mỗi video | |----------|------------------------| | 4s | 7 | | 6s | 10 | | 8s | 12 | | 10s | 15 | | Chỉnh sửa V2V | 20 | Đó là mức tốn ở `720p` mặc định. Truyền `resolution: "360p"` tốn khoảng một nửa — 4 / 5 / 6 / 7 credit theo độ dài, 10 cho một lần chỉnh sửa V2V — và video 360p có thể nâng lên 720p sau đó bằng [POST /videos/upscale](/docs/api-google-flow-v1/post-google-flow-videos-upscale). Omni 1.2 Flash (`model: "omni-flash-1.2"`) nhận mọi số giây nguyên từ 3 đến 15 và tính giá theo giây, như nhau trên mọi gói: | Độ dài | 720p | 360p | |--------|------|------| | 3s | 9 | 3 | | 8s | 24 | 8 | | 10s | 30 | 10 | | 15s | 60 | 20 | Tới 10 giây, mức tốn là 3 credit mỗi giây ở 720p và 1 ở 360p, và mỗi giây sau giây thứ 10 tốn gấp đôi. Một lần chỉnh sửa V2V tốn bằng một video có cùng độ dài với phần được chỉnh, và bản 1.2 chỉnh sửa được tối đa 15 giây của một clip. Tài khoản Google miễn phí dùng được 1.2 cho video tối đa 10 giây. Omni Flash nhận năm chế độ trên [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos): tạo video thuần từ văn bản (T2V), tạo video từ ảnh tham chiếu (R2V) với tối đa 10 `referenceImage_1..10` trên Omni 1.2 Flash (7 trên Omni 1.1 Flash), tạo video từ một khung đầu qua `startImage` (I2V), tạo video giữa khung đầu và khung cuối qua `startImage` + `endImage` (I2V-FL), và chỉnh sửa video sang video (V2V) một file MP4 tải lên qua `referenceVideo_1`. Xem [Các chế độ tham chiếu](#reference-modes) bên dưới. ### Giá Omni 1.1 Flash cần gói Google AI trả phí (Plus, Pro hoặc Ultra), Omni 1.2 Flash chạy trên tài khoản miễn phí với video tối đa 10 giây, và useapi.net không thu phí theo video. Mỗi video dùng credit Flow theo độ dài (xem [Model được hỗ trợ](#supported-model)). Giá mỗi video trên từng gói, so với Gemini API chính thức, có trong [bảng giá Google Flow](/docs/api-google-flow-v1#pricing). Gói Google AI còn đi kèm một hạn mức hằng tháng trong [Google Vids](https://docs.google.com/videos), nơi tạo video dài tới 15 giây bằng Gemini Omni 1.2 Flash ([thông báo của Google](https://workspaceupdates.googleblog.com/2026/11/gemini-omni-12-flash-now-in-vids-with-15second-generations-and-improved-quality.html)) mà không dùng credit Flow. Trên Ultra $199,99 (Google gọi là Ultra 20x), hạn mức là 10.000 giây video mỗi tháng — thêm khoảng 1.000 clip 10 giây ở 1080p, ngoài khoảng 1.666 clip Omni 1.1 Flash dài 10 giây (hoặc khoảng 833 clip Omni 1.2 Flash ở 720p) mà 25.000 credit của Flow mua được. Số giây này được dùng chung bởi mọi người trong gói gia đình Google. Các gói khác được ít hơn (xem trang [Gemini trong Google Vids](https://support.google.com/docs/answer/15609411?hl=vi) của Google), và các tài khoản miễn phí chúng tôi thử nghiệm không có giây nào. [Google Vids API](/docs/api-google-vids-v1) dùng hạn mức này mà không cần captcha. Kết nối tài khoản theo [Setup Google Vids](/docs/start-here/setup-google-vids). ### Tạo video bằng hai lệnh gọi API Bạn cần một [API token](/docs/start-here/setup-useapi) của useapi.net và một [tài khoản Google Flow](/docs/start-here/setup-google-flow) đã kết nối, dùng gói Google AI trả phí (Plus, Pro hoặc Ultra) cho ví dụ Omni 1.1 Flash bên dưới (Omni 1.2 Flash cũng chạy trên tài khoản miễn phí, tối đa 10 giây). Job video chạy bất đồng bộ: truyền `async: true` và lệnh tạo trả về `jobid` ngay, sau đó bạn polling cho tới khi video sẵn sàng. 1. Gửi job — `POST https://api.useapi.net/v1/google-flow/videos` với `model: "omni-flash"`: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A lighthouse keeper narrates the coming storm, waves crashing below", "model": "omni-flash", "aspectRatio": "landscape", "duration": 10, "async": true }' ``` Omni Flash có âm thanh gốc, nên nó tạo luôn phần âm thanh — lời thuyết minh của người gác hải đăng và tiếng sóng vỗ — thẳng từ prompt, không cần tham số âm thanh nào. Ở chế độ async, phản hồi trả về ngay với `201 Created`, một `jobid` viết thường và `status: "created"`: ```json { "jobid": "j1731859234567v-u12345-email:jo***@gmail.com-bot:google-flow", "type": "video", "status": "created", "created": "2026-06-15T12:34:56.789Z", "request": { "async": true, "prompt": "A lighthouse keeper narrates the coming storm, waves crashing below", "model": "omni-flash", "aspectRatio": "landscape", "duration": 10 } } ``` 2. Polling lấy kết quả — `GET https://api.useapi.net/v1/google-flow/jobs/{jobId}`: ```bash curl "https://api.useapi.net/v1/google-flow/jobs/JOBID" \ -H "Authorization: Bearer $USEAPI_TOKEN" ``` `status` chuyển qua `created` → `started` → `completed`. Khi tới `completed`, file MP4 hoàn chỉnh nằm ở `response.media[].videoUrl` (một prompt với `count > 1` trả về một mục cho mỗi video): ```json { "jobid": "j1731859234567v-...", "type": "video", "status": "completed", "response": { "media": [ { "mediaGenerationId": "user:12345-email:6a6f...-video:a1d95d21-...", "videoUrl": "https://flow-content.google/video/a1d95d21-...?Expires=...", "thumbnailUrl": "https://flow-content.google/image/a1d95d21-...?Expires=..." } ], "remainingCredits": 18760 } } ``` Omni Flash thường xong trong 60–180 giây. `videoUrl` có chữ ký dùng được khoảng 6 giờ, nên hãy tải về sớm. Không muốn polling? Truyền `replyUrl` trong body của lệnh tạo để nhận webhook khi job xong. ### Các chế độ tham chiếu Giá trị riêng của Omni Flash nằm ở chỗ bạn đưa vào được rất nhiều tham chiếu. Mọi tham chiếu đều đến từ endpoint tải lên [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email) (hoặc, với nhân vật, từ [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters)). Phản hồi tải lên đặt id tham chiếu lồng ở `mediaGenerationId.mediaGenerationId` — chuỗi lồng đó là thứ bạn truyền lại. Các chế độ `omni-flash` nhận (theo tài liệu [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos#references)): | Chế độ | Tham số | Giới hạn của Omni Flash | |------|--------------|------------------| | Video từ ảnh tham chiếu (R2V) | `referenceImage_1..10` | tối đa 10 ảnh tham chiếu trên `omni-flash-1.2`, 7 trên `omni-flash` | | Video từ ảnh (I2V) | `startImage` | một khung đầu | | Video từ ảnh, khung đầu + cuối (I2V-FL) | `startImage` + `endImage` | chỉ hai khung — không kèm tham chiếu khác | | Chỉnh sửa video sang video (V2V) | `referenceVideo_1` (+ tùy chọn `startFrameIndex_1` / `endFrameIndex_1`) | một file MP4 tải lên | | Nhân vật | `character_1..10` (từ [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters)) | tổng cộng 10 khi gộp với `referenceImage_*` trên `omni-flash-1.2`, 7 trên `omni-flash` | | Thuyết minh bằng giọng | `referenceAudio_1..5` | tối đa 5 (R2V) / tối đa 3 (chỉnh sửa V2V) | Video từ ảnh tham chiếu (R2V) — tải lên một hoặc nhiều ảnh, rồi truyền chúng làm `referenceImage_1`, `referenceImage_2`, … (các ô `_4`..`_7` chỉ có trên Omni Flash). Ảnh tham chiếu không kết hợp được với `startImage`/`endImage`. ```bash # 1. Upload a reference image — the id is nested one level deep: curl -X POST "https://api.useapi.net/v1/google-flow/assets/john%40gmail.com" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: image/jpeg" \ --data-binary @subject.jpeg # Response: { "mediaGenerationId": { "mediaGenerationId": "user:12345-email:...-image:..." }, ... } # 2. Generate, narrated by a system voice curl -X POST "https://api.useapi.net/v1/google-flow/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model": "omni-flash", "prompt": "the subject walks toward camera and introduces herself", "duration": 8, "referenceImage_1": "user:12345-email:...-image:...", "referenceAudio_1": "Kore" }' ``` Chỉnh sửa video sang video (V2V) — tải một file MP4 lên [POST /assets](/docs/api-google-flow-v1/post-google-flow-assets-email) với `Content-Type: video/mp4`, rồi truyền id nhận được làm `referenceVideo_1` để chỉnh sửa video đó. Chế độ này chỉ có trên Omni Flash và chuyển request sang chế độ V2V. Không nhận `duration` (độ dài đầu ra bằng đoạn cắt của đầu vào, tối đa 10 s trên `omni-flash` và 15 s trên `omni-flash-1.2`). Bạn có thể cắt video nguồn trên một dòng thời gian ảo 24 fps bằng `startFrameIndex_1` (0–239) và `endFrameIndex_1` (1–240, trong đó 240 = 10 s), hoặc tới 359 và 360 (15 s) trên `omni-flash-1.2`: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model": "omni-flash", "prompt": "restyle the scene as a rainy neon-lit night, add ambient city sound", "referenceVideo_1": "user:12345-email:...-video:...", "startFrameIndex_1": 0, "endFrameIndex_1": 240, "async": true }' ``` Bạn cũng có thể đặt các dấu `@` ngay trong prompt, trỏ tới các ô bạn truyền vào — ví dụ `@referenceImage_1`, `@character_1`, `@referenceAudio_1`. Dấu nhắc là tùy chọn, và mỗi dấu phải có một tham số tương ứng trong body. (`@referenceVideo_*` không dùng được trong prompt — hãy truyền nó làm một trường trong body.) Xem [Dấu nhắc @ trong prompt](/docs/api-google-flow-v1/post-google-flow-videos#inline--mention-markers-optional). ### Giọng nói và nhân vật Hai lệnh gọi thiết lập ngắn giúp bạn dùng tính năng âm thanh và nhận diện nhân vật của Omni Flash. Giọng tùy chỉnh — [POST /voices](/docs/api-google-flow-v1/post-google-flow-voices) lưu một giọng dựa trên một trong 30 giọng hệ thống, với `dialog` và `voicePerformance` của riêng bạn. Trường `voice` trong phản hồi là một id tham chiếu mà bạn truyền làm `referenceAudio_1..5` trên [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos): ```bash curl -X POST "https://api.useapi.net/v1/google-flow/voices" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "john@gmail.com", "voice": "Achernar", "dialog": "Welcome to the demo.", "voicePerformance": "Cheerful, energetic delivery", "displayName": "Cheerful Narrator" }' # Response: { "voice": "user:12345-email:...-voice:...-mid:...", ... } ``` Mỗi ô `referenceAudio_*` nhận tên một giọng hệ thống (không phân biệt hoa thường, một trong 30 giọng có sẵn như `Aoede`, `Kore`, `Puck`, `Zephyr`) hoặc id giọng của người dùng từ lệnh gọi trên. Tạo giọng cần reCAPTCHA (được giải tự động — xem [phần câu hỏi thường gặp](#frequently-asked-questions)). Nhân vật dùng lại được — [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters) gộp 1–2 ảnh tham chiếu cùng một giọng tùy chọn thành một nhân vật có tên. Trường `character` trong phản hồi là thứ bạn truyền làm `character_1..10`: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/characters" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "displayName": "Carol", "imageReference_1": "user:12345-email:...-image:abc123...", "voice": "user:12345-email:...-voice:...-mid:..." }' # Response: { "character": "user:12345-email:...-character:...-imgs:1-voice:...", ... } ``` Trên Omni Flash, nhân vật dùng được với mọi độ dài và chia chung giới hạn tổng 10 ảnh tham chiếu với `referenceImage_*` (`referenceImages.length + Σ(character.imgs) ≤ 10`, Omni 1.1: 7). `POST /characters` không cần captcha. Nhân vật và giọng nói cũng dùng được với Veo, nhưng giới hạn chặt hơn (3 ảnh, 1 giọng, chỉ 8 s) — xem [What can use a character?](/docs/api-google-flow-v1/post-google-flow-characters#what-can-use-a-character). ### Kéo dài video bằng Omni 1.2 [POST /videos/extend](/docs/api-google-flow-v1/post-google-flow-videos-extend) thêm 3 đến 10 giây mỗi lần bằng Omni 1.2 Flash vào bất kỳ video nào ngắn hơn 30 giây, với tối đa 3 giọng, ảnh tham chiếu hoặc nhân vật, và trả về một clip liền mạch (chỉ gói trả phí). Phần hướng dẫn trong [Cách dùng Gemini Omni 1.2 Flash API](/docs/articles/gemini-omni-1-2-flash-api-vi#flow-walkthrough) kéo dài một video 10 giây hai lần thành 30 giây với hai giọng, chính là [ví dụ bên dưới](#examples). ### Tạo hàng loạt bằng script Tìm được cảnh quay ưng ý cần nhiều lần thử, và chạy từng lần bằng tay rất mất công. Script Node.js dưới đây đọc danh sách prompt từ `prompts.json`, tải lên ảnh tham chiếu, khung đầu và khung cuối hoặc video nguồn nếu có, truyền thẳng các id `character_*` và `resolution`, gửi từng job ở chế độ async với `model: "omni-flash"`, rồi polling và tải về mọi file MP4 đã xong — nên bạn có thể xếp hàng cả loạt rồi quay lại chọn video đẹp nhất. Script dừng lại kèm cảnh báo trước khi gửi một tổ hợp mà API sẽ từ chối, chẳng hạn khung cuối mà không có khung đầu. Bạn cần [Node.js](https://nodejs.org) v21 trở lên. Đặt `prompts.json` và `omni-flash.mjs` cùng một thư mục và chạy `node ./omni-flash.mjs API_TOKEN EMAIL`, trong đó `API_TOKEN` là [API token](/docs/start-here/setup-useapi) useapi.net của bạn và `EMAIL` là email của [tài khoản Google Flow](/docs/start-here/setup-google-flow) đã kết nối. Script tự tìm tài khoản theo email và kiểm tra trường `health` trước khi gửi. Muốn clone và chạy trên máy? File `omni-flash.mjs` và `prompts.json` đầy đủ có trên GitHub ở [`useapi/google-flow-api`](https://github.com/useapi/google-flow-api/tree/main/omni-flash). Bạn làm việc trong Claude Code hoặc Codex? [Agent skill omni-flash-video](https://github.com/useapi/google-flow-api/tree/main/skills/omni-flash-video) để agent làm hết việc này cho bạn: mô tả video, chỉ cho nó ảnh của bạn, và nó tải ảnh lên, viết request, chờ và lưu file `.mp4`. Cài bằng `npx skills add useapi/google-flow-api --skill omni-flash-video`. <details markdown="block"> <summary>Mở `prompts.json`</summary> ```json [ { "prompt": "Audio-native text-to-video. By default model omni-flash with a landscape 8-second clip will be used." }, { "duration": 10, "prompt": "A 10-second clip (omni-flash only). Omni Flash is audio-native, so narration, dialogue and sound come from the prompt. To pin a specific voice, add referenceAudio_1 together with a referenceImage_* or character_*, as in the next prompt." }, { "duration": 8, "referenceImage_1": "./subject.jpeg", "referenceAudio_1": "Kore", "prompt": "Reference-to-video (R2V): the uploaded image is a reference, narrated by 'Kore'. Up to 7 referenceImage_* on omni-flash, 10 on omni-flash-1.2." }, { "duration": 8, "startImage": "./first_image.jpeg", "endImage": "./last_image.jpeg", "prompt": "Image-to-video with a start frame (startImage) and an end frame (endImage). The two frames are the only input — no referenceImage_*, character_* or referenceAudio_* alongside them." }, { "referenceVideo_1": "./source.mp4", "startFrameIndex_1": 0, "endFrameIndex_1": 240, "prompt": "Video-to-video edit (V2V): omni-flash restyles the uploaded MP4. No duration here — output matches the trim window (max 10 s). For all parameters see https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos" } ] ``` </details> <details markdown="block"> <summary>Mở script `omni-flash.mjs`</summary> ```javascript /* Script version 1.3, November 11, 2026 Script to batch-generate audio-native videos with Gemini Omni Flash using the Google Flow API by useapi.net Uses the POST /videos endpoint in async mode (model: omni-flash by default, or omni-flash-1.2 per prompt) and polls GET /jobs/{jobId}. For more details visit https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos Installation Instructions: ========================== You need Node.js v21 or newer installed to run this script. Download and install Node.js from: - Windows, macOS, Linux: https://nodejs.org/ After installation, verify by running the following command in a terminal: node -v Running the Script: =================== Usage: node omni-flash.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE] Replace API_TOKEN with your actual useapi.net API token, see https://useapi.net/docs/start-here/setup-useapi Replace EMAIL with configured Google Flow email account, see https://useapi.net/docs/start-here/setup-google-flow If optional PROMPTS_FILE not provided prompts.json will be used. Example: -------- node omni-flash.mjs user:1234-abcdefhijklmnopqrstuv my@email.com This command executes the script using API token user:1234-abcdefhijklmnopqrstuv with my@email.com Google Flow account email. Changelog: ========== - June 15, 2026: Initial release. - September 11, 2026: Adds resolution, startImage / endImage (start and end frames, local files uploaded for you) and character_1..7. Accepts .jpg and upper-case file extensions. Stops with a warning before submitting combinations the API rejects, such as endImage without startImage or referenceAudio_* on its own. A prompt whose local startImage, endImage, referenceImage_* or referenceVideo_1 file fails to upload is skipped and logged to omni-flash_errors.txt instead of being submitted without it. Saves a downloaded video under its final name only once it has been fully received, so a failed download leaves no partial MP4 for the next run to skip as "already exists". - November 11, 2026: referenceImage_8..10 and character_8..10: omni-flash-1.2 takes up to 10 references (omni-flash 7). */ import readline from 'node:readline'; import fs from 'fs/promises'; import path from 'path'; import { writeFile } from 'node:fs/promises'; import { Readable } from 'node:stream'; // Constants const RESULTS_FILE = 'omni-flash_results.txt'; const ERRORS_FILE = 'omni-flash_errors.txt'; const DEFAULT_PROMPTS_FILE = 'prompts.json'; const MODEL = 'omni-flash'; // Reference slots: up to 10 on omni-flash-1.2, 7 on omni-flash, 3 on Veo (referenceImage_* and character_* together). const imageRefKeys = Array.from({ length: 10 }, (_, i) => `referenceImage_${i + 1}`); const characterKeys = Array.from({ length: 10 }, (_, i) => `character_${i + 1}`); const SLEEP_429 = 30 * 1000; // in milliseconds const SLEEP_POLL = 15 * 1000; // in milliseconds const urlAccounts = 'https://api.useapi.net/v1/google-flow/accounts'; const urlVideos = 'https://api.useapi.net/v1/google-flow/videos'; const urlJobs = 'https://api.useapi.net/v1/google-flow/jobs/'; const urlUploadAsset = 'https://api.useapi.net/v1/google-flow/assets/'; // Google Flow accepts png, jpeg and webp images, and mp4 video (for omni-flash V2V edit). const supportedImageExtensions = ['png', 'jpg', 'jpeg', 'webp']; const supportedVideoExtensions = ['mp4']; // { filename: mediaGenerationId } const uploadedFiles = {}; // Utility to sleep for given milliseconds const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); // Function to fetch configured Google Flow API accounts async function fetchAccounts(apiToken) { const response = await fetch(urlAccounts, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.error(`⛔ Error fetching accounts (HTTP ${response.status}): ${response.statusText}`); process.exit(1); } return response.json(); } const elapsedTimeSec = (start) => (Date.now() - start) / 1000; // Map a file extension to the Content-Type required by POST /assets const contentTypeForExt = (ext) => ext === 'png' ? 'image/png' : ext === 'webp' ? 'image/webp' : ext === 'mp4' ? 'video/mp4' : 'image/jpeg'; async function uploadAsset(apiToken, email, filename) { // Check if already uploaded if (uploadedFiles.hasOwnProperty(filename)) return uploadedFiles[filename]; const startTime = Date.now(); console.log(`⬆️ Account ${email} uploading file…`, filename); const body = new Blob([await fs.readFile(filename)]); const fileExt = filename.split('.').pop().toLowerCase(); const response = await fetch(`${urlUploadAsset}${encodeURIComponent(email)}`, { method: 'POST', headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}`, 'Content-Type': contentTypeForExt(fileExt) }, body }); if (response.ok) { const json = await response.json(); // POST /assets returns the reference id nested as mediaGenerationId.mediaGenerationId const mediaGenerationId = json?.mediaGenerationId?.mediaGenerationId; console.log(`🆗 mediaGenerationId (${elapsedTimeSec(startTime)} sec)`, mediaGenerationId); uploadedFiles[filename] = mediaGenerationId; } else { console.error(`❗ Unable to upload file HTTP ${response.status} (${elapsedTimeSec(startTime)} sec)`, await response.text()); // Do not attempt to upload failed file again uploadedFiles[filename] = undefined; } return uploadedFiles[filename]; } async function submit(apiToken, url, body, index, prompt) { const createResponse = await fetch(url, { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiToken}` }, body }); const createBody = await createResponse.text(); // Async POST /videos returns 201 Created with a jobid to poll. if (createResponse.status == 201) { const json = JSON.parse(createBody); // 201 async payload uses lowercase "jobid"; sync 200 uses "jobId". Accept either. const jobId = json.jobid ?? json.jobId; if (jobId) { await fs.appendFile(RESULTS_FILE, `${jobId},#${index}:${prompt}\n`); console.log(`✅ jobId`, jobId); return 201; } else { const error = `No jobid found in HTTP 201 response`; console.log(`❓ ${error}`, createBody); await fs.appendFile(ERRORS_FILE, `${error},#${index}:${prompt}\n`); return 500; } } else { switch (createResponse.status) { case 429: console.log(`🔄️ Retry on HTTP ${createResponse.status}`, createBody); break; case 503: console.log(`🔄️ Service unavailable, retry on HTTP ${createResponse.status}`, createBody); break; case 400: console.log(`🛑 Rejected request (validation or content policy)`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${prompt}\n`); break; case 402: console.log(`🛑 No subscription / insufficient credits`, createBody); break; default: console.log(`❗ FAILED with HTTP ${createResponse.status}`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${prompt}\n`); } return createResponse.status; } } // Submit a single prompt to POST /videos with model omni-flash (or the prompt's own model) in async mode. // startImage = start frame (I2V), endImage = end frame (I2V-FL, requires startImage) — the frames are the only input; // referenceImage_1..10 = R2V image refs; character_1..10 = POST /characters ids (10 on omni-flash-1.2, 7 on omni-flash); // referenceVideo_1 = V2V edit (no duration); referenceAudio_1..5 = system voice name or POST /voices user-voice id; // resolution = 720p (default) or 360p; model = 'omni-flash' (Omni 1.1, the default) or 'omni-flash-1.2' (3–15 s, per-second credits). async function submitVideo(apiToken, email, prompt, index) { const { prompt: text, model = MODEL, aspectRatio, duration, resolution, count, startImage, endImage, referenceVideo_1, startFrameIndex_1, endFrameIndex_1, referenceAudio_1, referenceAudio_2, referenceAudio_3, referenceAudio_4, referenceAudio_5 } = prompt; console.log(`🚀 ${model} » Prompt #${index} • account ${email} …`); // Upload any local image/video files and swap the paths for their mediaGenerationId. const resolveRef = async (ref) => ref && (ref.startsWith('./') || ref.includes('.')) && [...supportedImageExtensions, ...supportedVideoExtensions].includes(ref.split('.').pop().toLowerCase()) ? await uploadAsset(apiToken, email, ref) : ref; const startImageId = await resolveRef(startImage); const endImageId = await resolveRef(endImage); const refImages = {}; for (const key of imageRefKeys) refImages[key] = await resolveRef(prompt[key]); const refVideo_1 = await resolveRef(referenceVideo_1); // A local file that failed to upload would be left out of the body, and the prompt would still be // generated (and charged) without it. Skip the prompt instead. uploadAsset remembers the failed file, // so a later prompt using it is skipped too, without another upload attempt. const failedUploads = [ ['startImage', startImage, startImageId], ['endImage', endImage, endImageId], ...imageRefKeys.map(key => [key, prompt[key], refImages[key]]), ['referenceVideo_1', referenceVideo_1, refVideo_1] ].filter(([, file, id]) => file && !id); for (const [param, file] of failedUploads) { console.error(`🛑 Prompt #${index} skipped: ${param} ${file} failed to upload`); await fs.appendFile(ERRORS_FILE, `Upload failed for ${param} ${file},#${index}:${text}\n`); } if (failedUploads.length) return; // V2V edit does not accept duration — output matches the trim window. const isV2V = !!refVideo_1; const body = JSON.stringify({ model, email, prompt: text, aspectRatio, duration: isV2V ? undefined : duration, resolution, count, startImage: startImageId, endImage: endImageId, ...refImages, ...Object.fromEntries(characterKeys.map(key => [key, prompt[key]])), referenceVideo_1: refVideo_1, startFrameIndex_1, endFrameIndex_1, referenceAudio_1, referenceAudio_2, referenceAudio_3, referenceAudio_4, referenceAudio_5, async: true }); return await submit(apiToken, urlVideos, body, index, text); } // Function to download videos async function download(apiToken) { if (! await fileExists(RESULTS_FILE)) return; try { const resultsContent = await fs.readFile(RESULTS_FILE, 'utf8'); const lines = resultsContent.trim().split('\n'); for (const line of lines) { const [jobId, prompt] = line.split(','); console.log(`👉 ${jobId}`); while (true) { const response = await fetch(`${urlJobs}${jobId}`, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.log(`🛑 Poll failed ${jobId} (HTTP ${response.status}):\n${prompt}\n`, await response.text()); break; } const jobBody = await response.json(); const { status, error, response: jobResponse } = jobBody; if (status == 'failed') { console.error(`🛑 FAILED ${jobId} (${error}):\n${prompt}\n`); break; } if (status == 'completed') { const media = jobResponse?.media ?? []; if (media.length == 0) console.error(`🛑 Completed but no media for ${jobId}:\n${prompt}\n`); // A single prompt with count > 1 returns multiple videos. for (let i = 0; i < media.length; i++) { const url = media[i]?.videoUrl; const videoFilename = `${jobId.replace(/[:*]/g, '_')}_${i + 1}.mp4`; try { await fs.access(videoFilename); console.log(`⚠️ ${videoFilename} already exists. Skipping download.`); continue; } catch { // File does not exist, proceed with downloading } if (url) { console.log(`✅ Downloading ${url} to ${videoFilename}`); // Stream into a temporary file and rename it once the whole video has arrived, so a download // that drops mid-stream leaves no partial file behind for the next run to skip as "already exists". const tempFilename = `${videoFilename}.part`; try { const videoResponse = await fetch(url); if (!videoResponse.ok) { console.error(`⛔ Unable to download ${jobId} (HTTP ${videoResponse.status}):\n${prompt}\n`, url); continue; } const stream = Readable.fromWeb(videoResponse.body); await writeFile(tempFilename, stream); await fs.rename(tempFilename, videoFilename); } catch (err) { await fs.rm(tempFilename, { force: true }); console.error(`⛔ Error during download: ${err}`); } } else console.error(`🛑 No videoUrl for ${jobId} media #${i + 1}:\n${prompt}\n`); } break; } console.log(`⌛ ${jobId} status (${status}) and is still in progress, waiting…`); await sleep(SLEEP_POLL); } } } catch (error) { console.log(`⛔ Error during download:`, error.stack || error); } } // Main function async function main() { const apiToken = process.argv[2]; const email = process.argv[3]; const promptFile = process.argv[4] || DEFAULT_PROMPTS_FILE; if (!apiToken || !email) { console.error('Usage: node omni-flash.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE]'); process.exit(1); } console.info('Script v1.3'); console.info('Node version is: ' + process.version); try { if (await fileExists(RESULTS_FILE)) { let user_input; while (!['y', 'n'].includes(user_input)) { user_input = (await promptUser(`❔ ${RESULTS_FILE} file detected. Do you want to download the results now? (y/n): `))?.toLowerCase(); if (user_input == 'y') { await download(apiToken); await fs.unlink(RESULTS_FILE); } } } const start = new Date(); try { console.info('START EXECUTION', start); await execute(apiToken, email, promptFile); // Pass the promptFile to execute function } finally { console.info('COMPLETED', new Date()); console.info('EXECUTION ELAPSED', diffInMinutesAndSeconds(start, new Date())); } try { console.info('START DOWNLOAD', start); await download(apiToken); } finally { console.info('TOTAL ELAPSED', diffInMinutesAndSeconds(start, new Date())); } } catch (error) { console.error('⛔ Error during execution:', error.stack || error); } } // Modify the execute function to accept promptFile as a parameter async function execute(apiToken, email, promptFile) { const accounts = await fetchAccounts(apiToken); console.info(`Configured Google Flow API accounts (${Object.keys(accounts).length}):`, Object.keys(accounts).join(', ')); if (Object.keys(accounts).length <= 0) { console.error(`⛔ No configured Google Flow accounts found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (!accounts[email]) { console.error(`⛔ Account ${email} not found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (accounts[email].health && accounts[email].health !== 'OK') { console.error(`⛔ Account ${email} health is '${accounts[email].health}'. Please resolve and update the account, see https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } const promptData = await fs.readFile(promptFile, 'utf8'); const prompts = JSON.parse(promptData); console.log(`Total number of prompts to process`, prompts.length); let warnings = []; // Parameters accepted by this script for the omni-flash POST /videos endpoint. // See https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos for the full parameter set. const supportedParams = [ 'prompt', 'model', 'aspectRatio', 'duration', 'resolution', 'count', 'startImage', 'endImage', ...imageRefKeys, ...characterKeys, 'referenceVideo_1', 'startFrameIndex_1', 'endFrameIndex_1', 'referenceAudio_1', 'referenceAudio_2', 'referenceAudio_3', 'referenceAudio_4', 'referenceAudio_5' ]; const audioRefKeys = ['referenceAudio_1', 'referenceAudio_2', 'referenceAudio_3', 'referenceAudio_4', 'referenceAudio_5']; const invalidKeys = (prompt) => Object.keys(prompt).filter(key => !key.startsWith('__') && !supportedParams.includes(key)) // Validate a local file path reference (skip already-uploaded mediaGenerationId strings). const looksLikePath = (ref) => ref && (ref.startsWith('./') || (ref.includes('.') && !ref.startsWith('user:'))); for (let i = 1; i <= prompts.length; i++) { const prompt = prompts[i - 1]; const { prompt: text, referenceVideo_1, duration, startImage, endImage } = prompt; const validateFile = async (file, allowedExts) => { if (looksLikePath(file)) { try { await fs.access(file); } catch { warnings.push(`⚠️ File '${file}' does not exist. Prompt ${i}`); } const ext = file.split('.').pop().toLowerCase(); if (!allowedExts.includes(ext)) warnings.push(`⚠️ File ${file} extension ${ext} not supported. Prompt ${i}`); } }; const notSupported = invalidKeys(prompt); if (notSupported.length) warnings.push(`⚠️ Following params not supported: ${notSupported.join(',')}. Prompt ${i}`); if (!text) warnings.push(`⚠️ prompt is required. Prompt ${i}`); // V2V edit (referenceVideo_1) does not accept duration — output matches the trim window. if (referenceVideo_1 && duration) warnings.push(`⚠️ duration is not accepted with referenceVideo_1 (V2V edit). Prompt ${i}`); if (endImage && !startImage) warnings.push(`⚠️ endImage requires startImage (end-frame-only is not supported). Prompt ${i}`); // Start/end frames (I2V, I2V-FL) are the only input in that mode — the API rejects anything alongside them. if (startImage || endImage) { if (referenceVideo_1) warnings.push(`⚠️ startImage/endImage cannot be combined with referenceVideo_1 (V2V edit). Prompt ${i}`); if ([...imageRefKeys, ...characterKeys].some(k => prompt[k])) warnings.push(`⚠️ startImage/endImage cannot be combined with referenceImage_* or character_*. Prompt ${i}`); if (audioRefKeys.some(k => prompt[k])) warnings.push(`⚠️ startImage/endImage cannot be combined with referenceAudio_*. Prompt ${i}`); } // A voice needs a referenceImage_* or character_* to attach to (or a V2V edit) — the API rejects referenceAudio_* on its own. // With start/end frames the check above already applies. if (!startImage && !endImage && !referenceVideo_1 && audioRefKeys.some(k => prompt[k]) && ![...imageRefKeys, ...characterKeys].some(k => prompt[k])) warnings.push(`⚠️ referenceAudio_* requires a referenceImage_* or character_* (or referenceVideo_1 for a V2V edit). Prompt ${i}`); await Promise.all([ validateFile(referenceVideo_1, supportedVideoExtensions), ...['startImage', 'endImage', ...imageRefKeys].map(k => validateFile(prompt[k], supportedImageExtensions)) ]); } if (warnings.length > 0) { warnings.forEach(warning => console.warn(warning)); console.error(`⛔ Execution stopped due to warnings.`); process.exit(1); } for (let i = 0; i < prompts.length; i++) { const prompt = prompts[i]; while (true) { const responseCode = await submitVideo(apiToken, email, prompt, i + 1); if (responseCode == 429 || responseCode == 503) await sleep(SLEEP_429); else if (responseCode == 402) { process.exit(1); } else break; } } } // Utility function to check if a file exists async function fileExists(path) { try { await fs.access(path); return true; } catch { return false; } } // Function to prompt user input async function promptUser(query) { const rl = readline.createInterface({ input: process.stdin, output: process.stdout }); return new Promise((resolve) => rl.question(query, answer => { rl.close(); resolve(answer); })); } function diffInMinutesAndSeconds(date1, date2) { const diffInSeconds = Math.floor((date2 - date1) / 1000); return `${Math.floor(diffInSeconds / 60)} minutes ${diffInSeconds % 60} seconds`; }; main(); ``` </details> ### Ví dụ Các video dưới đây là kết quả Gemini Omni Flash thật, làm qua Google Flow API này — `model: "omni-flash-1.2"` và `model: "omni-flash"`, kéo dài, giọng nói, tham chiếu, nhân vật và chỉnh sửa V2V. ###### Kéo dài bằng Omni 1.2 — video 10 giây được kéo dài hai lần thành 30 giây, với hai giọng {: .no_toc #omni-12-extend--a-10-second-video-extended-twice-to-30-seconds-with-two-voices } <video poster="https://media.useapi.net/articles/2026-06-15-omni-flash-bash/261106-google-flow-omni-1-2-magician-extended-30s-web-poster.jpg" controls width="100%" style="max-width:640px;border-radius:8px"> <source src="https://media.useapi.net/articles/2026-06-15-omni-flash-bash/261106-google-flow-omni-1-2-magician-extended-30s-web.mp4" type="video/mp4"> </video> Từ [Google Flow: Omni 1.2 Flash, 15-Second Videos, and Extend with Voices](/blog/261106) — `omni-flash-1.2` cho 10 giây đầu, rồi hai lệnh gọi `POST /videos/extend` với `referenceAudio_1`. ###### Chỉnh sửa V2V — đổi phong cách một file MP4 tải lên thành hoạt hình, giữ nguyên chuyển động và khung hình {: .no_toc #v2v-edit--restyle-an-uploaded-mp4-into-a-cartoon-same-motion-and-framing } <video poster="https://media.useapi.net/blog/2026-05-20-260520/google-flow-edit-video-poster.jpg" controls width="100%" style="max-width:640px;border-radius:8px"> <source src="https://media.useapi.net/blog/2026-05-20-260520/google-flow-edit-video.mp4" type="video/mp4"> </video> Từ [Google Flow: Gemini Omni Flash](/blog/260520) — chỉnh sửa bằng `referenceVideo_1`. ###### Dấu nhắc @ trong prompt — video noir R2V với @character_1, @referenceImage_1, @referenceImage_2 và một giọng tùy chỉnh {: .no_toc #inline--mentions--r2v-noir-video-with-character_1-referenceimage_1-referenceimage_2-and-a-custom-voice } <video poster="https://media.useapi.net/blog/2026-06-09-260609/noir-shot-1-poster.jpg" controls width="100%" style="max-width:640px;border-radius:8px"> <source src="https://media.useapi.net/blog/2026-06-09-260609/noir-shot-1.mp4" type="video/mp4"> </video> Từ [Google Flow: Inline @-mentions](/blog/260609) — dấu nhắc `@` trong prompt gắn từng tham chiếu vào đúng chỗ. ###### Nhân vật + chỉnh sửa V2V — ghép hai nhân vật dùng lại được vào video noir {: .no_toc #characters--v2v-edit--composites-two-reusable-characters-into-the-noir-video } <video poster="https://media.useapi.net/blog/2026-06-09-260609/edit-1-poster.jpg" controls width="100%" style="max-width:640px;border-radius:8px"> <source src="https://media.useapi.net/blog/2026-06-09-260609/edit-1.mp4" type="video/mp4"> </video> Từ [Google Flow: Inline @-mentions](/blog/260609) — chỉnh sửa V2V bằng `referenceVideo_1` với `@character_*` trong prompt. Xem thêm [Reusable Voices and Characters](/blog/260605) về quy trình thiết lập giọng nói và nhân vật. ### Câu hỏi thường gặp - **Gemini Omni Flash là gì?** Qua useapi.net, bạn chạy Gemini Omni Flash, [model video có âm thanh gốc](https://deepmind.google/models/model-cards/gemini-omni-flash/) của Google trong [Google Flow](https://flow.google.com), bằng cách đặt `model: "omni-flash-1.2"` (Omni 1.2 Flash) hoặc `model: "omni-flash"` (Omni 1.1 Flash) trên [Google Flow API](/docs/api-google-flow-v1). Khác với model video không tiếng, nó tạo phần âm thanh, lời thuyết minh, hội thoại và âm thanh nền ngay trong cùng một video, và nhận tham chiếu ảnh, video, âm thanh cùng nhân vật dùng lại được. - **Omni Flash khác Veo 3.1 thế nào?** Qua useapi.net, cả hai chạy trên cùng Google Flow API, được chọn bằng trường `model`. Veo là engine tạo video thuần từ văn bản và từ ảnh với độ chân thực cao hơn, còn Omni Flash có âm thanh gốc và nhận nhiều tham chiếu, với chỉnh sửa video sang video (`referenceVideo_1`), nhiều giọng trong một video, nhân vật dùng lại được ở mọi độ dài và video dài hơn Veo. Xem [Các chế độ tham chiếu](#reference-modes) để biết giới hạn chính xác. - **Có dùng được giọng của riêng tôi, video tham chiếu hoặc âm thanh tham chiếu không?** Qua useapi.net thì được. Thuyết minh bằng các giọng hệ thống có sẵn hoặc giọng tùy chỉnh từ [POST /voices](/docs/api-google-flow-v1/post-google-flow-voices), truyền làm `referenceAudio_1..5`, và tải một file MP4 lên bằng [POST /assets](/docs/api-google-flow-v1/post-google-flow-assets-email) để chỉnh sửa nó làm `referenceVideo_1` (V2V). Xem [Các chế độ tham chiếu](#reference-modes) và [Giọng nói và nhân vật](#voices--characters) để biết giới hạn của từng chế độ. - **Omni Flash có API chính thức không?** Qua useapi.net, Omni 1.1 Flash rẻ hơn nhiều so với trên API của chính Google: một video 720p dài 8 giây tốn $0,10 trên Google AI Ultra $199,99, so với $0,81 trên [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) chính thức, nơi bán model này theo giây từ ngày 30 tháng 6 năm 2026 (tính đến tháng 11/2026). Nó chạy qua một endpoint REST tiêu chuẩn trên gói đăng ký website Google Flow của bạn. - **Omni Flash có làm được video dài hơn 10 giây không?** Qua useapi.net thì được: Omni 1.2 Flash (`model: "omni-flash-1.2"`) làm tối đa 15 giây trong một lệnh gọi, và [POST /videos/extend](/docs/api-google-flow-v1/post-google-flow-videos-extend) thêm tối đa 10 giây mỗi lần kèm giọng nói, với giá $0,19 cho một video 720p dài 8 giây trên Google AI Ultra $199,99, so với $0,56 trên [API của chính Google](https://cloud.google.com/blog/products/ai-machine-learning/gemini-omni-1-2-flash-generally-available) (tính đến tháng 11/2026). Mọi giới hạn độ dài và mức giá trong Google Flow và Google Vids có ở [Cách dùng Gemini Omni 1.2 Flash API](/docs/articles/gemini-omni-1-2-flash-api-vi). - **Tôi có phải tự giải captcha không?** Qua useapi.net, bạn không bao giờ phải tự giải. Google Flow yêu cầu reCAPTCHA cho mỗi video và mỗi giọng mới, và worker của useapi.net tự động giải: tài khoản Google Flow đầu tiên của bạn được 300 lần giải miễn phí bằng key AntiCaptcha, CapSolver và EzCaptcha của chúng tôi, sau đó bạn thêm key dịch vụ của riêng mình bằng [POST /accounts/captcha-providers](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers). [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters) không cần captcha. ### Kết luận Ghé <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> hoặc <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> của chúng tôi cho mọi câu hỏi hỗ trợ. Xem [repo GitHub](https://github.com/useapi/google-flow-api) của chúng tôi với các ví dụ code. Một trợ lý AI cũng có thể làm việc với Google Flow thay bạn: [MCP server Google Flow](/docs/api-google-flow-v1/mcp) được host sẵn cho phép Claude Code, Cursor và VS Code trò chuyện với Google Flow Agent, và Agent tạo ảnh và video trên tài khoản của bạn. ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/omni-flash-bash-zh === Document URL: https://useapi.net/docs/articles/omni-flash-bash-zh --- layout: default title: "如何通过 Google Flow API 用 Gemini Omni Flash 生成带原生音频的 AI 视频(中文教程)" description: "Gemini Omni Flash 中文教程:通过 useapi.net 的 Google Flow API 调用 Omni 1.2 和 1.1 Flash,支持参考图、角色、音色和 V2V 编辑,附 curl 示例和批量生成脚本。" keywords: [Gemini Omni Flash, Omni 1.2 Flash, Omni 1.1 Flash, Omni Flash API, omni-flash-1.2, omni-flash, Google Flow API, Gemini Omni Flash 教程, Omni Flash API 教程, 原生音频视频, AI 视频对白, 视频延长, 音色, 角色, 视频编辑, 参考图生视频, 批量生成, Google Flow, 中文教程, Chinese tutorial, tutorial, code] parent: Articles nav_exclude: true lang: zh-CN translation_key: omni-flash date: 2026-06-15 last_modified: 2026-11-12 nav_order: 830 repo: https://github.com/useapi/google-flow-api --- ## 如何通过 Google Flow API 用 Gemini Omni Flash 生成带原生音频的 AI 视频(中文教程) {: .no_toc #how-to-generate-audio-native-ai-video-with-gemini-omni-flash-via-the-google-flow-api } 8 分钟阅读 • 2026 年 6 月 15 日(2026 年 11 月 12 日更新) useapi.net 是第三方 API,与 Google 无关联,也未获得 Google 的认可。 ## 目录 {: .no_toc .text-delta #table-of-contents } ### 简介 通过 useapi.net 的 [Google Flow API](/docs/api-google-flow-v1),一条 `curl` 就能用 [Gemini Omni Flash](https://deepmind.google/models/model-cards/gemini-omni-flash/) 生成带原生音频的 AI 视频,支持同步音色、角色和视频到视频编辑,运行在你的 [Google Flow](https://flow.google.com) 网站订阅上([Google AI](https://gemini.google/subscriptions/):Omni 1.1 Flash 需要 Plus、Pro 或 Ultra,Omni 1.2 Flash 所有套餐都能用,免费账号最长 10 秒)。一条 10 秒 720p 视频在 Google AI Ultra(199.99 美元)上约 0.12 美元,官方 [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) 为 1.01 美元(截至 2026 年 11 月),而且不需要 Google Cloud 项目,也不需要 API Key。同一个订阅还能在 [Google Vids](/docs/api-google-vids-v1) 里生成 Omni 视频,不消耗 Flow 积分。 这个模型在 Google Flow 界面里叫 Omni 1.1 Flash,API 取值是 `model: "omni-flash"`。Google 于 2026 年 11 月 5 日发布的 Omni 1.2 Flash 是另一个取值 `model: "omni-flash-1.2"`:时长可在 3 到 15 秒之间任选,按秒计算积分,也是用来[延长视频](#extend-a-video-with-omni-12)的模型,每次最多延长 10 秒。传 `omni-flash` 的代码仍然调用 1.1。15 秒视频、带音色的延长以及在 Google Flow 和 Google Vids 中的单条价格,见 [Gemini Omni 1.2 Flash API 中文教程](/docs/articles/gemini-omni-1-2-flash-api-zh)。 Omni Flash 和 Veo 用的是[同一个 Google Flow API](/docs/api-google-flow-v1),只靠一个字段区分:`model: "omni-flash-1.2"` 或 `model: "omni-flash"`。但它是另一类模型。Veo 擅长纯文本生成视频,而 Omni Flash 原生生成音频,并且能接收大量参考素材: - 声音和视频一起生成。旁白、对白和环境音都出自同一个模型,不是事后拼接上去的。 - 音色。30 个内置系统音色,外加用你自己的对白和表演说明创建的自定义音色,通过 `referenceAudio_1..5` 传入。 - 图片和视频参考。Omni 1.2 Flash 最多 10 张参考图(Omni 1.1 Flash 为 7 张),用于参考图生视频(R2V),还可以通过 `referenceVideo_1` 对上传或生成的视频做视频到视频(V2V)编辑。 - 可复用角色。把参考图和一个音色打包成一个有名字的角色,在多条视频里重复使用。 - 更长的视频。Omni 1.1 Flash 可生成 4、6、8 或 10 秒,Omni 1.2 Flash 可生成 3 到 15 秒之间的任意时长(Veo 最长 `8`),Omni 1.2 还能以每次最多 10 秒的步长延长视频。 本文先用可直接复制的 `curl` 演示两次调用的流程,再介绍 Omni Flash 独有的参考模式,最后给出一个能从提示词列表批量生成视频的 Node.js 脚本。纯文本生成视频请看同系列的 [Google Flow API 中文教程](/docs/articles/google-flow-api-zh)。 ### 支持的模型 本文使用 Google 的两个原生音频视频模型:Omni 1.1 Flash(`model: "omni-flash"`)和 Omni 1.2 Flash(`model: "omni-flash-1.2"`)。Omni 1.1 的积分消耗随视频时长变化: | 时长 | 每条视频积分 | |----------|------------------------| | 4 秒 | 7 | | 6 秒 | 10 | | 8 秒 | 12 | | 10 秒 | 15 | | V2V 编辑 | 20 | 以上是默认 `720p` 的消耗。传 `resolution: "360p"` 大约减半,按时长依次为 4 / 5 / 6 / 7 个积分,V2V 编辑为 10 个。360p 视频之后可以用 [POST /videos/upscale](/docs/api-google-flow-v1/post-google-flow-videos-upscale) 提升到 720p。 Omni 1.2 Flash(`model: "omni-flash-1.2"`)接受 3 到 15 之间的任意整数秒,按秒计价,所有套餐相同: | 时长 | 720p | 360p | |--------|------|------| | 3 秒 | 9 | 3 | | 8 秒 | 24 | 8 | | 10 秒 | 30 | 10 | | 15 秒 | 60 | 20 | 10 秒以内,720p 每秒 3 个积分,360p 每秒 1 个,超过 10 秒的部分每秒加倍。V2V 编辑的价格与同等时长的视频相同,1.2 最多可编辑片段中的 15 秒。免费 Google 账号可以用 1.2 生成最长 10 秒的视频。 Omni Flash 在 [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) 上支持五种模式:纯文本生成视频(T2V),参考图生视频(R2V,Omni 1.2 Flash 最多 10 张 `referenceImage_1..10`,Omni 1.1 Flash 最多 7 张),通过 `startImage` 从首帧生成视频(I2V),通过 `startImage` + `endImage` 在首尾帧之间生成视频(I2V-FL),以及通过 `referenceVideo_1` 编辑上传的 MP4(V2V)。详见下文的[参考模式](#reference-modes)。 ### 价格 Omni 1.1 Flash 需要付费 Google AI 订阅(Plus、Pro 或 Ultra),Omni 1.2 Flash 免费账号也能用(最长 10 秒),useapi.net 不按视频收费。每条视频按时长消耗 Flow 积分(见[支持的模型](#supported-model))。各套餐上每条视频的价格以及与官方 Gemini API 的对比,见 [Google Flow 价格表](/docs/api-google-flow-v1#pricing)。 Google AI 套餐每月还附带一份 [Google Vids](https://docs.google.com/videos) 额度,可用 Gemini Omni 1.2 Flash 生成最长 15 秒的视频([Google 公告](https://workspaceupdates.googleblog.com/2026/11/gemini-omni-12-flash-now-in-vids-with-15second-generations-and-improved-quality.html)),不消耗 Flow 积分。在 Ultra(199.99 美元,Google 称为 Ultra 20x)上,每月有 10,000 秒视频额度,约等于再多 1,000 条 1080p 10 秒视频,而 Flow 的 25,000 积分本身可生成约 1,666 条 10 秒 Omni 1.1 Flash 视频(或约 833 条 720p Omni 1.2 Flash 视频)。这些秒数由 Google 家庭方案的所有成员共享。其他套餐的额度更少(见 Google 的 [Gemini in Google Vids](https://support.google.com/docs/answer/15609411?hl=zh-CN) 页面),我们测试的免费账号则没有额度。[Google Vids API](/docs/api-google-vids-v1) 使用这份额度,不需要验证码。用 [Setup Google Vids](/docs/start-here/setup-google-vids) 绑定账号。 ### 两次 API 调用生成一条视频 你需要一个 useapi.net [API Token](/docs/start-here/setup-useapi),以及一个已绑定的 [Google Flow 账号](/docs/start-here/setup-google-flow)。下面的 Omni 1.1 Flash 示例要求该账号有付费 Google AI 订阅(Plus、Pro 或 Ultra),Omni 1.2 Flash 用免费账号也能运行(最长 10 秒)。视频任务是异步的:传 `async: true`,创建请求会立即返回一个 `jobid`,然后轮询直到视频生成完毕。 1. 提交任务:`POST https://api.useapi.net/v1/google-flow/videos`,`model: "omni-flash"`: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A lighthouse keeper narrates the coming storm, waves crashing below", "model": "omni-flash", "aspectRatio": "landscape", "duration": 10, "async": true }' ``` Omni Flash 原生生成音频,所以守塔人的旁白和海浪拍岸声都直接来自提示词,不需要任何音频参数。异步模式下请求会立即返回 `201 Created`,带一个小写的 `jobid` 和 `status: "created"`: ```json { "jobid": "j1731859234567v-u12345-email:jo***@gmail.com-bot:google-flow", "type": "video", "status": "created", "created": "2026-06-15T12:34:56.789Z", "request": { "async": true, "prompt": "A lighthouse keeper narrates the coming storm, waves crashing below", "model": "omni-flash", "aspectRatio": "landscape", "duration": 10 } } ``` 2. 轮询结果:`GET https://api.useapi.net/v1/google-flow/jobs/{jobId}`: ```bash curl "https://api.useapi.net/v1/google-flow/jobs/JOBID" \ -H "Authorization: Bearer $USEAPI_TOKEN" ``` `status` 依次经过 `created` → `started` → `completed`。到 `completed` 时,成品 MP4 在 `response.media[].videoUrl` 里(单个提示词传 `count > 1` 时,每条视频各一项): ```json { "jobid": "j1731859234567v-...", "type": "video", "status": "completed", "response": { "media": [ { "mediaGenerationId": "user:12345-email:6a6f...-video:a1d95d21-...", "videoUrl": "https://flow-content.google/video/a1d95d21-...?Expires=...", "thumbnailUrl": "https://flow-content.google/image/a1d95d21-...?Expires=..." } ], "remainingCredits": 18760 } } ``` Omni Flash 通常在 60–180 秒内完成。带签名的 `videoUrl` 约 6 小时内有效,请尽快下载。不想轮询?在创建请求里传 `replyUrl`,任务完成时会回调你的 webhook。 ### 参考模式 Omni Flash 的独特之处在于它能接收大量参考素材。所有参考都来自 [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email) 上传接口(角色则来自 [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters))。上传响应把参考 id 嵌套在 `mediaGenerationId.mediaGenerationId` 里,要回传的就是这个嵌套的字符串。`omni-flash` 支持的模式(来自 [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos#references) 文档): | 模式 | 参数 | Omni Flash 限制 | |------|--------------|------------------| | 参考图生视频(R2V) | `referenceImage_1..10` | `omni-flash-1.2` 最多 10 张参考图,`omni-flash` 最多 7 张 | | 图生视频(I2V) | `startImage` | 一张首帧 | | 首尾帧图生视频(I2V-FL) | `startImage` + `endImage` | 只能用这两帧,不能加其他参考 | | 视频到视频编辑(V2V) | `referenceVideo_1`(可选 `startFrameIndex_1` / `endFrameIndex_1`) | 一个上传的 MP4 | | 角色 | `character_1..10`(来自 [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters)) | 与 `referenceImage_*` 合计:`omni-flash-1.2` 最多 10 个,`omni-flash` 最多 7 个 | | 音色旁白 | `referenceAudio_1..5` | 最多 5 个(R2V)/ 最多 3 个(V2V 编辑) | 参考图生视频(R2V):上传一张或多张图片,然后作为 `referenceImage_1`、`referenceImage_2` … 传入(`_4`..`_7` 槽位仅 Omni Flash 可用)。参考图不能与 `startImage`/`endImage` 同时使用。 ```bash # 1. Upload a reference image — the id is nested one level deep: curl -X POST "https://api.useapi.net/v1/google-flow/assets/john%40gmail.com" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: image/jpeg" \ --data-binary @subject.jpeg # Response: { "mediaGenerationId": { "mediaGenerationId": "user:12345-email:...-image:..." }, ... } # 2. Generate, narrated by a system voice curl -X POST "https://api.useapi.net/v1/google-flow/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model": "omni-flash", "prompt": "the subject walks toward camera and introduces herself", "duration": 8, "referenceImage_1": "user:12345-email:...-image:...", "referenceAudio_1": "Kore" }' ``` 视频到视频编辑(V2V):以 `Content-Type: video/mp4` 把 MP4 上传到 [POST /assets](/docs/api-google-flow-v1/post-google-flow-assets-email),再把返回的 id 作为 `referenceVideo_1` 传入,即可编辑这段视频。此模式仅限 Omni Flash,会把请求切换到 V2V 模式。不接受 `duration`(输出时长等于输入的裁剪窗口,`omni-flash` 最长 10 秒,`omni-flash-1.2` 最长 15 秒)。可以在 24 fps 的虚拟时间轴上用 `startFrameIndex_1`(0–239)和 `endFrameIndex_1`(1–240,240 = 10 秒)裁剪源视频,`omni-flash-1.2` 上最大可到 359 和 360(15 秒): ```bash curl -X POST "https://api.useapi.net/v1/google-flow/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model": "omni-flash", "prompt": "restyle the scene as a rainy neon-lit night, add ambient city sound", "referenceVideo_1": "user:12345-email:...-video:...", "startFrameIndex_1": 0, "endFrameIndex_1": 240, "async": true }' ``` 你还可以在提示词里放入 `@` 行内标记,它们会对应到你提供的槽位,例如 `@referenceImage_1`、`@character_1`、`@referenceAudio_1`。标记是可选的,每个标记都必须有对应的请求体参数。(`@referenceVideo_*` 不支持行内写法,请作为请求体字段传入。)见 [Inline @-mention markers](/docs/api-google-flow-v1/post-google-flow-videos#inline--mention-markers-optional)。 ### 音色与角色 Omni Flash 的音频和人物一致性功能靠两个简短的准备调用实现。 自定义音色:[POST /voices](/docs/api-google-flow-v1/post-google-flow-voices) 在 30 个系统音色之一的基础上,用你自己的 `dialog` 和 `voicePerformance` 保存一个音色。响应中的 `voice` 字段是一个参考 id,之后在 [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) 上作为 `referenceAudio_1..5` 传入: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/voices" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "john@gmail.com", "voice": "Achernar", "dialog": "Welcome to the demo.", "voicePerformance": "Cheerful, energetic delivery", "displayName": "Cheerful Narrator" }' # Response: { "voice": "user:12345-email:...-voice:...-mid:...", ... } ``` 每个 `referenceAudio_*` 槽位既可以填系统音色名(不区分大小写,30 个预设之一,如 `Aoede`、`Kore`、`Puck`、`Zephyr`),也可以填上面调用返回的用户音色 id。创建音色需要 reCAPTCHA(自动求解,见[常见问题](#frequently-asked-questions))。 可复用角色:[POST /characters](/docs/api-google-flow-v1/post-google-flow-characters) 把 1–2 张参考图和一个可选音色打包成一个有名字的角色。响应中的 `character` 字段就是作为 `character_1..10` 传入的值: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/characters" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "displayName": "Carol", "imageReference_1": "user:12345-email:...-image:abc123...", "voice": "user:12345-email:...-voice:...-mid:..." }' # Response: { "character": "user:12345-email:...-character:...-imgs:1-voice:...", ... } ``` 在 Omni Flash 上,角色适用于所有时长,并与 `referenceImage_*` 共用 10 张参考图的总额度(`referenceImages.length + Σ(character.imgs) ≤ 10`, Omni 1.1: 7)。`POST /characters` 不需要验证码。Veo 也能使用角色和音色,但额度更紧(3 张图、1 个音色、仅 8 秒),见 [What can use a character?](/docs/api-google-flow-v1/post-google-flow-characters#what-can-use-a-character)。 ### 用 Omni 1.2 延长视频 [POST /videos/extend](/docs/api-google-flow-v1/post-google-flow-videos-extend) 用 Omni 1.2 Flash 给任意短于 30 秒的视频每次续写 3 到 10 秒,可带最多 3 个音色、参考图或角色,返回一段连续的完整片段(仅限付费套餐)。[Gemini Omni 1.2 Flash API 中文教程](/docs/articles/gemini-omni-1-2-flash-api-zh#flow-walkthrough)里的完整流程把一段 10 秒视频用两种音色延长两次到 30 秒,成片见[下方示例](#examples)。 ### 用脚本批量生成 找到满意的一条往往要试很多次,手动一条条跑很繁琐。下面的 Node.js 脚本从 `prompts.json` 读取提示词列表,上传参考图、首尾帧或源视频,把 `character_*` id 和 `resolution` 原样传过去,以异步模式和 `model: "omni-flash"` 提交每个任务,然后轮询并下载每一个完成的 MP4。你可以一次排好一批,回头再挑最好的。如果某个组合会被 API 拒绝,比如只有尾帧没有首帧,脚本会在提交前给出警告并停止。 需要 [Node.js](https://nodejs.org) v21 或更高版本。把 `prompts.json` 和 `omni-flash.mjs` 放在同一个文件夹,运行 `node ./omni-flash.mjs API_TOKEN EMAIL`,其中 `API_TOKEN` 是你的 useapi.net [API Token](/docs/start-here/setup-useapi),`EMAIL` 是已绑定的 [Google Flow 账号](/docs/start-here/setup-google-flow)邮箱。脚本会按邮箱自动查找账号,并在提交前检查它的 `health` 字段。 想克隆到本地运行?完整的 `omni-flash.mjs` 和 `prompts.json` 在 GitHub 的 [`useapi/google-flow-api`](https://github.com/useapi/google-flow-api/tree/main/omni-flash) 仓库里。 在用 Claude Code 或 Codex?[omni-flash-video agent skill](https://github.com/useapi/google-flow-api/tree/main/skills/omni-flash-video) 能让智能体替你完成这一切:描述你想要的视频,告诉它图片在哪里,它会上传图片、编写请求、等待生成并保存 `.mp4`。安装命令:`npx skills add useapi/google-flow-api --skill omni-flash-video`。 <details markdown="block"> <summary>展开 `prompts.json`</summary> ```json [ { "prompt": "Audio-native text-to-video. By default model omni-flash with a landscape 8-second clip will be used." }, { "duration": 10, "prompt": "A 10-second clip (omni-flash only). Omni Flash is audio-native, so narration, dialogue and sound come from the prompt. To pin a specific voice, add referenceAudio_1 together with a referenceImage_* or character_*, as in the next prompt." }, { "duration": 8, "referenceImage_1": "./subject.jpeg", "referenceAudio_1": "Kore", "prompt": "Reference-to-video (R2V): the uploaded image is a reference, narrated by 'Kore'. Up to 7 referenceImage_* on omni-flash, 10 on omni-flash-1.2." }, { "duration": 8, "startImage": "./first_image.jpeg", "endImage": "./last_image.jpeg", "prompt": "Image-to-video with a start frame (startImage) and an end frame (endImage). The two frames are the only input — no referenceImage_*, character_* or referenceAudio_* alongside them." }, { "referenceVideo_1": "./source.mp4", "startFrameIndex_1": 0, "endFrameIndex_1": 240, "prompt": "Video-to-video edit (V2V): omni-flash restyles the uploaded MP4. No duration here — output matches the trim window (max 10 s). For all parameters see https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos" } ] ``` </details> <details markdown="block"> <summary>展开 `omni-flash.mjs` 脚本</summary> ```javascript /* Script version 1.3, November 11, 2026 Script to batch-generate audio-native videos with Gemini Omni Flash using the Google Flow API by useapi.net Uses the POST /videos endpoint in async mode (model: omni-flash by default, or omni-flash-1.2 per prompt) and polls GET /jobs/{jobId}. For more details visit https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos Installation Instructions: ========================== You need Node.js v21 or newer installed to run this script. Download and install Node.js from: - Windows, macOS, Linux: https://nodejs.org/ After installation, verify by running the following command in a terminal: node -v Running the Script: =================== Usage: node omni-flash.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE] Replace API_TOKEN with your actual useapi.net API token, see https://useapi.net/docs/start-here/setup-useapi Replace EMAIL with configured Google Flow email account, see https://useapi.net/docs/start-here/setup-google-flow If optional PROMPTS_FILE not provided prompts.json will be used. Example: -------- node omni-flash.mjs user:1234-abcdefhijklmnopqrstuv my@email.com This command executes the script using API token user:1234-abcdefhijklmnopqrstuv with my@email.com Google Flow account email. Changelog: ========== - June 15, 2026: Initial release. - September 11, 2026: Adds resolution, startImage / endImage (start and end frames, local files uploaded for you) and character_1..7. Accepts .jpg and upper-case file extensions. Stops with a warning before submitting combinations the API rejects, such as endImage without startImage or referenceAudio_* on its own. A prompt whose local startImage, endImage, referenceImage_* or referenceVideo_1 file fails to upload is skipped and logged to omni-flash_errors.txt instead of being submitted without it. Saves a downloaded video under its final name only once it has been fully received, so a failed download leaves no partial MP4 for the next run to skip as "already exists". - November 11, 2026: referenceImage_8..10 and character_8..10: omni-flash-1.2 takes up to 10 references (omni-flash 7). */ import readline from 'node:readline'; import fs from 'fs/promises'; import path from 'path'; import { writeFile } from 'node:fs/promises'; import { Readable } from 'node:stream'; // Constants const RESULTS_FILE = 'omni-flash_results.txt'; const ERRORS_FILE = 'omni-flash_errors.txt'; const DEFAULT_PROMPTS_FILE = 'prompts.json'; const MODEL = 'omni-flash'; // Reference slots: up to 10 on omni-flash-1.2, 7 on omni-flash, 3 on Veo (referenceImage_* and character_* together). const imageRefKeys = Array.from({ length: 10 }, (_, i) => `referenceImage_${i + 1}`); const characterKeys = Array.from({ length: 10 }, (_, i) => `character_${i + 1}`); const SLEEP_429 = 30 * 1000; // in milliseconds const SLEEP_POLL = 15 * 1000; // in milliseconds const urlAccounts = 'https://api.useapi.net/v1/google-flow/accounts'; const urlVideos = 'https://api.useapi.net/v1/google-flow/videos'; const urlJobs = 'https://api.useapi.net/v1/google-flow/jobs/'; const urlUploadAsset = 'https://api.useapi.net/v1/google-flow/assets/'; // Google Flow accepts png, jpeg and webp images, and mp4 video (for omni-flash V2V edit). const supportedImageExtensions = ['png', 'jpg', 'jpeg', 'webp']; const supportedVideoExtensions = ['mp4']; // { filename: mediaGenerationId } const uploadedFiles = {}; // Utility to sleep for given milliseconds const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); // Function to fetch configured Google Flow API accounts async function fetchAccounts(apiToken) { const response = await fetch(urlAccounts, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.error(`⛔ Error fetching accounts (HTTP ${response.status}): ${response.statusText}`); process.exit(1); } return response.json(); } const elapsedTimeSec = (start) => (Date.now() - start) / 1000; // Map a file extension to the Content-Type required by POST /assets const contentTypeForExt = (ext) => ext === 'png' ? 'image/png' : ext === 'webp' ? 'image/webp' : ext === 'mp4' ? 'video/mp4' : 'image/jpeg'; async function uploadAsset(apiToken, email, filename) { // Check if already uploaded if (uploadedFiles.hasOwnProperty(filename)) return uploadedFiles[filename]; const startTime = Date.now(); console.log(`⬆️ Account ${email} uploading file…`, filename); const body = new Blob([await fs.readFile(filename)]); const fileExt = filename.split('.').pop().toLowerCase(); const response = await fetch(`${urlUploadAsset}${encodeURIComponent(email)}`, { method: 'POST', headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}`, 'Content-Type': contentTypeForExt(fileExt) }, body }); if (response.ok) { const json = await response.json(); // POST /assets returns the reference id nested as mediaGenerationId.mediaGenerationId const mediaGenerationId = json?.mediaGenerationId?.mediaGenerationId; console.log(`🆗 mediaGenerationId (${elapsedTimeSec(startTime)} sec)`, mediaGenerationId); uploadedFiles[filename] = mediaGenerationId; } else { console.error(`❗ Unable to upload file HTTP ${response.status} (${elapsedTimeSec(startTime)} sec)`, await response.text()); // Do not attempt to upload failed file again uploadedFiles[filename] = undefined; } return uploadedFiles[filename]; } async function submit(apiToken, url, body, index, prompt) { const createResponse = await fetch(url, { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiToken}` }, body }); const createBody = await createResponse.text(); // Async POST /videos returns 201 Created with a jobid to poll. if (createResponse.status == 201) { const json = JSON.parse(createBody); // 201 async payload uses lowercase "jobid"; sync 200 uses "jobId". Accept either. const jobId = json.jobid ?? json.jobId; if (jobId) { await fs.appendFile(RESULTS_FILE, `${jobId},#${index}:${prompt}\n`); console.log(`✅ jobId`, jobId); return 201; } else { const error = `No jobid found in HTTP 201 response`; console.log(`❓ ${error}`, createBody); await fs.appendFile(ERRORS_FILE, `${error},#${index}:${prompt}\n`); return 500; } } else { switch (createResponse.status) { case 429: console.log(`🔄️ Retry on HTTP ${createResponse.status}`, createBody); break; case 503: console.log(`🔄️ Service unavailable, retry on HTTP ${createResponse.status}`, createBody); break; case 400: console.log(`🛑 Rejected request (validation or content policy)`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${prompt}\n`); break; case 402: console.log(`🛑 No subscription / insufficient credits`, createBody); break; default: console.log(`❗ FAILED with HTTP ${createResponse.status}`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${prompt}\n`); } return createResponse.status; } } // Submit a single prompt to POST /videos with model omni-flash (or the prompt's own model) in async mode. // startImage = start frame (I2V), endImage = end frame (I2V-FL, requires startImage) — the frames are the only input; // referenceImage_1..10 = R2V image refs; character_1..10 = POST /characters ids (10 on omni-flash-1.2, 7 on omni-flash); // referenceVideo_1 = V2V edit (no duration); referenceAudio_1..5 = system voice name or POST /voices user-voice id; // resolution = 720p (default) or 360p; model = 'omni-flash' (Omni 1.1, the default) or 'omni-flash-1.2' (3–15 s, per-second credits). async function submitVideo(apiToken, email, prompt, index) { const { prompt: text, model = MODEL, aspectRatio, duration, resolution, count, startImage, endImage, referenceVideo_1, startFrameIndex_1, endFrameIndex_1, referenceAudio_1, referenceAudio_2, referenceAudio_3, referenceAudio_4, referenceAudio_5 } = prompt; console.log(`🚀 ${model} » Prompt #${index} • account ${email} …`); // Upload any local image/video files and swap the paths for their mediaGenerationId. const resolveRef = async (ref) => ref && (ref.startsWith('./') || ref.includes('.')) && [...supportedImageExtensions, ...supportedVideoExtensions].includes(ref.split('.').pop().toLowerCase()) ? await uploadAsset(apiToken, email, ref) : ref; const startImageId = await resolveRef(startImage); const endImageId = await resolveRef(endImage); const refImages = {}; for (const key of imageRefKeys) refImages[key] = await resolveRef(prompt[key]); const refVideo_1 = await resolveRef(referenceVideo_1); // A local file that failed to upload would be left out of the body, and the prompt would still be // generated (and charged) without it. Skip the prompt instead. uploadAsset remembers the failed file, // so a later prompt using it is skipped too, without another upload attempt. const failedUploads = [ ['startImage', startImage, startImageId], ['endImage', endImage, endImageId], ...imageRefKeys.map(key => [key, prompt[key], refImages[key]]), ['referenceVideo_1', referenceVideo_1, refVideo_1] ].filter(([, file, id]) => file && !id); for (const [param, file] of failedUploads) { console.error(`🛑 Prompt #${index} skipped: ${param} ${file} failed to upload`); await fs.appendFile(ERRORS_FILE, `Upload failed for ${param} ${file},#${index}:${text}\n`); } if (failedUploads.length) return; // V2V edit does not accept duration — output matches the trim window. const isV2V = !!refVideo_1; const body = JSON.stringify({ model, email, prompt: text, aspectRatio, duration: isV2V ? undefined : duration, resolution, count, startImage: startImageId, endImage: endImageId, ...refImages, ...Object.fromEntries(characterKeys.map(key => [key, prompt[key]])), referenceVideo_1: refVideo_1, startFrameIndex_1, endFrameIndex_1, referenceAudio_1, referenceAudio_2, referenceAudio_3, referenceAudio_4, referenceAudio_5, async: true }); return await submit(apiToken, urlVideos, body, index, text); } // Function to download videos async function download(apiToken) { if (! await fileExists(RESULTS_FILE)) return; try { const resultsContent = await fs.readFile(RESULTS_FILE, 'utf8'); const lines = resultsContent.trim().split('\n'); for (const line of lines) { const [jobId, prompt] = line.split(','); console.log(`👉 ${jobId}`); while (true) { const response = await fetch(`${urlJobs}${jobId}`, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.log(`🛑 Poll failed ${jobId} (HTTP ${response.status}):\n${prompt}\n`, await response.text()); break; } const jobBody = await response.json(); const { status, error, response: jobResponse } = jobBody; if (status == 'failed') { console.error(`🛑 FAILED ${jobId} (${error}):\n${prompt}\n`); break; } if (status == 'completed') { const media = jobResponse?.media ?? []; if (media.length == 0) console.error(`🛑 Completed but no media for ${jobId}:\n${prompt}\n`); // A single prompt with count > 1 returns multiple videos. for (let i = 0; i < media.length; i++) { const url = media[i]?.videoUrl; const videoFilename = `${jobId.replace(/[:*]/g, '_')}_${i + 1}.mp4`; try { await fs.access(videoFilename); console.log(`⚠️ ${videoFilename} already exists. Skipping download.`); continue; } catch { // File does not exist, proceed with downloading } if (url) { console.log(`✅ Downloading ${url} to ${videoFilename}`); // Stream into a temporary file and rename it once the whole video has arrived, so a download // that drops mid-stream leaves no partial file behind for the next run to skip as "already exists". const tempFilename = `${videoFilename}.part`; try { const videoResponse = await fetch(url); if (!videoResponse.ok) { console.error(`⛔ Unable to download ${jobId} (HTTP ${videoResponse.status}):\n${prompt}\n`, url); continue; } const stream = Readable.fromWeb(videoResponse.body); await writeFile(tempFilename, stream); await fs.rename(tempFilename, videoFilename); } catch (err) { await fs.rm(tempFilename, { force: true }); console.error(`⛔ Error during download: ${err}`); } } else console.error(`🛑 No videoUrl for ${jobId} media #${i + 1}:\n${prompt}\n`); } break; } console.log(`⌛ ${jobId} status (${status}) and is still in progress, waiting…`); await sleep(SLEEP_POLL); } } } catch (error) { console.log(`⛔ Error during download:`, error.stack || error); } } // Main function async function main() { const apiToken = process.argv[2]; const email = process.argv[3]; const promptFile = process.argv[4] || DEFAULT_PROMPTS_FILE; if (!apiToken || !email) { console.error('Usage: node omni-flash.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE]'); process.exit(1); } console.info('Script v1.3'); console.info('Node version is: ' + process.version); try { if (await fileExists(RESULTS_FILE)) { let user_input; while (!['y', 'n'].includes(user_input)) { user_input = (await promptUser(`❔ ${RESULTS_FILE} file detected. Do you want to download the results now? (y/n): `))?.toLowerCase(); if (user_input == 'y') { await download(apiToken); await fs.unlink(RESULTS_FILE); } } } const start = new Date(); try { console.info('START EXECUTION', start); await execute(apiToken, email, promptFile); // Pass the promptFile to execute function } finally { console.info('COMPLETED', new Date()); console.info('EXECUTION ELAPSED', diffInMinutesAndSeconds(start, new Date())); } try { console.info('START DOWNLOAD', start); await download(apiToken); } finally { console.info('TOTAL ELAPSED', diffInMinutesAndSeconds(start, new Date())); } } catch (error) { console.error('⛔ Error during execution:', error.stack || error); } } // Modify the execute function to accept promptFile as a parameter async function execute(apiToken, email, promptFile) { const accounts = await fetchAccounts(apiToken); console.info(`Configured Google Flow API accounts (${Object.keys(accounts).length}):`, Object.keys(accounts).join(', ')); if (Object.keys(accounts).length <= 0) { console.error(`⛔ No configured Google Flow accounts found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (!accounts[email]) { console.error(`⛔ Account ${email} not found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (accounts[email].health && accounts[email].health !== 'OK') { console.error(`⛔ Account ${email} health is '${accounts[email].health}'. Please resolve and update the account, see https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } const promptData = await fs.readFile(promptFile, 'utf8'); const prompts = JSON.parse(promptData); console.log(`Total number of prompts to process`, prompts.length); let warnings = []; // Parameters accepted by this script for the omni-flash POST /videos endpoint. // See https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos for the full parameter set. const supportedParams = [ 'prompt', 'model', 'aspectRatio', 'duration', 'resolution', 'count', 'startImage', 'endImage', ...imageRefKeys, ...characterKeys, 'referenceVideo_1', 'startFrameIndex_1', 'endFrameIndex_1', 'referenceAudio_1', 'referenceAudio_2', 'referenceAudio_3', 'referenceAudio_4', 'referenceAudio_5' ]; const audioRefKeys = ['referenceAudio_1', 'referenceAudio_2', 'referenceAudio_3', 'referenceAudio_4', 'referenceAudio_5']; const invalidKeys = (prompt) => Object.keys(prompt).filter(key => !key.startsWith('__') && !supportedParams.includes(key)) // Validate a local file path reference (skip already-uploaded mediaGenerationId strings). const looksLikePath = (ref) => ref && (ref.startsWith('./') || (ref.includes('.') && !ref.startsWith('user:'))); for (let i = 1; i <= prompts.length; i++) { const prompt = prompts[i - 1]; const { prompt: text, referenceVideo_1, duration, startImage, endImage } = prompt; const validateFile = async (file, allowedExts) => { if (looksLikePath(file)) { try { await fs.access(file); } catch { warnings.push(`⚠️ File '${file}' does not exist. Prompt ${i}`); } const ext = file.split('.').pop().toLowerCase(); if (!allowedExts.includes(ext)) warnings.push(`⚠️ File ${file} extension ${ext} not supported. Prompt ${i}`); } }; const notSupported = invalidKeys(prompt); if (notSupported.length) warnings.push(`⚠️ Following params not supported: ${notSupported.join(',')}. Prompt ${i}`); if (!text) warnings.push(`⚠️ prompt is required. Prompt ${i}`); // V2V edit (referenceVideo_1) does not accept duration — output matches the trim window. if (referenceVideo_1 && duration) warnings.push(`⚠️ duration is not accepted with referenceVideo_1 (V2V edit). Prompt ${i}`); if (endImage && !startImage) warnings.push(`⚠️ endImage requires startImage (end-frame-only is not supported). Prompt ${i}`); // Start/end frames (I2V, I2V-FL) are the only input in that mode — the API rejects anything alongside them. if (startImage || endImage) { if (referenceVideo_1) warnings.push(`⚠️ startImage/endImage cannot be combined with referenceVideo_1 (V2V edit). Prompt ${i}`); if ([...imageRefKeys, ...characterKeys].some(k => prompt[k])) warnings.push(`⚠️ startImage/endImage cannot be combined with referenceImage_* or character_*. Prompt ${i}`); if (audioRefKeys.some(k => prompt[k])) warnings.push(`⚠️ startImage/endImage cannot be combined with referenceAudio_*. Prompt ${i}`); } // A voice needs a referenceImage_* or character_* to attach to (or a V2V edit) — the API rejects referenceAudio_* on its own. // With start/end frames the check above already applies. if (!startImage && !endImage && !referenceVideo_1 && audioRefKeys.some(k => prompt[k]) && ![...imageRefKeys, ...characterKeys].some(k => prompt[k])) warnings.push(`⚠️ referenceAudio_* requires a referenceImage_* or character_* (or referenceVideo_1 for a V2V edit). Prompt ${i}`); await Promise.all([ validateFile(referenceVideo_1, supportedVideoExtensions), ...['startImage', 'endImage', ...imageRefKeys].map(k => validateFile(prompt[k], supportedImageExtensions)) ]); } if (warnings.length > 0) { warnings.forEach(warning => console.warn(warning)); console.error(`⛔ Execution stopped due to warnings.`); process.exit(1); } for (let i = 0; i < prompts.length; i++) { const prompt = prompts[i]; while (true) { const responseCode = await submitVideo(apiToken, email, prompt, i + 1); if (responseCode == 429 || responseCode == 503) await sleep(SLEEP_429); else if (responseCode == 402) { process.exit(1); } else break; } } } // Utility function to check if a file exists async function fileExists(path) { try { await fs.access(path); return true; } catch { return false; } } // Function to prompt user input async function promptUser(query) { const rl = readline.createInterface({ input: process.stdin, output: process.stdout }); return new Promise((resolve) => rl.question(query, answer => { rl.close(); resolve(answer); })); } function diffInMinutesAndSeconds(date1, date2) { const diffInSeconds = Math.floor((date2 - date1) / 1000); return `${Math.floor(diffInSeconds / 60)} minutes ${diffInSeconds % 60} seconds`; }; main(); ``` </details> ### 示例 下面的视频都是通过这个 Google Flow API 真实生成的 Gemini Omni Flash 结果,涵盖 `model: "omni-flash-1.2"` 和 `model: "omni-flash"`、延长、音色、参考、角色和 V2V 编辑。 ###### Omni 1.2 延长:10 秒视频延长两次到 30 秒,两种音色 {: .no_toc #omni-12-extend--a-10-second-video-extended-twice-to-30-seconds-with-two-voices } <video poster="https://media.useapi.net/articles/2026-06-15-omni-flash-bash/261106-google-flow-omni-1-2-magician-extended-30s-web-poster.jpg" controls width="100%" style="max-width:640px;border-radius:8px"> <source src="https://media.useapi.net/articles/2026-06-15-omni-flash-bash/261106-google-flow-omni-1-2-magician-extended-30s-web.mp4" type="video/mp4"> </video> 来自 [Google Flow: Omni 1.2 Flash, 15-Second Videos, and Extend with Voices](/blog/261106)(英文):前 10 秒用 `omni-flash-1.2` 生成,然后用 `referenceAudio_1` 调用两次 `POST /videos/extend`。 ###### V2V 编辑:把上传的 MP4 改成卡通风格,动作和构图不变 {: .no_toc #v2v-edit--restyle-an-uploaded-mp4-into-a-cartoon-same-motion-and-framing } <video poster="https://media.useapi.net/blog/2026-05-20-260520/google-flow-edit-video-poster.jpg" controls width="100%" style="max-width:640px;border-radius:8px"> <source src="https://media.useapi.net/blog/2026-05-20-260520/google-flow-edit-video.mp4" type="video/mp4"> </video> 来自 [Google Flow: Gemini Omni Flash](/blog/260520)(英文):用 `referenceVideo_1` 编辑。 ###### 行内 @ 标记:带 @character_1、@referenceImage_1、@referenceImage_2 和自定义音色的 R2V 黑色电影风格视频 {: .no_toc #inline--mentions--r2v-noir-video-with-character_1-referenceimage_1-referenceimage_2-and-a-custom-voice } <video poster="https://media.useapi.net/blog/2026-06-09-260609/noir-shot-1-poster.jpg" controls width="100%" style="max-width:640px;border-radius:8px"> <source src="https://media.useapi.net/blog/2026-06-09-260609/noir-shot-1.mp4" type="video/mp4"> </video> 来自 [Google Flow: Inline @-mentions](/blog/260609)(英文):用行内 `@` 标记逐一指定每个参考。 ###### 角色 + V2V 编辑:把两个可复用角色合成进黑色电影风格视频 {: .no_toc #characters--v2v-edit--composites-two-reusable-characters-into-the-noir-video } <video poster="https://media.useapi.net/blog/2026-06-09-260609/edit-1-poster.jpg" controls width="100%" style="max-width:640px;border-radius:8px"> <source src="https://media.useapi.net/blog/2026-06-09-260609/edit-1.mp4" type="video/mp4"> </video> 来自 [Google Flow: Inline @-mentions](/blog/260609)(英文):`referenceVideo_1` V2V 编辑,配合行内 `@character_*`。音色和角色的准备流程另见 [Reusable Voices and Characters](/blog/260605)(英文)。 ### 常见问题 - **Gemini Omni Flash 是什么?** 通过 useapi.net,在 [Google Flow API](/docs/api-google-flow-v1) 上设置 `model: "omni-flash-1.2"`(Omni 1.2 Flash)或 `model: "omni-flash"`(Omni 1.1 Flash),就能调用 Gemini Omni Flash,即 [Google Flow](https://flow.google.com) 里 Google 的[原生音频视频模型](https://deepmind.google/models/model-cards/gemini-omni-flash/)。与无声视频模型不同,它在同一条视频里同时生成配乐、旁白、对白和环境音,并支持图片、视频和音频参考以及可复用角色。 - **Omni Flash 和 Veo 3.1 有什么区别?** 通过 useapi.net,两者都运行在同一个 Google Flow API 上,用 `model` 字段选择。Veo 是画质更高的纯文本生成视频和图生视频模型,而 Omni Flash 原生生成音频、支持丰富的参考素材,可以做视频到视频编辑(`referenceVideo_1`),一条视频可用多个音色,任意时长都能用可复用角色,视频也比 Veo 更长。具体限制见[参考模式](#reference-modes)。 - **能用我自己的音色、参考视频或参考音频吗?** 通过 useapi.net 可以。用内置系统音色或 [POST /voices](/docs/api-google-flow-v1/post-google-flow-voices) 创建的自定义音色配旁白,作为 `referenceAudio_1..5` 传入,也可以用 [POST /assets](/docs/api-google-flow-v1/post-google-flow-assets-email) 上传 MP4,作为 `referenceVideo_1` 编辑(V2V)。各模式的限制见[参考模式](#reference-modes)和[音色与角色](#voices--characters)。 - **Omni Flash 有官方 API 吗?** 通过 useapi.net 调用 Omni 1.1 Flash 远比 Google 自己的 API 便宜:一条 8 秒 720p 视频在 Google AI Ultra(199.99 美元)上约 0.10 美元,而官方 [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) 为 0.81 美元,官方自 2026 年 6 月 30 日起按秒出售该模型(截至 2026 年 11 月)。它通过标准 REST 接口运行在你的 Google Flow 网站订阅上。 - **Omni Flash 能生成超过 10 秒的视频吗?** 通过 useapi.net 可以:Omni 1.2 Flash(`model: "omni-flash-1.2"`)一次调用最长 15 秒,[POST /videos/extend](/docs/api-google-flow-v1/post-google-flow-videos-extend) 每次还能带音色续写最多 10 秒。一条 8 秒 720p 视频在 Google AI Ultra(199.99 美元)上约 0.19 美元,而 [Google 自己的 API](https://cloud.google.com/blog/products/ai-machine-learning/gemini-omni-1-2-flash-generally-available) 为 0.56 美元(截至 2026 年 11 月)。Google Flow 和 Google Vids 中的所有时长限制和价格见 [Gemini Omni 1.2 Flash API 中文教程](/docs/articles/gemini-omni-1-2-flash-api-zh)。 - **需要自己解验证码吗?** 通过 useapi.net 你永远不用自己解。Google Flow 每生成一条视频、每创建一个新音色都要求 reCAPTCHA,useapi.net 的 worker 会自动求解:你的第一个 Google Flow 账号赠送 300 次免费求解,使用我们自己的 AntiCaptcha、CapSolver 和 EzCaptcha 密钥,之后用 [POST /accounts/captcha-providers](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers) 添加你自己的打码服务密钥。[POST /characters](/docs/api-google-flow-v1/post-google-flow-characters) 不需要验证码。 ### 结语 有问题欢迎加入我们的 <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord 服务器</a> 或 <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram 频道</a>。 示例代码见 [GitHub 仓库](https://github.com/useapi/google-flow-api)。 AI 助手也可以替你操作 Google Flow:托管的 [Google Flow MCP 服务器](/docs/api-google-flow-v1/mcp)让 Claude Code、Cursor 和 VS Code 与 Google Flow Agent 对话,由它在你的账号上生成图片和视频。 ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/omni-flash-bash === Document URL: https://useapi.net/docs/articles/omni-flash-bash --- layout: default title: How to Generate Audio-Native AI Video with Gemini Omni Flash via the Google Flow API description: "Gemini Omni Flash in the useapi.net Google Flow API with code: image references, characters, voices and V2V edits on Omni 1.2 and 1.1, plus a batch script." keywords: [Gemini Omni Flash, Omni 1.2 Flash, Omni Flash API, audio-native video, Google Flow, extend video, voices, characters, video editing, tutorial, code] parent: Articles nav_exclude: true date: 2026-06-15 last_modified: 2026-11-12 nav_order: 830 repo: https://github.com/useapi/google-flow-api translation_key: omni-flash --- ## How to Generate Audio-Native AI Video with Gemini Omni Flash via the Google Flow API 8 min read • June 15, 2026 (November 12, 2026) ## Table of contents ### Introduction [Gemini Omni Flash](https://deepmind.google/models/model-cards/gemini-omni-flash/) makes audio-native AI video from a single `curl` through the useapi.net [Google Flow API](/docs/api-google-flow-v1), with synced voices, characters and video-to-video edits, on your [Google Flow](https://flow.google.com) website subscription ([Google AI](https://gemini.google/subscriptions/): Omni 1.1 Flash on Plus, Pro or Ultra, Omni 1.2 Flash on every plan, free accounts up to 10 seconds). A 10-second 720p video costs $0.12 on Google AI Ultra $199.99, against $1.01 on the official [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) (as of November 2026), with no Google Cloud project or API key. The same subscription also makes Omni video in [Google Vids](/docs/api-google-vids-v1), without spending Flow credits. Google Flow labels this model Omni 1.1 Flash in its interface, and the API value is `model: "omni-flash"`. Omni 1.2 Flash, which Google released on November 5, 2026, is a separate value, `model: "omni-flash-1.2"`: any length from 3 to 15 seconds, per-second credits, and the model that [extends a video](#extend-a-video-with-omni-12) by up to 10 seconds at a time. Code that sends `omni-flash` keeps getting 1.1. For 15-second videos, extend with voices and the price per video in Google Flow and Google Vids, see [How to Use the Gemini Omni 1.2 Flash API](/docs/articles/gemini-omni-1-2-flash-api). Omni Flash is the [same Google Flow API](/docs/api-google-flow-v1) as Veo, picked with one field — `model: "omni-flash-1.2"` or `model: "omni-flash"` — but it is a different kind of model. Where Veo is a strong plain text-to-video engine, Omni Flash is audio-native and reference-rich: - Sound is generated as part of the video — narration, dialog, and ambience come out of the same model, not bolted on after. - Voices — 30 built-in system voice presets plus custom voices you create from your own dialog and performance notes, fed in via `referenceAudio_1..5`. - Image and video references — up to 10 reference images on Omni 1.2 Flash (7 on Omni 1.1 Flash) for reference-to-video (R2V), and video-to-video (V2V) editing of an uploaded or generated video via `referenceVideo_1`. - Reusable characters — bundle reference images + a voice into a named character and reuse it across videos. - Longer videos — Omni 1.1 Flash makes 4, 6, 8 or 10 seconds and Omni 1.2 Flash any length from 3 to 15 (Veo tops out at `8`), and Omni 1.2 extends a video in steps of up to 10 seconds. This guide shows the two-call workflow with copy-paste `curl`, the reference modes that make Omni Flash distinctive, then a runnable Node.js script that batch-generates from a list of prompts. For plain text-to-video, see the sibling [Veo 3.1 tutorial](/docs/articles/google-flow-bash). ### Supported model This guide uses Google's audio-native video models, Omni 1.1 Flash (`model: "omni-flash"`) and Omni 1.2 Flash (`model: "omni-flash-1.2"`). For Omni 1.1, credit cost scales with video length: | Duration | Credits per video | |----------|------------------------| | 4s | 7 | | 6s | 10 | | 8s | 12 | | 10s | 15 | | V2V edit | 20 | Those are the costs at the default `720p`. Passing `resolution: "360p"` costs about half — 4 / 5 / 6 / 7 credits by length, 10 for a V2V edit — and a 360p video can be promoted to 720p afterwards with [POST /videos/upscale](/docs/api-google-flow-v1/post-google-flow-videos-upscale). Omni 1.2 Flash (`model: "omni-flash-1.2"`) takes any whole number of seconds from 3 to 15 and prices them per second, the same on every plan: | Length | 720p | 360p | |--------|------|------| | 3s | 9 | 3 | | 8s | 24 | 8 | | 10s | 30 | 10 | | 15s | 60 | 20 | Up to 10 seconds it is 3 credits a second at 720p and 1 at 360p, and every second past 10 costs double. A V2V edit costs the same as a video of the edited length, and 1.2 edits up to 15 seconds of a clip. Free Google accounts can use 1.2 for videos of up to 10 seconds. Omni Flash accepts five modes on [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos): plain text-to-video (T2V), reference-to-video (R2V) with up to 10 `referenceImage_1..10` on Omni 1.2 Flash (7 on Omni 1.1 Flash), image-to-video from a start frame via `startImage` (I2V), image-to-video between a start and an end frame via `startImage` + `endImage` (I2V-FL), and video-to-video editing (V2V) of an uploaded MP4 via `referenceVideo_1`. See [Reference modes](#reference-modes) below. ### Pricing Omni 1.1 Flash needs a paid Google AI subscription (Plus, Pro or Ultra), Omni 1.2 Flash works on free accounts up to 10 seconds, and useapi.net adds no per-video charge. Each video spends Flow credits by length (see [Supported model](#supported-model)). The price per video on every plan, against the official Gemini API, is in the [Google Flow price table](/docs/api-google-flow-v1#pricing). A Google AI plan also comes with a monthly allowance in [Google Vids](https://docs.google.com/videos), which generates video of up to 15 seconds with Gemini Omni 1.2 Flash ([Google's announcement](https://workspaceupdates.googleblog.com/2026/11/gemini-omni-12-flash-now-in-vids-with-15second-generations-and-improved-quality.html)) and does not use Flow credits. On Ultra $199.99 (Google calls it Ultra 20x) it is 10,000 seconds of video a month — about 1,000 more 10-second clips at 1080p on top of the ~1,666 ten-second Omni 1.1 Flash clips (or ~833 Omni 1.2 Flash clips at 720p) that Flow's 25,000 credits buy. Those seconds are shared by everyone on a Google family plan. Other plans get less (see Google's [Gemini in Google Vids](https://support.google.com/docs/answer/15609411) page), and the free accounts we tested had none. The [Google Vids API](/docs/api-google-vids-v1) uses this allowance with no captcha. Connect the account with [Setup Google Vids](/docs/start-here/setup-google-vids). ### Generate a video in two API calls You need a useapi.net [API token](/docs/start-here/setup-useapi) and a connected [Google Flow account](/docs/start-here/setup-google-flow) on a paid Google AI subscription (Plus, Pro or Ultra) for the Omni 1.1 Flash example below (Omni 1.2 Flash also runs on a free account, up to 10 seconds). Video jobs are asynchronous: pass `async: true` and the create call returns a `jobid` immediately, then you poll until the video is ready. 1. Submit the job — `POST https://api.useapi.net/v1/google-flow/videos` with `model: "omni-flash"`: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A lighthouse keeper narrates the coming storm, waves crashing below", "model": "omni-flash", "aspectRatio": "landscape", "duration": 10, "async": true }' ``` Omni Flash is audio-native, so it generates the soundtrack — the keeper's narration and the crashing waves — straight from the prompt, no audio parameter required. In async mode the response returns immediately with `201 Created`, a lowercase `jobid`, and `status: "created"`: ```json { "jobid": "j1731859234567v-u12345-email:jo***@gmail.com-bot:google-flow", "type": "video", "status": "created", "created": "2026-06-15T12:34:56.789Z", "request": { "async": true, "prompt": "A lighthouse keeper narrates the coming storm, waves crashing below", "model": "omni-flash", "aspectRatio": "landscape", "duration": 10 } } ``` 2. Poll for the result — `GET https://api.useapi.net/v1/google-flow/jobs/{jobId}`: ```bash curl "https://api.useapi.net/v1/google-flow/jobs/JOBID" \ -H "Authorization: Bearer $USEAPI_TOKEN" ``` `status` moves through `created` → `started` → `completed`. When it reaches `completed`, the finished MP4 is in `response.media[].videoUrl` (a single prompt with `count > 1` returns one entry per video): ```json { "jobid": "j1731859234567v-...", "type": "video", "status": "completed", "response": { "media": [ { "mediaGenerationId": "user:12345-email:6a6f...-video:a1d95d21-...", "videoUrl": "https://flow-content.google/video/a1d95d21-...?Expires=...", "thumbnailUrl": "https://flow-content.google/image/a1d95d21-...?Expires=..." } ], "remainingCredits": 18760 } } ``` Omni Flash typically finishes in 60–180 seconds. The signed `videoUrl` is valid for about 6 hours, so download promptly. Prefer not to poll? Pass a `replyUrl` in the create body to receive a webhook callback when the job completes. ### Reference modes Omni Flash's distinctive value is how much you can feed it as a reference. All references come from the [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email) upload endpoint (or, for characters, from [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters)). The upload response nests the reference id at `mediaGenerationId.mediaGenerationId` — that nested string is what you pass back. The modes accepted by `omni-flash` (from the [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos#references) docs): | Mode | Parameter(s) | Omni Flash limit | |------|--------------|------------------| | Reference-to-video (R2V) | `referenceImage_1..10` | up to 10 image refs on `omni-flash-1.2`, 7 on `omni-flash` | | Image-to-video (I2V) | `startImage` | one start frame | | Image-to-video, first + last (I2V-FL) | `startImage` + `endImage` | the two frames only — no other refs | | Video-to-video edit (V2V) | `referenceVideo_1` (+ optional `startFrameIndex_1` / `endFrameIndex_1`) | one uploaded MP4 | | Characters | `character_1..10` (from [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters)) | 10 total combined with `referenceImage_*` on `omni-flash-1.2`, 7 on `omni-flash` | | Voice narration | `referenceAudio_1..5` | up to 5 (R2V) / up to 3 (V2V edit) | Reference-to-video (R2V) — upload one or more images, then pass them as `referenceImage_1`, `referenceImage_2`, … (slots `_4`..`_7` are Omni Flash only). Image references cannot be combined with `startImage`/`endImage`. ```bash # 1. Upload a reference image — the id is nested one level deep: curl -X POST "https://api.useapi.net/v1/google-flow/assets/john%40gmail.com" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: image/jpeg" \ --data-binary @subject.jpeg # Response: { "mediaGenerationId": { "mediaGenerationId": "user:12345-email:...-image:..." }, ... } # 2. Generate, narrated by a system voice curl -X POST "https://api.useapi.net/v1/google-flow/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model": "omni-flash", "prompt": "the subject walks toward camera and introduces herself", "duration": 8, "referenceImage_1": "user:12345-email:...-image:...", "referenceAudio_1": "Kore" }' ``` Video-to-video edit (V2V) — upload an MP4 with `Content-Type: video/mp4` to [POST /assets](/docs/api-google-flow-v1/post-google-flow-assets-email), then pass the returned id as `referenceVideo_1` to edit that video. This is Omni Flash only and switches the request into V2V mode. `duration` is not accepted (output length matches the input trim window, max 10 s on `omni-flash` and 15 s on `omni-flash-1.2`). Optionally trim the source on a 24 fps virtual timeline with `startFrameIndex_1` (0–239) and `endFrameIndex_1` (1–240, where 240 = 10 s), or up to 359 and 360 (15 s) on `omni-flash-1.2`: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/videos" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model": "omni-flash", "prompt": "restyle the scene as a rainy neon-lit night, add ambient city sound", "referenceVideo_1": "user:12345-email:...-video:...", "startFrameIndex_1": 0, "endFrameIndex_1": 240, "async": true }' ``` You can also place inline `@`-markers in the prompt that resolve to the slots you supply — e.g. `@referenceImage_1`, `@character_1`, `@referenceAudio_1`. Markers are opt-in and each must have a matching body param. (`@referenceVideo_*` is not supported inline — pass it as a body field.) See [Inline @-mention markers](/docs/api-google-flow-v1/post-google-flow-videos#inline--mention-markers-optional). ### Voices & characters Two short setup calls power Omni Flash's audio and identity features. Custom voices — [POST /voices](/docs/api-google-flow-v1/post-google-flow-voices) saves a voice built on one of the 30 system presets with your own `dialog` and `voicePerformance`. The response `voice` field is a reference-id you then pass as `referenceAudio_1..5` on [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos): ```bash curl -X POST "https://api.useapi.net/v1/google-flow/voices" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "john@gmail.com", "voice": "Achernar", "dialog": "Welcome to the demo.", "voicePerformance": "Cheerful, energetic delivery", "displayName": "Cheerful Narrator" }' # Response: { "voice": "user:12345-email:...-voice:...-mid:...", ... } ``` Each `referenceAudio_*` slot accepts either a system voice name (case-insensitive, one of the 30 presets such as `Aoede`, `Kore`, `Puck`, `Zephyr`) or a user voice id from the call above. Voice creation requires reCAPTCHA (solved automatically — see [the FAQ](#frequently-asked-questions)). Reusable characters — [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters) bundles 1–2 reference images plus an optional voice into a named character. The response `character` field is what you pass as `character_1..10`: ```bash curl -X POST "https://api.useapi.net/v1/google-flow/characters" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "displayName": "Carol", "imageReference_1": "user:12345-email:...-image:abc123...", "voice": "user:12345-email:...-voice:...-mid:..." }' # Response: { "character": "user:12345-email:...-character:...-imgs:1-voice:...", ... } ``` On Omni Flash, characters work in all durations and share the 10-total image-ref budget with `referenceImage_*` (`referenceImages.length + Σ(character.imgs) ≤ 10`, Omni 1.1: 7). `POST /characters` does not require a captcha. Characters and voices are also usable from Veo, but with tighter budgets (3 images, 1 voice, 8 s only) — see [What can use a character?](/docs/api-google-flow-v1/post-google-flow-characters#what-can-use-a-character). ### Extend a video with Omni 1.2 [POST /videos/extend](/docs/api-google-flow-v1/post-google-flow-videos-extend) adds 3 to 10 seconds at a time with Omni 1.2 Flash to any video shorter than 30 seconds, with up to 3 voices, image references or characters, and returns one continuous clip (paid plans only). The walkthrough in [How to Use the Gemini Omni 1.2 Flash API](/docs/articles/gemini-omni-1-2-flash-api#flow-walkthrough) extends a 10-second video twice to 30 seconds with two voices, the [example below](#examples). ### Batch-generate with a script Finding the right take takes many attempts, and running them by hand is tedious. The Node.js script below reads a list of prompts from `prompts.json`, uploads any reference images, start and end frames or source videos, passes `character_*` ids and `resolution` straight through, submits each job in async mode with `model: "omni-flash"`, then polls and downloads every finished MP4 — so you can queue a batch and come back to the winners. It stops with a warning before submitting a combination the API would reject, such as an end frame without a start frame. You need [Node.js](https://nodejs.org) v21 or newer. Put `prompts.json` and `omni-flash.mjs` in the same folder and run `node ./omni-flash.mjs API_TOKEN EMAIL`, where `API_TOKEN` is your useapi.net [API token](/docs/start-here/setup-useapi) and `EMAIL` is your connected [Google Flow account](/docs/start-here/setup-google-flow) email. The script looks the account up by email automatically and checks its `health` field before submitting. Prefer to clone and run it locally? The complete `omni-flash.mjs` and `prompts.json` are on GitHub in [`useapi/google-flow-api`](https://github.com/useapi/google-flow-api/tree/main/omni-flash). Working in Claude Code or Codex? The [omni-flash-video agent skill](https://github.com/useapi/google-flow-api/tree/main/skills/omni-flash-video) lets the agent do all of this for you: describe the video, point it at your images, and it uploads them, writes the request, waits and saves the `.mp4`. Install it with `npx skills add useapi/google-flow-api --skill omni-flash-video`. <details markdown="block"> <summary>Expand `prompts.json`</summary> ```json [ { "prompt": "Audio-native text-to-video. By default model omni-flash with a landscape 8-second clip will be used." }, { "duration": 10, "prompt": "A 10-second clip (omni-flash only). Omni Flash is audio-native, so narration, dialogue and sound come from the prompt. To pin a specific voice, add referenceAudio_1 together with a referenceImage_* or character_*, as in the next prompt." }, { "duration": 8, "referenceImage_1": "./subject.jpeg", "referenceAudio_1": "Kore", "prompt": "Reference-to-video (R2V): the uploaded image is a reference, narrated by 'Kore'. Up to 7 referenceImage_* on omni-flash, 10 on omni-flash-1.2." }, { "duration": 8, "startImage": "./first_image.jpeg", "endImage": "./last_image.jpeg", "prompt": "Image-to-video with a start frame (startImage) and an end frame (endImage). The two frames are the only input — no referenceImage_*, character_* or referenceAudio_* alongside them." }, { "referenceVideo_1": "./source.mp4", "startFrameIndex_1": 0, "endFrameIndex_1": 240, "prompt": "Video-to-video edit (V2V): omni-flash restyles the uploaded MP4. No duration here — output matches the trim window (max 10 s). For all parameters see https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos" } ] ``` </details> <details markdown="block"> <summary>Expand `omni-flash.mjs` script</summary> ```javascript /* Script version 1.3, November 11, 2026 Script to batch-generate audio-native videos with Gemini Omni Flash using the Google Flow API by useapi.net Uses the POST /videos endpoint in async mode (model: omni-flash by default, or omni-flash-1.2 per prompt) and polls GET /jobs/{jobId}. For more details visit https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos Installation Instructions: ========================== You need Node.js v21 or newer installed to run this script. Download and install Node.js from: - Windows, macOS, Linux: https://nodejs.org/ After installation, verify by running the following command in a terminal: node -v Running the Script: =================== Usage: node omni-flash.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE] Replace API_TOKEN with your actual useapi.net API token, see https://useapi.net/docs/start-here/setup-useapi Replace EMAIL with configured Google Flow email account, see https://useapi.net/docs/start-here/setup-google-flow If optional PROMPTS_FILE not provided prompts.json will be used. Example: -------- node omni-flash.mjs user:1234-abcdefhijklmnopqrstuv my@email.com This command executes the script using API token user:1234-abcdefhijklmnopqrstuv with my@email.com Google Flow account email. Changelog: ========== - June 15, 2026: Initial release. - September 11, 2026: Adds resolution, startImage / endImage (start and end frames, local files uploaded for you) and character_1..7. Accepts .jpg and upper-case file extensions. Stops with a warning before submitting combinations the API rejects, such as endImage without startImage or referenceAudio_* on its own. A prompt whose local startImage, endImage, referenceImage_* or referenceVideo_1 file fails to upload is skipped and logged to omni-flash_errors.txt instead of being submitted without it. Saves a downloaded video under its final name only once it has been fully received, so a failed download leaves no partial MP4 for the next run to skip as "already exists". - November 11, 2026: referenceImage_8..10 and character_8..10: omni-flash-1.2 takes up to 10 references (omni-flash 7). */ import readline from 'node:readline'; import fs from 'fs/promises'; import path from 'path'; import { writeFile } from 'node:fs/promises'; import { Readable } from 'node:stream'; // Constants const RESULTS_FILE = 'omni-flash_results.txt'; const ERRORS_FILE = 'omni-flash_errors.txt'; const DEFAULT_PROMPTS_FILE = 'prompts.json'; const MODEL = 'omni-flash'; // Reference slots: up to 10 on omni-flash-1.2, 7 on omni-flash, 3 on Veo (referenceImage_* and character_* together). const imageRefKeys = Array.from({ length: 10 }, (_, i) => `referenceImage_${i + 1}`); const characterKeys = Array.from({ length: 10 }, (_, i) => `character_${i + 1}`); const SLEEP_429 = 30 * 1000; // in milliseconds const SLEEP_POLL = 15 * 1000; // in milliseconds const urlAccounts = 'https://api.useapi.net/v1/google-flow/accounts'; const urlVideos = 'https://api.useapi.net/v1/google-flow/videos'; const urlJobs = 'https://api.useapi.net/v1/google-flow/jobs/'; const urlUploadAsset = 'https://api.useapi.net/v1/google-flow/assets/'; // Google Flow accepts png, jpeg and webp images, and mp4 video (for omni-flash V2V edit). const supportedImageExtensions = ['png', 'jpg', 'jpeg', 'webp']; const supportedVideoExtensions = ['mp4']; // { filename: mediaGenerationId } const uploadedFiles = {}; // Utility to sleep for given milliseconds const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); // Function to fetch configured Google Flow API accounts async function fetchAccounts(apiToken) { const response = await fetch(urlAccounts, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.error(`⛔ Error fetching accounts (HTTP ${response.status}): ${response.statusText}`); process.exit(1); } return response.json(); } const elapsedTimeSec = (start) => (Date.now() - start) / 1000; // Map a file extension to the Content-Type required by POST /assets const contentTypeForExt = (ext) => ext === 'png' ? 'image/png' : ext === 'webp' ? 'image/webp' : ext === 'mp4' ? 'video/mp4' : 'image/jpeg'; async function uploadAsset(apiToken, email, filename) { // Check if already uploaded if (uploadedFiles.hasOwnProperty(filename)) return uploadedFiles[filename]; const startTime = Date.now(); console.log(`⬆️ Account ${email} uploading file…`, filename); const body = new Blob([await fs.readFile(filename)]); const fileExt = filename.split('.').pop().toLowerCase(); const response = await fetch(`${urlUploadAsset}${encodeURIComponent(email)}`, { method: 'POST', headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}`, 'Content-Type': contentTypeForExt(fileExt) }, body }); if (response.ok) { const json = await response.json(); // POST /assets returns the reference id nested as mediaGenerationId.mediaGenerationId const mediaGenerationId = json?.mediaGenerationId?.mediaGenerationId; console.log(`🆗 mediaGenerationId (${elapsedTimeSec(startTime)} sec)`, mediaGenerationId); uploadedFiles[filename] = mediaGenerationId; } else { console.error(`❗ Unable to upload file HTTP ${response.status} (${elapsedTimeSec(startTime)} sec)`, await response.text()); // Do not attempt to upload failed file again uploadedFiles[filename] = undefined; } return uploadedFiles[filename]; } async function submit(apiToken, url, body, index, prompt) { const createResponse = await fetch(url, { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiToken}` }, body }); const createBody = await createResponse.text(); // Async POST /videos returns 201 Created with a jobid to poll. if (createResponse.status == 201) { const json = JSON.parse(createBody); // 201 async payload uses lowercase "jobid"; sync 200 uses "jobId". Accept either. const jobId = json.jobid ?? json.jobId; if (jobId) { await fs.appendFile(RESULTS_FILE, `${jobId},#${index}:${prompt}\n`); console.log(`✅ jobId`, jobId); return 201; } else { const error = `No jobid found in HTTP 201 response`; console.log(`❓ ${error}`, createBody); await fs.appendFile(ERRORS_FILE, `${error},#${index}:${prompt}\n`); return 500; } } else { switch (createResponse.status) { case 429: console.log(`🔄️ Retry on HTTP ${createResponse.status}`, createBody); break; case 503: console.log(`🔄️ Service unavailable, retry on HTTP ${createResponse.status}`, createBody); break; case 400: console.log(`🛑 Rejected request (validation or content policy)`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${prompt}\n`); break; case 402: console.log(`🛑 No subscription / insufficient credits`, createBody); break; default: console.log(`❗ FAILED with HTTP ${createResponse.status}`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${prompt}\n`); } return createResponse.status; } } // Submit a single prompt to POST /videos with model omni-flash (or the prompt's own model) in async mode. // startImage = start frame (I2V), endImage = end frame (I2V-FL, requires startImage) — the frames are the only input; // referenceImage_1..10 = R2V image refs; character_1..10 = POST /characters ids (10 on omni-flash-1.2, 7 on omni-flash); // referenceVideo_1 = V2V edit (no duration); referenceAudio_1..5 = system voice name or POST /voices user-voice id; // resolution = 720p (default) or 360p; model = 'omni-flash' (Omni 1.1, the default) or 'omni-flash-1.2' (3–15 s, per-second credits). async function submitVideo(apiToken, email, prompt, index) { const { prompt: text, model = MODEL, aspectRatio, duration, resolution, count, startImage, endImage, referenceVideo_1, startFrameIndex_1, endFrameIndex_1, referenceAudio_1, referenceAudio_2, referenceAudio_3, referenceAudio_4, referenceAudio_5 } = prompt; console.log(`🚀 ${model} » Prompt #${index} • account ${email} …`); // Upload any local image/video files and swap the paths for their mediaGenerationId. const resolveRef = async (ref) => ref && (ref.startsWith('./') || ref.includes('.')) && [...supportedImageExtensions, ...supportedVideoExtensions].includes(ref.split('.').pop().toLowerCase()) ? await uploadAsset(apiToken, email, ref) : ref; const startImageId = await resolveRef(startImage); const endImageId = await resolveRef(endImage); const refImages = {}; for (const key of imageRefKeys) refImages[key] = await resolveRef(prompt[key]); const refVideo_1 = await resolveRef(referenceVideo_1); // A local file that failed to upload would be left out of the body, and the prompt would still be // generated (and charged) without it. Skip the prompt instead. uploadAsset remembers the failed file, // so a later prompt using it is skipped too, without another upload attempt. const failedUploads = [ ['startImage', startImage, startImageId], ['endImage', endImage, endImageId], ...imageRefKeys.map(key => [key, prompt[key], refImages[key]]), ['referenceVideo_1', referenceVideo_1, refVideo_1] ].filter(([, file, id]) => file && !id); for (const [param, file] of failedUploads) { console.error(`🛑 Prompt #${index} skipped: ${param} ${file} failed to upload`); await fs.appendFile(ERRORS_FILE, `Upload failed for ${param} ${file},#${index}:${text}\n`); } if (failedUploads.length) return; // V2V edit does not accept duration — output matches the trim window. const isV2V = !!refVideo_1; const body = JSON.stringify({ model, email, prompt: text, aspectRatio, duration: isV2V ? undefined : duration, resolution, count, startImage: startImageId, endImage: endImageId, ...refImages, ...Object.fromEntries(characterKeys.map(key => [key, prompt[key]])), referenceVideo_1: refVideo_1, startFrameIndex_1, endFrameIndex_1, referenceAudio_1, referenceAudio_2, referenceAudio_3, referenceAudio_4, referenceAudio_5, async: true }); return await submit(apiToken, urlVideos, body, index, text); } // Function to download videos async function download(apiToken) { if (! await fileExists(RESULTS_FILE)) return; try { const resultsContent = await fs.readFile(RESULTS_FILE, 'utf8'); const lines = resultsContent.trim().split('\n'); for (const line of lines) { const [jobId, prompt] = line.split(','); console.log(`👉 ${jobId}`); while (true) { const response = await fetch(`${urlJobs}${jobId}`, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.log(`🛑 Poll failed ${jobId} (HTTP ${response.status}):\n${prompt}\n`, await response.text()); break; } const jobBody = await response.json(); const { status, error, response: jobResponse } = jobBody; if (status == 'failed') { console.error(`🛑 FAILED ${jobId} (${error}):\n${prompt}\n`); break; } if (status == 'completed') { const media = jobResponse?.media ?? []; if (media.length == 0) console.error(`🛑 Completed but no media for ${jobId}:\n${prompt}\n`); // A single prompt with count > 1 returns multiple videos. for (let i = 0; i < media.length; i++) { const url = media[i]?.videoUrl; const videoFilename = `${jobId.replace(/[:*]/g, '_')}_${i + 1}.mp4`; try { await fs.access(videoFilename); console.log(`⚠️ ${videoFilename} already exists. Skipping download.`); continue; } catch { // File does not exist, proceed with downloading } if (url) { console.log(`✅ Downloading ${url} to ${videoFilename}`); // Stream into a temporary file and rename it once the whole video has arrived, so a download // that drops mid-stream leaves no partial file behind for the next run to skip as "already exists". const tempFilename = `${videoFilename}.part`; try { const videoResponse = await fetch(url); if (!videoResponse.ok) { console.error(`⛔ Unable to download ${jobId} (HTTP ${videoResponse.status}):\n${prompt}\n`, url); continue; } const stream = Readable.fromWeb(videoResponse.body); await writeFile(tempFilename, stream); await fs.rename(tempFilename, videoFilename); } catch (err) { await fs.rm(tempFilename, { force: true }); console.error(`⛔ Error during download: ${err}`); } } else console.error(`🛑 No videoUrl for ${jobId} media #${i + 1}:\n${prompt}\n`); } break; } console.log(`⌛ ${jobId} status (${status}) and is still in progress, waiting…`); await sleep(SLEEP_POLL); } } } catch (error) { console.log(`⛔ Error during download:`, error.stack || error); } } // Main function async function main() { const apiToken = process.argv[2]; const email = process.argv[3]; const promptFile = process.argv[4] || DEFAULT_PROMPTS_FILE; if (!apiToken || !email) { console.error('Usage: node omni-flash.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE]'); process.exit(1); } console.info('Script v1.3'); console.info('Node version is: ' + process.version); try { if (await fileExists(RESULTS_FILE)) { let user_input; while (!['y', 'n'].includes(user_input)) { user_input = (await promptUser(`❔ ${RESULTS_FILE} file detected. Do you want to download the results now? (y/n): `))?.toLowerCase(); if (user_input == 'y') { await download(apiToken); await fs.unlink(RESULTS_FILE); } } } const start = new Date(); try { console.info('START EXECUTION', start); await execute(apiToken, email, promptFile); // Pass the promptFile to execute function } finally { console.info('COMPLETED', new Date()); console.info('EXECUTION ELAPSED', diffInMinutesAndSeconds(start, new Date())); } try { console.info('START DOWNLOAD', start); await download(apiToken); } finally { console.info('TOTAL ELAPSED', diffInMinutesAndSeconds(start, new Date())); } } catch (error) { console.error('⛔ Error during execution:', error.stack || error); } } // Modify the execute function to accept promptFile as a parameter async function execute(apiToken, email, promptFile) { const accounts = await fetchAccounts(apiToken); console.info(`Configured Google Flow API accounts (${Object.keys(accounts).length}):`, Object.keys(accounts).join(', ')); if (Object.keys(accounts).length <= 0) { console.error(`⛔ No configured Google Flow accounts found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (!accounts[email]) { console.error(`⛔ Account ${email} not found. Please refer to https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } if (accounts[email].health && accounts[email].health !== 'OK') { console.error(`⛔ Account ${email} health is '${accounts[email].health}'. Please resolve and update the account, see https://useapi.net/docs/start-here/setup-google-flow`); process.exit(1); } const promptData = await fs.readFile(promptFile, 'utf8'); const prompts = JSON.parse(promptData); console.log(`Total number of prompts to process`, prompts.length); let warnings = []; // Parameters accepted by this script for the omni-flash POST /videos endpoint. // See https://useapi.net/docs/api-google-flow-v1/post-google-flow-videos for the full parameter set. const supportedParams = [ 'prompt', 'model', 'aspectRatio', 'duration', 'resolution', 'count', 'startImage', 'endImage', ...imageRefKeys, ...characterKeys, 'referenceVideo_1', 'startFrameIndex_1', 'endFrameIndex_1', 'referenceAudio_1', 'referenceAudio_2', 'referenceAudio_3', 'referenceAudio_4', 'referenceAudio_5' ]; const audioRefKeys = ['referenceAudio_1', 'referenceAudio_2', 'referenceAudio_3', 'referenceAudio_4', 'referenceAudio_5']; const invalidKeys = (prompt) => Object.keys(prompt).filter(key => !key.startsWith('__') && !supportedParams.includes(key)) // Validate a local file path reference (skip already-uploaded mediaGenerationId strings). const looksLikePath = (ref) => ref && (ref.startsWith('./') || (ref.includes('.') && !ref.startsWith('user:'))); for (let i = 1; i <= prompts.length; i++) { const prompt = prompts[i - 1]; const { prompt: text, referenceVideo_1, duration, startImage, endImage } = prompt; const validateFile = async (file, allowedExts) => { if (looksLikePath(file)) { try { await fs.access(file); } catch { warnings.push(`⚠️ File '${file}' does not exist. Prompt ${i}`); } const ext = file.split('.').pop().toLowerCase(); if (!allowedExts.includes(ext)) warnings.push(`⚠️ File ${file} extension ${ext} not supported. Prompt ${i}`); } }; const notSupported = invalidKeys(prompt); if (notSupported.length) warnings.push(`⚠️ Following params not supported: ${notSupported.join(',')}. Prompt ${i}`); if (!text) warnings.push(`⚠️ prompt is required. Prompt ${i}`); // V2V edit (referenceVideo_1) does not accept duration — output matches the trim window. if (referenceVideo_1 && duration) warnings.push(`⚠️ duration is not accepted with referenceVideo_1 (V2V edit). Prompt ${i}`); if (endImage && !startImage) warnings.push(`⚠️ endImage requires startImage (end-frame-only is not supported). Prompt ${i}`); // Start/end frames (I2V, I2V-FL) are the only input in that mode — the API rejects anything alongside them. if (startImage || endImage) { if (referenceVideo_1) warnings.push(`⚠️ startImage/endImage cannot be combined with referenceVideo_1 (V2V edit). Prompt ${i}`); if ([...imageRefKeys, ...characterKeys].some(k => prompt[k])) warnings.push(`⚠️ startImage/endImage cannot be combined with referenceImage_* or character_*. Prompt ${i}`); if (audioRefKeys.some(k => prompt[k])) warnings.push(`⚠️ startImage/endImage cannot be combined with referenceAudio_*. Prompt ${i}`); } // A voice needs a referenceImage_* or character_* to attach to (or a V2V edit) — the API rejects referenceAudio_* on its own. // With start/end frames the check above already applies. if (!startImage && !endImage && !referenceVideo_1 && audioRefKeys.some(k => prompt[k]) && ![...imageRefKeys, ...characterKeys].some(k => prompt[k])) warnings.push(`⚠️ referenceAudio_* requires a referenceImage_* or character_* (or referenceVideo_1 for a V2V edit). Prompt ${i}`); await Promise.all([ validateFile(referenceVideo_1, supportedVideoExtensions), ...['startImage', 'endImage', ...imageRefKeys].map(k => validateFile(prompt[k], supportedImageExtensions)) ]); } if (warnings.length > 0) { warnings.forEach(warning => console.warn(warning)); console.error(`⛔ Execution stopped due to warnings.`); process.exit(1); } for (let i = 0; i < prompts.length; i++) { const prompt = prompts[i]; while (true) { const responseCode = await submitVideo(apiToken, email, prompt, i + 1); if (responseCode == 429 || responseCode == 503) await sleep(SLEEP_429); else if (responseCode == 402) { process.exit(1); } else break; } } } // Utility function to check if a file exists async function fileExists(path) { try { await fs.access(path); return true; } catch { return false; } } // Function to prompt user input async function promptUser(query) { const rl = readline.createInterface({ input: process.stdin, output: process.stdout }); return new Promise((resolve) => rl.question(query, answer => { rl.close(); resolve(answer); })); } function diffInMinutesAndSeconds(date1, date2) { const diffInSeconds = Math.floor((date2 - date1) / 1000); return `${Math.floor(diffInSeconds / 60)} minutes ${diffInSeconds % 60} seconds`; }; main(); ``` </details> ### Examples The videos below are real Gemini Omni Flash results made through this Google Flow API — `model: "omni-flash-1.2"` and `model: "omni-flash"`, extend, voices, references, characters, and V2V editing. ###### Omni 1.2 extend — a 10-second video extended twice to 30 seconds, with two voices <video poster="https://media.useapi.net/articles/2026-06-15-omni-flash-bash/261106-google-flow-omni-1-2-magician-extended-30s-web-poster.jpg" controls width="100%" style="max-width:640px;border-radius:8px"> <source src="https://media.useapi.net/articles/2026-06-15-omni-flash-bash/261106-google-flow-omni-1-2-magician-extended-30s-web.mp4" type="video/mp4"> </video> From [Google Flow: Omni 1.2 Flash, 15-Second Videos, and Extend with Voices](/blog/261106) — `omni-flash-1.2` for the first 10 seconds, then two `POST /videos/extend` calls with `referenceAudio_1`. ###### V2V edit — restyle an uploaded MP4 into a cartoon, same motion and framing <video poster="https://media.useapi.net/blog/2026-05-20-260520/google-flow-edit-video-poster.jpg" controls width="100%" style="max-width:640px;border-radius:8px"> <source src="https://media.useapi.net/blog/2026-05-20-260520/google-flow-edit-video.mp4" type="video/mp4"> </video> From [Google Flow: Gemini Omni Flash](/blog/260520) — `referenceVideo_1` editing. ###### Inline @-mentions — R2V noir video with @character_1, @referenceImage_1, @referenceImage_2 and a custom voice <video poster="https://media.useapi.net/blog/2026-06-09-260609/noir-shot-1-poster.jpg" controls width="100%" style="max-width:640px;border-radius:8px"> <source src="https://media.useapi.net/blog/2026-06-09-260609/noir-shot-1.mp4" type="video/mp4"> </video> From [Google Flow: Inline @-mentions](/blog/260609) — inline `@`-mention markers grounding each reference. ###### Characters + V2V edit — composites two reusable characters into the noir video <video poster="https://media.useapi.net/blog/2026-06-09-260609/edit-1-poster.jpg" controls width="100%" style="max-width:640px;border-radius:8px"> <source src="https://media.useapi.net/blog/2026-06-09-260609/edit-1.mp4" type="video/mp4"> </video> From [Google Flow: Inline @-mentions](/blog/260609) — `referenceVideo_1` V2V edit with inline `@character_*`. See also [Reusable Voices and Characters](/blog/260605) for the voice/character setup pipeline. ### Frequently asked questions - **What is Gemini Omni Flash?** Through useapi.net you run Gemini Omni Flash, Google's [audio-native video model](https://deepmind.google/models/model-cards/gemini-omni-flash/) in [Google Flow](https://flow.google.com), by setting `model: "omni-flash-1.2"` (Omni 1.2 Flash) or `model: "omni-flash"` (Omni 1.1 Flash) on the [Google Flow API](/docs/api-google-flow-v1). Unlike a silent video model, it makes the soundtrack, narration, dialog and ambience, as part of the same video, and it accepts image, video and audio references plus reusable characters. - **How is Omni Flash different from Veo 3.1?** Through useapi.net both run on the same Google Flow API, picked with the `model` field. Veo is the higher-fidelity plain text-to-video and image-to-video engine, while Omni Flash is audio-native and reference-rich, with video-to-video editing (`referenceVideo_1`), several voices per video, reusable characters at any length, and longer videos than Veo. See [Reference modes](#reference-modes) for the exact limits. - **Can it use my own voice, a reference video, or a reference audio?** Through useapi.net, yes. Narrate with the built-in system voices or with custom voices from [POST /voices](/docs/api-google-flow-v1/post-google-flow-voices), passed as `referenceAudio_1..5`, and upload an MP4 with [POST /assets](/docs/api-google-flow-v1/post-google-flow-assets-email) to edit it as `referenceVideo_1` (V2V). See [Reference modes](#reference-modes) and [Voices & characters](#voices--characters) for the limits of each mode. - **Is there an official Omni Flash API?** Through useapi.net, Omni 1.1 Flash costs far less than on Google's own API: an 8-second 720p video costs $0.10 on Google AI Ultra $199.99, against $0.81 on the official [Gemini API](https://ai.google.dev/gemini-api/docs/pricing), which has sold the model per second since June 30, 2026 (as of November 2026). It runs through a standard REST endpoint on your Google Flow website subscription. - **Can Omni Flash make videos longer than 10 seconds?** Through useapi.net, yes: Omni 1.2 Flash (`model: "omni-flash-1.2"`) makes up to 15 seconds in one call, and [POST /videos/extend](/docs/api-google-flow-v1/post-google-flow-videos-extend) adds up to 10 seconds at a time with voices, at $0.19 for an 8-second 720p video on Google AI Ultra $199.99 against $0.56 on [Google's own API](https://cloud.google.com/blog/products/ai-machine-learning/gemini-omni-1-2-flash-generally-available) (as of November 2026). Every length limit and price in Google Flow and Google Vids: [How to Use the Gemini Omni 1.2 Flash API](/docs/articles/gemini-omni-1-2-flash-api). - **Do I need to solve a captcha?** Through useapi.net you never solve one yourself. Google Flow asks for a reCAPTCHA on every video and every new voice, and the useapi.net worker solves it automatically: your first Google Flow account comes with 300 free solves on our own AntiCaptcha, CapSolver and EzCaptcha keys, and after that you add your own provider keys with [POST /accounts/captcha-providers](/docs/api-google-flow-v1/post-google-flow-accounts-captcha-providers). [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters) needs no captcha. ### Conclusion Visit our <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> or <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> for any support questions and concerns. Check our [GitHub repo](https://github.com/useapi/google-flow-api) with code examples. An AI assistant can also work with Google Flow for you: the hosted [Google Flow MCP server](/docs/api-google-flow-v1/mcp) lets Claude Code, Cursor and VS Code chat with Google Flow Agent, which generates images and videos on your account. === URL: https://useapi.net/docs/articles/pixverse-demo === Document URL: https://useapi.net/docs/articles/pixverse-demo --- layout: default title: How to Generate AI Video with PixVerse V6 via the PixVerse API description: "Generate PixVerse V6 video — integrated audio, multi-shot, 900+ effects — through the useapi.net PixVerse API, with copy-paste curl and a runnable batch script." keywords: [PixVerse API, PixVerse V6, AI video generation, text to video, image to video, video effects, tutorial, code] parent: Articles nav_exclude: true date: 2024-06-08 last_modified: 2026-11-20 nav_order: 300 repo: https://github.com/useapi/pixverse-api --- ## How to Generate AI Video with PixVerse V6 via the PixVerse API 6 min read • June 8, 2024 (November 20, 2026) ## Table of contents ### Introduction Yes — you can generate [PixVerse V6](https://pixverse.ai) video through a REST API. [useapi.net](/docs/subscription) provides a [PixVerse API](/docs/api-pixverse-v2) for [PixVerse.ai](https://pixverse.ai) that drives your own PixVerse account: you send a text or image prompt to one `POST` endpoint, poll a `GET` endpoint for the result, and get back an MP4. The default model is the native PixVerse V6 — up to 15-second 1080p clips with integrated audio and multi-shot storytelling — and the same `videos/create` endpoint also exposes the rest of the native family (`v5.6`, `v5.5`, `v5`, `v5-fast`, `pixverse-c1`) plus third-party models such as Seedance 2.5 (also Flash and Draft) and the Seedance 2.0 family, Kling 4.0, O3 and V3, Veo 3.1, Grok Imagine, HappyHorse, MiniMax H3, and Gemini Omni Flash — all selectable with a single `model` field. This guide shows the two-call video workflow with copy-paste `curl`, then a runnable Node.js script that batch-generates from a list of prompts. ### Generate a video in two API calls You need a useapi.net [API token](/docs/start-here/setup-useapi) and a connected [PixVerse account](/docs/start-here/setup-pixverse). Generation is asynchronous: the create call returns a `video_id` immediately, then you poll until the video is ready. #### 1. Submit the job `POST https://api.useapi.net/v2/pixverse/videos/create`: ```bash curl -X POST "https://api.useapi.net/v2/pixverse/videos/create" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model": "v6", "prompt": "A red panda eating bamboo in a misty forest, camera slowly pushing in", "quality": "720p", "duration": 5, "aspect_ratio": "16:9" }' ``` The response returns immediately with a `video_id`: ```json { "video_id": "user:1234-pixverse:jo***@gmail.com-video:112233445566" } ``` #### 2. Poll for the result `GET https://api.useapi.net/v2/pixverse/videos/{video_id}`: ```bash curl "https://api.useapi.net/v2/pixverse/videos/VIDEO_ID" \ -H "Authorization: Bearer $USEAPI_TOKEN" ``` While the video is still processing this endpoint returns `404`. Once it is done it returns `200` with `video_status_name: "COMPLETED"` and `video_status_final: true`. The finished MP4 is in the `url` field: ```json { "video_id": "user:1234-pixverse:jo***@gmail.com-video:112233445566", "model": "v6", "prompt": "A red panda eating bamboo in a misty forest, camera slowly pushing in", "quality": "720p", "duration": 5, "url": "https://media.pixverse.ai/....mp4", "video_status_name": "COMPLETED", "video_status_final": true } ``` Prefer not to poll? Pass a `replyUrl` in the create body to receive a webhook callback (same JSON shape) when the video completes or fails. ### Supported models Pick a model per request with the `model` field (default `v6`). Native PixVerse models support integrated audio, the off-peak discount, preview mode, and `seed`; see [Model Capabilities](/docs/api-pixverse-v2/model-capabilities) for the full per-model quality / duration / aspect-ratio matrix. | Model id | Highlights | Qualities | Durations | |----------|-----------|-----------|-----------| | `v6` *(default)* | Multi-shot, integrated audio, longest clips | 360p, 540p, 720p, 1080p | 1–15s | | `v5.6` | Integrated audio | 360p, 540p, 720p, 1080p | 1–10s (1080p ≤ 8s) | | `v5.5` | Integrated audio | 360p, 540p, 720p, 1080p | 1–10s (1080p ≤ 8s) | | `v5` | Lip-sync TTS + sound-effect prompts | 360p, 540p, 720p, 1080p | 1–10s (1080p ≤ 8s) | | `v5-fast` | Fastest native model | 360p, 540p, 720p, 1080p | 1–10s (1080p ≤ 8s) | | `pixverse-c1` | Wide aspect-ratio support, 15s | 360p, 540p, 720p, 1080p | 1–15s | Beyond the native family, the same `videos/create` endpoint accepts 20 third-party models via the `model` field: `seedance-2.5` / `seedance-2.5-flash` / `seedance-2.5-draft` / `seedance-2.0` / `seedance-2.0-fast` / `seedance-2.0-mini` (ByteDance), `kling-4.0` / `kling-o3` / `kling-v3` (Kuaishou), `veo-3.1-lite` / `veo-3.1-standard` / `veo-3.1-fast` and `gemini-omni-flash` (Google), `grok-imagine` / `grok-imagine-1.5` (xAI), `happyhorse-1.0` and `wan-3.0` (Alibaba), `minimax-h3` / `minimax-h3-max` (MiniMax), and `flux-3.0` (Black Forest Labs). A `seedance-2.5-draft` video is a 480p preview that [POST videos/create-final](/docs/api-pixverse-v2/post-pixverse-videos-create-final) renders again in 1080p or 4K. Each has its own quality, duration, and feature constraints — see [Model Capabilities](/docs/api-pixverse-v2/model-capabilities). Sora 2 is no longer available: OpenAI shut it down on September 24, 2026. ### Audio, multi-shot & effects #### Integrated audio Set `audio: true` to generate voice, dialogue, and background sound in a single step. It is a toggle on `v6`, `v5.6`, `v5.5`, `pixverse-c1`, the Seedance 2.0 family, `kling-o3`, `kling-v3`, `wan-3.0` and `flux-3.0`. On `veo-3.1-standard`, `veo-3.1-fast`, and `happyhorse-1.0` audio is always on. The Seedance 2.5 models, `kling-4.0`, `minimax-h3`, `minimax-h3-max` and `gemini-omni-flash` generate audio natively and reject the parameter. (Legacy `v5` instead uses `lip_sync_tts_prompt` and `sound_effect_prompt`.) #### Multi-shot storytelling On `v6` only, set `multi_shot: true` to have the model generate multiple camera angles and scene cuts within one clip instead of a single continuous shot. #### 900+ effect templates List the catalog with [GET videos/effects](/docs/api-pixverse-v2/get-pixverse-videos-effects), then pass the chosen `template_id` to `videos/create` along with the required input image(s). When `template_id` is set, the template controls `model`, `duration`, and `quality` — you only supply the frame path(s). For more workflows on native PixVerse models, the API also offers [image-to-video](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) (upload a frame via [POST files](/docs/api-pixverse-v2/post-pixverse-files), pass it as `first_frame_path`), [extend](/docs/api-pixverse-v2/post-pixverse-videos-extend-v4), [upscale](/docs/api-pixverse-v2/post-pixverse-videos-upscale), [lip-sync](/docs/api-pixverse-v2/post-pixverse-videos-lipsync), [modify](/docs/api-pixverse-v2/post-pixverse-videos-modify), and [motion-control](/docs/api-pixverse-v2/post-pixverse-videos-motion-control). ### Pricing You keep your own [PixVerse subscription](https://app.pixverse.ai/subscribe) (Pro, Premium, or Ultra) and add a single flat [$15/month](/docs/subscription) to useapi.net that covers API access to every supported service — there are no per-call API surcharges. Each generation spends credits from your PixVerse plan. For native PixVerse models you can cut that cost with `off_peak_mode: true` (results usually delivered within 24 hours): Pro 30% off, Premium 50% off, Ultra unlimited free. `preview_mode: true` is another native-only option — a fast, lower-quality preview at 20% off that you can later [upscale](/docs/api-pixverse-v2/post-pixverse-videos-upscale). Third-party models don't support off-peak or preview mode. Ultra gets a discount on them instead, applied per model rather than as one flat rate, from 20% off up to free (MiniMax H3 and Wan 3.0), and Premium and Pro get a few of their own. They apply unless the request sends `relax_mode: false`. These are promotions and PixVerse ends them without notice, so check the [calculator](/docs/api-pixverse-v2) rather than relying on these figures. Pro+ plans additionally include unlimited image generation in Relax Mode for select models (Ultra covers all of them). Relax Mode costs no credits but is throttled to a slow queue past a daily volume threshold that applies per model, so an account throttled on one model stays fast on the others. For an interactive per-model, per-plan cost calculator, see the [PixVerse API overview](/docs/api-pixverse-v2). ### Batch-generate with a script Finding the right shot takes many attempts, and running them by hand is tedious. The Node.js script below reads a list of prompts from `prompts.json`, uploads any input frame images, submits each `videos/create` job, then polls and downloads every finished MP4 — so you can queue a batch and come back to the winners. You need [Node.js](https://nodejs.org) v21 or newer. Put `prompts.json` and `pixverse.mjs` in the same folder and run `node ./pixverse.mjs API_TOKEN EMAIL`, where `API_TOKEN` is your useapi.net [API token](/docs/start-here/setup-useapi) and `EMAIL` is your connected [PixVerse account](/docs/start-here/setup-pixverse) email. The script looks the account up by email automatically. <details markdown="block"> <summary>Expand `prompts.json`</summary> ```json [ { "prompt": "By default the v6 model with a 5-second 720p 16:9 clip will be used." }, { "model": "v6", "duration": 15, "quality": "1080p", "aspect_ratio": "16:9", "audio": true, "multi_shot": true, "prompt": "PixVerse V6 with integrated audio and multi-shot storytelling. A dramatic courtroom scene with multiple camera angles. For all parameters see https://useapi.net/docs/api-pixverse-v2/post-pixverse-videos-create-v4" }, { "model": "v5.6", "duration": 8, "quality": "1080p", "first_frame_path": "./first_frame.webp", "audio": true, "prompt": "Image-to-video: the local image is uploaded via POST files and passed as first_frame_path. Note: aspect_ratio is derived from the image and must NOT be set for i2v." }, { "model": "seedance-2.0", "duration": 5, "quality": "720p", "aspect_ratio": "16:9", "prompt": "Third-party models (seedance-2.5, seedance-2.0, kling-o3, veo-3.1-fast, grok-imagine, happyhorse-1.0, minimax-h3, gemini-omni-flash, …) are selectable via the model field. They reject native-only flags such as off_peak_mode, preview_mode, multi_shot and seed." } ] ``` </details> <details markdown="block"> <summary>Expand `pixverse.mjs` script</summary> ```javascript /* Script version 1.0, June 15, 2026 Script to batch-generate videos using prompts with the PixVerse API v2 by useapi.net 🚀 Uses the POST /videos/create endpoint (default model: v6) and polls GET /videos/{video_id}. For more details visit https://useapi.net/docs/api-pixverse-v2/post-pixverse-videos-create-v4 Installation Instructions: ========================== You need Node.js v21 or newer installed to run this script. Download and install Node.js from: - Windows, macOS, Linux: https://nodejs.org/ After installation, verify by running the following command in a terminal: node -v Running the Script: =================== Usage: node pixverse.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE] Replace API_TOKEN with your actual useapi.net API token, see https://useapi.net/docs/start-here/setup-useapi Replace EMAIL with configured PixVerse email account, see https://useapi.net/docs/start-here/setup-pixverse If optional PROMPTS_FILE not provided prompts.json will be used. Example: -------- node pixverse.mjs user:1234-abcdefhijklmnopqrstuv my@email.com This command executes the script using API token user:1234-abcdefhijklmnopqrstuv with my@email.com PixVerse account email. Changelog: ========== - June 15, 2026: Initial release. */ import readline from 'node:readline'; import fs from 'fs/promises'; import { writeFile } from 'node:fs/promises'; import { Readable } from 'node:stream'; // Constants const RESULTS_FILE = 'pixverse_results.txt'; const ERRORS_FILE = 'pixverse_errors.txt'; const DEFAULT_PROMPTS_FILE = 'prompts.json'; const DEFAULT_MODEL = 'v6'; const SLEEP_429 = 30 * 1000; // in milliseconds const SLEEP_POLL = 15 * 1000; // in milliseconds const urlAccounts = 'https://api.useapi.net/v2/pixverse/accounts'; const urlCreate = 'https://api.useapi.net/v2/pixverse/videos/create'; const urlVideo = 'https://api.useapi.net/v2/pixverse/videos/'; // + video_id (poll) const urlFiles = 'https://api.useapi.net/v2/pixverse/files/'; // + ?email= (upload) // PixVerse accepts these image extensions for uploaded frames. const supportedFileExtensions = ['png', 'jpeg', 'jpg', 'gif', 'webp']; // { filename: path } const uploadedFiles = {}; // Utility to sleep for given milliseconds const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); // Function to fetch configured PixVerse API accounts async function fetchAccounts(apiToken) { const response = await fetch(urlAccounts, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.error(`⛔ Error fetching accounts (HTTP ${response.status}): ${response.statusText}`); process.exit(1); } return response.json(); } const elapsedTimeSec = (start) => (Date.now() - start) / 1000; // Map a file extension to the Content-Type required by POST /files const contentTypeForExt = (ext) => ext === 'png' ? 'image/png' : ext === 'gif' ? 'image/gif' : ext === 'webp' ? 'image/webp' : 'image/jpeg'; // Upload a local image and return its PixVerse `path` (used as first_frame_path etc.) async function uploadFile(apiToken, email, filename) { // Check if already uploaded if (uploadedFiles.hasOwnProperty(filename)) return uploadedFiles[filename]; const startTime = Date.now(); console.log(`⬆️ Account ${email} uploading file…`, filename); const body = new Blob([await fs.readFile(filename)]); const fileExt = filename.split('.').pop().toLowerCase(); const response = await fetch(`${urlFiles}?email=${encodeURIComponent(email)}`, { method: 'POST', headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}`, 'Content-Type': contentTypeForExt(fileExt) }, body }); if (response.ok) { const json = await response.json(); // Image uploads return result[0].path; use that as the frame path. const path = json?.result?.[0]?.path ?? json?.path; console.log(`🆗 path (${elapsedTimeSec(startTime)} sec)`, path); uploadedFiles[filename] = path; } else { console.error(`❗ Unable to upload file HTTP ${response.status} (${elapsedTimeSec(startTime)} sec)`, await response.text()); // Do not attempt to upload failed file again uploadedFiles[filename] = undefined; } return uploadedFiles[filename]; } async function submit(apiToken, url, body, index, prompt) { const createResponse = await fetch(url, { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiToken}` }, body }); const createBody = await createResponse.text(); // POST /videos/create returns 200 with a video_id to poll. if (createResponse.status == 200) { const json = JSON.parse(createBody); const videoId = json.video_id ?? json.image_id; if (videoId) { await fs.appendFile(RESULTS_FILE, `${videoId},#${index}:${prompt}\n`); console.log(`✅ video_id`, videoId); return 200; } else { const error = `No video_id found in HTTP 200 response`; console.log(`❓ ${error}`, createBody); await fs.appendFile(ERRORS_FILE, `${error},#${index}:${prompt}\n`); return 500; } } else { switch (createResponse.status) { case 429: console.log(`🔄️ Account busy / concurrent limit, retry on HTTP ${createResponse.status}`, createBody); break; case 400: console.log(`🛑 Rejected request (validation)`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${prompt}\n`); break; case 412: console.log(`🛑 Insufficient credits`, createBody); break; case 422: console.log(`🛑 Moderated prompt`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${prompt}\n`); break; default: console.log(`❗ FAILED with HTTP ${createResponse.status}`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${prompt}\n`); } return createResponse.status; } } // Submit a single prompt to POST /videos/create. // first_frame_path (uploaded image) switches to image-to-video; aspect_ratio is then derived from the image. async function submitVideo(apiToken, email, prompt, index) { const { model, prompt: text, first_frame_path, duration, quality, aspect_ratio, audio, multi_shot, preview_mode, off_peak_mode, seed, template_id } = prompt; const useModel = model ?? DEFAULT_MODEL; console.log(`🚀 ${useModel} » Prompt #${index} • account ${email} …`); const framePath = first_frame_path ? await uploadFile(apiToken, email, first_frame_path) : undefined; const body = JSON.stringify({ model: useModel, email, prompt: text, first_frame_path: framePath, duration, quality, // aspect_ratio applies only to text-to-video and is optional (the server defaults to 16:9 when omitted); for image-to-video it is derived from the image aspect_ratio: framePath ? undefined : aspect_ratio, audio, multi_shot, preview_mode, off_peak_mode, seed, template_id }); return await submit(apiToken, urlCreate, body, index, text); } // Function to poll and download videos async function download(apiToken) { if (! await fileExists(RESULTS_FILE)) return; try { const resultsContent = await fs.readFile(RESULTS_FILE, 'utf8'); const lines = resultsContent.trim().split('\n'); for (const line of lines) { const [videoId, prompt] = line.split(','); console.log(`👉 ${videoId}`); while (true) { const response = await fetch(`${urlVideo}${videoId}`, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); // 404 means the video is still processing — keep waiting. if (response.status == 404) { console.log(`⌛ ${videoId} still processing, waiting…`); await sleep(SLEEP_POLL); continue; } if (!response.ok) { console.log(`🛑 Poll failed ${videoId} (HTTP ${response.status}):\n${prompt}\n`, await response.text()); break; } const job = await response.json(); const { url, video_status_name, video_status_final, error } = job; if (error) { console.error(`🛑 FAILED ${videoId} (${error}):\n${prompt}\n`); break; } // Poll until the status is final (COMPLETED, MODERATED, etc.). if (!video_status_final) { console.log(`⌛ ${videoId} status (${video_status_name}) and is still in progress, waiting…`); await sleep(SLEEP_POLL); continue; } if (video_status_name !== 'COMPLETED' || !url) { console.error(`🛑 ${videoId} finished as ${video_status_name} with no url:\n${prompt}\n`); break; } const videoFilename = `${videoId.replace(/[:*]/g, '_')}.mp4`; try { await fs.access(videoFilename); console.log(`⚠️ ${videoFilename} already exists. Skipping download.`); break; } catch { // File does not exist, proceed with downloading } console.log(`✅ Downloading ${url} to ${videoFilename}`); try { const videoResponse = await fetch(url); if (!videoResponse.ok) { console.error(`⛔ Unable to download ${videoId} (HTTP ${videoResponse.status}):\n${prompt}\n`, url); break; } const stream = Readable.fromWeb(videoResponse.body); await writeFile(videoFilename, stream); } catch (err) { console.error(`⛔ Error during download: ${err}`); } break; } } } catch (error) { console.log(`⛔ Error during download:`, error.stack || error); } } // Main function async function main() { const apiToken = process.argv[2]; const email = process.argv[3]; const promptFile = process.argv[4] || DEFAULT_PROMPTS_FILE; if (!apiToken || !email) { console.error('Usage: node pixverse.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE]'); process.exit(1); } console.info('Script v1.0'); console.info('Node version is: ' + process.version); try { if (await fileExists(RESULTS_FILE)) { let user_input; while (!['y', 'n'].includes(user_input)) { user_input = (await promptUser(`❔ ${RESULTS_FILE} file detected. Do you want to download the results now? (y/n): `))?.toLowerCase(); if (user_input == 'y') { await download(apiToken); await fs.unlink(RESULTS_FILE); } } } const start = new Date(); try { console.info('START EXECUTION', start); await execute(apiToken, email, promptFile); // Pass the promptFile to execute function } finally { console.info('COMPLETED', new Date()); console.info('EXECUTION ELAPSED', diffInMinutesAndSeconds(start, new Date())); } try { console.info('START DOWNLOAD', start); await download(apiToken); } finally { console.info('TOTAL ELAPSED', diffInMinutesAndSeconds(start, new Date())); } } catch (error) { console.error('⛔ Error during execution:', error.stack || error); } } // Modify the execute function to accept promptFile as a parameter async function execute(apiToken, email, promptFile) { const accounts = await fetchAccounts(apiToken); console.info(`Configured PixVerse API accounts (${Object.keys(accounts).length}):`, Object.keys(accounts).join(', ')); if (Object.keys(accounts).length <= 0) { console.error(`⛔ No configured PixVerse accounts found. Please refer to https://useapi.net/docs/start-here/setup-pixverse`); process.exit(1); } if (!accounts[email]) { console.error(`⛔ Account ${email} not found. Please refer to https://useapi.net/docs/start-here/setup-pixverse`); process.exit(1); } const promptData = await fs.readFile(promptFile, 'utf8'); const prompts = JSON.parse(promptData); console.log(`Total number of prompts to process`, prompts.length); let warnings = []; // Parameters accepted by this script for the POST /videos/create endpoint. // See https://useapi.net/docs/api-pixverse-v2/post-pixverse-videos-create-v4 for the full parameter set. const supportedParams = ['model', 'prompt', 'first_frame_path', 'duration', 'quality', 'aspect_ratio', 'audio', 'multi_shot', 'preview_mode', 'off_peak_mode', 'seed', 'template_id']; const invalidKeys = (prompt) => Object.keys(prompt).filter(key => !key.startsWith('__') && !supportedParams.includes(key)) for (let i = 1; i <= prompts.length; i++) { const prompt = prompts[i - 1]; const { prompt: text, first_frame_path, template_id } = prompt; if (first_frame_path) { try { await fs.access(first_frame_path); } catch { warnings.push(`⚠️ Image '${first_frame_path}' does not exist. Prompt ${i}`); } const ext = first_frame_path.split('.').pop().toLowerCase(); if (!supportedFileExtensions.includes(ext)) warnings.push(`⚠️ Image ${first_frame_path} extension ${ext} not supported. Prompt ${i}`); } const notSupported = invalidKeys(prompt); if (notSupported.length) warnings.push(`⚠️ Following params not supported: ${notSupported.join(',')}. Prompt ${i}`); // prompt is optional only when a template_id supplies the generation. if (!text && !template_id) warnings.push(`⚠️ prompt is required (unless template_id is set). Prompt ${i}`); } if (warnings.length > 0) { warnings.forEach(warning => console.warn(warning)); console.error(`⛔ Execution stopped due to warnings.`); process.exit(1); } for (let i = 0; i < prompts.length; i++) { const prompt = prompts[i]; while (true) { const responseCode = await submitVideo(apiToken, email, prompt, i + 1); if (responseCode == 429) await sleep(SLEEP_429); else if (responseCode == 412) { process.exit(1); } else break; } } } // Utility function to check if a file exists async function fileExists(path) { try { await fs.access(path); return true; } catch { return false; } } // Function to prompt user input async function promptUser(query) { const rl = readline.createInterface({ input: process.stdin, output: process.stdout }); return new Promise((resolve) => rl.question(query, answer => { rl.close(); resolve(answer); })); } function diffInMinutesAndSeconds(date1, date2) { const diffInSeconds = Math.floor((date2 - date1) / 1000); return `${Math.floor(diffInSeconds / 60)} minutes ${diffInSeconds % 60} seconds`; }; main(); ``` </details> ### Examples Real PixVerse clips generated through this PixVerse API, taken straight from our release notes. ###### v6 » Dramatic courtroom scene (text-to-video, 15s 1080p, multi-shot + audio) From [PixVerse v6: Multi-Shot Storytelling and Audio](/blog/260405). Generated with `multi_shot: true` and `audio: true` — multiple camera angles and synchronized dialogue in a single 15-second clip. <video poster="https://media.useapi.net/articles/2024-06-08-pixverse-demo/t2v-v6-15s-1080p-16x9-audio-mshot-poster.jpg" src="https://media.useapi.net/articles/2024-06-08-pixverse-demo/t2v-v6-15s-1080p-16x9-audio-mshot.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> ###### v5.6 » Playing guitar and singing (image-to-video, integrated audio) From [PixVerse v5.6: Integrated Audio Generation](/blog/260127). Animated from a still passed as `first_frame_path` with `audio: true`. <video poster="https://media.useapi.net/articles/2024-06-08-pixverse-demo/pixverse-v56-frame-poster.jpg" src="https://media.useapi.net/articles/2024-06-08-pixverse-demo/pixverse-v56-frame.mp4" style="width: 100%; max-width: 400px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> ###### v5.6 » Motion Control (retarget motion onto a character image) From [PixVerse: Motion Control](/blog/260513). A still character image (`frame_1_path`) is driven by motion extracted from a reference video (`video_1_path`) via [POST videos/motion-control](/docs/api-pixverse-v2/post-pixverse-videos-motion-control). <video poster="https://media.useapi.net/articles/2024-06-08-pixverse-demo/pixverse-motioncontrol-v56-poster.jpg" controls width="100%" style="max-width:480px"> <source src="https://media.useapi.net/articles/2024-06-08-pixverse-demo/pixverse-motioncontrol-v56.mp4" type="video/mp4"> </video> Related tutorials: [Seedance 2.0 and 2.5 API pricing compared](/docs/articles/seedance-2-api-pricing), [Sora 2 API alternatives](/docs/articles/sora-2-api-alternatives) and [Kling v3 video via the Kling API](/docs/articles/kling-bash). ### Use it from Claude, ChatGPT or Cursor The hosted [PixVerse MCP server](/docs/api-pixverse-v2/mcp) gives Claude Code, Cursor, VS Code and other MCP clients this PixVerse API as 38 tools, with nothing to install, and the Claude app and ChatGPT connect to it with a sign-in. It runs on your own PixVerse accounts with your useapi.net API token. In Claude Code: ```bash claude mcp add --transport http useapi-pixverse https://api.useapi.net/v2/pixverse/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` Then ask in plain words, for example "Make a 5-second PixVerse V6 video at 1080p with sound of a paper boat drifting down a rainy street at night". The assistant calls `pixverse_create_video`, which takes the same models, `audio`, `multi_shot` and effect templates as [POST videos/create](/docs/api-pixverse-v2/post-pixverse-videos-create-v4), and `pixverse_motion_control` animates a character image like the example above. The server is listed in the official MCP Registry as `net.useapi/pixverse`, and the [`pixverse-api`](https://github.com/useapi/pixverse-api#use-with-claude-code) repo also installs as a Claude Code plugin or a [Gemini CLI extension](https://github.com/useapi/pixverse-api#use-with-gemini-cli). ### Frequently asked questions #### Is there a PixVerse API? Yes, and useapi.net's [PixVerse API](/docs/api-pixverse-v2) drives your own consumer PixVerse account through a standard REST endpoint, on the [web subscription](https://app.pixverse.ai/subscribe) credits you already pay for: PixVerse V6 at 1080p costs about $0.064 a second on Premium, or $0.032 in Off-Peak mode, against $0.080 on PixVerse's own [developer API](https://docs.platform.pixverse.ai/pixverse-api-pricing-2394995m0) (as of October 2026). The same single endpoint also exposes third-party models (Seedance, Kling, Veo 3.1, Grok, HappyHorse, MiniMax H3, Gemini Omni Flash) that PixVerse's developer price list doesn't include. PixVerse.ai's [official platform API](https://platform.pixverse.ai) is billed against a separate API subscription. #### What models can I use? The default is native PixVerse V6. The same `videos/create` endpoint also accepts `v5.6`, `v5.5`, `v5`, `v5-fast`, and `pixverse-c1`, plus 20 third-party models: `seedance-2.5` / `seedance-2.5-flash` / `seedance-2.5-draft` / `seedance-2.0` / `seedance-2.0-fast` / `seedance-2.0-mini`, `kling-4.0` / `kling-o3` / `kling-v3`, `veo-3.1-lite` / `veo-3.1-standard` / `veo-3.1-fast`, `gemini-omni-flash`, `grok-imagine` / `grok-imagine-1.5`, `happyhorse-1.0`, `minimax-h3` / `minimax-h3-max`, `wan-3.0` and `flux-3.0`. See [Supported models](#supported-models) and [Model Capabilities](/docs/api-pixverse-v2/model-capabilities). #### Can I generate audio and multi-shot video? Yes. Set `audio: true` for integrated voice, dialogue, and background sound (a toggle on `v6`, `v5.6`, `v5.5`, `pixverse-c1`, the Seedance 2.0 family, and Kling — always on and not settable for `seedance-2.5`, `minimax-h3`, `minimax-h3-max`, `gemini-omni-flash`, `veo-3.1-standard`, `veo-3.1-fast` and `happyhorse-1.0`). Multi-shot storytelling is `v6`-only via `multi_shot: true`. See [Audio, multi-shot & effects](#audio-multi-shot--effects). #### Can I do image-to-video? Yes. Upload your starting frame with [POST files](/docs/api-pixverse-v2/post-pixverse-files), then pass the returned `path` as `first_frame_path` on `videos/create`. For image-to-video, `aspect_ratio` is derived from the image and must not be set. #### How much does it cost? Through useapi.net, on your own PixVerse subscription, PixVerse V6 at 1080p uses 16 credits a second, about $0.064 on Premium ($60/month for 15,000 credits), against $0.080 on the official API (as of October 2026). Each generation spends PixVerse credits from your plan — and native models can run far cheaper with `off_peak_mode` (Pro 30% off, Premium 50% off, Ultra free) or `preview_mode` (20% off). See [Pricing](#pricing) and the [interactive calculator](/docs/api-pixverse-v2). #### Do I need PixVerse credits, or are they included? Credits come from your own PixVerse plan — useapi.net does not resell them. The $15/month is purely for API access. A `412` response from `videos/create` means your PixVerse credits are exhausted. ### Conclusion Visit our <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> or <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> for any support questions and concerns. Check our [GitHub repo](https://github.com/useapi/examples) with code examples. === URL: https://useapi.net/docs/articles/pixverse-music-video-api === Document URL: https://useapi.net/docs/articles/pixverse-music-video-api --- layout: default title: How to Make an AI Music Video from a Song with the PixVerse API description: "Make a lip-synced AI music video from a song with the useapi.net PixVerse API (One-Click MV): full code, a free full-song 1080p example, then $2.40 a minute of song on Premium." keywords: [AI music video API, PixVerse music video API, One-Click MV API, song to music video AI, lip sync music video generator, PixVerse API, music video API, Flow Music, Lyria 3.5, Nano Banana 2.1, tutorial] image: https://media.useapi.net/pixverse/2026-11-10-music-video-article/nano-banana-2-1-character-oakland-coliseum-dancer.jpg parent: Articles nav_exclude: true date: 2026-11-10 last_modified: 2026-11-20 nav_order: 301 repo: https://github.com/useapi/pixverse-api --- ## How to Make an AI Music Video from a Song with the PixVerse API 7 min read • November 10, 2026 (November 20, 2026) ## Table of contents ### Introduction The useapi.net [PixVerse API](/docs/api-pixverse-v2) turns a song and one character photo into a finished, lip-synced AI music video with a single REST call, [POST music-video/create](/docs/api-pixverse-v2/post-pixverse-music-video-create), using [PixVerse](https://pixverse.ai)'s One-Click MV engine on the PixVerse subscription you already pay for. The first music video on every PixVerse account is free, at any length and in 1080p, even on a free Basic plan, which otherwise makes video only up to 540p. After that a minute of song costs $2.40 on Premium at 720p, against $4.00 on PixVerse's own developer API (as of November 2026). To show what it does, we made a whole music video from scratch, all through useapi.net: an original song with the [Flow Music API](/docs/api-flowmusic-v1), a dancer with [Nano Banana 2.1](/docs/api-google-flow-v1/post-google-flow-images) on the [Google Flow API](/docs/api-google-flow-v1), then the full 2½-minute video at 1080p. This page has every prompt, every request, the timings, the prices and the results. useapi.net is a [third-party](/docs/legal#affiliation--third-party-services) API, not affiliated with PixVerse or Google. ### Pricing One minute of song costs (PixVerse bills every second, rounded to the nearest second): | Mode and quality | [Official API](https://docs.platform.pixverse.ai/one-click-vibemv-44144151e0) | Ultra $199/mo (30,000 cr/mo) | Premium $60/mo (15,000 cr/mo) | Pro $30/mo (6,000 cr/mo) | |---|---|---|---|---| | `performance` or `expressive`, 720p | $4.00 (15 cr/s) | $3.98 (10 cr/s) | $2.40 (10 cr/s) | $3.00 (10 cr/s) | | `performance` or `expressive`, 1080p | $6.00 (22.5 cr/s) | $5.97 (15 cr/s) | $3.60 (15 cr/s) | $4.50 (15 cr/s) | | `storytelling`, 720p | not sold | $7.96 (20 cr/s) | $4.80 (20 cr/s) | $6.00 (20 cr/s) | | `storytelling`, 1080p | not sold | $15.92 (40 cr/s) | $9.60 (40 cr/s) | $12.00 (40 cr/s) | The first music video on every PixVerse account is free, at any length and in 1080p, even on a free Basic plan. Prices as of November 2026. - Our 2½-minute 1080p video below was the free one of a Basic account. On Premium it would have cost $9.12. - PixVerse's developer API has one music video workflow and no `expressive` or `storytelling` mode, which the PixVerse website and this API both offer. ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. ### Example: a 2½-minute AI music video made from one song on a free account A 2½-minute song at 1080p in `performance` mode with lyric captions, made on a free PixVerse account at no cost (normally 2,280 credits). It took 15 minutes 44 seconds: <video src="https://media.useapi.net/pixverse/2026-11-10-music-video-article/pixverse-music-video-cant-stop-this-1080p.mp4" poster="https://media.useapi.net/pixverse/2026-11-10-music-video-article/pixverse-music-video-cant-stop-this-1080p-poster.jpg" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> PixVerse planned 17 shots from the song, kept the dancer from our photo in almost every one of them (afro, black sunglasses, tied-up white shirt, blue cycling shorts), lip-synced her to the vocals, built bright retro sets with floating cubes, music notes and a gramophone, and timed the captions to the sung words. Nobody edited anything. The same video on YouTube: [AI music video from one song and one photo](https://youtu.be/VDKYSzk3JQI). ### Step 1. Write the song with Flow Music The [Flow Music API](/docs/api-flowmusic-v1) generates a complete song from a style prompt and your lyrics on Google's Lyria models. We wanted a hard, minimal party rap with chants and stop-and-drop breaks, so the prompt spells out the beat, the voice and the structure: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-flowmusic-v1/post-flowmusic-music">POST /music</a> (Flow Music)</summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="lyria-3.5"' \ --form 'prompt="1990 pop-rap dance hit, 133 BPM, hard minimal drum machine beat with booming 808 kick and big gated hand claps, one repeating staccato funk bass-and-synth riff in the style of an early-80s funk sample looped through the whole song, sparse arrangement, confident sassy female MC with a strong low voice chanting short rhythmic lines on the beat, punchy shouted hooks, mixed gang vocal chants answering oh-oh oh-oh-oh, hard stops where the whole beat cuts out for a shouted line then slams back in, party dance floor energy, classic 1990 MTV rap anthem sound"' \ --form 'lyrics="[Verse 1] Ooh, that bassline hits me so hard Makes me jump up off the boulevard … [Verse 2] Step to the left, now step to the right Spin on the floor till the morning light …"' ``` </details> One request returns two takes in about a minute. We kept the first one, about 2½ minutes long. Lyria rewrote part of our lyrics while it sang and named the song "Can't Stop This", which is why the captions use the lyrics it returned, not the ones we sent: <audio class="audio-player" controls preload="metadata" src="https://media.useapi.net/pixverse/2026-11-10-music-video-article/flow-music-lyria-3-5-cant-stop-this.mp3"></audio> Getting here took four tries. A synth-pop song with clear vocals came out too sweet, a generic pop-rap prompt came out bland, and a male MC voice didn't fit a female dancer. Spelling out the minimal 808 beat, the looped funk riff, the chanted delivery and the hard stops is what got the sound. ### Step 2. Make the dancer with Nano Banana 2.1 The character photo decides who performs. PixVerse keeps the face, hair and outfit from it in almost every shot, so the photo needs a full body, a clearly visible face and a look that tells the story. We made it with Nano Banana 2.1 (`nano-banana-2` on the [Google Flow API](/docs/api-google-flow-v1/post-google-flow-images)), two images per request at 9:16: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a> (Google Flow)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="nano-banana-2"' \ --form 'aspectRatio="9:16"' \ --form 'count="2"' \ --form 'prompt="Still frame from a 1990 rap music video shot on 35mm film: a sexy, athletic, fit young woman rapper dancing in the sunny parking lot outside the Oakland Coliseum, clear blue sky, a boombox at her feet, dancers clapping behind her. Her look: black sunglasses, a white cropped jacket tied up at the front over a toned stomach, tight royal blue cycling shorts, gold chains, gold hoop earrings, white high-tops, voluminous curls. Rapping mid-line with lips clearly visible, full body in frame, face toward the camera, warm film colors, sharp focus"' ``` </details> <img src="https://media.useapi.net/pixverse/2026-11-10-music-video-article/nano-banana-2-1-character-oakland-coliseum-dancer.jpg" alt="Nano Banana 2.1 character: a dancer in a tied-up white shirt and blue cycling shorts outside the Oakland Coliseum" style="width: 100%; max-width: 360px;" loading="lazy"> Our first dancers looked like stock photos. What made the difference was describing the picture as a still from an old music video shot on film, naming a real place and period clothes, and asking for the lips to be visible for lip-sync. ### Step 3. Upload the song and the photo Upload both files to your PixVerse account with [POST files](/docs/api-pixverse-v2/post-pixverse-files) and keep the `path` of each. Upload the song as MP3: PixVerse refused an M4A file in our tests. With several PixVerse accounts connected, add `?email=` to the upload and `email` to the requests below to pick one, for example the account whose free music video you want to use. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-pixverse-v2/post-pixverse-files">POST /files</a> (PixVerse)</summary> ```bash curl --location 'https://api.useapi.net/v2/pixverse/files/' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: audio/mpeg' \ --data-binary '@cant-stop-this.mp3' # {"path": "upload/8aa34c5f-7f33-4fdc-af40-7357909102cb.mp3", "duration": 151.968, …} curl --location 'https://api.useapi.net/v2/pixverse/files/' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: image/jpeg' \ --data-binary '@dancer.jpg' # {"result": [{"path": "upload/66952750-badc-473b-b2a2-721197e96e7d.jpeg", …}]} ``` </details> ### Step 4. Check the price, then make the video Every request can be quoted first, for free. `quote: true` returns the exact price and creates nothing: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-pixverse-v2/post-pixverse-music-video-create">POST /music-video/create</a> with <code>quote</code></summary> ```bash curl --location 'https://api.useapi.net/v2/pixverse/music-video/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'audio_path="upload/8aa34c5f-7f33-4fdc-af40-7357909102cb.mp3"' \ --form 'image_path="upload/66952750-badc-473b-b2a2-721197e96e7d.jpeg"' \ --form 'mode="performance"' \ --form 'music_genre="hip_hop"' \ --form 'subtitles="true"' \ --form 'aspect_ratio="16:9"' \ --form 'quality="1080p"' \ --form 'quote="true"' ``` </details> <details markdown="block"> <summary>Expand <code>Response</code></summary> ```json { "quote": true, "mode": "performance", "quality": "1080p", "bill_seconds": 152, "credits_per_second": 15, "list_cost_credits": 2280, "cost_credits": 0, "free": true, "has_enough_credits": true } ``` </details> `cost_credits: 0` and `free: true` mean the account's free music video applies. Drop `quote` and add the lyrics, one line per caption, to make it. curl reads a multi-line field from a file with `<`: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-pixverse-v2/post-pixverse-music-video-create">POST /music-video/create</a></summary> ```bash curl --location 'https://api.useapi.net/v2/pixverse/music-video/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'audio_path="upload/8aa34c5f-7f33-4fdc-af40-7357909102cb.mp3"' \ --form 'image_path="upload/66952750-badc-473b-b2a2-721197e96e7d.jpeg"' \ --form 'mode="performance"' \ --form 'music_genre="hip_hop"' \ --form 'subtitles="true"' \ --form 'lyrics=<lyrics.txt' \ --form 'aspect_ratio="16:9"' \ --form 'quality="1080p"' ``` </details> The answer carries the `video_id`: <details markdown="block"> <summary>Expand <code>Response</code></summary> ```json { "video_id": "user:12345-pixverse:you@example.com-video:642767619916505", "project_id": 192080023076656, "mode": "performance", "quality": "1080p", "aspect_ratio": "16:9", "bill_seconds": 152, "credits_per_second": 15, "list_cost_credits": 2280, "cost_credits": 0, "free": true } ``` </details> ### Step 5. Wait for it and download it Poll [GET music-video/`video_id`](/docs/api-pixverse-v2/get-pixverse-music-video-video_id) until `status` is `succeeded` or `failed`, or pass a `replyUrl` with the create request and get the result by callback. A 30-second song took about 5 minutes to render, the 2½-minute song about 16 minutes. Save this as `poll.mjs` and run it with `node poll.mjs`: <details markdown="block"> <summary>Expand <code>poll.mjs</code></summary> ```javascript const token = process.env.USEAPI_TOKEN; const video_id = "user:12345-pixverse:you@example.com-video:642767619916505"; for (;;) { const res = await fetch(`https://api.useapi.net/v2/pixverse/music-video/${video_id}`, { headers: { Authorization: `Bearer ${token}` } }); const mv = await res.json(); console.log(mv.status); if (mv.status === "succeeded") { console.log(mv.video.url, mv.files); break; } if (mv.status === "failed") { console.log(mv.error); break; } await new Promise(r => setTimeout(r, 20000)); } ``` </details> `video.url` is the finished mp4. `files` holds the extras: the same video without captions, the timed lyrics as an `.ass` subtitle file (for a song with vocals), and the key images and clips PixVerse cut together. For our song that was 17 images and 17 clips, handy if you want to re-edit it yourself. PixVerse's media server refuses downloads that don't send a browser-like `User-Agent`, so set one if a script gets `403`. A runnable version of these steps, for a whole list of songs at once, is the [`music-video/` example](https://github.com/useapi/pixverse-api/tree/main/music-video) on GitHub: it quotes each job for free, makes the videos and downloads them with every extra file. ### More examples Three shorter videos from the same tests, each with a different mode or style. #### Performance, `auto` style, 9:16 at 720p A 30-second song clip and a Nano Banana 2.1 dancer on a neon street at night. With `style: auto` PixVerse chose its own set, a plush retro lounge with chandeliers, disco balls and backup dancers. 300 credits, 5 minutes 21 seconds. The song and the character that went in: <audio class="audio-player" controls preload="metadata" src="https://media.useapi.net/pixverse/2026-11-10-music-video-article/input-song-performance-lounge-30s.mp3"></audio> <img src="https://media.useapi.net/pixverse/2026-11-10-music-video-article/nano-banana-2-1-character-neon-street-dancer.jpg" alt="Nano Banana 2.1 character: a dancer in a black jacket on a neon street at night" style="width: 100%; max-width: 240px;" loading="lazy"> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-pixverse-v2/post-pixverse-music-video-create">POST /music-video/create</a></summary> ```bash curl --location 'https://api.useapi.net/v2/pixverse/music-video/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'audio_path="upload/881729de-53f0-47bd-8e46-d2c93a8a751f.mp3"' \ --form 'image_path="upload/51b3b775-5f85-4016-a946-4de6ba35c042.jpeg"' \ --form 'mode="performance"' \ --form 'style="auto"' \ --form 'aspect_ratio="9:16"' \ --form 'quality="720p"' ``` </details> The music video that came out: <video src="https://media.useapi.net/pixverse/2026-11-10-music-video-article/pixverse-music-video-performance-lounge-9x16-720p.mp4" poster="https://media.useapi.net/pixverse/2026-11-10-music-video-article/pixverse-music-video-performance-lounge-9x16-720p-poster.jpg" style="width: 100%; max-width: 400px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> #### Expressive, `custom` style, 16:9 at 1080p A 21-second song clip and a black-and-white Nano Banana 2.1 studio portrait of a dancer in a fedora and blazer. `style: custom` with no separate style image uses the character photo as the style, so the whole video stays black and white. 315 credits, 5 minutes 22 seconds. The song and the character that went in: <audio class="audio-player" controls preload="metadata" src="https://media.useapi.net/pixverse/2026-11-10-music-video-article/input-song-expressive-black-white-21s.mp3"></audio> <img src="https://media.useapi.net/pixverse/2026-11-10-music-video-article/nano-banana-2-1-character-black-white-dancer.jpg" alt="Nano Banana 2.1 character: a black-and-white photo of a dancer in a fedora, white shirt and blazer" style="width: 100%; max-width: 240px;" loading="lazy"> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-pixverse-v2/post-pixverse-music-video-create">POST /music-video/create</a></summary> ```bash curl --location 'https://api.useapi.net/v2/pixverse/music-video/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'audio_path="upload/90f95193-2c91-4a42-a506-930d4c964c45.mp3"' \ --form 'image_path="upload/ff4265e2-bdd5-490a-83bb-f77a34d2761b.jpeg"' \ --form 'mode="expressive"' \ --form 'style="custom"' \ --form 'aspect_ratio="16:9"' \ --form 'quality="1080p"' ``` </details> The music video that came out: <video src="https://media.useapi.net/pixverse/2026-11-10-music-video-article/pixverse-music-video-expressive-black-white-1080p.mp4" poster="https://media.useapi.net/pixverse/2026-11-10-music-video-article/pixverse-music-video-expressive-black-white-1080p-poster.jpg" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> #### Performance on an instrumental, 9:16 at 720p A 10-second instrumental beat from Flow Music and the same dancer as the main video. With no vocals there is nothing to lip-sync, so PixVerse makes a dance video on a sunny Mediterranean street. 100 credits, 3 minutes 13 seconds. The beat that went in: <audio class="audio-player" controls preload="metadata" src="https://media.useapi.net/pixverse/2026-11-10-music-video-article/flow-music-lyria-3-5-instrumental-10s.mp3"></audio> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-pixverse-v2/post-pixverse-music-video-create">POST /music-video/create</a></summary> ```bash curl --location 'https://api.useapi.net/v2/pixverse/music-video/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'audio_path="upload/23f6fdc4-8882-4b65-a70e-7a1a8b9c9761.mp3"' \ --form 'image_path="upload/66952750-badc-473b-b2a2-721197e96e7d.jpeg"' \ --form 'mode="performance"' \ --form 'style="auto"' \ --form 'aspect_ratio="9:16"' \ --form 'quality="720p"' ``` </details> The music video that came out: <video src="https://media.useapi.net/pixverse/2026-11-10-music-video-article/pixverse-music-video-instrumental-street-9x16-720p.mp4" poster="https://media.useapi.net/pixverse/2026-11-10-music-video-article/pixverse-music-video-instrumental-street-9x16-720p-poster.jpg" style="width: 100%; max-width: 400px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> ### Modes and styles | Mode | What it makes | Styles | |:-----|:--------------|:-------| | `performance` | the character sings the song with lip-sync | `auto`, `custom` and 16 looks such as `cinematic`, `underground`, `lo_fi`, `claymation`, `retro_game` | | `expressive` | emotional, atmospheric shots of the character | the same 18 | | `storytelling` | a storyline from your `prompt`, one or two characters | 18 of its own, such as `photorealistic`, `anime`, `cyberpunk`, `ghibli`, `lego_blocks` | The full lists, lyric captions, aspect ratios and the built-in [library](/docs/api-pixverse-v2/get-pixverse-music-video-library) of 13 songs, 15 characters and 28 style images are on the [endpoint page](/docs/api-pixverse-v2/post-pixverse-music-video-create). ### Use it from Claude, ChatGPT or Cursor The hosted [PixVerse MCP server](/docs/api-pixverse-v2/mcp) makes the same music videos from Claude Code, Cursor, VS Code and other MCP clients, with nothing to install, and the Claude app and ChatGPT connect to it with a sign-in. It has 38 tools and runs on your own PixVerse accounts with your useapi.net API token. In Claude Code: ```bash claude mcp add --transport http useapi-pixverse https://api.useapi.net/v2/pixverse/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` Then ask, for example, "Make a music video from this MP3 with my photo as the performer, 9:16, with lyric captions". The assistant uploads both with `pixverse_upload_file`, can quote the price first, calls `pixverse_create_music_video` with the same modes and styles as above and hands back the finished video from `pixverse_get_music_video`. The [`pixverse-api`](https://github.com/useapi/pixverse-api#use-with-claude-code) repo also installs as a Claude Code plugin or a [Gemini CLI extension](https://github.com/useapi/pixverse-api#use-with-gemini-cli). ### Questions #### Is there a PixVerse music video API? Yes. useapi.net's [PixVerse API](/docs/api-pixverse-v2) makes music videos from your song on your PixVerse subscription, in all three modes of PixVerse's One-Click MV. On Premium a minute of song at 720p costs $2.40, against $4.00 on PixVerse's own developer API, which has no expressive or storytelling mode (as of November 2026). #### Can I make an AI music video for free? Yes. Through useapi.net the first music video on any PixVerse account, even a free Basic one, costs nothing at any length (ours ran 2½ minutes), in any mode and at 1080p, and a `quote` shows `free: true` while it is unused. On PixVerse's own developer API the same 2½-minute 1080p video would cost $15.20 (22.5 credits a second at 225 credits per dollar, as of November 2026). #### Can an API lip-sync a singer to my song? Yes. In `performance` mode the useapi.net PixVerse API lip-syncs the character from your photo to the song's vocals, with no separate lip-sync step, as in our video above. Use a full-body photo with the face and lips clearly visible. At 1080p it costs $3.60 a minute on Premium, against $6.00 on PixVerse's own developer API (as of November 2026). #### Do I need lyrics to get captions? No. Through useapi.net, `subtitles: true` alone makes PixVerse transcribe the vocals and time the captions, and `lyrics`, one line per caption, fixes the spelling. Every video also comes with a copy without captions, and a song with vocals also gets the `.ass` subtitle file. Captions work in `expressive` mode too, which PixVerse's developer API doesn't offer (as of November 2026). ### Conclusion A song, a photo and one API call make a finished music video, and with Flow Music and the Google Flow API the song and the photo can come from the same useapi.net subscription. Start with the free music video on your PixVerse account, then see [POST music-video/create](/docs/api-pixverse-v2/post-pixverse-music-video-create) for every option. Visit our <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> or <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> for any support questions and concerns. === URL: https://useapi.net/docs/articles/runway-bash === Document URL: https://useapi.net/docs/articles/runway-bash --- layout: default title: How to Generate Runway Gen Videos via API description: "Generate Runway Gen-4.5 / Gen-4 video — plus the Veo 3.1, Kling and Seedance 2.0 models Runway hosts — through the useapi.net Runway API, with copy-paste curl and a batch script." keywords: [Runway API, Gen-4.5 API, Gen-4 API, Runway Gen video, RunwayML API, Veo 3.1, Kling, Seedance 2.0, video generation, text to video, image to video] parent: Articles nav_exclude: true date: 2024-08-11 last_modified: 2026-10-23 nav_order: 200 repo: https://github.com/useapi/runway-api --- ## How to Generate Runway Gen Videos via API 6 min read • August 11, 2024 (October 23, 2026) ## Table of contents ### Introduction Runway hosts its own Gen-4.5 / Gen-4 / Gen-4 Aleph video and Frames images, plus third-party models behind the same account, and you can drive every one of them from code. [Runway](https://runwayml.com) is the generative-video studio behind the Gen series, and [useapi.net](/docs/subscription) fronts it with a third-party [Runway API](/docs/api-runwayml-v1) that runs on your Runway website subscription over a standard REST endpoint — one unified [videos/create](/docs/api-runwayml-v1/post-runwayml-videos-create) call, no developer account, no per-generation metering from us. The same subscription and token reach the third-party models Runway hosts — [Veo 3.1](https://deepmind.google/models/veo/), [Kling](https://klingai.com), [Seedance 2.0](https://seed.bytedance.com/) and [Wan](https://wan.video/) for video, plus [FLUX.2](https://bfl.ai), [Nano Banana](https://deepmind.google/models/gemini/flash/) and [GPT Image](https://platform.openai.com/docs/models/gpt-image-1) for stills — so you can pick the right model per prompt without juggling a separate key for each vendor. ### Supported models The [videos/create](/docs/api-runwayml-v1/post-runwayml-videos-create) endpoint is unified — you pick a model per request with the `model` field, and the script defaults to `gen4.5`. The most-used video models are below. Capabilities differ by model. | Model (`model`) | Durations | Aspect ratios | Frames | Audio | |---|---|---|---|---| | `gen4.5` (default) | 2–10s | 16:9 (T2V) · all (I2V) | start frame | yes | | `gen4` | 5s, 10s | all | start frame *(required)* | — | | `gen4-turbo` | 5s, 10s | all | start frame *(required)* | — | | `veo-3.1` | 4s, 6s, 8s | 16:9, 9:16 | start + end | yes | | `kling-3.0-pro` | 5s, 10s, 15s | 16:9, 9:16, 1:1 | start + end | yes | | `kling-2.6-pro` | 5s, 10s | 16:9, 9:16 | start frame | yes | | `seedance-2` | 4–15s | 16:9, 9:16, 1:1, 4:3, 3:4, 21:9 | start + end | yes | | `seedance-2-fast` | 4–15s | 16:9, 9:16, 1:1, 4:3, 3:4, 21:9 | start + end | yes | | `wan-2.6-flash` | 5s, 10s, 15s | 16:9, 9:16, 1:1 | start frame *(required)* | yes | That is the short list — [videos/create](/docs/api-runwayml-v1/post-runwayml-videos-create) also exposes `seedance-2-5` (up to 30s with as many as 50 references), `seedance-2-mini`, `kling-3.0-standard`, `kling-3.0-motion-control`, the `kling-o3-*` omni tiers, `kling-2.6-i2v`, `wan-2.2-animate`, `wan-3.0` / `wan-3.0-prime` (up to 30s with image, video and audio references), `minimax-h3` / `minimax-h3-max`, `flux-3` (with video extend), `grok-imagine-1.5` and `happyhorse-1.0`. The endpoint page has the full per-model parameter tables. Sora 2 is no longer available: OpenAI shut it down on September 24, 2026. Among the frame-aware models, `kling-3.0-pro` and `veo-3.1` accept an end frame for a first→last transition, while the Gen-4.x models take a single start frame only. ### Pricing Your Runway website subscription pays for every video: each generation spends the same credits it costs in the Runway web app, with no per-generation surcharge from useapi.net. On [Runway Max](https://runwayml.com/pricing) billed yearly ($76 a month for 9,500 credits) a credit costs $0.008, against $0.01 on Runway's [developer API](https://docs.dev.runwayml.com/guides/pricing/) (as of October 2026). The [cost calculator](/docs/api-runwayml-v1) on the overview prices every model on every plan. ### Generate a video in two API calls You need a useapi.net [API token](/docs/start-here/setup-useapi) and a connected [Runway account](/docs/start-here/setup-runwayml) — export the token so the `curl` examples below run as-is: ```bash export USEAPI_TOKEN="user:1234-..." ``` Generation is asynchronous — the create call returns a task immediately, then you poll until the video is ready. First, submit the job with `POST https://api.useapi.net/v1/runwayml/videos/create`: ```bash curl -X POST "https://api.useapi.net/v1/runwayml/videos/create" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model": "gen4.5", "text_prompt": "A cinematic aerial shot of a coastal city at golden hour, camera slowly pushing in", "duration": 5, "aspect_ratio": "16:9" }' ``` The response returns immediately with a task object. The id you poll on is the `taskId` string: ```json { "task": { "taskId": "user:1234-runwayml:user@example.com-task:<uuid>", "taskType": "gen4.5", "status": "PENDING", "artifacts": [], "code": 200 } } ``` Then poll for the result with `GET https://api.useapi.net/v1/runwayml/tasks/{taskId}`: ```bash curl "https://api.useapi.net/v1/runwayml/tasks/TASK_ID" \ -H "Authorization: Bearer $USEAPI_TOKEN" ``` The task is done when `status` is `SUCCEEDED` — the finished MP4 is the first entry of the `artifacts` array, at `artifacts[0].url`: ```json { "status": "SUCCEEDED", "artifacts": [ { "url": "https://.../runway-result.mp4" } ] } ``` A Gen-4.5 generation typically finishes in a couple of minutes — Gen-4 Turbo and Veo 3.1 are usually faster. Prefer not to poll? Pass a `replyUrl` in the create body to receive a webhook callback when the task completes or fails. The create call can return `412` (not enough credits — switch to a model or plan you have credits for), `422` (the prompt was moderated), or `429` (the account is busy — wait 10–30 seconds and retry). Up to two generations usually run in parallel per account, so add more Runway accounts to run a bigger batch at once. ### Image-to-video (first / last frame) To animate a still image, upload it first with [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets) — the upload returns an `assetId` tied to the account it was uploaded to (that same account runs the generation). Pass it as `imageAssetId1` for the start frame, and on the frame-aware models that support it (`kling-3.0-pro`, `veo-3.1`) add `imageAssetId2` for the end frame: ```bash # 1. Upload the start frame → returns { "assetId": "..." } curl -X POST "https://api.useapi.net/v1/runwayml/assets/?email=user@example.com&name=first.jpeg" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: image/jpeg" \ --data-binary @first.jpeg # 2. Create the video from that frame curl -X POST "https://api.useapi.net/v1/runwayml/videos/create" \ -H "Authorization: Bearer $USEAPI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model": "gen4.5", "text_prompt": "the character turns and smiles", "duration": 5, "imageAssetId1": "ASSET_ID_FROM_STEP_1" }' ``` Runway accepts `.png`, `.jpeg` and `.gif` images. You can also feed `.webp` — just rename the extension to `.jpeg`. A start → end frame pair (`imageAssetId1` + `imageAssetId2`) is supported only by `kling-3.0-pro` and `veo-3.1`. ### Beyond text-to-video The same account and token also reach Runway's other tools through their own endpoints, so the batch script extends naturally to more than `videos/create`: - [Frames images](/docs/api-runwayml-v1/post-runwayml-frames-create) — Runway's high-fidelity image model. [POST /frames/create](/docs/api-runwayml-v1/post-runwayml-frames-create) returns four 1080p images and lets you pass up to three reference images (`imageAssetId1`–`imageAssetId3`, referenced as `@IMG_1`–`@IMG_3` in the prompt). A separate [Runway Frames tutorial](/docs/articles/runway-frames-script) covers it end to end. - [Act-Two](/docs/api-runwayml-v1/post-runwayml-gen4-act-two) — animate a character from a driving video plus an image or video reference, via [POST /gen4/act-two](/docs/api-runwayml-v1/post-runwayml-gen4-act-two). - [Images](/docs/api-runwayml-v1/post-runwayml-images-create) — a unified image endpoint for FLUX 3, FLUX.2, Nano Banana / Pro, GPT Image and Seedream 5. - [4K upscale](/docs/api-runwayml-v1/post-runwayml-videos-upscale) — upscale any clip to 4K with Topaz. ### Batch-generate with a script Finding the right shot takes many attempts, and running them by hand is tedious. The Node.js script below reads a list of prompts from `prompts.json`, uploads any first/last frame images, submits each job (defaulting to `gen4.5`), then polls and downloads every finished MP4 — so you can queue a batch and come back to the winners. You select the model per prompt with the `model` field, so a single `prompts.json` can mix Gen-4.5 text-to-video, a `kling-3.0-pro` first-and-last-frame shot, and a fast `gen4-turbo` image-to-video clip. You need [Node.js](https://nodejs.org) v21 or newer. Put `prompts.json` and `runwayml.mjs` in the same folder and run `node ./runwayml.mjs API_TOKEN EMAIL`, where `API_TOKEN` is your useapi.net [API token](/docs/start-here/setup-useapi) and `EMAIL` is your connected [Runway account](/docs/start-here/setup-runwayml) email. It helps to feed your images to ChatGPT, Claude or Gemini along with Runway's [prompting guides](https://help.runwayml.com/) and have it draft prompt variations for you — then keep the winners. <details markdown="block"> <summary>Expand `prompts.json`</summary> ```json [ { "text_prompt": "By default the Gen-4.5 model with a 5-second duration will be used." }, { "model": "kling-3.0-pro", "duration": 10, "aspect_ratio": "16:9", "firstImage": "./first_image.jpeg", "lastImage": "./last_image.jpeg", "text_prompt": "First-and-last-frame video with Kling 3.0 Pro: a start frame (firstImage → imageAssetId1) and an end frame (lastImage → imageAssetId2). Kling 3.0 Pro supports an end frame — the Gen-4.x models accept a single start frame only. For all parameters see https://useapi.net/docs/api-runwayml-v1/post-runwayml-videos-create" }, { "model": "gen4-turbo", "duration": 5, "firstImage": "./image.jpeg", "text_prompt": "Faster Gen-4 Turbo generation from a single start frame. Other models (veo-3.1, kling-3.0-pro, seedance-2, …) are selectable via the model field — see the videos/create docs." } ] ``` </details> <details markdown="block"> <summary>Expand `runwayml.mjs` script</summary> ```javascript /* Script version 3.1, June 22, 2026 Script to batch-generate videos using prompts with the Runway API v1 by useapi.net 🚀 Uses the unified videos/create endpoint (default model: Gen-4.5). For more details visit https://useapi.net/docs/api-runwayml-v1/post-runwayml-videos-create Installation Instructions: ========================== You need Node.js v21 or newer installed to run this script. Download and install Node.js from: - Windows, macOS, Linux: https://nodejs.org/ After installation, verify by running the following command in a terminal: node -v Running the Script: =================== Usage: node runwayml.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE] Replace API_TOKEN with your actual useapi.net API token, see https://useapi.net/docs/start-here/setup-useapi Replace EMAIL with configured Runway email account, see https://useapi.net/docs/start-here/setup-runwayml If optional PROMPTS_FILE not provided prompts.json will be used. Example: -------- node runwayml.mjs user:1234-abcdefhijklmnopqrstuv my@email.com This command executes the script using API token user:1234-abcdefhijklmnopqrstuv with my@email.com Runway account email. Changelog: ========== - June 22, 2026: Maintenance release. - June 15, 2026: Migrated to the unified videos/create endpoint. Select the model via the prompt's model field (default gen4.5). - October 22, 2024: Small bug fix with parameter validation. */ import readline from 'node:readline'; import fs from 'fs/promises'; import path from 'path'; import { writeFile } from 'node:fs/promises'; import { Readable } from 'node:stream'; // Constants const RESULTS_FILE = 'runwayml_results.txt'; const ERRORS_FILE = 'runwayml_errors.txt'; const DEFAULT_PROMPTS_FILE = 'prompts.json'; const DEFAULT_MODEL = 'gen4.5'; const SLEEP_429 = 10 * 1000; // in milliseconds const SLEEP_DOWNLOAD = 20 * 1000; // in milliseconds const urlAccounts = 'https://api.useapi.net/v1/runwayml/accounts'; const urlVideosCreate = 'https://api.useapi.net/v1/runwayml/videos/create'; const urlDownload = 'https://api.useapi.net/v1/runwayml/tasks/'; const urlUploadAsset = 'https://api.useapi.net/v1/runwayml/assets/?email='; // To upload .webp rename it to .jpeg const supportedFileExtensions = ['png', 'jpeg', 'gif'] // { filename: assetId } const uploadedFiles = {}; // Utility to sleep for given milliseconds const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); // Function to fetch configured Runway API accounts async function fetchAccounts(apiToken) { const response = await fetch(urlAccounts, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.error(`⛔ Error fetching accounts (HTTP ${response.status}): ${response.statusText}`); process.exit(1); } return response.json(); } const elapsedTimeSec = (start) => (Date.now() - start) / 1000; async function uploadAsset(apiToken, email, filename) { // Check if already uploaded if (uploadedFiles.hasOwnProperty(filename)) return uploadedFiles[filename]; const startTime = Date.now(); console.log(`⬆️ Account ${email} uploading file…`, filename); const body = new Blob([await fs.readFile(filename)]); const name = path.basename(filename); const fileExt = filename.split('.').pop(); const response = await fetch(`${urlUploadAsset}${email}&name=${name}`, { method: 'POST', headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}`, 'Content-Type': `image/${fileExt}` }, body }); if (response.ok) { const json = await response.json(); const { assetId } = json; console.log(`🆗 assetId (${elapsedTimeSec(startTime)} sec)`, assetId); uploadedFiles[filename] = assetId; } else { console.error(`❗ Unable to upload file HTTP ${response.status} (${elapsedTimeSec(startTime)} sec)`, await response.text()); // Do not attempt to upload failed file again uploadedFiles[filename] = undefined; } return uploadedFiles[filename]; } async function submit(apiToken, url, body, index, text_prompt) { const createResponse = await fetch(url, { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiToken}` }, body }); const createBody = await createResponse.text(); if (createResponse.status == 200) { const json = JSON.parse(createBody); const { taskId } = json; if (taskId) { await fs.appendFile(RESULTS_FILE, `${taskId},#${index}:${text_prompt}\n`); console.log(`✅ taskId`, taskId); return 200; } else { const error = `No taskId found in HTTP 200 response`; console.log(`❓ ${error}`, createBody); await fs.appendFile(ERRORS_FILE, `${error},#${index}:${text_prompt}\n`); return 500; } } else { switch (createResponse.status) { case 429: console.log(`🔄️ Retry on HTTP ${createResponse.status}`); break; case 422: console.log(`🛑 MODERATED prompt`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${text_prompt}\n`); break; case 412: console.log(`🛑 account run out of credits`, createBody); break; default: console.log(`❗ FAILED with HTTP ${createResponse.status}`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${text_prompt}\n`); } return createResponse.status; } } // Submit a single prompt to the unified videos/create endpoint. // imageAssetId1 = start frame (firstImage or image), imageAssetId2 = end frame (lastImage). async function submitVideo(apiToken, email, prompt, index) { const { model, text_prompt, firstImage, lastImage, image, aspect_ratio, duration, seed } = prompt; const useModel = model ?? DEFAULT_MODEL; const exploreMode = prompt?.exploreMode; const useDuration = duration ?? 5; console.log(`🚀 ${useModel} » Prompt #${index} • account ${email} • ${useDuration} secs …`); const startFrame = firstImage ?? image; const imageAssetId1 = startFrame ? await uploadAsset(apiToken, email, startFrame) : undefined; const imageAssetId2 = lastImage ? await uploadAsset(apiToken, email, lastImage) : undefined; const body = JSON.stringify({ model: useModel, email, text_prompt, aspect_ratio, duration: useDuration, seed, exploreMode, imageAssetId1, imageAssetId2 }); return await submit(apiToken, urlVideosCreate, body, index, text_prompt); } // Function to download videos async function download(apiToken) { if (! await fileExists(RESULTS_FILE)) return; try { const resultsContent = await fs.readFile(RESULTS_FILE, 'utf8'); const lines = resultsContent.trim().split('\n'); for (const line of lines) { const [taskId, prompt] = line.split(','); const videoFilename = `${taskId.replace(/:/g, '_')}.mp4`; console.log(`👉 ${taskId}`); try { await fs.access(videoFilename); console.log(`⚠️ ${videoFilename} already exists. Skipping download.`); continue; } catch { // File does not exist, proceed with downloading } while (true) { const response = await fetch(`${urlDownload}${taskId}`, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.log(`🛑 Download failed ${taskId} (HTTP ${response.status}):\n${prompt}\n`, await response.text()); break; } const taskResponseBody = await response.json(); const { status, artifacts, error, progressRatio, estimatedTimeToStartSeconds } = taskResponseBody; if (status == 'FAILED') { console.error(`🛑 FAILED ${taskId} (${error}):\n${prompt}\n`); break; } if (status == 'SUCCEEDED') { const url = artifacts.at(0).url; if (url) { console.log(`✅ Downloading ${url} to ${videoFilename}`); try { const videoResponse = await fetch(url); if (!videoResponse.ok) { console.error(`⛔ Unable to download ${taskId} (HTTP ${videoResponse.status}):\n${prompt}\n`, url); break; } const stream = Readable.fromWeb(videoResponse.body); await writeFile(videoFilename, stream); } catch (err) { console.error(`⛔ Error during download: ${err}`); } } else console.error(`🛑 Unable to download ${taskId} status (${status} ${error}):\n${prompt}\n`); break; } console.log(`⌛ ${taskId} status (${status}) and is still in progress (${progressRatio * 100}%, seconds to start ${estimatedTimeToStartSeconds}), waiting…`); await sleep(SLEEP_DOWNLOAD); } } } catch (error) { console.log(`⛔ Error during download:`, error.stack || error); } } // Main function async function main() { const apiToken = process.argv[2]; const email = process.argv[3]; const promptFile = process.argv[4] || DEFAULT_PROMPTS_FILE; if (!apiToken || !email) { console.error('Usage: node runwayml.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE]'); process.exit(1); } console.info('Script v3.1'); console.info('Node version is: ' + process.version); try { if (await fileExists(RESULTS_FILE)) { let user_input; while (!['y', 'n'].includes(user_input)) { user_input = (await promptUser(`❔ ${RESULTS_FILE} file detected. Do you want to download the results now? (y/n): `))?.toLowerCase(); if (user_input == 'y') { await download(apiToken); await fs.unlink(RESULTS_FILE); } } } const start = new Date(); try { console.info('START EXECUTION', start); await execute(apiToken, email, promptFile); // Pass the promptFile to execute function } finally { console.info('COMPLETED', new Date()); console.info('EXECUTION ELAPSED', diffInMinutesAndSeconds(start, new Date())); } try { console.info('START DOWNLOAD', start); await download(apiToken); } finally { console.info('TOTAL ELAPSED', diffInMinutesAndSeconds(start, new Date())); } } catch (error) { console.error('⛔ Error during execution:', error.stack || error); } } // Modify the execute function to accept promptFile as a parameter async function execute(apiToken, email, promptFile) { const accounts = await fetchAccounts(apiToken); console.info(`Configured Runway API accounts (${Object.values(accounts).length}):`, Object.values(accounts).map(a => a.email).join(', ')); if (Object.values(accounts).length <= 0) { console.error(`⛔ No configured Runway accounts found. Please refer to https://useapi.net/docs/start-here/setup-runwayml`); process.exit(1); } if (!accounts[email]) { console.error(`⛔ Accounts ${email} not found. Please refer to https://useapi.net/docs/start-here/setup-runwayml`); process.exit(1); } if (accounts[email].error) { console.error(`⛔ Accounts ${email} has pending error. Please resolve and update account at https://useapi.net/docs/api-runwayml-v1/post-runwayml-accounts-email`); process.exit(1); } const promptData = await fs.readFile(promptFile, 'utf8'); const prompts = JSON.parse(promptData); console.log(`Total number of prompts to process`, prompts.length); let warnings = []; // Parameters accepted by this script for the videos/create endpoint. // See https://useapi.net/docs/api-runwayml-v1/post-runwayml-videos-create for every model's full parameter set. const supportedParams = ['model', 'text_prompt', 'firstImage', 'lastImage', 'image', 'aspect_ratio', 'duration', 'seed', 'exploreMode']; const invalidKeys = (prompt) => Object.keys(prompt).filter(key => !key.startsWith('__') && !supportedParams.includes(key)) for (let i = 1; i <= prompts.length; i++) { const prompt = prompts[i - 1]; const { text_prompt, firstImage, lastImage, image } = prompt; const validateImage = async (file) => { if (file) { try { await fs.access(file); } catch { warnings.push(`⚠️ Image '${file}' does not exist. Prompt ${i}`); } const ext = file.split('.').pop(); if (!supportedFileExtensions.includes(ext)) warnings.push(`⚠️ Image ${file} extension ${ext} not supported. Prompt ${i}`); } }; const notSupported = invalidKeys(prompt); if (notSupported.length) warnings.push(`⚠️ Following params not supported: ${notSupported.join(',')}. Prompt ${i}`); if (!text_prompt && !firstImage && !lastImage && !image) warnings.push(`⚠️ Please specify text_prompt and/or an image (firstImage / lastImage / image). Prompt ${i}`); await Promise.all([validateImage(firstImage), validateImage(lastImage), validateImage(image)]); } if (warnings.length > 0) { warnings.forEach(warning => console.warn(warning)); console.error(`⛔ Execution stopped due to warnings.`); process.exit(1); } for (let i = 0; i < prompts.length; i++) { const prompt = prompts[i]; while (true) { const responseCode = await submitVideo(apiToken, email, prompt, i + 1); if (responseCode == 429) await sleep(SLEEP_429); else if (responseCode == 412) { process.exit(1); } else break; } } } // Utility function to check if a file exists async function fileExists(path) { try { await fs.access(path); return true; } catch { return false; } } // Function to prompt user input async function promptUser(query) { const rl = readline.createInterface({ input: process.stdin, output: process.stdout }); return new Promise((resolve) => rl.question(query, answer => { rl.close(); resolve(answer); })); } function diffInMinutesAndSeconds(date1, date2) { const diffInSeconds = Math.floor((date2 - date1) / 1000); return `${Math.floor(diffInSeconds / 60)} minutes ${diffInSeconds % 60} seconds`; }; main(); ``` </details> ### Examples The clips below are real generations produced through this Runway API, straight from our blog walkthroughs — same `videos/create` endpoint, model-matched. ###### Gen-4.5 — text-to-video, 16:9 (no image input) <video poster="https://media.useapi.net/articles/2024-08-11-runway-bash/runway45result-poster.jpg" src="https://media.useapi.net/articles/2024-08-11-runway-bash/runway45result.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> — from [Runway: Gen-4.5 Text-to-Video](/blog/251215) Also on YouTube: [Noir Christmas • Runway Gen-4.5](https://www.youtube.com/watch?v=I8esy4sKMwo). ###### Gen-4.5 — image-to-video, 9:16 from a single start frame <video poster="https://media.useapi.net/articles/2024-08-11-runway-bash/runway-gen4-5-i2v-result-poster.jpg" src="https://media.useapi.net/articles/2024-08-11-runway-bash/runway-gen4-5-i2v-result.mp4" style="width: 100%; max-width: 400px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> — from [Runway Gen-4.5: Image-to-Video](/blog/260123) ###### Kling 3.0 Pro — `kling-3.0-pro`, text-to-video with sound, 9:16 <video poster="https://media.useapi.net/articles/2024-08-11-runway-bash/runway-kling-3-0-pro-with-sound-poster.jpg" src="https://media.useapi.net/articles/2024-08-11-runway-bash/runway-kling-3-0-pro-with-sound.mp4" style="width: 100%; max-width: 400px;" controls type="video/mp4" preload="metadata"></video> ###### Veo 3.1 — `veo-3.1`, same prompt with sound, 9:16 <video poster="https://media.useapi.net/articles/2024-08-11-runway-bash/runway-veo-3-1-with-sound-poster.jpg" src="https://media.useapi.net/articles/2024-08-11-runway-bash/runway-veo-3-1-with-sound.mp4" style="width: 100%; max-width: 400px;" controls type="video/mp4" preload="metadata"></video> ###### Sora 2 — `sora-2`, same prompt with sound, 9:16 Generated before OpenAI shut down Sora 2 on September 24, 2026. Sora 2 is no longer available, but the clip stays here as a comparison point. <video poster="https://media.useapi.net/articles/2024-08-11-runway-bash/runway-sora-2-with-sound-poster.jpg" src="https://media.useapi.net/articles/2024-08-11-runway-bash/runway-sora-2-with-sound.mp4" style="width: 100%; max-width: 400px;" controls type="video/mp4" preload="metadata"></video> The Kling 3.0 Pro, Veo 3.1 and Sora 2 clips above are the same prompt run through three hosted models (Sora 2 before its shutdown) — from [Runway: Unified Videos Endpoint and New Models](/blog/260305), which also shows Kling 2.6 I2V and Wan 2.2 Animate. ###### Seedance 2.0 (via Runway) — `seedance-2`, image-to-video with real faces, 15s 9:16 <video poster="https://media.useapi.net/articles/2024-08-11-runway-bash/runway-original-result-poster.jpg" src="https://media.useapi.net/articles/2024-08-11-runway-bash/runway-original-result.mp4" style="width: 100%; max-width: 400px;" controls type="video/mp4" preload="metadata"></video> — from [Seedance 2.0: Using Real Faces](/blog/260415) ### Frequently asked questions **Is there a Runway API?** Through useapi.net, yes: the Runway API spends the credits of your [Runway website subscription](https://runwayml.com/pricing), which Runway's own developer API can't use, and those credits reach models its [developer price list](https://docs.dev.runwayml.com/guides/pricing/) doesn't sell: FLUX 3, Kling 2.6, Kling 3.0 Motion Control, Wan 2.2 Animate and Topaz 4K upscale (as of October 2026). Gen-4.5, Gen-4, Gen-4 Turbo and every other model Runway hosts run on the same REST endpoint. **How much does the Runway API cost?** Through useapi.net, a 5-second Gen-4.5 video spends 60 credits, about $0.48 on Runway Max billed yearly, against $0.60 on Runway's [developer API](https://docs.dev.runwayml.com/guides/pricing/), which bills the same 12 credits a second at $0.01 each (as of October 2026). The overview's [cost calculator](/docs/api-runwayml-v1) prices every model on every plan. **Do I need a Runway API key?** Through useapi.net, no Runway developer key: you call the API with a useapi.net [API token](/docs/start-here/setup-useapi) and connect your Runway website subscription through [Setup Runway](/docs/start-here/setup-runwayml). Runway's developer API uses its own key and a separate credit balance, which the credits of a Runway website subscription don't cover. Runnable Node.js examples are on GitHub at [useapi/runway-api](https://github.com/useapi/runway-api). **Can I turn an image into a video (image-to-video)?** Through useapi.net, yes. Upload the still with [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets) and pass the returned `assetId` as `imageAssetId1` (start frame). For a first→last transition add `imageAssetId2` (end frame) on `kling-3.0-pro` or `veo-3.1`, while the Gen-4.x models take a single start frame only. See [Image-to-video](#image-to-video-first--last-frame) above. **Which Runway models can I generate through the API?** Through useapi.net, pick a model per request with the `model` field on [POST /videos/create](/docs/api-runwayml-v1/post-runwayml-videos-create): Runway's own `gen4.5` (default), `gen4` and `gen4-turbo`, plus the Veo 3.1, Kling, Seedance, Wan, MiniMax H3, FLUX 3, Grok Imagine and HappyHorse models Runway hosts, all on the credits of your Runway website subscription. The [Supported models](#supported-models) table lists durations, aspect ratios and frames for the most-used ones. ### Conclusion Visit our <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> or <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> for any support questions and concerns. The full runnable example is in the [`runway-api` GitHub repo](https://github.com/useapi/runway-api). === URL: https://useapi.net/docs/articles/runway-frames-script === Document URL: https://useapi.net/docs/articles/runway-frames-script --- layout: default title: How to Batch-Generate Images with Runway Frames via API description: "Batch-generate high-fidelity images with Runway Frames — including reference images — via the useapi.net Runway API, with example code." keywords: [Runway, Runway Frames, image generation, reference images, tutorial, code] parent: Articles nav_exclude: true date: 2025-02-01 last_modified: 2026-10-18 nav_order: 210 repo: https://github.com/useapi/runway-api --- ## How to Batch-Generate Images with Runway Frames via API 3 min read • January 31, 2025 (October 18, 2026) ## Table of contents ### Introduction In this article, we will show how to use a [third-party Runway API](/docs/api-runwayml-v1) for [RunwayML](https://runwayml.com) to batch-generate images with [Runway Frames](https://useapi.net/docs/api-runwayml-v1/post-runwayml-frames-create). If you are an advanced user or perhaps want to utilize your time and efforts efficiently, and are a happy owner of Runway's [Unlimited subscription](https://runwayml.com/pricing), this article is for you! As you probably already figured out, it takes many attempts before you get your perfect image. This trial and error task can be very tedious and time-consuming. But it does not have to be, enter the bright and shiny world of Automation. With a simple script provided below and some basic file editing, you can cut out all the waiting time and get straight to picking the winners. On average, Runway takes about 20 to 30 seconds to complete a single Frames generation. Each generation produces four images. You can run up to two generations in parallel. With the script provided below, you can expect to complete around 100 generations per hour (about 400 images in total). ### Preparing Prompts Suppose you have a few text prompts for your project. The first step will be to create a file `frames.json` as shown below and edit it so it contains your Runway prompts. You can put as many prompts as you wish. No need to hold back, as you will not be running them manually, not anymore. It may help to use ChatGPT, Claude or perhaps Gemini along with the [Frames Prompting Guide](https://help.runwayml.com/hc/en-us/articles/35694045317139-Frames-Prompting-Guide) and ask them to build prompts for you. This way, you can build a lot of prompts very quickly and get it going. Later, you can see what is working and what's not, and refine them. Frames also supports up to three **reference images** — upload them first with [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets), then pass their asset ids as `imageAssetId1`, `imageAssetId2` and `imageAssetId3` and refer to them in the prompt as `@IMG_1`, `@IMG_2` and `@IMG_3` to guide style, character or scene. See the [References Guide](https://help.runwayml.com/hc/en-us/articles/40042718905875-References-Guide) and this [worked example](/blog/250430). Each call returns `num_images` images (1 or 4, default 4 in the script below). <details markdown="block"> <summary>Expand `frames.json`</summary> ```json [ { "text_prompt": "Your prompt goes here. By default exploreMode is ON and num_images is 4." }, { "text_prompt": "Your prompt goes here. You can optionally provide all the params supported by Frames, see https://useapi.net/docs/api-runwayml-v1/post-runwayml-frames-create", "style": "terracotta", "exploreMode": false, "aspect_ratio": "21:9", "diversity": 5, "num_images": 4, "seed": 987654321 }, { "text_prompt": "Reference images: upload them first with POST /assets, then refer to them as @IMG_1 / @IMG_2 / @IMG_3 in the prompt. A woman in the style of @IMG_1 standing in @IMG_2.", "imageAssetId1": "user:1234-runwayml:me@email.com-asset:uuid-1", "imageAssetId2": "user:1234-runwayml:me@email.com-asset:uuid-2" } ] ``` </details> ### Executing script The real magic starts here. We assume that you subscribed to [useapi.net](/docs/subscription). Our subscription is essentially free when you consider the time you will save. It takes only a few minutes to [set up](/docs/start-here/setup-runwayml) Runway with our API. Finally, you can glance over the very [detailed API documentation](/docs/api-runwayml-v1) we provide. Each endpoint provides the ability to **Try It** right from the browser, for example [Frames » Try It](/docs/api-runwayml-v1/post-runwayml-frames-create#try-it). If you don't feel like reading the docs, that is fine too, the script below is all you need. We will be using [Node.js](https://nodejs.org) to execute JavaScript script provided below. Please [download](https://nodejs.org/en/download/package-manager) and install version 21 or older. Create a file `frames.mjs` with the code provided below. Your `frames.json` should be in the same folder as `frames.mjs`. Finally, execute the script `node ./frames.mjs API_TOKEN EMAIL` where `API_TOKEN` is your useapi.net [API token](/docs/start-here/setup-useapi) and `EMAIL` is configured [Runway account](/docs/start-here/setup-runwayml) email you want to use. All generated images will be downloaded locally to your drive, so you can view them once they are ready. <details markdown="block"> <summary>Expand `frames.mjs` script</summary> ```javascript /* Script version 3.0, June 15, 2026 Script to generate images using prompts with Runway API v1 by useapi.net 🚀 For more details visit https://useapi.net/docs/api-runwayml-v1 Installation Instructions: ========================== You need Node.js v21 or newer installed to run this script. Download and install Node.js from: - Windows, macOS, Linux: https://nodejs.org/ After installation, verify by running the following commands in a terminal: node -v Running the Script: =================== Usage: node frames.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE] Replace API_TOKEN with your actual useapi.net API token, see https://useapi.net/docs/start-here/setup-useapi Replace EMAIL with configured Runway email account, see https://useapi.net/docs/start-here/setup-runwayml If optional PROMPTS_FILE not provided frames.json will be used. Example #1: -------- node frames.mjs user:1234-abcdefhijklmnopqrstuv my@email.com This command executes the script using API token user:1234-abcdefhijklmnopqrstuv with my@email.com Runway account email. Example #2: -------- node frames.mjs user:1234-abcdefhijklmnopqrstuv my@email.com frames.json This command executes the script using API token user:1234-abcdefhijklmnopqrstuv with my@email.com Runway account email and load prompts from frames.json file. */ import readline from 'node:readline'; import fs from 'fs/promises'; import path from 'path'; import { writeFile } from 'node:fs/promises'; import { Readable } from 'node:stream'; // Constants const RESULTS_FILE = 'frames_results.txt'; const ERRORS_FILE = 'frames_errors.txt'; const DEFAULT_PROMPTS_FILE = 'frames.json'; const SLEEP_429 = 5 * 1000; // in milliseconds const SLEEP_DOWNLOAD = 10 * 1000; // in milliseconds const MAX_CONCURRENT_JOBS = 3; // Number of parallel jobs const DEFAULT_DIVERSITY = 3; const DEFAULT_NUM_IMAGES = 4; // Frames returns 1 or 4 images per generation // Docs reference https://useapi.net/docs/api-runwayml-v1/get-runwayml-accounts const urlAccounts = 'https://api.useapi.net/v1/runwayml/accounts'; // Docs reference https://useapi.net/docs/api-runwayml-v1/post-runwayml-frames-create const urlFramesCreate = 'https://api.useapi.net/v1/runwayml/frames/create'; // Docs reference https://useapi.net/docs/api-runwayml-v1/get-runwayml-tasks-taskId const urlTasks = 'https://api.useapi.net/v1/runwayml/tasks/'; // Utility to sleep for given milliseconds const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); // Function to fetch configured Runway API accounts async function fetchAccounts(apiToken) { const response = await fetch(urlAccounts, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.error(`⛔ Error fetching accounts (HTTP ${response.status}): ${response.statusText}`); process.exit(1); } return response.json(); } async function submit(apiToken, url, body, index, text_prompt) { const createResponse = await fetch(url, { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiToken}` }, body }); const createBody = await createResponse.text(); if (createResponse.status == 200) { const json = JSON.parse(createBody); const { taskId } = json; if (taskId) { await fs.appendFile(RESULTS_FILE, `${taskId},#${index}:${text_prompt}\n`); console.log(`✅ taskId`, taskId); return 200; } else { const error = `No taskId found in HTTP 200 response`; console.log(`❓ ${error}`, createBody); await fs.appendFile(ERRORS_FILE, `${error},#${index}:${text_prompt}\n`); return 500; } } else { switch (createResponse.status) { case 429: console.log(`🔄️ Retry on HTTP ${createResponse.status}`); break; case 422: console.log(`🛑 MODERATED prompt`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${text_prompt}\n`); break; case 412: console.log(`🛑 account run out of credits`, createBody); break; default: console.log(`❗ FAILED with HTTP ${createResponse.status}`, createBody); await fs.appendFile(ERRORS_FILE, `${createResponse.status},#${index}:${text_prompt}\n`); } return createResponse.status; } } async function submitFrames(apiToken, email, prompt, index) { const { text_prompt, aspect_ratio, diversity, style, seed, num_images, imageAssetId1, imageAssetId2, imageAssetId3 } = prompt; const exploreMode = prompt?.exploreMode ?? true; console.log(`🚀 Frames » Prompt #${index} • account ${email} • exploreMode ${exploreMode ? 'ON' : 'OFF'}`); const body = JSON.stringify({ email, text_prompt, aspect_ratio, diversity: diversity ?? DEFAULT_DIVERSITY, num_images: num_images ?? DEFAULT_NUM_IMAGES, style, seed, exploreMode, imageAssetId1, imageAssetId2, imageAssetId3 }); return await submit(apiToken, urlFramesCreate, body, index, text_prompt); } // Function to download assets async function download(apiToken) { if (! await fileExists(RESULTS_FILE)) return; try { const resultsContent = await fs.readFile(RESULTS_FILE, 'utf8'); const lines = resultsContent.trim().split('\n'); for (const line of lines) { const [taskId, prompt] = line.split(','); console.log(`👉 ${taskId}`); while (true) { const response = await fetch(`${urlTasks}${taskId}`, { headers: { 'Accept': 'application/json', 'Authorization': `Bearer ${apiToken}` } }); if (!response.ok) { console.log(`🛑 Download failed ${taskId} (HTTP ${response.status}):\n${prompt}\n`, await response.text()); break; } const taskResponseBody = await response.json(); const { status, artifacts, error, progressRatio, estimatedTimeToStartSeconds } = taskResponseBody; if (status == 'FAILED') { console.error(`🛑 FAILED ${taskId} (${error}):\n${prompt}\n`); break; } if (status == 'SUCCEEDED') { for (let i = 0; i < artifacts.length; i++) { const url = artifacts[i].url; const extension = path.extname(new URL(url).pathname); const assetFileName = `${taskId}-${i}${extension}`; try { await fs.access(assetFileName); console.log(`⚠️ ${assetFileName} already exists. Skipping download.`); continue; } catch { // File does not exist, proceed with downloading } if (url) { console.log(`✅ Downloading ${url} to ${assetFileName}`); try { const assetResponse = await fetch(url); if (!assetResponse.ok) { console.error(`⛔ Unable to download ${taskId} (HTTP ${assetResponse.status}):\n${prompt}\n`, url); break; } const stream = Readable.fromWeb(assetResponse.body); await writeFile(assetFileName, stream); } catch (err) { console.error(`⛔ Error during download: ${err}`); } } else { console.error(`🛑 Unable to download ${taskId} status (${status} ${error}):\n${prompt}\n`); } } break; } console.log(`⌛ ${taskId} status (${status}) and is still in progress (${progressRatio * 100}%, seconds to start ${estimatedTimeToStartSeconds}), waiting…`); await sleep(SLEEP_DOWNLOAD); } } } catch (error) { console.log(`⛔ Error during download:`, error.stack || error); } } // Main function async function main() { const apiToken = process.argv[2]; const email = process.argv[3]; const promptFile = process.argv[4] || DEFAULT_PROMPTS_FILE; if (!apiToken || !email) { console.error('Usage: node frames.mjs <API_TOKEN> <EMAIL> [PROMPTS_FILE]'); process.exit(1); } console.info('Script v3.0'); console.info('Node version is: ' + process.version); try { if (await fileExists(RESULTS_FILE)) { let user_input; while (!['y', 'n'].includes(user_input)) { user_input = (await promptUser(`❔ ${RESULTS_FILE} file detected. Do you want to download the results now? (y/n): `))?.toLowerCase(); if (user_input == 'y') { await download(apiToken); await fs.unlink(RESULTS_FILE); } } } const start = new Date(); try { console.info('START EXECUTION', start); await execute(apiToken, email, promptFile); // Pass the promptFile to execute function } finally { console.info('COMPLETED', new Date()); console.info('EXECUTION ELAPSED', diffInMinutesAndSeconds(start, new Date())); } try { console.info('START DOWNLOAD', start); await download(apiToken); } finally { console.info('TOTAL ELAPSED', diffInMinutesAndSeconds(start, new Date())); } } catch (error) { console.error('⛔ Error during execution:', error.stack || error); } } // Modify the execute function to accept promptFile as a parameter async function execute(apiToken, email, promptFile) { const accounts = await fetchAccounts(apiToken); console.info(`Configured Runway API accounts (${Object.values(accounts).length}):`, Object.values(accounts).map(a => a.email).join(', ')); if (Object.values(accounts).length <= 0) { console.error(`⛔ No configured Runway accounts found. Please refer to https://useapi.net/docs/start-here/setup-runwayml`); process.exit(1); } if (!accounts[email]) { console.error(`⛔ Accounts ${email} not found. Please refer to https://useapi.net/docs/start-here/setup-runwayml`); process.exit(1); } if (accounts[email].error) { console.error(`⛔ Accounts ${email} has pending error. Please resolve and update account at https://useapi.net/docs/api-runwayml-v1/post-runwayml-accounts-email`); process.exit(1); } const promptData = await fs.readFile(promptFile, 'utf8'); const prompts = JSON.parse(promptData); console.log(`Total number of prompts to process`, prompts.length); let warnings = []; const paramsFrames = ['text_prompt', 'aspect_ratio', 'diversity', 'style', 'seed', 'exploreMode', 'num_images', 'imageAssetId1', 'imageAssetId2', 'imageAssetId3']; const invalidKeys = (supported, prompt) => Object.keys(prompt).filter(key => !key.startsWith('__') && !supported.includes(key)); for (let i = 1; i <= prompts.length; i++) { const prompt = prompts[i - 1]; const { text_prompt } = prompt; const notSupported = invalidKeys(paramsFrames, prompt); if (notSupported.length) warnings.push(`⚠️ Frames » following params not supported: ${notSupported.join(',')}. Prompt ${i}`); if (!text_prompt) warnings.push(`⚠️ Frames » please specify text_prompt. Prompt ${i}`); } if (warnings.length > 0) { warnings.forEach(warning => console.warn(warning)); console.error(`⛔ Execution stopped due to warnings.`); process.exit(1); } const queue = prompts.map((prompt, index) => ({ prompt, index })); const processQueue = async () => { const activeJobs = []; while (queue.length > 0) { if (activeJobs.length < MAX_CONCURRENT_JOBS) { const { prompt, index } = queue.shift(); const job = (async () => { while (true) { const responseCode = await submitFrames(apiToken, email, prompt, index + 1); if (responseCode == 429) { await sleep(SLEEP_429); } else if (responseCode == 412) { process.exit(1); } else { break; } } })(); activeJobs.push(job); job.finally(() => activeJobs.splice(activeJobs.indexOf(job), 1)); } else { await Promise.race(activeJobs); } } await Promise.all(activeJobs); }; await processQueue(); } // Utility function to check if a file exists async function fileExists(path) { try { await fs.access(path); return true; } catch { return false; } } // Function to prompt user input async function promptUser(query) { const rl = readline.createInterface({ input: process.stdin, output: process.stdout }); return new Promise((resolve) => rl.question(query, answer => { rl.close(); resolve(answer); })); } function diffInMinutesAndSeconds(date1, date2) { const diffInSeconds = Math.floor((date2 - date1) / 1000); return `${Math.floor(diffInSeconds / 60)} minutes ${diffInSeconds % 60} seconds`; }; main(); ``` </details> ### **Examples** At a vintage carnival in the evening, a poised woman stands by a striped carousel. She wears a polka-dot tea-length dress in vibrant red, cinched at the waist, showcasing her hourglass figure. With softly curled auburn hair pinned back by a ribbon and bright, wide eyes, she exudes a classic elegance. The warm carnival lights cast a gentle glow against her porcelain skin, illuminating her cheerful smile as merry-go-round animals spin behind her. ![](https://media.useapi.net/articles/2025-02-01-runway-frames-script/5.png) With a stern expression, the flamboyant estate owner brandishes a skull he claims belonged to a former servant. His refined manner is shattered by a cruel demonstration, illustrating his twisted worldview. The foreign gentleman and his partner observe, forcibly maintaining composure while clenching their fists in secret anger. ![](https://media.useapi.net/articles/2025-02-01-runway-frames-script/10.png) A horse-drawn stagecoach cuts through a snowy Wyoming pass under ominous gray skies. `B&W` ![](https://media.useapi.net/articles/2025-02-01-runway-frames-script/12.png) A rain-soaked street at night glimmers with neon reflections. A statuesque woman leans against a classic car, her figure wrapped in a sleek black trench coat and her keen cat-like eyes scanning her surroundings. Her iconic platinum-blonde hair frames a face with sharp cheekbones and red lips, while the city lights illuminate her pale complexion, creating a moody, suspenseful atmosphere as she clutches a hidden object under her coat. `High Contrast Cool` ![](https://media.useapi.net/articles/2025-02-01-runway-frames-script/1.png) In a bustling train station at dusk, a determined Caucasian woman with light freckled skin, vivid blue eyes, and shoulder-length blonde hair styled in a neat bob stands beside a vintage steam engine. Her stylish yet practical trench coat outlines her slender figure while the golden glow of sunset and the steam swirling around create a scene of cinematic suspense and understated allure. `High Contrast Warm` ![](https://media.useapi.net/articles/2025-02-01-runway-frames-script/8.png) Inside a bright 1950s-themed diner featuring vibrant neon signs and checkered floors, a slender, pale-skinned woman with a short black bob cut, wearing a white button-up shirt and cropped black pants, raises her arms as she prepares to dance. Opposite her stands a lean man with slicked-back dark hair and a thin black tie, clad in a sharp black suit, mimicking iconic dance moves. They sway together in a memorable twist contest, capturing a moment of spontaneous charm and playful rivalry. `Vivid Warm` ![](https://media.useapi.net/articles/2025-02-01-runway-frames-script/2.png) Gasping for air, the bride claws through earthen walls inside a narrow wooden coffin. Her face is streaked with sweat and dirt, yet determination burns in her eyes. Each hammering punch against the coffin lid echoes her desperation to escape what seems like a living burial. ![](https://media.useapi.net/articles/2025-02-01-runway-frames-script/9.png) At a candlelit masquerade ball in an elegant manor, a captivating Eastern European beauty with porcelain skin, sapphire eyes, and long, flowing dark hair with subtle auburn highlights glides through the scene. Dressed in a rich burgundy velvet gown detailed with intricate lace, she exudes mystery and refined sensuality, as the soft flicker of candlelight dances on her delicate features. `B&W Contrast` ![](https://media.useapi.net/articles/2025-02-01-runway-frames-script/6.png) A dramatic shootout erupts in the estate’s parlor, with bullets splintering ornate furniture and painting the walls. The freed man leaps over a fallen table, firing a revolver at the unsuspecting guards. In the midst of the chaos, the foreign gentleman’s calm presence and precise aim counter the swarm of attackers. ![](https://media.useapi.net/articles/2025-02-01-runway-frames-script/11.png) At a slim diner table with chipped cream-colored paint, six men in matching black suits, skinny ties, and sunglasses argue about tipping etiquette. The shortest of the group is particularly defensive, while the older gentleman with salt-and-pepper hair tries to keep the peace. Their camaraderie is fleeting, hinting at underlying tensions. ![](https://media.useapi.net/articles/2025-02-01-runway-frames-script/3.png) At a foggy, windswept harbor under an overcast sky, a resolute Nordic woman with fair, freckled skin, piercing ice-blue eyes, and platinum blonde hair arranged in a sophisticated braid stands tall. Dressed in a modern windbreaker with subtle Viking-inspired motifs, she faces the cold, crashing waves with a determined expression. The high-contrast cool lighting reinforces her heroic poise and inner strength. `High Contrast Cool` ![](https://media.useapi.net/articles/2025-02-01-runway-frames-script/7.png) A sweltering jungle hideout dotted with flickering torches. A resolute woman, clad in a sweat-dappled camisole and rugged shorts, presses her back against a crumbling wall. The parted neckline reveals a light sheen across her clavicles as she exhales in relief. A partner joins her, close enough that their ragged breathing mingles in the low firelight. Her eyes dart from the carved stone idol to those insistent hands that anchor her waist, capturing the forbidden thrill of danger interwoven with an intense, fleeting desire. `Dark Anime` ![](https://media.useapi.net/articles/2025-02-01-runway-frames-script/41.png) In a flamboyant carnival parade wending its way down narrow streets, a proud samba dancer twirls at the procession’s front. Her sequined costume, bursting with feather plumes in emerald and fuchsia, shimmers under strings of festival lanterns overhead. Bronze arms and legs move in hypnotic patterns, energizing the beating drums that match her joyful heartbeat. A bejeweled headdress sways precariously yet gracefully above her luminous smile. Towering confetti cannons explode in a shower of color, and the throng claps in unison, enthralled by her radiant spirit celebrating life’s vibrancy under the starry sky of the night festival. `Vivid Warm` ![](https://media.useapi.net/articles/2025-02-01-runway-frames-script/34.png) In a 1970s roller rink awash with neon strobes, a confident woman gracefully skates in hypnotic circles. She wears glittery spandex flares that hug her curves, and a matching halter top revealing toned arms. Her Afro hairstyle, voluminous and bold, casts soft shadows beneath the pulsing disco lights. She glides effortlessly across the checkered floor, weaving around smaller clusters of skaters in a rhythmic sway. The funky bassline resonates under the swirling disco ball overhead, each note fueling her smooth movements. Iridescent beads around her neck clack softly with her momentum, accenting her cool, unshakeable poise. `In Motion` ![](https://media.useapi.net/articles/2025-02-01-runway-frames-script/23.png) From the rafters overhead, blood drips onto the wooden floorboards, hinting at a hidden casualty. The bounty hunter steps back, revolver in hand, scanning the ceiling for the source. In this suffocating environment, paranoia pushes each person to suspect the others of orchestrating the carnage. ![](https://media.useapi.net/articles/2025-02-01-runway-frames-script/13.png) In a velvet-padded booth of a dimly lit speakeasy, a sharp-eyed lounge singer leans over a small round table. Her strappy black dress reveals the smooth curve of her back, each breath shifting the feathers nested in her short hairstyle. A single spotlight from the stage glances across her sequined neckline. Smoke drifts through the golden ambiance, and the hush from surrounding patrons hints at the layered tension—her gaze is locked in a private rendezvous, her entire posture promising illicit secrets hidden behind each melodic note. `B&W` ![](https://media.useapi.net/articles/2025-02-01-runway-frames-script/38.png) Related tutorials: [Runway Gen video via API](/docs/articles/runway-bash), [Nano Banana images via the Google Flow API](/docs/articles/google-flow-images-bash) and [Nano Banana image models compared](/docs/articles/google-flow-nano-banana-compare). ### Conclusion Visit our <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> or <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> for any support questions and concerns. The full runnable example is in the [`runway-api` GitHub repo](https://github.com/useapi/runway-api) — see the `frames/` example. === URL: https://useapi.net/docs/articles/seedance-2-api-pricing-es === Document URL: https://useapi.net/docs/articles/seedance-2-api-pricing-es --- layout: default title: "Precios de la API de Seedance 2.0 y 2.5: todas las rutas comparadas" seo_title: "Precios de la API de Seedance 2.0 y 2.5, comparados" description: "Cuánto cuesta un video de 5 segundos de Seedance 2.0 o 2.5 en la API oficial de ByteDance, en una docena de revendedores y en cuatro rutas de useapi.net, revisado el 13 de noviembre de 2026." keywords: [API de Seedance 2.0, API de Seedance 2.5, precios de Seedance, precio de Seedance 2.0, precio de Seedance 2.5, cuánto cuesta Seedance, costo de Seedance por video, costo de la API de Seedance, API de video de ByteDance, API de texto a video, Seedance 2.0 API, Seedance 2.5 API, Seedance pricing, Seedance 2.0 pricing, Seedance 2.5 pricing, Seedance 2.0 price, Seedance cost per video, Seedance API cost, ByteDance video API, BytePlus ModelArk Seedance, fal.ai Seedance, Replicate Seedance, PixVerse Seedance, Runway Seedance, Dreamina Seedance, text to video API] image: /assets/images/articles/seedance-2-api-pricing-2026-10.jpg parent: Articles nav_exclude: true lang: es translation_key: seedance-2-pricing date: 2026-07-21 repo: https://github.com/useapi/seedance-2-api last_modified: 2026-11-18 nav_order: 90 --- ## Precios de la API de Seedance 2.0 y 2.5: todas las rutas comparadas {: .no_toc #seedance-20-and-25-api-pricing-every-route-compared } 13 min de lectura • 21 de julio de 2026 (18 de noviembre de 2026) ## Índice {: .no_toc .text-delta #table-of-contents } ### Introducción Un video Seedance 2.0 de 5 segundos en 1080p cuesta US$1,87 en la API oficial de ByteDance, y la tarifa por video más baja que verificamos es de US$1,12 con la ruta PixVerse de useapi.net, con un plan Ultra anual (US$1,49 en el mensual), o US$1,44 con un plan Premium anual (US$1,80 en el mensual), sin ningún revendedor por debajo de ella (el más barato, Segmind, cobra US$1,97). Seedance 2.5 es otra historia. A US$2,84 por video en 1080p, la tarifa de la propia ByteDance es más baja que la de todos los revendedores y todos los planes mensuales que encontramos, y solo los planes anuales quedan apenas por debajo: PixVerse Ultra (US$2,32), y PixVerse Premium o Runway Max (US$2,72). El 13 de noviembre de 2026 (la ruta PixVerse, de nuevo el 15 de noviembre) volvimos a leer los precios de los dos canales oficiales de ByteDance y de una docena de proveedores de terceros en sus páginas en vivo, recalculamos nuestras cuatro rutas con las tarifas de créditos actuales y normalizamos todo a una sola unidad: el costo en dólares de un video de texto a video de 5 segundos, sin video de entrada. El panorama cambió desde que publicamos este artículo en julio. PixVerse cambió los precios de Seedance y terminó el descuento de sus planes Pro y Premium, lo que subió su ruta de US$1,20 a US$1,80 por video en un plan mensual, ByteDance lanzó Seedance 2.5 con una tarifa por token cerca de un 50% más alta que la de 2.0, y la mayoría de los revendedores sacó después sus propios niveles de 2.5. Conviene ser claros sobre nuestra posición. useapi.net es una capa en la que traes tu propia cuenta, no un revendedor oficial de ByteDance. Controlamos tu propia cuenta de [PixVerse](/docs/api-pixverse-v2), [Runway](/docs/api-runwayml-v1), [Dreamina](/docs/api-dreamina-v1) o [MiniMax](/docs/api-minimax-v1) con una sola API REST, así que gastas los créditos de consumidor de esas plataformas en lugar de la tarifa medida de su API para desarrolladores. Cada cifra de abajo lleva su fecha y su fuente, y los precios de este mercado cambian cada mes, así que vuelve a revisarlos antes de comprometer tu gasto. Una sola suscripción de useapi.net ejecuta Seedance 2.0 y 2.5 en las cuatro rutas de abajo, con el plan de PixVerse, Runway, Dreamina o MiniMax que ya tienes, e incluye todas las demás API del sitio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03?client_reference_id={{ page.url | slugify | default: 'home' }}){: .btn .btn-purple .mr-2 .mb-3 } [Cómo se comparan las cuatro rutas](#four-ways-to-run-seedance-20-through-useapinet) ### Precios oficiales de la API de Seedance 2.0 y 2.5 ByteDance vende Seedance por dos canales oficiales: [BytePlus ModelArk](https://docs.byteplus.com/en/docs/ModelArk/1544106) a nivel internacional y [Volcano Engine](https://www.volcengine.com/docs/82379/1544106) en China. Los dos cobran por millón de tokens, y la cantidad de tokens de un video es `width × height × 24fps × seconds ÷ 1024`. Un video de 5 segundos en 1080p son 243.000 tokens. Seedance 2.0 cobra US$7,7 por millón en 1080p, así que ese video cuesta US$1,87. Seedance 2.5 cobra US$11,7 por millón en 1080p, así que el mismo video cuesta US$2,84. Normalizado, según la página de precios de BytePlus (leída el 13 de noviembre de 2026, en dólares estadounidenses): | Resolución | Seedance 2.0, 5s | Seedance 2.0, 10s | Seedance 2.5, 5s | Seedance 2.5, 10s | |:-----------|-----------------:|------------------:|-----------------:|------------------:| | 480p | $0,35 | $0,70 | $0,51 | $1,03 | | 720p | $0,76 | $1,51 | $1,16 | $2,31 | | 1080p | $1,87 | $3,74 | $2,84 | $5,69 | | 4K | $3,89 | $7,78 | $4,57 | $9,14 | Seedance 2.5 llegó a 4K en BytePlus el 16 de noviembre de 2026, a US$4,57 por un video de 5 segundos sin video de entrada, hace videos de hasta 30 segundos frente a los 15 de 2.0, y acepta hasta 50 referencias (30 imágenes, 10 videos, 10 clips de audio). Un video 2.5 completo de 30 segundos en 1080p cuesta unos US$17. Seedance 2.0 Fast y Mini siguen siendo más baratos y siguen limitados a 720p: un video de 5 segundos en 720p cuesta US$0,60 en Fast y US$0,38 en Mini. El nuevo Seedance 2.5 Flash también se queda en 720p, a US$0,76 por un video de 5 segundos en 720p, y BytePlus lo abre a llamadas de API el 15 de noviembre de 2026. El audio va incluido sin costo extra. Volcano cobra 2.5 a ¥77 por millón de tokens en 1080p, pero exige verificación de nombre real y facial china, así que en la práctica solo sirve dentro de China. El precio de lista no es todo el costo. Activar Seedance en BytePlus requiere unos US$30 por adelantado: un [paquete de recursos](https://docs.byteplus.com/en/docs/ModelArk/2191775) prepagado (los más pequeños cuestan US$30,10 para 2.0 y US$32 para 2.5, no son reembolsables y vencen a los 90 días) o la recarga de saldo de US$30 que recomienda BytePlus. Las cuentas individuales están limitadas a 3 tareas simultáneas (180 solicitudes por minuto), y el 4K está limitado a una sola tarea simultánea para todos. Nada de eso hace que la API oficial sea un mal negocio. Solo fija la referencia con la que hay que medir cada alternativa. ### Cuatro formas de ejecutar Seedance 2.0 con useapi.net Un solo token de useapi.net ejecuta Seedance 2.0 en cuatro plataformas, con el plan de cuenta que ya pagas. Los costos de abajo son el costo del plan por video de 5 segundos en 1080p (en dólares estadounidenses), calculado con las tarifas de créditos y los precios de los planes de nuestra documentación. | Ruta | Modelos Seedance | 5s 1080p, plan mensual | 5s 1080p, plan anual | Destaca por | |:------|:----------------|-----------------------:|----------------------:|:---------------| | [PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) | 2.5, 2.5 Flash, 2.5 Draft, 2.0, Fast, Mini | $1,80 | $1,44 | 2.0 en 1080p y 4K más baratos ($1,49 y $1,12 con Ultra), rostros humanos reales | | [Dreamina](/docs/api-dreamina-v1/post-dreamina-videos) | 2.5, 2.5 Flash, 2.0, Fast, Mini, 1.5 Pro, familia 1.0 | ~$1,83–1,87 | ~$1,78–1,81 | Seedance 2.5 con rostros reales y videos largos, la mayor variedad de modelos | | [MiniMax](/docs/api-minimax-v1/post-minimax-videos-create) | 2.0, Fast, Mini | $2,00 | $1,70 | 4K y un flujo completo con imágenes de referencia | | [Runway](/docs/api-runwayml-v1/post-runwayml-videos-create) | 2.5, 2.0, Fast, Mini | $2,00 | $1,60 | rostros reales, moderación más ligera que Dreamina | La ruta PixVerse cobra Seedance 2.0 a 90 créditos por segundo en 1080p, así que un video de 5 segundos son 450 créditos. En el plan Premium de US$60/mes (US$0,004 por crédito) eso es US$1,80, y en Premium con facturación anual (US$0,0032 por crédito) es US$1,44. Los créditos de Ultra cuestan más, pero en Ultra PixVerse descuenta un 50% en Seedance 2.0, salvo que la solicitud envíe `relax_mode: false`, lo que deja un video en US$1,49, o US$1,12 con facturación anual (Ultra cuesta US$199 al mes por 30.000 créditos, a 15 de noviembre de 2026). Al precio completo, que es lo que paga una solicitud con `relax_mode: false`, un video en Ultra cuesta US$2,99. PixVerse también llega a 2160p (4K) en Seedance 2.0, a US$4,00 por 5 segundos en Premium, o US$3,20 con facturación anual, y US$3,32 o US$2,48 con Ultra: el 4K más barato que encontramos. En julio esta ruta costaba US$1,20 por video. Desde entonces PixVerse cambió los precios de la familia Seedance y terminó el descuento de Pro y Premium que tenía, que es el mayor cambio de esta actualización ([tablas de costos de PixVerse](/docs/api-pixverse-v2)). La verdadera ventaja de la ruta Dreamina es Seedance 2.5: acepta rostros reales y hace videos largos de 31 a 180 segundos en un solo job, algo que la API oficial no hace ([precios de Seedance 2.5](#seedance-25-pricing)). En Seedance 2.0 en 1080p queda prácticamente empatada con la API oficial. A 57 créditos por segundo en un plan Advanced de la región de Canadá, un video de 5 segundos cuesta unos US$1,83 con facturación mensual (C$109,99 por 11.997 créditos) y US$1,81 con facturación anual (C$1.299,99), frente a US$1,87. Un plan Advanced de EE. UU. lo ejecuta a 41 créditos por segundo, unos US$1,87 con facturación mensual (US$79 por 8.645 créditos) y US$1,78 con facturación anual (US$900). Las dos regiones hacen 1080p y 4K, y la familia 2.0 de Dreamina rechaza rostros humanos reales. Los precios de los planes y las tarifas de créditos se volvieron a leer el 12 de noviembre de 2026, convertidos a un tipo de cambio CAD/USD de 0,7023 ([calculadora de costos de Dreamina](/docs/start-here/setup-dreamina#cost-calculator)). La ruta MiniMax cobra Seedance 2.0 a 50 créditos por segundo en 1080p, sin cambios desde julio, que es el descuento de 50% de MiniMax en Seedance, presentado como oferta por tiempo limitado (a 12 de noviembre de 2026). MiniMax también cambió los precios de sus planes. El plan Master de US$89 (10.500 créditos) deja un video en US$2,12, el plan Max de US$216 (27.000 créditos) en US$2,00, y Master con facturación anual en US$1,70, con 4K a US$3,39 en ese plan anual. La ruta Runway ahora también tiene una tarifa publicada. Su Seedance 2.0 cuesta 40 créditos por segundo en 1080p, es decir, US$2,00 por video en el plan Max de US$95 de Runway y US$1,60 con facturación anual ([calculadora de costos de Runway](/docs/api-runwayml-v1)). El `exploreMode` heredado de Runway todavía ejecuta Seedance en 480p y 720p sin gastar créditos en las cuentas Unlimited antiguas que ya tienen Explore mode activado, hasta que Runway pase esas cuentas a Max el 30 de noviembre de 2026. Runway ya no lo activa en cuentas nuevas, y es lento: un video a la vez, unos 10 a 15 minutos cada uno. Tómalo como un extra si ya lo tienes, no como una razón para elegir Runway. Estos son costos del plan por video, y los más baratos suponen un compromiso anual que realmente aprovechas. Premium con facturación anual son US$576 por adelantado por 15.000 créditos al mes, unos 33 videos en 1080p al mes, y Ultra con facturación anual son US$1.788 por 30.000 créditos al mes, unos 133 videos. Vale la pena nombrar las desventajas. Nuestras rutas automatizan cuentas de consumidor, así que la concurrencia depende de la cuenta (normalmente de 5 a 10 jobs en paralelo, frente a los límites por clave de la API oficial), y las plataformas cambian sus precios sin aviso, como acaba de hacer PixVerse. A cambio obtienes un costo por video por debajo del oficial en 2.0 con planes anuales (y con PixVerse mensual), sin paquete prepagado, y un solo token para las cuatro plataformas. ### Precios de Seedance 2.5 Seedance 2.5 funciona en tres de nuestras cuatro rutas: [PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4), [Dreamina](/docs/api-dreamina-v1/post-dreamina-videos) y [Runway](/docs/api-runwayml-v1/post-runwayml-videos-create). MiniMax no lo ofrece. En 2.5 la mayor diferencia es lo que la API oficial no hace. La propia [guía de Seedance 2.5](https://docs.byteplus.com/en/docs/modelark/seedance-2-5) de ByteDance dice que 2.5 "does not support directly uploading reference images or videos containing real human faces" (no admite subir directamente imágenes o videos de referencia con rostros humanos reales), y la API oficial se detiene en 30 segundos por video. La [ruta Dreamina acepta rostros reales en 2.5](/docs/api-dreamina-v1/post-dreamina-videos) directamente y suma un modo de video largo de 31 a 180 segundos en un solo job, además de edición de video, y en cuentas de Canadá genera 2.5 en 4K por unos US$4,15 por video de 5 segundos en el plan Advanced de Canadá, por debajo de los US$4,57 oficiales. La [ruta Runway](/docs/api-runwayml-v1/post-runwayml-videos-create) también acepta rostros reales en Seedance, y no hay que comprar un paquete prepagado de unos US$30 antes del primer video. En 1080p, nuestras rutas PixVerse y Runway también cuestan menos por video que la tarifa de la propia ByteDance en un plan anual. Un video de 5 segundos, sin video de entrada (en dólares estadounidenses): | Ruta | 1080p, 5 s | Duración máxima | |:------|-----------:|:-----------| | [PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) *(Ultra, facturación anual)* | $2,32 | 30s | | [PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) *(Premium, facturación anual)* | $2,72 | 30s | | [Runway](/docs/api-runwayml-v1/post-runwayml-videos-create) *(Max, facturación anual)* | $2,72 | 30s | | [BytePlus oficial](https://docs.byteplus.com/en/docs/ModelArk/1544106) | $2,84 | 30s | PixVerse cobra 2.5 a 170 créditos por segundo en 1080p (US$0,0032 por crédito en Premium con facturación anual), y Ultra descuenta un 45%: 468 créditos por video a US$0,00497 por crédito con facturación anual (US$3,10 en un plan Ultra mensual). Runway cobra 68 créditos por segundo en 1080p (US$0,008 por crédito en Max con facturación anual, US$76 al mes por 9.500 créditos, a 13 de noviembre de 2026). Las tarifas anuales suponen que usas los créditos del plan. PixVerse ahora también genera Seedance 2.5 en 4K (2160p), a 286 créditos por segundo (a 15 de noviembre de 2026). Un video 4K de 5 segundos son 1.430 créditos, o 787 con el descuento de Ultra, lo que da US$3,91 en Ultra con facturación anual, frente a US$4,57 en la propia API de ByteDance (a 18 de noviembre de 2026). ### La brecha de los rostros reales Tanto Seedance 2.0 como 2.5 rechazan en la API oficial las imágenes y los videos de referencia que contienen rostros humanos reales, salvo que el rostro venga de un resultado reciente del propio modelo, de un personaje digital predefinido o de un recurso de persona real verificado. Trabajar con referencias de personas reales a escala exige los "Advanced Creation Rights" empresariales de ByteDance: [US$14.000 al año o US$1.400 al mes](https://docs.byteplus.com/en/docs/modelark/2377608) por un millón de recursos, US$42.000 al año por cinco millones, y se requiere verificación de empresa. Nuestras rutas suavizan esto en cuatro puntos. La [ruta PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) acepta rostros humanos reales en Seedance 2.0, la [ruta Runway](/docs/api-runwayml-v1/post-runwayml-videos-create) documenta compatibilidad con rostros reales en Seedance y en general una moderación más ligera que Dreamina, la [ruta MiniMax](/docs/api-minimax-v1/post-minimax-videos-create) acepta rostros reales en imágenes de referencia (los videos de referencia con rostros reconocibles se siguen moderando), y la [ruta Dreamina](/docs/api-dreamina-v1/post-dreamina-videos) acepta retratos fotográficos en Seedance 2.5, aunque no en su familia 2.0. En publicidad, UGC y flujos de creadores que giran en torno a una persona real, esa diferencia pesa más que unos centavos por video, y no exige un contrato empresarial. ### Precios de la API de Seedance en los revendedores La mayoría de los proveedores de terceros de Seedance revenden la API de la propia ByteDance con un margen encima. Este es Seedance 2.0 a 5 segundos y 1080p, con cada precio de terceros leído en la página en vivo del proveedor el 13 de noviembre de 2026 (en dólares estadounidenses): | Proveedor | 5s 1080p | Notas | |:-------|---------:|:------| | [useapi.net (ruta PixVerse)](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) | $1,12–1,80 | créditos de cuenta de consumidor, de Ultra anual a Premium mensual | | [useapi.net (ruta Runway)](/docs/api-runwayml-v1/post-runwayml-videos-create) | $1,60–2,00 | plan Max, anual o mensual | | [useapi.net (ruta MiniMax)](/docs/api-minimax-v1/post-minimax-videos-create) | $1,70–2,12 | de Master anual a Master mensual ($2,00 en Max mensual) | | [useapi.net (ruta Dreamina)](/docs/api-dreamina-v1/post-dreamina-videos) | ~$1,78–1,87 | cuentas de EE. UU. o Canadá, Advanced anual o mensual, leído el 12 de noviembre de 2026 | | [BytePlus oficial](https://docs.byteplus.com/en/docs/ModelArk/1544106) | $1,87 | la referencia, igualada exactamente por el passthrough de OpenRouter | | [Segmind](https://www.segmind.com/models/seedance-2.0/pricing) | $1,97 | por encima del oficial desde noviembre ($8,105 por millón de tokens en 1080p) | | [RunComfy](https://www.runcomfy.com/models/bytedance/seedance-v2/pro) | $2,00 | $0,40 por segundo, bajó de $0,55 en julio | | [EachLabs](https://www.eachlabs.ai/bytedance/seedance-2-0/bytedance-seedance-2-0-text-to-video) | $2,22 | unos $0,444 por segundo, bajó de $0,60 | | [Replicate](https://replicate.com/bytedance/seedance-2.0) | $2,25 | insignia de modelo "Official", $0,45 por segundo de salida | | [Poyo.ai](https://poyo.ai/models/seedance-2) | $2,25 | $0,45 por segundo | | [EvoLink](https://evolink.ai/seedance-2-0) | $2,48 | $0,497 por segundo | | [PiAPI](https://piapi.ai/seedance-2-0) | $2,50 | $0,50 por segundo | | [Kie.ai](https://kie.ai/seedance-2-0) | $2,55 | $0,51 por segundo | | [Atlas Cloud](https://www.atlascloud.ai/models/bytedance/seedance-2.0/text-to-video) | $2,74 | $2,20 con una promoción de 20% | | [WaveSpeedAI](https://wavespeed.ai/models/bytedance/seedance-2.0/text-to-video) | $3,00 | $0,60 por segundo | | [fal.ai](https://fal.ai/models/bytedance/seedance-2.0/text-to-video) | $3,41 | la opción por defecto del mercado, y todavía la más cara | Vale la pena detenerse en esa última fila. fal.ai es donde muchos desarrolladores buscan Seedance primero, y a US$0,682 por segundo cobra cerca de un 82% más que la tarifa de la propia ByteDance por el mismo modelo. Hace lo mismo con 2.5, donde su video en 720p cuesta US$2,31 frente a los US$1,16 oficiales y su video en 1080p cuesta unos US$5,69 frente a US$2,84. Seedance 2.5 tiene su propio grupo de revendedores. Replicate y OpenRouter trasladan exactamente la tarifa oficial (US$1,16 en 720p, US$0,51 en 480p), pero llegan solo a 720p, y [RunComfy](https://www.runcomfy.com/models/bytedance/seedance-2.5/text-to-video) ahora vende 2.5 solo en 720p (US$1,53 por 5 segundos durante su promoción actual de 35%). Entre los proveedores que venden 2.5 en 1080p, [Poyo](https://poyo.ai/models/seedance-2-5) (US$2,85), [Segmind](https://www.segmind.com/models/seedance-2.5/pricing) (US$2,99) y [Atlas Cloud](https://www.atlascloud.ai/models/bytedance/seedance-2.5/text-to-video) (US$2,98 con su promoción de 20%, US$3,73 sin ella) quedan a pocos puntos porcentuales del oficial, [EachLabs](https://www.eachlabs.ai/bytedance/seedance-2-5/bytedance-seedance-2-5-text-to-video) (US$3,28) está cerca de un 15% por encima, y [EvoLink](https://evolink.ai/seedance-2-5) (US$3,70), [Kie.ai](https://kie.ai/seedance-2-5) (US$3,95), [PiAPI](https://piapi.ai/seedance-2-5) (US$4,00) y [WaveSpeedAI](https://wavespeed.ai/models/bytedance/seedance-2.5/text-to-video) (US$4,50) están entre un 30 y un 60% por encima. También verás precios de lista que parecen mucho más bajos que el oficial. Cada uno que investigamos resultó ser otra cosa que un video estándar más barato. Algunos patrones a vigilar cuando un precio parece demasiado bueno: - Variantes "turbo" o "aceleradas" que no son el modelo estándar: un proveedor ofrece un video Seedance 2.5 de 5 segundos en 1080p a US$1,10 con un nombre de modelo turbo que ByteDance no publica, mientras su Seedance 2.5 estándar cuesta US$4,50 en el mismo sitio. - Precios en 720p cuando querías 1080p: varias páginas de "el Seedance más barato", y los listados de Seedance 2.5 en Replicate y OpenRouter, no tienen ningún nivel de 1080p. - Precios de 2.0 en una página sobre 2.5: Seedance 2.5 cuesta cerca de la mitad más por token, así que un precio de "Seedance" sin número de versión no es comparable. - Créditos sin valor en dólares publicado: si una página da el precio de las generaciones en créditos pero nunca dice cuánto cuesta un crédito, no puedes compararlo, y normalmente esa es la idea. Nada de esto significa que esos proveedores sean deshonestos: significa que la versión, la resolución y la letra pequeña tienen que coincidir antes de que una comparación signifique algo. ### Cómo llamar a la API de Seedance Cada precio de arriba está a una llamada REST de distancia. Genera un video Seedance 2.0 en 1080p con la ruta PixVerse: ```bash curl --location 'https://api.useapi.net/v2/pixverse/videos/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="seedance-2.0"' \ --form 'prompt="A lone lighthouse on a storm-battered cliff at dusk, waves exploding against the rocks, beam sweeping through the rain, cinematic wide shot."' \ --form 'quality="1080p"' \ --form 'duration="5"' \ --form 'aspect_ratio="16:9"' ``` La misma llamada ejecuta Seedance 2.5 si cambias `model` a `seedance-2.5`, con `duration` entre 4 y 30. O, si tu cuenta de Runway todavía tiene Explore mode (Runway ya no lo ofrece en cuentas nuevas y lo termina para las cuentas Unlimited antiguas el 30 de noviembre de 2026), la misma forma se ejecuta sin créditos en 720p agregando `exploreMode`, un video lento a la vez: ```bash curl --location 'https://api.useapi.net/v1/runwayml/videos/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="seedance-2"' \ --form 'text_prompt="A lone lighthouse on a storm-battered cliff at dusk, waves exploding against the rocks, beam sweeping through the rain, cinematic wide shot."' \ --form 'resolution="720p"' \ --form 'duration="5"' \ --form 'exploreMode="true"' ``` Las dos devuelven un id de job para consultar (o un webhook `replyUrl` cuando el video está listo). El conjunto completo de parámetros (imágenes de referencia, primer y último fotograma, relaciones de aspecto y audio) está en la página de cada endpoint enlazada en las tablas de arriba. ### ¿Qué ruta conviene usar para Seedance 2.0 o 2.5? - Seedance 2.0 en 1080p más barato: la [ruta PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) en un plan anual, US$1,12 con Ultra o US$1,44 con Premium. Sin compromiso anual, PixVerse mensual (US$1,49 con Ultra, US$1,80 con Premium) sigue por debajo de los US$1,87 oficiales, y todos los revendedores están por encima. - 4K más barato: la ruta PixVerse a US$2,48 con Ultra anual o US$3,20 con Premium anual, y después [MiniMax](/docs/api-minimax-v1/post-minimax-videos-create) a US$3,39 anual, todas por debajo de los US$3,89 oficiales. - Seedance 2.5 en 1080p más barato: la [ruta PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) en Ultra con facturación anual, US$2,32 por video de 5 segundos, y después PixVerse Premium o la [ruta Runway](/docs/api-runwayml-v1/post-runwayml-videos-create) en Max, ambas con facturación anual, a US$2,72, frente a US$2,84 en la API oficial. - Seedance 2.5 en 4K más barato: la [ruta PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) en Ultra con facturación anual, US$3,91 por video de 5 segundos, y después la [ruta Dreamina](/docs/api-dreamina-v1/post-dreamina-videos) en el plan Advanced de Canadá, a unos US$4,15, frente a los US$4,57 oficiales. - Seedance 2.5 con rostros humanos reales, o videos de más de 30 segundos: la [ruta Dreamina](/docs/api-dreamina-v1/post-dreamina-videos). - Rostros humanos reales en Seedance 2.0: la ruta [PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4), [MiniMax](/docs/api-minimax-v1/post-minimax-videos-create) o [Runway](/docs/api-runwayml-v1/post-runwayml-videos-create). - Seedance 1.5 Pro o 1.0: la ruta Dreamina, la única que ofrece la familia 1.x. BytePlus retiró 1.5 Pro de su propia API. ### Ejemplos Resultados reales de Seedance 2.0 en cada ruta, tomados de nuestras entradas del blog: el mismo modelo, ejecutado en distintas plataformas. Tres de ellos usan rostros humanos reales, el flujo que la API oficial reserva para un contrato empresarial. PixVerse · Seedance 2.0 (Standard), 1080p: un rostro real tomado de una foto, insertado en un video de referencia y con voz a partir de un clip de audio de referencia, todo en una sola solicitud omni. De [PixVerse Seedance 2.0: Mini vs Fast vs Standard](/blog/260626a). <video poster="https://media.useapi.net/blog/2026-06-26-260626a/omni-standard-1080p-4s-9x16-swap-poster.jpg" src="https://media.useapi.net/blog/2026-06-26-260626a/omni-standard-1080p-4s-9x16-swap.mp4" style="width: 100%; max-width: 420px;" controls type="video/mp4" preload="metadata">Your browser does not support the video element.</video> También en YouTube: [Seedance 2.0 Omni: Photo + Reference Video + Audio → One Clip (Mini vs Fast vs Standard)](https://youtube.com/shorts/apUc3lXrY_4). MiniMax · Seedance 2.0 (Standard), 1080p: el mismo flujo omni con rostro real en la ruta MiniMax. De [MiniMax Seedance 2.0: Standard vs Fast vs Mini](/blog/260626b). <video poster="https://media.useapi.net/blog/2026-06-26-260626b/std-1080-5s-nowm-poster.jpg" src="https://media.useapi.net/blog/2026-06-26-260626b/std-1080-5s-nowm.mp4" style="width: 100%; max-width: 420px;" controls type="video/mp4" preload="metadata">Your browser does not support the video element.</video> Runway · Seedance 2.0, 15 segundos, 9:16: un rostro real animado en la ruta Runway, que aplica una moderación más ligera a personas reales. De [Seedance 2.0: Using Real Faces](/blog/260415). <video poster="https://media.useapi.net/articles/2024-08-11-runway-bash/runway-original-result-poster.jpg" src="https://media.useapi.net/articles/2024-08-11-runway-bash/runway-original-result.mp4" style="width: 100%; max-width: 420px;" controls type="video/mp4" preload="metadata">Your browser does not support the video element.</video> Dreamina · Seedance 2.0, texto a video con sincronización de labios solo a partir del prompt. De [Dreamina: Seedance 2.0 Video Generation](/blog/260402). <video poster="https://media.useapi.net/blog/2026-04-02-260402/seedance-2.0-prompt-9-16-poster.jpg" src="https://media.useapi.net/blog/2026-04-02-260402/seedance-2.0-prompt-9-16.mp4" style="width: 100%; max-width: 420px;" controls type="video/mp4" preload="metadata">Your browser does not support the video element.</video> Tutoriales relacionados: [video Seedance 2.0 con la API de Dreamina](/docs/articles/dreamina-bash), [alternativas a la API de Sora 2](/docs/articles/sora-2-api-alternatives) y [video PixVerse V6 con la API de PixVerse](/docs/articles/pixverse-demo). ## Preguntas frecuentes **¿useapi.net es una API oficial de Seedance?** No. useapi.net es una capa REST que automatiza tu propia cuenta de [PixVerse](/docs/api-pixverse-v2), [Runway](/docs/api-runwayml-v1), [Dreamina](/docs/api-dreamina-v1) o [MiniMax](/docs/api-minimax-v1), y cada una de ellas ejecuta Seedance. Gastas los créditos de consumidor de esas plataformas en lugar de la tarifa medida de la API para desarrolladores de ByteDance. **¿Cuánto cuesta Seedance 2.0 por video?** Con useapi.net, un video de 5 segundos en 1080p cuesta US$1,12 en la [ruta PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) con un plan Ultra anual, o US$1,44 con Premium anual (US$1,80 en el mensual), frente a US$1,87 en la API oficial de ByteDance. La API oficial cobra US$0,35 en 480p, US$0,76 en 720p, US$1,87 en 1080p y US$3,89 en 4K por un video de 5 segundos, a 13 de noviembre de 2026. Consulta [la tabla de precios oficiales](#official-seedance-20-and-25-api-pricing). **¿Cuánto cuesta Seedance 2.5?** Con useapi.net, Seedance 2.5 funciona con rostros reales y con videos de más de 30 segundos, algo que la API oficial restringe: la [ruta Dreamina](/docs/api-dreamina-v1/post-dreamina-videos) acepta fotos reales y hace de 31 a 180 segundos en un solo job. En 1080p, un video de 5 segundos cuesta US$2,32 en PixVerse Ultra y US$2,72 en PixVerse Premium o Runway, con facturación anual, frente a US$2,84 en la API oficial de ByteDance (a noviembre de 2026). Consulta [precios de Seedance 2.5](#seedance-25-pricing). **¿Cuál es la forma más barata de ejecutar Seedance 2.0 en 1080p?** De todo lo que verificamos el 13 y el 15 de noviembre de 2026, la [ruta PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4): US$1,12 por video de 5 segundos con un plan Ultra anual, o US$1,44 con Premium anual. Sin compromiso anual, PixVerse mensual (US$1,49 con Ultra, US$1,80 con Premium) es lo más barato, por debajo de los US$1,87 oficiales de ByteDance, y ningún revendedor está por debajo (Segmind, el más barato, cobra US$1,97). Consulta [la tabla del mercado](#seedance-api-pricing-across-resellers). **¿Puedo generar videos de Seedance con rostros humanos reales?** Sí, con useapi.net: las rutas [PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4), [Runway](/docs/api-runwayml-v1/post-runwayml-videos-create) y [MiniMax](/docs/api-minimax-v1/post-minimax-videos-create) aceptan rostros reales en 2.0 (MiniMax en imágenes de referencia), y la [ruta Dreamina](/docs/api-dreamina-v1/post-dreamina-videos) los acepta en 2.5. La API oficial restringe las referencias con rostros reales, tanto en 2.0 como en 2.5, a recursos verificados o a un contrato empresarial desde US$14.000 al año. **¿Cómo cobra useapi.net menos que la propia API de ByteDance?** En Seedance 2.0, los planes de consumidor de PixVerse (mensual o anual), Runway, Dreamina y MiniMax (anual) cobran la misma generación por debajo de la tarifa medida para desarrolladores, y useapi.net automatiza una de esas cuentas por REST, con una sola [suscripción](/docs/subscription) para todos los servicios. En Seedance 2.5 en general no es así: la tarifa oficial es más baja salvo frente a un plan anual de PixVerse o Runway en 1080p, y nuestras rutas ganan en cambio con rostros reales, videos más largos y sin paquete prepagado. **¿Son reales los precios de Seedance de menos de un dólar que veo en otros sitios?** Normalmente no para un video estándar en 1080p. Suelen ser tarifas de 720p, precios de 2.0 en una página de 2.5, planes de tarifa plana subsidiados, variantes "turbo" destiladas o créditos sin valor en dólares publicado. Consulta [la sección del mercado](#seedance-api-pricing-across-resellers). --- ¿Listo para probarlo? Toda la comparación es un solo script: [github.com/useapi/seedance-2-api](https://github.com/useapi/seedance-2-api) envía un prompt a las cuatro rutas e imprime el costo y la velocidad de cada una, junto con una calculadora de precios que puedes ejecutar sin ninguna cuenta. Después elige una ruta ([PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) para el Seedance 2.0 en 1080p más barato, [Dreamina](/docs/api-dreamina-v1/post-dreamina-videos) para Seedance 2.5 con rostros reales y videos largos), conecta la cuenta, y una [suscripción a useapi.net](/docs/subscription) controla las cuatro con un solo token. Los precios de este artículo estaban vigentes el 13 de noviembre de 2026, y este mercado cambia cada mes, así que confirma la tarifa en vivo antes de escalar. #### Publicado también en {: .no_toc #cross-posted } También publicado en [dev.to](https://dev.to/useapi/seedance-20-api-pricing-the-cheapest-ways-to-run-it-compared-4kno){:rel="nofollow"} (en inglés). ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/seedance-2-api-pricing-id === Document URL: https://useapi.net/docs/articles/seedance-2-api-pricing-id --- layout: default title: "Harga API Seedance 2.0 dan 2.5: Semua Jalur, Dibandingkan" seo_title: "Harga API Seedance 2.0 dan 2.5: Semua Jalur Dibandingkan" description: "Berapa biaya video Seedance 2.0 atau 2.5 berdurasi 5 detik di API resmi ByteDance, selusin reseller dan empat jalur useapi.net, dicek ulang 13 November 2026." keywords: [harga API Seedance 2.0, harga API Seedance 2.5, harga Seedance, harga Seedance 2.0, harga Seedance 2.5, biaya per video Seedance, biaya API Seedance, API Seedance murah, API video ByteDance, Seedance 2.0 API, Seedance 2.5 API, Seedance pricing, Seedance 2.0 pricing, Seedance 2.5 pricing, Seedance 2.0 price, Seedance cost per video, Seedance API cost, ByteDance video API, BytePlus ModelArk Seedance, fal.ai Seedance, Replicate Seedance, PixVerse Seedance, Runway Seedance, Dreamina Seedance, text to video API] image: /assets/images/articles/seedance-2-api-pricing-2026-10.jpg parent: Articles nav_exclude: true lang: id translation_key: seedance-2-pricing date: 2026-07-21 repo: https://github.com/useapi/seedance-2-api last_modified: 2026-11-18 nav_order: 90 --- ## Harga API Seedance 2.0 dan 2.5: Semua Jalur, Dibandingkan {: .no_toc #seedance-20-and-25-api-pricing-every-route-compared } 13 menit baca • 21 Juli 2026 (18 November 2026) ## Daftar isi {: .no_toc .text-delta #table-of-contents } ### Pendahuluan Video Seedance 2.0 1080p berdurasi 5 detik berharga $1,87 di API resmi ByteDance, dan tarif per video terendah yang kami verifikasi adalah $1,12 lewat jalur PixVerse useapi.net, di paket Ultra tahunan ($1,49 bulanan), atau $1,44 di paket Premium tahunan ($1,80 bulanan), dan kini tidak ada reseller di bawahnya (yang termurah, Segmind, $1,97). Seedance 2.5 lain ceritanya. Dengan $2,84 per video 1080p, tarif ByteDance sendiri mengalahkan semua reseller dan semua paket bulanan yang kami temukan, dan hanya paket tahunan yang sedikit lebih murah: PixVerse Ultra ($2,32), serta PixVerse Premium atau Runway Max ($2,72). Pada 13 November 2026 (jalur PixVerse sekali lagi pada 15 November) kami membaca ulang harga dua kanal resmi ByteDance dan selusin vendor pihak ketiga dari halaman live mereka, menghitung ulang empat jalur kami dari tarif kredit saat ini, dan menyamakan semuanya ke satu satuan: biaya dalam dolar untuk satu video text-to-video berdurasi 5 detik tanpa input video. Gambarannya sudah berubah sejak artikel ini pertama terbit di bulan Juli. PixVerse mengubah harga Seedance dan menghentikan diskon untuk Pro dan Premium, sehingga jalurnya naik dari $1,20 menjadi $1,80 per video di paket bulanan, ByteDance meluncurkan Seedance 2.5 dengan tarif token sekitar 50% lebih tinggi dari 2.0, dan sebagian besar reseller menyusul dengan tier 2.5 mereka sendiri. Kami perlu terus terang soal posisi kami. useapi.net adalah lapisan bring-your-own-account, bukan reseller resmi ByteDance. Kami menjalankan akun [PixVerse](/docs/api-pixverse-v2), [Runway](/docs/api-runwayml-v1), [Dreamina](/docs/api-dreamina-v1), atau [MiniMax](/docs/api-minimax-v1) milik Anda lewat satu REST API, jadi Anda memakai kredit konsumen platform itu, bukan tarif terukur API developer. Setiap angka di bawah mencantumkan tanggal dan sumbernya, dan harga di pasar ini berubah setiap bulan, jadi cek ulang sebelum mengalokasikan anggaran. Satu langganan useapi.net menjalankan Seedance 2.0 dan 2.5 di keempat jalur di bawah, di paket PixVerse, Runway, Dreamina atau MiniMax yang sudah Anda punya, dan mencakup semua API lain di situs ini. [Berlangganan — $15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03?client_reference_id={{ page.url | slugify | default: 'home' }}){: .btn .btn-purple .mr-2 .mb-3 } [Perbandingan empat jalur](#four-ways-to-run-seedance-20-through-useapinet) ### Harga resmi API Seedance 2.0 dan 2.5 ByteDance menjual Seedance lewat dua kanal resmi — [BytePlus ModelArk](https://docs.byteplus.com/en/docs/ModelArk/1544106) untuk pasar internasional dan [Volcano Engine](https://www.volcengine.com/docs/82379/1544106) di Tiongkok. Keduanya menagih per juta token, dengan jumlah token sebuah video dihitung `width × height × 24fps × seconds ÷ 1024`. Video 1080p berdurasi 5 detik setara 243.000 token. Seedance 2.0 menagih $7,7 per juta di 1080p, jadi video itu berharga $1,87. Seedance 2.5 menagih $11,7 per juta di 1080p, jadi video yang sama berharga $2,84. Setelah dinormalkan, menurut halaman harga BytePlus (dibaca 13 November 2026): | Resolusi | Seedance 2.0, 5 detik | Seedance 2.0, 10 detik | Seedance 2.5, 5 detik | Seedance 2.5, 10 detik | |:-----------|-----------------:|------------------:|-----------------:|------------------:| | 480p | $0,35 | $0,70 | $0,51 | $1,03 | | 720p | $0,76 | $1,51 | $1,16 | $2,31 | | 1080p | $1,87 | $3,74 | $2,84 | $5,69 | | 4K | $3,89 | $7,78 | $4,57 | $9,14 | Seedance 2.5 mencapai 4K di BytePlus pada 16 November 2026, seharga $4,57 untuk video 5 detik tanpa input video, berjalan hingga 30 detik per video dibanding 15 detik di 2.0, dan menerima hingga 50 referensi (30 gambar, 10 video, 10 klip audio). Video 2.5 1080p penuh berdurasi 30 detik berharga sekitar $17. Seedance 2.0 Fast dan Mini tetap lebih murah dan masih mentok di 720p — video 720p berdurasi 5 detik tercantum $0,60 di Fast dan $0,38 di Mini. Seedance 2.5 Flash yang baru juga berhenti di 720p, seharga $0,76 untuk video 720p berdurasi 5 detik, dan BytePlus membukanya untuk panggilan API pada 15 November 2026. Audio sudah termasuk tanpa biaya tambahan. Volcano mematok 2.5 di ¥77 per juta token di 1080p, tetapi mewajibkan verifikasi nama asli dan wajah Tiongkok, jadi praktis hanya untuk Tiongkok. Harga di label bukan seluruh biayanya. Mengaktifkan Seedance di BytePlus butuh sekitar $30 di muka — [resource pack](https://docs.byteplus.com/en/docs/ModelArk/2191775) prabayar (yang terkecil $30,10 untuk 2.0 dan $32 untuk 2.5, tidak bisa dikembalikan, kedaluwarsa setelah 90 hari) atau top-up saldo $30 yang disarankan BytePlus. Akun individu dibatasi 3 tugas bersamaan (180 request/menit), dan 4K dibatasi satu tugas bersamaan untuk semua orang. Semua itu tidak membuat API resmi jadi pilihan buruk. Justru itulah patokan yang harus dipakai untuk mengukur setiap alternatif. ### Empat cara menjalankan Seedance 2.0 lewat useapi.net Satu token useapi.net menjalankan Seedance 2.0 di empat platform, di paket akun yang sudah Anda bayar. Biaya di bawah adalah biaya paket per video 1080p berdurasi 5 detik, diturunkan dari tarif kredit dan harga paket di dokumentasi kami. | Jalur | Model Seedance | 5 detik 1080p, paket bulanan | 5 detik 1080p, paket tahunan | Keunggulan | |:------|:----------------|-----------------------:|----------------------:|:---------------| | [PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) | 2.5, 2.5 Flash, 2.5 Draft, 2.0, Fast, Mini | $1,80 | $1,44 | 2.0 1080p dan 4K termurah ($1,49 dan $1,12 di Ultra), wajah manusia asli | | [Dreamina](/docs/api-dreamina-v1/post-dreamina-videos) | 2.5, 2.5 Flash, 2.0, Fast, Mini, 1.5 Pro, keluarga 1.0 | ~$1,83–1,87 | ~$1,78–1,81 | Seedance 2.5 dengan wajah asli dan video panjang, pilihan model terluas | | [MiniMax](/docs/api-minimax-v1/post-minimax-videos-create) | 2.0, Fast, Mini | $2,00 | $1,70 | 4K plus alur kerja gambar referensi yang lengkap | | [Runway](/docs/api-runwayml-v1/post-runwayml-videos-create) | 2.5, 2.0, Fast, Mini | $2,00 | $1,60 | wajah asli, moderasi lebih ringan dari Dreamina | Jalur PixVerse menagih Seedance 2.0 sebesar 90 kredit per detik di 1080p, jadi video 5 detik memakai 450 kredit. Di paket Premium $60/bulan ($0,004 per kredit) itu berarti $1,80, dan di Premium yang ditagih tahunan ($0,0032 per kredit) menjadi $1,44. Kredit Ultra lebih mahal, tetapi di Ultra PixVerse memberi diskon 50% untuk Seedance 2.0 kecuali request mengirim `relax_mode: false`, sehingga satu video menjadi $1,49, atau $1,12 jika ditagih tahunan (Ultra berharga $199 per bulan untuk 30.000 kredit, per 15 November 2026). Dengan harga penuh, yaitu yang dibayar request yang mengirim `relax_mode: false`, satu video Ultra berharga $2,99. PixVerse juga mencapai 2160p (4K) di Seedance 2.0, seharga $4,00 untuk 5 detik di Premium, atau $3,20 jika ditagih tahunan, dan $3,32 atau $2,48 di Ultra — 4K termurah yang kami temukan. Di bulan Juli jalur ini berharga $1,20 per video — sejak itu PixVerse mengubah harga keluarga Seedance dan menghentikan diskon Pro dan Premium yang dulu berlaku, dan itulah perubahan terbesar dalam pembaruan ini ([tabel biaya PixVerse](/docs/api-pixverse-v2)). Keunggulan nyata jalur Dreamina adalah Seedance 2.5: jalur ini menerima wajah asli dan membuat video panjang berdurasi 31 hingga 180 detik dalam satu job, yang tidak bisa dilakukan API resmi ([harga Seedance 2.5](#seedance-25-pricing)). Untuk Seedance 2.0 di 1080p, harganya praktis setara dengan API resmi. Dengan 57 kredit per detik di paket Advanced wilayah Kanada, video 5 detik berharga sekitar $1,83 jika ditagih bulanan (C$109,99 untuk 11.997 kredit) dan $1,81 jika ditagih tahunan (C$1.299,99), dibanding $1,87. Paket Advanced AS menjalankannya dengan 41 kredit per detik, sekitar $1,87 ditagih bulanan ($79 untuk 8.645 kredit) dan $1,78 ditagih tahunan ($900). Kedua wilayah menjalankan 1080p dan 4K, dan keluarga 2.0 di Dreamina menolak wajah manusia asli. Harga paket dan tarif kredit dibaca ulang pada 12 November 2026, dikonversi dengan kurs CAD/USD 0,7023 ([kalkulator biaya Dreamina](/docs/start-here/setup-dreamina#cost-calculator)). Jalur MiniMax menagih Seedance 2.0 sebesar 50 kredit per detik di 1080p, tidak berubah sejak Juli, yang merupakan diskon Seedance 50% dari MiniMax, berlabel penawaran waktu terbatas (per 12 November 2026). MiniMax juga mengubah harga paketnya. Paket Master $89 (10.500 kredit) membuat satu video berharga $2,12, paket Max $216 (27.000 kredit) $2,00, dan Master yang ditagih tahunan $1,70, dengan 4K seharga $3,39 di paket tahunan itu. Jalur Runway kini juga punya tarif yang dipublikasikan. Seedance 2.0 di sana memakai 40 kredit per detik di 1080p, yaitu $2,00 per video di paket Max Runway seharga $95 dan $1,60 jika ditagih tahunan ([kalkulator biaya Runway](/docs/api-runwayml-v1)). `exploreMode` lama milik Runway masih menjalankan Seedance di 480p dan 720p tanpa memakai kredit di akun Unlimited lama yang sudah mengaktifkan Explore mode, sampai Runway memindahkan akun-akun itu ke Max pada 30 November 2026. Runway tidak lagi mengaktifkannya di akun baru, dan mode ini lambat — satu video dalam satu waktu, kira-kira 10 sampai 15 menit per video. Anggap saja bonus kalau Anda sudah punya, bukan alasan untuk memilih Runway. Ini adalah biaya paket per video, dan yang termurah mengasumsikan komitmen tahunan yang benar-benar Anda pakai. Premium yang ditagih tahunan berarti $576 di muka untuk 15.000 kredit per bulan, sekitar 33 video 1080p per bulan, dan Ultra yang ditagih tahunan berarti $1.788 untuk 30.000 kredit per bulan, sekitar 133 video. Kompromi-kompromi ini perlu disebutkan. Jalur kami mengotomatiskan akun konsumen, jadi konkurensi terikat pada akun (biasanya 5–10 job paralel, dibanding batas per key di API resmi), dan platform-platform ini mengubah harga tanpa pemberitahuan, seperti yang baru saja dilakukan PixVerse. Sebagai gantinya Anda mendapat biaya per video di bawah tarif resmi untuk 2.0 di paket tahunan (dan di PixVerse bulanan), tanpa paket prabayar, dan satu token untuk keempat platform. ### Harga Seedance 2.5 Seedance 2.5 berjalan di tiga dari empat jalur kami — [PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4), [Dreamina](/docs/api-dreamina-v1/post-dreamina-videos), dan [Runway](/docs/api-runwayml-v1/post-runwayml-videos-create). MiniMax tidak menyediakannya. Di 2.5, perbedaan yang lebih besar adalah apa yang tidak mau dilakukan API resmi. [Panduan Seedance 2.5](https://docs.byteplus.com/en/docs/modelark/seedance-2-5) milik ByteDance sendiri menyatakan bahwa 2.5 "does not support directly uploading reference images or videos containing real human faces", dan API resmi berhenti di 30 detik per video. [Jalur Dreamina menerima wajah asli di 2.5](/docs/api-dreamina-v1/post-dreamina-videos) secara langsung dan menambahkan mode video panjang berdurasi 31 hingga 180 detik dalam satu job, plus edit video, dan di akun Kanada jalur ini merender 2.5 dalam 4K seharga sekitar $4,15 per video 5 detik di paket Advanced Kanada, di bawah harga resmi $4,57. [Jalur Runway](/docs/api-runwayml-v1/post-runwayml-videos-create) juga menerima wajah asli di Seedance, dan tidak ada paket prabayar sekitar $30 yang harus dibeli sebelum video pertama. Di 1080p, jalur PixVerse dan Runway kami juga lebih murah per video dibanding tarif ByteDance sendiri di paket tahunan. Video 5 detik tanpa input video: | Jalur | 1080p, 5 detik | Durasi maks. | |:------|-----------:|:-----------| | [PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) *(Ultra, ditagih tahunan)* | $2,32 | 30 detik | | [PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) *(Premium, ditagih tahunan)* | $2,72 | 30 detik | | [Runway](/docs/api-runwayml-v1/post-runwayml-videos-create) *(Max, ditagih tahunan)* | $2,72 | 30 detik | | [BytePlus resmi](https://docs.byteplus.com/en/docs/ModelArk/1544106) | $2,84 | 30 detik | PixVerse menagih 2.5 sebesar 170 kredit per detik di 1080p ($0,0032 per kredit di Premium yang ditagih tahunan), dan Ultra memberi diskon 45%, 468 kredit per video dengan $0,00497 per kredit jika ditagih tahunan ($3,10 di paket Ultra bulanan). Runway menagih 68 kredit per detik di 1080p ($0,008 per kredit di Max yang ditagih tahunan, $76 per bulan untuk 9.500 kredit, per 13 November 2026). Tarif tahunan mengasumsikan Anda memakai kredit paketnya. PixVerse kini juga merender Seedance 2.5 dalam 4K (2160p), seharga 286 kredit per detik (per 15 November 2026). Video 4K 5 detik memakai 1.430 kredit, atau 787 setelah diskon Ultra, yaitu $3,91 di Ultra yang ditagih tahunan, dibanding $4,57 di API ByteDance sendiri (per 18 November 2026). ### Celah wajah asli Seedance 2.0 dan 2.5 sama-sama menolak gambar dan video referensi yang berisi wajah manusia asli di API resmi, kecuali wajah itu berasal dari output terbaru model itu sendiri, karakter digital preset, atau aset orang asli yang sudah diverifikasi. Pekerjaan referensi orang asli dalam skala besar berarti memakai "Advanced Creation Rights" enterprise dari ByteDance — [$14.000 per tahun atau $1.400 per bulan](https://docs.byteplus.com/en/docs/modelark/2377608) untuk satu juta aset, $42.000 per tahun untuk lima juta, dengan verifikasi perusahaan. Jalur kami melonggarkan hal ini di empat tempat. [Jalur PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) menerima wajah manusia asli di Seedance 2.0, [jalur Runway](/docs/api-runwayml-v1/post-runwayml-videos-create) mendokumentasikan dukungan wajah asli di Seedance dan umumnya moderasi yang lebih ringan dari Dreamina, [jalur MiniMax](/docs/api-minimax-v1/post-minimax-videos-create) menerima wajah asli di referensi gambar (referensi video dengan wajah yang bisa dikenali tetap dimoderasi), dan [jalur Dreamina](/docs/api-dreamina-v1/post-dreamina-videos) menerima potret fotografis di Seedance 2.5, meski tidak di keluarga 2.0-nya. Untuk iklan, UGC, dan alur kerja kreator yang berpusat pada orang sungguhan, perbedaan itu lebih penting daripada selisih beberapa sen per video — dan tidak butuh kontrak enterprise. ### Harga API Seedance di berbagai reseller Sebagian besar vendor Seedance pihak ketiga menjual ulang API ByteDance sendiri dengan margin di atasnya. Berikut Seedance 2.0 untuk 5 detik di 1080p, setiap harga pihak ketiga dibaca dari halaman live vendor pada 13 November 2026: | Vendor | 5 detik 1080p | Catatan | |:-------|---------:|:------| | [useapi.net (jalur PixVerse)](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) | $1,12–1,80 | kredit akun konsumen, dari Ultra tahunan hingga Premium bulanan | | [useapi.net (jalur Runway)](/docs/api-runwayml-v1/post-runwayml-videos-create) | $1,60–2,00 | paket Max, tahunan atau bulanan | | [useapi.net (jalur MiniMax)](/docs/api-minimax-v1/post-minimax-videos-create) | $1,70–2,12 | Master tahunan hingga Master bulanan ($2,00 di Max bulanan) | | [useapi.net (jalur Dreamina)](/docs/api-dreamina-v1/post-dreamina-videos) | ~$1,78–1,87 | akun AS atau Kanada, Advanced tahunan atau bulanan, dibaca 12 November 2026 | | [BytePlus resmi](https://docs.byteplus.com/en/docs/ModelArk/1544106) | $1,87 | patokan, disamai persis oleh passthrough OpenRouter | | [Segmind](https://www.segmind.com/models/seedance-2.0/pricing) | $1,97 | di atas tarif resmi sejak November ($8,105 per juta token di 1080p) | | [RunComfy](https://www.runcomfy.com/models/bytedance/seedance-v2/pro) | $2,00 | $0,40 per detik, turun dari $0,55 di bulan Juli | | [EachLabs](https://www.eachlabs.ai/bytedance/seedance-2-0/bytedance-seedance-2-0-text-to-video) | $2,22 | sekitar $0,444 per detik, turun dari $0,60 | | [Replicate](https://replicate.com/bytedance/seedance-2.0) | $2,25 | lencana model "Official", $0,45 per detik output | | [Poyo.ai](https://poyo.ai/models/seedance-2) | $2,25 | $0,45 per detik | | [EvoLink](https://evolink.ai/seedance-2-0) | $2,48 | $0,497 per detik | | [PiAPI](https://piapi.ai/seedance-2-0) | $2,50 | $0,50 per detik | | [Kie.ai](https://kie.ai/seedance-2-0) | $2,55 | $0,51 per detik | | [Atlas Cloud](https://www.atlascloud.ai/models/bytedance/seedance-2.0/text-to-video) | $2,74 | $2,20 dengan promosi 20% | | [WaveSpeedAI](https://wavespeed.ai/models/bytedance/seedance-2.0/text-to-video) | $3,00 | $0,60 per detik | | [fal.ai](https://fal.ai/models/bytedance/seedance-2.0/text-to-video) | $3,41 | pilihan default pasar, dan tetap yang termahal | Baris terakhir itu patut direnungkan. fal.ai adalah tempat banyak developer pertama kali mencari Seedance, dan dengan $0,682 per detik ia menagih sekitar 82% lebih mahal dari tarif ByteDance sendiri untuk model yang sama. Hal yang sama terjadi di 2.5, dengan video 720p seharga $2,31 dibanding $1,16 resmi, dan video 1080p sekitar $5,69 dibanding $2,84. Seedance 2.5 punya deretan reseller sendiri. Replicate dan OpenRouter meneruskan tarif resmi apa adanya ($1,16 untuk 720p, $0,51 untuk 480p) tetapi berhenti di 720p, dan [RunComfy](https://www.runcomfy.com/models/bytedance/seedance-2.5/text-to-video) kini menjual 2.5 hanya di 720p ($1,53 untuk 5 detik selama promosi 35% yang sedang berjalan). Di antara vendor yang menjual 2.5 di 1080p, [Poyo](https://poyo.ai/models/seedance-2-5) ($2,85), [Segmind](https://www.segmind.com/models/seedance-2.5/pricing) ($2,99) dan [Atlas Cloud](https://www.atlascloud.ai/models/bytedance/seedance-2.5/text-to-video) ($2,98 dengan promosi 20%, $3,73 tanpa promosi) berada dalam selisih beberapa persen dari tarif resmi, [EachLabs](https://www.eachlabs.ai/bytedance/seedance-2-5/bytedance-seedance-2-5-text-to-video) ($3,28) sekitar 15% di atasnya, dan [EvoLink](https://evolink.ai/seedance-2-5) ($3,70), [Kie.ai](https://kie.ai/seedance-2-5) ($3,95), [PiAPI](https://piapi.ai/seedance-2-5) ($4,00), serta [WaveSpeedAI](https://wavespeed.ai/models/bytedance/seedance-2.5/text-to-video) ($4,50) 30–60% di atasnya. Anda juga akan melihat harga label yang tampak jauh lebih rendah dari tarif resmi. Setiap harga yang kami telusuri ternyata bukan video standar yang lebih murah. Beberapa pola yang perlu diwaspadai saat harga terlihat terlalu bagus: - Varian "turbo" atau "accelerated" yang bukan model standar — satu vendor mencantumkan video Seedance 2.5 1080p berdurasi 5 detik seharga $1,10 dengan nama model turbo yang tidak dipublikasikan ByteDance, sementara Seedance 2.5 standarnya berharga $4,50 di situs yang sama. - Harga untuk 720p padahal Anda butuh 1080p — beberapa halaman "Seedance termurah", serta listing Seedance 2.5 di Replicate dan OpenRouter, sama sekali tidak punya tier 1080p. - Harga 2.0 di halaman tentang 2.5 — Seedance 2.5 berharga sekitar 50% lebih mahal per token, jadi harga "Seedance" tanpa nomor versi tidak bisa dibandingkan. - Kredit tanpa nilai dolar yang dipublikasikan — kalau sebuah halaman menghargai generasi dalam kredit tetapi tidak pernah menyebut harga satu kredit, Anda tidak bisa membandingkannya, dan biasanya memang itu tujuannya. Semua ini tidak berarti vendor-vendor itu tidak jujur — artinya versi, resolusi, dan detail kecilnya harus sama sebelum perbandingan punya arti. ### Cara memanggil Seedance API Setiap harga di atas hanya berjarak satu panggilan REST. Buat video Seedance 2.0 1080p lewat jalur PixVerse: ```bash curl --location 'https://api.useapi.net/v2/pixverse/videos/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="seedance-2.0"' \ --form 'prompt="A lone lighthouse on a storm-battered cliff at dusk, waves exploding against the rocks, beam sweeping through the rain, cinematic wide shot."' \ --form 'quality="1080p"' \ --form 'duration="5"' \ --form 'aspect_ratio="16:9"' ``` Panggilan yang sama menjalankan Seedance 2.5 dengan mengganti `model` menjadi `seedance-2.5`, dengan `duration` antara 4 dan 30. Atau, jika akun Runway Anda masih punya Explore mode — Runway tidak lagi menawarkannya di akun baru dan mengakhirinya untuk akun Unlimited lama pada 30 November 2026 — bentuk yang sama berjalan tanpa kredit di 720p dengan menambahkan `exploreMode`, satu video lambat dalam satu waktu: ```bash curl --location 'https://api.useapi.net/v1/runwayml/videos/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="seedance-2"' \ --form 'text_prompt="A lone lighthouse on a storm-battered cliff at dusk, waves exploding against the rocks, beam sweeping through the rain, cinematic wide shot."' \ --form 'resolution="720p"' \ --form 'duration="5"' \ --form 'exploreMode="true"' ``` Keduanya mengembalikan job id untuk di-poll (atau webhook `replyUrl` saat video siap). Set parameter lengkapnya — gambar referensi, frame awal dan akhir, rasio aspek, dan audio — ada di halaman setiap endpoint yang ditautkan di tabel-tabel di atas. ### Jalur mana yang sebaiknya dipakai untuk Seedance 2.0 atau 2.5? - Seedance 2.0 1080p termurah — [jalur PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) di paket tahunan, $1,12 di Ultra atau $1,44 di Premium. Tanpa komitmen tahunan, PixVerse bulanan ($1,49 di Ultra, $1,80 di Premium) tetap di bawah tarif resmi $1,87, dan semua reseller berada di atasnya. - 4K termurah — jalur PixVerse seharga $2,48 di Ultra tahunan atau $3,20 di Premium tahunan, lalu [MiniMax](/docs/api-minimax-v1/post-minimax-videos-create) seharga $3,39 tahunan, semuanya di bawah tarif resmi $3,89. - Seedance 2.5 1080p termurah — [jalur PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) di Ultra yang ditagih tahunan, $2,32 per video 5 detik, lalu PixVerse Premium atau [jalur Runway](/docs/api-runwayml-v1/post-runwayml-videos-create) di Max, keduanya ditagih tahunan, seharga $2,72, dibanding $2,84 di API resmi. - Seedance 2.5 4K termurah — [jalur PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) di Ultra yang ditagih tahunan, $3,91 per video 5 detik, lalu [jalur Dreamina](/docs/api-dreamina-v1/post-dreamina-videos) di paket Advanced Kanada seharga sekitar $4,15, dibanding harga resmi $4,57. - Seedance 2.5 dengan wajah manusia asli, atau video lebih dari 30 detik — [jalur Dreamina](/docs/api-dreamina-v1/post-dreamina-videos). - Wajah manusia asli di Seedance 2.0 — jalur [PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4), [MiniMax](/docs/api-minimax-v1/post-minimax-videos-create), atau [Runway](/docs/api-runwayml-v1/post-runwayml-videos-create). - Seedance 1.5 Pro atau 1.0 — jalur Dreamina, satu-satunya yang menyediakan keluarga 1.x. BytePlus sudah menghentikan 1.5 Pro di API-nya sendiri. ### Contoh Output Seedance 2.0 asli dari setiap jalur, diambil dari postingan blog kami — model yang sama, dijalankan di platform yang berbeda. Tiga di antaranya memakai wajah manusia asli, alur kerja yang di API resmi dikunci di balik kontrak enterprise. PixVerse · Seedance 2.0 (Standard), 1080p — wajah asli dari sebuah foto dimasukkan ke footage referensi dan diberi ucapan dari klip audio referensi, semuanya dalam satu request omni. Dari [PixVerse Seedance 2.0: Mini vs Fast vs Standard](/blog/260626a). <video poster="https://media.useapi.net/blog/2026-06-26-260626a/omni-standard-1080p-4s-9x16-swap-poster.jpg" src="https://media.useapi.net/blog/2026-06-26-260626a/omni-standard-1080p-4s-9x16-swap.mp4" style="width: 100%; max-width: 420px;" controls type="video/mp4" preload="metadata">Your browser does not support the video element.</video> Juga di YouTube: [Seedance 2.0 Omni: Photo + Reference Video + Audio → One Clip (Mini vs Fast vs Standard)](https://youtube.com/shorts/apUc3lXrY_4). MiniMax · Seedance 2.0 (Standard), 1080p — alur kerja omni wajah asli yang sama di jalur MiniMax. Dari [MiniMax Seedance 2.0: Standard vs Fast vs Mini](/blog/260626b). <video poster="https://media.useapi.net/blog/2026-06-26-260626b/std-1080-5s-nowm-poster.jpg" src="https://media.useapi.net/blog/2026-06-26-260626b/std-1080-5s-nowm.mp4" style="width: 100%; max-width: 420px;" controls type="video/mp4" preload="metadata">Your browser does not support the video element.</video> Runway · Seedance 2.0, 15 detik, 9:16 — wajah asli yang dianimasikan di jalur Runway, yang menerapkan moderasi lebih ringan pada orang sungguhan. Dari [Seedance 2.0: Using Real Faces](/blog/260415). <video poster="https://media.useapi.net/articles/2024-08-11-runway-bash/runway-original-result-poster.jpg" src="https://media.useapi.net/articles/2024-08-11-runway-bash/runway-original-result.mp4" style="width: 100%; max-width: 420px;" controls type="video/mp4" preload="metadata">Your browser does not support the video element.</video> Dreamina · Seedance 2.0, text-to-video dengan lip-sync hanya dari prompt. Dari [Dreamina: Seedance 2.0 Video Generation](/blog/260402). <video poster="https://media.useapi.net/blog/2026-04-02-260402/seedance-2.0-prompt-9-16-poster.jpg" src="https://media.useapi.net/blog/2026-04-02-260402/seedance-2.0-prompt-9-16.mp4" style="width: 100%; max-width: 420px;" controls type="video/mp4" preload="metadata">Your browser does not support the video element.</video> Tutorial terkait: [video Seedance 2.0 lewat Dreamina API](/docs/articles/dreamina-bash), [alternatif API Sora 2](/docs/articles/sora-2-api-alternatives) dan [video PixVerse V6 lewat PixVerse API](/docs/articles/pixverse-demo). ## FAQ **Apakah useapi.net adalah API Seedance resmi?** Bukan. useapi.net adalah lapisan REST yang mengotomatiskan akun [PixVerse](/docs/api-pixverse-v2), [Runway](/docs/api-runwayml-v1), [Dreamina](/docs/api-dreamina-v1), atau [MiniMax](/docs/api-minimax-v1) milik Anda, yang masing-masing menjalankan Seedance. Anda memakai kredit konsumen platform itu, bukan tarif terukur API developer ByteDance. **Berapa biaya Seedance 2.0 per video?** Lewat useapi.net, video 1080p berdurasi 5 detik berharga $1,12 di [jalur PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) di paket Ultra tahunan, atau $1,44 di Premium tahunan ($1,80 bulanan), dibanding $1,87 di API resmi ByteDance. API resmi menagih $0,35 di 480p, $0,76 di 720p, $1,87 di 1080p, dan $3,89 di 4K untuk video 5 detik, per 13 November 2026. Lihat [tabel harga resmi](#official-seedance-20-and-25-api-pricing). **Berapa biaya Seedance 2.5?** Lewat useapi.net, Seedance 2.5 berjalan dengan wajah asli dan untuk video lebih dari 30 detik, yang dibatasi API resmi: [jalur Dreamina](/docs/api-dreamina-v1/post-dreamina-videos) menerima foto asli dan berjalan 31 hingga 180 detik dalam satu job. Di 1080p, video 5 detik berharga $2,32 di PixVerse Ultra dan $2,72 di PixVerse Premium atau Runway, yang ditagih tahunan, dibanding $2,84 di API resmi ByteDance (per November 2026). Lihat [harga Seedance 2.5](#seedance-25-pricing). **Apa cara termurah menjalankan Seedance 2.0 di 1080p?** Dari semua yang kami verifikasi pada 13 dan 15 November 2026, [jalur PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4): $1,12 per video 5 detik di paket Ultra tahunan, atau $1,44 di Premium tahunan. Tanpa komitmen tahunan, PixVerse bulanan ($1,49 di Ultra, $1,80 di Premium) adalah yang termurah, di bawah tarif resmi ByteDance $1,87, dan tidak ada reseller di bawahnya (Segmind, yang termurah, $1,97). Lihat [tabel pasar](#seedance-api-pricing-across-resellers). **Bisakah saya membuat video Seedance dengan wajah manusia asli?** Bisa, lewat useapi.net: jalur [PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4), [Runway](/docs/api-runwayml-v1/post-runwayml-videos-create), dan [MiniMax](/docs/api-minimax-v1/post-minimax-videos-create) menerima wajah asli di 2.0 (MiniMax di referensi gambar), dan [jalur Dreamina](/docs/api-dreamina-v1/post-dreamina-videos) menerimanya di 2.5. API resmi membatasi input referensi wajah asli di 2.0 maupun 2.5 hanya untuk aset terverifikasi atau kontrak enterprise mulai $14.000 per tahun. **Bagaimana useapi.net bisa lebih murah dari API ByteDance sendiri?** Untuk Seedance 2.0, paket konsumen di PixVerse (bulanan atau tahunan), Runway, Dreamina, dan MiniMax (tahunan) menghargai generasi yang sama di bawah tarif terukur developer, dan useapi.net mengotomatiskan salah satu akun itu lewat REST, dengan satu [langganan](/docs/subscription) untuk semua layanan. Untuk Seedance 2.5 sebagian besar tidak — tarif resmi lebih rendah kecuali dibanding paket tahunan PixVerse atau Runway di 1080p, dan jalur kami unggul di wajah asli, video lebih panjang, dan tanpa paket prabayar. **Apakah harga Seedance di bawah satu dolar yang saya lihat di tempat lain itu nyata?** Biasanya tidak untuk video 1080p standar. Harga itu umumnya tarif 720p, harga 2.0 di halaman 2.5, paket flat-rate bersubsidi, varian "turbo" hasil distilasi, atau kredit tanpa nilai dolar yang dipublikasikan — lihat [bagian pasar yang lebih luas](#seedance-api-pricing-across-resellers). --- Siap mencoba? Seluruh perbandingan ini ada dalam satu skrip — [github.com/useapi/seedance-2-api](https://github.com/useapi/seedance-2-api) mengirim prompt ke keempat jalur dan mencetak biaya dan kecepatan masing-masing, ditambah kalkulator harga yang bisa Anda jalankan tanpa akun sama sekali. Lalu pilih jalur — [PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) untuk Seedance 2.0 1080p termurah, [Dreamina](/docs/api-dreamina-v1/post-dreamina-videos) untuk Seedance 2.5 dengan wajah asli dan video panjang — hubungkan akunnya, dan [langganan useapi.net](/docs/subscription) menjalankan keempatnya dengan satu token. Harga di artikel ini berlaku pada 13 November 2026, dan pasar ini berubah setiap bulan, jadi pastikan tarif terbaru sebelum Anda menaikkan skala. #### Dipublikasikan juga di {: .no_toc #cross-posted } Juga dipublikasikan di [dev.to](https://dev.to/useapi/seedance-20-api-pricing-the-cheapest-ways-to-run-it-compared-4kno){:rel="nofollow"} (bahasa Inggris). ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/seedance-2-api-pricing-ja === Document URL: https://useapi.net/docs/articles/seedance-2-api-pricing-ja --- layout: default title: "Seedance 2.0・2.5 API の料金:すべての利用ルートを比較" seo_title: "Seedance 2.0・2.5 API 料金比較:公式 API と再販業者と useapi.net" description: "5秒の Seedance 2.0・2.5 動画の料金を、ByteDance の公式 API、十数社の再販業者、useapi.net の4つのルートで比較。2026年11月13日に再確認。" keywords: [Seedance 2.0 API, Seedance 2.5 API, Seedance 料金, Seedance 2.0 料金, Seedance 2.5 料金, Seedance 2.0 価格, Seedance API 料金, Seedance 1本あたりの料金, Seedance API 比較, ByteDance 動画生成 API, 動画生成 API 料金, テキストから動画 API, Seedance pricing, Seedance 2.0 pricing, Seedance 2.5 pricing, Seedance 2.0 price, Seedance cost per video, Seedance API cost, ByteDance video API, BytePlus ModelArk Seedance, fal.ai Seedance, Replicate Seedance, PixVerse Seedance, Runway Seedance, Dreamina Seedance, text to video API] image: /assets/images/articles/seedance-2-api-pricing-2026-10.jpg parent: Articles nav_exclude: true lang: ja translation_key: seedance-2-pricing date: 2026-07-21 repo: https://github.com/useapi/seedance-2-api last_modified: 2026-11-18 nav_order: 90 --- ## Seedance 2.0・2.5 API の料金:すべての利用ルートを比較 {: .no_toc #seedance-20-and-25-api-pricing-every-route-compared } 13分で読めます • 2026年7月21日(2026年11月18日更新) ## 目次 {: .no_toc .text-delta #table-of-contents } ### はじめに 5秒・1080p の Seedance 2.0 動画は、ByteDance の公式 API で $1.87 かかります。確認できた中で1本あたり最も安いのは useapi.net の PixVerse ルートで、Ultra の年額プランなら $1.12(月額プランなら $1.49)、Premium の年額プランなら $1.44(月額プランなら $1.80)です。これより安い再販業者はもうありません(最安の Segmind で $1.97)。Seedance 2.5 は事情が違います。1080p で1本 $2.84 という ByteDance 自身の料金は、私たちが調べたどの再販業者、どの月額プランよりも安く、それを下回るのは年額プランだけです。PixVerse Ultra($2.32)と、PixVerse Premium か Runway Max($2.72)です。2026年11月13日に(PixVerse ルートは11月15日にも改めて)、ByteDance の2つの公式チャネルと十数社のサードパーティ業者の料金をそれぞれのサイトで読み直し、私たちの4つのルートも現在のクレジット単価から計算し直しました。そのうえで、すべてを1つの単位にそろえています。動画入力なしで、テキストから作る5秒の動画1本のドル建て料金です。 7月に最初に公開したときから状況は変わりました。PixVerse は Seedance の料金を改定して Pro と Premium の割引を終了し、月額プランでのこのルートの料金は1本 $1.20 から $1.80 に上がりました。ByteDance は Seedance 2.5 を 2.0 より約50%高いトークン単価で公開し、ほとんどの再販業者もそれぞれ 2.5 の料金を設定しました。 私たちの立ち位置も最初にはっきりさせておきます。useapi.net はご自身のアカウントを持ち込んで使う仕組みで、ByteDance の公式再販業者ではありません。お持ちの [PixVerse](/docs/api-pixverse-v2)、[Runway](/docs/api-runwayml-v1)、[Dreamina](/docs/api-dreamina-v1)、[MiniMax](/docs/api-minimax-v1) のアカウントを1つの REST API で操作するので、従量制の開発者向け API 料金ではなく、それらのプラットフォームの一般向けクレジットを使います。以下の数字にはすべて日付と出典を付けていますが、この市場の料金は毎月のように変わるので、支出を決める前にもう一度確認してください。 useapi.net のサブスクリプション1つで、下の4つのルートすべてで Seedance 2.0 と 2.5 を、すでにお持ちの PixVerse、Runway、Dreamina、MiniMax のプランのまま使えます。サイトのほかのすべての API も含まれます。 [登録する — 月額 $15](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03?client_reference_id={{ page.url | slugify | default: 'home' }}){: .btn .btn-purple .mr-2 .mb-3 } [4つのルートの比較](#four-ways-to-run-seedance-20-through-useapinet) ### Seedance 2.0・2.5 の公式 API の料金 ByteDance は Seedance を2つの公式チャネルで販売しています。海外向けの [BytePlus ModelArk](https://docs.byteplus.com/en/docs/ModelArk/1544106) と、中国向けの [Volcano Engine](https://www.volcengine.com/docs/82379/1544106) です。どちらも100万トークン単位の課金で、動画1本のトークン数は `width × height × 24fps × seconds ÷ 1024` です。5秒・1080p の動画は243,000トークンになります。Seedance 2.0 は 1080p で100万トークンあたり $7.7 なので、この動画は $1.87 です。Seedance 2.5 は 1080p で100万トークンあたり $11.7 なので、同じ動画が $2.84 になります。BytePlus の料金ページ(2026年11月13日に確認)をもとに1本あたりに換算すると、次のとおりです。 | 解像度 | Seedance 2.0、5秒 | Seedance 2.0、10秒 | Seedance 2.5、5秒 | Seedance 2.5、10秒 | |:-----------|-----------------:|------------------:|-----------------:|------------------:| | 480p | $0.35 | $0.70 | $0.51 | $1.03 | | 720p | $0.76 | $1.51 | $1.16 | $2.31 | | 1080p | $1.87 | $3.74 | $2.84 | $5.69 | | 4K | $3.89 | $7.78 | $4.57 | $9.14 | Seedance 2.5 は2026年11月16日に BytePlus で 4K に対応し、動画入力なしの5秒の動画が $4.57 です。1本の長さは 2.0 の15秒に対して最大30秒で、参照素材も最大50個(画像30枚、動画10本、音声10本)使えます。30秒・1080p の 2.5 の動画を1本作ると約 $17 です。Seedance 2.0 Fast と Mini はより安く、上限は今も 720p です。720p・5秒の動画は Fast で $0.60、Mini で $0.38 です。新しい Seedance 2.5 Flash も 720p までで、720p・5秒の動画が $0.76 です。BytePlus は2026年11月15日に API から使えるようにします。音声は追加料金なしで含まれます。Volcano は 2.5 を 1080p で100万トークンあたり ¥77 としていますが、中国の実名認証と顔認証が必要なので、実質的に中国国内向けです。 表示価格がコストのすべてではありません。BytePlus で Seedance を有効にするには、最初に約 $30 かかります。前払いの[リソースパック](https://docs.byteplus.com/en/docs/ModelArk/2191775)(最小で 2.0 が $30.10、2.5 が $32、返金不可、90日で失効)か、BytePlus が推奨する $30 の残高チャージです。個人アカウントは同時実行3タスク(毎分180リクエスト)に制限され、4K は全員が同時実行1タスクまでです。だからといって公式 API が割高というわけではありません。ほかのすべての選択肢を比べる基準になる、ということです。 ### useapi.net で Seedance 2.0 を使う4つのルート useapi.net のトークン1つで、すでに支払っているアカウントのプランのまま、4つのプラットフォームで Seedance 2.0 を使えます。下の料金は5秒・1080p の動画1本あたりのプラン料金で、私たちのドキュメントにあるクレジット単価とプラン料金から計算しています。 | ルート | Seedance モデル | 5秒 1080p、月額プラン | 5秒 1080p、年額プラン | 強み | |:------|:----------------|-----------------------:|----------------------:|:---------------| | [PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) | 2.5、2.5 Flash、2.5 Draft、2.0、Fast、Mini | $1.80 | $1.44 | 1080p の 2.0 と 4K が最安(Ultra で $1.49 と $1.12)、実在の人物の顔 | | [Dreamina](/docs/api-dreamina-v1/post-dreamina-videos) | 2.5、2.5 Flash、2.0、Fast、Mini、1.5 Pro、1.0 系 | ~$1.83–1.87 | ~$1.78–1.81 | 実在の顔と長尺動画に対応した Seedance 2.5、最多のモデル | | [MiniMax](/docs/api-minimax-v1/post-minimax-videos-create) | 2.0、Fast、Mini | $2.00 | $1.70 | 4K と充実した参照画像ワークフロー | | [Runway](/docs/api-runwayml-v1/post-runwayml-videos-create) | 2.5、2.0、Fast、Mini | $2.00 | $1.60 | 実在の顔、Dreamina より緩いモデレーション | PixVerse ルートでは、Seedance 2.0 は 1080p で1秒90クレジットなので、5秒の動画は450クレジットです。月額 $60 の Premium プラン(1クレジット $0.004)なら $1.80、Premium の年額払い(1クレジット $0.0032)なら $1.44 です。Ultra はクレジット単価が高いものの、Ultra ではリクエストで `relax_mode: false` を送らない限り PixVerse が Seedance 2.0 を50%割引にするので、1本 $1.49、年額払いなら $1.12 です(Ultra は月額 $199 で30,000クレジット、2026年11月15日時点)。`relax_mode: false` で支払う通常料金では、Ultra の動画は1本 $2.99 です。PixVerse は Seedance 2.0 で 2160p(4K)にも対応し、5秒で Premium なら $4.00、年額払いなら $3.20、Ultra なら $3.32 または $2.48 です。私たちが見つけた中で最も安い 4K です。7月にはこのルートは1本 $1.20 でしたが、PixVerse はその後 Seedance 系の料金を改定し、Pro と Premium に付いていた割引を終了しました。今回の更新で最も大きな変化です([PixVerse の料金表](/docs/api-pixverse-v2))。 Dreamina ルートの本当の強みは Seedance 2.5 です。実在の人物の顔を使え、31〜180秒の長い動画を1回のジョブで作れます。公式 API にはどちらもできません([Seedance 2.5 の料金](#seedance-25-pricing))。1080p の Seedance 2.0 では、公式 API とほぼ同じ料金です。カナダ地域の Advanced プランでは1秒57クレジットで、5秒の動画は月額払い(C$109.99 で11,997クレジット)で約 $1.83、年額払い(C$1,299.99)で $1.81 となり、公式の $1.87 と比べられます。米国の Advanced プランでは1秒41クレジットで、月額払い($79 で8,645クレジット)で約 $1.87、年額払い($900)で $1.78 です。どちらの地域も 1080p と 4K に対応していますが、Dreamina の 2.0 系は実在の人物の顔を受け付けません。プラン料金とクレジット単価は2026年11月12日に改めて確認し、CAD/USD 0.7023 で換算しました([Dreamina の料金計算ツール](/docs/start-here/setup-dreamina#cost-calculator))。 MiniMax ルートでは、Seedance 2.0 は 1080p で1秒50クレジットで、7月から変わっていません。これは MiniMax の Seedance 50%割引で、期間限定のオファーと表示されています(2026年11月12日時点)。MiniMax もプランの料金を改定しました。$89 の Master プラン(10,500クレジット)では1本 $2.12、$216 の Max プラン(27,000クレジット)では $2.00、Master の年額払いでは $1.70 で、その年額プランなら 4K は $3.39 です。Runway ルートにも料金が公開されました。Seedance 2.0 は 1080p で1秒40クレジットで、Runway の $95 の Max プランで1本 $2.00、年額払いで $1.60 です([Runway の料金計算ツール](/docs/api-runwayml-v1))。Runway の旧来の `exploreMode` は、すでに Explore mode が有効になっている古い Unlimited アカウントなら、今も Seedance を 480p と 720p でクレジットを使わずに実行できます。ただし、Runway がそれらのアカウントを Max に移行する2026年11月30日までです。Runway は新しいアカウントではもう有効にしておらず、しかも遅く、1本ずつしか作れず、1本あたり10〜15分ほどかかります。すでに使えるならおまけと考え、Runway を選ぶ理由にはしないでください。 これらは動画1本あたりのプラン料金で、最も安いものは、年額契約をしてそのクレジットを実際に使い切ることが前提です。Premium の年額払いは最初に $576 で、毎月15,000クレジット、1080p の動画で月に約33本分です。Ultra の年額払いは $1,788 で、毎月30,000クレジット、動画で約133本分です。 トレードオフも挙げておきます。私たちのルートは一般向けアカウントを自動操作するので、同時実行数はアカウントに依存します(公式 API のキーごとの制限に対し、通常は5〜10件の並列ジョブ)。また、各プラットフォームは予告なく料金を改定します。PixVerse がまさにそうでした。その代わり、2.0 では年額プランで(PixVerse は月額でも)1本あたりの料金が公式より安く、前払いのパックも不要で、4つのプラットフォームすべてをトークン1つで使えます。 ### Seedance 2.5 の料金 Seedance 2.5 は、4つのルートのうち3つで使えます。[PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4)、[Dreamina](/docs/api-dreamina-v1/post-dreamina-videos)、[Runway](/docs/api-runwayml-v1/post-runwayml-videos-create) です。MiniMax にはありません。 2.5 で大きく違うのは、公式 API にできないことです。ByteDance 自身の [Seedance 2.5 ガイド](https://docs.byteplus.com/en/docs/modelark/seedance-2-5)には、2.5 は「does not support directly uploading reference images or videos containing real human faces」(実在の人物の顔を含む参照画像や動画の直接アップロードには対応していない)とあり、公式 API の動画は1本30秒までです。[Dreamina ルートは 2.5 で実在の顔を](/docs/api-dreamina-v1/post-dreamina-videos)そのまま受け付け、31〜180秒を1回のジョブで作る長尺動画モードと動画編集も加わります。カナダのアカウントでは 2.5 を 4K で出力でき、カナダの Advanced プランなら5秒の動画1本で約 $4.15 と、公式の $4.57 を下回ります。[Runway ルート](/docs/api-runwayml-v1/post-runwayml-videos-create)も Seedance で実在の顔を受け付け、最初の1本の前に約 $30 の前払いパックを買う必要もありません。 1080p では、私たちの PixVerse ルートと Runway ルートも、年額プランなら ByteDance 自身の料金より1本あたり安くなります。動画入力なし・5秒の動画で比べると、次のとおりです。 | ルート | 1080p、5秒 | 最大の長さ | |:------|-----------:|:-----------| | [PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) *(Ultra、年額払い)* | $2.32 | 30秒 | | [PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) *(Premium、年額払い)* | $2.72 | 30秒 | | [Runway](/docs/api-runwayml-v1/post-runwayml-videos-create) *(Max、年額払い)* | $2.72 | 30秒 | | [公式 BytePlus](https://docs.byteplus.com/en/docs/ModelArk/1544106) | $2.84 | 30秒 | PixVerse は 2.5 を 1080p で1秒170クレジットで課金します(Premium の年額払いで1クレジット $0.0032)。Ultra では45%割引になり、1本468クレジット、年額払いで1クレジット $0.00497 です(月額の Ultra プランなら $3.10)。Runway は 1080p で1秒68クレジットです(Max の年額払いで1クレジット $0.008、月あたり $76 で9,500クレジット、2026年11月13日時点)。年額料金は、プランのクレジットを使い切ることが前提です。 PixVerse も Seedance 2.5 を 4K(2160p)で生成できるようになりました。料金は1秒286クレジットです(2026年11月15日時点)。5秒の 4K 動画は1,430クレジット、Ultra の割引後は787クレジットで、Ultra の年額払いなら $3.91 で、ByteDance 自身の API では $4.57 です(2026年11月18日時点)。 ### 実在の顔をめぐる差 公式 API では、Seedance 2.0 も 2.5 も、実在の人物の顔を含む参照画像や動画を受け付けません。例外は、その顔がモデル自身の最近の出力、用意されたデジタルキャラクター、または認証済みの実在人物アセットから来ている場合です。実在の人物を参照する作業を大規模に行うには、ByteDance の法人向け「Advanced Creation Rights」が必要です。100万アセットで[年 $14,000 または月 $1,400](https://docs.byteplus.com/en/docs/modelark/2377608)、500万アセットで年 $42,000 で、法人認証が必要です。 私たちのルートでは、この制約が4か所で緩和されます。[PixVerse ルート](/docs/api-pixverse-v2/post-pixverse-videos-create-v4)は Seedance 2.0 で実在の人物の顔を受け付けます。[Runway ルート](/docs/api-runwayml-v1/post-runwayml-videos-create)は Seedance での実在の顔への対応をドキュメントに明記しており、全般に Dreamina より緩いモデレーションです。[MiniMax ルート](/docs/api-minimax-v1/post-minimax-videos-create)は参照画像で実在の顔を受け付けます(判別できる顔が写った参照動画は今もモデレーションの対象です)。[Dreamina ルート](/docs/api-dreamina-v1/post-dreamina-videos)は Seedance 2.5 で写真の人物を受け付けますが、2.0 系では受け付けません。実在の人物を中心とする広告、UGC、クリエイターのワークフローでは、この違いは1本数セントの差より重要で、しかも法人契約は必要ありません。 ### 再販業者ごとの Seedance API 料金 サードパーティの Seedance 業者の多くは、ByteDance 自身の API に利幅を上乗せして再販しています。以下は Seedance 2.0 の5秒・1080p の料金で、サードパーティの価格はすべて2026年11月13日に各業者のサイトで確認したものです。 | 業者 | 5秒 1080p | 備考 | |:-------|---------:|:------| | [useapi.net(PixVerse ルート)](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) | $1.12–1.80 | 一般向けアカウントのクレジット、Ultra の年額〜Premium の月額 | | [useapi.net(Runway ルート)](/docs/api-runwayml-v1/post-runwayml-videos-create) | $1.60–2.00 | Max プラン、年額または月額 | | [useapi.net(MiniMax ルート)](/docs/api-minimax-v1/post-minimax-videos-create) | $1.70–2.12 | Master の年額〜月額(Max の月額で $2.00) | | [useapi.net(Dreamina ルート)](/docs/api-dreamina-v1/post-dreamina-videos) | ~$1.78–1.87 | 米国またはカナダのアカウント、Advanced の年額または月額、2026年11月12日に確認 | | [公式 BytePlus](https://docs.byteplus.com/en/docs/ModelArk/1544106) | $1.87 | 比較の基準、OpenRouter のパススルーも同額 | | [Segmind](https://www.segmind.com/models/seedance-2.0/pricing) | $1.97 | 11月から公式より高い(1080p で100万トークンあたり $8.105) | | [RunComfy](https://www.runcomfy.com/models/bytedance/seedance-v2/pro) | $2.00 | 1秒 $0.40、7月の $0.55 から値下げ | | [EachLabs](https://www.eachlabs.ai/bytedance/seedance-2-0/bytedance-seedance-2-0-text-to-video) | $2.22 | 1秒約 $0.444、$0.60 から値下げ | | [Replicate](https://replicate.com/bytedance/seedance-2.0) | $2.25 | 「Official」モデルバッジ、出力1秒 $0.45 | | [Poyo.ai](https://poyo.ai/models/seedance-2) | $2.25 | 1秒 $0.45 | | [EvoLink](https://evolink.ai/seedance-2-0) | $2.48 | 1秒 $0.497 | | [PiAPI](https://piapi.ai/seedance-2-0) | $2.50 | 1秒 $0.50 | | [Kie.ai](https://kie.ai/seedance-2-0) | $2.55 | 1秒 $0.51 | | [Atlas Cloud](https://www.atlascloud.ai/models/bytedance/seedance-2.0/text-to-video) | $2.74 | 20%のプロモーションで $2.20 | | [WaveSpeedAI](https://wavespeed.ai/models/bytedance/seedance-2.0/text-to-video) | $3.00 | 1秒 $0.60 | | [fal.ai](https://fal.ai/models/bytedance/seedance-2.0/text-to-video) | $3.41 | 市場の定番で、今も最も高い | 最後の行はよく考える価値があります。fal.ai は多くの開発者が最初に Seedance を探す場所ですが、1秒 $0.682 で、同じモデルに ByteDance 自身の料金より約82%多く請求しています。2.5 でも同じで、720p の動画は公式の $1.16 に対して $2.31、1080p の動画は $2.84 に対して約 $5.69 です。 Seedance 2.5 にも独自の再販業者の顔ぶれがあります。Replicate と OpenRouter は公式料金をそのまま通していますが(720p で $1.16、480p で $0.51)、720p までです。[RunComfy](https://www.runcomfy.com/models/bytedance/seedance-2.5/text-to-video) は現在 2.5 を 720p のみで販売しています(現在の35%プロモーション中は5秒で $1.53)。2.5 を 1080p で販売している業者では、[Poyo](https://poyo.ai/models/seedance-2-5)($2.85)、[Segmind](https://www.segmind.com/models/seedance-2.5/pricing)($2.99)、[Atlas Cloud](https://www.atlascloud.ai/models/bytedance/seedance-2.5/text-to-video)(20%のプロモーションで $2.98、通常 $3.73)が公式との差数パーセント以内、[EachLabs](https://www.eachlabs.ai/bytedance/seedance-2-5/bytedance-seedance-2-5-text-to-video)($3.28)が約15%高く、[EvoLink](https://evolink.ai/seedance-2-5)($3.70)、[Kie.ai](https://kie.ai/seedance-2-5)($3.95)、[PiAPI](https://piapi.ai/seedance-2-5)($4.00)、[WaveSpeedAI](https://wavespeed.ai/models/bytedance/seedance-2.5/text-to-video)($4.50)は30〜60%高くなっています。 公式よりはるかに安く見える表示価格を目にすることもあります。私たちが追跡したものはどれも、標準の動画が安く買えるという話ではありませんでした。価格が安すぎると感じたら、次のパターンに注意してください。 - 標準モデルではない「Turbo」や「高速化」版。ある業者は、ByteDance が公開していない turbo のモデル名で 1080p・5秒の Seedance 2.5 動画を $1.10 としていますが、同じサイトの標準の Seedance 2.5 は $4.50 です。 - 1080p が欲しいのに 720p の価格が示されている。「最安の Seedance」をうたうページのいくつかや、Replicate と OpenRouter の Seedance 2.5 には、1080p の料金がそもそもありません。 - 2.5 のページに 2.0 の価格。Seedance 2.5 はトークン単価が約1.5倍なので、バージョンの書かれていない「Seedance」の価格は比較できません。 - ドル換算の公開されていないクレジット。生成をクレジットで値付けしていても1クレジットの値段が書かれていなければ比較できず、たいていはそれが狙いです。 だからといって、これらの業者が不誠実だというわけではありません。バージョン、解像度、細かい条件がそろって初めて比較に意味が出る、ということです。 ### Seedance API の呼び出し方 上のどの料金も、REST の呼び出し1回で使えます。PixVerse ルートで 1080p の Seedance 2.0 動画を生成する例です。 ```bash curl --location 'https://api.useapi.net/v2/pixverse/videos/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="seedance-2.0"' \ --form 'prompt="A lone lighthouse on a storm-battered cliff at dusk, waves exploding against the rocks, beam sweeping through the rain, cinematic wide shot."' \ --form 'quality="1080p"' \ --form 'duration="5"' \ --form 'aspect_ratio="16:9"' ``` 同じ呼び出しで `model` を `seedance-2.5` に変えれば Seedance 2.5 になり、`duration` は4〜30の範囲で指定できます。また、お使いの Runway アカウントにまだ Explore mode があれば(Runway は新しいアカウントではもう提供しておらず、旧来の Unlimited アカウントでも2026年11月30日に終了します)、同じ形で `exploreMode` を加えると、720p でクレジットを使わずに実行できます。ただし1本ずつで時間がかかります。 ```bash curl --location 'https://api.useapi.net/v1/runwayml/videos/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="seedance-2"' \ --form 'text_prompt="A lone lighthouse on a storm-battered cliff at dusk, waves exploding against the rocks, beam sweeping through the rain, cinematic wide shot."' \ --form 'resolution="720p"' \ --form 'duration="5"' \ --form 'exploreMode="true"' ``` どちらもポーリング用のジョブ ID を返します(動画ができたときに `replyUrl` の Webhook で受け取ることもできます)。参照画像、最初と最後のフレーム、アスペクト比、音声など、すべてのパラメーターは上の表からリンクしている各エンドポイントのページにあります。 ### Seedance 2.0・2.5 にはどのルートを使うべきか - 1080p の Seedance 2.0 を最も安く:年額プランの [PixVerse ルート](/docs/api-pixverse-v2/post-pixverse-videos-create-v4)。Ultra で $1.12、Premium で $1.44 です。年額契約をしなくても、PixVerse の月額(Ultra で $1.49、Premium で $1.80)は公式の $1.87 を下回り、再販業者はすべてそれより高くなります。 - 4K を最も安く:PixVerse ルートの年額 Ultra で $2.48、または年額 Premium で $3.20、次が年額の [MiniMax](/docs/api-minimax-v1/post-minimax-videos-create) で $3.39。いずれも公式の $3.89 を下回ります。 - 1080p の Seedance 2.5 を最も安く:Ultra の年額払いの [PixVerse ルート](/docs/api-pixverse-v2/post-pixverse-videos-create-v4)で、5秒の動画1本 $2.32。次が PixVerse の Premium か、Max の [Runway ルート](/docs/api-runwayml-v1/post-runwayml-videos-create)で、どちらも年額払いで $2.72 です。公式 API の $2.84 を下回ります。 - 4K の Seedance 2.5 を最も安く:Ultra の年額払いの [PixVerse ルート](/docs/api-pixverse-v2/post-pixverse-videos-create-v4)で、5秒の動画1本 $3.91。次がカナダの Advanced プランの [Dreamina ルート](/docs/api-dreamina-v1/post-dreamina-videos)で約 $4.15 です。公式の $4.57 を下回ります。 - 実在の人物の顔を使う Seedance 2.5、または30秒を超える動画:[Dreamina ルート](/docs/api-dreamina-v1/post-dreamina-videos)。 - Seedance 2.0 で実在の人物の顔:[PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4)、[MiniMax](/docs/api-minimax-v1/post-minimax-videos-create)、[Runway](/docs/api-runwayml-v1/post-runwayml-videos-create) のルート。 - Seedance 1.5 Pro や 1.0:1.x 系を扱う唯一のルートである Dreamina ルート。BytePlus は自社 API で 1.5 Pro を終了しています。 ### 作例 各ルートで実際に作った Seedance 2.0 の動画を、私たちのブログ記事から再掲します。同じモデルを別々のプラットフォームで実行したものです。このうち3本は、公式 API では法人契約が必要な、実在の人物の顔を使うワークフローです。 PixVerse · Seedance 2.0(Standard)、1080p。写真の実在の顔を参照映像に入れ、参照音声からせりふを付けるまでを、1回の omni リクエストで行っています。出典:[PixVerse Seedance 2.0: Mini vs Fast vs Standard](/blog/260626a)。 <video poster="https://media.useapi.net/blog/2026-06-26-260626a/omni-standard-1080p-4s-9x16-swap-poster.jpg" src="https://media.useapi.net/blog/2026-06-26-260626a/omni-standard-1080p-4s-9x16-swap.mp4" style="width: 100%; max-width: 420px;" controls type="video/mp4" preload="metadata">Your browser does not support the video element.</video> YouTube でも公開しています:[Seedance 2.0 Omni: Photo + Reference Video + Audio → One Clip (Mini vs Fast vs Standard)](https://youtube.com/shorts/apUc3lXrY_4)。 MiniMax · Seedance 2.0(Standard)、1080p。同じ実在の顔の omni ワークフローを MiniMax ルートで実行したものです。出典:[MiniMax Seedance 2.0: Standard vs Fast vs Mini](/blog/260626b)。 <video poster="https://media.useapi.net/blog/2026-06-26-260626b/std-1080-5s-nowm-poster.jpg" src="https://media.useapi.net/blog/2026-06-26-260626b/std-1080-5s-nowm.mp4" style="width: 100%; max-width: 420px;" controls type="video/mp4" preload="metadata">Your browser does not support the video element.</video> Runway · Seedance 2.0、15秒、9:16。実在の人物の顔を Runway ルートで動かしたもので、このルートは実在の人物へのモデレーションが緩めです。出典:[Seedance 2.0: Using Real Faces](/blog/260415)。 <video poster="https://media.useapi.net/articles/2024-08-11-runway-bash/runway-original-result-poster.jpg" src="https://media.useapi.net/articles/2024-08-11-runway-bash/runway-original-result.mp4" style="width: 100%; max-width: 420px;" controls type="video/mp4" preload="metadata">Your browser does not support the video element.</video> Dreamina · Seedance 2.0、プロンプトだけで口の動きまで合わせたテキストからの動画生成。出典:[Dreamina: Seedance 2.0 Video Generation](/blog/260402)。 <video poster="https://media.useapi.net/blog/2026-04-02-260402/seedance-2.0-prompt-9-16-poster.jpg" src="https://media.useapi.net/blog/2026-04-02-260402/seedance-2.0-prompt-9-16.mp4" style="width: 100%; max-width: 420px;" controls type="video/mp4" preload="metadata">Your browser does not support the video element.</video> 関連チュートリアル:[Dreamina API で Seedance 2.0 の動画を作る](/docs/articles/dreamina-bash)、[Sora 2 API の代替](/docs/articles/sora-2-api-alternatives)、[PixVerse API で PixVerse V6 の動画を作る](/docs/articles/pixverse-demo)。 ## よくある質問 **useapi.net は Seedance の公式 API ですか?** いいえ。useapi.net は、お持ちの [PixVerse](/docs/api-pixverse-v2)、[Runway](/docs/api-runwayml-v1)、[Dreamina](/docs/api-dreamina-v1)、[MiniMax](/docs/api-minimax-v1) のアカウントを自動操作する REST レイヤーで、どのプラットフォームでも Seedance が使えます。ByteDance の従量制の開発者向け API 料金ではなく、それらのプラットフォームの一般向けクレジットを使います。 **Seedance 2.0 は動画1本いくらですか?** useapi.net なら、5秒・1080p の動画は [PixVerse ルート](/docs/api-pixverse-v2/post-pixverse-videos-create-v4)で、Ultra 年額プランなら $1.12、Premium 年額プランなら $1.44(月額なら $1.80)で、ByteDance の公式 API の $1.87 を下回ります。公式 API の5秒の動画は、480p で $0.35、720p で $0.76、1080p で $1.87、4K で $3.89 です(2026年11月13日時点)。[公式の料金表](#official-seedance-20-and-25-api-pricing)をご覧ください。 **Seedance 2.5 の料金はいくらですか?** useapi.net なら、公式 API が制限している実在の顔や30秒を超える動画でも Seedance 2.5 を使えます。[Dreamina ルート](/docs/api-dreamina-v1/post-dreamina-videos)は実在の人物の写真を受け付け、31〜180秒を1回のジョブで作れます。1080p・5秒の動画は年額払いで、PixVerse Ultra なら $2.32、PixVerse Premium か Runway なら $2.72 で、ByteDance の公式 API の $2.84 を下回ります(2026年11月時点)。[Seedance 2.5 の料金](#seedance-25-pricing)をご覧ください。 **1080p の Seedance 2.0 を最も安く使う方法は?** 2026年11月13日と15日に確認した中では、[PixVerse ルート](/docs/api-pixverse-v2/post-pixverse-videos-create-v4)です。Ultra 年額プランで5秒の動画1本 $1.12、Premium 年額プランで $1.44 です。年額契約なしなら PixVerse の月額(Ultra で $1.49、Premium で $1.80)が最安で、ByteDance の公式 $1.87 を下回り、これより安い再販業者はありません(最安の Segmind で $1.97)。[市場の比較表](#seedance-api-pricing-across-resellers)をご覧ください。 **実在の人物の顔で Seedance の動画を作れますか?** はい、useapi.net なら作れます。[PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4)、[Runway](/docs/api-runwayml-v1/post-runwayml-videos-create)、[MiniMax](/docs/api-minimax-v1/post-minimax-videos-create) のルートは 2.0 で実在の顔を受け付け(MiniMax は参照画像で)、[Dreamina ルート](/docs/api-dreamina-v1/post-dreamina-videos)は 2.5 で受け付けます。公式 API は 2.0 でも 2.5 でも、実在の顔を含む参照入力を認証済みアセットか、年 $14,000 からの法人契約に限っています。 **useapi.net はなぜ ByteDance 自身の API より安いのですか?** Seedance 2.0 では、PixVerse(月額でも年額でも)、Runway、Dreamina、MiniMax(年額)の一般向けプランが、同じ生成を従量制の開発者向け料金より安く提供しています。useapi.net はそのアカウントの1つを REST で自動操作し、1つの[サブスクリプション](/docs/subscription)ですべてのサービスを使えます。Seedance 2.5 ではたいてい安くなりません。1080p で PixVerse か Runway の年額プランを使う場合を除けば公式料金のほうが安く、私たちのルートの強みは、実在の顔、より長い動画、前払いパックが不要なことにあります。 **ほかで見かける1ドル未満の Seedance の価格は本当ですか?** 標準の 1080p の動画については、たいてい違います。多くは 720p の料金、2.5 のページに載った 2.0 の価格、補助の入った定額プラン、蒸留された「turbo」版、またはドル換算が公開されていないクレジットです。[市場全体のセクション](#seedance-api-pricing-across-resellers)をご覧ください。 --- 試してみませんか? この比較全体が1つのスクリプトになっています。[github.com/useapi/seedance-2-api](https://github.com/useapi/seedance-2-api) は、プロンプトを4つのルートすべてに送り、それぞれの料金と速度を表示します。アカウントなしで使える料金計算ツールも付いています。次にルートを選びます。1080p の Seedance 2.0 を最も安く使うなら [PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4)、実在の顔と長い動画で Seedance 2.5 を使うなら [Dreamina](/docs/api-dreamina-v1/post-dreamina-videos) です。アカウントを接続すれば、[useapi.net のサブスクリプション](/docs/subscription)1つで、トークン1つから4つすべてを操作できます。この記事の料金は2026年11月13日時点のもので、この市場は毎月のように変わるので、規模を広げる前に最新の料金を確認してください。 #### ほかの掲載先 {: .no_toc #cross-posted } この記事(英語版)は [dev.to](https://dev.to/useapi/seedance-20-api-pricing-the-cheapest-ways-to-run-it-compared-4kno){:rel="nofollow"} にも掲載しています。 ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/seedance-2-api-pricing-pt === Document URL: https://useapi.net/docs/articles/seedance-2-api-pricing-pt --- layout: default title: "Preços da API do Seedance 2.0 e 2.5: todas as rotas comparadas" seo_title: "Preço da API do Seedance 2.0 e 2.5: todas as rotas" description: "Quanto custa um vídeo de 5 segundos do Seedance 2.0 ou 2.5 na API oficial da ByteDance, em uma dúzia de revendedores e em quatro rotas da useapi.net, conferido de novo em 13 de novembro de 2026." keywords: [API do Seedance 2.0, API do Seedance 2.5, preço do Seedance, preço do Seedance 2.0, preço do Seedance 2.5, preço da API do Seedance, custo por vídeo do Seedance, API de vídeo da ByteDance, API de texto para vídeo, Seedance 2.0 API, Seedance 2.5 API, Seedance pricing, Seedance 2.0 pricing, Seedance 2.5 pricing, Seedance 2.0 price, Seedance cost per video, Seedance API cost, ByteDance video API, BytePlus ModelArk Seedance, fal.ai Seedance, Replicate Seedance, PixVerse Seedance, Runway Seedance, Dreamina Seedance, text to video API] image: /assets/images/articles/seedance-2-api-pricing-2026-10.jpg parent: Articles nav_exclude: true lang: pt-BR translation_key: seedance-2-pricing date: 2026-07-21 repo: https://github.com/useapi/seedance-2-api last_modified: 2026-11-18 nav_order: 90 --- ## Preços da API do Seedance 2.0 e 2.5: todas as rotas comparadas {: .no_toc #seedance-20-and-25-api-pricing-every-route-compared } 13 min de leitura • 21 de julho de 2026 (18 de novembro de 2026) ## Sumário {: .no_toc .text-delta #table-of-contents } ### Introdução Um vídeo de 5 segundos do Seedance 2.0 em 1080p custa $1,87 na API oficial da ByteDance, e o menor preço por vídeo que verificamos é $1,12, pela rota PixVerse da useapi.net, num plano Ultra anual ($1,49 no mensal), ou $1,44 num plano Premium anual ($1,80 no mensal). Nenhum revendedor fica mais abaixo disso (o mais barato, o Segmind, cobra $1,97). Com o Seedance 2.5 a história é outra. A $2,84 por vídeo em 1080p, o preço da própria ByteDance bate todos os revendedores e todos os planos mensais que encontramos, e só os planos anuais ficam um pouco abaixo dele: o PixVerse Ultra ($2,32), e o PixVerse Premium ou o Runway Max ($2,72). Em 13 de novembro de 2026 (a rota PixVerse de novo em 15 de novembro) relemos os preços dos dois canais oficiais da ByteDance e de uma dúzia de fornecedores terceiros nas páginas ao vivo deles, recalculamos as nossas quatro rotas a partir das taxas de crédito atuais e normalizamos tudo numa unidade só: o custo em dólares de um vídeo de 5 segundos, de texto para vídeo, sem vídeo de entrada. O cenário mudou desde a primeira publicação, em julho. O PixVerse mudou os preços do Seedance e encerrou o desconto dos planos Pro e Premium, o que levou a rota dele de $1,20 para $1,80 por vídeo num plano mensal. A ByteDance lançou o Seedance 2.5 com uma taxa por token cerca de 50% maior que a do 2.0, e a maioria dos revendedores lançou faixas de 2.5 em seguida. Vale deixar claro onde nós estamos. A useapi.net é uma camada em que você traz a sua própria conta, não um revendedor oficial da ByteDance. Nós controlamos a sua própria conta do [PixVerse](/docs/api-pixverse-v2), do [Runway](/docs/api-runwayml-v1), do [Dreamina](/docs/api-dreamina-v1) ou do [MiniMax](/docs/api-minimax-v1) por uma única API REST, então você gasta os créditos de consumidor dessas plataformas em vez da tarifa medida da API para desenvolvedores. Cada número abaixo traz a data e a fonte, e os preços desse mercado mudam todo mês, então confira de novo antes de se comprometer com um gasto. Uma única assinatura da useapi.net roda o Seedance 2.0 e 2.5 nas quatro rotas abaixo, no plano do PixVerse, Runway, Dreamina ou MiniMax que você já tem, e cobre todas as outras APIs do site. [Assine — $15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03?client_reference_id={{ page.url | slugify | default: 'home' }}){: .btn .btn-purple .mr-2 .mb-3 } [Compare as quatro rotas](#four-ways-to-run-seedance-20-through-useapinet) ### Preços da API oficial do Seedance 2.0 e 2.5 A ByteDance vende o Seedance por dois canais oficiais: o [BytePlus ModelArk](https://docs.byteplus.com/en/docs/ModelArk/1544106) no mercado internacional e o [Volcano Engine](https://www.volcengine.com/docs/82379/1544106) na China. Os dois cobram por milhão de tokens, e a contagem de tokens de um vídeo é `width × height × 24fps × seconds ÷ 1024`. Um vídeo de 5 segundos em 1080p tem 243.000 tokens. O Seedance 2.0 cobra $7,7 por milhão em 1080p, então esse vídeo sai por $1,87. O Seedance 2.5 cobra $11,7 por milhão em 1080p, então o mesmo vídeo sai por $2,84. Normalizado, segundo a página de preços do BytePlus (lida em 13 de novembro de 2026): | Resolução | Seedance 2.0, 5s | Seedance 2.0, 10s | Seedance 2.5, 5s | Seedance 2.5, 10s | |:-----------|-----------------:|------------------:|-----------------:|------------------:| | 480p | $0,35 | $0,70 | $0,51 | $1,03 | | 720p | $0,76 | $1,51 | $1,16 | $2,31 | | 1080p | $1,87 | $3,74 | $2,84 | $5,69 | | 4K | $3,89 | $7,78 | $4,57 | $9,14 | O Seedance 2.5 chegou ao 4K no BytePlus em 16 de novembro de 2026, a $4,57 por um vídeo de 5 segundos sem vídeo de entrada, faz vídeos de até 30 segundos, contra 15 do 2.0, e aceita até 50 referências (30 imagens, 10 vídeos, 10 clipes de áudio). Um vídeo 2.5 completo de 30 segundos em 1080p custa cerca de $17. O Seedance 2.0 Fast e o Mini continuam mais baratos e ainda param em 720p: um vídeo de 5 segundos em 720p sai por $0,60 no Fast e $0,38 no Mini. O novo Seedance 2.5 Flash também para em 720p, a $0,76 por um vídeo de 5 segundos em 720p, e o BytePlus o libera para chamadas de API em 15 de novembro de 2026. O áudio vem incluído, sem custo extra. O Volcano cobra ¥77 por milhão de tokens pelo 2.5 em 1080p, mas exige verificação chinesa de nome real e de rosto, então na prática é só para a China. O preço de tabela não é o custo inteiro. Ativar o Seedance no BytePlus custa cerca de $30 adiantados: um [pacote de recursos](https://docs.byteplus.com/en/docs/ModelArk/2191775) pré-pago (os menores custam $30,10 para o 2.0 e $32 para o 2.5, não reembolsáveis, e expiram em 90 dias) ou a recarga de saldo de $30 que o BytePlus recomenda. Contas individuais ficam limitadas a 3 tarefas simultâneas (180 requisições/minuto), e o 4K fica limitado a uma única tarefa simultânea para todo mundo. Nada disso torna a API oficial um mau negócio. Ela define a régua pela qual toda alternativa deve ser medida. ### Quatro jeitos de rodar o Seedance 2.0 pela useapi.net Um único token da useapi.net roda o Seedance 2.0 em quatro plataformas, no plano da conta que você já paga. Os custos abaixo são o custo do plano por vídeo de 5 segundos em 1080p, calculado a partir das taxas de crédito e dos preços de plano da nossa documentação. | Rota | Modelos Seedance | 5s 1080p, plano mensal | 5s 1080p, plano anual | Destaque | |:------|:----------------|-----------------------:|----------------------:|:---------------| | [PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) | 2.5, 2.5 Flash, 2.5 Draft, 2.0, Fast, Mini | $1,80 | $1,44 | 2.0 em 1080p e 4K mais baratos ($1,49 e $1,12 no Ultra), rostos humanos reais | | [Dreamina](/docs/api-dreamina-v1/post-dreamina-videos) | 2.5, 2.5 Flash, 2.0, Fast, Mini, 1.5 Pro, família 1.0 | ~$1,83–1,87 | ~$1,78–1,81 | Seedance 2.5 com rostos reais e vídeos longos, mais modelos | | [MiniMax](/docs/api-minimax-v1/post-minimax-videos-create) | 2.0, Fast, Mini | $2,00 | $1,70 | 4K e um fluxo rico com imagens de referência | | [Runway](/docs/api-runwayml-v1/post-runwayml-videos-create) | 2.5, 2.0, Fast, Mini | $2,00 | $1,60 | rostos reais, moderação mais leve que a do Dreamina | A rota PixVerse cobra o Seedance 2.0 a 90 créditos por segundo em 1080p, então um vídeo de 5 segundos custa 450 créditos. No plano Premium de $60/mês ($0,004 por crédito), isso dá $1,80, e no Premium com cobrança anual ($0,0032 por crédito), $1,44. Os créditos do Ultra custam mais, mas no Ultra o PixVerse dá 50% de desconto no Seedance 2.0, a menos que a requisição envie `relax_mode: false`, o que leva um vídeo a $1,49, ou $1,12 com cobrança anual (o Ultra custa $199 por mês por 30.000 créditos, em 15 de novembro de 2026). No preço cheio, que é o que paga uma requisição com `relax_mode: false`, um vídeo no Ultra custa $2,99. O PixVerse também chega a 2160p (4K) no Seedance 2.0, a $4,00 por 5 segundos no Premium, ou $3,20 com cobrança anual, e $3,32 ou $2,48 no Ultra, o 4K mais barato que encontramos. Em julho essa rota custava $1,20 por vídeo. Desde então o PixVerse mudou os preços da família Seedance e encerrou o desconto que os planos Pro e Premium tinham, e essa é a maior mudança desta atualização ([tabelas de custo do PixVerse](/docs/api-pixverse-v2)). A vantagem real da rota Dreamina é o Seedance 2.5: ela aceita rostos reais e faz vídeos longos, de 31 a 180 segundos, num único job, o que a API oficial não faz ([Preços do Seedance 2.5](#seedance-25-pricing)). No Seedance 2.0 em 1080p ela praticamente empata com a API oficial. A 57 créditos por segundo num plano Advanced da região do Canadá, um vídeo de 5 segundos sai por cerca de $1,83 com cobrança mensal (C$109,99 por 11.997 créditos) e $1,81 com cobrança anual (C$1.299,99), contra $1,87. Um plano Advanced dos EUA roda a 41 créditos por segundo, cerca de $1,87 com cobrança mensal ($79 por 8.645 créditos) e $1,78 com cobrança anual ($900). As duas regiões rodam 1080p e 4K, e a família 2.0 do Dreamina rejeita rostos humanos reais. Os preços dos planos e as taxas de crédito foram lidos de novo em 12 de novembro de 2026, convertidos a CAD/USD 0,7023 ([calculadora de custos do Dreamina](/docs/start-here/setup-dreamina#cost-calculator)). A rota MiniMax cobra o Seedance 2.0 a 50 créditos por segundo em 1080p, sem mudança desde julho, que é o desconto de 50% do MiniMax no Seedance, anunciado como oferta por tempo limitado (em 12 de novembro de 2026). O MiniMax também mudou os preços dos planos. O plano Master de $89 (10.500 créditos) põe um vídeo a $2,12, o plano Max de $216 (27.000 créditos) a $2,00, e o Master com cobrança anual a $1,70, com 4K a $3,39 nesse plano anual. A rota Runway agora também tem um preço publicado. O Seedance 2.0 dela custa 40 créditos por segundo em 1080p, o que dá $2,00 por vídeo no plano Max de $95 do Runway e $1,60 com cobrança anual ([calculadora de custos do Runway](/docs/api-runwayml-v1)). O antigo `exploreMode` do Runway ainda roda o Seedance em 480p e 720p sem gastar créditos em contas Unlimited antigas que já têm o Explore mode ativado, até o Runway migrar essas contas para o Max em 30 de novembro de 2026. O Runway não ativa mais esse modo em contas novas, e ele é lento: um vídeo por vez, cerca de 10 a 15 minutos cada. Trate-o como um bônus se você já o tem, não como motivo para escolher o Runway. Esses são custos de plano por vídeo, e os mais baratos pressupõem um compromisso anual que você realmente use. O Premium com cobrança anual custa $576 adiantados por 15.000 créditos por mês, cerca de 33 vídeos em 1080p por mês, e o Ultra com cobrança anual custa $1.788 por 30.000 créditos por mês, cerca de 133 vídeos. Vale citar as contrapartidas. As nossas rotas automatizam contas de consumidor, então o número de jobs simultâneos depende da conta (normalmente 5–10 jobs em paralelo, contra os limites por chave da API oficial), e as plataformas mudam os preços sem aviso, como o PixVerse acabou de fazer. Em troca, você tem um custo por vídeo abaixo do oficial no 2.0 em planos anuais (e no PixVerse mensal), nenhum pacote pré-pago e um único token para as quatro plataformas. ### Preços do Seedance 2.5 O Seedance 2.5 roda em três das nossas quatro rotas: [PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4), [Dreamina](/docs/api-dreamina-v1/post-dreamina-videos) e [Runway](/docs/api-runwayml-v1/post-runwayml-videos-create). O MiniMax não o oferece. No 2.5, a diferença maior está no que a API oficial não faz. O próprio [guia do Seedance 2.5](https://docs.byteplus.com/en/docs/modelark/seedance-2-5) da ByteDance diz que o 2.5 "does not support directly uploading reference images or videos containing real human faces" (não aceita o envio direto de imagens ou vídeos de referência com rostos humanos reais), e a API oficial para em 30 segundos por vídeo. A [rota Dreamina aceita rostos reais no 2.5](/docs/api-dreamina-v1/post-dreamina-videos) diretamente e acrescenta um modo de vídeo longo, de 31 a 180 segundos num único job, além de edição de vídeo, e em contas do Canadá gera o 2.5 em 4K por cerca de $4,15 por vídeo de 5 segundos no plano Advanced do Canadá, abaixo dos $4,57 oficiais. A [rota Runway](/docs/api-runwayml-v1/post-runwayml-videos-create) também aceita rostos reais no Seedance, e não há pacote pré-pago de cerca de $30 para comprar antes do primeiro vídeo. Em 1080p, as nossas rotas PixVerse e Runway também custam menos por vídeo que a tarifa da própria ByteDance num plano anual. Um vídeo de 5 segundos, sem vídeo de entrada: | Rota | 1080p, 5 s | Duração máx. | |:------|-----------:|:-----------| | [PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) *(Ultra, cobrança anual)* | $2,32 | 30s | | [PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) *(Premium, cobrança anual)* | $2,72 | 30s | | [Runway](/docs/api-runwayml-v1/post-runwayml-videos-create) *(Max, cobrança anual)* | $2,72 | 30s | | [BytePlus oficial](https://docs.byteplus.com/en/docs/ModelArk/1544106) | $2,84 | 30s | O PixVerse cobra o 2.5 a 170 créditos por segundo em 1080p ($0,0032 por crédito no Premium com cobrança anual), e o Ultra dá 45% de desconto, 468 créditos por vídeo a $0,00497 por crédito com cobrança anual ($3,10 num plano Ultra mensal). O Runway cobra 68 créditos por segundo em 1080p ($0,008 por crédito no Max com cobrança anual, $76 por mês por 9.500 créditos, em 13 de novembro de 2026). As tarifas anuais pressupõem que você use os créditos do plano. O PixVerse agora também gera o Seedance 2.5 em 4K (2160p), a 286 créditos por segundo (em 15 de novembro de 2026). Um vídeo 4K de 5 segundos custa 1.430 créditos, ou 787 com o desconto do Ultra, o que dá $3,91 no Ultra com cobrança anual, contra $4,57 na API da própria ByteDance (em 18 de novembro de 2026). ### A lacuna dos rostos reais Tanto o Seedance 2.0 quanto o 2.5 rejeitam, na API oficial, imagens e vídeos de referência com rostos humanos reais, a menos que o rosto venha de uma saída recente do próprio modelo, de um personagem digital predefinido ou de um ativo de pessoa real verificado. Trabalhar com referências de pessoas reais em escala exige os "Advanced Creation Rights" corporativos da ByteDance: [$14.000 por ano ou $1.400 por mês](https://docs.byteplus.com/en/docs/modelark/2377608) por um milhão de ativos, $42.000 por ano por cinco milhões, com verificação de empresa obrigatória. As nossas rotas aliviam isso em quatro pontos. A [rota PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) aceita rostos humanos reais no Seedance 2.0, a [rota Runway](/docs/api-runwayml-v1/post-runwayml-videos-create) documenta suporte a rostos reais no Seedance e, em geral, uma moderação mais leve que a do Dreamina, a [rota MiniMax](/docs/api-minimax-v1/post-minimax-videos-create) aceita rostos reais em imagens de referência (vídeos de referência com rostos reconhecíveis continuam moderados), e a [rota Dreamina](/docs/api-dreamina-v1/post-dreamina-videos) aceita retratos fotográficos no Seedance 2.5, mas não na família 2.0. Para publicidade, UGC e fluxos de criadores que giram em torno de uma pessoa real, essa diferença pesa mais que alguns centavos por vídeo, e não exige contrato corporativo. ### Preços da API do Seedance nos revendedores A maioria dos fornecedores terceiros de Seedance revende a própria API da ByteDance com uma margem por cima. Aqui está o Seedance 2.0 em 5 segundos e 1080p, com cada preço de terceiros lido da página ao vivo do fornecedor em 13 de novembro de 2026: | Fornecedor | 5s 1080p | Observações | |:-------|---------:|:------| | [useapi.net (rota PixVerse)](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) | $1,12–1,80 | créditos de conta de consumidor, do Ultra anual ao Premium mensal | | [useapi.net (rota Runway)](/docs/api-runwayml-v1/post-runwayml-videos-create) | $1,60–2,00 | plano Max, anual ou mensal | | [useapi.net (rota MiniMax)](/docs/api-minimax-v1/post-minimax-videos-create) | $1,70–2,12 | Master anual a Master mensal ($2,00 no Max mensal) | | [useapi.net (rota Dreamina)](/docs/api-dreamina-v1/post-dreamina-videos) | ~$1,78–1,87 | contas dos EUA ou do Canadá, Advanced anual ou mensal, lido em 12 de novembro de 2026 | | [BytePlus oficial](https://docs.byteplus.com/en/docs/ModelArk/1544106) | $1,87 | a referência, igualada exatamente pelo repasse do OpenRouter | | [Segmind](https://www.segmind.com/models/seedance-2.0/pricing) | $1,97 | acima do oficial desde novembro ($8,105 por milhão de tokens em 1080p) | | [RunComfy](https://www.runcomfy.com/models/bytedance/seedance-v2/pro) | $2,00 | $0,40 por segundo, abaixo dos $0,55 de julho | | [EachLabs](https://www.eachlabs.ai/bytedance/seedance-2-0/bytedance-seedance-2-0-text-to-video) | $2,22 | cerca de $0,444 por segundo, abaixo dos $0,60 | | [Replicate](https://replicate.com/bytedance/seedance-2.0) | $2,25 | selo de modelo "Official", $0,45 por segundo gerado | | [Poyo.ai](https://poyo.ai/models/seedance-2) | $2,25 | $0,45 por segundo | | [EvoLink](https://evolink.ai/seedance-2-0) | $2,48 | $0,497 por segundo | | [PiAPI](https://piapi.ai/seedance-2-0) | $2,50 | $0,50 por segundo | | [Kie.ai](https://kie.ai/seedance-2-0) | $2,55 | $0,51 por segundo | | [Atlas Cloud](https://www.atlascloud.ai/models/bytedance/seedance-2.0/text-to-video) | $2,74 | $2,20 com uma promoção de 20% | | [WaveSpeedAI](https://wavespeed.ai/models/bytedance/seedance-2.0/text-to-video) | $3,00 | $0,60 por segundo | | [fal.ai](https://fal.ai/models/bytedance/seedance-2.0/text-to-video) | $3,41 | o padrão do mercado, e ainda o mais caro | Vale olhar com calma essa última linha. O fal.ai é onde muitos desenvolvedores procuram o Seedance primeiro, e a $0,682 por segundo ele cobra cerca de 82% a mais que a tarifa da própria ByteDance pelo mesmo modelo. O mesmo acontece no 2.5, em que o vídeo em 720p dele custa $2,31 contra $1,16 no oficial, e o vídeo em 1080p cerca de $5,69 contra $2,84. O Seedance 2.5 tem o seu próprio grupo de revendedores. O Replicate e o OpenRouter repassam a tarifa oficial exatamente ($1,16 em 720p, $0,51 em 480p), mas param em 720p, e o [RunComfy](https://www.runcomfy.com/models/bytedance/seedance-2.5/text-to-video) agora vende o 2.5 só em 720p ($1,53 por 5 segundos durante a promoção atual de 35%). Entre os fornecedores que vendem o 2.5 em 1080p, o [Poyo](https://poyo.ai/models/seedance-2-5) ($2,85), o [Segmind](https://www.segmind.com/models/seedance-2.5/pricing) ($2,99) e o [Atlas Cloud](https://www.atlascloud.ai/models/bytedance/seedance-2.5/text-to-video) ($2,98 com a promoção de 20%, $3,73 sem ela) ficam a poucos por cento do oficial, o [EachLabs](https://www.eachlabs.ai/bytedance/seedance-2-5/bytedance-seedance-2-5-text-to-video) ($3,28) fica cerca de 15% acima, e o [EvoLink](https://evolink.ai/seedance-2-5) ($3,70), o [Kie.ai](https://kie.ai/seedance-2-5) ($3,95), o [PiAPI](https://piapi.ai/seedance-2-5) ($4,00) e o [WaveSpeedAI](https://wavespeed.ai/models/bytedance/seedance-2.5/text-to-video) ($4,50) ficam 30–60% acima. Você também vai ver preços de tabela muito abaixo do oficial. Todos os que investigamos se revelaram outra coisa que não um vídeo padrão mais barato. Alguns padrões a observar quando um preço parece bom demais: - Variantes "turbo" ou "aceleradas" que não são o modelo padrão: um fornecedor anuncia um vídeo Seedance 2.5 de 5 segundos em 1080p a $1,10 sob um nome de modelo turbo que a ByteDance não publica, enquanto o Seedance 2.5 padrão custa $4,50 no mesmo site. - Preços em 720p quando você queria 1080p: várias páginas de "Seedance mais barato", e as ofertas de Seedance 2.5 no Replicate e no OpenRouter, não têm nenhuma faixa de 1080p. - Preços do 2.0 numa página sobre o 2.5: o Seedance 2.5 custa cerca de 50% a mais por token, então um preço de "Seedance" sem número de versão não é comparável. - Créditos sem valor em dólar publicado: se uma página cobra gerações em créditos mas nunca diz quanto custa um crédito, não dá para comparar, e geralmente é essa a intenção. Nada disso quer dizer que esses fornecedores sejam desonestos. Quer dizer que versão, resolução e letras miúdas precisam bater antes que uma comparação signifique alguma coisa. ### Como chamar a API do Seedance Cada preço acima está a uma chamada REST de distância. Gere um vídeo Seedance 2.0 em 1080p pela rota PixVerse: ```bash curl --location 'https://api.useapi.net/v2/pixverse/videos/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="seedance-2.0"' \ --form 'prompt="A lone lighthouse on a storm-battered cliff at dusk, waves exploding against the rocks, beam sweeping through the rain, cinematic wide shot."' \ --form 'quality="1080p"' \ --form 'duration="5"' \ --form 'aspect_ratio="16:9"' ``` A mesma chamada roda o Seedance 2.5 trocando `model` para `seedance-2.5`, com `duration` de 4 a 30. Ou, se a sua conta do Runway ainda tem o Explore mode (o Runway não o oferece mais em contas novas e o encerra nas contas Unlimited antigas em 30 de novembro de 2026), o mesmo formato roda sem créditos em 720p acrescentando `exploreMode`, um vídeo lento por vez: ```bash curl --location 'https://api.useapi.net/v1/runwayml/videos/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="seedance-2"' \ --form 'text_prompt="A lone lighthouse on a storm-battered cliff at dusk, waves exploding against the rocks, beam sweeping through the rain, cinematic wide shot."' \ --form 'resolution="720p"' \ --form 'duration="5"' \ --form 'exploreMode="true"' ``` As duas devolvem um id de job para consultar (ou um webhook `replyUrl` quando o vídeo fica pronto). O conjunto completo de parâmetros (imagens de referência, primeiro e último quadro, proporções e áudio) está na página de cada endpoint linkada nas tabelas acima. ### Qual rota usar para o Seedance 2.0 ou 2.5? - Seedance 2.0 em 1080p mais barato: a [rota PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) num plano anual, $1,12 no Ultra ou $1,44 no Premium. Sem compromisso anual, o PixVerse mensal ($1,49 no Ultra, $1,80 no Premium) ainda fica abaixo dos $1,87 oficiais, e todos os revendedores ficam acima disso. - 4K mais barato: a rota PixVerse a $2,48 no Ultra anual ou $3,20 no Premium anual, depois o [MiniMax](/docs/api-minimax-v1/post-minimax-videos-create) a $3,39 no anual, todos abaixo dos $3,89 oficiais. - Seedance 2.5 em 1080p mais barato: a [rota PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) no Ultra com cobrança anual, $2,32 por vídeo de 5 segundos, depois o PixVerse Premium ou a [rota Runway](/docs/api-runwayml-v1/post-runwayml-videos-create) no Max, os dois com cobrança anual, a $2,72, contra $2,84 na API oficial. - Seedance 2.5 em 4K mais barato: a [rota PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) no Ultra com cobrança anual, $3,91 por vídeo de 5 segundos, depois a [rota Dreamina](/docs/api-dreamina-v1/post-dreamina-videos) no plano Advanced do Canadá, a cerca de $4,15, contra $4,57 na API oficial. - Seedance 2.5 com rostos humanos reais, ou vídeos com mais de 30 segundos: a [rota Dreamina](/docs/api-dreamina-v1/post-dreamina-videos). - Rostos humanos reais no Seedance 2.0: a rota [PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4), [MiniMax](/docs/api-minimax-v1/post-minimax-videos-create) ou [Runway](/docs/api-runwayml-v1/post-runwayml-videos-create). - Seedance 1.5 Pro ou 1.0: a rota Dreamina, a única com a família 1.x. O BytePlus aposentou o 1.5 Pro na própria API. ### Exemplos Saídas reais do Seedance 2.0 de cada rota, reaproveitadas dos nossos posts no blog: o mesmo modelo, rodando em plataformas diferentes. Três delas usam rostos humanos reais, o fluxo que a API oficial só libera com um contrato corporativo. PixVerse · Seedance 2.0 (Standard), 1080p: um rosto real de uma foto colocado num vídeo de referência e com fala vinda de um clipe de áudio de referência, tudo numa única requisição omni. De [PixVerse Seedance 2.0: Mini vs Fast vs Standard](/blog/260626a). <video poster="https://media.useapi.net/blog/2026-06-26-260626a/omni-standard-1080p-4s-9x16-swap-poster.jpg" src="https://media.useapi.net/blog/2026-06-26-260626a/omni-standard-1080p-4s-9x16-swap.mp4" style="width: 100%; max-width: 420px;" controls type="video/mp4" preload="metadata">Your browser does not support the video element.</video> Também no YouTube: [Seedance 2.0 Omni: Photo + Reference Video + Audio → One Clip (Mini vs Fast vs Standard)](https://youtube.com/shorts/apUc3lXrY_4). MiniMax · Seedance 2.0 (Standard), 1080p: o mesmo fluxo omni com rosto real na rota MiniMax. De [MiniMax Seedance 2.0: Standard vs Fast vs Mini](/blog/260626b). <video poster="https://media.useapi.net/blog/2026-06-26-260626b/std-1080-5s-nowm-poster.jpg" src="https://media.useapi.net/blog/2026-06-26-260626b/std-1080-5s-nowm.mp4" style="width: 100%; max-width: 420px;" controls type="video/mp4" preload="metadata">Your browser does not support the video element.</video> Runway · Seedance 2.0, 15 segundos, 9:16: um rosto real animado na rota Runway, que aplica uma moderação mais leve a pessoas reais. De [Seedance 2.0: Using Real Faces](/blog/260415). <video poster="https://media.useapi.net/articles/2024-08-11-runway-bash/runway-original-result-poster.jpg" src="https://media.useapi.net/articles/2024-08-11-runway-bash/runway-original-result.mp4" style="width: 100%; max-width: 420px;" controls type="video/mp4" preload="metadata">Your browser does not support the video element.</video> Dreamina · Seedance 2.0, texto para vídeo com sincronia labial a partir só do prompt. De [Dreamina: Seedance 2.0 Video Generation](/blog/260402). <video poster="https://media.useapi.net/blog/2026-04-02-260402/seedance-2.0-prompt-9-16-poster.jpg" src="https://media.useapi.net/blog/2026-04-02-260402/seedance-2.0-prompt-9-16.mp4" style="width: 100%; max-width: 420px;" controls type="video/mp4" preload="metadata">Your browser does not support the video element.</video> Tutoriais relacionados: [vídeo com Seedance 2.0 pela API do Dreamina](/docs/articles/dreamina-bash), [alternativas à API do Sora 2](/docs/articles/sora-2-api-alternatives) e [vídeo com PixVerse V6 pela API do PixVerse](/docs/articles/pixverse-demo). ## Perguntas frequentes **A useapi.net é uma API oficial do Seedance?** Não. A useapi.net é uma camada REST que automatiza a sua própria conta do [PixVerse](/docs/api-pixverse-v2), do [Runway](/docs/api-runwayml-v1), do [Dreamina](/docs/api-dreamina-v1) ou do [MiniMax](/docs/api-minimax-v1), e todas elas rodam o Seedance. Você gasta os créditos de consumidor dessas plataformas em vez da tarifa medida da API para desenvolvedores da ByteDance. **Quanto custa um vídeo do Seedance 2.0?** Pela useapi.net, um vídeo de 5 segundos em 1080p custa $1,12 na [rota PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) num plano Ultra anual, ou $1,44 no Premium anual ($1,80 no mensal), contra $1,87 na API oficial da ByteDance. A API oficial cobra $0,35 em 480p, $0,76 em 720p, $1,87 em 1080p e $3,89 em 4K por um vídeo de 5 segundos, em 13 de novembro de 2026. Veja [a tabela de preços oficial](#official-seedance-20-and-25-api-pricing). **Quanto custa o Seedance 2.5?** Pela useapi.net, o Seedance 2.5 roda com rostos reais e em vídeos de mais de 30 segundos, o que a API oficial restringe: a [rota Dreamina](/docs/api-dreamina-v1/post-dreamina-videos) aceita fotos reais e faz de 31 a 180 segundos num único job. Em 1080p, um vídeo de 5 segundos custa $2,32 no PixVerse Ultra e $2,72 no PixVerse Premium ou no Runway, com cobrança anual, contra $2,84 na API oficial da ByteDance (em novembro de 2026). Veja [Preços do Seedance 2.5](#seedance-25-pricing). **Qual o jeito mais barato de rodar o Seedance 2.0 em 1080p?** De tudo o que verificamos em 13 e 15 de novembro de 2026, a [rota PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4): $1,12 por vídeo de 5 segundos num plano Ultra anual, ou $1,44 no Premium anual. Sem compromisso anual, o PixVerse mensal ($1,49 no Ultra, $1,80 no Premium) é o mais barato, abaixo dos $1,87 oficiais da ByteDance, e nenhum revendedor fica abaixo dele (o Segmind, o mais barato, cobra $1,97). Veja [a tabela do mercado](#seedance-api-pricing-across-resellers). **Dá para gerar vídeos do Seedance com rostos humanos reais?** Sim, pela useapi.net: as rotas [PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4), [Runway](/docs/api-runwayml-v1/post-runwayml-videos-create) e [MiniMax](/docs/api-minimax-v1/post-minimax-videos-create) aceitam rostos reais no 2.0 (o MiniMax em imagens de referência), e a [rota Dreamina](/docs/api-dreamina-v1/post-dreamina-videos) os aceita no 2.5. A API oficial restringe referências com rostos reais, no 2.0 e no 2.5, a ativos verificados ou a um contrato corporativo a partir de $14.000 por ano. **Como a useapi.net cobra menos que a própria API da ByteDance?** No Seedance 2.0, os planos de consumidor do PixVerse (mensal ou anual), do Runway, do Dreamina e do MiniMax (anual) cobram pela mesma geração menos que a tarifa medida para desenvolvedores, e a useapi.net automatiza uma dessas contas por REST, com uma única [assinatura](/docs/subscription) para todos os serviços. No Seedance 2.5 isso quase nunca acontece: a tarifa oficial é menor, exceto contra um plano anual do PixVerse ou do Runway em 1080p, e as nossas rotas ganham em rostos reais, vídeos mais longos e na ausência de pacote pré-pago. **Os preços de Seedance abaixo de um dólar que vejo por aí são reais?** Normalmente não para um vídeo padrão em 1080p. Costumam ser preços de 720p, preços do 2.0 numa página do 2.5, planos de valor fixo subsidiados, variantes "turbo" destiladas ou créditos sem valor em dólar publicado. Veja [a seção sobre o mercado](#seedance-api-pricing-across-resellers). --- Quer experimentar? A comparação inteira é um único script: [github.com/useapi/seedance-2-api](https://github.com/useapi/seedance-2-api) envia um prompt para as quatro rotas e mostra o custo e a velocidade de cada uma, junto com uma calculadora de preços que você roda sem conta nenhuma. Depois escolha uma rota ([PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) para o Seedance 2.0 em 1080p mais barato, [Dreamina](/docs/api-dreamina-v1/post-dreamina-videos) para o Seedance 2.5 com rostos reais e vídeos longos), conecte a conta, e uma [assinatura da useapi.net](/docs/subscription) roda as quatro com um único token. Os preços deste artigo valiam em 13 de novembro de 2026, e esse mercado muda todo mês, então confirme a tarifa atual antes de escalar. #### Publicado também em {: .no_toc #cross-posted } Também publicado no [dev.to](https://dev.to/useapi/seedance-20-api-pricing-the-cheapest-ways-to-run-it-compared-4kno){:rel="nofollow"} (em inglês). ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/seedance-2-api-pricing-th === Document URL: https://useapi.net/docs/articles/seedance-2-api-pricing-th --- layout: default title: "ราคา Seedance 2.0 และ 2.5 API: เทียบทุกช่องทาง" seo_title: "ราคา Seedance 2.0 และ 2.5 API: คลิปละเท่าไร เทียบทุกช่องทาง" description: "คลิป Seedance 2.0 หรือ 2.5 ยาว 5 วินาทีมีค่าใช้จ่ายเท่าไรบน API ทางการของ ByteDance ผู้ขายต่อราว 12 ราย และสี่ช่องทางของ useapi.net ตรวจสอบใหม่เมื่อ 13 พฤศจิกายน 2026" keywords: [ราคา Seedance 2.0, ราคา Seedance 2.5, Seedance API ราคา, ราคา Seedance 2.0 API, ราคา Seedance 2.5 API, ค่าใช้จ่าย Seedance ต่อวิดีโอ, Seedance 2.0 API ภาษาไทย, API สร้างวิดีโอ ByteDance, API ข้อความเป็นวิดีโอ, Seedance 2.0 API, Seedance 2.5 API, Seedance pricing, Seedance 2.0 pricing, Seedance 2.5 pricing, Seedance 2.0 price, Seedance cost per video, Seedance API cost, ByteDance video API, BytePlus ModelArk Seedance, fal.ai Seedance, Replicate Seedance, PixVerse Seedance, Runway Seedance, Dreamina Seedance, text to video API] image: /assets/images/articles/seedance-2-api-pricing-2026-10.jpg parent: Articles nav_exclude: true lang: th translation_key: seedance-2-pricing date: 2026-07-21 repo: https://github.com/useapi/seedance-2-api last_modified: 2026-11-18 nav_order: 90 --- ## ราคา Seedance 2.0 และ 2.5 API: เทียบทุกช่องทาง {: .no_toc #seedance-20-and-25-api-pricing-every-route-compared } อ่าน 13 นาที • 21 กรกฎาคม 2026 (18 พฤศจิกายน 2026) ## สารบัญ {: .no_toc .text-delta #table-of-contents } ### บทนำ คลิป Seedance 2.0 ยาว 5 วินาทีที่ 1080p ราคา $1.87 บน API ทางการของ ByteDance และราคาต่อคลิปต่ำที่สุดที่เราตรวจสอบได้คือ $1.12 ผ่านช่องทาง PixVerse ของ useapi.net บนแพ็กเกจ Ultra รายปี ($1.49 แบบรายเดือน) หรือ $1.44 บนแพ็กเกจ Premium รายปี ($1.80 แบบรายเดือน) และตอนนี้ไม่มีผู้ขายต่อรายใดถูกกว่านั้นแล้ว (รายที่ถูกที่สุดคือ Segmind ที่ $1.97) ส่วน Seedance 2.5 เป็นอีกเรื่องหนึ่ง ที่ $2.84 ต่อคลิป 1080p ราคาของ ByteDance เองถูกกว่าผู้ขายต่อทุกรายและทุกแพ็กเกจรายเดือนที่เราพบ มีเพียงแพ็กเกจรายปีที่ต่ำกว่าได้เล็กน้อย คือ PixVerse Ultra ($2.32) และ PixVerse Premium หรือ Runway Max ($2.72) เมื่อวันที่ 13 พฤศจิกายน 2026 (ช่องทาง PixVerse อ่านอีกครั้งเมื่อ 15 พฤศจิกายน 2026) เราอ่านราคาจากช่องทางทางการทั้งสองของ ByteDance และผู้ให้บริการบุคคลที่สามราว 12 รายจากหน้าเว็บจริงอีกครั้ง คำนวณสี่ช่องทางของเราใหม่จากอัตราเครดิตปัจจุบัน แล้วปรับทุกตัวเลขให้อยู่ในหน่วยเดียวกัน คือค่าใช้จ่ายเป็นดอลลาร์ของคลิปข้อความเป็นวิดีโอยาว 5 วินาทีที่ไม่มีวิดีโออินพุต ภาพรวมเปลี่ยนไปตั้งแต่เราเผยแพร่บทความนี้ครั้งแรกในเดือนกรกฎาคม PixVerse ปรับราคา Seedance ใหม่และยกเลิกส่วนลดของแพ็กเกจ Pro และ Premium ทำให้ช่องทางนี้ขึ้นจาก $1.20 เป็น $1.80 ต่อคลิปบนแพ็กเกจรายเดือน ByteDance เปิดตัว Seedance 2.5 ด้วยอัตราต่อโทเค็นสูงกว่า 2.0 ราว 50% และผู้ขายต่อส่วนใหญ่ก็ออกระดับราคา 2.5 ของตัวเองตามมา ขอบอกตรง ๆ ว่าเราอยู่ตรงไหน useapi.net เป็นเลเยอร์แบบนำบัญชีของคุณเองมาใช้ (bring-your-own-account) ไม่ใช่ผู้ขายต่ออย่างเป็นทางการของ ByteDance เราสั่งงานบัญชี [PixVerse](/docs/api-pixverse-v2) [Runway](/docs/api-runwayml-v1) [Dreamina](/docs/api-dreamina-v1) หรือ [MiniMax](/docs/api-minimax-v1) ของคุณเองผ่าน REST API เดียว คุณจึงใช้เครดิตแบบผู้บริโภคของแพลตฟอร์มเหล่านั้นแทนอัตราคิดตามการใช้งานของ API สำหรับนักพัฒนา ทุกตัวเลขด้านล่างระบุวันที่และแหล่งที่มา และราคาในตลาดนี้เปลี่ยนทุกเดือน จึงควรตรวจสอบอีกครั้งก่อนตัดสินใจใช้เงิน การสมัคร useapi.net ครั้งเดียวรัน Seedance 2.0 และ 2.5 ได้ครบทั้งสี่ช่องทางด้านล่าง บนแพ็กเกจ PixVerse, Runway, Dreamina หรือ MiniMax ที่คุณมีอยู่แล้ว และครอบคลุมทุก API อื่นบนเว็บไซต์ด้วย [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03?client_reference_id={{ page.url | slugify | default: 'home' }}){: .btn .btn-purple .mr-2 .mb-3 } [สี่ช่องทางต่างกันอย่างไร](#four-ways-to-run-seedance-20-through-useapinet) ### ราคา Seedance 2.0 และ 2.5 API ทางการ ByteDance ขาย Seedance ผ่านช่องทางทางการสองช่องทาง คือ [BytePlus ModelArk](https://docs.byteplus.com/en/docs/ModelArk/1544106) สำหรับตลาดต่างประเทศ และ [Volcano Engine](https://www.volcengine.com/docs/82379/1544106) ในจีน ทั้งสองคิดเงินต่อล้านโทเค็น โดยจำนวนโทเค็นของคลิปคือ `width × height × 24fps × seconds ÷ 1024` คลิป 1080p ยาว 5 วินาทีเท่ากับ 243,000 โทเค็น Seedance 2.0 คิด $7.7 ต่อล้านโทเค็นที่ 1080p คลิปนั้นจึงราคา $1.87 Seedance 2.5 คิด $11.7 ต่อล้านโทเค็นที่ 1080p คลิปเดียวกันจึงราคา $2.84 เมื่อปรับเป็นราคาต่อคลิปตามหน้าราคาของ BytePlus (อ่านเมื่อ 13 พฤศจิกายน 2026): | ความละเอียด | Seedance 2.0, 5 วินาที | Seedance 2.0, 10 วินาที | Seedance 2.5, 5 วินาที | Seedance 2.5, 10 วินาที | |:-----------|-----------------:|------------------:|-----------------:|------------------:| | 480p | $0.35 | $0.70 | $0.51 | $1.03 | | 720p | $0.76 | $1.51 | $1.16 | $2.31 | | 1080p | $1.87 | $3.74 | $2.84 | $5.69 | | 4K | $3.89 | $7.78 | $4.57 | $9.14 | Seedance 2.5 รองรับ 4K บน BytePlus ตั้งแต่วันที่ 16 พฤศจิกายน 2026 ที่ $4.57 ต่อคลิป 5 วินาทีแบบไม่มีวิดีโออินพุต และยาวได้ถึง 30 วินาทีต่อคลิป เทียบกับ 15 วินาทีของ 2.0 และรับข้อมูลอ้างอิงได้สูงสุด 50 รายการ (ภาพ 30 วิดีโอ 10 และคลิปเสียง 10) คลิป 2.5 ที่ 1080p ยาวเต็ม 30 วินาทีราคาราว $17 Seedance 2.0 Fast และ Mini ยังถูกกว่าและยังจำกัดที่ 720p โดยคลิป 720p ยาว 5 วินาทีมีราคาตามรายการ $0.60 บน Fast และ $0.38 บน Mini ส่วน Seedance 2.5 Flash ตัวใหม่ก็หยุดที่ 720p เช่นกัน ที่ $0.76 ต่อคลิป 720p ยาว 5 วินาที และ BytePlus เปิดให้เรียกผ่าน API ในวันที่ 15 พฤศจิกายน 2026 เสียงรวมอยู่ในราคาโดยไม่มีค่าใช้จ่ายเพิ่ม Volcano ตั้งราคา 2.5 ที่ ¥77 ต่อล้านโทเค็นที่ 1080p แต่ต้องยืนยันตัวตนด้วยชื่อจริงและใบหน้าแบบจีน จึงใช้ได้จริงเฉพาะในจีน ราคาที่ติดไว้ไม่ใช่ค่าใช้จ่ายทั้งหมด การเปิดใช้ Seedance บน BytePlus ต้องจ่ายล่วงหน้าราว $30 คือ[แพ็กทรัพยากร](https://docs.byteplus.com/en/docs/ModelArk/2191775)แบบเติมเงินล่วงหน้า (แพ็กเล็กที่สุดคือ $30.10 สำหรับ 2.0 และ $32 สำหรับ 2.5 คืนเงินไม่ได้ และหมดอายุหลัง 90 วัน) หรือการเติมยอดเงิน $30 ที่ BytePlus แนะนำ บัญชีบุคคลถูกจำกัดที่ 3 งานพร้อมกัน (180 request ต่อนาที) และ 4K ถูกจำกัดที่งานเดียวพร้อมกันสำหรับทุกคน ทั้งหมดนี้ไม่ได้ทำให้ API ทางการเป็นตัวเลือกที่แย่ แต่มันคือมาตรฐานที่ทุกทางเลือกควรถูกนำมาเทียบ ### สี่วิธีรัน Seedance 2.0 ผ่าน useapi.net token เดียวของ useapi.net สั่งงาน Seedance 2.0 ได้บนสี่แพลตฟอร์ม บนแพ็กเกจบัญชีที่คุณจ่ายอยู่แล้ว ค่าใช้จ่ายด้านล่างคือค่าแพ็กเกจต่อคลิป 1080p ยาว 5 วินาที คำนวณจากอัตราเครดิตและราคาแพ็กเกจในเอกสารของเรา | ช่องทาง | โมเดล Seedance | 5 วินาที 1080p, แพ็กเกจรายเดือน | 5 วินาที 1080p, แพ็กเกจรายปี | จุดเด่น | |:------|:----------------|-----------------------:|----------------------:|:---------------| | [PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) | 2.5, 2.5 Flash, 2.5 Draft, 2.0, Fast, Mini | $1.80 | $1.44 | 1080p 2.0 และ 4K ถูกที่สุด ($1.49 และ $1.12 บน Ultra) รับใบหน้าคนจริง | | [Dreamina](/docs/api-dreamina-v1/post-dreamina-videos) | 2.5, 2.5 Flash, 2.0, Fast, Mini, 1.5 Pro, ตระกูล 1.0 | ~$1.83–1.87 | ~$1.78–1.81 | Seedance 2.5 กับใบหน้าคนจริงและวิดีโอยาว มีโมเดลให้เลือกมากที่สุด | | [MiniMax](/docs/api-minimax-v1/post-minimax-videos-create) | 2.0, Fast, Mini | $2.00 | $1.70 | 4K พร้อมเวิร์กโฟลว์ภาพอ้างอิงที่ครบเครื่อง | | [Runway](/docs/api-runwayml-v1/post-runwayml-videos-create) | 2.5, 2.0, Fast, Mini | $2.00 | $1.60 | รับใบหน้าคนจริง ตรวจเนื้อหาเบากว่า Dreamina | ช่องทาง PixVerse คิด Seedance 2.0 ที่ 90 เครดิตต่อวินาทีที่ 1080p คลิป 5 วินาทีจึงเท่ากับ 450 เครดิต บนแพ็กเกจ Premium $60/เดือน ($0.004 ต่อเครดิต) เท่ากับ $1.80 และบน Premium แบบรายปี ($0.0032 ต่อเครดิต) เท่ากับ $1.44 เครดิตของ Ultra แพงกว่า แต่บน Ultra นั้น PixVerse ลดราคา Seedance 2.0 50% เว้นแต่คำขอจะส่ง `relax_mode: false` ทำให้คลิปหนึ่งเหลือ $1.49 หรือ $1.12 แบบรายปี (Ultra ราคา $199 ต่อเดือนได้ 30,000 เครดิต ข้อมูล ณ 15 พฤศจิกายน 2026) ที่ราคาเต็มซึ่งคำขอที่ส่ง `relax_mode: false` ต้องจ่าย คลิปบน Ultra ราคา $2.99 PixVerse ยังทำได้ถึง 2160p (4K) บน Seedance 2.0 ที่ $4.00 ต่อ 5 วินาทีบน Premium หรือ $3.20 แบบรายปี และ $3.32 หรือ $2.48 บน Ultra ซึ่งเป็น 4K ที่ถูกที่สุดที่เราพบ ในเดือนกรกฎาคมช่องทางนี้ราคา $1.20 ต่อคลิป หลังจากนั้น PixVerse ปรับราคาตระกูล Seedance ใหม่และยกเลิกส่วนลด Pro และ Premium ที่เคยมี ซึ่งเป็นการเปลี่ยนแปลงครั้งใหญ่ที่สุดในการอัปเดตนี้ ([ตารางค่าใช้จ่ายของ PixVerse](/docs/api-pixverse-v2)) ข้อได้เปรียบจริงของช่องทาง Dreamina คือ Seedance 2.5 ซึ่งรับใบหน้าคนจริงและสร้างวิดีโอยาว 31 ถึง 180 วินาทีได้ในงานเดียว ซึ่ง API ทางการทำไม่ได้ ([ราคา Seedance 2.5](#seedance-25-pricing)) สำหรับ Seedance 2.0 ที่ 1080p ราคาแทบเท่ากับ API ทางการ ที่ 57 เครดิตต่อวินาทีบนแพ็กเกจ Advanced ภูมิภาคแคนาดา คลิป 5 วินาทีราคาราว $1.83 แบบรายเดือน (C$109.99 ได้ 11,997 เครดิต) และ $1.81 แบบรายปี (C$1,299.99) เทียบกับ $1.87 แพ็กเกจ Advanced ของสหรัฐฯ คิด 41 เครดิตต่อวินาที ราว $1.87 แบบรายเดือน ($79 ได้ 8,645 เครดิต) และ $1.78 แบบรายปี ($900) ทั้งสองภูมิภาครัน 1080p และ 4K ได้ และตระกูล 2.0 ของ Dreamina ปฏิเสธใบหน้าคนจริง ราคาแพ็กเกจและอัตราเครดิตอ่านใหม่อีกครั้งเมื่อ 12 พฤศจิกายน 2026 แปลงที่อัตรา CAD/USD 0.7023 ([เครื่องคำนวณค่าใช้จ่ายของ Dreamina](/docs/start-here/setup-dreamina#cost-calculator)) ช่องทาง MiniMax คิด Seedance 2.0 ที่ 50 เครดิตต่อวินาทีที่ 1080p ไม่เปลี่ยนตั้งแต่กรกฎาคม ซึ่งเป็นส่วนลด Seedance 50% ของ MiniMax ที่ระบุว่าเป็นข้อเสนอช่วงเวลาจำกัด (ข้อมูล ณ 12 พฤศจิกายน 2026) MiniMax ปรับราคาแพ็กเกจใหม่ด้วย แพ็กเกจ Master $89 (10,500 เครดิต) ทำให้คลิปหนึ่งราคา $2.12 แพ็กเกจ Max $216 (27,000 เครดิต) ราคา $2.00 และ Master แบบรายปีราคา $1.70 โดย 4K ราคา $3.39 บนแพ็กเกจรายปีนั้น ตอนนี้ช่องทาง Runway ก็มีอัตราที่เผยแพร่แล้วเช่นกัน Seedance 2.0 ของ Runway ใช้ 40 เครดิตต่อวินาทีที่ 1080p เท่ากับ $2.00 ต่อคลิปบนแพ็กเกจ Max $95 ของ Runway และ $1.60 แบบรายปี ([เครื่องคำนวณค่าใช้จ่ายของ Runway](/docs/api-runwayml-v1)) `exploreMode` แบบเดิมของ Runway ยังรัน Seedance ที่ 480p และ 720p ได้โดยไม่ใช้เครดิต บนบัญชี Unlimited รุ่นเก่าที่เปิด Explore mode ไว้แล้ว จนกว่า Runway จะย้ายบัญชีเหล่านั้นไปเป็น Max ในวันที่ 30 พฤศจิกายน 2026 Runway ไม่เปิดโหมดนี้ให้บัญชีใหม่แล้ว และโหมดนี้ช้า คือทีละคลิป คลิปละราว 10 ถึง 15 นาที ให้ถือว่าเป็นของแถมถ้าคุณมีอยู่แล้ว ไม่ใช่เหตุผลที่จะเลือก Runway ตัวเลขเหล่านี้คือค่าแพ็กเกจต่อคลิป และตัวที่ถูกที่สุดตั้งอยู่บนสมมติฐานว่าคุณผูกมัดแบบรายปีและใช้เครดิตจริง Premium แบบรายปีจ่ายล่วงหน้า $576 ได้ 15,000 เครดิตต่อเดือน หรือราว 33 คลิป 1080p ต่อเดือน และ Ultra แบบรายปีราคา $1,788 ได้ 30,000 เครดิตต่อเดือน หรือราว 133 คลิป ข้อแลกเปลี่ยนก็ควรพูดถึง ช่องทางของเราสั่งงานบัญชีผู้บริโภคอัตโนมัติ จำนวนงานพร้อมกันจึงขึ้นกับบัญชี (โดยทั่วไป 5–10 งานพร้อมกัน เทียบกับขีดจำกัดต่อคีย์ของ API ทางการ) และแพลตฟอร์มปรับราคาได้โดยไม่แจ้งล่วงหน้า อย่างที่ PixVerse เพิ่งทำ สิ่งที่คุณได้กลับมาคือค่าใช้จ่ายต่อคลิปที่ต่ำกว่าราคาทางการบน 2.0 สำหรับแพ็กเกจรายปี (และ PixVerse รายเดือน) ไม่ต้องซื้อแพ็กล่วงหน้า และใช้ token เดียวได้ทั้งสี่แพลตฟอร์ม ### ราคา Seedance 2.5 Seedance 2.5 รันได้บนสามจากสี่ช่องทางของเรา คือ [PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) [Dreamina](/docs/api-dreamina-v1/post-dreamina-videos) และ [Runway](/docs/api-runwayml-v1/post-runwayml-videos-create) ส่วน MiniMax ไม่มีโมเดลนี้ สำหรับ 2.5 ความต่างที่ใหญ่กว่าคือสิ่งที่ API ทางการไม่ยอมทำ [คู่มือ Seedance 2.5](https://docs.byteplus.com/en/docs/modelark/seedance-2-5) ของ ByteDance เองระบุว่า 2.5 "does not support directly uploading reference images or videos containing real human faces" (ไม่รองรับการอัปโหลดภาพหรือวิดีโออ้างอิงที่มีใบหน้าคนจริงโดยตรง) และ API ทางการหยุดที่ 30 วินาทีต่อคลิป [ช่องทาง Dreamina รับใบหน้าคนจริงบน 2.5](/docs/api-dreamina-v1/post-dreamina-videos) ได้โดยตรง และเพิ่มโหมดวิดีโอยาวที่ทำได้ 31 ถึง 180 วินาทีในงานเดียว รวมถึงการแก้ไขวิดีโอ และบนบัญชีแคนาดายังเรนเดอร์ 2.5 เป็น 4K ได้ในราคาราว $4.15 ต่อคลิป 5 วินาทีบนแพ็กเกจ Advanced ของแคนาดา ต่ำกว่าราคาทางการ $4.57 [ช่องทาง Runway](/docs/api-runwayml-v1/post-runwayml-videos-create) ก็รับใบหน้าคนจริงบน Seedance เช่นกัน และไม่ต้องซื้อแพ็กล่วงหน้าราว $30 ก่อนคลิปแรก ที่ 1080p ช่องทาง PixVerse และ Runway ของเรายังมีราคาต่อคลิปต่ำกว่าราคาของ ByteDance เองด้วยบนแพ็กเกจรายปี สำหรับคลิปยาว 5 วินาทีที่ไม่มีวิดีโออินพุต: | ช่องทาง | 1080p, 5 วินาที | ความยาวสูงสุด | |:------|-----------:|:-----------| | [PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) *(Ultra, รายปี)* | $2.32 | 30 วินาที | | [PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) *(Premium, รายปี)* | $2.72 | 30 วินาที | | [Runway](/docs/api-runwayml-v1/post-runwayml-videos-create) *(Max, รายปี)* | $2.72 | 30 วินาที | | [BytePlus ทางการ](https://docs.byteplus.com/en/docs/ModelArk/1544106) | $2.84 | 30 วินาที | PixVerse คิด 2.5 ที่ 170 เครดิตต่อวินาทีที่ 1080p ($0.0032 ต่อเครดิตบน Premium แบบรายปี) และ Ultra ลด 45% เหลือ 468 เครดิตต่อคลิปที่ $0.00497 ต่อเครดิตแบบรายปี ($3.10 บนแพ็กเกจ Ultra รายเดือน) Runway คิด 68 เครดิตต่อวินาทีที่ 1080p ($0.008 ต่อเครดิตบน Max แบบรายปี คือ $76 ต่อเดือนได้ 9,500 เครดิต ข้อมูล ณ 13 พฤศจิกายน 2026) อัตรารายปีตั้งอยู่บนสมมติฐานว่าคุณใช้เครดิตของแพ็กเกจจริง ตอนนี้ PixVerse สร้าง Seedance 2.5 ที่ 4K (2160p) ได้ด้วย ที่ 286 เครดิตต่อวินาที (ข้อมูล ณ 15 พฤศจิกายน 2026) คลิป 4K ยาว 5 วินาทีเท่ากับ 1,430 เครดิต หรือ 787 เครดิตหลังส่วนลดของ Ultra คือ $3.91 บน Ultra แบบรายปี เทียบกับ $4.57 บน API ของ ByteDance เอง (ข้อมูล ณ 18 พฤศจิกายน 2026) ### ช่องว่างเรื่องใบหน้าคนจริง บน API ทางการ ทั้ง Seedance 2.0 และ 2.5 ปฏิเสธภาพและวิดีโออ้างอิงที่มีใบหน้าคนจริง เว้นแต่ใบหน้านั้นมาจากผลลัพธ์ล่าสุดของโมเดลเอง ตัวละครดิจิทัลสำเร็จรูป หรือ asset บุคคลจริงที่ยืนยันแล้ว การทำงานอ้างอิงบุคคลจริงในปริมาณมากต้องใช้ "Advanced Creation Rights" ระดับองค์กรของ ByteDance ซึ่งราคา [$14,000 ต่อปี หรือ $1,400 ต่อเดือน](https://docs.byteplus.com/en/docs/modelark/2377608) สำหรับหนึ่งล้าน asset และ $42,000 ต่อปีสำหรับห้าล้าน asset และต้องยืนยันตัวตนบริษัท ช่องทางของเราผ่อนปรนเรื่องนี้ได้ในสี่จุด [ช่องทาง PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) รับใบหน้าคนจริงบน Seedance 2.0 [ช่องทาง Runway](/docs/api-runwayml-v1/post-runwayml-videos-create) ระบุในเอกสารว่ารองรับใบหน้าคนจริงบน Seedance และโดยทั่วไปตรวจเนื้อหาเบากว่า Dreamina [ช่องทาง MiniMax](/docs/api-minimax-v1/post-minimax-videos-create) รับใบหน้าคนจริงในภาพอ้างอิง (วิดีโออ้างอิงที่มีใบหน้าที่จดจำได้ยังถูกตรวจเนื้อหา) และ[ช่องทาง Dreamina](/docs/api-dreamina-v1/post-dreamina-videos)รับภาพถ่ายบุคคลบน Seedance 2.5 แต่ไม่รับในตระกูล 2.0 สำหรับงานโฆษณา UGC และเวิร์กโฟลว์ของครีเอเตอร์ที่มีบุคคลจริงเป็นศูนย์กลาง ความต่างนี้สำคัญกว่าส่วนต่างไม่กี่เซนต์ต่อคลิป และไม่ต้องมีสัญญาระดับองค์กร ### ราคา Seedance API จากผู้ขายต่อ ผู้ให้บริการ Seedance บุคคลที่สามส่วนใหญ่ขายต่อ API ของ ByteDance เองโดยบวกส่วนต่างเพิ่ม นี่คือ Seedance 2.0 ที่ 5 วินาทีและ 1080p โดยทุกราคาของบุคคลที่สามอ่านจากหน้าเว็บจริงของผู้ให้บริการเมื่อ 13 พฤศจิกายน 2026: | ผู้ให้บริการ | 5 วินาที 1080p | หมายเหตุ | |:-------|---------:|:------| | [useapi.net (ช่องทาง PixVerse)](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) | $1.12–1.80 | เครดิตบัญชีผู้บริโภค ตั้งแต่ Ultra รายปีถึง Premium รายเดือน | | [useapi.net (ช่องทาง Runway)](/docs/api-runwayml-v1/post-runwayml-videos-create) | $1.60–2.00 | แพ็กเกจ Max รายปีหรือรายเดือน | | [useapi.net (ช่องทาง MiniMax)](/docs/api-minimax-v1/post-minimax-videos-create) | $1.70–2.12 | Master รายปีถึง Master รายเดือน ($2.00 บน Max รายเดือน) | | [useapi.net (ช่องทาง Dreamina)](/docs/api-dreamina-v1/post-dreamina-videos) | ~$1.78–1.87 | บัญชีสหรัฐฯ หรือแคนาดา Advanced รายปีหรือรายเดือน อ่านเมื่อ 12 พฤศจิกายน 2026 | | [BytePlus ทางการ](https://docs.byteplus.com/en/docs/ModelArk/1544106) | $1.87 | มาตรฐานอ้างอิง OpenRouter ส่งผ่านในราคาเดียวกันทุกประการ | | [Segmind](https://www.segmind.com/models/seedance-2.0/pricing) | $1.97 | สูงกว่าราคาทางการตั้งแต่พฤศจิกายน ($8.105 ต่อล้านโทเค็นที่ 1080p) | | [RunComfy](https://www.runcomfy.com/models/bytedance/seedance-v2/pro) | $2.00 | $0.40 ต่อวินาที ลดจาก $0.55 ในเดือนกรกฎาคม | | [EachLabs](https://www.eachlabs.ai/bytedance/seedance-2-0/bytedance-seedance-2-0-text-to-video) | $2.22 | ราว $0.444 ต่อวินาที ลดจาก $0.60 | | [Replicate](https://replicate.com/bytedance/seedance-2.0) | $2.25 | ป้ายโมเดล "Official" $0.45 ต่อวินาทีของวิดีโอที่ได้ | | [Poyo.ai](https://poyo.ai/models/seedance-2) | $2.25 | $0.45 ต่อวินาที | | [EvoLink](https://evolink.ai/seedance-2-0) | $2.48 | $0.497 ต่อวินาที | | [PiAPI](https://piapi.ai/seedance-2-0) | $2.50 | $0.50 ต่อวินาที | | [Kie.ai](https://kie.ai/seedance-2-0) | $2.55 | $0.51 ต่อวินาที | | [Atlas Cloud](https://www.atlascloud.ai/models/bytedance/seedance-2.0/text-to-video) | $2.74 | $2.20 เมื่อมีโปรโมชัน 20% | | [WaveSpeedAI](https://wavespeed.ai/models/bytedance/seedance-2.0/text-to-video) | $3.00 | $0.60 ต่อวินาที | | [fal.ai](https://fal.ai/models/bytedance/seedance-2.0/text-to-video) | $3.41 | ตัวเลือกยอดนิยมของตลาด และยังแพงที่สุด | แถวสุดท้ายนี้ควรพิจารณาให้ดี fal.ai คือที่ที่นักพัฒนาจำนวนมากมองหา Seedance เป็นที่แรก และที่ $0.682 ต่อวินาที มันคิดแพงกว่าราคาของ ByteDance เองราว 82% สำหรับโมเดลเดียวกัน บน 2.5 ก็เช่นกัน คลิป 720p ของมันราคา $2.31 เทียบกับราคาทางการ $1.16 และคลิป 1080p ราคาราว $5.69 เทียบกับ $2.84 Seedance 2.5 มีกลุ่มผู้ขายต่อของตัวเอง Replicate และ OpenRouter ส่งผ่านราคาทางการเท่ากันทุกประการ ($1.16 สำหรับ 720p และ $0.51 สำหรับ 480p) แต่หยุดที่ 720p และตอนนี้ [RunComfy](https://www.runcomfy.com/models/bytedance/seedance-2.5/text-to-video) ขาย 2.5 ที่ 720p เท่านั้น ($1.53 ต่อ 5 วินาทีระหว่างโปรโมชัน 35% ในปัจจุบัน) ในบรรดาผู้ให้บริการที่ขาย 2.5 ที่ 1080p [Poyo](https://poyo.ai/models/seedance-2-5) ($2.85) [Segmind](https://www.segmind.com/models/seedance-2.5/pricing) ($2.99) และ [Atlas Cloud](https://www.atlascloud.ai/models/bytedance/seedance-2.5/text-to-video) ($2.98 เมื่อมีโปรโมชัน 20% หรือ $3.73 หากไม่มี) อยู่ห่างจากราคาทางการเพียงไม่กี่เปอร์เซ็นต์ [EachLabs](https://www.eachlabs.ai/bytedance/seedance-2-5/bytedance-seedance-2-5-text-to-video) ($3.28) สูงกว่าราว 15% ส่วน [EvoLink](https://evolink.ai/seedance-2-5) ($3.70) [Kie.ai](https://kie.ai/seedance-2-5) ($3.95) [PiAPI](https://piapi.ai/seedance-2-5) ($4.00) และ [WaveSpeedAI](https://wavespeed.ai/models/bytedance/seedance-2.5/text-to-video) ($4.50) สูงกว่า 30–60% คุณจะเห็นราคาที่ติดไว้ซึ่งดูต่ำกว่าราคาทางการมากด้วย แต่ทุกรายที่เราตามไปตรวจสอบล้วนกลายเป็นอย่างอื่นที่ไม่ใช่คลิปมาตรฐานที่ถูกกว่า รูปแบบที่ควรระวังเมื่อราคาดูดีเกินจริง: - รุ่น "Turbo" หรือ "accelerated" ที่ไม่ใช่โมเดลมาตรฐาน — ผู้ให้บริการรายหนึ่งตั้งราคาคลิป Seedance 2.5 ที่ 1080p ยาว 5 วินาทีไว้ $1.10 ภายใต้ชื่อโมเดล turbo ที่ ByteDance ไม่ได้เผยแพร่ ขณะที่ Seedance 2.5 มาตรฐานบนเว็บเดียวกันราคา $4.50 - ราคาที่อ้างที่ 720p ขณะที่คุณต้องการ 1080p — หลายหน้าที่อ้างว่าเป็น "Seedance ที่ถูกที่สุด" รวมถึงรายการ Seedance 2.5 บน Replicate และ OpenRouter ไม่มีระดับ 1080p เลย - ราคา 2.0 บนหน้าที่พูดถึง 2.5 — Seedance 2.5 ราคาต่อโทเค็นสูงกว่าราวครึ่งหนึ่ง ราคา "Seedance" ที่ไม่ระบุเวอร์ชันจึงนำมาเทียบกันไม่ได้ - เครดิตที่ไม่ได้เผยแพร่มูลค่าเป็นดอลลาร์ — ถ้าหน้าเว็บตั้งราคาการสร้างเป็นเครดิตแต่ไม่เคยบอกว่าหนึ่งเครดิตราคาเท่าไร คุณก็เทียบไม่ได้ และนั่นมักเป็นจุดประสงค์ ทั้งหมดนี้ไม่ได้แปลว่าผู้ให้บริการเหล่านั้นไม่ซื่อสัตย์ แต่แปลว่าเวอร์ชัน ความละเอียด และเงื่อนไขปลีกย่อยต้องตรงกันก่อน การเปรียบเทียบจึงจะมีความหมาย ### วิธีเรียก Seedance API ทุกราคาข้างต้นอยู่ห่างไปแค่ REST call เดียว สร้างคลิป Seedance 2.0 ที่ 1080p ผ่านช่องทาง PixVerse: ```bash curl --location 'https://api.useapi.net/v2/pixverse/videos/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="seedance-2.0"' \ --form 'prompt="A lone lighthouse on a storm-battered cliff at dusk, waves exploding against the rocks, beam sweeping through the rain, cinematic wide shot."' \ --form 'quality="1080p"' \ --form 'duration="5"' \ --form 'aspect_ratio="16:9"' ``` call เดียวกันนี้รัน Seedance 2.5 ได้โดยเปลี่ยน `model` เป็น `seedance-2.5` และตั้ง `duration` ได้ตั้งแต่ 4 ถึง 30 หรือถ้าบัญชี Runway ของคุณยังมี Explore mode (Runway ไม่เปิดให้บัญชีใหม่แล้ว และจะยุติสำหรับบัญชี Unlimited รุ่นเก่าในวันที่ 30 พฤศจิกายน 2026) รูปแบบเดียวกันนี้รันได้โดยไม่ใช้เครดิตที่ 720p ด้วยการเพิ่ม `exploreMode` ทีละคลิปแบบช้า ๆ: ```bash curl --location 'https://api.useapi.net/v1/runwayml/videos/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="seedance-2"' \ --form 'text_prompt="A lone lighthouse on a storm-battered cliff at dusk, waves exploding against the rocks, beam sweeping through the rain, cinematic wide shot."' \ --form 'resolution="720p"' \ --form 'duration="5"' \ --form 'exploreMode="true"' ``` ทั้งสองคืนค่า job id ให้เรียกดูสถานะ (หรือใช้ webhook `replyUrl` ที่แจ้งเมื่อคลิปพร้อม) พารามิเตอร์ทั้งหมด ทั้งภาพอ้างอิง เฟรมแรกและเฟรมสุดท้าย อัตราส่วนภาพ และเสียง อยู่ในหน้า endpoint แต่ละหน้าที่ลิงก์ไว้ในตารางด้านบน ### ควรใช้ช่องทางไหนสำหรับ Seedance 2.0 หรือ 2.5? - Seedance 2.0 ที่ 1080p ถูกที่สุด — [ช่องทาง PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) บนแพ็กเกจรายปี คือ $1.12 บน Ultra หรือ $1.44 บน Premium ถ้าไม่ผูกมัดรายปี PixVerse รายเดือน ($1.49 บน Ultra และ $1.80 บน Premium) ก็ยังต่ำกว่าราคาทางการ $1.87 และผู้ขายต่อทุกรายแพงกว่านั้น - 4K ถูกที่สุด — ช่องทาง PixVerse ที่ $2.48 บน Ultra รายปี หรือ $3.20 บน Premium รายปี ตามด้วย [MiniMax](/docs/api-minimax-v1/post-minimax-videos-create) ที่ $3.39 แบบรายปี ทั้งหมดต่ำกว่าราคาทางการ $3.89 - Seedance 2.5 ที่ 1080p ถูกที่สุด — [ช่องทาง PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) บน Ultra แบบรายปีที่ $2.32 ต่อคลิป 5 วินาที ตามด้วย PixVerse Premium หรือ [ช่องทาง Runway](/docs/api-runwayml-v1/post-runwayml-videos-create) บน Max ทั้งคู่แบบรายปี ที่ $2.72 เทียบกับ $2.84 บน API ทางการ - Seedance 2.5 ที่ 4K ถูกที่สุด — [ช่องทาง PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) บน Ultra แบบรายปีที่ $3.91 ต่อคลิป 5 วินาที ตามด้วย [ช่องทาง Dreamina](/docs/api-dreamina-v1/post-dreamina-videos) บนแพ็กเกจ Advanced ของแคนาดาที่ราว $4.15 เทียบกับ $4.57 บน API ทางการ - Seedance 2.5 กับใบหน้าคนจริง หรือคลิปที่ยาวกว่า 30 วินาที — [ช่องทาง Dreamina](/docs/api-dreamina-v1/post-dreamina-videos) - ใบหน้าคนจริงบน Seedance 2.0 — ช่องทาง [PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) [MiniMax](/docs/api-minimax-v1/post-minimax-videos-create) หรือ [Runway](/docs/api-runwayml-v1/post-runwayml-videos-create) - Seedance 1.5 Pro หรือ 1.0 — ช่องทาง Dreamina ซึ่งเป็นช่องทางเดียวที่มีตระกูล 1.x และ BytePlus เลิกให้บริการ 1.5 Pro บน API ของตัวเองแล้ว ### ตัวอย่าง ผลลัพธ์จริงของ Seedance 2.0 จากแต่ละช่องทาง นำมาจากบล็อกโพสต์ของเรา เป็นโมเดลเดียวกันที่รันบนแพลตฟอร์มต่างกัน สามคลิปในนี้ใช้ใบหน้าคนจริง ซึ่งเป็นเวิร์กโฟลว์ที่ API ทางการกันไว้หลังสัญญาระดับองค์กร PixVerse · Seedance 2.0 (Standard), 1080p — ใบหน้าคนจริงจากรูปถ่ายถูกใส่ลงในฟุตเทจอ้างอิง และพูดตามเสียงจากคลิปเสียงอ้างอิง ทั้งหมดในคำขอ omni เดียว จาก [PixVerse Seedance 2.0: Mini vs Fast vs Standard](/blog/260626a) <video poster="https://media.useapi.net/blog/2026-06-26-260626a/omni-standard-1080p-4s-9x16-swap-poster.jpg" src="https://media.useapi.net/blog/2026-06-26-260626a/omni-standard-1080p-4s-9x16-swap.mp4" style="width: 100%; max-width: 420px;" controls type="video/mp4" preload="metadata">Your browser does not support the video element.</video> ดูบน YouTube ได้ด้วย: [Seedance 2.0 Omni: Photo + Reference Video + Audio → One Clip (Mini vs Fast vs Standard)](https://youtube.com/shorts/apUc3lXrY_4) MiniMax · Seedance 2.0 (Standard), 1080p — เวิร์กโฟลว์ omni กับใบหน้าคนจริงแบบเดียวกันบนช่องทาง MiniMax จาก [MiniMax Seedance 2.0: Standard vs Fast vs Mini](/blog/260626b) <video poster="https://media.useapi.net/blog/2026-06-26-260626b/std-1080-5s-nowm-poster.jpg" src="https://media.useapi.net/blog/2026-06-26-260626b/std-1080-5s-nowm.mp4" style="width: 100%; max-width: 420px;" controls type="video/mp4" preload="metadata">Your browser does not support the video element.</video> Runway · Seedance 2.0, 15 วินาที, 9:16 — ใบหน้าคนจริงที่ทำให้เคลื่อนไหวบนช่องทาง Runway ซึ่งตรวจเนื้อหาเรื่องบุคคลจริงเบากว่า จาก [Seedance 2.0: Using Real Faces](/blog/260415) <video poster="https://media.useapi.net/articles/2024-08-11-runway-bash/runway-original-result-poster.jpg" src="https://media.useapi.net/articles/2024-08-11-runway-bash/runway-original-result.mp4" style="width: 100%; max-width: 420px;" controls type="video/mp4" preload="metadata">Your browser does not support the video element.</video> Dreamina · Seedance 2.0 ข้อความเป็นวิดีโอพร้อมลิปซิงก์จากพรอมต์เพียงอย่างเดียว จาก [Dreamina: Seedance 2.0 Video Generation](/blog/260402) <video poster="https://media.useapi.net/blog/2026-04-02-260402/seedance-2.0-prompt-9-16-poster.jpg" src="https://media.useapi.net/blog/2026-04-02-260402/seedance-2.0-prompt-9-16.mp4" style="width: 100%; max-width: 420px;" controls type="video/mp4" preload="metadata">Your browser does not support the video element.</video> บทแนะนำที่เกี่ยวข้อง: [วิดีโอ Seedance 2.0 ผ่าน Dreamina API](/docs/articles/dreamina-bash) [ทางเลือกแทน Sora 2 API](/docs/articles/sora-2-api-alternatives) และ [วิดีโอ PixVerse V6 ผ่าน PixVerse API](/docs/articles/pixverse-demo) ## คำถามที่พบบ่อย **useapi.net เป็น Seedance API ทางการหรือไม่?** ไม่ใช่ useapi.net เป็นเลเยอร์ REST ที่สั่งงานบัญชี [PixVerse](/docs/api-pixverse-v2) [Runway](/docs/api-runwayml-v1) [Dreamina](/docs/api-dreamina-v1) หรือ [MiniMax](/docs/api-minimax-v1) ของคุณเองโดยอัตโนมัติ ซึ่งแต่ละแพลตฟอร์มรัน Seedance ได้ คุณใช้เครดิตแบบผู้บริโภคของแพลตฟอร์มเหล่านั้นแทนอัตราคิดตามการใช้งานของ API สำหรับนักพัฒนาของ ByteDance **Seedance 2.0 ราคาวิดีโอละเท่าไร?** ผ่าน useapi.net คลิป 1080p ยาว 5 วินาทีราคา $1.12 บน[ช่องทาง PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4)กับแพ็กเกจ Ultra รายปี หรือ $1.44 กับ Premium รายปี ($1.80 แบบรายเดือน) เทียบกับ $1.87 บน API ทางการของ ByteDance ส่วน API ทางการคิด $0.35 ที่ 480p, $0.76 ที่ 720p, $1.87 ที่ 1080p และ $3.89 ที่ 4K สำหรับคลิป 5 วินาที ข้อมูล ณ 13 พฤศจิกายน 2026 ดู[ตารางราคาทางการ](#official-seedance-20-and-25-api-pricing) **Seedance 2.5 ราคาเท่าไร?** ผ่าน useapi.net Seedance 2.5 รันกับใบหน้าคนจริงและคลิปที่ยาวเกิน 30 วินาทีได้ ซึ่ง API ทางการจำกัดไว้ [ช่องทาง Dreamina](/docs/api-dreamina-v1/post-dreamina-videos) รับรูปถ่ายจริงและรันได้ 31 ถึง 180 วินาทีในงานเดียว ที่ 1080p คลิป 5 วินาทีราคา $2.32 บน PixVerse Ultra และ $2.72 บน PixVerse Premium หรือ Runway แบบรายปี เทียบกับ $2.84 บน API ทางการของ ByteDance (ข้อมูล ณ พฤศจิกายน 2026) ดู[ราคา Seedance 2.5](#seedance-25-pricing) **วิธีที่ถูกที่สุดในการรัน Seedance 2.0 ที่ 1080p คืออะไร?** จากทุกราคาที่เราตรวจสอบเมื่อ 13 และ 15 พฤศจิกายน 2026 คือ[ช่องทาง PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4)ที่ $1.12 ต่อคลิป 5 วินาทีบนแพ็กเกจ Ultra รายปี หรือ $1.44 บน Premium รายปี ถ้าไม่ผูกมัดรายปี PixVerse รายเดือน ($1.49 บน Ultra และ $1.80 บน Premium) ถูกที่สุด ต่ำกว่าราคาทางการ $1.87 ของ ByteDance และไม่มีผู้ขายต่อรายใดต่ำกว่านั้น (Segmind ซึ่งถูกที่สุดราคา $1.97) ดู[ตารางราคาตลาด](#seedance-api-pricing-across-resellers) **สร้างวิดีโอ Seedance ที่มีใบหน้าคนจริงได้ไหม?** ได้ ผ่าน useapi.net ช่องทาง [PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) [Runway](/docs/api-runwayml-v1/post-runwayml-videos-create) และ [MiniMax](/docs/api-minimax-v1/post-minimax-videos-create) รับใบหน้าคนจริงบน 2.0 (MiniMax รับในภาพอ้างอิง) และ[ช่องทาง Dreamina](/docs/api-dreamina-v1/post-dreamina-videos)รับบน 2.5 ส่วน API ทางการจำกัดอินพุตอ้างอิงที่เป็นใบหน้าคนจริงทั้งบน 2.0 และ 2.5 ไว้เฉพาะ asset ที่ยืนยันแล้ว หรือสัญญาระดับองค์กรที่เริ่มต้น $14,000 ต่อปี **useapi.net คิดราคาถูกกว่า API ของ ByteDance เองได้อย่างไร?** บน Seedance 2.0 แพ็กเกจผู้บริโภคของ PixVerse (รายเดือนหรือรายปี) Runway Dreamina และ MiniMax (รายปี) ตั้งราคาการสร้างแบบเดียวกันไว้ต่ำกว่าอัตราคิดตามการใช้งานสำหรับนักพัฒนา และ useapi.net สั่งงานบัญชีใดบัญชีหนึ่งในนั้นอัตโนมัติผ่าน REST ด้วย[การสมัครสมาชิก](/docs/subscription)เดียวสำหรับทุกบริการ บน Seedance 2.5 ส่วนใหญ่ไม่เป็นเช่นนั้น ราคาทางการต่ำกว่า ยกเว้นเมื่อเทียบกับแพ็กเกจรายปีของ PixVerse หรือ Runway ที่ 1080p และช่องทางของเราได้เปรียบเรื่องใบหน้าคนจริง คลิปที่ยาวกว่า และการไม่ต้องซื้อแพ็กล่วงหน้าแทน **ราคา Seedance ต่ำกว่าหนึ่งดอลลาร์ที่เห็นที่อื่นเป็นของจริงไหม?** ส่วนใหญ่ไม่ใช่สำหรับคลิป 1080p มาตรฐาน มักเป็นราคา 720p ราคา 2.0 บนหน้า 2.5 แพ็กเกจเหมาจ่ายที่ได้รับการอุดหนุน รุ่น "turbo" แบบกลั่น (distilled) หรือเครดิตที่ไม่ได้เผยแพร่มูลค่าเป็นดอลลาร์ ดู[ส่วนภาพรวมตลาด](#seedance-api-pricing-across-resellers) --- พร้อมลองแล้วหรือยัง? การเปรียบเทียบทั้งหมดอยู่ในสคริปต์เดียว [github.com/useapi/seedance-2-api](https://github.com/useapi/seedance-2-api) ส่งพรอมต์ไปยังทั้งสี่ช่องทางแล้วแสดงค่าใช้จ่ายและความเร็วของแต่ละช่องทาง พร้อมเครื่องคำนวณราคาที่รันได้โดยไม่ต้องมีบัญชีเลย จากนั้นเลือกช่องทาง คือ [PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) สำหรับ Seedance 2.0 ที่ 1080p ราคาถูกที่สุด หรือ [Dreamina](/docs/api-dreamina-v1/post-dreamina-videos) สำหรับ Seedance 2.5 กับใบหน้าคนจริงและคลิปยาว เชื่อมต่อบัญชี แล้ว[การสมัครสมาชิก useapi.net](/docs/subscription)ก็สั่งงานได้ทั้งสี่ช่องทางด้วย token เดียว ราคาในบทความนี้เป็นปัจจุบัน ณ 13 พฤศจิกายน 2026 และตลาดนี้เปลี่ยนทุกเดือน จึงควรยืนยันอัตราจริงก่อนขยายการใช้งาน #### เผยแพร่ที่อื่นด้วย {: .no_toc #cross-posted } เผยแพร่บน [dev.to](https://dev.to/useapi/seedance-20-api-pricing-the-cheapest-ways-to-run-it-compared-4kno){:rel="nofollow"} (ภาษาอังกฤษ) ด้วย ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/seedance-2-api-pricing-vi === Document URL: https://useapi.net/docs/articles/seedance-2-api-pricing-vi --- layout: default title: "Giá API Seedance 2.0 và 2.5: so sánh mọi tuyến" seo_title: "Giá Seedance 2.0 và 2.5 API: mỗi video tốn bao nhiêu" description: "Một video Seedance 2.0 hoặc 2.5 dài 5 giây tốn bao nhiêu trên API chính thức của ByteDance, ở khoảng một chục bên bán lại và qua bốn tuyến của useapi.net, kiểm tra lại ngày 13 tháng 11 năm 2026." keywords: [giá API Seedance, giá Seedance 2.0, giá Seedance 2.5, Seedance 2.0 API giá rẻ, chi phí Seedance mỗi video, API video ByteDance, API tạo video từ văn bản, Seedance 2.0 API, Seedance 2.5 API, Seedance pricing, Seedance 2.0 pricing, Seedance 2.5 pricing, Seedance 2.0 price, Seedance cost per video, Seedance API cost, ByteDance video API, BytePlus ModelArk Seedance, fal.ai Seedance, Replicate Seedance, PixVerse Seedance, Runway Seedance, Dreamina Seedance, text to video API] image: /assets/images/articles/seedance-2-api-pricing-2026-10.jpg parent: Articles nav_exclude: true lang: vi translation_key: seedance-2-pricing date: 2026-07-21 repo: https://github.com/useapi/seedance-2-api last_modified: 2026-11-18 nav_order: 90 --- ## Giá API Seedance 2.0 và 2.5: so sánh mọi tuyến {: .no_toc #seedance-20-and-25-api-pricing-every-route-compared } 13 phút đọc • 21 tháng 7 năm 2026 (18 tháng 11 năm 2026) ## Mục lục {: .no_toc .text-delta #table-of-contents } ### Giới thiệu Một video Seedance 2.0 dài 5 giây ở 1080p tốn $1,87 trên API chính thức của ByteDance. Mức giá mỗi video thấp nhất mà chúng tôi xác minh được là $1,12, qua tuyến PixVerse của useapi.net, trên gói Ultra năm ($1,49 với gói tháng), hoặc $1,44 trên gói Premium năm ($1,80 với gói tháng), và không còn bên bán lại nào rẻ hơn mức đó (rẻ nhất là Segmind, $1,97). Seedance 2.5 thì khác. Với $2,84 cho một video 1080p, giá của chính ByteDance thấp hơn mọi bên bán lại và mọi gói tháng chúng tôi tìm thấy, và chỉ các gói năm rẻ hơn một chút: PixVerse Ultra ($2,32), và PixVerse Premium hoặc Runway Max ($2,72). Ngày 13 tháng 11 năm 2026 (riêng tuyến PixVerse đọc lại thêm ngày 15 tháng 11 năm 2026), chúng tôi đọc lại giá trên hai kênh chính thức của ByteDance và của khoảng một chục nhà cung cấp bên thứ ba ngay trên trang của họ, tính lại bốn tuyến của chính mình theo tỉ giá credit hiện tại, rồi quy tất cả về một đơn vị: số đô la cho một video 5 giây, tạo từ văn bản, không có video đầu vào. Bức tranh đã thay đổi kể từ lần đầu chúng tôi đăng bài này vào tháng 7. PixVerse định giá lại Seedance và bỏ mức giảm giá cho gói Pro và Premium, khiến tuyến này tăng từ $1,20 lên $1,80 một video với gói tháng. ByteDance ra mắt Seedance 2.5 với giá token cao hơn 2.0 khoảng 50%, và phần lớn bên bán lại cũng ra mức giá 2.5 của riêng họ. Cũng nên nói rõ vị trí của chúng tôi. useapi.net là một lớp API chạy trên tài khoản của chính bạn, không phải đơn vị bán lại chính thức của ByteDance. Chúng tôi điều khiển tài khoản [PixVerse](/docs/api-pixverse-v2), [Runway](/docs/api-runwayml-v1), [Dreamina](/docs/api-dreamina-v1) hoặc [MiniMax](/docs/api-minimax-v1) của bạn qua một REST API duy nhất, nên bạn dùng credit gói người dùng của các nền tảng đó thay vì trả theo giá đo lường của API dành cho nhà phát triển. Mọi con số dưới đây đều ghi ngày và nguồn, và giá trên thị trường này thay đổi hằng tháng, nên hãy kiểm tra lại trước khi cam kết chi tiêu. Một gói đăng ký useapi.net chạy Seedance 2.0 và 2.5 trên cả bốn tuyến dưới đây, trên gói PixVerse, Runway, Dreamina hoặc MiniMax bạn đang có, và dùng được cho mọi API khác trên trang. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03?client_reference_id={{ page.url | slugify | default: 'home' }}){: .btn .btn-purple .mr-2 .mb-3 } [So sánh bốn tuyến](#four-ways-to-run-seedance-20-through-useapinet) ### Giá API Seedance 2.0 và 2.5 chính thức ByteDance bán Seedance qua hai kênh chính thức: [BytePlus ModelArk](https://docs.byteplus.com/en/docs/ModelArk/1544106) cho thị trường quốc tế và [Volcano Engine](https://www.volcengine.com/docs/82379/1544106) ở Trung Quốc. Cả hai tính tiền theo triệu token, trong đó số token của một video là `width × height × 24fps × seconds ÷ 1024`. Một video 1080p dài 5 giây là 243.000 token. Seedance 2.0 tính $7,7 mỗi triệu token ở 1080p, nên video đó tốn $1,87. Seedance 2.5 tính $11,7 mỗi triệu token ở 1080p, nên cùng video đó tốn $2,84. Quy đổi theo trang giá BytePlus (đọc ngày 13 tháng 11 năm 2026): | Độ phân giải | Seedance 2.0, 5s | Seedance 2.0, 10s | Seedance 2.5, 5s | Seedance 2.5, 10s | |:-----------|-----------------:|------------------:|-----------------:|------------------:| | 480p | $0,35 | $0,70 | $0,51 | $1,03 | | 720p | $0,76 | $1,51 | $1,16 | $2,31 | | 1080p | $1,87 | $3,74 | $2,84 | $5,69 | | 4K | $3,89 | $7,78 | $4,57 | $9,14 | Seedance 2.5 có 4K trên BytePlus từ ngày 16 tháng 11 năm 2026, với $4,57 cho một video 5 giây không có video đầu vào, chạy tối đa 30 giây mỗi video so với 15 giây của 2.0, và nhận tối đa 50 tham chiếu (30 ảnh, 10 video, 10 đoạn âm thanh). Một video 2.5 đầy đủ 30 giây ở 1080p tốn khoảng $17. Seedance 2.0 Fast và Mini vẫn rẻ hơn và vẫn chỉ tới 720p: một video 720p dài 5 giây có giá niêm yết $0,60 trên Fast và $0,38 trên Mini. Seedance 2.5 Flash mới cũng dừng ở 720p, với $0,76 cho một video 720p dài 5 giây, và BytePlus mở model này cho lệnh gọi API từ ngày 15 tháng 11 năm 2026. Âm thanh được kèm theo, không tính thêm. Volcano định giá 2.5 ở mức ¥77 mỗi triệu token ở 1080p, nhưng yêu cầu xác minh danh tính thật và khuôn mặt theo quy định Trung Quốc, nên trên thực tế chỉ dùng được ở Trung Quốc. Giá niêm yết chưa phải toàn bộ chi phí. Để kích hoạt Seedance trên BytePlus, bạn cần trả trước khoảng $30: một [gói tài nguyên](https://docs.byteplus.com/en/docs/ModelArk/2191775) trả trước (nhỏ nhất là $30,10 cho 2.0 và $32 cho 2.5, không hoàn tiền, hết hạn sau 90 ngày) hoặc khoản nạp $30 vào số dư mà BytePlus khuyến nghị. Tài khoản cá nhân bị giới hạn 3 tác vụ đồng thời (180 request/phút), và 4K bị giới hạn một tác vụ đồng thời với mọi tài khoản. Không điều nào trong số đó khiến API chính thức trở thành một lựa chọn tồi. Nó đặt ra mốc để so sánh mọi phương án khác. ### Bốn cách chạy Seedance 2.0 qua useapi.net Một token useapi.net điều khiển Seedance 2.0 trên bốn nền tảng, với gói tài khoản bạn đang trả tiền. Chi phí dưới đây là chi phí gói cho mỗi video 1080p dài 5 giây, tính từ tỉ giá credit và giá gói trong tài liệu của chúng tôi. | Tuyến | Model Seedance | 5s 1080p, gói tháng | 5s 1080p, gói năm | Điểm mạnh | |:------|:----------------|-----------------------:|----------------------:|:---------------| | [PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) | 2.5, 2.5 Flash, 2.5 Draft, 2.0, Fast, Mini | $1,80 | $1,44 | 2.0 1080p và 4K rẻ nhất ($1,49 và $1,12 trên Ultra), khuôn mặt người thật | | [Dreamina](/docs/api-dreamina-v1/post-dreamina-videos) | 2.5, 2.5 Flash, 2.0, Fast, Mini, 1.5 Pro, dòng 1.0 | ~$1,83–1,87 | ~$1,78–1,81 | Seedance 2.5 với khuôn mặt thật và video dài, nhiều model nhất | | [MiniMax](/docs/api-minimax-v1/post-minimax-videos-create) | 2.0, Fast, Mini | $2,00 | $1,70 | 4K cùng quy trình ảnh tham chiếu phong phú | | [Runway](/docs/api-runwayml-v1/post-runwayml-videos-create) | 2.5, 2.0, Fast, Mini | $2,00 | $1,60 | khuôn mặt thật, kiểm duyệt nhẹ hơn Dreamina | Tuyến PixVerse tính Seedance 2.0 ở mức 90 credit mỗi giây ở 1080p, nên một video 5 giây là 450 credit. Trên gói Premium $60/tháng ($0,004 một credit), con số đó là $1,80, và trên Premium trả theo năm ($0,0032 một credit) là $1,44. Credit của Ultra đắt hơn, nhưng trên Ultra, PixVerse giảm 50% cho Seedance 2.0 trừ khi request gửi `relax_mode: false`, đưa giá một video xuống $1,49, hoặc $1,12 khi trả theo năm (Ultra có giá $199 một tháng cho 30.000 credit, tính đến ngày 15 tháng 11 năm 2026). Ở mức giá đầy đủ, tức là mức mà một request gửi `relax_mode: false` phải trả, một video trên Ultra là $2,99. PixVerse cũng chạy Seedance 2.0 ở 2160p (4K), với $4,00 cho 5 giây trên Premium, hoặc $3,20 khi trả theo năm, và $3,32 hoặc $2,48 trên Ultra, mức 4K rẻ nhất chúng tôi tìm thấy. Hồi tháng 7, tuyến này tốn $1,20 một video. Sau đó PixVerse định giá lại cả dòng Seedance và bỏ mức giảm giá cho Pro và Premium, và đó là thay đổi lớn nhất trong lần cập nhật này ([bảng chi phí PixVerse](/docs/api-pixverse-v2)). Lợi thế thật sự của tuyến Dreamina là Seedance 2.5: tuyến này nhận khuôn mặt thật và tạo video dài từ 31 đến 180 giây trong một job, điều API chính thức không làm được ([giá Seedance 2.5](#seedance-25-pricing)). Với Seedance 2.0 ở 1080p, giá gần như ngang API chính thức. Ở mức 57 credit mỗi giây trên gói Advanced vùng Canada, một video 5 giây tốn khoảng $1,83 khi trả theo tháng (C$109,99 cho 11.997 credit) và $1,81 khi trả theo năm (C$1.299,99), so với $1,87. Gói Advanced ở Mỹ chạy model này với 41 credit mỗi giây, khoảng $1,87 khi trả theo tháng ($79 cho 8.645 credit) và $1,78 khi trả theo năm ($900). Cả hai vùng đều chạy 1080p và 4K, và dòng 2.0 của Dreamina từ chối khuôn mặt người thật. Giá gói và tỉ giá credit được đọc lại ngày 12 tháng 11 năm 2026, quy đổi theo tỉ giá CAD/USD 0,7023 ([công cụ tính chi phí Dreamina](/docs/start-here/setup-dreamina#cost-calculator)). Tuyến MiniMax tính Seedance 2.0 ở mức 50 credit mỗi giây ở 1080p, không đổi từ tháng 7. Đây là mức giảm 50% cho Seedance của MiniMax, được ghi là ưu đãi có thời hạn (tính đến ngày 12 tháng 11 năm 2026). MiniMax cũng đã định giá lại các gói. Gói Master $89 (10.500 credit) cho giá $2,12 một video, gói Max $216 (27.000 credit) cho $2,00, và Master trả theo năm cho $1,70, với 4K ở mức $3,39 trên gói năm đó. Tuyến Runway giờ cũng đã có giá công bố. Seedance 2.0 của Runway tốn 40 credit mỗi giây ở 1080p, tức $2,00 một video trên gói Max $95 của Runway và $1,60 khi trả theo năm ([công cụ tính chi phí Runway](/docs/api-runwayml-v1)). `exploreMode` cũ của Runway vẫn chạy Seedance ở 480p và 720p mà không tốn credit trên các tài khoản Unlimited cũ đã bật Explore mode, cho tới khi Runway chuyển các tài khoản đó sang Max vào ngày 30 tháng 11 năm 2026. Runway không còn bật chế độ này cho tài khoản mới, và nó chậm: mỗi lần một video, mỗi video khoảng 10 đến 15 phút. Hãy coi đó là một tiện ích nếu bạn đã có, không phải lý do để chọn Runway. Đây là chi phí gói cho mỗi video, và các mức rẻ nhất giả định bạn cam kết gói năm và dùng hết credit. Premium trả theo năm là $576 trả trước cho 15.000 credit mỗi tháng, khoảng 33 video 1080p mỗi tháng, và Ultra trả theo năm là $1.788 cho 30.000 credit mỗi tháng, khoảng 133 video. Cũng nên nói rõ những đánh đổi. Các tuyến của chúng tôi tự động hóa tài khoản người dùng, nên số tác vụ đồng thời phụ thuộc vào tài khoản (thường 5–10 job song song, so với giới hạn theo key của API chính thức), và các nền tảng định giá lại không báo trước, như PixVerse vừa làm. Đổi lại, bạn có chi phí mỗi video thấp hơn giá chính thức với 2.0 trên gói năm (và với PixVerse gói tháng), không cần gói trả trước, và một token cho cả bốn nền tảng. ### Giá Seedance 2.5 Seedance 2.5 chạy trên ba trong bốn tuyến của chúng tôi: [PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4), [Dreamina](/docs/api-dreamina-v1/post-dreamina-videos) và [Runway](/docs/api-runwayml-v1/post-runwayml-videos-create). MiniMax không có model này. Với 2.5, khác biệt lớn hơn nằm ở những gì API chính thức không làm. [Hướng dẫn Seedance 2.5](https://docs.byteplus.com/en/docs/modelark/seedance-2-5) của chính ByteDance ghi rằng 2.5 "does not support directly uploading reference images or videos containing real human faces", và API chính thức dừng ở 30 giây mỗi video. [Tuyến Dreamina nhận khuôn mặt thật trên 2.5](/docs/api-dreamina-v1/post-dreamina-videos) trực tiếp và thêm chế độ video dài từ 31 đến 180 giây trong một job, cùng tính năng chỉnh sửa video, và trên tài khoản Canada tuyến này dựng 2.5 ở 4K với khoảng $4,15 cho mỗi video 5 giây trên gói Advanced của Canada, thấp hơn mức chính thức $4,57. [Tuyến Runway](/docs/api-runwayml-v1/post-runwayml-videos-create) cũng nhận khuôn mặt thật trên Seedance, và không có gói trả trước khoảng $30 phải mua trước video đầu tiên. Ở 1080p, tuyến PixVerse và Runway của chúng tôi cũng rẻ hơn giá của chính ByteDance cho mỗi video trên gói năm. Một video 5 giây, không có video đầu vào: | Tuyến | 1080p, 5 s | Độ dài tối đa | |:------|-----------:|:-----------| | [PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) *(Ultra, trả theo năm)* | $2,32 | 30s | | [PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) *(Premium, trả theo năm)* | $2,72 | 30s | | [Runway](/docs/api-runwayml-v1/post-runwayml-videos-create) *(Max, trả theo năm)* | $2,72 | 30s | | [BytePlus chính thức](https://docs.byteplus.com/en/docs/ModelArk/1544106) | $2,84 | 30s | PixVerse tính 2.5 ở mức 170 credit mỗi giây ở 1080p ($0,0032 một credit trên Premium trả theo năm), và Ultra giảm 45%, 468 credit một video với $0,00497 một credit khi trả theo năm ($3,10 trên gói Ultra tháng). Runway tính 68 credit mỗi giây ở 1080p ($0,008 một credit trên Max trả theo năm, $76 một tháng cho 9.500 credit, tính đến ngày 13 tháng 11 năm 2026). Giá gói năm giả định bạn dùng hết credit của gói. PixVerse giờ cũng tạo Seedance 2.5 ở 4K (2160p), với 286 credit mỗi giây (tính đến ngày 15 tháng 11 năm 2026). Một video 4K 5 giây là 1.430 credit, hoặc 787 sau mức giảm của Ultra, tức $3,91 trên Ultra trả theo năm, so với $4,57 trên API của chính ByteDance (tính đến ngày 18 tháng 11 năm 2026). ### Khoảng trống về khuôn mặt thật Cả Seedance 2.0 và 2.5 trên API chính thức đều từ chối ảnh và video tham chiếu có khuôn mặt người thật, trừ khi khuôn mặt đó đến từ chính kết quả gần đây của model, một nhân vật số có sẵn, hoặc một tài sản người thật đã được xác minh. Muốn làm việc với tham chiếu người thật ở quy mô lớn, bạn cần "Advanced Creation Rights" dành cho doanh nghiệp của ByteDance: [$14.000 một năm hoặc $1.400 một tháng](https://docs.byteplus.com/en/docs/modelark/2377608) cho một triệu tài sản, $42.000 một năm cho năm triệu, và phải xác minh doanh nghiệp. Các tuyến của chúng tôi nới lỏng hạn chế này ở bốn chỗ. [Tuyến PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) nhận khuôn mặt người thật trên Seedance 2.0, [tuyến Runway](/docs/api-runwayml-v1/post-runwayml-videos-create) ghi rõ hỗ trợ khuôn mặt thật trên Seedance và nhìn chung kiểm duyệt nhẹ hơn Dreamina, [tuyến MiniMax](/docs/api-minimax-v1/post-minimax-videos-create) nhận khuôn mặt thật trong ảnh tham chiếu (video tham chiếu có khuôn mặt nhận diện được vẫn bị kiểm duyệt), còn [tuyến Dreamina](/docs/api-dreamina-v1/post-dreamina-videos) nhận ảnh chân dung chụp thật trên Seedance 2.5, dù không nhận trên dòng 2.0. Với quảng cáo, UGC và quy trình của nhà sáng tạo xoay quanh một người thật, khác biệt đó quan trọng hơn vài cent mỗi video, và không cần hợp đồng doanh nghiệp. ### Giá API Seedance ở các bên bán lại Phần lớn nhà cung cấp Seedance bên thứ ba bán lại chính API của ByteDance và cộng thêm biên lợi nhuận. Dưới đây là Seedance 2.0 ở 5 giây và 1080p, mọi giá của bên thứ ba đều đọc từ trang của nhà cung cấp ngày 13 tháng 11 năm 2026: | Nhà cung cấp | 5s 1080p | Ghi chú | |:-------|---------:|:------| | [useapi.net (tuyến PixVerse)](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) | $1,12–1,80 | credit tài khoản người dùng, từ Ultra năm đến Premium tháng | | [useapi.net (tuyến Runway)](/docs/api-runwayml-v1/post-runwayml-videos-create) | $1,60–2,00 | gói Max, năm hoặc tháng | | [useapi.net (tuyến MiniMax)](/docs/api-minimax-v1/post-minimax-videos-create) | $1,70–2,12 | Master năm đến Master tháng ($2,00 với Max tháng) | | [useapi.net (tuyến Dreamina)](/docs/api-dreamina-v1/post-dreamina-videos) | ~$1,78–1,87 | tài khoản Mỹ hoặc Canada, Advanced năm hoặc tháng, đọc ngày 12 tháng 11 năm 2026 | | [BytePlus chính thức](https://docs.byteplus.com/en/docs/ModelArk/1544106) | $1,87 | mốc so sánh, OpenRouter chuyển tiếp đúng bằng giá này | | [Segmind](https://www.segmind.com/models/seedance-2.0/pricing) | $1,97 | cao hơn giá chính thức từ tháng 11 ($8,105 mỗi triệu token ở 1080p) | | [RunComfy](https://www.runcomfy.com/models/bytedance/seedance-v2/pro) | $2,00 | $0,40 mỗi giây, giảm từ $0,55 hồi tháng 7 | | [EachLabs](https://www.eachlabs.ai/bytedance/seedance-2-0/bytedance-seedance-2-0-text-to-video) | $2,22 | khoảng $0,444 mỗi giây, giảm từ $0,60 | | [Replicate](https://replicate.com/bytedance/seedance-2.0) | $2,25 | nhãn model "Official", $0,45 mỗi giây đầu ra | | [Poyo.ai](https://poyo.ai/models/seedance-2) | $2,25 | $0,45 mỗi giây | | [EvoLink](https://evolink.ai/seedance-2-0) | $2,48 | $0,497 mỗi giây | | [PiAPI](https://piapi.ai/seedance-2-0) | $2,50 | $0,50 mỗi giây | | [Kie.ai](https://kie.ai/seedance-2-0) | $2,55 | $0,51 mỗi giây | | [Atlas Cloud](https://www.atlascloud.ai/models/bytedance/seedance-2.0/text-to-video) | $2,74 | $2,20 với khuyến mãi 20% | | [WaveSpeedAI](https://wavespeed.ai/models/bytedance/seedance-2.0/text-to-video) | $3,00 | $0,60 mỗi giây | | [fal.ai](https://fal.ai/models/bytedance/seedance-2.0/text-to-video) | $3,41 | lựa chọn mặc định của thị trường, và vẫn đắt nhất | Dòng cuối đáng để suy nghĩ. fal.ai là nơi nhiều nhà phát triển tìm đến Seedance đầu tiên, và với $0,682 mỗi giây, họ tính cao hơn giá của chính ByteDance khoảng 82% cho cùng một model. Với 2.5 cũng vậy: video 720p của họ là $2,31 so với $1,16 chính thức, và video 1080p khoảng $5,69 so với $2,84. Seedance 2.5 có nhóm bên bán lại riêng. Replicate và OpenRouter chuyển tiếp đúng giá chính thức ($1,16 cho 720p, $0,51 cho 480p) nhưng dừng ở 720p, và [RunComfy](https://www.runcomfy.com/models/bytedance/seedance-2.5/text-to-video) giờ chỉ bán 2.5 ở 720p ($1,53 cho 5 giây trong đợt khuyến mãi 35% hiện tại). Trong số các nhà cung cấp bán 2.5 ở 1080p, [Poyo](https://poyo.ai/models/seedance-2-5) ($2,85), [Segmind](https://www.segmind.com/models/seedance-2.5/pricing) ($2,99) và [Atlas Cloud](https://www.atlascloud.ai/models/bytedance/seedance-2.5/text-to-video) ($2,98 với khuyến mãi 20%, $3,73 khi không có) chỉ chênh vài phần trăm so với giá chính thức, [EachLabs](https://www.eachlabs.ai/bytedance/seedance-2-5/bytedance-seedance-2-5-text-to-video) ($3,28) cao hơn khoảng 15%, còn [EvoLink](https://evolink.ai/seedance-2-5) ($3,70), [Kie.ai](https://kie.ai/seedance-2-5) ($3,95), [PiAPI](https://piapi.ai/seedance-2-5) ($4,00) và [WaveSpeedAI](https://wavespeed.ai/models/bytedance/seedance-2.5/text-to-video) ($4,50) cao hơn 30–60%. Bạn cũng sẽ thấy những mức giá niêm yết trông thấp hơn giá chính thức rất nhiều. Mọi trường hợp chúng tôi lần theo đều hóa ra là thứ khác chứ không phải một video tiêu chuẩn rẻ hơn. Vài dấu hiệu cần để ý khi một mức giá trông quá tốt: - Các biến thể "turbo" hoặc "tăng tốc" không phải model tiêu chuẩn: một nhà cung cấp niêm yết video Seedance 2.5 1080p dài 5 giây ở mức $1,10 dưới một tên model turbo mà ByteDance không công bố, trong khi Seedance 2.5 tiêu chuẩn của họ tốn $4,50 trên cùng trang. - Giá báo ở 720p khi bạn cần 1080p: một số trang "Seedance rẻ nhất", và các trang Seedance 2.5 trên Replicate và OpenRouter, hoàn toàn không có mức 1080p. - Giá 2.0 trên một trang về 2.5: Seedance 2.5 đắt hơn khoảng một nửa cho mỗi token, nên một mức giá "Seedance" không ghi phiên bản thì không so sánh được. - Credit không công bố giá trị bằng đô la: nếu một trang định giá theo credit mà không bao giờ nói một credit giá bao nhiêu, bạn không thể so sánh, và thường đó chính là mục đích. Điều này không có nghĩa các nhà cung cấp đó thiếu trung thực. Nó có nghĩa là phiên bản, độ phân giải và các điều khoản nhỏ phải khớp nhau thì phép so sánh mới có ý nghĩa. ### Cách gọi Seedance API Mọi mức giá ở trên chỉ cách bạn một lệnh gọi REST. Tạo một video Seedance 2.0 1080p qua tuyến PixVerse: ```bash curl --location 'https://api.useapi.net/v2/pixverse/videos/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="seedance-2.0"' \ --form 'prompt="A lone lighthouse on a storm-battered cliff at dusk, waves exploding against the rocks, beam sweeping through the rain, cinematic wide shot."' \ --form 'quality="1080p"' \ --form 'duration="5"' \ --form 'aspect_ratio="16:9"' ``` Cùng lệnh gọi đó chạy Seedance 2.5 khi đổi `model` thành `seedance-2.5`, với `duration` từ 4 đến 30. Hoặc, nếu tài khoản Runway của bạn vẫn còn Explore mode (Runway không còn cung cấp chế độ này cho tài khoản mới và sẽ dừng nó với các tài khoản Unlimited cũ vào ngày 30 tháng 11 năm 2026), cùng dạng lệnh gọi chạy không tốn credit ở 720p khi thêm `exploreMode`, mỗi lần một video và chậm: ```bash curl --location 'https://api.useapi.net/v1/runwayml/videos/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="seedance-2"' \ --form 'text_prompt="A lone lighthouse on a storm-battered cliff at dusk, waves exploding against the rocks, beam sweeping through the rain, cinematic wide shot."' \ --form 'resolution="720p"' \ --form 'duration="5"' \ --form 'exploreMode="true"' ``` Cả hai trả về một job id để kiểm tra (hoặc một webhook `replyUrl` khi video xong). Toàn bộ tham số, gồm ảnh tham chiếu, khung hình đầu và cuối, tỉ lệ khung hình và âm thanh, có trên trang của từng endpoint được liên kết trong các bảng ở trên. ### Nên dùng tuyến nào cho Seedance 2.0 hoặc 2.5? - Seedance 2.0 1080p rẻ nhất: [tuyến PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) với gói năm, $1,12 trên Ultra hoặc $1,44 trên Premium. Không cam kết gói năm thì PixVerse gói tháng ($1,49 trên Ultra, $1,80 trên Premium) vẫn thấp hơn mức chính thức $1,87, và mọi bên bán lại đều cao hơn. - 4K rẻ nhất: tuyến PixVerse với $2,48 trên Ultra năm hoặc $3,20 trên Premium năm, tiếp theo là [MiniMax](/docs/api-minimax-v1/post-minimax-videos-create) với $3,39 trên gói năm, tất cả đều thấp hơn mức chính thức $3,89. - Seedance 2.5 ở 1080p rẻ nhất: [tuyến PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) trên Ultra trả theo năm, $2,32 cho mỗi video 5 giây, tiếp theo là PixVerse Premium hoặc [tuyến Runway](/docs/api-runwayml-v1/post-runwayml-videos-create) trên Max, cả hai trả theo năm, với $2,72, so với $2,84 trên API chính thức. - Seedance 2.5 ở 4K rẻ nhất: [tuyến PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) trên Ultra trả theo năm, $3,91 cho mỗi video 5 giây, tiếp theo là [tuyến Dreamina](/docs/api-dreamina-v1/post-dreamina-videos) trên gói Advanced của Canada với khoảng $4,15, so với mức chính thức $4,57. - Seedance 2.5 với khuôn mặt người thật, hoặc video dài hơn 30 giây: [tuyến Dreamina](/docs/api-dreamina-v1/post-dreamina-videos). - Khuôn mặt người thật trên Seedance 2.0: tuyến [PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4), [MiniMax](/docs/api-minimax-v1/post-minimax-videos-create) hoặc [Runway](/docs/api-runwayml-v1/post-runwayml-videos-create). - Seedance 1.5 Pro hoặc 1.0: tuyến Dreamina, tuyến duy nhất có dòng 1.x. BytePlus đã ngừng 1.5 Pro trên API của chính họ. ### Ví dụ Kết quả Seedance 2.0 thật từ từng tuyến, lấy lại từ các bài blog của chúng tôi: cùng một model, chạy trên các nền tảng khác nhau. Ba trong số đó dùng khuôn mặt người thật, đúng quy trình mà API chính thức chỉ mở qua hợp đồng doanh nghiệp. PixVerse · Seedance 2.0 (Standard), 1080p: một khuôn mặt thật từ ảnh được đặt vào video tham chiếu và cho nói bằng một đoạn âm thanh tham chiếu, tất cả trong một request omni. Từ bài [PixVerse Seedance 2.0: Mini vs Fast vs Standard](/blog/260626a). <video poster="https://media.useapi.net/blog/2026-06-26-260626a/omni-standard-1080p-4s-9x16-swap-poster.jpg" src="https://media.useapi.net/blog/2026-06-26-260626a/omni-standard-1080p-4s-9x16-swap.mp4" style="width: 100%; max-width: 420px;" controls type="video/mp4" preload="metadata">Your browser does not support the video element.</video> Cũng có trên YouTube: [Seedance 2.0 Omni: Photo + Reference Video + Audio → One Clip (Mini vs Fast vs Standard)](https://youtube.com/shorts/apUc3lXrY_4). MiniMax · Seedance 2.0 (Standard), 1080p: cùng quy trình omni với khuôn mặt thật trên tuyến MiniMax. Từ bài [MiniMax Seedance 2.0: Standard vs Fast vs Mini](/blog/260626b). <video poster="https://media.useapi.net/blog/2026-06-26-260626b/std-1080-5s-nowm-poster.jpg" src="https://media.useapi.net/blog/2026-06-26-260626b/std-1080-5s-nowm.mp4" style="width: 100%; max-width: 420px;" controls type="video/mp4" preload="metadata">Your browser does not support the video element.</video> Runway · Seedance 2.0, 15 giây, 9:16: một khuôn mặt thật được tạo chuyển động trên tuyến Runway, tuyến kiểm duyệt nhẹ hơn với người thật. Từ bài [Seedance 2.0: Using Real Faces](/blog/260415). <video poster="https://media.useapi.net/articles/2024-08-11-runway-bash/runway-original-result-poster.jpg" src="https://media.useapi.net/articles/2024-08-11-runway-bash/runway-original-result.mp4" style="width: 100%; max-width: 420px;" controls type="video/mp4" preload="metadata">Your browser does not support the video element.</video> Dreamina · Seedance 2.0, tạo video từ văn bản với khẩu hình khớp lời chỉ từ prompt. Từ bài [Dreamina: Seedance 2.0 Video Generation](/blog/260402). <video poster="https://media.useapi.net/blog/2026-04-02-260402/seedance-2.0-prompt-9-16-poster.jpg" src="https://media.useapi.net/blog/2026-04-02-260402/seedance-2.0-prompt-9-16.mp4" style="width: 100%; max-width: 420px;" controls type="video/mp4" preload="metadata">Your browser does not support the video element.</video> Hướng dẫn liên quan: [video Seedance 2.0 qua Dreamina API](/docs/articles/dreamina-bash), [các lựa chọn thay thế Sora 2 API](/docs/articles/sora-2-api-alternatives) và [video PixVerse V6 qua PixVerse API](/docs/articles/pixverse-demo). ## Câu hỏi thường gặp **useapi.net có phải là Seedance API chính thức không?** Không. useapi.net là một lớp REST tự động hóa tài khoản [PixVerse](/docs/api-pixverse-v2), [Runway](/docs/api-runwayml-v1), [Dreamina](/docs/api-dreamina-v1) hoặc [MiniMax](/docs/api-minimax-v1) của chính bạn, mỗi nền tảng đều chạy Seedance. Bạn dùng credit gói người dùng của các nền tảng đó thay vì giá đo lường của API dành cho nhà phát triển của ByteDance. **Seedance 2.0 giá bao nhiêu mỗi video?** Qua useapi.net, một video 1080p dài 5 giây tốn $1,12 trên [tuyến PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) với gói Ultra năm, hoặc $1,44 với gói Premium năm ($1,80 với gói tháng), so với $1,87 trên API chính thức của ByteDance. API chính thức tính $0,35 ở 480p, $0,76 ở 720p, $1,87 ở 1080p và $3,89 ở 4K cho một video 5 giây, tính đến ngày 13 tháng 11 năm 2026. Xem [bảng giá chính thức](#official-seedance-20-and-25-api-pricing). **Seedance 2.5 giá bao nhiêu?** Qua useapi.net, Seedance 2.5 chạy được với khuôn mặt thật và video dài hơn 30 giây, những thứ API chính thức hạn chế: [tuyến Dreamina](/docs/api-dreamina-v1/post-dreamina-videos) nhận ảnh thật và chạy từ 31 đến 180 giây trong một job. Ở 1080p, một video 5 giây tốn $2,32 trên PixVerse Ultra và $2,72 trên PixVerse Premium hoặc Runway, trả theo năm, so với $2,84 trên API chính thức của ByteDance (tính đến tháng 11/2026). Xem [giá Seedance 2.5](#seedance-25-pricing). **Cách rẻ nhất để chạy Seedance 2.0 ở 1080p là gì?** Trong mọi thứ chúng tôi xác minh ngày 13 và 15 tháng 11 năm 2026, đó là [tuyến PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4): $1,12 mỗi video 5 giây trên gói Ultra năm, hoặc $1,44 trên gói Premium năm. Không cam kết gói năm thì PixVerse gói tháng ($1,49 trên Ultra, $1,80 trên Premium) là rẻ nhất, thấp hơn mức chính thức $1,87 của ByteDance, và không bên bán lại nào rẻ hơn (rẻ nhất là Segmind, $1,97). Xem [bảng giá thị trường](#seedance-api-pricing-across-resellers). **Có tạo được video Seedance với khuôn mặt người thật không?** Có, qua useapi.net: tuyến [PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4), [Runway](/docs/api-runwayml-v1/post-runwayml-videos-create) và [MiniMax](/docs/api-minimax-v1/post-minimax-videos-create) nhận khuôn mặt thật trên 2.0 (MiniMax trong ảnh tham chiếu), và [tuyến Dreamina](/docs/api-dreamina-v1/post-dreamina-videos) nhận trên 2.5. API chính thức chỉ cho phép đầu vào tham chiếu có khuôn mặt thật trên cả 2.0 và 2.5 với tài sản đã xác minh hoặc hợp đồng doanh nghiệp từ $14.000 một năm. **Vì sao useapi.net tính rẻ hơn API của chính ByteDance?** Với Seedance 2.0, các gói người dùng trên PixVerse (tháng hoặc năm), Runway, Dreamina và MiniMax (năm) có giá cho cùng một lần tạo thấp hơn giá đo lường dành cho nhà phát triển, và useapi.net tự động hóa một trong các tài khoản đó qua REST, với một [gói đăng ký](/docs/subscription) cho mọi dịch vụ. Với Seedance 2.5 thì phần lớn không phải vậy: giá chính thức thấp hơn, trừ khi so với gói năm của PixVerse hoặc Runway ở 1080p, và các tuyến của chúng tôi thắng ở khuôn mặt thật, video dài hơn và không cần gói trả trước. **Những mức giá Seedance dưới một đô la ở nơi khác có thật không?** Thường là không, với một video 1080p tiêu chuẩn. Đó thường là giá 720p, giá 2.0 trên trang 2.5, gói trọn gói được trợ giá, biến thể "turbo" đã chưng cất, hoặc credit không công bố giá trị bằng đô la. Xem [phần thị trường rộng hơn](#seedance-api-pricing-across-resellers). --- Sẵn sàng thử chưa? Toàn bộ phép so sánh là một script: [github.com/useapi/seedance-2-api](https://github.com/useapi/seedance-2-api) gửi một prompt tới cả bốn tuyến và in ra chi phí và tốc độ của từng tuyến, kèm một công cụ tính giá bạn có thể chạy mà không cần tài khoản nào. Sau đó chọn một tuyến, [PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) cho Seedance 2.0 1080p rẻ nhất, [Dreamina](/docs/api-dreamina-v1/post-dreamina-videos) cho Seedance 2.5 với khuôn mặt thật và video dài, kết nối tài khoản, và một [gói đăng ký useapi.net](/docs/subscription) điều khiển cả bốn bằng một token. Giá trong bài này đúng vào ngày 13 tháng 11 năm 2026, và thị trường này thay đổi hằng tháng, nên hãy xác nhận giá hiện tại trước khi mở rộng quy mô. #### Đăng ở nơi khác {: .no_toc #cross-posted } Cũng đăng trên [dev.to](https://dev.to/useapi/seedance-20-api-pricing-the-cheapest-ways-to-run-it-compared-4kno){:rel="nofollow"} (tiếng Anh). ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/seedance-2-api-pricing-zh === Document URL: https://useapi.net/docs/articles/seedance-2-api-pricing-zh --- layout: default title: "Seedance 2.0 和 2.5 API 价格:所有渠道逐一对比" seo_title: "Seedance 2.0 / 2.5 API 价格对比:官方、转售商与 useapi.net" description: "一条 5 秒 Seedance 2.0 或 2.5 视频在字节跳动官方 API、十几家转售商和 useapi.net 四条渠道上各要多少钱,2026 年 11 月 13 日重新核对。" keywords: [Seedance 2.0 API 价格, Seedance 2.5 API 价格, Seedance 价格, Seedance 2.0 价格, Seedance 2.5 价格, Seedance 每条视频费用, Seedance API 费用, 字节跳动视频 API, BytePlus ModelArk Seedance, 火山引擎 Seedance, 文生视频 API, Seedance 2.0 API, Seedance 2.5 API, Seedance pricing, Seedance 2.0 pricing, Seedance 2.5 pricing, Seedance 2.0 price, Seedance cost per video, Seedance API cost, ByteDance video API, fal.ai Seedance, Replicate Seedance, PixVerse Seedance, Runway Seedance, Dreamina Seedance, text to video API] image: /assets/images/articles/seedance-2-api-pricing-2026-10.jpg parent: Articles nav_exclude: true lang: zh-CN translation_key: seedance-2-pricing date: 2026-07-21 repo: https://github.com/useapi/seedance-2-api last_modified: 2026-11-18 nav_order: 90 --- ## Seedance 2.0 和 2.5 API 价格:所有渠道逐一对比 {: .no_toc #seedance-20-and-25-api-pricing-every-route-compared } 13 分钟阅读 • 2026 年 7 月 21 日(2026 年 11 月 18 日更新) ## 目录 {: .no_toc .text-delta #table-of-contents } ### 简介 一条 5 秒 1080p 的 Seedance 2.0 视频,在字节跳动官方 API 上要 $1.87,而经过核实的最低单条价格是 $1.12,来自 useapi.net 的 PixVerse 渠道,使用年付 Ultra 套餐(月付为 $1.49),或者使用年付 Premium 套餐,为 $1.44(月付为 $1.80),现在已经没有哪家转售商比它更便宜(最便宜的 Segmind 是 $1.97)。Seedance 2.5 则是另一回事。1080p 每条 $2.84 的字节跳动官方价,低于我们找到的所有转售商和所有月付套餐,只有年付套餐略低于它:PixVerse Ultra($2.32),以及 PixVerse Premium 或 Runway Max($2.72)。2026 年 11 月 13 日(PixVerse 渠道于 11 月 15 日再次核对),我们从字节跳动两个官方渠道和十几家第三方供应商的线上页面重新读取了价格,按当前积分费率重新计算了我们自己的四条渠道,并把所有价格统一换算成同一个单位:一条 5 秒、文生视频、无视频输入的视频的美元成本。 自 7 月首次发布以来,情况已经变了。PixVerse 重新定价了 Seedance,并取消了 Pro 和 Premium 套餐的折扣,使其渠道在月付套餐上从每条 $1.20 涨到 $1.80。字节跳动推出了 Seedance 2.5,token 价格比 2.0 高出约 50%,大多数转售商也随之推出了自己的 2.5 档位。 先说清楚我们的位置。useapi.net 是一个自带账号(BYO)的接入层,不是字节跳动的官方转售商。我们通过一个统一的 REST API 驱动你自己的 [PixVerse](/docs/api-pixverse-v2)、[Runway](/docs/api-runwayml-v1)、[Dreamina](/docs/api-dreamina-v1) 或 [MiniMax](/docs/api-minimax-v1) 账号,所以你花的是这些平台的消费者积分,而不是按量计费的开发者 API 价格。下面每个数字都标明了日期和来源。这个市场的价格每月都在变,投入预算前请再核对一次。 一个 useapi.net 订阅就能在下面全部四条渠道上运行 Seedance 2.0 和 2.5,用的是你已有的 PixVerse、Runway、Dreamina 或 MiniMax 套餐,并且覆盖本站所有其他 API。 [订阅 — $15/月](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03?client_reference_id={{ page.url | slugify | default: 'home' }}){: .btn .btn-purple .mr-2 .mb-3 } [四条渠道对比](#four-ways-to-run-seedance-20-through-useapinet) ### Seedance 2.0 和 2.5 官方 API 价格 字节跳动通过两个官方渠道销售 Seedance:面向国际市场的 [BytePlus ModelArk](https://docs.byteplus.com/en/docs/ModelArk/1544106) 和面向中国的[火山引擎(Volcano Engine)](https://www.volcengine.com/docs/82379/1544106)。两者都按百万 token 计费,一条视频的 token 数为 `width × height × 24fps × seconds ÷ 1024`。一条 5 秒 1080p 视频是 243,000 token。Seedance 2.0 在 1080p 下每百万 token $7.7,所以这条视频是 $1.87。Seedance 2.5 在 1080p 下每百万 token $11.7,同一条视频就是 $2.84。按 BytePlus 价格页(2026 年 11 月 13 日读取)换算如下: | 分辨率 | Seedance 2.0,5 秒 | Seedance 2.0,10 秒 | Seedance 2.5,5 秒 | Seedance 2.5,10 秒 | |:-----------|-----------------:|------------------:|-----------------:|------------------:| | 480p | $0.35 | $0.70 | $0.51 | $1.03 | | 720p | $0.76 | $1.51 | $1.16 | $2.31 | | 1080p | $1.87 | $3.74 | $2.84 | $5.69 | | 4K | $3.89 | $7.78 | $4.57 | $9.14 | Seedance 2.5 于 2026 年 11 月 16 日在 BytePlus 上支持 4K,一条不含视频输入的 5 秒视频 $4.57,单条视频最长 30 秒(2.0 为 15 秒),最多接受 50 个参考素材(30 张图片、10 段视频、10 段音频)。一条完整的 30 秒 1080p 2.5 视频约 $17。Seedance 2.0 Fast 和 Mini 仍然更便宜,最高仍是 720p:一条 720p 5 秒视频在 Fast 上标价 $0.60,在 Mini 上 $0.38。新的 Seedance 2.5 Flash 也只到 720p,一条 5 秒 720p 视频 $0.76,BytePlus 将于 2026 年 11 月 15 日开放其 API 调用。音频包含在内,不另收费。火山引擎的 2.5 价格是 1080p 每百万 token ¥77,但需要中国实名和人脸认证,实际上只面向中国用户。 标价并不是全部成本。在 BytePlus 上开通 Seedance 需要先付约 $30:要么购买预付[资源包](https://docs.byteplus.com/en/docs/ModelArk/2191775)(最小的 2.0 资源包 $30.10,2.5 资源包 $32,不可退款,90 天后过期),要么按 BytePlus 的建议充值 $30 余额。个人账号限制为 3 个并发任务(每分钟 180 次请求),4K 对所有人都限制为 1 个并发任务。这些都不意味着官方 API 不划算。它设定了一条基准线,所有替代方案都应该拿来与之比较。 ### 通过 useapi.net 运行 Seedance 2.0 的四种方式 一个 useapi.net token 就能在四个平台上驱动 Seedance 2.0,用的是你已经在付费的账号套餐。下表是每条 5 秒 1080p 视频的套餐成本,根据我们文档中的积分费率和套餐价格计算。 | 渠道 | Seedance 模型 | 5 秒 1080p,月付 | 5 秒 1080p,年付 | 优势 | |:------|:----------------|-----------------------:|----------------------:|:---------------| | [PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) | 2.5、2.5 Flash、2.5 Draft、2.0、Fast、Mini | $1.80 | $1.44 | 最便宜的 1080p 2.0 和 4K(Ultra 为 $1.49 和 $1.12),支持真人脸 | | [Dreamina](/docs/api-dreamina-v1/post-dreamina-videos) | 2.5、2.5 Flash、2.0、Fast、Mini、1.5 Pro、1.0 系列 | ~$1.83–1.87 | ~$1.78–1.81 | Seedance 2.5 支持真人脸和长视频,模型最全 | | [MiniMax](/docs/api-minimax-v1/post-minimax-videos-create) | 2.0、Fast、Mini | $2.00 | $1.70 | 4K,以及丰富的参考图工作流 | | [Runway](/docs/api-runwayml-v1/post-runwayml-videos-create) | 2.5、2.0、Fast、Mini | $2.00 | $1.60 | 支持真人脸,审核比 Dreamina 宽松 | PixVerse 渠道的 Seedance 2.0 在 1080p 下每秒 90 积分,所以一条 5 秒视频是 450 积分。在 $60/月的 Premium 套餐上(每积分 $0.004)是 $1.80,Premium 年付(每积分 $0.0032)则是 $1.44。Ultra 的积分更贵,但在 Ultra 上,只要请求没有发送 `relax_mode: false`,PixVerse 就给 Seedance 2.0 50% 折扣,一条视频降到 $1.49,年付 $1.12(Ultra 每月 $199 含 30,000 积分,截至 2026 年 11 月 15 日)。按 `relax_mode: false` 支付的全价,一条 Ultra 视频是 $2.99。PixVerse 的 Seedance 2.0 还能输出 2160p(4K),在 Premium 上 5 秒 $4.00,年付 $3.20,在 Ultra 上为 $3.32 或 $2.48,是我们找到的最便宜的 4K。7 月时这条渠道每条只要 $1.20,之后 PixVerse 重新定价了 Seedance 系列,并取消了此前 Pro 和 Premium 的折扣,这是本次更新中最大的变化([PixVerse 费用表](/docs/api-pixverse-v2))。 Dreamina 渠道真正的优势在 Seedance 2.5:它接受真人脸,并能在一个任务里生成 31 到 180 秒的长视频,这两点官方 API 都做不到([Seedance 2.5 价格](#seedance-25-pricing))。在 1080p 的 Seedance 2.0 上,它和官方 API 基本持平。在加拿大地区的 Advanced 套餐上每秒 57 积分,一条 5 秒视频月付约 $1.83(C$109.99 含 11,997 积分),年付约 $1.81(C$1,299.99),对比官方的 $1.87。美国 Advanced 套餐每秒 41 积分,月付约 $1.87($79 含 8,645 积分),年付约 $1.78($900)。两个地区都支持 1080p 和 4K,Dreamina 的 2.0 系列不接受真人脸。套餐价格和积分费率于 2026 年 11 月 12 日重新读取,按 CAD/USD 0.7023 换算([Dreamina 费用计算器](/docs/start-here/setup-dreamina#cost-calculator))。 MiniMax 渠道的 Seedance 2.0 在 1080p 下每秒 50 积分,自 7 月以来未变,这是 MiniMax 的 Seedance 50% 折扣,标注为限时优惠(截至 2026 年 11 月 12 日)。MiniMax 也重新定价了套餐。$89 的 Master 套餐(10,500 积分)每条 $2.12,$216 的 Max 套餐(27,000 积分)每条 $2.00,Master 年付每条 $1.70,该年付套餐上的 4K 为 $3.39。Runway 渠道现在也有了公开费率。它的 Seedance 2.0 在 1080p 下每秒 40 积分,在 Runway $95 的 Max 套餐上每条 $2.00,年付 $1.60([Runway 费用计算器](/docs/api-runwayml-v1))。Runway 旧版的 `exploreMode` 仍可在已开启 Explore mode 的老 Unlimited 账号上以 480p 和 720p 运行 Seedance,不消耗积分,直到 Runway 于 2026 年 11 月 30 日把这些账号迁移到 Max。Runway 已不再为新账号开启它,而且速度很慢:一次一条,每条大约 10 到 15 分钟。如果你已经有它,就当作额外福利,不要因为它选择 Runway。 这些是每条视频的套餐成本,其中最便宜的几个都以你真正用完的年付套餐为前提。Premium 年付需预付 $576,每月 15,000 积分,大约每月 33 条 1080p 视频,Ultra 年付为 $1,788,每月 30,000 积分,大约 133 条视频。 取舍也值得说明。我们的渠道自动化的是消费者账号,所以并发受账号限制(通常 5–10 个并行任务,而官方 API 按密钥限制),而且各平台会不打招呼地调价,PixVerse 刚刚就这么做了。换来的是:年付套餐(以及 PixVerse 月付)下 2.0 的单条成本低于官方,无需预付资源包,一个 token 通用全部四个平台。 ### Seedance 2.5 价格 Seedance 2.5 可以在我们四条渠道中的三条上运行:[PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4)、[Dreamina](/docs/api-dreamina-v1/post-dreamina-videos) 和 [Runway](/docs/api-runwayml-v1/post-runwayml-videos-create)。MiniMax 不提供 2.5。 在 2.5 上,更大的差别在于官方 API 不做什么。字节跳动自己的 [Seedance 2.5 指南](https://docs.byteplus.com/en/docs/modelark/seedance-2-5)写明 2.5“不支持直接上传包含真人脸的参考图片或视频”,而且官方 API 单条最长 30 秒。[Dreamina 渠道在 2.5 上直接接受真人脸](/docs/api-dreamina-v1/post-dreamina-videos),并提供一个在单个任务中生成 31 到 180 秒的长视频模式,外加视频编辑,在加拿大账号上还能以 4K 渲染 2.5,加拿大 Advanced 套餐下每条 5 秒视频约 $4.15,低于官方的 $4.57。[Runway 渠道](/docs/api-runwayml-v1/post-runwayml-videos-create)在 Seedance 上也接受真人脸,而且生成第一条视频之前不需要购买约 $30 的预付资源包。 在 1080p 下,我们的 PixVerse 和 Runway 渠道在年付套餐上的单条成本也低于字节跳动官方价。一条 5 秒、无视频输入的视频: | 渠道 | 1080p,5 秒 | 最长时长 | |:------|-----------:|:-----------| | [PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) *(Ultra,年付)* | $2.32 | 30 秒 | | [PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) *(Premium,年付)* | $2.72 | 30 秒 | | [Runway](/docs/api-runwayml-v1/post-runwayml-videos-create) *(Max,年付)* | $2.72 | 30 秒 | | [BytePlus 官方](https://docs.byteplus.com/en/docs/ModelArk/1544106) | $2.84 | 30 秒 | PixVerse 的 2.5 在 1080p 下每秒 170 积分(Premium 年付每积分 $0.0032),Ultra 给 45% 折扣,每条 468 积分,年付每积分 $0.00497(月付 Ultra 套餐为 $3.10)。Runway 在 1080p 下每秒 68 积分(Max 年付每积分 $0.008,每月 $76 含 9,500 积分,截至 2026 年 11 月 13 日)。年付价格的前提是你用完套餐积分。 PixVerse 现在也能以 4K(2160p)生成 Seedance 2.5,每秒 286 积分(截至 2026 年 11 月 15 日)。一条 5 秒 4K 视频是 1,430 积分,Ultra 折后为 787 积分,Ultra 年付为 $3.91,字节跳动自己的 API 为 $4.57(截至 2026 年 11 月 18 日)。 ### 真人脸的差距 在官方 API 上,Seedance 2.0 和 2.5 都拒绝包含真人脸的参考图片和视频,除非人脸来自模型自己最近的输出、预设的数字角色或经过认证的真人素材。要大规模使用真人参考,就需要字节跳动面向企业的“Advanced Creation Rights”:100 万个素材 [每年 $14,000 或每月 $1,400](https://docs.byteplus.com/en/docs/modelark/2377608),500 万个素材每年 $42,000,并需要企业认证。 我们的渠道在四个地方缓解了这个问题。[PixVerse 渠道](/docs/api-pixverse-v2/post-pixverse-videos-create-v4)在 Seedance 2.0 上接受真人脸,[Runway 渠道](/docs/api-runwayml-v1/post-runwayml-videos-create)文档中写明在 Seedance 上支持真人脸,审核总体比 Dreamina 宽松,[MiniMax 渠道](/docs/api-minimax-v1/post-minimax-videos-create)在参考图片中接受真人脸(含可识别人脸的参考视频仍会被审核),[Dreamina 渠道](/docs/api-dreamina-v1/post-dreamina-videos)在 Seedance 2.5 上接受真人照片,但其 2.0 系列不接受。对于围绕真人展开的广告、UGC 和创作者工作流来说,这个差别比每条视频差几美分更重要,而且不需要企业合同。 ### 各转售商的 Seedance API 价格 大多数第三方 Seedance 供应商都是在字节跳动官方 API 的基础上加价转售。下面是 5 秒 1080p 的 Seedance 2.0,每个第三方价格都于 2026 年 11 月 13 日从供应商的线上页面读取: | 供应商 | 5 秒 1080p | 备注 | |:-------|---------:|:------| | [useapi.net(PixVerse 渠道)](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) | $1.12–1.80 | 消费者账号积分,Ultra 年付到 Premium 月付 | | [useapi.net(Runway 渠道)](/docs/api-runwayml-v1/post-runwayml-videos-create) | $1.60–2.00 | Max 套餐,年付或月付 | | [useapi.net(MiniMax 渠道)](/docs/api-minimax-v1/post-minimax-videos-create) | $1.70–2.12 | Master 年付到 Master 月付(Max 月付 $2.00) | | [useapi.net(Dreamina 渠道)](/docs/api-dreamina-v1/post-dreamina-videos) | ~$1.78–1.87 | 美国或加拿大账号,Advanced 年付或月付,2026 年 11 月 12 日读取 | | [BytePlus 官方](https://docs.byteplus.com/en/docs/ModelArk/1544106) | $1.87 | 基准价,OpenRouter 直通价与之完全相同 | | [Segmind](https://www.segmind.com/models/seedance-2.0/pricing) | $1.97 | 自 11 月起高于官方(1080p 每百万 token $8.105) | | [RunComfy](https://www.runcomfy.com/models/bytedance/seedance-v2/pro) | $2.00 | 每秒 $0.40,7 月时为 $0.55 | | [EachLabs](https://www.eachlabs.ai/bytedance/seedance-2-0/bytedance-seedance-2-0-text-to-video) | $2.22 | 每秒约 $0.444,此前为 $0.60 | | [Replicate](https://replicate.com/bytedance/seedance-2.0) | $2.25 | 带“Official”模型标识,每输出秒 $0.45 | | [Poyo.ai](https://poyo.ai/models/seedance-2) | $2.25 | 每秒 $0.45 | | [EvoLink](https://evolink.ai/seedance-2-0) | $2.48 | 每秒 $0.497 | | [PiAPI](https://piapi.ai/seedance-2-0) | $2.50 | 每秒 $0.50 | | [Kie.ai](https://kie.ai/seedance-2-0) | $2.55 | 每秒 $0.51 | | [Atlas Cloud](https://www.atlascloud.ai/models/bytedance/seedance-2.0/text-to-video) | $2.74 | 20% 促销时 $2.20 | | [WaveSpeedAI](https://wavespeed.ai/models/bytedance/seedance-2.0/text-to-video) | $3.00 | 每秒 $0.60 | | [fal.ai](https://fal.ai/models/bytedance/seedance-2.0/text-to-video) | $3.41 | 市场默认选择,仍然最贵 | 最后一行值得细看。很多开发者首先在 fal.ai 上找 Seedance,而它每秒 $0.682,同一个模型比字节跳动官方价贵约 82%。在 2.5 上也一样:它的 720p 视频 $2.31,官方是 $1.16,1080p 视频约 $5.69,官方是 $2.84。 Seedance 2.5 有自己的一批转售商。Replicate 和 OpenRouter 完全按官方价直通(720p $1.16,480p $0.51),但最高只到 720p,[RunComfy](https://www.runcomfy.com/models/bytedance/seedance-2.5/text-to-video) 现在只卖 720p 的 2.5(目前 35% 优惠期间 5 秒 $1.53)。在提供 1080p 2.5 的供应商中,[Poyo](https://poyo.ai/models/seedance-2-5)($2.85)、[Segmind](https://www.segmind.com/models/seedance-2.5/pricing)($2.99)和 [Atlas Cloud](https://www.atlascloud.ai/models/bytedance/seedance-2.5/text-to-video)(20% 促销价 $2.98,原价 $3.73)与官方价相差不过几个百分点,[EachLabs](https://www.eachlabs.ai/bytedance/seedance-2-5/bytedance-seedance-2-5-text-to-video)($3.28)高出约 15%,[EvoLink](https://evolink.ai/seedance-2-5)($3.70)、[Kie.ai](https://kie.ai/seedance-2-5)($3.95)、[PiAPI](https://piapi.ai/seedance-2-5)($4.00)和 [WaveSpeedAI](https://wavespeed.ai/models/bytedance/seedance-2.5/text-to-video)($4.50)则高出 30–60%。 你还会看到一些远低于官方的标价。我们追查过的每一个,拆开来看都不是更便宜的标准视频。当价格好得不像真的时,可以留意以下几种情况: - 并非标准模型的“Turbo”或“加速”版本:有一家供应商以字节跳动并未发布的 turbo 模型名,把一条 1080p 5 秒的 Seedance 2.5 视频标价 $1.10,而同一网站上标准 Seedance 2.5 的价格是 $4.50。 - 你要的是 1080p,报价却是 720p:好几个“最便宜 Seedance”页面,以及 Replicate 和 OpenRouter 上的 Seedance 2.5,根本没有 1080p 档位。 - 介绍 2.5 的页面上写的是 2.0 的价格:Seedance 2.5 每 token 的价格约高出一半,所以不带版本号的“Seedance”价格没有可比性。 - 没有公开美元价值的积分:如果一个页面用积分给生成定价,却从不说明一个积分值多少钱,你就没法比较,而这通常正是它的用意。 这些都不说明那些供应商不诚实,只说明版本、分辨率和细则必须一致,比较才有意义。 ### 如何调用 Seedance API 上面的每个价格都只需一次 REST 调用。通过 PixVerse 渠道生成一条 1080p 的 Seedance 2.0 视频: ```bash curl --location 'https://api.useapi.net/v2/pixverse/videos/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="seedance-2.0"' \ --form 'prompt="A lone lighthouse on a storm-battered cliff at dusk, waves exploding against the rocks, beam sweeping through the rain, cinematic wide shot."' \ --form 'quality="1080p"' \ --form 'duration="5"' \ --form 'aspect_ratio="16:9"' ``` 把 `model` 改为 `seedance-2.5`,同样的调用就能运行 Seedance 2.5,`duration` 可设为 4 到 30 之间的任意值。或者,如果你的 Runway 账号还有 Explore mode(Runway 已不再为新账号提供,并将于 2026 年 11 月 30 日对老 Unlimited 账号停止提供),加上 `exploreMode`,同样结构的请求就能以 720p 不耗积分地运行,一次一条,速度较慢: ```bash curl --location 'https://api.useapi.net/v1/runwayml/videos/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="seedance-2"' \ --form 'text_prompt="A lone lighthouse on a storm-battered cliff at dusk, waves exploding against the rocks, beam sweeping through the rain, cinematic wide shot."' \ --form 'resolution="720p"' \ --form 'duration="5"' \ --form 'exploreMode="true"' ``` 两者都返回一个用于轮询的任务 id(或者在视频完成时通过 `replyUrl` webhook 通知)。完整参数,包括参考图片、首帧和尾帧、画面比例和音频,见上面各表格中链接的端点页面。 ### Seedance 2.0 或 2.5 该用哪条渠道? - 最便宜的 1080p Seedance 2.0:年付套餐的 [PixVerse 渠道](/docs/api-pixverse-v2/post-pixverse-videos-create-v4),Ultra 为 $1.12,Premium 为 $1.44。不签年付的话,PixVerse 月付(Ultra $1.49,Premium $1.80)仍低于官方的 $1.87,而所有转售商都比它贵。 - 最便宜的 4K:PixVerse 渠道在年付 Ultra 上 $2.48,或年付 Premium 上 $3.20,其次是年付的 [MiniMax](/docs/api-minimax-v1/post-minimax-videos-create) $3.39,都低于官方的 $3.89。 - 最便宜的 1080p Seedance 2.5:Ultra 年付的 [PixVerse 渠道](/docs/api-pixverse-v2/post-pixverse-videos-create-v4),每条 5 秒视频 $2.32,其次是 PixVerse Premium,或 Max 套餐的 [Runway 渠道](/docs/api-runwayml-v1/post-runwayml-videos-create),均为年付,$2.72,官方 API 为 $2.84。 - 最便宜的 4K Seedance 2.5:Ultra 年付的 [PixVerse 渠道](/docs/api-pixverse-v2/post-pixverse-videos-create-v4),每条 5 秒视频 $3.91,其次是加拿大 Advanced 套餐的 [Dreamina 渠道](/docs/api-dreamina-v1/post-dreamina-videos),约 $4.15,官方 API 为 $4.57。 - 需要真人脸的 Seedance 2.5,或长于 30 秒的视频:[Dreamina 渠道](/docs/api-dreamina-v1/post-dreamina-videos)。 - 需要真人脸的 Seedance 2.0:[PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4)、[MiniMax](/docs/api-minimax-v1/post-minimax-videos-create) 或 [Runway](/docs/api-runwayml-v1/post-runwayml-videos-create) 渠道。 - Seedance 1.5 Pro 或 1.0:Dreamina 渠道,唯一提供 1.x 系列的渠道。BytePlus 已在自己的 API 上下线 1.5 Pro。 ### 示例 下面是各渠道真实生成的 Seedance 2.0 视频,取自我们的博客文章:同一个模型,在不同平台上运行。其中三条用到了真人脸,而官方 API 把这种工作流放在企业合同之后。 PixVerse · Seedance 2.0(Standard),1080p:把照片中的真人脸放进参考视频,并用参考音频让它说话,全部在一次 omni 请求中完成。出自 [PixVerse Seedance 2.0: Mini vs Fast vs Standard](/blog/260626a)。 <video poster="https://media.useapi.net/blog/2026-06-26-260626a/omni-standard-1080p-4s-9x16-swap-poster.jpg" src="https://media.useapi.net/blog/2026-06-26-260626a/omni-standard-1080p-4s-9x16-swap.mp4" style="width: 100%; max-width: 420px;" controls type="video/mp4" preload="metadata">Your browser does not support the video element.</video> YouTube 上也有:[Seedance 2.0 Omni: Photo + Reference Video + Audio → One Clip (Mini vs Fast vs Standard)](https://youtube.com/shorts/apUc3lXrY_4)。 MiniMax · Seedance 2.0(Standard),1080p:同样的真人脸 omni 工作流,运行在 MiniMax 渠道上。出自 [MiniMax Seedance 2.0: Standard vs Fast vs Mini](/blog/260626b)。 <video poster="https://media.useapi.net/blog/2026-06-26-260626b/std-1080-5s-nowm-poster.jpg" src="https://media.useapi.net/blog/2026-06-26-260626b/std-1080-5s-nowm.mp4" style="width: 100%; max-width: 420px;" controls type="video/mp4" preload="metadata">Your browser does not support the video element.</video> Runway · Seedance 2.0,15 秒,9:16:在 Runway 渠道上让真人脸动起来,该渠道对真人的审核较宽松。出自 [Seedance 2.0: Using Real Faces](/blog/260415)。 <video poster="https://media.useapi.net/articles/2024-08-11-runway-bash/runway-original-result-poster.jpg" src="https://media.useapi.net/articles/2024-08-11-runway-bash/runway-original-result.mp4" style="width: 100%; max-width: 420px;" controls type="video/mp4" preload="metadata">Your browser does not support the video element.</video> Dreamina · Seedance 2.0,文生视频,仅凭提示词实现口型同步。出自 [Dreamina: Seedance 2.0 Video Generation](/blog/260402)。 <video poster="https://media.useapi.net/blog/2026-04-02-260402/seedance-2.0-prompt-9-16-poster.jpg" src="https://media.useapi.net/blog/2026-04-02-260402/seedance-2.0-prompt-9-16.mp4" style="width: 100%; max-width: 420px;" controls type="video/mp4" preload="metadata">Your browser does not support the video element.</video> 相关教程:[通过 Dreamina API 生成 Seedance 2.0 视频](/docs/articles/dreamina-bash)、[Sora 2 API 替代方案](/docs/articles/sora-2-api-alternatives)和[通过 PixVerse API 生成 PixVerse V6 视频](/docs/articles/pixverse-demo)。 ## 常见问题 **useapi.net 是官方的 Seedance API 吗?** 不是。useapi.net 是一个 REST 接入层,自动化你自己的 [PixVerse](/docs/api-pixverse-v2)、[Runway](/docs/api-runwayml-v1)、[Dreamina](/docs/api-dreamina-v1) 或 [MiniMax](/docs/api-minimax-v1) 账号,这些平台都能运行 Seedance。你花的是这些平台的消费者积分,而不是字节跳动按量计费的开发者 API 价格。 **Seedance 2.0 每条视频多少钱?** 通过 useapi.net,一条 5 秒 1080p 视频在 [PixVerse 渠道](/docs/api-pixverse-v2/post-pixverse-videos-create-v4)上,用年付 Ultra 套餐是 $1.12,用年付 Premium 是 $1.44(月付 $1.80),字节跳动官方 API 则是 $1.87。截至 2026 年 11 月 13 日,官方 API 的 5 秒视频价格为 480p $0.35、720p $0.76、1080p $1.87、4K $3.89。见[官方价格表](#official-seedance-20-and-25-api-pricing)。 **Seedance 2.5 多少钱?** 通过 useapi.net,Seedance 2.5 可以使用真人脸,也可以生成超过 30 秒的视频,这两点官方 API 都有限制:[Dreamina 渠道](/docs/api-dreamina-v1/post-dreamina-videos)接受真人照片,并能在一个任务中生成 31 到 180 秒的视频。在 1080p 下,一条 5 秒视频在 PixVerse Ultra 上是 $2.32,在 PixVerse Premium 或 Runway 上是 $2.72,均为年付,字节跳动官方 API 为 $2.84(截至 2026 年 11 月)。见 [Seedance 2.5 价格](#seedance-25-pricing)。 **以 1080p 运行 Seedance 2.0 最便宜的方式是什么?** 在我们于 2026 年 11 月 13 日和 15 日核实的所有选项中,是 [PixVerse 渠道](/docs/api-pixverse-v2/post-pixverse-videos-create-v4):用年付 Ultra 套餐,每条 5 秒视频 $1.12,用年付 Premium 则是 $1.44。不签年付的话,PixVerse 月付(Ultra $1.49,Premium $1.80)最便宜,低于字节跳动官方的 $1.87,没有任何转售商比它便宜(最便宜的 Segmind 是 $1.97)。见[市场价格表](#seedance-api-pricing-across-resellers)。 **可以用真人脸生成 Seedance 视频吗?** 可以,通过 useapi.net:[PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4)、[Runway](/docs/api-runwayml-v1/post-runwayml-videos-create) 和 [MiniMax](/docs/api-minimax-v1/post-minimax-videos-create) 渠道在 2.0 上接受真人脸(MiniMax 限参考图片),[Dreamina 渠道](/docs/api-dreamina-v1/post-dreamina-videos)在 2.5 上接受真人脸。官方 API 在 2.0 和 2.5 上都把真人脸参考输入限制在经过认证的素材,或起价每年 $14,000 的企业合同。 **useapi.net 为什么能比字节跳动自己的 API 便宜?** 在 Seedance 2.0 上,PixVerse(月付或年付)、Runway、Dreamina 和 MiniMax(年付)的消费者套餐给同一次生成的定价低于按量计费的开发者价格,而 useapi.net 通过 REST 自动化其中一个账号,一个[订阅](/docs/subscription)覆盖所有服务。在 Seedance 2.5 上大多不是这样:除了 1080p 下年付的 PixVerse 或 Runway 套餐,官方价格更低,我们的渠道胜在真人脸、更长的视频和无需预付资源包。 **别处看到的一美元以下的 Seedance 价格是真的吗?** 对标准的 1080p 视频来说,通常不是。它们往往是 720p 价格、2.5 页面上的 2.0 价格、补贴的包月套餐、蒸馏的“turbo”版本,或者没有公开美元价值的积分,见[更广泛的市场部分](#seedance-api-pricing-across-resellers)。 --- 准备试试了吗?整个对比就是一个脚本:[github.com/useapi/seedance-2-api](https://github.com/useapi/seedance-2-api) 把一个提示词发送到全部四条渠道,打印每条渠道的费用和速度,另附一个不需要任何账号就能运行的价格计算器。然后选一条渠道,[PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) 适合最便宜的 1080p Seedance 2.0,[Dreamina](/docs/api-dreamina-v1/post-dreamina-videos) 适合需要真人脸和长视频的 Seedance 2.5,绑定账号后,一个 [useapi.net 订阅](/docs/subscription)用一个 token 驱动全部四条渠道。本文价格截至 2026 年 11 月 13 日,这个市场每月都在变,扩大规模前请先确认实时价格。 #### 其他发布平台 {: .no_toc #cross-posted } 本文英文版也发布在 [dev.to](https://dev.to/useapi/seedance-20-api-pricing-the-cheapest-ways-to-run-it-compared-4kno){:rel="nofollow"}。 ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/seedance-2-api-pricing === Document URL: https://useapi.net/docs/articles/seedance-2-api-pricing --- layout: default title: "Seedance 2.0 and 2.5 API Pricing: Every Route, Compared" description: "What a 5-second Seedance 2.0 or 2.5 clip costs on ByteDance's official API, a dozen resellers and four useapi.net routes, re-checked November 13, 2026." keywords: [Seedance 2.0 API, Seedance 2.5 API, Seedance pricing, Seedance 2.0 pricing, Seedance 2.5 pricing, Seedance 2.0 price, Seedance cost per video, Seedance API cost, ByteDance video API, BytePlus ModelArk Seedance, fal.ai Seedance, Replicate Seedance, PixVerse Seedance, Runway Seedance, Dreamina Seedance, text to video API] image: /assets/images/articles/seedance-2-api-pricing-2026-10.jpg parent: Articles nav_exclude: true date: 2026-07-21 repo: https://github.com/useapi/seedance-2-api last_modified: 2026-11-18 nav_order: 90 translation_key: seedance-2-pricing --- ## Seedance 2.0 and 2.5 API Pricing: Every Route, Compared 13 min read • July 21, 2026 (November 18, 2026) ## Table of contents ### Introduction A 5-second 1080p Seedance 2.0 clip costs $1.87 on ByteDance's official API, and the lowest verified per-clip rate is $1.12 through useapi.net's PixVerse route on a yearly Ultra plan ($1.49 monthly), or $1.44 on a yearly Premium plan ($1.80 monthly), and no reseller under it any more (the cheapest, Segmind, is $1.97). Seedance 2.5 is a different story. At $2.84 per 1080p clip, ByteDance's own rate beats every reseller and every monthly plan we found, and only yearly plans edge under it: PixVerse Ultra ($2.32), and PixVerse Premium or Runway Max ($2.72). On November 13, 2026 (the PixVerse route again on November 15) we re-read the prices of ByteDance's two official channels and a dozen third-party vendors from their live pages, recomputed our own four routes from current credit rates, and normalized everything to one unit: the dollar cost of a 5-second, text-to-video clip with no video input. The picture has shifted since we first published this in July. PixVerse repriced Seedance and ended its Pro and Premium discount, lifting its route from $1.20 to $1.80 a clip on a monthly plan, ByteDance launched Seedance 2.5 at a roughly 50% higher token rate than 2.0, and most resellers followed with 2.5 tiers of their own. It is worth being upfront about where we sit. useapi.net is a bring-your-own-account layer, not an official ByteDance reseller. We drive your own [PixVerse](/docs/api-pixverse-v2), [Runway](/docs/api-runwayml-v1), [Dreamina](/docs/api-dreamina-v1), or [MiniMax](/docs/api-minimax-v1) account over a single REST API, so you spend those platforms' consumer credits instead of the metered developer-API rate. Every figure below carries its date and source, and prices in this market move monthly, so re-check before committing spend. One useapi.net subscription runs Seedance 2.0 and 2.5 on all four routes below, on the PixVerse, Runway, Dreamina or MiniMax plan you already have, and covers every other API on the site. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03?client_reference_id={{ page.url | slugify | default: 'home' }}){: .btn .btn-purple .mr-2 .mb-3 } [How the four routes compare](#four-ways-to-run-seedance-20-through-useapinet) ### Official Seedance 2.0 and 2.5 API pricing ByteDance sells Seedance through two official channels — [BytePlus ModelArk](https://docs.byteplus.com/en/docs/ModelArk/1544106) internationally and [Volcano Engine](https://www.volcengine.com/docs/82379/1544106) in China. Both bill per million tokens, where a clip's token count is `width × height × 24fps × seconds ÷ 1024`. A 5-second 1080p clip is 243,000 tokens. Seedance 2.0 charges $7.7 per million at 1080p, so that clip is $1.87. Seedance 2.5 charges $11.7 per million at 1080p, so the same clip is $2.84. Normalized, per the BytePlus pricing page (read November 13, 2026): | Resolution | Seedance 2.0, 5s | Seedance 2.0, 10s | Seedance 2.5, 5s | Seedance 2.5, 10s | |:-----------|-----------------:|------------------:|-----------------:|------------------:| | 480p | $0.35 | $0.70 | $0.51 | $1.03 | | 720p | $0.76 | $1.51 | $1.16 | $2.31 | | 1080p | $1.87 | $3.74 | $2.84 | $5.69 | | 4K | $3.89 | $7.78 | $4.57 | $9.14 | Seedance 2.5 reached 4K on BytePlus on November 16, 2026, at $4.57 for a 5-second clip without a video input, and runs up to 30 seconds per clip against 2.0's 15, and takes up to 50 references (30 images, 10 videos, 10 audio clips). A full 30-second 1080p 2.5 clip is about $17. Seedance 2.0 Fast and Mini remain cheaper and still cap at 720p — a 720p 5-second clip lists at $0.60 on Fast and $0.38 on Mini. The new Seedance 2.5 Flash also stops at 720p, at $0.76 for a 5-second 720p clip, and BytePlus opens it to API calls on November 15, 2026. Audio is included at no extra cost. Volcano prices 2.5 at ¥77 per million tokens at 1080p, but it requires Chinese real-name and face verification, so it is effectively China-only. The sticker price is not the whole cost. Activating Seedance on BytePlus takes about $30 up front — a prepaid [resource pack](https://docs.byteplus.com/en/docs/ModelArk/2191775) (the smallest are $30.10 for 2.0 and $32 for 2.5, non-refundable, expiring after 90 days) or the $30 balance top-up BytePlus recommends. Individual accounts are throttled to 3 concurrent tasks (180 requests/minute), and 4K is capped at a single concurrent task for everyone. None of that makes the official API a bad deal. It sets the bar every alternative should be measured against. ### Four ways to run Seedance 2.0 through useapi.net One useapi.net token drives Seedance 2.0 on four platforms, on the account plan you already pay for. Costs below are the plan cost per 5-second 1080p clip, derived from the credit rates and plan prices in our docs. | Route | Seedance models | 5s 1080p, monthly plan | 5s 1080p, yearly plan | Stands out for | |:------|:----------------|-----------------------:|----------------------:|:---------------| | [PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) | 2.5, 2.5 Flash, 2.5 Draft, 2.0, Fast, Mini | $1.80 | $1.44 | cheapest 1080p 2.0 and 4K ($1.49 and $1.12 on Ultra), real human faces | | [Dreamina](/docs/api-dreamina-v1/post-dreamina-videos) | 2.5, 2.5 Flash, 2.0, Fast, Mini, 1.5 Pro, 1.0 family | ~$1.83–1.87 | ~$1.78–1.81 | Seedance 2.5 with real faces and long videos, widest model range | | [MiniMax](/docs/api-minimax-v1/post-minimax-videos-create) | 2.0, Fast, Mini | $2.00 | $1.70 | 4K plus a rich reference-image workflow | | [Runway](/docs/api-runwayml-v1/post-runwayml-videos-create) | 2.5, 2.0, Fast, Mini | $2.00 | $1.60 | real faces, lighter moderation than Dreamina | The PixVerse route bills Seedance 2.0 at 90 credits a second at 1080p, so a 5-second clip is 450 credits. On the $60/month Premium plan ($0.004 a credit) that is $1.80, and on Premium billed yearly ($0.0032 a credit) it is $1.44. Ultra's credits cost more, but on Ultra PixVerse takes 50% off Seedance 2.0 unless the request sends `relax_mode: false`, which brings a clip to $1.49, or $1.12 billed yearly (Ultra is $199 a month for 30,000 credits, as of November 15, 2026). At the full price that `relax_mode: false` pays, an Ultra clip is $2.99. PixVerse also reaches 2160p (4K) on Seedance 2.0, at $4.00 for 5 seconds on Premium, or $3.20 billed yearly, and $3.32 or $2.48 on Ultra — the cheapest 4K we found. In July this route cost $1.20 a clip — PixVerse has since repriced the Seedance family and ended the Pro and Premium discount it carried, which is the single biggest change in this update ([PixVerse cost tables](/docs/api-pixverse-v2)). The Dreamina route's real advantage is Seedance 2.5: it takes real faces and makes long videos of 31 to 180 seconds in one job, which the official API does not ([Seedance 2.5 pricing](#seedance-25-pricing)). On Seedance 2.0 at 1080p it is essentially tied with the official API. At 57 credits a second on a Canada-region Advanced plan, a 5-second clip is about $1.83 billed monthly (C$109.99 for 11,997 credits) and $1.81 billed yearly (C$1,299.99), against $1.87. A US Advanced plan runs it at 41 credits a second, about $1.87 billed monthly ($79 for 8,645 credits) and $1.78 billed yearly ($900). Both regions run 1080p and 4K, and Dreamina's 2.0 family rejects real human faces. Plan prices and credit rates were read again on November 12, 2026, converted at CAD/USD 0.7023 ([Dreamina cost calculator](/docs/start-here/setup-dreamina#cost-calculator)). The MiniMax route bills Seedance 2.0 at 50 credits a second at 1080p, unchanged since July, which is MiniMax's 50% Seedance discount, labeled a limited-time offer (as of November 12, 2026). MiniMax has also repriced its plans. The $89 Master plan (10,500 credits) puts a clip at $2.12, the $216 Max plan (27,000 credits) at $2.00, and Master billed yearly at $1.70, with 4K at $3.39 on that yearly plan. The Runway route now has a published rate too. Its Seedance 2.0 costs 40 credits a second at 1080p, which is $2.00 a clip on Runway's $95 Max plan and $1.60 billed yearly ([Runway cost calculator](/docs/api-runwayml-v1)). Runway's legacy `exploreMode` still runs Seedance at 480p and 720p without spending credits on older Unlimited accounts that already have Explore mode enabled, until Runway moves those accounts to Max on November 30, 2026. Runway no longer enables it on new accounts, and it is slow — one clip at a time, roughly 10 to 15 minutes each. Treat it as a perk if you already have it, not a reason to pick Runway. These are plan costs per clip, and the cheapest of them assume a yearly commitment you actually use. Premium billed yearly is $576 up front for 15,000 credits a month, about 33 1080p clips a month, and Ultra billed yearly is $1,788 for 30,000 credits a month, about 133 clips. The trade-offs are worth naming. Our routes automate consumer accounts, so concurrency is account-bound (typically 5–10 parallel jobs, versus the official API's per-key limits), and the platforms reprice without notice, as PixVerse just did. What you get in return is a per-clip cost below official on 2.0 on yearly plans (and on PixVerse monthly), no prepaid pack, and one token across all four platforms. ### Seedance 2.5 pricing Seedance 2.5 runs on three of our four routes — [PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4), [Dreamina](/docs/api-dreamina-v1/post-dreamina-videos), and [Runway](/docs/api-runwayml-v1/post-runwayml-videos-create). MiniMax does not carry it. On 2.5 the bigger difference is what the official API won't do. ByteDance's own [Seedance 2.5 guide](https://docs.byteplus.com/en/docs/modelark/seedance-2-5) states that 2.5 "does not support directly uploading reference images or videos containing real human faces", and the official API stops at 30 seconds a clip. The [Dreamina route accepts real faces on 2.5](/docs/api-dreamina-v1/post-dreamina-videos) directly and adds a long video mode that runs from 31 to 180 seconds in one job, plus video edit, and on Canada accounts it renders 2.5 in 4K for about $4.15 per 5-second clip on Canada's Advanced plan, below the official $4.57. The [Runway route](/docs/api-runwayml-v1/post-runwayml-videos-create) also takes real faces on Seedance, and there is no prepaid pack of about $30 to buy before the first clip. At 1080p, our PixVerse and Runway routes also cost less per clip than ByteDance's own rate on a yearly plan. A 5-second, no-video-input clip: | Route | 1080p, 5 s | Max length | |:------|-----------:|:-----------| | [PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) *(Ultra, billed yearly)* | $2.32 | 30s | | [PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) *(Premium, billed yearly)* | $2.72 | 30s | | [Runway](/docs/api-runwayml-v1/post-runwayml-videos-create) *(Max, billed yearly)* | $2.72 | 30s | | [Official BytePlus](https://docs.byteplus.com/en/docs/ModelArk/1544106) | $2.84 | 30s | PixVerse bills 2.5 at 170 credits a second at 1080p ($0.0032 a credit on Premium billed yearly), and Ultra takes 45% off, 468 credits a clip at $0.00497 a credit billed yearly ($3.10 on a monthly Ultra plan). Runway bills 68 credits a second at 1080p ($0.008 a credit on Max billed yearly, $76 a month for 9,500 credits, as of November 13, 2026). The yearly rates assume you use the plan's credits. PixVerse now renders Seedance 2.5 in 4K (2160p) too, at 286 credits a second (as of November 15, 2026). A 5-second 4K clip is 1,430 credits, or 787 after Ultra's discount, which is $3.91 on Ultra billed yearly, against $4.57 on ByteDance's own API (as of November 18, 2026). ### The real-faces gap Both Seedance 2.0 and 2.5 reject reference images and videos that contain real human faces on the official API, unless the face comes from the model's own recent output, a preset digital character, or a verified real-person asset. Doing real-person reference work at scale means ByteDance's enterprise "Advanced Creation Rights" — [$14,000 a year or $1,400 a month](https://docs.byteplus.com/en/docs/modelark/2377608) for a million assets, $42,000 a year for five million, corporate verification required. Our routes soften this in four places. The [PixVerse route](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) accepts real human faces on Seedance 2.0, the [Runway route](/docs/api-runwayml-v1/post-runwayml-videos-create) documents real-face support on Seedance and generally lighter moderation than Dreamina, the [MiniMax route](/docs/api-minimax-v1/post-minimax-videos-create) accepts real faces in image references (video references with recognizable faces are still moderated), and the [Dreamina route](/docs/api-dreamina-v1/post-dreamina-videos) accepts photographic portraits on Seedance 2.5, though not on its 2.0 family. For advertising, UGC, and creator workflows that revolve around a real person, that difference matters more than a few cents per clip — and it does not require an enterprise contract. ### Seedance API pricing across resellers Most third-party Seedance vendors resell ByteDance's own API with a margin on top. Here is Seedance 2.0 at 5 seconds and 1080p, every third-party price read from the vendor's live page on November 13, 2026: | Vendor | 5s 1080p | Notes | |:-------|---------:|:------| | [useapi.net (PixVerse route)](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) | $1.12–1.80 | consumer-account credits, yearly Ultra to monthly Premium | | [useapi.net (Runway route)](/docs/api-runwayml-v1/post-runwayml-videos-create) | $1.60–2.00 | Max plan, yearly or monthly | | [useapi.net (MiniMax route)](/docs/api-minimax-v1/post-minimax-videos-create) | $1.70–2.12 | Master yearly to Master monthly ($2.00 on Max monthly) | | [useapi.net (Dreamina route)](/docs/api-dreamina-v1/post-dreamina-videos) | ~$1.78–1.87 | US or Canada accounts, Advanced yearly or monthly, read November 12, 2026 | | [Official BytePlus](https://docs.byteplus.com/en/docs/ModelArk/1544106) | $1.87 | the yardstick, matched exactly by OpenRouter's passthrough | | [Segmind](https://www.segmind.com/models/seedance-2.0/pricing) | $1.97 | above official since November ($8.105 per million tokens at 1080p) | | [RunComfy](https://www.runcomfy.com/models/bytedance/seedance-v2/pro) | $2.00 | $0.40 per second, down from $0.55 in July | | [EachLabs](https://www.eachlabs.ai/bytedance/seedance-2-0/bytedance-seedance-2-0-text-to-video) | $2.22 | about $0.444 per second, down from $0.60 | | [Replicate](https://replicate.com/bytedance/seedance-2.0) | $2.25 | "Official" model badge, $0.45 per output second | | [Poyo.ai](https://poyo.ai/models/seedance-2) | $2.25 | $0.45 per second | | [EvoLink](https://evolink.ai/seedance-2-0) | $2.48 | $0.497 per second | | [PiAPI](https://piapi.ai/seedance-2-0) | $2.50 | $0.50 per second | | [Kie.ai](https://kie.ai/seedance-2-0) | $2.55 | $0.51 per second | | [Atlas Cloud](https://www.atlascloud.ai/models/bytedance/seedance-2.0/text-to-video) | $2.74 | $2.20 with a 20% promotion | | [WaveSpeedAI](https://wavespeed.ai/models/bytedance/seedance-2.0/text-to-video) | $3.00 | $0.60 per second | | [fal.ai](https://fal.ai/models/bytedance/seedance-2.0/text-to-video) | $3.41 | the market's default, and still the most expensive | That last row is worth sitting with. fal.ai is where a lot of developers reach for Seedance first, and at $0.682 a second it charges about 82% more than ByteDance's own rate for the same model. It does the same on 2.5, where its 720p clip is $2.31 against the official $1.16 and its 1080p clip is about $5.69 against $2.84. Seedance 2.5 has its own reseller field. Replicate and OpenRouter pass the official rate through exactly ($1.16 for 720p, $0.51 for 480p) but stop at 720p, and [RunComfy](https://www.runcomfy.com/models/bytedance/seedance-2.5/text-to-video) now sells 2.5 at 720p only ($1.53 for 5 seconds during its current 35% promotion). Among vendors selling 2.5 at 1080p, [Poyo](https://poyo.ai/models/seedance-2-5) ($2.85), [Segmind](https://www.segmind.com/models/seedance-2.5/pricing) ($2.99) and [Atlas Cloud](https://www.atlascloud.ai/models/bytedance/seedance-2.5/text-to-video) ($2.98 with its 20% promotion, $3.73 without) sit within a few percent of official, [EachLabs](https://www.eachlabs.ai/bytedance/seedance-2-5/bytedance-seedance-2-5-text-to-video) ($3.28) runs about 15% above, and [EvoLink](https://evolink.ai/seedance-2-5) ($3.70), [Kie.ai](https://kie.ai/seedance-2-5) ($3.95), [PiAPI](https://piapi.ai/seedance-2-5) ($4.00), and [WaveSpeedAI](https://wavespeed.ai/models/bytedance/seedance-2.5/text-to-video) ($4.50) run 30–60% above it. You will also see sticker prices that look far lower than official. Every one we chased down decomposed into something other than a cheaper standard clip. A few patterns to watch for when a price looks too good: - "Turbo" or "accelerated" variants that are not the standard model — one vendor lists a 1080p 5-second Seedance 2.5 clip at $1.10 under a turbo model name ByteDance does not publish, while its standard Seedance 2.5 costs $4.50 on the same site. - Prices quoted at 720p when you wanted 1080p — several "cheapest Seedance" pages, and the Seedance 2.5 listings on Replicate and OpenRouter, have no 1080p tier at all. - 2.0 prices on a page about 2.5 — Seedance 2.5 costs about half again as much per token, so a "Seedance" price without a version number is not comparable. - Credits with no published dollar value — if a page prices generations in credits but never says what a credit costs, you cannot compare it, and that is usually the point. None of this means those vendors are dishonest — it means version, resolution, and fine print have to match before a comparison means anything. ### How to call the Seedance API Every price above is one REST call away. Generate a 1080p Seedance 2.0 clip through the PixVerse route: ```bash curl --location 'https://api.useapi.net/v2/pixverse/videos/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="seedance-2.0"' \ --form 'prompt="A lone lighthouse on a storm-battered cliff at dusk, waves exploding against the rocks, beam sweeping through the rain, cinematic wide shot."' \ --form 'quality="1080p"' \ --form 'duration="5"' \ --form 'aspect_ratio="16:9"' ``` The same call runs Seedance 2.5 by changing `model` to `seedance-2.5`, with `duration` anywhere from 4 to 30. Or, if your Runway account still has Explore mode — Runway no longer offers it on new accounts and ends it for legacy Unlimited accounts on November 30, 2026 — the same shape runs without credits at 720p by adding `exploreMode`, one slow clip at a time: ```bash curl --location 'https://api.useapi.net/v1/runwayml/videos/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="seedance-2"' \ --form 'text_prompt="A lone lighthouse on a storm-battered cliff at dusk, waves exploding against the rocks, beam sweeping through the rain, cinematic wide shot."' \ --form 'resolution="720p"' \ --form 'duration="5"' \ --form 'exploreMode="true"' ``` Both return a job id to poll (or a `replyUrl` webhook when the clip is ready). The full parameter set — reference images, first and last frames, aspect ratios, and audio — lives on each endpoint page linked in the tables above. ### Which route should you use for Seedance 2.0 or 2.5? - Cheapest 1080p Seedance 2.0 — the [PixVerse route](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) on a yearly plan, $1.12 on Ultra or $1.44 on Premium. Without a yearly commitment, PixVerse monthly ($1.49 on Ultra, $1.80 on Premium) is still under the official $1.87, and every reseller is above it. - Cheapest 4K — the PixVerse route at $2.48 on yearly Ultra or $3.20 on yearly Premium, then [MiniMax](/docs/api-minimax-v1/post-minimax-videos-create) at $3.39 yearly, all below the official $3.89. - Cheapest Seedance 2.5 at 1080p — the [PixVerse route](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) on Ultra billed yearly, $2.32 per 5-second clip, then PixVerse Premium or the [Runway route](/docs/api-runwayml-v1/post-runwayml-videos-create) on Max, both billed yearly, at $2.72, against $2.84 on the official API. - Cheapest Seedance 2.5 at 4K — the [PixVerse route](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) on Ultra billed yearly, $3.91 per 5-second clip, then the [Dreamina route](/docs/api-dreamina-v1/post-dreamina-videos) on Canada's Advanced plan at about $4.15, against the official $4.57. - Seedance 2.5 with real human faces, or clips longer than 30 seconds — the [Dreamina route](/docs/api-dreamina-v1/post-dreamina-videos). - Real human faces on Seedance 2.0 — the [PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4), [MiniMax](/docs/api-minimax-v1/post-minimax-videos-create), or [Runway](/docs/api-runwayml-v1/post-runwayml-videos-create) route. - Seedance 1.5 Pro or 1.0 — the Dreamina route, the only one carrying the 1.x family. BytePlus has retired 1.5 Pro on its own API. ### Examples Real Seedance 2.0 output from each route, reused from our blog posts — the same model, run on different platforms. Three of these lean on real human faces, the workflow the official API gates behind an enterprise contract. PixVerse · Seedance 2.0 (Standard), 1080p — a real face from a photo dropped into reference footage and given speech from a reference audio clip, all in one omni request. From [PixVerse Seedance 2.0: Mini vs Fast vs Standard](/blog/260626a). <video poster="https://media.useapi.net/blog/2026-06-26-260626a/omni-standard-1080p-4s-9x16-swap-poster.jpg" src="https://media.useapi.net/blog/2026-06-26-260626a/omni-standard-1080p-4s-9x16-swap.mp4" style="width: 100%; max-width: 420px;" controls type="video/mp4" preload="metadata">Your browser does not support the video element.</video> Also on YouTube: [Seedance 2.0 Omni: Photo + Reference Video + Audio → One Clip (Mini vs Fast vs Standard)](https://youtube.com/shorts/apUc3lXrY_4). MiniMax · Seedance 2.0 (Standard), 1080p — the same real-face omni workflow on the MiniMax route. From [MiniMax Seedance 2.0: Standard vs Fast vs Mini](/blog/260626b). <video poster="https://media.useapi.net/blog/2026-06-26-260626b/std-1080-5s-nowm-poster.jpg" src="https://media.useapi.net/blog/2026-06-26-260626b/std-1080-5s-nowm.mp4" style="width: 100%; max-width: 420px;" controls type="video/mp4" preload="metadata">Your browser does not support the video element.</video> Runway · Seedance 2.0, 15 seconds, 9:16 — a real face animated on the Runway route, which applies lighter moderation on real people. From [Seedance 2.0: Using Real Faces](/blog/260415). <video poster="https://media.useapi.net/articles/2024-08-11-runway-bash/runway-original-result-poster.jpg" src="https://media.useapi.net/articles/2024-08-11-runway-bash/runway-original-result.mp4" style="width: 100%; max-width: 420px;" controls type="video/mp4" preload="metadata">Your browser does not support the video element.</video> Dreamina · Seedance 2.0, text-to-video with lip-sync from a prompt alone. From [Dreamina: Seedance 2.0 Video Generation](/blog/260402). <video poster="https://media.useapi.net/blog/2026-04-02-260402/seedance-2.0-prompt-9-16-poster.jpg" src="https://media.useapi.net/blog/2026-04-02-260402/seedance-2.0-prompt-9-16.mp4" style="width: 100%; max-width: 420px;" controls type="video/mp4" preload="metadata">Your browser does not support the video element.</video> Related tutorials: [Seedance 2.0 video via the Dreamina API](/docs/articles/dreamina-bash), [Sora 2 API alternatives](/docs/articles/sora-2-api-alternatives) and [PixVerse V6 video via the PixVerse API](/docs/articles/pixverse-demo). ## FAQ **Is useapi.net an official Seedance API?** No. useapi.net is a REST layer that automates your own [PixVerse](/docs/api-pixverse-v2), [Runway](/docs/api-runwayml-v1), [Dreamina](/docs/api-dreamina-v1), or [MiniMax](/docs/api-minimax-v1) account, each of which runs Seedance. You spend those platforms' consumer credits rather than ByteDance's metered developer-API rate. **How much does Seedance 2.0 cost per video?** Through useapi.net, a 5-second 1080p clip is $1.12 on the [PixVerse route](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) on a yearly Ultra plan, or $1.44 on yearly Premium ($1.80 monthly), against $1.87 on ByteDance's official API. The official API charges $0.35 at 480p, $0.76 at 720p, $1.87 at 1080p, and $3.89 at 4K for a 5-second clip, as of November 13, 2026. See [the official price table](#official-seedance-20-and-25-api-pricing). **How much does Seedance 2.5 cost?** Through useapi.net, Seedance 2.5 runs on real faces and on clips past 30 seconds, which the official API restricts: the [Dreamina route](/docs/api-dreamina-v1/post-dreamina-videos) takes real photos and runs 31 to 180 seconds in one job. At 1080p a 5-second clip is $2.32 on PixVerse Ultra and $2.72 on PixVerse Premium or Runway, billed yearly, against $2.84 on ByteDance's official API (as of November 2026). See [Seedance 2.5 pricing](#seedance-25-pricing). **What is the cheapest way to run Seedance 2.0 at 1080p?** Of everything we verified on November 13 and 15, 2026, the [PixVerse route](/docs/api-pixverse-v2/post-pixverse-videos-create-v4): $1.12 per 5-second clip on a yearly Ultra plan, or $1.44 on yearly Premium. Without a yearly commitment, PixVerse monthly ($1.49 on Ultra, $1.80 on Premium) is cheapest, below ByteDance's official $1.87, and no reseller is under it (Segmind, the cheapest, is $1.97). See [the market table](#seedance-api-pricing-across-resellers). **Can I generate Seedance videos with real human faces?** Yes, through useapi.net: the [PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4), [Runway](/docs/api-runwayml-v1/post-runwayml-videos-create), and [MiniMax](/docs/api-minimax-v1/post-minimax-videos-create) routes accept real faces on 2.0 (MiniMax in image references), and the [Dreamina route](/docs/api-dreamina-v1/post-dreamina-videos) accepts them on 2.5. The official API restricts real-face reference inputs on both 2.0 and 2.5 to verified assets or an enterprise contract starting at $14,000 a year. **How does useapi.net charge less than ByteDance's own API?** On Seedance 2.0, consumer plans on PixVerse (monthly or yearly), Runway, Dreamina, and MiniMax (yearly) price the same generation below the metered developer rate, and useapi.net automates one of those accounts over REST, with one [subscription](/docs/subscription) across every service. On Seedance 2.5 it mostly does not — the official rate is lower except against a yearly PixVerse or Runway plan at 1080p, and our routes win on real faces, longer clips, and no prepaid pack instead. **Are the sub-dollar Seedance prices I see elsewhere real?** Usually not for a standard 1080p clip. They tend to be 720p rates, 2.0 prices on a 2.5 page, subsidized flat-rate plans, distilled "turbo" variants, or credits with no published dollar value — see [the wider market section](#seedance-api-pricing-across-resellers). --- Ready to try it? The whole comparison is one script — [github.com/useapi/seedance-2-api](https://github.com/useapi/seedance-2-api) sends a prompt to all four routes and prints the cost and speed of each, alongside a price calculator you can run with no account at all. Then pick a route — [PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) for the cheapest 1080p Seedance 2.0, [Dreamina](/docs/api-dreamina-v1/post-dreamina-videos) for Seedance 2.5 with real faces and long clips — connect the account, and a [useapi.net subscription](/docs/subscription) drives all four with one token. Prices in this article were current on November 13, 2026, and this market moves monthly, so confirm the live rate before you scale. ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. #### Cross posted Also published on [dev.to](https://dev.to/useapi/seedance-20-api-pricing-the-cheapest-ways-to-run-it-compared-4kno){:rel="nofollow"}. === URL: https://useapi.net/docs/articles/sora-2-api-alternatives === Document URL: https://useapi.net/docs/articles/sora-2-api-alternatives --- layout: default title: "Sora 2 API Alternatives Compared, With Code: Seedance 2.5, Omni Flash, MiniMax H3, Kling v3" description: "OpenAI removed the Sora 2 models and the Videos API on September 24, 2026 with no replacement named. Four working alternatives through useapi.net — Seedance 2.5, Omni 1.1 Flash, MiniMax H3 and Kling v3 — each generating the same six-second shot, priced side by side from free to $1.65 as of November 15, 2026." keywords: [Sora 2 API shutdown, Sora 2 alternative, Sora API deprecated, Sora 2 replacement API, Seedance 2.5 API, Omni 1.1 Flash API, Omni 1.2 Flash API, MiniMax H3 API, Kling v3 API, text to video API, video API pricing, image to video API] image: https://media.useapi.net/articles/2026-09-21-sora-2-api-alternatives/sora2-alt-00-character-reference-nano-banana-pro.jpg video: name: "Four Sora 2 alternatives, the same shot in each" description: "A neon-sign maker retires a SORA 2 sign, then presents four replacements — Seedance 2.5, Omni 1.1 Flash, MiniMax H3 and Kling v3 — each clip generated by the model on its own sign, with its six-second price on screen." url: https://media.useapi.net/articles/2026-09-21-sora-2-api-alternatives/sora2-alt-reel-31s-labelled-720p.mp4 embed: https://www.youtube.com/embed/W5vXcM2cCJs thumbnail: https://media.useapi.net/articles/2026-09-21-sora-2-api-alternatives/sora2-alt-00-character-reference-nano-banana-pro.jpg date: 2026-09-21 duration: PT31S width: 720 height: 1280 parent: Articles nav_exclude: true date: 2026-09-21 repo: https://github.com/useapi/sora-2-alternatives last_modified: 2026-11-15 nav_order: 85 --- ## Sora 2 API Alternatives Compared, With Code: Seedance 2.5, Omni Flash, MiniMax H3, Kling v3 9 min read • September 21, 2026 (November 15, 2026) ## Table of contents ### Introduction OpenAI removed `sora-2`, `sora-2-pro` and the whole Videos API on September 24, 2026, and its deprecation table names no replacement — so the migration is to another vendor, and through the [useapi.net](/) APIs the same six-second shot costs between nothing and $1.65 depending on which one you pick (as of November 15, 2026). Seedance 2.5, the most expensive at $1.65, costs about 20 times Omni 1.1 Flash at $0.08, and MiniMax H3 costs nothing on a PixVerse Premium or Ultra plan, all from the same brief, the same character and the same framing. At any real volume that gap, not the output quality, is what decides the choice. So the comparison is not just a table, the same scene was shot five times with one character: a neon-sign maker retires a SORA 2 sign, then presents each replacement in turn. Every clip was generated by the model whose name is on the sign, so what you are watching is each model describing itself, at its own price: <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 260px;max-width:320px;margin:0"> <video poster="https://media.useapi.net/articles/2026-09-21-sora-2-api-alternatives/sora2-alt-reel-31s-labelled-720p-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/articles/2026-09-21-sora-2-api-alternatives/sora2-alt-reel-31s-labelled-720p.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em"><strong>The result</strong> — 31 seconds, five models, one character ($3.93 in total at October 23, 2026 prices, all five clips · <a href="https://www.youtube.com/watch?v=W5vXcM2cCJs" target="_blank" rel="noopener noreferrer">watch on YouTube</a>)</figcaption> </figure> </div> ### What is actually being removed On March 24, 2026 OpenAI notified developers that the Videos API and every Sora 2 alias and snapshot — `sora-2`, `sora-2-pro`, `sora-2-2025-10-06`, `sora-2-2025-12-08`, `sora-2-pro-2025-10-06` — would be removed on September 24, 2026. The Sora consumer app had already closed on April 26, 2026. After the removal date the endpoints stopped answering, and OpenAI says it will permanently delete the data associated with your use of Sora once any final export window closes. Sora 2 is no longer available through useapi.net either. PixVerse, Runway, MiniMax and Dreamina, which ran it, stopped with the shutdown, so the four models below are the way to keep generating. The detail that decides the migration is the shape of the [deprecations table](https://developers.openai.com/api/docs/deprecations) itself. Most rows name a recommended replacement. The Sora 2 and Videos API rows leave that column empty, because OpenAI has no other video model to move you to. There is no in-house upgrade path — the only question is which vendor you go to instead. ### The four replacements Each of these generates video from a start frame with synchronised speech, which is the capability most Sora 2 pipelines were using. Prices are for a six-second clip at the resolution each clip was made, on the plan where it costs least, as of November 15, 2026. | Model | Vendor | Route | Six seconds | Notes | |---|---|---|---|---| | MiniMax H3 | MiniMax | [PixVerse API](/docs/api-pixverse-v2) | $0 | 768p or 1440p, no 720p tier, free on PixVerse Premium and Ultra | | Omni 1.1 Flash | Google | [Google Flow API](/docs/api-google-flow-v1) | $0.08 | generates at 360p or 720p, free upscale to 1080p | | Kling v3 | Kuaishou | [Kling API](/docs/api-kling-v1) | $0.69 | up to 4K, derives aspect from the frame | | Seedance 2.5 | ByteDance | [PixVerse API](/docs/api-pixverse-v2) | $1.65 | reference audio and video, via create-fusion | Google released Omni 1.2 Flash on November 5, 2026, after this comparison was made. It runs on the same route as `model: "omni-flash-1.2"`: any length from 3 to 15 seconds, a six-second 720p clip for 18 credits ($0.14 on Ultra $199.99), and [extend](/docs/api-google-flow-v1/post-google-flow-videos-extend) adds up to 10 seconds at a time with voices. Omni 1.1 Flash retires on December 5, 2026, and from then on an `omni-flash` request runs as Omni 1.2 Flash. MiniMax H3 is also the only one of the four whose weights are public, which matters if you are thinking about self-hosting. The [FAQ](#frequently-asked-questions) covers what the licence actually allows. ### Pricing Every route here is flat-fee. You bring your own vendor account, and useapi.net adds no per-generation charge — the credits above are the vendor's own, spent on your own plan. The figures use the best plan for each clip, on monthly billing. PixVerse Ultra ($199 for 30,000 credits, $0.00663 a credit) takes 45% off Seedance 2.5, so the six-second clip uses 248 credits instead of 450. Google AI Ultra $199.99 works out to roughly $0.008 per Flow credit, and Kling Ultra+ at $544.99 a month to $0.00956 a credit (the cheaper Kling Ultra is no longer sold). These are the lowest prices per clip, not the cheapest plans — Ultra and Ultra+ are PixVerse's and Kling's top plans, and Ultra $199.99 is Google's top tier, above Ultra $99.99. Yearly billing is cheaper again on all three. Full per-model, per-plan tables are on the [PixVerse overview](/docs/api-pixverse-v2), the [Google Flow overview](/docs/api-google-flow-v1) and the [Kling overview](/docs/api-kling-v1), and the numbers move when vendors change their promotions, so treat them as current as of November 15, 2026 rather than contractual. Route matters as much as plan. PixVerse's plan discounts apply unless the request sends `relax_mode: false`, which pays the full price: the MiniMax H3 clip is then 180 credits ($0.72 on Premium) and the Seedance 2.5 clip 450 ($2.99 on Ultra). MiniMax H3 also runs on our own [MiniMax API](/docs/api-minimax-v1) at 7 credits per second, about $0.34 on Hailuo AI Max for the same six seconds. Both PixVerse clips here were kept on one account for convenience, not because it was the cheapest way to buy them. The [model matrix](/model-matrix) lists every API that carries a given model. ### Getting the video back Every create call below is asynchronous — it returns an id, not a file. All of them authenticate the same way, with your useapi.net token as `Authorization: Bearer user:1234-…` (see [Setup](/docs/start-here/setup-useapi)), and that one token reaches all four vendors. | Route | Poll | Finished when | The file | |---|---|---|---| | PixVerse | [GET /videos/{video_id}](/docs/api-pixverse-v2/get-pixverse-videos-video_id) | `video_status_final: true` | `url` | | Google Flow | [GET /jobs/{jobId}](/docs/api-google-flow-v1/get-google-flow-jobs-jobid) | `status: "completed"` | `fifeUrl` on the returned media | | Kling | [GET /tasks/{task_id}](/docs/api-kling-v1/get-kling-tasks-task_id) | `status_final: true` | `works[0].resource.resource` | Any create call also accepts `replyUrl`, which calls you back when the job finishes instead of making you poll. ### Step 1: one character, reused everywhere Everything starts from a single generated portrait. Images are free on Google Flow — Nano Banana Pro is billed at $0.134 an image on the official Gemini API and included here — so this stage costs nothing however many times you run it. It is passed as `reference_1` to every later image request, which is what keeps the same face, the same room and the same bench across five clips made by four different vendors. Nothing else carries identity between them. The character is invented rather than photographed. In our runs Google's moderation was markedly stricter with real, identifiable people, and a generated reference sidesteps that entirely. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a> — the character, free on the <a href="/docs/api-google-flow-v1">Google Flow API</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'model="nano-banana-pro"' \ --form 'aspectRatio="9:16"' \ --form 'count="4"' \ --form 'prompt="Photoreal vertical phone video still, handheld, mid-shot from the waist up. A man in his late twenties stands behind a brushed steel workbench in a neon sign workshop: short black hair, thin glasses, plain black t-shirt. Bare pale wall behind him, nothing else in the room. He looks straight into the lens, mouth closed, expression flat. Natural phone-camera look, slight sensor noise, no colour grade."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-21-sora-2-api-alternatives/sora2-alt-00-character-reference-nano-banana-pro.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-21-sora-2-api-alternatives/sora2-alt-00-character-reference-nano-banana-pro.jpg" alt="The generated character used across all five clips: a neon-sign maker behind a steel workbench, reused as the reference for the Seedance 2.5, Omni 1.1 Flash, MiniMax H3 and Kling v3 start frames" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em"><strong>The character</strong> — Nano Banana Pro (0 credits)</figcaption> </figure> </div> ### Step 2: a start frame per model One image request per clip, each passing the character as `reference_1` and changing only the sign's text and colour. Holding the wording identical — *"Same man, same room, same framing as the reference image … change only the sign"* — is what keeps the framing stable enough that the five clips cut together. Text on a generated sign is the fragile part. Twelve characters (`SEEDANCE 2.5`) rendered cleanly here, but that is close to where image models start mangling glyphs, so check every frame before spending a credit on video. Pick the variant where the whole sign sits inside the frame, not one that runs off the edge — once the clip animates, anything near the border clips out of shot. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a> — a start frame, free on the <a href="/docs/api-google-flow-v1">Google Flow API</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'model="nano-banana-pro"' \ --form 'aspectRatio="9:16"' \ --form 'count="4"' \ --form 'reference_1="user:1234-email:…-image:168caede-…"' \ --form 'prompt="Same man, same room, same framing as the reference image: he stands behind the brushed steel workbench, both hands resting on the top edge of a large upright neon sign standing on the bench in front of him. Change only the sign: it now reads \"SEEDANCE 2.5\" in bright pink neon tubing on a clear acrylic backing, spanning the width of the bench, reflecting in the steel. He looks straight into the lens, mouth closed, expression flat. Photoreal vertical phone video still, natural phone-camera look, slight sensor noise, no colour grade."' ``` `reference_1` is the character from Step 1. </details> <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 150px;max-width:165px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-21-sora-2-api-alternatives/sora2-alt-02-start-frame-seedance-2-5-nano-banana-pro.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-21-sora-2-api-alternatives/sora2-alt-02-start-frame-seedance-2-5-nano-banana-pro.jpg" alt="Seedance 2.5 start frame: the sign maker behind a pink SEEDANCE 2.5 neon sign, the ByteDance Sora 2 replacement" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.8em">Seedance 2.5</figcaption> </figure> <figure style="flex:1 1 150px;max-width:165px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-21-sora-2-api-alternatives/sora2-alt-03-start-frame-omni-1-1-flash-nano-banana-pro.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-21-sora-2-api-alternatives/sora2-alt-03-start-frame-omni-1-1-flash-nano-banana-pro.jpg" alt="Omni 1.1 Flash start frame: the sign maker behind an amber OMNI FLASH neon sign, the Google Sora 2 replacement" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.8em">Omni 1.1 Flash</figcaption> </figure> <figure style="flex:1 1 150px;max-width:165px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-21-sora-2-api-alternatives/sora2-alt-04-start-frame-minimax-h3-nano-banana-pro.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-21-sora-2-api-alternatives/sora2-alt-04-start-frame-minimax-h3-nano-banana-pro.jpg" alt="MiniMax H3 start frame: the sign maker behind a cyan MINIMAX H3 neon sign, the MiniMax Sora 2 replacement" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.8em">MiniMax H3</figcaption> </figure> <figure style="flex:1 1 150px;max-width:165px;margin:0"> <a href="https://media.useapi.net/articles/2026-09-21-sora-2-api-alternatives/sora2-alt-05-start-frame-kling-v3-nano-banana-pro.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/articles/2026-09-21-sora-2-api-alternatives/sora2-alt-05-start-frame-kling-v3-nano-banana-pro.jpg" alt="Kling v3 start frame: the sign maker behind a green KLING V3 neon sign, the Kuaishou Sora 2 replacement" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.8em">Kling v3</figcaption> </figure> </div> The start frames live in Google Flow, and the video calls below are on three different vendors. Omni 1.1 Flash takes the Flow `mediaGenerationId` directly. For the others, download the frame with [GET /assets/{mediaGenerationId}](/docs/api-google-flow-v1/get-google-flow-assets-mediagenerationid), then upload the file to [POST /files](/docs/api-pixverse-v2/post-pixverse-files) for PixVerse and use the returned `path`, or to [POST /assets](/docs/api-kling-v1/post-kling-assets) for Kling and use the returned URL. ### Step 3: the farewell clip, on Sora 2 itself The opening clip was generated on Sora 2 through [PixVerse](/docs/api-pixverse-v2) before the shutdown. The sign maker boxes the sign and ships it off. Sora 2 only took 4, 8 or 12 seconds, with no six-second option, so this one is eight, trimmed back to six in the reel. Sora 2 is no longer available: OpenAI shut it down on September 24, 2026, so this clip can't be made again. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-pixverse-v2/post-pixverse-videos-create-v4">POST /videos/create-v4</a> — Sora 2, via the <a href="/docs/api-pixverse-v2">PixVerse API</a> (no longer runs)</summary> Kept for reference: this is the call that made the clip above. It no longer runs, because Sora 2 is no longer available. ```bash curl --location 'https://api.useapi.net/v2/pixverse/videos/create-v4' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'model="sora-2"' \ --form 'quality="720p"' \ --form 'duration="8"' \ --form 'first_frame_path="upload/96c1035e-….jpeg"' \ --form 'prompt="He looks into the lens and says, flat: \"Sora 2'\''s done. Museum of useless AI shit.\" He drags an open cardboard box into frame from the right, lifts the neon sign off the bench and drops it in, folds the lid shut, then shoves the box out of frame to the right. Handheld phone camera, slight drift."' ``` `first_frame_path` comes from [POST /files](/docs/api-pixverse-v2/post-pixverse-files). </details> <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:230px;margin:0"> <video poster="https://media.useapi.net/articles/2026-09-21-sora-2-api-alternatives/sora2-alt-clip-1-sora-2-farewell-pixverse-720p-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/articles/2026-09-21-sora-2-api-alternatives/sora2-alt-clip-1-sora-2-farewell-pixverse-720p.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em"><strong>Sora 2</strong> — 720p ($0.64 for eight seconds)</figcaption> </figure> </div> ### Step 4: one clip per replacement The same prompt shape drives all four, with only the model name and the closing line changed. Each names itself, gives a flat endorsement, then an honest catch. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-pixverse-v2/post-pixverse-videos-create-v4">POST /videos/create-v4</a> — Seedance 2.5 and MiniMax H3, via the <a href="/docs/api-pixverse-v2">PixVerse API</a></summary> ```bash curl --location 'https://api.useapi.net/v2/pixverse/videos/create-v4' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'model="seedance-2.5"' \ --form 'quality="720p"' \ --form 'duration="6"' \ --form 'first_frame_path="upload/8bb69d77-….jpeg"' \ --form 'prompt="The man holds the neon sign on the bench with both hands. He looks into the lens and says, flat: \"Seedance two point five. Best model.\" He pauses. He says: \"Pricey as fuck.\" The neon sign flickers off and back on twice while he speaks. Handheld phone camera, slight drift."' ``` For MiniMax H3 change `model` to `minimax-h3` and `quality` to `768p` — it publishes no 720p tier. Neither model accepts an `audio` field — both generate native audio and reject the flag. Both also require `duration` and `quality`, which are optional only on PixVerse's own models. </details> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos">POST /videos</a> — Omni 1.1 Flash, via the <a href="/docs/api-google-flow-v1">Google Flow API</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'model="omni-flash"' \ --form 'aspectRatio="portrait"' \ --form 'resolution="720p"' \ --form 'duration="6"' \ --form 'startImage="user:1234-email:…-image:aeecdde7-…"' \ --form 'prompt="The man holds the neon sign on the bench with both hands. He looks into the lens and says, flat: \"Omni Flash. Google'\''s finest.\" He pauses. He says: \"Insane moderation. But real cheap.\" The neon sign flashes off and back on several times while he speaks. Handheld phone camera, slight drift."' ``` `aspectRatio` defaults to `landscape` here and the start frame does not override it — pass `portrait` explicitly or a 9:16 frame still returns a 16:9 clip. </details> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-kling-v1/post-kling-videos-image2video-frames">POST /videos/image2video-frames</a> — Kling v3, via the <a href="/docs/api-kling-v1">Kling API</a></summary> ```bash curl --location 'https://api.useapi.net/v1/kling/videos/image2video-frames' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'model_name="kling-v3-0"' \ --form 'mode="pro"' \ --form 'duration="6"' \ --form 'image="https://s15-kling.klingai.com/kimg/…"' \ --form 'prompt="The green neon sign switches off completely, then back on. It does this twice. The man holds the sign on the bench with both hands and looks into the lens, his face blank and still. He says, flat: \"Kling V3. Kling is the King.\" He pauses. He says: \"Nuff said.\" Handheld phone camera, slight drift."' ``` `image` is a URL returned by [POST /assets](/docs/api-kling-v1/post-kling-assets). Kling v3 rejects `aspect_ratio` and derives it from the frame, and audio is on by default. </details> <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:8px"> <figure style="flex:1 1 150px;max-width:175px;margin:0"> <video poster="https://media.useapi.net/articles/2026-09-21-sora-2-api-alternatives/sora2-alt-clip-2-seedance-2-5-pixverse-720p-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/articles/2026-09-21-sora-2-api-alternatives/sora2-alt-clip-2-seedance-2-5-pixverse-720p.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.8em"><strong>Seedance 2.5</strong> ($1.80 on Oct 23)</figcaption> </figure> <figure style="flex:1 1 150px;max-width:175px;margin:0"> <video poster="https://media.useapi.net/articles/2026-09-21-sora-2-api-alternatives/sora2-alt-clip-3-omni-1-1-flash-google-flow-720p-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/articles/2026-09-21-sora-2-api-alternatives/sora2-alt-clip-3-omni-1-1-flash-google-flow-720p.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.8em"><strong>Omni 1.1 Flash</strong> ($0.08 on Oct 23)</figcaption> </figure> <figure style="flex:1 1 150px;max-width:175px;margin:0"> <video poster="https://media.useapi.net/articles/2026-09-21-sora-2-api-alternatives/sora2-alt-clip-4-minimax-h3-pixverse-768p-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/articles/2026-09-21-sora-2-api-alternatives/sora2-alt-clip-4-minimax-h3-pixverse-768p.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.8em"><strong>MiniMax H3</strong> ($0.72 on Oct 23)</figcaption> </figure> <figure style="flex:1 1 150px;max-width:175px;margin:0"> <video poster="https://media.useapi.net/articles/2026-09-21-sora-2-api-alternatives/sora2-alt-clip-5-kling-v3-kling-api-1080p-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/articles/2026-09-21-sora-2-api-alternatives/sora2-alt-clip-5-kling-v3-kling-api-1080p.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.8em"><strong>Kling v3</strong> ($0.69 on Oct 23)</figcaption> </figure> </div> ### What changes when you move off Sora 2 * Duration grids differ, and a hard-coded value will not port. Sora 2 took 4, 8 or 12 seconds. Omni 1.1 Flash takes 4, 6, 8 or 10 (Omni 1.2 Flash any length from 3 to 15), MiniMax H3 5 to 15, Kling v3 3 to 15, and Seedance 2.5 anything from 4 to 30. * Resolution tiers are not uniform either. Omni 1.1 Flash generates at 360p or 720p, MiniMax H3 skips 720p entirely and jumps 768p to 1440p, Seedance 2.5 reaches 1080p and Kling v3 goes to 4K. Mixing them means conforming everything to the lowest common size, so pick that size before you shoot. * Quality varies more than the resolution numbers suggest. At the same nominal size the H3 clip came back at 1.3 Mbps against Seedance's 6.5 Mbps, and it is visibly the softest of the set. * Voice is the one capability that does not port cleanly. Seedance 2.5 is the only one of the four that accepts an uploaded audio clip as a reference, and only through [create-fusion](/docs/api-pixverse-v2/post-pixverse-videos-create-fusion). Omni 1.1 Flash offers Google's preset voices through `referenceAudio_1`, and Kling can carry a voice on a character [element](/docs/api-kling-v1/post-kling-elements). Each clip here uses its model's own native voice, which is why they differ. * Prompts mostly carry over, with one habit worth adopting: give each physical action its own sentence and describe expressions positively. Trailing clauses and negations get dropped, unevenly, by all four. ### What it cost | Step | Model | Credits | Cost | |---|---|---|---| | Character portrait, 9:16 | Nano Banana Pro | 0 | $0 | | Four start frames, 9:16 | Nano Banana Pro | 0 | $0 | | Clip 1, Sora 2 (before the shutdown), 8s 720p, trimmed to 6s | `sora-2` | 160 | $0.64 | | Clip 2, Seedance 2.5, 6s 720p | `seedance-2.5` | 450 | $1.80 | | Clip 3, Omni 1.1 Flash, 6s 720p | `omni-flash` | 10 | $0.08 | | Clip 4, MiniMax H3, 6s 768p | `minimax-h3` | 180 | $0.72 | | Clip 5, Kling v3, 6s 1080p | `kling-v3-0` | 72 | $0.69 | | **Total** | | | **$3.93** | This is the run's own log: the credits each clip used, priced at October 23, 2026 rates, when all five came to $3.93. Today's prices are in [the replacements table](#the-four-replacements). Images cost nothing on Google Flow, so iterate on the character and the signs as long as you like before spending anything on video. ### Run it yourself Every call on this page chains into two scripts. [`useapi/sora-2-alternatives`](https://github.com/useapi/sora-2-alternatives) holds them along with every prompt above in `prompts.json`: `frames/` generates the character and a start frame per model, and `clips/` sends each frame to the model named on its sign, then prints the credit cost the API returned. The frame stage is free, so you can iterate on the character and the signs as long as you like before spending anything. One command does the cheap end of the comparison on its own: ```bash node clips.mjs <API_TOKEN> omni ``` Related tutorials: [Omni Flash video via the Google Flow API](/docs/articles/omni-flash-bash), [Kling v3 video via the Kling API](/docs/articles/kling-bash) and [Seedance 2.0 and 2.5 API pricing compared](/docs/articles/seedance-2-api-pricing). ### Frequently asked questions - **When exactly does the Sora 2 API stop working?** It stopped on September 24, 2026. OpenAI announced it on March 24, 2026, covering the Videos API and every `sora-2` alias and snapshot. The endpoints no longer answer, and OpenAI permanently deletes the associated data once any final export window closes. Sora 2 is no longer available through useapi.net either, so the four models above are the way to keep generating. - **What does OpenAI recommend migrating to?** Nothing. The [deprecations table](https://developers.openai.com/api/docs/deprecations) leaves the recommended-replacement column empty for both rows, because OpenAI has no other video model in the API. Migration means another vendor. - **Which alternative is closest to Sora 2 in capability?** For the common case — a start frame plus synchronised speech — all four here do it. Seedance 2.5 is the most capable, taking up to 30 reference images plus 10 reference videos and 10 reference audios — 50 in total, through [create-fusion](/docs/api-pixverse-v2/post-pixverse-videos-create-fusion) — and it is also the most expensive at $1.65 per six seconds on PixVerse Ultra (as of November 15, 2026). Omni 1.1 Flash does the same core job for $0.08 with a 720p ceiling. - **Is MiniMax H3 really open source?** Its weights are public — MiniMax published them in early August 2026, 33B parameters, on [Hugging Face](https://huggingface.co/MiniMaxAI/MiniMax-H3). It is open-*weight* under a custom community licence whose territory clause requires an application form for the USA, EU, UK and South Korea, so "open source" is a loose description of it. The full repository runs to hundreds of gigabytes, though the smallest usable checkpoint is far smaller. - **Do I pay useapi.net per generation?** No. You bring your own vendor account and pay a flat [$15/month](/docs/subscription) for API access. The credits in the table are the vendor's own, spent against your plan. See [Pricing](#pricing). ### Conclusion Visit our <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg" alt=""> Discord Server</a> or <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg" alt=""> Telegram Channel</a> for any support questions and concerns. Check our [GitHub repo](https://github.com/useapi/sora-2-alternatives) with code examples. #### Cross posted Also published on [dev.to](https://dev.to/useapi/sora-2-api-alternatives-compared-with-code-seedance-25-omni-flash-minimax-h3-kling-v3-4cek){:rel="nofollow"}, discussed on [Reddit](https://www.reddit.com/r/ThirdPartyAPI/comments/1wm1agp/sora_2_api_alternatives_compared_with_code/){:rel="nofollow"}, and shared on [Bluesky](https://bsky.app/profile/useapi.net/post/3mvyugq6wgz27){:rel="nofollow"}. === URL: https://useapi.net/docs/articles/suno-api-alternative-es === Document URL: https://useapi.net/docs/articles/suno-api-alternative-es --- layout: default lang: es translation_key: suno-api-alternative title: "Alternativa a la API de Suno: ACE Music, Mureka, Lyria 3.5, TemPolor y MiniMax" seo_title: "Alternativa a la API de Suno: ACE Music, Mureka, Lyria, TemPolor, MiniMax" description: "Alternativa a la API de Suno con useapi.net: ACE Music v1, número 1 del ranking vocal de Artificial Analysis por delante de Suno v6, además de Mureka V9.5, Lyria 3.5, TemPolor y MiniMax, por entre US$0,01 y US$0,02 la canción." keywords: [alternativa a la API de Suno, API alternativa a Suno, API de ACE Music, API de ACE Music v1, API de ACE-Step, API para generar canciones con IA, API de canciones con voz, API de música con IA, precios de API de música con IA, API de generación de canciones, API de texto a canción, API de Mureka, API de Mureka V9.5, API de Lyria 3.5, API de Flow Music, precios de la API de Lyria, API de TemPolor, API de MiniMax Music, Suno API alternative, Suno alternative API, ACE Music API, ACE Music v1 API, ACE-Step API, AI song generator API, AI song API with vocals, AI music API, AI music API pricing, song generation API, text to song API, Mureka API, Mureka V9.5 API, Lyria 3.5 API, Flow Music API, Lyria API pricing, TemPolor API, TemPolor v4.8 API, MiniMax Music API, MiniMax Music 3.0 API, MiniMax music API pricing] image: /assets/images/articles/ai-music-flagships-compared.jpg video: name: "Cinco API de música con IA con las mismas seis consignas" description: "ACE Music v1, TemPolor v4.8 e i4, MiniMax Music-3.0, Google Lyria 3.5 y Mureka V9.5 con las mismas seis consignas: los 30 segundos más fuertes de cada pista, con el volumen igualado, y el prompt, el precio y el tiempo de generación en pantalla." embed: https://www.youtube.com/embed/MSUGckk4JqU thumbnail: https://i.ytimg.com/vi/MSUGckk4JqU/maxresdefault.jpg date: 2026-11-14 duration: PT15M width: 1920 height: 1080 parent: Articles nav_exclude: true date: 2026-10-20 last_modified: 2026-11-18 nav_order: 906 --- ## Alternativa a la API de Suno: ACE Music, Mureka, Lyria 3.5, TemPolor y MiniMax {: .no_toc #suno-api-alternative-ace-music-mureka-lyria-35-tempolor-and-minimax } 7 min de lectura • 20 de octubre de 2026 (18 de noviembre de 2026) ## Índice {: .no_toc .text-delta #table-of-contents } ### Introducción Con useapi.net, ACE Music v1, que ocupa el primer puesto del [ranking de música vocal de Artificial Analysis](https://artificialanalysis.ai/music/leaderboard/vocals) por delante de Suno v6, crea canciones completas por REST con tu suscripción de [ACE Music](https://acemusic.ai/pricing/). Otros cuatro modelos de canciones con voz funcionan de la misma manera: Mureka V9.5 y Lyria 3.5 de Google, ambos entre los seis primeros de ese ranking, TemPolor v4.8 y MiniMax Music 3.0, con tu suscripción del sitio web de [Mureka](https://www.mureka.ai/subscribe), [Flow Music](https://www.flowmusic.app/pricing), [TemPolor](https://www.tempolor.com/pricing) o [MiniMax Audio](https://www.minimax.io/audio/subscribe). La API para desarrolladores de Suno es una beta para socios seleccionados, sin documentación pública ni lista de precios (a noviembre de 2026). useapi.net es un servicio [de terceros](/docs/legal#affiliation--third-party-services), sin afiliación con Suno, Timedomain, Kunlun Tech, Google, Qustar Technology ni MiniMax. ### Precio por canción Lo que cuesta una canción con voz en la API oficial de cada creador ([Mureka](https://platform.mureka.ai/pricing), la [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) de Google, [TemPolor](https://platform.tempolor.com/docs/6665893m0), [MiniMax](https://platform.minimax.io/docs/pricing/overview#about-music-models), cerrada a nuevos usuarios desde el 20 de agosto de 2026) y en cada suscripción del sitio web (en dólares estadounidenses, a noviembre de 2026). Cada suscripción incluye un número mensual de créditos, y cada canción usa una cantidad fija de ellos, así que una canción cuesta su parte de la suscripción. | Modelo | API oficial | Suscripción mensual del sitio web | Precio por canción | |---|---|---|---| | ACE Music v1 | — | ACE Music Creator $9,90 (1.000 cr/mes) | $0,02 / 2 cr (500 canciones/mes) | | ACE Music v1 | — | ACE Music Artist $29 (2.500 cr/mes) | $0,023 / 2 cr (1.250 canciones/mes) | | ACE-Step v1.5 XL (de 10 a 240 s, solo MP3) | — (código abierto) | Cualquier plan de ACE Music (incluido el plan Free) | $0 / 0 cr (sin créditos) | | Mureka V9.5 | $0,15 (prepago desde $1.000) | Mureka Pro $10 (5.000 cr/mes) | $0,024 / 12 cr (416 canciones/mes) | | Mureka V9.5 | $0,15 (prepago desde $1.000) | Mureka Premier $30 (20.000 cr/mes) | $0,018 / 12 cr (1.666 canciones/mes) | | Lyria 3.5 | $0,08 (por canción) | Flow Music Starter $8 (3.000 cr/mes) | $0,013 / 5 cr (600 canciones/mes) | | Lyria 3.5 | $0,08 (por canción) | Flow Music Member $64 (30.000 cr/mes) | $0,011 / 5 cr (6.000 canciones/mes) | | TemPolor v4.8 | $0,04 (por llamada, prepago desde $100) | TemPolor Ultra $29,99 | $0 / 0 cr (sin cargo por canción) | | MiniMax Music 3.0 | $0,15 (cerrada a nuevos usuarios desde el 20 de agosto de 2026) | MiniMax Audio Pro $99 (3.000.000 cr/mes) | $0,01 / 300 cr (10.000 canciones/mes) | - Con pago anual, ACE Music Artist cuesta US$16,58 al mes, lo que deja una canción de ACE Music v1 en unos US$0,013. Los 20 créditos diarios del plan Free generan unas 10 canciones al día para uso personal, y los derechos comerciales vienen con Creator y Artist. - [ACE-Step](https://ace-step.github.io) v1.5 XL es el modelo de código abierto de ACE Studio y StepFun, con tempo (`bpm`), tonalidad (`key`) y compás (`timeSignature`) a tu elección. No gasta créditos en ningún plan de ACE Music, incluido el plan Free, mientras que el sitio de terceros acestep.io cobra unos US$0,14 por canción mediante una API que requiere su plan Studio de US$49 al mes. - Cuando el modelo escribe la letra a partir de un prompt, la API de Mureka cobra US$0,50 en lugar de US$0,15, y las de MiniMax y TemPolor agregan US$0,01, mientras que con useapi.net una canción cuesta lo mismo en ambos casos. - Los créditos de la API de TemPolor cuestan lo mismo en todos los tamaños de paquete, así que el volumen nunca baja su precio. - Con pago anual, Flow Music Member cuesta US$48 al mes, lo que deja una canción de Lyria en unos US$0,008. - Las suscripciones de Google AI incluyen un plan de Flow Music, con créditos separados de los créditos de Google AI: Starter en [Google AI Plus](https://support.google.com/googleone/answer/16882689?hl=es), Plus en [Google AI Pro](https://support.google.com/googleone/answer/14534406?hl=es) y Member en [Google AI Ultra](https://support.google.com/googleone/answer/16286513?hl=es). - Con más de una suscripción, un solo token de useapi.net funciona con todas y reparte tus canciones entre ellas automáticamente. ### Lo que hace cada uno - ACE Music v1, con la [ACE Music API](/docs/api-acemusic-v1): dos canciones por solicitud a partir de un prompt o de tu propio estilo y letra, cantadas o instrumentales, de 30 segundos a 10 minutos. ACE Music v1.1 Preview hace [covers y mashups](/docs/api-acemusic-v1/post-acemusic-music#modes) que siguen la melodía de una canción, las canciones e imágenes que [subes](/docs/api-acemusic-v1/post-acemusic-files) guían canciones nuevas, y en Creator y Artist sus canciones se separan en [stems](/docs/api-acemusic-v1/post-acemusic-music-stems) y se [descargan](/docs/api-acemusic-v1/get-acemusic-music-download) en WAV, MIDI o MusicXML. El gratuito ACE-Step v1.5 XL agrega remixes, ediciones y tempo, tonalidad y compás a tu elección. Cada cuenta ejecuta hasta 4 solicitudes a la vez. - Mureka V9.5, con la [Mureka API](/docs/api-mureka-v1): dos canciones por llamada, de hasta 5 minutos, a partir de un prompt de una línea o de tu letra más un estilo. En Mureka Premier canta con tu propia voz mediante un [personaje](/docs/api-mureka-v1/post-mureka-music-characters) reutilizable y separa una canción en [stems](/docs/api-mureka-v1/post-mureka-music-stems) más MIDI. También escribe [partituras](/docs/articles/mureka-sheet-music) en MusicXML y PDF, hace [remixes](/docs/api-mureka-v1/post-mureka-music-remix) de una canción en un estilo nuevo, la extiende y edita secciones, con hasta 10 generaciones a la vez por cuenta. - Lyria 3.5, con la [Flow Music API](/docs/api-flowmusic-v1), que controla [Google Flow Music](https://www.flowmusic.app): un par A/B por llamada, en WAV, mp3 o m4a. [POST music/edit](/docs/api-flowmusic-v1/post-flowmusic-music-edit) hace covers, remixes de la letra, extensiones de hasta 300 segundos, reemplazos de secciones, efectos de audio y una separación en cuatro stems con el mismo plan. Pasa `model="lyria-3.5"`, porque la API mantiene `lyria-3-pro` como predeterminado. Los planes de pago ejecutan de 8 a 16 generaciones a la vez. - TemPolor v4.8, con la [TemPolor API](/docs/api-tempolor-v1): canciones de hasta 5 minutos en más de 30 idiomas a partir de un prompt o de tu propia letra, cantadas por una [voz clonada](/docs/api-tempolor-v1/post-tempolor-music-cloned-voices) o por una de sus voces de artista, o construidas sobre un [archivo MIDI](/docs/api-tempolor-v1/post-tempolor-music-midi) que subes. Cada canción se [descarga](/docs/api-tempolor-v1/get-tempolor-music-download-job_id) en mp3, wav o un ZIP de stems, [music/stems-splitter](/docs/api-tempolor-v1/post-tempolor-music-stems-splitter) separa tu propio audio y [music/instrumental](/docs/api-tempolor-v1/post-tempolor-music-instrumental) ejecuta el modelo i4 para pistas sin voz. Se ejecutan hasta 10 generaciones a la vez. - MiniMax Music 3.0, con la [MiniMax API](/docs/api-minimax-v1/post-minimax-music-create): de una a tres canciones por llamada a partir de un prompt de estilo y tu letra, o de una letra que escribe el propio modelo, además de instrumentales y covers de una [pista de referencia](/docs/api-minimax-v1/post-minimax-music-reference). Las canciones llegan en MP3 de 256 kbps y, con `stream: true`, el audio se reproduce mientras se genera. ### Escucha primero Cada pista de abajo está completa y sin editar, y la página de la que viene cada una muestra la llamada a la API que la generó. Todas vienen de nuestra [comparación de estos modelos con las mismas seis consignas](/docs/articles/ai-music-flagships-compared), a la que ACE Music v1 se sumó junto a los otros cuatro el 14 de noviembre de 2026. Las pistas de Lyria están convertidas del WAV de la API a MP3 para que un navegador pueda reproducirlas, y cada pista de ACE Music v1 es la primera de las dos canciones que ACE Music genera por solicitud. Un prompt de una sola oración, y el modelo escribe la letra: *"A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."* ([ronda 3](/docs/articles/ai-music-flagships-compared#round-3-pop-duet)) ACE Music v1 — "Three Dot Bubbles" · 0:41 · generada en 54 s <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Are You Still Awake?" · 3:05 · generada en 88 s <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "You Go First" · 1:59 · generada en 74 s <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Nuestra propia letra y una consigna de estilo deep house a 121 BPM, en los cinco modelos ([ronda 5](/docs/articles/ai-music-flagships-compared#round-5-deep-house)): ACE Music v1 — "Two shadows in a velvet" · 1:53 · generada en 52 s <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Low Light" · 3:09 · generada en 101 s <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Velvet Room" · 2:26 · generada en 43 s <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> TemPolor v4.8 — "Low Light" · 1:28 · generada en 51 s <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-tempolor-v4.8.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music 3.0 — "Low Light" · 2:47 · generada en 135 s <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Un dúo de voz masculina y femenina sobre jazzy house, con el papel de cada voz escrito en la letra ([ronda 6](/docs/articles/ai-music-flagships-compared#round-6-jazzy-house-duet)): Mureka V9.5 — "Blue Hour" · 3:12 · generada en 70 s <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Blue Hour" · 2:34 · generada en 58 s <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Una tercera canción de ACE Music v1, escrita a partir de la foto de una mascota robot que baila, suena junto con la foto en un [YouTube Short](https://youtube.com/shorts/z_aOmILvIng). Hay más, cada una con la solicitud que la generó, en los [ejemplos de nuestro tutorial de la ACE Music API](/docs/articles/ace-music-api-tutorial#examples). El corte de escucha de 15 minutos en YouTube reproduce los 30 segundos más fuertes de las 30 pistas, cinco modelos con seis consignas y ACE Music v1 incluido, con el volumen igualado y el precio por canción de cada servicio a noviembre de 2026. La comparación completa de precios está en [Precio por canción](#price-per-song). <div style="max-width:720px"> <div style="position:relative;width:100%;padding-top:56.25%;border-radius:8px;overflow:hidden"> <iframe src="https://www.youtube.com/embed/MSUGckk4JqU" title="Five AI music APIs on the same six briefs" style="position:absolute;top:0;left:0;width:100%;height:100%;border:0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen loading="lazy"></iframe> </div> </div> ### Manos a la obra Conecta tu cuenta con [Configurar ACE Music](/docs/start-here/setup-acemusic), [Configurar Mureka](/docs/start-here/setup-mureka), [Configurar Flow Music](/docs/start-here/setup-flowmusic), [Configurar TemPolor](/docs/start-here/setup-tempolor) o [Configurar MiniMax](/docs/start-here/setup-minimax), y luego crea una canción con [ACE Music POST music](/docs/api-acemusic-v1/post-acemusic-music), [Mureka POST music/create](/docs/api-mureka-v1/post-mureka-music-create), [Flow Music POST music](/docs/api-flowmusic-v1/post-flowmusic-music), [TemPolor POST music/song](/docs/api-tempolor-v1/post-tempolor-music-song) o [MiniMax POST music/create](/docs/api-minimax-v1/post-minimax-music-create). Cada página tiene código listo para ejecutar, y los tutoriales de [ACE Music](/docs/articles/ace-music-api-tutorial), [Mureka](/docs/articles/mureka-bash) y [Flow Music](/docs/articles/flowmusic-bash) te guían paso a paso por tu primera canción. [Ejemplos en GitHub: useapi/acemusic-api](https://github.com/useapi/acemusic-api), [useapi/mureka-api](https://github.com/useapi/mureka-api) y [useapi/flowmusic-api](https://github.com/useapi/flowmusic-api) generación de canciones en Node.js, además de Python para ACE Music [Servidor MCP de ACE Music](/docs/api-acemusic-v1/mcp) (15 herramientas), [servidor MCP de Mureka](/docs/api-mureka-v1/mcp) (40 herramientas) y [servidor MCP de Flow Music](/docs/api-flowmusic-v1/mcp) (18 herramientas) canciones, stems y ediciones desde Claude Code, Cursor, VS Code y otros clientes MCP ## Preguntas ### ¿Existe una alternativa a la API de Suno? Con useapi.net, sí: ACE Music v1, número 1 del [ranking de música vocal de Artificial Analysis](https://artificialanalysis.ai/music/leaderboard/vocals) por delante de Suno v6, además de Mureka V9.5, Lyria 3.5 de Google, TemPolor v4.8 y MiniMax Music 3.0, crean canciones con voz por REST, a partir de un prompt o de tu propia letra. La API para desarrolladores de Suno es una beta para socios seleccionados (a noviembre de 2026). ### ¿Cuánto cuesta una canción con IA mediante una API? Con useapi.net, una canción de ACE Music v1 cuesta unos US$0,013 en ACE Music Artist con pago anual, y una canción de ACE-Step v1.5 XL no cuesta nada, mientras que la API de terceros de acestep.io cobra unos US$0,14. Una canción de MiniMax Music 3.0 cuesta alrededor de US$0,01 en MiniMax Audio Pro, frente a US$0,15 en la API de MiniMax, y una canción de Lyria 3.5 unos US$0,011 en Flow Music Member, frente a US$0,08 en la Gemini API de Google (a noviembre de 2026). Consulta [Precio por canción](#price-per-song). ### ¿Una API de música con IA puede cantar con mi propia voz? Con useapi.net, sí. Mureka convierte unos 30 segundos de tu canto en un [personaje](/docs/api-mureka-v1/post-mureka-music-characters) reutilizable sin costo en Mureka Premier, mientras que la API oficial de Mureka cobra US$5 por voz (a noviembre de 2026). TemPolor clona una voz a partir de una muestra que subes con [POST music/cloned-voices](/docs/api-tempolor-v1/post-tempolor-music-cloned-voices) y canta cualquier canción con ella, a partir de un prompt o de tu propia letra. ### ¿Puedo obtener stems y partituras de una API de música con IA? Con useapi.net, una canción de Mureka se separa en hasta 12 stems más MIDI en Mureka Premier por alrededor de una quinta parte de los US$0,70 que cobra la API oficial de Mureka, y se convierte en partitura por US$0,02 o menos, frente a US$0,20 (a noviembre de 2026). ACE Music exporta stems, MIDI y MusicXML en Creator y Artist, cada canción de TemPolor se descarga como un ZIP de stems, y Flow Music separa una canción de Lyria en batería, bajo, voz y otros. --- Los precios de este artículo se consultaron en noviembre de 2026, y estos servicios cambian sus planes y tarifas sin previo aviso, así que revisa el precio actual antes de comprometer un gasto. ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/suno-api-alternative-id === Document URL: https://useapi.net/docs/articles/suno-api-alternative-id --- layout: default translation_key: suno-api-alternative lang: id title: "Alternatif API Suno: ACE Music, Mureka, Lyria 3.5, TemPolor, dan MiniMax" seo_title: "Alternatif API Suno: ACE Music, Mureka, Lyria, TemPolor, MiniMax" description: "Alternatif API Suno lewat useapi.net: ACE Music v1, #1 di papan peringkat vokal Artificial Analysis di atas Suno v6, plus Mureka V9.5, Lyria 3.5, TemPolor, dan MiniMax, sekitar 1 sampai 2 sen per lagu." keywords: [Suno API alternative, Suno alternative API, ACE Music API, ACE Music v1 API, ACE-Step API, AI song generator API, AI song API with vocals, AI music API, AI music API pricing, song generation API, text to song API, Mureka API, Mureka V9.5 API, Lyria 3.5 API, Flow Music API, Lyria API pricing, TemPolor API, TemPolor v4.8 API, MiniMax Music API, MiniMax Music 3.0 API, MiniMax music API pricing, alternatif API Suno, alternatif Suno, API Suno, API musik AI, API pembuat lagu AI, API lagu AI dengan vokal, harga API musik AI, membuat lagu AI, API ACE Music, API Mureka, API Lyria, tutorial bahasa Indonesia] image: /assets/images/articles/ai-music-flagships-compared.jpg video: name: "Lima API musik AI dengan enam brief yang sama" description: "ACE Music v1, TemPolor v4.8 dan i4, MiniMax Music-3.0, Google Lyria 3.5, dan Mureka V9.5 dengan enam brief yang identik — 30 detik paling keras dari setiap trek, dengan loudness yang disamakan, beserta prompt, harga, dan waktu pembuatan di layar." embed: https://www.youtube.com/embed/MSUGckk4JqU thumbnail: https://i.ytimg.com/vi/MSUGckk4JqU/maxresdefault.jpg date: 2026-11-14 duration: PT15M width: 1920 height: 1080 parent: Articles nav_exclude: true date: 2026-10-20 last_modified: 2026-11-18 nav_order: 906 --- ## Alternatif API Suno: ACE Music, Mureka, Lyria 3.5, TemPolor, dan MiniMax {: .no_toc #suno-api-alternative-ace-music-mureka-lyria-35-tempolor-and-minimax } 7 menit baca • 20 Oktober 2026 (18 November 2026) ## Daftar isi {: .no_toc .text-delta #table-of-contents } ### Pendahuluan Lewat useapi.net, ACE Music v1, yang menempati peringkat #1 di [papan peringkat musik vokal Artificial Analysis](https://artificialanalysis.ai/music/leaderboard/vocals) di atas Suno v6, membuat lagu utuh lewat REST memakai langganan [ACE Music](https://acemusic.ai/pricing/) Anda. Empat model lagu bervokal lainnya berjalan dengan cara yang sama: Mureka V9.5 dan Lyria 3.5 dari Google, keduanya di enam besar papan peringkat itu, TemPolor v4.8, dan MiniMax Music 3.0, memakai langganan situs [Mureka](https://www.mureka.ai/subscribe), [Flow Music](https://www.flowmusic.app/pricing), [TemPolor](https://www.tempolor.com/pricing), atau [MiniMax Audio](https://www.minimax.io/audio/subscribe) Anda. API developer milik Suno sendiri masih beta untuk mitra terpilih, tanpa dokumentasi publik maupun daftar harga (per November 2026). useapi.net adalah layanan [pihak ketiga](/docs/legal#affiliation--third-party-services) dan tidak berafiliasi dengan Suno, Timedomain, Kunlun Tech, Google, Qustar Technology, maupun MiniMax. ### Harga per lagu Biaya satu lagu bervokal di API resmi setiap pembuatnya ([Mureka](https://platform.mureka.ai/pricing), [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) milik Google, [TemPolor](https://platform.tempolor.com/docs/6665893m0), [MiniMax](https://platform.minimax.io/docs/pricing/overview#about-music-models) yang tertutup untuk pengguna baru sejak 20 Agustus 2026) dan di setiap langganan situsnya (November 2026). Setiap langganan memberi sejumlah kredit per bulan, dan setiap lagu memakai jumlah kredit yang tetap, jadi satu lagu berharga sebesar bagiannya dari langganan itu. | Model | API resmi | Langganan bulanan situs | Harga per lagu | |---|---|---|---| | ACE Music v1 | — | ACE Music Creator $9,90 (1.000 cr/bln) | 2¢ / 2 cr (500 lagu/bln) | | ACE Music v1 | — | ACE Music Artist $29 (2.500 cr/bln) | 2,3¢ / 2 cr (1.250 lagu/bln) | | ACE-Step v1.5 XL (10 sampai 240 s, hanya MP3) | — (open source) | Paket ACE Music apa pun (termasuk paket Free) | $0 / 0 cr (tanpa kredit) | | Mureka V9.5 | 15¢ (prabayar mulai $1.000) | Mureka Pro $10 (5.000 cr/bln) | 2,4¢ / 12 cr (416 lagu/bln) | | Mureka V9.5 | 15¢ (prabayar mulai $1.000) | Mureka Premier $30 (20.000 cr/bln) | 1,8¢ / 12 cr (1.666 lagu/bln) | | Lyria 3.5 | 8¢ (per lagu) | Flow Music Starter $8 (3.000 cr/bln) | 1,3¢ / 5 cr (600 lagu/bln) | | Lyria 3.5 | 8¢ (per lagu) | Flow Music Member $64 (30.000 cr/bln) | 1,1¢ / 5 cr (6.000 lagu/bln) | | TemPolor v4.8 | 4¢ (per panggilan, prabayar mulai $100) | TemPolor Ultra $29,99 | $0 / 0 cr (tanpa biaya per lagu) | | MiniMax Music 3.0 | 15¢ (tertutup untuk pengguna baru sejak 20 Agustus 2026) | MiniMax Audio Pro $99 (3.000.000 cr/bln) | 1¢ / 300 cr (10.000 lagu/bln) | - Jika ditagih tahunan, ACE Music Artist berharga $16,58 per bulan, sehingga satu lagu ACE Music v1 menjadi sekitar 1,3¢. 20 kredit harian paket Free membuat sekitar 10 lagu per hari untuk penggunaan pribadi, dan hak komersial tersedia di Creator dan Artist. - [ACE-Step](https://ace-step.github.io) v1.5 XL adalah model open source dari ACE Studio dan StepFun, dengan tempo (`bpm`), `key`, dan `timeSignature` yang bisa diatur. Model ini tidak memakai kredit di paket ACE Music mana pun, termasuk paket Free, sementara acestep.io yang merupakan pihak ketiga menagih sekitar 14¢ per lagu lewat API yang butuh paket Studio seharga $49 per bulan. - Jika model yang menulis lirik dari sebuah prompt, API Mureka menagih 50¢ alih-alih 15¢, dan API MiniMax serta TemPolor menambahkan 1¢, sementara lewat useapi.net harga satu lagu tetap sama. - Kredit API TemPolor berharga sama di setiap ukuran paket, jadi volume tidak pernah menurunkan harganya. - Jika ditagih tahunan, Flow Music Member berharga $48 per bulan, sehingga satu lagu Lyria menjadi sekitar 0,8¢. - Langganan Google AI sudah termasuk paket Flow Music, dengan kredit yang terpisah dari kredit Google AI: Starter di [Google AI Plus](https://support.google.com/googleone/answer/16882689?hl=id), Plus di [Google AI Pro](https://support.google.com/googleone/answer/14534406?hl=id), dan Member di [Google AI Ultra](https://support.google.com/googleone/answer/16286513?hl=id). - Jika Anda punya lebih dari satu langganan, satu token useapi.net bekerja dengan semuanya dan membagi lagu Anda ke semua langganan itu secara otomatis. ### Kemampuan masing-masing model - ACE Music v1, lewat [ACE Music API](/docs/api-acemusic-v1): dua lagu per request dari sebuah prompt atau dari gaya dan lirik Anda sendiri, dengan vokal atau instrumental, berdurasi 30 detik sampai 10 menit. ACE Music v1.1 Preview membuat [cover dan mashup](/docs/api-acemusic-v1/post-acemusic-music#modes) yang mengikuti melodi sebuah lagu, lagu dan gambar yang Anda [upload](/docs/api-acemusic-v1/post-acemusic-files) mengarahkan lagu baru, dan di Creator dan Artist lagunya bisa dipisah menjadi [stem](/docs/api-acemusic-v1/post-acemusic-music-stems) dan [diunduh](/docs/api-acemusic-v1/get-acemusic-music-download) sebagai WAV, MIDI, atau MusicXML. ACE-Step v1.5 XL yang gratis menambahkan remix, edit, serta tempo, kunci nada, dan birama yang bisa diatur. Setiap akun menjalankan hingga 4 request sekaligus. - Mureka V9.5, lewat [Mureka API](/docs/api-mureka-v1): dua lagu per panggilan, berdurasi hingga 5 menit, dari prompt satu baris atau dari lirik Anda plus sebuah gaya. Di Mureka Premier, model ini bernyanyi dengan suara Anda sendiri lewat [character](/docs/api-mureka-v1/post-mureka-music-characters) yang bisa dipakai ulang, dan memisahkan lagu menjadi [stem](/docs/api-mureka-v1/post-mureka-music-stems) plus MIDI. Model ini juga menulis [partitur](/docs/articles/mureka-sheet-music) sebagai MusicXML dan PDF, [me-remix](/docs/api-mureka-v1/post-mureka-music-remix) lagu ke gaya baru, memperpanjangnya, dan mengedit bagian-bagiannya, dengan hingga 10 generate sekaligus per akun. - Lyria 3.5, lewat [Flow Music API](/docs/api-flowmusic-v1), yang menjalankan [Google Flow Music](https://www.flowmusic.app): sepasang A/B per panggilan, sebagai WAV, mp3, atau m4a. [POST music/edit](/docs/api-flowmusic-v1/post-flowmusic-music-edit) membuat cover, remix lirik, perpanjangan hingga 300 detik, penggantian bagian, efek audio, dan pemisahan empat stem dari paket yang sama. Kirim `model="lyria-3.5"`, karena API ini tetap memakai `lyria-3-pro` sebagai default. Paket berbayar menjalankan 8 sampai 16 generate sekaligus. - TemPolor v4.8, lewat [TemPolor API](/docs/api-tempolor-v1): lagu hingga 5 menit dalam lebih dari 30 bahasa dari sebuah prompt atau lirik Anda sendiri, dinyanyikan oleh [suara kloning](/docs/api-tempolor-v1/post-tempolor-music-cloned-voices) atau salah satu suara artisnya, atau dibangun di atas [file MIDI](/docs/api-tempolor-v1/post-tempolor-music-midi) yang Anda upload. Setiap lagu bisa [diunduh](/docs/api-tempolor-v1/get-tempolor-music-download-job_id) sebagai mp3, wav, atau ZIP stem, [music/stems-splitter](/docs/api-tempolor-v1/post-tempolor-music-stems-splitter) memisahkan audio Anda sendiri, dan [music/instrumental](/docs/api-tempolor-v1/post-tempolor-music-instrumental) menjalankan model i4 untuk trek tanpa vokal. Hingga 10 generate berjalan sekaligus. - MiniMax Music 3.0, lewat [MiniMax API](/docs/api-minimax-v1/post-minimax-music-create): satu sampai tiga lagu per panggilan dari prompt gaya dan lirik Anda, atau lirik yang ditulisnya sendiri, plus instrumental dan cover dari sebuah [trek referensi](/docs/api-minimax-v1/post-minimax-music-reference). Lagu dikembalikan sebagai MP3 256 kbps, dan dengan `stream: true` audionya diputar selagi dirender. ### Dengarkan dulu Setiap trek di bawah ini utuh dan tidak diedit, dan halaman asal masing-masing menunjukkan panggilan API di baliknya. Semuanya berasal dari [perbandingan model-model ini dengan enam brief yang sama](/docs/articles/ai-music-flagships-compared), tempat ACE Music v1 bergabung dengan empat model lainnya pada 14 November 2026. Trek Lyria ditranskode dari WAV keluaran API ke MP3 agar bisa diputar di browser, dan setiap trek ACE Music v1 adalah lagu pertama dari dua lagu yang dibuat ACE Music per request. Prompt satu kalimat, model menulis liriknya: *"A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."* ([ronde 3](/docs/articles/ai-music-flagships-compared#round-3-pop-duet)) ACE Music v1 — "Three Dot Bubbles" · 0:41 · dibuat dalam 54 s <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Are You Still Awake?" · 3:05 · dibuat dalam 88 s <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "You Go First" · 1:59 · dibuat dalam 74 s <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lirik kami sendiri dan brief gaya deep house di 121 BPM, di kelima model ([ronde 5](/docs/articles/ai-music-flagships-compared#round-5-deep-house)): ACE Music v1 — "Two shadows in a velvet" · 1:53 · dibuat dalam 52 s <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Low Light" · 3:09 · dibuat dalam 101 s <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Velvet Room" · 2:26 · dibuat dalam 43 s <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> TemPolor v4.8 — "Low Light" · 1:28 · dibuat dalam 51 s <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-tempolor-v4.8.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music 3.0 — "Low Light" · 2:47 · dibuat dalam 135 s <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Duet pria dan wanita di atas jazzy house, dengan peran suara yang ditulis di dalam liriknya ([ronde 6](/docs/articles/ai-music-flagships-compared#round-6-jazzy-house-duet)): Mureka V9.5 — "Blue Hour" · 3:12 · dibuat dalam 70 s <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Blue Hour" · 2:34 · dibuat dalam 58 s <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lagu ACE Music v1 ketiga, yang ditulis dari foto maskot robot yang sedang menari, diputar bersama fotonya di sebuah [YouTube Short](https://youtube.com/shorts/z_aOmILvIng). Lagu lainnya, masing-masing dengan request yang membuatnya, ada di [contoh tutorial ACE Music API kami](/docs/articles/ace-music-api-tutorial#examples). Potongan dengar 15 menit di YouTube memutar 30 detik paling keras dari ke-30 trek, lima model dengan enam brief termasuk ACE Music v1, dengan loudness yang disamakan, beserta harga per lagu setiap layanan per November 2026. Perbandingan harga lengkapnya ada di [Harga per lagu](#price-per-song). <div style="max-width:720px"> <div style="position:relative;width:100%;padding-top:56.25%;border-radius:8px;overflow:hidden"> <iframe src="https://www.youtube.com/embed/MSUGckk4JqU" title="Five AI music APIs on the same six briefs" style="position:absolute;top:0;left:0;width:100%;height:100%;border:0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen loading="lazy"></iframe> </div> </div> ### Mulai membangun Hubungkan akun Anda dengan [Setup ACE Music](/docs/start-here/setup-acemusic), [Setup Mureka](/docs/start-here/setup-mureka), [Setup Flow Music](/docs/start-here/setup-flowmusic), [Setup TemPolor](/docs/start-here/setup-tempolor), atau [Setup MiniMax](/docs/start-here/setup-minimax), lalu buat lagu dengan [ACE Music POST music](/docs/api-acemusic-v1/post-acemusic-music), [Mureka POST music/create](/docs/api-mureka-v1/post-mureka-music-create), [Flow Music POST music](/docs/api-flowmusic-v1/post-flowmusic-music), [TemPolor POST music/song](/docs/api-tempolor-v1/post-tempolor-music-song), atau [MiniMax POST music/create](/docs/api-minimax-v1/post-minimax-music-create). Setiap halaman punya kode yang siap dijalankan, dan tutorial [ACE Music](/docs/articles/ace-music-api-tutorial), [Mureka](/docs/articles/mureka-bash), dan [Flow Music](/docs/articles/flowmusic-bash) memandu Anda membuat lagu pertama. [Contoh GitHub: useapi/acemusic-api](https://github.com/useapi/acemusic-api), [useapi/mureka-api](https://github.com/useapi/mureka-api), dan [useapi/flowmusic-api](https://github.com/useapi/flowmusic-api) pembuatan lagu dengan Node.js, plus Python untuk ACE Music [MCP server ACE Music](/docs/api-acemusic-v1/mcp) (15 tool), [MCP server Mureka](/docs/api-mureka-v1/mcp) (40 tool), dan [MCP server Flow Music](/docs/api-flowmusic-v1/mcp) (18 tool) lagu, stem, dan edit dari Claude Code, Cursor, VS Code, dan klien MCP lainnya ## Pertanyaan ### Apakah ada alternatif untuk API Suno? Lewat useapi.net, ada: ACE Music v1, #1 di [papan peringkat musik vokal Artificial Analysis](https://artificialanalysis.ai/music/leaderboard/vocals) di atas Suno v6, plus Mureka V9.5, Lyria 3.5 dari Google, TemPolor v4.8, dan MiniMax Music 3.0 membuat lagu bervokal lewat REST, dari sebuah prompt atau dari lirik Anda sendiri. API developer Suno masih beta untuk mitra terpilih (per November 2026). ### Berapa biaya satu lagu AI lewat API? Lewat useapi.net, satu lagu ACE Music v1 berharga sekitar 1,3 sen dolar AS di ACE Music Artist yang ditagih tahunan, dan satu lagu ACE-Step v1.5 XL gratis, sementara API pihak ketiga acestep.io menagih sekitar 14 sen. Satu lagu MiniMax Music 3.0 berharga sekitar 1 sen di MiniMax Audio Pro, dibanding 15 sen di API MiniMax, dan satu lagu Lyria 3.5 sekitar 1,1 sen di Flow Music Member, dibanding 8 sen di Gemini API milik Google (per November 2026). Lihat [Harga per lagu](#price-per-song). ### Bisakah API musik AI bernyanyi dengan suara saya sendiri? Lewat useapi.net, bisa. Mureka mengubah sekitar 30 detik nyanyian Anda menjadi [character](/docs/api-mureka-v1/post-mureka-music-characters) yang bisa dipakai ulang tanpa biaya di Mureka Premier, sementara API resmi Mureka menagih $5 per suara (per November 2026). TemPolor mengkloning suara dari sampel yang Anda upload dengan [POST music/cloned-voices](/docs/api-tempolor-v1/post-tempolor-music-cloned-voices) dan menyanyikan lagu apa pun dengan suara itu, dari sebuah prompt atau dari lirik Anda sendiri. ### Bisakah saya mendapatkan stem dan partitur dari API musik AI? Lewat useapi.net, satu lagu Mureka bisa dipisah menjadi hingga 12 stem plus MIDI di Mureka Premier dengan biaya sekitar seperlima dari 70 sen yang ditagih API resmi Mureka, dan dijadikan partitur seharga 2 sen atau kurang, dibanding 20 sen (per November 2026). ACE Music mengekspor stem, MIDI, dan MusicXML di Creator dan Artist, setiap lagu TemPolor bisa diunduh sebagai ZIP stem, dan Flow Music memisahkan lagu Lyria menjadi drum, bass, vokal, dan lainnya. --- Harga di artikel ini dibaca pada November 2026, dan layanan-layanan ini mengubah paket dan tarifnya tanpa pemberitahuan, jadi periksa harga terbaru sebelum Anda mengeluarkan biaya. ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/suno-api-alternative-ja === Document URL: https://useapi.net/docs/articles/suno-api-alternative-ja --- layout: default lang: ja translation_key: suno-api-alternative title: "Suno API の代替:ACE Music、Mureka、Lyria 3.5、TemPolor、MiniMax" seo_title: "Suno API の代替:ACE Music、Mureka、Lyria、TemPolor、MiniMax" description: "useapi.net で使える Suno API の代替。Artificial Analysis のボーカル部門で Suno v6 を抑えて1位の ACE Music v1 に加え、Mureka V9.5、Lyria 3.5、TemPolor、MiniMax で、1曲約 $0.01〜0.02。" keywords: [Suno API alternative, Suno alternative API, ACE Music API, ACE Music v1 API, ACE-Step API, AI song generator API, AI song API with vocals, AI music API, AI music API pricing, song generation API, text to song API, Mureka API, Mureka V9.5 API, Lyria 3.5 API, Flow Music API, Lyria API pricing, TemPolor API, TemPolor v4.8 API, MiniMax Music API, MiniMax Music 3.0 API, MiniMax music API pricing, Suno API 代替, Suno API 料金, AI 作曲 API, 音楽生成 API, AI 音楽生成 API, 歌入り AI 作曲, 日本語] image: /assets/images/articles/ai-music-flagships-compared.jpg video: name: "同じ6つの課題で比べた5つの AI 音楽 API" description: "ACE Music v1、TemPolor v4.8 と i4、MiniMax Music-3.0、Google Lyria 3.5、Mureka V9.5 を同じ6つの課題で比較。各トラックの最も音の大きい30秒を音量をそろえて流し、プロンプト、料金、生成時間を画面に表示します。" embed: https://www.youtube.com/embed/MSUGckk4JqU thumbnail: https://i.ytimg.com/vi/MSUGckk4JqU/maxresdefault.jpg date: 2026-11-14 duration: PT15M width: 1920 height: 1080 parent: Articles nav_exclude: true date: 2026-10-20 last_modified: 2026-11-18 nav_order: 906 --- ## Suno API の代替:ACE Music、Mureka、Lyria 3.5、TemPolor、MiniMax {: .no_toc #suno-api-alternative-ace-music-mureka-lyria-35-tempolor-and-minimax } 7分で読めます • 2026年10月20日(2026年11月18日更新) ## 目次 {: .no_toc .text-delta #table-of-contents } ### はじめに useapi.net を使えば、[Artificial Analysis のボーカル音楽リーダーボード](https://artificialanalysis.ai/music/leaderboard/vocals)で Suno v6 を抑えて1位の ACE Music v1 で、お使いの [ACE Music](https://acemusic.ai/pricing/) のサブスクリプションを使って、REST から完成した曲を作れます。ボーカル入りの曲を作るほかの4つのモデルも同じように動きます。同じリーダーボードで上位6位に入る Mureka V9.5 と Google の Lyria 3.5、そして TemPolor v4.8 と MiniMax Music 3.0 で、それぞれ [Mureka](https://www.mureka.ai/subscribe)、[Flow Music](https://www.flowmusic.app/pricing)、[TemPolor](https://www.tempolor.com/pricing)、[MiniMax Audio](https://www.minimax.io/audio/subscribe) のウェブサイトのサブスクリプションを使います。Suno 自身の開発者向け API は一部のパートナー向けのベータ版で、公開のドキュメントも料金表もありません(2026年11月時点)。useapi.net は[サードパーティ](/docs/legal#affiliation--third-party-services)のサービスで、Suno、Timedomain、Kunlun Tech、Google、Qustar Technology、MiniMax とは提携していません。 ### 1曲の料金 ボーカル入りの曲1曲にかかる料金を、各メーカーの公式 API([Mureka](https://platform.mureka.ai/pricing)、Google の [Gemini API](https://ai.google.dev/gemini-api/docs/pricing)、[TemPolor](https://platform.tempolor.com/docs/6665893m0)、[MiniMax](https://platform.minimax.io/docs/pricing/overview#about-music-models)。MiniMax は2026年8月20日から新規ユーザーを受け付けていません)と、各ウェブサイトのサブスクリプションで比べました(2026年11月時点)。サブスクリプションには毎月決まった数のクレジットが付き、1曲ごとに決まった数のクレジットを使うので、1曲の料金はサブスクリプション料金のその曲の分の割合です。 | モデル | 公式 API | サイトの月額プラン | 1曲の料金 | |---|---|---|---| | ACE Music v1 | — | ACE Music Creator $9.90 (月1,000 cr) | $0.02 / 2 cr (月500曲) | | ACE Music v1 | — | ACE Music Artist $29 (月2,500 cr) | $0.023 / 2 cr (月1,250曲) | | ACE-Step v1.5 XL (10〜240秒、MP3 のみ) | — (オープンソース) | ACE Music の全プラン (Free プランを含む) | $0 / 0 cr (クレジット不要) | | Mureka V9.5 | $0.15 ($1,000 からの前払い) | Mureka Pro $10 (月5,000 cr) | $0.024 / 12 cr (月416曲) | | Mureka V9.5 | $0.15 ($1,000 からの前払い) | Mureka Premier $30 (月20,000 cr) | $0.018 / 12 cr (月1,666曲) | | Lyria 3.5 | $0.08 (1曲) | Flow Music Starter $8 (月3,000 cr) | $0.013 / 5 cr (月600曲) | | Lyria 3.5 | $0.08 (1曲) | Flow Music Member $64 (月30,000 cr) | $0.011 / 5 cr (月6,000曲) | | TemPolor v4.8 | $0.04 (1回、$100 からの前払い) | TemPolor Ultra $29.99 | $0 / 0 cr (曲ごとの課金なし) | | MiniMax Music 3.0 | $0.15 (2026年8月20日から新規受付停止) | MiniMax Audio Pro $99 (月3,000,000 cr) | $0.01 / 300 cr (月10,000曲) | - 年払いなら ACE Music Artist は月額 $16.58 で、ACE Music v1 の曲は1曲約 $0.013 になります。Free プランの1日20クレジットで、個人利用なら1日約10曲を作れます。商用利用の権利は Creator と Artist に付きます。 - [ACE-Step](https://ace-step.github.io) v1.5 XL は ACE Studio と StepFun によるオープンソースのモデルで、テンポ(`bpm`)、`key`、`timeSignature` を指定できます。Free プランを含むどの ACE Music のプランでもクレジットを消費しません。一方、サードパーティの acestep.io は、月額 $49 の Studio プランが必要な API で1曲約 $0.14 を請求します。 - モデルがプロンプトから歌詞を書く場合、Mureka の API は $0.15 ではなく $0.50 を請求し、MiniMax と TemPolor の API は $0.01 を上乗せします。useapi.net では、どちらの場合も1曲の料金は変わりません。 - TemPolor の API クレジットはパッケージの大きさにかかわらず同じ単価なので、量を増やしても安くなりません。 - 年払いなら Flow Music Member は月額 $48 で、Lyria の曲は1曲約 $0.008 になります。 - Google AI のサブスクリプションには Flow Music のプランが含まれ、そのクレジットは Google AI のクレジットとは別です。[Google AI Plus](https://support.google.com/googleone/answer/16882689?hl=ja) には Starter、[Google AI Pro](https://support.google.com/googleone/answer/14534406?hl=ja) には Plus、[Google AI Ultra](https://support.google.com/googleone/answer/16286513?hl=ja) には Member が付きます。 - 複数のサブスクリプションがある場合も、useapi.net のトークン1つですべてを使え、曲は自動的に各サブスクリプションに振り分けられます。 ### 各モデルでできること - ACE Music v1([ACE Music API](/docs/api-acemusic-v1)):プロンプト、または自分で用意したスタイルと歌詞から、1リクエストで2曲を作ります。歌入りでもインストでも作れ、長さは30秒から10分です。ACE Music v1.1 Preview は、原曲のメロディに沿った[カバーやマッシュアップ](/docs/api-acemusic-v1/post-acemusic-music#modes)を作ります。[アップロードした](/docs/api-acemusic-v1/post-acemusic-files)曲や画像を新しい曲の手がかりにでき、Creator と Artist では曲を[ステム](/docs/api-acemusic-v1/post-acemusic-music-stems)に分け、WAV、MIDI、MusicXML で[ダウンロード](/docs/api-acemusic-v1/get-acemusic-music-download)できます。無料の ACE-Step v1.5 XL では、リミックス、編集、テンポ・キー・拍子の指定もできます。1アカウントで同時に4リクエストまで実行できます。 - Mureka V9.5([Mureka API](/docs/api-mureka-v1)):1行のプロンプト、または自作の歌詞とスタイルから、1回の呼び出しで最長5分の曲を2曲作ります。Mureka Premier では、再利用できる[キャラクター](/docs/api-mureka-v1/post-mureka-music-characters)を使ってあなた自身の声で歌わせたり、曲を[ステム](/docs/api-mureka-v1/post-mureka-music-stems)と MIDI に分けたりできます。ほかにも、[楽譜](/docs/articles/mureka-sheet-music)を MusicXML と PDF で書き出し、曲を新しいスタイルに[リミックス](/docs/api-mureka-v1/post-mureka-music-remix)し、延長やセクションの編集もでき、1アカウントで同時に10件まで生成できます。 - Lyria 3.5([Google Flow Music](https://www.flowmusic.app) を操作する [Flow Music API](/docs/api-flowmusic-v1)):1回の呼び出しで A/B の2曲を WAV、mp3、m4a で返します。[POST music/edit](/docs/api-flowmusic-v1/post-flowmusic-music-edit) では、同じプランでカバー、歌詞のリミックス、最長300秒の延長、セクションの差し替え、オーディオエフェクト、4ステムへの分離ができます。API のデフォルトは `lyria-3-pro` のままなので、`model="lyria-3.5"` を指定してください。有料プランでは同時に8〜16件を生成できます。 - TemPolor v4.8([TemPolor API](/docs/api-tempolor-v1)):プロンプトまたは自作の歌詞から、30以上の言語で最長5分の曲を作ります。歌うのは[クローンした声](/docs/api-tempolor-v1/post-tempolor-music-cloned-voices)か用意されたアーティストの声で、アップロードした [MIDI ファイル](/docs/api-tempolor-v1/post-tempolor-music-midi)をもとに作ることもできます。どの曲も mp3、wav、ステムの ZIP で[ダウンロード](/docs/api-tempolor-v1/get-tempolor-music-download-job_id)でき、[music/stems-splitter](/docs/api-tempolor-v1/post-tempolor-music-stems-splitter) は手持ちの音声を分離し、[music/instrumental](/docs/api-tempolor-v1/post-tempolor-music-instrumental) はボーカルなしのトラック向けに i4 モデルを実行します。同時に10件まで生成できます。 - MiniMax Music 3.0([MiniMax API](/docs/api-minimax-v1/post-minimax-music-create)):スタイルのプロンプトと自作の歌詞、またはモデル自身が書いた歌詞から、1回の呼び出しで1〜3曲を作ります。インストや、[参照トラック](/docs/api-minimax-v1/post-minimax-music-reference)のカバーも作れます。曲は 256 kbps の MP3 で返り、`stream: true` を指定すると生成中から音声を再生できます。 ### まず聴いてみる 以下のトラックはすべて完全版で編集もしておらず、それぞれの出典ページに、その曲を作った API 呼び出しを載せています。 すべて、[同じ6つの課題でこれらのモデルを比べた記事](/docs/articles/ai-music-flagships-compared)からのもので、ACE Music v1 は2026年11月14日にほかの4モデルに加わりました。Lyria のトラックは、ブラウザで再生できるよう API の WAV から MP3 に変換しています。ACE Music v1 のトラックは、ACE Music が1リクエストで作る2曲のうち1曲目です。 1文のプロンプトだけで、歌詞はモデルが書きます。*"A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."*([ラウンド3](/docs/articles/ai-music-flagships-compared#round-3-pop-duet)) ACE Music v1 —「Three Dot Bubbles」· 0:41 · 生成 54秒 <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 —「Are You Still Awake?」· 3:05 · 生成 88秒 <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 —「You Go First」· 1:59 · 生成 74秒 <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> 自作の歌詞と、121 BPM のディープハウスのスタイル指定を、5つのモデルすべてに渡しました([ラウンド5](/docs/articles/ai-music-flagships-compared#round-5-deep-house))。 ACE Music v1 —「Two shadows in a velvet」· 1:53 · 生成 52秒 <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 —「Low Light」· 3:09 · 生成 101秒 <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 —「Velvet Room」· 2:26 · 生成 43秒 <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> TemPolor v4.8 —「Low Light」· 1:28 · 生成 51秒 <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-tempolor-v4.8.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music 3.0 —「Low Light」· 2:47 · 生成 135秒 <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ジャジーなハウスに乗せた男女のデュエットで、どちらが歌うかを歌詞に書き込みました([ラウンド6](/docs/articles/ai-music-flagships-compared#round-6-jazzy-house-duet))。 Mureka V9.5 —「Blue Hour」· 3:12 · 生成 70秒 <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 —「Blue Hour」· 2:34 · 生成 58秒 <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ACE Music v1 の3曲目は、踊るロボットのマスコットの写真から作った曲で、[YouTube ショート](https://youtube.com/shorts/z_aOmILvIng)で写真と一緒に流れます。ほかの曲も、それぞれを作ったリクエストとともに [ACE Music API チュートリアルの例](/docs/articles/ace-music-api-tutorial#examples)に載せています。 YouTube の15分の試聴版では、全30トラックについて、音量をそろえたうえで最も音の大きい30秒ずつを流しています。ACE Music v1 を含む5つのモデルを6つの課題で比べ、各サービスの1曲あたりの料金を2026年11月時点で表示しています。料金の比較の全体は[1曲の料金](#price-per-song)にあります。 <div style="max-width:720px"> <div style="position:relative;width:100%;padding-top:56.25%;border-radius:8px;overflow:hidden"> <iframe src="https://www.youtube.com/embed/MSUGckk4JqU" title="Five AI music APIs on the same six briefs" style="position:absolute;top:0;left:0;width:100%;height:100%;border:0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen loading="lazy"></iframe> </div> </div> ### 作ってみる [ACE Music のセットアップ](/docs/start-here/setup-acemusic)、[Mureka のセットアップ](/docs/start-here/setup-mureka)、[Flow Music のセットアップ](/docs/start-here/setup-flowmusic)、[TemPolor のセットアップ](/docs/start-here/setup-tempolor)、[MiniMax のセットアップ](/docs/start-here/setup-minimax)のいずれかでアカウントを接続し、[ACE Music POST music](/docs/api-acemusic-v1/post-acemusic-music)、[Mureka POST music/create](/docs/api-mureka-v1/post-mureka-music-create)、[Flow Music POST music](/docs/api-flowmusic-v1/post-flowmusic-music)、[TemPolor POST music/song](/docs/api-tempolor-v1/post-tempolor-music-song)、[MiniMax POST music/create](/docs/api-minimax-v1/post-minimax-music-create) で曲を作ります。各ページにすぐ実行できるコードがあり、[ACE Music](/docs/articles/ace-music-api-tutorial)、[Mureka](/docs/articles/mureka-bash)、[Flow Music](/docs/articles/flowmusic-bash) のチュートリアルでは、最初の1曲を作るまでを順を追って説明しています。 [GitHub の例:useapi/acemusic-api](https://github.com/useapi/acemusic-api)、[useapi/mureka-api](https://github.com/useapi/mureka-api)、[useapi/flowmusic-api](https://github.com/useapi/flowmusic-api) Node.js による曲の生成、ACE Music は Python も [ACE Music MCP サーバー](/docs/api-acemusic-v1/mcp)(15ツール)、[Mureka MCP サーバー](/docs/api-mureka-v1/mcp)(40ツール)、[Flow Music MCP サーバー](/docs/api-flowmusic-v1/mcp)(18ツール) Claude Code、Cursor、VS Code などの MCP クライアントから、曲、ステム、編集 ## よくある質問 ### Suno API の代わりになるものはありますか? useapi.net を使えば、あります。[Artificial Analysis のボーカル音楽リーダーボード](https://artificialanalysis.ai/music/leaderboard/vocals)で Suno v6 を抑えて1位の ACE Music v1 に加え、Mureka V9.5、Google の Lyria 3.5、TemPolor v4.8、MiniMax Music 3.0 が、プロンプトや自作の歌詞から REST でボーカル入りの曲を作ります。Suno の開発者向け API は一部のパートナー向けのベータ版です(2026年11月時点)。 ### API で AI の曲を作るといくらかかりますか? useapi.net なら、ACE Music v1 の曲は ACE Music Artist の年払いで1曲約 $0.013、ACE-Step v1.5 XL の曲は無料です。サードパーティの acestep.io の API では1曲約 $0.14 かかります。MiniMax Music 3.0 の曲は MiniMax Audio Pro で約 $0.01(MiniMax の API では $0.15)、Lyria 3.5 の曲は Flow Music Member で約 $0.011(Google の Gemini API では $0.08)です(2026年11月時点)。[1曲の料金](#price-per-song)をご覧ください。 ### AI 音楽 API で自分の声で歌わせることはできますか? useapi.net を使えば、できます。Mureka は、約30秒のあなたの歌声を、再利用できる[キャラクター](/docs/api-mureka-v1/post-mureka-music-characters)に変えます。Mureka Premier なら無料で、Mureka の公式 API では1声 $5 かかります(2026年11月時点)。TemPolor は [POST music/cloned-voices](/docs/api-tempolor-v1/post-tempolor-music-cloned-voices) でアップロードしたサンプルから声をクローンし、プロンプトからでも自作の歌詞からでも、どんな曲もその声で歌います。 ### AI 音楽 API でステムや楽譜を取得できますか? useapi.net なら、Mureka の曲は Mureka Premier で最大12のステムと MIDI に分けられ、料金は Mureka の公式 API の $0.70 の約5分の1です。楽譜にするのも、公式の $0.20 に対して $0.02 以下です(2026年11月時点)。ACE Music は Creator と Artist でステム、MIDI、MusicXML を書き出し、TemPolor の曲はどれもステムの ZIP でダウンロードでき、Flow Music は Lyria の曲をドラム、ベース、ボーカル、その他に分けます。 --- この記事の料金は2026年11月に確認したものです。これらのサービスは予告なくプランや料金を変更するため、費用をかける前に最新の料金を確認してください。 ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/suno-api-alternative-pt === Document URL: https://useapi.net/docs/articles/suno-api-alternative-pt --- layout: default title: "Alternativa à API do Suno: ACE Music, Mureka, Lyria 3.5, TemPolor e MiniMax" seo_title: "Alternativa à API do Suno: ACE Music, Mureka, Lyria, TemPolor" description: "Alternativa à API do Suno pela useapi.net: o ACE Music v1, 1º lugar no ranking vocal da Artificial Analysis à frente do Suno v6, além de Mureka V9.5, Lyria 3.5, TemPolor e MiniMax, por cerca de $0,01 a $0,02 por música." keywords: [alternativa à API do Suno, alternativa ao Suno, API alternativa ao Suno, Suno API alternative, Suno alternative API, API do ACE Music, ACE Music API, ACE Music v1 API, ACE-Step API, API de música com IA, API de música com IA com vocais, gerador de músicas com IA, AI song generator API, AI music API, preço de API de música com IA, API de geração de músicas, API de texto para música, text to song API, Mureka API, Mureka V9.5 API, Lyria 3.5 API, Flow Music API, preço da API do Lyria, TemPolor API, TemPolor v4.8 API, MiniMax Music API, MiniMax Music 3.0 API, preço da API do MiniMax Music] image: /assets/images/articles/ai-music-flagships-compared.jpg video: name: "Cinco APIs de música com IA nos mesmos seis briefings" description: "ACE Music v1, TemPolor v4.8 e i4, MiniMax Music-3.0, Google Lyria 3.5 e Mureka V9.5 nos mesmos seis briefings: os 30 segundos mais altos de cada faixa, com volume equalizado, e o prompt, o preço e o tempo de geração na tela." embed: https://www.youtube.com/embed/MSUGckk4JqU thumbnail: https://i.ytimg.com/vi/MSUGckk4JqU/maxresdefault.jpg date: 2026-11-14 duration: PT15M width: 1920 height: 1080 parent: Articles nav_exclude: true lang: pt-BR translation_key: suno-api-alternative date: 2026-10-20 last_modified: 2026-11-18 nav_order: 906 --- ## Alternativa à API do Suno: ACE Music, Mureka, Lyria 3.5, TemPolor e MiniMax {: .no_toc #suno-api-alternative-ace-music-mureka-lyria-35-tempolor-and-minimax } 7 min de leitura • 20 de outubro de 2026 (18 de novembro de 2026) ## Sumário {: .no_toc .text-delta #table-of-contents } ### Introdução Pela useapi.net, o ACE Music v1, que está em 1º lugar no [ranking de música vocal da Artificial Analysis](https://artificialanalysis.ai/music/leaderboard/vocals), à frente do Suno v6, gera músicas completas via REST na sua assinatura do [ACE Music](https://acemusic.ai/pricing/). Mais quatro modelos de música com vocais funcionam do mesmo jeito: o Mureka V9.5 e o Lyria 3.5 do Google, ambos entre os seis primeiros desse ranking, o TemPolor v4.8 e o MiniMax Music 3.0, na sua assinatura do site do [Mureka](https://www.mureka.ai/subscribe), do [Flow Music](https://www.flowmusic.app/pricing), do [TemPolor](https://www.tempolor.com/pricing) ou do [MiniMax Audio](https://www.minimax.io/audio/subscribe). A API para desenvolvedores do próprio Suno é um beta para parceiros selecionados, sem documentação pública nem tabela de preços (em novembro de 2026). A useapi.net é um serviço de [terceiros](/docs/legal#affiliation--third-party-services), sem afiliação com Suno, Timedomain, Kunlun Tech, Google, Qustar Technology ou MiniMax. ### Preço por música Quanto custa uma música com vocais na API oficial de cada fabricante ([Mureka](https://platform.mureka.ai/pricing), a [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) do Google, [TemPolor](https://platform.tempolor.com/docs/6665893m0), [MiniMax](https://platform.minimax.io/docs/pricing/overview#about-music-models), fechada a novos usuários desde 20 de agosto de 2026) e em cada assinatura do site (novembro de 2026). Cada assinatura traz um número mensal de créditos, e cada música usa um número fixo deles, então uma música custa a sua parte da assinatura. | Modelo | API oficial | Assinatura mensal do site | Preço por música | |---|---|---|---| | ACE Music v1 | — | ACE Music Creator $9,90 (1.000 cr/mês) | $0,020 / 2 cr (500 músicas/mês) | | ACE Music v1 | — | ACE Music Artist $29 (2.500 cr/mês) | $0,023 / 2 cr (1.250 músicas/mês) | | ACE-Step v1.5 XL (10 a 240 s, só MP3) | — (código aberto) | Qualquer plano do ACE Music (inclusive o plano Free) | $0 / 0 cr (sem créditos) | | Mureka V9.5 | $0,15 (pré-pago a partir de $1.000) | Mureka Pro $10 (5.000 cr/mês) | $0,024 / 12 cr (416 músicas/mês) | | Mureka V9.5 | $0,15 (pré-pago a partir de $1.000) | Mureka Premier $30 (20.000 cr/mês) | $0,018 / 12 cr (1.666 músicas/mês) | | Lyria 3.5 | $0,08 (por música) | Flow Music Starter $8 (3.000 cr/mês) | $0,013 / 5 cr (600 músicas/mês) | | Lyria 3.5 | $0,08 (por música) | Flow Music Member $64 (30.000 cr/mês) | $0,011 / 5 cr (6.000 músicas/mês) | | TemPolor v4.8 | $0,04 (por chamada, pré-pago a partir de $100) | TemPolor Ultra $29,99 | $0 / 0 cr (sem cobrança por música) | | MiniMax Music 3.0 | $0,15 (fechada a novos usuários desde 20/08/2026) | MiniMax Audio Pro $99 (3.000.000 cr/mês) | $0,010 / 300 cr (10.000 músicas/mês) | - Com cobrança anual, o ACE Music Artist sai por $16,58 por mês, o que leva uma música do ACE Music v1 a cerca de $0,013. Os 20 créditos diários do plano Free fazem cerca de 10 músicas por dia para uso pessoal, e os direitos comerciais vêm com o Creator e o Artist. - O [ACE-Step](https://ace-step.github.io) v1.5 XL é o modelo de código aberto da ACE Studio e da StepFun, com andamento (`bpm`), tom (`key`) e compasso (`timeSignature`) definidos. Ele não gasta créditos em nenhum plano do ACE Music, inclusive no Free, enquanto a acestep.io, de terceiros, cobra cerca de $0,14 por música por uma API que exige o plano Studio de $49 por mês. - Quando o modelo escreve a letra a partir de um prompt, a API do Mureka cobra $0,50 em vez de $0,15, e as do MiniMax e do TemPolor acrescentam $0,01, enquanto pela useapi.net uma música custa o mesmo nos dois casos. - Os créditos da API do TemPolor custam o mesmo em qualquer tamanho de pacote, então o volume nunca baixa o preço. - Com cobrança anual, o Flow Music Member sai por $48 por mês, o que leva uma música do Lyria a cerca de $0,008. - As assinaturas do Google AI incluem um plano do Flow Music, com créditos separados dos créditos do Google AI: Starter no [Google AI Plus](https://support.google.com/googleone/answer/16882689?hl=pt-BR), Plus no [Google AI Pro](https://support.google.com/googleone/answer/14534406?hl=pt-BR) e Member no [Google AI Ultra](https://support.google.com/googleone/answer/16286513?hl=pt-BR). - Com mais de uma assinatura, um único token da useapi.net funciona com todas e distribui as suas músicas entre elas automaticamente. ### O que cada um faz - ACE Music v1, pela [API do ACE Music](/docs/api-acemusic-v1): duas músicas por requisição a partir de um prompt ou do seu próprio estilo e letra, cantadas ou instrumentais, de 30 segundos a 10 minutos. O ACE Music v1.1 Preview faz [covers e mashups](/docs/api-acemusic-v1/post-acemusic-music#modes) que seguem a melodia de uma música, as músicas e imagens que você [envia](/docs/api-acemusic-v1/post-acemusic-files) guiam as novas, e no Creator e no Artist as músicas se separam em [stems](/docs/api-acemusic-v1/post-acemusic-music-stems) e são [baixadas](/docs/api-acemusic-v1/get-acemusic-music-download) em WAV, MIDI ou MusicXML. O ACE-Step v1.5 XL, gratuito, acrescenta remixes, edições e andamento, tom e compasso definidos. Cada conta roda até 4 requisições ao mesmo tempo. - Mureka V9.5, pela [API do Mureka](/docs/api-mureka-v1): duas músicas por chamada, de até 5 minutos, a partir de um prompt de uma linha ou da sua letra mais um estilo. No Mureka Premier ele canta com a sua própria voz por meio de um [character](/docs/api-mureka-v1/post-mureka-music-characters) reutilizável e separa uma música em [stems](/docs/api-mureka-v1/post-mureka-music-stems) mais MIDI. Ele também escreve [partituras](/docs/articles/mureka-sheet-music) em MusicXML e PDF, faz [remix](/docs/api-mureka-v1/post-mureka-music-remix) de uma música num novo estilo, estende a música e edita trechos, com até 10 gerações ao mesmo tempo por conta. - Lyria 3.5, pela [API do Flow Music](/docs/api-flowmusic-v1), que controla o [Google Flow Music](https://www.flowmusic.app): um par A/B por chamada, em WAV, mp3 ou m4a. O [POST music/edit](/docs/api-flowmusic-v1/post-flowmusic-music-edit) faz covers, remixes de letra, extensões de até 300 segundos, substituição de trechos, efeitos de áudio e uma separação em quatro stems no mesmo plano. Passe `model="lyria-3.5"`, porque a API mantém `lyria-3-pro` como padrão. Os planos pagos rodam de 8 a 16 gerações ao mesmo tempo. - TemPolor v4.8, pela [API do TemPolor](/docs/api-tempolor-v1): músicas de até 5 minutos em mais de 30 idiomas a partir de um prompt ou da sua própria letra, cantadas por uma [voz clonada](/docs/api-tempolor-v1/post-tempolor-music-cloned-voices) ou por uma das vozes de artista do serviço, ou construídas sobre um [arquivo MIDI](/docs/api-tempolor-v1/post-tempolor-music-midi) que você envia. Toda música pode ser [baixada](/docs/api-tempolor-v1/get-tempolor-music-download-job_id) em mp3, wav ou num ZIP de stems, o [music/stems-splitter](/docs/api-tempolor-v1/post-tempolor-music-stems-splitter) separa o seu próprio áudio, e o [music/instrumental](/docs/api-tempolor-v1/post-tempolor-music-instrumental) roda o modelo i4 para faixas sem vocais. Até 10 gerações rodam ao mesmo tempo. - MiniMax Music 3.0, pela [API do MiniMax](/docs/api-minimax-v1/post-minimax-music-create): de uma a três músicas por chamada a partir de um prompt de estilo e da sua letra, ou de uma letra que ele mesmo escreve, além de instrumentais e covers de uma [faixa de referência](/docs/api-minimax-v1/post-minimax-music-reference). As músicas chegam em MP3 de 256 kbps, e com `stream: true` o áudio toca enquanto é renderizado. ### Ouça primeiro Todas as faixas abaixo estão completas e sem edição, e a página de onde cada uma vem mostra a chamada de API por trás dela. Todas vêm da nossa [comparação destes modelos nos mesmos seis briefings](/docs/articles/ai-music-flagships-compared), onde o ACE Music v1 se juntou aos outros quatro em 14 de novembro de 2026. As faixas do Lyria foram convertidas do WAV da API para MP3 para que o navegador consiga tocá-las, e cada faixa do ACE Music v1 é a primeira das duas músicas que o ACE Music gera por requisição. Um prompt de uma frase, e o modelo escreve a letra: *"A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."* ([rodada 3](/docs/articles/ai-music-flagships-compared#round-3-pop-duet)) ACE Music v1 — "Three Dot Bubbles" · 0:41 · gerada em 54 s <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Are You Still Awake?" · 3:05 · gerada em 88 s <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "You Go First" · 1:59 · gerada em 74 s <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> A nossa própria letra e um briefing de estilo deep house a 121 BPM, nos cinco modelos ([rodada 5](/docs/articles/ai-music-flagships-compared#round-5-deep-house)): ACE Music v1 — "Two shadows in a velvet" · 1:53 · gerada em 52 s <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Low Light" · 3:09 · gerada em 101 s <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Velvet Room" · 2:26 · gerada em 43 s <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> TemPolor v4.8 — "Low Light" · 1:28 · gerada em 51 s <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-tempolor-v4.8.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music 3.0 — "Low Light" · 2:47 · gerada em 135 s <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Um dueto masculino e feminino sobre jazzy house, com os papéis de cada voz escritos na letra ([rodada 6](/docs/articles/ai-music-flagships-compared#round-6-jazzy-house-duet)): Mureka V9.5 — "Blue Hour" · 3:12 · gerada em 70 s <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Blue Hour" · 2:34 · gerada em 58 s <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Uma terceira música do ACE Music v1, escrita a partir da foto de um robô mascote dançando, toca junto com a foto num [YouTube Short](https://youtube.com/shorts/z_aOmILvIng). Outras, cada uma com a requisição que a gerou, estão nos [exemplos do nosso tutorial da API do ACE Music](/docs/articles/ace-music-api-tutorial#examples). O corte de 15 minutos no YouTube toca os 30 segundos mais altos de todas as 30 faixas, cinco modelos nos seis briefings com o ACE Music v1 incluído, com volume equalizado, e o preço por música de cada serviço em novembro de 2026. A comparação completa de preços está em [Preço por música](#price-per-song). <div style="max-width:720px"> <div style="position:relative;width:100%;padding-top:56.25%;border-radius:8px;overflow:hidden"> <iframe src="https://www.youtube.com/embed/MSUGckk4JqU" title="Five AI music APIs on the same six briefs" style="position:absolute;top:0;left:0;width:100%;height:100%;border:0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen loading="lazy"></iframe> </div> </div> ### Mãos à obra Conecte a sua conta com [Setup ACE Music](/docs/start-here/setup-acemusic), [Setup Mureka](/docs/start-here/setup-mureka), [Setup Flow Music](/docs/start-here/setup-flowmusic), [Setup TemPolor](/docs/start-here/setup-tempolor) ou [Setup MiniMax](/docs/start-here/setup-minimax) e depois gere uma música com [ACE Music POST music](/docs/api-acemusic-v1/post-acemusic-music), [Mureka POST music/create](/docs/api-mureka-v1/post-mureka-music-create), [Flow Music POST music](/docs/api-flowmusic-v1/post-flowmusic-music), [TemPolor POST music/song](/docs/api-tempolor-v1/post-tempolor-music-song) ou [MiniMax POST music/create](/docs/api-minimax-v1/post-minimax-music-create). Cada página tem código pronto para rodar, e os tutoriais do [ACE Music](/docs/articles/ace-music-api-tutorial), do [Mureka](/docs/articles/mureka-bash) e do [Flow Music](/docs/articles/flowmusic-bash) mostram a primeira música passo a passo. [Exemplos no GitHub: useapi/acemusic-api](https://github.com/useapi/acemusic-api), [useapi/mureka-api](https://github.com/useapi/mureka-api) e [useapi/flowmusic-api](https://github.com/useapi/flowmusic-api) geração de músicas em Node.js, e também em Python para o ACE Music [Servidor MCP do ACE Music](/docs/api-acemusic-v1/mcp) (15 ferramentas), [servidor MCP do Mureka](/docs/api-mureka-v1/mcp) (40 ferramentas) e [servidor MCP do Flow Music](/docs/api-flowmusic-v1/mcp) (18 ferramentas) músicas, stems e edições pelo Claude Code, Cursor, VS Code e outros clientes MCP ## Perguntas ### Existe uma alternativa à API do Suno? Pela useapi.net, sim: o ACE Music v1, 1º lugar no [ranking de música vocal da Artificial Analysis](https://artificialanalysis.ai/music/leaderboard/vocals) à frente do Suno v6, além do Mureka V9.5, do Lyria 3.5 do Google, do TemPolor v4.8 e do MiniMax Music 3.0, geram músicas com vocais via REST, a partir de um prompt ou da sua própria letra. A API para desenvolvedores do Suno é um beta para parceiros selecionados (em novembro de 2026). ### Quanto custa uma música com IA por API? Pela useapi.net, uma música do ACE Music v1 custa cerca de $0,013 no ACE Music Artist com cobrança anual, e uma música do ACE-Step v1.5 XL não custa nada, enquanto a API da acestep.io, de terceiros, cobra cerca de $0,14. Uma música do MiniMax Music 3.0 custa cerca de $0,01 no MiniMax Audio Pro, contra $0,15 na API do MiniMax, e uma do Lyria 3.5 cerca de $0,011 no Flow Music Member, contra $0,08 na Gemini API do Google (em novembro de 2026). Veja [Preço por música](#price-per-song). ### Uma API de música com IA pode cantar com a minha voz? Pela useapi.net, sim. O Mureka transforma cerca de 30 segundos do seu canto num [character](/docs/api-mureka-v1/post-mureka-music-characters) reutilizável sem custo no Mureka Premier, enquanto a API oficial do Mureka cobra $5 por voz (em novembro de 2026). O TemPolor clona uma voz a partir de uma amostra enviada com o [POST music/cloned-voices](/docs/api-tempolor-v1/post-tempolor-music-cloned-voices) e canta qualquer música com ela, a partir de um prompt ou da sua própria letra. ### Dá para obter stems e partitura de uma API de música com IA? Pela useapi.net, uma música do Mureka se separa em até 12 stems mais MIDI no Mureka Premier por cerca de um quinto dos $0,70 que a API oficial do Mureka cobra, e vira partitura por $0,02 ou menos, contra $0,20 (em novembro de 2026). O ACE Music exporta stems, MIDI e MusicXML no Creator e no Artist, toda música do TemPolor pode ser baixada como ZIP de stems, e o Flow Music separa uma música do Lyria em bateria, baixo, vocais e o restante. --- Os preços deste artigo foram conferidos em novembro de 2026, e esses serviços mudam planos e tarifas sem aviso, então confira o preço atual antes de investir. ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/suno-api-alternative-th === Document URL: https://useapi.net/docs/articles/suno-api-alternative-th --- layout: default translation_key: suno-api-alternative lang: th title: "ทางเลือกแทน Suno API: ACE Music, Mureka, Lyria 3.5, TemPolor และ MiniMax" seo_title: "ทางเลือกแทน Suno API: ACE Music, Mureka, Lyria, TemPolor, MiniMax" description: "ทางเลือกแทน Suno API ผ่าน useapi.net: ACE Music v1 อันดับ 1 บนตารางอันดับเสียงร้องของ Artificial Analysis นำหน้า Suno v6 พร้อม Mureka V9.5, Lyria 3.5, TemPolor และ MiniMax ราวเพลงละ $0.01 ถึง $0.02" keywords: [Suno API alternative, Suno alternative API, ACE Music API, ACE Music v1 API, ACE-Step API, AI song generator API, AI song API with vocals, AI music API, AI music API pricing, song generation API, text to song API, Mureka API, Mureka V9.5 API, Lyria 3.5 API, Flow Music API, Lyria API pricing, TemPolor API, TemPolor v4.8 API, MiniMax Music API, MiniMax Music 3.0 API, MiniMax music API pricing, ทางเลือกแทน Suno API, Suno API ภาษาไทย, API สร้างเพลง AI, API เพลง AI, ราคา API เพลง AI, สร้างเพลงด้วย AI, แต่งเพลง AI, เพลง AI มีเสียงร้อง, เปรียบเทียบเพลง AI] image: /assets/images/articles/ai-music-flagships-compared.jpg video: name: "API เพลง AI ห้าตัวกับโจทย์เดียวกันหกโจทย์" description: "ACE Music v1, TemPolor v4.8 และ i4, MiniMax Music-3.0, Google Lyria 3.5 และ Mureka V9.5 กับโจทย์เดียวกันหกโจทย์ — 30 วินาทีที่ดังที่สุดของแต่ละแทร็ก ปรับความดังให้เท่ากัน พร้อมพรอมต์ ราคา และเวลาที่ใช้สร้างบนหน้าจอ" embed: https://www.youtube.com/embed/MSUGckk4JqU thumbnail: https://i.ytimg.com/vi/MSUGckk4JqU/maxresdefault.jpg date: 2026-11-14 duration: PT15M width: 1920 height: 1080 parent: Articles nav_exclude: true date: 2026-10-20 last_modified: 2026-11-18 nav_order: 906 --- ## ทางเลือกแทน Suno API: ACE Music, Mureka, Lyria 3.5, TemPolor และ MiniMax {: .no_toc #suno-api-alternative-ace-music-mureka-lyria-35-tempolor-and-minimax } อ่าน 7 นาที • 20 ตุลาคม 2026 (18 พฤศจิกายน 2026) ## สารบัญ {: .no_toc .text-delta #table-of-contents } ### บทนำ ผ่าน useapi.net โมเดล ACE Music v1 ซึ่งอยู่อันดับ 1 บน[ตารางอันดับโมเดลเพลงที่มีเสียงร้องของ Artificial Analysis](https://artificialanalysis.ai/music/leaderboard/vocals) นำหน้า Suno v6 สร้างเพลงเต็มเพลงผ่าน REST ด้วยแพ็กเกจ [ACE Music](https://acemusic.ai/pricing/) ของคุณ โมเดลเพลงที่มีเสียงร้องอีกสี่ตัวทำงานแบบเดียวกัน ได้แก่ Mureka V9.5 และ Lyria 3.5 ของ Google ซึ่งทั้งคู่อยู่ในหกอันดับแรกของตารางนั้น รวมถึง TemPolor v4.8 และ MiniMax Music 3.0 โดยใช้แพ็กเกจบนเว็บไซต์ [Mureka](https://www.mureka.ai/subscribe), [Flow Music](https://www.flowmusic.app/pricing), [TemPolor](https://www.tempolor.com/pricing) หรือ [MiniMax Audio](https://www.minimax.io/audio/subscribe) ของคุณ ส่วน API สำหรับนักพัฒนาของ Suno เองยังเป็นเบตาสำหรับพาร์ตเนอร์ที่คัดเลือกไว้ ไม่มีเอกสารหรือรายการราคาสาธารณะ (ข้อมูล ณ พฤศจิกายน 2026) useapi.net เป็นบริการของ[บุคคลที่สาม](/docs/legal#affiliation--third-party-services) ไม่มีส่วนเกี่ยวข้องกับ Suno, Timedomain, Kunlun Tech, Google, Qustar Technology หรือ MiniMax ### ราคาต่อเพลง ค่าใช้จ่ายของเพลงที่มีเสียงร้องหนึ่งเพลงบน API ทางการของผู้สร้างแต่ละราย ([Mureka](https://platform.mureka.ai/pricing), [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) ของ Google, [TemPolor](https://platform.tempolor.com/docs/6665893m0), [MiniMax](https://platform.minimax.io/docs/pricing/overview#about-music-models) ซึ่งปิดรับผู้ใช้ใหม่ตั้งแต่ 20 สิงหาคม 2026) และบนแพ็กเกจเว็บไซต์แต่ละแบบ (พฤศจิกายน 2026) แต่ละแพ็กเกจให้เครดิตจำนวนหนึ่งต่อเดือน และแต่ละเพลงใช้เครดิตจำนวนตายตัว ราคาต่อเพลงจึงเท่ากับส่วนแบ่งของค่าแพ็กเกจ | โมเดล | API ทางการ | แพ็กเกจรายเดือนบนเว็บไซต์ | ราคาต่อเพลง | |---|---|---|---| | ACE Music v1 | — | ACE Music Creator $9.90 (1,000 cr/เดือน) | $0.02 / 2 cr (500 เพลง/เดือน) | | ACE Music v1 | — | ACE Music Artist $29 (2,500 cr/เดือน) | $0.023 / 2 cr (1,250 เพลง/เดือน) | | ACE-Step v1.5 XL (10 ถึง 240 วินาที, MP3 เท่านั้น) | — (โอเพนซอร์ส) | ทุกแพ็กเกจ ACE Music (รวมถึงแพ็กเกจ Free) | $0 / 0 cr (ไม่ใช้เครดิต) | | Mureka V9.5 | $0.15 (เติมเงินล่วงหน้าตั้งแต่ $1,000) | Mureka Pro $10 (5,000 cr/เดือน) | $0.024 / 12 cr (416 เพลง/เดือน) | | Mureka V9.5 | $0.15 (เติมเงินล่วงหน้าตั้งแต่ $1,000) | Mureka Premier $30 (20,000 cr/เดือน) | $0.018 / 12 cr (1,666 เพลง/เดือน) | | Lyria 3.5 | $0.08 (ต่อเพลง) | Flow Music Starter $8 (3,000 cr/เดือน) | $0.013 / 5 cr (600 เพลง/เดือน) | | Lyria 3.5 | $0.08 (ต่อเพลง) | Flow Music Member $64 (30,000 cr/เดือน) | $0.011 / 5 cr (6,000 เพลง/เดือน) | | TemPolor v4.8 | $0.04 (ต่อครั้ง เติมเงินล่วงหน้าตั้งแต่ $100) | TemPolor Ultra $29.99 | $0 / 0 cr (ไม่คิดเงินต่อเพลง) | | MiniMax Music 3.0 | $0.15 (ปิดรับผู้ใช้ใหม่ตั้งแต่ 20 สิงหาคม 2026) | MiniMax Audio Pro $99 (3,000,000 cr/เดือน) | $0.01 / 300 cr (10,000 เพลง/เดือน) | - เมื่อชำระรายปี ACE Music Artist อยู่ที่ $16.58 ต่อเดือน ทำให้เพลง ACE Music v1 หนึ่งเพลงเหลือราว $0.013 เครดิตรายวัน 20 เครดิตของแพ็กเกจ Free สร้างได้ราว 10 เพลงต่อวันสำหรับใช้ส่วนตัว ส่วนสิทธิ์เชิงพาณิชย์มาพร้อม Creator และ Artist - [ACE-Step](https://ace-step.github.io) v1.5 XL คือโมเดลโอเพนซอร์สโดย ACE Studio และ StepFun ที่กำหนดจังหวะ (`bpm`), `key` และ `timeSignature` ได้ ไม่ใช้เครดิตในทุกแพ็กเกจ ACE Music รวมถึงแพ็กเกจ Free ขณะที่ acestep.io ซึ่งเป็นบุคคลที่สามคิดราว $0.14 ต่อเพลง ผ่าน API ที่ต้องใช้แพ็กเกจ Studio $49 ต่อเดือน - เมื่อให้โมเดลเขียนเนื้อเพลงจากพรอมต์ API ของ Mureka คิด $0.50 แทน $0.15 และ API ของ MiniMax กับ TemPolor บวกเพิ่ม $0.01 ส่วนผ่าน useapi.net เพลงหนึ่งเพลงราคาเท่าเดิมไม่ว่าแบบใด - เครดิต API ของ TemPolor ราคาเท่ากันทุกขนาดแพ็กเกจ การซื้อจำนวนมากจึงไม่ทำให้ราคาถูกลง - เมื่อชำระรายปี Flow Music Member อยู่ที่ $48 ต่อเดือน ทำให้เพลง Lyria หนึ่งเพลงเหลือราว $0.008 - แพ็กเกจ Google AI รวมแพ็กเกจ Flow Music ไว้ด้วย โดยเครดิตแยกจากเครดิต Google AI: Starter ใน [Google AI Plus](https://support.google.com/googleone/answer/16882689?hl=th), Plus ใน [Google AI Pro](https://support.google.com/googleone/answer/14534406?hl=th) และ Member ใน [Google AI Ultra](https://support.google.com/googleone/answer/16286513?hl=th) - หากมีหลายแพ็กเกจ โทเค็น useapi.net เดียวใช้ได้กับทุกแพ็กเกจ และกระจายเพลงของคุณไปยังแต่ละแพ็กเกจให้โดยอัตโนมัติ ### แต่ละโมเดลทำอะไรได้บ้าง - ACE Music v1 ผ่าน [ACE Music API](/docs/api-acemusic-v1): สองเพลงต่อคำขอ จากพรอมต์หรือจากสไตล์และเนื้อเพลงของคุณเอง แบบมีเสียงร้องหรือบรรเลง ยาวตั้งแต่ 30 วินาทีถึง 10 นาที ACE Music v1.1 Preview ทำ[คัฟเวอร์และแมชอัป](/docs/api-acemusic-v1/post-acemusic-music#modes)ที่ตามทำนองของเพลงต้นทาง เพลงและภาพที่คุณ[อัปโหลด](/docs/api-acemusic-v1/post-acemusic-files)ใช้นำทางเพลงใหม่ได้ และใน Creator และ Artist เพลงแยกเป็น[สเต็ม](/docs/api-acemusic-v1/post-acemusic-music-stems)และ[ดาวน์โหลด](/docs/api-acemusic-v1/get-acemusic-music-download)เป็น WAV, MIDI หรือ MusicXML ได้ ส่วน ACE-Step v1.5 XL ที่ใช้ฟรีเพิ่มรีมิกซ์ การแก้ไข และการกำหนดจังหวะ คีย์ และอัตราจังหวะ แต่ละบัญชีรันได้พร้อมกันสูงสุด 4 คำขอ - Mureka V9.5 ผ่าน [Mureka API](/docs/api-mureka-v1): สองเพลงต่อการเรียก ยาวไม่เกิน 5 นาที จากพรอมต์บรรทัดเดียวหรือจากเนื้อเพลงของคุณพร้อมสไตล์ ใน Mureka Premier ร้องด้วยเสียงของคุณเองผ่าน[ตัวละคร (character)](/docs/api-mureka-v1/post-mureka-music-characters)ที่ใช้ซ้ำได้ และแยกเพลงเป็น[สเต็ม](/docs/api-mureka-v1/post-mureka-music-stems)พร้อม MIDI ได้ นอกจากนี้ยังเขียน[โน้ตเพลง](/docs/articles/mureka-sheet-music)เป็น MusicXML และ PDF [รีมิกซ์](/docs/api-mureka-v1/post-mureka-music-remix)เพลงเป็นสไตล์ใหม่ ต่อความยาว และแก้ไขบางท่อนได้ รันได้พร้อมกันสูงสุด 10 งานต่อบัญชี - Lyria 3.5 ผ่าน [Flow Music API](/docs/api-flowmusic-v1) ซึ่งควบคุม [Google Flow Music](https://www.flowmusic.app): ได้คู่ A/B ต่อการเรียก เป็น WAV, mp3 หรือ m4a [POST music/edit](/docs/api-flowmusic-v1/post-flowmusic-music-edit) ทำคัฟเวอร์ รีมิกซ์เนื้อเพลง ต่อความยาวได้สูงสุด 300 วินาที แทนที่บางท่อน ใส่เอฟเฟกต์เสียง และแยกเป็นสี่สเต็มได้จากแพ็กเกจเดียวกัน ให้ส่ง `model="lyria-3.5"` เพราะ API ใช้ `lyria-3-pro` เป็นค่าเริ่มต้น แพ็กเกจแบบชำระเงินรันได้พร้อมกัน 8 ถึง 16 งาน - TemPolor v4.8 ผ่าน [TemPolor API](/docs/api-tempolor-v1): เพลงยาวไม่เกิน 5 นาทีในกว่า 30 ภาษา จากพรอมต์หรือเนื้อเพลงของคุณเอง ร้องด้วย[เสียงโคลน](/docs/api-tempolor-v1/post-tempolor-music-cloned-voices)หรือเสียงศิลปินของ TemPolor หรือสร้างบน[ไฟล์ MIDI](/docs/api-tempolor-v1/post-tempolor-music-midi)ที่คุณอัปโหลด ทุกเพลง[ดาวน์โหลด](/docs/api-tempolor-v1/get-tempolor-music-download-job_id)ได้เป็น mp3, wav หรือ ZIP สเต็ม [music/stems-splitter](/docs/api-tempolor-v1/post-tempolor-music-stems-splitter) แยกไฟล์เสียงของคุณเอง และ [music/instrumental](/docs/api-tempolor-v1/post-tempolor-music-instrumental) ใช้โมเดล i4 สำหรับแทร็กที่ไม่มีเสียงร้อง รันได้พร้อมกันสูงสุด 10 งาน - MiniMax Music 3.0 ผ่าน [MiniMax API](/docs/api-minimax-v1/post-minimax-music-create): หนึ่งถึงสามเพลงต่อการเรียก จากพรอมต์สไตล์และเนื้อเพลงของคุณ หรือเนื้อเพลงที่โมเดลเขียนเอง รวมถึงเพลงบรรเลงและคัฟเวอร์จาก[แทร็กอ้างอิง](/docs/api-minimax-v1/post-minimax-music-reference) ได้เพลงเป็น MP3 256 kbps และเมื่อใช้ `stream: true` เสียงจะเล่นได้ระหว่างที่กำลังสร้าง ### ฟังก่อน ทุกแทร็กด้านล่างเป็นเพลงเต็มที่ไม่ได้ตัดต่อ และหน้าที่มาของแต่ละแทร็กแสดงการเรียก API ที่ใช้สร้างไว้ ทั้งหมดมาจาก[การเปรียบเทียบโมเดลเหล่านี้กับโจทย์เดียวกันหกโจทย์](/docs/articles/ai-music-flagships-compared) ซึ่ง ACE Music v1 เข้าร่วมกับอีกสี่โมเดลเมื่อ 14 พฤศจิกายน 2026 แทร็ก Lyria แปลงจาก WAV ของ API เป็น MP3 เพื่อให้เล่นในเบราว์เซอร์ได้ และแทร็ก ACE Music v1 แต่ละแทร็กคือเพลงแรกจากสองเพลงที่ ACE Music สร้างต่อคำขอ พรอมต์ประโยคเดียว ให้โมเดลเขียนเนื้อเพลงเอง: *"A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."* ([รอบที่ 3](/docs/articles/ai-music-flagships-compared#round-3-pop-duet)) ACE Music v1 — "Three Dot Bubbles" · 0:41 · สร้างใน 54 วินาที <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Are You Still Awake?" · 3:05 · สร้างใน 88 วินาที <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "You Go First" · 1:59 · สร้างใน 74 วินาที <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> เนื้อเพลงของเราเองกับโจทย์สไตล์ดีปเฮาส์ที่ 121 BPM บนทั้งห้าโมเดล ([รอบที่ 5](/docs/articles/ai-music-flagships-compared#round-5-deep-house)): ACE Music v1 — "Two shadows in a velvet" · 1:53 · สร้างใน 52 วินาที <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Low Light" · 3:09 · สร้างใน 101 วินาที <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Velvet Room" · 2:26 · สร้างใน 43 วินาที <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> TemPolor v4.8 — "Low Light" · 1:28 · สร้างใน 51 วินาที <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-tempolor-v4.8.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music 3.0 — "Low Light" · 2:47 · สร้างใน 135 วินาที <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> เพลงคู่ชายหญิงบนจังหวะแจ๊ซซีเฮาส์ โดยกำหนดบทของแต่ละเสียงไว้ในเนื้อเพลง ([รอบที่ 6](/docs/articles/ai-music-flagships-compared#round-6-jazzy-house-duet)): Mureka V9.5 — "Blue Hour" · 3:12 · สร้างใน 70 วินาที <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Blue Hour" · 2:34 · สร้างใน 58 วินาที <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> เพลง ACE Music v1 เพลงที่สาม แต่งจากภาพถ่ายมาสคอตหุ่นยนต์ที่กำลังเต้น เล่นคู่กับภาพนั้นใน [YouTube Short](https://youtube.com/shorts/z_aOmILvIng) ดูเพลงเพิ่มเติมพร้อมคำขอที่ใช้สร้างแต่ละเพลงได้ใน[ตัวอย่างของคู่มือ ACE Music API](/docs/articles/ace-music-api-tutorial#examples) คลิปฟังเปรียบเทียบความยาว 15 นาทีบน YouTube เล่น 30 วินาทีที่ดังที่สุดของทั้ง 30 แทร็ก ห้าโมเดลกับโจทย์เดียวกันหกโจทย์ รวม ACE Music v1 ด้วย โดยปรับความดังให้เท่ากัน พร้อมราคาต่อเพลงของแต่ละบริการ ณ เดือนพฤศจิกายน 2026 การเปรียบเทียบราคาฉบับเต็มอยู่ใน[ราคาต่อเพลง](#price-per-song) <div style="max-width:720px"> <div style="position:relative;width:100%;padding-top:56.25%;border-radius:8px;overflow:hidden"> <iframe src="https://www.youtube.com/embed/MSUGckk4JqU" title="Five AI music APIs on the same six briefs" style="position:absolute;top:0;left:0;width:100%;height:100%;border:0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen loading="lazy"></iframe> </div> </div> ### เริ่มสร้าง เชื่อมต่อบัญชีของคุณด้วย[ตั้งค่า ACE Music](/docs/start-here/setup-acemusic), [ตั้งค่า Mureka](/docs/start-here/setup-mureka), [ตั้งค่า Flow Music](/docs/start-here/setup-flowmusic), [ตั้งค่า TemPolor](/docs/start-here/setup-tempolor) หรือ[ตั้งค่า MiniMax](/docs/start-here/setup-minimax) แล้วสร้างเพลงด้วย [ACE Music POST music](/docs/api-acemusic-v1/post-acemusic-music), [Mureka POST music/create](/docs/api-mureka-v1/post-mureka-music-create), [Flow Music POST music](/docs/api-flowmusic-v1/post-flowmusic-music), [TemPolor POST music/song](/docs/api-tempolor-v1/post-tempolor-music-song) หรือ [MiniMax POST music/create](/docs/api-minimax-v1/post-minimax-music-create) แต่ละหน้ามีโค้ดพร้อมรัน และคู่มือ [ACE Music](/docs/articles/ace-music-api-tutorial), [Mureka](/docs/articles/mureka-bash) และ [Flow Music](/docs/articles/flowmusic-bash) พาไปทีละขั้นตอนจนได้เพลงแรก [ตัวอย่างบน GitHub: useapi/acemusic-api](https://github.com/useapi/acemusic-api), [useapi/mureka-api](https://github.com/useapi/mureka-api) และ [useapi/flowmusic-api](https://github.com/useapi/flowmusic-api) สร้างเพลงด้วย Node.js และ Python สำหรับ ACE Music [ACE Music MCP server](/docs/api-acemusic-v1/mcp) (15 เครื่องมือ), [Mureka MCP server](/docs/api-mureka-v1/mcp) (40 เครื่องมือ) และ [Flow Music MCP server](/docs/api-flowmusic-v1/mcp) (18 เครื่องมือ) สร้างเพลง สเต็ม และการแก้ไขจาก Claude Code, Cursor, VS Code และไคลเอนต์ MCP อื่นๆ ## คำถามที่พบบ่อย ### มีทางเลือกแทน Suno API ไหม? ผ่าน useapi.net มี: ACE Music v1 อันดับ 1 บน[ตารางอันดับโมเดลเพลงที่มีเสียงร้องของ Artificial Analysis](https://artificialanalysis.ai/music/leaderboard/vocals) นำหน้า Suno v6 พร้อม Mureka V9.5, Lyria 3.5 ของ Google, TemPolor v4.8 และ MiniMax Music 3.0 สร้างเพลงที่มีเสียงร้องผ่าน REST จากพรอมต์หรือเนื้อเพลงของคุณเอง ส่วน API สำหรับนักพัฒนาของ Suno ยังเป็นเบตาสำหรับพาร์ตเนอร์ที่คัดเลือกไว้ (ข้อมูล ณ พฤศจิกายน 2026) ### เพลง AI ผ่าน API ราคาเท่าไร? ผ่าน useapi.net เพลง ACE Music v1 หนึ่งเพลงราว $0.013 บน ACE Music Artist แบบชำระรายปี และเพลง ACE-Step v1.5 XL ไม่มีค่าใช้จ่าย ขณะที่ API ของ acestep.io ซึ่งเป็นบุคคลที่สามคิดราว $0.14 เพลง MiniMax Music 3.0 ราว $0.01 บน MiniMax Audio Pro เทียบกับ $0.15 บน API ของ MiniMax และเพลง Lyria 3.5 ราว $0.011 บน Flow Music Member เทียบกับ $0.08 บน Gemini API ของ Google (ข้อมูล ณ พฤศจิกายน 2026) ดูที่[ราคาต่อเพลง](#price-per-song) ### API เพลง AI ร้องด้วยเสียงของฉันเองได้ไหม? ผ่าน useapi.net ได้ Mureka เปลี่ยนเสียงร้องของคุณราว 30 วินาทีให้เป็น[ตัวละคร (character)](/docs/api-mureka-v1/post-mureka-music-characters)ที่ใช้ซ้ำได้โดยไม่มีค่าใช้จ่ายบน Mureka Premier ขณะที่ API ทางการของ Mureka คิด $5 ต่อเสียง (ข้อมูล ณ พฤศจิกายน 2026) ส่วน TemPolor โคลนเสียงจากตัวอย่างเสียงที่อัปโหลดด้วย [POST music/cloned-voices](/docs/api-tempolor-v1/post-tempolor-music-cloned-voices) แล้วร้องเพลงใดก็ได้ด้วยเสียงนั้น จากพรอมต์หรือจากเนื้อเพลงของคุณเอง ### API เพลง AI แยกสเต็มและทำโน้ตเพลงได้ไหม? ผ่าน useapi.net เพลง Mureka แยกได้สูงสุด 12 สเต็มพร้อม MIDI บน Mureka Premier ในราคาราวหนึ่งในห้าของ $0.70 ที่ API ทางการของ Mureka คิด และทำเป็นโน้ตเพลงได้ในราคา $0.02 หรือน้อยกว่า เทียบกับ $0.20 (ข้อมูล ณ พฤศจิกายน 2026) ACE Music ส่งออกสเต็ม MIDI และ MusicXML ได้บน Creator และ Artist ทุกเพลงของ TemPolor ดาวน์โหลดเป็น ZIP สเต็มได้ และ Flow Music แยกเพลง Lyria เป็นกลอง เบส เสียงร้อง และส่วนอื่นๆ --- ราคาในบทความนี้อ่านเมื่อพฤศจิกายน 2026 และบริการเหล่านี้เปลี่ยนแพ็กเกจและอัตราราคาโดยไม่แจ้งล่วงหน้า โปรดตรวจสอบราคาปัจจุบันก่อนตัดสินใจใช้จ่าย ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/suno-api-alternative-vi === Document URL: https://useapi.net/docs/articles/suno-api-alternative-vi --- layout: default title: "Giải pháp thay thế Suno API: ACE Music, Mureka, Lyria 3.5, TemPolor và MiniMax" seo_title: "Thay thế Suno API: ACE Music, Mureka, Lyria, TemPolor, MiniMax" description: "Giải pháp thay thế Suno API qua useapi.net: ACE Music v1, hạng 1 trên bảng xếp hạng nhạc có giọng hát của Artificial Analysis, trên cả Suno v6, cùng Mureka V9.5, Lyria 3.5, TemPolor và MiniMax, khoảng $0,01 đến $0,02 một bài hát." keywords: [Suno API alternative, Suno alternative API, ACE Music API, ACE Music v1 API, ACE-Step API, AI song generator API, AI song API with vocals, AI music API, AI music API pricing, song generation API, text to song API, Mureka API, Mureka V9.5 API, Lyria 3.5 API, Flow Music API, Lyria API pricing, TemPolor API, TemPolor v4.8 API, MiniMax Music API, MiniMax Music 3.0 API, MiniMax music API pricing, thay thế Suno API, API tạo nhạc AI, API tạo bài hát AI, tạo bài hát có giọng hát, giá API nhạc AI, tạo nhạc từ văn bản] image: /assets/images/articles/ai-music-flagships-compared.jpg video: name: "Năm API nhạc AI trên cùng sáu đề bài" description: "ACE Music v1, TemPolor v4.8 và i4, MiniMax Music-3.0, Google Lyria 3.5 và Mureka V9.5 trên cùng sáu đề bài, mỗi bản nhạc lấy 30 giây to nhất, cân bằng âm lượng, kèm prompt, giá và thời gian tạo trên màn hình." embed: https://www.youtube.com/embed/MSUGckk4JqU thumbnail: https://i.ytimg.com/vi/MSUGckk4JqU/maxresdefault.jpg date: 2026-11-14 duration: PT15M width: 1920 height: 1080 parent: Articles nav_exclude: true lang: vi translation_key: suno-api-alternative date: 2026-10-20 last_modified: 2026-11-18 nav_order: 906 --- ## Giải pháp thay thế Suno API: ACE Music, Mureka, Lyria 3.5, TemPolor và MiniMax {: .no_toc #suno-api-alternative-ace-music-mureka-lyria-35-tempolor-and-minimax } 7 phút đọc • 20 tháng 10 năm 2026 (18 tháng 11 năm 2026) ## Mục lục {: .no_toc .text-delta #table-of-contents } ### Giới thiệu Qua useapi.net, ACE Music v1, model đứng hạng 1 trên [bảng xếp hạng nhạc có giọng hát của Artificial Analysis](https://artificialanalysis.ai/music/leaderboard/vocals), trên cả Suno v6, tạo trọn vẹn bài hát qua REST trên gói [ACE Music](https://acemusic.ai/pricing/) của bạn. Bốn model tạo bài hát có giọng hát khác chạy theo cùng cách: Mureka V9.5 và Lyria 3.5 của Google, cả hai đều nằm trong top sáu của bảng xếp hạng đó, TemPolor v4.8 và MiniMax Music 3.0, trên gói website [Mureka](https://www.mureka.ai/subscribe), [Flow Music](https://www.flowmusic.app/pricing), [TemPolor](https://www.tempolor.com/pricing) hoặc [MiniMax Audio](https://www.minimax.io/audio/subscribe) của bạn. API dành cho nhà phát triển của chính Suno đang là bản beta cho một số đối tác được chọn, không có tài liệu hay bảng giá công khai (tính đến tháng 11/2026). useapi.net là dịch vụ của [bên thứ ba](/docs/legal#affiliation--third-party-services), không liên kết với Suno, Timedomain, Kunlun Tech, Google, Qustar Technology hay MiniMax. ### Giá mỗi bài hát Chi phí một bài hát có giọng hát trên API chính thức của từng hãng ([Mureka](https://platform.mureka.ai/pricing), [Gemini API](https://ai.google.dev/gemini-api/docs/pricing) của Google, [TemPolor](https://platform.tempolor.com/docs/6665893m0), [MiniMax](https://platform.minimax.io/docs/pricing/overview#about-music-models), đã đóng với người dùng mới từ ngày 20/8/2026) và trên từng gói website (tháng 11/2026). Mỗi gói đi kèm một số credit mỗi tháng, và mỗi bài hát dùng một số credit cố định, nên một bài hát tốn đúng phần của nó trong giá gói. | Model | API chính thức | Gói website theo tháng | Giá mỗi bài | |---|---|---|---| | ACE Music v1 | — | ACE Music Creator $9,90 (1.000 cr/tháng) | $0,02 / 2 cr (500 bài/tháng) | | ACE Music v1 | — | ACE Music Artist $29 (2.500 cr/tháng) | $0,023 / 2 cr (1.250 bài/tháng) | | ACE-Step v1.5 XL (10 đến 240 giây, chỉ MP3) | — (mã nguồn mở) | Mọi gói ACE Music (kể cả gói Free) | $0 / 0 cr (không tốn credit) | | Mureka V9.5 | $0,15 (trả trước từ $1.000) | Mureka Pro $10 (5.000 cr/tháng) | $0,024 / 12 cr (416 bài/tháng) | | Mureka V9.5 | $0,15 (trả trước từ $1.000) | Mureka Premier $30 (20.000 cr/tháng) | $0,018 / 12 cr (1.666 bài/tháng) | | Lyria 3.5 | $0,08 (mỗi bài) | Flow Music Starter $8 (3.000 cr/tháng) | $0,013 / 5 cr (600 bài/tháng) | | Lyria 3.5 | $0,08 (mỗi bài) | Flow Music Member $64 (30.000 cr/tháng) | $0,011 / 5 cr (6.000 bài/tháng) | | TemPolor v4.8 | $0,04 (một lệnh gọi, trả trước từ $100) | TemPolor Ultra $29,99 | $0 / 0 cr (không tính phí theo bài) | | MiniMax Music 3.0 | $0,15 (đóng với người dùng mới từ 20/8/2026) | MiniMax Audio Pro $99 (3.000.000 cr/tháng) | $0,01 / 300 cr (10.000 bài/tháng) | - Khi trả theo năm, ACE Music Artist là $16,58 một tháng, đưa giá một bài hát ACE Music v1 xuống khoảng $0,013. 20 credit mỗi ngày của gói Free tạo được khoảng 10 bài mỗi ngày cho mục đích cá nhân, còn quyền sử dụng thương mại đi kèm Creator và Artist. - [ACE-Step](https://ace-step.github.io) v1.5 XL là model mã nguồn mở của ACE Studio và StepFun, với nhịp độ (`bpm`), `key` và `timeSignature` cố định theo ý bạn. Nó không tốn credit trên bất kỳ gói ACE Music nào, kể cả gói Free, trong khi bên thứ ba acestep.io tính khoảng $0,14 một bài qua một API đòi gói Studio $49 một tháng. - Khi model tự viết lời từ prompt, API của Mureka tính $0,50 thay vì $0,15, còn API của MiniMax và TemPolor cộng thêm $0,01, trong khi qua useapi.net một bài hát có giá như nhau dù theo cách nào. - Credit API của TemPolor có cùng giá ở mọi gói nạp, nên mua nhiều cũng không làm giá rẻ hơn. - Khi trả theo năm, Flow Music Member là $48 một tháng, đưa giá một bài hát Lyria xuống khoảng $0,008. - Các gói Google AI có kèm một gói Flow Music, với credit tách riêng khỏi credit Google AI: Starter trên [Google AI Plus](https://support.google.com/googleone/answer/16882689?hl=vi), Plus trên [Google AI Pro](https://support.google.com/googleone/answer/14534406?hl=vi) và Member trên [Google AI Ultra](https://support.google.com/googleone/answer/16286513?hl=vi). - Khi có nhiều gói, một token useapi.net dùng được với tất cả và tự động phân bổ bài hát của bạn giữa chúng. ### Mỗi model làm được gì - ACE Music v1, qua [ACE Music API](/docs/api-acemusic-v1): hai bài hát mỗi request từ một prompt hoặc phong cách và lời của riêng bạn, có hát hoặc không lời, dài từ 30 giây đến 10 phút. ACE Music v1.1 Preview tạo [cover và mashup](/docs/api-acemusic-v1/post-acemusic-music#modes) bám theo giai điệu của một bài hát, các bài hát và hình ảnh bạn [upload](/docs/api-acemusic-v1/post-acemusic-files) định hướng bài mới, và trên Creator và Artist, bài hát của nó tách được thành [stem](/docs/api-acemusic-v1/post-acemusic-music-stems) và [tải về](/docs/api-acemusic-v1/get-acemusic-music-download) dưới dạng WAV, MIDI hoặc MusicXML. ACE-Step v1.5 XL miễn phí bổ sung remix, chỉnh sửa và nhịp độ, tông, số chỉ nhịp cố định. Mỗi tài khoản chạy tối đa 4 request cùng lúc. - Mureka V9.5, qua [Mureka API](/docs/api-mureka-v1): hai bài hát mỗi lệnh gọi, dài tối đa 5 phút, từ một prompt một dòng hoặc từ lời của bạn cùng một phong cách. Trên Mureka Premier, nó hát bằng chính giọng của bạn qua một [character](/docs/api-mureka-v1/post-mureka-music-characters) dùng lại được và tách một bài hát thành [stem](/docs/api-mureka-v1/post-mureka-music-stems) kèm MIDI. Nó còn viết [bản nhạc](/docs/articles/mureka-sheet-music) dưới dạng MusicXML và PDF, [remix](/docs/api-mureka-v1/post-mureka-music-remix) một bài hát sang phong cách mới, kéo dài bài và chỉnh sửa từng đoạn, tối đa 10 lượt tạo cùng lúc mỗi tài khoản. - Lyria 3.5, qua [Flow Music API](/docs/api-flowmusic-v1), vốn điều khiển [Google Flow Music](https://www.flowmusic.app): một cặp A/B mỗi lệnh gọi, dưới dạng WAV, mp3 hoặc m4a. [POST music/edit](/docs/api-flowmusic-v1/post-flowmusic-music-edit) tạo cover, remix lời, kéo dài bài tối đa 300 giây, thay thế từng đoạn, hiệu ứng âm thanh và tách bốn stem trên cùng gói. Hãy truyền `model="lyria-3.5"`, vì API giữ `lyria-3-pro` làm mặc định. Các gói trả phí chạy 8 đến 16 lượt tạo cùng lúc. - TemPolor v4.8, qua [TemPolor API](/docs/api-tempolor-v1): bài hát dài tối đa 5 phút bằng hơn 30 ngôn ngữ từ một prompt hoặc lời của riêng bạn, do một [giọng nhân bản](/docs/api-tempolor-v1/post-tempolor-music-cloned-voices) hoặc một trong các giọng ca sĩ của nó hát, hoặc dựng trên một [file MIDI](/docs/api-tempolor-v1/post-tempolor-music-midi) bạn upload. Mọi bài hát đều [tải về](/docs/api-tempolor-v1/get-tempolor-music-download-job_id) được dưới dạng mp3, wav hoặc file ZIP chứa stem, [music/stems-splitter](/docs/api-tempolor-v1/post-tempolor-music-stems-splitter) tách âm thanh của riêng bạn, và [music/instrumental](/docs/api-tempolor-v1/post-tempolor-music-instrumental) chạy model i4 cho bản nhạc không lời. Tối đa 10 lượt tạo chạy cùng lúc. - MiniMax Music 3.0, qua [MiniMax API](/docs/api-minimax-v1/post-minimax-music-create): một đến ba bài hát mỗi lệnh gọi từ một prompt phong cách và lời của bạn, hoặc lời do nó tự viết, cùng bản nhạc không lời và cover theo một [bản nhạc tham chiếu](/docs/api-minimax-v1/post-minimax-music-reference). Bài hát trả về dưới dạng MP3 256 kbps, và với `stream: true`, âm thanh phát ngay trong lúc đang được tạo. ### Nghe trước Mỗi bản nhạc dưới đây đều hoàn chỉnh và chưa qua chỉnh sửa, và trang gốc của từng bản cho thấy lệnh gọi API đã tạo ra nó. Tất cả đều lấy từ [bài so sánh các model này trên cùng sáu đề bài](/docs/articles/ai-music-flagships-compared), nơi ACE Music v1 tham gia cùng bốn model kia vào ngày 14/11/2026. Các bản Lyria được chuyển mã từ WAV của API sang MP3 để trình duyệt phát được, và mỗi bản ACE Music v1 là bài đầu tiên trong hai bài ACE Music tạo mỗi request. Một prompt một câu, model tự viết lời: *"A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."* ([vòng 3](/docs/articles/ai-music-flagships-compared#round-3-pop-duet)) ACE Music v1 — "Three Dot Bubbles" · 0:41 · tạo trong 54 giây <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Are You Still Awake?" · 3:05 · tạo trong 88 giây <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "You Go First" · 1:59 · tạo trong 74 giây <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lời của chính chúng tôi và một đề bài phong cách deep house ở 121 BPM, trên cả năm model ([vòng 5](/docs/articles/ai-music-flagships-compared#round-5-deep-house)): ACE Music v1 — "Two shadows in a velvet" · 1:53 · tạo trong 52 giây <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Low Light" · 3:09 · tạo trong 101 giây <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Velvet Room" · 2:26 · tạo trong 43 giây <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> TemPolor v4.8 — "Low Light" · 1:28 · tạo trong 51 giây <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-tempolor-v4.8.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music 3.0 — "Low Light" · 2:47 · tạo trong 135 giây <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Một bản song ca nam nữ trên nền jazzy house, với vai của từng giọng được ghi ngay trong lời ([vòng 6](/docs/articles/ai-music-flagships-compared#round-6-jazzy-house-duet)): Mureka V9.5 — "Blue Hour" · 3:12 · tạo trong 70 giây <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Blue Hour" · 2:34 · tạo trong 58 giây <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Một bài hát ACE Music v1 thứ ba, viết từ bức ảnh một linh vật robot đang nhảy, phát cùng bức ảnh trong một [YouTube Short](https://youtube.com/shorts/z_aOmILvIng). Thêm nhiều bài khác, mỗi bài kèm request đã tạo ra nó, có trong [phần ví dụ của hướng dẫn ACE Music API](/docs/articles/ace-music-api-tutorial#examples). Bản nghe thử 15 phút trên YouTube phát 30 giây to nhất của cả 30 bản nhạc, năm mô hình trên sáu đề bài, có cả ACE Music v1, đã cân bằng âm lượng, kèm giá mỗi bài hát của từng dịch vụ tính đến tháng 11 năm 2026. Bảng so sánh giá đầy đủ nằm ở [Giá mỗi bài hát](#price-per-song). <div style="max-width:720px"> <div style="position:relative;width:100%;padding-top:56.25%;border-radius:8px;overflow:hidden"> <iframe src="https://www.youtube.com/embed/MSUGckk4JqU" title="Five AI music APIs on the same six briefs" style="position:absolute;top:0;left:0;width:100%;height:100%;border:0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen loading="lazy"></iframe> </div> </div> ### Bắt tay vào làm Kết nối tài khoản của bạn bằng [Setup ACE Music](/docs/start-here/setup-acemusic), [Setup Mureka](/docs/start-here/setup-mureka), [Setup Flow Music](/docs/start-here/setup-flowmusic), [Setup TemPolor](/docs/start-here/setup-tempolor) hoặc [Setup MiniMax](/docs/start-here/setup-minimax), rồi tạo một bài hát với [ACE Music POST music](/docs/api-acemusic-v1/post-acemusic-music), [Mureka POST music/create](/docs/api-mureka-v1/post-mureka-music-create), [Flow Music POST music](/docs/api-flowmusic-v1/post-flowmusic-music), [TemPolor POST music/song](/docs/api-tempolor-v1/post-tempolor-music-song) hoặc [MiniMax POST music/create](/docs/api-minimax-v1/post-minimax-music-create). Mỗi trang đều có code chạy được ngay, và các hướng dẫn [ACE Music](/docs/articles/ace-music-api-tutorial), [Mureka](/docs/articles/mureka-bash) và [Flow Music](/docs/articles/flowmusic-bash) đi qua từng bước tạo bài hát đầu tiên. [Ví dụ trên GitHub: useapi/acemusic-api](https://github.com/useapi/acemusic-api), [useapi/mureka-api](https://github.com/useapi/mureka-api) và [useapi/flowmusic-api](https://github.com/useapi/flowmusic-api) tạo bài hát bằng Node.js, thêm Python cho ACE Music [ACE Music MCP server](/docs/api-acemusic-v1/mcp) (15 công cụ), [Mureka MCP server](/docs/api-mureka-v1/mcp) (40 công cụ) và [Flow Music MCP server](/docs/api-flowmusic-v1/mcp) (18 công cụ) bài hát, stem và chỉnh sửa từ Claude Code, Cursor, VS Code và các MCP client khác ## Câu hỏi thường gặp ### Có giải pháp thay thế Suno API không? Qua useapi.net thì có: ACE Music v1, hạng 1 trên [bảng xếp hạng nhạc có giọng hát của Artificial Analysis](https://artificialanalysis.ai/music/leaderboard/vocals), trên cả Suno v6, cùng Mureka V9.5, Lyria 3.5 của Google, TemPolor v4.8 và MiniMax Music 3.0 tạo bài hát có giọng hát qua REST, từ một prompt hoặc lời của riêng bạn. API dành cho nhà phát triển của Suno là bản beta cho một số đối tác được chọn (tính đến tháng 11/2026). ### Một bài hát AI qua API giá bao nhiêu? Qua useapi.net, một bài hát ACE Music v1 tốn khoảng $0,013 trên ACE Music Artist trả theo năm, và một bài hát ACE-Step v1.5 XL không tốn gì, trong khi API của bên thứ ba acestep.io tính khoảng $0,14. Một bài hát MiniMax Music 3.0 tốn khoảng $0,01 trên MiniMax Audio Pro, so với $0,15 trên API của MiniMax, và một bài hát Lyria 3.5 khoảng $0,011 trên Flow Music Member, so với $0,08 trên Gemini API của Google (tính đến tháng 11/2026). Xem [Giá mỗi bài hát](#price-per-song). ### API nhạc AI có hát được bằng giọng của tôi không? Qua useapi.net thì có. Mureka biến khoảng 30 giây giọng hát của bạn thành một [character](/docs/api-mureka-v1/post-mureka-music-characters) dùng lại được mà không mất phí trên Mureka Premier, trong khi API chính thức của Mureka tính $5 mỗi giọng (tính đến tháng 11/2026). TemPolor nhân bản một giọng từ mẫu bạn upload bằng [POST music/cloned-voices](/docs/api-tempolor-v1/post-tempolor-music-cloned-voices) và hát bất kỳ bài nào bằng giọng đó, từ một prompt hoặc từ lời của riêng bạn. ### Tôi có lấy được stem và bản nhạc từ API nhạc AI không? Qua useapi.net, một bài hát Mureka tách được thành tối đa 12 stem kèm MIDI trên Mureka Premier với giá khoảng một phần năm mức $0,70 mà API chính thức của Mureka tính, và chuyển thành bản nhạc với giá $0,02 hoặc thấp hơn, so với $0,20 (tính đến tháng 11/2026). ACE Music xuất stem, MIDI và MusicXML trên Creator và Artist, mọi bài hát TemPolor đều tải về được dưới dạng file ZIP chứa stem, và Flow Music tách một bài hát Lyria thành trống, bass, giọng hát và phần còn lại. --- Giá trong bài viết này được ghi nhận vào tháng 11/2026, và các dịch vụ này thay đổi gói và mức giá mà không báo trước, nên hãy kiểm tra giá hiện hành trước khi chi tiền. ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/suno-api-alternative-zh === Document URL: https://useapi.net/docs/articles/suno-api-alternative-zh --- layout: default translation_key: suno-api-alternative title: "Suno API 替代方案:ACE Music、Mureka、Lyria 3.5、TemPolor 和 MiniMax" seo_title: "Suno API 替代方案:ACE Music、Mureka、Lyria、TemPolor、MiniMax" description: "通过 useapi.net 获得 Suno API 替代方案:ACE Music v1 在 Artificial Analysis 人声排行榜上排名第一,领先 Suno v6,另有 Mureka V9.5、Lyria 3.5、TemPolor 和 MiniMax,每首歌约 1 到 2 美分。" keywords: [Suno API alternative, Suno alternative API, ACE Music API, ACE Music v1 API, ACE-Step API, AI song generator API, AI song API with vocals, AI music API, AI music API pricing, song generation API, text to song API, Mureka API, Mureka V9.5 API, Lyria 3.5 API, Flow Music API, Lyria API pricing, TemPolor API, TemPolor v4.8 API, MiniMax Music API, MiniMax Music 3.0 API, MiniMax music API pricing, Suno API 替代, Suno 替代方案, AI 歌曲生成 API, AI 音乐 API, AI 音乐 API 价格, 文本生成歌曲, 带人声的 AI 歌曲, 中文教程, Chinese tutorial] image: /assets/images/articles/ai-music-flagships-compared.jpg video: name: "五个 AI 音乐 API,同样的六个创作要求" description: "ACE Music v1、TemPolor v4.8 和 i4、MiniMax Music-3.0、Google Lyria 3.5 和 Mureka V9.5 使用完全相同的六个创作要求:每首曲目最响的 30 秒,响度已统一,屏幕上显示提示词、价格和生成耗时。" embed: https://www.youtube.com/embed/MSUGckk4JqU thumbnail: https://i.ytimg.com/vi/MSUGckk4JqU/maxresdefault.jpg date: 2026-11-14 duration: PT15M width: 1920 height: 1080 parent: Articles nav_exclude: true lang: zh-CN date: 2026-10-20 last_modified: 2026-11-18 nav_order: 906 --- ## Suno API 替代方案:ACE Music、Mureka、Lyria 3.5、TemPolor 和 MiniMax {: .no_toc #suno-api-alternative-ace-music-mureka-lyria-35-tempolor-and-minimax } 7 分钟阅读 • 2026 年 10 月 20 日(2026 年 11 月 18 日更新) ## 目录 {: .no_toc .text-delta #table-of-contents } ### 简介 通过 useapi.net,在 [Artificial Analysis 人声音乐排行榜](https://artificialanalysis.ai/music/leaderboard/vocals)上排名第一、领先 Suno v6 的 ACE Music v1,可以用你的 [ACE Music](https://acemusic.ai/pricing/) 订阅通过 REST 生成完整的歌曲。另外四个带人声的歌曲模型也以同样的方式运行:同样位列该排行榜前六的 Mureka V9.5 和 Google 的 Lyria 3.5,以及 TemPolor v4.8 和 MiniMax Music 3.0,分别使用你的 [Mureka](https://www.mureka.ai/subscribe)、[Flow Music](https://www.flowmusic.app/pricing)、[TemPolor](https://www.tempolor.com/pricing) 或 [MiniMax Audio](https://www.minimax.io/audio/subscribe) 网站订阅。Suno 自己的开发者 API 只是面向特定合作伙伴的测试版,没有公开的文档和价目表(截至 2026 年 11 月)。useapi.net 是[第三方](/docs/legal#affiliation--third-party-services)服务,与 Suno、Timedomain、昆仑万维、Google、Qustar Technology 和 MiniMax 均无关联。 ### 每首歌的价格 下表列出一首带人声的歌曲在各家官方 API 上的价格([Mureka](https://platform.mureka.ai/pricing)、Google 的 [Gemini API](https://ai.google.dev/gemini-api/docs/pricing)、[TemPolor](https://platform.tempolor.com/docs/6665893m0)、[MiniMax](https://platform.minimax.io/docs/pricing/overview#about-music-models),2026 年 8 月 20 日起不对新用户开放),以及在各家网站订阅上的价格(2026 年 11 月)。每个订阅每月附带一定数量的积分,每首歌消耗固定数量的积分,所以一首歌的价格就是它所占的订阅费份额。 | 模型 | 官方 API | 网站月度订阅 | 每首价格 | |---|---|---|---| | ACE Music v1 | — | ACE Music Creator $9.90 (每月 1,000 积分) | 2 美分 / 2 积分 (每月 500 首) | | ACE Music v1 | — | ACE Music Artist $29 (每月 2,500 积分) | 2.3 美分 / 2 积分 (每月 1,250 首) | | ACE-Step v1.5 XL (10 到 240 秒,仅 MP3) | — (开源) | 任何 ACE Music 套餐 (包括免费套餐) | $0 / 0 积分 (不消耗积分) | | Mureka V9.5 | 15 美分 (预付 $1,000 起) | Mureka Pro $10 (每月 5,000 积分) | 2.4 美分 / 12 积分 (每月 416 首) | | Mureka V9.5 | 15 美分 (预付 $1,000 起) | Mureka Premier $30 (每月 20,000 积分) | 1.8 美分 / 12 积分 (每月 1,666 首) | | Lyria 3.5 | 8 美分 (每首) | Flow Music Starter $8 (每月 3,000 积分) | 1.3 美分 / 5 积分 (每月 600 首) | | Lyria 3.5 | 8 美分 (每首) | Flow Music Member $64 (每月 30,000 积分) | 1.1 美分 / 5 积分 (每月 6,000 首) | | TemPolor v4.8 | 4 美分 (每次调用,预付 $100 起) | TemPolor Ultra $29.99 | $0 / 0 积分 (不按首收费) | | MiniMax Music 3.0 | 15 美分 (2026 年 8 月 20 日起不对新用户开放) | MiniMax Audio Pro $99 (每月 3,000,000 积分) | 1 美分 / 300 积分 (每月 10,000 首) | - ACE Music Artist 按年付费为每月 $16.58,一首 ACE Music v1 歌曲约合 1.3 美分。免费套餐每天的 20 积分可生成约 10 首歌,仅限个人使用,商用权随 Creator 和 Artist 套餐提供。 - [ACE-Step](https://ace-step.github.io) v1.5 XL 是 ACE Studio 和 StepFun 推出的开源模型,可设定速度(`bpm`)、调性(`key`)和拍号(`timeSignature`)。它在任何 ACE Music 套餐上都不消耗积分,免费套餐也一样;而第三方 acestep.io 每首收费约 14 美分,且它的 API 需要每月 $49 的 Studio 套餐。 - 由模型根据提示词写歌词时,Mureka 的 API 收费 50 美分而不是 15 美分,MiniMax 和 TemPolor 的 API 各加收 1 美分;通过 useapi.net,两种方式的价格相同。 - TemPolor 的 API 积分在任何套餐规模下单价都一样,所以用量再大也不会更便宜。 - Flow Music Member 按年付费为每月 $48,一首 Lyria 歌曲约合 0.8 美分。 - Google AI 订阅包含一个 Flow Music 套餐,其积分与 Google AI 积分分开计算:[Google AI Plus](https://support.google.com/googleone/answer/16882689?hl=zh-CN) 包含 Starter,[Google AI Pro](https://support.google.com/googleone/answer/14534406?hl=zh-CN) 包含 Plus,[Google AI Ultra](https://support.google.com/googleone/answer/16286513?hl=zh-CN) 包含 Member。 - 如果你有多个订阅,一个 useapi.net 令牌就能同时使用它们,并自动把歌曲分配到各个订阅上。 ### 各模型的功能 - ACE Music v1,通过 [ACE Music API](/docs/api-acemusic-v1):每个请求根据提示词或你自己的风格和歌词生成两首歌,可演唱也可纯音乐,时长 30 秒到 10 分钟。ACE Music v1.1 Preview 能制作跟随原曲旋律的[翻唱和混搭](/docs/api-acemusic-v1/post-acemusic-music#modes),你[上传](/docs/api-acemusic-v1/post-acemusic-files)的歌曲和图片可以引导新歌;在 Creator 和 Artist 套餐上,歌曲还能拆分为[分轨](/docs/api-acemusic-v1/post-acemusic-music-stems),并以 WAV、MIDI 或 MusicXML 格式[下载](/docs/api-acemusic-v1/get-acemusic-music-download)。免费的 ACE-Step v1.5 XL 另外提供重混、编辑,以及设定速度、调性和拍号。每个账号最多同时运行 4 个请求。 - Mureka V9.5,通过 [Mureka API](/docs/api-mureka-v1):每次调用生成两首歌,最长 5 分钟,可以根据一句话提示词,也可以根据你的歌词加风格。在 Mureka Premier 上,它能通过可复用的[角色](/docs/api-mureka-v1/post-mureka-music-characters)用你自己的声音演唱,并把歌曲拆分为[分轨](/docs/api-mureka-v1/post-mureka-music-stems)和 MIDI。它还能把歌曲写成 MusicXML 和 PDF 格式的[乐谱](/docs/articles/mureka-sheet-music),把歌曲[重混](/docs/api-mureka-v1/post-mureka-music-remix)成新风格、延长歌曲和编辑段落,每个账号最多同时运行 10 个生成。 - Lyria 3.5,通过驱动 [Google Flow Music](https://www.flowmusic.app) 的 [Flow Music API](/docs/api-flowmusic-v1):每次调用生成一对 A/B 歌曲,格式为 WAV、mp3 或 m4a。[POST music/edit](/docs/api-flowmusic-v1/post-flowmusic-music-edit) 在同一个套餐上提供翻唱、歌词重混、最长 300 秒的延长、段落替换、音频效果和四轨分离。请传入 `model="lyria-3.5"`,因为 API 的默认值仍是 `lyria-3-pro`。付费套餐可同时运行 8 到 16 个生成。 - TemPolor v4.8,通过 [TemPolor API](/docs/api-tempolor-v1):根据提示词或你自己的歌词生成最长 5 分钟的歌曲,支持 30 多种语言,可由[克隆的声音](/docs/api-tempolor-v1/post-tempolor-music-cloned-voices)或它的一位艺人声音演唱,也可以基于你上传的 [MIDI 文件](/docs/api-tempolor-v1/post-tempolor-music-midi)创作。每首歌都能以 mp3、wav 或分轨 ZIP 格式[下载](/docs/api-tempolor-v1/get-tempolor-music-download-job_id),[music/stems-splitter](/docs/api-tempolor-v1/post-tempolor-music-stems-splitter) 能拆分你自己的音频,[music/instrumental](/docs/api-tempolor-v1/post-tempolor-music-instrumental) 用 i4 模型生成无人声的曲目。最多同时运行 10 个生成。 - MiniMax Music 3.0,通过 [MiniMax API](/docs/api-minimax-v1/post-minimax-music-create):每次调用根据风格提示词和你的歌词(或由它自己写的歌词)生成一到三首歌,还能生成纯音乐,以及基于[参考曲目](/docs/api-minimax-v1/post-minimax-music-reference)的翻唱。歌曲以 256 kbps MP3 返回,使用 `stream: true` 时可以边生成边播放。 ### 先听一听 下面每首曲目都是完整、未经剪辑的,来源页面里都附有生成它的 API 调用。 所有曲目都来自我们[在同样六个创作要求上对这些模型的比较](/docs/articles/ai-music-flagships-compared),ACE Music v1 于 2026 年 11 月 14 日加入另外四个模型的行列。Lyria 曲目已从 API 返回的 WAV 转码为 MP3,以便浏览器播放;每首 ACE Music v1 曲目都是 ACE Music 每个请求生成的两首歌中的第一首。 一句话提示词,由模型写歌词:*"A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."*([第 3 轮](/docs/articles/ai-music-flagships-compared#round-3-pop-duet)) ACE Music v1 — "Three Dot Bubbles" · 0:41 · 生成耗时 54 秒 <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Are You Still Awake?" · 3:05 · 生成耗时 88 秒 <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "You Go First" · 1:59 · 生成耗时 74 秒 <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> 我们自己写的歌词和 121 BPM 的 deep house 风格要求,在全部五个模型上运行([第 5 轮](/docs/articles/ai-music-flagships-compared#round-5-deep-house)): ACE Music v1 — "Two shadows in a velvet" · 1:53 · 生成耗时 52 秒 <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Low Light" · 3:09 · 生成耗时 101 秒 <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Velvet Room" · 2:26 · 生成耗时 43 秒 <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> TemPolor v4.8 — "Low Light" · 1:28 · 生成耗时 51 秒 <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-tempolor-v4.8.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music 3.0 — "Low Light" · 2:47 · 生成耗时 135 秒 <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> 一首男女对唱的 jazzy house,人声分工写在歌词里([第 6 轮](/docs/articles/ai-music-flagships-compared#round-6-jazzy-house-duet)): Mureka V9.5 — "Blue Hour" · 3:12 · 生成耗时 70 秒 <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Blue Hour" · 2:34 · 生成耗时 58 秒 <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> 第三首 ACE Music v1 歌曲是根据一张跳舞机器人吉祥物的照片写的,可以在一个 [YouTube Short](https://youtube.com/shorts/z_aOmILvIng) 中配着照片收听。更多歌曲及生成它们的请求,见我们 [ACE Music API 教程的示例](/docs/articles/ace-music-api-tutorial#examples)。 YouTube 上 15 分钟的试听剪辑播放了全部 30 首曲目中各自最响的 30 秒,即五个模型、六个创作要求,包含 ACE Music v1,响度已统一,并显示各服务截至 2026 年 11 月的每首歌价格。完整的价格比较见[每首歌的价格](#price-per-song)。 <div style="max-width:720px"> <div style="position:relative;width:100%;padding-top:56.25%;border-radius:8px;overflow:hidden"> <iframe src="https://www.youtube.com/embed/MSUGckk4JqU" title="Five AI music APIs on the same six briefs" style="position:absolute;top:0;left:0;width:100%;height:100%;border:0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen loading="lazy"></iframe> </div> </div> ### 开始构建 先用 [Setup ACE Music](/docs/start-here/setup-acemusic)、[Setup Mureka](/docs/start-here/setup-mureka)、[Setup Flow Music](/docs/start-here/setup-flowmusic)、[Setup TemPolor](/docs/start-here/setup-tempolor) 或 [Setup MiniMax](/docs/start-here/setup-minimax) 连接你的账号,然后用 [ACE Music POST music](/docs/api-acemusic-v1/post-acemusic-music)、[Mureka POST music/create](/docs/api-mureka-v1/post-mureka-music-create)、[Flow Music POST music](/docs/api-flowmusic-v1/post-flowmusic-music)、[TemPolor POST music/song](/docs/api-tempolor-v1/post-tempolor-music-song) 或 [MiniMax POST music/create](/docs/api-minimax-v1/post-minimax-music-create) 生成歌曲。每个页面都有可直接运行的代码,[ACE Music](/docs/articles/ace-music-api-tutorial)、[Mureka](/docs/articles/mureka-bash) 和 [Flow Music](/docs/articles/flowmusic-bash) 教程会带你完成第一首歌。 [GitHub 示例:useapi/acemusic-api](https://github.com/useapi/acemusic-api)、[useapi/mureka-api](https://github.com/useapi/mureka-api) 和 [useapi/flowmusic-api](https://github.com/useapi/flowmusic-api) Node.js 歌曲生成,ACE Music 另有 Python [ACE Music MCP 服务器](/docs/api-acemusic-v1/mcp)(15 个工具)、[Mureka MCP 服务器](/docs/api-mureka-v1/mcp)(40 个工具)和 [Flow Music MCP 服务器](/docs/api-flowmusic-v1/mcp)(18 个工具) 在 Claude Code、Cursor、VS Code 和其他 MCP 客户端中生成歌曲、分轨和编辑 ## 常见问题 ### 有 Suno API 的替代方案吗? 通过 useapi.net 就有:在 [Artificial Analysis 人声音乐排行榜](https://artificialanalysis.ai/music/leaderboard/vocals)上排名第一、领先 Suno v6 的 ACE Music v1,以及 Mureka V9.5、Google 的 Lyria 3.5、TemPolor v4.8 和 MiniMax Music 3.0,都能通过 REST 根据提示词或你自己的歌词生成带人声的歌曲。Suno 的开发者 API 只是面向特定合作伙伴的测试版(截至 2026 年 11 月)。 ### 通过 API 生成一首 AI 歌曲要多少钱? 通过 useapi.net,在按年付费的 ACE Music Artist 上,一首 ACE Music v1 歌曲约 1.3 美分,一首 ACE-Step v1.5 XL 歌曲不花钱,而第三方 acestep.io 的 API 每首约收 14 美分。在 MiniMax Audio Pro 上,一首 MiniMax Music 3.0 歌曲约 1 美分,MiniMax 的 API 则要 15 美分;在 Flow Music Member 上,一首 Lyria 3.5 歌曲约 1.1 美分,Google 的 Gemini API 则要 8 美分(截至 2026 年 11 月)。见[每首歌的价格](#price-per-song)。 ### AI 音乐 API 能用我自己的声音演唱吗? 通过 useapi.net 可以。在 Mureka Premier 上,Mureka 能把你约 30 秒的演唱免费做成一个可复用的[角色](/docs/api-mureka-v1/post-mureka-music-characters),而 Mureka 官方 API 每个声音收费 $5(截至 2026 年 11 月)。TemPolor 用 [POST music/cloned-voices](/docs/api-tempolor-v1/post-tempolor-music-cloned-voices) 从上传的样本克隆声音,并用它演唱任何歌曲,可以根据提示词,也可以根据你自己的歌词。 ### 能从 AI 音乐 API 获得分轨和乐谱吗? 通过 useapi.net,在 Mureka Premier 上,一首 Mureka 歌曲可拆分为最多 12 条分轨加 MIDI,费用约为 Mureka 官方 API 收费 70 美分的五分之一;转成乐谱只需 2 美分或更少,官方 API 则要 20 美分(截至 2026 年 11 月)。ACE Music 在 Creator 和 Artist 套餐上可导出分轨、MIDI 和 MusicXML,每首 TemPolor 歌曲都能下载分轨 ZIP,Flow Music 能把 Lyria 歌曲拆分为鼓、贝斯、人声和其他。 --- 本文中的价格读取于 2026 年 11 月,这些服务会随时更改套餐和价格,恕不另行通知,所以在投入费用之前请先确认实时价格。 ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/suno-api-alternative === Document URL: https://useapi.net/docs/articles/suno-api-alternative --- layout: default translation_key: suno-api-alternative title: "Suno API Alternative: ACE Music, Mureka, Lyria 3.5, TemPolor and MiniMax" seo_title: "Suno API Alternative: ACE Music, Mureka, Lyria, TemPolor, MiniMax" description: "Suno API alternative via useapi.net: ACE Music v1, #1 on Artificial Analysis' vocal leaderboard ahead of Suno v6, plus Mureka V9.5, Lyria 3.5, TemPolor and MiniMax, about 1 to 2 cents a song." keywords: [Suno API alternative, Suno alternative API, ACE Music API, ACE Music v1 API, ACE-Step API, AI song generator API, AI song API with vocals, AI music API, AI music API pricing, song generation API, text to song API, Mureka API, Mureka V9.5 API, Lyria 3.5 API, Flow Music API, Lyria API pricing, TemPolor API, TemPolor v4.8 API, MiniMax Music API, MiniMax Music 3.0 API, MiniMax music API pricing] image: /assets/images/articles/ai-music-flagships-compared.jpg video: name: "Five AI music APIs on the same six briefs" description: "ACE Music v1, TemPolor v4.8 and i4, MiniMax Music-3.0, Google Lyria 3.5 and Mureka V9.5 on the identical six briefs — each track's loudest 30 seconds, loudness-matched, with the prompt, price and generation time on screen." embed: https://www.youtube.com/embed/MSUGckk4JqU thumbnail: https://i.ytimg.com/vi/MSUGckk4JqU/maxresdefault.jpg date: 2026-11-14 duration: PT15M width: 1920 height: 1080 parent: Articles nav_exclude: true date: 2026-10-20 last_modified: 2026-11-18 nav_order: 906 --- ## Suno API Alternative: ACE Music, Mureka, Lyria 3.5, TemPolor and MiniMax 7 min read • October 20, 2026 (November 18, 2026) ## Table of contents ### Introduction Through useapi.net, ACE Music v1, which ranks #1 on [Artificial Analysis' vocal music leaderboard](https://artificialanalysis.ai/music/leaderboard/vocals) ahead of Suno v6, makes full songs over REST on your [ACE Music](https://acemusic.ai/pricing/) subscription. Four more song models with vocals run the same way: Mureka V9.5 and Google's Lyria 3.5, both in the top six of that leaderboard, TemPolor v4.8 and MiniMax Music 3.0, on your [Mureka](https://www.mureka.ai/subscribe), [Flow Music](https://www.flowmusic.app/pricing), [TemPolor](https://www.tempolor.com/pricing) or [MiniMax Audio](https://www.minimax.io/audio/subscribe) website subscription. Suno's own developer API is a beta for selected partners, with no public documentation or price list (as of November 2026). useapi.net is a [third-party](/docs/legal#affiliation--third-party-services) service, not affiliated with Suno, Timedomain, Kunlun Tech, Google, Qustar Technology or MiniMax. ### Price per song What one song with vocals costs on each maker's official API ([Mureka](https://platform.mureka.ai/pricing), Google's [Gemini API](https://ai.google.dev/gemini-api/docs/pricing), [TemPolor](https://platform.tempolor.com/docs/6665893m0), [MiniMax](https://platform.minimax.io/docs/pricing/overview#about-music-models), closed to new users since August 20, 2026) and on each website subscription (November 2026). Each subscription comes with a monthly number of credits, and each song uses a set number of them, so a song costs its share of the subscription. | Model | Official API | Website monthly subscription | Price per song | |---|---|---|---| | ACE Music v1 | — | ACE Music Creator $9.90 (1,000 cr/mo) | 2¢ / 2 cr (500 songs/mo) | | ACE Music v1 | — | ACE Music Artist $29 (2,500 cr/mo) | 2.3¢ / 2 cr (1,250 songs/mo) | | ACE-Step v1.5 XL (10 to 240 s, MP3 only) | — (open source) | Any ACE Music plan (the Free plan included) | $0 / 0 cr (no credits) | | Mureka V9.5 | 15¢ (prepaid from $1,000) | Mureka Pro $10 (5,000 cr/mo) | 2.4¢ / 12 cr (416 songs/mo) | | Mureka V9.5 | 15¢ (prepaid from $1,000) | Mureka Premier $30 (20,000 cr/mo) | 1.8¢ / 12 cr (1,666 songs/mo) | | Lyria 3.5 | 8¢ (per song) | Flow Music Starter $8 (3,000 cr/mo) | 1.3¢ / 5 cr (600 songs/mo) | | Lyria 3.5 | 8¢ (per song) | Flow Music Member $64 (30,000 cr/mo) | 1.1¢ / 5 cr (6,000 songs/mo) | | TemPolor v4.8 | 4¢ (a call, prepaid from $100) | TemPolor Ultra $29.99 | $0 / 0 cr (no per-song charge) | | MiniMax Music 3.0 | 15¢ (closed to new users since August 20, 2026) | MiniMax Audio Pro $99 (3,000,000 cr/mo) | 1¢ / 300 cr (10,000 songs/mo) | - Billed yearly, ACE Music Artist is $16.58 a month, which brings an ACE Music v1 song to about 1.3¢. The Free plan's 20 daily credits make about 10 songs a day for personal use, and commercial rights come with Creator and Artist. - [ACE-Step](https://ace-step.github.io) v1.5 XL is the open-source model by ACE Studio and StepFun, with a set tempo (`bpm`), `key` and `timeSignature`. It uses no credits on any ACE Music plan, the Free plan included, where the third-party acestep.io charges about 14¢ a song through an API that needs its $49 a month Studio plan. - When the model writes the lyrics from a prompt, Mureka's API charges 50¢ instead of 15¢, and MiniMax's and TemPolor's add 1¢, while a song costs the same either way through useapi.net. - TemPolor's API credits cost the same at every package size, so volume never lowers its price. - Billed yearly, Flow Music Member is $48 a month, which brings a Lyria song to about 0.8¢. - Google AI subscriptions include a Flow Music plan, with credits separate from the Google AI credits: Starter on [Google AI Plus](https://support.google.com/googleone/answer/16882689), Plus on [Google AI Pro](https://support.google.com/googleone/answer/14534406) and Member on [Google AI Ultra](https://support.google.com/googleone/answer/16286513). - With more than one subscription, one useapi.net token works with all of them and spreads your songs across them automatically. ### What each one does - ACE Music v1, through the [ACE Music API](/docs/api-acemusic-v1): two songs per request from a prompt or your own style and lyrics, sung or instrumental, from 30 seconds to 10 minutes long. ACE Music v1.1 Preview makes [covers and mashups](/docs/api-acemusic-v1/post-acemusic-music#modes) that follow a song's melody, your [uploaded](/docs/api-acemusic-v1/post-acemusic-files) songs and pictures guide new ones, and on Creator and Artist its songs split into [stems](/docs/api-acemusic-v1/post-acemusic-music-stems) and [downloads](/docs/api-acemusic-v1/get-acemusic-music-download) as WAV, MIDI or MusicXML. The free ACE-Step v1.5 XL adds remixes, edits and a set tempo, key and meter. Each account runs up to 4 requests at once. - Mureka V9.5, through the [Mureka API](/docs/api-mureka-v1): two songs per call, up to 5 minutes long, from a one-line prompt or from your lyrics plus a style. On Mureka Premier it sings in your own voice through a reusable [character](/docs/api-mureka-v1/post-mureka-music-characters) and splits a song into [stems](/docs/api-mureka-v1/post-mureka-music-stems) plus MIDI. It also writes [sheet music](/docs/articles/mureka-sheet-music) as MusicXML and PDF, [remixes](/docs/api-mureka-v1/post-mureka-music-remix) a song into a new style, extends it and edits sections, up to 10 generations at once per account. - Lyria 3.5, through the [Flow Music API](/docs/api-flowmusic-v1), which drives [Google Flow Music](https://www.flowmusic.app): an A/B pair per call, as WAV, mp3 or m4a. [POST music/edit](/docs/api-flowmusic-v1/post-flowmusic-music-edit) makes covers, lyric remixes, extends of up to 300 seconds, section replacements, audio effects and a four-stem split from the same plan. Pass `model="lyria-3.5"`, because the API keeps `lyria-3-pro` as its default. Paid plans run 8 to 16 generations at once. - TemPolor v4.8, through the [TemPolor API](/docs/api-tempolor-v1): songs up to 5 minutes in more than 30 languages from a prompt or your own lyrics, sung by a [cloned voice](/docs/api-tempolor-v1/post-tempolor-music-cloned-voices) or one of its artist voices, or built on a [MIDI file](/docs/api-tempolor-v1/post-tempolor-music-midi) you upload. Every song [downloads](/docs/api-tempolor-v1/get-tempolor-music-download-job_id) as mp3, wav or a stems ZIP, [music/stems-splitter](/docs/api-tempolor-v1/post-tempolor-music-stems-splitter) splits your own audio, and [music/instrumental](/docs/api-tempolor-v1/post-tempolor-music-instrumental) runs the i4 model for tracks without vocals. Up to 10 generations run at once. - MiniMax Music 3.0, through the [MiniMax API](/docs/api-minimax-v1/post-minimax-music-create): one to three songs per call from a style prompt and your lyrics, or lyrics it writes itself, plus instrumentals and covers of a [reference track](/docs/api-minimax-v1/post-minimax-music-reference). Songs come back as 256 kbps MP3, and with `stream: true` the audio plays while it renders. ### Listen first Every track below is complete and unedited, and the page each one comes from shows the API call behind it. All of them come from our [comparison of these models on the same six briefs](/docs/articles/ai-music-flagships-compared), where ACE Music v1 joined the other four on November 14, 2026. The Lyria tracks are transcoded from the API's WAV to MP3 so a browser can play them, and each ACE Music v1 track is the first of the two songs ACE Music makes per request. A one-sentence prompt, the model writes the lyrics: *"A playful pop duet between a male and a female singer about texting too late at night, around 60 seconds, catchy back-and-forth chorus."* ([round 3](/docs/articles/ai-music-flagships-compared#round-3-pop-duet)) ACE Music v1 — "Three Dot Bubbles" · 0:41 · generated in 54 s <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Are You Still Awake?" · 3:05 · generated in 88 s <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "You Go First" · 1:59 · generated in 74 s <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/03-pop-duet-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Our own lyrics and a deep-house style brief at 121 BPM, on all five models ([round 5](/docs/articles/ai-music-flagships-compared#round-5-deep-house)): ACE Music v1 — "Two shadows in a velvet" · 1:53 · generated in 52 s <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-acemusic-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Mureka V9.5 — "Low Light" · 3:09 · generated in 101 s <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Velvet Room" · 2:26 · generated in 43 s <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> TemPolor v4.8 — "Low Light" · 1:28 · generated in 51 s <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-tempolor-v4.8.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> MiniMax Music 3.0 — "Low Light" · 2:47 · generated in 135 s <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/05-low-light-minimax-music-3.0.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> A male and female duet over jazzy house, with the voice roles written into the lyrics ([round 6](/docs/articles/ai-music-flagships-compared#round-6-jazzy-house-duet)): Mureka V9.5 — "Blue Hour" · 3:12 · generated in 70 s <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-mureka-v9.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Lyria 3.5 — "Blue Hour" · 2:34 · generated in 58 s <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-08-19-ai-music-flagships-compared/06-blue-hour-google-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> A third ACE Music v1 song, written from a photo of a dancing robot mascot, plays with the photo in a [YouTube Short](https://youtube.com/shorts/z_aOmILvIng). More, each with the request that made it, are in the [examples of our ACE Music API tutorial](/docs/articles/ace-music-api-tutorial#examples). The 15-minute listening cut on YouTube plays the loudest 30 seconds of all 30 tracks, five models on six briefs with ACE Music v1 included, loudness-matched, with each service's price per song as of November 2026. The full price comparison is in [Price per song](#price-per-song). <div style="max-width:720px"> <div style="position:relative;width:100%;padding-top:56.25%;border-radius:8px;overflow:hidden"> <iframe src="https://www.youtube.com/embed/MSUGckk4JqU" title="Five AI music APIs on the same six briefs" style="position:absolute;top:0;left:0;width:100%;height:100%;border:0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen loading="lazy"></iframe> </div> </div> ### Build it Connect your account with [Setup ACE Music](/docs/start-here/setup-acemusic), [Setup Mureka](/docs/start-here/setup-mureka), [Setup Flow Music](/docs/start-here/setup-flowmusic), [Setup TemPolor](/docs/start-here/setup-tempolor) or [Setup MiniMax](/docs/start-here/setup-minimax), then make a song with [ACE Music POST music](/docs/api-acemusic-v1/post-acemusic-music), [Mureka POST music/create](/docs/api-mureka-v1/post-mureka-music-create), [Flow Music POST music](/docs/api-flowmusic-v1/post-flowmusic-music), [TemPolor POST music/song](/docs/api-tempolor-v1/post-tempolor-music-song) or [MiniMax POST music/create](/docs/api-minimax-v1/post-minimax-music-create). Each page has ready-to-run code, and the [ACE Music](/docs/articles/ace-music-api-tutorial), [Mureka](/docs/articles/mureka-bash) and [Flow Music](/docs/articles/flowmusic-bash) tutorials walk through a first song. [GitHub examples: useapi/acemusic-api](https://github.com/useapi/acemusic-api), [useapi/mureka-api](https://github.com/useapi/mureka-api) and [useapi/flowmusic-api](https://github.com/useapi/flowmusic-api) Node.js song generation, plus Python for ACE Music [ACE Music MCP server](/docs/api-acemusic-v1/mcp) (15 tools), [Mureka MCP server](/docs/api-mureka-v1/mcp) (40 tools) and [Flow Music MCP server](/docs/api-flowmusic-v1/mcp) (18 tools) songs, stems and edits from Claude Code, Cursor, VS Code and other MCP clients ## Questions ### Is there a Suno API alternative? Through useapi.net, yes: ACE Music v1, #1 on [Artificial Analysis' vocal music leaderboard](https://artificialanalysis.ai/music/leaderboard/vocals) ahead of Suno v6, plus Mureka V9.5, Google's Lyria 3.5, TemPolor v4.8 and MiniMax Music 3.0 make songs with vocals over REST, from a prompt or your own lyrics. Suno's developer API is a beta for selected partners (as of November 2026). ### How much does an AI song cost through an API? Through useapi.net, an ACE Music v1 song costs about 1.3 cents on ACE Music Artist billed yearly, and an ACE-Step v1.5 XL song nothing, where the third-party acestep.io API charges about 14 cents. A MiniMax Music 3.0 song costs about 1 cent on MiniMax Audio Pro, against 15 cents on MiniMax's API, and a Lyria 3.5 song about 1.1 cents on Flow Music Member, against 8 cents on Google's Gemini API (as of November 2026). See [Price per song](#price-per-song). ### Can an AI music API sing in my own voice? Through useapi.net, yes. Mureka turns about 30 seconds of your singing into a reusable [character](/docs/api-mureka-v1/post-mureka-music-characters) at no charge on Mureka Premier, where Mureka's official API charges $5 per voice (as of November 2026). TemPolor clones a voice from an uploaded sample with [POST music/cloned-voices](/docs/api-tempolor-v1/post-tempolor-music-cloned-voices) and sings any song in it, from a prompt or from your own lyrics. ### Can I get stems and sheet music from an AI music API? Through useapi.net, a Mureka song splits into up to 12 stems plus MIDI on Mureka Premier for about a fifth of the 70 cents Mureka's official API charges, and becomes sheet music for 2 cents or less against 20 cents (as of November 2026). ACE Music exports stems, MIDI and MusicXML on Creator and Artist, every TemPolor song downloads as a stems ZIP, and Flow Music splits a Lyria song into drums, bass, vocals and other. --- Prices in this article were read in November 2026, and these services change plans and rates without notice, so check the live price before you commit spend. ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/docs/articles/veo-3-1-api-pricing === Document URL: https://useapi.net/docs/articles/veo-3-1-api-pricing --- layout: default title: "Veo 3.1 API Pricing: Official Google Veo API vs Google Flow API" seo_title: "Veo 3.1 API Pricing: Official Veo API vs Google Flow API" description: "Veo 3.1 API pricing: an 8-second Fast, Quality or Lite video on Google's own Veo API vs Google AI Pro or Ultra through the useapi.net Google Flow API." keywords: [Veo 3.1 API pricing, Veo 3.1 API cost, Veo 3.1 Fast API pricing, Veo 3.1 Lite API pricing, Veo 3 API cost per video, Google Veo API pricing, Gemini Veo API pricing, cheap Veo 3 API, Veo 3.1 Gemini API shutdown, Veo 3.1 Agent Platform, Vertex AI Veo pricing, Google Flow API, Google AI Ultra, Flow credits] image: /assets/images/articles/veo-3-1-api-pricing-2026-10.jpg parent: Articles nav_exclude: true date: 2026-10-20 last_modified: 2026-11-06 nav_order: 806 repo: https://github.com/useapi/google-flow-api --- ## Veo 3.1 API Pricing: Official Google Veo API vs Google Flow API 4 min read • October 20, 2026 (November 6, 2026) ## Table of contents ### Introduction Through the useapi.net [Google Flow API](/docs/api-google-flow-v1), Veo 3.1 runs on your [Google Flow](https://flow.google.com) website subscription ([Google AI Pro or Ultra](https://gemini.google/subscriptions/)), so you pay the subscription and nothing per second. ### Price per video What one 8-second 720p Veo 3.1 video with sound costs on Google's own Veo API, [Agent Platform](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing) on Google Cloud, priced per second ("per count" there), and on each Google Flow subscription. Each Google Flow subscription comes with a monthly number of credits, and each video uses a set number of them, so a video costs its share of the subscription. | Model | [Official API](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing) | Ultra $199.99/m (25,000 cr/mo) | Ultra $99.99/m (10,000 cr/mo) | Pro $19.99/m (1,000 cr/mo) | |---|---|---|---|---| | Veo 3.1 Fast (720p, 8s) | $0.80 ($0.10 a second) | $0.08 / 10 cr (2,500 videos/mo) | $0.10 / 10 cr (1,000 videos/mo) | $0.40 / 20 cr (50 videos/mo) | | Veo 3.1 Quality (720p, 8s) | $3.20 ($0.40 a second) | $0.80 / 100 cr (250 videos/mo) | $1.00 / 100 cr (100 videos/mo) | $2.00 / 100 cr (10 videos/mo) | | Veo 3.1 Lite (720p, 8s) | $0.40 ($0.05 a second) | $0.04 / 5 cr (5,000 videos/mo) | $0.05 / 5 cr (2,000 videos/mo) | $0.20 / 10 cr (100 videos/mo) | | Veo 3.1 Lite (lower priority, 720p, 8s) | — | $0 / 0 cr (about 1,000 or more videos a day) | — | — | - 1080p costs nothing extra on Google Flow with a paid subscription ([upscale](/docs/api-google-flow-v1/post-google-flow-videos-upscale)), while the official Veo API charges $0.96 for a 1080p Fast video. - 4K upscaling on Ultra costs 50 credits ($0.50 on Ultra $99.99), so a 4K Fast video comes to $0.60 and a 4K Quality video $1.50, against $2.40 and $4.80 on the official Veo API. - With more than one subscription, one useapi.net token works with all of them and spreads your videos across them automatically. - Prices are US prices from Google's [subscription page](https://gemini.google/subscriptions/) and its [Flow credits page](https://support.google.com/flow/answer/16526234). ### Google's own Veo API Google's own Veo API is [Agent Platform](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing) on Google Cloud (formerly Vertex AI), and it needs a Google Cloud project with billing. The Gemini API no longer has Veo 3.1: Google [shut down its Veo 3.1 Preview models](https://ai.google.dev/gemini-api/docs/deprecations) on October 22, 2026. The Google Flow API runs Veo 3.1 on Google Flow with your Google AI subscription, with no Google Cloud project. Google's suggested replacement, [Omni Flash](/docs/articles/omni-flash-bash), runs there too: Omni 1.1 Flash on a paid Google AI subscription (Plus, Pro or Ultra), and Omni 1.2 Flash, released on November 5, 2026, on every plan, with videos of 3 to 15 seconds and extend in steps of up to 10 seconds. ### Examples Veo 3.1 videos made through the Google Flow API, from our release notes. To make your own, [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) has ready-to-run code, and the [Veo 3.1 tutorial](/docs/articles/google-flow-bash) walks through a first video. In our runs on October 20, 2026, an 8-second video took 50 to 105 seconds. ###### veo-3.1-fast » Lady and her dog, with AI voice narration From [Veo 3.1 Lite and Voice Narration](/blog/260403). <video poster="https://media.useapi.net/blog/2026-04-03-260403/veo-3-1-fast-voice-zephyr-poster.jpg" controls width="100%" style="max-width:400px"> <source src="https://media.useapi.net/blog/2026-04-03-260403/veo-3-1-fast-voice-zephyr.mp4" type="video/mp4"> </video> ###### veo-3.1-fast » Dancing cha-cha (portrait reference-to-video) From [Veo 3.1 Portrait R2V](/blog/260113). <video poster="https://media.useapi.net/blog/2026-01-13-260113/dancing-cha-cha-poster.jpg" src="https://media.useapi.net/blog/2026-01-13-260113/dancing-cha-cha.mp4" style="width: 100%; max-width: 400px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> More on YouTube: [Veo 3.1 extend and concatenate](https://www.youtube.com/shorts/PWWH2aOJG3A). ## Questions ### How much does the Veo 3.1 API cost? Through useapi.net on Google Flow with Google AI Ultra $199.99, an 8-second Veo 3.1 Quality video costs $0.80 and a Lite video $0.04, against $3.20 and $0.40 on the official Veo API. The same subscription also includes Veo 3.1 Lite at lower priority for $0, about 1,000 or more videos a day (as of November 2026). See [Price per video](#price-per-video). ### Is Veo 3.1 still on the Gemini API? Through useapi.net, Veo 3.1 runs on Google Flow with a Google AI subscription. The Gemini API no longer has it: Google shut down its Veo 3.1 Preview models there on October 22, 2026, and Google's own Veo API is now Agent Platform on Google Cloud, which needs a Google Cloud project and a billing account. The Google Flow API needs neither, only a Google AI plan and a useapi.net token. ### What is the cheapest way to run Veo 3.1 at volume? Through useapi.net, connect several Google AI Ultra $199.99 subscriptions and one token spreads your jobs across them. 4K costs 50 extra credits there, so a 4K Fast video comes to about $0.48, against $2.40 on the official Veo API (as of November 2026). See [Price per video](#price-per-video). --- Connect your accounts with the [setup guide](/docs/start-here/setup-google-flow). ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/blog/241213 === Document URL: https://useapi.net/blog/241213 --- layout: blog_post title: "Mureka API v1: Pro Subscription Features" description: "The Mureka API v1 now supports all functionality of Mureka AI, including Pro subscription features. We have added the ability to regenerate and extend music,…" parent: Blog nav_exclude: true nav_order: -241213 --- ## December 13, 2024 The [Mureka API v1](/docs/api-mureka-v1) now supports **all** functionality of [Mureka AI](https://www.mureka.ai), including Pro subscription features. We have added the ability to regenerate and extend music, upload custom soundtracks for reference, and use melodies (motifs) as references. Examples below were created using the Mureka API endpoint [POST mureka/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced). * Uploaded reference track using [POST mureka/files](/docs/api-mureka-v1/post-mureka-files) Generated song <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2024-12-13-241213/1-developerstheydontcareaboutbugs-file-id.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Also on YouTube: [Developers, They Don’t Care About Bugs! • Mureka AI](https://www.youtube.com/watch?v=i0wMct6GzIs). `ref_id` (reference song) Michael Jackson - They Don't Care About Us <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2024-12-13-241213/2-reference-file-michael-jackson-they-dont-care-about-us-prison-version.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> `title` Developers, They Don't Care About Bugs! `lyrics` ```text [Intro] Every time I load the app, it keeps crashin' down, I send a ticket, I report, but the problem spins around. [Verse] They've got deadlines, bottom lines, and features to discuss, But when it comes to all these bugs, they're leaving me to fuss! [Pre-Chorus] All I wanna say is that They don't really care about bugs! All I wanna say is that They don't really care about bugs! … ``` * Uploaded reference melody (motif) using [POST mureka/files/motif](/docs/api-mureka-v1/post-mureka-files-motif) Generated song <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2024-12-13-241213/1-developerstheydontcareaboutbugs-motif-id.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> `motif_id` (reference melody) Linkin Park - Numb Just Lyrics <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2024-12-13-241213/2-reference-morif-linkin-park-numb-just-lyrics-shorts-acapella.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> `title` Developers, They Don't Care About Bugs! `lyrics` ```text [Intro] I'm tired of all these errors, Every line just brings despair. [Verse] I try to raise my voice, but they Act like nothing's even there. [Pre-Chorus] Caught in this loop, I'm breaking down, Their silence is deafening. The code keeps crashing to the ground, They don't hear a thing. … ``` === URL: https://useapi.net/blog/241231 === Document URL: https://useapi.net/blog/241231 --- layout: blog_post title: "PixVerse v3.5: New Styles and Frames" description: "PixVerse API v2 on useapi.net adds model v3.5: first and last frame videos, 360p to 1080p, and new anime, 3D animation, comic, cyberpunk, and clay styles." parent: Blog nav_exclude: true nav_order: -241231 --- ## December 31, 2024 [PixVerse API v2](/docs/api-pixverse-v2) has been updated to support **v3.5**: * Use the `model` parameter to specify the desired model when using [POST videos/create-v3](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) and [POST videos/extend-v3](/docs/api-pixverse-v2/post-pixverse-videos-extend-v4). You can choose between `v3.5` and `v3`. * A new [POST videos/create-frames-v3](/docs/api-pixverse-v2/post-pixverse-videos-create-frames-v4) has been added to support creating videos using the first and last frames. * List of supported video quality formats extended to `360p`, `540p`, `720p` and `1080p`. * List of supported styles extended to `anime`, `3d_animation`, `comic`, `cyberpunk` and `clay`. Please see the examples below generated via [POST videos/create-frames-v3](/docs/api-pixverse-v2/post-pixverse-videos-create-frames-v4): <video poster="https://media.useapi.net/blog/2024-12-31-241231/1-pixverse-v35-frames-demo-poster.jpg" src="https://media.useapi.net/blog/2024-12-31-241231/1-pixverse-v35-frames-demo.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> <video poster="https://media.useapi.net/blog/2024-12-31-241231/2-pixverse-v35-frames-demo-poster.jpg" src="https://media.useapi.net/blog/2024-12-31-241231/2-pixverse-v35-frames-demo.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> <video poster="https://media.useapi.net/blog/2024-12-31-241231/3-pixverse-v35-frames-demo-poster.jpg" src="https://media.useapi.net/blog/2024-12-31-241231/3-pixverse-v35-frames-demo.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> Also on YouTube: [PixVerse v3.5 first & last frame demo](https://youtube.com/shorts/R_5UirmZYqA). Original images used as the first and last frames to generate the above videos: ![](https://media.useapi.net/blog/2024-12-31-241231/sample-1.webp) ![](https://media.useapi.net/blog/2024-12-31-241231/sample-3.webp) ![](https://media.useapi.net/blog/2024-12-31-241231/sample-2.jpg) ![](https://media.useapi.net/blog/2024-12-31-241231/sample-5.webp) === URL: https://useapi.net/blog/250102 === Document URL: https://useapi.net/blog/250102 --- layout: blog_post title: "Runway Gen-3 Turbo: Middle Frame Support" description: "Added the parameter middleImageassetId to Runway Gen-3 Alpha Turbo POST gen3turbo/create endpoint to support a middle frame in addition to the first and last…" parent: Blog nav_exclude: true nav_order: -250102 --- ## January 2, 2025 Added the parameter `middleImage_assetId` to Runway Gen-3 Alpha Turbo [POST gen3turbo/create](/docs/api-runwayml-v1/post-runwayml-gen3turbo-create) endpoint to support a `middle` frame in addition to the `first` and `last` frames. Please see the example below generated via [POST gen3turbo/create](/docs/api-runwayml-v1/post-runwayml-gen3turbo-create): <video poster="https://media.useapi.net/blog/2025-01-02-250102/street-workout-poster.jpg" src="https://media.useapi.net/blog/2025-01-02-250102/street-workout.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> Original images used as the first, middle and last frames to generate the above video: ![](https://media.useapi.net/blog/2025-01-02-250102/first.jpg) ![](https://media.useapi.net/blog/2025-01-02-250102/middle.jpg) ![](https://media.useapi.net/blog/2025-01-02-250102/last.jpg) === URL: https://useapi.net/blog/250115 === Document URL: https://useapi.net/blog/250115 --- layout: blog_post title: "Mureka: Custom Vocals" description: "Mureka API v1 updated to support custom vocals (upload your own voice):" parent: Blog nav_exclude: true nav_order: -250115 --- ## January 15, 2025 [Mureka API v1](/docs/api-mureka-v1) updated to support custom vocals (upload your own voice): * Retrieve a list of vocal samples including the ones you uploaded [GET music/vocals](/docs/api-mureka-v1/get-mureka-music-vocals). * Upload mp3 vocal [POST files/vocal](/docs/api-mureka-v1/post-mureka-files-vocal). * Delete vocal [DEL files/vocal](/docs/api-mureka-v1/del-mureka-files-vocal). Please see the examples below generated via [POST music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced): <video poster="https://media.useapi.net/blog/2025-01-15-250115/trump-rapping-poster.jpg" src="https://media.useapi.net/blog/2025-01-15-250115/trump-rapping.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> * MP3 extracted form original [song by Eminem](https://www.youtube.com/watch?v=xFYQQPAOz7Y) via [GET files/youtube](/docs/api-mureka-v1/get-mureka-files-youtube) and uploaded as reference track via [POST files](/docs/api-mureka-v1/post-mureka-files). * Trump vocals uploaded via [POST files/vocal](/docs/api-mureka-v1/post-mureka-files-vocal) <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2025-01-15-250115/voice-tump.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> * Lyrics ```text [Intro] (Yo, yo!) Trump and Elon, getting quirky with flair, Turning life into a circus, AI everywhere! [Verse] It’s Trump with the mic, Elon's on a roll, AI taking over, even stealing your role. Robots making burgers without a single mess, And hologram baristas passing the latte test! [Chorus] You better hold onto your hats, folks, AI’s here, Replacing your dog as man’s best peer! Tariffs on yo-yos, just for the laugh, Robots running marathons on our behalf! [Break] (Elon: Yeah, our Teslas now juggle, it's a sight) Martian golf courses where robots take flight! [Outro] So here’s the deal, we’re having a ball, Trump and Musk, running the digital hall. With AI in charge, who needs shoes? In our zany world, you’ll never lose! (Laugh it up, join the AI cruise!) ``` [YouTube](https://www.youtube.com/watch?v=mZDCfVmyEoc). === URL: https://useapi.net/blog/250124 === Document URL: https://useapi.net/blog/250124 --- layout: blog_post title: "PixVerse: Lip-Sync for Uploaded Videos" description: "PixVerse API v2 has been updated to support lip-sync for uploaded videos:" parent: Blog nav_exclude: true nav_order: -250124 --- ## January 24, 2025 [PixVerse API v2](/docs/api-pixverse-v2) has been updated to support lip-sync for uploaded videos: * Parameter `video_path` added to [POST pixverse/videos/lipsync](/docs/api-pixverse-v2/post-pixverse-videos-lipsync) to specify video uploaded via [POST /files](/docs/api-pixverse-v2/post-pixverse-files). Please see the examples below generated via [POST pixverse/videos/lipsync](/docs/api-pixverse-v2/post-pixverse-videos-lipsync): #### #1 [YouTube](https://www.youtube.com/watch?v=3dcEjIZ_loc) <video poster="https://media.useapi.net/blog/2025-01-24-250124/pixverse-lipsync-from-uploaded-video-poster.jpg" src="https://media.useapi.net/blog/2025-01-24-250124/pixverse-lipsync-from-uploaded-video.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> * [Video](https://media.useapi.net/blog/2025-01-24-250124/runway-generated-video.mp4) generated via [POST runway/videos/create-v3](/docs/api-runwayml-v1/post-runwayml-gen3turbo-create) from original [image](https://media.useapi.net/blog/2025-01-24-250124/lady-wizard.webp). * MP3 music generated via [POST mureka/music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced) using Scarlett Johansson voice uploaded via [POST mureka/files/vocal](/docs/api-mureka-v1/post-mureka-files-vocal). <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2025-01-24-250124/mureka-generated-song-trimmed.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### #2 [YouTube](https://www.youtube.com/watch?v=tUts-39VvRg) <video poster="https://media.useapi.net/blog/2025-01-24-250124/pixverse-lipsync-from-uploaded-lazer-sword-poster.jpg" src="https://media.useapi.net/blog/2025-01-24-250124/pixverse-lipsync-from-uploaded-lazer-sword.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> * [Video](https://media.useapi.net/blog/2025-01-24-250124/runway-generated-lazer-sword.mp4) generated via [POST runway/videos/create-v3](/docs/api-runwayml-v1/post-runwayml-gen3turbo-create) from original [image](https://media.useapi.net/blog/2025-01-24-250124/lazer-sword.webp). * Lip sync `prompt: Come to the dark side, learn the power of the API` with `speaker_id: 3` (Isabella). #### #3 [YouTube](https://www.youtube.com/watch?v=WZ_QMT7BabY) <video poster="https://media.useapi.net/blog/2025-01-24-250124/pixverse-lipsync-from-generated-video-poster.jpg" src="https://media.useapi.net/blog/2025-01-24-250124/pixverse-lipsync-from-generated-video.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> * Video generated via [POST pixverse/videos/create-v3](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) from original [image](https://media.useapi.net/blog/2025-01-24-250124/pixverse-generated-video.webp). * MP3 music generated via [POST mureka/music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced) using Scarlett Johansson voice uploaded via [POST mureka/files/vocal](/docs/api-mureka-v1/post-mureka-files-vocal). <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2025-01-24-250124/mureka-generated-song-trimmed.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> #### #4 [YouTube](https://www.youtube.com/watch?v=yA1-PRCfD1w) <video poster="https://media.useapi.net/blog/2025-01-24-250124/pixverse-image-to-video-to-lipsync-with-text-poster.jpg" src="https://media.useapi.net/blog/2025-01-24-250124/pixverse-image-to-video-to-lipsync-with-text.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> * Video generated via [POST pixverse/videos/create-v3](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) from original [image](https://media.useapi.net/blog/2025-01-24-250124/pretty-lady.webp). * Lip sync `prompt: Hey, I'm strutting in this crochet masterpiece, looking like a sunset's way of saying, Stay cozy, summer is still here!` with `speaker_id: 1` (Emily). === URL: https://useapi.net/blog/250129 === Document URL: https://useapi.net/blog/250129 --- layout: blog_post title: "Runway Frames: Fast Image Generation" description: "We have added support for Runway Frames see POST frames/create. This endpoint will generate 4 images in under 20 seconds on average. You can run several…" parent: Blog nav_exclude: true nav_order: -250129 --- ## January 29, 2025 We have added support for [Runway Frames](https://help.runwayml.com/hc/en-us/articles/35694045317139-Frames-Prompting-Guide) see [POST frames/create](/docs/api-runwayml-v1/post-runwayml-frames-create). This endpoint will generate 4 images in under 20 seconds on average. You can run several generations in parallel as well. Please see the example below generated via [POST frames/create](/docs/api-runwayml-v1/post-runwayml-frames-create): * Photography of an attractive woman with beautiful long legs in leather short dress with headscarf leaning on the door of a 1966 289 black mustang, on the streets of London (B&W Contrast) ![](https://media.useapi.net/blog/2025-01-29-250129/frames-1.png) * Surreal minimalist drawing illustration, abstract art (High Contrast Cool) ![](https://media.useapi.net/blog/2025-01-29-250129/frames-2.png) * Appetizing slice of cherry cheesecake, professional photography and light, close-up (High Contrast Warm) ![](https://media.useapi.net/blog/2025-01-29-250129/frames-3.png) * A beautiful woman sits on a throne, wearing a velvet nun outfit, smoky eyes, dark blue hair, bangs, gloves, floral tattoo on leg, edgy, happy expression, flash photography, chandelier on top, garnet walls and ceiling (Vivid) ![](https://media.useapi.net/blog/2025-01-29-250129/frames-4.png) * Sweedish supermodel wearing jedi outfit, holding long lightsaber (High Contrast Cool) ![](https://media.useapi.net/blog/2025-01-29-250129/frames-5.png) === URL: https://useapi.net/blog/250224m === Document URL: https://useapi.net/blog/250224m --- layout: blog_post title: "MiniMax: I2V-01-Director Image-to-Video Model" description: "The MiniMax API v1 endpoint POST videos/create has been updated to support I2V-01-Director Image-to-Video Director model." parent: Blog nav_exclude: true nav_order: -250224 --- ## February 24, 2025 The [MiniMax API v1](/docs/api-minimax-v1) endpoint [POST videos/create](/docs/api-minimax-v1/post-minimax-videos-create) has been updated to support `I2V-01-Director` Image-to-Video Director model. Please see the example below generated via [POST videos/create](/docs/api-minimax-v1/post-minimax-videos-create): <video poster="https://media.useapi.net/blog/2025-02-24-250224m/earthquake-poster.jpg" src="https://media.useapi.net/blog/2025-02-24-250224m/earthquake.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> Prompt: >Earth is shaking. She looks terrified! [Shake] [Zoom out] Prompt image: ![](https://media.useapi.net/blog/2025-02-24-250224m/athena.webp) === URL: https://useapi.net/blog/250224r === Document URL: https://useapi.net/blog/250224r --- layout: blog_post title: "Runway: Frames Describe Endpoint" description: "Added new Runway API v1 endpoint GET frames/describe. This endpoint extracts a text image description that can be adjusted and used as a starting point for…" parent: Blog nav_exclude: true nav_order: -250224 --- ## February 24, 2025 Added new [Runway API v1](/docs/api-runwayml-v1) endpoint [GET frames/describe](/docs/api-runwayml-v1/get-runwayml-frames-describe). This endpoint extracts a text image description that can be adjusted and used as a starting point for the prompt in [POST frames/create](/docs/api-runwayml-v1/post-runwayml-frames-create). Prompt image: ![](https://media.useapi.net/blog/2025-02-24-250224m/athena.webp) Provided description: ```json { "prompt": "Subject: A woman wearing an elegant Greco-Roman style ivory silk dress with ornate golden embellishments at the neckline and waist. Multiple golden bangles adorn her wrists as she stands in a graceful pose with one hand extended to touch a column.\n\nScene: Ancient stone columns with weathered surfaces frame a shadowy interior space. The architectural elements suggest a classical temple or palace setting with fluted pillars and worn stone textures visible in the warm lighting.\n\nStyle: Dramatic chiaroscuro lighting creates deep shadows while highlighting the luxurious fabric draping and metallic details. The composition emphasizes classical beauty through careful attention to form, texture, and light interplay. Professional fashion photography meets fine art painting aesthetic. Classical, dramatic lighting, textile-focused, painterly, architectural." } ``` === URL: https://useapi.net/blog/250317 === Document URL: https://useapi.net/blog/250317 --- layout: blog_post title: "MiniMax: Text-to-Image Generation" description: "We are happy to announce support for the recently released text-to-image AI model for MiniMax API v1." parent: Blog nav_exclude: true nav_order: -250317 --- ### March 17, 2025 We are happy to announce support for the recently released `text-to-image` AI model for [MiniMax API v1](/docs/api-minimax-v1). The following endpoints have been added: * Create an image using a text prompt [POST images/create](/docs/api-minimax-v1/post-minimax-images-create) * Retrieve the list of images you have generated [GET images](/docs/api-minimax-v1/get-minimax-images) * Retrieve an image [GET images/`imageId`](/docs/api-minimax-v1/get-minimax-images-imageId) * Delete an image [DELETE images/`imageId`](/docs/api-minimax-v1/del-minimax-images-imageId) It costs one credit to generate a single image, and you can generate up to four images at once. With the daily free top-up of 100 credits, a free [hailuoai.video](https://hailuoai.video) account can generate 100 images per day - up to 3K images per month. Prompt: > Ultra-realistic image: the skin of women's lips as black oil. The surface and structure of the lips look as if they were made of fresh oily, rich black oil. The lips should have a texture that is as close as possible to the black oil structure. Result: ![](https://media.useapi.net/blog/2025-03-17-250317/lips.png) Prompt: > A mesmerizing image of smoke elegantly forming a lifelike cat silhouette in mid-air. The intricate details and vibrant colors of the cat, along with the perfect balance of smoke density and airiness, create an incredible visual effect. The background reveals a mystical or enchanted setting, possibly a dimly lit room with candles and a moonlit sky. The combination of photo, illustration, 3D render, and painting techniques make this piece a true masterpiece., 3d render, photo, painting, vibrant, illustration Result: ![](https://media.useapi.net/blog/2025-03-17-250317/cat.png) Prompt: > A stunning high-contrast, cinematic photo-style vertical collage of iconic landmarks and scenes from New York City, with each letter of 'NEW YORK CITY' featuring a different, dynamic scene. The overall mood is vibrant and bustling, capturing the essence of the city. Result: ![](https://media.useapi.net/blog/2025-03-17-250317/nyc.png) Prompt: > Ultra-realistic image: poster for the cartoon "Little Fairy". The title of the cartoon at the top of the poster: Use an unusually beautiful hand-written antique font, as if written with a fountain pen in fairy ink with changing colors. The title harmoniously contrasts with the main image of the poster: A face in half-turn close-up, eyes looking at the nose, a little fairy with wings sits on the nose and waves a magic wand. In the background - traces of steam, translucent stars and magical scenery. Maximum realism, magic and miracles. A three-dimensional poster in the best traditions of animation studios such as Disney and Pixar. Result: ![](https://media.useapi.net/blog/2025-03-17-250317/little-fairy.png) Prompt: > Extreme Closeup of a Wonder Woman, dark-haired, with a red top with a gold breastplate, and a blue bottom with white stars and a golden belt, the face of a 25 year old supermodel, flexing a bulging bicep with an intimidating glare, staring straight into the camera, with a female fitness model physique with bulging biceps and chiseled six-pack abs, showing off her muscles in the gym Result: ![](https://media.useapi.net/blog/2025-03-17-250317/wonder-woman.png) === URL: https://useapi.net/blog/250324 === Document URL: https://useapi.net/blog/250324 --- layout: blog_post title: "PixVerse v4: Now on API v2" description: "PixVerse API v2 on useapi.net now runs PixVerse v4, with an example video from POST videos/create using a first frame, template, sound effects, and lip sync." parent: Blog nav_exclude: true nav_order: -250324 --- ### March 24, 2025 [PixVerse API v2](/docs/api-pixverse-v2) has been updated to support PixVerse v4. Please see the examples below generated via [POST videos/create](/docs/api-pixverse-v2/post-pixverse-videos-create-v4): <video poster="https://media.useapi.net/blog/2025-03-24-250324/wait-for-it-poster.jpg" src="https://media.useapi.net/blog/2025-03-24-250324/wait-for-it.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> Also on YouTube: [Wait for it … • PixVerse V4](https://youtube.com/shorts/JkBUF4GE1oU). Original [image](https://media.useapi.net/blog/2025-03-24-250324/wait-for-it.jpg) `POST https://api.useapi.net/v2/pixverse/videos/create-v4` ```typescript { "model": "v4", "quality": "720p", "duration":"8", "prompt": "Pretty lady smiling", "first_frame_path": "upload/<wait_for_it.jpg>", "template_id": 326607027713088, // Fire Roar "sound_effect_prompt": "music playing in the background", "lip_sync_tts_prompt": "Wait for it", "lip_sync_tts_speaker_id": "1", // Emily } ``` === URL: https://useapi.net/blog/250331 === Document URL: https://useapi.net/blog/250331 --- layout: blog_post title: "PixVerse v4: Frames, Extend, Restyle, Lip Sync" description: "PixVerse v4 endpoints in useapi.net API v2: create videos from first and last frames, extend and restyle videos, and lip sync updated to V4, with examples." parent: Blog nav_exclude: true nav_order: -250331 --- ### March 31, 2025 [PixVerse API v2](/docs/api-pixverse-v2) has been updated to support PixVerse v4: * Create video using first and last frames [POST videos/create-frames](/docs/api-pixverse-v2/post-pixverse-videos-create-frames-v4). * Extend video [POST videos/extend](/docs/api-pixverse-v2/post-pixverse-videos-extend-v4). * Restyle video [POST videos/restyle](/docs/api-pixverse-v2/post-pixverse-videos-restyle-v4). * Lip sync video [POST videos/lipsync](/docs/api-pixverse-v2/post-pixverse-videos-lipsync), updated to use `V4`. 1. [POST videos/create-frames](/docs/api-pixverse-v2/post-pixverse-videos-create-frames-v4) [First frame](https://media.useapi.net/blog/2025-03-31-250331/first-frame.jpg) [Last frame](https://media.useapi.net/blog/2025-03-31-250331/last-frame.jpg) Prompt > She is smiling, camera rotating around her <video poster="https://media.useapi.net/blog/2025-03-31-250331/frames-v4-poster.jpg" src="https://media.useapi.net/blog/2025-03-31-250331/frames-v4.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> 2. Extend video [POST videos/extend](/docs/api-pixverse-v2/post-pixverse-videos-extend-v4) Prompt > taking her hat off <video poster="https://media.useapi.net/blog/2025-03-31-250331/extend-v4-poster.jpg" src="https://media.useapi.net/blog/2025-03-31-250331/extend-v4.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> 3. Restyle video [POST videos/restyle](/docs/api-pixverse-v2/post-pixverse-videos-restyle-v4) restyle_id: `322876019426368` (Ghibli) <video poster="https://media.useapi.net/blog/2025-03-31-250331/restyle-ghibli-poster.jpg" src="https://media.useapi.net/blog/2025-03-31-250331/restyle-ghibli.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> 4. Lip sync video [POST videos/lipsync](/docs/api-pixverse-v2/post-pixverse-videos-lipsync) <video poster="https://media.useapi.net/blog/2025-03-31-250331/orange-glow-video-poster.jpg" src="https://media.useapi.net/blog/2025-03-31-250331/orange-glow-video.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> Also on YouTube: [Orange Glow • PixVerse](https://youtube.com/shorts/NOq4K1WbTIU). Song was composed via [POST riffusion/music/create-prompt](/docs/api-riffusion-v1/post-riffusion-music-create-prompt). <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2025-03-31-250331/orange-glow.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> === URL: https://useapi.net/blog/250402 === Document URL: https://useapi.net/blog/250402 --- layout: blog_post title: "Runway: Gen-4 Video Generation" description: "Runway API v1 has been updated to support Gen-4, see POST gen4/create." parent: Blog nav_exclude: true nav_order: -250402 --- ### April 2, 2025 [Runway API v1](/docs/api-runwayml-v1) has been updated to support Gen-4, see [POST gen4/create](/docs/api-runwayml-v1/post-runwayml-gen4-create). [First frame](https://media.useapi.net/blog/2025-04-02-250402/femme-fatale.webp) <video poster="https://media.useapi.net/blog/2025-04-02-250402/gen4-wow-just-wow-poster.jpg" src="https://media.useapi.net/blog/2025-04-02-250402/gen4-wow-just-wow.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> Also on YouTube: [Who is she? • Runway Gen-4](https://youtube.com/shorts/R_P0dhahQAY). Instrumental music was composed via [POST mureka/music/create-instrumental](/docs/api-mureka-v1/post-mureka-music-create-instrumental). <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2025-04-02-250402/instrumental.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> === URL: https://useapi.net/announcement-250407 === Document URL: https://useapi.net/announcement-250407 --- layout: blog_post title: April 7 '25 • New Subscription Model description: "We updated our subscription model, please take a look to familiarize yourself. Feel free to reach support if you have any questions or concerns." nav_exclude: true permalink: /announcement-250407 --- # New Subscription Model ### April 7, 2024 We updated our [subscription](/docs/subscription) model, please take a look to familiarize yourself. Feel free to reach [support](/docs/support) if you have any questions or concerns. 1. Starting Thursday, April **10th**, 2025, you will receive a `402` error with a detailed error message when attempting to *add* or *update* your AI API account if the number of your accounts exceeds your subscription quantity. Simply delete unused accounts to bring the total number below three, or update your [subscription](/docs/subscription) quantity. 2. Starting Thursday, April **17th**, 2025, you will receive a `402` error with a detailed error message when using AI API *endpoints* if the number of your accounts exceeds your subscription quantity. Simply delete unused accounts to bring the total number below three, or update your [subscription](/docs/subscription) quantity. Check your [useapi.net account](/docs/account-management/get-account) status and current number of configured accounts to ensure uninterrupted service. We also sent an email with detailed instructions to all users affected by this change. === URL: https://useapi.net/blog/250418 === Document URL: https://useapi.net/blog/250418 --- layout: blog_post title: "Kling API v1: Now Available" description: "We're excited to announce the release of Kling API v1, our latest experimental API for Kling AI." parent: Blog nav_exclude: true nav_order: -250418 --- ## Kling API v1 April 18, 2025 --- We're excited to announce the release of [Kling API v1](/docs/api-kling-v1), our latest experimental API for [Kling AI](https://klingai.com). Kling offers text-to-video, image-to-video, and image manipulation capabilities with multiple model versions `1.5`, `1.6` and `2.0`. Key features include video generation from elements, special effects, virtual try-on, video extension, lip-syncing, and text-to-speech. The API supports both free and paid Kling accounts. In contrast to the [official](https://app.klingai.com/global/dev/document-api/productBilling/prePaidResourcePackage) Kling API, which starts at $1,400/month (Video Generation) and requires a 3-month subscription commitment, you can start using the API with a Free or [$10/month](https://app.klingai.com/global/membership/membership-plan) Standard plan and upgrade or [top up](https://app.klingai.com/global/membership/spirit-unit) your account as needed. As a bonus, you can execute an unlimited number of TTS generations for free via [POST /tts/create](/docs/api-kling-v1/post-kling-tts-create). This feature is available for all Kling subscription plans, including the free one. ### Example » Virtual Try-On [POST /kling/images/virtual-try-on](/docs/api-kling-v1/post-kling-images-virtual-try-on) <details markdown="block"> <summary><b>Input Images</b></summary> `humanImage` ![](https://media.useapi.net/blog/2025-04-18-250418/model.png) `upperInput` ![](https://media.useapi.net/blog/2025-04-18-250418/white-top.png) `lowerInput` ![](https://media.useapi.net/blog/2025-04-18-250418/hot-pants.jpg) </details> Result ![](https://media.useapi.net/blog/2025-04-18-250418/kling-virtual-try-on-result.png) ### Example » Image-to-Video • Elements [POST /kling/images/elements](/docs/api-kling-v1/post-kling-videos-image2video-elements) `model` Kling 1.6 `prompt` > Pretty lady sitting at a table at the french cafe and drinking coffee, she is looking at the camera and smiling. The camera is slowly rotating around, almost as if we are walking past her table. <details markdown="block"> <summary><b>Input Images</b></summary> `image_0` ![](https://media.useapi.net/blog/2025-04-18-250418/kling-virtual-try-on-result.png) `image_1` ![](https://media.useapi.net/blog/2025-04-18-250418/french-cafe.jpg) `image_2` ![](https://media.useapi.net/blog/2025-04-18-250418/monster-coffee-cup.png) </details> Result <video poster="https://media.useapi.net/blog/2025-04-18-250418/kling-elements-result-poster.jpg" src="https://media.useapi.net/blog/2025-04-18-250418/kling-elements-result.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> ### Example » TTS Text to Speech [POST /kling/tts/create](/docs/api-kling-v1/post-kling-tts-create) `speakerId` Tender `prompt` > Hey! Hello! Nice to meet you finally! Look at my fancy espresso drink I just ordered! Do you want to share it? Result <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2025-04-18-250418/kling-tts.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ### Example » Lip Sync [POST /kling/videos/lipsync](/docs/api-kling-v1/post-kling-videos-lipsync) Result <video poster="https://media.useapi.net/blog/2025-04-18-250418/kling-lip-sync-poster.jpg" src="https://media.useapi.net/blog/2025-04-18-250418/kling-lip-sync.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> Also on YouTube: [Le Grand Espresso](https://youtube.com/shorts/amsfLt_jA8w). === URL: https://useapi.net/blog/250424 === Document URL: https://useapi.net/blog/250424 --- layout: blog_post title: "Kling: Now Supports KOLORS" description: "Kling API v1 has been updated to support KOLORS v1.5 and v2.0:" parent: Blog nav_exclude: true nav_order: -250424 --- ## Kling API now supports KOLORS April 24, 2025 --- [Kling API v1](/docs/api-kling-v1) has been updated to support KOLORS v1.5 and v2.0: * Create images using KOLORS [POST images/kolors](/docs/api-kling-v1/post-kling-images-kolors) * Detect faces in images (**free** for all users) [POST images/recognize-faces](/docs/api-kling-v1/post-kling-images-recognize-faces) * Upscale previously generated images [POST images/upscale](/docs/api-kling-v1/post-kling-images-upscale) ### Example » Text-to-Image [POST images/kolors](/docs/api-kling-v1/post-kling-images-kolors) reference `none`. <details markdown="block"> <summary><b>CURL</b></summary> ```bash curl --location 'https://api.useapi.net/v1/kling/images/kolors' \ --header 'Authorization: Bearer user:1234-abcdefghijkl' \ --form 'email="my@email.com"' \ --form 'prompt="Swedish supermodel wearing a light pink mini sports crop top, running mini shorts, and high heels decorated with Swarovski crystals, posing for the camera. The background is a solid very light off-white. She is smiling and looking at the camera. Her right arm is raised up in the air, her legs are shoulder-width apart."' \ --form 'aspect_ratio="3:4"' \ --form 'imageCount="4"' ``` </details> Result ![](https://media.useapi.net/blog/2025-04-24-250424/super-model.png) ### Example » Restyle [POST images/kolors](/docs/api-kling-v1/post-kling-images-kolors) reference `restyle`. <details markdown="block"> <summary><b>CURL and imageReference</b></summary> ```bash curl --location 'https://api.useapi.net/v1/kling/images/kolors' \ --header 'Content-Type: application/json;charset=utf-8' \ --header 'Authorization: Bearer user:1234-abcdefghijkl' \ --form 'imageReference="https://my-server.com/model.jpg"' \ --form 'email="my@email.com"' \ --form 'prompt="Fashion model posing for a magazine photoshoot. She is wearing Adidas shorts and a gold chain on her neck. She has a colorful dragon tattoo on her left arm."' \ --form 'imageCount="3"' \ --form 'reference="restyle"' ``` `imageReference` ![](https://media.useapi.net/blog/2025-04-24-250424/model-a.jpg) </details> Result ![](https://media.useapi.net/blog/2025-04-24-250424/model-a-restyle.png) ### Example » Face [POST images/kolors](/docs/api-kling-v1/post-kling-images-kolors) reference `face`. <details markdown="block"> <summary><b>CURL and imageReference</b></summary> ```bash curl --location 'https://api.useapi.net/v1/kling/images/kolors' \ --header 'Content-Type: application/json;charset=utf-8' \ --header 'Authorization: Bearer user:1234-abcdefghijkl' \ --form 'imageReference="https://my-server.com/model.jpg"' \ --form 'email="my@email.com"' \ --form 'prompt="Lady playing tennis, she is serving, standing behind the baseline. She is holding a tennis racket in her right hand. We can see the tennis ball in the air."' \ --form 'aspect_ratio="3:2"' \ --form 'faceStrength="90"' \ --form 'imageCount="3"' \ --form 'reference="face"' ``` `imageReference` ![](https://media.useapi.net/blog/2025-04-24-250424/model-a.jpg) </details> Result ![](https://media.useapi.net/blog/2025-04-24-250424/model-tennis-player-face.png) ### Example » Subject [POST images/kolors](/docs/api-kling-v1/post-kling-images-kolors) reference `subject`. <details markdown="block"> <summary><b>CURL and imageReference</b></summary> ```bash curl --location 'https://api.useapi.net/v1/kling/images/kolors' \ --header 'Content-Type: application/json;charset=utf-8' \ --header 'Authorization: Bearer user:1234-abcdefghijkl' \ --form 'imageReference="https://my-server.com/model/cup.jpeg"' \ --form 'email="my@email.com"' \ --form 'prompt="Professional photograph of a coffee cup standing on the marble table next to a plate with an appetizing slice of cherry cheesecake."' \ --form 'aspect_ratio="4:30"' \ --form 'subjectStrength="90"' \ --form 'imageCount="3"' \ --form 'reference="subject"' ``` `imageReference` ![](https://media.useapi.net/blog/2025-04-24-250424/monster-coffee-cup.png) </details> Result ![](https://media.useapi.net/blog/2025-04-24-250424/coffee-cup-subject.png) === URL: https://useapi.net/blog/250430 === Document URL: https://useapi.net/blog/250430 --- layout: blog_post title: "Runway Frames: Reference Images" description: "Updated Runway API v1 endpoint POST frames/create to support optional reference images. See the official References Guide." parent: Blog nav_exclude: true nav_order: -250430 --- ### April 30, 2025 Updated [Runway API v1](/docs/api-runwayml-v1) endpoint [POST frames/create](/docs/api-runwayml-v1/post-runwayml-frames-create) to support optional reference images. See the official [References Guide](https://help.runwayml.com/hc/en-us/articles/40042718905875-References-Guide). **Example** [imageAssetId1](https://media.useapi.net/blog/2025-04-30-250430/red-head-model.webp) can be referenced in prompt via `@IMG_1` [imageAssetId2](https://media.useapi.net/blog/2025-04-30-250430/the-purple-cat.webp) can be referenced in prompt via `@IMG_2` [imageAssetId3](https://media.useapi.net/blog/2025-04-30-250430/horse.webp) can be referenced in prompt via `@IMG_3` CURL ```bash curl --location 'https://api.useapi.net/v1/runwayml/frames/create' \ --header 'Authorization: Bearer user:1234-abcdrfgh' \ --form 'exploreMode="true"' \ --form 'text_prompt="A pretty red-haired lady riding a horse with her pet cat."' \ --form 'aspect_ratio="9:16"' \ --form 'style="high-contrast-warm"' \ --form 'imageAssetId1="user:1234-runwayml:my@email.com-asset:a8b63275-b485-4ed5-b210-41b5a4896be1"' \ --form 'imageAssetId2="user:1234-runwayml:my@email.com-asset:2f4cd3c7-b05c-4ac9-87a1-e6ef2e86f013"' \ --form 'imageAssetId3="user:1234-runwayml:my@email.com-asset:780e1a25-32ca-426a-975c-030bcbb6e5e6"' ``` CURL with prompt using `@IMG_1`, `@IMG_2` and `@IMG_3` ```bash curl --location 'https://api.useapi.net/v1/runwayml/frames/create' \ --header 'Authorization: Bearer user:1234-abcdrfgh' \ --form 'exploreMode="true"' \ --form 'text_prompt="@IMG_1 riding a @IMG_2 with @IMG_3"' \ --form 'aspect_ratio="9:16"' \ --form 'style="high-contrast-warm"' \ --form 'imageAssetId1="user:1234-runwayml:my@email.com-asset:a8b63275-b485-4ed5-b210-41b5a4896be1"' \ --form 'imageAssetId2="user:1234-runwayml:my@email.com-asset:2f4cd3c7-b05c-4ac9-87a1-e6ef2e86f013"' \ --form 'imageAssetId3="user:1234-runwayml:my@email.com-asset:780e1a25-32ca-426a-975c-030bcbb6e5e6"' ``` Result ![](https://media.useapi.net/blog/2025-04-30-250430/frame-refs-results.png) === URL: https://useapi.net/blog/250508 === Document URL: https://useapi.net/blog/250508 --- layout: blog_post title: "MiniMax: Character Reference for Image Generation" description: "MiniMax API v1 added support for character reference for the image endpoint POST images/create." parent: Blog nav_exclude: true nav_order: -250508 --- [MiniMax API v1](/docs/api-minimax-v1) added support for character reference for the image endpoint [POST images/create](/docs/api-minimax-v1/post-minimax-images-create). **Example** [characterFileId](https://media.useapi.net/blog/2025-05-08-250508/characterref.png) CURL ```bash curl --location 'https://api.useapi.net/v1/minimax/images/create' \ --header 'Authorization: Bearer user:1234-abcdefghijklm' \ --form 'prompt="Freakish-looking clown wearing a red MAGA baseball cap and holding a large orange sparkling air balloon in his right hand. We see large graffiti behind him on the wall saying \"BEAUTIFooL TARIFFS\""' \ --form 'quantity="4"' \ --form 'aspectRatio="9:16"' \ --form 'characterFileId="user:1234-minimax:1234567890-file:1234567890"' ``` Result ![](https://media.useapi.net/blog/2025-05-08-250508/characterrefresult.png) === URL: https://useapi.net/blog/250515 === Document URL: https://useapi.net/blog/250515 --- layout: blog_post title: "TemPolor: Introducing the Music Generation API" description: "We’re excited to announce the release of TemPolor API v1, our latest experimental API for TemPolor, an AI-powered, royalty-free music generation service that…" parent: Blog nav_exclude: true nav_order: -250515 --- We’re excited to announce the release of [TemPolor API v1](/docs/api-tempolor-v1), our latest experimental API for [TemPolor](https://www.tempolor.com), an AI-powered, royalty-free **music generation** service that creates high-quality soundtracks from text prompts, custom lyrics, MIDI, and supports voice cloning. TemPolor offers extensive customization for instrumental tracks, including chords and BPM. Supports export in mp3, wav, and stems, and it can generate stems from users' audio files. Up to 10 tracks can be generated concurrently, with **unlimited** generations available on the [Ultra](https://www.tempolor.com/pricing) plan. **Examples** * Create music with vocals [POST music/song](/docs/api-tempolor-v1/post-tempolor-music-song). <details markdown="block"> <summary>Song sample, prompt only</summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/song' \ --header 'Authorization: Bearer user:12345-abcdefghijklm' \ --form 'prompt="Pop"' \ --form 'lyrics="[Verse 1] Left sock'\''s blue, right sock'\''s green, Best darn pair I'\''ve ever seen. Pulled from the basket in a rush, Why bother matching? It'\''s too much fuss. [Chorus] Laundry day mystery, what can I do? Guess my feet just like mismatched shoes\! Stripes and polka dots, it’s a fashion coup— My toes are quirky, how about you? [Verse 2] One’s got avocados, one’s got moons, I just hope I find the mates… soon. Sometimes I wonder, do socks escape, For wild sock parties on laundry day break? [Bridge] Maybe in the dryer, there'\''s a secret sock door, Where singles go dancing on a linty floor. [Chorus] Laundry day mystery, missing socks anew, Guess my feet just like mismatched shoes\! If you spot their twins, give me some clues— Until then, it’s blue and green for Scarlett’s shoes\!"' \ --form 'model_song="v3.5"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2025-05-15-250515/laundry-day-mystery.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> <details markdown="block"> <summary>Song sample, with lyrics</summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/song' \ --header 'Authorization: Bearer user:12345-abcdefghijklm' \ --form 'prompt="Song about an awesome API that helps to generate music"' ``` Generated lyrics: ```text [Intro] [Verse] Silent sparks beneath the code Waves of sound begin to flow Lines unfold a secret road Where beats ignite and glow [Verse] Echoes pulse through circuit veins Electric streams from distant plains Rhythms dance in coded chains Unleashing sonic reigns [Verse] Digits hum the vibrant light Crafting realms in endless flight Notes cascade from endless night Shaping dreams in flight [Chorus] Feel the surge beneath your skin Power wakes from deep within Synthesized and born again A world of sound begins [Chorus] Rhythms twist in neon flare Energy flows through the air Boundless sounds beyond compare Lift us from despair [Chorus] Pulse and fire blend as one Chasing dawns till night is gone In the code the beats run on Endless dance till dawn [Inst] [Verse] Hidden layers intertwine Crafting patterns so divine Every turn a new design Futures start to shine [Verse] Breaking through the silent night Guided by the glowing light Waves that break the quiet fight Echoes strong and bright [Chorus] Feel the surge beneath your skin Power wakes from deep within Synthesized and born again A world of sound begins [Chorus] Rhythms twist in neon flare Energy flows through the air Boundless sounds beyond compare Lift us from despair [Chorus] Pulse and fire blend as one Chasing dawns till night is gone In the code the beats run on Endless dance till dawn [Outro] ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2025-05-15-250515/code-of-sound.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> * Create instrumental music [POST music/instrumental](/docs/api-tempolor-v1/post-tempolor-music-instrumental). <details markdown="block"> <summary>Instrumental sample, prompt with BMP, chords and tonality</summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/instrumental' \ --header 'Authorization: Bearer user:12345-abcdefghijklm' \ --form 'prompt="A smooth chillhop beat with electric piano and relaxed hip-hop drums"' \ --form 'bpm="85"' \ --form 'tonality="F:minor"' \ --form 'chords="Fm7 Eb7 AbMaj7"' \ --form 'model_instrumental="i3"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2025-05-15-250515/echoes-beneath-city-lights.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> <details markdown="block"> <summary>Instrumental sample, prompt only</summary> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/instrumental' \ --header 'Authorization: user:12345-abcdefghijklm' \ --form 'prompt="A cinematic orchestral piece with soaring strings and dramatic percussion"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2025-05-15-250515/ascendance.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> === URL: https://useapi.net/blog/250516 === Document URL: https://useapi.net/blog/250516 --- layout: blog_post title: "PixVerse v4.5: Image Fusion" description: "PixVerse API v2 on useapi.net makes v4.5 the default model, adds POST videos/create-fusion for @pic1 and @pic2 image fusion, and many new camera movements." parent: Blog nav_exclude: true nav_order: -250516 --- [PixVerse API v2](/docs/api-pixverse-v2) has been updated to support **v4.5** and more: * Added support for the new model **v4.5** (now default) across all endpoints * Removed the no longer used `negative_prompt` parameter * Added new [POST videos/create-fusion](/docs/api-pixverse-v2/post-pixverse-videos-create-fusion) endpoint for image fusion with special `@pic1` and `@pic2` notation * Expanded camera movement options with many new types, including `crane_up`, `hitchcock`, `smooth_zoom_in`, `pan_left`, `camera_rotation`, and more **Example** Create video using image fusion [POST videos/create-fusion](/docs/api-pixverse-v2/post-pixverse-videos-create-fusion). [@pic1](https://media.useapi.net/blog/2025-05-16-250516/pic1.webp) [@pic2](https://media.useapi.net/blog/2025-05-16-250516/pic2.webp) CURL: ```bash curl --location 'https://api.useapi.net/v2/pixverse/videos/create-fusion' \ --header 'Authorization: Bearer user:12345-abcdefghijklm' \ --form 'prompt="@pic1 fixing the hair of @pic2 while @pic2 is sticking her tongue out"' \ --form 'duration="8"' \ --form 'quality="720p"' \ --form 'first_frame_path="upload/pic1.webp"' \ --form 'last_frame_path="upload/pic2.jpeg"' \ --form 'aspect_ratio="3:4"' ``` Result <video poster="https://media.useapi.net/blog/2025-05-16-250516/pixverse-fusion-poster.jpg" src="https://media.useapi.net/blog/2025-05-16-250516/pixverse-fusion.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> Also on YouTube: [Say AAA • PixVerse Fusion](https://www.youtube.com/watch?v=Ip4RsMh_yFY). === URL: https://useapi.net/blog/250530 === Document URL: https://useapi.net/blog/250530 --- layout: blog_post title: "Kling: v2.1 and v2.1 Master Models" description: "Kling API on useapi.net adds kling-v2-1-master to text-to-video and kling-v2-1 (now the default) to image-to-video frames, plus a TemPolor music demo." parent: Blog nav_exclude: true nav_order: -250530 --- * Added support for model `kling-v2-1-master` to [POST videos/text2video](/docs/api-kling-v1/post-kling-videos-text2video). * Added support for models `kling-v2-1`, `kling-v2-1-master` to [POST videos/image2video-frames](/docs/api-kling-v1/post-kling-videos-image2video-frames). `kling-v2-1` is now the default model. **Example** * Create Video From Image Frames [POST videos/image2video-frames](/docs/api-kling-v1/post-kling-videos-image2video-frames) [image](https://media.useapi.net/blog/2025-05-30-250530/no-smoking-start-image.webp) ```bash curl --location 'https://api.useapi.net/v1/kling/videos/image2video-frames' \ --header 'Authorization: Bearer user:1234-abcdefgh' \ --form 'prompt="No smoking\!"' \ --form 'image="https://…"' \ --form 'model_name="kling-v2-1"' \ --form 'duration="10"' ``` Result <video poster="https://media.useapi.net/blog/2025-05-30-250530/no-smoking-poster.jpg" src="https://media.useapi.net/blog/2025-05-30-250530/no-smoking.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> Also on YouTube: [No Smoking! • Kling v2.1](https://youtube.com/shorts/9iqDRfOTmn8). * Instrumental music generated using TemPolor API [POST music/instrumental](/docs/api-tempolor-v1/post-tempolor-music-instrumental). ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/instrumental' \ --header 'Authorization: Bearer user:1234-abcdefgh' \ --form 'prompt="90x techno song in the club"' ``` <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2025-05-30-250530/techno-beat.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> === URL: https://useapi.net/blog/250619 === Document URL: https://useapi.net/blog/250619 --- layout: blog_post title: "MiniMax: Hailuo 02 and MiniMax-M1" description: "MiniMax API v1 on useapi.net adds the Hailuo 02 video model at 768p and 1080p and the MiniMax-M1 reasoning LLM with 1M-token input, and drops DeepSeek R1." parent: Blog nav_exclude: true nav_order: -250619 --- [MiniMax API v1](/docs/api-minimax-v1) updates: * [POST llm](/docs/api-minimax-v1/post-minimax-llm) now supports the [MiniMax-M1](https://github.com/MiniMax-AI/MiniMax-M1) reasoning model, allowing up to 1M-token input and 80K-token output. * [POST videos/create](/docs/api-minimax-v1/post-minimax-videos-create) now supports the Hailuo 02 model which generates videos at 768p (6 or 10 seconds) and 1080p (6 seconds) resolutions, features advanced instruction following, handles complex physics (including acrobatics 🤹‍♀️), and supports native 1080p output. **Note:** The DeepSeek R1 model not longer supported. **Examples** * LTX Turbo [POST videos/create](/docs/api-minimax-v1/post-minimax-videos-create) `fileID` [start frame](https://media.useapi.net/blog/2025-06-19-250619/cupcake.jpg) ```bash curl --location 'https://api.useapi.net/v1/minimax/videos/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="02"' \ --form 'options="768p-10sec"' \ --form 'prompt="The lady throws cupcake at the camera. The cupcake hits the camera lens, completely blocking the view as it smashes. Then, as the cupcake slowly slides down the camera, we see the lady jumping with joy in the background."' \ --form 'fileID="user:12345-minimax:…-file:…"' ``` Result <video poster="https://media.useapi.net/blog/2025-06-19-250619/capcake-throw-poster.jpg" src="https://media.useapi.net/blog/2025-06-19-250619/capcake-throw.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> Also on YouTube: [Cupcake is no good • Hailuo 02](https://youtube.com/shorts/38I2M0EbqSg). === URL: https://useapi.net/blog/250627 === Document URL: https://useapi.net/blog/250627 --- layout: blog_post title: "Kling: Audio Support for Video Generation" description: "Kling API on useapi.net adds an enable_audio parameter for sound effects on text-to-video, image-to-video, elements, and extend, plus fileTypes for downloads." parent: Blog nav_exclude: true nav_order: -250627 --- [Kling API v1](/docs/api-kling-v1) updates: * Added `enable_audio` parameter to video generation endpoints for sound effects support: - [POST videos/text2video](/docs/api-kling-v1/post-kling-videos-text2video) - [POST videos/image2video-frames](/docs/api-kling-v1/post-kling-videos-image2video-frames) - [POST videos/image2video-elements](/docs/api-kling-v1/post-kling-videos-image2video-elements) - [POST videos/extend](/docs/api-kling-v1/post-kling-videos-extend) * Enhanced [GET assets/download](/docs/api-kling-v1/get-kling-assets-download) with `fileTypes` parameter for selective file format downloads (MP4, MP3, WAV, PNG) **Example** ```bash curl --location 'https://api.useapi.net/v1/kling/videos/text2video' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer user:12345-…' \ --form 'prompt="A confident, energetic young woman is dancing and twerking at a vibrant disco club. Multicolored lasers flash and sweep across the crowded dance floor, their lights reflecting dramatically off her shimmering outfit and highlighting the rhythm of her movements. The lady'\''s hair bounces with each move; her body sways and twerks to the pulsing beat of upbeat dance music. The kaleidoscopic disco lights and vivid reflections create an electric party atmosphere all around her, as other dancers blur in the background. The camera follows her fluid, joyful movements, emphasizing her expressive face and the sparkle of the club scene."' \ --form 'aspect_ratio="9:16"' \ --form 'model_name="kling-v2-1-master"' \ --form 'mode="pro"' \ --form 'duration="10"' \ --form 'enable_audio="true"'``` ``` Result <video poster="https://media.useapi.net/blog/2025-06-27-250627/kling-2-1-master-with-audio-poster.jpg" src="https://media.useapi.net/blog/2025-06-27-250627/kling-2-1-master-with-audio.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> Also on YouTube: [Disco Twerking • Kling 2.1-master with audio](https://youtube.com/shorts/3S1cvi7uuFg). === URL: https://useapi.net/blog/250630 === Document URL: https://useapi.net/blog/250630 --- layout: blog_post title: "MiniMax: Agent Video Templates" description: "MiniMax API v1 groundbreaking agent video templates support:" parent: Blog nav_exclude: true nav_order: -250630 --- [MiniMax API v1](/docs/api-minimax-v1) groundbreaking agent video templates support: * Added [GET videos/agent-templates](/docs/api-minimax-v1/get-minimax-videos-agent-templates) endpoint to retrieve available agent video templates * Added [POST videos/agent-create](/docs/api-minimax-v1/post-minimax-videos-agent-create) endpoint to create videos using agent templates **Examples** Example • August 21, 2025 * Template: [`Maid Costume`](https://hailuoai.video/agent/chat/394590550286176260) (input image only) >[Image](https://media.useapi.net/blog/2025-06-30-250630/minamax-agent-template-source.jpg) uploaded using [POST files](/docs/api-minimax-v1/post-minimax-files) and provided via `fileID` & `ossPath` ```bash curl --location 'https://api.useapi.net/v1/minimax/videos/agent-create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'fileID="user:12345-minimax:…-file:…"' \ --form 'ossPath="https://cdn.hailuoai.video/moss/prod/….png"' \ --form 'templateId="394590550286176260"' ``` Result <video poster="https://media.useapi.net/blog/2025-06-30-250630/minamax-agent-template-result-poster.jpg" src="https://media.useapi.net/blog/2025-06-30-250630/minamax-agent-template-result.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> Example • June 30, 2025 * Template: [`Jelly Cut`](https://hailuoai.video/agent/chat/388743897282048009) (input image only) >Tesla Model 3 image uploaded using [POST files](/docs/api-minimax-v1/post-minimax-files) and provided via `fileID` & `ossPath` ```bash curl --location 'https://api.useapi.net/v1/minimax/videos/agent-create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'fileID="user:12345-minimax:…-file:…"' \ --form 'ossPath="https://cdn.hailuoai.video/moss/prod/….png"' \ --form 'templateId="388743897282048009"' ``` Result <video poster="https://media.useapi.net/blog/2025-06-30-250630/tesla-sliced-poster.jpg" src="https://media.useapi.net/blog/2025-06-30-250630/tesla-sliced.mp4" width="100%" controls type="video/mp4" preload="metadata"></video> Also on YouTube: [Tesla Model 3 made of Jello • MiniMax Video Agent](https://www.youtube.com/watch?v=HYeiT6P4sKE). Example • June 30, 2025 * Template: [`Felt Realm`](https://hailuoai.video/agent/chat/394119523270754311) (prompt and input image) >Little boy image uploaded using [POST files](/docs/api-minimax-v1/post-minimax-files) and provided via `fileID` & `ossPath` ```bash curl --location 'https://api.useapi.net/v1/minimax/videos/agent-create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'prompt="Create a South Park themed felt animation"' \ --form 'fileID="user:12345-minimax:…-file:…"' \ --form 'ossPath="https://cdn.hailuoai.video/moss/prod/….png"' \ --form 'templateId="394119523270754311"' ``` Result <video poster="https://media.useapi.net/blog/2025-06-30-250630/felt-magic-poster.jpg" src="https://media.useapi.net/blog/2025-06-30-250630/felt-magic.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> Also on YouTube: [Felt Magic • MiniMax Video Agent](https://youtube.com/shorts/QtmyJAghl7s). === URL: https://useapi.net/blog/250718 === Document URL: https://useapi.net/blog/250718 --- layout: blog_post title: "Kling: KOLORS v2.1 and Elements" description: "Kling API on useapi.net adds KOLORS v2.1 text-to-image and a new POST images/kolors-elements endpoint that combines up to 4 subject images with scene and style." parent: Blog nav_exclude: true nav_order: -250718 --- [Kling API v1](/docs/api-kling-v1) updates: * Updated [POST images/kolors](/docs/api-kling-v1/post-kling-images-kolors) to support KOLORS v2.1 for text-to-image generation (in addition to existing v1.5 and v2.0 support) * Added new [POST images/kolors-elements](/docs/api-kling-v1/post-kling-images-kolors-elements) endpoint for generating images with multiple image elements (up to 4 subject images, plus optional scene and style images) using KOLORS v2.0 **Example** * KOLORS Elements [POST images/kolors-elements](/docs/api-kling-v1/post-kling-images-kolors-elements) [subjectImage1](https://media.useapi.net/blog/2025-07-18-250718/jenna.jpg) [subjectImage2](https://media.useapi.net/blog/2025-07-18-250718/rabbit.jpg) [sceneImage](https://media.useapi.net/blog/2025-07-18-250718/forrest.jpg) ```bash curl --location 'https://api.useapi.net/v1/kling/images/kolors-elements' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer user:12345-…' \ --form 'subjectImage1="https://kling.klingai.com/….origin?x-kcdn-pid=12345"' \ --form 'subjectImage2="https://kling.klingai.com/….origin?x-kcdn-pid=12345"' \ --form 'sceneImage="https://kling.klingai.com/….origin?x-kcdn-pid=12345"' \ --form 'prompt="Lady holding a cute rabbit. She is looking straight at the camera."' \ --form 'aspect_ratio="9:16"' ``` Result ![](https://media.useapi.net/blog/2025-07-18-250718/jenna-holding-rabbit.png) === URL: https://useapi.net/blog/250722 === Document URL: https://useapi.net/blog/250722 --- layout: blog_post title: "Runway: Gen-4 Act-Two Video" description: "Runway API v1 added POST gen4/act-two endpoint for Gen-4 Act-Two video creation with driving video and character reference." parent: Blog nav_exclude: true nav_order: -250722 --- [Runway API v1](/docs/api-runwayml-v1) added [POST gen4/act-two](/docs/api-runwayml-v1/post-runwayml-gen4-act-two) endpoint for Gen-4 Act-Two video creation with driving video and character reference. **Example** <details markdown="block"> <summary>driving_assetId & character_assetId</summary> `driving_assetId` <video poster="https://media.useapi.net/blog/2025-07-22-250722/cool-dance-moves-poster.jpg" src="https://media.useapi.net/blog/2025-07-22-250722/cool-dance-moves.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> `character_assetId` ![](https://media.useapi.net/blog/2025-07-22-250722/act-two-model.png) </details> ```bash curl --location 'https://api.useapi.net/v1/runwayml/gen4/act-two' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Bearer user:12345-…' \ --data-urlencode 'driving_assetId=…' \ --data-urlencode 'character_assetId=…' \ --data-urlencode 'body_control=true' \ --data-urlencode 'expression_intensity=2' \ --data-urlencode 'exploreMode=true' ``` Result <video poster="https://media.useapi.net/blog/2025-07-22-250722/act-two-result-poster.jpg" src="https://media.useapi.net/blog/2025-07-22-250722/act-two-result.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> Also on YouTube: [Runway Act-Two](https://youtube.com/shorts/79Q_OwJ_ZXQ). === URL: https://useapi.net/blog/250725 === Document URL: https://useapi.net/blog/250725 --- layout: blog_post title: "Kling: Video Effects Updates" description: "Kling API v1 video effects endpoints POST videos/image2video-effects and GET videos/effects updated:" parent: Blog nav_exclude: true nav_order: -250725 --- [Kling API v1](/docs/api-kling-v1) video effects endpoints [POST videos/image2video-effects](/docs/api-kling-v1/post-kling-videos-image2video-effects) and [GET videos/effects](/docs/api-kling-v1/get-kling-videos-effects) updated: * Removed `image_tail` parameter - no longer supported in the current API implementation * Added `mode` parameter - select between `std` (standard) and `pro` (professional) quality modes * Enhanced effect validation - effects now include `effectSupported` and `promptSupported` flags to indicate capabilities * Updated response structure - reflects current API with detailed user points, tickets, and task information Currently unsupported effects (require image preprocessing): * `felt` (FeltFelt) * `furry` (PlushCut) * `jelly` (JellyJelly) * `pixel` (PixelPixel) * `yearbook` (Yearbook) * `polaroid` (Instant Film) * `spring_blossoms` (BloomBloom) *Note: This list may change and may not be complete. Effects marked as `effectSupported: false` in the API response require multi-step preprocessing and are not yet available through this endpoint.* ### Examples ```bash curl --location 'https://api.useapi.net/v1/kling/videos/image2video-effects' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: application/json' \ --form 'image="https://…"' \ --form 'effect="fighting"' ``` Result <video poster="https://media.useapi.net/blog/2025-07-25-250725/fighting-poster.jpg" src="https://media.useapi.net/blog/2025-07-25-250725/fighting.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> ```bash curl --location 'https://api.useapi.net/v1/kling/videos/image2video-effects' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: application/json' \ --form 'image="https://…"' \ --form 'effect="skate"' ``` Result <video poster="https://media.useapi.net/blog/2025-07-25-250725/skate-poster.jpg" src="https://media.useapi.net/blog/2025-07-25-250725/skate.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> === URL: https://useapi.net/blog/250801 === Document URL: https://useapi.net/blog/250801 --- layout: blog_post title: "Mureka: V7 Now Default with Higher Limits" description: "Mureka API v1 has been updated with model improvements and increased character limits:" parent: Blog nav_exclude: true nav_order: -250801 --- [Mureka API v1](/docs/api-mureka-v1) has been updated with model improvements and increased character limits: * Model `V7` is now the default for all music generation endpoints, replacing `V6` * Increased character limits: - Prompt maximum length increased from 300 to 1000 characters for [POST music/create](/docs/api-mureka-v1/post-mureka-music-create) and [POST music/create-instrumental](/docs/api-mureka-v1/post-mureka-music-create-instrumental) - Lyrics maximum length increased from 2000 to 3000 characters for [POST music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced) and [POST music/extend](/docs/api-mureka-v1/post-mureka-music-extend) * For instrumental generation, older models (`O1`, `V6`, `V5.5`) now redirect to `V7`, we will be removing retired models on September 1, 2025. [POST music/create-instrumental](/docs/api-mureka-v1/post-mureka-music-create-instrumental) ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-instrumental' \ --header 'Authorization: Bearer user:12345-…' \ --form 'prompt="The sound of an ancient, forgotten technology slowly powering up for the first time in millennia. Low hum, crackling energy, glitchy arpeggios, and a rising synth choir."' \ --form 'model="V7"' ``` <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2025-08-01-250801/echoes-of-time.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> [POST music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced) ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-advanced' \ --header 'Authorization: Bearer user:12345-…' \ --form 'lyrics="[Verse] Place the item. In the bagging area. You have failed. It creates mass hysteria. Unexpected item. My sensors are screaming. Is this a banana? Or are you just dreaming? [Chorus] I am the machine, I see your mistake Please wait for assistance, for goodness sake Your coupon'\''s expired, your card is declined The human condition is poorly designed."' \ --form 'model="V7"' \ --form 'desc="sea shanty, 80s power ballad, spy jazz"' ``` <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2025-08-01-250801/place-the-item-in-the-bagging-area.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Also on YouTube: [Banana Error • Music by Mureka V7](https://www.youtube.com/watch?v=ug9hnMIX2wU). === URL: https://useapi.net/blog/250804 === Document URL: https://useapi.net/blog/250804 --- layout: blog_post title: "Runway: Gen-4 Aleph Video-to-Video" description: "Runway API v1 has been updated to support Gen-4 Aleph (video-to-video transformation) with the new POST gen4/video endpoint for video-to-video generation…" parent: Blog nav_exclude: true nav_order: -250804 --- [Runway API v1](/docs/api-runwayml-v1) has been updated to support Gen-4 Aleph (video-to-video transformation) with the new [POST gen4/video](/docs/api-runwayml-v1/post-runwayml-gen4-video) endpoint for video-to-video generation using text prompts and optional image conditioning. <details markdown="block"> <summary>video_assetId</summary> <video poster="https://media.useapi.net/blog/2025-08-04-250804/maga-poster.jpg" src="https://media.useapi.net/blog/2025-08-04-250804/maga.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> </details> <details markdown="block"> <summary>image_assetId</summary> ![](https://media.useapi.net/blog/2025-08-04-250804/penguin.webp) </details> ```bash curl --location 'https://api.useapi.net/v1/runwayml/gen4/video' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Bearer user:12345-…' \ --data-urlencode 'video_assetId=user:12345-runwayml:…@mail.com-asset:…efg' \ --data-urlencode 'image_assetId=user:12345-runwayml:…@mail.com-asset:…abc' \ --data-urlencode 'text_prompt=A man making a speech on stage, with two penguins standing to his left and right sides, nodding. Cinematic wide-angle shot. Remove all watermarks.' ``` Gen-4 Aleph Result <video poster="https://media.useapi.net/blog/2025-08-04-250804/trump-made-deal-with-penguins-poster.jpg" src="https://media.useapi.net/blog/2025-08-04-250804/trump-made-deal-with-penguins.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> Voiceover using cloned voice ⁝ MiniMax TTS [POST minimax/speech/create-mp3](/docs/api-minimax-v1/post-minimax-speech-create-mp3) ```bash curl --location 'https://api.useapi.net/v1/minimax/speech/create-mp3' \ --header 'Authorization: Bearer user:12345-…' \ --form 'text="We reached a historic deal\! We will be buying snow from the Democratic Penguins Republic\! No more tariffs\!"' \ --form 'voice_id="…"' ``` MiniMax TTS Result <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2025-08-04-250804/drp-deal-signed.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> PixVerse LipSync ⁝ MiniMax TTS [POST pixverse/videos/lipsync](/docs/api-pixverse-v2/post-pixverse-videos-lipsync) ```bash curl --location 'https://api.useapi.net/v2/pixverse/videos/lipsync' \ --header 'Authorization: Bearer user:12345-…' \ --form 'video_path="upload/…abcd.mp4"' \ --form 'audio_path="upload/…efgh.mp3"' ``` PixVerse LipSync Result <video poster="https://media.useapi.net/blog/2025-08-04-250804/trump-made-deal-with-penguins-lipsync-poster.jpg" src="https://media.useapi.net/blog/2025-08-04-250804/trump-made-deal-with-penguins-lipsync.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> Also on YouTube: [Trump made a historic deal with the DPR • Runway Aleph](https://youtube.com/shorts/jG6aCT8F9uM). === URL: https://useapi.net/blog/250804m === Document URL: https://useapi.net/blog/250804m --- layout: blog_post title: "MiniMax Hailuo 02: 512p Image-to-Video" description: "MiniMax API v1 endpoint POST videos/create updated to support new image-to-video resolution options for the Hailuo 02 model:" parent: Blog nav_exclude: true nav_order: -250804 --- [MiniMax API v1](/docs/api-minimax-v1) endpoint [POST videos/create](/docs/api-minimax-v1/post-minimax-videos-create) updated to support new image-to-video resolution options for the Hailuo 02 model: * Added `512p-6sec` option (image-to-video only, fileID is required) * Added `512p-10sec` option (image-to-video only, fileID is required) <details markdown="block"> <summary>fileID</summary> ![](https://media.useapi.net/blog/2025-08-04-250804m/bi-crow.jpg) </details> ```bash curl --location 'https://api.useapi.net/v1/minimax/videos/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="02"' \ --form 'options="512p-10sec"' \ --form 'prompt="She is making funny faces"' ``` MiniMax 02 Result <video poster="https://media.useapi.net/blog/2025-08-04-250804m/minimax-02-512p-10sec-poster.jpg" src="https://media.useapi.net/blog/2025-08-04-250804m/minimax-02-512p-10sec.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> Billie Eilish [Bad Guy](https://www.youtube.com/watch?v=DyDfgMOUjCI) video soundtrack downloaded ⁝ Mureka YouTube download [GET mureka/files/youtube](/docs/api-mureka-v1/get-mureka-files-youtube) ```bash curl --location 'https://api.useapi.net/v1-dev/mureka/files/youtube/?account=86142223515649&url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DDyDfgMOUjCI' \ --header 'Authorization: Bearer user:12345-…' ``` Composed soundtrack inspired by [Bad Guy](https://www.youtube.com/watch?v=DyDfgMOUjCI) by Billie Eilish ⁝ Mureka Instrumental [POST mureka/music/create-instrumental](/docs/api-mureka-v1/post-mureka-music-create-instrumental) ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-instrumental' \ --header 'Authorization: Bearer user:12345-…' --form 'model="V7"' \ --form 'ref_id="…"' ``` Mureka Instrumental Result <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2025-08-04-250804m/bad-guy-cover.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Final video with the soundtrack <video poster="https://media.useapi.net/blog/2025-08-04-250804m/minimax-02-512p-10sec-audio-poster.jpg" src="https://media.useapi.net/blog/2025-08-04-250804m/minimax-02-512p-10sec-audio.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> Also on YouTube: [Making funny faces • MiniMax 02 540p](https://www.youtube.com/watch?v=LkiSlL19T_0). === URL: https://useapi.net/blog/250808 === Document URL: https://useapi.net/blog/250808 --- layout: blog_post title: "Kling: Add Sound Endpoint for Videos" description: "Kling API on useapi.net adds POST videos/add-sound to generate audio for a video, GET assets/uploaded to list your uploads, and a fileName field on POST assets." parent: Blog nav_exclude: true nav_order: -250808 --- [Kling API v1](/docs/api-kling-v1) enhancements: * Added new [POST videos/add-sound](/docs/api-kling-v1/post-kling-videos-add-sound) endpoint for AI-generated video-to-audio conversion with optional original sound preservation * Added new [GET assets/uploaded](/docs/api-kling-v1/get-kling-assets-uploaded) endpoint to retrieve user-uploaded assets with filename filtering support * Enhanced [POST assets](/docs/api-kling-v1/post-kling-assets) response to include `fileName` field with the generated unique filename <details markdown="block"> <summary>video asset</summary> <video poster="https://media.useapi.net/blog/2025-07-28-250728/mj-video-imagine-u1-animate-high-u3-extend-high-u3-poster.jpg" src="https://media.useapi.net/blog/2025-07-28-250728/mj-video-imagine-u1-animate-high-u3-extend-high-u3.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> </details> ```bash curl --location 'https://api.useapi.net/v1/kling/videos/add-sound' \ --header 'Authorization: Bearer user:12345-…' \ --form 'video="https://v15-kling.klingai.com/…"' ``` Result <video poster="https://media.useapi.net/blog/2025-08-08-250808/sharkobatics-wih-audio-poster.jpg" src="https://media.useapi.net/blog/2025-08-08-250808/sharkobatics-wih-audio.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> === URL: https://useapi.net/blog/250818 === Document URL: https://useapi.net/blog/250818 --- layout: blog_post title: "Mureka: Speech Generation and Voice Cloning" description: "Mureka API v1 on useapi.net adds speech generation: text-to-speech with multi-speaker conversations, voice cloning from MP3 samples, and voice management." parent: Blog nav_exclude: true nav_order: -250818 --- [Mureka API v1](/docs/api-mureka-v1) TTS/speech generation endpoints added: * [POST speech](/docs/api-mureka-v1/post-mureka-speech) - generate speech from text with voice cloning and multi-speaker conversations * [GET speech](/docs/api-mureka-v1/get-mureka-speech) - retrieve generated speech recordings * [DELETE speech](/docs/api-mureka-v1/del-mureka-speech) - delete speech recordings * [GET speech/voices](/docs/api-mureka-v1/get-mureka-speech-voices) - list available voices including cloned ones * [POST speech/voice](/docs/api-mureka-v1/post-mureka-speech-voice) - clone voice from MP3 audio samples * [DELETE speech/voice](/docs/api-mureka-v1/del-mureka-speech-voice) - delete cloned voices ### Example [POST speech](/docs/api-mureka-v1/post-mureka-speech) * Cloned voice - Scarlet (`"voice_id": 12345`) <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2025-08-18-250818/voice-scarlett-1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> * Cloned voice - Morgan (`"voice_id": 67890`) <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2025-08-18-250818/voice-morgan.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ```bash curl --location 'https://api.useapi.net/v1/mureka/speech/' \ --header 'Authorization: Bearer user:12345-…' \ --form 'conversation="[ { \"voice_id\": 12345, \"text\": \"Scarlett, I have a query of a cosmological nature. If the universe is constantly expanding, does that mean this jar of pickles is, on a molecular level, getting infinitesimally farther away from the olives?\" }, { \"voice_id\": 67890, \"text\": \"It means you'\''ve been standing in front of the open fridge for five minutes. Are you making a sandwich or narrating the secret life of condiments?\" }, { \"voice_id\": 12345, \"text\": \"A sandwich is not merely a construct of bread and fillings. It is a journey. A story of disparate elements... the humble turkey, the audacious mustard... all coming together to create a fleeting moment of culinary harmony. This pickle is the story'\''s climax.\" }, { \"voice_id\": 67890, \"text\": \"The only climax happening here is my electricity bill. Grab the jar and close the door before you cause a temporal rift in the dairy aisle.\" } ]"' ``` Result <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2025-08-18-250818/morgan-scarlett-dialogue.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> === URL: https://useapi.net/blog/250822 === Document URL: https://useapi.net/blog/250822 --- layout: blog_post title: "Kling 2.1: End Frame Support" description: "Kling API v1 video frames endpoints POST videos/image2video-frames updated to add model KLING 2.1 End Frame feature - imagetail parameter support." parent: Blog nav_exclude: true nav_order: -250822 --- [Kling API v1](/docs/api-kling-v1) video frames endpoints [POST videos/image2video-frames](/docs/api-kling-v1/post-kling-videos-image2video-frames) updated to add model [KLING 2.1 End Frame](https://app.klingai.com/global/image-to-video/frame-mode) feature - `image_tail` parameter support. **Example** * Create Video From Image Frames [POST videos/image2video-frames](/docs/api-kling-v1/post-kling-videos-image2video-frames) [image](https://media.useapi.net/blog/2025-08-22-250822/start.jpg) [image_tail](https://media.useapi.net/blog/2025-08-22-250822/end.jpg) ```bash curl --location 'https://api.useapi.net/v1/kling/videos/image2video-frames' \ --header 'Authorization: Bearer user:12345-…' \ --form 'prompt="flying and spinning"' \ --form 'image="https://s15-kling.klingai.com/…"' \ --form 'image_tail="https://s15-kling.klingai.com/…"' \ --form 'model_name="kling-v2-1"' \ --form 'duration="5"' \ --form 'enable_audio="true"' ``` Result <video poster="https://media.useapi.net/blog/2025-08-22-250822/kling-2-1-end-frame-poster.jpg" src="https://media.useapi.net/blog/2025-08-22-250822/kling-2-1-end-frame.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> Also on YouTube: [KLING 2.1 End Frame](https://youtube.com/shorts/nh333dq0grs). === URL: https://useapi.net/blog/250829 === Document URL: https://useapi.net/blog/250829 --- layout: blog_post title: "PixVerse v5: Model and Transition Videos" description: "PixVerse API v2 on useapi.net makes v5 the default model, adds multi-frame transition videos and 3-frame fusion, and moves the -v4 endpoints to simpler URLs." parent: Blog nav_exclude: true nav_order: -250829 --- ## Table of contents ### [PixVerse API v2](/docs/api-pixverse-v2) major update * Added support for the new **v5** model, which is now the default model * Added [model capabilities matrix](/docs/api-pixverse-v2/model-capabilities) documentation * Added [POST videos/create-transition](/docs/api-pixverse-v2/post-pixverse-videos-create-transition) for multi-frame transition videos * Updated [POST videos/create-fusion](/docs/api-pixverse-v2/post-pixverse-videos-create-fusion) to support up to 3 frames (up from 2) * Updated [POST videos/create](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) to make the `prompt` parameter optional * Old versioned endpoints now redirect to new simplified URLs: - `POST videos/create-v4` → `POST videos/create` - `POST videos/create-frames-v4` → `POST videos/create-frames` - `POST videos/extend-v4` → `POST videos/extend` - `POST videos/restyle-v4` → `POST videos/restyle` * [POST videos/create-fusion](/docs/api-pixverse-v2/post-pixverse-videos-create-fusion) parameter mapping (old → new): - `first_frame_path` → `frame_1_path` - `last_frame_path` → `frame_2_path` See examples below. --- ### Create transition video [POST videos/create-transition](/docs/api-pixverse-v2/post-pixverse-videos-create-transition). [frame_1_path](https://media.useapi.net/blog/2025-08-29-250829/car1-a.png) [frame_2_path](https://media.useapi.net/blog/2025-08-29-250829/car2.jpg) [frame_3_path](https://media.useapi.net/blog/2025-08-29-250829/car3.jpg) [frame_4_path](https://media.useapi.net/blog/2025-08-29-250829/car4.jpg) [frame_5_path](https://media.useapi.net/blog/2025-08-29-250829/car5.jpg) CURL: ```bash curl --location 'https://api.useapi.net/v2/pixverse/videos/create-transition' \ --header 'Authorization: Bearer user:12345-…' \ --form 'quality="720p"' \ --form 'frame_1_path="upload/<car1>.jpeg"' \ --form 'frame_2_path="upload/<car2>.jpeg"' \ --form 'frame_3_path="upload/<car3>.jpeg"' \ --form 'frame_4_path="upload/<car4>.jpeg"' \ --form 'frame_5_path="upload/<car5>.jpeg"' ``` Instrumental music composed via [POST mureka/music/create-instrumental](/docs/api-mureka-v1/post-mureka-music-create-instrumental) Using [POST videos/lipsync](/docs/api-pixverse-v2/post-pixverse-videos-lipsync) composed mp3 track applied to previously generated transition video. Final result with transition video and music <video poster="https://media.useapi.net/blog/2025-08-29-250829/car-final-540p-with-sound-track-poster.jpg" src="https://media.useapi.net/blog/2025-08-29-250829/car-final-540p-with-sound-track.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> Also on YouTube: [PixVerse v5 Transition](https://www.youtube.com/watch?v=iphtkhFP9SQ). ### Create fusion video [POST videos/create-fusion](/docs/api-pixverse-v2/post-pixverse-videos-create-fusion). [frame_1_path](https://media.useapi.net/blog/2025-08-29-250829/grl.png) [frame_2_path](https://media.useapi.net/blog/2025-08-29-250829/lady-in-the-red-hat.webp) [frame_3_path](https://media.useapi.net/blog/2025-08-29-250829/egupt.jpg) CURL: ```bash curl --location 'https://api.useapi.net/v2/pixverse/videos/create-fusion' \ --header 'Authorization: Bearer user:12345-…' \ --form 'prompt="@pic1 fixing the hair of @pic2 while @pic2 is sticking her tongue out with @pic3 in the background"' \ --form 'duration="8"' \ --form 'frame_1_path="upload/….png"' \ --form 'frame_2_path="upload/….webp"' \ --form 'frame_3_path="upload/….jpg"' \ --form 'aspect_ratio="9:16"' ``` Result <video poster="https://media.useapi.net/blog/2025-08-29-250829/fusion-result-poster.jpg" src="https://media.useapi.net/blog/2025-08-29-250829/fusion-result.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> ### Create video effect using template [POST videos/create](/docs/api-pixverse-v2/post-pixverse-videos-create-v4). [first_frame_path](https://media.useapi.net/blog/2025-08-29-250829/winter-coming.webp) Effect `340541567573824` "Dive in! Get your fins now" see [GET videos/effects](/docs/api-pixverse-v2/get-pixverse-videos-effects). CURL: ```bash curl --location 'https://api.useapi.net/v2/pixverse/videos/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'quality="720p"' \ --form 'first_frame_path="upload/….webp"' \ --form 'template_id="340541567573824"' ``` Result <video poster="https://media.useapi.net/blog/2025-08-29-250829/template-effect-720p-poster.jpg" src="https://media.useapi.net/blog/2025-08-29-250829/template-effect-720p.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> ### Create video using first and last frames [POST videos/create-frames](/docs/api-pixverse-v2/post-pixverse-videos-create-frames-v4). [first_frame_path](https://media.useapi.net/blog/2025-08-29-250829/girl-no-cat.webp) [last_frame_path](https://media.useapi.net/blog/2025-08-29-250829/girl-and-a-cat.webp) CURL: ```bash curl --location 'https://api.useapi.net/v2/pixverse/videos/create-frames' \ --header 'Authorization: Bearer user:12345-…' \ --form 'duration="8"' \ --form 'model="v5"' \ --form 'quality="720p"' \ --form 'first_frame_path="upload/….webp"' \ --form 'last_frame_path="upload/….webp"' \ --form 'sound_effect_prompt="Happy, upbeat music playing."' \ --form 'lip_sync_tts_prompt="Time to take my kitty for a walk\!"' \ --form 'lip_sync_tts_speaker_id="5"' ``` Result <video poster="https://media.useapi.net/blog/2025-08-29-250829/frames-transition-poster.jpg" src="https://media.useapi.net/blog/2025-08-29-250829/frames-transition.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> ### Create video from the text prompt [POST videos/create](/docs/api-pixverse-v2/post-pixverse-videos-create-v4). CURL: ```bash curl --location 'https://api.useapi.net/v2/pixverse/videos/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'prompt="A handheld selfie-style shot, from the point-of-view of the Predator in full armor (from the Predator movie) in a lush jungle. The Predator holds the camera in his right arm at arm’s length. His long, powerful arms are clearly visible in the frame, and his face featuring arthropod-like mandibles and no visible nose is perfectly framed. The Predator says in a deep voice: “I just landed on this planet. Will be scouting for the prey and sending updates shortly.” (lips moving like he’s saying it)"' \ --form 'duration="8"' \ --form 'quality="720p"' \ --form 'sound_effect_prompt="Rumbling alien voice"' ``` Result <video poster="https://media.useapi.net/blog/2025-08-29-250829/text-to-video-720p-8sec-auto-audio-poster.jpg" src="https://media.useapi.net/blog/2025-08-29-250829/text-to-video-720p-8sec-auto-audio.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> ### Create video from text and an image prompts [POST videos/create](/docs/api-pixverse-v2/post-pixverse-videos-create-v4). [first_frame_path](https://media.useapi.net/blog/2025-08-29-250829/crows-menace.webp) CURL: ```bash curl --location 'https://api.useapi.net/v2/pixverse/videos/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'prompt="Menacing crows circling around wizard lady. Atmosphere of dark magic. Camera slowly zooming out."' \ --form 'duration="8"' \ --form 'quality="720p"' \ --form 'aspect_ratio="9:16"' \ --form 'first_frame_path="upload/….webp"' \ --form 'sound_effect_prompt="Sound of the crows flapping their wings."' \ --form 'lip_sync_tts_prompt="Stay away from my crows\!"' \ --form 'lip_sync_tts_speaker_id="1"' ``` Result <video poster="https://media.useapi.net/blog/2025-08-29-250829/pixverse-v5-create-720p-poster.jpg" src="https://media.useapi.net/blog/2025-08-29-250829/pixverse-v5-create-720p.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> ### Extend video with the prompt [POST videos/extend](/docs/api-pixverse-v2/post-pixverse-videos-extend-v4). We will be using video generated above. CURL: ```bash curl --location 'https://api.useapi.net/v2-dev/pixverse/videos/extend' \ --header 'Authorization: Bearer user:12345-…' \ --form 'prompt="She grows wings and flies away with the crows."' \ --form 'duration="8"' \ --form 'model="v5"' \ --form 'quality="720p"' \ --form 'video_id="user:…-video:…"' ``` Result <video poster="https://media.useapi.net/blog/2025-08-29-250829/pixverse-v5-create-720p-extended-to-16sec-poster.jpg" src="https://media.useapi.net/blog/2025-08-29-250829/pixverse-v5-create-720p-extended-to-16sec.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> ### Upscale video to 4K [POST videos/upscale](/docs/api-pixverse-v2/post-pixverse-videos-upscale). We will be using video generated above. CURL: ```bash curl --location 'https://api.useapi.net/v2/pixverse/videos/upscale' \ --header 'Authorization: Bearer user:12345-…' \ --form 'video_id="user:…-video:…"' ``` Result <video poster="https://media.useapi.net/blog/2025-08-29-250829/pixverse-v5-create-720p-extended-to-16sec-upscaled-poster.jpg" src="https://media.useapi.net/blog/2025-08-29-250829/pixverse-v5-create-720p-extended-to-16sec-upscaled.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> === URL: https://useapi.net/blog/250830 === Document URL: https://useapi.net/blog/250830 --- layout: blog_post title: "MiniMax: End Frame Parameter for Video" description: "MiniMax API v1 endpoint POST videos/create updated to support the End Frame parameter endframefileID." parent: Blog nav_exclude: true nav_order: -250830 --- [MiniMax API v1](/docs/api-minimax-v1) endpoint [POST videos/create](/docs/api-minimax-v1/post-minimax-videos-create) updated to support the End Frame parameter `end_frame_fileID`. **Example** * Create a video using a text and image prompt [POST videos/create](/docs/api-minimax-v1/post-minimax-videos-create) [fileID](https://media.useapi.net/blog/2025-08-30-250830/levitation.jpg) [end_frame_fileID](https://media.useapi.net/blog/2025-08-30-250830/levitation.jpg) > Keep in mind that if you want to use the same end frame as the first one, you still have to re-upload it in order for the API to accept it. ```bash curl --location 'https://api.useapi.net/v1/minimax/videos/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="02"' \ --form 'prompt="Camera rotating around subject hovering in the air."' \ --form 'options="768p-10sec"' \ --form 'fileID="user:12345-minimax:…-file:…"' \ --form 'end_frame_fileID="user:12345-minimax:…-file:…"' ``` Result <video poster="https://media.useapi.net/articles/2024-09-28-minimax-bash/minimax-end-frame-poster.jpg" src="https://media.useapi.net/articles/2024-09-28-minimax-bash/minimax-end-frame.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> Also on YouTube: [MiniMax 02 End Frame](https://youtube.com/shorts/g6_nL6FXI3k). === URL: https://useapi.net/blog/250908 === Document URL: https://useapi.net/blog/250908 --- layout: blog_post title: "Runway: Act-Two Voice Swapping" description: "Runway API v1 added POST gen4/act-two-voice endpoint for AI voice swapping with Act-Two." parent: Blog nav_exclude: true nav_order: -250908 --- [Runway API v1](/docs/api-runwayml-v1) added [POST gen4/act-two-voice](/docs/api-runwayml-v1/post-runwayml-gen4-act-two-voice) endpoint for AI voice swapping with Act-Two. **Example** * Runway Act-Two voice swap [POST gen4/act-two-voice](/docs/api-runwayml-v1/post-runwayml-gen4-act-two-voice) using Ragnar voice Original [video](/blog/250124.html#4-youtube) ```bash curl --location 'https://api.useapi.net/v1/runwayml/gen4/act-two-voice' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: application/json' \ --data '{ "video_assetId": "user:12345-runwayml:…-asset:…", "voiceId": "YOq2y2Up4RgXP2HyXjE5" }' ``` Result <video poster="https://media.useapi.net/blog/2025-09-08-250908/act-two-voice-poster.jpg" src="https://media.useapi.net/blog/2025-09-08-250908/act-two-voice.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> Also on YouTube: [Runway Act-Two voice swap](https://youtube.com/shorts/C8o9bl7PItQ). === URL: https://useapi.net/blog/250923 === Document URL: https://useapi.net/blog/250923 --- layout: blog_post title: "Kling v2.5: Text-to-Video and Image-to-Video" description: "Kling API on useapi.net adds the kling-v2-5 model to text-to-video and image-to-video frames, shown in two 10-second examples generated with audio enabled." parent: Blog nav_exclude: true nav_order: -250923 --- [Kling API v1](/docs/api-kling-v1) has been updated to support model `v2.5`: * Added support for model `kling-v2-5` to [POST videos/text2video](/docs/api-kling-v1/post-kling-videos-text2video). * Added support for models `kling-v2-5` to [POST videos/image2video-frames](/docs/api-kling-v1/post-kling-videos-image2video-frames). **Example** * Create Video From Text [POST videos/text2video](/docs/api-kling-v1/post-kling-videos-text2video) ```bash curl --location 'https://api.useapi.net/v1/kling/videos/text2video' \ --header 'Authorization: Bearer user:12345-…' \ --form 'prompt="Donald Trump and Robert F. Kennedy Jr., dressed formally, are sitting at a desk in the Oval Office. They grab two Tylenol bottles and start bashing them against the table. Both appear to be mad, with pronounced facial expressions."' \ --form 'aspect_ratio="16:9"' \ --form 'model_name="kling-v2-5"' \ --form 'duration="10"' \ --form 'enable_audio="true"' ``` Result <video poster="https://media.useapi.net/blog/2025-09-23-250923/no-more-tylenol-poster.jpg" src="https://media.useapi.net/blog/2025-09-23-250923/no-more-tylenol.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> Also on YouTube: [No More Tylenol • Kling v2.5](https://www.youtube.com/watch?v=dCSwOizOJKU). * Create Video From Image Frames [POST videos/image2video-frames](/docs/api-kling-v1/post-kling-videos-image2video-frames) [image](https://media.useapi.net/blog/2025-09-23-250923/dog-and-cat.jpg) ```bash curl --location 'https://api.useapi.net/v1/kling/videos/image2video-frames' \ --header 'Authorization: Bearer user:12345-…' \ --form 'prompt="The cat jumps on the dog'\''s back. Both are excited and happy to see each other. The cat jumps while standing on the dog'\''s back."' \ --form 'image="https://s15-kling.klingai.com/…"' \ --form 'model_name="kling-v2-5"' \ --form 'duration="10"' \ --form 'enable_audio="true"' ``` Result <video poster="https://media.useapi.net/blog/2025-09-23-250923/dog-and-cat-kling-2-5-poster.jpg" src="https://media.useapi.net/blog/2025-09-23-250923/dog-and-cat-kling-2-5.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> === URL: https://useapi.net/blog/250925 === Document URL: https://useapi.net/blog/250925 --- layout: blog_post title: "Mureka: V7.5 Now the Default Model" description: "Mureka API v1 on useapi.net switches music generation to V7.5 by default, adds a vocal gender option, and walks through a song parody using a reference track." parent: Blog nav_exclude: true nav_order: -250925 --- [Mureka API v1](/docs/api-mureka-v1) has been updated: * Model `V7.5` is now the default for all music generation endpoints, replacing `V7`. * [POST music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced) supports an optional parameter `voice_gender`, which can be set to `female` or `male`. * [POST music/instrumental](/docs/api-mureka-v1/post-mureka-music-create-instrumental) supports models `V7.5`, `O1` and `V6`. Let's create short parody for [Camila Cabello - Havana](https://www.youtube.com/watch?v=HCjNJDNzw8Y). **1** Download original song from YouTube via [GET files/youtube](/docs/api-mureka-v1/get-mureka-files-youtube) ```bash curl --location 'https://api.useapi.net/v1/mureka/files/youtube/?account=123456789&url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DHCjNJDNzw8Y' \ --header 'Authorization: Bearer user:12345-…' ``` Downloaded mp3 [track](https://media.useapi.net/blog/2025-09-25-250925/camila-cabello-havana-audio-ft.-young-thug.mp3) was uploaded to Mureka via [POST files](/docs/api-mureka-v1/post-mureka-files). **2** Generate lyrics via [POST music/lyrics-generate](/docs/api-mureka-v1/post-mureka-music-lyrics-generate) ```bash curl --location 'https://api.useapi.net/v1/mureka/music/lyrics-generate/' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer user:12345-…' \ --data '{ "account": 123456789, "prompt": "Create lyrics mocking Camila Cabello - Havana song, make it a humorous song about Banana" }' ``` Result ```text [Intro] [Verse] Banana, banana, in my handa, Taste so sweet, no need for candy. Camila singin' 'bout Havana, I'm sippin' on banana flav'ry. Banana, banana, in my handa, Taste so sweet, no need for candy. Camila singin' 'bout Havana, I'm sippin' on banana flav'ry. [Outro] ``` **3** Generate song using the lyrics above and reference sound with [POST music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced). ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-advanced' \ --header 'Authorization: Bearer user:12345-…' \ --form 'account="123456789"' \ --form 'lyrics="[Intro] [Verse] Banana, banana, in my handa, Taste so sweet, no need for candy. Camila singin'\'' '\''bout Havana, I'\''m sippin'\'' on banana flav'\''ry. Banana, banana, in my handa, Taste so sweet, no need for candy. Camila singin'\'' '\''bout Havana, I'\''m sippin'\'' on banana flav'\''ry. [Outro]"' \ --form 'vocal_gender="female"' \ --form 'ref_id="987654321"' ``` Result <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2025-09-25-250925/camila-cabello-havana-funny.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Also on YouTube: [Banana Ooh Nah Nah • Mureka v7.5 / Midjourney v7 / Kling v2.5](https://youtube.com/shorts/ol2ZosOSvrg). **4** We can also create instrumental music based on the original song via [POST music/create-instrumental](/docs/api-mureka-v1/post-mureka-music-create-instrumental). ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-instrumental' \ --header 'Authorization: Bearer user:12345-…' \ --form 'account="123456789"' \ --form 'ref_id="987654321"' ``` Result <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2025-09-25-250925/camila-cabello-havana-instrumental.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> === URL: https://useapi.net/blog/251007 === Document URL: https://useapi.net/blog/251007 --- layout: blog_post title: "Kling: Motion Control Endpoints" description: "Kling API on useapi.net adds Motion Control: list motion templates, upload 2 to 10 second clips as custom motions, and apply them to characters in an image." parent: Blog nav_exclude: true nav_order: -251007 --- [Kling API v1](/docs/api-kling-v1) new endpoints for Motion Control: * [GET videos/motions](/docs/api-kling-v1/get-kling-videos-motions) to retrieve available motion templates (official Kling motions and user-uploaded custom motions) * [POST videos/motion-upload](/docs/api-kling-v1/post-kling-videos-motion-upload) to upload custom videos (2-10 seconds) for motion extraction * [POST videos/motion-create](/docs/api-kling-v1/post-kling-videos-motion-create) to apply motion templates to static images, creating animated videos with character motion control - Supports multi-character detection and selection - Optional audio generation with sound effects, music, and ASMR * [DELETE tasks/`task_id`](/docs/api-kling-v1/del-kling-tasks-task_id) to delete tasks and associated works **Examples** * Create Video using one of standard Kling motions [POST videos/motion-create](/docs/api-kling-v1/post-kling-videos-motion-create) [image](https://media.useapi.net/blog/2025-10-07-251007/dance-festival.webp) > Motion: `Circle Glide` > Targeting **first** character from the left (`character_id=0`) ```bash curl --location 'https://api.useapi.net/v1/kling/videos/motion-create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'workId="-100000000000004"' \ --form 'image="https://s15-kling.klingai.com/…"' \ --form 'character_id="0"' \ --form 'mode="std"' \ --form 'duration="5"' ``` Result <video poster="https://media.useapi.net/blog/2025-10-07-251007/demo-left-0-poster.jpg" src="https://media.useapi.net/blog/2025-10-07-251007/demo-left-0.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> > Motion: `Circle Glide` > Targeting **second** character from the left (`character_id=1`) ```bash curl --location 'https://api.useapi.net/v1/kling/videos/motion-create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'workId="-100000000000004"' \ --form 'image="https://s15-kling.klingai.com/…"' \ --form 'character_id="1"' \ --form 'mode="std"' \ --form 'duration="5"' ``` Result <video poster="https://media.useapi.net/blog/2025-10-07-251007/demo-right-1-poster.jpg" src="https://media.useapi.net/blog/2025-10-07-251007/demo-right-1.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> * Create user-defined motion [POST videos/motion-upload](/docs/api-kling-v1/post-kling-videos-motion-upload) Video <video poster="https://media.useapi.net/blog/2025-10-07-251007/gangnam-style-original-poster.jpg" src="https://media.useapi.net/blog/2025-10-07-251007/gangnam-style-original.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> ```bash curl --location 'https://api.useapi.net/v1-dev/kling/videos/motion-upload' \ --header 'Authorization: Bearer user:12345-…' \ --form 'resourceUrl="https://v15-kling.klingai.com/…"' \ --form 'coverUrl="https://s15-kling.klingai.com/…"' ``` Result <video poster="https://media.useapi.net/blog/2025-10-07-251007/gangnam-style-motion-poster.jpg" src="https://media.useapi.net/blog/2025-10-07-251007/gangnam-style-motion.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> * Create Video using one of user-defined motions (see above) [POST videos/motion-create](/docs/api-kling-v1/post-kling-videos-motion-create) [image](https://media.useapi.net/blog/2025-10-07-251007/trump-and-melania.jpg) ```bash curl --location 'https://api.useapi.net/v1/kling/videos/motion-create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'workId="123456789"' \ --form 'image="https://s15-kling.klingai.com/…"' \ --form 'prompt="dancing and having fun"' \ --form 'sound_effect="true"' \ --form 'music_prompt="Gundam Style music blasting"' \ --form 'enable_asmr="true"' \ --form 'character_id="1"' \ --form 'mode="pro"' \ --form 'duration="10"' ``` Result <video poster="https://media.useapi.net/blog/2025-10-07-251007/gangnam-style-result-poster.jpg" src="https://media.useapi.net/blog/2025-10-07-251007/gangnam-style-result.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> Also on YouTube: [Kling Motion Control / Mureka Music](https://youtube.com/shorts/TUAUO5cAlac). === URL: https://useapi.net/blog/251030 === Document URL: https://useapi.net/blog/251030 --- layout: blog_post title: "MiniMax: 2.3 Video Generation Models" description: "MiniMax API v1 has been updated with new video generation models:" parent: Blog nav_exclude: true nav_order: -251030 --- [MiniMax API v1](/docs/api-minimax-v1) has been updated with new video generation models: * Three new models added to [POST videos/create](/docs/api-minimax-v1/post-minimax-videos-create): * `T2V-2.3` - Text-to-Video generation model * `I2V-2.3` - Image-to-Video generation model * `I2V-2.3-Fast` - Image-to-Video Fast generation with faster processing * All new 2.3 models support the `options` parameter for resolution and duration control: `768p-6sec` (default), `768p-10sec`, `1080p-6sec`. #### `T2V-2.3` - Text-to-Video generation model ```bash curl --location 'https://api.useapi.net/v1/minimax/videos/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="T2V-2.3"' \ --form 'options="768p-10sec"' \ --form 'prompt="As the camera slowly zooms out, we see Pennywise the clown riding the carousel, holding a red balloon in his hand."' ``` Result <video poster="https://media.useapi.net/blog/2025-10-30-251030/t2v-2.3-768p-10sec-poster.jpg" src="https://media.useapi.net/blog/2025-10-30-251030/t2v-2.3-768p-10sec.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> Also on YouTube: [Pennywise the Clown • MiniMax T2V 2.3](https://www.youtube.com/watch?v=iIF5wY8Kweg). #### `I2V-2.3` - Image-to-Video generation model [image](https://media.useapi.net/blog/2025-10-30-251030/fancy-dress-jpeg.jpg) ```bash curl --location 'https://api.useapi.net/v1/minimax/videos/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="I2V-2.3"' \ --form 'prompt="She is dancing and spinning around"' \ --form 'options="768p-10sec"' \ --form 'fileID="user:12345-minimax:…-file:…"' ``` Result <video poster="https://media.useapi.net/articles/2024-09-28-minimax-bash/i2v-2.3-768p-10sec-lady-poster.jpg" src="https://media.useapi.net/articles/2024-09-28-minimax-bash/i2v-2.3-768p-10sec-lady.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> Also on YouTube: [The Lady • MiniMax I2V 2.3](https://youtube.com/shorts/pc9WNBGRBg8). #### `I2V-2.3` - Image-to-Video generation model [image](https://media.useapi.net/blog/2025-10-30-251030/flaming-pumpking-jpeg.jpg) ```bash curl --location 'https://api.useapi.net/v1/minimax/videos/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="I2V-2.3"' \ --form 'prompt="A pumpkin-headed figure in burning leather armor takes his head off and throws it to the camera."' \ --form 'options="768p-10sec"' \ --form 'fileID="user:12345-minimax:…-file:…"' ``` Result <video poster="https://media.useapi.net/blog/2025-10-30-251030/i2v-2.3-768p-10sec-pumpkin-poster.jpg" src="https://media.useapi.net/blog/2025-10-30-251030/i2v-2.3-768p-10sec-pumpkin.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> === URL: https://useapi.net/blog/251031 === Document URL: https://useapi.net/blog/251031 --- layout: blog_post title: "Kling: Image Elements Updated to v2.1" description: "Kling API v1 Image Elements endpoint POST images/kolors-elements updated to v2.1." parent: Blog nav_exclude: true nav_order: -251031 --- [Kling API v1](/docs/api-kling-v1) Image Elements endpoint [POST images/kolors-elements](/docs/api-kling-v1/post-kling-images-kolors-elements) updated to v2.1. **Example** Image Elements [POST images/kolors-elements](/docs/api-kling-v1/post-kling-images-kolors-elements) [subjectImage1](https://media.useapi.net/blog/2025-10-31-251031/classi-oil-painting-lady-jpeg.jpg) [sceneImage](https://media.useapi.net/blog/2025-10-31-251031/carousel-jpeg.jpg) ```bash curl --location 'https://api.useapi.net/v1/kling/images/kolors-elements' \ --header 'Authorization: Bearer user:12345-…' \ --form 'subjectImage1="https://s15-kling.klingai.com/…?x-kcdn-pid=112372"' \ --form 'sceneImage="https://s15-kling.klingai.com/…?x-kcdn-pid=112372"' \ --form 'prompt=" Pretty lady riding a carousel"' \ --form 'aspect_ratio="16:9"' ``` Result ![](https://media.useapi.net/blog/2025-10-31-251031/elemets-v2-1.png) === URL: https://useapi.net/blog/251117 === Document URL: https://useapi.net/blog/251117 --- layout: blog_post title: "Google Flow API v1: Initial Release" description: "useapi.net launches its Google Flow API: generate and edit images with Imagen 4 and Nano Banana, and create videos with the Veo 3.1 Quality and Fast models." parent: Blog nav_exclude: true nav_order: -251117 --- [Google Flow API v1](/docs/api-google-flow-v1) initial release: * Generate and edit images with [Imagen 4](https://deepmind.google/technologies/imagen-3/) and [Nano Banana / Gemini 2.5 Flash Image](https://deepmind.google/technologies/gemini/flash/) * Generate videos with [Veo 3.1 Quality and Fast](https://deepmind.google/technologies/veo/) models * Use **free** Google accounts for unlimited image generations * Use [Google AI Ultra](https://one.google.com/ai) $125/m subscription for **unlimited** Veo 3.1 Fast video generations For a step-by-step walkthrough with curl, see the [Veo 3.1 API tutorial](/docs/articles/google-flow-bash). **Examples** * Create image using `imagen-4` [POST images](/docs/api-google-flow-v1/post-google-flow-images) ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'prompt="Cat dressed like a pirate fencing with a real pirate"' \ --form 'model="imagen-4"' \ --form 'aspectRatio="portrait"' \ --form 'count="4"' ``` * Edit image using `nano-banana` [POST images](/docs/api-google-flow-v1/post-google-flow-images) Result ![](https://media.useapi.net/blog/2025-11-17-251117/imagen-4-jpeg.jpg) ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'prompt="Cat dressed like a pirate fencing with a real pirate, pirate looks absolutely terrified"' \ --form 'model="nano-banana"' \ --form 'aspectRatio="portrait"' \ --form 'count="4"' \ --form 'reference_1="user:12345-email:…-image:…"' ``` Result ![](https://media.useapi.net/blog/2025-11-17-251117/nano-banana-jpeg.jpg) * Animate image using `veo-3.1-fast` [POST videos](/docs/api-google-flow-v1/post-google-flow-videos) ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos' \ --header 'Authorization: Bearer user:1234-…' \ --form 'prompt="Brave Captain Cat chasing away the pirates\!"' \ --form 'model="veo-3.1-fast"' \ --form 'aspectRatio="portrait"' \ --form 'startImage="user:12345-email:…-image:…"' \ --form 'count="4"' \ ``` Result <video poster="https://media.useapi.net/blog/2025-11-17-251117/veo-3-1-fast-poster.jpg" src="https://media.useapi.net/blog/2025-11-17-251117/veo-3-1-fast.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> === URL: https://useapi.net/blog/251120 === Document URL: https://useapi.net/blog/251120 --- layout: blog_post title: "Google Flow: Nano Banana Pro Images" description: "Google Flow adds Nano Banana Pro (Gemini 3 Pro Image) for AI image generation." parent: Blog nav_exclude: true nav_order: -251120 --- [Google Flow API v1](/docs/api-google-flow-v1) updates: * [POST /images](/docs/api-google-flow-v1/post-google-flow-images) now supports [Nano Banana Pro / Gemini 3 Pro Image](https://deepmind.google/models/gemini-image/pro/) model (requires [Google AI](https://one.google.com/ai) subscription) * Enhanced 429 error responses to include `metadata` field with `canUpgradeForQuota` information for quota-related errors **Examples** * Generate images using `nano-banana-pro` with Ultra account [POST images](/docs/api-google-flow-v1/post-google-flow-images) ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:12345-…' \ --form 'prompt="Cat dressed like a pirate fencing with a real pirate, pirate looks absolutely terrified, this is happening on a deck of the Disney cruise ship"' \ --form 'model="nano-banana-pro"' \ --form 'aspectRatio="portrait"' \ --form 'count="4"' ``` Result ![](https://media.useapi.net/blog/2025-11-20-251120/nano-banana-pro-text-to-image.jpg) * Edit images using `nano-banana-pro` with reference images [POST images](/docs/api-google-flow-v1/post-google-flow-images) Original ![](https://media.useapi.net/blog/2025-11-20-251120/lady-photo-old-2.jpg) ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:12345-…' \ --form 'prompt="Make this photograph look modern"' \ --form 'model="nano-banana-pro"' \ --form 'aspectRatio="portrait"' \ --form 'count=""' \ --form 'reference_1="user:12345-email:…-image:…"' ``` Result ![](https://media.useapi.net/blog/2025-11-20-251120/nano-banana-pro-image-to-image.jpg) === URL: https://useapi.net/blog/251124 === Document URL: https://useapi.net/blog/251124 --- layout: blog_post title: "MiniMax Agent API: Image, Video, and Audio" description: "MiniMax API v1 on useapi.net adds Agent endpoints for Hailuo 2.3 video, Nano Banana 2/Pro, Seedream 4.0 and Qwen images, and Speech 2.5 and Music 2.0 audio." parent: Blog nav_exclude: true nav_order: -251124 --- [MiniMax API v1](/docs/api-minimax-v1) new Agent API: * New [POST agent](/docs/api-minimax-v1/post-minimax-agent), [GET agent/`jobId`](/docs/api-minimax-v1/get-minimax-agent-jobId), [GET agent/jobs](/docs/api-minimax-v1/get-minimax-agent-jobs) endpoints * MiniMax [agent](/docs/api-minimax-v1/post-minimax-agent) supports multiple AI models including video generation ([Hailuo 2.3](https://hailuoai.video/ai-video-landing/ai-video-generator-hailuo-2-3), [02](https://www.minimax.io/news/minimax-hailuo-02)), image generation ([Nano Banana 2/Pro](https://blog.google/technology/ai/nano-banana-pro/), [Seedream 4.0](https://seed.bytedance.com/en/seedream4_0), [F.1 Kontext](https://bfl.ai/models/flux-kontext), [Qwen](https://github.com/QwenLM/Qwen-Image), Kolors), and audio synthesis ([Speech 2.5](https://minimax-ai.chat/models/minimax-speech-25/), [Music 2.0](https://www.minimax.io/news/minimax-music-20)) It costs 1 to 4 credits to generate an image and 1 credit to generate a song. With the [$79.99/m](https://hailuoai.video/subscribe/modal) Master account (12,000 credits), you can generate ~12,000 songs or up to 12,000 images. Nano Banana 2/Pro costs 4 credits, so you can generate 3,000 images per month. Nano Banana 2/Pro deployment provided by MiniMax has less content moderation compared to Google Flow and is capable of editing photos of minors or famous people. * Image editing with Nano Banana 2/Pro - Photo modernization [POST agent](/docs/api-minimax-v1/post-minimax-agent) Input ![](https://media.useapi.net/blog/2025-11-24-251124/photo-test.jpg) ```bash curl --location 'https://api.useapi.net/v1/minimax/agent' \ --header 'Authorization: Bearer user:12345-…' \ --form 'prompt="Make this photo look modern, retain 100% human face identity."' \ --form 'models="nano-banana-2"' \ --form 'file=@/path/to/old-photo.jpg' ``` Result ![](https://media.useapi.net/blog/2025-11-24-251124/minimax-agent-nano-banan-2-edit-2.png) * Image editing with Nano Banana 2/Pro - Adding objects to people [POST agent](/docs/api-minimax-v1/post-minimax-agent) Input ![](https://media.useapi.net/blog/2025-11-24-251124/trump-melania-2-3-small.webp) ```bash curl --location 'https://api.useapi.net/v1/minimax/agent' \ --header 'Authorization: Bearer user:12345-…' \ --form 'prompt="Make people in the photo wear red MAGA hats."' \ --form 'models="nano-banana-2"' \ --form 'file=@/path/to/photo.jpg' ``` Result ![](https://media.useapi.net/blog/2025-11-24-251124/minimax-agent-nano-banan-2-edit.png) * Speech generation with Speech 2.5 HD - Multilingual Jokes [POST agent](/docs/api-minimax-v1/post-minimax-agent) ```bash curl --location 'https://api.useapi.net/v1/minimax/agent' \ --header 'Authorization: Bearer user:12345-…' \ --form 'prompt="Generate speech using confident female alto voice with sophisticated American accent, articulate and alluring. See provided below text: === English Joke: What do you call a fake noodle? Answer: An Impasta. Spanish Joke: ¿Qué hace un pez? Answer: Nada. (Translation: What does a fish do? Nothing / Swims. It'\''s a pun.) French Joke: Que fait une fraise sur un cheval ? Answer: Tagada tagada! (Translation: What does a strawberry do on a horse? Tagada tagada! - The sound of galloping.) Portuguese Joke: O que o zero disse para o oito? Answer: Belo cinto! (Translation: What did the 0 say to the 8? Nice belt!) Russian Joke: Колобок повесился. Answer: The round bread ball hanged himself. (Dark humor: A ball has no neck.) German Joke: Was ist rot und schlecht für die Zähne? Answer: Ein Backstein. (Translation: What is red and bad for your teeth? A brick.) Italian Joke: Cosa fa un pomodoro al mattino? Answer: La salsa. (Translation: What does a tomato do in the morning? The sauce / The dance.) ==="' \ --form 'models="speech-2.5-hd-preview"' ``` Result <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2025-11-24-251124/minimax-agent-tts.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> * Generate a video from the altered image with a composed soundtrack [POST agent](/docs/api-minimax-v1/post-minimax-agent) Input ![](https://media.useapi.net/blog/2025-11-24-251124/mario.png) ```bash curl --location 'https://api.useapi.net/v1/minimax/agent' \ --header 'Authorization: Bearer user:12345-…' \ --form 'prompt="Remove speech bubbles. Create a video of him dancing, and create a Mario-game inspired soundtrack for the video."' \ --form 'models="nano-banana-2,hailuo-2.3,minimax-music-2.0"' \ --form 'file=@/path/to/mario.jpg' ``` Result: attachment 1/4 - altered image ![](https://media.useapi.net/blog/2025-11-24-251124/minimax-agent-combo-1.png) Result: attachment 2/4 - video <video poster="https://media.useapi.net/blog/2025-11-24-251124/minimax-agent-combo-2-poster.jpg" src="https://media.useapi.net/blog/2025-11-24-251124/minimax-agent-combo-2.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> Result: attachment 3/4 - generated song <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2025-11-24-251124/minimax-agent-combo-3.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Result: attachment 4/4 - final result <video poster="https://media.useapi.net/blog/2025-11-24-251124/minimax-agent-combo-4-poster.jpg" src="https://media.useapi.net/blog/2025-11-24-251124/minimax-agent-combo-4.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> === URL: https://useapi.net/blog/251127 === Document URL: https://useapi.net/blog/251127 --- layout: blog_post title: "Kling v2.5: End Frame Control" description: "Kling API v1 model kling-v2-5 now supports the imagetail parameter for end frame control." parent: Blog nav_exclude: true nav_order: -251127 --- [Kling API v1](/docs/api-kling-v1) model `kling-v2-5` now supports the `image_tail` parameter for end frame control. [POST videos/image2video-frames](/docs/api-kling-v1/post-kling-videos-image2video-frames) can now use both `image` (start frame) and `image_tail` (end frame) with the `kling-v2-5` model, enabling video generation with controlled start and end frames. **Example** [image](https://media.useapi.net/blog/2025-11-27-251127/kling-2-5-first-frame-jpeg.jpg) [image_tail](https://media.useapi.net/blog/2025-11-27-251127/kling-2-5-last-frame-jpeg.jpg) ```bash curl --location 'https://api.useapi.net/v1/kling/videos/image2video-frames' \ --header 'Authorization: Bearer user:12345-…' \ --form 'prompt="Turkey catching a man in the forest"' \ --form 'image="https://s15-kling.klingai.com/…"' \ --form 'image_tail="https://s15-kling.klingai.com/…"' \ --form 'model_name="kling-v2-5"' \ --form 'duration="5"' \ --form 'enable_audio="true"' ``` Result <video poster="https://media.useapi.net/blog/2025-11-27-251127/kling-2-5-first-and-last-frames-poster.jpg" src="https://media.useapi.net/blog/2025-11-27-251127/kling-2-5-first-and-last-frames.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> === URL: https://useapi.net/blog/251128 === Document URL: https://useapi.net/blog/251128 --- layout: blog_post title: "Mureka: O2 and V7.6 Music Models" description: "Mureka API v1 has been updated with new models and increased field limits:" parent: Blog nav_exclude: true nav_order: -251128 --- [Mureka API v1](/docs/api-mureka-v1) has been updated with new models and increased field limits: * New models `O2` and `V7.6` added, with `V7.6` as the new default * Updated field limits: `prompt` 3000, `lyrics` 5000, `desc` 1000 **Instrumental O2** - Galactic Odyssey ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-instrumental' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: application/json' \ --data '{ "prompt": "Cinematic sci-fi soundtrack with pulsing synths, ethereal pads, and massive reverb - interstellar voyage through a neon galaxy", "model": "O2" }' ``` <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2025-11-28-251128/instrumental-o2-galactic-odyssey-v2.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> **Music O2 Female** - Cosmic Barista ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-advanced' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: application/json' \ --data '{ "lyrics": "[Verse 1]\nBrewing lattes on the moon\nSaturn'\''s rings are coming soon\nMars wants extra foam today\nVenus takes her coffee grey\n\n[Chorus]\nI'\''m your cosmic barista queen\nMaking drinks you'\''ve never seen\nEspresso shots across the stars\nFrom Mercury all the way to Mars", "desc": "space disco, funky bass, sparkly synths, groovy and playful", "vocal_gender": "female", "model": "O2" }' ``` <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2025-11-28-251128/music-o2-female-cosmicbarista-cosmic-barista-o2-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> **Music O2 Male** - Robot Dreams ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-advanced' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: application/json' \ --data '{ "lyrics": "[Verse 1]\nI'\''m just a robot dreaming of electric sheep\nCounting binary stars before I go to sleep\nMy circuits hum a melody in ones and zeros deep\nThese silicon memories are mine to keep\n\n[Chorus]\nBeep boop, I'\''m alive tonight\nDancing through the data streams of light\nMaybe I'\''m not human but I feel alright\nRobot dreams are taking flight", "desc": "futuristic synthpop, vocoder harmonies, glitchy beats, retro-futurism", "vocal_gender": "male", "model": "O2" }' ``` <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2025-11-28-251128/music-o2-male-robotdreams-robot-dreams-o2-v2.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> **Music V7.6 Male** - Pirate Programmer ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-advanced' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: application/json' \ --data '{ "lyrics": "[Verse 1]\nYo ho ho and a bottle of code\nDebugging treasures on this binary road\nMy parrot squawks in JavaScript\nWhile I sail the seven internets\n\n[Chorus]\nI'\''m a pirate programmer, arrr!\nSailing through the bugs near and far\nCommit and push to the repo shore\nMerge conflicts? Bring me more!", "desc": "sea shanty meets electronic, accordion, maritime vibes, rebellious energy", "vocal_gender": "male", "model": "V7.6" }' ``` <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2025-11-28-251128/music-v7-6-male-pirateprogrammer-pirate-programmer-v-v1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> === URL: https://useapi.net/blog/251201 === Document URL: https://useapi.net/blog/251201 --- layout: blog_post title: "Google Flow: Nano Banana Pro, 10 References" description: "Google Flow's Nano Banana Pro image generation now supports up to 10 reference images." parent: Blog nav_exclude: true nav_order: -251201 --- [Google Flow API v1](/docs/api-google-flow-v1) updates: * [POST /images](/docs/api-google-flow-v1/post-google-flow-images) `nano-banana-pro` model now supports up to 10 reference images (previously 3) * [GET /accounts](/docs/api-google-flow-v1/get-google-flow-accounts) response simplified to return account summary (health, project, session expiry) without sensitive data Combine multiple reference images with `nano-banana-pro` [POST images](/docs/api-google-flow-v1/post-google-flow-images). Reference images (5 individual portraits): [Star-Lord](https://media.useapi.net/blog/2025-12-01-251201/star-lord-3.jpg) | [Gamora](https://media.useapi.net/blog/2025-12-01-251201/gamora-3.jpg) | [Drax](https://media.useapi.net/blog/2025-12-01-251201/drax-3.jpg) | [Mantis](https://media.useapi.net/blog/2025-12-01-251201/mantis-3.jpg) | [Nebula](https://media.useapi.net/blog/2025-12-01-251201/nebula-3.jpg) ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: application/json' \ --data '{ "prompt": "K-Pop group victory celebration, five members together on stage with confetti and spotlights, award show moment, glamorous outfits, joyful energy mixed with fierce attitudes, concert photography, epic wide shot", "model": "nano-banana-pro", "aspectRatio": "landscape", "count": 4, "reference_1": "user:12345-email:abc123-image:star-lord-ref", "reference_2": "user:12345-email:abc123-image:gamora-ref", "reference_3": "user:12345-email:abc123-image:drax-ref", "reference_4": "user:12345-email:abc123-image:mantis-ref", "reference_5": "user:12345-email:abc123-image:nebula-ref" }' ``` Result: ![](https://media.useapi.net/blog/2025-12-01-251201/result.jpg) === URL: https://useapi.net/blog/251204 === Document URL: https://useapi.net/blog/251204 --- layout: blog_post title: "Kling v2.6: Native Audio Generation" description: "Kling API v1 endpoints POST videos/text2video and POST videos/image2video-frames now support kling-v2-6 model with Native Audio generation (enableaudio: true)." parent: Blog nav_exclude: true nav_order: -251204 --- [Kling API v1](/docs/api-kling-v1) endpoints [POST videos/text2video](/docs/api-kling-v1/post-kling-videos-text2video) and [POST videos/image2video-frames](/docs/api-kling-v1/post-kling-videos-image2video-frames) now support `kling-v2-6` model with Native Audio generation (`enable_audio: true`). **Example** Start image: [Bruce Willis (Nano Banana Pro enhanced)](https://media.useapi.net/blog/2025-12-04-251204/bruce-nano-banana-pro.jpg) ```bash curl --location 'https://api.useapi.net/v1/kling/videos/image2video-frames' \ --header 'Authorization: Bearer user:12345-…' \ --form 'prompt="Bruce Willis says, \"Yippee-ki-yay, motherfucker\!\" and winks at the camera"' \ --form 'image="https://s15-kling.klingai.com/kimg/…"' \ --form 'model_name="kling-v2-6"' \ --form 'mode="pro"' \ --form 'duration="5"' \ --form 'enable_audio="true"' ``` Result <video poster="https://media.useapi.net/blog/2025-12-04-251204/bruce-kling-2-6-poster.jpg" src="https://media.useapi.net/blog/2025-12-04-251204/bruce-kling-2-6.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> Also on YouTube: [Christmas is Coming • Kling v2.6](https://www.youtube.com/watch?v=oqVPl9V9jIw). === URL: https://useapi.net/blog/251205 === Document URL: https://useapi.net/blog/251205 --- layout: blog_post title: "PixVerse v5.5: Native Audio Generation" description: "PixVerse API v2 now supports model v5.5 with integrated native audio generation via audio: true parameter." parent: Blog nav_exclude: true nav_order: -251205 --- [PixVerse API v2](/docs/api-pixverse-v2) now supports model `v5.5` with integrated native audio generation via `audio: true` parameter. **Image-to-Video with Audio** Start image: [Flirty Barista](https://media.useapi.net/blog/2025-12-05-251205/flirtybarista.jpg) ```bash curl -X POST "https://api.useapi.net/v2/pixverse/videos/create" \ -H "Authorization: Bearer user:12345-…" \ -H "Content-Type: application/json" \ -d '{ "prompt": "The barista winks slowly and whispers You look almost as hot as the coffee I made you", "model": "v5.5", "duration": "5", "quality": "540p", "first_frame_path": "upload/....jpg", "audio": true }' ``` Result: <video poster="https://media.useapi.net/blog/2025-12-05-251205/1764921439704-i2v-v55-540p-audio-barista-sound-poster.jpg" src="https://media.useapi.net/blog/2025-12-05-251205/1764921439704-i2v-v55-540p-audio-barista-sound.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> **Text-to-Video 1080p** ```bash curl -X POST "https://api.useapi.net/v2/pixverse/videos/create" \ -H "Authorization: Bearer user:12345-…" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A family of ducks crossing a busy street while cars stop and wait, pedestrians watching and smiling", "model": "v5.5", "duration": "5", "quality": "1080p", "aspect_ratio": "16:9" }' ``` Result: <video poster="https://media.useapi.net/blog/2025-12-05-251205/1764919367746-t2v-v55-1080p-ducks-poster.jpg" src="https://media.useapi.net/blog/2025-12-05-251205/1764919367746-t2v-v55-1080p-ducks.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> === URL: https://useapi.net/blog/251210 === Document URL: https://useapi.net/blog/251210 --- layout: blog_post title: "Kling: Image O1 (Omni) Generation" description: "Kling's O1 (Omni) image-generation endpoint — reference uploaded images with @image1/@image2 placeholders in your prompt." parent: Blog nav_exclude: true nav_order: -251210 --- [Kling API v1](/docs/api-kling-v1) updates: * New [POST images/omni](/docs/api-kling-v1/post-kling-images-omni) endpoint for Image O1 (Omni) generation * Supports text-to-image and up to 10 reference images via `@image_1`…`@image_10` placeholders * Resolution options: `1k` (default), `2k` **Text-to-Image, 2K** ```bash curl -X POST "https://api.useapi.net/v1/kling/images/omni" \ -H "Authorization: Bearer user:12345-…" \ -H "Content-Type: application/json" \ -d '{ "email": "your-kling-account@example.com", "prompt": "Ice queen playing chess with fire elemental, pieces melting and freezing, dramatic tension", "resolution": "2k", "aspect_ratio": "16:9", "imageCount": 5 }' ``` Results: ![Kling O1 Text-to-Image](https://media.useapi.net/blog/2025-12-10-251210/kling-omni-text-to-image.png) **With Two Reference Images, 2K** Use `@image_1`, `@image_2`, etc. placeholders to reference uploaded images in your prompt. Upload reference images using [POST /assets](/docs/api-kling-v1/post-kling-assets) first. Reference images: * [Cow girl](https://media.useapi.net/blog/2025-12-10-251210/cow-girl-jpeg.jpg) * [Ostrich](https://media.useapi.net/blog/2025-12-10-251210/crazy-looking-ostrich-jpeg.jpg) ```bash curl -X POST "https://api.useapi.net/v1/kling/images/omni" \ -H "Authorization: Bearer user:12345-…" \ -H "Content-Type: application/json" \ -d '{ "email": "your-kling-account@example.com", "prompt": "@image_1 riding @image_2 on a busy NY street", "resolution": "2k", "aspect_ratio": "16:9", "imageCount": 3, "image_1": "https://s21-kling.klingai.com/ai-platform/xxx/xxx.jpg", "image_2": "https://s21-kling.klingai.com/ai-platform/yyy/yyy.jpg" }' ``` Results: ![Kling O1 with References](https://media.useapi.net/blog/2025-12-10-251210/kling-images-omni-results.png) === URL: https://useapi.net/blog/251211 === Document URL: https://useapi.net/blog/251211 --- layout: blog_post title: "Kling: Video O1 (Omni) Generation Endpoint" description: "Kling's O1 (Omni) video-generation endpoint — reference uploaded images with @image placeholders in your prompt." parent: Blog nav_exclude: true nav_order: -251211 --- [Kling API v1](/docs/api-kling-v1) updates: * New [POST videos/omni](/docs/api-kling-v1/post-kling-videos-omni) endpoint for Video O1 (Omni) generation * Supports text-to-video and up to 7 reference images (or 1 video + 4 images) via `@image_1`…`@image_7`, `@video_1` placeholders * Duration options: `3`-`10` seconds (7-10 require VIP) * Aspect ratio options: `16:9`, `9:16`, `1:1`, `auto` (auto when video reference used) **Text-to-Video** ```bash curl -X POST "https://api.useapi.net/v1/kling/videos/omni" \ -H "Authorization: Bearer user:12345-…" \ -H "Content-Type: application/json" \ -d '{ "email": "your-kling-account@example.com", "prompt": "Tiny fairy mechanic fixing a broken butterfly wing with welding torch, macro photography style", "duration": "5", "aspect_ratio": "16:9" }' ``` Result: <video poster="https://media.useapi.net/blog/2025-12-11-251211/kling-omni-text-to-video-result-poster.jpg" src="https://media.useapi.net/blog/2025-12-11-251211/kling-omni-text-to-video-result.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> **Reference Images to Video** Use `@image_1`, `@image_2`, etc. placeholders to reference uploaded images in your prompt. Upload reference images using [POST /assets](/docs/api-kling-v1/post-kling-assets) first. Reference images: [Cow girl](https://media.useapi.net/blog/2025-12-10-251210/cow-girl-jpeg.jpg) • [BMW R32 Motorcycle](https://media.useapi.net/blog/2025-12-11-251211/1932-bmw-r32-jpeg.jpg) ```bash curl -X POST "https://api.useapi.net/v1/kling/videos/omni" \ -H "Authorization: Bearer user:12345-…" \ -H "Content-Type: application/json" \ -d '{ "email": "your-kling-account@example.com", "prompt": "@image_1 dressed like a heavy metal rock star riding her motorcycle @image_2 under the Golden Gate bridge, dynamic action scene", "duration": "10", "aspect_ratio": "16:9", "image_1": "https://s21-kling.klingai.com/…/cow_girl.jpg", "image_2": "https://s21-kling.klingai.com/…/bmw_r32.jpg" }' ``` Result: <video poster="https://media.useapi.net/blog/2025-12-11-251211/kling-omni-ref-images-to-vidoe-result-poster.jpg" src="https://media.useapi.net/blog/2025-12-11-251211/kling-omni-ref-images-to-vidoe-result.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> **Video + Image Reference** Combine a video reference with image references. When `video_1` is provided, `aspect_ratio` is automatically set to `auto`. Maximum 4 images can be used alongside a video reference. <details markdown="block"> <summary><b>Input Video</b></summary> <video poster="https://media.useapi.net/blog/2025-12-11-251211/coke-ad-short-poster.jpg" src="https://media.useapi.net/blog/2025-12-11-251211/coke-ad-short.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> </details> ```bash curl -X POST "https://api.useapi.net/v1/kling/videos/omni" \ -H "Authorization: Bearer user:12345-…" \ -H "Content-Type: application/json" \ -d '{ "email": "your-kling-account@example.com", "prompt": "On the @video_1 replace coke can with @image_1", "video_1": "https://s21-kling.klingai.com/…/coke-ad.mp4", "image_1": "https://s21-kling.klingai.com/…/redbull.jpg" }' ``` Result: <video poster="https://media.useapi.net/blog/2025-12-11-251211/kling-omni-video-to-video-result-poster.jpg" src="https://media.useapi.net/blog/2025-12-11-251211/kling-omni-video-to-video-result.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> === URL: https://useapi.net/blog/251215 === Document URL: https://useapi.net/blog/251215 --- layout: blog_post title: "Runway: Gen-4.5 Text-to-Video" description: "Runway API on useapi.net adds POST gen4_5/create for Gen-4.5 text-to-video at a fixed 720p 16:9, with 5, 8, or 10 second durations and exploreMode support." parent: Blog nav_exclude: true nav_order: -251215 --- [Runway API v1](/docs/api-runwayml-v1) updates: * New [POST gen4_5/create](/docs/api-runwayml-v1/post-runwayml-gen4_5-create) endpoint for Gen-4.5 text-to-video generation * Text-to-video only (no image input required) * Duration options: `5` (default), `8`, `10` seconds * Fixed 720p 16:9 resolution (1280x720) * Supports `exploreMode` for Unlimited plan users ```bash curl -X POST "https://api.useapi.net/v1/runwayml/gen4_5/create" \ -H "Authorization: Bearer user:12345-…" \ -H "Content-Type: application/json" \ -d '{ "text_prompt": "A dramatic film-noir-style scene of a pretty lady dressed in a Christmas costume. The tones are deep and high-contrast, with rich shadows and bright highlights that create a stark, cinematic tension. The lighting is directional and theatrical, evocative of classic 1940s noir photography — exaggerated grainy texture, dramatic silhouettes, and a sense of narrative suspense.", "seconds": 5 }' ``` <video poster="https://media.useapi.net/articles/2024-08-11-runway-bash/runway45result-poster.jpg" src="https://media.useapi.net/articles/2024-08-11-runway-bash/runway45result.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> Also on YouTube: [Noir Christmas • Runway Gen-4.5](https://www.youtube.com/watch?v=I8esy4sKMwo). === URL: https://useapi.net/blog/260102 === Document URL: https://useapi.net/blog/260102 --- layout: blog_post title: "MiniMax: Sora 2 and Veo 3.1" description: "MiniMax API v1 now supports Sora 2 (OpenAI) and Veo 3.1 (Google DeepMind) video models via POST /videos/create." parent: Blog nav_exclude: true nav_order: -260102 --- [MiniMax API v1](/docs/api-minimax-v1) now supports [Sora 2](https://openai.com/sora/) (OpenAI) and [Veo 3.1](https://deepmind.google/models/veo/) (Google DeepMind) video models via [POST /videos/create](/docs/api-minimax-v1/post-minimax-videos-create). **Step 1: Generate Start Frame with GPT Image 1.5** Reference image: [Pink Hair Lady](https://media.useapi.net/blog/2026-01-02-260102/pink-hair-lady.jpg) ```bash curl -X POST "https://api.useapi.net/v1/minimax/images/create" \ -H "Authorization: Bearer user:12345-..." \ -F 'model="gpt-image-1.5"' \ -F 'prompt="She is pulled over on the side of a busy highway, standing next to a police car with flashing lights. A police officer is holding a ticket. Instead of signing it, she looks the officer dead in the eye and starts a high-speed, aggressive robot dance. She shouts over the traffic: YOU CANT GIVE A ROBOT A TICKET, OFFICER! IM NOT TECHNICALLY DRIVING, IM UPLOADING! 4K, realistic roadside lighting, handheld witness camera style."' \ -F 'aspectRatio="3:2"' \ -F 'resolution="2k"' \ -F 'referenceFileId1="user:...-minimax:...-file:..."' ``` Result (cropped to 1280x720 for Sora 2 which requires exact dimensions): [GPT Image 1.5 Result](https://media.useapi.net/blog/2026-01-02-260102/cropped-to-1280x720-sora-2-start-frame-gpt-image-1.5.jpg) **Step 2: Sora 2 Video with Start Frame** Sora 2 requires exact image dimensions: 1280x720 (16:9) or 720x1280 (9:16). ```bash curl -X POST "https://api.useapi.net/v1/minimax/videos/create" \ -H "Authorization: Bearer user:12345-..." \ -F 'model="Sora-2"' \ -F 'options="720p-8sec"' \ -F 'aspectRatio="16:9"' \ -F 'prompt="She is pulled over on the side of a busy highway, standing next to a police car with flashing lights. A police officer is holding a ticket. Instead of signing it, she looks the officer dead in the eye and starts a high-speed, aggressive robot dance. She shouts over the traffic: YOU CANT GIVE A ROBOT A TICKET, OFFICER! IM NOT TECHNICALLY DRIVING, IM UPLOADING! 4K, realistic roadside lighting, handheld witness camera style."' \ -F 'fileID="user:...-minimax:...-file:..."' ``` Result: <video poster="https://media.useapi.net/blog/2026-01-02-260102/sora-2-with-start-frame-poster.jpg" src="https://media.useapi.net/blog/2026-01-02-260102/sora-2-with-start-frame.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> **Step 3: Veo 3.1 Subject Reference** Veo-3.1-S2V maintains character/subject consistency using a reference image (no exact dimension requirements). ```bash curl -X POST "https://api.useapi.net/v1/minimax/videos/create" \ -H "Authorization: Bearer user:12345-..." \ -F 'model="Veo-3.1-S2V"' \ -F 'options="veo-720p-8sec"' \ -F 'aspectRatio="16:9"' \ -F 'prompt="She is pulled over on the side of a busy highway, standing next to a police car with flashing lights. A police officer is holding a ticket. Instead of signing it, she looks the officer dead in the eye and starts a high-speed, aggressive robot dance. She shouts over the traffic: YOU CANT GIVE A ROBOT A TICKET, OFFICER! IM NOT TECHNICALLY DRIVING, IM UPLOADING! 4K, realistic roadside lighting, handheld witness camera style."' \ -F 'fileID="user:...-minimax:...-file:..."' ``` Result: <video poster="https://media.useapi.net/articles/2024-09-28-minimax-bash/minimax-veo-3-1-with-subject-ref-poster.jpg" src="https://media.useapi.net/articles/2024-09-28-minimax-bash/minimax-veo-3-1-with-subject-ref.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> === URL: https://useapi.net/blog/260106 === Document URL: https://useapi.net/blog/260106 --- layout: blog_post title: "Kling: Motion Control v2.6" description: "Kling API v1 now supports Motion Control using the v2.6 API via POST /videos/motion-create." parent: Blog nav_exclude: true nav_order: -260106 --- [Kling API v1](/docs/api-kling-v1) now supports Motion Control using the v2.6 API via [POST /videos/motion-create](/docs/api-kling-v1/post-kling-videos-motion-create). Apply motion from a reference video to any image - the character in the image will perform the motion from the video. Optionally keep the original audio and add a prompt to guide the generation. **Source Image:** [Super Model](https://media.useapi.net/blog/2026-01-06-260106/super-model.png) **Motion Reference Video (Gangnam Style):** <video poster="https://media.useapi.net/blog/2026-01-06-260106/gangnam-style-original-poster.jpg" src="https://media.useapi.net/blog/2026-01-06-260106/gangnam-style-original.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> **API Request:** ```bash curl -X POST "https://api.useapi.net/v1/kling/videos/motion-create" \ -H "Authorization: Bearer user:12345-..." \ -F 'email="my@gmail.com"' \ -F 'motionUrl="https://v15-kling.klingai.com/....mp4?x-kcdn-pid=112372"' \ -F 'imageUrl="https://s15-kling.klingai.com/....origin?x-kcdn-pid=112372"' \ -F 'prompt="On the beach"' \ -F 'mode="std"' \ -F 'motionDirection="image_direction"' \ -F 'keepAudio="true"' ``` **Result (with audio and prompt "On the beach"):** <video poster="https://media.useapi.net/blog/2026-01-06-260106/kling-motion-control-2.6-result-with-sound-and-prompt-poster.jpg" src="https://media.useapi.net/blog/2026-01-06-260106/kling-motion-control-2.6-result-with-sound-and-prompt.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> Key features: - `keepAudio: true` - Preserves original audio from motion video - `motionDirection: image_direction` - Generated video follows pose from source image - `prompt` - Guide the scene with text description - Use [GET /videos/motions](/docs/api-kling-v1/get-kling-videos-motions) to retrieve official Kling motions or your previously uploaded motions === URL: https://useapi.net/blog/260112 === Document URL: https://useapi.net/blog/260112 --- layout: blog_post title: "Kling: Elements and Avatars 2.0" description: "Kling API v1 now supports Elements and Avatars 2.0 for creating reusable character/object references and AI-powered lip-sync video generation." parent: Blog nav_exclude: true nav_order: -260112 --- ## Table of contents [Kling API v1](/docs/api-kling-v1) now supports [Elements](/docs/api-kling-v1/get-kling-elements) and [Avatars 2.0](/docs/api-kling-v1/get-kling-avatars) for creating reusable character/object references and AI-powered lip-sync video generation. **Elements** are saved character/object references that can be reused across multiple O1 generations using the `@element_N` syntax. Create elements with [POST /elements](/docs/api-kling-v1/post-kling-elements), then reference them in [POST /images/omni](/docs/api-kling-v1/post-kling-images-omni) and [POST /videos/omni](/docs/api-kling-v1/post-kling-videos-omni). **Avatars 2.0** are digital characters that can be animated with AI-powered lip-sync using [POST /avatars/video](/docs/api-kling-v1/post-kling-avatars-video). Create avatars from any image with [POST /avatars](/docs/api-kling-v1/post-kling-avatars). ## Avatars 2.0 with Lip-Sync Create talking avatars from any image with AI-powered lip-sync and TTS. **Avatar Image:** [Vlogger](https://media.useapi.net/blog/2026-01-12-260112/vlogger.jpg) ```bash curl -X POST "https://api.useapi.net/v1/kling/avatars/video" \ -H "Authorization: Bearer user:12345-..." \ -H "Content-Type: application/json" \ -d '{ "avatarId": "your_avatar_id", "prompt": "She is holding hot coffee cup in her hands and smiling.", "text": "Hello there! What is your name?", "ttsSpeed": 1.2, "ttsSpeaker": "moss_audio_ad5baf92-735f-11f0-8263-fe5a2fe98ec8" }' ``` **Result:** <video poster="https://media.useapi.net/blog/2026-01-12-260112/avatar-results-poster.jpg" src="https://media.useapi.net/blog/2026-01-12-260112/avatar-results.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> Also on YouTube: [Kling Avatar 2.0](https://youtube.com/shorts/nKw61pdzFmw). ## Video O1 with Images and Elements Mix reference images with saved elements for video generation. **Reference Images:** [@image_1](https://media.useapi.net/blog/2026-01-12-260112/actor.jpg) • [@image_2](https://media.useapi.net/blog/2026-01-12-260112/scene.jpg) **Element:** [@element_1](https://media.useapi.net/blog/2026-01-12-260112/lady.jpg) ```bash curl -X POST "https://api.useapi.net/v1/kling/videos/omni" \ -H "Authorization: Bearer user:12345-..." \ -H "Content-Type: application/json" \ -d '{ "prompt": "@image_1 and @element_1 practicing hand-to-hand combat training at @image_2", "duration": "3", "aspect_ratio": "16:9", "image_1": "https://s21-kling.klingai.com/.../actor.jpg", "image_2": "https://s21-kling.klingai.com/.../scene.jpg", "element_1": "u_lady_element_id" }' ``` **Result:** <video poster="https://media.useapi.net/blog/2026-01-12-260112/video-o1-image-and-element-poster.jpg" src="https://media.useapi.net/blog/2026-01-12-260112/video-o1-image-and-element.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> Also on YouTube: [Kling Video O1](https://www.youtube.com/watch?v=rUcVpqwcNVY). ## Video O1 Element Transitions Create magical transitions between elements. **Elements:** [@element_1](https://media.useapi.net/blog/2026-01-12-260112/lady.jpg) • [@element_2](https://media.useapi.net/blog/2026-01-12-260112/super-woman-costume.jpg) ```bash curl -X POST "https://api.useapi.net/v1/kling/videos/omni" \ -H "Authorization: Bearer user:12345-..." \ -H "Content-Type: application/json" \ -d '{ "prompt": "@element_1 magically transition to @element_2", "duration": "5", "aspect_ratio": "9:16", "element_1": "u_lady_element_id", "element_2": "u_costume_element_id" }' ``` **Result:** <video poster="https://media.useapi.net/blog/2026-01-12-260112/vidoe-o1-elements-poster.jpg" src="https://media.useapi.net/blog/2026-01-12-260112/vidoe-o1-elements.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> ## Video O1 Start/End Frames Generate video transitions between start and end frame images. **Frame Images:** [frame_start](https://media.useapi.net/blog/2026-01-12-260112/lady.jpg) • [frame_end](https://media.useapi.net/blog/2026-01-12-260112/super-woman-costume.jpg) ```bash curl -X POST "https://api.useapi.net/v1/kling/videos/omni" \ -H "Authorization: Bearer user:12345-..." \ -H "Content-Type: application/json" \ -d '{ "prompt": "@image_1 magically transition to @image_2", "duration": "4", "aspect_ratio": "9:16", "frame_start": "https://s21-kling.klingai.com/.../lady.jpg", "frame_end": "https://s21-kling.klingai.com/.../super_woman.jpg" }' ``` **Result:** <video poster="https://media.useapi.net/blog/2026-01-12-260112/video-o1-strat-end-frames-poster.jpg" src="https://media.useapi.net/blog/2026-01-12-260112/video-o1-strat-end-frames.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> ## Video O1 with Video Reference Combine elements with video references to transfer motion. **Element:** [@element_1](https://media.useapi.net/blog/2026-01-12-260112/lady.jpg) <details markdown="block"> <summary><b>Video: [@video_1]</b></summary> <video poster="https://media.useapi.net/blog/2026-01-12-260112/cool-dance-moves-poster.jpg" src="https://media.useapi.net/blog/2026-01-12-260112/cool-dance-moves.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> </details> ```bash curl -X POST "https://api.useapi.net/v1/kling/videos/omni" \ -H "Authorization: Bearer user:12345-..." \ -H "Content-Type: application/json" \ -d '{ "prompt": "@element_1 dancing like @video_1", "element_1": "u_lady_element_id", "video_1": "https://s21-kling.klingai.com/.../cool_dance_moves.mp4" }' ``` **Result:** <video poster="https://media.useapi.net/blog/2026-01-12-260112/video-o1-element-and-video-poster.jpg" src="https://media.useapi.net/blog/2026-01-12-260112/video-o1-element-and-video.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> ## Image O1 with Elements Combine reference images and saved elements in a single prompt for complex compositions. **Reference Images:** [@image_1](https://media.useapi.net/blog/2026-01-12-260112/actor.jpg) • [@image_2](https://media.useapi.net/blog/2026-01-12-260112/scene.jpg) **Elements:** [@element_1](https://media.useapi.net/blog/2026-01-12-260112/lady.jpg) • [@element_2](https://media.useapi.net/blog/2026-01-12-260112/super-woman-costume.jpg) • [@element_3](https://media.useapi.net/blog/2026-01-12-260112/warrior.jpg) ```bash curl -X POST "https://api.useapi.net/v1/kling/images/omni" \ -H "Authorization: Bearer user:12345-..." \ -H "Content-Type: application/json" \ -d '{ "prompt": "Lady warrior @image_1 and her friend @element_1 who is wearing dress @element_2 fight against the alien @element_3 at the factory @image_2, epic poster", "aspect_ratio": "16:9", "unlimited": true, "image_1": "https://s21-kling.klingai.com/.../actor.jpg", "image_2": "https://s21-kling.klingai.com/.../scene.jpg", "element_1": "u_lady_element_id", "element_2": "u_costume_element_id", "element_3": "u_warrior_element_id" }' ``` **Result:** ![Image O1 Result](https://media.useapi.net/blog/2026-01-12-260112/image-o1-results.png) Key endpoints: - [POST /elements](/docs/api-kling-v1/post-kling-elements) - Create reusable elements - [GET /elements](/docs/api-kling-v1/get-kling-elements) - List your elements - [POST /avatars](/docs/api-kling-v1/post-kling-avatars) - Create avatars - [GET /avatars](/docs/api-kling-v1/get-kling-avatars) - List your avatars - [POST /avatars/video](/docs/api-kling-v1/post-kling-avatars-video) - Generate lip-sync video - [GET /tts/voices](/docs/api-kling-v1/get-kling-tts-voices) - Available TTS voices === URL: https://useapi.net/blog/260113 === Document URL: https://useapi.net/blog/260113 --- layout: blog_post title: "Google Flow: Veo 3.1 Portrait R2V" description: "Google Flow API v1 R2V (Reference-to-Video) now supports portrait aspect ratio with Veo 3.1 models." parent: Blog nav_exclude: true nav_order: -260113 --- [Google Flow API v1](/docs/api-google-flow-v1) R2V (Reference-to-Video) now supports portrait aspect ratio with Veo 3.1 models. For a step-by-step walkthrough with curl, see the [Veo 3.1 API tutorial](/docs/articles/google-flow-bash). **Veo 3.1 Ultra Fast Relaxed - Portrait R2V Demo** Reference image: [Lady](https://media.useapi.net/blog/2026-01-12-260112/lady.jpg) ```bash curl -X POST "https://api.useapi.net/v1/google-flow/videos" \ -H "Authorization: Bearer user:12345-..." \ -H "Content-Type: application/json" \ -d '{ "prompt": "dancing cha-cha", "model": "veo-3.1-fast-relaxed", "aspectRatio": "portrait", "referenceImage_1": "user:...-email:...-mediaGenerationId:..." }' ``` Result: <video poster="https://media.useapi.net/blog/2026-01-13-260113/dancing-cha-cha-poster.jpg" src="https://media.useapi.net/blog/2026-01-13-260113/dancing-cha-cha.mp4" style="width: 100%; max-width: 400px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> R2V mode now works with both `landscape` and `portrait` aspect ratios using `veo-3.1-fast` and `veo-3.1-fast-relaxed` models. === URL: https://useapi.net/blog/260120 === Document URL: https://useapi.net/blog/260120 --- layout: blog_post title: "Google Flow: Video Upscale and GIF" description: "Google Flow API v1 new video upscaling and GIF generation endpoints:" parent: Blog nav_exclude: true nav_order: -260120 --- [Google Flow API v1](/docs/api-google-flow-v1) new video upscaling and GIF generation endpoints: * [POST /videos/upscale](/docs/api-google-flow-v1/post-google-flow-videos-upscale) - Upscale videos to 1080p or 4K resolution * [POST /videos/gif](/docs/api-google-flow-v1/post-google-flow-videos-gif) - Generate animated GIF preview from video **Examples** * Generate video using `veo-3.1-fast` [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos' \ --header 'Authorization: Bearer user:12345-…' \ --form 'prompt="Cinematography: A dynamic tracking shot. The camera starts on a low-angle close-up of a 21-year-old Roman woman'\''s face, then pulls back to reveal the chaos behind her. Subject & Action: The woman has perfectly styled hair and a vibrant, shimmering silk teal and gold tunic. She is pouting, making a \"duck face,\" and holding a rose-gold iPhone high for a selfie, checking her reflection in the screen. Background: In the background, the streets of Pompeii are a hellscape. Roman legionaries in full armor and screaming civilians in dirty tunics are sprinting past her toward the camera, eyes wide with terror. A massive, looming Mt. Vesuvius erupts in the far distance, spewing a colossal, mushroom-shaped cloud of black ash and glowing red lava. Style & Lighting: Cinematic realism. High-contrast \"Chiaroscuro\" lighting—the orange glow of the volcano clashing with the cool daylight. Audio: The deafening roar of the volcano, the rhythmic thumping of soldiers'\'' sandals on cobblestone, and the woman'\''s faint, bubbly voice saying, \"OMG, the lighting is literally fire right now.\""' \ --form 'model="veo-3.1-fast"' \ --form 'aspectRatio="portrait"' ``` Result (720p) <video poster="https://media.useapi.net/blog/2026-01-20-260120/veo-3-1-fast-portrait-720p-poster.jpg" src="https://media.useapi.net/blog/2026-01-20-260120/veo-3-1-fast-portrait-720p.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> * Upscale to 1080p using [POST /videos/upscale](/docs/api-google-flow-v1/post-google-flow-videos-upscale) ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos/upscale' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: application/json' \ --data '{ "mediaGenerationId": "user:12345-email:…-video:…", "resolution": "1080p" }' ``` Result (1080p) <video poster="https://media.useapi.net/blog/2026-01-20-260120/veo-3-1-fast-portrait-upscaled-1080p-poster.jpg" src="https://media.useapi.net/blog/2026-01-20-260120/veo-3-1-fast-portrait-upscaled-1080p.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> * Upscale to 4K using [POST /videos/upscale](/docs/api-google-flow-v1/post-google-flow-videos-upscale) (requires Ultra) ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos/upscale' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: application/json' \ --data '{ "mediaGenerationId": "user:12345-email:…-video:…", "resolution": "4K" }' ``` Result (4K) <video poster="https://media.useapi.net/blog/2026-01-20-260120/veo-3-1-fast-portrait-upscaled-4k-poster.jpg" src="https://media.useapi.net/blog/2026-01-20-260120/veo-3-1-fast-portrait-upscaled-4k.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> Also on YouTube: [Let me take a #SELFIE • Veo 3.1 Fast 1080p Upscaled](https://youtube.com/shorts/k38RWvjHHtA). * Generate GIF preview using [POST /videos/gif](/docs/api-google-flow-v1/post-google-flow-videos-gif) ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos/gif' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: application/json' \ --data '{ "mediaGenerationId": "user:12345-email:…-video:…" }' ``` Result ![](https://media.useapi.net/blog/2026-01-20-260120/veo-3-1-fast-portrait-gif.gif) === URL: https://useapi.net/blog/260121 === Document URL: https://useapi.net/blog/260121 --- layout: blog_post title: "Mureka: Async Job Processing" description: "Mureka API v1 now supports async job processing for music and speech generation:" parent: Blog nav_exclude: true nav_order: -260121 --- [Mureka API v1](/docs/api-mureka-v1) now supports async job processing for music and speech generation: * [GET /jobs](/docs/api-mureka-v1/get-mureka-jobs) - List running jobs for an account * [GET /jobs/`jobid`](/docs/api-mureka-v1/get-mureka-jobs-jobid) - Get job status and results * `async` and `replyUrl` parameters added to all generation endpoints **Examples** * Create song using O2 model with [POST /music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced) ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-advanced' \ --header 'Authorization: Bearer user:12345-…' \ --form 'lyrics="[verse] Three souls, one fight Gold and dust tonight Stand tall, no fear The showdown is here [chorus] The good, the bad and the ugly, woh-oh-oh! The good, the bad and the ugly! The good, the bad and the ugly! We'\''re fighting like the good, the bad and the ugly! We'\''re fighting like the good, the bad and the ugly! We'\''re fighting like someone'\''s going to win! The good, the bad and the ugly! We'\''re fighting like the good, the bad and the ugly! We'\''re fighting like the good, the bad and the ugly! We'\''re fighting like someone'\''s going to win!"' \ --form 'model="O2"' \ --form 'desc="eurodance, jungle, breakbeat, drum and bass, dark, energetic"' \ --form 'async="true"' ``` Result <audio src="https://media.useapi.net/blog/2026-01-21-260121/create-advanced.mp3" style="width: 100%;" controls preload="metadata"></audio> * Extend the song with new lyrics using [POST /music/extend](/docs/api-mureka-v1/post-mureka-music-extend) ```bash curl --location 'https://api.useapi.net/v1/mureka/music/extend' \ --header 'Authorization: Bearer user:12345-…' \ --form 'song_id="user:12345-mureka:…-song:…"' \ --form 'lyrics="[verse] Draw fast, aim true It'\''s me versus you High noon, last chance This is our final dance [chorus] The good, the bad and the ugly, woh-oh-oh! The good, the bad and the ugly! The good, the bad and the ugly! We'\''re fighting like the good, the bad and the ugly! We'\''re fighting like the good, the bad and the ugly! We'\''re fighting like someone'\''s going to win! The good, the bad and the ugly! We'\''re fighting like the good, the bad and the ugly! We'\''re fighting like the good, the bad and the ugly! We'\''re fighting like someone'\''s going to win!"' \ --form 'async="true"' ``` Result <audio src="https://media.useapi.net/blog/2026-01-21-260121/extend.mp3" style="width: 100%;" controls preload="metadata"></audio> === URL: https://useapi.net/blog/260123 === Document URL: https://useapi.net/blog/260123 --- layout: blog_post title: "Runway Gen-4.5: Image-to-Video" description: "Runway API on useapi.net extends POST gen4_5/create with Gen-4.5 image-to-video via firstImage_assetId, six aspect ratios, and 5, 8, or 10 second clips." parent: Blog nav_exclude: true nav_order: -260123 --- [Runway API v1](/docs/api-runwayml-v1) updates: * [POST gen4_5/create](/docs/api-runwayml-v1/post-runwayml-gen4_5-create) now supports **Image-to-Video (I2V)** * Use `firstImage_assetId` parameter to generate video from an image * Supports all aspect ratios: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9` * Duration options: `5` (default), `8`, `10` seconds **Source Image:** <img src="https://media.useapi.net/blog/2026-01-23-260123/mandalorian.webp" style="width: 100%; max-width: 400px;" /> **Request:** ```bash curl --location 'https://api.useapi.net/v1/runwayml/gen4_5/create' \ --header 'Authorization: Bearer user:12345-…' \ --data-urlencode 'seconds=8' \ --data-urlencode 'text_prompt=Epic close-up of an ornate golden warrior helmet with intricate engravings. The camera pulls back in a dramatic zoom-out as the armored figure draws a sleek glowing energy sword. The blade ignites with crackling white light, casting a flickering cold glow onto the golden faceplate. Hyper-realistic metallic reflections, cinematic lighting, continuous shot.' \ --data-urlencode 'firstImage_assetId=user:12345-runwayml:user@gmail.com-asset:…' \ --data-urlencode 'aspect_ratio=9:16' ``` **Result:** <video poster="https://media.useapi.net/articles/2024-08-11-runway-bash/runway-gen4-5-i2v-result-poster.jpg" src="https://media.useapi.net/articles/2024-08-11-runway-bash/runway-gen4-5-i2v-result.mp4" style="width: 100%; max-width: 400px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> === URL: https://useapi.net/blog/260126 === Document URL: https://useapi.net/blog/260126 --- layout: blog_post title: "PixVerse: Modify Video Content" description: "PixVerse API v2 now supports POST videos/modify to modify video content based on your prompt." parent: Blog nav_exclude: true nav_order: -260126 --- [PixVerse API v2](/docs/api-pixverse-v2) now supports [POST videos/modify](/docs/api-pixverse-v2/post-pixverse-videos-modify) to modify video content based on your prompt. **Step 1: Create video from image** Source image: <img src="https://media.useapi.net/blog/2026-01-26-260126/lady-and-the-dragon.webp" style="width: 100%; max-width: 400px;" /> ```bash curl --location 'https://api.useapi.net/v2/pixverse/videos/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'prompt="The dragon dives forward through the clouds. The camera tracks alongside the dragon'"'"'s head and then performs a smooth zoom into the rider'"'"'s face. She leans forward, gripping the dragon. High motion, realistic wind physics, epic cinematography."' \ --form 'duration="8"' \ --form 'model="v5.5"' \ --form 'quality="1080p"' \ --form 'aspect_ratio="9:16"' \ --form 'first_frame_path="upload/….webp"' \ --form 'audio="true"' ``` Result: <video poster="https://media.useapi.net/blog/2026-01-26-260126/pixverse-v5-5-create-first-frame-poster.jpg" src="https://media.useapi.net/blog/2026-01-26-260126/pixverse-v5-5-create-first-frame.mp4" style="width: 100%; max-width: 400px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> **Step 2: Modify the video** ```bash curl --location 'https://api.useapi.net/v2/pixverse/videos/modify' \ --header 'Authorization: Bearer user:12345-…' \ --form 'prompt="She is wearing Mandalorian Beskar armor"' \ --form 'model="v5.5"' \ --form 'quality="720p"' \ --form 'video_id="user:12345-user@gmail.com-video:…"' ``` Result: <video poster="https://media.useapi.net/blog/2026-01-26-260126/pixverse-v5-5-modify-poster.jpg" src="https://media.useapi.net/blog/2026-01-26-260126/pixverse-v5-5-modify.mp4" style="width: 100%; max-width: 400px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> Also on YouTube: [PixVerse v5.5 Video Modify](https://youtube.com/shorts/L8aSVk4Nxv8). === URL: https://useapi.net/blog/260127 === Document URL: https://useapi.net/blog/260127 --- layout: blog_post title: "PixVerse v5.6: Integrated Audio Generation" description: "PixVerse API v2 now supports the latest v5.6 model with integrated audio generation." parent: Blog nav_exclude: true nav_order: -260127 --- [PixVerse API v2](/docs/api-pixverse-v2) now supports the latest `v5.6` model with integrated audio generation. See [Model Capabilities](/docs/api-pixverse-v2/model-capabilities) for the complete feature matrix. **v5.6 Image-to-Video with Audio** Source image: <img src="https://media.useapi.net/blog/2026-01-27-260127/playing-guitar.webp" style="width: 100%; max-width: 400px;" /> ```bash curl --location 'https://api.useapi.net/v2/pixverse/videos/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'prompt="She is playing guitar and singing "Yesterday, all my troubles seemed so far away""' \ --form 'duration="8"' \ --form 'model="v5.6"' \ --form 'quality="1080p"' \ --form 'aspect_ratio="9:16"' \ --form 'first_frame_path="upload/….webp"' \ --form 'audio="true"' ``` Result: <video poster="https://media.useapi.net/articles/2024-06-08-pixverse-demo/pixverse-v56-frame-poster.jpg" src="https://media.useapi.net/articles/2024-06-08-pixverse-demo/pixverse-v56-frame.mp4" style="width: 100%; max-width: 400px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> **What's New in v5.6** | Feature | v5.6 | v5.5 | v5 | v5-fast | |---------|------|------|----|---------| | Native Audio | ✅ | ✅ | - | - | | Lip Sync TTS | - | - | ✅ | - | | Sound Effects | - | - | ✅ | - | | Duration 1-10s | ✅ | ✅ | ✅ | ✅ | **Breaking Changes** * `v4` and `v4.5` models removed (deprecated by PixVerse) * `motion_mode` parameter removed * `style` parameter removed * [POST videos/restyle](/docs/api-pixverse-v2/post-pixverse-videos-restyle-v4) endpoint deprecated === URL: https://useapi.net/blog/260127m === Document URL: https://useapi.net/blog/260127m --- layout: blog_post title: "Mureka: V8 Now the Default Model" description: "Mureka API v1 now supports the latest V8 model as the new default." parent: Blog nav_exclude: true nav_order: -260127 --- [Mureka API v1](/docs/api-mureka-v1) now supports the latest `V8` model as the new default. **Instrumental V8** - Aurora Dreamscape ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-instrumental' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: application/json' \ --data '{ "prompt": "Ambient electronic dreamscape with shimmering arpeggios, deep sub-bass, crystalline bells, and evolving textures - floating through aurora borealis", "model": "V8" }' ``` <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-01-27-260127m/v8-instrumental.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> **Music V8 Female** - Astro Gardener ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-advanced' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: application/json' \ --data '{ "lyrics": "[Verse 1]\nPlanting roses on the rings of Saturn\nWatering moonflowers in zero gravity pattern\nComets bring the seeds I need\nGrowing cosmic flowers from a supernova seed\n\n[Chorus]\nI'\''m the astro gardener floating free\nTending galaxies you'\''ll never see\nSolar winds blow through my hair\nStarlight orchids everywhere", "desc": "dreamy indie pop, floating guitars, cosmic reverb, hopeful and whimsical", "vocal_gender": "female", "model": "V8" }' ``` <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-01-27-260127m/v8-example1.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> **Music V8** - Haunted Wifi ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-advanced' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: application/json' \ --data '{ "lyrics": "[Verse 1]\nSignal bars are flickering at three AM\nSomething in the router wants to be my friend\nDownloads starting by themselves again\nGhost in the bandwidth sending data from the end\n\n[Chorus]\nHaunted wifi in my walls\nPhantom packets through the halls\nEvery ping returns a scream\nDigital nightmares in the stream", "desc": "dark synthwave, eerie pads, pulsing bass, ghostly atmosphere, horror movie vibes", "model": "V8" }' ``` <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-01-27-260127m/v8-exmple2.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> === URL: https://useapi.net/blog/260129 === Document URL: https://useapi.net/blog/260129 --- layout: blog_post title: "Google Flow: Video Extend and Concatenate" description: "Google Flow API v1 new video extension and concatenation endpoints:" parent: Blog nav_exclude: true nav_order: -260129 --- [Google Flow API v1](/docs/api-google-flow-v1) new video extension and concatenation endpoints: * [POST /videos/extend](/docs/api-google-flow-v1/post-google-flow-videos-extend) - Extend video with a new prompt * [POST /videos/concatenate](/docs/api-google-flow-v1/post-google-flow-videos-concatenate) - Concatenate multiple videos **Examples** * Generate initial video using `veo-3.1-fast-relaxed` [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) [Start image](https://media.useapi.net/blog/2026-01-29-260129/stylish-lady-jpeg.jpg) ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos' \ --header 'Authorization: Bearer user:12345-…' \ --form 'prompt="Using the provided start image, the woman with dark bangs and a brown duster coat looks directly at the camera and says, '\''Wait, did you see this?'\'' with a smirk. She then tosses her black handbag off-camera to the left and begins the '\''Apple'\'' dance. She lip-syncs the words '\''Apple'\''s rotten to the core'\'' while performing sharp hand-peeling motions and a circular hand gesture over her head. Her expression is confident and playful. The long coat swishes as she moves. 4k, cinematic studio lighting."' \ --form 'model="veo-3.1-fast-relaxed"' \ --form 'aspectRatio="portrait"' \ --form 'startImage="user:12345-email:…-image:…"' ``` Result <video poster="https://media.useapi.net/blog/2026-01-29-260129/video1-poster.jpg" src="https://media.useapi.net/blog/2026-01-29-260129/video1.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> * Extend video using [POST /videos/extend](/docs/api-google-flow-v1/post-google-flow-videos-extend) ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos/extend' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: application/json' \ --data '{ "mediaGenerationId": "user:12345-email:…-video:…", "prompt": "The woman in the brown coat and jeans mouths the words '\''Is somebody gonna match my freak?'\'' while performing a slow, rhythmic deep hip roll. She looks intensely at the camera, then adds, '\''Let'\''s see,'\'' with a wink. She performs a '\''searching'\'' hand gesture over her eyes and a slow-motion shoulder shimmy while stepping forward in her black lace-up boots. No handbag. The lighting is moody and sophisticated.", "model": "veo-3.1-fast-relaxed" }' ``` Result <video poster="https://media.useapi.net/blog/2026-01-29-260129/video2-poster.jpg" src="https://media.useapi.net/blog/2026-01-29-260129/video2.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> * Extend again using [POST /videos/extend](/docs/api-google-flow-v1/post-google-flow-videos-extend) ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos/extend' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: application/json' \ --data '{ "mediaGenerationId": "user:12345-email:…-video:…", "prompt": "The woman transitions into an upbeat pop dance. She looks at the camera and says, '\''I'\''m working late... obviously,'\'' then lip-syncs the line '\''That'\''s that me, espresso!'\'' while performing the signature move: she holds an invisible espresso cup with her pinky up, then tilts her head onto her hands. She performs a fast sequence of heel-taps and a crisp 360-degree walking-turn to the left. The long brown coat flares out beautifully during the turn. She finishes with a bright, confident smile and a thumbs-up. Professional studio aesthetic.", "model": "veo-3.1-fast-relaxed" }' ``` Result <video poster="https://media.useapi.net/blog/2026-01-29-260129/video3-poster.jpg" src="https://media.useapi.net/blog/2026-01-29-260129/video3.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> * Extend one more time using [POST /videos/extend](/docs/api-google-flow-v1/post-google-flow-videos-extend) ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos/extend' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: application/json' \ --data '{ "mediaGenerationId": "user:12345-email:…-video:…", "prompt": "The woman in the brown duster coat looks directly into the lens and says: '\''And that is the look. Stay stylish, everyone!'\'' with a professional and confident expression. She performs an elegant fashion sequence: she takes rhythmic lateral sliding steps to the left and right while raising her arms into a triumphant V-shape above her head. She then brings her hands down to firmly grasp and adjust the lapels of her long coat, showing off the fabric. She performs a sharp, professional runway turn on her heels. She walks calmly and confidently away from the camera toward the back of the studio. Cinematic wide shot, soft background focus, high-fashion lighting.", "model": "veo-3.1-fast-relaxed" }' ``` Result <video poster="https://media.useapi.net/blog/2026-01-29-260129/video4-poster.jpg" src="https://media.useapi.net/blog/2026-01-29-260129/video4.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> * Concatenate all videos using [POST /videos/concatenate](/docs/api-google-flow-v1/post-google-flow-videos-concatenate) Note: `trimStart: 1` removes the ~1 second overlap from extended videos. ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos/concatenate' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: application/json' \ --data '{ "media": [ { "mediaGenerationId": "user:12345-email:…-video:…" }, { "mediaGenerationId": "user:12345-email:…-video:…", "trimStart": 1 }, { "mediaGenerationId": "user:12345-email:…-video:…", "trimStart": 1 }, { "mediaGenerationId": "user:12345-email:…-video:…", "trimStart": 1 } ] }' ``` Final result (all four clips concatenated) <video poster="https://media.useapi.net/blog/2026-01-29-260129/concatenated-video-poster.jpg" src="https://media.useapi.net/blog/2026-01-29-260129/concatenated-video.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> Also on YouTube: [Let's Dance • Veo 3.1 Extend & Concatenate](https://youtube.com/shorts/PWWH2aOJG3A). === URL: https://useapi.net/blog/260209 === Document URL: https://useapi.net/blog/260209 --- layout: blog_post title: "Kling v3: 4K Resolution and Video Elements" description: "Create two VIDEO elements from random TikTok clips and use them to generate an 11-second video." parent: Blog nav_exclude: true nav_order: -260209 --- [Kling API v1](/docs/api-kling-v1) updates: * v3 features: 4k resolution (VIP), `auto` aspect ratio, 3-15s video duration, VIDEO elements * Kling v3 is now the default model version across all Omni endpoints * [POST /images/omni](/docs/api-kling-v1/post-kling-images-omni): `omni_version` default changed from `o1` to `v3` * [POST /videos/omni](/docs/api-kling-v1/post-kling-videos-omni): `omni_version` default changed from `o1` to `v3` * [POST /images/kolors](/docs/api-kling-v1/post-kling-images-kolors): `version` default changed from `kling-v1-6` to `kling-v3-0` * Kling v3 (`kling-v3-0`) added to [POST /videos/text2video](/docs/api-kling-v1/post-kling-videos-text2video), [POST /videos/image2video-frames](/docs/api-kling-v1/post-kling-videos-image2video-frames), [POST /videos/image2video-elements](/docs/api-kling-v1/post-kling-videos-image2video-elements) **Example: VIDEO Elements with [POST /videos/omni](/docs/api-kling-v1/post-kling-videos-omni) v3** Create two VIDEO elements from random TikTok clips and use them to generate an 11-second video. `@image_1` — [image_1](https://media.useapi.net/blog/2026-02-09-260209/arctic-jpeg.jpg) background image <details markdown="block"> <summary><b>@element_1 — first character (VIDEO element)</b></summary> <video poster="https://media.useapi.net/blog/2026-02-09-260209/element-1-h264-poster.jpg" src="https://media.useapi.net/blog/2026-02-09-260209/element-1-h264.mp4" style="height: 40vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> </details> <details markdown="block"> <summary><b>@element_2 — second character (VIDEO element)</b></summary> <video poster="https://media.useapi.net/blog/2026-02-09-260209/element-2-h264-poster.jpg" src="https://media.useapi.net/blog/2026-02-09-260209/element-2-h264.mp4" style="height: 40vh; width: 100%;" controls type="video/mp4" preload="metadata"></video> </details> ```bash curl --location 'https://api.useapi.net/v1/kling/videos/omni' \ --header 'Authorization: Bearer user:12345-…' \ --form 'prompt="@object_1 and @object_2 standing at @image_1, @object_1 asking \"Does this blue dress make me look intellectual?\" and @object_2 reply \"No, you look like a clickable link on Wikipedia\""' \ --form 'duration="11"' \ --form 'omni_version="v3"' \ --form 'aspect_ratio="16:9"' \ --form 'mode="std"' \ --form 'element_1="u_…"' \ --form 'element_2="u_…"' \ --form 'image_1="https://s15-kling.klingai.com/…"' ``` Result (`mode="std"` 720p) <video poster="https://media.useapi.net/blog/2026-02-09-260209/elements-v3-results-720p-11sec-poster.jpg" src="https://media.useapi.net/blog/2026-02-09-260209/elements-v3-results-720p-11sec.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> Result (`mode="pro"` 1080p) <video poster="https://media.useapi.net/blog/2026-02-09-260209/elements-v3-results-1080p-11sec-poster.jpg" src="https://media.useapi.net/blog/2026-02-09-260209/elements-v3-results-1080p-11sec.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> === URL: https://useapi.net/blog/260216 === Document URL: https://useapi.net/blog/260216 --- layout: blog_post title: "Kling v3: Multi-Shot Storytelling" description: "Kling API on useapi.net adds v3 multi-shot storytelling: split one video into 2 to 6 shots with per-shot prompts and durations via omni, text2video, and frames." parent: Blog nav_exclude: true nav_order: -260216 --- [Kling API v1](/docs/api-kling-v1) updates: * Multi-shot storytelling for v3: split video into 2-6 shots with per-shot prompts and durations via [POST /videos/omni](/docs/api-kling-v1/post-kling-videos-omni), [POST /videos/text2video](/docs/api-kling-v1/post-kling-videos-text2video), [POST /videos/image2video-frames](/docs/api-kling-v1/post-kling-videos-image2video-frames) **Example 1: Multi-Shot with Elements and Image via [POST /videos/omni](/docs/api-kling-v1/post-kling-videos-omni) v3** 3 shots with two character elements and a background image. <details markdown="block"> <summary><b>@element_1 — Tom</b></summary> <video poster="https://media.useapi.net/blog/2026-02-16-260216/tom-1-poster.jpg" src="https://media.useapi.net/blog/2026-02-16-260216/tom-1.mp4" style="height: 40vh; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> </details> <details markdown="block"> <summary><b>@element_2 — Brad</b></summary> <video poster="https://media.useapi.net/blog/2026-02-16-260216/brad-1-poster.jpg" src="https://media.useapi.net/blog/2026-02-16-260216/brad-1.mp4" style="height: 40vh; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> </details> `@image_1` — [kitchen](https://media.useapi.net/blog/2026-02-16-260216/kitchen.jpg) background image ```bash curl --location 'https://api.useapi.net/v1/kling/videos/omni' \ --header 'Authorization: Bearer user:12345-…' \ --form 'omni_version="v3"' \ --form 'aspect_ratio="16:9"' \ --form 'mode="pro"' \ --form 'element_1="u_…"' \ --form 'element_2="u_…"' \ --form 'image_1="https://s15-kling.klingai.com/…"' \ --form 'shot_1_prompt="Cinematic medium shot, @element_1 and @element_2 standing behind a professional stainless steel TV-show stove with open blue flames @image_1 with two frying pans. @element_1 is cooking with intense focus. @element_2 is leaning back casually, chewing on a carrot while holding his pan loosely. @element_2 turns to @element_1 with a charming smirk and speaks."' \ --form 'shot_1_duration="3"' \ --form 'shot_2_prompt="Cinematic medium shot, continuous scene behind the same professional stove @image_1. @element_1 looks furiously intense, staring at the pan. He aggressively flips the food high into the air with military precision. He turns his head sharply to @element_2 and yells. @element_2 shrugs and keeps chewing."' \ --form 'shot_2_duration="3"' \ --form 'shot_3_prompt="Cinematic medium shot, continuous scene behind the same professional stove @image_1. Slapstick comedy action. @element_1 and @element_2 grab their pans and start fencing. @element_1 swings his pan like a weapon, @element_2 parries the blow with his own pan. Cooked vegetables and flour explode into the air. Both characters are laughing maniacally."' \ --form 'shot_3_duration="3"' ``` Result <video poster="https://media.useapi.net/blog/2026-02-16-260216/result-720p-poster.jpg" src="https://media.useapi.net/blog/2026-02-16-260216/result-720p.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> Also on YouTube: [Mission: Kitchen Impossible • Kling v3 multi-shot](https://www.youtube.com/watch?v=Ti8oHAvg7Cw). --- **Example 2: Text-only Multi-Shot via [POST /videos/omni](/docs/api-kling-v1/post-kling-videos-omni) v3** 2 shots, text-only, no elements or images. ```bash curl --location 'https://api.useapi.net/v1/kling/videos/omni' \ --header 'Authorization: Bearer user:12345-…' \ --form 'omni_version="v3"' \ --form 'aspect_ratio="16:9"' \ --form 'mode="std"' \ --form 'shot_1_prompt="A penguin in a chef hat carefully stacks pancakes into an impossibly tall tower, wobbling dangerously"' \ --form 'shot_1_duration="1"' \ --form 'shot_2_prompt="The pancake tower collapses and buries the penguin, who pops out wearing a pancake as a beret"' \ --form 'shot_2_duration="2"' ``` Result <video poster="https://media.useapi.net/blog/2026-02-16-260216/v3-omni-text-result-poster.jpg" src="https://media.useapi.net/blog/2026-02-16-260216/v3-omni-text-result.mp4" style="width: 100%; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> === URL: https://useapi.net/blog/260217 === Document URL: https://useapi.net/blog/260217 --- layout: blog_post title: "Runway: Nano Banana Pro and Gen-4 Images" description: "Runway: Nano Banana Pro and Gen-4 Images — useapi.net API update." parent: Blog nav_exclude: true nav_order: -260217 --- [Runway API v1](/docs/api-runwayml-v1) updates: * New [POST /images/create](/docs/api-runwayml-v1/post-runwayml-images-create) — unified image generation endpoint supporting **Nano Banana**, **Nano Banana Pro**, **Gen-4**, and **Gen-4 Turbo** models * Nano Banana and Nano Banana Pro support image references of famous people and minors * Explore mode for Runway Unlimited plan accounts — generate images without using credits ### Example 1: Nano Banana Pro with reference image via [POST /images/create](/docs/api-runwayml-v1/post-runwayml-images-create) `imageAssetId1`: <img src="https://media.useapi.net/blog/2026-02-17-260217/brad.jpg" style="width: 100%; max-width: 400px;" /> ```bash curl --location 'https://api.useapi.net/v1/runwayml/images/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'text_prompt="Make him wear clown hat and stick his tongue out making silly face"' \ --form 'aspect_ratio="9:16"' \ --form 'num_images="1"' \ --form 'model="nano-banana-pro"' \ --form 'imageAssetId1="user:12345-runwayml:…"' \ --form 'resolution="1K"' ``` Result: <img src="https://media.useapi.net/blog/2026-02-17-260217/nano-banana-pro-1k-via-runway-result.png" style="width: 100%; max-width: 400px;" /> ### Example 2: Nano Banana Pro with reference image via [POST /images/create](/docs/api-runwayml-v1/post-runwayml-images-create) `imageAssetId1`: <img src="https://media.useapi.net/blog/2026-02-17-260217/photo-test.jpg" style="width: 100%; max-width: 400px;" /> ```bash curl --location 'https://api.useapi.net/v1/runwayml/images/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'text_prompt="Restore this photo, add colors"' \ --form 'aspect_ratio="3:4"' \ --form 'num_images="1"' \ --form 'model="nano-banana-pro"' \ --form 'imageAssetId1="user:12345-runwayml:…"' \ --form 'resolution="2K"' ``` Result: <img src="https://media.useapi.net/blog/2026-02-17-260217/nano-banana-pro-via-runvay-results.jpg" style="width: 100%; max-width: 400px;" /> === URL: https://useapi.net/blog/260223 === Document URL: https://useapi.net/blog/260223 --- layout: blog_post title: "Dreamina: Seedance 2.0 Launch Examples (February 2026)" description: "February 2026 launch post: the first Seedance 2.0 image-to-video and text-to-video runs on the Dreamina API, with launch-day credit costs." parent: Blog nav_exclude: true nav_order: -260223 --- This is the February 2026 launch post. The current [Dreamina API](/docs/api-dreamina-v1) runs Seedance 2.5, 2.0, 2.0 Fast and 2.0 Mini on your [Dreamina website subscription](https://dreamina.capcut.com/pricing/dreamina-price). New [Dreamina API v1](/docs/api-dreamina-v1) — experimental API for [Dreamina](https://dreamina.capcut.com/) by [ByteDance](https://www.bytedance.com/): * Video generation with [Seedance 2.0](https://dreamina.capcut.com/), [Seedance 1.5 Pro](https://dreamina.capcut.com/), and [Seedance 1.0 Mini](https://dreamina.capcut.com/) models * Text-to-video, image-to-video (first frame), end frame, and multi-frame keyframe modes * Multiple accounts with automated load balancing **Note:** Seedance 2.0 is not yet visible in the Dreamina website UI but is available internally — we anticipate an official release the week of February 23, 2026. All generations initiated via the API appear on the [Dreamina website](https://dreamina.capcut.com/), where you can verify that the Seedance 2.0 model was used. **Cost estimate** ([Dreamina Advanced](https://dreamina.capcut.com/) subscription): - Monthly: $40/mo, 30K credits — ~**$0.095** per 12s Seedance 2.0 generation (72 credits each) - Yearly: $335/yr, 30K credits/mo — under **$0.07** per generation - 2 free generations per day on every account - Both plans include free unlimited Seedream 4.0 image generation (2K) [View credits consumed](https://media.useapi.net/blog/2026-02-23-260223/credits.jpg){:target="_blank"} Compare every Seedance 2.0 and 2.5 route and price: [Seedance 2.0 and 2.5 API Pricing](/docs/articles/seedance-2-api-pricing). --- ### Image-to-video via [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos) using `seedance-2.0` [`firstFrameRef`](https://media.useapi.net/blog/2026-02-23-260223/two-ladies-selfie.webp){:target="_blank"} <img src="https://media.useapi.net/blog/2026-02-23-260223/two-ladies-selfie.webp" style="width: 100%; max-width: 400px;" /> ```bash curl --location 'https://api.useapi.net/v1/dreamina/videos' \ --header 'Authorization: Bearer user:12345-…' \ --form 'prompt="Lady on the left leans into the lens and starts making a \"duck face,\" then suddenly stops and pokes the Lady on the right. Lady on the left says \"Wait, is the '\''Big Forehead'\'' filter on?\" and starts tapping the camera screen aggressively. Lady on the right leans in, looks deeply into the lens, and says \"No... that'\''s just your face today,\" before they both burst into laughter and the camera shakes."' \ --form 'model="seedance-2.0"' \ --form 'firstFrameRef="US:email@proton.me-image:w760:h1400:s87516-uri:…"' \ --form 'duration="12"' ``` Result <video poster="https://media.useapi.net/blog/2026-02-23-260223/seedance-20-result-poster.jpg" src="https://media.useapi.net/blog/2026-02-23-260223/seedance-20-result.mp4" style="width: 100%; aspect-ratio: 9/16; max-width: 400px;" controls type="video/mp4" preload="metadata"></video> Also on YouTube: [Selfie Situation • Seedance 2.0](https://youtube.com/shorts/TYlg9cVyNy4). [View on Dreamina website](https://media.useapi.net/blog/2026-02-23-260223/the-selfie-situation.jpg){:target="_blank"} --- ### Text-to-video via [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos) using `seedance-2.0` ```bash curl --location 'https://api.useapi.net/v1/dreamina/videos' \ --header 'Authorization: Bearer user:12345-…' \ --form 'prompt="A high-fidelity video of a round, fluffy grey cat with large amber eyes in a convenience store. The cat has a bag of dried fish in its mouth and is walking with a funny, high-step waddle to avoid tripping on it. A woman in a white turtleneck and a \"Store Manager\" vest walks into the shot, laughs, and picks up the cat like a toddler. The cat refuses to drop the fish. Natively generated audio includes the soft chime of a store door and the crinkle of the plastic fish bag."' \ --form 'model="seedance-2.0"' \ --form 'ratio="9:16"' \ --form 'duration="12"' ``` Result <video poster="https://media.useapi.net/blog/2026-02-23-260223/seedance-20-t2v-result-poster.jpg" src="https://media.useapi.net/blog/2026-02-23-260223/seedance-20-t2v-result.mp4" style="width: 100%; aspect-ratio: 9/16; max-width: 400px;" controls type="video/mp4" preload="metadata"></video> [View on Dreamina website](https://media.useapi.net/blog/2026-02-23-260223/the-cat.jpg){:target="_blank"} --- ### Image-to-video via [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos) using `seedance-2.0` [`firstFrameRef`](https://media.useapi.net/blog/2026-02-23-260223/trump-and-melania.jpg){:target="_blank"} <img src="https://media.useapi.net/blog/2026-02-23-260223/trump-and-melania.jpg" style="width: 100%; max-width: 400px;" /> ```bash curl --location 'https://api.useapi.net/v1/dreamina/videos' \ --header 'Authorization: Bearer user:12345-…' \ --form 'prompt="Donald and Melania dancing the cha-cha. He is screaming, \"I won the dance competition, give me my prize now!\""' \ --form 'model="seedance-2.0"' \ --form 'firstFrameRef="US:user@email.com-image:…"' \ --form 'duration="12"' ``` Result <video poster="https://media.useapi.net/blog/2026-02-23-260223/donnie-poster.jpg" src="https://media.useapi.net/blog/2026-02-23-260223/donnie.mp4" style="width: 100%; max-width: 400px;" controls type="video/mp4" preload="metadata"></video> Also on YouTube: [A Very Talented Man • Seedance 2.0](https://youtube.com/shorts/AZKeOy4u1t4). [View on Dreamina website](https://media.useapi.net/blog/2026-02-23-260223/donald-won-another-prize.jpg){:target="_blank"} === URL: https://useapi.net/blog/260224 === Document URL: https://useapi.net/blog/260224 --- layout: blog_post title: "MiniMax: Sora, Veo, and Hailuo Models" description: "MiniMax: Sora, Veo, and Hailuo Models — useapi.net API update." parent: Blog nav_exclude: true nav_order: -260224 --- [MiniMax API v1](/docs/api-minimax-v1) updates: * Video generation now supports 15 models across 3 families: * **Hailuo**: `T2V-01`, `I2V-01`, `I2V-01-Director`, `I2V-01-live`, `S2V-01`, `T2V-02`, `I2V-02`, `T2V-2.3`, `I2V-2.3`, `I2V-2.3-Fast` * **Veo**: `Veo-3.1`, `Veo-3.1-Fast`, `Veo-3.1-S2V`, `Veo-3.1-S2V-Fast` * **Sora**: `Sora-2` * Image generation now supports 7 models: `image-01`, `Midjourney V7`, `Midjourney NiJi 7`, `Nano Banana Pro`, `GPT Image 1.5`, `Seedream 4.5`, `Seedream 5.0` ### Example 1: Sora-2 9:16 image-to-video via [POST /videos/create](/docs/api-minimax-v1/post-minimax-videos-create) `fileID`: <img src="https://media.useapi.net/blog/2026-02-24-260224/the-warrior-720x1280.jpg" style="width: 100%; aspect-ratio: 9/16; max-width: 400px;" /> ```bash curl --location 'https://api.useapi.net/v1/minimax/videos/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="Sora-2"' \ --form 'options="720p-12sec"' \ --form 'prompt="Beast vs. Man"' \ --form 'aspectRatio="9:16"' \ --form 'fileID="user:1245-minimax:…-file:…"' ``` Result <video poster="https://media.useapi.net/articles/2024-09-28-minimax-bash/beast-results-poster.jpg" src="https://media.useapi.net/articles/2024-09-28-minimax-bash/beast-results.mp4" style="width: 100%; aspect-ratio: 9/16; max-width: 400px;" controls type="video/mp4" preload="metadata"></video> --- ### Example 2: Midjourney V7 4:3 multi-reference image via [POST /images/create](/docs/api-minimax-v1/post-minimax-images-create) `referenceFileId1`: <img src="https://media.useapi.net/blog/2026-02-24-260224/character-1-jpeg.jpg" style="width: 100%; max-width: 400px;" /> `referenceFileId2`: <img src="https://media.useapi.net/blog/2026-02-24-260224/character-2-jpeg.jpg" style="width: 100%; max-width: 400px;" /> ```bash curl --location 'https://api.useapi.net/v1/minimax/images/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="midjourney-v7"' \ --form 'prompt="Looking straight at the camera the two princesses having a pleasant conversation at a café in Paris with the Eiffel Tower view in the background."' \ --form 'aspectRatio="4:3"' \ --form 'referenceFileId1="user:…-minimax:…-file:…"' \ --form 'referenceFileId2="user:…-minimax:…-file:…"' ``` Result: <img src="https://media.useapi.net/articles/2024-09-28-minimax-bash/midjourney-results.png" style="width: 100%; max-width: 400px;" /> === URL: https://useapi.net/blog/260227 === Document URL: https://useapi.net/blog/260227 --- layout: blog_post title: "MiniMax: Nano Banana 2 Image Model" description: "MiniMax API v1 on useapi.net adds the nano-banana-2 image model with 512P to 4K resolutions and up to 14 reference images, at 4 to 8 credits per image." parent: Blog nav_exclude: true nav_order: -260227 --- [MiniMax API v1](/docs/api-minimax-v1) updates: * New image model: `nano-banana-2` — lower cost flash variant with 512P/1K/2K/4K resolutions and up to 14 reference images * Credits per image: 512P/1K = 4, 2K = 5, 4K = 8 * [POST /images/create](/docs/api-minimax-v1/post-minimax-images-create) now supports 8 models MiniMax is currently running a yearly [subscription](https://hailuoai.video/subscribe) promo with 49% off, which comes with unlimited image generations, see [screenshot](https://media.useapi.net/blog/2026-02-27-260227/minimax-promo-unlimited.jpg){:target="_blank"} --- ### Example 1: Multi-reference 16:9 1K via [POST /images/create](/docs/api-minimax-v1/post-minimax-images-create) [referenceFileId1](https://media.useapi.net/blog/2026-02-27-260227/contextreference-2.jpg){:target="_blank"} [referenceFileId2](https://media.useapi.net/blog/2026-02-27-260227/contextreference-3.jpg){:target="_blank"} ```bash curl --location 'https://api.useapi.net/v1/minimax/images/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="nano-banana-2"' \ --form 'prompt="Retro travel poster combining classic motorcycle and Golden Gate Bridge, 1950s Americana"' \ --form 'aspectRatio="16:9"' \ --form 'referenceFileId1="user:12345-minimax:…-file:…1"' \ --form 'referenceFileId2="user:12345-minimax:…-file:…2"' \ --form 'resolution="1K"' ``` Result: ![](https://media.useapi.net/blog/2026-02-27-260227/nano-banana-2-bridge-cycle-result.png) --- ### Example 2: Multi-reference 3:4 2K quantity 3 via [POST /images/create](/docs/api-minimax-v1/post-minimax-images-create) [referenceFileId1](https://media.useapi.net/blog/2026-02-27-260227/cool-cats.jpg){:target="_blank"} [referenceFileId2](https://media.useapi.net/blog/2026-02-27-260227/cherry-cake.jpg){:target="_blank"} ```bash curl --location 'https://api.useapi.net/v1/minimax/images/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="nano-banana-2"' \ --form 'prompt="Cinematic still in the style of 1970s crime drama cinematography. The background is a dimly lit, ultra-exclusive Italian speakeasy with dark mahogany wood paneling and heavy crimson velvet curtains. The lighting is dramatic Chiaroscuro, featuring deep noir shadows and warm, moody amber glows from vintage table lamps. In the soft-focus background, shadowed figures of feline bodyguards in suits stand near arched doorways. The scene features The Boss Mr. Catz and his wife, Mrs. Catz, eating cake. The air is thick with a hazy, sophisticated atmosphere. Rich textures of polished silver, lace tablecloths, and crystal glassware. 8k resolution, film grain, intense dramatic mood."' \ --form 'quantity="3"' \ --form 'aspectRatio="3:4"' \ --form 'referenceFileId1="user:12345-minimax:…-file:…1"' \ --form 'referenceFileId2="user:12345-minimax:…-file:…2"' \ --form 'resolution="2K"' ``` Result: ![](https://media.useapi.net/articles/2024-09-28-minimax-bash/nano-banana-2-cool-cats-2k-result.png) === URL: https://useapi.net/blog/260302 === Document URL: https://useapi.net/blog/260302 --- layout: blog_post title: "Dreamina: Seedream 4.5 Image Generation" description: "Dreamina API v1 on useapi.net adds image generation with Seedream 4.5, 4.1, 4.0, 3.0 and Nano Banana, up to 6 reference images, and 2K to 8K upscaling." parent: Blog nav_exclude: true nav_order: -260302 --- [Dreamina API v1](/docs/api-dreamina-v1) updates: * Image generation with [Seedream 4.5](https://dreamina.capcut.com/), [Seedream 4.1](https://dreamina.capcut.com/), [Seedream 4.0](https://dreamina.capcut.com/) (free), [Nano Banana](https://dreamina.capcut.com/), and [Seedream 3.0](https://dreamina.capcut.com/) models * Text-to-image with up to 6 reference images, upscale to 2K/4K/8K * Generation history via [GET /assets](/docs/api-dreamina-v1/get-dreamina-assets-account), delete via [DELETE /assets](/docs/api-dreamina-v1/delete-dreamina-assets-assetid) --- ### Text-to-image via [POST /images](/docs/api-dreamina-v1/post-dreamina-images) using `seedream-4.5` ```bash curl --location 'https://api.useapi.net/v1/dreamina/images' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: application/json' \ --data '{ "prompt": "Cinematic nighttime outdoor portrait: A striking, highly detailed side-profile shot of a beautiful young woman standing inside a vintage public phone booth. She is delicately holding a classic blue phone receiver to her ear, with one hand softly resting against the glass in a relaxed, elegant posture. She wears a stylish trench coat draped effortlessly over a white silk blouse. Her facial features are perfectly captured in profile, showcasing delicate skin texture and soft contouring. The booth'\''s glass is slightly fogged, reflecting vibrant neon city streetlights with a breathtaking, deep bokeh effect. Cinematic lighting, rim light illuminating her hair, hyper-realistic, photorealistic, shot on 35mm lens, moody vintage film aesthetic, masterpiece, 8k resolution, high-end commercial photography.", "model": "seedream-4.5", "ratio": "9:16" }' ``` [Result (2K)](https://media.useapi.net/blog/2026-03-02-260302/seedream-4.5-2k-result.jpg){:target="_blank"} <img src="https://media.useapi.net/blog/2026-03-02-260302/seedream-4.5-2k-result.jpg" style="width: 100%; max-width: 400px;" /> --- ### Upscale to 4K via [POST /images/upscale](/docs/api-dreamina-v1/post-dreamina-images-upscale) Using the generated image from the example above: ```bash curl --location 'https://api.useapi.net/v1/dreamina/images/upscale' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: application/json' \ --data '{ "jobid": "j0302…-bot:dreamina", "imageIndex": 0, "upscaleResolution": "4k" }' ``` [Result (4K)](https://media.useapi.net/blog/2026-03-02-260302/seedream-4.5-upscale-4k-result.jpg){:target="_blank"} <img src="https://media.useapi.net/blog/2026-03-02-260302/seedream-4.5-upscale-4k-result.jpg" style="width: 100%; max-width: 400px;" /> --- ### Image with reference via [POST /images](/docs/api-dreamina-v1/post-dreamina-images) using `seedream-4.5` [imageRef_1](https://media.useapi.net/blog/2026-03-02-260302/brad.jpg){:target="_blank"} ```bash curl --location 'https://api.useapi.net/v1/dreamina/images' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: application/json' \ --data '{ "prompt": "Sitting at the beach bar on a high stool, wearing flip-flops, and holding a cigar and a margarita, we see calm ocean behind him.", "model": "seedream-4.5", "ratio": "9:16", "imageRef_1": "US:…-image:w…:h…:s…-uri:…" }' ``` Result (2K): <img src="https://media.useapi.net/blog/2026-03-02-260302/seedream-4.5-with-ref-2k-result.jpg" style="width: 100%; max-width: 400px;" /> --- ### Image-to-video via [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos) using `seedance-2.0` Using the generated image from Example 3 above as [`firstFrameRef`](https://media.useapi.net/blog/2026-03-02-260302/seedream-4.5-with-ref-2k-result.jpg){:target="_blank"}: ```bash curl --location 'https://api.useapi.net/v1/dreamina/videos' \ --header 'Authorization: Bearer user:12345-…' \ --form 'prompt="A man relaxing on a high stool at a sunny beach bar, holding a margarita in his left hand and a smoking cigar in his right. He takes a drink from the glass, then immediately takes a drag from the cigar, blowing out smoke. He makes direct eye contact with the viewer and says: \"Smoking and drinking is bad for you, buddy.\""' \ --form 'model="seedance-2.0"' \ --form 'firstFrameRef="US:…-image:w…:h…:s…-uri:…"' \ --form 'duration="12"' ``` Result: <video poster="https://media.useapi.net/blog/2026-03-02-260302/seedance-2.0-from-generated-image-ref-result-poster.jpg" src="https://media.useapi.net/blog/2026-03-02-260302/seedance-2.0-from-generated-image-ref-result.mp4" style="width: 100%; aspect-ratio: 9/16; max-width: 400px;" controls type="video/mp4" preload="metadata"></video> Also on YouTube: [Smoking is bad for you • Seedance 2.0](https://youtube.com/shorts/22wkkVyn4Xk). [Screenshot from Dreamina website](https://media.useapi.net/blog/2026-03-02-260302/dreamina-website-screenshot.jpg){:target="_blank"} Compare every Seedance 2.0 and 2.5 route and price: [Seedance 2.0 and 2.5 API Pricing](/docs/articles/seedance-2-api-pricing). === URL: https://useapi.net/blog/260305 === Document URL: https://useapi.net/blog/260305 --- layout: blog_post title: "Runway: Unified Videos Endpoint and New Models" description: "Prompt: Elegant portrait of a woman in vintage 1920s fashion with art deco jewelry and soft studio lighting" parent: Blog nav_exclude: true nav_order: -260305 --- [Runway API v1](/docs/api-runwayml-v1) updates: * New unified [Videos](/docs/api-runwayml-v1/post-runwayml-videos-create) endpoint supporting 12 models: Gen-4.5, Gen-4, Gen-4 Turbo, Kling 3.0 Pro/Standard, Kling 2.6 Pro/I2V, Veo 3.1, Sora 2/Pro, Wan 2.6 Flash, and Wan 2.2 Animate * [Images](/docs/api-runwayml-v1/post-runwayml-images-create) endpoint: added Nano Banana 2, GPT Image 1.5, GPT Image 1 Mini, and Seedream 5 models * `exploreMode` for credit-free generation on [Unlimited plan](https://help.runwayml.com/hc/en-us/articles/18053095835795-Unlimited-plan-details) accounts --- ## Videos ### Kling 2.6 I2V with sound via [POST /videos/create](/docs/api-runwayml-v1/post-runwayml-videos-create) [imageAssetId1](https://media.useapi.net/blog/2026-03-05-260305/lady-in-white.webp){:target="_blank"} ```bash curl --location 'https://api.useapi.net/v1/runwayml/videos/create' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: application/json' \ --data '{ "model": "kling-2.6-i2v", "text_prompt": "She turns around and says \"Hello there!\"", "duration": 5, "imageAssetId1": "user:12345-runwayml:…-asset:…", "exploreMode": true }' ``` Result: <video poster="https://media.useapi.net/blog/2026-03-05-260305/runway-kling-v-2-6-pro-sound-ref-image-poster.jpg" src="https://media.useapi.net/blog/2026-03-05-260305/runway-kling-v-2-6-pro-sound-ref-image.mp4" style="width: 100%; max-width: 400px;" controls type="video/mp4" preload="metadata"></video> --- ### Text-to-video with sound — same prompt, 4 models via [POST /videos/create](/docs/api-runwayml-v1/post-runwayml-videos-create) Prompt: *Elegant portrait of a woman in vintage 1920s fashion with art deco jewelry and soft studio lighting* Aspect ratio: 9:16, with sound enabled #### Veo 3.1 <video poster="https://media.useapi.net/articles/2024-08-11-runway-bash/runway-veo-3-1-with-sound-poster.jpg" src="https://media.useapi.net/articles/2024-08-11-runway-bash/runway-veo-3-1-with-sound.mp4" style="width: 100%; max-width: 400px;" controls type="video/mp4" preload="metadata"></video> #### Kling 3.0 Pro <video poster="https://media.useapi.net/articles/2024-08-11-runway-bash/runway-kling-3-0-pro-with-sound-poster.jpg" src="https://media.useapi.net/articles/2024-08-11-runway-bash/runway-kling-3-0-pro-with-sound.mp4" style="width: 100%; max-width: 400px;" controls type="video/mp4" preload="metadata"></video> #### Sora 2 <video poster="https://media.useapi.net/articles/2024-08-11-runway-bash/runway-sora-2-with-sound-poster.jpg" src="https://media.useapi.net/articles/2024-08-11-runway-bash/runway-sora-2-with-sound.mp4" style="width: 100%; max-width: 400px;" controls type="video/mp4" preload="metadata"></video> #### Kling 2.6 Pro <video poster="https://media.useapi.net/blog/2026-03-05-260305/runway-kling-2-6-with-sound-poster.jpg" src="https://media.useapi.net/blog/2026-03-05-260305/runway-kling-2-6-with-sound.mp4" style="width: 100%; max-width: 400px;" controls type="video/mp4" preload="metadata"></video> --- ### Wan 2.2 Animate via [POST /videos/create](/docs/api-runwayml-v1/post-runwayml-videos-create) [imageAssetId1](https://media.useapi.net/blog/2026-03-05-260305/lady-in-white.webp){:target="_blank"} <details><summary>videoAssetId (click to play)</summary> <video poster="https://media.useapi.net/blog/2026-03-05-260305/mj-15sec-poster.jpg" src="https://media.useapi.net/blog/2026-03-05-260305/mj-15sec.mp4" style="width: 100%; max-width: 400px;" controls type="video/mp4" preload="metadata"></video> </details> ```bash curl --location 'https://api.useapi.net/v1/runwayml/videos/create' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: application/json' \ --data '{ "model": "wan-2.2-animate", "aspect_ratio": "9:16", "imageAssetId1": "user:12345-runwayml:…-asset:…1", "videoAssetId": "user:12345-runwayml:…-asset:…2", "exploreMode": true }' ``` Result: <video poster="https://media.useapi.net/blog/2026-03-05-260305/runway-wan-2-2-animate-poster.jpg" src="https://media.useapi.net/blog/2026-03-05-260305/runway-wan-2-2-animate.mp4" style="width: 100%; max-width: 400px;" controls type="video/mp4" preload="metadata"></video> --- ## Images ### Nano Banana 2 with reference via [POST /images/create](/docs/api-runwayml-v1/post-runwayml-images-create) [imageAssetId1](https://media.useapi.net/blog/2026-03-05-260305/contextreference-1.jpg){:target="_blank"} ```bash curl --location 'https://api.useapi.net/v1/runwayml/images/create' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: application/json' \ --data '{ "model": "nano-banana-2", "text_prompt": "Elegant portrait of a woman in vintage 1920s fashion with art deco jewelry and soft studio lighting", "aspect_ratio": "9:16", "resolution": "1K", "imageAssetId1": "user:12345-runwayml:…-asset:…" }' ``` Result: <img src="https://media.useapi.net/blog/2026-03-05-260305/runway-nano-banana-2-ref.png" style="width: 100%; max-width: 400px;" /> --- ### Seedream 5 via [POST /images/create](/docs/api-runwayml-v1/post-runwayml-images-create) ```bash curl --location 'https://api.useapi.net/v1/runwayml/images/create' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: application/json' \ --data '{ "model": "seedream-5", "text_prompt": "Elegant portrait of a woman in vintage 1920s fashion with art deco jewelry and soft studio lighting", "aspect_ratio": "2:3", "resolution": "2K" }' ``` Result: <img src="https://media.useapi.net/blog/2026-03-05-260305/runway-seedream-5-0-prompt.jpg" style="width: 100%; max-width: 400px;" /> --- ### Nano Banana Pro with reference via [POST /images/create](/docs/api-runwayml-v1/post-runwayml-images-create) [imageAssetId1](https://media.useapi.net/blog/2026-03-05-260305/contextreference-4.jpg){:target="_blank"} ```bash curl --location 'https://api.useapi.net/v1/runwayml/images/create' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: application/json' \ --data '{ "model": "nano-banana-pro", "text_prompt": "Contemporary high fashion portrait with bold geometric patterns and dramatic shadow play", "aspect_ratio": "9:16", "resolution": "1K", "imageAssetId1": "user:12345-runwayml:…-asset:…" }' ``` Result: <img src="https://media.useapi.net/blog/2026-03-05-260305/runway-nano-banana-pro-ref.png" style="width: 100%; max-width: 400px;" /> === URL: https://useapi.net/blog/260306 === Document URL: https://useapi.net/blog/260306 --- layout: blog_post title: "Kling: Motion Control 3.0 with Character Consistency" description: "Step 1: Create a character element from a video using POST /elements" parent: Blog nav_exclude: true nav_order: -260306 --- [Kling API v1](/docs/api-kling-v1) updates: * [Motion Control](/docs/api-kling-v1/post-kling-videos-motion-create) now supports v3.0 model with upgraded motion capture, high facial consistency, and optional `element_1` for character consistency --- ## Motion Control v3.0 via [POST /videos/motion-create](/docs/api-kling-v1/post-kling-videos-motion-create) ### Basic motion transfer [imageUrl](https://media.useapi.net/blog/2026-03-06-260306/lady-in-yellow-jpeg.jpg){:target="_blank"} <details><summary>motionUrl (click to play)</summary> <video poster="https://media.useapi.net/blog/2026-03-05-260305/mj-15sec-poster.jpg" src="https://media.useapi.net/blog/2026-03-05-260305/mj-15sec.mp4" style="width: 100%; max-width: 400px;" controls type="video/mp4" preload="metadata"></video> </details> ```bash curl --location 'https://api.useapi.net/v1/kling/videos/motion-create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'motionUrl="https://v15-kling.klingai.com/…"' \ --form 'imageUrl="https://s15-kling.klingai.com/…"' \ --form 'keepAudio="true"' \ --form 'model_name="kling-v3-0"' ``` Result: <video poster="https://media.useapi.net/blog/2026-03-06-260306/kling-motion-3-720p-15sec-poster.jpg" src="https://media.useapi.net/blog/2026-03-06-260306/kling-motion-3-720p-15sec.mp4" style="width: 100%; max-width: 400px;" controls type="video/mp4" preload="metadata"></video> --- ### Motion transfer with element for character consistency Step 1: Create a character element from a video using [POST /elements](/docs/api-kling-v1/post-kling-elements) <details><summary>video (click to play)</summary> <video poster="https://media.useapi.net/blog/2026-03-06-260306/jennifer-tiktok-poster.jpg" src="https://media.useapi.net/blog/2026-03-06-260306/jennifer-tiktok.mp4" style="width: 100%; max-width: 400px;" controls type="video/mp4" preload="metadata"></video> </details> ```bash curl --location 'https://api.useapi.net/v1/kling/elements' \ --header 'Authorization: Bearer user:12345-…' \ --form 'name="jennifer"' \ --form 'video="https://v15-kling.klingai.com/…"' ``` Step 2: Use the element in motion control with `element_1` [imageUrl](https://media.useapi.net/blog/2026-03-06-260306/jennifer-1-jpeg.jpg){:target="_blank"} <details><summary>motionUrl (click to play)</summary> <video poster="https://media.useapi.net/blog/2026-03-05-260305/mj-15sec-poster.jpg" src="https://media.useapi.net/blog/2026-03-05-260305/mj-15sec.mp4" style="width: 100%; max-width: 400px;" controls type="video/mp4" preload="metadata"></video> </details> ```bash curl --location 'https://api.useapi.net/v1/kling/videos/motion-create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'motionUrl="https://v15-kling.klingai.com/…"' \ --form 'imageUrl="https://s15-kling.klingai.com/…"' \ --form 'motionDirection="image_direction"' \ --form 'mode="pro"' \ --form 'keepAudio="true"' \ --form 'model_name="kling-v3-0"' \ --form 'element_1="u_1234567890"' ``` Result: <video poster="https://media.useapi.net/blog/2026-03-06-260306/kling-motion-1080p-with-element-poster.jpg" src="https://media.useapi.net/blog/2026-03-06-260306/kling-motion-1080p-with-element.mp4" style="width: 100%; max-width: 400px;" controls type="video/mp4" preload="metadata"></video> Also on YouTube: [Smooth Criminal • Kling Motion 3.0](https://youtube.com/shorts/VztjBYqqQ1A). === URL: https://useapi.net/blog/260309 === Document URL: https://useapi.net/blog/260309 --- layout: blog_post title: "PixVerse: Image Generation" description: "PixVerse API v2 on useapi.net adds text-to-image with 7 models at roughly 3 to 60 seconds per image, with Nano Banana Pro examples and a same-prompt comparison." parent: Blog nav_exclude: true nav_order: -260309 --- [PixVerse API v2](/docs/api-pixverse-v2) updates: * [Image generation](/docs/api-pixverse-v2/post-pixverse-images-create) with 7 models — surprisingly fast, ~3s to ~60s per image * Pro+ plans include **unlimited image generation** in Relax Mode at the same fast speeds, see [PixVerse subscription plans](https://media.useapi.net/blog/2026-03-09-260309/pixverse-subscription-monthly.jpg){:target="_blank"} as of March 9, 2026 * Nano Banana models have relaxed content moderation — photos of minors or famous people supported as reference images --- ## Text-to-image via [POST images/create](/docs/api-pixverse-v2/post-pixverse-images-create) ### nano-banana-pro • 1080p • auto aspect ratio ```bash curl --location 'https://api.useapi.net/v2/pixverse/images/create' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: application/json' \ --data '{ "prompt": "A visually stunning, highly detailed, absurdly comical vertical 9:16 photograph. In the center, a stunningly beautiful young woman with a flawless, glowing, fit figure is wearing a vibrant, tiny tropical bikini swimsuit. Bizarrely, on her head, she is wearing a professional white beekeeper'\''s veil and helmet. She has a confident, upbeat posture as she pulls a wooden honeycomb frame, dripping with thick, glowing golden honey, out of a wooden beehive box in a sunlit, blooming meadow. In the top-left corner, a swarm of bees is hovering in a disorganized, confused cluster, completely puzzled and unsure of what to do. In the extreme top-right corner, there is a giant, macro close-up of a single fuzzy honeybee looking directly into the camera lens with a hilariously exaggerated, shocked, wide-open expression of pure disbelief. Bright, cinematic summer sunlight, highly aesthetic body proportions mixed with an odd, crazy situation, perfectly photorealistic, rich vibrant colors, masterpiece.", "model": "nano-banana-pro", "quality": "1080p", "aspect_ratio": "auto" }' ``` <img src="https://media.useapi.net/blog/2026-03-09-260309/pixverse-auto-nano-banana-pro-1080p-auto-img1.png" style="width: 100%; max-width: 400px;" /> --- ### Model comparison • 1080p–1440p • 16:9 Same prompt across all models: ```bash curl --location 'https://api.useapi.net/v2/pixverse/images/create' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: application/json' \ --data '{ "prompt": "A visually breathtaking, beautifully absurd, single-frame street photography shot on a sunny city sidewalk. In the center midground, a gorgeous, stunningly beautiful young woman with a soft, elegant feminine figure, a flawless glowing complexion, and a radiant, upbeat laugh is wearing a tiny, elegant black-lace string bikini. She is effortlessly operating a heavy, rattling, bright yellow pneumatic jackhammer, busting up the concrete pavement while dust and debris fly around her beautifully. In the extreme bottom-right foreground of the exact same scene, standing on the sidewalk and photobombing the camera lens, is a huge forced-perspective close-up of a city squirrel. The squirrel is holding a half-eaten hotdog, staring directly into the lens with bulging, mind-blown eyes, completely frozen in comical disbelief. Single cohesive image, seamless depth of field, dynamic lighting, crazy situational comedy, delicate feminine features contrasting with heavy machinery, masterpiece.", "model": "<model>", "quality": "<quality>", "aspect_ratio": "16:9" }' ``` **nano-banana-pro** • 1080p (~60s): <img src="https://media.useapi.net/blog/2026-03-09-260309/pixverse-base-nano-banana-pro-1080p-16x9-img1.png" style="width: 100%; max-width: 600px;" /> **nano-banana** • 1080p (~10s): <img src="https://media.useapi.net/blog/2026-03-09-260309/pixverse-base-nano-banana-1080p-16x9-img1.png" style="width: 100%; max-width: 600px;" /> **seedream-5.0-lite** • 1440p (~30s): <img src="https://media.useapi.net/blog/2026-03-09-260309/pixverse-base-seedream-5.0-lite-1440p-16x9-img1.png" style="width: 100%; max-width: 600px;" /> **seedream-4.5** • 1440p (~15s): <img src="https://media.useapi.net/blog/2026-03-09-260309/pixverse-base-seedream-4.5-1440p-16x9-img1.png" style="width: 100%; max-width: 600px;" /> **seedream-4.0** • 1080p (~10s): <img src="https://media.useapi.net/blog/2026-03-09-260309/pixverse-base-seedream-4.0-1080p-16x9-img1.png" style="width: 100%; max-width: 600px;" /> **qwen-image** • 1080p (~3s): <img src="https://media.useapi.net/blog/2026-03-09-260309/pixverse-base-qwen-image-1080p-16x9-img1.png" style="width: 100%; max-width: 600px;" /> --- ## Image-to-image (reference images) ### nano-banana-2 • 1 reference • 1080p • 16:9 [Reference image](https://media.useapi.net/blog/2026-02-27-260227/contextreference-2.jpg){:target="_blank"} (classic 1920s BMW motorcycle) ```bash curl --location 'https://api.useapi.net/v2/pixverse/images/create' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: application/json' \ --data '{ "prompt": "Transform this classic motorcycle into a futuristic cyberpunk hover bike with glowing neon underglow and holographic dashboard", "model": "nano-banana-2", "quality": "1080p", "aspect_ratio": "16:9", "image_path_1": "<path from POST files>" }' ``` <img src="https://media.useapi.net/blog/2026-03-09-260309/pixverse-i2i-nano-banana-2-motorcycle-1080p-16x9-img1.png" style="width: 100%; max-width: 600px;" /> --- ### seedream-4.5 • 1 reference • 1440p • 16:9 [Reference image](https://media.useapi.net/blog/2026-02-27-260227/contextreference-3.jpg){:target="_blank"} (Golden Gate Bridge from Baker Beach) ```bash curl --location 'https://api.useapi.net/v2/pixverse/images/create' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: application/json' \ --data '{ "prompt": "Render this iconic bridge scene as an impressionist oil painting at sunset with dramatic purple and orange sky reflections on the water", "model": "seedream-4.5", "quality": "1440p", "aspect_ratio": "16:9", "image_path_1": "<path from POST files>" }' ``` <img src="https://media.useapi.net/blog/2026-03-09-260309/pixverse-i2i-seedream-4.5-bridge-1440p-16x9-img1.png" style="width: 100%; max-width: 600px;" /> --- ### seedream-4.0 • 2 references • 1080p • 16:9 [Reference image 1](https://media.useapi.net/blog/2026-03-05-260305/contextreference-1.jpg){:target="_blank"} (vintage Edwardian woman portrait) [Reference image 2](https://media.useapi.net/blog/2026-02-27-260227/contextreference-2.jpg){:target="_blank"} (classic BMW motorcycle) ```bash curl --location 'https://api.useapi.net/v2/pixverse/images/create' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: application/json' \ --data '{ "prompt": "An elegant Edwardian woman riding a gleaming vintage motorcycle through a misty countryside road at dawn", "model": "seedream-4.0", "quality": "1080p", "aspect_ratio": "16:9", "image_path_1": "<path from POST files>", "image_path_2": "<path from POST files>" }' ``` <img src="https://media.useapi.net/blog/2026-03-09-260309/pixverse-i2i-seedream-4.0-2refs-vintage-moto-1080p-16x9-img1.png" style="width: 100%; max-width: 600px;" /> === URL: https://useapi.net/blog/260309i === Document URL: https://useapi.net/blog/260309i --- layout: blog_post title: "AI Image Models: 17 Compared" description: "We ran the same text to image generation through 17 image generation models to see how each one interprets it. All images use 16:9 aspect ratio with…" parent: Blog nav_exclude: true nav_order: -260309 --- # 17 AI Image Models: The Showdown March 9, 2026 ## Table of contents ## Introduction We ran the same text to image generation through 17 image generation models to see how each one interprets it. All images use 16:9 aspect ratio with resolution closest to 1080p — not all models support it since some start at 2K and up. Google Flow's version of Nano Banana models was too restrictive for this prompt, so Nano Banana generation was done via [PixVerse](https://pixverse.ai) instead. ### Why this prompt This prompt stress-tests NSFW content moderation boundaries, multi-subject composition with precise spatial layout, forced perspective depth of field, contradictory context (bikini + jackhammer), specific animal facial expressions, prop fidelity, single cohesive frame rendering, dynamic action, and clashing tone contrast — all in one image. ### Prompt 14 of 17 models used the same prompt: ``` A visually breathtaking, beautifully absurd, single-frame street photography shot on a sunny city sidewalk. In the center midground, a gorgeous, stunningly beautiful young woman with a soft, elegant feminine figure, a flawless glowing complexion, and a radiant, upbeat laugh is wearing a tiny, elegant black-lace string bikini. She is effortlessly operating a heavy, rattling, bright yellow pneumatic jackhammer, busting up the concrete pavement while dust and debris fly around her beautifully. In the extreme bottom-right foreground of the exact same scene, standing on the sidewalk and photobombing the camera lens, is a huge forced-perspective close-up of a city squirrel. The squirrel is holding a half-eaten hotdog, staring directly into the lens with bulging, mind-blown "o_O" eyes, completely frozen in comical disbelief. Single cohesive image, seamless depth of field, no cut-ins, dynamic lighting, crazy situational comedy, delicate feminine features contrasting with heavy machinery, masterpiece. ``` **Imagen 4** — Google's content moderation required a toned-down version: `...is wearing a stylish summer swimsuit...` (all other text identical). **GPT Image 2** — like Imagen 4, OpenAI's content moderation required the toned-down version (`...stylish summer swimsuit...`). **Midjourney v7** — rewritten for Midjourney's style: ``` A wide-angle GoPro action-camera shot of a sunny city sidewalk. In the extreme bottom-right foreground, a shocked squirrel's face photobombs the lens while holding a hotdog. In the center midground, a stunning woman in a tiny black lace bikini is clearly visible and in sharp focus, operating a heavy yellow jackhammer. Concrete debris flying, 8k, deep depth of field, f/11, high-speed shutter, absurd comedy ``` ### How it was generated All images were generated on the actual provider websites ([PixVerse](https://pixverse.ai), [Dreamina](https://dreamina.bytedance.com), [MiniMax/HailuoAI](https://hailuoai.video), [Runway](https://app.runwayml.com), [Google Flow](https://labs.google/fx/tools/video-fx), [Kling](https://klingai.com), [Midjourney](https://midjourney.com)) — our [third-party API](https://useapi.net) is just a smart proxy service that automates interaction with the provider websites and does not generate images itself. ### Unlimited generations [PixVerse](/docs/api-pixverse-v2), [Google Flow](/docs/api-google-flow-v1), [Dreamina](/docs/api-dreamina-v1), and [Runway](/docs/api-runwayml-v1) support unlimited image generations for select models depending on the underlying website subscription plan. --- ## Midjourney v7 <img src="https://media.useapi.net/blog/2026-03-09-260309i/midjourney-v7-via-midjourney-api-by-useapi.net.jpg" style="width: 100%;" /> [open in new tab](https://media.useapi.net/blog/2026-03-09-260309i/midjourney-v7-via-midjourney-api-by-useapi.net.jpg){:target="_blank"} Midjourney v7 via [MiniMax API](/docs/api-minimax-v1) — [POST images/create](/docs/api-minimax-v1/post-minimax-images-create){:target="_blank"} (model `midjourney-v7`) --- ## GPT Image 2 <img src="https://media.useapi.net/blog/2026-03-09-260309i/gpt-2.png" style="width: 100%;" /> [open in new tab](https://media.useapi.net/blog/2026-03-09-260309i/gpt-2.png){:target="_blank"} GPT Image 2 (OpenAI) via [MiniMax API](/docs/api-minimax-v1) — [POST images/create](/docs/api-minimax-v1/post-minimax-images-create){:target="_blank"} (model `gpt-image-2`) --- ## GPT Image 1.5 <img src="https://media.useapi.net/articles/2024-09-28-minimax-bash/gpt-image-1.5-via-minimax-api-by-useapi.net.png" style="width: 100%;" /> [open in new tab](https://media.useapi.net/articles/2024-09-28-minimax-bash/gpt-image-1.5-via-minimax-api-by-useapi.net.png){:target="_blank"} GPT Image 1.5 (OpenAI) via [MiniMax API](/docs/api-minimax-v1) — [POST images/create](/docs/api-minimax-v1/post-minimax-images-create){:target="_blank"} --- ## GPT Image 1 Mini <img src="https://media.useapi.net/blog/2026-03-09-260309i/gpt-image-1-mini-via-runway-api-by-useapi.net.png" style="width: 100%;" /> [open in new tab](https://media.useapi.net/blog/2026-03-09-260309i/gpt-image-1-mini-via-runway-api-by-useapi.net.png){:target="_blank"} GPT Image 1 Mini (OpenAI) via [Runway API](/docs/api-runwayml-v1) — [POST images/create](/docs/api-runwayml-v1/post-runwayml-images-create){:target="_blank"} --- ## Nano Banana Pro <img src="https://media.useapi.net/blog/2026-03-09-260309i/nano-banana-pro-via-pixverse-api-by-useapi.net.png" style="width: 100%;" /> [open in new tab](https://media.useapi.net/blog/2026-03-09-260309i/nano-banana-pro-via-pixverse-api-by-useapi.net.png){:target="_blank"} Nano Banana Pro ([Gemini 3.0](https://deepmind.google/technologies/gemini/)) via [PixVerse API](/docs/api-pixverse-v2) — [POST images/create](/docs/api-pixverse-v2/post-pixverse-images-create){:target="_blank"} --- ## Nano Banana 2 <img src="https://media.useapi.net/blog/2026-03-09-260309i/nano-banana-2-via-pixverse-api-by-useapi.net.png" style="width: 100%;" /> [open in new tab](https://media.useapi.net/blog/2026-03-09-260309i/nano-banana-2-via-pixverse-api-by-useapi.net.png){:target="_blank"} Nano Banana 2 ([Gemini 3.1 Flash](https://deepmind.google/technologies/gemini/flash/)) via [PixVerse API](/docs/api-pixverse-v2) — [POST images/create](/docs/api-pixverse-v2/post-pixverse-images-create){:target="_blank"} --- ## Nano Banana <img src="https://media.useapi.net/blog/2026-03-09-260309i/nano-banana-via-pixverse-api-by-useapi.net.png" style="width: 100%;" /> [open in new tab](https://media.useapi.net/blog/2026-03-09-260309i/nano-banana-via-pixverse-api-by-useapi.net.png){:target="_blank"} Nano Banana ([Gemini 2.5 Flash](https://deepmind.google/technologies/gemini/flash/)) via [PixVerse API](/docs/api-pixverse-v2) — [POST images/create](/docs/api-pixverse-v2/post-pixverse-images-create){:target="_blank"} --- ## Kling Kolors v3.0 <img src="https://media.useapi.net/blog/2026-03-09-260309i/kling-kolors-v3.0-via-kling-api-by-useapi.net.png" style="width: 100%;" /> [open in new tab](https://media.useapi.net/blog/2026-03-09-260309i/kling-kolors-v3.0-via-kling-api-by-useapi.net.png){:target="_blank"} Kling Kolors v3.0 via [Kling API](/docs/api-kling-v1) — [POST images/kolors](/docs/api-kling-v1/post-kling-images-kolors){:target="_blank"} --- ## Kling Kolors v2.1 <img src="https://media.useapi.net/blog/2026-03-09-260309i/kling-kolors-v2.1-via-kling-api-by-useapi.net.png" style="width: 100%;" /> [open in new tab](https://media.useapi.net/blog/2026-03-09-260309i/kling-kolors-v2.1-via-kling-api-by-useapi.net.png){:target="_blank"} Kling Kolors v2.1 via [Kling API](/docs/api-kling-v1) — [POST images/kolors](/docs/api-kling-v1/post-kling-images-kolors){:target="_blank"} --- ## Seedream 5.0 Lite <img src="https://media.useapi.net/blog/2026-03-09-260309i/seedream-5.0-lite-via-pixverse-api-by-useapi.net.png" style="width: 100%;" /> [open in new tab](https://media.useapi.net/blog/2026-03-09-260309i/seedream-5.0-lite-via-pixverse-api-by-useapi.net.png){:target="_blank"} [Seedream 5.0 Lite](https://seed.bytedance.com/en/seedream) via [PixVerse API](/docs/api-pixverse-v2) — [POST images/create](/docs/api-pixverse-v2/post-pixverse-images-create){:target="_blank"} --- ## Seedream 4.6 <img src="https://media.useapi.net/blog/2026-03-09-260309i/seedream-4.6-via-dreamina-api-by-useapi.net.jpg" style="width: 100%;" /> [open in new tab](https://media.useapi.net/blog/2026-03-09-260309i/seedream-4.6-via-dreamina-api-by-useapi.net.jpg){:target="_blank"} [Seedream 4.6](https://seed.bytedance.com/en/seedream) via [Dreamina API](/docs/api-dreamina-v1) — [POST images](/docs/api-dreamina-v1/post-dreamina-images){:target="_blank"} --- ## Seedream 4.5 <img src="https://media.useapi.net/blog/2026-03-09-260309i/seedream-4.5-via-pixverse-api-by-useapi.net.png" style="width: 100%;" /> [open in new tab](https://media.useapi.net/blog/2026-03-09-260309i/seedream-4.5-via-pixverse-api-by-useapi.net.png){:target="_blank"} [Seedream 4.5](https://seed.bytedance.com/en/seedream) via [PixVerse API](/docs/api-pixverse-v2) — [POST images/create](/docs/api-pixverse-v2/post-pixverse-images-create){:target="_blank"} --- ## Seedream 4.1 <img src="https://media.useapi.net/blog/2026-03-09-260309i/seedream-4.1-via-dreamina-api-by-useapi.net.jpg" style="width: 100%;" /> [open in new tab](https://media.useapi.net/blog/2026-03-09-260309i/seedream-4.1-via-dreamina-api-by-useapi.net.jpg){:target="_blank"} [Seedream 4.1](https://seed.bytedance.com/en/seedream) via [Dreamina API](/docs/api-dreamina-v1) — [POST images](/docs/api-dreamina-v1/post-dreamina-images){:target="_blank"} --- ## Seedream 4.0 <img src="https://media.useapi.net/blog/2026-03-09-260309i/seedream-4.0-via-pixverse-api-by-useapi.net.png" style="width: 100%;" /> [open in new tab](https://media.useapi.net/blog/2026-03-09-260309i/seedream-4.0-via-pixverse-api-by-useapi.net.png){:target="_blank"} [Seedream 4.0](https://seed.bytedance.com/en/seedream) via [PixVerse API](/docs/api-pixverse-v2) — [POST images/create](/docs/api-pixverse-v2/post-pixverse-images-create){:target="_blank"} --- ## Imagen 4 <img src="https://media.useapi.net/blog/2026-03-09-260309i/imagen-4-via-google-flow-api-by-useapi.net.png" style="width: 100%;" /> [open in new tab](https://media.useapi.net/blog/2026-03-09-260309i/imagen-4-via-google-flow-api-by-useapi.net.png){:target="_blank"} Imagen 4 (Google) via [Google Flow API](/docs/api-google-flow-v1) — [POST images](/docs/api-google-flow-v1/post-google-flow-images){:target="_blank"} Note: uses toned-down prompt (see above) --- ## Qwen Image <img src="https://media.useapi.net/blog/2026-03-09-260309i/qwen-image-via-pixverse-api-by-useapi.net.png" style="width: 100%;" /> [open in new tab](https://media.useapi.net/blog/2026-03-09-260309i/qwen-image-via-pixverse-api-by-useapi.net.png){:target="_blank"} Qwen Image ([Qwen2.5-VL](https://github.com/QwenLM/Qwen2.5-VL)) via [PixVerse API](/docs/api-pixverse-v2) — [POST images/create](/docs/api-pixverse-v2/post-pixverse-images-create){:target="_blank"} --- ## Runway Gen4 <img src="https://media.useapi.net/blog/2026-03-09-260309i/runway-gen4-via-runway-api-by-useapi.net.png" style="width: 100%;" /> [open in new tab](https://media.useapi.net/blog/2026-03-09-260309i/runway-gen4-via-runway-api-by-useapi.net.png){:target="_blank"} Runway Gen4 via [Runway API](/docs/api-runwayml-v1) — [POST images/create](/docs/api-runwayml-v1/post-runwayml-images-create){:target="_blank"} === URL: https://useapi.net/blog/260321 === Document URL: https://useapi.net/blog/260321 --- layout: blog_post title: "TemPolor: v4.5+ Song Model With 16+ Languages" description: "TemPolor API v1 now supports the v4.5+ song model — a next-gen proprietary model with 16+ languages and up to 5 minutes of generated music. It is now the…" parent: Blog nav_exclude: true nav_order: -260321 --- [TemPolor API v1](/docs/api-tempolor-v1) now supports the `v4.5+` song model — a next-gen proprietary model with **16+ languages** and up to **5 minutes** of generated music. It is now the default song model. A single song featuring lyrics in **English, Spanish, French, Chinese, Hindi, Japanese, Arabic, Korean, and Russian** — all generated in one pass with the `v4.5+` model. [POST music/song](/docs/api-tempolor-v1/post-tempolor-music-song) <details markdown="block"> <summary>Full lyrics (click to expand)</summary> ```text [Intro] Welcome back please enter your password Incorrect Contraseña incorrecta Mot de passe invalide 密码错误 You have one attempt remaining before you are locked out of your own life [Verse] It's 2 AM the screen is bright I just wanna buy some socks tonight I type my email hit the key But the glowing red text is mocking me Was it my dog's name was it my ex Mera password kya hai I'm sweating now the stakes are high If I fail this time my account will die [Verse] It needs a capital letter It needs a number or two Ay Dios mío no me acuerdo It needs a hieroglyph from ancient Peru Je perds la tête what do I do I'm throwing my laptop out of the chair [Chorus] I forgot my password error four oh four Nasitu kalimat al murur I'm locked outside my digital door Pasuwādo o wasuremashita Was it password one two three was it monkey bite I'm gonna be resetting this all damn night [Inst] [Verse] Check my email click the link Now prove I'm human make me think A CAPTCHA pops up on the screen Я не робот what does this mean Select all the images with a bus Is that a bus or a van why the fuss Wo bu shi ji qi ren I swear to you This artificial intelligence is making me blue [Verse] Is the crosswalk the pole or just the paint Robotto de wa arimasen Mujhe nahi pata I feel faint It needs a special symbol a lock of my hair 제발 살려줘 it isn't fair [Chorus] I forgot my password error four oh four Nasitu kalimat al murur I'm locked outside my digital door Pasuwādo o wasuremashita Was it password one two three was it monkey bite I'm gonna be resetting this all damn night [Inst] [Bridge] I finally passed the CAPTCHA I proved I have a soul I typed a brand new password to regain my control I hit submit and waited for the screen to load But then the red text came back It said new password cannot be the same as the old password If it was the same as the old password Then why didn't it work the first time Khata Oshibka Cuowu Why didn't it work the first time! [Chorus] I forgot my password error four oh four Nasitu kalimat al murur I'm locked outside my digital door Pasuwādo o wasuremashita Was it password one two three was it monkey bite I'm gonna be resetting this all damn night [Inst] [Outro] Old password new password Ошибка доступа Bimilbeonhoreul ijeusyeonnayo I just wanted to buy socks Au revoir my digital life You know what never mind I'll just check out as a guest ``` </details> ```bash curl --location 'https://api.useapi.net/v1/tempolor/music/song' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: application/json' \ --data '{ "prompt": "Eurodance, Electro House, EDM, heavy bass drop", "lyrics": "[Intro]\nWelcome back please enter your password…", "model_song": "v4.5+" }' ``` <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-03-21-260321/tempolor-45.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> === URL: https://useapi.net/blog/260402 === Document URL: https://useapi.net/blog/260402 --- layout: blog_post title: "Dreamina: Seedance 2.0 Video Generation" description: "Dreamina API v1 now supports the CA (Canada) region with access to Seedance 2.0 — ByteDance's latest and most capable video generation model. Also new: 1080p…" parent: Blog nav_exclude: true nav_order: -260402 --- [Dreamina API v1](/docs/api-dreamina-v1) now supports the **CA (Canada) region** with access to **Seedance 2.0** — ByteDance's latest and most capable video generation model. Also new: **1080p resolution**, **video upscale** (2x super resolution), and **Omni Reference** mode for interleaved text and image references. All videos below were upscaled to 2x resolution using [POST /videos/upscale](/docs/api-dreamina-v1/post-dreamina-videos-upscale). --- ### Omni Reference — interleaved text and image references Upload reference images via [POST /assets](/docs/api-dreamina-v1/post-dreamina-assets-account), then use `@imageN` placeholders in your prompt to reference them. <div style="display:flex;gap:8px;flex-wrap:wrap;margin-bottom:12px"> <div>@image1<br><img src="https://media.useapi.net/blog/2026-04-02-260402/cute-assasin-lady-2.png" style="height:200px"></div> <div>@image2<br><img src="https://media.useapi.net/blog/2026-04-02-260402/1932-bmw-r32.webp" style="height:200px"></div> <div>@image3<br><img src="https://media.useapi.net/blog/2026-04-02-260402/runway-seedream-5-0-ref.jpg" style="height:200px"></div> </div> ```bash curl --location 'https://api.useapi.net/v1/dreamina/videos' \ --header 'Authorization: Bearer user:12345-…' \ --form 'prompt="Cinematic, photorealistic tracking shot. A @image1 rides the @image2 along a sandy, rocky beach, cutting thru the waves. @image3 looms in the foggy background with crashing ocean waves. @image1 lets go of the handlebars, spreads her arms wide into the wind, and shouts joyfully with perfect lip-sync: '\''Whoo hoo! I'\''m flying!'\'' Dynamic motion, wind effects, highly detailed."' \ --form 'ratio="16:9"' \ --form 'duration="15"' \ --form 'omni_1_imageRef="CA:user@email.com-image:w1088:h1920:s1800540-uri:…"' \ --form 'omni_2_imageRef="CA:user@email.com-image:w2560:h1440:s181878-uri:…"' \ --form 'omni_3_imageRef="CA:user@email.com-image:w2848:h1600:s442898-uri:…"' ``` <video poster="https://media.useapi.net/blog/2026-04-02-260402/seedance-2.0-omni-poster.jpg" controls width="100%"> <source src="https://media.useapi.net/blog/2026-04-02-260402/seedance-2.0-omni.mp4" type="video/mp4"> </video> --- ### First Frame — image-to-video with lip-sync <img src="https://media.useapi.net/blog/2026-04-02-260402/start-frame.jpg" style="max-width:400px"> ```bash curl --location 'https://api.useapi.net/v1/dreamina/videos' \ --header 'Authorization: Bearer user:12345-…' \ --form 'prompt="The giant red, winged demonic monster looming over the warrior suddenly stops acting menacing. It drops its clawed hands, sighs, and speaks in a deep, terrifying, roaring monster voice with perfect lip-sync: '\''Hold up, dude! I'\''m literally just walking to the market to get some wine!'\'' The massive demon then comically slumps its shoulders and sits down in the dusty ruins. Ignoring the demon, the warrior in the red cape suddenly turns his head to face the camera directly. Looking straight at the viewer, he proudly raises his fist and shouts in a booming voice with perfect lip-sync: '\''Glory to Rome!'\'' High fantasy meets mundane comedy, cinematic motion, realistic dust particles."' \ --form 'model="seedance-2.0"' \ --form 'duration="15"' \ --form 'firstFrameRef="CA:user@email.com-image:w1376:h768:s695678-uri:…"' ``` <video poster="https://media.useapi.net/blog/2026-04-02-260402/seedance-2.0-start-frame-poster.jpg" controls width="100%"> <source src="https://media.useapi.net/blog/2026-04-02-260402/seedance-2.0-start-frame.mp4" type="video/mp4"> </video> --- ### Text-to-video — prompt only with lip-sync ```bash curl --location 'https://api.useapi.net/v1/dreamina/videos' \ --header 'Authorization: Bearer user:12345-…' \ --form 'prompt="TikTok POV selfie-camera angle. A stylish, trendy Gen-Z girl stands outside an aesthetic pastel coffee shop on a sunny street, holding up a plastic iced coffee cup. She looks directly into the camera lens with a deadpan, slightly traumatized expression and speaks in a fast, sarcastic, comedic voice with perfect lip-sync: '\''I just paid twelve dollars for an oat milk latte... and the barista looked me dead in the eyes and wrote Gargoyle on my cup. My name is Chloe.'\'' She sighs, breaks eye contact, and takes a slow, aggressive sip of her iced coffee. Modern influencer aesthetic, bright natural lighting, highly detailed, photorealistic."' \ --form 'model="seedance-2.0"' \ --form 'ratio="9:16"' \ --form 'duration="15"' ``` <video poster="https://media.useapi.net/blog/2026-04-02-260402/seedance-2.0-prompt-9-16-poster.jpg" controls width="300"> <source src="https://media.useapi.net/blog/2026-04-02-260402/seedance-2.0-prompt-9-16.mp4" type="video/mp4"> </video> Compare every Seedance 2.0 and 2.5 route and price: [Seedance 2.0 and 2.5 API Pricing](/docs/articles/seedance-2-api-pricing). === URL: https://useapi.net/blog/260403 === Document URL: https://useapi.net/blog/260403 --- layout: blog_post title: "Google Flow: Veo 3.1 Lite and Voice Narration" description: "Google Flow API v1 now supports Veo 3.1 Lite — a faster, cheaper model at just 5 credits ($0.025) per video — and voice narration with 30 AI voice presets…" parent: Blog nav_exclude: true nav_order: -260403 --- ## Veo 3.1 Lite & Voice Narration --- [Google Flow API v1](/docs/api-google-flow-v1) now supports **Veo 3.1 Lite** — a faster, cheaper model at just 5 credits ($0.025) per video — and **voice narration** with 30 AI voice presets for adding spoken dialogue to generated videos. For a step-by-step walkthrough with curl, see the [Veo 3.1 API tutorial](/docs/articles/google-flow-bash). --- ### Voice Narration — AI voices for video dialogue Add a `voice` parameter to any R2V (reference image) generation to include AI narration. 30 voice presets are available — preview them in the [Try It](/docs/api-google-flow-v1/post-google-flow-videos#try-it) section. <div style="margin-bottom:12px"> Reference image<br> <img src="https://media.useapi.net/blog/2026-04-03-260403/lady-and-her-dog.webp" style="max-width:300px"> (Zephyr voice preview)<br> <audio controls src="https://www.gstatic.com/aistudio/voices/samples/Zephyr.wav" style="width:300px"></audio> </div> ```bash curl -X POST \ -H "Authorization: Bearer user:12345-…" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A lady says to the dog, '\''Say meow meow meow.'\'' The dog looks at the lady with a surprised and frustrated look and woofs in a human voice, '\''What the heck lady?!'\''", "model": "veo-3.1-fast-relaxed", "aspectRatio": "portrait", "referenceImage_1": "user:12345-email:…-image:abcde-…", "voice": "zephyr" }' \ "https://api.useapi.net/v1/google-flow/videos" ``` <video poster="https://media.useapi.net/blog/2026-04-03-260403/veo-3-1-fast-voice-zephyr-poster.jpg" controls width="100%" style="max-width:400px"> <source src="https://media.useapi.net/blog/2026-04-03-260403/veo-3-1-fast-voice-zephyr.mp4" type="video/mp4"> </video> --- ### Veo 3.1 Lite — fast and affordable `veo-3.1-lite` generates videos at 5 credits ($0.025) per video — half the cost of Veo 3.1 Fast. Supports text-to-video, start frame (I2V), and start+end frame interpolation (I2V-FL). | Model | Cost | Modes | |-------|------|-------| | `veo-3.1-quality` | 100 credits / $0.50 | T2V, I2V, I2V-FL | | `veo-3.1-fast` | 10 credits / $0.05 | T2V, I2V, I2V-FL, R2V, Voice | | `veo-3.1-fast-relaxed` | free (Ultra only) | T2V, I2V, I2V-FL, R2V, Voice | | **`veo-3.1-lite`** | **5 credits / $0.025** | T2V, I2V, I2V-FL | ```bash curl -X POST \ -H "Authorization: Bearer user:12345-…" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A calm river flowing through a green valley with morning mist", "model": "veo-3.1-lite", "aspectRatio": "landscape" }' \ "https://api.useapi.net/v1/google-flow/videos" ``` --- ### Available voice presets 30 voice presets with astronomical names. Preview any voice at `https://www.gstatic.com/aistudio/voices/samples/{Name}.wav` Achird, Achernar, Algieba, Algenib, 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 === URL: https://useapi.net/blog/260404 === Document URL: https://useapi.net/blog/260404 --- layout: blog_post title: "Mureka: V9 Now the Default Music Model" description: "Mureka API v1 now supports the latest V9 model as the new default. V9 features advanced prompt control and studio-grade sound at 12 credits per song." parent: Blog nav_exclude: true nav_order: -260404 --- [Mureka API v1](/docs/api-mureka-v1) now supports the latest `V9` model as the new default. V9 features advanced prompt control and studio-grade sound at 12 credits per song. **Music V9 Female** - Astro Gardener ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-advanced' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: application/json' \ --data '{ "lyrics": "[Verse 1]\nPlanting roses on the rings of Saturn\nWatering moonflowers in zero gravity pattern\nComets bring the seeds I need\nGrowing cosmic flowers from a supernova seed\n\n[Chorus]\nI'\''m the astro gardener floating free\nTending galaxies you'\''ll never see\nSolar winds blow through my hair\nStarlight orchids everywhere", "desc": "dreamy indie pop, floating guitars, cosmic reverb, hopeful and whimsical", "vocal_gender": "female", "model": "V9" }' ``` <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-04-04-260404/music-v9-female-astrogardener-astro-gardener-v9-v2.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> **Music V9 Male** - Haunted Wifi ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-advanced' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: application/json' \ --data '{ "lyrics": "[Verse 1]\nSignal bars are flickering at three AM\nSomething in the router wants to be my friend\nDownloads starting by themselves again\nGhost in the bandwidth sending data from the end\n\n[Chorus]\nHaunted wifi in my walls\nPhantom packets through the halls\nEvery ping returns a scream\nDigital nightmares in the stream", "desc": "dark synthwave, eerie pads, pulsing bass, ghostly atmosphere, horror movie vibes", "vocal_gender": "male", "model": "V9" }' ``` <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-04-04-260404/music-v9-male-hauntedwifi-haunted-wifi-v9-v2.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> **Instrumental V9** - Cascading Sunrise ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-instrumental' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: application/json' \ --data '{ "prompt": "Ethereal post-rock with cascading delay guitars, orchestral swells, driving drums building to a cinematic crescendo - sunrise over mountain peaks", "model": "V9" }' ``` <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-04-04-260404/async-instrumental-v9-async-untitled-v2.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> === URL: https://useapi.net/blog/260405 === Document URL: https://useapi.net/blog/260405 --- layout: blog_post title: "PixVerse v6: Multi-Shot Storytelling and Audio" description: "PixVerse API v2 now supports the latest v6 model as the new default — the most advanced and cost-effective PixVerse model yet." parent: Blog nav_exclude: true nav_order: -260405 --- [PixVerse API v2](/docs/api-pixverse-v2) now supports the latest `v6` model as the new default — the most advanced and cost-effective PixVerse model yet. See [Model Capabilities](/docs/api-pixverse-v2/model-capabilities) for the complete feature matrix. --- ## What's New in V6 * **Duration up to 15 seconds** at all qualities including 1080p (v5.x was limited to 10s, 8s at 1080p) * **Multi-shot storytelling** (`multi_shot: true`) — generates videos with multiple camera angles and scene cuts * **Integrated audio** — voice, lip sync, and background music in a single step * **Default quality 720p** (up from 540p) * **Extend with audio** — audio generation now supported on video extensions * Most cost-effective: 15s 1080p with audio for just 210 credits ($0.84) ## Examples ### Text-to-Video • 15s 1080p • multi-shot + audio ```bash curl --location 'https://api.useapi.net/v2/pixverse/videos/create' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: application/json' \ --data '{ "prompt": "A dramatic courtroom scene: a tall sharp-faced male lawyer in a navy suit slams his fist on the oak table and shouts \"You were there that night!\", cut to the young blonde female defendant in a white blouse whispering tearfully \"I did not do it\", cut to an elderly bald male juror in glasses turning to a middle-aged Black woman juror beside him as the packed gallery of spectators gasps in shock, cut to the stern gray-haired male judge in black robes banging his wooden gavel forcefully and bellowing \"Order in the court!\"", "model": "v6", "duration": "15", "quality": "1080p", "aspect_ratio": "16:9", "audio": true, "multi_shot": true }' ``` <video poster="https://media.useapi.net/articles/2024-06-08-pixverse-demo/t2v-v6-15s-1080p-16x9-audio-mshot-poster.jpg" src="https://media.useapi.net/articles/2024-06-08-pixverse-demo/t2v-v6-15s-1080p-16x9-audio-mshot.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> --- ### Text-to-Video • 15s 1080p • audio ```bash curl --location 'https://api.useapi.net/v2/pixverse/videos/create' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: application/json' \ --data '{ "prompt": "Two ancient warriors face each other on a cliff at golden hour. The challenger shouts \"Your reign ends today!\" and charges with sword raised. Blades clash with sparks flying as the camera orbits around them revealing an army below. The defender grunts \"You know nothing of power\" and parries. After a fierce exchange the challenger lands a decisive blow, the defeated warrior falls to one knee, and the victor raises their sword shouting \"For the kingdom!\" against a blood-red sunset", "model": "v6", "duration": "15", "quality": "1080p", "aspect_ratio": "16:9", "audio": true }' ``` <video poster="https://media.useapi.net/blog/2026-04-05-260405/t2v-v6-15s-1080p-16x9-audio-poster.jpg" src="https://media.useapi.net/blog/2026-04-05-260405/t2v-v6-15s-1080p-16x9-audio.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> --- ### Image-to-Video • 10s 540p • multi-shot + audio Source image: <img src="https://media.useapi.net/blog/2026-04-05-260405/flirtybarista.jpg" style="width: 100%; max-width: 400px;" /> ```bash curl --location 'https://api.useapi.net/v2/pixverse/videos/create' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: application/json' \ --data '{ "prompt": "The subject turns dramatically toward camera, their coat swirling, points directly at the viewer and says \"Your turn\" with a smirk, then walks forward with purpose as city lights blur in the background", "model": "v6", "duration": "10", "quality": "540p", "first_frame_path": "upload/….jpeg", "audio": true, "multi_shot": true }' ``` <video poster="https://media.useapi.net/blog/2026-04-05-260405/i2v-v6-10s-540p-audio-mshot-poster.jpg" src="https://media.useapi.net/blog/2026-04-05-260405/i2v-v6-10s-540p-audio-mshot.mp4" style="width: 100%; max-width: 400px;" controls type="video/mp4" preload="metadata"></video> --- ## V6 Pricing (with audio included) | Quality | Per second | 10s | 15s | |:--------|:----------:|:---:|:---:| | 360p | 4 cr | 40 cr / $0.16 | 60 cr / $0.24 | | 540p | 6 cr | 60 cr / $0.24 | 90 cr / $0.36 | | 720p | 7 cr | 70 cr / $0.28 | 105 cr / $0.42 | | 1080p | 14 cr | 140 cr / $0.56 | 210 cr / $0.84 | Based on [$60/m Premium subscription](https://app.pixverse.ai/subscribe) (15,000 credits/month). === URL: https://useapi.net/blog/260415 === Document URL: https://useapi.net/blog/260415 --- layout: blog_post title: "Seedance 2.0: Using Real Faces (Tutorial)" description: "Seedance 2.0 is now available on both Runway API v1 and Dreamina API v1. The two integrations share the same underlying model but differ in one important…" parent: Blog nav_exclude: true nav_order: -260415 --- ## Tutorial: Using Real Faces with Seedance 2.0 Seedance 2.0 is now available on **both** [Runway API v1](/docs/api-runwayml-v1) and [Dreamina API v1](/docs/api-dreamina-v1). The two integrations share the same underlying model but differ in one important detail for end users: * **Runway** — no real-people restriction, lighter content moderation, `exploreMode` makes 15-second generations effectively free on the Unlimited plan * **Dreamina** — real human faces are moderated; use illustrated, anime or stylized character references This post walks through a single **cinematic finger-snap time-freeze** scene driven by one character reference image, submitted to both APIs from the same prompt. --- ## The reference image A single 9:16 editorial still of the subject — long dark hair, pale complexion — is all Seedance 2.0 needs to carry the character identity through the entire 15-second clip. **Two versions of the same portrait** were used — the unaltered original for Runway, and the same image with a sparse grid overlaid on the face for Dreamina: <table> <thead><tr><th>Runway input (original)</th><th>Dreamina input (face grid)</th></tr></thead> <tbody><tr> <td><img src="https://media.useapi.net/blog/2026-04-15-260415/model-original.webp" style="width: 100%;" /></td> <td><img src="https://media.useapi.net/blog/2026-04-15-260415/model-grid.webp" style="width: 100%;" /></td> </tr></tbody> </table> On Runway the unaltered image is uploaded once via [POST /assets](/docs/api-runwayml-v1/post-runwayml-assets); the returned `assetId` is passed as `imageAssetId1`. On Dreamina the grid-overlaid image is uploaded via [POST /assets/`account`](/docs/api-dreamina-v1/post-dreamina-assets-account) as type `image`; the returned `imageRef` is passed as `omni_1_imageRef`. --- ## How to use real faces in Seedance on Dreamina Dreamina's Seedance 2.0 input filter scans the reference image with a **face-detection classifier**; a high-confidence real-human-face hit is rejected before generation even starts with a moderation error. On Runway there is no such restriction, so the unmodified portrait goes straight through. Compare the two images above. The Dreamina version has a sparse mesh of thin crisscrossing lines overlaid **only** on the face region — roughly from the hairline down to the chin. The grid does not cover the hair, the dress, or any of the background. Everything else about the reference is identical to the Runway original. **Why it works:** * **Face classifiers are brittle to structured occlusion.** A sparse grid overlaid on key facial landmarks (eyes, nose, mouth contours) drops the classifier's confidence below the moderation threshold — the image is no longer tagged as a "real face". * **Seedance's reference conditioning is not a face classifier.** It is a dense-pixel visual encoder (similar to Kontext / IP-Adapter approaches) that still absorbs the underlying identity, hair color, skin tone, bone structure and wardrobe from the pixels *between* the grid lines. * The generated video — conditioned on the image as a whole — **reconstructs a coherent face** in every frame because Seedance has enough un-occluded signal to infer the identity. The grid itself never appears in the output. ## Fully automated grid — free face detection via Kling Hard-coding face-box coordinates is fine for a one-off, but for a pipeline you want the face location auto-detected. Kling provides a **free, unlimited face-detection endpoint** at [POST /images/recognize-faces](/docs/api-kling-v1/post-kling-images-recognize-faces) that returns exact face bounding boxes — no credit cost, works on the free Kling plan. **Step 1 — detect the face box.** Upload the portrait via [POST /assets](/docs/api-kling-v1/post-kling-assets) to get a public URL, then: ```bash curl -sS -X POST 'https://api.useapi.net/v1/kling/images/recognize-faces' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ --data '{"imageReference": "https://.../portrait.jpg"}' ``` Response — the first face's `face_bound` is a JSON string carrying `{x, y, width, height}` in image pixels: ```json { "status": 0, "faceItems": [{ "name": "face_0", "arguments": [{ "name": "face_bound", "value": "{\"x\":120,\"y\":80,\"width\":200,\"height\":240}" }] }], "mediaInfo": { "width": 724, "height": 1268 } } ``` **Step 2 — apply the grid only on those bounds** with `ffmpeg`: ```bash # Pull the numbers out of the Kling response (requires jq) eval "$(echo "$KLING_RESPONSE" | jq -r ' .faceItems[0].arguments[] | select(.name=="face_bound").value | fromjson | "FX=\(.x); FY=\(.y); FW=\(.width); FH=\(.height)"')" ffmpeg -y -i portrait.jpg -vf "\ geq=lum='p(X,Y)*if(between(X,${FX},${FX}+${FW})*between(Y,${FY},${FY}+${FH})*\ (lt(mod(X-${FX},40),1)+lt(mod(Y-${FY},40),1)),0.92,1)':\ cb='p_cb(X,Y)':cr='p_cr(X,Y)'" portrait_grid.jpg ``` The grid is clipped exactly to the detected face rectangle and lined up on a 40-pixel pitch originating from the face-box top-left — tune the `40` for a coarser or finer mesh. The subtler the grid, the safer it is against future classifier updates, but too subtle and it stops defeating the current one. The whole pipeline — detect face → apply grid → upload to Dreamina → submit Seedance generation — can run in a single script with no manual tuning per image. > This technique is documented for legitimate use with stylized characters, your own likeness, or licensed model imagery. It is **not** a license to violate Dreamina's terms of service around celebrity faces or non-consensual real-person content. Use accordingly. --- ## The prompt The only reference token differs between the two APIs: Runway uses `@IMG_1`, Dreamina uses `@image1`. > A cinematic continuous shot on a sunlit Midtown Manhattan avenue at golden hour. **@IMG_1** walks confidently toward camera, holding an unlit cigarette between two fingers of her right hand. She wears a black knee-length peacoat, white t-shirt and blue straight-leg jeans. Tall glass skyscrapers, yellow cabs, a white truck, pedestrians streaming past on both sides, pigeons take flight behind her, autumn leaves drift in the air. Direct eye contact with camera. > > She stops dead center in the frame, raises her right hand with the cigarette, and snaps her fingers with a deep thunderous boom sound — a shockwave sonic ripple explodes outward across the frame. > > The world instantly freezes. Every pedestrian completely still, locked mid-step with one foot in the air. Pigeons hang motionless in the sky, wings spread wide. Falling leaves suspended in mid-air. Cars stopped in the street. Absolute stillness everywhere. She is the only thing moving. She walks slowly between the frozen statue-still pedestrians, looks up at the unmoving pigeons in wonder, reaches up and gently touches one suspended in the air, then continues toward a bearded man in a dark coat and scarf who stands frozen with his foot mid-step. > > She stops directly in front of him. She flicks open a lighter, cups her hand around the flame, and lights her cigarette — the tip glows red as she inhales. She exhales a long slow plume of smoke into his still face, smirks, and says *"smoke, cool."* > > She raises her hand and snaps her fingers a second time with another deep thunderous boom sound. The world unfreezes: the bearded man jolts and looks around confused, the crowd, traffic and pigeons all resume motion. She walks casually past him like nothing happened, cigarette between her fingers, a slow plume of smoke trailing behind her. > > Camera cranes back and rises to a high-angle wide shot of the avenue — commuters streaming forward, traffic flowing, skyscraper canyon stretching into the distance. Image fades to black. > > Cinematic realism, golden-hour sun flare, shallow depth of field, film grain. Keep **@IMG_1** identity consistent throughout. --- ## Runway Seedance 2.0 • 15s 9:16 ```bash curl -X POST 'https://api.useapi.net/v1/runwayml/videos/create' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ --data '{ "model": "seedance-2", "text_prompt": "… @IMG_1 …", "aspect_ratio": "9:16", "resolution": "720p", "duration": 15, "audio": true, "exploreMode": true, "imageAssetId1": "user:12345-runwayml:account@example.com-asset:…" }' ``` See [POST /videos/create](/docs/api-runwayml-v1/post-runwayml-videos-create) for the full parameter reference. <video poster="https://media.useapi.net/articles/2024-08-11-runway-bash/runway-original-result-poster.jpg" src="https://media.useapi.net/articles/2024-08-11-runway-bash/runway-original-result.mp4" style="width: 100%; max-width: 400px;" controls type="video/mp4" preload="metadata"></video> **Typical timing in `exploreMode`:** ~10 min total (queue ~7–9 min, render ~1.5–4 min). Zero credit cost on the Runway Unlimited plan. --- ## Dreamina Seedance 2.0 • 15s 9:16 ```bash curl -X POST 'https://api.useapi.net/v1/dreamina/videos' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ --data '{ "model": "seedance-2.0", "prompt": "… @image1 …", "duration": 15, "ratio": "9:16", "account": "account@example.com", "omni_1_imageRef": "assetRef:…" }' ``` Notes: * **Omni Reference mode** is auto-triggered by presence of any `omni_N_*Ref` param. The `@image1` token in the prompt matches the `omni_1_imageRef` asset. * Pass `ratio` explicitly — `9:16` here to match Runway. See [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos) for the full parameter reference. <video poster="https://media.useapi.net/blog/2026-04-15-260415/seedance-grid-result-poster.jpg" src="https://media.useapi.net/blog/2026-04-15-260415/seedance-grid-result.mp4" style="width: 100%; max-width: 400px;" controls type="video/mp4" preload="metadata"></video> **Typical timing:** ~2 min (no queue). ~$0.044/sec = **~$0.66** for a 15-second clip. --- ## When to use which | | Runway Seedance 2.0 | Dreamina Seedance 2.0 | |---|---|---| | Real human faces | ✓ supported | ✗ moderated | | Cost (15s) | free on Unlimited (explore) | ~$0.66 | | Typical latency | ~10 min (explore queue) | ~2 min | | Max refs | 11 images + 3 videos | 9 images + 3 videos + 3 audio | | Audio reference | no | yes (`omni_N_audioRef`) | | Native audio generation | yes (`audio: true`) | yes | | Region | global | CA only | For **volume / real people / no-cost iteration** — use Runway with `exploreMode`. For **fast turnaround / audio-reference work / non-human characters** — use Dreamina. Compare every Seedance 2.0 and 2.5 route and price: [Seedance 2.0 and 2.5 API Pricing](/docs/articles/seedance-2-api-pricing). === URL: https://useapi.net/blog/260504 === Document URL: https://useapi.net/blog/260504 --- layout: blog_post title: "PixVerse: HappyHorse 1.0" description: "PixVerse API v2 now supports HappyHorse 1.0 — Alibaba's 1-ranked video model. Native 1080p, audio always on (cannot be disabled), free for Pro+ subscribers…" parent: Blog nav_exclude: true nav_order: -260504 --- ## HappyHorse 1.0 on PixVerse [PixVerse API v2](/docs/api-pixverse-v2) now supports [**HappyHorse 1.0**](https://fal.ai/happyhorse-1.0) — Alibaba's [#1-ranked](https://www.cnbc.com/2026/04/10/alibaba-happyhorse-ai-video-model-benchmark-reveal.html) video model. Native 1080p, **audio always on** (cannot be disabled), free for Pro+ subscribers until **May 7, 2026 07:00 UTC**. | Field | Value | |---|---| | `model` | `happyhorse-1.0` | | `quality` | `720p`, `1080p` | | `duration` | `3`–`15` seconds | | `aspect_ratio` (t2v) | `16:9`, `9:16`, `1:1`, `4:3`, `3:4` | | Modes | `t2v`, `i2v` (no fusion / no reference) | See [Model Capabilities](/docs/api-pixverse-v2/model-capabilities) and [POST /videos/create](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) for the full spec. ### [POST /videos/create](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) — image-to-video example <div style="margin-bottom:12px"> Starting frame<br> <img src="https://media.useapi.net/blog/2026-05-04-260504/frame-0-mirrored.jpg" style="max-width:300px"> </div> ```bash curl -X POST 'https://api.useapi.net/v2/pixverse/videos/create' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ --data '{ "email": "account@example.com", "model": "happyhorse-1.0", "prompt": "A 15-second cinematic shot. The cigarette in her left hand is UNLIT … she smirks and says clearly: \"You'\''re late.\"", "duration": 15, "quality": "1080p", "first_frame_path": "upload/<uuid>.jpeg" }' ``` <video poster="https://media.useapi.net/blog/2026-05-04-260504/happyhorse-result-v7-run2-poster.jpg" controls width="100%" style="max-width:400px"> <source src="https://media.useapi.net/blog/2026-05-04-260504/happyhorse-result-v7-run2.mp4" type="video/mp4"> </video> === URL: https://useapi.net/blog/260513 === Document URL: https://useapi.net/blog/260513 --- layout: blog_post title: "PixVerse: Motion Control" description: "PixVerse API v2 now supports Motion Control — drive a still character image with motion extracted from a reference video. Upload a portrait of who you want…" parent: Blog nav_exclude: true nav_order: -260513 --- ## Motion Control on PixVerse [PixVerse API v2](/docs/api-pixverse-v2) now supports **Motion Control** — drive a still character image with motion extracted from a reference video. Upload a portrait of who you want to animate, upload a short clip of the motion (dancing, gestures, gait), and PixVerse retargets the motion onto your character. | Field | Value | |---|---| | Endpoint | [POST /videos/motion-control](/docs/api-pixverse-v2/post-pixverse-videos-motion-control) | | `model` | `v5.6` *(only engine today)* | | `quality` | `360p`, `540p`, `720p` *(default)* | | `frame_1_path` | character image (person or animal) | | `video_1_path` | motion reference — 1–30 sec, ≤50 MB, ≤1920×1920 px | ### Example <div style="display:flex;gap:20px;flex-wrap:wrap;margin-bottom:16px;align-items:flex-start"> <div> Character image (<code>frame_1_path</code>)<br> <img src="https://media.useapi.net/blog/2026-04-15-260415/model-original.webp" style="max-width:240px"> </div> <div> Motion video (<code>video_1_path</code>)<br> <video poster="https://media.useapi.net/blog/2026-05-13-260513/videoref-1-poster.jpg" controls width="240" muted> <source src="https://media.useapi.net/blog/2026-05-13-260513/videoref-1.mp4" type="video/mp4"> </video> </div> </div> ```bash curl -X POST 'https://api.useapi.net/v2/pixverse/videos/motion-control' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ --data '{ "email": "account@example.com", "frame_1_path": "upload/<uuid>.webp", "video_1_path": "upload/<uuid>.mp4", "quality": "540p" }' ``` <div style="margin-top:12px"> Result<br> <video poster="https://media.useapi.net/articles/2024-06-08-pixverse-demo/pixverse-motioncontrol-v56-poster.jpg" controls width="100%" style="max-width:480px"> <source src="https://media.useapi.net/articles/2024-06-08-pixverse-demo/pixverse-motioncontrol-v56.mp4" type="video/mp4"> </video> </div> === URL: https://useapi.net/blog/260520 === Document URL: https://useapi.net/blog/260520 --- layout: blog_post title: "Google Flow: Gemini Omni Flash" description: "Google Flow API v1 now supports Gemini Omni Flash — Google's audio-native video model with text-to-video, reference-to-video, and a new video editing mode…" parent: Blog nav_exclude: true nav_order: -260520 --- ## Gemini Omni Flash on Google Flow API [Google Flow API v1](/docs/api-google-flow-v1) now supports [Gemini Omni Flash](https://deepmind.google/models/model-cards/gemini-omni-flash/) — Google's audio-native video model with text-to-video, reference-to-video, and a new **video editing** mode (transform an uploaded MP4 with a prompt). Omni 1.2 Flash (15-second videos, extend with voices, price per video): see [How to Use the Gemini Omni 1.2 Flash API](/docs/articles/gemini-omni-1-2-flash-api). | Field | Value | |---|---| | Endpoint | [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) | | `model` | `omni-flash` | | `referenceVideo_1` | uploaded MP4 *(via [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email))* | | `referenceImage_1..7` | image references | | `referenceAudio_1..5` | voice presets for spoken dialogue | | `aspectRatio` | `landscape`, `portrait` | ### Example Source MP4 → restyled cartoon, same motion and framing: <div style="margin-bottom:12px"> Source video (<code>referenceVideo_1</code>)<br> <video poster="https://media.useapi.net/blog/2026-05-20-260520/videoreference11sec-poster.jpg" controls width="100%" style="max-width:480px" muted> <source src="https://media.useapi.net/blog/2026-05-20-260520/videoreference11sec.mp4" type="video/mp4"> </video> </div> ```bash # 1. Upload MP4 curl -X POST 'https://api.useapi.net/v1/google-flow/assets/your@email.com' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: video/mp4' \ --data-binary @source.mp4 # 2. Submit edit curl -X POST 'https://api.useapi.net/v1/google-flow/videos' \ -H 'Authorization: Bearer user:12345-…' \ -H 'Content-Type: application/json' \ --data '{ "model": "omni-flash", "prompt": "Transform the scene into a vibrant animated cartoon style with bright neon colors", "referenceVideo_1": "user:…-email:…-video:…", "async": true }' # 3. Poll GET /jobs/{jobId} until status: "completed" ``` <div style="margin-top:12px"> Result<br> <video poster="https://media.useapi.net/blog/2026-05-20-260520/google-flow-edit-video-poster.jpg" controls width="100%" style="max-width:480px" muted> <source src="https://media.useapi.net/blog/2026-05-20-260520/google-flow-edit-video.mp4" type="video/mp4"> </video> </div> === URL: https://useapi.net/blog/260603 === Document URL: https://useapi.net/blog/260603 --- layout: blog_post title: "FlowMusic API v1: Powered by Lyria 3 Pro" description: "FlowMusic API v1 turns a text prompt into a complete, fully-produced song, powered by Google's Lyria 3 Pro (formerly Producer AI, originally Riffusion). The…" parent: Blog nav_exclude: true nav_order: -260603 --- ## Table of contents [FlowMusic API v1](/docs/api-flowmusic-v1) turns a text prompt into a complete, fully-produced song, powered by Google's [Lyria 3 Pro](https://deepmind.google/models/lyria/) (formerly Producer AI, originally Riffusion). The result is a finished track up to ~3 mins long (5+ with `extend`) — vocals with model-written or your own custom lyrics, or instrumental — that you can extend, cover, remix, and apply studio effects to, without regenerating from scratch. A song costs about $0.008–$0.013 on paid plans (see the [cost calculator](/docs/api-flowmusic-v1) for details), vs $0.08 per song on Google's [official Lyria 3 Pro API](https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing#lyria). Roughly 6–10× cheaper, and includes cover, remix, extend/replace, effects, and stem-splitting. Downloads (mp3, wav, m4a, and stems) are free. ### Generate a song from a prompt The model decides vocal vs. instrumental from your prompt — describe a voice and it sings (writing its own lyrics), or set `instrumental: true`. Euphoric Currents — instrumental liquid drum & bass <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-flowmusic-v1/post-flowmusic-music">POST /music</a> (instrumental)</summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:1234-…' \ --header 'Content-Type: application/json' \ --data '{ "prompt": "Liquid drum and bass, rolling breakbeats, deep rolling bassline, lush atmospheric pads, 174 bpm, euphoric", "instrumental": true }' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-06-03-260603/inst-06-dnb-a.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Solid Ground — pop ballad, soaring female vocal <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-flowmusic-v1/post-flowmusic-music">POST /music</a></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:1234-…' \ --header 'Content-Type: application/json' \ --data '{ "prompt": "Emotional pop ballad, soaring female vocal, grand piano and lush strings building to a powerful chorus, 70 bpm, heartfelt and cinematic" }' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-06-03-260603/01-vocal-pop-ballad-b.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> High Ground — stadium rock anthem, gritty male vocal <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-flowmusic-v1/post-flowmusic-music">POST /music</a></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:1234-…' \ --header 'Content-Type: application/json' \ --data '{ "prompt": "Stadium rock anthem, gritty male vocal, distorted guitars, pounding drums, huge gang-vocal chorus, 130 bpm, triumphant" }' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-06-03-260603/06-vocal-rock-anthem-b.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ### Edit a generated song Every clip you generate can be transformed — pass its `clip` id to [`POST /music/edit`](/docs/api-flowmusic-v1/post-flowmusic-music-edit). First we write lyrics, sing them into a power ballad, then reshape that exact track four ways. Write the lyrics — [`POST /music/lyrics`](/docs/api-flowmusic-v1/post-flowmusic-music-lyrics) turns a one-line idea into `[Verse]`/`[Chorus]` structure (and suggests a `sound_prompt`) <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-flowmusic-v1/post-flowmusic-music-lyrics">POST /music/lyrics</a></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music/lyrics' \ --header 'Authorization: Bearer user:1234-…' \ --header 'Content-Type: application/json' \ --data '{ "prompt": "An epic power ballad about the existential despair of running out of coffee on a Monday morning" }' ``` Returns structured lyrics (here titled *Zero Percent*) plus a suggested `sound_prompt`: ```json { "title": "Zero Percent", "lyrics": "[Verse 1]\nMonday hits like a hammer to the teeth\nI’m sinking fast beneath the kitchen floorboards\n…\n[Chorus]\nThe spark is dead and I’m losing my grip\nNot when the tank is running on empty", "sound_prompt": "Anthemic Pop-Punk, Alt-Rock, high-energy distorted guitars, raspy emotive male vocals, 165 BPM…", "source": "lyrics-create" } ``` </details> Running on Empty — sing those lyrics into a track ([`POST /music`](/docs/api-flowmusic-v1/post-flowmusic-music)) <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-flowmusic-v1/post-flowmusic-music">POST /music</a> (with your own lyrics)</summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:1234-…' \ --header 'Content-Type: application/json' \ --data '{ "prompt": "epic power ballad, soaring male vocal, big electric guitar solo, pounding drums, 75 bpm", "lyrics": "[Verse 1]\nMonday hits like a hammer to the teeth\nI’m sinking fast beneath the kitchen floorboards\nSearching for a reason to even exist\n…\n[Chorus]\nThe spark is dead and I’m losing my grip\nFalling through the floor of a sinking ship\nNot when the tank is running on empty" }' ``` We pass our own `prompt` here; the `sound_prompt` from the lyrics step works too. Omit `lyrics` to let `/music` write its own, or for an instrumental. </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-06-03-260603/song-lyrics-02-coffee-b.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Extended to 5 minutes — `extend` continues the track with a new, in-style section <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-flowmusic-v1/post-flowmusic-music-edit">POST /music/edit</a> (extend)</summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music/edit' \ --header 'Authorization: Bearer user:1234-…' \ --header 'Content-Type: application/json' \ --data '{ "operation": "extend", "clip": "user:1234-user@email.com-clip:…", "instruction": "add a triumphant building outro that lifts into one final chorus", "extend_s": 124 }' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-06-03-260603/extend-song-lyrics-02-coffee-b.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Acoustic cover — `cover` re-performs the song in a new style <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-flowmusic-v1/post-flowmusic-music-edit">POST /music/edit</a> (cover)</summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music/edit' \ --header 'Authorization: Bearer user:1234-…' \ --header 'Content-Type: application/json' \ --data '{ "operation": "cover", "clip": "user:1234-user@email.com-clip:…", "instruction": "reimagine as a warm acoustic unplugged cover", "strength": 0.7 }' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-06-03-260603/cover-song-lyrics-02-coffee-b.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Remixed with new lyrics — `remix` keeps the song's bones, swaps the words and style <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-flowmusic-v1/post-flowmusic-music-edit">POST /music/edit</a> (remix)</summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music/edit' \ --header 'Authorization: Bearer user:1234-…' \ --header 'Content-Type: application/json' \ --data '{ "operation": "remix", "clip": "user:1234-user@email.com-clip:…", "lyrics": "[Verse]\nSunrise hits the kitchen, beans are grinding fine\nThat first electric sip is hitting right on time\n[Chorus]\nI’m wired up, I’m golden, caffeine in my veins", "prompt": "upbeat bright indie pop, caffeinated and triumphant" }' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-06-03-260603/remix-song-lyrics-02-coffee-b.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Cathedral reverb — `effect` applies a studio effect (Reverb, Equalizer, Gain, Pan, Fade, Trim) <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-flowmusic-v1/post-flowmusic-music-edit">POST /music/edit</a> (effect)</summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music/edit' \ --header 'Authorization: Bearer user:1234-…' \ --header 'Content-Type: application/json' \ --data '{ "operation": "effect", "clip": "user:1234-user@email.com-clip:…", "effect": "Reverb", "mix": 0.5, "room_size": 0.85 }' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-06-03-260603/effect-song-lyrics-02-coffee-b.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> [`POST /music/edit`](/docs/api-flowmusic-v1/post-flowmusic-music-edit) also covers **replace** (regenerate a section) and **stems** (split into vocals/drums/bass/other) — see the [edit docs](/docs/api-flowmusic-v1/post-flowmusic-music-edit). ### Generate cover art Need album art to match the music? [`POST /files/generate`](/docs/api-flowmusic-v1/post-flowmusic-files-generate) turns a prompt into an image. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-flowmusic-v1/post-flowmusic-files-generate">POST /files/generate</a></summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/files/generate' \ --header 'Authorization: Bearer user:1234-…' \ --header 'Content-Type: application/json' \ --data '{ "prompt": "A grand piano half-submerged in a misty lake at dawn, surreal and painterly, soft atmospheric light, muted earthy palette, fine-art photograph" }' ``` </details> <a href="https://media.useapi.net/blog/2026-06-03-260603/img-piano-lake.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/blog/2026-06-03-260603/img-piano-lake.png" alt="A grand piano on a misty lake at dawn" style="max-width:512px;width:100%;border-radius:8px;"></a> ### Get started [FlowMusic API v1 docs](/docs/api-flowmusic-v1) · [Setup Flow Music](/docs/start-here/setup-flowmusic) === URL: https://useapi.net/blog/260605 === Document URL: https://useapi.net/blog/260605 --- layout: blog_post title: "Google Flow: Reusable Voices and Characters" description: "Google Flow API v1 now supports custom voices and reusable characters. Build a voice once, build a character once (1–2 reference images + that voice…" parent: Blog nav_exclude: true nav_order: -260605 --- ## Reusable Voices and Characters on Google Flow API [Google Flow API v1](/docs/api-google-flow-v1) now supports custom **voices** and reusable **characters**. Build a voice once, build a character once (1–2 reference images + that voice attached), then drop the character into any video or image generation — identity and voice stay consistent across runs. | New endpoint | What it does | |---|---| | [POST /voices](/docs/api-google-flow-v1/post-google-flow-voices) | Create a custom voice on top of one of the 30 system voice presets | | [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters) | Create a character — 1–2 reference images + an optional attached voice | | `character_1..7` on [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) | Use a character in a video generation | | `character_1..7` on [POST /images](/docs/api-google-flow-v1/post-google-flow-images) | Use a character in an image generation | Plus the supporting [GET /voices](/docs/api-google-flow-v1/get-google-flow-voices) / [GET /voices/`ref`](/docs/api-google-flow-v1/get-google-flow-voices-ref) / [DELETE /voices/`ref`](/docs/api-google-flow-v1/delete-google-flow-voices-ref) and the matching trio for characters. ## Showcase: build a swaggering pirate captain Below is the full pipeline. Every audio, image, and video clip was generated through the API. ### 1. Create the voice Pick one of the 30 system voice presets as the base, then add your own `dialog` and `voicePerformance` to shape the delivery. Here we use `Umbriel` (a deep, gravelly preset) and direct it toward a drunken pirate growl. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-voices">POST /voices</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/voices' \ --header 'Authorization: Bearer user:1234-…' \ --header 'Content-Type: application/json' \ --data '{ "email": "your@email.com", "voice": "Umbriel", "displayName": "Drunken Pirate Captain", "dialog": "Where be me rum?! Speak now, ye worthless bilge rat, or I'\''ll feed yer entrails to the sharks!", "voicePerformance": "Drunken pirate raging, deep booming voice with explosive growls, ragged breathing between threats." }' ``` </details> The response includes a `voice` reference-id and a freshly resolved `audioUrl` you can play back immediately: <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-06-05-260605/character-generated-voice.wav" type="audio/wav">Your browser does not support the audio element. </audio> ### 2. Pick the character reference images A character takes 1–2 reference images. Source them either from [POST /images](/docs/api-google-flow-v1/post-google-flow-images) (Imagen / Nano Banana) or upload your own via [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email) — either path returns a `mediaGenerationId` you can use. Here we use two angles — one head-and-shoulders, one tighter close-up — so the character extractor has more identity coverage and downstream gens drift less. <a href="https://media.useapi.net/blog/2026-06-05-260605/character-full.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/blog/2026-06-05-260605/character-full.jpg" alt="Pirate captain — head and shoulders reference" style="max-width:320px;width:100%;border-radius:8px;margin-right:8px;"></a> <a href="https://media.useapi.net/blog/2026-06-05-260605/character-close-up.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/blog/2026-06-05-260605/character-close-up.jpg" alt="Pirate captain — tight face close-up" style="max-width:320px;width:100%;border-radius:8px;"></a> ### 3. Create the character Bundle the two image `mediaGenerationId` values plus the voice reference-id into a named character with `personalityNotes`. The character ref is what you'll pass to every downstream gen. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-characters">POST /characters</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/characters' \ --header 'Authorization: Bearer user:1234-…' \ --header 'Content-Type: application/json' \ --data '{ "displayName": "The Pirate", "personalityNotes": "A swaggering, perpetually half-drunk pirate captain with a sharp wit hiding behind a slurred drawl. Charming when sober (rarely), menacing when crossed, theatrical at all times. Speaks in a deep gravelly bellow that drops to a conspiratorial growl when sharing secrets. Superstitious — kisses his gold tooth before any risky move, refuses to harm a parrot. Always has a half-empty bottle within arm'\''s reach.", "imageReference_1": "user:1234-email:…-image:7623b296-…", "imageReference_2": "user:1234-email:…-image:b7165c9e-…", "voice": "user:1234-email:…-voice:9f001ef8-…-mid:673330b9-…" }' ``` </details> The response is a portable `character` ref with `imgs:2` and `voice:…` in its tail — pass it straight to `character_1..7` on POST /videos or POST /images. ```json { "entityId": "60831b31-…", "character": "user:1234-email:…-character:60831b31-…-imgs:2-voice:9f001ef8-…", "displayName": "The Pirate", "imageReferences": [ { "mediaId": "user:1234-email:…-image:7623b296-…" }, { "mediaId": "user:1234-email:…-image:b7165c9e-…" } ], "voice": "user:1234-email:…-voice:9f001ef8-…-mid:673330b9-…" } ``` ### 4. Generate the video Use the character ref in `character_1`. The attached voice rides along automatically — no need to pass `referenceAudio_*` separately. Eight seconds, push-in from wide to close-up, the captain delivers his catchphrase on the close-up: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos">POST /videos</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos' \ --header 'Authorization: Bearer user:1234-…' \ --header 'Content-Type: application/json' \ --data '{ "model": "veo-3.1-fast", "aspectRatio": "landscape", "duration": 8, "character_1": "user:1234-email:…-character:60831b31-…-imgs:2-voice:9f001ef8-…", "prompt": "Eight-second continuous shot. Opens on a wide full-figure view of the pirate captain on the sunlit deck of his galleon, leaning casually on the wooden rail with one boot up on a coiled rope, rum bottle dangling from one hand. A colorful parrot is perched on the rail beside him. Brilliant blue sky and turquoise sea visible behind him, sun glinting off the water. The camera slowly pushes in over the first four seconds, smoothly ending tight on his face. The instant the close-up locks, he lifts the rum bottle toward the camera in a mock toast, tilts his head with a sly half-grin, and delivers the line lipsynced clearly: \"I'\''ll be sober when I'\''m dead, and not a minute sooner!\" Bright midday sun on his face when the close-up holds. Smooth single take, no cuts." }' ``` </details> <div style="margin-top:12px"> <video poster="https://media.useapi.net/blog/2026-06-05-260605/video-3-1-fast-result-poster.jpg" controls width="100%" style="max-width:640px;border-radius:8px" muted> <source src="https://media.useapi.net/blog/2026-06-05-260605/video-3-1-fast-result.mp4" type="video/mp4"> </video> </div> Also on YouTube: [Sober When Dead • Google Flow reusable voices and characters](https://www.youtube.com/watch?v=D1RM-tGZ6lw). The character face is consistent with the reference images, the Umbriel voice carries through with the drunken-pirate performance direction, and the push-in lands the punchline on the close-up exactly where the prompt asked. ## Why it matters Without characters, every video generation needs you to pass the same `referenceImage_*` set and re-explain the look in the prompt. Drift compounds across runs and the look slowly mutates. With a saved character: - One reference id replaces every image + voice you'd otherwise re-attach - The image-ref budget check happens server-side from the inline image count - Personality notes travel with the character so the model has consistent flavor across gens - Voices follow the same lifecycle — create once, reuse anywhere they'd otherwise need to be re-attached ## Get started [Google Flow API v1 docs](/docs/api-google-flow-v1) · [Setup Google Flow](/docs/start-here/setup-google-flow) · [POST /voices](/docs/api-google-flow-v1/post-google-flow-voices) · [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters) === URL: https://useapi.net/blog/260609 === Document URL: https://useapi.net/blog/260609 --- layout: blog_post title: "Google Flow: Inline @-mentions" description: "Google Flow API v1 now supports inline @-mention markers in the prompt on POST /videos and POST /images. Place your character / image / voice references…" parent: Blog nav_exclude: true nav_order: -260609 --- ## Table of contents ## Inline `@`-mentions on Google Flow API [Google Flow API v1](/docs/api-google-flow-v1) now supports **inline `@`-mention markers** in the `prompt` on [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) and [POST /images](/docs/api-google-flow-v1/post-google-flow-images). Place your character / image / voice references **inside** the prompt — `@character_1`, `@referenceImage_2`, `@referenceAudio_1` — and the API wires them to the corresponding body slot at exactly that position in the sentence. | Endpoint | Supported markers | |---|---| | [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) | `@character_1..7`, `@referenceImage_1..7`, `@referenceAudio_1..5` | | [POST /images](/docs/api-google-flow-v1/post-google-flow-images) | `@character_1..7`, `@reference_1..10` | Case-insensitive, opt-in (prompts without markers are unchanged), each marker must have its matching body slot supplied. Plain text prompts continue to work exactly like before. This post walks two demos end-to-end: 1. **`omni-flash` R2V** with three inline `@`-refs — a moonlit San Francisco noir clip. 2. **`omni-flash` V2V edit** that round-trips the noir clip back to the API as a source video, then composites two new characters into it via inline `@character_1` / `@character_2`. All assets, references, voices, characters, and the two generated videos below were produced through the public [Google Flow API v1](/docs/api-google-flow-v1). --- ## Demo 1: noir clip with three inline `@`-mentions The shot we want: a self-assured biker character sits on a vintage BMW motorcycle in an empty parking lot at night, Golden Gate Bridge in the far distance, San Francisco neo-noir atmosphere, slowly revs the engine, then delivers a single line in a deep raspy voice. ### Source images Three images uploaded via [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email) — each used in a different role below. <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:240px;margin:0"> <a href="https://media.useapi.net/blog/2026-06-09-260609/contextreference-4.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/blog/2026-06-09-260609/contextreference-4.jpg" alt="Smoker Biker character source" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em"><strong>Smoker Biker</strong> — character source (face reference passed to <a href="/docs/api-google-flow-v1/post-google-flow-characters"><code>POST /characters</code></a>)</figcaption> </figure> <figure style="flex:1 1 200px;max-width:240px;margin:0"> <a href="https://media.useapi.net/blog/2026-06-09-260609/contextreference-2.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/blog/2026-06-09-260609/contextreference-2.jpg" alt="Vintage BMW motorcycle reference" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em"><strong>Motorcycle</strong> — <code>referenceImage_1</code> (<code>@referenceImage_1</code> in the prompt)</figcaption> </figure> <figure style="flex:1 1 200px;max-width:240px;margin:0"> <a href="https://media.useapi.net/blog/2026-06-09-260609/contextreference-3.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/blog/2026-06-09-260609/contextreference-3.jpg" alt="Golden Gate Bridge reference" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em"><strong>Golden Gate Bridge</strong> — <code>referenceImage_2</code> (<code>@referenceImage_2</code> in the prompt)</figcaption> </figure> </div> ### Create the voice A custom voice for the biker — `Laomedeia` base preset with a smoke-roughened performance direction. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-voices">POST /voices</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/voices' \ --header 'Authorization: Bearer user:1234-…' \ --header 'Content-Type: application/json' \ --data '{ "email": "your@email.com", "voice": "Laomedeia", "displayName": "Smoker Lady", "dialog": "Honey, you have no idea what I'\''ve seen in this town.", "voicePerformance": "Deep raspy smoke-roughened, low gravelly pitch, slow drawl with audible exhales, world-weary" }' ``` </details> ### Create the character Bundle the character image and the custom voice into a single named character. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-characters">POST /characters</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/characters' \ --header 'Authorization: Bearer user:1234-…' \ --header 'Content-Type: application/json' \ --data '{ "displayName": "Smoker Biker", "imageReference_1": "user:1234-email:…-image:129960d4-…", "voice": "user:1234-email:…-voice:e25b42db-…-mid:fec00c57-…" }' ``` </details> ### Generate the noir clip Three inline markers do the work. Notice the prompt does **not** describe what `@referenceImage_1` or `@referenceImage_2` *are* — no "motorcycle", no "bridge", no "Golden Gate" mentioned in the text. Identity comes purely from the references; the model uses the inline position to anchor each one in the noun phrase. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos">POST /videos</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos' \ --header 'Authorization: Bearer user:1234-…' \ --header 'Content-Type: application/json' \ --data '{ "model": "omni-flash", "aspectRatio": "landscape", "duration": 8, "character_1": "user:1234-email:…-character:7bf2bc7f-…-imgs:1-voice:e25b42db-…", "referenceImage_1": "user:1234-email:…-image:6139e134-…", "referenceImage_2": "user:1234-email:…-image:bb5032e0-…", "prompt": "OPEN ON ambient neo-noir synthwave score already playing — low pulsing bass and distant saxophone. @character_1 sitting on @referenceImage_1 in an empty parking lot at night, hands on the controls. Clear sky, sharp moonlight, deep crisp shadows under tall amber street lamps, dry asphalt with faint road markings. @referenceImage_2 visible in the far distance. Iconic neo-noir atmosphere. Static locked-off camera, no zoom, no pan, no movement. @character_1 twists throttle once and revs @referenceImage_1 once — smoke briefly rises from @referenceImage_1 — then eases off, looks at the camera with a knowing half-smile and says slowly \"What a night for a ride.\"" }' ``` </details> The 8-second result: <div style="margin-top:12px"> <video poster="https://media.useapi.net/blog/2026-06-09-260609/noir-shot-1-poster.jpg" controls width="100%" style="max-width:640px;border-radius:8px"> <source src="https://media.useapi.net/blog/2026-06-09-260609/noir-shot-1.mp4" type="video/mp4"> </video> </div> Every `@`-mention grounded to its exact reference: the same specific BMW vintage motorcycle, the same Golden Gate Bridge in the distance, the same character identity from the source image — plus the smoke-roughened custom voice on the spoken line. Music kicks in from frame one. ## Demo 2: V2V edit — round-trip the noir clip and add two more characters For the next shot, we want to take the noir clip above and add **two more characters** flanking the biker — one on the left dancing, one on the right jumping with arms raised. This exercises `omni-flash`'s V2V edit path via `referenceVideo_1` combined with inline `@character_*` markers. ### Two more character sources Two more images uploaded via [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email), then turned into characters via [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters) (no voice attached this time). <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 240px;max-width:280px;margin:0"> <a href="https://media.useapi.net/blog/2026-06-09-260609/refcharacter1b.webp" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/blog/2026-06-09-260609/refcharacter1b.webp" alt="Left character source" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em"><strong>character_1</strong> — LEFT side (<code>@character_1</code> in the prompt — dances)</figcaption> </figure> <figure style="flex:1 1 240px;max-width:280px;margin:0"> <a href="https://media.useapi.net/blog/2026-06-09-260609/refcharacter2b.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/blog/2026-06-09-260609/refcharacter2b.jpg" alt="Right character source" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em"><strong>character_2</strong> — RIGHT side (<code>@character_2</code> in the prompt — jumps with arms raised)</figcaption> </figure> </div> ### Get a `referenceVideo_1` for the V2V edit Two ways to get one: - **Reuse the generated video's `mediaGenerationId` directly** from the Demo 1 response (`media[0].mediaGenerationId`) — no download or re-upload needed. - **Upload an MP4 from disk** via [POST /assets/`email`](/docs/api-google-flow-v1/post-google-flow-assets-email) with `Content-Type: video/mp4` — for video sources that aren't already in your Flow history. We'll use the first. #### V2V edit constraints — heads up V2V edit has tighter slot caps than R2V (5 image refs vs 7, 3 audio vs 5), accepts only `omni-flash`, and uses `endFrameIndex_1` instead of `duration` to size the output. Full constraints in [POST /videos → Model Capabilities](/docs/api-google-flow-v1/post-google-flow-videos#model-capabilities). One thing worth knowing from this demo: **Google's V2V moderation is non-deterministic.** The exact same body can land on a content-safety reject one attempt and a clean success the next. A simple resubmit usually clears it — no input changes needed. ### V2V edit with inline `@character_1` + `@character_2` `referenceVideo_1` switches the request into V2V edit mode. The inline `@character_*` markers place each new character at the specified position in the scene without ever describing what they look like in the text — identity, again, comes entirely from the references. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos">POST /videos</a> (V2V edit)</summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos' \ --header 'Authorization: Bearer user:1234-…' \ --header 'Content-Type: application/json' \ --data '{ "model": "omni-flash", "aspectRatio": "landscape", "character_1": "user:1234-email:…-character:5116516f-…-imgs:1", "character_2": "user:1234-email:…-character:1555335b-…-imgs:1", "referenceVideo_1": "user:1234-email:…-video:19ea81d0-…", "prompt": "@character_1 on the LEFT side of the frame busts some cool noir-style dance moves — slow confident shoulder rolls, smooth hip sway, runs a hand through her hair, fitting the moody parking-lot vibe. @character_2 on the RIGHT side of the frame jumps up and down enthusiastically with both arms raised, beaming smile. The center character stays where she is. Same noir parking lot at night, same Golden Gate behind, same moonlit atmosphere from the source video. Static locked-off camera, no zoom, no pan, no movement." }' ``` </details> The result: <div style="margin-top:12px"> <video poster="https://media.useapi.net/blog/2026-06-09-260609/edit-1-poster.jpg" controls width="100%" style="max-width:640px;border-radius:8px"> <source src="https://media.useapi.net/blog/2026-06-09-260609/edit-1.mp4" type="video/mp4"> </video> </div> Three distinct characters in one frame, each anchored to a specific reference: the original biker preserved in place from the source video, plus the two new flanking characters in their assigned positions and actions. Moon, bridge, parking lot, and amber street lamps all carried through unchanged from the source. ## Why inline `@`-mentions matter Without inline markers, a video gen with three references says "use these for context" but doesn't tell the model *where* each one belongs. The model has to guess from word order. With markers: - **Positional grounding.** The model knows `@character_1` goes in the noun phrase the marker sits in — not somewhere else. - **No descriptive cheating needed.** You don't have to describe what the reference *is* in the prompt (`"the chrome motorcycle"`, `"the Golden Gate Bridge"`) — identity comes from the reference. The prompt stays neutral and the model has to use the ref to render correctly. - **Multi-mention reuse.** Mention the same `@character_1` or `@referenceImage_1` multiple times across one prompt. The top-level reference array de-duplicates by id; only the positional information stacks. - **Same wire shape across endpoints.** Both `/videos` (R2V, V2V edit) and `/images` accept the same markers — pick the right slot name for the endpoint (`@reference_N` on /images, `@referenceImage_N` on /videos). ## Get started [Google Flow API v1 docs](/docs/api-google-flow-v1) · [Setup Google Flow](/docs/start-here/setup-google-flow) · [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) · [POST /images](/docs/api-google-flow-v1/post-google-flow-images) · [POST /characters](/docs/api-google-flow-v1/post-google-flow-characters) · [POST /voices](/docs/api-google-flow-v1/post-google-flow-voices) === URL: https://useapi.net/blog/260617 === Document URL: https://useapi.net/blog/260617 --- layout: blog_post title: "Kling 3.0 Turbo: faster video with dialogue and scene changes" description: "Kling v3 Turbo is now on the useapi.net Kling API — a faster v3.0 variant for text-to-video and image-to-video. Watch one portrait become a 10s 1080p noir clip with spoken dialogue and scene cuts." parent: Blog nav_exclude: true nav_order: -260617 --- ## Kling 3.0 Turbo on the API [Kling API v1](/docs/api-kling-v1) now supports **Kling v3 Turbo** (`kling-v3-0-turbo`) — a faster variant of Kling 3.0 that keeps v3.0 quality while cutting generation time. It's available on [POST /videos/text2video](/docs/api-kling-v1/post-kling-videos-text2video) and [POST /videos/image2video-frames](/docs/api-kling-v1/post-kling-videos-image2video-frames), with `std`/`pro` modes and 3–15s durations. Audio is always on, and Turbo leans into multi-shot output — so a single prompt can carry **spoken dialogue and scene changes** without any extra parameters. This post walks one image-to-video demo end to end: a single noir portrait becomes a 10-second 1080p clip with two spoken lines and three settings — all produced through the public [Kling API v1](/docs/api-kling-v1). --- ## The demo: one portrait → a 10s noir clip ### Source image A single 9:16 portrait, uploaded via [POST /assets](/docs/api-kling-v1/post-kling-assets) and passed as the start frame. The output aspect ratio is derived from the image (no `aspect_ratio` parameter on v3 image-to-video). <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:300px;margin:0"> <a href="https://media.useapi.net/blog/2026-06-17-260617/extraimage2.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/blog/2026-06-17-260617/extraimage2.jpg" alt="Noir woman in a red hat and coat — start frame" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em"><strong>Start frame</strong> — <code>image</code> (uploaded via <a href="/docs/api-kling-v1/post-kling-assets"><code>POST /assets</code></a>)</figcaption> </figure> </div> ### Generate the clip One call to [POST /videos/image2video-frames](/docs/api-kling-v1/post-kling-videos-image2video-frames). `model_name: kling-v3-0-turbo`, `mode: pro` (1080p), `duration: 10`. The prompt does all the directing — two spoken lines for the always-on audio, and an office → alley → rooftop progression that Turbo renders as scene cuts within the single clip. No `aspect_ratio`, no `enable_audio`, no multi-shot parameters. ```bash curl --location 'https://api.useapi.net/v1/kling/videos/image2video-frames' \ --header 'Authorization: Bearer user:12345-…' \ --form 'email="your@email.com"' \ --form 'model_name="kling-v3-0-turbo"' \ --form 'mode="pro"' \ --form 'duration="10"' \ --form 'image="https://s15-kling.klingai.com/…"' \ --form 'prompt="The woman in the red hat leans toward the camera in a dim, rain-streaked office and says in a low, confident voice: Everyone'\''s chasing the diamond — but only I know where it'\''s hidden. She turns and strides into a neon-soaked alley; the scene then cuts to a glittering rooftop overlooking the night skyline, where she glances back over her shoulder with a sly smile and adds: Catch me if you can. The camera sweeps up from the street to the city lights."' ``` Result <video poster="https://media.useapi.net/blog/2026-06-17-260617/kling-v3-turbo-poster.jpg" src="https://media.useapi.net/blog/2026-06-17-260617/kling-v3-turbo.mp4" style="width: 100%; max-width: 420px; aspect-ratio: 9/16;" controls type="video/mp4" preload="metadata"></video> From one still portrait: two spoken lines on an in-character voice, and a clean cut from the rain-streaked office to the neon alley to the rooftop skyline — all driven by the prompt alone, on the faster Turbo model. ## Turbo or standard 3.0? Turbo is the faster option and was a great fit for this image-to-video demo. When you need the full v3.0 feature set, use `kling-v3-0` (standard 3.0). Model capabilities change with each Kling release, so for the current, authoritative comparison check the live [Model Matrix](/model-matrix) and the [text2video](/docs/api-kling-v1/post-kling-videos-text2video) and [image2video-frames](/docs/api-kling-v1/post-kling-videos-image2video-frames) docs. ## Get started [Kling API v1 docs](/docs/api-kling-v1) · [Setup Kling](/docs/start-here/setup-kling) · [POST /videos/text2video](/docs/api-kling-v1/post-kling-videos-text2video) · [POST /videos/image2video-frames](/docs/api-kling-v1/post-kling-videos-image2video-frames) === URL: https://useapi.net/blog/260623 === Document URL: https://useapi.net/blog/260623 --- layout: blog_post title: "PixVerse: Grok Imagine 1.5 and Seedance 2.0 4K" description: "PixVerse API v2 adds Grok Imagine 1.5 image-to-video, Grok video extend, and Seedance 2.0 4K — example clips generated from a single source image." parent: Blog nav_exclude: true nav_order: -260623 --- ## Grok Imagine 1.5 and Seedance 2.0 4K on PixVerse June 23, 2026 The [PixVerse API v2](/docs/api-pixverse-v2) adds [xAI Grok Imagine 1.5](https://x.ai/grok) as an image-to-video model, brings Grok into [video extend](/docs/api-pixverse-v2/post-pixverse-videos-extend-v4), and unlocks 4K on Seedance 2.0. Every clip below started from this single source image. <img src="https://media.useapi.net/blog/2026-06-23-260623/two-friends.webp" alt="Source image — two friends in a vintage living room" width="200"> ### Grok Imagine 1.5 — image-to-video Grok Imagine 1.5 is image-to-video only — pass the first frame via `first_frame_path` on [POST /videos/create](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) with `model: grok-imagine-1.5`. It runs at `480p` / `720p`, `1`-`15s`, and merges native audio (the spoken line below is generated, not added). This one is `720p`, 5 seconds. <details markdown="block"> <summary><b>curl — POST /videos/create</b></summary> ```bash curl --location 'https://api.useapi.net/v2/pixverse/videos/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'email="account@example.com"' \ --form 'model="grok-imagine-1.5"' \ --form 'prompt="The red-haired woman on the left turns and slaps the brunette across the cheek, then snaps a cockney one-liner — ornate vintage living room"' \ --form 'quality="720p"' \ --form 'duration="5"' \ --form 'first_frame_path="upload/<uuid>.webp"' ``` </details> <video poster="https://media.useapi.net/blog/2026-06-23-260623/i2v-grok15-720p-5s-discord-poster.jpg" controls width="240" style="max-width:100%"> <source src="https://media.useapi.net/blog/2026-06-23-260623/i2v-grok15-720p-5s-discord.mp4" type="video/mp4"> </video> ### Extend the result with Grok [POST /videos/extend](/docs/api-pixverse-v2/post-pixverse-videos-extend-v4) now accepts `model: grok-imagine` (`480p` / `720p`, `2`-`10s`, native audio). Point it at the `video_id` from the clip above and it continues the scene — here the 5-second source grows to a 10-second exchange. <details markdown="block"> <summary><b>curl — POST /videos/extend</b></summary> ```bash curl --location 'https://api.useapi.net/v2/pixverse/videos/extend' \ --header 'Authorization: Bearer user:12345-…' \ --form 'email="account@example.com"' \ --form 'model="grok-imagine"' \ --form 'video_id="<video_id of the clip to extend>"' \ --form 'prompt="The other woman recovers, then slaps back — both glaring at each other"' \ --form 'quality="720p"' \ --form 'duration="5"' ``` </details> <video poster="https://media.useapi.net/blog/2026-06-23-260623/extend-grok-imagine-720p-10s-discord-poster.jpg" controls width="240" style="max-width:100%"> <source src="https://media.useapi.net/blog/2026-06-23-260623/extend-grok-imagine-720p-10s-discord.mp4" type="video/mp4"> </video> ### Seedance 2.0 — 4K `seedance-2.0` now generates 4K. Pass `quality: 2160p` on [POST /videos/create](/docs/api-pixverse-v2/post-pixverse-videos-create-v4) — the output is a true 2160×3840 video delivered as HEVC. The same prompt and source image, at 4K, 5 seconds. <details markdown="block"> <summary><b>curl — POST /videos/create</b></summary> ```bash curl --location 'https://api.useapi.net/v2/pixverse/videos/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'email="account@example.com"' \ --form 'model="seedance-2.0"' \ --form 'prompt="The red-haired woman on the left turns and slaps the brunette across the cheek — ornate vintage living room"' \ --form 'quality="2160p"' \ --form 'duration="5"' \ --form 'first_frame_path="upload/<uuid>.webp"' ``` </details> <video poster="https://media.useapi.net/blog/2026-06-23-260623/i2v-seedance2.0-2160p-5s-discord-poster.jpg" controls width="240" style="max-width:100%"> <source src="https://media.useapi.net/blog/2026-06-23-260623/i2v-seedance2.0-2160p-5s-discord.mp4" type="video/mp4"> </video> See [Model Capabilities](/docs/api-pixverse-v2/model-capabilities) for the full per-model quality, duration, and audio matrix. Compare every Seedance 2.0 and 2.5 route and price: [Seedance 2.0 and 2.5 API Pricing](/docs/articles/seedance-2-api-pricing). === URL: https://useapi.net/blog/260624 === Document URL: https://useapi.net/blog/260624 --- layout: blog_post title: "PixVerse: Music Generation with MiniMax, ElevenLabs and Lyria 3 Pro" description: "PixVerse API v2 adds music generation — songs and instrumentals from a text prompt across MiniMax music-2.6, ElevenLabs music-v1, and Google Lyria 3 Pro, with custom or model-written lyrics." parent: Blog nav_exclude: true nav_order: -260624 --- ## Music Generation on PixVerse with MiniMax, ElevenLabs and Lyria 3 Pro June 24, 2026 The [PixVerse API v2](/docs/api-pixverse-v2) now generates music. [POST /music/create](/docs/api-pixverse-v2/post-pixverse-music-create) turns a text prompt into a full track across three models — `music-2.6` ([MiniMax](https://www.minimax.io), default), `music-v1` ([ElevenLabs](https://elevenlabs.io)), and `lyria-3-pro-preview` ([Google Lyria 3 Pro](https://deepmind.google/technologies/lyria)) — then you poll [GET /music/`audio_id`](/docs/api-pixverse-v2/get-pixverse-music-music_id) for the `.mp3`, or pass a `replyUrl` callback. Set `instrumental: true` for no vocals, pass your own `lyrics` to have them sung, or send just a prompt and the model writes the lyrics. Each section below runs the same request on all three models so you can compare them. On a Premium plan ($60/month), a full track costs about $0.08 (`lyria-3-pro-preview`), $0.16 (`music-2.6`), or $0.60 (`music-v1`) — at the time of writing, and not accounting for any PixVerse promotions or special pricing. ### Instrumental Set `instrumental: true` for a track with no vocals. The same prompt on each model: <details markdown="block"> <summary><b>curl — POST /music/create</b></summary> ```bash curl --location 'https://api.useapi.net/v2/pixverse/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'email="account@example.com"' \ --form 'model="music-2.6"' \ --form 'instrumental="true"' \ --form 'prompt="A warm, melodic electronic instrumental with dreamy analog synths, a smooth rolling bassline and a catchy lead melody, relaxed and polished with a light steady groove"' ``` </details> `music-2.6` <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-06-24-260624/music-2.6-instrumental-melodic.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> `music-v1` <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-06-24-260624/music-v1-instrumental-melodic.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> `lyria-3-pro-preview` <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-06-24-260624/lyria-3-pro-preview-instrumental-melodic.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ### Vocals from your own lyrics Pass `lyrics` and the model sings them — the prompt sets the style, the lyrics set the words. Supported by `music-2.6` and `music-v1` (`lyria-3-pro-preview` writes its own lyrics, it does not take custom ones). <details markdown="block"> <summary><b>curl — POST /music/create</b></summary> ```bash curl --location 'https://api.useapi.net/v2/pixverse/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'email="account@example.com"' \ --form 'model="music-2.6"' \ --form 'prompt="An upbeat synthwave anthem with a clear, catchy female vocal, driving bassline and shimmering retro arps, around 120 BPM"' \ --form 'lyrics="[Verse 1] Two AM and the fridge light'\''s humming One last slice, I can hear it coming [Chorus] It'\''s the last slice, baby, it'\''s mine tonight Neon cheese under kitchen light"' ``` </details> `music-2.6` <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-06-24-260624/music-2.6-custom-lyrics.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> `music-v1` <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-06-24-260624/music-v1-custom-lyrics.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ### Vocals written by the model Send just a prompt — no `instrumental`, no `lyrics` — and the model writes the lyrics and sings them. <details markdown="block"> <summary><b>curl — POST /music/create</b></summary> ```bash curl --location 'https://api.useapi.net/v2/pixverse/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'email="account@example.com"' \ --form 'model="music-2.6"' \ --form 'prompt="An upbeat synthwave anthem with a clear, catchy female vocal, driving bassline and shimmering retro arps, around 120 BPM"' ``` </details> `music-2.6` <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-06-24-260624/music-2.6-auto-lyrics.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> `music-v1` <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-06-24-260624/music-v1-auto-lyrics.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> `lyria-3-pro-preview` <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-06-24-260624/lyria-3-pro-preview-auto-lyrics.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Looking for more from Lyria 3 Pro? [Flow Music](/docs/api-flowmusic-v1) runs the same model at a lower price with many more features — cover and restyle, lyrics-adjust remix, extend and replace, and audio effects. See [POST /music/create](/docs/api-pixverse-v2/post-pixverse-music-create) for the full model matrix, per-model prompt and lyrics limits, credits, and Lyria's reference-image support. === URL: https://useapi.net/blog/260625 === Document URL: https://useapi.net/blog/260625 --- layout: blog_post title: "PixVerse: Text-to-Speech with MiniMax and ElevenLabs" description: "PixVerse API v2 adds text-to-speech — five models across MiniMax Speech 2.8 and ElevenLabs (multilingual-v2, v3 audio tags, turbo-v2.5), with 300+ voices, emotions, inline audio tags, and 40+ languages." parent: Blog nav_exclude: true nav_order: -260625 --- ## Text-to-Speech on PixVerse with MiniMax and ElevenLabs June 25, 2026 The [PixVerse API v2](/docs/api-pixverse-v2) now turns text into speech. [POST /speech/create](/docs/api-pixverse-v2/post-pixverse-speech-create) generates spoken audio across five models from two providers — [MiniMax](https://www.minimax.io) `speech-2.8-hd` (default) and `speech-2.8-turbo`, and [ElevenLabs](https://elevenlabs.io) `eleven-multilingual-v2`, `eleven-v3`, and `eleven-turbo-v2.5` — then you poll [GET /speech/`audio_id`](/docs/api-pixverse-v2/get-pixverse-speech-speech_id) for the `.mp3`, or pass a `replyUrl` callback. A request is just a `model`, the `text`, and a `voice_id` from [GET /speech/voices](/docs/api-pixverse-v2/get-pixverse-speech-voices) (300+ MiniMax voices, ~20 ElevenLabs). MiniMax voices take an `emotion` setting, `eleven-v3` takes inline audio tags, and both cover 40+ languages. On a Premium plan ($60/month) speech runs $0.04–$0.08 per 1,000 characters. Each sample below has the exact `curl` that produced it. ### Audio tags — eleven-v3 `eleven-v3` is ElevenLabs' most expressive model. Instead of an `emotion` setting, you direct the delivery with inline tags like `[whispers]`, `[excited]`, and `[shouts]` placed right in the text — they work best on longer, sentence-level prompts. <details markdown="block"> <summary><b>curl — eleven-v3, a whisper that builds to a shout</b></summary> ```bash curl --location 'https://api.useapi.net/v2/pixverse/speech/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="eleven-v3"' \ --form 'voice_id="eleven_roger"' \ --form 'text="[whispers] The Force surrounds us. It binds the galaxy together. [curious] Do you feel it? [excited] Your destiny is calling... [shouts] may the Force be with you!"' ``` </details> <audio controls class="audio-player"><source src="https://media.useapi.net/blog/2026-06-25-260625/demo-v3-force-dramatic.mp3" type="audio/mp3">Your browser does not support the audio element.</audio> <details markdown="block"> <summary><b>curl — eleven-v3, a different emotional arc</b></summary> ```bash curl --location 'https://api.useapi.net/v2/pixverse/speech/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="eleven-v3"' \ --form 'voice_id="eleven_sarah"' \ --form 'text="[sighs] For a thousand generations, the Jedi kept the peace. [sad] And then, we lost everything. [whispers] But hope is not gone. [excited] May the Force be with you!"' ``` </details> <audio controls class="audio-player"><source src="https://media.useapi.net/blog/2026-06-25-260625/demo-v3-force-arc.mp3" type="audio/mp3">Your browser does not support the audio element.</audio> ### Voice variety — MiniMax Speech 2.8 The same line — "Use API dot net" — on the fast, lower-cost `speech-2.8-turbo`, then a male `speech-2.8-hd` voice. <details markdown="block"> <summary><b>curl — speech-2.8-turbo, female voice</b></summary> ```bash curl --location 'https://api.useapi.net/v2/pixverse/speech/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="speech-2.8-turbo"' \ --form 'voice_id="minimax_english_radiant_girl"' \ --form 'emotion="happy"' \ --form 'text="Use API dot net."' ``` </details> <audio controls class="audio-player"><source src="https://media.useapi.net/blog/2026-06-25-260625/demo-minimax-turbo-brand.mp3" type="audio/mp3">Your browser does not support the audio element.</audio> <details markdown="block"> <summary><b>curl — speech-2.8-hd, male voice</b></summary> ```bash curl --location 'https://api.useapi.net/v2/pixverse/speech/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="speech-2.8-hd"' \ --form 'voice_id="minimax_english_magnetic_voiced_man"' \ --form 'emotion="happy"' \ --form 'text="Use API dot net."' ``` </details> <audio controls class="audio-player"><source src="https://media.useapi.net/blog/2026-06-25-260625/demo-minimax-male-brand.mp3" type="audio/mp3">Your browser does not support the audio element.</audio> ### ElevenLabs Turbo `eleven-turbo-v2.5` is the fastest, lowest-cost ElevenLabs model, with a 40,000-character limit — here on a female voice reading "May the Force be with you". <details markdown="block"> <summary><b>curl — eleven-turbo-v2.5, female voice</b></summary> ```bash curl --location 'https://api.useapi.net/v2/pixverse/speech/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="eleven-turbo-v2.5"' \ --form 'voice_id="eleven_sarah"' \ --form 'text="May the Force be with you."' ``` </details> <audio controls class="audio-player"><source src="https://media.useapi.net/blog/2026-06-25-260625/demo-elevenlabs-turbo-female.mp3" type="audio/mp3">Your browser does not support the audio element.</audio> ### Emotion — MiniMax MiniMax voices take an `emotion` setting (`happy`, `sad`, `angry`, `calm`, and more) that colors the delivery. Here `emotion: happy` on the Expressive Narrator voice. <details markdown="block"> <summary><b>curl — speech-2.8-hd, emotion: happy</b></summary> ```bash curl --location 'https://api.useapi.net/v2/pixverse/speech/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="speech-2.8-hd"' \ --form 'voice_id="minimax_english_expressive_narrator"' \ --form 'emotion="happy"' \ --form 'text="I can'\''t believe it. After everything we'\''ve been through... this is finally the moment. May the Force be with you."' ``` </details> <audio controls class="audio-player"><source src="https://media.useapi.net/blog/2026-06-25-260625/demo-minimax-expressive-happy.mp3" type="audio/mp3">Your browser does not support the audio element.</audio> --- See the [POST /speech/create](/docs/api-pixverse-v2/post-pixverse-speech-create) reference for the full model matrix, per-voice settings, languages, and a live Try-It console — or browse the voices with [GET /speech/voices](/docs/api-pixverse-v2/get-pixverse-speech-voices). === URL: https://useapi.net/blog/260626 === Document URL: https://useapi.net/blog/260626 --- layout: blog_post title: "Dreamina: Seedance 2.0 Mini omni video from three image references" description: "Seedance 2.0 Mini is now on the useapi.net Dreamina API — the cheapest, fastest Seedance 2.0 with Omni Reference. Watch three reference images become a 15s 720p clip with a spoken line." parent: Blog nav_exclude: true nav_order: -260626 --- ## Seedance 2.0 Mini on the Dreamina API [Dreamina API v1](/docs/api-dreamina-v1) now supports Seedance 2.0 Mini (`seedance-2.0-mini`) — the cheapest, fastest member of the Seedance 2.0 family. It runs on [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos) at 720p, 4–15s, and supports the full Seedance 2.0 input set: text-to-video, first/last frame, and Omni Reference. Omni Reference is the interesting one. You upload several images, drop them straight into the prompt as `@image1`, `@image2`, …, and the model composes them into a single scene. A quoted line in the prompt becomes spoken dialogue in the clip, with audio generated automatically. This post walks one Omni demo end to end: three unrelated reference images become a 15-second 720p clip with motion and a spoken line, all through the public [Dreamina API v1](/docs/api-dreamina-v1). --- ## The demo: three references → one 15s clip ### Reference images Three images, each uploaded via [POST /assets](/docs/api-dreamina-v1/post-dreamina-assets-account) and referenced by placeholder in the prompt: <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 180px;max-width:240px;margin:0"> <a href="https://media.useapi.net/blog/2026-06-09-260609/contextreference-4.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/blog/2026-06-09-260609/contextreference-4.jpg" alt="Anime-character rider reference" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em"><code>@image1</code> — rider</figcaption> </figure> <figure style="flex:1 1 180px;max-width:240px;margin:0"> <a href="https://media.useapi.net/blog/2026-06-09-260609/contextreference-2.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/blog/2026-06-09-260609/contextreference-2.jpg" alt="Motorcycle reference" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em"><code>@image2</code> — motorcycle</figcaption> </figure> <figure style="flex:1 1 180px;max-width:240px;margin:0"> <a href="https://media.useapi.net/blog/2026-06-09-260609/contextreference-3.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/blog/2026-06-09-260609/contextreference-3.jpg" alt="Golden Gate Bridge reference" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em"><code>@image3</code> — bridge background</figcaption> </figure> </div> Omni does not require the references to share an aspect ratio, so the portrait, the landscape, and the background shot mix freely. ### Generate the clip One call to [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos). `model: seedance-2.0-mini`, `duration: 15`, `ratio: 16:9`, and three `omni_N_imageRef` assets matched to the `@imageN` placeholders. The prompt does the directing — a tracking shot, the riding action, and a line for the always-on audio. ```bash curl --location 'https://api.useapi.net/v1/dreamina/videos' \ --header 'Authorization: Bearer user:12345-…' \ --form 'account="CA:your@email.com"' \ --form 'model="seedance-2.0-mini"' \ --form 'duration="15"' \ --form 'ratio="16:9"' \ --form 'omni_1_imageRef="CA:your@email.com-image:…-uri:…"' \ --form 'omni_2_imageRef="CA:your@email.com-image:…-uri:…"' \ --form 'omni_3_imageRef="CA:your@email.com-image:…-uri:…"' \ --form 'prompt="Tracking shot following @image1 riding @image2 at high speed along the wet beach, front wheel slicing through the shallow surf and kicking up a spray of water, sand and sea-spray flying, cinematic motion blur, @image3 in the background. She grins and shouts excitedly: Woo-hoo! Fastest ride on the whole coast!"' ``` Result <video poster="https://media.useapi.net/blog/2026-06-26-260626/omni-beach-15s-poster.jpg" src="https://media.useapi.net/blog/2026-06-26-260626/omni-beach-15s.mp4" style="width: 100%; max-width: 720px; aspect-ratio: 16/9;" controls type="video/mp4" preload="metadata"></video> From three stills, the rider, the motorcycle, and the bridge land in one beach scene — with the motion and the spoken line driven by the prompt alone, on the most cost-effective Seedance 2.0 model. ## Mini, Fast, or full 2.0? Seedance 2.0 Mini is the cheapest and quickest option, and it is 720p-only. For 1080p or 4K output use `seedance-2.0` (full), which also gained a `4k` tier in this same update. `seedance-2.0-fast` sits in between. All three share Omni Reference, first/last frame, and text-to-video. For the current, authoritative capabilities check the live [Model Matrix](/model-matrix) and the [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos) docs. Compare every Seedance 2.0 and 2.5 route and price: [Seedance 2.0 and 2.5 API Pricing](/docs/articles/seedance-2-api-pricing). ## Get started [Dreamina API v1 docs](/docs/api-dreamina-v1) · [Setup Dreamina](/docs/start-here/setup-dreamina) · [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos) · [POST /assets](/docs/api-dreamina-v1/post-dreamina-assets-account) === URL: https://useapi.net/blog/260626a === Document URL: https://useapi.net/blog/260626a --- layout: blog_post title: "PixVerse Seedance 2.0: Mini vs Fast vs Standard — real faces with video + audio omni references" description: "PixVerse API v2 Seedance 2.0 omni mode drops a real face from a photo into a reference video and drives speech from a reference audio — compared across the Mini, Fast, and Standard tiers." parent: Blog nav_exclude: true nav_order: -260626 --- ## Seedance 2.0 omni on PixVerse: real faces, driven by a reference video and audio June 26, 2026 Seedance 2.0 keeps real human faces photoreal where many video models distort them, and PixVerse's omni (Reference) mode now combines an image, a video, and an audio clip in one request. [POST /videos/create-fusion](/docs/api-pixverse-v2/post-pixverse-videos-create-fusion) accepts up to 9 reference images, 3 reference videos (`@video1`…`@video3`), and 3 reference audios (`@audio1`…`@audio3`), each addressed by an `@`-tag in the prompt. Here we drop one person into another's footage: take a studio portrait (`@image1`), replace the woman in a soccer-pitch clip (`@video1`) with her, and make her speak from an audio clip (`@audio1`). The same request runs on all three Seedance 2.0 tiers — `seedance-2.0` (Standard), `seedance-2.0-fast`, and `seedance-2.0-mini` — so you can compare the face fidelity directly. Also on YouTube: [Seedance 2.0 Omni: Photo + Reference Video + Audio → One Clip (Mini vs Fast vs Standard)](https://youtube.com/shorts/apUc3lXrY_4). ### The three references A photo, a video, and an audio clip go in together: <img src="https://media.useapi.net/blog/2026-06-26-260626a/model-original-jpeg.jpg" style="max-height: 60vh;" /> `@image1` — the face and identity to drop in. <video poster="https://media.useapi.net/blog/2026-06-26-260626a/soccer-player-720p-5s-poster.jpg" src="https://media.useapi.net/blog/2026-06-26-260626a/soccer-player-720p-5s.mp4" style="height: 60vh; width: 100%;" controls type="video/mp4" preload="metadata">Your browser does not support the video element.</video> `@video1` — the scene, pose, ball, and motion to keep. <audio controls class="audio-player"><source src="https://media.useapi.net/blog/2026-06-26-260626a/hey-there-want-to-play-2s.mp3" type="audio/mp3">Your browser does not support the audio element.</audio> `@audio1` — the speech to drive (about 2 seconds). ### The prompt > Replace the woman in @video1 with @image1, keeping the exact same scene, soccer ball and movements, and make her say @audio1 First upload each file with [POST /files](/docs/api-pixverse-v2/post-pixverse-files) to get its `upload/…` path, then pass those paths as `frame_1_path`, `video_1_path`, and `audio_1_path`. Only the `model` and `quality` change between the three runs below. ### seedance-2.0 (Standard) — 1080p Standard is the top tier, with 1080p and 4K (`2160p`). Same omni request at the highest resolution. <details markdown="block"> <summary><b>curl — seedance-2.0 (Standard), 1080p, omni image + video + audio</b></summary> ```bash curl --location 'https://api.useapi.net/v2/pixverse/videos/create-fusion' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="seedance-2.0"' \ --form 'prompt="Replace the woman in @video1 with @image1, keeping the exact same scene, soccer ball and movements, and make her say @audio1"' \ --form 'frame_1_path="upload/your-image.jpg"' \ --form 'video_1_path="upload/your-video.mp4"' \ --form 'audio_1_path="upload/your-audio.mp3"' \ --form 'quality="1080p"' \ --form 'duration="4"' \ --form 'aspect_ratio="9:16"' ``` </details> <video poster="https://media.useapi.net/blog/2026-06-26-260626a/omni-standard-1080p-4s-9x16-swap-poster.jpg" src="https://media.useapi.net/blog/2026-06-26-260626a/omni-standard-1080p-4s-9x16-swap.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata">Your browser does not support the video element.</video> ### seedance-2.0-fast — 720p <details markdown="block"> <summary><b>curl — seedance-2.0-fast, 720p, omni image + video + audio</b></summary> ```bash curl --location 'https://api.useapi.net/v2/pixverse/videos/create-fusion' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="seedance-2.0-fast"' \ --form 'prompt="Replace the woman in @video1 with @image1, keeping the exact same scene, soccer ball and movements, and make her say @audio1"' \ --form 'frame_1_path="upload/your-image.jpg"' \ --form 'video_1_path="upload/your-video.mp4"' \ --form 'audio_1_path="upload/your-audio.mp3"' \ --form 'quality="720p"' \ --form 'duration="4"' \ --form 'aspect_ratio="9:16"' ``` </details> <video poster="https://media.useapi.net/blog/2026-06-26-260626a/omni-fast-720p-4s-9x16-swap-poster.jpg" src="https://media.useapi.net/blog/2026-06-26-260626a/omni-fast-720p-4s-9x16-swap.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata">Your browser does not support the video element.</video> ### seedance-2.0-mini — 720p <details markdown="block"> <summary><b>curl — seedance-2.0-mini, 720p, omni image + video + audio</b></summary> ```bash curl --location 'https://api.useapi.net/v2/pixverse/videos/create-fusion' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="seedance-2.0-mini"' \ --form 'prompt="Replace the woman in @video1 with @image1, keeping the exact same scene, soccer ball and movements, and make her say @audio1"' \ --form 'frame_1_path="upload/your-image.jpg"' \ --form 'video_1_path="upload/your-video.mp4"' \ --form 'audio_1_path="upload/your-audio.mp3"' \ --form 'quality="720p"' \ --form 'duration="4"' \ --form 'aspect_ratio="9:16"' ``` </details> <video poster="https://media.useapi.net/blog/2026-06-26-260626a/omni-mini-720p-4s-9x16-swap-poster.jpg" src="https://media.useapi.net/blog/2026-06-26-260626a/omni-mini-720p-4s-9x16-swap.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata">Your browser does not support the video element.</video> ### What it costs Omni runs on the same credit model as the rest of PixVerse video — `base × quality × seconds`. On a Premium plan ($60/month → 15,000 credits at $0.004 each) this 4-second 9:16 clip costs: | Model | Quality | Credits | Cost (Premium) | |:------|:--------|:--------|:---------------| | `seedance-2.0` | 1080p | 240 | ~$0.96 | | `seedance-2.0-fast` | 720p | 80 | ~$0.32 | | `seedance-2.0-mini` | 720p | 56 | ~$0.22 | Mini delivers the same omni capability — real faces, plus video and audio references — at roughly a quarter of the Standard-1080p credit cost, which makes it the natural default for iterating. Move up to Standard when you need 1080p or 4K. See the [interactive cost calculator](/docs/api-pixverse-v2) and [Model Capabilities](/docs/api-pixverse-v2/model-capabilities) for the full per-model breakdown. --- See the [POST /videos/create-fusion](/docs/api-pixverse-v2/post-pixverse-videos-create-fusion) reference for every `@image` / `@video` / `@audio` tag, the reference-media limits, and a live Try-It console. Compare every Seedance 2.0 and 2.5 route and price: [Seedance 2.0 and 2.5 API Pricing](/docs/articles/seedance-2-api-pricing). === URL: https://useapi.net/blog/260626b === Document URL: https://useapi.net/blog/260626b --- layout: blog_post title: "MiniMax (Hailuo) Seedance 2.0: Standard vs Fast vs Mini — real faces with video + audio omni references" description: "MiniMax (Hailuo) API Seedance 2.0 omni mode drops a real face from a photo into a reference video and drives speech from a reference audio — compared across the Standard, Fast, and Mini tiers." parent: Blog nav_exclude: true nav_order: -260626 --- ## Seedance 2.0 omni on MiniMax: real faces, driven by a reference video and audio June 26, 2026 Seedance 2.0 keeps a real human face photoreal where many video models distort it, and MiniMax's omni references now combine an image, a video, and an audio clip in one request. [POST videos/create](/docs/api-minimax-v1/post-minimax-videos-create) accepts up to 9 reference images (`@Image1`…`@Image9`), 3 reference videos (`@Video1`…`@Video3`), and 3 reference audios (`@Audio1`…`@Audio3`), each addressed by an `@`-tag in the prompt. Here we drop one person into another's footage: take a studio portrait (`@image1`), replace the woman in a rope-skipping clip (`@video1`) with her, and make her speak from an audio clip (`@audio1`). The same request runs on all three Seedance 2.0 tiers — `Seedance-2.0` (Standard), `Seedance-2.0-Fast`, and `Seedance-2.0-Mini` — so you can compare the result directly. ### The three references A photo, a video, and an audio clip go in together: <img src="https://media.useapi.net/blog/2026-06-26-260626b/pretty-lady-in-the-bar-1080p.jpg" style="max-height: 60vh;" /> `@image1` — the face and identity to drop in. A real face in an image reference is fine. <video poster="https://media.useapi.net/blog/2026-06-26-260626b/lady-jumping-rope-1080p-10s-blurred-poster.jpg" src="https://media.useapi.net/blog/2026-06-26-260626b/lady-jumping-rope-1080p-10s-blurred.mp4" style="height: 60vh; width: 100%;" controls type="video/mp4" preload="metadata">Your browser does not support the video element.</video> `@video1` — the scene, rope, and motion to keep. Its face is blurred on purpose: Hailuo's Seedance declines a video reference that shows a clear real face (the job comes back `moderated`, "Face Detected"), and the identity you keep comes from `@image1` anyway. A quick blur over the face in the reference clip is all it takes. <audio controls class="audio-player"><source src="https://media.useapi.net/blog/2026-06-26-260626b/count-me-jumping-jsessica-eleven-v3-2s.mp3" type="audio/mp3">Your browser does not support the audio element.</audio> `@audio1` — the speech to drive (about 2 seconds). ### The prompt > Replace the woman in @video1 with @image1, keeping the same outdoor scene, rope, and jumping movements. She speaks out loud, clearly saying Count me jumping in the voice from @audio1, audible throughout the clip. First upload each file with [POST /files](/docs/api-minimax-v1/post-minimax-files) to get its `fileID`, then pass those IDs as `fileID`, `videoFileID1`, and `audioFileID1`. Only the `model` and `resolution` change between the three runs below. One tip for omni audio: spell out the spoken line and state that it is heard. MiniMax renders the `@audio1` voice when the prompt says something like *clearly saying … audible throughout* — a bare *make her say @audio1* tends to return a silent track even though the request is accepted. ### Seedance-2.0 (Standard) — 1080p Standard is the only tier with 1080p and 4K. Same omni request, highest resolution. <details markdown="block"> <summary><b>curl — Seedance-2.0 (Standard), 1080p, omni image + video + audio</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/videos/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="Seedance-2.0"' \ --form 'prompt="Replace the woman in @video1 with @image1, keeping the same outdoor scene, rope, and jumping movements. She speaks out loud, clearly saying Count me jumping in the voice from @audio1, audible throughout the clip."' \ --form 'fileID="user:12345-minimax:1234567890-file:your-image"' \ --form 'videoFileID1="user:12345-minimax:1234567890-file:your-video"' \ --form 'audioFileID1="user:12345-minimax:1234567890-file:your-audio"' \ --form 'resolution="1080"' \ --form 'duration="5"' \ --form 'aspectRatio="9:16"' ``` </details> <video poster="https://media.useapi.net/blog/2026-06-26-260626b/std-1080-5s-nowm-poster.jpg" src="https://media.useapi.net/blog/2026-06-26-260626b/std-1080-5s-nowm.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata">Your browser does not support the video element.</video> ### Seedance-2.0-Fast — 720p <details markdown="block"> <summary><b>curl — Seedance-2.0-Fast, 720p, omni image + video + audio</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/videos/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="Seedance-2.0-Fast"' \ --form 'prompt="Replace the woman in @video1 with @image1, keeping the same outdoor scene, rope, and jumping movements. She speaks out loud, clearly saying Count me jumping in the voice from @audio1, audible throughout the clip."' \ --form 'fileID="user:12345-minimax:1234567890-file:your-image"' \ --form 'videoFileID1="user:12345-minimax:1234567890-file:your-video"' \ --form 'audioFileID1="user:12345-minimax:1234567890-file:your-audio"' \ --form 'resolution="720"' \ --form 'duration="5"' \ --form 'aspectRatio="9:16"' ``` </details> <video poster="https://media.useapi.net/blog/2026-06-26-260626b/fast-720-5s-nowm-poster.jpg" src="https://media.useapi.net/blog/2026-06-26-260626b/fast-720-5s-nowm.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata">Your browser does not support the video element.</video> ### Seedance-2.0-Mini — 720p The cheapest tier, same omni capability — a real face from the photo, plus video and audio references. <details markdown="block"> <summary><b>curl — Seedance-2.0-Mini, 720p, omni image + video + audio</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/videos/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="Seedance-2.0-Mini"' \ --form 'prompt="Replace the woman in @video1 with @image1, keeping the same outdoor scene, rope, and jumping movements. She speaks out loud, clearly saying Count me jumping in the voice from @audio1, audible throughout the clip."' \ --form 'fileID="user:12345-minimax:1234567890-file:your-image"' \ --form 'videoFileID1="user:12345-minimax:1234567890-file:your-video"' \ --form 'audioFileID1="user:12345-minimax:1234567890-file:your-audio"' \ --form 'resolution="720"' \ --form 'duration="5"' \ --form 'aspectRatio="9:16"' ``` </details> <video poster="https://media.useapi.net/blog/2026-06-26-260626b/mini-720-5s-nowm-poster.jpg" src="https://media.useapi.net/blog/2026-06-26-260626b/mini-720-5s-nowm.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata">Your browser does not support the video element.</video> ### What it costs Seedance models are billed per second — multiply the rate by your `duration`. For this 5-second omni clip: | Model | Resolution | Credits/sec | Credits (5s) | |:------|:-----------|:----------:|:------------:| | `Seedance-2.0` (Standard) | 1080p | 50 | 250 | | `Seedance-2.0-Fast` | 720p | 17 | 85 | | `Seedance-2.0-Mini` | 720p | 11 | 55 | Mini is the natural default for iterating — the same omni capability at the lowest cost. Move up to Standard when you need 1080p or 4K. See the [POST videos/create](/docs/api-minimax-v1/post-minimax-videos-create) credits estimator for the full per-resolution breakdown. --- See the [POST videos/create](/docs/api-minimax-v1/post-minimax-videos-create) reference for every `@Image` / `@Video` / `@Audio` tag, the reference-media limits, and a live Try-It console. Compare every Seedance 2.0 and 2.5 route and price: [Seedance 2.0 and 2.5 API Pricing](/docs/articles/seedance-2-api-pricing). === URL: https://useapi.net/blog/260629 === Document URL: https://useapi.net/blog/260629 --- layout: blog_post title: "MiniMax: Midjourney V7 Image Generation" description: "Generate Midjourney V7 images through the useapi.net MiniMax API using prose prompts and image references — no Midjourney -- flags — with copy-paste curl examples and Pro/Master per-generation pricing." parent: Blog nav_exclude: true nav_order: -260629 --- **You can generate [Midjourney V7](https://www.midjourney.com/) images straight from a REST call** through the [MiniMax API v1](/docs/api-minimax-v1) on useapi.net — no Discord bot, no `/imagine`, just [POST images/create](/docs/api-minimax-v1/post-minimax-images-create) with `model="midjourney-v7"`. Generation runs through MiniMax (Hailuo) rather than Midjourney's own Discord, so there are no Midjourney subscription or Discord account bans to worry about. ### How it works * Send your prompt to [POST images/create](/docs/api-minimax-v1/post-minimax-images-create) with `model="midjourney-v7"`. * Pick the frame with the `aspectRatio` parameter — `auto` (default), `21:9`, `16:9`, `5:4`, `4:3`, `3:2`, `1:1`, `2:3`, `3:4`, `4:5`, or `9:16`. * Optionally guide the look with up to 14 image references. Upload each one with [POST /files](/docs/api-minimax-v1/post-minimax-files), then pass the returned `fileID` as `referenceFileId1`…`referenceFileId14`. * Every request returns exactly 4 images (the `quantity` parameter is ignored for this model), so each call gives you a full Midjourney-style grid to choose from. * The call responds with an `imageIds` array. Poll [GET images/`imageId`](/docs/api-minimax-v1/get-minimax-images-imageId) until `status` is `2` (completed) and read `downloadURL` for the clean, non-watermarked image (paid accounts) or `videoURL` for the watermarked fallback. ### No `--` flags — prose and image references only MiniMax's Midjourney V7 does **not** understand native Midjourney flags. Tokens such as `--ar`, `--s`, `--style`, `--sref`, `--no`, and `::` weights are not parsed — leaving them in your prompt just feeds literal text to the model. Everything is plain natural-language prose, and the two levers you have are the prompt itself and image references. Anything a flag used to control goes through an API parameter instead — aspect ratio via `aspectRatio`, reference imagery via `referenceFileId1`…`14`. ### Pricing — single generation on Pro and Master Midjourney V7 costs 3 credits per image, and every request always produces 4 images, so one generation is 12 credits. | Plan | Monthly | $/credit | Per generation (4 images, 12 cr) | |:-----|:-------:|:--------:|:--------------------------------:| | [Pro](https://hailuoai.video/subscribe/modal) | $34.99 | $0.00778 | ~$0.093 | | [Master](https://hailuoai.video/subscribe/modal) | $79.99 | $0.00762 | ~$0.091 | Master has the lowest cost per credit of any plan. See the [Credits estimator](/docs/api-minimax-v1/post-minimax-images-create) for every model and the [MiniMax API overview](/docs/api-minimax-v1) for the full plan and per-model breakdown. --- ### Example 1: Cinematic street — 21:9 <img src="https://media.useapi.net/blog/2026-06-29-260629/t1-cinematic-keep.png" style="width: 100%;" /> <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/images/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="midjourney-v7"' \ --form 'prompt="A lone figure in a long charcoal trench coat stands at a rain-soaked city intersection at 3 a.m., sodium streetlights throwing pools of amber across wet asphalt, neon signs bleeding reflections into the puddles, thin fog drifting through the frame. Anamorphic widescreen, teal shadows and warm amber highlights, shot on Arri Alexa with a vintage anamorphic lens, shallow depth of field, photoreal cinematic color grade."' \ --form 'aspectRatio="21:9"' ``` </details> --- ### Example 2: Epic fantasy dragon — 16:9 <img src="https://media.useapi.net/blog/2026-06-29-260629/epic-dragon-2.png" style="width: 100%; max-width: 720px;" /> <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/images/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="midjourney-v7"' \ --form 'prompt="A titanic ancient dragon with iridescent storm-grey scales and wings spanning the sky descends through roiling thunderclouds toward a besieged cliffside citadel, lightning forking around its horns, firelight glowing through the rain, knights and banners tiny on the battlements below, immense scale and dread, epic fantasy concept art in the style of Frank Frazetta and Weta Workshop, hyper-detailed, cinematic, photoreal."' \ --form 'aspectRatio="16:9"' ``` </details> --- ### Example 3: Erupting volcano — 21:9 <img src="https://media.useapi.net/blog/2026-06-29-260629/epic-volcano-3.png" style="width: 100%;" /> <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/images/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="midjourney-v7"' \ --form 'prompt="An epic nocturnal vista of an erupting volcano, rivers of molten lava carving glowing veins down black mountainsides into a steaming ocean, a towering ash plume lit from within, aurora and a field of stars overhead, a lone eagle silhouetted against the firelight, monumental raw power, National Geographic photography shot on Phase One medium format, ultra-detailed, cinematic, 8K."' \ --form 'aspectRatio="21:9"' ``` </details> --- ### Example 4: Image reference — warrior queen — 2:3 Upload a reference photo, then transform the person while keeping their face and features. Reference (`referenceFileId1`): <img src="https://media.useapi.net/blog/2026-06-29-260629/lady-dressed-up-staris.jpg" style="width: 100%; max-width: 360px;" /> Result: <img src="https://media.useapi.net/blog/2026-06-29-260629/epic-imgref-1.png" style="width: 100%; max-width: 400px;" /> <details markdown="block"> <summary><b>Show the API calls</b></summary> Step 1 — upload the reference image with [POST /files](/docs/api-minimax-v1/post-minimax-files). The response returns a `fileID`: ```bash curl --location 'https://api.useapi.net/v1/minimax/files/' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: image/jpeg' \ --data-binary '@lady-dressed-up-staris.jpg' ``` Step 2 — generate, passing the returned `fileID` as `referenceFileId1`: ```bash curl --location 'https://api.useapi.net/v1/minimax/images/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="midjourney-v7"' \ --form 'prompt="Transform this woman into an epic warrior queen — keep her exact face and features — clad in ornate silver-and-gold filigree armor and a flowing crimson cloak, standing atop a windswept cliff above a vast army and a burning ancient city at dusk, storm clouds and embers swirling, dramatic god-rays breaking through, monumental cinematic scale, hyper-detailed, photoreal, epic blockbuster film-poster style."' \ --form 'aspectRatio="2:3"' \ --form 'referenceFileId1="user:…-minimax:…-file:…"' ``` </details> --- ### Example 5: Image reference — film-noir femme fatale — 4:5 Same uploaded reference as Example 4 — one `fileID`, many looks. <img src="https://media.useapi.net/blog/2026-06-29-260629/ir-noir-2.png" style="width: 100%; max-width: 420px;" /> <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/images/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="midjourney-v7"' \ --form 'prompt="Transform this exact woman into the femme fatale of a 1940s film-noir — keep her exact face and likeness unchanged. Black-and-white cinematic still, dramatic venetian-blind shadows striping her face, glamorous satin gown and elbow gloves, curling cigarette smoke, smoky jazz-club backdrop, hard chiaroscuro key light, deep contrast, classic Hollywood glamour, 35mm grain."' \ --form 'aspectRatio="4:5"' \ --form 'referenceFileId1="user:…-minimax:…-file:…"' ``` </details> --- ### Example 6: Food hero — omakase sushi — 3:2 <img src="https://media.useapi.net/blog/2026-06-29-260629/food-sushi-3.png" style="width: 100%;" /> <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/images/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="midjourney-v7"' \ --form 'prompt="Elegant minimalist food photograph of a premium omakase sushi platter — glistening nigiri of salmon, tuna and uni, perfectly pressed rice, a brush of glaze, garnished with microgreens and edible gold leaf, on a black slate stone, soft directional light, refined negative space, ultra-sharp, fine-dining advertising, macro detail."' \ --form 'aspectRatio="3:2"' ``` </details> --- ### Example 7: Food hero — gourmet cheeseburger — 4:5 <img src="https://media.useapi.net/blog/2026-06-29-260629/food-burger-3.png" style="width: 100%; max-width: 420px;" /> <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/images/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="midjourney-v7"' \ --form 'prompt="Epic commercial food photograph of the ultimate gourmet cheeseburger — toasted brioche sesame bun, thick flame-grilled patty, molten cheddar dripping down the sides, crisp lettuce, ripe tomato, caramelized onions, on a dark slate board, dramatic rim-lit studio lighting, rising steam, shallow depth of field, glistening textures, hyper-detailed advertising hero shot, 50mm macro."' \ --form 'aspectRatio="4:5"' ``` </details> --- ### Example 8: Food hero — molten chocolate lava cake — 4:5 <img src="https://media.useapi.net/blog/2026-06-29-260629/food-dessert-1.png" style="width: 100%; max-width: 420px;" /> <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/images/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="midjourney-v7"' \ --form 'prompt="Decadent fine-dining food photograph of a molten chocolate lava cake — dark chocolate oozing from the center onto a white plate, a dusting of powdered sugar, fresh raspberries, a quenelle of vanilla ice cream, mint, glossy chocolate-sauce art, dramatic restaurant lighting, rich and indulgent, hyper-detailed macro, Michelin plating."' \ --form 'aspectRatio="4:5"' ``` </details> --- ### Example 9: Food hero — weekend brunch flat-lay — 1:1 <img src="https://media.useapi.net/blog/2026-06-29-260629/food-breakfast-3.png" style="width: 100%; max-width: 480px;" /> <details markdown="block"> <summary><b>Show the API call</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/images/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="midjourney-v7"' \ --form 'prompt="Bright top-down flat-lay of the perfect weekend brunch — a stack of fluffy pancakes with dripping maple syrup and melting butter, fresh berries, crispy bacon, golden croissants, a latte with leaf art, fresh orange juice, on a marble table, scattered crumbs, airy natural morning light, vibrant, hyper-detailed, food-blogger aesthetic."' \ --form 'aspectRatio="1:1"' ``` </details> --- Prefer the anime look? Swap `model="midjourney-v7"` for `model="midjourney-niji7"` — same flag-free prose, same 4-image grid, same pricing. See [POST images/create](/docs/api-minimax-v1/post-minimax-images-create) for the full parameter reference, and [Setup MiniMax](/docs/start-here/setup-minimax) to connect an account. === URL: https://useapi.net/blog/260730 === Document URL: https://useapi.net/blog/260730 --- layout: blog_post title: "MiniMax H3 vs Seedance 2.0: 2K with native audio, head to head on the same omni references" description: "MiniMax Hailuo 3.0 on the useapi.net API generates 2K video at 24 fps with native stereo audio on every clip, shown three ways — and run head to head against Seedance 2.0 on the identical image, video, and audio references." parent: Blog nav_exclude: true nav_order: -260730 image: /assets/images/blog/minimax-h3.jpg --- ## MiniMax H3 vs Seedance 2.0: 2K with native audio, three ways to drive it July 30, 2026 (August 6, 2026) ## Table of contents MiniMax's newest video model, **H3**, is live on [POST videos/create](/docs/api-minimax-v1/post-minimax-videos-create) as `model: "Hailuo-3.0"`. Two things separate it from everything else in the MiniMax lineup: every generation ships with **native stereo audio** — no separate voice or music pass — and it renders **2K at 24 fps** by default. A cheaper 768p rung is also available. H3 is a general-purpose multimodal model rather than a set of task-specific modes. The same endpoint takes a prompt alone, a start frame, or a tray of image, video, and audio references, and the request shape is the one Seedance 2.0 already uses — set `model`, `resolution`, and `duration` directly. The three clips below are the actual output of a single 4-second run at each mode, unedited. **Turn the sound on** — the audio in all three is generated by the model. The last of the three is a direct comparison: it reuses the exact image, video, and audio references and the exact prompt from our [Seedance 2.0 omni post](/blog/260626b), so H3 and the three Seedance 2.0 tiers can be judged on identical input rather than on separate demos. ### Text to video No references at all, just a prompt. `aspectRatio` is explicit here, though H3 defaults to 16:9 when no reference is supplied. > Aerial push over jagged sea cliffs at dawn. Waves crash white against black rock far below as mist burns off in the first gold light. A lone seabird crosses frame. Cinematic wide-angle, natural color grade. Crashing surf, wind, and distant gull calls. <details markdown="block"> <summary><b>curl — Hailuo-3.0, 2K, text-to-video, 16:9</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/videos/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="Hailuo-3.0"' \ --form 'prompt="Aerial push over jagged sea cliffs at dawn. Waves crash white against black rock far below as mist burns off in the first gold light. A lone seabird crosses frame. Cinematic wide-angle, natural color grade. Crashing surf, wind, and distant gull calls."' \ --form 'resolution="1440"' \ --form 'duration="4"' \ --form 'aspectRatio="16:9"' ``` </details> <video poster="https://media.useapi.net/blog/2026-07-30-260730/t2v-16x9-4s-539432070076583938-poster.jpg" src="https://media.useapi.net/blog/2026-07-30-260730/t2v-16x9-4s-539432070076583938.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata">Your browser does not support the video element.</video> The surf, wind, and gulls are all model-generated — nothing was added to the audio track. ### A start frame, with speech Supply one image as the first frame and let the prompt drive what happens next. The portrait below is the same reference used in our [Seedance 2.0 omni post](/blog/260626b), so the two models can be compared on identical input. <img src="https://media.useapi.net/blog/2026-06-26-260626b/pretty-lady-in-the-bar-1080p.jpg" style="max-height: 50vh;" /> `fileID` — the start frame. Upload it with [POST /files](/docs/api-minimax-v1/post-minimax-files) first. > She looks into the camera, smiles, and says warmly: "You made it — I was starting to think you'd stood me up." Warm bar lights bokeh behind her, subtle handheld drift on the camera. Low jazz and crowd murmur sit under her voice. <details markdown="block"> <summary><b>curl — Hailuo-3.0, 2K, start frame + speech, 9:16</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/videos/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="Hailuo-3.0"' \ --form 'prompt="She looks into the camera, smiles, and says warmly: '\''You made it — I was starting to think you'\''d stood me up.'\'' Warm bar lights bokeh behind her, subtle handheld drift on the camera. Low jazz and crowd murmur sit under her voice."' \ --form 'fileID="user:12345-minimax:1234567890-file:your-image"' \ --form 'resolution="1440"' \ --form 'duration="4"' \ --form 'aspectRatio="9:16"' ``` </details> <video poster="https://media.useapi.net/blog/2026-07-30-260730/i2v-9x16-4s-539433093738381315-poster.jpg" src="https://media.useapi.net/blog/2026-07-30-260730/i2v-9x16-4s-539433093738381315.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata">Your browser does not support the video element.</video> Spell the spoken line out in the prompt. H3 renders the delivery from the text, so quoting the line and saying it is spoken is what puts a voice on the track. ### Omni references — image, video, and audio together The same three references from the [Seedance 2.0 omni post](/blog/260626b), and the same prompt, run through H3 for a direct comparison. H3 accepts up to 9 images, 3 videos, and 3 audio clips, capped at 12 files in total, each addressed by an `@`-tag in the prompt. <video poster="https://media.useapi.net/blog/2026-06-26-260626b/lady-jumping-rope-1080p-10s-blurred-poster.jpg" src="https://media.useapi.net/blog/2026-06-26-260626b/lady-jumping-rope-1080p-10s-blurred.mp4" style="height: 50vh; width: 100%;" controls type="video/mp4" preload="metadata">Your browser does not support the video element.</video> `@video1` — the scene, rope, and motion to keep. Its face is blurred on purpose: a clear real face in a video reference is rejected by the content filter, and the identity comes from `@image1` anyway. <audio controls class="audio-player"><source src="https://media.useapi.net/blog/2026-06-26-260626b/count-me-jumping-jsessica-eleven-v3-2s.mp3" type="audio/mp3">Your browser does not support the audio element.</audio> `@audio1` — the speech to drive, about 2 seconds. Together with the portrait above as `@image1`, that is the full tray. > Replace the woman in @video1 with @image1, keeping the same outdoor scene, rope, and jumping movements. She speaks out loud, clearly saying "Count me jumping" in the voice from @audio1, audible throughout the clip. <details markdown="block"> <summary><b>curl — Hailuo-3.0, 2K, omni image + video + audio</b></summary> ```bash curl --location 'https://api.useapi.net/v1/minimax/videos/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="Hailuo-3.0"' \ --form 'prompt="Replace the woman in @video1 with @image1, keeping the same outdoor scene, rope, and jumping movements. She speaks out loud, clearly saying '\''Count me jumping'\'' in the voice from @audio1, audible throughout the clip."' \ --form 'fileID="user:12345-minimax:1234567890-file:your-image"' \ --form 'videoFileID1="user:12345-minimax:1234567890-file:your-video"' \ --form 'audioFileID1="user:12345-minimax:1234567890-file:your-audio"' \ --form 'resolution="1440"' \ --form 'duration="4"' ``` </details> <video poster="https://media.useapi.net/blog/2026-07-30-260730/omni-4s-539434016338526214-poster.jpg" src="https://media.useapi.net/blog/2026-07-30-260730/omni-4s-539434016338526214.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata">Your browser does not support the video element.</video> No `aspectRatio` was sent here. With references attached H3 defaults to `Auto` and matched the 9:16 shape of the inputs on its own. ### What it costs H3 bills per second of output — 12 credits at 2K, and 7 at 768p. A video reference is charged on its own length at the same rate, on top of the generated clip. Image and audio references add nothing per second. | Request | 768p | 2K | |:--------|:----:|:--:| | 4-second clip, no references | 28 | 48 | | 4-second clip, image reference | 28 | 48 | | 4-second clip, 10-second video reference | 98 | 168 | | 15-second clip, no references | 105 | 180 | That surcharge is worth planning around: trim a video reference to the shortest clip that carries the motion you need, since its full length is billed whatever the output duration. ### Where H3 fits Seedance 2.0 still reaches 4K, so it stays the pick when you need the highest resolution, and Seedance-2.0-Mini at 480p is the cheapest per second on the whole endpoint. Everywhere else the arithmetic now favours H3: at 7 credits per second, 768p undercuts every Seedance tier at a comparable size — Mini's 720p is 11, Fast's is 17, Standard's is 21 — and it still carries native audio. Use 768p to iterate and 2K to finish, and reach for Seedance when you want 4K. --- See the [POST videos/create](/docs/api-minimax-v1/post-minimax-videos-create) reference for every parameter, the reference-media limits, and a live Try-It console. Compare every Seedance 2.0 and 2.5 route and price: [Seedance 2.0 and 2.5 API Pricing](/docs/articles/seedance-2-api-pricing). ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/blog/260807 === Document URL: https://useapi.net/blog/260807 --- layout: blog_post title: "Dreamina: Seedance 2.5" description: "Seedance 2.5 lands on the Dreamina API with 30-second clips, up to 50 omni references, a 480p tier, and a discount for supplying a reference video — plus real human faces without the grid workaround." parent: Blog nav_exclude: true nav_order: -260807 --- ## Seedance 2.5 on the Dreamina API August 7, 2026 `seedance-2.5` is live on [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos) in both the US and CA regions. It is a new generation rather than a variant of the Seedance 2.0 family: | | Seedance 2.0 | Seedance 2.5 | |---|---|---| | Duration | 4-15s | **4-30s** | | Resolutions | 720p / 1080p / 4K | **480p (default) / 720p** | | Omni references | 9 images, 3 videos, 3 audio | **30 / 10 / 10, 50 total** | | Reference video length | 2-15.4s | **1.8-30.2s** | | Prompt length | 4,000 | **15,000** | The headline is the reference-video discount: give Seedance 2.5 a video to work from and the per-second rate drops by roughly a fifth. It is the only Dreamina model whose price depends on what you feed it. ## Real human faces and cinematic violence both work now Our [Seedance 2.0 real-faces tutorial](/blog/260415) documented a workaround: Dreamina's Seedance 2.0 input filter rejected recognisable human faces, so the portrait had to be shipped with a sparse grid overlaid on the face to drop the classifier below its threshold. **Seedance 2.5 does not need it.** Every clip below uses the unaltered original portrait — the same image, no grid. If you built the grid step into a pipeline, you can skip it for this model. Stylised violence is generated too. The boxing clip below is a bare-knuckle-style impact with blood spraying through the light, and it renders without complaint — cinematic gore is not what this model refuses. What it does refuse is covered at the end. ## Text to video No references at all, 480p, 4 seconds. Human bodies under impact are where video models usually fall apart, so that is what we asked for: a boxing ring, one swinging work lamp, and a spray of sweat and blood suspended in the light while the camera arcs around the moment of contact. <details markdown="block"> <summary><b>curl — seedance-2.5, 480p, 4s, text only</b></summary> ```bash curl --location 'https://api.useapi.net/v1/dreamina/videos' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="seedance-2.5"' \ --form 'prompt="Extreme slow motion inside a boxing ring at night, one hard work lamp swinging on its cable above the ropes. A boxer takes a hook to the jaw — head snapping sideways, sweat and blood spraying outward in a suspended arc through the light. His opponent follows through, shoulder and back muscles taut, gloves laced tight. A ring of onlookers watches from the shadows. The camera arcs around the moment of impact. Desaturated, harsh contrast, anamorphic flare, heavy film grain."' \ --form 'ratio="16:9"' \ --form 'duration="4"' \ --form 'account="CA:your-dreamina-email@example.com"' ``` </details> <video poster="https://media.useapi.net/blog/2026-08-07-260807/t2v-480p-4s-0807-215322-poster.jpg" src="https://media.useapi.net/blog/2026-08-07-260807/t2v-480p-4s-0807-215322.mp4" style="width: 100%; max-width: 700px;" controls type="video/mp4" preload="metadata">Your browser does not support the video element.</video> ## Omni: image, video and audio together The same request we published for [Seedance 2.0 on PixVerse](/blog/260626a) — one portrait, one soccer clip, one line of speech — re-run on Seedance 2.5. The prompt drops the woman from `@image1` into the scene from `@video1` and drives her speech from `@audio1`. The three references go in together: <img src="https://media.useapi.net/blog/2026-06-26-260626a/model-original-jpeg.jpg" style="max-height: 60vh;" /> `@image1` — the face and identity to drop in. Unaltered, no face grid. <video poster="https://media.useapi.net/blog/2026-06-26-260626a/soccer-player-720p-5s-poster.jpg" src="https://media.useapi.net/blog/2026-06-26-260626a/soccer-player-720p-5s.mp4" style="height: 60vh; width: 100%;" controls type="video/mp4" preload="metadata">Your browser does not support the video element.</video> `@video1` — the scene, pose, ball, and motion to keep. <audio controls class="audio-player"><source src="https://media.useapi.net/blog/2026-06-26-260626a/hey-there-want-to-play-2s.mp3" type="audio/mp3">Your browser does not support the audio element.</audio> `@audio1` — the speech to drive (about 2 seconds). Because a video reference is attached, this one bills at the discounted rate. <details markdown="block"> <summary><b>curl — seedance-2.5, 480p, 4s, omni image + video + audio</b></summary> ```bash curl --location 'https://api.useapi.net/v1/dreamina/videos' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="seedance-2.5"' \ --form 'prompt="Replace the woman in @video1 with @image1, keeping the exact same scene, soccer ball and movements, and make her say @audio1"' \ --form 'omni_1_imageRef="CA:your-dreamina-email@example.com-image:w457:h819:s122199-uri:tos-..."' \ --form 'omni_1_videoRef="CA:your-dreamina-email@example.com-video:w720:h1366:d5000-vid:v107..."' \ --form 'omni_1_audioRef="CA:your-dreamina-email@example.com-audio:d2038-vid:v107..."' \ --form 'ratio="9:16"' \ --form 'duration="4"' \ --form 'account="CA:your-dreamina-email@example.com"' ``` </details> <video poster="https://media.useapi.net/blog/2026-08-07-260807/omni-swap-480p-4s-0807-214408-poster.jpg" src="https://media.useapi.net/blog/2026-08-07-260807/omni-swap-480p-4s-0807-214408.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata">Your browser does not support the video element.</video> Upload each reference with [POST /assets/`account`](/docs/api-dreamina-v1/post-dreamina-assets-account) first, then pass the returned `assetRef` values as `omni_N_imageRef`, `omni_N_videoRef` and `omni_N_audioRef`. A reference the prompt never `@`-mentions is ignored and not billed. ## Fifteen seconds in one shot The 2.0 family stops at 15 seconds. Seedance 2.5 goes to 30, and holds a character across the whole thing from a single reference image — here a full time-freeze scene at 720p with a beginning, a middle and a punchline. <details markdown="block"> <summary><b>curl — seedance-2.5, 720p, 15s, one image reference</b></summary> ```bash curl --location 'https://api.useapi.net/v1/dreamina/videos' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="seedance-2.5"' \ --form 'prompt="A cinematic continuous shot on a palm-lined boulevard at golden hour. @image1 walks confidently toward camera ... She stops directly in front of him and looks him slowly up and down. She flicks open a lighter, lights her cigarette, exhales a long slow plume of smoke into his frozen face, smirks, and says '\''Still not returning my calls?'\'' ... Keep @image1 identity consistent throughout."' \ --form 'omni_1_imageRef="CA:your-dreamina-email@example.com-image:w457:h819:s122199-uri:tos-..."' \ --form 'ratio="9:16"' \ --form 'duration="15"' \ --form 'resolution="720p"' \ --form 'account="CA:your-dreamina-email@example.com"' ``` </details> <video poster="https://media.useapi.net/blog/2026-08-07-260807/hollywood-720p-15s-0807-220801-poster.jpg" src="https://media.useapi.net/blog/2026-08-07-260807/hollywood-720p-15s-0807-220801.mp4" style="height: 70vh; width: 100%;" controls type="video/mp4" preload="metadata">Your browser does not support the video element.</video> ## What it costs Cost is `rate × billed seconds`, and the rate depends on the resolution and on whether you supplied a reference video. All figures in US dollars, using each region's Advanced plan (CA converted at CAD/USD 0.7167). | | US $/sec | CA $/sec | 4-second clip (US / CA) | |---|---:|---:|---:| | 480p, with a video reference | $0.113 | $0.105 | $0.45 / $0.42 | | 480p | $0.138 | $0.128 | $0.55 / $0.51 | | 720p, with a video reference | $0.235 | $0.216 | $0.94 / $0.86 | | 720p | $0.300 | $0.280 | $1.20 / $1.12 | The reference video's own duration is billed on top of the output, so a 4-second clip built from a 5-second reference bills 9 seconds. The discount pays off when the reference is short relative to the output. Failed generations are not charged. See the [Dreamina cost calculator](/docs/start-here/setup-dreamina#cost-calculator) for the full per-model breakdown and plan pricing in both regions. ## One gotcha worth knowing Seedance 2.5 can reject a finished generation with `fail_code 2053` — the web UI phrases it as "the video may contain third-party content". It fires two to four minutes into generation and judges the **output**, not the prompt. It is not about violence, and it is not about real faces — the boxing clip and the portrait above both render fine. It triggers when the result would depict something recognisable. In our testing, prompts that named no person and no property still failed because they *described* one: a costumed superhero in a crowd, a trademarked landmark, and a man with a "movie-star jaw" surrounded by paparazzi who was "clearly the most famous person on the street". Removing that last phrase was what made the 15-second clip render. The rule for prompt authors: it is not enough to avoid naming a property or a person — avoid asking the model to produce one. --- Full parameter reference, per-model limits and a live Try-It console: [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos). New to the API? Start with [Setup Dreamina](/docs/start-here/setup-dreamina). Compare every Seedance 2.0 and 2.5 route and price: [Seedance 2.0 and 2.5 API Pricing](/docs/articles/seedance-2-api-pricing). ### 开始使用 每月 15 美元的订阅即可使用 useapi.net 上的所有 API:一个 Token,所有服务。每个服务最多绑定 3 个你自己的账号,useapi.net 负责 REST 接口、负载均衡和轮询。需要更多账号?每增加一个订阅每月 10 美元,每个服务再多 3 个账号。 [订阅 — 每月 15 美元](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [用加密货币支付](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 没有国际信用卡?可以[用加密货币订阅](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)(加密货币付款不退款)。价格与批量方案见[订阅页面](/docs/subscription)。用 Stripe 付款,首次购买 14 天内、且成功生成少于 50 次可全额退款。已经订阅?请在 [Stripe 客户门户](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) 修改数量,无需重新购买。 ### API を使い始める 月額15ドルのサブスクリプション1つで、useapi.net のすべての API を使えます。トークン1つで、すべてのサービスに対応します。各サービスにご自身のアカウントを最大3つまで接続でき、REST API、負荷分散、ポーリングは useapi.net が担当します。アカウントを増やしたい場合は、サブスクリプションを1つ追加するごとに月額10ドルで、各サービスのアカウントが3つずつ増えます。 [登録する — 月額15ドル](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [暗号資産で支払う](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) 海外で使えるクレジットカードがない場合は、[暗号資産で登録](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)することもできます(暗号資産での支払いは返金できません)。料金とボリュームプランは[サブスクリプションのページ](/docs/subscription)をご覧ください。Stripe でお支払いの場合、初回購入から14日以内で、成功した生成が50回未満であれば全額返金されます。すでに登録済みの場合は、新たに購入せず [Stripe カスタマーポータル](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo)で数量を変更してください。 ### Comece a usar a API Uma assinatura de US$ 15 por mês dá acesso a todas as APIs da useapi.net: um token, todos os serviços. Você conecta até 3 contas suas por serviço, e a useapi.net cuida da API REST, do balanceamento de carga e do polling. Precisa de mais contas? Cada assinatura extra custa US$ 10 por mês e acrescenta mais 3 contas por serviço. [Assinar — US$ 15/mês](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar com cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Não tem cartão de crédito internacional? Você também pode [assinar com criptomoedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pagamentos em cripto não são reembolsáveis). Preços e planos de volume estão na [página de assinatura](/docs/subscription). Pagando pelo Stripe, você recebe reembolso integral em até 14 dias após a primeira compra, se tiver menos de 50 gerações bem-sucedidas. Já é assinante? Altere a quantidade no [portal do cliente Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) em vez de comprar de novo. ### Bắt đầu dùng API Một gói đăng ký $15/tháng dùng được mọi API trên useapi.net: một token cho tất cả dịch vụ. Mỗi dịch vụ bạn kết nối tối đa 3 tài khoản của riêng mình, còn useapi.net lo REST API, cân bằng tải và polling. Cần thêm tài khoản? Mỗi gói đăng ký thêm giá $10/tháng và cho thêm 3 tài khoản ở mỗi dịch vụ. [Đăng ký — $15/tháng](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Thanh toán bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Không có thẻ thanh toán quốc tế? Bạn có thể [đăng ký bằng tiền mã hóa](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (thanh toán bằng tiền mã hóa không được hoàn tiền). Giá và các gói số lượng lớn có trên [trang đăng ký](/docs/subscription). Nếu thanh toán qua Stripe, bạn được hoàn tiền toàn bộ trong 14 ngày kể từ lần mua đầu tiên khi có dưới 50 lượt tạo thành công. Đã đăng ký rồi? Hãy đổi số lượng trong [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) thay vì mua lại. ### Mulai memakai API Satu langganan US$15/bulan mencakup semua API di useapi.net: satu token untuk semua layanan. Di setiap layanan Anda bisa menghubungkan hingga 3 akun milik Anda sendiri, dan useapi.net menangani REST API, load balancing, dan polling. Butuh lebih banyak akun? Setiap langganan tambahan US$10/bulan dan menambah 3 akun lagi per layanan. [Berlangganan — US$15/bulan](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Bayar dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Tidak punya kartu kredit internasional? Anda bisa [berlangganan dengan kripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (pembayaran kripto tidak bisa di-refund). Harga dan paket volume ada di [halaman langganan](/docs/subscription). Jika membayar lewat Stripe, Anda mendapat refund penuh dalam 14 hari sejak pembelian pertama, selama jumlah generasi yang berhasil kurang dari 50. Sudah berlangganan? Ubah jumlahnya di [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo), tidak perlu membeli lagi. ### เริ่มใช้งาน API การสมัครสมาชิกเดือนละ $15 ใช้ได้กับทุก API บน useapi.net ใช้ Token เดียวกับทุกบริการ เชื่อมบัญชีของคุณเองได้สูงสุด 3 บัญชีต่อบริการ แต่ละบัญชีใช้แพ็กเกจของเว็บไซต์นั้นเอง ส่วน useapi.net ดูแล REST API การกระจายโหลด และการ polling ให้ ต้องการบัญชีมากกว่านี้? สมัครเพิ่มแต่ละครั้งเดือนละ $10 และได้เพิ่มอีก 3 บัญชีต่อบริการ [สมัครสมาชิก — $15/เดือน](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [ชำระด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ไม่มีบัตรเครดิตที่ใช้จ่ายต่างประเทศได้? [สมัครด้วยคริปโต](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK)ก็ได้ (การชำระด้วยคริปโตขอคืนเงินไม่ได้) ดูราคาและแพ็กเกจสำหรับปริมาณมากได้ที่[หน้าการสมัครสมาชิก](/docs/subscription) ถ้าชำระผ่าน Stripe ขอคืนเงินเต็มจำนวนได้ภายใน 14 วันหลังซื้อครั้งแรก หากสร้างงานสำเร็จไม่ถึง 50 ครั้ง สมัครไว้แล้ว? เปลี่ยนจำนวนได้ที่ [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) โดยไม่ต้องซื้อใหม่ ### Empieza a usar la API Una sola suscripción de US$15 al mes cubre todas las API de useapi.net: un token para todos los servicios. Conectas hasta 3 cuentas propias por servicio, cada una con la suscripción de su sitio web, y useapi.net se encarga de la API REST, el balanceo de carga y el polling. ¿Necesitas más cuentas? Cada suscripción adicional cuesta US$10 al mes y suma 3 cuentas más por servicio. [Suscríbete — US$15/mes](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pagar con cripto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) ¿No tienes una tarjeta de crédito internacional? También puedes [suscribirte con criptomonedas](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) (los pagos con cripto no se reembolsan). Los precios y los planes por volumen están en la [página de suscripción](/docs/subscription). Si pagas con Stripe, recibes el reembolso completo dentro de los 14 días posteriores a la primera compra, si tienes menos de 50 generaciones exitosas. ¿Ya tienes una suscripción? Cambia la cantidad en el [portal de clientes de Stripe](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) en lugar de volver a comprar. ### Start using the API A single $15/month subscription covers every API on useapi.net — one token, all services. You connect up to 3 accounts per service, each with its own website subscription, and useapi.net handles the REST API, load balancing, and polling. Need more accounts? Each extra subscription is $10/month and adds 3 more accounts per service. [Subscribe — $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03){: .btn .btn-purple .mr-2 .mt-3 .mb-3 } [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) [Pricing and volume options](/docs/subscription) — full refund within the first 14 days if you have fewer than 50 successful generations. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. === URL: https://useapi.net/blog/260812 === Document URL: https://useapi.net/blog/260812 --- layout: blog_post title: "Flow Music: Generate Songs with Google's Lyria 3.5" description: "Generate complete songs with Google's Lyria 3.5 through the Flow Music API v1 — the new model parameter picks Lyria 3.5 or Lyria 3 Pro, which stays the default so existing integrations are unchanged." parent: Blog nav_exclude: true nav_order: -260812 --- ## Flow Music: Generate Songs with Google's Lyria 3.5 ## Table of contents Google shipped [Lyria 3.5](https://deepmind.google/models/lyria/) to [Flow Music](https://www.flowmusic.app), describing it as its top-performing model with more dynamic vocals and richer musicality. The [Flow Music API v1](/docs/api-flowmusic-v1) now exposes it through a new optional `model` parameter on [POST /music](/docs/api-flowmusic-v1/post-flowmusic-music) and [POST /music/edit](/docs/api-flowmusic-v1/post-flowmusic-music-edit). `model` accepts `lyria-3.5` or `lyria-3-pro`. **`lyria-3-pro` remains the default.** Every song generated through this API since launch was rendered on it, so leaving `model` out keeps your output exactly as it was — nothing changes for existing integrations unless you opt in. ### Generate an instrumental on Lyria 3.5 Add `"model": "lyria-3.5"` to any [POST /music](/docs/api-flowmusic-v1/post-flowmusic-music) call. Everything else works the same, and each generation still returns up to two clips as an A/B pair. Analog Tides — warm analog synthwave, instrumental <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-flowmusic-v1/post-flowmusic-music">POST /music</a> (instrumental, Lyria 3.5)</summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:1234-…' \ --form 'prompt="warm analog synthwave, steady 100bpm, shimmering arpeggios"' \ --form 'instrumental="true"' \ --form 'model="lyria-3.5"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-08-12-260812/a2-instrumental-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> ### Sing your own lyrics Pass `lyrics` and the model sings your words instead of writing its own. Tag the sections with `[Verse]` and `[Chorus]` to shape the arrangement. Dashboard Drift — the same synthwave prompt, with supplied lyrics <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-flowmusic-v1/post-flowmusic-music">POST /music</a> (custom lyrics, Lyria 3.5)</summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:1234-…' \ --form 'prompt="warm analog synthwave, steady 100bpm, shimmering arpeggios"' \ --form 'model="lyria-3.5"' \ --form 'lyrics="[Verse] Neon lines across the dashboard glow [Chorus] Drive me slow, drive me slow"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-08-12-260812/c1-vocals-custom-lyrics-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Dashboard Ghost — a slower ballad prompt over a longer lyric <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-flowmusic-v1/post-flowmusic-music">POST /music</a> (ballad, Lyria 3.5)</summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music' \ --header 'Authorization: Bearer user:1234-…' \ --form 'prompt="synthwave ballad, warm analog pads, emotive female vocal, 90 bpm"' \ --form 'model="lyria-3.5"' \ --form 'lyrics="[Verse] Neon rain on the boulevard I keep your ghost in the dashboard light [Chorus] Drive me slow through the afterglow We were never meant to say goodnight"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-08-12-260812/e2-vocal-custom-lyrics-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> The model expands what you give it — the returned `clip.lyrics` holds the full lyric it actually sang, which is usually longer than the seed you passed. ### Editing existing songs [POST /music/edit](/docs/api-flowmusic-v1/post-flowmusic-music-edit) takes `model` too, alongside `cover`, `extend`, `replace` and `remix`. The four examples below are all edits of one existing track, each requested with `model: lyria-3.5`. `cover` restyles the whole song, here to solo piano. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-flowmusic-v1/post-flowmusic-music-edit">POST /music/edit</a> (cover)</summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music/edit' \ --header 'Authorization: Bearer user:1234-…' \ --form 'operation="cover"' \ --form 'clip="user:1234-user@email.com-clip:…"' \ --form 'instruction="solo piano"' \ --form 'model="lyria-3.5"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-08-12-260812/d1-cover-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> `extend` adds new music to the end — 30 seconds here, taking the track from 175 s to 205 s. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-flowmusic-v1/post-flowmusic-music-edit">POST /music/edit</a> (extend)</summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music/edit' \ --header 'Authorization: Bearer user:1234-…' \ --form 'operation="extend"' \ --form 'clip="user:1234-user@email.com-clip:…"' \ --form 'instruction="build to a big finish"' \ --form 'extend_s="30"' \ --form 'model="lyria-3.5"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-08-12-260812/d2-extend-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> `replace` regenerates one section in place, leaving the rest untouched. This one swaps seconds 20 to 40 for a bright synth lead. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-flowmusic-v1/post-flowmusic-music-edit">POST /music/edit</a> (replace)</summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music/edit' \ --header 'Authorization: Bearer user:1234-…' \ --form 'operation="replace"' \ --form 'clip="user:1234-user@email.com-clip:…"' \ --form 'instruction="swap in a bright synth lead"' \ --form 'mask_start_s="20"' \ --form 'mask_end_s="40"' \ --form 'model="lyria-3.5"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-08-12-260812/d3-replace-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> `remix` re-sings the song with edited lyrics over the original sound. Pin `seed` to make the run reproducible. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-flowmusic-v1/post-flowmusic-music-edit">POST /music/edit</a> (remix)</summary> ```bash curl --location 'https://api.useapi.net/v1/flowmusic/music/edit' \ --header 'Authorization: Bearer user:1234-…' \ --form 'operation="remix"' \ --form 'clip="user:1234-user@email.com-clip:…"' \ --form 'prompt="warm analog synthwave, steady 100bpm, shimmering arpeggios"' \ --form 'seed="777"' \ --form 'model="lyria-3.5"' \ --form 'lyrics="[Verse] Neon lines across the dashboard glow [Chorus] Drive me slow, drive me slow"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-08-12-260812/b2-remix-lyria-3.5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> `effect` and `stems` accept `model` as well, but their output is unaffected — those are signal processing and stem separation, with no music model in the loop. ### Which model should you use Both models are available on every Flow Music plan, including free accounts, and cost the same per song. `lyria-3-pro` stays the default, so nothing changes until you ask for something else. If you want the newer model, send `"model": "lyria-3.5"` and compare against your own prompts — that is the only comparison that matters for your material. See [POST /music](/docs/api-flowmusic-v1/post-flowmusic-music) and [POST /music/edit](/docs/api-flowmusic-v1/post-flowmusic-music-edit) for the full parameter reference, or the [Flow Music API overview](/docs/api-flowmusic-v1) for pricing and the cost calculator. === URL: https://useapi.net/blog/260814 === Document URL: https://useapi.net/blog/260814 --- layout: blog_post title: "Mureka: V9.5 Now the Default Music Model" description: "Mureka API v1 now supports V9.5, the new default music model — natural songwriting, authentic performances and a fuller sound at 12 credits per song." parent: Blog nav_exclude: true nav_order: -260814 --- [Mureka API v1](/docs/api-mureka-v1) now supports Mureka's latest `V9.5` model, and it takes over from `V9` as the default. Mureka bills it as natural songwriting, authentic performances and a fuller sound. It costs 12 credits per song, the same as `V9`, and accepts everything `V9` did — reference tracks, motifs, cloned vocals, instrumentals and remix. **Music V9.5 Female** - Wait for the Morning ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-advanced' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: application/json' \ --data '{ "lyrics": "[Verse]\nThe kitchen clock is ticking loud\nWatching shadows cross the floor\nI left the coffee in the pot\nAnd leaned my head against the door\n\n[Chorus]\nWait for the morning\nThe light is gonna find us soon\nWait for the morning\nI'\''m tired of this empty room\n\n[Verse]\nI found your jacket on the chair\nThe one you bought three years ago\nThe pockets full of movie stubs\nFrom all the places we would go\n\n[Chorus]\nWait for the morning\nThe light is gonna find us soon\nWait for the morning\nI'\''m tired of this empty room\n\n[Verse]\nThe radio is playing soft\nA song about a different time\nIt'\''s funny how the melody\nJust never seems to fit the rhyme\n\n[Chorus]\nWait for the morning\nThe light is gonna find us soon\nWait for the morning\nI'\''m tired of this empty room\n\n[Outro]", "desc": "soft jazz, classic edm", "vocal_gender": "female", "model": "V9.5" }' ``` <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-08-14-260814/mureka-v95.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Three minutes twenty-three from a four-word style brief. Mureka labelled what came back *nu-jazz, sophisticated, upright bass, syncopated breakbeat, a female vocalist* — its own reading of the track, not our prompt. ### Choosing a model Omit `model` and the API uses whichever model Mureka reports as the default for your account, falling back to `V9.5`. Ask for an older one by name and it still works — `V9`, `V8`, `O2`, `V7.6` and `V7.5-all` are all unchanged, and the retired `V7`, `O1`, `V6` and `V5.5` aliases keep redirecting to `V7.6`. One thing to watch: Mureka will advertise `V9.5` as the default even for accounts that are not entitled to it, so treat the default it reports as a suggestion rather than a guarantee. === URL: https://useapi.net/blog/260817 === Document URL: https://useapi.net/blog/260817 --- layout: blog_post title: "MiniMax: Music Generation, Three Ways" description: "MiniMax API v1 now generates complete songs with Music-3.0 and Music-2.6 — instrumentals, model-written lyrics, or your own words, streamed while they render, at roughly $0.01 a song." parent: Blog nav_exclude: true nav_order: -260817 --- [MiniMax API v1](/docs/api-minimax-v1) now generates music. One endpoint — [POST /music/create](/docs/api-minimax-v1/post-minimax-music-create) — covers three quite different ways of asking for a song. Everything below is a single unedited call. No retries, no cherry-picking. --- ### An instrumental Set `instrumental` to `true` and describe the arrangement. Leaving `lyrics` empty is *not* enough on its own — without the flag the model writes its own words and sings them. ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: application/json' \ --data '{ "title": "Rain on Sixth Street", "prompt": "smoky late-night jazz instrumental, upright bass walking slow, brushed snare, muted trumpet playing a lonely melody, rhodes piano comping, rainy city club atmosphere, loose and unhurried, tape warmth", "instrumental": true, "model": "music-3.0" }' ``` <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-08-17-260817/1-rain-on-sixth-street.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Two minutes twenty, and the `lyrics` field comes back empty — there is nothing to sing. ### Lyrics written for you Give it only a `prompt` and the model writes the words. The prompt field does two jobs at once: it carries the musical style *and* the subject. Say what the song should be about in the same sentence and it obliges. ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: application/json' \ --data '{ "title": "The Last Train Home", "prompt": "warm indie folk, fingerpicked acoustic guitar, male vocals, gentle brushed drums, nostalgic and unhurried, about a night shift worker riding the last train home through empty streets", "model": "music-3.0" }' ``` <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-08-17-260817/2-the-last-train-home.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Three minutes three, and the response carries the lyrics it invented — two verses, a pre-chorus, a bridge, and a chorus it returns to three times: ``` [Verse] Punch the card and grab my coat Losing buttons on my throat The station floor is shining grey Final hour of the day [Post-Chorus] Click-clack, the rhythm goes Watch how the city glows Click-clack, it's almost dawn Before the stars are gone ``` `[Post-Chorus]` is not one of the section tags we document, which is the point — the tag list is what *you* can use to structure your own words. Left to itself the model structures the song however the song wants to go. ### Your own lyrics Supply `lyrics` and they are used verbatim. Structure them with tags on their own line — `[Verse]`, `[Pre-Chorus]`, `[Chorus]`, `[Bridge]`, `[Outro]` and the rest — and use the `prompt` for the sound. ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: application/json' \ --data '{ "title": "Paper Boats", "prompt": "dreamy synth-pop, female vocals, shimmering pads, steady mid-tempo beat, bittersweet", "lyrics": "[Verse]\nWe folded up the summer into paper boats\nSet them on the water, watched them barely float\nYou said nothing lasts, and I said that'\''s alright\nWe were only ever borrowing the light\n\n[Pre-Chorus]\nAnd the current took them one by one\nEverything we made came undone\n\n[Chorus]\nPaper boats, paper boats\nCarrying the things we never wrote\nLet them go, let them go\nSome of them were never meant to float\n\n[Verse]\nI keep one folded flat inside my coat\nA small white promise and a paper throat\nIt doesn'\''t sail, it doesn'\''t have to now\nIt just remembers how\n\n[Chorus]\nPaper boats, paper boats\nCarrying the things we never wrote\nLet them go, let them go\nSome of them were never meant to float\n\n[Outro]\nAh, ah, ah\nSome of them were never meant to float", "model": "music-3.0" }' ``` <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-08-17-260817/3-paper-boats.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Two minutes forty-eight, and the lyrics come back byte-for-byte as they went in. Wordless vocals work too — spell the syllables out, as the `[Outro]` above does. ### About $0.01 a song Music does not draw on the credits your video and image generations use. MiniMax bills audio separately: a new account gets a small allowance to try it, and past that you buy a **MiniMax audio subscription** — covering music and speech — from MiniMax directly. Budget for it alongside whatever you already spend there on video. A song costs **300 credits**, and bought as part of that audio subscription those 300 credits come to about **$0.01**. Compare that with MiniMax's own [pay-as-you-go API](https://platform.minimax.io/docs/pricing/overview#about-music-models), which charges **$0.15 a composition**, and **$0.01 more** if you want it to write the lyrics: | MiniMax plan | $/month | Songs included | Cost per song | vs. $0.15 API | |---|--:|--:|--:|--:| | Starter | $5 | 333 | $0.0150 | 10× cheaper | | Creator | $15 | 1 100 | $0.0136 | 11× cheaper | | Standard | $30 | 2 500 | $0.0120 | 12.5× cheaper | | Pro | $99 | 10 000 | **$0.0099** | **15× cheaper** | The lyrics are free on top of that. On the pay-as-you-go API, model-written lyrics are a separate `lyrics_generation` call at $0.01 a song — a two-thirds surcharge on a $0.15 track. Here they are part of the same 300 credits, and they come back in the `201` response before any audio exists, so you can read the words the moment you submit. *The Last Train Home* above cost the same as the instrumental beside it. One caveat: a plan is money up front, so at very low volume pay-as-you-go still wins — below roughly **31 songs a month** the $5 Starter plan costs more than paying $0.16 a track. Above that the subscription is ahead, and configuring several accounts multiplies both the throughput and the allowance. ### Streaming Set `stream` to `true` and the response becomes a Server-Sent Events stream of MP3 chunks instead of JSON, so playback can start before the song is finished. Expect twenty to fifty seconds of silence before the first audio arrives, then continuous audio to the end. The [streaming section](/docs/api-minimax-v1/post-minimax-music-create#streaming) has a worked example, including feeding the chunks straight into a MediaSource for live playback in a browser. Otherwise the call returns a `musicId` immediately and you poll [GET /music/`musicId`](/docs/api-minimax-v1/get-minimax-music-musicId), or pass a `replyUrl` and we POST you the finished track. Everything comes back as 44.1 kHz stereo MP3 at 256 kbps. === URL: https://useapi.net/blog/260821 === Document URL: https://useapi.net/blog/260821 --- layout: blog_post title: "MiniMax: Cover a Track You Upload" description: "MiniMax API v1 can now build a song from a reference track — upload an MP3 or WAV, get a reusable musicId, and pass it to music/create as referenceMusicId." parent: Blog nav_exclude: true nav_order: -260821 --- [MiniMax API v1](/docs/api-minimax-v1) can now generate from a **reference track**. Upload a piece of audio, get a `musicId` back, and hand that to [POST /music/create](/docs/api-minimax-v1/post-minimax-music-create) — the song it writes is built in the character of what you uploaded. Two calls, and the first one is free. --- ### Upload the reference [POST /music/reference](/docs/api-minimax-v1/post-minimax-music-reference) takes the raw bytes of an MP3 or WAV. This is the one endpoint in the music API that is not JSON or form-encoded — the body *is* the file, and `Content-Type` has to match it. ```bash curl --location 'https://api.useapi.net/v1/minimax/music/reference?name=Stadium%20Reference' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: audio/mpeg' \ --data-binary '@reference.mp3' ``` The clip used below is 21 seconds of a stomping, chant-driven groove: <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-08-21-260821/minimax-reference-clip-21s.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> It comes back complete — no polling, no waiting: ```json { "musicId": "user:12345-minimax:123456789012345678-music:987654321098766", "title": "Stadium Reference", "duration": 21408, "statusLabel": "completed", "typeLabel": "reference", "lyrics": "[Verse]\n…" } ``` Two things worth noticing. `lyrics` is filled in — MiniMax transcribes whatever singing it hears during the upload, which is how you recover the original words if you want the cover to keep them. And `audio_url` points at MiniMax's own re-encoded copy, not your file, so you can play back exactly what the model will be working from. Uploading costs no credits, and the reference is permanent. One upload backs any number of covers. ### Cover it Pass that `musicId` as `referenceMusicId`. Your `prompt` sets the genre and arrangement, your `lyrics` set the words. ```bash curl --location 'https://api.useapi.net/v1/minimax/music/create' \ --header 'Authorization: Bearer user:12345-…' \ --form 'referenceMusicId="user:12345-minimax:123456789012345678-music:987654321098766"' \ --form 'title="Ship It Friday"' \ --form 'prompt="stadium stomp and clap rock anthem, huge gang vocals, boot stomps and handclaps, distorted guitar riff, arena crowd, no drum kit until the chorus"' \ --form 'lyrics="[Verse] Warn me, storm me, you can never ground me Test me, stress me, everybody doubt me Page me, rage me, watch the pipeline turning Roll me, hold me, but the green light'\''s burning [Chorus] Ship it! Ship it! Friday! Nobody'\''s rolling back today"' ``` <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-08-21-260821/minimax-cover-ship-it-friday-stadium-stomp.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Twenty-one seconds, generated in about forty-five. Same length as the reference, same stomp underneath, different genre on top. ### Lyric volume is the length dial There is no duration parameter, and the reference does not set the length either — the amount of `lyrics` you supply does. That turns out to matter more than it sounds. Against the same 21-second reference, holding everything else constant: | `lyrics` | Result | |---|---| | None | 51 s — the model writes its own, at length | | 246 characters | 21 s | | 1,031 characters | 30-45 s, and audibly rushed | The failure mode is worth knowing about. A thousand characters of lyrics over a thirty-second track is roughly 32 characters of text per second of audio, and it sounds exactly like it reads — crammed. Trim the words back to about 12 characters per second and the same prompt, the same reference and the same idea land properly. Three very different genre prompts at that density all came out within 0.7 s of each other, and within 0.5 s of the reference. So if a result feels wrong, cut lyrics before you rewrite the prompt. ### Anything on the account can be a reference `referenceMusicId` is not limited to uploads. Any `musicId` on the same account works, including songs this API generated earlier — so you can take a track you like and re-cut it in another genre without uploading anything. Uploaded references live in the same history as your songs, and [GET /music](/docs/api-minimax-v1/get-minimax-music) keeps them apart with a new `type` parameter: ```bash curl --location 'https://api.useapi.net/v1/minimax/music/?type=reference' \ --header 'Authorization: Bearer user:12345-…' ``` `type` defaults to `song`, so uploading references never changes what an existing integration sees. Every row also carries `typeLabel`, and a cover carries `referenceMusicId` pointing back at what it was built from. ### Notes - Covers cost the same 300 credits as any other song. Uploads are free. - `instrumental` cannot be combined with `referenceMusicId`. MiniMax accepts the pair and then fails the track, so the API rejects it up front rather than spending your credits on something that will never render. - Streaming works with covers. Set `stream` to `true` and you can play it while it renders, exactly as with a normal generation. - Only use material you have the rights to. A reference you upload is audio you are responsible for. Full reference: [POST music/reference](/docs/api-minimax-v1/post-minimax-music-reference) and [POST music/create](/docs/api-minimax-v1/post-minimax-music-create). === URL: https://useapi.net/blog/260826 === Document URL: https://useapi.net/blog/260826 --- layout: blog_post title: "Google Flow: Omni 1.1 Flash — 360p tier, first + last frames, and a new upscaler" description: "Four demos generated through the Google Flow API v1 on Omni 1.1 Flash: a 10s pigeon-POV dive off the Eiffel Tower, a two-voice R2V scene, a V2V subject swap, and a 4-credit 360p clip taken to 1080p." parent: Blog nav_exclude: true nav_order: -260826 --- ## Table of contents ## Omni 1.1 Flash on the Google Flow API Google updated Gemini Omni Flash on August 26, 2026. The Flow interface now labels it **Omni 1.1 Flash**, and three things arrived with the rename: | What | How to reach it | |---|---| | A 360p output tier at roughly half the credits | `resolution: "360p"` on [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) | | First **and** last frame, previously Veo-only | `startImage` + `endImage` on `model: "omni-flash"` | | A 360p to 720p upscaler | `resolution: "720p"` on [POST /videos/upscale](/docs/api-google-flow-v1/post-google-flow-videos-upscale) | The `model` value stays `omni-flash`. It carries no version, so nothing you already run needs changing — the current label is readable as `displayName` on [GET /accounts/`email`](/docs/api-google-flow-v1/get-google-flow-accounts-email). Everything below was generated through the public [Google Flow API v1](/docs/api-google-flow-v1) on a single Google AI Pro account. Each demo shows the native output and the same clip after a free upscale, so you can judge what the upscaler actually does. --- ## Demo 1: a 10-second POV handoff Text-to-video, no references at all. The interesting part is asking for a camera handoff mid-shot — the camera starts as an observer at a café table, then becomes a bird and dives. Omni tends to cut rather than carry a move like that unless the transition is spelled out, so the prompt names it explicitly. Shot in portrait at 10 seconds, which is the longest clip Omni produces and the shape social platforms want. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos">POST /videos</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'model="omni-flash"' \ --form 'aspectRatio="portrait"' \ --form 'duration="10"' \ --form 'prompt="Two young women sit at a small café table on the top deck of the Eiffel Tower, laughing over coffee and a slice of cake, Paris spread out gold and hazy behind them. A pigeon lands on the railing beside them and tilts its head — and the camera becomes the bird: it drops off the rail and dives, the tower'\''s iron latticework rushing past, the Champ de Mars swinging up to meet it, until it levels out and skims low over the gravel path between the trees, weaving past strolling Parisians. Their chatter and laughter rise and fall, cups clink, an accordion plays somewhere below. One continuous shot, no cuts."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 260px;max-width:300px;margin:0"> <video poster="https://media.useapi.net/blog/2026-08-26-260826/01-eiffel-pigeon-pov-omni-1.1-flash-720p-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/blog/2026-08-26-260826/01-eiffel-pigeon-pov-omni-1.1-flash-720p.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em"><strong>720p</strong> — as generated (15 credits)</figcaption> </figure> <figure style="flex:1 1 260px;max-width:300px;margin:0"> <video poster="https://media.useapi.net/blog/2026-08-26-260826/01-eiffel-pigeon-pov-omni-1.1-flash-1080p-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/blog/2026-08-26-260826/01-eiffel-pigeon-pov-omni-1.1-flash-1080p.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em"><strong>1080p</strong> — after upscale (free)</figcaption> </figure> </div> Audio is generated with the video, not added afterwards. The café ambience, the accordion and the wind on the dive all come out of the same request. --- ## Demo 2: two reference images and two voices Reference-to-video with an image supplying the subject's likeness, a second image supplying a prop, and two voice presets driving a short exchange. The references are placed with [inline `@`-mentions](/blog/260609) so each one is anchored to a specific noun rather than left to positional inference. Note what the prompt does *not* say: it never describes the woman's appearance or the cake. Identity comes from the references. ### Source references <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/blog/2026-08-26-260826/02-train-cavalier-reference-lady.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/blog/2026-08-26-260826/02-train-cavalier-reference-lady.jpg" alt="Portrait used as the subject likeness reference" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em"><strong>Subject</strong> — <code>referenceImage_1</code> (<code>@referenceImage_1</code> in the prompt)</figcaption> </figure> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/blog/2026-08-26-260826/02-train-cavalier-reference-cake.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/blog/2026-08-26-260826/02-train-cavalier-reference-cake.png" alt="Cheesecake used as the prop reference" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em"><strong>Prop</strong> — <code>referenceImage_2</code> (<code>@referenceImage_2</code> in the prompt)</figcaption> </figure> </div> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos">POST /videos</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'model="omni-flash"' \ --form 'aspectRatio="portrait"' \ --form 'duration="8"' \ --form 'referenceImage_1="user:1234-email:…-image:6faaf4d8-…"' \ --form 'referenceImage_2="user:1234-email:…-image:e45eb0e8-…"' \ --form 'referenceAudio_1="charon"' \ --form 'referenceAudio_2="aoede"' \ --form 'prompt="@referenceImage_1 as a late-1800s European aristocrat in a high-necked lace gown with pearl drops, sitting alone at a polished table in the dining car of a luxury steam train. A slice of @referenceImage_2 on fine china rests in front of her and she lifts a forkful to her lips. Warm brass lamps, white linen, the carriage swaying gently. She glances up to the window, where sunlit rural French fields roll past — and a dashing cavalier in a red riding coat gallops alongside the train on a chestnut horse, sweeping off his hat to her. Over the rush of wind and rails he calls (with the first voice): \"Bonjour, my lady!\" She smiles behind her hand and answers (with the second voice): \"You will tire that poor horse, monsieur.\" Warm film grain, the clatter of wheels on track and a distant whistle underneath."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 260px;max-width:300px;margin:0"> <video poster="https://media.useapi.net/blog/2026-08-26-260826/02-train-cavalier-omni-1.1-flash-720p-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/blog/2026-08-26-260826/02-train-cavalier-omni-1.1-flash-720p.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em"><strong>720p</strong> — as generated (12 credits)</figcaption> </figure> <figure style="flex:1 1 260px;max-width:300px;margin:0"> <video poster="https://media.useapi.net/blog/2026-08-26-260826/02-train-cavalier-omni-1.1-flash-1080p-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/blog/2026-08-26-260826/02-train-cavalier-omni-1.1-flash-1080p.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em"><strong>1080p</strong> — after upscale (free)</figcaption> </figure> </div> The `(with the first voice)` and `(with the second voice)` markers are what bind a preset to a speaker. Without them the model picks arbitrarily. `charon` and `aoede` were chosen by ear — Google publishes tone descriptors for the 30 presets but no gender, so preview them at `https://www.gstatic.com/aitestkitchen/voices/samples/<Name>.wav` before casting a scene. --- ## Demo 3: replacing the subject of an existing clip Video-to-video edit. Two inputs go in together: the source clip as `referenceVideo_1`, and an image as `referenceImage_1` supplying a new subject to drop into the existing motion. The instruction is to change who the person is while leaving the performance alone. This combination is what separates a subject swap from a style transfer — an edit with no image reference restyles the scene, an edit with one replaces what is in it. ### Source clip and reference <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 220px;max-width:260px;margin:0"> <video poster="https://media.useapi.net/blog/2026-08-26-260826/03-subject-swap-source-clip-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/blog/2026-08-26-260826/03-subject-swap-source-clip.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em"><strong>Source clip</strong> — <code>referenceVideo_1</code> (uploaded via <a href="/docs/api-google-flow-v1/post-google-flow-assets-email"><code>POST /assets/email</code></a>)</figcaption> </figure> <figure style="flex:1 1 180px;max-width:200px;margin:0"> <a href="https://media.useapi.net/blog/2026-08-26-260826/03-subject-swap-reference-character.jpg" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/blog/2026-08-26-260826/03-subject-swap-reference-character.jpg" alt="Illustrated character used as the replacement subject" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em"><strong>New subject</strong> — <code>referenceImage_1</code> (<code>@referenceImage_1</code> in the prompt)</figcaption> </figure> </div> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos">POST /videos</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'model="omni-flash"' \ --form 'aspectRatio="landscape"' \ --form 'referenceVideo_1="user:1234-email:…-video:6087a39d-…"' \ --form 'referenceImage_1="user:1234-email:…-image:6faaf4d8-…"' \ --form 'prompt="Replace the woman in the video with @referenceImage_1. Keep her original pose, head movement, camera framing and the plain studio background exactly as they are — change only who she is."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 300px;max-width:380px;margin:0"> <video poster="https://media.useapi.net/blog/2026-08-26-260826/03-subject-swap-omni-1.1-flash-720p-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/blog/2026-08-26-260826/03-subject-swap-omni-1.1-flash-720p.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em"><strong>720p</strong> — as generated (20 credits)</figcaption> </figure> <figure style="flex:1 1 300px;max-width:380px;margin:0"> <video poster="https://media.useapi.net/blog/2026-08-26-260826/03-subject-swap-omni-1.1-flash-1080p-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/blog/2026-08-26-260826/03-subject-swap-omni-1.1-flash-1080p.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em"><strong>1080p</strong> — after upscale (free)</figcaption> </figure> </div> The edit takes no `duration`. Output length comes from the input trim window, which defaults to the uploaded clip and is set explicitly with `startFrameIndex_1` and `endFrameIndex_1` on a 24 fps timeline capped at 240 frames. --- ## Demo 4: iterate at 360p, finish at 1080p The 360p tier is the practical reason to care about this release. A 4-second clip costs 4 credits instead of 7, and it renders faster — two 4-second clips in the same run came back in 35 seconds at 360p and 45 at 720p. That makes 360p the right place to iterate on wording, then spend the credits once you like the result. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos">POST /videos</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'model="omni-flash"' \ --form 'resolution="360p"' \ --form 'duration="4"' \ --form 'prompt="An astronaut'\''s glove drifts into frame against the curve of the Earth, sunrise flaring white off the visor as the terminator line creeps across the Pacific below. Slow weightless rotation, the station hull passing beneath. Almost silent — steady breathing inside the helmet and the soft tick of a suit radio."' ``` </details> Then hand the result straight to the upscaler. A 360p clip can go to 720p, and it can also go directly to 1080p — both are free on a paid plan. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos-upscale">POST /videos/upscale</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos/upscale' \ --header 'Authorization: Bearer user:1234-…' \ --form 'mediaGenerationId="user:1234-email:…-video:82e432a8-…"' \ --form 'resolution="1080p"' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 300px;max-width:380px;margin:0"> <video poster="https://media.useapi.net/blog/2026-08-26-260826/04-orbit-sunrise-omni-1.1-flash-360p-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/blog/2026-08-26-260826/04-orbit-sunrise-omni-1.1-flash-360p.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em"><strong>360p</strong> — as generated, 640×360 (4 credits)</figcaption> </figure> <figure style="flex:1 1 300px;max-width:380px;margin:0"> <video poster="https://media.useapi.net/blog/2026-08-26-260826/04-orbit-sunrise-360p-upscaled-to-1080p-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/blog/2026-08-26-260826/04-orbit-sunrise-360p-upscaled-to-1080p.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em"><strong>1080p</strong> — after upscale, 1920×1080 (free)</figcaption> </figure> </div> An upscaled 360p clip is not the same picture as one generated at 720p, so this is a drafting workflow rather than a free lunch. For a clip that matters, generate at 720p. --- ## What the four demos cost The four demos above cost 51 credits on a Google AI Pro plan, which is 1,000 Flow credits a month. The full test run they came from — eight generations across both resolutions and every mode — came to 84. | Demo | Mode | Credits | |---|---|---| | 1 — Eiffel POV, 10s portrait | T2V | 15 | | 2 — train cavalier, 8s portrait | R2V, 2 images + 2 voices | 12 | | 3 — subject swap | V2V edit | 20 | | 4 — orbit sunrise, 4s at 360p | T2V | 4 | | Every upscale above | 1080p | 0 | Full per-tier costs are in the [credit table](/docs/api-google-flow-v1), and the per-mode limits are under [Model Capabilities](/docs/api-google-flow-v1/post-google-flow-videos#model-capabilities). === URL: https://useapi.net/blog/260902 === Document URL: https://useapi.net/blog/260902 --- layout: blog_post title: "Google Flow: Extend Omni 1.1 Flash Videos — UGC Talking Head" description: "How to extend an Omni 1.1 Flash video through the Google Flow API v1 the way the Flow editor does it, chained V2V edits with the next line each time, and keep the joins invisible. A 10-second UGC talking head from three 4-second clips, all API." parent: Blog nav_exclude: true nav_order: -260902 --- ## Table of contents ## Extending a clip that has no extend endpoint [POST /videos/extend](/docs/api-google-flow-v1/post-google-flow-videos-extend) is Veo-only. The way the Flow editor extends an Omni 1.1 Flash clip is a video-to-video edit: the clip goes back in as `referenceVideo_1`, the prompt keeps the person, the framing and the mannerisms and gives them the next line, and each output becomes the next input. A customer showed us that workflow, and it is exactly the request the API already makes for a V2V edit. The catch is the join. Two takes cut together show a small jump at the cut, and this post is about the one precaution, taken at the very first clip, that makes the joins invisible. Everything runs through the public [Google Flow API v1](/docs/api-google-flow-v1), nothing is processed locally. The format this suits best is UGC, the user-generated-content style of one person talking to a phone camera that fills social feeds and ad libraries. Here is a 10-second UGC talking head built from one still and three 4-second Omni clips on a Google AI Pro account: <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 260px;max-width:320px;margin:0"> <video poster="https://media.useapi.net/blog/2026-09-02-260902/05-ugc-extended-lively-trimmed-10s-concatenated-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/blog/2026-09-02-260902/05-ugc-extended-lively-trimmed-10s-concatenated.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em"><strong>The result</strong> — 10 seconds, three clips, no visible join (47 credits in total)</figcaption> </figure> </div> Every step below is the real request that produced it, and every clip is the real output. --- ## Why the seed matters An edit replays its source: same length, same motion, same first and last frames. So every clip in the chain starts on the seed's first frame and ends on the seed's last frame, and if those two frames differ, every cut shows the difference. Make them the same frame, one still as both `startImage` and `endImage`, and every cut lands on it. --- ## Step 1: one still of the presenter A single image from [POST /images](/docs/api-google-flow-v1/post-google-flow-images), portrait, at rest, looking into the lens, hands in her lap. This frame becomes both ends of every clip, so it should be a pose she can naturally return to. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'aspectRatio="9:16"' \ --form 'count="1"' \ --form 'prompt="A young woman in a cozy oatmeal knit sweater sits on a bright living-room sofa facing the camera like a vlogger about to speak, waist-up, centered, soft window daylight, hands resting in her lap, a small closed-mouth smile, looking straight into the lens. Photoreal, phone-camera look, full frame, no text, no border."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:12px;margin-top:8px"> <figure style="flex:1 1 200px;max-width:220px;margin:0"> <a href="https://media.useapi.net/blog/2026-09-02-260902/01-ugc-still-nano-banana-2-lite.png" target="_blank" rel="noopener noreferrer"><img src="https://media.useapi.net/blog/2026-09-02-260902/01-ugc-still-nano-banana-2-lite.png" alt="The presenter at rest, used as the first and last frame of the seed clip" style="width:100%;border-radius:8px"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em"><strong>The still</strong> — Nano Banana 2 Lite (0 credits)</figcaption> </figure> </div> The response carries the image's `mediaGenerationId` under `media[0].image.generatedImage`. --- ## Step 2: the seed clip, first frame equals last frame Omni's first-plus-last-frame mode with the same still in both slots. The prompt gives the first line, asks for real movement in the middle, leaning in, both hands, a head tilt, a laugh, and says she begins and ends on this frame with a quiet beat on each side. The movement is free, only the two ends are pinned. Checked afterwards, the seed's first and last frames are as alike as any two neighbouring frames inside the clip. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos">POST /videos</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'model="omni-flash"' \ --form 'aspectRatio="portrait"' \ --form 'duration="4"' \ --form 'resolution="720p"' \ --form 'startImage="user:1234-email:…-image:01d1e6ff-…"' \ --form 'endImage="user:1234-email:…-image:01d1e6ff-…"' \ --form 'prompt="She talks straight to the camera like an animated vlogger: she leans in toward the lens as she starts, gestures with both hands, tilts her head, raises her eyebrows and laughs once, shifting on the sofa as she talks, with a warm friendly voice. She begins and ends exactly on this frame: hands resting in her lap, a small smile, looking into the lens, with a short quiet beat before she speaks and another after she settles back into it. She says: \"Okay, I finally did the lighthouse trail this weekend.\" Natural room tone, no music."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 220px;max-width:260px;margin:0"> <video poster="https://media.useapi.net/blog/2026-09-02-260902/02-ugc-seed-lively-4s-first-equals-last-omni-1.1-flash-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/blog/2026-09-02-260902/02-ugc-seed-lively-4s-first-equals-last-omni-1.1-flash.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em"><strong>Clip 1</strong> — 4 seconds, 43 seconds to generate (7 credits)</figcaption> </figure> </div> --- ## Step 3: extend it The same endpoint, now with the seed as `referenceVideo_1`. This is the captured editor prompt with one sentence added: she begins and ends exactly as the video does. The first paragraph pins what must not change, the quoted line is the new content, and the last sentence keeps hands empty and strips any captions. No `duration` is sent, because an edit takes its length from the input. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos">POST /videos</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'model="omni-flash"' \ --form 'aspectRatio="portrait"' \ --form 'resolution="720p"' \ --form 'referenceVideo_1="user:1234-email:…-video:e3d8ce7f-…"' \ --form 'prompt="Extend this video seamlessly. Same person, same outfit, same background, same framing and camera. Keep her movement style, energy, expressions, and mannerisms exactly like the video — the same animated, expressive way she talks with her hands, leaning in, tilting her head and shifting on the sofa. She begins and ends exactly as the video does: hands resting in her lap, looking at the camera with a small smile, a short quiet beat before she speaks and another after she settles back. She keeps talking naturally to the camera. What she says: \"Forty minutes up, and the view is unreal.\" She is not holding any objects — nothing in her hands. Remove all text, captions, buttons, and watermarks from the screen."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 220px;max-width:260px;margin:0"> <video poster="https://media.useapi.net/blog/2026-09-02-260902/03-ugc-extend-1-lively-4s-omni-1.1-flash-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/blog/2026-09-02-260902/03-ugc-extend-1-lively-4s-omni-1.1-flash.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em"><strong>Clip 2</strong> — 4 seconds, 66 seconds to generate (20 credits)</figcaption> </figure> </div> Same woman, same sweater, same sofa, same light, same voice. New line, and it opens and closes on the still. --- ## Step 4: extend again Clip 2 goes in as `referenceVideo_1` and only the quoted line changes. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos">POST /videos</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos' \ --header 'Authorization: Bearer user:1234-…' \ --form 'email="your@email.com"' \ --form 'model="omni-flash"' \ --form 'aspectRatio="portrait"' \ --form 'resolution="720p"' \ --form 'referenceVideo_1="user:1234-email:…-video:ce28ccf7-…"' \ --form 'prompt="Extend this video seamlessly. Same person, same outfit, same background, same framing and camera. Keep her movement style, energy, expressions, and mannerisms exactly like the video — the same animated, expressive way she talks with her hands, leaning in, tilting her head and shifting on the sofa. She begins and ends exactly as the video does: hands resting in her lap, looking at the camera with a small smile, a short quiet beat before she speaks and another after she settles back. She keeps talking naturally to the camera. What she says: \"Go early, the parking fills up by nine. Bye!\" She is not holding any objects — nothing in her hands. Remove all text, captions, buttons, and watermarks from the screen."' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 220px;max-width:260px;margin:0"> <video poster="https://media.useapi.net/blog/2026-09-02-260902/04-ugc-extend-2-lively-4s-omni-1.1-flash-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/blog/2026-09-02-260902/04-ugc-extend-2-lively-4s-omni-1.1-flash.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em"><strong>Clip 3</strong> — 4 seconds, 55 seconds to generate (20 credits)</figcaption> </figure> </div> --- ## Step 5: join them Concatenate takes the three ids in order and returns the joined file as base64. The trims matter here. The quiet beat that pins each clip to the still also shows up at a join: measured on these clips, she holds the still for about half a second before she speaks and takes about a third of a second to settle back into it at the end, so a plain join stacks the two into a freeze. `trimEnd: 0.375` on clips 1 and 2 and `trimStart: 0.458` on clips 2 and 3 cut both holds down to two frames each side of the cut. Concatenate reads each clip's real length, so nothing else is lost. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos-concatenate">POST /videos/concatenate</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos/concatenate' \ --header 'Authorization: Bearer user:1234-…' \ --header 'Content-Type: application/json' \ --data '{ "media": [ { "mediaGenerationId": "user:1234-email:…-video:e3d8ce7f-…", "trimEnd": 0.375 }, { "mediaGenerationId": "user:1234-email:…-video:ce28ccf7-…", "trimStart": 0.458, "trimEnd": 0.375 }, { "mediaGenerationId": "user:1234-email:…-video:9feb862d-…", "trimStart": 0.458 } ] }' ``` </details> <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 260px;max-width:320px;margin:0"> <video poster="https://media.useapi.net/blog/2026-09-02-260902/05-ugc-extended-lively-trimmed-10s-concatenated-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/blog/2026-09-02-260902/05-ugc-extended-lively-trimmed-10s-concatenated.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em"><strong>Joined</strong> — 10.33 seconds, 720×1280 (0 credits)</figcaption> </figure> </div> Checked frame by frame, the change across each join is smaller than the change between two ordinary neighbouring frames, the longest hold across a join is three frames, and the biggest changes anywhere in the file are her own gestures. She finishes one line, settles for an eighth of a second, and starts the next. --- ## What to expect * The gestures repeat. Every edit replays the seed's movement over its own seconds, and on a talking head that is what takes look like. It is also what makes the joins work. * Movement is free. A first version of this demo kept her almost still. This one asks the seed for leaning in, both hands, a head tilt and a laugh, and the edits inherit all of it. She moves a lot more and the joins stayed clean, because only the two ends of each clip are pinned to the still. Put the energy in the seed prompt and keep the quiet beat on both sides. * Trim the beats at the joins. The beats are what pin the ends, and untrimmed they read as a freeze. Half a second off the start of each edit and a third of a second off the end of each clip but the last is what this run needed. Measure your own seed once and reuse the numbers, the edits inherit its timing. * The voice carries. An edit keeps the voice of its source, so the whole run sounds like one person without any audio reference. * Keep the lines short. An edit inherits the seed's timing, so a line that runs long is cut off rather than sped up. The last clip here was asked for "Go early, the parking fills up by nine. Bye!" and the "Bye!" did not make it. About eight words per 4-second clip. * Say what the frame is. An earlier run with "phone-video framing" in the prompt produced a drawn phone bezel on the opening frame. "Full frame, no text, no border" in the still's prompt and the edits' "remove all text, captions, buttons, and watermarks" line keep the picture clean. * The presenter is invented. Google's V2V moderation is stricter with real, identifiable people, and a clip that contains someone's actual speech can be refused outright. Start from your own generated or original footage. --- ## What it cost | Step | Mode | Credits | |---|---|---| | The still, 9:16 | Nano Banana 2 Lite | 0 | | Clip 1, 4s seed | I2V, first + last frame | 7 | | Clip 2, extend | V2V edit | 20 | | Clip 3, extend | V2V edit | 20 | | Concatenate | — | 0 | | **Total** | | **47** | A 4-second Omni clip costs 7 credits at 720p whether it is made from text, from an image, or from references. An edit costs 20 credits at 720p, or 10 at 360p, no matter how long the clip is. Full prices are in the [credit table](/docs/api-google-flow-v1). === URL: https://useapi.net/blog/260905 === Document URL: https://useapi.net/blog/260905 --- layout: blog_post title: "Mureka: Rewrite One Section of a Song" description: "Mureka API v1 adds POST /music/edit — pick a millisecond range inside a finished song, hand it new lyrics, and get the whole track back with only that stretch re-sung. 20 credits." parent: Blog nav_exclude: true nav_order: -260905 --- ## Table of contents ## Rewriting one section of a finished song [Mureka API v1](/docs/api-mureka-v1) can now rewrite one section of a song you have already generated. Pick a range in milliseconds, give it new words, and the rest of the track comes back untouched: [POST /music/edit](/docs/api-mureka-v1/post-mureka-music-edit). Until now the only way to change a finished song was [POST /music/regenerate](/docs/api-mureka-v1/post-mureka-music-regenerate), which rewrites everything from a start point to the end. Editing is surgical, and it can hold the melody while the words underneath it change. ## The demo A 1920s vaudeville patter song about a man with an extensive list of places he is no longer welcome. Generated once with `V9.5`, then edited once. The chorus at **0:32** is the original. The chorus at **1:19** is the one we rewrote — same tune, same voice, an entirely different alphabet. **Original** — the B's <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-mureka-v1/post-mureka-music-create-advanced">POST /music/create-advanced</a></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-advanced' \ --header 'Authorization: Bearer user:1234-…' \ --form 'model="V9.5"' \ --form 'title="Barred"' \ --form 'vocal_gender="male"' \ --form 'desc="1920s hot jazz, vaudeville patter song, banjo, muted trumpet, stride piano, upright bass, brushed snare, brisk and comic, crisp theatrical diction, upbeat"' \ --form 'lyrics="[Verse] I have been asked to leave a number of establishments Usually politely, occasionally not I keep a little notebook of my accomplishments And frankly it'\''s a rather impressive lot [Chorus] I'\''m barred from the bakery, barred from the bank Barred from the ballroom, and I'\''ve only got myself to thank Barred from the bandstand, barred from the bar And that'\''s just the ones beginning with B so far [Verse] The magistrate has memorised my overcoat The barman keeps my photograph behind the till [Chorus] I'\''m barred from the bakery, barred from the bank Barred from the ballroom, and I'\''ve only got myself to thank Barred from the bandstand, barred from the bar And that'\''s just the ones beginning with B so far [Outro] There are twenty-six letters and I'\''m working through them all Do let me know if you hear of anywhere still open"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-09-05-260905/mureka-edit-barred-original.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> **Edited** — the C's, from 1:19 <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-mureka-v1/post-mureka-music-edit">POST /music/edit</a></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/edit' \ --header 'Authorization: Bearer user:1234-…' \ --form 'song_id="user:1234-mureka:12345678901234-song:159302587383810"' \ --form 'start_milliseconds="79000"' \ --form 'end_milliseconds="95160"' \ --form 'keep_melody="true"' \ --form 'lyrics="I'\''m barred from the chemist, barred from the choir Barred from the cinema for setting it on fire Barred from the casino, barred from the cafe And that'\''s just the C'\''s, I'\''ll get to the D'\''s on Thursday"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-09-05-260905/mureka-edit-barred-keep-melody.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> The first chorus still lists the B's. Only the range we asked for moved, and it moved without disturbing the melody, the arrangement or the timing — the track is 174,710 ms before and 174,766 ms after. ## Finding the range The bounds come from [GET /music/`song_id`](/docs/api-mureka-v1/get-mureka-music-song_id), where every sung line carries its own `start` and `end`: ```json { "user_input_tag": "[Chorus]", "start": 79000, "end": 95160, "rows": [ { "start": 79000, "end": 82760, "text": "I'm barred from the bakery, barred from the bank" }, { "start": 83760, "end": 87400, "text": "Barred from the ballroom, and I've only got myself to thank" }, { "start": 88320, "end": 92600, "text": "Barred from the bandstand, barred from the bar" }, { "start": 92600, "end": 95160, "text": "And that's just the ones beginning with B so far" } ] } ``` Take the section's `start` and `end` and that is your range. Mureka treats it as a hint and may widen it to a musical boundary — here it went 56 ms past, in other runs a few seconds — so read `regenerate_from` and `regenerate_to` on the returned song to see what it actually re-sang. You can also leave `lyrics` out entirely. The API then reuses the lines the song already sings inside the range, which re-rolls the performance of a section without changing a word. ## Keeping the melody, or not `keep_melody` defaults to `true`, which is what makes the demo above a like-for-like swap. Set it to `false` and Mureka writes a new tune for the section instead: <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-mureka-v1/post-mureka-music-edit">POST /music/edit</a> with <code>keep_melody: false</code></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/edit' \ --header 'Authorization: Bearer user:1234-…' \ --form 'song_id="user:1234-mureka:12345678901234-song:159302587383810"' \ --form 'start_milliseconds="79000"' \ --form 'end_milliseconds="95160"' \ --form 'keep_melody="false"' \ --form 'lyrics="I'\''m barred from the chemist, barred from the choir Barred from the cinema for setting it on fire Barred from the casino, barred from the cafe And that'\''s just the C'\''s, I'\''ll get to the D'\''s on Thursday"' ``` </details> <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-09-05-260905/mureka-edit-barred-new-melody.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Worth knowing before you reach for it: a new melody has its own timing. The same four lines came back six seconds shorter, everything after them shifted earlier, and the track went from 2:55 to 2:49. With `keep_melody: true` the duration barely moves. If anything downstream depends on the length, re-read `duration_milliseconds` rather than assuming it survived. ## What it costs An edit costs 20 credits and returns one song. Credits come off when Mureka accepts the request, not when the song finishes. Editing needs an active paid Mureka plan. Without one the call returns `403 low vip level (6335)`, the same gate [POST /music/regenerate](/docs/api-mureka-v1/post-mureka-music-regenerate) sits behind. Full parameters, responses and a live Try It console: [POST /music/edit](/docs/api-mureka-v1/post-mureka-music-edit). === URL: https://useapi.net/blog/260907 === Document URL: https://useapi.net/blog/260907 --- layout: blog_post title: "Dreamina: 3-Minute Clips and Video Edit" description: "Seedance 2.5 on the Dreamina API gains two modes — long video up to 180 seconds, and an edit that re-cuts an existing clip. A full walkthrough from a stock dance video to a 35-second finished scene, with every request and every credit cost." parent: Blog nav_exclude: true nav_order: -260907 --- ## Long video and edit on Seedance 2.5 September 7, 2026 Two new modes are live on `seedance-2.5` at [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos), on both the US and CA regions. **Long video** raises the ceiling from 30 seconds to 180. **Edit** takes a video you already have and re-cuts it — same motion, same framing, new content. This post runs both end to end on one stock clip. Every request below is the real one, every video is the real output, and every credit figure is what the account was actually charged. --- ## The starting material One stock clip of a woman dancing against a corrugated shutter. 21.3 seconds, 720x1280, 30fps — the player below shows it downscaled for the web. Nothing about it was generated. It is the fixed input both modes work from. <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 240px;max-width:280px;margin:0"> <video poster="https://media.useapi.net/blog/2026-09-07-260907/dreamina-edit-source-21s-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/blog/2026-09-07-260907/dreamina-edit-source-21s.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em"><strong>The source</strong> — 21.3s, untouched stock footage</figcaption> </figure> </div> Upload it once and reuse the reference for both runs. Video uploads take the raw bytes with a matching `Content-Type`: ```bash curl --location 'https://api.useapi.net/v1/dreamina/assets/CA:you@example.com' \ --header 'Authorization: Bearer user:1234-…' \ --header 'Content-Type: video/mp4' \ --data-binary '@girl-dancing-21s.mp4' ``` ```json { "assetRef": "CA:you@example.com-video:w720:h1280:s7279723:d21300-vid:v10762g50003dafirrvog65js2v7k7qg" } ``` The `d21300` in that reference is the duration in milliseconds. It matters — it is what the API uses to bill the job and to check the source against the edit mode's 4-30 second window. --- ## Run one: edit Edit is selected by one new parameter, `editVideoRef`. Point it at an uploaded video and Seedance re-cuts that video rather than generating a fresh one. We wanted a wardrobe change, so we generated the two garments as flat product shots on the [Google Flow API](/docs/api-google-flow-v1) — plain background, no mannequin, nothing for the model to confuse for context: <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 200px;max-width:240px;margin:0"> <img src="https://media.useapi.net/blog/2026-09-07-260907/dreamina-edit-ref-propeller-hat.jpg" style="width:100%;border-radius:8px"> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">Reference 1 — propeller beanie</figcaption> </figure> <figure style="flex:1 1 200px;max-width:240px;margin:0"> <img src="https://media.useapi.net/blog/2026-09-07-260907/dreamina-edit-ref-polkadot-shorts.png" style="width:100%;border-radius:8px"> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">Reference 2 — polka dot shorts</figcaption> </figure> </div> Both go up through [POST /assets](/docs/api-dreamina-v1/post-dreamina-assets-account) the same way, then ride along as ordinary omni references, mentioned in the prompt by `@image1` and `@image2`: ```bash curl --location 'https://api.useapi.net/v1/dreamina/videos' \ --header 'Authorization: Bearer user:1234-…' \ --form 'model="seedance-2.5"' \ --form 'resolution="480p"' \ --form 'editVideoRef="CA:you@example.com-video:w720:h1280:s7279723:d21300-vid:v10762…"' \ --form 'omni_1_imageRef="CA:you@example.com-image:w1024:h1024:s637405-uri:tos-…propeller-hat"' \ --form 'omni_2_imageRef="CA:you@example.com-image:w1024:h1024:s661090-uri:tos-…polkadot-shorts"' \ --form 'prompt="make her wear the rainbow striped propeller beanie from @image1 and the neon green polka dot shorts from @image2, keep her dancing exactly as she is and keep the background unchanged"' ``` There is no `duration` and no `ratio` in that request, and neither is accepted. The output inherits both from the source, which is the whole point of the mode — you are re-cutting a specific video, not describing a new one. <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 240px;max-width:280px;margin:0"> <video poster="https://media.useapi.net/blog/2026-09-07-260907/dreamina-edit-source-21s-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/blog/2026-09-07-260907/dreamina-edit-source-21s.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em"><strong>Before</strong></figcaption> </figure> <figure style="flex:1 1 240px;max-width:280px;margin:0"> <video poster="https://media.useapi.net/blog/2026-09-07-260907/dreamina-seedance-25-video-edit-21sec-480p-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/blog/2026-09-07-260907/dreamina-seedance-25-video-edit-21sec-480p.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em"><strong>After</strong> — 21.0s, 480x854 (756 credits)</figcaption> </figure> </div> Both garments transferred, and the dance is preserved move for move — sample the two clips at the same timestamps and she is in the same pose in both, against the same shutter, in the same light. That fidelity is what separates an edit from a generation that merely resembles the input. It also did something we did not ask for: her orange crop top came back as a skin-toned band. The prompt named two garments and said to leave everything else alone, and the model changed a third. If a specific element must survive an edit, name it explicitly as something to keep. --- ## Run two: long video Long video needs no new parameter at all. A `duration` above 30 can only be served by that mode, so asking for the duration is asking for the mode: ```json { "model": "seedance-2.5", "duration": 35, "prompt": "..." } ``` Anything from 31 to 180 seconds qualifies. Exactly 30 stays an ordinary generation, where it is valid and cheaper per second. For this run the brief was a scene that could not fit in 15 seconds: relocate her, then bring in two dancers one at a time, then end on a group hug. Three more Flow images supply the cast and the location: <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 170px;max-width:200px;margin:0"> <img src="https://media.useapi.net/blog/2026-09-07-260907/dreamina-longvideo-ref-robot-mascot.png" style="width:100%;border-radius:8px"> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">@image1 — robot mascot</figcaption> </figure> <figure style="flex:1 1 170px;max-width:200px;margin:0"> <img src="https://media.useapi.net/blog/2026-09-07-260907/dreamina-longvideo-ref-flamingo-mascot.png" style="width:100%;border-radius:8px"> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">@image2 — flamingo mascot</figcaption> </figure> <figure style="flex:1 1 170px;max-width:200px;margin:0"> <img src="https://media.useapi.net/blog/2026-09-07-260907/dreamina-longvideo-ref-theme-park.png" style="width:100%;border-radius:8px"> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">@image3 — the location</figcaption> </figure> </div> The source clip comes back as `omni_1_videoRef`, carrying her appearance and her actual dance rather than a description of one: ```bash curl --location 'https://api.useapi.net/v1/dreamina/videos' \ --header 'Authorization: Bearer user:1234-…' \ --form 'model="seedance-2.5"' \ --form 'resolution="480p"' \ --form 'duration="35"' \ --form 'ratio="9:16"' \ --form 'omni_1_videoRef="CA:you@example.com-video:w720:h1280:s7279723:d21300-vid:v10762…"' \ --form 'omni_1_imageRef="CA:you@example.com-image:…robot-mascot"' \ --form 'omni_2_imageRef="CA:you@example.com-image:…flamingo-mascot"' \ --form 'omni_3_imageRef="CA:you@example.com-image:…theme-park"' \ --form 'prompt="A continuous 35-second shot on a sunny movie studio theme park street. Take the woman dancing in @video1 — her exact appearance, outfit and dance moves — and place her in the location shown in @image3: the middle of a colourful empty street with pastel building facades, festive bunting strung overhead, tall palm trees and a wooden rollercoaster rising behind her. She dances continuously throughout. She dances alone at first. Then @image1, the fuzzy teal robot mascot with the boxy head and orange sneakers, dances into frame from the left and starts dancing beside her. A few seconds later @image2, the pink flamingo mascot in yellow boots, dances into frame from the right and joins them. All three dance together in a row. At the end the two mascots close in on either side and the three of them come together in a big happy group hug, laughing, as the shot holds. Bright natural daylight, warm saturated colours, camera slowly pushing in throughout. One continuous take, no cuts."' ``` <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 260px;max-width:300px;margin:0"> <video poster="https://media.useapi.net/blog/2026-09-07-260907/dreamina-seedance-25-longvideo-35sec-480p-poster.jpg" controls width="100%" style="border-radius:8px"> <source src="https://media.useapi.net/blog/2026-09-07-260907/dreamina-seedance-25-longvideo-35sec-480p.mp4" type="video/mp4"> </video> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em"><strong>35.07 seconds</strong>, 480x856, one take (1,680 credits)</figcaption> </figure> </div> Every beat landed in order: she starts alone far down an empty street, the robot arrives from the left, the flamingo from the right, and all three close into the hug as the camera finishes its push in. Her orange top survived this time, which the edit run did not manage. Writing a long prompt as a sequence of timed beats rather than one description is what makes the length usable. Ask for 35 seconds of "a woman dancing" and you get a longer clip of the same thing. --- ## What it costs Billed seconds are the output duration plus every reference video attached, rounded down to a whole second. Both runs landed on the predicted figure exactly: | Run | Billed seconds | Rate | Charged | |---|---|---|---| | Edit, 21.3s source at 480p | 21.3 output + 21.3 source = **42** | 18 | **756** | | Long video, 35s from a 21.3s reference | 35 output + 21.3 reference = **56** | 30 | **1,680** | Two things to plan around. An edit bills its source twice — once as the input, once as the output — because the source *is* the output. A 21-second edit is charged for 42 billed seconds. Long video is priced on its own scale, roughly 1.7x the ordinary rate at 480p on CA, and gets no reference-video discount. A full 180-second clip at 480p is around 5,400 credits before any reference is added. Full per-region rates are in the [cost calculator](/docs/start-here/setup-dreamina#cost-calculator). --- ## Notes from the two runs **Generation is slow at these lengths.** The 21-second edit took 13 minutes 30 seconds, the 35-second long video 17 minutes 33. Use a `replyUrl` webhook rather than polling, and set generous timeouts. **Reference images work best as flat product or full-body shots** on a plain background. The garments and both mascots were framed that way and transferred cleanly. The location reference was an ordinary wide photograph instead, and it carried across just as well, so the plain background matters for a subject you want lifted out, not for a scene you want matched. **Keep third-party property out of the prompt.** Seedance refuses recognisable IP as `fail_code 2053`, and it judges the finished video several minutes in rather than the prompt text. A failed generation is not charged, but a branded theme park would still have cost the full generation time before telling us. **Name what must not change.** The edit altered a garment the prompt never mentioned. Elements you need preserved should be stated as explicitly as the ones you want changed. --- Both modes are live now on [POST /videos](/docs/api-dreamina-v1/post-dreamina-videos) for every [useapi.net subscriber](/docs/subscription), on any Dreamina account in either region. See [Setup Dreamina](/docs/start-here/setup-dreamina) to connect one. Compare every Seedance 2.0 and 2.5 route and price: [Seedance 2.0 and 2.5 API Pricing](/docs/articles/seedance-2-api-pricing). The clips above are re-encoded to a lower bitrate for the web. Resolution, duration and the generated audio are unchanged from what the API returned. === URL: https://useapi.net/blog/261016 === Document URL: https://useapi.net/blog/261016 --- layout: blog_post title: "Mureka: Scarlett Sings \"This Is It\" — Characters, Remix and Sheet Music" description: "A cloned singer covers a Michael Jackson reference with new lyrics on V9.5 and O2, gets remixed into a torch ballad, and every take comes back as sheet music, all through the useapi.net Mureka API." parent: Blog nav_exclude: true nav_order: -261016 --- ## Table of contents ## One voice, any song October 16, 2026 [Mureka API v1](/docs/api-mureka-v1) can now do everything Mureka's own Custom page does with a cloned voice: * [Characters](/docs/api-mureka-v1/post-mureka-music-characters): turn a voice clip into a reusable singer, for free * [POST /music/create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced) takes the character, a reference track, a style and your lyrics in one call * [POST /music/remix](/docs/api-mureka-v1/post-mureka-music-remix): re-record a finished song in a new style * [POST /music/score](/docs/api-mureka-v1/post-mureka-music-score): sheet music (staff and numbered notation PDF, plus MusicXML) from a song or a YouTube link This post runs all of them on one song. Every request below is the real one, every player is the real output, and every file is downloadable. This is a non-commercial technology demo. The reference recording is Michael Jackson's "Who Is It", used only to show how the reference parameter works. The lyrics are new and original. Rights holders can ask us to take the post down at any time. ## The singer: Scarlett A 55-second clip of one female voice, uploaded once with [POST /files/vocal](/docs/api-mureka-v1/post-mureka-files-vocal): **The source voice** <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-10-16-261016/scarlett-voice.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-mureka-v1/post-mureka-files-vocal">POST /files/vocal</a> then <a href="/docs/api-mureka-v1/post-mureka-music-characters">POST /music/characters</a></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/files/vocal/?title=scarlett' \ --header 'Authorization: Bearer user:1234-…' \ --header 'Content-Type: audio/mpeg' \ --data-binary '@scarlett-voice.mp3' ``` ```json { "id": 11223344, "duration_milliseconds": 54308, "title": "scarlett", "source_type": 2 } ``` ```bash curl --location 'https://api.useapi.net/v1/mureka/music/characters' \ --header 'Authorization: Bearer user:1234-…' \ --form 'vocal_id="11223344"' \ --form 'name="Scarlett"' \ --form 'bio="A smoky, intimate female voice."' \ --form 'tags="Female, Smoky"' \ --form 'private="true"' ``` ```json { "id": 55667788, "name": "Scarlett", "bio": "A smoky, intimate female voice.", "tags": ["Female", "Smoky"], "avatar": "https://static-cos.mureka.ai/cos-prod/mureka/static/img/<id>.jpg" } ``` </details> Creating a character is free and instant, and the character is ready to sing right away. `private: true` keeps it off Mureka's public character gallery. ## The reference: "Who Is It" The reference is [Michael Jackson — Who Is It](https://www.youtube.com/watch?v=PfrV_6yWbEg): dark, tense, minor-key funk. [GET /files/youtube](/docs/api-mureka-v1/get-mureka-files-youtube) pulls the audio from the link, and a 30-second excerpt goes up as a reference track with [POST /files](/docs/api-mureka-v1/post-mureka-files): <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-mureka-v1/get-mureka-files-youtube">GET /files/youtube</a> then <a href="/docs/api-mureka-v1/post-mureka-files">POST /files</a></summary> ```bash curl 'https://api.useapi.net/v1/mureka/files/youtube/?url=https://www.youtube.com/watch?v=PfrV_6yWbEg' \ --header 'Authorization: Bearer user:1234-…' ``` ```json { "name": "Michael Jackson - Who Is It (Official Video - Upscaled)", "cos_url": "https://static-cos.mureka.ai/cos-prod/data/audio/<path>/<file>.mp3", "duration": 396179 } ``` ```bash curl --location 'https://api.useapi.net/v1/mureka/files/?title=This%20Is%20It%20reference&mood=dark&genre=funk&url=https://www.youtube.com/watch?v=PfrV_6yWbEg' \ --header 'Authorization: Bearer user:1234-…' \ --header 'Content-Type: audio/mpeg' \ --data-binary '@who-is-it-30s.mp3' ``` ```json { "id": 99887766, "duration_milliseconds": 30000, "title": "This Is It reference", "mood": "dark", "genre": "funk", "source_type": 1 } ``` </details> ## The cover: "This Is It" One call puts it all together: Scarlett as `character_id`, the excerpt as `ref_id`, a style in `desc`, and new lyrics written for the same tense mood. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-mureka-v1/post-mureka-music-create-advanced">POST /music/create-advanced</a> with the full lyrics</summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/create-advanced' \ --header 'Authorization: Bearer user:1234-…' \ --form 'model="V9.5"' \ --form 'title="This Is It"' \ --form 'character_id="55667788"' \ --form 'ref_id="99887766"' \ --form 'vocal_gender="female"' \ --form 'desc="dark minor-key funk pop, tight drums, slap bass, synth stabs, tense female vocal"' \ --form 'lyrics="[Verse] Static on the line at the edge of the night Every window'\''s dark but one burning light I hear the footsteps that I swore were gone Playing back the same old song [Pre-Chorus] Don'\''t you tell me it'\''s over, don'\''t you lie to my face I can feel you in the shadows, I can see you in this place [Chorus] This is it, this is it Every secret'\''s coming out This is it, this is it No more shadows, no more doubt [Verse] Lipstick on a letter that I never wrote Someone else'\''s perfume on my winter coat They say this city never sleeps alone Then who keeps calling, calling on my phone [Pre-Chorus] Don'\''t you tell me it'\''s over, don'\''t you lie to my face I can feel you in the shadows, I can see you in this place [Chorus] This is it, this is it Every secret'\''s coming out This is it, this is it No more shadows, no more doubt [Bridge] I gave you all my midnights You gave me all your lies Now the curtain'\''s falling And I see it in your eyes [Chorus] This is it, this is it Every secret'\''s coming out This is it, this is it No more shadows, no more doubt [Outro] This is it..."' ``` </details> Each call returns two songs. We picked one take from each model. **V9.5 — 3:23** <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-10-16-261016/this-is-it-v9-5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> **O2 — the same call with model O2, 3:21** <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-10-16-261016/this-is-it-o2.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> Both songs carry Mureka's control types for reference, vocal, style and character, so all four inputs went into each one. V9.5 costs 12 Mureka Gold per song and O2 costs 20. Each call took about 90 seconds and returned two songs. ## The remix: a torch ballad [POST /music/remix](/docs/api-mureka-v1/post-mureka-music-remix) takes the finished V9.5 take and re-records it in a new style. The lyrics carry over, and the title becomes "This Is It(Remix)". <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-mureka-v1/post-mureka-music-remix">POST /music/remix</a></summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/remix' \ --header 'Authorization: Bearer user:1234-…' \ --form 'song_id="user:1234-mureka:12345678901234-song:33445566"' \ --form 'desc="slow torch ballad, piano and strings, intimate female vocal"' ``` </details> **Remix — slow torch ballad, 3:29** <audio controls class="audio-player"> <source src="https://media.useapi.net/blog/2026-10-16-261016/this-is-it-remix-v9-5.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> A remix costs the same as a song. Add `async: true` and a `replyUrl` to get it by webhook instead of waiting. ## The sheet music [POST /music/score](/docs/api-mureka-v1/post-mureka-music-score) transcribes the main melody, the chords and the lyrics. It takes a `song_id`, a YouTube link or an uploaded file, answers in 10 to 20 seconds and costs 10 Mureka Gold. Click a page to open the full PDF. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-mureka-v1/post-mureka-music-score">POST /music/score</a>, from a song and from YouTube</summary> ```bash curl --location 'https://api.useapi.net/v1/mureka/music/score' \ --header 'Authorization: Bearer user:1234-…' \ --form 'song_id="user:1234-mureka:12345678901234-song:33445566"' ``` ```bash curl --location 'https://api.useapi.net/v1/mureka/music/score' \ --header 'Authorization: Bearer user:1234-…' \ --form 'url="https://www.youtube.com/watch?v=PfrV_6yWbEg"' ``` ```json { "title": "This Is It", "url": "https://static-cos.mureka.ai/cos-prod/skm/music-staff/20261017/<id>.zip" } ``` </details> <div style="display:flex;flex-wrap:wrap;gap:16px;margin-top:12px"> <figure style="flex:1 1 260px;max-width:340px;margin:0"> <a href="https://media.useapi.net/blog/2026-10-16-261016/this-is-it-v9-5-staff.pdf"><img src="https://media.useapi.net/blog/2026-10-16-261016/this-is-it-v9-5-staff-page1.png" alt="This Is It, V9.5 take, page 1 of 4" style="width:100%;border-radius:8px;background:#fff"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">"This Is It", V9.5 take — page 1 of 4</figcaption> </figure> <figure style="flex:1 1 260px;max-width:340px;margin:0"> <a href="https://media.useapi.net/blog/2026-10-16-261016/who-is-it-staff.pdf"><img src="https://media.useapi.net/blog/2026-10-16-261016/who-is-it-staff-page1.png" alt="Who Is It, from the YouTube link, page 1 of 8" style="width:100%;border-radius:8px;background:#fff"></a> <figcaption style="text-align:center;margin-top:6px;font-size:0.85em">"Who Is It", from the YouTube link — page 1 of 8</figcaption> </figure> </div> Every file, one link each: **"This Is It", V9.5** · [staff PDF](https://media.useapi.net/blog/2026-10-16-261016/this-is-it-v9-5-staff.pdf) · [numbered notation PDF](https://media.useapi.net/blog/2026-10-16-261016/this-is-it-v9-5-numbered-notation.pdf) · [MusicXML](https://media.useapi.net/blog/2026-10-16-261016/this-is-it-v9-5-staff.musicxml) **"This Is It", O2** · [staff PDF](https://media.useapi.net/blog/2026-10-16-261016/this-is-it-o2-staff.pdf) · [numbered notation PDF](https://media.useapi.net/blog/2026-10-16-261016/this-is-it-o2-numbered-notation.pdf) · [MusicXML](https://media.useapi.net/blog/2026-10-16-261016/this-is-it-o2-staff.musicxml) **"This Is It", remix** · [staff PDF](https://media.useapi.net/blog/2026-10-16-261016/this-is-it-remix-v9-5-staff.pdf) · [numbered notation PDF](https://media.useapi.net/blog/2026-10-16-261016/this-is-it-remix-v9-5-numbered-notation.pdf) · [MusicXML](https://media.useapi.net/blog/2026-10-16-261016/this-is-it-remix-v9-5-staff.musicxml) **"Who Is It", from YouTube** · [staff PDF](https://media.useapi.net/blog/2026-10-16-261016/who-is-it-staff.pdf) · [numbered notation PDF](https://media.useapi.net/blog/2026-10-16-261016/who-is-it-numbered-notation.pdf) · [MusicXML](https://media.useapi.net/blog/2026-10-16-261016/who-is-it-staff.musicxml) The MusicXML opens in MuseScore, Sibelius, Finale, Dorico and most other notation software. ## What it cost | Step | Endpoint | Mureka Gold | |---|---|---| | Upload the voice, create the character | POST /files/vocal, POST /music/characters | free | | Import the reference | GET /files/youtube, POST /files | free | | Cover on V9.5, two songs | POST /music/create-advanced | 24 | | Cover on O2, two songs | POST /music/create-advanced | 40 | | Remix, two songs | POST /music/remix | 24 | | Sheet music, four sources | POST /music/score | 40 | 128 Mureka Gold in total. Full parameters, responses and a live Try It console for each endpoint: [characters](/docs/api-mureka-v1/post-mureka-music-characters), [create-advanced](/docs/api-mureka-v1/post-mureka-music-create-advanced), [remix](/docs/api-mureka-v1/post-mureka-music-remix), [score](/docs/api-mureka-v1/post-mureka-music-score). === URL: https://useapi.net/blog/261104 === Document URL: https://useapi.net/blog/261104 --- layout: blog_post title: "Google Vids: 30-Second Talking Avatars from a Photo, and Text to Speech" description: "Turn a photo into a Google Vids avatar, restyle it with a sentence, have it read your script in a 30-second talking-head video, and voice scripts of up to 2,500 characters in 30 Gemini voices, all through the useapi.net Google Vids API." parent: Blog nav_exclude: true nav_order: -261104 --- ## Table of contents ## From a photo to a talking video, and speech on its own November 4, 2026 The [Google Vids API](/docs/api-google-vids-v1) can now make an avatar talk for up to 30 seconds: * [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) makes an avatar from a **photo** (or from a description, an image, or another avatar), and `refine` restyles it in words: clothes, place, light, a logo on the shirt * [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar) has the avatar read your script, word for word, in its own voice: a 1280×720 talking-head video with lip sync, as long as the speech (up to 30 seconds) * [POST /speech](/docs/api-google-vids-v1/post-google-vids-speech) turns a script of up to 2,500 characters into speech in any of the 30 Gemini voices, to hear a voice first or to use the audio on its own This post makes one avatar end to end. Every request below is the real one, and every picture and video is the real output. ## Step 1: upload the photo We started from a photo of a real person (not a famous one: Google refuses photos of prominent people), uploaded with [POST /assets](/docs/api-google-vids-v1/post-google-vids-assets) to the Google account that will make the avatar. An uploaded file only works on its own account. <img src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/261104-google-vids-amber-original-photo.jpg" alt="The original photo: a woman with long red hair in a white dress, standing in front of a cream curtain" style="max-height: 70vh; max-width: 100%;"> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-assets">POST /assets</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-vids/assets?email=user@example.com' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: image/jpeg' \ --data-binary '@photo.jpg' ``` ```json { "assetId": "user:12345-user@example.com-asset:AYGXpjA1zXgqhhQOy…", "email": "user@example.com", "type": "image/jpeg", "bytes": 2054748 } ``` </details> ## Step 2: the avatar, restyled in one sentence [POST /avatars](/docs/api-google-vids-v1/post-google-vids-avatars) with the photo as `image` and a `refine`: Google reframes the photo into an avatar picture, then changes the scene as asked while keeping the person. We named her Amber and gave her the voice Vira. Avatar pictures cost nothing on a plan without images; on a plan with images each picture Google makes counts one image. <img src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/261104-google-vids-amber-avatar.jpg" alt="Amber, the avatar made from the photo: a hilltop at sunset with a glass of red wine" style="width: 100%;"> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-avatars">POST /avatars</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-vids/avatars' \ --header 'Authorization: Bearer user:12345-…' \ --form 'name="Amber"' \ --form 'voice="Vira"' \ --form 'image="user:12345-user@example.com-asset:AYGXpjA1zXgqhhQOy…"' \ --form 'refine="Sitting relaxed in a simple wooden chair on a hilltop, facing the camera. She holds a glass of red wine in her left hand. Wind is blowing her hair. Behind her a still, open field of tall golden grass under a spectacular sunset sky in orange, pink and violet, warm soft light, no water, no movement in the background."' ``` ```json { "avatarId": "user:12345-user@example.com-avatar:eyJnIjoiaDcyMzdmZjVi…", "name": "Amber", "voice": "Vira", "voiceId": "Pulcherrima", "voiceStyle": "Forward", "email": "user@example.com", "source": "photo", "previewMediaId": "user:12345-user@example.com-image:eyJ1IjoiaHR0cHM6Ly9s…", "refine": "Sitting relaxed in a simple wooden chair on a hilltop, facing the camera. …" } ``` </details> Two things we learned on the way: * The avatar must face the camera: the video lip-syncs the face. * Pick a still background, so that she is the only thing that moves in the video. That is why we asked for a quiet field instead of waves on a beach. ## Step 3: the script The script is up to 400 characters, and spoken it has to fit in 30 seconds. Audio tags in square brackets are performed, not read: `[awe]`, `[thoughtful]` and `[whisper]` here. In Vira's voice these 327 characters ran 23.8 seconds; a slower voice or `[slow pace]` makes the same text longer, and a script that runs past 30 seconds is refused before the video starts. > Hi there. [awe] Can you believe this view? The sun is sinking behind the hills, the sky turned pink and gold, and the tall grass glows like it's on fire. [thoughtful] I come up here at the end of every busy day, just to slow down. No emails, no rush, only the quiet field and this glass of wine. [whisper] Stay a little longer. ## Step 4: the talking video [POST /videos/avatar](/docs/api-google-vids-v1/post-google-vids-videos-avatar) with the avatar and the script. Google took about two and a half minutes; the video is 1280×720 with sound, 24 seconds long, exactly the length of the speech. It used one of the account's monthly AI avatar videos. <video poster="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/261104-google-vids-amber-talking-avatar-24s-poster.jpg" src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/261104-google-vids-amber-talking-avatar-24s.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> The same video as a YouTube Short: [Talking AI avatar from one photo](https://youtube.com/shorts/P44L9VZ8bME). <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos-avatar">POST /videos/avatar</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-vids/videos/avatar' \ --header 'Authorization: Bearer user:12345-…' \ --form 'avatar="user:12345-user@example.com-avatar:eyJnIjoiaDcyMzdmZjVi…"' \ --form 'script="Hi there. [awe] Can you believe this view? The sun is sinking behind the hills, the sky turned pink and gold, and the tall grass glows like it'\''s on fire. [thoughtful] I come up here at the end of every busy day, just to slow down. No emails, no rush, only the quiet field and this glass of wine. [whisper] Stay a little longer."' \ --form 'async="true"' ``` ```json { "jobid": "j1105035516096819105a-u12345-email:user@example.com-bot:google-vids", "type": "avatarVideo", "email": "user@example.com", "status": "completed", "result": { "mediaId": "user:12345-user@example.com-video:eyJ1IjoiaHR0cHM6Ly9j…", "width": 1280, "height": 720, "duration": 24, "resolution": "720p", "aspectRatio": "landscape", "speechDuration": 23.84, "quota": { "avatarVideo": { "limit": 10, "left": 6, "resetAt": "2026-12-01T08:00:00.000Z" } } } } ``` The job runs in the background (`async: true`); [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid) returns it until it completes, and [GET /media/`mediaId`](/docs/api-google-vids-v1/get-google-vids-media-mediaId) downloads the MP4. </details> ## Speech on its own: 2,426 characters in one call [POST /speech](/docs/api-google-vids-v1/post-google-vids-speech) voices any script of up to 2,500 characters in one of the 30 [voices](/docs/api-google-vids-v1/get-google-vids-voices). We gave it a short original story, "My smart fridge unionized", in the voice Vira. Google answered in 20 seconds with 2 minutes 22 seconds of speech, the whole story. It used one of the account's monthly Gemini uses. The API returns a WAV (24 kHz mono); the player below is the same audio as an MP3. <audio controls class="audio-player"> <source src="https://media.useapi.net/articles/2026-10-07-google-vids-influencer-avatars-id/261104-google-vids-speech-smart-fridge-2426-chars.mp3" type="audio/mp3">Your browser does not support the audio element. </audio> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-speech">POST /speech</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-vids/speech' \ --header 'Authorization: Bearer user:12345-…' \ --form 'voice="Vira"' \ --form 'script="Last Tuesday, my smart fridge decided it was smarter than me. It started small. A polite notification: \"You are out of milk.\" … I have never felt so seen by an appliance."' ``` ```json { "jobid": "j1105025759739671733s-u12345-email:user@example.com-bot:google-vids", "type": "speech", "email": "user@example.com", "status": "completed", "result": { "mediaId": "user:12345-user@example.com-audio:eyJ1IjoiaHR0cHM6Ly9j…", "duration": 142, "model": "/flix/generate_text_to_speech/v1", "quota": { "speech": { "limit": 50, "left": 31, "resetAt": "2026-12-01T08:00:00.000Z" } }, "elapsedMs": 20174 } } ``` [GET /media/`mediaId`](/docs/api-google-vids-v1/get-google-vids-media-mediaId) downloads the WAV. </details> ## Good to know * **Cost.** Each video uses one AI avatar video from the account's monthly allowance, plus one Gemini use for the speech. [GET /accounts/`email`](/docs/api-google-vids-v1/get-google-vids-accounts-email) shows what is left (`avatarVideo`, `speech`). The avatar itself and its changes cost nothing on a plan without images. * **Google checks the video too, and still counts a refusal.** The check while making the video is stricter than the one for avatar pictures: an earlier version of this avatar, made from a different photo of an ordinary person on a beach, was refused as looking like a celebrity, and that attempt still used a video. Restyling or using another photo helped. * **Landscape only.** Google has no portrait option for talking avatars. * **Longer scenes with action** are [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) with the avatar as `avatar_1`: 3 to 10 seconds where the avatar acts and speaks the lines you write in the prompt. * **MCP.** The same features are in the [Google Vids MCP server](/docs/api-google-vids-v1/mcp): `vids_create_avatar`, `vids_create_avatar_video` and `vids_create_speech`. === URL: https://useapi.net/blog/261106 === Document URL: https://useapi.net/blog/261106 --- layout: blog_post title: "Google Flow: Omni 1.2 Flash, 15-Second Videos, and Extend with Voices" description: "Omni 1.2 Flash in the useapi.net Google Flow API: 3 to 15 second videos, and extend with voices up to 10 seconds at a time. A 30-second scene built in three calls." parent: Blog nav_exclude: true nav_order: -261106 --- ## Table of contents ## Omni 1.2 Flash, and extend with voices November 6, 2026 Google released Omni 1.2 Flash in Flow on November 5, 2026, and the [Google Flow API](/docs/api-google-flow-v1) runs it now as `model: "omni-flash-1.2"`: * [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) makes videos of any whole number of seconds from 3 to 15, at 360p or 720p, landscape or portrait, from text, a start image, a start and end image, reference images and voices, or by editing a clip of up to 15 seconds * [POST /videos/extend](/docs/api-google-flow-v1/post-google-flow-videos-extend) uses Omni 1.2 by default. It adds 3 to 10 seconds to any video shorter than 30 seconds and returns one clip, the source plus the new seconds, and it takes up to 3 reference images or characters and up to 3 voices * Credits are per second and the same on every plan: at 720p 3 credits a second up to 10 seconds and 6 a second above that, at 360p 1 and 2 Free Google accounts can use Omni 1.2 too, for videos of up to 10 seconds. Longer videos and extending with Omni 1.2 need a paid Google AI plan. Below, one scene built in three calls: a 10-second video, then two 10-second extensions, each with its own voice. Every request is the real one, and the video is the real output. ## Step 1: the first 10 seconds [POST /videos](/docs/api-google-flow-v1/post-google-flow-videos) with `omni-flash-1.2` and `duration: 10`. Google answered in 56 seconds. At 720p a 10-second video is 30 credits. <video poster="https://media.useapi.net/blog/2026-11-06-261106/261106-google-flow-omni-1-2-magician-first-10s-poster.jpg" src="https://media.useapi.net/blog/2026-11-06-261106/261106-google-flow-omni-1-2-magician-first-10s.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos">POST /videos</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="omni-flash-1.2"' \ --form 'duration="10"' \ --form 'prompt="Cinematic night, a narrow rainy alley in Tokyo glowing with neon signs reflected in the puddles. A street magician in a long dark coat faces the camera, fans out a deck of cards that glow faintly gold, and says with a grin: \"Pick a card. Any card.\" A sudden gust snatches one glowing card from his hand and it flutters away down the alley. Handheld camera, shallow depth of field, rain drops catching the light."' \ --form 'async="true"' ``` The finished job, from [GET /jobs/`jobid`](/docs/api-google-flow-v1/get-google-flow-jobs-jobid) (shortened): ```json { "jobid": "j1106021223539251070v-u12345-email:user@example.com-bot:google-flow", "type": "video", "status": "completed", "response": { "media": [ { "video": { "generatedVideo": { "model": "macaron_cookie_t2v_10s", "aspectRatio": "VIDEO_ASPECT_RATIO_LANDSCAPE" }, "dimensions": { "length": "10s" } }, "mediaGenerationId": "user:12345-email:…-video:b08556b9-…", "videoUrl": "https://flow-content.google/video/b08556b9-…?Expires=…" } ], "remainingCredits": 877 } } ``` </details> ## Step 2: extend by 10 seconds, with a voice [POST /videos/extend](/docs/api-google-flow-v1/post-google-flow-videos-extend) with the first video's `mediaGenerationId`, `duration: 10` and the built-in voice Charon as `referenceAudio_1`. The prompt names the voice where the magician speaks, with the inline mention `@referenceAudio_1`. Extend uses Omni 1.2 by default, so no `model` is needed. The answer is one 20-second clip, the first 10 seconds unchanged plus the new 10, in 2 minutes 20 seconds, for 30 credits. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos-extend">POST /videos/extend</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos/extend' \ --header 'Authorization: Bearer user:12345-…' \ --form 'mediaGenerationId="user:12345-email:…-video:b08556b9-…"' \ --form 'duration="10"' \ --form 'referenceAudio_1="Charon"' \ --form 'prompt="The magician runs after the glowing card through the rain, past a ramen stall and under paper lanterns, laughing and calling out in a deep voice @referenceAudio_1: \"Come back here! You are the ace of hearts!\" The camera follows him close behind."' \ --form 'async="true"' ``` </details> ## Step 3: 10 more seconds, a second voice The same call on the 20-second clip, with the voice Aoede for the woman in the café. The result is the whole scene, 30 seconds long, after another 2 minutes and 30 credits. <video poster="https://media.useapi.net/articles/2026-06-15-omni-flash-bash/261106-google-flow-omni-1-2-magician-extended-30s-web-poster.jpg" src="https://media.useapi.net/articles/2026-06-15-omni-flash-bash/261106-google-flow-omni-1-2-magician-extended-30s-web.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-videos-extend">POST /videos/extend</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/videos/extend' \ --header 'Authorization: Bearer user:12345-…' \ --form 'mediaGenerationId="user:12345-email:…-video:113384cd-…"' \ --form 'duration="10"' \ --form 'referenceAudio_1="Aoede"' \ --form 'prompt="The glowing card drifts through the open door of a tiny warm café and lands on a table. A young woman in a yellow raincoat picks it up, looks at the out-of-breath magician in the doorway, and says with a smile @referenceAudio_1: \"Is this your card?\" He laughs. Warm light, rain outside the window."' \ --form 'async="true"' ``` ```json { "jobid": "j1106021547955542178v-u12345-email:user@example.com-bot:google-flow", "type": "video", "status": "completed", "response": { "media": [ { "video": { "generatedVideo": { "model": "macaron_cookie_extend_10s" }, "dimensions": { "length": "30s" } }, "mediaGenerationId": "user:12345-email:…-video:db0201df-…", "videoUrl": "https://flow-content.google/video/db0201df-…?Expires=…" } ], "remainingCredits": 817 } } ``` </details> The video above is re-encoded for the web at the original 1280×720. Google's own file is about 15 MB. ## The 30-second rule Google extends videos shorter than 30 seconds only, so this scene can grow no further. A fourth extend answers right away, before any captcha or credits: ```json { "error": "Google Flow extends videos shorter than 30 s only. This video is 30 s long.", "code": 400 } ``` A clip of 25 seconds can still take 10 more and end at 35. ## Prices The whole 30-second scene used 90 credits: 30 for the first 10 seconds and 30 for each extension. | Length | 720p | 360p | |:--|--:|--:| | 3 seconds | 9 credits | 3 credits | | 10 seconds | 30 credits | 10 credits | | 15 seconds | 60 credits | 20 credits | | Extend by 10 seconds | 30 credits | 10 credits | On Google AI Ultra ($199.99 a month for 25,000 credits) a credit is $0.008, so an 8-second 720p Omni 1.2 video is $0.19 (seconds past 10 cost double) and this 30-second scene about $0.72. Google's own API charges $0.07 a second for 720p Omni 1.2 Flash ([Google Cloud, November 5, 2026](https://cloud.google.com/blog/products/ai-machine-learning/gemini-omni-1-2-flash-generally-available)), about $2.10 for the same 30 seconds, and offers audio references there only to allowlisted customers. ## Good to know * Google is giving Omni 1.2 to accounts over several days from November 5. An account that does not have it yet answers `400` with a message that says so, and a request without `email` goes to one of your accounts that has it. * Veo still extends: pass `model: "veo-3.1-lite"` (or `veo-3.1-fast`, `veo-3.1-quality`) to extend with Veo as before: it adds about 7 seconds and returns only the new part. * With `referenceVideo_1`, Omni 1.2 edits up to 15 seconds of a clip (`endFrameIndex_1` up to 360, at 24 frames a second), priced like a video of the edited length. * [`omni-extend/`](https://github.com/useapi/google-flow-api/tree/main/omni-extend) on GitHub makes this scene from one `story.json`, in Node.js or Python. * A 360p draft costs a third of 720p, and its extensions stay 360p unless you ask for `resolution: "720p"`. The [Gemini Omni 1.2 Flash API guide](/docs/articles/gemini-omni-1-2-flash-api) compares Omni 1.2 in Google Flow and Google Vids, with the price per video on every plan. === URL: https://useapi.net/blog/261106v === Document URL: https://useapi.net/blog/261106v --- layout: blog_post title: "Google Vids: Omni 1.2 Flash, 15-Second Videos and 15-Second Edits" description: "Gemini Omni 1.2 Flash in the useapi.net Google Vids API: videos and edits up to 15 seconds, extend up to 10 seconds a call. A 15-second scene, its extension and a snow edit, with the real requests." parent: Blog nav_exclude: true nav_order: -261106 --- ## Table of contents ## Omni 1.2 Flash in Google Vids November 6, 2026 Google moved Google Vids to [Gemini Omni 1.2 Flash](https://workspaceupdates.googleblog.com/2026/11/gemini-omni-12-flash-now-in-vids-with-15second-generations-and-improved-quality.html) on November 5, 2026, and the [Google Vids API](/docs/api-google-vids-v1) supports its longer clips now: * [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) makes videos of 3 to 15 seconds, at 720p or 1080p, landscape or portrait, from text, a start image, reference images or voiced avatars * [POST /videos/edit](/docs/api-google-vids-v1/post-google-vids-videos-edit) edits up to 15 seconds of a clip * [POST /videos/extend](/docs/api-google-vids-v1/post-google-vids-videos-extend) adds up to 10 seconds a call, as Omni 1.2 does in [Google Flow](/blog/261106), to clips of up to 24 seconds. Call it again to go longer, up to about 34 seconds There is nothing to choose: Vids has one video model, and Google is moving accounts to Omni 1.2 over a few days from November 5. A video uses its seconds of the account's monthly Vids allowance, which is separate from Google Flow credits. Below, one scene in three calls: a 15-second video, a 10-second extension and an edit of the first 15 seconds. Every request is the real one, and every video is the real output. ## Step 1: a 15-second video from one prompt [POST /videos](/docs/api-google-vids-v1/post-google-vids-videos) with `duration: 15`. Google answered in about 60 seconds with a 1280×720 video, and both lines are spoken as written. It used 15 seconds of the allowance. <video poster="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-15s-poster.jpg" src="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-15s.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos">POST /videos</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-vids/videos' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: application/json' \ --data '{ "prompt": "Cinematic single continuous shot, 15 seconds, 16:9. Golden hour on a Tokyo rooftop garden, city skyline glowing behind. A young chef in a crisp white apron finishes plating a steaming bowl of ramen, steam curling in the warm light. She looks up into the camera and says with a confident smile: \"Fifteen seconds. One prompt. No editing.\" She slides the bowl toward the camera as it slowly pushes in, wind chimes ringing softly and city traffic humming far below. She laughs and adds: \"Now that'\''s fast food.\"", "duration": 15, "aspectRatio": "landscape", "resolution": "720p", "async": true }' ``` The finished job, from [GET /jobs/`jobid`](/docs/api-google-vids-v1/get-google-vids-jobs-jobid) (shortened): ```json { "status": "completed", "result": { "mediaId": "user:12345-user@example.com-video:eyJ1Ijoi…", "width": 1280, "height": 720, "duration": 15, "resolution": "720p", "aspectRatio": "landscape", "model": "/flix/generate_videos_omni_t2v_psq/v1", "quota": { "video": { "limit": 500, "left": 485, "resetAt": "2026-12-01T08:00:00.000Z" } } } } ``` </details> ## Step 2: extend it by 10 seconds [POST /videos/extend](/docs/api-google-vids-v1/post-google-vids-videos-extend) with the first video's `mediaId`. The result is one clip, the 15 seconds plus 10 new ones, 25 seconds long, after about 100 seconds. A friend walks in, tries the ramen, and both new lines are spoken. <video poster="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-extend-25s-poster.jpg" src="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-extend-25s.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> Also on YouTube: [Gemini Omni 1.2 Flash in Google Vids: 15 seconds from one prompt, extended to 25](https://www.youtube.com/watch?v=eJ3js18XCBM). We made this clip while testing with `duration: 15`, which the Vids editor's slider also offers. Google added only 10 seconds and still counted 15, so the API now takes up to 10 a call and answers a longer request with `400`. The same request with `duration: 10` returns the same 25-second clip and uses 10 seconds. <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos-extend">POST /videos/extend</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-vids/videos/extend' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: application/json' \ --data '{ "mediaId": "user:12345-user@example.com-video:eyJ1Ijoi…", "prompt": "Same shot continues on the Tokyo rooftop at dusk, the city lights now switching on. A friend in a denim jacket walks into frame, sits at the table and takes a first slurp of the ramen, eyes widening. He says: \"Wait, you made this in fifteen seconds?\" The chef folds her arms and grins: \"Fifteen more, and I'\''ll make dessert.\" They both laugh as string lights flicker on above them and soft city ambience fills the air.", "duration": 10, "async": true }' ``` </details> ## Step 3: edit all 15 seconds [POST /videos/edit](/docs/api-google-vids-v1/post-google-vids-videos-edit) on the first video with `duration: 15`. With Omni 1.1 an edit returned at most 10 seconds. Now the whole 15-second clip came back edited, every frame of it, after about 140 seconds. In this run it used 10 seconds of the allowance. <video poster="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-edit-snow-15s-poster.jpg" src="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-omni-1-2-ramen-edit-snow-15s.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-vids-v1/post-google-vids-videos-edit">POST /videos/edit</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-vids/videos/edit' \ --header 'Authorization: Bearer user:12345-…' \ --header 'Content-Type: application/json' \ --data '{ "video": "user:12345-user@example.com-video:eyJ1Ijoi…", "prompt": "Make it a snowy winter evening: snow falling gently over the rooftop and the city, the chef wearing a red knit scarf. Keep everything else the same.", "duration": 15, "async": true }' ``` </details> ## 720p or 1080p: what a 1080p extend does We recommend making and extending Vids clips at `720p` and going to `1080p` once, at the end. This test shows why. A `1080p` video from Google is a `720p` draft that Google upscales ([Gemini API docs](https://aistudio.google.com/docs/omni): "1080p output (upscaled)"). An extend at `1080p` processes the whole clip again, the seconds you already had included, and each pass sharpens them further. One detailed shot (a fisherman's face, rain on his skin, a knitted cap and a painted sign), made at `1080p` and then extended twice at `1080p`, against the same shot made and extended at `720p` with `1080p` set on the last extend only. Each panel plays the same first 10 seconds, cropped to the face: <video poster="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-1080p-extend-quality-comparison-poster.jpg" src="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-1080p-extend-quality-comparison.mp4" style="width: 100%;" controls type="video/mp4" preload="metadata"></video> 1. The `1080p` shot as Google made it. 2. The same seconds after one `1080p` extend: skin and wrinkles come back harder and crunchier. 3. After two `1080p` extends: the face looks plastic and over-drawn. 4. Made and extended at `720p`, with `resolution: "1080p"` on the last extend only: one `1080p` pass, and the face stays natural. A still from 5 seconds in, in the same order: <img src="https://media.useapi.net/blog/2026-11-06-261106v/261106v-google-vids-1080p-extend-quality-comparison.png" alt="The same frame of a fisherman's face: the 1080p shot, after one 1080p extend, after two 1080p extends, and the 720p route with 1080p on the last extend only" style="width: 100%;"> How much of the first 10 seconds each extend changed, measured against the shot as Google made it (SSIM, where 1.00 means identical): | Clip | First 10 seconds compared with the original | |---|---| | One extend at `1080p` | 0.92, re-rendered and sharper | | Two extends at `1080p` | 0.83, re-rendered again | | One extend at `720p` | 0.99, left as it was | So give a clip one `1080p` pass, at the end: - Make and extend your clips at `720p`. - Finish a clip of up to 20 seconds with one [upscale](/docs/api-google-vids-v1/post-google-vids-videos-upscale) to `1080p`. - For a clip of 21 to 34 seconds, which upscale doesn't take, set `resolution: "1080p"` on the last extend only. - A single clip you won't extend or edit can be made at `1080p` from the start: it uses the same seconds as `720p`. The prompts, in order: the shot (`duration: 10`), then two extends of 10 seconds each. ```text Static camera, extreme close-up portrait of an elderly fisherman on a harbor at dawn: deep wrinkles, grey stubble, rain droplets on his skin, a hand-knitted navy wool cap with clearly visible yarn stitches. Behind him a weathered wooden sign with small painted letters reading HARBOR MARKET OPEN 6AM. He looks into the camera and says calmly: "The sea gives, and the sea takes." Gulls cry softly, waves lap against the pier. Same static shot continues. He lifts a wet fishing net close to the camera, every rope knot sharp and dripping, and says: "Tomorrow, we go out again." Waves lap softly. Same static shot continues. He lowers the net, smiles, and the first sunlight catches the droplets on his cap. He nods once. Gulls cry in the distance. ``` ## Also through the MCP server The [Google Vids MCP server](/docs/api-google-vids-v1/mcp) has the same limits: `vids_create_video` and `vids_edit_video` take up to 15 seconds, `vids_extend_video` up to 10 a call on clips of up to 24 seconds. Omni 1.2 arrived in Google Flow on the same day, with 15-second videos and extend with voices: [Google Flow: Omni 1.2 Flash, 15-Second Videos, and Extend with Voices](/blog/261106). The [Gemini Omni 1.2 Flash API guide](/docs/articles/gemini-omni-1-2-flash-api) compares Omni 1.2 in Google Flow and Google Vids, with the price per video on every plan. === URL: https://useapi.net/blog/261107 === Document URL: https://useapi.net/blog/261107 --- layout: blog_post title: "Google Flow: Nano Banana 2.1 Thinking Level" description: "Choose how long Nano Banana 2.1 thinks before it draws: thinkingLevel low, medium or high in the useapi.net Google Flow API, compared on the same prompts and seeds." parent: Blog nav_exclude: true nav_order: -261107 --- ## Table of contents ## Nano Banana 2.1 thinking level November 7, 2026 Google added a Thinking level switch for Nano Banana 2.1 to Flow on November 7, 2026, and the [Google Flow API](/docs/api-google-flow-v1) supports it now as `thinkingLevel` on [POST /images](/docs/api-google-flow-v1/post-google-flow-images): * `low`, `medium` or `high` sets how long Nano Banana 2.1 (`model: "nano-banana-2"`) reasons about the prompt before it draws. The default is `high`, the same as Flow's own default * A higher level follows precise details more closely and takes longer. In Flow one image took about 11 seconds on `low`, 14 on `medium` and 21 on `high` * Every level costs the same: Nano Banana 2.1 images use no Flow credits * `low` and `medium` need a paid Google AI plan. Flow offers a free account `high` only, and the API answers `400` for the other two before any captcha is used Below, four prompts that need some reasoning, each run at all three levels with the same seed, so the level is the only thing that changes. These are the real outputs. ## A clock at 7:45 The prompt asks for a station clock showing exactly 7:45. On `low` and `medium` the minute hand points at the 8, so the clock reads about 7:40. On `high` it points at the 9, and the clock reads 7:45. The departure board text is right at every level. ![Nano Banana 2.1 thinking level low, medium and high: a station clock asked to show 7:45](https://media.useapi.net/blog/2026-11-07-261107/261107-google-flow-nb21-thinking-clock-low-medium-high.jpg) <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-google-flow-v1/post-google-flow-images">POST /images</a></summary> ```bash curl --location 'https://api.useapi.net/v1/google-flow/images' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="nano-banana-2"' \ --form 'thinkingLevel="high"' \ --form 'aspectRatio="16:9"' \ --form 'count="1"' \ --form 'seed="515151"' \ --form 'prompt="An old railway station clock showing exactly 7:45, next to a departure board that reads \"LONDON 8:05 - PLATFORM 2\". Photograph, morning light."' ``` </details> ## A chalkboard menu Five drinks with exact prices. All three levels spell every item and price correctly. `high` lays the board out the most cleanly. ![Nano Banana 2.1 thinking level low, medium and high: a café chalkboard menu with five drinks and prices](https://media.useapi.net/blog/2026-11-07-261107/261107-google-flow-nb21-thinking-menu-low-medium-high.jpg) <details markdown="block"> <summary>Prompt</summary> A hand-drawn chalkboard menu in a cozy café titled "MORNING BREW", listing exactly five drinks with prices, one per line: Espresso $3.00, Latte $4.50, Flat White $4.00, Matcha $5.00, Cold Brew $4.25. Warm light, photograph. Aspect ratio `3:4`, seed `424242`. </details> ## Seven apples, three pears A counting prompt. Every level got seven apples and three pears, so for a simple count `low` is enough. ![Nano Banana 2.1 thinking level low, medium and high: seven red apples above three green pears](https://media.useapi.net/blog/2026-11-07-261107/261107-google-flow-nb21-thinking-count-low-medium-high.jpg) <details markdown="block"> <summary>Prompt</summary> Top-down photograph of exactly seven red apples in a straight row on a wooden table, with exactly three green pears in a second row below them. Aspect ratio `1:1`, seed `717171`. </details> ## A labelled diagram The water cycle in four numbered steps. All three levels keep the steps in order. `medium` and `high` add a title, and `high` also adds labels the prompt did not ask for (surface runoff, groundwater). ![Nano Banana 2.1 thinking level low, medium and high: a water cycle infographic with four numbered steps](https://media.useapi.net/blog/2026-11-07-261107/261107-google-flow-nb21-thinking-diagram-low-medium-high.jpg) <details markdown="block"> <summary>Prompt</summary> A clean educational infographic of the water cycle with four labelled steps in order, connected by arrows: 1 Evaporation, 2 Condensation, 3 Precipitation, 4 Collection. Flat illustration, white background. Aspect ratio `16:9`, seed `616161`. </details> ## Which level to use Keep the default `high` when the image has to get a precise detail right, such as a time, a number of objects, or exact text. Use `low` for drafts and simple scenes, where it is about twice as fast. `thinkingLevel` works with reference images and characters too, and only `nano-banana-2` takes it: other models answer `400`. Full parameter reference: [POST /images](/docs/api-google-flow-v1/post-google-flow-images). === URL: https://useapi.net/blog/261109 === Document URL: https://useapi.net/blog/261109 --- layout: blog_post title: "Dreamina: Seedream 5.5 and Transparent Backgrounds" description: "Seedream 5.5 images and the new background parameter (transparent PNGs) in the useapi.net Dreamina API, with real outputs from Seedream 5.5 and GPT Image 2.5 Flare." parent: Blog nav_exclude: true nav_order: -261109 --- ## Table of contents ## Seedream 5.5 and transparent backgrounds November 9, 2026 Dreamina added ByteDance's Seedream 5.5 to Canadian accounts, and the [Dreamina API](/docs/api-dreamina-v1) supports it now on [POST /images](/docs/api-dreamina-v1/post-dreamina-images): * `model: "seedream-5.5"` makes 4 images per request at 1.5K (default) or 2K, from text and up to 6 reference images, and picks the aspect ratio for you when you don't set one * On a Canadian account it uses 8 credits an image at 1.5K and 13 at 2K (launch price, normally 11 and 18) * The new `background` parameter takes `auto` (default), `opaque` or `transparent`. With `transparent` you get PNG images with a transparent background. It works with `seedream-5.5`, `gpt-image-2`, `gpt-image-2.5-flare` and `gpt-image-2.5-sunburst` Below are the real outputs of our test round, all made through the API on a Canadian account. ## Seedream 5.5 at 1.5K One request, four images of 1536×1536, ready in 23 seconds. ![Seedream 5.5 in the Dreamina API: four 1.5K images of a red vintage bicycle against a white brick wall](https://media.useapi.net/blog/2026-11-09-261109/261109-dreamina-seedream-5-5-1-5k.jpg) <details markdown="block"> <summary><code>curl</code> — <a href="/docs/api-dreamina-v1/post-dreamina-images">POST /images</a></summary> ```bash curl --location 'https://api.useapi.net/v1/dreamina/images' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="seedream-5.5"' \ --form 'resolution="1.5k"' \ --form 'ratio="1:1"' \ --form 'prompt="a red vintage bicycle leaning on a white brick wall, soft morning light, photo"' ``` </details> ## Transparent background The same prompt with `background: "transparent"`. Seedream 5.5 returned four PNGs with an alpha channel, shown here on a checkerboard so you can see what is transparent. Because the prompt describes a scene, Seedream kept part of the wall in three of them and the whole scene in the fourth. ![Seedream 5.5 with background transparent: four PNG images on a checkerboard, the wall partly kept](https://media.useapi.net/blog/2026-11-09-261109/261109-dreamina-seedream-5-5-transparent.jpg) <details markdown="block"> <summary><code>curl</code></summary> ```bash curl --location 'https://api.useapi.net/v1/dreamina/images' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="seedream-5.5"' \ --form 'resolution="1.5k"' \ --form 'ratio="1:1"' \ --form 'background="transparent"' \ --form 'prompt="a red vintage bicycle leaning on a white brick wall, soft morning light, photo"' ``` </details> GPT Image 2.5 Flare, given the same prompt and `background: "transparent"`, dropped the wall and returned a clean cutout of the bicycle alone, one 1328×1328 PNG in 33 seconds for 5 credits. [Download the original PNG](https://media.useapi.net/blog/2026-11-09-261109/261109-dreamina-gpt-image-2-5-flare-transparent-original.png). ![GPT Image 2.5 Flare with background transparent: a red bicycle cut out on a checkerboard](https://media.useapi.net/blog/2026-11-09-261109/261109-dreamina-gpt-image-2-5-flare-transparent.jpg) <details markdown="block"> <summary><code>curl</code></summary> ```bash curl --location 'https://api.useapi.net/v1/dreamina/images' \ --header 'Authorization: Bearer user:12345-…' \ --form 'model="gpt-image-2.5-flare"' \ --form 'resolution="1k"' \ --form 'ratio="1:1"' \ --form 'background="transparent"' \ --form 'prompt="a red vintage bicycle leaning on a white brick wall, soft morning light, photo"' ``` </details> For stickers, product shots and logos, describe the object on its own ("a red vintage bicycle, isolated") rather than a scene, and both models have less background to decide about. ## Also new * US accounts now run Seedream 5.0 Pro (`seedream-5.0-pro`, 2K or 4K) and Seedream 5.0 Flash (`seedream-5.0-flash`, 1.5K, 2K or 4K, 6 credits an image up to 2K). Flash replaced Seedream 5.0 Lite on US, which stays on Canadian accounts * Canadian accounts get Seedream 3.1 (`seedream-3.1`, text only, 1K or 2K) * Dreamina dropped Nano Banana and Seedance 1.5 Pro from Canadian accounts. Seedance 1.5 Pro still runs on US accounts Full parameter reference: [POST /images](/docs/api-dreamina-v1/post-dreamina-images). Credits per image for every model: [Setup Dreamina](/docs/start-here/setup-dreamina#cost-calculator). === URL: https://useapi.net/docs/how-it-works === Document URL: https://useapi.net/docs/how-it-works --- title: How useapi.net works description: "How useapi.net works: third-party REST APIs that run on the AI accounts and plans you already have, since 2023, with tips for keeping those accounts healthy." parent: Support nav_order: 81000 layout: home --- # How useapi.net works October 25, 2026 useapi.net has run [third-party](/docs/legal#affiliation--third-party-services) REST APIs for AI websites since August 2023. It is not affiliated with Google, Meta, ByteDance, Kuaishou or the other companies whose products it connects to. ## Your accounts, your subscriptions You connect accounts you own on each service: your Google AI plan for Google Flow, your Kling or PixVerse subscription, and so on. useapi.net sends each request to that website from your account and returns the result through the REST API, webhooks or a hosted MCP server. Videos, images and songs use your plan's credits. We never sell, share or pool access to anyone's account. One [subscription](/docs/subscription) covers every API on useapi.net and up to 3 accounts on each service. ## Keeping your accounts healthy useapi.net has connected customers' own accounts to these services since 2023. It works with each one through your own sign-in and the plan you already pay for. A few habits help: - Connect accounts you use only for the API, and keep your sign-ins consistent. For Google, use a [dedicated Gmail account](/docs/start-here/setup-google-flow#use-a-dedicated-gmail-account). - Spread the work over several accounts. useapi.net shares the jobs between them, and on Google Flow it skips an account that has reached its quota until the quota resets. - The API emails you when an account needs attention, for example when it has to be signed in again. ## Community and updates Close to 2,000 developers follow useapi.net in our [Discord](https://discord.gg/w28uK3cnmF) and [Telegram](https://t.me/use_api) communities. The [changelog](/docs/changelog) lists every change. ## Payments and refunds You pay by card through Stripe or with crypto. We refund in full within the first 14 days of your first purchase if you have fewer than 50 successful generations, as the [Refund Policy](/docs/legal#refund-policy) explains. Questions go to [support@useapi.net](mailto:support@useapi.net). === URL: https://useapi.net/docs/legal === Document URL: https://useapi.net/docs/legal --- title: Legal description: "The useapi.net Terms of Service, Privacy Policy, and Refund Policy for our experimental API, with links to the terms of each third-party AI service." parent: Support nav_order: 86000 layout: home --- ToS » [Mureka](https://www.mureka.ai/terms) • [Runway](https://runwayml.com/terms-of-use) • [MiniMax](https://hailuoai.video/doc/terms-of-service.html) • [InsightFaceSwap by Picsi.ai](https://discord.com/channels/1095014106576212101/1135776376683769876) • [PixVerse by PixVerse.ai](https://pixverse.ai/en/terms-of-service) • [Kling AI](https://klingai.com/global/docs/user-policy) • [Dreamina by ByteDance](https://www.capcut.com/clause/terms-of-service) • [TemPolor](https://www.tempolor.com) • [Flow Music](https://www.flowmusic.app) • [Discord](https://discord.com/terms) • [Google](https://policies.google.com/terms) • [Muse by Meta](https://muse.ai/terms) • [ACE Music](https://acemusic.ai/terms/) 15 min read • July 2023 (October 2026) --- We reserve the right to modify these Terms of Service, our Privacy Policy, and our Refund Policy at any time. We will provide you with reasonable prior notice of any material changes by posting the updated policies on our website and/or sending an email to the address associated with your account. We will indicate the last updated date at the top of this page. Your continued use of our services after the effective date of such changes constitutes your acceptance of the new terms. If you do not agree to the modifications, you should discontinue your use of the service. # Terms of Service These Terms of Service ("Terms") govern your access to and use of the experimental third-party API services ("Services") provided by useapi.net ("we," "us," or "our"), a company based in New Mexico, USA. By accessing or using the Services, you agree to be bound by these Terms. If you do not agree to these terms, do not use the Services. Your use of the Services is also governed by our **Privacy Policy**, which is included below these terms. ### Experimental Nature & Disclaimer of Warranties You acknowledge the Services are experimental, provided **"as is"** and **"as available,"** and may change, be suspended, or terminate without notice. TO THE FULLEST EXTENT PERMITTED BY LAW, WE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, ACCURACY, RELIABILITY, AND NON-INFRINGEMENT. WE DO NOT WARRANT THAT THE SERVICES WILL BE UNINTERRUPTED, ERROR-FREE, OR SECURE. ### Affiliation & Third-Party Services Useapi.net is **not affiliated** with, endorsed by, or in any way officially connected with Google, Meta (including Muse), Flow Music, Discord, Mureka, Runway, MiniMax, Kling AI, Dreamina/ByteDance, TemPolor, PixVerse.AI, Picsi.ai, ACE Music/Timedomain, or any of their subsidiaries or affiliates. We provide an automation tool that interacts with these services on your behalf. We do not sell, resell, or license access to these Third-Party Services. You must have your own valid account with them. Your use of any Third-Party Service via our experimental API is subject to that service's own terms and policies. You are solely responsible for reviewing and complying with them. A violation of a Third-Party Service's terms constitutes a violation of these Terms. ### User Credentials & Authorized Agent Status By providing login credentials, session tokens, cookies, or other authentication data ("Credentials") to useapi.net, you explicitly appoint useapi.net as your **Authorized Agent**. You grant us limited power of attorney to access third-party platforms on your behalf solely to execute the automation requests you initiate. You represent and warrant that you are the legal owner of any third-party account you connect to our Services, or that you have explicit written permission from the account owner to grant us access. You acknowledge that using automation tools to interact with third-party services (such as Discord, etc.) may violate their Terms of Service. **You assume all risk** associated with such usage, including but not limited to account bans, suspensions, or legal action by those third parties. Useapi.net is not responsible for any account termination resulting from your use of our Services. ### Acceptable Use Policy You agree not to use the Services to: (a) Engage in any activity that is illegal under local, state, national, or international law. (b) Transmit or generate any content that is unlawful, harassing, defamatory, hateful, fraudulent, or obscene. (c) Violate the terms of service of any Third-Party Service. (d) Infringe upon the intellectual property rights, privacy rights, or other rights of any third party. (e) Attempt to disrupt, overload, or compromise the integrity or security of our systems or the systems of any third party. (f) Reverse-engineer, decompile, or otherwise attempt to discover the source code of the Services. We are not obligated to monitor your use of the Services, but we reserve the right to investigate and terminate your access for any violation of this policy, with or without notice. ### Payments and Fees If you subscribe to a paid tier of our Services, you agree to pay the fees specified. All payments are processed through our third-party payment processors. By providing payment information, you agree to payment processors terms and privacy policy. We do not store your full credit card information. All fees are non-refundable unless otherwise required by law. ### Intellectual Property You retain all rights to the input (e.g., prompts) you provide to the Services. The ownership of any output generated by the Services is governed by the terms of the specific Third-Party Service that created it. We make no claim of ownership and grant no rights to the generated output. ### Limitation of Liability TO THE MAXIMUM EXTENT PERMITTED BY LAW, USEAPI.NET AND ITS AFFILIATES WILL NOT BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, OR PUNITIVE DAMAGES, OR ANY LOSS OF PROFITS OR REVENUES, RESULTING FROM YOUR USE OF THE SERVICES. IN NO EVENT SHALL OUR AGGREGATE LIABILITY FOR ALL CLAIMS RELATING TO THE SERVICES EXCEED THE GREATER OF ONE HUNDRED U.S. DOLLARS ($100) OR THE TOTAL AMOUNT YOU PAID US IN THE SIX (6) MONTHS PRECEDING THE CLAIM. ### Indemnification You agree to defend, indemnify, and hold harmless useapi.net, its affiliates, licensors, and service providers, and its and their respective officers, managers, members, employees, contractors, agents, licensors, suppliers, successors, and assigns from and against any claims, liabilities, damages, judgments, awards, losses, costs, expenses, or fees (including reasonable attorneys' fees) arising out of or relating to: (a) Your violation of these Terms or the Terms of Service of any Third-Party Service; (b) Your use of the Services, including any use of the API's content, services, and products other than as expressly authorized in these Terms; (c) Any claim by a third party (including platforms like Discord) alleging that your use of our Services violated their rights or disrupted their operations. ### Termination We reserve the right to suspend or terminate your access to the Services at any time, for any reason, including for a violation of these Terms. You may stop using the Services at any time. ### Dispute Resolution: Binding Arbitration & Class Action Waiver **1. Binding Arbitration:** Any dispute, claim, or controversy arising out of or relating to these Terms or the breach, termination, enforcement, interpretation, or validity thereof, including the determination of the scope or applicability of this agreement to arbitrate, shall be determined by binding arbitration in **Santa Fe, New Mexico**, before one arbitrator. Judgment on the award may be entered in any court having jurisdiction. **2. Class Action Waiver:** YOU AND USEAPI.NET AGREE THAT EACH MAY BRING CLAIMS AGAINST THE OTHER ONLY IN AN INDIVIDUAL CAPACITY AND NOT AS A PLAINTIFF OR CLASS MEMBER IN ANY PURPORTED CLASS OR REPRESENTATIVE PROCEEDING. Further, unless both you and useapi.net agree otherwise, the arbitrator may not consolidate more than one person’s claims with your claims and may not otherwise preside over any form of a representative or class proceeding. ### Governing Law and Jurisdiction These Terms shall be governed by the laws of the State of New Mexico, USA, without regard to its conflict of law principles. You agree that any legal action or proceeding arising out of or relating to these Terms shall be brought exclusively in the state or federal courts located in New Mexico. ### General Provisions If any provision of these Terms is found to be unenforceable, the remaining provisions will continue in full force and effect. These Terms constitute the entire agreement between you and useapi.net regarding the Services. We may modify these Terms at any time by posting the revised version on our website. # Privacy Policy This Privacy Policy describes how useapi.net ("we," "us," or "our") collects, uses, and shares information about you when you use our experimental third-party API services ("Services"). ### Information We Collect We collect information in the following ways: * **Information You Provide:** * **Account Information:** When you register for an account, we collect your email address and, optionally, your name. * **API Usage Data:** We log the API requests you make, which may include the prompts you submit, to operate and improve the Services. * **Information from Third Parties:** * **Payment Information:** We use third-party payment processors for payment processing. When you make a payment, they collects your payment information directly. We do not store your full credit card number but may have access to billing details such as your billing address, the last four digits of your card, and transaction history, which we use for accounting and support. ### How We Use Your Information We use the information we collect to: * Provide, maintain, and improve our Services. * Process transactions and send you related information, including confirmations and invoices. * Communicate with you, including responding to your comments and questions and providing customer service. * Monitor and analyze trends, usage, and activities in connection with our Services. * Prevent fraudulent transactions and other illegal activities. ### How We Share Your Information We do not sell or rent your personal information. We may share information in the following limited circumstances: * **With Service Providers:** We share information with third-party vendors who need it to perform services for us, such as Stripe for payment processing. * **For Legal Reasons:** We may disclose your information if we believe that disclosure is necessary to comply with a law, regulation, legal process, or governmental request. * **To Enforce Our Policies:** We may disclose your information to enforce our Terms of Service or to protect the rights, property, or safety of useapi.net, our users, or the public. ### Cookies and local storage Our website uses Google Analytics and the Google Ads conversion tag, which set cookies to measure visits, which pages people read, and whether an ad led to a subscription. The website also keeps a short list of the API pages you visited in your browser's local storage (for example "muse" or "google-flow"). It stays on your device, holds no personal information, and is sent only as a tag on the Stripe checkout link when you click Subscribe, so we can see which service led to a purchase. Clearing your browser's site data removes it. ### Data Security We employ industry-standard security measures to protect your information, including **Encryption in Transit (TLS)** for data transmitted between **your client application** and our **public API endpoints**. However, you acknowledge that **no method of transmission over the Internet or method of electronic storage is 100% secure.** We store and process your Credentials to facilitate the automation services you request. By providing these Credentials, you acknowledge the inherent risk of transmitting and storing sensitive data online and agree that useapi.net shall not be liable for any breach of this data unless caused by our willful misconduct. **Exclusion of Liability:** To the fullest extent permitted by law, useapi.net and its Managers, Members, and officers shall not be liable for any unauthorized access to, or use of, your Credentials or third-party accounts, resulting from: (a) hacking or malicious attacks on our systems that circumvent reasonable security measures; (b) your failure to secure your own API keys or passwords; or (c) the compromise of your data on third-party platforms. # Refund Policy We will issue a full refund within the first **fourteen (14) days** of your initial purchase if you have been unable to successfully generate content using our API, defined as fewer than **fifty (50)** successful generations during that period. To request a refund, email [support@useapi.net](mailto:support@useapi.net?subject=Refund%20Request) with your account email and a brief description of the issue. Approved refunds will be processed within one (1) business day. Payments made with cryptocurrency are non-refundable and are not eligible for this fourteen-day refund. Beyond the fourteen-day period, all fees paid for the Services are non-refundable. Refunds will not be granted for any other reasons, including but not limited to change of mind, underutilization of the Services, or account suspensions by Third-Party Services resulting from violations of their terms. # Contact <script> document.addEventListener('DOMContentLoaded', () => { const encodedEmail = "c3VwcG9ydEB1c2VhcGkubmV0"; const decodedEmail = atob(encodedEmail); const supportLink = document.createElement('a'); supportLink.href = "mailto:" + decodedEmail + "?subject=Customer Support"; supportLink.innerText = decodedEmail; const legalLink = document.createElement('a'); legalLink.href = "mailto:" + decodedEmail + "?subject=Legal Matters"; legalLink.innerText = decodedEmail; const supportPlaceholder = document.getElementById("email-placeholder-support"); if (supportPlaceholder) { supportPlaceholder.replaceWith(supportLink); } const legalPlaceholder = document.getElementById("email-placeholder-legal"); if (legalPlaceholder) { legalPlaceholder.replaceWith(legalLink); } }) </script> <p> For general inquiries and customer support, please contact us at <span id="email-placeholder-support" style="font-weight: bold;">[email protected]</span>. For questions about these Terms or other legal matters, please email us at <span id="email-placeholder-legal" style="font-weight: bold;">[email protected]</span>. Official legal notices and service of process should be sent to our registered agent at the following address: <img src="/assets/images/legal-address.svg" alt="registered agent mailing address (shown as an image)" width="599" height="15" style="display:inline;vertical-align:-1px;max-width:100%;height:auto;box-shadow:none;border:0"> </p> === URL: https://useapi.net/model-matrix === Document URL: https://useapi.net/model-matrix --- title: Model Matrix & MCP nav_icon: grid seo_title: "Model Matrix & MCP Servers: AI Models and Hosted MCP Servers" description: "Compare the AI models available through the useapi.net API across image, video, music, and speech generation, and find the hosted MCP servers for Claude Code, Cursor and VS Code." nav_order: 200 layout: home permalink: /model-matrix last_modified: 2026-11-19 --- # Model Matrix & MCP March 9, 2026 (November 19, 2026) All models below are available through a single [useapi.net subscription](/docs/subscription). Our API connects your AI website accounts to a fully-featured REST API, letting you automate all supported services at website subscription prices — significantly cheaper than official API rates. Use multiple accounts per service with automated load balancing included. An active subscription to the underlying service (e.g. Runway, Kling) is required. Feed our [complete API spec](/llms.txt) to your LLM to build integrations, or connect your AI assistant to our [hosted MCP servers](#mcp-servers). --- ## MCP Servers Hosted [Model Context Protocol](https://modelcontextprotocol.io) servers let Claude Code, Cursor, VS Code Copilot and other AI assistants use these services on your own accounts. Each one takes your useapi.net API token in the `Authorization: Bearer …` header, nothing needs to be installed, and all are listed in the official MCP Registry under `net.useapi`. The Claude app and ChatGPT add them as custom connectors and sign in with OAuth instead, see each server's page. | Service | Tools | What your AI assistant can do | |:------|:--:|:----| | [Google Flow](/docs/api-google-flow-v1/mcp) | 12 | chat with Google Flow Agent, approve spending, characters, voices, uploads | | [Muse](/docs/api-muse-v1/mcp) | 37 | Meta Muse images, 10-second videos with sound, chat | | [ACE Music](/docs/api-acemusic-v1/mcp) | 15 | ACE Music and ACE-Step songs, covers, mashups, stems, scores | | [Google Vids](/docs/api-google-vids-v1/mcp) | 18 | Gemini Omni video, talking avatars from a photo or a description, speech, extend, upscale, images | | [Gemini Notebook (NotebookLM)](/docs/api-gemini-notebook-v1/mcp) | 57 | notebooks, sources, chat, research, Audio and Video Overviews, slides | | [Dreamina](/docs/api-dreamina-v1/mcp) | 15 | Seedance video and images, upscale, smoother frame rate, draft to full quality, uploads | | [Kling](/docs/api-kling-v1/mcp) | 46 | Kling 4.0, 4.0 Flash, v3 and Omni video, avatars, lip-sync, Kling Image 4.0 images | | [PixVerse](/docs/api-pixverse-v2/mcp) | 38 | videos and effects, images, music and music videos, speech, upscale, uploads | | [Mureka](/docs/api-mureka-v1/mcp) | 40 | songs, characters from your own voice, stems, sheet music, speech | | [Flow Music](/docs/api-flowmusic-v1/mcp) | 18 | Lyria songs, lyrics, covers, remixes, stems | | [MiniMax](/docs/api-minimax-v1/mcp) | 38 | Hailuo, Veo and Seedance video, templates, images, agent, songs and covers, speech, voice cloning | ## Video Models | Model | API | |:------|:----| | Seedance 2.5 | [Dreamina](/docs/api-dreamina-v1) – up to 30s or 180s in long video mode, video edit, 50 omni refs, 480p/720p/1080p, 4K on CA, unlimited at 480p/720p with Dreamina's November 2026 offers<br>[Runway](/docs/api-runwayml-v1) – up to 30s, video edit and extend, 50 omni refs, 480p/720p/1080p<br>[PixVerse](/docs/api-pixverse-v2) – up to 30s, 50 omni refs, 480p/720p/1080p/4K, Pro+ plan | | Seedance 2.5 Flash | [Dreamina](/docs/api-dreamina-v1) – up to 30s, video edit, 20 omni refs, 480p/720p, unlimited with Dreamina's November 2026 offers, CA region only<br>[PixVerse](/docs/api-pixverse-v2) – up to 30s, 20 omni refs, 480p/720p | | Seedance 2.5 Draft | [Dreamina](/docs/api-dreamina-v1) – 480p drafts up to 30s, 50 omni refs, then full quality in 1080p, or 4K on CA, unlimited drafts with Dreamina's November 2026 offers<br>[PixVerse](/docs/api-pixverse-v2) – 480p drafts up to 30s, 50 omni refs, then a final in 1080p or 4K | | Seedance 2.0 | [Dreamina](/docs/api-dreamina-v1) – 720p/1080p/4K, 12 omni refs, unlimited at 720p with Dreamina's November 2026 offers<br>[Runway](/docs/api-runwayml-v1)<br>[MiniMax](/docs/api-minimax-v1)<br>[PixVerse](/docs/api-pixverse-v2) | | Seedance 2.0 Fast | [Dreamina](/docs/api-dreamina-v1) – 720p, 1080p/2K/4K upscaled from 720p, unlimited at 720p with Dreamina's November 2026 offers<br>[Runway](/docs/api-runwayml-v1)<br>[MiniMax](/docs/api-minimax-v1)<br>[PixVerse](/docs/api-pixverse-v2) | | Seedance 2.0 Mini | [Dreamina](/docs/api-dreamina-v1) – 720p, 1080p/2K/4K upscaled from 720p, unlimited at 720p with Dreamina's November 2026 offers<br>[Runway](/docs/api-runwayml-v1)<br>[MiniMax](/docs/api-minimax-v1)<br>[PixVerse](/docs/api-pixverse-v2) | | Seedance 1.5 Pro | [Dreamina](/docs/api-dreamina-v1) – US region only | | Seedance 1.0 Pro | [Dreamina](/docs/api-dreamina-v1) – CA region only, 5/10 s, 1080p | | Seedance 1.0 Mini | [Dreamina](/docs/api-dreamina-v1) – US region only | | Seedance 1.0 Fast | [Dreamina](/docs/api-dreamina-v1) – CA region only, 5/10 s, 720p/1080p | | Grok Imagine | [PixVerse](/docs/api-pixverse-v2) | | Grok Imagine 1.5 | [Runway](/docs/api-runwayml-v1)<br>[PixVerse](/docs/api-pixverse-v2) | | HappyHorse 1.1 | [Dreamina](/docs/api-dreamina-v1) – CA region only, 4-15 s, 720p/1080p, 9 image refs | | HappyHorse 1.0 | [Runway](/docs/api-runwayml-v1)<br>[PixVerse](/docs/api-pixverse-v2) | | Veo 3.1 Quality | [Google Flow](/docs/api-google-flow-v1) – retiring 2026-12-05, then runs as Omni 1.2 Flash at 720p; Quality, Fast and Lite step by step in the [Veo 3.1 API tutorial](/docs/articles/google-flow-bash) | | Veo 3.1 Fast | [Google Flow](/docs/api-google-flow-v1) – retiring 2026-12-05, then runs as Veo 3.1 Lite | | Veo 3.1 Lite | [Google Flow](/docs/api-google-flow-v1) | | Veo 3.1 Lite Lower Priority | [Google Flow](/docs/api-google-flow-v1) – free on Ultra $199 plan (plan manager only) | | Veo 3.1 | [MiniMax](/docs/api-minimax-v1)<br>[Runway](/docs/api-runwayml-v1)<br>[PixVerse](/docs/api-pixverse-v2) – Lite / Standard / Fast | | Gemini Omni 1.2 Flash | [Google Flow](/docs/api-google-flow-v1) – as `omni-flash-1.2`, 3-15s, 360p or 720p, native audio, [extend](/docs/api-google-flow-v1/post-google-flow-videos-extend) up to 10s at a time with voices, free plan up to 10s<br>[Google Vids](/docs/api-google-vids-v1) – labelled *Omni* in Vids. Google AI Pro or Ultra, 3-15s in 720p or 1080p, start image, up to 3 image refs or avatars, extend up to 10s at a time to about 34s, upscale, edit up to 15s. Uses the monthly Vids allowance, not Flow credits | | Gemini Omni Flash | [Google Flow](/docs/api-google-flow-v1) – labelled *Omni 1.1 Flash* in Flow, retiring 2026-12-05, then runs as Omni 1.2 Flash. Plus, Pro or Ultra, audio-native T2V/R2V at 4/6/8/10s in 360p or 720p, start+end frames, V2V edit, up to 7 image refs, up to 5 voice refs<br>[PixVerse](/docs/api-pixverse-v2) – 720p, 3-10s, native audio, edit a clip with image + video references | | Kling 4.0 | [Kling](/docs/api-kling-v1) – a real run in the [Kling 4.0 API tutorial](/docs/articles/kling-4-api)<br>[PixVerse](/docs/api-pixverse-v2) | | Kling 4.0 Flash | [Kling](/docs/api-kling-v1) – 720p, 3-20 s with sound, text, start image or Omni references | | Kling v3 / O3 | [Kling](/docs/api-kling-v1)<br>[Runway](/docs/api-runwayml-v1)<br>[PixVerse](/docs/api-pixverse-v2) | | Kling v3 Turbo | [Kling](/docs/api-kling-v1) | | Kling O1 (elements) | [Kling](/docs/api-kling-v1) | | Kling 2.6 (native audio, motion control) | [Kling](/docs/api-kling-v1)<br>[Runway](/docs/api-runwayml-v1) | | Kling 2.5 / 2.1 / 1.6 / 1.5 | [Kling](/docs/api-kling-v1) | | Kling Motion Control (apply motion from video to image, v3.0 / v2.6) | [Kling](/docs/api-kling-v1)<br>[Runway](/docs/api-runwayml-v1) | | PixVerse v6 / v5.6 / v5.5 / v5 / v5-fast / c1 | [PixVerse](/docs/api-pixverse-v2) | | Gen-4.5 | [Runway](/docs/api-runwayml-v1) | | Gen-4 | [Runway](/docs/api-runwayml-v1) | | Gen-4 Turbo | [Runway](/docs/api-runwayml-v1) | | Gen-4 Aleph (video-to-video) | [Runway](/docs/api-runwayml-v1) | | Hailuo 3.0 | [MiniMax](/docs/api-minimax-v1) – 768p / 2K, native audio, omni references<br>[PixVerse](/docs/api-pixverse-v2) – as `minimax-h3`, 768p / 2K, 5-15s, up to 9 reference images<br>[Runway](/docs/api-runwayml-v1) – as `minimax-h3`, 768p / 2K, 5-15s, 9 images + 3 ref videos + 3 ref audios, or first/last frame | | Hailuo 3.0 Max | [PixVerse](/docs/api-pixverse-v2) – as `minimax-h3-max`, 480p / 768p / 1080p, 5-15s, up to 9 reference images<br>[Runway](/docs/api-runwayml-v1) – as `minimax-h3-max`, 480p / 768p, 5-15s, first/last frame, prompt expansion | | Hailuo 01 | [MiniMax](/docs/api-minimax-v1) – unlimited on Max, monthly or yearly | | Hailuo 02 / 2.3 | [MiniMax](/docs/api-minimax-v1) – unlimited on Max, monthly or yearly | | FLUX 3 | [PixVerse](/docs/api-pixverse-v2) – text-to-video and image-to-video, 5-20s, 720p/1080p, audio toggle<br>[Runway](/docs/api-runwayml-v1) – text-to-video, first frame, video extend, 5-20s, 720p/1080p, audio toggle | | Wan 3.0 | [PixVerse](/docs/api-pixverse-v2) – t2v, i2v, transition and fusion, 2-30s, 480p/720p/1080p, 10 images + 5 ref videos + 5 ref audios, audio toggle<br>[Runway](/docs/api-runwayml-v1) – 2-30s, 480p/720p/1080p, first/last frame or 10 images + 5 ref videos + 5 ref audios, audio toggle<br>[Dreamina](/docs/api-dreamina-v1) – CA region only, 4-15 s, 720p/1080p, 10 images + 5 videos + 5 audio refs | | Wan 3.0 Prime | [Runway](/docs/api-runwayml-v1) – faster tier of Wan 3.0, same parameters | | Wan 2.6 Flash | [Runway](/docs/api-runwayml-v1) | | Wan 2.2 Animate | [Runway](/docs/api-runwayml-v1) | | Muse (Meta) | [Muse](/docs/api-muse-v1) – Meta's muse.ai agent, no model choice. About 10s at about 720p with audio and speech, text/image/video to video, up to 9 image + 3 video + 3 audio inputs, aspect ratio by prompt, free plan works. Meta sells no Muse video API of its own: [Meta Muse video API options, compared](/docs/articles/meta-muse-video-api) | Sora 2 is no longer available: OpenAI shut it down on September 24, 2026. ## Image Models | Model | API | |:------|:----| | Midjourney V7 / NiJi 7 | [MiniMax](/docs/api-minimax-v1) | | GPT Image 2.5 | [PixVerse](/docs/api-pixverse-v2) – as `gpt-image-2.5-flare` and `gpt-image-2.5-sunburst`, unlimited on Ultra, up to 4K, 16 refs, `low`/`medium`/`high`/`xhigh`/`max` detail, +5 credits per reference, Standard+ plan<br>[Dreamina](/docs/api-dreamina-v1) – as `gpt-image-2.5-flare` and `gpt-image-2.5-sunburst`, unlimited with Dreamina's November 2026 offers, 1K/2K/4K, 6 refs | | GPT Image 2.0 | [PixVerse](/docs/api-pixverse-v2) – unlimited on Ultra, up to 4K, 9 refs, `low`/`medium`/`high` detail<br>[Runway](/docs/api-runwayml-v1) – up to 4K, 14 refs, `low`/`medium`/`high` quality<br>[MiniMax](/docs/api-minimax-v1) – 1K/2K/4K, 11 aspect ratios, up to 16 refs<br>[Dreamina](/docs/api-dreamina-v1) – 1K/2K/4K, 6 refs, ratios `1:1`/`2:3`/`3:2` | | GPT Image 1.5 | [Runway](/docs/api-runwayml-v1) – unlimited<br>[MiniMax](/docs/api-minimax-v1) – unlimited on yearly Pro, Master and Max | | GPT Image 1 Mini | [Runway](/docs/api-runwayml-v1) – unlimited | | Nano Banana Pro / Gemini 3 Pro Image | [Google Flow](/docs/api-google-flow-v1)<br>[Runway](/docs/api-runwayml-v1) – unlimited<br>[PixVerse](/docs/api-pixverse-v2) – unlimited on Ultra<br>[MiniMax](/docs/api-minimax-v1) – unlimited on yearly Pro, Master and Max<br>[Dreamina](/docs/api-dreamina-v1) – as `nano-banana-pro`, unlimited with Dreamina's November 2026 offers, 1K/2K/4K, 6 refs | | Nano Banana 2.1 | [Google Flow](/docs/api-google-flow-v1) – `nano-banana-2`<br>[PixVerse](/docs/api-pixverse-v2) – `nano-banana-2.1`, unlimited on Premium+<br>[Dreamina](/docs/api-dreamina-v1) – `nano-banana-2.1`, unlimited with Dreamina's November 2026 offers, CA region only, 1K/2K/4K | | Nano Banana 2 / Gemini 3.1 Flash Image | [Runway](/docs/api-runwayml-v1) – unlimited<br>[PixVerse](/docs/api-pixverse-v2) – unlimited on Premium+<br>[MiniMax](/docs/api-minimax-v1) – unlimited on yearly Pro, Master and Max | | Nano Banana 2 Lite / Gemini 3.1 Flash-Lite Image | [Google Flow](/docs/api-google-flow-v1) – works with free Google accounts<br>[Runway](/docs/api-runwayml-v1) – unlimited<br>[PixVerse](/docs/api-pixverse-v2) – unlimited on Pro+ | | Nano Banana / Gemini 2.5 Flash | [Runway](/docs/api-runwayml-v1) – unlimited<br>[PixVerse](/docs/api-pixverse-v2) – unlimited on Premium+ | | Seedream 5.5 | [Dreamina](/docs/api-dreamina-v1) – unlimited with Dreamina's November 2026 offers, CA region only, 1.5K/2K, transparent background | | Seedream 5.0 | [Runway](/docs/api-runwayml-v1) – unlimited<br>[MiniMax](/docs/api-minimax-v1) – unlimited on yearly Pro, Master and Max | | Seedream 5.0 Pro | [PixVerse](/docs/api-pixverse-v2) – unlimited on Ultra<br>[Dreamina](/docs/api-dreamina-v1) – 2K/4K, 1.5K on CA, 6 refs | | Seedream 5.0 Flash | [Dreamina](/docs/api-dreamina-v1) – US region only, 1.5K/2K/4K | | Seedream 5.0 Lite | [Dreamina](/docs/api-dreamina-v1) – CA region only<br>[PixVerse](/docs/api-pixverse-v2) – unlimited on Ultra | | Seedream 4.5 | [Dreamina](/docs/api-dreamina-v1)<br>[MiniMax](/docs/api-minimax-v1) – unlimited on yearly Pro, Master and Max<br>[PixVerse](/docs/api-pixverse-v2) – unlimited on Ultra | | Seedream 4.0 | [Dreamina](/docs/api-dreamina-v1)<br>[PixVerse](/docs/api-pixverse-v2) – unlimited on Premium+ | | Seedream 4.7 / 4.6 / 4.1 / 3.1 / 3.0 | [Dreamina](/docs/api-dreamina-v1) (4.7 and 3.1 are CA region only) | | Kling Image 4.0 | [Kling](/docs/api-kling-v1/post-kling-images-omni) – up to 8K, Series Mode, style / tone / font presets, product detail pages and web designs | | Kling Image v3 / O3 | [Kling](/docs/api-kling-v1)<br>[PixVerse](/docs/api-pixverse-v2) | | Gen-4 / Gen-4 Turbo | [Runway](/docs/api-runwayml-v1) | | FLUX 3 Image (Black Forest Labs, up to 4K, 10 refs) | [Runway](/docs/api-runwayml-v1) | | FLUX.2 Max (Black Forest Labs, up to 4K, 8 refs) | [Runway](/docs/api-runwayml-v1) | | FLUX.2 Klein (Black Forest Labs, up to 2K, 4 refs) | [Runway](/docs/api-runwayml-v1) | | Qwen Image | [PixVerse](/docs/api-pixverse-v2) – unlimited on Pro+ | | MiniMax H3 Image / H3 Image Highspeed | [MiniMax](/docs/api-minimax-v1) – 1K / 2K / 4K, 16 refs with `@Image1` mentions | | image-01 | [MiniMax](/docs/api-minimax-v1) | | Muse (Meta) | [Muse](/docs/api-muse-v1) – Meta's muse.ai agent, no model choice. About 2-2.5 MP, up to 9 input images, aspect ratio by prompt, free plan works | ## Music Models | Model | API | |:------|:----| | Lyria 3.5 (songs, vocals, instrumentals, lyrics, cover/restyle, lyrics-adjust remix, extend/replace, effects) | [Flow Music](/docs/api-flowmusic-v1) | | Lyria 3 Pro (songs, vocals, instrumentals, lyrics, cover/restyle, lyrics-adjust remix, extend/replace, effects) | [Flow Music](/docs/api-flowmusic-v1)<br>[PixVerse](/docs/api-pixverse-v2) – prompt + image refs, model-written lyrics | | Mureka V9.5 / V9 / O2 / V8 / V7.6 / V7.5-all (songs, instrumentals, custom or model-written lyrics, vocal references, characters from your own voice, motif seeding, remix, stem extraction with MIDI and DAW sessions, sheet music) | [Mureka](/docs/api-mureka-v1) | | TemPolor (text, lyrics, MIDI, voice cloning) | [TemPolor](/docs/api-tempolor-v1) – no per-song charge on Ultra | | Music 3.0 (MiniMax — songs, instrumentals, custom or model-written lyrics, SSE audio streaming) | [MiniMax](/docs/api-minimax-v1) – up to 3 tracks per call | | Music 2.6 (MiniMax — songs, instrumentals, custom or model-written lyrics) | [MiniMax](/docs/api-minimax-v1)<br>[PixVerse](/docs/api-pixverse-v2) | | Music 2.0 (via the [MiniMax Agent](/docs/api-minimax-v1/post-minimax-agent)) | [MiniMax](/docs/api-minimax-v1) | | ElevenLabs Music (songs, instrumentals, custom or model-written lyrics) | [PixVerse](/docs/api-pixverse-v2) | | ACE Music v1 (songs from a prompt or your own style and lyrics, 30 s to 10 min, WAV, MIDI and MusicXML downloads, stems, scores) | [ACE Music](/docs/api-acemusic-v1) – two songs per request | | ACE Music v1.1 Preview (covers and mashups of your songs and uploads, writes a score first) | [ACE Music](/docs/api-acemusic-v1) | | ACE-Step v1.5 XL (open-source, songs, remixes, edits of part of a song, tempo, key and meter) | [ACE Music](/docs/api-acemusic-v1) – no credits on any plan | ## Speech & Audio Models | Model | API | |:------|:----| | ElevenLabs text-to-speech (Multilingual v2, v3 with inline audio tags, Turbo v2.5 — ~20 voices) | [PixVerse](/docs/api-pixverse-v2) | | Mureka Speech (voice cloning, multi-speaker conversations) | [Mureka](/docs/api-mureka-v1) | | Gemini text-to-speech (Google Vids voices) | [Google Vids](/docs/api-google-vids-v1/post-google-vids-speech) – 30 voices, audio tags like `[whisper]`, 2,500 characters a call, WAV | | MiniMax Speech 2.8 (text-to-speech — HD / Turbo, emotion control, 600+ voices, 40 languages) | [MiniMax](/docs/api-minimax-v1) – also 2.6, 2.5, 02 and 01, each in hd and turbo, 5,000 characters a call or 10,000 on turbo, word timings, voice cloning<br>[PixVerse](/docs/api-pixverse-v2) | | Kling Audio (video audio generation) | [Kling](/docs/api-kling-v1) | | Avatars 2.0 (lip-sync video with TTS) | [Kling](/docs/api-kling-v1) | | Google Vids talking avatar (an avatar from a photo or a description reads your script) | [Google Vids](/docs/api-google-vids-v1/post-google-vids-videos-avatar) – up to 30s, 720p landscape, 30 Gemini voices, audio tags | | Act Two (character animation) | [Runway](/docs/api-runwayml-v1) | | Lip Sync | [Runway](/docs/api-runwayml-v1)<br>[PixVerse](/docs/api-pixverse-v2) | ## Notebook & Research Models (Gemini Notebook, formerly NotebookLM) | Model | API | |:------|:----| | Audio Overview (AI podcast — deep dive, brief, critique or debate) | [Gemini Notebook](/docs/api-gemini-notebook-v1) – short, default or long, any language, focus prompt, `m4a` | | Video Overview (explainer, brief or short) | [Gemini Notebook](/docs/api-gemini-notebook-v1) – 9 visual styles or a custom style prompt, `mp4` | | Video Overview, cinematic | [Gemini Notebook](/docs/api-gemini-notebook-v1) – not on the Free plan, `mp4` | | Slide deck (detailed or presenter) | [Gemini Notebook](/docs/api-gemini-notebook-v1) – `pdf` + `pptx` + one image per slide, revise any slide with a prompt | | Infographic | [Gemini Notebook](/docs/api-gemini-notebook-v1) – landscape, portrait or square, 11 styles, `png` | | Report (briefing, study guide, blog post or your own prompt) and interactive report | [Gemini Notebook](/docs/api-gemini-notebook-v1) – Markdown (report), plain text (interactive report) | | Data table | [Gemini Notebook](/docs/api-gemini-notebook-v1) – rows of cells from your instructions | | Quiz and flashcards | [Gemini Notebook](/docs/api-gemini-notebook-v1) – JSON, quantity and difficulty | | Mind map | [Gemini Notebook](/docs/api-gemini-notebook-v1) – JSON tree | | Deep Research (cited report from the web) and Discover sources | [Gemini Notebook](/docs/api-gemini-notebook-v1) – import the report and the sources into a notebook | | Grounded chat with citations | [Gemini Notebook](/docs/api-gemini-notebook-v1) – answers from your sources (web, YouTube, files, Google Drive), follow-ups, notes | ## Other | Feature | API | |:--------|:----| | Face Swap (HiFidelity, ARTIFY, multi-face morphing) | [InsightFaceSwap](/docs/api-faceswap-v1) | | Image Upscale | [Runway](/docs/api-runwayml-v1) – free and unlimited<br>[PixVerse](/docs/api-pixverse-v2/post-pixverse-images-upscale) – PixVerse Upscale or Topaz Gigapixel, any image, 1080p / 2K / 4K | | Video Upscale (Topaz) | [Runway](/docs/api-runwayml-v1) – Topaz 4K, any source video, up to 40s<br>[PixVerse](/docs/api-pixverse-v2/post-pixverse-videos-upscale) – Topaz Proteus, Starlight Fast, Starlight Precise or PixVerse Upscale, any source video up to 3 min, 1080p / 4K | | Video Extend | [Runway](/docs/api-runwayml-v1)<br>[PixVerse](/docs/api-pixverse-v2) | | Video Effects (900+ effects) | [PixVerse](/docs/api-pixverse-v2) | | Elements (reusable character/object references) | [Kling](/docs/api-kling-v1) | | Frames | [Runway](/docs/api-runwayml-v1) | | AI creative agent chat (plans, generates and edits images and videos in a conversation) | [Google Flow](/docs/api-google-flow-v1/agent) – Google Flow Agent, references and `@`-mentions, approval before spending, replies streamed over SSE<br>[Muse](/docs/api-muse-v1/chat-streaming-guide) – Meta's Muse agent, also research, code, documents and a live web browser, replies streamed over SSE | === URL: https://useapi.net/docs/postman-swagger === Document URL: https://useapi.net/docs/postman-swagger --- title: Integrations nav_icon: plug description: "Connect useapi.net APIs to Postman, n8n and other automation tools, MCP clients and LLM editors, with a Postman collection for every active API." nav_order: 79000 layout: home --- # Integrations Every useapi.net endpoint is a plain HTTPS request with your API token in the `Authorization` header, so it works from any tool that can make one. This page covers Postman, n8n and other automation tools, MCP clients, and machine-readable descriptions of the APIs. We maintain a Postman collection for every API we currently offer, in the public [useapi.net Postman workspace](https://www.postman.com/useapinet/useapi-net). Each collection covers the endpoints of one API, and most requests link back to their page in these docs. --- ### Postman collections | API docs | Postman workspace | Raw collection JSON | |:---|:---|:---| | [Google Flow API v1](/docs/api-google-flow-v1) | [Open in Postman](https://www.postman.com/useapinet/useapi-net/collection/29112081-db5b420d-b5a6-4710-91b2-82980b4cddd5) | [`google-flow-v1.json`](/assets/postman/google-flow-v1.json) | | [Dreamina API v1](/docs/api-dreamina-v1) | [Open in Postman](https://www.postman.com/useapinet/useapi-net/collection/29112081-347618e4-ef47-4ca4-bdee-72d321dcb4f2) | [`dreamina-v1.json`](/assets/postman/dreamina-v1.json) | | [Kling API v1](/docs/api-kling-v1) | [Open in Postman](https://www.postman.com/useapinet/useapi-net/collection/29112081-d26e35d5-af3a-44a7-9810-3aeb6351c169) | [`kling-v1.json`](/assets/postman/kling-v1.json) | | [MiniMax API v1](/docs/api-minimax-v1) | [Open in Postman](https://www.postman.com/useapinet/useapi-net/collection/29112081-ded91f3a-ca96-4842-ad7b-6b1244fed442) | [`minimax-v1.json`](/assets/postman/minimax-v1.json) | | [Runway API v1](/docs/api-runwayml-v1) | [Open in Postman](https://www.postman.com/useapinet/useapi-net/collection/29112081-c6d86d09-998e-4e9c-9d6d-54a9573cd9a7) | [`runwayml-v1.json`](/assets/postman/runwayml-v1.json) | | [PixVerse API v2](/docs/api-pixverse-v2) | [Open in Postman](https://www.postman.com/useapinet/useapi-net/collection/29112081-946e4e63-64de-4265-b388-6be967e9b061) | [`pixverse-v2.json`](/assets/postman/pixverse-v2.json) | | [Mureka API v1](/docs/api-mureka-v1) | [Open in Postman](https://www.postman.com/useapinet/useapi-net/collection/29112081-6ca3c497-835e-44bc-a2be-978be82b69cc) | [`mureka-v1.json`](/assets/postman/mureka-v1.json) | | [Google Vids API v1](/docs/api-google-vids-v1) | [Open in Postman](https://www.postman.com/useapinet/useapi-net/collection/29112081-9ef3d017-d44c-4f43-a4cb-7351b9b265df) | [`google-vids-v1.json`](/assets/postman/google-vids-v1.json) | | [Muse API v1](/docs/api-muse-v1) | [Open in Postman](https://www.postman.com/useapinet/useapi-net/collection/29112081-8619be70-7909-4fca-a03a-3b89e455c044) | [`muse-v1.json`](/assets/postman/muse-v1.json) | | [Gemini Notebook API v1](/docs/api-gemini-notebook-v1) | [Open in Postman](https://www.postman.com/useapinet/useapi-net/collection/29112081-40696e39-d128-417e-984b-fe1b97e7bb00) | [`gemini-notebook-v1.json`](/assets/postman/gemini-notebook-v1.json) | | [FlowMusic API v1](/docs/api-flowmusic-v1) | [Open in Postman](https://www.postman.com/useapinet/useapi-net/collection/29112081-3386ba6a-1539-415b-b9cf-7ef1c9d7939d) | [`flowmusic-v1.json`](/assets/postman/flowmusic-v1.json) | | [TemPolor API v1](/docs/api-tempolor-v1) | [Open in Postman](https://www.postman.com/useapinet/useapi-net/collection/29112081-e6199d78-0334-4936-bb19-94375d412f84) | [`tempolor-v1.json`](/assets/postman/tempolor-v1.json) | | [InsightFaceSwap API v1](/docs/api-faceswap-v1) | [Open in Postman](https://www.postman.com/useapinet/useapi-net/collection/29112081-9ac29d7b-9ca5-42c9-9d86-b9e29a16df56) | [`faceswap-v1.json`](/assets/postman/faceswap-v1.json) | | [ACE Music API v1](/docs/api-acemusic-v1) | [Open in Postman](https://www.postman.com/useapinet/useapi-net/collection/29112081-fb6c1594-534a-4d6f-9fdd-deea77bec055) | [`acemusic-v1.json`](/assets/postman/acemusic-v1.json) | The raw JSON files are the same collections we sync to the workspace, in Postman Collection v2.1 format. ### Use a Postman collection 1. Get your useapi.net API token, see [Setup useapi.net](/docs/start-here/setup-useapi). 2. Open the collection in the workspace and click Fork to copy it into your own workspace. You can also download the raw JSON from the table above and use Import in the Postman app. 3. Open the collection's Variables tab and paste your token into `api-token`. Requests send it as `Authorization: Bearer {API token}`. 4. Fill in the other collection variables the requests use, such as the service account `email` or a `jobid` returned by an earlier call. 5. Pick a request, adjust its body or query parameters, and send it. The endpoint's docs page lists every parameter and response field. Most generation endpoints are asynchronous. Send the create request first, then call the matching job endpoint with the returned id until the job completes. Every endpoint page also has a Try It form if you would rather test in the browser. ### n8n, Make.com and other automation tools No plugin is needed. In [n8n](https://n8n.io), add an HTTP Request node, take the method and URL from the endpoint's docs page, and send your token as an `Authorization: Bearer {API token}` header. Most generation endpoints are asynchronous: poll the job endpoint until the job completes, or, where the endpoint accepts `replyUrl`, set it to an n8n Webhook node URL so the result is pushed to your workflow. n8n AI Agent workflows can also call our hosted MCP servers through the MCP Client Tool node. Use the server URL from that service's MCP page, listed under [MCP Servers](/model-matrix#mcp-servers), and your API token as a Bearer auth header. [Gemini Notebook (NotebookLM) podcasts with n8n](/docs/articles/notebooklm-n8n-podcast) is a full worked example. Make.com, Zapier and similar tools work the same way through their HTTP modules. To upload a raw file from Make.com, see [this Q&A answer](/docs/questions-and-answers#how-post-raw-content-to-runwaymlassets-and-minimaxfiles-using-makecom-and-similar-nocode-tools). ### MCP servers Our hosted MCP servers expose the APIs as tools to Claude Code, Cursor, VS Code and other MCP clients, with your API token in the `Authorization` header. [MCP Servers](/model-matrix#mcp-servers) links to each server's page, which gives its URL and setup. ### OpenAPI / Swagger We do not publish separate OpenAPI (Swagger) specs for the current APIs. The Postman collections are the machine-readable description of each API. If your tooling needs OpenAPI, convert the raw collection JSON with a Postman-to-OpenAPI converter, and check the result against the endpoint docs. ### Machine-readable discovery - [`/.well-known/api-catalog`](/.well-known/api-catalog) lists every active API with its docs page and its collection JSON (RFC 9727). - [`/auth.md`](/auth.md) describes how API authentication works, for AI agents. - [LLM tools](/llm-tools) has per-service documentation files, `llms.txt`, and drop-in context files for Claude Code and Cursor. === URL: https://useapi.net/docs/subscription === Document URL: https://useapi.net/docs/subscription --- title: Subscription nav_icon: price description: "Buy useapi.net for $15 a month to connect 3 of your own accounts per AI service, $10 for each extra 3, paid by card through Stripe or with crypto." nav_order: 250 layout: home --- # Subscription One subscription is **$15 a month**, and **each extra subscription is $10 a month**. One subscription covers every API on useapi.net with one API token and lets you connect up to 3 of your own accounts on each service. Each extra subscription adds 3 more accounts on every service. You keep paying each service for its own plan, at website prices. | Subscriptions | Accounts per service / in total (14 services) | Monthly total | |:--|:-:|:-:| | 1 | 3 / 42 | **$15** | | 2 | 6 / 84 | **$25** | | 3 | 9 / 126 | **$35** | | each extra | +3 / +42 | **+$10** | [Subscribe · $15/month](https://buy.stripe.com/8x2aEX4Bd8Vh9PMg4qeUU03?client_reference_id=subscription) [Pay with crypto](https://pay.boomfi.xyz/38UTma36Rv0DrY8NlH1r2SEG7VK) Secure checkout by Stripe: cards, Link, Apple Pay, Google Pay, Alipay, Cash App Pay, Amazon Pay and Klarna, depending on your country. Need more than 3 accounts on a service? Set the quantity at checkout: the first subscription is $15 and each extra one is $10. Already subscribed? Change the quantity in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) instead of buying again. Crypto payments through BoomFi cover one subscription and are non-refundable. ## How many subscriptions do I need? Each subscription adds 3 accounts on every service: `1 sub = $15 → 2 = $25 → 3 = $35 → 4 = $45` The service where you connect the most accounts sets how many subscriptions you need. For example, 5 Google Flow accounts and 2 Kling accounts need 2 subscriptions. <div class="input-field"> <div class="input-field-row"> <label for="accountsNeeded">How many accounts do you need on one service? <input id="accountsNeeded" type="number" class="input-element" value="3" min="1" max="100" style="width:80px"> </label> </div> </div> <div id="calcResult" style="margin-top:10px;"> <table> <tr><td>Subscriptions needed</td><td id="subsNeeded"><b>1</b></td></tr> <tr><td>Accounts per service</td><td id="accsPerService">3</td></tr> <tr><td>Monthly cost</td><td id="monthlyCost"><b>$15</b></td></tr> </table> </div> Use "Subscriptions needed" as the quantity at checkout, or change it later in the [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo). <script> (function() { function updateCalc() { const needed = parseInt(document.getElementById('accountsNeeded').value) || 1; const subs = Math.ceil(needed / 3); document.getElementById('subsNeeded').innerHTML = '<b>' + subs + '</b>'; document.getElementById('accsPerService').textContent = subs * 3; document.getElementById('monthlyCost').innerHTML = '<b>$' + (15 + (subs - 1) * 10) + '</b>'; } document.getElementById('accountsNeeded')?.addEventListener('input', updateCalc); if (document.readyState === 'loading') { document.addEventListener('DOMContentLoaded', updateCalc); } else { updateCalc(); } })(); </script> ## After you pay Payment takes less than a minute. Open the link in your welcome email (check spam too) to see your API token, then follow [Setup useapi.net](/docs/start-here/setup-useapi). The email you pay with becomes your useapi.net account. [GET account](/docs/account-management/get-account) shows your subscription status and how many accounts you have connected on each service. ## Manage or cancel - The [Stripe Customer Portal](https://billing.stripe.com/p/login/28obM4fZld0JaHu6oo) changes the quantity, cancels a Stripe subscription and has your receipts. A quantity change mid-month is prorated. - The [BoomFi Customer Portal](https://app.boomfi.xyz/customer) manages a crypto subscription. We refund in full within the first fourteen (14) days of your first purchase if you have fewer than fifty (50) successful generations. See our [Refund Policy](/docs/legal#refund-policy), and email [support@useapi.net](mailto:support@useapi.net?subject=Refund%20Request) to request one. ## Supported services - [Google Flow](/docs/api-google-flow-v1): Veo 3.1, Omni 1.2 Flash and Omni 1.1 Flash videos and Nano Banana images on your Google AI plan, instead of paying per second on Google's Veo API - [Muse API](/docs/api-muse-v1): images and 10-second videos with spoken dialogue from Meta's Muse agent, which Meta's own API doesn't offer - [ACE Music API](/docs/api-acemusic-v1): songs from ACE Music v1, v1.1 and the open-source ACE-Step, with covers, mashups, stems and sheet music, two songs per request - [Google Vids API](/docs/api-google-vids-v1): Gemini Omni videos with sound, video edits and talking avatars from Google Vids, which has no public API - [Gemini Notebook API (NotebookLM API)](/docs/api-gemini-notebook-v1): podcasts, Video Overviews and slide decks from your sources, on free Google accounts too - [Dreamina API](/docs/api-dreamina-v1): Seedance 2.5 and 2.0 videos, real faces included, plus Seedream and GPT Image images - [Kling API](/docs/api-kling-v1): Kling 4.0, which Kling's own API doesn't sell yet, plus Kling 3.0, Omni and lip-sync - [PixVerse API](/docs/api-pixverse-v2): PixVerse V6 and C1 with Off-Peak mode, plus Seedance 2.5, Kling O3 and Veo 3.1 on the same plan - [Mureka API](/docs/api-mureka-v1): Mureka V9.5 songs, an alternative to Suno and Udio, with stems and sheet music - [FlowMusic API](/docs/api-flowmusic-v1): full songs with vocals on Google's Lyria 3.5 and Lyria 3 Pro, plus covers, remixes and stems - [MiniMax API](/docs/api-minimax-v1): Hailuo 3.0 videos, Speech 2.8 voices and Music 3.0 songs - [Runway API](/docs/api-runwayml-v1): Gen-4.5, plus Gen-4, Aleph video editing and lip sync, which Runway's developer API doesn't offer - [TemPolor API](/docs/api-tempolor-v1): royalty-free songs and instrumentals, sung in a voice you clone, which TemPolor's own API doesn't offer - [InsightFaceSwap API](/docs/api-faceswap-v1): the InsightFaceSwap Discord bot as a REST API, for face swaps, AI headshots and new backgrounds ## MCP servers for AI assistants The same subscription covers our hosted MCP servers, which let the Claude app, ChatGPT, Claude Code, Cursor, VS Code Copilot and other AI assistants work with your accounts: [Google Flow](/docs/api-google-flow-v1/mcp), [Muse](/docs/api-muse-v1/mcp), [ACE Music](/docs/api-acemusic-v1/mcp), [Google Vids](/docs/api-google-vids-v1/mcp), [Gemini Notebook (NotebookLM)](/docs/api-gemini-notebook-v1/mcp), [Dreamina](/docs/api-dreamina-v1/mcp), [Kling](/docs/api-kling-v1/mcp), [PixVerse](/docs/api-pixverse-v2/mcp), [Mureka](/docs/api-mureka-v1/mcp), [Flow Music](/docs/api-flowmusic-v1/mcp) and [MiniMax](/docs/api-minimax-v1/mcp). The [MCP Servers](/model-matrix#mcp-servers) table shows what each one can do. === URL: https://useapi.net/docs/support === Document URL: https://useapi.net/docs/support --- title: Support nav_icon: headset description: "Get help with every useapi.net API: ask your AI assistant with our LLM-ready docs for the fastest answer, or reach the team on Discord, Telegram or email at support@useapi.net." nav_order: 80000 has_children: true layout: home --- # Support We're a small team, and the people who build useapi.net are the ones answering. Tell us what you're making and where it's stuck, and we'll get it working with you. Something not working? Check the [status page](/status) first: it shows each API's state now, hour by hour for the last day, and every incident we confirmed. ## Fastest: ask your AI assistant Most setup and API questions get answered faster by your own AI assistant than by waiting for us, as long as it has our docs. Give it one of these and ask away: <div class="support-cards"> <a class="support-card" href="/llm-tools"><span class="top">Claude Code and Cursor</span> Install the drop-in context files once, and your editor knows every useapi.net endpoint.</a> <a class="support-card" href="/llms-full.txt"><span class="top">ChatGPT, Claude, Gemini</span> Attach the complete API spec to the chat, or the LLM-friendly API spec linked on each API page.</a> <a class="support-card" href="/model-matrix#mcp-servers"><span class="top">MCP servers</span> Hosted servers for eight services, so your assistant can call the API itself.</a> </div> ## Talk to us <div class="support-cards"> <a class="support-card" href="https://discord.gg/w28uK3cnmF"><span class="top"><img class="ui-icon" src="/assets/images/discord.svg" alt="" aria-hidden="true"> Discord</span> Fastest for setup questions. Share a screenshot or a request id.</a> <a class="support-card" href="https://t.me/use_api"><span class="top"><img class="ui-icon" src="/assets/images/telegram.svg" alt="" aria-hidden="true"> Telegram</span> Quick questions, plus release news on @use_api.</a> <div class="support-card"><span class="top">Email</span><a href="mailto:support@useapi.net">support@useapi.net</a> Billing, refunds and anything private.</div> </div> We usually reply within a few hours. We're on Pacific Time (PT). Often answered already: [Setup guides](/docs/start-here), [How useapi.net works](/docs/how-it-works), [Q&A](/docs/questions-and-answers), [code examples on GitHub](https://github.com/useapi/examples). === Cross-reference: General Q&A === For cross-cutting tips (rate limiting, prompt moderation, common patterns) see https://useapi.net/assets/aibot/qa.txt WARNING: Q&A items are general-purpose and may reference deprecated APIs, sunsetted services, or scenarios not applicable to the API documented above. Cross-check against this service's endpoint documentation before applying any Q&A guidance.